pi-gauntlet 5.3.7 → 5.5.0

package/extensions/lib/plan-check.ts

@@ -36,6 +36,12 @@ interface FileEntry {
   path: string;
 }
 
+interface TestsBullet {
+  line: number;
+  text: string;
+  value: string;
+}
+
 interface Task {
   number: number;
   line: number;
@@ -48,6 +54,12 @@ interface Task {
   specAnchorLine: number | undefined;
   anchors: Anchor[];
   anchorParseError: boolean;
+  testsHeadingLine: number | undefined;
+  testsMisplacedLines: number[];
+  tests: TestsBullet[];
+  testsVia: TestsBullet[];
+  testsNone: TestsBullet[];
+  testsMalformed: TestsBullet[];
 }
 
 interface Wave {
@@ -235,6 +247,50 @@ function parsePlan(planText: string): ParsedPlan {
       }
     }
 
+    let testsHeadingLine: number | undefined;
+    const testsMisplacedLines: number[] = [];
+    const tests: TestsBullet[] = [];
+    const testsVia: TestsBullet[] = [];
+    const testsNone: TestsBullet[] = [];
+    const testsMalformed: TestsBullet[] = [];
+
+    let headingIdx = -1;
+    if (filesLine !== undefined) {
+      let lastEntry = filesLine - 1;
+      let p = filesLine;
+      while (p <= bodyEndIdx) {
+        const l = lines[p];
+        if (l.trim() === "") { p++; continue; }
+        if (/^- \w+: /.test(l)) { lastEntry = p; p++; continue; }
+        break;
+      }
+      let q = lastEntry + 1;
+      while (q <= bodyEndIdx && lines[q].trim() === "") q++;
+      if (q <= bodyEndIdx && !mask[q] && lines[q] === "**Tests:**") {
+        headingIdx = q;
+        testsHeadingLine = q + 1;
+      }
+    }
+    for (let k = i; k <= bodyEndIdx; k++) {
+      if (mask[k] || k === headingIdx) continue;
+      if (/^\*\*Tests:\*\*/.test(lines[k])) testsMisplacedLines.push(k + 1);
+    }
+    if (headingIdx !== -1) {
+      for (let p = headingIdx + 1; p <= bodyEndIdx; p++) {
+        const l = lines[p];
+        if (l.trim() === "") continue;
+        if (mask[p] || !l.startsWith("- ") || l.startsWith("- [ ]")) break;
+        const cmd = /^- `([^`]+)`$/.exec(l);
+        const via = /^- via: (\S.*)$/.exec(l);
+        const none = /^- none: (\S.*)$/.exec(l);
+        const bullet = { line: p + 1, text: l, value: (cmd ?? via ?? none)?.[1] ?? "" };
+        if (cmd) tests.push(bullet);
+        else if (via) testsVia.push(bullet);
+        else if (none) testsNone.push(bullet);
+        else testsMalformed.push(bullet);
+      }
+    }
+
     tasks.push({
       number: Number(m[1]),
       line: i + 1,
@@ -247,6 +303,12 @@ function parsePlan(planText: string): ParsedPlan {
       specAnchorLine,
       anchors,
       anchorParseError,
+      testsHeadingLine,
+      testsMisplacedLines,
+      tests,
+      testsVia,
+      testsNone,
+      testsMalformed,
     });
   }
 
@@ -343,6 +405,99 @@ function isGlob(p: string): boolean {
   return /[*?{[\]]/.test(p);
 }
 
+function norm(s: string): string {
+  return s.replaceAll("`", "").replace(/\s+/g, " ").trim();
+}
+
+function backtickSpans(s: string): string[] {
+  const out: string[] = [];
+  const re = /`([^`]+)`/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(s))) out.push(m[1]);
+  return out;
+}
+
+function commandSegments(cmd: string): string[] {
+  return norm(cmd).split(/\s*(?:&&|\|\||;|\|)\s*/).map((s) => s.trim()).filter(Boolean);
+}
+
+function headerSegments(parsed: ParsedPlan): string[] {
+  const value = parsed.header.verificationText ?? "";
+  const spans = backtickSpans(value);
+  const parts = spans.length > 0 ? spans : [value];
+  return parts.flatMap((p) => norm(p).split(/\s*(?:&&|\|\||;|,)\s*/)).map((s) => s.trim()).filter(Boolean);
+}
+
+const RUN_RE = /^\s*(- \[ \] )?Run:\s*(.*)$/;
+
+function runPayloadSegments(line: string): string[] | undefined {
+  const m = RUN_RE.exec(line);
+  if (!m) return undefined;
+  const spans = backtickSpans(m[2]);
+  return (spans.length > 0 ? spans : [m[2]]).flatMap(commandSegments);
+}
+
+const UNSUPPORTED_SHELL = ["cd ", "sh -c", "bash -c", "eval ", "$("];
+
+function isBroadening(token: string): boolean {
+  return /[*?[]/.test(token) || token.endsWith("/");
+}
+
+function checkTestsBlock(parsed: ParsedPlan, fs: FsPort): PlanCheckFinding[] {
+  const findings: PlanCheckFinding[] = [];
+  const push = (task: Task, line: number, text: string, reason: string) =>
+    findings.push({ check: "tests-block", line, text, reason: `Task ${task.number}: ${reason}` });
+  const createPaths = new Set(
+    parsed.tasks.flatMap((t) => t.files.filter((f) => f.kind === "create").map((f) => stripLineSuffix(f.path))),
+  );
+  const header = headerSegments(parsed);
+
+  for (const task of parsed.tasks) {
+    const testEntries = task.files.filter((f) => f.kind === "test");
+    const testPaths = testEntries.map((f) => stripLineSuffix(f.path));
+
+    for (const f of testEntries) {
+      const p = stripLineSuffix(f.path);
+      if (!createPaths.has(p) && !fs.exists(p)) push(task, f.line, f.text, `unknown \`Test:\` path "${p}" (neither exists nor is a Create: path of any task)`);
+    }
+
+    if (task.testsMisplacedLines.length > 0) {
+      for (const ln of task.testsMisplacedLines) push(task, ln, parsed.lines[ln - 1], "misplaced block: `**Tests:**` must be the bare line directly after the Files: entries");
+    } else if (task.testsHeadingLine === undefined) {
+      push(task, task.line, task.text, "block missing: no `**Tests:**` directly after the Files: entries");
+    }
+    if (task.testsHeadingLine === undefined) continue;
+
+    const headingText = parsed.lines[task.testsHeadingLine - 1];
+    if (task.tests.length === 0 && task.testsNone.length === 0) push(task, task.testsHeadingLine, headingText, "block empty: no command bullet and no `none:`");
+    for (const b of task.testsMalformed) push(task, b.line, b.text, "malformed bullet: expected `- \\`command\\``, `- via: <seam>`, or `- none: <category>`");
+    if (task.testsNone.length > 1 || (task.testsNone.length > 0 && (task.tests.length > 0 || task.testsVia.length > 0))) {
+      push(task, task.testsNone[0].line, task.testsNone[0].text, "contradictory block: `none:` with a command or `via:`, or more than one `none:`");
+    }
+    if (task.testsNone.length > 0) {
+      for (const f of testEntries) push(task, f.line, f.text, "unused `Test:` path: task declares `none:`");
+    }
+
+    const anchors = testPaths.filter((p) => !isBroadening(p));
+    for (const b of task.tests) {
+      if (UNSUPPORTED_SHELL.some((s) => b.value.includes(s))) {
+        push(task, b.line, b.text, "unsupported shell: `cd `, `sh -c`, `bash -c`, `eval `, `$(` are not allowed");
+        continue;
+      }
+      for (const seg of commandSegments(b.value)) {
+        const tokens = seg.split(" ");
+        const isAnchor = (t: string) => anchors.some((p) => t === p || t.startsWith(p + "::") || t.startsWith(p + "#") || t.startsWith(p + ":"));
+        if (!tokens.some(isAnchor)) push(task, b.line, b.text, `segment not anchored: "${seg}" names no Test: path of this task`);
+        for (const t of tokens) {
+          if (!isAnchor(t) && isBroadening(t)) push(task, b.line, b.text, `broadening selector "${t}" in "${seg}"`);
+        }
+        if (header.includes(seg)) push(task, b.line, b.text, `full-suite command in task: "${seg}" equals a header **Verification:** segment`);
+      }
+    }
+  }
+  return findings;
+}
+
 function taskBodyText(task: Task, lines: string[]): string {
   return lines.slice(task.bodyStartLine - 1, task.bodyEndLine).join("\n");
 }
