pi-gauntlet 5.8.1 → 5.9.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.9.0 - 2026-09-17
+
+- Added `gauntlet-spec-index`, a build-on-query FTS5 search over root and one-level service spec corpora with a per-worktree cache and telemetry-enriched tabular results; brainstorming uses it to find predecessor specs. Requires Node >=24.15.0. (#34)
+
 ## v5.8.1 - 2026-09-17
 
 - chase-bug hotfix: the implementer proves its worktree binding first, addresses every mutating git command with `git -C`, runs with a fresh context, and the parent aborts non-destructively on any primary-checkout drift after each implementer return; `ci.mjs` asserts the guard text ([#36](https://github.com/jjuraszek/pi-gauntlet/issues/36))

package/README.md

@@ -116,6 +116,10 @@ pi install npm:pi-gauntlet
 
 Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. See [doc/install-internals.md](./doc/install-internals.md) for what the postinstall step actually does (symlink vs copy, `PI_GAUNTLET_AGENT_DIR`, upgrading from the pre-rename package).
 
+## 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 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`.
+
 For local development against a checkout instead of npm:
 
 ```bash

package/bin/gauntlet-spec-index.mjs

@@ -0,0 +1,223 @@
+#!/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";
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+import { parse as parseYaml } from "yaml";
+
+const SCHEMA_VERSION = 1;
+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 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,
+    tokenize = 'porter unicode61');
+`;
+
+const usage = () => {
+  process.stderr.write('usage: gauntlet-spec-index --query "<text>" [--limit N]\n');
+  process.exit(1);
+};
+const die = (msg) => {
+  process.stderr.write(`${msg}\n`);
+  process.exit(2);
+};
+
+function parseArgs(argv) {
+  let query;
+  let limit = 10;
+  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 usage();
+  }
+  if (query === undefined) usage();
+  return { query, limit };
+}
+
+function nodeOk() {
+  const cur = process.versions.node.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if (cur[i] !== MIN_NODE[i]) return cur[i] > MIN_NODE[i];
+  return true;
+}
+
+const git = (cwd, args) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+
+function repoRoot() {
+  try {
+    return git(process.cwd(), ["rev-parse", "--show-toplevel"]);
+  } catch {
+    return die("gauntlet-spec-index: not inside a git repository");
+  }
+}
+
+function discover(root) {
+  const out = [];
+  const seen = new Set();
+  const collect = (relDir, service) => {
+    const abs = join(root, relDir);
+    let real;
+    try {
+      real = realpathSync(abs);
+      if (!statSync(real).isDirectory()) return;
+    } catch {
+      return;
+    }
+    if (seen.has(real)) return;
+    seen.add(real);
+    for (const name of readdirSync(abs).sort()) {
+      if (!name.endsWith(".md")) continue;
+      const rel = `${relDir}/${name}`;
+      const st = statSync(join(root, rel));
+      if (st.isFile()) out.push({ path: rel, service, mtime_ms: Math.trunc(st.mtimeMs), size: st.size });
+    }
+  };
+  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);
+  }
+  return out;
+}
+
+function ensureExclude(root) {
+  const rel = git(root, ["rev-parse", "--git-path", "info/exclude"]);
+  const abs = isAbsolute(rel) ? rel : join(root, rel);
+  const cur = existsSync(abs) ? readFileSync(abs, "utf8") : "";
+  if (cur.split("\n").includes(EXCLUDE_LINE)) return;
+  mkdirSync(dirname(abs), { recursive: true });
+  appendFileSync(abs, `${cur.length && !cur.endsWith("\n") ? "\n" : ""}${EXCLUDE_LINE}\n`);
+}
+
+async function openDb(root) {
+  const { DatabaseSync } = await import("node:sqlite");
+  const dbPath = join(root, ".pi/gauntlet/index.sqlite");
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const fresh = !existsSync(dbPath);
+  const create = () => {
+    const db = new DatabaseSync(dbPath);
+    db.exec("PRAGMA busy_timeout = 2000");
+    try {
+      db.exec(SCHEMA);
+    } catch (e) {
+      if (/fts5/i.test(e.message)) die("gauntlet-spec-index: this Node's SQLite has no FTS5 module");
+      throw e;
+    }
+    db.prepare("INSERT OR REPLACE INTO meta VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+    return db;
+  };
+  const rebuild = (db) => {
+    try { db?.close(); } catch {}
+    for (const suffix of ["", "-journal", "-wal", "-shm"]) rmSync(dbPath + suffix, { force: true });
+    return create();
+  };
+  if (fresh) ensureExclude(root);
+  let db;
+  try {
+    db = new DatabaseSync(dbPath);
+    db.exec("PRAGMA busy_timeout = 2000");
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+    if (Number(row?.value) !== SCHEMA_VERSION) return rebuild(db);
+    return db;
+  } catch (e) {
+    const missingMeta = e?.code === "ERR_SQLITE_ERROR" && e.errcode === 1 && /no such table:\s*meta/i.test(e.message);
+    const corrupt = e?.code === "ERR_SQLITE_ERROR" && (e.errcode === 11 || e.errcode === 26);
+    if (missingMeta || corrupt) return rebuild(db);
+    try { db?.close(); } catch {}
+    throw e;
+  }
+}
+
+function extract(text, path) {
+  const lines = text.split(/\r?\n/);
+  const title = lines.find((l) => l.startsWith("# "))?.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 };
+}
+
+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 (?, ?, ?)");
+  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) {
+      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);
+    }
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  }
+}
+
+const toMatch = (query) =>
+  query.split(/\s+/).filter((t) => t.length >= 2).map((t) => `"${t.replaceAll('"', '""')}"`).join(" OR ");
+
+function telemetry(root, specPath) {
+  const blank = { status: null, shipped_at: null, files: null };
+  const p = join(root, ".pi/gauntlet/telemetry", specPath.replace(/\.md$/, ".yaml"));
+  if (!existsSync(p)) return blank;
+  let rec;
+  try {
+    rec = parseYaml(readFileSync(p, "utf8"));
+  } catch {
+    process.stderr.write(`gauntlet-spec-index: warning: unreadable telemetry ${p}\n`);
+    return blank;
+  }
+  if (!rec || typeof rec !== "object") return blank;
+  const mf = rec.derived?.modified_files;
+  return { status: rec.status ?? null, shipped_at: rec.shipped_at ?? null, files: Array.isArray(mf) ? mf.length : null };
+}
+
+const cell = (v) => (v === null || v === undefined ? "" : String(v).replace(/\s+/g, " ").trim());
+
+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 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 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, t.files, r.snippet].map(cell).join("\t"));
+  }
+  process.stdout.write(out.join("\n") + "\n");
+  db.close();
+}
+
+main().catch((e) => {
+  if (e?.code === "ERR_SQLITE_ERROR") die(`gauntlet-spec-index: ${e.message}`);
+  throw e;
+});

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

