pi-gauntlet 5.3.1 → 5.3.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v5.3.2 - 2026-09-06
+
+- Plan coverage: `## Spec coverage` rows accept the exact owner `Verification` for requirements the plan header's `**Verification:**` command proves. `table-closure` closes such rows (mechanical row, unparseable anchor, or literal-free anchor -> finding; never counted as task coverage); `quote-integrity` resolves their literals by verbatim containment in the backtick-stripped header. Orphan-owner reason now names `Verification`; anchor-parseability is checked once per row. `header-entrypoint` unchanged. `writing-plans` documents the owner form with a scoped-tests / final-suite example. Spec: `doc/specs/2026-09-06-gh-24-final-verification-ownership.md` (closes #24).
+
 ## v5.3.1 - 2026-09-06
 
 - Task tracking: planning initializes the list once; execution starts and completes existing indices explicitly. Execution retries and fix loops reuse their task; conformance adds only new remediation gaps and reuses their `Gn` indices across rounds.

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

@@ -16,6 +16,9 @@ const SPEC_TEXT = [
   "", // 11
   "## Other", // 12
   "Stuff.", // 13
+  "", // 14
+  "## Acceptance", // 15
+  "Full suite passes: `npm run fixture-verify`.", // 16
 ].join("\n");
 
 const VALID_PLAN = `# Fixture Plan
@@ -70,6 +73,7 @@ The literal TODO is intentionally documented here per spec quote-integrity requi
 | § "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 |
+| § "Acceptance" L16 | full suite passes | Verification |
 `;
 
 function alwaysTruePort(): FsPort {
@@ -157,7 +161,7 @@ test("check 1 owner-cell grammar: trailing junk after a Task <n> list is malform
   assert.ok(
     tc.some(
       (f) =>
-        f.reason.includes("owner cell is not a 'Task <n>' list or 'waived: <reason>'") &&
+        f.reason.includes("owner cell is not a 'Task <n>' list, 'Verification', or 'waived: <reason>'") &&
         f.text.includes("Task 1 (see note)"),
     ),
     `expected an owner-cell malformed finding, got: ${JSON.stringify(tc)}`,
@@ -165,7 +169,7 @@ test("check 1 owner-cell grammar: trailing junk after a Task <n> list is malform
   assert.ok(
     tc.some(
       (f) =>
-        f.reason.includes("owner cell is not a 'Task <n>' list or 'waived: <reason>'") &&
+        f.reason.includes("owner cell is not a 'Task <n>' list, 'Verification', 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)}`,
@@ -180,19 +184,173 @@ test("check 1 owner-cell grammar: empty waiver reason is malformed, not accepted
   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>'")),
+    tc.some((f) => f.reason.includes("owner cell is not a 'Task <n>' list, 'Verification', 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.reason.includes("owner cell is not a 'Task <n>' list, 'Verification', 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)}`,
   );
 });
 
+const VERIFICATION_ROW = '| § "Acceptance" L16 | full suite passes | Verification |';
+
+function withRow(plan: string, row: string): string {
+  return plan.replace(
+    '| § "Other" L12-L13 | out of scope thing | waived: out of scope per spec |',
+    `| § "Other" L12-L13 | out of scope thing | waived: out of scope per spec |\n${row}`,
+  );
+}
+
+for (const owner of ["verification", "Verify", "VERIFICATION", "Task 1, Verification"]) {
+  test(`Verification owner: '${owner}' is a malformed owner -> table-closure`, () => {
+    const row = `| § "Acceptance" L16 | full suite passes | ${owner} |`;
+    const findings = checkPlan(withRow(VALID_PLAN, row), SPEC_TEXT, alwaysTruePort());
+    const tc = findingsFor(findings, "table-closure");
+    assert.ok(
+      tc.some(
+        (f) =>
+          f.reason === "owner cell is not a 'Task <n>' list, 'Verification', or 'waived: <reason>'" &&
+          f.text === row,
+      ),
+      `expected orphan-owner finding for ${owner}, got: ${JSON.stringify(tc)}`,
+    );
+  });
+}
+
+test("Verification owner: unparseable anchor ('-') -> table-closure parseability reason", () => {
+  const row = "| - | full suite passes | Verification |";
+  const findings = checkPlan(withRow(VALID_PLAN, row), SPEC_TEXT, alwaysTruePort());
+  const tc = findingsFor(findings, "table-closure");
+  assert.ok(
+    tc.some(
+      (f) =>
+        f.reason === 'requirement row anchor is not a parseable § "heading" L<n>-L<n> anchor' && f.text === row,
+    ),
+    `expected parseability finding, got: ${JSON.stringify(tc)}`,
+  );
+});
+
+test("Verification owner: anchored lines without a backtick literal -> table-closure", () => {
+  const row = '| § "Other" L13 | stuff | Verification |';
+  const findings = checkPlan(withRow(VALID_PLAN, row), SPEC_TEXT, alwaysTruePort());
+  const tc = findingsFor(findings, "table-closure");
+  assert.ok(
+    tc.some(
+      (f) => f.reason === "Verification row has no backtick literal to check against the header" && f.text === row,
+    ),
+    `expected no-literal finding, got: ${JSON.stringify(tc)}`,
+  );
+});
+
+test("Verification owner: mechanical row -> table-closure", () => {
+  const row = "| - | mechanical: run the suite | Verification |";
+  const findings = checkPlan(withRow(VALID_PLAN, row), SPEC_TEXT, alwaysTruePort());
+  const tc = findingsFor(findings, "table-closure");
+  assert.ok(
+    tc.some((f) => f.reason === "mechanical row owner must be a Task <n>" && f.text === row),
+    `expected mechanical-owner finding, got: ${JSON.stringify(tc)}`,
+  );
+});
+
+test("table-closure: multi-owner row with unparseable anchor yields one parseability finding", () => {
+  const row = "| L999 | naming details | Task 1, Task 2 |";
+  const findings = checkPlan(withRow(VALID_PLAN, row), SPEC_TEXT, alwaysTruePort());
+  const parseability = findingsFor(findings, "table-closure").filter(
+    (f) => f.text === row && f.reason.includes("not a parseable"),
+  );
+  assert.equal(parseability.length, 1);
+});
+
+test("Verification owner: does not satisfy a task's coverage requirement", () => {
+  const mutated = withRow(VALID_PLAN, VERIFICATION_ROW).replace(
+    '| § "Testing" L9-L9 | banned token literal handling | Task 3 |\n',
+    "",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  assert.ok(
+    findingsFor(findings, "table-closure").some((f) =>
+      f.reason.includes("Task 3 does not appear as an owner"),
+    ),
+  );
+});
+
+test("Verification quote-integrity: literal missing from header -> quote-integrity on the row", () => {
+  const mutated = VALID_PLAN.replace("**Verification:** npm run fixture-verify", "**Verification:** npm run other");
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  const qi = findingsFor(findings, "quote-integrity");
+  const row = '| § "Acceptance" L16 | full suite passes | Verification |';
+  assert.ok(
+    qi.some(
+      (f) =>
+        f.reason === "verification header does not contain the required verbatim literal `npm run fixture-verify`" &&
+        f.text === row &&
+        f.line === lineOf(mutated, row),
+    ),
+    `expected header-containment finding, got: ${JSON.stringify(qi)}`,
+  );
+});
+
+test("Verification quote-integrity: multi-command header contains the literal", () => {
+  const mutated = VALID_PLAN.replace(
+    "**Verification:** npm run fixture-verify",
+    "**Verification:** `npm run fixture-verify && npm run lint`",
+  );
+  assert.deepEqual(findingsFor(checkPlan(mutated, SPEC_TEXT, alwaysTruePort()), "quote-integrity"), []);
+});
+
+test("Verification quote-integrity: two-span header contains both literals", () => {
+  const spec = SPEC_TEXT.replace(
+    "Full suite passes: `npm run fixture-verify`.",
+    "Full suite passes: `npm run fixture-verify` and `npm run lint`.",
+  );
+  const mutated = VALID_PLAN.replace(
+    "**Verification:** npm run fixture-verify",
+    "**Verification:** `npm run fixture-verify`, `npm run lint`",
+  );
+  assert.deepEqual(findingsFor(checkPlan(mutated, spec, alwaysTruePort()), "quote-integrity"), []);
+});
+
+test("Verification quote-integrity: missing header -> quote-integrity per literal plus header-entrypoint", () => {
+  const mutated = VALID_PLAN.replace("**Verification:** npm run fixture-verify\n", "");
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  assert.equal(
+    findingsFor(findings, "quote-integrity").filter((f) => f.reason.includes("`npm run fixture-verify`")).length,
+    1,
+  );
+  assert.ok(findingsFor(findings, "header-entrypoint").some((f) => f.reason.includes("missing header")));
+});
+
+test("Verification quote-integrity: task body containing the full header string still fails header-entrypoint", () => {
+  const mutated = VALID_PLAN.replace(
+    "This task handles naming details.",
+    "This task handles naming details. Run npm run fixture-verify here.",
+  );
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  assert.ok(findingsFor(findings, "header-entrypoint").some((f) => f.text.includes("Run npm run fixture-verify here")));
+  assert.deepEqual(findingsFor(findings, "quote-integrity"), []);
+});
+
+test("Verification quote-integrity: task body containing only a sub-command of a multi-command header is not caught by header-entrypoint", () => {
+  const mutated = VALID_PLAN.replace(
+    "**Verification:** npm run fixture-verify",
+    "**Verification:** `npm run fixture-verify && npm run lint`",
+  ).replace("This task handles naming details.", "This task handles naming details. Run npm run fixture-verify here.");
+  const findings = checkPlan(mutated, SPEC_TEXT, alwaysTruePort());
+  assert.deepEqual(findingsFor(findings, "header-entrypoint"), []);
+  assert.deepEqual(findingsFor(findings, "quote-integrity"), []);
+});
+
+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 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()`")));
+});
+
 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());

package/extensions/lib/plan-check.ts

@@ -69,6 +69,7 @@ interface CoverageRow {
   isWaived: boolean;
   ownerTasks: number[];
   ownerMalformed: boolean;
+  isVerification: boolean;
   anchor: Anchor | undefined;
 }
 
@@ -270,6 +271,7 @@ function parsePlan(planText: string): ParsedPlan {
       let isWaived = false;
       let ownerTasks: number[] = [];
       let ownerMalformed = false;
+      const isVerification = ownerCell === "Verification";
       if (waivedMatch) {
         if (waivedMatch[1].trim().length === 0) {
           ownerMalformed = true;
@@ -278,7 +280,7 @@ function parsePlan(planText: string): ParsedPlan {
         }
       } else if (isTaskList) {
         ownerTasks = [...ownerCell.matchAll(/Task (\d+)/g)].map((mm) => Number(mm[1]));
-      } else {
+      } else if (!isVerification) {
         ownerMalformed = true;
       }
       let anchor: Anchor | undefined;
@@ -296,6 +298,7 @@ function parsePlan(planText: string): ParsedPlan {
         isWaived,
         ownerTasks,
         ownerMalformed,
+        isVerification,
         anchor,
       });
       p++;
@@ -380,7 +383,7 @@ function computeRequiredLiteralsPerTask(parsed: ParsedPlan, specLines: string[])
   return map;
 }
 
-function checkTableClosure(parsed: ParsedPlan): PlanCheckFinding[] {
+function checkTableClosure(parsed: ParsedPlan, specLines: string[]): PlanCheckFinding[] {
   const findings: PlanCheckFinding[] = [];
   if (!parsed.coverageTableFound) {
     findings.push({ check: "table-closure", line: 0, text: "", reason: "no '## Spec coverage' table found" });
@@ -396,34 +399,54 @@ function checkTableClosure(parsed: ParsedPlan): PlanCheckFinding[] {
         check: "table-closure",
         line: row.line,
         text: row.text,
-        reason: "owner cell is not a 'Task <n>' list or 'waived: <reason>'",
+        reason: "owner cell is not a 'Task <n>' list, 'Verification', or 'waived: <reason>'",
+      });
+      continue;
+    }
+    if (row.isVerification && row.isMechanical) {
+      findings.push({
+        check: "table-closure",
+        line: row.line,
+        text: row.text,
+        reason: "mechanical row owner must be a Task <n>",
       });
       continue;
     }
     if (row.isWaived) continue;
-    for (const n of row.ownerTasks) {
-      coveredTasks.add(n);
-      if (row.isMechanical) mechanicalCoveredTasks.add(n);
-      const task = taskByNumber.get(n);
-      if (!task) {
+    const anchorUnparseable = !row.isMechanical && !row.anchor;
+    if (anchorUnparseable) {
+      findings.push({
+        check: "table-closure",
+        line: row.line,
+        text: row.text,
+        reason: 'requirement row anchor is not a parseable § "heading" L<n>-L<n> anchor',
+      });
+    }
+    if (row.isVerification) {
+      if (!anchorUnparseable && requiredLiteralsForRow(row, specLines).length === 0) {
         findings.push({
           check: "table-closure",
           line: row.line,
           text: row.text,
-          reason: `row references Task ${n} but no such task exists`,
+          reason: "Verification row has no backtick literal to check against the header",
         });
-        continue;
       }
-      if (row.isMechanical) continue;
-      if (!row.anchor) {
+      continue;
+    }
+    for (const n of row.ownerTasks) {
+      coveredTasks.add(n);
+      if (row.isMechanical) mechanicalCoveredTasks.add(n);
+      const task = taskByNumber.get(n);
+      if (!task) {
         findings.push({
           check: "table-closure",
           line: row.line,
           text: row.text,
-          reason: 'requirement row anchor is not a parseable \u00a7 "heading" L<n>-L<n> anchor',
+          reason: `row references Task ${n} but no such task exists`,
         });
         continue;
       }
+      if (row.isMechanical || anchorUnparseable) continue;
       const contained = task.anchors.some(
         (a) => a.heading === row.anchor!.heading && a.start === row.anchor!.start && a.end === row.anchor!.end,
       );
@@ -465,10 +488,24 @@ function checkQuoteIntegrity(parsed: ParsedPlan, specLines: string[]): PlanCheck
   const findings: PlanCheckFinding[] = [];
   if (!parsed.coverageTableFound) return findings;
   const taskByNumber = new Map(parsed.tasks.map((t) => [t.number, t]));
+  const headerText = (parsed.header.verificationText ?? "").replaceAll("`", "");
   for (const row of parsed.coverageRows) {
     if (row.ownerMalformed || row.isWaived || row.isMechanical) continue;
     const literals = requiredLiteralsForRow(row, specLines);
     if (literals.length === 0) continue;
+    if (row.isVerification) {
+      for (const lit of literals) {
+        if (!headerText.includes(lit)) {
+          findings.push({
+            check: "quote-integrity",
+            line: row.line,
+            text: row.text,
+            reason: `verification header does not contain the required verbatim literal \`${lit}\``,
+          });
+        }
+      }
+      continue;
+    }
     for (const n of row.ownerTasks) {
       const task = taskByNumber.get(n);
       if (!task) continue;
@@ -805,7 +842,7 @@ export function checkPlan(planText: string, specText: string, fs: FsPort): PlanC
     }
 
     const specLines = specText.split("\n");
-    findings.push(...checkTableClosure(parsed));
+    findings.push(...checkTableClosure(parsed, specLines));
     findings.push(...checkQuoteIntegrity(parsed, specLines));
     findings.push(...checkAnchorResolution(parsed, specLines));
     findings.push(...checkPathsExist(parsed, fs));

package/package.json

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

package/skills/writing-plans/SKILL.md

@@ -264,11 +264,14 @@ Every plan ends with a `## Spec coverage` section — authored last, placed afte
 |---|---|---|
 | § "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 `waived: <reason>` **only when the spec itself marks the item out of scope**. A waiver on an in-scope normative requirement is a Self-Review failure — there is no human plan-review gate to catch it downstream.
+- **Requirement rows:** anchor + short requirement + owner = task-ID list, or `Verification`, or `waived: <reason>` **only when the spec itself marks the item out of scope**. 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.
 - The table is plan-authoring-time only — never passed to implementer or reviewer dispatches.
 
@@ -293,12 +296,13 @@ 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, and header-only entrypoint.
-- **Code-vs-anchor sanity.** For each non-waived 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. Fix the task, don't annotate.
+- **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.
 - **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.** Every `waived: <reason>` owner in `## Spec coverage` is authorized by the spec itself marking the item out of scope. 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-ownership authorization.** `Verification` on a requirement no header command exercises is a Self-Review failure.
 - **Documentation-impact mapping.** Each Documentation impact entry maps to a plan task (or explicit "none").
 
 Fix what this review finds before handoff.