@@ -687,10 +842,14 @@ function checkPlaceholderScan(parsed: ParsedPlan, requiredLiterals: Map<number,
   return findings;
 }
 
-function fileEntries(task: Task): { path: string; kind: "literal" | "glob" }[] {
+function fileEntries(task: Task): { path: string; kind: "literal" | "glob"; role: "test" | "write" }[] {
   return task.files.map((f) => {
     const p = stripLineSuffix(f.path);
-    return { path: p, kind: (isGlob(p) ? "glob" : "literal") as "literal" | "glob" };
+    return {
+      path: p,
+      kind: (isGlob(p) ? "glob" : "literal") as "literal" | "glob",
+      role: f.kind === "test" ? "test" : "write",
+    };
   });
 }
 
@@ -719,6 +878,7 @@ function checkWaveFileDisjointness(parsed: ParsedPlan, fs: FsPort): PlanCheckFin
         const b = fileEntries(tasks[j]);
         for (const ea of a) {
           for (const eb of b) {
+            if (ea.role === "test" && eb.role === "test") continue;
             let overlap = false;
             let errFinding: PlanCheckFinding | undefined;
             if (ea.kind === "literal" && eb.kind === "literal") {
@@ -798,6 +958,15 @@ function checkHeaderEntrypoint(parsed: ParsedPlan): PlanCheckFinding[] {
   const entrypoint = parsed.header.verificationText.trim();
   if (!entrypoint) return findings;
 
+  const header = headerSegments(parsed);
+  const executable = new Set<number>();
+  for (const task of parsed.tasks) {
+    for (const bullet of [...task.tests, ...task.testsVia, ...task.testsNone, ...task.testsMalformed]) {
+      executable.add(bullet.line);
+    }
+  }
+  const mask = fenceMask(parsed.lines);
+
   const waveBoundaryRe = /^##\s/;
   const inScope = new Set<number>();
   for (const wave of parsed.waves) {
@@ -814,6 +983,21 @@ function checkHeaderEntrypoint(parsed: ParsedPlan): PlanCheckFinding[] {
 
   for (const ln of [...inScope].sort((a, b) => a - b)) {
     const line = parsed.lines[ln - 1];
+    if (executable.has(ln)) continue;
+    const segments = runPayloadSegments(line);
+    if (segments) {
+      if (mask[ln - 1]) continue;
+      const hit = segments.find((segment) => header.includes(segment));
+      if (hit !== undefined) {
+        findings.push({
+          check: "header-entrypoint",
+          line: ln,
+          text: line,
+          reason: `Run: segment "${hit}" equals a header **Verification:** segment (full suite belongs to the verify phase)`,
+        });
+      }
+      continue;
+    }
     if (line.includes(entrypoint)) {
       findings.push({
         check: "header-entrypoint",
@@ -870,6 +1054,7 @@ export function checkPlan(planText: string, specText: string, fs: FsPort): PlanC
     findings.push(...checkQuoteIntegrity(parsed, specLines));
     findings.push(...checkAnchorResolution(parsed, specLines));
     findings.push(...checkPathsExist(parsed, fs));
+    findings.push(...checkTestsBlock(parsed, fs));
     const requiredLiterals = computeRequiredLiteralsPerTask(parsed, specLines);
     findings.push(...checkPlaceholderScan(parsed, requiredLiterals));
     findings.push(...checkWaveFileDisjointness(parsed, fs));

package/extensions/phase-tracker.test.ts

@@ -51,7 +51,7 @@ const resumedBranch = (rest: Partial<Record<Phase, Status>>) => [
   phaseResult("complete", phases({ brainstorm: "skipped", ...rest })),
 ];
 
-function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean } = {}) {
+function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; beforeSettled?: (setIdle: (idle: boolean) => void) => void; sendThrows?: boolean; model?: { provider: string; id: string }; thinkingLevel?: string } = {}) {
   const handlers = new Map<string, ((event: unknown, ctx: unknown) => unknown)[]>();
   const tools: { name: string; execute: (...args: any[]) => unknown }[] = [];
   const sent: { message: any; options: any }[] = [];
@@ -62,6 +62,8 @@ function harness(options: { cwd?: string; branch?: unknown[]; idle?: boolean; be
     hasUI: false,
     isIdle: () => idle,
     sessionManager: { getBranch: () => branch },
+    model: options.model,
+    thinkingLevel: options.thinkingLevel,
   };
   const pi = {
     on(event: string, handler: (event: unknown, context: unknown) => unknown) {
@@ -705,7 +707,12 @@ const FIXTURE_PLAN = `# Fixture Plan
 
 **Files:**
 - Create: lib/task1.ts
+- Create: lib/task1.test.ts
 - Modify: file-a.ts
+- Test: lib/task1.test.ts
+
+**Tests:**
+- \`node --test lib/task1.test.ts\`
 
 This task implements helperFn() for parsing.
 
@@ -715,7 +722,12 @@ This task implements helperFn() for parsing.
 
 **Files:**
 - Create: lib/task2.ts
+- Create: lib/task2.test.ts
 - Modify: file-b.ts
+- Test: lib/task2.test.ts
+
+**Tests:**
+- \`node --test lib/task2.test.ts\`
 
 This task handles naming details.
 
@@ -1141,3 +1153,14 @@ test("replay via session_switch: pass then fail clears the stamp, rebuilt from r
   };
   assert.match(res.details.error ?? "", /plan_check/);
 });
+
+test("gauntlet_setting escalationLoop: setting absent -> ctx-derived main-loop model; setting wins when set", async () => {
+  const h = harness({ cwd: tempCwd({ piGauntlet: {} }), model: { provider: "p", id: "main" }, thinkingLevel: "medium" });
+  const tool = h.tools.find((t) => t.name === "gauntlet_setting")!;
+  const absent = (await tool.execute("g1", { key: "escalationLoop" }, undefined, undefined, h.ctx)) as { details: { key: string; implModel?: string; errors: string[] } };
+  assert.deepEqual(absent.details, { key: "escalationLoop", implModel: "p/main:medium", errors: [] });
+
+  const set = harness({ cwd: tempCwd({ piGauntlet: { escalationLoop: { implModel: "p/strong:high" } } }), model: { provider: "p", id: "main" }, thinkingLevel: "medium" });
+  const res = (await set.tools.find((t) => t.name === "gauntlet_setting")!.execute("g2", { key: "escalationLoop" }, undefined, undefined, set.ctx)) as { details: { implModel?: string } };
+  assert.equal(res.details.implModel, "p/strong:high");
+});

package/extensions/phase-tracker.ts

@@ -17,7 +17,9 @@ import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-c
 import { Text } from "@earendil-works/pi-tui";
 import { type Static, Type } from "@sinclair/typebox";
 import {
+  mainLoopModel,
   resolveClosureReview,
+  resolveEscalationLoop,
   resolveFlowGuards,
   resolveSpecCouncil,
   settingsErrorWarning,
@@ -666,7 +668,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   const GauntletSettingParams = Type.Object({
-    key: StringEnum(["specCouncil", "closureReview"] as const, {
+    key: StringEnum(["specCouncil", "closureReview", "escalationLoop"] as const, {
       description: "Which gauntlet setting to resolve (merged repo-over-preset).",
     }),
   });
@@ -681,7 +683,13 @@ export default function (pi: ExtensionAPI) {
       const payload =
         params.key === "specCouncil"
           ? { key: "specCouncil" as const, ...resolveSpecCouncil(gauntlet), errors }
-          : { key: "closureReview" as const, ...resolveClosureReview(gauntlet), errors };
+          : params.key === "closureReview"
+            ? { key: "closureReview" as const, ...resolveClosureReview(gauntlet), errors }
+            : {
+                key: "escalationLoop" as const,
+                ...resolveEscalationLoop(gauntlet, mainLoopModel(ctx.model, ctx.thinkingLevel)),
+                errors,
+              };
       return {
         content: [{ type: "text", text: "```json\n" + JSON.stringify(payload, null, 2) + "\n```" }],
         details: payload,
@@ -697,7 +705,7 @@ export default function (pi: ExtensionAPI) {
     name: "plan_check",
     label: "Plan Check",
     description:
-      "Deterministically verify an implementation plan against its spec (9 mechanical checks); " +
+      "Deterministically verify an implementation plan against its spec (mechanical checks); " +
       "a pass stamps the plan for implement-start.",
     parameters: PlanCheckParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {

package/package.json

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

package/skills/subagent-driven-development/SKILL.md

@@ -30,7 +30,7 @@ You are the **orchestrator**. You read the plan, dispatch, review the review, de
 **Do not pause to check in with the user between tasks.** The plan is already approved. Pause only when:
 
 - A subagent returns `NEEDS_CONTEXT` or `BLOCKED` (see [Implementer Status](#implementer-status))
-- A fix loop escalates per [Fix-Loop Rounds](#fix-loop-rounds) (stagnation, or budget exhausted without convergence)
+- An escalated round fails (stop note per [Fix-Loop Rounds](#fix-loop-rounds))
 - A ⚠️ workflow warning fires
 
 Reaching the end of the plan is not a pause: continue through verification and invoke `/skill:finishing-a-development-branch` as defined in [After All Tasks](#after-all-tasks-complete).
@@ -55,11 +55,13 @@ Before the first task, enter the implement phase: `phase_tracker({ action: "star
 
 For each task in `plan_tracker`:
 
-1. **Start, then dispatch implementer.** Mark the task's existing `plan_tracker` index `in_progress` before dispatch. Pass the full task text + scene-setting context + the task's plan-declared test commands as `SCOPED_TEST_COMMANDS` (or `none`). Don't make the subagent re-read the plan.
+**`SCOPED_TEST_COMMANDS`** = the task's `**Tests:**` command bullets, backticks stripped, one per line; `- none:` -> `none`; a wave = the union of its tasks' commands. `via:` bullets and `- Test:` paths are contract, not commands: they ride with the task text, never in `SCOPED_TEST_COMMANDS`.
+
+1. **Start, then dispatch implementer.** Mark the task's existing `plan_tracker` index `in_progress` before dispatch. Pass the full task text + scene-setting context + its `SCOPED_TEST_COMMANDS` (definition above) and its `**Tests:**` block verbatim. Don't make the subagent re-read the plan.
 2. **Handle implementer status** (see below).
-3. **Dispatch spec reviewer.** Pass the task text, the patch diff, the absolute spec path, and the task's `**Spec:**` anchors — SR reads the anchored ranges from the spec file itself; never inline spec excerpts. The spec wins every dispute; the authority hierarchy and finding labels live in `./spec-reviewer-prompt.md`. Anchor-less tasks (no `**Spec:**` line): task text alone is the contract. Verify the change satisfies the anchored spec — nothing missing, nothing extra.
+3. **Dispatch spec reviewer.** Pass the task text, the patch diff, the absolute spec path, and the task's `**Spec:**` anchors, plus the task's `**Tests:**` block and `- Test:` paths as contract (never as commands - SR never executes) — SR reads the anchored ranges from the spec file itself; never inline spec excerpts. The spec wins every dispute; the authority hierarchy and finding labels live in `./spec-reviewer-prompt.md`. Anchor-less tasks (no `**Spec:**` line): task text alone is the contract. Verify the change satisfies the anchored spec — nothing missing, nothing extra.
 4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
-5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves. Pass `SCOPED_TEST_COMMANDS` = the task's plan-declared commands.
+5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves. Pass the task's `SCOPED_TEST_COMMANDS`.
 6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 7. After its existing reviews accept the work (and its required commit point), mark that same task index `complete` in `plan_tracker`. A subagent exit or green tests alone are not acceptance.
 
@@ -73,11 +75,11 @@ One rule governs both review loops - spec-compliance and code-quality - in seque
 
 **Re-review dispatch rule:** every re-review task includes the complete prior review report verbatim under the marker `## Previous review report (re-review trigger)`, plus the trajectory block from the reviewer's prompt template. The marker's presence is what obligates the reviewer to emit the `TRAJECTORY:` line. You never select, summarize, or diff findings yourself - pattern-match the sentinel line only.
 
-**Fix fan-out.** When the triggering review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings, dispatch that fix round per `dispatching-parallel-agents` "Fix fan-out"; the fan-out counts as **one** fix against this budget, its scoped test gate is the consuming task/wave's plan-declared commands, and one re-review of the integrated delta follows.
+**Fix fan-out.** When the triggering review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings, dispatch that fix round per `dispatching-parallel-agents` "Fix fan-out"; the fan-out counts as **one** fix against this budget, its scoped test gate is the consuming task/wave's `SCOPED_TEST_COMMANDS`, and one re-review of the integrated delta follows.
 
-**Behaviour-change reroute.** When the triggering CR report carries `Behaviour-change: yes`, the fix round's re-review is SR first, then CR. The SR dispatch reviews the fix diff against the task's spec anchors as a first review (no `## Previous review report` marker, so no `TRAJECTORY:` line; SR carries no test commands), but its ordinal continues the task's SR-loop count - a task whose SR loop ended at review 2 gets review 3 here, and an issue-bearing rerouted SR after review 4 escalates. Issues follow the normal sequence: fix, then SR re-review pasting this SR's report. CR round numbering is unchanged. `Behaviour-change: no` re-reviews with CR only. A missing or malformed `Behaviour-change:` line is re-asked once like `Parallel-safe:` (see `dispatching-parallel-agents` "Structural probe"); still missing -> route through SR, never default to `no`. In wave mode the SR re-review targets the task(s) whose files the fix touched.
+**Behaviour-change reroute.** When the triggering CR report carries `Behaviour-change: yes`, the fix round's re-review is SR first, then CR. The SR dispatch reviews the fix diff against the task's spec anchors as a first review (no `## Previous review report` marker, so no `TRAJECTORY:` line; SR carries no test commands but does carry the task's `**Tests:**` block and `- Test:` paths), but its ordinal continues the task's SR-loop count - a task whose SR loop ended at review 2 gets review 3 here, and an issue-bearing rerouted SR after review 4 escalates. Issues follow the normal sequence: fix, then SR re-review pasting this SR's report. CR round numbering is unchanged. `Behaviour-change: no` re-reviews with CR only. A missing or malformed `Behaviour-change:` line is re-asked once like `Parallel-safe:` (see `dispatching-parallel-agents` "Structural probe"); still missing -> route through SR, never default to `no`. In wave mode the SR re-review targets the task(s) whose files the fix touched.
 
-Every fix re-dispatch (implementer) and code-review re-review carries the consuming task/wave's `SCOPED_TEST_COMMANDS`; spec-reviewer re-reviews carry none - SR never executes.
+Every fix re-dispatch (implementer) and code-review re-review carries the consuming task/wave's `SCOPED_TEST_COMMANDS`; spec-reviewer re-reviews carry the `**Tests:**` block and `- Test:` paths, no commands - SR never executes.
 
 **The sequence.** Each review that finds issues is a decision point: read the `TRAJECTORY:` line before dispatching anything (review 1 has no line - on issues, dispatch fix 1). Any clean review ends the loop.
 
@@ -88,12 +90,12 @@ Every fix re-dispatch (implementer) and code-review re-review carries the consum
 
 Every dispatched fix is verified by a re-review before escalation or task progression - the loop only ever exits on a clean review or an escalation.
 
-**Escalation report:** report reviews run per loop and the final `TRAJECTORY` verdict - report `TRAJECTORY: MISSING` if the line was absent, or quote the raw line if malformed. If the exception ran, say so explicitly: `fix 3 was the convergence exception (CONVERGING, no Critical)`.
+**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; in wave mode the escalated patch supersedes the prior one at integrate. Any review with issues, a non-`DONE` status, or a dispatch error -> stop note per `stop-note.md`; no second dispatch. Once per loop; independent of the convergence exception. No `plan_tracker` write during escalation - the task stays `in_progress` until the human decides.
 
 **Worked examples:**
 
 - Review-2 verdict `TRAJECTORY: STAGNANT (repeat of: unchecked error path in parser)` -> escalate now, before fix 2 - earlier than the ordinary budget.
-- Review-3 verdict `TRAJECTORY: CONVERGING (3 -> 1, max severity Moderate)` -> dispatch fix 3; if review 4 still finds issues, escalate with the exception named in the report.
+- Review-3 verdict `TRAJECTORY: CONVERGING (3 -> 1, max severity Moderate)` -> dispatch fix 3; if review 4 still finds issues, escalate.
 - Review-3 verdict `TRAJECTORY: CONVERGING (3 -> 2, max severity Critical)` or `TRAJECTORY: DIVERGING` or no `TRAJECTORY:` line -> escalate.
 
 ## Implementer Status
@@ -139,8 +141,11 @@ When in doubt, default. Don't downgrade reviewers — false negatives are expens
 // implementer
 subagent({ agent: "implementer", async: false, task: "<task text + context + SCOPED_TEST_COMMANDS + status protocol>" })
 
+// escalated fix round (Fix-Loop Rounds): same fix payload, model from gauntlet_setting({ key: "escalationLoop" }).implModel
+subagent({ agent: "implementer", model: "<implModel>", context: "fresh", async: false, task: "<the just-dispatched fix payload + prior review report verbatim>" })
+
 // spec compliance
-subagent({ agent: "spec-reviewer", async: false, task: "<task text + patch diff + absolute spec path + task's Spec: anchors>" })
+subagent({ agent: "spec-reviewer", async: false, task: "<task text + patch diff + absolute spec path + task's Spec: anchors + Tests: block + Test: paths>" })
 
 // code quality
 subagent({ agent: "code-reviewer", async: false, task: "<diff range + SCOPED_TEST_COMMANDS (task commands; wave: union; whole-diff: none) + ask: production-ready?>" })
@@ -174,12 +179,12 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 **Per-wave loop:**
 
-1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
+1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical, mirroring `wave-file-disjointness`: `Test`/`Test` on one path is not overlap, `Test` vs another task's `Create`/`Modify` is, `Modify`/`Modify` is). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
 2. **Start, then fan out.** Mark every wave index `in_progress` before one parallel foreground dispatch (shape below): `implementer` per task, `context: "fresh"`, `worktree: true`. Each returns a status + a patch.
-3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, the absolute spec path, and the task's `**Spec:**` anchors — SR reads the anchored ranges itself (never inline excerpts; authority hierarchy in `./spec-reviewer-prompt.md`; anchor-less tasks are task-text-only). Review starts from the diff (its hunks carry `file:line`) and reads each touched file in full, and test execution is never the reviewer's job - in either mode (persona rule; the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
+3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, the absolute spec path, and the task's `**Spec:**` anchors, plus its `**Tests:**` block and `- Test:` paths as contract — SR reads the anchored ranges itself (never inline excerpts; authority hierarchy in `./spec-reviewer-prompt.md`; anchor-less tasks are task-text-only). Review starts from the diff (its hunks carry `file:line`) and reads each touched file in full, and test execution is never the reviewer's job - in either mode (persona rule; the wave test gate in step 5 runs the wave's `SCOPED_TEST_COMMANDS`). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
 4. **Integrate.** `git apply` each task's patch sequentially onto HEAD. Apply fails = textual conflict → drop that task, finish the rest, re-run the dropped task sequentially on the updated HEAD.
-5. **Test gate.** Run the union of the wave's tasks' declared test commands on the integrated tree — the full verification set is the verify phase's job, run once. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
-6. **Quality review.** CR binds to the wave: exactly one **initial** code-review dispatch per code-touching wave, over the integrated wave diff - never per task within a wave, never batched across waves. Subsequent dispatches within the wave are re-reviews triggered only by findings, per Fix-Loop Rounds. Pass `SCOPED_TEST_COMMANDS` = the union of the wave's tasks' declared commands. Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
+5. **Test gate.** Run the wave's `SCOPED_TEST_COMMANDS` (union of its tasks' `Tests:` commands) on the integrated tree — the full verification set is the verify phase's job, run once. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
+6. **Quality review.** CR binds to the wave: exactly one **initial** code-review dispatch per code-touching wave, over the integrated wave diff - never per task within a wave, never batched across waves. Subsequent dispatches within the wave are re-reviews triggered only by findings, per Fix-Loop Rounds. Pass the wave's `SCOPED_TEST_COMMANDS`. Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
 7. **Commit and complete the wave.** After the gate passes and the wave commits, mark all of its existing indices `complete`. Leaves a clean tree; the next wave's children branch from this commit and so see the integrated work.
 
 **Two-stage review is preserved:** spec review per task (pre-integration, dispatched `spec-reviewer` — not inline), quality review per wave (post-integration). A wave commit requires one spec-review verdict per accepted task, plus one code-review verdict on the integrated diff for waves that touch code. A doc-only wave (every task's `Files:` block documentation-only, per `writing-plans`' Wave Grouping) is SR-only — the CR gate does not apply.
@@ -240,11 +245,11 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - Writing code yourself instead of dispatching.
 - Pausing between tasks for anything other than `NEEDS_CONTEXT`, `BLOCKED`, a fix-loop escalation, a workflow warning, or a spec amendment.
 - Dispatching parallel implementers on overlapping files, on a shared mutable runtime resource, or without `worktree: true`.
-- Making a subagent read the plan, inlining spec excerpts to the spec reviewer, or dispatching without a `SCOPED_TEST_COMMANDS` value.
+- Making a subagent read the plan, inlining spec excerpts to the spec reviewer, or dispatching with a `SCOPED_TEST_COMMANDS` value missing or not copied from the plan's `Tests:` bullets.
 - Dispatching `code-reviewer` before every in-scope spec-review verdict is ✅, or per task inside a wave.
 - Moving to the next task with either review still showing issues, or skipping the `Implementer Status` parse.
 - Dispatching fix 3 without a reviewer-emitted `CONVERGING` verdict, or continuing past `STAGNANT` instead of escalating.
-- Running the full verification entrypoint during the implement phase.
+- Running the full verification entrypoint, or any test command outside `SCOPED_TEST_COMMANDS`, during the implement phase.
 - Dispatching a repair before reopening the plan-task indices that own its files, whole-diff CR before parent verification passes, or conformance before the CR result is accepted.
 - Polling, joining, or relaunching an unexpectedly asynchronous dispatch, or starting on main without explicit user consent.
 

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -14,7 +14,7 @@ Dispatch a subagent with the code-reviewer template:
   PLAN_OR_REQUIREMENTS: Task N from [plan-file]
   BASE_SHA: [commit before task]
   HEAD_SHA: [current commit]
-  SCOPED_TEST_COMMANDS: [the consuming task's plan-declared commands; wave reviews: the union of the wave's tasks' declared commands; `none` for the whole-diff verify-phase review]
+  SCOPED_TEST_COMMANDS: [the consuming task's Tests: commands; wave reviews: the union of the wave's tasks' Tests: commands; `none` for the whole-diff verify-phase review]
 ```
 
 **In addition to standard code quality concerns, the reviewer should check:**

package/skills/subagent-driven-development/implementer-prompt.md

@@ -38,12 +38,17 @@ Dispatch a subagent with this prompt:
 
     Work from: [directory]
 
-    SCOPED_TEST_COMMANDS: [the task's plan-declared test commands, verbatim | none]
+    SCOPED_TEST_COMMANDS: [the task's Tests: bullets, backticks stripped, verbatim | none]
 
     Run ONLY these commands for verification. Never run a repo-wide suite,
     linter, or type-checker. If the value is `none`, run nothing and say so
     in your report.
 
+    TEST_CONTRACT: [the task's **Tests:** block verbatim (commands, via:, none:) and its Files: Create:/Test: paths]
+
+    Tests call the via: seam directly - not a wrapper, not the internals behind it.
+    Create every Create: path at exactly that path.
+
     **While you work:** If you encounter something unexpected or unclear, **ask questions**.
     It's always OK to pause and clarify. Don't guess or make assumptions.
 
@@ -109,6 +114,9 @@ Dispatch a subagent with this prompt:
     - **Status:** `DONE` | `DONE_WITH_CONCERNS` | `BLOCKED` | `NEEDS_CONTEXT`
     - What you implemented (or what you attempted, if blocked)
     - What you tested and test results
+    - Test contract: one line per SCOPED_TEST_COMMANDS command - `met` (exit 0; quote the last output line) or `unmet <reason>`;
+      one line per via: - `met <test file:line calling it>` or `unmet <reason>`; `none` when the block is `none:`.
+      Any `unmet` -> `DONE_WITH_CONCERNS`.
     - Files changed
     - Self-review findings (if any)
     - Any issues or concerns

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

@@ -24,6 +24,7 @@ Dispatch a subagent with this prompt:
 
     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]
 
     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.
 
@@ -35,6 +36,7 @@ Dispatch a subagent with this prompt:
     - **Finding grammar:** divergence findings use the existing F1..Fn finding grammar - a finding kind by prose label, not a new schema; the `Parallel-safe:` and `TRAJECTORY:` grammars are untouched.
     - **Condition match:** for every anchored clause that fixes a value, threshold, comparison, or trigger ("only when", "unless", "if", a literal), the clause row carries two indented sub-lines, before `touched-files:` where present: `spec-condition: <clause fragment quoted from the spec>` and `code-condition: <what the code checks, file:line>`. If the two differ, the clause is `PARTIAL` at most - regardless of passing tests. A plausible condition is not the specified condition.
     - **Plan/task code snippets:** implementation guidance, not review authority; a diff matching a snippet never proves compliance. For anchor-less tasks the task text's prose requirements remain your contract.
+    - **Task contract (Tests:/via:/Files:):** The task's `**Tests:**` block, `via:`, and its `Files:` paths supplement the anchored spec where it is silent; the anchored spec wins a conflict - report the divergence once, against the plan, never against code corrected to the spec. Findings: a `Create:` path absent from the diff or created elsewhere; a test that does not call the `via:` entry point; a `Tests:` block the diff contradicts. Existing files need no diff touch. You never run the commands.
 
     ## CRITICAL: Do Not Trust the Report
 
@@ -64,7 +66,7 @@ Dispatch a subagent with this prompt:
 
     ## Your Job
 
-    <!-- clause decomposition / snippet non-authority / whole-file reads: keep in lockstep with agents/spec-reviewer.md — change them together or not at all -->
+    <!-- clause decomposition / snippet non-authority / whole-file reads / task-contract supplement: keep in lockstep with agents/spec-reviewer.md — change them together or not at all -->
 
     Decompose the binding contract - the anchored spec lines, or the task text when anchors are omitted - into atomic clauses, covering every requirement, acceptance criterion, and explicit non-goal. Each independently checkable statement is one clause; a sentence listing three requirements yields three clauses.
 

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

@@ -0,0 +1,48 @@
+# Stop note (subagent-driven-development companion)
+
+Emitted when no escalation model resolves, the escalated dispatch errors, or its one escalated round fails (see `SKILL.md` "Fix-Loop Rounds"); 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. Wave mode: one note per stalled task, after the current batch returns.
+
+## Template
+
+```
+Stopped on task <n> (<title>)[; escalated round on <implModel> did not resolve it].
+
+Problem: <one sentence: what is wrong and why the fixes could not resolve it>
+  <file:line> - <quoted finding from the final review>
+  <failing test/command + 1-3 line output snippet, when present>
+
+Fix options:
+  a) <concrete change>
+  b) <concrete change - amending spec section X / plan task n is a normal option>
+  c) <optional third>
+
+Pick one, or give another fix.
+```
+
+## Rules
+
+- Bracketed header clause only when an escalated round actually ran; omit it when no model was resolvable or the dispatch errored.
+- Residual issues from the final review report only; quote, do not summarise history.
+- When no escalated round ran, the Problem is the reason: "no escalation model resolvable", or the implementer's non-DONE status text / the dispatch error, quoted; skip the file:line and test lines.
+- Options are actionable edits. Spec/plan amendment is first-class - stalls are usually a slightly contradictory spec, not a capability gap.
+- Never offer "skip the task". If the task is genuinely droppable, say so and name the plan tasks that depend on it.
+- No trajectory verdicts, round history, review counts, or paths to spec/plan/review reports.
+- Plain words, ASCII, no headings. One screen.
+
+## Example
+
+```
+Stopped on task 4 (retry policy for the outbound client); escalated round on <provider>/<model>:high did not resolve it.
+
+Problem: `RetryPolicy.next()` returns 0 ms for the first retry, but the client treats 0 as "no
+retry", so the first failure is never retried.
+  src/net/retry.ts:41 - `return attempt * this.baseMs;`
+  npm test -- retry > "retries once after a transient failure":
+    expected 1 call after failure, got 0
+
+Fix options:
+  a) start the backoff at `baseMs` (`(attempt + 1) * this.baseMs`)
+  b) amend plan task 4 so the client retries on any non-negative delay, and keep the policy as is
+
+Pick one, or give another fix.
+```

package/skills/test-driven-development/SKILL.md

@@ -117,11 +117,11 @@ Don't add features, refactor other code, or "improve" beyond what the test requi
 
 Run the test. Confirm:
 - New test passes
-- The task's scoped commands pass (full-suite verification belongs to the verify phase)
+- The task's `Tests:` commands pass (full-suite verification belongs to the verify phase)
 - Output is pristine (no errors, no warnings)
 
 **Test fails?** Fix code, not test.
-**Scoped commands fail?** Fix now — don't move on with broken tests.
+**`Tests:` commands fail?** Fix now — don't move on with broken tests.
 
 ### REFACTOR — Clean Up
 
@@ -176,7 +176,7 @@ Before marking work complete:
 - [ ] Watched each test fail before implementing
 - [ ] Each test failed for expected reason (feature missing, not typo)
 - [ ] Wrote minimal code to pass each test
-- [ ] The task's scoped commands pass (full suite belongs to the verify phase)
+- [ ] The task's `Tests:` commands pass (full suite belongs to the verify phase)
 - [ ] Output pristine (no errors, warnings)
 - [ ] Tests use real code (mocks only if unavoidable)
 - [ ] Edge cases and errors covered

package/skills/verification-before-completion/reference/settings-precedence.md

@@ -15,7 +15,7 @@ If the repo file defines a `piGauntlet.<key>` at all, that definition **replaces
 the preset's for that key entirely - the two are never merged leaf-by-leaf. If the
 repo file does not define the key, the preset's value is used unchanged. This is
 exactly pi's own `deepMergeSettings` behaviour: it spreads the second-level keys
-(`specCouncil`, `closureReview`, `flowGuards`, `verifyBeforeShip`) wholesale, and
+(`specCouncil`, `closureReview`, `flowGuards`, `verifyBeforeShip`, `escalationLoop`) wholesale, and
 does not recurse into their leaves.
 
 **Caveat - partial definitions drop siblings.** Because the replace is