@planu/cli 4.13.0 → 5.0.0

package/dist/tools/update-status/qa-gate.d.ts

@@ -1,5 +1,5 @@
 import type { ToolResult } from '../../types/index.js';
 import type { Spec } from '../../types/spec/core.js';
 /** SPEC-642 / SPEC-1111 / SPEC-1144: verify canonical QA evidence before done. */
-export declare function checkQaGate(spec: Spec, projectPath: string | undefined, force: boolean): Promise<ToolResult | null>;
+export declare function checkQaGate(spec: Spec, projectPath: string | undefined, force: boolean, canonicalProjectId?: string): Promise<ToolResult | null>;
 //# sourceMappingURL=qa-gate.d.ts.map

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

@@ -1,13 +1,13 @@
 import { getToolExecutionSignal } from '../safe-handler.js';
 /** SPEC-642 / SPEC-1111 / SPEC-1144: verify canonical QA evidence before done. */
-export async function checkQaGate(spec, projectPath, force) {
+export async function checkQaGate(spec, projectPath, force, canonicalProjectId) {
     if (force || !projectPath) {
         return null;
     }
     const specId = spec.id;
     const { runQaGate } = await import('../../engine/qa-gate.js');
     const effectiveResult = await runQaGate(spec, projectPath, {
-        projectId: spec.projectId,
+        projectId: canonicalProjectId,
         signal: getToolExecutionSignal(),
     });
     if (effectiveResult.passed) {

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

@@ -1,15 +1,14 @@
 import { specStore } from '../../storage/index.js';
 import { runCascade } from '../../engine/cascade-hooks/runner.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
-const DEFAULT_POST_COMMIT_TASK_TIMEOUT_MS = 10_000;
-const MIN_POST_COMMIT_LEASE_MS = 30_000;
-const MAX_DEDUPED_TRANSITIONS = 1_000;
+import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
+import { getRuntimePolicy } from '../../engine/runtime-policy.js';
 const queuedTransitions = new Map();
 function rememberTransition(transitionKey) {
     if (queuedTransitions.has(transitionKey)) {
         return false;
     }
-    if (queuedTransitions.size >= MAX_DEDUPED_TRANSITIONS) {
+    if (queuedTransitions.size >= getRuntimePolicy().postCommit.maximumRememberedTransitions) {
         const oldest = queuedTransitions.keys().next().value;
         if (oldest !== undefined) {
             queuedTransitions.delete(oldest);
@@ -20,8 +19,9 @@ function rememberTransition(transitionKey) {
 }
 async function runBoundedPostCommitTask(args) {
     const { projectId, specId, transitionId, task } = args;
-    const timeoutMs = task.timeoutMs ?? DEFAULT_POST_COMMIT_TASK_TIMEOUT_MS;
-    const leaseMs = Math.max(MIN_POST_COMMIT_LEASE_MS, timeoutMs * 3);
+    const policy = getRuntimePolicy().postCommit;
+    const timeoutMs = task.timeoutMs ?? policy.defaultTaskTimeoutMs;
+    const leaseMs = Math.max(policy.minimumLeaseMs, timeoutMs * policy.leaseMultiplier);
     const claim = await specStore.claimPostCommitTask(projectId, specId, transitionId, task.name, {
         leaseMs,
     });
@@ -39,14 +39,10 @@ async function runBoundedPostCommitTask(args) {
                 leaseMs,
             })
                 .catch((error) => {
-                console.warn('[planu:post-commit] failed to renew task lease', {
-                    specId,
-                    transitionId,
-                    task: task.name,
-                    error: error instanceof Error ? error.message : String(error),
-                });
+                /* reliability-optional: POST_COMMIT_LEASE_RENEW — timeout path settles the durable task */
+                reportClassifiedDegradation('POST_COMMIT_LEASE_RENEW', error);
             });
-        }, Math.max(1_000, Math.floor(leaseMs / 3)));
+        }, Math.max(policy.minimumHeartbeatMs, Math.floor(leaseMs / policy.leaseMultiplier)));
         heartbeat.unref();
         const runPromise = Promise.resolve().then(() => task.run(controller.signal));
         const timeout = new Promise((resolve) => {
@@ -71,31 +67,25 @@ async function runBoundedPostCommitTask(args) {
                 });
             }
             catch (logError) {
-                console.warn('[planu:post-commit] failed to record late task completion', {
-                    specId,
-                    transitionId,
-                    task: task.name,
-                    error: logError instanceof Error ? logError.message : String(logError),
-                });
+                /* reliability-optional: LATE_TASK_COMPLETION_LOG — durable task is already settled */
+                reportClassifiedDegradation('LATE_TASK_COMPLETION_LOG', logError);
             }
             return;
         }
         await specStore.settlePostCommitTask(projectId, specId, transitionId, task.name, claim.executionId, { status: 'done' });
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
+        /* reliability-optional: POST_COMMIT_TASK_FAILURE — durable failed state is persisted below */
+        reportClassifiedDegradation('POST_COMMIT_TASK_FAILURE', error);
+        const message = redactFailureMessage(error);
         await specStore
             .settlePostCommitTask(projectId, specId, transitionId, task.name, claim.executionId, {
             status: 'failed',
             error: message,
         })
             .catch((settleError) => {
-            console.warn('[planu:post-commit] failed to persist task failure', {
-                specId,
-                transitionId,
-                task: task.name,
-                error: settleError instanceof Error ? settleError.message : String(settleError),
-            });
+            /* reliability-optional: TASK_FAILURE_SETTLEMENT — recovery lease remains retryable */
+            reportClassifiedDegradation('TASK_FAILURE_SETTLEMENT', settleError);
         });
         try {
             await appendAutopilotLogEntry(projectId, {
@@ -108,12 +98,8 @@ async function runBoundedPostCommitTask(args) {
             });
         }
         catch (logError) {
-            console.warn('[planu:post-commit] failed to record task failure', {
-                specId,
-                transitionId,
-                task: task.name,
-                error: logError instanceof Error ? logError.message : String(logError),
-            });
+            /* reliability-optional: TASK_FAILURE_LOG — durable failure state remains authoritative */
+            reportClassifiedDegradation('TASK_FAILURE_LOG', logError);
         }
     }
     finally {
@@ -167,7 +153,9 @@ export async function maybeSafePushOnDone(projectPath, newStatus) {
         }
         return { label: 'autopush', message: `Not pushed: ${result.reason} — ${result.message}` };
     }
-    catch {
+    catch (error) {
+        /* reliability-optional: AUTOPUSH_RESULT_UNAVAILABLE — optional result is explicitly absent */
+        reportClassifiedDegradation('AUTOPUSH_RESULT_UNAVAILABLE', error);
         return null;
     }
 }
@@ -184,7 +172,9 @@ async function readDisabledByConfig(projectPath) {
         const disabled = parsed.cascadeHooks?.disabled;
         return Array.isArray(disabled) ? new Set(disabled) : new Set();
     }
-    catch {
+    catch (error) {
+        /* reliability-optional: CASCADE_CONFIG_UNAVAILABLE — default empty disable set is explicit */
+        reportClassifiedDegradation('CASCADE_CONFIG_UNAVAILABLE', error);
         return new Set();
     }
 }
@@ -203,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,
@@ -221,8 +211,9 @@ export function fireAndForgetSideEffects(params) {
             Promise.resolve(readDisabledByEnv()),
         ]);
         await runCascade(ctx, { disabledByConfig, disabledByEnv });
-    })().catch(() => {
-        /* best-effort — cascade errors never surface to the caller */
+    })().catch((error) => {
+        /* reliability-optional: ASYNC_CASCADE_FAILURE — post-commit task ledger captures retry state */
+        reportClassifiedDegradation('ASYNC_CASCADE_FAILURE', error);
     });
 }
 /**
@@ -232,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,
@@ -250,7 +241,9 @@ export async function runCascadeForResponse(params) {
         ]);
         return await runCascade(ctx, { disabledByConfig, disabledByEnv });
     }
-    catch {
+    catch (error) {
+        /* reliability-optional: CASCADE_SYNC_FAILURE — explicit null reports unavailable result */
+        reportClassifiedDegradation('CASCADE_SYNC_FAILURE', error);
         return null;
     }
 }

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

