pi-gauntlet 8.4.9 → 8.4.11

package/skills/loop-implementation/reference/unreachable-returns.md

@@ -1,13 +1,12 @@
 # Unreachable returns
 
-Key routing to the admitted return, not unchanged evidence. Keep an unanswered stop pending, including on resume. Treat a human retry, `rows +N`, an applied amendment answering the stop, or an applied cut as answering that return. Recover answered state on resume from the existing retry, raise-allowance and amendment decisions/commits after that admission; add no routing marker. Continue at the ordered table without re-firing its marker, even while the failed row's evidence is unchanged. Route a newly admitted failed return independently, even with identical evidence. Keep action counts and authorization bounds unchanged by retry or `rows +N`; only an approved amendment can raise an action's bound.
+Key routing to the admitted return, not unchanged evidence. Keep an unanswered stop pending, including on resume. Treat a human retry, `rows +N`, an applied amendment answering the stop, or an applied cut as answering that return. Recover answered state on resume from the existing retry, raise-allowance and amendment decisions/commits after that admission; add no routing marker. Continue at the ordered table without re-firing its marker, even while the failed row's evidence is unchanged. Route a newly admitted failed return independently, even with identical evidence.
 
 Inspect only the target's first result segment after the check name in its admitted evidence cell; split on unescaped semicolons and trim whitespace. Never inspect later result segments, other rows or a rejected return. Leave malformed markers on the ordinary failed-attempt path.
 
 | First result segment | Action |
 |---|---|
-| Matches `^bound spent: .+$` | Render `Stopped on row <n>` per the driver's Human stop under options 4 and 5 alike, with the ordinary row menu (retry, `rows +N`, Amend, Stop) and `Recommendation: none - named action bound spent`; never cut or redispatch automatically, including for a `venue:` row. |
 | Matches `^unreachable: .+ - .+$` | Keep `venue:` rows on the ordinary failed-attempt path with their held disposition unchanged. For other rows, take the amendment action below before another dispatch. |
-| Neither | Return to the ordered table. |
+| Otherwise | Return to the ordered table. |
 
 Leave diagnosis to the child. Form one amend item outside the dispatch loop through [amendment-surface](../../brainstorming/reference/amendment-surface.md), using the captured `<what>` and `<where>` from `unreachable: <what> - <where>` as evidence. Recommend disposition `deviates: unreachable in this checkout - <what>; proof at <where>` and an `## Out of scope` entry `<row text, first 60 chars> - unreachable in this checkout - <what>`; never convert the disposition to `venue:`, even for a production proof location. Reuse the surface's batch preparation, grant decoding and section 5 audit/ledger aftermath, including its redraw and repeated-evidence stops. Without amend permission take its human batch before any write or dispatch. Under amend permission apply the item: set the ledger row `cut` with the disposition as evidence in the surface's single `loop: cut row <n>` commit, and print `amended the spec: row <n> - unreachable in this checkout - <what>`. Preserve attempts, iterations, allowance and spent escalation. Refresh held state through the driver's Human stop amendment return and continue the ordered table in the same turn. Carry the cut on After the loop's `Deferred/deviates per spec:` line. For companions use the held mapping and coordinated amendment rules; the home spec/ledger own the cut.

package/skills/using-git-worktrees/reference/pr-head.md

@@ -6,18 +6,44 @@ For `$ROOT`, `$BRANCH`, `REMOTE_BRANCH=existing`, follow companion mode below be
 
 ### Companion identity and provisioning
 
