pi-gauntlet 5.21.0 → 5.22.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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 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] [--exclude <repo-relative path>]...`; it requires Node >=24.15.0, refreshes its FTS5 index on every query, and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `state`, `files`, and `snippet` columns. Rows pass a confidence rule before `--limit` applies: a query term is evidence when it occurs in fewer than half the indexed specs (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 its `title` or `goal`, and rows scoring below half the best live row's score are dropped. A query with no real match therefore prints the header only and exits 0, and a corpus of two or fewer specs 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 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`. `/skill:brainstorming` queries the index 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.
 
 ## Performance digest
 

package/bin/gauntlet-spec-index.mjs

@@ -7,22 +7,28 @@ import { execFileSync } from "node:child_process";
 import process from "node:process";
 import { parse as parseYaml } from "yaml";
 
-const SCHEMA_VERSION = 1;
+const SCHEMA_VERSION = 2;
+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 HEADER = ["score", "path", "service", "title", "status", "shipped_at", "state", "files", "snippet"];
 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 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');
 `;
 
 const usage = () => {
-  process.stderr.write('usage: gauntlet-spec-index --query "<text>" [--limit N]\n');
+  process.stderr.write('usage: gauntlet-spec-index --query "<text>" [--limit N] [--exclude <repo-relative path>]...\n');
   process.exit(1);
 };
 const die = (msg) => {
@@ -33,13 +39,15 @@ const die = (msg) => {
 function parseArgs(argv) {
   let query;
   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] === "--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, limit, exclude };
 }
 
 function nodeOk() {
@@ -139,10 +147,19 @@ async function openDb(root) {
 
 function extract(text, path) {
   const lines = text.split(/\r?\n/);
-  const title = lines.find((l) => l.startsWith("# "))?.slice(2).trim() || basename(path, ".md");
+  const h1 = lines.findIndex((l) => 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 };
+  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) || /^\s*(`{3,}|~{3,})/.test(l)) break;
+      if (FULLY_BANNER.test(l)) { state = "superseded"; break; }
+    }
+  }
+  return { title, goal, headings, state };
 }
 
 function refresh(db, root, corpus) {
@@ -150,7 +167,7 @@ function refresh(db, root, corpus) {
   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 insSpec = db.prepare("INSERT INTO specs (path, service, title, goal, headings, body, state) VALUES (?, ?, ?, ?, ?, ?, ?)");
   const putFile = db.prepare("INSERT OR REPLACE INTO files (path, mtime_ms, size) VALUES (?, ?, ?)");
   db.exec("BEGIN IMMEDIATE");
   try {
@@ -162,7 +179,7 @@ function refresh(db, root, corpus) {
       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);
+      insSpec.run(f.path, f.service, x.title, x.goal, x.headings, text, x.state);
       putFile.run(f.path, f.mtime_ms, f.size);
     }
     db.exec("COMMIT");
@@ -172,8 +189,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 titleGoal = evidence.filter((e) => e.titleGoal.has(r.rowid)).length;
+    return hits >= MIN_EVIDENCE_TOKENS && titleGoal >= MIN_EVIDENCE_TOKENS;
+  });
+}
+
+function query(db, toks, { limit, exclude }) {
+  const n = db.prepare("SELECT count(*) AS n FROM specs").get().n;
+  const rowids = (match) => new Set(db.prepare("SELECT rowid FROM specs WHERE specs 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, titleGoal: rowids(`title:${quote(tok)} OR goal:${quote(tok)}`) });
+  }
+  if (evidence.length < MIN_EVIDENCE_TOKENS) return [];
+  const rows = db.prepare(
+    `SELECT rowid, path, service, title, state,
+            bm25(specs, 0, 0, 10.0, 5.0, 2.0, 1.0, 0) AS score,
+            snippet(specs, 5, '', '', '...', 12) AS snippet
+     FROM specs WHERE specs MATCH ?`,
+  ).all(toMatch(terms)).filter((r) => !exclude.includes(r.path));
+  const kept = confidenceFilter(rows, evidence);
+  kept.sort((a, b) => (a.state !== "live") - (b.state !== "live") || a.score - b.score);
+  const best = kept.find((r) => r.state === "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: "" };
@@ -200,23 +267,17 @@ const filesCell = (v) => v.replace(/[\t\r\n]+/g, " ");
 
 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, limit, exclude } = parseArgs(process.argv.slice(2));
+  const toks = tokens(text);
+  if (!toks.length) usage();
   const root = repoRoot();
   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 rows = query(db, toks, { limit, exclude });
   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"));
+    out.push([...[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)].join("\t"));
   }
   process.stdout.write(out.join("\n") + "\n");
   db.close();

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

@@ -9,23 +9,35 @@ 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 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;
 };
 
@@ -47,41 +59,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 +99,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), "2");
 });
 
 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), "2");
 });
 
 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 +171,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 +187,156 @@ 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"])));
 });

package/package.json

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