pi-gauntlet 5.6.2 → 5.8.0

package/extensions/verify-before-ship.ts

@@ -25,21 +25,14 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { resolveVerifyBeforeShip, settingsErrorWarning } from "./lib/gauntlet-settings.ts";
+import {
+  DEFAULT_TEST_COMMANDS,
+  buildTestCmdRegex,
+  resolveVerifyBeforeShip,
+  settingsErrorWarning,
+} from "./lib/gauntlet-settings.ts";
 import { loadGauntletSettings } from "./lib/gauntlet-settings-loader.ts";
 
-// Default verification entrypoints. Override via settings.
-const DEFAULT_TEST_COMMANDS = [
-  "make\\s+(?:ci|test)(?![-\\w])", // rejects make test-smoke, test-corpus, etc.
-  "npm\\s+(?:test|run\\s+test)",
-  "pnpm\\s+test",
-  "yarn\\s+test",
-  "pytest",
-  "rspec",
-  "cargo\\s+test",
-  "go\\s+test",
-];
-
 const SHIP_CMD = /\b(git\s+push|gh\s+pr\s+create)\b/;
 
 const SOURCE_EXT = /\.(ts|tsx|js|jsx|py|rb|go|rs|java|swift|kt)$/;
@@ -50,9 +43,6 @@ const isSourceWrite = (filePath: string | undefined): boolean => {
   return SOURCE_EXT.test(filePath) && !TEST_PATH.test(filePath);
 };
 
-const buildTestCmdRegex = (commands: string[]): RegExp =>
-  new RegExp(`\\b(${commands.join("|")})\\b`);
-
 const formatWarning = (command: string, testCommands: string[], reference: string | undefined): string => {
   const examples = testCommands
     .slice(0, 3)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.6.2",
+  "version": "5.8.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -38,7 +38,8 @@
     "extensions": [
       "./extensions/phase-tracker.ts",
       "./extensions/plan-tracker.ts",
-      "./extensions/verify-before-ship.ts"
+      "./extensions/verify-before-ship.ts",
+      "./extensions/telemetry.ts"
     ],
     "image": "https://raw.githubusercontent.com/jjuraszek/pi-gauntlet/main/pi-gauntlet.png"
   },
@@ -50,5 +51,8 @@
     "postinstall": "node ./bin/install-agents.mjs",
     "link-agents": "node ./bin/install-agents.mjs",
     "test": "node scripts/ci.mjs"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
   }
 }

package/skills/brainstorming/SKILL.md

@@ -38,7 +38,7 @@ This skill ends with a **written, user-reviewed spec inside a worktree**. Nothin
 
 ## Foreground dispatch policy
 
-Flow-owned execution dispatches run in the foreground: set top-level `async: false` on gather, critique, council, summary, implementation, review, conformance, and retry calls. `forceTopLevelAsync` must remain unset or false; it is incompatible with this flow. See [pi-cohort dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md). If a dispatch returns an async handle despite `async: false`, stop and report the configuration error: do not poll it, relaunch work, or advance the flow. An intercom-detached child is likewise incomplete work; use the existing coordination path and never accept or duplicate it.
+Flow-owned execution dispatches run in the foreground: set top-level `async: false` on gather, critique, council, summary, implementation, review, conformance, and retry calls. `forceTopLevelAsync` must remain unset or false; it is incompatible with this flow. See [pi-cohort dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md). If a dispatch returns an async handle despite `async: false`, stop and report the configuration error: do not poll it, relaunch work, or advance the flow. A child that detached from the foreground run is likewise incomplete work; use the existing coordination path and never accept or duplicate it.
 
 Foreground does not serialize independent work: preserve existing isolated parallel `tasks` batches and await their terminal results before acceptance or tracker/phase advancement.
 

package/skills/dispatching-parallel-agents/SKILL.md

