pi-gauntlet 5.2.2 → 5.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v5.3.0 - 2026-09-04
+
+- `chase-bug`: the real-bug verdict menu gains a fourth row, "Implement hotfix now", for small, evidenced, urgent fixes - a middle ceremony tier between the trivial carve-out and the full gauntlet. It hands off to the new companion `skills/chase-bug/hotfix.md`: dedicated `hotfix/<slug>` worktree, one implementer (TDD), one code review as the last mutation gate, an advisory conformance pass, then an unpushed squash commit on the default branch with guaranteed worktree/branch cleanup (or a PR when the pick says "as a PR"). Three safety invariants (no schema/persistence change, no public-contract change, one-commit rollback) gate the row's availability; three judgment predicates steer `[recommended]`. Triage itself stays read-only; the row is reachable only through the verdict menu. Zero changes to finishing, SDD, verification, extensions, or ci.mjs. Spec: `doc/specs/2026-09-03-chase-bug-hotfix.md`.
+
+## v5.2.3 - 2026-09-01
+
+- Isolated `subagent` dispatch examples now mint an OS-temp report directory and use absolute `output:` paths, preventing reports from being captured in and deleted with throwaway worktrees. The parallel-dispatch Output capture guidance now distinguishes that isolated failure mode from non-isolated shared-working-tree commit/overwrite risk. Fixes #23. Spec: `doc/specs/2026-09-01-gh-23-absolute-report-paths.md`.
+
 ## v5.2.2 - 2026-09-01
 
 - `linear` skill: the once-per-session `linearis issues usage` sweep no longer requires authentication. `usage` prints local help and makes no API call, so gating it on `auth status` skipped the cheap staleness check exactly when the agent was already degraded; it now runs whenever the binary is present. Also drops a dead "or the MCP path is in use" skip clause - the sweep sits inside the present-binary branch, and MCP is the fallback only when the binary is missing. Prose only, no code or config surface. Follow-up to #22; spec `doc/specs/2026-09-01-gh-22-linear-cli-verification.md` amended to match.

package/README.md

@@ -35,7 +35,7 @@ pi-gauntlet's only hard dependency is pi-cohort - every gate that dispatches a r
 
 Concretely, one change through the gauntlet:
 
-0. *(Optional)* Before there's even a spec, `/skill:shape-ticket` can create or repair a single tracker issue - shaping a raw ask into a Context/Problem/Idea/Acceptance Criteria ticket, gated by an AC integrity check, a cheap council roast, and one human-confirmed write that may include one optional gated Reporter-note comment. A failed roast is retried once, then surfaced inline at the gate if it fails again. It's a tool, not a phase: no worktree, no plan/phase tracker, runs from any repo state. It never activates on its own (`disable-model-invocation: true`) - invoke it explicitly. Similarly, `/skill:chase-bug` triages a raw bug report into an evidenced verdict - and can hand off to shape-ticket or brainstorming - before any spec exists.
+0. *(Optional)* Before there's even a spec, `/skill:shape-ticket` can create or repair a single tracker issue - shaping a raw ask into a Context/Problem/Idea/Acceptance Criteria ticket, gated by an AC integrity check, a cheap council roast, and one human-confirmed write that may include one optional gated Reporter-note comment. A failed roast is retried once, then surfaced inline at the gate if it fails again. It's a tool, not a phase: no worktree, no plan/phase tracker, runs from any repo state. It never activates on its own (`disable-model-invocation: true`) - invoke it explicitly. Similarly, `/skill:chase-bug` triages a raw bug report into an evidenced verdict - and can hand off to shape-ticket, brainstorming, or a bounded hotfix - before any spec exists.
 1. You describe the change. **`brainstorming`** sets up an isolated worktree, explores the codebase, and turns your description into a written spec. A multi-model critique runs on it automatically. If the spec replaces a known prior spec, brainstorming marks the predecessor with a `> **Superseded by:**` banner under its title (default format, syntax overridable via `.pi/gauntlet-overrides.md`; event-driven only — gauntlet never sweeps historical specs). **You read and approve the spec - human gate 1.** No implementation code exists yet.
 2. **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files.
 3. **`subagent-driven-development`** executes the plan one task at a time, each in a fresh subagent, behind spec-compliance review then code-quality review. TDD-locked: red, green, refactor.
