@planu/cli 4.13.0 → 5.0.0

package/dist/engine/timing/budget.js

@@ -1,56 +1,88 @@
-// engine/timing/budget.ts — Per-step budget wrapper (SPEC-713)
-// withBudget(stepName, ms, fn) aborts fn after `ms` milliseconds and returns
-// a PartialResult with a warning string instead of throwing.
+// engine/timing/budget.ts — Cancellation-aware per-step budgets.
+import { createChildCancellationScope } from '../execution/context.js';
+function elapsedSince(start) {
+    return Math.round(performance.now() - start);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function executeWithinBudget(requestedMs, fn) {
+    const scope = createChildCancellationScope(requestedMs);
+    let task;
+    try {
+        task = fn(scope.signal);
+    }
+    catch (error) {
+        task = Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+    void task.catch(() => undefined);
+    const result = new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (!settled) {
+                settled = true;
+                scope.signal.removeEventListener('abort', onAbort);
+                resolve(value);
+            }
+        };
+        const onAbort = () => {
+            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)),
+                source: 'operation',
+            });
+        });
+        if (scope.signal.aborted) {
+            onAbort();
+        }
+    });
+    return {
+        result,
+        timeoutMs: scope.timeoutMs,
+        dispose: () => {
+            scope.dispose();
+        },
+    };
+}
 /**
- * Run `fn` within a time budget of `budgetMs` milliseconds.
- *
- * - If `fn` resolves in time → returns {exceeded: false, value, elapsedMs}
- * - If the budget fires first → returns {exceeded: true, step, budgetMs, elapsedMs, warning}
- *   and the underlying promise is left to settle on its own (fire-and-forget).
- *
- * Never throws — all errors from `fn` are caught and treated as budget exceeded.
+ * Runs a step under a child deadline. The supplied signal is aborted when the
+ * local budget or any parent request deadline expires. Abandoned work is
+ * observed but is never awaited on the response path.
  */
 export async function withBudget(step, budgetMs, fn) {
     const start = performance.now();
-    const timeoutPromise = new Promise((resolve) => {
-        setTimeout(() => {
-            const elapsed = Math.round(performance.now() - start);
-            resolve({
-                exceeded: true,
-                step,
-                budgetMs,
-                elapsedMs: elapsed,
-                warning: `[SPEC-713] Step "${step}" exceeded ${String(budgetMs)}ms budget (actual: ${String(elapsed)}ms)`,
-            });
-        }, budgetMs);
-    });
+    const execution = executeWithinBudget(budgetMs, fn);
     try {
-        const result = await Promise.race([
-            fn().then((value) => ({
-                exceeded: false,
-                value,
-                elapsedMs: Math.round(performance.now() - start),
-            })),
-            timeoutPromise,
-        ]);
-        return result;
-    }
-    catch (err) {
-        const elapsed = Math.round(performance.now() - start);
-        const message = err instanceof Error ? err.message : String(err);
+        const outcome = await execution.result;
+        const elapsedMs = elapsedSince(start);
+        if (outcome.ok) {
+            return { exceeded: false, value: outcome.value, elapsedMs };
+        }
+        const thrownBeforeDeadline = outcome.source === 'operation';
         return {
             exceeded: true,
             step,
-            budgetMs,
-            elapsedMs: elapsed,
-            warning: `[SPEC-713] Step "${step}" threw after ${String(elapsed)}ms: ${message}`,
+            budgetMs: execution.timeoutMs,
+            elapsedMs,
+            warning: thrownBeforeDeadline
+                ? `[SPEC-713] Step "${step}" threw after ${String(elapsedMs)}ms: ${errorMessage(outcome.error)}`
+                : `[SPEC-713] Step "${step}" exceeded ${String(execution.timeoutMs)}ms budget (actual: ${String(elapsedMs)}ms)`,
         };
     }
+    finally {
+        execution.dispose();
+    }
 }
