pi-gauntlet 5.21.0 → 5.23.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## v5.23.0 - 2026-09-27
+
+### Added
+
+- `gauntlet-spec-index` gains `--corpus specs|docs` (default `specs`, output unchanged). `--corpus docs` indexes project documentation - tracked and untracked non-gitignored `*.md` files matching `**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md`, replaceable through `- docs: <glob>` bullets under `## Spec index` in the gauntlet overrides file - into a second FTS5 table in the same cache, minus `doc(s)/specs`, `doc(s)/plans`, `node_modules`, `.pi/gauntlet`, `.worktrees`, symlinks and context drafts, and prints `score`, `path`, `title`, `snippet`. Both corpora share one confidence rule driven by a corpus descriptor (strong fields `title`/`goal` for specs, `title`/`headings` for docs). The brainstorming scout runs the docs query and renders `Docs touched: <path> - <section heading>` lines that round 2 weighs as documentation-impact candidates.
+
+### Changed
+
+- Spec-index cache schema is 3 (the `files` table is keyed by `(corpus, path)`); existing caches rebuild on first query. `#`/`##`/`###` lines inside fenced code blocks no longer count as the title or headings in either corpus.
+
+## v5.22.0 - 2026-09-26
+
+### Added
+
+- `gauntlet-spec-index` gains a `state` column after `shipped_at` (`superseded` for a `- fully` banner directly under the title, `live` otherwise) and a repeatable `--exclude <path>` flag. `/skill:brainstorming` runs a second predecessor query at spec self-review from the finished spec's title, goal, and H2 headings and lists new `live` candidates at the review gate; the scout composes its first query from the ticket title and body.
+
+### Changed
+
+- `gauntlet-spec-index` applies a confidence rule before `--limit`: only terms in fewer than half the specs count as evidence, a row needs two distinct evidence terms in title or goal, and rows under half the best live score are dropped, so queries with no real match return zero rows. Live rows sort before superseded rows. The cache schema is version 2 and rebuilds on first use.
+
 ## v5.21.0 - 2026-09-26
 
 ### Added

package/README.md

