@planu/cli 4.11.7 → 4.11.9

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

@@ -2,16 +2,17 @@ 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 { transitionSpec } from '../../engine/spec-state-machine/transition-spec.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 { runImplementingActions, runDoneActions } from '../update-status-actions.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 { 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';
@@ -20,11 +21,11 @@ import { buildStatusResponse, buildValidateBlockedResponse, buildDryRunResponse,
 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';
-import { randomUUID as uuid } from 'node:crypto';
+import { createHash, randomUUID as uuid } from 'node:crypto';
 import { updateFrontmatterField } from '../../engine/frontmatter-parser.js';
 import { atomicWriteFile } from '../../engine/safety/atomic-write-file.js';
 import { recordForceUsage } from '../../storage/force-analytics-store.js';
-import { maybeSafePushOnDone, runCascadeForResponse } from './side-effects.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';
@@ -144,11 +145,265 @@ async function createVersionSnapshot(specId, projectId, tag) {
     await mkdir(dirname(snapshotPath), { recursive: true });
     await writeFile(snapshotPath, JSON.stringify(spec, null, 2), 'utf-8');
 }
-function checkIdempotentOrTransition(specId, current, target) {
-    if (current === target) {
-        return { content: [{ type: 'text', text: `Spec ${specId} is already ${target}.` }] };
+function checkIdempotentOrTransition(projectId, spec, target) {
+    if (spec.status === target) {
+        const latestReceipt = [...(spec.statusHistory ?? [])]
+            .reverse()
+            .find((entry) => entry.status === target);
+        const committedAt = latestReceipt?.changedAt ?? spec.updatedAt;
+        const transitionId = latestReceipt?.transitionId ??
+            createHash('sha256')
+                .update(['update_status:legacy:v1', projectId, spec.id, target, committedAt].join('\0'))
+                .digest('hex')
+                .slice(0, 24);
+        const pendingBackgroundActions = [...(latestReceipt?.pendingBackgroundActions ?? [])];
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Spec ${spec.id} is already ${target}; the committed transition was reused.`,
+                },
+            ],
+            structuredContent: {
+                specId: spec.id,
+                previousStatus: latestReceipt?.fromStatus ?? target,
+                newStatus: target,
+                committed: true,
+                transitionId,
+                committedAt,
+                idempotent: true,
+                pendingBackgroundActions,
+            },
+        };
+    }
+    return checkTransition(spec.status, target);
+}
+function planBackgroundActions(args) {
+    const actions = ['cascade'];
+    if (args.newStatus === 'implementing') {
+        actions.push('implementing-side-effects');
+    }
+    if (args.newStatus === 'approved') {
+        actions.push('version-snapshot');
+    }
+    if (args.newStatus === 'done') {
+        actions.push('done-side-effects', 'reconcile');
+        if (args.hasActuals) {
+            actions.push('record-done-metrics');
+        }
+        if (args.hasProjectPath) {
+            actions.push('autopush');
+        }
+    }
+    if (args.shouldAutoStage) {
+        actions.push('git-autostage');
+    }
+    return actions;
+}
+function buildPostCommitTasks(args) {
+    const enabled = new Set(args.actionNames);
+    const tasks = [];
+    const versionSnapshotTag = args.versionSnapshotTag ?? `approved-${args.committedAt.replace(/[-:]/g, '').slice(0, 13)}`;
+    if (enabled.has('version-snapshot')) {
+        tasks.push({
+            name: 'version-snapshot',
+            run: () => createVersionSnapshot(args.spec.id, args.projectId, versionSnapshotTag),
+        });
+    }
+    if (enabled.has('implementing-side-effects')) {
+        tasks.push({
+            name: 'implementing-side-effects',
+            run: () => runImplementingSideEffects(args.projectId, args.spec.id),
+        });
+    }
+    if (enabled.has('done-side-effects')) {
+        tasks.push({
+            name: 'done-side-effects',
+            run: () => runDoneSideEffects(args.projectId, args.spec.id, args.spec.gitBranch),
+        });
     }
-    return checkTransition(current, target);
+    if (enabled.has('reconcile')) {
+        tasks.push({
+            name: 'reconcile',
+            run: () => tryReconcile(args.spec.status, args.spec.id, args.projectId),
+        });
+    }
+    const actuals = args.actuals;
+    if (enabled.has('record-done-metrics') && actuals) {
+        tasks.push({
+            name: 'record-done-metrics',
+            run: () => recordDoneMetrics(args.projectId, args.spec.id, args.spec, actuals, args.knowledge?.projectPath),
+        });
+    }
+    const effectiveProjectPath = args.effectiveProjectPath;
+    if (enabled.has('autopush') && effectiveProjectPath) {
+        tasks.push({
+            name: 'autopush',
+            run: () => maybeSafePushOnDone(effectiveProjectPath, args.spec.status),
+        });
+    }
+    if (enabled.has('cascade')) {
+        tasks.push({
+            name: 'cascade',
+            run: () => runCascadeForResponse({
+                knowledge: args.knowledge,
+                allSpecs: args.allSpecs,
+                specId: args.spec.id,
+                newStatus: args.spec.status,
+                validateScore: args.validateScore,
+                projectId: args.projectId,
+                spec: args.spec,
+                currentStatus: args.previousStatus,
+            }),
+        });
+    }
+    if (enabled.has('git-autostage') && effectiveProjectPath) {
+        tasks.push({
+            name: 'git-autostage',
+            run: async () => {
+                const { git: gitCmd } = await import('../git/git-helpers.js');
+                await gitCmd(effectiveProjectPath, ['add', 'planu/']);
+                const { planuAutoCommit } = await import('./../../engine/git/planu-autocommit.js');
+                await planuAutoCommit({
+                    projectPath: effectiveProjectPath,
+                    specId: args.spec.id,
+                    reason: args.spec.status === 'done' ? 'mark-done' : 'status-update',
+                });
+            },
+        });
+    }
+    const knownNames = new Set(tasks.map((task) => task.name));
+    for (const unknownName of enabled) {
+        if (knownNames.has(unknownName)) {
+            continue;
+        }
+        tasks.push({
+            name: unknownName,
+            run: () => Promise.reject(new Error(`Unknown post-commit task: ${unknownName}`)),
+        });
+    }
+    return tasks;
+}
+async function replayIdempotentPostCommitTasks(args) {
+    const receipt = [...(args.spec.statusHistory ?? [])]
+        .reverse()
+        .find((entry) => entry.status === args.spec.status);
+    if (!receipt?.transitionId || !receipt.pendingBackgroundActions?.length) {
+        return;
+    }
+    const knowledge = await knowledgeStore.getKnowledge(args.projectId);
+    const effectiveProjectPath = knowledge?.projectPath ?? args.projectPath;
+    const specAtTransition = { ...args.spec, status: receipt.status };
+    const tasks = buildPostCommitTasks({
+        actionNames: receipt.pendingBackgroundActions,
+        projectId: args.projectId,
+        spec: specAtTransition,
+        previousStatus: receipt.fromStatus ?? args.spec.status,
+        committedAt: receipt.changedAt,
+        knowledge,
+        allSpecs: await specStore.listSpecs(args.projectId),
+        validateScore: null,
+        actuals: specAtTransition.actuals ?? undefined,
+        effectiveProjectPath,
+    });
+    queuePostCommitTasks({
+        projectId: args.projectId,
+        specId: args.spec.id,
+        transitionId: receipt.transitionId,
+        tasks,
+    });
+}
+async function recoverPendingPostCommitTasks(projectId, projectPath) {
+    const [knowledge, specs] = await Promise.all([
+        knowledgeStore.getKnowledge(projectId),
+        specStore.listSpecs(projectId),
+    ]);
+    const effectiveProjectPath = knowledge?.projectPath ?? projectPath;
+    for (const spec of specs) {
+        const hasPendingWork = (spec.statusHistory ?? []).some((receipt) => receipt.transitionId && receipt.pendingBackgroundActions?.length);
+        if (!hasPendingWork) {
+            continue;
+        }
+        const recoveryLock = await acquireLock(effectiveProjectPath ?? projectPath ?? process.cwd(), spec.id, { reason: 'recover pending post-commit tasks' });
+        if (recoveryLock === null) {
+            continue;
+        }
+        try {
+            const currentSpec = typeof specStore.getSpecFresh === 'function'
+                ? await specStore.getSpecFresh(projectId, spec.id)
+                : spec;
+            if (!currentSpec) {
+                continue;
+            }
+            for (const receipt of currentSpec.statusHistory ?? []) {
+                if (!receipt.transitionId || !receipt.pendingBackgroundActions?.length) {
+                    continue;
+                }
+                const specAtTransition = { ...currentSpec, status: receipt.status };
+                const tasks = buildPostCommitTasks({
+                    actionNames: receipt.pendingBackgroundActions,
+                    projectId,
+                    spec: specAtTransition,
+                    previousStatus: receipt.fromStatus ?? currentSpec.status,
+                    committedAt: receipt.changedAt,
+                    knowledge,
+                    allSpecs: specs,
+                    validateScore: null,
+                    actuals: specAtTransition.actuals ?? undefined,
+                    effectiveProjectPath,
+                });
+                queuePostCommitTasks({
+                    projectId,
+                    specId: currentSpec.id,
+                    transitionId: receipt.transitionId,
+                    tasks,
+                });
+            }
+        }
+        finally {
+            await releaseLock(recoveryLock).catch(() => undefined);
+        }
+    }
+}
+/** Recover durable post-commit work for every registered project after server startup. */
+export async function recoverPendingPostCommitTasksAtStartup() {
+    const { getProjects } = await import('../../storage/global-projects-store.js');
+    const projects = await getProjects();
+    const results = await Promise.allSettled(projects.map((project) => recoverPendingPostCommitTasks(project.hash, project.path)));
+    for (let index = 0; index < results.length; index += 1) {
+        const result = results[index];
+        if (result?.status !== 'rejected') {
+            continue;
+        }
+        console.warn('[planu:post-commit] startup recovery failed for project', {
+            projectId: projects[index]?.hash ?? 'unknown',
+            error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+        });
+    }
+}
+function buildPersistenceFailureResponse(args) {
+    const committed = args.recoveryRequired ? null : false;
+    const message = args.recoveryRequired
+        ? `Transition persistence became indeterminate for ${args.specId}; manual recovery is required.`
+        : `Transition ${args.specId} → ${args.newStatus} was not committed; the previous state was restored.`;
+    return {
+        isError: true,
+        content: [{ type: 'text', text: `${message} Detail: ${args.reason}` }],
+        structuredContent: {
+            error: args.recoveryRequired
+                ? 'transition_recovery_required'
+                : 'transition_persistence_failed',
+            specId: args.specId,
+            previousStatus: args.previousStatus,
+            newStatus: args.newStatus,
+            committed,
+            recoveryRequired: args.recoveryRequired,
+            reason: args.reason,
+            fixHint: args.recoveryRequired
+                ? 'Run repair_frontmatter_drift and inspect the canonical spec store before retrying.'
+                : 'Fix the persistence error and retry update_status; no transition was committed.',
+        },
+    };
 }
 /** SPEC-628: Check crash scan rate-limit and return skip reason if within window. */
 async function checkCrashScanRateLimit(newStatus, effectiveGatePath) {
@@ -247,930 +502,937 @@ export async function handleUpdateStatus(params, server) {
                 /* strict cleanup is best-effort here; validate fails closed if artifacts remain */
             }
         }
-        try {
-            // Get the current spec
-            const spec = await specStore.getSpec(projectId, specId);
-            if (!spec) {
-                return {
-                    content: [{ type: 'text', text: ti('spec.notFound', { id: specId }) }],
-                    isError: true,
-                };
-            }
-            const originalStatus = spec.status;
-            if (newStatus === 'done' && actuals === undefined) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: 'actuals_required: provide measured values for done. Use zero only when a metric is explicitly unavailable; Planu does not estimate provider tokens or costs.',
-                        },
-                    ],
-                    isError: true,
-                    structuredContent: {
-                        error: 'actuals_required',
-                        code: 422,
-                        fixHint: 'Provide actuals with measured values or zero for unavailable metrics. Values are preserved without estimation.',
-                    },
-                };
-            }
-            // SPEC-301: Reject status changes when spec is locked by another holder (legacy manual lock)
-            const lockError = await checkSpecLockGate(params.projectPath, 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.
-            const isDryRun = params.dry_run === true;
-            let crossProcessLockHandle = null;
-            if (!isDryRun && params.projectPath !== undefined) {
-                crossProcessLockHandle = await acquireLock(params.projectPath, 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 && params.projectPath !== undefined) {
-                // 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(params.projectPath, specId).catch(() => null);
-                const lockIsBusy = lockInfo !== null && !lockInfo.stale;
-                if (lockIsBusy) {
-                    // Lock is busy — return dry_run result indicating this without blocking
-                    return buildDryRunResponse({
-                        ok: true,
-                        dryRun: true,
-                        wouldTransition: false,
-                        gates: {
-                            dod: 'skip',
-                            validate: 'skip',
-                            qa: 'skip',
-                            security: 'skip',
-                            lock: 'busy',
-                            compliance: 'skip',
-                        },
-                        blockingReasons: ['Cross-process lock is held by another process'],
-                    });
-                }
-            }
+        await recoverPendingPostCommitTasks(projectId, effectiveProjectPath).catch((error) => {
+            console.warn('[planu:post-commit] automatic recovery scan failed', {
+                projectId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+        return withApprovalSpecLock(effectiveProjectPath, specId, async () => {
             try {
-                if (spec.status === newStatus) {
-                    const idempotentResult = checkIdempotentOrTransition(specId, spec.status, newStatus);
-                    if (idempotentResult) {
-                        return idempotentResult;
-                    }
-                }
-                // SPEC-280/SPEC-1122: plan every intermediate state in memory. No status is
-                // persisted until all gates for the complete path have passed.
-                const { plannedStatuses, stepsExecuted } = buildAutoAdvancePlan(spec.status, newStatus);
-                let plannedFromStatus = spec.status;
-                for (const plannedStatus of plannedStatuses) {
-                    const transitionError = checkTransition(plannedFromStatus, plannedStatus);
-                    if (transitionError) {
-                        return transitionError;
-                    }
-                    plannedFromStatus = plannedStatus;
+                // 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-733: Detect reverse transition and validate mandatory reason
-                const reverseTransition = isReverseTransition(spec.status, newStatus);
-                if (reverseTransition) {
-                    const reverseValidation = validateReverseTransition({
-                        from: spec.status,
-                        to: newStatus,
-                        reason: params.reason,
+                // 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.
+                const isDryRun = params.dry_run === true;
+                let crossProcessLockHandle = null;
+                if (!isDryRun) {
+                    crossProcessLockHandle = await acquireLock(effectiveProjectPath, specId, {
+                        reason: `update_status(${newStatus})`,
                     });
-                    if (!reverseValidation.ok) {
+                    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: formatKeyValue({
-                                        error: 'invalid_input',
-                                        message: reverseValidation.error,
-                                        fixHint: reverseValidation.fixHint,
-                                    }),
+                                    text: `Spec ${specId} is locked by another process (cross-process lock). Retry later or inspect data/.locks/planu/${specId}.lock`,
                                 },
                             ],
                             isError: true,
-                            structuredContent: {
-                                error: 'invalid_input',
-                                code: 422,
-                                fixHint: reverseValidation.fixHint,
-                            },
                         };
                     }
                 }
-                // Gate: approval policy must be satisfied before transitioning to 'approved'
-                const approvalGateStatus = plannedStatuses.includes('approved') ? 'approved' : newStatus;
-                const approvalError = await checkApprovalPolicyGate(projectId, specId, approvalGateStatus);
-                if (approvalError) {
-                    return approvalError;
-                }
-                // Gate: DoR must pass before transitioning to 'implementing'
-                const dorGateStatus = plannedStatuses.includes('implementing') ? 'implementing' : newStatus;
-                const dorError = checkDorGate(spec, specId, projectId, dorGateStatus);
-                if (dorError) {
-                    return dorError;
-                }
-                // SPEC-716/SPEC-780: Format gate — block 'approved' unless forceApprove bypasses with warnings
-                const formatGate = await checkApprovedFormatGate(spec, approvalGateStatus, params.forceApprove);
-                if (formatGate.blockResult) {
-                    return formatGate.blockResult;
-                }
-                // SPEC-632: Ambiguity gate — block 'approved' if score < 70
-                const ambiguityError = await checkAmbiguityGate(spec, approvalGateStatus);
-                if (ambiguityError) {
-                    return ambiguityError;
-                }
-                // SPEC-769: Readiness gate — block 'approved' if spec has 0 criteria or score < 70
-                const readinessGate = await checkReadinessGate(spec, approvalGateStatus, params.forceApprove);
-                if (readinessGate.blockResult) {
-                    return readinessGate.blockResult;
+                else {
+                    // 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 lockIsBusy = lockInfo !== null && !lockInfo.stale;
+                    if (lockIsBusy) {
+                        // Lock is busy — return dry_run result indicating this without blocking
+                        return buildDryRunResponse({
+                            ok: true,
+                            dryRun: true,
+                            wouldTransition: false,
+                            gates: {
+                                dod: 'skip',
+                                validate: 'skip',
+                                qa: 'skip',
+                                security: 'skip',
+                                lock: 'busy',
+                                compliance: 'skip',
+                            },
+                            blockingReasons: ['Cross-process lock is held by another process'],
+                        });
+                    }
                 }
-                // SPEC-728: DepGuard — block 'approved' if spec participates in a dependency cycle
-                let depGuardResult = null;
-                if (plannedStatuses.includes('approved')) {
-                    const allSpecsForDepGuard = await specStore.listSpecs(projectId);
-                    depGuardResult = checkApprovedDepGate(spec, allSpecsForDepGuard);
-                    if (depGuardResult.blocked) {
+                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);
+                    if (!spec) {
+                        return {
+                            content: [{ type: 'text', text: ti('spec.notFound', { id: specId }) }],
+                            isError: true,
+                        };
+                    }
+                    const originalStatus = spec.status;
+                    if (spec.status === newStatus) {
+                        await replayIdempotentPostCommitTasks({
+                            projectId,
+                            spec,
+                            projectPath: effectiveProjectPath,
+                        });
+                        const idempotentResult = checkIdempotentOrTransition(projectId, spec, newStatus);
+                        if (idempotentResult) {
+                            return idempotentResult;
+                        }
+                    }
+                    if (newStatus === 'done' && actuals === undefined) {
                         return {
-                            content: [{ type: 'text', text: `DepGuard blocked: ${depGuardResult.narrative}` }],
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'actuals_required: provide measured values for done. Use zero only when a metric is explicitly unavailable; Planu does not estimate provider tokens or costs.',
+                                },
+                            ],
                             isError: true,
                             structuredContent: {
-                                error: 'DEP_GUARD_BLOCKED',
-                                code: depGuardResult.code,
-                                cyclePath: depGuardResult.cyclePath,
-                                narrative: depGuardResult.narrative,
-                                depGuard: depGuardResult,
+                                error: 'actuals_required',
+                                code: 422,
+                                fixHint: 'Provide actuals with measured values or zero for unavailable metrics. Values are preserved without estimation.',
                             },
                         };
                     }
-                }
-                // SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
-                const challengeGateStatus = plannedStatuses.includes('review') ? 'review' : newStatus;
-                const challengeGate = checkChallengeGate(spec, challengeGateStatus);
-                if (challengeGate) {
-                    return challengeGate;
-                }
-                if (plannedStatuses.includes('approved')) {
-                    const specReviewError = await checkSpecReviewGate(specId, projectId, params.forceApprove);
-                    if (specReviewError) {
-                        return specReviewError;
+                    // SPEC-280/SPEC-1122: plan every intermediate state in memory. No status is
+                    // persisted until all gates for the complete path have passed.
+                    const { plannedStatuses, stepsExecuted } = buildAutoAdvancePlan(spec.status, newStatus);
+                    let plannedFromStatus = spec.status;
+                    for (const plannedStatus of plannedStatuses) {
+                        const transitionError = checkTransition(plannedFromStatus, plannedStatus);
+                        if (transitionError) {
+                            return transitionError;
+                        }
+                        plannedFromStatus = plannedStatus;
                     }
-                }
-                // SPEC-595: Elicit confirmation for destructive status transitions (→done with forceStatus)
-                const elicitResult = await runForceStatusElicitation(server, specId, newStatus, params.forceStatus);
-                if (elicitResult) {
-                    return elicitResult;
-                }
-                // 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;
-                // SPEC-1044: SDD model-routing + context continuity hard gate.
-                const sddRoutingGate = {
-                    blockResult: null,
-                    gateResults: { sddModelRouting: 'skip' },
-                    forcedReasons: [],
-                };
-                if (!shouldSkipSddRoutingGateForLegacyTestHarness()) {
-                    const routedStatuses = plannedStatuses.filter((status) => status === 'approved' || status === 'implementing' || status === 'done');
-                    for (const status of routedStatuses) {
-                        const gate = await checkSddModelRoutingGate({
-                            params,
-                            status,
-                            projectPath: effectiveGatePath,
+                    // SPEC-733: Detect reverse transition and validate mandatory reason
+                    const reverseTransition = isReverseTransition(spec.status, newStatus);
+                    if (reverseTransition) {
+                        const reverseValidation = validateReverseTransition({
+                            from: spec.status,
+                            to: newStatus,
+                            reason: params.reason,
                         });
-                        if (gate.blockResult) {
-                            return gate.blockResult;
+                        if (!reverseValidation.ok) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: formatKeyValue({
+                                            error: 'invalid_input',
+                                            message: reverseValidation.error,
+                                            fixHint: reverseValidation.fixHint,
+                                        }),
+                                    },
+                                ],
+                                isError: true,
+                                structuredContent: {
+                                    error: 'invalid_input',
+                                    code: 422,
+                                    fixHint: reverseValidation.fixHint,
+                                },
+                            };
                         }
-                        Object.assign(sddRoutingGate.gateResults, gate.gateResults);
-                        sddRoutingGate.forcedReasons.push(...gate.forcedReasons);
                     }
-                    if (sddRoutingGate.forcedReasons.length > 0) {
-                        sddRoutingGate.gateResults.sddModelRouting = 'forced';
+                    // Gate: approval policy must be satisfied before transitioning to 'approved'
+                    const approvalGateStatus = plannedStatuses.includes('approved') ? 'approved' : newStatus;
+                    const approvalError = await checkApprovalPolicyGate(projectId, specId, approvalGateStatus);
+                    if (approvalError) {
+                        return approvalError;
                     }
-                }
-                // 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()) {
-                    const evidenceStatuses = plannedStatuses.filter((status) => status === 'approved' || status === 'implementing' || status === 'done');
-                    for (const transition of evidenceStatuses) {
-                        const evidenceGate = await checkLifecycleEvidenceTransitionGate({
-                            spec,
-                            specId,
-                            projectId,
-                            projectPath: effectiveGatePath,
-                            transition,
-                        });
-                        if (evidenceGate !== null) {
-                            return evidenceGate;
+                    // Gate: DoR must pass before transitioning to 'implementing'
+                    const dorGateStatus = plannedStatuses.includes('implementing')
+                        ? 'implementing'
+                        : newStatus;
+                    const dorError = checkDorGate(spec, specId, projectId, dorGateStatus);
+                    if (dorError) {
+                        return dorError;
+                    }
+                    // SPEC-716/SPEC-780: Format gate — block 'approved' unless forceApprove bypasses with warnings
+                    const formatGate = await checkApprovedFormatGate(spec, approvalGateStatus, params.forceApprove);
+                    if (formatGate.blockResult) {
+                        return formatGate.blockResult;
+                    }
+                    // SPEC-632: Ambiguity gate — block 'approved' if score < 70
+                    const ambiguityError = await checkAmbiguityGate(spec, approvalGateStatus);
+                    if (ambiguityError) {
+                        return ambiguityError;
+                    }
+                    // SPEC-769: Readiness gate — block 'approved' if spec has 0 criteria or score < 70
+                    const readinessGate = await checkReadinessGate(spec, approvalGateStatus, params.forceApprove);
+                    if (readinessGate.blockResult) {
+                        return readinessGate.blockResult;
+                    }
+                    // SPEC-728: DepGuard — block 'approved' if spec participates in a dependency cycle
+                    let depGuardResult = null;
+                    if (plannedStatuses.includes('approved')) {
+                        const allSpecsForDepGuard = await specStore.listSpecs(projectId);
+                        depGuardResult = checkApprovedDepGate(spec, allSpecsForDepGuard);
+                        if (depGuardResult.blocked) {
+                            return {
+                                content: [{ type: 'text', text: `DepGuard blocked: ${depGuardResult.narrative}` }],
+                                isError: true,
+                                structuredContent: {
+                                    error: 'DEP_GUARD_BLOCKED',
+                                    code: depGuardResult.code,
+                                    cyclePath: depGuardResult.cyclePath,
+                                    narrative: depGuardResult.narrative,
+                                    depGuard: depGuardResult,
+                                },
+                            };
                         }
                     }
-                }
-                // ---------------------------------------------------------------------------
-                // BATCH A (parallel): code-reality + done-gates — independent of each other
-                // 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;
+                    // SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
+                    const challengeGateStatus = plannedStatuses.includes('review') ? 'review' : newStatus;
+                    const challengeGate = checkChallengeGate(spec, challengeGateStatus);
+                    if (challengeGate) {
+                        return challengeGate;
                     }
-                }
-                // ---------------------------------------------------------------------------
-                let codeRealityWarning = null;
-                let forcedBypassWarning = null;
-                const [codeRealityResult, doneGatesResult] = await Promise.all([
-                    // Code reality: only relevant for 'implementing'
-                    newStatus === 'implementing' && !reverseTransition && effectiveGatePath
-                        ? checkCodeReality(effectiveGatePath, spec.title).catch(() => null)
-                        : Promise.resolve(null),
-                    // Done gates: only relevant for 'done'
-                    newStatus === 'done'
-                        ? checkDoneGates(spec, specId, projectId, effectiveGatePath, params.force, params.forceStatusReason ?? params.reason ?? 'No force reason provided')
-                        : Promise.resolve(null),
-                ]);
-                // Process code reality result
-                if (codeRealityResult?.status === 'complete' || codeRealityResult?.status === 'partial') {
-                    codeRealityWarning = codeRealityResult.warning;
-                }
-                // Process done gates result — may block
-                if (doneGatesResult !== null) {
-                    if (doneGatesResult.blocked) {
-                        return doneGatesResult.blocked;
+                    if (plannedStatuses.includes('approved')) {
+                        const specReviewError = await checkSpecReviewGate(specId, projectId, params.forceApprove);
+                        if (specReviewError) {
+                            return specReviewError;
+                        }
                     }
-                    forcedBypassWarning = doneGatesResult.forcedBypassWarning;
-                }
-                // ---------------------------------------------------------------------------
-                // 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'
-                // ---------------------------------------------------------------------------
-                let validateScore = null;
-                let validateScoreSource = null;
-                let crashShieldWarning = null;
-                let crashShieldSkipReason = 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);
+                    // SPEC-595: Elicit confirmation for destructive status transitions (→done with forceStatus)
+                    const elicitResult = await runForceStatusElicitation(server, specId, newStatus, params.forceStatus);
+                    if (elicitResult) {
+                        return elicitResult;
                     }
-                    validateScore = validateGateResult.score;
-                    if (validateGateResult.forced) {
-                        validateScoreSource = validateGateResult.scoreSource;
-                        forcedValidateBypass = {
-                            reason: validateGateResult.forcedReason,
-                            observedScore: validateGateResult.score,
-                        };
+                    // 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;
+                    // SPEC-1044: SDD model-routing + context continuity hard gate.
+                    const sddRoutingGate = {
+                        blockResult: null,
+                        gateResults: { sddModelRouting: 'skip' },
+                        forcedReasons: [],
+                    };
+                    if (!shouldSkipSddRoutingGateForLegacyTestHarness()) {
+                        const routedStatuses = plannedStatuses.filter((status) => status === 'approved' || status === 'implementing' || status === 'done');
+                        for (const status of routedStatuses) {
+                            const gate = await checkSddModelRoutingGate({
+                                params,
+                                status,
+                                projectPath: effectiveGatePath,
+                            });
+                            if (gate.blockResult) {
+                                return gate.blockResult;
+                            }
+                            Object.assign(sddRoutingGate.gateResults, gate.gateResults);
+                            sddRoutingGate.forcedReasons.push(...gate.forcedReasons);
+                        }
+                        if (sddRoutingGate.forcedReasons.length > 0) {
+                            sddRoutingGate.gateResults.sddModelRouting = 'forced';
+                        }
                     }
-                    else {
-                        validateScoreSource = 'validateSpec';
+                    // 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()) {
+                        const evidenceStatuses = plannedStatuses.filter((status) => status === 'approved' || status === 'implementing' || status === 'done');
+                        for (const transition of evidenceStatuses) {
+                            const evidenceGate = await checkLifecycleEvidenceTransitionGate({
+                                spec,
+                                specId,
+                                projectId,
+                                projectPath: effectiveGatePath,
+                                transition,
+                            });
+                            if (evidenceGate !== null) {
+                                return evidenceGate;
+                            }
+                        }
                     }
-                }
-                if (newStatus === 'done' &&
-                    effectiveGatePath &&
-                    !shouldSkipStrictLayoutGateForLegacyTestHarness()) {
-                    const strictLayoutError = await validateStrictLayoutOrError({
-                        projectPath: effectiveGatePath,
-                        specId,
-                        specPath: spec.specPath,
-                        failClosedOnCrash: true,
-                    });
-                    if (strictLayoutError) {
-                        return strictLayoutError;
+                    // ---------------------------------------------------------------------------
+                    // BATCH A (parallel): code-reality + done-gates — independent of each other
+                    // 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;
+                        }
                     }
-                }
-                // 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.`;
+                    // ---------------------------------------------------------------------------
+                    let codeRealityWarning = null;
+                    let forcedBypassWarning = null;
+                    const [codeRealityResult, doneGatesResult] = await Promise.all([
+                        // Code reality: only relevant for 'implementing'
+                        newStatus === 'implementing' && !reverseTransition && effectiveGatePath
+                            ? checkCodeReality(effectiveGatePath, spec.title).catch(() => null)
+                            : Promise.resolve(null),
+                        // Done gates: only relevant for 'done'
+                        newStatus === 'done'
+                            ? checkDoneGates(spec, specId, projectId, effectiveGatePath, params.force, params.forceStatusReason ?? params.reason ?? 'No force reason provided')
+                            : Promise.resolve(null),
+                    ]);
+                    // Process code reality result
+                    if (codeRealityResult?.status === 'complete' || codeRealityResult?.status === 'partial') {
+                        codeRealityWarning = codeRealityResult.warning;
                     }
-                    if (effectiveGatePath) {
-                        void recordCrashScanRun(effectiveGatePath).catch(() => {
-                            /* best-effort */
-                        });
+                    // Process done gates result — may block
+                    if (doneGatesResult !== null) {
+                        if (doneGatesResult.blocked) {
+                            return doneGatesResult.blocked;
+                        }
+                        forcedBypassWarning = doneGatesResult.forcedBypassWarning;
                     }
-                }
-                // Process compliance gate result — may block on 'review'
-                if (complianceResult !== null) {
-                    complianceGateResult = complianceResult;
-                    if (plannedStatuses.includes('review') && complianceResult.blocked) {
-                        return buildBlockedByComplianceResponse(specId, complianceResult);
+                    // ---------------------------------------------------------------------------
+                    // 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'
+                    // ---------------------------------------------------------------------------
+                    let validateScore = null;
+                    let validateScoreSource = null;
+                    let crashShieldWarning = null;
+                    let crashShieldSkipReason = 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';
+                        }
                     }
-                }
-                // 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')
-                    ? await runComplianceGates(projectId, spec.title, spec.tags, newStatus)
-                    : {
-                        conventionWarnings: [],
-                        constitutionWarnings: [],
-                        compileWarnings: [],
-                        lintWarnings: [],
-                        testWarnings: [],
-                    };
-                if (newStatus === 'done' && !(params.force ?? params.forceStatus ?? false)) {
-                    if (!isDryRun && effectiveGatePath) {
-                        await writeImplementationReviewReport({
-                            projectId,
-                            specId,
-                            spec,
+                    if (newStatus === 'done' &&
+                        effectiveGatePath &&
+                        !shouldSkipStrictLayoutGateForLegacyTestHarness()) {
+                        const strictLayoutError = await validateStrictLayoutOrError({
                             projectPath: effectiveGatePath,
-                            score: validateScore,
-                            lintPassed: lintWarnings.length === 0,
-                            conventionRegression: conventionWarnings.length > 0,
+                            specId,
+                            specPath: spec.specPath,
+                            failClosedOnCrash: true,
                         });
+                        if (strictLayoutError) {
+                            return strictLayoutError;
+                        }
                     }
-                    validationReportGate = await readApprovedValidationReportGate(specId, projectId, false);
-                    if (!validationReportGate.ok) {
-                        return validationReportGate.error;
+                    // 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 */
+                            });
+                        }
                     }
-                    if (validationReportGate.score !== null) {
-                        validateScore = validationReportGate.score;
-                        validateScoreSource = 'validation-report';
+                    // Process compliance gate result — may block on 'review'
+                    if (complianceResult !== null) {
+                        complianceGateResult = complianceResult;
+                        if (plannedStatuses.includes('review') && complianceResult.blocked) {
+                            return buildBlockedByComplianceResponse(specId, complianceResult);
+                        }
                     }
-                }
-                // 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
-                        security: newStatus === 'done' ? (doneGatesResult?.blocked ? 'fail' : 'pass') : 'skip',
-                        lock: 'available',
-                        compliance: complianceGateResult === null
-                            ? 'skip'
-                            : complianceGateResult.skipped
-                                ? 'skip'
-                                : complianceGateResult.blocked
-                                    ? 'fail'
-                                    : 'pass',
-                    };
-                    return buildDryRunResponse({
-                        ok: true,
-                        dryRun: true,
-                        wouldTransition: true,
-                        gates: dryRunGates,
-                        blockingReasons: [],
-                    });
-                }
-                // Entering review creates reviewer evidence only after every lifecycle gate has passed.
-                // Auto-advance to approval must consume pre-existing approved reviewer evidence.
-                if (newStatus === 'review') {
-                    const specReviewWriteError = await writeSpecReviewArtifact(spec, specId, projectId);
-                    if (specReviewWriteError) {
-                        return specReviewWriteError;
+                    // 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')
+                        ? await runComplianceGates(projectId, spec.title, spec.tags, newStatus, specId)
+                        : {
+                            conventionWarnings: [],
+                            constitutionWarnings: [],
+                            compileWarnings: [],
+                            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';
+                        }
                     }
-                }
-                // Explicit actuals are preserved verbatim. Provider usage and cost are never inferred.
-                const resolvedActuals = actuals;
-                // Run transition-specific actions
-                const implActions = newStatus === 'implementing' ? await runImplementingActions(projectId, specId) : null;
-                const doneActions = newStatus === 'done' ? await runDoneActions(projectId, specId, spec.gitBranch) : null;
-                // SPEC-720: Step 1 — Transition the status through the single authorised path
-                const trigger = reverseTransition
-                    ? 'reopen'
-                    : stepsExecuted.length > 0
-                        ? 'auto-advance'
-                        : (params.trigger ?? 'user');
-                const actor = params.actor ?? 'system';
-                const viaSync = params.viaSync ?? false;
-                await transitionSpec(projectId, specId, newStatus, {
-                    trigger: trigger,
-                    actor,
-                    viaSync,
-                    reason: params.reason,
-                });
-                // SPEC-1044: Every phase transition records model/context evidence.
-                const transitionEvidenceMeta = {
-                    ...buildTransitionEvidenceMeta(params),
-                    ...(sddRoutingGate.forcedReasons.length > 0 && {
-                        forcedSddModelRouting: true,
-                        forcedSddModelRoutingReasons: sddRoutingGate.forcedReasons,
-                    }),
-                };
-                void appendTransitionEvent({
-                    projectId,
-                    specId,
-                    eventType: 'transition',
-                    from: originalStatus,
-                    to: newStatus,
-                    actor,
-                    reason: params.reason,
-                    sessionId: params.sessionId,
-                    modelId: params.modelId,
-                    gateResults: sddRoutingGate.gateResults,
-                    meta: transitionEvidenceMeta,
-                }).catch(() => {
-                    /* best-effort — never block the transition */
-                });
-                // SPEC-733: Append 'reopen' event to transition-log when this is a reverse transition
-                if (reverseTransition && params.reason) {
-                    void appendTransitionEvent({
-                        projectId,
-                        specId,
-                        eventType: 'reopen',
-                        from: originalStatus,
-                        to: newStatus,
-                        actor,
-                        reason: params.reason,
-                    }).catch((err) => {
-                        console.warn('[planu:transition] reopen_event_append_failed', {
-                            specId,
-                            error: err instanceof Error ? err.message : String(err),
-                        });
-                    });
-                }
-                // SPEC-720: Step 2 — Update non-status fields (reviewNotes, actuals) separately
-                const nonStatusUpdates = {};
-                // Store review notes when sending back (review->draft or approved->review)
-                if (reviewNotes) {
-                    const existing = spec.reviewNotes ?? [];
-                    nonStatusUpdates.reviewNotes = [
-                        ...existing,
-                        `[${new Date().toISOString()}] ${originalStatus}→${newStatus}: ${reviewNotes}`,
-                    ];
-                }
-                // If actuals are provided (or auto-generated), save them
-                if (resolvedActuals) {
-                    nonStatusUpdates.actuals = resolvedActuals;
-                }
-                // Update non-status fields (if any)
-                const updatedSpec = Object.keys(nonStatusUpdates).length > 0
-                    ? await specStore.updateSpec(projectId, specId, nonStatusUpdates)
-                    : // Re-fetch the spec (transitionSpec already wrote the status)
-                        ((await specStore.getSpec(projectId, specId)) ?? spec);
-                // 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,
-                            },
+                    // 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
+                            security: newStatus === 'done' ? (doneGatesResult?.blocked ? 'fail' : 'pass') : 'skip',
+                            lock: 'available',
+                            compliance: complianceGateResult === null
+                                ? 'skip'
+                                : complianceGateResult.skipped
+                                    ? 'skip'
+                                    : complianceGateResult.blocked
+                                        ? 'fail'
+                                        : 'pass',
                         };
-                        appendEntry(entry);
-                        forceStatusAuditId = auditId;
+                        return buildDryRunResponse({
+                            ok: true,
+                            dryRun: true,
+                            wouldTransition: true,
+                            gates: dryRunGates,
+                            blockingReasons: [],
+                        });
                     }
-                    catch {
-                        /* best-effort — audit must never block transition */
+                    // Entering review creates reviewer evidence only after every lifecycle gate has passed.
+                    // Auto-advance to approval must consume pre-existing approved reviewer evidence.
+                    if (newStatus === 'review') {
+                        const specReviewWriteError = await writeSpecReviewArtifact(spec, specId, projectId);
+                        if (specReviewWriteError) {
+                            return specReviewWriteError;
+                        }
                     }
-                }
-                // SPEC-780: Audit-trail entry when forceApprove bypassed readiness/format gates
-                let forceApproveAuditId = null;
-                if (newStatus === 'approved' && params.forceApprove) {
-                    const bypassedGates = [];
-                    if (readinessGate.qualityWarnings.length > 0) {
-                        bypassedGates.push('readiness');
+                    // Explicit actuals are preserved verbatim. Provider usage and cost are never inferred.
+                    const resolvedActuals = actuals;
+                    // Run only fast, read-only transition checks before persistence.
+                    const implActions = newStatus === 'implementing'
+                        ? await runImplementingActions(projectId, specId, { deferSideEffects: true })
+                        : null;
+                    const doneActions = newStatus === 'done'
+                        ? await runDoneActions(projectId, specId, spec.gitBranch, {
+                            deferSideEffects: true,
+                        })
+                        : null;
+                    const trigger = reverseTransition
+                        ? 'reopen'
+                        : stepsExecuted.length > 0
+                            ? 'auto-advance'
+                            : (params.trigger ?? 'user');
+                    const actor = params.actor ?? 'system';
+                    const viaSync = params.viaSync ?? false;
+                    // SPEC-1044: Every phase transition records model/context evidence.
+                    const transitionEvidenceMeta = {
+                        ...buildTransitionEvidenceMeta(params),
+                        ...(sddRoutingGate.forcedReasons.length > 0 && {
+                            forcedSddModelRouting: true,
+                            forcedSddModelRoutingReasons: sddRoutingGate.forcedReasons,
+                        }),
+                    };
+                    const nonStatusUpdates = {};
+                    // Store review notes when sending back (review->draft or approved->review)
+                    if (reviewNotes) {
+                        const existing = spec.reviewNotes ?? [];
+                        nonStatusUpdates.reviewNotes = [
+                            ...existing,
+                            `[${new Date().toISOString()}] ${originalStatus}→${newStatus}: ${reviewNotes}`,
+                        ];
                     }
-                    if (formatGate.qualityWarnings.length > 0) {
-                        bypassedGates.push('format');
+                    // If actuals are provided (or auto-generated), save them
+                    if (resolvedActuals) {
+                        nonStatusUpdates.actuals = resolvedActuals;
                     }
-                    if (bypassedGates.length > 0) {
+                    // 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: `approve_gate_forced_bypass specId=${specId} bypassedGates=[${bypassedGates.join(',')}]`,
+                                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: 'approve_gate_forced_bypass',
+                                event: 'validate_gate_forced_bypass',
                                 details: {
-                                    bypassedGates,
+                                    reason: forcedValidateBypass.reason,
+                                    observedScore: forcedValidateBypass.observedScore,
                                     fromStatus: originalStatus,
                                     toStatus: newStatus,
-                                    originalBlockers: [
-                                        ...readinessGate.qualityWarnings,
-                                        ...formatGate.qualityWarnings,
-                                    ],
                                 },
                             };
                             appendEntry(entry);
-                            forceApproveAuditId = auditId;
+                            forceStatusAuditId = auditId;
                         }
                         catch {
                             /* best-effort — audit must never block transition */
                         }
                     }
-                }
-                // SPEC-1044: Audit forced SDD model/context gate bypasses.
-                let sddRoutingAuditId = null;
-                if (sddRoutingGate.forcedReasons.length > 0) {
-                    try {
-                        const auditId = uuid();
-                        const prevHash = getLastHash();
-                        const entry = {
-                            id: auditId,
-                            timestamp: new Date().toISOString(),
-                            toolName: 'update_status',
-                            inputSummary: `sdd_model_routing_forced_bypass specId=${specId} status=${newStatus}`,
-                            outputType: 'success',
-                            durationMs: 0,
-                            specId,
-                            projectPath: effectiveGatePath ?? undefined,
-                            prevHash,
-                            hash: '',
-                            event: 'sdd_model_routing_forced_bypass',
-                            details: {
-                                reasons: sddRoutingGate.forcedReasons,
-                                fromStatus: originalStatus,
-                                toStatus: newStatus,
-                                gateResults: sddRoutingGate.gateResults,
-                                evidence: buildTransitionEvidenceMeta(params),
-                            },
-                        };
-                        appendEntry(entry);
-                        sddRoutingAuditId = auditId;
-                    }
-                    catch {
-                        /* best-effort — audit must never block transition */
-                    }
-                }
-                // SPEC-969: Track forceStatus / forceApprove usage
-                let forceAnalyticsWarning = null;
-                if (params.forceStatus || params.forceApprove) {
-                    try {
-                        const allSpecsForAnalytics = await specStore.listSpecs(projectId);
-                        const analytics = await recordForceUsage(projectId, {
-                            specId,
-                            type: params.forceStatus ? 'forceStatus' : 'forceApprove',
-                            reason: params.forceStatusReason ?? params.reason ?? 'No reason provided',
-                            agentId: params.agentId ?? 'unknown',
-                        }, allSpecsForAnalytics.length);
-                        if (analytics.stats.ratio > 0.2) {
-                            const pct = Math.round(analytics.stats.ratio * 100);
-                            forceAnalyticsWarning =
-                                `${pct}% of specs bypassed gates — review process health. ` +
-                                    `Consider re-running validate within 24h.`;
+                    // SPEC-780: Audit-trail entry when forceApprove bypassed readiness/format gates
+                    let forceApproveAuditId = null;
+                    if (newStatus === 'approved' && params.forceApprove) {
+                        const bypassedGates = [];
+                        if (readinessGate.qualityWarnings.length > 0) {
+                            bypassedGates.push('readiness');
+                        }
+                        if (formatGate.qualityWarnings.length > 0) {
+                            bypassedGates.push('format');
+                        }
+                        if (bypassedGates.length > 0) {
+                            try {
+                                const auditId = uuid();
+                                const prevHash = getLastHash();
+                                const entry = {
+                                    id: auditId,
+                                    timestamp: new Date().toISOString(),
+                                    toolName: 'update_status',
+                                    inputSummary: `approve_gate_forced_bypass specId=${specId} bypassedGates=[${bypassedGates.join(',')}]`,
+                                    outputType: 'success',
+                                    durationMs: 0,
+                                    specId,
+                                    projectPath: effectiveGatePath ?? undefined,
+                                    prevHash,
+                                    hash: '',
+                                    event: 'approve_gate_forced_bypass',
+                                    details: {
+                                        bypassedGates,
+                                        fromStatus: originalStatus,
+                                        toStatus: newStatus,
+                                        originalBlockers: [
+                                            ...readinessGate.qualityWarnings,
+                                            ...formatGate.qualityWarnings,
+                                        ],
+                                    },
+                                };
+                                appendEntry(entry);
+                                forceApproveAuditId = auditId;
+                            }
+                            catch {
+                                /* best-effort — audit must never block transition */
+                            }
                         }
                     }
-                    catch {
-                        /* best-effort — analytics must never block transition */
-                    }
-                }
-                // SPEC-448: Auto version snapshot when spec is approved
-                let versionSnapshotTag = null;
-                if (newStatus === 'approved') {
-                    const tag = `approved-${new Date().toISOString().replace(/[-:]/g, '').slice(0, 13)}`;
-                    versionSnapshotTag = await createVersionSnapshot(specId, projectId, tag)
-                        .then(() => tag)
-                        .catch(() => null);
-                }
-                // SPEC-694: Auto-orchestration plan for cross-module/architectural specs on approved
-                const orchestrationPlan = await resolveOrchestrationPlan(newStatus, spec.scope, specId, effectiveGatePath);
-                // Sync spec.md frontmatter and inline ## Progress section.
-                // SPEC-698: capture warning so it surfaces in the tool response (was silent before)
-                const syncResult = await syncSpecFiles(updatedSpec, originalStatus, newStatus, effectiveGatePath);
-                const frontmatterSyncWarnings = syncResult.warning ? [syncResult.warning] : [];
-                // 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 */
-                    });
-                }
-                // SPEC-769/SPEC-780: Write qualityWarnings to spec.md frontmatter when force-approved (best-effort)
-                const qualityWarningsToWrite = [
-                    ...readinessGate.qualityWarnings,
-                    ...formatGate.qualityWarnings,
-                ];
-                const specPathForWarnings = updatedSpec.specPath;
-                if (newStatus === 'approved' && qualityWarningsToWrite.length > 0 && specPathForWarnings) {
-                    void (async () => {
+                    // SPEC-1044: Audit forced SDD model/context gate bypasses.
+                    let sddRoutingAuditId = null;
+                    if (sddRoutingGate.forcedReasons.length > 0) {
                         try {
-                            const { readFile: fsReadFile } = await import('node:fs/promises');
-                            const content = await fsReadFile(specPathForWarnings, 'utf-8');
-                            const warningsJson = JSON.stringify(qualityWarningsToWrite);
-                            const updated = updateFrontmatterField(content, 'qualityWarnings', warningsJson);
-                            await atomicWriteFile(specPathForWarnings, updated);
+                            const auditId = uuid();
+                            const prevHash = getLastHash();
+                            const entry = {
+                                id: auditId,
+                                timestamp: new Date().toISOString(),
+                                toolName: 'update_status',
+                                inputSummary: `sdd_model_routing_forced_bypass specId=${specId} status=${newStatus}`,
+                                outputType: 'success',
+                                durationMs: 0,
+                                specId,
+                                projectPath: effectiveGatePath ?? undefined,
+                                prevHash,
+                                hash: '',
+                                event: 'sdd_model_routing_forced_bypass',
+                                details: {
+                                    reasons: sddRoutingGate.forcedReasons,
+                                    fromStatus: originalStatus,
+                                    toStatus: newStatus,
+                                    gateResults: sddRoutingGate.gateResults,
+                                    evidence: buildTransitionEvidenceMeta(params),
+                                },
+                            };
+                            appendEntry(entry);
+                            sddRoutingAuditId = auditId;
                         }
                         catch {
-                            // best-effort — never blocks the transition
+                            /* best-effort — audit must never block transition */
                         }
-                    })();
-                }
-                // SPEC-723: Record terminal transition in hash-chained log (best-effort, fire-and-forget)
-                // SPEC-734: Thread enriched payload — sessionId, modelId, gateResults
-                if (newStatus === 'done' || newStatus === 'discarded') {
-                    // Build gateResults from gate outcomes resolved earlier in this handler
-                    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';
+                    }
+                    // SPEC-969: Track forceStatus / forceApprove usage
+                    let forceAnalyticsWarning = null;
+                    if (params.forceStatus || params.forceApprove) {
+                        try {
+                            const allSpecsForAnalytics = await specStore.listSpecs(projectId);
+                            const analytics = await recordForceUsage(projectId, {
+                                specId,
+                                type: params.forceStatus ? 'forceStatus' : 'forceApprove',
+                                reason: params.forceStatusReason ?? params.reason ?? 'No reason provided',
+                                agentId: params.agentId ?? 'unknown',
+                            }, allSpecsForAnalytics.length);
+                            if (analytics.stats.ratio > 0.2) {
+                                const pct = Math.round(analytics.stats.ratio * 100);
+                                forceAnalyticsWarning =
+                                    `${pct}% of specs bypassed gates — review process health. ` +
+                                        `Consider re-running validate within 24h.`;
+                            }
                         }
-                        if (complianceGateResult !== null) {
-                            terminalGateResults.compliance = complianceGateResult.skipped
-                                ? 'skip'
-                                : complianceGateResult.blocked
-                                    ? 'fail'
-                                    : 'pass';
+                        catch {
+                            /* best-effort — analytics must never block transition */
                         }
-                        if (crashRisksReport !== null) {
-                            terminalGateResults['crash-shield'] = crashRisksReport.score >= 80 ? 'pass' : 'fail';
+                    }
+                    const versionSnapshotTag = newStatus === 'approved'
+                        ? `approved-${new Date().toISOString().replace(/[-:]/g, '').slice(0, 13)}`
+                        : null;
+                    // SPEC-694: Auto-orchestration plan for cross-module/architectural specs on approved
+                    const orchestrationPlan = await resolveOrchestrationPlan(newStatus, spec.scope, specId, effectiveGatePath);
+                    const shouldAutoStage = Boolean(effectiveGatePath && spec.specPath) &&
+                        process.env.PLANU_ENABLE_AUTOCOMMIT === 'true' &&
+                        process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true';
+                    const plannedBackgroundActions = planBackgroundActions({
+                        newStatus,
+                        hasActuals: resolvedActuals !== undefined,
+                        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,
+                        expectedSpec: spec,
+                    });
+                    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,
+                            });
                         }
