pi-gauntlet 7.33.0 → 7.34.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## v7.34.0 - 2026-10-26
+
+### Changed
+
+- **Breaking:** `piGauntlet.loopEngine.maxIterations` is removed, not aliased; use `piGauntlet.loopEngine.maxIterationsPerRow` (default 4, integer floor 1). The loop seeds a durable ledger `cap:` from non-cut rows times that multiplier plus one seed dispatch. Cuts and reopening preserve the cap; redraw recomputes it. Clean cap stops accept durable `cap +N` grants without resetting attempts or iterations, and resume restores the ledger cap without settings. Legacy ledgers missing `cap:` stop for a grant based on consumed iterations.
+- Drafted tree-wide or set-wide negative acceptance rows split into one row per family explicitly enumerated in Design, preserving every outcome. An absent, partial or unrelated enumeration stops spec-writing for clarification; ticket rows stay verbatim.
+- pi-cohort peer floor raised to 7.5.0.
+
 ## v7.33.0 - 2026-10-26
 
 ### Changed

package/README.md

@@ -126,7 +126,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) ≥ 0.85.1 - tested minimum for sequential `phase_tracker` tool execution, which persists a tracker update before a later tool call in the same model message.
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.4.5 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) >= 7.5.0 - required peer package, including binary-safe worktree patches; it also lets a persona with `subagent` in `tools:` start with inherited extensions ([pi-cohort #26](https://github.com/jjuraszek/pi-cohort/issues/26)), which multi-PR `gatekeep-pr` needs. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics. A wave of N >= 1 tasks dispatches its implementers and first spec reviews as one chain call. `subagent-driven-development` stops before dispatch on unsupported installs; there is no older-runtime fallback.
 
 Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both. At each pi-gauntlet release, set the pi-cohort peer minimum and README floor together to the newest released pi-cohort version; `/skill:release` checks the registry before proceeding.
 

package/extensions/lib/gauntlet-settings.test.ts

@@ -21,12 +21,36 @@ import {
 } from "./gauntlet-settings.ts";
 
 test("loopEngine resolves defaults, integers, clamps, and malformed values", () => {
-  for (const [raw, expected, warns] of [[undefined, 30, false], [7, 7, false], [0, 1, false], [-3, 1, false], [1.5, 30, true], ["5", 30, true]] as const) {
-    const result = resolveLoopEngine({ loopEngine: { maxIterations: raw } });
-    assert.equal(result.maxIterations, expected);
-    assert.equal(Boolean(result.warning), warns);
+  const warning = "loopEngine.maxIterationsPerRow must be an integer; using default 4";
+  for (const [raw, expected, expectedWarning] of [
+    [undefined, 4, undefined], [7, 7, undefined], [0, 1, undefined], [-3, 1, undefined],
+    ["4", 4, warning], [4.5, 4, warning], [true, 4, warning], [null, 4, warning],
+  ] as const) {
+    assert.deepEqual(resolveLoopEngine({ loopEngine: { maxIterationsPerRow: raw } }), {
+      maxIterationsPerRow: expected, warning: expectedWarning,
+    });
   }
-  assert.deepEqual(resolveLoopEngine({}), { maxIterations: 30, warning: undefined });
+  assert.deepEqual(resolveLoopEngine({}), { maxIterationsPerRow: 4, warning: undefined });
+});
+
+test("loopEngine ignores the removed key by own-property presence and orders warnings", () => {
+  const removed = "loopEngine.maxIterations is removed; set loopEngine.maxIterationsPerRow";
+  for (const raw of [30, undefined, null, false]) {
+    assert.deepEqual(resolveLoopEngine({ loopEngine: { maxIterations: raw } }), {
+      maxIterationsPerRow: 4, warning: removed,
+    });
+  }
+  for (const [raw, expected, warning] of [
+    [7, 7, removed],
+    ["4", 4, removed + "; loopEngine.maxIterationsPerRow must be an integer; using default 4"],
+  ] as const) {
+    assert.deepEqual(resolveLoopEngine({ loopEngine: { maxIterations: 99, maxIterationsPerRow: raw } }), {
+      maxIterationsPerRow: expected, warning,
+    });
+  }
+  assert.deepEqual(resolveLoopEngine({ loopEngine: Object.create({ maxIterations: 99 }) }), {
+    maxIterationsPerRow: 4, warning: undefined,
+  });
 });
 
 const CUSTOM_TEST_COMMANDS = ["make ci", "pytest"];

package/extensions/lib/gauntlet-settings.ts

@@ -11,7 +11,7 @@ export interface PiGauntlet {
   flowGuards?: { enforce?: unknown; specDirs?: unknown };
   verifyBeforeShip?: { testCommands?: unknown; warningReference?: unknown };
   escalationLoop?: { implModel?: unknown };
-  loopEngine?: { maxIterations?: unknown };
+  loopEngine?: { maxIterationsPerRow?: unknown; maxIterations?: unknown };
   phaseModels?: { plan?: unknown; implement?: unknown; verify?: unknown; ship?: unknown };
   telemetry?: { enabled?: unknown; dir?: unknown; buckets?: unknown };
 }
@@ -93,11 +93,19 @@ export function resolveClosureReview(g: PiGauntlet): ClosureReviewResolved {
   return { model, enforce, maxFixRounds };
 }
 
-export function resolveLoopEngine(g: PiGauntlet): { maxIterations: number; warning: string | undefined } {
-  const raw = g.loopEngine?.maxIterations;
-  if (raw === undefined) return { maxIterations: 30, warning: undefined };
-  if (typeof raw === "number" && Number.isInteger(raw)) return { maxIterations: Math.max(1, raw), warning: undefined };
-  return { maxIterations: 30, warning: "loopEngine.maxIterations must be an integer; using default 30" };
+export function resolveLoopEngine(g: PiGauntlet): { maxIterationsPerRow: number; warning: string | undefined } {
+  const loop = g.loopEngine;
+  const raw = loop?.maxIterationsPerRow;
+  const valid = typeof raw === "number" && Number.isInteger(raw);
+  const maxIterationsPerRow = valid ? Math.max(1, raw) : 4;
+  const warnings: string[] = [];
+  if (loop && Object.hasOwn(loop, "maxIterations")) {
+    warnings.push("loopEngine.maxIterations is removed; set loopEngine.maxIterationsPerRow");
+  }
+  if (raw !== undefined && !valid) {
+    warnings.push("loopEngine.maxIterationsPerRow must be an integer; using default 4");
+  }
+  return { maxIterationsPerRow, warning: joinWarn(warnings) };
 }
 
 export interface EscalationLoopResolved {

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

@@ -16,7 +16,9 @@ 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", () => {
-  assert.deepEqual(checkPlan(ledger(), ledgerSpec, { exists: () => false, glob: () => [] }), []);
+  for (const input of [ledger(), ledger().replace("iterations: 0\n", "iterations: 0\ncap: 97\n")]) {
+    assert.deepEqual(checkPlan(input, ledgerSpec, { exists: () => false, glob: () => [] }), []);
+  }
 });
 for (const [name, rows] of Object.entries({
   missing: ["1 | open | 0 |"],

package/extensions/phase-tracker.test.ts

@@ -1404,11 +1404,18 @@ test("gauntlet_setting escalationLoop: setting absent -> ctx-derived main-loop m
 });
 
 test("gauntlet_setting loopEngine resolves the key", async () => {
-  const h = harness({ cwd: tempCwd({ piGauntlet: { loopEngine: { maxIterations: 8 } } }) });
-  const tool = h.tools.find(t => t.name === "gauntlet_setting")!;
-  const result = await tool.execute("loop", { key: "loopEngine" }, undefined, undefined, h.ctx) as any;
-  assert.equal(result.details.key, "loopEngine");
-  assert.equal(result.details.maxIterations, 8);
+  for (const [loopEngine, expected, warning] of [
+    [undefined, 4, undefined],
+    [{ maxIterationsPerRow: 8 }, 8, undefined],
+    [{ maxIterations: 99, maxIterationsPerRow: "4" }, 4,
+      "loopEngine.maxIterations is removed; set loopEngine.maxIterationsPerRow; loopEngine.maxIterationsPerRow must be an integer; using default 4"],
+  ] as const) {
+    const h = harness({ cwd: tempCwd({ piGauntlet: { loopEngine } }) });
+    const tool = h.tools.find(t => t.name === "gauntlet_setting")!;
+    const result = await tool.execute("loop", { key: "loopEngine" }, undefined, undefined, h.ctx) as any;
+    assert.deepEqual(result.details, { key: "loopEngine", maxIterationsPerRow: expected, warning, errors: [] });
+    assert.equal(Object.hasOwn(result.details, "maxIterations"), false);
+  }
 });
 
 test("gauntlet_setting loopEngine composes settings load warnings", async () => {
@@ -1416,9 +1423,11 @@ test("gauntlet_setting loopEngine composes settings load warnings", async () =>
   writeFileSync(join(dir, ".pi/settings.json"), "{");
   const h = harness({ cwd: dir });
   const result = await h.tools.find(t => t.name === "gauntlet_setting")!.execute("loop", { key: "loopEngine" }, undefined, undefined, h.ctx) as any;
-  assert.equal(result.details.maxIterations, 30);
+  assert.equal(result.details.key, "loopEngine");
+  assert.equal(result.details.maxIterationsPerRow, 4);
+  assert.equal(Object.hasOwn(result.details, "maxIterations"), false);
   assert.ok(result.details.errors.length);
-  assert.match(result.details.warning, /gauntlet settings load error/);
+  assert.equal(result.details.warning, `⚠️ gauntlet settings load error (using defaults): ${result.details.errors.join("; ")}`);
 });
 
 test("ledger handler stamps after brainstorm and skipped plan, then admits implement", async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "7.33.0",
+  "version": "7.34.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",
@@ -62,7 +62,7 @@
     "test": "node scripts/ci.mjs"
   },
   "peerDependencies": {
-    "pi-cohort": ">=7.4.5"
+    "pi-cohort": ">=7.5.0"
   },
   "dependencies": {
     "yaml": "^2.9.0"

package/skills/brainstorming/reference/ticket-acceptance.md

@@ -42,6 +42,7 @@ Apply these integrity classes inline without invoking ticket shaping. Preserve e
 |---|---|
 | Wishful | Rewrite to the design's observable with design-sourced baseline, target, and measurement |
 | Tautological | Rewrite to a design-sourced, already-enumerated set or observable |
+| Tree-wide | Split a drafted row requiring zero/no findings of one or several kinds anywhere in or across a tree or set into one row per family from the explicit complete enumeration in Design for that row, covering every kind it names; give each family's own observable and preserve every outcome across the resulting rows. For an absent, partial, or unrelated enumeration, stop before writing, quote the row, and request the complete enumeration in Design. Keep this recovery drafted-only: a ticket row of this shape stays one verbatim row; require human ticket repair through `/skill:shape-ticket` before approval to split it |
 | Unspecified-but-binding | Resolve the value from Design and record the resolution there; ask the user for a missing value |
 | External-input | Ask the user for the external yardstick before writing |
 | Post-deployment | Rewrite to a pre-production observation when available, retaining `venue:`; move production-only observations to a tracked, non-blocking `Post-deployment housekeeping` Design clause, never an AC row |

package/skills/gauntlet-resume/SKILL.md

@@ -144,9 +144,9 @@ owning skill **without** its reset-bearing entry:
 | brainstorm | [brainstorming checklist](../brainstorming/SKILL.md#checklist) | on-disk state decides the step: draft marker on line 1 of the spec file -> step 4; spec title -> step 8. Never `/skill:brainstorming` entry (it resets both trackers) |
 | approved spec with `**Engine:** loop`, no ledger | loop-implementation | after check 6, arm with `start brainstorm`, then `skip brainstorm resume: <spec path>` before driver admission; carry absolute worktree/spec paths and plan directory through Entry steps 1-5 per `reference/reconstruction.md` "Spec without plan": settings step 1, verification step 2, driver's plan skip step 3, ledger creation step 4, check/commit and implement start step 5; no writing-plans body or task tracker |
 | plan with task engine | writing-plans body | skip its `start plan` call (already in_progress) |
-| implement with line-1 ledger | loop-implementation | complete `reference/reconstruction.md` "Spec with ledger" ordered restore, cited by `reference/brief-contract.md`'s call table: entry checks 1-6, brainstorm start/skip, plan start/check/skip with reason `resume: <spec> (loop engine)`, implement start, no task tracker; state the entire ordered sequence explicitly even when entry checks are already reported as passed; then continue at step 5 (`Before each dispatch`), preserving ledger iterations/retry data; dirty tree stops before dispatch; reuse the existing ledger |
+| implement with line-1 ledger | loop-implementation | complete `reference/reconstruction.md` "Spec with ledger" ordered restore, cited by `reference/brief-contract.md`'s call table: entry checks 1-6, brainstorm start/skip, plan start/check/skip with reason `resume: <spec> (loop engine)`, implement start, no task tracker; state the entire ordered sequence explicitly even when entry checks are already reported as passed; then continue at step 5 (`Before each dispatch`), applying the shared cap boundary in reconstruction step 4 before continuation and preserving ledger cap, iterations/retry data; dirty tree stops before dispatch; reuse the existing ledger |
 | implement with task plan | subagent-driven-development | re-validate `<task>` first (re-run its `Tests:`), then the task loop from the first non-complete task |
-| verify with `Ledger:` (including ship-stage ledger briefs restored at verify) | /skill:loop-implementation | read `After the loop` and its references; continue from step 1, full ledger verification, after the already-restored `start verify`; retain whole-diff code review, happy path when triggered, fresh conformance review and finishing; no task-tracker calls |
+| verify with `Ledger:` (including ship-stage ledger briefs restored at verify) | /skill:loop-implementation | apply the shared cap boundary in `reference/reconstruction.md` "Spec with ledger" step 4 before verification; render cap and restored ledger state; read `After the loop` and its references; continue from step 1, full ledger verification, after the already-restored `start verify`; retain whole-diff code review, happy path when triggered, fresh conformance review and finishing; no task-tracker calls |
 | verify without `Ledger:` | verification-before-completion | full conformance gate; nothing carried over |
 
 ## Red flags — STOP

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

@@ -149,12 +149,12 @@ announcement without re-resolving it.
 |---|---|
 | brainstorm | `start brainstorm`; `substep` if the brief shows one |
 | plan | `start brainstorm`; `skip brainstorm S`; `start plan`; `substep` if shown |
-| implement with ledger | Read ledger line 1; resolve its path-only `**Spec:**` header; run entry checks 1-6, naming check 6 (Grant field); `start brainstorm`; `skip brainstorm` reason `resume: <spec path>`; `start plan`; `plan_check` on the absolute ledger path; on PASS `skip plan` reason `resume: <spec> (loop engine)` using the resolved absolute spec path as `<spec>`; `start implement`; no `plan_tracker init`; render rows and last decision; continue at loop step 5. Follow `reconstruction.md` "Spec with ledger" for this self-contained ordered restore. On FAIL stop with findings, never `## Plan repair` or writing-plans. |
+| implement with ledger | Read ledger line 1; resolve its path-only `**Spec:**` header; run entry checks 1-6, naming check 6 (Grant field); `start brainstorm`; `skip brainstorm` reason `resume: <spec path>`; `start plan`; `plan_check` on the absolute ledger path; on PASS `skip plan` reason `resume: <spec> (loop engine)` using the resolved absolute spec path as `<spec>`; `start implement`; no `plan_tracker init`; apply the shared cap boundary in `reconstruction.md` "Spec with ledger" step 4 before continuation; render cap, rows and decisions; continue at loop step 5. Follow `reconstruction.md` "Spec with ledger" for this self-contained ordered restore. On FAIL stop with findings, never `## Plan repair` or writing-plans. |
 | implement with task plan | `start brainstorm`; `skip brainstorm S`; `start plan`; `plan_check({ planPath })`; on FAIL run `## Plan repair`; on PASS `skip plan R`; `start implement`; `substep` if shown; `plan_tracker init` |
-| verify | as implement through `skip plan R`, then `skip implement R`; `start verify`; `substep` if shown; `plan_tracker init` |
+| verify | `start brainstorm`; `skip brainstorm S`; `start plan`; `plan_check({ planPath })`; on FAIL run `## Plan repair`; on PASS `skip plan R`, then `skip implement R`; `start verify`; `substep` if shown; `plan_tracker init`. Never call `start implement`. |
 | ship | as verify. Restoration stops at verify in_progress: `complete verify` needs a fresh conformance dispatch and `skip verify` would bypass a real gate. Announce that the closure review re-runs before ship |
 
-For a ledger brief, pair by the ledger's path-only `**Spec:**` header, not basename; require the resolved spec under `flowGuards.specDirs` and the ledger under its sibling plans directory. Keep same-repository binding and human confirmation. For verify/ship ledger briefs, use the ledger restore sequence through `skip plan`, then `skip implement R`; `start verify`, with no task tracker. Continue verify/ship ledger briefs in `/skill:loop-implementation` `After the loop` from step 1 (full ledger verification), after the already-restored `start verify`, retaining whole-diff code review, happy path when triggered, fresh conformance review and finishing without task-tracker calls. Ship still stops at verify for fresh conformance.
+For a ledger brief, pair by the ledger's path-only `**Spec:**` header, not basename; require the resolved spec under `flowGuards.specDirs` and the ledger under its sibling plans directory. Keep same-repository binding and human confirmation. For every ledger brief apply the shared cap boundary in `reconstruction.md` "Spec with ledger" step 4 before dispatch or verification, retaining its legacy stop and original-phase grant continuation. For verify/ship ledger briefs, use the ledger restore sequence through `skip plan`, then `skip implement R`; `start verify`, with no task tracker. Continue verify/ship ledger briefs in `/skill:loop-implementation` `After the loop` from step 1 (full ledger verification), after the already-restored `start verify`, retaining whole-diff code review, happy path when triggered, fresh conformance review and finishing without task-tracker calls. Ship still stops at verify for fresh conformance.
 
 `planPath` (task-plan implement onward): the brief carries none. Resolve as reconstruction does
 (`reconstruction.md`, "Candidates", including its `flowGuards.specDirs` resolution): the

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

@@ -80,7 +80,7 @@ After confirmation:
 1. Read ledger line 1: require `# Ledger - loop engine`. Resolve its path-only `**Spec:**` header to an absolute spec path under the worktree's configured spec directories, not by basename. Run SKILL.md entry checks 1-6 in order, including check 6, **Grant field**, on that spec, before any tracker mutation.
 2. Call `phase_tracker({ action: "start", phase: "brainstorm" })`, then `phase_tracker({ action: "skip", phase: "brainstorm", reason: "resume: <spec path>" })`, then `phase_tracker({ action: "start", phase: "plan" })`.
 3. Call `plan_check({ planPath: <absolute ledger path> })`. On FAIL, stop with findings, retaining plan in_progress; never enter `## Plan repair` or writing-plans. On PASS, call `phase_tracker({ action: "skip", phase: "plan", reason: "resume: <spec> (loop engine)" })`, then `phase_tracker({ action: "start", phase: "implement" })`. Use the resolved absolute spec path as `<spec>` in the reason. Never call `plan_tracker init`.
-4. Read `/skill:loop-implementation`; resolve its Entry settings/maxIterations without creating or overwriting the ledger. Restore base, verification, iterations, row attempts, funding and retry allowances from the ledger/spec and branch. Render rows and last decision. A dirty tree stops before any dispatch using the driver's dirty-tree stop note; preserve changes for the human.
+4. **Shared cap boundary (every ledger restore, before phase continuation).** Read `/skill:loop-implementation`. Skip Entry step 1 entirely; settings resolution and its unavailable-tool stop apply only to fresh seeding. Restore base, verification, iterations, `cap:`, row attempts, funding and retry allowances from the ledger/spec and branch without overwriting it. Render `cap: <n>`, rows, iterations, attempts, funding, retry allowances and all decisions; distinguish the latest operational `row <n> ...` decision from the last physical history line. A dirty tree takes the driver's discard-authorization stop without offering a cap grant. On a clean ledger missing `cap:`, stop with `ledger has no cap: line - seeded under the old loopEngine contract`, even when every row is closed. Use the driver's legacy `cap +N` grant (durable iterations + N), never settings. After the grant continue the original phase: implement at `Before each dispatch`; verify/ship at `After the loop` step 1, never reseed.
 5. Continue at loop step 5, the delivered driver's `Before each dispatch`, with durable iterations and retry data. Never reset counters or reseed a validated seed.
 
 ## Spec with plan

package/skills/loop-implementation/SKILL.md

@@ -9,7 +9,7 @@ Run this driver in the main session. Carry the absolute implementation worktree
 
 ## Entry
 
-1. Read project overrides below. Resolve `gauntlet_setting({ key: "loopEngine" })` and retain `maxIterations` (default 30). Stop on an unavailable settings tool.
+1. Read project overrides below. Resolve `gauntlet_setting({ key: "loopEngine" })` and retain `maxIterationsPerRow` (default 4). Stop on an unavailable settings tool.
 2. Resolve verification once using this ordered table. Print `verification command: <command> (<source>)`.
 
 | Observed configuration | Action |
@@ -27,6 +27,7 @@ Run this driver in the main session. Carry the absolute implementation worktree
 base: <HEAD SHA before skeleton>
 verification: <resolved command>
 iterations: 0
+cap: <n>
 
 | row | status | attempts | evidence |
 |---|---|---|---|
@@ -35,26 +36,26 @@ iterations: 0
 ## Decisions
 ```
 
-Use the actual repo-relative spec path alone in the Spec header. Read base with `git -C "<worktree>" rev-parse HEAD`. Index every spec AC in order, including nested disposition lines without treating them as extra ACs; keep row text only in the spec. Initialize explicit/absent `in-scope` and `venue:` rows `open`, attempts 0, evidence empty. Initialize only `deviates:`, `deferred:`, `elsewhere:` rows `cut`, attempts 0, disposition text as evidence. Serialize evidence in one physical table cell, result lines separated by semicolons, pipes escaped, plain text without angle markup.
+Use the actual repo-relative spec path alone in the Spec header. Read base with `git -C "<worktree>" rev-parse HEAD`. Index every spec AC in order, including nested disposition lines without treating them as extra ACs; keep row text only in the spec. Initialize explicit/absent `in-scope` and `venue:` rows `open`, attempts 0, evidence empty. Initialize only `deviates:`, `deferred:`, `elsewhere:` rows `cut`, attempts 0, disposition text as evidence. Compute cap once as (rows not initialized cut) * maxIterationsPerRow + 1, including the seed dispatch. Write `cap:` immediately after `iterations: 0`: 24 non-cut rows at default 4 yield 97; all-cut yields 1 and exits through rule 1 without a seed dispatch. Later cuts, reopens and requirement-preserving amendments leave cap unchanged; redraw deletes the ledger and reseeds it. Serialize evidence in one physical table cell, result lines separated by semicolons, pipes escaped, plain text without angle markup.
 5. Call `plan_check({ planPath: <ledger path> })`. Stop with findings as a configuration error. Commit the stamped skeleton as `loop: seed ledger`; call `phase_tracker({ action: "start", phase: "implement" })`.
 
-For resume, use the admitted ledger, its base and verification command, and durable iterations instead of overwriting it. Render rows and last decision; stop on a dirty tree before dispatch.
+For resume, use the admitted ledger, its base and verification command, and durable iterations and cap instead of overwriting it. Skip Entry step 1 for an admitted ledger; settings apply only to fresh seeding. Render rows, cap and decision history; stop on a dirty tree before dispatch.
 
 ## Before each dispatch
 
-Read the ledger. Count empty child commits and validation misses only after the latest `loop: retry row <n>` commit. Funding alone resets neither window. Preserve every row's attempts and the total iteration cap. Apply this ordered table, starting here after each return or human decision:
+Read the ledger and require its `cap:` header before the ordered table, including before rule 1. On a missing header stop with `ledger has no cap: line - seeded under the old loopEngine contract`, even for a completed ledger; use the legacy grant below, never derive cap from settings. Count empty child commits and validation misses only after the latest `loop: retry row <n>` commit. Funding alone resets neither window. Preserve every row's attempts and the total iteration cap. Apply this ordered table, starting here after each return or human decision:
 
 | Order | Observed state | Action |
 |---|---|---|
 | 1 | No `open` or `failed` row | Exit verification. All-cut and baseline-complete ledgers exit normally. |
 | 2 | Unresolved row attempts at its allowance | Human stop. Exempt `done` and `cut`, including third-attempt success. |
 | 3 | Last two child row commits both changed no file outside the ledger and no row status | Human stop, regardless of funding. Count child `loop: row ...` commits only, excluding seed and parent repair/retry/cut commits. A decision alone is not progress. |
-| 4 | `iterations` >= `maxIterations` | Human stop naming cap, unresolved rows and attempts, before verification. Seed and interrupted dispatches count. |
+| 4 | `iterations` >= `cap` | Human stop naming the header cap value and every open/failed row with its attempts, before dispatch and before verification. Seed and interrupted dispatches count. |
 | 5 | Dispatch allowed | Select target by the priority below. |
 
 Set row allowance to 3 + funded N, increased to the latest `row <n> retry` decision's `allowed attempts <m>` when larger. Recover spent funding per row as `max(0, attempts - 3)`; a mid-loop grant applies prospectively. Before dispatch on a funded row with attempts >= 3 and spent < N print `funded round <k> of <N> for row <n>`, with k = attempts - 3 + 1. Funding buys neither cap bypass nor empty-commit bypass nor an escalated model. Include `budget: <spent> of <N> spent` in funded stops.
 
-Select `seed` until a validated `loop: seed evidence` commit with its `row 0 done` decision and evidence on every non-cut row survives on the branch, independently of `iterations`; otherwise select the still-unresolved human retry target, then the still-failed row named by the previous decision, then first failed row, then first open row. Durable status beats a decision's suggestion. Keep the retry hint only for its target.
+Select `seed` until a validated `loop: seed evidence` commit with its `row 0 done` decision and evidence on every non-cut row survives on the branch, independently of `iterations`; otherwise select the still-unresolved human retry target, then the still-failed row named by the previous decision, then first failed row, then first open row. Use the latest operational `row <n> ...` decision for targeting and the child's `previous decision:` input, skipping cap grant history while retaining the entire Decisions section. Durable status beats a decision's suggestion. Keep the retry hint only for its target.
 
 ## Dispatch
 
@@ -75,7 +76,7 @@ Omit the model override; let the persona override or parent inheritance resolve
 ## Validate the return
 
 1. Require empty `git -C "<worktree>" status --porcelain` and exactly 1 from `git -C "<worktree>" rev-list HEAD_BEFORE..HEAD --count`. On dirty/zero/multiple commits stop, preserving changes and commits. Use `Stopped: iteration <i> left the tree dirty` or `Stopped: iteration <i> added <k> commits`. Read the ledger from HEAD only after this boundary passes.
-2. Validate by dispatched `target`, not iteration number, against the saved copy using this table. Preserve headers including the bumped iterations, row identifiers and prior decisions.
+2. Validate by dispatched `target`, not iteration number, against the saved copy using this table. Preserve headers including cap and the bumped iterations, row identifiers and prior decisions.
 
 | Target | Required changes | Miss |
 |---|---|---|
@@ -84,7 +85,7 @@ Omit the model override; let the persona override or parent inheritance resolve
 
 Require ordinary decision grammar `^row <target> (done|failed) \| .{1,200} \| .{1,200}$`; an old conforming line is not a new line. Require check name plus at most three result lines in evidence, serialized with semicolons and escaped pipes as in the persona. Reject wrong targets, foreign cells, missing/malformed/new-extra decisions and changed headers.
 
-On an ordinary miss restore every non-target row, headers and prior decisions from the saved copy, retaining the incremented iterations. Set the target `failed`, attempts = saved attempts +1, evidence = `iteration <i>: <concrete miss>`. Remove malformed appended decisions and commit `loop: repair row <n>`. Set previous decision to `none`; otherwise use the new conforming line. Two consecutive validation misses stop because the child is not following the contract. A conforming return resets the consecutive-miss count; parent repair commits do not count toward child-only empty stagnation.
+On an ordinary miss restore every non-target row, headers (including the saved cap) and prior decisions from the saved copy, retaining the incremented iterations. Set the target `failed`, attempts = saved attempts +1, evidence = `iteration <i>: <concrete miss>`. Remove malformed appended decisions and commit `loop: repair row <n>`. Set previous decision to `none`; otherwise use the new conforming line. Two consecutive validation misses stop because the child is not following the contract. A conforming return resets the consecutive-miss count; parent repair commits do not count toward child-only empty stagnation.
 
 ## Exit verification
 
@@ -92,19 +93,22 @@ Run the ledger's `verification:` command exactly once foreground in the worktree
 
 ## Human stop
 
-Leave implement active. Use one screen of plain words: `Stopped on row <n> (<row text>)` for row failures, or the concrete boundary/cap/verification header above. `Problem:` quotes the evidence cell verbatim, identifying the actual spec/code contradiction, failing assertion/output or missing capability, and quotes the last decision line. Include funding budget only when funded. Omit round history, model escalation and reasoning traces.
+Leave implement active. Use one screen of plain words: `Stopped on row <n> (<row text>)` for row failures, or the concrete boundary/cap/verification header above. `Problem:` quotes the evidence cell verbatim, identifying the actual spec/code contradiction, failing assertion/output or missing capability, and quotes the last decision line. Include funding budget only when funded. At every stop print `Preserve every row's attempts and the total iteration cap.` Omit round history, model escalation and reasoning traces.
 
-Offer these concrete actions:
+Offer these concrete actions. Offer `cap +N` only at a clean cap or legacy missing-cap stop; dirty-tree and commit-boundary stops keep discard authorization and never offer `cap +N`. When both the row allowance and total cap are exhausted, list independent funding and cap offers despite rule 2 priority. Take separate replies: funding follows the spec's `**Amend-grant:**` contract, cap follows the row below; define no combined syntax.
 
 | Human choice | Durable action |
 |---|---|
+| Raise cap (`cap +N`) | Parse anchored `cap +<n>` with `<n>` matching `[1-9][0-9]*` and a token boundary (end, whitespace or `\|`); reject `cap +50x`. Trim the optional remainder and optional leading pipe into the words cell. Append `cap +<n> \| <words>` under `## Decisions`; bare `cap +50` writes `cap +50 \|`. Raise the old header cap by N, or set a missing cap to durable iterations + N. Write a missing `cap:` directly after `iterations:`. Commit both changes exactly once as parent `loop: raise cap`, leaving iterations and all attempts unchanged; return to the ordered table. Malformed `cap +0`, `cap +x`, `cap -5` asks once; a second invalid reply holds the same stop with no commit. |
 | Retry with hint | Append `row <n> retry | <hint> | allowed attempts <attempts + 1>`, commit `loop: retry row <n>`, resume checks with that target/hint. Never reset attempts or iterations. |
 | Amend | Follow `/skill:brainstorming` amendment surface; cut only through an approved disposition amendment. Reconcile ledger and spec in one commit. |
 | Stop | Keep phase implement and preserve branch state. |
 
+Serialize the bare decision as `cap +50 |` with an empty words cell. A cap grant resets neither window (empty-child or validation-miss); exclude `loop: raise cap` from child-commit counting. Only retry starts new windows.
+
 For dirty/commit-boundary retry, ask the human to authorize discarding uncommitted changes/resetting to last valid commit. Preserve consumed dispatch count: set iterations to restored HEAD's value +1 before the next normal bump. An interrupted dispatch consumes the same count; recover it from disk/branch rather than silently repeating iteration 0.
 
-For ledger amendments use its line-1 discriminant: no plan writer, plan_check or task-tracker lifecycle. Approved deviates/deferred/elsewhere becomes `cut` with disposition evidence; requirement-preserving amendments leave rows unchanged; a re-bounded done row becomes `open` with `reopened by amendment`. Preserve attempts and iterations. Commit spec + ledger as `loop: cut row <n>` or `loop: amend`. Option 4 stops for amendments, option 5 auto-applies amends, redraw always stops and deletes the ledger with the plan. Never cut automatically.
+For ledger amendments use its line-1 discriminant: no plan writer, plan_check or task-tracker lifecycle. Approved deviates/deferred/elsewhere becomes `cut` with disposition evidence; requirement-preserving amendments leave rows unchanged; a re-bounded done row becomes `open` with `reopened by amendment`. Preserve attempts, iterations and cap. Commit spec + ledger as `loop: cut row <n>` or `loop: amend`. Option 4 stops for amendments, option 5 auto-applies amends, redraw always stops and deletes the ledger with the plan. Never cut automatically.
 
 ## After the loop