@planu/cli 5.5.0 → 5.6.0

package/CHANGELOG.md

@@ -1,3 +1,76 @@
+## [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
+- fix: reuse canonical pathExistsStrictByStat and give worktree-list test a real project path
+- fix(SPEC-1682): honor Risks and Test Plan section headings in handoff packager
+- fix(SPEC-1683): close guard bypass, fail-closed pristine check, TOCTOU-safe removal
+- fix(SPEC-1683): git command guard and stray embedded repo self-heal
+
+### Chores
+- chore(planu): SPEC-1685 implementing transition state
+
+
+## [5.5.2] - 2026-08-30
+
+### Bug Fixes
+- fix: reuse canonical pathExistsStrictByStat and give worktree-list test a real project path
+- fix(SPEC-1682): honor Risks and Test Plan section headings in handoff packager
+- fix(SPEC-1683): close guard bypass, fail-closed pristine check, TOCTOU-safe removal
+- fix(SPEC-1683): git command guard and stray embedded repo self-heal
+
+### Chores
+- chore(planu): SPEC-1685 implementing transition state
+
+
+## [5.5.1] - 2026-08-30
+
+### Bug Fixes
+- fix(SPEC-1682): honor Risks and Test Plan section headings in handoff packager
+- fix(SPEC-1683): close guard bypass, fail-closed pristine check, TOCTOU-safe removal
+- fix(SPEC-1683): git command guard and stray embedded repo self-heal
+
+### Chores
+- chore(planu): SPEC-1685 implementing transition state
+
+
 ## [5.5.0] - 2026-08-29
 
 ### Features

package/dist/.planu-build.json

@@ -1 +1 @@
-{"schemaVersion":1,"commit":"2c3e47edf445a0c8422cbeec33a6a929edd764b5"}
+{"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/git/git-command-guard.d.ts

@@ -0,0 +1,2 @@
+export declare function assertSafeGitInvocation(cwd: string, args: readonly string[]): void;
+//# sourceMappingURL=git-command-guard.d.ts.map

package/dist/engine/git/git-command-guard.js

@@ -0,0 +1,43 @@
+import { normalize, sep } from 'node:path';
+const VALUE_TAKING_GLOBAL_OPTIONS = new Set([
+    '-C',
+    '-c',
+    '--config-env',
+    '--exec-path',
+    '--git-dir',
+    '--work-tree',
+    '--namespace',
+    '--super-prefix',
+    '--attr-source',
+    '--list-cmds',
+]);
+const REPO_CREATING_SUBCOMMANDS = new Set(['init', 'clone']);
+function resolveSubcommand(args) {
+    let index = 0;
+    while (index < args.length) {
+        const arg = args[index];
+        if (!arg?.startsWith('-')) {
+            return arg;
+        }
+        if (!arg.includes('=') && VALUE_TAKING_GLOBAL_OPTIONS.has(arg)) {
+            index += 2;
+            continue;
+        }
+        index += 1;
+    }
+    return undefined;
+}
+function cwdTargetsSpecFolder(cwd) {
+    const segments = normalize(cwd).split(sep);
+    return segments.some((segment, i) => segment === 'planu' && segments[i + 1] === 'specs');
+}
+export function assertSafeGitInvocation(cwd, args) {
+    const subcommand = resolveSubcommand(args);
+    if (subcommand !== undefined && REPO_CREATING_SUBCOMMANDS.has(subcommand)) {
+        throw new Error(`Refusing to run repo-creating git subcommand "${subcommand}" (cwd: ${cwd}). Planu's git wrappers never create git repositories.`);
+    }
+    if (cwdTargetsSpecFolder(cwd)) {
+        throw new Error(`Refusing to run git with cwd inside a planu/specs folder (cwd: ${cwd}). Git commands must target the project root, never a spec folder.`);
+    }
+}
+//# sourceMappingURL=git-command-guard.js.map

package/dist/engine/git/planu-autocommit.js

@@ -2,11 +2,13 @@
 import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runAbortableProcess } from '../abortable-process-runner.js';
+import { assertSafeGitInvocation } from './git-command-guard.js';
 export function isPlanuAutocommitEnabled() {
     return process.env.PLANU_ENABLE_AUTOCOMMIT === 'true';
 }
 /** Run git through the request-aware process-group supervisor. */
 async function runGit(cwd, args) {
+    assertSafeGitInvocation(cwd, args);
     const result = await runAbortableProcess('git', args, {
         cwd,
         maxBufferBytes: 1024 * 1024,

package/dist/engine/handoff-packager.js

@@ -484,10 +484,46 @@ function extractLinesByKeywords(content, keywords) {
         .filter((line) => line.length > 0 && !/^#{1,6}\s/.test(line) && keywords.test(line));
     return [...new Set(lines)].slice(0, 12);
 }
+const LIST_ITEM_PATTERN = /^(?:[-*]|\d+\.)\s+(?:\[[ x]\]\s+)?(.+)$/;
+function sectionBullets(content, headingRegex) {
+    const lines = content.split('\n');
+    const bullets = [];
+    let inSection = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (headingRegex.test(trimmed)) {
+            inSection = true;
+            continue;
+        }
+        if (/^#{1,6}\s/.test(trimmed)) {
+            inSection = false;
+            continue;
+        }
+        if (!inSection) {
+            continue;
+        }
+        const match = LIST_ITEM_PATTERN.exec(trimmed);
+        if (match?.[1]) {
+            bullets.push(match[1].trim());
+        }
+    }
+    return bullets;
+}
+function dedupeMerge(primary, fallback) {
+    const seen = new Set();
+    const merged = [];
+    for (const item of [...primary, ...fallback]) {
+        if (!seen.has(item)) {
+            seen.add(item);
+            merged.push(item);
+        }
+    }
+    return merged.slice(0, 12);
+}
 function extractOperationalSections(content, spec) {
     return {
-        testPlan: extractLinesByKeywords(content, /\b(test|typecheck|lint|vitest|playwright|verification|validate|pnpm|npm)\b/i),
-        risks: extractLinesByKeywords(content, /\b(risk|edge|failure|security|drift|migration|breaking|compatibility|rollback)\b/i),
+        testPlan: dedupeMerge(sectionBullets(content, /^#{2,6}\s*test plan\b/i), extractLinesByKeywords(content, /\b(test|typecheck|lint|vitest|playwright|verification|validate|pnpm|npm)\b/i)),
+        risks: dedupeMerge(sectionBullets(content, /^#{2,6}\s*risks?\b/i), extractLinesByKeywords(content, /\b(risk|edge|failure|security|drift|migration|breaking|compatibility|rollback)\b/i)),
         ownership: extractLinesByKeywords(content, /\b(owner|ownership|wave|agent|reviewer|arbiter|files?|responsible)\b/i),
         currentState: `Spec ${spec.id} is ${spec.status}; implementation must follow the approved spec artifact, not chat history.`,
         nextAction: lifecycleNextAction(spec.status),

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