@planu/cli 5.3.3 → 5.3.5

package/CHANGELOG.md

@@ -1,3 +1,38 @@
+## [5.3.5] - 2026-08-06
+
+### Bug Fixes
+- fix(tests): make the spec-write guard test independent of git HEAD
+- fix(lifecycle): close done-gate bypass, report digest drift and ship debate rules
+- fix(reconcile): harden audit-cell escaping and fail-closed rollback (SPEC-1250)
+- fix(spec-format): preserve wrapped BDD continuation lines in criterion identities (SPEC-1253)
+
+### Chores
+- chore(planu): close SPEC-1250 with debate evidence, file SPEC-1424
+- chore(planu): SPEC-1253 done with debate evidence
+- chore(planu): file SPEC-1423 (done-gate revalidate reprocessing)
+- chore(planu): file SPEC-1421 and SPEC-1422 from client dogfood report
+
+
+## [5.3.4] - 2026-08-06
+
+### Bug Fixes
+- fix(deps): override js-yaml to patched versions for CVE-2026-59870
+- fix(spec-format): keep rendered criteria BDD-executable after canonical parsing
+- fix(spec-format): resolve rendered criteria through the canonical parser (SPEC-1410)
+- fix(spec-quality): render and count every acceptance criterion (SPEC-1410)
+- fix(planu): point SPEC-1405 verification map at the real test filename
+- fix(spec-quality): stop shipping template filler and self-certifying spec sections (SPEC-1406)
+- fix(drift): make follow-up spec id deterministic per parent spec (SPEC-1405)
+- fix(drift): emit one drift event per project instead of one per spec (SPEC-1405)
+
+### Chores
+- chore(planu): SPEC-1405 and SPEC-1406 done with debate evidence
+- chore(planu): SPEC-1405 and SPEC-1406 implementing with packaged handoffs
+- chore(planu): approve SPEC-1405 and SPEC-1406 with debate evidence, file SPEC-1410..1411
+- chore(planu): file SPEC-1401..1409 from deep flow audit
+- chore(planu): SPEC-1396 done with debate evidence, file SPEC-1397..1400
+
+
 ## [5.3.3] - 2026-08-06
 
 ### Bug Fixes

package/dist/engine/autopilot/action-registry.js

