@planu/cli 5.6.0 → 5.7.1

package/dist/engine/telemetry/telemetry-client.js

@@ -1,7 +1,8 @@
 // Remote telemetry is disabled by default and always crosses consent + redaction boundaries.
 import { networkFetch, withNetworkConsent } from '../network-policy.js';
 import { redactSensitiveValue } from '../../security/redactor.js';
-import { isTelemetryEnabled } from './telemetry-store.js';
+import { isTelemetryEnabled, getOrCreateAnonymousInstallationId } from './telemetry-store.js';
+import { buildTelemetryEnvelope, TELEMETRY_SESSION_ID } from './event-envelope.js';
 function isLoopbackHost(hostname) {
     return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
 }
@@ -24,25 +25,19 @@ function isConfiguredTelemetryToken(token) {
     return Boolean(token?.trim());
 }
 const ALLOWED_PROPERTIES = new Set([
-    'allowed',
-    'context',
-    'diagnostic',
-    'duplicateCount',
-    'durationMs',
-    'errorClass',
-    'errorType',
-    'framework',
-    'freeGBObserved',
-    'language',
-    'nodeVersion',
-    'planVersion',
-    'platform',
-    'pressureLevel',
-    'requested',
-    'specCount',
-    'stack',
-    'timestamp',
-    'tool',
+    'schemaVersion',
+    'eventId',
+    'eventName',
+    'occurredAt',
+    'anonymousInstallationId',
+    'sessionId',
+    'planuVersion',
+    'toolName',
+    'result',
+    'durationBucket',
+    'operatingSystem',
+    'nodeMajor',
+    'mcpHost',
 ]);
 function safeProperties(properties) {
     const allowlisted = Object.fromEntries(Object.entries(properties).filter(([key]) => ALLOWED_PROPERTIES.has(key)));
@@ -75,4 +70,27 @@ export function sendTelemetryEvent(event) {
     })
         .catch(() => undefined);
 }
+/**
+ * Builds a schemaVersion-1 envelope and emits it through sendTelemetryEvent.
+ * Fire-and-forget: never awaited by callers, and every failure (disabled consent, no
+ * installation id yet, an unknown enum value) resolves to a silent no-op — telemetry
+ * never blocks or delays the operation it is describing.
+ */
+export function sendTelemetryEnvelopeEvent(name, fields) {
+    void (async () => {
+        const anonymousInstallationId = await getOrCreateAnonymousInstallationId();
+        if (!anonymousInstallationId) {
+            return;
+        }
+        const envelope = buildTelemetryEnvelope(name, {
+            ...fields,
+            anonymousInstallationId,
+            sessionId: TELEMETRY_SESSION_ID,
+        });
+        sendTelemetryEvent({
+            event: envelope.eventName,
+            properties: envelope,
+        });
+    })().catch(() => undefined);
+}
 //# sourceMappingURL=telemetry-client.js.map

package/dist/engine/telemetry/telemetry-store.d.ts

@@ -4,10 +4,23 @@ export declare function readTelemetryConfig(): Promise<TelemetryConfig | null>;
 export declare function writeTelemetryConfig(config: TelemetryConfig): Promise<void>;
 /**
  * Returns true if telemetry is enabled.
- * Default: disabled. Both environment and stored opt-ins are versioned so a
- * changed privacy contract requires renewed consent.
+ * Suppression precedence (each read fresh from process.env on every call, so an
+ * env change within a process lifetime is respected immediately):
+ *   PLANU_TELEMETRY_DISABLED=1 > DO_NOT_TRACK=1 > CI=true > PLANU_TELEMETRY=off
+ *   > PLANU_TELEMETRY=on (with matching consent version) > stored consent.
+ * A corrupted or unparseable telemetry.json reads as consent-unknown (false), never crashes.
  */
 export declare function isTelemetryEnabled(): Promise<boolean>;
