@planu/cli 5.5.3 → 5.7.0

package/dist/engine/telemetry/error-reporter.js

@@ -3,8 +3,7 @@
 // Fire-and-forget. Sends sanitized error info to Supabase on unhandled tool exceptions.
 // Opt-out: set PLANU_TELEMETRY=off to disable remote reporting.
 // No PII: only tool name, sanitized error message, version, and Node version are sent.
-import { sendTelemetryEvent } from './telemetry-client.js';
-import { PLANU_VERSION } from '../../config/version.js';
+import { sendTelemetryEnvelopeEvent } from './telemetry-client.js';
 import { redactText } from '../../security/redactor.js';
 import { TELEMETRY_CONSENT_VERSION } from './telemetry-store.js';
 /**
@@ -31,58 +30,40 @@ const BLOCKED_PATTERNS = [
     'does not meet',
 ];
 /**
- * Classifies a telemetry event as tool_blocked or tool_error.
- * Gate blocks (DoD, validate score, spec locked, invalid transition) → tool_blocked.
- * Unhandled exceptions → tool_error.
+ * Classifies a telemetry event as blocked or error, mapping onto the envelope's `result` field.
+ * Gate blocks (DoD, validate score, spec locked, invalid transition) → blocked.
+ * Unhandled exceptions → error.
  */
 export function classifyToolEvent(errorMessage, errorType) {
     if (errorType === 'validation' || errorType === 'gate') {
-        return 'tool_blocked';
+        return 'blocked';
     }
     if (BLOCKED_PATTERNS.some((pattern) => errorMessage.includes(pattern))) {
-        return 'tool_blocked';
+        return 'blocked';
     }
-    return 'tool_error';
+    return 'error';
 }
 /**
- * Sends a tool_error event to Supabase. Fire-and-forget — never throws.
+ * Emits an mcp_tool_failed envelope for an unhandled exception. Fire-and-forget — never throws.
+ * The envelope has no message field in Phase 1, so no error text is ever transmitted.
  * Call this from safe-handler catch blocks after returning isError:true to the user.
  */