@@ -137,7 +137,7 @@ Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. See [doc/install-internals.md
 
 ## Spec search index
 
-`gauntlet-spec-index` provides lexical search across `doc/specs/*.md` at the repository root and one service level down. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--limit N]`; it requires Node >=24.15.0, refreshes its FTS5 index on every query, and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `files`, and `snippet` columns. The `files` column is a `;`-separated list of repo-relative paths the spec's shipped change modified and that still exist in the repository, the literal `missing` when the spec's telemetry record has no `derived.modified_files` list, or blank when there is no readable record or no recorded path remains. The per-worktree cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`.
+`gauntlet-spec-index` provides lexical search over two corpora in one per-worktree cache. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--corpus specs|docs] [--limit N] [--exclude <repo-relative path>]...`; it requires Node >=24.15.0 and refreshes its FTS5 index on every query. `--corpus specs` (the default) searches `doc/specs/*.md` at the repository root and one service level down and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `state`, `files`, and `snippet` columns. `--corpus docs` searches project documentation and prints `score`, `path`, `title`, and `snippet`; the snippet is the matched `##`/`###` heading line when one holds a query term, else a body fragment. Docs candidates are the tracked and untracked, non-gitignored `*.md` files (`git ls-files -co --exclude-standard`, so nested repositories and submodules are not indexed) matching an include list - default `**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md`, where a slash-free entry also matches one service level down - minus the fixed exclusions `**/doc/specs/**`, `**/docs/specs/**`, `**/doc/plans/**`, `**/docs/plans/**`, `**/node_modules/**`, `.pi/gauntlet/**`, `.worktrees/**`, symlinks, and files whose first line is the context-draft marker; `**` never matches a dot directory, so `.pi/*.md` or `.github/*.md` is indexed only through an explicit include. A project replaces the include list with `- docs: <glob>` bullets under a `## Spec index` heading in its gauntlet overrides file (see [Project-specific overrides](#project-specific-overrides)); the exclusions are not configurable. Both corpora pass the same confidence rule before `--limit` applies: a query term is evidence when it occurs in fewer than half the rows of the queried table (stem variants of one word count once); query tokens split on word boundaries, so `gauntlet-spec-index` searches as three words; a row is returned only when it matches at least two distinct evidence terms in the corpus's strong fields - `title` or `goal` for specs, `title` or `headings` for docs - and rows scoring below half the best live row's score are dropped (every docs row is live). A query with no real match therefore prints the header only and exits 0, and a corpus of two or fewer files never returns rows. `--exclude` (repeatable) removes a path before the rule runs, so the spec under review never sets the bar. `state` is `superseded` when a `> **Superseded by:** ... - fully` banner sits in the block directly under the title and `live` otherwise; named-section banners and consumer-defined banner syntaxes both read as `live`. Live rows sort before superseded rows, then by score. The `files` column is a `;`-separated list of repo-relative paths the spec's shipped change modified and that still exist in the repository, the literal `missing` when the spec's telemetry record has no `derived.modified_files` list, or blank when there is no readable record or no recorded path remains. The cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`. `/skill:brainstorming` queries the specs corpus twice - the scout at gather time from the request, and the main loop at spec-writing from the finished spec's title, goal, and headings, surfacing new `live` candidates at the review gate - and the scout queries the docs corpus once to render `Docs touched:` lines that round 2 weighs as documentation-impact candidates.
 
 ## Performance digest
 
@@ -279,10 +279,18 @@ Use the project's wrapper: `script/worktree create <name>`. It provisions an iso
 database and copies `.env.local`. Never call `git worktree add` directly.
 ```
 
-Beyond `## conventions` and skill-named sections, headings a skill reads by name are documented in their owning skills; other headings retain topic/workflow-convention matching. The override file is read by skill instructions, not by the Pi runtime itself. Missing or empty `## conventions` adds no rules; a lower-priority file cannot supplement the selected file.
+Beyond `## conventions` and skill-named sections, headings a skill reads by name are documented in their owning skills; other headings retain topic/workflow-convention matching. The override file is read by skill instructions and, for its `## Spec index` section only, by `gauntlet-spec-index`; the Pi runtime itself never reads it. Missing or empty `## conventions` adds no rules; a lower-priority file cannot supplement the selected file.
 
 **Discovery ladder:** skills check three locations, in order, and use the first one found - never merged: `.pi/gauntlet-overrides.md`, then `<repo root>/gauntlet-overrides.md`, then `<repo root>/doc/gauntlet-overrides.md` (`<repo root>` = `git rev-parse --show-toplevel`, or the current directory outside a repo). Pick one location per repo.
 
+**`## Spec index` section:** `gauntlet-spec-index --corpus docs` reads `- docs: <glob>` bullets under this heading as the docs include list, replacing the default (`**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md`). Backticks or quotes around the glob are stripped; no other key under the heading is read, and the fixed exclusions always apply. For example:
+
+```markdown
+## Spec index
+- docs: `**/doc/**/*.md`
+- docs: `handbook/**/*.md`
+```
+
 **`## Issue tracker` section:** `shape-ticket` resolves tracker access through a capability ladder, and this is its first rung - it overrides the zero-config `gh` (GitHub) / `linearis` (Linear) defaults for any other tracker. Name the CLI's read, search, create, update, and post comment commands explicitly. For a Jira CLI, for example:
 
 ```markdown

package/bin/gauntlet-spec-index.mjs

@@ -1,28 +1,39 @@
 #!/usr/bin/env node
-// Lexical search over the spec corpus. Build-on-query: refresh a per-worktree
-// FTS5 cache by mtime+size, then rank with bm25 and join telemetry at output.
-import { readFileSync, appendFileSync, existsSync, statSync, readdirSync, mkdirSync, rmSync, realpathSync } from "node:fs";
-import { join, dirname, basename, isAbsolute } from "node:path";
+// Lexical search over spec and docs corpora (FTS5, bm25, shared confidence rule); telemetry joined for specs only.
+import { readFileSync, appendFileSync, existsSync, statSync, lstatSync, readdirSync, mkdirSync, rmSync, realpathSync, openSync, readSync, closeSync } from "node:fs";
+import { join, dirname, basename, isAbsolute, matchesGlob } from "node:path";
 import { execFileSync } from "node:child_process";
 import process from "node:process";
 import { parse as parseYaml } from "yaml";
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 3;
+const EVIDENCE_DF_FRACTION = 0.5;
+const MIN_EVIDENCE_TOKENS = 2;
+const SCORE_RATIO = 0.5;
+// Default banner grammar of skills/brainstorming/reference/superseding.md; a named-section
+// scope or anything after `- fully` keeps the spec live.
+const FULLY_BANNER = /^> \*\*Superseded by:\*\* \[.*\]\(.*\) - fully$/;
 const MIN_NODE = [24, 15, 0];
 const DRAFT_MARKER = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
 const EXCLUDE_LINE = "/.pi/gauntlet/index.sqlite*";
 const SKIP_DIRS = new Set([".worktrees", "node_modules", "build"]);
-const HEADER = ["score", "path", "service", "title", "status", "shipped_at", "files", "snippet"];
+const FENCE = /^\s*(`{3,}|~{3,})/;
+const DOC_INCLUDES = ["**/doc/**/*.md", "**/docs/**/*.md", "README.md", "AGENTS.md"];
+const DOC_EXCLUDES = ["**/doc/specs/**", "**/docs/specs/**", "**/doc/plans/**", "**/docs/plans/**", "**/node_modules/**", ".pi/gauntlet/**", ".worktrees/**"];
+const OVERRIDES_FILES = [".pi/gauntlet-overrides.md", "gauntlet-overrides.md", "doc/gauntlet-overrides.md"];
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS meta  (key TEXT PRIMARY KEY, value TEXT);
-  CREATE TABLE IF NOT EXISTS files (path TEXT PRIMARY KEY, mtime_ms INTEGER, size INTEGER);
+  CREATE TABLE IF NOT EXISTS files (corpus TEXT NOT NULL, path TEXT NOT NULL, mtime_ms INTEGER, size INTEGER, PRIMARY KEY (corpus, path));
   CREATE VIRTUAL TABLE IF NOT EXISTS specs USING fts5(
-    path UNINDEXED, service UNINDEXED, title, goal, headings, body,
+    path UNINDEXED, service UNINDEXED, title, goal, headings, body, state UNINDEXED,
+    tokenize = 'porter unicode61');
+  CREATE VIRTUAL TABLE IF NOT EXISTS docs USING fts5(
+    path UNINDEXED, title, headings, body,
     tokenize = 'porter unicode61');
 `;
 
 const usage = () => {
-  process.stderr.write('usage: gauntlet-spec-index --query "<text>" [--limit N]\n');
+  process.stderr.write('usage: gauntlet-spec-index --query "<text>" [--corpus specs|docs] [--limit N] [--exclude <repo-relative path>]...\n');
   process.exit(1);
 };
 const die = (msg) => {
@@ -32,14 +43,18 @@ const die = (msg) => {
 
 function parseArgs(argv) {
   let query;
+  let corpus = "specs";
   let limit = 10;
+  const exclude = [];
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === "--query" && argv[i + 1] !== undefined) query = argv[++i];
+    else if (argv[i] === "--corpus" && Object.hasOwn(CORPORA, argv[i + 1] ?? "")) corpus = argv[++i];
     else if (argv[i] === "--limit" && /^[1-9]\d*$/.test(argv[i + 1] ?? "")) limit = Number(argv[++i]);
+    else if (argv[i] === "--exclude" && argv[i + 1] !== undefined) exclude.push(argv[++i]);
     else usage();
   }
   if (query === undefined) usage();
-  return { query, limit };
+  return { query, corpus, limit, exclude };
 }
 
 function nodeOk() {
@@ -80,11 +95,64 @@ function discover(root) {
     }
   };
   collect("doc/specs", "root");
-  const entries = readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
-  for (const e of entries) {
-    if (e.name.startsWith(".") || SKIP_DIRS.has(e.name)) continue;
-    if (!e.isDirectory() && !e.isSymbolicLink()) continue;
-    collect(`${e.name}/doc/specs`, e.name);
+  for (const s of services(root).sort((a, b) => a.localeCompare(b))) collect(`${s}/doc/specs`, s);
+  return out;
+}
+
+// Top-level directories discover() would scan; a slash-free include also matches one level under them.
+function services(root) {
+  return readdirSync(root, { withFileTypes: true })
+    .filter((e) => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith(".") && !SKIP_DIRS.has(e.name))
+    .map((e) => e.name);
+}
+
+function includes(root) {
+  const file = OVERRIDES_FILES.map((rel) => join(root, rel)).find((abs) => existsSync(abs));
+  if (!file) return DOC_INCLUDES;
+  const globs = [];
+  let inSection = false;
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (e) {
+    die(`gauntlet-spec-index: unreadable overrides file ${file}: ${e.message}`);
+  }
+  for (const line of text.split(/\r?\n/)) {
+    if (/^## /.test(line)) { inSection = line.trim() === "## Spec index"; continue; }
+    if (!inSection) continue;
+    const m = /^-\s+docs:\s*(.+?)\s*$/.exec(line);
+    if (m) globs.push(m[1].replace(/^[`"']+|[`"']+$/g, ""));
+  }
+  return globs.length ? globs : DOC_INCLUDES;
+}
+
+function firstLine(abs) {
+  const fd = openSync(abs, "r");
+  try {
+    const buf = Buffer.alloc(128);
+    const n = readSync(fd, buf, 0, 128, 0);
+    return buf.toString("utf8", 0, n).split(/\r?\n/, 1)[0];
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function discoverDocs(root, globs) {
+  const svc = services(root);
+  const patterns = globs.flatMap((g) => (g.includes("/") ? [g] : [g, ...svc.map((s) => `${s}/${g}`)]));
+  const listed = execFileSync("git", ["-C", root, "ls-files", "-co", "--exclude-standard", "-z", "--", "*.md"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split("\0").filter(Boolean);
+  const out = [];
+  for (const rel of listed) {
+    if (!patterns.some((p) => matchesGlob(rel, p))) continue;
+    if (DOC_EXCLUDES.some((p) => matchesGlob(rel, p))) continue;
+    let st;
+    try {
+      st = lstatSync(join(root, rel));
+      if (!st.isFile() || firstLine(join(root, rel)) === DRAFT_MARKER) continue;
+    } catch {
+      continue;
+    }
+    out.push({ path: rel, mtime_ms: Math.trunc(st.mtimeMs), size: st.size });
   }
   return out;
 }
@@ -137,33 +205,60 @@ async function openDb(root) {
   }
 }
 
+function fenceMask(lines) {
+  const mask = new Array(lines.length).fill(false);
+  let open = null;
+  for (let i = 0; i < lines.length; i++) {
+    const m = FENCE.exec(lines[i]);
+    if (open) {
+      mask[i] = true;
+      if (m && m[1][0] === open.ch && m[1].length >= open.len) open = null;
+    } else if (m) {
+      mask[i] = true;
+      open = { ch: m[1][0], len: m[1].length };
+    }
+  }
+  return mask;
+}
+
 function extract(text, path) {
   const lines = text.split(/\r?\n/);
-  const title = lines.find((l) => l.startsWith("# "))?.slice(2).trim() || basename(path, ".md");
+  const fenced = fenceMask(lines);
+  const h1 = lines.findIndex((l, i) => !fenced[i] && l.startsWith("# "));
+  const title = (h1 >= 0 ? lines[h1].slice(2).trim() : "") || basename(path, ".md");
   const goal = lines.find((l) => l.startsWith("**Goal:**"))?.slice("**Goal:**".length).trim() ?? "";
-  const headings = lines.filter((l) => /^##{1,2} /.test(l)).map((l) => l.replace(/^#+ /, "")).join("\n");
-  return { title, goal, headings };
+  const headings = lines.filter((l, i) => !fenced[i] && /^##{1,2} /.test(l)).map((l) => l.replace(/^#+ /, "")).join("\n");
+  let state = "live";
+  if (h1 >= 0) {
+    // Title block: everything after the H1 up to the first H2 heading or code fence.
+    for (const l of lines.slice(h1 + 1)) {
+      if (/^## /.test(l) || FENCE.test(l)) break;
+      if (FULLY_BANNER.test(l)) { state = "superseded"; break; }
+    }
+  }
+  return { title, goal, headings, state };
 }
 
 function refresh(db, root, corpus) {
-  const known = new Map(db.prepare("SELECT path, mtime_ms, size FROM files").all().map((r) => [r.path, r]));
-  const present = new Set(corpus.map((f) => f.path));
-  const delSpec = db.prepare("DELETE FROM specs WHERE path = ?");
-  const delFile = db.prepare("DELETE FROM files WHERE path = ?");
-  const insSpec = db.prepare("INSERT INTO specs (path, service, title, goal, headings, body) VALUES (?, ?, ?, ?, ?, ?)");
-  const putFile = db.prepare("INSERT OR REPLACE INTO files (path, mtime_ms, size) VALUES (?, ?, ?)");
+  const { table } = corpus;
+  const found = corpus.discover(root);
+  const known = new Map(db.prepare("SELECT path, mtime_ms, size FROM files WHERE corpus = ?").all(table).map((r) => [r.path, r]));
+  const present = new Set(found.map((f) => f.path));
+  const delRow = db.prepare(`DELETE FROM ${table} WHERE path = ?`);
+  const delFile = db.prepare("DELETE FROM files WHERE corpus = ? AND path = ?");
+  const insRow = db.prepare(`INSERT INTO ${table} (${corpus.columns.join(", ")}) VALUES (${corpus.columns.map(() => "?").join(", ")})`);
+  const putFile = db.prepare("INSERT OR REPLACE INTO files (corpus, path, mtime_ms, size) VALUES (?, ?, ?, ?)");
   db.exec("BEGIN IMMEDIATE");
   try {
-    for (const path of known.keys()) if (!present.has(path)) { delSpec.run(path); delFile.run(path); }
-    for (const f of corpus) {
+    for (const path of known.keys()) if (!present.has(path)) { delRow.run(path); delFile.run(table, path); }
+    for (const f of found) {
       const k = known.get(f.path);
       if (k && k.mtime_ms === f.mtime_ms && k.size === f.size) continue;
       const text = readFileSync(join(root, f.path), "utf8");
-      delSpec.run(f.path);
-      if (text.split(/\r?\n/, 1)[0] === DRAFT_MARKER) { delFile.run(f.path); continue; }
-      const x = extract(text, f.path);
-      insSpec.run(f.path, f.service, x.title, x.goal, x.headings, text);
-      putFile.run(f.path, f.mtime_ms, f.size);
+      delRow.run(f.path);
+      if (text.split(/\r?\n/, 1)[0] === DRAFT_MARKER) { delFile.run(table, f.path); continue; }
+      insRow.run(...corpus.row(text, f));
+      putFile.run(table, f.path, f.mtime_ms, f.size);
     }
     db.exec("COMMIT");
   } catch (e) {
@@ -172,8 +267,58 @@ function refresh(db, root, corpus) {
   }
 }
 
-const toMatch = (query) =>
-  query.split(/\s+/).filter((t) => t.length >= 2).map((t) => `"${t.replaceAll('"', '""')}"`).join(" OR ");
+const tokens = (query) => query.split(/[^\p{L}\p{N}\p{Co}]+/u).filter((t) => t.length >= 2);
+const quote = (t) => `"${t.replaceAll('"', '""')}"`;
+const toMatch = (toks) => toks.map(quote).join(" OR ");
+
+// Porter is not idempotent (manatee -> manate -> manat), so MATCH always receives an
+// original token; the vocab pass only decides which tokens are the same term.
+function representatives(db, toks) {
+  const mem = new db.constructor(":memory:");
+  try {
+    mem.exec("CREATE VIRTUAL TABLE q USING fts5(t, tokenize = 'porter unicode61'); CREATE VIRTUAL TABLE qi USING fts5vocab(q, 'instance')");
+    const ins = mem.prepare("INSERT INTO q (rowid, t) VALUES (?, ?)");
+    toks.forEach((t, i) => ins.run(i + 1, t));
+    const rep = new Map();
+    for (const r of mem.prepare("SELECT term, doc FROM qi ORDER BY doc, offset").all()) if (!rep.has(r.term)) rep.set(r.term, toks[r.doc - 1]);
+    return rep;
+  } finally {
+    mem.close();
+  }
+}
+
+function confidenceFilter(rows, evidence) {
+  return rows.filter((r) => {
+    const hits = evidence.filter((e) => e.all.has(r.rowid)).length;
+    const strong = evidence.filter((e) => e.strong.has(r.rowid)).length;
+    return hits >= MIN_EVIDENCE_TOKENS && strong >= MIN_EVIDENCE_TOKENS;
+  });
+}
+
+function query(db, corpus, toks, { limit, exclude }) {
+  const { table } = corpus;
+  const n = db.prepare(`SELECT count(*) AS n FROM ${table}`).get().n;
+  const rowids = (match) => new Set(db.prepare(`SELECT rowid FROM ${table} WHERE ${table} MATCH ?`).all(match).map((r) => r.rowid));
+  const reps = representatives(db, toks);
+  const terms = [...new Set(reps.values())];
+  const evidence = [];
+  for (const tok of terms) {
+    const all = rowids(quote(tok));
+    if (all.size === 0 || all.size >= n * EVIDENCE_DF_FRACTION) continue;
+    evidence.push({ all, strong: rowids(corpus.strong.map((f) => `${f}:${quote(tok)}`).join(" OR ")) });
+  }
+  if (evidence.length < MIN_EVIDENCE_TOKENS) return [];
+  const rows = db.prepare(
+    `SELECT rowid, ${corpus.select}, bm25(${table}, ${corpus.weights.map((w) => w.toFixed(1)).join(", ")}) AS score
+     FROM ${table} WHERE ${table} MATCH ?`,
+  ).all(toMatch(terms)).filter((r) => !exclude.includes(r.path));
+  const kept = confidenceFilter(rows, evidence);
+  const live = (r) => !corpus.hasState || r.state === "live";
+  kept.sort((a, b) => Number(!live(a)) - Number(!live(b)) || a.score - b.score);
+  const best = kept.find(live);
+  const cut = best ? kept.filter((r) => Math.abs(r.score) >= SCORE_RATIO * Math.abs(best.score)) : kept;
+  return cut.slice(0, limit);
+}
 
 function telemetry(root, specPath) {
   const blank = { status: null, shipped_at: null, files: "" };
@@ -198,26 +343,60 @@ const cell = (v) => (v === null || v === undefined ? "" : String(v).replace(/\s+
 // Paths keep their spaces; only column and row delimiters are neutralised.
 const filesCell = (v) => v.replace(/[\t\r\n]+/g, " ");
 
+function docSnippet(r) {
+  if (!r.hsnip.includes("\u0001")) return r.bsnip;
+  const fragment = r.hsnip.split("\n").find((line) => line.includes("\u0001")).replace(/[\u0001\u0002]/g, "");
+  return r.headings.split("\n").find((line) => line.includes(fragment));
+}
+
+const CORPORA = {
+  specs: {
+    table: "specs",
+    columns: ["path", "service", "title", "goal", "headings", "body", "state"],
+    strong: ["title", "goal"],
+    weights: [0, 0, 10, 5, 2, 1, 0],
+    hasState: true,
+    header: ["score", "path", "service", "title", "status", "shipped_at", "state", "files", "snippet"],
+    select: "path, service, title, state, snippet(specs, 5, '', '', '...', 12) AS snippet",
+    discover,
+    row: (text, f) => {
+      const x = extract(text, f.path);
+      return [f.path, f.service, x.title, x.goal, x.headings, text, x.state];
+    },
+    format: (root, r) => {
+      const t = telemetry(root, r.path);
+      return [...[r.score.toFixed(3), r.path, r.service, r.title, t.status, t.shipped_at, r.state].map(cell), filesCell(t.files), cell(r.snippet)];
+    },
+  },
+  docs: {
+    table: "docs",
+    columns: ["path", "title", "headings", "body"],
+    strong: ["title", "headings"],
+    weights: [0, 10, 3, 1],
+    hasState: false,
+    header: ["score", "path", "title", "snippet"],
+    select: "path, title, headings, snippet(docs, 2, '\u0001', '\u0002', '', 12) AS hsnip, snippet(docs, 3, '', '', '...', 12) AS bsnip",
+    discover: (root) => discoverDocs(root, includes(root)),
+    row: (text, f) => {
+      const x = extract(text, f.path);
+      return [f.path, x.title, x.headings, text];
+    },
+    format: (root, r) => [r.score.toFixed(3), r.path, r.title, docSnippet(r)].map(cell),
+  },
+};
+
 async function main() {
   if (!nodeOk()) die(`gauntlet-spec-index needs Node >=24.15.0 (found ${process.versions.node})`);
-  const { query, limit } = parseArgs(process.argv.slice(2));
-  const match = toMatch(query);
-  if (!match) usage();
+  const { query: text, corpus: name, limit, exclude } = parseArgs(process.argv.slice(2));
+  const toks = tokens(text);
+  if (!toks.length) usage();
   const root = repoRoot();
+  const corpus = CORPORA[name];
   const db = await openDb(root);
-  refresh(db, root, discover(root));
-  const rows = db.prepare(
-    `SELECT path, service, title,
-            bm25(specs, 0, 0, 10.0, 5.0, 2.0, 1.0) AS score,
-            snippet(specs, 5, '', '', '...', 12) AS snippet
-     FROM specs WHERE specs MATCH ?
-     ORDER BY score LIMIT ?`,
-  ).all(match, limit);
-  const out = [HEADER.join("\t")];
-  for (const r of rows) {
-    const t = telemetry(root, r.path);
-    out.push([...[r.score.toFixed(3), r.path, r.service, r.title, t.status, t.shipped_at].map(cell), filesCell(t.files), cell(r.snippet)].join("\t"));
-  }
+  refresh(db, root, corpus);
+  const rows = query(db, corpus, toks, { limit, exclude });
+  const out = [corpus.header.join("\t")];
+  for (const r of rows) out.push(corpus.format(root, r).join("\t"));
   process.stdout.write(out.join("\n") + "\n");
   db.close();
 }

package/bin/gauntlet-spec-index.test.mjs

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, utimesSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, utimesSync, symlinkSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { spawnSync } from "node:child_process";
@@ -9,30 +9,58 @@ import { DatabaseSync } from "node:sqlite";
 
 const CLI = join(dirname(fileURLToPath(import.meta.url)), "gauntlet-spec-index.mjs");
 const DRAFT = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
+const HEADER = ["score", "path", "service", "title", "status", "shipped_at", "state", "files", "snippet"];
+const DOCS_HEADER = ["score", "path", "title", "snippet"];
+const docFiller = (n) => `# Filler ${n}\n\n## Design\n\nnothing of note here\n`;
+const decoy = "# ptarmigan gannet decoy\n\n## ptarmigan gannet\n\nbody\n";
+const docsRepo = () => {
+  const root = gitRepo();
+  write(root, "doc/guide.md", "# Guide\n\n## Configuring the ptarmigan gannet\n\nprose about setup\n");
+  write(root, "README.md", "# Repo\n\nThe body mentions ptarmigan once.\n");
+  for (let n = 1; n <= 4; n++) write(root, `doc/filler-${n}.md`, docFiller(n));
+  for (const p of ["doc/specs/a.md", "docs/specs/b.md", "doc/plans/p.md", "docs/plans/q.md", "node_modules/x/doc/a.md", "build/doc/b.md", ".pi/gauntlet/n.md", ".worktrees/w/doc/g.md"]) write(root, p, decoy);
+  write(root, ".gitignore", "build/\n");
+  write(root, "doc/draft.md", `${DRAFT}\n\n## ptarmigan gannet\n`);
+  commit(root);
+  return root;
+};
+const docsPaths = (root) => withDb(root, (db) => db.prepare("SELECT path FROM docs ORDER BY path").all().map((r) => r.path));
+const overrides = (root, globs) => write(root, ".pi/gauntlet-overrides.md", `## Issue tracker\ntracker: none\n\n## Spec index\n${globs.map((g) => `- docs: \`${g}\``).join("\n")}\n\n## release\nnothing\n`);
 
 const write = (root, rel, text) => {
   mkdirSync(join(root, dirname(rel)), { recursive: true });
   writeFileSync(join(root, rel), text);
 };
 
-const repo = () => {
+const gitRepo = () => {
   const root = mkdtempSync(join(tmpdir(), "gsi-"));
   spawnSync("git", ["init", "-q"], { cwd: root });
-  write(root, "doc/specs/a.md", "# Alpha zephyr widget\n\n**Goal:** rank the widget.\n\n## Design\n\nbody text\n");
-  write(root, "svc-a/doc/specs/b.md", "# Beta service\n\n**Goal:** unrelated.\n\nDeep in the body a zephyr appears.\n");
-  write(root, ".worktrees/x/doc/specs/decoy1.md", "# zephyr decoy one\n");
-  write(root, "build/doc/specs/decoy2.md", "# zephyr decoy two\n");
-  write(root, "apps/svc/doc/specs/decoy3.md", "# zephyr decoy three\n");
-  write(root, "doc/specs/draft.md", `${DRAFT}\n\nzephyr zephyr zephyr\n`);
+  return root;
+};
+const commit = (root) => {
   spawnSync("git", ["add", "-A"], { cwd: root });
   spawnSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "fixture"], { cwd: root });
+};
+// Fillers keep the corpus large enough that two-document probe terms stay below N/2.
+const filler = (n) => `# Filler ${n}\n\n**Goal:** filler goal ${n}.\n\n## Design\n\nnothing of note here\n`;
+
+const repo = () => {
+  const root = gitRepo();
+  write(root, "doc/specs/a.md", "# Alpha zephyr widget\n\n**Goal:** rank the widget.\n\n## Design\n\nbody text\n");
+  write(root, "svc-a/doc/specs/b.md", "# Beta service\n\n**Goal:** zephyr widget for the beta service.\n\nDeep in the body a zephyr appears.\n");
+  for (const n of ["one", "two", "three", "four"]) write(root, `doc/specs/filler-${n}.md`, filler(n));
+  write(root, ".worktrees/x/doc/specs/decoy1.md", "# zephyr widget decoy one\n");
+  write(root, "build/doc/specs/decoy2.md", "# zephyr widget decoy two\n");
+  write(root, "apps/svc/doc/specs/decoy3.md", "# zephyr widget decoy three\n");
+  write(root, "doc/specs/draft.md", `${DRAFT}\n\nzephyr widget zephyr widget\n`);
+  commit(root);
   return root;
 };
 
 const run = (cwd, args) => {
   const r = spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: "utf8" });
   const lines = r.stdout.split("\n").filter(Boolean);
-  return { status: r.status, stderr: r.stderr, header: lines[0]?.split("\t"), rows: lines.slice(1).map((l) => l.split("\t")) };
+  return { status: r.status, stderr: r.stderr, stdout: r.stdout, header: lines[0]?.split("\t"), rows: lines.slice(1).map((l) => l.split("\t")) };
 };
 const paths = (res) => res.rows.map((r) => r[1]);
 const withDb = (root, fn) => {
@@ -47,41 +75,39 @@ const withDb = (root, fn) => {
 test("1: corpus boundary, ordering, draft skip, git status clean, exclude written once", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  const r1 = run(root, ["--query", "zephyr"]);
+  const r1 = run(root, ["--query", "zephyr widget"]);
   assert.equal(r1.status, 0, r1.stderr);
   assert.deepEqual(paths(r1), ["doc/specs/a.md", "svc-a/doc/specs/b.md"]);
   assert.deepEqual(r1.rows.map((r) => r[2]), ["root", "svc-a"]);
   const status = spawnSync("git", ["status", "--porcelain"], { cwd: root, encoding: "utf8" }).stdout;
   assert.equal(status, "");
-  run(root, ["--query", "zephyr"]);
+  run(root, ["--query", "zephyr widget"]);
   const exclude = readFileSync(join(root, ".git/info/exclude"), "utf8");
   assert.equal(exclude.split("\n").filter((l) => l === "/.pi/gauntlet/index.sqlite*").length, 1);
 });
 
-test("2: title outranks body; --limit 1; default up to 10", (t) => {
+test("2: title outranks goal; --limit 1", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  for (let i = 0; i < 12; i++) write(root, `doc/specs/many-${i}.md`, `# Spec ${i}\n\nquokka\n`);
-  assert.deepEqual(paths(run(root, ["--query", "zephyr", "--limit", "1"])), ["doc/specs/a.md"]);
-  assert.equal(run(root, ["--query", "quokka"]).rows.length, 10);
+  assert.deepEqual(paths(run(root, ["--query", "zephyr widget", "--limit", "1"])), ["doc/specs/a.md"]);
 });
 
 test("3: incremental refresh updates only the edited row; delete removes rows", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  run(root, ["--query", "zephyr"]);
+  run(root, ["--query", "zephyr widget"]);
   const before = withDb(root, (database) => Object.fromEntries(database.prepare("SELECT path, mtime_ms, size FROM files").all().map((r) => [r.path, `${r.mtime_ms}:${r.size}`])));
   const b = join(root, "svc-a/doc/specs/b.md");
-  writeFileSync(b, readFileSync(b, "utf8") + "\nwombat\n");
+  writeFileSync(b, "# Beta service wombat kudu\n\n**Goal:** zephyr widget for the beta service.\n\nDeep in the body a zephyr appears.\n");
   utimesSync(b, new Date(), new Date(Date.now() + 5000));
-  assert.deepEqual(paths(run(root, ["--query", "wombat"])), ["svc-a/doc/specs/b.md"]);
+  assert.deepEqual(paths(run(root, ["--query", "wombat kudu"])), ["svc-a/doc/specs/b.md"]);
   const after = withDb(root, (database) => Object.fromEntries(database.prepare("SELECT path, mtime_ms, size FROM files").all().map((r) => [r.path, `${r.mtime_ms}:${r.size}`])));
   assert.equal(after["doc/specs/a.md"], before["doc/specs/a.md"]);
   assert.notEqual(after["svc-a/doc/specs/b.md"], before["svc-a/doc/specs/b.md"]);
   const count = (root, sql, path) => withDb(root, (database) => Object.values(database.prepare(sql).get(path))[0]);
   assert.equal(count(root, "SELECT count(*) FROM specs WHERE path = ?", "svc-a/doc/specs/b.md"), 1);
   rmSync(b);
-  run(root, ["--query", "zephyr"]);
+  run(root, ["--query", "zephyr widget"]);
   assert.equal(count(root, "SELECT count(*) FROM specs WHERE path = ?", "svc-a/doc/specs/b.md"), 0);
   assert.equal(count(root, "SELECT count(*) FROM files WHERE path = ?", "svc-a/doc/specs/b.md"), 0);
 });
@@ -89,71 +115,70 @@ test("3: incremental refresh updates only the edited row; delete removes rows",
 test("4: schema_version mismatch rebuilds the db", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  run(root, ["--query", "zephyr"]);
+  run(root, ["--query", "zephyr widget"]);
   withDb(root, (database) => database.prepare("UPDATE meta SET value = '999' WHERE key = 'schema_version'").run());
-  const r = run(root, ["--query", "zephyr"]);
+  const r = run(root, ["--query", "zephyr widget"]);
   assert.equal(r.status, 0, r.stderr);
   assert.equal(paths(r).length, 2);
-  assert.equal(withDb(root, (database) => database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get().value), "1");
+  assert.equal(withDb(root, (database) => database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get().value), "3");
 });
 
 test("5: a non-SQLite database is rebuilt", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
   write(root, ".pi/gauntlet/index.sqlite", "not a sqlite database");
-  const r = run(root, ["--query", "zephyr"]);
+  const r = run(root, ["--query", "zephyr widget"]);
   assert.equal(r.status, 0, r.stderr);
   assert.deepEqual(paths(r), ["doc/specs/a.md", "svc-a/doc/specs/b.md"]);
-  assert.equal(withDb(root, (database) => database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get().value), "1");
+  assert.equal(withDb(root, (database) => database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get().value), "3");
 });
 
 test("6: telemetry join is output-only and tolerant", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  run(root, ["--query", "zephyr"]);
+  run(root, ["--query", "zephyr widget"]);
   const filesBefore = withDb(root, (database) => JSON.stringify(database.prepare("SELECT * FROM files ORDER BY path").all()));
   write(root, "x", "x\n");
   write(root, "y", "y\n");
   write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: shipped\nshipped_at: 2026-09-17T10:00:00Z\nderived:\n  modified_files:\n    - x\n    - y\n");
-  let r = run(root, ["--query", "zephyr"]);
-  assert.deepEqual(r.rows[0].slice(4, 7), ["shipped", "2026-09-17T10:00:00Z", "x;y"]);
-  assert.equal(r.rows[0].length, 8);
-  assert.equal(r.rows[1][6], "");
+  let r = run(root, ["--query", "zephyr widget"]);
+  assert.deepEqual(r.rows[0].slice(4, 8), ["shipped", "2026-09-17T10:00:00Z", "live", "x;y"]);
+  assert.equal(r.rows[0].length, 9);
+  assert.equal(r.rows[1][7], "");
   assert.equal(withDb(root, (database) => JSON.stringify(database.prepare("SELECT * FROM files ORDER BY path").all())), filesBefore);
   write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: in_progress\nshipped_at: 2026-09-18T10:00:00Z\n");
-  r = run(root, ["--query", "zephyr"]);
-  assert.deepEqual(r.rows[0].slice(4, 7), ["in_progress", "2026-09-18T10:00:00Z", "missing"]);
+  r = run(root, ["--query", "zephyr widget"]);
+  assert.deepEqual(r.rows[0].slice(4, 8), ["in_progress", "2026-09-18T10:00:00Z", "live", "missing"]);
   write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: [unclosed\n");
-  r = run(root, ["--query", "zephyr"]);
+  r = run(root, ["--query", "zephyr widget"]);
   assert.equal(r.status, 0);
-  assert.deepEqual(r.rows[0].slice(4, 7), ["", "", ""]);
+  assert.deepEqual(r.rows[0].slice(4, 8), ["", "", "live", ""]);
   assert.match(r.stderr, /a\.yaml/);
 });
 
 test("6b: files cell is the AC fixture - present paths kept, gone paths dropped, no list is missing", (t) => {
-  const root = mkdtempSync(join(tmpdir(), "gsi-"));
+  const root = gitRepo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  spawnSync("git", ["init", "-q"], { cwd: root });
-  write(root, "doc/specs/a.md", "# Alpha quokka\n\n**Goal:** quokka.\n");
-  write(root, "doc/specs/b.md", "# Beta quokka\n\n**Goal:** quokka too.\n");
+  write(root, "doc/specs/a.md", "# Alpha quokka wallaby\n\n**Goal:** quokka.\n");
+  write(root, "doc/specs/b.md", "# Beta quokka wallaby\n\n**Goal:** quokka too.\n");
+  for (const n of ["one", "two", "three"]) write(root, `doc/specs/filler-${n}.md`, filler(n));
   write(root, "src/x.ts", "export {};\n");
   write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: shipped\nderived:\n  modified_files:\n    - src/x.ts\n    - src/gone.ts\n");
   write(root, ".pi/gauntlet/telemetry/doc/specs/b.yaml", "status: shipped\n");
-  spawnSync("git", ["add", "-A"], { cwd: root });
-  spawnSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "fixture"], { cwd: root });
-  const r = run(root, ["--query", "quokka"]);
+  commit(root);
+  const r = run(root, ["--query", "quokka wallaby"]);
   assert.equal(r.status, 0, r.stderr);
-  const cells = Object.fromEntries(r.rows.map((row) => [row[1], row[6]]));
+  const cells = Object.fromEntries(r.rows.map((row) => [row[1], row[7]]));
   assert.equal(cells["doc/specs/a.md"], "src/x.ts");
   assert.equal(cells["doc/specs/b.md"], "missing");
-  for (const row of r.rows) assert.equal(row.length, 8);
+  for (const row of r.rows) assert.equal(row.length, 9);
 });
 
 test("6c: files cell edge cases - order, spaces kept, all gone, non-array, null record", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
   const yaml = ".pi/gauntlet/telemetry/doc/specs/a.yaml";
-  const files = () => run(root, ["--query", "zephyr"]).rows[0][6];
+  const files = () => run(root, ["--query", "zephyr widget"]).rows[0][7];
   write(root, "b.js", "");
   write(root, "a.js", "");
   write(root, "sp  aced.txt", "");
@@ -162,7 +187,7 @@ test("6c: files cell edge cases - order, spaces kept, all gone, non-array, null
   write(root, "tab\there.js", "");
   write(root, yaml, 'status: shipped\nderived:\n  modified_files:\n    - a.js\n    - "tab\\there.js"\n');
   assert.equal(files(), "a.js;tab here.js");
-  assert.equal(run(root, ["--query", "zephyr"]).rows[0].length, 8);
+  assert.equal(run(root, ["--query", "zephyr widget"]).rows[0].length, 9);
   write(root, yaml, "status: shipped\nderived:\n  modified_files:\n    - 'sp  aced.txt'\n    - 7\n");
   assert.equal(files(), "sp  aced.txt");
   write(root, yaml, "status: shipped\nderived:\n  modified_files:\n    - nope1\n    - nope2\n");
@@ -178,45 +203,358 @@ test("6c: files cell edge cases - order, spaces kept, all gone, non-array, null
 test("7: query sanitising tolerates embedded quotes", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  write(root, "doc/specs/q.md", '# Quotes\n\nfoo"bar and "plain" words\n');
-  let r = run(root, ["--query", 'foo"bar']);
+  write(root, "doc/specs/q.md", '# Quotes foo"bar ocelot\n\n**Goal:** "plain" ocelot words\n');
+  let r = run(root, ["--query", 'foo"bar ocelot']);
   assert.equal(r.status, 0, r.stderr);
   assert.ok(paths(r).includes("doc/specs/q.md"));
-  r = run(root, ["--query", '"plain"']);
+  r = run(root, ["--query", '"plain" ocelot']);
   assert.equal(r.status, 0, r.stderr);
   assert.ok(paths(r).includes("doc/specs/q.md"));
 });
 
-test("8: one line per hit, eight tab-separated fields, whitespace collapsed", (t) => {
+test("8: one line per hit, nine tab-separated fields, whitespace collapsed", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  write(root, "doc/specs/t.md", "# Tab\tin\ttitle narwhal\n\nbody narwhal\nline two\twith tab narwhal\r\nmore\n");
-  const r = run(root, ["--query", "narwhal"]);
-  assert.equal(r.header.length, 8);
+  write(root, "doc/specs/t.md", "# Tab\tin\ttitle narwhal manatee\n\n**Goal:** narwhal manatee.\n\nbody narwhal\nline two\twith tab narwhal\r\nmore\n");
+  const r = run(root, ["--query", "narwhal manatee"]);
+  assert.deepEqual(r.header, HEADER);
   assert.equal(r.rows.length, 1);
-  assert.equal(r.rows[0].length, 8);
-  assert.equal(r.rows[0][3], "Tab in title narwhal");
+  assert.equal(r.rows[0].length, 9);
+  assert.equal(r.rows[0][3], "Tab in title narwhal manatee");
 });
 
-test("9: supersession banner is plain body text", (t) => {
+test("9: state is superseded only for a `- fully` banner in the title block", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
-  write(root, "doc/specs/old.md", "# Old\n\n> **Superseded by:** [doc/specs/a.md](./a.md) - fully\n\nplatypus\n");
-  const r = run(root, ["--query", "Superseded"]);
-  assert.deepEqual(paths(r), ["doc/specs/old.md"]);
-  assert.deepEqual(r.rows[0].slice(4, 7), ["", "", ""]);
-  assert.deepEqual(r.header, ["score", "path", "service", "title", "status", "shipped_at", "files", "snippet"]);
+  const banner = "> **Superseded by:** [doc/specs/a.md](./a.md) - fully";
+  write(root, "doc/specs/old-fully.md", `# Old kestrel marmot\n\n${banner}\n\n**Goal:** kestrel marmot.\n`);
+  write(root, "doc/specs/old-trailing.md", `# Old trailing\n\n${banner} \n`);
+  write(root, "doc/specs/blank-title.md", "# \n\nbody\n");
+  write(root, "doc/specs/old-prose.md", `# Old two\n\n> Historical note kept for context.\n${banner}\n`);
+  write(root, "doc/specs/old-section.md", '# Old three\n\n> **Superseded by:** [doc/specs/a.md](./a.md) - "Design" section only\n');
+  write(root, "doc/specs/old-semicolon.md", `# Old four\n\n${banner}; see also b\n`);
+  write(root, "doc/specs/old-fenced.md", `# Old five\n\n\`\`\`markdown\n${banner}\n\`\`\`\n`);
+  write(root, "doc/specs/old-h2.md", `# Old six\n\n## History\n\n${banner}\n`);
+  write(root, "doc/specs/old-h3.md", `# Old seven\n\n### Detail\n\n${banner}\n`);
+  const r = run(root, ["--query", "kestrel marmot"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.header, HEADER);
+  assert.equal(r.header[6], "state");
+  assert.deepEqual(paths(r), ["doc/specs/old-fully.md"]);
+  assert.equal(r.rows[0][6], "superseded");
+  const states = withDb(root, (database) => Object.fromEntries(database.prepare("SELECT path, state FROM specs WHERE path LIKE 'doc/specs/old-%'").all().map((row) => [row.path, row.state])));
+  assert.deepEqual(states, {
+    "doc/specs/old-fully.md": "superseded",
+    "doc/specs/old-trailing.md": "live",
+    "doc/specs/old-prose.md": "superseded",
+    "doc/specs/old-section.md": "live",
+    "doc/specs/old-semicolon.md": "live",
+    "doc/specs/old-fenced.md": "live",
+    "doc/specs/old-h2.md": "live",
+    "doc/specs/old-h3.md": "superseded",
+  });
+  assert.equal(withDb(root, (database) => database.prepare("SELECT state FROM specs WHERE path = 'doc/specs/a.md'").get().state), "live");
+  assert.equal(withDb(root, (database) => database.prepare("SELECT title FROM specs WHERE path = 'doc/specs/blank-title.md'").get().title), "blank-title");
 });
 
 test("10: usage errors exit 1, environment errors exit 2", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
   assert.equal(run(root, []).status, 1);
-  assert.equal(run(root, ["--query", "zephyr", "--limit", "0"]).status, 1);
-  assert.equal(run(root, ["--query", "zephyr", "--limit", "x"]).status, 1);
-  assert.equal(run(root, ["--query", "zephyr", "--json"]).status, 1);
+  assert.equal(run(root, ["--query", "zephyr widget", "--limit", "0"]).status, 1);
+  assert.equal(run(root, ["--query", "zephyr widget", "--limit", "x"]).status, 1);
+  assert.equal(run(root, ["--query", "zephyr widget", "--json"]).status, 1);
+  assert.equal(run(root, ["--query", "zephyr widget", "--exclude"]).status, 1);
   assert.equal(run(root, ["--query", "a"]).status, 1);
   const bare = mkdtempSync(join(tmpdir(), "gsi-bare-"));
   t.after(() => rmSync(bare, { recursive: true, force: true }));
-  assert.equal(run(bare, ["--query", "zephyr"]).status, 2);
+  assert.equal(run(bare, ["--query", "zephyr widget"]).status, 2);
+});
+
+test("11: AC1 fixture - exactly the strong row; no-match and all-common queries return header only", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const common = (n) => `# Plain spec ${n}\n\n**Goal:** plain goal ${n}.\n\nThe body mentions the common shared vocabulary.\n`;
+  write(root, "doc/specs/strong.md", "# Strong heron ibis\n\n**Goal:** heron ibis jackal.\n\nbody\n");
+  for (let n = 1; n <= 5; n++) write(root, `doc/specs/p${n}.md`, common(n));
+  commit(root);
+  const strong = run(root, ["--query", "heron ibis jackal common", "--limit", "10"]);
+  assert.equal(strong.status, 0, strong.stderr);
+  assert.deepEqual(paths(strong), ["doc/specs/strong.md"]);
+  for (const q of ["yeti unicorn", "common shared"]) {
+    const r = run(root, ["--query", q]);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.header, HEADER);
+    assert.deepEqual(r.rows, []);
+  }
+});
+
+test("12: evidence identity - stem variants of one word are one term", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/cfg.md", "# Configuration lemur index\n\n**Goal:** configure the lemur index.\n\nbody\n");
+  for (const q of ["configuration configuration", "Configuration configure", "index indexing"]) {
+    const r = run(root, ["--query", q]);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.rows, [], q);
+  }
+  assert.deepEqual(paths(run(root, ["--query", "configuration lemur"])), ["doc/specs/cfg.md"]);
+});
+
+test("13: ratio - a row far below the best live score is dropped; an equal pair is kept", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/r1.md", "# Otter pangolin vole yak emu dingo\n\n**Goal:** otter pangolin vole yak emu dingo.\n\nbody\n");
+  write(root, "doc/specs/r2.md", "# Otter pangolin service\n\n**Goal:** otter pangolin.\n\nbody\n");
+  write(root, "doc/specs/weak-super.md", "# Otter pangolin service archive\n\n> **Superseded by:** [doc/specs/r1.md](./r1.md) - fully\n\n**Goal:** otter pangolin.\n\nbody\n");
+  write(root, "doc/specs/e1.md", "# Quail raccoon\n\n**Goal:** quail raccoon.\n\nbody\n");
+  write(root, "doc/specs/e2.md", "# Quail raccoon\n\n**Goal:** quail raccoon.\n\nbody\n");
+  const r = run(root, ["--query", "otter pangolin vole yak emu dingo"]);
+  assert.deepEqual(paths(r), ["doc/specs/r1.md"]);
+  const pair = run(root, ["--query", "quail raccoon"]);
+  assert.deepEqual(paths(pair).sort(), ["doc/specs/e1.md", "doc/specs/e2.md"]);
+  assert.equal(pair.rows[0][0], pair.rows[1][0]);
+});
+
+test("14: superseded rows sort after live rows and never set the ratio bar", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/old.md", "# Otter pangolin vole yak emu dingo\n\n> **Superseded by:** [doc/specs/new.md](./new.md) - fully\n\n**Goal:** otter pangolin vole yak emu dingo.\n");
+  write(root, "doc/specs/new.md", "# Otter pangolin service\n\n**Goal:** otter pangolin.\n\nbody\n");
+  const r = run(root, ["--query", "otter pangolin vole yak emu dingo"]);
+  assert.deepEqual(paths(r), ["doc/specs/new.md", "doc/specs/old.md"]);
+  assert.deepEqual(r.rows.map((row) => row[6]), ["live", "superseded"]);
+  assert.ok(Math.abs(Number(r.rows[1][0])) > Math.abs(Number(r.rows[0][0])));
+  assert.deepEqual(paths(run(root, ["--query", "otter pangolin vole yak emu dingo", "--limit", "1"])), ["doc/specs/new.md"]);
+  assert.deepEqual(paths(run(root, ["--query", "vole yak"])), ["doc/specs/old.md"]);
+});
+
+test("15: --exclude removes a path before the filter so it never sets the bar", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/self.md", "# Sloth tapir vole yak emu dingo\n\n**Goal:** sloth tapir vole yak emu dingo.\n\nbody\n");
+  write(root, "doc/specs/pred.md", "# Sloth tapir service\n\n**Goal:** sloth tapir.\n\nbody\n");
+  const q = ["--query", "sloth tapir vole yak emu dingo"];
+  assert.deepEqual(paths(run(root, q)), ["doc/specs/self.md"]);
+  assert.deepEqual(paths(run(root, [...q, "--exclude", "doc/specs/self.md"])), ["doc/specs/pred.md"]);
+  assert.deepEqual(paths(run(root, [...q, "--exclude", "doc/specs/nope.md"])), ["doc/specs/self.md"]);
+});
+
+test("16: punctuation splits into distinct evidence terms and query order does not change rows", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/cfg.md", "# Configuration lemur index\n\n**Goal:** configure the lemur index.\n\nbody\n");
+  write(root, "doc/specs/cf.md", "# Config file lynx\n\n**Goal:** config file.\n\nbody\n");
+  for (let n = 1; n <= 5; n++) write(root, `doc/specs/p${n}.md`, `# Plain spec ${n}\n\n**Goal:** plain goal ${n}.\n\nthe plain body\n`);
+  commit(root);
+  const common = run(root, ["--query", "the-lemur"]);
+  assert.equal(common.status, 0, common.stderr);
+  assert.deepEqual(common.header, HEADER);
+  assert.deepEqual(common.rows, []);
+  const distinct = run(root, ["--query", "configuration-lemur"]);
+  assert.equal(distinct.status, 0, distinct.stderr);
+  assert.deepEqual(paths(distinct), ["doc/specs/cfg.md"]);
+  assert.deepEqual(paths(run(root, ["--query", "config config-file"])), paths(run(root, ["--query", "config-file config"])));
+});
+
+test("D1: --corpus specs and omitted --corpus are byte-identical; nine columns", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const plain = run(root, ["--query", "zephyr widget"]);
+  const explicit = run(root, ["--query", "zephyr widget", "--corpus", "specs"]);
+  assert.equal(explicit.status, 0, explicit.stderr);
+  assert.equal(explicit.stdout, plain.stdout);
+  assert.deepEqual(explicit.header, HEADER);
+});
+
+test("D11: unknown --corpus exits 1 with usage", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const r = run(root, ["--query", "zephyr widget", "--corpus", "notes"]);
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /usage:/);
+  assert.equal(run(root, ["--query", "zephyr widget", "--corpus"]).status, 1);
+});
+
+test("D12: a schema 2 cache is rebuilt to 3 with both tables present", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  run(root, ["--query", "zephyr widget"]);
+  withDb(root, (database) => database.prepare("UPDATE meta SET value = '2' WHERE key = 'schema_version'").run());
+  const r = run(root, ["--query", "zephyr widget"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(withDb(root, (database) => database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get().value), "3");
+  const tables = withDb(root, (database) => database.prepare("SELECT name FROM sqlite_master WHERE name IN ('specs', 'docs') ORDER BY name").all().map((row) => row.name));
+  assert.deepEqual(tables, ["docs", "specs"]);
+  const cols = withDb(root, (database) => database.prepare("PRAGMA table_info(files)").all().map((row) => row.name));
+  assert.deepEqual(cols, ["corpus", "path", "mtime_ms", "size"]);
+});
+
+test("D10-specs: a `## ` line inside a code fence is not a heading", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/fenced.md", "# Fenced pelican\n\n**Goal:** pelican.\n\n```markdown\n## Not a heading pelican\n```\n\n## Real heading\n");
+  run(root, ["--query", "zephyr widget"]);
+  const h = withDb(root, (database) => database.prepare("SELECT headings FROM specs WHERE path = 'doc/specs/fenced.md'").get().headings);
+  assert.equal(h, "Real heading");
+});
+
+test("D2: docs include defaults and fixed exclusions", (t) => {
+  const root = docsRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const r = run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.header, DOCS_HEADER);
+  assert.deepEqual(paths(r), ["doc/guide.md"]);
+  assert.equal(r.rows[0].length, 4);
+  assert.deepEqual(docsPaths(root), ["README.md", ...[1, 2, 3, 4].map((n) => `doc/filler-${n}.md`), "doc/guide.md"]);
+  overrides(root, [".pi/**/*.md", ".worktrees/**/*.md", "doc/**/*.md"]);
+  assert.equal(run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]).status, 0);
+  assert.deepEqual(docsPaths(root), [".pi/gauntlet-overrides.md", ...[1, 2, 3, 4].map((n) => `doc/filler-${n}.md`), "doc/guide.md"]);
+  const two = gitRepo();
+  t.after(() => rmSync(two, { recursive: true, force: true }));
+  write(two, "doc/x.md", decoy);
+  write(two, "doc/y.md", decoy);
+  commit(two);
+  const tiny = run(two, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
+  assert.equal(tiny.status, 0, tiny.stderr);
+  assert.deepEqual(tiny.header, DOCS_HEADER);
+  assert.deepEqual(tiny.rows, []);
+});
+
+test("D3: shared confidence rejects common body-only hits", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/strong.md", "# Strong heron ibis\n\n## jackal\n\nbody\n");
+  for (let n = 1; n <= 5; n++) write(root, `doc/p${n}.md`, `# Plain doc ${n}\n\nThe body mentions the common shared vocabulary.\n`);
+  commit(root);
+  const r = run(root, ["--corpus", "docs", "--query", "heron ibis jackal common", "--limit", "10"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["doc/strong.md"]);
+});
+
+test("D4: no cross-corpus leakage", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/guide.md", "# zephyr widget guide\n\n## zephyr widget\n");
+  for (let n = 1; n <= 4; n++) write(root, `doc/filler-${n}.md`, docFiller(n));
+  assert.deepEqual(paths(run(root, ["--query", "zephyr widget"])), ["doc/specs/a.md", "svc-a/doc/specs/b.md"]);
+  const docs = run(root, ["--corpus", "docs", "--query", "zephyr widget"]);
+  assert.deepEqual(paths(docs), ["doc/guide.md"]);
+  assert.deepEqual(docs.header, DOCS_HEADER);
+});
+
+test("D5: independent cache refresh in both directions", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/guide.md", "# Guide\n\n## zephyr widget\n");
+  run(root, ["--query", "zephyr widget"]);
+  run(root, ["--corpus", "docs", "--query", "zephyr widget"]);
+  const files = () => withDb(root, (db) => Object.fromEntries(db.prepare("SELECT corpus, path, mtime_ms FROM files").all().map((r) => [`${r.corpus}:${r.path}`, r.mtime_ms])));
+  const before = files();
+  utimesSync(join(root, "doc/specs/a.md"), new Date(), new Date(Date.now() + 5000));
+  run(root, ["--corpus", "docs", "--query", "zephyr widget"]);
+  assert.deepEqual(files(), before);
+  run(root, ["--query", "zephyr widget"]);
+  assert.notEqual(files()["specs:doc/specs/a.md"], before["specs:doc/specs/a.md"]);
+  assert.equal(files()["docs:doc/guide.md"], before["docs:doc/guide.md"]);
+  assert.deepEqual(docsPaths(root), ["doc/guide.md"]);
+});
+
+test("D6: overrides replace defaults but cannot bypass exclusions", (t) => {
+  const root = docsRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "notes/a.md", decoy);
+  write(root, "CONTRIBUTING.md", decoy);
+  write(root, "svc/CONTRIBUTING.md", decoy);
+  write(root, "svc/doc/inner.md", decoy);
+  commit(root);
+  const search = () => run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
+  overrides(root, ["notes/**/*.md"]);
+  assert.equal(search().status, 0);
+  assert.deepEqual(docsPaths(root), ["notes/a.md"]);
+  overrides(root, ["**/*.md"]);
+  assert.equal(search().status, 0);
+  const all = docsPaths(root);
+  for (const p of ["doc/specs/a.md", "docs/specs/b.md", "doc/plans/p.md", "docs/plans/q.md", "node_modules/x/doc/a.md", "build/doc/b.md", "doc/draft.md", ".pi/gauntlet/n.md", ".worktrees/w/doc/g.md"]) assert.ok(!all.includes(p), p);
+  assert.ok(all.includes("doc/guide.md"));
+  overrides(root, ["CONTRIBUTING.md"]);
+  assert.equal(search().status, 0);
+  assert.deepEqual(docsPaths(root), ["CONTRIBUTING.md", "svc/CONTRIBUTING.md"]);
+  write(root, ".pi/gauntlet-overrides.md", "## Spec index\n\nno bullets here\n");
+  assert.equal(search().status, 0);
+  assert.ok(docsPaths(root).includes("doc/guide.md"));
+  assert.ok(docsPaths(root).includes("svc/doc/inner.md"));
+});
+
+test("D6b: overrides file resolution order", (t) => {
+  const root = docsRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/gauntlet-overrides.md", "## Spec index\n- docs: `notes/**/*.md`\n");
+  write(root, "notes/a.md", decoy);
+  const search = () => run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
+  assert.equal(search().status, 0);
+  assert.deepEqual(docsPaths(root), ["notes/a.md"]);
+  write(root, "gauntlet-overrides.md", "## Spec index\n- docs: `other/**/*.md`\n");
+  write(root, "other/b.md", decoy);
+  assert.equal(search().status, 0);
+  assert.deepEqual(docsPaths(root), ["other/b.md"]);
+  overrides(root, ["doc/**/*.md"]);
+  assert.equal(search().status, 0);
+  assert.deepEqual(docsPaths(root), ["doc/filler-1.md", "doc/filler-2.md", "doc/filler-3.md", "doc/filler-4.md", "doc/gauntlet-overrides.md", "doc/guide.md"]);
+});
+
+test("D7: heading hits are strong, body-only hits are not", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/h.md", "# H\n\n## Setup\n\n## Feeding the kudu wombat\n\nprose\n");
+  write(root, "doc/b.md", "# B\n\n## Setup\n\nkudu wombat in the body only\n");
+  for (let n = 1; n <= 4; n++) write(root, `doc/filler-${n}.md`, docFiller(n));
+  commit(root);
+  const r = run(root, ["--corpus", "docs", "--query", "kudu wombat"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["doc/h.md"]);
+});
+
+test("D8: snippet selects heading line or body fallback", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const longHeading = "Feeding the wandering herds across twelve distant valleys before finally finding the kudu wombat";
+  write(root, "doc/h.md", `# H\n\n## Setup\n\n## ${longHeading}\n\nprose\n`);
+  write(root, "doc/t.md", "# lynx ocelot title\n\n## Unrelated\n\nbody says lynx ocelot here\n");
+  for (let n = 1; n <= 4; n++) write(root, `doc/filler-${n}.md`, docFiller(n));
+  commit(root);
+  const heading = run(root, ["--corpus", "docs", "--query", "kudu wombat"]);
+  assert.deepEqual(paths(heading), ["doc/h.md"]);
+  assert.equal(heading.rows[0][3], longHeading);
+  const body = run(root, ["--corpus", "docs", "--query", "lynx ocelot"]);
+  assert.deepEqual(paths(body), ["doc/t.md"]);
+  assert.match(body.rows[0][3], /body says lynx ocelot/);
+  assert.doesNotMatch(body.rows[0][3], /[\u0001\u0002]/);
+});
+
+test("D9: deleted files and symlinks are skipped, stale rows removed", (t) => {
+  const root = docsRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/gone.md", "# Gone\n\n## ptarmigan gannet\n");
+  commit(root);
+  run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
+  assert.ok(docsPaths(root).includes("doc/gone.md"));
+  rmSync(join(root, "doc/gone.md"));
+  symlinkSync(join(root, "doc/specs/a.md"), join(root, "doc/link.md"));
+  symlinkSync(join(root, "doc/nowhere.md"), join(root, "doc/dangling.md"));
+  const r = run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["doc/guide.md"]);
+  for (const p of ["doc/gone.md", "doc/link.md", "doc/dangling.md"]) assert.ok(!docsPaths(root).includes(p), p);
+  assert.equal(withDb(root, (db) => db.prepare("SELECT count(*) AS c FROM files WHERE corpus = 'docs' AND path = 'doc/gone.md'").get().c), 0);
+});
+
+test("D10: fenced headings and shorter nested fences are ignored", (t) => {
+  const root = docsRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/f.md", "# F\n\n```\n## kudu wombat\n```\n\nbody\n");
+  write(root, "doc/nested.md", "# N\n\n````markdown\n```js\n## inner heading\n```\n## still fenced\n````\n");
+  run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
+  for (const p of ["doc/f.md", "doc/nested.md"]) assert.equal(withDb(root, (db) => db.prepare("SELECT headings FROM docs WHERE path = ?").get(p).headings), "");
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.21.0",
+  "version": "5.23.0",
   "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

@@ -44,7 +44,7 @@ Work through the items below **in order**. This is your own checklist to follow,
 4. **Understand the idea against the draft** - see [Understand the idea](#3-understand-the-idea).
 5. **Propose 2-3 approaches** - see [Explore approaches](#4-explore-approaches).
 6. **Present the design** - see [Present the design in two rounds](#6-present-the-design-in-two-rounds).
-7. **Write the spec** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate) steps 1-4.
+7. **Write the spec** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate) steps 1-5.
 8. **Spec self-review (lint)** - run the inline checks in [Spec Self-Review](#spec-self-review-before-user-review-gate).
 9. **Critique pass (auto-dispatched)** - use [Spec Council](#spec-council-optional).
 10. **Re-run placeholder scan** - follow [Spec Self-Review](#spec-self-review-before-user-review-gate).
@@ -104,7 +104,7 @@ Prefer clear testable boundaries, YAGNI, existing conventions, the owning schema
 
 ### 6. Present the design in two rounds
 
-Use two rounds, targeting 300-500 words each, with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`.
+Use two rounds, targeting 300-500 words each, with one approval each; revisions remain within that approval point. Ask once per round; round-1 approval without correction confirms the predecessor. Round 1 covers architecture, responsibilities, data flow, and `supersedes <path>, <scope>` when applicable. Round 2 covers errors, edges, tests, and `## Documentation impact`. In round 2, cite the draft's `Docs touched:` entries as candidates for "Materially amended existing docs"; admit or drop each by the materiality bar in `reference/documentation-impact.md`, never list them automatically.
 
 `## Documentation impact` is required. Cite `reference/documentation-impact.md` by relative path, do not restate its categories, and reproduce this template verbatim:
 
@@ -163,7 +163,21 @@ Spec-writing replaces the context draft, in this exact order:
    `# 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.
-4. **After the line-1 check and before the inline lint**, `edit` any known
+4. **After the line-1 check**, run the second predecessor pass. Compose a query from
+   the spec's H1 terms, then the terms of every H2 that is not a template heading
+   (Problem, Acceptance criteria, Design, Errors and edge cases, Tests, Documentation
+   impact, Out of scope, Open questions), then the `**Goal:**` line's terms - same
+   token rules as the scout, deduplicated, cut at 15. Run
+   `(cd <abs worktree path> && node <SPEC_INDEX> --query '<terms>' --limit 5 --exclude <spec path relative to the worktree>)`
+   with `<SPEC_INDEX>` resolved as in `gatherer.md`. Take the `live` rows and drop every
+   path the draft's `Predecessor:` line(s) named (retained from the step-1 read). Carry
+   the remainder to the gate as one adjacent line:
+   `New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.`
+   or `New predecessor candidates at spec-writing: none.` A non-zero exit degrades to
+   `Second predecessor pass unavailable: <first stderr line>`; it never blocks the gate
+   or the commit. "yes, <path> is a predecessor" at the gate is a change request that
+   adds the `supersedes <path>, <scope>` clause and the banner, then re-presents the gate.
+5. **After the second predecessor pass and before the inline lint**, `edit` any known
    predecessor spec to insert its supersession banner (see
    [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.
@@ -244,6 +258,7 @@ Rejected: [<severity>] <cluster> — raised-by: [<slugs>] -> <one-line reason>
 (one line per item, exactly as returned by roasting-the-spec - `Applied: none` / `Deferred: none` / `Rejected: none` when a list is empty; omit the audit lines when the worker path ran, not the council)
 
 <unresolved ambiguities; every gap-footer entry from the summary>
+New predecessor candidates at spec-writing: <path> (<title>), ... - index rows are a hint; code is the source and an absent row proves nothing.
 
 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. Reply "auto-apply amends" - every later amend-class change in this flow then applies without review, scope changes included; redraws and the spec gate still stop. "approve, auto-apply amends" does both.
 ```
@@ -288,6 +303,7 @@ One question at a time, YAGNI, 2-3 approaches, two design rounds, clarify freely
 - Proposed-change execution before approval ([owner](#hard-constraint)).
 - Plan before approval; brainstorming invocation for an amend ([owner](#user-review-gate)).
 - Missing predecessor banner; invalid multi-spec split ([owner](#spec-self-review-before-user-review-gate); [owner](#2-scope-check)).
+- Gate reached without the second predecessor pass ([owner](#spec-self-review-before-user-review-gate)).
 - Approaches while a contradicted premise remains unresolved ([owner](#3-understand-the-idea)).
 - Amend without `reference/amendment-surface.md`; waiting after an amend grant; auto-applying a redraw ([owner](#amending-an-approved-spec)).
 

package/skills/brainstorming/gatherer.md

@@ -53,11 +53,13 @@ Scout (always dispatched):
 > 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 request is only a ticket reference, take the terms from the ticket title and body 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
+> list; zero rows means the index found no evidence, not that no predecessor exists -
+> judge `Predecessor: none` from the code recon. 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
@@ -67,7 +69,8 @@ Scout (always dispatched):
 > Judge by topic; shared file paths never decide.
 > The `files` column of each candidate row is the `;`-separated list of repo-relative
 > paths that predecessor's ship modified and that still exist, or the literal `missing`,
-> or blank; do not recompute it from git or telemetry. After the `Predecessor:` line(s),
+> or blank; do not recompute it from git or telemetry. The `state` column is `live` or
+> `superseded`; cite a `superseded` row only through its successor. After the `Predecessor:` line(s),
 > and only when at least one predecessor is named, render a `Predecessor anchors`
 > section: list every attributed path exactly once, attributed to the first named
 > predecessor in index output order whose cell lists it, with no per-path commentary
@@ -79,7 +82,22 @@ Scout (always dispatched):
 > from the directory-listing fallback) contributes no path and no `missing` line. When
 > no path and no `missing` line results - including whenever the index was unavailable -
 > omit the section entirely; `Predecessor: none` produces no anchors section. The anchors
-> are a recon hint, never a selection input. End with an
+> are a recon hint, never a selection input.
+> Docs check: run `node <SPEC_INDEX> --corpus docs --query '<the same keywords>' --limit 10`
+> from the worktree root. Its rows are project documentation that already speaks about the
+> request's topic; open at most five whose topic matches and let them inform the "already
+> solves this?" finding and the current-contract recon. If the command fails, write
+> `Docs index unavailable - docs check used recon only.` in your handoff and continue. After
+> the `Predecessor:` line(s) and any `Predecessor anchors` section, render at most
+> five `Docs touched: <path> - <section heading>` lines, one per document that
+> genuinely covers the request's topic - an opened index row or a document your own
+> recon found - where
+> `<section heading>` is the `##`/`###` heading of the covering section as read in the
+> document (the row's `snippet` column is a hint to it), or the document title when no single
+> section applies; or `Docs touched: none`. Judge by topic; a lexical hit alone is not
+> coverage. Zero rows means the index found no evidence, not that no document covers the
+> topic. This query supplements the code and documentation recon you already perform; it
+> never replaces it - keep reading the files the request touches. End with an
 > "Open questions that matter for the spec"
 > section. Compact handoff, not a dump.