@planu/cli 4.13.0 → 4.14.1

package/dist/tools/update-status/index.js

@@ -2,22 +2,22 @@ import { elicitOrFallback, buildEnumSchema } from '../../engine/elicitation/elic
 import { ti } from '../../i18n/index.js';
 import { AutopilotSummaryCollector } from '../../engine/autopilot/summary-collector.js';
 import { specStore, knowledgeStore } from '../../storage/index.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { rollbackTransitionSpec, transitionSpec, } from '../../engine/spec-state-machine/transition-spec.js';
 import { calculateAccuracy } from '../../engine/estimator.js';
 import { cascadeCheck } from '../../engine/spec-versioner.js';
 import { runComplianceGates } from '../update-status-convention-gate.js';
 import { runDoneActions, runDoneSideEffects, runImplementingActions, runImplementingSideEffects, } from '../update-status-actions.js';
 import { compactObj } from '../../engine/compact-obj.js';
-import { checkTransition, checkDorGate, checkAmbiguityGate, checkReadinessGate, checkChallengeGate, resolveAutoAdvanceSteps, isReverseTransition, validateReverseTransition, } from './transition-guard.js';
+import { checkTransition, checkDorGate, checkAmbiguityGate, checkReadinessGate, checkChallengeGate, checkImplementationDependencyGate, resolveAutoAdvanceSteps, isReverseTransition, validateReverseTransition, } from './transition-guard.js';
 import { checkApprovedDepGate } from '../../engine/dep-guard/index.js';
 import { checkApprovalGate } from '../../engine/approval-workflow.js';
 import * as approvalStore from '../../storage/approval-store.js';
 import { withApprovalSpecLock } from '../../storage/approval-operation-lock.js';
 import { isLocked, getLock } from '../../storage/spec-lock-store.js';
-import { runValidateGate, checkDoneGates, checkComplianceGate, checkQaGate, checkApprovedFormatGate, readApprovedValidationReportGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
-import { writeImplementationReviewReport } from '../../engine/validator/validation-report-writer.js';
+import { checkDoneGates, checkComplianceGate, checkApprovedFormatGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
 import { checkLifecycleEvidenceTransitionGate } from './evidence-gate.js';
-import { buildStatusResponse, buildValidateBlockedResponse, buildDryRunResponse, } from './response-builder.js';
+import { buildStatusResponse, buildDryRunResponse } from './response-builder.js';
 import { recordDoneMetrics, syncSpecFiles, tryReconcile, recordTerminalTransitionEvent, } from './file-sync.js';
 import { appendEntry, getLastHash } from '../../storage/audit-trail-store.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
@@ -28,10 +28,7 @@ import { recordForceUsage } from '../../storage/force-analytics-store.js';
 import { maybeSafePushOnDone, queuePostCommitTasks, runCascadeForResponse, } from './side-effects.js';
 import { formatKeyValue } from '../output-formatter.js';
 import { checkCodeReality } from '../../engine/code-scanner/index.js';
-import { scanCrashRisks } from '../../engine/crash-shield/index.js';
-import { shouldSkipCrashScan, recordCrashScanRun, } from '../../engine/autopilot/crash-shield-rate-limiter.js';
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { join } from 'node:path';
 import { trackCost } from '../../engine/cost-tracking/operation-tracker.js';
 import { resolveProjectIdOrAutoDetect } from '../resolve-project-id.js';
 import { withToolTimeout } from '../safe-handler.js';
@@ -39,7 +36,10 @@ import { detectHost } from '../../engine/host-detection/detect-host.js';
 import { shellHygieneReminder } from '../../hosts/claude-code/coach.js';
 import { buildTransitionEvidenceMeta, checkSddModelRoutingGate, } from '../../engine/sdd-model-routing.js';
 import { acquireLock, releaseLock, isLocked as isCrossProcessLocked, LockBusyError, } from '../../engine/safety/cross-process-lock.js';
-import { validateStrictLayoutOrError } from '../validate-helpers.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { assertExecutionCanCommit } from '../../engine/execution/context.js';
+import { shouldSkipGateForExplicitLegacyHarness } from './gate-harness.js';
+import { assertValidationFreshnessBarrier, } from '../../engine/validation/validation-freshness.js';
 /**
  * SPEC-280: Silently traverse intermediate states so callers can jump forward
  * (e.g. draft → approved) without receiving an error.
@@ -141,9 +141,8 @@ async function createVersionSnapshot(specId, projectId, tag) {
     if (!spec) {
         return;
     }
-    const snapshotPath = join('data', 'projects', projectId, 'version-snapshots', `${tag}.json`);
-    await mkdir(dirname(snapshotPath), { recursive: true });
-    await writeFile(snapshotPath, JSON.stringify(spec, null, 2), 'utf-8');
+    const snapshotPath = join(projectDataDir(projectId), 'version-snapshots', `${tag}.json`);
+    await atomicWriteFile(snapshotPath, `${JSON.stringify(spec, null, 2)}\n`);
 }
 function checkIdempotentOrTransition(projectId, spec, target) {
     if (spec.status === target) {
@@ -361,7 +360,10 @@ async function recoverPendingPostCommitTasks(projectId, projectPath) {
             }
         }
         finally {
-            await releaseLock(recoveryLock).catch(() => undefined);
+            await releaseLock(recoveryLock).catch((error) => {
+                /* reliability-cleanup: RECOVERY_LOCK_RELEASE — lease expiry remains the recovery boundary */
+                reportClassifiedDegradation('RECOVERY_LOCK_RELEASE', error);
+            });
         }
     }
 }