@@ -206,7 +206,7 @@ subagent({
 })
 ```
 
-For chains, async runs, intercom coordination, and the full agent roster, read the `pi-cohort` skill — this skill covers only the parallel fan-out case.
+For chains, async runs, and the full agent roster, read the `pi-cohort` skill — this skill covers only the parallel fan-out case.
 
 ## Verification
 

package/skills/gauntlet-resume/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: gauntlet-resume
+description: Use when a human wants to continue an interrupted gauntlet flow in a fresh session - from a pi-cohort handoff brief (file or pasted) 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.
+disable-model-invocation: true
+argument-hint: "[<brief-file>] [<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.
+
+# Gauntlet Resume
+
+## Overview
+
+Re-enter an interrupted gauntlet flow in a fresh session. Two inputs: a handoff brief
+produced by pi-cohort's `/handoff` (grammar in `reference/brief-contract.md`), or 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.
+
+**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).
+
+## Arguments
+
+`/skill:gauntlet-resume [<brief>] [<worktree>]` - zero to two positional tokens, plus
+optional pasted text after the command line.
+
+| Form | Meaning |
+|---|---|
+| `<brief-file>` | readable file whose line 1 starts `# Handoff:` |
+| pasted text whose first line starts `# Handoff:` | inline brief (equivalent to a file) |
+| `<worktree>` alone | bare name resolved as `<primary>/.worktrees/<name>`, or an absolute path; must already be a git worktree |
+| `<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 --git-common-dir)`
+(not `--show-toplevel`, which returns the linked worktree when run inside one). A pasted
+brief that needs an override uses the file form. This skill never runs `git worktree add`.
+
+## Entry checks
+
+In order. All before any tracker mutation; entry check 1 is read-only.
+
+1. **Idle session.** `phase_tracker({ action: "status" })`. Any phase not pending ->
+   stop: "session already carries flow state - reset is your call".
+2. **Target worktree.** Resolve from the brief's `worktree:` field, the override, or the
+   bare argument. Stops: path missing or `git -C <path> rev-parse --is-inside-work-tree`
+   fails; override and brief worktree differ after `realpath`; brief has no
+   `## Repo state` heading (prefix match: `## Repo state` or
+   `## Repo state: not a git repo`); brief worktree is `no`, `unavailable`, or
+   `not a git repo` and no override was given - except a `worktree: no` brief **without**
+   process state, which is the brainstorming route in Dispatch, not a stop. Other
+   `unavailable` fields inside `## Repo state` are legal.
+3. **Session cwd binding.** `phase_tracker`, `plan_check`, and the flow guards resolve
+   every path against the extension's session cwd; a child-shell `cd` cannot relocate it.
+   If `realpath $(git rev-parse --show-toplevel)` in the session cwd differs from the
+   resolved worktree, stop: "restart pi in <worktree> and re-run". Every restoration
+   therefore runs with the session rooted in the resolved worktree.
+4. **Drift notice.** Compare the brief's `HEAD` and `dirty` fields in `## Repo state`
+   with the live worktree (`git rev-parse HEAD`, `git status --porcelain`). Announce
+   differences. Informational, never a stop.
+5. **Skills loaded.** For each name in `## Skills loaded` (none for
+   `## Skills loaded: none`): match against the frontmatter `name` of every
+   `skills/*/SKILL.md` in this package; `Read` each match's complete file into the
+   transcript; list non-matches as skipped. Loaded bodies are context only - no skill's
+   entry actions run until Dispatch names one.
+
+## Dispatch
+
+| Input | Route |
+|---|---|
+| brief with `## Process state` | process-state restore - `reference/brief-contract.md` "Process-state restore" |
+| brief without process state, `## Skills loaded` names `chase-bug` | hotfix route below, before any artifact reconstruction, no tracker calls |
+| 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) |
+
+**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
+path, hand it to hotfix.md and skip its worktree-create step when the brief's worktree
+exists (reuse it). Otherwise invoke `/skill:chase-bug` triage with `## Intent` to
+re-derive the record.
+
+## Post-restore continuation
+
+After a successful restore, print the closing line from `reference/brief-contract.md`
+(gate history not restored; the task to re-validate), then continue in the stage's
+owning skill **without** its reset-bearing entry:
+
+| Active after restore | Continue in | Entry point |
+|---|---|---|
+| brainstorm | brainstorming checklist | on-disk state decides the step: draft marker on line 1 of the spec file -> step 4; spec title -> step 8. Never `/skill:brainstorming` entry (it resets both trackers) |
+| plan | writing-plans body | skip its `start plan` call (already in_progress) |
+| implement | subagent-driven-development | re-validate `<task>` first (re-run its `Tests:`), then the task loop from the first non-complete task |
+| verify | verification-before-completion | full conformance gate; nothing carried over |
+
+## Red flags — STOP
+
+- Any `phase_tracker` or `plan_tracker` mutation before entry checks 1-5 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.
+- Accepting a free-form prompt as a brief.
+
+## Project overrides
+If a gauntlet overrides file exists - checked in order:
+`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`,
+`<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Any
+sections relevant to this skill - by name match, by topic (routing,
+verification, worktrees, etc.), or by workflow convention - override or
+extend the instructions above. Project-local `AGENTS.md` is already in
+context - check it for project-specific routing tables, service paths, and
+verification commands.

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

@@ -0,0 +1,121 @@
+# Handoff brief contract (gauntlet-resume supplementary)
+
+Consumed only by `SKILL.md` in this directory. This file is the single concentration
+point for text coupled to pi-cohort's `/handoff` template (`doc/handoff-template.md`
+in pi-cohort; baseline inlined from its `prune-prompts` branch, commit `d737eb9`).
+Cohort drift is reconciled here and nowhere else.
+
+## Brief grammar
+
+Headings, fixed order. A consumer keys on headings, never prose.
+
+```markdown
+# Handoff: <one line>
+## Intent
+## Repo state
+## Decisions
+## Open questions
+## Skills loaded
+## Process state
+```
+
+| Section | Content | Presence |
+|---|---|---|
+| `## Repo state` | one field per line: `toplevel`, `worktree: yes <path>` or `worktree: no`, `branch` (`detached` when none), `HEAD`, `base` (`unknown` when no remote resolves), `dirty: <porcelain>` or `dirty: clean`, `diff-stat` (`unavailable` when base unknown), `test cmd`; any field `unavailable` when its command failed; heading `## Repo state: not a git repo` outside git | always |
+| `## Decisions` | bullets; rejected alternatives marked `rejected:` | always |
+| `## Skills loaded` | frontmatter `name`s; `## Skills loaded: none` when none | always |
+| `## Process state` | `phase_tracker status` then `plan_tracker status` verbatim; `Active task: <name|none>`; the line `Gate history not restored - re-validate before advancing.` | only when both tracker tools exist and a phase is `in_progress` |
+
+Consumer rules (cohort): process state absent -> plain handoff (the consumer starts its
+own process from `## Intent`); present with `No plan active.` -> phase-only, restore no
+plan; loading named skills is the consumer's job.
+
+A brief is any text whose first line starts `# Handoff:` - a file on disk or pasted
+inline. `## Repo state` is matched by prefix: `## Repo state` or
+`## Repo state: not a git repo`.
+
+## Tracker output grammar
+
+Must match `formatStatus` in the phase-tracker and plan-tracker extensions.
+
+```
+Phases:
+  ✓ brainstorm
+  → implement(W2)
+  ○ verify (reason)
+```
+
+Glyphs `✓` complete, `→` in_progress, `⊘` skipped, `○` pending; `(reason)` suffix when
+set; `name(substep)` only on the in-progress phase.
+
+```
+Plan: 2/5 done (1 in progress, 2 pending)
+
+  ✓ [0] <name>
+  → [1] <name>
+```
+
+or `No plan active.`. Task glyphs `✓` complete, `→` in_progress, `✗` failed, `⊘` skipped,
+`○` pending, mapping 1:1 onto `plan_tracker init` `{name, status}` statuses.
+
+Parse stops (print the offending line, make no tracker call):
+
+- a task line not matching `^\s*[✓→✗⊘○] \[\d+\] .+$` - the "unparsable process-state
+  task line" stop;
+- a process-state section whose phase block shows all `○` - contradictory (the producer
+  emits the section only with an in-progress phase);
+- a phase block with more than one `→` line - contradictory (the tracker holds one active
+  phase; print both lines).
+
+## Process-state restore
+
+Facts that fix the order (from the extensions):
+
+- Arming happens only on `start brainstorm`; `reset` disarms; `skip` and `complete`
+  preserve it.
+- `plan_check` stamps only inside an armed flow; unarmed it returns
+  `PASS (no flow to stamp)`.
+- `start implement` is rejected without a current `plan_check` stamp.
+- `skip` has no state precondition and takes a `reason`; one phase is active at a time.
+- `complete verify` is blocked without a fresh `conformance-reviewer` dispatch when
+  closure review is enforced.
+- `plan_tracker init` on an in-progress implement with every task `complete`/`skipped`
+  auto-completes implement.
+
+Per-stage call table, keyed by the brief's active phase (`→`). `R` is the reason string
+`resume: <brief file or "pasted brief">`.
+
+| Active | Calls, in order |
+|---|---|
+| brainstorm | `start brainstorm`; `substep` if the brief shows one |
+| plan | `start brainstorm`; `skip brainstorm R`; `start plan`; `substep` if shown |
+| implement | `start brainstorm`; `skip brainstorm R`; `start plan`; `plan_check({ planPath })`; on FAIL print findings and stop with plan in_progress, no init; on PASS `skip plan R`; `start implement`; `substep` if shown; `plan_tracker init` |
+| verify | as implement through `skip plan R`, then `skip implement R`; `start verify`; `substep` if shown; `plan_tracker init` |
+| ship | as verify. Restoration stops at verify in_progress: `complete verify` needs a fresh conformance dispatch and `skip verify` would bypass a real gate. Announce that the closure review re-runs before ship |
+
+`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);
+zero pairs -> stop; more than one -> human picks.
+
+"Exact" restoration binds: the active phase identity and substep, and the plan task list
+(names, order, statuses) verbatim. Prior phases show `⊘ (resume: ...)` regardless of the
+brief's glyph - skip-arming is the mechanism and completing priors would fabricate gated
+history. `No plan active.` -> no `init` call.
+
+Before `init`, validate feasibility against the tracker's own rules:
+
+- pending-suffix order - every `○` task must trail every non-pending task;
+- the implement auto-complete edge - an implement brief whose tasks are all
+  complete/skipped is infeasible as stated; propose verify as the target and ask.
+
+Every restore ends with:
+
+```
+Gate history not restored; re-validating `<task>` before any stage advance
+```
+
+where `<task>` is the brief's `Active task`, else the first in-progress task, else `none`
+(whole-deliverable re-validation). Gate history, closure-review evidence, and fix rounds
+are never inferred or restored; a ship-stage brief resumes at verify.

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

@@ -0,0 +1,96 @@
+# Bare-worktree reconstruction (gauntlet-resume supplementary)
+
+Consumed only by `SKILL.md` in this directory, for a resolved worktree with no
+`## Process state` to restore from - a bare worktree argument, or a brief without
+process state whose worktree exists. Artifact presence never implies approval; task
+commits never imply review acceptance. Every question below is a human question, and
+no tracker call happens before the human answers.
+
+Brief context: when the input was a brief, carry its `## Intent`/`## Decisions` verbatim
+into every prompt below. When the input was a bare worktree, say so - "no brief context
+available" - and never invent Intent or Decisions.
+
+## Base
+
+```bash
+git merge-base HEAD origin/HEAD 2>/dev/null \
+  || git merge-base HEAD main 2>/dev/null \
+  || git merge-base HEAD master 2>/dev/null
+```
+
+Base = `git merge-base HEAD origin/HEAD`, else `main`/`master`. Empty -> ask the human
+for a base ref before reading any artifact.
+
+## Candidates
+
+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,
+space-separated - never the literal defaults when a setting is present.
+
+```bash
+git diff --diff-filter=A --name-only <base>..HEAD -- <dirs>
+git ls-files --others --exclude-standard -- <dirs>
+```
+
+Candidates are files under those directories added after base, plus untracked files
+there. A spec and a plan pair by identical basename (`<specDir>/<name>.md` <->
+`<sibling plans dir>/<name>.md`). The plan commit is the first post-base commit that added the
+plan file: `git log --diff-filter=A --format=%H --reverse <base>..HEAD -- <plan>`, first
+line. An uncommitted plan has no plan commit; treat every task as `pending`.
+
+| Candidates | Route |
+|---|---|
+| no spec | stop; offer `/skill:brainstorming`; 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" |
+
+## Spec without plan
+
+Ask exactly one question: is this spec approved? Show the spec path (and the brief's
+`## Intent`/`## Decisions` when present).
+
+- Approved: `start brainstorm`; `skip brainstorm resume: <spec path>`; `start plan`;
+  continue in writing-plans (its own `start plan` is skipped - plan is already
+  in_progress).
+- Not approved: invoke `/skill:brainstorming` with the spec as the draft; arm nothing.
+  using-git-worktrees Step 0 detects the existing worktree and creates none.
+
+## Spec with plan
+
+Show, and ask the human to confirm or edit both in one reply:
+
+1. Per task, in plan order: the commits after the plan commit that touch any path in
+   the task's declared `Files:` block. Strip a trailing `:digits[-digits]` range from
+   each `Modify:` path before matching `git log -- <path>`:
+   `git log --format=%h --oneline <plan-commit>..HEAD -- <path>`. Uncommitted plan (no
+   plan commit): skip this query entirely - there is no range to search - and show
+   "plan uncommitted; no task evidence" in its place; every task is proposed `pending`.
+2. Uncommitted files: `git status --porcelain`.
+3. Proposed task statuses: `complete` iff at least one matching commit, else `pending`.
+4. Proposed stage: `implement` if any task is `pending`, else `verify`.
+
+Validate the confirmed snapshot before any tracker call:
+
+- pending-suffix order - every `pending` task trails every non-pending one;
+- all tasks complete/skipped with stage `implement` is infeasible (implement would
+  auto-complete on `init`).
+
+Reject an infeasible edit by citing the offending rows and re-asking. Confirmation
+edits override proposals; never rewrite confirmed state silently.
+
+After confirmation:
+
+1. `start brainstorm`; `skip brainstorm resume: <spec path>`; `start plan`.
+2. `plan_check` with `planPath` = the plan. FAIL -> print the findings, stop with plan
+   in_progress, no `init`.
+3. PASS -> `skip plan` with the same `resume:` reason; for stage verify also
+   `skip implement`; `start <stage>`.
+4. `init` the confirmed non-empty task list as `{name, status}` elements.
+5. `phase_tracker status` and `plan_tracker status` must match the confirmed active
+   stage and task list exactly; a mismatch is reported verbatim, not patched.
+
+End with the standard line from `brief-contract.md`. `<task>` follows the same rule as
+there: there is no brief `Active task` on this route, so it is the first confirmed
+`in_progress` task, else `none` (whole-deliverable re-validation).

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`, 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`.
+> **Related skills:** Reached via the auto-chain from `/skill:brainstorming`, or via `/skill:gauntlet-resume` when a restored flow lands at the plan stage — 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" })` (if resuming with a spec in hand, see "Resuming with a spec in hand" below first -- its arming sequence already performs this call).
+Before drafting the plan, check `phase_tracker({ action: "status" })`. If `plan` is already `in_progress` (a flow restored by `/skill:gauntlet-resume` arrives this way), do **not** call `start` again - a repeat `start` on the in_progress phase resets its guard ledger. Otherwise call `phase_tracker({ action: "start", phase: "plan" })`.
 
-**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").
+**Input:** an approved spec in `<project>/doc/specs/<filename>.md` — produced by `/skill:brainstorming` in this session, or restored from another session by `/skill:gauntlet-resume`. Those two are the only entry points.
 
 **Save plans to:** the sibling `doc/plans/` directory next to the spec. The plan filename matches the spec filename exactly — same date, same ticket ID (if any), same topic slug, no `-design` suffix.
 
@@ -29,36 +29,6 @@ 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, including Recon).
-
-**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