@planu/cli 5.5.3 → 5.7.0

package/dist/storage/spec-store.d.ts

@@ -29,8 +29,11 @@ export declare function invalidateSpecsCache(projectId: string): void;
 export declare function discoverCanonicalSpecPath(specId: string, canonicalRoot: string): Promise<string | null>;
 /**
  * List every spec for a project.
+ *
+ * When `canonicalRoot` is supplied, every record's content-derived fields are
+ * verified against the current spec.md before being returned (SPEC-1699).
  */
-export declare function listSpecs(projectId: string): Promise<Spec[]>;
+export declare function listSpecs(projectId: string, canonicalRoot?: string): Promise<Spec[]>;
 /**
  * Run a read-modify side effect against a fresh spec snapshot while holding the
  * same cross-process lock used by status mutations.
@@ -39,9 +42,11 @@ export declare function withFreshSpecsLock<T>(projectId: string, fn: (specs: Spe
 /**
  * Get a single spec by ID. Returns `null` when not found.
  *
- * When `canonicalRoot` is supplied, a legacy absolute `specPath`/`technicalPath`
+ * When `canonicalRoot` is supplied: a legacy absolute `specPath`/`technicalPath`
  * for this spec is migrated to its portable project-relative identity first
- * (best-effort — a failed migration attempt never blocks the read).
+ * (best-effort — a failed migration attempt never blocks the read), and the
+ * returned record's content-derived fields are verified against the current
+ * spec.md before being returned (SPEC-1699).
  */
 export declare function getSpec(projectId: string, specId: string, canonicalRoot?: string): Promise<Spec | null>;
 /** Result of a {@link migrateLegacySpecPaths} run. */

package/dist/storage/spec-store.js

@@ -1,5 +1,6 @@
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 import { CriticalJsonReadError, readCriticalJson, readJson, writeJson, projectDataDir, } from './base-store.js';
+import { enforceRetention } from './retention.js';
 import { decodeCriticalSchema, registerCriticalSchema } from './schema-registry.js';
 import { BoundaryFailure } from '../errors/error-taxonomy.js';
 import { withFileLock } from './file-mutex.js';
@@ -8,11 +9,13 @@ import { computeHealthScore } from '../engine/spec-health-scorer.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { loadSpecContent } from '../engine/validation-loop.js';
 import { createHash, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import { glob } from 'glob';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { acquireLock, releaseLock } from '../engine/safety/cross-process-lock.js';
-import { resolvePortableSpecPath, toPortableSpecPath, PortablePathError, } from './project-identity.js';
+import { resolvePortableSpecPath, resolveVerifiedSpecPath, toPortableSpecPath, PortablePathError, } from './project-identity.js';
+import { digestOf, readFrontmatterScalars } from './spec-index.js';
 import { appendEntry, getLastHash } from './audit-trail-store.js';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashEntry } from '../engine/audit-trail/hasher.js';
@@ -200,6 +203,7 @@ async function saveAll(projectId, specs) {
     const normalized = specs.map((spec) => normalizeSpec(spec));
     validateCanonicalSpecRows(projectId, normalized);
     await writeJson(specsFile(projectId), { schemaVersion: 1, data: normalized });
+    await enforceRetention({ kind: 'spec-store-backup', path: specsFile(projectId) });
     specsCache.set(projectId, normalized);
 }
 /** Evict the cache for a project (e.g. after external file changes). */
@@ -221,12 +225,72 @@ export async function discoverCanonicalSpecPath(specId, canonicalRoot) {
     });
     return candidates.length === 1 ? (candidates[0] ?? null) : null;
 }
