pi-gauntlet 5.6.1 → 5.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v5.7.0 - 2026-09-17
+
+- `gauntlet-resume` (new, human-only, `disable-model-invocation: true`): the sole re-entry point into an interrupted gauntlet flow from a fresh session. Input is a pi-cohort `/handoff` brief (file or pasted; grammar in `skills/gauntlet-resume/reference/brief-contract.md`) or a bare worktree that already holds a spec (`reference/reconstruction.md`). Restores `phase_tracker` / `plan_tracker` state via `start brainstorm` + `skip` with `resume:` reasons, re-runs `plan_check` before implement-or-later, stops a ship-stage brief at verify, never creates a worktree, never infers approval from artifacts. Free-form prompts redirect to `/skill:brainstorming`.
+- `writing-plans`: "Resuming with a spec in hand" removed; `start plan` is skipped when the phase is already `in_progress` (a `gauntlet-resume` arrival).
+- Removed the three remaining `intercom` references (pi-intercom no longer exists); `scripts/ci.mjs` asserts both retirements stay absent.
+
+## v5.6.2 - 2026-09-17
+
+- `brainstorming`: the lookup rule distinguishes current-state facts (looked up) from decisions about what should happen (asked, even when a ticket recorded one earlier); the `Recommendation:` suffix binds questionary questions only, not the skill's git-state, design-round, or spec-gate approvals; the premise note may be questionary question one. Follow-ups from the #32 post-ship assessment. (#32)
+
 ## v5.6.1 - 2026-09-17
 
 - `brainstorming`: the questionary looks up questions the code, docs, or issue tracker already answer instead of asking; every question it does ask ends with `Recommendation: <answer> - <why>` (including the ask to accept a corrected fact); before approaches, a plain-prose premise note in chat names which design-dependent claims the sources support, disprove (with the corrected fact and where), or leave unverified - a contradicted claim stops the flow until the user accepts the correction or explicitly overrides, with the outcome recorded in the draft. One checklist pointer, one Red Flags entry. (#32)

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:
 
-- **17 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). Four 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`.
+- **18 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). Five 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-resume` is the only way back into an interrupted flow from a fresh session: it takes a pi-cohort `/handoff` brief (file or pasted) 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>]`.
 - **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 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. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 

package/package.json

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

package/skills/brainstorming/SKILL.md

@@ -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.
 
@@ -145,10 +145,12 @@ path.
 - Ask questions **one at a time** to refine the idea. Prefer multiple-choice; one
   question per message. Focus on: purpose, constraints, success criteria, who/what
   it touches. Before asking, check whether the code, the docs, or the issue tracker
-  already answer it - if so, look it up instead of asking (dispatch a subagent when
-  the lookup is costly), and ask only what no source can answer. Every question you
-  ask, including asking the user to accept a corrected fact, ends with the line
-  `Recommendation: <answer> - <why>` - the answer, then " - ", then the reason.
+  already answer it: a fact about the current state is looked up, not asked (dispatch
+  a subagent when the lookup is costly); a decision about what should happen is asked,
+  even when a ticket recorded one earlier. Every questionary question, including the
+  ask to accept a corrected fact, ends with the line `Recommendation: <answer> - <why>`
+  (the answer, then " - ", then the reason); approvals elsewhere in this skill (git
+  state, design rounds, the spec gate) keep their own wording.
 - **Append bar:** append to the draft's `## Appended during questionary` only
   findings the spec will cite — schema shapes, hard constraints, ticket-vs-code
   contradictions, user answers that changed scope. Not a log of every grep.
@@ -160,13 +162,14 @@ on, which of those claims the sources support and where you saw it (a file and l
 a doc, a ticket), which they disprove - give the corrected fact and where you found
 it - and which remain unverified, naming the lookup you tried. Write it as a note a
 person can act on: full sentences, no status-keyword lists, no template; when the
-design depends on no claims at all, one sentence saying so is enough. An unverified claim is not a stop - it enters the
-spec as an Open Question or a stated assumption. If a claim the design depends on was
-contradicted, the note is your next message and it ends by asking the user to accept
-the corrected fact or explicitly override it; nothing else continues - no other
-questions, no approaches - until they answer, and the outcome is recorded in the draft's
-`## Appended during questionary` so spec-writing carries it into `## Problem` or the relevant `## Design`
-decision.
+design depends on no claims at all, one sentence saying so is enough. An unverified
+claim is not a stop - it enters the spec as an Open Question or a stated assumption.
+If a claim the design depends on was contradicted, the note is your next message -
+even as questionary question one - and it ends by asking the user to accept the
+corrected fact or explicitly override it; nothing else continues - no other questions,
+no approaches - until they answer, and the outcome is recorded in the draft's
+`## Appended during questionary` so spec-writing carries it into `## Problem` or the
+relevant `## Design` decision.
 
 ### 4. Explore approaches
 

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