pi-gauntlet 4.0.1 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## v4.2.0 - 2026-07-04
+
+Documents become first-class origin requirements, the post-execution review stack
+is deduplicated, and this repo now dogfoods its own workflow (GitHub #1 + folded-in B/C/D/E).
+
+- **Part A - docs as first-class origin.** New shared reference
+  `skills/brainstorming/reference/documentation-impact.md` defines a materiality
+  bar (seven inclusion categories + a litmus test, an anti-flooding exclusion list,
+  and amend-over-create) so only meaningful docs earn a place. `brainstorming` gets
+  a required `## Documentation impact` spec section (three classes: introduced /
+  materially amended / derived-memory invalidated); `writing-plans` turns doc updates
+  into real tasks + a trailing doc-only wave; `conformance-check.md` names spec docs
+  as origin requirements the existing pass already verifies. No new pass or agent.
+- **Part B - review-stack dedup.** `subagent-driven-development`'s post-execution
+  stack collapses from a duplicated whole-diff review to one `requesting-code-review`
+  plus the separate `conformance-reviewer`; the auto-fired project-audit supplement
+  is removed (consumers re-wire via `.pi/gauntlet-overrides.md` or run it manually).
+  `agents/code-reviewer.md` severity and `README.md` are decoupled from the example
+  self-audit skill. Execution-phase per-task/per-wave reviews are untouched.
+- **Part C - ephemeral-plan parity.** `finishing-a-development-branch` now strips the
+  plan doc before the PR push (guarded `git ls-files --error-unmatch`), symmetric with
+  the squash-merge path; the plan never lands on base.
+- **Part D - self-hosting mandate.** `AGENTS.md` mandates the full gauntlet for this
+  repo's own non-trivial changes and reframes the direct-edit recipes as implement-phase
+  mechanics.
+- **Part E - file-placement convention.** `writing-skills` codifies dispatch-payload
+  templates as `SKILL.md` siblings vs deep guidance in `reference/` (destination, not format).
+
+## v4.1.0 - 2026-07-02
+
+- **`closureReview` now resolves repo-local first.** The verify-step skills
+  (`subagent-driven-development`, `verification-before-completion/reference/conformance-check.md`)
+  resolve `piGauntlet.closureReview.model`/`maxFixRounds` from a repo's
+  `.pi/settings.json` over the agent preset, **whole-object** - matching how the
+  `phase-tracker.ts` guard already reads `pi.settings` (pi replaces the whole
+  `closureReview` block when a repo defines it). Previously they read the preset
+  only, so a repo-local `closureReview.model` was silently ignored and the
+  conformance gate ran on the parent's model.
+- **New shared reference `skills/verification-before-completion/reference/settings-precedence.md`.**
+  States the two-file source order and the whole-object merge rule once; `specCouncil`
+  and `closureReview` both resolve the same way and both point at it. `roasting-the-spec`
+  and `brainstorming` replace their duplicated lookup prose with a pointer.
+- **Closure guard upgraded from presence-check to match-check.** A
+  `conformance-reviewer` dispatch that omits `model:` is still blocked; one whose
+  `model:` differs from the configured `closureReview.model` now gets a non-blocking
+  warning appended to the result. Gated by `closureReview.enforce` as before.
+
 ## v4.0.1 - 2026-07-02
 
 No content change. Smoke-tests the tag-triggered CI publish path (OIDC trusted publishing to npm) added in v4.0.0's release machinery commit.

package/README.md

@@ -15,10 +15,10 @@ brainstorm → plan → implement → verify → ship
 1. **`brainstorming`** — every change starts here. Sets up an isolated worktree, explores the codebase, and turns the idea into a written spec under `doc/specs/`. A multi-model critique runs automatically before you read it (`roasting-the-spec` when a council is configured, else one fresh `worker`). **Hard gate:** no implementation code is written until you approve the spec.
 2. **`writing-plans`** — derives an implementation plan from the approved spec, decomposed into atomic, independently-verifiable tasks (grouped into parallel waves when they're file- and resource-disjoint). Auto-chains into execution.
 3. **`subagent-driven-development`** — executes the plan one atomic task at a time, each in a **fresh subagent**, behind a **two-stage review**: spec compliance first (`spec-reviewer`), then code quality (`code-reviewer`). The `implementer` persona is TDD-locked (RED→GREEN→REFACTOR). You orchestrate; you never hand-write the code.
-4. **verify** — after the last task: a whole-diff review (`requesting-code-review`, plus any project-specific `self-audit` supplement), then the `conformance-reviewer` closing-loop gate that confronts the delivered code **and** docs against the *origin* (spec + your verbatim original prompt), not the plan. The phase-tracker **blocks `complete verify`** until a conformance dispatch has run, and on a successful `complete verify` (ship still pending) injects an advisory to invoke `finishing-a-development-branch` immediately without a redundant "ready to finish?" prompt - or to reopen verify if a requirement decision is still open.
+4. **verify** — after the last task: a whole-diff review (`requesting-code-review`), then the `conformance-reviewer` closing-loop gate that confronts the delivered code **and** docs against the *origin* (spec + your verbatim original prompt), not the plan. The phase-tracker **blocks `complete verify`** until a conformance dispatch has run, and on a successful `complete verify` (ship still pending) injects an advisory to invoke `finishing-a-development-branch` immediately without a redundant "ready to finish?" prompt - or to reopen verify if a requirement decision is still open.
 5. **`finishing-a-development-branch`** — squash / PR / keep / discard. This menu is the single human decision gate at the end, mirroring spec approval at the start.
 
-Spec, plan, and implementation all live in the **same worktree** and ship as **one squash commit**.
+Spec, plan, and implementation are all developed in the **same worktree**. The squash commit ships spec and implementation; the plan is ephemeral and is stripped before any landing path.
 
 **Supporting skills** slot in as the pipeline needs them: `using-git-worktrees` (isolation, before the spec), `test-driven-development` (inside every implementer), `dispatching-parallel-agents` (wave fan-out), `systematic-debugging` (when something breaks), `receiving-code-review` (when you get feedback), `writing-skills` (authoring more of these).
 
@@ -162,7 +162,7 @@ Unset → provider default thinking for that model. `conformance-reviewer` and t
 
 ### Conformance gate model
 
-`conformance-reviewer` ships without a `model:` in its frontmatter — like the spec-council personas, its model is supplied per preset so each profile points the last correctness gate at the strongest reasoning model its providers can reach. The verify-step skills read it from `piGauntlet.closureReview.model` and inject it **call-site** on the conformance dispatch (the same mechanism the spec-council chair uses). Add it to each preset's `settings.json`:
+`conformance-reviewer` ships without a `model:` in its frontmatter — like the spec-council personas, its model is supplied per preset so each profile points the last correctness gate at the strongest reasoning model its providers can reach. The verify-step skills resolve `piGauntlet.closureReview.model` **repo-local first** (a repo's `.pi/settings.json` overrides the preset whole-object - defining `closureReview` there replaces the preset's entire block, so set every leaf you need together) and inject it **call-site** on the conformance dispatch (the same mechanism the spec-council chair uses). Add it to each preset's `settings.json` (or a repo's `.pi/settings.json` to override per repo):
 
 ```json
 {
@@ -174,7 +174,7 @@ Unset → provider default thinking for that model. `conformance-reviewer` and t
 
 Frontmatter pins `thinking: xhigh` and `defaultContext: fresh` (the gate always runs cold, with max reasoning) and `thinking` is not call-site overridable, so the config supplies only `model`. If `closureReview.model` is unset the dispatch omits `model:` and the gate inherits the parent's model; if the configured model is unreachable it retries once inherited.
 
-When `closureReview.model` **is** set, the phase-tracker enforces call-site injection: a `subagent` dispatch of `conformance-reviewer` that omits `model:` is **blocked at tool-call time** (before it runs) so the gate can never silently degrade to the parent's builder model. The documented one-retry fallback still works - pass the inherited model *explicitly* and it is allowed; only a bare omission is blocked. Disabling `closureReview.enforce` disables this guard too.
+When `closureReview.model` **is** set, the phase-tracker match-checks call-site injection: a `subagent` dispatch of `conformance-reviewer` that omits `model:` is **blocked at tool-call time** (before it runs) so the gate can never silently degrade to the parent's builder model, and a dispatch whose `model:` **differs** from the configured value gets a non-blocking **warning** appended to the result (drift is surfaced, not blocked). The documented one-retry fallback still works - pass an explicit model and it runs (with a warning if it differs). Disabling `closureReview.enforce` disables this guard too.
 
 `closureReview.enforce` (default `true`) controls the phase-tracker gate that
 blocks `complete verify` until the conformance-reviewer has run; set `false` to
@@ -202,7 +202,7 @@ If you want to know what's in each persona before using it, see [`agents/`](./ag
 - `members` (required) — roster of `provider/model` strings; council size = array length, one critique per model. Empty or absent → the council never runs; brainstorming falls back to a single fresh-`worker` critique (scope + ambiguity, auto-applied).
 - `chair` (optional) — model for the consolidating synthesizer; defaults to the inherited model when omitted.
 
-Rosters are per-preset: each pi profile (`agent`, `agent.anthropic`, `agent.bedrock`, …) reads its own `settings.json`, so list only models that profile's providers can reach. The two personas it dispatches — `spec-council-member` and `spec-council-synthesizer` — are model-free; their model is injected per task from this config.
+Rosters resolve **repo-local first**: a repo's `.pi/settings.json` overrides the preset (whole-object — the first file that defines `specCouncil` wins), otherwise each pi profile (`agent`, `agent.anthropic`, `agent.bedrock`, …) reads its own `settings.json`. List only models the resolving config's providers can reach. The two personas it dispatches — `spec-council-member` and `spec-council-synthesizer` — are model-free; their model is injected per task from this config.
 
 ## Extensions
 

package/agents/code-reviewer.md

@@ -40,7 +40,8 @@ Findings:
 Complexity: net -<N> lines   (omit if nothing to cut)
 ```
 
-Severity (aligned with the `self-audit` skill):
+Severity:
+
 - **Critical** — must fix before merge (data loss, security, broken correctness on a common path, broken contract).
 - **Moderate** — should fix; open for discussion (significant but not strictly blocking).
 - **Minor** — nit, style, preference, suggestion.

package/extensions/phase-tracker.ts

@@ -98,19 +98,21 @@ const branchBlockReason = (phase: Phase): string =>
   "To override, set piGauntlet.flowGuards.enforce: false.";
 
 // Closure-review model guard: when piGauntlet.closureReview.model is configured,
-// a conformance-reviewer dispatch MUST inject that model call-site. The persona ships
-// model-free, so a bare omission silently inherits the parent session's builder model -
-// defeating the point of an independent closing gate on a different model. Walk the
-// single / tasks / chain / parallel dispatch shapes and report any conformance-reviewer
-// entry that carries no model. An explicit model (even a fallback) is fine; only a bare
-// omission is caught - that preserves the documented "retry once inherited" escape hatch,
-// which the orchestrator takes by passing the inherited model explicitly.
-const conformanceEntriesMissingModel = (input: unknown): boolean => {
-  const entries: { agent?: unknown; model?: unknown }[] = [];
+// a conformance-reviewer dispatch should inject that model call-site. The persona
+// ships model-free, so a bare omission silently inherits the parent session's
+// builder model - defeating the point of an independent closing gate. Walk the
+// single / tasks / chain / parallel dispatch shapes and collect the model of every
+// conformance-reviewer entry (undefined = absent/empty/non-string). A bare omission
+// is BLOCKED; an explicit model that differs from the configured one is WARNED
+// (non-blocking), preserving the documented retry-with-fallback hatch while
+// surfacing drift.
+const conformanceModels = (input: unknown): (string | undefined)[] => {
+  const models: (string | undefined)[] = [];
+  const norm = (m: unknown) => (typeof m === "string" && m.trim() ? m.trim() : undefined);
   const collect = (node: unknown): void => {
     if (!node || typeof node !== "object") return;
     const o = node as Record<string, unknown>;
-    if (typeof o.agent === "string") entries.push({ agent: o.agent, model: o.model });
+    if (o.agent === "conformance-reviewer") models.push(norm(o.model));
     for (const key of ["tasks", "chain", "parallel"] as const) {
       const v = o[key];
       if (Array.isArray(v)) for (const item of v) collect(item);
@@ -118,19 +120,28 @@ const conformanceEntriesMissingModel = (input: unknown): boolean => {
     }
   };
   collect(input);
-  return entries.some((e) => e.agent === "conformance-reviewer" && !e.model);
+  return models;
 };
 
-const closureModelBlockReason = (model: string): string =>
-  `Blocked: conformance-reviewer dispatched without a model while ` +
-  `piGauntlet.closureReview.model is set to "${model}".\n` +
+const closureModelBlockReason = (model: string, missing: number, total: number): string =>
+  `Blocked: ${missing} of ${total} conformance-reviewer ${total === 1 ? "dispatch" : "entries"} ` +
+  `omitted a model while piGauntlet.closureReview.model is set to "${model}".\n` +
   `The persona ships model-free, so a bare omission silently inherits this session's ` +
   `builder model - the closing gate would then run on the same model that built the work, ` +
-  `not the independent one the preset pins. Re-dispatch with model: "${model}" injected ` +
-  `call-site. If that model is unreachable, pass an explicit fallback model (the documented ` +
-  `one-retry escape hatch) - only a bare omission is blocked.\n` +
+  `not the independent one configured (repo .pi/settings.json, else the preset). Re-dispatch ` +
+  `with model: "${model}" injected call-site on every conformance-reviewer entry. If that ` +
+  `model is unreachable, pass an explicit fallback model (the documented one-retry escape ` +
+  `hatch) - only a bare omission is blocked.\n` +
   `To disable this gate, set piGauntlet.closureReview.enforce: false.`;
 
+const closureModelMismatchWarning = (configured: string, mismatched: string[]): string =>
+  `⚠️ conformance-reviewer dispatched with ${mismatched.length === 1 ? "model" : "models"} ` +
+  `${mismatched.map((m) => `"${m}"`).join(", ")} while ` +
+  `piGauntlet.closureReview.model is set to "${configured}".\n` +
+  `If this is the documented one-retry fallback (the configured model was ` +
+  `unreachable), ignore this. Otherwise the closing gate is running on an ` +
+  `unintended model - re-dispatch with model: "${configured}".`;
+
 const brainstormWriteWarning = (specDirs: string[]): string =>
   "⚠️ Writing outside the spec directory during the brainstorm phase.\n" +
   `Brainstorming may only edit the spec under ${specDirs.join(", ")}. Implementation\n` +
@@ -317,8 +328,19 @@ export default function (pi: ExtensionAPI) {
       // Only execution-mode dispatches carry a model; management/control modes
       // (action: list/get/create/update/delete/status/...) execute nothing, so skip them.
       const hasAction = !!(event.input as { action?: unknown })?.action;
-      if (model && !hasAction && conformanceEntriesMissingModel(event.input)) {
-        return { block: true, reason: closureModelBlockReason(model) };
+      if (model && !hasAction) {
+        const configured = model.trim();
+        const models = conformanceModels(event.input);
+        if (models.length > 0) {
+          const missing = models.filter((m) => m === undefined).length;
+          if (missing > 0) {
+            return { block: true, reason: closureModelBlockReason(configured, missing, models.length) };
+          }
+          const mismatched = [...new Set((models as string[]).filter((m) => m !== configured))];
+          if (mismatched.length > 0) {
+            pendingGuardWarnings.set(event.toolCallId, closureModelMismatchWarning(configured, mismatched));
+          }
+        }
       }
     }
 
@@ -377,6 +399,11 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_result", async (event) => {
     if (event.toolName === "subagent") {
       if (qualifiesAsClosureDispatch(event.details)) conformanceDispatched = true;
+      const warning = pendingGuardWarnings.get(event.toolCallId);
+      if (warning) {
+        pendingGuardWarnings.delete(event.toolCallId);
+        return { content: [{ type: "text" as const, text: warning }, ...event.content] };
+      }
       return undefined;
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.0.1",
+  "version": "4.2.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "type": "module",
   "license": "MIT",

package/skills/brainstorming/SKILL.md

@@ -78,7 +78,7 @@ The spec is the **first commit in a dedicated worktree**, not a separate commit
 2. Switch into the worktree.
 3. From there, write the spec, run self-review, commit, hand off.
 
-Spec doc, plan doc, and implementation all live in the same worktree and ship together as a single squash commit (see `/skill:finishing-a-development-branch`).
+Spec doc, plan doc, and implementation are all developed in the same worktree; the squash ships the spec and the implementation, with the ephemeral plan stripped before landing (see `/skill:finishing-a-development-branch`).
 
 **Exception:** trivial one-off edits the user explicitly asks for outside this skill flow (e.g. "fix this typo") do not require a worktree.
 
@@ -140,7 +140,16 @@ Cover at minimum:
 - Data flow (or request flow)
 - Error handling and edge cases
 - Testing approach
-- Documentation impact — name each doc that changes (README, AGENTS.md, CHANGELOG, API contracts, inline docs), or write "none". Doc updates ship in the same commit and are verified against the spec by the conformance gate.
+- Documentation impact — a required `## Documentation impact` section. Cite the materiality bar in `reference/documentation-impact.md` by relative path rather than restating its categories, and reproduce its template block verbatim:
+
+  ```markdown
+  ## Documentation impact
+  - Feature / user-facing docs introduced: <list, or "none">
+  - Materially amended existing docs: <list, or "none">
+  - Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
+  ```
+
+  Each entry answers with a doc name, "none", or "deferred: <trigger>". A new standalone `.md` appears only where no existing doc already owns the topic. Project-specific doc taxonomy goes in a `## documentation` block in `.pi/gauntlet-overrides.md` (no new settings key; guidance only). Doc updates ship in the same commit and are verified against the spec by the conformance gate.
 
 Be ready to go back and clarify when something doesn't make sense.
 
@@ -188,7 +197,7 @@ After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Con
 
 - **Placeholder scan.** Any `TODO`, `TBD`, `<fill in>`, `[example]`, `xxx`? Either resolve them or convert to explicit "Open Questions" with names.
 - **Internal consistency.** Does Section 4 contradict Section 2? Are component names and field names consistent throughout?
-- **Documentation named.** Does the spec state which docs change (or an explicit "none")?
+- **Documentation named.** Does the spec name all three classes (feature/user-facing introduced; materially amended; derived/memory invalidated), or an explicit "none" for each? Enforce the materiality bar in `reference/documentation-impact.md` without restating it: each listed doc names the category it clears, none is a code-mirror, amend-over-create was applied, and skill/agent bodies are implementation surface, not doc-impact entries here.
 - **Scope check.** Does every paragraph serve the goal? Cut filler. If something is out of scope, say it's out of scope.
 - **Ambiguity check.** Is every "we should…" backed by a concrete decision? Replace "we could probably" with "we will" or "we won't".
 
@@ -215,14 +224,7 @@ After the critique pass returns, scan it for load-bearing external references be
 
 ## Spec Council (Optional)
 
-After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**: resolve `piGauntlet.specCouncil` from **two** settings files, repo-local first, and select the path.
-
-Lookup order (first file that **defines** `specCouncil` wins — do not merge across files):
-
-1. `<repo-root>/.pi/settings.json` — repo root from `git rev-parse --show-toplevel` (the worktree root inside a worktree). A repo that defines `specCouncil` overrides the preset, even with empty `members` (explicit "no council here").
-2. `$PI_CODING_AGENT_DIR/settings.json` — agent preset; consulted only when the repo file does not define `specCouncil`.
-
-Both files may contain comments — read them, don't strict-parse. **Expand `$PI_CODING_AGENT_DIR`; never substitute a hardcoded project path for it** (reading the repo `.pi/settings.json` as if it were the preset file is the classic miss — repo-local and preset are different files). **When `members` is non-empty, the council *is* the critique pass — invoke `/skill:roasting-the-spec` automatically (no offer, no prompt).** When it is absent or empty, run the fresh-`worker` critique instead (see [Spec Self-Review](#spec-self-review-before-user-review-gate)); if `specCouncil` is present but malformed, emit one warning line and fall back to the worker. Approved council edits (or the worker's in-place fixes) are applied to the spec and ride in the same worktree commit as the rest of this skill's output.
+After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**: resolve `piGauntlet.specCouncil` **repo-local first** — the repo's `.pi/settings.json` overrides the agent preset, **whole-object** (the first file that defines `specCouncil` wins; an empty `members` there is an explicit "no council here"). Full source order and mechanics: `verification-before-completion/reference/settings-precedence.md`. **Expand `$PI_CODING_AGENT_DIR`; never substitute a hardcoded project path for it.** **When `members` is non-empty, the council *is* the critique pass — invoke `/skill:roasting-the-spec` automatically (no offer, no prompt).** When it is absent or empty, run the fresh-`worker` critique instead (see [Spec Self-Review](#spec-self-review-before-user-review-gate)); if `specCouncil` is present but malformed, emit one warning line and fall back to the worker. Approved council edits (or the worker's in-place fixes) are applied to the spec and ride in the same worktree commit as the rest of this skill's output.
 
 ## User Review Gate
 

package/skills/brainstorming/reference/documentation-impact.md

@@ -0,0 +1,134 @@
+# Documentation Impact: the Materiality Bar
+
+The shared materiality bar for a spec's "Documentation impact" section. Several
+skills cite this doc by relative path rather than restating its rules.
+
+## Governing principle
+
+The governing principle: document what the code cannot tell you.
+
+The "Documentation impact" section is a **filter with a default of "none,"** not
+a prompt to produce documentation. A doc earns a line in that section only when
+it clears one of the categories below. Absence is the expected outcome for most
+changes - most changes touch no product-facing doc at all.
+
+## Scope + the three doc classes
+
+The section tracks **product-facing docs**: README, `AGENTS.md`, CHANGELOG,
+external / API contracts, and genuinely-new standalone guidance docs.
+
+Skill and agent bodies, and their `reference/` sub-docs, are **implementation
+surface** - the deliverable itself, tracked in the plan's file list - **not**
+doc-impact entries. Listing them here would just restate the diff.
+
+Within that scope, a spec's Documentation impact section enumerates three
+classes:
+
+- **Feature / user-facing docs introduced** - a new doc the change adds.
+- **Materially amended existing docs** - an existing product doc that gains a
+  new section or a changed contract.
+- **Derived / memory docs invalidated** - router entries (`AGENTS.md` sections),
+  topic guides, taxonomy indexes that go stale because of this change.
+
+## The seven inclusion categories
+
+These seven categories gate classes 1 and 2 (feature/user-facing introduced;
+materially amended) - selection by importance. Class 3 (derived/memory
+invalidated) uses a different, lighter test; see "Gating class 3" below.
+
+A doc earns its place in classes 1-2 only by clearing at least one of these.
+Categories are not mutually exclusive; one match is sufficient.
+
+**Litmus test for every category:** would a competent teammate need this
+written down to safely operate or extend the system without reading the diff
+or the code? If the code (or its tests) already answers it, it fails the bar.
+
+- **Major procedures / conventions** - how work is done here (workflow, review,
+  release discipline).
+- **Operations / tunable parameters** - env vars, thresholds, feature flags,
+  runbook / recovery steps. PASS: a new `PI_LENS_MAX_FILES` threshold, its
+  default, and when to change it. FAIL: restating that a function reads an
+  env var - the code already says that.
+- **Communication contracts / integrations** - API / wire / queue contracts,
+  cross-component boundaries.
+- **Architecture** - module boundaries, data flow, structural decisions.
+- **Major definitions** - the canonical definition of a load-bearing domain
+  term, concept, or invariant that multiple components depend on and no single
+  code location fully owns. PASS: the canonical meaning of a domain term
+  several components rely on. FAIL: a one-line type alias the code already
+  names in full.
+- **Non-obvious rationale / decisions that outlive the PR** - the "why," and
+  why not the obvious alternative. PASS: why a simpler, obvious approach was
+  rejected, recorded so it is not re-litigated later. FAIL: a restatement of
+  what the chosen code does.
+- **Security, data-access & permissions** - trust boundaries, who can access
+  what, data-handling and permission decisions.
+
+## Gating class 3
+
+Class 3 ("Derived / memory docs invalidated") is not gated by the seven
+categories above. A router entry, topic guide, or taxonomy index is
+invalidated by drift, not selected by topical weight. The test is: an
+existing doc's content is now wrong or misleading because of this change.
+If so, it belongs in class 3 regardless of whether it would clear any of the
+seven categories. A citing skill (for example `writing-plans`, which sources
+doc-update tasks from this section) must not apply the seven-category filter
+to class 3 entries.
+
+## Exclusion / anti-pattern list
+
+None of the following clears the bar, no matter how it is framed:
+
+- Per-symbol or per-module narration.
+- Restating signatures, types, or schemas the code already owns.
+- "How it works" prose that reading the code answers directly.
+- Anything that would need an edit on every code change - the code-mirror
+  tell: if a doc rots the moment the function it describes changes, it was
+  never documentation, it was a copy.
+
+In-code doc comments such as RDoc/JSDoc are out of scope for this bar; it
+governs standalone `.md` docs only, and the same "no code-mirror" rule
+applies to both: a narrow markdown file that mirrors one function or one
+module fails the bar the same way an inline doc comment would.
+
+## Amend over create
+
+Clearing the bar does not default to a new file. **Extend the canonical
+existing doc that owns the topic.** When ownership is ambiguous, extend the
+most specific existing doc that already discusses the surrounding topic; a
+new standalone `.md` is justified only when zero existing docs mention the
+topic at all - this is the anti-proliferation rule, and it is why most
+changes that clear the bar still show up under "materially amended," not
+"introduced."
+
+## The section template
+
+Reproduce this block exactly in a spec's "Documentation impact" section:
+
+```markdown
+## Documentation impact
+- Feature / user-facing docs introduced: <list, or "none">
+- Materially amended existing docs: <list, or "none">
+- Derived / memory docs invalidated: <routers / AGENTS.md sections / topic guides / indexes, or "none">
+```
+
+Each entry answers with a doc name, `"none"`, or `"deferred: <trigger>"` (for
+example, `CHANGELOG.md - deferred: release`, when a doc changes on a known
+later event and should not be flagged as missing before that event fires).
+
+## Referenced by
+
+Keep this list in sync with the skills that cite this doc:
+
+- `brainstorming` section 6 and its Spec Self-Review check.
+- `writing-plans` - sources doc-update tasks from the spec's Documentation
+  impact section.
+- `verification-before-completion/reference/conformance-check.md` - docs named
+  here are origin requirements the conformance pass verifies.
+- `finishing-a-development-branch` Step 1's doc-impact pointer.
+
+## Project-specific taxonomy
+
+This doc is generic. Project-specific doc taxonomy (which docs a given
+project treats as canonical for which topic) lives in a project's
+`.pi/gauntlet-overrides.md`, in a `## documentation` section - not here.

package/skills/finishing-a-development-branch/SKILL.md

@@ -42,7 +42,7 @@ Stop. Don't proceed to Step 2.
 
 **If tests pass:** Continue to Step 2.
 
-No documentation prompt here: doc impact is decided at spec time (`/skill:brainstorming` section 6) and has already shipped in the diff by the time you reach finishing.
+No documentation prompt here: Documentation impact is decided at spec time (`/skill:brainstorming` section 6, gated by `brainstorming/reference/documentation-impact.md`) and has already shipped in the diff by the time you reach finishing.
 
 ### Step 2: Detect Environment
 
@@ -154,6 +154,12 @@ git branch -d <feature-branch>
 #### Option 2: Push and Create PR
 
 ```bash
+# Plans are ephemeral - if one was committed on this branch, remove it before the PR diff is opened.
+PLAN_PATH=doc/plans/<plan-file>.md   # or <service>/doc/plans/<plan-file>.md
+if git ls-files --error-unmatch "$PLAN_PATH" >/dev/null 2>&1; then
+  git rm "$PLAN_PATH" && git commit -m "Remove ephemeral plan doc"
+fi
+
 # Push branch
 git push -u origin <feature-branch>
 
@@ -235,12 +241,12 @@ git worktree prune  # Self-healing: clean up any stale registrations
 
 ## Quick Reference
 
-| Option | Merge | Push | Keep Worktree | Cleanup Branch |
-|--------|-------|------|---------------|----------------|
-| 1. Squash-merge locally | yes (squash) | - | - | yes |
-| 2. Create PR | - | yes | yes | - |
-| 3. Keep as-is | - | - | yes | - |
-| 4. Discard | - | - | - | yes (force) |
+| Option | Merge | Push | Keep Worktree | Cleanup Branch | Plan-doc removal |
+|---|---|---|---|---|---|
+| 1. Squash-merge locally | yes (squash) | - | - | yes | yes (unconditional) |
+| 2. Create PR | - | yes | yes | - | yes (guarded, before push) |
+| 3. Keep as-is | - | - | yes | - | - |
+| 4. Discard | - | - | - | yes (force) | - |
 
 ## Common Mistakes
 
@@ -272,7 +278,7 @@ git worktree prune  # Self-healing: clean up any stale registrations
 - **Problem:** Accidentally delete work
 - **Fix:** Require typed "discard" confirmation
 
-**Skipping the plan-doc deletion in Option 1**
+**Skipping the plan-doc deletion in Options 1 and 2 (any path that lands on base)**
 - **Problem:** Plan docs are ephemeral and shouldn't land on `<base-branch>`. Forgetting `git rm doc/plans/<plan-file>.md` ships scaffolding to main.
 - **Fix:** The plan stays in the deleted branch's git history (`git log --all -- doc/plans/...`). Spec stays on `<base-branch>`; plan does not.
 
@@ -295,6 +301,7 @@ phase_tracker({ action: "complete", phase: "ship" })
 - Clean up worktrees you didn't create (provenance check)
 - Run `git worktree remove` from inside the worktree
 - Present finish options while a conformance gap is open and undispositioned
+- Skip the guarded plan-doc removal before push on Option 2 when a plan doc was committed
 
 **Always:**
 - Verify tests before offering options

package/skills/roasting-the-spec/SKILL.md

@@ -24,12 +24,7 @@ This skill may read anything and edit **only** the spec under `doc/specs/`. It d
 
 ## Configuration and gating
 
-Resolve `piGauntlet.specCouncil` from **two** settings files, repo-local first:
-
-1. `<repo-root>/.pi/settings.json` (repo root = `git rev-parse --show-toplevel`, which inside a worktree is the worktree root). **If this file defines `specCouncil`, it wins** — even an empty `members` here is an explicit "no council for this repo".
-2. `$PI_CODING_AGENT_DIR/settings.json` (agent preset) — consulted **only** when the repo file does not define `specCouncil` at all.
-
-The first file that defines the key wins; do not merge member lists across files. Do not hardcode a project path in place of `$PI_CODING_AGENT_DIR` — expand the env var. The resolved config looks like:
+Resolve `piGauntlet.specCouncil` **repo-local first** — the repo's `.pi/settings.json` overrides the agent preset, **whole-object** (the first file that defines `specCouncil` wins outright; an empty `members` there is an explicit "no council for this repo"). Full source order, mechanics, and the per-key granularity rule live in `verification-before-completion/reference/settings-precedence.md`. Do not hardcode a path in place of `$PI_CODING_AGENT_DIR` — expand the env var. The resolved config looks like:
 
 ```json
 {

package/skills/subagent-driven-development/SKILL.md

@@ -60,7 +60,7 @@ For each task in `plan_tracker`:
 6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅.
 7. Mark task complete in `plan_tracker`.
 
-After all tasks: dispatch a final reviewer over the full diff. Then [After All Tasks](#after-all-tasks-complete).
+After all tasks: run the whole-diff code review (`requesting-code-review`). Then [After All Tasks](#after-all-tasks-complete).
 
 ## Implementer Status
 
@@ -86,8 +86,7 @@ Pi-subagents accepts a per-task `model` override. Use it.
 | Hard / novel / large surface | Most capable | New subsystem, complex algorithm, cross-service contract change |
 | Spec review | Default | Reads diff + spec, mechanical comparison |
 | Code-quality review | Most capable | Judgment call on naming, design, complexity |
-| Final reviewer | Most capable | Whole-PR-scope review |
-| Conformance / closure | Most capable | Whole-deliverable-vs-origin intent gate (`conformance-reviewer`; model from `piGauntlet.closureReview.model`, injected call-site) |
+| Conformance / closure | Most capable | Whole-deliverable-vs-origin intent gate (`conformance-reviewer`; model from `piGauntlet.closureReview.model`, resolved repo-first whole-object, injected call-site) |
 
 ```ts
 subagent({
@@ -112,8 +111,8 @@ subagent({ agent: "spec-reviewer", task: "<diff range + spec excerpt + ask: does
 subagent({ agent: "code-reviewer", task: "<diff range + ask: production-ready?>" })
 
 // closing-loop conformance (origin vs deliverable) — its OWN dispatch, never fused with code quality
-// model from piGauntlet.closureReview.model (read $PI_CODING_AGENT_DIR/settings.json); omit to inherit
-subagent({ agent: "conformance-reviewer", model: /* piGauntlet.closureReview.model from config, else omit to inherit */, task: "<spec path + verbatim original prompt + full diff vs main; per conformance-check.md>" })
+// model from piGauntlet.closureReview.model — resolve repo-local .pi/settings.json over the preset, whole-object (see verification-before-completion/reference/settings-precedence.md); omit to inherit
+subagent({ agent: "conformance-reviewer", model: /* piGauntlet.closureReview.model, repo-first per settings-precedence.md, else omit to inherit */, task: "<spec path + verbatim original prompt + full diff vs main; per conformance-check.md>" })
 ```
 
 Prompt templates live alongside this SKILL.md:
@@ -188,11 +187,10 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 ## After All Tasks Complete
 
 0. Call `phase_tracker({ action: "start", phase: "verify" })`. (The `implement` phase was started at execution start and auto-completes from `plan_tracker` once all tasks are done; this flow runs its own verify gate instead of `/skill:verification-before-completion`, so it must mark verify itself.)
-1. Dispatch the final reviewer over the full diff (already covered in [The Process](#the-process) step "After all tasks").
-2. **Run an audit pass automatically.** Run `/skill:requesting-code-review` against the worktree's full diff vs `main`. Then, if the project ships a project-specific audit skill (e.g., `.agents/skills/self-audit/`), run it as an optional supplement (it adds project-specific checks and fixes, not a replacement). Address Critical and Moderate findings before handoff. Do not ask the user — just run it.
-3. **Close the loop — conformance check.** The audit in step 2 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 final review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. On `GAPS`, do not auto-fix or auto-proceed: run the remediation loop in `verification-before-completion/reference/conformance-check.md` "When the check finds gaps" (disposition menu → isolated fix waves → bounded delta re-audit, capped by `piGauntlet.closureReview.maxFixRounds`). Only when the verdict is `CONFORMS` (or every gap is dispositioned) call `phase_tracker({ action: "complete", phase: "verify" })`.
-4. Summarize what was implemented (tasks completed, files changed, test counts, self-audit verdict). Give the closing loop its **own section** — `Closure / conformance: CONFORMS` (or `GAPS` with each gap and its disposition) — so the user sees intent-fidelity as a first-class line before any finishing decision, not buried in the audit verdict.
-5. **Proceed to finishing — no confirmation prompt.** When the verdict is `CONFORMS` (or every gap is dispositioned), invoke `/skill:finishing-a-development-branch` immediately. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Open gaps are already owned by step 3, so nothing is left to decide here. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
+1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in `.pi/gauntlet-overrides.md`, or run `/self-audit` manually.)
+2. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. On `GAPS`, do not auto-fix or auto-proceed: run the remediation loop in `verification-before-completion/reference/conformance-check.md` "When the check finds gaps" (disposition menu → isolated fix waves → bounded delta re-audit, capped by `piGauntlet.closureReview.maxFixRounds`). Only when the verdict is `CONFORMS` (or every gap is dispositioned) call `phase_tracker({ action: "complete", phase: "verify" })`.
+3. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Give the closing loop its **own section** — `Closure / conformance: CONFORMS` (or `GAPS` with each gap and its disposition) — so the user sees intent-fidelity as a first-class line before any finishing decision, not buried in the review verdict.
+4. **Proceed to finishing — no confirmation prompt.** When the verdict is `CONFORMS` (or every gap is dispositioned), invoke `/skill:finishing-a-development-branch` immediately. Its Step 4 menu (squash / PR / keep / discard) is the human gate; a separate "ready to finish?" prompt only stacks a second stop in front of it. Open gaps are already owned by step 2, so nothing is left to decide here. Manual testing is a follow-up after the finishing choice (on `<base-branch>` after a squash-merge, or on the PR branch), never a reason to hold this gate.
 
 ## Red Flags — STOP
 

package/skills/verification-before-completion/reference/conformance-check.md

@@ -2,7 +2,12 @@
 
 Tests passing proves the code runs. It does **not** prove the code does what was
 asked. This check confronts deliverables (code **and** docs) against the
-requirements.
+requirements. Docs named in a spec's "Documentation impact" section - any of
+the three classes (introduced, materially amended, derived/memory invalidated) -
+are origin requirements the same as code: a missing or drifted doc from that
+section is a conformance gap, not a code-review nit. See
+`../../brainstorming/reference/documentation-impact.md` for what that section
+contains and how its entries are scoped.
 
 ## Why this is distinct from code review
 
@@ -36,14 +41,14 @@ whole-PR code-quality review. Fusing the two subordinates intent-coverage to a
 code-quality system prompt and compresses the conformance result to an
 afterthought. Code quality is one dispatch; conformance is another.
 
-The persona ships model-free. Read the active preset's settings at
-`$PI_CODING_AGENT_DIR/settings.json` for `piGauntlet.closureReview.model` and
-inject it **call-site** on the dispatch (`model:` if set, else omit to inherit the
-parent's model) — the same mechanism the spec-council chair uses. If the configured
-model is unreachable, retry once with the inherited model. Point it at the strongest
-reasoning model the preset can reach — this is the last correctness gate.
-`thinking` stays frontmatter-pinned at `xhigh` and is not call-site overridable, so
-the config supplies only `model`.
+The persona ships model-free. Resolve `piGauntlet.closureReview.model` **repo-local
+first** — the repo's `.pi/settings.json` overrides the agent preset, whole-object (see
+sibling `settings-precedence.md`) — and inject it **call-site** on the dispatch
+(`model:` if set, else omit to inherit the parent's model) — the same mechanism the
+spec-council chair uses. If the configured model is unreachable, retry once with the
+inherited model. Point it at the strongest reasoning model the resolved config can
+reach — this is the last correctness gate. `thinking` stays frontmatter-pinned at
+`xhigh` and is not call-site overridable, so the config supplies only `model`.
 
 Self-checking in the main session is the fallback when delegation isn't possible.
 
@@ -197,7 +202,8 @@ still-open with its prior verdict, or introducing `Gn+1`.
 
 - The re-audit dispatch carries the **same call-site `model:` injection** as the initial
   audit (when `piGauntlet.closureReview.model` is set, the phase-tracker closure guard
-  requires every `conformance-reviewer` dispatch to specify `model:`).
+  blocks a `conformance-reviewer` dispatch that omits `model:`, and warns — non-blocking —
+  on one whose model differs from the configured value).
 - New or still-open gaps within the cap re-enter the menu above.
 - **Cap: read `piGauntlet.closureReview.maxFixRounds`** (default `2`; missing/non-integer
   → `2`; `< 0` → `0`). `0` = audit-only: `GAPS` renders an accept/rescope-only menu and any

package/skills/verification-before-completion/reference/settings-precedence.md

@@ -0,0 +1,44 @@
+# Settings precedence: repo-local first
+
+How to resolve a `piGauntlet.<key>` settings value that both a repo and an agent
+preset may define. Both the spec-critique gate (`specCouncil`) and the conformance
+gate (`closureReview`) use this rule; it is stated once here.
+
+## Source order (both keys)
+
+Read two files, **repo-local first**:
+
+1. `<repo-root>/.pi/settings.json` - repo root from `git rev-parse --show-toplevel`
+   (inside a worktree this is the worktree root).
+2. `$PI_CODING_AGENT_DIR/settings.json` - the agent preset.
+
+Mechanics for both files: they may contain comments - read them, do not pipe
+through a strict JSON parser. Expand `$PI_CODING_AGENT_DIR`; never substitute a
+hardcoded path for it (reading the repo `.pi/settings.json` as if it were the
+preset is the classic miss - they are different files). On a malformed repo-local
+file, the reading agent emits one warning line in its response and falls back to
+the preset.
+
+## Merge granularity (same for both keys): whole-object
+
+Both `specCouncil` and `closureReview` resolve **whole-object**: if the repo file
+defines the key at all, that definition **replaces** the preset's entirely; the two
+are never merged leaf-by-leaf. If the repo file does not define the key, the
+preset's value is used unchanged.
+
+This is not a pi-gauntlet convention - it is exactly what pi's own settings merge
+does. `deepMergeSettings` (pi's `SettingsManager`) merges only the **top-level**
+Settings keys (of which `piGauntlet` is one) by a one-level spread
+`{ ...preset.piGauntlet, ...repo.piGauntlet }`. That spread replaces each
+**second-level** key (`closureReview`, `specCouncil`, `flowGuards`) wholesale when
+the repo defines it; it does **not** recurse into that key's leaves. So the
+`phase-tracker.ts` closure guard (which reads `pi.settings.piGauntlet.closureReview.model`)
+and the skills (which read repo-first, whole-object) resolve the same value.
+
+**Caveat - partial definitions drop siblings.** Because the replace is
+whole-object, a repo file that sets only *one* leaf of a key silently drops the
+preset's other leaves for that key. A repo `closureReview: { "model": "..." }` with
+no `enforce`/`maxFixRounds` makes those fall back to their code defaults
+(`enforce` true, `maxFixRounds` 2), **not** to the preset's values. Define every
+leaf you care about together in the file that owns the key. (Sibling keys like
+`specCouncil` are unaffected - only the key the repo redefines is replaced.)

package/skills/writing-plans/SKILL.md

@@ -85,6 +85,10 @@ Group tasks into **waves** so the executor can parallelize independent work (see
 
 **Runtime-resource disjointness.** File-disjoint is necessary but not sufficient: two tasks with disjoint files that both mutate the same DB, bind the same port, or share a fixture are **not** parallel-safe and must land in different waves. The executor auto-selects parallel for *every* multi-task wave, so this grouping is the sole parallel-safety guarantee — there is no selection-time judgment downstream. No new mandatory per-task syntax; when a shared runtime resource is the reason two file-disjoint tasks sit in different waves, record it in an inline note on the later wave.
 
+**Doc tasks.** Doc updates are real plan tasks, not an afterthought. Task-local docs (a doc that only describes the file(s) a task already touches) ride with that task. Cross-cutting or index docs (README, `AGENTS.md`, topic guides, taxonomy indexes) sequence into a dedicated trailing doc-only wave — last wave by convention, file-disjoint from every code task so the pairwise-disjoint wave contract holds.
+
+**Doc-wave collision rule.** Amend-over-create (see `brainstorming/reference/documentation-impact.md`) concentrates edits into hub docs like README and `AGENTS.md`. A doc wave with ≥2 tasks auto-selects Parallel-Wave Mode, which requires pairwise-disjoint files — so doc tasks that land on the *same* file merge into one task rather than splitting. A single-task trailing doc wave is the expected shape, not a smell.
+
 ```markdown
 ## Wave 1 — Foundations
 
@@ -189,7 +193,7 @@ Every plan failure mode:
 - ❌ "Similar to Task N" — repeat the code. Implementers (and subagents with fresh context) may read tasks out of order; pointing at a sibling task is not a substitute for showing the code.
 - ❌ References to types, functions, methods, or fields not defined in any task in this plan. If it shows up in Task 5, it must be introduced by Task 1–4 or already exist in the codebase (with a file:line citation).
 - ❌ `[fill in]`, `<example>`, `xxx` markers anywhere in the doc.
-- ❌ "Probably also need to update the docs" — either yes (which doc) or no.
+- ❌ "Probably also need to update the docs" — either yes (which doc) or no. Docs are named plan tasks, sourced from the spec's Documentation impact section (materiality bar in `brainstorming/reference/documentation-impact.md`).
 
 If a decision is genuinely open, put it in an explicit **Open Questions** section at the top and resolve before execution starts.
 
@@ -197,7 +201,7 @@ If a decision is genuinely open, put it in an explicit **Open Questions** sectio
 
 After drafting the plan and before announcing it complete, run three checks yourself. This is a checklist you run yourself — not a subagent dispatch.
 
-- **Spec coverage.** Cross-reference the spec's components/decisions/constraints against the plan. Does every spec section map to one or more tasks? If a spec decision has no implementation task, the plan is missing work or the spec was overspecified.
+- **Spec coverage.** Cross-reference the spec's components/decisions/constraints against the plan. Does every spec section map to one or more tasks? If a spec decision has no implementation task, the plan is missing work or the spec was overspecified. Each Documentation impact entry maps to a plan task (or explicit "none").
 - **Placeholder scan.** Grep the doc for `TODO`, `TBD`, `xxx`, `[fill in]`, `<example>`, `etc.`, "probably", "something like". Resolve or convert each into an explicit Open Question.
 - **Type / API consistency.** Function signatures and field names that appear in multiple tasks must match exactly. The plan is its own contract — internal contradictions surface as bugs during execution.
 - **Wave disjointness.** For every multi-task wave, confirm the tasks' `Files:` sets are pairwise disjoint **and** that no two tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path). Either kind of overlap = mis-grouped wave; split or re-order before handoff.

package/skills/writing-skills/SKILL.md

@@ -36,11 +36,14 @@ Each skill directory contains:
 SKILL.md              # required entry point
 reference/            # optional progressive-disclosure files
   <topic>.md          # read directly when SKILL.md points at it
-<supporting>.md       # prompt templates, examples
+  examples.md         # read directly when SKILL.md points at it
+<supporting>.md       # prompt templates (dispatch payloads)
 ```
 
 `reference/` is the pi pattern for keeping SKILL.md tight while still shipping deep guidance. See `.pi/skills/test-driven-development/reference/` and `.pi/skills/systematic-debugging/reference/` for working examples.
 
+Prompt templates and other dispatch payloads - files filled in and passed wholesale into a subagent `task` - live as siblings of SKILL.md, not under `reference/`. See `requesting-code-review/code-reviewer.md` and the three `subagent-driven-development/*-prompt.md` files. The decision criterion is destination, not format: a file passed wholesale into a subagent's `task` is a sibling; a file read at a decision point for deep guidance, examples, or rationale is `reference/`. Some older skills (`systematic-debugging`, `test-driven-development`) keep deep-guidance `*.md` files flat as siblings, predating the `reference/` convention (obra/superpowers lineage) - that is descriptive history, not a mandate to move them.
+
 ### Reference Files Bundled With This Skill
 
 Read directly when SKILL.md tells you to (path is given inline). The progressive-disclosure pattern is *which file to read when*, not a special tool: