pi-gauntlet 5.18.7 → 5.20.0

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

@@ -181,9 +181,11 @@ Rows 1-2 run the Option 1/2 blocks; row 3 runs the Keep block and row 4 the Disc
 
 ### Step 5: Execute Choice
 
-#### Strip the plan, keep the record (Options 1-3)
+#### Strip the plan, seal the record (Options 1-3)
 
-Run this on the feature branch before any landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
+Run this on the feature branch before any landing path. The spec and its telemetry record (`<telemetry.dir>/<spec path with .md -> .yaml>`, default `.pi/gauntlet/telemetry/doc/specs/<spec>.yaml`) are deliverables and ship in the squash; only the plan is stripped. The record is an untracked, git-excluded file until this step commits it. `<bin>` is `<directory of this skill's SKILL.md>/../../bin`, resolved from the skill's `<location>` in the system prompt.
+
+Read the plan's `**Spec:**` header (repo-relative, backticks stripped) before the strip; that value is `--spec`.
 
 ```bash
 # Plans are ephemeral - if one was committed on this branch, remove it before landing.
@@ -192,15 +194,16 @@ if git -C "$WORKTREE" ls-files --error-unmatch "$PLAN_PATH" >/dev/null 2>&1; the
   git -C "$WORKTREE" rm "$PLAN_PATH" && git -C "$WORKTREE" commit -m "Remove ephemeral plan doc"
 fi
 
-# The telemetry record is a deliverable - restore it if a strip or a stray delete removed it.
-node <bin>/gauntlet-telemetry-salvage.mjs --worktree "$WORKTREE" --base <base-branch>
+# Seal the telemetry record: stamp shipped, compute the diff, commit it once.
+# --option is pr for Options 1-2 and squash for Option 3; --spec is the plan header's **Spec:** value (omit when no plan is known).
+node <bin>/gauntlet-telemetry-seal.mjs --worktree "$WORKTREE" --option <pr|squash> --base <base-branch> --spec <spec path>
 ```
 
-The salvage prints one line per spec on the branch (`present`, `present <path> (marked shipped)`, `restored <path> from <sha>`, `restored <path> from <sha> (marked shipped)`, `no telemetry run`, `never written`, `restore failed <path>: <reason>`) and always exits 0. `(marked shipped)` means the record was still `in_progress` with no ship phase (the recorder lost its binding) and the salvage committed `status: shipped` + `shipped_at` as one `telemetry:` commit; it rides the squash or push like any branch commit. Print its stdout verbatim in the ship completion message. A `restore failed` line is reported, never retried, and never blocks the ship - the record stays recoverable from the branch ref.
+The seal prints one line per record (`sealed <path>`, `already sealed <path>`) or one bare outcome (`no telemetry run`, `telemetry disabled`) and exits 0; print its stdout verbatim in the ship completion message. Any nonzero exit stops the flow before the first landing command, quoting the bin's line: exit 2 (`no record at <path>`, `unparseable record <path>: <reason>`) means this gauntlet run's recorder never armed or its record is corrupt; exit 1 is a usage, environment, or git failure (`seal failed <path>: <reason>` restored the pre-seal bytes). The user decides; never land without the seal.
 
 #### Option 1: Push and Create PR
 
-Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then:
+Run the strip-and-seal block above first (plan stripped, telemetry record sealed), then:
 
 ```bash
 # Push branch
@@ -231,11 +234,11 @@ When the spec's `## Acceptance criteria` has at least one `venue:` or `deferred:
 
 #### Option 2: Push and Create Draft PR
 
-Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then Option 1's push and `gh pr create` commands with `--draft` added. The PR body is unchanged. Do not clean up the worktree.
+Run the strip-and-seal block above first (plan stripped, telemetry record sealed), then Option 1's push and `gh pr create` commands with `--draft` added. The PR body is unchanged. Do not clean up the worktree.
 
 #### Option 3: Squash-merge to base
 
-Run the strip-and-salvage block above first (plan stripped, telemetry record kept), then:
+Run the strip-and-seal block above first (plan stripped, telemetry record sealed), then:
 
 ```bash
 git -C "$PRIMARY" checkout <base-branch>
@@ -245,7 +248,7 @@ git -C "$PRIMARY" commit -m "<imperative summary> (ref <ticket-id>)"
 (cd "$PRIMARY" && <the Step 1 set>)
 ```
 
