@planu/cli 4.14.1 → 5.1.1

package/dist/tools/create-spec.js

@@ -6,15 +6,17 @@ import { readTechnologySelectionContract } from '../storage/technology-selection
 import { toolResult, interactiveResult } from './response-helpers.js';
 import { readFile, stat as fsStat } from 'node:fs/promises';
 import { createHash, randomUUID } from 'node:crypto';
-import { dirname as pathDirname, isAbsolute as pathIsAbsolute, join as pathJoin, relative as pathRelative, sep as pathSeparator, } from 'node:path';
-import { buildSpecContext, buildSplitResult } from './create-spec/spec-builder.js';
+import { basename as pathBasename, dirname as pathDirname, isAbsolute as pathIsAbsolute, join as pathJoin, relative as pathRelative, sep as pathSeparator, } from 'node:path';
+import { withFileLock } from '../storage/file-mutex.js';
+import { generateBranchName } from './create-spec-helpers.js';
+import { buildSpecContext, buildSplitResult, computeNextSpecId, } from './create-spec/spec-builder.js';
 import { validateConstitution } from './create-spec/constitution-validator.js';
 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 +33,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 +189,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) {
@@ -275,6 +286,19 @@ function finishRecoveredOperation(journal, key, result) {
     }
     return entry?.result ?? result;
 }
