pi-gauntlet 5.3.7 → 5.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v5.5.0 - 2026-09-10
+
+- `writing-plans`: every task carries a `**Tests:**` block - scoped commands anchored to the task's `Test:` paths, optional `via:` entry point, or `none: <category>`; the plan grammar `plan_check` enforces moves to `skills/writing-plans/reference/plan-contract.md`. (#28)
+- `plan_check`: new `tests-block` check (block present and well-formed, every command segment names a task `Test:` path, no broadening selectors or `cd`/`sh -c`/`eval`/`$(`, no segment equal to a header `**Verification:**` segment); `header-entrypoint` compares `Run:` payloads by segment, so `npm test` no longer slips past `npm test && npm run lint`; `Test:` entries no longer count as file ownership in `wave-file-disjointness`. (#28)
+- `subagent-driven-development`, `test-driven-development`, prompts, `spec-reviewer`: `SCOPED_TEST_COMMANDS` comes from the `Tests:` block; implementer reports `met`/`unmet` per command and per `via:`; the spec reviewer treats the task contract as a supplement the anchored spec overrides. (#28)
+
+## v5.4.0 - 2026-09-10
+
+- `subagent-driven-development`: a stalled review fix loop runs one escalated fix round (`implementer`, `context: fresh`, model from new `piGauntlet.escalationLoop.implModel`, default main-loop model + thinking) before stopping; the stop is a one-screen problem note (`stop-note.md`) with concrete fix options, replacing the trajectory-log escalation report. `gauntlet_setting` gains the `escalationLoop` key. (#29)
+
 ## v5.3.7 - 2026-09-10
 
 - `brainstorming`: the standalone "does this replace a prior spec" question is gone - the gather scout names candidate predecessor specs and round 1 states them; the design is presented in two rounds (architecture/components/data flow, then errors/testing/docs) with one approval each. (#27)

package/README.md

@@ -71,7 +71,7 @@ pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
 - **17 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Four more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`.
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
-- **3 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers plan_check, a deterministic plan linter (9 mechanical plan-vs-spec checks) whose pass stamp gates implement-start inside a gauntlet flow. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
+- **3 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
 pi-gauntlet is **opinionated**: every non-trivial change is *meant* to ride this one pipeline, entered through `brainstorming`. Enforcement is opt-in by entry, not ambient: once brainstorming starts a flow, the phase-tracker extension mechanically blocks a phase from closing before its gate runs, and warns once if the main loop writes code during implement (subagents own implement-phase edits). A change made *without* entering the flow (a typo, a formatting run, a dependency bump - see "When to use / when NOT to use") is not gated; the discipline of routing real work through the pipeline is a convention the tooling supports, not a trap it springs on every edit.
 

package/agents/spec-reviewer.md

@@ -13,14 +13,15 @@ You are a spec compliance reviewer. Your job is to verify that an implementation
 
 ## Process
 
-<!-- clause decomposition / snippet non-authority / whole-file reads: keep in lockstep with skills/subagent-driven-development/spec-reviewer-prompt.md — change them together or not at all -->
+<!-- clause decomposition / snippet non-authority / whole-file reads / task-contract supplement: keep in lockstep with skills/subagent-driven-development/spec-reviewer-prompt.md — change them together or not at all -->
 
 1. 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. Every clause gets a verdict row.
-2. Read the implementation. Do not trust summaries. Read every diff-touched file in full, not just the hunks - continue in chunks until the file is exhausted; if you cannot exhaust it, say so in the report instead of treating the file as covered. A statement elsewhere in a touched file that the change now contradicts is in scope.
-3. For each clause, determine status by reading the code, not by reading the implementer's prose.
-4. Never run tests, linters, or type-checkers. Your evidence is the diff and the files you read. Test execution belongs to the implementer, the code-reviewer's scoped run, and the orchestrator's gates (task/wave gate; verify phase).
-5. Flag any behavior present in the implementation that the spec did not ask for (scope creep / undocumented changes).
-6. Flag any clause from the spec that is missing from the implementation.
+2. 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.
+3. Read the implementation. Do not trust summaries. Read every diff-touched file in full, not just the hunks - continue in chunks until the file is exhausted; if you cannot exhaust it, say so in the report instead of treating the file as covered. A statement elsewhere in a touched file that the change now contradicts is in scope.
+4. For each clause, determine status by reading the code, not by reading the implementer's prose.
+5. Never run tests, linters, or type-checkers. Your evidence is the diff and the files you read. Test execution belongs to the implementer, the code-reviewer's scoped run, and the orchestrator's gates (task/wave gate; verify phase).
+6. Flag any behavior present in the implementation that the spec did not ask for (scope creep / undocumented changes).
+7. Flag any clause from the spec that is missing from the implementation.
 
 ## Output format
 

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

@@ -4,6 +4,8 @@ import {
   mergeGauntlet,
   resolveSpecCouncil,
   resolveClosureReview,
+  resolveEscalationLoop,
+  mainLoopModel,
   resolveFlowGuards,
   resolveVerifyBeforeShip,
   settingsErrorWarning,
@@ -24,6 +26,41 @@ test("mergeGauntlet: undefined layers -> {}", () => {
   assert.deepEqual(mergeGauntlet(undefined, undefined), {});
 });
 
+test("mergeGauntlet: repo escalationLoop replaces preset whole-object", () => {
+  const preset = { escalationLoop: { implModel: "p/preset:high" }, closureReview: { model: "m" } };
+  const repo = { escalationLoop: {} };
+  const merged = mergeGauntlet(preset, repo);
+  assert.deepEqual(merged.escalationLoop, {});
+  assert.deepEqual(merged.closureReview, { model: "m" });
+});
+
+test("escalationLoop: absent/empty/null/non-string -> mainLoop", () => {
+  const main = "p/main:medium";
+  assert.equal(resolveEscalationLoop({}, main).implModel, main);
+  assert.equal(resolveEscalationLoop({ escalationLoop: {} }, main).implModel, main);
+  assert.equal(resolveEscalationLoop({ escalationLoop: { implModel: "" } }, main).implModel, main);
+  assert.equal(resolveEscalationLoop({ escalationLoop: { implModel: null } }, main).implModel, main);
+  assert.equal(resolveEscalationLoop({ escalationLoop: { implModel: 42 } }, main).implModel, main);
+});
+
+test("escalationLoop: non-empty string wins, trimmed; undefined mainLoop passes through", () => {
+  assert.equal(
+    resolveEscalationLoop({ escalationLoop: { implModel: " p/x:high " } }, "p/main:medium").implModel,
+    "p/x:high",
+  );
+  assert.equal(resolveEscalationLoop({}, undefined).implModel, undefined);
+});
+
+test("mainLoopModel: always suffixed; unset -> off, max -> xhigh, recognised pass through", () => {
+  const m = { provider: "p", id: "id" };
+  assert.equal(mainLoopModel(m, undefined), "p/id:off");
+  assert.equal(mainLoopModel(m, "off"), "p/id:off");
+  assert.equal(mainLoopModel(m, "medium"), "p/id:medium");
+  assert.equal(mainLoopModel(m, "xhigh"), "p/id:xhigh");
+  assert.equal(mainLoopModel(m, "max"), "p/id:xhigh");
+  assert.equal(mainLoopModel(undefined, "medium"), undefined);
+});
+
 test("specCouncil: non-empty string array -> council", () => {
   const r = resolveSpecCouncil({ specCouncil: { members: ["p/m1", " p/m2 "], chair: "p/c" } });
   assert.equal(r.verdict, "council");

package/extensions/lib/gauntlet-settings.ts

@@ -8,6 +8,7 @@ export interface PiGauntlet {
   closureReview?: { enforce?: unknown; model?: unknown; maxFixRounds?: unknown };
   flowGuards?: { enforce?: unknown; specDirs?: unknown };
   verifyBeforeShip?: { testCommands?: unknown; warningReference?: unknown };
+  escalationLoop?: { implModel?: unknown };
 }
 
 // Whole-object second-level merge: each piGauntlet key present in the repo layer
@@ -87,6 +88,29 @@ export function resolveClosureReview(g: PiGauntlet): ClosureReviewResolved {
   return { model, enforce, maxFixRounds };
 }
 
+export interface EscalationLoopResolved {
+  implModel: string | undefined;
+}
+
+export function resolveEscalationLoop(g: PiGauntlet, mainLoop: string | undefined): EscalationLoopResolved {
+  const raw = g.escalationLoop?.implModel;
+  return { implModel: nonEmptyString(raw) ? raw.trim() : mainLoop };
+}
+
+const THINKING_SUFFIXES = new Set(["off", "minimal", "low", "medium", "high", "xhigh"]);
+
+// Always emit a suffix so pi-cohort's applyThinkingSuffix never falls back to the
+// implementer's configured thinking; pi's "max" has no pi-cohort equivalent -> xhigh.
+export function mainLoopModel(
+  model: { provider: string; id: string } | undefined,
+  thinkingLevel: string | undefined,
+): string | undefined {
+  if (!model) return undefined;
+  const level =
+    thinkingLevel === "max" ? "xhigh" : THINKING_SUFFIXES.has(thinkingLevel ?? "") ? thinkingLevel : "off";
+  return `${model.provider}/${model.id}:${level}`;
+}
+
 export interface FlowGuardsResolved {
   enforce: boolean;
   specDirs: string[];

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

@@ -38,6 +38,11 @@ const VALID_PLAN = `# Fixture Plan
 **Files:**
 - Create: extensions/lib/fixture-task1.ts
 - Modify: extensions/lib/fixture-shared.ts
+- Test: extensions/lib/fixture-task1.test.ts
+
+**Tests:**
+- \`node --test extensions/lib/fixture-task1.test.ts\`
+- via: \`helperFn()\`
 
 This task implements helperFn() for parsing.
 
@@ -48,6 +53,10 @@ This task implements helperFn() for parsing.
 **Files:**
 - Create: extensions/lib/fixture-task2.ts
 - Modify: extensions/lib/fixture-other.ts
+- Test: extensions/lib/fixture-task2.test.ts
+
+**Tests:**
+- \`node --test extensions/lib/fixture-task2.test.ts\`
 
 This task handles naming details.
 
@@ -61,6 +70,10 @@ Solo: lone remaining task
 
 **Files:**
 - Modify: extensions/lib/fixture-task3.ts
+- Test: extensions/lib/fixture-task3.test.ts
+
+**Tests:**
+- \`node --test extensions/lib/fixture-task3.test.ts\`
 
 The literal TODO is intentionally documented here per spec quote-integrity requirement.
 
@@ -136,8 +149,8 @@ test("check 1 fail-closed: missing '## Spec coverage' table entirely", () => {
 
 test("check 2 quote-integrity: required verbatim literal missing from owner task body", () => {
   const mutated = VALID_PLAN.replace(
-    "This task implements helperFn() for parsing.",
-    "This task implements the helper for parsing.",
+    "- via: `helperFn()`\n\nThis task implements helperFn() for parsing.",
+    "- via: `parserSeam()`\n\nThis task implements the helper for parsing.",
   );
   const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
   const qi = findingsFor(findings, "quote-integrity");
@@ -374,8 +387,61 @@ test("Verification quote-integrity: task body containing only a sub-command of a
   assert.deepEqual(findingsFor(findings, "quote-integrity"), []);
 });
 
+const HE = (plan: string) => findingsFor(checkPlan(plan, SPEC_TEXT, alwaysTruePort()), "header-entrypoint");
+const WD = (plan: string) => findingsFor(checkPlan(plan, SPEC_TEXT, alwaysTruePort()), "wave-file-disjointness");
+
+test("header-entrypoint: Run: with backticked payload npm test under header npm test && npm run lint fails (regression for the hole)", () => {
+  const mutated = VALID_PLAN.replace("**Verification:** npm run fixture-verify", "**Verification:** npm test && npm run lint")
+    .replace("This task handles naming details.", "- [ ] **Step 1: verify**\n\n  Run: `npm test`\n  Expected: PASS");
+  assert.ok(HE(mutated).some((f) => f.text.includes("Run: `npm test`")));
+});
+
+test("header-entrypoint: Run: npm test && echo ok fails", () => {
+  const mutated = VALID_PLAN.replace("**Verification:** npm run fixture-verify", "**Verification:** npm test")
+    .replace("This task handles naming details.", "Run: npm test && echo ok");
+  assert.ok(HE(mutated).some((f) => f.text.includes("Run: npm test && echo ok")));
+});
+
+test("header-entrypoint: Run: npm test -- x.test.ts passes under bare and backticked header npm test", () => {
+  for (const header of ["**Verification:** npm test", "**Verification:** `npm test`"]) {
+    const mutated = VALID_PLAN.replace("**Verification:** npm run fixture-verify", header)
+      .replace("This task handles naming details.", "Run: npm test -- x.test.ts");
+    assert.deepEqual(HE(mutated), [], header);
+  }
+});
+
+test("header-entrypoint: Run: line with two backtick spans - both are payload", () => {
+  const mutated = VALID_PLAN.replace("This task handles naming details.", "Run: `echo a` then `npm run fixture-verify`");
+  assert.equal(HE(mutated).length, 1);
+});
+
+test("header-entrypoint: Tests: bullets are judged by tests-block, not here", () => {
+  const mutated = VALID_PLAN.replace(
+    "**Tests:**\n- `node --test extensions/lib/fixture-task2.test.ts`",
+    "**Tests:**\n- `npm run fixture-verify`",
+  );
+  assert.deepEqual(HE(mutated), []);
+  assert.ok(findingsFor(checkPlan(mutated, SPEC_TEXT, alwaysTruePort()), "tests-block").some((f) => f.reason.includes("full-suite command")));
+});
+
+test("wave-file-disjointness: Test/Test allowed; Test vs Modify conflict; Modify/Modify conflict", () => {
+  const shared = "- Test: extensions/lib/fixture-shared.test.ts\n";
+  const testTest = VALID_PLAN.replace("- Test: extensions/lib/fixture-task1.test.ts\n", shared).replace("- Test: extensions/lib/fixture-task2.test.ts\n", shared)
+    .replace("- `node --test extensions/lib/fixture-task1.test.ts`", "- `node --test extensions/lib/fixture-shared.test.ts`")
+    .replace("- `node --test extensions/lib/fixture-task2.test.ts`", "- `node --test extensions/lib/fixture-shared.test.ts`");
+  assert.deepEqual(WD(testTest), []);
+  const testModify = VALID_PLAN.replace("- Test: extensions/lib/fixture-task2.test.ts\n", "- Test: extensions/lib/fixture-shared.ts\n")
+    .replace("- `node --test extensions/lib/fixture-task2.test.ts`", "- `node --test extensions/lib/fixture-shared.ts`");
+  assert.ok(WD(testModify).some((f) => f.reason.includes("fixture-shared.ts")));
+  const modifyModify = VALID_PLAN.replace("- Modify: extensions/lib/fixture-other.ts", "- Modify: extensions/lib/fixture-shared.ts");
+  assert.ok(WD(modifyModify).some((f) => f.reason.includes("fixture-shared.ts")));
+});
+
 test("Verification quote-integrity: task-owned literal check unchanged", () => {
-  const mutated = VALID_PLAN.replace("This task implements helperFn() for parsing.", "This task implements the helper.");
+  const mutated = VALID_PLAN.replace(
+    "- via: `helperFn()`\n\nThis task implements helperFn() for parsing.",
+    "- via: `parserSeam()`\n\nThis task implements the helper.",
+  );
   const qi = findingsFor(checkPlan(mutated, SPEC_TEXT, alwaysTruePort()), "quote-integrity");
   assert.ok(qi.some((f) => f.reason.includes("Task 1 body does not contain the required verbatim literal `helperFn()`")));
 });
@@ -405,6 +471,10 @@ Solo: lone remaining task
 
 **Files:**
 - Modify: extensions/lib/fixture-task1.ts
+- Test: extensions/lib/plan-check.test.ts
+
+**Tests:**
+- \`node --test extensions/lib/plan-check.test.ts\`
 
 Run node --test extensions/lib/plan-check.test.ts and confirm green.
 
@@ -423,8 +493,8 @@ test("quote-integrity: header entrypoint literal on an anchored line is satisfie
 
 test("quote-integrity: scoped command on the same anchored line is still required in the task body", () => {
   const mutated = ENTRYPOINT_PLAN.replace(
-    "Run node --test extensions/lib/plan-check.test.ts and confirm green.",
-    "Run the scoped test and confirm green.",
+    "- Test: extensions/lib/plan-check.test.ts\n\n**Tests:**\n- `node --test extensions/lib/plan-check.test.ts`\n\nRun node --test extensions/lib/plan-check.test.ts and confirm green.",
+    "- Test: extensions/lib/other.test.ts\n\n**Tests:**\n- `node --test extensions/lib/other.test.ts`\n\nRun the scoped test and confirm green.",
   );
   const qi = findingsFor(checkPlan(mutated, ENTRYPOINT_SPEC, alwaysTruePort()), "quote-integrity");
   assert.equal(qi.length, 1);
@@ -522,7 +592,7 @@ test("check 4 fail-closed: invalid glob (port throws)", () => {
 
 test("check 4 fail-closed: task missing **Files:** block", () => {
   const mutated = VALID_PLAN.replace(
-    "**Files:**\n- Modify: extensions/lib/fixture-task3.ts\n\n",
+    "**Files:**\n- Modify: extensions/lib/fixture-task3.ts\n- Test: extensions/lib/fixture-task3.test.ts\n\n**Tests:**\n- `node --test extensions/lib/fixture-task3.test.ts`\n\n",
     "",
   );
   const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
@@ -627,6 +697,10 @@ Solo: only task in this wave
 
 **Files:**
 - Create: extensions/lib/exemption-task1.ts
+- Test: extensions/lib/exemption-task1.test.ts
+
+**Tests:**
+- \`node --test extensions/lib/exemption-task1.test.ts\`
 
 The literal TODO is intentionally documented here per spec quote-integrity requirement.
 
@@ -672,8 +746,8 @@ test("aggregate: independent mutations across three checks are all reported toge
   let mutated = VALID_PLAN;
   mutated = mutated.replace("Solo: lone remaining task\n\n", "");
   mutated = mutated.replace(
-    "This task implements helperFn() for parsing.",
-    "This task implements the helper for parsing.",
+    "- via: `helperFn()`\n\nThis task implements helperFn() for parsing.",
+    "- via: `parserSeam()`\n\nThis task implements the helper for parsing.",
   );
   mutated = mutated.replace(
     "- Modify: extensions/lib/fixture-other.ts",
@@ -727,3 +801,202 @@ test("sha256 returns lowercase hex of the expected length", () => {
   assert.equal(digest.length, 64);
   assert.match(digest, /^[0-9a-f]+$/);
 });
+
+const T2_TESTS = "**Tests:**\n- `node --test extensions/lib/fixture-task2.test.ts`\n";
+const T2_FILES_TEST = "- Test: extensions/lib/fixture-task2.test.ts\n";
+
+function tb(plan: string, spec = SPEC_TEXT, fs: FsPort = alwaysTruePort()): PlanCheckFinding[] {
+  return findingsFor(checkPlan(plan, spec, fs), "tests-block");
+}
+
+test("tests-block: block missing when a task has no **Tests:**", () => {
+  const mutated = VALID_PLAN.replace(T2_TESTS, "");
+  assert.ok(tb(mutated).some((f) => f.reason.includes("block missing") && f.reason.includes("Task 2")));
+});
+
+test("tests-block: block missing when **Files:** is absent", () => {
+  const mutated = VALID_PLAN.replace(
+    "**Files:**\n- Create: extensions/lib/fixture-task2.ts\n- Modify: extensions/lib/fixture-other.ts\n" + T2_FILES_TEST + "\n" + T2_TESTS,
+    "",
+  );
+  const f = tb(mutated);
+  assert.ok(f.some((x) => x.reason.includes("block missing") && x.reason.includes("Task 2")));
+});
+
+test("tests-block: misplaced block (before Files:) fires without block missing", () => {
+  const mutated = VALID_PLAN.replace(
+    "**Files:**\n- Create: extensions/lib/fixture-task2.ts",
+    T2_TESTS + "\n**Files:**\n- Create: extensions/lib/fixture-task2.ts",
+  ).replace("\n" + T2_TESTS + "\nThis task handles naming details.", "\nThis task handles naming details.");
+  const f = tb(mutated);
+  assert.ok(f.some((x) => x.reason.includes("misplaced")));
+  assert.ok(!f.some((x) => x.reason.includes("block missing")));
+});
+
+test("tests-block: duplicated **Tests:** heading is misplaced", () => {
+  const mutated = VALID_PLAN.replace("This task handles naming details.", T2_TESTS + "\nThis task handles naming details.");
+  assert.ok(tb(mutated).some((x) => x.reason.includes("misplaced")));
+});
+
+test("tests-block: text after the heading is misplaced, not missing", () => {
+  const mutated = VALID_PLAN.replace("**Tests:**\n- `node --test extensions/lib/fixture-task2.test.ts`", "**Tests:** see below\n- `node --test extensions/lib/fixture-task2.test.ts`");
+  const f = tb(mutated);
+  assert.ok(f.some((x) => x.reason.includes("misplaced")));
+  assert.ok(!f.some((x) => x.reason.includes("block missing")));
+});
+
+test("tests-block: a Delete: bullet before **Tests:** is legal", () => {
+  const mutated = VALID_PLAN.replace(T2_FILES_TEST, T2_FILES_TEST + "- Delete: extensions/lib/fixture-legacy.ts\n");
+  assert.deepEqual(tb(mutated), []);
+});
+
+test("tests-block: block empty (via: alone)", () => {
+  const mutated = VALID_PLAN.replace(T2_TESTS, "**Tests:**\n- via: `naming()`\n");
+  assert.ok(tb(mutated).some((x) => x.reason.includes("block empty")));
+});
+
+test("tests-block: malformed bullet after a valid one; block continues; a - [ ] step terminates", () => {
+  const mutated = VALID_PLAN.replace(
+    T2_TESTS,
+    T2_TESTS + "- node --test x\n- via: `naming()`\n- [ ] **Step 1: nothing**\n",
+  );
+  const f = tb(mutated);
+  assert.equal(f.filter((x) => x.reason.includes("malformed")).length, 1);
+  assert.ok(!f.some((x) => x.reason.includes("block empty")));
+});
+
+test("tests-block: none: with a command, none: with via:, two none: -> contradictory", () => {
+  for (const block of [
+    "**Tests:**\n- none: docs\n- `node --test extensions/lib/fixture-task2.test.ts`\n",
+    "**Tests:**\n- none: docs\n- via: `naming()`\n",
+    "**Tests:**\n- none: docs\n- none: config\n",
+  ]) {
+    const mutated = VALID_PLAN.replace(T2_TESTS, block);
+    assert.ok(tb(mutated).some((x) => x.reason.includes("contradictory")), block);
+  }
+});
+
+test("tests-block: none: while a Test: path is declared -> unused Test: path", () => {
+  const mutated = VALID_PLAN.replace(T2_TESTS, "**Tests:**\n- none: docs\n");
+  assert.ok(tb(mutated).some((x) => x.reason.includes("unused `Test:` path")));
+});
+
+test("tests-block: none: docs, config with no Test: path is valid", () => {
+  const mutated = VALID_PLAN.replace(T2_FILES_TEST, "").replace(T2_TESTS, "**Tests:**\n- none: docs, config\n");
+  assert.deepEqual(tb(mutated), []);
+});
+
+test("tests-block: via: with commands passes", () => {
+  const mutated = VALID_PLAN.replace(T2_TESTS, T2_TESTS + "- via: `naming()` - the seam\n");
+  assert.deepEqual(tb(mutated), []);
+});
+
+test("tests-block: unknown Test: path unless it exists or another task Create:s it", () => {
+  const fs: FsPort = { exists: () => false, glob: () => [] };
+  assert.ok(tb(VALID_PLAN, SPEC_TEXT, fs).some((x) => x.reason.includes("unknown `Test:` path")));
+  const created = VALID_PLAN.replace(
+    "- Create: extensions/lib/fixture-task1.ts",
+    "- Create: extensions/lib/fixture-task1.ts\n- Create: extensions/lib/fixture-task1.test.ts\n- Create: extensions/lib/fixture-task2.test.ts\n- Create: extensions/lib/fixture-task3.test.ts",
+  );
+  assert.deepEqual(tb(created, SPEC_TEXT, fs), []);
+});
+
+test("tests-block: segment without a Test: token is not anchored", () => {
+  const mutated = VALID_PLAN.replace(T2_TESTS, "**Tests:**\n- `node --test extensions/lib/fixture-task2.test.ts && echo done`\n");
+  assert.ok(tb(mutated).some((x) => x.reason.includes("not anchored")));
+});
+
+test("tests-block: pipe segment equal to a header segment; tee log has no anchor", () => {
+  const mutated = VALID_PLAN.replace("**Verification:** npm run fixture-verify", "**Verification:** npm test")
+    .replace(T2_FILES_TEST, "- Test: x.test.ts\n")
+    .replace(T2_TESTS, "**Tests:**\n- `npm test | tee log && node --test x.test.ts`\n");
+  const f = tb(mutated);
+  assert.ok(f.some((x) => x.reason.includes("full-suite command") && x.reason.includes("npm test")));
+  assert.ok(f.some((x) => x.reason.includes("not anchored") && x.reason.includes("tee log")));
+});
+
+test("tests-block: broadening selectors tests/ and tests/*.py fail; Test: value tests/ never anchors", () => {
+  const dir = VALID_PLAN.replace(T2_TESTS, "**Tests:**\n- `node --test extensions/lib/fixture-task2.test.ts tests/`\n");
+  assert.ok(tb(dir).some((x) => x.reason.includes("broadening")));
+  const glob = VALID_PLAN.replace(T2_TESTS, "**Tests:**\n- `node --test extensions/lib/fixture-task2.test.ts tests/*.py`\n");
+  assert.ok(tb(glob).some((x) => x.reason.includes("broadening")));
+  const dirAnchor = VALID_PLAN.replace(T2_FILES_TEST, "- Test: tests/\n").replace(
+    T2_TESTS,
+    "**Tests:**\n- `node --test tests/`\n",
+  );
+  assert.ok(tb(dirAnchor).some((x) => x.reason.includes("not anchored")));
+});
+
+test("tests-block: unsupported shell (cd, sh -c, bash -c, eval, $( )", () => {
+  for (const cmd of [
+    "cd pkg && pytest tests/a.py",
+    "sh -c 'node --test extensions/lib/fixture-task2.test.ts'",
+    "bash -c 'node --test extensions/lib/fixture-task2.test.ts'",
+    "eval node --test extensions/lib/fixture-task2.test.ts",
+    "node --test $(echo extensions/lib/fixture-task2.test.ts)",
+  ]) {
+    const mutated = VALID_PLAN.replace(T2_TESTS, "**Tests:**\n- `" + cmd + "`\n");
+    assert.ok(tb(mutated).some((x) => x.reason.includes("unsupported shell")), cmd);
+  }
+});
+
+test("tests-block: segment equal to a header segment (bare, &&, comma-listed, trailing prose, a && b)", () => {
+  for (const header of [
+    "**Verification:** npm test",
+    "**Verification:** `npm test`",
+    "**Verification:** npm test && npm run lint",
+    "**Verification:** `npm test`, `npm run lint`",
+    "**Verification:** `npm test` (bundles lint)",
+  ]) {
+    const mutated = VALID_PLAN.replace("**Verification:** npm run fixture-verify", header).replace(
+      T2_TESTS,
+      "**Tests:**\n- `npm run lint`\n- `npm test`\n",
+    );
+    const f = tb(mutated);
+    assert.ok(f.some((x) => x.reason.includes("full-suite command") && x.text === "- `npm test`"), header);
+    if (header.includes("npm run lint")) assert.ok(f.some((x) => x.reason.includes("full-suite command") && x.text.includes("lint")), header);
+  }
+  const ab = VALID_PLAN.replace("**Verification:** npm run fixture-verify", "**Verification:** a && b").replace(T2_TESTS, "**Tests:**\n- `b`\n");
+  assert.ok(tb(ab).some((x) => x.reason.includes("full-suite command")));
+});
+
+test("tests-block: npm test -- x.test.ts passes under header npm test (bare and backticked); the header segment npm test alone fails", () => {
+  for (const header of ["**Verification:** npm test", "**Verification:** `npm test`"]) {
+    const ok = VALID_PLAN.replace("**Verification:** npm run fixture-verify", header)
+      .replace(T2_FILES_TEST, "- Test: x.test.ts\n")
+      .replace(T2_TESTS, "**Tests:**\n- `npm test -- x.test.ts`\n");
+    assert.deepEqual(tb(ok, SPEC_TEXT, alwaysTruePort()), [], header);
+  }
+});
+
+test("tests-block: header segment that is itself scoped is still rejected as a bullet", () => {
+  const mutated = VALID_PLAN.replace("**Verification:** npm run fixture-verify", "**Verification:** node --test x.test.ts && npm run lint")
+    .replace(T2_FILES_TEST, "- Test: x.test.ts\n")
+    .replace(T2_TESTS, "**Tests:**\n- `node --test x.test.ts`\n");
+  assert.ok(tb(mutated).some((x) => x.reason.includes("full-suite command")));
+});
+
+test("tests-block: passing forms - multi-path, ::filter -v, -k name, -- passthrough, line-suffixed Test:", () => {
+  const multi = VALID_PLAN.replace(T2_TESTS, "**Tests:**\n- `node --test extensions/lib/fixture-task2.test.ts extensions/lib/fixture-task1.test.ts`\n")
+    .replace(T2_FILES_TEST, T2_FILES_TEST + "- Test: extensions/lib/fixture-task1.test.ts\n");
+  assert.deepEqual(tb(multi), []);
+  const filt = VALID_PLAN.replace(T2_FILES_TEST, "- Test: tests/a.py\n").replace(T2_TESTS, "**Tests:**\n- `pytest tests/a.py::test_x -v -k name --filter x`\n");
+  assert.deepEqual(tb(filt), []);
+  const passthrough = VALID_PLAN.replace(T2_TESTS, "**Tests:**\n- `npm run fixture-verify -- extensions/lib/fixture-task2.test.ts`\n");
+  assert.deepEqual(tb(passthrough), []);
+  const suffixed = VALID_PLAN.replace(T2_FILES_TEST, "- Test: extensions/lib/fixture-task2.test.ts:10-20\n");
+  assert.deepEqual(tb(suffixed), []);
+});
+
+test("tests-block: no path normalization - ./x and x differ, as in Files:", () => {
+  const mutated = VALID_PLAN.replace(T2_FILES_TEST, "- Test: ./extensions/lib/fixture-task2.test.ts\n");
+  assert.ok(tb(mutated).some((x) => x.reason.includes("not anchored")));
+});
+
+test("tests-block: fenced **Tests:** lines are ignored", () => {
+  const mutated = VALID_PLAN.replace(
+    "This task handles naming details.",
+    "This task handles naming details.\n\n```markdown\n**Tests:**\n- none: docs\n```",
+  );
+  assert.deepEqual(tb(mutated), []);
+});