@planu/cli 5.5.3 → 5.6.0

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+## [5.6.0] - 2026-08-31
+
+### Features
+- feat(init-project): regenerate conventions.md from folded conventions.json (SPEC-1699)
+- feat(init-project): fold legacy planu/ root artifacts on update (SPEC-1699)
+- feat(init-project): gitignore legacy planu/ root files (SPEC-1699)
+- feat(create-spec): refresh the regenerable spec index after writing spec.md (SPEC-1699)
+- feat(storage): add regenerable spec.md index (SPEC-1699)
+
+### Bug Fixes
+- fix(test): reconcile suites with SPEC-1699 runtime relocation and serialize frozen-lockfile suite
+- fix(storage): classify retention and current-project catch degradations
+- fix(release): require the exact tsgo package dir, not any node_modules content
+- fix(release): drop CI=true from frozen-lockfile install, probe tsgo native package
+- fix(SPEC-1696): accept inline YAML arrays for scenario tests in frontmatter
+- fix(storage): close retention review gaps from Codex CHANGES_REQUIRED
+- fix(storage): enforce retention budgets on runtime storage writers
+- fix(SPEC-1694): report the actual test runner instead of Unknown
+- fix(SPEC-1694): promote framework/database claims only from runtime dependencies
+- fix: parse ordered-list markers in BDD criteria extraction (SPEC-1688)
+- fix: repair release-gate collateral fallout from SPEC-1699 fold (blocker 6 sweep)
+- fix: release.sh repoints version marker to planu/project.json (SPEC-1699 blocker 6)
+- fix: reconcile-release-pending falls back to legacy pending.json (SPEC-1699 blocker 4)
+- fix: legacy-root-migration idempotency and fail-safe malformed handling (SPEC-1699 blocker 3)
+- fix: append-releases fails closed on ledger errors (SPEC-1699 blocker 5)
+- fix: verify spec.md digest at the spec-store read choke point (SPEC-1699 blocker 2)
+- fix(housekeeping): protect planu/.runtime as the canonical runtime home (SPEC-1699)
+- fix: address implementation-review blockers for SPEC-1695 runtime relocation
+- fix: reroute default proposal/export/docs-site outputs to planu/.runtime (SPEC-1695)
+- fix: relocate runtime artifacts to planu/.runtime (SPEC-1695)
+
+### Refactoring
+- refactor(release): fold pending release ledger into planu/project.json (SPEC-1699)
+- refactor: relocate session.json and session-context.md under planu/.runtime (SPEC-1699)
+- refactor: route spec resources through the current-project spec index (SPEC-1699)
+- refactor: canonical planu/ set shrinks to project.json + specs/ (SPEC-1699)
+
+
 ## [5.5.3] - 2026-08-30
 
 ### Bug Fixes

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"5060255598e14cab792b6b5b0d75a077f23fe018"}
+{"schemaVersion":1,"commit":"fa03e03df9ac0a344ac184a06f67f4de5956d0d6"}

package/dist/engine/autopilot/bootstrap.js

@@ -52,7 +52,7 @@ function registerImplementingCascadeListener() {
     });
 }
 // SPEC-649: registerDoneCascadeListener (optimize_context on done) removed — cascade reduced to
