@planu/cli 5.3.63 → 5.3.65

package/dist/tools/generate-execution-plan.js

@@ -1,18 +1,113 @@
-// tools/generate-execution-plan.ts — Execution plan tool handler + orchestrator
-// SRP: this file owns only tool I/O and phase orchestration.
-// Phase logic lives in src/engine/execution-plan/phases.ts
-// Mobile distribution lives in src/engine/execution-plan/mobile-distribution.ts
-// Utilities live in src/engine/execution-plan/plan-utils.ts
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { specStore, knowledgeStore, patternStore } from '../storage/index.js';
-import { t, ti } from '../i18n/index.js';
-import { generatePlanMarkdown } from '../engine/dor-dod.js';
-import { generateSetupPhase, generateDataLayerPhase, generateBusinessLogicPhase, generateUIPhase, generateTestingPhase, generateIntegrationPhase, } from '../engine/execution-plan/phases.js';
+import { ti } from '../i18n/index.js';
+import { generatePlanMarkdown, EXECUTION_PLAN_MARKER } from '../engine/dor-dod.js';
+import { extractCanonicalFileOwnership } from '../engine/handoff-packager.js';
+import { readEvidenceArtifacts } from '../engine/evidence-gates/artifact-reader.js';
 import { generateMobileDistributionPhase, isMobileDistributionSpec, } from '../engine/execution-plan/mobile-distribution.js';
 import { isDesktopReleaseSpec, generateDesktopDistributionPhase, } from '../engine/execution-plan/desktop-distribution.js';
-import { determineCriticalPath, findParallelizable, readSpecContent, } from '../engine/execution-plan/plan-utils.js';
+import { determineCriticalPath, findParallelizable, validateExecutionPlanGraph, } from '../engine/execution-plan/plan-utils.js';
 import { projectDataDir } from '../storage/base-store.js';
 import { atomicWriteFile } from '../engine/safety/atomic-write-file.js';
