@planu/cli 4.11.1 → 4.11.3

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

@@ -13,11 +13,9 @@ 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 { getSuggestedMode } from './mode-hints.js';
-import { autoFillActuals, createDefaultActuals } from '../../engine/actuals-estimator.js';
 import { recordDoneMetrics, syncSpecFiles, tryReconcile, recordTerminalTransitionEvent, } from './file-sync.js';
 import { appendEntry, getLastHash } from '../../storage/audit-trail-store.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
@@ -45,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.
@@ -117,18 +104,18 @@ function computeDoneMetrics(newStatus, spec, actuals) {
     if (newStatus !== 'done' || actuals === undefined || spec === null) {
         return null;
     }
+    const actualHours = actuals.devHours + actuals.reviewHours;
+    if (actualHours === 0) {
+        return null;
+    }
     return {
-        accuracyScore: calculateAccuracy(spec.estimation, actuals.devHours + actuals.reviewHours),
+        accuracyScore: calculateAccuracy(spec.estimation, actualHours),
         estimatedHours: spec.estimation.devHours + spec.estimation.reviewHours,
-        actualHours: actuals.devHours + actuals.reviewHours,
+        actualHours,
         estimatedCost: spec.estimation.totalCostUsd,
         actualCost: actuals.totalCostUsd,
     };
 }
-/** Extract recordActualHint from doneActions without adding cyclomatic complexity inline. */
-function extractRecordActualHint(doneActions) {
-    return doneActions?.recordActualHint;
-}
 /** SPEC-447: Build a blocked-by-compliance response. */
 function buildBlockedByComplianceResponse(_specId, result) {
     const scoreStr = result.score !== null ? String(result.score) : 'N/A';
@@ -269,6 +256,22 @@ export async function handleUpdateStatus(params, server) {
                 };
             }
             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) {
@@ -321,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,
                     });
@@ -359,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) {
@@ -403,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;
@@ -429,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;
+                        }
                     }
                 }
                 // ---------------------------------------------------------------------------
@@ -477,7 +497,7 @@ export async function handleUpdateStatus(params, server) {
                 let forcedBypassWarning = null;
                 const [codeRealityResult, doneGatesResult] = await Promise.all([
                     // Code reality: only relevant for 'implementing'
-                    newStatus === 'implementing' && effectiveGatePath
+                    newStatus === 'implementing' && !reverseTransition && effectiveGatePath
                         ? checkCodeReality(effectiveGatePath, spec.title).catch(() => null)
                         : Promise.resolve(null),
                     // Done gates: only relevant for 'done'
@@ -508,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),
-                    // Compliance gate: only on 'done' or 'implementing' (score-compliance is heavy) — hard deadline 9s
-                    newStatus === 'done' || newStatus === 'implementing' || newStatus === 'review'
+                    // 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,
@@ -546,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;
@@ -586,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: [],
@@ -631,25 +670,25 @@ export async function handleUpdateStatus(params, server) {
                         blockingReasons: [],
                     });
                 }
