@planu/cli 4.14.1 → 5.1.1

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

@@ -1,6 +1,30 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { UpdateStatusInput, ToolResult } from '../../types/index.js';
+import type { UpdateStatusInput, ToolResult, Actuals, ReconciliationInvocationContext } from '../../types/index.js';
+type LifecycleAuthorityRoute = {
+    route: 'ordinary';
+} | {
+    route: 'reconcile';
+} | {
+    route: 'error';
+    result: ToolResult;
+};
+/** Select the lifecycle path before any transition, artifact, receipt, or log mutation. */
+export declare function classifyLifecycleAuthority(input: UpdateStatusInput, context: ReconciliationInvocationContext, options?: {
+    requireDoneDigest?: boolean;
+}): LifecycleAuthorityRoute;
+/**
+ * SPEC-1356 (T-A2): a `done` transition no longer requires the caller to supply
+ * actuals. When the whole object is omitted, synthesize a minimal record instead
+ * of blocking the transition with `actuals_required`. Every caller-provided
+ * field — including a caller-provided partial object once the MCP input schema
+ * accepts one — is preserved verbatim; only genuinely unmeasured numeric fields
+ * default to 0, and `completedAt`/`notes` only default when absent.
+ */
+export declare function synthesizeActuals(actuals: Partial<Actuals> | undefined, transitionedAt: string): Actuals;
+/** Bind deferred lifecycle work to one normalized absolute root without persisting that path. */
+export declare function computeTransitionRootBinding(projectPath: string): string;
 /** Recover durable post-commit work for every registered project after server startup. */
 export declare function recoverPendingPostCommitTasksAtStartup(): Promise<void>;
 export declare function handleUpdateStatus(params: UpdateStatusInput, server?: McpServer): Promise<ToolResult>;
+export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -15,20 +15,21 @@ 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 { checkDoneGates, checkComplianceGate, checkApprovedFormatGate, checkSpecReviewGate, writeSpecReviewArtifact, } from './dod-gates.js';
+import { checkDoneGates, checkComplianceGate, checkApprovedFormatGate, checkSpecReviewGate, writeSpecReviewArtifact, deriveDoneReviewDigest, } from './dod-gates.js';
 import { checkLifecycleEvidenceTransitionGate } from './evidence-gate.js';
+import { autofillTraceabilityMatrix } from '../../engine/evidence-gates/evidence-autofill.js';
 import { buildStatusResponse, buildDryRunResponse } from './response-builder.js';
 import { recordDoneMetrics, syncSpecFiles, tryReconcile, recordTerminalTransitionEvent, } from './file-sync.js';
 import { appendEntry, getLastHash } from '../../storage/audit-trail-store.js';
 import { appendTransitionEvent } from '../../storage/transition-log.js';
 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, queuePostCommitTasks, runCascadeForResponse, } from './side-effects.js';
 import { formatKeyValue } from '../output-formatter.js';
 import { checkCodeReality } from '../../engine/code-scanner/index.js';
-import { join } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
+import { readSpecContent } from '../../engine/spec-reader.js';
 import { trackCost } from '../../engine/cost-tracking/operation-tracker.js';
 import { resolveProjectIdOrAutoDetect } from '../resolve-project-id.js';
 import { withToolTimeout } from '../safe-handler.js';
