pi-gauntlet 5.14.0 → 5.15.0

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.15.0 - 2026-09-20
+
+- New human-only `/skill:gauntlet-handoff`: invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`; default key = the run worktree's branch, `/` flattened to `-`, file `<tmpdir>/pi-handoff/<key>.md`) and appends the gauntlet `## Process state` section in the layout fixed by `skills/gauntlet-resume/reference/brief-contract.md` (`## Producers`); stops instead of writing when the skill is absent or the installed cohort still writes that section itself. `/skill:gauntlet-resume` with no arguments lists the briefs under `<tmpdir>/pi-handoff/` for a human pick, and a token that looks like a path is always a brief file (missing -> stop, never a scan). `scripts/ci.mjs` gains a drift lint (`scripts/brief-contract-lint.mjs`): the three process-state grammar lines may appear only in the contract file, both skills must cite it, and gauntlet-handoff may not carry cohort's core headings. Requires pi-cohort >= the release shipping [pi-cohort #18](https://github.com/jjuraszek/pi-cohort/issues/18) (exact version filled at release). (#40)
+
 ## v5.14.0 - 2026-09-20
 
 - Specs carry the ticket's acceptance criteria verbatim in a required `## Acceptance criteria` section, one disposition per row (`in-scope`, `deviates: <why>`, `deferred: <where>`, `venue: <env> - <observation>`; `none - <reason>` when there is no ticket or no ACs). `brainstorming` extracts heading-scoped rows and lints the section's presence, `gatherer` quotes the raw rows, `spec-council-member` flags dropped/reworded rows and invalid deferrals, `conformance-reviewer` and `conformance-check` read the section as origin (`in-scope`/`venue:` rows are requirements, `venue:` observations never block), `writing-plans` tables only `in-scope`/`venue:` rows, and `finishing-a-development-branch` lists `venue:`/`deferred:` rows in the PR body. `scripts/ci.mjs` pins the new tokens. (#41)

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:
 
-- **19 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). Six more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-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>]`.
+- **20 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Seven more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`) or a bare worktree that already holds a spec, restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), never creates a worktree, and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief>] [<worktree>]`.
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
 - **4 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. `telemetry` records one committed YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - finishing and the PR gate restore a stripped record, and stamp a record left `in_progress` with no ship phase as `shipped`, with `gauntlet-telemetry-salvage` - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
@@ -77,6 +77,20 @@ pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this
 
 **Worktree contract.** pi runs in the primary checkout; the work happens in `.worktrees/<branch>`. Skills never `cd` there - the worktree path is a value from the `using-git-worktrees` report (or the handoff brief on `gauntlet-resume`), carried as dispatch `cwd: "<path>"`, as `git -C <path>`, or as `(cd "<path>" && <cmd>)` for other cwd-bound commands; the runtime extensions derive the checkout from the artifact path they act on. Requires git >= 2.31; a plain (non-colocated) jj workspace has no `.git`, so the resolver falls back to `jj root` there, reading primary-vs-workspace from `.jj/repo` (a directory in the primary checkout, a pointer file in added workspaces).
 
+## Handoff and resume
+
+`/skill:gauntlet-handoff` and `/skill:gauntlet-resume` are a pair: cohort's `handoff` skill writes the six flow-agnostic headings, gauntlet-handoff appends `## Process state`, and gauntlet-resume reads the whole brief back. Both gauntlet skills read one grammar file, `skills/gauntlet-resume/reference/brief-contract.md`; the repo validator (`scripts/ci.mjs`) fails if a grammar line appears anywhere else under `skills/`. Requires the pi-cohort release that ships [pi-cohort #18](https://github.com/jjuraszek/pi-cohort/issues/18) (the `handoff` skill); on an older pi-cohort, gauntlet-handoff stops before writing.
+
+### Smoke walkthrough (release-gated)
+
+Run by a human against the pi-cohort release that ships #18, before a pi-gauntlet release claims the pair works; record the outcome in the release commit body.
+
+1. Implement phase with tasks `complete`/`in_progress`/`pending` in a `.worktrees/<branch>` flow, session in the primary checkout: `/skill:gauntlet-handoff` writes `<tmpdir>/pi-handoff/<branch>.md` with the six core headings then `## Process state` last; a fresh session running `/skill:gauntlet-resume <path>` restores implement with the three statuses and ends `Gate history not restored; re-validating <task> before any stage advance`.
+2. Plan phase, `No plan active.`: the brief keeps that line and `Active task: none`; resume restores phase-only with no `plan_tracker init`.
+3. Hotfix context with non-pending trackers: the brief ends at `## Skills loaded`; resume takes the `chase-bug` route.
+4. Fresh session, zero arguments: the listing shows the briefs from 1-3 and a pick restores; `/skill:gauntlet-resume /nonexistent.md` stops naming that path without listing anything.
+5. Branch `hotfix/x`: the default file is `pi-handoff/hotfix-x.md` and appears in the zero-argument listing.
+
 ## Key concepts
 
 | Term | Meaning |

