@planu/cli 4.14.1 → 5.0.0

package/dist/engine/core-bridge.d.ts

@@ -1,8 +1,8 @@
-import type { FileHash, FileMetadata, SpecAnnotation, DriftResult, PlanuCore, DuplicateRawBlockRs, DuplicateBlockLocationRs, FastGrepMatch, FileContent, SpecBriefRs, AmbiguousCriterionRs, GapsLogChainResultRs, SearchResult, VectorNode, ProjectGraphSourceFileRs, TsRelationRs, GraphNodeInputRs, GraphEdgeInputRs, AffectedNodeRs, ShortestPathResultRs, CompactGraphSliceRs, CompactGraphEdgesRs, ProjectGraphLimitsPolicyRs, ResolvedProjectGraphLimitsRs, NativeRuntimeHandshake, NativeRuntimeCompatibility, NativeArtifactManifest, NativeLoadDiagnostic } from '../types/core-bridge.js';
+import type { FileHash, FileMetadata, SpecAnnotation, DriftResult, PlanuCore, DuplicateRawBlockRs, DuplicateBlockLocationRs, FastGrepMatch, FileContent, SpecBriefRs, AmbiguousCriterionRs, GapsLogChainResultRs, NativeVectorSearchResult, VectorNode, ProjectGraphSourceFileRs, TsRelationRs, GraphNodeInputRs, GraphEdgeInputRs, AffectedNodeRs, ShortestPathResultRs, CompactGraphSliceRs, CompactGraphEdgesRs, ProjectGraphLimitsPolicyRs, ResolvedProjectGraphLimitsRs, NativeRuntimeHandshake, NativeRuntimeCompatibility, NativeArtifactManifest, NativeLoadDiagnostic } from '../types/core-bridge.js';
 import type { MacOSKeychainNativePort } from '../types/security.js';
 import { negotiateNativeRuntime, NATIVE_CAPABILITY_ABI, NATIVE_NODE_API_ABI, NATIVE_PROTOCOL_ABI, RUNTIME_STORAGE_SCHEMA } from './native-runtime-handshake.js';
 export { negotiateNativeRuntime, NATIVE_CAPABILITY_ABI, NATIVE_NODE_API_ABI, NATIVE_PROTOCOL_ABI, RUNTIME_STORAGE_SCHEMA, };
-export type { FileHash, FileMetadata, SpecAnnotation, DriftResult, PlanuCore, DuplicateRawBlockRs, DuplicateBlockLocationRs, FastGrepMatch, FileContent, SpecBriefRs, AmbiguousCriterionRs, GapsLogChainResultRs, SearchResult, VectorNode, ProjectGraphSourceFileRs, TsRelationRs, GraphNodeInputRs, GraphEdgeInputRs, AffectedNodeRs, ShortestPathResultRs, CompactGraphSliceRs, CompactGraphEdgesRs, ProjectGraphLimitsPolicyRs, ResolvedProjectGraphLimitsRs, NativeRuntimeHandshake, NativeRuntimeCompatibility, NativeArtifactManifest, NativeLoadDiagnostic as LoadDiagnostic, };
+export type { FileHash, FileMetadata, SpecAnnotation, DriftResult, PlanuCore, DuplicateRawBlockRs, DuplicateBlockLocationRs, FastGrepMatch, FileContent, SpecBriefRs, AmbiguousCriterionRs, GapsLogChainResultRs, NativeVectorSearchResult, VectorNode, ProjectGraphSourceFileRs, TsRelationRs, GraphNodeInputRs, GraphEdgeInputRs, AffectedNodeRs, ShortestPathResultRs, CompactGraphSliceRs, CompactGraphEdgesRs, ProjectGraphLimitsPolicyRs, ResolvedProjectGraphLimitsRs, NativeRuntimeHandshake, NativeRuntimeCompatibility, NativeArtifactManifest, NativeLoadDiagnostic as LoadDiagnostic, };
 export declare function currentNativePackageName(): string | null;
 /** Main-thread port for async Keychain calls; never accepts override or unverified native code. */
 export declare function requireMacOSKeychainNativePort(): MacOSKeychainNativePort;
@@ -23,7 +23,7 @@ export declare function fastScanSpecs(rootPath: string): SpecBriefRs[] | null;
 export declare function fastVerifyGapsChain(filePath: string): GapsLogChainResultRs;
 export declare function fastAppendGapEntry(filePath: string, id: string, timestamp: string, specId: string, description: string, severity: string, affectedSpecs: string[]): string;
 export declare function fastCosineSimilarity(v1: number[], v2: number[]): number;
