@planu/cli 5.6.0 → 5.7.1

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/validate.js

@@ -58,6 +58,7 @@ import { compactObj } from '../engine/compact-obj.js';
 import { resolveProjectId, missingProjectIdError } from './resolve-project-id.js';
 import { specStore, knowledgeStore } from '../storage/index.js';
 import { validateSpec, generateDoR, generateDoD } from '../engine/validator.js';
+import { scanCodeForSpec } from '../engine/validator/analyzer.js';
 import { isBlockingQualitySeverity } from '../engine/validator/dor-dod.js';
 import { readVerifiedImplementationReview } from '../engine/handoff-artifacts/implementation-review-reader.js';
 import { calcQualityScore } from '../engine/auditor-scoring.js';
@@ -69,6 +70,7 @@ import { parseConventions, scanConventions } from '../engine/convention-scanner/
 import { validateScopeCompliance } from '../engine/scope-boundaries/index.js';
 import { compareWithBaseline } from '../storage/convention-baseline.js';
 import { writeImplementationReviewReport } from '../engine/validator/validation-report-writer.js';
+import { runReliabilityGate } from '../engine/validator/reliability-gate.js';
 import { buildGraphCoverageReport, formatGraphCoverageText } from './validate-graph-coverage.js';
 import { buildMinimalityReport } from './validate-minimality.js';
 import { buildValidateFailureFallback, validateStrictLayoutOrError } from './validate-helpers.js';
@@ -85,7 +87,7 @@ import { getRuntimePolicy } from '../engine/runtime-policy.js';
 import { resolveValidationWorktree, ValidationWorktreeError, } from '../engine/validation/validation-worktree.js';
 // Re-export for external use (SPEC-018)
 export { validateContractCompliance };