@@ -39,7 +40,79 @@ import { acquireLock, releaseLock, isLocked as isCrossProcessLocked, LockBusyErr
 import { projectDataDir } from '../../storage/base-store.js';
 import { assertExecutionCanCommit } from '../../engine/execution/context.js';
 import { shouldSkipGateForExplicitLegacyHarness } from './gate-harness.js';
-import { assertValidationFreshnessBarrier, } from '../../engine/validation/validation-freshness.js';
+import { assertValidationFreshnessBarrier, closeValidationFreshnessLease, } from '../../engine/validation/validation-freshness.js';
+import { currentReconciliationInvocationContext, reconcileImplementingSpec, } from '../../engine/lifecycle-reconciliation.js';
+const IMPLEMENTATION_REVIEW_DIGEST = /^sha256:[a-f0-9]{64}$/u;
+function lifecycleAuthorityError(code, message, fixHint) {
+    return {
+        content: [{ type: 'text', text: `${code}: ${message}\nFix: ${fixHint}` }],
+        isError: true,
+        structuredContent: { error: code, code: 422, fixHint },
+    };
+}
+/** Select the lifecycle path before any transition, artifact, receipt, or log mutation. */
+export function classifyLifecycleAuthority(input, context, options = {}) {
+    const hasRequestId = input.reconciliationRequestId !== undefined;
+    const hasTransitionId = input.expectedImplementingTransitionId !== undefined;
+    const hasDigest = input.implementationReviewDigest !== undefined;
+    const hasAnyAuthority = hasRequestId || hasTransitionId || hasDigest;
+    if (input.status === 'done') {
+        if (hasRequestId || hasTransitionId) {
+            return {
+                route: 'error',
+                result: lifecycleAuthorityError('RECONCILIATION_TARGET_INVALID', 'Reconciliation authority is valid only for the review target.', 'Remove reconciliationRequestId and expectedImplementingTransitionId from the done request.'),
+            };
+        }
+        // SPEC-1356: implementationReviewDigest is optional. When the caller omits it,
+        // the done gate (checkDoneGates via dod-gates.deriveDoneReviewDigest) derives
+        // it automatically from the persisted validation-report.json — the caller no
+        // longer has to compute the sha256 by hand. `options.requireDoneDigest` is
+        // retained only so legacy/explicit-authority callers can still demand it.
+        if (options.requireDoneDigest === true && !hasDigest) {
+            return {
+                route: 'error',
+                result: lifecycleAuthorityError('DONE_REVIEW_DIGEST_REQUIRED', 'A done transition requires the implementation review digest.', 'Supply the sha256 digest of the exact persisted validation-report.json bytes.'),
+            };
+        }
+        if (hasDigest &&
+            (typeof input.implementationReviewDigest !== 'string' ||
+                !IMPLEMENTATION_REVIEW_DIGEST.test(input.implementationReviewDigest))) {
+            return {
+                route: 'error',
+                result: lifecycleAuthorityError('DONE_REVIEW_DIGEST_INVALID', 'The implementation review digest must be sha256 followed by 64 lowercase hex characters.', 'Recompute the digest from the exact persisted validation-report.json bytes.'),
+            };
+        }
+        return { route: 'ordinary' };
+    }
+    if (input.status === 'review' && hasAnyAuthority) {
+        if (!hasRequestId || !hasTransitionId || !hasDigest) {
+            return {
+                route: 'error',
+                result: lifecycleAuthorityError('RECONCILIATION_TUPLE_INCOMPLETE', 'Review reconciliation requires the complete authority tuple.', 'Supply reconciliationRequestId, expectedImplementingTransitionId, implementationReviewDigest, and a reason of at least 100 characters.'),
+            };
+        }
+        if (!input.reason || input.reason.trim().length < 100) {
+            return {
+                route: 'error',
+                result: lifecycleAuthorityError('RECONCILIATION_REASON_INVALID', 'Review reconciliation requires a non-blank reason of at least 100 characters.', 'Explain the reviewed implementation drift and required follow-up in at least 100 characters.'),
+            };
+        }
+        if (context.surface !== 'local-mcp') {
+            return {
+                route: 'error',
+                result: lifecycleAuthorityError('RECONCILIATION_UNTRUSTED_SURFACE', 'Reconciliation is available only through trusted local MCP.', 'Retry the complete reconciliation request through the registered local MCP tool.'),
+            };
+        }
+        return { route: 'reconcile' };
+    }
+    if (hasAnyAuthority) {
+        return {
+            route: 'error',
+            result: lifecycleAuthorityError('RECONCILIATION_TARGET_INVALID', 'Lifecycle authority fields are invalid for this target.', 'Remove the authority fields or use implementationReviewDigest only with done.'),
+        };
+    }
+    return { route: 'ordinary' };
+}
 /**
  * SPEC-280: Silently traverse intermediate states so callers can jump forward
  * (e.g. draft → approved) without receiving an error.
@@ -52,6 +125,58 @@ function buildAutoAdvancePlan(currentStatus, targetStatus) {
         stepsExecuted,
     };
 }
+/**
+ * SPEC-1356 (T-A3): auto-generate traceability-matrix.json when it is missing,
+ * BEFORE the evidence gate reads it for a 'done' transition. Never overwrites an
+ * existing artifact. Tolerates every internal failure (falls through to the
+ * ordinary evidence gate, which will report the real missing-evidence error).
+ *
+ * When autofill actually writes a fresh file, the newly-created evidence has not
+ * been bound by validate's durable receipt yet, so this blocks once with a clear
+ * "re-run validate" message instead of letting a stale-relative-to-receipt
+ * traceability matrix slide through the done gates silently.
+ */
+async function runTraceabilityAutofillGate(args) {
+    try {
+        const specPath = isAbsolute(args.spec.specPath) || !args.projectPath
+            ? args.spec.specPath
+            : join(args.projectPath, args.spec.specPath);
+        const specBody = await readSpecContent(specPath);
+        if (specBody === null) {
+            return null;
+        }
+        const result = await autofillTraceabilityMatrix({
+            projectId: args.projectId,
+            specId: args.specId,
+            projectPath: args.projectPath,
+            specBody,
+        });
+        if (!result.written) {
+            return null;
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `traceability-matrix.json was auto-generated at ${result.path} (${String(result.rowCount)} rows). ` +
+                        'Run validate to bind this evidence, then retry update_status(done).',
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'traceability_matrix_autofilled',
+                code: 422,
+                context: { specId: args.specId, path: result.path, rowCount: result.rowCount },
+                fixHint: 'Run validate so the new traceability-matrix.json is bound, then retry done.',
+            },
+        };
+    }
+    catch (error) {
+        // reliability-optional: EVIDENCE_AUTOFILL_GATE — falls through to the ordinary evidence gate
+        reportClassifiedDegradation('EVIDENCE_AUTOFILL_GATE', error);
+        return null;
+    }
+}
 /**
  * SPEC-301: Check if spec is locked by another agent.
  * Returns an error ToolResult if locked, or null to continue.
@@ -101,6 +226,27 @@ async function checkApprovalPolicyGate(projectId, specId, newStatus) {
     }
     return null;
 }
+/**
+ * SPEC-1356 (T-A2): a `done` transition no longer requires the caller to supply
+ * actuals. When the whole object is omitted, synthesize a minimal record instead
+ * of blocking the transition with `actuals_required`. Every caller-provided
+ * field — including a caller-provided partial object once the MCP input schema
+ * accepts one — is preserved verbatim; only genuinely unmeasured numeric fields
+ * default to 0, and `completedAt`/`notes` only default when absent.
+ */
+export function synthesizeActuals(actuals, transitionedAt) {
+    return {
+        devHours: actuals?.devHours ?? 0,
+        reviewHours: actuals?.reviewHours ?? 0,
+        tokensOpus: actuals?.tokensOpus ?? 0,
+        tokensSonnet: actuals?.tokensSonnet ?? 0,
+        apiCostUsd: actuals?.apiCostUsd ?? 0,
+        humanCostUsd: actuals?.humanCostUsd ?? 0,
+        totalCostUsd: actuals?.totalCostUsd ?? 0,
+        completedAt: actuals?.completedAt ?? transitionedAt,
+        notes: actuals?.notes ?? 'actuals unavailable — auto-filled by done gate',
+    };
+}
 /** Compute done metrics when transitioning to 'done' with actuals provided. */
 function computeDoneMetrics(newStatus, spec, actuals) {
     if (newStatus !== 'done' || actuals === undefined || spec === null) {
@@ -199,6 +345,18 @@ function planBackgroundActions(args) {
     }
     return actions;
 }
+/** Bind deferred lifecycle work to one normalized absolute root without persisting that path. */
+export function computeTransitionRootBinding(projectPath) {
+    return createHash('sha256')
+        .update('planu:transition-root:v1\0')
+        .update(resolve(projectPath))
+        .digest('hex');
+}
+function receiptMatchesTransitionRoot(receipt, projectPath) {
+    return (projectPath !== undefined &&
+        receipt.transitionRootBinding !== undefined &&
+        receipt.transitionRootBinding === computeTransitionRootBinding(projectPath));
+}
 function buildPostCommitTasks(args) {
     const enabled = new Set(args.actionNames);
     const tasks = [];
@@ -212,13 +370,13 @@ function buildPostCommitTasks(args) {
     if (enabled.has('implementing-side-effects')) {
         tasks.push({
             name: 'implementing-side-effects',
-            run: () => runImplementingSideEffects(args.projectId, args.spec.id),
+            run: () => runImplementingSideEffects(args.projectId, args.spec.id, args.effectiveProjectPath),
         });
     }
     if (enabled.has('done-side-effects')) {
         tasks.push({
             name: 'done-side-effects',
-            run: () => runDoneSideEffects(args.projectId, args.spec.id, args.spec.gitBranch),
+            run: () => runDoneSideEffects(args.projectId, args.spec.id, args.spec.gitBranch, args.effectiveProjectPath),
         });
     }
     if (enabled.has('reconcile')) {
@@ -231,7 +389,7 @@ function buildPostCommitTasks(args) {
     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),
+            run: () => recordDoneMetrics(args.projectId, args.spec.id, args.spec, actuals, args.effectiveProjectPath),
         });
     }
     const effectiveProjectPath = args.effectiveProjectPath;
@@ -253,6 +411,7 @@ function buildPostCommitTasks(args) {
                 projectId: args.projectId,
                 spec: args.spec,
                 currentStatus: args.previousStatus,
+                projectPath: args.effectiveProjectPath,
             }),
         });
     }