-Use caller `$ROOT` unchanged, not the session's git common directory; apply Step 0's submodule guard against that root. Use `$BRANCH` as the branch and the companion's repo identity in every stop, never a PR number. Run `git -C "$ROOT" fetch origin`, then repeat the live check `git -C "$ROOT" ls-remote --exit-code --heads origin refs/heads/<branch>` before any companion writes. On any fetch failure or lookup exit other than 0 or 2 stop naming repo and command output, never diagnose absence. On exit 0 require `origin/<branch>`. On exit 2 stop even when a stale tracking ref still resolves: `origin/<branch> is missing in <repo>; on the machine that ran option 6, push <branch> from that companion's checkout, then rerun brainstorming #N`. On that machine, verify `git log -1 --format=%H refs/heads/<branch> -- <spec-dir>/<home spec filename>` shows the leg-file commit without checking out or modifying the primary, then run `git push -u origin <branch>`. Stop continuation when that commit exists on no machine; do not regenerate it.
+Use caller `$ROOT` unchanged, not the session's git common directory; apply Step 0's submodule guard against that root. Use `$BRANCH` as the branch and the companion's repo identity in every stop, never a PR number. Run `git -C "$ROOT" fetch origin`, then repeat the live check `git -C "$ROOT" ls-remote --exit-code --heads origin refs/heads/<branch>` before any companion writes. On any fetch failure or lookup exit other than 0 or 2 stop naming repo and command output, never diagnose absence. On exit 0 require `origin/<branch>`. On exit 2 stop even when a stale tracking ref still resolves; use [Missing remote recovery](#missing-remote-recovery) before selecting the stop's recovery ending.
 
-Set `ORIGINAL_HEAD=$(git -C "$ROOT" rev-parse origin/<branch>)`. Obtain nonempty `baseRefName` with `gh repo view <owner/name> --json defaultBranchRef -q .defaultBranchRef.name` (positional repo, never `-R`), then `BASE_SHA=$(git -C "$ROOT" rev-parse origin/<baseRefName>)`; retain full SHAs. Resolve home and create through Step 1a's rules from this repo's own overrides and `.pi/settings.json` read by file with existing preset rules, already compared with recorded contract in caller preflight. Derive NAME from BRANCH with `/` replaced by `-`.
+Set `ORIGINAL_HEAD=$(git -C "$ROOT" rev-parse origin/<branch>)`. Obtain nonempty `baseRefName` with `gh repo view <owner/name> --json defaultBranchRef -q .defaultBranchRef.name` (positional repo, never `-R`), then `BASE_SHA=$(git -C "$ROOT" rev-parse origin/<baseRefName>)`; retain full SHAs. Use this repo's own overrides and `.pi/settings.json` read by file with existing preset rules, already compared with the recorded contract in caller preflight. For a recorded `home:`, resolve home/create through Step 1a; without `home:`, select and provision through [Recorded no-home provisioning](#recorded-no-home-provisioning). Derive NAME from BRANCH with `/` replaced by `-`.
 
-Read no `headRefOid`, `MEMBER_HEADS` or `PRE_REWORK_HEAD` on this path. Skip cross-repository/PR-head-unreachable checks, PR reports, pre-rework refs and thread fetching. Keep the checked-out-elsewhere stop from the home table, substituting BRANCH and naming repo. Before the local-branch ancestry stop, apply coordinated base-sync recovery below. Without recovery require `git -C "$ROOT" merge-base --is-ancestor refs/heads/<branch> origin/<branch>` for an existing branch; on exit 1 use the local-branch ancestry stop naming repo and replacing "rework needs the PR head" with "companion needs the published branch head". Surface command errors, not negative proofs.
+Read no `headRefOid`, `MEMBER_HEADS` or `PRE_REWORK_HEAD` on this path. Skip cross-repository/PR-head-unreachable checks, PR reports, pre-rework refs and thread fetching. Keep the checked-out-elsewhere stop from the home table only for a recorded `home:`, substituting BRANCH and naming repo. Before the local-branch ancestry stop, apply coordinated base-sync recovery below. Without recovery require `git -C "$ROOT" merge-base --is-ancestor refs/heads/<branch> origin/<branch>` for an existing branch; on exit 1 use the local-branch ancestry stop naming repo and replacing "rework needs the PR head" with "companion needs the published branch head". Surface command errors, not negative proofs.
 
