pi-gauntlet 5.23.0 → 5.23.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v5.23.1 - 2026-09-27
+
+### Changed
+
+- `gauntlet-spec-index` prints a one-line stderr note (`<corpus> corpus has <n> documents - too small for the confidence rule; no rows returned`) when a query returns no rows on a corpus under 10 documents; stdout and exit code are unchanged. The brainstorming scout carries the reason as `Predecessor: none (specs corpus too small: <n> documents)` / `Docs touched: none (docs corpus too small: <n> documents)`.
+
 ## v5.23.0 - 2026-09-27
 
 ### 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 over two corpora in one per-worktree cache. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--corpus specs|docs] [--limit N] [--exclude <repo-relative path>]...`; it requires Node >=24.15.0 and refreshes its FTS5 index on every query. `--corpus specs` (the default) searches `doc/specs/*.md` at the repository root and one service level down and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `state`, `files`, and `snippet` columns. `--corpus docs` searches project documentation and prints `score`, `path`, `title`, and `snippet`; the snippet is the matched `##`/`###` heading line when one holds a query term, else a body fragment. Docs candidates are the tracked and untracked, non-gitignored `*.md` files (`git ls-files -co --exclude-standard`, so nested repositories and submodules are not indexed) matching an include list - default `**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md`, where a slash-free entry also matches one service level down - minus the fixed exclusions `**/doc/specs/**`, `**/docs/specs/**`, `**/doc/plans/**`, `**/docs/plans/**`, `**/node_modules/**`, `.pi/gauntlet/**`, `.worktrees/**`, symlinks, and files whose first line is the context-draft marker; `**` never matches a dot directory, so `.pi/*.md` or `.github/*.md` is indexed only through an explicit include. A project replaces the include list with `- docs: <glob>` bullets under a `## Spec index` heading in its gauntlet overrides file (see [Project-specific overrides](#project-specific-overrides)); the exclusions are not configurable. Both corpora pass the same confidence rule before `--limit` applies: a query term is evidence when it occurs in fewer than half the rows of the queried table (stem variants of one word count once); query tokens split on word boundaries, so `gauntlet-spec-index` searches as three words; a row is returned only when it matches at least two distinct evidence terms in the corpus's strong fields - `title` or `goal` for specs, `title` or `headings` for docs - and rows scoring below half the best live row's score are dropped (every docs row is live). A query with no real match therefore prints the header only and exits 0, and a corpus of two or fewer files never returns rows. `--exclude` (repeatable) removes a path before the rule runs, so the spec under review never sets the bar. `state` is `superseded` when a `> **Superseded by:** ... - fully` banner sits in the block directly under the title and `live` otherwise; named-section banners and consumer-defined banner syntaxes both read as `live`. Live rows sort before superseded rows, then by score. The `files` column is a `;`-separated list of repo-relative paths the spec's shipped change modified and that still exist in the repository, the literal `missing` when the spec's telemetry record has no `derived.modified_files` list, or blank when there is no readable record or no recorded path remains. The cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`. `/skill:brainstorming` queries the specs corpus twice - the scout at gather time from the request, and the main loop at spec-writing from the finished spec's title, goal, and headings, surfacing new `live` candidates at the review gate - and the scout queries the docs corpus once to render `Docs touched:` lines that round 2 weighs as documentation-impact candidates.