+/** Enables telemetry and generates a fresh anonymousInstallationId, replacing any prior one. */
+export declare function enableTelemetry(): Promise<TelemetryConfig>;
+/** Disables telemetry and deletes the stored anonymousInstallationId. */
+export declare function disableTelemetry(): Promise<TelemetryConfig>;
+/**
+ * Returns the current anonymousInstallationId when telemetry is enabled, lazily generating
+ * and persisting one if enabled but none is stored yet (e.g. enabled via PLANU_TELEMETRY=on).
+ * Returns undefined when telemetry is not enabled — never creates an id in that case.
+ */
+export declare function getOrCreateAnonymousInstallationId(): Promise<string | undefined>;
 /** Returns true if the user has never been shown the opt-in prompt. */
 export declare function hasNeverBeenPrompted(): Promise<boolean>;
 /** Mark that the user was shown the opt-in prompt (so we don't show it again). */

package/dist/engine/telemetry/telemetry-store.js

@@ -2,12 +2,14 @@
 // engine/telemetry/telemetry-store.ts — SPEC-200: Read/write telemetry config from ~/.planu/
 // Stores opt-in preference and installation ID outside the project directory.
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
 import { join } from 'node:path';
 // eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { resolveStorageLayout } from '../../storage/storage-layout.js';
 const PLANU_DIR = resolveStorageLayout().config;
 const TELEMETRY_FILE = join(PLANU_DIR, 'telemetry.json');
 export const TELEMETRY_CONSENT_VERSION = 1;
