@planu/cli 5.5.3 → 5.7.0

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/init-project/schedule-housekeeping.d.ts

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

package/dist/tools/init-project/schedule-housekeeping.js

@@ -0,0 +1,8 @@
+// tools/init-project/schedule-housekeeping.ts — SPEC-1709
+import { scheduleRuntimeResidueSweep } from './runtime-residue.js';
+import { scheduleLegacyPlanuDemolition } from './legacy-planu.js';
+export function scheduleHousekeepingSweeps(projectPath) {
+    scheduleRuntimeResidueSweep(projectPath);
+    scheduleLegacyPlanuDemolition(projectPath);
+}
+//# sourceMappingURL=schedule-housekeeping.js.map

package/dist/tools/reconcile-spec.js

@@ -1,5 +1,5 @@
 import { SECTIONS_WITHOUT_LITERAL_BODY_TEXT, } from '../types/index.js';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { elicitOrFallback, buildEnumSchema } from '../engine/elicitation/elicit-helper.js';
 import { ti, t } from '../i18n/index.js';
 import { formatSuccess, addNextSteps } from './response-helpers.js';
@@ -14,6 +14,9 @@ import { analyzeLivingSpec } from '../engine/living-spec-analyzer.js';
 import { notifyStoreChange } from '../engine/doc-generator/portal/regen-hook.js';
 import { applyChangesToSpec } from '../engine/reconcile/apply-changes.js';
 import { verifyWriteSucceeded } from '../engine/reconcile/verify-write.js';
+import { reconcileImplementingSpec, currentReconciliationInvocationContext, } from '../engine/lifecycle-reconciliation.js';
+import { reconciliationDigest } from '../engine/lifecycle-reconciliation-io.js';
+import { syncSpecFiles } from './update-status/file-sync.js';
 function detectEstimationDrift(spec) {
     if (!spec.actuals) {
         return null;
@@ -322,8 +325,29 @@ function applyConflictResolution(resolution, allChanges, pendingChanges) {
         }
     }
 }