-// exactly 2 actions: session.json update + releases/pending.json append.
+// exactly 2 actions: session.json update + project.json releases append.
 /**
  * SPEC-628: Fire-and-forget auto_fix_health on cron:daily.
  * Moved from update_status(done) cascade to reduce latency on done transitions.

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

@@ -35,13 +35,17 @@ export function normalizePendingReleaseEntries(value) {
         throw new Error('Pending release ledger is not an array');
     }
     const deduped = new Map();
+    const preserved = [];
     for (const entry of value) {
         if (!isValidPendingReleaseEntry(entry) || !hasParsableCompletionDate(entry)) {
+            // Unknown/invalid shape: never silently drop ledger data — pass it
+            // through verbatim so a human can inspect and fix it later.
+            preserved.push(entry);
             continue;
         }
         deduped.set(entry.specId, entry);
     }
-    return [...deduped.values()];
+    return [...preserved, ...deduped.values()];
 }
 export function reconcilePublishedPendingEntries(entries, release, isCommitReachable = requireIsCommitReachable) {
     if (!release) {
@@ -78,16 +82,23 @@ async function captureHeadCommit(projectPath) {
         return undefined;
     }
 }
+function extractReleasesField(parsedProject) {
+    return parsedProject !== null &&
+        typeof parsedProject === 'object' &&
+        !Array.isArray(parsedProject)
+        ? parsedProject.releases
+        : undefined;
+}
 async function rewritePendingLedger(input) {
     let pendingList = [];
     try {
-        const raw = await readFile(input.pendingPath, 'utf-8');
-        pendingList = normalizePendingReleaseEntries(JSON.parse(raw));
+        const raw = await readFile(input.projectJsonPath, 'utf-8');
+        pendingList = normalizePendingReleaseEntries(extractReleasesField(JSON.parse(raw)) ?? []);
     }
     catch (error) {
         if (error.code !== 'ENOENT') {
             reportClassifiedDegradation('PENDING_RELEASE_LEDGER_UNREADABLE', error);
-            return;
+            throw error instanceof Error ? error : new Error(String(error));
         }
     }
     pendingList = reconcilePublishedPendingEntries(pendingList, input.releaseInfo, input.isCommitReachable).filter((entry) => entry.specId !== input.specId);
@@ -97,7 +108,7 @@ async function rewritePendingLedger(input) {
         completedAt: new Date().toISOString().substring(0, 10),
         ...(input.implementationCommit ? { implementationCommit: input.implementationCommit } : {}),
     });
-    await input.writePendingReleaseLedger(input.pendingPath, pendingList);
+    await input.writePendingReleaseLedger(input.projectJsonPath, pendingList);
 }
 async function actuallyAppendReleasesPending(ctx, opts) {
     const { projectPath, projectId, specId } = ctx;
@@ -116,19 +127,19 @@ async function actuallyAppendReleasesPending(ctx, opts) {
         return;
     }
     const { isCommitReachable, resolveLatestReleaseTag, withPendingReleaseLock, writePendingReleaseLedger, } = helpers;
-    const releasesDir = join(projectPath, 'planu', 'releases');
-    const pendingPath = join(releasesDir, 'pending.json');
+    const planuDir = join(projectPath, 'planu');
+    const projectJsonPath = join(planuDir, 'project.json');
     await new Promise((resolve, reject) => {
         opts.signal.addEventListener('abort', () => {
             reject(new Error('CoreActionTimeoutError: append-releases-pending timed out'));
         });
         (async () => {
-            await mkdir(releasesDir, { recursive: true });
+            await mkdir(planuDir, { recursive: true });
             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 }, () => rewritePendingLedger({
-                pendingPath,
+            await withPendingReleaseLock(projectJsonPath, { timeoutMs: 1_500, signal: opts.signal }, () => rewritePendingLedger({
+                projectJsonPath,
                 specId,
                 title: spec?.title ?? specId,
                 implementationCommit,
@@ -150,8 +161,7 @@ async function actuallyAppendReleasesPending(ctx, opts) {
             resolve();
         })
             .catch((err) => {
-            void err; // best-effort — surface as result, not throw
-            resolve();
+            reject(err instanceof Error ? err : new Error(String(err)));
         });
     });
 }

package/dist/engine/detection-utils.d.ts

@@ -4,6 +4,7 @@ export { fileExists };
 declare const IGNORE_DIRS: string[];
 export declare function hasAnyFile(basePath: string, patterns: string[]): Promise<boolean>;
 export declare function collectDependencies(projectPath: string): Promise<Set<string>>;
+export declare function collectRuntimeDependencies(projectPath: string): Promise<Set<string>>;
 export declare function loadStackSignatures(): Promise<StackSignatures>;
 export declare function loadArchPatterns(): Promise<ArchPatternsFile>;
 export declare function readJsonFile(filePath: string): Promise<Record<string, unknown> | null>;

package/dist/engine/detection-utils.js

@@ -53,6 +53,17 @@ export async function collectDependencies(projectPath) {
     await collectPhpDeps(projectPath, deps);
     return deps;
 }
+export async function collectRuntimeDependencies(projectPath) {
+    const deps = new Set();
+    await collectNodeRuntimeDeps(projectPath, deps);
+    await collectPythonRequirements(projectPath, deps);
+    await collectPyprojectDeps(projectPath, deps);
+    await collectGoDeps(projectPath, deps);
+    await collectRubyDeps(projectPath, deps);
+    await collectRustDeps(projectPath, deps);
+    await collectPhpRuntimeDeps(projectPath, deps);
+    return deps;
+}
 async function collectNodeDeps(projectPath, deps) {
     try {
         const pkgJson = JSON.parse(await readFile(join(projectPath, 'package.json'), 'utf-8'));
@@ -67,6 +78,17 @@ async function collectNodeDeps(projectPath, deps) {
         // No package.json
     }
 }
+async function collectNodeRuntimeDeps(projectPath, deps) {
+    try {
+        const pkgJson = JSON.parse(await readFile(join(projectPath, 'package.json'), 'utf-8'));
+        for (const dep of Object.keys(pkgJson.dependencies ?? {})) {
+            deps.add(dep);
+        }
+    }
+    catch {
+        // No package.json
+    }
+}
 async function collectPythonRequirements(projectPath, deps) {
     try {
         const content = await readFile(join(projectPath, 'requirements.txt'), 'utf-8');
@@ -181,6 +203,17 @@ async function collectPhpDeps(projectPath, deps) {
         // No composer.json
     }
 }
+async function collectPhpRuntimeDeps(projectPath, deps) {
+    try {
+        const composerJson = JSON.parse(await readFile(join(projectPath, 'composer.json'), 'utf-8'));
+        for (const dep of Object.keys(composerJson.require ?? {})) {
+            deps.add(dep);
+        }
+    }
+    catch {
+        // No composer.json
+    }
+}
 export async function loadStackSignatures() {
     try {
         const configPath = new URL('../config/stack-signatures.json', import.meta.url);

package/dist/engine/doc-generator/portal/index.d.ts

@@ -16,7 +16,7 @@ export { computeVelocity } from './data-aggregators/velocity-aggregator.js';
 export { computeBurndown } from './data-aggregators/burndown-aggregator.js';
 export { detectBottlenecks } from './data-aggregators/bottleneck-detector.js';
 export { computeAccuracy } from './data-aggregators/accuracy-aggregator.js';
-export { scheduleRegeneration, regeneratePages } from './portal-regenerator.js';
+export { scheduleRegeneration, regeneratePages, portalPageOutputPath, } from './portal-regenerator.js';
 export { notifyStoreChange } from './regen-hook.js';
 export { getAffectedPages } from './dirty-flag-map.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/doc-generator/portal/index.js

@@ -19,7 +19,7 @@ export { computeBurndown } from './data-aggregators/burndown-aggregator.js';
 export { detectBottlenecks } from './data-aggregators/bottleneck-detector.js';
 export { computeAccuracy } from './data-aggregators/accuracy-aggregator.js';
 // SPEC-146 — Auto-regeneration on store changes
-export { scheduleRegeneration, regeneratePages } from './portal-regenerator.js';
+export { scheduleRegeneration, regeneratePages, portalPageOutputPath, } from './portal-regenerator.js';
 export { notifyStoreChange } from './regen-hook.js';
 export { getAffectedPages } from './dirty-flag-map.js';
 //# sourceMappingURL=index.js.map

package/dist/engine/doc-generator/portal/portal-regenerator.d.ts

@@ -1,13 +1,18 @@
-import type { StoreType } from '../../../types/portal.js';
+import type { RegeneratedPortalPage, StoreType } from '../../../types/portal.js';
 /**
  * Schedule a debounced regeneration (500 ms window).
  * Multiple calls within the window are coalesced per project.
  */
 export declare function scheduleRegeneration(projectPath: string, changedStores: StoreType[]): void;
