pi-gauntlet 5.8.0 → 5.9.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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))
+- `gauntlet-resume`: same-repository worktrees resume from a pi session launched in the primary checkout; cross-repository targets still stop, and reconstruction addresses the resolved worktree by path.
+
 ## v5.8.0 - 2026-09-17
 
 - New extension `telemetry`: records one committed YAML record per gauntlet run at `.pi/gauntlet/telemetry/<spec path>.yaml` (phase timing, model/thinking snapshots, per-persona dispatches and tokens, reviewer findings, gate and fix-round counters, plan totals, last test result, diff buckets and modified files at ship), keyed by spec path and continued across sessions; pathspec-commits the record at checkpoints; reconciles a failed ship command; freezes after squash/PR/discard. During brainstorm a `write` into a spec whose record is shipped is blocked (`edit` passes). Settings `piGauntlet.telemetry.{enabled,dir,buckets}`. (#33)

package/README.md

@@ -116,6 +116,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -31,6 +31,12 @@
     "bin",
     "CHANGELOG.md"
   ],
+  "bin": {
+    "gauntlet-spec-index": "bin/gauntlet-spec-index.mjs"
+  },
+  "engines": {
+    "node": ">=24.15.0"
+  },
   "pi": {
     "skills": [
       "./skills"

package/skills/brainstorming/SKILL.md

@@ -22,7 +22,7 @@ You **may**:
 - Read code and docs
 - Run the existing system to observe its **current** behaviour — this is research and feeds the spec (boot a local service, replay a sample request, capture a baseline classification, etc.)
 - Write to the project's `doc/specs/` directory
-- `edit` a predecessor spec in the project's spec directory to add a supersession banner (see [Marking superseded specs](#marking-superseded-specs)) — the `edit` prohibition at spec-writing binds the spec being written, not a predecessor file
+- `edit` a predecessor spec in the project's spec directory to add a supersession banner (see [Marking superseded specs](reference/superseding.md)) — the `edit` prohibition at spec-writing binds the spec being written, not a predecessor file
 
 You may **not**:
 
@@ -65,7 +65,7 @@ Work through the items below **in order**. This is your own checklist to follow,
    then state the chat premise note (section 3) before approaches
 5. **Propose 2-3 approaches** — with trade-offs and a recommendation
 6. **Present the design** — in two rounds, one approval each
-7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](#marking-superseded-specs), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
+7. **Write the spec** — to `doc/specs/` (see [Filename Convention](#filename-convention)); then mark any known superseded predecessor(s) per [Marking superseded specs](reference/superseding.md), at the exact-order position defined in [Spec Self-Review](#spec-self-review-before-user-review-gate)
 8. **Spec self-review (lint)** — placeholder scan + internal consistency + documentation named, run inline
 9. **Critique pass (auto-dispatched)** — scope + ambiguity; the spec council via `/skill:roasting-the-spec` when `gauntlet_setting` returns verdict `council` (it applies its apply-set, including any external-ref inlining, to the spec before returning — see [Spec Council](#spec-council-optional)), else a fresh `worker` that applies its own fixes in place
 10. **Re-run placeholder scan** — after the critique pass returns, re-scan the **applied** spec for placeholders its edits may have introduced; if a predecessor banner exists, confirm its `<scope>` still matches the applied spec (critique edits can change what is superseded); surface any ambiguity the critique could not safely resolve at the user gate
@@ -239,25 +239,6 @@ overwrite reuses the path. If the questionary invalidated the slug, rename at
 spec-writing: write the spec at the new path **and delete the old draft file**
 (nothing was committed, so this is free).
 
-## Marking superseded specs
-
-When the new spec replaces a prior spec — fully or in part — (from the draft's scout recon or the request), mark the predecessor. No mechanical sweep: grep or path-overlap hits never decide supersession.
-
-- `edit` the predecessor spec (in the project's spec directory, per [Project Routing](#project-routing)) to insert, after its title line and a blank line, one banner line per successor:
-
-  ```markdown
-  > **Superseded by:** [<repo-relative path to successor>](<href relative to THIS file>) - <scope>
-  ```
-
-- The visible label is the successor's repo-relative path; the href is computed relative to the predecessor's own directory (Markdown resolves links from the containing file). Same directory: `[doc/specs/B.md](./B.md)`.
-- `<scope>` is the value after the ` - ` separator: `fully`, or the named superseded section(s), e.g. `"Settings resolution" section only`. The scope value itself carries no leading dash — the template above already supplies the separator.
-- Banners are **append-only**: add below any existing supersession lines, formatted or free-form prose. One old spec may accumulate banners from multiple successors. No migration, no dedup.
-- **No transitive rewrite**: if A points at B and B is later superseded by C, A keeps pointing at B; the reader hops.
-- **Mark, never delete.** Delete/archive policy is consumer territory via overrides.
-- **Coverage limits**: unmarked does NOT mean current (code drift, abandoned designs, and partial ships produce no successor spec); marked does NOT mean dead (partial supersession leaves live sections).
-- Predecessor in a **different service's spec directory**: out of scope — record it in the new spec's Open Questions instead of editing outside the write grant.
-- **Override contract**: the gauntlet overrides file (see Project overrides) may replace the banner *syntax*; placement, append-only, no-transitive-rewrite, and mark-never-delete stay fixed. A syntax override entry must itself state the scout-citation guidance for its format (the shipped `gatherer.md` guidance names only the default banner).
-
 ## Spec Self-Review (Before User Review Gate)
 
 Spec-writing replaces the context draft, in this exact order:
@@ -273,7 +254,7 @@ Spec-writing replaces the context draft, in this exact order:
    guard is a backstop, not the primary check.
 4. **After the line-1 check and before the inline lint**, `edit` any known
    predecessor spec to insert its supersession banner (see
-   [Marking superseded specs](#marking-superseded-specs)). This position is fixed:
+   [Marking superseded specs](reference/superseding.md)). This position is fixed:
    the banner is written after any slug rename, so it always cites the final path.
 
 After writing the spec to `<project>/doc/specs/<filename>.md` (per [Filename Convention](#filename-convention)) and before showing it to the user, run a self-review pass. **Read all five bullets first, then act:** only the **first three** run here at the main loop (the inline lint); the **last two** (scope + ambiguity) do **not** run inline — they are the dispatched critique pass (checklist item 9). Do not apply scope/ambiguity edits yourself.
@@ -328,7 +309,7 @@ subagent({ agent: "spec-summarizer", context: "fresh", async: false, cwd: "<abs
 
 `<SUMMARY_PATH>` above is a placeholder in the dispatch object; it means substitute the value of the shell variable `$SUMMARY_PATH` set above. The steps below use `$SUMMARY_PATH` (the shell form) once the value is in hand.
 
-Then commit the spec — staging any predecessor spec edited per [Marking superseded specs](#marking-superseded-specs) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
+Then commit the spec — staging any predecessor spec edited per [Marking superseded specs](reference/superseding.md) alongside it; a change request at the gate that renames, materially revises, or drops the spec also reconciles the predecessor's banner before recommitting. This commit is **unconditional**: the summary is only a gate aid, so a degraded or missing summary never blocks it. If the council path ran, include its audit (`Coverage:` when present, then `Applied:` / `Deferred:` / `Rejected:`, verbatim from `/skill:roasting-the-spec`'s return) in the **commit message body** - this is the durable, non-contractual record a finish-time revert reads back; the audit is never a committed spec section. Evaluate the summary in two stages (the **Degrade path** referenced in each is defined just below):
 
 1. **From the dispatch tool result, before the `Read`.** If the result is **not** an `"Output saved to: <path> (<N> KB, <M> lines)"` reference (e.g. an exit-0 save error returns the full inline output plus an "Output file error" line — the prunable shape, no file to read), or the reference reports under ~500 bytes, or a size grossly disproportionate to the spec (under ~2% of its byte size), or over ~45 KB (the `Read` truncates at 50KB / 2000 lines, so a larger file cannot render whole) — skip the `Read` and take the degrade path. Use the reference's reported figures; do not re-derive them.
 2. **The `Read` itself, as the last content-producing tool call before composing the gate.** `Read` `$SUMMARY_PATH` and paste its contents verbatim at the top of the gate. If the `Read` fails, returns 0 bytes, or reports truncation — take the degrade path. The `Read` must be last: pi-condense does not protect a `/tmp` read, so any turn boundary between the `Read` and the render lets the ~9KB read result be pruned, reproducing the bug.

package/skills/brainstorming/gatherer.md

@@ -35,6 +35,10 @@ subagent({
 Absolute `output:` paths are mandatory: relative paths in parallel mode resolve
 against the worktree and would get committed.
 
+`<SPEC_INDEX>` is `<directory of this skill's SKILL.md>/../../bin/gauntlet-spec-index.mjs`,
+resolved to an absolute path by the main loop from the skill's `<location>` in the system prompt
+before pasting the task.
+
 ## Task templates
 
 Scout (always dispatched):
@@ -46,12 +50,21 @@ Scout (always dispatched):
 > exact paths and line ranges. If a spec you cite carries a supersession marker
 > (default: a `> **Superseded by:**` banner; the project's overrides may define
 > another format), follow the successor for the superseded scope and cite it
-> instead; cite the old spec only for its unsuperseded sections. Predecessor
-> check: list the project's spec directory, read titles and `**Goal:**` lines,
-> open at most five whose topic matches this request, and name any whose design
-> this request replaces or amends with the section(s) affected -
-> `Predecessor: <path>, <scope>` - or `Predecessor: none`. Judge by topic; shared
-> file paths never decide. End with an
+> instead; cite the old spec only for its unsuperseded sections (banner contract:
+> `reference/superseding.md`). Predecessor check: compose a 5-15 term keyword query
+> from the request (topic nouns, component names, file names - not stop words; if
+> the request is only a ticket reference, take the terms from the ticket title via
+> the tracker CLI when one is available, otherwise use the fallback below). Run
+> `node <SPEC_INDEX> --query '<keywords>' --limit 10` from the worktree root,
+> keeping the keywords inside single quotes, and treat its rows as the candidate
+> list. If the command fails, fall back to listing the project's spec directory
+> and reading titles and `**Goal:**` lines, and write
+> `Spec index unavailable - predecessor check used directory listing.` in your
+> handoff. Either way open at
+> most five candidates whose topic matches this request, and name any whose design
+> this request replaces or amends with the section(s) affected - `Predecessor:
+> <path>, <scope>` - or `Predecessor: none`. Judge by topic; shared file paths never
+> decide. End with an
 > "Open questions that matter for the spec"
 > section. Compact handoff, not a dump.
 

package/skills/brainstorming/reference/superseding.md

@@ -0,0 +1,18 @@
+# Marking superseded specs
+
+When the new spec replaces a prior spec — fully or in part — (from the draft's scout recon or the request), mark the predecessor. No mechanical sweep: grep or path-overlap hits never decide supersession.
+
+- `edit` the predecessor spec (in the project's spec directory, per [Project Routing](../SKILL.md#project-routing)) to insert, after its title line and a blank line, one banner line per successor:
+
+  ```markdown
+  > **Superseded by:** [<repo-relative path to successor>](<href relative to THIS file>) - <scope>
+  ```
+
+- The visible label is the successor's repo-relative path; the href is computed relative to the predecessor's own directory (Markdown resolves links from the containing file). Same directory: `[doc/specs/B.md](./B.md)`.
+- `<scope>` is the value after the ` - ` separator: `fully`, or the named superseded section(s), e.g. `"Settings resolution" section only`. The scope value itself carries no leading dash — the template above already supplies the separator.
+- Banners are **append-only**: add below any existing supersession lines, formatted or free-form prose. One old spec may accumulate banners from multiple successors. No migration, no dedup.
+- **No transitive rewrite**: if A points at B and B is later superseded by C, A keeps pointing at B; the reader hops.
+- **Mark, never delete.** Delete/archive policy is consumer territory via overrides.
+- **Coverage limits**: unmarked does NOT mean current (code drift, abandoned designs, and partial ships produce no successor spec); marked does NOT mean dead (partial supersession leaves live sections).
+- Predecessor in a **different service's spec directory**: out of scope — record it in the new spec's Open Questions instead of editing outside the write grant.
+- **Override contract**: the gauntlet overrides file (see `../SKILL.md#project-overrides`) may replace the banner *syntax*; placement, append-only, no-transitive-rewrite, and mark-never-delete stay fixed. A syntax override entry must itself state the scout-citation guidance for its format (the shipped `gatherer.md` guidance names only the default banner).

package/skills/chase-bug/hotfix.md

@@ -37,6 +37,7 @@ succeeds (it creates both). Every destructive command below is gated on its flag
    DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD) && DEFAULT=${DEFAULT#origin/}
    BASE_SHA=$(git rev-parse "$DEFAULT")
    ORIG_BRANCH=$(git branch --show-current)
+   ORIG_HEAD=$(git rev-parse HEAD)
    git status --porcelain > "$TMPDIR/hotfix-<slug>.baseline"
    ```
 
@@ -49,14 +50,42 @@ succeeds (it creates both). Every destructive command below is gated on its flag
    reuse, never force); `git worktree add` itself failing (creation failure).
 
    ```bash
-   git worktree add ".worktrees/hotfix/<slug>" -b "hotfix/<slug>" "$DEFAULT"
+   git worktree add "$PRIMARY_ROOT/.worktrees/hotfix/<slug>" -b "hotfix/<slug>" "$DEFAULT"
+   WORKTREE=$(git -C "$PRIMARY_ROOT/.worktrees/hotfix/<slug>" rev-parse --show-toplevel)
    ```
 
-   Success sets both flags. Run the project's dependency install inside the
-   worktree. Every dispatch below: `cwd` = the worktree path, the record path in the
-   task text, `output:` (when used) an absolute `$TMPDIR` path.
-4. **Implement.** One `implementer`, fork context:
-
+   Success sets both flags; `WORKTREE` is set only after `git worktree add`
+   succeeds - empty `WORKTREE` -> abort (pre-land, both flags set so cleanup runs)
+   - and is the literal the child is compared against - both sides come from `git
+   rev-parse --show-toplevel`, so a symlinked `.worktrees/` cannot make them
+   disagree. Run the project's dependency install inside the worktree. Every
+   dispatch below: `cwd` = the worktree path, the record path in the task text,
+   `output:` (when used) an absolute `$TMPDIR` path. Every implementer round - step
+   4, the step 5 retry, the step 6 gap fix, the step 7 FIX_FIRST round - is
+   `context: "fresh"` and reuses the full step 4 task text (binding block, record
+   path and inlined evidence pack, `SCOPED_TEST_COMMANDS`, commit-before-reporting,
+   SDD status line) with the round's failing output appended verbatim: the red test
+   output (step 5), the conformance gaps (step 6), the review findings (step 7).
+   Each round is followed by `binding_check` (see Abort, **Binding**) before
+   anything else. Under a fresh context a retry child sees only its task text; a
+   fix child not told to commit leaves its fix where step 7's `<base-sha>..HEAD`
+   review and step 8's `merge --squash` never see it.
+4. **Implement.** One `implementer`, `context: "fresh"` - passed explicitly,
+   because the persona's frontmatter defaults to fork, and a forked parent
+   transcript carries the parent's `cd <primary>` commands and primes the child to
+   leave the worktree; the record path and inlined evidence pack already make the
+   task self-contained. `<WORKTREE>` and `<PRIMARY_ROOT>` below are the literal
+   step 3 values, never a `$VAR` for the child to resolve:
+
+   > Worktree binding: your checkout is <WORKTREE>. Your first command, before any
+   > other, is
+   >   actual=$(git rev-parse --show-toplevel); [ "$actual" = "<WORKTREE>" ] || echo "MISMATCH: $actual != <WORKTREE>"
+   > On MISMATCH run nothing else; your final message opens with the line
+   > `BLOCKED: toplevel <actual> != <WORKTREE>` and ends with `STATUS: BLOCKED`.
+   > Every mutating git command (add, commit, checkout, reset, stash) runs as
+   > `git -C <WORKTREE> ...`. Never `cd` out of <WORKTREE>; never run a command
+   > against <PRIMARY_ROOT>.
+   >
    > Read `$TMPDIR/hotfix-<slug>.md`; the evidence pack is also inlined here:
    > <evidence pack>. The evidence pack replaces plan and spec; do
    > not report BLOCKED for a missing plan. TDD: write the regression test, run it,
@@ -64,6 +93,14 @@ succeeds (it creates both). Every destructive command below is gated on its flag
    > re-run is the regression evidence). SCOPED_TEST_COMMANDS: <commands>. Commit on
    > `hotfix/<slug>` before reporting. End with the SDD status line verbatim.
 
+   The `BLOCKED:` opening line is load-bearing: pi-cohort turns a final message
+   whose first non-empty line starts with `BLOCKED:` into a dispatch error that
+   carries the full output, ahead of the implementer's completion guard that would
+   otherwise replace an edit-free report with a generic no-edits error.
+
+   On return, `binding_check` runs before anything else - before the status line
+   is read and before a dispatch error is handled; a failed check -> `binding_abort`,
+   the status branch is skipped. A dispatch error is routed as `BLOCKED`. Then:
    `DONE` -> step 5. `DONE_WITH_CONCERNS` -> step 5 unless a concern names a safety
    invariant -> abort. `NEEDS_CONTEXT` or `BLOCKED` -> abort. A regression command
    named in the report joins `SCOPED_TEST_COMMANDS` only if it uses the resolved
@@ -126,6 +163,8 @@ succeeds (it creates both). Every destructive command below is gated on its flag
    without the hotfix entry; `git branch --list hotfix/<slug>` empty; porcelain
    delta vs baseline none. PR exit and land-stage aborts: both present, plus
    `git worktree remove --force .worktrees/hotfix/<slug> && git branch -D hotfix/<slug>`.
+   Binding aborts: worktree and `hotfix/<slug>` both present; no removal command
+   is run.
 10. **Response.** chase-bug step 5 rules apply unchanged: addressable -> draft
     citing `fixed in <SHA>` or the PR link -> `send it`; unaddressable -> summary.
     Abort never reaches this step - it returns to the menu.
@@ -151,7 +190,7 @@ Judgment predicates (`[recommended]` only; Moderate review items):
 
 ## Abort
 
-Both classes end with the baseline re-check, then chase-bug step 4 re-renders.
+All three classes end with the baseline re-check, then chase-bug step 4 re-renders.
 
 **Pre-land** (steps 2-7): unresolvable commands or task text; setup precondition
 unmet; `NEEDS_CONTEXT`/`BLOCKED` or a concern naming an invariant; red after retry;
@@ -175,21 +214,73 @@ exactly that); on base moved `<default>` is never touched and both SHAs are
 reported. Restore `<orig-branch>`. Preserve worktree and branch (reviewed work).
 Report path, tip SHA, closing line. The menu re-renders without the hotfix row.
 
-**Baseline re-check**: `git status --porcelain --untracked-files=no` matches the
-triage baseline; full porcelain delta reported; `<default>` == `<base-sha>` asserted
-only when this run touched `<default>`. Pre-existing dirt is never touched.
+**Binding** (after any implementer return, steps 4-7): the parent runs
+`binding_check` from `PRIMARY_ROOT` before reading the child's status line or
+handling a dispatch error - a `BLOCKED` or errored child may have mutated the
+primary before stopping, and the pre-land cleanup would delete the evidence.
+
+```bash
+binding_check() {
+  local head branch dirt default
+  default=$(git -C "$PRIMARY_ROOT" rev-parse "$DEFAULT")    || binding_abort read "rev-parse $DEFAULT failed"
+  head=$(git -C "$PRIMARY_ROOT" rev-parse HEAD)              || binding_abort read "rev-parse HEAD failed"
+  branch=$(git -C "$PRIMARY_ROOT" branch --show-current)     || binding_abort read "branch --show-current failed"
+  dirt=$(git -C "$PRIMARY_ROOT" status --porcelain --untracked-files=no) || binding_abort read "status failed"
+  local moved=""
+  [ "$default" = "$BASE_SHA" ] || moved="$moved <default>:$BASE_SHA..$default"
+  [ "$head" = "$ORIG_HEAD" ]   || moved="$moved HEAD:$ORIG_HEAD..$head"
+  [ "$branch" = "$ORIG_BRANCH" ] || moved="$moved branch:$ORIG_BRANCH->$branch"
+  [ -z "$moved" ] && [ -z "$dirt" ] && return 0
+  binding_abort drift "$moved" "$dirt"
+}
+```
+
+Every read must succeed before any comparison: a failed read with empty stdout
+would otherwise pass `-z "$dirt"` or be misread as HEAD drift. All observations
+are collected first, so a stray commit plus tracked dirt is one abort. Three refs,
+not one: a drifted child commits on whatever the primary has checked out, which is
+`<orig-branch>`, and `<orig-branch>` may differ from `<default>`. The tracked-only
+target is the empty string - the step 3 precondition already guarantees it.
+
+`binding_abort` never touches the primary checkout: no `git reset`, no
+`git checkout`, no stash - this run moved nothing, so the land-stage reset rule
+already forbids it. The worktree and `hotfix/<slug>` are **preserved** as
+evidence of what the child did where (a deliberate exception to pre-land
+cleanup). Report, by kind: `read` - the failing command and its stderr, the
+worktree path and `hotfix/<slug>` tip SHA, no drift claim; `drift` - for each
+moved ref `<ref> moved from <old> to <new>` plus
+`git --no-pager log --oneline <old>..<new>`
+(branch switch: `checked-out branch changed from <orig-branch> to <branch>`),
+for tracked dirt the path fields only (no `XY` codes), the full
+`git status --porcelain` delta against the step 3 baseline file
+(`$TMPDIR/hotfix-<slug>.baseline`, report-only as today), the worktree path and
+`hotfix/<slug>` tip SHA. The non-executed repair line
+`git checkout <ref> && git reset --hard <old-sha>` is printed only when tracked
+dirt is empty -
+with dirt present the parent cannot tell whose edits a reset would destroy. The
+menu re-renders without the hotfix row.
+
+**Baseline re-check**: `git status --porcelain --untracked-files=no` is empty (the
+step 3 precondition; the tracked-only baseline is empty by construction); full
+porcelain delta reported; `<default>` == `<base-sha>` asserted only when this run
+touched `<default>`. Pre-existing dirt is never touched.
 
 ## Harness fallback
 
 No `subagent` tool and no personas (the Claude Code marketplace ships `agents: []`):
 run the duties inline, same order. Write the failing regression test, confirm red,
-minimal fix, confirm green, commit on `hotfix/<slug>`. Self-review the diff against
-the record, invariants 1-3, predicates 4-6. Run `SCOPED_TEST_COMMANDS`. Apply the
-abort classes as written. Finish and report per steps 8-9.
+minimal fix, confirm green, commit on `hotfix/<slug>`. With no child the binding
+block is moot, but `binding_check` still runs after the initial inline commit and
+after each inline retry, conformance fix, or review fix, before tests continue.
+Self-review the diff against the record, invariants 1-3, predicates 4-6. Run
+`SCOPED_TEST_COMMANDS`. Apply the abort classes as written. Finish and report per
+steps 8-9.
 
 ## Red Flags - STOP
 
 - Any mutation before every step 3 precondition passes
+- Reading an implementer's status line before `binding_check`
+- Resetting or checking out any primary ref from `binding_abort`
 - Reusing or force-replacing an existing `hotfix/<slug>` branch or path
 - `git reset --hard` after *proven*, on `<orig-branch>`, or inside the worktree
 - Re-running tests in the primary checkout

package/skills/gauntlet-resume/SKILL.md

@@ -59,14 +59,18 @@ In order. All before any tracker mutation; entry check 1 is read-only.
    `not a git repo` and no override was given - except a `worktree: no` brief **without**
    process state, which is the brainstorming route in Dispatch, not a stop. Other
    `unavailable` fields inside `## Repo state` are legal.
-3. **Session cwd binding.** `phase_tracker`, `plan_check`, and the flow guards resolve
-   every path against the extension's session cwd; a child-shell `cd` cannot relocate it.
-   If `realpath $(git rev-parse --show-toplevel)` in the session cwd differs from the
-   resolved worktree, stop: "restart pi in <worktree> and re-run". Every restoration
-   therefore runs with the session rooted in the resolved worktree.
+3. **Same-repository binding.** Settings and flow guards come from the repository in
+   the extension's session cwd. Compare
+   `realpath "$(git rev-parse --path-format=absolute --git-common-dir)"` in the session
+   cwd with
+   `realpath "$(git -C <worktree> rev-parse --path-format=absolute --git-common-dir)"`.
+   If they differ, stop, name both paths, and say the resolved worktree belongs to a
+   different repository; restart pi in that repository's primary checkout and re-run.
+   Same-repository worktrees proceed by path: use `git -C <worktree>` for
+   worktree Git commands and absolute artifact paths for `Read` and `plan_check`.
 4. **Drift notice.** Compare the brief's `HEAD` and `dirty` fields in `## Repo state`
-   with the live worktree (`git rev-parse HEAD`, `git status --porcelain`). Announce
-   differences. Informational, never a stop.
+   with the live worktree (`git -C <worktree> rev-parse HEAD`, `git -C <worktree>
+   status --porcelain`). Announce differences. Informational, never a stop.
 5. **Skills loaded.** For each name in `## Skills loaded` (none for
    `## Skills loaded: none`): match against the frontmatter `name` of every
    `skills/*/SKILL.md` in this package; `Read` each match's complete file into the

package/skills/gauntlet-resume/reference/brief-contract.md

@@ -97,7 +97,8 @@ Per-stage call table, keyed by the brief's active phase (`→`). `R` is the reas
 (`reconstruction.md`, "Candidates", including its `flowGuards.specDirs` resolution): the
 single spec/plan pair added after base in the worktree, paired by identical basename
 (`<specDir>/<name>.md` <-> `<sibling plans dir>/<name>.md`, the writing-plans contract);
-zero pairs -> stop; more than one -> human picks.
+resolve the selected plan to an absolute path under the worktree before `plan_check`.
+Zero pairs -> stop; more than one -> human picks.
 
 "Exact" restoration binds: the active phase identity and substep, and the plan task list
 (names, order, statuses) verbatim. Prior phases show `⊘ (resume: ...)` regardless of the

package/skills/gauntlet-resume/reference/reconstruction.md

@@ -13,12 +13,12 @@ available" - and never invent Intent or Decisions.
 ## Base
 
 ```bash
-git merge-base HEAD origin/HEAD 2>/dev/null \
-  || git merge-base HEAD main 2>/dev/null \
-  || git merge-base HEAD master 2>/dev/null
+git -C <worktree> merge-base HEAD origin/HEAD 2>/dev/null \
+  || git -C <worktree> merge-base HEAD main 2>/dev/null \
+  || git -C <worktree> merge-base HEAD master 2>/dev/null
 ```
 
-Base = `git merge-base HEAD origin/HEAD`, else `main`/`master`. Empty -> ask the human
+Base = `git -C <worktree> merge-base HEAD origin/HEAD`, else `main`/`master`. Empty -> ask the human
 for a base ref before reading any artifact.
 
 ## Candidates
@@ -29,15 +29,18 @@ else the active pi profile's `settings.json`, else the default `["doc/specs"]` (
 space-separated - never the literal defaults when a setting is present.
 
 ```bash
-git diff --diff-filter=A --name-only <base>..HEAD -- <dirs>
-git ls-files --others --exclude-standard -- <dirs>
+git -C <worktree> diff --diff-filter=A --name-only <base>..HEAD -- <dirs>
+git -C <worktree> ls-files --others --exclude-standard -- <dirs>
 ```
 
 Candidates are files under those directories added after base, plus untracked files
-there. A spec and a plan pair by identical basename (`<specDir>/<name>.md` <->
-`<sibling plans dir>/<name>.md`). The plan commit is the first post-base commit that added the
-plan file: `git log --diff-filter=A --format=%H --reverse <base>..HEAD -- <plan>`, first
-line. An uncommitted plan has no plan commit; treat every task as `pending`.
+there. Paths returned by these commands are relative to `<worktree>`; resolve them to
+absolute paths under `<worktree>` before reading artifacts, showing paths in prompts,
+or calling `plan_check`. A spec and a plan pair by identical basename
+(`<specDir>/<name>.md` <-> `<sibling plans dir>/<name>.md`). The plan commit is the first
+post-base commit that added the plan file: `git -C <worktree> log --diff-filter=A
+--format=%H --reverse <base>..HEAD -- <plan>`, first line. An uncommitted plan has no
+plan commit; treat every task as `pending`.
 
 | Candidates | Route |
 |---|---|
@@ -63,11 +66,12 @@ Show, and ask the human to confirm or edit both in one reply:
 
 1. Per task, in plan order: the commits after the plan commit that touch any path in
    the task's declared `Files:` block. Strip a trailing `:digits[-digits]` range from
-   each `Modify:` path before matching `git log -- <path>`:
-   `git log --format=%h --oneline <plan-commit>..HEAD -- <path>`. Uncommitted plan (no
+   each `Modify:` path before matching `git -C <worktree> log -- <path>`:
+   `git -C <worktree> log --format=%h --oneline <plan-commit>..HEAD -- <path>`.
+   Uncommitted plan (no
    plan commit): skip this query entirely - there is no range to search - and show
    "plan uncommitted; no task evidence" in its place; every task is proposed `pending`.
-2. Uncommitted files: `git status --porcelain`.
+2. Uncommitted files: `git -C <worktree> status --porcelain`.
 3. Proposed task statuses: `complete` iff at least one matching commit, else `pending`.
 4. Proposed stage: `implement` if any task is `pending`, else `verify`.
 
@@ -83,7 +87,7 @@ edits override proposals; never rewrite confirmed state silently.
 After confirmation:
 
 1. `start brainstorm`; `skip brainstorm resume: <spec path>`; `start plan`.
-2. `plan_check` with `planPath` = the plan. FAIL -> print the findings, stop with plan
+2. `plan_check` with `planPath` = the plan's absolute path. FAIL -> print the findings, stop with plan
    in_progress, no `init`.
 3. PASS -> `skip plan` with the same `resume:` reason; for stage verify also
    `skip implement`; `start <stage>`.