pi-gauntlet 4.6.2 → 4.7.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## v4.7.0 - 2026-08-07
+
+Sanction the spec-in-hand resume gesture and guard the implement phase (#6).
+Sessions that start with an approved spec from a handoff doc previously ran
+fully unarmed - the observed incident implemented an entire plan inline in the
+main loop with every enforcement surface dormant.
+
+- `writing-plans` gains a "Resuming with a spec in hand" subsection: a
+  state-detected handoff entry (branch on `phase_tracker status`) that verifies
+  the spec, confirms approval, sets up the worktree, and arms `gauntletEntered`
+  via the existing `start brainstorm -> skip brainstorm -> start plan`
+  sequence, plus guidance for writing handoff docs. Prose only - no new skill,
+  no new tracker action.
+- Fourth flow guard in `phase-tracker`: a warn-once advisory on parent
+  `write`/`edit` in the armed implement window (`implement` in progress, or
+  `plan` complete with `implement` still pending), exempting
+  `flowGuards.specDirs` plus each spec dir's sibling `plans` dir. Advisory,
+  never blocks (merge-conflict resolution between parallel waves proceeds past
+  it); subagent children (`PI_SUBAGENT_DEPTH` >= 1) never trip it; disabled
+  with the other guards via `flowGuards.enforce: false`. No new settings key.
+- Regression coverage: resumed-session replay arming, recovery edge, and
+  closure gate; test stub `SettingsManager` now reads the repo settings layer.
+- The 2026-07-19 sole-entry-point spec carries a supersession banner scoped to
+  its sole-arming claim.
+
 ## v4.6.2 - 2026-08-07
 
 Trim the always-shipped tool descriptions of the gauntlet-internal tools to

package/README.md

@@ -68,7 +68,7 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 - **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.
 - **3 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 commit/push without a passing test run since your last edit. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
-pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs. 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.
+pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs, and warns once if the main loop writes code during implement (subagents own implement-phase edits). A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
 
 ## Key concepts
 

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

@@ -6,6 +6,8 @@ import {
   closureGateBlocks,
   closureModelGuardApplies,
   flowGuardApplies,
+  implementWriteGuardApplies,
+  implementExemptDirs,
   nextGauntletEntered,
   phaseLabel,
   parseGitCommit,
@@ -210,3 +212,29 @@ test("closureModelGuardApplies: requires both an entered flow and closure enforc
   assert.equal(closureModelGuardApplies(true, false), false); // enforce off
   assert.equal(closureModelGuardApplies(false, false), false);
 });
+
+test("implementWriteGuardApplies: window is implement in_progress or plan-complete/implement-pending", () => {
+  assert.equal(implementWriteGuardApplies("complete", "in_progress", true, false), true);
+  assert.equal(implementWriteGuardApplies("complete", "pending", true, false), true); // armed post-plan gap (incident window)
+  assert.equal(implementWriteGuardApplies("skipped", "in_progress", true, false), true); // window is implement itself
+  assert.equal(implementWriteGuardApplies("in_progress", "pending", true, false), false); // still planning
+  assert.equal(implementWriteGuardApplies("skipped", "pending", true, false), false); // plan skipped: accepted residual gap (spec Edge cases)
+  assert.equal(implementWriteGuardApplies("complete", "complete", true, false), false); // implement done
+});
+
+test("implementWriteGuardApplies: requires an armed flow and a parent process", () => {
+  assert.equal(implementWriteGuardApplies("complete", "in_progress", false, false), false); // unarmed
+  assert.equal(implementWriteGuardApplies("complete", "in_progress", true, true), false); // subagent child
+});
+
+test("implementExemptDirs: adds each spec dir's sibling plans dir, deduped", () => {
+  assert.deepEqual(implementExemptDirs(["doc/specs"]), ["doc/specs", "doc/plans"]);
+  assert.deepEqual(implementExemptDirs(["specs"]), ["specs", "plans"]);
+  assert.deepEqual(implementExemptDirs(["doc/specs/"]), ["doc/specs", "doc/plans"]);
+  assert.deepEqual(implementExemptDirs(["a/plans"]), ["a/plans"]); // already a plans dir: Set dedups
+  assert.deepEqual(implementExemptDirs(["doc/specs", "svc/doc/specs"]), ["doc/specs", "doc/plans", "svc/doc/specs", "svc/doc/plans"]);
+});
+
+test("nextGauntletEntered: skip preserves the marker (resume gesture)", () => {
+  assert.equal(nextGauntletEntered(true, "skip", "skipped"), true);
+});

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

@@ -145,6 +145,39 @@ export function flowGuardApplies(phaseActive: boolean, gauntletEntered: boolean)
   return phaseActive && gauntletEntered;
 }
 