-export declare function fastHnswSearchFlat(query: number[], nodes: VectorNode[], topK: number): SearchResult[];
+export declare function fastHnswSearchFlat(query: number[], nodes: VectorNode[], topK: number): NativeVectorSearchResult[];
 export declare function fastHmacSign(secret: string, data: string): string;
 export declare function fastHmacVerify(secret: string, data: string, signature: string): boolean;
 export declare function fastScanProjectGraphSources(rootPath: string, policy: ProjectGraphLimitsPolicyRs, overrides?: Partial<ResolvedProjectGraphLimitsRs>): ProjectGraphSourceFileRs[];

package/dist/engine/cost-guardrails.d.ts

@@ -9,7 +9,7 @@ export declare function computeBudgetStatus(budget: SpecBudget): SpecBudgetStatu
  */
 export declare function formatBudgetMessage(status: SpecBudgetStatus): string;
 /**
- * Enforces budget limits before executing a licensed tool.
+ * Enforces engineering budget limits before executing a governed tool.
  * - If no budget is configured for the spec → no-op (pass through).
  * - If budget is exhausted → throws an Error to block tool execution.
  * - If warning threshold is reached → logs a warning but allows execution.

package/dist/engine/cost-guardrails.js

@@ -38,7 +38,7 @@ export function formatBudgetMessage(status) {
     return msg;
 }
 /**
- * Enforces budget limits before executing a licensed tool.
+ * Enforces engineering budget limits before executing a governed tool.
  * - If no budget is configured for the spec → no-op (pass through).
  * - If budget is exhausted → throws an Error to block tool execution.
  * - If warning threshold is reached → logs a warning but allows execution.

package/dist/engine/criterion-identity.d.ts

@@ -1,5 +1,6 @@
 import type { CriterionIdentity, CriterionIdentityOptions } from '../types/criterion-identity.js';
 export type { CriterionIdentity, CriterionIdentityOptions } from '../types/criterion-identity.js';
+export declare function hasExplicitCriterionId(value: string): boolean;
 export declare function normalizeCriterionText(value: string): string;
 export declare function createCriterionIdentity(value: string, options?: CriterionIdentityOptions): CriterionIdentity;
 export declare function criterionIdentitiesMatch(left: CriterionIdentity, right: CriterionIdentity): boolean;

package/dist/engine/criterion-identity.js

@@ -1,5 +1,12 @@
 import { createHash } from 'node:crypto';
 const CRITERION_ID_PREFIX = /^(AC|AB)\s*-?\s*(\d+)\b\s*[:.)-]?\s*/i;
