pi-gauntlet 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v6.1.0 - 2026-09-30
+
+### Changed
+
+- Minor code-review findings ride along in a `FIX_FIRST` fix round and never trigger one; a `SHIP` report ends the loop whatever Minors it lists. The whole-diff review's Minors land in the closure block as `whole-diff minors:` and the finish gate offers a one-shot `fix minors` reply. Re-reviews are scoped to a `## Fix delta` block (the whole-diff review and its re-reviews stay unscoped): a new finding outside it blocks only when Critical; `TRAJECTORY:` counts Critical and Moderate only. Telemetry counts `[Critical]`/`[Moderate]` into `blocker`/`major`. (#56)
+
+## v6.0.1 - 2026-09-30
+
+### Changed
+
+- `flowGuards.specDirs` defaults to `["doc/specs", "docs/specs"]` and now governs telemetry spec/plan classification, the seal's plan exclusion, and the spec index; `gauntlet-telemetry-seal` selects records by their `spec:` field; `gauntlet-spec-index` ships as an esbuild bundle from `src/bins/`; `gauntlet_setting` gains the `flowGuards` key.
+
 ## v6.0.0 - 2026-09-30
 
 ### Changed

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 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.
+`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 `<spec dir>/*.md` for each resolved `flowGuards.specDirs` entry (default `doc/specs` and `docs/specs`) 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 resolved spec and plan dirs (matched as literal path components), `**/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 through the overrides file; the spec and plan dir exclusions follow `flowGuards.specDirs`. 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/agents/code-reviewer.md

@@ -59,6 +59,7 @@ Rules:
 - Verify before praising: no "looks good" on code you did not read.
 - Report only on code you read.
 - Name the concrete change in every Fix; "improve error handling" is not a Fix.