@@ -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/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 - run it with `/skill:chase-bug`.
+- **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`.
 - **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. phase-tracker also registers plan_check, a deterministic plan linter (8 mechanical plan-vs-spec checks) whose pass stamp gates implement-start inside a gauntlet flow. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
@@ -89,7 +89,7 @@ pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this
 
 **Use it** for any change with more than one moving part: a feature, a refactor across files, anything where "what did we actually agree to build" matters by the time it's done.
 
-**Don't use it** for a one-line fix, a typo, or a throwaway spike you're going to discard. The gates have real overhead - a spec, a plan, a conformance check - and that overhead isn't worth paying for a change trivial enough to just make.
+**Don't use it** for a one-line fix, a typo, or a throwaway spike you're going to discard. The gates have real overhead - a spec, a plan, a conformance check - and that overhead isn't worth paying for a change trivial enough to just make. Between that carve-out and the full pipeline sits one middle tier: `chase-bug`'s hotfix row - a small, evidenced, urgent fix landed as an unpushed squash, entered only through the triage verdict menu.
 
 ## Requirements
 

package/package.json

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

package/skills/chase-bug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chase-bug
-description: Use when a human hands you a bug report to triage - a Slack paste, tracker ticket, GitHub issue, or described symptom - and the goal is an evidenced verdict (real bug, not-a-bug, cannot reproduce, already fixed or reported), not a fix.
+description: Use when a human hands you a bug report to triage - a Slack paste, tracker ticket, GitHub issue, or described symptom - and the goal is an evidenced verdict (real bug, not-a-bug, cannot reproduce, already fixed or reported); triage itself never fixes - a real-bug verdict may hand off to a bounded hotfix after the menu.
 disable-model-invocation: true
 ---
 
@@ -8,13 +8,16 @@ disable-model-invocation: true
 
 ## Overview
 
-Triage a bug report to an evidenced verdict, never a fix.
+Triage a bug report to an evidenced verdict. Triage never
+fixes; a real-bug verdict may hand off to a bounded hotfix (hotfix.md) after
+the menu.
 
 ## Boundaries
 
 - Reads: anything - code, history, tracker, origin text.
 - Writes: `$TMPDIR` scratch only (repro captures, notes), plus at most one gated push to the
-  origin's response channel at the very end.
+  origin's response channel at the very end; after a valid hotfix pick: the hotfix
+  worktree and one default-branch squash commit, per hotfix.md.
 - Does NOT: touch tracked files; touch tracker state (never closes, relabels, or
   reassigns an existing issue).
 - The zero-mutation invariant below mechanically enforces tracked-file immutability
@@ -25,7 +28,8 @@ Triage a bug report to an evidenced verdict, never a fix.
 
 ## Hard constraint
 
-**No verdict without evidenced root cause; no fix, ever.** (write surface: see
+**No verdict without evidenced root cause; no fix during
+triage. After a valid hotfix pick, writes follow hotfix.md.** (write surface: see
 Boundaries; enforcement: see the zero-mutation invariant below.)
 
 The invariant is baseline-relative, checked at three points. Never revert
@@ -41,17 +45,24 @@ pre-existing work - only ever revert damage this skill caused.
    rendering the summary). Re-run the same command and confirm it still matches
    the baseline.
 
+**Handoff check** (hotfix row only). Immediately before handing off to
+`hotfix.md`, run the same command on the primary checkout and require it to
+match the baseline. Checkpoint 3 still runs at skill end, on the primary
+checkout: a landed squash
+commit and a restored branch leave tracked porcelain clean, so the invariant
+holds literally on both exits.
+
 ## When to Use
 
 - A human pastes a bug report (Slack message, tracker ticket, GitHub issue, plain
   description of broken behavior) and wants to know whether it is real.
 - The ask is "is this a bug" / "can we reproduce this" / "what's causing this",
   not "fix this".
+- An evidenced, urgent "fix this" request also enters
+  here - triage stops at the menu, where the hotfix row is offered.
 
 ## When NOT to Use
 
-- The report already has an evidenced root cause and the ask is to implement a
-  fix - exit into `/skill:brainstorming` directly.
 - The item is an already-shaped ticket ready for implementation, not a report
   needing triage.
 
@@ -153,33 +164,64 @@ Render **only the matching action set** - never merge real-bug and negative-verd
 menus into one list. The human may **overrule the verdict in prose** - that is a
 change request, not a menu row.
 
-**Real bug** - three actions (all rendered unless noted), exactly one tagged
-`[recommended]`:
+**Real bug** - four actions (all rendered unless noted), exactly one tagged
+`[recommended]`. Untracked origin:
 
 ```
