@planu/cli 5.3.63 → 5.3.64

package/dist/engine/handoff-artifacts/implementation-review-reader.js

@@ -0,0 +1,72 @@
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { readTransitionLog } from '../../storage/transition-log.js';
+import { readArtifact } from './io.js';
+export 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.`);
+}
+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;
+        }
+    }
+    return undefined;
+}
+export async function readVerifiedImplementationReview(projectId, specId) {
+    try {
+        const result = await readArtifact({ projectId, specId, kind: 'implementation_review' });
+        if (!result.ok) {
+            const firstErr = result.errors[0];
+            return {
+                ok: false,
+                reason: firstErr?.code === 'ARTIFACT_NOT_FOUND' ? 'missing' : 'schema_invalid',
+                errors: result.errors,
+            };
+        }
+        const review = result.payload;
+        if (review.specId !== specId) {
+            return { ok: false, reason: 'wrong_spec', review };
+        }
+        if (isLifecycleStubBody(specId, review.body)) {
+            return { ok: false, reason: 'stub_body', review };
+        }
+        if (review.verdict !== 'approved' || review.reviewer.verdict !== 'approved') {
+            return { ok: false, reason: 'not_approved', review };
+        }
+        if (review.reviewer.kind !== 'implementation-review-agent' ||
+            review.reviewer.agent !== 'planu-implementation-reviewer') {
+            return { ok: false, reason: 'wrong_agent_or_kind', review };
+        }
+        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);
+            return {
+                ok: false,
+                reason: 'actor_unreadable',
+                review,
+                readError: err instanceof Error ? err.message : String(err),
+            };
+        }
+        if (implementerActor !== undefined && implementerActor === review.reviewer.agent) {
+            return { ok: false, reason: 'self_review', review, implementingActor: implementerActor };
+        }
+        return { ok: true, review, implementingActor: implementerActor ?? null };
+    }
+    catch (err) {
+        /* reliability-optional: IMPLEMENTATION_REVIEW_GATE_READ — typed gate error blocks done */
+        reportClassifiedDegradation('IMPLEMENTATION_REVIEW_GATE_READ', err);
+        return {
+            ok: false,
+            reason: 'unreadable',
+            readError: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=implementation-review-reader.js.map

package/dist/engine/validator/dor-dod.d.ts

@@ -1,4 +1,4 @@
-import type { Spec, ValidateResult, DefinitionOfReady, DefinitionOfDone, CodeState } from '../../types/index.js';
+import type { Spec, ValidateResult, DefinitionOfReady, DefinitionOfDone, CodeState, VerifiedImplementationReviewResult } from '../../types/index.js';
 export declare function isBlockingQualitySeverity(severity: unknown): boolean;
 /**
  * Generate a Definition of Ready checklist for a spec.
@@ -7,5 +7,5 @@ export declare function generateDoR(spec: Spec): DefinitionOfReady;
 /**
  * Generate a Definition of Done checklist for a spec.
  */
-export declare function generateDoD(spec: Spec, validationResult?: ValidateResult, codeState?: CodeState, projectPath?: string): Promise<DefinitionOfDone>;
+export declare function generateDoD(spec: Spec, validationResult?: ValidateResult, codeState?: CodeState, projectPath?: string, verifiedReview?: VerifiedImplementationReviewResult): Promise<DefinitionOfDone>;
 //# sourceMappingURL=dor-dod.d.ts.map

package/dist/engine/validator/dor-dod.js

@@ -120,10 +120,11 @@ export function generateDoR(spec) {
         generatedAt: new Date().toISOString(),
     };
 }
-function buildDoDItems(spec, score, hasBlockingQualityIssues, hasTestFiles) {
+function buildDoDItems(spec, score, hasBlockingQualityIssues, hasTestFiles, verifiedReview) {
     // If spec is already marked "done", manual gates are implicitly satisfied —
     // the user explicitly transitioned the spec, which implies review/tests/docs passed.
     const isDone = spec.status === 'done';
+    const reviewApproved = isDone || verifiedReview?.ok === true;
     return [
         {
             id: 'dod-1',
@@ -157,7 +158,7 @@ function buildDoDItems(spec, score, hasBlockingQualityIssues, hasTestFiles) {
             category: 'review',
             required: true,
             autoCheck: false,
-            status: isDone ? 'passed' : 'pending',
+            status: reviewApproved ? 'passed' : 'pending',
         },
         {
             id: 'dod-5',
@@ -321,12 +322,12 @@ function gateCategory(gate) {
 /**
  * Generate a Definition of Done checklist for a spec.
  */
-export async function generateDoD(spec, validationResult, codeState, projectPath) {
+export async function generateDoD(spec, validationResult, codeState, projectPath, verifiedReview) {
     const score = validationResult?.score ?? 0;
     const hasBlockingQualityIssues = validationResult?.qualityIssues.some((issue) => isBlockingQualitySeverity(issue.severity)) ??
         false;
     const hasTestFiles = await detectTestFiles(spec, codeState);
-    const items = buildDoDItems(spec, score, hasBlockingQualityIssues, hasTestFiles);
+    const items = buildDoDItems(spec, score, hasBlockingQualityIssues, hasTestFiles, verifiedReview);
     // Override actuals check with progress.md parsing
     const actualsItem = items.find((i) => i.id === 'dod-8');
     if (actualsItem?.status === 'pending') {

package/dist/tools/challenge-spec/resilience-challenge-scenarios-a.d.ts

@@ -1,4 +1,5 @@
 import type { FailureScenario, Spec } from '../../types/index.js';
+import { type ChallengeCapabilities } from './scenarios-utils.js';
 export declare const EXTERNAL_CALL_KEYWORDS: string[];
 export declare const VALIDATION_KEYWORDS: string[];
 export declare const RATE_LIMIT_KEYWORDS: string[];
@@ -24,10 +25,7 @@ export declare function hasConcurrencySignal(spec: Spec, specContent: string): b
  * Returns true when the spec describes a distributed saga.
  */
 export declare function hasSagaSignal(spec: Spec, specContent: string): boolean;
-/**
- * Generate validation boundary challenge scenarios.
- */
-export declare function generateValidationBoundaryScenarios(spec: Spec): FailureScenario[];
+export declare function generateValidationBoundaryScenarios(spec: Spec, capabilities: ChallengeCapabilities): FailureScenario[];
 /**
  * Generate cascade failure challenge scenarios.
  */

package/dist/tools/challenge-spec/resilience-challenge-scenarios-a.js

@@ -97,11 +97,8 @@ export function hasConcurrencySignal(spec, specContent) {
 export function hasSagaSignal(spec, specContent) {
     return contentMentions(`${spec.title}\n${spec.tags.join(' ')}\n${specContent}`, SAGA_KEYWORDS);
 }
-/**
- * Generate validation boundary challenge scenarios.
- */
-export function generateValidationBoundaryScenarios(spec) {
-    return [
+export function generateValidationBoundaryScenarios(spec, capabilities) {
+    const scenarios = [
         {
             scenario: `[${spec.id}] Validation Boundary — String Fields: ` +
                 'What happens when a required string field receives: (a) empty string "", (b) null, (c) field absent from body entirely, ' +
@@ -119,7 +116,9 @@ export function generateValidationBoundaryScenarios(spec) {
             dataConsistency: 'Accepting empty strings as valid inputs leads to records with meaningless values polluting the database.',
             userExperience: 'Clear per-field error messages with the specific constraint violated improve form UX significantly.',
         },
-        {
+    ];
+    if (capabilities.numericInput) {
+        scenarios.push({
             scenario: `[${spec.id}] Validation Boundary — Numeric Fields: ` +
                 'What happens when a numeric field receives: (a) value exactly at min boundary (e.g., min=0 → test with -1, 0, 1), ' +
                 '(b) value exactly at max boundary, (c) NaN, (d) Infinity or -Infinity, ' +
@@ -132,24 +131,25 @@ export function generateValidationBoundaryScenarios(spec) {
                 'Coercion policy must be explicit: either always reject type mismatches or always coerce with documented behavior.',
             dataConsistency: 'NaN or Infinity stored in numeric columns causes silent corruption or runtime exceptions.',
             userExperience: 'Off-by-one errors in validation create confusing UX where users cannot submit valid data.',
-        },
-        {
-            scenario: `[${spec.id}] Validation Security — Injection Payloads: ` +
-                'Does the validation layer handle security-relevant strings without crashing or leaking internals? ' +
-                "Test with: SQL injection ('; DROP TABLE users; --), XSS (<script>alert(1)</script>), " +
-                'path traversal (../../etc/passwd), null bytes (\\0), template injection ({{7*7}}). ' +
-                'Validation is not the primary defense (that is parameterized queries / output encoding), ' +
-                'but it must not crash and must not expose stack traces.',
-            probability: 'medium',
-            impact: 'critical',
-            currentHandling: 'Injection payloads may cause unhandled exceptions in validation middleware, exposing internal error details.',
-            requiredHandling: 'All string inputs must be treated as untrusted. ' +
-                'Validation rejects malformed types; sanitization and parameterized queries handle injection prevention downstream. ' +
-                'Error responses must never include the rejected payload or stack trace — return sanitized field name + constraint only.',
-            dataConsistency: 'If injection payloads reach the database layer (even as errors), they can leak schema information via error messages.',
-            userExperience: 'Stack traces exposed in 400 responses are a security vulnerability — use opaque error IDs instead.',
-        },
-    ];
+        });
+    }
+    scenarios.push({
+        scenario: `[${spec.id}] Validation Security — Injection Payloads: ` +
+            'Does the validation layer handle security-relevant strings without crashing or leaking internals? ' +
+            "Test with: SQL injection ('; DROP TABLE users; --), XSS (<script>alert(1)</script>), " +
+            'path traversal (../../etc/passwd), null bytes (\\0), template injection ({{7*7}}). ' +
+            'Validation is not the primary defense (that is parameterized queries / output encoding), ' +
+            'but it must not crash and must not expose stack traces.',
+        probability: 'medium',
+        impact: 'critical',
+        currentHandling: 'Injection payloads may cause unhandled exceptions in validation middleware, exposing internal error details.',
+        requiredHandling: 'All string inputs must be treated as untrusted. ' +
+            'Validation rejects malformed types; sanitization and parameterized queries handle injection prevention downstream. ' +
+            'Error responses must never include the rejected payload or stack trace — return sanitized field name + constraint only.',
+        dataConsistency: 'If injection payloads reach the database layer (even as errors), they can leak schema information via error messages.',
+        userExperience: 'Stack traces exposed in 400 responses are a security vulnerability — use opaque error IDs instead.',
+    });
+    return scenarios;
 }
 /**
  * Generate cascade failure challenge scenarios.

package/dist/tools/challenge-spec/resilience-challenge-scenarios.js

@@ -15,7 +15,7 @@ export function generateResilienceChallengeScenarios(spec, specContent, knowledg
     const resolvedCapabilities = capabilities ?? detectChallengeCapabilities(spec, specContent);
     if (resolvedCapabilities.validation &&
         (resolvedCapabilities.userInput || resolvedCapabilities.networkApi)) {
-        scenarios.push(...generateValidationBoundaryScenarios(spec));
+        scenarios.push(...generateValidationBoundaryScenarios(spec, resolvedCapabilities));
     }
     if (resolvedCapabilities.externalService || resolvedCapabilities.payment) {
         scenarios.push(...generateCascadeFailureScenarios(spec));

package/dist/tools/challenge-spec/scenarios-failure.js

@@ -3,8 +3,7 @@ import { contentMentions, detectChallengeCapabilities } from './scenarios-utils.
 export function generateFailureScenarios(spec, content, _knowledge) {
     const scenarios = [];
     const capabilities = detectChallengeCapabilities(spec, content);
-    // Network failures
-    if (capabilities.networkApi) {
+    if (capabilities.outboundDependency) {
         scenarios.push({
             scenario: 'API endpoint becomes unreachable (network timeout)',
             probability: 'medium',

package/dist/tools/challenge-spec/scenarios-utils.d.ts

@@ -24,6 +24,9 @@ export interface ChallengeCapabilities {
     rateLimit: boolean;
     saga: boolean;
     platform: boolean;
+    outboundDependency: boolean;
+    numericInput: boolean;
+    rollout: boolean;
 }
 /** Boundary-aware, affirmative replacement for advisory substring checks. */
 export declare function contentMentions(content: string, keywords: string[]): boolean;

package/dist/tools/challenge-spec/scenarios-utils.js

@@ -87,6 +87,22 @@ const CAPABILITY_SIGNALS = {
     platform: [
         /\b(?:smart\s+contract|solidity|discord\s+bot|telegram\s+bot|iot\s+device|firmware|infrastructure\s+as\s+code|terraform|machine\s+learning\s+model)\b/i,
     ],
+    outboundDependency: [
+        /\boutbound\s+(?:http\s+)?(?:client|call|request|dependency)\b/i,
+        /\b(?:fetch(?:es|ing)?|calls?|invokes?)\b(?:\W+\w+){0,4}?\W+(?:api|endpoint|service|dependency)\b/i,
+        /\bremote\s+dependency\s+call\b/i,
+    ],
+    numericInput: [
+        /\bnumeric\s+(?:field|input|value|schema|constraint)\b/i,
+        /\b(?:integer|float|decimal)\s+field\b/i,
+        /\b(?:min|max)(?:imum)?\s+(?:value|constraint|boundary)\b/i,
+        /\bz\.number\(/i,
+    ],
+    rollout: [
+        /\b(?:canary|phased\s+rollout|gradual\s+rollout|blue-green\s+deploy(?:ment)?|rolling\s+deployment|feature\s+flag)\b/i,
+        /\broll(?:s|ed|ing)?\s+out\b(?:\W+\w+){0,4}?\W+(?:in\s+phases|gradually)\b/i,
+        /\bdeployment\s+strategy\b/i,
+    ],
 };
 const AUTHENTICATION_BARE_TOKEN_RE = /\bauth(?:entication|enticate)?\b/i;
 // A bare "auth" token next to registry/package-manager vocabulary describes a

package/dist/tools/challenge-spec-helpers.d.ts

@@ -9,7 +9,7 @@ export interface ConcurrencyAnalysisResult extends ConcurrencyAnalysis {
     suppressedCount: number;
 }
 export declare function generateConcurrencyAnalysis(_spec: Spec, content: string, _knowledge: ProjectKnowledge): ConcurrencyAnalysisResult;
-export declare function buildScalabilityAssessment(spec: Spec, knowledge: ProjectKnowledge, scenarios: FailureScenario[]): string;
+export declare function buildScalabilityAssessment(spec: Spec, knowledge: ProjectKnowledge, scenarios: FailureScenario[], hasRolloutEvidence?: boolean): string;
 export declare function calculateOverallRisk(scenarios: FailureScenario[], concurrency: ConcurrencyAnalysis): RiskLevel;
 export declare function readSpecContent(spec: Spec): Promise<string>;
 //# sourceMappingURL=challenge-spec-helpers.d.ts.map

package/dist/tools/challenge-spec-helpers.js

@@ -93,7 +93,7 @@ export function generateConcurrencyAnalysis(_spec, content, _knowledge) {
     return { hotPaths, raceConditions, sharedState, recommendations, suppressedCount };
 }
 // --- Scalability and risk ---
-export function buildScalabilityAssessment(spec, knowledge, scenarios) {
+export function buildScalabilityAssessment(spec, knowledge, scenarios, hasRolloutEvidence = false) {
     const criticalCount = scenarios.filter((s) => s.impact === 'critical').length;
     const arch = knowledge.architecture.primary;
     const parts = [];
@@ -108,7 +108,10 @@ export function buildScalabilityAssessment(spec, knowledge, scenarios) {
         parts.push('No critical scalability concerns for the current scope.');
     }
     if (spec.scope === 'architectural' || spec.scope === 'cross-module') {
-        parts.push('Cross-module scope increases blast radius. Consider phased rollout with feature flags.');
+        parts.push('Cross-module scope increases blast radius.');
+        if (hasRolloutEvidence) {
+            parts.push('Consider phased rollout with feature flags.');
+        }
     }
     return parts.join(' ');
 }

package/dist/tools/challenge-spec.js

@@ -268,7 +268,7 @@ export async function handleChallengeSpec(args, server) {
     const actionableFailureScenarios = failureScenarios.filter((scenario) => isScenarioSupportedByCapabilities(scenario, capabilities));
     const suppressedScenarioCount = failureScenarios.length - actionableFailureScenarios.length;
     // 7. Build scalability assessment from grounded scenarios only.
-    const scalabilityAssessment = buildScalabilityAssessment(spec, knowledge, actionableFailureScenarios);
+    const scalabilityAssessment = buildScalabilityAssessment(spec, knowledge, actionableFailureScenarios, capabilities.rollout);
     // 8. Calculate overall risk from grounded scenarios only.
     const overallRisk = calculateOverallRisk(actionableFailureScenarios, concurrencyAnalysis);
     // 9. Compute relevance scores and select top-3 diagnostics (SPEC-338) — retained as-is
@@ -465,7 +465,10 @@ function isScenarioSupportedByCapabilities(scenario, capabilities) {
         ],
         [/\b(?:sql|nosql|database|connection pool)\b/, capabilities.database],
         [/\b(?:event contract|event schema|message broker|kafka|rabbitmq|dlq)\b/, capabilities.events],
-        [/\b(?:api endpoint|http route|http status|network timeout)\b/, capabilities.networkApi],
+        [
+            /\b(?:api endpoint|http route|http status|network timeout)\b/,
+            capabilities.outboundDependency,
+        ],
         [/\b(?:traffic spike|load test|auto-scaling|throughput)\b/, capabilities.scale],
     ];
     return rules.every(([pattern, supported]) => !pattern.test(haystack) || supported);

package/dist/tools/create-spec.js

@@ -1335,8 +1335,26 @@ async function prepareCreateSpecCandidate(initialParams, server) {
         },
     };
 }
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function buildMissingTitleResult() {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: 'create_spec requires a non-empty title. Provide the title field and call create_spec again.',
+            },
+        ],
+        isError: true,
+        structuredContent: { error: 'MISSING_TITLE', code: 'INVALID_INPUT', field: 'title' },
+    };
+}
 // eslint-disable-next-line max-lines-per-function
 export async function handleCreateSpec(inputParams, server) {
+    if (!isNonEmptyString(inputParams.title)) {
+        return buildMissingTitleResult();
+    }
     const enumValidation = validateCreateSpecEnums(inputParams);
     if (enumValidation) {
         return enumValidation;

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