Process: session wrap-up protocol — doc-update, then clean-context review subagents

.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).

.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.

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
 

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.