pi-gauntlet 7.0.1 → 7.0.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v7.0.3 - 2026-10-02
+
+### Fixed
+
+- **Amendment aftermath keeps the phase; reopened tasks close in place.** A spec amendment approved during `verify` or `ship` reopens its plan tasks inside that phase; `amendment-surface.md` no longer prescribes `skip <phase>` + `start implement force: true`, and the batch card's phase slot is the constant `no phase change`. Each reopened task is repaired through the current phase's fix loop and closed with `plan_tracker update ... complete` once its re-review or re-audit accepts. Supersedes the phase-restart clauses of the 2026-09-10 gh-27 spec and the 2026-09-22 batch-card spec.
+- **Skill resources load with `read`, never a shell command.** Brainstorming's amend section states the rule (pi-condense's `**/skills/**/*.md` protection keys on `read`'s `path`, so a `bash sed` load was pruned mid-flow); `amendment-surface.md`, SDD, and finishing name `read` at their amendment entry points, and section 5 re-reads itself before the aftermath.
+- **phase-tracker: open-task nudge after a verify-phase repair wave.** Under `flowGuards.enforce`, every non-error implementer-wave result while `verify` is in progress is prefixed with the latest `plan_tracker` snapshot's `pending`/`in_progress` rows and the `update ... complete` call that closes them. Advisory only - no block, no fix-round or phase change - and it reads session entries, so context pruning cannot hide it. The completion backstop's branch scan is shared with it (`latestPlanSnapshot`/`unfinishedTaskLines`). Documented in `doc/configuration.md`.
+
+## v7.0.2 - 2026-10-02
+
+### Added
+
+- `gauntlet-telemetry-seal` seals records in a plain jj workspace (no `.git`): all git/jj dispatch centralizes in a new `extensions/lib/vcs.ts` (`vcsFor` over the shared `checkoutOfSync`), the ship diff comes from `computeJjDiff` (fork-point base against `trunk()`/`main`/`master`, `--to @`), `--base` is validated as a jj revset, and the record is tracked with `jj file track --include-ignored` instead of a `telemetry:` commit, so a gitignored telemetry dir is snapshotted like `git add -f` stages it. The jj runner reads up to 64 MiB of patch output. `/skill:finishing-a-development-branch` Step 5 strips the plan with `jj restore --from <base-branch> -- root:"<plan>"` there (anchored at the workspace root, since jj resolves bare paths against cwd), and a checkout with neither git nor jj now errors `not a git or jj checkout`.
+
 ## v7.0.1 - 2026-10-02
 
 ### Fixed

package/README.md

@@ -71,7 +71,7 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
 - **20 skills** - the workflow logic. Twelve activate automatically when pi sees the matching kind of task, and the workflow skills chain through their gates: `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `forge-skill`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Eight more require explicit entry (`disable-model-invocation: true`): `brainstorming` starts the gated workflow on explicit consent - use `/skill:brainstorming` for reliable discovery, or opt in through reachable explicit prose or a human-selected handoff; after spec approval, downstream planning and implementation still chain automatically. `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue's acceptance criteria - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, a compact bottom-up report (what the PR delivers, ticket changes, PR comments, nits, blockers, then a `mergeable` / `fixable` verdict) and a verb menu that always offers `fix` whoever authored the PR; nothing mutates (fixes, pushes, reviews, merges, tracker comments) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, a council assessment when available, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
-- **4 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. `telemetry` records one YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - it is written only inside a brainstorming-entered flow, kept untracked and git-excluded until `finishing-a-development-branch` seals and commits it once with `gauntlet-telemetry-seal` - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
+- **4 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. `telemetry` records one YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - it is written only inside a brainstorming-entered flow, kept out of history until `finishing-a-development-branch` seals it once with `gauntlet-telemetry-seal` (a `telemetry:` commit under git; the working-copy snapshot in a plain jj workspace) - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
 pi-gauntlet is **opinionated**: it recommends this pipeline for non-trivial changes, but starts `brainstorming` only after explicit user consent. 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.
 

package/bin/gauntlet-telemetry-seal.mjs

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
 
 // src/bins/gauntlet-telemetry-seal.mjs
-import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync as existsSync2, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { isAbsolute as isAbsolute2, join, relative as relative2 } from "node:path";
-import { spawnSync } from "node:child_process";
-import process from "node:process";
+import { isAbsolute as isAbsolute2, join as join2, relative as relative2 } from "node:path";
+import process2 from "node:process";
 
 // extensions/lib/gauntlet-settings.ts
 import path from "node:path";
@@ -87,6 +86,105 @@ function numstatPath(raw) {
   const arrow = braced.indexOf(" => ");
   return arrow >= 0 ? braced.slice(arrow + 4) : braced;
 }
+function patchBlockPath(headers) {
+  const plus = headers.find((l) => l.startsWith("+++ b/"));
+  if (plus) return plus.slice(6);
+  const renameTo = headers.find((l) => l.startsWith("rename to "));
+  if (renameTo) return renameTo.slice(10);
+  const minus = headers.find((l) => l.startsWith("--- a/"));
+  if (minus && headers.includes("+++ /dev/null")) return minus.slice(6);
+  if (!headers[0].startsWith("diff --git a/")) return void 0;
+  const rest = headers[0].slice("diff --git a/".length);
+  const mid = (rest.length - 3) / 2;
+  if (Number.isInteger(mid) && mid > 0 && rest.slice(mid, mid + 3) === " b/" && rest.slice(0, mid) === rest.slice(mid + 3)) return rest.slice(0, mid);
+  return void 0;
+}
+function parsePatchBlock(block) {
+  const hunk = block.findIndex((l) => l.startsWith("@@"));
+  const headers = hunk < 0 ? block : block.slice(0, hunk);
+  const path2 = patchBlockPath(headers);
+  if (path2 === void 0) return void 0;
+  let added = 0;
+  let removed = 0;
+  for (const line of hunk < 0 ? [] : block.slice(hunk)) {
+    if (line.startsWith("+")) added++;
+    else if (line.startsWith("-")) removed++;
+  }
+  return { added, removed, path: path2 };
+}
+function parsePatchNumstat(patch) {
+  if (!patch.trim()) return [];
+  const lines = patch.split("\n");
+  if (!lines.find((l) => l.trim()).startsWith("diff --git ")) return null;
+  const blocks = [];
+  for (const line of lines) {
+    if (line.startsWith("diff --git ")) blocks.push([line]);
+    else if (blocks.length) blocks[blocks.length - 1].push(line);
+  }
+  const rows = [];
+  for (const block of blocks) {
+    const row = parsePatchBlock(block);
+    if (!row) return null;
+    rows.push(row);
+  }
+  return rows;
+}
+
+// extensions/lib/vcs.ts
+import { spawnSync } from "node:child_process";
+
+// extensions/lib/checkout.ts
+import { execFileSync } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+var CHECKOUT_ARGS = ["rev-parse", "--path-format=absolute", "--show-toplevel", "--git-dir", "--git-common-dir"];
+function parseCheckout(r) {
+  if (r.code !== 0) return void 0;
+  const lines = r.stdout.trim().split("\n").map((l) => l.trim());
+  if (lines.length < 3 || !lines[0]) return void 0;
+  return { toplevel: lines[0], isPrimary: lines[1] === lines[2] };
+}
+var isDir = (p) => {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+function nearestExistingDir(absPath) {
+  let p = absPath;
+  while (!(existsSync(p) && isDir(p))) {
+    const parent = dirname(p);
+    if (parent === p) return p;
+    p = parent;
+  }
+  return p;
+}
+var JJ_ROOT_ARGS = ["root"];
+function parseJjRoot(r) {
+  if (r.code !== 0) return void 0;
+  const toplevel = r.stdout.trim();
+  if (!toplevel) return void 0;
+  return { toplevel, isPrimary: isDir(join(toplevel, ".jj", "repo")) };
+}
+function checkoutOfSync(absPath, git = gitSync, jj = jjSync) {
+  const cwd = nearestExistingDir(absPath);
+  const g = parseCheckout(git(CHECKOUT_ARGS, cwd));
+  if (g) return { ...g, via: "git" };
+  const j = parseJjRoot(jj(JJ_ROOT_ARGS, cwd));
+  return j ? { ...j, via: "jj" } : void 0;
+}
+var commandSync = (bin) => (args, cwd) => {
+  try {
+    const stdout = execFileSync(bin, args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5e3 });
+    return { code: 0, stdout };
+  } catch (e) {
+    const status = e.status;
+    return { code: typeof status === "number" ? status : 1, stdout: "" };
+  }
+};
+var gitSync = commandSync("git");
+var jjSync = commandSync("jj");
 
 // extensions/lib/telemetry-ship.ts
 function modifiedFilesFrom(nameOnly, spec, dir, planDirs) {
@@ -111,7 +209,28 @@ function aggregateNumstat(numstat, files, buckets) {
   }
   return out;
 }
+var JJ_MAINLINE = "coalesce(trunk() ~ root(), present(main), present(master))";
+var JJ_FORK_POINT = `fork_point(${JJ_MAINLINE} | @) ~ root() & ::${JJ_MAINLINE}`;
 var firstLine = (s) => s.trim().split("\n")[0];
