pi-gauntlet 4.3.1 → 4.4.1

package/extensions/lib/phase-tracker-helpers.ts

@@ -0,0 +1,97 @@
+/**
+ * Pure logic for phase-tracker's substep action and marker commit guard.
+ * No fs/git access here — file access is injected so node --test covers it
+ * (registered in scripts/ci.mjs alongside the settings resolvers).
+ */
+
+import { resolve } from "node:path";
+
+export const CONTEXT_DRAFT_MARKER = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
+
+export type SubstepCheck = { ok: true } | { ok: false; error: string };
+
+export function checkSubstep(phaseStatus: string): SubstepCheck {
+  if (phaseStatus === "in_progress") return { ok: true };
+  return { ok: false, error: `substep requires an in_progress phase (status is ${phaseStatus})` };
+}
+
+export function phaseLabel(name: string, substep?: string): string {
+  return substep ? `${name}(${substep})` : name;
+}
+
+// Same statement-start anchor as the branch guards in phase-tracker.ts. Exported
+// so Wave 2 wiring in phase-tracker.ts can drop its duplicate copy.
+export const STMT_START = "(?:^|[\\n;&|(])\\s*";
+// `git commit`, tolerating any global flags between `git` and `commit` (e.g.
+// `-c user.email=x`, common in CI per-commit identity). Group 1 captures the
+// whole flags span as ONE opaque block rather than -C directly: nesting a
+// capture inside a repeated alternation resets it to undefined on iterations
+// that take the other branch (JS regex semantics), so -C after a later flag
+// (e.g. `-C /wt -c user.email=x commit`) would silently lose its capture.
+// DASH_C below re-extracts -C from that span once, outside any repetition.
+// `commit` must be followed by whitespace or end-of-string, not just a word
+// boundary, so `commit-graph` / `commit-tree` don't false-positive.
+const GIT_COMMIT = new RegExp(
+  STMT_START + "git\\s+((?:-\\S+(?:\\s+\\S+)?\\s+)*)commit(?=\\s|$)",
+);
+const DASH_C = /(?:^|\s)-C\s+(\S+)/;
+// Global, lookaround-delimited (not consuming) so adjacent `cd a && cd b &&`
+// statements don't eat each other's anchor/`&&` and hide the second match.
+// parseGitCommit picks the LAST cd before the matched git-commit position, so
+// `cd /a && cd /b && git commit` resolves against /b, not the first cd found.
+const LEADING_CD = /(?<=^|[\n;&|(])\s*cd\s+([^\s)]+)\s*(?=&&|\|\||[;)\n]|$)/g;
+
+export interface CommitForm {
+  cPath: string | undefined;
+  cdPath: string | undefined;
+}
+
+// Textual match anchored at statement starts (^ ; & | ( or newline). Quoted text
+// can still match when preceded by such a char (e.g. sh -c 'x; git commit') —
+// accepted heuristic, same tolerance as the existing Guard 3 mutation checks.
+export function parseGitCommit(command: string): CommitForm | undefined {
+  const m = GIT_COMMIT.exec(command);
+  if (!m) return undefined;
+  let cdPath: string | undefined;
+  for (const cd of command.matchAll(LEADING_CD)) {
+    if (cd.index! < m.index!) cdPath = cd[1];
+  }
+  return { cPath: DASH_C.exec(m[1])?.[1], cdPath };
+}
+
+export function resolveRepoDir(form: CommitForm, sessionCwd: string): string {
+  const base = form.cdPath ? resolve(sessionCwd, form.cdPath) : sessionCwd;
+  return form.cPath ? resolve(base, form.cPath) : base;
+}
+
+// Line-1 anchoring prevents false positives on specs that QUOTE the marker.
+// Working-tree read (not index) is an accepted false-negative window for a
+// backstop whose primary check lives in the brainstorming skill.
+export function findMarkerFile(
+  repoDir: string,
+  specDirs: string[],
+  listFiles: (dir: string) => string[],
+  readFirstLine: (file: string) => string | undefined,
+): string | undefined {
+  for (const dir of specDirs) {
+    for (const file of listFiles(resolve(repoDir, dir))) {
+      if (readFirstLine(file) === CONTEXT_DRAFT_MARKER) return file;
+    }
+  }
+  return undefined;
+}
+
+// Transitions always build fresh state: a substep never survives start/complete/skip/reset.
+export function transitionPhaseState(status: string, reason?: string): { status: string; reason?: string } {
+  return reason === undefined ? { status } : { status, reason };
+}
+
+export function markerGuardApplies(flowGuardsEnforced: boolean, brainstormStatus: string): boolean {
+  return flowGuardsEnforced && brainstormStatus === "in_progress";
+}
+
+export const markerBlockReason = (file: string): string =>
+  `Blocked: ${file} still begins with the context-draft marker - the spec-writing ` +
+  `overwrite has not happened. Overwrite the draft with the real spec (write tool, ` +
+  `full replacement) before committing. ` +
+  `To override, set piGauntlet.flowGuards.enforce: false.`;