-1. [ ] File a ticket - one /skill:shape-ticket create-mode invocation, seeded
-       with this evidence.
+1. [ ] File a ticket - /skill:shape-ticket, seeded with this evidence.
 2. [ ] Brainstorm now - /skill:brainstorming with this evidence as the seed.
-       Handoff happens AFTER gate 2 (step 5).
+3. [ ] Implement hotfix now - follow hotfix.md; add "as a PR" for a PR.
+4. [ ] Respond to reporter only.
+```
+
+Tracker/GitHub origin (ticket row omitted as today, renumbered):
+
+```
+1. [ ] Brainstorm now - /skill:brainstorming with this evidence as the seed.
+2. [ ] Implement hotfix now - follow hotfix.md; add "as a PR" for a PR.
 3. [ ] Respond to reporter only.
 ```
 
-For unaddressable origins, action 3 reads `Finish with rendered summary`
-instead of "Respond to reporter only", and action 2's handoff happens after
-the rendered summary instead of gate 2. Exactly one rendered action still
-carries `[recommended]`.
+Unaddressable variants adjust the last row's label exactly as today. Exactly
+one `[recommended]` preserved. The eligibility line renders under the menu:
+`eligible` or `not eligible: <predicate>`, from the predicate evaluation below.
 
-If the origin is itself a tracker/GitHub ticket, it's already tracked: omit
-action 1 and renumber the remaining two as 1 (Brainstorm now) and 2 (Respond
-to reporter only). Exactly one rendered action still carries `[recommended]`.
+For unaddressable origins, the last action reads `Finish with rendered summary`
+instead of "Respond to reporter only", and the Brainstorm handoff happens after
+the rendered summary instead of gate 2.
 
-Heuristic for the `[recommended]` tag: pressing (user-facing break, data loss,
-security) or trivially fixable -> recommend brainstorm now; real but deferrable
--> recommend file a ticket; blocked on another party (needs reporter input,
-upstream fix, another team) -> recommend respond-only (rendered as "Finish with
-rendered summary" for unaddressable origins). Root cause found but the
-fix cost is unclear still stays a **real-bug** verdict - state the uncertainty
-plainly in the fault story, do not downgrade the verdict to hedge on cost.
+**Predicates and row availability.** Evaluate the six predicates in
+`hotfix.md` once, here, from the root cause - a prediction of the fix shape
+(read-only judgment). A failed safety invariant (1-3) renders the row as
+`Implement hotfix now - unavailable: <invariant>`: never pickable, never
+`[recommended]`; a pick of it is a change request. Judgment predicates (4-6)
+only steer `[recommended]` and the eligibility line.
+
+Heuristic for the `[recommended]` tag - rows top-down, first match wins:
+
+| Situation | `[recommended]` |
+|---|---|
+| Pressing or trivially fixable, all predicates pass | Hotfix now |
+| Pressing, any predicate fails | Brainstorm now |
+| Trivially fixable, any predicate fails | Brainstorm now |
+| Real but deferrable | File a ticket (tracker-origin: respond-only) |
+| Blocked on another party | Respond-only |
+
+Respond-only renders as "Finish with rendered summary" for unaddressable
+origins. Root cause found but the fix cost is unclear still stays a
+**real-bug** verdict - state the uncertainty plainly in the fault story, do
+not downgrade the verdict to hedge on cost.
+
+**Hotfix handoff.** On a hotfix pick, write the handoff record to
+`$TMPDIR/hotfix-<slug>.md`: `delivery-mode` (`squash`, or `pr` when the pick
+says "as a PR"); the evidence pack (fault story; trigger, observed, and
+expected values from Phase 1; repro command; `file:line`; falsification
+result); `slug` (kebab-case, from the symptom); origin type and response
+target (step 1); the predicate evaluation. Run the handoff check (see the
+zero-mutation invariant), then follow `hotfix.md`, which reads only this
+record. On a hotfix abort, `hotfix.md` runs its baseline re-check and this
+menu re-renders - the same gate, re-fired: with the hotfix row when the abort
+created nothing, without it otherwise.
 
 **Negative verdicts** - exactly five, each with its own named citation source:
 
@@ -236,6 +278,10 @@ any handoff:
   response citing the new ticket link -> gate 2 -> done.
 - Brainstorm now chosen -> draft the response first ("confirmed, investigating
   now - fix to follow") -> gate 2 -> **then** hand off to `/skill:brainstorming`.
+- Hotfix now chosen -> hand off to `hotfix.md` first; on completion, draft the
+  response citing `fixed in <SHA>` or the PR link -> gate 2 (`send it`) -> done.
+  Gate 2 fires once. On abort, `hotfix.md` returns to the step-4 menu; step 5
+  then runs for the new pick, the draft citing the abort reason.
 - Respond-only, or any negative verdict -> draft -> gate 2 -> done.
 
 **Draft template:**
@@ -298,6 +344,9 @@ action renders the verdict as a **summary to the human**, then the skill ends
   link.
 - Brainstorm now chosen -> render the summary -> **then** hand off to
   `/skill:brainstorming`.
+- Hotfix now chosen -> hand off to `hotfix.md`; on completion render the
+  summary citing `fixed in <SHA>` or the PR link -> done. On abort, return to
+  the step-4 menu.
 - Finish with rendered summary chosen -> render the summary -> done.
 
 **Summary template** (same four fields as the draft - the difference is
@@ -319,7 +368,7 @@ rendered is out of skill scope - the skill has ended.
 
 | Verdict | Citation source | Response next-step |
 |---|---|---|
-| Real bug | Falsification test run + passed | Ticket link, fix branch, or ack |
+| Real bug | Falsification test run + passed | Ticket link, squash SHA, fix branch, or ack |
 | `not-a-bug` | Contract satisfied (spec/schema/API doc) | Explain the contract |
 | `intended-behavior` | Decision record (design doc/ADR/commit) | Point to the decision |
 | `cannot-replicate` | Phase 1 repro attempts, missing input named | Ask reporter for missing input; offer discovery ticket |
@@ -337,11 +386,14 @@ falls through to the 404 handler.
 Proof: `curl /widgets/` -> 404 | src/router.ts:88 | expected match, got none
 
 1. [ ] File a ticket - /skill:shape-ticket, seeded with the above.
-2. [x] Brainstorm now - user-facing 404 on a common URL shape. [recommended]
-3. [ ] Respond to reporter only.
+2. [ ] Brainstorm now - /skill:brainstorming with the above as the seed.
+3. [x] Implement hotfix now - follow hotfix.md; add "as a PR" for a PR. [recommended]
+4. [ ] Respond to reporter only.
+
+eligible - all predicates pass
 ```
 
