@planu/cli 4.13.0 → 4.14.1

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/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 { createPendingValidationSubmission, createValidationSubmission, validationOperationId, validationSubmissionOperationId, } from './validation-submission.js';
+export declare function toValidationReceiptBindings(bindings: DurableValidationBindings, artifactDigests: ValidationArtifactDigests): ValidationReceiptBindings;
+export declare function gitSourceTreeDigest(projectPath: string): Promise<string>;
+/** 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

package/dist/engine/validation/durable-validation.js

@@ -0,0 +1,335 @@
+import { technologyValue } from '../technology-registry.js';
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { lstat, readFile, readlink } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
+import { runAbortableProcess } from '../abortable-process-runner.js';
+import { projectDataDir } from '../../storage/base-store.js';
+import { atomicWriteFile } from '../safety/atomic-write-file.js';
+import { evidenceArtifactCollectionDigest, evidenceArtifactDigest, } from '../evidence-gates/artifact-reader.js';
+import { isValidationSourcePath } from './validation-source-policy.js';
+import { PROJECT_ID as CANONICAL_PROJECT_ID } from './validation-receipt-codec.js';
+export { createPendingValidationSubmission, createValidationSubmission, validationOperationId, validationSubmissionOperationId, } from './validation-submission.js';
+const execFileAsync = promisify(execFile);
+const DIGEST_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+const DEFAULT_MAX_CONCURRENCY = 2;
+const MAX_CONCURRENCY = 8;
+const MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+function assertBindings(bindings) {
+    if (!CANONICAL_PROJECT_ID.test(bindings.projectId)) {
+        throw new Error('[Planu] Durable validation requires a canonical projectId');
+    }
+    if (!/^SPEC-[A-Za-z0-9][A-Za-z0-9-]*$/u.test(bindings.specId)) {
+        throw new Error('[Planu] Durable validation requires a valid specId');
+    }
+    for (const bindingDigest of [
+        bindings.sourceTreeHash,
+        bindings.specHash,
+        bindings.policyHash,
+        bindings.toolchainHash,
+    ]) {
+        if (!DIGEST_PATTERN.test(bindingDigest)) {
+            throw new Error('[Planu] Durable validation requires four sha256 bindings');
+        }
+    }
+}
+function digest(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+export function toValidationReceiptBindings(bindings, artifactDigests) {
+    return {
+        projectId: bindings.projectId,
+        specId: bindings.specId,
+        sourceDigest: bindings.sourceTreeHash,
+        specDigest: bindings.specHash,
+        policyDigest: bindings.policyHash,
+        toolchainDigest: bindings.toolchainHash,
+        artifactDigests,
+    };
+}
+async function digestFile(path, missingLabel) {
+    try {
+        return digest(await readFile(path));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return digest(`missing:${missingLabel}`);
+        }
+        throw error;
+    }
+}
+async function readEvidenceFile(path) {
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            throw new Error('expected a JSON object');
+        }
+        return value;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw new Error(`[Planu] Invalid lifecycle evidence: ${path}`, { cause: error });
+    }
+}
+async function mapWithConcurrency(values, concurrency, worker) {
+    const results = new Array(values.length);
+    let cursor = 0;
+    const runners = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+        for (;;) {
+            const index = cursor;
+            cursor += 1;
+            if (index >= values.length) {
+                return;
+            }
+            results[index] = await worker(values[index]);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}
+export async function gitSourceTreeDigest(projectPath) {
+    try {
+        const gitOptions = { cwd: projectPath, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 };
+        const [trackedResult, untrackedResult] = await Promise.all([
+            execFileAsync('git', ['ls-files', '--cached', '-z'], gitOptions),
+            execFileAsync('git', ['ls-files', '--others', '--exclude-standard', '-z'], gitOptions),
+        ]);
+        const sourceEntries = (stdout) => stdout
+            .split('\0')
+            .filter(Boolean)
+            .map((sourcePath) => ({ sourcePath, canonicalPath: sourcePath.normalize('NFC') }))
+            .filter(({ canonicalPath }) => isValidationSourcePath(canonicalPath));
+        const entriesToRead = [
+            ...sourceEntries(trackedResult.stdout),
+            ...sourceEntries(untrackedResult.stdout),
+        ].sort((left, right) => Buffer.compare(Buffer.from(left.canonicalPath), Buffer.from(right.canonicalPath)));
+        if (new Set(entriesToRead.map(({ canonicalPath }) => canonicalPath)).size !== entriesToRead.length) {
+            throw new Error('source paths collide after Unicode normalization');
+        }
+        const entries = await mapWithConcurrency(entriesToRead, MAX_CONCURRENCY, async (entry) => {
+            const { canonicalPath: path, sourcePath } = entry;
+            const absolutePath = join(projectPath, sourcePath);
+            try {
+                const stats = await lstat(absolutePath);
+                if (stats.isSymbolicLink()) {
+                    const target = (await readlink(absolutePath)).normalize('NFC');
+                    return { path, content: Buffer.from(`symlink\0${target}`, 'utf8') };
+                }
+                if (!stats.isFile()) {
+                    throw new Error(`unsupported source entry type: ${path}`);
+                }
+                return {
+                    path,
+                    content: Buffer.concat([Buffer.from('file\0'), await readFile(absolutePath)]),
+                };
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return undefined;
+                }
+                throw error;
+            }
+        });
+        const hash = createHash('sha256');
+        hash.update('planu-source-v1\0');
+        for (const entry of entries) {
+            if (!entry) {
+                continue;
+            }
+            const pathBytes = Buffer.from(entry.path, 'utf8');
+            hash.update(`${pathBytes.length}:`);
+            hash.update(pathBytes);
+            hash.update(`${entry.content.length}:`);
+            hash.update(entry.content);
+        }
+        return `sha256:${hash.digest('hex')}`;
+    }
+    catch (error) {
+        throw new Error('[Planu] Unable to bind validation to the source tree', { cause: error });
+    }
+}
+/** Compute immutable validation and lifecycle-artifact bindings without trusting spec metadata. */
+export async function computeDurableValidationBindings(input) {
+    const handoff = join(projectDataDir(input.canonicalProjectId), 'handoffs', input.specId);
+    const specHash = await digestFile(input.specPath, 'approved-spec');
+    const [discovery, taskPlan, traceability, ...contracts] = await Promise.all([
+        readEvidenceFile(join(handoff, 'discovery.json')),
+        readEvidenceFile(join(handoff, 'task-plan.json')),
+        readEvidenceFile(join(handoff, 'traceability-matrix.json')),
+        ...['api', technologyValue('technology-graphql-aed31c'), 'event', 'ui', 'mcp'].map((kind) => readEvidenceFile(join(handoff, `contract-validation-${kind}.json`))),
+    ]);
+    const policyFiles = ['planu.json', 'planu/conventions.json', 'AGENTS.md'];
+    const toolchainFiles = ['package.json', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'];
+    const [policyEntries, toolchainEntries] = await Promise.all([
+        Promise.all(policyFiles.map(async (path) => [
+            path,
+            await digestFile(join(input.projectPath, path), path),
+        ])),
+        Promise.all(toolchainFiles.map(async (path) => [
+            path,
+            await digestFile(join(input.projectPath, path), path),
+        ])),
+    ]);
+    const contractArtifacts = contracts.filter((artifact) => typeof artifact?.kind === 'string');
+    return {
+        bindings: {
+            projectId: input.canonicalProjectId,
+            specId: input.specId,
+            sourceTreeHash: await gitSourceTreeDigest(input.projectPath),
+            specHash,
+            policyHash: digest(JSON.stringify(policyEntries)),
+            toolchainHash: digest(JSON.stringify({
+                node: process.version,
+                platform: process.platform,
+                files: toolchainEntries,
+            })),
+        },
+        artifactDigests: {
+            approvedSpec: specHash,
+            discovery: discovery
+                ? evidenceArtifactDigest(discovery)
+                : evidenceArtifactDigest({ missing: 'discovery' }),
+            taskPlan: taskPlan
+                ? evidenceArtifactDigest(taskPlan)
+                : evidenceArtifactDigest({ missing: 'task-plan' }),
+            traceability: traceability
+                ? evidenceArtifactDigest(traceability)
+                : evidenceArtifactDigest({ missing: 'traceability' }),
+            contractValidation: evidenceArtifactCollectionDigest(contractArtifacts),
+        },
+    };
+}
+/** Persist content-addressed receipt links beside machine-local lifecycle artifacts. */
+export async function writeValidationArtifactProvenance(input) {
+    assertBindings({
+        projectId: input.canonicalProjectId,
+        specId: input.specId,
+        sourceTreeHash: input.artifactDigests.approvedSpec,
+        specHash: input.artifactDigests.approvedSpec,
+        policyHash: input.artifactDigests.discovery,
+        toolchainHash: input.artifactDigests.taskPlan,
+    });
+    if (!DIGEST_PATTERN.test(input.receiptId) || !input.issuerId.trim()) {
+        throw new Error('[Planu] Invalid validation artifact provenance identity');
+    }
+    const directory = join(projectDataDir(input.canonicalProjectId), 'handoffs', input.specId);
+    const entries = [
+        ['approved-spec', input.artifactDigests.approvedSpec],
+        ['discovery', input.artifactDigests.discovery],
+        ['task-plan', input.artifactDigests.taskPlan],
+        ['traceability-matrix', input.artifactDigests.traceability],
+        ['contract-validation', input.artifactDigests.contractValidation],
+    ];
+    const sidecars = await Promise.all(entries.map(async ([name, artifactDigest]) => {
+        const path = join(directory, `${name}.provenance.json`);
+        await atomicWriteFile(path, `${JSON.stringify({
+            receiptId: input.receiptId,
+            artifactDigest,
+            specId: input.specId,
+            issuerId: input.issuerId,
+        }, null, 2)}\n`);
+        return path;
+    }));
+    return sidecars;
+}
+/** Redact progress before it crosses the durable checkpoint boundary. */
+export function redactValidationProgress(progress) {
+    const redact = (value) => value
+        .replace(/\/Users\/[^/\s]+/gu, '/Users/[redacted]')
+        .replace(/\/(?:home|root)\/[^/\s]+/gu, '/home/[redacted]')
+        .replace(/(--?(?:token|password|secret|api[-_]?key)(?:=|\s+))\S+/giu, '$1[redacted]')
+        .replace(/(bearer\s+)\S+/giu, '$1[redacted]');
+    return {
+        ...progress,
+        command: redact(progress.command),
+        ...(progress.remediation === undefined ? {} : { remediation: redact(progress.remediation) }),
+    };
+}
+/** Execute independent validation gates with one shared deadline and cancellation tree. */
+export async function runValidationPhaseGraph(input) {
+    if (!Number.isSafeInteger(input.deadlineAt) || input.deadlineAt <= Date.now()) {
+        throw new Error('[Planu] Validation phase graph requires a future absolute deadline');
+    }
+    const maxConcurrency = input.maxConcurrency ?? DEFAULT_MAX_CONCURRENCY;
+    if (!Number.isSafeInteger(maxConcurrency) ||
+        maxConcurrency < 1 ||
+        maxConcurrency > MAX_CONCURRENCY) {
+        throw new Error(`[Planu] maxConcurrency must be between 1 and ${String(MAX_CONCURRENCY)}`);
+    }
+    const results = Array.from({ length: input.phases.length }, () => undefined);
+    const logs = Array.from({ length: input.phases.length }, () => '');
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < input.phases.length) {
+            const index = cursor++;
+            const phase = input.phases[index];
+            if (!phase) {
+                continue;
+            }
+            const completed = await executeValidationPhase(phase, input);
+            results[index] = completed.result;
+            logs[index] = completed.log;
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(maxConcurrency, input.phases.length) }, () => worker()));
+    const completedResults = results.filter((result) => result !== undefined);
+    const status = completedResults.some((result) => result.status === 'cancelled')
+        ? 'cancelled'
+        : completedResults.some((result) => result.status === 'failed')
+            ? 'failed'
+            : 'passed';
+    return { status, gates: completedResults, log: logs.join('\n') };
+}
+async function executeValidationPhase(phase, input) {
+    const startedAt = Date.now();
+    const safeCommand = [basename(phase.command.executable), ...(phase.command.args ?? [])].join(' ');
+    input.onProgress?.(redactValidationProgress({
+        phase: phase.id,
+        command: safeCommand,
+        durationMs: 0,
+        ...(phase.filesScanned === undefined ? {} : { filesScanned: phase.filesScanned }),
+        status: 'running',
+    }));
+    phase.onStarted?.();
+    try {
+        const remainingMs = Math.max(1, input.deadlineAt - Date.now());
+        const processResult = await runAbortableProcess(phase.command.executable, [...(phase.command.args ?? [])], {
+            cwd: input.projectPath,
+            timeoutMs: Math.min(phase.timeoutMs ?? remainingMs, remainingMs),
+            maxBufferBytes: MAX_BUFFER_BYTES,
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+        });
+        const log = `${processResult.stdout}${processResult.stderr}`;
+        const status = processResult.aborted || processResult.timedOut
+            ? 'cancelled'
+            : processResult.status === 0
+                ? 'passed'
+                : 'failed';
+        const durationMs = Date.now() - startedAt;
+        input.onProgress?.(redactValidationProgress({
+            phase: phase.id,
+            command: safeCommand,
+            durationMs,
+            ...(phase.filesScanned === undefined ? {} : { filesScanned: phase.filesScanned }),
+            status,
+            ...(phase.remediation === undefined ? {} : { remediation: phase.remediation }),
+        }));
+        return {
+            log,
+            result: {
+                id: phase.id,
+                status,
+                durationMs,
+                exitCode: processResult.status,
+                logDigest: `sha256:${createHash('sha256').update(log).digest('hex')}`,
+            },
+        };
+    }
+    finally {
+        phase.onSettled?.();
+    }
+}
+//# sourceMappingURL=durable-validation.js.map

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