+async function readSpecBody(spec) {
+    try {
+        return await readFile(spec.specPath, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function invalidTaskPlanEntry(taskPlan) {
+    const task = taskPlan.tasks.find((candidate) => candidate.id.trim().length === 0 ||
+        candidate.title.trim().length === 0 ||
+        candidate.acceptanceCriteria.length === 0 ||
+        candidate.acceptanceCriteria.some((criterion) => criterion.trim().length === 0));
+    if (!task) {
+        return undefined;
+    }
+    const trimmedId = task.id.trim();
+    return trimmedId.length > 0 ? trimmedId : '(missing id)';
+}
+async function loadGroundedContract(spec, projectId, specId) {
+    const body = await readSpecBody(spec);
+    const ownership = body
+        ? extractCanonicalFileOwnership(body)
+        : { present: false, toCreate: [], toModify: [], toTest: [], toTestDeclared: [], blockers: [] };
+    const ownedFiles = [...ownership.toCreate, ...ownership.toModify];
+    if (!ownership.present || ownedFiles.length === 0) {
+        return {
+            ok: false,
+            issues: [
+                'No approved file ownership found under the spec ## Files section; cannot ground execution steps.',
+            ],
+        };
+    }
+    if (ownership.blockers.length > 0) {
+        return {
+            ok: false,
+            issues: [`Approved file ownership is malformed: ${ownership.blockers.join('; ')}`],
+        };
+    }
+    const artifacts = await readEvidenceArtifacts({ spec, projectId, specId });
+    if (artifacts.invalidArtifacts.some((entry) => entry.startsWith('Task plan evidence'))) {
+        return {
+            ok: false,
+            issues: [
+                'Task plan evidence is invalid; regenerate task-plan.json before generating an execution plan.',
+            ],
+        };
+    }
+    const taskPlan = artifacts.taskPlan;
+    if (!taskPlan) {
+        return {
+            ok: false,
+            issues: ['No task-plan.json evidence found; cannot ground execution steps in approved work.'],
+        };
+    }
+    if (taskPlan.generatedBy === 'planu-evidence-skeleton') {
+        return {
+            ok: false,
+            issues: [
+                'task-plan.json is still the auto-generated skeleton; replace it with the real task plan before generating an execution plan.',
+            ],
+        };
+    }
+    if (taskPlan.tasks.length === 0) {
+        return { ok: false, issues: ['task-plan.json has no tasks; cannot ground execution steps.'] };
+    }
+    const invalidTaskId = invalidTaskPlanEntry(taskPlan);
+    if (invalidTaskId !== undefined) {
+        return {
+            ok: false,
+            issues: [
+                `Task plan entry "${invalidTaskId}" has an empty id, title, or acceptance-criteria list.`,
+            ],
+        };
+    }
+    const steps = taskPlan.tasks.map((task, index) => ({
+        order: index + 1,
+        title: task.title,
+        description: `Satisfy ${task.acceptanceCriteria.join(', ')} per task ${task.id}.`,
+        files: ownedFiles,
+        dependsOn: index === 0 ? [] : [index],
+        verification: ownership.toTest.length > 0
+            ? `Tests pass: ${ownership.toTest.join(', ')}`
+            : `Task ${task.id} satisfies ${task.acceptanceCriteria.join(', ')}.`,
+        estimatedMinutes: 30,
+        canRollback: true,
+    }));
+    return { ok: true, steps };
+}
+async function isPreservedForeignPlan(planPath) {
+    try {
+        const existing = await readFile(planPath, 'utf-8');
+        return !existing.startsWith(EXECUTION_PLAN_MARKER);
+    }
+    catch (error) {
+        return error.code !== 'ENOENT';
+    }
+}
 export async function handleGenerateExecutionPlan(args) {
     const { specId, projectId } = args;
     const spec = await specStore.getSpec(projectId, specId);
@@ -25,33 +120,76 @@ export async function handleGenerateExecutionPlan(args) {
     const knowledge = await knowledgeStore.getKnowledge(projectId);
     if (!knowledge) {
         return {
-            content: [{ type: 'text', text: t('project.notFound') }],
+            content: [{ type: 'text', text: ti('project.notFound', {}) }],
             isError: true,
         };
     }
     await patternStore.listPatterns(projectId);
-    const specContent = await readSpecContent(spec);
-    const phases = generatePhases(spec, knowledge, specContent);
+    const planPath = join(projectDataDir(projectId), 'handoffs', specId, 'execution-plan.md');
+    if (await isPreservedForeignPlan(planPath)) {
+        await specStore.updateSpec(projectId, specId, { planPath }).catch(() => undefined);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Execution plan preserved: an existing execution-plan.md at ${planPath} was not generated by Planu and was left unmodified.`,
+                },
+                {
+                    type: 'text',
+                    text: JSON.stringify({ planPath, planPreserved: true }, null, 2),
+                },
+            ],
+        };
+    }
+    const contract = await loadGroundedContract(spec, projectId, specId);
+    if (!contract.ok) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Execution plan generation failed closed: ${contract.issues.join(' | ')}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    const phases = generatePhases(spec, knowledge, contract.steps);
+    const graphViolations = validateExecutionPlanGraph(phases);
+    if (graphViolations.length > 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Execution plan generation failed closed: ${graphViolations.map((v) => v.message).join(' | ')}`,
+                },
+                {
+                    type: 'text',
+                    text: JSON.stringify({ violations: graphViolations }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
     const criticalPath = determineCriticalPath(phases);
     const parallelizable = findParallelizable(phases);
     const totalSteps = phases.reduce((sum, phase) => sum + phase.steps.length, 0);
     const totalMinutes = phases.reduce((sum, phase) => sum + phase.steps.reduce((s, step) => s + step.estimatedMinutes, 0), 0);
     const plan = { phases, totalSteps, criticalPath, parallelizable };
-    let planPath;
+    let writtenPlanPath;
     try {
-        planPath = join(projectDataDir(projectId), 'handoffs', specId, 'execution-plan.md');
         const planContent = generatePlanMarkdown(plan, spec);
         await atomicWriteFile(planPath, planContent, { encoding: 'utf-8' });
-        await specStore.updateSpec(projectId, specId, { planPath });
+        writtenPlanPath = planPath;
+        await specStore.updateSpec(projectId, specId, { planPath: writtenPlanPath });
         /* v8 ignore next 3 -- defensive: filesystem write failure during plan generation */
     }
     catch {
-        planPath = undefined;
+        writtenPlanPath = undefined;
     }
-    // Expose plan data as structured JSON for downstream tools that parse content[1]
     const planJson = JSON.stringify({
         ...plan,
-        planPath: planPath ?? null,
+        planPath: writtenPlanPath ?? null,
+        planPreserved: false,
         summary: {
             phases: phases.length,
             totalSteps,
@@ -77,40 +215,12 @@ export async function handleGenerateExecutionPlan(args) {
         ],
     };
 }
-// --- Phase dispatcher (OCP: add new phases here without modifying phase files) ---
-function generatePhases(spec, knowledge, specContent) {
+function generatePhases(spec, knowledge, groundedSteps) {
     const phases = [];
-    let stepOrder = 1;
-    const setupSteps = generateSetupPhase(spec, knowledge, stepOrder);
-    if (setupSteps.length > 0) {
-        phases.push({ name: 'Setup & Scaffolding', steps: setupSteps });
-        stepOrder += setupSteps.length;
-    }
-    if (spec.target === 'backend' || spec.target === 'fullstack' || spec.target === 'database') {
-        const dataSteps = generateDataLayerPhase(spec, knowledge, specContent, stepOrder);
-        if (dataSteps.length > 0) {
-            phases.push({ name: 'Data Layer', steps: dataSteps });
-            stepOrder += dataSteps.length;
-        }
-    }
-    if (spec.target !== 'frontend') {
-        const logicSteps = generateBusinessLogicPhase(spec, knowledge, specContent, stepOrder);
-        if (logicSteps.length > 0) {
-            phases.push({ name: 'Business Logic & API', steps: logicSteps });
-            stepOrder += logicSteps.length;
-        }
-    }
-    if (spec.target === 'frontend' || spec.target === 'fullstack') {
-        const uiSteps = generateUIPhase(spec, knowledge, specContent, stepOrder);
-        if (uiSteps.length > 0) {
-            phases.push({ name: 'UI Implementation', steps: uiSteps });
-            stepOrder += uiSteps.length;
-        }
+    let stepOrder = groundedSteps.length + 1;
+    if (groundedSteps.length > 0) {
+        phases.push({ name: 'Grounded Implementation', steps: groundedSteps });
     }
-    const testSteps = generateTestingPhase(spec, knowledge, stepOrder);
-    phases.push({ name: 'Testing & Verification', steps: testSteps });
-    stepOrder += testSteps.length;
-    // SPEC-013: Distribution phase for mobile release specs (iOS/Android/Flutter/RN/Expo)
     if (isMobileDistributionSpec(spec)) {
         const distSteps = generateMobileDistributionPhase(spec, stepOrder);
         if (distSteps.length > 0) {
@@ -118,16 +228,12 @@ function generatePhases(spec, knowledge, specContent) {
             stepOrder += distSteps.length;
         }
     }
-    // SPEC-014b: Distribution phase for desktop release specs
     if (knowledge.projectCategory === 'desktop' && isDesktopReleaseSpec(spec)) {
         const desktopDistSteps = generateDesktopDistributionPhase(spec, stepOrder);
         if (desktopDistSteps.length > 0) {
             phases.push({ name: 'Distribution', steps: desktopDistSteps });
-            stepOrder += desktopDistSteps.length;
         }
     }
-    const integrationSteps = generateIntegrationPhase(spec, knowledge, stepOrder);
-    phases.push({ name: 'Integration & Cleanup', steps: integrationSteps });
     return phases;
 }
 //# sourceMappingURL=generate-execution-plan.js.map

package/dist/tools/update-status/dod-gates.js

@@ -17,9 +17,10 @@ import { formatKeyValue } from '../output-formatter.js';
 import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
 import { verifyCurrentDoneReceipt } from './done-receipt-verifier.js';
 import { projectDataDir } from '../../storage/base-store.js';
-import { readTransitionLog, transitionLogPath } from '../../storage/transition-log.js';
+import { transitionLogPath } from '../../storage/transition-log.js';
 import { ImplementationReviewV1Schema, ReviewFeedbackV1Schema, ValidationReportV1Schema, } from '../../engine/handoff-artifacts/schemas.js';
 import { renderSchemaSkeleton } from '../../engine/handoff-artifacts/schema-skeleton.js';
+import { isLifecycleStubBody, readVerifiedImplementationReview, } from '../../engine/handoff-artifacts/implementation-review-reader.js';
 export { completedJobPublishesReceipt } from './done-receipt-verifier.js';
 const HANDOFF_ARTIFACT_TEMPLATE_TIMESTAMP = '2026-01-01T00:00:00.000Z';
 const HANDOFF_ARTIFACT_TEMPLATE_SCHEMA_VERSION = '1.0.0';
@@ -186,7 +187,8 @@ export async function runValidateGate(spec, projectPath, forceStatus, forceStatu
  * Returns an error ToolResult if blocked (unless force=true), null if passed.
  */
 export async function checkDodGate(spec, specId, projectId, projectPath, _force) {
-    const dod = await generateDoD(spec, undefined, undefined, projectPath);
+    const verifiedReview = await readVerifiedImplementationReview(projectId, specId);
+    const dod = await generateDoD(spec, undefined, undefined, projectPath, verifiedReview);
     const requiredItems = dod.items.filter((i) => i.required);
     const blockingItems = requiredItems
         .filter((i) => i.status === 'failed')
@@ -591,10 +593,6 @@ export async function readApprovedValidationReportGate(specId, projectId, force)
         };
     }
 }
-function isLifecycleStubBody(specId, body) {
-    return (body === `Spec ${specId} reviewed by planu-spec-reviewer and approved for approval gates.` ||
-        body === `Spec ${specId} reviewed by planu-spec-reviewer with requested changes.`);
-}
 /** SPEC-1051: Approval requires a dedicated spec reviewer artifact. */
 export async function checkSpecReviewGate(specId, projectId, _forceApprove) {
     try {
@@ -665,28 +663,36 @@ export async function checkSpecReviewGate(specId, projectId, _forceApprove) {
     }
 }
 export async function checkImplementationReviewGate(specId, projectId, _force) {
-    try {
-        const { readArtifact } = await import('../../engine/handoff-artifacts/io.js');
-        const result = await readArtifact({ projectId, specId, kind: 'implementation_review' });
-        if (!result.ok) {
-            const firstErr = result.errors[0];
+    const verified = await readVerifiedImplementationReview(projectId, specId);
+    if (verified.ok) {
+        return null;
+    }
+    switch (verified.reason) {
+        case 'missing':
+        case 'schema_invalid':
             return implementationReviewGateError({
                 specId,
-                error: firstErr?.code === 'ARTIFACT_NOT_FOUND'
+                error: verified.reason === 'missing'
                     ? 'implementation_review_missing'
                     : 'implementation_review_invalid',
-                message: firstErr?.code === 'ARTIFACT_NOT_FOUND'
+                message: verified.reason === 'missing'
                     ? 'No implementation review exists for this spec. An independent planu-implementation-reviewer must review the implementation and write its own evidence before done.'
                     : 'Implementation review evidence is malformed or uses an obsolete schema.',
-                blockers: schemaBlockers(result.errors),
-                fixHint: firstErr?.code === 'ARTIFACT_NOT_FOUND'
+                blockers: schemaBlockers(verified.errors ?? []),
+                fixHint: verified.reason === 'missing'
                     ? 'Have planu-implementation-reviewer write implementation_review.json (ImplementationReviewV1) into the handoff store, then retry update_status(done).'
                     : 'Have planu-implementation-reviewer rewrite implementation_review.json as valid ImplementationReviewV1 evidence, then retry done.',
                 template: implementationReviewTemplate(),
             });
-        }
-        const review = result.payload;
-        if (isLifecycleStubBody(specId, review.body)) {
+        case 'wrong_spec':
+            return implementationReviewGateError({
+                specId,
+                error: 'implementation_review_wrong_spec',
+                message: 'Implementation review evidence is bound to a different spec.',
+                blockers: [`Review specId was ${verified.review?.specId}. Expected ${specId}.`],
+                fixHint: 'Have planu-implementation-reviewer write review evidence bound to this spec, then retry done.',
+            });
+        case 'stub_body':
             return implementationReviewGateError({
                 specId,
                 error: 'implementation_review_stub',
@@ -694,24 +700,22 @@ export async function checkImplementationReviewGate(specId, projectId, _force) {
                 blockers: [],
                 fixHint: 'Replace the stub with genuine planu-implementation-reviewer evidence in the handoff store, then retry done.',
             });
-        }
-        if (review.verdict !== 'approved' || review.reviewer.verdict !== 'approved') {
+        case 'not_approved':
             return implementationReviewGateError({
                 specId,
                 error: 'implementation_review_changes_requested',
                 message: 'Implementation reviewer requested changes. Done is blocked until the review passes.',
-                blockers: review.blockers,
+                blockers: verified.review?.blockers ?? [],
                 fixHint: 'Resolve the implementation review blockers and have planu-implementation-reviewer write updated evidence, then retry done.',
             });
-        }
-        const implementationReviewerBlockers = [];
-        if (review.reviewer.kind !== 'implementation-review-agent') {
-            implementationReviewerBlockers.push(`reviewer.kind was ${review.reviewer.kind}. Expected implementation-review-agent.`);
-        }
-        if (review.reviewer.agent !== 'planu-implementation-reviewer') {
-            implementationReviewerBlockers.push(`reviewer.agent was ${review.reviewer.agent}. Expected planu-implementation-reviewer.`);
-        }
-        if (implementationReviewerBlockers.length > 0) {
+        case 'wrong_agent_or_kind': {
+            const implementationReviewerBlockers = [];
+            if (verified.review?.reviewer.kind !== 'implementation-review-agent') {
+                implementationReviewerBlockers.push(`reviewer.kind was ${verified.review?.reviewer.kind}. Expected implementation-review-agent.`);
+            }
+            if (verified.review?.reviewer.agent !== 'planu-implementation-reviewer') {
+                implementationReviewerBlockers.push(`reviewer.agent was ${verified.review?.reviewer.agent}. Expected planu-implementation-reviewer.`);
+            }
             return implementationReviewGateError({
                 specId,
                 error: 'implementation_review_wrong_reviewer',
@@ -720,54 +724,32 @@ export async function checkImplementationReviewGate(specId, projectId, _force) {
                 fixHint: 'Have planu-implementation-reviewer write the review artifact with reviewer.kind implementation-review-agent and reviewer.agent planu-implementation-reviewer, then retry done.',
             });
         }
-        let implementerActor;
-        try {
-            implementerActor = await findImplementingActor(specId, projectId);
-        }
-        catch (err) {
-            /* reliability-optional: TRANSITION_LOG_GATE_READ — typed gate error blocks done */
-            reportClassifiedDegradation('TRANSITION_LOG_GATE_READ', err);
+        case 'actor_unreadable':
             return implementationReviewGateError({
                 specId,
                 error: 'implementing_actor_unreadable',
-                message: `Could not read the transition log to find the implementing actor: ${err instanceof Error ? err.message : String(err)}`,
+                message: `Could not read the transition log to find the implementing actor: ${verified.readError ?? ''}`,
                 blockers: [],
                 fixHint: 'Fix the transition log so it can be read, then retry update_status(done).',
                 artifactPath: transitionLogPath(projectId),
             });
-        }
-        if (implementerActor !== undefined && implementerActor === review.reviewer.agent) {
+        case 'self_review':
             return implementationReviewGateError({
                 specId,
                 error: 'implementation_review_self_review',
                 message: 'The implementation reviewer must be a different identity from the implementer. Self-review is blocked.',
-                blockers: [`Implementer and reviewer share the identity "${implementerActor}".`],
+                blockers: [`Implementer and reviewer share the identity "${verified.implementingActor}".`],
                 fixHint: 'Have a different, independent agent write the implementation review evidence, then retry done.',
             });
-        }
-        return null;
-    }
-    catch (err) {
-        /* reliability-optional: IMPLEMENTATION_REVIEW_GATE_READ — typed gate error blocks done */
-        reportClassifiedDegradation('IMPLEMENTATION_REVIEW_GATE_READ', err);
-        return implementationReviewGateError({
-            specId,
-            error: 'implementation_review_unreadable',
-            message: `Could not read implementation review evidence: ${err instanceof Error ? err.message : String(err)}`,
-            blockers: [],
-            fixHint: 'Fix the artifact store issue so implementation_review.json is readable, then retry update_status(done).',
-        });
-    }
-}
-async function findImplementingActor(specId, projectId) {
-    const entries = await readTransitionLog(projectId, specId);
-    for (let i = entries.length - 1; i >= 0; i--) {
-        const entry = entries[i];
-        if (entry?.to === 'implementing' && entry.actor) {
-            return entry.actor;
-        }
+        case 'unreadable':
+            return implementationReviewGateError({
+                specId,
+                error: 'implementation_review_unreadable',
+                message: `Could not read implementation review evidence: ${verified.readError ?? ''}`,
+                blockers: [],
+                fixHint: 'Fix the artifact store issue so implementation_review.json is readable, then retry update_status(done).',
+            });
     }
-    return undefined;
 }
 function implementationReviewGateError(args) {
     const artifactPath = args.artifactPath ??

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

@@ -2,6 +2,10 @@ import type { SpecStatus } from '../../types/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 declare function drainPendingPostCommitWork(boundMs: number): Promise<{
+    pendingCount: number;
+    drained: boolean;
+}>;
 export interface PostCommitTask {
     name: string;
     run: (signal?: AbortSignal) => Promise<unknown>;

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

@@ -3,7 +3,48 @@ import { runCascade } from '../../engine/cascade-hooks/runner.js';
 import { appendAutopilotLogEntry } from '../../storage/autopilot-log-store.js';
 import { redactFailureMessage, reportClassifiedDegradation, } from '../../errors/classified-degradation.js';
 import { getRuntimePolicy } from '../../engine/runtime-policy.js';
+import { createExecutionScope } from '../../engine/execution/context.js';
 const queuedTransitions = new Map();
+const CASCADE_ISOLATED_SCOPE_MS = 30_000;
+const pendingPostCommitWork = new Set();
+function resolveTaskLeaseMs(task) {
+    const policy = getRuntimePolicy().postCommit;
+    const timeoutMs = task.timeoutMs ?? policy.defaultTaskTimeoutMs;
+    return Math.max(policy.minimumLeaseMs, timeoutMs * policy.leaseMultiplier);
+}
+function trackIsolatedWork(deadlineAt, fn) {
+    const scope = createExecutionScope({ deadlineAt });
+    const work = scope.run(fn).finally(() => {
+        scope.dispose();
+    });
+    pendingPostCommitWork.add(work);
+    const untrack = () => {
+        pendingPostCommitWork.delete(work);
+    };
+    work.then(untrack, untrack);
+    return work;
+}
+export async function drainPendingPostCommitWork(boundMs) {
+    const pending = [...pendingPostCommitWork];
+    if (pending.length === 0) {
+        return { pendingCount: 0, drained: true };
+    }
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            resolve('timeout');
+        }, boundMs);
+        timer.unref();
+    });
+    const outcome = await Promise.race([
+        Promise.allSettled(pending).then(() => 'settled'),
+        timeout,
+    ]);
+    if (timer !== undefined) {
+        clearTimeout(timer);
+    }
+    return { pendingCount: pending.length, drained: outcome === 'settled' };
+}
 function rememberTransition(transitionKey) {
     if (queuedTransitions.has(transitionKey)) {
         return false;
@@ -21,7 +62,7 @@ async function runBoundedPostCommitTask(args) {
     const { projectId, specId, transitionId, task } = args;
     const policy = getRuntimePolicy().postCommit;
     const timeoutMs = task.timeoutMs ?? policy.defaultTaskTimeoutMs;
-    const leaseMs = Math.max(policy.minimumLeaseMs, timeoutMs * policy.leaseMultiplier);
+    const leaseMs = resolveTaskLeaseMs(task);
     const claim = await specStore.claimPostCommitTask(projectId, specId, transitionId, task.name, {
         leaseMs,
     });
@@ -120,7 +161,7 @@ export function queuePostCommitTasks(args) {
     if (!rememberTransition(transitionKey)) {
         return [];
     }
-    void Promise.allSettled(args.tasks.map((task) => runBoundedPostCommitTask({ ...args, task }))).finally(() => {
+    void Promise.allSettled(args.tasks.map((task) => trackIsolatedWork(Date.now() + resolveTaskLeaseMs(task), () => runBoundedPostCommitTask({ ...args, task })))).finally(() => {
         queuedTransitions.delete(transitionKey);
     });
     return args.tasks.map((task) => task.name);
@@ -205,13 +246,13 @@ export function fireAndForgetSideEffects(params) {
         allSpecs,
     };
     // Launch cascade — fire-and-forget, never blocks the response
-    void (async () => {
+    void trackIsolatedWork(Date.now() + CASCADE_ISOLATED_SCOPE_MS, async () => {
         const [disabledByConfig, disabledByEnv] = await Promise.all([
             readDisabledByConfig(projectPath),
             Promise.resolve(readDisabledByEnv()),
         ]);
         await runCascade(ctx, { disabledByConfig, disabledByEnv });
-    })().catch((error) => {
+    }).catch((error) => {
         /* reliability-optional: ASYNC_CASCADE_FAILURE — post-commit task ledger captures retry state */
         reportClassifiedDegradation('ASYNC_CASCADE_FAILURE', error);
     });

package/dist/tools/validate.js

@@ -59,6 +59,7 @@ import { resolveProjectId, missingProjectIdError } from './resolve-project-id.js
 import { specStore, knowledgeStore } from '../storage/index.js';
 import { validateSpec, generateDoR, generateDoD } from '../engine/validator.js';
 import { isBlockingQualitySeverity } from '../engine/validator/dor-dod.js';
+import { readVerifiedImplementationReview } from '../engine/handoff-artifacts/implementation-review-reader.js';
 import { calcQualityScore } from '../engine/auditor-scoring.js';
 import { dispatchFeedbackEvent } from './learn.js';
 import { t, ti } from '../i18n/index.js';
@@ -350,10 +351,13 @@ export async function executeValidate(args, server, onProgress) {
     }
     const result = await runStage('spec-scan', 'validate spec implementation', () => validateSpec(executionSpec, projectPath));
     const graphCoverage = await runStage('graph', 'validate graph coverage', () => buildGraphCoverageReport({ projectId, projectPath, specId }));
-    const { dor, dod } = await runStage('definitions', 'validate ready and done definitions', async () => ({
-        dor: generateDoR(executionSpec),
-        dod: await generateDoD(executionSpec, result, undefined, projectPath),
-    }));
+    const { dor, dod } = await runStage('definitions', 'validate ready and done definitions', async () => {
+        const verifiedReview = await readVerifiedImplementationReview(projectId, specId);
+        return {
+            dor: generateDoR(executionSpec),
+            dod: await generateDoD(executionSpec, result, undefined, projectPath, verifiedReview),
+        };
+    });
     const implementationQualityScore = calcQualityScore(result.qualityIssues);
     const auditedFiles = [...new Set(result.qualityIssues.map((i) => i.file))];
     const { conventionViolations, regressionDetected } = await runStage('conventions', 'validate project conventions', () => scanProjectConventions(projectId, projectPath));

package/dist/transports/transport-factory.js

@@ -3,10 +3,12 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { execFileSync } from 'node:child_process';
 import { createHttpTransport } from './http-transport.js';
 import { compactToolsListMessage, isToolsListResponse, } from '../engine/compact/tool-list-compactor.js';
+import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 const VALID_TRANSPORTS = ['stdio', 'http'];
 const DEFAULT_PORT = 3100;
 const DEFAULT_HOST = '127.0.0.1';
 const SHUTDOWN_GRACE_MS = 100;
+const POST_COMMIT_DRAIN_MS = 1_200;
 function descendantPids(parentPid) {
     if (process.platform === 'win32') {
         return [];
@@ -114,6 +116,13 @@ function installToolsListCompaction(transport) {
     const wrappedTransport = transport;
     wrappedTransport.send = compactingSend;
 }
+async function drainPostCommitWorkOnShutdown() {
+    const { drainPendingPostCommitWork } = await import('../tools/update-status/side-effects.js');
+    const drainResult = await drainPendingPostCommitWork(POST_COMMIT_DRAIN_MS);
+    if (!drainResult.drained) {
+        reportClassifiedDegradation('POST_COMMIT_DRAIN_TIMEOUT', new Error(`Shutdown drain exceeded ${String(POST_COMMIT_DRAIN_MS)}ms with ${String(drainResult.pendingCount)} pending`));
+    }
+}
 function installStdioShutdownHandlers(server) {
     let shuttingDown = false;
     const handlers = new Map();
@@ -153,6 +162,10 @@ function installStdioShutdownHandlers(server) {
         })
             .catch(() => {
             /* shutdown remains best-effort */
+        })
+            .then(() => drainPostCommitWorkOnShutdown())
+            .catch((err) => {
+            reportClassifiedDegradation('POST_COMMIT_DRAIN_UNAVAILABLE', err);
         })
             .then(() => Promise.all([
             server.close(),

package/dist/types/cli.d.ts

@@ -17,6 +17,9 @@ export interface CliCommand {
     /** Execute the command with parsed args */
     run(args: string[], flags?: GlobalFlags): Promise<void>;
 }
+export interface CliJsonFallbackEnvelope {
+    content: unknown[];
+}
 export interface StatusCommandValues {
     set?: string;
     'project-id'?: string;

package/dist/types/evidence-gates.d.ts

@@ -20,9 +20,11 @@ export interface DiscoveryEvidence {
         meaning: string;
     }[];
 }
+export type TaskPlanGeneratedBy = 'planu-evidence-skeleton';
 export interface TaskPlanEvidence {
     version: 1;
     provenance?: ValidationArtifactProvenance;
+    generatedBy?: TaskPlanGeneratedBy;
     tasks: {
         id: string;
         title: string;

package/dist/types/execution.d.ts

@@ -26,6 +26,11 @@ export interface ExecutionStep {
     parallelizable?: boolean;
     cycle?: PlanCycle;
 }
+export type ExecutionPlanGraphViolationCode = 'SELF_DEPENDENT_STEP' | 'INVALID_STEP_DEPENDENCY' | 'CYCLIC_STEP_DEPENDENCIES';
+export interface ExecutionPlanGraphViolation {
+    code: ExecutionPlanGraphViolationCode;
+    message: string;
+}
 export interface PhaseTracker {
     currentPhase: SddPhase;
     specId: string | null;