docs: notifications + state-isolation design + Strict Installation Decoupling sync#255
Open
celstnblacc wants to merge 2 commits into
Open
docs: notifications + state-isolation design + Strict Installation Decoupling sync#255celstnblacc wants to merge 2 commits into
celstnblacc wants to merge 2 commits into
Conversation
Append the same paragraph to AGENTS.md, CLAUDE.md, GEMINI.md: Once installed (e.g., to ~/.local/bin), the project binary must NEVER depend on the local repository path (~/DevOpsSec) for execution, configuration, or data. All paths must be relative to the installation root or use standard system config paths (~/.config). Standardizes the no-repo-coupling rule across all three agent instruction surfaces so every agent reads the same constraint. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CONCEPT-notifications-and-state-isolation.md captures a full design discussion for two coupled superharness features: 1. Lifecycle notifications — let users opt into Telegram, Slack, email, (deferred: Signal) messages on task.created, report_ready, review_requested, etc. Credentials in OS keychain only, never in the DB or env. Per-channel rate limit + coalescing. Payload-hash logging only (never raw content). 2. State isolation — move .superharness/state.db out of the project repo to ~/.local/state/superharness/projects/<hash>/state.db so it can never be committed by accident. .superharness/ becomes a thin config-only directory with an allowlist .gitignore. Doc covers: schema (notify.db, channels, subscriptions, log), CLI surface, credential controls, state-isolation rationale, resolved gotchas (worktree per-path hashing, backup tiers 0-5 covering iCloud / Google Drive / Dropbox / OneDrive / Box / pCloud / MEGA / Syncthing / restic / borg / rclone on macOS+Linux+Windows, debug surface via shux state subcommand), prerequisites inventory (deps, modules, migrations, tests, hooks, docs), onboarding integration via shux onboard / shux explain, definition of done. Not yet implemented — this is the spec input for a future /plan-iter run. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two docs commits, one PR:
chore(docs): Strict Installation Decoupling — append the same paragraph to AGENTS.md, CLAUDE.md, GEMINI.md so every agent reads the same constraint: once installed, the project binary must never depend on the local repo path.
docs(spec): CONCEPT-notifications-and-state-isolation.md — full design discussion captured for two coupled future features (lifecycle notifications + state.db isolation outside the repo). 11 sections including prerequisites inventory, 6-tier backup matrix across macOS/Linux/Windows, and onboarding integration via shux onboard. Not yet implemented — this is the spec input for a future /plan-iter run.
Test plan
Why one PR
Both commits are docs-only, both predate any implementation work, both belong on main before the implementation branches start. Splitting would create two CI cycles for zero review-clarity gain — the diff is small and the two changes are clearly separable.
Release impact
docs: / chore(docs): per conventional commits — no version bump. No PyPI publish. Safe to merge.
Generated with Claude Code