pi-gauntlet 5.23.1 → 6.0.1

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 }));