pi-gauntlet 5.0.8 → 5.2.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v5.2.0 - 2026-08-31
+
+- **`plan_check` deterministic plan checker (new tool).** `phase-tracker` now registers `plan_check({ planPath })`, running 8 mechanical plan-vs-spec checks (table closure, quote integrity, anchor resolution, path existence, placeholder scan, wave file-disjointness, solo-line presence, header-only entrypoint) from a pi-free library at `extensions/lib/plan-check.ts`. Fail-closed: it never throws, and findings are returned for the main model to fix autonomously.
+- **Implement-start gate (enforcing by default).** Inside a gauntlet flow, `phase_tracker({ action: "start", phase: "implement" })` is rejected unless a passing `plan_check` stamp exists and both the plan and spec files still match their stamped content hashes. Sixth flow guard, block-only, no new settings key - disable with `piGauntlet.flowGuards.enforce: false`. Outside a flow, `plan_check` acts as a plain linter.
+- **`writing-plans` Self-Review** is now one deterministic-checker bullet plus seven judgment bullets; the mechanical checks are no longer LLM-attested.
+- **`Parallel-safe:` structural probe.** The three consumer skills (`dispatching-parallel-agents`, `requesting-code-review`, `subagent-driven-development`) replace silent degradation with an explicit probe -> one reviewer re-ask -> explicit sequential fallback, with the `<group>` production now defined at the canonical consumer. Prose-only; the five pinned producer grammar copies are untouched. Fixes #19. Spec: `doc/specs/2026-08-31-gh-19-deterministic-plan-checker.md`.
+
+## v5.1.0 - 2026-08-31
+
+- New skill `linear`: package-owned home for all linearis mechanics (verb reference, six gotchas, multi-line body pattern, ID-cache convention, failure modes, MCP fallback) and the five-key overrides `## Issue tracker` schema, including the explicit `tracker:` off-switch (`linear` / `github` / `none` - exclusive selection, zero probing when non-Linear). shape-ticket, check-delivery, and chase-bug slim to detection + a `/skill:linear` routing line (chase-bug's fabricated `linearis comment` example fixed); brainstorming's gatherer fetch-path definition honors the off-switch; `./skills/linear` joins the Claude Code marketplace allowlist (five exposed skills). Fixes #17. Spec: `doc/specs/2026-08-31-gh-17-linear-skill.md`.
+
 ## v5.0.8 - 2026-08-31
 
 - shape-ticket: ticket bodies must be self-contained - new wording contract in `skills/shape-ticket/reference/ticket-wording.md` (repo-stranger reader, strip-test, plain-words lead + example per asserted failure, jargon defined, references demoted to deletable parenthetical pointers, big chunks linkable with a summary line - no spiderman tickets). Wired into the draft step, every roast brief (members, worker fallback, runtime conditional; fidelity exempts contract-driven unpacking from `added`), and the repair-mode no-op check (a violating body is non-conforming and gets a proposed rewrite). Generic repo density norms can no longer override ticket prose; only an explicit ticket-wording overrides section can. Fixes #18. Spec: `doc/specs/2026-08-31-gh-18-self-contained-ticket-wording.md`.

package/README.md

@@ -69,9 +69,9 @@ Everything between gate 1 and gate 2 - task breakdown, implementation, both revi
 
 pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-- **16 skills** - the workflow logic. Twelve 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`. 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/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 - run it with `/skill:chase-bug`.
+- **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/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 - 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. 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. phase-tracker also registers plan_check, a deterministic plan linter (8 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.
 
 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.
 
@@ -126,9 +126,9 @@ cd ~/repos/pi-gauntlet && npm run link-agents   # local-path installs skip npm i
 
 ## Use from Claude Code
 
-Four skills are exposed to Claude Code via the plugin marketplace at
+Five skills are exposed to Claude Code via the plugin marketplace at
 `.claude-plugin/marketplace.json`: **shape-ticket**, **gatekeep-pr**,
-**check-delivery**, and **chase-bug**. They are harness-portable by design - every pi-specific
+**check-delivery**, **chase-bug**, and **linear**. They are harness-portable by design - every pi-specific
 mechanic they touch (`plan_tracker`, `gauntlet_setting`, `subagent()`) carries
 an inline fallback, so they run on Claude Code's native facilities. This is the
 supported set. Not exposed, in two classes: (a) genuinely pi-bound surface -
@@ -202,8 +202,9 @@ exact repo folder* in interactive Claude Code. Trusting a parent folder,
 4. Run `/plugin` and confirm: marketplace `pi-gauntlet` is listed, plugin
    `gauntlet` is enabled. If it shows as known but not installed, run
    `/plugin install gauntlet@pi-gauntlet` and re-check.
-5. Confirm exactly four skills are registered under the plugin (via the
-   `/plugin` details view): shape-ticket, gatekeep-pr, check-delivery, chase-bug.
+5. Confirm exactly five skills are registered under the plugin (via the
+   `/plugin` details view): shape-ticket, gatekeep-pr, check-delivery, chase-bug,
+   linear.
 6. Invoke `/gauntlet:shape-ticket` with a deliberately two-concern ask (e.g.
    "shape a ticket: CSV import for operators, plus a partner-facing status
    API") so the skill deterministically consults its
@@ -261,6 +262,20 @@ Use the `jira` CLI (authenticated via `jira login`), not `gh` or `linearis`.
 - post comment (Reporter note only): `jira issue comment ABC-123 --body "<text>"`
 ```
 
+**`linear` setup:** mandatory - `linearis` installed and authenticated (or a Linear
+MCP server as a fallback when `linearis` is unavailable). Optional - the five
+`## Issue tracker` override keys (`tracker`, `workspace urlKey`, `default team`,
+`self`, `id cache`); the full schema is documented once, in
+[skills/linear/SKILL.md](./skills/linear/SKILL.md) - not restated here. Off switch:
+set `tracker: github` or `tracker: none` in `## Issue tracker` to disable Linear
+entirely - no `linearis` probing, no prompts.
+
+**Coexistence:** the five `## Issue tracker` keys compose with the free-form
+command-mapping convention above, they don't replace it. `tracker:` adds exclusive
+tracker selection; free-form verb mappings keep working both without a `tracker:`
+key (ladder rung 1, as today) and as the mechanics source when `tracker:` names an
+unknown value.
+
 **`## Deployment` section:** `shape-ticket` (split rule), `writing-plans` (scope check), and `brainstorming` (scope check) read deploy topology from this section: what ships together, what ships independently, and the mechanism. It is a fact to look up, never to infer - when the section is absent, or when it documents a monolithic topology (like the example below), the "separable release timing" split axis is unavailable and splits fail closed to one artifact.
 
 ```markdown

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

@@ -0,0 +1,485 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { checkPlan, sha256, type FsPort, type PlanCheckFinding } from "./plan-check.ts";
+
+const SPEC_TEXT = [
+  "# Fixture Spec", // 1
+  "", // 2
+  "## Design", // 3
+  "Line A.", // 4
+  "This part defines `helperFn()` config.", // 5
+  "Another line here.", // 6
+  "", // 7
+  "## Testing", // 8
+  "This mentions `TODO` as a banned token example for exemption checking.", // 9
+  "More text.", // 10
+  "", // 11
+  "## Other", // 12
+  "Stuff.", // 13
+].join("\n");
+
+const VALID_PLAN = `# Fixture Plan
+
+**Spec:** \`doc/specs/fixture-spec.md\`
+
+**Verification:** npm run fixture-verify
+
+---
+
+## Wave 1 — Two parallel tasks
+
+### Task 1: Implement helper
+
+**Spec:** doc/specs/fixture-spec.md § "Design" L4-L6
+
+**Files:**
+- Create: extensions/lib/fixture-task1.ts
+- Modify: extensions/lib/fixture-shared.ts
+
+This task implements helperFn() for parsing.
+
+### Task 2: Implement naming
+
+**Spec:** doc/specs/fixture-spec.md § "Design" L4-L4
+
+**Files:**
+- Create: extensions/lib/fixture-task2.ts
+- Modify: extensions/lib/fixture-other.ts
+
+This task handles naming details.
+
+## Wave 2 — Solo task
+
+Solo: lone remaining task
+
+### Task 3: Document banned token handling
+
+**Spec:** doc/specs/fixture-spec.md § "Testing" L9
+
+**Files:**
+- Modify: extensions/lib/fixture-task3.ts
+
+The literal TODO is intentionally documented here per spec quote-integrity requirement.
+
+## Spec coverage
+
+| anchor | requirement | owner |
+|---|---|---|
+| § "Design" L4-L6 | parser grammar basics | Task 1 |
+| § "Design" L4-L4 | helper naming | Task 2 |
+| § "Testing" L9-L9 | banned token literal handling | Task 3 |
+| - | mechanical: wire test into CI | Task 2 |
+| § "Other" L12-L13 | out of scope thing | waived: out of scope per spec |
+`;
+
+function alwaysTruePort(): FsPort {
+  return {
+    exists: () => true,
+    glob: () => [],
+  };
+}
+
+function lineOf(text: string, needle: string): number {
+  const idx = text.split("\n").findIndex((l) => l.includes(needle));
+  assert.notEqual(idx, -1, `expected to find a line containing ${JSON.stringify(needle)}`);
+  return idx + 1;
+}
+
+function findingsFor(findings: PlanCheckFinding[], check: string): PlanCheckFinding[] {
+  return findings.filter((f) => f.check === check);
+}
+
+test("valid fixture: checkPlan returns no findings (also covers the placeholder exemption case)", () => {
+  const findings = checkPlan(VALID_PLAN, SPEC_TEXT, alwaysTruePort());
+  assert.deepEqual(findings, []);
+});
+
+test("no gauntlet grammar at all: emits both an absent-wave-headers and an absent-task-headers finding", () => {
+  const plan = "# Just a plan\n\nSome prose with no wave or task headers at all.\n";
+  const findings = checkPlan(plan, SPEC_TEXT, alwaysTruePort());
+  const waveFindings = findings.filter((f) => f.reason.includes("wave headers"));
+  const taskFindings = findings.filter((f) => f.reason.includes("task headers"));
+  assert.equal(waveFindings.length, 1, "expected exactly one absent-wave-headers finding");
+  assert.equal(taskFindings.length, 1, "expected exactly one absent-task-headers finding");
+});
+
+test("check 1 table-closure: task not covered by any Spec coverage row", () => {
+  const mutated = VALID_PLAN.replace('| § "Testing" L9-L9 | banned token literal handling | Task 3 |\n', "");
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const tc = findingsFor(findings, "table-closure");
+  assert.ok(
+    tc.some((f) => f.reason.includes("Task 3") && f.reason.includes("does not appear as an owner")),
+    `expected a table-closure finding about Task 3 not covered, got: ${JSON.stringify(tc)}`,
+  );
+  assert.ok(
+    tc.some(
+      (f) =>
+        f.reason.includes("Task 3") &&
+        f.line === lineOf(mutated, "### Task 3: Document banned token handling"),
+    ),
+    `expected the table-closure finding's line to point at Task 3's header, got: ${JSON.stringify(tc)}`,
+  );
+});
+
+test("check 1 fail-closed: missing '## Spec coverage' table entirely", () => {
+  const mutated = VALID_PLAN.slice(0, VALID_PLAN.indexOf("## Spec coverage"));
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const tc = findingsFor(findings, "table-closure");
+  assert.equal(tc.length, 1);
+  assert.match(tc[0].reason, /no '## Spec coverage' table found/);
+  assert.equal(tc[0].line, 0);
+});
+
+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.",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const qi = findingsFor(findings, "quote-integrity");
+  assert.ok(
+    qi.some((f) => f.reason.includes("helperFn()") && f.reason.includes("Task 1")),
+    `expected a quote-integrity finding naming the missing literal, got: ${JSON.stringify(qi)}`,
+  );
+  assert.ok(
+    qi.some((f) => f.line === lineOf(mutated, "parser grammar basics")),
+    `expected the quote-integrity finding's line to point at the offending Spec coverage row, got: ${JSON.stringify(qi)}`,
+  );
+});
+
+test("check 1 owner-cell grammar: trailing junk after a Task <n> list is malformed, not accepted", () => {
+  const mutated = VALID_PLAN.replace(
+    '| § "Design" L4-L6 | parser grammar basics | Task 1 |',
+    '| § "Design" L4-L6 | parser grammar basics | Task 1 (see note) |',
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const tc = findingsFor(findings, "table-closure");
+  assert.ok(
+    tc.some(
+      (f) =>
+        f.reason.includes("owner cell is not a 'Task <n>' list or 'waived: <reason>'") &&
+        f.text.includes("Task 1 (see note)"),
+    ),
+    `expected an owner-cell malformed finding, got: ${JSON.stringify(tc)}`,
+  );
+  assert.ok(
+    tc.some(
+      (f) =>
+        f.reason.includes("owner cell is not a 'Task <n>' list or 'waived: <reason>'") &&
+        f.line === lineOf(mutated, '| § "Design" L4-L6 | parser grammar basics | Task 1 (see note) |'),
+    ),
+    `expected the owner-cell malformed finding's line to point at the offending row, got: ${JSON.stringify(tc)}`,
+  );
+});
+
+test("check 1 owner-cell grammar: empty waiver reason is malformed, not accepted as a waiver", () => {
+  const mutated = VALID_PLAN.replace(
+    '| § "Other" L12-L13 | out of scope thing | waived: out of scope per spec |',
+    '| § "Other" L12-L13 | out of scope thing | waived: |',
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const tc = findingsFor(findings, "table-closure");
+  assert.ok(
+    tc.some((f) => f.reason.includes("owner cell is not a 'Task <n>' list or 'waived: <reason>'")),
+    `expected an owner-cell malformed finding for empty waiver reason, got: ${JSON.stringify(tc)}`,
+  );
+  assert.ok(
+    tc.some(
+      (f) =>
+        f.reason.includes("owner cell is not a 'Task <n>' list or 'waived: <reason>'") &&
+        f.line === lineOf(mutated, '| § "Other" L12-L13 | out of scope thing | waived: |'),
+    ),
+    `expected the owner-cell malformed finding's line to point at the offending row, got: ${JSON.stringify(tc)}`,
+  );
+});
+
+test("check 3 anchor-resolution: ambiguous heading match (duplicate spec heading)", () => {
+  const dupSpec = SPEC_TEXT.replace('## Testing', '## Design\n\nduplicate section body.\n\n## Testing');
+  const findings = checkPlan(VALID_PLAN, dupSpec, alwaysTruePort());
+  const ar = findingsFor(findings, "anchor-resolution");
+  assert.ok(
+    ar.some((f) => f.reason.includes("ambiguous") && f.reason.includes('"Design"')),
+    `expected an ambiguous-heading finding, got: ${JSON.stringify(ar)}`,
+  );
+  assert.ok(
+    ar.some(
+      (f) =>
+        f.reason.includes("ambiguous") &&
+        f.line === lineOf(VALID_PLAN, '**Spec:** doc/specs/fixture-spec.md § "Design" L4-L6'),
+    ),
+    `expected an ambiguous-heading finding whose line points at Task 1's **Spec:** anchor line, got: ${JSON.stringify(ar)}`,
+  );
+});
+
+test("check 3 fail-closed: unparseable **Spec:** anchor line", () => {
+  const mutated = VALID_PLAN.replace(
+    '**Spec:** doc/specs/fixture-spec.md § "Design" L4-L6',
+    "**Spec:** doc/specs/fixture-spec.md § Design without quotes or line numbers",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const ar = findingsFor(findings, "anchor-resolution");
+  assert.equal(ar.length, 1);
+  assert.match(ar[0].reason, /unparseable/);
+  assert.equal(ar[0].line, lineOf(mutated, "**Spec:** doc/specs/fixture-spec.md § Design without quotes"));
+});
+
+test("check 4 paths-exist: Modify: literal path does not exist", () => {
+  const port: FsPort = {
+    exists: (p) => p !== "extensions/lib/fixture-shared.ts",
+    glob: () => [],
+  };
+  const findings = checkPlan(VALID_PLAN, SPEC_TEXT, port);
+  const pe = findingsFor(findings, "paths-exist");
+  assert.ok(
+    pe.some((f) => f.reason.includes("fixture-shared.ts") && f.reason.includes("does not exist")),
+    `expected a paths-exist finding, got: ${JSON.stringify(pe)}`,
+  );
+  assert.ok(
+    pe.some((f) => f.line === lineOf(VALID_PLAN, "- Modify: extensions/lib/fixture-shared.ts")),
+    `expected the paths-exist finding's line to point at the offending Modify: entry, got: ${JSON.stringify(pe)}`,
+  );
+});
+
+test("check 4 paths-exist: backtick-wrapped Modify: path is stripped before the existence check", () => {
+  const mutated = VALID_PLAN.replace(
+    "- Modify: extensions/lib/fixture-shared.ts",
+    "- Modify: `extensions/lib/fixture-shared.ts`",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  assert.deepEqual(findingsFor(findings, "paths-exist"), []);
+});
+
+test("check 4 fail-closed: invalid glob (port throws)", () => {
+  const mutated = VALID_PLAN.replace(
+    "- Modify: extensions/lib/fixture-shared.ts",
+    "- Modify: extensions/lib/fixture-*.ts",
+  );
+  const port: FsPort = {
+    exists: () => true,
+    glob: () => {
+      throw new Error("bad pattern");
+    },
+  };
+  const findings = checkPlan(mutated, SPEC_TEXT, port);
+  const pe = findingsFor(findings, "paths-exist");
+  assert.ok(
+    pe.some((f) => f.reason.includes("invalid") && f.reason.includes("bad pattern")),
+    `expected an invalid-glob finding, got: ${JSON.stringify(pe)}`,
+  );
+  assert.ok(
+    pe.some(
+      (f) =>
+        f.reason.includes("invalid") &&
+        f.line === lineOf(mutated, "- Modify: extensions/lib/fixture-*.ts"),
+    ),
+    `expected the invalid-glob finding's line to point at the offending Modify: entry, got: ${JSON.stringify(pe)}`,
+  );
+});
+
+test("check 4 fail-closed: task missing **Files:** block", () => {
+  const mutated = VALID_PLAN.replace(
+    "**Files:**\n- Modify: extensions/lib/fixture-task3.ts\n\n",
+    "",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const pe = findingsFor(findings, "paths-exist");
+  assert.ok(
+    pe.some((f) => f.reason.includes("missing a **Files:** block") && f.text.includes("Task 3")),
+    `expected a missing-Files-block finding, got: ${JSON.stringify(pe)}`,
+  );
+  assert.ok(
+    pe.some(
+      (f) =>
+        f.reason.includes("missing a **Files:** block") &&
+        f.line === lineOf(mutated, "### Task 3: Document banned token handling"),
+    ),
+    `expected the missing-Files-block finding's line to point at Task 3's header, got: ${JSON.stringify(pe)}`,
+  );
+});
+
+test("check 5 placeholder-scan: banned token flagged outside a required-literal span", () => {
+  const mutated = VALID_PLAN.replace(
+    "This task handles naming details.",
+    "This task handles naming details. TODO clean this up.",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const ps = findingsFor(findings, "placeholder-scan");
+  assert.ok(
+    ps.some((f) => f.reason.includes('"TODO"') && f.line === lineOf(mutated, "TODO clean this up")),
+    `expected a placeholder-scan finding for the unexempted TODO, got: ${JSON.stringify(ps)}`,
+  );
+});
+
+test("check 6 wave-file-disjointness: two tasks in the same wave declare the same file", () => {
+  const mutated = VALID_PLAN.replace(
+    "- Modify: extensions/lib/fixture-other.ts",
+    "- Modify: extensions/lib/fixture-shared.ts",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const wfd = findingsFor(findings, "wave-file-disjointness");
+  assert.ok(
+    wfd.some((f) => f.reason.includes("Task 1") && f.reason.includes("Task 2") && f.reason.includes("fixture-shared.ts")),
+    `expected a wave-file-disjointness finding, got: ${JSON.stringify(wfd)}`,
+  );
+  assert.ok(
+    wfd.some((f) => f.line === lineOf(mutated, "## Wave 1 — Two parallel tasks")),
+    `expected the wave-file-disjointness finding's line to point at the offending wave header, got: ${JSON.stringify(wfd)}`,
+  );
+});
+
+test("check 7 solo-line: single-task wave missing its Solo: line", () => {
+  const mutated = VALID_PLAN.replace("Solo: lone remaining task\n\n", "");
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const sl = findingsFor(findings, "solo-line");
+  assert.equal(sl.length, 1);
+  assert.match(sl[0].reason, /missing a 'Solo: <reason>' line/);
+  assert.equal(sl[0].line, lineOf(mutated, "## Wave 2 — Solo task"));
+});
+
+test("check 8 header-entrypoint: verification entrypoint string reused outside the header", () => {
+  const mutated = VALID_PLAN.replace(
+    "This task handles naming details.",
+    "This task handles naming details. Run `npm run fixture-verify` here too.",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const he = findingsFor(findings, "header-entrypoint");
+  assert.ok(
+    he.some((f) => f.line === lineOf(mutated, "Run `npm run fixture-verify` here too")),
+    `expected a header-entrypoint finding, got: ${JSON.stringify(he)}`,
+  );
+});
+
+test("check 8 header-entrypoint: entrypoint text inside the '## Spec coverage' table is out of scope (not a wave/task body)", () => {
+  const mutated = VALID_PLAN.replace(
+    "parser grammar basics",
+    "parser grammar basics npm run fixture-verify",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  assert.deepEqual(findingsFor(findings, "header-entrypoint"), []);
+});
+
+const EXEMPTION_SPEC_TEXT = [
+  "# Exemption Spec", // 1
+  "", // 2
+  "## Notes", // 3
+  "This mentions `TODO` as a banned placeholder example.", // 4
+].join("\n");
+
+const EXEMPTION_PLAN = `# Exemption Plan
+
+**Spec:** \`doc/specs/exemption-spec.md\`
+
+**Verification:** npm run exemption-verify
+
+---
+
+## Wave 1 — Solo task
+
+Solo: only task in this wave
+
+### Task 1: Document banned token handling
+
+**Spec:** doc/specs/exemption-spec.md § "Notes" L4
+
+**Files:**
+- Create: extensions/lib/exemption-task1.ts
+
+The literal TODO is intentionally documented here per spec quote-integrity requirement.
+
+## Spec coverage
+
+| anchor | requirement | owner |
+|---|---|---|
+| § "Notes" L4-L4 | banned token literal handling | Task 1 |
+`;
+
+test("check 2/5 exemption: task body carrying the required verbatim TODO literal satisfies quote-integrity and exempts placeholder-scan", () => {
+  const findings = checkPlan(EXEMPTION_PLAN, EXEMPTION_SPEC_TEXT, alwaysTruePort());
+  assert.deepEqual(findings, []);
+});
+
+test("check 2/5 exemption negative: without the task body carrying the literal, quote-integrity fails and an unexempted TODO elsewhere trips placeholder-scan", () => {
+  const mutated = EXEMPTION_PLAN.replace("## Wave 1 — Solo task", "## Wave 1 — TODO task").replace(
+    "The literal TODO is intentionally documented here per spec quote-integrity requirement.",
+    "This task implements the handling here.",
+  );
+  const findings = checkPlan(mutated, EXEMPTION_SPEC_TEXT, alwaysTruePort());
+  const qi = findingsFor(findings, "quote-integrity");
+  const ps = findingsFor(findings, "placeholder-scan");
+  assert.ok(
+    qi.some((f) => f.reason.includes("TODO") && f.reason.includes("Task 1")),
+    `expected a quote-integrity finding for the missing literal, got: ${JSON.stringify(qi)}`,
+  );
+  assert.ok(
+    qi.some(
+      (f) =>
+        f.reason.includes("TODO") &&
+        f.line === lineOf(mutated, '| § "Notes" L4-L4 | banned token literal handling | Task 1 |'),
+    ),
+    `expected the quote-integrity finding's line to point at the offending Spec coverage row, got: ${JSON.stringify(qi)}`,
+  );
+  assert.ok(
+    ps.some((f) => f.reason.includes('"TODO"') && f.line === lineOf(mutated, "## Wave 1 — TODO task")),
+    `expected an unexempted placeholder-scan finding on the wave header, got: ${JSON.stringify(ps)}`,
+  );
+});
+
+test("aggregate: independent mutations across three checks are all reported together", () => {
+  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.",
+  );
+  mutated = mutated.replace(
+    "- Modify: extensions/lib/fixture-other.ts",
+    "- Modify: extensions/lib/fixture-shared.ts",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  assert.ok(findingsFor(findings, "solo-line").length > 0, "expected a solo-line finding");
+  assert.ok(findingsFor(findings, "quote-integrity").length > 0, "expected a quote-integrity finding");
+  assert.ok(findingsFor(findings, "wave-file-disjointness").length > 0, "expected a wave-file-disjointness finding");
+});
+
+test("grammarless plan: absent-structure findings do not short-circuit the catalog (placeholder-scan still runs)", () => {
+  const grammarless = "# Not a plan\n\nJust some prose with a TODO in it.\n";
+  const findings = checkPlan(grammarless, SPEC_TEXT, alwaysTruePort());
+  const input = findingsFor(findings, "input");
+  assert.ok(
+    input.some((f) => f.reason.includes("no wave headers found")),
+    `expected an absent-wave-structure finding, got: ${JSON.stringify(input)}`,
+  );
+  assert.ok(
+    input.some((f) => f.reason.includes("no task headers found")),
+    `expected an absent-task-structure finding, got: ${JSON.stringify(input)}`,
+  );
+  const ps = findingsFor(findings, "placeholder-scan");
+  assert.ok(
+    ps.some((f) => f.reason.includes('"TODO"')),
+    `expected placeholder-scan to still run over a grammarless plan, got: ${JSON.stringify(ps)}`,
+  );
+});
+
+test("fail-closed: checkPlan never throws on an empty string", () => {
+  assert.doesNotThrow(() => checkPlan("", SPEC_TEXT, alwaysTruePort()));
+});
+
+test("fail-closed: checkPlan never throws on a non-markdown garbage blob", () => {
+  const garbage = "\u0000\u0001binary\ngarbage\tstuff \u{1F4A9} \"\"\"\n```unterminated fence";
+  assert.doesNotThrow(() => checkPlan(garbage, SPEC_TEXT, alwaysTruePort()));
+});
+
+test("sha256 is deterministic and content-sensitive", () => {
+  const a = sha256(new TextEncoder().encode("hello"));
+  const b = sha256(new TextEncoder().encode("hello"));
+  const c = sha256(new TextEncoder().encode("hello!"));
+  assert.equal(a, b);
+  assert.notEqual(a, c);
+  assert.equal(a, "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824");
+});
+
+test("sha256 returns lowercase hex of the expected length", () => {
+  const digest = sha256(new TextEncoder().encode(""));
+  assert.equal(digest.length, 64);
+  assert.match(digest, /^[0-9a-f]+$/);
+});