@planu/cli 5.0.0 → 5.2.0

package/dist/tools/init-project/handler.js

@@ -11,6 +11,7 @@ import { analyzeProject, checkProjectCompleteness } from '../../engine/analyzer.
 import { parseProjectQualityRules } from '../../engine/auditor-claude-md.js';
 import { detectMissingAreas, buildRequestPrompt } from '../../engine/context-merger.js';
 import { detectProjectPrivacyConfig, maybeGenerateEnvExample, buildBeginnerEnvGuide, } from './helpers.js';
+import { buildDefaultPrivacyConfig } from '../../engine/pii-detector.js';
 import { checkBundledVersionGap } from '../../engine/version-detector/bundled-version-checker.js';
 import { checkAndFixBundledVersion } from '../../engine/mcp-config/mcp-config-writer.js';
 import { buildInitProjectResult } from './result-builder.js';
@@ -86,6 +87,25 @@ function detectMultipleFrameworks(stack) {
     }
     return null;
 }
+/**
+ * SPEC-1343: Runs one independent, best-effort pipeline stage in isolation so it can be
+ * batched with `Promise.all` alongside other independent stages. A rejection never
+ * propagates to the caller — it resolves to `fallback` and is flagged via `failed`/`error`
+ * so init_project can still succeed and surface the failure in its result summary (AC2).
+ */
+async function runOptionalStage(name, fallback, task) {
+    try {
+        return { name, value: await task(), failed: false };
+    }
+    catch (err) {
+        return {
+            name,
+            value: fallback,
+            failed: true,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 // eslint-disable-next-line max-lines-per-function
 export async function handleInitProject(params, server) {
     // eslint-disable-next-line max-lines-per-function, complexity
@@ -256,8 +276,14 @@ export async function handleInitProject(params, server) {
             const globalConfig = await globalStore.getGlobalConfig();
             const effectiveLocale = locale ?? globalConfig.defaultLocale;
             const effectiveExperience = experienceLevel ?? globalConfig.defaultExperienceLevel;
-            // Run full project analysis
-            const knowledge = await analyzeProject(projectPath, projectId, effectiveLocale, effectiveExperience);
+            // SPEC-1343: analyzeProject (full tree scan) and detectStackPatterns are both
+            // independent read-only scans of the same project tree — run them concurrently
+            // instead of back-to-back so wall time is ~1x the slower stage, not the sum (AC1).
+            const [knowledge, stackResult] = await Promise.all([
+                analyzeProject(projectPath, projectId, effectiveLocale, effectiveExperience),
+                detectStackPatterns(projectPath),
+            ]);
+            const { modernPatterns, dddConfig, agileDetection, orchestratorInfo, composeMultiplatform } = stackResult;
             if (approvedTechnologyContract !== null) {
                 knowledge.language = approvedTechnologyContract.language ?? knowledge.language;
                 knowledge.framework =
@@ -330,9 +356,6 @@ export async function handleInitProject(params, server) {
             if (hourlyRate !== undefined) {
                 await globalStore.updateGlobalConfig({ hourlyRate });
             }
-            // SPEC-033: Detect modern architecture patterns and stack info
-            const stackResult = await detectStackPatterns(projectPath);
-            const { modernPatterns, dddConfig, agileDetection, orchestratorInfo, composeMultiplatform } = stackResult;
             // SPEC-568: Smart tool group activation based on detected stack.
             // Runs before saveKnowledge so the snapshot can be persisted in one write.
             const groupProfileSnapshot = applyStackBasedGroupActivations(knowledge.stack);
@@ -352,16 +375,54 @@ export async function handleInitProject(params, server) {
             addProject(projectPath).catch(() => {
                 /* best-effort — never block init_project */
             });
+            // SPEC-1343: buildProjectConfig -> runSpecMigrations must stay ordered (config must be
+            // written before migrations run against it, and runSpecMigrations is invoked exactly
+            // once per run, AC3). That ordered chain is independent of the read-only discovery
+            // batch below, so both run concurrently (AC1/AC4).
             // SPEC-131: Build legal profile and generate planu.json / What's New
             // SPEC-313: Pass workMode to persist in planu.json
-            const configResult = await buildProjectConfig(projectPath, projectId, knowledge, workMode);
+            const configAndMigrations = (async () => {
+                const configResult = await buildProjectConfig(projectPath, projectId, knowledge, workMode);
+                // Run spec migrations (v0.30 -> v0.40, legacy paths, prefix normalization)
+                const migrations = await runSpecMigrations(projectPath, projectId, knowledge, {
+                    repositoryMigration: 'initialization',
+                });
+                return { configResult, migrations };
+            })();
+            // SPEC-1343: Independent, best-effort discovery stages (skills fetch, privacy
+            // detection, health check, convention scan) — none of these feed each other, so they
+            // batch into a single Promise.all with per-stage error isolation. A failing optional
+            // stage falls back to a safe default instead of failing init_project (AC2).
+            const [recommendedSkillsOutcome, privacyConfigOutcome, healthReportOutcome, conventionScanOutcome,] = await Promise.all([
+                runOptionalStage('fetchRecommendedSkills', [], () => fetchRecommendedSkills(knowledge)),
+                runOptionalStage('detectProjectPrivacyConfig', buildDefaultPrivacyConfig('GDPR', []), () => detectProjectPrivacyConfig(projectPath)),
+                runOptionalStage('runHealthCheckWithBaseline', null, async () => {
+                    const allSpecs = await listProjectSpecs(projectId);
+                    const specSummaries = allSpecs.map((s) => ({
+                        specId: s.id,
+                        status: s.status,
+                        gitBranch: s.gitBranch,
+                        updatedAt: s.updatedAt,
+                    }));
+                    return runHealthCheckWithBaseline(projectPath, projectId, knowledge, specSummaries);
+                }),
+                runOptionalStage('runConventionScanSafe', 'failed', () => runConventionScanSafe(projectPath)),
+            ]);
+            const recommendedSkills = recommendedSkillsOutcome.value;
+            const privacyConfig = privacyConfigOutcome.value;
+            const healthReport = healthReportOutcome.value;
+            const conventionScanStatus = conventionScanOutcome.value;
+            const optionalStageFailures = [
+                recommendedSkillsOutcome,
+                privacyConfigOutcome,
+                healthReportOutcome,
+                conventionScanOutcome,
+            ]
+                .filter((outcome) => outcome.failed)
+                .map((outcome) => `${outcome.name}: ${outcome.error ?? 'unknown error'}`);
+            const { configResult, migrations } = await configAndMigrations;
             const { planuConfigPath, planuConfigGenerated, whatsNew } = configResult;
-            // Run spec migrations (v0.30 -> v0.40, legacy paths, prefix normalization)
-            const { discoveryResult, migrationResult, folderMigrationResult, criticalMigrationFailures, nonCriticalWarnings: nonCriticalMigrationWarnings, migrationReportPath, changedPaths: migrationChangedPaths = [], } = await runSpecMigrations(projectPath, projectId, knowledge, {
-                repositoryMigration: 'initialization',
-            });
-            // Auto-fetch recommended skills based on detected stack
-            const recommendedSkills = await fetchRecommendedSkills(knowledge);
+            const { discoveryResult, migrationResult, folderMigrationResult, criticalMigrationFailures, nonCriticalWarnings: nonCriticalMigrationWarnings, migrationReportPath, changedPaths: migrationChangedPaths = [], } = migrations;
             // Auto-install or queue skills (opt-out via planu.json or input param, SPEC-185)
             const autoInstallFromConfig = autoInstallSkills ?? (await readAutoInstallFlag(planuConfigPath));
             const { skillsAutoInstalled, skillsPendingInstall, skillsSkipped } = await orchestrateSkillInstalls(recommendedSkills, projectPath, autoInstallFromConfig);
@@ -393,17 +454,6 @@ export async function handleInitProject(params, server) {
             const beginnerEnvGuide = effectiveExperience === 'beginner' && envVars.length > 0
                 ? buildBeginnerEnvGuide(envVars)
                 : null;
-            // SPEC-030: Detect legal framework and third-party data processors
-            const privacyConfig = await detectProjectPrivacyConfig(projectPath);
-            // SPEC-180: Project health check (best-effort)
-            const allSpecs = await listProjectSpecs(projectId);
-            const specSummaries = allSpecs.map((s) => ({
-                specId: s.id,
-                status: s.status,
-                gitBranch: s.gitBranch,
-                updatedAt: s.updatedAt,
-            }));
-            const healthReport = await runHealthCheckWithBaseline(projectPath, projectId, knowledge, specSummaries);
             // SPEC-491: Auto-cleanup planu/ — remove legacy HTMLs, migrate to lean spec format (fire-and-forget)
             import('../../engine/spec-migrator/planu-root-cleaner.js')
                 .then(({ cleanPlanuRoot }) => cleanPlanuRoot(join(projectPath, 'planu')))
@@ -414,8 +464,6 @@ export async function handleInitProject(params, server) {
             void withAudit(projectPath, 'init_project', 'regeneratePages', () => regeneratePages(projectPath, ['knowledge', 'risks', 'decisions']), (pages) => ({ pages: pages.length })).catch(() => {
                 /* best-effort — never fail init */
             });
-            // SPEC-228: Deep scan — detect conventions and write planu/conventions.json (best-effort)
-            const conventionScanStatus = await runConventionScanSafe(projectPath);
             // SPEC-645: Detect LLM client and cache in conventions.json (fire-and-forget)
             void import('../../engine/client-detection.js')
                 .then(({ detectAndCacheClient }) => detectAndCacheClient(projectPath))
@@ -480,6 +528,11 @@ export async function handleInitProject(params, server) {
             }
             // SPEC-469: Build autopilot summary from setup steps performed
             const collector = new AutopilotSummaryCollector();
+            // SPEC-1343 AC2: surface optional discovery-stage failures in the result summary
+            // instead of failing init_project.
+            for (const failure of optionalStageFailures) {
+                collector.pushFail('discovery-stage-failed', failure);
+            }
             if (knowledge.stack.length > 0) {
                 collector.pushOk('stack-detection', `Stack detected: ${knowledge.stack.join(', ')}`);
             }

package/dist/tools/learn.js

@@ -3,8 +3,8 @@
 // to pattern-store for future use by estimation, auditing, and spec generation.
 // SPEC-011: adds dispatchFeedbackEvent for feedback loop dispatch.
 import { patternStore, knowledgeStore } from '../storage/index.js';
+import { SemanticIndexStore } from '../storage/semantic-index-store.js';
 import { t, ti } from '../i18n/index.js';
-import { TFIDFEngine } from '../engine/vector-store/tfidf.js';
 import { cosineSimilarity } from '../engine/vector-store/similarity.js';
 import { compactJson } from './output-formatter.js';
 /** Default cosine similarity threshold for semantic deduplication. */
@@ -45,7 +45,7 @@ export async function handleLearn(args) {
         };
     }
     // 3. Semantic deduplication check (SPEC-075 AC-08)
-    const dedupWarning = checkSemanticDuplicate(existingPatterns, pattern, type);
+    const dedupWarning = await checkSemanticDuplicate(projectId, existingPatterns, pattern, type);
     // 4. Create new pattern (store even if semantically similar — just warn)
     const patternId = `PAT-${type.substring(0, 3).toUpperCase()}-${Date.now().toString(36).toUpperCase()}`;
     const learnedPattern = {
@@ -93,18 +93,20 @@ export async function handleLearn(args) {
 /**
  * SPEC-075 AC-08: Check existing patterns for semantic similarity using TF-IDF.
  * Returns a DedupWarning if a pattern with cosine similarity > threshold exists.
+ * SPEC-1345: the same-type corpus is loaded from a persisted, incrementally
+ * updated TF-IDF index instead of being rebuilt from scratch on every call.
  */
-function checkSemanticDuplicate(existingPatterns, newPattern, patternType, threshold = DEFAULT_DEDUP_THRESHOLD) {
+async function checkSemanticDuplicate(projectId, existingPatterns, newPattern, patternType, threshold = DEFAULT_DEDUP_THRESHOLD) {
     // Filter to same-type patterns only
     const sameType = existingPatterns.filter((p) => p.type === patternType);
     if (sameType.length === 0) {
         return undefined;
     }
-    // Build TF-IDF engine from existing patterns + the new one
-    const tfidf = new TFIDFEngine();
-    for (const p of sameType) {
-        tfidf.addDocument(p.pattern);
-    }
+    const indexStore = new SemanticIndexStore(projectId, `pattern-${patternType}`);
+    const tfidf = await indexStore.loadOrBuild(sameType.map((p) => ({ id: p.id, content: p.pattern })));
+    // Embed the candidate in-memory only (it isn't stored yet, so it never
+    // becomes part of the persisted corpus) so the IDF reflects it, matching
+    // the previous non-persisted behavior.
     tfidf.addDocument(newPattern);
     // Embed the new pattern
     const newEmbedding = tfidf.embed(newPattern);

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/registry/auth.js

@@ -22,8 +22,6 @@ export async function handleRegistryLogin(args) {
         const token = args.token;
         const user = args.user;
         const email = args.email;
-        const rawPlan = args.plan;
-        const plan = rawPlan ?? 'free';
         const expiresAt = args.expiresAt;
         if (!token || !user || !email) {
             return {
@@ -37,7 +35,6 @@ export async function handleRegistryLogin(args) {
             token: await storeSecretField('global/registry/pat', 'registry-pat', token),
             user,
             email,
-            plan,
             expiresAt: expiresAt ?? new Date(Date.now() + TOKEN_EXPIRY_MS).toISOString(),
         };
         const credPath = credentialsPath();
@@ -45,12 +42,7 @@ export async function handleRegistryLogin(args) {
         await chmod(resolveStorageLayout().secrets, 0o700);
         await writeFile(credPath, JSON.stringify(credentials, null, 2), 'utf-8');
         await chmod(credPath, 0o600);
-        return compactResult([
-            `Done: Logged in successfully`,
-            `**user**: ${user}`,
-            `**email**: ${email}`,
-            `**plan**: ${plan}`,
-        ].join('\n'));
+        return compactResult([`Done: Logged in successfully`, `**user**: ${user}`, `**email**: ${email}`].join('\n'));
     }
     catch (error) {
         /* v8 ignore start -- unexpected runtime errors */
@@ -100,7 +92,6 @@ export async function handleRegistryWhoami(_args) {
         const info = {
             user: cred.user,
             email: cred.email,
-            plan: cred.plan,
             expiresAt: cred.expiresAt,
             expired: isExpired,
             authenticated: !isExpired,
@@ -108,7 +99,6 @@ export async function handleRegistryWhoami(_args) {
         return compactResult([
             `**user**: ${info.user}`,
             `**email**: ${info.email}`,
-            `**plan**: ${info.plan}`,
             `**expiresAt**: ${info.expiresAt}`,
             `**expired**: ${String(info.expired)}`,
             `**authenticated**: ${String(info.authenticated)}`,

package/dist/tools/semantic-search-handler.js

@@ -1,7 +1,7 @@
 // tools/semantic-search-handler.ts — Handler for semantic_search tool.
 // SPEC-075 AC-07: Generates TF-IDF embedding of query, searches backend.
 import { getOrCreateBackend } from '../storage/vector-store/backend-factory.js';
-import { TFIDFEngine } from '../engine/vector-store/tfidf.js';
+import { SemanticIndexStore } from '../storage/semantic-index-store.js';
 /**
  * Handle a semantic_search request.
  * Embeds the query with TF-IDF, then searches the vector backend.
@@ -33,11 +33,10 @@ export async function handleSemanticSearch(args) {
             ],
         };
     }
-    // Build TF-IDF from existing corpus
-    const tfidf = new TFIDFEngine();
-    for (const doc of allDocs) {
-        tfidf.addDocument(doc.content);
-    }
+    // SPEC-1345: load the persisted TF-IDF index for this scope, incrementally
+    // reconciled against the current corpus (no full rebuild for unchanged docs).
+    const indexStore = new SemanticIndexStore(projectId, scope);
+    const tfidf = await indexStore.loadOrBuild(allDocs.map((doc) => ({ id: doc.id, content: doc.content })));
     // Embed the query
     const queryEmbedding = tfidf.embed(query);
     // Search

package/dist/tools/status-handler.js

@@ -79,18 +79,28 @@ function parseSpecNumber(id) {
     const match = /SPEC-(\d+)/i.exec(id);
     return match?.[1] !== undefined ? parseInt(match[1], 10) : 0;
 }
+function selectActiveSpec(specs) {
+    // Lifecycle-first ordering: implementing always outranks review, regardless of SPEC number.
+    // Within the same lifecycle status, the tie-break is descending SPEC number (most recent first).
+    for (const status of ['implementing', 'review']) {
+        const candidates = specs
+            .filter((s) => s.status === status)
+            .sort((a, b) => parseSpecNumber(b.id) - parseSpecNumber(a.id));
+        const candidate = candidates[0];
+        if (candidate !== undefined) {
+            return { id: candidate.id, title: candidate.title, status };
+        }
+    }
+    return null;
+}
 async function getStatusSpecSnapshot(projectId) {
     try {
         const specs = await listSpecs(projectId);
-        const inProgress = specs
-            .filter((s) => s.status === 'implementing' || s.status === 'review')
-            .sort((a, b) => parseSpecNumber(b.id) - parseSpecNumber(a.id));
+        const active = selectActiveSpec(specs.filter((s) => s.status === 'implementing' || s.status === 'review'));
         const approved = specs
             .filter((s) => s.status === 'approved')
             .sort((a, b) => parseSpecNumber(a.id) - parseSpecNumber(b.id));
-        const activeItem = inProgress[0];
         const nextItem = approved[0];
-        const active = activeItem !== undefined ? { id: activeItem.id, title: activeItem.title } : null;
         const next = nextItem !== undefined ? { id: nextItem.id, title: nextItem.title } : null;
         return { active, next, queueCount: approved.length };
     }
@@ -130,6 +140,9 @@ async function getSLABreaches(projectId) {
 // ---------------------------------------------------------------------------
 function buildSuggestion(snapshot) {
     if (snapshot.active !== null) {
+        if (snapshot.active.status === 'review') {
+            return `Resolve review for ${snapshot.active.id} — it is not yet implementing`;
+        }
         return `Continue ${snapshot.active.id} — it may be blocking others`;
     }
     if (snapshot.next !== null) {
@@ -145,7 +158,7 @@ function buildOutput(params) {
     const lines = ['Planu Status', '━━━━━━━━━━━━━━━'];
     if (snapshot.active !== null) {
         const title = snapshot.active.title.slice(0, 40);
-        lines.push(`ACTIVE    ${snapshot.active.id} ${title} (in-progress)`);
+        lines.push(`ACTIVE    ${snapshot.active.id} ${title} (${snapshot.active.status})`);
     }
     else {
         lines.push(`ACTIVE    (none)`);

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

package/dist/tools/update-status/batch.js

@@ -6,7 +6,60 @@ function firstText(result) {
     const first = result.content[0];
     return first?.type === 'text' ? first.text : JSON.stringify(result.structuredContent ?? {});
 }
+/** SPEC-1349: extract the gate failure code + actionable next step from a per-spec transition result. */
+function failureDetails(result) {
+    const structured = result.structuredContent;
+    const code = typeof structured?.error === 'string' ? structured.error : undefined;
+    const nextAction = typeof structured?.fixHint === 'string' ? structured.fixHint : undefined;
+    return { code, nextAction };
+}
+const MAX_NARRATIVE_FAILURE_ROWS = 5;
+/** SPEC-1349: render up to MAX_NARRATIVE_FAILURE_ROWS per-spec reasons, capping token cost. */
+function renderFailureNarrative(failed) {
+    if (failed.length === 0) {
+        return [];
+    }
+    const shown = failed.slice(0, MAX_NARRATIVE_FAILURE_ROWS);
+    const remaining = failed.length - shown.length;
+    const lines = ['Failed specs:', ...shown.map((row) => `- ${row.specId}: ${row.message}`)];
+    if (remaining > 0) {
+        const dominantCode = shown[0]?.code;
+        const sameCause = dominantCode !== undefined && failed.every((row) => row.code === dominantCode);
+        lines.push(sameCause
+            ? `...and ${String(remaining)} more with the same cause.`
+            : `...and ${String(remaining)} more (see structuredContent.failed for details).`);
+    }
+    return lines;
+}
+/** SPEC-1349: when every failure shares one gate cause, surface a single aggregated next step. */
+function dominantFailureNextAction(failed) {
+    if (failed.length === 0) {
+        return undefined;
+    }
+    const firstCode = failed[0]?.code;
+    if (firstCode === undefined) {
+        return undefined;
+    }
+    const allSameCause = failed.every((row) => row.code === firstCode);
+    if (!allSameCause) {
+        return undefined;
+    }
+    return failed[0]?.nextAction;
+}
 export async function handleUpdateStatusBatch(input) {
+    if (input.status === 'done') {
+        const fixHint = 'Close each spec individually with update_status(done) and its full implementation review evidence.';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `BATCH_DONE_UNSUPPORTED: Batch done transitions are not supported.\nFix: ${fixHint}`,
+                },
+            ],
+            isError: true,
+            structuredContent: { error: 'BATCH_DONE_UNSUPPORTED', code: 422, fixHint },
+        };
+    }
     const uniqueSpecIds = [...new Set(input.specIds)].sort();
     if (uniqueSpecIds.length === 0) {
         return {
@@ -57,7 +110,7 @@ export async function handleUpdateStatusBatch(input) {
                     skipped.push({ specId, message });
                 }
                 else {
-                    failed.push({ specId, message });
+                    failed.push({ specId, message, ...failureDetails(result) });
                 }
             }
             else {
@@ -81,11 +134,14 @@ export async function handleUpdateStatusBatch(input) {
         /* reliability-cleanup: POST_BATCH_STRICT_CLEANUP — validation remains fail-closed */
         reportClassifiedDegradation('POST_BATCH_STRICT_CLEANUP', error);
     }
+    const aggregatedNextAction = dominantFailureNextAction(failed);
     const text = [
         `Batch status transition complete: ${input.status}`,
         `Updated: ${updated.length}`,
         `Skipped: ${skipped.length}`,
         `Failed: ${failed.length}`,
+        ...renderFailureNarrative(failed),
+        ...(aggregatedNextAction ? [`Next action: ${aggregatedNextAction}`] : []),
     ].join('\n');
     return {
         content: [{ type: 'text', text }],
@@ -95,6 +151,7 @@ export async function handleUpdateStatusBatch(input) {
             skipped,
             failed,
             sideEffectsFlushed: ['strict-planu-cleanup'],
+            ...(aggregatedNextAction ? { nextAction: aggregatedNextAction } : {}),
         },
     };
 }

package/dist/tools/update-status/dod-gates.d.ts

@@ -83,6 +83,21 @@ export interface DoneGateResult {
     forcedBypassWarning: string | null;
     freshnessLease: ValidationFreshnessLease | null;
 }
+/**
+ * SPEC-1356 (T-A1): auto-derive the sha256 digest of the persisted
+ * `validation-report.json` so callers no longer have to compute it by hand.
+ * Reads and hashes the exact same bytes `checkDoneReviewDigest` would validate
+ * against, using the same hardened path/identity checks. Returns the digest, or
+ * the exact blocking `ToolResult` when the report cannot be safely read (e.g.
+ * validate has not run yet). Exported for direct unit testing and for the
+ * orchestration layer (`update-status/index.ts`) that no longer requires the
+ * caller to supply `implementationReviewDigest`.
+ */
+export declare function deriveDoneReviewDigest(specId: string, projectId: string): Promise<{
+    digest: string;
+} | {
+    error: ToolResult;
+}>;
 /**
  * SPEC-725: Check the validation-report artifact gate before marking done.
  * SPEC-1050: Fail closed. A done transition requires a fresh validation-report
@@ -99,7 +114,7 @@ export declare function checkSpecReviewGate(specId: string, projectId: string, _
  * When force=true, gates are not blocking but failing items are recorded in
  * the project's force-bypass-log.json for traceability (guard: done ≠ implemented).
  */
-export declare function checkDoneGates(spec: Spec, specId: string, projectId: string, projectPath: string | undefined, _force: boolean | undefined, _forceReason?: string, verifyReceipt?: DoneReceiptVerifier): Promise<DoneGateResult>;
+export declare function checkDoneGates(spec: Spec, specId: string, projectId: string, projectPath: string | undefined, _force: boolean | undefined, _forceReason?: string, verifyReceipt?: DoneReceiptVerifier, implementationReviewDigest?: string): Promise<DoneGateResult>;
 export { checkQaGate } from './qa-gate.js';
 export { checkApprovedFormatGate, checkComplianceGate, type ComplianceGateResult, } from './approval-gates.js';
 /**