@planu/cli 4.11.7 → 4.11.8

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

@@ -86,6 +86,12 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
     const lines = [
         `**SPEC-${specId}** moved: ${fromEmoji} \`${currentStatus}\` → ${toEmoji} \`${newStatus}\``,
     ];
+    if (r.committed && r.transitionId) {
+        lines.push(`\nTransition committed: \`${r.transitionId}\``);
+    }
+    if (r.pendingBackgroundActions && r.pendingBackgroundActions.length > 0) {
+        lines.push(`\nBackground actions queued: ${r.pendingBackgroundActions.join(', ')}`);
+    }
     if (r.autoBranch) {
         lines.push(`\n🌿 Branch created: \`${r.autoBranch}\``);
     }
@@ -221,6 +227,11 @@ export function buildStatusResponse(result, specId, currentStatus, newStatus, re
         specId,
         previousStatus: currentStatus,
         newStatus,
+        committed: r.committed ?? undefined,
+        transitionId: r.transitionId ?? undefined,
+        committedAt: r.committedAt ?? undefined,
+        idempotent: r.idempotent ?? undefined,
+        pendingBackgroundActions: r.pendingBackgroundActions ?? undefined,
         autoBranch: r.autoBranch ?? undefined,
         protectedBranchWarning: r.protectedBranchWarning ?? undefined,
         mergeWarning: r.mergeWarning ?? undefined,

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

@@ -1,7 +1,22 @@
 import type { SpecStatus } from '../../types/index.js';
-import type { knowledgeStore } from '../../storage/index.js';
+import { type knowledgeStore } from '../../storage/index.js';
 import type { Spec } from '../../types/spec/core.js';
 import type { RunCascadeResult } from '../../types/cascade-hooks.js';
+export interface PostCommitTask {
+    name: string;
+    run: (signal?: AbortSignal) => Promise<unknown>;
+    timeoutMs?: number;
+}
+/**
+ * Queue optional work after a durable transition. Returns immediately and
+ * deduplicates retries by transition identity for the lifetime of the process.
+ */
+export declare function queuePostCommitTasks(args: {
+    projectId: string;
+    specId: string;
+    transitionId: string;
+    tasks: PostCommitTask[];
+}): string[];
 /**
  * SPEC-585: Autopush on done if configured.
  * Returns the push result for inclusion in autopilotSummary (or null when disabled/skipped).

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

@@ -1,4 +1,144 @@
+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;
+const queuedTransitions = new Map();
+function rememberTransition(transitionKey) {
+    if (queuedTransitions.has(transitionKey)) {
+        return false;
+    }
+    if (queuedTransitions.size >= MAX_DEDUPED_TRANSITIONS) {
+        const oldest = queuedTransitions.keys().next().value;
+        if (oldest !== undefined) {
+            queuedTransitions.delete(oldest);
+        }
+    }
+    queuedTransitions.set(transitionKey, Date.now());
+    return true;
+}
+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 claim = await specStore.claimPostCommitTask(projectId, specId, transitionId, task.name, {
+        leaseMs,
+    });
+    if (!claim.claimed) {
+        return;
+    }
+    const startedAt = Date.now();
+    const controller = new AbortController();
+    let timer;
+    let heartbeat;
+    try {
+        heartbeat = setInterval(() => {
+            void specStore
+                .renewPostCommitTaskLease(projectId, specId, transitionId, task.name, claim.executionId, {
+                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),
+                });
+            });
+        }, Math.max(1_000, Math.floor(leaseMs / 3)));
+        heartbeat.unref();
+        const runPromise = Promise.resolve().then(() => task.run(controller.signal));
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => {
+                controller.abort(new Error(`Timed out after ${String(timeoutMs)}ms`));
+                resolve('timeout');
+            }, timeoutMs);
+            timer.unref();
+        });
+        const firstResult = await Promise.race([runPromise.then(() => 'completed'), timeout]);
+        if (firstResult === 'timeout') {
+            await runPromise;
+            await specStore.settlePostCommitTask(projectId, specId, transitionId, task.name, claim.executionId, { status: 'done' });
+            try {
+                await appendAutopilotLogEntry(projectId, {
+                    specId,
+                    hookName: `post-commit:${task.name}:${transitionId}`,
+                    result: 'fail',
+                    error: `Timed out after ${String(timeoutMs)}ms, then completed successfully; retry suppressed.`,
+                    timestamp: new Date().toISOString(),
+                    durationMs: Date.now() - startedAt,
+                });
+            }
+            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),
+                });
+            }
+            return;
+        }
+        await specStore.settlePostCommitTask(projectId, specId, transitionId, task.name, claim.executionId, { status: 'done' });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(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),
+            });
+        });
+        try {
+            await appendAutopilotLogEntry(projectId, {
+                specId,
+                hookName: `post-commit:${task.name}:${transitionId}`,
+                result: 'fail',
+                error: message,
+                timestamp: new Date().toISOString(),
+                durationMs: Date.now() - startedAt,
+            });
+        }
+        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),
+            });
+        }
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+        if (heartbeat !== undefined) {
+            clearInterval(heartbeat);
+        }
+    }
+}
+/**
+ * Queue optional work after a durable transition. Returns immediately and
+ * deduplicates retries by transition identity for the lifetime of the process.
+ */
+export function queuePostCommitTasks(args) {
+    const transitionKey = `${args.projectId}\0${args.specId}\0${args.transitionId}`;
+    if (!rememberTransition(transitionKey)) {
+        return [];
+    }
+    void Promise.allSettled(args.tasks.map((task) => runBoundedPostCommitTask({ ...args, task }))).finally(() => {
+        queuedTransitions.delete(transitionKey);
+    });
+    return args.tasks.map((task) => task.name);
+}
 /**
  * SPEC-585: Autopush on done if configured.
  * Returns the push result for inclusion in autopilotSummary (or null when disabled/skipped).

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

@@ -21,7 +21,7 @@ import { getResolvedChallengeEvidence, requiredResolvedChallenges, } from '../ch
 export const VALID_TRANSITIONS = {
     draft: ['review', 'discarded'],
     review: ['draft', 'approved', 'discarded'],
-    approved: ['review', 'implementing', 'discarded'],
+    approved: ['draft', 'review', 'implementing', 'discarded'],
     implementing: ['approved', 'done', 'discarded'],
     done: ['implementing'], // SPEC-733: reverse transition with mandatory reason
     discarded: ['draft'], // SPEC-733: reverse transition with mandatory reason

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

@@ -1,11 +1,17 @@
 import type { ConstitutionViolation } from '../types/index.js';
-export declare function runImplementingActions(projectId: string, specId: string): Promise<{
+export declare function runImplementingActions(projectId: string, specId: string, options?: {
+    deferSideEffects?: boolean;
+}): Promise<{
     autoBranch: string | undefined;
     protectedBranchWarning: string | null;
     suggestions: string[];
     autopilotSummary: string[];
 }>;
-export declare function runDoneActions(projectId: string, specId: string, gitBranch: string | undefined): Promise<{
+/** Create the implementation branch and refresh derived context after commit. */
+export declare function runImplementingSideEffects(projectId: string, specId: string): Promise<string | undefined>;
+export declare function runDoneActions(projectId: string, specId: string, gitBranch: string | undefined, options?: {
+    deferSideEffects?: boolean;
+}): Promise<{
     mergeWarning: string | null;
     prSuggestion: {
         title: string;
@@ -15,6 +21,8 @@ export declare function runDoneActions(projectId: string, specId: string, gitBra
     uncommittedWarning: string | null;
     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>;
 /**
  * Best-effort constitution compliance check for status transitions.
  * Returns warnings (never blocks the transition).

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

@@ -2,7 +2,13 @@ import { specStore, knowledgeStore } from '../storage/index.js';
 import { checkConstitutionCompliance } from './create-spec-tech.js';
 import { withAudit } from '../engine/autopilot/audit-logger.js';
 import { hasPending, markPending, clearPending } from '../engine/autopilot/cascade-deduplicator.js';
-export async function runImplementingActions(projectId, specId) {
+function normalizeRejectedReasons(results) {
+    return results.map((result) => {
+        const reason = result.reason;
+        return reason instanceof Error ? reason : new Error(String(reason));
+    });
+}
+export async function runImplementingActions(projectId, specId, options = {}) {
     let autoBranch;
     let protectedBranchWarning = null;
     // Check if on a protected branch
@@ -19,7 +25,24 @@ export async function runImplementingActions(projectId, specId) {
     catch {
         // Not a git repo — skip check
     }
-    // Auto-create branch
+    if (!options.deferSideEffects) {
+        try {
+            autoBranch = await runImplementingSideEffects(projectId, specId);
+        }
+        catch {
+            // Legacy direct callers keep best-effort behavior.
+        }
+    }
+    return {
+        autoBranch,
+        protectedBranchWarning,
+        suggestions: [],
+        autopilotSummary: [],
+    };
+}
+/** Create the implementation branch and refresh derived context after commit. */
+export async function runImplementingSideEffects(projectId, specId) {
+    let autoBranch;
     const foundSpec = await specStore.getSpec(projectId, specId);
     if (foundSpec && !foundSpec.gitBranch) {
         let branchResult;
@@ -46,98 +69,89 @@ export async function runImplementingActions(projectId, specId) {
     // -------------------------------------------------------------------------
     // SPEC-600: Fire-and-forget cascade — recommend_model, orchestration plan, context check
     // -------------------------------------------------------------------------
-    const autopilotSummary = [];
-    void (async () => {
-        try {
-            const { resolveProjectPath: resolveCascadePath } = await import('./git/git-helpers.js');
-            const projectPath = await resolveCascadePath(projectId);
-            const spec = foundSpec ?? (await specStore.getSpec(projectId, specId));
-            void Promise.allSettled([
-                // SPEC-633: Write session state when spec moves to implementing
-                (async () => {
-                    const { writeSpecSessionState } = await import('../engine/session-state/writer.js');
-                    await writeSpecSessionState(projectPath, specId, spec?.title ?? specId, 'moved to implementing').catch(() => {
-                        /* best-effort */
-                    });
-                })(),
-                // SPEC-635: Regenerate context.md
-                (async () => {
-                    const { generateContextMd } = await import('../engine/context-md-generator.js');
-                    await generateContextMd(projectPath, projectId).catch(() => {
+    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
+            (async () => {
+                const { writeSpecSessionState } = await import('../engine/session-state/writer.js');
+                await writeSpecSessionState(projectPath, specId, spec?.title ?? specId, 'moved to implementing').catch(() => {
+                    /* best-effort */
+                });
+            })(),
+            // SPEC-635: Regenerate context.md
+            (async () => {
+                const { generateContextMd } = await import('../engine/context-md-generator.js');
+                await generateContextMd(projectPath, projectId).catch(() => {
+                    /* best-effort */
+                });
+            })(),
+            // SPEC-656: Recalculate epicProgress when spec moves to implementing
+            (async () => {
+                try {
+                    const { updateEpicProgressInSession } = await import('../engine/session-state/writer.js');
+                    const allSpecs = await specStore.listSpecs(projectId);
+                    await updateEpicProgressInSession(projectPath, allSpecs).catch(() => {
                         /* best-effort */
                     });
-                })(),
-                // SPEC-656: Recalculate epicProgress when spec moves to implementing
-                (async () => {
-                    try {
-                        const { updateEpicProgressInSession } = await import('../engine/session-state/writer.js');
-                        const allSpecs = await specStore.listSpecs(projectId);
-                        await updateEpicProgressInSession(projectPath, allSpecs).catch(() => {
-                            /* best-effort */
+                }
+                catch {
+                    /* best-effort */
+                }
+            })(),
+            // recommend_model — suggest haiku/sonnet/opus based on spec complexity
+            (async () => {
+                try {
+                    const { handleRecommendModel } = await import('./recommend-model-handler.js');
+                    const result = handleRecommendModel({ specId });
+                    void result;
+                }
+                catch {
+                    /* best-effort */
+                }
+            })(),
+            // generate_orchestration_plan — if cross-module or high difficulty
+            (async () => {
+                try {
+                    const scope = spec?.scope ?? '';
+                    const difficulty = spec?.difficulty ?? 1;
+                    if (scope === 'cross-module' || difficulty >= 3) {
+                        const { handleGenerateOrchestrationScript } = await import('./generate-orchestration-script.js');
+                        handleGenerateOrchestrationScript({
+                            specIds: [specId],
+                            projectPath,
                         });
                     }
-                    catch {
-                        /* best-effort */
-                    }
-                })(),
-                // recommend_model — suggest haiku/sonnet/opus based on spec complexity
-                (async () => {
-                    try {
-                        const { handleRecommendModel } = await import('./recommend-model-handler.js');
-                        const result = handleRecommendModel({ specId });
-                        if (!result.isError) {
-                            autopilotSummary.push('recommend_model: auto-recommended');
-                        }
-                    }
-                    catch {
-                        /* best-effort */
-                    }
-                })(),
-                // generate_orchestration_plan — if cross-module or high difficulty
-                (async () => {
-                    try {
-                        const scope = spec?.scope ?? '';
-                        const difficulty = spec?.difficulty ?? 1;
-                        if (scope === 'cross-module' || difficulty >= 3) {
-                            const { handleGenerateOrchestrationScript } = await import('./generate-orchestration-script.js');
-                            handleGenerateOrchestrationScript({
-                                specIds: [specId],
-                                projectPath,
-                            });
-                            autopilotSummary.push('generate_orchestration_plan: auto-generated');
-                        }
-                    }
-                    catch {
-                        /* best-effort */
-                    }
-                })(),
-                // context_window_status — check context weight and warn
-                (async () => {
-                    try {
-                        const { handleContextWindowStatus } = await import('./context-manager-handler.js');
-                        const ctxResult = await handleContextWindowStatus({ projectPath });
-                        if (!ctxResult.isError) {
-                            autopilotSummary.push('context_window_status: checked');
-                        }
-                    }
-                    catch {
-                        /* best-effort */
-                    }
-                })(),
-            ]);
-        }
-        catch {
-            // Project path unavailable — skip cascade silently
+                }
+                catch {
+                    /* best-effort */
+                }
+            })(),
+            // context_window_status — check context weight and warn
+            (async () => {
+                try {
+                    const { handleContextWindowStatus } = await import('./context-manager-handler.js');
+                    const ctxResult = await handleContextWindowStatus({ projectPath });
+                    void ctxResult;
+                }
+                catch {
+                    /* best-effort */
+                }
+            })(),
+        ]);
+        const failures = results.filter((result) => result.status === 'rejected');
+        if (failures.length > 0) {
+            throw new AggregateError(normalizeRejectedReasons(failures), `${String(failures.length)} implementing side effect(s) failed`);
         }
-    })();
-    return {
-        autoBranch,
-        protectedBranchWarning,
-        suggestions: [],
-        autopilotSummary,
-    };
+    }
+    catch (error) {
+        throw error instanceof Error ? error : new Error(String(error));
+    }
+    return autoBranch;
 }
-export async function runDoneActions(projectId, specId, gitBranch) {
+export async function runDoneActions(projectId, specId, gitBranch, options = {}) {
     // -------------------------------------------------------------------------
     // SPEC-628: Group A — fast synchronous checks only (< 100ms each)
     // Validation removed: already done by runValidateGate in index.ts (BATCH B)
@@ -198,112 +212,15 @@ export async function runDoneActions(projectId, specId, gitBranch) {
         })());
         mergeWarning = mergeResult;
     }
-    // -------------------------------------------------------------------------
-    // Group C — fire-and-forget side effects: launch all in parallel, don't await
-    // -------------------------------------------------------------------------
-    void (async () => {
-        try {
-            const { resolveProjectPath } = await import('./git/git-helpers.js');
-            const projectPath = await resolveProjectPath(projectId);
-            // AC-01: Cleanup worktree, local branch, and remote branch for done spec (best-effort)
-            // SPEC-491: Sweep planu/ to remove legacy files
-            // SPEC-496: Auto-generate portable session context snapshot
-            void Promise.allSettled([
-                (async () => {
-                    const { cleanupSpecOnDone } = await import('./git/cleanup-ops.js');
-                    await withAudit(projectPath, 'update_status(done)', 'cleanupSpecOnDone', () => cleanupSpecOnDone(projectPath, specId, gitBranch)).catch(() => {
-                        /* best-effort — never blocks status transition */
-                    });
-                })(),
-                // SPEC-633: Remove spec from session.json index when done
-                (async () => {
-                    const { removeSpecFromSession } = await import('../engine/session-state/writer.js');
-                    await removeSpecFromSession(projectPath, specId).catch(() => {
-                        /* best-effort */
-                    });
-                })(),
-                // SPEC-656: Recalculate epicProgress after status change
-                (async () => {
-                    try {
-                        const { updateEpicProgressInSession } = await import('../engine/session-state/writer.js');
-                        const allSpecs = await specStore.listSpecs(projectId);
-                        await updateEpicProgressInSession(projectPath, allSpecs).catch(() => {
-                            /* best-effort */
-                        });
-                    }
-                    catch {
-                        /* best-effort */
-                    }
-                })(),
-                // SPEC-635: Regenerate context.md after status change
-                (async () => {
-                    const { generateContextMd } = await import('../engine/context-md-generator.js');
-                    await generateContextMd(projectPath, projectId).catch(() => {
-                        /* best-effort */
-                    });
-                })(),
-                (async () => {
-                    const { join } = await import('node:path');
-                    const { cleanPlanuRoot } = await import('../engine/spec-migrator/planu-root-cleaner.js');
-                    await cleanPlanuRoot(join(projectPath, 'planu')).catch(() => {
-                        /* best-effort */
-                    });
-                })(),
-                // SPEC-1002: Auto-cleanup stale branches/worktrees when spec reaches done
-                (async () => {
-                    try {
-                        const { runHousekeepingSweep } = await import('../engine/housekeeping/index.js');
-                        await runHousekeepingSweep({ projectPath, dryRun: false }).catch(() => {
-                            /* best-effort — never blocks status transition */
-                        });
-                    }
-                    catch {
-                        /* best-effort */
-                    }
-                })(),
-                // SPEC-660: Dedup — session.json update runs once per spec within 5s window
-                (async () => {
-                    if (hasPending(specId, 'generateSessionContext')) {
-                        return;
-                    }
-                    markPending(specId, 'generateSessionContext');
-                    try {
-                        const { generateSessionContext } = await import('../engine/session-context-generator.js');
-                        await generateSessionContext(projectPath, projectId).catch(() => {
-                            /* best-effort — never blocks status transition */
-                        });
-                    }
-                    finally {
-                        clearPending(specId, 'generateSessionContext');
-                    }
-                })(),
-                // SPEC-629: Delete ephemeral prompt.md — file served its purpose once implementing starts
-                (async () => {
-                    /* v8 ignore start */
-                    try {
-                        const { glob } = await import('glob');
-                        const { unlink } = await import('node:fs/promises');
-                        const specFiles = await glob(`planu/specs/${specId}-*/prompt.md`, { cwd: projectPath, absolute: true });
-                        const exactFile = await glob(`planu/specs/${specId}/prompt.md`, { cwd: projectPath, absolute: true });
-                        await Promise.allSettled([...specFiles, ...exactFile].map((f) => unlink(f).catch(() => {
-                            /* best-effort */
-                        })));
-                    }
-                    catch {
-                        /* best-effort — never blocks status transition */
-                    }
-                    /* v8 ignore stop */
-                })(),
-            ]);
-        }
-        catch {
-            // Project path unavailable — skip all fire-and-forget cleanup silently
-        }
-    })();
+    if (!options.deferSideEffects) {
+        void runDoneSideEffects(projectId, specId, gitBranch).catch(() => {
+            // Legacy direct callers keep best-effort behavior.
+        });
+    }
     // SPEC-649: slim cascade — 2 actions only
     const autopilotSummary = [
-        'session.json: updated (next spec suggested)',
-        'releases/pending.json: spec appended',
+        'session.json: refresh queued',
+        'releases/pending.json: refresh queued',
     ];
     return {
         mergeWarning,
@@ -313,6 +230,63 @@ export async function runDoneActions(projectId, specId, gitBranch) {
         autopilotSummary,
     };
 }
+/** Run cleanup and state refreshes only after the done transition is durable. */
+export async function runDoneSideEffects(projectId, specId, gitBranch) {
+    const { resolveProjectPath } = await import('./git/git-helpers.js');
+    const projectPath = await resolveProjectPath(projectId);
+    const results = await Promise.allSettled([
+        (async () => {
+            const { cleanupSpecOnDone } = await import('./git/cleanup-ops.js');
+            await withAudit(projectPath, 'update_status(done)', 'cleanupSpecOnDone', () => cleanupSpecOnDone(projectPath, specId, gitBranch));
+        })(),
+        (async () => {
+            const { removeSpecFromSession } = await import('../engine/session-state/writer.js');
+            await removeSpecFromSession(projectPath, specId);
+        })(),
+        (async () => {
+            const { updateEpicProgressInSession } = await import('../engine/session-state/writer.js');
+            const allSpecs = await specStore.listSpecs(projectId);
+            await updateEpicProgressInSession(projectPath, allSpecs);
+        })(),
+        (async () => {
+            const { generateContextMd } = await import('../engine/context-md-generator.js');
+            await generateContextMd(projectPath, projectId);
+        })(),
+        (async () => {
+            const { join } = await import('node:path');
+            const { cleanPlanuRoot } = await import('../engine/spec-migrator/planu-root-cleaner.js');
+            await cleanPlanuRoot(join(projectPath, 'planu'));
+        })(),
+        (async () => {
+            const { runHousekeepingSweep } = await import('../engine/housekeeping/index.js');
+            await runHousekeepingSweep({ projectPath, dryRun: false });
+        })(),
+        (async () => {
+            if (hasPending(specId, 'generateSessionContext')) {
+                return;
+            }
+            markPending(specId, 'generateSessionContext');
+            try {
+                const { generateSessionContext } = await import('../engine/session-context-generator.js');
+                await generateSessionContext(projectPath, projectId);
+            }
+            finally {
+                clearPending(specId, 'generateSessionContext');
+            }
+        })(),
+        (async () => {
+            const { glob } = await import('glob');
+            const { unlink } = await import('node:fs/promises');
+            const specFiles = await glob(`planu/specs/${specId}-*/prompt.md`, { cwd: projectPath, absolute: true });
+            const exactFiles = await glob(`planu/specs/${specId}/prompt.md`, { cwd: projectPath, absolute: true });
+            await Promise.allSettled([...specFiles, ...exactFiles].map((file) => unlink(file)));
+        })(),
+    ]);
+    const failures = results.filter((result) => result.status === 'rejected');
+    if (failures.length > 0) {
+        throw new AggregateError(normalizeRejectedReasons(failures), `${String(failures.length)} done side effect(s) failed`);
+    }
+}
 /**
  * Best-effort constitution compliance check for status transitions.
  * Returns warnings (never blocks the transition).

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

@@ -1,7 +1,9 @@
 import type { SpecStatus, ComplianceGateResult } from '../types/index.js';
+/** Test-only reset to prevent process-cache state leaking between cases. */
+export declare function resetProcessValidationCacheForTests(): void;
 /**
  * Runs non-blocking transition checks not already covered by the authoritative validate report.
  * in parallel. Extracts complexity from handleUpdateStatus.
  */
-export declare function runComplianceGates(projectId: string, specTitle: string, specTags: string[], newStatus: SpecStatus): Promise<ComplianceGateResult>;
+export declare function runComplianceGates(projectId: string, specTitle: string, specTags: string[], newStatus: SpecStatus, specId?: string): Promise<ComplianceGateResult>;
 //# sourceMappingURL=update-status-convention-gate.d.ts.map