-/**
- * Extract the value from a BudgetResult, or return `fallback` when exceeded.
- * Optionally collect warnings into a mutable array.
- */
 export function unwrapBudget(result, fallback, warnings) {
     if (result.exceeded) {
         warnings?.push(result.warning);
@@ -58,34 +90,36 @@ export function unwrapBudget(result, fallback, warnings) {
     }
     return result.value;
 }
-/**
- * Total budget enforcer — wraps an entire operation in a hard ceiling.
- * Returns {timedOut: true, warning} if the ceiling fires, or {timedOut: false, value} otherwise.
- */
+/** Applies the same cancellation tree to a complete operation ceiling. */
 export async function withTotalBudget(operationName, ceilingMs, fn) {
     const start = performance.now();
-    const ceilingPromise = new Promise((resolve) => {
-        setTimeout(() => {
-            const elapsed = Math.round(performance.now() - start);
-            resolve({
-                timedOut: true,
-                warning: `[SPEC-713] Operation "${operationName}" exceeded ${String(ceilingMs)}ms ceiling (actual: ${String(elapsed)}ms) — aborting cleanly`,
-            });
-        }, ceilingMs);
-    });
+    const execution = executeWithinBudget(ceilingMs, fn);
     try {
-        return await Promise.race([
-            fn().then((value) => ({ timedOut: false, value })),
-            ceilingPromise,
-        ]);
-    }
-    catch (err) {
-        const elapsed = Math.round(performance.now() - start);
-        const message = err instanceof Error ? err.message : String(err);
+        const outcome = await execution.result;
+        const elapsedMs = elapsedSince(start);
+        if (outcome.ok) {
+            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)`,
+            };
+        }
         return {
+            status: 'timed_out',
             timedOut: true,
-            warning: `[SPEC-713] Operation "${operationName}" threw after ${String(elapsed)}ms: ${message}`,
+            ceilingMs: execution.timeoutMs,
+            elapsedMs,
+            warning: `[SPEC-713] Operation "${operationName}" exceeded ${String(execution.timeoutMs)}ms ceiling (actual: ${String(elapsedMs)}ms) — aborted cleanly`,
         };
     }
+    finally {
+        execution.dispose();
+    }
 }
 //# sourceMappingURL=budget.js.map

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

package/dist/engine/token-optimizer/analytics.js

@@ -41,7 +41,7 @@ function average(nums) {
     return nums.reduce((s, n) => s + n, 0) / nums.length;
 }
 function daysInCalendarMonth(year, month) {
-    return new Date(year, month, 0).getDate(); // month is 1-based here
+    return new Date(Date.UTC(year, month, 0)).getUTCDate(); // month is 1-based here
 }
 // ---------------------------------------------------------------------------
 // aggregateEntries
@@ -262,12 +262,11 @@ export function detectAnomalies(entries, dailyBreakdown) {
 // ---------------------------------------------------------------------------
 // computeBudgetStatus
 // ---------------------------------------------------------------------------
-export function computeBudgetStatus(entries, config) {
-    const now = new Date();
-    const year = now.getFullYear();
-    const month = now.getMonth() + 1; // 1-based
+export function computeBudgetStatus(entries, config, now = new Date()) {
+    const year = now.getUTCFullYear();
+    const month = now.getUTCMonth() + 1; // 1-based
     const daysInMonth = daysInCalendarMonth(year, month);
-    const daysElapsed = now.getDate();
+    const daysElapsed = now.getUTCDate();
     // Current month filter
     const monthPrefix = `${year}-${String(month).padStart(2, '0')}`;
     const monthEntries = entries.filter((e) => e.timestamp.startsWith(monthPrefix));

package/dist/engine/tool-groups/group-manager.js

@@ -1,6 +1,6 @@
 import { readJson, writeJson } from '../../storage/base-store.js';
 import toolGroupsConfigJson from '../../config/tool-groups.json' with { type: 'json' };
-const STATE_PATH = 'data/global/tool-group-state.json';
+import { resolvedStorageArtifactPath } from '../../storage/storage-catalog.js';
 const toolGroupsConfig = toolGroupsConfigJson;
 export class GroupManager {
     groups;
@@ -137,7 +137,7 @@ export class GroupManager {
     /** Load persisted group states from disk. */
     async loadPersistedState() {
         const defaultState = { states: [], updatedAt: '' };
-        const persisted = await readJson(STATE_PATH, defaultState);
+        const persisted = await readJson(resolvedStorageArtifactPath('tool-group-state'), defaultState);
         const result = new Map();
         for (const entry of persisted.states) {
             result.set(entry.groupId, entry.enabled);
@@ -154,7 +154,7 @@ export class GroupManager {
             states,
             updatedAt: new Date().toISOString(),
         };
-        await writeJson(STATE_PATH, payload);
+        await writeJson(resolvedStorageArtifactPath('tool-group-state'), payload);
     }
     /** Apply enabled/disabled state to all tools in a group via toolMap. */
     applyGroupState(groupId, enabled) {

package/dist/engine/universal-rules/installer.js

@@ -13,7 +13,7 @@ function manifestPath(projectPath, host) {
     if (host === 'gemini') {
         return join(projectPath, '.gemini', '.planu-rules-manifest.json');
     }
-    return join(projectPath, '.planu', 'rules-manifest.codex.json');
+    return join(projectPath, 'planu', 'rules-manifest.codex.json');
 }
 /**
  * Install all default-enabled universal rules applicable to `host`.

package/dist/engine/universal-rules/rules/planu-modes.js

@@ -21,6 +21,7 @@ Never suggest bypassPermissions — it disables all safety checks.
 
 ## How to apply
 
+- Run the relevant tests before moving the spec to \`done\`
 - NEVER switch modes automatically — always tell the user and let them decide
 - Critical bash actions (git push, npm publish, rm -rf) require approval regardless of mode
 `;
@@ -42,6 +43,7 @@ Auto-generated by \`init_project\`.
 
 ## How to apply
 
+- Run the relevant tests before moving the spec to \`done\`
 - NEVER switch modes automatically — always inform the user first
 `;
 }

package/dist/engine/universal-rules/rules/planu-release-policy.js

@@ -15,6 +15,7 @@ When implementation changes are complete and validated, always address release e
 
 ## Required Release Checklist
 
+- tests, lint, and typecheck gates passed
 - local validation commands passed
 - changelog or release notes updated when applicable
 - package version and git tag stay aligned

package/dist/engine/update-notifier.js

@@ -5,6 +5,8 @@ import { get } from 'node:https';
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { PLANU_VERSION } from '../config/version.js';
+import { resolveStorageLayout } from '../storage/storage-layout.js';
+import { assertNetworkAllowed } from './network-policy.js';
 const NPM_REGISTRY_URL = 'https://registry.npmjs.org/@planu%2Fcli/latest';
 const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
 // ---------------------------------------------------------------------------
@@ -69,6 +71,7 @@ function isCacheValid(cache) {
     return age < CACHE_TTL_MS;
 }
 function fetchLatestVersion() {
+    assertNetworkAllowed(NPM_REGISTRY_URL);
     return new Promise((resolve, reject) => {
         const req = get(NPM_REGISTRY_URL, { timeout: 5000 }, (res) => {
             if (res.statusCode !== 200) {
@@ -138,8 +141,8 @@ function emitUpdateHint(latest, deprecated) {
     const urgency = deprecated ? '🚨 OUTDATED' : '🆕 Update';
     const msg = [
         `[Planu] ${urgency}: v${PLANU_VERSION} → v${latest}`,
-        `[Planu]    Run: npm install -g @planu/cli@latest`,
-        `[Planu]    Or:  npx @planu/cli@latest`,
+        `[Planu]    Run: npm install -g @planu/cli@${latest}`,
+        `[Planu]    Or:  npx @planu/cli@${latest}`,
     ].join('\n');
     process.stderr.write(msg + '\n');
     isDeprecatedVersion = deprecated;
@@ -147,12 +150,12 @@ function emitUpdateHint(latest, deprecated) {
         pendingUpdateBanner = [
             `🚨 Planu OUTDATED: v${PLANU_VERSION} is ${DEPRECATED_MINOR_GAP}+ minor versions behind v${latest}.`,
             `Some tools may not work correctly. Update NOW:`,
-            `  npm install -g @planu/cli@latest`,
+            `  npm install -g @planu/cli@${latest}`,
             `  — or run: check_update_status for instructions`,
         ].join('\n');
     }
     else {
-        pendingUpdateBanner = `⚠️  Update available: v${PLANU_VERSION} → v${latest}. Run: npm install -g @planu/cli@latest`;
+        pendingUpdateBanner = `⚠️  Update available: v${PLANU_VERSION} → v${latest}. Run: npm install -g @planu/cli@${latest}`;
     }
 }
 /**
@@ -162,7 +165,7 @@ function emitUpdateHint(latest, deprecated) {
  * @param dataDir - Project data directory (default: process.cwd()/data)
  */
 export async function checkForUpdates(dataDir) {
-    const resolvedDataDir = dataDir ?? join(process.cwd(), 'data');
+    const resolvedDataDir = dataDir ?? resolveStorageLayout().cache;
     const cachePath = getCachePath(resolvedDataDir);
     try {
         const cache = readCache(cachePath);

package/dist/engine/usage-tracker/core.d.ts

@@ -1,8 +1,8 @@
-import type { UsageEvent, PricingTier } from '../../types/index.js';
+import type { UsageEvent } from '../../types/index.js';
 /**
  * Creates a new UsageEvent object. Does NOT persist — that is storage's job.
  */
-export declare function recordUsageEvent(toolName: string, tier: PricingTier, success: boolean): UsageEvent;
+export declare function recordUsageEvent(toolName: string, success: boolean): UsageEvent;
 /**
  * Returns events within the specified time period relative to now.
  * 'all' returns the full array unchanged.

package/dist/engine/usage-tracker/core.js

@@ -6,10 +6,9 @@
 /**
  * Creates a new UsageEvent object. Does NOT persist — that is storage's job.
  */
-export function recordUsageEvent(toolName, tier, success) {
+export function recordUsageEvent(toolName, success) {
     return {
         toolName,
-        tier,
         timestamp: new Date().toISOString(),
         success,
     };

package/dist/engine/usage-tracker/index.d.ts

@@ -1,6 +1,3 @@
 export { recordUsageEvent, filterEventsByPeriod, countEventsForDate, getLastEventTimestamp, } from './core.js';
 export { calculateUsageStats, formatStatsAsMarkdown } from './stats.js';
-export { TRIAL_DAYS, calculateDaysSinceFirstRun, isTrialActive, trialDaysRemaining, getTrialLimits, } from './trial.js';
-export { COOLDOWN_MS, checkDailyLimit, checkCooldown } from './rate-limiter.js';
-export { evaluateRateLimit } from './rate-check.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/usage-tracker/index.js

@@ -1,7 +1,4 @@
 // engine/usage-tracker/index.ts — Barrel re-export for usage-tracker engine module.
 export { recordUsageEvent, filterEventsByPeriod, countEventsForDate, getLastEventTimestamp, } from './core.js';
 export { calculateUsageStats, formatStatsAsMarkdown } from './stats.js';
-export { TRIAL_DAYS, calculateDaysSinceFirstRun, isTrialActive, trialDaysRemaining, getTrialLimits, } from './trial.js';
-export { COOLDOWN_MS, checkDailyLimit, checkCooldown } from './rate-limiter.js';
-export { evaluateRateLimit } from './rate-check.js';
 //# sourceMappingURL=index.js.map

package/dist/engine/usage-tracker/stats.d.ts

@@ -1,9 +1,9 @@
-import type { UsageEvent, UsageStats, ToolHealthEntry, PricingTier } from '../../types/index.js';
+import type { UsageEvent, UsageStats, ToolHealthEntry } from '../../types/index.js';
 /**
  * Computes full UsageStats from a set of events and runtime context.
  * All parameters are passed in — no I/O performed here.
  */
-export declare function calculateUsageStats(events: readonly UsageEvent[], activeSpecs: number, activeProjects: number, currentTier: PricingTier, daysSinceFirstRun: number, isTrialActive: boolean, remainingDailyCalls: number): UsageStats;
+export declare function calculateUsageStats(events: readonly UsageEvent[], activeSpecs: number, activeProjects: number): UsageStats;
 export declare function buildToolHealthBreakdown(events: readonly UsageEvent[], allKnownTools?: readonly string[]): {
     breakdown: ToolHealthEntry[];
     deadTools: string[];

package/dist/engine/usage-tracker/stats.js

@@ -6,26 +6,19 @@
  * Computes full UsageStats from a set of events and runtime context.
  * All parameters are passed in — no I/O performed here.
  */
-export function calculateUsageStats(events, activeSpecs, activeProjects, currentTier, daysSinceFirstRun, isTrialActive, remainingDailyCalls) {
+export function calculateUsageStats(events, activeSpecs, activeProjects) {
     const callsByTool = {};
-    const callsByTier = {};
     for (const event of events) {
         callsByTool[event.toolName] = (callsByTool[event.toolName] ?? 0) + 1;
-        callsByTier[event.tier] = (callsByTier[event.tier] ?? 0) + 1;
     }
     const topTools = buildTopTools(callsByTool, 10);
     const { breakdown: toolHealthBreakdown, deadTools } = buildToolHealthBreakdown(events);
     return {
         totalCalls: events.length,
         callsByTool,
-        callsByTier,
         topTools,
         activeSpecs,
         activeProjects,
-        currentTier,
-        daysSinceFirstRun,
-        isTrialActive,
-        remainingDailyCalls,
         toolHealthBreakdown,
         deadTools,
     };
@@ -82,15 +75,9 @@ export function formatStatsAsMarkdown(stats) {
     const lines = [];
     lines.push('## Usage Statistics');
     lines.push('');
-    lines.push(`**Tier:** ${stats.currentTier}`);
-    lines.push(`**Days since first run:** ${String(stats.daysSinceFirstRun)}`);
-    lines.push(`**Trial active:** ${stats.isTrialActive ? 'Yes' : 'No'}`);
     lines.push(`**Total calls:** ${String(stats.totalCalls)}`);
     lines.push(`**Active specs:** ${String(stats.activeSpecs)}`);
     lines.push(`**Active projects:** ${String(stats.activeProjects)}`);
-    if (stats.remainingDailyCalls >= 0) {
-        lines.push(`**Remaining daily calls:** ${String(stats.remainingDailyCalls)}`);
-    }
     lines.push('');
     lines.push('### Top Tools');
     lines.push('');
@@ -125,20 +112,6 @@ export function formatStatsAsMarkdown(stats) {
             lines.push(`- ${tool}`);
         }
     }
-    lines.push('');
-    lines.push('### Calls by Tier');
-    lines.push('');
-    lines.push('| Tier | Calls |');
-    lines.push('|------|-------|');
-    const tierEntries = Object.entries(stats.callsByTier);
-    if (tierEntries.length === 0) {
-        lines.push('| *(none)* | 0 |');
-    }
-    else {
-        for (const [tier, count] of tierEntries) {
-            lines.push(`| ${tier} | ${String(count)} |`);
-        }
-    }
     return lines.join('\n');
 }
 //# sourceMappingURL=stats.js.map

package/dist/engine/validation/approved-spec-portability.d.ts

@@ -0,0 +1,12 @@
+/** Rebuild machine-local mutable ledgers from the committed approved spec. */
+export declare function reconstructApprovedSpecLedgers(input: {
+    readonly canonicalProjectId: string;
+    readonly specId: string;
+    readonly specPath: string;
+    readonly projectPath?: string;
+    readonly outputDirectory?: string;
+}): Promise<{
+    readonly taskPlanPath: string;
+    readonly traceabilityPath: string;
+}>;
+//# sourceMappingURL=approved-spec-portability.d.ts.map

package/dist/engine/validation/approved-spec-portability.js

@@ -0,0 +1,107 @@
+import { access, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { PROJECT_ID as CANONICAL_PROJECT_ID } from './validation-receipt-codec.js';
+import { parseGroundedTechnicalPaths } from '../spec-grounding/contract.js';
+function section(markdown, title) {
+    const escaped = title.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    const match = new RegExp(`^#{2,3}\\s+${escaped}\\s*$`, 'imu').exec(markdown);
+    if (!match) {
+        return '';
+    }
+    const start = match.index + match[0].length;
+    const remainder = markdown.slice(start);
+    const end = /^#{2,3}\s+/mu.exec(remainder)?.index ?? remainder.length;
+    return remainder.slice(0, end).trim();
+}
+function frontmatterValue(markdown, key) {
+    const frontmatter = /^---\s*\n([\s\S]*?)\n---/u.exec(markdown)?.[1];
+    if (!frontmatter) {
+        return undefined;
+    }
+    const escaped = key.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    return new RegExp(`^${escaped}:\\s*["']?([^"'\\n]+)["']?\\s*$`, 'imu')
+        .exec(frontmatter)?.[1]
+        ?.trim();
+}
+function numberedItems(value) {
+    return [...value.matchAll(/^\s*\d+[.)]\s+(.+?)\s*$/gmu)].map((match) => match[1] ?? '');
+}
+function referencedPaths(value) {
+    return [...new Set([...value.matchAll(/`([^`]+)`/gu)].map((match) => match[1] ?? ''))]
+        .filter(Boolean)
+        .sort();
+}
+async function existingProjectPaths(projectPath, paths) {
+    const resolved = await Promise.all(paths.map(async (path) => {
+        try {
+            await access(join(projectPath, path));
+            return path;
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                'code' in error &&
+                error.code === 'ENOENT') {
+                return undefined;
+            }
+            throw error;
+        }
+    }));
+    return resolved.filter((path) => path !== undefined);
+}
+/** Rebuild machine-local mutable ledgers from the committed approved spec. */
+export async function reconstructApprovedSpecLedgers(input) {
+    if (!CANONICAL_PROJECT_ID.test(input.canonicalProjectId)) {
+        throw new Error('[Planu] Invalid canonical projectId for approved spec reconstruction');
+    }
+    const markdown = await readFile(input.specPath, 'utf8');
+    const status = frontmatterValue(markdown, 'status');
+    if (frontmatterValue(markdown, 'id') !== input.specId ||
+        (status !== 'approved' && status !== 'implementing')) {
+        throw new Error('[Planu] approved or implementing spec identity/status mismatch');
+    }
+    const criteria = numberedItems(section(markdown, 'Acceptance Criteria'));
+    if (criteria.length === 0) {
+        throw new Error('[Planu] Approved spec has no reconstructable acceptance criteria');
+    }
+    const workPlan = section(markdown, 'File-Level Work Plan');
+    const verificationMap = section(markdown, 'Acceptance-To-Verification Map');
+    const approvedChangedFiles = parseGroundedTechnicalPaths(markdown);
+    const changedFiles = approvedChangedFiles.length > 0
+        ? approvedChangedFiles
+        : referencedPaths(workPlan).filter((path) => !path.startsWith('tests/'));
+    const taskStatus = status === 'implementing' ? 'done' : 'pending';
+    const tasks = criteria.map((criterion, index) => ({
+        id: `T${String(index + 1)}`,
+        title: criterion,
+        acceptanceCriteria: [`AC${String(index + 1)}`],
+        status: taskStatus,
+    }));
+    const verificationLines = verificationMap
+        .split('\n')
+        .filter((line) => line.trim().startsWith('-'));
+    const rows = await Promise.all(criteria.map(async (criterion, index) => {
+        const matchingLine = verificationLines.find((line) => line.includes(criterion) || line.includes(`AC${String(index + 1)}`)) ?? verificationLines[index];
+        const candidateTests = referencedPaths(matchingLine ?? '').filter((path) => path.startsWith('tests/'));
+        const testEvidence = input.projectPath
+            ? await existingProjectPaths(input.projectPath, candidateTests)
+            : candidateTests;
+        return {
+            acceptanceCriterion: `AC${String(index + 1)}`,
+            scenario: criterion,
+            testEvidence,
+            changedFiles,
+            validationEvidence: matchingLine?.trim() ?? 'Validated against the approved acceptance criterion.',
+            reviewerEvidence: 'Approved spec scope and acceptance-to-verification map.',
+        };
+    }));
+    const outputDirectory = input.outputDirectory ??
+        join(projectDataDir(input.canonicalProjectId), 'handoffs', input.specId);
+    const taskPlanPath = join(outputDirectory, 'task-plan.json');
+    const traceabilityPath = join(outputDirectory, 'traceability-matrix.json');
+    await atomicWriteFile(taskPlanPath, `${JSON.stringify({ version: 1, tasks }, null, 2)}\n`);
+    await atomicWriteFile(traceabilityPath, `${JSON.stringify({ version: 1, rows }, null, 2)}\n`);
+    return { taskPlanPath, traceabilityPath };
+}
+//# sourceMappingURL=approved-spec-portability.js.map

package/dist/engine/validation/durable-validation.d.ts

@@ -0,0 +1,36 @@
+import type { ValidationArtifactDigests, ValidationReceiptBindings } from '../../types/validation-receipt.js';
+import type { DurableValidationBindings, ValidationPhase, ValidationPhaseGraphResult, ValidationPhaseProgress } from '../../types/durable-validation.js';
+export type { DurableValidationBindings } from '../../types/durable-validation.js';
+export { gitSourceTreeDigest } from './validation-source-digest.js';
+export { createPendingValidationSubmission, createValidationSubmission, validationOperationId, validationSubmissionOperationId, } from './validation-submission.js';
+export declare function toValidationReceiptBindings(bindings: DurableValidationBindings, artifactDigests: ValidationArtifactDigests): ValidationReceiptBindings;
+/** Compute immutable validation and lifecycle-artifact bindings without trusting spec metadata. */
+export declare function computeDurableValidationBindings(input: {
+    readonly canonicalProjectId: string;
+    readonly specId: string;
+    readonly projectPath: string;
+    readonly specPath: string;
+}): Promise<{
+    readonly bindings: DurableValidationBindings;
+    readonly artifactDigests: ValidationArtifactDigests;
+}>;
+/** Persist content-addressed receipt links beside machine-local lifecycle artifacts. */
+export declare function writeValidationArtifactProvenance(input: {
+    readonly canonicalProjectId: string;
+    readonly specId: string;
+    readonly receiptId: string;
+    readonly issuerId: string;
+    readonly artifactDigests: ValidationArtifactDigests;
+}): Promise<readonly string[]>;
+/** Redact progress before it crosses the durable checkpoint boundary. */
+export declare function redactValidationProgress(progress: ValidationPhaseProgress): ValidationPhaseProgress;
+/** Execute independent validation gates with one shared deadline and cancellation tree. */
+export declare function runValidationPhaseGraph(input: {
+    readonly projectPath: string;
+    readonly deadlineAt: number;
+    readonly phases: readonly ValidationPhase[];
+    readonly maxConcurrency?: number;
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: ValidationPhaseProgress) => void;
+}): Promise<ValidationPhaseGraphResult>;
+//# sourceMappingURL=durable-validation.d.ts.map