@@ -405,15 +407,106 @@ function buildPersistenceFailureResponse(args) {
         },
     };
 }
-/** SPEC-628: Check crash scan rate-limit and return skip reason if within window. */
-async function checkCrashScanRateLimit(newStatus, effectiveGatePath) {
-    if (newStatus !== 'done' || !effectiveGatePath) {
-        return null;
-    }
-    const skipCheck = await shouldSkipCrashScan(effectiveGatePath).catch(() => ({
-        skip: false,
-    }));
-    return skipCheck.skip ? (skipCheck.reason ?? 'recently scanned') : null;
+async function commitTransitionWithNarrowLock(args) {
+    return withApprovalSpecLock(args.projectPath, args.specId, async () => {
+        const lock = await acquireLock(args.projectPath, args.specId, {
+            reason: `update_status(${args.newStatus}) commit`,
+        });
+        if (lock === null) {
+            return {
+                ok: false,
+                error: {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Spec ${args.specId} is locked by another process (cross-process lock). Retry later.`,
+                        },
+                    ],
+                    isError: true,
+                },
+            };
+        }
+        try {
+            const freshSpec = typeof specStore.getSpecFresh === 'function'
+                ? await specStore.getSpecFresh(args.projectId, args.specId)
+                : await specStore.getSpec(args.projectId, args.specId);
+            if (freshSpec?.status !== args.expectedSpec.status ||
+                freshSpec.updatedAt !== args.expectedSpec.updatedAt) {
+                return {
+                    ok: false,
+                    error: {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Spec ${args.specId} changed while lifecycle gates were running. Retry with the fresh state.`,
+                            },
+                        ],
+                        isError: true,
+                        structuredContent: { error: 'TRANSITION_CONFLICT', code: 409 },
+                    },
+                };
+            }
+            if (args.newStatus === 'done' &&
+                (!args.freshnessLease || !(await assertValidationFreshnessBarrier(args.freshnessLease))) &&
+                !shouldSkipGateForExplicitLegacyHarness('evidence')) {
+                return {
+                    ok: false,
+                    error: {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Validation inputs for ${args.specId} changed before commit. Re-run validate.`,
+                            },
+                        ],
+                        isError: true,
+                        structuredContent: { error: 'VALIDATION_RECEIPT_STALE', code: 409 },
+                    },
+                };
+            }
+            assertExecutionCanCommit();
+            const transitionRecord = await transitionSpec(args.projectId, args.specId, args.newStatus, {
+                ...args.options,
+                expectedSpec: freshSpec,
+            });
+            const updatedSpec = transitionRecord.spec;
+            const syncResult = await syncSpecFiles(updatedSpec, args.originalStatus, args.newStatus, args.projectPath);
+            if (!syncResult.warning) {
+                return { ok: true, transitionRecord, updatedSpec };
+            }
+            try {
+                await rollbackTransitionSpec(transitionRecord);
+                return {
+                    ok: false,
+                    error: buildPersistenceFailureResponse({
+                        specId: args.specId,
+                        previousStatus: args.originalStatus,
+                        newStatus: args.newStatus,
+                        reason: syncResult.warning.reason,
+                        recoveryRequired: false,
+                    }),
+                };
+            }
+            catch (rollbackError) {
+                return {
+                    ok: false,
+                    error: buildPersistenceFailureResponse({
+                        specId: args.specId,
+                        previousStatus: args.originalStatus,
+                        newStatus: args.newStatus,
+                        reason: `${syncResult.warning.reason}; compensation failed: ` +
+                            (rollbackError instanceof Error ? rollbackError.message : String(rollbackError)),
+                        recoveryRequired: true,
+                    }),
+                };
+            }
+        }
+        finally {
+            await releaseLock(lock).catch((error) => {
+                /* reliability-cleanup: UPDATE_STATUS_LOCK_RELEASE — lease expiry remains the recovery boundary */
+                reportClassifiedDegradation('UPDATE_STATUS_LOCK_RELEASE', error);
+            });
+        }
+    });
 }
 /** Build fallback interactiveQuestion for status confirmation (SPEC-595). */
 function buildStatusConfirmFallback(specId, newStatus) {
@@ -468,20 +561,15 @@ async function resolveOrchestrationPlan(newStatus, specScope, specId, projectPat
     }
     return withToolTimeout(import('../orchestrate-agents-handler.js')
         .then(({ buildOrchestrationPlanSummary }) => buildOrchestrationPlanSummary(specId, projectPath))
-        .catch(() => null), 5_000, null);
-}
-function shouldSkipSddRoutingGateForLegacyTestHarness() {
-    return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_SDD_GATES !== 'true';
-}
-function shouldSkipEvidenceGateForLegacyTestHarness() {
-    return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_EVIDENCE_GATES !== 'true';
-}
-function shouldSkipStrictLayoutGateForLegacyTestHarness() {
-    return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_LAYOUT_GATE !== 'true';
+        .catch((error) => {
+        // reliability-optional: ORCHESTRATION_PLAN_SUMMARY — summary enrichment is non-authoritative
+        reportClassifiedDegradation('ORCHESTRATION_PLAN_SUMMARY', error);
+        return null;
+    }), 5_000, null);
 }
 /* eslint-disable complexity, max-lines-per-function */
 export async function handleUpdateStatus(params, server) {
-    return trackCost(params.projectPath ?? '', 'update_status', async () => {
+    return trackCost(params.projectPath?.trim() ?? '', 'update_status', async () => {
         const { specId, status: newStatus, actuals, reviewNotes } = params;
         // SPEC-509: auto-detect project from git root when projectPath/projectId are omitted
         const resolved = await resolveProjectIdOrAutoDetect({
@@ -498,50 +586,33 @@ export async function handleUpdateStatus(params, server) {
                 const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
                 await runStrictPlanuCleanup(effectiveProjectPath);
             }
-            catch {
-                /* strict cleanup is best-effort here; validate fails closed if artifacts remain */
+            catch (error) {
+                /* reliability-cleanup: PRE_TRANSITION_STRICT_CLEANUP — validate remains fail-closed */
+                reportClassifiedDegradation('PRE_TRANSITION_STRICT_CLEANUP', error);
             }
         }
         await recoverPendingPostCommitTasks(projectId, effectiveProjectPath).catch((error) => {
-            console.warn('[planu:post-commit] automatic recovery scan failed', {
-                projectId,
-                error: error instanceof Error ? error.message : String(error),
-            });
+            /* reliability-optional: POST_COMMIT_RECOVERY_SCAN — durable tasks remain retryable */
+            reportClassifiedDegradation('POST_COMMIT_RECOVERY_SCAN', error);
         });
-        return withApprovalSpecLock(effectiveProjectPath, specId, async () => {
+        return (async () => {
             try {
                 // SPEC-301: Reject status changes when spec is locked by another holder (legacy manual lock)
                 const lockError = await checkSpecLockGate(effectiveProjectPath, specId);
                 if (lockError) {
                     return lockError;
                 }
-                // SPEC-731: dry_run never acquires the cross-process lock.
-                // SPEC-719: Cross-process disk lock — acquire before any spec.md mutation.
-                // Released in finally below. Best-effort when no projectPath is available.
+                // Dry-run checks availability without acquiring. Real mutations acquire only
+                // around the compare-and-swap plus spec/store commit below.
                 const isDryRun = params.dry_run === true;
-                let crossProcessLockHandle = null;
-                if (!isDryRun) {
-                    crossProcessLockHandle = await acquireLock(effectiveProjectPath, specId, {
-                        reason: `update_status(${newStatus})`,
-                    });
-                    if (crossProcessLockHandle === null) {
-                        // acquireLock returns null only when another live session holds the lock
-                        // For dry_run, return a special response indicating lock is busy
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: `Spec ${specId} is locked by another process (cross-process lock). Retry later or inspect data/.locks/planu/${specId}.lock`,
-                                },
-                            ],
-                            isError: true,
-                        };
-                    }
-                }
-                else {
+                if (isDryRun) {
                     // SPEC-731: dry_run checks lock availability without acquiring it.
                     // isLocked returns null when no lockfile exists (available), or a LockInfo when locked.
-                    const lockInfo = await isCrossProcessLocked(effectiveProjectPath, specId).catch(() => null);
+                    const lockInfo = await isCrossProcessLocked(effectiveProjectPath, specId).catch((error) => {
+                        // reliability-optional: DRY_RUN_LOCK_PROBE — null conservatively avoids stale lock claims
+                        reportClassifiedDegradation('DRY_RUN_LOCK_PROBE', error);
+                        return null;
+                    });
                     const lockIsBusy = lockInfo !== null && !lockInfo.stale;
                     if (lockIsBusy) {
                         // Lock is busy — return dry_run result indicating this without blocking
@@ -562,11 +633,9 @@ export async function handleUpdateStatus(params, server) {
                     }
                 }
                 try {
-                    // Reload only after the per-spec lock is held. This snapshot is the sole
-                    // input for gates, transition persistence, and rollback compensation.
-                    const spec = crossProcessLockHandle !== null && typeof specStore.getSpecFresh === 'function'
-                        ? await specStore.getSpecFresh(projectId, specId)
-                        : await specStore.getSpec(projectId, specId);
+                    // Gates consume an unlocked snapshot. Commit revalidates this snapshot
+                    // under the narrow mutation lock before compare-and-swap.
+                    const spec = await specStore.getSpec(projectId, specId);
                     if (!spec) {
                         return {
                             content: [{ type: 'text', text: ti('spec.notFound', { id: specId }) }],
@@ -672,9 +741,12 @@ export async function handleUpdateStatus(params, server) {
                     }
                     // SPEC-728: DepGuard — block 'approved' if spec participates in a dependency cycle
                     let depGuardResult = null;
+                    let allSpecsForDependencyGate = null;
+                    if (plannedStatuses.includes('approved') || plannedStatuses.includes('implementing')) {
+                        allSpecsForDependencyGate = await specStore.listSpecs(projectId);
+                    }
                     if (plannedStatuses.includes('approved')) {
-                        const allSpecsForDepGuard = await specStore.listSpecs(projectId);
-                        depGuardResult = checkApprovedDepGate(spec, allSpecsForDepGuard);
+                        depGuardResult = checkApprovedDepGate(spec, allSpecsForDependencyGate ?? []);
                         if (depGuardResult.blocked) {
                             return {
                                 content: [{ type: 'text', text: `DepGuard blocked: ${depGuardResult.narrative}` }],
@@ -689,6 +761,12 @@ export async function handleUpdateStatus(params, server) {
                             };
                         }
                     }
+                    if (plannedStatuses.includes('implementing')) {
+                        const dependencyGate = checkImplementationDependencyGate(spec, allSpecsForDependencyGate ?? [], 'implementing');
+                        if (dependencyGate) {
+                            return dependencyGate;
+                        }
+                    }
                     // SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
                     const challengeGateStatus = plannedStatuses.includes('review') ? 'review' : newStatus;
                     const challengeGate = checkChallengeGate(spec, challengeGateStatus);
@@ -709,14 +787,14 @@ export async function handleUpdateStatus(params, server) {
                     // Load knowledge for project path (needed for DoD gates, validate trigger and HTML regen)
                     const knowledge = await knowledgeStore.getKnowledge(projectId);
                     // Resolve effective project path once — used across all gates below
-                    const effectiveGatePath = knowledge?.projectPath ?? params.projectPath;
+                    const effectiveGatePath = knowledge?.projectPath ?? effectiveProjectPath;
                     // SPEC-1044: SDD model-routing + context continuity hard gate.
                     const sddRoutingGate = {
                         blockResult: null,
                         gateResults: { sddModelRouting: 'skip' },
                         forcedReasons: [],
                     };
-                    if (!shouldSkipSddRoutingGateForLegacyTestHarness()) {
+                    if (!shouldSkipGateForExplicitLegacyHarness('routing')) {
                         const routedStatuses = plannedStatuses.filter((status) => status === 'approved' || status === 'implementing' || status === 'done');
                         for (const status of routedStatuses) {
                             const gate = await checkSddModelRoutingGate({
@@ -737,7 +815,7 @@ export async function handleUpdateStatus(params, server) {
                     // SPEC-1054: BDD/SDD evidence gates. Non-trivial specs must carry
                     // Discovery before approval, task-plan before implementation, and
                     // traceability/contract evidence before done.
-                    if (!shouldSkipEvidenceGateForLegacyTestHarness()) {
+                    if (!shouldSkipGateForExplicitLegacyHarness('evidence')) {
                         const evidenceStatuses = plannedStatuses.filter((status) => status === 'approved' || status === 'implementing' || status === 'done');
                         for (const transition of evidenceStatuses) {
                             const evidenceGate = await checkLifecycleEvidenceTransitionGate({
@@ -757,24 +835,22 @@ export async function handleUpdateStatus(params, server) {
                     // SPEC-441: Code reality check before transitioning to 'implementing'
                     // SPEC-335: DoD + security gates before transitioning to 'done'
                     // ---------------------------------------------------------------------------
-                    // SPEC-642: QA gate — block done if typecheck + test:coverage have not passed
-                    // ---------------------------------------------------------------------------
-                    if (newStatus === 'done') {
-                        const qaGateResult = await checkQaGate(spec, effectiveGatePath, params.force ?? false);
-                        if (qaGateResult !== null) {
-                            return qaGateResult;
-                        }
-                    }
-                    // ---------------------------------------------------------------------------
+                    // `done` consumes the immutable validation receipt below. Validation, QA,
+                    // security and repository scans belong to the durable validation worker.
                     let codeRealityWarning = null;
                     let forcedBypassWarning = null;
+                    let doneFreshnessLease;
                     const [codeRealityResult, doneGatesResult] = await Promise.all([
                         // Code reality: only relevant for 'implementing'
                         newStatus === 'implementing' && !reverseTransition && effectiveGatePath
-                            ? checkCodeReality(effectiveGatePath, spec.title).catch(() => null)
+                            ? checkCodeReality(effectiveGatePath, spec.title).catch((error) => {
+                                // reliability-optional: CODE_REALITY_ENRICHMENT — downstream evidence gates remain binding
+                                reportClassifiedDegradation('CODE_REALITY_ENRICHMENT', error);
+                                return null;
+                            })
                             : Promise.resolve(null),
                         // Done gates: only relevant for 'done'
-                        newStatus === 'done'
+                        newStatus === 'done' && !shouldSkipGateForExplicitLegacyHarness('evidence')
                             ? checkDoneGates(spec, specId, projectId, effectiveGatePath, params.force, params.forceStatusReason ?? params.reason ?? 'No force reason provided')
                             : Promise.resolve(null),
                     ]);
@@ -788,89 +864,24 @@ export async function handleUpdateStatus(params, server) {
                             return doneGatesResult.blocked;
                         }
                         forcedBypassWarning = doneGatesResult.forcedBypassWarning;
+                        doneFreshnessLease = doneGatesResult.freshnessLease ?? undefined;
                     }
                     // ---------------------------------------------------------------------------
-                    // BATCH B (parallel): validate + crash-shield + compliance — independent of
-                    // each other, all need spec/projectPath (available from Batch A outputs)
-                    // SPEC-222: Auto-validate before marking done
-                    // SPEC-442: Crash Shield warning on 'done'
-                    // SPEC-447: Compliance gate on 'review' or 'implementing'
+                    // Review-only heuristic compliance. `done` must remain an O(1) receipt
+                    // consumer and therefore must not execute commands or scan the repository.
                     // ---------------------------------------------------------------------------
-                    let validateScore = null;
-                    let validateScoreSource = null;
-                    let crashShieldWarning = null;
-                    let crashShieldSkipReason = null;
+                    const validateScore = null;
+                    const validateScoreSource = null;
+                    const crashShieldWarning = null;
                     let complianceGateResult = null;
-                    let validationReportGate = null;
-                    // SPEC-628: Rate-limit crash scan — check before entering the parallel batch
-                    crashShieldSkipReason = await checkCrashScanRateLimit(newStatus, effectiveGatePath ?? null);
-                    const [validateGateResult, crashRisksReport, complianceResult] = await Promise.all([
-                        // Validate: only on 'done'.
-                        // SPEC-721: timeout lives inside runValidateGate (Promise.race) — do NOT wrap with
-                        // withToolTimeout here, which would silently convert timeout into blocked:false (fail-open).
-                        newStatus === 'done'
-                            ? runValidateGate(spec, effectiveGatePath ?? '', params.forceStatus ?? false, params.forceStatusReason, 9_000, { projectId, specId })
-                            : Promise.resolve(null),
-                        // Crash shield: only on 'done', skipped if rate-limited (SPEC-628)
-                        newStatus === 'done' && effectiveGatePath && !crashShieldSkipReason
-                            ? withToolTimeout(scanCrashRisks(effectiveGatePath).catch(() => null), 9_000, null)
-                            : Promise.resolve(null),
-                        // The heuristic scorer is a review aid. Done relies on the authoritative validate report.
-                        plannedStatuses.includes('review')
-                            ? withToolTimeout(checkComplianceGate(specId, projectId, effectiveGatePath), 9_000, {
-                                skipped: true,
-                                blocked: false,
-                                score: null,
-                                issues: [],
-                            })
-                            : Promise.resolve(null),
-                    ]);
-                    // Process validate result — may block (SPEC-721: fail-closed)
-                    let forcedValidateBypass = null;
-                    if (validateGateResult !== null) {
-                        if (validateGateResult.blocked) {
-                            return buildValidateBlockedResponse(specId, validateGateResult);
-                        }
-                        validateScore = validateGateResult.score;
-                        if (validateGateResult.forced) {
-                            validateScoreSource = validateGateResult.scoreSource;
-                            forcedValidateBypass = {
-                                reason: validateGateResult.forcedReason,
-                                observedScore: validateGateResult.score,
-                            };
-                        }
-                        else {
-                            validateScoreSource = 'validateSpec';
-                        }
-                    }
-                    if (newStatus === 'done' &&
-                        effectiveGatePath &&
-                        !shouldSkipStrictLayoutGateForLegacyTestHarness()) {
-                        const strictLayoutError = await validateStrictLayoutOrError({
-                            projectPath: effectiveGatePath,
-                            specId,
-                            specPath: spec.specPath,
-                            failClosedOnCrash: true,
-                        });
-                        if (strictLayoutError) {
-                            return strictLayoutError;
-                        }
-                    }
-                    // Process crash shield result — record run timestamp on success (SPEC-628)
-                    /* c8 ignore next */
-                    if (crashRisksReport !== null) {
-                        if (crashRisksReport.score < 80) {
-                            const criticalCount = crashRisksReport.risks.filter((r) => r.severity === 'CRITICAL').length;
-                            crashShieldWarning =
-                                `Crash Shield: score ${String(crashRisksReport.score)}/100 — ${String(criticalCount)} critical risk(s) detected. ` +
-                                    `Run \`scan_crash_risks\` for details.`;
-                        }
-                        if (effectiveGatePath) {
-                            void recordCrashScanRun(effectiveGatePath).catch(() => {
-                                /* best-effort */
-                            });
-                        }
-                    }
+                    const complianceResult = plannedStatuses.includes('review')
+                        ? await withToolTimeout(checkComplianceGate(specId, projectId, effectiveGatePath), 9_000, {
+                            skipped: true,
+                            blocked: false,
+                            score: null,
+                            issues: [],
+                        })
+                        : null;
                     // Process compliance gate result — may block on 'review'
                     if (complianceResult !== null) {
                         complianceGateResult = complianceResult;
@@ -878,10 +889,9 @@ export async function handleUpdateStatus(params, server) {
                             return buildBlockedByComplianceResponse(specId, complianceResult);
                         }
                     }
-                    // SPEC-190: Run all compliance gates in parallel (convention + constitution + compile + lint + test, non-blocking)
-                    // runComplianceGates internally skips heavy commands (compile/lint/test) for non-done transitions,
-                    // but 'approved' still needs constitutionWarnings — so run for 'done' and 'approved' only.
-                    const { conventionWarnings, constitutionWarnings, compileWarnings, lintWarnings, testWarnings, } = newStatus === 'done' || plannedStatuses.includes('approved')
+                    // Approved still needs constitution warnings. Done relies exclusively on
+                    // the validation receipt and never invokes this legacy command runner.
+                    const { conventionWarnings, constitutionWarnings, compileWarnings, lintWarnings, testWarnings, } = plannedStatuses.includes('approved')
                         ? await runComplianceGates(projectId, spec.title, spec.tags, newStatus, specId)
                         : {
                             conventionWarnings: [],
@@ -890,38 +900,13 @@ export async function handleUpdateStatus(params, server) {
                             lintWarnings: [],
                             testWarnings: [],
                         };
-                    if (newStatus === 'done' && !(params.force ?? params.forceStatus ?? false)) {
-                        if (!isDryRun && effectiveGatePath) {
-                            await writeImplementationReviewReport({
-                                projectId,
-                                specId,
-                                spec,
-                                projectPath: effectiveGatePath,
-                                score: validateScore,
-                                lintPassed: lintWarnings.length === 0,
-                                conventionRegression: conventionWarnings.length > 0,
-                            });
-                        }
-                        validationReportGate = await readApprovedValidationReportGate(specId, projectId, false);
-                        if (!validationReportGate.ok) {
-                            return validationReportGate.error;
-                        }
-                        if (validationReportGate.score !== null) {
-                            validateScore = validationReportGate.score;
-                            validateScoreSource = 'validation-report';
-                        }
-                    }
                     // SPEC-731: dry_run short-circuit — all gates have been evaluated above.
                     // Do NOT call transitionSpec, appendTransitionEvent, or acquire any lock.
                     if (isDryRun) {
                         const dryRunGates = {
                             dod: newStatus === 'done' ? (doneGatesResult?.blocked ? 'fail' : 'pass') : 'skip',
-                            validate: newStatus === 'done'
-                                ? validateGateResult === null
-                                    ? 'skip'
-                                    : 'pass' // blocked case already returned above (line 615)
-                                : 'skip',
-                            qa: newStatus === 'done' ? 'pass' : 'skip', // QA gate runs above — if we reach here, it passed
+                            validate: newStatus === 'done' ? 'pass' : 'skip',
+                            qa: newStatus === 'done' ? 'pass' : 'skip',
                             security: newStatus === 'done' ? (doneGatesResult?.blocked ? 'fail' : 'pass') : 'skip',
                             lock: 'available',
                             compliance: complianceGateResult === null
@@ -987,39 +972,7 @@ export async function handleUpdateStatus(params, server) {
                     if (resolvedActuals) {
                         nonStatusUpdates.actuals = resolvedActuals;
                     }
-                    // SPEC-721: Audit-trail entry when forceStatus bypassed the validate gate
-                    let forceStatusAuditId = null;
-                    if (newStatus === 'done' && forcedValidateBypass !== null) {
-                        try {
-                            const auditId = uuid();
-                            const prevHash = getLastHash();
-                            // Hash this entry minimally — full chain hashing is handled by the audit engine on export
-                            const entry = {
-                                id: auditId,
-                                timestamp: new Date().toISOString(),
-                                toolName: 'update_status',
-                                inputSummary: `validate_gate_forced_bypass specId=${specId} score=${String(forcedValidateBypass.observedScore)} reason="${forcedValidateBypass.reason.slice(0, 80)}"`,
-                                outputType: 'success',
-                                durationMs: 0,
-                                specId,
-                                projectPath: effectiveGatePath ?? undefined,
-                                prevHash,
-                                hash: '',
-                                event: 'validate_gate_forced_bypass',
-                                details: {
-                                    reason: forcedValidateBypass.reason,
-                                    observedScore: forcedValidateBypass.observedScore,
-                                    fromStatus: originalStatus,
-                                    toStatus: newStatus,
-                                },
-                            };
-                            appendEntry(entry);
-                            forceStatusAuditId = auditId;
-                        }
-                        catch {
-                            /* best-effort — audit must never block transition */
-                        }
-                    }
+                    const forceStatusAuditId = null;
                     // SPEC-780: Audit-trail entry when forceApprove bypassed readiness/format gates
                     let forceApproveAuditId = null;
                     if (newStatus === 'approved' && params.forceApprove) {
@@ -1042,7 +995,7 @@ export async function handleUpdateStatus(params, server) {
                                     outputType: 'success',
                                     durationMs: 0,
                                     specId,
-                                    projectPath: effectiveGatePath ?? undefined,
+                                    projectPath: effectiveGatePath,
                                     prevHash,
                                     hash: '',
                                     event: 'approve_gate_forced_bypass',
@@ -1059,8 +1012,9 @@ export async function handleUpdateStatus(params, server) {
                                 appendEntry(entry);
                                 forceApproveAuditId = auditId;
                             }
-                            catch {
-                                /* best-effort — audit must never block transition */
+                            catch (error) {
+                                /* reliability-optional: FORCE_APPROVAL_AUDIT — transition receipt remains authoritative */
+                                reportClassifiedDegradation('FORCE_APPROVAL_AUDIT', error);
                             }
                         }
                     }
@@ -1078,7 +1032,7 @@ export async function handleUpdateStatus(params, server) {
                                 outputType: 'success',
                                 durationMs: 0,
                                 specId,
-                                projectPath: effectiveGatePath ?? undefined,
+                                projectPath: effectiveGatePath,
                                 prevHash,
                                 hash: '',
                                 event: 'sdd_model_routing_forced_bypass',
@@ -1093,8 +1047,9 @@ export async function handleUpdateStatus(params, server) {
                             appendEntry(entry);
                             sddRoutingAuditId = auditId;
                         }
-                        catch {
-                            /* best-effort — audit must never block transition */
+                        catch (error) {
+                            /* reliability-optional: SDD_ROUTING_AUDIT — transition receipt remains authoritative */
+                            reportClassifiedDegradation('SDD_ROUTING_AUDIT', error);
                         }
                     }
                     // SPEC-969: Track forceStatus / forceApprove usage
@@ -1115,8 +1070,9 @@ export async function handleUpdateStatus(params, server) {
                                         `Consider re-running validate within 24h.`;
                             }
                         }
-                        catch {
-                            /* best-effort — analytics must never block transition */
+                        catch (error) {
+                            /* reliability-optional: BYPASS_ANALYTICS — lifecycle gates remain authoritative */
+                            reportClassifiedDegradation('BYPASS_ANALYTICS', error);
                         }
                     }
                     const versionSnapshotTag = newStatus === 'approved'
@@ -1133,45 +1089,32 @@ export async function handleUpdateStatus(params, server) {
                         hasProjectPath: Boolean(effectiveGatePath),
                         shouldAutoStage,
                     });
-                    // Commit status and non-status fields in one store mutation, then pair it
-                    // with an atomic spec.md write while the per-spec lock is still held.
-                    const transitionRecord = await transitionSpec(projectId, specId, newStatus, {
-                        trigger: trigger,
-                        actor,
-                        viaSync,
-                        reason: params.reason,
-                        updates: nonStatusUpdates,
-                        pendingBackgroundActions: plannedBackgroundActions,
+                    const persistence = await commitTransitionWithNarrowLock({
+                        projectPath: effectiveProjectPath || projectId,
+                        projectId,
+                        specId,
+                        newStatus,
+                        originalStatus,
                         expectedSpec: spec,
+                        options: {
+                            trigger: trigger,
+                            actor,
+                            viaSync,
+                            reason: params.reason,
+                            updates: nonStatusUpdates,
+                            pendingBackgroundActions: plannedBackgroundActions,
+                            expectedSpec: spec,
+                        },
+                        ...(doneFreshnessLease ? { freshnessLease: doneFreshnessLease } : {}),
                     });
-                    const updatedSpec = transitionRecord.spec;
-                    const syncResult = await syncSpecFiles(updatedSpec, originalStatus, newStatus, effectiveGatePath);
-                    if (syncResult.warning) {
-                        try {
-                            await rollbackTransitionSpec(transitionRecord);
-                            return buildPersistenceFailureResponse({
-                                specId,
-                                previousStatus: originalStatus,
-                                newStatus,
-                                reason: syncResult.warning.reason,
-                                recoveryRequired: false,
-                            });
-                        }
-                        catch (rollbackError) {
-                            return buildPersistenceFailureResponse({
-                                specId,
-                                previousStatus: originalStatus,
-                                newStatus,
-                                reason: `${syncResult.warning.reason}; compensation failed: ` +
-                                    (rollbackError instanceof Error ? rollbackError.message : String(rollbackError)),
-                                recoveryRequired: true,
-                            });
-                        }
+                    if (!persistence.ok) {
+                        return persistence.error;
                     }
+                    const { transitionRecord, updatedSpec } = persistence;
                     const frontmatterSyncWarnings = [];
                     const transitionId = transitionRecord.transitionId;
                     const committedAt = transitionRecord.timestamp;
-                    void appendTransitionEvent({
+                    await appendTransitionEvent({
                         projectId,
                         specId,
                         eventType: 'transition',
@@ -1183,11 +1126,12 @@ export async function handleUpdateStatus(params, server) {
                         modelId: params.modelId,
                         gateResults: sddRoutingGate.gateResults,
                         meta: { ...transitionEvidenceMeta, transitionId, committedAt },
-                    }).catch(() => {
-                        /* best-effort — never block the committed acknowledgement */
+                    }).catch((error) => {
+                        /* reliability-optional: SDD_ROUTING_REPORT — never block committed acknowledgement */
+                        reportClassifiedDegradation('SDD_ROUTING_REPORT', error);
                     });
                     if (reverseTransition && params.reason) {
-                        void appendTransitionEvent({
+                        await appendTransitionEvent({
                             projectId,
                             specId,
                             eventType: 'reopen',
@@ -1197,18 +1141,8 @@ export async function handleUpdateStatus(params, server) {
                             reason: params.reason,
                             meta: { transitionId, committedAt },
                         }).catch((err) => {
-                            console.warn('[planu:transition] reopen_event_append_failed', {
-                                specId,
-                                error: err instanceof Error ? err.message : String(err),
-                            });
-                        });
-                    }
-                    // SPEC-1044: Keep the reconstructible context packet fresh on every phase change.
-                    if (effectiveGatePath) {
-                        void import('../../engine/session-context-generator.js')
-                            .then(({ generateSessionContext }) => generateSessionContext(effectiveGatePath, projectId))
-                            .catch(() => {
-                            /* best-effort — context gate blocks later phases if this cannot be reconstructed */
+                            /* reliability-optional: REOPEN_EVENT_APPEND — transition receipt remains authoritative */
+                            reportClassifiedDegradation('REOPEN_EVENT_APPEND', err);
                         });
                     }
                     // SPEC-769/SPEC-780: Write qualityWarnings to spec.md frontmatter when force-approved (best-effort)
@@ -1228,8 +1162,9 @@ export async function handleUpdateStatus(params, server) {
                                 const updated = updateFrontmatterField(content, 'qualityWarnings', warningsJson);
                                 await atomicWriteFile(specPathForWarnings, updated);
                             }
-                            catch {
-                                // best-effort — never blocks the transition
+                            catch (error) {
+                                // reliability-optional: QUALITY_WARNING_FRONTMATTER — canonical receipt retains warnings
+                                reportClassifiedDegradation('QUALITY_WARNING_FRONTMATTER', error);
                             }
                         })();
                     }
@@ -1240,10 +1175,7 @@ export async function handleUpdateStatus(params, server) {
                         const terminalGateResults = {};
                         if (newStatus === 'done') {
                             Object.assign(terminalGateResults, sddRoutingGate.gateResults);
-                            if (validateGateResult !== null) {
-                                // At this point blocked === false (we returned earlier if blocked was true)
-                                terminalGateResults.validate = validateGateResult.forced ? 'forced' : 'pass';
-                            }
+                            terminalGateResults.validate = 'pass';
                             if (complianceGateResult !== null) {
                                 terminalGateResults.compliance = complianceGateResult.skipped
                                     ? 'skip'
@@ -1251,15 +1183,8 @@ export async function handleUpdateStatus(params, server) {
                                         ? 'fail'
                                         : 'pass';
                             }
-                            if (crashRisksReport !== null) {
-                                terminalGateResults['crash-shield'] =
-                                    crashRisksReport.score >= 80 ? 'pass' : 'fail';
-                            }
-                            else if (crashShieldSkipReason) {
-                                terminalGateResults['crash-shield'] = 'skip';
-                            }
                         }
-                        void recordTerminalTransitionEvent({
+                        await recordTerminalTransitionEvent({
                             projectId,
                             specId,
                             specPath: updatedSpec.specPath,
@@ -1272,8 +1197,9 @@ export async function handleUpdateStatus(params, server) {
                             modelId: params.modelId,
                             gateResults: Object.keys(terminalGateResults).length > 0 ? terminalGateResults : undefined,
                             meta: transitionEvidenceMeta,
-                        }).catch(() => {
-                            /* best-effort — never block the transition */
+                        }).catch((error) => {
+                            /* reliability-optional: TERMINAL_VALIDATION_REPORT — canonical receipt is authoritative */
+                            reportClassifiedDegradation('TERMINAL_VALIDATION_REPORT', error);
                         });
                     }
                     const allSpecs = await specStore.listSpecs(projectId);
@@ -1301,15 +1227,6 @@ export async function handleUpdateStatus(params, server) {
                     // SPEC-469: Collect autopilot summary for done-transition side effects
                     const collector = new AutopilotSummaryCollector();
                     if (newStatus === 'done') {
-                        if (validateScore !== null) {
-                            collector.pushOk('validate', `Validate score: ${String(validateScore)}/100`);
-                        }
-                        if (crashShieldWarning) {
-                            collector.pushFail('crash-shield', crashShieldWarning);
-                        }
-                        else if (crashShieldSkipReason) {
-                            collector.pushOk('crash-shield', `scan_crash_risks: skipped (${crashShieldSkipReason})`);
-                        }
                         if (doneActions?.mergeWarning) {
                             collector.pushFail('merge-check', doneActions.mergeWarning);
                         }
@@ -1392,26 +1309,12 @@ export async function handleUpdateStatus(params, server) {
                         ...(collector.hasEntries() ? { autopilotSummary: collector.getMessages() } : {}),
                     });
                     // SPEC-772 Scenario 4: surface validate failure from cascade as explicit warning
-                    const autopilotValidateWarning = validateScore !== null && validateScore < 100
-                        ? `Validate score ${String(validateScore)}/100 — below threshold. Check workspace_alerts for cascade details.`
-                        : null;
-                    if (autopilotValidateWarning) {
-                        result.autopilotValidateWarning = autopilotValidateWarning;
-                    }
                     // SPEC-754: Append shell-hygiene reminder when transitioning to done on claude-code host
                     const shellHygieneHint = newStatus === 'done' && detectHost() === 'claude-code' ? shellHygieneReminder() : null;
                     return buildStatusResponse(result, specId, originalStatus, newStatus, null, spec.title, shellHygieneHint);
                 }
                 finally {
-                    // SPEC-719: Release cross-process lock in all exit paths (return, throw)
-                    if (crossProcessLockHandle !== null) {
-                        await releaseLock(crossProcessLockHandle).catch((err) => {
-                            console.warn('[planu:lock] update_status release error', {
-                                specId,
-                                error: err instanceof Error ? err.message : String(err),
-                            });
-                        });
-                    }
+                    // Expensive gates intentionally execute without a mutation lock.
                 }
             }
             catch (error) {
@@ -1432,7 +1335,7 @@ export async function handleUpdateStatus(params, server) {
                     isError: true,
                 };
             }
-        });
+        })();
     }); // end trackCost
 }
 //# sourceMappingURL=index.js.map