pi-gauntlet 7.41.3 → 7.42.0

package/skills/subagent-driven-development/reference/dispatch-contract.md

@@ -0,0 +1,39 @@
+# Implement dispatch contract
+
+Read these schemas and carrier rules before the first implement dispatch. Keep them available through recovery. Apply this contract only during implement; leave verification and the loop engine's contract unchanged.
+
+## Schemas
+
+Mirror each child's saved report, not an independent verdict calculation. Bound implementer reasoning to one sentence and 300 characters; keep concerns and evidence entries one line each, questions explicit, and delegated answers one paragraph. Preserve `parallelSafe` as the `Parallel-safe:` line verbatim and `trajectory.line` as the `TRAJECTORY:` line verbatim. Require `behaviourChange` on every CR report, mirroring `Behaviour-change:`. Use `measured` only for values an explicit `orchestrator` instruction consumes.
+
+```ts
+const IMPLEMENTER_STATUS_SCHEMA = {"type":"object","required":["status","reasoning"],"additionalProperties":false,"properties":{"status":{"type":"string","enum":["DONE","DONE_WITH_CONCERNS","NEEDS_CONTEXT","BLOCKED"]},"reasoning":{"type":"string","maxLength":300},"concerns":{"type":"array","items":{"type":"string"}},"question":{"type":"string"},"anchorUnreadable":{"type":"string"},"measured":{"type":"object"}},"allOf":[{"if":{"properties":{"status":{"const":"DONE_WITH_CONCERNS"}}},"then":{"required":["concerns"]}},{"if":{"properties":{"status":{"const":"NEEDS_CONTEXT"}}},"then":{"required":["question"]}}]};
+const SPEC_VERDICT_SCHEMA = {"type":"object","required":["verdict","reasoning"],"additionalProperties":false,"properties":{"reasoning":{"type":"string"},"findingCount":{"type":"integer","minimum":0},"parallelSafe":{"type":"string"},"touchedTasks":{"type":"array","items":{"type":"integer"}},"trajectory":{"type":"object","required":["verdict","line"],"additionalProperties":false,"properties":{"verdict":{"type":"string","enum":["CONVERGING","DIVERGING","STAGNANT"]},"line":{"type":"string"}}},"anchorUnreadable":{"type":"string"},"verdict":{"type":"string","enum":["COMPLIANT","NEEDS_REWORK","OUT_OF_SCOPE_CHANGES"]},"maxSeverity":{"type":"string","enum":["PARTIAL","MISSING","SCOPE_CREEP"]}}};
+const CODE_VERDICT_SCHEMA = {"type":"object","required":["verdict","reasoning","behaviourChange"],"additionalProperties":false,"properties":{"reasoning":{"type":"string"},"findingCount":{"type":"integer","minimum":0},"parallelSafe":{"type":"string"},"touchedTasks":{"type":"array","items":{"type":"integer"}},"trajectory":{"type":"object","required":["verdict","line"],"additionalProperties":false,"properties":{"verdict":{"type":"string","enum":["CONVERGING","DIVERGING","STAGNANT"]},"line":{"type":"string"}}},"anchorUnreadable":{"type":"string"},"verdict":{"type":"string","enum":["SHIP","FIX_FIRST","REJECT"]},"maxSeverity":{"type":"string","enum":["Critical","Moderate","Minor"]},"behaviourChange":{"type":"boolean"}}};
+const ANSWER_SCHEMA = {"type":"object","required":["answer","evidence"],"additionalProperties":false,"properties":{"answer":{"type":"string"},"evidence":{"type":"array","items":{"type":"string"}}}};
+const DIAGNOSIS_SCHEMA = {"type":"object","required":["tasks","decision","diagnostic"],"additionalProperties":false,"properties":{"tasks":{"type":"array","items":{"type":"object","required":["task","status","reportPath","diagnostic"],"additionalProperties":false,"properties":{"task":{"type":"integer"},"status":{"type":"string"},"reportPath":{"type":"string"},"patchPath":{"type":"string"},"diagnostic":{"type":"string"}}}},"decision":{"type":"string","enum":["retry","repair","stop"]},"diagnostic":{"type":"string"}}};
+const PREPARE_SCHEMA = {"type":"object","required":["items","redraws"],"additionalProperties":false,"properties":{"items":{"type":"array","items":{"type":"object","required":["evidence","recommended","location","edit"],"additionalProperties":false,"properties":{"evidence":{"type":"string"},"recommended":{"type":"string","pattern":"^(accept|alt-[0-9]+)$"},"location":{"type":"string"},"edit":{"type":"string"}}}},"redraws":{"type":"array","items":{"type":"object","required":["location","reason"],"additionalProperties":false,"properties":{"location":{"type":"string"},"reason":{"type":"string","maxLength":300}}}}}};
+const APPLY_SCHEMA = {"type":"object","required":["amendedSections","tasksAdded","tasksAnchorChanged","tasksRemoved","passed"],"additionalProperties":false,"properties":{"amendedSections":{"type":"array","items":{"type":"string"}},"tasksAdded":{"type":"array","items":{"type":"integer"}},"tasksAnchorChanged":{"type":"array","items":{"type":"integer"}},"tasksRemoved":{"type":"array","items":{"type":"integer"}},"passed":{"type":"boolean"},"failLines":{"type":"array","items":{"type":"string"}}}};
+```
+
+## One-step carrier
+
+Use this shape for initial CR, repair implementers, post-repair SR fan-outs, SR/CR re-reviews, escalated/funded rounds, delegated answers and amendment workers. Set the persona and schema for each item; use `/status` for implementers and `/verdict` for reviewers with their non-clean enums. Put `output`, `outputMode` and `outputSchema` on every item, never on a `ParallelStep`. Keep `context: "fresh"` and `async: false` invocation-level. Omit `model` except a runtime-resolved setting or a user-named override. A schema-bound `anchorUnreadable` is a failed attempt, not permission for the primary to inspect the file.
+
+```ts
+subagent({ async: false, context: "fresh", cwd: "<owning checkout>",
+  chain: [{ parallel: [
+    { agent: "code-reviewer", output: "<REPORT_DIR>/wave<w>-cr<k>.md",
+      outputMode: "file-only", outputSchema: CODE_VERDICT_SCHEMA,
+      task: "planPath: <absolute plan>; anchors: <wave task prefixes>; Spec: <absolute home spec>; BASE_SHA: <WAVE_BASE_SHA>; HEAD_SHA: WORKTREE; SCOPED_TEST_COMMANDS: <manifest union>" }
+  ], stopOn: { path: "/verdict", in: ["FIX_FIRST", "REJECT"] } }]
+})
+```
+
+For answer/evidence, preparation and apply results, retain their approved schemas without adding a status field. Use carrier-only `stopOn: { path: "/status", in: ["BLOCKED"] }`: an absent pointer does not match, but the presence of stopOn exposes successful `## Outputs` JSON. Save each report under `REPORT_DIR`. Give delegated reads the question, artifact paths, owning checkout, and documented lookup ordering; let the child read source, provenance, task contents or current grants. Consume only `answer` and `evidence`. A delegated failure stops; never recursively diagnose delegated failures.
+
+## Anchored payload
+
+Pass `planPath: <absolute plan path>`, `anchor: "### Task N:"` or `anchors: [<exact prefixes>]`, and `Spec: <absolute authoritative home spec path>` to every implementer, SR and CR. `### Task 4:` never matches `### Task 40:`; end each selected section at `^#{2,3}\s`. Children read the union of selected sections, `Spec:`, `Files:`, `Tests:`, `Rules:` and `Leg:` themselves. Combine task Rules with that leg's Rules in home `## Legs`; absent Leg uses the first `### Leg:`. Resolve rules in the owning checkout. Pass isolated implementers only their own task's manifest `tests` as `SCOPED_TEST_COMMANDS`, or `none` when empty, including isolated spec-gap redispatch. Give the integrated gate, in-place repairs and code reviews the wave union; give initial in-place implementers that union too. Preserve command strings verbatim; keep dispatch-supplied commands independent of the Tests metadata children read.
+
+Forward dependent context as the prior status line plus report path. Put the saved prior report path under `## Previous review report (re-review trigger)`; require the child to read it and apply the existing trajectory block. Findings and binary delta bytes stay child-owned.

