pi-gauntlet 5.18.6 → 5.19.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v5.19.0 - 2026-09-26
+
+### Added
+
+- `gauntlet-resume` accepts a spec seed: a one-token `.md` file tracked on main under a configured spec dir. The route (`skills/gauntlet-resume/reference/seed.md`) checks primary session, tracked, and not shipped, derives the branch name from the spec basename minus its date, reuses the worktree registered for that branch or creates it through `/skill:using-git-worktrees`, pins the spec, and continues in reconstruction. Reconstruction pairs a candidate plan with a spec tracked from base; a plan already at base reports `plan predates base; no post-base task evidence`.
+
+### Changed
+
+- `gauntlet-resume` arguments classify by token count then content: a file whose line 1 starts `# Handoff:` is a brief regardless of extension, a `.md` under a spec dir is a seed, an existing git worktree root or bare name is a worktree. "Never creates a worktree" narrows to "never `git worktree add` directly". Supersedes the matching clauses of `doc/specs/2026-09-17-gh-31-gauntlet-resume.md` and `doc/specs/2026-09-20-gh-40-gauntlet-handoff-shared-brief-contract.md`.
+
+## v5.18.7 - 2026-09-24
+
+### Added
+
+- The telemetry recorder derives `modified_files` and diff buckets in plain jj workspaces through `jj` (remote trunk or local `main`/`master` as the mainline), with jj-named warnings and an intact record on any jj failure. (#51)
+
 ## v5.18.6 - 2026-09-24
 
 ### Changed

package/README.md

@@ -69,7 +69,7 @@ Everything between gate 1 and gate 2 - task breakdown, implementation, both revi
 
 pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-- **20 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `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`, `writing-skills`, `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). Seven more are explicit-invocation-only (`disable-model-invocation: true`): `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 - 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, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) 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, 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/`) or a bare worktree that already holds a spec, restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), never creates a worktree, and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief>] [<worktree>]`.
+- **20 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `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`, `writing-skills`, `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). Seven more are explicit-invocation-only (`disable-model-invocation: true`): `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 - 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, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) 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, 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 committed YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - finishing and the PR gate restore a stripped record, and stamp a record left `in_progress` with no ship phase as `shipped`, with `gauntlet-telemetry-salvage` - 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.
 
@@ -90,6 +90,9 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 3. Hotfix context with non-pending trackers: the brief ends at `## Skills loaded`; resume takes the `chase-bug` route.
 4. Fresh session, zero arguments: the listing shows the briefs from 1-3 and a pick restores; `/skill:gauntlet-resume /nonexistent.md` stops naming that path without listing anything.
 5. Branch `hotfix/x`: the default file is `pi-handoff/hotfix-x.md` and appears in the zero-argument listing.
+6. Primary session, idle trackers, spec tracked on main: `/skill:gauntlet-resume doc/specs/<x>.md` creates the worktree and asks the approval question; approval leaves `phase_tracker` at plan in_progress with brainstorm `⊘ (resume: ...)`.
+7. Fresh idle session, same seed: the registered worktree is reused (no creation) and the question repeats. Run once on a consumer whose `## using-git-worktrees` override lays worktrees out as sibling dirs, once on `.worktrees/`.
+8. After writing-plans commits the plan beside the seeded spec: `/skill:gauntlet-handoff` then a fresh `/skill:gauntlet-resume <brief>` restores plan phase; a fresh `/skill:gauntlet-resume <worktree>` reaches "Spec with plan" with task evidence from the plan commit.
 
 ## Key concepts
 

package/extensions/lib/telemetry-paths.test.ts

@@ -9,6 +9,7 @@ import {
   matchDiscardStatement,
   matchShipStatement,
   matchTestStatement,
+  parsePatchNumstat,
   parseSpecLinks,
   planSpecHeader,
   recordPathFor,
@@ -95,6 +96,48 @@ test("aggregateNumstat sums per bucket over the given file set; binary rows coun
   });
 });
 