@@ -0,0 +1,173 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, utimesSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+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 write = (root, rel, text) => {
+  mkdirSync(join(root, dirname(rel)), { recursive: true });
+  writeFileSync(join(root, rel), text);
+};
+
+const repo = () => {
+  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`);
+  spawnSync("git", ["add", "-A"], { cwd: root });
+  spawnSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "fixture"], { cwd: 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")) };
+};
+const paths = (res) => res.rows.map((r) => r[1]);
+const withDb = (root, fn) => {
+  const database = new DatabaseSync(join(root, ".pi/gauntlet/index.sqlite"));
+  try {
+    return fn(database);
+  } finally {
+    database.close();
+  }
+};
+
+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"]);
+  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"]);
+  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) => {
+  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);
+});
+
+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"]);
+  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");
+  utimesSync(b, new Date(), new Date(Date.now() + 5000));
+  assert.deepEqual(paths(run(root, ["--query", "wombat"])), ["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"]);
+  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);
+});
+
+test("4: schema_version mismatch rebuilds the db", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  run(root, ["--query", "zephyr"]);
+  withDb(root, (database) => database.prepare("UPDATE meta SET value = '999' WHERE key = 'schema_version'").run());
+  const r = run(root, ["--query", "zephyr"]);
+  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");
+});
+
+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"]);
+  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");
+});
+
+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"]);
+  const filesBefore = withDb(root, (database) => JSON.stringify(database.prepare("SELECT * FROM files ORDER BY path").all()));
+  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", "2"]);
+  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", ""]);
+  write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: [unclosed\n");
+  r = run(root, ["--query", "zephyr"]);
+  assert.equal(r.status, 0);
+  assert.deepEqual(r.rows[0].slice(4, 7), ["", "", ""]);
+  assert.match(r.stderr, /a\.yaml/);
+});
+
+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']);
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(paths(r).includes("doc/specs/q.md"));
+  r = run(root, ["--query", '"plain"']);
+  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) => {
+  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);
+  assert.equal(r.rows.length, 1);
+  assert.equal(r.rows[0].length, 8);
+  assert.equal(r.rows[0][3], "Tab in title narwhal");
+});
+
+test("9: supersession banner is plain body text", (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"]);
+});
+
+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", "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);
+});

package/package.json

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

package/skills/brainstorming/SKILL.md

@@ -22,7 +22,7 @@ You **may**:
 - Read code and docs
 - Run the existing system to observe its **current** behaviour — this is research and feeds the spec (boot a local service, replay a sample request, capture a baseline classification, etc.)
 - Write to the project's `doc/specs/` directory
-- `edit` a predecessor spec in the project's spec directory to add a supersession banner (see [Marking superseded specs](#marking-superseded-specs)) — the `edit` prohibition at spec-writing binds the spec being written, not a predecessor file
+- `edit` a predecessor spec in the project's spec directory to add a supersession banner (see [Marking superseded specs](reference/superseding.md)) — the `edit` prohibition at spec-writing binds the spec being written, not a predecessor file
 
 You may **not**:
 
@@ -65,7 +65,7 @@ Work through the items below **in order**. This is your own checklist to follow,
    then state the chat premise note (section 3) before approaches
 5. **Propose 2-3 approaches** — with trade-offs and a recommendation
 6. **Present the design** — in two rounds, one approval each
-7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](#marking-superseded-specs), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
+7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](reference/superseding.md), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
 8. **Spec self-review (lint)** — placeholder scan + internal consistency + documentation named, run inline
 9. **Critique pass (auto-dispatched)** — scope + ambiguity; the spec council via `/skill:roasting-the-spec` when `gauntlet_setting` returns verdict `council` (it applies its apply-set, including any external-ref inlining, to the spec before returning — see [Spec Council](#spec-council-optional)), else a fresh `worker` that applies its own fixes in place
 10. **Re-run placeholder scan** — after the critique pass returns, re-scan the **applied** spec for placeholders its edits may have introduced; if a predecessor banner exists, confirm its `<scope>` still matches the applied spec (critique edits can change what is superseded); surface any ambiguity the critique could not safely resolve at the user gate
@@ -239,25 +239,6 @@ overwrite reuses the path. If the questionary invalidated the slug, rename at
 spec-writing: write the spec at the new path **and delete the old draft file**
 (nothing was committed, so this is free).
 
-## Marking superseded specs
-
-When the new spec replaces a prior spec — fully or in part — (from the draft's scout recon or the request), mark the predecessor. No mechanical sweep: grep or path-overlap hits never decide supersession.
-
-- `edit` the predecessor spec (in the project's spec directory, per [Project Routing](#project-routing)) to insert, after its title line and a blank line, one banner line per successor:
-
-  ```markdown
-  > **Superseded by:** [<repo-relative path to successor>](<href relative to THIS file>) - <scope>
-  ```
-
-- The visible label is the successor's repo-relative path; the href is computed relative to the predecessor's own directory (Markdown resolves links from the containing file). Same directory: `[doc/specs/B.md](./B.md)`.
-- `<scope>` is the value after the ` - ` separator: `fully`, or the named superseded section(s), e.g. `"Settings resolution" section only`. The scope value itself carries no leading dash — the template above already supplies the separator.
-- Banners are **append-only**: add below any existing supersession lines, formatted or free-form prose. One old spec may accumulate banners from multiple successors. No migration, no dedup.
-- **No transitive rewrite**: if A points at B and B is later superseded by C, A keeps pointing at B; the reader hops.
-- **Mark, never delete.** Delete/archive policy is consumer territory via overrides.
-- **Coverage limits**: unmarked does NOT mean current (code drift, abandoned designs, and partial ships produce no successor spec); marked does NOT mean dead (partial supersession leaves live sections).
-- Predecessor in a **different service's spec directory**: out of scope — record it in the new spec's Open Questions instead of editing outside the write grant.
-- **Override contract**: the gauntlet overrides file (see Project overrides) may replace the banner *syntax*; placement, append-only, no-transitive-rewrite, and mark-never-delete stay fixed. A syntax override entry must itself state the scout-citation guidance for its format (the shipped `gatherer.md` guidance names only the default banner).
-
 ## Spec Self-Review (Before User Review Gate)
 
 Spec-writing replaces the context draft, in this exact order:
@@ -273,7 +254,7 @@ Spec-writing replaces the context draft, in this exact order:
    guard is a backstop, not the primary check.
 4. **After the line-1 check and before the inline lint**, `edit` any known
    predecessor spec to insert its supersession banner (see
-   [Marking superseded specs](#marking-superseded-specs)). This position is fixed:
+   [Marking superseded specs](reference/superseding.md)). This position is fixed:
    the banner is written after any slug rename, so it always cites the final path.
 
 After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Convention](#filename-convention)) and before showing it to the user, run a self-review pass. **Read all five bullets first, then act:** only the **first three** run here at the main loop (the inline lint); the **last two** (scope + ambiguity) do **not** run inline — they are the dispatched critique pass (checklist item 9). Do not apply scope/ambiguity edits yourself.
@@ -328,7 +309,7 @@ subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs
 
 `<SUMMARY_PATH>` above is a placeholder in the dispatch object; it means substitute the value of the shell variable `$SUMMARY_PATH` set above. The steps below use `$SUMMARY_PATH` (the shell form) once the value is in hand.
 
-Then commit the spec — staging any predecessor spec edited per [Marking superseded specs](#marking-superseded-specs) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
+Then commit the spec — staging any predecessor spec edited per [Marking superseded specs](reference/superseding.md) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
 
 1. **From the dispatch tool result, before the `Read`.** If the result is **not** an `"Output saved to: <path> (<N> KB, <M> lines)"` reference (e.g. an exit-0 save error returns the full inline output plus an "Output file error" line — the prunable shape, no file to read), or the reference reports under ~500 bytes, or a size grossly disproportionate to the spec (under ~2% of its byte size), or over ~45 KB (the `Read` truncates at 50KB / 2000 lines, so a larger file cannot render whole) — skip the `Read` and take the degrade path. Use the reference's reported figures; do not re-derive them.
 2. **The `Read` itself, as the last content-producing tool call before composing the gate.** `Read` `$SUMMARY_PATH` and paste its contents verbatim at the top of the gate. If the `Read` fails, returns 0 bytes, or reports truncation — take the degrade path. The `Read` must be last: pi-condense does not protect a `/tmp` read, so any turn boundary between the `Read` and the render lets the ~9KB read result be pruned, reproducing the bug.

package/skills/brainstorming/gatherer.md

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

package/skills/brainstorming/reference/superseding.md

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