Skip to content

docs(spec): add spec for repo-root CLAUDE.md (claude-context) - #3

Merged
inkatze merged 10 commits into
mainfrom
feat/spec-dotfiles-claude-md
Apr 7, 2026
Merged

docs(spec): add spec for repo-root CLAUDE.md (claude-context)#3
inkatze merged 10 commits into
mainfrom
feat/spec-dotfiles-claude-md

Conversation

@inkatze

@inkatze inkatze commented Apr 7, 2026

Copy link
Copy Markdown
Owner

Summary

  • New specs/claude-context/ spec (design, requirements, tasks, test-spec) for introducing a tracked CLAUDE.md at the dotfiles repo root.
  • Plan-only (Wave C); no CLAUDE.md written 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

  • Spec is internally consistent across the four files
  • No external/uncommitted file paths referenced

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread specs/claude-context/test-spec.md Outdated
Comment thread specs/claude-context/test-spec.md Outdated
Comment thread specs/claude-context/tasks.md Outdated
Comment thread specs/claude-context/requirements.md Outdated
Comment thread specs/claude-context/requirements.md Outdated
Comment thread specs/claude-context/design.md
Comment thread specs/claude-context/design.md Outdated
Comment thread specs/claude-context/design.md

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread specs/claude-context/test-spec.md
Comment thread specs/claude-context/requirements.md
Comment thread roles/osx/tasks/osx.yml

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread specs/claude-context/design.md Outdated
Comment thread specs/claude-context/requirements.md Outdated
Comment thread specs/claude-context/tasks.md Outdated
Comment thread specs/claude-context/requirements.md Outdated

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread specs/claude-context/design.md Outdated

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread specs/claude-context/requirements.md Outdated
Comment thread specs/claude-context/requirements.md Outdated
Comment thread specs/claude-context/tasks.md Outdated
Comment thread specs/claude-context/tasks.md Outdated

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread specs/claude-context/tasks.md Outdated
Comment thread specs/claude-context/tasks.md Outdated

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread specs/claude-context/design.md Outdated

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@inkatze
inkatze marked this pull request as ready for review April 7, 2026 23:51
@inkatze
inkatze merged commit 4864aca into main Apr 7, 2026
5 checks passed
@inkatze
inkatze deleted the feat/spec-dotfiles-claude-md branch April 7, 2026 23:51
inkatze added a commit that referenced this pull request Jul 13, 2026
- 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.
inkatze added a commit that referenced this pull request Jul 14, 2026
…, 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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants