@planu/cli 4.14.1 → 5.0.0

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

@@ -22,13 +22,12 @@ import { recordDoneMetrics, syncSpecFiles, tryReconcile, recordTerminalTransitio
 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 { join, resolve } from 'node:path';
 import { trackCost } from '../../engine/cost-tracking/operation-tracker.js';
 import { resolveProjectIdOrAutoDetect } from '../resolve-project-id.js';
 import { withToolTimeout } from '../safe-handler.js';
@@ -39,7 +38,8 @@ 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';
 /**
  * SPEC-280: Silently traverse intermediate states so callers can jump forward
  * (e.g. draft → approved) without receiving an error.
@@ -199,6 +199,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 +224,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 +243,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 +265,7 @@ function buildPostCommitTasks(args) {
                 projectId: args.projectId,
                 spec: args.spec,
                 currentStatus: args.previousStatus,
+                projectPath: args.effectiveProjectPath,
             }),
         });
     }
@@ -291,7 +304,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 +333,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 +355,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 +405,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 +503,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 };
             }
@@ -581,24 +615,29 @@ 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 (params.reconciliationRequestId ||
+            params.expectedImplementingTransitionId ||
+            params.implementationReviewDigest) {
+            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 +647,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,7 +686,7 @@ export async function handleUpdateStatus(params, server) {
                         await replayIdempotentPostCommitTasks({
                             projectId,
                             spec,
-                            projectPath: effectiveProjectPath,
+                            projectPath: transitionProjectPath,
                         });
                         const idempotentResult = checkIdempotentOrTransition(projectId, spec, newStatus);
                         if (idempotentResult) {
@@ -784,10 +823,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,
@@ -839,7 +876,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
@@ -937,11 +973,15 @@ export async function handleUpdateStatus(params, server) {
                     const resolvedActuals = actuals;
                     // 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 +1129,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 +1150,7 @@ export async function handleUpdateStatus(params, server) {
                             reason: params.reason,
                             updates: nonStatusUpdates,
                             pendingBackgroundActions: plannedBackgroundActions,
+                            transitionRootBinding,
                             expectedSpec: spec,
                         },
                         ...(doneFreshnessLease ? { freshnessLease: doneFreshnessLease } : {}),
@@ -1114,6 +1162,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 +1196,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 +1225,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 +1364,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
 }

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

@@ -84,7 +84,7 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
     const toEmoji = STATUS_EMOJIS[newStatus];
     const r = result;
     const lines = [
-        `**SPEC-${specId}** moved: ${fromEmoji} \`${currentStatus}\` → ${toEmoji} \`${newStatus}\``,
+        `**${specId}** moved: ${fromEmoji} \`${currentStatus}\` → ${toEmoji} \`${newStatus}\``,
     ];
     if (r.committed && r.transitionId) {
         lines.push(`\nTransition committed: \`${r.transitionId}\``);
@@ -125,7 +125,7 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
         lines.push(`\n✅ Validate score: ${String(r.validateScore)}/100${sourceSuffix}`);
     }
     if (r.cascade.affectedSpecs.length > 0) {
-        lines.push(`\n🔗 Downstream specs affected: ${r.cascade.affectedSpecs.map((s) => `SPEC-${s}`).join(', ')}`);
+        lines.push(`\n🔗 Downstream specs affected: ${r.cascade.affectedSpecs.join(', ')}`);
     }
     if (r.codeRealityWarning) {
         lines.push(`\n${r.codeRealityWarning}`);
@@ -200,7 +200,7 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
     const markdownText = reconciliationMarkdown
         ? `${withNextSteps}\n\n${reconciliationMarkdown}`
         : withNextSteps;
-    const displayTitle = specTitle ?? `SPEC-${specId}`;
+    const displayTitle = specTitle ?? specId;
     const humanSummary = buildUpdateStatusSummary(displayTitle, newStatus);
     const warningItems = [
         r.protectedBranchWarning,

package/dist/tools/update-status/side-effects.d.ts

@@ -35,6 +35,7 @@ export declare function fireAndForgetSideEffects(params: {
     projectId: string;
     spec: Spec;
     currentStatus: SpecStatus;
+    projectPath?: string;
 }): void;
 /**
  * SPEC-772: Run cascade and await fast hooks (fast: true) within a 2s window.
@@ -50,5 +51,6 @@ export declare function runCascadeForResponse(params: {
     projectId: string;
     spec: Spec;
     currentStatus: SpecStatus;
+    projectPath?: string;
 }): Promise<RunCascadeResult | null>;
 //# sourceMappingURL=side-effects.d.ts.map

package/dist/tools/update-status/side-effects.js

@@ -193,7 +193,7 @@ function readDisabledByEnv() {
 /** Fire-and-forget side effects after a successful status transition. */
 export function fireAndForgetSideEffects(params) {
     const { knowledge, allSpecs, specId, newStatus, validateScore, projectId, spec, currentStatus } = params;
-    const projectPath = knowledge?.projectPath;
+    const projectPath = params.projectPath ?? knowledge?.projectPath;
     const ctx = {
         specId,
         spec,
@@ -223,7 +223,7 @@ export function fireAndForgetSideEffects(params) {
  */
 export async function runCascadeForResponse(params) {
     const { knowledge, allSpecs, specId, newStatus, validateScore, projectId, spec, currentStatus } = params;
-    const projectPath = knowledge?.projectPath;
+    const projectPath = params.projectPath ?? knowledge?.projectPath;
     const ctx = {
         specId,
         spec,

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

@@ -4,7 +4,7 @@ import { ti } from '../../i18n/index.js';
 import { validateDoR } from '../../engine/dor-dod.js';
 import { dispatchFeedbackEvent } from '../learn.js';
 import { scoreAmbiguityFromPath } from '../../engine/ambiguity-scorer.js';
-import { checkReadinessInternal } from '../../engine/readiness-checker.js';
+import { checkSpecReadiness } from '../../engine/readiness-checker.js';
 import { validateEnglishOnlySpecText } from '../../engine/spec-language/english-only.js';
 import { checkGroundedSpecContract } from '../../engine/spec-grounding/contract.js';
 import { checkGenericSpecOutput } from '../../engine/spec-quality/generic-output-gate.js';
@@ -331,18 +331,21 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             qualityWarnings: [],
         };
     }
-    let score;
-    let warnings;
-    let criteriaCount;
+    let readiness;
     try {
-        ({ score, warnings, criteriaCount } = checkReadinessInternal(body));
+        readiness = await checkSpecReadiness(spec, 'strict');
     }
     catch (error) {
         /* reliability-optional: READINESS_EVALUATION_FAILED — transition fails closed below */
         reportClassifiedDegradation('READINESS_EVALUATION_FAILED', error);
         return readinessUnavailable('READINESS_EVALUATION_FAILED', error instanceof Error ? error.message : 'readiness evaluation failed');
     }
-    if (criteriaCount === 0) {
+    const { score } = readiness;
+    const blockers = [...readiness.issues.blockers];
+    const warnings = [...readiness.issues.warnings];
+    const issues = [...blockers, ...warnings];
+    const hasNoCriteria = readiness.issues.breakdown.criteria === 0;
+    if (hasNoCriteria) {
         if (newStatus === 'review') {
             return {
                 blockResult: {
@@ -357,6 +360,7 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
                         error: 'READINESS_GATE_BLOCKED',
                         score,
                         threshold: 70,
+                        blockers,
                         warnings,
                         fixHint: 'Add at least 3 testable acceptance criteria before moving to review.',
                     },
@@ -388,24 +392,32 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
                     },
                 ],
                 structuredContent: {
+                    error: 'READINESS_GATE_BLOCKED',
+                    score,
+                    threshold: 70,
+                    blockers,
+                    warnings,
                     interactiveQuestions: [question],
                 },
             },
             qualityWarnings: [],
         };
     }
-    if (score >= 70) {
+    if (readiness.ready) {
         return { blockResult: null, qualityWarnings: [] };
     }
+    const diagnostic = score < 70
+        ? `score ${String(score)}/100 is below the 70 threshold`
+        : `score ${String(score)}/100 meets the threshold, but ${String(blockers.length)} canonical blocker(s) remain`;
+    const issuesSummary = issues.slice(0, 3).join('; ');
     if (newStatus === 'review') {
-        const warningsSummary = warnings.slice(0, 3).join('; ');
         return {
             blockResult: {
                 content: [
                     {
                         type: 'text',
-                        text: `Readiness gate blocked transition to review: score ${String(score)}/100 — below 70 threshold. ` +
-                            `Warnings: ${warningsSummary}`,
+                        text: `Readiness gate blocked transition to review: ${diagnostic}. ` +
+                            `Issues: ${issuesSummary}`,
                     },
                 ],
                 isError: true,
@@ -413,6 +425,7 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
                     error: 'READINESS_GATE_BLOCKED',
                     score,
                     threshold: 70,
+                    blockers,
                     warnings,
                     fixHint: 'Complete the spec before moving from draft to review.',
                 },
@@ -423,12 +436,11 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
     // Score < 70
     if (forceApprove) {
         // Caller wants to force through — proceed with warnings attached
-        return { blockResult: null, qualityWarnings: warnings };
+        return { blockResult: null, qualityWarnings: issues };
     }
-    const warningsSummary = warnings.slice(0, 3).join('; ');
     const question = {
         header: 'Readiness gate',
-        question: `Spec readiness score ${String(score)}/100 (threshold: 70). How to proceed?`,
+        question: `Spec readiness ${diagnostic}. How to proceed?`,
         multiSelect: false,
         options: [
             {
@@ -437,7 +449,7 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             },
             {
                 label: 'view_missing',
-                description: `View missing items: ${warningsSummary}`,
+                description: `View missing items: ${issuesSummary}`,
             },
             {
                 label: 'force_approve',
@@ -450,10 +462,15 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
             content: [
                 {
                     type: 'text',
-                    text: `Readiness gate: score ${String(score)}/100 — below 70 threshold. Warnings: ${warningsSummary}`,
+                    text: `Readiness gate: ${diagnostic}. Issues: ${issuesSummary}`,
                 },
             ],
             structuredContent: {
+                error: 'READINESS_GATE_BLOCKED',
+                score,
+                threshold: 70,
+                blockers,
+                warnings,
                 interactiveQuestions: [question],
             },
         },

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

@@ -1,6 +1,7 @@
 import type { ConstitutionViolation } from '../types/index.js';
 export declare function runImplementingActions(projectId: string, specId: string, options?: {
     deferSideEffects?: boolean;
+    projectPath?: string;
 }): Promise<{
     autoBranch: string | undefined;
     protectedBranchWarning: string | null;
@@ -8,9 +9,10 @@ export declare function runImplementingActions(projectId: string, specId: string
     autopilotSummary: string[];
 }>;
 /** Create the implementation branch and refresh derived context after commit. */
-export declare function runImplementingSideEffects(projectId: string, specId: string): Promise<string | undefined>;
+export declare function runImplementingSideEffects(projectId: string, specId: string, transitionProjectPath?: string): Promise<string | undefined>;
 export declare function runDoneActions(projectId: string, specId: string, gitBranch: string | undefined, options?: {
     deferSideEffects?: boolean;
+    projectPath?: string;
 }): Promise<{
     mergeWarning: string | null;
     prSuggestion: {
@@ -22,7 +24,7 @@ export declare function runDoneActions(projectId: string, specId: string, gitBra
     autopilotSummary: string[];
 }>;
 /** Run cleanup and state refreshes only after the done transition is durable. */
-export declare function runDoneSideEffects(projectId: string, specId: string, gitBranch: string | undefined): Promise<void>;
+export declare function runDoneSideEffects(projectId: string, specId: string, gitBranch: string | undefined, transitionProjectPath?: string): Promise<void>;
 /**
  * Best-effort constitution compliance check for status transitions.
  * Returns warnings (never blocks the transition).

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

@@ -8,13 +8,17 @@ function normalizeRejectedReasons(results) {
         return reason instanceof Error ? reason : new Error(String(reason));
     });
 }
+function suppliedProjectPath(value) {
+    const trimmed = value?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : undefined;
+}
 export async function runImplementingActions(projectId, specId, options = {}) {
     let autoBranch;
     let protectedBranchWarning = null;
     // Check if on a protected branch
     try {
         const { resolveProjectPath, git: gitCmd } = await import('./git/git-helpers.js');
-        const projectPath = await resolveProjectPath(projectId);
+        const projectPath = suppliedProjectPath(options.projectPath) ?? (await resolveProjectPath(projectId));
         const { stdout } = await gitCmd(projectPath, ['rev-parse', '--abbrev-ref', 'HEAD']);
         const currentBranch = stdout.trim();
         const protectedBranches = ['main', 'master', 'develop', 'production'];
@@ -27,7 +31,7 @@ export async function runImplementingActions(projectId, specId, options = {}) {
     }
     if (!options.deferSideEffects) {
         try {
-            autoBranch = await runImplementingSideEffects(projectId, specId);
+            autoBranch = await runImplementingSideEffects(projectId, specId, options.projectPath);
         }
         catch {
             // Legacy direct callers keep best-effort behavior.
@@ -41,20 +45,20 @@ export async function runImplementingActions(projectId, specId, options = {}) {
     };
 }
 /** Create the implementation branch and refresh derived context after commit. */
-export async function runImplementingSideEffects(projectId, specId) {
+export async function runImplementingSideEffects(projectId, specId, transitionProjectPath) {
+    const { resolveProjectPath } = await import('./git/git-helpers.js');
+    const projectPath = suppliedProjectPath(transitionProjectPath) ?? (await resolveProjectPath(projectId));
     let autoBranch;
     const foundSpec = await specStore.getSpec(projectId, specId);
     if (foundSpec && !foundSpec.gitBranch) {
         let branchResult;
         try {
-            const { resolveProjectPath: resolveBranchPath } = await import('./git/git-helpers.js');
             const { handleCreateBranch } = await import('./git/branch-ops.js');
-            const branchProjectPath = await resolveBranchPath(projectId);
-            branchResult = await withAudit(branchProjectPath, 'update_status(implementing)', 'handleCreateBranch', () => handleCreateBranch(projectId, specId), (r) => ({ isError: r.isError }));
+            branchResult = await withAudit(projectPath, 'update_status(implementing)', 'handleCreateBranch', () => handleCreateBranch(projectId, specId, undefined, projectPath), (r) => ({ isError: r.isError }));
         }
         catch {
             const { handleCreateBranch } = await import('./git/branch-ops.js');
-            branchResult = await handleCreateBranch(projectId, specId);
+            branchResult = await handleCreateBranch(projectId, specId, undefined, projectPath);
         }
         if (!branchResult.isError) {
             try {
@@ -70,8 +74,6 @@ export async function runImplementingSideEffects(projectId, specId) {
     // SPEC-600: Fire-and-forget cascade — recommend_model, orchestration plan, context check
     // -------------------------------------------------------------------------
     try {
-        const { resolveProjectPath: resolveCascadePath } = await import('./git/git-helpers.js');
-        const projectPath = await resolveCascadePath(projectId);
         const spec = foundSpec ?? (await specStore.getSpec(projectId, specId));
         const results = await Promise.allSettled([
             // SPEC-633: Write session state when spec moves to implementing
@@ -161,7 +163,7 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
         (async () => {
             try {
                 const { resolveProjectPath, git: gitCmd } = await import('./git/git-helpers.js');
-                const projectPath = await resolveProjectPath(projectId);
+                const projectPath = suppliedProjectPath(options.projectPath) ?? (await resolveProjectPath(projectId));
                 if (process.env.PLANU_ENABLE_AUTOCOMMIT === 'true') {
                     await gitCmd(projectPath, ['add', 'planu/']);
                     const { planuAutoCommit } = await import('../engine/git/planu-autocommit.js');
@@ -193,7 +195,7 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
         const mergeResult = await Promise.resolve((async () => {
             try {
                 const { resolveProjectPath, resolveBaseBranch, git: gitCmd, } = await import('./git/git-helpers.js');
-                const projectPath = await resolveProjectPath(projectId);
+                const projectPath = suppliedProjectPath(options.projectPath) ?? (await resolveProjectPath(projectId));
                 await gitCmd(projectPath, ['rev-parse', '--verify', gitBranch]);
                 const baseBranch = await resolveBaseBranch(projectPath);
                 if (!baseBranch) {
@@ -213,7 +215,7 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
         mergeWarning = mergeResult;
     }
     if (!options.deferSideEffects) {
-        void runDoneSideEffects(projectId, specId, gitBranch).catch(() => {
+        void runDoneSideEffects(projectId, specId, gitBranch, options.projectPath).catch(() => {
             // Legacy direct callers keep best-effort behavior.
         });
     }
@@ -231,9 +233,9 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
     };
 }
 /** Run cleanup and state refreshes only after the done transition is durable. */
-export async function runDoneSideEffects(projectId, specId, gitBranch) {
+export async function runDoneSideEffects(projectId, specId, gitBranch, transitionProjectPath) {
     const { resolveProjectPath } = await import('./git/git-helpers.js');
-    const projectPath = await resolveProjectPath(projectId);
+    const projectPath = suppliedProjectPath(transitionProjectPath) ?? (await resolveProjectPath(projectId));
     const results = await Promise.allSettled([
         (async () => {
             const { cleanupSpecOnDone } = await import('./git/cleanup-ops.js');