+// Implement-write guard window (spec 2026-08-07-resume-spec-in-hand). Fires while
+// implement runs, or in the armed post-plan gap (plan complete, implement not yet
+// started) - the incident window where neither recoverableEdge (needs an idle
+// session) nor an implement-scoped check could fire. Marker-first like every other
+// surface; the enforce + path + fired conjuncts stay at the call site (settings and
+// ledger live there). isSubagentChild: implementer forks inherit extensions and
+// replay the parent's phase state, so without it every implementer's first write
+// would trip a spurious advisory.
+export function implementWriteGuardApplies(
+  planStatus: string,
+  implementStatus: string,
+  gauntletEntered: boolean,
+  isSubagentChild: boolean,
+): boolean {
+  const windowOpen =
+    implementStatus === "in_progress" || (planStatus === "complete" && implementStatus === "pending");
+  return windowOpen && gauntletEntered && !isSubagentChild;
+}
+
+// Exempt dirs for the implement-write guard: the configured spec dirs plus each
+// one's sibling `plans` dir (doc/specs -> doc/plans; plans live there per
+// writing-plans) - a routine parent plan-doc update must not burn the one-shot warning.
+export function implementExemptDirs(specDirs: string[]): string[] {
+  const dirs = new Set<string>();
+  for (const dir of specDirs) {
+    const parts = dir.split("/").filter((c) => c.length > 0);
+    if (parts.length === 0) continue;
+    dirs.add(parts.join("/"));
+    dirs.add([...parts.slice(0, -1), "plans"].join("/"));
+  }
+  return [...dirs];
+}
+
 export const markerBlockReason = (file: string): string =>
   `Blocked: ${file} still begins with the context-draft marker - the spec-writing ` +
   `overwrite has not happened. Overwrite the draft with the real spec (write tool, ` +

package/extensions/phase-tracker.test.ts

@@ -1,7 +1,25 @@
 import assert from "node:assert/strict";
-import { test } from "node:test";
+import { after, test } from "node:test";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import registerPhaseTracker from "./phase-tracker.ts";
 
+const tempDirs: string[] = [];
+after(() => {
+  for (const dir of tempDirs) rmSync(dir, { recursive: true, force: true });
+});
+
+const tempCwd = (settings?: unknown) => {
+  const dir = mkdtempSync(join(tmpdir(), "phase-tracker-test-"));
+  tempDirs.push(dir);
+  if (settings !== undefined) {
+    mkdirSync(join(dir, ".pi"), { recursive: true });
+    writeFileSync(join(dir, ".pi", "settings.json"), JSON.stringify(settings));
+  }
+  return dir;
+};
+
 const PHASES = ["brainstorm", "plan", "implement", "verify", "ship"] as const;
 type Phase = (typeof PHASES)[number];
 type Status = "pending" | "in_progress" | "complete" | "skipped";
