@planu/cli 5.3.56 → 5.3.58

package/CHANGELOG.md

@@ -1,3 +1,49 @@
+## [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
+- fix(SPEC-1316): stop non-array ledgers and silent reachability failures from losing pending releases
+- fix(build-freshness): stop bricking a legit checkout when git is unavailable
+- fix(build): reject stale local dist before dispatch (SPEC-1318)
+- fix(build-freshness): allow diff-clean commits past the build stamp
+- fix(release): classify pending releases by git reachability (SPEC-1316)
+- fix(build): support reftable HEAD and tolerate a dirty-build-then-commit push
+- fix(release): close three fail-open gaps in pending-release reconciliation
+- fix(build): treat uncompiled TypeScript execution as not-applicable
+- fix(release): classify pending releases by git tag reachability, not date
+- fix(build): reject stale local dist output before CLI/MCP dispatch
+
+### Chores
+- chore(planu): close SPEC-1316 and SPEC-1318
+- chore(planu): add executable scenarios to SPEC-1316/1318 and file SPEC-1631
+- chore(planu): record SPEC-1316/1318 implementing transitions
+- chore(planu): add missing Create subsection to SPEC-1316 files ownership
+- chore(planu): approve 5 more specs after adding implementation contracts and test-break evidence
+- chore(planu): approve 6 reviewed specs, discard 2 stale after independent review
+- chore(planu): discard 9 speculative feature specs and 5 already-fixed gate specs
+- chore(planu): session checkpoint after v5.3.56
+
+
 ## [5.3.56] - 2026-08-25
 
 ### Bug Fixes

package/dist/.planu-build.json