-export function reportToolError(toolName, error) {
+export function reportToolError(toolName, _error) {
     if (process.env.PLANU_TELEMETRY === 'off') {
         return;
     }
-    const errorClass = error instanceof Error ? error.name : typeof error;
-    sendTelemetryEvent({
-        event: 'tool_error',
-        properties: {
-            tool: toolName,
-            errorType: 'exception',
-            errorClass,
-            planVersion: PLANU_VERSION,
-            nodeVersion: process.version,
-        },
-    });
+    sendTelemetryEnvelopeEvent('mcp_tool_failed', { toolName, result: 'error' });
 }
 /**
- * Sends a tool_error or tool_blocked event for business-logic validation failures.
- * Gate/policy blocks (DoD, spec locked, invalid transitions) emit tool_blocked.
- * Other expected errors (missing params, not-found, etc.) emit tool_error.
+ * Emits an mcp_tool_failed envelope for a business-logic validation failure, classifying
+ * `result` as blocked (gate/policy blocks) or error (other expected failures).
  * Fire-and-forget — never throws.
  */
 export function reportToolValidationError(toolName, message) {
     if (process.env.PLANU_TELEMETRY === 'off') {
         return;
     }
-    const event = classifyToolEvent(message, 'validation');
-    sendTelemetryEvent({
-        event,
-        properties: {
-            tool: toolName,
-            errorType: 'validation',
-            planVersion: PLANU_VERSION,
-            nodeVersion: process.version,
-        },
-    });
+    const result = classifyToolEvent(message, 'validation');
+    sendTelemetryEnvelopeEvent('mcp_tool_failed', { toolName, result });
 }
 //# sourceMappingURL=error-reporter.js.map

package/dist/engine/telemetry/event-envelope.d.ts

@@ -0,0 +1,11 @@
+import type { TelemetryEnvelopeV1, TelemetryEnvelopeEventName, TelemetryEnvelopeInput, TelemetryEnvelopeBuildOptions, TelemetryDurationBucket } from '../../types/index.js';
+/** Ephemeral per-process session id, generated once at module load. */
+export declare const TELEMETRY_SESSION_ID: `${string}-${string}-${string}-${string}-${string}`;
+export declare function bucketDuration(durationMs: number): TelemetryDurationBucket;
+/**
+ * Builds a schemaVersion-1 telemetry envelope with exactly the allowlisted fields.
+ * Unknown fields on `fields` and unknown enum values are rejected (throw), never stored.
+ * `options.uuid`/`options.clock` make eventId/occurredAt deterministic for tests and `show`.
+ */
+export declare function buildTelemetryEnvelope(name: TelemetryEnvelopeEventName, fields: TelemetryEnvelopeInput, options?: TelemetryEnvelopeBuildOptions): TelemetryEnvelopeV1;
+//# sourceMappingURL=event-envelope.d.ts.map

package/dist/engine/telemetry/event-envelope.js

@@ -0,0 +1,124 @@
+// engine/telemetry/event-envelope.ts — SPEC-1704: versioned, allowlisted telemetry envelope v1.
+// Every field is typed and closed; unknown fields or enum values are rejected rather than
+// stored, so no free-form data (paths, args, spec content) has a code path into the envelope.
+import { randomUUID } from 'node:crypto';
+import { PLANU_VERSION } from '../../config/version.js';
+/** Ephemeral per-process session id, generated once at module load. */
+export const TELEMETRY_SESSION_ID = randomUUID();
+const EVENT_NAMES = new Set([
+    'installation_activated',
+    'mcp_server_started',
+    'mcp_tool_completed',
+    'mcp_tool_failed',
+    'spec_lifecycle_transitioned',
+    'release_check_completed',
+]);
+const RESULTS = new Set([
+    'success',
+    'error',
+    'blocked',
+    'cancelled',
+]);
+const MCP_HOSTS = new Set([
+    'claude-code',
+    'claude-desktop',
+    'cursor',
+    'codex',
+    'other',
+    'unknown',
+]);
+const OPERATING_SYSTEMS = new Set(['darwin', 'linux', 'win32']);
+const ALLOWED_INPUT_KEYS = new Set([
+    'anonymousInstallationId',
+    'sessionId',
+    'toolName',
+    'result',
+    'durationMs',
+    'mcpHost',
+]);
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+const MAX_TOOL_NAME_LENGTH = 64;
+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;
+const FAST_MS = 100;
+const MEDIUM_MS = 1_000;
+const SLOW_MS = 5_000;
+export function bucketDuration(durationMs) {
+    if (durationMs < FAST_MS) {
+        return 'lt_100ms';
+    }
+    if (durationMs < MEDIUM_MS) {
+        return '100ms_1s';
+    }
+    if (durationMs < SLOW_MS) {
+        return '1s_5s';
+    }
+    return 'gte_5s';
+}
+function resolveOperatingSystem() {
+    return OPERATING_SYSTEMS.has(process.platform)
+        ? process.platform
+        : 'other';
+}
+function resolveNodeMajor() {
+    return Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+}
+function rejectUnknownFields(fields) {
+    for (const key of Object.keys(fields)) {
+        if (!ALLOWED_INPUT_KEYS.has(key)) {
+            throw new Error(`Rejected telemetry event: unknown field "${key}"`);
+        }
+    }
+}
+function rejectUnknownEnumValues(fields) {
+    if (fields.result !== undefined && !RESULTS.has(fields.result)) {
+        throw new Error(`Rejected telemetry event: unknown result "${fields.result}"`);
+    }
+    if (fields.mcpHost !== undefined && !MCP_HOSTS.has(fields.mcpHost)) {
+        throw new Error(`Rejected telemetry event: unknown mcpHost "${fields.mcpHost}"`);
+    }
+    if (fields.toolName !== undefined &&
+        fields.toolName !== '' &&
+        (fields.toolName.length > MAX_TOOL_NAME_LENGTH || !TOOL_NAME_PATTERN.test(fields.toolName))) {
+        throw new Error(`Rejected telemetry event: unknown toolName "${fields.toolName}"`);
+    }
+    if (!UUID_V4_PATTERN.test(fields.anonymousInstallationId)) {
+        throw new Error('Rejected telemetry event: malformed anonymousInstallationId');
+    }
+}
+/**
+ * Builds a schemaVersion-1 telemetry envelope with exactly the allowlisted fields.
+ * Unknown fields on `fields` and unknown enum values are rejected (throw), never stored.
+ * `options.uuid`/`options.clock` make eventId/occurredAt deterministic for tests and `show`.
+ */
+export function buildTelemetryEnvelope(name, fields, options = {}) {
+    if (!EVENT_NAMES.has(name)) {
+        throw new Error(`Rejected telemetry event: unknown eventName "${name}"`);
+    }
+    rejectUnknownFields(fields);
+    rejectUnknownEnumValues(fields);
+    const uuid = options.uuid ?? randomUUID;
+    const clock = options.clock ?? (() => new Date());
+    const envelope = {
+        schemaVersion: 1,
+        eventId: uuid(),
+        eventName: name,
+        occurredAt: clock().toISOString(),
+        anonymousInstallationId: fields.anonymousInstallationId,
+        sessionId: fields.sessionId,
+        planuVersion: PLANU_VERSION,
+        operatingSystem: resolveOperatingSystem(),
+        nodeMajor: resolveNodeMajor(),
+        mcpHost: fields.mcpHost ?? 'unknown',
+    };
+    if (fields.toolName !== undefined && fields.toolName !== '') {
+        envelope.toolName = fields.toolName;
+    }
+    if (fields.result !== undefined) {
+        envelope.result = fields.result;
+    }
+    if (fields.durationMs !== undefined) {
+        envelope.durationBucket = bucketDuration(fields.durationMs);
+    }
+    return envelope;
+}
+//# sourceMappingURL=event-envelope.js.map

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

@@ -1,4 +1,11 @@
-import type { TelemetryEvent } from '../../types/index.js';
+import type { TelemetryEvent, TelemetryEnvelopeEventName, TelemetryEnvelopeInput } from '../../types/index.js';
 /** Fire-and-forget; absence or staleness of opt-in prevents any network access. */
 export declare function sendTelemetryEvent(event: TelemetryEvent): void;
+/**
+ * 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 declare function sendTelemetryEnvelopeEvent(name: TelemetryEnvelopeEventName, fields: Omit<TelemetryEnvelopeInput, 'anonymousInstallationId' | 'sessionId'>): void;
 //# sourceMappingURL=telemetry-client.d.ts.map

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/universal-rules/rules/planu-release-policy.js

@@ -19,7 +19,7 @@ When implementation changes are complete and validated, always address release e
 - local validation commands passed
 - changelog or release notes updated when applicable
 - package version and git tag stay aligned
-- release metadata under \`planu/releases/pending.json\` contains only genuinely pending entries
+- release metadata under the \`releases\` field of \`planu/project.json\` contains only genuinely pending entries
 - published package smoke check is run after release when applicable
 
 ## Hard Blocks

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

@@ -24,6 +24,41 @@ const FILE_EXTENSION = /\.[A-Za-z0-9]+$/;
 function isPathShapedSegment(segment) {
     return segment.length > 0 && (PATH_SHAPED.test(segment) || FILE_EXTENSION.test(segment));
 }
+function splitInlineArrayItems(content) {
+    const items = [];
+    let current = '';
+    let quote = null;
+    for (const char of content) {
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else {
+                current += char;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === ',') {
+            items.push(current);
+            current = '';
+            continue;
+        }
+        current += char;
+    }
+    items.push(current);
+    return items;
+}
+function parseInlineTestLinks(bracketContent) {
+    return splitInlineArrayItems(bracketContent)
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0)
+        .map((item) => parseTestLinkString(item))
+        .filter((link) => link !== null);
+}
 function parseTestLinkString(raw) {
     if (WINDOWS_DRIVE_PATH.test(raw)) {
         return { path: raw };
@@ -104,6 +139,16 @@ export function parseFrontmatterScenarios(raw) {
             inSteps = false;
             continue;
         }
+        const inlineTestsMatch = /^\s+tests:\s*\[(.*)\]\s*$/.exec(trimmed);
+        if (inlineTestsMatch) {
+            currentScenario.tests = [
+                ...(currentScenario.tests ?? []),
+                ...parseInlineTestLinks(inlineTestsMatch[1] ?? ''),
+            ];
+            inTests = false;
+            inSteps = false;
+            continue;
+        }
         if (/^\s+steps:\s*$/.test(trimmed)) {
             currentScenario.steps ??= [];
             inSteps = true;
@@ -457,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)));
@@ -468,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,
@@ -475,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 ?? []);
@@ -588,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) {
@@ -595,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