package/extensions/phase-tracker.ts

@@ -10,6 +10,8 @@
  */
 
 import { execSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -21,6 +23,16 @@ import {
   settingsErrorWarning,
 } from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
+import {
+  checkSubstep,
+  findMarkerFile,
+  markerBlockReason,
+  parseGitCommit,
+  phaseLabel,
+  resolveRepoDir,
+  STMT_START,
+  transitionPhaseState,
+} from "./lib/phase-tracker-helpers.ts";
 
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
 type Phase = (typeof PHASES)[number];
@@ -29,12 +41,13 @@ type PhaseStatus = "pending" | "in_progress" | "complete" | "skipped";
 interface PhaseState {
   status: PhaseStatus;
   reason?: string;
+  substep?: string;
 }
 
 type PhaseMap = Record<Phase, PhaseState>;
 
 interface PhaseTrackerDetails {
-  action: "start" | "complete" | "skip" | "status" | "reset";
+  action: "start" | "complete" | "skip" | "status" | "reset" | "substep";
   phases: PhaseMap;
   error?: string;
 }
@@ -58,12 +71,12 @@ const CLOSURE_GATE_ERROR =
   '  phase_tracker({ action: "skip", phase: "verify", reason: "<user waiver>" })';
 
 const SHIP_ADVISORY =
-  "Verify is complete and ship is pending. If the conformance verdict is resolved\n" +
-  "(CONFORMS, or every gap dispositioned and approved), invoke\n" +
-  "/skill:finishing-a-development-branch now - do not add a 'ready to finish?' prompt;\n" +
-  "its squash/PR/keep/discard menu is the human gate. If a requirement decision is\n" +
-  "still open, you should not have completed verify - reopen it and surface the open\n" +
-  "decision instead.";
+  "Verify is complete and ship is pending. Verify may complete when the conformance\n" +
+  "verdict is CONFORMS, or every gap is either fixed or carried open as a deferred\n" +
+  "accept/rescope/unauthorized decision. Invoke /skill:finishing-a-development-branch\n" +
+  "now - do not add a 'ready to finish?' prompt; its disposition + squash/PR/keep/discard\n" +
+  "menu is the human gate that resolves any carried-open decision. Only reopen verify if\n" +
+  "a `fix` gap was left unresolved (neither fixed nor deferred).";
 
 // --- Flow guards (spec 2026-06-17-gauntlet-flow-guards) ---
 
@@ -72,7 +85,6 @@ const GUARD_PHASES: Phase[] = ["brainstorm", "plan", "implement"];
 // Guard 2 — branch ops in place. `git switch` never targets a file path;
 // `git checkout -b/-B` is explicit branch creation. Bare `git checkout <x>`
 // is excluded (ambiguous with file checkout). `git worktree ...` is exempt.
-const STMT_START = "(?:^|[\\n;&|(])\\s*";
 const BRANCH_SWITCH = new RegExp(STMT_START + "git\\s+switch\\b");
 const BRANCH_CHECKOUT = new RegExp(STMT_START + "git\\s+checkout\\s+-[bB]\\b");
 const GIT_WORKTREE = /\bgit\s+worktree\b/;
@@ -155,7 +167,7 @@ const pathInSpecDirs = (rawPath: string, specDirs: string[]): boolean => {
 };
 
 const PhaseTrackerParams = Type.Object({
-  action: StringEnum(["start", "complete", "skip", "status", "reset"] as const, {
+  action: StringEnum(["start", "complete", "skip", "status", "reset", "substep"] as const, {
     description: "Action to perform",
   }),
   phase: Type.Optional(
@@ -173,6 +185,11 @@ const PhaseTrackerParams = Type.Object({
       description: "Reset and re-start a phase that is already complete or skipped (rare; default false)",
     }),
   ),
+  substep: Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description: "Substep label for action=substep on an in_progress phase; null or omitted clears it",
+    }),
+  ),
 });
 
 export type PhaseTrackerInput = Static<typeof PhaseTrackerParams>;