-                // SPEC-495: Auto-generate actuals when not provided; auto-fill zeros when provided
-                let resolvedActuals = actuals;
-                if (newStatus === 'done') {
-                    if (!resolvedActuals) {
-                        // Agent did not pass actuals at all — create from spec estimation
-                        resolvedActuals = createDefaultActuals(spec.estimation);
-                    }
-                    else {
-                        // Agent passed actuals but tokens/costs are zero — auto-fill
-                        resolvedActuals = autoFillActuals(resolvedActuals, spec.estimation);
+                // 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
                 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'
-                    : (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, {
@@ -670,7 +709,7 @@ export async function handleUpdateStatus(params, server) {
                     projectId,
                     specId,
                     eventType: 'transition',
-                    from: currentStatus,
+                    from: originalStatus,
                     to: newStatus,
                     actor,
                     reason: params.reason,
@@ -687,7 +726,7 @@ export async function handleUpdateStatus(params, server) {
                         projectId,
                         specId,
                         eventType: 'reopen',
-                        from: currentStatus,
+                        from: originalStatus,
                         to: newStatus,
                         actor,
                         reason: params.reason,
@@ -1030,7 +1069,6 @@ export async function handleUpdateStatus(params, server) {
                 if (cascadeResult.affectedSpecs.length > 0) {
                     collector.pushOk('cascade', `Notified ${String(cascadeResult.affectedSpecs.length)} downstream spec(s)`);
                 }
-                const modeSuggestion = getSuggestedMode(newStatus);
                 const result = compactObj({
                     specId,
                     projectId,
@@ -1068,8 +1106,6 @@ export async function handleUpdateStatus(params, server) {
                     metrics: doneMetrics,
                     complianceGateResult,
                     versionSnapshotTag,
-                    suggestedClaudeMode: modeSuggestion?.mode ?? null,
-                    modeHint: modeSuggestion?.hint ?? null,
                     orchestrationPlan,
                     // SPEC-728: DepGuard result (null when gate was not applicable)
                     depGuard: depGuardResult,
@@ -1105,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, extractRecordActualHint(doneActions), 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)

package/dist/tools/update-status/qa-gate.js

@@ -9,6 +9,9 @@ export async function checkQaGate(spec, projectPath, force) {
     if (state?.lastResult?.passed === true) {
         return null;
     }
+    if (await hasPassedExternalQaEvidence(spec, projectPath)) {
+        return null;
+    }
     let effectiveResult = state?.lastResult ?? null;
     if (effectiveResult === null) {
         const { runQaGate } = await import('../../engine/qa-gate.js');
@@ -47,4 +50,27 @@ export async function checkQaGate(spec, projectPath, force) {
         },
     };
 }
+async function hasPassedExternalQaEvidence(spec, projectPath) {
+    try {
+        const { readEvidenceArtifacts } = await import('../../engine/evidence-gates/artifact-reader.js');
+        const artifacts = await readEvidenceArtifacts({
+            spec,
+            projectId: spec.projectId,
+            specId: spec.id,
+            projectPath,
+        });
+        const rows = artifacts.traceabilityMatrix?.rows ?? [];
+        return rows.length > 0 && rows.every((row) => isPassedQaEvidence(row.validationEvidence));
+    }
+    catch {
+        return false;
+    }
+}
+function isPassedQaEvidence(value) {
+    if (!value) {
+        return false;
+    }
+    return (/\b(?:pnpm\s+validate|pnpm\s+test|pnpm\s+typecheck)\b[\s\S]{0,120}\bpass(?:ed|ing)?\b/i.test(value) ||
+        /\bpass(?:ed|ing)?\b[\s\S]{0,120}\b(?:pnpm\s+validate|pnpm\s+test|pnpm\s+typecheck)\b/i.test(value));
+}
 //# sourceMappingURL=qa-gate.js.map

package/dist/tools/update-status/response-builder.d.ts

@@ -13,5 +13,5 @@ export declare function buildValidateBlockedResponse(specId: string, result: Ext
  */
 export declare function buildDryRunResponse(dryRunResult: DryRunResult): ToolResult;
 export declare const STATUS_EMOJIS: Record<SpecStatus, string>;
-export declare function buildStatusResponse(result: Record<string, unknown>, specId: string, currentStatus: SpecStatus, newStatus: SpecStatus, reconciliationMarkdown?: string | null, recordActualHint?: string | null, specTitle?: string, shellHygieneHint?: string | null): ToolResult;
+export declare function buildStatusResponse(result: Record<string, unknown>, specId: string, currentStatus: SpecStatus, newStatus: SpecStatus, reconciliationMarkdown?: string | null, specTitle?: string, shellHygieneHint?: string | null): ToolResult;
 //# sourceMappingURL=response-builder.d.ts.map

package/dist/tools/update-status/response-builder.js

@@ -79,7 +79,7 @@ export const STATUS_EMOJIS = {
     discarded: '🗑️',
 };
 // eslint-disable-next-line complexity -- aggregates many host- and status-specific branches
-export function buildStatusResponse(result, specId, currentStatus, newStatus, reconciliationMarkdown, recordActualHint, specTitle, shellHygieneHint) {
+export function buildStatusResponse(result, specId, currentStatus, newStatus, reconciliationMarkdown, specTitle, shellHygieneHint) {
     const fromEmoji = STATUS_EMOJIS[currentStatus];
     const toEmoji = STATUS_EMOJIS[newStatus];
     const r = result;
@@ -102,18 +102,15 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
         lines.push(`\n🔗 ${r.prSuggestion.title}`);
     }
     if (r.metrics) {
-        lines.push(`\n📊 Accuracy: ${Math.round(r.metrics.accuracyScore * 100)}% | ` +
+        lines.push(`\n📊 Accuracy: ${Math.round(r.metrics.accuracyScore)}% | ` +
             `Estimated: ${String(r.metrics.estimatedHours)}h → Actual: ${String(r.metrics.actualHours)}h`);
     }
     if (r.actuals && (r.actuals.tokensOpus > 0 || r.actuals.tokensSonnet > 0)) {
-        const prefix = r.actuals.estimated ? '~' : '';
-        const opus = r.actuals.tokensOpus > 0 ? `${prefix}${r.actuals.tokensOpus.toLocaleString()} opus` : null;
-        const sonnet = r.actuals.tokensSonnet > 0
-            ? `${prefix}${r.actuals.tokensSonnet.toLocaleString()} sonnet`
-            : null;
+        const opus = r.actuals.tokensOpus > 0 ? `${r.actuals.tokensOpus.toLocaleString()} opus` : null;
+        const sonnet = r.actuals.tokensSonnet > 0 ? `${r.actuals.tokensSonnet.toLocaleString()} sonnet` : null;
         const tokenStr = [opus, sonnet].filter(Boolean).join(' + ');
-        const costStr = r.actuals.apiCostUsd > 0 ? ` | ${prefix}$${r.actuals.apiCostUsd.toFixed(3)} API` : '';
-        lines.push(`\n🤖 Tokens: ${tokenStr}${costStr}${r.actuals.estimated ? ' *(auto-estimated)*' : ''}`);
+        const costStr = r.actuals.apiCostUsd > 0 ? ` | $${r.actuals.apiCostUsd.toFixed(3)} API` : '';
+        lines.push(`\n🤖 Tokens: ${tokenStr}${costStr}`);
     }
     if (r.validateScore !== null && r.validateScore !== undefined) {
         const sourceSuffix = r.validateScoreSource === 'forced-best-effort-validateSpec'
@@ -180,22 +177,17 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
         const v = r.orchestrationPlan.parallelSafetyVerdict ? 'parallel-safe' : 'sequential-required';
         lines.push(`\n🤖 Orchestration: ${String(r.orchestrationPlan.executionOrder.length)} waves | ${v}`);
     }
-    // SPEC-494: Claude Code mode hint
-    if (r.suggestedClaudeMode) {
-        lines.push(`\n💡 **Suggested Claude mode:** \`${r.suggestedClaudeMode}\` — ${r.modeHint ?? ''}`);
-    }
-    if (recordActualHint) {
-        lines.push(`\n💡 ${recordActualHint}`);
-    }
     // SPEC-754: Shell hygiene reminder for claude-code host on done transition
     if (shellHygieneHint) {
         lines.push(`\n🐚 **Shell hygiene:** ${shellHygieneHint}`);
     }
     // SPEC-340: nextAction and lifecycleMap
-    const nextAction = buildNextAction(newStatus);
     const lifecycleMap = buildLifecycleMap(newStatus);
+    const nextAction = lifecycleMap.next === null ? null : buildNextAction(newStatus);
     lines.push(buildLifecycleMapLine(lifecycleMap));
-    lines.push(`\n**Next step:** ${nextAction.step}\n> ${nextAction.prompt}\n> \`${nextAction.suggestedCommand}\` — ${nextAction.whenToDoIt}`);
+    if (nextAction) {
+        lines.push(`\n**Next step:** ${nextAction.step}\n> ${nextAction.prompt}\n> \`${nextAction.suggestedCommand}\` — ${nextAction.whenToDoIt}`);
+    }
     const allNextSteps = [...(r.implementingSuggestions ?? [])];
     const baseText = formatSuccess(t('tools.response.statusTitle'), lines.join(''));
     const withNextSteps = allNextSteps.length > 0 ? addNextSteps(baseText, allNextSteps) : baseText;
@@ -284,7 +276,7 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
         warningsTop5: warningItems.slice(0, 5),
         affectedSpecsCount: r.cascade.affectedSpecs.length,
         affectedSpecsTop5: r.cascade.affectedSpecs.slice(0, 5),
-        nextAction,
+        nextAction: nextAction ?? undefined,
         lifecycleMap,
         humanSummary,
         orchestrationPlan: r.orchestrationPlan

package/dist/tools/update-status/transition-guard.d.ts

@@ -73,10 +73,10 @@ export declare function checkAmbiguityGate(spec: Spec, newStatus: SpecStatus): P
 export declare function checkReadinessGate(spec: Spec, newStatus: SpecStatus, forceApprove: boolean | undefined): Promise<ReadinessGateOutput>;
 /**
  * SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
- * or did not generate enough addressed scenarios.
+ * or does not contain enough explicit resolution evidence.
  *
  * - Requires challengeReport to exist on the spec
- * - Requires at least 3 scenarios addressed
+ * - Requires at least 3 scenarios with explicit mitigation/risk-acceptance evidence
  * - High-risk specs (high/critical) require all 5 focus areas
  */
 export declare function checkChallengeGate(spec: Spec, newStatus: SpecStatus): ToolResult | null;

package/dist/tools/update-status/transition-guard.js

@@ -9,6 +9,7 @@ import { validateEnglishOnlySpecText } from '../../engine/spec-language/english-
 import { checkGroundedSpecContract } from '../../engine/spec-grounding/contract.js';
 import { checkGenericSpecOutput } from '../../engine/spec-quality/generic-output-gate.js';
 import { formatKeyValue } from '../output-formatter.js';
+import { getResolvedChallengeEvidence, MINIMUM_RESOLVED_CHALLENGES, } from '../challenge-spec/challenge-report.js';
 /**
  * Valid state transitions for spec lifecycle.
  * draft -> review -> approved -> implementing -> done
@@ -115,7 +116,7 @@ export function checkTransition(currentStatus, newStatus) {
  * Returns an error ToolResult if blocked, null if passed.
  */
 export function checkDorGate(spec, specId, projectId, newStatus) {
-    if (newStatus !== 'implementing') {
+    if (newStatus !== 'implementing' || isReverseTransition(spec.status, newStatus)) {
         return null;
     }
     const dorResult = validateDoR(spec);
@@ -432,10 +433,10 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
 }
 /**
  * SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
- * or did not generate enough addressed scenarios.
+ * or does not contain enough explicit resolution evidence.
  *
  * - Requires challengeReport to exist on the spec
- * - Requires at least 3 scenarios addressed
+ * - Requires at least 3 scenarios with explicit mitigation/risk-acceptance evidence
  * - High-risk specs (high/critical) require all 5 focus areas
  */
 export function checkChallengeGate(spec, newStatus) {
@@ -459,21 +460,23 @@ export function checkChallengeGate(spec, newStatus) {
             },
         };
     }
-    if (report.addressedCount < 3) {
+    const resolutionEvidence = getResolvedChallengeEvidence(report);
+    const addressedCount = resolutionEvidence.length;
+    if (addressedCount < MINIMUM_RESOLVED_CHALLENGES) {
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Challenge gate blocked: only ${String(report.addressedCount)} scenario(s) addressed (minimum 3 required). Re-run challenge_spec(specId="${spec.id}") with broader focus areas.`,
+                    text: `Challenge gate blocked: only ${String(addressedCount)} scenario(s) have explicit resolution evidence (minimum ${String(MINIMUM_RESOLVED_CHALLENGES)} required). Record mitigation or accepted-risk evidence for discovered findings before retrying.`,
                 },
             ],
             isError: true,
             structuredContent: {
                 error: 'CHALLENGE_GATE_BLOCKED',
                 code: 'INSUFFICIENT_CHALLENGES',
-                addressedCount: report.addressedCount,
-                requiredCount: 3,
-                fixHint: `Run challenge_spec(specId="${spec.id}") to generate more failure scenarios.`,
+                addressedCount,
+                requiredCount: MINIMUM_RESOLVED_CHALLENGES,
+                fixHint: `Resolve challenge_spec findings with concrete evidence, then retry update_status(specId="${spec.id}", status="review").`,
             },
         };
     }

package/dist/tools/update-status-actions.d.ts

@@ -13,7 +13,6 @@ export declare function runDoneActions(projectId: string, specId: string, gitBra
     } | null;
     validationWarning: string | null;
     uncommittedWarning: string | null;
-    recordActualHint: string | null;
     autopilotSummary: string[];
 }>;
 /**