package/skills/subagent-driven-development/reference/fix-loop.md

@@ -1,14 +1,16 @@
 # Escalated fix rounds
 
-**Escalate** = one escalated round; stop only on failure. Call `gauntlet_setting({ key: "escalationLoop" })` (unavailable -> stop and report). `implModel` undefined -> stop note. Otherwise re-dispatch that fix - same payload and isolation knobs (`cwd`, `worktree`, `SCOPED_TEST_COMMANDS`, status protocol, prior patch, spec anchors) plus the prior report verbatim - overriding only `model: <implModel>`, `context: "fresh"`, `async: false`; one implementer, no fan-out. Run the normal fix-round review gate (SR then CR on `Behaviour-change: yes`, else the triggering reviewer with the re-review marker). All clean -> proceed; the escalated patch supersedes the prior one at integrate. A non-`DONE` status or a dispatch error -> stop note per `stop-note.md`. A review with issues -> a funded round while one remains for the task (below), otherwise stop note; no other second dispatch. Once per loop; independent of the convergence exception. No `plan_tracker` write during escalation - keep the task `in_progress` until the wave commit or, on a stop, the human decides.
+Use the dispatch-contract one-step carrier for escalated and funded implementers and every review, with output/file-only/schema and a status/verdict stopOn. Consume structured results only. Serialize a fix with missing parallelSafe; absent touchedTasks on a multi-task repair means all dispatched tasks. Escalate a re-review missing trajectory instead of requesting the line again.
+
+**Escalate** = one escalated round; stop only on failure. Call `gauntlet_setting({ key: "escalationLoop" })` (unavailable -> stop and report). `implModel` undefined -> stop note. Otherwise re-dispatch that fix - same payload and isolation knobs (`cwd`, `worktree`, `SCOPED_TEST_COMMANDS`, status protocol, prior patch, spec anchors) plus the prior report path under `## Previous review report (re-review trigger)` - overriding only `model: <implModel>`, `context: "fresh"`, `async: false`; one implementer, no fan-out. Run the normal fix-round review gate (SR then CR on `Behaviour-change: yes`, else the triggering reviewer with the re-review marker). All clean -> proceed; the escalated patch supersedes the prior one at integrate. A non-`DONE` status or a dispatch error -> stop note per `stop-note.md`. A review with issues -> a funded round while one remains for the task (below), otherwise stop note; no other second dispatch. Once per loop; independent of the convergence exception. No `plan_tracker` write during escalation - keep the task `in_progress` until the wave commit or, on a stop, the human decides.
 
 ## Funded rounds
 