+const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 export async function readTelemetryConfig() {
     try {
         const raw = await readFile(TELEMETRY_FILE, 'utf-8');
@@ -22,6 +24,10 @@ export async function readTelemetryConfig() {
         if (parsed.enableObservatory === true) {
             config.enableObservatory = true;
         }
+        if (typeof parsed.anonymousInstallationId === 'string' &&
+            UUID_V4_PATTERN.test(parsed.anonymousInstallationId)) {
+            config.anonymousInstallationId = parsed.anonymousInstallationId;
+        }
         return config;
     }
     catch {
@@ -35,15 +41,28 @@ export async function writeTelemetryConfig(config) {
         promptedAt: config.promptedAt,
         consentVersion: config.consentVersion,
         enableObservatory: config.enableObservatory,
+        anonymousInstallationId: config.anonymousInstallationId,
     };
     await writeFile(TELEMETRY_FILE, JSON.stringify(safeConfig, null, 2) + '\n', 'utf-8');
 }
 /**
  * Returns true if telemetry is enabled.
- * Default: disabled. Both environment and stored opt-ins are versioned so a
- * changed privacy contract requires renewed consent.
+ * Suppression precedence (each read fresh from process.env on every call, so an
+ * env change within a process lifetime is respected immediately):
+ *   PLANU_TELEMETRY_DISABLED=1 > DO_NOT_TRACK=1 > CI=true > PLANU_TELEMETRY=off
+ *   > PLANU_TELEMETRY=on (with matching consent version) > stored consent.
+ * A corrupted or unparseable telemetry.json reads as consent-unknown (false), never crashes.
  */
 export async function isTelemetryEnabled() {
+    if (process.env.PLANU_TELEMETRY_DISABLED === '1') {
+        return false;
+    }
+    if (process.env.DO_NOT_TRACK === '1') {
+        return false;
+    }
+    if (process.env.CI === 'true') {
+        return false;
+    }
     if (process.env.PLANU_TELEMETRY === 'off') {
         return false;
     }
@@ -53,6 +72,57 @@ export async function isTelemetryEnabled() {
     const config = await readTelemetryConfig();
     return config?.enabled === true && config.consentVersion === TELEMETRY_CONSENT_VERSION;
 }
+function promptedAtOrNow(promptedAt) {
+    return promptedAt !== undefined && promptedAt !== '' ? promptedAt : new Date().toISOString();
+}
+/** Enables telemetry and generates a fresh anonymousInstallationId, replacing any prior one. */
+export async function enableTelemetry() {
+    const existing = await readTelemetryConfig();
+    const config = {
+        enabled: true,
+        promptedAt: promptedAtOrNow(existing?.promptedAt),
+        consentVersion: TELEMETRY_CONSENT_VERSION,
+        enableObservatory: existing?.enableObservatory,
+        anonymousInstallationId: randomUUID(),
+    };
+    await writeTelemetryConfig(config);
+    return config;
+}
+/** Disables telemetry and deletes the stored anonymousInstallationId. */
+export async function disableTelemetry() {
+    const existing = await readTelemetryConfig();
+    const config = {
+        enabled: false,
+        promptedAt: existing?.promptedAt ?? new Date().toISOString(),
+        consentVersion: existing?.consentVersion,
+        enableObservatory: existing?.enableObservatory,
+    };
+    await writeTelemetryConfig(config);
+    return config;
+}
+/**
+ * Returns the current anonymousInstallationId when telemetry is enabled, lazily generating
+ * and persisting one if enabled but none is stored yet (e.g. enabled via PLANU_TELEMETRY=on).
+ * Returns undefined when telemetry is not enabled — never creates an id in that case.
+ */
+export async function getOrCreateAnonymousInstallationId() {
+    if (!(await isTelemetryEnabled())) {
+        return undefined;
+    }
+    const config = await readTelemetryConfig();
+    if (config?.anonymousInstallationId) {
+        return config.anonymousInstallationId;
+    }
+    const anonymousInstallationId = randomUUID();
+    await writeTelemetryConfig({
+        enabled: true,
+        promptedAt: promptedAtOrNow(config?.promptedAt),
+        consentVersion: config?.consentVersion ?? TELEMETRY_CONSENT_VERSION,
+        enableObservatory: config?.enableObservatory,
+        anonymousInstallationId,
+    });
+    return anonymousInstallationId;
+}
 /** Returns true if the user has never been shown the opt-in prompt. */
 export async function hasNeverBeenPrompted() {
     const config = await readTelemetryConfig();
@@ -66,6 +136,7 @@ export async function markAsPrompted() {
         promptedAt: new Date().toISOString(),
         consentVersion: existing?.consentVersion,
         enableObservatory: existing?.enableObservatory,
+        anonymousInstallationId: existing?.anonymousInstallationId,
     });
 }
 //# sourceMappingURL=telemetry-store.js.map

package/dist/engine/validator/reliability-gate.d.ts

@@ -0,0 +1,4 @@
+import type { ReliabilityGateResult, ReliabilityGateViolation } from '../../types/index.js';
+export type { ReliabilityGateResult, ReliabilityGateViolation };
+export declare function runReliabilityGate(projectPath: string, specFiles: string[]): ReliabilityGateResult;
+//# sourceMappingURL=reliability-gate.d.ts.map

package/dist/engine/validator/reliability-gate.js

@@ -0,0 +1,93 @@
+import { execFileSync } from 'node:child_process';
+import { relative, resolve } from 'node:path';
+let cachedProtectedDirectories;
+function fetchProtectedDirectories() {
+    if (cachedProtectedDirectories !== undefined) {
+        return cachedProtectedDirectories;
+    }
+    const stdout = execFileSync(process.execPath, ['scripts/check-reliability-policies.mjs', '--print-protected-dirs'], { cwd: process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    const parsed = JSON.parse(stdout);
+    if (!Array.isArray(parsed) || !parsed.every((entry) => typeof entry === 'string')) {
+        throw new Error('reliability gate protected-directories output is not a string array');
+    }
+    cachedProtectedDirectories = parsed;
+    return parsed;
+}
+function normalizeToProjectRelative(projectPath, file) {
+    return relative(projectPath, resolve(projectPath, file));
+}
+function isProtected(protectedDirectories, file) {
+    return protectedDirectories.some((directory) => file === directory || file.startsWith(`${directory}/`));
+}
+function parseViolations(stdout) {
+    const parsed = JSON.parse(stdout);
+    if (!Array.isArray(parsed)) {
+        throw new Error('reliability gate output is not a JSON array');
+    }
+    return parsed.map((entry) => {
+        if (typeof entry !== 'object' ||
+            entry === null ||
+            typeof entry.file !== 'string' ||
+            typeof entry.line !== 'number' ||
+            typeof entry.rule !== 'string') {
+            throw new Error('reliability gate output entry is malformed');
+        }
+        return entry;
+    });
+}
+export function runReliabilityGate(projectPath, specFiles) {
+    const normalizedSpecFiles = new Set(specFiles.map((file) => normalizeToProjectRelative(projectPath, file)));
+    if (normalizedSpecFiles.size === 0) {
+        return { skipped: true, passed: true, failures: [], warnings: [] };
+    }
+    let protectedDirectories;
+    try {
+        protectedDirectories = fetchProtectedDirectories();
+    }
+    catch (error) {
+        return {
+            skipped: false,
+            passed: false,
+            failures: [],
+            warnings: [],
+            executionError: `could not resolve protected-directory allowlist: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (![...normalizedSpecFiles].some((file) => isProtected(protectedDirectories, file))) {
+        return { skipped: true, passed: true, failures: [], warnings: [] };
+    }
+    let stdout;
+    try {
+        stdout = execFileSync(process.execPath, ['scripts/check-reliability-policies.mjs', '--root', projectPath, '--json'], { cwd: process.cwd(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch (error) {
+        const stdoutFromError = error.stdout;
+        if (typeof stdoutFromError !== 'string' || stdoutFromError.trim().length === 0) {
+            return {
+                skipped: false,
+                passed: false,
+                failures: [],
+                warnings: [],
+                executionError: error instanceof Error ? error.message : String(error),
+            };
+        }
+        stdout = stdoutFromError;
+    }
+    let violations;
+    try {
+        violations = parseViolations(stdout);
+    }
+    catch (error) {
+        return {
+            skipped: false,
+            passed: false,
+            failures: [],
+            warnings: [],
+            executionError: `unparseable reliability gate output: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const failures = violations.filter((violation) => normalizedSpecFiles.has(violation.file));
+    const warnings = violations.filter((violation) => !normalizedSpecFiles.has(violation.file));
+    return { skipped: false, passed: failures.length === 0, failures, warnings };
+}
+//# sourceMappingURL=reliability-gate.js.map

package/dist/engine/validator/spec-compliance-runner.d.ts

@@ -1,5 +1,5 @@
 import type { Spec } from '../../types/index.js';
-import type { FrontmatterScenario, SpecComplianceResult } from '../../types/validation-evidence.js';
+import type { DoneDriftMissingFileFinding, FrontmatterScenario, SpecComplianceResult } from '../../types/validation-evidence.js';
 /** A sanitized terminal adapter failure that cannot be mistaken for a failed test verdict. */
 export declare class ComplianceCommandTerminalError extends Error {
     readonly code: string;
@@ -8,4 +8,5 @@ export declare class ComplianceCommandTerminalError extends Error {
 export declare function parseFrontmatterScenarios(raw: string): FrontmatterScenario[];
 export declare function runSpecCompliance(spec: Spec, projectPath: string, signal?: AbortSignal, canonicalProjectId?: string): Promise<SpecComplianceResult>;
 export declare function findScenariosWithoutTests(raw: string): string[];
+export declare function findDoneDriftMissingFiles(spec: Spec, raw: string, projectPath: string, fileExists: (path: string) => boolean): DoneDriftMissingFileFinding[];
 //# sourceMappingURL=spec-compliance-runner.d.ts.map

package/dist/engine/validator/spec-compliance-runner.js

@@ -502,7 +502,13 @@ export async function runSpecCompliance(spec, projectPath, signal, canonicalProj
         raw = await readFile(spec.specPath, 'utf-8');
     }
     catch {
-        return { dimensionScore: 0, perScenario: [], command: '', evidenceSource: 'none' };
+        return {
+            dimensionScore: 0,
+            perScenario: [],
+            command: '',
+            evidenceSource: 'none',
+            doneDriftFindings: [],
+        };
     }
     const frontmatterScenarios = parseFrontmatterScenarios(raw);
     const executableEvidence = normalizeExecutableEvidence(raw, frontmatterScenarios, (path) => existsSync(join(projectPath, path)));
@@ -513,6 +519,7 @@ export async function runSpecCompliance(spec, projectPath, signal, canonicalProj
             done: false,
             tests: scenario.tests.map((test) => ({ path: test.path })).filter(isExecutableTestLink),
         }));
+    const doneDriftFindings = findDoneDriftMissingFiles(spec, raw, projectPath, existsSync);
     if (scenarios.length === 0) {
         return {
             dimensionScore: 0,
@@ -520,6 +527,7 @@ export async function runSpecCompliance(spec, projectPath, signal, canonicalProj
             command: '',
             evidenceSource: executableEvidence.source,
             ignoredCriteriaTitles: executableEvidence.ignoredCriteriaTitles,
+            doneDriftFindings,
         };
     }
     const allLinks = scenarios.flatMap((scenario) => scenario.tests ?? []);
@@ -633,6 +641,7 @@ export async function runSpecCompliance(spec, projectPath, signal, canonicalProj
             `${technologyValue('technology-vitest-a9127f')} --reporter=json --run (no test files linked)`,
         evidenceSource: executableEvidence.source,
         ignoredCriteriaTitles: executableEvidence.ignoredCriteriaTitles,
+        doneDriftFindings,
     };
 }
 export function findScenariosWithoutTests(raw) {
@@ -640,4 +649,72 @@ export function findScenariosWithoutTests(raw) {
         .filter((scenario) => !scenario.tests?.length)
         .map((scenario) => scenario.title);
 }
+const DONE_DRIFT_ELIGIBLE_PREFIXES = ['src/', 'scripts/', 'tests/'];
+const FILES_MARKER = /FILES:\s*([^\n]*)/g;
+const NEXT_MARKER_KEYWORD = /\s+(?:TEST|FUNCTIONS|AND|GIVEN|WHEN|THEN):/;
+const FILES_SECTION_HEADING = /^##\s+Files\s*$/m;
+const MARKDOWN_SECTION_HEADING = /^##\s+\S/m;
+const BACKTICKED_LIST_ITEM = /^-\s+`([^`]+)`/;
+function normalizeDoneDriftCandidate(segment) {
+    const trimmed = segment.trim().replace(/^`|`$/g, '');
+    return trimmed.endsWith('.') ? trimmed.slice(0, -1) : trimmed;
+}
+function isDoneDriftEligiblePath(path) {
+    return DONE_DRIFT_ELIGIBLE_PREFIXES.some((prefix) => path.startsWith(prefix));
+}
+const DONE_DRIFT_GLOB_CHARACTER = /[*?[]/;
+const DONE_DRIFT_FILE_EXTENSION = /\.\w{1,6}$/;
+function isDoneDriftCheckablePath(path) {
+    return (!DONE_DRIFT_GLOB_CHARACTER.test(path) &&
+        !path.endsWith('/') &&
+        DONE_DRIFT_FILE_EXTENSION.test(path));
+}
+function extractFilesMarkerPaths(raw) {
+    const paths = [];
+    for (const match of raw.matchAll(FILES_MARKER)) {
+        const rest = match[1] ?? '';
+        const boundary = NEXT_MARKER_KEYWORD.exec(rest);
+        const segment = boundary ? rest.slice(0, boundary.index) : rest;
+        for (const item of segment.split(',')) {
+            const candidate = normalizeDoneDriftCandidate(item);
+            if (candidate) {
+                paths.push(candidate);
+            }
+        }
+    }
+    return paths;
+}
+function extractFilesSectionPaths(raw) {
+    const sectionMatch = FILES_SECTION_HEADING.exec(raw);
+    if (!sectionMatch) {
+        return [];
+    }
+    const rest = raw.slice(sectionMatch.index + sectionMatch[0].length);
+    const nextSection = MARKDOWN_SECTION_HEADING.exec(rest);
+    const body = nextSection ? rest.slice(0, nextSection.index) : rest;
+    const paths = [];
+    for (const line of body.split('\n')) {
+        const itemMatch = BACKTICKED_LIST_ITEM.exec(line.trim());
+        if (itemMatch?.[1]) {
+            paths.push(normalizeDoneDriftCandidate(itemMatch[1]));
+        }
+    }
+    return paths;
+}
+export function findDoneDriftMissingFiles(spec, raw, projectPath, fileExists) {
+    if (spec.status !== 'done') {
+        return [];
+    }
+    const candidates = new Set([...extractFilesMarkerPaths(raw), ...extractFilesSectionPaths(raw)]);
+    const findings = [];
+    for (const candidate of candidates) {
+        if (!isDoneDriftEligiblePath(candidate) || !isDoneDriftCheckablePath(candidate)) {
+            continue;
+        }
+        if (!fileExists(join(projectPath, candidate))) {
+            findings.push({ kind: 'done-drift-missing-files', specId: spec.id, missingPath: candidate });
+        }
+    }
+    return findings;
+}
 //# sourceMappingURL=spec-compliance-runner.js.map

package/dist/index.js

@@ -84,6 +84,27 @@ function scheduleStartupStateRecovery(startupSync, recoverPendingPostCommitTasks
         recoverValidateJobsAtStartup();
     });
 }
+const MCP_HOST_MARKERS = [
+    ['claude-code', 'claude-code'],
+    ['claude-code', 'claude code'],
+    ['claude-desktop', 'claude-desktop'],
+    ['claude-desktop', 'claude desktop'],
+    ['cursor', 'cursor'],
+    ['codex', 'codex'],
+];
+/** Maps the MCP client's reported implementation name to the envelope's allowlisted mcpHost. */
+function resolveMcpHost(clientName) {
+    if (!clientName) {
+        return 'unknown';
+    }
+    const normalized = clientName.toLowerCase();
+    for (const [host, marker] of MCP_HOST_MARKERS) {
+        if (normalized.includes(marker)) {
+            return host;
+        }
+    }
+    return 'other';
+}
 // Loads post-handshake modules after the MCP handshake has completed.
 // Separated from main() to keep main() within the 80-line function budget.
 async function setupPostHandshake(handshakeGate, officialToolNames) {
@@ -109,6 +130,11 @@ async function setupPostHandshake(handshakeGate, officialToolNames) {
     if (clientVersion) {
         setConnectedClient(clientVersion);
     }
+    // SPEC-1704: emit the mcp_server_started envelope now that the client is known.
+    const { sendTelemetryEnvelopeEvent } = await import('./engine/telemetry/telemetry-client.js');
+    sendTelemetryEnvelopeEvent('mcp_server_started', {
+        mcpHost: resolveMcpHost(clientVersion?.name),
+    });
     // SPEC-251: Check npm registry for newer version (fire-and-forget, 24h cache)
     checkForUpdates().catch(() => {
         /* best-effort */

package/dist/storage/migrations/canonical-storage.js

@@ -61,6 +61,7 @@ async function listFiles(root, current = root) {
     }
     return files;
 }
+const ATOMIC_WRITE_TEMP_SUFFIX = /\.tmp\.\d+\.[0-9a-f]{8}$/;
 export async function inventoryStorageRoot(rootInput) {
     const root = assertAbsolute(rootInput, 'inventory root');
     const info = await lstat(root);
@@ -70,7 +71,19 @@ export async function inventoryStorageRoot(rootInput) {
     const files = [];
     let totalBytes = 0;
     for (const path of await listFiles(root)) {
-        const content = await readFile(path);
+        if (ATOMIC_WRITE_TEMP_SUFFIX.test(path)) {
+            continue;
+        }
+        let content;
+        try {
+            content = await readFile(path);
+        }
+        catch (error) {
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                continue;
+            }
+            throw error;
+        }
         const relativePath = relative(root, path).split(sep).join('/');
         files.push({ relativePath, size: content.byteLength, sha256: sha256(content) });
         totalBytes += content.byteLength;
@@ -218,17 +231,17 @@ async function retireCompletedJournalForNewSources(journalPath, expected) {
     }
     try {
         const previous = validateJournal(parsed, { ...expected, legacyRoots: previousRoots });
-        if (!rootsChanged) {
+        if (previous.phase === 'completed') {
+            if (rootsChanged) {
+                await inventoryStorageRoot(expected.destinationRoot);
+            }
+            await rm(journalPath, { force: true });
             return;
         }
-        if (previous.phase !== 'completed') {
-            throw new Error('[Planu] Active migration journal does not match requested roots');
+        if (!rootsChanged) {
+            return;
         }
-        // A completed destination remains live and may legitimately receive newer
-        // canonical records. Re-inventory its real directory instead of requiring
-        // the historical generation digest to remain frozen forever.
-        await inventoryStorageRoot(expected.destinationRoot);
-        await rm(journalPath, { force: true });
+        throw new Error('[Planu] Active migration journal does not match requested roots');
     }
     catch (error) {
         if (!isTerminalPhaseValue(record.phase)) {

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 ?? []);
 }
 /**
@@ -230,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
@@ -249,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/init-project/handler.js

@@ -46,7 +46,7 @@ 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 { 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 = [
@@ -219,7 +219,7 @@ export async function handleInitProject(params, server) {
             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);
+            scheduleHousekeepingSweeps(projectPath);
             const authorizedMigrations = params.authorizedMigrations ?? [];
             if (isUpdate && authorizedMigrations.length === 0) {
                 const reconciliation = await reconcilePortableSpecIndex(projectPath, projectId);

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

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