@planu/cli 5.0.0 → 5.1.1

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';
@@ -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) {
@@ -1253,7 +1268,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 +1401,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 +1552,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,6 +1565,7 @@ 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) {
@@ -1511,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
     }

package/dist/tools/register-spec-tools/core-spec-tools.js

@@ -359,18 +359,18 @@ export function registerCoreSpecTools(server) {
                 .describe('Set true when implementation drift requires reconcile_spec before status=done; true blocks done.'),
             actuals: z
                 .object({
-                devHours: z.number().min(0),
-                reviewHours: z.number().min(0),
-                tokensOpus: z.number().min(0),
-                tokensSonnet: z.number().min(0),
-                apiCostUsd: z.number().min(0),
-                humanCostUsd: z.number().min(0),
-                totalCostUsd: z.number().min(0),
-                completedAt: z.string().max(500),
-                notes: z.string().max(10_000),
+                devHours: z.number().min(0).optional(),
+                reviewHours: z.number().min(0).optional(),
+                tokensOpus: z.number().min(0).optional(),
+                tokensSonnet: z.number().min(0).optional(),
+                apiCostUsd: z.number().min(0).optional(),
+                humanCostUsd: z.number().min(0).optional(),
+                totalCostUsd: z.number().min(0).optional(),
+                completedAt: z.string().max(500).optional(),
+                notes: z.string().max(10_000).optional(),
             })
                 .optional()
-                .describe('Actual metrics (required when status = done)'),
+                .describe('Actual metrics for status = done. All fields optional (SPEC-1356): missing numeric fields default to 0, completedAt/notes are auto-filled when omitted.'),
             reviewNotes: z
                 .string()
                 .max(10_000)
@@ -407,7 +407,8 @@ export function registerCoreSpecTools(server) {
             implementationReviewDigest: z
                 .string()
                 .regex(/^sha256:[a-f0-9]{64}$/u)
-                .optional(),
+                .optional()
+                .describe('SHA-256 of the exact validation-report.json bytes. Required implementation evidence for status=done; for status=review it is valid only inside the complete trusted local-MCP reconciliation tuple.'),
             forceApprove: z
                 .boolean()
                 .optional()
@@ -424,7 +425,7 @@ export function registerCoreSpecTools(server) {
                 .max(4096)
                 .optional()
                 .describe('Absolute project root. Preferred when projectId is unknown.'),
-            status: SpecStatusEnum.describe('New status for all specs'),
+            status: SpecStatusEnum.exclude(['done']).describe('New status for all specs. Batch supports draft, review, approved, implementing, and discarded; close done specs individually with full evidence.'),
             dryRun: z.boolean().optional().describe('Preview the batch without mutating any spec.'),
             reviewNotes: z
                 .string()

package/dist/tools/sync-spec-state-handler.js

@@ -12,7 +12,7 @@ import { parseFrontmatter } from '../engine/frontmatter-parser.js';
 import { verifyTerminalFrontmatter } from '../engine/frontmatter-sha/index.js';
 import { appendTransitionEvent } from '../storage/transition-log.js';
 import { cleanEphemeralArtifacts } from '../engine/housekeeping/index.js';
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 // ---------------------------------------------------------------------------
 // Sync helpers (exported for startup use)
 // ---------------------------------------------------------------------------
@@ -33,9 +33,15 @@ export async function syncSpecState(projectPath, projectId) {
             divergences: [],
             errors: [`Failed to load specs for ${projectId}: ${msg}`],
             rejected: [],
+            ghosts: [],
         };
     }
+    // SPEC-1351 (AC3): quarantine store entries whose spec.md is missing on
+    // disk — ghost registrations left behind by a create_spec attempt that
+    // reported success but never persisted (or whose file was later deleted).
+    const ghosts = await detectGhostSpecs(projectId, dataEntries);
     const { updates, report } = await detectSpecStateDivergences(projectPath, dataEntries);
+    report.ghosts = ghosts;
     // SyncReport.rejected is always defined (SPEC-720)
     const TERMINAL_STATUSES = ['done', 'discarded'];
     for (const { specId, newStatus } of updates) {
@@ -136,6 +142,41 @@ export async function syncSpecState(projectPath, projectId) {
     }
     return report;
 }
+/**
+ * SPEC-1351 (AC3): scan the data store for entries whose spec.md is missing on
+ * disk and quarantine each one — appends a `ghost_spec_quarantined` transition
+ * event (surfaced by workspace_alerts with a recovery action) and returns the
+ * list so callers can report it inline.
+ */
+async function detectGhostSpecs(projectId, dataEntries) {
+    const ghosts = [];
+    await Promise.all(dataEntries.map(async (entry) => {
+        if (!entry.specPath) {
+            return;
+        }
+        try {
+            const fileStat = await stat(entry.specPath);
+            if (fileStat.size > 0) {
+                return;
+            }
+        }
+        catch {
+            // fall through to quarantine — missing or unreadable spec.md
+        }
+        const reason = `Store entry ${entry.id} references spec.md at ${entry.specPath}, which is missing or empty on disk. Recreate the spec via create_spec or restore spec.md from git/backup.`;
+        ghosts.push({ specId: entry.id, specPath: entry.specPath, reason });
+        void appendTransitionEvent({
+            projectId,
+            specId: entry.id,
+            eventType: 'ghost_spec_quarantined',
+            actor: 'sync_spec_state',
+            reason,
+        }).catch(() => {
+            /* best-effort */
+        });
+    }));
+    return ghosts;
+}
 /**
  * Startup sync: iterates all registered projects and calls syncSpecState for each.
  * Non-blocking — errors are logged but not propagated.
@@ -183,6 +224,13 @@ function formatReport(report, label) {
             lines.push(`    - ${r.specId}: ${r.reason}`);
         }
     }
+    // SPEC-1351: Ghost store entries quarantined (missing spec.md on disk)
+    if ((report.ghosts?.length ?? 0) > 0) {
+        lines.push('  Quarantined ghosts (spec.md missing — recreate or restore):');
+        for (const g of report.ghosts ?? []) {
+            lines.push(`    - ${g.specId}: ${g.specPath}`);
+        }
+    }
     if (report.errors.length > 0) {
         lines.push('  Errors:');
         for (const e of report.errors) {

package/dist/tools/update-status/batch.d.ts

@@ -1,3 +1,7 @@
-import type { ToolResult, UpdateStatusBatchInput } from '../../types/index.js';
-export declare function handleUpdateStatusBatch(input: UpdateStatusBatchInput): Promise<ToolResult>;
+import type { SpecStatus, ToolResult, UpdateStatusBatchInput } from '../../types/index.js';
+type UncheckedUpdateStatusBatchInput = Omit<UpdateStatusBatchInput, 'status'> & {
+    status: SpecStatus;
+};
+export declare function handleUpdateStatusBatch(input: UncheckedUpdateStatusBatchInput): Promise<ToolResult>;
+export {};
 //# sourceMappingURL=batch.d.ts.map