-Apply the "Provision the exact head" rows and wrapper/token/home safety rules with BRANCH for headRefName and ORIGINAL_HEAD for headRefOid. Keep their order: validated recovery, selected-home dirty-tree ask then ff-only and exact head, absent tree/local ancestor proof then update-ref and add, absent tree/absent branch existing-branch DWIM add. Never supply `-b`/`-B`. Run a compatible existing-branch wrapper only; retain `create: override skipped (contains -b)` otherwise. After creation require HEAD equal ORIGINAL_HEAD or validated recovery tip; on mismatch preserve the tree and print its path and both full SHAs.
+Apply the "Provision the exact head" rows and wrapper/token/home safety rules with BRANCH for headRefName and ORIGINAL_HEAD for headRefOid; for a block without `home:`, replace their tree selection and add commands through the no-home table below, including on validated recovery. Keep their order: validated recovery, selected-home dirty-tree ask then ff-only and exact head, absent tree/local ancestor proof then update-ref and add, absent tree/absent branch existing-branch DWIM add. Never supply `-b`/`-B`. Run a compatible existing-branch wrapper only; retain `create: override skipped (contains -b)` otherwise. After creation require HEAD equal ORIGINAL_HEAD or validated recovery tip; on mismatch preserve the tree and print its path and both literal full SHAs (define any report aliases with all 40 characters).
 
-Run only "Merge the fetched base", with companion WORKTREE and its own BASE_SHA overrides for SCOPED_TEST_COMMANDS. Keep helper scope, staging, contained-delta and orchestrator completion checks. On failure abort and record `merge: unresolved - <files>`; return the unresolved result to the coordinated caller for its by-hand stop, not the home Task 1 continuation. Require `git -C "$WORKTREE" merge-base --is-ancestor <ORIGINAL_HEAD> HEAD` after merge. Report Base SHA and merge outcome, not `PR:` or `Pre-rework head:`. Require Step 4's coordinated read-back (`worktree list --porcelain` path and `branch --show-current` exactly BRANCH) before `Worktree ready at <path>`.
+Run only "Merge the fetched base", with companion WORKTREE and its own BASE_SHA overrides for SCOPED_TEST_COMMANDS. Keep helper scope, staging, contained-delta and orchestrator completion checks. On failure abort and record `merge: unresolved - <files>`; end with the preserved-leg inventory and the caller's by-hand stop, even after a clean abort. Emit no `Worktree ready` or home Task 1 continuation on this path. Require `git -C "$WORKTREE" merge-base --is-ancestor <ORIGINAL_HEAD> HEAD` after merge. Report Base SHA and merge outcome, not `PR:` or `Pre-rework head:`. Require Step 4's coordinated read-back (`worktree list --porcelain` path and `branch --show-current` exactly BRANCH) before `Worktree ready at <path>`.
 
 On every companion provisioning failure name repo and branch and print `Preserved created legs:` using Step 4's inventory, including the stopped member's tree after a successful creator. Remove nothing.
 