@@ -0,0 +1,36 @@
+import type { ValidationFreshnessLease, ValidationReceiptBindings } from '../../types/validation-receipt.js';
+export type { ValidationFreshnessLease } from '../../types/validation-receipt.js';
+/**
+ * Invalidate the active validation lease for a spec.
+ *
+ * Filesystem watchers and Planu-owned writers share this entry point so callers
+ * that know they changed validation evidence do not depend on fs.watch timing.
+ */
+export declare function invalidateValidationFreshness(input: {
+    projectId: string;
+    specId: string;
+}): boolean;
+/** Start both watchers before snapshotting and invalidate any older receipt immediately. */
+export declare function beginValidationFreshnessBarrier(input: {
+    projectId: string;
+    specId: string;
+    projectPath: string;
+    handoffPath: string;
+    invalidateCurrentBindings?: boolean;
+}): Promise<ValidationFreshnessLease>;
+/** Bind the post-watch snapshot; an event before this call makes the lease unusable. */
+export declare function bindValidationFreshnessLease(lease: ValidationFreshnessLease, bindings: ValidationReceiptBindings): Promise<boolean>;
+/** Drain invalidation work and verify epoch, generation, health, expiry and bound inputs. */
+export declare function assertValidationFreshnessBarrier(lease: ValidationFreshnessLease, bindings?: ValidationReceiptBindings): Promise<boolean>;
+export declare function captureValidationFreshnessLease(identity: {
+    projectId: string;
+    specId: string;
+}, bindings: ValidationReceiptBindings): Promise<ValidationFreshnessLease | undefined>;
+/** Accept validation-generated filesystem activity only after an exact full recomputation. */
+export declare function rebaselineValidationFreshnessLeaseAfterRecompute(input: {
+    lease: ValidationFreshnessLease;
+    expectedBindings: ValidationReceiptBindings;
+    recompute: () => Promise<ValidationReceiptBindings>;
+}): Promise<ValidationFreshnessLease | undefined>;
+export declare function resetValidationFreshnessForTests(): void;
+//# sourceMappingURL=validation-freshness.d.ts.map