@planu/cli 4.10.2 → 4.10.3

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [4.10.3] - 2026-07-02
+
+### Bug Fixes
+- fix(SPEC-1106): reduce validate response duplication
+- fix(SPEC-1106): harden critical fallback paths
+
+
 ## [4.10.2] - 2026-07-02
 
 ### Bug Fixes

package/dist/engine/validator/analyzer.d.ts

@@ -1,4 +1,4 @@
-import type { Spec, AuditFinding, CodeState, VerifyBlock } from '../../types/index.js';
+import type { Spec, AuditFinding, CodeState, VerifyBlock, CriterionEvidenceResult } from '../../types/index.js';
 /**
  * Scan the project directory to build a CodeState for the given spec.
  */
@@ -12,6 +12,7 @@ export declare function scanCodeForSpec(spec: Spec, projectPath: string): Promis
  * buildFileContentsCache from criterion-matcher) to avoid a redundant
  * glob+readFile pass when checking multiple criteria in the same call.
  */
+export declare function checkCriterionEvidence(criterion: string, projectPath: string, codeState: CodeState, verifyBlock?: VerifyBlock, sharedFileContents?: Map<string, string>): Promise<CriterionEvidenceResult>;
 export declare function checkCriterion(criterion: string, projectPath: string, codeState: CodeState, verifyBlock?: VerifyBlock, sharedFileContents?: Map<string, string>): Promise<boolean>;
 /**
  * Classify the severity of a missing criterion based on its content.

package/dist/engine/validator/analyzer.js

@@ -164,16 +164,16 @@ export async function scanCodeForSpec(spec, projectPath) {
  * buildFileContentsCache from criterion-matcher) to avoid a redundant
  * glob+readFile pass when checking multiple criteria in the same call.
  */