@@ -201,7 +218,8 @@ function hasActivity(phases: PhaseMap): boolean {
 function formatWidget(phases: PhaseMap, theme: Theme): string {
   const parts = PHASES.map((p) => {
     const icon = phaseIcon(phases[p].status, theme);
-    const name = phases[p].status === "skipped" ? theme.fg("dim", p) : p;
+    const labeled = phaseLabel(p, phases[p].status === "in_progress" ? phases[p].substep : undefined);
+    const name = phases[p].status === "skipped" ? theme.fg("dim", labeled) : labeled;
     return `${icon} ${name}`;
   });
   return `${theme.fg("muted", "Phases:")} ${parts.join(theme.fg("dim", " → "))}`;
@@ -213,7 +231,7 @@ function formatStatus(phases: PhaseMap): string {
     const s = phases[p];
     const icon = s.status === "complete" ? "✓" : s.status === "in_progress" ? "→" : s.status === "skipped" ? "⊘" : "○";
     const suffix = s.reason ? ` (${s.reason})` : "";
-    lines.push(`  ${icon} ${p}${suffix}`);
+    lines.push(`  ${icon} ${phaseLabel(p, s.status === "in_progress" ? s.substep : undefined)}${suffix}`);
   }
   return lines.join("\n");
 }
@@ -386,6 +404,41 @@ export default function (pi: ExtensionAPI) {
       return { block: true, reason: branchBlockReason(gphase) };
     }
 
+    // Marker commit guard — the context draft (brainstorming gather step) must be
+    // overwritten by the real spec before any commit lands. Backstop to the skill's
+    // own post-write check. Blocked, like Guard 2; skipped entirely when
+    // flowGuards.enforce is false (checked above).
+    // gating contract: markerGuardApplies (see helpers) - enforce checked once above
+    // (flowGuardsEnforced()); re-checking it here would be belt-and-suspenders.
+    if (phases.brainstorm.status === "in_progress") {
+      const commit = parseGitCommit(command);
+      if (commit) {
+        const repoDir = resolveRepoDir(commit, ctx.cwd);
+        const listFiles = (dir: string): string[] => {
+          const walk = (d: string): string[] => {
+            return readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+              const p = join(d, e.name);
+              return e.isDirectory() ? walk(p) : e.isFile() ? [p] : [];
+            });
+          };
+          try {
+            return walk(dir);
+          } catch {
+            return [];
+          }
+        };
+        const readFirstLine = (file: string): string | undefined => {
+          try {
+            return readFileSync(file, "utf8").split("\n", 1)[0];
+          } catch {
+            return undefined;
+          }
+        };
+        const hit = findMarkerFile(repoDir, specDirs(), listFiles, readFirstLine);
+        if (hit) return { block: true, reason: markerBlockReason(hit) };
+      }
+    }
+
     // Guard 3 — bash mutation outside the spec dir during brainstorm.
     if (phases.brainstorm.status === "in_progress" && !firedGuards.get("brainstorm-write")) {
       // Redirect target is cleanly extractable: judge it directly against the spec dirs,
@@ -474,7 +527,7 @@ export default function (pi: ExtensionAPI) {
     description:
       "Track workflow phase progress (brainstorm → plan → implement → verify → ship). " +
       "Actions: start (mark phase in_progress), complete (mark phase complete), " +
-      "skip (mark phase skipped with reason), status (show all phases), reset (clear all phases).",
+      "skip (mark phase skipped with reason), status (show all phases), reset (clear all phases), substep (set/clear a substep label on an in_progress phase).",
     parameters: PhaseTrackerParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -518,7 +571,7 @@ export default function (pi: ExtensionAPI) {
               } as PhaseTrackerDetails,
             };
           }
-          phases = { ...phases, [params.phase]: { status: "in_progress" } };
+          phases = { ...phases, [params.phase]: transitionPhaseState("in_progress") as PhaseState };
           firedGuards.clear();
           updateWidget(ctx);
           return {
@@ -559,7 +612,7 @@ export default function (pi: ExtensionAPI) {
               } as PhaseTrackerDetails,
             };
           }
-          phases = { ...phases, [params.phase]: { status: "complete" } };
+          phases = { ...phases, [params.phase]: transitionPhaseState("complete") as PhaseState };
           firedGuards.clear();
           updateWidget(ctx);
           const advisory =
@@ -591,7 +644,7 @@ export default function (pi: ExtensionAPI) {
             };
           }
           const reason = params.reason;
