pi-gauntlet 5.8.1 → 5.9.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v5.9.1 - 2026-09-17
+
+- Process in primary, work by path: `plan_check` roots at the plan's checkout, settings load from the session cwd's checkout toplevel, the branch-switch guard evaluates the command's `-C`/`cd` target, telemetry commits on the spec's checkout, and ship detection accepts `git -C <worktree> push` / `merge --squash`. Stage skills carry the worktree path as a value (dispatch `cwd`, `git -C`, subshell) - a new CI lint keeps them that way; `finishing-a-development-branch` takes `<worktree-path>` as a mandatory argument. Requires git >= 2.31. ([#37](https://github.com/jjuraszek/pi-gauntlet/issues/37))
+
+## v5.9.0 - 2026-09-17
+
+- Added `gauntlet-spec-index`, a build-on-query FTS5 search over root and one-level service spec corpora with a per-worktree cache and telemetry-enriched tabular results; brainstorming uses it to find predecessor specs. Requires Node >=24.15.0. (#34)
+
 ## v5.8.1 - 2026-09-17
 
 - chase-bug hotfix: the implementer proves its worktree binding first, addresses every mutating git command with `git -C`, runs with a fresh context, and the parent aborts non-destructively on any primary-checkout drift after each implementer return; `ci.mjs` asserts the guard text ([#36](https://github.com/jjuraszek/pi-gauntlet/issues/36))

package/README.md

@@ -75,6 +75,8 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
 pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs, and warns once if the main loop writes code during implement (subagents own implement-phase edits). A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
 
+**Worktree contract.** pi runs in the primary checkout; the work happens in `.worktrees/<branch>`. Skills never `cd` there - the worktree path is a value from the `using-git-worktrees` report (or the handoff brief on `gauntlet-resume`), carried as dispatch `cwd: "<path>"`, as `git -C <path>`, or as `(cd "<path>" && <cmd>)` for other cwd-bound commands; the runtime extensions derive the checkout from the artifact path they act on. Requires git >= 2.31.
+
 ## Key concepts
 
 | Term | Meaning |
@@ -116,6 +118,10 @@ pi install npm:pi-gauntlet
 
 Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. See [doc/install-internals.md](./doc/install-internals.md) for what the postinstall step actually does (symlink vs copy, `PI_GAUNTLET_AGENT_DIR`, upgrading from the pre-rename package).
 
+## Spec search index
+
+`gauntlet-spec-index` provides lexical search across `doc/specs/*.md` at the repository root and one service level down. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--limit N]`; it requires Node >=24.15.0, refreshes its FTS5 index on every query, and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `files`, and `snippet` columns. The per-worktree cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`.
+
 For local development against a checkout instead of npm:
 
 ```bash

package/bin/gauntlet-spec-index.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+// Lexical search over the spec corpus. Build-on-query: refresh a per-worktree
+// FTS5 cache by mtime+size, then rank with bm25 and join telemetry at output.
+import { readFileSync, appendFileSync, existsSync, statSync, readdirSync, mkdirSync, rmSync, realpathSync } from "node:fs";
+import { join, dirname, basename, isAbsolute } from "node:path";
+import { execFileSync } from "node:child_process";
+import process from "node:process";
+import { parse as parseYaml } from "yaml";
+
+const SCHEMA_VERSION = 1;
+const MIN_NODE = [24, 15, 0];
+const DRAFT_MARKER = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
+const EXCLUDE_LINE = "/.pi/gauntlet/index.sqlite*";
+const SKIP_DIRS = new Set([".worktrees", "node_modules", "build"]);
+const HEADER = ["score", "path", "service", "title", "status", "shipped_at", "files", "snippet"];
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS meta  (key TEXT PRIMARY KEY, value TEXT);
+  CREATE TABLE IF NOT EXISTS files (path TEXT PRIMARY KEY, mtime_ms INTEGER, size INTEGER);
+  CREATE VIRTUAL TABLE IF NOT EXISTS specs USING fts5(
+    path UNINDEXED, service UNINDEXED, title, goal, headings, body,
+    tokenize = 'porter unicode61');
+`;
+
+const usage = () => {
+  process.stderr.write('usage: gauntlet-spec-index --query "<text>" [--limit N]\n');
+  process.exit(1);
+};
+const die = (msg) => {
+  process.stderr.write(`${msg}\n`);
+  process.exit(2);
+};
+
+function parseArgs(argv) {
+  let query;
+  let limit = 10;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--query" && argv[i + 1] !== undefined) query = argv[++i];
+    else if (argv[i] === "--limit" && /^[1-9]\d*$/.test(argv[i + 1] ?? "")) limit = Number(argv[++i]);
+    else usage();
+  }
+  if (query === undefined) usage();
+  return { query, limit };
+}
+
+function nodeOk() {
+  const cur = process.versions.node.split(".").map(Number);
+  for (let i = 0; i < 3; i++) if (cur[i] !== MIN_NODE[i]) return cur[i] > MIN_NODE[i];
+  return true;
+}
+
+const git = (cwd, args) => execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+
+function repoRoot() {
+  try {
+    return git(process.cwd(), ["rev-parse", "--show-toplevel"]);
+  } catch {
+    return die("gauntlet-spec-index: not inside a git repository");
+  }
+}
+
+function discover(root) {
+  const out = [];
+  const seen = new Set();
+  const collect = (relDir, service) => {
+    const abs = join(root, relDir);
+    let real;
+    try {
+      real = realpathSync(abs);
+      if (!statSync(real).isDirectory()) return;
+    } catch {
+      return;
+    }
+    if (seen.has(real)) return;
+    seen.add(real);
+    for (const name of readdirSync(abs).sort()) {
+      if (!name.endsWith(".md")) continue;
+      const rel = `${relDir}/${name}`;
+      const st = statSync(join(root, rel));
+      if (st.isFile()) out.push({ path: rel, service, mtime_ms: Math.trunc(st.mtimeMs), size: st.size });
+    }
+  };
+  collect("doc/specs", "root");
+  const entries = readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const e of entries) {
+    if (e.name.startsWith(".") || SKIP_DIRS.has(e.name)) continue;
+    if (!e.isDirectory() && !e.isSymbolicLink()) continue;
+    collect(`${e.name}/doc/specs`, e.name);
+  }
+  return out;
+}
+
+function ensureExclude(root) {
+  const rel = git(root, ["rev-parse", "--git-path", "info/exclude"]);
+  const abs = isAbsolute(rel) ? rel : join(root, rel);
+  const cur = existsSync(abs) ? readFileSync(abs, "utf8") : "";
+  if (cur.split("\n").includes(EXCLUDE_LINE)) return;
+  mkdirSync(dirname(abs), { recursive: true });
+  appendFileSync(abs, `${cur.length && !cur.endsWith("\n") ? "\n" : ""}${EXCLUDE_LINE}\n`);
+}
+
+async function openDb(root) {
+  const { DatabaseSync } = await import("node:sqlite");
+  const dbPath = join(root, ".pi/gauntlet/index.sqlite");
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const fresh = !existsSync(dbPath);
+  const create = () => {
+    const db = new DatabaseSync(dbPath);
+    db.exec("PRAGMA busy_timeout = 2000");
+    try {
+      db.exec(SCHEMA);
+    } catch (e) {
+      if (/fts5/i.test(e.message)) die("gauntlet-spec-index: this Node's SQLite has no FTS5 module");
+      throw e;
+    }
+    db.prepare("INSERT OR REPLACE INTO meta VALUES ('schema_version', ?)").run(String(SCHEMA_VERSION));
+    return db;
+  };
+  const rebuild = (db) => {
+    try { db?.close(); } catch {}
+    for (const suffix of ["", "-journal", "-wal", "-shm"]) rmSync(dbPath + suffix, { force: true });
+    return create();
+  };
+  if (fresh) ensureExclude(root);
+  let db;
+  try {
+    db = new DatabaseSync(dbPath);
+    db.exec("PRAGMA busy_timeout = 2000");
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+    if (Number(row?.value) !== SCHEMA_VERSION) return rebuild(db);
+    return db;
+  } catch (e) {
+    const missingMeta = e?.code === "ERR_SQLITE_ERROR" && e.errcode === 1 && /no such table:\s*meta/i.test(e.message);
+    const corrupt = e?.code === "ERR_SQLITE_ERROR" && (e.errcode === 11 || e.errcode === 26);
+    if (missingMeta || corrupt) return rebuild(db);
+    try { db?.close(); } catch {}
+    throw e;
+  }
+}
+
+function extract(text, path) {
+  const lines = text.split(/\r?\n/);
+  const title = lines.find((l) => l.startsWith("# "))?.slice(2).trim() || basename(path, ".md");
+  const goal = lines.find((l) => l.startsWith("**Goal:**"))?.slice("**Goal:**".length).trim() ?? "";
+  const headings = lines.filter((l) => /^##{1,2} /.test(l)).map((l) => l.replace(/^#+ /, "")).join("\n");
+  return { title, goal, headings };
+}
+
+function refresh(db, root, corpus) {
+  const known = new Map(db.prepare("SELECT path, mtime_ms, size FROM files").all().map((r) => [r.path, r]));
+  const present = new Set(corpus.map((f) => f.path));
+  const delSpec = db.prepare("DELETE FROM specs WHERE path = ?");
+  const delFile = db.prepare("DELETE FROM files WHERE path = ?");
+  const insSpec = db.prepare("INSERT INTO specs (path, service, title, goal, headings, body) VALUES (?, ?, ?, ?, ?, ?)");
+  const putFile = db.prepare("INSERT OR REPLACE INTO files (path, mtime_ms, size) VALUES (?, ?, ?)");
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    for (const path of known.keys()) if (!present.has(path)) { delSpec.run(path); delFile.run(path); }
+    for (const f of corpus) {
+      const k = known.get(f.path);
+      if (k && k.mtime_ms === f.mtime_ms && k.size === f.size) continue;
+      const text = readFileSync(join(root, f.path), "utf8");
+      delSpec.run(f.path);
+      if (text.split(/\r?\n/, 1)[0] === DRAFT_MARKER) { delFile.run(f.path); continue; }
+      const x = extract(text, f.path);
+      insSpec.run(f.path, f.service, x.title, x.goal, x.headings, text);
+      putFile.run(f.path, f.mtime_ms, f.size);
+    }
+    db.exec("COMMIT");
+  } catch (e) {
+    db.exec("ROLLBACK");
+    throw e;
+  }
+}
+
+const toMatch = (query) =>
+  query.split(/\s+/).filter((t) => t.length >= 2).map((t) => `"${t.replaceAll('"', '""')}"`).join(" OR ");
+
+function telemetry(root, specPath) {
+  const blank = { status: null, shipped_at: null, files: null };
+  const p = join(root, ".pi/gauntlet/telemetry", specPath.replace(/\.md$/, ".yaml"));
+  if (!existsSync(p)) return blank;
+  let rec;
+  try {
+    rec = parseYaml(readFileSync(p, "utf8"));
+  } catch {
+    process.stderr.write(`gauntlet-spec-index: warning: unreadable telemetry ${p}\n`);
+    return blank;
+  }
+  if (!rec || typeof rec !== "object") return blank;
+  const mf = rec.derived?.modified_files;
+  return { status: rec.status ?? null, shipped_at: rec.shipped_at ?? null, files: Array.isArray(mf) ? mf.length : null };
+}
+
+const cell = (v) => (v === null || v === undefined ? "" : String(v).replace(/\s+/g, " ").trim());
+
+async function main() {
+  if (!nodeOk()) die(`gauntlet-spec-index needs Node >=24.15.0 (found ${process.versions.node})`);
+  const { query, limit } = parseArgs(process.argv.slice(2));
+  const match = toMatch(query);
+  if (!match) usage();
+  const root = repoRoot();
+  const db = await openDb(root);
+  refresh(db, root, discover(root));
+  const rows = db.prepare(
+    `SELECT path, service, title,
+            bm25(specs, 0, 0, 10.0, 5.0, 2.0, 1.0) AS score,
+            snippet(specs, 5, '', '', '...', 12) AS snippet
+     FROM specs WHERE specs MATCH ?
+     ORDER BY score LIMIT ?`,
+  ).all(match, limit);
+  const out = [HEADER.join("\t")];
+  for (const r of rows) {
+    const t = telemetry(root, r.path);
+    out.push([r.score.toFixed(3), r.path, r.service, r.title, t.status, t.shipped_at, t.files, r.snippet].map(cell).join("\t"));
+  }
+  process.stdout.write(out.join("\n") + "\n");
+  db.close();
+}
+
+main().catch((e) => {
+  if (e?.code === "ERR_SQLITE_ERROR") die(`gauntlet-spec-index: ${e.message}`);
+  throw e;
+});

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

@@ -0,0 +1,173 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, utimesSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { DatabaseSync } from "node:sqlite";
+
+const CLI = join(dirname(fileURLToPath(import.meta.url)), "gauntlet-spec-index.mjs");
+const DRAFT = "# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing";
+
+const write = (root, rel, text) => {
+  mkdirSync(join(root, dirname(rel)), { recursive: true });
+  writeFileSync(join(root, rel), text);
+};
+
+const repo = () => {
+  const root = mkdtempSync(join(tmpdir(), "gsi-"));
+  spawnSync("git", ["init", "-q"], { cwd: root });
+  write(root, "doc/specs/a.md", "# Alpha zephyr widget\n\n**Goal:** rank the widget.\n\n## Design\n\nbody text\n");
+  write(root, "svc-a/doc/specs/b.md", "# Beta service\n\n**Goal:** unrelated.\n\nDeep in the body a zephyr appears.\n");
+  write(root, ".worktrees/x/doc/specs/decoy1.md", "# zephyr decoy one\n");
+  write(root, "build/doc/specs/decoy2.md", "# zephyr decoy two\n");
+  write(root, "apps/svc/doc/specs/decoy3.md", "# zephyr decoy three\n");
+  write(root, "doc/specs/draft.md", `${DRAFT}\n\nzephyr zephyr zephyr\n`);
+  spawnSync("git", ["add", "-A"], { cwd: root });
+  spawnSync("git", ["-c", "user.name=t", "-c", "user.email=t@t", "commit", "-q", "-m", "fixture"], { cwd: root });
+  return root;
+};
+
+const run = (cwd, args) => {
+  const r = spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: "utf8" });
+  const lines = r.stdout.split("\n").filter(Boolean);
+  return { status: r.status, stderr: r.stderr, header: lines[0]?.split("\t"), rows: lines.slice(1).map((l) => l.split("\t")) };
+};
+const paths = (res) => res.rows.map((r) => r[1]);
+const withDb = (root, fn) => {
+  const database = new DatabaseSync(join(root, ".pi/gauntlet/index.sqlite"));
+  try {
+    return fn(database);
+  } finally {
+    database.close();
+  }
+};
+
+test("1: corpus boundary, ordering, draft skip, git status clean, exclude written once", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const r1 = run(root, ["--query", "zephyr"]);
+  assert.equal(r1.status, 0, r1.stderr);
+  assert.deepEqual(paths(r1), ["doc/specs/a.md", "svc-a/doc/specs/b.md"]);
+  assert.deepEqual(r1.rows.map((r) => r[2]), ["root", "svc-a"]);
+  const status = spawnSync("git", ["status", "--porcelain"], { cwd: root, encoding: "utf8" }).stdout;
+  assert.equal(status, "");
+  run(root, ["--query", "zephyr"]);
+  const exclude = readFileSync(join(root, ".git/info/exclude"), "utf8");
+  assert.equal(exclude.split("\n").filter((l) => l === "/.pi/gauntlet/index.sqlite*").length, 1);
+});
+
+test("2: title outranks body; --limit 1; default up to 10", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  for (let i = 0; i < 12; i++) write(root, `doc/specs/many-${i}.md`, `# Spec ${i}\n\nquokka\n`);
+  assert.deepEqual(paths(run(root, ["--query", "zephyr", "--limit", "1"])), ["doc/specs/a.md"]);
+  assert.equal(run(root, ["--query", "quokka"]).rows.length, 10);
+});
+
+test("3: incremental refresh updates only the edited row; delete removes rows", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  run(root, ["--query", "zephyr"]);
+  const before = withDb(root, (database) => Object.fromEntries(database.prepare("SELECT path, mtime_ms, size FROM files").all().map((r) => [r.path, `${r.mtime_ms}:${r.size}`])));
+  const b = join(root, "svc-a/doc/specs/b.md");
+  writeFileSync(b, readFileSync(b, "utf8") + "\nwombat\n");
+  utimesSync(b, new Date(), new Date(Date.now() + 5000));
+  assert.deepEqual(paths(run(root, ["--query", "wombat"])), ["svc-a/doc/specs/b.md"]);
+  const after = withDb(root, (database) => Object.fromEntries(database.prepare("SELECT path, mtime_ms, size FROM files").all().map((r) => [r.path, `${r.mtime_ms}:${r.size}`])));
+  assert.equal(after["doc/specs/a.md"], before["doc/specs/a.md"]);
+  assert.notEqual(after["svc-a/doc/specs/b.md"], before["svc-a/doc/specs/b.md"]);
+  const count = (root, sql, path) => withDb(root, (database) => Object.values(database.prepare(sql).get(path))[0]);
+  assert.equal(count(root, "SELECT count(*) FROM specs WHERE path = ?", "svc-a/doc/specs/b.md"), 1);
+  rmSync(b);
+  run(root, ["--query", "zephyr"]);
+  assert.equal(count(root, "SELECT count(*) FROM specs WHERE path = ?", "svc-a/doc/specs/b.md"), 0);
+  assert.equal(count(root, "SELECT count(*) FROM files WHERE path = ?", "svc-a/doc/specs/b.md"), 0);
+});
+
+test("4: schema_version mismatch rebuilds the db", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  run(root, ["--query", "zephyr"]);
+  withDb(root, (database) => database.prepare("UPDATE meta SET value = '999' WHERE key = 'schema_version'").run());
+  const r = run(root, ["--query", "zephyr"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(paths(r).length, 2);
+  assert.equal(withDb(root, (database) => database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get().value), "1");
+});
+
+test("5: a non-SQLite database is rebuilt", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, ".pi/gauntlet/index.sqlite", "not a sqlite database");
+  const r = run(root, ["--query", "zephyr"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["doc/specs/a.md", "svc-a/doc/specs/b.md"]);
+  assert.equal(withDb(root, (database) => database.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get().value), "1");
+});
+
+test("6: telemetry join is output-only and tolerant", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  run(root, ["--query", "zephyr"]);
+  const filesBefore = withDb(root, (database) => JSON.stringify(database.prepare("SELECT * FROM files ORDER BY path").all()));
+  write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: shipped\nshipped_at: 2026-09-17T10:00:00Z\nderived:\n  modified_files:\n    - x\n    - y\n");
+  let r = run(root, ["--query", "zephyr"]);
+  assert.deepEqual(r.rows[0].slice(4, 7), ["shipped", "2026-09-17T10:00:00Z", "2"]);
+  assert.equal(withDb(root, (database) => JSON.stringify(database.prepare("SELECT * FROM files ORDER BY path").all())), filesBefore);
+  write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: in_progress\nshipped_at: 2026-09-18T10:00:00Z\n");
+  r = run(root, ["--query", "zephyr"]);
+  assert.deepEqual(r.rows[0].slice(4, 7), ["in_progress", "2026-09-18T10:00:00Z", ""]);
+  write(root, ".pi/gauntlet/telemetry/doc/specs/a.yaml", "status: [unclosed\n");
+  r = run(root, ["--query", "zephyr"]);
+  assert.equal(r.status, 0);
+  assert.deepEqual(r.rows[0].slice(4, 7), ["", "", ""]);
+  assert.match(r.stderr, /a\.yaml/);
+});
+
+test("7: query sanitising tolerates embedded quotes", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/q.md", '# Quotes\n\nfoo"bar and "plain" words\n');
+  let r = run(root, ["--query", 'foo"bar']);
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(paths(r).includes("doc/specs/q.md"));
+  r = run(root, ["--query", '"plain"']);
+  assert.equal(r.status, 0, r.stderr);
+  assert.ok(paths(r).includes("doc/specs/q.md"));
+});
+
+test("8: one line per hit, eight tab-separated fields, whitespace collapsed", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/t.md", "# Tab\tin\ttitle narwhal\n\nbody narwhal\nline two\twith tab narwhal\r\nmore\n");
+  const r = run(root, ["--query", "narwhal"]);
+  assert.equal(r.header.length, 8);
+  assert.equal(r.rows.length, 1);
+  assert.equal(r.rows[0].length, 8);
+  assert.equal(r.rows[0][3], "Tab in title narwhal");
+});
+
+test("9: supersession banner is plain body text", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/specs/old.md", "# Old\n\n> **Superseded by:** [doc/specs/a.md](./a.md) - fully\n\nplatypus\n");
+  const r = run(root, ["--query", "Superseded"]);
+  assert.deepEqual(paths(r), ["doc/specs/old.md"]);
+  assert.deepEqual(r.rows[0].slice(4, 7), ["", "", ""]);
+  assert.deepEqual(r.header, ["score", "path", "service", "title", "status", "shipped_at", "files", "snippet"]);
+});
+
+test("10: usage errors exit 1, environment errors exit 2", (t) => {
+  const root = repo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  assert.equal(run(root, []).status, 1);
+  assert.equal(run(root, ["--query", "zephyr", "--limit", "0"]).status, 1);
+  assert.equal(run(root, ["--query", "zephyr", "--limit", "x"]).status, 1);
+  assert.equal(run(root, ["--query", "zephyr", "--json"]).status, 1);
+  assert.equal(run(root, ["--query", "a"]).status, 1);
+  const bare = mkdtempSync(join(tmpdir(), "gsi-bare-"));
+  t.after(() => rmSync(bare, { recursive: true, force: true }));
+  assert.equal(run(bare, ["--query", "zephyr"]).status, 2);
+});