-export async function checkCriterion(criterion, projectPath, codeState, verifyBlock, sharedFileContents) {
+export async function checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock, sharedFileContents) {
     // Check for file existence criteria
     const fileMatch = /(?:create|add|implement)\s+(?:file\s+)?["']?([^\s"']+\.\w+)["']?/i.exec(criterion);
     if (fileMatch?.[1]) {
         try {
             await stat(join(projectPath, fileMatch[1]));
-            return true;
+            return { status: 'proven' };
         }
         catch {
-            return false;
+            return { status: 'missing' };
         }
     }
     // Check for component/function existence in code
@@ -183,7 +183,7 @@ export async function checkCriterion(criterion, projectPath, codeState, verifyBl
         // Search in already-loaded codeState contents first (zero extra I/O)
         for (const [, content] of codeState.fileContents) {
             if (content.includes(name)) {
-                return true;
+                return { status: 'proven' };
             }
         }
         // Broader search: reuse sharedFileContents when provided to avoid a
@@ -192,17 +192,17 @@ export async function checkCriterion(criterion, projectPath, codeState, verifyBl
         const broadContents = sharedFileContents ?? (await buildBroadCache(projectPath));
         for (const [, content] of broadContents) {
             if (content.includes(name)) {
-                return true;
+                return { status: 'proven' };
             }
         }
-        return false;
+        return { status: 'missing' };
     }
     // Check for API endpoint criteria
     const endpointMatch = /(?:endpoint|route|api)\s+(?:for\s+)?["']?(\w+)["']?/i.exec(criterion);
     if (endpointMatch?.[1]) {
         for (const [, content] of codeState.fileContents) {
             if (content.toLowerCase().includes(endpointMatch[1].toLowerCase())) {
-                return true;
+                return { status: 'proven' };
             }
         }
     }
@@ -212,13 +212,17 @@ export async function checkCriterion(criterion, projectPath, codeState, verifyBl
     // For manual checks (type === 'manual'), we fall back to the optimistic heuristic.
     const deepResult = await deepCheckCriterion(criterion, projectPath, verifyBlock);
     if (deepResult.checkType !== 'manual') {
-        return deepResult.passed;
+        return { status: deepResult.passed ? 'proven' : 'missing' };
     }
-    // If we have affected files, assume basic criteria are met (optimistic fallback)
+    // Affected files alone show scope, not proof. Keep this visible so validate
+    // cannot report score 100 for manual/unclassified criteria without evidence.
     if (codeState.affectedFiles.length > 0) {
-        return true;
+        return { status: 'indeterminate' };
     }
-    return false;
+    return { status: 'missing' };
+}
+export async function checkCriterion(criterion, projectPath, codeState, verifyBlock, sharedFileContents) {
+    return ((await checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock, sharedFileContents)).status === 'proven');
 }
 /**
  * Classify the severity of a missing criterion based on its content.

package/dist/engine/validator.js

@@ -3,7 +3,7 @@
 // All imports from '../engine/validator.js' continue to work unchanged.
 import { readFile } from 'node:fs/promises';
 import { extractCriteria, extractVerifyBlocks } from './validator/extractors.js';
-import { scanCodeForSpec, checkCriterion, classifyDriftSeverity, quickQualityCheck, } from './validator/analyzer.js';
+import { scanCodeForSpec, checkCriterionEvidence, classifyDriftSeverity, quickQualityCheck, } from './validator/analyzer.js';
 import { resolveApplicableDimensions } from './validator/scope-resolver.js';
 import { buildHolisticReportFromFlatScore } from './validator/holistic-report.js';
 import { readEvidenceArtifacts } from './evidence-gates/artifact-reader.js';
@@ -71,6 +71,7 @@ export async function validateSpec(spec, projectPath) {
         return {
             matches: [],
             missing: [],
+            indeterminate: [],
             extra: [],
             fieldsImplemented: 0,
             fieldsTotal: 0,
@@ -93,15 +94,22 @@ export async function validateSpec(spec, projectPath) {
     }
     const matches = [];
     const missing = [];
+    const indeterminate = [];
     const extra = [];
     const qualityIssues = [];
     for (const criterion of criteria) {
         const verifyBlock = verifyBlockMap.get(criterion);
         const evidenceRow = traceabilityEvidence.get(normalizeCriterionForEvidence(criterion));
-        const found = evidenceRow !== undefined ||
-            (await checkCriterion(criterion, projectPath, codeState, verifyBlock));
-        if (found) {
+        if (evidenceRow !== undefined) {
             matches.push(criterion);
+            continue;
+        }
+        const evidence = await checkCriterionEvidence(criterion, projectPath, codeState, verifyBlock);
+        if (evidence.status === 'proven') {
+            matches.push(criterion);
+        }
+        else if (evidence.status === 'indeterminate') {
+            indeterminate.push(criterion);
         }
         else {
             missing.push(criterion);
@@ -131,6 +139,7 @@ export async function validateSpec(spec, projectPath) {
     return {
         matches,
         missing,
+        indeterminate,
         extra,
         fieldsImplemented,
         fieldsTotal,
@@ -157,6 +166,17 @@ export async function detectDrift(spec, projectPath, _mode = 'full', threshold =
             autoFixable: false,
         });
     }
+    for (const criterion of validation.indeterminate ?? []) {
+        drifts.push({
+            file: '',
+            specCriterion: criterion,
+            expected: 'Proven implementation evidence',
+            actual: 'Indeterminate',
+            severity: classifyDriftSeverity(criterion),
+            autoFixable: false,
+            suggestedFix: 'Add explicit validation evidence or implement a recognizable check.',
+        });
+    }
     // Quality issues as drift items
     for (const issue of validation.qualityIssues) {
         drifts.push({

package/dist/storage/base-store.d.ts

@@ -14,6 +14,13 @@
  * JSON_PARSE_UNSAFE_CAST.
  */
 export declare function safeJsonParse<T>(raw: string, fallback: T): T;
+export declare class CriticalJsonReadError extends Error {
+    readonly filePath: string;
+    readonly reason: string;
+    constructor(filePath: string, reason: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Hash a project path into a deterministic projectId using SHA-256.
  */
@@ -23,6 +30,15 @@ export declare function hashProjectPath(projectPath: string): string;
  * default value when the file does not exist.
  */
 export declare function readJson<T>(filePath: string, defaultValue: T): Promise<T>;
+/**
+ * Read a critical JSON store. Missing files still return the initialization
+ * default, but malformed JSON or wrong top-level shape throw an observable
+ * recoverable error instead of silently replacing state with an empty value.
+ */
+export declare function readCriticalJson<T>(filePath: string, defaultValue: T, options?: {
+    validate?: (value: unknown) => value is T;
+    expectedDescription?: string;
+}): Promise<T>;
 /**
  * Write a value to a JSON file, creating parent directories as needed.
  */

package/dist/storage/base-store.js

@@ -32,6 +32,16 @@ export function safeJsonParse(raw, fallback) {
         return fallback;
     }
 }
+export class CriticalJsonReadError extends Error {
+    filePath;
+    reason;
+    constructor(filePath, reason, options) {
+        super(`[Planu] Critical JSON store is unreadable at ${filePath}: ${reason}`, options);
+        this.filePath = filePath;
+        this.reason = reason;
+        this.name = 'CriticalJsonReadError';
+    }
+}
 /**
  * Hash a project path into a deterministic projectId using SHA-256.
  */
@@ -60,6 +70,34 @@ export async function readJson(filePath, defaultValue) {
         throw err;
     }
 }
+/**
+ * Read a critical JSON store. Missing files still return the initialization
+ * default, but malformed JSON or wrong top-level shape throw an observable
+ * recoverable error instead of silently replacing state with an empty value.
+ */
+export async function readCriticalJson(filePath, defaultValue, options = {}) {
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (isNodeError(err) && err.code === 'ENOENT') {
+            return defaultValue;
+        }
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new CriticalJsonReadError(filePath, 'malformed JSON', { cause: err });
+    }
+    if (options.validate && !options.validate(parsed)) {
+        throw new CriticalJsonReadError(filePath, `expected ${options.expectedDescription ?? 'valid critical JSON shape'}`);
+    }
+    return parsed;
+}
 /**
  * Write a value to a JSON file, creating parent directories as needed.
  */

package/dist/storage/knowledge-store/knowledge.js

@@ -1,10 +1,13 @@
-import { readJson, writeJson, projectDataDir } from '../base-store.js';
+import { readCriticalJson, writeJson, projectDataDir } from '../base-store.js';
 import { withFileLock } from '../file-mutex.js';
 import { discoverProjectDataFile } from '../data-dir-discovery.js';
 import { migrateLegacyDataDir } from '../migrations/cwd-to-absolute.js';
 function knowledgeFile(projectId) {
     return `${projectDataDir(projectId)}/knowledge.json`;
 }
+function isKnowledgeOrNull(value) {
+    return value === null || (typeof value === 'object' && !Array.isArray(value));
+}
 /**
  * Get project knowledge. Returns `null` when no knowledge has been stored yet.
  *
@@ -16,7 +19,10 @@ function knowledgeFile(projectId) {
 export async function getKnowledge(projectId) {
     // SPEC-1007: migrate legacy <cwd>/data/projects/{id} to absolute home once.
     await migrateLegacyDataDir(projectId);
-    const direct = await readJson(knowledgeFile(projectId), null);
+    const direct = await readCriticalJson(knowledgeFile(projectId), null, {
+        validate: isKnowledgeOrNull,
+        expectedDescription: 'a project knowledge object or null',
+    });
     if (direct !== null) {
         return direct;
     }
@@ -24,7 +30,10 @@ export async function getKnowledge(projectId) {
     if (discovered === null) {
         return null;
     }
-    return readJson(discovered, null);
+    return readCriticalJson(discovered, null, {
+        validate: isKnowledgeOrNull,
+        expectedDescription: 'a project knowledge object or null',
+    });
 }
 /**
  * Save or overwrite the full project knowledge object.
@@ -41,7 +50,10 @@ export async function saveKnowledge(projectId, knowledge) {
  */
 export async function updateKnowledge(projectId, updates) {
     return withFileLock(knowledgeFile(projectId), async () => {
-        const existing = await readJson(knowledgeFile(projectId), null);
+        const existing = await readCriticalJson(knowledgeFile(projectId), null, {
+            validate: isKnowledgeOrNull,
+            expectedDescription: 'a project knowledge object or null',
+        });
         if (!existing) {
             throw new Error(`No knowledge found for project "${projectId}". Use saveKnowledge first.`);
         }
@@ -60,7 +72,10 @@ export async function updateKnowledge(projectId, updates) {
  */
 export async function deleteKnowledge(projectId) {
     return withFileLock(knowledgeFile(projectId), async () => {
-        const existing = await readJson(knowledgeFile(projectId), null);
+        const existing = await readCriticalJson(knowledgeFile(projectId), null, {
+            validate: isKnowledgeOrNull,
+            expectedDescription: 'a project knowledge object or null',
+        });
         if (!existing) {
             return false;
         }

package/dist/storage/spec-store.js

@@ -1,4 +1,4 @@
-import { readJson, writeJson, projectDataDir } from './base-store.js';
+import { readCriticalJson, readJson, writeJson, projectDataDir } from './base-store.js';
 import { migrateLegacyDataDir } from './migrations/cwd-to-absolute.js';
 import { withFileLock } from './file-mutex.js';
 import { discoverProjectDataFile } from './data-dir-discovery.js';
@@ -60,11 +60,17 @@ async function loadAll(projectId) {
     // SPEC-1007: migrate legacy <cwd>/data/projects/{id} to absolute home once.
     await migrateLegacyDataDir(projectId);
     const directFile = specsFile(projectId);
-    let raw = await readJson(directFile, []);
+    let raw = await readCriticalJson(directFile, [], {
+        validate: (value) => Array.isArray(value),
+        expectedDescription: 'an array of specs',
+    });
     if (raw.length === 0) {
         const discovered = await discoverProjectDataFile(projectId, 'specs.json');
         if (discovered !== null && discovered !== directFile) {
-            raw = await readJson(discovered, []);
+            raw = await readCriticalJson(discovered, [], {
+                validate: (value) => Array.isArray(value),
+                expectedDescription: 'an array of specs',
+            });
         }
     }
     const specs = raw.map(normalizeSpec);

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

@@ -271,7 +271,7 @@ export async function handleInitProject(params, server) {
             const configResult = await buildProjectConfig(projectPath, projectId, knowledge, workMode);
             const { planuConfigPath, planuConfigGenerated, whatsNew } = configResult;
             // Run spec migrations (v0.30 -> v0.40, legacy paths, prefix normalization)
-            const { discoveryResult, migrationResult, folderMigrationResult } = await runSpecMigrations(projectPath, projectId, knowledge);
+            const { discoveryResult, migrationResult, folderMigrationResult, criticalMigrationFailures, nonCriticalWarnings: nonCriticalMigrationWarnings, migrationReportPath, } = await runSpecMigrations(projectPath, projectId, knowledge);
             // Auto-fetch recommended skills based on detected stack
             const recommendedSkills = await fetchRecommendedSkills(knowledge);
             // Auto-install or queue skills (opt-out via planu.json or input param, SPEC-185)
@@ -434,6 +434,9 @@ export async function handleInitProject(params, server) {
                 migrationResult,
                 discoveryResult,
                 folderMigrationResult,
+                criticalMigrationFailures,
+                nonCriticalMigrationWarnings,
+                migrationReportPath,
                 hooksInstalled,
                 gitFlowType,
                 gitignoreUpdated,

package/dist/tools/init-project/migration-runner.d.ts

@@ -1,4 +1,9 @@
 import type { ProjectKnowledge, Spec } from '../../types/index.js';
+export interface MigrationRunIssue {
+    phase: string;
+    severity: 'critical' | 'nonCritical';
+    message: string;
+}
 export interface MigrationRunResult {
     discoveryResult: {
         flattenedCount: number;
@@ -14,6 +19,9 @@ export interface MigrationRunResult {
         migratedCount: number;
         errors: string[];
     } | null;
+    criticalMigrationFailures: MigrationRunIssue[];
+    nonCriticalWarnings: MigrationRunIssue[];
+    migrationReportPath: string | null;
 }
 /**
  * Run all spec migration passes during init_project:

package/dist/tools/init-project/migration-runner.js

@@ -1,6 +1,17 @@
 // tools/init-project/migration-runner.ts — Spec migration orchestration during init_project
 import { specStore, knowledgeStore } from '../../storage/index.js';
+import { projectDataDir, writeJson } from '../../storage/base-store.js';
 import { filterLegacySpecs, migrateSpecs, filterUnprefixedSpecs, migrateSpecFolderNames, discoverAndFlattenSpecs, reconcileSpecPaths, migrateAllSpecsToLean, } from '../../engine/spec-migrator.js';
+function issueFromError(phase, severity, err) {
+    return {
+        phase,
+        severity,
+        message: err instanceof Error ? err.message : String(err),
+    };
+}
+function issuesFromMessages(phase, severity, messages) {
+    return (messages ?? []).map((message) => ({ phase, severity, message }));
+}
 /**
  * Run all spec migration passes during init_project:
  * 1. Discover and flatten specs from subcategory folders (v0.30 → v0.40)
@@ -11,23 +22,38 @@ import { filterLegacySpecs, migrateSpecs, filterUnprefixedSpecs, migrateSpecFold
 export async function runSpecMigrations(projectPath, projectId, knowledge) {
     // Auto-discover and flatten specs in subcategory folders (v0.30 → v0.40 migration)
     let discoveryResult = null;
+    const criticalMigrationFailures = [];
+    const nonCriticalWarnings = [];
     try {
         discoveryResult = await discoverAndFlattenSpecs(projectPath);
+        criticalMigrationFailures.push(...issuesFromMessages('discover-and-flatten-specs', 'critical', discoveryResult.errors));
     }
-    catch {
-        /* best-effort — don't fail init */
+    catch (err) {
+        criticalMigrationFailures.push(issueFromError('discover-and-flatten-specs', 'critical', err));
     }
     // Auto-migrate legacy specs if detected (docs/sdd/specs/ → planu/specs/)
-    const allSpecs = await specStore.listSpecs(projectId);
+    let allSpecs = [];
+    try {
+        allSpecs = await specStore.listSpecs(projectId);
+    }
+    catch (err) {
+        criticalMigrationFailures.push(issueFromError('list-specs-before-migration', 'critical', err));
+    }
     const legacySpecs = filterLegacySpecs(allSpecs);
     let migrationResult = null;
     if (legacySpecs.length > 0) {
-        migrationResult = await migrateSpecs(projectPath, legacySpecs, {
-            listSpecs: specStore.listSpecs,
-            updateSpec: specStore.updateSpec,
-        });
-        // Update knowledge specLocation after migration (create new object to avoid param mutation)
-        await knowledgeStore.saveKnowledge(projectId, { ...knowledge, specLocation: 'planu/specs' });
+        try {
+            migrationResult = await migrateSpecs(projectPath, legacySpecs, {
+                listSpecs: specStore.listSpecs,
+                updateSpec: specStore.updateSpec,
+            });
+            criticalMigrationFailures.push(...issuesFromMessages('legacy-spec-migration', 'critical', migrationResult.errors));
+            // Update knowledge specLocation after migration (create new object to avoid param mutation)
+            await knowledgeStore.saveKnowledge(projectId, { ...knowledge, specLocation: 'planu/specs' });
+        }
+        catch (err) {
+            criticalMigrationFailures.push(issueFromError('legacy-spec-migration', 'critical', err));
+        }
     }
     // Reconcile specs.json paths with actual filesystem (fixes stale paths after rename/flatten)
     try {
@@ -36,42 +62,80 @@ export async function runSpecMigrations(projectPath, projectId, knowledge) {
             updateSpec: specStore.updateSpec,
         }, projectId);
     }
-    catch {
-        /* best-effort */
+    catch (err) {
+        criticalMigrationFailures.push(issueFromError('reconcile-spec-paths', 'critical', err));
     }
     // Auto-migrate spec folders without SPEC-XXX- prefix
-    const unprefixedSpecs = filterUnprefixedSpecs(await specStore.listSpecs(projectId));
+    let specsAfterReconcile = [];
+    try {
+        specsAfterReconcile = await specStore.listSpecs(projectId);
+    }
+    catch (err) {
+        criticalMigrationFailures.push(issueFromError('list-specs-before-folder-migration', 'critical', err));
+    }
+    const unprefixedSpecs = filterUnprefixedSpecs(specsAfterReconcile);
     let folderMigrationResult = null;
     if (unprefixedSpecs.length > 0) {
-        folderMigrationResult = await migrateSpecFolderNames(projectPath, unprefixedSpecs, {
-            listSpecs: specStore.listSpecs,
-            updateSpec: specStore.updateSpec,
-        });
+        try {
+            folderMigrationResult = await migrateSpecFolderNames(projectPath, unprefixedSpecs, {
+                listSpecs: specStore.listSpecs,
+                updateSpec: specStore.updateSpec,
+            });
+            criticalMigrationFailures.push(...issuesFromMessages('spec-folder-migration', 'critical', folderMigrationResult.errors));
+        }
+        catch (err) {
+            criticalMigrationFailures.push(issueFromError('spec-folder-migration', 'critical', err));
+        }
     }
     // SPEC-461 Phase 2: Auto-migrate old verbose specs to lean format
     try {
         await migrateAllSpecsToLean(projectPath);
     }
-    catch {
-        /* best-effort — never block init_project */
+    catch (err) {
+        criticalMigrationFailures.push(issueFromError('lean-spec-migration', 'critical', err));
     }
     // SPEC-630: Merge separate technical.md into unified spec.md
     try {
         const { migrateAllSpecsToUnified } = await import('../../engine/spec-migrator/index.js');
-        await migrateAllSpecsToUnified(projectPath).catch(() => null);
+        await migrateAllSpecsToUnified(projectPath);
     }
-    catch {
-        /* best-effort — never block init_project */
+    catch (err) {
+        criticalMigrationFailures.push(issueFromError('unified-spec-migration', 'critical', err));
     }
     // SPEC-1017: strict managed planu/ cleanup after all legacy migrations.
     try {
         const { runStrictPlanuCleanup } = await import('../../engine/spec-migrator/index.js');
         await runStrictPlanuCleanup(projectPath);
     }
-    catch {
-        /* best-effort — never block init_project */
+    catch (err) {
+        criticalMigrationFailures.push(issueFromError('strict-planu-cleanup', 'critical', err));
+    }
+    let migrationReportPath = null;
+    try {
+        const reportPath = `${projectDataDir(projectId)}/reports/init-migrations/latest.json`;
+        await writeJson(reportPath, {
+            version: 1,
+            projectId,
+            generatedAt: new Date().toISOString(),
+            discoveryResult,
+            migrationResult,
+            folderMigrationResult,
+            criticalMigrationFailures,
+            nonCriticalWarnings,
+        });
+        migrationReportPath = reportPath;
+    }
+    catch (err) {
+        nonCriticalWarnings.push(issueFromError('write-migration-report', 'nonCritical', err));
     }
-    return { discoveryResult, migrationResult, folderMigrationResult };
+    return {
+        discoveryResult,
+        migrationResult,
+        folderMigrationResult,
+        criticalMigrationFailures,
+        nonCriticalWarnings,
+        migrationReportPath,
+    };
 }
 /** Return all specs for the project (needed by caller for health check refs). */
 export async function listProjectSpecs(projectId) {

package/dist/tools/init-project/result-builder.js

@@ -149,6 +149,9 @@ export function buildInitProjectResult(input) {
         specMigration: input.migrationResult,
         specDiscovery: input.discoveryResult,
         specFolderMigration: input.folderMigrationResult,
+        criticalMigrationFailures: input.criticalMigrationFailures ?? [],
+        bestEffortWarnings: input.nonCriticalMigrationWarnings ?? [],
+        migrationReportPath: input.migrationReportPath ?? null,
         gitAutomation: {
             hooksInstalled: input.hooksInstalled,
             gitFlowType: input.gitFlowType,
@@ -196,6 +199,10 @@ export function buildInitProjectResult(input) {
     const narrative = ti('tools.init_project.success', { projectPath: result.projectPath }) +
         `\n\nDetected: **${result.language}** / ${framework} — project ${action}. ` +
         `Run \`create_spec\` to start planning your first feature.` +
+        ((input.criticalMigrationFailures?.length ?? 0) > 0
+            ? `\n\n⚠️ Critical spec migration warnings: ${String(input.criticalMigrationFailures?.length ?? 0)} issue(s). ` +
+                `See migrationReportPath in structuredContent${input.migrationReportPath ? ` (${input.migrationReportPath})` : ''}.`
+            : '') +
         telemetryNote +
         trialNote +
         tokenTip;

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

@@ -38,6 +38,7 @@ import { detectHost } from '../../engine/host-detection/detect-host.js';
 import { shellHygieneReminder } from '../../hosts/claude-code/coach.js';
 import { buildTransitionEvidenceMeta, checkSddModelRoutingGate, } from '../../engine/sdd-model-routing.js';
 import { acquireLock, releaseLock, isLocked as isCrossProcessLocked, LockBusyError, } from '../../engine/safety/cross-process-lock.js';
+import { validateStrictLayoutOrError } from '../validate-helpers.js';
 /**
  * SPEC-280: Silently traverse intermediate states so callers can jump forward
  * (e.g. draft → approved) without receiving an error.
@@ -231,6 +232,9 @@ function shouldSkipSddRoutingGateForLegacyTestHarness() {
 function shouldSkipEvidenceGateForLegacyTestHarness() {
     return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_EVIDENCE_GATES !== 'true';
 }
+function shouldSkipStrictLayoutGateForLegacyTestHarness() {
+    return process.env.VITEST === 'true' && process.env.PLANU_TEST_STRICT_LAYOUT_GATE !== 'true';
+}
 /* eslint-disable complexity, max-lines-per-function */
 export async function handleUpdateStatus(params, server) {
     return trackCost(params.projectPath ?? '', 'update_status', async () => {
@@ -545,6 +549,19 @@ export async function handleUpdateStatus(params, server) {
                         return validationReportError;
                     }
                 }
+                if (newStatus === 'done' &&
+                    effectiveGatePath &&
+                    !shouldSkipStrictLayoutGateForLegacyTestHarness()) {
+                    const strictLayoutError = await validateStrictLayoutOrError({
+                        projectPath: effectiveGatePath,
+                        specId,
+                        specPath: spec.specPath,
+                        failClosedOnCrash: true,
+                    });
+                    if (strictLayoutError) {
+                        return strictLayoutError;
+                    }
+                }
                 // Process crash shield result — record run timestamp on success (SPEC-628)
                 /* c8 ignore next */
                 if (crashRisksReport !== null) {

package/dist/tools/validate-helpers.d.ts

@@ -4,6 +4,7 @@ export declare function validateStrictLayoutOrError(args: {
     projectPath: string;
     specId: string;
     specPath?: string;
+    failClosedOnCrash?: boolean;
 }): Promise<ToolResult | null>;
 export declare function buildValidateFailureFallback(failedCount: number): InteractiveQuestion;
 //# sourceMappingURL=validate-helpers.d.ts.map

package/dist/tools/validate-helpers.js

@@ -25,7 +25,25 @@ export async function validateStrictLayoutOrError(args) {
             },
         };
     }
-    catch {
+    catch (err) {
+        if (args.failClosedOnCrash) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Strict Planu layout validation crashed for ${args.specId}.\n\n` +
+                            `The done transition is blocked because canonical layout could not be verified.\n\n` +
+                            `Error: ${message}`,
+                    },
+                ],
+                isError: true,
+                structuredContent: {
+                    error: 'strict_planu_layout_check_crashed',
+                    message,
+                },
+            };
+        }
         return null;
     }
 }

package/dist/tools/validate.js

@@ -303,25 +303,21 @@ export async function handleValidate(args, server) {
     const totalCriteria = result.fieldsTotal;
     const passedCount = result.fieldsImplemented;
     const failedCount = totalCriteria - passedCount;
+    const indeterminate = result.indeterminate ?? [];
     const compactText = buildCompactValidateText({
         score: scoreValue,
         passedCount,
         failedCount,
         totalCriteria,
         missing: result.missing,
+        indeterminate,
         commitReminder,
         planuReminder,
     });
     const graphText = formatGraphCoverageText(graphCoverage);
     // SPEC-512: Compact structuredContent — essential fields only at top level
-    const compactSummary = {
-        specId,
-        score: result.score,
-        passed: passedCount,
-        failed: failedCount,
-        total: totalCriteria,
-        status: failedCount === 0 ? 'passing' : 'failing',
-    };
+    const compactSummary = buildCompactSummary(specId, result.score, passedCount, failedCount, totalCriteria);
+    const structuredBase = { ...outputWithSuggestions, summary: compactSummary, indeterminate };
     // SPEC-595: Elicit next action when validation fails and a server is available
     if (server !== undefined && failedCount > 0) {
         const { field, property } = buildEnumSchema('action', ['re-implement', 'ignore', 'mark-manual'], ['Fix failing criteria (Recommended)', 'Ignore failures', 'Mark as manually reviewed'], 'Next action', 're-implement');
@@ -339,8 +335,7 @@ export async function handleValidate(args, server) {
                     },
                 ],
                 structuredContent: {
-                    ...outputWithSuggestions,
-                    summary: compactSummary,
+                    ...structuredBase,
                     interactiveQuestions: outcome.interactiveQuestions,
                 },
             };
@@ -352,8 +347,7 @@ export async function handleValidate(args, server) {
             phaseEvent: createBasicPhaseEvent('validate', 'completed', 100, 'validating'),
             content: [{ type: 'text', text: compactText + graphText }],
             structuredContent: {
-                ...outputWithSuggestions,
-                summary: compactSummary,
+                ...structuredBase,
                 elicitedAction,
             },
         };
@@ -361,14 +355,21 @@ export async function handleValidate(args, server) {
     return {
         phaseEvent: createBasicPhaseEvent('validate', 'completed', 100, 'validating'),
         content: [{ type: 'text', text: compactText + graphText }],
-        structuredContent: {
-            ...outputWithSuggestions,
-            summary: compactSummary,
-        },
+        structuredContent: structuredBase,
+    };
+}
+function buildCompactSummary(specId, score, passedCount, failedCount, totalCriteria) {
+    return {
+        specId,
+        score,
+        passed: passedCount,
+        failed: failedCount,
+        total: totalCriteria,
+        status: failedCount === 0 ? 'passing' : 'failing',
     };
 }
 function buildCompactValidateText(args) {
-    const { score, passedCount, failedCount, totalCriteria, missing, commitReminder, planuReminder } = args;
+    const { score, passedCount, failedCount, totalCriteria, missing, indeterminate, commitReminder, planuReminder, } = args;
     if (failedCount === 0) {
         // All passing — single line
         return (`✅ Validate: ${String(score)}/100 — ${String(passedCount)}/${String(totalCriteria)} criteria passing` +
@@ -377,11 +378,20 @@ function buildCompactValidateText(args) {
     }
     // Failures exist — list only the failing ones (max 5)
     const MAX_FAILURES = 5;
-    const shownFailures = missing.slice(0, MAX_FAILURES);
-    const remainingCount = missing.length - shownFailures.length;
-    const failureList = shownFailures.map((f) => `  - ${f}`).join('\n');
+    const labelledFailures = [
+        ...missing.map((criterion) => ({ label: 'missing', criterion })),
+        ...indeterminate.map((criterion) => ({ label: 'indeterminate', criterion })),
+    ];
+    const shownFailures = labelledFailures.slice(0, MAX_FAILURES);
+    const remainingCount = labelledFailures.length - shownFailures.length;
+    const failureList = shownFailures
+        .map((f) => `  - ${f.label === 'missing' ? f.criterion : `${f.label}: ${f.criterion}`}`)
+        .join('\n');
     const moreLine = remainingCount > 0 ? `\n  ... and ${String(remainingCount)} more` : '';
-    const failNames = shownFailures.slice(0, 3).join(', ');
+    const failNames = shownFailures
+        .slice(0, 3)
+        .map((failure) => `${failure.label}: ${failure.criterion}`)
+        .join(', ');
     const summaryLine = `❌ Validate: ${String(score)}/100 — ${String(failedCount)} failing: [${failNames}${remainingCount + shownFailures.length > 3 ? '...' : ''}]`;
     return summaryLine + '\n' + failureList + moreLine + commitReminder + planuReminder;
 }

package/dist/types/analysis.d.ts

@@ -183,6 +183,8 @@ export interface HolisticValidateReport {
 export interface ValidateResult {
     matches: string[];
     missing: string[];
+    /** Criteria that could not be proven or disproven with available evidence. */
+    indeterminate?: string[];
     extra: string[];
     fieldsImplemented: number;
     fieldsTotal: number;
@@ -198,6 +200,10 @@ export interface ValidateResult {
      */
     holisticReport?: HolisticValidateReport;
 }
+export type CriterionEvidenceStatus = 'proven' | 'missing' | 'indeterminate';
+export interface CriterionEvidenceResult {
+    status: CriterionEvidenceStatus;
+}
 export interface CodeState {
     affectedFiles: string[];
     unexpectedFiles: string[];

package/dist/types/project/planu-config.d.ts

@@ -79,6 +79,17 @@ export interface InitProjectResultInput {
         migratedCount: number;
         errors: string[];
     } | null;
+    criticalMigrationFailures?: {
+        phase: string;
+        severity: 'critical' | 'nonCritical';
+        message: string;
+    }[];
+    nonCriticalMigrationWarnings?: {
+        phase: string;
+        severity: 'critical' | 'nonCritical';
+        message: string;
+    }[];
+    migrationReportPath?: string | null;
     hooksInstalled: string[];
     gitFlowType: string;
     gitignoreUpdated: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "4.10.2",
+  "version": "4.10.3",
   "description": "Planu — MCP Server for Spec Driven Development with native Rust acceleration for hot paths. Cross-platform (Linux/macOS/Windows, x64/arm64, glibc/musl).",
   "type": "module",
   "main": "dist/index.js",
@@ -34,14 +34,14 @@
     "packageName": "@planu/core"
   },
   "optionalDependencies": {
-    "@planu/core-darwin-arm64": "4.10.2",
-    "@planu/core-darwin-x64": "4.10.2",
-    "@planu/core-linux-arm64-gnu": "4.10.2",
-    "@planu/core-linux-arm64-musl": "4.10.2",
-    "@planu/core-linux-x64-gnu": "4.10.2",
-    "@planu/core-linux-x64-musl": "4.10.2",
-    "@planu/core-win32-arm64-msvc": "4.10.2",
-    "@planu/core-win32-x64-msvc": "4.10.2"
+    "@planu/core-darwin-arm64": "4.10.3",
+    "@planu/core-darwin-x64": "4.10.3",
+    "@planu/core-linux-arm64-gnu": "4.10.3",
+    "@planu/core-linux-arm64-musl": "4.10.3",
+    "@planu/core-linux-x64-gnu": "4.10.3",
+    "@planu/core-linux-x64-musl": "4.10.3",
+    "@planu/core-win32-arm64-msvc": "4.10.3",
+    "@planu/core-win32-x64-msvc": "4.10.3"
   },
   "engines": {
     "node": ">=24.0.0"

package/planu-native.json

@@ -1,7 +1,7 @@
 {
   "name": "dev.planu.native",
   "displayName": "Planu Native Lightweight Surface",
-  "version": "4.10.2",
+  "version": "4.10.3",
   "packageName": "@planu/cli",
   "modes": {
     "lightweight": {

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "4.10.2",
+  "version": "4.10.3",
   "icon": "assets/plugin/icon.svg",
   "command": [
     "npx",