+/**
+ * Persist a digest-refresh in isolation from whatever mutation the caller of
+ * getSpec/listSpecs is otherwise doing. Best-effort: failure to persist never
+ * blocks the caller — the freshly parsed value is already what gets returned.
+ */
+async function persistDigestRefresh(projectId, specId, title, contentDigest) {
+    await withSpecMutationLock(projectId, async () => {
+        const specs = await loadAll(projectId);
+        const idx = specs.findIndex((s) => s.id === specId);
+        if (idx === -1) {
+            return;
+        }
+        const nextSpecs = specs.map((current, currentIdx) => currentIdx === idx ? { ...current, title, contentDigest } : current);
+        await saveAll(projectId, nextSpecs);
+    });
+}
+/**
+ * SPEC-1699: single-source-of-truth choke point. spec.md is authoritative for
+ * the fields it carries — before returning a record, verify the persisted
+ * `contentDigest` still matches the current spec.md on disk. On a mismatch or
+ * missing digest, re-parse spec.md and return the fresh title/digest instead
+ * of the possibly-stale specs.json copy. Requires `canonicalRoot` to locate
+ * spec.md; callers that omit it get the specs.json record unchecked (matching
+ * the existing canonicalRoot-gated legacy-migration behavior on this same path).
+ */
+async function refreshSpecFromDisk(projectId, spec, canonicalRoot) {
+    let specMdPath;
+    try {
+        specMdPath = await resolveVerifiedSpecPath(spec.id, spec.specPath, canonicalRoot);
+    }
+    catch (error) {
+        reportClassifiedDegradation('SPEC_CONTENT_DIGEST_CHECK_SKIPPED', error);
+        return spec;
+    }
+    let content;
+    try {
+        content = await readFile(specMdPath, 'utf-8');
+    }
+    catch (error) {
+        reportClassifiedDegradation('SPEC_CONTENT_DIGEST_CHECK_SKIPPED', error);
+        return spec;
+    }
+    const digest = digestOf(content);
+    if (digest === spec.contentDigest) {
+        return spec;
+    }
+    const fields = readFrontmatterScalars(content);
+    const refreshed = { ...spec, title: fields.title ?? spec.title, contentDigest: digest };
+    await persistDigestRefresh(projectId, spec.id, refreshed.title, digest).catch((error) => {
+        reportClassifiedDegradation('SPEC_CONTENT_DIGEST_REFRESH_PERSIST', error);
+    });
+    return refreshed;
+}
 // --- public API ---
 /**
  * List every spec for a project.
+ *
+ * When `canonicalRoot` is supplied, every record's content-derived fields are
+ * verified against the current spec.md before being returned (SPEC-1699).
  */
-export async function listSpecs(projectId) {
-    return loadAll(projectId);
+export async function listSpecs(projectId, canonicalRoot) {
+    const specs = await loadAll(projectId);
+    if (canonicalRoot === undefined) {
+        return specs;
+    }
+    return Promise.all(specs.map((spec) => refreshSpecFromDisk(projectId, spec, canonicalRoot)));
 }
 /**
  * Run a read-modify side effect against a fresh spec snapshot while holding the
@@ -238,9 +302,11 @@ export async function withFreshSpecsLock(projectId, fn) {
 /**
  * Get a single spec by ID. Returns `null` when not found.
  *
- * When `canonicalRoot` is supplied, a legacy absolute `specPath`/`technicalPath`
+ * When `canonicalRoot` is supplied: a legacy absolute `specPath`/`technicalPath`
  * for this spec is migrated to its portable project-relative identity first
- * (best-effort — a failed migration attempt never blocks the read).
+ * (best-effort — a failed migration attempt never blocks the read), and the
+ * returned record's content-derived fields are verified against the current
+ * spec.md before being returned (SPEC-1699).
  */
 export async function getSpec(projectId, specId, canonicalRoot) {
     if (canonicalRoot !== undefined) {
@@ -249,7 +315,11 @@ export async function getSpec(projectId, specId, canonicalRoot) {
         });
     }
     const specs = await loadAll(projectId);
-    return specs.find((s) => s.id === specId) ?? null;
+    const spec = specs.find((s) => s.id === specId) ?? null;
+    if (spec && canonicalRoot !== undefined) {
+        return refreshSpecFromDisk(projectId, spec, canonicalRoot);
+    }
+    return spec;
 }
 /**
  * Record one hash-chained audit event for a legacy specPath migration batch.

package/dist/storage/storage-catalog.js

@@ -69,9 +69,9 @@ export function createStorageCatalog(context = {}) {
         },
         {
             id: 'portable-release-evidence',
-            templatePath: '<project>/planu/releases/',
-            resolvedPath: portableRoot ? join(portableRoot, 'releases') : undefined,
-            purpose: 'Versioned release declarations and portable verification evidence.',
+            templatePath: '<project>/planu/project.json#releases',
+            resolvedPath: portableRoot ? join(portableRoot, 'project.json') : undefined,
+            purpose: 'Pending release declarations tracked in the releases field of project.json.',
             owner: 'project',
             sourceOfTruth: true,
             lifecycle: 'portable',

package/dist/storage/storage-layout.d.ts

@@ -19,6 +19,14 @@ export interface StorageLayoutOptions {
     readonly homeDirectory?: string;
     readonly platform?: NodeJS.Platform;
 }
+export type ProjectRuntimeSubdir = 'state' | 'cache' | 'logs' | 'reports';
+/**
+ * Resolve the per-project runtime directory for a subdir kind.
+ * Rooted at <projectPath>/planu/.runtime/ — the only per-project runtime root.
+ * Platform storage roots from resolveStorageLayout are machine-local and do not
+ * apply to per-project artifacts.
+ */
+export declare function projectRuntimeDir(projectPath: string, subdir: ProjectRuntimeSubdir): string;
 /** Resolve every machine-local Planu path independently from the current directory. */
 export declare function resolveStorageLayout(options?: StorageLayoutOptions): StorageLayout;
 //# sourceMappingURL=storage-layout.d.ts.map