package/extensions/lib/checkout.test.ts

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { checkoutOf, parseCheckout, gitSync, type GitResult } from "./checkout.ts";
+
+const tempDirs: string[] = [];
+after(() => { for (const d of tempDirs) rmSync(d, { recursive: true, force: true }); });
+const tmp = () => { const d = realpathSync(mkdtempSync(join(tmpdir(), "checkout-test-"))); tempDirs.push(d); return d; };
+
+const out = (lines: string[]): GitResult => ({ code: 0, stdout: lines.join("\n") + "\n" });
+
+test("parseCheckout: primary checkout when git-dir equals common-dir", () => {
+  assert.deepEqual(parseCheckout(out(["/repo", "/repo/.git", "/repo/.git"])), { toplevel: "/repo", isPrimary: true });
+});
+
+test("parseCheckout: linked worktree when the dirs differ", () => {
+  assert.deepEqual(
+    parseCheckout(out(["/repo/.worktrees/x", "/repo/.git/worktrees/x", "/repo/.git"])),
+    { toplevel: "/repo/.worktrees/x", isPrimary: false },
+  );
+});
+
+test("parseCheckout: nonzero code or fewer than three lines -> undefined", () => {
+  assert.equal(parseCheckout({ code: 128, stdout: "" }), undefined);
+  assert.equal(parseCheckout(out(["/repo", "/repo/.git"])), undefined);
+});
+
+test("checkoutOf: a file path runs git in its dirname", async () => {
+  const dir = tmp();
+  writeFileSync(join(dir, "spec.md"), "# s\n");
+  const cwds: string[] = [];
+  const git = (_args: string[], cwd: string): GitResult => { cwds.push(cwd); return out([dir, dir + "/.git", dir + "/.git"]); };
+  assert.deepEqual(await checkoutOf(join(dir, "spec.md"), git), { toplevel: dir, isPrimary: true });
+  assert.deepEqual(cwds, [dir]);
+});
+
+test("checkoutOf: a nonexistent leaf walks up to the nearest existing ancestor", async () => {
+  const dir = tmp();
+  mkdirSync(join(dir, "doc"));
+  const cwds: string[] = [];
+  const git = async (_args: string[], cwd: string): Promise<GitResult> => { cwds.push(cwd); return out([dir, dir + "/.git", dir + "/.git"]); };
+  await checkoutOf(join(dir, "doc", "specs", "new.md"), git);
+  assert.deepEqual(cwds, [join(dir, "doc")]);
+});
+
+test("checkoutOf: an existing directory is used as-is", async () => {
+  const dir = tmp();
+  const cwds: string[] = [];
+  await checkoutOf(dir, (_a, cwd) => { cwds.push(cwd); return out([dir, dir + "/.git", dir + "/.git"]); });
+  assert.deepEqual(cwds, [dir]);
+});
+
+test("gitSync: never throws; nonzero code outside a repo", () => {
+  const r = gitSync(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"], tmp());
+  assert.notEqual(r.code, 0);
+  assert.equal(typeof r.stdout, "string");
+});

package/extensions/lib/checkout.ts

@@ -0,0 +1,57 @@
+// One checkout resolver for every extension that needs "which git checkout owns this
+// path" (#37): plan_check, the settings loader, Guard 2, telemetry. `--path-format=absolute`
+// (git >= 2.31) makes git-dir and common-dir comparable as strings from any subdirectory.
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+
+export type GitResult = { code: number; stdout: string };
+export type Checkout = { toplevel: string; isPrimary: boolean };
+
+export const CHECKOUT_ARGS = ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"];
+
+// isPrimary = gitDir === commonDir (both absolute thanks to --path-format).
+export function parseCheckout(r: GitResult): Checkout | undefined {
+  if (r.code !== 0) return undefined;
+  const lines = r.stdout.trim().split("\n").map((l) => l.trim());
+  if (lines.length < 3 || !lines[0]) return undefined;
+  return { toplevel: lines[0], isPrimary: lines[1] === lines[2] };
+}
+
+const isDir = (p: string): boolean => {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+// Nearest existing directory at or above absPath: the path itself when it is a directory,
+// else its dirname, walking up. Covers the first write into a not-yet-existing doc/specs/.
+export function nearestExistingDir(absPath: string): string {
+  let p = absPath;
+  while (!(existsSync(p) && isDir(p))) {
+    const parent = dirname(p);
+    if (parent === p) return p;
+    p = parent;
+  }
+  return p;
+}
+
+export async function checkoutOf(
+  absPath: string,
+  git: (args: string[], cwd: string) => GitResult | Promise<GitResult>,
+): Promise<Checkout | undefined> {
+  return parseCheckout(await git(CHECKOUT_ARGS, nearestExistingDir(absPath)));
+}
+
+// Never throws: any failure (not a repo, missing dir, old git) is a nonzero code.
+export const gitSync = (args: string[], cwd: string): GitResult => {
+  try {
+    const stdout = execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    return { code: 0, stdout };
+  } catch (e) {
+    const status = (e as { status?: unknown }).status;
+    return { code: typeof status === "number" ? status : 1, stdout: "" };
+  }
+};

package/extensions/lib/gauntlet-settings-loader.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { after, test } from "node:test";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadGauntletSettings } from "./gauntlet-settings-loader.ts";
+
+const tempDirs: string[] = [];
+after(() => { for (const d of tempDirs) rmSync(d, { recursive: true, force: true }); });
+const tmp = () => { const d = realpathSync(mkdtempSync(join(tmpdir(), "settings-loader-test-"))); tempDirs.push(d); return d; };
+const gitRepo = () => { const d = tmp(); execFileSync("git", ["init", "-q", d]); return d; };
+
+test("settings resolve from the checkout root when cwd is a subdirectory (AC 2)", () => {
+  const repo = gitRepo();
+  mkdirSync(join(repo, ".pi"));
+  mkdirSync(join(repo, "doc"));
+  writeFileSync(join(repo, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { specCouncil: { members: ["p/m"] } } }));
+  const loaded = loadGauntletSettings(join(repo, "doc"), "/tmp/pi-gauntlet-test-agent");
+  assert.equal(loaded.root, repo);
+  assert.deepEqual(loaded.gauntlet.specCouncil, { members: ["p/m"] });
+  assert.deepEqual(loaded.errors, []);
+});
+
+test("outside any checkout the loader falls back to cwd", () => {
+  const dir = tmp();
+  mkdirSync(join(dir, ".pi"));
+  writeFileSync(join(dir, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { flowGuards: { enforce: false } } }));
+  const loaded = loadGauntletSettings(dir, "/tmp/pi-gauntlet-test-agent");
+  assert.equal(loaded.root, dir);
+  assert.deepEqual(loaded.gauntlet.flowGuards, { enforce: false });
+});

