@planu/cli 5.6.0 → 5.7.0

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/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/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

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/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;
@@ -150,4 +151,37 @@ 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/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