@planu/cli 5.3.2 → 5.3.4

package/CHANGELOG.md

@@ -1,3 +1,40 @@
+## [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
+- fix(release): tolerate empty ff-behind mirror list under set -u
+- fix(outbox): return a typed failure from delivery attempts for the reliability gate
+- fix(git): close SPEC-1396 debate findings and record review evidence
+- fix(git): never move the shared checkout from automatic paths (SPEC-1396)
+- fix(outbox): address SPEC-1271 debate review findings
+- fix(outbox): bounded fair durable spec.created recovery without blocking startup (SPEC-1271)
+
+### Chores
+- chore(planu): file SPEC-1396 git-safety dogfood bug
+- chore(planu): session checkpoint after SPEC-1271 cycle
+- chore(planu): SPEC-1271 done with debate evidence, file SPEC-1395
+- chore(planu): SPEC-1271 implementing with structured work plan, file SPEC-1394
+
+
 ## [5.3.2] - 2026-08-06
 
 ### Bug Fixes

package/dist/config/runtime-policy.json

@@ -51,5 +51,14 @@
     "leaseMultiplier": 3,
     "maximumRememberedTransitions": 1000,
     "minimumHeartbeatMs": 1000
+  },
+  "outbox": {
+    "sliceRecordBudget": 25,
+    "sliceTimeBudgetMs": 5000,
+    "backoffBaseMs": 30000,
+    "backoffCapMs": 1800000,
+    "maxAttempts": 3,
+    "diagnosticMaxLength": 500,
+    "continuationDelayMs": 250
   }
 }

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/autopilot/complete-loop.js