+### Missing remote recovery
+
+Print `origin/<branch> is missing in <repo>`. Run `git -C <primary> log -1 --format=%H refs/heads/<branch> -- <spec-dir>/<home spec filename>` on this machine without checking out or modifying the primary. Select the recovery ending from that file-scoped result, not the branch tip or a stale tracking ref:
+
+| Observation | Recovery ending |
+|---|---|
+| The file-scoped log prints a commit | Offer `git push -u origin <branch>` from that primary, then rerun `brainstorming #N`. |
+| No local branch, or a local branch without the leg-file commit; the log prints nothing | State `no local branch on this machine holds the leg file; restore origin/<branch> from a clone that still has it and rerun brainstorming #N; nothing is regenerated`. Offer no push from this machine. |
+
+Preserve all provisioned trees. Run no creation, local ref update or merge on this stop.
+
+### Recorded no-home provisioning
+
+Apply to a companion block without `home:` and to a marked home's block without `home:`. Keep blocks with `home:` and unmarked PR subjects on their existing rows, including the another-path stop and the `create: override skipped (contains -b)` native fallback.
+
+Locate by [Locate a leg tree](../../brainstorming/reference/legs.md#locate-a-leg-tree) in ROOT using the recorded branch, including for marked home selection before its worktree exists. Use its linked-block and checkout identity checks; never derive a folder from NAME or default a missing recorded `home:`. Keep NAME as the branch with `/` replaced by `-` for creation tokens, not the located folder basename.
+
+| Observed state | Action |
+|---|---|
+| One valid linked tree on the branch | Set WORKTREE to that path; bypass the another-path stop. Run the existing dirty-tree ask, ff-only and exact published-head checks there, or reuse the validated recovery tip unchanged. |
+| Lookup fails other than `no worktree holds <branch>` | Stop naming repo and branch with the lookup reason; create nothing. |
+| No tree, recorded script supports an existing-branch form | Read its source before any write. After the existing source-clean ask and local-branch ancestry proof, update-ref only for an unrecovered local ancestor; preserve a recovered tip. Run the script's existing-branch form from ROOT with shared NAME for `<name>` and the recorded branch for `<branch>`, quoted as single shell words. Never pass `-b`/`-B`; surface nonzero output without a built-in fallback. Locate the created tree by branch and require HEAD equal to the published head or validated recovery tip, then complete normal base sync and Step 4 read-back. |
+| No tree, recorded script cannot check out an existing branch | Stop before any write, including update-ref: `cannot provision <repo>: <script> cannot check out existing branch <branch>`. Create no built-in tree. |
+
+Resolve other tokens through the existing wrapper-token rule before execution. Keep built-in existing-branch creation only for a recorded built-in creator, never as a fallback for a script-owned tree.
+
 ### Recover coordinated base sync
 
 Apply only for a companion or a caller-observed marked home with N>1 Legs, before ancestry and exact-head stops. Use ORIGINAL_HEAD for companions and home headRefOid for marked home as the published head. Inspect the actual `refs/heads/<branch>` tip, not session HEAD. Keep the active-rebase guard below. For a differing local tip require published-head ancestry, then walk `git -C "$ROOT" log --first-parent --format='%H %P' origin/<branch>..refs/heads/<branch>`. Require a nonempty walk, exactly two parents on every entry, and `git -C "$ROOT" merge-base --is-ancestor <second parent> origin/<baseRefName>` exit 0 for each. Require a clean existing selected worktree. A failed proof takes the existing ancestry/carries-commits-beyond stop naming repo; preserve local commits and all created legs.
@@ -26,14 +52,14 @@ Reuse the validated tip without reset, update-ref or `-b`: keep its selected tre
 
 ## Select home and stop before writes
 
-Consume SYNC beside the ordered array of admitted PR values, home first; use home's `headRefName` for checkout and `PRE_REWORK_HEAD=<home headRefOid>`. Carry the remaining entries as MEMBER_HEADS `{ number, url, title, headRefName, headRefOid }`. For a caller passing PR values, follow this reference instead of `using-git-worktrees/SKILL.md` Steps 0 and 1. Derive ROOT from the absolute git common directory as in Step 0, applying its submodule guard. Resolve the worktree home through the existing overrides/native-tool/wrapper contract; default to `$ROOT/.worktrees/<name>`. Set `<name>` to `headRefName` with every `/` replaced by `-`. Never adopt the session's linked tree unless it is the selected home on `headRefName`.
+Consume SYNC beside the ordered array of admitted PR values, home first; use home's `headRefName` for checkout and `PRE_REWORK_HEAD=<home headRefOid>`. Carry the remaining entries as MEMBER_HEADS `{ number, url, title, headRefName, headRefOid }`. For a caller passing PR values, follow this reference instead of `using-git-worktrees/SKILL.md` Steps 0 and 1. Derive ROOT from the absolute git common directory as in Step 0, applying its submodule guard. For a marked home with a recorded block without `home:`, use [Recorded no-home provisioning](#recorded-no-home-provisioning) for selection and every add below. Otherwise resolve the worktree home through the existing overrides/native-tool/wrapper contract; default to `$ROOT/.worktrees/<name>`. Set `<name>` to `headRefName` with every `/` replaced by `-`. Never adopt the session's linked tree unless it is the selected home on `headRefName`.
 
 Run `git -C "$ROOT" fetch origin`, then check reachability and remote equality for every admitted PR (home and members) before any worktree write: require each original `headRefOid` object and `origin/<headRefName>` equal to it; use the branch-moved stop below naming that PR. Resolve `BASE_SHA=$(git -C "$ROOT" rev-parse origin/<baseRefName>)` as a full SHA before any conflict helper needs fetched-base overrides. Then check these stops in order before creating or modifying any file in the primary or a worktree, or running `git worktree add`.
 
 | Observable case | Exact stop |
 |---|---|
 | `isCrossRepository` true | `PR #N's head lives on fork <headRepository.nameWithOwner>; rework needs an in-repo branch.` |
-| `headRefName` listed by `git -C "$ROOT" worktree list --porcelain` at another path, including `.worktrees/pr-<N>` | `branch <headRefName> is checked out at <path>; finish or remove that worktree first.` |
+| Recorded `home:` or unmarked subject, and `headRefName` listed by `git -C "$ROOT" worktree list --porcelain` at another path, including `.worktrees/pr-<N>` | `branch <headRefName> is checked out at <path>; finish or remove that worktree first.` |
 | `git -C "$ROOT" rev-parse --verify -q <headRefOid>^{commit}` fails after fetch, or `origin/<headRefName>` differs from `headRefOid` | `PR #N head <headRefOid7> is not reachable (origin/<headRefName> is at <sha7>); the branch moved.` |
 | Local branch exists without validated recovery (after recovery below; N=1 without a rework-base ref, with or without a worktree, always takes this check) and `git -C "$ROOT" merge-base --is-ancestor <headRefName> origin/<headRefName>` exits 1 | `local branch <headRefName> is at <sha7>, not an ancestor of origin/<headRefName> (<sha7>); rework needs the PR head.` |
 

package/skills/verification-before-completion/reference/conformance-check.md

@@ -126,7 +126,7 @@ partition from an earlier round.
 
 ### Ledger subjects
 
-Treat a `# Ledger - loop engine` subject as the loop path, never the ad-hoc no-plan path. Read `/skill:loop-implementation`'s `## Gate set` at its absolute skill path and apply it at every test site below, including its missing-`checks:` stop, checkout ownership, fail-fast execution and `LOG_DIR` redirection. Reuse the executing skill's session `LOG_DIR`; on a resumed session mint it once at the first gate-set site. Keep the plan and ad-hoc rules below unchanged for non-ledger subjects.
+Treat a `# Ledger - loop engine` subject as the loop path, never the ad-hoc no-plan path. Read `/skill:loop-implementation`'s `## Gate set` at its absolute skill path and apply it at every test site below, including its missing-`checks:` stop, owning-checkout routing, fail-fast execution and `LOG_DIR` redirection. Reuse the executing skill's session `LOG_DIR`; on a resumed session mint it once at the first gate-set site. Keep the plan and ad-hoc rules below unchanged for non-ledger subjects.
 
 For a ledger repair or Convergence task, pass the failing command, its checkout, exit code and log path, never pasted output. The child reads the log to derive the files to touch, including Convergence (c)'s files named by failing output; the driver does not read it. Feed that single gate failure into the existing fix-round machinery.
 

package/skills/writing-plans/SKILL.md

@@ -114,7 +114,7 @@ If you can't list the files, the spec isn't ready: amend or redraw per brainstor
 
 ## Leg routing
 
-Read the home spec's `## Legs` and [the leg contract](../brainstorming/reference/legs.md) before recon. Keep the plan and `**Spec:**` header home-owned. Resolve each member's checkout from its declared primary and recorded `home:` with shared `NAME`; admit task ownership through `plan_check`, never from `design:` prose. Follow [plan-contract.md](reference/plan-contract.md#legs-leg-unknown) for `Leg:`, per-leg baselines and path keys. Repair unknown task legs in the plan, not spec membership.
+Read the home spec's `## Legs` and [the leg contract](../brainstorming/reference/legs.md) before recon. Keep the plan and `**Spec:**` header home-owned. Keep home's checkout at the session's home worktree and resolve companions through [Locate a leg tree](../brainstorming/reference/legs.md#locate-a-leg-tree); admit task ownership through `plan_check`, never from `design:` prose. Stop plan writing on a failed lookup and report its reason; create no plan against a guessed checkout. Follow [plan-contract.md](reference/plan-contract.md#legs-leg-unknown) for `Leg:`, per-leg baselines and path keys. Repair unknown task legs in the plan, not spec membership.
 
 Re-walk every task's `Files:` using Gather rules in the leg contract. Append extra task `Rules:` and resolve `Rules: root only - paths unresolved`; retain missing-link evidence. Split mixed waves into consecutive single-leg waves without violating dependencies.
 

package/skills/writing-plans/reference/plan-contract.md

@@ -13,7 +13,7 @@ A wave is a maximal set of tasks that have no ordering dependency on each other,
 
 Read the home spec's `## Legs` using [the leg contract](../../brainstorming/reference/legs.md). Write `Leg: <repo>` immediately after each task heading, before `**Files:**`; absence means home. Keep the plan and its `**Spec:**` header at home, citing the home spec. Repair a `leg-unknown` task in the plan, never by adding spec membership.
 
-Write one `Baseline <repo>: <sha>` header per member. Match each task's baseline bullets to its own leg's SHA; require equality within a leg, not across legs. Resolve `Modify:`/`Create:`/`Test:`/`Delete:` paths and globs against the admitted leg checkout, using its recorded `home:` with shared `NAME` against its declared primary. Key file overlap and cross-task created anchors on `(leg, path)`.
+Write one `Baseline <repo>: <sha>` header per member. Match each task's baseline bullets to its own leg's SHA; require equality within a leg, not across legs. Resolve `Modify:`/`Create:`/`Test:`/`Delete:` paths and globs against the admitted leg checkout from [Locate a leg tree](../../brainstorming/reference/legs.md#locate-a-leg-tree), keeping home at the session's home worktree. Stop plan writing on a failed lookup and report its reason; create no plan against a guessed checkout. Key file overlap and cross-task created anchors on `(leg, path)`.
 
 Split mixed waves into consecutive leg-homogeneous waves, preserving dependencies. Re-walk each task's `Files:` under its leg using the leg contract's Gather rules procedure. Append task `Rules:` for files missing from the spec list; resolve `Rules: root only - paths unresolved`. Read the combined lists before execution and review.
 

package/skills/loop-implementation/reference/action-spend.md

@@ -1,10 +0,0 @@
-# Action-spend durability
-
-Read this contract before admitting a return or restoring any saved ledger, including seed, row, companion and verification repairs. Keep action accounting separate from row attempts and repair allowances.
-
-1. Before deleting a jobs file, resetting a checkout or restoring ledger decisions, retain every `ran <action> (<k> of <bound>)` and `bound spent: <action> (<k> of <bound>)` record from the child's jobs file, returned evidence/decisions and attributable ledger or commit body. Read only those permitted boundary artifacts, never a transcript or log. Treat action-record lines in the jobs file as accounting, not process entries; apply process ownership checks only to pid records. Require a pre-launch spend reservation, confirmed execution record or affirmative retained evidence that no paid/external action launched. With uncertain execution and no attributable reservation, stop at recovery incomplete with `action execution uncertain`; preserve state rather than infer an unspent bound from missing decision text.
-2. Before admitting a successful row or seed return, require every reserved spend to survive in its ledger evidence/decisions (or companion result cells). Before replacing an evidence cell, require the child to repeat each carried `ran <action> (<k> of <bound>)` and `bound spent: <action> (<k> of <bound>)` record verbatim in its own decision sentence before any new spend, including records from a successful seed. Treat a dropped record as a validation miss even when the replacement check passes. For verification repairs, require the records after tuple/iteration in the attributed child commit body instead, leaving row cells unchanged; copy them into the home repair marker. A reservation without a confirmed `ran` record stays conservatively spent. A missing spend record is a validation miss, not permission to erase it. Retain the action records until admission or a durable repair marker; only then delete the jobs file after process cleanup.
-3. For every interrupted or validation-miss repair, copy all retained action records into the parent repair commit body before clearing the pending tuple or discarding child output. Include them in a numbered target's evidence cell after the interruption/miss reason, within the existing result-line bound; the commit body retains the complete accounting. For seed preserve the saved row cells and fixed seed decision contract; keep action accounting in the `loop: repair seed` commit body. For verification retain it in the `loop: repair verification` marker. Keep prior decisions intact and add no decision kind or ledger header.
-4. Carry these repair commit bodies as spend history on every later dispatch and authorized restore, including companion dispatches: inject home repair action records in the existing hint when the child cannot read home history. Count the highest recorded k for each action across decisions, evidence and repair bodies; identical copies are one spend. Preserve this history through retry, amendment and finish.
-
-For a capture that succeeds before an interrupted seed, preserve `ran capture (1 of 1)` in the seed repair commit body even when reset removes its fixture and ledger changes. The next child counts that spend and records `bound spent: capture 1 of 1`, never another capture. Preserve a lone pre-launch reservation conservatively in the same way.