@@ -291,7 +450,10 @@ async function replayIdempotentPostCommitTasks(args) {
         return;
     }
     const knowledge = await knowledgeStore.getKnowledge(args.projectId);
-    const effectiveProjectPath = knowledge?.projectPath ?? args.projectPath;
+    const effectiveProjectPath = args.projectPath ?? knowledge?.projectPath;
+    if (!receiptMatchesTransitionRoot(receipt, effectiveProjectPath)) {
+        return;
+    }
     const specAtTransition = { ...args.spec, status: receipt.status };
     const tasks = buildPostCommitTasks({
         actionNames: receipt.pendingBackgroundActions,
@@ -317,13 +479,17 @@ async function recoverPendingPostCommitTasks(projectId, projectPath) {
         knowledgeStore.getKnowledge(projectId),
         specStore.listSpecs(projectId),
     ]);
-    const effectiveProjectPath = knowledge?.projectPath ?? projectPath;
+    const effectiveProjectPath = projectPath ?? knowledge?.projectPath;
     for (const spec of specs) {
-        const hasPendingWork = (spec.statusHistory ?? []).some((receipt) => receipt.transitionId && receipt.pendingBackgroundActions?.length);
-        if (!hasPendingWork) {
+        const recoverableReceipts = (spec.statusHistory ?? []).filter((receipt) => receipt.transitionId &&
+            receipt.pendingBackgroundActions?.length &&
+            receiptMatchesTransitionRoot(receipt, effectiveProjectPath));
+        if (recoverableReceipts.length === 0 || !effectiveProjectPath) {
             continue;
         }
-        const recoveryLock = await acquireLock(effectiveProjectPath ?? projectPath ?? process.cwd(), spec.id, { reason: 'recover pending post-commit tasks' });
+        const recoveryLock = await acquireLock(effectiveProjectPath, spec.id, {
+            reason: 'recover pending post-commit tasks',
+        });
         if (recoveryLock === null) {
             continue;
         }
@@ -335,7 +501,9 @@ async function recoverPendingPostCommitTasks(projectId, projectPath) {
                 continue;
             }
             for (const receipt of currentSpec.statusHistory ?? []) {
-                if (!receipt.transitionId || !receipt.pendingBackgroundActions?.length) {
+                if (!receipt.transitionId ||
+                    !receipt.pendingBackgroundActions?.length ||
+                    !receiptMatchesTransitionRoot(receipt, effectiveProjectPath)) {
                     continue;
                 }
                 const specAtTransition = { ...currentSpec, status: receipt.status };
@@ -383,6 +551,18 @@ export async function recoverPendingPostCommitTasksAtStartup() {
         });
     }
 }
+async function runTransitionMaintenance(transitionProjectPath) {
+    if (transitionProjectPath) {
+        try {
+            const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
+            await runStrictPlanuCleanup(transitionProjectPath);
+        }
+        catch (error) {
+            /* reliability-cleanup: PRE_TRANSITION_STRICT_CLEANUP — validate remains fail-closed */
+            reportClassifiedDegradation('PRE_TRANSITION_STRICT_CLEANUP', error);
+        }
+    }
+}
 function buildPersistenceFailureResponse(args) {
     const committed = args.recoveryRequired ? null : false;
     const message = args.recoveryRequired
@@ -469,7 +649,7 @@ async function commitTransitionWithNarrowLock(args) {
                 expectedSpec: freshSpec,
             });
             const updatedSpec = transitionRecord.spec;
-            const syncResult = await syncSpecFiles(updatedSpec, args.originalStatus, args.newStatus, args.projectPath);
+            const syncResult = await syncSpecFiles(updatedSpec, args.originalStatus, args.newStatus, args.projectPath, args.qualityWarnings);
             if (!syncResult.warning) {
                 return { ok: true, transitionRecord, updatedSpec };
             }
@@ -571,6 +751,13 @@ async function resolveOrchestrationPlan(newStatus, specScope, specId, projectPat
 export async function handleUpdateStatus(params, server) {
     return trackCost(params.projectPath?.trim() ?? '', 'update_status', async () => {
         const { specId, status: newStatus, actuals, reviewNotes } = params;
+        // SPEC-1356: implementationReviewDigest is derived automatically by the done
+        // gate when omitted (see dod-gates.deriveDoneReviewDigest), so it is never
+        // required here.
+        const authorityRoute = classifyLifecycleAuthority(params, currentReconciliationInvocationContext());
+        if (authorityRoute.route === 'error') {
+            return authorityRoute.result;
+        }
         // SPEC-509: auto-detect project from git root when projectPath/projectId are omitted
         const resolved = await resolveProjectIdOrAutoDetect({
             projectId: params.projectId,
@@ -581,24 +768,27 @@ export async function handleUpdateStatus(params, server) {
         }
         const projectId = resolved.projectId;
         const effectiveProjectPath = resolved.projectPath;
-        if (effectiveProjectPath) {
-            try {
-                const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
-                await runStrictPlanuCleanup(effectiveProjectPath);
-            }
-            catch (error) {
-                /* reliability-cleanup: PRE_TRANSITION_STRICT_CLEANUP — validate remains fail-closed */
-                reportClassifiedDegradation('PRE_TRANSITION_STRICT_CLEANUP', error);
-            }
+        const knowledge = await knowledgeStore.getKnowledge(projectId);
+        const transitionProjectPath = (params.projectPath?.trim()
+            ? effectiveProjectPath
+            : (knowledge?.projectPath ?? effectiveProjectPath)) || undefined;
+        if (authorityRoute.route === 'reconcile') {
+            return reconcileImplementingSpec({
+                input: params,
+                projectId,
+                projectPath: transitionProjectPath,
+                context: currentReconciliationInvocationContext(),
+                syncSpecFiles,
+            });
         }
-        await recoverPendingPostCommitTasks(projectId, effectiveProjectPath).catch((error) => {
-            /* reliability-optional: POST_COMMIT_RECOVERY_SCAN — durable tasks remain retryable */
-            reportClassifiedDegradation('POST_COMMIT_RECOVERY_SCAN', error);
-        });
+        if (newStatus !== 'done') {
+            await runTransitionMaintenance(transitionProjectPath);
+        }
+        let doneFreshnessLease;
         return (async () => {
             try {
                 // SPEC-301: Reject status changes when spec is locked by another holder (legacy manual lock)
-                const lockError = await checkSpecLockGate(effectiveProjectPath, specId);
+                const lockError = await checkSpecLockGate(transitionProjectPath, specId);
                 if (lockError) {
                     return lockError;
                 }
@@ -608,7 +798,7 @@ export async function handleUpdateStatus(params, server) {
                 if (isDryRun) {
                     // SPEC-731: dry_run checks lock availability without acquiring it.
                     // isLocked returns null when no lockfile exists (available), or a LockInfo when locked.
-                    const lockInfo = await isCrossProcessLocked(effectiveProjectPath, specId).catch((error) => {
+                    const lockInfo = await isCrossProcessLocked(transitionProjectPath ?? projectId, specId).catch((error) => {
                         // reliability-optional: DRY_RUN_LOCK_PROBE — null conservatively avoids stale lock claims
                         reportClassifiedDegradation('DRY_RUN_LOCK_PROBE', error);
                         return null;
@@ -647,29 +837,16 @@ export async function handleUpdateStatus(params, server) {
                         await replayIdempotentPostCommitTasks({
                             projectId,
                             spec,
-                            projectPath: effectiveProjectPath,
+                            projectPath: transitionProjectPath,
                         });
                         const idempotentResult = checkIdempotentOrTransition(projectId, spec, newStatus);
                         if (idempotentResult) {
                             return idempotentResult;
                         }
                     }
-                    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-1356 (T-A2): actuals are no longer required to reach done. When
+                    // omitted, synthesizeActuals() below fills in a defaulted record instead
+                    // of blocking the transition — see synthesizeActuals doc comment.
                     // 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);
@@ -784,10 +961,8 @@ export async function handleUpdateStatus(params, server) {
                     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 ?? effectiveProjectPath;
+                    const effectiveGatePath = transitionProjectPath;
                     // SPEC-1044: SDD model-routing + context continuity hard gate.
                     const sddRoutingGate = {
                         blockResult: null,
@@ -812,6 +987,26 @@ export async function handleUpdateStatus(params, server) {
                             sddRoutingGate.gateResults.sddModelRouting = 'forced';
                         }
                     }
+                    // SPEC-1356 (T-A3): auto-generate traceability-matrix.json before the
+                    // evidence gate below reads it, so a spec never fails 'done' purely
+                    // because nobody hand-wrote the traceability artifact. Never overwrites
+                    // an existing file. Freshness caveat: when autofill actually writes a
+                    // new file, its evidence has not yet been bound by validate's durable
+                    // receipt, so we block once and ask the caller to re-run validate
+                    // rather than risk certifying stale bindings. See evidence-autofill.ts
+                    // for the full rationale.
+                    if (plannedStatuses.includes('done') &&
+                        !shouldSkipGateForExplicitLegacyHarness('evidence')) {
+                        const autofillGate = await runTraceabilityAutofillGate({
+                            spec,
+                            specId,
+                            projectId,
+                            projectPath: effectiveGatePath,
+                        });
+                        if (autofillGate) {
+                            return autofillGate;
+                        }
+                    }
                     // SPEC-1054: BDD/SDD evidence gates. Non-trivial specs must carry
                     // Discovery before approval, task-plan before implementation, and
                     // traceability/contract evidence before done.
@@ -830,6 +1025,21 @@ export async function handleUpdateStatus(params, server) {
                             }
                         }
                     }
+                    // SPEC-1356 (T-A1): implementationReviewDigest is optional. When the
+                    // caller omits it, derive it automatically from the persisted
+                    // validation-report.json instead of requiring the caller to hand-compute
+                    // a sha256. Failure to derive it fails closed with a clear "run validate
+                    // first" message — identical strength to the explicit-digest path.
+                    let resolvedImplementationReviewDigest = params.implementationReviewDigest;
+                    if (newStatus === 'done' &&
+                        resolvedImplementationReviewDigest === undefined &&
+                        !shouldSkipGateForExplicitLegacyHarness('evidence')) {
+                        const derived = await deriveDoneReviewDigest(specId, projectId);
+                        if ('error' in derived) {
+                            return derived.error;
+                        }
+                        resolvedImplementationReviewDigest = derived.digest;
+                    }
                     // ---------------------------------------------------------------------------
                     // BATCH A (parallel): code-reality + done-gates — independent of each other
                     // SPEC-441: Code reality check before transitioning to 'implementing'
@@ -839,7 +1049,6 @@ export async function handleUpdateStatus(params, server) {
                     // security and repository scans belong to the durable validation worker.
                     let codeRealityWarning = null;
                     let forcedBypassWarning = null;
-                    let doneFreshnessLease;
                     const [codeRealityResult, doneGatesResult] = await Promise.all([
                         // Code reality: only relevant for 'implementing'
                         newStatus === 'implementing' && !reverseTransition && effectiveGatePath
@@ -851,7 +1060,7 @@ export async function handleUpdateStatus(params, server) {
                             : Promise.resolve(null),
                         // Done gates: only relevant for 'done'
                         newStatus === 'done' && !shouldSkipGateForExplicitLegacyHarness('evidence')
-                            ? checkDoneGates(spec, specId, projectId, effectiveGatePath, params.force, params.forceStatusReason ?? params.reason ?? 'No force reason provided')
+                            ? checkDoneGates(spec, specId, projectId, effectiveGatePath, params.force, params.forceStatusReason ?? params.reason ?? 'No force reason provided', undefined, resolvedImplementationReviewDigest)
                             : Promise.resolve(null),
                     ]);
                     // Process code reality result
@@ -933,15 +1142,23 @@ export async function handleUpdateStatus(params, server) {
                             return specReviewWriteError;
                         }
                     }
-                    // Explicit actuals are preserved verbatim. Provider usage and cost are never inferred.
-                    const resolvedActuals = actuals;
+                    // Explicit actuals are preserved verbatim. Provider usage and cost are
+                    // never inferred — synthesizeActuals only fills gaps the caller left
+                    // unmeasured (SPEC-1356 T-A2).
+                    const resolvedActuals = newStatus === 'done' || actuals !== undefined
+                        ? synthesizeActuals(actuals, new Date().toISOString())
+                        : undefined;
                     // Run only fast, read-only transition checks before persistence.
                     const implActions = newStatus === 'implementing'
-                        ? await runImplementingActions(projectId, specId, { deferSideEffects: true })
+                        ? await runImplementingActions(projectId, specId, {
+                            deferSideEffects: true,
+                            projectPath: effectiveGatePath,
+                        })
                         : null;
                     const doneActions = newStatus === 'done'
                         ? await runDoneActions(projectId, specId, spec.gitBranch, {
                             deferSideEffects: true,
+                            projectPath: effectiveGatePath,
                         })
                         : null;
                     const trigger = reverseTransition
@@ -1089,13 +1306,20 @@ export async function handleUpdateStatus(params, server) {
                         hasProjectPath: Boolean(effectiveGatePath),
                         shouldAutoStage,
                     });
+                    const transitionRootBinding = plannedBackgroundActions.length > 0 && effectiveGatePath
+                        ? computeTransitionRootBinding(effectiveGatePath)
+                        : undefined;
+                    const qualityWarningsToWrite = newStatus === 'approved'
+                        ? [...readinessGate.qualityWarnings, ...formatGate.qualityWarnings]
+                        : [];
                     const persistence = await commitTransitionWithNarrowLock({
-                        projectPath: effectiveProjectPath || projectId,
+                        projectPath: effectiveGatePath ?? projectId,
                         projectId,
                         specId,
                         newStatus,
                         originalStatus,
                         expectedSpec: spec,
+                        qualityWarnings: qualityWarningsToWrite,
                         options: {
                             trigger: trigger,
                             actor,
@@ -1103,6 +1327,7 @@ export async function handleUpdateStatus(params, server) {
                             reason: params.reason,
                             updates: nonStatusUpdates,
                             pendingBackgroundActions: plannedBackgroundActions,
+                            transitionRootBinding,
                             expectedSpec: spec,
                         },
                         ...(doneFreshnessLease ? { freshnessLease: doneFreshnessLease } : {}),
@@ -1114,6 +1339,9 @@ export async function handleUpdateStatus(params, server) {
                     const frontmatterSyncWarnings = [];
                     const transitionId = transitionRecord.transitionId;
                     const committedAt = transitionRecord.timestamp;
+                    if (newStatus === 'done') {
+                        await runTransitionMaintenance(transitionProjectPath);
+                    }
                     await appendTransitionEvent({
                         projectId,
                         specId,
@@ -1145,29 +1373,6 @@ export async function handleUpdateStatus(params, server) {
                             reportClassifiedDegradation('REOPEN_EVENT_APPEND', err);
                         });
                     }
-                    // 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 (error) {
-                                // reliability-optional: QUALITY_WARNING_FRONTMATTER — canonical receipt retains warnings
-                                reportClassifiedDegradation('QUALITY_WARNING_FRONTMATTER', error);
-                            }
-                        })();
-                    }
                     // 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') {
@@ -1197,6 +1402,7 @@ export async function handleUpdateStatus(params, server) {
                             modelId: params.modelId,
                             gateResults: Object.keys(terminalGateResults).length > 0 ? terminalGateResults : undefined,
                             meta: transitionEvidenceMeta,
+                            projectPath: effectiveGatePath,
                         }).catch((error) => {
                             /* reliability-optional: TERMINAL_VALIDATION_REPORT — canonical receipt is authoritative */
                             reportClassifiedDegradation('TERMINAL_VALIDATION_REPORT', error);
@@ -1335,6 +1541,14 @@ export async function handleUpdateStatus(params, server) {
                     isError: true,
                 };
             }
+            finally {
+                if (doneFreshnessLease) {
+                    await closeValidationFreshnessLease(doneFreshnessLease).catch((error) => {
+                        /* reliability-cleanup: freshness expiry remains the recovery boundary */
+                        reportClassifiedDegradation('VALIDATION_FRESHNESS_CHECK_FAILED', error);
+                    });
+                }
+            }
         })();
     }); // end trackCost
 }