+`gauntlet-spec-index` provides lexical search over two corpora in one per-worktree cache. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--corpus specs|docs] [--limit N] [--exclude <repo-relative path>]...`; it requires Node >=24.15.0 and refreshes its FTS5 index on every query. `--corpus specs` (the default) searches `doc/specs/*.md` at the repository root and one service level down and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `state`, `files`, and `snippet` columns. `--corpus docs` searches project documentation and prints `score`, `path`, `title`, and `snippet`; the snippet is the matched `##`/`###` heading line when one holds a query term, else a body fragment. Docs candidates are the tracked and untracked, non-gitignored `*.md` files (`git ls-files -co --exclude-standard`, so nested repositories and submodules are not indexed) matching an include list - default `**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md`, where a slash-free entry also matches one service level down - minus the fixed exclusions `**/doc/specs/**`, `**/docs/specs/**`, `**/doc/plans/**`, `**/docs/plans/**`, `**/node_modules/**`, `.pi/gauntlet/**`, `.worktrees/**`, symlinks, and files whose first line is the context-draft marker; `**` never matches a dot directory, so `.pi/*.md` or `.github/*.md` is indexed only through an explicit include. A project replaces the include list with `- docs: <glob>` bullets under a `## Spec index` heading in its gauntlet overrides file (see [Project-specific overrides](#project-specific-overrides)); the exclusions are not configurable. Both corpora pass the same confidence rule before `--limit` applies: a query term is evidence when it occurs in fewer than half the rows of the queried table (stem variants of one word count once); query tokens split on word boundaries, so `gauntlet-spec-index` searches as three words; a row is returned only when it matches at least two distinct evidence terms in the corpus's strong fields - `title` or `goal` for specs, `title` or `headings` for docs - and rows scoring below half the best live row's score are dropped (every docs row is live). A query with no real match therefore prints the header only and exits 0 - and when the queried corpus has fewer than 10 documents, also writes one stderr line naming the corpus and its size (`gauntlet-spec-index: docs corpus has 5 documents - too small for the confidence rule; no rows returned`), so a small corpus and a genuine miss stay distinguishable; a corpus of two or fewer files never returns rows. `--exclude` (repeatable) removes a path before the rule runs, so the spec under review never sets the bar. `state` is `superseded` when a `> **Superseded by:** ... - fully` banner sits in the block directly under the title and `live` otherwise; named-section banners and consumer-defined banner syntaxes both read as `live`. Live rows sort before superseded rows, then by score. The `files` column is a `;`-separated list of repo-relative paths the spec's shipped change modified and that still exist in the repository, the literal `missing` when the spec's telemetry record has no `derived.modified_files` list, or blank when there is no readable record or no recorded path remains. The cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`. `/skill:brainstorming` queries the specs corpus twice - the scout at gather time from the request, and the main loop at spec-writing from the finished spec's title, goal, and headings, surfacing new `live` candidates at the review gate - and the scout queries the docs corpus once to render `Docs touched:` lines that round 2 weighs as documentation-impact candidates.
 
 ## Performance digest
 

package/bin/gauntlet-spec-index.mjs

@@ -10,6 +10,8 @@ const SCHEMA_VERSION = 3;
 const EVIDENCE_DF_FRACTION = 0.5;
 const MIN_EVIDENCE_TOKENS = 2;
 const SCORE_RATIO = 0.5;
+// Policy floor, not derived from the rule: below it an empty result says little about coverage.
+const MIN_CORPUS = 10;
 // 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$/;
@@ -307,7 +309,7 @@ function query(db, corpus, toks, { limit, exclude }) {
     if (all.size === 0 || all.size >= n * EVIDENCE_DF_FRACTION) continue;
     evidence.push({ all, strong: rowids(corpus.strong.map((f) => `${f}:${quote(tok)}`).join(" OR ")) });
   }
-  if (evidence.length < MIN_EVIDENCE_TOKENS) return [];
+  if (evidence.length < MIN_EVIDENCE_TOKENS) return { rows: [], n };
   const rows = db.prepare(
     `SELECT rowid, ${corpus.select}, bm25(${table}, ${corpus.weights.map((w) => w.toFixed(1)).join(", ")}) AS score
      FROM ${table} WHERE ${table} MATCH ?`,
@@ -317,7 +319,7 @@ function query(db, corpus, toks, { limit, exclude }) {
   kept.sort((a, b) => Number(!live(a)) - Number(!live(b)) || a.score - b.score);
   const best = kept.find(live);
   const cut = best ? kept.filter((r) => Math.abs(r.score) >= SCORE_RATIO * Math.abs(best.score)) : kept;
-  return cut.slice(0, limit);
+  return { rows: cut.slice(0, limit), n };
 }
 
 function telemetry(root, specPath) {
@@ -394,10 +396,13 @@ async function main() {
   const corpus = CORPORA[name];
   const db = await openDb(root);
   refresh(db, root, corpus);
-  const rows = query(db, corpus, toks, { limit, exclude });
+  const { rows, n } = query(db, corpus, toks, { limit, exclude });
   const out = [corpus.header.join("\t")];
   for (const r of rows) out.push(corpus.format(root, r).join("\t"));
   process.stdout.write(out.join("\n") + "\n");
+  if (rows.length === 0 && n < MIN_CORPUS) {
+    process.stderr.write(`gauntlet-spec-index: ${name} corpus has ${n} documents - too small for the confidence rule; no rows returned\n`);
+  }
   db.close();
 }
 

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

@@ -43,6 +43,16 @@ const commit = (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 boundaryRepo = (fillers) => {
+  const root = gitRepo();
+  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));
+  for (const f of fillers) write(root, `doc/specs/filler-${f}.md`, filler(f));
+  commit(root);
+  return root;
+};
+const NOTE = "too small for the confidence rule; no rows returned";
 
 const repo = () => {
   const root = gitRepo();
@@ -357,6 +367,50 @@ test("16: punctuation splits into distinct evidence terms and query order does n
   assert.deepEqual(paths(run(root, ["--query", "config config-file"])), paths(run(root, ["--query", "config-file config"])));
 });
 
+test("21: three-spec corpus, no match - header only plus the small-corpus note", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  for (const n of ["one", "two", "three"]) write(root, `doc/specs/filler-${n}.md`, filler(n));
+  commit(root);
+  const r = run(root, ["--query", "yeti unicorn"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.header, HEADER);
+  assert.deepEqual(r.rows, []);
+  assert.equal(r.stderr, `gauntlet-spec-index: specs corpus has 3 documents - ${NOTE}\n`);
+});
+
+test("22: MIN_CORPUS boundary - note at N = 9, silent at N = 10, rows unaffected", (t) => {
+  const root = boundaryRepo(["one", "two", "three"]);
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const nine = run(root, ["--query", "yeti unicorn"]);
+  assert.equal(nine.status, 0, nine.stderr);
+  assert.deepEqual(nine.rows, []);
+  assert.equal(nine.stderr, `gauntlet-spec-index: specs corpus has 9 documents - ${NOTE}\n`);
+  write(root, "doc/specs/filler-four.md", filler("four"));
+  commit(root);
+  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, []);
+    assert.equal(r.stderr, "");
+  }
+  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"]);
+  assert.equal(strong.stderr, "");
+});
+
+test("23: n is the table count before --exclude", (t) => {
+  const root = boundaryRepo(["one", "two", "three", "four"]);
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const r = run(root, ["--query", "yeti unicorn", "--exclude", "doc/specs/p1.md"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.header, HEADER);
+  assert.deepEqual(r.rows, []);
+  assert.equal(r.stderr, "");
+});
+
 test("D1: --corpus specs and omitted --corpus are byte-identical; nine columns", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
@@ -420,6 +474,7 @@ test("D2: docs include defaults and fixed exclusions", (t) => {
   assert.equal(tiny.status, 0, tiny.stderr);
   assert.deepEqual(tiny.header, DOCS_HEADER);
   assert.deepEqual(tiny.rows, []);
+  assert.equal(tiny.stderr, `gauntlet-spec-index: docs corpus has 2 documents - ${NOTE}\n`);
 });
 
 test("D3: shared confidence rejects common body-only hits", (t) => {
@@ -558,3 +613,15 @@ test("D10: fenced headings and shorter nested fences are ignored", (t) => {
   run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
   for (const p of ["doc/f.md", "doc/nested.md"]) assert.equal(withDb(root, (db) => db.prepare("SELECT headings FROM docs WHERE path = ?").get(p).headings), "");
 });
+
+test("D13: five-document docs corpus with rare heading terms returns rows and no note", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/strong.md", "# Strong doc\n\n## heron ibis\n\n## jackal\n\nbody\n");
+  for (let n = 1; n <= 4; n++) write(root, `doc/p${n}.md`, `# Plain doc ${n}\n\nThe body mentions the common shared vocabulary.\n`);
+  commit(root);
+  const r = run(root, ["--corpus", "docs", "--query", "heron ibis jackal common", "--limit", "10"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["doc/strong.md"]);
+  assert.equal(r.stderr, "");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.23.0",
+  "version": "5.23.1",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/gatherer.md

@@ -58,7 +58,11 @@ Scout (always dispatched):
 > `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; 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
+> judge `Predecessor: none` from the code recon. When the command output contains a line
+> ending "too small for the confidence rule; no rows returned" (a diagnostic, not a row) and
+> the code recon names no predecessor, write
+> `Predecessor: none (specs corpus too small: <n> documents)`, copying <n> from that
+> line. 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
@@ -96,7 +100,10 @@ Scout (always dispatched):
 > document (the row's `snippet` column is a hint to it), or the document title when no single
 > section applies; or `Docs touched: none`. Judge by topic; a lexical hit alone is not
 > coverage. Zero rows means the index found no evidence, not that no document covers the
-> topic. This query supplements the code and documentation recon you already perform; it
+> topic. When the docs command output contains that same diagnostic line and the recon
+> found no covering document, write
+> `Docs touched: none (docs corpus too small: <n> documents)` instead. This query
+> supplements the code and documentation recon you already perform; it
 > never replaces it - keep reading the files the request touches. End with an
 > "Open questions that matter for the spec"
 > section. Compact handoff, not a dump.