pi-gauntlet 5.8.1 → 5.9.1

package/extensions/telemetry.ts

@@ -9,12 +9,13 @@
   import { execFile } from "node:child_process";
   import { randomUUID } from "node:crypto";
   import * as nodeFs from "node:fs";
-  import { dirname, join, posix } from "node:path";
+  import { dirname, isAbsolute, join, posix, resolve } from "node:path";
   import * as piRuntime from "@earendil-works/pi-coding-agent";
   import { SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
   import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
   import { DEFAULT_TEST_COMMANDS, resolveTelemetry, settingsErrorWarning, type TelemetryResolved } from "./lib/gauntlet-settings.ts";
   import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
+  import { checkoutOf } from "./lib/checkout.ts";
   import { CONTEXT_DRAFT_MARKER } from "./lib/phase-tracker-helpers.ts";
   import { sha256 } from "./lib/plan-check.ts";
   import { SUPERSEDED_BY_RE, aggregateNumstat, isPlanPath, isSpecPath, isSupersededByBanner, matchDiscardStatement, matchShipStatement, matchTestStatement, parseSpecLinks, planSpecHeader, recordPathFor, repoRelativeToolPath, toPosix, truncateCommand } from "./lib/telemetry-paths.ts";
@@ -100,9 +101,9 @@
   }
 
   function realSettings(cwd: string): SettingsSnapshot {
-    const { gauntlet, errors } = loadGauntletSettings(cwd);
+    const { gauntlet, errors, root } = loadGauntletSettings(cwd);
     const telemetry = resolveTelemetry(gauntlet);
-    const sm = SettingsManager.create(cwd, getAgentDir());
+    const sm = SettingsManager.create(root, getAgentDir());
     const layer = (s: unknown) => ((s as { subagents?: { agentOverrides?: unknown } })?.subagents?.agentOverrides ?? undefined) as Record<string, unknown> | undefined;
     const preset = layer(sm.getGlobalSettings());
     const repo = layer(sm.getProjectSettings());
@@ -158,8 +159,7 @@
 
   export default function (pi: ExtensionAPI, deps: Deps = realDeps) {
     let phases: PhaseMap = emptyPhases();
-    let toplevel: string | undefined;
-    let inGit = false;
+    let toplevel: string | undefined; // toplevel of the bound record's checkout; undefined until bind
     let boundSpec: string | undefined; // repo-relative
     let record: TelemetryRecord | undefined;
     const predecessorLinks = new Set<string>();
@@ -180,12 +180,13 @@
       return s;
     };
 
-    const ensureToplevel = async (ctx: ExtensionContext): Promise<string> => {
-      if (toplevel) return toplevel;
-      const r = await deps.git(["rev-parse", "--show-toplevel"], ctx.cwd);
-      inGit = r.code === 0 && r.stdout.trim() !== "";
-      toplevel = inGit ? r.stdout.trim() : ctx.cwd;
-      return toplevel;
+    // Resolves a tool path (relative to ctx.cwd or absolute) to its owning checkout and
+    // checkout-relative key. undefined outside any checkout.
+    const locate = async (ctx: ExtensionContext, p: string): Promise<{ toplevel: string; rel: string } | undefined> => {
+      const candidateAbs = isAbsolute(p) ? p : resolve(ctx.cwd, p);
+      const co = await checkoutOf(candidateAbs, deps.git);
+      const rel = co ? repoRelativeToolPath(co.toplevel, ctx.cwd, p) : undefined;
+      return co && rel ? { toplevel: co.toplevel, rel } : undefined;
     };
 
     const live = (): Accumulators => record
@@ -228,7 +229,7 @@
     };
 
     const commitRecord = async () => {
-      if (!record || !recordRel || frozen || !inGit) return;
+      if (!record || !recordRel || frozen || !toplevel) return;
       const text = deps.fs.readFile(abs(recordRel)) ?? "";
       if (text === lastCommitted) return;
       const paths = [recordRel, ...(oldRecordRel ? [oldRecordRel] : [])];
@@ -273,7 +274,8 @@
       return newRecord({ spec: specRel, session: sessionId, now: buffer[0]?.ts ?? deps.now(), runId: randomUUID() });
     };
 
-    const bind = async (specRel: string, snap: SettingsSnapshot) => {
+    const bind = async (specRel: string, snap: SettingsSnapshot, specToplevel: string) => {
+      toplevel = specToplevel;
       currentDir = snap.telemetry.dir;
       boundSpec = specRel;
       recordRel = recordPathFor(currentDir, specRel);
@@ -302,7 +304,6 @@
       const approval = record.events.find((e) => e.kind === "phase" && e.name === "brainstorm" && (e.action === "complete" || e.action === "skip"));
       if (approval) record.approved_at ??= approval.ts;
       buffer = [];
-      if (!inGit) warn("not a git repository: record is written but never committed");
       if (!settingsWarned && (snap.errors.length || snap.telemetry.warning)) {
         settingsWarned = true;
         if (snap.errors.length) warn(settingsErrorWarning(snap.errors));
@@ -312,6 +313,7 @@
     };
 
     const unbind = () => {
+      toplevel = undefined;
       boundSpec = undefined;
       record = undefined;
       recordRel = undefined;
@@ -347,8 +349,8 @@
         warn(`record move skipped: ${to} already exists`);
         return false;
       }
-      const trackedResult = inGit ? await deps.git(["ls-files", "--error-unmatch", "--", from], toplevel!) : undefined;
-      const tracked = trackedResult?.code === 0 && trackedResult.stdout.trim() !== "";
+      const trackedResult = await deps.git(["ls-files", "--error-unmatch", "--", from], toplevel!);
+      const tracked = trackedResult.code === 0 && trackedResult.stdout.trim() !== "";
       try {
         deps.fs.mkdirp(dirname(abs(to)));
         if (tracked) {
@@ -408,14 +410,13 @@
       const snap = enabledSettings(ctx);
       if (!snap) return;
       sessionId = ctx.sessionManager.getSessionId();
-      await ensureToplevel(ctx);
       currentDir = snap.telemetry.dir;
       const replay = replayBranch(ctx.sessionManager.getBranch());
       phases = replay.phases;
       const candidate = replay.planCheckSpec ?? replay.lastSpecWrite;
-      const rel = candidate ? repoRelativeToolPath(toplevel!, ctx.cwd, candidate) : undefined;
-      if (rel && isSpecPath(rel)) {
-        await bind(rel, snap);
+      const loc = candidate ? await locate(ctx, candidate) : undefined;
+      if (loc && isSpecPath(loc.rel)) {
+        await bind(loc.rel, snap, loc.toplevel);
         await flush(false);
       }
     });
@@ -436,19 +437,20 @@
       const snap = enabledSettings(ctx);
       if (!snap) return undefined;
       if (!sessionId) sessionId = ctx.sessionManager.getSessionId();
-      await ensureToplevel(ctx);
       if (event.toolName === "phase_tracker" && !event.isError) {
         await applyPhaseDetails(event.details as never, snap);
         return undefined;
       }
       if (event.toolName === "plan_check" && !event.isError) {
         const d = event.details as { status?: string; specPath?: string; planPath?: string } | undefined;
-        const spec = d?.specPath ? repoRelativeToolPath(toplevel!, ctx.cwd, d.specPath) : undefined;
-        const plan = d?.planPath ? repoRelativeToolPath(toplevel!, ctx.cwd, d.planPath) : undefined;
+        const specLoc = d?.specPath ? await locate(ctx, d.specPath) : undefined;
+        const planLoc = d?.planPath ? await locate(ctx, d.planPath) : undefined;
+        const spec = specLoc?.rel;
+        const plan = planLoc?.rel;
         const pass = d?.status === "pass";
-        if (pass && spec && spec !== boundSpec) {
+        if (pass && specLoc && (specLoc.rel !== boundSpec || specLoc.toplevel !== toplevel)) {
           if (record) unbind();
-          await bind(spec, snap);
+          await bind(specLoc.rel, snap, specLoc.toplevel);
         }
         live().gates.plan_rounds += 1;
         pushEvent({ kind: "plan_check", pass, spec, plan });
@@ -457,9 +459,12 @@
       }
       if ((event.toolName === "write" || event.toolName === "edit" || event.toolName === "read") && !event.isError) {
         const rawPath = (event.input as { path?: unknown }).path;
-        const rel = typeof rawPath === "string" ? repoRelativeToolPath(toplevel!, ctx.cwd, rawPath) : undefined;
-        if (!rel) return undefined;
-        return onSpecInteraction(event.toolName, rel, event, snap);
+        const loc = typeof rawPath === "string" ? await locate(ctx, rawPath) : undefined;
+        if (!loc) {
+          if (typeof rawPath === "string" && isSpecPath(toPosix(rawPath))) warn(`spec ${rawPath} is outside a git checkout; telemetry not recorded`);
+          return undefined;
+        }
+        return onSpecInteraction(event.toolName, loc, event, snap);
       }
       if (event.toolName === "subagent" && !event.isError) {
         await onSubagentResult(event.details, event.content);
@@ -493,23 +498,35 @@
     });
 
     // Binding + spec-write bookkeeping; the bound-spec hooks are defined in block 2.
-    const onSpecInteraction = async (tool: "write" | "edit" | "read", rel: string, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
+    const onSpecInteraction = async (tool: "write" | "edit" | "read", loc: { toplevel: string; rel: string }, event: { input: unknown; content: unknown[] }, snap: SettingsSnapshot): Promise<unknown> => {
+      const rel = loc.rel;
       if (!boundSpec) {
         if ((tool === "write" || tool === "edit") && isSpecPath(rel)) {
-          await bind(rel, snap);
+          await bind(rel, snap, loc.toplevel);
           const patch = onBoundSpecWrite(tool, rel, event);
           await flush(true);
           return patch;
         } else if (isPlanPath(rel)) {
-          const spec = planSpecHeader(deps.fs.readFile(abs(rel)) ?? "");
-          const specRel = spec ? repoRelativeToolPath(toplevel!, toplevel!, spec) : undefined;
-          if (specRel && deps.fs.exists(abs(specRel))) {
-            await bind(specRel, snap);
+          const spec = planSpecHeader(deps.fs.readFile(join(loc.toplevel, rel)) ?? "");
+          const specRel = spec ? repoRelativeToolPath(loc.toplevel, loc.toplevel, spec) : undefined;
+          if (specRel && deps.fs.exists(join(loc.toplevel, specRel))) {
+            await bind(specRel, snap, loc.toplevel);
             await flush(true);
           }
         }
         return undefined;
       }
+      if (loc.toplevel !== toplevel) {
+        // Another checkout: a fresh run, never a rename of this record.
+        if ((tool === "write" || tool === "edit") && isSpecPath(rel)) {
+          unbind();
+          await bind(rel, snap, loc.toplevel);
+          const patch = onBoundSpecWrite(tool, rel, event);
+          await flush(true);
+          return patch;
+        }
+        return undefined;
+      }
       if (tool === "read") return undefined;
       if (rel === boundSpec) {
         const patch = onBoundSpecWrite(tool, rel, event);
@@ -603,7 +620,7 @@
     let pendingShip: { id: string; option: "squash" | "pr" | "discard" } | undefined;
 
     const computeDiff = async (snap: SettingsSnapshot) => {
-      if (!record || !inGit) return;
+      if (!record || !toplevel) return;
       let baseRef: string | undefined;
       for (const ref of BASE_REFS) {
         if ((await deps.git(["rev-parse", "--verify", "--quiet", ref], toplevel!)).code === 0) {
@@ -665,13 +682,12 @@
       if (event.toolName === "write") {
         const rawPath = (event.input as { path?: unknown }).path;
         if (typeof rawPath === "string" && phases.brainstorm.status === "in_progress") {
-          await ensureToplevel(ctx);
-          const rel = repoRelativeToolPath(toplevel!, ctx.cwd, rawPath);
-          if (rel && isSpecPath(rel)) {
-            const recRel = recordPathFor(snap.telemetry.dir, rel);
-            const existing = deps.fs.readFile(join(toplevel!, recRel));
+          const loc = await locate(ctx, rawPath);
+          if (loc && isSpecPath(loc.rel)) {
+            const recRel = recordPathFor(snap.telemetry.dir, loc.rel);
+            const existing = deps.fs.readFile(join(loc.toplevel, recRel));
             const parsed = existing ? parseRecord(existing) : undefined;
-            if (parsed?.shipped_at) return { block: true, reason: guardReason(rel, parsed.shipped_at, recRel) };
+            if (parsed?.shipped_at) return { block: true, reason: guardReason(loc.rel, parsed.shipped_at, recRel) };
           }
         }
         return undefined;

package/extensions/verify-before-ship.test.ts

@@ -72,6 +72,22 @@ test("gh pr create warns when unverified", async () => {
   assert.match(warning ?? "", /ran without verification/);
 });
 
+test("git -C <worktree> push and merge --squash are ship events (AC 5)", async () => {
+  for (const cmd of ["git -C /p push -u origin HEAD", "git -C /p merge --squash f"]) {
+    const h = harness();
+    await editSource(h);
+    await h.emitEvent("tool_call", bashCall("s1", cmd));
+    assert.match(warningOf(await h.emitEvent("tool_result", bashResult("s1"))) ?? "", /ran without verification/, cmd);
+  }
+});
+
+test("a quoted mention of git push is not a ship event", async () => {
+  const h = harness();
+  await editSource(h);
+  await h.emitEvent("tool_call", bashCall("q1", 'rg "git push" skills/'));
+  assert.equal((await h.emitEvent("tool_result", bashResult("q1")))[0], undefined);
+});
+
 test("a passing recognised run clears the warning for push", async () => {
   const h = harness();
   await editSource(h);

package/extensions/verify-before-ship.ts

@@ -1,7 +1,8 @@
 /**
  * Verify-before-ship extension
  *
- * Single-session verification gate for shipping commands (git push / gh pr create).
+ * Single-session verification gate for statement-start shipping commands: git merge
+ * --squash, git push, and gh pr create (with any git global flags).
  * Local commits are not ship events; commit-time review-cadence advisories live in
  * phase-tracker. Tracks whether a recognised verification command has succeeded
  * since the last source-file write; injects an advisory warning into the tool
@@ -32,8 +33,7 @@ import {
   settingsErrorWarning,
 } from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
-
-const SHIP_CMD = /\b(git\s+push|gh\s+pr\s+create)\b/;
+import { matchShipStatement } from "./lib/telemetry-paths.ts";
 
 const SOURCE_EXT = /\.(ts|tsx|js|jsx|py|rb|go|rs|java|swift|kt)$/;
 const TEST_PATH = /(^|\/)(tests?|__tests__)\/|\.(test|spec)\.|_test\.(py|go|rb)$/;
@@ -101,7 +101,7 @@ export default function (pi: ExtensionAPI) {
       return undefined;
     }
 
-    if (SHIP_CMD.test(command) && !verified) {
+    if (matchShipStatement(command) && !verified) {
       if (settingsWarned && !settingsErrShown) {
         addShipWarning(event.toolCallId, settingsWarned);
         settingsErrShown = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.8.1",
+  "version": "5.9.1",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -31,6 +31,12 @@
     "bin",
     "CHANGELOG.md"
   ],
+  "bin": {
+    "gauntlet-spec-index": "bin/gauntlet-spec-index.mjs"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
   "pi": {
     "skills": [
       "./skills"

package/skills/brainstorming/SKILL.md

@@ -22,7 +22,7 @@ You **may**:
 - Read code and docs
 - Run the existing system to observe its **current** behaviour — this is research and feeds the spec (boot a local service, replay a sample request, capture a baseline classification, etc.)
 - Write to the project's `doc/specs/` directory
-- `edit` a predecessor spec in the project's spec directory to add a supersession banner (see [Marking superseded specs](#marking-superseded-specs)) — the `edit` prohibition at spec-writing binds the spec being written, not a predecessor file
+- `edit` a predecessor spec in the project's spec directory to add a supersession banner (see [Marking superseded specs](reference/superseding.md)) — the `edit` prohibition at spec-writing binds the spec being written, not a predecessor file
 
 You may **not**:
 
@@ -65,7 +65,7 @@ Work through the items below **in order**. This is your own checklist to follow,
    then state the chat premise note (section 3) before approaches
 5. **Propose 2-3 approaches** — with trade-offs and a recommendation
 6. **Present the design** — in two rounds, one approval each
-7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](#marking-superseded-specs), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
+7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](reference/superseding.md), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
 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` (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; if a predecessor banner exists, confirm its `<scope>` still matches the applied spec (critique edits can change what is superseded); surface any ambiguity the critique could not safely resolve at the user gate
@@ -92,8 +92,8 @@ If the project's `AGENTS.md` calls out additional reading for a specific area (e
 The spec is the **first commit in a dedicated worktree**, not a separate commit on `main`. Before drafting any spec content:
 
 1. Invoke `/skill:using-git-worktrees`. Worktrees live under `.worktrees/` at the repo root, or wherever a project-native worktree script places them.
-2. Switch into the worktree.
-3. From there, write the spec, run self-review, commit, hand off.
+2. Carry the worktree path from the `using-git-worktrees` Step 4 report (`Worktree ready at <full-path>`) as a value: the spec path is `<full-path>/doc/specs/<filename>.md`, every dispatch below sets `cwd: "<full-path>"`, and git runs as `git -C <full-path> ...`. The process cwd stays where pi was launched.
+3. Write the spec at that path, run self-review, commit with `git -C <full-path>`, hand off.
 
 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`).
 
@@ -103,6 +103,8 @@ Spec doc, plan doc, and implementation are all developed in the same worktree; t
 
 ### 1. Check git state
 
+Check git state in the primary checkout (the process cwd; no worktree exists yet):
+
 ```bash
 git status
 git --no-pager log --oneline -5
@@ -239,25 +241,6 @@ 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).
 
-## Marking superseded specs
-
-When the new spec replaces a prior spec — fully or in part — (from the draft's scout recon or the request), mark the predecessor. No mechanical sweep: grep or path-overlap hits never decide supersession.
-
-- `edit` the predecessor spec (in the project's spec directory, per [Project Routing](#project-routing)) to insert, after its title line and a blank line, one banner line per successor:
-
-  ```markdown
-  > **Superseded by:** [<repo-relative path to successor>](<href relative to THIS file>) - <scope>
-  ```
-
-- The visible label is the successor's repo-relative path; the href is computed relative to the predecessor's own directory (Markdown resolves links from the containing file). Same directory: `[doc/specs/B.md](./B.md)`.
-- `<scope>` is the value after the ` - ` separator: `fully`, or the named superseded section(s), e.g. `"Settings resolution" section only`. The scope value itself carries no leading dash — the template above already supplies the separator.
-- Banners are **append-only**: add below any existing supersession lines, formatted or free-form prose. One old spec may accumulate banners from multiple successors. No migration, no dedup.
-- **No transitive rewrite**: if A points at B and B is later superseded by C, A keeps pointing at B; the reader hops.
-- **Mark, never delete.** Delete/archive policy is consumer territory via overrides.
-- **Coverage limits**: unmarked does NOT mean current (code drift, abandoned designs, and partial ships produce no successor spec); marked does NOT mean dead (partial supersession leaves live sections).
-- Predecessor in a **different service's spec directory**: out of scope — record it in the new spec's Open Questions instead of editing outside the write grant.
-- **Override contract**: the gauntlet overrides file (see Project overrides) may replace the banner *syntax*; placement, append-only, no-transitive-rewrite, and mark-never-delete stay fixed. A syntax override entry must itself state the scout-citation guidance for its format (the shipped `gatherer.md` guidance names only the default banner).
-
 ## Spec Self-Review (Before User Review Gate)
 
 Spec-writing replaces the context draft, in this exact order:
@@ -273,7 +256,7 @@ Spec-writing replaces the context draft, in this exact order:
    guard is a backstop, not the primary check.
 4. **After the line-1 check and before the inline lint**, `edit` any known
    predecessor spec to insert its supersession banner (see
-   [Marking superseded specs](#marking-superseded-specs)). This position is fixed:
+   [Marking superseded specs](reference/superseding.md)). This position is fixed:
    the banner is written after any slug rename, so it always cites the final path.
 
 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.
@@ -290,7 +273,7 @@ The first three checks — **placeholder scan**, **internal consistency**, and *
 - **Otherwise** → dispatch one fresh `worker` that applies the scope + ambiguity checks and fixes them in place:
 
   ```
-  subagent({ agent: "worker", context: "fresh", async: false, cwd: "<abs worktree path, from git rev-parse --show-toplevel>", task:
+  subagent({ agent: "worker", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>", task:
     "Problem statement: <the problem the spec addresses + the user's stated intent>.\n" +
     "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" +
@@ -321,14 +304,14 @@ SUMMARY_PATH=$(mktemp "${TMPDIR:-/tmp}/gauntlet-spec-summary.XXXXXX")   # absolu
 ```
 
 ```
-subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs worktree path, from git rev-parse --show-toplevel>",
+subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs worktree path, from the using-git-worktrees Step 4 report>",
   output: "<SUMMARY_PATH>", outputMode: "file-only", task:
   "Summarize the spec at <abs path to doc/specs/...> for the user review gate. Read ONLY that file." })
 ```
 
 `<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 — staging any predecessor spec edited per [Marking superseded specs](#marking-superseded-specs) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. 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 (`Coverage:` when present, then `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):
+Then commit the spec — staging any predecessor spec edited per [Marking superseded specs](reference/superseding.md) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. 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 (`Coverage:` when present, then `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.
@@ -373,7 +356,7 @@ phase_tracker({ action: "complete", phase: "brainstorm" })
 
 Execute this section in place from any later phase. Do not invoke `/skill:brainstorming` (its entry resets both trackers). Worktree, spec commits, and plan survive.
 
-1. Edit the spec. Show `git --no-pager diff -- <spec path>` and one line of impact (affected plan tasks / waves, or "no plan yet").
+1. Edit the spec. Show `git -C <abs worktree path> --no-pager diff -- <spec path>` and one line of impact (affected plan tasks / waves, or "no plan yet").
 2. Wait for approval. Change request -> revise, re-show.
 3. No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks; anchor-changed completed tasks are reopened as `in_progress` and re-run the task loop (`update` never sets `pending`). A removed task is deleted from the plan; then re-`init` the tracker with `{ name, status }` elements: preserved tasks keep their order and statuses, reopened tasks are `in_progress` in place, every still-`pending` task (including newly added ones, whatever wave label they carry) trails the non-pending ones, removed tasks are the only deletions (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress: `phase_tracker({ action: "skip", phase: "<current>", reason: "amendment reopened Task N" })`, then `phase_tracker({ action: "start", phase: "implement", force: true })`; later phases re-enter with `force: true` and rerun in full.
 

package/skills/brainstorming/gatherer.md

@@ -35,6 +35,10 @@ subagent({
 Absolute `output:` paths are mandatory: relative paths in parallel mode resolve
 against the worktree and would get committed.
 
+`<SPEC_INDEX>` is `<directory of this skill's SKILL.md>/../../bin/gauntlet-spec-index.mjs`,
+resolved to an absolute path by the main loop from the skill's `<location>` in the system prompt
+before pasting the task.
+
 ## Task templates
 
 Scout (always dispatched):
@@ -46,12 +50,21 @@ Scout (always dispatched):
 > exact paths and line ranges. If a spec you cite carries a supersession marker
 > (default: a `> **Superseded by:**` banner; the project's overrides may define
 > another format), follow the successor for the superseded scope and cite it
-> instead; cite the old spec only for its unsuperseded sections. Predecessor
-> check: list the project's spec directory, read titles and `**Goal:**` lines,
-> open at most five whose topic matches this request, and name any whose design
-> this request replaces or amends with the section(s) affected -
-> `Predecessor: <path>, <scope>` - or `Predecessor: none`. Judge by topic; shared
-> file paths never decide. End with an
+> instead; cite the old spec only for its unsuperseded sections (banner contract:
+> `reference/superseding.md`). Predecessor check: compose a 5-15 term keyword query
+> from the request (topic nouns, component names, file names - not stop words; if
+> the request is only a ticket reference, take the terms from the ticket title via
+> the tracker CLI when one is available, otherwise use the fallback below). Run
+> `node <SPEC_INDEX> --query '<keywords>' --limit 10` from the worktree root,
+> keeping the keywords inside single quotes, and treat its rows as the candidate
+> list. If the command fails, fall back to listing the project's spec directory
+> and reading titles and `**Goal:**` lines, and write
+> `Spec index unavailable - predecessor check used directory listing.` in your
+> handoff. Either way open at
+> most five candidates whose topic matches this request, and name any whose design
+> this request replaces or amends with the section(s) affected - `Predecessor:
+> <path>, <scope>` - or `Predecessor: none`. Judge by topic; shared file paths never
+> decide. End with an
 > "Open questions that matter for the spec"
 > section. Compact handoff, not a dump.
 

package/skills/brainstorming/reference/superseding.md

@@ -0,0 +1,18 @@
+# Marking superseded specs
+
+When the new spec replaces a prior spec — fully or in part — (from the draft's scout recon or the request), mark the predecessor. No mechanical sweep: grep or path-overlap hits never decide supersession.
+
+- `edit` the predecessor spec (in the project's spec directory, per [Project Routing](../SKILL.md#project-routing)) to insert, after its title line and a blank line, one banner line per successor:
+
+  ```markdown
+  > **Superseded by:** [<repo-relative path to successor>](<href relative to THIS file>) - <scope>
+  ```
+
+- The visible label is the successor's repo-relative path; the href is computed relative to the predecessor's own directory (Markdown resolves links from the containing file). Same directory: `[doc/specs/B.md](./B.md)`.
+- `<scope>` is the value after the ` - ` separator: `fully`, or the named superseded section(s), e.g. `"Settings resolution" section only`. The scope value itself carries no leading dash — the template above already supplies the separator.
+- Banners are **append-only**: add below any existing supersession lines, formatted or free-form prose. One old spec may accumulate banners from multiple successors. No migration, no dedup.
+- **No transitive rewrite**: if A points at B and B is later superseded by C, A keeps pointing at B; the reader hops.
+- **Mark, never delete.** Delete/archive policy is consumer territory via overrides.
+- **Coverage limits**: unmarked does NOT mean current (code drift, abandoned designs, and partial ships produce no successor spec); marked does NOT mean dead (partial supersession leaves live sections).
+- Predecessor in a **different service's spec directory**: out of scope — record it in the new spec's Open Questions instead of editing outside the write grant.
+- **Override contract**: the gauntlet overrides file (see `../SKILL.md#project-overrides`) may replace the banner *syntax*; placement, append-only, no-transitive-rewrite, and mark-never-delete stay fixed. A syntax override entry must itself state the scout-citation guidance for its format (the shipped `gatherer.md` guidance names only the default banner).