+const patch = (...blocks: string[][]) => blocks.map((b) => b.join("\n")).join("\n") + "\n";
+
+test("parsePatchNumstat counts hunk lines and paths with spaces", () => {
+  const p = patch(
+    ["diff --git a/src/a.ts b/src/a.ts", "--- a/src/a.ts", "+++ b/src/a.ts", "@@ -1 +1 @@", "+a", "+b", "-c", "\"],
+    ["diff --git a/sp ace.txt b/sp ace.txt", "--- a/sp ace.txt", "+++ b/sp ace.txt", "@@ -1 +1 @@", "-x", "+y"],
+  );
+  assert.deepEqual(parsePatchNumstat(p), [{ added: 2, removed: 1, path: "src/a.ts" }, { added: 1, removed: 1, path: "sp ace.txt" }]);
+});
+
+test("parsePatchNumstat handles renames and delete/add pairs", () => {
+  assert.deepEqual(parsePatchNumstat(patch(
+    ["diff --git a/old.ts b/new.ts", "rename from old.ts", "rename to new.ts"],
+    ["diff --git a/o2.ts b/n2.ts", "rename from o2.ts", "rename to n2.ts", "--- a/o2.ts", "+++ b/n2.ts", "@@ -1 +1,2 @@", " k", "+extra"],
+    ["diff --git a/gone.ts b/gone.ts", "deleted file mode 100644", "--- a/gone.ts", "+++ /dev/null", "@@ -1 +0,0 @@", "-old"],
+    ["diff --git a/newer.ts b/newer.ts", "new file mode 100644", "--- /dev/null", "+++ b/newer.ts", "@@ -0,0 +1 @@", "+new"],
+  )), [
+    { added: 0, removed: 0, path: "new.ts" }, { added: 1, removed: 0, path: "n2.ts" },
+    { added: 0, removed: 1, path: "gone.ts" }, { added: 1, removed: 0, path: "newer.ts" },
+  ]);
+});
+
+test("parsePatchNumstat handles binary, mode-only and positional hunk headers", () => {
+  assert.deepEqual(parsePatchNumstat(patch(
+    ["diff --git a/dir b/icon.png b/dir b/icon.png", "Binary files a/dir b/icon.png and b/dir b/icon.png differ"],
+    ["diff --git a/run.sh b/run.sh", "old mode 100644", "new mode 100755"],
+    ["diff --git a/image.png b/image.png", "GIT binary patch", "literal 4"],
+    ["diff --git a/test/fm.md b/test/fm.md", "--- a/test/fm.md", "+++ b/test/fm.md", "@@ -1 +1 @@", "----", "++text"],
+  )), [
+    { added: 0, removed: 0, path: "dir b/icon.png" }, { added: 0, removed: 0, path: "run.sh" },
+    { added: 0, removed: 0, path: "image.png" }, { added: 1, removed: 1, path: "test/fm.md" },
+  ]);
+});
+
+test("parsePatchNumstat rejects malformed input and accepts empty patches", () => {
+  assert.deepEqual(parsePatchNumstat(""), []);
+  assert.deepEqual(parsePatchNumstat("  \n\n"), []);
+  assert.equal(parsePatchNumstat("garbage\n"), null);
+  assert.equal(parsePatchNumstat("diff --git a/x b/y\nindex 1..2\n"), null);
+  assert.equal(parsePatchNumstat("diff --git c/x b/x\n"), null);
+});
+
 test("parseSpecLinks reads Supersedes/Fixes banners as paths or markdown links", () => {
   const body = "# T\n\n> **Supersedes:** [doc/specs/a.md](./a.md), doc/specs/b.md\n> **Fixes:** [doc/specs/c.md](./c.md)\n";
   assert.deepEqual(parseSpecLinks(body), { supersedes: ["doc/specs/a.md", "doc/specs/b.md"], fixes: ["doc/specs/c.md"] });

package/extensions/lib/telemetry-paths.ts

@@ -116,6 +116,60 @@ export function aggregateNumstat(numstat: string, files: Set<string>, buckets: [
   return out;
 }
 
+export interface PatchRow {
+  added: number;
+  removed: number;
+  path: string;
+}
+
+function patchBlockPath(headers: string[]): string | undefined {
+  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 undefined;
+  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 undefined;
+}
+
+function parsePatchBlock(block: string[]): PatchRow | undefined {
+  const hunk = block.findIndex((l) => l.startsWith("@@"));
+  const headers = hunk < 0 ? block : block.slice(0, hunk);
+  const path = patchBlockPath(headers);
+  if (path === undefined) return undefined;
+  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 };
+}
+
+// jj has no numstat: --stat truncates paths and -T exposes no line counts.
+// Headers end at the first @@; subsequent ---- and ++text lines count as content.
+export function parsePatchNumstat(patch: string): PatchRow[] | null {
+  if (!patch.trim()) return [];
+  const lines = patch.split("\n");
+  if (!lines.find((l) => l.trim())!.startsWith("diff --git ")) return null;
+  const blocks: string[][] = [];
+  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: PatchRow[] = [];
+  for (const block of blocks) {
+    const row = parsePatchBlock(block);
+    if (!row) return null;
+    rows.push(row);
+  }
+  return rows;
+}
+
 // ---- spec banners --------------------------------------------------------------
 
 const LINK_BANNER_RE = /^> \*\*(Supersedes|Fixes):\*\*\s*(.+)$/gm;

package/extensions/telemetry.test.ts

@@ -20,7 +20,7 @@
 
   type Handler = (event: any, ctx: any) => unknown;
 
-  function harness(o: { branch?: unknown[]; enabled?: boolean; gitFail?: (args: string[], cwd: string) => GitResult | undefined; jjWorkspace?: boolean; cwdSub?: string; sessionId?: string; model?: { provider: string; id: string }; thinkingLevel?: string; contextTokens?: number | null; telemetryWarning?: string; telemetryDir?: string } = {}) {
+  function harness(o: { branch?: unknown[]; enabled?: boolean; gitFail?: (args: string[], cwd: string) => GitResult | undefined; jjWorkspace?: boolean; jjFail?: (args: string[], cwd: string) => GitResult | undefined; cwdSub?: string; sessionId?: string; model?: { provider: string; id: string }; thinkingLevel?: string; contextTokens?: number | null; telemetryWarning?: string; telemetryDir?: string } = {}) {
     const root = mkdtempSync(join(tmpdir(), "telemetry-test-"));
     tempDirs.push(root);
     mkdirSync(join(root, "doc/specs"), { recursive: true });
@@ -29,6 +29,7 @@
     const handlers = new Map<string, Handler[]>();
     const gitCalls: string[][] = [];
     const gitCwds: string[] = [];
+    const jjCalls: string[][] = [];
     const readFileCalls: string[] = [];
     let clock = Date.parse("2026-09-17T10:00:00Z");
     const deps: Deps = {
@@ -53,7 +54,13 @@
       },
       settings: () => ({ telemetry: { enabled: o.enabled ?? true, dir: o.telemetryDir ?? ".pi/gauntlet/telemetry", buckets: DEFAULT_TELEMETRY_BUCKETS, warning: o.telemetryWarning }, errors: [], agentOverrides: { implementer: { model: "p/x" } }, versions: { pi: "0.85.1" } }),
       // A plain jj workspace: `jj root` answers the temp root while git rev-parse fails.
-      ...(o.jjWorkspace ? { jj: async () => ({ code: 0, stdout: root + "\n", stderr: "" }) } : {}),
+      jj: async (args, cwd) => {
+        jjCalls.push(args);
+        const forced = o.jjFail?.(args, cwd);
+        if (forced) return forced;
+        if (!o.jjWorkspace) return { code: 1, stdout: "", stderr: "jj stub: not a jj workspace" };
+        return shipJj(args, root);
+      },
     };
     let branch = o.branch ?? [];
     const ctx = {
@@ -79,11 +86,39 @@
       await emit("tool_call", { toolName: "write", toolCallId: "w", input: { path: rel, content: body } });
       return emit("tool_result", { toolName: "write", toolCallId: "w", input: { path: rel, content: body }, content: [], isError: false, details: undefined });
     };
-    return { root, handlers, emit, gitCalls, gitCwds, readFileCalls, commits, recordPath, readRecord, phaseResult, writeSpec, setBranch: (b: unknown[]) => (branch = b), ctx };
+    return { root, handlers, emit, gitCalls, gitCwds, jjCalls, readFileCalls, commits, recordPath, readRecord, phaseResult, writeSpec, setBranch: (b: unknown[]) => (branch = b), ctx };
   }
 
   const P = (over: Record<string, string> = {}) => Object.fromEntries(["brainstorm", "plan", "implement", "verify", "ship"].map((p) => [p, { status: over[p] ?? "pending" }]));
 
+  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/test/a.test.ts b/test/a.test.ts",
+    "new file mode 100644",
+    "index 0000000..3333333",
+    "--- /dev/null",
+    "+++ b/test/a.test.ts",
+    "@@ -0,0 +1,5 @@",
+    ...Array.from({ length: 5 }, (_, i) => `+t ${i}`),
+    "",
+  ].join("\n");
+
+  function shipJj(args: string[], root: string): GitResult {
+    if (args[0] === "root") return { code: 0, stdout: root + "\n", stderr: "" };
+    if (args.includes("--count")) return { code: 0, stdout: args.some((a) => a.includes('files(~glob:".pi/gauntlet/telemetry/**")')) ? "2\n" : "3\n", stderr: "" };
+    if (args.includes("log")) return { code: 0, stdout: "jjbase0001\n", stderr: "" };
+    if (args.includes("diff")) return { code: 0, stdout: JJ_PATCH, stderr: "" };
+    return { code: 1, stdout: "", stderr: `jj stub: unexpected call ${args.join(" ")}` };
+  }
+
   test("enabled: false registers handlers that no-op", async () => {
     const h = harness({ enabled: false });
     await h.emit("session_start", { type: "session_start", reason: "startup" });
@@ -726,6 +761,100 @@
     assert.ok(rec.events.some((e) => e.kind === "warning" && /base/.test((e as any).message)));
   });
 
+  async function boundInJjShip(jjFail?: (args: string[]) => GitResult | undefined) {
+    const h = harness({
+      jjWorkspace: true,
+      jjFail: jjFail ? (args) => jjFail(args) : undefined,
+      gitFail: (args) => (args[0] === "rev-parse" && args.includes("--path-format=absolute") ? { code: 128, stdout: "", stderr: "fatal: not a git repository" } : undefined),
+    });
+    await h.phaseResult("start", P({ brainstorm: "in_progress" }));
+    await h.writeSpec("doc/specs/a.md");
+    await h.phaseResult("complete", P({ brainstorm: "complete" }));
+    await h.phaseResult("start", P({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "in_progress" }));
+    await h.phaseResult("complete", P({ brainstorm: "complete", plan: "complete", implement: "complete", verify: "complete", ship: "complete" }));
+    return h;
+  }
+
+  const diffWarnings = (h: { readRecord: () => ReturnType<typeof parseRecord> }) =>
+    h.readRecord()!.events.filter((e) => e.kind === "warning").map((e: any) => e.message as string).filter((m) => m.startsWith("diff omitted"));
+
+  const isBaseLog = (args: string[]) => args.includes("log") && !args.includes("--count");
+
+  test("jj ship (AC 1): keep path derives modified_files and diff through jj with pinned output flags", async () => {
+    const h = await boundInJjShip();
+    const rec = h.readRecord();
+    assert.equal(rec.status, "shipped");
+    assert.equal(rec.derived.gates.ship_option, "keep");
+    assert.deepEqual(rec.derived.modified_files, ["src/a.ts", "test/a.test.ts"]);
+    assert.deepEqual(rec.derived.diff, { base: "jjbase0001", commits: 2, buckets: { code: { files: 1, insertions: 10, deletions: 2 }, test: { files: 1, insertions: 5, deletions: 0 } } });
+    assert.deepEqual(diffWarnings(h), []);
+    const diffSteps = h.jjCalls.filter((a) => a[0] !== "root");
+    assert.equal(diffSteps.length, 3);
+    assert.ok(diffSteps.every((a) => a.includes("--color=never")));
+    assert.deepEqual(diffSteps[1].slice(0, 4), ["--color=never", "--config", "diff.git.show-path-prefix=true", "diff"]);
+    assert.ok(diffSteps[0].some((a) => a.includes("fork_point(") && a.includes("~ root() & ::")));
+  });
+
+  test("jj ship (AC 2): empty mainline -> jj-named warning, both derived fields absent, record written", async () => {
+    const h = await boundInJjShip((args) => (isBaseLog(args) ? { code: 0, stdout: "", stderr: "" } : undefined));
+    const rec = h.readRecord();
+    assert.equal(rec.status, "shipped");
+    assert.equal(rec.derived.diff, undefined);
+    assert.equal(rec.derived.modified_files, undefined);
+    assert.deepEqual(diffWarnings(h), ["diff omitted: jj mainline unresolved (trunk() is root(); no main/master bookmark)"]);
+  });
+
+  test("jj ship: jj diff nonzero exit -> first stderr line in the warning", async () => {
+    const h = await boundInJjShip((args) => (args.includes("diff") ? { code: 1, stdout: "", stderr: "Error: Revision `jjbase0001` doesn't exist\nHint: try jj log\n" } : undefined));
+    assert.deepEqual(diffWarnings(h), ["diff omitted: jj diff failed: Error: Revision `jjbase0001` doesn't exist"]);
+    assert.equal(h.readRecord().derived.diff, undefined);
+  });
+
+  test("jj ship: ENOENT-shaped runner result (empty stderr) -> 'unknown error'", async () => {
+    const h = await boundInJjShip((args) => (isBaseLog(args) ? { code: 127, stdout: "", stderr: "" } : undefined));
+    assert.deepEqual(diffWarnings(h), ["diff omitted: jj log failed: unknown error"]);
+    assert.equal(h.readRecord().status, "shipped");
+  });
+
+  test("jj ship: unparseable patch -> warning, neither field set", async () => {
+    const h = await boundInJjShip((args) => (args.includes("diff") ? { code: 0, stdout: "not a patch\n", stderr: "" } : undefined));
+    assert.deepEqual(diffWarnings(h), ["diff omitted: jj diff unparseable"]);
+    const rec = h.readRecord();
+    assert.equal(rec.derived.diff, undefined);
+    assert.equal(rec.derived.modified_files, undefined);
+  });
+
+  test("jj ship: malformed patch header -> warning, neither field set, record shipped", async () => {
+    const h = await boundInJjShip((args) => (args.includes("diff") ? { code: 0, stdout: "diff --git c/x b/x\n", stderr: "" } : undefined));
+    assert.deepEqual(diffWarnings(h), ["diff omitted: jj diff unparseable"]);
+    const rec = h.readRecord();
+    assert.equal(rec.status, "shipped");
+    assert.equal(rec.derived.diff, undefined);
+    assert.equal(rec.derived.modified_files, undefined);
+  });
+
+  test("jj ship: --count failure -> jj log warning, no derived diff", async () => {
+    const h = await boundInJjShip((args) => (args.includes("--count") ? { code: 1, stdout: "", stderr: "Error: invalid revset\nHint: check the mainline\n" } : undefined));
+    assert.deepEqual(diffWarnings(h), ["diff omitted: jj log failed: Error: invalid revset"]);
+    const rec = h.readRecord();
+    assert.equal(rec.status, "shipped");
+    assert.equal(rec.derived.diff, undefined);
+    assert.equal(rec.derived.modified_files, undefined);
+  });
+
+  test("jj ship: unparseable --count -> warning with the raw output", async () => {
+    const h = await boundInJjShip((args) => (args.includes("--count") ? { code: 0, stdout: "abc\n", stderr: "" } : undefined));
+    assert.deepEqual(diffWarnings(h), ["diff omitted: jj log --count unparseable: abc"]);
+    assert.equal(h.readRecord().derived.diff, undefined);
+  });
+
+  test("git ship never calls jj", async () => {
+    const h = await boundInShip();
+    await h.bash("s1", "git push");
+    assert.deepEqual(h.readRecord().derived.modified_files, ["README.md", "extensions/telemetry.test.ts", "extensions/telemetry.ts"]);
+    assert.deepEqual(h.jjCalls, []);
+  });
+
   test("guard: write to a shipped spec during brainstorm is blocked before any state change; edit passes; other phases pass", async () => {
     const h = await boundInShip();
     await h.bash("s1", "git push");

package/extensions/telemetry.ts

@@ -18,7 +18,7 @@
   import { checkoutOf } from "./lib/checkout.ts";
   import { CONTEXT_DRAFT_MARKER } from "./lib/phase-tracker-helpers.ts";
   import { sha256 } from "./lib/plan-check.ts";
-  import { SUPERSEDED_BY_RE, aggregateNumstat, isPlanPath, isSpecPath, isSupersededByBanner, matchDiscardStatement, matchShipStatement, matchTestStatement, parseSpecLinks, planSpecHeader, recordPathFor, repoRelativeToolPath, toPosix, truncateCommand } from "./lib/telemetry-paths.ts";
+  import { SUPERSEDED_BY_RE, aggregateNumstat, isPlanPath, isSpecPath, isSupersededByBanner, matchDiscardStatement, matchShipStatement, matchTestStatement, parsePatchNumstat, parseSpecLinks, planSpecHeader, recordPathFor, repoRelativeToolPath, toPosix, truncateCommand } from "./lib/telemetry-paths.ts";
   import { COUNTED_USER_PHASES, REVIEWER_AGENTS, countFindings, countOpenGaps, hasReopen, insertedText, planTotals, textOf, usageToTokens } from "./lib/telemetry-collect.ts";
   import { addTokens, capEvents, compact, currentPhase, derive, diffPhases, emptyAccumulators, emptyPhases, foldAccumulators, implementAutoCompletes, liveShipEvent, newRecord, parseRecord, serializeRecord, type Accumulators, type BaseEvent, type PhaseAcc, type PhaseKey, type PhaseMap, type TelemetryEvent, type TelemetryRecord, type Tokens } from "./lib/telemetry-record.ts";
   import { BASE_REFS, guardReason, modifiedFilesFrom } from "./lib/telemetry-ship.ts";
@@ -48,7 +48,7 @@
   export interface Deps {
     fs: FsPort;
     git: (args: string[], cwd: string) => Promise<GitResult>;
-    // Optional jj override for tests; production resolves plain jj workspaces via jjSync.
+    // jj runner; production uses realJj for both checkout detection and the ship-time diff.
     jj?: (args: string[], cwd: string) => GitResult | Promise<GitResult>;
     now: () => string;
     settings: (cwd: string) => SettingsSnapshot;
@@ -78,6 +78,16 @@
       });
     });
 
+  // jj diff --git returns full patches; execFile's default buffer is too small.
+  // On ENOENT stderr is empty, so preserve the error message.
+  export const realJj = (args: string[], cwd: string): Promise<GitResult> =>
+    new Promise((res) => {
+      execFile("jj", args, { cwd, timeout: 10_000, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }, (err, stdout, stderr) => {
+        const code = err ? (typeof (err as { code?: unknown }).code === "number" ? ((err as { code: number }).code) : 1) : 0;
+        res({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? "").trim() || String(err?.message ?? "") });
+      });
+    });
+
   const isoNow = (): string => new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 
   const readPkgVersion = (p: string): string | undefined => {
@@ -115,7 +125,7 @@
     return { telemetry, errors, agentOverrides, versions: realVersions(), testCommands };
   }
 