@@ -0,0 +1 @@
+{"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/cli/index.js

@@ -6,7 +6,13 @@
 // we act as the MCP server. Otherwise we run the CLI router.
 import { route } from './router.js';
 import { installNetworkPolicy } from '../engine/network-policy.js';
+import { assertLocalBuildFreshness } from '../engine/build-freshness.js';
 installNetworkPolicy();
+const freshness = assertLocalBuildFreshness();
+if (freshness.status === 'stale') {
+    process.stderr.write(`Stale local build output detected (${freshness.reason}). Run \`pnpm build:ts\` and retry.\n`);
+    process.exit(1);
+}
 const args = process.argv.slice(2);
 // stdin.isTTY is undefined/false when piped (MCP host); true in a terminal.
 if (args.length === 0 && !process.stdin.isTTY) {

package/dist/engine/build-freshness.d.ts

@@ -0,0 +1,6 @@
+import type { BuildFreshnessResult, BuildStamp } from '../types/build-freshness.js';
+export declare const BUILD_STAMP_FILENAME = ".planu-build.json";
+export declare const BUILD_STAMP_SCHEMA_VERSION = 1;
+export declare function writeBuildStamp(distRoot: string, stamp: Omit<BuildStamp, 'schemaVersion'>): void;
+export declare function assertLocalBuildFreshness(distRoot?: string): BuildFreshnessResult;
+//# sourceMappingURL=build-freshness.d.ts.map

package/dist/engine/build-freshness.js

@@ -0,0 +1,170 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const BUILD_STAMP_FILENAME = '.planu-build.json';
+export const BUILD_STAMP_SCHEMA_VERSION = 1;
+const GIT_FALLBACK_TIMEOUT_MS = 2000;
+function isBuildStamp(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (candidate.schemaVersion === BUILD_STAMP_SCHEMA_VERSION &&
+        typeof candidate.commit === 'string' &&
+        candidate.commit.length > 0);
+}
+export function writeBuildStamp(distRoot, stamp) {
+    const finalPath = join(distRoot, BUILD_STAMP_FILENAME);
+    const tempPath = `${finalPath}.${process.pid}.tmp`;
+    const record = { schemaVersion: BUILD_STAMP_SCHEMA_VERSION, ...stamp };
+    try {
+        writeFileSync(tempPath, `${JSON.stringify(record)}\n`, 'utf8');
+        renameSync(tempPath, finalPath);
+    }
+    finally {
+        rmSync(tempPath, { force: true });
+    }
+}
+function readBuildStamp(distRoot) {
+    const stampPath = join(distRoot, BUILD_STAMP_FILENAME);
+    if (!existsSync(stampPath)) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(stampPath, 'utf8'));
+        return isBuildStamp(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function hasGitMarker(repoRoot) {
+    return existsSync(join(repoRoot, '.git'));
+}
+const GIT_SHA_RE = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/iu;
+const GIT_SYMBOLIC_REF_RE = /^ref:\s*(\S+)$/u;
+function readTrimmed(path) {
+    try {
+        return readFileSync(path, 'utf8').trim();
+    }
+    catch {
+        return null;
+    }
+}
+function resolveWorktreeGitDir(repoRoot) {
+    const gitPath = join(repoRoot, '.git');
+    let stat;
+    try {
+        stat = statSync(gitPath);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isDirectory()) {
+        return gitPath;
+    }
+    const content = readTrimmed(gitPath);
+    const match = content === null ? null : /^gitdir:\s*(.+)$/u.exec(content);
+    return match?.[1] ? resolve(repoRoot, match[1]) : null;
+}
+function resolveCommonGitDir(worktreeGitDir) {
+    const commonDirRelative = readTrimmed(join(worktreeGitDir, 'commondir'));
+    return commonDirRelative === null ? worktreeGitDir : resolve(worktreeGitDir, commonDirRelative);
+}
+function resolveRefSha(commonGitDir, ref) {
+    const looseRef = readTrimmed(join(commonGitDir, ref));
+    if (looseRef !== null && GIT_SHA_RE.test(looseRef)) {
+        return looseRef;
+    }
+    const packedRefs = readTrimmed(join(commonGitDir, 'packed-refs'));
+    if (packedRefs === null) {
+        return null;
+    }
+    for (const line of packedRefs.split('\n')) {
+        const [sha, packedRef] = line.split(' ');
+        if (packedRef === ref && sha !== undefined && GIT_SHA_RE.test(sha)) {
+            return sha;
+        }
+    }
+    return null;
+}
+function resolveHeadFromFilesystem(repoRoot) {
+    const worktreeGitDir = resolveWorktreeGitDir(repoRoot);
+    if (worktreeGitDir === null) {
+        return null;
+    }
+    const headContent = readTrimmed(join(worktreeGitDir, 'HEAD'));
+    if (headContent === null) {
+        return null;
+    }
+    if (GIT_SHA_RE.test(headContent)) {
+        return headContent;
+    }
+    const symbolicMatch = GIT_SYMBOLIC_REF_RE.exec(headContent);
+    if (!symbolicMatch) {
+        return null;
+    }
+    const ref = symbolicMatch[1];
+    return ref === undefined ? null : resolveRefSha(resolveCommonGitDir(worktreeGitDir), ref);
+}
+function runGitRevParse(repoRoot, revision) {
+    try {
+        const output = execFileSync('git', ['rev-parse', revision], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            timeout: GIT_FALLBACK_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return GIT_SHA_RE.test(output) ? output : null;
+    }
+    catch {
+        return null;
+    }
+}
+function resolveHead(repoRoot) {
+    return resolveHeadFromFilesystem(repoRoot) ?? runGitRevParse(repoRoot, 'HEAD');
+}
+const BUILD_INPUT_ROOT = 'src';
+function sourceUnchanged(repoRoot, diffArgs) {
+    const result = spawnSync('git', ['diff', '--quiet', ...diffArgs, '--', BUILD_INPUT_ROOT], {
+        cwd: repoRoot,
+        timeout: GIT_FALLBACK_TIMEOUT_MS,
+        killSignal: 'SIGKILL',
+        stdio: 'ignore',
+    });
+    return result.error === undefined && result.signal === null && result.status === 0;
+}
+function sourceMatchesRevision(repoRoot, stampCommit, head) {
+    return sourceUnchanged(repoRoot, [stampCommit, head]) || sourceUnchanged(repoRoot, [stampCommit]);
+}
+function resolveDistRoot() {
+    return resolve(dirname(fileURLToPath(import.meta.url)), '..');
+}
+function isRunningFromCompiledModule() {
+    return fileURLToPath(import.meta.url).endsWith('.js');
+}
+export function assertLocalBuildFreshness(distRoot) {
+    if (distRoot === undefined && !isRunningFromCompiledModule()) {
+        return { status: 'not-applicable' };
+    }
+    const resolvedDistRoot = distRoot ?? resolveDistRoot();
+    const repoRoot = resolve(resolvedDistRoot, '..');
+    if (!hasGitMarker(repoRoot)) {
+        return { status: 'not-applicable' };
+    }
+    const stamp = readBuildStamp(resolvedDistRoot);
+    if (!stamp) {
+        return { status: 'stale', reason: 'missing or malformed build provenance' };
+    }
+    const head = resolveHead(repoRoot);
+    if (!head) {
+        return { status: 'not-applicable' };
+    }
+    if (stamp.commit === head || sourceMatchesRevision(repoRoot, stamp.commit, head)) {
+        return { status: 'fresh' };
+    }
+    return { status: 'stale', reason: 'build provenance does not match the current revision' };
+}
+//# sourceMappingURL=build-freshness.js.map

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

@@ -1,5 +1,12 @@
 import type { CascadeContext, CoreActionResult, PendingReleaseEntry } from '../../../types/cascade-hooks.js';
-export declare function normalizePendingReleaseEntries(value: unknown, now?: Date): PendingReleaseEntry[];
-export declare function reconcilePublishedPendingEntries(entries: readonly PendingReleaseEntry[], latestPublishedAt: string | null): PendingReleaseEntry[];
+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, isCommitReachable?: (repoRoot: string, commit: string, target: string) => boolean): (PendingReleaseEntry & {
+    implementationCommit?: string;
+})[];
 export declare function appendReleasesPending(ctx: CascadeContext): Promise<CoreActionResult>;
 //# sourceMappingURL=append-releases.d.ts.map

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

@@ -4,68 +4,99 @@
 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 { withPendingReleaseLock, writePendingReleaseLedger, } from '../../../../scripts/lib/pending-release-file.mjs';
+import { reportClassifiedDegradation } from '../../../errors/classified-degradation.js';
 const CORE_ACTION_BUDGET_MS = 2000;
-const PENDING_ENTRY_MAX_AGE_DAYS = 30;
 const execFile = promisify(execFileCallback);
-function isValidPendingReleaseEntry(value) {
-    return (typeof value === 'object' &&
-        value !== null &&
-        typeof value.specId === 'string' &&
-        typeof value.title === 'string' &&
-        typeof value.completedAt === 'string');
+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 isRecentPendingEntry(entry, now = new Date()) {
-    const completedAt = new Date(entry.completedAt);
-    if (Number.isNaN(completedAt.getTime())) {
+function isValidPendingReleaseEntry(value) {
+    if (typeof value !== 'object' || value === null) {
         return false;
     }
-    const ageMs = now.getTime() - completedAt.getTime();
-    return ageMs <= PENDING_ENTRY_MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+    const candidate = value;
+    return (typeof candidate.specId === 'string' &&
+        typeof candidate.title === 'string' &&
+        typeof candidate.completedAt === 'string' &&
+        (candidate.implementationCommit === undefined ||
+            typeof candidate.implementationCommit === 'string'));
+}
+function hasParsableCompletionDate(entry) {
+    return !Number.isNaN(new Date(entry.completedAt).getTime());
 }
-export function normalizePendingReleaseEntries(value, now = new Date()) {
+export function normalizePendingReleaseEntries(value) {
     if (!Array.isArray(value)) {
-        return [];
+        throw new Error('Pending release ledger is not an array');
     }
     const deduped = new Map();
     for (const entry of value) {
-        if (!isValidPendingReleaseEntry(entry) || !isRecentPendingEntry(entry, now)) {
+        if (!isValidPendingReleaseEntry(entry) || !hasParsableCompletionDate(entry)) {
             continue;
         }
         deduped.set(entry.specId, entry);
     }
     return [...deduped.values()];
 }
-export function reconcilePublishedPendingEntries(entries, latestPublishedAt) {
-    if (!latestPublishedAt || !/^\d{4}-\d{2}-\d{2}/.test(latestPublishedAt)) {
+export function reconcilePublishedPendingEntries(entries, release, isCommitReachable = requireIsCommitReachable) {
+    if (!release) {
         return [...entries];
     }
-    const releaseDay = latestPublishedAt.slice(0, 10);
-    // Date-only completion metadata cannot prove ordering within the release day.
-    // Preserve same-day entries fail-closed; a later release can reconcile them safely.
-    return entries.filter((entry) => entry.completedAt.slice(0, 10) >= releaseDay);
+    let reachabilityCheckFailed = false;
+    return entries.filter((entry) => {
+        if (!entry.implementationCommit) {
+            return true;
+        }
+        try {
+            return !isCommitReachable(release.repoRoot, entry.implementationCommit, release.commit);
+        }
+        catch (error) {
+            if (!reachabilityCheckFailed) {
+                reachabilityCheckFailed = true;
+                reportClassifiedDegradation('PENDING_RELEASE_REACHABILITY_CHECK_FAILED', error);
+            }
+            return true;
+        }
+    });
 }
-async function readLatestPublishedReleaseDate(projectPath) {
+async function captureHeadCommit(projectPath) {
     try {
-        const manifest = JSON.parse(await readFile(join(projectPath, 'package.json'), 'utf-8'));
-        if (typeof manifest.version !== 'string' ||
-            !/^\d+\.\d+\.\d+(?:[-+].*)?$/.test(manifest.version)) {
-            return null;
-        }
-        const tag = `v${manifest.version}`;
-        const { stdout } = await execFile('git', ['show', '-s', '--format=%cI', tag], {
+        const { stdout } = await execFile('git', ['rev-parse', 'HEAD'], {
             cwd: projectPath,
             timeout: 1_000,
             maxBuffer: 16 * 1024,
         });
-        const publishedAt = stdout.trim();
-        return Number.isNaN(Date.parse(publishedAt)) ? null : publishedAt;
+        const commit = stdout.trim();
+        return commit || undefined;
     }
     catch {
-        return null;
+        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;
@@ -75,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) => {
@@ -84,24 +124,17 @@ async function actuallyAppendReleasesPending(ctx, opts) {
         (async () => {
             await mkdir(releasesDir, { recursive: true });
             const spec = await specStore.getSpec(projectId, specId);
-            const latestPublishedAt = await readLatestPublishedReleaseDate(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 {
-                    /* file doesn't exist yet — start fresh */
-                }
-                pendingList = reconcilePublishedPendingEntries(pendingList, latestPublishedAt);
-                const completedAt = new Date().toISOString().substring(0, 10);
-                pendingList = pendingList.filter((entry) => entry.specId !== specId);
-                pendingList.push({ specId, title: spec?.title ?? specId, completedAt });
-                await writePendingReleaseLedger(pendingPath, pendingList);
-            });
-            // Auto-commit planu/ changes so pending.json is never left unstaged
+            const releaseInfo = await resolveLatestReleaseTag(projectPath);
+            const implementationCommit = await captureHeadCommit(projectPath);
+            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/dist/index.js

@@ -3,6 +3,12 @@
 // Creates the MCP server, registers tools & resources, and starts stdio transport.
 import { installNetworkPolicy } from './engine/network-policy.js';
 installNetworkPolicy();
+const { assertLocalBuildFreshness } = await import('./engine/build-freshness.js');
+const freshness = assertLocalBuildFreshness();
+if (freshness.status === 'stale') {
+    process.stderr.write(`Stale local build output detected (${freshness.reason}). Run \`pnpm build:ts\` and retry.\n`);
+    process.exit(1);
+}
 // Remove obsolete entitlement state before CLI dispatch or MCP registration can read requests.
 const { removeCommercialState } = await import('./engine/migrations/remove-commercial-state.js');
 await removeCommercialState();

package/dist/types/build-freshness.d.ts

@@ -0,0 +1,10 @@
+export type BuildFreshnessStatus = 'fresh' | 'stale' | 'not-applicable';
+export interface BuildFreshnessResult {
+    readonly status: BuildFreshnessStatus;
+    readonly reason?: string;
+}
+export interface BuildStamp {
+    readonly schemaVersion: number;
+    readonly commit: string;
+}
+//# sourceMappingURL=build-freshness.d.ts.map

package/dist/types/build-freshness.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=build-freshness.js.map

package/dist/types/index.d.ts

@@ -169,6 +169,7 @@ export * from './spec-lock.js';
 export * from './spec-lock-v2.js';
 export * from './diagram.js';
 export * from './browser-validator.js';
+export * from './build-freshness.js';
 export * from './google-workspace.js';
 export * from './skill-eval.js';
 export * from './spec-marketplace.js';

package/dist/types/index.js

@@ -166,6 +166,7 @@ export * from './spec-lock.js';
 export * from './spec-lock-v2.js';
 export * from './diagram.js';
 export * from './browser-validator.js';
+export * from './build-freshness.js';
 export * from './google-workspace.js';
 export * from './skill-eval.js';
 export * from './spec-marketplace.js';

package/package.json

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

package/scripts/lib/pending-release-file.mjs

@@ -1,5 +1,9 @@
+import { execFile as execFileCallback, spawnSync } from 'node:child_process';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
 
+const execFile = promisify(execFileCallback);
 const DEFAULT_TIMEOUT_MS = 5_000;
 const POLL_INTERVAL_MS = 10;
 const ABANDONED_LOCK_MS = 30_000;
@@ -77,6 +81,41 @@ export async function withPendingReleaseLock(pendingPath, options, task) {
   }
 }
 
+const VERSION_TAG_PATTERN = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+
+export async function resolveLatestReleaseTag(repoRoot) {
+  try {
+    const manifest = JSON.parse(await readFile(join(repoRoot, 'package.json'), 'utf8'));
+    if (typeof manifest.version !== 'string' || !VERSION_TAG_PATTERN.test(manifest.version)) {
+      return null;
+    }
+    const tag = `v${manifest.version}`;
+    const { stdout } = await execFile('git', ['rev-parse', '--verify', '-q', `${tag}^{commit}`], {
+      cwd: repoRoot,
+      timeout: 1_000,
+      maxBuffer: 16 * 1024,
+    });
+    const commit = stdout.trim();
+    return commit ? { tag, commit, repoRoot } : null;
+  } catch {
+    return null;
+  }
+}
+
+export function isCommitReachable(repoRoot, commit, ontoCommit) {
+  const result = spawnSync('git', ['merge-base', '--is-ancestor', commit, ontoCommit], {
+    cwd: repoRoot,
+    stdio: 'ignore',
+    timeout: 1_000,
+  });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status === 0) return true;
+  if (result.status === 1) return false;
+  throw new Error(`git merge-base --is-ancestor exited with status ${String(result.status)}`);
+}
+
 export async function writePendingReleaseLedger(pendingPath, entries) {
   const temporaryPath = `${pendingPath}.${process.pid}.${Date.now()}.tmp`;
   try {