@planu/cli 5.5.3 → 5.6.0

package/dist/tools/challenge-spec.js

@@ -172,15 +172,7 @@ export async function handleChallengeSpec(args, server) {
     if (!projectId) {
         return missingProjectIdError;
     }
-    // 1. Load spec
-    const spec = await specStore.getSpec(projectId, specId);
-    if (!spec) {
-        return {
-            content: [{ type: 'text', text: ti('spec.notFound', { id: specId }) }],
-            isError: true,
-        };
-    }
-    // 2. Load project knowledge — SPEC-1011 Bug F: use disk fingerprint fallback
+    // 1. Load project knowledge — SPEC-1011 Bug F: use disk fingerprint fallback
     let knowledge = await knowledgeStore.getKnowledge(projectId);
     if (!knowledge && args.projectPath) {
         const resolved = await resolveProjectFromPath(args.projectPath);
@@ -194,6 +186,15 @@ export async function handleChallengeSpec(args, server) {
             isError: true,
         };
     }
+    // 2. Load spec — SPEC-1699: pass canonicalRoot so a stale specs.json record
+    // (e.g. spec.md hand-edited after the last write) is refreshed on read.
+    const spec = await specStore.getSpec(projectId, specId, knowledge.projectPath);
+    if (!spec) {
+        return {
+            content: [{ type: 'text', text: ti('spec.notFound', { id: specId }) }],
+            isError: true,
+        };
+    }
     // 2b. Load Constitution for compliance context
     const constitution = await knowledgeStore.getConstitution(projectId);
     // 3. Read spec content

package/dist/tools/create-spec.js

@@ -2,6 +2,7 @@ import { checkGate } from '../engine/clarification-gate/gate.js';
 import { upsertToken, hashQuestions } from '../engine/clarification-gate/token-store.js';
 import { ti } from '../i18n/index.js';
 import { knowledgeStore, specStore } from '../storage/index.js';
+import { loadSpecIndex } from '../storage/spec-index.js';
 import { readTechnologySelectionContract } from '../storage/technology-selection-store.js';
 import { toolResult, interactiveResult } from './response-helpers.js';
 import { readFile, stat as fsStat } from 'node:fs/promises';
@@ -9,6 +10,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { pathExistsByStat as pathExists } from '../core/shared/fs.js';
 import { basename as pathBasename, dirname as pathDirname, isAbsolute as pathIsAbsolute, join as pathJoin, relative as pathRelative, sep as pathSeparator, } from 'node:path';
 import { withFileLock } from '../storage/file-mutex.js';
+import { enforceRetention } from '../storage/retention.js';
 import { generateBranchName } from './create-spec-helpers.js';
 import { buildSpecContext, buildSplitResult, computeNextSpecId, } from './create-spec/spec-builder.js';
 import { validateConstitution } from './create-spec/constitution-validator.js';
@@ -635,6 +637,7 @@ async function commitIdempotencyEvidence(projectPath, key, claim, spec, specPath
         await executionWriteFileExclusive(evidencePath, JSON.stringify(evidence, null, 2), {
             encoding: 'utf-8',
         });
+        await enforceRetention({ kind: 'idempotency', path: pathDirname(evidencePath) });
     }
     catch (error) {
         if (error.code !== 'EEXIST') {
@@ -1688,6 +1691,13 @@ export async function handleCreateSpec(inputParams, server) {
                             }
                             await measureStep('specStore-createSpec', () => specStore.createSpec(projectId, spec));
                             storeCreated = true;
+                            // SPEC-1699: refresh the regenerable spec.md index cache file.
+                            // Best-effort — specStore.getSpec/listSpecs independently verify
+                            // spec.md's digest on every read that supplies canonicalRoot, so
+                            // a failed refresh here only lags this cache file, not a caller.
+                            await loadSpecIndex(resolvedPath).catch(() => {
+                                /* best-effort */
+                            });
                             assertExecutionCanCommit(criticalSignal);
                             await measureStep('commit-idempotency-evidence', () => commitIdempotencyEvidence(resolvedPath, idempotencyKey, idempotencyClaim, spec, specPath));
                             operationJournal.commitWithOutbox('create_spec', operationKey, committedResult, {

package/dist/tools/execute-sdd-flow.js

@@ -48,9 +48,18 @@ export async function handleExecuteSddFlow(args) {
     if (specIds.length === 0 && !args.resumeFrom) {
         return compactError('specIds is required when not resuming. Provide at least one approved spec ID.');
     }
-    let state = args.resumeFrom ? await loadCheckpoint(projectPath, args.resumeFrom) : null;
+    let state = null;
+    if (args.resumeFrom) {
+        try {
+            state = await loadCheckpoint(projectPath, args.resumeFrom);
+        }
+        catch (error) {
+            return compactError(error instanceof Error ? error.message : String(error));
+        }
+    }
     if (args.resumeFrom && !state) {
-        return compactError(`Run state not found for runId: ${args.resumeFrom}. Check planu/state/ directory.`);
+        return compactError(`Run state not found for runId: ${args.resumeFrom}. ` +
+            'Checked planu/.runtime/state/ and legacy planu/state/.');
     }
     if (!state) {
         const runId = randomUUID();

package/dist/tools/export-spec.js

@@ -8,6 +8,7 @@ import { stripFrontmatter } from '../engine/frontmatter-parser.js';
 import { specToAgentReady, serializeAgentReady } from '../engine/agent-ready-exporter.js';
 import { assertPathWithinBase } from '../engine/safety/assert-within-project.js';
 import { compactResult, formatKeyValue } from './output-formatter.js';
+import { projectRuntimeDir } from '../storage/storage-layout.js';
 async function readFileContent(filePath) {
     try {
         const raw = await readFile(filePath, 'utf-8');
@@ -122,7 +123,7 @@ export async function handleExportSpec(params) {
     });
     // Write to output directory
     const slug = toSlug(spec.title);
-    const outputDir = params.outputDir ?? join(params.projectPath, 'planu', 'exports', slug);
+    const outputDir = params.outputDir ?? join(projectRuntimeDir(params.projectPath, 'reports'), 'exports', slug);
     let resolvedOutput;
     try {
         resolvedOutput = assertPathWithinBase(params.projectPath, outputDir);

package/dist/tools/force-status-analytics.js

@@ -4,6 +4,7 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { readForceAnalytics } from '../storage/force-analytics-store.js';
 import { resolveProjectPath } from '../storage/path-resolver.js';
 import { hashProjectPath } from '../storage/base-store.js';
+import { projectRuntimeDir } from '../storage/storage-layout.js';
 function buildMarkdownReport(projectPath, entries, stats) {
     const lines = [
         '# Quality Exceptions Report',
@@ -42,7 +43,7 @@ export async function handleForceStatusAnalytics(params) {
     let reportPath = null;
     if (generateReport) {
         try {
-            const reportDir = join(projectPath, 'planu', 'reports');
+            const reportDir = projectRuntimeDir(projectPath, 'reports');
             await mkdir(reportDir, { recursive: true });
             reportPath = join(reportDir, 'quality-exceptions.md');
             const markdown = buildMarkdownReport(projectPath, analytics.forcedTransitions, analytics.stats);

package/dist/tools/generate-docs-site.js

@@ -2,6 +2,7 @@ import { join } from 'node:path';
 import { rm, access } from 'node:fs/promises';
 import { generateDocsSite } from '../engine/docs-site-generator/index.js';
 import { compactResult } from './output-formatter.js';
+import { projectRuntimeDir } from '../storage/storage-layout.js';
 async function removeMisplacedDocsSite(projectPath) {
     const stale = join(projectPath, 'docs-site');
     try {
@@ -17,7 +18,7 @@ export async function handleGenerateDocsSite(params) {
     const removed = await removeMisplacedDocsSite(params.projectPath);
     const config = {
         projectPath: params.projectPath,
-        outputDir: join(params.projectPath, 'planu', 'docs-site'),
+        outputDir: join(projectRuntimeDir(params.projectPath, 'cache'), 'docs-site'),
         title: params.title,
     };
     const result = await generateDocsSite(config);

package/dist/tools/generate-proposal.js

@@ -6,6 +6,7 @@ import { hashProjectPath, projectDataDir } from '../storage/base-store.js';
 import { specStore, knowledgeStore, decisionStore, metricsStore } from '../storage/index.js';
 import { loadAllRiskRegisters } from '../storage/risk-store.js';
 import { generateProposal } from '../engine/doc-generator/proposal/proposal-generator.js';
+import { projectRuntimeDir } from '../storage/storage-layout.js';
 import { SpecIdSchema } from './schemas/index.js';
 // ── Zod schema ────────────────────────────────────────────────────────────────
 const PhaseSchema = z.object({
@@ -131,8 +132,11 @@ async function handleGenerateProposal(args) {
     };
     const html = generateProposal(proposalData);
     // Resolve output path
-    const relOutput = args.outputPath ?? 'planu/proposal.html';
-    const outputFilePath = isAbsolute(relOutput) ? relOutput : join(args.projectPath, relOutput);
+    const outputFilePath = args.outputPath
+        ? isAbsolute(args.outputPath)
+            ? args.outputPath
+            : join(args.projectPath, args.outputPath)
+        : join(projectRuntimeDir(args.projectPath, 'reports'), 'proposal.html');
     await mkdir(dirname(outputFilePath), { recursive: true });
     await writeFile(outputFilePath, html, 'utf-8');
     const sizeKb = Math.round(html.length / 1024);

package/dist/tools/init-project/claude-md-generator.js

@@ -116,7 +116,7 @@ function buildArchitecture(knowledge) {
     } // only monorepo=No is not useful alone
     return wrap('architecture', `## Architecture\n${items.join('\n')}`);
 }
-function detectTestFramework(testCommand) {
+function detectTestFrameworkFromCommand(testCommand) {
     if (testCommand.includes(technologyValue('technology-vitest-a9127f'))) {
         return technologyValue('technology-vitest-7fc39e');
     }
@@ -143,11 +143,28 @@ function detectTestFramework(testCommand) {
     }
     return 'Unknown';
 }
+const TOOLING_TEST_FRAMEWORK_LABELS = {
+    [technologyValue('technology-vitest-a9127f')]: technologyValue('technology-vitest-7fc39e'),
+    [technologyValue('technology-jest-35e99f')]: technologyValue('technology-jest-1f30f0'),
+    mocha: 'Mocha',
+    [technologyValue('technology-pytest-2b0121')]: technologyValue('technology-pytest-2b0121'),
+    'cargo-test': 'cargo test',
+};
+function detectTestFramework(knowledge, testCommand) {
+    const toolingTesting = knowledge.tooling.testing;
+    if (toolingTesting) {
+        const label = TOOLING_TEST_FRAMEWORK_LABELS[toolingTesting];
+        if (label) {
+            return label;
+        }
+    }
+    return detectTestFrameworkFromCommand(testCommand);
+}
 function buildTesting(knowledge) {
     if (!knowledge.testCommand) {
         return null;
     }
-    const framework = detectTestFramework(knowledge.testCommand);
+    const framework = detectTestFramework(knowledge, knowledge.testCommand);
     const items = [
         `- **Framework**: ${framework}`,
         `- **Command**: \`${knowledge.testCommand}\``,

package/dist/tools/init-project/conventions-writer.d.ts

@@ -1,8 +1,11 @@
 import type { ProjectKnowledge } from '../../types/index.js';
+export type ConventionsSource = Pick<ProjectKnowledge, 'stack' | 'language' | 'framework' | 'projectPath'>;
 /**
  * SPEC-530: Write .claude/rules/conventions.md if missing.
  * Generates project-specific conventions from detected knowledge.
- * @returns true if file was created, false if it already existed.
+ * SPEC-1699: pass force=true to regenerate even when the file already exists,
+ * e.g. after migrateLegacyPlanuRoot folds conventions.json into project.json.
+ * @returns true if the file was written, false if it already existed and force was false.
  */
-export declare function generateConventionsMdIfMissing(projectPath: string, knowledge: ProjectKnowledge): Promise<boolean>;
+export declare function generateConventionsMdIfMissing(projectPath: string, knowledge: ConventionsSource, force?: boolean): Promise<boolean>;
 //# sourceMappingURL=conventions-writer.d.ts.map

package/dist/tools/init-project/conventions-writer.js

@@ -33,21 +33,26 @@ function buildConventionsContent(knowledge) {
 /**
  * SPEC-530: Write .claude/rules/conventions.md if missing.
  * Generates project-specific conventions from detected knowledge.
- * @returns true if file was created, false if it already existed.
+ * SPEC-1699: pass force=true to regenerate even when the file already exists,
+ * e.g. after migrateLegacyPlanuRoot folds conventions.json into project.json.
+ * @returns true if the file was written, false if it already existed and force was false.
  */
-export async function generateConventionsMdIfMissing(projectPath, knowledge) {
+export async function generateConventionsMdIfMissing(projectPath, knowledge, force = false) {
     const conventionsPath = join(projectPath, CONVENTIONS_MD_PATH);
-    try {
-        await access(conventionsPath);
-        return false;
-    }
-    catch {
-        const rulesDir = join(projectPath, '.claude/rules');
-        await mkdir(rulesDir, { recursive: true });
-        const content = buildConventionsContent(knowledge);
-        assertEnglishOnlyArtifactText(content, 'rule');
-        await writeFile(conventionsPath, content, 'utf-8');
-        return true;
+    if (!force) {
+        try {
+            await access(conventionsPath);
+            return false;
+        }
+        catch {
+            /* file absent — fall through and write it */
+        }
     }
+    const rulesDir = join(projectPath, '.claude/rules');
+    await mkdir(rulesDir, { recursive: true });
+    const content = buildConventionsContent(knowledge);
+    assertEnglishOnlyArtifactText(content, 'rule');
+    await writeFile(conventionsPath, content, 'utf-8');
+    return true;
 }
 //# sourceMappingURL=conventions-writer.js.map

package/dist/tools/init-project/git-setup.js

@@ -113,6 +113,7 @@ async function configureGitignore(projectPath) {
 }
 function buildPlanuIgnoreBlock() {
     return [
+        'planu/.runtime/',
         'planu/*.html',
         'planu/status.json',
         'planu/CHANGELOG.md',
@@ -122,6 +123,14 @@ function buildPlanuIgnoreBlock() {
         'planu/data/',
         'planu/state/',
         'planu/.locks/',
+        // SPEC-1699: legacy root files/dir folded into project.json by init_project's
+        // migration — ignored so a transitional checkout never re-commits them.
+        'planu/conventions.json',
+        'planu/context.md',
+        'planu/session-context.md',
+        'planu/session.json',
+        'planu/technology-selection.json',
+        'planu/releases/',
         'planu/specs/**',
         '!planu/specs/**/',
         '!planu/specs/**/spec.md',

package/dist/tools/init-project/handler.js

@@ -46,6 +46,8 @@ import { reconcileInteractiveQuestionHooks } from '../reconcile-interactive-ques
 import { installSessionSafeguardHook } from '../reconcile-session-safeguard-hook.js';
 import { resolveNewProjectOnboarding } from '../../engine/onboarding/new-project-resolver.js';
 import { interactiveResult } from '../response-helpers.js';
+import { scheduleRuntimeResidueSweep } from './runtime-residue.js';
+import { resolveLegacyMigration } from './legacy-root-migration.js';
 /** Frontend framework groups — mutually exclusive. Two or more detected → multi-stack conflict. */
 const FRONTEND_FRAMEWORK_GROUPS = [
     [
@@ -213,6 +215,11 @@ export async function handleInitProject(params, server) {
             // Check if project is already initialized
             const existing = await knowledgeStore.getKnowledge(projectId);
             const isUpdate = hadProjectIdentity || existing !== null;
+            // SPEC-1699: fold legacy planu/ root artifacts before the sweep below runs.
+            const legacyMigration = await resolveLegacyMigration(isUpdate, projectPath);
+            // SPEC-1699: Sweep runtime residue on every init_project run, including the
+            // already-initialized early-return path below — not just the fresh-init path.
+            scheduleRuntimeResidueSweep(projectPath);
             const authorizedMigrations = params.authorizedMigrations ?? [];
             if (isUpdate && authorizedMigrations.length === 0) {
                 const reconciliation = await reconcilePortableSpecIndex(projectPath, projectId);
@@ -234,6 +241,7 @@ export async function handleInitProject(params, server) {
                         failures: reconciliation.failures,
                         skippedLegacy: reconciliation.skippedLegacy,
                         strayRepoRemovals: reconciliation.strayRepoRemovals,
+                        migratedLegacyPaths: legacyMigration.migrated,
                     },
                     ...(reconciliation.failures.length > 0 ? { isError: true } : {}),
                 };
@@ -463,7 +471,7 @@ export async function handleInitProject(params, server) {
                 /* best-effort */
             });
             // SPEC-193: Generate portal pages (fire-and-forget)
-            void withAudit(projectPath, 'init_project', 'regeneratePages', () => regeneratePages(projectPath, ['knowledge', 'risks', 'decisions']), (pages) => ({ pages: pages.length })).catch(() => {
+            void withAudit(projectPath, 'init_project', 'regeneratePages', () => regeneratePages(projectPath, ['knowledge', 'risks', 'decisions']), (pages) => ({ pages })).catch(() => {
                 /* best-effort — never fail init */
             });
             // SPEC-645: Detect LLM client and cache in conventions.json (fire-and-forget)

package/dist/tools/init-project/legacy-root-migration.d.ts

@@ -0,0 +1,15 @@
+export interface LegacyMigrationResult {
+    readonly migrated: readonly string[];
+    readonly warnings: readonly string[];
+}
+/**
+ * Fold conventions.json, technology-selection.json, and releases/pending.json
+ * into project.json, then move context.md/session-context.md/session.json
+ * under planu/.runtime. Returns the migrated relative paths and any
+ * malformed-legacy-artifact warnings. Best-effort — a failure leaves the
+ * remaining legacy artifacts for a later retry.
+ */
+export declare function migrateLegacyPlanuRoot(projectPath: string): Promise<LegacyMigrationResult>;
+/** Runs `migrateLegacyPlanuRoot` only for an already-initialized project; a no-op otherwise. */
+export declare function resolveLegacyMigration(isUpdate: boolean, projectPath: string): Promise<LegacyMigrationResult>;
+//# sourceMappingURL=legacy-root-migration.d.ts.map

package/dist/tools/init-project/legacy-root-migration.js

@@ -0,0 +1,213 @@
+// tools/init-project/legacy-root-migration.ts — SPEC-1699
+// Folds legacy planu/ root artifacts into their canonical SPEC-1699 locations:
+// conventions.json and technology-selection.json fold into project.json,
+// releases/pending.json folds into project.json's releases field, and
+// context.md/session-context.md/session.json move under planu/.runtime.
+// Best-effort and idempotent — a project with none of these legacy artifacts
+// is a no-op. A malformed legacy file is left in place for manual repair
+// instead of being silently treated as absent.
+import { readFile, writeFile, rename, rm, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { generateConventionsMdIfMissing } from './conventions-writer.js';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { pathExists } from '../../core/shared/fs.js';
+async function readJsonFile(filePath, isExpectedShape) {
+    let raw;
+    try {
+        raw = await readFile(filePath, 'utf-8');
+    }
+    catch {
+        return { status: 'missing' };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isExpectedShape(parsed)) {
+            return { status: 'malformed', error: `${filePath} does not have the expected shape` };
+        }
+        return { status: 'ok', value: parsed };
+    }
+    catch (error) {
+        return { status: 'malformed', error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function isJsonObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isJsonArray(value) {
+    return Array.isArray(value);
+}
+function malformedWarning(filePath, result) {
+    return result.status === 'malformed'
+        ? `Legacy artifact ${filePath} is malformed and was left in place: ${result.error}`
+        : null;
+}
+async function planConventionsFold(planuDir) {
+    const filePath = join(planuDir, 'conventions.json');
+    const result = await readJsonFile(filePath, isJsonObject);
+    if (result.status !== 'ok') {
+        return { step: null, warning: malformedWarning(filePath, result) };
+    }
+    return {
+        step: {
+            projectField: 'conventions',
+            projectValue: result.value,
+            pathsToDelete: [filePath],
+            migratedPath: 'planu/conventions.json',
+        },
+        warning: null,
+    };
+}
+async function planTechnologySelectionFold(planuDir) {
+    const filePath = join(planuDir, 'technology-selection.json');
+    const result = await readJsonFile(filePath, isJsonObject);
+    if (result.status !== 'ok') {
+        return { step: null, warning: malformedWarning(filePath, result) };
+    }
+    return {
+        step: {
+            projectField: 'technologySelection',
+            projectValue: result.value,
+            pathsToDelete: [filePath],
+            migratedPath: 'planu/technology-selection.json',
+        },
+        warning: null,
+    };
+}
+function dedupeReleaseEntriesById(entries) {
+    const deduped = new Map();
+    const undeduplicated = [];
+    for (const entry of entries) {
+        const id = isJsonObject(entry) && typeof entry.specId === 'string' ? entry.specId : undefined;
+        if (id === undefined) {
+            undeduplicated.push(entry);
+            continue;
+        }
+        deduped.set(id, entry);
+    }
+    return [...undeduplicated, ...deduped.values()];
+}
+async function planReleasesFold(planuDir, existingReleases) {
+    const releasesDir = join(planuDir, 'releases');
+    const pendingPath = join(releasesDir, 'pending.json');
+    const result = await readJsonFile(pendingPath, isJsonArray);
+    if (result.status !== 'ok') {
+        return { step: null, warning: malformedWarning(pendingPath, result) };
+    }
+    const existing = Array.isArray(existingReleases) ? existingReleases : [];
+    return {
+        step: {
+            projectField: 'releases',
+            // Deduped by specId so an interrupted-and-retried migration (project.json
+            // already updated, planu/releases/ not yet deleted) never duplicates entries.
+            projectValue: dedupeReleaseEntriesById([...existing, ...result.value]),
+            pathsToDelete: [releasesDir],
+            migratedPath: 'planu/releases/pending.json',
+        },
+        warning: null,
+    };
+}
+function extractConventionsSource(parsed, projectPath) {
+    const stackRaw = parsed.stack;
+    const stack = stackRaw !== null && typeof stackRaw === 'object' ? stackRaw : {};
+    const stackFields = [
+        stack.language,
+        stack.framework,
+        stack.testRunner,
+        stack.linter,
+        stack.formatter,
+        stack.bundler,
+    ].filter((value) => typeof value === 'string');
+    return {
+        language: typeof stack.language === 'string' ? stack.language : 'unknown',
+        framework: typeof stack.framework === 'string' ? stack.framework : null,
+        stack: stackFields,
+        projectPath,
+    };
+}
+async function moveUnderRuntime(planuDir, fileName) {
+    const source = join(planuDir, fileName);
+    if (!(await pathExists(source))) {
+        return null;
+    }
+    const runtimeDir = join(planuDir, '.runtime');
+    await mkdir(runtimeDir, { recursive: true });
+    await rename(source, join(runtimeDir, fileName));
+    return `planu/${fileName}`;
+}
+async function planJsonFolds(planuDir, project) {
+    const outcomes = await Promise.all([
+        planConventionsFold(planuDir),
+        planTechnologySelectionFold(planuDir),
+        planReleasesFold(planuDir, project.releases),
+    ]);
+    return {
+        steps: outcomes
+            .map((outcome) => outcome.step)
+            .filter((step) => step !== null),
+        warnings: outcomes
+            .map((outcome) => outcome.warning)
+            .filter((warning) => warning !== null),
+    };
+}
+async function foldJsonArtifactsIntoProject(projectPath, planuDir, projectJsonPath, project) {
+    const { steps, warnings } = await planJsonFolds(planuDir, project);
+    if (steps.length === 0) {
+        return { migrated: [], warnings };
+    }
+    const nextProject = { ...project };
+    for (const step of steps) {
+        nextProject[step.projectField] = step.projectValue;
+    }
+    // Write project.json, then regenerate conventions.md, and only then delete
+    // the legacy source files — a crash between steps must never leave the
+    // canonical record updated with the legacy source already gone unread.
+    await writeFile(projectJsonPath, `${JSON.stringify(nextProject, null, 2)}\n`, 'utf-8');
+    const conventionsStep = steps.find((step) => step.projectField === 'conventions');
+    if (conventionsStep) {
+        await generateConventionsMdIfMissing(projectPath, extractConventionsSource(conventionsStep.projectValue, projectPath), true);
+    }
+    for (const step of steps) {
+        for (const pathToDelete of step.pathsToDelete) {
+            await rm(pathToDelete, { recursive: true, force: true });
+        }
+    }
+    return { migrated: steps.map((step) => step.migratedPath), warnings };
+}
+/**
+ * Fold conventions.json, technology-selection.json, and releases/pending.json
+ * into project.json, then move context.md/session-context.md/session.json
+ * under planu/.runtime. Returns the migrated relative paths and any
+ * malformed-legacy-artifact warnings. Best-effort — a failure leaves the
+ * remaining legacy artifacts for a later retry.
+ */
+export async function migrateLegacyPlanuRoot(projectPath) {
+    const planuDir = join(projectPath, 'planu');
+    const projectJsonPath = join(planuDir, 'project.json');
+    const migrated = [];
+    const warnings = [];
+    try {
+        const projectResult = await readJsonFile(projectJsonPath, isJsonObject);
+        const project = projectResult.status === 'ok' ? projectResult.value : {};
+        const folded = await foldJsonArtifactsIntoProject(projectPath, planuDir, projectJsonPath, project);
+        migrated.push(...folded.migrated);
+        warnings.push(...folded.warnings);
+        for (const fileName of ['context.md', 'session-context.md', 'session.json']) {
+            const movedPath = await moveUnderRuntime(planuDir, fileName);
+            if (movedPath) {
+                migrated.push(movedPath);
+            }
+        }
+    }
+    catch (error) {
+        warnings.push(`Legacy migration stopped early: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    for (const warning of warnings) {
+        reportClassifiedDegradation('LEGACY_MIGRATION_ARTIFACT_WARNING', new Error(warning));
+    }
+    return { migrated, warnings };
+}
+/** Runs `migrateLegacyPlanuRoot` only for an already-initialized project; a no-op otherwise. */
+export async function resolveLegacyMigration(isUpdate, projectPath) {
+    return isUpdate ? migrateLegacyPlanuRoot(projectPath) : { migrated: [], warnings: [] };
+}
+//# sourceMappingURL=legacy-root-migration.js.map

package/dist/tools/init-project/runtime-residue.d.ts

@@ -0,0 +1,2 @@
+export declare function scheduleRuntimeResidueSweep(projectPath: string): void;
+//# sourceMappingURL=runtime-residue.d.ts.map

package/dist/tools/init-project/runtime-residue.js

@@ -0,0 +1,11 @@
+// tools/init-project/runtime-residue.ts — SPEC-1695
+// Fire-and-forget trigger for the runtime-residue sweep, called from init_project
+// so existing client checkouts self-heal without a manual cleanup step.
+import { withAudit } from '../../engine/autopilot/audit-logger.js';
+import { sweepRuntimeResidue } from '../../engine/housekeeping/runtime-residue-sweep.js';
+export function scheduleRuntimeResidueSweep(projectPath) {
+    void withAudit(projectPath, 'init_project', 'sweepRuntimeResidue', () => sweepRuntimeResidue(projectPath), (result) => ({ removed: result.removed.length })).catch(() => {
+        /* best-effort */
+    });
+}
+//# sourceMappingURL=runtime-residue.js.map

package/dist/tools/session-checkpoint.js

@@ -9,7 +9,7 @@ import { compactResult } from './output-formatter.js';
 export async function handleSessionCheckpoint(args) {
     const snapshot = sessionTracker.getSnapshot();
     await writeCheckpoint(args.projectPath, snapshot);
-    return compactResult(`Session checkpoint written to ${args.projectPath}/planu/session-context.md\n` +
+    return compactResult(`Session checkpoint written to ${args.projectPath}/planu/.runtime/session-context.md\n` +
         `Calls recorded: ${String(snapshot.callCount)}, ` +
         `files tracked: ${String(snapshot.modifiedFiles.length)}.`);
 }

package/dist/tools/update-status/index.js

@@ -7,7 +7,7 @@ import { rollbackTransitionSpec, transitionSpec, } from '../../engine/spec-state
 import { calculateAccuracy } from '../../engine/estimator.js';
 import { cascadeCheck } from '../../engine/spec-versioner.js';
 import { runComplianceGates } from '../update-status-convention-gate.js';
-import { runDoneActions, runDoneSideEffects, runImplementingActions, runImplementingSideEffects, } from '../update-status-actions.js';
+import { runDoneActions, runDoneSideEffects, runImplementingActions, runImplementingSideEffects, pruneRuntimeArtifactsOnTerminal, } from '../update-status-actions.js';
 import { compactObj } from '../../engine/compact-obj.js';
 import { checkTransition, checkDorGate, checkAmbiguityGate, checkReadinessGate, checkChallengeGate, checkImplementationDependencyGate, checkSpecArtifactCommittedGate, resolveAutoAdvanceSteps, isReverseTransition, validateReverseTransition, } from './transition-guard.js';
 import { checkApprovedDepGate } from '../../engine/dep-guard/index.js';
@@ -1426,6 +1426,12 @@ export async function handleUpdateStatus(params, server) {
                             /* reliability-optional: TERMINAL_VALIDATION_REPORT — canonical receipt is authoritative */
                             reportClassifiedDegradation('TERMINAL_VALIDATION_REPORT', error);
                         });
+                        try {
+                            await pruneRuntimeArtifactsOnTerminal(projectId, specId);
+                        }
+                        catch (error) {
+                            reportClassifiedDegradation('RETENTION_TERMINAL_PRUNE', error);
+                        }
                     }
                     const allSpecs = await specStore.listSpecs(projectId);
                     const cascadeResult = cascadeCheck(specId, allSpecs, newStatus);

package/dist/tools/update-status-actions.d.ts

@@ -1,4 +1,10 @@
-import type { ConstitutionViolation, DoneSideEffectsReport } from '../types/index.js';
+import type { ConstitutionViolation, DoneSideEffectsReport, RetentionResult } from '../types/index.js';
+/**
+ * Remove handoff packages, evidence bundles, and archived context for a spec
+ * that just reached a terminal status (done or discarded). Never touches
+ * planu/specs/ — the canonical spec.md lives outside runtime storage.
+ */
+export declare function pruneRuntimeArtifactsOnTerminal(projectId: string, specId: string): Promise<RetentionResult>;
 export declare function runImplementingActions(projectId: string, specId: string, options?: {
     deferSideEffects?: boolean;
     projectPath?: string;

package/dist/tools/update-status-actions.js

@@ -1,7 +1,15 @@
-import { specStore, knowledgeStore } from '../storage/index.js';
+import { specStore, knowledgeStore, projectDataDir, enforceRetention } from '../storage/index.js';
 import { checkConstitutionCompliance } from './create-spec-tech.js';
 import { withAudit } from '../engine/autopilot/audit-logger.js';
 import { hasPending, markPending, clearPending } from '../engine/autopilot/cascade-deduplicator.js';
+/**
+ * Remove handoff packages, evidence bundles, and archived context for a spec
+ * that just reached a terminal status (done or discarded). Never touches
+ * planu/specs/ — the canonical spec.md lives outside runtime storage.
+ */
+export async function pruneRuntimeArtifactsOnTerminal(projectId, specId) {
+    return enforceRetention({ kind: 'spec-artifacts', path: projectDataDir(projectId), specId });
+}
 function normalizeRejectedReasons(results) {
     return results.map((result) => {
         const reason = result.reason;
@@ -210,7 +218,7 @@ export async function runDoneActions(projectId, specId, gitBranch, options = {})
     // SPEC-649: slim cascade — 2 actions only
     const autopilotSummary = [
         'session.json: refresh queued',
-        'releases/pending.json: refresh queued',
+        'project.json releases: refresh queued',
     ];
     return {
         mergeWarning,