-  export const realDeps: Deps = { fs: realFs, git: realGit, now: isoNow, settings: realSettings };
+  export const realDeps: Deps = { fs: realFs, git: realGit, jj: realJj, now: isoNow, settings: realSettings };
 
   // ---- replay ------------------------------------------------------------------------
 
@@ -635,6 +645,38 @@
     let pendingShip: { id: string; option: "squash" | "pr" | "discard" } | undefined;
 
     const computeDiff = async (snap: SettingsSnapshot) => {
+      if (checkoutVia === "jj") await computeJjDiff(snap);
+      else await computeGitDiff(snap);
+    };
+
+    const JJ_MAINLINE = "coalesce(trunk() ~ root(), present(main), present(master))";
+
+    const computeJjDiff = async (snap: SettingsSnapshot) => {
+      if (!record || !toplevel) return;
+      const jj = deps.jj ?? realJj;
+      const failed = (sub: string, r: GitResult) => warn(`diff omitted: jj ${sub} failed: ${r.stderr.trim().split("\n")[0] || "unknown error"}`);
+      // Without the ::M guard an empty mainline resolves to @ and counts the full history.
+      const baseR = await jj(["--color=never", "log", "-r", `fork_point(${JJ_MAINLINE} | @) ~ root() & ::${JJ_MAINLINE}`, "--no-graph", "-T", 'commit_id ++ "\\n"'], toplevel);
+      if (baseR.code !== 0) return failed("log", baseR);
+      const base = baseR.stdout.trim().split("\n")[0].trim();
+      if (!base) return warn("diff omitted: jj mainline unresolved (trunk() is root(); no main/master bookmark)");
+      const patch = await jj(["--color=never", "--config", "diff.git.show-path-prefix=true", "diff", "--from", base, "--to", "@", "--git"], toplevel);
+      if (patch.code !== 0) return failed("diff", patch);
+      const rows = parsePatchNumstat(patch.stdout);
+      if (!rows) return warn("diff omitted: jj diff unparseable");
+      const dir = currentDir.replace(/\/+$/, "");
+      // Exclude record-only @ and other telemetry-only revisions from the count.
+      const count = await jj(["--color=never", "log", "-r", `(${base}::@ ~ ${base}) & files(~glob:"${dir}/**")`, "--count"], toplevel);
+      if (count.code !== 0) return failed("log", count);
+      const n = count.stdout.trim();
+      if (!/^\d+$/.test(n)) return warn(`diff omitted: jj log --count unparseable: ${n}`);
+      const files = modifiedFilesFrom(rows.map((r) => r.path).join("\n"), record.spec, currentDir);
+      const numstat = rows.map((r) => `${r.added}\t${r.removed}\t${r.path}`).join("\n");
+      record.derived.modified_files = files;
+      record.derived.diff = { base, commits: Number(n), buckets: aggregateNumstat(numstat, new Set(files), snap.telemetry.buckets) };
+    };
+
+    const computeGitDiff = async (snap: SettingsSnapshot) => {
       if (!record || !toplevel) return;
       let baseRef: string | undefined;
       for (const ref of BASE_REFS) {

package/package.json

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

package/skills/gauntlet-resume/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: gauntlet-resume
-description: Use when a human wants to continue an interrupted gauntlet flow in a fresh session - from a gauntlet-handoff brief (file, pasted, or picked from the default handoff directory) or from a bare worktree that already holds a spec. Human-only; the sole resume entry point. Restores phase/plan tracker state through the legal arming sequence, never creates a worktree, never infers approval.
+description: Use when a human wants to continue an interrupted gauntlet flow in a fresh session - from a gauntlet-handoff brief (file, pasted, or picked from the default handoff directory), from a bare worktree that already holds a spec, or from a spec tracked on main (creates or reuses its worktree via `/skill:using-git-worktrees`). Human-only; the sole resume entry point. Restores phase/plan tracker state through the legal arming sequence, never infers approval.
 disable-model-invocation: true
-argument-hint: "[<brief-file>] [<worktree-name-or-path>]"
+argument-hint: "[<brief-file> | <spec>.md | <worktree-name-or-path>]"
 ---
 
 > **Related skills:** Continues into `/skill:writing-plans`, `/skill:subagent-driven-development`, or `/skill:verification-before-completion` depending on the restored stage. `/skill:brainstorming` is where new ideas go - a free-form prompt is not a resume input.
@@ -11,48 +11,61 @@ argument-hint: "[<brief-file>] [<worktree-name-or-path>]"
 
 ## Overview
 
-Re-enter an interrupted gauntlet flow in a fresh session. Two inputs: a handoff brief
-produced by `/skill:gauntlet-handoff` (grammar in `reference/brief-contract.md`), or a bare
+Re-enter an interrupted gauntlet flow in a fresh session. Three inputs: a handoff brief
+produced by `/skill:gauntlet-handoff` (grammar in `reference/brief-contract.md`), a bare
 worktree whose spec/plan artifacts are reconstructed into tracker state
-(`reference/reconstruction.md`). Every check runs before any tracker mutation; every
-stop names the offending path, field, or line.
+(`reference/reconstruction.md`), a spec seed (`reference/seed.md`). Every check runs
+before any tracker mutation; every stop names the offending path, field, or line.
 
 **Announce at start:** "I'm using the gauntlet-resume skill to continue an interrupted flow."
 
 ## Boundaries
 
 - Reads: anything.
-- Writes: `phase_tracker` / `plan_tracker` state, only after every entry check passes
-  and every human question is answered. Nothing on disk.
-- Never: `git worktree add`; infer approval from artifact presence; restore gate history,
-  closure-review evidence, or fix rounds; start a later phase directly (that does not arm
-  the flow).
+- Writes: `phase_tracker` / `plan_tracker` state after every check passes and every
+  human question is answered; on the seed route, what `/skill:using-git-worktrees`
+  writes. Never a spec copy, rename, or marker commit.
+- Never: `git worktree add` directly; worktree creation by resume itself only on
+  the seed route, only through `/skill:using-git-worktrees`; infer approval from
+  artifact presence; restore
+  gate history, closure-review evidence, or fix rounds; start a later phase directly
+  (that does not arm the flow).
 
 ## Arguments
 
-`/skill:gauntlet-resume [<brief>] [<worktree>]` - zero to two positional tokens, plus
-optional pasted text after the command line.
+`/skill:gauntlet-resume [<token>] [<worktree>]` - zero to two positional tokens, plus
+optional pasted text after the command line. Count tokens first; then first match wins.
+Spec dirs resolve per `reference/reconstruction.md` "Candidates" (`flowGuards.specDirs`
+precedence).
 
-| Form | Meaning |
+| Input | Route |
 |---|---|
-| (no tokens, no pasted text) | discovery: `<tmpdir>` via `node -p "require('os').tmpdir()"`; candidates are the regular files directly under `<tmpdir>/pi-handoff/` ending `.md` (non-recursive) whose line 1 starts `# Handoff:`; sorted by mtime, newest first; displayed one per line as `<n>. <title line> - <worktree: field value> - <mtime ISO-8601>` with `worktree: unavailable` when the field is absent; the human picks `<n>` (a single candidate is still confirmed); none -> STOP "no handoff briefs found under <tmpdir>/pi-handoff" |
-| `<brief-file>` | a single token that is an absolute path, contains a path separator, or ends in `.md`; used as given, never widened to a scan; missing, unreadable, or line 1 not `# Handoff:` -> STOP with that path |
-| pasted text whose first line starts `# Handoff:` | inline brief (equivalent to a file) |
-| `<worktree>` alone | any other single token (no path separator, not ending `.md`): bare name resolved as `<primary>/.worktrees/<name>`; must already be a git worktree. An absolute worktree path is given only in the two-token `<brief> <worktree>` form |
-| `<brief> <worktree>` | brief plus an explicit worktree override (required when the brief's worktree field is `no`/`unavailable`/not a git repo; must equal the brief's worktree after `realpath` otherwise) |
-| anything else | not a resume input - stop with "this is a new idea - run /skill:brainstorming" |
-
-`<primary>` is the checkout owning `.worktrees/`: `dirname "$(git rev-parse --path-format=absolute --git-common-dir)"` run in the session cwd - absolute from any primary subdirectory and from inside a linked worktree (`--show-toplevel` would return the linked worktree there). A bare `<name>` resolves as `<primary>/.worktrees/<name>`. A pasted brief that needs an override uses the file form. This skill never runs `git worktree add`.
-
-Classification runs before anything else: a token that is an absolute path, contains a
-path separator, or ends in `.md` is a `<brief-file>` - never a worktree name, never
-widened to a scan. Any other single token is tried as `<worktree>`. A picked or given
-brief then runs entry checks 1-5 unchanged, so a stale or foreign-repo brief stops there.
-Free-form text still lands on the "anything else" row.
+| no tokens, no pasted text | discovery: `<tmpdir>` via `node -p "require('os').tmpdir()"`; candidates are the regular files directly under `<tmpdir>/pi-handoff/` ending `.md` (non-recursive) whose line 1 starts `# Handoff:`; sorted by mtime, newest first; displayed one per line as `<n>. <title line> - <worktree: field value> - <mtime ISO-8601>` with `worktree: unavailable` when the field is absent; the human picks `<n>` (a single candidate is still confirmed); none -> STOP "no handoff briefs found under <tmpdir>/pi-handoff" |
+| pasted text, line 1 starts `# Handoff:` | brief |
+| two tokens, first an existing file with line 1 `# Handoff:` | brief with worktree override: required when the brief's worktree field is `no`/`unavailable`/not a git repo; must equal the brief's worktree after `realpath` otherwise |
+| two tokens, first a spec seed | stop: `a spec seed takes no worktree: <second token>` |
+| one token, existing regular file, line 1 starts `# Handoff:` | brief |
+| one token, existing regular file ending `.md`, `realpath` under `<primary>/<specDir>` | spec seed - `reference/seed.md` |
+| one token, existing regular file, anything else | stop: `not a handoff brief and not under <specDirs>: <path>` |
+| one token, existing directory that is a git worktree root (`git -C <dir> rev-parse --show-toplevel` equals its `realpath`) other than `<primary>` | worktree |
+| one token, missing path (ends `.md` or contains a separator) | stop: `not found: <path>` |
+| one token, bare name | worktree at `<primary>/.worktrees/<name>`; missing or not a git worktree -> entry check 2 stop |
+| anything else | stop: "this is a new idea - run /skill:brainstorming" |
+
+A relative token resolves against the session cwd; a bare `name.md` absent there is
+tried at `<primary>/<specDir>/name.md` per resolved spec dir in order, first hit wins.
+`<primary>` is the checkout owning `.worktrees/`:
+`dirname "$(git rev-parse --path-format=absolute --git-common-dir)"` run in the session
+cwd - absolute from any primary subdirectory and from inside a linked worktree
+(`--show-toplevel` would return the linked worktree there). A pasted brief that needs
+an override uses the file form. A brief then runs entry checks 1-5, so a stale or
+foreign-repo brief stops there.
 
 ## Entry checks
 
-In order. All before any tracker mutation; entry check 1 is read-only.
+In order. All before any tracker mutation; entry check 1 is read-only. A spec
+seed runs check 1 here, then `reference/seed.md`, which runs check 3 itself;
+checks 2, 4, 5 do not apply.
 
 1. **Idle session.** `phase_tracker({ action: "status" })`. Any phase not pending ->
    stop: "session already carries flow state - reset is your call".
@@ -91,6 +104,7 @@ In order. All before any tracker mutation; entry check 1 is read-only.
 | brief without process state, `worktree: no` | invoke `/skill:brainstorming` with `## Intent` as the idea, in the current directory; resume creates no worktree - brainstorming's own Worktree First applies (a plain handoff is a new flow) |
 | brief without process state, worktree present | `reference/reconstruction.md`, with `## Intent` and `## Decisions` carried into every confirmation prompt |
 | bare worktree | `reference/reconstruction.md`; prompts state that no brief context is available (never invent Intent/Decisions) |
+| spec seed | `reference/seed.md` |
 
 **Hotfix route.** `skills/chase-bug/hotfix.md` consumes only a hotfix record at
 `$TMPDIR/hotfix-<slug>.md`. If `## Decisions` or `## Intent` names an existing record
@@ -113,11 +127,11 @@ owning skill **without** its reset-bearing entry:
 
 ## Red flags — STOP
 
-- Any `phase_tracker` or `plan_tracker` mutation before entry checks 1-5 pass and every
-  human question is answered.
+- Any `phase_tracker` or `plan_tracker` mutation before the route's entry checks pass and
+  every human question is answered.
 - `start <phase>` for anything other than brainstorm as the first arming call.
 - `complete` on a prior phase during restore (priors are `skip`ped with a `resume:` reason).
-- Running `git worktree add`, or `cd`-ing to "fix" a cwd mismatch.
+- Running `git worktree add` directly, or `cd`-ing to "fix" a cwd mismatch.
 - Accepting a free-form prompt as a brief.
 
 ## Project overrides

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

@@ -130,8 +130,8 @@ Per-stage call table, keyed by the brief's active phase (`→`). `R` is the reas
 
 `planPath`: the brief carries none. Resolve as reconstruction does
 (`reconstruction.md`, "Candidates", including its `flowGuards.specDirs` resolution): the
-single spec/plan pair added after base in the worktree, paired by identical basename
-(`<specDir>/<name>.md` <-> `<sibling plans dir>/<name>.md`, the writing-plans contract);
+single plan added after base, paired with `<specDir>/<same basename>` whether that
+spec was added after base or tracked from base (`reconstruction.md` "Candidates");
 resolve the selected plan to an absolute path under the worktree before `plan_check`.
 Zero pairs -> stop; more than one -> human picks.
 

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

@@ -23,6 +23,8 @@ for a base ref before reading any artifact.
 
 ## Candidates
 
+A pinned spec (seed route, `seed.md`) skips this section.
+
 Spec/plan directories: `piGauntlet.flowGuards.specDirs` plus each one's sibling `plans` directory. Resolve with the precedence `doc/configuration.md` documents for every `piGauntlet.*` key: the session cwd's `.pi/settings.json` if it defines `flowGuards`,
 else the active pi profile's `settings.json`, else the default `["doc/specs"]` (sibling
 `doc/plans`). An empty array is the default. `<dirs>` below is that resolved list,
@@ -36,15 +38,17 @@ git -C <worktree> ls-files --others --exclude-standard -- <dirs>
 Candidates are files under those directories added after base, plus untracked files
 there. Paths returned by these commands are relative to `<worktree>`; resolve them to
 absolute paths under `<worktree>` before reading artifacts, showing paths in prompts,
-or calling `plan_check`. A spec and a plan pair by identical basename
-(`<specDir>/<name>.md` <-> `<sibling plans dir>/<name>.md`). The plan commit is the first
+or calling `plan_check`. A candidate plan pairs with
+`<worktree>/<specDir>/<same basename>` whether that spec is a candidate or tracked
+from base; count a base-tracked spec so paired as a spec in the route table below.
+The plan commit is the first
 post-base commit that added the plan file: `git -C <worktree> log --diff-filter=A
 --format=%H --reverse <base>..HEAD -- <plan>`, first line. An uncommitted plan has no
 plan commit; treat every task as `pending`.
 
 | Candidates | Route |
 |---|---|
-| no spec | stop; offer `/skill:brainstorming`; no tracker call |
+| no spec | stop; offer `/skill:brainstorming` or pass the spec: `/skill:gauntlet-resume <specDir>/<name>.md`; no tracker call |
 | more than one spec | the human picks one, then continue below with that spec |
 | one spec, no plan | "Spec without plan" |
 | one spec with plan | "Spec with plan" |
@@ -71,6 +75,9 @@ Show, and ask the human to confirm or edit both in one reply:
    Uncommitted plan (no
    plan commit): skip this query entirely - there is no range to search - and show
    "plan uncommitted; no task evidence" in its place; every task is proposed `pending`.
+   Plan commit lookup empty while `git -C <worktree> cat-file -e <base>:<plan>` exits 0
+   (plan at or before base): skip the log query, show
+   `plan predates base; no post-base task evidence`, every task proposed `pending`.
 2. Uncommitted files: `git -C <worktree> status --porcelain`.
 3. Proposed task statuses: `complete` iff at least one matching commit, else `pending`.
 4. Proposed stage: `implement` if any task is `pending`, else `verify`.

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

@@ -0,0 +1,47 @@
+# Spec seed (gauntlet-resume supplementary)
+
+Consumed only by `SKILL.md` in this directory, for a one-token `.md` argument classified
+as a spec seed. `<seed>` is its `realpath`; `<rel>` is `<seed>` relative to `<primary>`.
+Entry check 1 (idle session) runs first. Then, in order; every stop names the path.
+
+1. **Primary session.** `git rev-parse --git-dir --git-common-dir` in the session cwd
+   prints two paths; their `realpath`s must agree. Otherwise stop:
+   `seed from the primary checkout`.
+2. **Tracked.** `git -C <primary> ls-files --error-unmatch <rel>` exits 0; otherwise
+   stop: `not tracked: <seed> - commit it first`. Line 1 of `<seed>` equal to
+   `# CONTEXT DRAFT - NOT A SPEC - fully replaced at spec-writing` -> stop:
+   `context draft, not a spec: <seed> - finish brainstorming`.
+3. **Not shipped.** Read `<primary>/<telemetry.dir>/<rel with .md -> .yaml>`
+   (`piGauntlet.telemetry.dir`, default `.pi/gauntlet/telemetry`). A `shipped_at:` or
+   `abandoned_at:` line carrying a value -> stop:
+   `spec already shipped at <ts> - write a superseding spec`. No record, or
+   `in_progress`: continue; the extension folds this run into the record on
+   `plan_check` pass.
+4. **Name.** `<name>` = basename of `<rel>` minus `.md`, minus a leading `YYYY-MM-DD-`:
+   `2026-09-17-gh-31-gauntlet-resume.md` -> `gh-31-gauntlet-resume`. Same shape as
+   brainstorming's Filename Convention slug; wrappers receive it as `<name>`.
+5. **Reuse or create.** `git -C <primary> worktree list --porcelain`. A block whose
+   `branch` line is `refs/heads/<name>` or ends in `/<name>` -> `<full-path>` is that
+   block's `worktree` line; skip creation (layout-agnostic: wrapper sibling dirs,
+   wrapper branch prefixes such as `<user>/<name>`, and `.worktrees/` alike); more than
+   one match -> the human picks. No block -> invoke `/skill:using-git-worktrees` with branch `<name>` and carry its
+   `Worktree ready at <full-path>`; its Step 1a applies project `## using-git-worktrees`
+   overrides, its Step 3 runs the clean-base check and dirty ask. Wrapper arguments
+   beyond `<name>` are that skill's ask, never inferred here. Any stop it raises is this
+   route's stop, verbatim. Never invent a second name.
+6. **Same repository.** Entry check 3 against `<full-path>`.
+7. **Pinned copy.** `<full-path>/<rel>` exists, is readable, and its line 1 is not the
+   context-draft marker; otherwise stop naming that path. Never copy `<seed>` in.
+8. **Continue** in `reconstruction.md` with the spec pinned at `<full-path>/<rel>`,
+   skipping Candidates: `<full-path>/<sibling plans dir>/<basename of rel>` exists ->
+   "Spec with plan"; otherwise "Spec without plan". Prompts say "no brief context
+   available".
+
+The seed route writes no spec copy, rename, or marker commit: the spec stays where main
+tracks it, amends ride the squash as ordinary diffs, and `finishing-a-development-branch`
+strips only the plan. `gauntlet-telemetry-salvage` prints `no spec on branch` for an
+unamended seed throughout the flow (it selects specs from `git diff --name-only
+<base>...HEAD`, which never lists a file tracked at base), so the extension's live ship
+stamp is the only writer of `shipped_at`; the record still binds on `plan_check` pass.
+Before a plan exists beside the spec, re-pass the seed to resume; after, plain `<worktree>` resume and
+`gauntlet-handoff` -> `gauntlet-resume <brief>` restore the flow.