@planu/cli 5.3.57 → 5.3.58

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [5.3.58] - 2026-08-26
+
+### Bug Fixes
+- fix(SPEC-1317): assert the dynamic-import edge for the pending-release helper
+- fix(SPEC-1319): close review findings on enricher integrity wiring
+- fix(SPEC-1317): align doctor deep-check count with the installation-integrity check
+- fix(SPEC-1319): block stale review-enricher runtimes from truncating canonical specs
+- fix(SPEC-1317): diagnose and recover incomplete CLI installs without crashing planu status
+
+### Refactoring
+- refactor(SPEC-1319): move enrichment integrity validator to a neutral module
+- refactor(SPEC-1317): extract pending-ledger rewrite to satisfy the function-length gate
+
+### Chores
+- chore(planu): close SPEC-1317 and SPEC-1319
+- chore(SPEC-1319): integrate review-enricher integrity and stale-dist guard
+- chore(SPEC-1317): integrate incomplete-install doctor and release-metadata degradation
+- chore(planu): record SPEC-1317 implementing state
+- chore(planu): record SPEC-1319 implementing and fix SPEC-1317 files ownership
+
+
 ## [5.3.57] - 2026-08-26
 
 ### Bug Fixes

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"c368e9e9512d869bdabaf330a598fadc95eb2a9c"}
+{"schemaVersion":1,"commit":"27eba0edeec0ce821f730eebbbbd999f5a1725b6"}

package/dist/cli/commands/doctor.d.ts

@@ -25,8 +25,10 @@ declare function checkDataDirWritable(): DeepCheckResult;
 declare function checkRuntimeDatabase(): DeepCheckResult;
 /** Check (4): the active locale resolves to a real translated message. */
 declare function checkLocaleResolution(): DeepCheckResult;
+/** Check (5): every package-owned runtime helper compiled CLI code imports is present. */
+declare function checkInstallationIntegrity(): DeepCheckResult;
 declare function runDeepChecks(): DeepCheckResult[];
-export { checkNodeVersion, checkDataDirWritable, checkRuntimeDatabase, checkLocaleResolution, runDeepChecks, };
+export { checkNodeVersion, checkDataDirWritable, checkRuntimeDatabase, checkLocaleResolution, checkInstallationIntegrity, runDeepChecks, };
 export { checkTool };
 export declare const doctorCommand: CliCommand;
 //# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.js

@@ -1,9 +1,9 @@
 // cli/commands/doctor.ts — planu doctor: verify MCP installations health (SPEC-236)
 // Deep diagnostics (Node version, storage writability, runtime DB,
 // locale resolution) added by SPEC-1346 / SPEC-1344.
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { bold, cyan, green, yellow, red, dim } from '../colors.js';
 import { readJsonFile, hasPlanuEntry } from './install.js';
@@ -97,6 +97,8 @@ function checkTool(check) {
 // ---------------------------------------------------------------------------
 /** Root of the package, resolved relative to this module so it works from src/ and dist/. */
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '../../../package.json');
+/** Package-relative runtime helpers compiled CLI code imports outside dist/. */
+const REQUIRED_RUNTIME_HELPERS = ['scripts/lib/pending-release-file.mjs'];
 function parseVersionTuple(version) {
     const match = /(\d+)\.(\d+)\.(\d+)/.exec(version);
     return [Number(match?.[1] ?? 0), Number(match?.[2] ?? 0), Number(match?.[3] ?? 0)];
@@ -196,12 +198,66 @@ function checkLocaleResolution() {
     }
     return { name: 'Locale resolution', status: 'ok', detail: `Resolved locale: ${locale}` };
 }
