@planu/cli 4.14.1 → 5.0.0

package/dist/tools/create-spec.js

@@ -13,8 +13,8 @@ import { getAsyncAnalysisPath } from './create-spec/post-creation.js';
 import { extractCriteria, generateLeanSpecContent, } from '../engine/spec-format/lean-spec-generator.js';
 import { generateLeanTechnicalContent, } from '../engine/spec-format/lean-technical-generator.js';
 import { extractFilesFromSpecBody } from '../engine/spec-format/technical-md-populator.js';
-import { buildUnifiedSpecContent } from '../engine/spec-format/unified-spec-builder.js';
-import { appendImplementationContractIfMissing } from '../engine/implementation-contract/index.js';
+import { buildCanonicalUnifiedSpecContent, validateUnifiedSpecCandidate, } from '../engine/spec-format/unified-spec-builder.js';
+import { buildImplementationContractSection } from '../engine/implementation-contract/index.js';
 import { validateEnglishOnlySpecText } from '../engine/spec-language/english-only.js';
 import { FallbackGenerator } from '../engine/spec-generator/index.js';
 import { analyzeProjectForSpec, getEmptyAutopilotResult, } from './create-spec/autopilot-analyzer.js';
@@ -31,6 +31,8 @@ import { buildCriterionGroundingRecords, filterGroundedCriteria, getAdvisoryCrit
 import { checkGenericSpecOutput } from '../engine/spec-quality/generic-output-gate.js';
 import { calculateActionableSpecMetrics, shouldExposeMetric, } from '../engine/spec-metrics/actionable-metrics.js';
 import { RuntimeDatabase } from '../storage/runtime-db.js';
+import { BoundaryFailure } from '../errors/error-taxonomy.js';
+import { SpecAcFormatEnum, SpecScopeEnum, SpecTargetEnum, SpecTypeEnum } from './schemas/spec.js';
 import { SPEC_CREATED_POST_COMMIT_TASKS } from '../types/outbox-worker.js';
 import { resolveStorageLayout } from '../storage/storage-layout.js';
 import { OperationJournal, recoverOperationJournal, } from '../engine/execution/operation-journal.js';
@@ -185,8 +187,15 @@ function buildAdvisoryCompat() {
     };
 }
 /** Persist only out-of-scope items supplied explicitly by the caller. */
-function resolveOutOfScope(provided) {
-    return provided?.filter((item) => item.trim().length > 0) ?? [];
+function resolveOutOfScope(provided, source = '') {
+    const explicit = provided?.filter((item) => item.trim().length > 0) ?? [];
+    if (explicit.length > 0) {
+        return explicit;
+    }
+    const section = /(?:^|\n)##\s+Out of scope\s*\n([\s\S]*?)(?=\n##\s|$)/i.exec(source)?.[1];
+    return section
+        ? Array.from(section.matchAll(/^[-*]\s+(.+)$/gm), (match) => match[1]?.trim() ?? '').filter(Boolean)
+        : [];
 }
 /** SPEC-783: Synthesize agent team findings into unified spec.md ## Technical section. */
 async function handleAgentTeamSynthesis(specId, projectPath, findings) {
@@ -330,9 +339,12 @@ function buildCommittedCreateResult(input) {
             deprecatedAlias: 'riskWarning',
         }));
     }