-The plan was already removed on the branch, so the staged squash tree carries the spec, the telemetry record, and the implementation - never the plan.
+The plan was already removed and the telemetry record sealed on the branch, so the staged squash tree carries the spec, the telemetry record, and the implementation - never the plan.
 
 The post-squash re-verify is not optional - `git merge --squash` can surface conflict-resolution mistakes the worktree-side run couldn't catch.
 
@@ -255,7 +258,7 @@ Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `git -C "$PRIMA
 
 #### Option 4: Keep As-Is
 
-Report: "Keeping branch <name>. Worktree preserved at <path>."
+Report: "Keeping branch <name>. Worktree preserved at <path>." The telemetry record stays untracked and in_progress in the worktree; a later finishing run on this worktree seals it.
 
 **Don't cleanup worktree.**
 
@@ -273,7 +276,7 @@ Type 'discard' to confirm.
 
 Wait for exact confirmation.
 
-If confirmed: Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `git -C "$PRIMARY" branch -D "$FEATURE"`.
+If confirmed: Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `git -C "$PRIMARY" branch -D "$FEATURE"`. The record is git-excluded, so git worktree remove needs no --force; it goes with the worktree.
 
 ### Step 6: Cleanup Workspace
 
@@ -294,7 +297,7 @@ Removal precedes branch deletion in both options; `git branch -d`/`-D` fails whi
 
 ## Quick Reference
 
-| Option | Merge | Push | Keep Worktree | Cleanup Branch | Plan strip + record salvage |
+| Option | Merge | Push | Keep Worktree | Cleanup Branch | Plan strip + record seal |
 |---|---|---|---|---|---|
 | 1. Create PR | - | yes | yes | - | yes (guarded, on the branch before push) |
 | 2. Create draft PR | - | yes | yes | - | yes (guarded, on the branch before push) |
@@ -334,13 +337,13 @@ A host-owned worktree (Step 6 "Otherwise") keeps both the worktree and the branc
 - **Problem:** Accidentally delete work
 - **Fix:** Require typed "discard" confirmation
 
-**Skipping the strip-and-salvage block in Options 1-3 (any path that lands on base)**
+**Skipping the strip-and-seal block in Options 1-3 (any path that lands on base)**
 - **Problem:** Plan docs are ephemeral and shouldn't land on `<base-branch>`; the telemetry record is a deliverable and must. Skipping the block ships the plan, or drops the record the spec index reads.
 - **Fix:** Run the block on `$WORKTREE` before the squash or the push. The plan stays in the branch's git history (`git -C "$PRIMARY" log --all -- doc/plans/...`). Spec and telemetry record stay on `<base-branch>`; plan does not.
 
 **Widening the plan strip to the telemetry record**
 - **Problem:** `.pi/gauntlet/telemetry/**` looks like scaffolding next to the plan and gets deleted in the same commit - main then has no record for the run.
-- **Fix:** Never `git rm` under the telemetry dir. The salvage restores a stripped record, but the deletion should not happen in the first place.
+- **Fix:** Never `git rm` under the telemetry dir. Until the seal the record is untracked and git-excluded, so a plan strip cannot reach it; after the seal it is a committed deliverable.
 
 ## Completion
 
@@ -363,12 +366,12 @@ Once the merge (and any deploy) has landed, `/skill:check-delivery <ticket-ref>`
 - Clean up worktrees you didn't create (provenance check)
 - Run any step without the `<worktree-path>` argument
 - Auto-proceed past an undispositioned carried-open gap
-- Skip the strip-and-salvage block before the Option 3 squash or the Option 1/2 push
+- Skip the strip-and-seal block before the Option 3 squash or the Option 1/2 push
 - Delete the telemetry record (`.pi/gauntlet/telemetry/**` or the configured `telemetry.dir`) on any path
 
 **Always:**
 - Verify, or apply the Step 1 skip rule, before offering options
-- Print the `gauntlet-telemetry-salvage.mjs` output verbatim in the ship completion message
+- Print the `gauntlet-telemetry-seal.mjs` output verbatim in the ship completion message
 - Derive `$PRIMARY` and `$FEATURE` from `<worktree-path>` before presenting the menu
 - Present exactly 5 options (or 4 for detached HEAD)
 - Get typed confirmation for Option 5 (Discard)

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

@@ -67,19 +67,6 @@ Orchestrator step.
   local reproduction, never implying the local command ran; `<sha>` is the assessed
   `headRefOid`, `<url>` degrades to `unavailable` when absent. Provenance checks on
   `worktree_root`/`run_cwd` bind only to the local path.
-- **Telemetry record:** run
-  `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base
-  origin/<baseRefName> --check`. The `--check` flag makes the probe detect-only: it
-  never mutates. `present` / `no telemetry run` / `never written` land in
-  `## Evidence` as one line each. `stripped <path> in <sha>` mints a blocking `P#`
-  (`source_ref`: `gauntlet-telemetry-salvage`) whose drafted fix is "run the salvage
-  without `--check`" - the spec and its telemetry record are deliverables that ship
-  in the squash. On a cell with no push row (fork overlay, report-only states) the
-  same finding is a non-blocking follow-up instead: the record stays recoverable
-  from the PR head ref after merge, and blocking would stop a ship the gate cannot
-  repair. `unfinished <path>` (record still `in_progress` with no ship phase) also
-  lands in `## Evidence` as one line and is non-blocking: pre-landing `in_progress`
-  is normal, and the merge course's salvage run stamps it.
 - **Evidence:** on the CI path, list each satisfying check's name, conclusion,
   assessed SHA, and run URL - there is no command or `raw_tail` to paste. On the
   local path, paste each run's `command` and `raw_tail` verbatim, fenced - never

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

@@ -12,8 +12,7 @@ Actions (compose freely in the custom row):
                                                                         reviewed doc edits exist
                                                                         in the worktree)
   merge-squash | merge-commit                                          (preconditions per Verdict;
-                                                                        never bundled with a push,
-                                                                        except the telemetry: restore commit)
+                                                                        never bundled with a push)
   merge-squash anyway | merge-commit anyway                            (custom row only: overrides a
                                                                         reviewer-withheld merge - the literal
                                                                         `anyway` accepts the named reason;

package/skills/gatekeep-pr/reference/post-selection-loop.md

@@ -14,17 +14,17 @@ For a `fix <set>` selection, filter the selected set to worktree-fixable `P#`s f
 
 Batch the remaining worktree-fixable set by the union of files each finding's drafted edit in `## Drafted fixes / review` touches - fall back to the `source_ref` file only when a finding has no draft. Findings whose drafts share a file share a batch.
 
-Use one child contract for every batch, whether there is one or many: dispatch `implementer` children with `subagent({ agent: "implementer", context: "fresh", cwd: <PR worktree> })`. The orchestrator owns commit, gate, and push - never a child. Every dispatched child gets `cwd` = the PR worktree; `worktree: true` is forbidden per `assessment.md` `## Inline-first execution`. Each child is edit-only - no git commands, no verification runs - and must never delete `.pi/gauntlet/telemetry/**` or anything under the configured telemetry dir (a fix that "cleans up" the run's telemetry record is a defect in the fix, not a cleanup). Each child's task is that batch's `P#` lines plus the drafted edit already keyed to each ID in `## Drafted fixes / review` - the child applies the consented payload, it does not re-solve the finding.
+Use one child contract for every batch, whether there is one or many: dispatch `implementer` children with `subagent({ agent: "implementer", context: "fresh", cwd: <PR worktree> })`. The orchestrator owns commit, gate, and push - never a child. Every dispatched child gets `cwd` = the PR worktree; `worktree: true` is forbidden per `assessment.md` `## Inline-first execution`. Each child is edit-only - no git commands, no verification runs. Each child's task is that batch's `P#` lines plus the drafted edit already keyed to each ID in `## Drafted fixes / review` - the child applies the consented payload, it does not re-solve the finding.
 
 At a cutoff of 2 worktree-fixable findings or fewer, the orchestrator applies the fix inline instead of dispatching - the no-cohort path stays available at any batch count per `assessment.md` `## Inline-first execution`. Past that cutoff, when more than one batch results, dispatch the batches' children in parallel, all under the same contract.
 
-Once every dispatched or inline batch returns, commit the golden course as one local commit set - the code fixes plus any already-applied reviewed doc edits selected alongside them (one commit, or one per batch sequentially; subjects name the fixes). Re-resolve the evidence for the new head once (the brief's stale-head row: prior evidence is stale; the local command executes only on a fallback/opt-out resolution). Before the push, run `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base origin/<baseRefName>` (no `--check`); a `restored` or `(marked shipped)` commit rides the wave's single push and the pushed SHA becomes the assessed head under the course's-own-push rule in `### Compare-and-swap`. Print its stdout in the re-rendered report's `## Evidence`. On green, push once - gate and push are per-wave invariants, never per-fix or per-batch. On red, do not push: leave the commit(s) local, re-render with the unresolved `P#`s still open, and warn that unpushed fix commits sit in the worktree exactly like unpushed doc edits (per `### Teardown`).
+Once every dispatched or inline batch returns, commit the golden course as one local commit set - the code fixes plus any already-applied reviewed doc edits selected alongside them (one commit, or one per batch sequentially; subjects name the fixes). Re-resolve the evidence for the new head once (the brief's stale-head row: prior evidence is stale; the local command executes only on a fallback/opt-out resolution). On green, push once - gate and push are per-wave invariants, never per-fix or per-batch. On red, do not push: leave the commit(s) local, re-render with the unresolved `P#`s still open, and warn that unpushed fix commits sit in the worktree exactly like unpushed doc edits (per `### Teardown`).
 
 Doc fixes (`push-docs` alone) follow the same rule: stage and commit (subject names what is documented), re-run the gate, and push only on green. Execute reviews, replies, and tracker actions via `gh pr review` / `gh api` / the tracker tool, non-interactively, with the drafted payload for the selected IDs.
 
 ### Merge course
 
-Merge always executes as `gh pr merge --match-head-commit <assessed-sha>`. Push and merge are never bundled into one selection, with one scoped exception: the selected merge course first runs the salvage (no `--check`) via `node <bin>/gauntlet-telemetry-salvage.mjs --worktree <provisioned path> --base origin/<baseRefName>`. `present` -> merge as-is. `restored <path> from <sha>` -> push that single `telemetry: restore` commit as part of this course, re-fetch `headRefOid`, and pass the new SHA to `--match-head-commit`. A line ending `(marked shipped)` (`present` or `restored`) is handled the same way: push that single `telemetry:` commit, re-fetch `headRefOid`, and pass the new SHA. `restore failed` -> merge proceeds, the reason is printed, and the follow-up names recovery from the PR head ref. A merge selection while any precondition (SKILL.md `## Verdict`) fails is refused, naming the failing precondition, and the menu re-renders - never a dead end, never a silent merge.
+Merge always executes as `gh pr merge --match-head-commit <assessed-sha>`. Push and merge are never bundled into one selection. A merge selection while any precondition (SKILL.md `## Verdict`) fails is refused, naming the failing precondition, and the menu re-renders - never a dead end, never a silent merge.
 
 ### Re-render
 

package/skills/gauntlet-performance/SKILL.md

@@ -18,7 +18,7 @@ The CLI parses and aggregates; you reason. Never open a telemetry YAML record yo
 
 ## Read the digest
 
-`runs` has one row per record; `shipped*` marks a truncated run (no ship phase recorded - salvage stamped it at landing; its `wall` is `-` and it feeds no aggregate). `by version` groups by pi-gauntlet version: `n` counts every row, `shipped` counts the rows behind the p50/max columns. `grants` is `fix_round_grants` - the fix-round proxy (human-granted extra review rounds); schema 1 has no code-review round count.
+`runs` has one row per record; `shipped*` marks a truncated run (no ship phase recorded - an older salvage stamped it at landing; its `wall` is `-` and it feeds no aggregate). `by version` groups by pi-gauntlet version: `n` counts every row, `shipped` counts the rows behind the p50/max columns. `grants` is `fix_round_grants` - the fix-round proxy (human-granted extra review rounds); schema 1 has no code-review round count.
 
 ## Reply - exactly this, in this order
 

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

@@ -53,7 +53,7 @@ Example appended block (the fence is documentation; the brief carries no fence):
 ## Process state
 
 Phases:
-  ⊘ brainstorm (resume: pasted brief)
+  ⊘ brainstorm (resume: <spec path>)
   ⊘ plan (resume: pasted brief)
   → implement(W2)
   ○ verify
@@ -117,21 +117,25 @@ Facts that fix the order (from the extensions):
 - `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">`.
+Per-stage call table, keyed by the brief's active phase (`→`). Use
+`R = resume: <brief file or "pasted brief">` for plan/implement/verify skips and
+`S = resume: <spec path>` for brainstorm skips. Resolve `<spec path>` to the absolute
+path of the single `*.md` spec added after base in the worktree under `flowGuards.specDirs`
+(as enumerated in `reconstruction.md`, "Candidates"). Zero specs -> stop; more than
+one -> human picks.
 
 | 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` |
+| plan | `start brainstorm`; `skip brainstorm S`; `start plan`; `substep` if shown |
+| implement | `start brainstorm`; `skip brainstorm S`; `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
+`planPath` (implement onward): 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.