docs(spec): add spec for repo-root CLAUDE.md (claude-context) - #3
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a plan-only specification under specs/claude-context/ for introducing a tracked repo-root CLAUDE.md in this dotfiles repository, capturing decisions/requirements/tasks/tests for the “claude-context” reframe from project memory to CLAUDE.md.
Changes:
- Introduces a new four-part spec set: design decisions, requirements, implementation tasks, and a manual test specification.
- Documents the scope gate, exclusions, and the (soft) dependency on the “#8” three-layer permissions model.
- Defines manual verification steps for CLAUDE.md auto-load behavior and implementation hygiene (diff + memory hygiene).
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 8 comments.
| File | Description |
|---|---|
| specs/claude-context/design.md | Design rationale, scope gate, exclusions, and dependency notes for repo-root CLAUDE.md. |
| specs/claude-context/requirements.md | “Shall” requirements for location/shape/content boundaries of the future CLAUDE.md. |
| specs/claude-context/tasks.md | Ordered implementation checklist for drafting/verifying/committing the future CLAUDE.md. |
| specs/claude-context/test-spec.md | Manual test/verification checklist for auto-load behavior and structural spot checks. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- skill-contracts.sh: the three-bucket check was decorative in 2 of 3 files it's supposed to guard. Reproduced directly: mutating panel-pairing.md/peer-review.md back to "four buckets" still passed, because an unrelated "three-pass"/"three tables" sentence elsewhere in the same file independently satisfied the shared alternation regex. Same failure mode the v1-retrospective already documented once for this exact checker. Rewritten to anchor on each file's own specific declarative sentence plus an explicit Agent-resolvable absence guard, using if-blocks instead of a set -e-unsafe `cond && ! grep && err` chain (which silently exited the script on the passing case during my own validation of the fix). - decouple-review-tooling.md: fixed a status line that claimed "resolved" while the body still narrated the deleted files in present tense, and a numbering reference that didn't map to the doc's actual numbered lists. - tasks.md: fixed a citation typo (D-9.1, which doesn't exist as a design decision, for REQ-D9.1) and an incomplete REQ-C1.x list (missing C1.1/C1.3) in the retirement bullet I added. - opportunities.md: fixed a misattributed quote (the "convergence layer" phrase is decouple-review-tooling.md's, not obs #3's) and an overstated claim that obs #3's "commands not skills" point is still open (it was already resolved in PR #33, before this branch). Declined with rationale: test-spec.md's and scheduled-runner.md's stale references to pair-flow-config.sh were left untouched, matching the verified precedent that the /orchestrate retirement also left these two files alone despite equivalent staleness at the time.
…, repo-class) (#35) * chore(tmux,claude): remove cross-session inbox substrate + tmux dashboard The tmux status-bar segment and prefix+i popup didn't pan out, so the whole substrate comes out rather than leaving the write-side hooks running with no reader: the six inbox-*.sh scripts, the tmux-side status wrapper, settings.json hook wiring, the inbox Ansible task, and pair-flow.yml's heartbeat-interval config. notify-event.sh (macOS notifications) is untouched since it's called independently. * chore(claude): retire notify-event.sh (Stop/permission/idle noise) Became noise, so it goes the same way as the inbox substrate: script deleted, hooks.Stop/hooks.Notification set to [] in settings.json. The tnotify-send/tnotify-watch fish infra stays; it's generic terminal- notification plumbing also used directly by worktree-bootstrap.sh. * chore(claude): retire repo-class / pair-flow-config.sh and the Agent-resolvable bucket repo-class (solo vs multi-reviewer) existed to gate whether Agent-resolvable findings could auto-apply without asking. Walking every consumer showed none of them actually varies safe behavior on it: /panel-pairing, /peer-review, and planwright's /polish all already draft a PR and never mark it ready without human sign-off regardless of repo-class, and /peer-review's "solo" branch was vacuous (it only runs when a peer already reviewed). Deletes pair-flow-config.sh, pair-flow.yml, and their Ansible task; collapses Finding Categorization from four buckets back to three (Auto-applicable / Needs sign-off / Needs human judgment) across CLAUDE.md, panel-review.md, panel-pairing.md, peer-review.md, code-review.md, and skill-contracts.sh. panel-backends now resolves from the profile-table default that already existed as a fallback, no config file needed. * fix(claude): self-review findings on the repo-class retirement branch - skill-contracts.sh: the three-bucket check was decorative in 2 of 3 files it's supposed to guard. Reproduced directly: mutating panel-pairing.md/peer-review.md back to "four buckets" still passed, because an unrelated "three-pass"/"three tables" sentence elsewhere in the same file independently satisfied the shared alternation regex. Same failure mode the v1-retrospective already documented once for this exact checker. Rewritten to anchor on each file's own specific declarative sentence plus an explicit Agent-resolvable absence guard, using if-blocks instead of a set -e-unsafe `cond && ! grep && err` chain (which silently exited the script on the passing case during my own validation of the fix). - decouple-review-tooling.md: fixed a status line that claimed "resolved" while the body still narrated the deleted files in present tense, and a numbering reference that didn't map to the doc's actual numbered lists. - tasks.md: fixed a citation typo (D-9.1, which doesn't exist as a design decision, for REQ-D9.1) and an incomplete REQ-C1.x list (missing C1.1/C1.3) in the retirement bullet I added. - opportunities.md: fixed a misattributed quote (the "convergence layer" phrase is decouple-review-tooling.md's, not obs #3's) and an overstated claim that obs #3's "commands not skills" point is still open (it was already resolved in PR #33, before this branch). Declined with rationale: test-spec.md's and scheduled-runner.md's stale references to pair-flow-config.sh were left untouched, matching the verified precedent that the /orchestrate retirement also left these two files alone despite equivalent staleness at the time. * chore(osx): clean up orphaned pair-flow.yml symlink and inbox dir Two hard-disqualifier-zone findings from the self-review pass (delete ops reaching other hosts), reviewed and approved in conversation rather than deferred to the PR checklist. Any host that ran the pre-retirement osx.yml has a dangling ~/.claude/pair-flow.yml symlink (target deleted) and an orphaned ~/.claude/inbox/ directory (inbox-sweep.sh, the only thing that ever cleaned it, is also deleted). Both are state: absent, safe no-ops on a fresh machine. Verified against fixtures: removes an existing dangling symlink + populated directory, and is idempotent when already absent. * fix(claude): panel-pairing findings, reviewed and approved /panel-pairing iteration 1 (backend: codex) surfaced 2 real findings that lacked a tool citation, so they routed to Needs sign-off rather than Auto-applicable per the skill's own rule; both approved in conversation rather than left on the checklist. - tasks.md / decouple-review-tooling.md overclaimed that pair-flow.local.yml "was removed" -- it wasn't. It's untracked and was never Ansible-managed (a pre-existing, deliberate policy); I only manually deleted it on this one machine earlier. Reworded to say it's orphaned wherever it existed, not deleted. - skill-contracts.sh's new bucket_files/bucket_phrases parallel arrays had no length-parity guard. Confirmed a mismatch already fails loudly under set -u (not silent), but with an unhelpful "unbound variable" instead of a clear diagnostic. Added an explicit check; validated against real files (still passes) and a simulated mismatch (now fails with a specific message). Two other codex findings were declined after validation: the settings.json Stop/Notification "[]" wipe concern doesn't apply (no other writer touches those hook categories, and "[]" to remove a hook is this repo's own documented convention); codex's "correction" to my set -e comment is itself incomplete (doesn't hold for the exact function-wrapped case the comment was describing, re-confirmed empirically). * chore(claude): address copilot-pairing thread on CLAUDE.md:171 Copilot flagged that /copilot-pairing was listed among skills that "categorize each finding into one of three buckets and present them as separate tables," but copilot-pairing.md never references the bucket taxonomy anywhere -- confirmed via direct grep, both on this branch and on origin/main (pre-existing since before this PR, but the sentence itself is already in this diff's touched lines, so in scope). It has its own classification scheme entirely (valid / already-handled / false positive / adjacent finding). Removed it from the list; kept /copilot-review's adjacent-findings output, which does genuinely use the three-bucket tables (confirmed in copilot-review.md). * chore(claude): fix v1-retrospective citation path in skill-contracts.sh Copilot flagged that the comment I added cites research/v1-retrospective.md:89, which doesn't resolve from repo root (lefthook's cwd). Every other reference to this file in the repo uses the full path specs/pair-flow/research/v1-retrospective.md; mine was the only outlier. Fixed to match. * chore(specs): fix stale tasks.md header (Last reviewed date, private wording) Copilot flagged this via /copilot-pairing on PR #35, twice in a row (loop detection fired on the second occurrence since I'd already replied "tracking elsewhere" to the first). Pulling it into scope per explicit direction rather than continuing to loop against an already correct dismissal. Bumped Last reviewed to today; planwright went public 2026-06-23 per the already-open opportunities.md entry this also closes out. Left tasks.md:55's Deferred-section "private" mention alone -- not flagged by Copilot, describes a historical fact, out of scope for this pass.
Summary
specs/claude-context/spec (design, requirements, tasks, test-spec) for introducing a trackedCLAUDE.mdat the dotfiles repo root.CLAUDE.mdwritten yet. Captures the reframe from "project memory" to repo-root CLAUDE.md, the three-part scope gate, and the soft dependency on improvement-plan fix(tnotify): write to client TTY and survive PTY destruction #8.Test plan