package/extensions/lib/gauntlet-settings-loader.ts

@@ -2,22 +2,26 @@
 // ci.mjs unit tests. Only pi-loaded extensions import this file.
 import { SettingsManager, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { mergeGauntlet, type PiGauntlet } from "./gauntlet-settings.ts";
+import { gitSync, parseCheckout } from "./checkout.ts";
 
 export interface LoadedGauntlet {
   gauntlet: PiGauntlet;
   errors: string[];
+  // Checkout toplevel the repo layer was read from (cwd itself outside any checkout).
+  root: string;
 }
 
-// Reads the preset (agentDir/settings.json) and repo (cwd/.pi/settings.json)
-// layers via pi's own SettingsManager and returns the whole-object second-level
-// merge (repo over preset). SettingsManager never throws on a bad file - it
-// substitutes {} for that layer and records the error, surfaced here via errors[]
-// so callers can report a degraded read instead of failing silent.
+// Reads the preset (agentDir/settings.json) and repo (<root>/.pi/settings.json) layers
+// via pi's own SettingsManager, where <root> is the git toplevel of cwd - pi launched in a
+// subdirectory or a linked worktree still finds that checkout's file (#37). SettingsManager
+// never throws on a bad file - it substitutes {} for that layer and records the error,
+// surfaced here via errors[] so callers can report a degraded read instead of failing silent.
 export function loadGauntletSettings(cwd: string, agentDir: string = getAgentDir()): LoadedGauntlet {
-  const sm = SettingsManager.create(cwd, agentDir);
+  const root = parseCheckout(gitSync(["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"], cwd))?.toplevel ?? cwd;
+  const sm = SettingsManager.create(root, agentDir);
   const preset = sm.getGlobalSettings() as { piGauntlet?: Record<string, unknown> };
   const repo = sm.getProjectSettings() as { piGauntlet?: Record<string, unknown> };
   const gauntlet = mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet);
   const errors = sm.drainErrors().map((e) => `${e.scope}: ${e.error.message}`);
-  return { gauntlet, errors };
+  return { gauntlet, errors, root };
 }