+function readInstalledVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(PACKAGE_ROOT, 'utf-8'));
+        return pkg.version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function readInstalledPackageName() {
+    try {
+        const pkg = JSON.parse(readFileSync(PACKAGE_ROOT, 'utf-8'));
+        return pkg.name ?? '@planu/cli';
+    }
+    catch {
+        return '@planu/cli';
+    }
+}
+function isContainedInPackageRoot(packageRoot, candidate) {
+    const rel = relative(packageRoot, candidate);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+function isRegularFileWithinPackage(packageRoot, relativePath) {
+    const candidate = join(packageRoot, relativePath);
+    if (!isContainedInPackageRoot(packageRoot, candidate)) {
+        return false;
+    }
+    try {
+        return statSync(candidate).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Check (5): every package-owned runtime helper compiled CLI code imports is present. */
+function checkInstallationIntegrity() {
+    const packageRoot = dirname(PACKAGE_ROOT);
+    const missing = REQUIRED_RUNTIME_HELPERS.filter((helper) => !isRegularFileWithinPackage(packageRoot, helper));
+    if (missing.length === 0) {
+        return {
+            name: 'Installation integrity',
+            status: 'ok',
+            detail: 'All package-owned runtime helpers are present.',
+        };
+    }
+    const version = readInstalledVersion();
+    const packageName = readInstalledPackageName();
+    return {
+        name: 'Installation integrity',
+        status: 'fail',
+        detail: `INCOMPLETE_INSTALLATION: ${packageName}@${version} is missing ${missing.join(', ')}. Reinstall with: npm install -g ${packageName}@${version}`,
+    };
+}
 function runDeepChecks() {
     return [
         checkNodeVersion(),
         checkDataDirWritable(),
         checkRuntimeDatabase(),
         checkLocaleResolution(),
+        checkInstallationIntegrity(),
     ];
 }
 function deepCheckIcon(status) {
@@ -226,7 +282,7 @@ function printDeepChecks(results) {
     }
 }
 // Exported for tests
-export { checkNodeVersion, checkDataDirWritable, checkRuntimeDatabase, checkLocaleResolution, runDeepChecks, };
+export { checkNodeVersion, checkDataDirWritable, checkRuntimeDatabase, checkLocaleResolution, checkInstallationIntegrity, runDeepChecks, };
 function statusIcon(status) {
     switch (status) {
         case 'ok':

package/dist/engine/cascade-hooks/core/append-releases.d.ts

@@ -1,11 +1,11 @@
 import type { CascadeContext, CoreActionResult, PendingReleaseEntry } from '../../../types/cascade-hooks.js';
-import { type ReleaseTagInfo } from '../../../../scripts/lib/pending-release-file.mjs';
+import type { ReleaseTagInfo } from '../../../../scripts/lib/pending-release-file.mjs';
 export declare function normalizePendingReleaseEntries(value: unknown): (PendingReleaseEntry & {
     implementationCommit?: string;
 })[];
 export declare function reconcilePublishedPendingEntries(entries: readonly (PendingReleaseEntry & {
     implementationCommit?: string;
-})[], release: ReleaseTagInfo | null): (PendingReleaseEntry & {
+})[], release: ReleaseTagInfo | null, isCommitReachable?: (repoRoot: string, commit: string, target: string) => boolean): (PendingReleaseEntry & {
     implementationCommit?: string;
 })[];
 export declare function appendReleasesPending(ctx: CascadeContext): Promise<CoreActionResult>;

package/dist/engine/cascade-hooks/core/append-releases.js

@@ -4,12 +4,17 @@
 import { join } from 'node:path';
 import { readFile, mkdir } from 'node:fs/promises';
 import { execFile as execFileCallback } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { promisify } from 'node:util';
 import { specStore } from '../../../storage/index.js';
 import { reportClassifiedDegradation } from '../../../errors/classified-degradation.js';
-import { isCommitReachable, resolveLatestReleaseTag, withPendingReleaseLock, writePendingReleaseLedger, } from '../../../../scripts/lib/pending-release-file.mjs';
 const CORE_ACTION_BUDGET_MS = 2000;
 const execFile = promisify(execFileCallback);
+const requireFromHere = createRequire(import.meta.url);
+function requireIsCommitReachable(repoRoot, commit, target) {
+    const helpers = requireFromHere('../../../../scripts/lib/pending-release-file.mjs');
+    return helpers.isCommitReachable(repoRoot, commit, target);
+}
 function isValidPendingReleaseEntry(value) {
     if (typeof value !== 'object' || value === null) {
         return false;
@@ -37,7 +42,7 @@ export function normalizePendingReleaseEntries(value) {
     }
     return [...deduped.values()];
 }
-export function reconcilePublishedPendingEntries(entries, release) {
+export function reconcilePublishedPendingEntries(entries, release, isCommitReachable = requireIsCommitReachable) {
     if (!release) {
         return [...entries];
     }
@@ -72,6 +77,27 @@ async function captureHeadCommit(projectPath) {
         return undefined;
     }
 }
+async function rewritePendingLedger(input) {
+    let pendingList = [];
+    try {
+        const raw = await readFile(input.pendingPath, 'utf-8');
+        pendingList = normalizePendingReleaseEntries(JSON.parse(raw));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            reportClassifiedDegradation('PENDING_RELEASE_LEDGER_UNREADABLE', error);
+            return;
+        }
+    }
+    pendingList = reconcilePublishedPendingEntries(pendingList, input.releaseInfo, input.isCommitReachable).filter((entry) => entry.specId !== input.specId);
+    pendingList.push({
+        specId: input.specId,
+        title: input.title,
+        completedAt: new Date().toISOString().substring(0, 10),
+        ...(input.implementationCommit ? { implementationCommit: input.implementationCommit } : {}),
+    });
+    await input.writePendingReleaseLedger(input.pendingPath, pendingList);
+}
 async function actuallyAppendReleasesPending(ctx, opts) {
     const { projectPath, projectId, specId } = ctx;
     if (!projectPath || ctx.newStatus !== 'done') {
@@ -80,6 +106,15 @@ async function actuallyAppendReleasesPending(ctx, opts) {
     if (opts.signal.aborted) {
         throw new Error('append-releases-pending aborted before start');
     }
+    let helpers;
+    try {
+        helpers = await import('../../../../scripts/lib/pending-release-file.mjs');
+    }
+    catch (error) {
+        reportClassifiedDegradation('RELEASE_METADATA_UNAVAILABLE', error);
+        return;
+    }
+    const { isCommitReachable, resolveLatestReleaseTag, withPendingReleaseLock, writePendingReleaseLedger, } = helpers;
     const releasesDir = join(projectPath, 'planu', 'releases');
     const pendingPath = join(releasesDir, 'pending.json');
     await new Promise((resolve, reject) => {
@@ -91,30 +126,15 @@ async function actuallyAppendReleasesPending(ctx, opts) {
             const spec = await specStore.getSpec(projectId, specId);
             const releaseInfo = await resolveLatestReleaseTag(projectPath);
             const implementationCommit = await captureHeadCommit(projectPath);
-            await withPendingReleaseLock(pendingPath, { timeoutMs: 1_500, signal: opts.signal }, async () => {
-                let pendingList = [];
-                try {
-                    const raw = await readFile(pendingPath, 'utf-8');
-                    const parsed = JSON.parse(raw);
-                    pendingList = normalizePendingReleaseEntries(parsed);
-                }
-                catch (error) {
-                    if (error.code !== 'ENOENT') {
-                        reportClassifiedDegradation('PENDING_RELEASE_LEDGER_UNREADABLE', error);
-                        return;
-                    }
-                }
-                pendingList = reconcilePublishedPendingEntries(pendingList, releaseInfo);
-                const completedAt = new Date().toISOString().substring(0, 10);
-                pendingList = pendingList.filter((entry) => entry.specId !== specId);
-                pendingList.push({
-                    specId,
-                    title: spec?.title ?? specId,
-                    completedAt,
-                    ...(implementationCommit ? { implementationCommit } : {}),
-                });
-                await writePendingReleaseLedger(pendingPath, pendingList);
-            });
+            await withPendingReleaseLock(pendingPath, { timeoutMs: 1_500, signal: opts.signal }, () => rewritePendingLedger({
+                pendingPath,
+                specId,
+                title: spec?.title ?? specId,
+                implementationCommit,
+                releaseInfo,
+                isCommitReachable,
+                writePendingReleaseLedger,
+            }));
             void (async () => {
                 try {
                     const { planuAutoCommit } = await import('../../git/planu-autocommit.js');

package/dist/engine/cascade-hooks/hooks/review-enricher.hook.js

@@ -1,18 +1,29 @@
 import { reportClassifiedDegradation } from '../../../errors/classified-degradation.js';
+import { assertLocalBuildFreshness } from '../../build-freshness.js';
+function isEnrichmentIntegrityFailure(error) {
+    return error instanceof Error && error.message.startsWith('SPEC_ENRICHMENT_INTEGRITY_FAILED');
+}
 async function handler(ctx) {
     const { projectPath, specId, spec } = ctx;
     if (!projectPath) {
         return;
     }
-    // Skip trivial-scope specs
     if (spec.scope === 'trivial') {
         return;
     }
     try {
+        if (assertLocalBuildFreshness().status === 'stale') {
+            reportClassifiedDegradation('STALE_LOCAL_DIST', new Error('Local build output is stale relative to the active checkout. Run `pnpm build:ts` before retrying.'));
+            return;
+        }
         const { runTechnicalEnricher } = await import('../../../engine/technical-enricher/index.js');
         await runTechnicalEnricher({ specId, projectPath, specScope: spec.scope });
     }
-    catch {
+    catch (error) {
+        if (isEnrichmentIntegrityFailure(error)) {
+            reportClassifiedDegradation('SPEC_ENRICHMENT_INTEGRITY_FAILED', new Error('Review enrichment output failed the canonical spec integrity contract'));
+            return;
+        }
         reportClassifiedDegradation('REVIEW_ENRICHER_FAILED', new Error('Technical review enrichment failed'));
     }
 }

package/dist/engine/cascade-hooks/integrity.d.ts

@@ -0,0 +1,2 @@
+export declare function assertEnrichmentPreservesContract(before: string, after: string, hookId: string): void;
+//# sourceMappingURL=integrity.d.ts.map

package/dist/engine/cascade-hooks/integrity.js

@@ -0,0 +1,40 @@
+const HISTORICAL_TRUNCATION_MARKER = '[truncated — spec too large, enrich remaining files manually]';
+const REQUIRED_WORD_MARKERS = ['GIVEN', 'WHEN', 'THEN', 'AND'];
+const REQUIRED_LITERAL_MARKERS = ['FILES:', 'FUNCTIONS:', 'TEST:'];
+const HEADING_LINE_PATTERN = /^#{1,6}[ \t]+.+$/gm;
+function countLiteralOccurrences(haystack, needle) {
+    let count = 0;
+    let index = haystack.indexOf(needle);
+    while (index !== -1) {
+        count += 1;
+        index = haystack.indexOf(needle, index + needle.length);
+    }
+    return count;
+}
+function countWordOccurrences(haystack, word) {
+    return (haystack.match(new RegExp(`\\b${word}\\b`, 'g')) ?? []).length;
+}
+function integrityFailure(hookId, reason) {
+    return new Error(`SPEC_ENRICHMENT_INTEGRITY_FAILED: ${hookId} ${reason}`);
+}
+export function assertEnrichmentPreservesContract(before, after, hookId) {
+    if (after.includes(HISTORICAL_TRUNCATION_MARKER)) {
+        throw integrityFailure(hookId, 'produced the historical truncation marker');
+    }
+    const afterHeadings = new Set(after.match(HEADING_LINE_PATTERN) ?? []);
+    const beforeHeadings = before.match(HEADING_LINE_PATTERN) ?? [];
+    if (beforeHeadings.some((heading) => !afterHeadings.has(heading))) {
+        throw integrityFailure(hookId, 'removed a pre-existing heading');
+    }
+    for (const marker of REQUIRED_WORD_MARKERS) {
+        if (countWordOccurrences(after, marker) < countWordOccurrences(before, marker)) {
+            throw integrityFailure(hookId, `reduced "${marker}" occurrences`);
+        }
+    }
+    for (const marker of REQUIRED_LITERAL_MARKERS) {
+        if (countLiteralOccurrences(after, marker) < countLiteralOccurrences(before, marker)) {
+            throw integrityFailure(hookId, `reduced "${marker}" occurrences`);
+        }
+    }
+}
+//# sourceMappingURL=integrity.js.map

package/dist/engine/technical-enricher/index.js

@@ -9,6 +9,7 @@ import { hasGeneratedEnrichment, renderEnriched } from './render-enriched.js';
 import { findMarkdownSectionRange } from '../spec-format/markdown-sections.js';
 import { resolveContainedProjectFile } from '../safety/contained-project-file.js';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { assertEnrichmentPreservesContract } from '../cascade-hooks/integrity.js';
 export async function enrichTechnicalContent(input) {
     const { technicalContent, specScope, projectPath } = input;
     if (hasGeneratedEnrichment(technicalContent)) {
@@ -63,6 +64,7 @@ async function runEnricherFromSpecSection(opts) {
     });
     if (result.enriched && result.enrichedContent) {
         const updated = `${specRaw.slice(0, section.contentStart)}${result.enrichedContent}${specRaw.slice(section.end)}`;
+        assertEnrichmentPreservesContract(specRaw, updated, 'review-enricher');
         await atomicWriteFile(physicalSpecPath, updated);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.3.57",
+  "version": "5.3.58",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

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": "5.3.57",
+  "version": "5.3.58",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",