-          phases = { ...phases, [params.phase]: { status: "skipped", reason } };
+          phases = { ...phases, [params.phase]: transitionPhaseState("skipped", reason) as PhaseState };
           firedGuards.clear();
           updateWidget(ctx);
           return {
@@ -602,6 +655,33 @@ export default function (pi: ExtensionAPI) {
           };
         }
 
+        case "substep": {
+          if (!params.phase) {
+            return {
+              content: [{ type: "text", text: "Error: phase required for substep" }],
+              details: { action: "substep", phases: { ...phases }, error: "phase required" } as PhaseTrackerDetails,
+            };
+          }
+          const check = checkSubstep(phases[params.phase].status);
+          if (!check.ok) {
+            return {
+              content: [{ type: "text", text: `Error: phase "${params.phase}": ${check.error}` }],
+              details: { action: "substep", phases: { ...phases }, error: check.error } as PhaseTrackerDetails,
+            };
+          }
+          const entry: PhaseState = { status: "in_progress" };
+          if (typeof params.substep === "string" && params.substep.trim()) entry.substep = params.substep.trim();
+          phases = { ...phases, [params.phase]: entry };
+          updateWidget(ctx);
+          const label = entry.substep
+            ? `Phase "${params.phase}" substep → ${entry.substep}`
+            : `Phase "${params.phase}" substep cleared`;
+          return {
+            content: [{ type: "text", text: `${label}\n${formatStatus(phases)}` }],
+            details: { action: "substep", phases: { ...phases } } as PhaseTrackerDetails,
+          };
+        }
+
         case "status": {
           return {
             content: [{ type: "text", text: formatStatus(phases) }],
@@ -610,7 +690,9 @@ export default function (pi: ExtensionAPI) {
         }
 
         case "reset": {
-          phases = emptyPhases();
+          phases = Object.fromEntries(
+            PHASES.map((p) => [p, transitionPhaseState("pending")]),
+          ) as PhaseMap;
           conformanceDispatched = false;
           firedGuards.clear();
           updateWidget(ctx);
@@ -667,6 +749,11 @@ export default function (pi: ExtensionAPI) {
           );
         case "skip":
           return new Text(theme.fg("dim", "⊘ ") + theme.fg("muted", "phase skipped"), 0, 0);
+        case "substep": {
+          const active = PHASES.find((ph) => p[ph].status === "in_progress");
+          const label = active ? phaseLabel(active, p[active].substep) : "";
+          return new Text(theme.fg("warning", "→ ") + theme.fg("muted", label), 0, 0);
+        }
         case "status": {
           let text = theme.fg("muted", "Phases:");
           for (const ph of PHASES) {

package/extensions/plan-tracker.ts

@@ -129,7 +129,7 @@ export default function (pi: ExtensionAPI) {
     name: "plan_tracker",
     label: "Plan Tracker",
     description:
-      "Track progress while EXECUTING an implementation plan — the implement phase only. Actions: init (set task list), update (change task status), status (show current state), clear (remove plan). Do NOT use for brainstorming, research, or planning checklists: those phases are open-ended and a bounded task list misrepresents them as a fixed N-step process.",
+      "Track progress while EXECUTING an implementation plan (the implement phase) or a verify-phase conformance fix wave. Actions: init (set task list), update (change task status), status (show current state), clear (remove plan). Do NOT use for brainstorming, research, or planning checklists: those phases are open-ended and a bounded task list misrepresents them as a fixed N-step process.",
     parameters: PlanTrackerParams,
 
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "4.3.1",
+  "version": "4.4.1",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/SKILL.md

@@ -49,16 +49,20 @@ Work through the items below **in order**. This is your own checklist to follow,
 
    Re-entering while a brainstorm is already in progress is safe: mid-brainstorm there are no tasks or later phases to lose, so the reset just re-establishes the same clean slate.
 2. **Set up the worktree** — see [Worktree First](#worktree-first)
-3. **Explore project context** — files, docs, recent commits, current behaviour
-4. **Ask clarifying questions** — one at a time
+3. **Gather context** — follow `gatherer.md` (same directory): set substep `gather`,
+   dispatch the builders, assemble the context draft at the spec path, clear the
+   substep. Unconditional, foreground, no user interaction — the next thing the user
+   sees is a questionary question. This produces the draft; the step below consumes it.
+4. **Understand the idea against the draft** — `Read` the draft, verify load-bearing
+   claims against real code, ask questions one at a time, append citable findings
 5. **Propose 2-3 approaches** — with trade-offs and a recommendation
 6. **Present the design** — in sections, get approval after each
 7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention))
 8. **Spec self-review (lint)** — placeholder scan + internal consistency + documentation named, run inline
-9. **Critique pass (auto-dispatched)** — scope + ambiguity; the spec council via `/skill:roasting-the-spec` when `gauntlet_setting` returns verdict `council`, else a fresh `worker` (see [Spec Council](#spec-council-optional))
-10. **Re-run placeholder scan** — after the critique pass returns, first inline any `external-ref:` flags it raised (see [Spec Self-Review](#spec-self-review-before-user-review-gate)), then re-scan for placeholders its edits may have introduced; surface any ambiguity the worker could not safely resolve at the user gate
-11. **Generate spec summary** — dispatch a fresh, spec-only `spec-summarizer` writing to an absolute temp-dir path via `outputMode: "file-only"`, then `Read` that file back as the **last content-producing** tool call before composing the gate and render its contents **verbatim** at the top of the gate message — do not paraphrase, condense, re-section, or rewrite it (see [User Review Gate](#user-review-gate)); this is part of the existing gate, not a new one
-12. **User review gate** — user reviews the committed spec
+9. **Critique pass (auto-dispatched)** — scope + ambiguity; the spec council via `/skill:roasting-the-spec` when `gauntlet_setting` returns verdict `council` (it applies its apply-set, including any external-ref inlining, to the spec before returning — see [Spec Council](#spec-council-optional)), else a fresh `worker` that applies its own fixes in place
+10. **Re-run placeholder scan** — after the critique pass returns, re-scan the **applied** spec for placeholders its edits may have introduced; surface any ambiguity the critique could not safely resolve at the user gate
+11. **Generate spec summary** — dispatch a fresh, spec-only `spec-summarizer` over the **final (post-apply)** spec, writing to an absolute temp-dir path via `outputMode: "file-only"`, then `Read` that file back as the **last content-producing** tool call before composing the gate and render its contents **verbatim** at the top of the gate message — do not paraphrase, condense, re-section, or rewrite it (see [User Review Gate](#user-review-gate)); this is part of the existing gate, not a new one
+12. **User review gate** — user reviews the applied spec's verbatim summary plus the council audit (Applied/Deferred/Rejected), with a revert valve for any applied council edit
 13. **Transition** — only after approval, invoke `/skill:writing-plans`
 
 ## Project Routing
@@ -112,12 +116,26 @@ Don't try to design a multi-subsystem monolith in one spec doc.
 
 ### 3. Understand the idea
 
-- Check the current project state first: files, docs, recent commits, neighboring services.
-- **Check if the codebase or ecosystem already solves this** before designing from scratch. Grep, read existing AGENTS.md, look at `doc/` and `doc/specs/`.
-- Ask questions **one at a time** to refine the idea.
-- Prefer multiple-choice questions; open-ended is fine when needed.
-- One question per message. If a topic needs more exploration, split into multiple turns.
-- Focus on: purpose, constraints, success criteria, who/what it touches.
+The gather step (see `gatherer.md`) has already assembled a context draft at the spec
+path.
+
+- `Read` the draft **unconditionally before composing question one**. The on-disk
+  copy is canonical — this one rule defeats both a turn-boundary prune after assembly
+  and a session restart.
+- The draft is a **helper, not a fence**: judgment still drives exploration. Verify
+  load-bearing claims (schemas, contracts, the code being changed) against real code
+  via targeted reads (`read_symbol`-grade, not scout's paraphrase) before designing
+  against them.
+- **Check if the codebase or ecosystem already solves this** — the draft's recon
+  section starts that answer; confirm it before designing from scratch.
+- Ask questions **one at a time** to refine the idea. Prefer multiple-choice; one
+  question per message. Focus on: purpose, constraints, success criteria, who/what
+  it touches.
+- **Append bar:** append to the draft's `## Appended during questionary` only
+  findings the spec will cite — schema shapes, hard constraints, ticket-vs-code
+  contradictions, user answers that changed scope. Not a log of every grep.
+  (Appending uses `edit`; the `edit` prohibition in the spec-writing step applies
+  only there.)
 
 ### 4. Explore approaches
 
@@ -197,8 +215,25 @@ Spec lives in the project's `doc/specs/` (see [Project Routing](#project-routing
 
 `<topic>` is a short kebab-case slug (3–6 words). Do **not** append `-design` or any other suffix.
 
+The slug is minted **once, at gather time**, from the initial prompt; the spec-writing
+overwrite reuses the path. If the questionary invalidated the slug, rename at
+spec-writing: write the spec at the new path **and delete the old draft file**
+(nothing was committed, so this is free).
+
 ## Spec Self-Review (Before User Review Gate)
 
+Spec-writing replaces the context draft, in this exact order:
+
+1. `Read` the draft in full — **immediately before** the overwrite. Without this, a
+   pruned questionary plus a full-replacement `write` destroys the only copy of the
+   gathered context at the moment it feeds the spec.
+2. Write the spec with the `write` tool (**full replacement**) at the spec path.
+   Using `edit` at this step is a red flag.
+3. **Immediately after the write**, confirm line 1 of the file is no longer
+   `# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing` — before
+   dispatching lint, critique, council, or summarizer. The phase-tracker commit
+   guard is a backstop, not the primary check.
+
 After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Convention](#filename-convention)) and before showing it to the user, run a self-review pass. **Read all five bullets first, then act:** only the **first three** run here at the main loop (the inline lint); the **last two** (scope + ambiguity) do **not** run inline — they are the dispatched critique pass (checklist item 9). Do not apply scope/ambiguity edits yourself.
 
 - **Placeholder scan.** Any `TODO`, `TBD`, `<fill in>`, `[example]`, `xxx`? Either resolve them or convert to explicit "Open Questions" with names.
@@ -209,7 +244,7 @@ After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Con
 
 The first three checks — **placeholder scan**, **internal consistency**, and **documentation named** — are the inline **lint**: run them here at the main loop and fix what they surface. The last two — **scope** and **ambiguity** — are **not** run inline; they are the **critique pass**, auto-dispatched (per [Spec Council](#spec-council-optional)):
 
-- **Council** (`gauntlet_setting({ key: "specCouncil" })` returns verdict `council`) → invoke `/skill:roasting-the-spec`; it runs the critique and proposes dispositions.
+- **Council** (`gauntlet_setting({ key: "specCouncil" })` returns verdict `council`) → invoke `/skill:roasting-the-spec`; it runs the critique, derives dispositions, and **applies the apply-set to the spec** (including inlining any `external-ref:` cluster it has context for) **before returning** — see that skill for apply mechanics. It returns a structured audit: `Applied:` / `Deferred:` / `Rejected:`.
 - **Otherwise** → dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
 
   ```
@@ -218,23 +253,24 @@ The first three checks — **placeholder scan**, **internal consistency**, and *
     "Read the spec at <abs path to doc/specs/...>. Edit ONLY that file. Apply two checks and\n" +
     "fix what you find in place: (1) Scope — does every paragraph serve the goal? Cut filler;\n" +
     "state out-of-scope explicitly. (2) Ambiguity — is every 'we should' a concrete decision?\n" +
-    "Replace 'we could probably' with 'we will'/'we won't'. Also flag (do NOT fetch) any\n" +
-    "load-bearing external reference (ticket AC, commit SHA, doc) the spec relies on but does\n" +
-    "not inline, and recommend inlining it. Return a summary of what you changed, and flag any\n" +
-    "ambiguity you could NOT safely resolve." })
+    "Replace 'we could probably' with 'we will'/'we won't'. Also inline any load-bearing\n" +
+    "external reference (ticket AC, commit SHA, doc) already given to you in the problem\n" +
+    "statement above; if the spec relies on one not provided here, flag it (do NOT fetch) in\n" +
+    "your summary. Return a summary of what you changed, and flag any ambiguity you could NOT\n" +
+    "safely resolve." })
   ```
 
   `worker`'s model resolves from `subagents.agentOverrides.worker.model` in `settings.json` (unset → inherits the main loop); the dispatch passes no `model:`.
 
-After the critique pass returns, scan it for load-bearing external references before re-running the placeholder scan: in the council path, look for chair clusters whose theme is prefixed `external-ref:`; in the worker path, look for the worker's external-ref flag. For each, inline the referenced content you have context for (e.g. the ticket fetched during brainstorming) via the normal disposition/edit path - you hold the ticket, the critics do not. Then re-run the placeholder scan to catch anything the edits introduced. If the worker flagged ambiguities it could not safely resolve, surface them in the [User Review Gate](#user-review-gate) message so the user decides - the worker auto-applies fixes but never silently swallows an open question.
+Both paths apply their fixes **before returning** — the council auto-applies inside `/skill:roasting-the-spec`, the worker edits the spec file directly. After the critique pass returns, re-run the placeholder scan over the **applied** spec to catch anything the edits introduced. If the worker flagged ambiguities it could not safely resolve, surface them in the [User Review Gate](#user-review-gate) message so the user decides - the worker auto-applies fixes but never silently swallows an open question.
 
 ## Spec Council (Optional)
 
-After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**. Resolve the council with `gauntlet_setting({ key: "specCouncil" })` - the tool returns the merged (repo-over-preset) value as `{ verdict, members, chair, malformed, warning, errors }`. **Do not** hand-roll a settings read. When `verdict` is `"council"`, the council *is* the critique pass - invoke `/skill:roasting-the-spec` automatically (no offer, no prompt), passing `members`/`chair`. When `verdict` is `"worker"`, run the fresh-`worker` critique instead (see [Spec Self-Review](#spec-self-review-before-user-review-gate)). If `malformed` is true or `errors` is non-empty, emit the `warning`/error as one line, then branch strictly on `verdict` - `malformed` can accompany *either* verdict (e.g. a bad `chair` with valid `members` still returns `council`), so never infer the worker path from `malformed` alone. If `gauntlet_setting` is unavailable, stop and report - never fall back to a manual bash/JSON settings merge. Approved council edits (or the worker's in-place fixes) ride in the same worktree commit. The conceptual precedence rule lives in `verification-before-completion/reference/settings-precedence.md`.
+After the inline lint and before the user review gate, **brainstorming owns the critique-pass gate**; council **apply mechanics** live in `/skill:roasting-the-spec` (single source of truth - link, don't restate). Resolve the council with `gauntlet_setting({ key: "specCouncil" })` - the tool returns the merged (repo-over-preset) value as `{ verdict, members, chair, malformed, warning, errors }`. **Do not** hand-roll a settings read. When `verdict` is `"council"`, the council *is* the critique pass - invoke `/skill:roasting-the-spec` automatically (no offer, no prompt), passing `members`/`chair`; it applies its apply-set and returns the audit (Applied/Deferred/Rejected). When `verdict` is `"worker"`, run the fresh-`worker` critique instead (see [Spec Self-Review](#spec-self-review-before-user-review-gate)). If `malformed` is true or `errors` is non-empty, emit the `warning`/error as one line, then branch strictly on `verdict` - `malformed` can accompany *either* verdict (e.g. a bad `chair` with valid `members` still returns `council`), so never infer the worker path from `malformed` alone. If `gauntlet_setting` is unavailable, stop and report - never fall back to a manual bash/JSON settings merge. The already-applied council edits (or the worker's in-place fixes) ride in the same worktree commit. The conceptual precedence rule lives in `verification-before-completion/reference/settings-precedence.md`.
 
 ## User Review Gate
 
-After self-review (and council review, if configured) and after inlining any external-ref flags, dispatch the spec-only summarizer, then commit the spec on the worktree branch and stop. This is the **same** single human gate - the summary is folded into it, not a new gate.
+After self-review and the critique pass (council or worker, both already applied to the spec - see [Spec Council](#spec-council-optional)), dispatch the spec-only summarizer over the **applied** spec, then commit the spec on the worktree branch and stop. This is the **same** single human gate - the summary is folded into it, not a new gate.
 
 Mint an absolute temp path outside the worktree (so it is never committed), then dispatch the summarizer on a fresh context, reading only the spec, writing to that path via file-only output (no `model:` - it inherits the main loop unless a preset sets `subagents.agentOverrides.spec-summarizer.model`):
 
@@ -250,7 +286,7 @@ subagent({ agent: "spec-summarizer", context: "fresh", cwd: "<abs worktree path,
 
 `<SUMMARY_PATH>` above is a placeholder in the dispatch object; it means substitute the value of the shell variable `$SUMMARY_PATH` set above. The steps below use `$SUMMARY_PATH` (the shell form) once the value is in hand.
 
-Then commit the spec — this commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
+Then commit the spec — this commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
 
 1. **From the dispatch tool result, before the `Read`.** If the result is **not** an `"Output saved to: <path> (<N> KB, <M> lines)"` reference (e.g. an exit-0 save error returns the full inline output plus an "Output file error" line — the prunable shape, no file to read), or the reference reports under ~500 bytes, or a size grossly disproportionate to the spec (under ~2% of its byte size), or over ~45 KB (the `Read` truncates at 50KB / 2000 lines, so a larger file cannot render whole) — skip the `Read` and take the degrade path. Use the reference's reported figures; do not re-derive them.
 2. **The `Read` itself, as the last content-producing tool call before composing the gate.** `Read` `$SUMMARY_PATH` and paste its contents verbatim at the top of the gate. If the `Read` fails, returns 0 bytes, or reports truncation — take the degrade path. The `Read` must be last: pi-condense does not protect a `/tmp` read, so any turn boundary between the `Read` and the render lets the ~9KB read result be pruned, reproducing the bug.
@@ -259,21 +295,28 @@ Then commit the spec — this commit is **unconditional**: the summary is only a
 
 Either way — summary rendered or degraded — then `rm "$SUMMARY_PATH"` (unconditional cleanup; harmless if the file was never created, since it lives outside the worktree under the OS temp dir).
 
-Render the temp file's contents **verbatim** first — paste it as-is, do **not** paraphrase, condense, re-section, drop sections, or merge it with council output. "Fold into the gate" means *place it inside the gate message*, not *rewrite it*. After the verbatim block, append the commit confirmation, then — as their **own** adjacent lines, not edits to the summary — any council outcome, critique-pass-unresolved ambiguities, and every entry from the summarizer's gap/external-context footer (surface **all** of them, not just the top risk):
+Render the temp file's contents **verbatim** first — paste it as-is, do **not** paraphrase, condense, re-section, drop sections, or merge it with the council audit. "Fold into the gate" means *place it inside the gate message*, not *rewrite it*. This summary is of the **final (post-apply)** spec, since both critique paths already applied before this dispatch. After the verbatim block, append the commit confirmation, then — as their **own** adjacent lines, not edits to the summary — the council audit (if the council path ran: `Applied:` / `Deferred:` / `Rejected:`, one line each), critique-pass-unresolved ambiguities, and every entry from the summarizer's gap/external-context footer (surface **all** of them, not just the top risk):
 
 ```
 <spec-only summary read back from the temp file — pasted verbatim, unedited>
 
 Spec written and committed to <project>/doc/specs/<filename>.md (worktree: <path>).
 
-<council outcome, if any; unresolved ambiguities; every gap-footer entry from the summary>
+Applied: <cluster -> edit>, ...
+Deferred: <cluster -> where it belongs>, ...
+Rejected: <cluster -> one-line reason>, ...
+(omit the three lines above when the worker path ran, not the council)
 
-Please review. Approve to proceed, or tell me what to change in the spec.
+<unresolved ambiguities; every gap-footer entry from the summary>
+
+Please review. Approve to proceed, tell me what to change in the spec, or say "revert applied council edit <X>" to undo a specific applied edit.
 ```
 
 If you believe the summary needs correcting, do **not** silently rewrite it — re-dispatch the summarizer or note the discrepancy as an adjacent line beneath the verbatim block.
 
-Wait for the user. On a change request, revise the spec and re-present — mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On approval, proceed immediately to `/skill:writing-plans` with no further prompt — the plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
+**Revert valve.** "Revert applied council edit X" is a normal change request: revise the spec to undo edit X, re-dispatch the summarizer with a **fresh** temp path (per the re-dispatch rule below), and re-present the gate. This is cheap here - the spec is not yet plan- or code-bearing.
+
+Wait for the user. On a change request (including a revert), revise the spec and re-present — mint a **fresh** temp path for the re-dispatched summarizer (never reuse a prior round's path, so stale content can never be mistaken for the new summary). On approval, proceed immediately to `/skill:writing-plans` with no further prompt — the plan and execution mode are mechanical derivatives, so the only human gate here is spec approval itself. Don't land the spec on `main`; it stays in the worktree and ships in the same squash commit as the implementation.
 
 After approval, mark the brainstorm phase complete:
 
@@ -294,6 +337,10 @@ phase_tracker({ action: "complete", phase: "brainstorm" })
 ## Red Flags — STOP
 
 - About to write code or start a non-spec edit while this skill is active
+- About to dispatch lint, critique, council, or summarizer while the spec file's line 1 is still the context-draft marker
+- About to run the spec-writing overwrite without re-reading the draft in the same turn
+- About to use `edit` instead of `write` for the spec-writing overwrite
+- About to insert a human gate, announcement, or question between gather dispatch and questionary question one
 - About to run, deploy, or validate the **proposed change** (vs. observing current behaviour) before the user approved the design
 - About to skip the critique pass (council if configured, else fresh worker)
 - Critique dispatch (council or worker) failed to complete and you proceeded to the gate anyway