@planu/cli 5.7.2 → 5.7.4

package/CHANGELOG.md

@@ -1,3 +1,21 @@
+## [5.7.4] - 2026-08-31
+
+### Bug Fixes
+- fix(cleanup): run runtime hygiene in report mode and exempt .runtime from offender scans
+- fix(cleanup): ignore planu/.runtime and untrack leaked runtime files in strict cleanup
+
+### Chores
+- chore(runtime): untrack leaked planu runtime state and pin repo-local ignores
+
+
+## [5.7.3] - 2026-08-31
+
+### Bug Fixes
+- fix(release): validate ledger shape before abort version derivation
+- fix(release): fail-closed recovery ledger writer and tolerant abort for corrupted releaseVersion
+- fix(build): report real git failure in provenance stamp and retry transient errors
+
+
 ## [5.7.2] - 2026-08-31
 
 ### Bug Fixes

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"a6e3e4beee6e286f9f7e2e336c4eb14beafe141c"}
+{"schemaVersion":1,"commit":"bae55ef85d50f56c6406a9a52291bdff9fcca4e3"}

package/dist/engine/spec-migrator/drift-detector.js

@@ -3,7 +3,7 @@ import { readdir, stat, access, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isOldFormat } from './lean-migration.js';
 import { fastScanSpecsAsync } from '../core-bridge.js';
