pi-gauntlet 5.4.0 → 5.5.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## v5.5.1 - 2026-09-10
+
+- `linear`: copyable, version-scoped recovery for attachment-download 401s resolves the decrypted credential through linearis instead of reading encrypted token storage. Restricts credential delivery to HTTPS Linear uploads, rejects redirects, and checks downloaded bytes; an offline regression executes the documented example.
+
+## 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)

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/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), []);
+});

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

@@ -707,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.
 
@@ -717,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.
 

package/extensions/phase-tracker.ts

@@ -705,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.4.0",
+  "version": "5.5.1",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/linear/SKILL.md

@@ -24,7 +24,9 @@ this skill alters re-gates.
 Preferred: `linearis` on PATH and authenticated (`linearis auth status`). Token
 resolution order: `--api-token`, `LINEAR_API_TOKEN`, `~/.linearis/token`. This is a
 preference, not a precondition - a missing or unauthenticated CLI degrades Linear
-functionality and is reported, never blocks the run.
+functionality and is reported, never blocks the run. The token file is encrypted
+storage: never use its contents as an HTTP credential or infer the credential type
+from its `v1:` storage-format prefix. Resolve it through linearis instead.
 
 > **No `linearis` installed?** If `command -v linearis` fails, fall back to a
 > **Linear MCP server** when the harness has one configured - its tools cover the
@@ -192,7 +194,7 @@ Safety rules, in addition to the write gate above:
 | Symptom | Cause | Fix |
 |---|---|---|
 | 401 | Not authenticated / expired token | `linearis auth status`; re-auth - unless the download row below applies. |
