@planu/cli 4.14.1 → 5.0.0

package/dist/engine/spec-migrator/frontmatter-parser.js

@@ -3,34 +3,51 @@
 // --- Lightweight frontmatter parser ---
 const FM_RE = /^---\n([\s\S]*?)\n---\n/;
 const FM_KV_RE = /^(\w+):\s*(.+)$/;
+const FM_OBJECT_RE = /^(\w+):\s*$/;
+function parseScalar(val) {
+    if (val.startsWith('[') && val.endsWith(']')) {
+        return val
+            .slice(1, -1)
+            .split(',')
+            .map((item) => item.trim().replace(/^["']|["']$/g, ''));
+    }
+    if (val === 'null') {
+        return null;
+    }
+    if (/^\d+$/.test(val)) {
+        return parseInt(val, 10);
+    }
+    return val.replace(/^["']|["']$/g, '');
+}
 export function parseFrontmatterLocal(content) {
     const match = FM_RE.exec(content);
     if (!match?.[1]) {
         return { metadata: {} };
     }
     const metadata = {};
+    let activeObject = null;
     for (const line of match[1].split('\n')) {
-        const kv = FM_KV_RE.exec(line.trim());
+        const indent = line.length - line.trimStart().length;
+        const trimmed = line.trim();
+        const object = FM_OBJECT_RE.exec(trimmed);
+        if (object?.[1]) {
+            const value = {};
+            metadata[object[1]] = value;
+            activeObject = { indent, value };
+            continue;
+        }
+        const kv = FM_KV_RE.exec(trimmed);
         if (!kv?.[1] || kv[2] === undefined) {
             continue;
         }
         const key = kv[1];
         const val = kv[2].trim();
-        if (val.startsWith('[') && val.endsWith(']')) {
-            metadata[key] = val
-                .slice(1, -1)
-                .split(',')
-                .map((s) => s.trim().replace(/^["']|["']$/g, ''));
-        }
-        else if (val === 'null') {
-            metadata[key] = null;
-        }
-        else if (/^\d+$/.test(val)) {
-            metadata[key] = parseInt(val, 10);
-        }
-        else {
-            metadata[key] = val.replace(/^["']|["']$/g, '');
+        if (activeObject !== null && indent > activeObject.indent) {
+            activeObject.value[key] = parseScalar(val);
+            continue;
         }
+        activeObject = null;
+        metadata[key] = parseScalar(val);
     }
     return { metadata };
 }

package/dist/engine/spec-migrator/index.d.ts

@@ -3,6 +3,7 @@ export { filterUnprefixedSpecs, migrateSpecFolderNames } from './prefix-migratio
 export { discoverAndFlattenSpecs } from './flatten-specs.js';
 export { reconcileSpecPaths } from './reconcile-paths.js';
 export { importFilesystemSpecs } from './filesystem-import.js';
+export { buildCanonicalRepairPlan, repairDuplicateSpecIds, rollbackCanonicalRepair, } from './canonical-deduplicator.js';
 export { rewritePath, flattenSpecPath } from './path-utils.js';
 export { hasLegacyConfig } from './version-detection.js';
 export { validateMigrationResult, mergeMigrationResults, emptyMigrationResult, } from './migration-validator.js';

package/dist/engine/spec-migrator/index.js

@@ -9,6 +9,7 @@ export { discoverAndFlattenSpecs } from './flatten-specs.js';
 export { reconcileSpecPaths } from './reconcile-paths.js';
 // Import filesystem specs into the store
 export { importFilesystemSpecs } from './filesystem-import.js';
+export { buildCanonicalRepairPlan, repairDuplicateSpecIds, rollbackCanonicalRepair, } from './canonical-deduplicator.js';
 // Path utilities (re-exported for consumers that may depend on them)
 export { rewritePath, flattenSpecPath } from './path-utils.js';
 // Legacy config detection

package/dist/engine/spec-state-machine/transition-spec.d.ts

@@ -2,7 +2,7 @@ import type { Spec, SpecStatus } from '../../types/index.js';
 /**
  * Why this transition is happening — surfaces in audit-trail and transition_log.
  */
-export type TransitionTrigger = 'user' | 'auto-advance' | 'git-merge' | 'fs-hook' | 'sync-spec-state' | 'multi-teammate-review' | 'http' | 'dashboard' | 'reopen';
+export type TransitionTrigger = 'user' | 'auto-advance' | 'git-merge' | 'fs-hook' | 'sync-spec-state' | 'multi-teammate-review' | 'http' | 'dashboard' | 'reopen' | 'reconciliation';
 export interface TransitionContext {
     /** Why this transition is happening. */
     trigger: TransitionTrigger;
@@ -16,6 +16,11 @@ export interface TransitionContext {
     updates?: Omit<Partial<Spec>, 'status'>;
     /** Optional work scheduled after the durable transition boundary. */
     pendingBackgroundActions?: readonly string[];
+    /** Opaque binding to the selected root for post-commit recovery. */
+    transitionRootBinding?: string;
+    /** Dedicated recovery transaction binding persisted with its status entry. */
+    reconciliationRequestId?: string;
+    reconciliationBindingDigest?: string;
     /** Snapshot used by lifecycle gates; the store rejects intervening mutations. */
     expectedSpec?: Spec;
 }

package/dist/engine/spec-state-machine/transition-spec.js

@@ -20,7 +20,16 @@ export async function transitionSpec(projectId, specId, newStatus, ctx) {
         throw new Error(`Spec ${specId} not found in project ${projectId}`);
     }
     // Use the internal-only write path that bypasses the status guard
-    const after = await specStore.__internalSetStatus(projectId, specId, newStatus, ctx.updates, ctx.pendingBackgroundActions, { status: before.status, updatedAt: before.updatedAt });
+    const reconciliation = ctx.reconciliationRequestId === undefined
+        ? undefined
+        : {
+            reconciliationRequestId: ctx.reconciliationRequestId,
+            reconciliationBindingDigest: ctx.reconciliationBindingDigest,
+            trigger: ctx.trigger,
+        };
+    const after = reconciliation
+        ? await specStore.__internalSetStatus(projectId, specId, newStatus, ctx.updates, ctx.pendingBackgroundActions, { status: before.status, updatedAt: before.updatedAt }, ctx.transitionRootBinding, reconciliation)
+        : await specStore.__internalSetStatus(projectId, specId, newStatus, ctx.updates, ctx.pendingBackgroundActions, { status: before.status, updatedAt: before.updatedAt }, ctx.transitionRootBinding);
     const receipt = after.statusHistory?.at(-1);
     if (!receipt?.transitionId) {
         throw new Error(`Transition receipt was not persisted for ${specId}`);

package/dist/engine/technical-enricher/index.js

@@ -1,13 +1,19 @@
 // technical-enricher/index.ts — Agnostic enricher + disk runner (SPEC-696)
-import { readFile, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseTechnicalMd } from './parse-technical.js';
 import { detectSkip } from './skip-detector.js';
 import { extractSignatures } from './signature-extractor.js';
 import { scanTestPattern } from './test-pattern-scanner.js';
-import { renderEnriched } from './render-enriched.js';
+import { hasGeneratedEnrichment, renderEnriched } from './render-enriched.js';
+import { findMarkdownSectionRange } from '../spec-format/markdown-sections.js';
+import { resolveContainedProjectFile } from '../safety/contained-project-file.js';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
 export async function enrichTechnicalContent(input) {
     const { technicalContent, specScope, projectPath } = input;
+    if (hasGeneratedEnrichment(technicalContent)) {
+        return { enriched: false, reason: 'already-enriched' };
+    }
     const parsed = parseTechnicalMd(technicalContent);
     const skipReason = detectSkip(parsed, specScope);
     if (skipReason) {
@@ -42,20 +48,22 @@ async function runEnricherFromSpecSection(opts) {
     if (!specPath) {
         return;
     }
-    const specRaw = await readFile(specPath, 'utf8');
-    const sectionMatch = /\n## Technical\n([\s\S]*)$/.exec(specRaw);
-    if (!sectionMatch?.[1]) {
+    const physicalSpecPath = await resolveContainedProjectFile(opts.projectPath, specPath);
+    const specRaw = await readFile(physicalSpecPath, 'utf8');
+    const section = findMarkdownSectionRange(specRaw, 'Technical');
+    if (!section) {
         return;
     }
+    const technicalContent = specRaw.slice(section.contentStart, section.end);
     const result = await enrichTechnicalContent({
         specId: opts.specId,
         projectPath: opts.projectPath,
-        technicalContent: sectionMatch[1],
+        technicalContent,
         specScope: opts.specScope,
     });
     if (result.enriched && result.enrichedContent) {
-        const updated = specRaw.replace(/\n## Technical\n[\s\S]*$/, `\n## Technical\n\n${result.enrichedContent}`);
-        await writeFile(specPath, updated, 'utf8');
+        const updated = `${specRaw.slice(0, section.contentStart)}${result.enrichedContent}${specRaw.slice(section.end)}`;
+        await atomicWriteFile(physicalSpecPath, updated);
     }
 }
 //# sourceMappingURL=index.js.map

package/dist/engine/technical-enricher/render-enriched.d.ts

@@ -1,3 +1,4 @@
 import type { RenderInput } from '../../types/technical-enrichment.js';
+export declare function hasGeneratedEnrichment(content: string): boolean;
 export declare function renderEnriched(input: RenderInput): string;
 //# sourceMappingURL=render-enriched.d.ts.map

package/dist/engine/technical-enricher/render-enriched.js

@@ -1,18 +1,41 @@
 const MAX_CHARS = 3200;
-export function renderEnriched(input) {
-    const { originalContent, signatures, testSample } = input;
-    const lines = [
-        originalContent.trimEnd(),
-        '',
+const GENERATED_START = '<!-- planu:technical-enrichment:start -->';
+const GENERATED_END = '<!-- planu:technical-enrichment:end -->';
+export function hasGeneratedEnrichment(content) {
+    return (content.includes(GENERATED_START) ||
+        /^#{2,3}[ \t]+Real Signatures \(auto-extracted by SPEC-696\)[ \t]*$/m.test(content));
+}
+function appendGenerated(originalContent, blocks) {
+    const separator = originalContent.endsWith('\n') ? '' : '\n\n';
+    const generated = [
+        GENERATED_START,
         '---',
         '',
-        '## Real Signatures (auto-extracted by SPEC-696)',
-    ];
+        '### Real Signatures (auto-extracted by SPEC-696)',
+        ...blocks,
+        GENERATED_END,
+        '',
+        '',
+    ].join('\n');
+    return `${originalContent}${separator}${generated}`;
+}
+export function renderEnriched(input) {
+    const { originalContent, signatures, testSample } = input;
+    if (originalContent.length >= MAX_CHARS || hasGeneratedEnrichment(originalContent)) {
+        return originalContent;
+    }
+    const blocks = [];
+    const tryAppendBlock = (block) => {
+        const candidateBlocks = [...blocks, block];
+        if (appendGenerated(originalContent, candidateBlocks).length <= MAX_CHARS) {
+            blocks.push(block);
+        }
+    };
     for (const sig of signatures) {
         if (sig.exports.length === 0 && sig.interfaces.length === 0) {
             continue;
         }
-        lines.push('', `### \`${sig.relPath}\``, '```typescript');
+        const lines = ['', `#### \`${sig.relPath}\``, '```typescript'];
         for (const exp of sig.exports.slice(0, 5)) {
             lines.push(exp);
         }
@@ -20,15 +43,20 @@ export function renderEnriched(input) {
             lines.push(iface);
         }
         lines.push('```');
+        tryAppendBlock(lines.join('\n'));
     }
     if (testSample) {
-        lines.push('', '## Test Patterns (from existing tests)', `- Mock style: \`${testSample.mockStyle}\``, `- Has \`beforeEach\`: ${String(testSample.hasBeforeEach)}`);
+        tryAppendBlock([
+            '',
+            '### Test Patterns (from existing tests)',
+            `- Mock style: \`${testSample.mockStyle}\``,
+            `- Has \`beforeEach\`: ${String(testSample.hasBeforeEach)}`,
+        ].join('\n'));
     }
-    const result = lines.join('\n');
-    if (result.length <= MAX_CHARS) {
-        return result;
+    if (blocks.length === 0) {
+        return originalContent;
     }
-    return (result.slice(0, MAX_CHARS) +
-        '\n\n> [truncated — spec too large, enrich remaining files manually]');
+    const result = appendGenerated(originalContent, blocks);
+    return result.length <= MAX_CHARS ? result : originalContent;
 }
 //# sourceMappingURL=render-enriched.js.map

package/dist/engine/telemetry/health-checker.js

@@ -2,17 +2,18 @@
 // engine/telemetry/health-checker.ts — SPEC-346: Diagnose why telemetry data is not reaching the dashboard.
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { readTelemetryConfig } from './telemetry-store.js';
+import { isTelemetryEnabled } from './telemetry-store.js';
 import { sendTelemetryEvent } from './telemetry-client.js';
 import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
+import { networkFetch, withNetworkConsent } from '../network-policy.js';
 const NETWORK_TIMEOUT_MS = 5_000;
 const RECENT_EVENT_THRESHOLD_DAYS = 7;
 // ---------------------------------------------------------------------------
 // Individual checks
 // ---------------------------------------------------------------------------
 async function checkConfigEnabled() {
-    const config = await readTelemetryConfig();
-    if (!config?.enabled) {
+    const enabled = await isTelemetryEnabled();
+    if (!enabled) {
         return {
             check: {
                 name: 'config-enabled',
@@ -32,19 +33,46 @@ async function checkConfigEnabled() {
     };
 }
 function checkEndpointConfigured(endpoint) {
-    if (!endpoint || endpoint.trim() === '') {
+    if (!isValidTelemetryEndpoint(endpoint)) {
         return {
             name: 'endpoint-configured',
             status: 'fail',
-            detail: 'No telemetry endpoint configured. Set PLANU_TELEMETRY_ENDPOINT env var.',
+            detail: 'Telemetry endpoint is missing or invalid. Use HTTPS, or HTTP only for an explicit loopback host.',
         };
     }
     return {
         name: 'endpoint-configured',
         status: 'ok',
-        detail: `Endpoint: ${endpoint}`,
+        detail: 'Telemetry endpoint configured',
     };
 }
+function isLoopbackHost(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+function isValidTelemetryEndpoint(endpoint) {
+    if (!endpoint || endpoint.trim() === '') {
+        return false;
+    }
+    try {
+        const parsed = new URL(endpoint.trim());
+        return (parsed.username === '' &&
+            parsed.password === '' &&
+            (parsed.protocol === 'https:' ||
+                (parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname))));
+    }
+    catch {
+        return false;
+    }
+}
+function checkTokenConfigured(token) {
+    return token?.trim()
+        ? { name: 'token-configured', status: 'ok', detail: 'Telemetry token configured' }
+        : {
+            name: 'token-configured',
+            status: 'fail',
+            detail: 'Telemetry token is missing. Set PLANU_TELEMETRY_TOKEN env var.',
+        };
+}
 async function checkNetworkReachable(endpoint) {
     if (!endpoint) {
         return {
@@ -54,10 +82,10 @@ async function checkNetworkReachable(endpoint) {
         };
     }
     try {
-        const response = await fetch(endpoint, {
+        const response = await withNetworkConsent('telemetry', (receipt) => networkFetch(receipt, endpoint, {
             method: 'GET',
             signal: AbortSignal.timeout(NETWORK_TIMEOUT_MS),
-        });
+        }));
         if (response.ok || response.status < 500) {
             return {
                 name: 'network-reachable',
@@ -208,7 +236,7 @@ function buildRecommendation(status) {
         case 'disabled':
             return 'Run configure_telemetry to enable usage tracking';
         case 'misconfigured':
-            return 'Set PLANU_TELEMETRY_ENDPOINT or run configure_telemetry';
+            return 'Set valid PLANU_TELEMETRY_ENDPOINT and PLANU_TELEMETRY_TOKEN values.';
         case 'degraded':
             return 'Check network connectivity or firewall rules blocking outbound requests';
         case 'healthy':
@@ -232,8 +260,8 @@ function computeStatus(isEnabled, checks) {
     if (!isEnabled) {
         return 'disabled';
     }
-    const endpointCheck = checks.find((c) => c.name === 'endpoint-configured');
-    if (endpointCheck?.status === 'fail') {
+    const configurationChecks = checks.filter((check) => check.name === 'endpoint-configured' || check.name === 'token-configured');
+    if (configurationChecks.some((check) => check.status === 'fail')) {
         return 'misconfigured';
     }
     const hasWarn = checks.some((c) => c.status === 'warn');
@@ -257,26 +285,34 @@ export async function checkTelemetryHealth(projectPath, options) {
             humanSummary: buildHumanSummary(status, checks),
         };
     }
-    // Default endpoint from telemetry-client
-    const defaultEndpoint = 'https://canusqigtzldstnjddio.supabase.co/rest/v1/telemetry_events';
-    const endpoint = process.env.PLANU_TELEMETRY_ENDPOINT?.trim() ?? defaultEndpoint;
+    const endpoint = process.env.PLANU_TELEMETRY_ENDPOINT?.trim();
+    const token = process.env.PLANU_TELEMETRY_TOKEN;
+    const endpointCheck = checkEndpointConfigured(endpoint ?? '');
+    const tokenCheck = checkTokenConfigured(token);
+    const configured = endpointCheck.status === 'ok' && tokenCheck.status === 'ok';
     const [networkCheck, lastEventCheck, errorLogCheck, versionCheck] = await Promise.all([
-        checkNetworkReachable(endpoint),
+        configured
+            ? checkNetworkReachable(endpoint ?? '')
+            : Promise.resolve({
+                name: 'network-reachable',
+                status: 'skip',
+                detail: 'Skipped until endpoint and token configuration is valid',
+            }),
         checkLastEvent(projectPath),
         checkErrorLog(projectPath),
         checkClientVersion(projectPath),
     ]);
-    const endpointCheck = checkEndpointConfigured(endpoint);
     const checks = [
         enabledCheck,
         endpointCheck,
+        tokenCheck,
         networkCheck,
         lastEventCheck,
         errorLogCheck,
         versionCheck,
     ];
     const status = computeStatus(enabled, checks);
-    if (options?.sendTestEvent === true) {
+    if (options?.sendTestEvent === true && configured) {
         sendTestDiagnosticEvent();
     }
     return {

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

@@ -2,9 +2,27 @@
 import { networkFetch, withNetworkConsent } from '../network-policy.js';
 import { redactSensitiveValue } from '../../security/redactor.js';
 import { isTelemetryEnabled } from './telemetry-store.js';
-const SUPABASE_URL = 'https://canusqigtzldstnjddio.supabase.co';
-const SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImNhbnVzcWlndHpsZHN0bmpkZGlvIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI3NTk2MjgsImV4cCI6MjA4ODMzNTYyOH0.Thw1Xgf9_iabOD75J00u35d2k5NsIpUBU9PrqOShxMU';
-const TELEMETRY_ENDPOINT = `${SUPABASE_URL}/rest/v1/telemetry_events`;
+function isLoopbackHost(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]';
+}
+function isValidTelemetryEndpoint(endpoint) {
+    if (!endpoint || endpoint.trim() === '') {
+        return false;
+    }
+    try {
+        const parsed = new URL(endpoint.trim());
+        return (parsed.username === '' &&
+            parsed.password === '' &&
+            (parsed.protocol === 'https:' ||
+                (parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname))));
+    }
+    catch {
+        return false;
+    }
+}
+function isConfiguredTelemetryToken(token) {
+    return Boolean(token?.trim());
+}
 const ALLOWED_PROPERTIES = new Set([
     'allowed',
     'context',
@@ -37,16 +55,16 @@ function safeProperties(properties) {
 export function sendTelemetryEvent(event) {
     void isTelemetryEnabled()
         .then((enabled) => {
-        if (!enabled) {
+        const endpoint = process.env.PLANU_TELEMETRY_ENDPOINT?.trim();
+        const token = process.env.PLANU_TELEMETRY_TOKEN?.trim();
+        if (!enabled || !isValidTelemetryEndpoint(endpoint) || !isConfiguredTelemetryToken(token)) {
             return undefined;
         }
-        return withNetworkConsent('telemetry', (receipt) => networkFetch(receipt, TELEMETRY_ENDPOINT, {
+        return withNetworkConsent('telemetry', (receipt) => networkFetch(receipt, endpoint, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
-                apikey: SUPABASE_ANON_KEY,
-                Authorization: `Bearer ${SUPABASE_ANON_KEY}`,
-                Prefer: 'return=minimal',
+                Authorization: `Bearer ${token}`,
             },
             body: JSON.stringify({
                 event_name: event.event,

package/dist/engine/text-signal-boundaries.d.ts

@@ -1,5 +1,7 @@
 /** Remove fenced code and quoted examples before keyword-driven inference. */
 export declare function stripNonContractText(text: string): string;
+/** Remove clauses whose subject is detector analysis or test evidence, not product behavior. */
+export declare function stripMetaAnalysisText(text: string): string;
 /** True only when a regex match appears in contract prose and is not negated/excluded. */
 export declare function hasAffirmedMatch(text: string, pattern: RegExp): boolean;
 export declare function hasAnyAffirmedMatch(text: string, patterns: RegExp[]): boolean;

package/dist/engine/text-signal-boundaries.js

@@ -1,4 +1,5 @@
 // engine/text-signal-boundaries.ts — Boundary-aware keyword matching for advisory signals.
+import { stripFrontmatter } from './frontmatter-parser.js';
 const NEGATION_TERMS = new Set([
     'no',
     'not',
@@ -15,7 +16,15 @@ const NEGATION_TERMS = new Set([
 ]);
 const OUT_OF_SCOPE_RE = /\b(?:out\s+of\s+scope|not\s+in\s+scope|no\s+scope|do\s+not|don't)\b/i;
 const NON_AFFIRMING_CONTEXT_RE = /\b(?:false[ -]?positive|incorrect(?:ly)?|wrong(?:ly)?|irrelevant|unrelated|noise|repeated\s+failure)\b/i;
-const EXCLUDED_SECTION_RE = /^(?:out\s+of\s+scope|non[ -]?goals?|examples?|anticipated\s+test\s+breaks?)\b/i;
+const EXCLUDED_SECTION_RE = /^(?:out\s+of\s+scope|non[ -]?goals?|examples?|anticipated\s+test\s+breaks?|challenge\s+resolution)\b/i;
+const META_ANALYSIS_CLAUSE_BOUNDARY_RE = /(?:[.!?;。！？]\s+|\n+|,\s+(?:but|while|whereas)\s+)/iu;
+const META_ANALYSIS_SUBJECT_RE = /^\s*(?:[-*+>]\s+|\d+[.)]\s+)?(?:(?:given|when|then|and)\s+)?(?:(?:negative|positive)\s+examples?\s*:|(?:(?:the|this|that|a|an|any|each|our|existing|current)\s+)?(?:capability\s+)?(?:detector|classifier|matcher|challenge\s+(?:finding|selection|scenario)|regression\s+(?:test|fixture)|fixture|positive\s+control|expected\s+(?:absence|selection|result)|(?:tooling|test|regression)\s+spec|paired\s+product\s+specs|spec\s+(?:title|tag|criterion)|(?:dogfood\s+)?reproducer|documentation|prose|titles?|criteria|criterion)(?:\s|[:,])|(?:the|this|that|a|an|any|each|our|existing|current)?\s*table(?:\s+rows?)?\s+(?:contains?|pairs?|asserts?|names?|uses?)\b|(?:add|use|write|run|extend|preserve)\s+(?:(?:paired|table-driven|positive|negative|regression)\s+)*(?:tests?|fixtures?|examples?|assertions?|rows?)\b|(?:apply|reuse|compose)\s+(?:the\s+)?(?:shared\s+|generic\s+|meta-analysis\s+)?boundary\b)/iu;
+const ACTION_LED_META_ANALYSIS_RE = /^\s*(?:[-*+>]\s+|\d+[.)]\s+)?(?:fix|prevent|ignore|document|repair|correct|avoid|remove|stop|resolve|investigate|verify)\b(?=[^.!?。！？]{0,240}\b(?:detector|classifier|matcher)\b)(?=[^.!?。！？]{0,240}\b(?:false[ -]?positives?|expected\s+(?:absence|selection|result)|irrelevant\s+findings?|scenario\s+selection)\b)/iu;
+const META_ANALYSIS_EVIDENCE_RE = /\b(?:is|are|as)\s+(?:an?\s+)?(?:positive[ -]?control|regression|detector)\s+(?:evidence|fixtures?|examples?|findings?)\b/iu;
+const EXPECTED_META_ANALYSIS_RE = /^\s*expected\s*:(?=[^.!?。！？]{0,240}\b(?:detector|classifier|matcher|fixture|regression\s+test|expected\s+result)\b)/iu;
+const QUALIFIED_EVIDENCE_SUBJECT_RE = /^\s*(?:[-*+>]\s+|\d+[.)]\s+)?(?:(?:given|when|then|and)\s+)?(?=[^.!?。！？]{0,240}\b(?:positive|negative|affirmative|meta-analysis(?:-only)?|regression|table-driven)\b)(?=[^.!?。！？]{0,240}\b(?:fixtures?|controls?|tests?|examples?|assertions?|findings?)\b)[^.!?。！？]{1,240}$/iu;
+const CONTRACT_ANALYSIS_SUBJECT_RE = /^\s*(?:[-*+>]\s+|\d+[.)]\s+)?(?:(?:given|when|then|and)\s+)?(?:(?:the|this|that|a|an|any|each|our|existing|current)\s+)?(?:[\p{L}\p{N}_-]+\s+){0,2}contract\s+(?:evidence|inference|requirements?)\b/iu;
+const CONTRACT_ANALYSIS_PREDICATE_RE = /\b(?:(?:is|are)\s+(?:inferred|expected|selected|classified|matched|detected|discussed|reported|recorded)|expects?|records?|describes?)\b|\b(?:detector|classifier|matcher)\s+evidence\b|\b(?:positive[ -]?control|expected\s+absence|meta-analysis(?:-only)?)\b/iu;
 function stripExcludedMarkdownSections(text) {
     const lines = text.split('\n');
     const kept = [];
@@ -45,12 +54,26 @@ function stripExcludedMarkdownSections(text) {
 }
 /** Remove fenced code and quoted examples before keyword-driven inference. */
 export function stripNonContractText(text) {
-    return stripExcludedMarkdownSections(text)
+    return stripExcludedMarkdownSections(stripFrontmatter(text.replace(/^\uFEFF/, '')))
         .replace(/```[\s\S]*?```/g, ' ')
         .replace(/`[^`\n]+`/g, ' ')
         .replace(/"[^"\n]+"/g, ' ')
         .replace(/'[^'\n]+'/g, ' ');
 }
+/** Remove clauses whose subject is detector analysis or test evidence, not product behavior. */
+export function stripMetaAnalysisText(text) {
+    return text
+        .replace(/\n[\t ]+(?=[a-z0-9`])/giu, ' ')
+        .split(META_ANALYSIS_CLAUSE_BOUNDARY_RE)
+        .filter((clause) => clause.trim().length > 0 &&
+        !META_ANALYSIS_SUBJECT_RE.test(clause) &&
+        !ACTION_LED_META_ANALYSIS_RE.test(clause) &&
+        !META_ANALYSIS_EVIDENCE_RE.test(clause) &&
+        !EXPECTED_META_ANALYSIS_RE.test(clause) &&
+        !QUALIFIED_EVIDENCE_SUBJECT_RE.test(clause) &&
+        !(CONTRACT_ANALYSIS_SUBJECT_RE.test(clause) && CONTRACT_ANALYSIS_PREDICATE_RE.test(clause)))
+        .join('\n');
+}
 function clauseBefore(text, index) {
     const before = text.slice(Math.max(0, index - 320), index);
     const boundary = Math.max(before.lastIndexOf('\n'), before.lastIndexOf('.'), before.lastIndexOf(';'));

package/dist/engine/time/relative-date.d.ts

@@ -0,0 +1,3 @@
+/** Format a relative date string for a canonical timestamp. */
+export declare function formatRelativeDate(timestamp: string): string;
+//# sourceMappingURL=relative-date.d.ts.map

package/dist/engine/time/relative-date.js

@@ -0,0 +1,16 @@
+/** Format a relative date string for a canonical timestamp. */
+export function formatRelativeDate(timestamp) {
+    const date = new Date(timestamp);
+    const diffDays = Math.floor((Date.now() - date.getTime()) / (1000 * 60 * 60 * 24));
+    if (diffDays === 0) {
+        return 'hoy';
+    }
+    if (diffDays === 1) {
+        return 'hace 1 dia';
+    }
+    if (diffDays <= 30) {
+        return `hace ${String(diffDays)} dias`;
+    }
+    return timestamp.slice(0, 10);
+}
+//# sourceMappingURL=relative-date.js.map

package/dist/engine/timing/budget.d.ts

@@ -9,10 +9,21 @@ export declare function withBudget<T>(step: string, budgetMs: number, fn: (signa
 export declare function unwrapBudget<T>(result: BudgetResult<T>, fallback: T, warnings?: string[]): T;
 /** Applies the same cancellation tree to a complete operation ceiling. */
 export declare function withTotalBudget<T>(operationName: string, ceilingMs: number, fn: (signal: AbortSignal) => Promise<T>): Promise<{
+    status: 'ok';
     timedOut: false;
     value: T;
+    elapsedMs: number;
 } | {
+    status: 'failed';
+    timedOut: false;
+    category: 'operation_failed';
+    elapsedMs: number;
+    warning: string;
+} | {
+    status: 'timed_out';
     timedOut: true;
+    ceilingMs: number;
+    elapsedMs: number;
     warning: string;
 }>;
 //# sourceMappingURL=budget.d.ts.map

package/dist/engine/timing/budget.js

@@ -26,13 +26,21 @@ function executeWithinBudget(requestedMs, fn) {
             }
         };
         const onAbort = () => {
-            settle({ ok: false, error: new Error(errorMessage(scope.signal.reason)) });
+            settle({
+                ok: false,
+                error: new Error(errorMessage(scope.signal.reason)),
+                source: scope.didDeadlineElapse() ? 'deadline' : 'operation',
+            });
         };
         scope.signal.addEventListener('abort', onAbort, { once: true });
         task.then((value) => {
             settle({ ok: true, value });
         }, (error) => {
-            settle({ ok: false, error: error instanceof Error ? error : new Error(String(error)) });
+            settle({
+                ok: false,
+                error: error instanceof Error ? error : new Error(String(error)),
+                source: 'operation',
+            });
         });
         if (scope.signal.aborted) {
             onAbort();
@@ -60,7 +68,7 @@ export async function withBudget(step, budgetMs, fn) {
         if (outcome.ok) {
             return { exceeded: false, value: outcome.value, elapsedMs };
         }
-        const thrownBeforeDeadline = elapsedMs < execution.timeoutMs;
+        const thrownBeforeDeadline = outcome.source === 'operation';
         return {
             exceeded: true,
             step,
@@ -88,16 +96,26 @@ export async function withTotalBudget(operationName, ceilingMs, fn) {
     const execution = executeWithinBudget(ceilingMs, fn);
     try {
         const outcome = await execution.result;
+        const elapsedMs = elapsedSince(start);
         if (outcome.ok) {
-            return { timedOut: false, value: outcome.value };
+            return { status: 'ok', timedOut: false, value: outcome.value, elapsedMs };
+        }
+        const thrownBeforeDeadline = outcome.source === 'operation';
+        if (thrownBeforeDeadline) {
+            return {
+                status: 'failed',
+                timedOut: false,
+                category: 'operation_failed',
+                elapsedMs,
+                warning: `[SPEC-713] Operation "${operationName}" failed after ${String(elapsedMs)}ms (operation_failed)`,
+            };
         }
-        const elapsedMs = elapsedSince(start);
-        const thrownBeforeDeadline = elapsedMs < execution.timeoutMs;
         return {
+            status: 'timed_out',
             timedOut: true,
-            warning: thrownBeforeDeadline
-                ? `[SPEC-713] Operation "${operationName}" threw after ${String(elapsedMs)}ms: ${errorMessage(outcome.error)}`
-                : `[SPEC-713] Operation "${operationName}" exceeded ${String(execution.timeoutMs)}ms ceiling (actual: ${String(elapsedMs)}ms) — aborted cleanly`,
+            ceilingMs: execution.timeoutMs,
+            elapsedMs,
+            warning: `[SPEC-713] Operation "${operationName}" exceeded ${String(execution.timeoutMs)}ms ceiling (actual: ${String(elapsedMs)}ms) — aborted cleanly`,
         };
     }
     finally {

package/dist/engine/token-optimizer/analytics.d.ts

@@ -4,7 +4,7 @@ export declare function aggregateEntries(entries: LedgerEntry[]): LedgerAggregat
 export declare function computeDailyBreakdown(entries: LedgerEntry[]): DailyBreakdown[];
 export declare function detectTrend(dailyBreakdown: DailyBreakdown[]): TrendResult;
 export declare function detectAnomalies(entries: LedgerEntry[], dailyBreakdown: DailyBreakdown[]): Anomaly[];
-export declare function computeBudgetStatus(entries: LedgerEntry[], config: BudgetConfig): LedgerBudgetStatus;
+export declare function computeBudgetStatus(entries: LedgerEntry[], config: BudgetConfig, now?: Date): LedgerBudgetStatus;
 export declare function getTopConsumers(entries: LedgerEntry[], limit?: number): TopConsumer[];
 export declare function computeOptimizationSavings(entries: LedgerEntry[]): OptimizationSavings;
 //# sourceMappingURL=analytics.d.ts.map