-                        else if (crashShieldSkipReason) {
-                            terminalGateResults['crash-shield'] = 'skip';
+                        catch (rollbackError) {
+                            return buildPersistenceFailureResponse({
+                                specId,
+                                previousStatus: originalStatus,
+                                newStatus,
+                                reason: `${syncResult.warning.reason}; compensation failed: ` +
+                                    (rollbackError instanceof Error ? rollbackError.message : String(rollbackError)),
+                                recoveryRequired: true,
+                            });
                         }
                     }
-                    void recordTerminalTransitionEvent({
+                    const frontmatterSyncWarnings = [];
+                    const transitionId = transitionRecord.transitionId;
+                    const committedAt = transitionRecord.timestamp;
+                    void appendTransitionEvent({
                         projectId,
                         specId,
-                        specPath: updatedSpec.specPath,
-                        newStatus,
+                        eventType: 'transition',
                         from: originalStatus,
-                        actor: actor,
-                        // SPEC-734: sessionId from MCP context params (best-effort)
+                        to: newStatus,
+                        actor,
+                        reason: params.reason,
                         sessionId: params.sessionId,
-                        // SPEC-734: modelId from params or known convention
                         modelId: params.modelId,
-                        gateResults: Object.keys(terminalGateResults).length > 0 ? terminalGateResults : undefined,
-                        meta: transitionEvidenceMeta,
+                        gateResults: sddRoutingGate.gateResults,
+                        meta: { ...transitionEvidenceMeta, transitionId, committedAt },
                     }).catch(() => {
-                        /* best-effort — never block the transition */
+                        /* best-effort — never block the committed acknowledgement */
                     });
-                }
-                // SPEC-544: Final git add after all writes complete (covers auto-advance multi-step transitions)
-                // SPEC-575: Auto-commit staged planu/ docs (idempotent, safe-fail)
-                if (effectiveGatePath &&
-                    updatedSpec.specPath &&
-                    process.env.PLANU_ENABLE_AUTOCOMMIT === 'true' &&
-                    process.env.PLANU_SUPPRESS_AUTOCOMMIT !== 'true') {
-                    try {
-                        const { git: gitCmd } = await import('../git/git-helpers.js');
-                        await gitCmd(effectiveGatePath, ['add', 'planu/']);
-                        const { planuAutoCommit } = await import('./../../engine/git/planu-autocommit.js');
-                        void planuAutoCommit({
-                            projectPath: effectiveGatePath,
+                    if (reverseTransition && params.reason) {
+                        void appendTransitionEvent({
+                            projectId,
                             specId,
-                            reason: newStatus === 'done' ? 'mark-done' : 'status-update',
+                            eventType: 'reopen',
+                            from: originalStatus,
+                            to: newStatus,
+                            actor,
+                            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),
+                            });
                         });
                     }
-                    catch {
-                        // best-effort — never blocks
+                    // 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 */
+                        });
                     }