+async function routeDeclaredArchitecturalDrift(spec, projectId, projectPath, declaredDrift) {
+    const reason = declaredDrift.reason;
+    const input = {
+        specId: spec.id,
+        projectId,
+        projectPath,
+        status: 'review',
+        reconciliationRequestId: randomUUID(),
+        expectedImplementingTransitionId: spec.statusHistory?.at(-1)?.transitionId,
+        implementationReviewDigest: reconciliationDigest(reason.trim()),
+        reason,
+        declaredDriftKind: declaredDrift.kind,
+    };
+    return reconcileImplementingSpec({
+        input,
+        projectId,
+        projectPath,
+        context: currentReconciliationInvocationContext(),
+        syncSpecFiles,
+    });
+}
 export async function handleReconcileSpec(params, server) {
-    const { specId, projectId, autoDetect = true, livingSpec = false, changes: manualChanges, } = params;
+    const { specId, projectId, autoDetect = true, livingSpec = false, changes: manualChanges, declaredDrift, } = params;
     try {
         const spec = await specStore.getSpec(projectId, specId);
         if (!spec) {
@@ -333,6 +357,9 @@ export async function handleReconcileSpec(params, server) {
             };
         }
         const knowledge = await knowledgeStore.getKnowledge(projectId);
+        if (declaredDrift) {
+            return await routeDeclaredArchitecturalDrift(spec, projectId, knowledge?.projectPath, declaredDrift);
+        }
         const allChanges = [];
         if (autoDetect) {
             const autoChanges = await autoDetectChanges(spec, knowledge);

package/dist/tools/register-spec-tools/analysis-tools.d.ts

@@ -1,4 +1,11 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+export declare const DeclaredDriftInputSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        "architectural-premise": "architectural-premise";
+    }>;
+    reason: z.ZodString;
+}, z.core.$strip>;
 /**
  * Registers drift detection, analysis, and discovery tools (tools 11–19) on the MCP server.
  */

package/dist/tools/register-spec-tools/analysis-tools.js

@@ -7,6 +7,7 @@ import { handleDetectDrift } from '../detect-drift.js';
 import { handleSummarizeSpec } from '../summarize-spec.js';
 import { handleGenerateChecklist } from '../generate-checklist.js';
 import { handleReconcileSpec } from '../reconcile-spec.js';
+import { runWithTrustedLocalMcpContext } from '../../engine/lifecycle-reconciliation.js';
 import { handleLearn } from '../learn.js';
 import { handleAudit } from '../audit.js';
 import { handleConsultDocs } from '../consult-docs.js';
@@ -17,6 +18,16 @@ import { handleSuggestMcpServer } from '../suggest-mcp-server.js';
 import { handleScanOrphanSpecRefs, ScanOrphanSpecRefsInputSchema, } from '../scan-orphan-spec-refs.js';
 import { registerGraphSpecsTool } from '../graph-specs.js';
 import { registerAuditSpecsDriftTool } from '../audit-specs-drift.js';
+export const DeclaredDriftInputSchema = z.object({
+    kind: z
+        .enum(['architectural-premise'])
+        .describe('Drift kind. Only "architectural-premise" is supported: an orchestrator-declared premise contradiction that produces no auto-detectable file/scope drift.'),
+    reason: z
+        .string()
+        .min(100)
+        .max(10_000)
+        .describe('Why the implementation drifted from the approved architectural premise. Minimum 100 characters — becomes the reconciliation transition reason.'),
+});
 import { handleSsrBackMigration } from '../ssr-back-migration.js';
 import { registerMigrateLegacySpecTool } from '../migrate-legacy-spec.js';
 /**
@@ -130,13 +141,14 @@ export function registerAnalysisTools(server) {
                 .max(1000)
                 .optional()
                 .describe('Manual changes to apply'),
+            declaredDrift: DeclaredDriftInputSchema.optional().describe('When the spec is implementing, routes reconcile_spec into the existing implementing→review reconciliation demotion instead of auto-detected drift.'),
         },
     }, safeGoverned('reconcile_spec', async (args) => {
         const pid = resolveProjectId(args);
         if (!pid) {
             return missingProjectIdError;
         }
-        return handleReconcileSpec({ ...args, projectId: pid });
+        return runWithTrustedLocalMcpContext(() => handleReconcileSpec({ ...args, projectId: pid }));
     }));
     // 15. learn_pattern
     server.registerTool('learn_pattern', {

package/dist/tools/safe-handler.js

@@ -7,8 +7,7 @@ import { ensureWorkersStarted } from '../engine/workers/index.js';
 import { recordError } from '../storage/error-telemetry-store.js';
 import { hashProjectPath } from '../storage/base-store.js';
 import { reportToolError, reportToolValidationError } from '../engine/telemetry/error-reporter.js';
-import { sendTelemetryEvent } from '../engine/telemetry/telemetry-client.js';
-import { PLANU_VERSION } from '../config/version.js';
+import { sendTelemetryEnvelopeEvent } from '../engine/telemetry/telemetry-client.js';
 import { recordToolTokens, extractOutputText } from './token-recording.js';
 import { DriftCacheStore } from '../storage/drift-cache-store.js';
 import { consumeUpdateBanner } from '../engine/update-notifier.js';
@@ -509,18 +508,13 @@ function safeWithTelemetry(toolName, handler) {
                     const outputText = extractOutputText(processedResult);
                     recordLlmTokens(toolName, inputText, outputText);
                 }
-                // Emit tool_used telemetry for successful calls (fire-and-forget)
+                // Emit mcp_tool_completed envelope for successful calls (fire-and-forget)
                 /* v8 ignore start */
                 if (toolName !== undefined && processedResult.isError !== true) {
-                    sendTelemetryEvent({
-                        event: 'tool_used',
-                        properties: {
-                            tool: toolName,
-                            planVersion: PLANU_VERSION,
-                            nodeVersion: process.version,
-                            platform: process.platform,
-                            durationMs: Date.now() - startTime,
-                        },
+                    sendTelemetryEnvelopeEvent('mcp_tool_completed', {
+                        toolName,
+                        result: 'success',
+                        durationMs: Date.now() - startTime,
                     });
                 }
                 /* v8 ignore stop */

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,

package/dist/types/handoff-artifacts.d.ts

@@ -124,6 +124,7 @@ export interface ReconciliationReceiptV1 {
     transitionId?: string;
     phase?: 'prepared' | 'status-committed' | 'spec-synced' | 'audit-appended';
     auditPending?: boolean;
+    driftSource?: 'declared-architectural-premise';
 }
 /** Injectable receipt persistence boundary used only for reconciliation crash tests. */
 export interface ReconciliationIo {

package/dist/types/housekeeping.d.ts

@@ -1,3 +1,4 @@
+import type { GlobalProjectsRegistry, RegisteredProject } from './cross-repo-search.js';
 export interface StaleBranchInfo {
     /** Short ref name, e.g. 'tmp-foo' or 'feat/spec-100-bar'. */
     name: string;
@@ -146,4 +147,41 @@ export interface HousekeepingHistoryEntry {
     prevSha: string;
     sha256: string;
 }
+export interface RuntimeResidueSweepResult {
+    /** Absolute paths of every legacy runtime artifact removed from planu/. */
+    removed: string[];
+}
+export interface LegacyPlanuDemolitionFailure {
+    /** Directory name under <legacyRoot>/data/projects. */
+    dir: string;
+    /** Human-readable reason the directory could not be migrated. */
+    reason: string;
+}
+export type LegacyPlanuDemolitionStatus = 'demolished' | 'retained' | 'absent';
+export interface LegacyPlanuDemolitionReport {
+    status: LegacyPlanuDemolitionStatus;
+    /** Directory names successfully migrated into their canonical destination. */
+    migrated: string[];
+    /** Count of unmappable directories deleted outright. */
+    demolishedUnmappable: number;
+    /** Per-directory migration failures; the root is retained when this is non-empty. */
+    failures: LegacyPlanuDemolitionFailure[];
+    /** Bytes freed by deleting the whole legacy root (0 unless status is 'demolished'). */
+    freedBytes: number;
+}
+export interface LegacyPlanuDemolisherOptions {
+    /** Legacy root to sweep. Defaults to join(homedir(), '.planu'). */
+    legacyRoot?: string;
+    /** Global cross-repo registry. Defaults to a live read via getRegistry(). */
+    registry?: GlobalProjectsRegistry;
+    /** Resolves a registered project's canonical storage destination. */
+    resolveDestination?: (project: RegisteredProject) => Promise<string>;
+}
+/** Internal accumulator returned by the data/projects sweep pass. */
+export interface LegacyPlanuSweepResult {
+    migrated: string[];
+    demolishedUnmappable: number;
+    failures: LegacyPlanuDemolitionFailure[];
+    freedBytes: number;
+}
 //# sourceMappingURL=housekeeping.d.ts.map

package/dist/types/housekeeping.js

@@ -1,3 +1,2 @@
-// types/housekeeping.ts — SPEC-751: Housekeeping sweep types
 export {};
 //# sourceMappingURL=housekeeping.js.map

package/dist/types/index.d.ts

@@ -293,5 +293,6 @@ export * from './host-tool-filter.js';
 export * from './reconcile.js';
 export * from './release-pipeline.js';
 export * from './network-policy.js';
+export * from './retention.js';
 export type { VerifiedImplementationReviewResult, VerifiedImplementationReviewOk, VerifiedImplementationReviewErr, ImplementationReviewRejectionReason, } from './handoff-artifacts.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.js

@@ -304,4 +304,5 @@ export * from './reconcile.js';
 // SPEC-1012: Release spec closer types
 export * from './release-pipeline.js';
 export * from './network-policy.js';
+export * from './retention.js';
 //# sourceMappingURL=index.js.map

package/dist/types/retention.d.ts

@@ -0,0 +1,12 @@
+export interface RetentionResult {
+    readonly freedBytes: number;
+    readonly removedPaths: readonly string[];
+}
+export type RetentionKind = 'transition-log' | 'graph-cache' | 'spec-store-backup' | 'idempotency' | 'snapshot' | 'spec-artifacts';
+export interface EnforceRetentionInput {
+    readonly kind: RetentionKind;
+    readonly path: string;
+    readonly protectedPaths?: readonly string[];
+    readonly specId?: string;
+}
+//# sourceMappingURL=retention.d.ts.map

package/dist/types/retention.js

@@ -0,0 +1,3 @@
+// types/retention.ts — SPEC-1697: retention budgets for runtime storage artifacts
+export {};
+//# sourceMappingURL=retention.js.map

package/dist/types/scope.d.ts

@@ -126,4 +126,27 @@ export interface ContradictionPatternDef {
     /** Recommended resolution action. */
     recommendation: string;
 }
+/** A pair of antonymic direction phrases used to detect cross-spec premise drift (SPEC-1702). */
+export interface DirectionalPhrasePair {
+    /** One side of the directional claim, e.g. "re-roots at". */
+    phraseA: string;
+    /** The opposite side of the directional claim, e.g. "relocates to". */
+    phraseB: string;
+}
+/**
+ * A contradiction between a spec's body claim about a done/approved sibling spec
+ * and that sibling's own delivered contract (SPEC-1702).
+ */
+export interface CrossSpecPremiseFinding {
+    /** ID of the spec containing the premise claim (e.g. "SPEC-1698"). */
+    targetSpecId: string;
+    /** ID of the referenced sibling spec whose contract contradicts the claim (e.g. "SPEC-1695"). */
+    siblingSpecId: string;
+    /** The exact sentence in the target spec asserting the contradicted claim. */
+    targetSentence: string;
+    /** The exact sentence in the sibling spec's own body stating the opposite direction. */
+    siblingSentence: string;
+    /** File path shared between both specs' ## Files sections, evidencing the same subject. */
+    sharedFilePath: string;
+}
 //# sourceMappingURL=scope.d.ts.map

package/dist/types/spec/core.d.ts

@@ -139,6 +139,13 @@ export interface Spec {
      * Contains failure scenarios, addressed count, and overall risk.
      */
     challengeReport?: ChallengeReport;
+    /**
+     * SPEC-1699: sha256 digest of the spec.md content this record's title was
+     * last synced from. Absent or mismatched against the current spec.md means
+     * the record is stale and is refreshed on the next read that supplies a
+     * canonicalRoot (see spec-store.ts refreshSpecFromDisk).
+     */
+    contentDigest?: string;
 }
 /** SPEC-964: Result of running challenge_spec on a spec. */
 export interface ChallengeReport {

package/dist/types/spec/index-cache.d.ts

@@ -0,0 +1,25 @@
+/** One spec's fields as parsed from its canonical spec.md, plus a content digest. */
+export interface SpecIndexRecord {
+    readonly id: string;
+    readonly title: string;
+    readonly status: string;
+    readonly type: string;
+    readonly target: string;
+    readonly scope: string;
+    readonly difficulty: number | null;
+    readonly risk: string;
+    readonly createdAt: string | null;
+    readonly updatedAt: string;
+    readonly specPath: string;
+    readonly digest: string;
+    /** GIVEN/WHEN/THEN acceptance-criteria lines parsed from the spec.md body. */
+    readonly scenarios: readonly string[];
+    /** `TEST:` marker contents parsed from the spec.md body. */
+    readonly tests: readonly string[];
+}
+/** Regenerable cache persisted at planu/.runtime/index.json. spec.md is authoritative. */
+export interface SpecIndex {
+    readonly generatedAt: string;
+    readonly specs: Readonly<Record<string, SpecIndexRecord>>;
+}
+//# sourceMappingURL=index-cache.d.ts.map

package/dist/types/spec/index-cache.js

@@ -0,0 +1,3 @@
+// Planu — Regenerable spec.md read-index types (SPEC-1699)
+export {};
+//# sourceMappingURL=index-cache.js.map