-| 401 on `files download` while `issues read` works | linearis 2026.7.0 and 2026.8.0 prepend `Bearer ` to personal API keys on file downloads ([linearis-oss/linearis#300](https://github.com/linearis-oss/linearis/issues/300)) | Not an auth problem - do not re-auth. Fetch the URL with the bare key, or use a version without the bug once one ships. |
+| 401 on `files download` while `issues read` works | linearis 2026.7.0 and 2026.8.0 prepend `Bearer ` to personal API keys on file downloads ([linearis-oss/linearis#300](https://github.com/linearis-oss/linearis/issues/300)) | Not an auth problem - do not re-auth. Use the recovery below, or use a version without the bug once one ships. |
 | Issue not found | Wrong workspace, or issue archived | Confirm workspace; check archived state. |
 | Status not found | Status name doesn't match the team's workflow states | List the team's states before setting one. |
 | Missing `--team` error on create | `--team` is required | Supply `--team <default team>`. |
@@ -203,6 +205,45 @@ Safety rules, in addition to the write gate above:
 | Read is slow | Big ticket with many comments/attachments | Drop `--with-*` flags not needed. |
 | Parser-shape failure on a documented invocation: unknown command/option, unexpected argument | Section 3's snapshot may have drifted from the installed CLI | Re-read that subcommand's `--help`; report the row stale **only if** help actually contradicts it, then follow help |
 
+For that download-only 401, this 2026.7.0/2026.8.0 workaround calls linearis's
+version-specific internal `getApiToken` API. Supply the fresh `uploads.linear.app` URL
+from `issues read --with-attachments` and an output path. It rejects other hosts and
+redirects, sends the resolved key without `Bearer`, writes only a non-empty response,
+and never prints or stores the key separately:
+
+<!-- linear-download-recovery:start -->
+```bash
+download_linear_asset() {
+  LINEARIS_BIN="${LINEARIS_BIN:-$(command -v linearis)}" node --input-type=module - "$1" "$2" <<'NODE'
+import { realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [urlText, output] = process.argv.slice(2);
+const url = new URL(urlText);
+if (url.protocol !== "https:" || url.hostname !== "uploads.linear.app")
+  throw new Error("refusing to send a credential outside https://uploads.linear.app");
+const packageRoot = dirname(dirname(realpathSync(process.env.LINEARIS_BIN)));
+const { getApiToken } = await import(pathToFileURL(join(packageRoot, "dist/common/auth.js")));
+const response = await fetch(url, {
+  headers: { Authorization: getApiToken({}) },
+  redirect: "error",
+});
+if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+const bytes = new Uint8Array(await response.arrayBuffer());
+if (bytes.byteLength === 0) throw new Error("download failed: empty response");
+writeFileSync(output, bytes);
+console.log(`downloaded ${bytes.byteLength} bytes to ${output}`);
+NODE
+}
+download_linear_asset 'https://uploads.linear.app/...' '/tmp/attachment'
+```
+<!-- linear-download-recovery:end -->
+
+Do not declare the attachment inaccessible until this recovery used the resolved
+credential; reading `~/.linearis/token` directly does not count. Afterward, confirm the
+reported byte count and inspect the file type before consuming or extracting it.
+
 The last row's trigger is deliberately narrow. Data, auth, status-name, and root-thread
 validation errors have their own rows above and are **not** drift - routing them to "the
 skill is stale" would misdiagnose ordinary failures. This row is the reactive path for

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

@@ -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.
 
@@ -143,7 +145,7 @@ subagent({ agent: "implementer", async: false, task: "<task text + context + SCO
 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?>" })
@@ -177,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.
@@ -243,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/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/writing-plans/SKILL.md

@@ -126,14 +126,13 @@ If you can't list the files, the spec isn't ready: amend or redraw per brainstor
 
 Group tasks into **waves** so the executor can parallelize independent work (see `subagent-driven-development` Parallel-Wave Mode). A wave is a maximal set of tasks that (a) have no ordering dependency on each other, (b) own **pairwise-disjoint files**, and (c) 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.
 - Group independent tasks into the same wave by default. A wave with one task is legal **only with a named-blocker justification**: a body line directly under the `## Wave N — <label>` header, `Solo: <reason>`, where the reason names the blocking task/wave, the contended runtime resource, or `lone remaining task` (reserved for the genuinely final unmatched task; doc-only trailing waves qualify). Category-only justifications ("dependency" with no named task) do not satisfy the rule.
 - A pure dependency chain yields one task per wave — no parallelism, which is correct; each such wave carries its `Solo:` line naming the prior-wave dependency.
 - Each wave after the first states its dependency on prior waves.
 
-**File-ownership contract.** The per-task `**Files:**` block *is* the ownership declaration — no new syntax. Rule: **within a wave, the union of every task's declared paths must be pairwise disjoint.** Globs are allowed for `Modify` when exact paths are unknown, but must not overlap another same-wave task's paths. A task that must touch another's file belongs in a later wave.
+**File-ownership contract.** See [reference/plan-contract.md § Files](reference/plan-contract.md).
 
-**Test-command contract.** Every code-touching wave declares at least one scoped test command across its tasks' steps. A wave with zero test commands is legal only when every task's `Files:` block is documentation-only (the trailing doc-only wave below).
+**Test contract.** Every task that creates or modifies code declares a `Test:` path and an executable `**Tests:**` command anchored to it (grammar: [reference/plan-contract.md § Tests](reference/plan-contract.md)); `- none: <category>` only when no tests apply. Anchoring is presence, not coverage. When the anchored spec names the thing under test, the task carries `- via:` naming it; a fixture path the spec names goes under `Create:`.
 
 **Runtime-resource disjointness.** File-disjoint is necessary but not sufficient: two tasks with disjoint files that both mutate the same DB, bind the same port, or share a fixture are **not** parallel-safe and must land in different waves. The executor auto-selects parallel for *every* multi-task wave, so this grouping is the sole parallel-safety guarantee — there is no selection-time judgment downstream. No new mandatory per-task syntax; when a shared runtime resource is the reason two file-disjoint tasks sit in different waves, record it in an inline note on the later wave.
 
@@ -192,7 +191,7 @@ Each step is **one action, 2-5 minutes**:
 ---
 ```
 
-The `**Verification:**` line is the **only** place the full verification entrypoint may appear — never in any task or wave step. The verify phase reads it from the plan instead of re-deriving it; execution runs scoped commands only.
+The full verification entrypoint appears only on the `**Verification:**` line — see [reference/plan-contract.md § Header-only entrypoint](reference/plan-contract.md). The verify phase reads it from the plan; execution runs `Tests:` commands only.
 
 ## Task Structure
 
@@ -210,6 +209,10 @@ Each task uses `- [ ]` checkbox steps so execution tools (and humans) can track
 - Modify: `exact/path/to/existing.py:123-145`
 - Test: `tests/exact/path/to/test.py`
 
+**Tests:**
+- `uv run pytest tests/exact/path/to/test.py`
+- via: `function()`
+
 - [ ] **Step 1: Write the failing test**
 
   ```python
@@ -250,28 +253,14 @@ Each task uses `- [ ]` checkbox steps so execution tools (and humans) can track
 
 Every code task carries this step (red -> green -> fmt/lint -> commit). Doc-only tasks omit it unless the project formats Markdown.
 
-**Anchor rules.** The task's `**Spec:**` line cites the plan header's spec path; multiple anchors sit comma-separated on one line (`§ "A" L10-L18, § "C" L40-L44`). Checks key on the `§` marker, so the header's path-only `**Spec:**` line is never matched. Anchors are captured against the gated spec at plan-writing time; a change to the approved spec follows brainstorming's [Amending an approved spec](../brainstorming/SKILL.md#amending-an-approved-spec), executed in place. A task with no anchorable requirement (pure-mechanics chore) omits the `**Spec:**` line entirely (never `**Spec:** none`) and carries a mechanical-task row in `## Spec coverage` — silence is never valid.
+**Anchor rules.** See [reference/plan-contract.md § Spec anchors](reference/plan-contract.md). A task with no anchorable requirement omits the `**Spec:**` line and carries a mechanical-task row in `## Spec coverage` — silence is never valid.
 
 ## Spec Coverage Table
 
-Every plan ends with a `## Spec coverage` section — authored last, placed after all Task sections (owner IDs do not exist earlier). Build it extraction-first: walk the spec top to bottom and write one row per normative requirement **before** assigning owners — every Design imperative (Add/Remove/Keep/Replace-style directives, not any fixed lexical form), every Edge-cases rule, every Acceptance criterion, every Out-of-scope entry, and every non-none Documentation-impact entry. Then assign owners, then re-walk the spec once: every normative clause has a row. Two row kinds:
-
-```markdown
-## Spec coverage
-
-| anchor | requirement (short) | owner |
-|---|---|---|
-| § "Design" L34-L37 | anchor line in task template | Task 2 |
-| § "Edge cases" L120 | stale anchor = blocking SR finding | Task 4, Task 5 |
-| § "Testing" L84 | checker fixtures: `node --test extensions/lib/plan-check.test.ts` | Task 3 |
-| § "Acceptance" L88 | full suite passes: `npm test` | Verification |
-| § "Out of scope" L131 | fix-round anchoring | waived: out of scope per spec |
-| - | mechanical: release commit | Task 7 |
-```
+Every plan ends with a `## Spec coverage` section (grammar and example: [reference/plan-contract.md § Spec coverage table](reference/plan-contract.md)). Build it extraction-first: walk the spec top to bottom and write one row per normative requirement **before** assigning owners — every Design imperative (Add/Remove/Keep/Replace-style directives, not any fixed lexical form), every Edge-cases rule, every Acceptance criterion, every Out-of-scope entry, and every non-none Documentation-impact entry. Then assign owners, then re-walk the spec once: every normative clause has a row. Two row kinds:
 
-- **Requirement rows:** anchor + short requirement + owner = task-ID list, or `Verification`, or `waived: <reason>`. A cross-cutting requirement (decided in more than one task) lists **every** deciding task as owner, not the first. `waived: <reason>` is only for requirements the spec marks out of scope **and** that exclude work from the change. A requirement whose text carries an inline code span (`` `literal` ``) names concrete behaviour and is never waivable - it maps to a task or `Verification`. A waiver on an in-scope normative requirement is a Self-Review failure — there is no human plan-review gate to catch it downstream.
-- **`Verification` owner:** use for a requirement the header `**Verification:**` command proves. Write the exact string `Verification`, alone. Quote only literals contained in that header. Anchor the single requirement line. Keep scoped commands task-owned.
-- **Mechanical-task rows:** anchor `-`, requirement `mechanical: <short>`, owner = the task ID. One such row per anchor-less task.
+- **Requirement rows:** a cross-cutting requirement (decided in more than one task) lists **every** deciding task as owner, not the first. `waived: <reason>` is only for requirements the spec marks out of scope **and** that exclude work from the change. A requirement whose text carries an inline code span (`` `literal` ``) names concrete behaviour and is never waivable - it maps to a task or `Verification`. A waiver on an in-scope normative requirement is a Self-Review failure — there is no human plan-review gate to catch it downstream.
+- **`Verification` owner:** only for a requirement the header command proves; grammar in the reference.
 - The table is plan-authoring-time only — never passed to implementer or reviewer dispatches.
 
 ## No Placeholders
@@ -282,11 +271,10 @@ Every plan failure mode:
 - ❌ `# Implement the rest of the function` — incomplete code is invalid code.
 - ❌ "Add tests for edge cases" — name the edge cases.
 - ❌ "Wire it up to the existing system" — give file paths and call sites.
-- ❌ "timeout/gtimeout ladder" when the spec fixes the literal `timeout 30` — never paraphrase an exact-string requirement (setting keys, error messages, banner/format strings, command names and invocations, API shapes); transcribe it as a backtick-quoted spec literal: `timeout 30`. Spec-side backtick spans containing `<placeholder>` segments are templates the plan instantiates, not exact-string requirements — exempt from quote integrity.
 - ❌ "Similar to Task N" — repeat the code. Implementers (and subagents with fresh context) may read tasks out of order; pointing at a sibling task is not a substitute for showing the code.
 - ❌ References to types, functions, methods, or fields not defined in any task in this plan. If it shows up in Task 5, it must be introduced by Task 1–4 or already exist in the codebase (with a file:line citation).
-- ❌ `[fill in]`, `<example>`, `xxx` markers anywhere in the doc.
 - ❌ "Probably also need to update the docs" — either yes (which doc) or no. Docs are named plan tasks, sourced from the spec's Documentation impact section (materiality bar in `brainstorming/reference/documentation-impact.md`).
+- Quote integrity and the banned-token list: [reference/plan-contract.md § Placeholders and quote integrity](reference/plan-contract.md).
 
 If a decision is genuinely open, put it in an explicit **Open Questions** section at the top and resolve before execution starts.
 
@@ -294,10 +282,10 @@ If a decision is genuinely open, put it in an explicit **Open Questions** sectio
 
 After drafting the plan and before announcing it complete, run the deterministic checker, then the judgment checks yourself — not a subagent dispatch.
 
-- **Deterministic checker.** Run `plan_check({ planPath })` on the saved plan. Assess and fix every finding yourself (no human involvement), then re-run until it passes — a pass writes the execution stamp that implement-start verifies mechanically. If the same finding survives 3 fix rounds, convert it to an explicit Open Question and stop (the pre-existing Open-Questions halt, resolved by the human in-session — not a new gate). The checker covers table closure, quote integrity, anchor resolution, path existence, placeholder scan, wave file-disjointness, solo-line presence, header-only entrypoint, and waiver-literal.
+- **Deterministic checker.** Run `plan_check({ planPath })` on the saved plan. Assess and fix every finding yourself (no human involvement), then re-run until it passes — a pass writes the execution stamp that implement-start verifies mechanically. If the same finding survives 3 fix rounds, convert it to an explicit Open Question and stop (the pre-existing Open-Questions halt, resolved by the human in-session — not a new gate). Findings are defined in [reference/plan-contract.md](reference/plan-contract.md).
 - **Code-vs-anchor sanity.** For each task-owned requirement row, re-read the anchored spec lines and confirm the owner tasks' bodies do what they say - mechanism present, not just the quoted literal. For each `Verification` row, confirm the header command exercises the anchored requirement. Fix the task, don't annotate.
 - **Type / API consistency.** Function signatures and field names that appear in multiple tasks must match exactly. The plan is its own contract — internal contradictions surface as bugs during execution.
-- **Scoped-test coverage.** Every code-touching wave declares at least one scoped test command; only doc-only waves may have none.
+- **Test contract.** Every code task's `Tests:` commands are anchored to its `Test:` path(s); `none:` only where no tests apply; a spec-named seam appears as `via:`, a spec-named fixture path as `Create:`.
 - **Runtime-resource disjointness.** For every multi-task wave, confirm no two tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path) — `Files:` overlap is checked mechanically, resource contention is not. Contention = mis-grouped wave; split or re-order before handoff.
 - **Solo-reason validity.** Every single-task wave's `Solo:` line (presence is checked mechanically) must name its specific blocker — the blocking task/wave, the contended resource, or `lone remaining task`. Category-only justifications are under-justified; merge or justify before handoff.
 - **Waiver authorization.** `waived: <reason>` is only for requirements the spec marks out of scope **and** that exclude work from the change. A requirement whose text carries an inline code span (`` `literal` ``) names concrete behaviour and is never waivable - it maps to a task or `Verification`. A waiver on an in-scope normative requirement is a Self-Review failure — there is no human plan-review gate to catch it downstream.

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

@@ -0,0 +1,70 @@
+# Plan contract
+
+The grammar `plan_check` enforces. Each section names its check(s). Findings resolve in `writing-plans` Self-Review: fix, re-run.
+
+## Waves and tasks
+
+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.
+
+## Files (`wave-file-disjointness`, `paths-exist`)
+
+**File-ownership contract.** The per-task `**Files:**` block *is* the ownership declaration — no new syntax. Rule: **within a wave, the union of every task's declared paths must be pairwise disjoint.** Globs are allowed for `Modify` when exact paths are unknown, but must not overlap another same-wave task's paths. A task that must touch another's file belongs in a later wave.
+
+`Test:` entries are run anchors, not ownership: `Test`/`Test` on the same path across same-wave tasks is allowed; `Test` vs another task's `Create`/`Modify` is a conflict; writer/writer stays a conflict. `Modify:` paths must exist.
+
+## Spec anchors (`anchor-resolution`)
+
+**Anchor rules.** The task's `**Spec:**` line cites the plan header's spec path; multiple anchors sit comma-separated on one line (`§ "A" L10-L18, § "C" L40-L44`). Checks key on the `§` marker, so the header's path-only `**Spec:**` line is never matched. Anchors are captured against the gated spec at plan-writing time; a change to the approved spec follows brainstorming's [Amending an approved spec](../../brainstorming/SKILL.md#amending-an-approved-spec), executed in place. A task with no anchorable requirement (pure-mechanics chore) omits the `**Spec:**` line entirely (never `**Spec:** none`) and carries a mechanical-task row in `## Spec coverage` — silence is never valid.
+
+## Tests (`tests-block`)
+
+Every `### Task N` carries a `**Tests:**` block: the bare line `**Tests:**` directly after the last `Files:` entry (blank lines allowed). Bullets, in either form:
+
+- `- ` + backtick + command + backtick - one scoped test command; `- via: <entry point>` - the seam the tests call directly (function, route, CLI, module - e.g. `each_finding`), zero or more
+- `- none: <category>` - the task runs no tests; `<category>` is free text derived from the project (docs, config, fixtures, generated assets, ...); exactly one, and no `- Test:` path in `Files:`
+
+Absence is never valid. A `- [ ]` step or any non-bullet line ends the block. `via:` and `none:` are unchecked beyond form.
+
+Commands run from the repo root. Each command is split into segments on `&&`, `||`, `;`, `|`; every segment must contain, as a whitespace-delimited token, a `Test:` path of the same task (the path alone, or followed by `::`, `#`, or `:` and a filter). A `Test:` value containing `*`, `?`, `[` or ending in `/` never anchors; any other argument token with those shapes is a broadening selector and fails. `cd `, `sh -c`, `bash -c`, `eval `, `$(` are unsupported. Each `Test:` path must exist or be a `Create:` path of some task. A segment equal to a header `**Verification:**` segment is a full-suite command and fails. Runners with no file-addressable form are out of scope (`go test ./pkg -run X`, `mvn -Dtest=`).
+
+## Solo line (`solo-line`)
+
+A wave with one task carries, directly under its `## Wave N — <label>` header, the line `Solo: <reason>`. The reason names the blocking task/wave, the contended runtime resource, or `lone remaining task`. Presence is checked here; validity is `writing-plans` Self-Review.
+
+## Header-only entrypoint (`header-entrypoint`)
+
+The `**Verification:**` line is the **only** place the full verification entrypoint may appear — never in any task or wave step. The verify phase reads it from the plan instead of re-deriving it; execution runs scoped commands only.
+
+The header value's backtick spans (else the raw value) are split on `&&`, `||`, `;`, `,` into segments. No `Run:` step payload segment and no `Tests:` bullet segment may equal a header segment; prose inside waves may not contain the whole header value.
+
+## Spec coverage table (`table-closure`, `waiver-literal`)
+
+Every plan ends with a `## Spec coverage` section — authored last, placed after all Task sections (owner IDs do not exist earlier). Closure both ways: every `### Task N` appears as an owner in some row; every row's owner task exists.
+
+```markdown
+## Spec coverage
+
+| anchor | requirement (short) | owner |
+|---|---|---|
+| § "Design" L34-L37 | anchor line in task template | Task 2 |
+| § "Edge cases" L120 | stale anchor = blocking SR finding | Task 4, Task 5 |
+| § "Testing" L84 | checker fixtures: `node --test extensions/lib/plan-check.test.ts` | Task 3 |
+| § "Acceptance" L88 | full suite passes: `npm test` | Verification |
+| § "Out of scope" L131 | fix-round anchoring | waived: out of scope per spec |
+| - | mechanical: release commit | Task 7 |
+```
+
+**Requirement rows:** anchor + short requirement + owner = task-ID list, or `Verification`, or `waived: <reason>`. A `waived:` row whose requirement cell contains an inline code span fails `waiver-literal`.
+
+**`Verification` owner:** use for a requirement the header `**Verification:**` command proves. Write the exact string `Verification`, alone. Quote only literals contained in that header. Anchor the single requirement line. Keep scoped commands task-owned.
+
+**Mechanical-task rows:** anchor `-`, requirement `mechanical: <short>`, owner = the task ID. One such row per anchor-less task.
+
+## Placeholders and quote integrity (`placeholder-scan`, `quote-integrity`)
+
+- ❌ "timeout/gtimeout ladder" when the spec fixes the literal `timeout 30` — never paraphrase an exact-string requirement (setting keys, error messages, banner/format strings, command names and invocations, API shapes); transcribe it as a backtick-quoted spec literal: `timeout 30`. Spec-side backtick spans containing `<placeholder>` segments are templates the plan instantiates, not exact-string requirements — exempt from quote integrity.
+- ❌ `[fill in]`, `<example>`, `xxx` markers anywhere in the doc.
+
+The banned token list is `BANNED_TOKENS` in `extensions/lib/plan-check.ts`; a token inside a literal the anchored spec requires is exempt.