-                }
-                // If spec is done and has actuals, record metrics
-                if (newStatus === 'done' && resolvedActuals) {
-                    await recordDoneMetrics(projectId, specId, spec, resolvedActuals, knowledge?.projectPath);
-                }
-                // Cascade check: notify downstream specs of the status change
-                const allSpecs = await specStore.listSpecs(projectId);
-                const cascadeResult = cascadeCheck(specId, allSpecs, newStatus);
-                const doneMetrics = computeDoneMetrics(newStatus, spec, resolvedActuals);
-                // SPEC-585: Autopush on done if configured (awaited so result is in autopilotSummary)
-                const autopushResult = newStatus === 'done' && effectiveGatePath
-                    ? await maybeSafePushOnDone(effectiveGatePath, newStatus)
-                    : null;
-                // SPEC-751: Auto-housekeeping post-done — delete merged feat/spec branch + worktree (best-effort)
-                if (newStatus === 'done' && effectiveGatePath) {
-                    void (async () => {
-                        try {
-                            const specBranch = updatedSpec.gitBranch;
-                            if (/^feat\/spec-\d+/.test(specBranch)) {
-                                const { runHousekeepingSweep } = await import('../../engine/housekeeping/index.js');
-                                await runHousekeepingSweep({
-                                    projectPath: effectiveGatePath,
-                                    dryRun: false,
-                                    aggressive: false,
-                                    includeStashes: false,
-                                });
+                    // SPEC-769/SPEC-780: Write qualityWarnings to spec.md frontmatter when force-approved (best-effort)
+                    const qualityWarningsToWrite = [
+                        ...readinessGate.qualityWarnings,
+                        ...formatGate.qualityWarnings,
+                    ];
+                    const specPathForWarnings = updatedSpec.specPath;
+                    if (newStatus === 'approved' &&
+                        qualityWarningsToWrite.length > 0 &&
+                        specPathForWarnings) {
+                        void (async () => {
+                            try {
+                                const { readFile: fsReadFile } = await import('node:fs/promises');
+                                const content = await fsReadFile(specPathForWarnings, 'utf-8');
+                                const warningsJson = JSON.stringify(qualityWarningsToWrite);
+                                const updated = updateFrontmatterField(content, 'qualityWarnings', warningsJson);
+                                await atomicWriteFile(specPathForWarnings, updated);
+                            }
+                            catch {
+                                // best-effort — never blocks the transition
+                            }
+                        })();
+                    }
+                    // SPEC-723: Record terminal transition in hash-chained log (best-effort, fire-and-forget)
+                    // SPEC-734: Thread enriched payload — sessionId, modelId, gateResults
+                    if (newStatus === 'done' || newStatus === 'discarded') {
+                        // Build gateResults from gate outcomes resolved earlier in this handler
+                        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';
+                            }
+                            if (complianceGateResult !== null) {
+                                terminalGateResults.compliance = complianceGateResult.skipped
+                                    ? 'skip'
+                                    : complianceGateResult.blocked
+                                        ? 'fail'
+                                        : 'pass';
+                            }
+                            if (crashRisksReport !== null) {
+                                terminalGateResults['crash-shield'] =
+                                    crashRisksReport.score >= 80 ? 'pass' : 'fail';
+                            }
+                            else if (crashShieldSkipReason) {
+                                terminalGateResults['crash-shield'] = 'skip';
                             }
                         }
-                        catch {
-                            /* best-effort — never block done transition */
+                        void recordTerminalTransitionEvent({
+                            projectId,
+                            specId,
+                            specPath: updatedSpec.specPath,
+                            newStatus,
+                            from: originalStatus,
+                            actor: actor,
+                            // SPEC-734: sessionId from MCP context params (best-effort)
+                            sessionId: params.sessionId,
+                            // SPEC-734: modelId from params or known convention
+                            modelId: params.modelId,
+                            gateResults: Object.keys(terminalGateResults).length > 0 ? terminalGateResults : undefined,
+                            meta: transitionEvidenceMeta,
+                        }).catch(() => {
+                            /* best-effort — never block the transition */
+                        });
+                    }
+                    const allSpecs = await specStore.listSpecs(projectId);
+                    const cascadeResult = cascadeCheck(specId, allSpecs, newStatus);
+                    const doneMetrics = computeDoneMetrics(newStatus, spec, resolvedActuals);
+                    const postCommitTasks = buildPostCommitTasks({
+                        actionNames: plannedBackgroundActions,
+                        projectId,
+                        spec: updatedSpec,
+                        previousStatus: originalStatus,
+                        committedAt,
+                        knowledge,
+                        allSpecs,
+                        validateScore,
+                        actuals: resolvedActuals,
+                        effectiveProjectPath: effectiveGatePath,
+                        versionSnapshotTag,
+                    });
+                    const pendingBackgroundActions = queuePostCommitTasks({
+                        projectId,
+                        specId,
+                        transitionId,
+                        tasks: postCommitTasks,
+                    });
+                    // 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);
+                        }
+                        if (doneActions?.prSuggestion) {
+                            collector.pushOk('pr-created', doneActions.prSuggestion.title);
                         }
-                    })();
-                }
-                // 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);
+                    if (newStatus === 'approved' && versionSnapshotTag) {
+                        collector.pushOk('version-snapshot', `Snapshot queued: ${versionSnapshotTag}`);
                     }
