@planu/cli 5.0.0 → 5.2.0

package/dist/tools/check-readiness.js

@@ -1,7 +1,5 @@
 // tools/check-readiness.ts — Completeness checkpoint tool (SPEC-039, SPEC-314, SPEC-716)
 import { specStore } from '../storage/index.js';
-import { checkSpecReadiness } from '../engine/readiness-checker.js';
-import { scoreSpecQuality } from '../engine/spec-quality-scorer.js';
 import { buildCheckReadinessSummary } from '../engine/human-summary.js';
 import { validateSpecFormat } from '../core/spec-validator.js';
 import { resolveProjectId } from './resolve-project-id.js';
@@ -9,6 +7,7 @@ import { resolveProjectId } from './resolve-project-id.js';
 const MAX_VISIBLE_BLOCKERS = 8;
 const MAX_VISIBLE_WARNINGS = 8;
 const MAX_VISIBLE_RECOMMENDATIONS = 5;
+const CANONICAL_CRITERIA_MISSING = 'CANONICAL_CRITERIA_MISSING';
 function formatScore(score) {
     if (score >= 90) {
         return `${score}/100 (Excellent)`;
@@ -21,6 +20,23 @@ function formatScore(score) {
     }
     return `${score}/100 (Not Ready)`;
 }
+function canonicalReadinessFailure(validationResult) {
+    const metrics = validationResult.metrics;
+    if (metrics === undefined || metrics.criteriaCount === 0) {
+        return CANONICAL_CRITERIA_MISSING;
+    }
+    return null;
+}
+function createFailClosedReport(specId, mode) {
+    return {
+        specId,
+        score: 0,
+        ready: false,
+        mode,
+        issues: { score: 0, breakdown: {}, blockers: [], warnings: [] },
+        recommendations: [],
+    };
+}
 function formatReport(report) {
     const lines = [];
     lines.push(`# Readiness Report — ${report.specId}`);
@@ -109,20 +125,15 @@ export async function handleCheckReadiness(args) {
             isError: true,
         };
     }
-    // SPEC-716: Ground yes/no decision in validateSpecFormat.
-    // The existing checkSpecReadiness call and formatReport are preserved for
-    // the rich human-readable output. validateSpecFormat drives the yes/no gate
-    // and its errors/warnings are surfaced in structuredContent.validationResult.
-    const [report, qualityReport, validationResult] = await Promise.all([
-        checkSpecReadiness(spec, mode),
-        scoreSpecQuality(spec),
-        validateSpecFormat(spec, { readinessMode: mode, skipQuality: true }),
-    ]);
+    // validateSpecFormat owns the readiness and quality evaluation so the response
+    // cannot combine separately computed evidence from different reads of spec.md.
+    const validationResult = await validateSpecFormat(spec, { readinessMode: mode });
     // SPEC-716: Ground ready flag in unified SpecValidationResult.
     // Only non-file-access errors from validateSpecFormat are surfaced in the
     // report — MISSING_FRONTMATTER due to file-not-found is best-effort since
     // the readiness checker already handles missing files gracefully.
     const vr = validationResult;
+    const report = vr.readinessReport ?? createFailClosedReport(spec.id, mode);
     const hardFormatErrors = vr.errors.filter((e) => e.code !== 'MISSING_FRONTMATTER' && !(e.code === 'READINESS_CHECK_FAILED'));
     const hardFormatMessages = hardFormatErrors.map((e) => e.message);
     const formatWarnings = vr.warnings
@@ -142,11 +153,24 @@ export async function handleCheckReadiness(args) {
     // Ground ready: only false if BOTH readiness report and format gate agree
     // (or format has hard non-file errors)
     report.ready = report.ready && hardFormatErrors.length === 0;
+    const canonicalFailure = canonicalReadinessFailure(vr);
+    if (canonicalFailure !== null) {
+        const target = mode === 'strict' ? report.issues.blockers : report.issues.warnings;
+        if (!target.includes(canonicalFailure)) {
+            target.push(canonicalFailure);
+        }
+        if (!report.recommendations.includes(`Resolve ${canonicalFailure} before implementation.`)) {
+            report.recommendations.push(`Resolve ${canonicalFailure} before implementation.`);
+        }
+        // Lenient mode is advisory, but it must not present a contradictory
+        // canonical validation result as an implementation-ready pass.
+        report.ready = false;
+    }
     // SPEC-612: recommend adding outOfScope items when none are declared
     if (spec.outOfScope === undefined || spec.outOfScope.length === 0) {
         report.recommendations.push('Add outOfScope items to the spec frontmatter to declare explicit scope boundaries (SPEC-612). This reduces scope creep during implementation.');
     }
-    const qualityScore = qualityReport.score;
+    const qualityScore = vr.qualityReport?.score;
     const formatted = formatReport(report);
     const humanSummary = buildCheckReadinessSummary(report.score, report.issues.blockers.length);
     return {
@@ -161,7 +185,7 @@ export async function handleCheckReadiness(args) {
             mode: report.mode,
             issues: report.issues,
             recommendations: report.recommendations,
-            qualityScore,
+            ...(qualityScore === undefined ? {} : { qualityScore }),
             humanSummary,
             validationResult: vr,
         },

package/dist/tools/create-spec/spec-builder.d.ts

@@ -13,4 +13,11 @@ export declare function buildSpecContext(params: CreateSpecInput): Promise<{
 export declare function buildSplitResult(splitSuggestion: ReturnType<typeof analyzeSplit>, experienceLevel: string | undefined): Record<string, unknown> | undefined;
 /** Infer meaningful tags from title and description when no tags were provided. */
 export declare function inferTagsFromContent(title: string, description: string, type?: string): string[];
+/**
+ * SPEC-1351: Recompute the next spec id from a fresh store + filesystem scan.
+ * Called once (unlocked) during prepare to pick a candidate id, and again
+ * inside the exclusive create-spec write lock immediately before persisting
+ * so the id actually written can never collide under concurrency.
+ */
+export declare function computeNextSpecId(projectPath: string, projectId: string): Promise<string>;
 //# sourceMappingURL=spec-builder.d.ts.map

package/dist/tools/create-spec/spec-builder.js

@@ -23,10 +23,13 @@ export async function buildSpecContext(params) {
     const projectId = hashProjectPath(projectPath);
     const knowledge = await knowledgeStore.getKnowledge(projectId);
     const existingSpecs = await specStore.listSpecs(projectId);
-    // Generate spec ID: combine store IDs + filesystem IDs for global max
-    const fsSpecIds = await scanFilesystemSpecIds(projectPath);
-    const allSpecs = [...existingSpecs, ...fsSpecIds.map((id) => ({ id }))];
-    const specId = generateSpecId(allSpecs);
+    // Generate spec ID: combine store IDs + filesystem IDs for global max.
+    // SPEC-1351: this snapshot read is NOT locked — under concurrency two callers
+    // can compute the same "next" id here. create-spec.ts re-derives the id via
+    // computeNextSpecId() again inside its exclusive per-project write lock right
+    // before persisting, so a stale id computed here is only ever a starting
+    // candidate, never the value that actually gets written to disk.
+    const specId = await computeNextSpecId(projectPath, projectId);
     const slug = slugify(title);
     // Check for duplicate title
     const duplicate = existingSpecs.find((s) => slugify(s.title) === slug);
@@ -209,6 +212,18 @@ function buildTags(tags, feature, _title, _description, _type) {
     const result = feature ? [...new Set([...explicitTags, slugify(feature)])] : explicitTags;
     return [...new Set(result)];
 }
+/**
+ * SPEC-1351: Recompute the next spec id from a fresh store + filesystem scan.
+ * Called once (unlocked) during prepare to pick a candidate id, and again
+ * inside the exclusive create-spec write lock immediately before persisting
+ * so the id actually written can never collide under concurrency.
+ */
+export async function computeNextSpecId(projectPath, projectId) {
+    const existingSpecs = await specStore.listSpecs(projectId);
+    const fsSpecIds = await scanFilesystemSpecIds(projectPath);
+    const allSpecs = [...existingSpecs, ...fsSpecIds.map((id) => ({ id }))];
+    return generateSpecId(allSpecs);
+}
 /* v8 ignore start -- filesystem scanning is best-effort, tested via integration */
 /** Scan filesystem for SPEC-XXX directories to find max ID globally. */
 async function scanFilesystemSpecIds(projectPath) {

package/dist/tools/create-spec.js

@@ -6,8 +6,10 @@ 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';
@@ -15,7 +17,7 @@ import { generateLeanTechnicalContent, } from '../engine/spec-format/lean-techni
 import { extractFilesFromSpecBody } from '../engine/spec-format/technical-md-populator.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 { resolveEnglishOnlySpecGate } from '../engine/spec-language/english-only.js';
 import { FallbackGenerator } from '../engine/spec-generator/index.js';
 import { analyzeProjectForSpec, getEmptyAutopilotResult, } from './create-spec/autopilot-analyzer.js';
 import { trackCost } from '../engine/cost-tracking/operation-tracker.js';
@@ -284,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) {
@@ -865,28 +880,50 @@ function validateCreateSpecEnums(input) {
 }
 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) {
-    const validation = validateEnglishOnlySpecText(`${params.title}\n\n${params.description}`);
-    if (validation.ok) {
-        return null;
-    }
+/** SPEC-1342: Terminal rejection — only reached after one translation clarification round failed. */
+function buildEnglishGateRejectionResult(gate) {
     return {
         content: [
             {
                 type: 'text',
-                text: `English-only spec gate blocked create_spec.\n\n${validation.reason ?? 'Non-English prose detected.'}\n\n` +
+                text: `English-only spec gate blocked create_spec.\n\n${gate.reason ?? 'Non-English prose detected.'}\n\n` +
                     'Rewrite the title and description in English, then call create_spec again. User-facing responses may be localized, but spec.md must be English.',
             },
         ],
         isError: true,
         structuredContent: {
             error: 'SPEC_LANGUAGE_GATE_BLOCKED',
-            detectedLanguage: validation.detectedLanguage,
-            signals: validation.signals,
+            detectedLanguage: gate.originalLanguage,
             fixHint: 'Rewrite title and description in English before creating the spec.',
         },
     };
 }
+/**
+ * SPEC-1342: Apply an already-resolved English-only gate outcome. Returns:
+ * - `{ earlyReturn: null, englishTitle?, englishDescription? }` when the caller may proceed
+ *   (input was already English, or was successfully translated).
+ * - `{ earlyReturn: ToolResult }` when the caller must return early (translation clarification
+ *   question, or terminal rejection after one failed clarification round).
+ */
+function applyEnglishOnlyGate(gate) {
+    switch (gate.action) {
+        case 'ok':
+            return { earlyReturn: null };
+        case 'translated':
+            return {
+                earlyReturn: null,
+                englishTitle: gate.englishTitle,
+                englishDescription: gate.englishDescription,
+            };
+        case 'reject':
+            return { earlyReturn: buildEnglishGateRejectionResult(gate) };
+        case 'ask':
+            return {
+                earlyReturn: interactiveResult(gate.questions ?? [], 'The spec title/description are not in English. Provide the English translation ' +
+                    '(e.g. via AskUserQuestion), then retry create_spec with clarificationAnswers.', 'universal'),
+            };
+    }
+}
 function quotePosixShellArgument(value) {
     return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
@@ -1194,15 +1231,30 @@ export async function handleCreateSpec(inputParams, server) {
         inputParams.specId) {
         return handleAgentTeamSynthesis(inputParams.specId, resolvedPath, inputParams.agentTeamFindings);
     }
-    const languageGate = checkEnglishOnlyInput(resolvedInputParams);
-    if (languageGate) {
-        return languageGate;
-    }
-    // SPEC-584: Gate check — block if pending clarification token exists and no answers provided
+    // SPEC-584: Gate check — block if pending clarification token exists and no answers provided.
+    // Runs before the English-only gate so a second call with no translation answer hits the
+    // existing well-formed "must call AskUserQuestion" mandate instead of re-asking forever.
     const gateError = await runClarificationGate(resolvedPath, 'create_spec', inputParams.clarificationAnswers);
     if (gateError) {
         return gateError;
     }
+    // SPEC-1342: English-only gate — offers a translation clarification round instead of
+    // hard-rejecting non-English title/description.
+    const languageGateResult = resolveEnglishOnlySpecGate(resolvedInputParams.title, resolvedInputParams.description, resolvedInputParams.clarificationAnswers);
+    const languageGate = applyEnglishOnlyGate(languageGateResult);
+    if (languageGate.earlyReturn) {
+        if (languageGateResult.action === 'ask') {
+            await persistClarificationToken(languageGate.earlyReturn, hashProjectPath(resolvedPath), 'create_spec');
+        }
+        return languageGate.earlyReturn;
+    }
+    if (languageGate.englishTitle !== undefined) {
+        resolvedInputParams.title = languageGate.englishTitle;
+    }
+    if (languageGate.englishDescription !== undefined) {
+        resolvedInputParams.description = languageGate.englishDescription;
+    }
+    const originalLanguage = languageGateResult.originalLanguage;
     const idempotencyKey = computeIdempotencyKey(inputParams.title, resolvedPath, inputParams.idempotencyKey);
     const cutoff = Date.now() - IDEMPOTENCY_MATCH_WINDOW_MS;
     const storeOnlyCandidate = await findStoreByIdempotencyKey(hashProjectPath(resolvedPath), idempotencyKey, cutoff);
@@ -1253,7 +1305,15 @@ export async function handleCreateSpec(inputParams, server) {
     });
     // SPEC-770: Idempotency check — return existing spec if same title+projectPath within 10 minutes
     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 {
@@ -1378,95 +1438,138 @@ export async function handleCreateSpec(inputParams, server) {
                 // 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) => {
-                    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');
-                    }
-                    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,
-                    });
-                    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,
-                        });
-                        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,
-                                projectPath: resolvedPath,
-                                postCommitTasks: SPEC_CREATED_POST_COMMIT_TASKS,
-                            },
+                    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');
+                        }
+                        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,
                         });