+async function computeJjDiff(o) {
+  const failed = (sub, r) => ({ warning: `diff omitted: jj ${sub} failed: ${firstLine(r.stderr) || "unknown error"}` });
+  const baseR = await o.jj(["--color=never", "log", "-r", JJ_FORK_POINT, "--no-graph", "-T", 'commit_id ++ "\\n"'], o.cwd);
+  if (baseR.code !== 0) return failed("log", baseR);
+  const base = firstLine(baseR.stdout).trim();
+  if (!base) return { warning: "diff omitted: jj mainline unresolved (trunk() is root(); no main/master bookmark)" };
+  const patch = await o.jj(["--color=never", "--config", "diff.git.show-path-prefix=true", "diff", "--from", base, "--to", "@", "--git"], o.cwd);
+  if (patch.code !== 0) return failed("diff", patch);
+  const rows = parsePatchNumstat(patch.stdout);
+  if (!rows) return { warning: "diff omitted: jj diff unparseable" };
+  const dir = o.dir.replace(/\/+$/, "");
+  const count = await o.jj(["--color=never", "log", "-r", `(${base}::@ ~ ${base}) & files(~glob:"${dir}/**")`, "--count"], o.cwd);
+  if (count.code !== 0) return failed("log", count);
+  const n = count.stdout.trim();
+  if (!/^\d+$/.test(n)) return { warning: `diff omitted: jj log --count unparseable: ${n}` };
+  const files = modifiedFilesFrom(rows.map((r) => r.path).join("\n"), o.spec, o.dir, o.planDirs);
+  const numstat = rows.map((r) => `${r.added}	${r.removed}	${r.path}`).join("\n");
+  return { modified_files: files, diff: { base, commits: Number(n), buckets: aggregateNumstat(numstat, new Set(files), o.buckets) } };
+}
 async function computeGitDiff(o) {
   const mb = await o.git(["merge-base", "HEAD", o.base], o.cwd);
   if (mb.code !== 0 || !mb.stdout.trim()) return { warning: `diff omitted: merge-base failed: ${firstLine(mb.stderr)}` };
@@ -123,6 +242,46 @@ async function computeGitDiff(o) {
   return { modified_files: files, diff: { base, commits: Number(count.stdout.trim()) || 0, buckets: aggregateNumstat(numstat.stdout, new Set(files), o.buckets) } };
 }
 
+// extensions/lib/vcs.ts
+var NO_PROMPT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_EDITOR: "true" };
+var runBinary = (bin) => (args, cwd, timeoutMs = 1e4) => {
+  const r = spawnSync(bin, args, { cwd, encoding: "utf8", env: NO_PROMPT_ENV, timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 });
+  const err = r.error;
+  const timedOut = err?.code === "ETIMEDOUT";
+  const stderr = timedOut ? "timed out" : (r.stderr ?? "").trim().split("\n")[0] || err?.message || `${bin} exited ${r.status}`;
+  return { ok: !timedOut && r.status === 0, code: timedOut ? 1 : r.status ?? 1, stdout: (r.stdout ?? "").trim(), stderr };
+};
+function vcsFor(absPath) {
+  const co = checkoutOfSync(absPath);
+  return co && { kind: co.via, root: co.toplevel, run: runBinary(co.via) };
+}
+async function computeShipDiff(vcs, o) {
+  return vcs.kind === "jj" ? computeJjDiff({ jj: vcs.run, cwd: vcs.root, spec: o.spec, dir: o.dir, planDirs: o.planDirs, buckets: o.buckets }) : computeGitDiff({ git: vcs.run, cwd: vcs.root, spec: o.spec, dir: o.dir, planDirs: o.planDirs, buckets: o.buckets, base: o.base });
+}
+function validateBase(vcs, base) {
+  const r = vcs.kind === "jj" ? vcs.run(["--color=never", "log", "-r", base, "--limit", "1", "--no-graph", "-T", 'commit_id ++ "\\n"'], vcs.root) : vcs.run(["rev-parse", "--verify", "-q", `${base}^{commit}`], vcs.root);
+  return r.ok && r.stdout !== "";
+}
+function changedNames(vcs, base) {
+  if (vcs.kind === "git") return vcs.run(["diff", "--no-renames", "--name-only", `${base}...HEAD`], vcs.root);
+  const forkR = vcs.run(["--color=never", "log", "-r", JJ_FORK_POINT, "--no-graph", "-T", 'commit_id ++ "\\n"'], vcs.root);
+  if (!forkR.ok) return forkR;
+  const fork = forkR.stdout.split("\n")[0];
+  if (!fork) return { ok: false, code: 1, stdout: "", stderr: "jj mainline unresolved (trunk() is root(); no main/master bookmark)" };
+  return vcs.run(["--color=never", "diff", "--name-only", "--from", fork, "--to", "@"], vcs.root);
+}
+function recordSealed(vcs, rel) {
+  if (vcs.kind === "jj") return true;
+  return vcs.run(["ls-files", "--error-unmatch", "--", rel], vcs.root).ok && vcs.run(["diff", "--quiet", "HEAD", "--", rel], vcs.root).ok;
+}
+function commitRecordFile(vcs, rel, message) {
+  if (vcs.kind === "jj") return vcs.run(["file", "track", "--include-ignored", "--", rel], vcs.root);
+  const add = vcs.run(["add", "-f", "--", rel], vcs.root);
+  const commit = add.ok ? vcs.run(["commit", "-q", "-m", message, "--", rel], vcs.root, 3e4) : add;
+  if (!commit.ok) vcs.run(["reset", "-q", "--", rel], vcs.root);
+  return commit;
+}
+
 // extensions/lib/telemetry-record.ts
 import { Document, isCollection, isMap, isSeq, parse as parseYaml, stringify as stringifyYaml } from "yaml";
 var PHASES = ["brainstorm", "plan", "implement", "verify", "ship"];
@@ -251,13 +410,10 @@ function parseRecord(text) {
 }
 
 // src/bins/gauntlet-telemetry-seal.mjs
