pi-gauntlet 5.8.0 → 5.8.1

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v5.8.1 - 2026-09-17
+
+- chase-bug hotfix: the implementer proves its worktree binding first, addresses every mutating git command with `git -C`, runs with a fresh context, and the parent aborts non-destructively on any primary-checkout drift after each implementer return; `ci.mjs` asserts the guard text ([#36](https://github.com/jjuraszek/pi-gauntlet/issues/36))
+- `gauntlet-resume`: same-repository worktrees resume from a pi session launched in the primary checkout; cross-repository targets still stop, and reconstruction addresses the resolved worktree by path.
+
 ## v5.8.0 - 2026-09-17
 
 - New extension `telemetry`: records one committed YAML record per gauntlet run at `.pi/gauntlet/telemetry/<spec path>.yaml` (phase timing, model/thinking snapshots, per-persona dispatches and tokens, reviewer findings, gate and fix-round counters, plan totals, last test result, diff buckets and modified files at ship), keyed by spec path and continued across sessions; pathspec-commits the record at checkpoints; reconciles a failed ship command; freezes after squash/PR/discard. During brainstorm a `write` into a spec whose record is shipped is blocked (`edit` passes). Settings `piGauntlet.telemetry.{enabled,dir,buckets}`. (#33)

package/package.json

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

package/skills/chase-bug/hotfix.md

@@ -37,6 +37,7 @@ succeeds (it creates both). Every destructive command below is gated on its flag
    DEFAULT=$(git symbolic-ref --short refs/remotes/origin/HEAD) && DEFAULT=${DEFAULT#origin/}
    BASE_SHA=$(git rev-parse "$DEFAULT")
    ORIG_BRANCH=$(git branch --show-current)
+   ORIG_HEAD=$(git rev-parse HEAD)
    git status --porcelain > "$TMPDIR/hotfix-<slug>.baseline"
    ```
 
@@ -49,14 +50,42 @@ succeeds (it creates both). Every destructive command below is gated on its flag
    reuse, never force); `git worktree add` itself failing (creation failure).
 
    ```bash
-   git worktree add ".worktrees/hotfix/<slug>" -b "hotfix/<slug>" "$DEFAULT"
+   git worktree add "$PRIMARY_ROOT/.worktrees/hotfix/<slug>" -b "hotfix/<slug>" "$DEFAULT"
+   WORKTREE=$(git -C "$PRIMARY_ROOT/.worktrees/hotfix/<slug>" rev-parse --show-toplevel)
    ```
 
-   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:
-
+   Success sets both flags; `WORKTREE` is set only after `git worktree add`
+   succeeds - empty `WORKTREE` -> abort (pre-land, both flags set so cleanup runs)
+   - and is the literal the child is compared against - both sides come from `git
+   rev-parse --show-toplevel`, so a symlinked `.worktrees/` cannot make them
+   disagree. 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. Every implementer round - step
+   4, the step 5 retry, the step 6 gap fix, the step 7 FIX_FIRST round - is
+   `context: "fresh"` and reuses the full step 4 task text (binding block, record
+   path and inlined evidence pack, `SCOPED_TEST_COMMANDS`, commit-before-reporting,
+   SDD status line) with the round's failing output appended verbatim: the red test
+   output (step 5), the conformance gaps (step 6), the review findings (step 7).
+   Each round is followed by `binding_check` (see Abort, **Binding**) before
+   anything else. Under a fresh context a retry child sees only its task text; a
+   fix child not told to commit leaves its fix where step 7's `<base-sha>..HEAD`
+   review and step 8's `merge --squash` never see it.
+4. **Implement.** One `implementer`, `context: "fresh"` - passed explicitly,
+   because the persona's frontmatter defaults to fork, and a forked parent
+   transcript carries the parent's `cd <primary>` commands and primes the child to
+   leave the worktree; the record path and inlined evidence pack already make the
+   task self-contained. `<WORKTREE>` and `<PRIMARY_ROOT>` below are the literal
+   step 3 values, never a `$VAR` for the child to resolve:
+
+   > Worktree binding: your checkout is <WORKTREE>. Your first command, before any
+   > other, is
+   >   actual=$(git rev-parse --show-toplevel); [ "$actual" = "<WORKTREE>" ] || echo "MISMATCH: $actual != <WORKTREE>"
+   > On MISMATCH run nothing else; your final message opens with the line
+   > `BLOCKED: toplevel <actual> != <WORKTREE>` and ends with `STATUS: BLOCKED`.
+   > Every mutating git command (add, commit, checkout, reset, stash) runs as
+   > `git -C <WORKTREE> ...`. Never `cd` out of <WORKTREE>; never run a command
+   > against <PRIMARY_ROOT>.
+   >
    > 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,
@@ -64,6 +93,14 @@ succeeds (it creates both). Every destructive command below is gated on its flag
    > re-run is the regression evidence). SCOPED_TEST_COMMANDS: <commands>. Commit on
    > `hotfix/<slug>` before reporting. End with the SDD status line verbatim.
 
+   The `BLOCKED:` opening line is load-bearing: pi-cohort turns a final message
+   whose first non-empty line starts with `BLOCKED:` into a dispatch error that
+   carries the full output, ahead of the implementer's completion guard that would
+   otherwise replace an edit-free report with a generic no-edits error.
+
+   On return, `binding_check` runs before anything else - before the status line
+   is read and before a dispatch error is handled; a failed check -> `binding_abort`,
+   the status branch is skipped. A dispatch error is routed as `BLOCKED`. Then:
    `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
@@ -126,6 +163,8 @@ succeeds (it creates both). Every destructive command below is gated on its flag
    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>`.
+   Binding aborts: worktree and `hotfix/<slug>` both present; no removal command
+   is run.
 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.
@@ -151,7 +190,7 @@ Judgment predicates (`[recommended]` only; Moderate review items):
 
 ## Abort
 
-Both classes end with the baseline re-check, then chase-bug step 4 re-renders.
+All three 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;
@@ -175,21 +214,73 @@ 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.
+**Binding** (after any implementer return, steps 4-7): the parent runs
+`binding_check` from `PRIMARY_ROOT` before reading the child's status line or
+handling a dispatch error - a `BLOCKED` or errored child may have mutated the
+primary before stopping, and the pre-land cleanup would delete the evidence.
+
+```bash
+binding_check() {
+  local head branch dirt default
+  default=$(git -C "$PRIMARY_ROOT" rev-parse "$DEFAULT")    || binding_abort read "rev-parse $DEFAULT failed"
+  head=$(git -C "$PRIMARY_ROOT" rev-parse HEAD)              || binding_abort read "rev-parse HEAD failed"
+  branch=$(git -C "$PRIMARY_ROOT" branch --show-current)     || binding_abort read "branch --show-current failed"
+  dirt=$(git -C "$PRIMARY_ROOT" status --porcelain --untracked-files=no) || binding_abort read "status failed"
+  local moved=""
+  [ "$default" = "$BASE_SHA" ] || moved="$moved <default>:$BASE_SHA..$default"
+  [ "$head" = "$ORIG_HEAD" ]   || moved="$moved HEAD:$ORIG_HEAD..$head"
+  [ "$branch" = "$ORIG_BRANCH" ] || moved="$moved branch:$ORIG_BRANCH->$branch"
+  [ -z "$moved" ] && [ -z "$dirt" ] && return 0
+  binding_abort drift "$moved" "$dirt"
+}
+```
+
+Every read must succeed before any comparison: a failed read with empty stdout
+would otherwise pass `-z "$dirt"` or be misread as HEAD drift. All observations
+are collected first, so a stray commit plus tracked dirt is one abort. Three refs,
+not one: a drifted child commits on whatever the primary has checked out, which is
+`<orig-branch>`, and `<orig-branch>` may differ from `<default>`. The tracked-only
+target is the empty string - the step 3 precondition already guarantees it.
+
+`binding_abort` never touches the primary checkout: no `git reset`, no
+`git checkout`, no stash - this run moved nothing, so the land-stage reset rule
+already forbids it. The worktree and `hotfix/<slug>` are **preserved** as
+evidence of what the child did where (a deliberate exception to pre-land
+cleanup). Report, by kind: `read` - the failing command and its stderr, the
+worktree path and `hotfix/<slug>` tip SHA, no drift claim; `drift` - for each
+moved ref `<ref> moved from <old> to <new>` plus
+`git --no-pager log --oneline <old>..<new>`
+(branch switch: `checked-out branch changed from <orig-branch> to <branch>`),
+for tracked dirt the path fields only (no `XY` codes), the full
+`git status --porcelain` delta against the step 3 baseline file
+(`$TMPDIR/hotfix-<slug>.baseline`, report-only as today), the worktree path and
+`hotfix/<slug>` tip SHA. The non-executed repair line
+`git checkout <ref> && git reset --hard <old-sha>` is printed only when tracked
+dirt is empty -
+with dirt present the parent cannot tell whose edits a reset would destroy. The
+menu re-renders without the hotfix row.
+
+**Baseline re-check**: `git status --porcelain --untracked-files=no` is empty (the
+step 3 precondition; the tracked-only baseline is empty by construction); 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.
+minimal fix, confirm green, commit on `hotfix/<slug>`. With no child the binding
+block is moot, but `binding_check` still runs after the initial inline commit and
+after each inline retry, conformance fix, or review fix, before tests continue.
+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
+- Reading an implementer's status line before `binding_check`
+- Resetting or checking out any primary ref from `binding_abort`
 - 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

package/skills/gauntlet-resume/SKILL.md

@@ -59,14 +59,18 @@ In order. All before any tracker mutation; entry check 1 is read-only.
    `not a git repo` and no override was given - except a `worktree: no` brief **without**
    process state, which is the brainstorming route in Dispatch, not a stop. Other
    `unavailable` fields inside `## Repo state` are legal.
-3. **Session cwd binding.** `phase_tracker`, `plan_check`, and the flow guards resolve
-   every path against the extension's session cwd; a child-shell `cd` cannot relocate it.
-   If `realpath $(git rev-parse --show-toplevel)` in the session cwd differs from the
-   resolved worktree, stop: "restart pi in <worktree> and re-run". Every restoration
-   therefore runs with the session rooted in the resolved worktree.
+3. **Same-repository binding.** Settings and flow guards come from the repository in
+   the extension's session cwd. Compare
+   `realpath "$(git rev-parse --path-format=absolute --git-common-dir)"` in the session
+   cwd with
+   `realpath "$(git -C <worktree> rev-parse --path-format=absolute --git-common-dir)"`.
+   If they differ, stop, name both paths, and say the resolved worktree belongs to a
+   different repository; restart pi in that repository's primary checkout and re-run.
+   Same-repository worktrees proceed by path: use `git -C <worktree>` for
+   worktree Git commands and absolute artifact paths for `Read` and `plan_check`.
 4. **Drift notice.** Compare the brief's `HEAD` and `dirty` fields in `## Repo state`
-   with the live worktree (`git rev-parse HEAD`, `git status --porcelain`). Announce
-   differences. Informational, never a stop.
+   with the live worktree (`git -C <worktree> rev-parse HEAD`, `git -C <worktree>
+   status --porcelain`). Announce differences. Informational, never a stop.
 5. **Skills loaded.** For each name in `## Skills loaded` (none for
    `## Skills loaded: none`): match against the frontmatter `name` of every
    `skills/*/SKILL.md` in this package; `Read` each match's complete file into the

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

@@ -97,7 +97,8 @@ Per-stage call table, keyed by the brief's active phase (`→`). `R` is the reas
 (`reconstruction.md`, "Candidates", including its `flowGuards.specDirs` resolution): the
 single spec/plan pair added after base in the worktree, paired by identical basename
 (`<specDir>/<name>.md` <-> `<sibling plans dir>/<name>.md`, the writing-plans contract);
-zero pairs -> stop; more than one -> human picks.
+resolve the selected plan to an absolute path under the worktree before `plan_check`.
+Zero pairs -> stop; more than one -> human picks.
 
 "Exact" restoration binds: the active phase identity and substep, and the plan task list
 (names, order, statuses) verbatim. Prior phases show `⊘ (resume: ...)` regardless of the

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

@@ -13,12 +13,12 @@ available" - and never invent Intent or Decisions.
 ## Base
 
 ```bash
-git merge-base HEAD origin/HEAD 2>/dev/null \
-  || git merge-base HEAD main 2>/dev/null \
-  || git merge-base HEAD master 2>/dev/null
+git -C <worktree> merge-base HEAD origin/HEAD 2>/dev/null \
+  || git -C <worktree> merge-base HEAD main 2>/dev/null \
+  || git -C <worktree> merge-base HEAD master 2>/dev/null
 ```
 
-Base = `git merge-base HEAD origin/HEAD`, else `main`/`master`. Empty -> ask the human
+Base = `git -C <worktree> merge-base HEAD origin/HEAD`, else `main`/`master`. Empty -> ask the human
 for a base ref before reading any artifact.
 
 ## Candidates
@@ -29,15 +29,18 @@ else the active pi profile's `settings.json`, else the default `["doc/specs"]` (
 space-separated - never the literal defaults when a setting is present.
 
 ```bash
-git diff --diff-filter=A --name-only <base>..HEAD -- <dirs>
-git ls-files --others --exclude-standard -- <dirs>
+git -C <worktree> diff --diff-filter=A --name-only <base>..HEAD -- <dirs>
+git -C <worktree> ls-files --others --exclude-standard -- <dirs>
 ```
 
 Candidates are files under those directories added after base, plus untracked files
-there. A spec and a plan pair by identical basename (`<specDir>/<name>.md` <->
-`<sibling plans dir>/<name>.md`). The plan commit is the first post-base commit that added the
-plan file: `git log --diff-filter=A --format=%H --reverse <base>..HEAD -- <plan>`, first
-line. An uncommitted plan has no plan commit; treat every task as `pending`.
+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
+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 |
 |---|---|
@@ -63,11 +66,12 @@ Show, and ask the human to confirm or edit both in one reply:
 
 1. Per task, in plan order: the commits after the plan commit that touch any path in
    the task's declared `Files:` block. Strip a trailing `:digits[-digits]` range from
-   each `Modify:` path before matching `git log -- <path>`:
-   `git log --format=%h --oneline <plan-commit>..HEAD -- <path>`. Uncommitted plan (no
+   each `Modify:` path before matching `git -C <worktree> log -- <path>`:
+   `git -C <worktree> log --format=%h --oneline <plan-commit>..HEAD -- <path>`.
+   Uncommitted plan (no
    plan commit): skip this query entirely - there is no range to search - and show
    "plan uncommitted; no task evidence" in its place; every task is proposed `pending`.
-2. Uncommitted files: `git status --porcelain`.
+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`.
 
@@ -83,7 +87,7 @@ edits override proposals; never rewrite confirmed state silently.
 After confirmation:
 
 1. `start brainstorm`; `skip brainstorm resume: <spec path>`; `start plan`.
-2. `plan_check` with `planPath` = the plan. FAIL -> print the findings, stop with plan
+2. `plan_check` with `planPath` = the plan's absolute path. FAIL -> print the findings, stop with plan
    in_progress, no `init`.
 3. PASS -> `skip plan` with the same `resume:` reason; for stage verify also
    `skip implement`; `start <stage>`.