+/**
+ * SPEC-1695: Absolute path of a portal page's HTML output, under the
+ * per-project storage-layout cache directory (planu/.runtime/cache).
+ */
+export declare function portalPageOutputPath(projectPath: string, page: RegeneratedPortalPage): string;
 /**
  * Immediately regenerate all portal pages affected by the given store changes.
- * Creates planu/ directory if it does not exist.
- * Returns the list of page keys that were successfully written.
+ * Creates the storage-layout cache directory if it does not exist.
+ * Returns the absolute output paths of the pages that were successfully written.
  * Never throws.
  */
 export declare function regeneratePages(projectPath: string, changedStores: StoreType[]): Promise<string[]>;

package/dist/engine/doc-generator/portal/portal-regenerator.js

@@ -3,6 +3,8 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath } from '../../../storage/base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1699
+import { projectRuntimeDir } from '../../../storage/storage-layout.js';
 import { getAffectedPages } from './dirty-flag-map.js';
 import { withAudit } from '../../../engine/autopilot/audit-logger.js';
 // Debounce state keyed by projectPath to avoid cross-project interference
@@ -30,16 +32,24 @@ export function scheduleRegeneration(projectPath, changedStores) {
     }, 500);
     debounceTimers.set(projectPath, timer);
 }
+/**
+ * SPEC-1695: Absolute path of a portal page's HTML output, under the
+ * per-project storage-layout cache directory (planu/.runtime/cache).
+ */
+export function portalPageOutputPath(projectPath, page) {
+    const filename = page === 'index' ? 'index.html' : `${page}.html`;
+    return join(projectRuntimeDir(projectPath, 'cache'), filename);
+}
 /**
  * Immediately regenerate all portal pages affected by the given store changes.
- * Creates planu/ directory if it does not exist.
- * Returns the list of page keys that were successfully written.
+ * Creates the storage-layout cache directory if it does not exist.
+ * Returns the absolute output paths of the pages that were successfully written.
  * Never throws.
  */
 export async function regeneratePages(projectPath, changedStores) {
-    const planuDir = join(projectPath, 'planu');
+    const cacheDir = projectRuntimeDir(projectPath, 'cache');
     try {
-        await mkdir(planuDir, { recursive: true });
+        await mkdir(cacheDir, { recursive: true });
     }
     catch {
         return [];
@@ -51,10 +61,9 @@ export async function regeneratePages(projectPath, changedStores) {
             await withAudit(projectPath, 'portal_regeneration', `regeneratePage(${page})`, async () => {
                 const html = await generatePage(projectPath, page);
                 if (html) {
-                    const filename = page === 'index' ? 'index.html' : `${page}.html`;
-                    const filePath = join(planuDir, filename);
+                    const filePath = portalPageOutputPath(projectPath, page);
                     await writeFile(filePath, html, 'utf-8');
-                    regenerated.push(page);
+                    regenerated.push(filePath);
                 }
             });
         }

package/dist/engine/evidence-gates/evidence-autofill.d.ts

@@ -1,6 +1,6 @@
 import type { AutofillTraceabilityMatrixArgs, AutofillTraceabilityMatrixResult } from '../../types/evidence-autofill.js';
 /** Exact Planu lifecycle files every spec branch mutates; never counted as implementation drift. */
-export declare const PLANU_BOOKKEEPING_FILES: readonly ['planu/context.md', 'planu/session-context.md', 'planu/session.json', 'planu/status.json', 'planu/releases/pending.json', 'planu/conventions.json'];
+export declare const PLANU_BOOKKEEPING_FILES: readonly ['planu/context.md', 'planu/session-context.md', 'planu/session.json', 'planu/status.json', 'planu/project.json', 'planu/conventions.json'];
 /** Normalizes a spec.md path (absolute or already repo-relative) to a repo-relative,
  * forward-slash path so it can be compared against `git diff` output. */
 export declare function toRepoRelativePath(specPath: string, projectPath?: string): string;

package/dist/engine/evidence-gates/evidence-autofill.js

@@ -42,7 +42,7 @@ export const PLANU_BOOKKEEPING_FILES = [
     'planu/session-context.md',
     'planu/session.json',
     'planu/status.json',
-    'planu/releases/pending.json',
+    'planu/project.json',
     'planu/conventions.json',
 ];
 const OTHER_SPEC_MD_PATTERN = /^planu\/specs\/[^/]+\/spec\.md$/;

package/dist/engine/framework-detector.js

@@ -1,7 +1,7 @@
 import { technologyValue } from './technology-registry.js';
 // Planu — Framework, ORM, and database detection
 import { join } from 'node:path';
-import { fileExists, hasAnyFile, collectDependencies, readJsonFile } from './detection-utils.js';
+import { fileExists, hasAnyFile, collectDependencies, collectRuntimeDependencies, readJsonFile, } from './detection-utils.js';
 /**
  * Detect the primary framework from indicator files and dependencies.
  */
@@ -14,8 +14,9 @@ export async function detectFramework(projectPath, signatures) {
             }
         }
     }