@@ -25,13 +43,20 @@ const enteredBranch = (state: Record<Phase, { status: Status }>, extra: unknown[
   ...extra,
 ];
 
-function harness(options: { branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean } = {}) {
+const resumedBranch = (rest: Partial<Record<Phase, Status>>) => [
+  phaseResult("start", phases({ brainstorm: "in_progress" })),
+  phaseResult("skip", phases({ brainstorm: "skipped" })),
+  phaseResult("start", phases({ brainstorm: "skipped", plan: "in_progress" })),
+  phaseResult("complete", phases({ brainstorm: "skipped", ...rest })),
+];
+
+function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean } = {}) {
   const handlers = new Map<string, ((event: unknown, ctx: unknown) => unknown)[]>();
   const tools: { name: string; execute: (...args: any[]) => unknown }[] = [];
   const sent: { message: any; options: any }[] = [];
   let idle = options.idle ?? true;
   const ctx = {
-    cwd: process.cwd(),
+    cwd: options.cwd ?? tempCwd(),
     hasUI: false,
     isIdle: () => idle,
     sessionManager: { getBranch: () => options.branch ?? [] },
@@ -55,7 +80,12 @@ function harness(options: { branch?: unknown[]; idle?: boolean; beforeSettled?:
   const emit = async (event: string) => {
     for (const handler of handlers.get(event) ?? []) await handler({ type: event }, ctx);
   };
-  return { emit, sent, tools, setIdle: (next: boolean) => (idle = next) };
+  const emitEvent = async (name: string, event: unknown) => {
+    const results: unknown[] = [];
+    for (const handler of handlers.get(name) ?? []) results.push(await handler(event, ctx));
+    return results;
+  };
+  return { emit, emitEvent, sent, tools, ctx, setIdle: (next: boolean) => (idle = next) };
 }
 
 const settle = async (h: ReturnType<typeof harness>) => {
@@ -157,3 +187,103 @@ test("a throwing send spends the in-memory edge", async () => {
   await h.emit("agent_settled");
   assert.equal(h.sent.length, 1);
 });
+
+const writeCall = (id: string, path: string) => ({ toolName: "write", toolCallId: id, input: { path } });
+const writeResult = (id: string) => ({ toolName: "write", toolCallId: id, content: [{ type: "text", text: "ok" }] });
+
+test("implement-write guard: warns once on parent write outside exempt dirs, exempt paths silent", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH; // isolate from an ambient subagent depth in the test-runner's own process
+  try {
+    const h = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete", implement: "in_progress" }) });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", writeCall("t1", "doc/specs/x.md"));
+    assert.equal((await h.emitEvent("tool_result", writeResult("t1")))[0], undefined); // spec dir exempt
+    await h.emitEvent("tool_call", writeCall("t2", "doc/plans/x.md"));
+    assert.equal((await h.emitEvent("tool_result", writeResult("t2")))[0], undefined); // plans dir exempt
+    await h.emitEvent("tool_call", writeCall("t3", "src/x.ts"));
+    const warned = (await h.emitEvent("tool_result", writeResult("t3")))[0] as { content: { text: string }[] };
+    assert.match(warned.content[0].text, /implement/);
+    assert.match(warned.content[0].text, /subagent-driven-development/);
+    assert.match(warned.content[0].text, /merge-conflict/);
+    await h.emitEvent("tool_call", writeCall("t4", "src/y.ts"));
+    assert.equal((await h.emitEvent("tool_result", writeResult("t4")))[0], undefined); // warn-once
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("implement-write guard: fires in the armed post-plan gap (plan complete, implement pending)", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete" }) });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+    const warned = (await h.emitEvent("tool_result", writeResult("t1")))[0] as { content: { text: string }[] };
+    assert.match(warned.content[0].text, /implement/);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("implement-write guard: silent when unarmed, when enforce is false, and in subagent children", async () => {
+  const cold = harness({ cwd: tempCwd(), branch: [phaseResult("complete", phases({ plan: "complete", implement: "in_progress" }))] });
+  await cold.emit("session_start");
+  await cold.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+  assert.equal((await cold.emitEvent("tool_result", writeResult("t1")))[0], undefined);
+
+  const off = harness({
+    cwd: tempCwd({ piGauntlet: { flowGuards: { enforce: false } } }),
+    branch: resumedBranch({ plan: "complete", implement: "in_progress" }),
+  });
+  await off.emit("session_start");
+  await off.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+  assert.equal((await off.emitEvent("tool_result", writeResult("t1")))[0], undefined);
+
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  process.env.PI_SUBAGENT_DEPTH = "1";
+  try {
+    const child = harness({ cwd: tempCwd(), branch: resumedBranch({ plan: "complete", implement: "in_progress" }) });
+    await child.emit("session_start");
+    await child.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+    assert.equal((await child.emitEvent("tool_result", writeResult("t1")))[0], undefined);
+  } finally {
+    if (priorDepth === undefined) delete process.env.PI_SUBAGENT_DEPTH;
+    else process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("brainstorm write guard is unchanged by the implement guard", async () => {
+  const priorDepth = process.env.PI_SUBAGENT_DEPTH;
+  delete process.env.PI_SUBAGENT_DEPTH;
+  try {
+    const h = harness({ cwd: tempCwd(), branch: [phaseResult("start", phases({ brainstorm: "in_progress" }))] });
+    await h.emit("session_start");
+    await h.emitEvent("tool_call", writeCall("t1", "src/x.ts"));
+    const warned = (await h.emitEvent("tool_result", writeResult("t1")))[0] as { content: { text: string }[] };
+    assert.match(warned.content[0].text, /brainstorm/);
+  } finally {
+    if (priorDepth !== undefined) process.env.PI_SUBAGENT_DEPTH = priorDepth;
+  }
+});
+
+test("resumed session: plan-implement recovery edge fires (AC 3)", async () => {
+  const h = harness({ cwd: tempCwd(), branch: [...resumedBranch({ plan: "complete" }), assistant()] });
+  await settle(h);
+  assert.equal(h.sent.length, 1);
+  assert.deepEqual(h.sent[0].message.details, { piGauntletRecoveryEdge: "plan-implement" });
+});
+
+test("resumed session: closure gate blocks complete verify without a conformance dispatch (AC 3)", async () => {
+  const h = harness({
+    cwd: tempCwd(),
+    branch: resumedBranch({ plan: "complete", implement: "complete", verify: "in_progress" }),
+  });
+  await h.emit("session_start");
+  const tool = h.tools.find((t) => t.name === "phase_tracker")!;
+  const res = (await tool.execute("t1", { action: "complete", phase: "verify" }, undefined, undefined, h.ctx)) as {
+    details: { error?: string };
+  };
+  assert.equal(res.details.error, "no conformance-reviewer dispatch observed");
+});

package/extensions/phase-tracker.ts

@@ -27,6 +27,8 @@ import {
   checkSubstep,
   findMarkerFile,
   flowGuardApplies,
+  implementExemptDirs,
+  implementWriteGuardApplies,
   markerBlockReason,
   nextGauntletEntered,
   parseGitCommit,
@@ -169,6 +171,12 @@ const brainstormWriteWarning = (specDirs: string[]): string =>
   `Brainstorming may only edit the spec under ${specDirs.join(", ")}. Implementation\n` +
   "waits for the spec approval gate. If this edit IS the spec, place it under the spec dir.";
 
+const implementWriteWarning = (): string =>
+  "⚠️ Parent write during the implement phase.\n" +
+  "During implement the main loop orchestrates; subagents write the code - dispatch\n" +
+  "this via /skill:subagent-driven-development instead of editing directly.\n" +
+  "If this edit is merge-conflict resolution between parallel waves, proceed.";
+
 // Contiguous-subsequence match of a configured spec dir against path components.
 const pathInSpecDirs = (rawPath: string, specDirs: string[]): boolean => {
   const comps = rawPath.split("/").filter((c) => c.length > 0 && c !== ".");
@@ -272,6 +280,11 @@ export default function (pi: ExtensionAPI) {
   // (Inside a submodule the comparison is git-version-dependent and irrelevant here -
   // gauntlet flows do not run inside submodule git internals; whichever way it
   // resolves, the guard merely staying off in that edge case is harmless.)
+  // pi-cohort sets PI_SUBAGENT_DEPTH >= 1 in every spawned child (getSubagentDepthEnv).
+  // Implementer forks replay the parent's phase state; without this gate every
+  // implementer's first write would trip a spurious advisory.
+  const isSubagentChild = Number(process.env.PI_SUBAGENT_DEPTH ?? "0") > 0;
+
   const inPrimaryCheckout = (() => {
     try {
       const lines = execSync("git rev-parse --git-dir --git-common-dir", {
@@ -429,7 +442,9 @@ export default function (pi: ExtensionAPI) {
     // returns here without touching disk. Only genuinely guardable events pay for g().
     const brainstormActive = phases.brainstorm.status === "in_progress";
     const guardableWrite =
-      (event.toolName === "write" || event.toolName === "edit") && flowGuardApplies(brainstormActive, gauntletEntered);
+      (event.toolName === "write" || event.toolName === "edit") &&
+      (flowGuardApplies(brainstormActive, gauntletEntered) ||
+        implementWriteGuardApplies(phases.plan.status, phases.implement.status, gauntletEntered, isSubagentChild));
     const guardableBash =
       event.toolName === "bash" && flowGuardApplies(activeGuardPhase() !== undefined, gauntletEntered);
     if (!guardableWrite && !guardableBash) return undefined;
@@ -437,12 +452,21 @@ export default function (pi: ExtensionAPI) {
     if (!flowGuardsEnforced()) return undefined;
 
     // Guard 3 — write/edit outside the spec dir during brainstorm.
+    // Guard 4 — parent write/edit in the armed implement window (spec
+    // 2026-08-07-resume-spec-in-hand): advisory, warn-once, plans dir also exempt.
     if (event.toolName === "write" || event.toolName === "edit") {
-      if (phases.brainstorm.status !== "in_progress" || firedGuards.get("brainstorm-write")) return undefined;
       const p = (event.input as { path?: unknown } | undefined)?.path;
-      if (typeof p !== "string" || pathInSpecDirs(p, specDirs())) return undefined;
-      firedGuards.set("brainstorm-write", true);
-      addGuardWarning(event.toolCallId, brainstormWriteWarning(specDirs()));
+      if (phases.brainstorm.status === "in_progress") {
+        if (firedGuards.get("brainstorm-write")) return undefined;
+        if (typeof p !== "string" || pathInSpecDirs(p, specDirs())) return undefined;
+        firedGuards.set("brainstorm-write", true);
+        addGuardWarning(event.toolCallId, brainstormWriteWarning(specDirs()));
+        return undefined;
+      }
+      if (firedGuards.get("implement-write")) return undefined;
+      if (typeof p !== "string" || pathInSpecDirs(p, implementExemptDirs(specDirs()))) return undefined;
+      firedGuards.set("implement-write", true);
+      addGuardWarning(event.toolCallId, implementWriteWarning());
       return undefined;
     }
 

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

@@ -1,10 +1,17 @@
 const sources = {
   "@earendil-works/pi-ai": `export const StringEnum = (values, options = {}) => ({ values, ...options });`,
+  // Reads only the repo (project) settings layer - guard tests exercise repo-local
+  // settings via tempCwd()'s .pi/settings.json; there is no preset layer to stub.
   "@earendil-works/pi-coding-agent": `
+    import { readFileSync } from "node:fs";
     export class SettingsManager {
-      static create() { return new SettingsManager(); }
+      static create(cwd) { return new SettingsManager(cwd); }
+      constructor(cwd) { this.cwd = cwd; }
       getGlobalSettings() { return {}; }
-      getProjectSettings() { return {}; }
+      getProjectSettings() {
+        try { return JSON.parse(readFileSync(this.cwd + "/.pi/settings.json", "utf8")); }
+        catch { return {}; }
+      }
       drainErrors() { return []; }
     }
     export const getAgentDir = () => "/tmp/pi-gauntlet-test-agent";

package/package.json

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

package/skills/writing-plans/SKILL.md

@@ -3,7 +3,7 @@ name: writing-plans
 description: Use when you have a spec or requirements for a multi-step task, before touching code
 ---
 
-> **Related skills:** Reached via the auto-chain from `/skill:brainstorming` (not a direct human entry point). On completion this skill auto-invokes `/skill:subagent-driven-development`.
+> **Related skills:** Reached via the auto-chain from `/skill:brainstorming`, or via the spec-in-hand handoff path (see "Resuming with a spec in hand" below) — otherwise not a direct human entry point. On completion this skill auto-invokes `/skill:subagent-driven-development`.
 
 # Writing Plans
 
@@ -15,9 +15,9 @@ DRY. YAGNI. TDD. Frequent commits.
 
 **Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
 
-Before drafting the plan, call `phase_tracker({ action: "start", phase: "plan" })`.
+Before drafting the plan, call `phase_tracker({ action: "start", phase: "plan" })` (if resuming with a spec in hand, see "Resuming with a spec in hand" below first -- its arming sequence already performs this call).
 
-**Input:** an approved spec in `<project>/doc/specs/<filename>.md` (produced by `/skill:brainstorming`).
+**Input:** an approved spec in `<project>/doc/specs/<filename>.md` — produced by `/skill:brainstorming` in this session, or handed off from another session (see "Resuming with a spec in hand").
 
 **Save plans to:** the sibling `doc/plans/` directory next to the spec. The plan filename matches the spec filename exactly — same date, same Linear ID (if any), same topic slug, no `-design` suffix.
 
@@ -29,6 +29,36 @@ Before drafting the plan, call `phase_tracker({ action: "start", phase: "plan" }
 
 If no spec exists, send the work back to `/skill:brainstorming`. Do not invent a plan without a spec.
 
+## Resuming with a spec in hand
+
+A handoff path, not a shortcut: use it when an **approved spec arrives from another session** (a handoff doc, a fresh top-level session resuming ratified work). New work still enters via `/skill:brainstorming`. The trigger is **phase-tracker state, not handoff prose** — it works even when the handoff doc says nothing about arming. On invocation, check `phase_tracker({ action: "status" })` and branch on the brainstorm phase:
+
+| brainstorm status | meaning | action |
+|---|---|---|
+| `in_progress` or `complete` | auto-chain from brainstorming | normal flow below, unchanged |
+| `pending`, no other phase `in_progress` | fresh resume | arm, then plan (this section) |
+| `skipped` | already resumed in this session | do **not** re-run the sequence (`start` errors on a skipped phase without `force`); verify plan state and continue |
+| `pending`, another phase `in_progress` | not a fresh resume (`start brainstorm` would error) | stop and ask the user; do not arm |
+
+On a fresh resume:
+
+1. **Verify the spec exists** at the given path. Missing → stop and ask; never arm on a missing spec.
+2. **Confirm approval.** Any unambiguous assertion in the prompt, handoff doc, or user message ("Brainstorming is complete", "spec approved" — examples, not an allowlist) counts. No assertion → ask once; on "no", route to `/skill:brainstorming`.
+3. **Worktree.** If not already in an isolated worktree, set one up per `/skill:using-git-worktrees` and commit the spec there (the spec must live in the worktree, same as the brainstorm path).
+4. **Arm the flow** — run exactly:
+
+   ```
+   phase_tracker({ action: "start", phase: "brainstorm" })
+   phase_tracker({ action: "skip", phase: "brainstorm", reason: "resume: approved spec at <path>" })
+   phase_tracker({ action: "start", phase: "plan" })
+   ```
+
+   This is the existing arming mechanism, not new mechanics: the `start` arms `gauntletEntered`, `skip` preserves it, session replay reconstructs it, `reset` disarms. The sequence already performed this skill's own `start plan` call — **do not** issue a second one (a repeat `start` on the in_progress phase is a no-op reset that re-clears the warn-once guard ledger).
+
+Then continue with the normal flow below (Scope Check onward).
+
+**Writing a handoff doc** (from the producing session): name `/skill:writing-plans` as the entry point — never a phase past planning, since this gesture only arms through `start plan` — give the spec's path, and assert its approval status.
+
 ## Boundaries
 
 - Read code and docs: yes