-Decode the current `**Amend-grant:**` line using **Value decoding** in [Standing grants](../../brainstorming/reference/amendment-surface.md#standing-grants) before each funded dispatch. Funding is independent of ordinary fixes and the escalated round; it never supplies a missing `implModel`, another escalation grant, verify credits, or `grant_fix_rounds`. Keep the review-3 convergence exception once per loop; never re-arm it through funding.
+Delegate a current `**Amend-grant:**` read and grant decoding through the answer/evidence one-step carrier using **Value decoding** in [Standing grants](../../brainstorming/reference/amendment-surface.md#standing-grants) before each funded dispatch. Funding is independent of ordinary fixes and the escalated round; it never supplies a missing `implModel`, another escalation grant, verify credits, or `grant_fix_rounds`. Keep the review-3 convergence exception once per loop; never re-arm it through funding.
 
 Start one per-task ledger at zero when each task first enters Fix-Loop Rounds. Carry it across SR, behavior-change reroutes, the SR-to-CR transition, and wave repairs re-entering SR; use no wave-level allowance. Determine touched owners using the SR targeting rule (tasks whose files the fix touches). For a multi-task CR repair, spend once from every touched task; a touched exhausted owner stops the wave with that task's stop note before dispatch.
 
-Before every funded dispatch, print `funded round <k> of <N> for task <n>` for each touched task. Apply mid-loop grants prospectively, with spent starting at zero: rounds before the token was written neither count against nor toward it. Repeat the escalated payload and isolation exactly: configured `model: <implModel>` from `escalationLoop`, `context: "fresh"`, `async: false`, one implementer, no fan-out, same `cwd`/`worktree`, task text, prior patch, spec anchors, status protocol, `SCOPED_TEST_COMMANDS`, and complete prior report verbatim. Run the same tests and same review gate: SR then CR on `Behaviour-change: yes`, otherwise the triggering reviewer with the re-review marker, trajectory block and Fix delta. Every dispatched round spends one, including failures.
+Before every funded dispatch, print `funded round <k> of <N> for task <n>` for each touched task. Apply mid-loop grants prospectively, with spent starting at zero: rounds before the token was written neither count against nor toward it. Repeat the escalated payload and isolation exactly: configured `model: <implModel>` from `escalationLoop`, `context: "fresh"`, `async: false`, one implementer, no fan-out, same `cwd`/`worktree`, planPath and task anchors, prior patch path, spec path, status protocol, `SCOPED_TEST_COMMANDS`, and saved prior report path under `## Previous review report (re-review trigger)`. Run the same tests and same review gate: SR then CR on `Behaviour-change: yes`, otherwise the triggering reviewer with the re-review marker, trajectory block and Fix delta. Every dispatched round spends one, including failures.
 
 | Funded outcome | Action |
 |---|---|
@@ -28,7 +30,7 @@ Decode grants through [Value decoding](../../brainstorming/reference/amendment-s
 
 1. **Hard stops**: stop first for malformed grants, missing `implModel`, unavailable settings tools, dirty-tree/commit-boundary returns, empty-commit stagnation, cap, funded re-review `STAGNANT`, `REJECT`, and [redraws](../SKILL.md#implementer-status).
 2. **Takeable decision**: route only `BLOCKED`/`NEEDS_CONTEXT` decisions with attempts remaining below. Compare whitespace-normalized `file:line` finding or failing command plus assertion already auto-resolved on this task -> `Recommendation: none - evidence repeats task <n>`; stop.
-3. **Execution escalation**: after two failed attempts, escalate before routing `Recommendation:`; call `gauntlet_setting({ key: "escalationLoop" })`; `implModel` undefined stops with the existing note. Print `escalated round for task <n> after 2 failed attempts`. Dispatch one implementer: `model: <implModel>`, `context: "fresh"`, `async: false`, same payload and isolation as above (`SCOPED_TEST_COMMANDS`, complete prior report verbatim); retain siblings; no fan-out/re-chain. Spend once/task/site, independently of review escalation/funding.
+3. **Execution escalation**: after two failed attempts, escalate before routing `Recommendation:`; call `gauntlet_setting({ key: "escalationLoop" })`; `implModel` undefined stops with the existing note. Print `escalated round for task <n> after 2 failed attempts`. Dispatch one implementer: `model: <implModel>`, `context: "fresh"`, `async: false`, same payload and isolation as above (`SCOPED_TEST_COMMANDS`, the prior report path and the anchored task payload); retain siblings; no fan-out/re-chain. Spend once/task/site, independently of review escalation/funding.
 4. **Resulting decision**: dispatch error or non-`DONE` spends escalation; use step 2's table; no fourth unnamed repair. Success still runs the ordinary scoped tests and SR/CR gates before wave commit/completion.
 
 When taken, print `took recommendation: <option> for task <n>`.

package/skills/subagent-driven-development/reference/implement-amendments.md

@@ -0,0 +1,9 @@
+# Implement amendments
+
+Read [amendment-surface.md](../../brainstorming/reference/amendment-surface.md) for the existing gate and Standing grants. Apply this delegation only during implement; keep the planning caller unchanged. Use the one-step carrier and schemas in [dispatch-contract.md](dispatch-contract.md) for every child, with saved output, file-only, fresh context and foreground execution.
+
+1. Dispatch `plan-writer` with `Amend-prepare:`, the five absolute paths (worktree, approved spec, plan, plan skill and plan contract) and the evidence already in context: plan_check FAIL lines, structured concerns/question or measured baseline rows. Preparation writes nothing. Require `{ items: [{ evidence, recommended: "accept" | "alt-<n>", location: "<spec section>", edit: string }], redraws: [{ location: "<spec section>", reason: string (max 300 characters) }] }`; keep each edit one paragraph. Keep the existing menu spelling `alt-n` for a named alternative; encode the selected number as `alt-<n>` in JSON. Require both items and redraws arrays, including empty arrays; put redraws only in redraws, never items. Fail malformed preparation output.
+2. Inspect structured redraws first. A nonempty array holds the whole batch at the redraw gate before grant evaluation or applying any sibling item, for redraw-only and mixed batches alike. Never open the preparation report to discover redraws. With no redraws, delegate reading the current `Amend-grant:` and Value decoding through the answer/evidence carrier. Preserve the surface's grant predicate: malformed -> stop and quote; absent, none or no permission -> the existing human menu and escalation gate. Stop on changed problem statement or a component added, removed or re-bounded.
+3. With amend permission, apply the recommended choice without reviewer, menu or confirmation turns; pass granted items verbatim to `plan-writer` under `Amend-apply:` plus the existing `Amend:` entry and parent-supplied `In-flight:` paths from `status --porcelain`, including staged in-place repair deliverables. Preserve Baseline ownership, protected-path and dirty-baseline exits; delegate attribution reads and human wording instead of loading documents in the primary. Authorize only the named spec sections and plan regeneration, preserving unaffected task titles and wave positions. Before the first apply, require original task numbers, titles, spec anchors, and wave positions in the existing saved apply report; retain that original inventory on every return, including failures. Add no sidecar.
+4. Consume the unchanged apply result `{ amendedSections: string[], tasksAdded: number[], tasksAnchorChanged: number[], tasksRemoved: number[], passed: boolean, failLines?: string[] }`. On `passed: false`, retry once in a fresh child with failLines as the rule and `previousApplyReport` set to the first apply report path. Require the retry to read original inventory, apply granted edits idempotently without duplicates, and compute deltas against that original inventory rather than the already-mutated plan. Missing original inventory fails the retry. Escalate a second failure; never repeat granted edits blindly.
+5. After child success, run parent `plan_check({ planPath })`. Reconcile only after parent PASS: replace the manifest; use tracker update and `add` for tasksAdded, reopen completed tasksAnchorChanged as `in_progress`, and handle tasksRemoved through the surface's existing path. Print `amended the spec: <title> - <what>` from structured item location/edit observations, and make the existing single `amend:` audit commit. Keep the parent from opening spec, plan or reports. Persist measured values from explicit orchestrator instructions through this same path.

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -10,21 +10,24 @@ Dispatch a subagent with this prompt:
   prompt: |
     You are reviewing whether an implementation matches its specification.
 
-    ## What Was Requested
+    planPath: [absolute plan path]
+    anchor: "### Task N:"
+    anchors: [use instead of anchor for a multi-task review]
+    Spec: [absolute authoritative home spec path]
+    Work from: [review checkout]
+    SCOPED_TEST_COMMANDS: [dispatch-supplied values | none; evidence only, never execute]
+    Implementer report: [saved implementer report path]
 
-    [FULL TEXT of task requirements]
+    Read the selected task sections first. Read their Spec anchors, Tests:/via: and Files: Create:/Test: paths yourself; derive Rules from the task and home-spec leg as your persona directs. Read the saved implementer report, then verify its claims independently.
 
-    (The task text is a derivative of the spec — a lossy projection into an executable unit. See ## Spec Authority below.)
+    ## Previous review report (re-review trigger)
 
-    ## What Implementer Claims They Built
-
-    [From implementer's report]
+    [Re-review only: saved previous review report path; omit this section on initial review]
+    Read that report yourself before evaluating trajectory.
 
     ## Spec Authority
 
-    Spec: [absolute spec path]
-    Anchors: [the task's **Spec:** anchor list, e.g. § "Design" L34-L37 — or "omitted: anchor-less mechanical task"]
-    Task contract: [the task's **Tests:** block verbatim + its `Files:` paths]
+    Derive the spec anchor list and task contract from the selected sections; distinguish plan task anchors from spec clause anchors. The task text is a derivative of the spec, not its authority.
 
     The spec is the sole authority — human-approved; the task never wins a dispute. Read the anchored ranges from the spec file yourself. Requirements in scope are ONLY the cited anchor ranges; do not extract, review, or flag the rest of the spec file.
 
@@ -91,7 +94,7 @@ Dispatch a subagent with this prompt:
 
     **Verify by reading code, not by trusting report.**
 
-    Report in the output format `agents/spec-reviewer.md` defines in your system prompt.
+    Report in the output format `agents/spec-reviewer.md` defines in your system prompt. Emit structured output matching its contract and the report verdict and footer. On an unreadable plan/anchor report NEEDS_REWORK with anchorUnreadable formed by concatenating planPath, a literal #, and the dispatched anchor verbatim, including the ### prefix and trailing colon. Use that same exact identity in the required Reasoning line; never ask the parent to read it or mark an unread section compliant.
 
     ## Re-review: trajectory verdict
 

package/skills/subagent-driven-development/stop-note.md

@@ -1,11 +1,13 @@
 # Stop note (subagent-driven-development companion)
 
-For a `NEEDS_CONTEXT`/`BLOCKED` fact ask, search the locations documented by the spec, plan, or repo: one bounded lookup per location in documented order, stopping at the first hit. Record each lookup and result, including earlier misses; re-dispatch with the found result in the task text.
+For a `NEEDS_CONTEXT`/`BLOCKED` fact ask, dispatch a delegated answer/evidence child to search the locations documented by the spec, plan, or repo: one bounded lookup per location in documented order, stopping at the first hit. Record each lookup and result, including earlier misses; consume the compact answer/evidence and re-dispatch with the found result. Never open source or deliverable reports in the primary. Stop on a delegated failure.
 
 Emit when no escalation model resolves, the escalated dispatch errors, its one escalated round fails (see `SKILL.md` "Fix-Loop Rounds"), or a `NEEDS_CONTEXT`/`BLOCKED` fact ask exhausts documented locations, needs credentials for a remaining location, or lacks its named lookup tool; an unavailable `gauntlet_setting` tool is a configuration error - stop and report, no stop note. Inline in the reply; the turn ends; phase stays `implement`, the task stays `in_progress`; no further tasks start. Emit one note per stalled task, after the current batch returns.
 
 ## Template
 
+Delegate human escalation wording through the answer/evidence carrier with the final review path, scoped-output paths, structured routing fields and lookup observations. Require the child to read findings and return the exact one-screen note below as its answer. Keep the primary from opening the report. Apply funded-round budget placement from reference/fix-loop.md.
+
 Read and apply [menu-layout](../brainstorming/reference/menu-layout.md). Start the message with `gauntlet: question` alone on the first output line, followed by a newline before the stop note; this is an implementation decision, not a done or stuck outcome.
 
 ```

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

@@ -7,6 +7,7 @@ The grammar `plan_check` enforces. Each section names its check(s). Findings res
 A wave is a maximal set of tasks that have no ordering dependency on each other, own pairwise-disjoint files, and contend on no shared mutable runtime resource (same DB/schema, port, fixture file, external service, shared temp path).
 
 - Tasks nest under `## Wave N — <label>` headers; `### Task N` headers sit inside a wave.
+- Write an optional single-line `Orchestrator: <instruction>` in a task body only for coordination the orchestrator must perform between waves; the first line matching `^Orchestrator: (.+)$` wins. Keep all other task prose worker-only. Route spec or plan persistence through the approved amendment procedure.
 
 ## Legs (`leg-unknown`)