pi-gauntlet 8.1.1 → 8.1.3

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v8.1.3 - 2026-11-01
+
+- The loop engine runs on one per-row budget: a fresh ledger carries `allowance: <maxIterationsPerRow>` (default 4) in place of `cap:`, a `4; allowance N` or `5; allowance N` approval reply overrides the setting, and each `retry <n> | <hint>` decision adds one attempt to that row. The driver drops funded rounds, `cap +N`, the total-iteration cap and amend-gated escalation; a row's last allowed attempt runs once on `escalationLoop.implModel` under option 4 and option 5 alike, and exit-verification failure gets one escalated repair per flow. Human stops offer only `retry <n> | <hint>` and `rows +N` and print each open row as `<attempts> of <allowance>`; the task tracker labels rows `<attempts>/<allowance>: <criterion text>` while task names stay `row N`. A legacy `cap:` ledger migrates on resume through a parent `loop: migrate allowance` commit. (#108)
+
+## v8.1.2 - 2026-11-01
+
+- `gatekeep-pr` selects the viewer's newest submitted, non-dismissed review and, when its commit is an ancestor of the assessed head, sends the reviewer its posted items and only the intervening code delta. The report counts addressed items; contract checks still judge the whole head. Assess pins its review to the assessed commit and checks the response; own-PR comment reviews supply the same bounded baseline.
+
 ## v8.1.1 - 2026-11-01
 
 - Loop verification and finish run the deduplicated gate set of recorded row checks in their owning checkouts; CI on push owns the full suite. Gate output stays in session logs, repair children receive log paths, and the driver reads only a 20-line tail at the verify-step-1 human stop. Workers record selective commands with TDD and test-economy rules; ledgers without `checks:` stop instead of falling back to a full run. Loop PR summaries identify scoped verification; unmatched gate commands can leave `verification_runs` at zero and trigger the expected ship advisory without authorizing a full local run. (#109)

package/README.md

@@ -39,7 +39,7 @@ Concretely, one change through the gauntlet:
 1. Opt in with `/skill:brainstorming` and describe the change. The command is the reliable discovery-and-entry path; explicit prose requesting brainstorming/the gauntlet also supplies consent when the skill is already loaded or an available instruction or route identifies it. An ordinary implementation request or an agent recommendation is not consent. A leading run of GitHub references (`#N`, `owner/repo#N`, or a `/pull/N` or `/issues/N` URL), separated by whitespace or commas, resolves each reference as a PR first: related open, same-repository, non-fork PRs on one base form one rework subject, including drafts. Admission runs in listed order and relatedness is checked before provisioning; the first retained PR is home, whose existing branch rebases onto the fetched PR base by default, then member commits replay onto it in listed order. The first intent word `merge-forward` opts out and keeps the merge path. An unresolved conflict after its scoped helper aborts that step and continues to the spec with the repair as Task 1. A single non-PR reference follows the ticket path. The first non-reference token starts intent text; mid-sentence references and other ticket/free-text subjects keep their existing paths. The combined code, PR-carried specs, claims, and review threads are the brainstorm input, with each PR's provenance retained; only home's bound ticket supplies acceptance criteria, while member tickets supply context. A single PR retains the same rework path without member replays or a close offer. The combined state is judged against constraints from the fetched current base HEAD, not the fork point or the PRs' proposed policy edits; see the [PR-subject contract](skills/brainstorming/reference/pr-subject.md) and [PR-head worktree owner](skills/using-git-worktrees/reference/pr-head.md). **`brainstorming`** sets up an isolated worktree (on the existing branch for PR rework), explores the codebase, and turns the subject into a written spec - when its recon finds a cited case that the ask is the wrong change (misdiagnosed, wrong-sized, already solved, a band-aid, or cutting across a sound pattern - including a repo convention that is itself debt) and can name the alternative, question one is a framing question (`as framed`, `pivot: <alternative>`, or `smaller or none`); otherwise it opens with one sentence naming what it checked, and every approach it proposes ends with a `Pattern:` line naming what it follows or cuts across; when the run starts from a ticket, the spec carries the ticket's acceptance criteria verbatim, each with a disposition (`in-scope`, `deviates:`, `deferred:`, `venue:`, `elsewhere:` for a row another repo's part delivers), scope cuts come only from your answer to a cut question and are listed at the gate, the conformance gate checks the in-scope ones, and `/skill:check-delivery` verifies `venue:` rows before the prod deploy. 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`; candidates come from brainstorming's scout recon, never a mechanical sweep). **You read and approve the spec - human gate 1.** Options 1/2/4/5 approve and pick an engine; option 6 approves the content only: it writes `**Engine:** deferred` under `**Amend-grant:** none`, pushes the branch, opens a draft PR carrying just the spec, prints the URL, and ends the flow - no plan, no loop, no handoff brief. For a coordinated spec, it first pushes every companion branch to origin, then opens one home draft PR; it creates no companion PRs. A later `brainstorming #N` reconstructs the recorded companions from their origin branches before re-presenting the implementation gate; the [publication and re-gate owner](skills/brainstorming/reference/spec-pr.md) defines all-member preflight, recovery, and cleanup. The branch stays; a gauntlet-owned worktree is removed, a host-owned checkout is reported and left. Option 6 is withheld on a PR subject (`Withheld: draft PR - #N already exists`) and when the branch's diff against the default branch is not spec-only. A later `brainstorming #N` on that PR classifies it from the diff alone: one added spec carrying the marker plus banner-only predecessor edits re-presents the gate with 1/2/4/5 (3 only when the spec commit carries a council audit) and skips gather, questionary, council, and scout; a spec-only diff without the marker prints `spec-only PR without the gate marker - running lint and council` and takes the normal brainstorm path with the carried spec as the draft; any other diff takes the rework path. Approval at that re-gate writes `**Engine:**`, `**Amend-grant:**`, and `**PR:** <owner/repo#N>` as a new commit on the PR branch and chains into planning or the loop as usual. Before approval, PR rework's sole write/run exception outside the spec directories permits only the base sync (rebase or merge), each member replay or merge, their conflict helpers' edits to the conflicted files, and their scoped conflict tests; other subjects have no implementation code yet.
 2. By default, **`writing-plans`** decomposes the approved spec into atomic, independently-verifiable tasks, grouped into parallel waves where they don't touch the same files. Experimental approval options 4/5 instead select **`loop-implementation`**: the plan phase is skipped and a stamped acceptance-criteria ledger replaces the task plan. Option 4 retains amendment review; option 5 grants auto-apply amends, with redraws still stopping. See [Loop engine operations](doc/configuration.md#loop-engine-operations).
 3. **`subagent-driven-development`** executes the plan in waves, with task implementers followed by one integrated `wave-reviewer` after the scoped test gate passes. The reviewer checks anchored spec clauses and code quality together; repairs stay on the current tree and pass the same gate before re-review. TDD-locked: red, green, refactor. Independent implementation, review, and council batches remain parallel, but their dispatches are foreground: the orchestrator waits for terminal results before accepting work or advancing a phase.
-The loop alternative to step 3 runs one fresh `loop-implementer` per seed or row iteration, without implement-phase reviewers. Stagnation stops for a human decision. Under amend permission, row-allowance exhaustion and a failed verify-step gate each get one bounded escalated-model round within the existing cap. Ledger refresh completes implement when every row is closed; verify step 1 runs the gate set: deduplicated (owning checkout, command) pairs from done rows' recorded checks, with ownership from the ledger. Gate output goes to logs; the driver keeps exit codes and paths, not test output. CI on push owns the full run.
+The loop alternative to step 3 runs one fresh `loop-implementer` per seed or row iteration, without implement-phase reviewers. Each row starts with the shared allowance (default 4); approval replies such as `4; allowance 6` override it for one run. Under either loop approval option, the last allowed attempt escalates once per row on `escalationLoop.implModel` (the main-loop model when unset); one exit-verification repair per flow uses the same model. Exhaustion and stagnation stop for a human decision: `retry <n> | <hint>` adds one attempt to that row, while `rows +N` raises every row's allowance. Attempts never reset and there is no total iteration cap. Ledger refresh completes implement when every row is closed; verify step 1 runs the gate set: deduplicated (owning checkout, command) pairs from done rows' recorded checks, with ownership from the ledger. Gate output goes to logs; the driver keeps exit codes and paths, not test output. CI on push owns the full run.
 
 4. **verify**: the parent first runs the plan's full verification command set for waves, or the ledger gate set for loop; only a passing result permits whole-diff code review, then the **conformance gate**. A review fix invalidates that result, so the parent reruns the same set before the next review or conformance gate. Loop conformance repairs and finish also use the gate set, never the ledger's full `verification:` command. When the overrides file declares a happy path for the touched paths (see [Project-specific overrides](#project-specific-overrides)), the parent runs it once here, between code review and the conformance gate, and the reviewer reads its transcript as runtime evidence - a hang or a failed request shows up in the audit with the transcript quoted - as a gap when an origin clause ties to it, otherwise as a `happy-path: failed - unattributable` line - never as a silent green. The conformance subagent reads the finished code and docs against your *original words* from step 1, not the plan, and reports per-requirement: delivered, partial, missing, drifted, or unauthorized. Unauthorized rows - shipped surface no human input asked for, whether it crept in or was laundered through the spec - follow their recommendation like every other row: a contained removal auto-runs, anything another requirement leans on is deferred with a plain-language "I'd cut it / I'd keep it" recommendation. Inside a brainstorming-entered flow this gate is machine-blocked from being skipped. Compatible executable recommendations auto-run through an isolated fix-and-re-audit loop with no prompt; anything still open surfaces as a numbered decision brief - one item per decision, the problem in plain words first, lettered options each with a one-line consequence, and `Recommended: <letter> - <reason>` or `No recommendation - pick one`. Reply with one line per item (`1. B`), or bare `1` to take every recommendation (no-recommendation items are re-asked by number); a current `CONFORMS` / no-concerns result goes straight to the branch options with no extra conformance sign-off.
 5. **`finishing-a-development-branch`**: PR, draft PR, squash, keep, or discard; PR rework's row 1 offers a lease push of the rebased home branch to the existing PR (`Base:` records in `merge:` form push non-force). A spec whose header carries `**PR:**` (approved at a spec-PR re-gate) and no `## Rework record` replaces the two create rows with `Push to PR #N and mark it ready for review` and `Push to PR #N, keep it a draft` (`Push to PR #N (already ready for review)` when the PR is already ready): both push without force after strip-and-seal, the first then runs `gh pr ready`, neither rewrites the PR body, and both are withheld when origin's branch head is no longer an ancestor of local HEAD. For coordinated specs, these [header-linked rows 1/2](skills/finishing-a-development-branch/reference/spec-pr.md#push-rows-12) deliver companions in recorded order before one home seal carrying every companion PR URL, then push home and apply its readiness choice. Row 1 makes companion drafts ready too; row 2 creates drafts but never converts an already-ready PR back to draft. Companion URLs appear in the shipped summary, companions first and home last, not in the unchanged home PR body; keep that summary for cross-repo review because successful home delivery removes receipts. A spec still carrying `**Engine:** deferred` stops finishing (and `gauntlet-resume`) with `spec approved for handoff only - run brainstorming #N` before any phase change, verification, or push. The PR-rework push appends a `## Rework` block naming absorbed PRs while retaining the original description bytes; the header-linked `**PR:**` push leaves the body untouched. Only after a successful rework push and home-description edit does one gated confirmation show the exact close comments and eligible member targets, linking home; declining or any other finish option leaves members open. Closing never deletes member branches, and finish posts no review-thread replies. Its `Before:` handle includes the full portable pre-rework SHA and the local `refs/gauntlet/pre-rework/pr-<N>` ref in the rework checkout. The [finishing owner](skills/finishing-a-development-branch/SKILL.md#pr-subject-row-1-push-to-the-pr-branch) defines the landing and body-update contract. Once a PR exists, run `/skill:gatekeep-pr <pr>` to verify it before merging - it judges the diff against the spec at the PR's head (the acceptance-criteria dispositions and Design you approved; the PR description when no spec applies) - rows the spec defers or deviates are settled, every other row needs its mechanism (code, tests, docs) - and against the rubric; whatever can be seen only after merge is left to step 6. **Human gate 2** - the only other decision you make.
@@ -87,6 +87,8 @@ One finish choice spans all legs. PR, draft PR and squash deliver companions in
 
 ## Architecture
 
+A `gatekeep-pr` run after your newest submitted, non-dismissed review uses that review's commit as its baseline when it is an ancestor of the assessed head. The reviewer checks your posted items and only the intervening code delta; the report shows `Prior review: <k> of <n> items addressed`. Contract checks still judge the whole head. See the [review task](skills/gatekeep-pr/reference/assessment.md#step-4-review-task).
+
 `gatekeep-pr` selects one course per run: `assess` posts open blockers as one review (`request-changes` on someone else's PR, `comment` on your own), posts nothing with zero blockers, and performs no repair or sync; `deliver` repairs blockers, syncs, pushes, watches CI, and re-reviews until readiness, an obstacle, or a cap exit. `deliver with nits` stores `deliver-nits` and includes current and later nits. A ready first report skips the course pick and renders the final menu directly. Delivery rebases your own non-bot branch with `--force-with-lease` unless its history contains merge commits; someone else's, bot-authored, and merge-containing heads merge base instead. Final `merge` and `approve` remain separate picks; approval is offered only on someone else's non-draft PR with zero blockers. See the [course loop](skills/gatekeep-pr/reference/post-selection-loop.md) and [menu templates](skills/gatekeep-pr/reference/menus.md). In pi, `/skill:gatekeep-pr 12 15 18 [--rebase [base]]` gates a set of PR numbers or same-repository URLs, with one fresh `pr-gatekeeper` child and one worktree per PR. The parent shows a summary and unchanged per-PR menus in input order, queues every pick until the last menu, then executes the queued work in parallel. The set must fit pi-cohort's `parallel.maxTasks` (default `8`); it is never chunked. With `--rebase`, the parent asks once per set for eligible other-author or unreadable-author heads, excluding no-op heads and heads with merge commits. Multi-PR mode rejects positional issue references and is pi-only. An explicit no-argument invocation on either harness discovers your open PRs in origin, authored by you or directly awaiting your review (not team requests), excludes drafts and the `APPROVED` and `CHANGES_REQUESTED` states, and sorts by additions plus deletions, then PR number, ascending. One match gates directly on the single-PR path; multiple matches enter pi's batch path, while Claude Code stops with the sorted `discovered, smallest first:` list. Every report shows the refreshed viewer `Role:` under `Delivers`, not in the batch summary row. See the [parent-child contract](skills/gatekeep-pr/reference/batch.md).
 
 The course, target/scope baseline, repair and sync usage, and poll deadline live in one OS temporary continuation record, whose path appears in the tracker or checklist and `show evidence`. Gatekeep initializes independent repair-round and sync budgets to `2 x closureReview.maxFixRounds` (default `5`, no-tool fallback `2 x 5`). Only source-changing repair waves spend rounds; conflict-only syncs spend the separate sync budget, and description-only work, watches, and re-reviews spend neither. Obstacle `deliver` extends each cap by `2 x` the resolved value without resetting usage; a timeout continuation instead opens one more watch window without extending caps. Only the gate's own push automatically renews the CI window (`timeout minutes`, default `15`). The verify-phase runtime guard still uses `1 x` the resolved value and can block a gatekeep dispatch earlier.
@@ -598,7 +600,7 @@ Anything a wrapper skill contains beyond trigger phrases is misplaced - move it
 
 Settled skill-owned turns carry a machine-readable first line identifying a gate, question, or terminal outcome. Programs answering these turns use the [gate inventory and reply contract](doc/gate-contract.md); the rendered row bodies define valid replies.
 
-Choose experimental loop options 4/5, configure the iteration cap and worker model, and operate the planless ledger through [Loop engine operations](doc/configuration.md#loop-engine-operations). Waves remains the default.
+Choose experimental loop options 4/5, configure the per-row allowance and worker model, and operate the planless ledger through [Loop engine operations](doc/configuration.md#loop-engine-operations). The menu shows the resolved allowance; `; allowance N` overrides it for one run. Resume preserves an existing allowance or migrates a legacy cap after pending recovery. Waves remains the default.
 
 | Want to ... | Read |
 |---|---|
@@ -613,7 +615,8 @@ The conformance gate's model, the spec council's roster, and the phase-tracker's
 | `closureReview.enforce` | phase-tracker | `true` | conformance gate on/off - [detail](./doc/configuration.md#conformance-gate-model) |
 | `closureReview.model` | phase-tracker | unset (inherits) | conformance reviewer model - [detail](./doc/configuration.md#conformance-gate-model) |
 | `closureReview.maxFixRounds` | phase-tracker | `5` | fix rounds before escalation - [detail](./doc/configuration.md#conformance-gate-model) |
-| `escalationLoop.implModel` | phase-tracker | unset (main loop) | implementer model on escalation - [detail](./doc/configuration.md#escalation-loop) |
+| `escalationLoop.implModel` | phase-tracker | unset (main loop) | execution escalation under either loop option; review escalation remains separate - [detail](./doc/configuration.md#escalation-loop) |
+| `loopEngine.maxIterationsPerRow` | phase-tracker | `4` (floor `1`) | fresh-ledger per-row allowance; run override on approval 4/5 - [detail](./doc/configuration.md#setting-and-command-resolution) |
 | `phaseModels.plan` / `.implement` / `.verify` / `.ship` | phase-tracker | unset (no switch) | `provider/id[:level]` applied persistently at that phase's start - [detail](./doc/configuration.md#phase-models) |
 | `flowGuards.enforce` | phase-tracker | `true` | phase gates on/off - [detail](./doc/configuration.md#phase-tracker) |
 | `flowGuards.specDirs` | phase-tracker, plan-tracker; telemetry and spec-index consumers | `["doc/specs", "docs/specs"]` | where specs and sibling plans live - [detail](./doc/configuration.md#phase-tracker) |

package/extensions/lib/plan-check.test.ts

@@ -16,7 +16,7 @@ const ledger = (rows = ["1 | open | 0 |", "2 | cut | 0 | deferred: #70", "3 | do
   "# Ledger - loop engine\n**Spec:** `doc/specs/test.md`\nbase: abc\nverification: check\niterations: 0\n\n| row | status | attempts | evidence |\n|---|---|---|---|\n" + rows.map(r => `| ${r} |`).join("\n") + "\n\n## Decisions\n";
 
 test("ledger admission bypasses task checks and permits empty open evidence", () => {
-  for (const input of [ledger(), ledger().replace("iterations: 0\n", "iterations: 0\ncap: 97\n")]) {
+  for (const input of [ledger(), ...["cap: 97", "allowance: 4"].map(header => ledger().replace("iterations: 0\n", `iterations: 0\n${header}\n`))]) {
     assert.deepEqual(checkPlan(input, ledgerSpec, { exists: () => false, glob: () => [] }).findings, []);
   }
 });
@@ -1271,6 +1271,22 @@ const emptyPort: FsPort = { exists: () => false, glob: () => [] };
 test("coordinated ledger expands shared ownership and defaults unlisted ACs home", () => {
   assert.deepEqual(checkPlan(coordinatedLedger(), coordinatedSpec, emptyPort).findings, []);
 });
+test("coordinated ledger budget header admits allowance or legacy cap, never both", () => {
+  for (const key of ["allowance", "cap"]) {
+    for (const value of ["1", "4", "9007199254740991"]) {
+      const input = coordinatedLedger().replace("cap: 20", `${key}: ${value}`);
+      assert.deepEqual(checkPlan(input, coordinatedSpec, emptyPort).findings, [], `${key}: ${value}`);
+    }
+    for (const value of ["", "0", "-1", "1.5", "04", "four", "9007199254740992"]) {
+      const input = coordinatedLedger().replace("cap: 20", `${key}: ${value}`);
+      assert.ok(checkPlan(input, coordinatedSpec, emptyPort).findings.some(f => f.check === "ledger"), `${key}: ${value}`);
+    }
+  }
+  for (const header of ["", "allowance: 4\nallowance: 4", "cap: 20\ncap: 20", "allowance: 4\ncap: 20"]) {
+    const input = coordinatedLedger().replace("cap: 20", header);
+    assert.ok(checkPlan(input, coordinatedSpec, emptyPort).findings.some(f => f.check === "ledger"), header);
+  }
+});
 for (const scope of ["", "scope: AC 1\nscope: AC 2", "scope: AC 1, AC 1", "scope: AC 0", "scope: AC -1", "scope: AC 1.5", "scope: AC 4", "scope: 1", "scope: AC 1-2", "scope: AC 1,", "scope: none, AC 1"]) {
   test(`coordinated scope rejects ${JSON.stringify(scope)}`, () => {
     assert.ok(checkPlan(coordinatedLedger(), coordinatedSpec.replace("scope: AC 1, AC 2", scope), emptyPort).findings.some(f => f.check === "leg-scope"));

package/extensions/lib/plan-check.ts

@@ -1205,9 +1205,10 @@ function coordinatedMetadata(lines: string[], legs: ReturnType<typeof parseLegs>
   const sha = /^[a-f0-9]{7,40}$/;
   const base = one("base", sha);
   const iterations = one("iterations", /^(?:0|[1-9]\d*)$/);
-  const cap = one("cap", /^[1-9]\d*$/);
+  const budgets = [...header("allowance"), ...header("cap")];
+  if (budgets.length !== 1) add(budgets[0]?.i ?? 0, "expected exactly one allowance or cap header");
+  else if (!/^[1-9]\d*$/.test(budgets[0].value) || !Number.isSafeInteger(Number(budgets[0].value))) add(budgets[0].i, "allowance or cap must be a positive safe integer");
   if (!Number.isSafeInteger(Number(iterations))) add(0, "iterations must be a safe integer");
-  if (!Number.isSafeInteger(Number(cap))) add(0, "cap must be a safe integer");
   for (const [i, l] of lines.entries()) {
     const m = /^(base|seeded) ([^:]+):/.exec(l);
     if (m && !legs.some(leg => leg.repo === m[2].toLowerCase())) add(i, "foreign member header");

package/extensions/lib/telemetry-collect.test.ts

@@ -46,6 +46,18 @@ test("reopens match distinct string names, not position", () => {
   assert.equal(countReopens([{ status: "complete" }], [{ status: "in_progress" }]), 0);
 });
 
+test("allowance label changes between ledger refreshes never change reopen identity", () => {
+  const before = [
+    { name: "row 3", status: "complete", label: "2/5" },
+    { name: "row 4 (repo-b)", status: "complete", label: "1/4" },
+    { name: "G1: check", status: "complete" },
+  ];
+  const relabeled = before.map(task => task.label ? { ...task, label: "2/6" } : task);
+  assert.equal(countReopens(before, relabeled), 0);
+  assert.equal(countReopens(before, relabeled.map(task => ({ ...task, status: "in_progress" }))), 3);
+  assert.equal(countReopens(before, relabeled.map(task => ({ ...task, status: "pending" }))), 0);
+});
+
 test("insertedText joins edit newText values or returns write content", () => {
   assert.equal(insertedText({ path: "x", edits: [{ oldText: "a", newText: "b" }, { oldText: "c", newText: "d" }] }), "b\nd");
   assert.equal(insertedText({ path: "x", content: "body" }), "body");

package/extensions/phase-tracker.test.ts

@@ -536,7 +536,9 @@ test("ledger refresh completes only started implement and keeps failed, in-fligh
   for (const allCut of [true, false]) {
     const dir = tempCwd({ piGauntlet: { flowGuards: { enforce: false } } });
     const path = join(dir, "ledger.md");
-    const save = (status: string, pending = "") => writeFileSync(path, `# Ledger - loop engine\n${pending}\n| row | status | attempts | evidence |\n|---|---|---|---|\n| 1 | ${status} | 0 | check |\n\n## Decisions\n`);
+    execFileSync("git", ["init", "-q", dir]);
+    writeFileSync(join(dir, "spec.md"), "# Spec\n\n## Acceptance criteria\n- [ ] The tracker shows a readable step\n  in-scope\n");
+    const save = (status: string, pending = "") => writeFileSync(path, `# Ledger - loop engine\n**Spec:** \`spec.md\`\n${pending}\n| row | status | attempts | evidence |\n|---|---|---|---|\n| 1 | ${status} | 0 | check |\n\n## Decisions\n`);
     save(allCut ? "cut" : "failed");
     const branch = implementBranch().slice(0, -1);
     const h = harness({ cwd: dir, branch });

package/extensions/plan-tracker.test.ts

@@ -1,13 +1,14 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import registerPlanTracker, { validateSnapshot } from "./plan-tracker.ts";
 
 type ToolResult = {
   content: { type: string; text: string }[];
-  details: { action: string; tasks: { name: string; status: string }[]; error?: string };
+  details: { action: string; tasks: { name: string; status: string; label?: string }[]; error?: string };
 };
 
 function harness(branch: unknown[] = [], cwd = process.cwd()) {
@@ -384,14 +385,25 @@ test("legacy-invalid snapshot: first update is rejected listing legacy offenders
   assert.deepEqual(repaired.details.tasks.map((t) => t.status), ["complete", "skipped", "complete"]);
 });
 
+const descriptions = [
+  "Keep cut requirements visible", "Reject malformed allowance replies", "Verify loop behavior and recovery",
+  "Report failed checks", "Preserve completed work", "Start the next criterion",
+];
+const spec = (criteria = descriptions) => `# Spec\n\n## Acceptance criteria\n${criteria.map(text => `- [ ] ${text}`).join("\n")}\n`;
+function ledgerFixture(prefix: string) {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  execFileSync("git", ["init", "-q", dir]);
+  writeFileSync(join(dir, "spec.md"), spec(descriptions.map(text => `${text}\n  in-scope`)));
+  return dir;
+}
 const ledger = (rows: string[], tail = "", pending = "") => [
-  "# Ledger - loop engine", pending,
+  "# Ledger - loop engine", "**Spec:** `spec.md`", pending,
   "| row | status | attempts | evidence |", "|---|---|---|---|",
   ...rows.map(row => `| ${row} |`), "", "## Decisions", tail,
 ].join("\n");
 
 test("refresh projects ledger states, numeric pending targets and live leg mappings", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "plan-refresh-"));
+  const dir = ledgerFixture("plan-refresh-");
   const path = join(dir, "ledger.md");
   const cases = [
     {
@@ -425,7 +437,7 @@ test("refresh projects ledger states, numeric pending targets and live leg mappi
 });
 
 test("refresh replaces only whole ledger names, preserves Gn statuses and replays its snapshot", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "plan-refresh-kept-"));
+  const dir = ledgerFixture("plan-refresh-kept-");
   const path = join(dir, "ledger.md");
   writeFileSync(path, ledger(["1 | open | 0 |", "2 | open | 0 |", "3 | done | 1 | passed"], "row 3 done | passed | row 1"));
   const h = harness();
@@ -437,9 +449,9 @@ test("refresh replaces only whole ledger names, preserves Gn statuses and replay
   const result = await h.call({ action: "refresh", path });
   assert.equal(result.details.error, undefined);
   assert.deepEqual(result.details.tasks, [
-    { name: "row 3", status: "complete" },
+    { name: "row 3", status: "complete", label: descriptions[2] },
     { name: "G1: closed", status: "complete" }, { name: "G2: working", status: "in_progress" },
-    { name: "row 1", status: "pending" }, { name: "row 2", status: "pending" },
+    { name: "row 1", status: "pending", label: descriptions[0] }, { name: "row 2", status: "pending", label: descriptions[1] },
     { name: "row 4 notes", status: "pending" }, { name: "G3: pending", status: "pending" },
   ]);
   assert.deepEqual(validateSnapshot(result.details.tasks as any), []);
@@ -449,8 +461,235 @@ test("refresh replaces only whole ledger names, preserves Gn statuses and replay
   assert.equal(replay.widget(), h.widget());
 });
 
+test("allowance labels count retry decisions, preserve identity and render on every status surface", async () => {
+  const dir = ledgerFixture("plan-allowance-");
+  const path = join(dir, "ledger.md");
+  const text = ledger([
+    "1 | cut | 3 | deferred: #1", "2 | done | 0 | baseline", "3 | open | 2 | check",
+    "4 | failed | 7 | failed", "5 | done | 1 | passed", "6 | open | 0 | check",
+  ], [
+    "row 3 retry | hint | allowed attempts 5", "row 3 retry | next | allowed attempts 99",
+    "row 3 escalated | implModel round | allowed attempts 100", "cap +20 | historical | cap 40",
+    "row 4 retry | hint | allowed attempts 8", "row 5 done | passed | row 3",
+    "## Notes", "row 3 retry | not a decision | allowed attempts 101",
+    "## Leg mapping", "| row | ac | leg |", "|---|---|---|",
+    "| 1 | 1 | repo-a |", "| 2 | 2 | repo-a |", "| 3 | 3 | repo-b |",
+    "| 4 | 4 | repo-a |", "| 5 | 5 | repo-b |", "| 6 | 6 | repo-a |",
+  ].join("\n"), "allowance: 4\npending: 3 | repo-b | abc1234");
+  writeFileSync(path, text);
+  const h = harness();
+  await h.call({ action: "init", tasks: [{ name: "G1: fixed", status: "complete" }, "2/5: G2: pending"] });
+  const result = await h.call({ action: "refresh", path });
+  assert.equal(result.details.error, undefined);
+  assert.deepEqual(result.details.tasks, [
+    { name: "row 1 (repo-a)", status: "skipped", label: `${descriptions[0]} (repo-a)` },
+    { name: "row 2 (repo-a)", status: "skipped", label: `${descriptions[1]} (repo-a)` },
+    { name: "row 3 (repo-b)", status: "in_progress", label: `2/6: ${descriptions[2]} (repo-b)` },
+    { name: "row 4 (repo-a)", status: "failed", label: `7/5: ${descriptions[3]} (repo-a)` },
+    { name: "row 5 (repo-b)", status: "complete", label: `1/4: ${descriptions[4]} (repo-b)` },
+    { name: "G1: fixed", status: "complete" },
+    { name: "row 6 (repo-a)", status: "pending", label: `0/4: ${descriptions[5]} (repo-a)` },
+    { name: "2/5: G2: pending", status: "pending" },
+  ]);
+  assert.match(h.widget()!, /2\/6: Verify loop behavior and recovery \(repo-b\)$/);
+  assert.doesNotMatch(h.widget()!, /row 3/);
+  assert.match(result.content[0].text, /\[2\] row 3 \(repo-b\) \| 2\/6: Verify loop behavior and recovery \(repo-b\)/);
+  const status = await h.call({ action: "status" });
+  assert.match(status.content[0].text, /\[4\] row 5 \(repo-b\) \| 1\/4: Preserve completed work \(repo-b\)/);
+  const rendered = h.tool().renderResult(status, {}, h.theme).text!;
+  assert.match(rendered, /row 3 \(repo-b\) \| 2\/6: Verify loop behavior and recovery \(repo-b\)/);
+  assert.match(rendered, /row 4 \(repo-a\) \| 7\/5: Report failed checks \(repo-a\)/);
+  const replay = harness([{ type: "message", message: { role: "toolResult", toolName: "plan_tracker", details: status.details } }]);
+  await replay.fire("session_start");
+  assert.equal(replay.widget(), h.widget());
+  assert.deepEqual((await replay.call({ action: "status" })).details.tasks, status.details.tasks);
+
+  writeFileSync(path, text.replace("allowance: 4", "allowance: 7"));
+  const raised = await h.call({ action: "refresh", path });
+  assert.deepEqual(raised.details.tasks.map(t => [t.name, t.status]), result.details.tasks.map(t => [t.name, t.status]));
+  assert.equal(raised.details.tasks.find(t => t.name === "row 3 (repo-b)")!.label, `2/9: ${descriptions[2]} (repo-b)`);
+  assert.equal(raised.details.tasks.find(t => t.name === "row 5 (repo-b)")!.label, `1/7: ${descriptions[4]} (repo-b)`);
+  assert.equal(raised.details.tasks.length, result.details.tasks.length);
+  writeFileSync(path, text.replace("allowance: 4", "cap: 49"));
+  const legacy = await h.call({ action: "refresh", path });
+  assert.equal(legacy.details.error, undefined);
+  assert.deepEqual(legacy.details.tasks.filter(t => t.name.startsWith("row ")).map(t => t.label),
+    descriptions.map((description, i) => `${description} (${[2, 4].includes(i) ? "repo-b" : "repo-a"})`));
+});
+
+test("allowance labels tolerate surrounding whitespace in the header value", async () => {
+  const dir = ledgerFixture("plan-allowance-whitespace-");
+  const path = join(dir, "ledger.md");
+  const h = harness();
+  const labels = [];
+  for (const header of ["allowance: 4", "allowance:  4", "allowance: 4 "]) {
+    writeFileSync(path, ledger(["1 | open | 0 |"], "", header));
+    const result = await h.call({ action: "refresh", path });
+    assert.equal(result.details.error, undefined, header);
+    labels.push(result.details.tasks[0].label);
+  }
+  assert.deepEqual(labels, Array(3).fill(`0/4: ${descriptions[0]}`));
+});
+
+test("single-repo labels are projection-only and cannot enter through init or add", async () => {
+  const dir = ledgerFixture("plan-label-input-");
+  const path = join(dir, "ledger.md");
+  writeFileSync(path, ledger(["3 | open | 2 | check"], "row 3 retry | hint | allowed attempts 99", "allowance: 4"));
+  const h = harness();
+  const projected = await h.call({ action: "refresh", path });
+  assert.deepEqual(projected.details.tasks, [{ name: "row 3", status: "pending", label: `2/5: ${descriptions[2]}` }]);
+  assert.match(h.widget()!, /2\/5: Verify loop behavior and recovery$/);
+  const init = await h.call({ action: "init", tasks: [{ name: "row 3", status: "in_progress", label: "9/9" }] });
+  assert.deepEqual(init.details.tasks, [{ name: "row 3", status: "in_progress" }]);
+  const added = await h.call({ action: "add", tasks: [{ name: "G1: check", status: "pending", label: "9/9" }] });
+  assert.ok(added.details.tasks.every(t => !Object.hasOwn(t, "label")));
+  const objectSchema = h.parameters().args[0].tasks.args[0].args[0].args[0][1];
+  assert.deepEqual(Object.keys(objectSchema.args[0]), ["name", "status"]);
+});
+
+test("refresh resolves the owning root, normalizes original AC text, and keeps labels stable across status changes", async () => {
+  const dir = ledgerFixture("plan-descriptions-");
+  const nested = join(dir, "doc", "plans");
+  mkdirSync(nested, { recursive: true });
+  const path = join(nested, "ledger.md");
+  writeFileSync(join(dir, "spec.md"), [
+    "# Spec", "```md", "## Acceptance criteria", "- [ ] Not a criterion", "```",
+    "## Acceptance Criteria", "- [x] Keep   cut requirements", "  visible",
+    "  deferred: #1", "    disposition continuation", "- [ ] Reject malformed allowance replies",
+    "  elsewhere: repo-b#2", "- [ ] Verify loop behavior", "  and recovery | row 99 is only text",
+    "  venue: staging - observe completion", "## Design", "- [ ] Not an acceptance criterion",
+  ].join("\n"));
+  const text = ledger(["1 | cut | 0 | deferred", "2 | done | 0 | baseline", "3 | open | 2 | check"], "", "allowance: 4");
+  writeFileSync(path, text);
+  const h = harness([], nested);
+  const first = await h.call({ action: "refresh", path: "ledger.md" });
+  assert.equal(first.details.error, undefined);
+  assert.deepEqual(first.details.tasks.map(t => t.label), [
+    "Keep cut requirements visible", descriptions[1], "2/4: Verify loop behavior and recovery | row 99 is only text",
+  ]);
+  assert.match(first.content[0].text, /row 3 \| 2\/4: Verify loop behavior and recovery \| row 99 is only text/);
+  for (const [status, tail, pending] of [
+    ["failed", "", ""], ["failed", "", "pending: 3 | home | abc1234"],
+    ["done", "row 3 done | passed | none", ""],
+  ]) {
+    writeFileSync(path, text.replace("| 3 | open", `| 3 | ${status}`).replace("allowance: 4", `allowance: 4\n${pending}`) + tail);
+    const next = await h.call({ action: "refresh", path });
+    assert.equal(next.details.error, undefined);
+    assert.deepEqual(next.details.tasks.map(t => [t.name, t.label]), first.details.tasks.map(t => [t.name, t.label]));
+  }
+  writeFileSync(join(dir, "spec.md"), spec([descriptions[0], descriptions[1], "Verify amended behavior"]));
+  const amended = await h.call({ action: "refresh", path });
+  assert.equal(amended.details.tasks[2].name, "row 3");
+  assert.equal(amended.details.tasks[2].label, "2/4: Verify amended behavior");
+  assert.equal(amended.details.tasks.length, 3);
+});
+
+test("coordinated labels use mapped original AC indices, including shared criteria", async () => {
+  const dir = ledgerFixture("plan-original-ac-");
+  const path = join(dir, "ledger.md");
+  writeFileSync(path, ledger(["1 | cut | 0 | cut", "2 | open | 1 | check", "3 | open | 0 | check"], [
+    "## Leg mapping", "| row | ac | leg |", "|---|---|---|",
+    "| 1 | 2 | repo-a |", "| 2 | 3 | repo-a |", "| 3 | 3 | repo-b |",
+  ].join("\n"), "allowance: 4"));
+  const result = await harness().call({ action: "refresh", path });
+  assert.equal(result.details.error, undefined);
+  assert.deepEqual(result.details.tasks.map(t => [t.name, t.label]), [
+    ["row 1 (repo-a)", `${descriptions[1]} (repo-a)`],
+    ["row 2 (repo-a)", `1/4: ${descriptions[2]} (repo-a)`],
+    ["row 3 (repo-b)", `0/4: ${descriptions[2]} (repo-b)`],
+  ]);
+});
+
+test("refresh rejects an unresolvable repository root without changing initialized tasks", async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "plan-no-checkout-"));
+  try {
+    execFileSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], { stdio: "ignore" });
+    t.skip("temporary directory is inside a git repository");
+    return;
+  } catch {}
+  writeFileSync(join(dir, "spec.md"), spec(["Keep prior tasks"]));
+  const path = join(dir, "ledger.md");
+  writeFileSync(path, ledger(["1 | open | 0 |"], "", "allowance: 4"));
+  const h = harness([], dir);
+  const initial = await h.call({ action: "init", tasks: [{ name: "G1: closed", status: "complete" }, "G2: pending"] });
+  const result = await h.call({ action: "refresh", path });
+  assert.match(result.details.error!, /cannot resolve repository root for Spec reference/);
+  assert.equal(result.details.tasks, undefined);
+  assert.deepEqual((await h.call({ action: "status" })).details.tasks, initial.details.tasks);
+});
+
+test("refresh rejects missing specs, missing criteria and empty descriptions atomically", async () => {
+  const dir = ledgerFixture("plan-spec-errors-");
+  const path = join(dir, "ledger.md");
+  const valid = ledger(["1 | open | 0 | check"], "", "allowance: 4");
+  writeFileSync(path, valid);
+  const h = harness();
+  const initial = await h.call({ action: "refresh", path });
+  assert.equal(initial.details.error, undefined);
+  const widget = h.widget();
+  const cases = [
+    { text: valid.replace("**Spec:** `spec.md`", ""), spec: spec(), error: /missing Spec reference/ },
+    { text: valid.replace("`spec.md`", "`absent.md`"), spec: spec(), error: /cannot read spec .*absent\.md:/ },
+    { text: valid, spec: "# Spec\n## Design\n- [ ] Not an AC", error: /row 1: spec .*spec\.md AC 1 is missing/ },
+    { text: valid, spec: spec(["  \n  deferred: #1"]), error: /row 1: spec .*spec\.md AC 1 has an empty description/ },
+    { text: ledger(["7 | open | 0 | check"]), spec: spec(), error: /row 7: spec .*spec\.md AC 7 is missing/ },
+    { text: valid + "\n## Leg mapping\n| row | ac | leg |\n|---|---|---|\n| 1 | 9 | repo-a |", spec: spec(), error: /row 1: spec .*spec\.md AC 9 is missing/ },
+  ];
+  for (const row of cases) {
+    writeFileSync(path, row.text);
+    writeFileSync(join(dir, "spec.md"), row.spec);
+    const result = await h.call({ action: "refresh", path });
+    assert.match(result.details.error!, row.error);
+    assert.equal(result.details.tasks, undefined);
+    assert.equal(h.widget(), widget);
+    assert.deepEqual((await h.call({ action: "status" })).details.tasks, initial.details.tasks);
+  }
+});
+
+test("status rows round-trip through the brief identity grammar without description drift or duplicate tasks", async () => {
+  const contract = readFileSync(new URL("../skills/gauntlet-resume/reference/brief-contract.md", import.meta.url), "utf8");
+  const suffix = new RegExp(contract.match(/suffix pattern `([^`]+)`/)![1]);
+  const prefix = new RegExp(contract.match(/prefix pattern `([^`]+)`/)![1]);
+  const canonical = new RegExp(contract.match(/canonical pattern `([^`]+)`/)![1]);
+  const restoreName = (name: string) => {
+    const labeled = suffix.exec(name);
+    if (labeled) return labeled[1];
+    const plain = name.replace(prefix, "");
+    return canonical.test(plain) ? plain : name;
+  };
+  for (const [input, expected] of [
+    ["row 3", "row 3"], ["2/5: row 3", "row 3"], ["2/5: row 3 (repo-b)", "row 3 (repo-b)"],
+    ["row 3 (repo-b) | 2/5: Verify | row 99", "row 3 (repo-b)"],
+    ["2/5: G3: pending", "2/5: G3: pending"], ["G1: row 3 | description", "G1: row 3 | description"],
+    ["row 3 notes | description", "row 3 notes | description"],
+  ]) assert.equal(restoreName(input), expected);
+  const dir = ledgerFixture("plan-brief-roundtrip-");
+  const path = join(dir, "ledger.md");
+  writeFileSync(join(dir, "spec.md"), spec([descriptions[0], descriptions[1], `${descriptions[2]} | row 99 is text`]));
+  const text = ledger(["2 | cut | 0 | cut", "3 | done | 2 | passed"], "row 3 done | passed | none", "allowance: 5");
+  writeFileSync(path, text);
+  const h = harness();
+  await h.call({ action: "init", tasks: [{ name: "G1: failed", status: "failed" }, { name: "G2: repair", status: "in_progress" }, "2/5: G3: pending"] });
+  await h.call({ action: "refresh", path });
+  const status = await h.call({ action: "status" });
+  const brief = status.content[0].text;
+  const statuses: Record<string, string> = { "\u2713": "complete", "\u2192": "in_progress", "\u2717": "failed", "\u2298": "skipped", "\u25cb": "pending" };
+  const restored = [...brief.matchAll(/^\s*([\u2713\u2192\u2717\u2298\u25cb]) \[\d+\] (.+)$/gm)]
+    .map(([, glyph, name]) => ({ name: restoreName(name), status: statuses[glyph] }));
+  assert.deepEqual(restored, status.details.tasks.map(({ name, status }) => ({ name, status })));
+  const resumed = harness();
+  const init = await resumed.call({ action: "init", tasks: restored });
+  assert.equal(init.details.error, undefined);
+  assert.ok(init.details.tasks.every(t => !Object.hasOwn(t, "label")));
+  writeFileSync(path, text.replace("allowance: 5", "allowance: 6"));
+  const refreshed = await resumed.call({ action: "refresh", path });
+  assert.deepEqual(refreshed.details.tasks.map(({ name, status }) => ({ name, status })), restored);
+  assert.match(refreshed.content[0].text, /row 3 \| 2\/6: Verify loop behavior and recovery \| row 99 is text/);
+  assert.equal(refreshed.details.tasks.filter(t => t.name === "row 3").length, 1);
+});
+
 test("refresh rejects unreadable or malformed ledgers atomically, including absent numeric pending rows", async () => {
-  const dir = mkdtempSync(join(tmpdir(), "plan-refresh-error-"));
+  const dir = ledgerFixture("plan-refresh-error-");
   const path = join(dir, "ledger.md");
   const valid = ledger(["1 | open | 0 |"]);
   const h = harness();
@@ -461,8 +700,9 @@ test("refresh rejects unreadable or malformed ledgers atomically, including abse
     { name: "unreadable path", path: join(dir, "absent.md"), text: valid, error: /refresh: cannot read .*absent\.md:/ },
     { name: "wrong discriminator", path, text: "# Plan", error: /line 1 is "# Plan", not a loop ledger/ },
     { name: "missing header", path, text: valid.replace("| row | status | attempts | evidence |", "| row | state | attempts | evidence |"), error: /row table malformed at line \d+/ },
-    { name: "nonnumeric row", path, text: valid.replace("| 1 | open", "| x | open"), error: /row table malformed at line 5/ },
-    { name: "invalid status", path, text: valid.replace("| 1 | open", "| 1 | unknown"), error: /row table malformed at line 5/ },
+    { name: "nonnumeric row", path, text: valid.replace("| 1 | open", "| x | open"), error: /row table malformed at line 6/ },
+    { name: "invalid status", path, text: valid.replace("| 1 | open", "| 1 | unknown"), error: /row table malformed at line 6/ },
+    ...["x", "-1", "1.5", ""].map(attempts => ({ name: `invalid attempts ${attempts}`, path, text: valid.replace("| 0 |", `| ${attempts} |`), error: /row table malformed at line 6/ })),
     { name: "absent pending row", path, text: "pending: 2 | home | abc1234", error: /pending: names row 2 which is absent/ },
     { name: "zero pending row", path, text: "pending: 0 | home | abc1234", error: /pending: names row 0 which is absent/ },
     { name: "leading-zero absent row", path, text: "pending: 02 | home | abc1234", error: /pending: names row 2 which is absent/ },