-    // Check dependencies
-    const deps = await collectDependencies(projectPath);
+    // Check runtime dependencies only — a framework declared solely in
+    // devDependencies is tooling, not the project's runtime stack.
+    const deps = await collectRuntimeDependencies(projectPath);
     for (const [fw, sig] of Object.entries(signatures.frameworks)) {
         for (const dep of sig.dependencies) {
             if (deps.has(dep)) {
@@ -55,9 +56,9 @@ export async function detectFrameworkVersion(projectPath, framework, signatures)
  * Detect the database engine from indicator files and dependencies.
  */
 export async function detectDatabase(projectPath, signatures) {
-    const deps = await collectDependencies(projectPath);
+    const deps = await collectRuntimeDependencies(projectPath);
     for (const [, sig] of Object.entries(signatures.databases)) {
-        // Check indicator files
+        // Check indicator files (migration dirs, connection configs)
         for (const indicator of sig.indicators) {
             if (await hasAnyFile(projectPath, [indicator])) {
                 if (isKnownEngine(sig.engine)) {
@@ -65,7 +66,8 @@ export async function detectDatabase(projectPath, signatures) {
                 }
             }
         }
-        // Check dependencies
+        // Check runtime dependencies only — a driver declared solely in
+        // devDependencies never produces a Database claim.
         for (const dep of sig.dependencies) {
             if (deps.has(dep)) {
                 if (isKnownEngine(sig.engine)) {

package/dist/engine/housekeeping/history-log.d.ts

@@ -1,4 +1,5 @@
 import type { HousekeepingHistoryEntry } from '../../types/housekeeping.js';
 export declare function housekeepingHistoryPath(projectPath: string): string;
+export declare function migrateLegacyHousekeepingHistory(projectPath: string): Promise<string | null>;
 export declare function appendHousekeepingEntry(projectPath: string, input: Omit<HousekeepingHistoryEntry, 'id' | 'deletedAt' | 'prevSha' | 'sha256'>): Promise<HousekeepingHistoryEntry>;
 //# sourceMappingURL=history-log.d.ts.map

package/dist/engine/housekeeping/history-log.js

@@ -1,14 +1,68 @@
 // engine/housekeeping/history-log.ts — SPEC-751
 // Hash-chained JSONL backup log for deleted housekeeping items.
 // Mirrors the SPEC-723/734 transition-log pattern for recoverability.
+import { existsSync } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
-import { appendFile, readFile, mkdir } from 'node:fs/promises';
+import { appendFile, readFile, mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1699
+import { projectRuntimeDir } from '../../storage/storage-layout.js';
 // ---------------------------------------------------------------------------
-// Path helper
+// Path helpers
 // ---------------------------------------------------------------------------
+const HISTORY_FILENAME = '.housekeeping-history.jsonl';
 export function housekeepingHistoryPath(projectPath) {
-    return join(projectPath, 'planu', '.housekeeping-history.jsonl');
+    return join(projectRuntimeDir(projectPath, 'state'), HISTORY_FILENAME);
+}
+function legacyHousekeepingHistoryPath(projectPath) {
+    return join(projectPath, 'planu', HISTORY_FILENAME);
+}
+/**
+ * SPEC-1695: One-time migration of the legacy planu/.housekeeping-history.jsonl
+ * into the storage-layout location. Copies content, verifies it round-tripped,
+ * then deletes the legacy file. Idempotent — a missing legacy file or an
+ * already-populated new file is a no-op.
+ * Returns the legacy path when a migration happened, otherwise null.
+ */
+function entryId(line) {
+    try {
+        return JSON.parse(line).id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function jsonlLines(content) {
+    return content.split('\n').filter((line) => line.trim().length > 0);
+}
+export async function migrateLegacyHousekeepingHistory(projectPath) {
+    const legacyPath = legacyHousekeepingHistoryPath(projectPath);
+    const newPath = housekeepingHistoryPath(projectPath);
+    if (!existsSync(legacyPath)) {
+        return null;
+    }
+    const legacyContent = await readFile(legacyPath, 'utf-8');
+    if (!existsSync(newPath)) {
+        await mkdir(dirname(newPath), { recursive: true });
+        await writeFile(newPath, legacyContent, 'utf-8');
+        const verified = await readFile(newPath, 'utf-8');
+        if (verified !== legacyContent) {
+            throw new Error('[Planu] housekeeping history migration verification failed');
+        }
+        await rm(legacyPath, { force: true });
+        return legacyPath;
+    }
+    const destinationContent = await readFile(newPath, 'utf-8');
+    const destinationIds = new Set(jsonlLines(destinationContent).map(entryId));
+    const missingLines = jsonlLines(legacyContent).filter((line) => {
+        const id = entryId(line);
+        return id === null || !destinationIds.has(id);
+    });
+    if (missingLines.length > 0) {
+        await appendFile(newPath, missingLines.map((line) => `${line}\n`).join(''), 'utf-8');
+    }
+    await rm(legacyPath, { force: true });
+    return legacyPath;
 }
 // ---------------------------------------------------------------------------
 // Hash chain helpers
@@ -47,6 +101,7 @@ async function readLastSha(filePath) {
     }
 }
 async function doAppend(filePath, input) {
+    await migrateLegacyHousekeepingHistory(input.projectPath);
     await mkdir(dirname(filePath), { recursive: true });
     const prevSha = await readLastSha(filePath);
     const partial = {

package/dist/engine/housekeeping/index.d.ts

@@ -2,7 +2,8 @@ export { findStaleBranches } from './find-stale-branches.js';
 export { findStaleWorktrees } from './find-stale-worktrees.js';
 export { findStaleStashes } from './find-stale-stashes.js';
 export { runHousekeepingSweep } from './sweep-runner.js';
-export { appendHousekeepingEntry, housekeepingHistoryPath } from './history-log.js';
+export { appendHousekeepingEntry, housekeepingHistoryPath, migrateLegacyHousekeepingHistory, } from './history-log.js';
+export { sweepRuntimeResidue } from './runtime-residue-sweep.js';
 export { cleanOrphanBrainstormingMarkdowns } from './orphan-brainstorming-cleaner.js';
 export { cleanEphemeralArtifacts } from './ephemeral-artifacts-cleaner.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/housekeeping/index.js

@@ -4,7 +4,8 @@ export { findStaleBranches } from './find-stale-branches.js';
 export { findStaleWorktrees } from './find-stale-worktrees.js';
 export { findStaleStashes } from './find-stale-stashes.js';
 export { runHousekeepingSweep } from './sweep-runner.js';
-export { appendHousekeepingEntry, housekeepingHistoryPath } from './history-log.js';
+export { appendHousekeepingEntry, housekeepingHistoryPath, migrateLegacyHousekeepingHistory, } from './history-log.js';
+export { sweepRuntimeResidue } from './runtime-residue-sweep.js';
 export { cleanOrphanBrainstormingMarkdowns } from './orphan-brainstorming-cleaner.js';
 export { cleanEphemeralArtifacts } from './ephemeral-artifacts-cleaner.js';
 //# sourceMappingURL=index.js.map

package/dist/engine/housekeeping/runtime-residue-sweep.d.ts

@@ -0,0 +1,9 @@
+import type { RuntimeResidueSweepResult } from '../../types/housekeeping.js';
+/**
+ * Delete every legacy runtime-residue path from planu/ without ever touching
+ * canonicalRootFiles / canonicalRootDirs. Idempotent — a checkout with no
+ * residue returns an empty removed list. Wired into init_project and the
+ * session-start housekeeping path so existing client checkouts self-heal.
+ */
+export declare function sweepRuntimeResidue(projectPath: string): Promise<RuntimeResidueSweepResult>;
+//# sourceMappingURL=runtime-residue-sweep.d.ts.map

package/dist/engine/housekeeping/runtime-residue-sweep.js

@@ -0,0 +1,57 @@
+// engine/housekeeping/runtime-residue-sweep.ts — SPEC-1695
+// Removes legacy runtime artifacts that PLANU_CANONICAL_POLICY already
+// classifies as regenerable (generatedRuntimePatterns), so a client checkout
+// self-heals on init_project / session start instead of accumulating residue.
+import { rm } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { glob } from 'glob';
+import { PLANU_CANONICAL_POLICY, isCanonicalPlanuRootFile, } from '../spec-migrator/planu-canonical-policy.js';
+import { migrateLegacyHousekeepingHistory } from './history-log.js';
+const HOUSEKEEPING_HISTORY_PATTERN = 'planu/.housekeeping-history.jsonl';
+const RUNTIME_HOME_TOP_DIR = PLANU_CANONICAL_POLICY.runtimeHomeDir
+    .replace(/^planu\//, '')
+    .replace(/\/$/, '');
+function isProtectedPath(planuDir, absolutePath) {
+    const rel = relative(planuDir, absolutePath);
+    if (rel === '' || rel.startsWith('..')) {
+        return true;
+    }
+    const top = rel.split(sep)[0] ?? '';
+    if (isCanonicalPlanuRootFile(top)) {
+        return true;
+    }
+    return top === RUNTIME_HOME_TOP_DIR || rel === 'releases' || rel === 'specs';
+}
+async function removeMatches(projectPath, pattern) {
+    const planuDir = join(projectPath, 'planu');
+    const relativePattern = pattern.replace(/^planu\//, '').replace(/\/$/, '');
+    const matches = await glob(relativePattern, { cwd: planuDir, dot: true, absolute: true });
+    const removed = [];
+    for (const absolutePath of matches) {
+        if (isProtectedPath(planuDir, absolutePath)) {
+            continue;
+        }
+        await rm(absolutePath, { recursive: true, force: true });
+        removed.push(absolutePath);
+    }
+    return removed;
+}
+/**
+ * Delete every legacy runtime-residue path from planu/ without ever touching
+ * canonicalRootFiles / canonicalRootDirs. Idempotent — a checkout with no
+ * residue returns an empty removed list. Wired into init_project and the
+ * session-start housekeeping path so existing client checkouts self-heal.
+ */
+export async function sweepRuntimeResidue(projectPath) {
+    const removed = [];
+    const patterns = PLANU_CANONICAL_POLICY.generatedRuntimePatterns.filter((pattern) => pattern !== HOUSEKEEPING_HISTORY_PATTERN);
+    for (const pattern of patterns) {
+        removed.push(...(await removeMatches(projectPath, pattern)));
+    }
+    const migratedHistoryPath = await migrateLegacyHousekeepingHistory(projectPath);
+    if (migratedHistoryPath) {
+        removed.push(migratedHistoryPath);
+    }
+    return { removed };
+}
+//# sourceMappingURL=runtime-residue-sweep.js.map

package/dist/engine/next-spec-resolver/orchestration-planner.js

@@ -196,7 +196,7 @@ function normalizeLegacyTier(value) {
 }
 async function readPlanVersion(projectPath) {
     try {
-        const raw = await readFile(join(projectPath, 'planu', 'session.json'), 'utf-8');
+        const raw = await readFile(join(projectPath, 'planu', '.runtime', 'session.json'), 'utf-8');
         const index = JSON.parse(raw);
         return index.orchestrationPlan?.planVersion ?? 0;
     }

package/dist/engine/next-spec-resolver/session-writer.js

@@ -68,7 +68,7 @@ export async function writeOrchestrationPlan(projectPath, plan) {
  */
 export async function patchSessionJson(projectPath, patch) {
     try {
-        const filePath = join(projectPath, 'planu', 'session.json');
+        const filePath = join(projectPath, 'planu', '.runtime', 'session.json');
         let existingContent = null;
         let current = { activeSpecs: [], updatedAt: '' };
         try {

package/dist/engine/project-graph/cache.js

@@ -8,6 +8,8 @@ import { setTimeout as delay } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { projectDataDir, readJson, writeJson } from '../../storage/base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
+import { enforceRetention } from '../../storage/retention.js';
 import { LockBusyError, withSpecLock } from '../safety/cross-process-lock.js';
 const POLICY_PATH = join(dirname(fileURLToPath(import.meta.url)), '../../config/project-knowledge-graph.json');
 const CACHE_VERSION = 2;
@@ -200,7 +202,13 @@ export async function readProjectGraph(projectId, policy) {
     return null;
 }
 export async function writeProjectGraph(projectId, policy, graph) {
-    await writeJson(projectGraphPath(projectId, policy), graph);
+    const graphPath = projectGraphPath(projectId, policy);
+    await writeJson(graphPath, graph);
+    await enforceRetention({
+        kind: 'graph-cache',
+        path: projectGraphDir(projectId, policy),
+        protectedPaths: [graphPath],
+    });
 }
 export async function readProjectGraphSourceHashes(projectId, policy) {
     const active = activeBuilds.get(projectGraphDir(projectId, policy));
@@ -217,6 +225,11 @@ export async function writeProjectGraphSourceHashes(projectId, policy, hashes) {
         records: hashes,
         fragments: current.cache?.fragments ?? {},
     });
+    await enforceRetention({
+        kind: 'graph-cache',
+        path: projectGraphDir(projectId, policy),
+        protectedPaths: [projectGraphCachePath(projectId, policy)],
+    });
 }
 export async function writeProjectGraphArtifacts(args) {
     if (args.graph.generation.length === 0 ||
@@ -225,8 +238,15 @@ export async function writeProjectGraphArtifacts(args) {
         throw new Error('[Planu] Project graph/cache generation mismatch');
     }
     // Readers verify the shared generation, so neither write order can expose a mixed snapshot.
-    await writeJson(projectGraphCachePath(args.projectId, args.policy), args.cache);
-    await writeJson(projectGraphPath(args.projectId, args.policy), args.graph);
+    const cachePath = projectGraphCachePath(args.projectId, args.policy);
+    const graphPath = projectGraphPath(args.projectId, args.policy);
+    await writeJson(cachePath, args.cache);
+    await writeJson(graphPath, args.graph);
+    await enforceRetention({
+        kind: 'graph-cache',
+        path: projectGraphDir(args.projectId, args.policy),
+        protectedPaths: [cachePath, graphPath],
+    });
 }
 export async function withProjectGraphBuildLock(projectId, policy, task) {
     const key = projectGraphDir(projectId, policy);

package/dist/engine/readiness-checker.js

@@ -428,7 +428,7 @@ export async function checkSpecReadiness(spec, mode, projectHash) {
     if (bddScenarioCount > 0) {
         const scenariosWithoutTests = findScenariosWithoutTests(huRaw);
         for (const title of scenariosWithoutTests) {
-            allBlockers.push(`scenarios_missing_tests: scenario "${title}" has no tests array — add tests entries (SPEC-732)`);
+            allBlockers.push(`scenarios_missing_tests: scenario "${title}" has no tests array — add tests entries as a block list (tests: with one "- path" line per test) or an inline array (tests: ["path"]) (SPEC-732)`);
         }
     }
     // SPEC-1214: BDD-criteria executable-evidence gate — when a spec has no frontmatter