@@ -53,15 +53,17 @@ export declare function checkTransition(currentStatus: SpecStatus, newStatus: Sp
  * Returns an error ToolResult if blocked, null if passed.
  */
 export declare function checkDorGate(spec: Spec, specId: string, projectId: string, newStatus: SpecStatus): ToolResult | null;
+/** Reject implementation until every declared dependency exists and is done. */
+export declare function checkImplementationDependencyGate(spec: Spec, allSpecs: readonly Spec[], newStatus: SpecStatus): ToolResult | null;
 /**
  * SPEC-632: Block transition to 'approved' if ambiguity score < 70.
- * Best-effort: if spec file cannot be read, gate is skipped.
+ * Fails closed when the spec cannot be scored.
  */
 export declare function checkAmbiguityGate(spec: Spec, newStatus: SpecStatus): Promise<ToolResult | null>;
 /**
  * SPEC-769/SPEC-492: Readiness gate — block 'review'/'approved' when spec
  * quality is too low or the persisted spec document is not English.
- * Best-effort: if spec.md cannot be read, the gate is skipped (returns no block).
+ * Fails closed if spec.md cannot be read or evaluated.
  *
  * - 0 criteria → InteractiveQuestion (hard block, no force path)
  * - score < 70 on approved && !forceApprove → InteractiveQuestion with 3 options

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

@@ -4,12 +4,14 @@ 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';
 import { formatKeyValue } from '../output-formatter.js';
 import { getResolvedChallengeEvidence, requiredResolvedChallenges, } from '../challenge-spec/challenge-report.js';
+import { evaluateSpecDependencies } from '../../engine/dependency-evaluator.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 /**
  * Valid state transitions for spec lifecycle.
  * draft -> review -> approved -> implementing -> done
@@ -129,7 +131,8 @@ export function checkDorGate(spec, specId, projectId, newStatus) {
             delta: { failedCount: dorResult.blockingItems.length },
             timestamp: new Date().toISOString(),
         }).catch((err) => {
-            console.error('[planu] DoR feedback event failed:', err);
+            /* reliability-optional: DOR_FEEDBACK_EVENT — blocking gate result remains authoritative */
+            reportClassifiedDegradation('DOR_FEEDBACK_EVENT', err);
         });
         return {
             content: [
@@ -162,16 +165,47 @@ export function checkDorGate(spec, specId, projectId, newStatus) {
     }
     return null;
 }
+/** Reject implementation until every declared dependency exists and is done. */
+export function checkImplementationDependencyGate(spec, allSpecs, newStatus) {
+    if (newStatus !== 'implementing' || isReverseTransition(spec.status, newStatus)) {
+        return null;
+    }
+    const evaluation = evaluateSpecDependencies(spec, allSpecs);
+    if (evaluation.allowed) {
+        return null;
+    }
+    const blockingIds = [...new Set(evaluation.blockers.map((blocker) => blocker.specId))];
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Dependency gate blocked implementation: ${evaluation.blockers
+                    .map((blocker) => `${blocker.specId} (${blocker.reason})`)
+                    .join(', ')}.`,
+            },
+        ],
+        isError: true,
+        structuredContent: {
+            error: 'DEPENDENCY_GATE_BLOCKED',
+            code: 'UNMET_DEPENDENCIES',
+            blockingIds,
+            blockers: evaluation.blockers,
+        },
+    };
+}
 /**
  * SPEC-632: Block transition to 'approved' if ambiguity score < 70.
- * Best-effort: if spec file cannot be read, gate is skipped.
+ * Fails closed when the spec cannot be scored.
  */
 export async function checkAmbiguityGate(spec, newStatus) {
     if (newStatus !== 'approved' || !spec.specPath) {
         return null;
     }
     const report = await scoreAmbiguityFromPath(spec.specPath);
-    if (!report || report.score >= 70) {
+    if (!report) {
+        return gateUnavailableResult('AMBIGUITY_GATE_UNAVAILABLE', 'Ambiguity scoring failed.');
+    }
+    if (report.score >= 70) {
         return null;
     }
     return {
@@ -201,7 +235,7 @@ export async function checkAmbiguityGate(spec, newStatus) {
 /**
  * SPEC-769/SPEC-492: Readiness gate — block 'review'/'approved' when spec
  * quality is too low or the persisted spec document is not English.
- * Best-effort: if spec.md cannot be read, the gate is skipped (returns no block).
+ * Fails closed if spec.md cannot be read or evaluated.
  *
  * - 0 criteria → InteractiveQuestion (hard block, no force path)
  * - score < 70 on approved && !forceApprove → InteractiveQuestion with 3 options
@@ -218,13 +252,14 @@ export async function checkReadinessGate(spec, newStatus, forceApprove) {
     try {
         body = await readFile(spec.specPath, 'utf-8');
     }
-    catch {
-        // Best-effort — if file is unreadable, skip gate
-        return { blockResult: null, qualityWarnings: [] };
+    catch (error) {
+        /* reliability-optional: READINESS_SPEC_UNREADABLE — transition fails closed below */
+        reportClassifiedDegradation('READINESS_SPEC_UNREADABLE', error);
+        return readinessUnavailable('READINESS_SPEC_UNREADABLE', error instanceof Error ? error.message : 'spec.md could not be read');
     }
     // Guard: mock environments return undefined; unreadable files return non-string
     if (typeof body !== 'string') {
-        return { blockResult: null, qualityWarnings: [] };
+        return readinessUnavailable('READINESS_SPEC_INVALID', 'spec.md did not return text content');
     }
     const languageValidation = validateEnglishOnlySpecText(body);
     if (!languageValidation.ok) {
@@ -296,16 +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 {
-        return { blockResult: null, qualityWarnings: [] };
+    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: {
@@ -320,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.',
                     },
@@ -351,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,
@@ -376,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.',
                 },
@@ -386,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: [
             {
@@ -400,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',
@@ -413,16 +462,31 @@ 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],
             },
         },
         qualityWarnings: [],
     };
 }
+function gateUnavailableResult(code, message) {
+    return {
+        content: [{ type: 'text', text: `${message} Transition blocked until the gate succeeds.` }],
+        isError: true,
+        structuredContent: { error: code, message, retryable: true },
+    };
+}
+function readinessUnavailable(code, message) {
+    return { blockResult: gateUnavailableResult(code, message), qualityWarnings: [] };
+}
 /**
  * SPEC-964: Challenge gate — block 'review' if challenge_spec was never run
  * or does not contain enough explicit resolution evidence.

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');