-import { isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalSpecFile, } from './planu-canonical-policy.js';
+import { isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isCanonicalSpecFile, isRuntimeHomeRootDir, } from './planu-canonical-policy.js';
 async function scanPlanuRoot(projectPath) {
     const rootFiles = [];
     const planuDir = join(projectPath, 'planu');
@@ -14,7 +14,7 @@ async function scanPlanuRoot(projectPath) {
             try {
                 const info = await stat(fullPath);
                 if (info.isDirectory()) {
-                    if (!isCanonicalPlanuRootDir(entry)) {
+                    if (!isCanonicalPlanuRootDir(entry) && !isRuntimeHomeRootDir(entry)) {
                         rootFiles.push(entry);
                     }
                 }

package/dist/engine/spec-migrator/planu-canonical-policy.d.ts

@@ -2,6 +2,7 @@ import type { PlanuCanonicalPathPolicy } from '../../types/index.js';
 export declare const PLANU_CANONICAL_POLICY: PlanuCanonicalPathPolicy;
 export declare function isCanonicalPlanuRootFile(name: string): boolean;
 export declare function isCanonicalPlanuRootDir(name: string): boolean;
+export declare function isRuntimeHomeRootDir(name: string): boolean;
 export declare function isCanonicalSpecFile(name: string): boolean;
 export declare function isCanonicalSpecDir(name: string): boolean;
 export declare function mustMergeBeforeDeleteSpecFile(name: string): boolean;

package/dist/engine/spec-migrator/planu-canonical-policy.js

@@ -48,12 +48,18 @@ const ROOT_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalRootDirs);
 const SPEC_FILE_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecFiles);
 const SPEC_DIR_SET = new Set(PLANU_CANONICAL_POLICY.canonicalSpecDirs);
 const LEGACY_MERGE_SET = new Set(PLANU_CANONICAL_POLICY.legacyMergeBeforeDeleteFiles);
+const RUNTIME_HOME_TOP_DIR = PLANU_CANONICAL_POLICY.runtimeHomeDir
+    .replace(/^planu\//, '')
+    .replace(/\/$/, '');
 export function isCanonicalPlanuRootFile(name) {
     return ROOT_FILE_SET.has(name);
 }
 export function isCanonicalPlanuRootDir(name) {
     return ROOT_DIR_SET.has(name);
 }
+export function isRuntimeHomeRootDir(name) {
+    return name === RUNTIME_HOME_TOP_DIR;
+}
 export function isCanonicalSpecFile(name) {
     return SPEC_FILE_SET.has(name);
 }

package/dist/engine/spec-migrator/strict-planu-cleanup.js

@@ -8,7 +8,7 @@ import { dirname, isAbsolute, join, relative } from 'node:path';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
 import { safeUnlink } from './git-aware-fs.js';
 import { scanLegacyArtifacts } from './legacy-classifier.js';
-import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isLegacyReleasePendingFile, isCanonicalSpecDir, isCanonicalSpecFile, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
+import { PLANU_CANONICAL_POLICY, canonicalContractText, isCanonicalPlanuRootDir, isCanonicalPlanuRootFile, isLegacyReleasePendingFile, isCanonicalSpecDir, isCanonicalSpecFile, isRuntimeHomeRootDir, mustMergeBeforeDeleteSpecFile, } from './planu-canonical-policy.js';
 const execFileAsync = promisify(execFile);
 // SPEC-1699: legacy planu/ root files folded into project.json by init_project's
 // migration. Destructive cleanup must never delete them outright — only the
@@ -44,7 +44,6 @@ async function gitRmCached(projectPath, relPath) {
         return;
     }
     try {
-        // This helper is only called for directories from removePath.
         const args = ['rm', '--cached', '--quiet', '--ignore-unmatch', '-r', relPath];
         await execFileAsync('git', args, {
             cwd: projectPath,
@@ -82,6 +81,7 @@ function buildPlanuIgnoreBlock() {
         'planu/data/',
         'planu/state/',
         'planu/.locks/',
+        'planu/.runtime/',
         'planu/specs/**',
         '!planu/specs/**/',
         '!planu/specs/**/spec.md',
@@ -163,16 +163,23 @@ async function shouldDeleteOrphanSpecDir(specDir) {
     // Keeping them without spec.md leaves a permanently non-canonical orphan behind.
     return !entries.includes('spec.md');
 }
+async function runReportModeCleanup(projectPath) {
+    const validation = await validateStrictPlanuLayout(projectPath);
+    const planuExists = existsSync(join(projectPath, 'planu'));
+    const gitignoreUpdated = planuExists ? await updateGitignore(projectPath) : false;
+    const untracked = planuExists ? await untrackRuntimeFiles(projectPath) : [];
+    return {
+        mode: 'report',
+        deleted: [],
+        merged: [],
+        proposed: validation.offenders,
+        gitignoreUpdated,
+        untracked,
+    };
+}
 export async function runStrictPlanuCleanup(projectPath, authority = { mode: 'report' }) {
     if (authority.mode === 'report') {
-        const validation = await validateStrictPlanuLayout(projectPath);
-        return {
-            mode: 'report',
-            deleted: [],
-            merged: [],
-            proposed: validation.offenders,
-            gitignoreUpdated: false,
-        };
+        return runReportModeCleanup(projectPath);
     }
     const result = {
         mode: 'execute',
@@ -180,6 +187,7 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
         merged: [],
         proposed: [],
         gitignoreUpdated: false,
+        untracked: [],
     };
     const planuDir = join(projectPath, 'planu');
     if (!existsSync(planuDir)) {
@@ -189,10 +197,7 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
     for (const entry of entries) {
         const full = join(planuDir, entry);
         const isDir = await pathIsDirectory(full);
-        if (isDir && entry === 'releases') {
-            // SPEC-1699: 'releases' is no longer a canonical root dir, but its
-            // pending.json still needs the dedicated fold-into-project.json
-            // migration below before its directory can be removed.
+        if (isDir && (entry === 'releases' || isRuntimeHomeRootDir(entry))) {
             continue;
         }
         if (isDir && !isCanonicalPlanuRootDir(entry)) {
@@ -236,8 +241,20 @@ export async function runStrictPlanuCleanup(projectPath, authority = { mode: 're
         await walkSpecDirectory(projectPath, full, result);
     }
     result.gitignoreUpdated = await updateGitignore(projectPath);
+    result.untracked = await untrackRuntimeFiles(projectPath);
     return result;
 }
+async function untrackRuntimeFiles(projectPath) {
+    const trackedRuntimeFiles = await listTrackedFiles(projectPath, 'planu/.runtime');
+    if (trackedRuntimeFiles.length === 0) {
+        return trackedRuntimeFiles;
+    }
+    for (const relPath of trackedRuntimeFiles) {
+        await gitRmCached(projectPath, relPath);
+    }
+    const stillTracked = new Set(await listTrackedFiles(projectPath, 'planu/.runtime'));
+    return trackedRuntimeFiles.filter((relPath) => !stillTracked.has(relPath));
+}
 function resolveSpecDirsForValidation(projectPath, specPath) {
     if (!specPath?.trim()) {
         return null;
@@ -253,6 +270,9 @@ export async function validateStrictPlanuLayout(projectPath, options = {}) {
         for (const entry of entries) {
             const full = join(planuDir, entry);
             const isDir = await pathIsDirectory(full);
+            if (isDir && isRuntimeHomeRootDir(entry)) {
+                continue;
+            }
             if ((isDir && !isCanonicalPlanuRootDir(entry)) ||
                 (!isDir && !isCanonicalPlanuRootFile(entry))) {
                 offenders.push(relative(projectPath, full));

package/dist/types/spec-format.d.ts

@@ -82,6 +82,7 @@ export interface StrictPlanuCleanupResult {
     merged: string[];
     proposed: string[];
     gitignoreUpdated: boolean;
+    untracked: string[];
 }
 export interface StrictPlanuValidationResult {
     ok: boolean;

package/package.json

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