-(The example assumes an addressable origin - action 3's label is the addressable one.)
+(The example assumes an addressable origin - action 4's label is the addressable one.)
 
 **Negative-verdict example** (citation-source contrast):
 
@@ -361,7 +413,7 @@ nested resources" (the decision that made it so).
 
 | Excuse | Reality |
 |---|---|
-| "Trivial fix, faster to just do it" | Fixing during triage is the one thing this skill forbids - hand it to the human at the menu, always |
+| "Trivial fix, faster to just do it" | Fixing during triage is forbidden - the hotfix row after the menu is the sanctioned path |
 | "Root cause is obvious, skip falsification" | Obvious and evidenced are different things - run the test or report it blocked |
 | "Reporter is waiting, skip the gate" | The gate is what makes the response trustworthy - urgency is not a bypass |
 | "I already know there's no prior report" | A guess isn't a search - use the ladder or declare it unreachable |

package/skills/chase-bug/hotfix.md

@@ -0,0 +1,198 @@
+# Hotfix (chase-bug supplementary)
+
+Consumed only by `SKILL.md` in this directory, at the real-bug menu handoff. Input:
+the handoff record at `$TMPDIR/hotfix-<slug>.md` - read nothing else about the bug.
+Automatic end to end: the menu pick was the consent. The only human gate left is
+chase-bug's `send it`, reached in step 10 below.
+
+## Boundaries
+
+- Reads: anything.
+- Writes: the hotfix worktree; exactly one squash commit on `<default>`, made in the
+  primary checkout with a clean index, `<orig-branch>` restored after; `$TMPDIR`.
+- Does NOT: run tests or create files in the primary checkout; push without an
+  explicit request; touch tracker state; commit on the source checkout during setup;
+  touch pre-existing dirt or any resource this run did not create.
+
+## Ownership
+
+Two flags, `created-worktree` and `created-branch`, set only when `git worktree add`
+succeeds (it creates both). Every destructive command below is gated on its flag.
+
+## Procedure
+
+1. **Read the record; print the eligibility line.** Reprint the menu-time
+   evaluation verbatim: `eligible` or `not eligible: <predicate>`. Never
+   re-derive, never block.
+2. **Resolve before mutating.** `SCOPED_TEST_COMMANDS`: the gauntlet overrides
+   file's verification section (`## verification-before-completion`, or a section
+   matching the verification topic), else `AGENTS.md` or the project's documented
+   test command. The full project test target is acceptable. Add the record's repro
+   command when present. No exact command -> abort (pre-land). Draft the implementer
+   task text from the record; not writable -> abort (pre-land). Nothing exists yet.
+3. **Worktree.** From the primary checkout:
+
+   ```bash
+   PRIMARY_ROOT=$(git rev-parse --show-toplevel)
+   DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD) && DEFAULT=${DEFAULT#origin/}
+   BASE_SHA=$(git rev-parse "$DEFAULT")
+   ORIG_BRANCH=$(git branch --show-current)
+   git status --porcelain > "$TMPDIR/hotfix-<slug>.baseline"
+   ```
+
+   Abort (pre-land, nothing created) when: `git rev-parse --git-dir` differs from
+   `git rev-parse --git-common-dir` (inside a linked worktree); `DEFAULT` empty
+   (never guess a squash target); `ORIG_BRANCH` empty (detached HEAD); `git status
+   --porcelain --untracked-files=no` non-empty; `git check-ignore -q .worktrees/`
+   fails (never commit on the source checkout); `git show-ref --verify -q
+   refs/heads/hotfix/<slug>` succeeds or `.worktrees/hotfix/<slug>` exists (never
+   reuse, never force); `git worktree add` itself failing (creation failure).
+
+   ```bash
+   git worktree add ".worktrees/hotfix/<slug>" -b "hotfix/<slug>" "$DEFAULT"
+   ```
+
+   Success sets both flags. Run the project's dependency install inside the
+   worktree. Every dispatch below: `cwd` = the worktree path, the record path in the
+   task text, `output:` (when used) an absolute `$TMPDIR` path.
+4. **Implement.** One `implementer`, fork context:
+
+   > Read `$TMPDIR/hotfix-<slug>.md`; the evidence pack is also inlined here:
+   > <evidence pack>. The evidence pack replaces plan and spec; do
+   > not report BLOCKED for a missing plan. TDD: write the regression test, run it,
+   > confirm it fails, then the minimal fix (dependency-bump fallback: the repro
+   > re-run is the regression evidence). SCOPED_TEST_COMMANDS: <commands>. Commit on
+   > `hotfix/<slug>` before reporting. End with the SDD status line verbatim.
+
+   `DONE` -> step 5. `DONE_WITH_CONCERNS` -> step 5 unless a concern names a safety
+   invariant -> abort. `NEEDS_CONTEXT` or `BLOCKED` -> abort. A regression command
+   named in the report joins `SCOPED_TEST_COMMANDS` only if it uses the resolved
+   command's runner.
+5. **Test.** Run `SCOPED_TEST_COMMANDS` in the worktree. Red -> one implementer
+   retry -> red -> abort.
+6. **Verify (advisory).** One fresh `conformance-reviewer`. Its entire origin, in
+   the task text, located as `prompt`:
+
+   > R1: the trigger `<trigger>` now yields `<expected>` (was `<observed>`).
+   > R2: regression evidence exists (test or repro re-run).
+   > R3: the diff stays inside the envelope: files implementing the mechanism at
+   > the recorded `file:line`, the regression test, and (dependency exception)
+   > manifest + lockfile.
+
+   Parent filter: only rows located as `prompt` count; a row sourced from a spec
+   file or ticket is not-a-gap. Real gaps -> one implementer round -> re-run step
+   5 -> no second audit; unfixable -> abort. Dispatch failure or malformed output
+   -> note it, continue.
+7. **Review - last mutation gate.** One fresh `code-reviewer` over
+   `<base-sha>..HEAD` in the worktree. Task text: the record path,
+   `SCOPED_TEST_COMMANDS`, invariants 1-3 and predicates 4-6 as named review items
+   (a predicate miss is Moderate unless it trips an invariant). `SHIP` -> step 8.
+   `FIX_FIRST` -> one implementer round fixing every Critical and Moderate ->
+   re-run step 5 -> one re-review; `SHIP` -> step 8, else abort. `REJECT` or any
+   invariant violation -> abort, no round. Dispatch failure or malformed output ->
+   one redispatch, then abort.
+8. **Finish.** Branch on the record's `delivery-mode`: `squash` -> squash path;
+   `pr` -> PR path. Every command from `PRIMARY_ROOT`. Squash path, by state:
+
+   ```bash
+   cd "$PRIMARY_ROOT"
+   [ -z "$(git status --porcelain --untracked-files=no)" ] || land_abort
+   [ "$(git rev-parse "$DEFAULT")" = "$BASE_SHA" ] || land_abort   # base moved: never touch <default>
+   git checkout "$DEFAULT" || land_abort                            # pre-squash ends here
+   git merge --squash "hotfix/<slug>" || { git reset --hard "$BASE_SHA"; land_abort; }
+   git diff --cached --quiet && { git reset --hard "$BASE_SHA"; land_abort; }   # empty squash
+   git commit -m "fix: <slug>" -m "<fault story>" || { git reset --hard "$BASE_SHA"; land_abort; }
+   [ "$(git rev-parse HEAD^{tree})" = "$(git rev-parse "hotfix/<slug>^{tree}")" ] \
+     || { git reset --hard "$BASE_SHA"; land_abort; }              # proven; never reset after this line
+   SHA=$(git rev-parse HEAD)
+   [ "$ORIG_BRANCH" = "$DEFAULT" ] || git checkout "$ORIG_BRANCH"  # failure: report, commit stays
+   git worktree remove --force ".worktrees/hotfix/<slug>" && git worktree prune \
+     && git branch -D "hotfix/<slug>"                               # failure: keep commit, report residual
+   ```
+
+   `git branch -D` is forced by construction: a squash commit never has the branch
+   tip as ancestor, so `-d` always refuses; the proven tree is the loss guard. The
+   commit stays **unpushed**. Report: `$SHA`; revert line `git checkout <default>
+   && git reset --hard <base-sha>` (unpushed) or `git revert <sha>` (after any
+   push); `git status --porcelain` diff against the baseline (expected none); a
+   push nudge.
+
+   PR path, cwd = the worktree: `git push -u origin hotfix/<slug>` - failure ->
+   report branch + worktree path, no URL, preserve. `gh pr create --base <default>
+   --head hotfix/<slug>` - `gh` missing or failing after one retry -> report the
+   pushed branch and compare URL. Worktree and branch preserved; print the closing
+   line.
+9. **Cleanup evidence.** Squash exit and pre-land aborts: `git worktree list`
+   without the hotfix entry; `git branch --list hotfix/<slug>` empty; porcelain
+   delta vs baseline none. PR exit and land-stage aborts: both present, plus
+   `git worktree remove --force .worktrees/hotfix/<slug> && git branch -D hotfix/<slug>`.
+10. **Response.** chase-bug step 5 rules apply unchanged: addressable -> draft
+    citing `fixed in <SHA>` or the PR link -> `send it`; unaddressable -> summary.
+    Abort never reaches this step - it returns to the menu.
+
+## Eligibility predicates
+
+Evaluated once by `SKILL.md` at menu time from the root cause; re-checked against
+the diff in step 7.
+
+Safety invariants (row availability):
+
+1. No schema, migration, or persistence change.
+2. No public API, contract, or config-shape change.
+3. Rollback is reverting one commit - no data or state side effects.
+
+Judgment predicates (`[recommended]` only; Moderate review items):
+
+4. Existing code only - new files limited to the regression test.
+5. Dependencies unchanged, one exception: a patch/minor bump whose upstream issue or
+   changelog names the symptom, diff = manifest + lockfile, no call-site change.
+   Replacement, major/breaking upgrade, new dependency -> fails.
+6. Regression evidence writable in the existing harness (bump fallback: the repro).
+
+## Abort
+
+Both classes end with the baseline re-check, then chase-bug step 4 re-renders.
+
+**Pre-land** (steps 2-7): unresolvable commands or task text; setup precondition
+unmet; `NEEDS_CONTEXT`/`BLOCKED` or a concern naming an invariant; red after retry;
+unfixable conformance gap; review `REJECT`, invariant violation, or a non-`SHIP`
+re-review.
+
+```bash
+[ "$created_worktree" = 1 ] && git worktree remove --force ".worktrees/hotfix/<slug>"
+git worktree prune
+[ "$created_branch" = 1 ] && git branch -D "hotfix/<slug>"
+```
+
+Nothing else is touched. The re-rendered menu keeps the hotfix row when neither
+flag was set, omits it otherwise.
+
+**Land-stage** (step 8 before *proven*, after review `SHIP`): base moved, checkout failure, empty
+squash, merge/commit failure, tree mismatch. `git reset --hard <base-sha>` only when
+this run moved `<default>` (squash-applied or later) and `<default>` is checked
+out (the step 8 lines do
+exactly that); on base moved `<default>` is never touched and both SHAs are
+reported. Restore `<orig-branch>`. Preserve worktree and branch (reviewed work).
+Report path, tip SHA, closing line. The menu re-renders without the hotfix row.
+
+**Baseline re-check**: `git status --porcelain --untracked-files=no` matches the
+triage baseline; full porcelain delta reported; `<default>` == `<base-sha>` asserted
+only when this run touched `<default>`. Pre-existing dirt is never touched.
+
+## Harness fallback
+
+No `subagent` tool and no personas (the Claude Code marketplace ships `agents: []`):
+run the duties inline, same order. Write the failing regression test, confirm red,
+minimal fix, confirm green, commit on `hotfix/<slug>`. Self-review the diff against
+the record, invariants 1-3, predicates 4-6. Run `SCOPED_TEST_COMMANDS`. Apply the
+abort classes as written. Finish and report per steps 8-9.
+
+## Red Flags - STOP
+
+- Any mutation before every step 3 precondition passes
+- Reusing or force-replacing an existing `hotfix/<slug>` branch or path
+- `git reset --hard` after *proven*, on `<orig-branch>`, or inside the worktree
+- Re-running tests in the primary checkout
+- Merging onto a moved base
+- Landing a diff the last review did not see
+- Pushing without an explicit request

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

@@ -183,7 +183,11 @@ Parallel dispatch rides on the `subagent` tool (the pi-cohort package). Mechanic
 - **Filesystem isolation** — `worktree: true` runs each task in its own git worktree so concurrent edits can't collide. Requires clean git state; each task's diff returns separately for you to integrate. Omit it for read-only investigations.
 - **Worktree base / `cwd`** — under `worktree: true` the base commit is `HEAD` resolved from the **top-level `cwd`**, which defaults to the orchestrator's process cwd. When you orchestrate from inside a git worktree, pass that worktree's absolute path as the top-level `cwd`, or children branch from the wrong checkout. Don't set per-task `cwd` with `worktree: true` — it must equal the shared cwd or the run errors.
 - **Agent choice** — `worker` is the pi-cohort builtin generalist. Use a persona (`implementer`, `code-reviewer`) when you want its system prompt and tool profile. Persona frontmatter (tools, thinking, context) is fixed; only `model`, `task`, `output`, `reads`, `progress`, `skill` are callable per task.
-- **Output capture** — `output: "<file>"` writes a task's summary to a file instead of inline; add `outputMode: "file-only"` for large results.
+- **Output capture** - `output: "<file>"` writes a task's summary to a file instead of inline; add `outputMode: "file-only"` for large results. When a batch uses `worktree: true`, each `output:` path must be absolute and outside every isolated checkout; a relative report is captured as helper work and then deleted with the checkout. In a non-isolated batch, a relative report lands in the shared working tree and risks being committed or overwritten by a later task.
+
+```bash
+REPORT_DIR=$(mktemp -d)
+```
 
 ```ts
 subagent({
@@ -191,9 +195,9 @@ subagent({
   worktree: true,        // isolate edits; omit for read-only investigations
   concurrency: 3,
   tasks: [
-    { agent: "worker", task: "Fix + explain failures in src/a.test.ts", output: "a.md" },
-    { agent: "worker", task: "Fix + explain failures in src/b.test.ts", output: "b.md" },
-    { agent: "worker", task: "Fix + explain failures in src/c.test.ts", output: "c.md" },
+    { agent: "worker", task: "Fix + explain failures in src/a.test.ts", output: "<REPORT_DIR>/a.md" },
+    { agent: "worker", task: "Fix + explain failures in src/b.test.ts", output: "<REPORT_DIR>/b.md" },
+    { agent: "worker", task: "Fix + explain failures in src/c.test.ts", output: "<REPORT_DIR>/c.md" },
   ],
 })
 ```

package/skills/subagent-driven-development/SKILL.md

@@ -185,6 +185,10 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 **Set `cwd` to your worktree — resilience-critical.** This whole workflow runs *inside* a worktree, but the `subagent` tool resolves the worktree base from the **top-level `cwd`**, which defaults to the orchestrator's process cwd — the *primary* checkout (usually `main`), not the worktree. Omit `cwd` and `worktree: true` branches every child from the primary checkout's HEAD: the children never see your spec, plan, or prior-wave commits, and integration runs against the wrong baseline. Pass the worktree's absolute path as the top-level `cwd`. Do **not** set per-task `cwd` under `worktree: true` — pi-cohort requires it to equal the shared cwd and errors otherwise. (Clean-tree is enforced here too — `resolveRepoState` rejects a dirty tree — which is why each wave commits before the next.)
 
+```bash
+REPORT_DIR=$(mktemp -d)
+```
+
 ```ts
 subagent({
   context: "fresh",
@@ -193,8 +197,8 @@ subagent({
   concurrency: 4,        // default; cap = wave size
   tasks: [
     // do NOT set per-task cwd under worktree:true — it must equal the top-level cwd or the run errors
-    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "wave1-task1.md" },
-    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "wave1-task2.md" },
+    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "<REPORT_DIR>/wave1-task1.md" },
+    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "<REPORT_DIR>/wave1-task2.md" },
   ],
 })
 ```