@planu/cli 4.11.2 → 4.11.4

package/dist/tools/register-spec-tools/core-spec-tools.js

@@ -167,8 +167,17 @@ export function registerCoreSpecTools(server) {
                 .number()
                 .optional()
                 .describe('Maximum number of questions to generate (default: 5)'),
+            sessionId: z
+                .string()
+                .max(500)
+                .optional()
+                .describe('Existing clarification session to resume with user-confirmed answers.'),
+            answers: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Explicit user-confirmed answers keyed by clarification question ID.'),
         },
-    }, safeTracked('clarify_requirements', async (args) => handleClarifyRequirements(args)));
+    }, safeTracked('clarify_requirements', async (args) => handleClarifyRequirements(args, server)));
     // 5. create_spec
     server.registerTool('create_spec', {
         description: t('tools.create_spec.description'),
@@ -210,7 +219,7 @@ export function registerCoreSpecTools(server) {
             outOfScope: z
                 .array(z.string())
                 .optional()
-                .describe('SPEC-612: Explicit out-of-scope items for this spec. If omitted, Planu auto-suggests based on the description.'),
+                .describe('Explicit user-confirmed out-of-scope items for this spec.'),
             specId: z
                 .string()
                 .optional()

package/dist/tools/suggest-stack.js

@@ -7,20 +7,26 @@ import { adjustRecommendationRanking } from '../engine/self-improver.js';
 export async function handleSuggestStack(args) {
     const { projectType, requirements, constraints = [], projectId } = args;
     // If projectId provided, enrich with project knowledge
-    let contextInfo = '';
+    const projectEvidence = [];
     if (projectId) {
         const knowledge = await knowledgeStore.getKnowledge(projectId);
         if (knowledge) {
-            contextInfo =
-                `\n\n**Project context:** ${knowledge.language}` +
-                    (knowledge.framework ? ` / ${knowledge.framework}` : '') +
-                    ` — architecture: ${knowledge.architecture.primary}` +
-                    ` — database: ${knowledge.database}`;
+            if (knowledge.language !== 'unknown') {
+                projectEvidence.push(`language=${knowledge.language}`);
+            }
+            if (knowledge.framework) {
+                projectEvidence.push(`framework=${knowledge.framework}`);
+            }
+            projectEvidence.push(`architecture=${knowledge.architecture.primary}`);
+            if (knowledge.database !== 'unknown') {
+                projectEvidence.push(`database=${knowledge.database}`);
+            }
         }
     }
     // SPEC-012: Load developer preferences to adjust recommendation ranking
     const developerPrefs = await globalStore.getDeveloperPreferences();
     const result = await suggestStack(projectType, requirements, constraints);
+    const grounding = result;
     // Apply developer preference rankings to ecosystem items
     const ecosystemItems = [...result.primary.ecosystem, ...result.alternative.ecosystem];
     const rankings = adjustRecommendationRanking(ecosystemItems, developerPrefs);
@@ -28,11 +34,14 @@ export async function handleSuggestStack(args) {
     const rejectedItems = [...rankings.entries()]
         .filter(([, score]) => score < -1)
         .map(([tool]) => tool);
-    // Format primary recommendation
+    // Recommendations remain candidates until the user confirms a choice.
     const primaryLines = [
         `## ${t('tools.suggest_stack.description')}`,
         '',
-        '### Primary Recommendation',
+        grounding.candidateNotice ??
+            'Recommendations are optional candidates. This tool does not select or persist a stack.',
+        '',
+        '### Candidate A (unconfirmed)',
         '',
         `| Aspect | Value |`,
         `|--------|-------|`,
@@ -48,10 +57,10 @@ export async function handleSuggestStack(args) {
         '',
         `**Ecosystem:** ${result.primary.ecosystem.join(', ')}`,
     ].filter(Boolean);
-    // Format alternative
+    // Format alternative candidate
     const altLines = [
         '',
-        '### Alternative Recommendation',
+        '### Candidate B (unconfirmed)',
         '',
         `| Aspect | Value |`,
         `|--------|-------|`,
@@ -67,10 +76,10 @@ export async function handleSuggestStack(args) {
         '',
         `**Ecosystem:** ${result.alternative.ecosystem.join(', ')}`,
     ].filter(Boolean);
-    // Why not others
+    // Other optional candidates
     const whyNotLines = [
         '',
-        '### Why Not Others',
+        '### Other Candidates Considered',
         '',
         ...result.whyNotOthers.map((w) => `- **${w.name}:** ${w.reason}`),
     ];
@@ -86,18 +95,45 @@ export async function handleSuggestStack(args) {
     const prefsNote = rejectedItems.length > 0
         ? `\n\n> **Note:** Based on your preferences, these were previously rejected: ${rejectedItems.join(', ')}`
         : '';
+    const detectedEvidence = [
+        ...projectEvidence.map((item) => `project:${item}`),
+        ...(grounding.detectedEvidence ?? []),
+    ];
+    const evidenceLines = [
+        '',
+        '### Detected Evidence',
+        '',
+        ...(detectedEvidence.length > 0
+            ? detectedEvidence.map((item) => `- ${item}`)
+            : ['- No stack evidence was detected.']),
+        '',
+        '### User-Confirmed Choices',
+        '',
+        ...((grounding.confirmedChoices ?? []).length > 0
+            ? (grounding.confirmedChoices ?? []).map((choice) => `- ${choice.field}: ${choice.value}`)
+            : ['- None.']),
+    ];
     const text = [
         ...primaryLines,
         ...altLines,
         ...whyNotLines,
         ...mcpLines,
-        contextInfo,
+        ...evidenceLines,
         prefsNote,
         '',
         `_Last checked: ${result.lastChecked}_`,
     ].join('\n');
     return {
         content: [{ type: 'text', text }],
+        structuredContent: {
+            selectionStatus: grounding.selectionStatus ?? 'unconfirmed',
+            detectedEvidence,
+            confirmedChoices: grounding.confirmedChoices ?? [],
+            candidates: [
+                { id: 'candidate-a', status: 'candidate', stack: result.primary },
+                { id: 'candidate-b', status: 'candidate', stack: result.alternative },
+            ],
+        },
     };
 }
 //# sourceMappingURL=suggest-stack.js.map

package/dist/tools/update-status/dod-gates.d.ts

@@ -30,6 +30,13 @@ export type ValidateGateResult = {
     forcedReason: string;
     scoreSource: 'forced-best-effort-validateSpec';
 };
+export type ValidationReportGateResult = {
+    ok: true;
+    score: number | null;
+} | {
+    ok: false;
+    error: ToolResult;
+};
 /**
  * SPEC-721 / SPEC-222 Trigger 1: Run validate engine before marking done.
  *
@@ -79,6 +86,7 @@ export interface DoneGateResult {
  * with reviewer evidence and all validation gates passing.
  */
 export declare function checkValidationReportGate(specId: string, projectId: string, force: boolean | undefined): Promise<ToolResult | null>;
+export declare function readApprovedValidationReportGate(specId: string, projectId: string, force: boolean | undefined): Promise<ValidationReportGateResult>;
 /** SPEC-1051: Write spec-review evidence when a spec enters review. */
 export declare function writeSpecReviewArtifact(spec: Spec, specId: string, projectId: string): Promise<ToolResult | null>;
 /** SPEC-1051: Approval requires a dedicated spec reviewer artifact. */

package/dist/tools/update-status/dod-gates.js

@@ -280,8 +280,12 @@ async function recordForceDoneBypass(specId, projectId, reason, failingItems, wa
  * with reviewer evidence and all validation gates passing.
  */
 export async function checkValidationReportGate(specId, projectId, force) {
+    const result = await readApprovedValidationReportGate(specId, projectId, force);
+    return result.ok ? null : result.error;
+}
+export async function readApprovedValidationReportGate(specId, projectId, force) {
     if (force) {
-        return null;
+        return { ok: true, score: null };
     }
     try {
         const { readArtifact } = await import('../../engine/handoff-artifacts/io.js');
@@ -289,60 +293,81 @@ export async function checkValidationReportGate(specId, projectId, force) {
         if (!result.ok) {
             const firstErr = result.errors[0];
             if (firstErr?.code === 'ARTIFACT_NOT_FOUND') {
-                return validationReportGateError({
+                return {
+                    ok: false,
+                    error: validationReportGateError({
+                        specId,
+                        error: 'validation_report_missing',
+                        message: 'No validation-report artifact exists for this spec. Run validate to generate implementation-review evidence before marking done.',
+                        gates: [],
+                        fixHint: 'Run validate for this spec, fix any failing gates, then retry update_status(done). Use force:true only with an audited reason.',
+                    }),
+                };
+            }
+            return {
+                ok: false,
+                error: validationReportGateError({
                     specId,
-                    error: 'validation_report_missing',
-                    message: 'No validation-report artifact exists for this spec. Run validate to generate implementation-review evidence before marking done.',
+                    error: 'validation_report_invalid',
+                    message: 'The validation-report artifact is malformed or uses an obsolete schema. Re-run validate so Planu can generate reviewer evidence.',
                     gates: [],
-                    fixHint: 'Run validate for this spec, fix any failing gates, then retry update_status(done). Use force:true only with an audited reason.',
-                });
-            }
-            return validationReportGateError({
-                specId,
-                error: 'validation_report_invalid',
-                message: 'The validation-report artifact is malformed or uses an obsolete schema. Re-run validate so Planu can generate reviewer evidence.',
-                gates: [],
-                fixHint: 'Re-run validate for this spec. The report must include reviewer evidence and passing gates.',
-            });
+                    fixHint: 'Re-run validate for this spec. The report must include reviewer evidence and passing gates.',
+                }),
+            };
         }
         if (!result.payload.passed) {
-            return validationReportGateError({
-                specId,
-                error: 'validation_report_failed',
-                message: 'Validation report has passed:false — fix all failing gates before marking done.',
-                gates: result.payload.gates,
-                fixHint: 'Fix failing gates and re-run validate before marking done.',
-            });
+            return {
+                ok: false,
+                error: validationReportGateError({
+                    specId,
+                    error: 'validation_report_failed',
+                    message: 'Validation report has passed:false — fix all failing gates before marking done.',
+                    gates: result.payload.gates,
+                    fixHint: 'Fix failing gates and re-run validate before marking done.',
+                }),
+            };
         }
         if (result.payload.minimalityReport?.blocked) {
-            return validationReportGateError({
-                specId,
-                error: 'minimality_findings_block_done',
-                message: 'Validation report contains blocking minimal implementation findings. Remove avoidable complexity or provide an audited forceStatusReason.',
-                gates: result.payload.gates,
-                fixHint: 'Fix blocking minimality findings and re-run validate before marking done. Use forceStatus only with an audited reason for accepted complexity.',
-            });
+            return {
+                ok: false,
+                error: validationReportGateError({
+                    specId,
+                    error: 'minimality_findings_block_done',
+                    message: 'Validation report contains blocking minimal implementation findings. Remove avoidable complexity or provide an audited forceStatusReason.',
+                    gates: result.payload.gates,
+                    fixHint: 'Fix blocking minimality findings and re-run validate before marking done. Use forceStatus only with an audited reason for accepted complexity.',
+                }),
+            };
         }
         if (result.payload.reviewer.verdict !== 'approved' ||
             result.payload.reviewer.agent.trim().length === 0) {
-            return validationReportGateError({
-                specId,
-                error: 'validation_report_reviewer_not_approved',
-                message: 'The implementation reviewer did not approve this spec. Fix the requested changes and re-run validate.',
-                gates: result.payload.gates,
-                fixHint: 'Fix reviewer findings and re-run validate before marking done.',
-            });
+            return {
+                ok: false,
+                error: validationReportGateError({
+                    specId,
+                    error: 'validation_report_reviewer_not_approved',
+                    message: 'The implementation reviewer did not approve this spec. Fix the requested changes and re-run validate.',
+                    gates: result.payload.gates,
+                    fixHint: 'Fix reviewer findings and re-run validate before marking done.',
+                }),
+            };
         }
-        return null;
+        return {
+            ok: true,
+            score: typeof result.payload.score === 'number' ? result.payload.score : null,
+        };
     }
     catch (err) {
-        return validationReportGateError({
-            specId,
-            error: 'validation_report_unreadable',
-            message: `Could not read validation-report artifact: ${err instanceof Error ? err.message : String(err)}`,
-            gates: [],
-            fixHint: 'Re-run validate for this spec, then retry update_status(done).',
-        });
+        return {
+            ok: false,
+            error: validationReportGateError({
+                specId,
+                error: 'validation_report_unreadable',
+                message: `Could not read validation-report artifact: ${err instanceof Error ? err.message : String(err)}`,
+                gates: [],
+                fixHint: 'Re-run validate for this spec, then retry update_status(done).',
+            }),
+        };
     }
 }
 /** SPEC-1051: Write spec-review evidence when a spec enters review. */

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

@@ -13,7 +13,7 @@ import { checkApprovedDepGate } from '../../engine/dep-guard/index.js';
 import { checkApprovalGate } from '../../engine/approval-workflow.js';
 import * as approvalStore from '../../storage/approval-store.js';
 import { isLocked, getLock } from '../../storage/spec-lock-store.js';
-import { runValidateGate, checkDoneGates, checkComplianceGate, checkQaGate, checkApprovedFormatGate, checkValidationReportGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
+import { runValidateGate, checkDoneGates, checkComplianceGate, checkQaGate, checkApprovedFormatGate, checkValidationReportGate, readApprovedValidationReportGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
 import { checkLifecycleEvidenceTransitionGate } from './evidence-gate.js';
 import { buildStatusResponse, buildValidateBlockedResponse, buildDryRunResponse, } from './response-builder.js';
 import { recordDoneMetrics, syncSpecFiles, tryReconcile, recordTerminalTransitionEvent, } from './file-sync.js';
@@ -43,23 +43,12 @@ import { validateStrictLayoutOrError } from '../validate-helpers.js';
  * (e.g. draft → approved) without receiving an error.
  * Returns the list of states executed, or an empty array if none were needed.
  */
-async function runAutoAdvance(projectId, specId, currentStatus, targetStatus) {
-    const steps = resolveAutoAdvanceSteps(currentStatus, targetStatus);
-    if (!steps || steps.length === 0) {
-        return { updatedCurrentStatus: currentStatus, stepsExecuted: [] };
-    }
-    let updatedCurrentStatus = currentStatus;
-    const stepsExecuted = [];
-    for (const intermediateStatus of steps) {
-        // SPEC-720: route through transitionSpec — single entry point for status writes
-        await transitionSpec(projectId, specId, intermediateStatus, {
-            trigger: 'auto-advance',
-            actor: 'system',
-        });
-        stepsExecuted.push(intermediateStatus);
-        updatedCurrentStatus = intermediateStatus;
-    }
-    return { updatedCurrentStatus, stepsExecuted };
+function buildAutoAdvancePlan(currentStatus, targetStatus) {
+    const stepsExecuted = resolveAutoAdvanceSteps(currentStatus, targetStatus) ?? [];
+    return {
+        plannedStatuses: [...stepsExecuted, targetStatus],
+        stepsExecuted,
+    };
 }
 /**
  * SPEC-301: Check if spec is locked by another agent.
@@ -335,19 +324,28 @@ export async function handleUpdateStatus(params, server) {
                 }
             }
             try {
-                // SPEC-280: auto-advance silently through intermediate states (e.g. draft → approved)
-                const { updatedCurrentStatus, stepsExecuted } = await runAutoAdvance(projectId, specId, spec.status, newStatus);
-                const currentStatus = updatedCurrentStatus;
-                // Idempotent or invalid transition check — returns early if no change needed or blocked
-                const transitionError = checkIdempotentOrTransition(specId, currentStatus, newStatus);
-                if (transitionError) {
-                    return transitionError;
+                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-733: Detect reverse transition and validate mandatory reason
-                const reverseTransition = isReverseTransition(currentStatus, newStatus);
+                const reverseTransition = isReverseTransition(spec.status, newStatus);
                 if (reverseTransition) {
                     const reverseValidation = validateReverseTransition({
-                        from: currentStatus,
+                        from: spec.status,
                         to: newStatus,
                         reason: params.reason,
                     });
@@ -373,33 +371,35 @@ export async function handleUpdateStatus(params, server) {
                     }
                 }
                 // Gate: approval policy must be satisfied before transitioning to 'approved'
-                const approvalError = await checkApprovalPolicyGate(projectId, specId, newStatus);
+                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 dorError = checkDorGate(spec, specId, projectId, newStatus);
+                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, newStatus, params.forceApprove);
+                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, newStatus);
+                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, newStatus, params.forceApprove);
+                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 (newStatus === 'approved') {
+                if (plannedStatuses.includes('approved')) {
                     const allSpecsForDepGuard = await specStore.listSpecs(projectId);
                     depGuardResult = checkApprovedDepGate(spec, allSpecsForDepGuard);
                     if (depGuardResult.blocked) {
@@ -417,17 +417,12 @@ export async function handleUpdateStatus(params, server) {
                     }
                 }
                 // SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
-                const challengeGate = checkChallengeGate(spec, newStatus);
+                const challengeGateStatus = plannedStatuses.includes('review') ? 'review' : newStatus;
+                const challengeGate = checkChallengeGate(spec, challengeGateStatus);
                 if (challengeGate) {
                     return challengeGate;
                 }
-                if (newStatus === 'review') {
-                    const specReviewWriteError = await writeSpecReviewArtifact(spec, specId, projectId);
-                    if (specReviewWriteError) {
-                        return specReviewWriteError;
-                    }
-                }
-                if (newStatus === 'approved') {
+                if (plannedStatuses.includes('approved')) {
                     const specReviewError = await checkSpecReviewGate(specId, projectId, params.forceApprove);
                     if (specReviewError) {
                         return specReviewError;
@@ -443,34 +438,45 @@ export async function handleUpdateStatus(params, server) {
                 // 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 = shouldSkipSddRoutingGateForLegacyTestHarness()
-                    ? {
-                        blockResult: null,
-                        gateResults: { sddModelRouting: 'skip' },
-                        forcedReasons: [],
+                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';
                     }
-                    : await checkSddModelRoutingGate({
-                        params,
-                        status: newStatus,
-                        projectPath: effectiveGatePath,
-                    });
-                if (sddRoutingGate.blockResult) {
-                    return sddRoutingGate.blockResult;
                 }
                 // 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() &&
-                    (newStatus === 'approved' || newStatus === 'implementing' || newStatus === 'done')) {
-                    const evidenceGate = await checkLifecycleEvidenceTransitionGate({
-                        spec,
-                        specId,
-                        projectId,
-                        projectPath: effectiveGatePath,
-                        transition: newStatus,
-                    });
-                    if (evidenceGate !== null) {
-                        return evidenceGate;
+                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;
+                        }
                     }
                 }
                 // ---------------------------------------------------------------------------
@@ -522,21 +528,37 @@ export async function handleUpdateStatus(params, server) {
                 let crashShieldWarning = null;
                 let crashShieldSkipReason = null;
                 let complianceGateResult = null;
+                let validationReportGate = null;
+                if (newStatus === 'done' && !(params.force ?? params.forceStatus ?? false)) {
+                    validationReportGate = await readApprovedValidationReportGate(specId, projectId, false);
+                    if (!validationReportGate.ok) {
+                        return validationReportGate.error;
+                    }
+                }
                 // SPEC-628: Rate-limit crash scan — check before entering the parallel batch
                 crashShieldSkipReason = await checkCrashScanRateLimit(newStatus, effectiveGatePath ?? null);
+                const approvedValidationReportScore = validationReportGate?.ok === true && validationReportGate.score === 100
+                    ? validationReportGate.score
+                    : 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 })
+                        ? approvedValidationReportScore !== null
+                            ? Promise.resolve({
+                                blocked: false,
+                                score: approvedValidationReportScore,
+                                forced: false,
+                            })
+                            : 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.
-                    newStatus === 'review'
+                    plannedStatuses.includes('review')
                         ? withToolTimeout(checkComplianceGate(specId, projectId, effectiveGatePath), 9_000, {
                             skipped: true,
                             blocked: false,
@@ -560,10 +582,13 @@ export async function handleUpdateStatus(params, server) {
                         };
                     }
                     else {
-                        validateScoreSource = 'validateSpec';
+                        validateScoreSource =
+                            approvedValidationReportScore !== null ? 'validation-report' : 'validateSpec';
                     }
                 }
-                if (newStatus === 'done' && !(params.force ?? params.forceStatus ?? false)) {
+                if (newStatus === 'done' &&
+                    !(params.force ?? params.forceStatus ?? false) &&
+                    validationReportGate === null) {
                     const validationReportError = await checkValidationReportGate(specId, projectId, false);
                     if (validationReportError) {
                         return validationReportError;
@@ -600,14 +625,14 @@ export async function handleUpdateStatus(params, server) {
                 // Process compliance gate result — may block on 'review'
                 if (complianceResult !== null) {
                     complianceGateResult = complianceResult;
-                    if (newStatus === 'review' && complianceResult.blocked) {
+                    if (plannedStatuses.includes('review') && complianceResult.blocked) {
                         return buildBlockedByComplianceResponse(specId, complianceResult);
                     }
                 }
                 // SPEC-190: Run all compliance gates in parallel (convention + constitution + compile + lint + test, non-blocking)
                 // runComplianceGates internally skips heavy commands (compile/lint/test) for non-done transitions,
                 // but 'approved' still needs constitutionWarnings — so run for 'done' and 'approved' only.
-                const { conventionWarnings, constitutionWarnings, compileWarnings, lintWarnings, testWarnings, } = newStatus === 'done' || newStatus === 'approved'
+                const { conventionWarnings, constitutionWarnings, compileWarnings, lintWarnings, testWarnings, } = newStatus === 'done' || plannedStatuses.includes('approved')
                     ? await runComplianceGates(projectId, spec.title, spec.tags, newStatus)
                     : {
                         conventionWarnings: [],
@@ -645,6 +670,14 @@ export async function handleUpdateStatus(params, server) {
                         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;
+                    }
+                }
                 // Explicit actuals are preserved verbatim. Provider usage and cost are never inferred.
                 const resolvedActuals = actuals;
                 // Run transition-specific actions
@@ -653,7 +686,9 @@ export async function handleUpdateStatus(params, server) {
                 // SPEC-720: Step 1 — Transition the status through the single authorised path
                 const trigger = reverseTransition
                     ? 'reopen'
-                    : (params.trigger ?? 'user');
+                    : stepsExecuted.length > 0
+                        ? 'auto-advance'
+                        : (params.trigger ?? 'user');
                 const actor = params.actor ?? 'system';
                 const viaSync = params.viaSync ?? false;
                 await transitionSpec(projectId, specId, newStatus, {
@@ -674,7 +709,7 @@ export async function handleUpdateStatus(params, server) {
                     projectId,
                     specId,
                     eventType: 'transition',
-                    from: currentStatus,
+                    from: originalStatus,
                     to: newStatus,
                     actor,
                     reason: params.reason,
@@ -691,7 +726,7 @@ export async function handleUpdateStatus(params, server) {
                         projectId,
                         specId,
                         eventType: 'reopen',
-                        from: currentStatus,
+                        from: originalStatus,
                         to: newStatus,
                         actor,
                         reason: params.reason,
@@ -1106,7 +1141,7 @@ export async function handleUpdateStatus(params, server) {
                 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, currentStatus, newStatus, reconciliationMarkdown, spec.title, shellHygieneHint);
+                return buildStatusResponse(result, specId, originalStatus, newStatus, reconciliationMarkdown, spec.title, shellHygieneHint);
             }
             finally {
                 // SPEC-719: Release cross-process lock in all exit paths (return, throw)