@@ -47,7 +47,10 @@ async function runWithProgress(projectPath, projectId, specId, action, fn) {
  */
 async function doAutoCreateBranch(projectId, specId) {
     const { handleCreateBranch } = await import('../../tools/git/branch-ops.js');
-    const result = await handleCreateBranch(projectId, specId);
+    // SPEC-1396: cascade side effect — create the ref, never move the shared checkout.
+    const result = await handleCreateBranch(projectId, specId, undefined, undefined, {
+        mutateCheckout: false,
+    });
     if (result.isError === true) {
         /* v8 ignore next */
         const msg = result.content[0]?.type === 'text' ? result.content[0].text : 'branch creation failed';

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/outbox-worker.d.ts

@@ -18,12 +18,20 @@ export declare class TransactionalOutboxWorker {
         readonly clock?: () => Date;
         readonly limit?: number;
         readonly topics?: readonly string[];
+        readonly timeBudgetMs?: number;
     }): Promise<{
         readonly delivered: number;
+        readonly failed: number;
         readonly skipped: number;
+        readonly ineligible: number;
+        /** True when no eligible pending record remains in this scope right now. */
+        readonly exhausted: boolean;
     }>;
+    private attemptDelivery;
     private claim;
     private fail;
+    /** Deterministic exponential backoff with a validated cap; no random jitter. */
+    private computeNextAttemptAt;
     private complete;
     private deliveryKey;
     private fenceKey;

package/dist/engine/execution/outbox-worker.js

@@ -1,20 +1,32 @@
 import { createHash } from 'node:crypto';
 import { BoundaryFailure } from '../../errors/error-taxonomy.js';
+import { getRuntimePolicy } from '../runtime-policy.js';
 function parseFence(value) {
     if (!value || typeof value !== 'object') {
         return undefined;
     }
     const fence = value;
+    const nextAttemptAtValid = fence.nextAttemptAt === undefined ||
+        (typeof fence.nextAttemptAt === 'string' && Number.isFinite(Date.parse(fence.nextAttemptAt)));
     if (fence.schemaVersion !== 1 ||
         typeof fence.workerId !== 'string' ||
         !Number.isSafeInteger(fence.fencingToken) ||
         typeof fence.leaseExpiresAt !== 'string' ||
         typeof fence.state !== 'string' ||
-        !['leased', 'failed', 'dead-letter', 'delivered'].includes(fence.state)) {
+        !['leased', 'failed', 'dead-letter', 'delivered'].includes(fence.state) ||
+        !nextAttemptAtValid) {
         throw new BoundaryFailure('Corrupt', 'outbox fence read', 'Quarantine the invalid fence record before retrying delivery.');
     }
     return fence;
 }
+/**
+ * Upper bound on how many rows a single internal page fetch may request while
+ * paging past ineligible head records (foreign lease, delivered self-heal) that
+ * consume no record budget. 1000 is the existing hard ceiling `listOutbox`
+ * already enforces, so this reuses that ceiling rather than introducing a new
+ * tunable.
+ */
+const OUTBOX_PAGE_FETCH_LIMIT = 1_000;
 /**
  * Durable outbox dispatcher. The sink must deduplicate `deliveryKey`; this stable key closes the
  * unavoidable crash window between an external acknowledgement and the local delivered marker.
@@ -26,7 +38,7 @@ export class TransactionalOutboxWorker {
     workerId;
     leaseMs;
     maxAttempts;
-    constructor(database, projectId, workspaceId, workerId, leaseMs = 30_000, maxAttempts = 3) {
+    constructor(database, projectId, workspaceId, workerId, leaseMs = 30_000, maxAttempts = getRuntimePolicy().outbox.maxAttempts) {
         this.database = database;
         this.projectId = projectId;
         this.workspaceId = workspaceId;
@@ -46,38 +58,83 @@ export class TransactionalOutboxWorker {
     async drain(deliver, options = {}) {
         const clock = options.clock ?? (() => new Date());
         const now = currentIso(clock, options.now);
+        const policy = getRuntimePolicy().outbox;
+        const timeBudgetMs = options.timeBudgetMs ?? policy.sliceTimeBudgetMs;
+        const startedAtMs = clock().getTime();
+        let recordBudget = options.limit ?? policy.sliceRecordBudget;
         let delivered = 0;
-        let skipped = 0;
-        const pending = this.database.listOutbox(this.projectId, this.workspaceId, {
-            pendingOnly: true,
-            limit: options.limit,
-            topics: options.topics,
-        });
-        for (const message of pending) {
-            const fence = this.claim(message, now);
-            if (!fence) {
-                skipped += 1;
-                continue;
-            }
-            try {
-                await deliver({
-                    deliveryKey: this.deliveryKey(message),
-                    fencingToken: fence.fencingToken,
-                    topic: message.topic,
-                    payload: message.payload,
-                });
-            }
-            catch {
-                const failure = new BoundaryFailure('DependencyUnavailable', 'outbox delivery', 'Retry with the stable delivery key after the dependency recovers.');
-                this.fail(message, fence, failure, currentIso(clock, options.now));
-                throw failure;
+        let failed = 0;
+        let ineligible = 0;
+        let cursorId = 0;
+        let timedOut = false;
+        while (recordBudget > 0 && !timedOut) {
+            const batch = this.database.listOutbox(this.projectId, this.workspaceId, {
+                pendingOnly: true,
+                limit: OUTBOX_PAGE_FETCH_LIMIT,
+                topics: options.topics,
+                eligibleAt: now,
+                afterId: cursorId,
+            });
+            if (batch.length === 0) {
+                break;
             }
-            if (!this.complete(message, fence, currentIso(clock, options.now))) {
-                throw new BoundaryFailure('Conflict', 'outbox delivery commit', 'Another worker owns the lease; retry with the stable delivery key.');
+            for (const message of batch) {
+                // Admission check between deliveries: never aborts an in-flight delivery.
+                if (clock().getTime() - startedAtMs > timeBudgetMs) {
+                    timedOut = true;
+                    break;
+                }
+                cursorId = message.id;
+                const fence = this.claim(message, now);
+                if (!fence) {
+                    // Ineligible for a reason SQL cannot pre-filter (foreign unexpired lease,
+                    // self-healed delivered fence): consumes no record budget and does not
+                    // stop the worker from advancing to the next record in this same call.
+                    ineligible += 1;
+                    continue;
+                }
+                recordBudget -= 1;
+                const outcome = await this.attemptDelivery(message, fence, deliver, clock, options.now);
+                if (outcome.status === 'failed') {
+                    // Isolate the failure: continue offering remaining eligible records
+                    // instead of aborting the whole slice.
+                    failed += 1;
+                }
+                else {
+                    delivered += 1;
+                }
+                if (recordBudget === 0) {
+                    break;
+                }
             }
-            delivered += 1;
         }
-        return { delivered, skipped };
+        // Exact count of eligible work left unattempted (budget or time cutoff), not
+        // an estimate — this is what a further slice would find eligible right now.
+        const skipped = this.database.countEligibleOutbox(this.projectId, this.workspaceId, {
+            topics: options.topics,
+            eligibleAt: now,
+            afterId: cursorId,
+        });
+        return { delivered, failed, skipped, ineligible, exhausted: skipped === 0 };
+    }
+    async attemptDelivery(message, fence, deliver, clock, now) {
+        try {
+            await deliver({
+                deliveryKey: this.deliveryKey(message),
+                fencingToken: fence.fencingToken,
+                topic: message.topic,
+                payload: message.payload,
+            });
+        }
+        catch {
+            const failure = new BoundaryFailure('DependencyUnavailable', 'outbox delivery', 'Retry with the stable delivery key after the dependency recovers.');
+            this.fail(message, fence, failure, currentIso(clock, now));
+            return { status: 'failed' };
+        }
+        if (!this.complete(message, fence, currentIso(clock, now))) {
+            throw new BoundaryFailure('Conflict', 'outbox delivery commit', 'Another worker owns the lease; retry with the stable delivery key.');
+        }
+        return { status: 'delivered' };
     }
     claim(message, now) {
         return this.database.transaction(() => {
@@ -93,6 +150,12 @@ export class TransactionalOutboxWorker {
             if (existing?.state === 'leased' && existing.leaseExpiresAt > now) {
                 return undefined;
             }
+            if (existing?.state === 'failed' &&
+                existing.nextAttemptAt !== undefined &&
+                existing.nextAttemptAt > now) {
+                // Durable retry deadline not yet reached: not eligible, attempts unchanged.
+                return undefined;
+            }
             const fence = {
                 schemaVersion: 1,
                 workerId: this.workerId,
@@ -126,6 +189,7 @@ export class TransactionalOutboxWorker {
                 return false;
             }
             const attempts = current.attempts ?? 1;
+            const deadLettered = attempts >= this.maxAttempts;
             this.database.putRecord({
                 projectId: this.projectId,
                 workspaceId: this.workspaceId,
@@ -133,8 +197,9 @@ export class TransactionalOutboxWorker {
                 key,
                 value: {
                     ...current,
-                    state: attempts >= this.maxAttempts ? 'dead-letter' : 'failed',
+                    state: deadLettered ? 'dead-letter' : 'failed',
                     leaseExpiresAt: now,
+                    ...(deadLettered ? {} : { nextAttemptAt: this.computeNextAttemptAt(now, attempts) }),
                     lastError: error instanceof BoundaryFailure
                         ? error.message
                         : new BoundaryFailure('Internal', 'outbox failure recording', 'Inspect local diagnostics and retry safely.').message,
@@ -144,6 +209,12 @@ export class TransactionalOutboxWorker {
             return true;
         });
     }
+    /** Deterministic exponential backoff with a validated cap; no random jitter. */
+    computeNextAttemptAt(now, attempts) {
+        const policy = getRuntimePolicy().outbox;
+        const delayMs = Math.min(policy.backoffBaseMs * 2 ** (attempts - 1), policy.backoffCapMs);
+        return new Date(Date.parse(now) + delayMs).toISOString();
+    }
     complete(message, fence, now) {
         return this.database.transaction(() => {
             const key = this.fenceKey(message.id);

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;