+export function hasExplicitCriterionId(value) {
+    const stripped = value
+        .normalize('NFKC')
+        .replace(/^[-*+]\s*\[[ xX]\]\s*/, '')
+        .trim();
+    return CRITERION_ID_PREFIX.test(stripped);
+}
 export function normalizeCriterionText(value) {
     return value
         .normalize('NFKC')

package/dist/engine/dashboard/data-loader.js

@@ -324,18 +324,13 @@ export async function loadUsageStats() {
     const raw = await readJsonFile(usageFile);
     if (!raw) {
         return {
-            tier: 'unknown',
             callsToday: 0,
-            dailyLimit: null,
-            trialDaysLeft: null,
             isAvailable: false,
         };
     }
+    const today = new Date().toISOString().slice(0, 10);
     return {
-        tier: raw.tier ?? 'free',
-        callsToday: raw.callsToday ?? 0,
-        dailyLimit: raw.dailyLimit ?? null,
-        trialDaysLeft: raw.trialDaysLeft ?? null,
+        callsToday: (raw.events ?? []).filter((event) => event.timestamp?.startsWith(today)).length,
         isAvailable: true,
     };
 }

package/dist/engine/dashboard/templates-layout.js

@@ -194,9 +194,6 @@ function getPageStyles() {
   .usage-panel { background: var(--surface); border: 1px solid var(--border);
                  border-radius: var(--radius); padding: 1rem; margin-top: 1.5rem; }
   .usage-panel h3 { font-size: 0.9rem; font-weight: 600; margin-bottom: 0.75rem; color: var(--text-muted); }
-  .usage-tier { font-size: 1.1rem; font-weight: 700; color: var(--accent); }
-  .trial-warning { color: #f59e0b; font-size: 0.82rem; margin-top: 0.35rem; }
-  .trial-critical { color: #ef4444; font-weight: 600; }
   .status-indicator.updating { color: #f59e0b; }
   .shortcuts-overlay { display: none; position: fixed; inset: 0; background: rgba(0,0,0,0.7);
     z-index: 1000; align-items: center; justify-content: center; }

package/dist/engine/dashboard/templates-project.js

@@ -30,21 +30,9 @@ function renderUsagePanel(usage) {
       <div style="color:var(--text-muted);font-size:0.85rem">Sin datos de uso disponibles</div>
     </div>`;
     }
-    const tierLabel = usage.tier.charAt(0).toUpperCase() + usage.tier.slice(1);
-    const limitLabel = usage.dailyLimit !== null ? String(usage.dailyLimit) : '∞';
-    const callsLabel = `${usage.callsToday} / ${limitLabel}`;
-    let trialHtml = '';
-    if (usage.trialDaysLeft !== null) {
-        const isCritical = usage.trialDaysLeft <= 3;
-        trialHtml = `<div class="trial-warning ${isCritical ? 'trial-critical' : ''}">
-      Trial: ${usage.trialDaysLeft} día${usage.trialDaysLeft !== 1 ? 's' : ''} restante${usage.trialDaysLeft !== 1 ? 's' : ''}
-    </div>`;
-    }
     return `<div class="usage-panel">
     <h3>Uso</h3>
-    <div class="usage-tier">${escapeHtml(tierLabel)}</div>
-    <div style="font-size:0.82rem;color:var(--text-muted);margin-top:0.35rem">Llamadas hoy: ${escapeHtml(callsLabel)}</div>
-    ${trialHtml}
+    <div style="font-size:0.82rem;color:var(--text-muted);margin-top:0.35rem">Llamadas hoy: ${String(usage.callsToday)}</div>
   </div>`;
 }
 /** Render the health metrics panel */

package/dist/engine/docs-site-generator/data-collector.d.ts

@@ -1,5 +1,5 @@
 import type { DocSpecSummary, ToolEntry, ProjectMetrics } from '../../types/docs.js';
 export declare function collectSpecs(projectPath: string): Promise<DocSpecSummary[]>;
-export declare function collectTools(projectPath: string): ToolEntry[];
+export declare function collectTools(_projectPath: string): ToolEntry[];
 export declare function collectMetrics(projectPath: string): Promise<ProjectMetrics>;
 //# sourceMappingURL=data-collector.d.ts.map

package/dist/engine/docs-site-generator/data-collector.js

@@ -1,8 +1,8 @@
 // @crash-shield-ignore-file — config/cache reader for Planu-controlled JSON; writer is this codebase, shape guaranteed by build/seed.
 // SPEC-093: Data collector for docs site generator
-import { readFileSync } from 'node:fs';
 import { readdir, readFile, stat } from 'node:fs/promises';
 import { join } from 'node:path';
+import { readCanonicalToolNames } from '../../config/official-sdd-tools.js';
 import { parseFrontmatter } from '../frontmatter-parser.js';
 const SDD_PHASES = {
     Initialize: ['init_project', 'init_constitution', 'set_locale'],
@@ -225,33 +225,12 @@ export async function collectSpecs(projectPath) {
     });
     return results;
 }
-export function collectTools(projectPath) {
-    let plans;
-    try {
-        const plansPath = join(projectPath, 'src', 'config', 'license-plans.json');
-        plans = JSON.parse(readFileSync(plansPath, 'utf-8'));
-    }
-    catch {
-        return [];
-    }
-    const entries = [];
-    for (const tool of plans.freeTools ?? []) {
-        entries.push({
-            name: tool,
-            description: tool.replace(/_/g, ' '),
-            phase: findPhaseForTool(tool),
-            tier: 'free',
-        });
-    }
-    for (const tool of plans.proTools ?? []) {
-        entries.push({
-            name: tool,
-            description: tool.replace(/_/g, ' '),
-            phase: findPhaseForTool(tool),
-            tier: 'pro',
-        });
-    }
-    return entries;
+export function collectTools(_projectPath) {
+    return readCanonicalToolNames().map((tool) => ({
+        name: tool,
+        description: tool.replaceAll('_', ' '),
+        phase: findPhaseForTool(tool),
+    }));
 }
 async function countLinesInDir(dirPath) {
     let total = 0;

package/dist/engine/docs-site-generator/tools-renderer.js

@@ -11,18 +11,11 @@ function groupByPhase(tools) {
     }
     return groups;
 }
-function renderTierBadge(tier) {
-    const cls = tier === 'free' ? 'badge-free' : 'badge-pro';
-    const label = tier === 'free' ? 'Free' : 'Pro';
-    return `<span class="tier-badge ${cls}">${label}</span>`;
-}
 export function renderToolsCatalog(tools) {
-    const freeCount = tools.filter((t) => t.tier === 'free').length;
-    const proCount = tools.filter((t) => t.tier === 'pro').length;
     if (tools.length === 0) {
         return `<div class="tools-catalog">
   <div class="tools-summary">
-    <p>Total: 0 | Free: 0 | Pro: 0</p>
+    <p>Total: 0</p>
   </div>
   <p class="empty">No tools found.</p>
 </div>`;
@@ -34,7 +27,7 @@ export function renderToolsCatalog(tools) {
             .map((tool) => {
             const searchable = `${tool.name} ${tool.description}`.toLowerCase();
             return `    <div class="tool-card" data-searchable="${searchable}">
-      <h3>${tool.name} ${renderTierBadge(tool.tier)}</h3>
+      <h3>${tool.name}</h3>
       <p>${tool.description}</p>
     </div>`;
         })
@@ -47,7 +40,7 @@ ${cards}
         .join('\n');
     return `<div class="tools-catalog">
   <div class="tools-summary">
-    <p>Total: ${String(tools.length)} | Free: ${String(freeCount)} | Pro: ${String(proCount)}</p>
+    <p>Total: ${String(tools.length)}</p>
   </div>
 ${sections}
 </div>`;

package/dist/engine/evidence-gates/artifact-reader.d.ts

@@ -1,11 +1,20 @@
 import type { Spec } from '../../types/spec/core.js';
-import type { EvidenceArtifacts } from '../../types/evidence-gates.js';
+import type { EvidenceArtifacts, TraceabilityMatrixEvidence } from '../../types/evidence-gates.js';
 /** Digest of canonical artifact content; the provenance envelope is excluded. */
 export declare function evidenceArtifactDigest(artifact: unknown): string;
 export declare function evidenceArtifactCollectionDigest(artifacts: readonly {
     kind: string;
     provenance?: unknown;
 }[]): string;
+/** Verify legacy test-backed evidence without admitting prose-only traceability rows. */
+export declare function traceabilityRowHasCurrentTestEvidence(row: TraceabilityMatrixEvidence['rows'][number], args: {
+    projectPath: string;
+}): boolean;
+/** Verify strict command evidence against current repository inputs and the validation ledger. */
+export declare function traceabilityRowHasCurrentCommandEvidence(row: TraceabilityMatrixEvidence['rows'][number], args: {
+    projectId: string;
+    projectPath: string;
+}): boolean;
 export declare function readEvidenceArtifacts(args: {
     spec: Spec;
     projectId: string;

package/dist/engine/evidence-gates/artifact-reader.js

@@ -1,12 +1,30 @@
 import { technologyValue } from '../technology-registry.js';
 import { readFile } from 'node:fs/promises';
+import { lstatSync, realpathSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { join } from 'node:path';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { z } from 'zod';
 import { projectDataDir } from '../../storage/base-store.js';
+import { computeValidationEvidenceIdentity, computeValidationEvidenceKey, normalizeValidationCommand, readMatchingValidationEvidence, } from '../validation-evidence-ledger.js';
+import { VALIDATION_COMMANDS } from '../validation-impact-planner.js';
 const DIGEST = /^sha256:[a-f0-9]{64}$/u;
 const SPEC_ID = /^SPEC-[1-9]\d*$/u;
 const ISSUER_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const EVIDENCE_KEY = /^[a-f0-9]{64}$/u;
+const ValidationGateCapabilitySchema = z.enum([
+    'typecheck',
+    'lint',
+    'test-related',
+    'test-full',
+    'contract',
+    'coverage',
+    'migration',
+    'fault-injection',
+    'security',
+    'native',
+    'website',
+    'reproducibility',
+]);
 const ProvenanceSchema = z
     .object({
     receiptId: z.string().regex(DIGEST),
@@ -69,6 +87,16 @@ const TraceabilityMatrixSchema = z
         changedFiles: z.array(z.string().min(1)).max(200),
         validationEvidence: z.string().optional(),
         reviewerEvidence: z.string().optional(),
+        commandEvidence: z
+            .object({
+            capability: ValidationGateCapabilitySchema,
+            command: z.string().min(1),
+            scope: z.array(z.string().min(1)).min(1).max(200),
+            relevantPaths: z.array(z.string().min(1)).min(1).max(200).optional(),
+            evidenceKey: z.string().regex(EVIDENCE_KEY),
+        })
+            .strict()
+            .optional(),
     })
         .strict())
         .max(1000),
@@ -118,10 +146,95 @@ export function evidenceArtifactCollectionDigest(artifacts) {
         .map((artifact) => ({ kind: artifact.kind, digest: evidenceArtifactDigest(artifact) }))
         .sort((left, right) => left.kind.localeCompare(right.kind)));
 }
+function safeRepositoryPath(path) {
+    const normalized = path.trim().replaceAll('\\', '/').replace(/^\.\//u, '');
+    return (normalized.length > 0 &&
+        !normalized.startsWith('/') &&
+        !/^[A-Za-z]:/u.test(normalized) &&
+        normalized
+            .split('/')
+            .every((segment) => segment.length > 0 && segment !== '.' && segment !== '..'));
+}
+function repositoryEvidencePathsAreCurrent(row, projectPath, additionalPaths = []) {
+    let repositoryRoot;
+    try {
+        repositoryRoot = realpathSync(projectPath);
+    }
+    catch {
+        return false;
+    }
+    const paths = [
+        ...row.changedFiles,
+        ...(row.testEvidence ?? []),
+        ...(row.contractEvidence ?? []),
+        ...additionalPaths,
+    ];
+    return (paths.length > 0 &&
+        paths.every((path) => {
+            if (!safeRepositoryPath(path)) {
+                return false;
+            }
+            const candidate = resolve(repositoryRoot, path);
+            try {
+                if (lstatSync(candidate).isSymbolicLink()) {
+                    return false;
+                }
+                const realPath = realpathSync(candidate);
+                const relativePath = relative(repositoryRoot, realPath);
+                return (relativePath.length > 0 &&
+                    relativePath.split(/[\\/]/u)[0] !== '..' &&
+                    !isAbsolute(relativePath));
+            }
+            catch {
+                return false;
+            }
+        }));
+}
+function isExecutableTestPath(path) {
+    return /(?:^|\/)[^/]+\.(?:test|spec)\.[cm]?[jt]sx?$/u.test(path.replaceAll('\\', '/'));
+}
+/** Verify legacy test-backed evidence without admitting prose-only traceability rows. */
+export function traceabilityRowHasCurrentTestEvidence(row, args) {
+    return (row.commandEvidence === undefined &&
+        row.changedFiles.length > 0 &&
+        (row.testEvidence?.length ?? 0) > 0 &&
+        row.testEvidence?.every(isExecutableTestPath) === true &&
+        Boolean(row.validationEvidence?.trim()) &&
+        Boolean(row.reviewerEvidence?.trim()) &&
+        repositoryEvidencePathsAreCurrent(row, args.projectPath));
+}
+/** Verify strict command evidence against current repository inputs and the validation ledger. */
+export function traceabilityRowHasCurrentCommandEvidence(row, args) {
+    const evidence = row.commandEvidence;
+    const expectedCommand = evidence
+        ? VALIDATION_COMMANDS[evidence.capability]
+        : undefined;
+    if (!evidence ||
+        !expectedCommand ||
+        normalizeValidationCommand(evidence.command) !== normalizeValidationCommand(expectedCommand)) {
+        return false;
+    }
+    const repositoryPaths = [...(evidence.relevantPaths ?? [])];
+    if (row.changedFiles.length === 0 ||
+        !repositoryEvidencePathsAreCurrent(row, args.projectPath, repositoryPaths) ||
+        evidence.scope.some((path) => !safeRepositoryPath(path))) {
+        return false;
+    }
+    const input = {
+        projectPath: args.projectPath,
+        capability: evidence.capability,
+        command: evidence.command,
+        scope: evidence.scope,
+        ...(evidence.relevantPaths === undefined ? {} : { relevantPaths: evidence.relevantPaths }),
+    };
+    const currentKey = computeValidationEvidenceKey(computeValidationEvidenceIdentity(input));
+    return (currentKey === evidence.evidenceKey &&
+        readMatchingValidationEvidence(args.projectId, input)?.status === 'passed');
+}
 const ARTIFACT_HINTS = {
     'Discovery evidence': 'Expected discovery.json with { version: 1, rules: string[], examples: [{ rule, example }], openQuestions: [{ question, status, resolution? }], outOfScope: string[], glossary: [{ term, meaning }] }.',
     'Task plan evidence': 'Expected task-plan.json with { version: 1, tasks: [{ id, title, acceptanceCriteria: string[], status: "pending"|"doing"|"done" }] }. Acceptance criteria may be full text or stable IDs such as AC1 when they map to the canonical criteria order.',
-    'Traceability matrix evidence': 'Expected traceability-matrix.json with { version: 1, rows: [{ acceptanceCriterion, scenario?, testEvidence?, contractEvidence?, manualEvidence?, changedFiles: string[], validationEvidence?, reviewerEvidence? }] }.',
+    'Traceability matrix evidence': 'Expected traceability-matrix.json with { version: 1, rows: [{ acceptanceCriterion, scenario?, testEvidence?, contractEvidence?, manualEvidence?, changedFiles: string[], validationEvidence?, reviewerEvidence?, commandEvidence?: { capability, command, scope, relevantPaths?, evidenceKey } }] }.',
     'contract-validation-api.json': 'Expected filename contract-validation-api.json with { version: 1, kind: "api", passed: boolean, reportPath?, summary? }.',
     'contract-validation-graphql.json': 'Expected filename contract-validation-graphql.json with { version: 1, kind: "graphql", passed: boolean, reportPath?, summary? }.',
     'contract-validation-event.json': 'Expected filename contract-validation-event.json with { version: 1, kind: "event", passed: boolean, reportPath?, summary? }.',

package/dist/engine/evidence-gates/lifecycle-gate.js

@@ -1,5 +1,5 @@
 import { evidenceArtifactCollectionDigest, evidenceArtifactDigest } from './artifact-reader.js';
-import { hasAnyAffirmedMatch } from '../text-signal-boundaries.js';
+import { hasAnyAffirmedMatch, stripMetaAnalysisText, stripNonContractText, } from '../text-signal-boundaries.js';
 import { createCriterionIdentity } from '../criterion-identity.js';
 const CONTRACT_HINTS = {
     api: [
@@ -10,7 +10,8 @@ const CONTRACT_HINTS = {
     ],
     graphql: [/\b(?:graphql|gql)\s+(?:api|schema|resolver|contract)\b/i, /\bschema\.graphql\b/i],
     event: [
-        /\b(?:event|message)\s+(?:contract|schema|producer|consumer|handler|queue|topic)\b/i,
+        /\bevent\s+(?:contract|schema|producer|consumer|handler|queue|topic)\b/i,
+        /\bmessage\s+(?:schema|producer|consumer|handler|queue|topic)\b/i,
         /\b(?:message\s+broker|kafka|rabbitmq|pubsub|webhook\s+(?:delivery|contract|payload))\b/i,
     ],
     ui: [/\b(?:ui|component|screen|design)\s+contract\b/i],
@@ -76,7 +77,7 @@ function provenanceIssues(artifacts, context) {
     });
 }
 export function inferRequiredContractEvidence(spec, criteria) {
-    const text = `${spec.title} ${spec.tags.join(' ')} ${criteria.join(' ')}`;
+    const text = stripMetaAnalysisText(stripNonContractText([spec.title, ...spec.tags, ...criteria].join('\n')));
     const required = [];
     for (const [kind, patterns] of Object.entries(CONTRACT_HINTS)) {
         if (hasAnyAffirmedMatch(text, [...patterns])) {

package/dist/engine/evidence-gates/reconciliation-freshness.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns only project-relative IDs. Old evidence is rejected cumulatively: a
+ * later receipt cannot revive a digest superseded by an earlier receipt.
+ */
+export declare function checkReconciliationFreshness(args: {
+    projectId: string;
+    specId: string;
+}): Promise<{
+    artifactId: string;
+}[]>;
+//# sourceMappingURL=reconciliation-freshness.d.ts.map

package/dist/engine/evidence-gates/reconciliation-freshness.js

@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { projectDataDir } from '../../storage/base-store.js';
+import { readCommittedReconciliations } from '../lifecycle-reconciliation.js';
+const BASE_ARTIFACTS = [
+    'spec.lock.json',
+    'review_feedback.md',
+    'task-plan.json',
+    'implementation-report.json',
+    'validation-report.json',
+    'traceability-matrix.json',
+    'context-package.json',
+];
+function sha256(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+/**
+ * Returns only project-relative IDs. Old evidence is rejected cumulatively: a
+ * later receipt cannot revive a digest superseded by an earlier receipt.
+ */
+export async function checkReconciliationFreshness(args) {
+    const receipts = await readCommittedReconciliations(args.projectId, args.specId);
+    const tombstones = new Set(receipts.flatMap((receipt) => receipt.supersededArtifacts.flatMap((artifact) => artifact.sha256 ? [`${artifact.artifactId}\0${artifact.sha256}`] : [])));
+    if (tombstones.size === 0) {
+        return [];
+    }
+    const root = projectDataDir(args.projectId);
+    const handoff = join(root, 'handoffs', args.specId);
+    const candidates = [
+        ...BASE_ARTIFACTS.map((name) => ({
+            artifactId: `handoffs/${args.specId}/${name}`,
+            path: join(handoff, name),
+        })),
+        { artifactId: `handoffs/${args.specId}.md`, path: join(root, 'handoffs', `${args.specId}.md`) },
+    ];
+    try {
+        const names = await readdir(handoff);
+        for (const artifactName of names) {
+            if (/^contract-validation-[A-Za-z0-9_-]+\.json$/u.test(artifactName)) {
+                candidates.push({
+                    artifactId: `handoffs/${args.specId}/${artifactName}`,
+                    path: join(handoff, artifactName),
+                });
+            }
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+    const stale = [];
+    for (const candidate of candidates) {
+        try {
+            const stat = await lstat(candidate.path);
+            if (stat.isSymbolicLink() || !stat.isFile()) {
+                continue;
+            }
+            if (tombstones.has(`${candidate.artifactId}\0${sha256(await readFile(candidate.path))}`)) {
+                stale.push({ artifactId: candidate.artifactId });
+            }
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT')) {
+                throw error;
+            }
+        }
+    }
+    return stale;
+}
+//# sourceMappingURL=reconciliation-freshness.js.map

package/dist/engine/evidence-index/done-drift.d.ts

@@ -1,6 +1,6 @@
 import type { EvidenceGateIssue, SpecEvidenceIndex } from '../../types/index.js';
 export declare function checkDoneDriftContract(args: {
     index: SpecEvidenceIndex;
-    groundedTechnicalPaths: readonly string[];
+    approvedScopePaths: readonly string[];
 }): EvidenceGateIssue[];
 //# sourceMappingURL=done-drift.d.ts.map

package/dist/engine/evidence-index/done-drift.js

@@ -1,3 +1,8 @@
+import { normalizeChangedFilePath } from '../handoff-packager.js';
+function normalizedChangedFile(value) {
+    const normalized = normalizeChangedFilePath(value);
+    return normalized.status === 'valid' ? normalized.path : null;
+}
 export function checkDoneDriftContract(args) {
     const issues = [];
     const uncovered = args.index.criteria.filter((entry) => {
@@ -14,33 +19,50 @@ export function checkDoneDriftContract(args) {
     }
     const staleOrInvalid = args.index.criteria.flatMap((entry) => entry.evidence
         .filter((record) => record.status === 'stale' || record.status === 'invalid')
-        .map((record) => `${entry.criterion}: ${record.value} (${record.status})`));
+        .map((record) => {
+        if (record.kind !== 'changed-file') {
+            return `${entry.criterion}: ${record.value} (${record.status})`;
+        }
+        const normalized = normalizedChangedFile(record.value);
+        return normalized
+            ? `${entry.criterion}: ${normalized} (${record.status})`
+            : `${entry.criterion}: invalid changed-file (${record.status})`;
+    }));
     if (staleOrInvalid.length > 0) {
         issues.push({
             code: 'done_drift_stale_evidence',
             message: `Done drift check found stale or invalid evidence: ${staleOrInvalid.join('; ')}`,
         });
     }
-    const grounded = new Set(args.groundedTechnicalPaths);
-    if (grounded.size > 0) {
-        const unapproved = args.index.criteria.flatMap((entry) => {
-            const hasScopeAmendment = entry.evidence.some((record) => record.kind === 'reviewer' && /scope amendment|approved scope/i.test(record.value));
-            if (hasScopeAmendment) {
+    const approvedScopePaths = args.approvedScopePaths.flatMap((path) => {
+        const normalized = normalizedChangedFile(path);
+        return normalized ? [normalized] : [];
+    });
+    const approved = new Set(approvedScopePaths);
+    const unapproved = args.index.criteria.flatMap((entry) => {
+        const hasScopeAmendment = entry.evidence.some((record) => record.kind === 'reviewer' && /scope amendment|approved scope/i.test(record.value));
+        if (hasScopeAmendment) {
+            return [];
+        }
+        return entry.evidence.flatMap((record) => {
+            if (record.kind !== 'changed-file' ||
+                (record.status !== 'valid' && record.status !== 'missing')) {
                 return [];
             }
-            return entry.evidence
-                .filter((record) => record.kind === 'changed-file' && !grounded.has(record.value))
-                .map((record) => `${entry.criterion}: ${record.value}`);
+            const normalized = normalizedChangedFile(record.value);
+            return normalized && approved.has(normalized)
+                ? []
+                : [`${entry.criterion}: ${normalized ?? 'invalid changed-file path'}`];
+        });
+    });
+    if (unapproved.length > 0) {
+        const approvedHint = approvedScopePaths.length > 0
+            ? ` Approved canonical paths: ${approvedScopePaths.join(', ')}.`
+            : ' No approved canonical paths were found in the approved spec.';
+        issues.push({
+            code: 'done_drift_unapproved_scope',
+            message: `Done drift check found changed files outside approved canonical scope: ${unapproved.join('; ')}.${approvedHint} Add the file to approved canonical ownership or include reviewerEvidence with an approved scope amendment.`,
         });
-        if (unapproved.length > 0) {
-            const groundedHint = args.groundedTechnicalPaths.length > 0
-                ? ` Grounded technical paths: ${args.groundedTechnicalPaths.join(', ')}.`
-                : ' No grounded technical paths were found in the approved spec.';
-            issues.push({
-                code: 'done_drift_unapproved_scope',
-                message: `Done drift check found changed files outside grounded spec scope: ${unapproved.join('; ')}.${groundedHint} Add the file to approved technical references or include reviewerEvidence with an approved scope amendment.`,
-            });
-        }
     }
     return issues;
 }

package/dist/engine/execution/context.js

@@ -102,6 +102,7 @@ export function createChildCancellationScope(requestedMs) {
     const normalizedMs = Number.isFinite(requestedMs) ? Math.max(0, requestedMs) : 0;
     const timeoutMs = Math.max(0, Math.min(normalizedMs, parentRemaining));
     const controller = new AbortController();
+    let deadlineElapsed = false;
     const abortFromParent = () => {
         controller.abort(parent?.signal.reason ?? new ExecutionCancelledError());
     };
@@ -112,12 +113,14 @@ export function createChildCancellationScope(requestedMs) {
         parent?.signal.addEventListener('abort', abortFromParent, { once: true });
     }
     const timer = setTimeout(() => {
+        deadlineElapsed = true;
         controller.abort(new ExecutionCancelledError(`Execution budget elapsed after ${String(timeoutMs)}ms`));
     }, timeoutMs);
     timer.unref();
     return {
         signal: controller.signal,
         timeoutMs,
+        didDeadlineElapse: () => deadlineElapsed,
         dispose: () => {
             clearTimeout(timer);
             parent?.signal.removeEventListener('abort', abortFromParent);

package/dist/engine/execution/durable-job-heartbeat-runtime.d.ts

@@ -0,0 +1,4 @@
+import type { DurableJobHeartbeatController, DurableJobHeartbeatRuntimeOptions, DurableJobHeartbeatStartInput } from '../../types/durable-validation.js';
+/** Start one autonomous, fenced heartbeat and wait for its typed ready acknowledgement. */
+export declare function createDurableJobHeartbeat(input: DurableJobHeartbeatStartInput, options?: DurableJobHeartbeatRuntimeOptions): Promise<DurableJobHeartbeatController>;
+//# sourceMappingURL=durable-job-heartbeat-runtime.d.ts.map