diff --git a/.claude/skills/alignment/SKILL.md b/.claude/skills/alignment/SKILL.md index 30241db..5762984 100644 --- a/.claude/skills/alignment/SKILL.md +++ b/.claude/skills/alignment/SKILL.md @@ -9,6 +9,13 @@ disable-model-invocation: true Review staged or uncommitted code to ensure quality, test coverage, and alignment with the project's spec (`docs/spec/`) and architecture playbook (`docs/architecture/`). +This skill is also executed by a **clean-context subagent** at session wrap-up (see +CLAUDE.md → Session wrap-up protocol). When running as that subagent: you deliberately +have no session context — judge the diff against the written contracts only, and return +the summary (rule #15) as your final message so the session agent can relay it. If a +change looks deliberate but its rationale is recorded nowhere, that absence is itself a +finding. + ## Scope Determine the review scope using `git diff` (unstaged) and `git diff --staged` (staged). diff --git a/.claude/skills/eng-council/SKILL.md b/.claude/skills/eng-council/SKILL.md index 67d96ad..aa265b1 100644 --- a/.claude/skills/eng-council/SKILL.md +++ b/.claude/skills/eng-council/SKILL.md @@ -55,6 +55,13 @@ unavailable, the seat still sits — grep is the fallback evidence. Pick the mode from what's in front of you; say which mode is running. +The two review modes are also executed by a **clean-context subagent** at session +wrap-up, after `/doc-update` and the alignment pass (see CLAUDE.md → Session wrap-up +protocol). When running as that subagent: you deliberately have no session context — +judge the diff against the codebase's own population of shapes, and return the report as +your final message so the session agent can relay and arbitrate it. A deliberate-looking +divergence whose rationale is recorded nowhere is itself a finding. + ### Sweep — whole codebase For: milestone boundaries, the one-off backfill, "how healthy are we?" on demand. diff --git a/AGENTS.md b/AGENTS.md index 0db66bd..334992a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,6 +105,10 @@ npm run format # Prettier - **Spec is the contract** — when in doubt, read `docs/spec/`. If the spec is wrong or silent, raise it; change the spec deliberately rather than drifting from it. - **Core-first** — for each feature, build the pure `src/core/` logic with tests before UI. +- **Session wrap-up** — when the user signals the session is wrapping, run the review + pass before any commit: `/doc-update` in-session first (flush unrecorded rationale), + then `/alignment` — and `/eng-council` review when the diff is structural — each as a + **clean-context subagent** that reports back. Full protocol in CLAUDE.md. ### Project skills diff --git a/CLAUDE.md b/CLAUDE.md index 90a135a..a6ff6a7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,3 +43,33 @@ See @AGENTS.md for project overview, architecture rules, and the AI developer pr - No git actions unless explicitly invited. - Run `npm run typecheck` and `npm test` after changes. - Single-line commit subjects; no Co-Authored-By trailers. + +## Session wrap-up protocol + +When the user signals the session is wrapping (asks to commit, says it's done/wrapped), +run the review pass **before** anything is committed: + +1. **Flush knowledge first — `/doc-update`, in-session.** Capture what this session + decided or discovered: rationale for non-obvious choices (to `docs/` or a code + comment at the site, whichever is the right home), spec/architecture gaps, decisions + made in conversation that never landed in writing. This step cannot be delegated — + only the session knows what was decided — and it runs first so the clean-context + reviewers below judge against recorded rationale instead of flagging deliberate + choices as oversights. +2. **Alignment — clean-context subagent.** Spawn an agent with no session context + beyond this prompt: "Read `.claude/skills/alignment/SKILL.md` and execute it against + the current uncommitted/staged diff. Fix directly per the skill, run typecheck and + tests, and return the skill's summary as your final message." The clean slate is the + point — the reviewer simulates the future maintainer and must not inherit the + session's rationalizations. +3. **Eng-council review — clean-context subagent, conditional.** Only when the session's + diff is structural (a new module or kind-instance, a refactor, a new dependency): + spawn an agent the same way to execute `.claude/skills/eng-council/SKILL.md` in the + matching review mode (refactor review / new-functionality review — never the sweep; + sweeps stay a deliberate act). + +Run the subagents **sequentially**, not in parallel — both may edit the working tree. +Relay each report back to the user. Arbitrate findings that needed session context: +either accept them, or overrule them **and** record the missing rationale where the +reviewer looked for it — an overruled finding without a writing-down will recur. Then +commit only when invited.