pi-gauntlet 5.20.0 → 5.22.0

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/bin/gauntlet-telemetry-seal.mjs

@@ -168,7 +168,7 @@ function derive(rec, now) {
   }
   for (const k of Object.keys(acc.phases)) phases[k] = compact({ ...phases[k] ?? {}, ...acc.phases[k] });
   const live = liveShipEvent(rec.events);
-  return compact({ duration_s: seconds(rec.created_at, rec.shipped_at ?? rec.abandoned_at ?? now), phases, personas: acc.personas, reviews: Object.keys(acc.reviews).length ? acc.reviews : void 0, conformance_loops: acc.conformance_loops, conformance_open_gaps: acc.conformance_open_gaps, gates: compact({ ...acc.gates, ship_option: live?.option }), plan: rec.derived.plan, tests: rec.derived.tests, amendments: acc.amendments, spec_edits_after_ship: acc.spec_edits_after_ship, diff: rec.derived.diff, modified_files: rec.derived.modified_files, spec_writes: acc.spec_writes, events_dropped: acc.events_dropped });
+  return compact({ duration_s: seconds(rec.created_at, rec.shipped_at ?? rec.abandoned_at ?? now), phases, personas: acc.personas, reviews: Object.keys(acc.reviews).length ? acc.reviews : void 0, conformance_loops: acc.conformance_loops, conformance_open_gaps: acc.conformance_open_gaps, gates: compact({ ...acc.gates, ship_option: live?.option }), plan: rec.derived.plan, tests: rec.derived.tests, amendments: acc.amendments, spec_edits_after_ship: acc.spec_edits_after_ship, diff: rec.derived.diff, modified_files: rec.derived.modified_files, council: rec.derived.council, spec_writes: acc.spec_writes, events_dropped: acc.events_dropped });
 }
 var stripUndefined = (v) => {
   if (Array.isArray(v)) return v.map(stripUndefined);
@@ -202,7 +202,11 @@ function serializeRecord(rec) {
   const body = stripUndefined({ ...head, derived, accumulators });
   const doc = new Document(body);
   const derivedNode = doc.get("derived", true);
-  if (isMap(derivedNode)) flowLeafChildren(derivedNode, /* @__PURE__ */ new Set(["modified_files"]));
+  if (isMap(derivedNode)) {
+    flowLeafChildren(derivedNode, /* @__PURE__ */ new Set(["modified_files", "council"]));
+    const council = derivedNode.get("council", true);
+    if (isMap(council)) flowLeafChildren(council);
+  }
   const accumulatorNode = doc.get("accumulators", true);
   if (isMap(accumulatorNode)) {
     for (const session of accumulatorNode.items) if (isMap(session.value)) flowLeafChildren(session.value);

package/bin/gauntlet-telemetry-seal.test.mjs

@@ -100,6 +100,16 @@ test("seals an untracked in_progress record: stamp, ship event, diff, re-derived
   assert.equal(porcelain(root), "");
 });
 
+test("seal preserves derived.council through the shipped stamp", (t) => {
+  const council = { chair: { model: "p/chair:medium", dispatches: 1, clusters: 0, members_reported: 0 }, members: {} };
+  const root = repo({ record: RECORD.replace("  spec_writes: {}", `  council: ${JSON.stringify(council)}\n  spec_writes: {}`) }); cleanup(t, root);
+  const r = run(root, ["--spec", SPEC]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(record(root).status, "shipped");
+  assert.deepEqual(record(root).derived.council, council);
+  assert.deepEqual(parseYaml(out(root, ["show", `HEAD:${REC}`])).derived.council, council);
+});
+
 test("--spec accepts an absolute path within the checkout", (t) => {
   const root = repo(); cleanup(t, root);
   const r = run(root, ["--spec", join(realpathSync(root), SPEC)]);