@planu/cli 5.3.55 → 5.3.57

package/CHANGELOG.md

@@ -1,3 +1,45 @@
+## [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
+- fix(tests): anchor the revert-proof fixture to a pushed pre-guard tag
+- fix(release): name the failing command and its real termination cause
+- fix(release): name the blocking effect and fail closed on a broken tag lookup
+- fix(release): re-anchor a superseded recovery ledger instead of dead-ending
+- fix(worktree): reclaim content-equivalent worktrees and read the canonical branch
+
+### Chores
+- chore(planu): close SPEC-1626
+- chore(planu): close SPEC-1630
+- chore(planu): close SPEC-1625
+- chore(planu): close SPEC-1624, file SPEC-1629 transition-log rotation
+- chore(planu): file SPEC-1625 and SPEC-1626 release-pipeline dogfood bugs
+
+
 ## [5.3.55] - 2026-08-25
 
 ### Bug Fixes

package/dist/.planu-build.json

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

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): (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

@@ -6,65 +6,70 @@ import { readFile, mkdir } from 'node:fs/promises';
 import { execFile as execFileCallback } from 'node:child_process';
 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';
+import { isCommitReachable, resolveLatestReleaseTag, withPendingReleaseLock, writePendingReleaseLedger, } from '../../../../scripts/lib/pending-release-file.mjs';
 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');
-}
-function isRecentPendingEntry(entry, now = new Date()) {
-    const completedAt = new Date(entry.completedAt);
-    if (Number.isNaN(completedAt.getTime())) {
+    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) {
+    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 actuallyAppendReleasesPending(ctx, opts) {
@@ -84,7 +89,8 @@ async function actuallyAppendReleasesPending(ctx, opts) {
         (async () => {
             await mkdir(releasesDir, { recursive: true });
             const spec = await specStore.getSpec(projectId, specId);
-            const latestPublishedAt = await readLatestPublishedReleaseDate(projectPath);
+            const releaseInfo = await resolveLatestReleaseTag(projectPath);
+            const implementationCommit = await captureHeadCommit(projectPath);
             await withPendingReleaseLock(pendingPath, { timeoutMs: 1_500, signal: opts.signal }, async () => {
                 let pendingList = [];
                 try {
@@ -92,16 +98,23 @@ async function actuallyAppendReleasesPending(ctx, opts) {
                     const parsed = JSON.parse(raw);
                     pendingList = normalizePendingReleaseEntries(parsed);
                 }
-                catch {
-                    /* file doesn't exist yet — start fresh */
+                catch (error) {
+                    if (error.code !== 'ENOENT') {
+                        reportClassifiedDegradation('PENDING_RELEASE_LEDGER_UNREADABLE', error);
+                        return;
+                    }
                 }
-                pendingList = reconcilePublishedPendingEntries(pendingList, latestPublishedAt);
+                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 });
+                pendingList.push({
+                    specId,
+                    title: spec?.title ?? specId,
+                    completedAt,
+                    ...(implementationCommit ? { implementationCommit } : {}),
+                });
                 await writePendingReleaseLedger(pendingPath, pendingList);
             });
-            // Auto-commit planu/ changes so pending.json is never left unstaged
             void (async () => {
                 try {
                     const { planuAutoCommit } = await import('../../git/planu-autocommit.js');

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.55",
+  "version": "5.3.57",
   "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.55",
+  "version": "5.3.57",
   "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 {