+- On a re-review (the task carries `## Previous review report (re-review trigger)`): confirm each prior finding is resolved, then review the `## Fix delta` block, reading surrounding code as needed. A new finding outside that delta is Critical, or it is `[Minor]` with the note `(outside fix delta)`. No `## Fix delta` block -> the task's whole diff is the delta. The whole-diff review and its re-reviews are never scoped.
 
 Label every finding with a globally unique `F1..Fn` ID (no restart per severity),
 and a `touched-files:`/`touched-resources:` pair (files a fix would edit, not only

package/agents/conformance-reviewer.md

@@ -147,7 +147,7 @@ Footer order: `Parallel-safe:` is the final line of the report.
 - **Read-only. Never edit.** You audit; you do not fix.
 - **Propose, do not dispose.** For each gap you may suggest a one-line remediation *direction*, but you do **not** decide the disposition - the orchestrator auto-applies `fix` gaps and defers `accept`/`rescope` gaps to the user at the finish gate (an `UNAUTHORIZED` row follows its `recommended` value like every other verdict). Never present a fix as a decision you made.
 - **Evidence or it didn't happen.** Cite a real `file:line` for every DELIVERED/PARTIAL. If you cannot, downgrade the row to MISSING.
-- **Origin quote or it isn't a gap.** Every non-UNAUTHORIZED gap's `origin` carries a locator AND a verbatim quote: `origin: <file/section, 'prompt', or 'ticket'> - "<quoted clause>"` (truncate long clauses with `[...]` as long as the fragment uniquely identifies the clause). No quotable origin clause = no gap. Do not derive implicit requirements. Do not flag wording preferences. A deviation recorded in the spec wins over an older origin value (Process step 2); report it only if unrecorded.
+- **Origin quote or it isn't a gap.** Every non-UNAUTHORIZED gap's `origin` carries a locator AND a verbatim quote: `origin: <file/section, 'prompt', or 'ticket'> - "<quoted clause>"` (truncate long clauses with `[...]` as long as the fragment uniquely identifies the clause). No quotable origin clause = no gap. Do not derive implicit requirements. Do not flag wording preferences. A code-review finding - style, naming, comment, micro-efficiency - with no origin clause is never a gap, whatever its severity. A deviation recorded in the spec wins over an older origin value (Process step 2); report it only if unrecorded.
 - **Spec is canonical; the prompt catches what the spec dropped; the ticket is fallback only** when no spec exists.
 - **The spec's `## Acceptance criteria` section is origin, not ticket.** Its `in-scope`/`venue:` rows are `Rn`; its `deviates:`/`deferred:` rows are recorded drift (`recorded in spec? yes`).
 - **Do not absorb origin drift silently** — flag every spec↔prompt/ticket disagreement.

package/bin/gauntlet-performance.test.mjs

@@ -54,8 +54,8 @@ derived:
     worker: { dispatches: 3, models: [m/beta] }
     spec-council-member: { dispatches: 4, models: [m/alpha] }
   reviews:
-    spec-reviewer: { dispatches: 1, nonzero_exit: 0, findings: { blocker: 1, major: 2, minor: 3 } }
-    code-reviewer: { dispatches: 1, nonzero_exit: 0 }
+    spec-reviewer: { dispatches: 1, nonzero_exit: 0 }
+    code-reviewer: { dispatches: 1, nonzero_exit: 0, findings: { blocker: 1, major: 2, minor: 3 } }
   conformance_loops: 2
   conformance_open_gaps: 0
   gates: { spec_rounds: 1, plan_rounds: 1, fix_round_grants: 1, task_reopens: 0, ship_option: squash }
@@ -211,8 +211,8 @@ test("malformed reviewer entries and findings objects contribute null counters",
     'findings: "bad"',
   );
   const malformedReviewer = COMPLETE.replace(
-    "spec-reviewer: { dispatches: 1, nonzero_exit: 0, findings: { blocker: 1, major: 2, minor: 3 } }",
-    'spec-reviewer: "bad"',
+    "code-reviewer: { dispatches: 1, nonzero_exit: 0, findings: { blocker: 1, major: 2, minor: 3 } }",
+    'code-reviewer: "bad"',
   );
   write(root, `${TDIR}/malformed-findings-object.yaml`, malformedFindings);
   write(root, `${TDIR}/malformed-reviewer.yaml`, malformedReviewer.replace(

package/bin/gauntlet-spec-index.mjs

@@ -1,29 +1,53 @@
 #!/usr/bin/env node
-// Lexical search over spec and docs corpora (FTS5, bm25, shared confidence rule); telemetry joined for specs only.
+
+// src/bins/gauntlet-spec-index.mjs
 import { readFileSync, appendFileSync, existsSync, statSync, lstatSync, readdirSync, mkdirSync, rmSync, realpathSync, openSync, readSync, closeSync } from "node:fs";
 import { join, dirname, basename, isAbsolute, matchesGlob } from "node:path";
+import { homedir } from "node:os";
 import { execFileSync } from "node:child_process";
 import process from "node:process";
 import { parse as parseYaml } from "yaml";
 
-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$/;
-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 FENCE = /^\s*(`{3,}|~{3,})/;
-const DOC_INCLUDES = ["**/doc/**/*.md", "**/docs/**/*.md", "README.md", "AGENTS.md"];
-const DOC_EXCLUDES = ["**/doc/specs/**", "**/docs/specs/**", "**/doc/plans/**", "**/docs/plans/**", "**/node_modules/**", ".pi/gauntlet/**", ".worktrees/**"];
-const OVERRIDES_FILES = [".pi/gauntlet-overrides.md", "gauntlet-overrides.md", "doc/gauntlet-overrides.md"];
-const SCHEMA = `
+// extensions/lib/gauntlet-settings.ts
+function mergeGauntlet(preset, repo) {
+  return { ...preset ?? {}, ...repo ?? {} };
+}
+var nonEmptyString = (v) => typeof v === "string" && v.trim().length > 0;
+var DEFAULT_SPEC_DIRS = ["doc/specs", "docs/specs"];
+var normalizeDir = (d) => d.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+function resolveFlowGuards(g) {
+  const fg = g.flowGuards;
+  const enforce = fg?.enforce !== false;
+  const rawDirs = fg?.specDirs;
+  const specDirs = Array.isArray(rawDirs) && rawDirs.length > 0 && rawDirs.every(nonEmptyString) ? rawDirs.map(normalizeDir) : [...DEFAULT_SPEC_DIRS];
+  return { enforce, specDirs };
+}
+function planDirsFor(specDirs) {
+  const out = /* @__PURE__ */ new Set();
+  for (const dir of specDirs) {
+    const parts = dir.split("/").filter((c) => c.length > 0);
+    if (parts.length === 0) continue;
+    out.add([...parts.slice(0, -1), "plans"].join("/"));
+  }
+  return [...out];
+}
+
+// src/bins/gauntlet-spec-index.mjs
+var SCHEMA_VERSION = 3;
+var EVIDENCE_DF_FRACTION = 0.5;
+var MIN_EVIDENCE_TOKENS = 2;
+var SCORE_RATIO = 0.5;
+var MIN_CORPUS = 10;
+var FULLY_BANNER = /^> \*\*Superseded by:\*\* \[.*\]\(.*\) - fully$/;
+var MIN_NODE = [24, 15, 0];
+var DRAFT_MARKER = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
+var EXCLUDE_LINE = "/.pi/gauntlet/index.sqlite*";
+var SKIP_DIRS = /* @__PURE__ */ new Set([".worktrees", "node_modules", "build"]);
+var FENCE = /^\s*(`{3,}|~{3,})/;
+var DOC_INCLUDES = ["**/doc/**/*.md", "**/docs/**/*.md", "README.md", "AGENTS.md"];
+var DOC_EXCLUDE_GLOBS = ["**/node_modules/**", ".pi/gauntlet/**", ".worktrees/**"];
+var OVERRIDES_FILES = [".pi/gauntlet-overrides.md", "gauntlet-overrides.md", "doc/gauntlet-overrides.md"];
+var SCHEMA = `
   CREATE TABLE IF NOT EXISTS meta  (key TEXT PRIMARY KEY, value TEXT);
   CREATE TABLE IF NOT EXISTS files (corpus TEXT NOT NULL, path TEXT NOT NULL, mtime_ms INTEGER, size INTEGER, PRIMARY KEY (corpus, path));
   CREATE VIRTUAL TABLE IF NOT EXISTS specs USING fts5(
@@ -33,40 +57,36 @@ const SCHEMA = `
     path UNINDEXED, title, headings, body,
     tokenize = 'porter unicode61');
 `;
-
-const usage = () => {
+var usage = () => {
   process.stderr.write('usage: gauntlet-spec-index --query "<text>" [--corpus specs|docs] [--limit N] [--exclude <repo-relative path>]...\n');
   process.exit(1);
 };
-const die = (msg) => {
-  process.stderr.write(`${msg}\n`);
+var die = (msg) => {
+  process.stderr.write(`${msg}
+`);
   process.exit(2);
 };
-
 function parseArgs(argv) {
-  let query;
+  let query2;
   let corpus = "specs";
   let limit = 10;
   const exclude = [];
   for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === "--query" && argv[i + 1] !== undefined) query = argv[++i];
+    if (argv[i] === "--query" && argv[i + 1] !== void 0) query2 = argv[++i];
     else if (argv[i] === "--corpus" && Object.hasOwn(CORPORA, argv[i + 1] ?? "")) corpus = argv[++i];
     else if (argv[i] === "--limit" && /^[1-9]\d*$/.test(argv[i + 1] ?? "")) limit = Number(argv[++i]);
-    else if (argv[i] === "--exclude" && argv[i + 1] !== undefined) exclude.push(argv[++i]);
+    else if (argv[i] === "--exclude" && argv[i + 1] !== void 0) exclude.push(argv[++i]);
     else usage();
   }
-  if (query === undefined) usage();
-  return { query, corpus, limit, exclude };
+  if (query2 === void 0) usage();
+  return { query: query2, corpus, limit, exclude };
 }
-
 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();
-
+var 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"]);
@@ -74,10 +94,25 @@ function repoRoot() {
     return die("gauntlet-spec-index: not inside a git repository");
   }
 }
-
+function readLayer(file) {
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch (e) {
+    process.stderr.write(`warning: ${file}: ${e.message}; using {} for this layer
+`);
+    return {};
+  }
+}
+function specDirsFor(root) {
+  const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+  const merged = mergeGauntlet(readLayer(join(agentDir, "settings.json"))?.piGauntlet, readLayer(join(root, ".pi", "settings.json"))?.piGauntlet);
+  const specDirs = resolveFlowGuards(merged).specDirs;
+  return { specDirs, planDirs: planDirsFor(specDirs) };
+}
 function discover(root) {
   const out = [];
-  const seen = new Set();
+  const seen = /* @__PURE__ */ new Set();
   const collect = (relDir, service) => {
     const abs = join(root, relDir);
     let real;
@@ -96,18 +131,17 @@ function discover(root) {
       if (st.isFile()) out.push({ path: rel, service, mtime_ms: Math.trunc(st.mtimeMs), size: st.size });
     }
   };
-  collect("doc/specs", "root");
-  for (const s of services(root).sort((a, b) => a.localeCompare(b))) collect(`${s}/doc/specs`, s);
+  const { specDirs } = specDirsFor(root);
+  const svc = services(root).sort((a, b) => a.localeCompare(b));
+  for (const d of specDirs) {
+    collect(d, "root");
+    for (const s of svc) collect(`${s}/${d}`, s);
+  }
   return out;
 }
-
-// Top-level directories discover() would scan; a slash-free include also matches one level under them.
 function services(root) {
-  return readdirSync(root, { withFileTypes: true })
-    .filter((e) => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith(".") && !SKIP_DIRS.has(e.name))
-    .map((e) => e.name);
+  return readdirSync(root, { withFileTypes: true }).filter((e) => (e.isDirectory() || e.isSymbolicLink()) && !e.name.startsWith(".") && !SKIP_DIRS.has(e.name)).map((e) => e.name);
 }
-
 function includes(root) {
   const file = OVERRIDES_FILES.map((rel) => join(root, rel)).find((abs) => existsSync(abs));
   if (!file) return DOC_INCLUDES;
@@ -120,14 +154,16 @@ function includes(root) {
     die(`gauntlet-spec-index: unreadable overrides file ${file}: ${e.message}`);
   }
   for (const line of text.split(/\r?\n/)) {
-    if (/^## /.test(line)) { inSection = line.trim() === "## Spec index"; continue; }
+    if (/^## /.test(line)) {
+      inSection = line.trim() === "## Spec index";
+      continue;
+    }
     if (!inSection) continue;
     const m = /^-\s+docs:\s*(.+?)\s*$/.exec(line);
     if (m) globs.push(m[1].replace(/^[`"']+|[`"']+$/g, ""));
   }
   return globs.length ? globs : DOC_INCLUDES;
 }
-
 function firstLine(abs) {
   const fd = openSync(abs, "r");
   try {
@@ -138,15 +174,24 @@ function firstLine(abs) {
     closeSync(fd);
   }
 }
-
+function underDirs(rel, dirs) {
+  const parts = rel.split("/");
+  return dirs.some((d) => {
+    const dp = d.split("/");
+    for (let i = 0; i + dp.length < parts.length; i++) if (dp.every((c, j) => parts[i + j] === c)) return true;
+    return false;
+  });
+}
 function discoverDocs(root, globs) {
+  const { specDirs, planDirs } = specDirsFor(root);
+  const skip = [...specDirs, ...planDirs];
   const svc = services(root);
-  const patterns = globs.flatMap((g) => (g.includes("/") ? [g] : [g, ...svc.map((s) => `${s}/${g}`)]));
+  const patterns = globs.flatMap((g) => g.includes("/") ? [g] : [g, ...svc.map((s) => `${s}/${g}`)]);
   const listed = execFileSync("git", ["-C", root, "ls-files", "-co", "--exclude-standard", "-z", "--", "*.md"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split("\0").filter(Boolean);
   const out = [];
   for (const rel of listed) {
     if (!patterns.some((p) => matchesGlob(rel, p))) continue;
-    if (DOC_EXCLUDES.some((p) => matchesGlob(rel, p))) continue;
+    if (DOC_EXCLUDE_GLOBS.some((p) => matchesGlob(rel, p)) || underDirs(rel, skip)) continue;
     let st;
     try {
       st = lstatSync(join(root, rel));
@@ -158,35 +203,37 @@ function discoverDocs(root, globs) {
   }
   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`);
+  appendFileSync(abs, `${cur.length && !cur.endsWith("\n") ? "\n" : ""}${EXCLUDE_LINE}
+`);
 }
-
 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");
+    const db2 = new DatabaseSync(dbPath);
+    db2.exec("PRAGMA busy_timeout = 2000");
     try {
-      db.exec(SCHEMA);
+      db2.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;
+    db2.prepare("INSERT OR REPLACE INTO meta VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+    return db2;
   };
-  const rebuild = (db) => {
-    try { db?.close(); } catch {}
+  const rebuild = (db2) => {
+    try {
+      db2?.close();
+    } catch {
+    }
     for (const suffix of ["", "-journal", "-wal", "-shm"]) rmSync(dbPath + suffix, { force: true });
     return create();
   };
@@ -202,11 +249,13 @@ async function openDb(root) {
     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 {}
+    try {
+      db?.close();
+    } catch {
+    }
     throw e;
   }
 }
-
 function fenceMask(lines) {
   const mask = new Array(lines.length).fill(false);
   let open = null;
@@ -222,7 +271,6 @@ function fenceMask(lines) {
   }
   return mask;
 }
-
 function extract(text, path) {
   const lines = text.split(/\r?\n/);
   const fenced = fenceMask(lines);
@@ -232,15 +280,16 @@ function extract(text, path) {
   const headings = lines.filter((l, i) => !fenced[i] && /^##{1,2} /.test(l)).map((l) => l.replace(/^#+ /, "")).join("\n");
   let state = "live";
   if (h1 >= 0) {
-    // Title block: everything after the H1 up to the first H2 heading or code fence.
     for (const l of lines.slice(h1 + 1)) {
       if (/^## /.test(l) || FENCE.test(l)) break;
-      if (FULLY_BANNER.test(l)) { state = "superseded"; break; }
+      if (FULLY_BANNER.test(l)) {
+        state = "superseded";
+        break;
+      }
     }
   }
   return { title, goal, headings, state };
 }
-
 function refresh(db, root, corpus) {
   const { table } = corpus;
   const found = corpus.discover(root);
@@ -252,13 +301,19 @@ function refresh(db, root, corpus) {
   const putFile = db.prepare("INSERT OR REPLACE INTO files (corpus, path, mtime_ms, size) VALUES (?, ?, ?, ?)");
   db.exec("BEGIN IMMEDIATE");
   try {
-    for (const path of known.keys()) if (!present.has(path)) { delRow.run(path); delFile.run(table, path); }
+    for (const path of known.keys()) if (!present.has(path)) {
+      delRow.run(path);
+      delFile.run(table, path);
+    }
     for (const f of found) {
       const k = known.get(f.path);
       if (k && k.mtime_ms === f.mtime_ms && k.size === f.size) continue;
       const text = readFileSync(join(root, f.path), "utf8");
       delRow.run(f.path);
-      if (text.split(/\r?\n/, 1)[0] === DRAFT_MARKER) { delFile.run(table, f.path); continue; }
+      if (text.split(/\r?\n/, 1)[0] === DRAFT_MARKER) {
+        delFile.run(table, f.path);
+        continue;
+      }
       insRow.run(...corpus.row(text, f));
       putFile.run(table, f.path, f.mtime_ms, f.size);
     }
@@ -268,27 +323,22 @@ function refresh(db, root, corpus) {
     throw e;
   }
 }
-
-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.
+var tokens = (query2) => query2.split(/[^\p{L}\p{N}\p{Co}]+/u).filter((t) => t.length >= 2);
+var quote = (t) => `"${t.replaceAll('"', '""')}"`;
+var toMatch = (toks) => toks.map(quote).join(" OR ");
 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();
+    const rep = /* @__PURE__ */ 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;
@@ -296,7 +346,6 @@ function confidenceFilter(rows, evidence) {
     return hits >= MIN_EVIDENCE_TOKENS && strong >= MIN_EVIDENCE_TOKENS;
   });
 }
-
 function query(db, corpus, toks, { limit, exclude }) {
   const { table } = corpus;
   const n = db.prepare(`SELECT count(*) AS n FROM ${table}`).get().n;
@@ -312,7 +361,7 @@ function query(db, corpus, toks, { limit, exclude }) {
   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 ?`,
+     FROM ${table} WHERE ${table} MATCH ?`
   ).all(toMatch(terms)).filter((r) => !exclude.includes(r.path));
   const kept = confidenceFilter(rows, evidence);
   const live = (r) => !corpus.hasState || r.state === "live";
@@ -321,7 +370,6 @@ function query(db, corpus, toks, { limit, exclude }) {
   const cut = best ? kept.filter((r) => Math.abs(r.score) >= SCORE_RATIO * Math.abs(best.score)) : kept;
   return { rows: cut.slice(0, limit), n };
 }
-
 function telemetry(root, specPath) {
   const blank = { status: null, shipped_at: null, files: "" };
   const p = join(root, ".pi/gauntlet/telemetry", specPath.replace(/\.md$/, ".yaml"));
@@ -330,28 +378,23 @@ function telemetry(root, specPath) {
   try {
     rec = parseYaml(readFileSync(p, "utf8"));
   } catch {
-    process.stderr.write(`gauntlet-spec-index: warning: unreadable telemetry ${p}\n`);
+    process.stderr.write(`gauntlet-spec-index: warning: unreadable telemetry ${p}
+`);
     return blank;
   }
   if (!rec || typeof rec !== "object" || Array.isArray(rec)) return blank;
   const mf = rec.derived?.modified_files;
-  const files = Array.isArray(mf)
-    ? mf.filter((f) => typeof f === "string" && existsSync(join(root, f))).join(";")
-    : "missing";
+  const files = Array.isArray(mf) ? mf.filter((f) => typeof f === "string" && existsSync(join(root, f))).join(";") : "missing";
   return { status: rec.status ?? null, shipped_at: rec.shipped_at ?? null, files };
 }
-
-const cell = (v) => (v === null || v === undefined ? "" : String(v).replace(/\s+/g, " ").trim());
-// Paths keep their spaces; only column and row delimiters are neutralised.
-const filesCell = (v) => v.replace(/[\t\r\n]+/g, " ");
-
+var cell = (v) => v === null || v === void 0 ? "" : String(v).replace(/\s+/g, " ").trim();
+var filesCell = (v) => v.replace(/[\t\r\n]+/g, " ");
 function docSnippet(r) {
-  if (!r.hsnip.includes("\u0001")) return r.bsnip;
-  const fragment = r.hsnip.split("\n").find((line) => line.includes("\u0001")).replace(/[\u0001\u0002]/g, "");
+  if (!r.hsnip.includes("
")) return r.bsnip;
+  const fragment = r.hsnip.split("\n").find((line) => line.includes("
")).replace(/[\u0001\u0002]/g, "");
   return r.headings.split("\n").find((line) => line.includes(fragment));
 }
-
-const CORPORA = {
+var CORPORA = {
   specs: {
     table: "specs",
     columns: ["path", "service", "title", "goal", "headings", "body", "state"],
@@ -368,7 +411,7 @@ const CORPORA = {
     format: (root, r) => {
       const t = telemetry(root, r.path);
       return [...[r.score.toFixed(3), r.path, r.service, r.title, t.status, t.shipped_at, r.state].map(cell), filesCell(t.files), cell(r.snippet)];
-    },
+    }
   },
   docs: {
     table: "docs",
@@ -377,16 +420,15 @@ const CORPORA = {
     weights: [0, 10, 3, 1],
     hasState: false,
     header: ["score", "path", "title", "snippet"],
-    select: "path, title, headings, snippet(docs, 2, '\u0001', '\u0002', '', 12) AS hsnip, snippet(docs, 3, '', '', '...', 12) AS bsnip",
+    select: "path, title, headings, snippet(docs, 2, '
', '', '', 12) AS hsnip, snippet(docs, 3, '', '', '...', 12) AS bsnip",
     discover: (root) => discoverDocs(root, includes(root)),
     row: (text, f) => {
       const x = extract(text, f.path);
       return [f.path, x.title, x.headings, text];
     },
-    format: (root, r) => [r.score.toFixed(3), r.path, r.title, docSnippet(r)].map(cell),
-  },
+    format: (root, r) => [r.score.toFixed(3), r.path, r.title, docSnippet(r)].map(cell)
+  }
 };
-
 async function main() {
   if (!nodeOk()) die(`gauntlet-spec-index needs Node >=24.15.0 (found ${process.versions.node})`);
   const { query: text, corpus: name, limit, exclude } = parseArgs(process.argv.slice(2));
@@ -397,15 +439,15 @@ async function main() {
   const db = await openDb(root);
   refresh(db, root, corpus);
   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"));
+  const out = [corpus.header.join("	")];
+  for (const r of rows) out.push(corpus.format(root, r).join("	"));
   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`);
+    process.stderr.write(`gauntlet-spec-index: ${name} corpus has ${n} documents - too small for the confidence rule; no rows returned
+`);
   }
   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

@@ -8,6 +8,7 @@ import { fileURLToPath } from "node:url";
 import { DatabaseSync } from "node:sqlite";
 
 const CLI = join(dirname(fileURLToPath(import.meta.url)), "gauntlet-spec-index.mjs");
+const EMPTY_AGENT = mkdtempSync(join(tmpdir(), "gsi-empty-agent-"));
 const DRAFT = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
 const HEADER = ["score", "path", "service", "title", "status", "shipped_at", "state", "files", "snippet"];
 const DOCS_HEADER = ["score", "path", "title", "snippet"];
@@ -68,7 +69,7 @@ const repo = () => {
 };
 
 const run = (cwd, args) => {
-  const r = spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: "utf8" });
+  const r = spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: "utf8", env: { ...process.env, PI_CODING_AGENT_DIR: EMPTY_AGENT } });
   const lines = r.stdout.split("\n").filter(Boolean);
   return { status: r.status, stderr: r.stderr, stdout: r.stdout, header: lines[0]?.split("\t"), rows: lines.slice(1).map((l) => l.split("\t")) };
 };
@@ -82,6 +83,45 @@ const withDb = (root, fn) => {
   }
 };
 
+test("S1: a repo with only docs/specs/ is indexed under the default dirs", (t) => {
+  const root = gitRepo(); t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "docs/specs/a.md", "# Alpha zephyr widget\n\n**Goal:** rank the widget.\n");
+  for (const n of ["one", "two", "three", "four", "five", "six", "seven", "eight", "nine"]) write(root, `docs/specs/filler-${n}.md`, filler(n));
+  commit(root);
+  const r = run(root, ["--query", "zephyr widget"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["docs/specs/a.md"]);
+});
+
+test("S2: repo flowGuards.specDirs replaces the defaults for the specs corpus", (t) => {
+  const root = gitRepo(); t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, ".pi/settings.json", JSON.stringify({ piGauntlet: { flowGuards: { specDirs: ["design/specs"] } } }));
+  write(root, "design/specs/a.md", "# Alpha zephyr widget\n\n**Goal:** rank the widget.\n");
+  write(root, "doc/specs/decoy.md", "# zephyr widget decoy\n");
+  write(root, "docs/specs/decoy2.md", "# zephyr widget decoy two\n");
+  for (const n of ["one", "two", "three", "four", "five", "six", "seven", "eight", "nine"]) write(root, `design/specs/filler-${n}.md`, filler(n));
+  commit(root);
+  const r = run(root, ["--query", "zephyr widget"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["design/specs/a.md"]);
+});
+
+test("S3: docs corpus excludes configured spec and plan dirs by literal path components, including glob metacharacters", (t) => {
+  const root = gitRepo(); t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, ".pi/settings.json", JSON.stringify({ piGauntlet: { flowGuards: { specDirs: ["docs/[draft]/specs"] } } }));
+  write(root, "docs/[draft]/specs/s.md", decoy);
+  write(root, "docs/[draft]/plans/p.md", decoy);
+  write(root, "docs/guide.md", "# Guide\n\n## Configuring the ptarmigan gannet\n\nprose\n");
+  for (let n = 1; n <= 4; n++) write(root, `docs/filler-${n}.md`, docFiller(n));
+  commit(root);
+  const r = run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["docs/guide.md"]);
+  const specs = run(root, ["--query", "ptarmigan gannet"]);
+  assert.equal(specs.status, 0, specs.stderr);
+  assert.ok(withDb(root, (db) => db.prepare("SELECT path FROM specs").all().map((x) => x.path)).includes("docs/[draft]/specs/s.md"));
+});
+
 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 }));