-var GIT_TIMEOUT_MS = 1e4;
-var COMMIT_TIMEOUT_MS = 3e4;
-var GIT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_EDITOR: "true" };
 var OPTIONS = /* @__PURE__ */ new Set(["pr", "squash"]);
 var fail = (code, message) => {
-  process.stderr.write(message + "\n");
-  process.exit(code);
+  process2.stderr.write(message + "\n");
+  process2.exit(code);
 };
 var usage = () => fail(1, "usage: gauntlet-telemetry-seal --worktree <abs path> --option <pr|squash> --base <ref> [--spec <spec path inside the checkout>] [--dir <telemetry dir>]");
 function parseArgs(argv) {
@@ -279,107 +435,92 @@ function parseArgs(argv) {
   if (!opts.worktree || !isAbsolute2(opts.worktree) || !opts.base || !OPTIONS.has(opts.option)) usage();
   return opts;
 }
-function git(cwd, args, timeout = GIT_TIMEOUT_MS) {
-  const r = spawnSync("git", args, { cwd, encoding: "utf8", env: GIT_ENV, timeout });
-  const timedOut = r.error?.code === "ETIMEDOUT";
-  const stderr = timedOut ? "timed out" : (r.stderr ?? "").trim().split("\n")[0] || r.error?.message || `git exited ${r.status}`;
-  return { ok: !timedOut && r.status === 0, code: timedOut ? 1 : r.status ?? 1, stdout: (r.stdout ?? "").trim(), stderr };
-}
-var gitRunner = (args, cwd) => {
-  const r = git(cwd, args);
-  return { code: r.code, stdout: r.stdout, stderr: r.stderr };
-};
 function readLayer(file) {
-  if (!existsSync(file)) return {};
+  if (!existsSync2(file)) return {};
   try {
     return JSON.parse(readFileSync(file, "utf8"));
   } catch (e) {
-    process.stderr.write(`warning: ${file}: ${e.message}; using {} for this layer
+    process2.stderr.write(`warning: ${file}: ${e.message}; using {} for this layer
 `);
     return {};
   }
 }
 function settings(root) {
-  const agentDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
-  const preset = readLayer(join(agentDir, "settings.json"));
-  const repo = readLayer(join(root, ".pi", "settings.json"));
+  const agentDir = process2.env.PI_CODING_AGENT_DIR || join2(homedir(), ".pi", "agent");
+  const preset = readLayer(join2(agentDir, "settings.json"));
+  const repo = readLayer(join2(root, ".pi", "settings.json"));
   const merged = mergeGauntlet(preset?.piGauntlet, repo?.piGauntlet);
   return { telemetry: resolveTelemetry(merged), planDirs: planDirsFor(resolveFlowGuards(merged).specDirs) };
 }
 function walkRecords(absDir) {
-  if (!existsSync(absDir)) return [];
+  if (!existsSync2(absDir)) return [];
   const out = [];
   for (const e of readdirSync(absDir, { withFileTypes: true })) {
-    const p = join(absDir, e.name);
+    const p = join2(absDir, e.name);
     if (e.isDirectory()) out.push(...walkRecords(p));
     else if (e.isFile() && e.name.endsWith(".yaml")) out.push(p);
   }
   return out;
 }
 var isoNow = () => (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
-var trackedAndClean = (root, rec) => git(root, ["ls-files", "--error-unmatch", "--", rec]).ok && git(root, ["diff", "--quiet", "HEAD", "--", rec]).ok;
-async function seal(root, rec, o) {
-  const abs = join(root, rec);
-  if (!existsSync(abs)) fail(2, `no record at ${rec}`);
+async function seal(vcs, rec, o) {
+  const abs = join2(vcs.root, rec);
+  if (!existsSync2(abs)) fail(2, `no record at ${rec}`);
   const prior = readFileSync(abs);
   const parsed = parseRecord(prior.toString("utf8"));
   if (!parsed) fail(2, `unparseable record ${rec}: schema 1 with spec and run_id required`);
   if (parsed.status !== "in_progress") {
-    if (parsed.status !== "shipped" || trackedAndClean(root, rec)) return console.log(`already sealed ${rec}`);
+    if (parsed.status !== "shipped" || recordSealed(vcs, rec)) return console.log(`already sealed ${rec}`);
   } else {
     const now = isoNow();
     parsed.status = "shipped";
     parsed.shipped_at = now;
     parsed.events.push({ ts: now, session: parsed.sessions.at(-1) ?? "seal", phase: "ship", kind: "ship", option: o.option });
-    const out = await computeGitDiff({ git: gitRunner, cwd: root, spec: parsed.spec, dir: o.dir, buckets: o.buckets, base: o.base, planDirs: o.planDirs });
+    const out = await computeShipDiff(vcs, { spec: parsed.spec, dir: o.dir, buckets: o.buckets, base: o.base, planDirs: o.planDirs });
     if (out.warning) parsed.events.push({ ts: now, session: parsed.sessions.at(-1) ?? "seal", phase: "ship", kind: "warning", message: out.warning });
     parsed.derived.diff = out.diff;
     parsed.derived.modified_files = out.modified_files;
     parsed.derived = derive(parsed, now);
     writeFileSync(abs, serializeRecord(parsed));
   }
-  const rollback = (reason) => {
+  const commit = commitRecordFile(vcs, rec, `telemetry: ${parsed.spec}`);
+  if (!commit.ok) {
     writeFileSync(abs, prior);
-    git(root, ["reset", "-q", "--", rec]);
-    fail(1, `seal failed ${rec}: ${reason}`);
-  };
-  const add = git(root, ["add", "-f", "--", rec]);
-  if (!add.ok) rollback(add.stderr);
-  const commit = git(root, ["commit", "-q", "-m", `telemetry: ${parsed.spec}`, "--", rec], COMMIT_TIMEOUT_MS);
-  if (!commit.ok) rollback(commit.stderr);
+    fail(1, `seal failed ${rec}: ${commit.stderr}`);
+  }
   console.log(`sealed ${rec}`);
 }
 async function main() {
-  const opts = parseArgs(process.argv.slice(2));
+  const opts = parseArgs(process2.argv.slice(2));
   const override = opts.dir === void 0 ? void 0 : resolveTelemetry({ telemetry: { enabled: true, dir: opts.dir } });
   if (override?.warning) usage();
-  const top = existsSync(opts.worktree) ? git(opts.worktree, ["rev-parse", "--show-toplevel"]) : { ok: false };
-  if (!top.ok) fail(1, "not a git checkout");
-  const root = top.stdout;
+  const vcs = existsSync2(opts.worktree) ? vcsFor(opts.worktree) : void 0;
+  if (!vcs) fail(1, "not a git or jj checkout");
+  const root = vcs.root;
   let rel;
   if (opts.spec) {
-    const specAbs = isAbsolute2(opts.spec) && existsSync(opts.spec) ? realpathSync(opts.spec) : opts.spec;
+    const specAbs = isAbsolute2(opts.spec) && existsSync2(opts.spec) ? realpathSync(opts.spec) : opts.spec;
     rel = repoRelativeToolPath(root, root, specAbs);
     if (!rel) usage();
   }
   const { telemetry, planDirs } = settings(root);
-  if (telemetry.warning) process.stderr.write(`warning: ${telemetry.warning}
+  if (telemetry.warning) process2.stderr.write(`warning: ${telemetry.warning}
 `);
   if (!telemetry.enabled) return console.log("telemetry disabled");
   const dir = override?.dir ?? telemetry.dir;
-  if (!git(root, ["rev-parse", "--verify", "-q", `${opts.base}^{commit}`]).ok) fail(1, `no base ref ${opts.base}`);
+  if (!validateBase(vcs, opts.base)) fail(1, `no base ref ${opts.base}`);
   const o = { option: opts.option, base: opts.base, dir, buckets: telemetry.buckets, planDirs };
-  if (opts.spec) return seal(root, recordPathFor(dir, rel), o);
-  const diff = git(root, ["diff", "--no-renames", "--name-only", `${opts.base}...HEAD`]);
-  if (!diff.ok) fail(1, `git diff failed: ${diff.stderr}`);
+  if (opts.spec) return seal(vcs, recordPathFor(dir, rel), o);
+  const diff = changedNames(vcs, opts.base);
+  if (!diff.ok) fail(1, `${vcs.kind} diff failed: ${diff.stderr}`);
   const changed = new Set(diff.stdout.split("\n").filter(Boolean));
-  const records = walkRecords(join(root, dir)).filter((abs) => {
+  const records = walkRecords(join2(root, dir)).filter((abs) => {
     const parsed = parseRecord(readFileSync(abs, "utf8"));
-    if (!parsed) process.stderr.write(`warning: unparseable record ${toPosix(relative2(root, abs))}
+    if (!parsed) process2.stderr.write(`warning: unparseable record ${toPosix(relative2(root, abs))}
 `);
     return parsed && changed.has(parsed.spec);
   }).map((abs) => toPosix(relative2(root, abs))).sort();
   if (records.length === 0) return console.log("no telemetry run");
-  for (const rec of records) await seal(root, rec, o);
+  for (const rec of records) await seal(vcs, rec, o);
 }
 await main();

package/bin/gauntlet-telemetry-seal.test.mjs

@@ -339,7 +339,7 @@ test("usage and environment errors exit 1", (t) => {
   const notGit = mkdtempSync(join(tmpdir(), "gts-nogit-")); cleanup(t, notGit);
   const ng = invoke(["--worktree", notGit, "--option", "squash", "--base", "main"]);
   assert.equal(ng.status, 1);
-  assert.equal(ng.stderr, "not a git checkout");
+  assert.equal(ng.stderr, "not a git or jj checkout");
 });
 
 test("--dir overrides the telemetry dir", (t) => {
@@ -350,3 +350,167 @@ test("--dir overrides the telemetry dir", (t) => {
   assert.deepEqual(r.lines, ["sealed tele/doc/specs/x.yaml"]);
   assert.deepEqual(headFiles(root), ["tele/doc/specs/x.yaml"]);
 });
+
+// --- Plain jj workspace (no .git). git and jj are PATH shims: git always fails
+// rev-parse and only logs; jj answers from a per-test JSON script. CI has no jj.
+const JJ_FORK = "f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9";
+// src/a.ts: +10 -2; the spec and the record ride along to prove modified_files filters them out.
+const JJ_PATCH = [
+  "diff --git a/src/a.ts b/src/a.ts",
+  "index 1111111..2222222 100644",
+  "--- a/src/a.ts",
+  "+++ b/src/a.ts",
+  "@@ -1,4 +1,12 @@",
+  ...Array.from({ length: 10 }, (_, i) => `+added ${i}`),
+  "-removed 1",
+  "-removed 2",
+  " context",
+  "diff --git a/doc/specs/x.md b/doc/specs/x.md",
+  "new file mode 100644",
+  "index 0000000..3333333",
+  "--- /dev/null",
+  "+++ b/doc/specs/x.md",
+  "@@ -0,0 +1,5 @@",
+  ...Array.from({ length: 5 }, (_, i) => `+spec ${i}`),
+  "diff --git a/.pi/gauntlet/telemetry/doc/specs/x.yaml b/.pi/gauntlet/telemetry/doc/specs/x.yaml",
+  "new file mode 100644",
+  "index 0000000..4444444",
+  "--- /dev/null",
+  "+++ b/.pi/gauntlet/telemetry/doc/specs/x.yaml",
+  "@@ -0,0 +1,3 @@",
+  "+schema: 1",
+  "+spec: doc/specs/x.md",
+  "+run_id: r-1",
+  "",
+].join("\n");
+const GIT_SHIM = (log) => `#!${process.execPath}
+require("node:fs").appendFileSync(${JSON.stringify(log)}, "git " + process.argv.slice(2).join(" ") + "\\n");
+process.stderr.write("fatal: not a git repository (or any of the parent directories): .git\\n");
+process.exit(128);
+`;
+const JJ_SHIM = (log, scriptPath) => `#!${process.execPath}
+const fs = require("node:fs");
+const a = process.argv.slice(2);
+fs.appendFileSync(${JSON.stringify(log)}, "jj " + a.join(" ") + "\\n");
+const script = JSON.parse(fs.readFileSync(${JSON.stringify(scriptPath)}, "utf8"));
+const s = a.join(" ");
+const send = (r) => { const res = r ?? { code: 1, stderr: "unscripted jj call" }; process.stdout.write(res.stdout ?? ""); process.stderr.write(res.stderr ?? ""); process.exit(res.code ?? 0); };
+if (s === "root") send(script.root);
+if (s.includes("--limit")) send(script.base);
+if (s.includes("--count")) send(script.count);
+if (s.includes("fork_point(")) send(script.fork);
+if (s.includes("--name-only")) send(script.names);
+if (s.startsWith("file track")) send(script.track);
+send(script.patch);
+`;
+const jjWorkspace = (t, script, { recordText = RECORD } = {}) => {
+  const root = mkdtempSync(join(tmpdir(), "gts-jj-"));
+  write(root, SPEC, "# Spec X\n\n**Goal:** g.\n");
+  if (recordText !== undefined) write(root, REC, recordText);
+  const shims = mkdtempSync(join(tmpdir(), "gts-shim-"));
+  const log = join(shims, "calls.log");
+  writeFileSync(log, "");
+  const scriptPath = join(shims, "script.json");
+  writeFileSync(scriptPath, JSON.stringify({ root: { code: 0, stdout: root + "\n" }, ...script }));
+  for (const [name, body] of [["git", GIT_SHIM(log)], ["jj", JJ_SHIM(log, scriptPath)]]) {
+    const p = join(shims, name);
+    writeFileSync(p, body);
+    chmodSync(p, 0o755);
+  }
+  cleanup(t, root, shims);
+  return { root, log, env: { PATH: `${shims}:${process.env.PATH}` } };
+};
+const happyJj = {
+  base: { code: 0, stdout: JJ_FORK + "\n" },
+  fork: { code: 0, stdout: JJ_FORK + "\n" },
+  count: { code: 0, stdout: "2\n" },
+  patch: { code: 0, stdout: JJ_PATCH },
+  track: { code: 0, stdout: "" },
+};
+
+test("jj workspace: record stamped shipped from the jj diff, one git probe, no git writes, file track instead of a commit", (t) => {
+  const { root, log, env } = jjWorkspace(t, happyJj);
+  const r = run(root, ["--spec", SPEC], env);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.lines, [`sealed ${REC}`]);
+  const rec = record(root);
+  assert.equal(rec.status, "shipped");
+  assert.equal(rec.events.at(-1).kind, "ship");
+  assert.equal(rec.events.at(-1).option, "squash");
+  assert.deepEqual(rec.derived.modified_files, ["src/a.ts"], "spec and telemetry-dir paths filtered");
+  assert.equal(rec.derived.diff.base, JJ_FORK);
+  assert.equal(rec.derived.diff.commits, 2);
+  assert.deepEqual(rec.derived.diff.buckets.code, { files: 1, insertions: 10, deletions: 2 });
+  const calls = readFileSync(log, "utf8").split("\n").filter(Boolean);
+  assert.deepEqual(calls.filter((c) => c.startsWith("git ")).map((c) => c.split(" ")[1]), ["rev-parse"], "git is only the failed checkout probe");
+  assert.ok(calls.some((c) => c === "jj root"));
+  assert.ok(calls.includes(`jj file track --include-ignored -- ${REC}`), "the record is tracked even under a gitignored dir");
+});
+
+test("jj workspace: a failing file track restores the pre-seal bytes and exits 1", (t) => {
+  const { root, env } = jjWorkspace(t, { ...happyJj, track: { code: 1, stderr: "Error: Path is not in the workspace\n" } });
+  const r = run(root, ["--spec", SPEC], env);
+  assert.equal(r.status, 1);
+  assert.equal(r.stderr, `seal failed ${REC}: Error: Path is not in the workspace`);
+  assert.equal(record(root).status, "in_progress");
+});
+
+test("jj workspace with unresolved mainline: warning recorded, diff fields absent, record still sealed", (t) => {
+  const { root, env } = jjWorkspace(t, { ...happyJj, fork: { code: 0, stdout: "" } });
+  const r = run(root, ["--spec", SPEC], env);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.lines, [`sealed ${REC}`]);
+  const rec = record(root);
+  assert.equal(rec.status, "shipped");
+  assert.ok(!("diff" in rec.derived) && !("modified_files" in rec.derived));
+  assert.equal(rec.events.find((e) => e.kind === "warning")?.message, "diff omitted: jj mainline unresolved (trunk() is root(); no main/master bookmark)");
+});
+
+test("jj diff failure and unparseable patch each seal with a warning and no diff fields", (t) => {
+  const failing = jjWorkspace(t, { ...happyJj, patch: { code: 1, stderr: "fatal: diff exploded\n" } });
+  const r1 = run(failing.root, ["--spec", SPEC], failing.env);
+  assert.equal(r1.status, 0, r1.stderr);
+  let rec = record(failing.root);
+  assert.equal(rec.status, "shipped");
+  assert.ok(!("diff" in rec.derived) && !("modified_files" in rec.derived));
+  assert.equal(rec.events.find((e) => e.kind === "warning")?.message, "diff omitted: jj diff failed: fatal: diff exploded");
+
+  const garbage = jjWorkspace(t, { ...happyJj, patch: { code: 0, stdout: "not a git patch\n" } });
+  const r2 = run(garbage.root, ["--spec", SPEC], garbage.env);
+  assert.equal(r2.status, 0, r2.stderr);
+  rec = record(garbage.root);
+  assert.equal(rec.events.find((e) => e.kind === "warning")?.message, "diff omitted: jj diff unparseable");
+});
+
+test("jj workspace: an unresolvable or empty --base revset fails no base ref, exit 1", (t) => {
+  const unknown = jjWorkspace(t, { ...happyJj, base: { code: 1, stderr: "Error: No such bookmark: nope\n" } });
+  const r1 = invoke(["--worktree", unknown.root, "--option", "squash", "--base", "nope", "--spec", SPEC], unknown.env);
+  assert.equal(r1.status, 1);
+  assert.equal(r1.stderr, "no base ref nope");
+  const empty = jjWorkspace(t, { ...happyJj, base: { code: 0, stdout: "" } });
+  const r2 = invoke(["--worktree", empty.root, "--option", "squash", "--base", "none()"], empty.env);
+  assert.equal(r2.status, 1);
+  assert.equal(r2.stderr, "no base ref none()");
+});
+
+test("jj workspace without --spec discovers records from the jj fork-point diff", (t) => {
+  const found = jjWorkspace(t, { ...happyJj, names: { code: 0, stdout: `${SPEC}\nsrc/a.ts\n` } });
+  const r1 = run(found.root, [], found.env);
+  assert.equal(r1.status, 0, r1.stderr);
+  assert.deepEqual(r1.lines, [`sealed ${REC}`]);
+  assert.ok(readFileSync(found.log, "utf8").includes(`jj --color=never diff --name-only --from ${JJ_FORK} --to @`));
+  const none = jjWorkspace(t, { ...happyJj, names: { code: 0, stdout: "src/a.ts\n" } });
+  const r2 = run(none.root, [], none.env);
+  assert.equal(r2.status, 0, r2.stderr);
+  assert.deepEqual(r2.lines, ["no telemetry run"]);
+});
+
+test("jj workspace: a shipped record is already sealed without any git checks", (t) => {
+  const { root, log, env } = jjWorkspace(t, happyJj, { recordText: SEALED });
+  const r = run(root, ["--spec", SPEC], env);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.lines, [`already sealed ${REC}`]);
+  assert.equal(record(root).shipped_at, "2026-09-17T18:00:00Z");
+  const calls = readFileSync(log, "utf8").split("\n").filter(Boolean);
+  assert.deepEqual(calls.filter((c) => c.startsWith("git ")).map((c) => c.split(" ")[1]), ["rev-parse"]);
+});

package/extensions/lib/telemetry-diff.ts

@@ -25,12 +25,13 @@ export function aggregateNumstat(numstat: string, files: Set<string>, buckets: B
 }
 
 export const JJ_MAINLINE = "coalesce(trunk() ~ root(), present(main), present(master))";
+// Without the ::M guard an empty mainline resolves to @ and counts the full history.
+export const JJ_FORK_POINT = `fork_point(${JJ_MAINLINE} | @) ~ root() & ::${JJ_MAINLINE}`;
 const firstLine = (s: string): string => s.trim().split("\n")[0];
 
 export async function computeJjDiff(o: { jj: Runner; cwd: string; spec: string; dir: string; planDirs: readonly string[]; buckets: Buckets }): Promise<DiffOutcome> {
   const failed = (sub: string, r: RunResult): DiffOutcome => ({ warning: `diff omitted: jj ${sub} failed: ${firstLine(r.stderr) || "unknown error"}` });
-  // Without the ::M guard an empty mainline resolves to @ and counts the full history.
-  const baseR = await o.jj(["--color=never", "log", "-r", `fork_point(${JJ_MAINLINE} | @) ~ root() & ::${JJ_MAINLINE}`, "--no-graph", "-T", 'commit_id ++ "\\n"'], o.cwd);
+  const baseR = await o.jj(["--color=never", "log", "-r", JJ_FORK_POINT, "--no-graph", "-T", 'commit_id ++ "\\n"'], o.cwd);
   if (baseR.code !== 0) return failed("log", baseR);
   const base = firstLine(baseR.stdout).trim();
   if (!base) return { warning: "diff omitted: jj mainline unresolved (trunk() is root(); no main/master bookmark)" };

package/extensions/lib/vcs.ts

@@ -0,0 +1,74 @@
+// VCS-flavor dispatch for gauntlet tools: the one module that knows both git and
+// jj, so callers (the telemetry seal bin today) stay flavor-free. Checkout
+// resolution delegates to checkout.ts, ship-diff derivation to telemetry-diff.ts.
+import { spawnSync } from "node:child_process";
+import { checkoutOfSync } from "./checkout.ts";
+import { computeGitDiff, computeJjDiff, JJ_FORK_POINT, type Buckets, type DiffOutcome, type RunResult } from "./telemetry-diff.ts";
+
+export interface VcsResult extends RunResult { ok: boolean }
+export type VcsRun = (args: string[], cwd: string, timeoutMs?: number) => VcsResult;
+export interface Vcs { kind: "git" | "jj"; root: string; run: VcsRun }
+
+// Prompts off so a credential or editor request cannot hang a non-interactive caller.
+const NO_PROMPT_ENV = { ...process.env, GIT_TERMINAL_PROMPT: "0", GIT_EDITOR: "true" };
+
+const runBinary = (bin: "git" | "jj"): VcsRun => (args, cwd, timeoutMs = 10_000) => {
+  // jj diff --git returns full patches; spawnSync's 1 MiB default buffer truncates them (ENOBUFS).
+  const r = spawnSync(bin, args, { cwd, encoding: "utf8", env: NO_PROMPT_ENV, timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024 });
+  const err = r.error as NodeJS.ErrnoException | undefined;
+  const timedOut = err?.code === "ETIMEDOUT";
+  const stderr = timedOut ? "timed out" : (r.stderr ?? "").trim().split("\n")[0] || err?.message || `${bin} exited ${r.status}`;
+  return { ok: !timedOut && r.status === 0, code: timedOut ? 1 : (r.status ?? 1), stdout: (r.stdout ?? "").trim(), stderr };
+};
+
+export function vcsFor(absPath: string): Vcs | undefined {
+  const co = checkoutOfSync(absPath);
+  return co && { kind: co.via, root: co.toplevel, run: runBinary(co.via) };
+}
+
+// The ship diff for a sealed record. git diffs o.base's merge-base against HEAD;
+// jj derives its own fork-point base (o.base is validation-only there).
+export async function computeShipDiff(vcs: Vcs, o: { spec: string; dir: string; planDirs: readonly string[]; buckets: Buckets; base: string }): Promise<DiffOutcome> {
+  return vcs.kind === "jj"
+    ? computeJjDiff({ jj: vcs.run, cwd: vcs.root, spec: o.spec, dir: o.dir, planDirs: o.planDirs, buckets: o.buckets })
+    : computeGitDiff({ git: vcs.run, cwd: vcs.root, spec: o.spec, dir: o.dir, planDirs: o.planDirs, buckets: o.buckets, base: o.base });
+}
+
+// git: any committish. jj: a revset (local bookmark, main@origin, trunk(), ...)
+// resolving to at least one commit; the ship diff still derives its own base.
+export function validateBase(vcs: Vcs, base: string): boolean {
+  const r = vcs.kind === "jj"
+    ? vcs.run(["--color=never", "log", "-r", base, "--limit", "1", "--no-graph", "-T", 'commit_id ++ "\\n"'], vcs.root)
+    : vcs.run(["rev-parse", "--verify", "-q", `${base}^{commit}`], vcs.root);
+  return r.ok && r.stdout !== "";
+}
+
+// Name-only working diff for record discovery. git diffs base...HEAD; jj diffs
+// the fork point computeJjDiff derives against @ (--base is validation-only on jj).
+export function changedNames(vcs: Vcs, base: string): VcsResult {
+  if (vcs.kind === "git") return vcs.run(["diff", "--no-renames", "--name-only", `${base}...HEAD`], vcs.root);
+  const forkR = vcs.run(["--color=never", "log", "-r", JJ_FORK_POINT, "--no-graph", "-T", 'commit_id ++ "\\n"'], vcs.root);
+  if (!forkR.ok) return forkR;
+  const fork = forkR.stdout.split("\n")[0];
+  if (!fork) return { ok: false, code: 1, stdout: "", stderr: "jj mainline unresolved (trunk() is root(); no main/master bookmark)" };
+  return vcs.run(["--color=never", "diff", "--name-only", "--from", fork, "--to", "@"], vcs.root);
+}
+
+// git: sealed == tracked and clean (ls-files --error-unmatch, diff --quiet HEAD).
+// jj: no commit step, so a shipped record is always sealed.
+export function recordSealed(vcs: Vcs, rel: string): boolean {
+  if (vcs.kind === "jj") return true;
+  return vcs.run(["ls-files", "--error-unmatch", "--", rel], vcs.root).ok
+    && vcs.run(["diff", "--quiet", "HEAD", "--", rel], vcs.root).ok;
+}
+
+// jj has no commit step: `file track --include-ignored` is the `git add -f` equivalent - it
+// snapshots the stamped record into the working-copy change even under a gitignored dir.
+export function commitRecordFile(vcs: Vcs, rel: string, message: string): VcsResult {
+  if (vcs.kind === "jj") return vcs.run(["file", "track", "--include-ignored", "--", rel], vcs.root);
+  const add = vcs.run(["add", "-f", "--", rel], vcs.root);
+  const commit = add.ok ? vcs.run(["commit", "-q", "-m", message, "--", rel], vcs.root, 30_000) : add;
+  // Unstage the -f add so a retry sees the same state.
+  if (!commit.ok) vcs.run(["reset", "-q", "--", rel], vcs.root);
+  return commit;
+}

package/extensions/phase-tracker.test.ts

@@ -1814,3 +1814,111 @@ test("grant: accepts MAX_SAFE_INTEGER and current on-disk cap controls whether t
   writeFileSync(join(changed.ctx.cwd, ".pi", "settings.json"), JSON.stringify({ piGauntlet: { closureReview: { maxFixRounds: 1 } } }));
   assert.match((await grant(changed, "g", { rounds: 1, reason: "ok" })).details.error ?? "", /0 used, cap 1/);
 });
+
+const eightTasks = (open: number[]) =>
+  Array.from({ length: 8 }, (_, i) => ({ name: `T${i + 1} task`, status: open.includes(i) ? "in_progress" : "complete" }));
+
+const resultText = async (h: ReturnType<typeof harness>, id: string, isError = false) => {
+  const [res] = (await h.emitEvent("tool_result", waveResult(id, [{ agent: "implementer", exitCode: 0 }], isError))) as (
+    | { content: { text: string }[] }
+    | undefined
+  )[];
+  return res?.content[0]?.text;
+};
+
+test("open-task nudge: verify-phase implementer wave lists mid-list open rows with the closure instruction, before any audit", async () => {
+  const h = harness({ branch: verifyBranch([taskSnapshot(eightTasks([3]))]) });
+  await h.emit("session_start");
+  const text = await resultText(h, "w1");
+  assert.ok(text, "nudge present");
+  assert.match(text, /^Plan tasks still open after this repair wave:\n3: T4 task \(in_progress\)\nOnce this wave's repair is integrated and its re-review or re-audit accepts it, close that task: plan_tracker\(\{ action: "update", index: N, status: "complete" \}\)\. Leave unaccepted repairs in_progress\. A pending row is a task still to run, not to close\. Open tasks block complete verify\.$/);
+  assert.doesNotMatch(text, /0: T1 task/);
+});
+
+// fixRounds is observed through the cap guard: one nudged wave against maxFixRounds 1
+// blocks the next dispatch exactly as an un-nudged wave would.
+test("open-task nudge: fires on every qualifying wave and leaves fix-round counting unchanged", async () => {
+  const h = guardedHarness({ piGauntlet: { closureReview: { enforce: true, maxFixRounds: 1 } } }, [taskSnapshot(eightTasks([0, 3]))]);
+  await h.emit("session_start");
+  assert.equal(await firstCallResult(h, "c1", implementerWave(1)), undefined);
+  assert.match((await resultText(h, "c1")) ?? "", /0: T1 task \(in_progress\)\n3: T4 task \(in_progress\)/);
+  const blocked = await firstCallResult(h, "c2", implementerWave(1));
+  assert.equal(blocked?.block, true, "one wave counted, cap 1 reached");
+  const h2 = guardedHarness({ piGauntlet: { closureReview: { enforce: true } } }, [taskSnapshot(eightTasks([3]))]);
+  await h2.emit("session_start");
+  assert.match((await resultText(h2, "a")) ?? "", /^Plan tasks still open/);
+  assert.match((await resultText(h2, "b")) ?? "", /^Plan tasks still open/);
+});
+
+// The closure-model mismatch warning is stashed at tool_call; it must render first.
+test("open-task nudge: a stashed tool_call warning stays ahead of the nudge on the same result", async () => {
+  const h = harness({
+    cwd: tempCwd({ piGauntlet: { closureReview: { enforce: true, model: "p/configured" } } }),
+    branch: verifyBranch([taskSnapshot(eightTasks([3]))]),
+  });
+  await h.emit("session_start");
+  const call = { tasks: [{ agent: "conformance-reviewer", model: "p/other", task: "audit" }, { agent: "implementer", task: "fix", worktree: true }] };
+  assert.equal(await firstCallResult(h, "m1", call), undefined);
+  const text = (await resultText(h, "m1")) ?? "";
+  const warningAt = text.indexOf("p/other");
+  const nudgeAt = text.indexOf("Plan tasks still open after this repair wave:");
+  assert.ok(warningAt >= 0 && nudgeAt > warningAt, `warning first, nudge second: ${text}`);
+});
+
+test("open-task nudge: silent outside the verify window and without open rows", async () => {
+  const cases: [string, ReturnType<typeof harness>][] = [
+    ["implement in progress", harness({ branch: implementBranch([taskSnapshot(eightTasks([3]))]) })],
+    [
+      "ship in progress",
+      harness({
+        branch: verifyBranch([
+          phaseResult("complete", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete" })),
+          phaseResult("start", phases({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" })),
+          taskSnapshot(eightTasks([3])),
+        ]),
+      }),
+    ],
+    ["all tasks complete or skipped", harness({ branch: verifyBranch([taskSnapshot([...eightTasks([]).slice(0, 7), { name: "T8 task", status: "skipped" }])]) })],
+    ["no snapshot on the branch", harness({ branch: verifyBranch() })],
+    ["latest snapshot is a clear", harness({ branch: verifyBranch([taskSnapshot(eightTasks([3])), taskSnapshot([])]) })],
+    ["rejected update is skipped, prior all-complete snapshot used", harness({ branch: verifyBranch([taskSnapshot(eightTasks([])), { type: "message", message: { role: "toolResult", toolName: "plan_tracker", details: { tasks: eightTasks([3]), error: "rejected" } } }]) })],
+    ["flowGuards.enforce: false", harness({ cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }), branch: verifyBranch([taskSnapshot(eightTasks([3]))]) })],
+    ["async handle results: []", harness({ branch: verifyBranch([taskSnapshot(eightTasks([3]))]) })],
+  ];
+  for (const [label, h] of cases) {
+    await h.emit("session_start");
+    if (label === "async handle results: []") {
+      assert.deepEqual(await h.emitEvent("tool_result", waveResult("x", [])), [undefined], label);
+      continue;
+    }
+    assert.equal(await resultText(h, "x"), undefined, label);
+  }
+});
+
+test("open-task nudge: closureReview.enforce: false does not silence it", async () => {
+  const h = harness({ cwd: tempCwd({ piGauntlet: { closureReview: { enforce: false } } }), branch: verifyBranch([taskSnapshot(eightTasks([3]))]) });
+  await h.emit("session_start");
+  assert.match((await resultText(h, "k")) ?? "", /^Plan tasks still open/);
+});
+
+test("open-task nudge: silent on an isError result, a degraded settings read, and in a subagent child", async () => {
+  const errored = harness({ branch: verifyBranch([taskSnapshot(eightTasks([3]))]) });
+  await errored.emit("session_start");
+  assert.equal(await resultText(errored, "e", true), undefined, "isError result");
+
+  const malformed = tempCwd();
+  mkdirSync(join(malformed, ".pi"), { recursive: true });
+  writeFileSync(join(malformed, ".pi", "settings.json"), "{ not json");
+  const degraded = harness({ cwd: malformed, branch: verifyBranch([taskSnapshot(eightTasks([3]))]) });
+  await degraded.emit("session_start");
+  assert.equal(await resultText(degraded, "d"), undefined, "settings errors");
+
+  process.env.PI_SUBAGENT_DEPTH = "1";
+  try {
+    const child = harness({ branch: verifyBranch([taskSnapshot(eightTasks([3]))]) });
+    await child.emit("session_start");
+    assert.equal(await resultText(child, "c"), undefined, "subagent child");
+  } finally {
+    process.env.PI_SUBAGENT_DEPTH = "0";
+  }
+});

package/extensions/phase-tracker.ts

@@ -101,6 +101,33 @@ const isImplementerWave = (details: unknown, isError: boolean | undefined): bool
   return d.results.some((r) => r?.agent === "implementer");
 };
 
+type Task = { name: string; status: string };
+
+// Latest successful plan_tracker snapshot on the current branch. Shared by the
+// completion backstop and the open-task nudge so both reason about one state;
+// read from session entries, so context pruning cannot hide it.
+const latestPlanSnapshot = (ctx: ExtensionContext): Task[] => {
+  for (const entry of [...ctx.sessionManager.getBranch()].reverse()) {
+    if (
+      entry.type !== "message" ||
+      entry.message.role !== "toolResult" ||
+      entry.message.toolName !== "plan_tracker" ||
+      entry.message.isError
+    ) {
+      continue;
+    }
+    const details = entry.message.details as { tasks?: Task[]; error?: string } | undefined;
+    if (!details || details.error || !details.tasks) continue;
+    return details.tasks;
+  }
+  return [];
+};
+
+const unfinishedTaskLines = (tasks: Task[]): string[] =>
+  tasks.flatMap((task, index) =>
+    task.status === "pending" || task.status === "in_progress" ? [`${index}: ${task.name} (${task.status})`] : [],
+  );
+
 // Review-cadence guard (spec 2026-08-12-execution-fidelity-hardening): presence-only
 // advisory ledger of the most recent completed implementer / spec-reviewer /
 // code-reviewer dispatch. Agents completing in the SAME dispatch share a sequence
@@ -210,6 +237,13 @@ const loneImplementerBlockReason =
   "a lone agent call runs unisolated and produces no worktree diff. " +
   "To disable this gate, set piGauntlet.closureReview.enforce: false.";
 
+// Preview the completion backstop so reopened tasks close at acceptance,
+// not before the repair is integrated and reviewed.
+const openTaskNudge = (rows: string[]): string =>
+  `Plan tasks still open after this repair wave:\n${rows.join("\n")}\n` +
+  'Once this wave\'s repair is integrated and its re-review or re-audit accepts it, close that task: plan_tracker({ action: "update", index: N, status: "complete" }). ' +
+  "Leave unaccepted repairs in_progress. A pending row is a task still to run, not to close. Open tasks block complete verify.";
+
 const fixRoundCapBlockReason = (used: number, cap: number, settingsPath: string): string =>
   `Conformance fix loop: ${used} fix round(s) used against a cap of ${cap} (granted rounds included); ` +
   "escalate to the human with the verdict trail instead of re-looping.\n" +
@@ -382,6 +416,10 @@ export default function (pi: ExtensionAPI) {
   // Warnings stashed at tool_call, prepended at tool_result (verify-before-ship pattern).
   // Relies on tool_result firing for every tool_call; reconstructState clears any stragglers.
   const pendingGuardWarnings = new Map<string, string>();
+  const addGuardWarning = (id: string, text: string) => {
+    const prior = pendingGuardWarnings.get(id);
+    pendingGuardWarnings.set(id, prior ? prior + "\n\n" + text : text);
+  };
 
   const activeGuardPhase = (): Phase | undefined =>
     GUARD_PHASES.find((p) => phases[p].status === "in_progress");
@@ -519,10 +557,6 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("tool_call", async (event, ctx) => {
     // D3.b: one fresh settings read per event, lazily, only if a guard needs it.
-    const addGuardWarning = (id: string, text: string) => {
-      const prior = pendingGuardWarnings.get(id);
-      pendingGuardWarnings.set(id, prior ? prior + "\n\n" + text : text);
-    };
     let gauntletCache: ReturnType<typeof loadGauntletSettings> | undefined;
     const g = () => {
       if (!gauntletCache) {
@@ -706,6 +740,18 @@ export default function (pi: ExtensionAPI) {
       observeFixWave(event.details, event.isError, ctx);
       if (qualifiesAsClosureDispatch(event.details)) conformanceDispatched = true;
       observeCadence(event.details);
+      if (
+        !isSubagentChild &&
+        gauntletEntered &&
+        phases.verify.status === "in_progress" &&
+        isImplementerWave(event.details, event.isError)
+      ) {
+        const loaded = loadGauntletSettings(ctx.cwd);
+        if (loaded.errors.length === 0 && resolveFlowGuards(loaded.gauntlet).enforce) {
+          const open = unfinishedTaskLines(latestPlanSnapshot(ctx));
+          if (open.length) addGuardWarning(event.toolCallId, openTaskNudge(open));
+        }
+      }
       const warning = pendingGuardWarnings.get(event.toolCallId);
       if (warning) {
         pendingGuardWarnings.delete(event.toolCallId);
@@ -989,26 +1035,7 @@ export default function (pi: ExtensionAPI) {
             (params.phase === "implement" || params.phase === "verify") &&
             resolveFlowGuards(loadGauntletSettings(ctx.cwd).gauntlet).enforce
           ) {
-            let tasks: { name: string; status: string }[] = [];
-            for (const entry of [...ctx.sessionManager.getBranch()].reverse()) {
-              if (
-                entry.type !== "message" ||
-                entry.message.role !== "toolResult" ||
-                entry.message.toolName !== "plan_tracker" ||
-                entry.message.isError
-              ) {
-                continue;
-              }
-              const details = entry.message.details as { tasks?: { name: string; status: string }[]; error?: string } | undefined;
-              if (!details || details.error || !details.tasks) continue;
-              tasks = details.tasks;
-              break;
-            }
-            const unfinished = tasks.flatMap((task, index) =>
-              task.status === "pending" || task.status === "in_progress"
-                ? [`${index}: ${task.name} (${task.status})`]
-                : [],
-            );
+            const unfinished = unfinishedTaskLines(latestPlanSnapshot(ctx));
             if (unfinished.length) {
               return {
                 content: [

package/extensions/test-support/pi-stubs.mjs

@@ -6,13 +6,16 @@ const sources = {
     import { readFileSync } from "node:fs";
     export class SettingsManager {
       static create(cwd) { return new SettingsManager(cwd); }
-      constructor(cwd) { this.cwd = cwd; }
+      constructor(cwd) { this.cwd = cwd; this.errors = []; }
       getGlobalSettings() { return {}; }
       getProjectSettings() {
         try { return JSON.parse(readFileSync(this.cwd + "/.pi/settings.json", "utf8")); }
-        catch { return {}; }
+        catch (error) {
+          if (error?.code !== "ENOENT") this.errors.push({ scope: "project", error });
+          return {};
+        }
       }
-      drainErrors() { return []; }
+      drainErrors() { const drained = this.errors; this.errors = []; return drained; }
     }
     export const getAgentDir = () => "/tmp/pi-gauntlet-test-agent";
   `,

package/package.json

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

package/skills/brainstorming/SKILL.md

@@ -67,7 +67,7 @@ The spec is the first commit in a dedicated worktree, never a separate commit on
 
 Invoke `/skill:using-git-worktrees`; use `.worktrees/` or the project-native location. Carry its `Worktree ready at <full-path>` value: spec path `<full-path>/<spec dir>/<filename>.md`; every dispatch uses that `cwd`; git uses `git -C <full-path>`. Keep the process cwd unchanged.
 
-Spec, plan, and implementation share this worktree. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `/skill:finishing-a-development-branch` strips the plan, then seals and commits the record before landing. Explicit trivial one-off edits outside this flow need no worktree.
+Spec, plan, and implementation share this worktree. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `/skill:finishing-a-development-branch` strips the plan, then seals the record before landing (a `telemetry:` commit under git; the working-copy snapshot in a plain jj workspace). Explicit trivial one-off edits outside this flow need no worktree.
 
 ## The Process
 
@@ -146,9 +146,11 @@ Follow [User Review Gate](reference/spec-finalization.md#user-review-gate) for s
 
 Execute in place from any later phase; never invoke `/skill:brainstorming` for it (its entry resets both trackers). Worktree, spec commits, and plan survive.
 
+Every skill resource in this flow (a `SKILL.md` or a `reference/*.md`) is loaded with the `read` tool at its absolute path under `skills/`, never with a shell command - pruning protection keys on `read`'s `path`.
+
 Classify first. Redraw test: the change alters the problem statement, adds or removes a component, or moves a component boundary -> redraw. A change inside one component (a persistence mechanism, a worker's HTTP client, dropping a fallback and its task) -> amend. State the call; the user overrides either way.
 
-Amend -> load `reference/amendment-surface.md` and follow it (unreadable -> stop with a blocking error; never improvise the grammar). Apply its [Standing grants](reference/amendment-surface.md#standing-grants) boundaries.
+Amend -> `read` `reference/amendment-surface.md` and follow it (unreadable -> stop with a blocking error; never improvise the grammar). Apply its [Standing grants](reference/amendment-surface.md#standing-grants) boundaries.
 
 Redraw: keep the worktree and the approved spec file. `plan_tracker({ action: "clear" })`, `phase_tracker({ action: "reset" })`, `phase_tracker({ action: "start", phase: "brainstorm" })`, delete the plan file, resume at checklist step 4 with the approved spec as the draft (steps 2-3 skipped). Spec-writing overwrites it; the full gate follows.
 

package/skills/brainstorming/reference/amendment-surface.md

@@ -1,6 +1,6 @@
 # Amendment surface
 
-Load from `skills/brainstorming/SKILL.md` § Amending an approved spec, from any phase, for amend-class changes; at approval, load only [Standing grants](#standing-grants), not the batch procedure. Keep redraws outside this procedure. Only the main loop holding `edit`/`write` authors amendments and human-facing amendment text. Use the human last: a fresh reviewer clears evidence-backed factual corrections; present the rest to the human once per batch plainly.
+`read` this file (the `read` tool at its absolute path, never a shell command) from `skills/brainstorming/SKILL.md` § Amending an approved spec, from any phase, for amend-class changes; at approval, load only [Standing grants](#standing-grants), not the batch procedure. Keep redraws outside this procedure. Only the main loop holding `edit`/`write` authors amendments and human-facing amendment text. Use the human last: a fresh reviewer clears evidence-backed factual corrections; present the rest to the human once per batch plainly.
 
 ## Standing grants
 
@@ -77,7 +77,7 @@ Fail closed: a dispatch error, an async handle, a silence-kill, or a missing or
 Render only escalated and prefiltered items; `<N>` counts them. Nothing symbol-dense above the fold; each item's `old -> new` sits under `Details`, after the footer.
 
 ```
-Spec amendments: <N> need your call - from <trigger>; applying as recommended <reopens | adds | removes> <task ids | no tasks>; <phase consequence | no phase change>.
+Spec amendments: <N> need your call - from <trigger>; applying as recommended <reopens | adds | removes> <task ids | no tasks>; no phase change.
 
 * <handle> - <title>: <what>. <why>.
   Example: <before -> after>
@@ -93,7 +93,7 @@ Details
 <handle>: <location> - old: <text> -> new: <text>
 ```
 
-`<trigger>` is the step the main loop is running when the batch forms: `the spec review`, `planning Task <n>`, `Task <n> BLOCKED`, `the verify-phase code review (FIX_FIRST <ids>)`, `the finish-gate council-edit revert`, else `the <phase> phase`; `your request` only for an amend the user raised in prose. The plan clause is the section 5 aftermath as `recommended` would land, over reviewer-cleared plus rendered items, read from the plan file and tracker state - call no `plan_tracker`/`phase_tracker` before the reply: any of `reopens <ids>`, `adds <n> task(s)`, `removes <ids>`, comma-joined (`reopens no tasks` when the plan is untouched), then `; restarts implement, then verify` when a reopen lands in `verify`/`ship`, else `; no phase change`.
+`<trigger>` is the step the main loop is running when the batch forms: `the spec review`, `planning Task <n>`, `Task <n> BLOCKED`, `the verify-phase code review (FIX_FIRST <ids>)`, `the finish-gate council-edit revert`, else `the <phase> phase`; `your request` only for an amend the user raised in prose. The plan clause is the section 5 aftermath as `recommended` would land, over reviewer-cleared plus rendered items, read from the plan file and tracker state - call no `plan_tracker`/`phase_tracker` before the reply: any of `reopens <ids>`, `adds <n> task(s)`, `removes <ids>`, comma-joined (`reopens no tasks` when the plan is untouched), then `; no phase change`.
 
 `Reviewer:` quotes the `<one-line reason>` of the section 3 reply verbatim; the `probed:` half stays in the commit body; a prefiltered item carries `not reviewed - <the rule that prefiltered it>`. `Impact:` restates the design-contract shift from `location` in the reader's words, never quoted spec text, one clause per touched decision, `;`-joined; `(none) -> <new>` for a contract added, `<old> -> (removed)` for a contract removed. `Details` keeps the verbatim `old -> new`.
 
@@ -101,9 +101,11 @@ Details
 
 ## 5. Apply, aftermath, commit
 
+Before the aftermath, `read` this section again; never run it from memory.
+
 Apply accepted items only: reviewer clears, `accept`, `alt-n`, and state-changing `custom`. Print one line per applied item: `amended the spec: <title> - <what>`.
 
-Aftermath, once per batch, only when at least one item applied (nothing applied -> skip to the commit below). No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks; anchor-changed completed tasks are reopened as `in_progress` and re-run the task loop (`update` never sets `pending`). A removed task is deleted from the plan; then re-`init` the tracker with `{ name, status }` elements: preserved tasks keep their order and statuses, reopened tasks are `in_progress` in place, every still-`pending` task (including newly added ones, whatever wave label they carry) trails the non-pending ones, removed tasks are the only deletions (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress: `phase_tracker({ action: "skip", phase: "<current>", reason: "amendment reopened Task N" })`, then `phase_tracker({ action: "start", phase: "implement", force: true })`; later phases re-enter with `force: true` and rerun in full.
+Aftermath, once per batch, only when at least one item applied (nothing applied -> skip to the commit below). No plan yet -> commit the spec; continue. Plan exists -> update affected anchors and tasks: `plan_tracker` `add` for new tasks; anchor-changed completed tasks are reopened as `in_progress` and re-run the task loop (`update` never sets `pending`). A removed task is deleted from the plan; then re-`init` the tracker with `{ name, status }` elements: preserved tasks keep their order and statuses, reopened tasks are `in_progress` in place, every still-`pending` task (including newly added ones, whatever wave label they carry) trails the non-pending ones, removed tasks are the only deletions (the only permitted `init` after handoff; never `clear`). Re-run `plan_check` until it passes, commit spec + plan together; continue. A task reopened while `verify` or `ship` is in progress stays in that phase - no `phase_tracker` call. Repair it through the current phase's fix loop and `plan_tracker({ action: "update", index: N, status: "complete" })` it once that repair's review or re-audit accepts; open tasks block `complete verify`, and in `ship` nothing checks them, so close them explicitly.
 
 One commit per batch:
 

package/skills/finishing-a-development-branch/SKILL.md

@@ -94,7 +94,7 @@ then continue directly to Step 4. No approval prompt, no menu, no shared options
 
 When the sentinel carries a `happy-path:` line, print it directly under `Closure / conformance: CONFORMS` as one informational, non-blocking line in the same shape as the `auto-applied fix commits` line: `happy-path: passed`, `happy-path: failed - unattributable`, or `happy-path: not run - <reason>` (a `failed - attributed to G<n>` value cannot reach this branch: its gaps are open).
 
-**Pre-menu amendment funnel (GAPS only).** Before rendering the carried-open menu, run [`amendment-surface.md` § Conformance entry](../brainstorming/reference/amendment-surface.md) over the inventory once: gaps with `recommended: accept`, verdict `DRIFTED` or `PARTIAL`, not `UNAUTHORIZED`, whose `origin` is not an acceptance criterion are drafted as `accept-into-spec` items (the edit built from `origin` + `evidence`) and sent to the reviewer in one call; cleared items apply and land as one batch commit, the spec is re-audited, the inventory regenerated. Only concerns the re-audit actually closed drop out; sibling concerns in the same gap keep their rows and dispositions. Survivors and every other gap render as ordinary rows below - one menu, never two.
+**Pre-menu amendment funnel (GAPS only).** Before rendering the carried-open menu, `read` and run [`amendment-surface.md` § Conformance entry](../brainstorming/reference/amendment-surface.md) over the inventory once: gaps with `recommended: accept`, verdict `DRIFTED` or `PARTIAL`, not `UNAUTHORIZED`, whose `origin` is not an acceptance criterion are drafted as `accept-into-spec` items (the edit built from `origin` + `evidence`) and sent to the reviewer in one call; cleared items apply and land as one batch commit, the spec is re-audited, the inventory regenerated. Only concerns the re-audit actually closed drop out; sibling concerns in the same gap keep their rows and dispositions. Survivors and every other gap render as ordinary rows below - one menu, never two.
 
 **Carried-open (`status: GAPS (N open)`).** Read `reference/disposition-protocol.md` and follow it for the carried-open render (dense) grammar, the response grammar, and the 9-step execute order. Render the human decision menu in the shape below, with the sentinel's `happy-path:` line (when present) printed as one informational line directly under the `Conformance: N decisions needed before shipping.` header - a `failed - attributed to G<n>,...` value names the rows whose evidence is the transcript, a `rescope` recommendation on such a row means the failure lies in code the change never owned - drive the dispositions per that reference, then print the summary render and continue to Step 4. If that reference file cannot be read, stop and surface a blocking error — do **not** improvise the grammar from memory.
 
@@ -187,7 +187,7 @@ Rows 1-2 run the Option 1/2 blocks; row 3 runs the Keep block and row 4 the Disc
 
 #### Strip the plan, seal the record (Options 1-3)
 
-Run this on the feature branch before any landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. The record is an untracked, git-excluded file until this step commits it. `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
+Run this on the feature branch before any landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. The record is an untracked, git-excluded file until this step commits it (in a plain jj workspace there is no commit; jj snapshots the stamped record into the working-copy change). `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
 
 Read the plan's `**Spec:**` header (repo-relative, backticks stripped) before the strip; pass that value as `--spec`. Resolve the spec dirs with `gauntlet_setting({ key: "flowGuards" })` and use their sibling `plans` dirs for plan paths.
 
@@ -196,14 +196,19 @@ Read the plan's `**Spec:**` header (repo-relative, backticks stripped) before th
 PLAN_PATH=<sibling-plans-dir>/<plan-file>.md   # the sibling plans dir of the spec's dir
 if git -C "$WORKTREE" ls-files --error-unmatch "$PLAN_PATH" >/dev/null 2>&1; then
   git -C "$WORKTREE" rm "$PLAN_PATH" && git -C "$WORKTREE" commit -m "Remove ephemeral plan doc"
+elif [ -f "$WORKTREE/$PLAN_PATH" ] && jj -R "$WORKTREE" root >/dev/null 2>&1; then
+  # Plain jj workspace (no .git): the removal lands in the working-copy change; there is no commit step.
+  # root: anchors the path at the workspace root - jj resolves bare paths against cwd, not -R.
+  jj -R "$WORKTREE" restore --from <base-branch> -- "root:\"$PLAN_PATH\""
 fi
 
 # Seal the telemetry record: stamp shipped, compute the diff, commit it once.
+# The bin detects a plain jj workspace (no .git) itself: jj diff, no commit step.
 # --option is pr for Options 1-2 and squash for Option 3; --spec is the plan header's **Spec:** value (omit when no plan is known).
 node <bin>/gauntlet-telemetry-seal.mjs --worktree "$WORKTREE" --option <pr|squash> --base <base-branch> --spec <spec path>
 ```
 
-The seal prints one line per record (`sealed <path>`, `already sealed <path>`) or one bare outcome (`no telemetry run`, `telemetry disabled`) and exits 0; print its stdout verbatim in the ship completion message. Any nonzero exit stops the flow before the first landing command, quoting the bin's line: exit 2 (`no record at <path>`, `unparseable record <path>: <reason>`) means this gauntlet run's recorder never armed or its record is corrupt; exit 1 is a usage, environment, or git failure (`seal failed <path>: <reason>` restored the pre-seal bytes). The user decides; never land without the seal.
+The seal prints one line per record (`sealed <path>`, `already sealed <path>`) or one bare outcome (`no telemetry run`, `telemetry disabled`) and exits 0; print its stdout verbatim in the ship completion message. Any nonzero exit stops the flow before the first landing command, quoting the bin's line: exit 2 (`no record at <path>`, `unparseable record <path>: <reason>`) means this gauntlet run's recorder never armed or its record is corrupt; exit 1 is a usage, environment, or git/jj failure (`seal failed <path>: <reason>` restored the pre-seal bytes). The user decides; never land without the seal.
 
 #### Option 1: Push and Create PR
 

package/skills/subagent-driven-development/SKILL.md

@@ -65,7 +65,7 @@ For each task in `plan_tracker`:
 6. If the quality review is issue-bearing → re-dispatch the implementer per `/skill:requesting-code-review` Fix rounds → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 7. After its existing reviews accept the work (and its required commit point), mark that same task index `complete` in `plan_tracker`. A subagent exit or green tests alone are not acceptance.
 
-The orchestrator is the spec's only writer during execution. Amendment trigger: implementer `BLOCKED` citing a spec defect, or a review finding showing the spec (not the code) is wrong -> pause the fix loop, execute brainstorming's [amendment path](../brainstorming/SKILL.md#amending-an-approved-spec) in place (it reviews first, stops only on escalation or redraw), resume. Code-vs-spec mismatch stays in the SR loop. An SR unable to read the spec at a cited anchor (missing file, unresolvable heading/range) returns a blocking finding — the contract is spec+task or stop, never a silent fallback to task-only review.
+The orchestrator is the spec's only writer during execution. Amendment trigger: implementer `BLOCKED` citing a spec defect, or a review finding showing the spec (not the code) is wrong -> pause the fix loop, `read` and execute brainstorming's [amendment path](../brainstorming/SKILL.md#amending-an-approved-spec) in place (it reviews first, stops only on escalation or redraw), resume. Code-vs-spec mismatch stays in the SR loop. An SR unable to read the spec at a cited anchor (missing file, unresolvable heading/range) returns a blocking finding — the contract is spec+task or stop, never a silent fallback to task-only review.
 
 After all tasks: proceed to [After All Tasks](#after-all-tasks-complete) - it owns parent full verification, then whole-diff code review, then conformance.