package/package.json

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

package/skills/gauntlet-handoff/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: gauntlet-handoff
+description: Human-only producer of a gauntlet handoff brief - invokes pi-cohort's `handoff` skill, then appends the gauntlet process-state section (phase/plan tracker status) to the brief it wrote, per the shared brief contract. Run at the end of a session whose flow a fresh session will continue with /skill:gauntlet-resume.
+disable-model-invocation: true
+argument-hint: "[--out <path> | --key <name>]"
+---
+
+> **Related skills:** Pairs with `/skill:gauntlet-resume`, the sole consumer of the brief this skill finishes. The grammar both read is `../gauntlet-resume/reference/brief-contract.md` - this file cites it and restates none of it.
+
+# Gauntlet Handoff
+
+## Overview
+
+pi-cohort's `handoff` skill writes the flow-agnostic core of a brief (six headings,
+ending at `## Skills loaded`). Only this package knows what `phase_tracker` and
+`plan_tracker` state mean, so this skill appends that state as one more section, in
+the layout fixed by `reference/brief-contract.md` (`## Producers`). Runs in the main
+loop: tracker state is extension state no subagent can read.
+
+**Announce at start:** "I'm using the gauntlet-handoff skill to write a resumable handoff brief."
+
+## Boundaries
+
+- Reads: `../gauntlet-resume/reference/brief-contract.md` in full (resolve against this
+  skill's directory) before any other action; the transcript; git metadata by path.
+- Writes: only an append to the brief cohort wrote, wherever the resolved path puts it
+  (a repository-local `--out` included). Never a second file, never the trackers, never
+  any other repository file.
+- Every STOP below prints the offending path or fact and writes nothing further.
+
+## Sequence
+
+1. **Resolve the target.**
+   - `--out` and `--key` both given -> STOP: they are exclusive in cohort's grammar.
+   - `--out <path>` -> resolve to an absolute path against the session cwd
+     (`node -p "require('path').resolve(process.argv[1])" -- "<path>"`); that is the
+     expected path and the form passed to cohort.
+   - Otherwise the key is `--key <name>` when given, else derived from the **run
+     worktree**: the path a flow skill reported as `Worktree ready at <path>` in this
+     transcript (the same evidence cohort's snapshot uses):
+
+     ```bash
+     git -C "<run worktree>" branch --show-current
+     ```
+
+     No run worktree in the transcript -> the session cwd branch:
+
+     ```bash
+     BRANCH=$(git branch --show-current)
+     DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')
+     ```
+
+     `BRANCH` empty (detached HEAD) or equal to `DEFAULT` -> STOP asking for `--key` or
+     `--out` (a default-branch key would collide across flows).
+   - A derived key has every `/` replaced by `-` (`hotfix/x` -> `hotfix-x`) so the file
+     lands flat in the default directory. A human-given `--key` is passed verbatim.
+   - Expected path = `<tmpdir>/pi-handoff/<key>.md`, `<tmpdir>` from
+     `node -p "require('os').tmpdir()"`. This is the one place this package restates
+     cohort's default-path rule; step 3 verifies it.
+2. **Invoke cohort.** `/skill:handoff --out <absolute path>` or `/skill:handoff --key <key>`,
+   exactly as resolved in step 1. The skill must be present in the session skill list
+   under `name: handoff`. Absent -> STOP: "cohort `handoff` skill not in the session
+   skill list - install or upgrade pi-cohort to the release that ships pi-cohort #18".
+   No version lookup, no fallback to the `/handoff` prompt.
+3. **Verify the file.** Expected path missing, or line 1 not starting `# Handoff:` ->
+   STOP with the expected path.
+4. **Refuse a double section.** The file already has a line matching
+   `^## Process state\s*$` -> STOP: "the installed pi-cohort still writes process state
+   itself - upgrade to the release that ships #18".
+5. **Hotfix exclusion.** `skills/chase-bug/hotfix.md` is in this session's context ->
+   append nothing; report a plain hotfix handoff and go to step 7. Checked before the
+   trackers: chase-bug never touches tracker state, and a stale armed flow appended here
+   would steer resume away from its hotfix route.
+6. **Append.** `phase_tracker({ action: "status" })`, then `plan_tracker({ action: "status" })`.
+   - No phase `in_progress` -> append nothing; say the brief is a plain handoff.
+   - A phase `in_progress` (verify or ship included - resume stops at verify on its own)
+     -> append the process-state section exactly as `## Producers` in
+     `reference/brief-contract.md` lays it out: both status outputs verbatim
+     (`No plan active.` verbatim when there is no plan), the active-task line naming
+     the first `→` task else `none`, the gate-history line. Append with a single
+     `cat >> "<expected path>" <<'EOF' ... EOF` whose body is that block.
+   - Re-read the file tail and confirm it ends with the gate-history line from the
+     contract and nothing after.
+7. **Report.** Print the path and `/skill:gauntlet-resume <path>`. When a section was
+   appended and the brief's `worktree:` field is `no`, resume's entry check 2 needs an
+   override: print `/skill:gauntlet-resume <path> <override>` where `<override>` is the
+   run worktree from step 1 when one was found, else the session checkout root,
+   `dirname "$(git rev-parse --path-format=absolute --git-common-dir)"`. If that command
+   fails (session cwd is not inside a git repository), print the one-argument form and
+   the line `No resumable worktree found - pass the worktree path as the second argument.`
+
+## Red flags - STOP
+
+- Writing the brief yourself instead of invoking `/skill:handoff` (the core headings are
+  cohort's; this skill appends one section).
+- Restating the section layout here instead of reading `reference/brief-contract.md`.
+- Appending when step 4 or step 5 fired.
+- Deriving the key from the primary checkout's branch while a run worktree exists.
+
+## 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/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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.
 disable-model-invocation: true
 argument-hint: "[<brief-file>] [<worktree-name-or-path>]"
 ---
@@ -12,7 +12,7 @@ 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 pi-cohort's `/handoff` (grammar in `reference/brief-contract.md`), or a bare
+produced by `/skill:gauntlet-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.
@@ -35,14 +35,21 @@ optional pasted text after the command line.
 
 | Form | Meaning |
 |---|---|
-| `<brief-file>` | readable file whose line 1 starts `# Handoff:` |
+| (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 | bare name resolved as `<primary>/.worktrees/<name>`, or an absolute path; must already be a git worktree |
+| `<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.
+
 ## Entry checks
 
 In order. All before any tracker mutation; entry check 1 is read-only.

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

@@ -1,9 +1,12 @@
-# Handoff brief contract (gauntlet-resume supplementary)
+# Handoff brief contract (gauntlet-resume + gauntlet-handoff 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 `812de45`).
-Cohort drift is reconciled here and nowhere else.
+Consumed by `gauntlet-resume/SKILL.md` (consumer) and `gauntlet-handoff/SKILL.md`
+(producer). Grammar lives only here; both skills cite this file and inline none of it
+(`scripts/ci.mjs` drift lint). Coupled to pi-cohort's `handoff` skill (pi-cohort #18)
+for exactly six headings - `# Handoff:`, `## Intent`, `## Repo state`, `## Decisions`,
+`## Open questions`, `## Skills loaded` - and the `## Repo state` fields. `## Process
+state` grammar and its consumer rules are owned here. Cohort drift is reconciled here
+and nowhere else.
 
 ## Brief grammar
 
@@ -24,9 +27,9 @@ Headings, fixed order. A consumer keys on headings, never prose.
 | `## 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` |
+| `## 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 a phase is `in_progress` and no hotfix flow is in context |
 
-Consumer rules (cohort): process state absent -> plain handoff (the consumer starts its
+Consumer rules: 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.
 
@@ -34,6 +37,38 @@ A brief is any text whose first line starts `# Handoff:` - a file on disk or pas
 inline. `## Repo state` is matched by prefix: `## Repo state` or
 `## Repo state: not a git repo`.
 
+## Producers
+
+`gauntlet-handoff` is the only writer of `## Process state`; it appends to the file
+cohort's `handoff` skill wrote, which ends at `## Skills loaded`. Layout, byte-exact:
+one blank line, the heading on its own line, a blank line, the `phase_tracker status`
+output verbatim, a blank line, the `plan_tracker status` output verbatim, a blank line,
+`Active task: <name|none>`, then the gate-history line - unfenced, nothing after.
+`Active task` is the first `→` task name, else `none` (also for `No plan active.`).
+
+Example appended block (the fence is documentation; the brief carries no fence):
+
+```text
+
+## Process state
+
+Phases:
+  ⊘ brainstorm (resume: pasted brief)
+  ⊘ plan (resume: pasted brief)
+  → implement(W2)
+  ○ verify
+  ○ ship
+
+Plan: 1/3 done (1 in progress, 1 pending)
+
+  ✓ [0] W1: contract
+  → [1] W2: producer
+  ○ [2] W2: consumer
+
+Active task: W2: producer
+Gate history not restored - re-validate before advancing.
+```
+
 ## Tracker output grammar
 
 Must match `formatStatus` in the phase-tracker and plan-tracker extensions.