package/dist/storage/storage-layout.js

@@ -73,6 +73,15 @@ function resolvePlatformRoots(platform, home, env) {
     }
     return xdgRoots(home, env);
 }
+/**
+ * Resolve the per-project runtime directory for a subdir kind.
+ * Rooted at <projectPath>/planu/.runtime/ — the only per-project runtime root.
+ * Platform storage roots from resolveStorageLayout are machine-local and do not
+ * apply to per-project artifacts.
+ */
+export function projectRuntimeDir(projectPath, subdir) {
+    return join(projectPath, 'planu', '.runtime', subdir);
+}
 /** Resolve every machine-local Planu path independently from the current directory. */
 export function resolveStorageLayout(options = {}) {
     const env = options.env ?? process.env;

package/dist/storage/transition-log.js

@@ -9,6 +9,7 @@ import { appendFile, mkdir } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { projectDataDir } from './base-store.js';
+import { enforceRetention } from './retention.js';
 import { reportClassifiedDegradation } from '../errors/classified-degradation.js';
 // ---------------------------------------------------------------------------
 // Path helper
@@ -56,6 +57,7 @@ function computeEntrySha(entry) {
 const writeQueues = new Map();
 async function doAppend(filePath, input) {
     await mkdir(dirname(filePath), { recursive: true });
+    await enforceRetention({ kind: 'transition-log', path: filePath });
     let lastLine;
     for await (const line of streamJsonlLines(filePath)) {
         lastLine = line;

package/dist/tools/challenge-spec.js

@@ -15,6 +15,7 @@ import { t, ti } from '../i18n/index.js';
 import { generateConcurrencyAnalysis, buildScalabilityAssessment, calculateOverallRisk, readSpecContent, } from './challenge-spec-helpers.js';
 import { prioritizeScenarios, buildPrioritizedSummary } from '../engine/challenge-prioritizer.js';
 import { checkContradictions as checkScopeContradictions } from '../engine/scope-boundaries/index.js';
+import { detectCrossSpecPremiseContradictions } from '../engine/contradiction-detector.js';
 import { buildChallengeSpecSummary } from '../engine/human-summary.js';
 import { detectContradictions as detectDecisionContradictions, searchPriorDecisions, } from '../engine/prior-decisions/index.js';
 import { getDecisions } from '../storage/decision-store.js';
@@ -85,25 +86,23 @@ function extractOutOfScopeSection(content) {
     }
     return found ? captured.join('\n') : null;
 }
-async function resolveDocumentOutOfScope(spec, projectPath) {
+async function readRawSpecMarkdown(spec, projectPath) {
     if (!spec.specPath) {
-        return [];
+        return null;
     }
-    let fileContent;
     try {
         const resolvedPath = !isAbsolute(spec.specPath) && projectPath
             ? await resolveVerifiedSpecPath(spec.id, spec.specPath, projectPath)
             : spec.specPath;
-        fileContent = await readFile(resolvedPath, 'utf-8');
+        return await readFile(resolvedPath, 'utf-8');
     }
     catch {
-        return [];
+        return null;
     }
-    const sectionContent = extractOutOfScopeSection(fileContent);
-    return sectionContent === null ? [] : extractListItems(sectionContent);
 }
-async function resolveOutOfScopeItems(spec, projectPath) {
-    const documentItems = await resolveDocumentOutOfScope(spec, projectPath);
+function resolveOutOfScopeItems(spec, rawSpecMarkdown) {
+    const sectionContent = rawSpecMarkdown === null ? null : extractOutOfScopeSection(rawSpecMarkdown);
+    const documentItems = sectionContent === null ? [] : extractListItems(sectionContent);
     return documentItems.length > 0 ? documentItems : (spec.outOfScope ?? []);
 }
 /**
@@ -172,15 +171,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 +185,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
@@ -229,7 +229,8 @@ export async function handleChallengeSpec(args, server) {
     }
     failureScenarios.push(...collectCapabilityScenarios({ spec, specContent, knowledge, focusAreas, capabilities }));
     // SPEC-612: Check for contradictions between outOfScope and acceptance criteria
-    const resolvedOutOfScope = await resolveOutOfScopeItems(spec, knowledge.projectPath);
+    const rawSpecMarkdown = await readRawSpecMarkdown(spec, knowledge.projectPath);
+    const resolvedOutOfScope = resolveOutOfScopeItems(spec, rawSpecMarkdown);
     if (resolvedOutOfScope.length > 0) {
         const criteriaRange = findMarkdownSectionRange(specContent, 'Acceptance Criteria');
         const criteriaTexts = criteriaRange === null
@@ -248,6 +249,21 @@ export async function handleChallengeSpec(args, server) {
             });
         }
     }
+    // SPEC-1702: Check for premise contradictions against done/approved sibling specs
+    const crossSpecPremiseFindings = rawSpecMarkdown !== null
+        ? await detectCrossSpecPremiseContradictions(spec.id, rawSpecMarkdown, knowledge.projectPath)
+        : [];
+    for (const finding of crossSpecPremiseFindings) {
+        failureScenarios.push({
+            scenario: `cross-spec-premise: ${finding.targetSpecId} contradicts ${finding.siblingSpecId}`,
+            probability: 'high',
+            impact: 'critical',
+            currentHandling: `${finding.targetSpecId} claims: "${finding.targetSentence}"`,
+            requiredHandling: `${finding.siblingSpecId} states: "${finding.siblingSentence}" — reconcile the premise before implementation (shared file: ${finding.sharedFilePath})`,
+            dataConsistency: 'Cross-spec premise drift',
+            userExperience: 'Implementing on a contradicted premise risks a wasted implementation round',
+        });
+    }
     // SPEC-615 AC3: Check criteria against prior decisions for technology contradictions
     await runPriorDecisionContradictions(projectId, spec.title, spec.tags, specContent, failureScenarios);
     // 6. Generate concurrency analysis

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 { scheduleHousekeepingSweeps } from './schedule-housekeeping.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.
+            scheduleHousekeepingSweeps(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-planu.d.ts

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

package/dist/tools/init-project/legacy-planu.js

@@ -0,0 +1,18 @@
+// tools/init-project/legacy-planu.ts — SPEC-1709
+import { withAudit } from '../../engine/autopilot/audit-logger.js';
+import { demolishLegacyPlanuRoot } from '../../engine/housekeeping/legacy-planu-demolisher.js';
+export function scheduleLegacyPlanuDemolition(projectPath) {
+    const isTestEnvironment = Boolean(process.env.VITEST) || Boolean(process.env.PLANU_TEST_HOME);
+    if (isTestEnvironment) {
+        return;
+    }
+    void withAudit(projectPath, 'init_project', 'demolishLegacyPlanuRoot', () => demolishLegacyPlanuRoot(), (result) => ({
+        status: result.status,
+        migrated: result.migrated.length,
+        demolishedUnmappable: result.demolishedUnmappable,
+        freedBytes: result.freedBytes,
+    })).catch(() => {
+        /* best-effort */
+    });
+}
+//# sourceMappingURL=legacy-planu.js.map