pi-gauntlet 7.0.0 → 7.0.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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
+
+- **gatekeep-pr: cross-repo split is explicit.** `reference/findings.md` "Whole or part": a PR in another repository, named in the ticket body or a human ticket comment, waives exactly the rows whose mechanism lives there; a PR named only in this PR's body stays a lead. The `gap` table row carries the same exception. Before, a two-repo ticket produced an unfixable blocker per row owned by the other repo.
+- **gatekeep-pr: one defect, one blocker.** A missing mechanism that surfaces as reviewer finding, AC `gap`, doc drift, and `contradicted` claim at once renders as one blocker with every locator (`reference/findings.md` "Namespaces").
+- **gatekeep-pr: `Delivers` composes.** The coverage, split, and observation clauses are optional and joined with semicolons, so "covers none of the ACs" and "whole + observation half" both render (`reference/report.md`). The compose hint lists only compositions whose verbs are rendered rows (`reference/decision-menu.md`). `## PR gate` `verification command` accepts one command per subproject, resolved by the diff's paths (`reference/assessment.md`).
+
 ## v7.0.0 - 2026-10-01
 
 ### Changed

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "7.0.0",
+  "version": "7.0.2",
   "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
 

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

@@ -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/gatekeep-pr/reference/assessment.md

@@ -25,7 +25,7 @@ Resolve per concern, first match wins, evaluated unconditionally - never delegat
 
 ```markdown
 ## PR gate
-- verification command: <command>            # required unless documented elsewhere
+- verification command: <command>            # required unless documented elsewhere; one command per subproject ("<dir>: <command>") resolves by the diff's paths, every touched subproject runs
 - timeout minutes: 15                        # optional; default 15
 - requires credentials: false                # optional; true => the gate reports "not run" as missing evidence
 - local verification: always                 # optional; default (absent) = CI-first; "always" forces the local run even when exact-head CI is green

package/skills/gatekeep-pr/reference/decision-menu.md

@@ -21,7 +21,7 @@ Rows are `<n>. <verb> - <consequence>`; every row, `stop` and `(not available: .
 - `wait` - poll the reviewer run, the pending required checks, and the comment set, then re-render
 - `stop` - leave the PR as-is
 
-Compose hint: `Type a number, or compose: "fix 2", "fix nits", "fix + nits", "fix 1 + reply".` A composed line never bundles a push-producing verb (`fix`, `push`) with `merge`. When a failing check withholds `merge`, the hint line also offers `check <name> flaky | real | ci-broken`, which records the disposition on that check (`findings.md` `## Dispositions`): `flaky` lifts the blocker, `real` keeps it until green, `ci-broken` triggers the fallback local run (`ci-broken` records `ci-infrastructure-broken`).
+Compose hint: `Type a number, or compose: "fix 2", "fix nits", "fix + nits", "fix 1 + reply".` The hint lists only compositions whose every verb is a rendered row: no `Nits` section, no `fix nits`; no `reply` row, no `fix 1 + reply`; no composable row, `Type a number.` alone. A composed line never bundles a push-producing verb (`fix`, `push`) with `merge`. When a failing check withholds `merge`, the hint line also offers `check <name> flaky | real | ci-broken`, which records the disposition on that check (`findings.md` `## Dispositions`): `flaky` lifts the blocker, `real` keeps it until green, `ci-broken` triggers the fallback local run (`ci-broken` records `ci-infrastructure-broken`).
 
 A composed line naming a `(not available: ...)` row is refused by name and the menu re-renders; the two `merge anyway` forms are the only overrides.
 

package/skills/gatekeep-pr/reference/findings.md

@@ -15,7 +15,7 @@ Split each AC row once into a **mechanism half** (code + test + doc that make th
 | Outcome | Condition | Renders as | Blocks |
 |---|---|---|---|
 | `covered` | evidence matches what the AC promises: executable behavior needs the code path plus a real test that exercises it; a documentation-only AC is judged against the promised doc text and demands no test; in both cases docs that describe the behavior agree with it | counted in `Delivers` | no |
-| `gap` | any part of the mechanism absent in this PR | one `Blockers` item | yes - a mechanism `gap` is a blocker |
+| `gap` | any part of the mechanism absent in this PR and the row not explicitly split (see Whole or part) | one `Blockers` item | yes - a mechanism `gap` is a blocker |
 | `not judged here` | the observation half; the mechanism half of the same row is still judged `covered`/`gap` | one `Delivers` clause ("<row>'s observable half is checked after merge, not here"); nothing is written, listed, or handed to check-delivery | no |
 | `impossible` | a `gap` whose fix is on the ticket - all four conditions below hold | one `Ticket changes` item with a drafted replacement AC text, in state `drafted` or `proposed` | withholds `merge` until the ticket body changes or the human picks `merge anyway - accept AC<n> as impossible` |
 
@@ -25,7 +25,7 @@ Split each AC row once into a **mechanism half** (code + test + doc that make th
 
 **No ticket** (none linked, or fetch failed): no AC rows; `Delivers` states the PR's intent as read from its title and body; `not judged here`, `impossible`, `Ticket changes`, and scope creep do not apply.
 
-**Whole or part.** With a ticket linked, `Delivers` names coverage: *whole* when every row is `covered` or is `not judged here` with its mechanism half `covered`; *part, acceptable* when every uncovered row is either an observation half or **explicitly split** - the ticket body or a human-authored ticket comment names another tracker ref for that row, read from the tracker this run. Only the tracker waives an obligation: a spec `deferred: <where>`, a linked later PR, or a `proposed` (not yet `resolved`) ticket change is a lead to check the tracker, never a waiver. Any other uncovered row is `gap`: "a later PR will add X" in the PR body, an unchecked box with no tracker split, a `deferred:` the ticket does not confirm.
+**Whole or part.** With a ticket linked, `Delivers` names coverage: *whole* when every row is `covered` or is `not judged here` with its mechanism half `covered`; *part, acceptable* when every uncovered row is either an observation half or **explicitly split** - the ticket body or a human-authored ticket comment, read from the tracker this run, names another tracker ref or a PR in another repository for that row; a cross-repo PR named there waives exactly the rows whose mechanism lives in that repository. Only the tracker waives an obligation: a spec `deferred: <where>`, a later PR in the same repository, a PR named only in this PR's body, or a `proposed` (not yet `resolved`) ticket change is a lead to check the tracker, never a waiver. Any other uncovered row is `gap`: "a later PR will add X" in the PR body, an unchecked box with no tracker split, a `deferred:` the ticket does not confirm.
 
 **Claims.** The Verifier's three dispositions stand. `contradicted` is a blocker. `unverifiable-pre-merge` is not evidence and renders nothing: a PR whose only proof of a new path is "verified on stg" is blocked by the untested-path rubric row, not by a claim rule.
 
@@ -40,6 +40,8 @@ Every finding is one of two:
 
 Behavior the ticket promises is a blocker or an explicit tracker split - never deferred to a PR nobody opened.
 
+**One defect, one blocker.** A missing mechanism surfaces through several rules at once (reviewer finding, AC `gap`, doc drift, `contradicted` claim); render it as one blocker that names the defect and lists every locator, and keep each contributing rule's ID in the ledger.
+
 **Severity translation.** Reviewer Critical and Moderate -> blocker; Minor -> nit. A repo `REVIEW.md` mapping overrides this; a severity it names but does not map is fail-safe blocker, noted in `show evidence`.
 
 **Triage bar** for findings the orchestrator originates itself: blocker only when it must be fixed before merge (correctness, security, a material performance trap, a convention the repo enforces); everything else is a nit, whatever its category. The bar never re-triages a classification the severity translation already made.

package/skills/gatekeep-pr/reference/report.md

@@ -9,9 +9,11 @@ Render bottom-up for a terminal: least important first, verdict and menu last. E
 Section order is fixed:
 
 ```
-Delivers: <one or two sentences: what the PR does; with a ticket: "The PR covers the whole <ref>." |
-          "The PR covers AC1-2 of <ref>; AC3's observable half (<what>) is checked after merge, not here." |
-          "The PR covers AC1 of <ref>; AC2 belongs to <split ref>.">
+Delivers: <one sentence: what the PR does. With a ticket, a second sentence built from these clauses in
+          order, each present only when it applies: coverage ("The PR covers the whole <ref>" | "covers
+          AC1-2 of <ref>" | "covers none of <ref>'s ACs"); split ("AC3 belongs to <split ref>");
+          observation ("AC4's observable half (<what>) is checked after merge, not here"); joined with
+          semicolons.>
 
 Ticket changes:          (one item per unresolved `impossible` row)
 - AC<n> asks for <X>, and <cited constraint>. Proposed wording: "<new AC text>". (drafted | proposed <comment url>; <source>)