package/extensions/lib/phase-tracker-helpers.test.ts

@@ -10,6 +10,7 @@ import {
   implementExemptDirs,
   nextGauntletEntered,
   phaseLabel,
+  parseGitCommand,
   parseGitCommit,
   resolveRepoDir,
   findMarkerFile,
@@ -78,6 +79,22 @@ test("phaseLabel: with and without substep", () => {
   assert.equal(phaseLabel("brainstorm", undefined), "brainstorm");
 });
 
+test("parseGitCommand: branch subcommands with and without global flags", () => {
+  const SWITCH = /switch(?=\s|$)/;
+  const CHECKOUT_B = /checkout\s+-[bB](?=\s|$)/;
+  assert.deepEqual(parseGitCommand("git switch -c y", SWITCH), { cPath: undefined, cdPath: undefined });
+  assert.deepEqual(parseGitCommand("git -C .worktrees/x switch -c y", SWITCH), { cPath: ".worktrees/x", cdPath: undefined });
+  assert.deepEqual(parseGitCommand("git --no-pager -C p checkout -b y", CHECKOUT_B), { cPath: "p", cdPath: undefined });
+  assert.deepEqual(parseGitCommand("cd .worktrees/x && git checkout -b y", CHECKOUT_B), { cPath: undefined, cdPath: ".worktrees/x" });
+  assert.equal(parseGitCommand("git checkout file.ts", CHECKOUT_B), undefined);
+  assert.equal(parseGitCommand("git switcheroo", SWITCH), undefined);
+  assert.equal(parseGitCommand("echo git switch", SWITCH), undefined);
+});
+
+test("parseGitCommit is parseGitCommand with the commit subcommand", () => {
+  assert.deepEqual(parseGitCommit("git -C /wt -c user.email=x commit"), parseGitCommand("git -C /wt -c user.email=x commit", /commit(?=\s|$)/));
+});
+
 test("parseGitCommit: plain, -am, chained after &&", () => {
   assert.ok(parseGitCommit('git commit -m "x"'));
   assert.ok(parseGitCommit("git commit -am 'x'"));