-    return toolResult(`Spec ${spec.id} created and committed.`, {
+    return toolResult(`Spec ${spec.id} created and persisted.`, {
         operationId: input.operationId,
+        /** @deprecated Operation-journal durability; this is not Git evidence. */
         committed: true,
+        persisted: true,
+        gitCommitPerformed: false,
         pendingAnalysis: true,
         specId: spec.id,
         title: spec.title,
@@ -711,28 +723,27 @@ async function buildIdempotencyMatchResult(projectPath, existing) {
     };
 }
 const FRONTMATTER_ID_RE = /^id:\s*(SPEC-\d+)/m;
-const FRONTMATTER_TITLE_RE = /^title:\s*"?([^"\n]+?)"?\s*$/m;
 const FRONTMATTER_STATUS_RE = /^status:\s*(\S+)/m;
-/** SPEC-770: Scan store and filesystem for a spec with matching idempotency key within windowMs. */
-async function findByIdempotencyKey(projectPath, key, projectId, windowMs = IDEMPOTENCY_MATCH_WINDOW_MS) {
-    const cutoff = Date.now() - windowMs;
-    // Fast path: check store (always authoritative for successfully created specs)
+async function findStoreByIdempotencyKey(projectId, key, cutoff) {
     try {
         const existing = await specStore.listSpecs(projectId);
-        const match = existing.find((s) => s.idempotencyKey === key && new Date(s.createdAt).getTime() > cutoff);
-        if (match !== undefined) {
-            return match;
-        }
+        return existing.find((s) => s.idempotencyKey === key && new Date(s.createdAt).getTime() > cutoff);
     }
     catch {
-        /* best-effort */
+        return undefined;
+    }
+}
+/** SPEC-770: Scan store and filesystem for a spec with matching idempotency key within windowMs. */
+async function findByIdempotencyKey(projectPath, key, projectId, windowMs = IDEMPOTENCY_MATCH_WINDOW_MS) {
+    const cutoff = Date.now() - windowMs;
+    const storeMatch = await findStoreByIdempotencyKey(projectId, key, cutoff);
+    if (storeMatch) {
+        return storeMatch;
     }
-    // Transactional fallback: the request key stays in external project data, not spec.md.
     const evidenceMatch = await findByIdempotencyEvidence(projectPath, key, cutoff);
     if (evidenceMatch !== undefined) {
         return evidenceMatch;
     }
-    // Compatibility fallback for specs created before external evidence was introduced.
     try {
         const { glob } = await import('glob');
         const { join: joinPath } = await import('node:path');
@@ -762,7 +773,7 @@ async function findByIdempotencyKey(projectPath, key, projectId, windowMs = IDEM
     return undefined;
 }
 /** SPEC-770: Scan for recently written spec.md files (for possibleDuplicates in timeout response). */
-async function findRecentlyWrittenSpecs(projectPath, windowMs) {
+async function findRecentlyWrittenSpecs(projectPath, windowMs, requestedTitle) {
     try {
         const { glob } = await import('glob');
         const { join: joinPath } = await import('node:path');
@@ -776,9 +787,11 @@ async function findRecentlyWrittenSpecs(projectPath, windowMs) {
             }
             const content = await readFile(specFile, 'utf-8').catch(() => '');
             const idMatch = FRONTMATTER_ID_RE.exec(content);
-            const titleMatch = FRONTMATTER_TITLE_RE.exec(content);
-            if (idMatch?.[1] !== undefined) {
-                results.push({ id: idMatch[1], title: titleMatch?.[1] ?? '' });
+            const title = extractFrontmatterTitle(content);
+            if (idMatch?.[1] !== undefined &&
+                normalizeDuplicateTitle(title) !== '' &&
+                normalizeDuplicateTitle(title) === normalizeDuplicateTitle(requestedTitle)) {
+                results.push({ id: idMatch[1], title });
             }
         }
         return results;
@@ -787,6 +800,69 @@ async function findRecentlyWrittenSpecs(projectPath, windowMs) {
         return [];
     }
 }
+function extractFrontmatterTitle(content) {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content)?.[1];
+    const rawTitle = frontmatter ? /^title:\s*(.*?)\s*$/m.exec(frontmatter)?.[1] : undefined;
+    if (!rawTitle) {
+        return '';
+    }
+    if (rawTitle.startsWith('"') && rawTitle.endsWith('"')) {
+        try {
+            const parsed = JSON.parse(rawTitle);
+            return typeof parsed === 'string' ? parsed : '';
+        }
+        catch {
+            return '';
+        }
+    }
+    if (rawTitle.startsWith("'") && rawTitle.endsWith("'")) {
+        return rawTitle.slice(1, -1).replace(/''/g, "'");
+    }
+    return rawTitle;
+}
+function normalizeDuplicateTitle(value) {
+    return value
+        .normalize('NFKC')
+        .toLocaleLowerCase('en-US')
+        .replace(/[\p{P}]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+const CREATE_SPEC_ENUMS = {
+    type: SpecTypeEnum,
+    scope: SpecScopeEnum,
+    target: SpecTargetEnum,
+    acFormat: SpecAcFormatEnum,
+};
+function validateCreateSpecEnums(input) {
+    for (const [field, schema] of Object.entries(CREATE_SPEC_ENUMS)) {
+        const received = input[field];
+        if (received === undefined || schema.safeParse(received).success) {
+            continue;
+        }
+        const boundedReceived = received === null || ['string', 'number', 'boolean'].includes(typeof received)
+            ? received
+            : typeof received;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `${field} must be one of: ${schema.options.join(', ')}.`,
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'INVALID_INPUT',
+                code: 'INVALID_INPUT',
+                status: 422,
+                field,
+                received: boundedReceived,
+                allowed: schema.options,
+            },
+        };
+    }
+    return null;
+}
 const DESCRIPTION_MAX_CHARS = 10_000;
 const DESCRIPTION_EXCEED_MSG = 'Description exceeds 10000 chars. Create with a summary (<3k) and use reconcile_spec to add the rest.';
 function checkEnglishOnlyInput(params) {
@@ -811,8 +887,260 @@ function checkEnglishOnlyInput(params) {
         },
     };
 }
+function quotePosixShellArgument(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function earlyPreparation(result, clarificationProjectId) {
+    return {
+        kind: 'early',
+        result,
+        ...(clarificationProjectId ? { clarificationProjectId } : {}),
+    };
+}
+export async function resolveGroundedVerificationCommands(projectPath, testPaths) {
+    if (testPaths.length === 0) {
+        return [];
+    }
+    const packageJsonRaw = await readFile(pathJoin(projectPath, 'package.json'), 'utf8').catch(() => '');
+    if (!packageJsonRaw) {
+        return [];
+    }
+    try {
+        const manifest = JSON.parse(packageJsonRaw);
+        if (typeof manifest.packageManager !== 'string') {
+            return [];
+        }
+        const packageManager = /^(pnpm|npm|yarn|bun)@\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.exec(manifest.packageManager)?.[1];
+        if (!packageManager) {
+            return [];
+        }
+        if (typeof manifest.scripts?.test !== 'string' || manifest.scripts.test.trim() === '') {
+            return [];
+        }
+        return [`${packageManager} run test -- ${testPaths.map(quotePosixShellArgument).join(' ')}`];
+    }
+    catch {
+        return [];
+    }
+}
+async function prepareCreateSpecCandidate(initialParams, server) {
+    let params = initialParams;
+    const buildResult = await measureStep('buildSpecContext', () => buildSpecContext(params));
+    if (!buildResult.ok) {
+        return earlyPreparation({
+            content: [{ type: 'text', text: buildResult.errorMessage }],
+            isError: true,
+        });
+    }
+    const context = buildResult.context;
+    const { spec, estimation, projectId } = context;
+    const knowledge = await measureStep('loadKnowledge', () => knowledgeStore.getKnowledge(projectId));
+    const clarificationSession = params.clarificationSessionId
+        ? await knowledgeStore.getClarification(projectId, params.clarificationSessionId)
+        : null;
+    const constitutionCheck = await measureStep('validateConstitution', () => validateConstitution(projectId, spec.title, spec.tags));
+    if (constitutionCheck.blocked && constitutionCheck.errorResult) {
+        return earlyPreparation(constitutionCheck.errorResult);
+    }
+    const inlineAnalysis = await withBudget('create-spec-inline-analysis', getRuntimePolicy().createSpec.inlineAnalysisBudgetMs, (signal) => analyzeProjectForSpec(params.projectPath ?? '', params.description, spec.title, knowledge, signal));
+    const autopilot = unwrapBudget(inlineAnalysis, getEmptyAutopilotResult());
+    if (autopilot.isIdea) {
+        return earlyPreparation({
+            content: [
+                {
+                    type: 'text',
+                    text: `💡 **Idea captured**: "${params.description}"\n\nThe description is too brief for a full spec. Use \`capture_idea\` to save it to the backlog, or provide more detail (>10 words) to create a spec.`,
+                },
+            ],
+        });
+    }
+    const clarificationResult = handleClarification(server, params.description, knowledge, autopilot, params);
+    if (clarificationResult !== null) {
+        if ('earlyReturn' in clarificationResult) {
+            return earlyPreparation(clarificationResult.earlyReturn, projectId);
+        }
+        params = clarificationResult.params;
+    }
+    const filteredCriteria = filterGroundedCriteria(autopilot.suggestedCriteria);
+    const technologyContract = await readTechnologySelectionContract(params.projectPath ?? '');
+    const contractNote = technologyContract
+        ? [
+            '',
+            'Technology Contract:',
+            `- Mode: ${technologyContract.mode}`,
+            technologyContract.language ? `- Language: ${technologyContract.language}` : '',
+            technologyContract.framework
+                ? `- Framework: ${technologyContract.framework}`
+                : '- Framework: none or not selected',
+            technologyContract.platform ? `- Platform: ${technologyContract.platform}` : '',
+            technologyContract.projectType ? `- Project type: ${technologyContract.projectType}` : '',
+            '- Agents must not choose a different stack unless the user approves a new contract.',
+        ]
+            .filter(Boolean)
+            .join('\n')
+        : '';
+    const generatedSpec = await measureStep('generateSpecBody', () => new FallbackGenerator().generate({
+        title: spec.title,
+        description: `${params.description}${contractNote}`,
+        type: spec.type,
+        scope: spec.scope,
+        target: spec.target,
+        acFormat: params.acFormat,
+        projectContext: {
+            language: technologyContract?.language ?? knowledge?.language ?? undefined,
+            framework: technologyContract?.framework ?? knowledge?.framework ?? undefined,
+            architecture: knowledge?.architecture.primary ?? undefined,
+        },
+    }));
+    spec.generation = generatedSpec.generation;
+    spec.qualityWarnings =
+        generatedSpec.qualityWarnings.length > 0 ? generatedSpec.qualityWarnings : undefined;
+    const baseCriteria = extractCriteria(generatedSpec.specBody).map((criterion) => criterion.text);
+    const groundingCriteria = buildCriterionGroundingRecords({
+        criteria: [...baseCriteria, ...filteredCriteria],
+        userInput: params.description,
+        generatedEvidence: [generatedSpec.generation.modelId ?? generatedSpec.generation.method],
+    });
+    const contractCriteria = getContractCriteria(groundingCriteria);
+    const advisoryCriteria = getAdvisoryCriteria(groundingCriteria).map((record) => record.text);
+    if (contractCriteria.length === 0) {
+        return earlyPreparation({
+            content: [
+                {
+                    type: 'text',
+                    text: 'create_spec did not persist a spec because no acceptance criterion was grounded in the user request. ' +
+                        'Needs decision: provide at least one explicit, verifiable criterion as a checkbox or Given/When/Then outcome.',
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'MISSING_GROUNDED_ACCEPTANCE_CRITERIA',
+                missingDecision: 'Provide at least one explicit, verifiable acceptance criterion.',
+                persisted: false,
+            },
+        });
+    }
+    const actionableMetrics = calculateActionableSpecMetrics({
+        criteria: [...baseCriteria, ...filteredCriteria],
+        groundingRecords: groundingCriteria,
+    }).filter(shouldExposeMetric);
+    const technicalFiles = await measureStep('resolveTechnicalFiles', () => resolveTechnicalFiles({
+        generatedSpecBody: generatedSpec.specBody,
+        generatedTechnicalSection: generatedSpec.technicalSection,
+        projectPath: params.projectPath ?? '',
+    }));
+    const groundedTechnical = await measureStep('groundTechnicalFiles', () => groundTechnicalFiles({
+        files: technicalFiles,
+        projectPath: params.projectPath ?? '',
+        userInput: params.description,
+        autopilot,
+    }));
+    const outOfScope = resolveOutOfScope(params.outOfScope, params.description);
+    const scenarioTestPaths = groundedTechnical.files.test.map((file) => file.path);
+    const criteria = contractCriteria.map((record) => ({ text: record.text, done: false }));
+    const leanSpec = generateLeanSpecContent({
+        spec,
+        description: generatedSpec.specBody,
+        estimation,
+        criteriaOverride: criteria,
+        groundingCriteria: contractCriteria,
+        groundingTechnicalReferences: groundedTechnical.records,
+        acFormat: params.acFormat,
+        scenarioTestPaths,
+    });
+    const leanTechnical = generateLeanTechnicalContent({
+        specId: spec.id,
+        filesToCreate: groundedTechnical.files.create,
+        filesToModify: groundedTechnical.files.modify,
+        filesToTest: groundedTechnical.files.test,
+        includeDecisionRequiredPlaceholder: spec.scope !== 'trivial',
+    });
+    const verificationCommands = await resolveGroundedVerificationCommands(params.projectPath ?? '', scenarioTestPaths);
+    const implementationContract = buildImplementationContractSection({
+        description: generatedSpec.specBody,
+        criteria,
+        files: groundedTechnical.files,
+        outOfScope,
+        verificationCommands,
+    });
+    const unifiedSpec = buildCanonicalUnifiedSpecContent({
+        leanSpecBody: leanSpec,
+        sourceDescription: params.description,
+        technicalBody: leanTechnical,
+        implementationContract,
+        criteria,
+        files: groundedTechnical.files,
+        outOfScope,
+    });
+    const candidateValidation = validateUnifiedSpecCandidate(unifiedSpec, {
+        groundedFilePaths: groundedTechnical.records.map((record) => record.path),
+    });
+    if (!candidateValidation.valid) {
+        return earlyPreparation({
+            content: [
+                {
+                    type: 'text',
+                    text: `Unified spec candidate is invalid: ${candidateValidation.issues
+                        .slice(0, 3)
+                        .map((issue) => issue.message)
+                        .join('; ')}`,
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'SPEC_FORMAT_INVALID',
+                code: 422,
+                persisted: false,
+                issues: candidateValidation.issues,
+            },
+        });
+    }
+    const genericOutputGate = checkGenericSpecOutput(unifiedSpec);
+    if (!genericOutputGate.passed) {
+        return earlyPreparation({
+            content: [
+                {
+                    type: 'text',
+                    text: 'Spec quality gate blocked generic output before persistence. ' +
+                        genericOutputGate.issues
+                            .slice(0, 3)
+                            .map((issue) => `${issue.phrase}: ${issue.reason}`)
+                            .join('; '),
+                },
+            ],
+            isError: true,
+            structuredContent: {
+                error: 'GENERIC_SPEC_OUTPUT_BLOCKED',
+                sddConstitutionRuleId: 'sdd.no-generic-output',
+                issues: genericOutputGate.issues,
+                fixHint: 'Replace generic criteria or placeholder references with grounded, testable behavior.',
+            },
+        });
+    }
+    if (outOfScope.length > 0) {
+        spec.outOfScope = outOfScope;
+    }
+    return {
+        kind: 'ready',
+        prepared: {
+            params,
+            context,
+            knowledge,
+            clarificationSession,
+            constitutionWarnings: constitutionCheck.warnings,
+            advisoryCriteria,
+            actionableMetrics,
+            unifiedSpec,
+            simplicityResult: runSimplicityCheck([params.description, ...filteredCriteria].join('\n'), estimation.devHours),
+        },
+    };
+}
 // eslint-disable-next-line max-lines-per-function
 export async function handleCreateSpec(inputParams, server) {
+    const enumValidation = validateCreateSpecEnums(inputParams);
+    if (enumValidation) {
+        return enumValidation;
+    }
     if (inputParams.idempotencyKey !== undefined &&
         !/^[A-Za-z0-9._:-]{8,128}$/.test(inputParams.idempotencyKey)) {
         return {
@@ -870,19 +1198,60 @@ export async function handleCreateSpec(inputParams, server) {
     if (languageGate) {
         return languageGate;
     }
+    // SPEC-584: Gate check — block if pending clarification token exists and no answers provided
+    const gateError = await runClarificationGate(resolvedPath, 'create_spec', inputParams.clarificationAnswers);
+    if (gateError) {
+        return gateError;
+    }
+    const idempotencyKey = computeIdempotencyKey(inputParams.title, resolvedPath, inputParams.idempotencyKey);
+    const cutoff = Date.now() - IDEMPOTENCY_MATCH_WINDOW_MS;
+    const storeOnlyCandidate = await findStoreByIdempotencyKey(hashProjectPath(resolvedPath), idempotencyKey, cutoff);
+    let preparation;
+    try {
+        preparation = await prepareCreateSpecCandidate(resolvedInputParams, server);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: ti('errors.internalError', { message }) }],
+            isError: true,
+        };
+    }
+    if (preparation.kind === 'early') {
+        if (preparation.clarificationProjectId) {
+            await persistClarificationToken(preparation.result, preparation.clarificationProjectId, 'create_spec');
+        }
+        return preparation.result;
+    }
+    const prepared = preparation.prepared;
+    prepared.context.spec.idempotencyKey = idempotencyKey;
+    if (storeOnlyCandidate) {
+        const committedEvidence = await findByIdempotencyEvidence(resolvedPath, idempotencyKey, cutoff);
+        if (!committedEvidence) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `A partial create_spec transaction exists for ${storeOnlyCandidate.id}: the store row has no committed idempotency evidence. Recovery is required before retrying.`,
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'PARTIAL_IDEMPOTENCY_STATE',
+                    code: 409,
+                    persisted: false,
+                    specId: storeOnlyCandidate.id,
+                },
+            };
+        }
+    }
     // SPEC-665: Fire-and-forget TTL refresh for conventions.json (never blocks create_spec)
     void import('../engine/conventions-ttl.js').then(({ triggerConventionsTtlRefresh }) => {
         void triggerConventionsTtlRefresh(resolvedPath).catch(() => {
             /* best-effort */
         });
     });
-    // SPEC-584: Gate check — block if pending clarification token exists and no answers provided
-    const gateError = await runClarificationGate(resolvedPath, 'create_spec', inputParams.clarificationAnswers);
-    if (gateError) {
-        return gateError;
-    }
     // SPEC-770: Idempotency check — return existing spec if same title+projectPath within 10 minutes
-    const idempotencyKey = computeIdempotencyKey(inputParams.title, resolvedPath, inputParams.idempotencyKey);
     const operationKey = computeOperationKey(resolvedInputParams, resolvedPath, idempotencyKey);
     const runtimeDatabase = new RuntimeDatabase({ path: resolveStorageLayout().runtimeDatabase });
     const operationJournal = new OperationJournal(runtimeDatabase, createHash('sha256').update(hashProjectPath(resolvedPath)).digest('hex').slice(0, 32));
@@ -915,6 +1284,25 @@ export async function handleCreateSpec(inputParams, server) {
     }
     catch (error) {
         runtimeDatabase.close();
+        if (error instanceof BoundaryFailure &&
+            error.kind === 'Conflict' &&
+            error.operation === 'operation begin') {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'The idempotency key is already bound to a different create_spec request.',
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'IDEMPOTENCY_CONFLICT',
+                    code: 'IDEMPOTENCY_CONFLICT',
+                    status: 409,
+                    persisted: false,
+                },
+            };
+        }
         throw error;
     }
     if ((journalEntry.state === 'committed' || journalEntry.state === 'acknowledged') &&
@@ -984,216 +1372,14 @@ export async function handleCreateSpec(inputParams, server) {
             idempotencyKey,
             ownerId: idempotencyClaim.ownerId,
         });
-        // eslint-disable-next-line max-lines-per-function -- cohesive transactional create boundary
         return await trackCost(resolvedInputParams.projectPath ?? '', 'create_spec', async () => {
-            // Allow internal re-enrichment without mutating function parameter
-            let params = resolvedInputParams;
-            const { description, clarificationSessionId } = params;
             try {
                 // SPEC-713: Phase 1 — Critical path: build + persist spec within 25s hard ceiling.
                 // Only the steps required to produce spec.md on disk are inside this budget.
                 // Durable post-commit work is delegated to the spec.created outbox consumer.
                 const criticalResult = await withTotalBudget('create_spec-critical', getRuntimePolicy().createSpec.criticalTimeoutMs, async (criticalSignal) => {
-                    // Build spec context (ID, estimation, diagrams, scope filters)
-                    const buildResult = await measureStep('buildSpecContext', () => buildSpecContext(params));
-                    if (!buildResult.ok) {
-                        return {
-                            ok: false,
-                            earlyReturn: {
-                                content: [{ type: 'text', text: buildResult.errorMessage }],
-                                isError: true,
-                            },
-                        };
-                    }
-                    const { spec, specDir, specPath, estimation, splitSuggestion, duplicate, projectId } = buildResult.context;
-                    // Kept in external store/evidence for retries; the value-only serializer omits it.
-                    spec.idempotencyKey = idempotencyKey;
-                    // Load project knowledge and clarification session
-                    const knowledge = await measureStep('loadKnowledge', () => knowledgeStore.getKnowledge(projectId));
-                    const clarificationSession = clarificationSessionId
-                        ? await knowledgeStore.getClarification(projectId, clarificationSessionId)
-                        : null;
-                    // Validate against Constitution
-                    const constitutionCheck = await measureStep('validateConstitution', () => validateConstitution(projectId, spec.title, spec.tags));
-                    if (constitutionCheck.blocked && constitutionCheck.errorResult) {
-                        return { ok: false, earlyReturn: constitutionCheck.errorResult };
-                    }
-                    // Full project-wide analysis is delivered by the durable spec.created outbox consumer.
-                    // A tiny inline budget preserves deterministic idea/clarification behavior when the
-                    // answer is immediately available without allowing repository scans to delay ACK.
-                    const inlineAnalysis = await withBudget('create-spec-inline-analysis', getRuntimePolicy().createSpec.inlineAnalysisBudgetMs, (signal) => analyzeProjectForSpec(params.projectPath ?? '', description, spec.title, knowledge, signal));
-                    const autopilot = unwrapBudget(inlineAnalysis, getEmptyAutopilotResult());
-                    // If very vague (<10 words), capture as idea instead of spec
-                    if (autopilot.isIdea) {
-                        return {
-                            ok: false,
-                            earlyReturn: {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: `💡 **Idea captured**: "${description}"\n\nThe description is too brief for a full spec. Use \`capture_idea\` to save it to the backlog, or provide more detail (>10 words) to create a spec.`,
-                                    },
-                                ],
-                            },
-                        };
-                    }
-                    // SPEC-463 / SPEC-471: Interactive clarification
-                    const clarificationResult = handleClarification(server, description, knowledge, autopilot, params);
-                    if (clarificationResult !== null) {
-                        if ('earlyReturn' in clarificationResult) {
-                            // SPEC-584: Persist token so the gate blocks retries without answers
-                            await persistClarificationToken(clarificationResult.earlyReturn, projectId, 'create_spec');
-                            return { ok: false, earlyReturn: clarificationResult.earlyReturn };
-                        }
-                        params = clarificationResult.params;
-                    }
-                    const filteredCriteria = filterGroundedCriteria(autopilot.suggestedCriteria);
-                    const technologyContract = await readTechnologySelectionContract(params.projectPath ?? '');
-                    const contractNote = technologyContract
-                        ? [
-                            '',
-                            'Technology Contract:',
-                            `- Mode: ${technologyContract.mode}`,
-                            technologyContract.language ? `- Language: ${technologyContract.language}` : '',
-                            technologyContract.framework
-                                ? `- Framework: ${technologyContract.framework}`
-                                : '- Framework: none or not selected',
-                            technologyContract.platform ? `- Platform: ${technologyContract.platform}` : '',
-                            technologyContract.projectType
-                                ? `- Project type: ${technologyContract.projectType}`
-                                : '',
-                            '- Agents must not choose a different stack unless the user approves a new contract.',
-                        ]
-                            .filter(Boolean)
-                            .join('\n')
-                        : '';
-                    const specGenerator = new FallbackGenerator();
-                    const generatedSpec = await measureStep('generateSpecBody', () => specGenerator.generate({
-                        title: spec.title,
-                        description: `${description}${contractNote}`,
-                        type: spec.type,
-                        scope: spec.scope,
-                        target: spec.target,
-                        acFormat: params.acFormat,
-                        projectContext: {
-                            language: technologyContract?.language ?? knowledge?.language ?? undefined,
-                            framework: technologyContract?.framework ?? knowledge?.framework ?? undefined,
-                            architecture: knowledge?.architecture.primary ?? undefined,
-                        },
-                    }));
-                    spec.generation = generatedSpec.generation;
-                    spec.qualityWarnings =
-                        generatedSpec.qualityWarnings.length > 0 ? generatedSpec.qualityWarnings : undefined;
-                    const baseCriteria = extractCriteria(generatedSpec.specBody).map((criterion) => criterion.text);
-                    const groundingCriteria = buildCriterionGroundingRecords({
-                        criteria: [...baseCriteria, ...filteredCriteria],
-                        userInput: description,
-                        generatedEvidence: [
-                            generatedSpec.generation.modelId ?? generatedSpec.generation.method,
-                        ],
-                    });
-                    const contractCriteria = getContractCriteria(groundingCriteria);
-                    const advisoryCriteria = getAdvisoryCriteria(groundingCriteria).map((record) => record.text);
-                    if (contractCriteria.length === 0) {
-                        return {
-                            ok: false,
-                            earlyReturn: {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: 'create_spec did not persist a spec because no acceptance criterion was grounded in the user request. ' +
-                                            'Needs decision: provide at least one explicit, verifiable criterion as a checkbox or Given/When/Then outcome.',
-                                    },
-                                ],
-                                isError: true,
-                                structuredContent: {
-                                    error: 'MISSING_GROUNDED_ACCEPTANCE_CRITERIA',
-                                    missingDecision: 'Provide at least one explicit, verifiable acceptance criterion.',
-                                    persisted: false,
-                                },
-                            },
-                        };
-                    }
-                    const actionableMetrics = calculateActionableSpecMetrics({
-                        criteria: [...baseCriteria, ...filteredCriteria],
-                        groundingRecords: groundingCriteria,
-                    }).filter(shouldExposeMetric);
-                    const technicalFiles = await measureStep('resolveTechnicalFiles', () => resolveTechnicalFiles({
-                        generatedSpecBody: generatedSpec.specBody,
-                        generatedTechnicalSection: generatedSpec.technicalSection,
-                        projectPath: params.projectPath ?? '',
-                    }));
-                    const groundedTechnical = await measureStep('groundTechnicalFiles', () => groundTechnicalFiles({
-                        files: technicalFiles,
-                        projectPath: params.projectPath ?? '',
-                        userInput: description,
-                        autopilot,
-                    }));
-                    const outOfScope = resolveOutOfScope(params.outOfScope);
-                    const scenarioTestPaths = groundedTechnical.files.test.map((file) => file.path);
-                    const leanSpec = generateLeanSpecContent({
-                        spec,
-                        description: generatedSpec.specBody,
-                        estimation,
-                        criteriaOverride: contractCriteria.map((record) => ({
-                            text: record.text,
-                            done: false,
-                        })),
-                        groundingCriteria: contractCriteria,
-                        groundingTechnicalReferences: groundedTechnical.records,
-                        acFormat: params.acFormat,
-                        scenarioTestPaths,
-                    });
-                    const leanTechnical = generateLeanTechnicalContent({
-                        specId: spec.id,
-                        filesToCreate: groundedTechnical.files.create,
-                        filesToModify: groundedTechnical.files.modify,
-                        filesToTest: groundedTechnical.files.test,
-                        includeDecisionRequiredPlaceholder: spec.scope !== 'trivial',
-                    });
-                    // SPEC-709: write unified spec.md from origin — no separate technical.md.
-                    // The legacy two-file output is preserved by appending the technical body
-                    // as a `## Technical` section inside spec.md.
-                    const unifiedWithoutContract = buildUnifiedSpecContent(leanSpec, leanTechnical);
-                    const unifiedSpec = appendImplementationContractIfMissing(unifiedWithoutContract, {
-                        description: generatedSpec.specBody,
-                        criteria: contractCriteria.map((record) => ({ text: record.text, done: false })),
-                        files: groundedTechnical.files,
-                        outOfScope,
-                        verificationCommands: [],
-                    });
-                    const genericOutputGate = checkGenericSpecOutput(unifiedSpec);
-                    if (!genericOutputGate.passed) {
-                        return {
-                            ok: false,
-                            earlyReturn: {
-                                content: [
-                                    {
-                                        type: 'text',
-                                        text: 'Spec quality gate blocked generic output before persistence. ' +
-                                            genericOutputGate.issues
-                                                .slice(0, 3)
-                                                .map((issue) => `${issue.phrase}: ${issue.reason}`)
-                                                .join('; '),
-                                    },
-                                ],
-                                isError: true,
-                                structuredContent: {
-                                    error: 'GENERIC_SPEC_OUTPUT_BLOCKED',
-                                    sddConstitutionRuleId: 'sdd.no-generic-output',
-                                    issues: genericOutputGate.issues,
-                                    fixHint: 'Replace generic criteria or placeholder references with grounded, testable behavior.',
-                                },
-                            },
-                        };
-                    }
-                    // Contradiction analysis is durable post-commit work. Its synchronous scanners can
-                    // block the event loop, so it must never run on the persistence acknowledgement path.
-                    const contradictionHint = undefined;
-                    const committedSimplicity = runSimplicityCheck([params.description, ...filteredCriteria].join('\n'), estimation.devHours);
-                    if (outOfScope.length > 0) {
-                        spec.outOfScope = outOfScope;
-                    }
+                    const { params, context, knowledge, clarificationSession, constitutionWarnings, advisoryCriteria, actionableMetrics, unifiedSpec, simplicityResult: committedSimplicity, } = prepared;
+                    const { spec, specDir, specPath, splitSuggestion, duplicate, projectId } = context;
                     let committedPlannerToken;
                     try {
                         committedPlannerToken = await issuePlannerToken(resolvedPath, spec.id, params.sessionId ?? 'unknown-session', params.modelId ?? 'unknown-model', params.host ?? 'unknown-host');
@@ -1205,13 +1391,13 @@ export async function handleCreateSpec(inputParams, server) {
                         spec,
                         operationId: operationKey,
                         duplicate,
-                        constitutionWarnings: constitutionCheck.warnings,
+                        constitutionWarnings,
                         clarificationSession,
                         advisoryCriteria,
                         actionableMetrics,
                         splitSuggestion,
                         experienceLevel: knowledge?.experienceLevel,
-                        contradictionHint,
+                        contradictionHint: undefined,
                         simplicityResult: committedSimplicity,
                         plannerToken: committedPlannerToken,
                     });
@@ -1256,11 +1442,18 @@ export async function handleCreateSpec(inputParams, server) {
                         const storeRolledBack = storeCreated
                             ? await specStore.deleteSpec(projectId, spec.id).catch(() => false)
                             : true;
-                        if (storeRolledBack) {
-                            await cleanupExecutionArtifact(getIdempotencyEvidencePath(resolvedPath, idempotencyKey), {
-                                force: true,
+                        await cleanupExecutionArtifact(getIdempotencyEvidencePath(resolvedPath, idempotencyKey), { force: true });
+                        await cleanupExecutionArtifact(specDir, { recursive: true, force: true });
+                        try {
+                            operationJournal.resolveRecovery('create_spec', operationKey, {
+                                action: storeRolledBack ? 'rollback' : 'quarantine',
+                                reason: storeRolledBack
+                                    ? 'create_spec persistence failed and compensating cleanup completed'
+                                    : 'create_spec persistence failed and the spec store rollback was incomplete',
                             });
-                            await cleanupExecutionArtifact(specDir, { recursive: true, force: true });
+                        }
+                        catch {
+                            // The original persistence failure remains the primary error.
                         }
                         throw writeErr;
                     }
@@ -1276,7 +1469,7 @@ export async function handleCreateSpec(inputParams, server) {
                     claimLifecycle.retainForInFlightWork = criticalResult.warning.includes('exceeded');
                     // SPEC-770: Wait briefly for any in-flight spec write to complete, then scan for duplicates
                     await new Promise((resolve) => setTimeout(resolve, 500));
-                    const recentSpecs = await findRecentlyWrittenSpecs(resolvedPath, 2 * 60 * 1000);
+                    const recentSpecs = await findRecentlyWrittenSpecs(resolvedPath, 2 * 60 * 1000, resolvedInputParams.title);
                     const possibleDuplicates = recentSpecs.length > 0 ? recentSpecs : undefined;
                     const dupNote = possibleDuplicates
                         ? `\n\nA spec may have been created server-side: ${possibleDuplicates.map((s) => s.id).join(', ')}. Retry with the same title to return it instead of creating a duplicate.`
@@ -1285,13 +1478,25 @@ export async function handleCreateSpec(inputParams, server) {
                         content: [
                             {
                                 type: 'text',
-                                text: `❌ create_spec exceeded 25s internal budget.\n\n${criticalResult.warning}${dupNote}`,
+                                text: `❌ create_spec exceeded its ${String(criticalResult.ceilingMs)}ms internal budget.\n\n${criticalResult.warning}${dupNote}`,
                             },
                         ],
                         isError: true,
                         ...(possibleDuplicates ? { structuredContent: { possibleDuplicates } } : {}),
                     };
                 }
+                if (criticalResult.status === 'failed') {
+                    return {
+                        content: [{ type: 'text', text: criticalResult.warning }],
+                        isError: true,
+                        structuredContent: {
+                            error: 'OPERATION_FAILED',
+                            category: criticalResult.category,
+                            elapsedMs: criticalResult.elapsedMs,
+                            persisted: false,
+                        },
+                    };
+                }
                 if (!criticalResult.value.ok) {
                     return criticalResult.value.earlyReturn;
                 }