-                        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 });
+                        let storeCreated = false;
                         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',
+                            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,
                             });
+                            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 {
-                            // The original persistence failure remains the primary error.
+                        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, resolvedInputParams.title);
@@ -1486,6 +1589,7 @@ export async function handleCreateSpec(inputParams, server) {
                     };
                 }
                 if (criticalResult.status === 'failed') {
+                    rollbackUncommittedOperation(operationJournal, operationKey, 'create_spec critical path failed before commit');
                     return {
                         content: [{ type: 'text', text: criticalResult.warning }],
                         isError: true,
@@ -1498,12 +1602,21 @@ export async function handleCreateSpec(inputParams, server) {
                     };
                 }
                 if (!criticalResult.value.ok) {
+                    rollbackUncommittedOperation(operationJournal, operationKey, 'create_spec returned early before commit');
                     return criticalResult.value.earlyReturn;
                 }
                 if (!claimLifecycle.committed) {
                     throw new Error('create_spec critical path completed without a durable commit');
                 }
-                return finishRecoveredOperation(operationJournal, operationKey, criticalResult.value.data.committedResult);
+                const committedResult = criticalResult.value.data.committedResult;
+                // SPEC-1342: surface the original (pre-translation) language on the created spec's response.
+                if (originalLanguage && !committedResult.isError) {
+                    committedResult.structuredContent = {
+                        ...committedResult.structuredContent,
+                        originalLanguage,
+                    };
+                }
+                return finishRecoveredOperation(operationJournal, operationKey, committedResult);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -1511,9 +1624,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
     }