-const VALIDATION_GATE_TOTAL = 8;
+const VALIDATION_GATE_TOTAL = 9;
 const GATE_DEADLINE_EXEMPT_PHASES = new Set(['lint', 'compliance']);
 async function runWithGateDeadline(phase, command, work) {
     if (GATE_DEADLINE_EXEMPT_PHASES.has(phase)) {
@@ -360,6 +362,10 @@ export async function executeValidate(args, server, onProgress) {
     });
     const implementationQualityScore = calcQualityScore(result.qualityIssues);
     const auditedFiles = [...new Set(result.qualityIssues.map((i) => i.file))];
+    const reliabilityGate = await runStage('reliability', 'scripts/check-reliability-policies.mjs --json', async () => {
+        const codeState = await scanCodeForSpec(executionSpec, projectPath);
+        return runReliabilityGate(projectPath, codeState.affectedFiles);
+    });
     const { conventionViolations, regressionDetected } = await runStage('conventions', 'validate project conventions', () => scanProjectConventions(projectId, projectPath));
     const lintCheck = await runStage('lint', knowledge.lintCommand ?? 'pnpm lint', () => runLintCheck(projectPath, knowledge.lintCommand ?? null, {
         projectId,
@@ -397,6 +403,7 @@ export async function executeValidate(args, server, onProgress) {
         lintPassed: lintCheck.passed,
         assurancePassed: assuranceGates.newCode.passed,
         minimalityBlocked: minimalityReport?.blocked === true,
+        reliabilityPassed: reliabilityGate.passed,
         score: effectiveResult.score,
     });
     const output = {
@@ -492,6 +499,26 @@ export async function executeValidate(args, server, onProgress) {
             });
         }
     }
+    for (const failure of reliabilityGate.failures) {
+        output.qualityIssues.push({
+            file: failure.file,
+            line: failure.line,
+            severity: 'critical',
+            rule: failure.rule,
+            message: `Reliability gate violation: ${failure.rule}`,
+            suggestion: 'Fix the release-gate reliability violation before marking this spec done.',
+        });
+    }
+    for (const warning of reliabilityGate.warnings) {
+        output.qualityIssues.push({
+            file: warning.file,
+            line: warning.line,
+            severity: 'warning',
+            rule: warning.rule,
+            message: `Reliability gate violation in an unrelated file: ${warning.rule}`,
+            suggestion: 'Not blocking this spec — file is outside the spec Files section.',
+        });
+    }
     // Auto-suggest corrective actions based on validation results
     // score is null when no criteria can be extracted — treat as 0 for comparisons.
     const scoreValue = effectiveResult.score ?? 0;
@@ -523,6 +550,12 @@ export async function executeValidate(args, server, onProgress) {
     if (!lintCheck.passed) {
         suggestions.push(`Lint check failed: ${lintCheck.issueCount} issue(s) found via \`${lintCheck.command}\`. Fix before marking as done.`);
     }
+    if (reliabilityGate.executionError !== undefined) {
+        suggestions.push(`Reliability gate could not run: ${reliabilityGate.executionError}. Fix the gate before marking as done.`);
+    }
+    else if (!reliabilityGate.passed) {
+        suggestions.push(`Reliability gate failed: ${String(reliabilityGate.failures.length)} violation(s) in this spec's files. Fix before marking as done.`);
+    }
     if (!assuranceGates.newCode.passed) {
         suggestions.push(`Assurance gate failed: ${String(assuranceGates.newCode.findings.length)} new-code domain inference issue(s) found.`);
     }
@@ -673,6 +706,7 @@ function buildQualityGateSummary(input) {
         ...(!input.lintPassed ? ['lint'] : []),
         ...(!input.assurancePassed ? ['assurance'] : []),
         ...(input.minimalityBlocked ? ['minimality'] : []),
+        ...(!input.reliabilityPassed ? ['reliability'] : []),
     ];
     return {
         passed: failures.length === 0,
@@ -683,6 +717,7 @@ function buildQualityGateSummary(input) {
         lintPassed: input.lintPassed,
         assurancePassed: input.assurancePassed,
         minimalityPassed: !input.minimalityBlocked,
+        reliabilityPassed: input.reliabilityPassed,
     };
 }
 function buildExecutableCoverage(specCompliance) {

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

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

@@ -109,6 +109,8 @@ export interface UpdateStatusInput {
      * When true, the transition proceeds and qualityWarnings[] is written to spec.md frontmatter.
      */
     forceApprove?: boolean;
+    /** Marker set by reconcile_spec's declared-drift route; accepts the declared reason as reconciliation evidence in place of validation-report.json. */
+    declaredDriftKind?: 'architectural-premise';
 }
 /**
  * SPEC-769: Output from the readiness gate check in update_status(approved).
@@ -159,12 +161,19 @@ export interface GenerateChecklistInput {
     focus?: ChecklistCategory[];
     experienceLevel?: 'beginner' | 'expert';
 }
+/** An orchestrator-declared drift that produces no auto-detectable file/scope change. */
+export interface DeclaredSpecDrift {
+    kind: 'architectural-premise';
+    /** Why the implementation drifted from the approved premise. Minimum 100 characters. */
+    reason: string;
+}
 export interface ReconcileSpecInput {
     specId: string;
     projectId: string;
     autoDetect?: boolean;
     livingSpec?: boolean;
     changes?: ReconcileChange[];
+    declaredDrift?: DeclaredSpecDrift;
 }
 export interface ClarifyRequirementsInput {
     projectId: string;

package/dist/types/telemetry.d.ts

@@ -4,11 +4,47 @@ export interface GeoData {
     city: string;
     timezone: string;
 }
+/** SPEC-1704: the six allowlisted schemaVersion-1 envelope event names. */
+export type TelemetryEnvelopeEventName = 'installation_activated' | 'mcp_server_started' | 'mcp_tool_completed' | 'mcp_tool_failed' | 'spec_lifecycle_transitioned' | 'release_check_completed';
 export type TelemetryEventName = 'init_project' | 'create_spec' | 'tool_used' | 'tool_error' | 'tool_blocked'
 /** SPEC-705: Emitted when agent parallelism is downgraded due to host RAM constraints. */
  | 'ram_guardrail_downgrade'
 /** SPEC-727: Emitted when a panel is aborted because two specialists share the same (modelId, promptHash). */
- | 'panel_heterogeneity_violation';
+ | 'panel_heterogeneity_violation' | TelemetryEnvelopeEventName;
+export type TelemetryEnvelopeResult = 'success' | 'error' | 'blocked' | 'cancelled';
+export type TelemetryDurationBucket = 'lt_100ms' | '100ms_1s' | '1s_5s' | 'gte_5s';
+export type TelemetryOperatingSystem = 'darwin' | 'linux' | 'win32' | 'other';
+export type TelemetryMcpHost = 'claude-code' | 'claude-desktop' | 'cursor' | 'codex' | 'other' | 'unknown';
+/** SPEC-1704: the exact, closed shape of a schemaVersion-1 telemetry event. */
+export interface TelemetryEnvelopeV1 {
+    schemaVersion: 1;
+    eventId: string;
+    eventName: TelemetryEnvelopeEventName;
+    occurredAt: string;
+    anonymousInstallationId: string;
+    sessionId: string;
+    planuVersion: string;
+    toolName?: string;
+    result?: TelemetryEnvelopeResult;
+    durationBucket?: TelemetryDurationBucket;
+    operatingSystem: TelemetryOperatingSystem;
+    nodeMajor: number;
+    mcpHost: TelemetryMcpHost;
+}
+/** Caller-supplied fields for buildTelemetryEnvelope; unknown keys are rejected. */
+export interface TelemetryEnvelopeInput {
+    anonymousInstallationId: string;
+    sessionId: string;
+    toolName?: string;
+    result?: TelemetryEnvelopeResult;
+    durationMs?: number;
+    mcpHost?: TelemetryMcpHost;
+}
+/** Injectable determinism for tests and the `planu telemetry show` command. */
+export interface TelemetryEnvelopeBuildOptions {
+    uuid?: () => string;
+    clock?: () => Date;
+}
 export interface TelemetryConfig {
     enabled: boolean;
     /** ISO timestamp of when the user was first shown the opt-in prompt */
@@ -17,6 +53,8 @@ export interface TelemetryConfig {
     consentVersion?: number;
     /** SPEC-572: Opt-in to cross-project Observatory aggregated insights (requires telemetry enabled) */
     enableObservatory?: boolean;
+    /** SPEC-1704: generated on enable, deleted on disable, regenerated fresh on the next enable. */
+    anonymousInstallationId?: string;
 }
 export interface TelemetryEvent {
     event: TelemetryEventName;

package/dist/types/validation-evidence.d.ts

@@ -83,12 +83,18 @@ export interface PerScenarioResult {
     evidence: string[];
     unverifiable?: true;
 }
+export interface DoneDriftMissingFileFinding {
+    kind: 'done-drift-missing-files';
+    specId: string;
+    missingPath: string;
+}
 export interface SpecComplianceResult {
     dimensionScore: number;
     perScenario: PerScenarioResult[];
     command: string;
     evidenceSource?: 'frontmatter' | 'criteria' | 'none';
     ignoredCriteriaTitles?: string[];
+    doneDriftFindings?: DoneDriftMissingFileFinding[];
 }
 export interface EvidenceTestLink {
     path: string;
@@ -104,4 +110,16 @@ export interface ExecutableEvidence {
     unmappedCriteria: string[];
     ignoredCriteriaTitles: string[];
 }
+export interface ReliabilityGateViolation {
+    file: string;
+    line: number;
+    rule: string;
+}
+export interface ReliabilityGateResult {
+    skipped: boolean;
+    passed: boolean;
+    failures: ReliabilityGateViolation[];
+    warnings: ReliabilityGateViolation[];
+    executionError?: string;
+}
 //# sourceMappingURL=validation-evidence.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planu/cli",
-  "version": "5.6.0",
+  "version": "5.7.1",
   "description": "Planu — MCP Server for Spec Driven Development. Cross-platform (Linux/macOS/Windows, x64/arm64).",
   "type": "module",
   "main": "dist/index.js",

package/planu-plugin.json

@@ -2,7 +2,7 @@
   "name": "dev.planu.cli",
   "displayName": "Planu — Spec Driven Development",
   "description": "Manage software specs, estimations, and autonomous SDD workflows. Language-agnostic MCP server for Claude Code.",
-  "version": "5.6.0",
+  "version": "5.7.1",
   "icon": "assets/plugin/icon.svg",
   "command": ["npx", "@planu/cli@latest"],
   "packageName": "@planu/cli",