-                    else if (crashShieldSkipReason) {
-                        collector.pushOk('crash-shield', `scan_crash_risks: skipped (${crashShieldSkipReason})`);
+                    if (newStatus === 'implementing' && implActions?.autoBranch) {
+                        collector.pushOk('branch-created', `Branch: ${implActions.autoBranch}`);
                     }
-                    if (doneActions?.mergeWarning) {
-                        collector.pushFail('merge-check', doneActions.mergeWarning);
+                    // SPEC-600: Include cascade summaries from implementing/done actions
+                    if (implActions?.autopilotSummary) {
+                        for (const msg of implActions.autopilotSummary) {
+                            collector.pushOk('cascade', msg);
+                        }
                     }
-                    if (doneActions?.prSuggestion) {
-                        collector.pushOk('pr-created', doneActions.prSuggestion.title);
+                    if (doneActions?.autopilotSummary) {
+                        for (const msg of doneActions.autopilotSummary) {
+                            collector.pushOk('cascade', msg);
+                        }
                     }
-                }
-                if (newStatus === 'approved' && versionSnapshotTag) {
-                    collector.pushOk('version-snapshot', `Snapshot created: ${versionSnapshotTag}`);
-                }
-                if (autopushResult) {
-                    collector.pushOk(autopushResult.label, autopushResult.message);
-                }
-                if (newStatus === 'implementing' && implActions?.autoBranch) {
-                    collector.pushOk('branch-created', `Branch: ${implActions.autoBranch}`);
-                }
-                // SPEC-600: Include cascade summaries from implementing/done actions
-                if (implActions?.autopilotSummary) {
-                    for (const msg of implActions.autopilotSummary) {
-                        collector.pushOk('cascade', msg);
+                    if (stepsExecuted.length > 0) {
+                        collector.pushOk('auto-advance', `Auto-advanced through: ${stepsExecuted.join(' → ')}`);
                     }
-                }
-                if (doneActions?.autopilotSummary) {
-                    for (const msg of doneActions.autopilotSummary) {
-                        collector.pushOk('cascade', msg);
+                    if (cascadeResult.affectedSpecs.length > 0) {
+                        collector.pushOk('cascade', `Notified ${String(cascadeResult.affectedSpecs.length)} downstream spec(s)`);
                     }
+                    const result = compactObj({
+                        specId,
+                        projectId,
+                        previousStatus: originalStatus,
+                        newStatus,
+                        autoAdvanced: stepsExecuted.length > 0 ? true : null,
+                        stepsExecuted: stepsExecuted.length > 0 ? stepsExecuted : null,
+                        actuals: resolvedActuals ?? null,
+                        autoBranch: implActions?.autoBranch ?? null,
+                        protectedBranchWarning: implActions?.protectedBranchWarning ?? null,
+                        mergeWarning: doneActions?.mergeWarning ?? null,
+                        validationWarning: doneActions?.validationWarning ?? null,
+                        uncommittedWarning: doneActions?.uncommittedWarning ?? null,
+                        prSuggestion: doneActions?.prSuggestion ?? null,
+                        implementingSuggestions: implActions?.suggestions ?? null,
+                        codeRealityWarning,
+                        crashShieldWarning,
+                        forcedBypassWarning,
+                        forceAnalyticsWarning,
+                        validateScore,
+                        validateScoreSource,
+                        // SPEC-721: audit ID for the forced validate bypass (null when no bypass occurred)
+                        forceStatusAuditId,
+                        // SPEC-780: audit ID for the forced approve bypass (null when no bypass occurred)
+                        forceApproveAuditId,
+                        // SPEC-1044: audit ID for forced SDD model/context routing bypasses.
+                        sddRoutingAuditId,
+                        sddRoutingGateResults: sddRoutingGate.gateResults,
+                        constitutionWarnings: constitutionWarnings.length > 0 ? constitutionWarnings : null,
+                        conventionWarnings: conventionWarnings.length > 0 ? conventionWarnings : null,
+                        compileWarnings: compileWarnings.length > 0 ? compileWarnings : null,
+                        lintWarnings: lintWarnings.length > 0 ? lintWarnings : null,
+                        testWarnings: testWarnings.length > 0 ? testWarnings : null,
+                        cascade: cascadeResult,
+                        metrics: doneMetrics,
+                        complianceGateResult,
+                        versionSnapshotTag,
+                        orchestrationPlan,
+                        committed: true,
+                        transitionId,
+                        committedAt,
+                        idempotent: false,
+                        pendingBackgroundActions,
+                        // SPEC-728: DepGuard result (null when gate was not applicable)
+                        depGuard: depGuardResult,
+                        // SPEC-698: surface frontmatter sync failures in the response
+                        frontmatterSyncWarnings: frontmatterSyncWarnings.length > 0 ? frontmatterSyncWarnings : null,
+                        updatedAt: updatedSpec.updatedAt,
+                        message: ti('tools.update_status.success', { specId, status: newStatus }),
+                        ...(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);
                 }
-                if (stepsExecuted.length > 0) {
-                    collector.pushOk('auto-advance', `Auto-advanced through: ${stepsExecuted.join(' → ')}`);
-                }
-                if (cascadeResult.affectedSpecs.length > 0) {
-                    collector.pushOk('cascade', `Notified ${String(cascadeResult.affectedSpecs.length)} downstream spec(s)`);
-                }
-                const result = compactObj({
-                    specId,
-                    projectId,
-                    previousStatus: originalStatus,
-                    newStatus,
-                    autoAdvanced: stepsExecuted.length > 0 ? true : null,
-                    stepsExecuted: stepsExecuted.length > 0 ? stepsExecuted : null,
-                    actuals: resolvedActuals ?? null,
-                    autoBranch: implActions?.autoBranch ?? null,
-                    protectedBranchWarning: implActions?.protectedBranchWarning ?? null,
-                    mergeWarning: doneActions?.mergeWarning ?? null,
-                    validationWarning: doneActions?.validationWarning ?? null,
-                    uncommittedWarning: doneActions?.uncommittedWarning ?? null,
-                    prSuggestion: doneActions?.prSuggestion ?? null,
-                    implementingSuggestions: implActions?.suggestions ?? null,
-                    codeRealityWarning,
-                    crashShieldWarning,
-                    forcedBypassWarning,
-                    forceAnalyticsWarning,
-                    validateScore,
-                    validateScoreSource,
-                    // SPEC-721: audit ID for the forced validate bypass (null when no bypass occurred)
-                    forceStatusAuditId,
-                    // SPEC-780: audit ID for the forced approve bypass (null when no bypass occurred)
-                    forceApproveAuditId,
-                    // SPEC-1044: audit ID for forced SDD model/context routing bypasses.
-                    sddRoutingAuditId,
-                    sddRoutingGateResults: sddRoutingGate.gateResults,
-                    constitutionWarnings: constitutionWarnings.length > 0 ? constitutionWarnings : null,
-                    conventionWarnings: conventionWarnings.length > 0 ? conventionWarnings : null,
-                    compileWarnings: compileWarnings.length > 0 ? compileWarnings : null,
-                    lintWarnings: lintWarnings.length > 0 ? lintWarnings : null,
-                    testWarnings: testWarnings.length > 0 ? testWarnings : null,
-                    cascade: cascadeResult,
-                    metrics: doneMetrics,
-                    complianceGateResult,
-                    versionSnapshotTag,
-                    orchestrationPlan,
-                    // SPEC-728: DepGuard result (null when gate was not applicable)
-                    depGuard: depGuardResult,
-                    // SPEC-698: surface frontmatter sync failures in the response
-                    frontmatterSyncWarnings: frontmatterSyncWarnings.length > 0 ? frontmatterSyncWarnings : null,
-                    updatedAt: updatedSpec.updatedAt,
-                    message: ti('tools.update_status.success', { specId, status: newStatus }),
-                    ...(collector.hasEntries() ? { autopilotSummary: collector.getMessages() } : {}),
-                });
-                // SPEC-772: Run cascade — fast hooks awaited (results go into response), slow hooks fire-and-forget
-                const cascadeRunResult = await runCascadeForResponse({
-                    knowledge,
-                    allSpecs,
-                    specId,
-                    newStatus,
-                    validateScore,
-                    projectId,
-                    spec,
-                    currentStatus: originalStatus,
-                });
-                // Include fast hook results in response (Scenario 1: fast cascade results in humanSummary)
-                if (cascadeRunResult && cascadeRunResult.fastHookResults.length > 0) {
-                    result.cascadeFastResults = cascadeRunResult.fastHookResults;
-                }
-                // 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;
-                }
-                // Auto-reconcile token costs when spec reaches done (best-effort, non-blocking)
-                const reconciliationMarkdown = await tryReconcile(newStatus, specId, projectId);
-                // 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, reconciliationMarkdown, 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),
+                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),
+                            });
                         });
-                    });
+                    }
                 }
             }
-        }
-        catch (error) {
-            if (error instanceof LockBusyError) {
+            catch (error) {
+                if (error instanceof LockBusyError) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Spec ${specId} is locked by another process (LOCK_BUSY). Retry later.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const message = error instanceof Error ? error.message : String(error);
                 return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Spec ${specId} is locked by another process (LOCK_BUSY). Retry later.`,
-                        },
-                    ],
+                    content: [{ type: 'text', text: ti('errors.internalError', { message }) }],
                     isError: true,
                 };
             }
-            const message = error instanceof Error ? error.message : String(error);
-            return {
-                content: [{ type: 'text', text: ti('errors.internalError', { message }) }],
-                isError: true,
-            };
-        }
+        });
     }); // end trackCost
 }
 //# sourceMappingURL=index.js.map