+/**
+ * SPEC-1348: release the journal claim of an attempt that failed before commit.
+ * Rolling back marks the key re-claimable; committed entries are left untouched
+ * because recovery resolution only acts on active (intent/prepared) states.
+ */
+function rollbackUncommittedOperation(journal, key, reason) {
+    try {
+        journal.resolveRecovery('create_spec', key, { action: 'rollback', reason });
+    }
+    catch {
+        // Best-effort: the original failure remains the primary error.
+    }
+}
 function buildCommittedCreateResult(input) {
     const advisorySignals = [];
     if (input.advisoryCriteria.length > 0) {
@@ -330,9 +354,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 +738,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 +788,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 +802,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 +815,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 +902,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,21 +1213,70 @@ 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 });
+    // SPEC-1351: create_spec holds its RuntimeDatabase connection for the whole
+    // operation (idempotency journal + recovery payload). The default cap (4) is
+    // exhausted by a handful of concurrent create_spec calls in one process,
+    // which otherwise fail with RuntimeDatabaseResourceExhaustedError before any
+    // persistence work starts. Raise the ceiling for this call site only.
+    const runtimeDatabase = new RuntimeDatabase({
+        path: resolveStorageLayout().runtimeDatabase,
+        maxConnections: 16,
+    });
     const operationJournal = new OperationJournal(runtimeDatabase, createHash('sha256').update(hashProjectPath(resolvedPath)).digest('hex').slice(0, 32));
     let journalEntry;
     try {
@@ -915,6 +1307,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,299 +1395,147 @@ 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 };
+                    const { params, context, knowledge, clarificationSession, constitutionWarnings, advisoryCriteria, actionableMetrics, simplicityResult: committedSimplicity, } = prepared;
+                    const { splitSuggestion, duplicate, projectId } = context;
+                    let spec = context.spec;
+                    let specDir = context.specDir;
+                    let specPath = context.specPath;
+                    let unifiedSpec = prepared.unifiedSpec;
+                    // SPEC-1351: serialize the id re-derivation + persistence sequence
+                    // per project. The candidate id computed during (unlocked) prepare
+                    // can collide with another in-flight create_spec call; re-deriving
+                    // it here — inside the only place that ever writes spec.md for this
+                    // project — guarantees the id actually persisted is unique.
+                    return withFileLock(`create-spec:${projectId}`, async () => {
+                        let committedPlannerToken;
+                        try {
+                            const lockedSpecId = await computeNextSpecId(resolvedPath, projectId);
+                            if (lockedSpecId !== spec.id) {
+                                const newGitBranch = generateBranchName(lockedSpecId, spec.slug, spec.type);
+                                const newSpecDir = pathJoin(pathDirname(specDir), `${lockedSpecId}-${spec.slug}`);
+                                const newSpecPath = pathJoin(newSpecDir, pathBasename(specPath));
+                                unifiedSpec = unifiedSpec
+                                    .replace(`id: ${spec.id}\n`, `id: ${lockedSpecId}\n`)
+                                    .replace(`branch: ${spec.gitBranch}\n`, `branch: ${newGitBranch}\n`);
+                                spec = {
+                                    ...spec,
+                                    id: lockedSpecId,
+                                    specPath: newSpecPath,
+                                    technicalPath: newSpecPath,
+                                    gitBranch: newGitBranch,
+                                };
+                                specDir = newSpecDir;
+                                specPath = newSpecPath;
+                            }
+                            committedPlannerToken = await issuePlannerToken(resolvedPath, spec.id, params.sessionId ?? 'unknown-session', params.modelId ?? 'unknown-model', params.host ?? 'unknown-host');
                         }
-                        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;
-                    }
-                    let committedPlannerToken;
-                    try {
-                        committedPlannerToken = await issuePlannerToken(resolvedPath, spec.id, params.sessionId ?? 'unknown-session', params.modelId ?? 'unknown-model', params.host ?? 'unknown-host');
-                    }
-                    catch {
-                        // Best-effort evidence must not block durable spec creation.
-                    }
-                    const committedResult = buildCommittedCreateResult({
-                        spec,
-                        operationId: operationKey,
-                        duplicate,
-                        constitutionWarnings: constitutionCheck.warnings,
-                        clarificationSession,
-                        advisoryCriteria,
-                        actionableMetrics,
-                        splitSuggestion,
-                        experienceLevel: knowledge?.experienceLevel,
-                        contradictionHint,
-                        simplicityResult: committedSimplicity,
-                        plannerToken: committedPlannerToken,
-                    });
-                    let storeCreated = false;
-                    try {
-                        assertExecutionCanCommit(criticalSignal);
-                        operationJournal.setRecoveryPayload('create_spec', operationKey, 1, {
-                            operationVersion: 1,
-                            projectPath: resolvedPath,
-                            idempotencyKey,
-                            ownerId: idempotencyClaim.ownerId,
-                            projectId,
-                            specId: spec.id,
-                            specPath,
-                            specContentDigest: createHash('sha256').update(unifiedSpec).digest('hex'),
-                            result: committedResult,
+                        catch {
+                            // Best-effort evidence must not block durable spec creation.
+                        }
+                        const committedResult = buildCommittedCreateResult({
+                            spec,
+                            operationId: operationKey,
+                            duplicate,
+                            constitutionWarnings,
+                            clarificationSession,
+                            advisoryCriteria,
+                            actionableMetrics,
+                            splitSuggestion,
+                            experienceLevel: knowledge?.experienceLevel,
+                            contradictionHint: undefined,
+                            simplicityResult: committedSimplicity,
+                            plannerToken: committedPlannerToken,
                         });
-                        operationJournal.prepared('create_spec', operationKey);
-                        await measureStep('mkdir-specDir', () => executionMkdir(specDir, { recursive: true }));
-                        // SPEC-713: measure file write — this is the critical persistence step.
-                        assertExecutionCanCommit(criticalSignal);
-                        await measureStep('writeFile-specPath', () => atomicWriteFile(specPath, unifiedSpec, { encoding: 'utf-8' }));
-                        assertExecutionCanCommit(criticalSignal);
-                        await measureStep('specStore-createSpec', () => specStore.createSpec(projectId, spec));
-                        storeCreated = true;
-                        assertExecutionCanCommit(criticalSignal);
-                        await measureStep('commit-idempotency-evidence', () => commitIdempotencyEvidence(resolvedPath, idempotencyKey, idempotencyClaim, spec, specPath));
-                        operationJournal.commitWithOutbox('create_spec', operationKey, committedResult, {
-                            topic: 'spec.created',
-                            payload: {
-                                schemaVersion: 1,
-                                specId: spec.id,
-                                projectId,
+                        let storeCreated = false;
+                        try {
+                            assertExecutionCanCommit(criticalSignal);
+                            operationJournal.setRecoveryPayload('create_spec', operationKey, 1, {
+                                operationVersion: 1,
                                 projectPath: resolvedPath,
-                                postCommitTasks: SPEC_CREATED_POST_COMMIT_TASKS,
-                            },
-                        });
-                        claimLifecycle.committed = true;
-                        // SPEC-709/SPEC-461: unified spec.md; no progress or HTML artifacts.
-                    }
-                    catch (writeErr) {
-                        const storeRolledBack = storeCreated
-                            ? await specStore.deleteSpec(projectId, spec.id).catch(() => false)
-                            : true;
-                        if (storeRolledBack) {
-                            await cleanupExecutionArtifact(getIdempotencyEvidencePath(resolvedPath, idempotencyKey), {
-                                force: true,
+                                idempotencyKey,
+                                ownerId: idempotencyClaim.ownerId,
+                                projectId,
+                                specId: spec.id,
+                                specPath,
+                                specContentDigest: createHash('sha256').update(unifiedSpec).digest('hex'),
+                                result: committedResult,
+                            });
+                            operationJournal.prepared('create_spec', operationKey);
+                            await measureStep('mkdir-specDir', () => executionMkdir(specDir, { recursive: true }));
+                            // SPEC-713: measure file write — this is the critical persistence step.
+                            assertExecutionCanCommit(criticalSignal);
+                            await measureStep('writeFile-specPath', () => atomicWriteFile(specPath, unifiedSpec, { encoding: 'utf-8' }));
+                            assertExecutionCanCommit(criticalSignal);
+                            // SPEC-1351 (AC2): verify the write actually landed on disk
+                            // before any commit path is allowed to report persisted:true.
+                            // atomicWriteFile resolving without throwing is not sufficient
+                            // evidence under resource-exhaustion / concurrent-load
+                            // conditions that previously let the journal report success
+                            // with zero bytes ever reaching disk.
+                            const writtenStat = await fsStat(specPath).catch(() => null);
+                            if (!writtenStat || writtenStat.size === 0) {
+                                throw new Error(`create_spec failed to persist ${specPath}: file is missing or empty after write. ` +
+                                    'No spec was registered — retry create_spec.');
+                            }
+                            await measureStep('specStore-createSpec', () => specStore.createSpec(projectId, spec));
+                            storeCreated = true;
+                            assertExecutionCanCommit(criticalSignal);
+                            await measureStep('commit-idempotency-evidence', () => commitIdempotencyEvidence(resolvedPath, idempotencyKey, idempotencyClaim, spec, specPath));
+                            operationJournal.commitWithOutbox('create_spec', operationKey, committedResult, {
+                                topic: 'spec.created',
+                                payload: {
+                                    schemaVersion: 1,
+                                    specId: spec.id,
+                                    projectId,
+                                    projectPath: resolvedPath,
+                                    postCommitTasks: SPEC_CREATED_POST_COMMIT_TASKS,
+                                },
                             });
+                            claimLifecycle.committed = true;
+                            // SPEC-709/SPEC-461: unified spec.md; no progress or HTML artifacts.
+                        }
+                        catch (writeErr) {
+                            const storeRolledBack = storeCreated
+                                ? await specStore.deleteSpec(projectId, spec.id).catch(() => false)
+                                : 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',
+                                });
+                            }
+                            catch {
+                                // The original persistence failure remains the primary error.
+                            }
+                            throw writeErr;
                         }
-                        throw writeErr;
-                    }
-                    return {
-                        ok: true,
-                        data: {
-                            committedResult,
-                        },
-                    };
+                        return {
+                            ok: true,
+                            data: {
+                                committedResult,
+                            },
+                        };
+                    });
                 }); // end withTotalBudget critical path
                 // SPEC-713: Handle total budget exceeded — return clear error before 60s MCP timeout
                 if (criticalResult.timedOut) {
                     claimLifecycle.retainForInFlightWork = criticalResult.warning.includes('exceeded');
+                    if (!claimLifecycle.retainForInFlightWork) {
+                        rollbackUncommittedOperation(operationJournal, operationKey, 'create_spec timed out before commit with no in-flight work to preserve');
+                    }
                     // 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,14 +1544,28 @@ 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') {
+                    rollbackUncommittedOperation(operationJournal, operationKey, 'create_spec critical path failed before commit');
+                    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) {
+                    rollbackUncommittedOperation(operationJournal, operationKey, 'create_spec returned early before commit');
                     return criticalResult.value.earlyReturn;
                 }
                 if (!claimLifecycle.committed) {
@@ -1306,9 +1579,11 @@ export async function handleCreateSpec(inputParams, server) {
                     content: [{ type: 'text', text: ti('errors.internalError', { message }) }],
                     isError: true,
                 };
-                return claimLifecycle.committed
-                    ? finishRecoveredOperation(operationJournal, operationKey, errorResult)
-                    : errorResult;
+                if (claimLifecycle.committed) {
+                    return finishRecoveredOperation(operationJournal, operationKey, errorResult);
+                }
+                rollbackUncommittedOperation(operationJournal, operationKey, 'create_spec failed before commit');
+                return errorResult;
             }
         }); // end trackCost
     }