@@ -219,7 +219,17 @@ const ACTION_HANDLERS = {
     resolve_drift_violations: wrapHandler('resolve_drift_violations', async (ctx) => {
         const { resolveDriftViolations } = await import('../drift/violation-resolver.js');
         const result = (await resolveDriftViolations(ctx.projectPath, ctx.projectId));
-        const resolved = safeCount(result, 'resolvedCount');
+        // DriftResolutionResult exposes `resolved` as an array (see types/health.ts);
+        // safeCount() returns its length. There is no `resolvedCount` field.
+        const resolved = safeCount(result, 'resolved');
+        const manualReview = safeCount(result, 'manualReview');
+        if (manualReview > 0) {
+            return {
+                success: false,
+                summary: `Resolved ${resolved} drift violations, ${manualReview} need manual review`,
+                durationMs: 0,
+            };
+        }
         return {
             success: true,
             summary: `Resolved ${resolved} drift violations`,
@@ -228,13 +238,21 @@ const ACTION_HANDLERS = {
     }),
     log_lesson: wrapHandler('log_lesson', async (ctx) => {
         const { addLesson } = await import('../../storage/lessons-store.js');
+        // drift:detected events (auto-drift.ts) are project-wide and carry no
+        // ctx.specId; fall back to the payload's specIds so the lesson stays
+        // attributed to the drifted specs instead of going generic.
+        const payloadSpecIds = ctx.payload?.specIds;
+        const attributedSpecIds = Array.isArray(payloadSpecIds)
+            ? payloadSpecIds.filter((id) => typeof id === 'string')
+            : [];
+        const attribution = ctx.specId ?? (attributedSpecIds.length > 0 ? attributedSpecIds.join(', ') : undefined);
         const lesson = await addLesson(ctx.projectPath, {
             projectId: ctx.projectId,
             specId: ctx.specId,
             category: 'process',
             severity: 'low',
             title: 'Drift detected',
-            description: `Spec drift was detected${ctx.specId !== undefined ? ` for ${ctx.specId}` : ''}.`,
+            description: `Spec drift was detected${attribution !== undefined ? ` for ${attribution}` : ''}.`,
             prevention: 'Review spec file alignment with implementation after each commit.',
             tags: ['drift', 'autopilot'],
         });

package/dist/engine/constitution/sdd-rules-registry.js

@@ -1,4 +1,4 @@
-import { checkGenericSpecOutput } from '../spec-quality/generic-output-gate.js';
+import { checkGenericSpecOutput, STRUCTURAL_INTERPOLATION_KIND, } from '../spec-quality/generic-output-gate.js';
 import { checkGroundedSpecContract } from '../spec-grounding/contract.js';
 export const DEFAULT_SDD_CONSTITUTION_RULES = [
     {
@@ -81,7 +81,11 @@ export function evaluateSddConstitutionRules(args) {
     }
     if (rules.some((rule) => rule.id === 'sdd.no-generic-output')) {
         const generic = checkGenericSpecOutput(args.content);
-        violations.push(...generic.issues.map((issue) => violation('sdd.no-generic-output', issue.reason, [issue.phrase], rules)));
+        violations.push(...generic.issues.map((issue) => violation('sdd.no-generic-output', issue.reason, [issue.phrase], rules, 
+        // SPEC-1406: structural-interpolation findings are advisory here — the blocking
+        // enforcement point for this new detector is create_spec, not the constitution
+        // gate, so ~1100 already-persisted specs stay transitionable.
+        issue.kind === STRUCTURAL_INTERPOLATION_KIND ? 'advisory' : undefined)));
     }
     return violations;
 }
@@ -92,11 +96,11 @@ export function renderSddConstitutionRulesForHost() {
         ...enabled.map((rule) => `- ${rule.id} (${rule.level}): ${rule.description} Next action: ${rule.nextAction}`),
     ].join('\n');
 }
-function violation(ruleId, message, evidence, rules) {
+function violation(ruleId, message, evidence, rules, levelOverride) {
     const rule = rules.find((candidate) => candidate.id === ruleId);
     return {
         ruleId,
-        level: rule?.level ?? 'blocking',
+        level: levelOverride ?? rule?.level ?? 'blocking',
         message,
         evidence,
         nextAction: rule?.nextAction ?? 'Fix the violated SDD constitution rule.',

package/dist/engine/drift/violation-resolver.js

@@ -1,8 +1,9 @@
 // engine/drift/violation-resolver.ts — Semi-automatic drift violation resolution (SPEC-408)
-import { mkdir, writeFile, access } from 'node:fs/promises';
+import { mkdir, access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { specStore } from '../../storage/index.js';
 import { DriftCacheStore } from '../../storage/drift-cache-store.js';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -16,10 +17,22 @@ async function specDirExists(specDir) {
     }
 }
 async function createFollowUpSpec(projectPath, parentSpecId, reason, dryRun) {
-    const timestamp = Date.now();
-    const specId = `SPEC-followup-${parentSpecId.toLowerCase()}-${timestamp}`;
+    // SPEC-1405 (AC2): the id is deterministic per parent spec, not timestamp-keyed.
+    // A timestamped id made every drift pass create a brand-new follow-up directory,
+    // so repeated triggers spammed duplicates instead of converging on one record.
+    const specId = `SPEC-followup-${parentSpecId.toLowerCase()}`;
     if (!dryRun) {
         const specDir = join(projectPath, 'planu', 'specs', specId);
+        const specPath = join(specDir, 'spec.md');
+        // Already created by an earlier pass — leave it alone. Rewriting would clobber
+        // any edits made to the follow-up spec since it was raised.
+        try {
+            await access(specPath);
+            return specId;
+        }
+        catch {
+            // Not present yet — fall through and create it.
+        }
         await mkdir(specDir, { recursive: true });
         const now = new Date().toISOString();
         const specContent = [
@@ -42,7 +55,7 @@ async function createFollowUpSpec(projectPath, parentSpecId, reason, dryRun) {
             '- [ ] Run detect_drift to confirm score returns to 0',
             '',
         ].join('\n');
-        await writeFile(join(specDir, 'spec.md'), specContent, 'utf-8');
+        await atomicWriteFile(specPath, specContent);
     }
     return specId;
 }
@@ -88,12 +101,21 @@ export async function resolveDriftViolations(projectPath, projectId, dryRun = fa
             continue;
         }
         if (spec.status === 'done') {
-            // Code diverged from a completed spec — create follow-up
+            // Code diverged from a completed spec — create follow-up.
+            // The write is atomic (tmp + fsync + rename); if it throws (e.g. the
+            // target spec.md is frozen), count the violation as unresolved instead
+            // of letting the error escape into the fire-and-forget autopilot handler.
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             const reason = `Drift detected (score: ${entry.driftScore.toFixed(2)}) in files: ${(entry.driftedFiles ?? []).join(', ') || 'unknown'}`;
-            const followUpId = await createFollowUpSpec(projectPath, spec.id, reason, dryRun);
-            followUpSpecsCreated.push(followUpId);
-            resolved.push(buildDoneButDivergedResolution(spec.id));
+            try {
+                const followUpId = await createFollowUpSpec(projectPath, spec.id, reason, dryRun);
+                followUpSpecsCreated.push(followUpId);
+                resolved.push(buildDoneButDivergedResolution(spec.id));
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                manualReview.push(`${spec.id}: follow-up spec write failed — ${msg}`);
+            }
         }
         else if (spec.status === 'implementing') {
             // In-progress spec with code ahead — annotate but don't block

package/dist/engine/evidence-gates/evidence-skeletons.js

@@ -1,7 +1,12 @@
-// evidence-skeletons.ts — SPEC-1356: auto-generate schema-valid discovery/task-plan skeletons
-// when the underlying handoff evidence file is missing, so lifecycle gates self-heal instead
-// of blocking on a manual authoring step. Skeletons still require review; they only unblock
-// the transition, they do not fabricate confidence.
+// evidence-skeletons.ts — SPEC-1356: auto-generate a schema-valid task-plan skeleton when the
+// underlying handoff evidence file is missing, so the `implementing` lifecycle gate self-heals
+// instead of blocking on a manual authoring step.
+//
+// SPEC-1406 (DEFECT 3): `generateDiscoverySkeleton` is kept here (still exercised directly by
+// its own tests) but is no longer wired into the `approved` gate's autofill path — writing a
+// fabricated discovery skeleton made the blocking discovery-evidence gate self-certify. The
+// `approved` transition now reports `discovery_missing` with the specific missing fields
+// instead of silently manufacturing the evidence it was supposed to require.
 import { join } from 'node:path';
 import { extractListItems, extractSection } from '../spec-format/markdown-sections.js';
 import { parseCriterionGroundingRecords } from '../spec-grounding/contract.js';

package/dist/engine/execution/validate-job-executor.js

@@ -84,6 +84,25 @@ function validationPassed(result) {
     const report = structured?.validationReport;
     return structured?.ready === true && report?.passed === true;
 }
+function withEnrichedValidationReportSha(structuredContent, sha) {
+    const validationReport = structuredContent.validationReport;
+    const artifactRefs = structuredContent.artifactRefs;
+    return {
+        ...structuredContent,
+        ...(validationReport ? { validationReport: { ...validationReport, sha } } : {}),
+        ...(artifactRefs ? { artifactRefs: { ...artifactRefs, validationReportSha: sha } } : {}),
+    };
+}
+function buildReceiptResult(checkpointResult, receiptId, receiptKey, enrichedReportSha) {
+    const baseStructuredContent = checkpointResult.structuredContent ?? {};
+    const structuredContent = enrichedReportSha
+        ? withEnrichedValidationReportSha(baseStructuredContent, enrichedReportSha)
+        : baseStructuredContent;
+    return {
+        ...checkpointResult,
+        structuredContent: { ...structuredContent, receiptId, receiptKey },
+    };
+}
 async function closeFreshnessLeaseSafely(lease) {
     if (!lease) {
         return;
@@ -690,20 +709,14 @@ export class ValidateJobExecutor {
                 throw new Error('[Planu] Validation inputs changed during receipt publication');
             }
             const receiptKey = `validation-receipt:${receipt.receiptId.slice('sha256:'.length)}`;
+            let enrichedReportSha;
             try {
-                await this.persistReceiptArtifacts(identity, payload, receipt.receiptId, receiptKey);
+                enrichedReportSha = await this.persistReceiptArtifacts(identity, payload, receipt.receiptId, receiptKey);
             }
             catch (error) {
                 throw new ReceiptPublicationInterruptedError({ cause: error });
             }
-            return {
-                ...checkpoint.result,
-                structuredContent: {
-                    ...(checkpoint.result.structuredContent ?? {}),
-                    receiptId: receipt.receiptId,
-                    receiptKey,
-                },
-            };
+            return buildReceiptResult(checkpoint.result, receipt.receiptId, receiptKey, enrichedReportSha);
         }
         finally {
             database.close();
@@ -759,13 +772,15 @@ export class ValidateJobExecutor {
             kind: 'validation-report',
         });
         if (existingReport.ok) {
-            await appendArtifact({
+            const rewritten = await appendArtifact({
                 projectId: identity.projectId,
                 specId: payload.bindings.specId,
                 kind: 'validation-report',
                 payload: { ...existingReport.payload, receiptId, receiptKey },
             });
+            return `sha256:${rewritten.sha}`;
         }
+        return undefined;
     }
 }
 /** Schedules background execution after the submit response can be flushed. */

package/dist/engine/handoff-packager.js

@@ -444,12 +444,19 @@ function extractBacktickedFiles(content) {
     }
     return [...files].sort();
 }
+/**
+ * SPEC-1406 (DEFECT 6): markdown heading lines (e.g. "### Edge Cases And Failure Modes")
+ * match keyword regexes like /\bedge\b/ just as readily as real bullet content, so headings
+ * used to leak into testPlan/risks/ownership as if they were grounded items. Skip headings
+ * and dedupe before truncating, so a criterion repeated under multiple sections — or the same
+ * heading matching two keyword sets — is not counted as distinct evidence twice.
+ */
 function extractLinesByKeywords(content, keywords) {
-    return content
+    const lines = content
         .split('\n')
         .map((line) => line.trim().replace(/^[-*]\s*/, ''))
-        .filter((line) => line.length > 0 && keywords.test(line))
-        .slice(0, 12);
+        .filter((line) => line.length > 0 && !/^#{1,6}\s/.test(line) && keywords.test(line));
+    return [...new Set(lines)].slice(0, 12);
 }
 function extractOperationalSections(content, spec) {
     return {

package/dist/engine/implementation-contract/common.d.ts

@@ -1,5 +1,17 @@
 export declare const IMPLEMENTATION_CONTRACT_SECTION = "Implementation Contract";
-export declare const IMPLEMENTATION_CONTRACT_SUBSECTIONS: readonly ['User Outcome', 'Behavior Contract', 'File-Level Work Plan', 'Acceptance-To-Verification Map', 'Edge Cases And Failure Modes', 'Non-Goals And Forbidden Approaches', 'Verification Commands'];
+/** Subsections every rendered contract must include — omitting one is a defect. */
+export declare const IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS: readonly ['User Outcome', 'File-Level Work Plan', 'Acceptance-To-Verification Map', 'Verification Commands'];
+/**
+ * SPEC-1406: subsections that carry no grounded content are omitted from the rendered
+ * body rather than filled with restated-criterion filler. Their absence is not an
+ * evaluator defect — only their presence-but-empty is. This keeps the ~1100
+ * already-persisted specs that still carry these sections (with real, non-empty
+ * content) transitionable: `evaluateImplementationContract` only requires them when
+ * the rendered body chose to include the heading.
+ */
+export declare const IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS: readonly ['Behavior Contract', 'Edge Cases And Failure Modes', 'Non-Goals And Forbidden Approaches'];
+/** Union of required + optional subsections. Kept for callers that only need the full set. */
+export declare const IMPLEMENTATION_CONTRACT_SUBSECTIONS: readonly ["User Outcome", "File-Level Work Plan", "Acceptance-To-Verification Map", "Verification Commands", "Behavior Contract", "Edge Cases And Failure Modes", "Non-Goals And Forbidden Approaches"];
 export declare function hasImplementationContract(specBody: string): boolean;
 export declare function extractTopLevelSection(body: string, sectionName: string): string;
 //# sourceMappingURL=common.d.ts.map

package/dist/engine/implementation-contract/common.js

@@ -1,12 +1,28 @@
 export const IMPLEMENTATION_CONTRACT_SECTION = 'Implementation Contract';
-export const IMPLEMENTATION_CONTRACT_SUBSECTIONS = [
+/** Subsections every rendered contract must include — omitting one is a defect. */
+export const IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS = [
     'User Outcome',
-    'Behavior Contract',
     'File-Level Work Plan',
     'Acceptance-To-Verification Map',
+    'Verification Commands',
+];
+/**
+ * SPEC-1406: subsections that carry no grounded content are omitted from the rendered
+ * body rather than filled with restated-criterion filler. Their absence is not an
+ * evaluator defect — only their presence-but-empty is. This keeps the ~1100
+ * already-persisted specs that still carry these sections (with real, non-empty
+ * content) transitionable: `evaluateImplementationContract` only requires them when
+ * the rendered body chose to include the heading.
+ */
+export const IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS = [
+    'Behavior Contract',
     'Edge Cases And Failure Modes',
     'Non-Goals And Forbidden Approaches',
-    'Verification Commands',
+];
+/** Union of required + optional subsections. Kept for callers that only need the full set. */
+export const IMPLEMENTATION_CONTRACT_SUBSECTIONS = [
+    ...IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS,
+    ...IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS,
 ];
 export function hasImplementationContract(specBody) {
     return extractTopLevelSection(specBody, IMPLEMENTATION_CONTRACT_SECTION).trim().length > 0;

package/dist/engine/implementation-contract/evaluator.js

@@ -1,4 +1,4 @@
-import { extractTopLevelSection, IMPLEMENTATION_CONTRACT_SECTION, IMPLEMENTATION_CONTRACT_SUBSECTIONS, } from './common.js';
+import { extractTopLevelSection, IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS, IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS, IMPLEMENTATION_CONTRACT_SECTION, } from './common.js';
 const FILLER_PATTERNS = [
     /\bTBD\b/i,
     /\bN\/A\b/i,
@@ -8,6 +8,19 @@ const FILLER_PATTERNS = [
 ];
 const MANUAL_VERIFICATION_STEP_RE = /\b(given|when|then|step|observe|click|run)\b/i;
 const CONCRETE_MANUAL_EVIDENCE_RE = /`[^`]+`|\b(?:src|tests|docs|scripts|website|planu)\/[\w./-]+/i;
+const OPTIONAL_SUBSECTIONS = new Set(IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS);
+/**
+ * SPEC-1406 (DEFECT 1, round 2 — FALSE EVIDENCE fix): the old CONCRETE_MANUAL_EVIDENCE_RE
+ * accepted ANY backticked text, so a row whose evidence was `` `not-a-path` `` produced zero
+ * issues. Verification-row evidence must actually look like a test path (a `tests/` segment,
+ * or `.test.`/`.spec.` in the filename), a runnable test/typecheck/lint command, or a
+ * backticked command/path that names a real file or script (contains `/` or a file
+ * extension) — a bare backticked word with neither is not evidence.
+ */
+const TEST_EVIDENCE_RE = /tests?\/[\w./-]+\.\w+|\.(?:test|spec)\.\w+|\b(?:pnpm|npm|npx|yarn)\s+(?:run\s+)?[\w:-]*(?:test|typecheck|lint)[\w:-]*\b|\bvitest\b|\bjest\b|\bpytest\b|\bgo test\b|\bcargo test\b|`[^`]*(?:[\\/]|\.[a-zA-Z]{1,10}\b)[^`]*`/i;
+/** The shared row rendered by renderSharedVerificationRow when there are fewer test files
+ * than criteria — it covers every criterion at once rather than one row each. */
+const SHARED_VERIFICATION_ROW_RE = /^-\s*All criteria are verified by:/;
 export function evaluateImplementationContract(specBody, acceptanceCriteria) {
     const contract = extractTopLevelSection(specBody, IMPLEMENTATION_CONTRACT_SECTION);
     if (contract.trim().length === 0) {
@@ -19,56 +32,77 @@ export function evaluateImplementationContract(specBody, acceptanceCriteria) {
         ];
     }
     const issues = [];
-    const sections = new Map(IMPLEMENTATION_CONTRACT_SUBSECTIONS.map((section) => [
-        section,
-        extractSubsection(contract, section),
-    ]));
+    const allSubsections = [
+        ...IMPLEMENTATION_CONTRACT_REQUIRED_SUBSECTIONS,
+        ...IMPLEMENTATION_CONTRACT_OPTIONAL_SUBSECTIONS,
+    ];
+    const sections = new Map(allSubsections.map((section) => [section, extractSubsection(contract, section)]));
     for (const [section, content] of sections.entries()) {
-        if (content === null) {
+        issues.push(...evaluateSubsection(section, content));
+    }
+    const map = sections.get('Acceptance-To-Verification Map') ?? '';
+    const mapLines = map.split('\n').map((line) => line.trim());
+    const sharedRowCoversAll = mapLines.some((line) => SHARED_VERIFICATION_ROW_RE.test(line) && TEST_EVIDENCE_RE.test(line));
+    const useStrictIndex = hasCompleteAcLabeling(mapLines, acceptanceCriteria.length);
+    acceptanceCriteria.forEach((criterion, index) => {
+        if (sharedRowCoversAll) {
+            return;
+        }
+        if (!criterionHasVerification(criterion, index + 1, mapLines, useStrictIndex)) {
+            issues.push({
+                code: 'contract_unmapped_criterion',
+                message: `Acceptance criterion is not mapped to verification evidence: ${criterion}`,
+            });
+        }
+    });
+    if (/\bmanual verification\b/i.test(map) &&
+        !MANUAL_VERIFICATION_STEP_RE.test(map) &&
+        !CONCRETE_MANUAL_EVIDENCE_RE.test(map)) {
+        issues.push({
+            code: 'contract_manual_verification_vague',
+            message: 'Manual verification in the Implementation Contract must include exact observable steps.',
+        });
+    }
+    return issues;
+}
+/**
+ * SPEC-1406: optional subsections with no grounded content are omitted from the rendered
+ * body entirely — that is the intended fix, not a defect to flag.
+ */
+function evaluateSubsection(section, content) {
+    const issues = [];
+    if (content === null) {
+        if (!OPTIONAL_SUBSECTIONS.has(section)) {
             issues.push({
                 code: 'contract_subsection_missing',
                 message: `Implementation Contract subsection "${section}" is missing.`,
             });
-            continue;
         }
-        const trimmed = content.trim();
-        if (trimmed.length === 0) {
+        return issues;
+    }
+    const trimmed = content.trim();
+    if (trimmed.length === 0) {
+        if (!OPTIONAL_SUBSECTIONS.has(section)) {
             issues.push({
                 code: 'contract_subsection_empty',
                 message: `Implementation Contract subsection "${section}" is empty.`,
             });
         }
-        for (const pattern of FILLER_PATTERNS) {
-            if (pattern.test(trimmed)) {
-                issues.push({
-                    code: 'contract_filler',
-                    message: `Implementation Contract subsection "${section}" contains filler text.`,
-                });
-                break;
-            }
-        }
-        if (/\bNeeds decision:/i.test(trimmed)) {
-            issues.push({
-                code: 'contract_needs_decision',
-                message: `Implementation Contract subsection "${section}" still has unresolved Needs decision items.`,
-            });
-        }
+        return issues;
     }
-    const map = sections.get('Acceptance-To-Verification Map') ?? '';
-    for (const criterion of acceptanceCriteria) {
-        if (!criterionHasVerification(criterion, map)) {
+    for (const pattern of FILLER_PATTERNS) {
+        if (pattern.test(trimmed)) {
             issues.push({
-                code: 'contract_unmapped_criterion',
-                message: `Acceptance criterion is not mapped to verification evidence: ${criterion}`,
+                code: 'contract_filler',
+                message: `Implementation Contract subsection "${section}" contains filler text.`,
             });
+            break;
         }
     }
-    if (/\bmanual verification\b/i.test(map) &&
-        !MANUAL_VERIFICATION_STEP_RE.test(map) &&
-        !CONCRETE_MANUAL_EVIDENCE_RE.test(map)) {
+    if (/\bNeeds decision:/i.test(trimmed)) {
         issues.push({
-            code: 'contract_manual_verification_vague',
-            message: 'Manual verification in the Implementation Contract must include exact observable steps.',
+            code: 'contract_needs_decision',
+            message: `Implementation Contract subsection "${section}" still has unresolved Needs decision items.`,
         });
     }
     return issues;
@@ -85,7 +119,54 @@ function extractSubsection(sectionBody, subsectionName) {
     const next = nextRe.exec(sectionBody);
     return sectionBody.slice(start, next ? next.index : sectionBody.length);
 }
-function criterionHasVerification(criterion, map) {
+/**
+ * A map only qualifies for strict index-based matching when EVERY criterion 1..N has its
+ * own `AC{n}:` row — a partial or off-by-one labeling scheme (e.g. an extra `AB1:` row for
+ * a review-only criterion) is not the renderer's per-criterion output shape and must not
+ * be forced into it; fall back to the legacy whole-map match instead (see below).
+ */
+function hasCompleteAcLabeling(mapLines, criteriaCount) {
+    if (criteriaCount === 0) {
+        return false;
+    }
+    for (let index = 1; index <= criteriaCount; index += 1) {
+        const rowRe = new RegExp(`^-\\s*AC${String(index)}:`);
+        if (!mapLines.some((line) => rowRe.test(line))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * SPEC-1406 (DEFECT 1, round 2 — PREFIX COLLISION fix): the old lookup matched rows by
+ * `normalize(criterion).slice(0, 48)` and took the FIRST matching line — two criteria
+ * sharing the same first 48 normalized characters were both "certified" by AC1's row,
+ * so AC2 could be entirely unmapped and still pass. `AC{n}:` labels are only ever emitted
+ * by this renderer (renderPerCriterionRow), so when the map has a complete `AC1:`..`ACn:`
+ * sequence, match strictly on the labeled index instead of a truncated prefix.
+ *
+ * When the map does not have a complete AC-labeled sequence, it was authored by hand or by
+ * an older generator (bullet lists, GIVEN/WHEN/THEN prose, markdown tables, partial AC
+ * labeling — corpus-replay against all pre-SPEC-1406 persisted specs found no single
+ * positional or structural rule that covers every legacy shape without newly blocking specs
+ * that were previously readable). Falling back to the original whole-map prefix/keyword
+ * match preserves exact pre-fix behavior for that legacy corpus — the non-functional
+ * constraint that no already-persisted spec may gain a new blocker takes priority over
+ * tightening a shape this fix does not target.
+ */
+function criterionHasVerification(criterion, index, mapLines, useStrictIndex) {
+    if (criterion.trim().length === 0) {
+        return true;
+    }
+    if (useStrictIndex) {
+        const rowRe = new RegExp(`^-\\s*AC${String(index)}:`);
+        const row = mapLines.find((line) => rowRe.test(line));
+        return row !== undefined && TEST_EVIDENCE_RE.test(row);
+    }
+    return legacyCriterionHasVerification(criterion, mapLines.join('\n'));
+}
+/** Pre-SPEC-1406 whole-map matcher, kept verbatim for maps with no `AC{n}:` labels. */
+function legacyCriterionHasVerification(criterion, map) {
     const normalizedCriterion = normalize(criterion);
     if (normalizedCriterion.length === 0) {
         return true;