projscan 4.13.0 → 4.15.0

package/dist/core/prove.js

@@ -1,11 +1,20 @@
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { readFeedbackFile } from './feedback.js';
-import { appendProofLedgerRecord, changedFileFingerprint, latestProofRecordFor, readProofLedger, } from './proofLedger.js';
+import { appendProofLedgerRecord, changedFileFingerprint, normalizeProofCommand, prepareProofArtifactReadPath, prepareProofArtifactWritePath, readLatestProofLedgerRecords, redactProofOutput, } from './proofLedger.js';
+import { buildProofRequirements, isConfigPath, isDocumentationPath, isGeneratedPath, isProductionPath, isSecuritySensitivePath, isTestPath, proofRelevantChangedFiles, proofSufficiencyFor, } from './proofSufficiency.js';
+import { buildProofReplay } from './proofReplay.js';
 import { quoteShellArg } from './startShellArgs.js';
 import { computeSimulation } from './simulate.js';
 import { getChangedFiles } from '../utils/changedFiles.js';
 const DEFAULT_CONTRACT_PATH = '.projscan/proof-contract.json';
+const DEFAULT_RUN_TIMEOUT_MS = 10 * 60 * 1000;
+const PROOF_RUN_TIMEOUT_EXIT_CODE = 124;
+const COMMAND_NOT_FOUND_EXIT_CODE = 127;
+const MAX_PROOF_RUN_OUTPUT_CHARS = 256 * 1024;
+const MAX_PROOF_RUN_LOG_CHARS = 512 * 1024;
 const GENERATED_FORBIDDEN_PATTERNS = [
     '.agentflight/**',
     '.agentloop/**',
@@ -23,6 +32,7 @@ const HIGH_RISK_FORBIDDEN_FILES = [
     'package-lock.json',
     'package.json',
 ];
+const PATH_MATCH_REGEX_CACHE = new Map();
 const CHANGED_FILE_RULES = [
     {
         kind: 'generated',
@@ -76,25 +86,49 @@ const CHANGED_FILE_RULES = [
     },
 ];
 const NEGATIVE_PROOF_OUTCOMES = new Set(['rejected', 'reverted', 'suppressed', 'noisy']);
-const CONFIG_BASENAMES = new Set([
-    'package.json',
-    'package-lock.json',
-    'pnpm-lock.yaml',
-    'yarn.lock',
-    'tsconfig.json',
-]);
-const CONFIG_SUFFIXES = ['.config.js', '.config.cjs', '.config.mjs', '.config.ts'];
 export async function computeProve(rootPath, options = {}) {
-    const modeCount = [Boolean(options.intent?.trim()), Boolean(options.changed), Boolean(options.recordCommand?.trim())].filter(Boolean).length;
+    const modeCount = [
+        Boolean(options.intent?.trim()),
+        Boolean(options.changed),
+        Boolean(options.recordCommand?.trim()),
+        options.runCommand !== undefined,
+    ].filter(Boolean).length;
     if (modeCount > 1) {
-        throw new Error('prove accepts only one of --intent, --changed, or --record-command');
+        throw new Error('prove accepts only one of --intent, --changed, --record-command, or --run');
     }
+    if (options.runCommand !== undefined)
+        return computeRunProof(rootPath, options);
     if (options.recordCommand?.trim())
         return computeRecordProof(rootPath, options);
     if (options.changed)
         return computeChangedProof(rootPath, options);
     return computeIntentProof(rootPath, options);
 }
+async function computeRunProof(rootPath, options) {
+    const run = await executeProofCommand(rootPath, options.runCommand ?? [], options.runTimeoutMs);
+    const changedFiles = await getChangedFiles(rootPath, options.baseRef);
+    const record = await appendProofLedgerRecord(rootPath, options.ledgerPath, {
+        command: run.command,
+        exitCode: run.exitCode,
+        durationMs: run.durationMs,
+        changedFiles: proofRelevantChangedFiles(changedFiles.files),
+        outputSummary: run.outputSummary,
+        logPath: run.logPath,
+        source: 'prove-run',
+    });
+    const verdict = record.status === 'passed' ? 'ready' : 'blocked';
+    const verifiedWorkflow = verifiedWorkflowForRecord(verdict, record.status);
+    return {
+        schemaVersion: 1,
+        mode: 'run',
+        verdict,
+        summary: `${verdict}: executed ${record.status} proof for ${record.command}`,
+        commands: [record.command],
+        warnings: changedFiles.available ? [] : [changedFiles.reason ?? 'Changed-file evidence is unavailable.'],
+        verifiedWorkflow,
+        ledgerRecord: record,
+    };
+}
 async function computeRecordProof(rootPath, options) {
     const proof = recordProofInput(options);
     const changedFiles = await getChangedFiles(rootPath, options.baseRef);
@@ -105,9 +139,10 @@ async function computeRecordProof(rootPath, options) {
         changedFiles: proofRelevantChangedFiles(changedFiles.files),
         outputSummary: proof.summary,
         logPath: proof.logPath,
-        source: 'prove-record',
+        source: options.recordSource ?? 'prove-record',
     });
     const verdict = record.status === 'passed' ? 'ready' : 'blocked';
+    const verifiedWorkflow = verifiedWorkflowForRecord(verdict, record.status);
     return {
         schemaVersion: 1,
         mode: 'record',
@@ -115,6 +150,7 @@ async function computeRecordProof(rootPath, options) {
         summary: `${verdict}: recorded ${record.status} proof for ${record.command}`,
         commands: [record.command],
         warnings: changedFiles.available ? [] : [changedFiles.reason ?? 'Changed-file evidence is unavailable.'],
+        verifiedWorkflow,
         ledgerRecord: record,
     };
 }
@@ -136,6 +172,167 @@ function recordProofInput(options) {
         logPath: options.logPath,
     };
 }
+async function executeProofCommand(rootPath, command, timeoutMs) {
+    const commandVector = normalizeRunCommand(command);
+    const displayCommand = redactProofOutput(commandVector.map(quoteShellArg).join(' '));
+    const startedAtMs = Date.now();
+    const effectiveTimeoutMs = resolveRunTimeoutMs(timeoutMs);
+    const result = await spawnProofCommand(rootPath, commandVector, effectiveTimeoutMs);
+    const durationMs = Date.now() - startedAtMs;
+    const outputSummary = proofRunOutputSummary(result, effectiveTimeoutMs);
+    const logPath = await writeProofRunLog(rootPath, {
+        command: displayCommand,
+        exitCode: result.exitCode,
+        durationMs,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        errorMessage: result.errorMessage,
+        timedOut: result.timedOut,
+        truncated: result.truncated,
+    });
+    return {
+        command: displayCommand,
+        exitCode: result.exitCode,
+        durationMs,
+        outputSummary,
+        logPath,
+    };
+}
+function normalizeRunCommand(command) {
+    const normalized = command.map((part) => String(part));
+    if (normalized.length === 0 || normalized[0]?.trim().length === 0) {
+        throw new Error('prove --run requires a command after --, for example: projscan prove --run -- npm test');
+    }
+    return normalized;
+}
+function resolveRunTimeoutMs(value) {
+    if (value === undefined)
+        return DEFAULT_RUN_TIMEOUT_MS;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error('prove --run-timeout-ms requires a positive number');
+    }
+    return Math.round(value);
+}
+function spawnProofCommand(rootPath, command, timeoutMs) {
+    return new Promise((resolve) => {
+        const [executable, ...args] = command;
+        let stdout = '';
+        let stderr = '';
+        let truncated = false;
+        let timedOut = false;
+        let finished = false;
+        let killTimer;
+        const timeout = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+            killTimer = setTimeout(() => child.kill('SIGKILL'), 1_000);
+            killTimer.unref();
+        }, timeoutMs);
+        timeout.unref();
+        const child = spawn(executable, args, {
+            cwd: rootPath,
+            env: process.env,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const finish = (exitCode, errorMessage) => {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timeout);
+            if (killTimer)
+                clearTimeout(killTimer);
+            resolve({
+                exitCode: timedOut ? PROOF_RUN_TIMEOUT_EXIT_CODE : exitCode,
+                stdout,
+                stderr,
+                ...(errorMessage ? { errorMessage } : {}),
+                timedOut,
+                truncated,
+            });
+        };
+        child.stdout?.on('data', (chunk) => {
+            const next = appendBoundedOutput(stdout, chunk);
+            stdout = next.value;
+            truncated ||= next.truncated;
+        });
+        child.stderr?.on('data', (chunk) => {
+            const next = appendBoundedOutput(stderr, chunk);
+            stderr = next.value;
+            truncated ||= next.truncated;
+        });
+        child.on('error', (error) => {
+            finish(COMMAND_NOT_FOUND_EXIT_CODE, error instanceof Error ? error.message : String(error));
+        });
+        child.on('close', (code, signal) => {
+            if (code === null) {
+                finish(signal ? 1 : 0);
+                return;
+            }
+            finish(code);
+        });
+    });
+}
+function appendBoundedOutput(current, chunk) {
+    const text = chunk.toString('utf-8');
+    const remaining = MAX_PROOF_RUN_OUTPUT_CHARS - current.length;
+    if (remaining <= 0)
+        return { value: current, truncated: text.length > 0 };
+    if (text.length > remaining) {
+        return { value: current + text.slice(0, remaining), truncated: true };
+    }
+    return { value: current + text, truncated: false };
+}
+function proofRunOutputSummary(result, timeoutMs) {
+    const parts = [
+        result.timedOut ? `timed out after ${timeoutMs}ms` : undefined,
+        result.errorMessage ? `start error: ${result.errorMessage}` : undefined,
+        result.stdout.trim() ? `stdout: ${result.stdout.trim()}` : undefined,
+        result.stderr.trim() ? `stderr: ${result.stderr.trim()}` : undefined,
+        result.truncated ? 'output truncated' : undefined,
+    ].filter((part) => Boolean(part));
+    return parts.join(' | ');
+}
+async function writeProofRunLog(rootPath, input) {
+    const relativePath = proofRunLogPath(input.command);
+    const fullPath = path.resolve(rootPath, relativePath);
+    const root = path.resolve(rootPath);
+    const relativeToRoot = path.relative(root, fullPath);
+    if (!relativeToRoot || relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) {
+        throw new Error('Proof log path must stay inside the project root.');
+    }
+    await prepareProofArtifactWritePath(rootPath, fullPath);
+    await fs.writeFile(fullPath, redactedProofRunLog(input), 'utf-8');
+    return relativePath;
+}
+function proofRunLogPath(command) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const digest = crypto.createHash('sha256').update(command).digest('hex').slice(0, 10);
+    return `.projscan/proof-logs/prove-run-${stamp}-${digest}.log`;
+}
+function redactedProofRunLog(input) {
+    const raw = [
+        `command: ${input.command}`,
+        `exitCode: ${input.exitCode}`,
+        `durationMs: ${input.durationMs}`,
+        `timedOut: ${input.timedOut ? 'yes' : 'no'}`,
+        `truncated: ${input.truncated ? 'yes' : 'no'}`,
+        input.errorMessage ? `error: ${input.errorMessage}` : undefined,
+        '--- stdout ---',
+        input.stdout || '(empty)',
+        '--- stderr ---',
+        input.stderr || '(empty)',
+    ]
+        .filter((line) => typeof line === 'string')
+        .join('\n');
+    const redacted = redactProofOutput(raw);
+    return `${truncateText(redacted, MAX_PROOF_RUN_LOG_CHARS)}\n`;
+}
+function truncateText(value, maxLength) {
+    if (value.length <= maxLength)
+        return value;
+    return `${value.slice(0, maxLength - 24)}\n[projscan log truncated]\n`;
+}
 function isNonNegativeFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0;
 }
@@ -150,7 +347,12 @@ async function computeIntentProof(rootPath, options) {
         }),
         readTrustMemory(options.feedbackPath),
     ]);
-    const contract = buildContract({ intent, simulation, trustMemory });
+    const contract = buildContract({
+        intent,
+        simulation,
+        trustMemory,
+        proofRecipes: options.proofRecipes,
+    });
     let savedContractPath;
     if (options.saveContractPath) {
         savedContractPath = await writeContract(rootPath, options.saveContractPath, contract);
@@ -163,16 +365,22 @@ async function computeIntentProof(rootPath, options) {
         contract,
         commands: contract.proofCommands,
         warnings: simulation.warnings,
+        verifiedWorkflow: contract.verifiedWorkflow,
         ...(savedContractPath ? { savedContractPath } : {}),
     };
 }
 async function computeChangedProof(rootPath, options) {
-    const [contract, changedFiles, ledger] = await Promise.all([
+    const [contract, changedFiles] = await Promise.all([
         resolveContract(rootPath, options),
-        getChangedFiles(rootPath, options.baseRef),
-        readProofLedger(rootPath, options.ledgerPath),
+        options.changedFiles ? Promise.resolve(options.changedFiles) : getChangedFiles(rootPath, options.baseRef),
     ]);
     const quickPreflight = quickProofPreflight(changedFiles);
+    const relevantChangedFiles = proofRelevantChangedFiles(changedFiles.files);
+    const proofCommands = proofCommandsForReceipt(contract.contract);
+    const [currentChangedFileFingerprint, ledger] = await Promise.all([
+        changedFileFingerprint(rootPath, relevantChangedFiles),
+        readLatestProofLedgerRecords(rootPath, options.ledgerPath, proofCommands),
+    ]);
     const receipt = buildReceipt({
         contract: contract.contract,
         contractPath: contract.path,
@@ -183,6 +391,8 @@ async function computeChangedProof(rootPath, options) {
         newRisks: quickPreflight.risks,
         preflightVerdict: quickPreflight.verdict,
         ledger,
+        proofCommands,
+        currentChangedFileFingerprint,
     });
     return {
         schemaVersion: 1,
@@ -193,6 +403,7 @@ async function computeChangedProof(rootPath, options) {
         receipt,
         commands: receipt.proofStatus.commandsRequired,
         warnings: receipt.evidenceGaps,
+        verifiedWorkflow: receipt.verifiedWorkflow,
     };
 }
 function quickProofPreflight(changedFiles) {
@@ -217,15 +428,34 @@ function buildContract(input) {
     const simulationFiles = input.simulation.filesLikelyTouched.map((file) => file.path);
     const allowedFiles = unique(simulationFiles);
     const likelyTests = unique(input.simulation.testsLikelyAffected);
-    const forbiddenFiles = forbiddenFilesFor(input.intent, [...allowedFiles, ...likelyTests]);
-    const proofCommands = contractProofCommands(input.simulation.proofCommands);
+    const matchedRecipes = matchTeamProofRecipes(input.proofRecipes ?? [], [
+        ...allowedFiles,
+        ...likelyTests,
+    ]);
+    const forbiddenFiles = unique([
+        ...forbiddenFilesFor(input.intent, [...allowedFiles, ...likelyTests]),
+        ...matchedRecipes.flatMap((recipe) => recipe.forbiddenFiles ?? []),
+    ]);
+    const proofCommands = unique([
+        ...contractProofCommands(input.simulation.proofCommands),
+        ...matchedRecipes.flatMap((recipe) => recipe.requiredCommands),
+    ]);
+    const proofRequirements = [
+        ...buildProofRequirements({
+            allowedFiles,
+            likelyTests,
+            riskyContracts: riskyContractsFor(input.simulation.contractsLikelyAffected, allowedFiles),
+            proofCommands,
+        }),
+        ...recipeProofRequirements(matchedRecipes),
+    ];
     const evidenceGaps = unique([
         ...(input.simulation.warnings.length > 0 ? input.simulation.warnings : []),
         ...(likelyTests.length === 0 ? ['No likely regression test was inferred from the plan.'] : []),
         ...(input.trustMemory?.gaps ?? []),
     ]);
     const confidence = confidenceForTrustMemory(input.simulation.confidence, input.trustMemory);
-    return {
+    const contract = {
         schemaVersion: 1,
         id: `proof-contract-${slug(input.intent)}`,
         intent: input.intent,
@@ -236,6 +466,8 @@ function buildContract(input) {
         likelyTests,
         missingRegressionTests: likelyTests.length > 0 ? [] : ['Add one regression test around the behavior named by the intent.'],
         proofCommands,
+        proofRequirements,
+        ...(matchedRecipes.length > 0 ? { teamProofRecipes: matchedRecipes } : {}),
         safeChangeShape: safeChangeShape(input.simulation.recommendedAlternative.summary),
         rollbackPlan: rollbackPlan([...allowedFiles, ...likelyTests]),
         confidence,
@@ -255,6 +487,10 @@ function buildContract(input) {
         receiptCommand: `projscan prove --changed --contract ${quoteShellArg(DEFAULT_CONTRACT_PATH)} --format markdown`,
         riskDelta: input.simulation.riskDelta,
     };
+    return {
+        ...contract,
+        verifiedWorkflow: verifiedWorkflowForContract(contract),
+    };
 }
 function contractProofCommands(simulationCommands) {
     return unique([
@@ -264,46 +500,228 @@ function contractProofCommands(simulationCommands) {
         'projscan preflight --mode before_commit --format json',
     ].filter((command) => typeof command === 'string'));
 }
+function matchTeamProofRecipes(recipes, files) {
+    return recipes
+        .map((recipe) => {
+        const matchedFiles = unique(files.filter((file) => recipe.matches.some((pattern) => pathMatches(file, pattern))));
+        if (matchedFiles.length === 0)
+            return null;
+        return {
+            ...recipe,
+            matchedFiles,
+        };
+    })
+        .filter((recipe) => Boolean(recipe));
+}
+function recipeProofRequirements(recipes) {
+    return recipes.map((recipe) => ({
+        id: `recipe:${recipe.id}`,
+        surface: 'custom',
+        files: recipe.matchedFiles,
+        requiredCommands: recipe.requiredCommands,
+        requiredReview: recipe.requiredReviewers?.length
+            ? `require review from ${recipe.requiredReviewers.join(', ')}`
+            : `review Team Proof Recipe ${recipe.id}`,
+        reason: recipe.reason ?? `Team Proof Recipe ${recipe.id} matched ${recipe.matchedFiles.join(', ')}.`,
+        source: 'recipe',
+        recipeId: recipe.id,
+        ...(recipe.requiredReviewers ? { requiredReviewers: recipe.requiredReviewers } : {}),
+    }));
+}
+function teamProofRecipesForReceipt(recipes, changedFiles, proofStatus) {
+    return recipes
+        .map((recipe) => {
+        const matchedFiles = unique(changedFiles.filter((file) => recipe.matches.some((pattern) => pathMatches(file, pattern))));
+        const forbiddenTouched = unique(changedFiles.filter((file) => (recipe.forbiddenFiles ?? []).some((pattern) => pathMatches(file, pattern))));
+        if (matchedFiles.length === 0 && forbiddenTouched.length === 0)
+            return null;
+        const missingCommands = recipe.requiredCommands.filter((command) => proofStatus.missingCommands.includes(command));
+        const failedCommands = recipe.requiredCommands.filter((command) => proofStatus.failedCommands.includes(command));
+        const staleCommands = recipe.requiredCommands.filter((command) => proofStatus.staleCommands.includes(command));
+        return {
+            ...recipe,
+            matchedFiles,
+            ...(forbiddenTouched.length > 0 ? { forbiddenTouched } : {}),
+            ...(missingCommands.length > 0 ? { missingCommands } : {}),
+            ...(failedCommands.length > 0 ? { failedCommands } : {}),
+            ...(staleCommands.length > 0 ? { staleCommands } : {}),
+        };
+    })
+        .filter((recipe) => Boolean(recipe));
+}
+function recipeGapsFor(recipes) {
+    const gaps = [];
+    for (const recipe of recipes) {
+        for (const command of recipe.missingCommands ?? []) {
+            gaps.push(`${recipe.id} requires proof command: ${command}`);
+        }
+        for (const command of recipe.failedCommands ?? []) {
+            gaps.push(`${recipe.id} has failed proof command: ${command}`);
+        }
+        for (const command of recipe.staleCommands ?? []) {
+            gaps.push(`${recipe.id} has stale proof command: ${command}`);
+        }
+    }
+    return gaps;
+}
 function buildReceipt(input) {
     const scope = scopeFor(input.contract, input.contractPath, input.changedFiles);
     const evidenceGaps = evidenceGapsFor(input);
-    const proofCommands = input.contract?.proofCommands ?? [
-        'projscan assess --mode fix-first --format json',
-        'projscan preflight --mode before_commit --format json',
-    ];
-    const proofStatus = proofStatusFor(proofCommands, input.ledger, input.changedFiles);
+    const proofStatus = proofStatusFor(input.proofCommands, input.ledger, input.changedFiles, input.currentChangedFileFingerprint);
+    const teamProofRecipes = teamProofRecipesForReceipt(input.contract?.teamProofRecipes ?? [], input.changedFiles, proofStatus);
+    const requiredReviewers = unique(teamProofRecipes.flatMap((recipe) => recipe.requiredReviewers ?? []));
+    const recipeForbiddenTouched = unique(teamProofRecipes.flatMap((recipe) => recipe.forbiddenTouched ?? []));
+    const recipeGaps = recipeGapsFor(teamProofRecipes);
+    const proofSufficiency = proofSufficiencyFor({
+        contract: input.contract,
+        scope,
+        proofStatus,
+    });
     const commitReadiness = readinessFor({
         scopeStatus: scope.status,
         forbiddenTouched: scope.forbiddenTouched,
         preflightVerdict: input.preflightVerdict,
         evidenceGaps,
         proofStatus: proofStatus.status,
+        proofSufficiencyStatus: proofSufficiency.status,
     });
     const riskDeltaDirection = riskDeltaDirectionFor(input.riskDelta);
     const reviewerDecision = reviewerDecisionFor({
         commitReadiness,
         proofStatus: proofStatus.status,
+        proofSufficiencyStatus: proofSufficiency.status,
         scope,
         preflightVerdict: input.preflightVerdict,
     });
-    return {
+    const proofReplay = buildProofReplay({
+        scope,
+        proofStatus,
+        proofSufficiency,
+        riskDeltaDirection,
+        reviewerDecision,
+        replayCommand: replayCommandForReceipt(scope.contractPath),
+    });
+    const receipt = {
         summary: summaryForReceipt(commitReadiness, scope),
         commitReadiness,
         scope,
         proofStatus,
+        proofSufficiency,
+        proofReplay,
+        ...(teamProofRecipes.length > 0 ? { teamProofRecipes } : {}),
+        ...(requiredReviewers.length > 0 ? { requiredReviewers } : {}),
+        ...(recipeForbiddenTouched.length > 0 ? { recipeForbiddenTouched } : {}),
+        ...(recipeForbiddenTouched.length > 0 ? { recipeDrift: recipeForbiddenTouched } : {}),
+        ...(recipeGaps.length > 0 ? { recipeGaps } : {}),
         riskDelta: input.riskDelta,
         riskDeltaDirection,
         reviewerDecision,
         newRisks: input.newRisks,
         evidenceGaps,
-        reviewerGuidance: reviewerGuidanceFor(commitReadiness, scope, reviewerDecision, proofStatus.status),
+        reviewerGuidance: reviewerGuidanceFor(commitReadiness, scope, reviewerDecision, proofStatus.status, proofSufficiency.status),
+    };
+    return {
+        ...receipt,
+        verifiedWorkflow: verifiedWorkflowForReceipt(receipt),
     };
 }
-function proofStatusFor(proofCommands, ledger, changedFiles) {
+function verifiedWorkflowForContract(contract) {
+    return {
+        phase: 'contract',
+        status: intentVerdict(contract),
+        nextAction: 'save the Proof Contract, make the bounded edit, then record proof commands',
+        nextCommand: contract.receiptCommand,
+        staleProof: false,
+        missingProof: contract.proofCommands.length > 0,
+        failedProof: false,
+    };
+}
+function verifiedWorkflowForRecord(verdict, recordStatus) {
+    const failedProof = recordStatus === 'failed';
+    return {
+        phase: 'record',
+        status: verdict,
+        nextAction: failedProof
+            ? 'fix the failed proof command, record it again, then replay changed proof'
+            : 'run projscan prove --changed to replay the ledger against the current diff',
+        nextCommand: 'projscan prove --changed --format markdown',
+        staleProof: false,
+        missingProof: false,
+        failedProof,
+    };
+}
+function verifiedWorkflowForReceipt(receipt) {
+    const proofStatus = receipt.proofStatus.status;
+    const proofSufficiencyStatus = receipt.proofSufficiency?.status ?? 'missing';
+    const staleProof = proofStatus === 'stale' || receipt.proofStatus.staleCommands.length > 0;
+    const missingProof = isMissingProofStatus(proofStatus) ||
+        receipt.proofStatus.missingCommands.length > 0;
+    const failedProof = proofStatus === 'failed' || receipt.proofStatus.failedCommands.length > 0;
+    return {
+        phase: 'receipt',
+        status: receipt.commitReadiness,
+        nextAction: nextActionForReceipt({
+            receipt,
+            staleProof,
+            missingProof,
+            failedProof,
+        }),
+        nextCommand: nextCommandForReceipt({
+            receipt,
+            staleProof,
+            missingProof,
+            failedProof,
+        }),
+        reviewerDecision: receipt.reviewerDecision,
+        scopeStatus: receipt.scope.status,
+        proofStatus,
+        proofSufficiencyStatus,
+        riskDeltaDirection: receipt.riskDeltaDirection,
+        staleProof,
+        missingProof,
+        failedProof,
+    };
+}
+function nextActionForReceipt(input) {
+    if (input.failedProof)
+        return 'fix failed proof commands before review';
+    if (input.staleProof)
+        return 'rerun stale proof commands before review';
+    if (input.receipt.proofStatus.status === 'not-run') {
+        return 'add required proof commands to the Proof Contract before review';
+    }
+    if (input.missingProof)
+        return 'record missing proof commands before review';
+    if (input.receipt.scope.status === 'drifted') {
+        return 'resolve scope drift or update the Proof Contract before review';
+    }
+    if (input.receipt.reviewerDecision === 'safe-to-review') {
+        return 'share the Proof Receipt with the reviewer';
+    }
+    return 'review focused scope and proof gaps before approval';
+}
+function nextCommandForReceipt(input) {
+    if (input.failedProof) {
+        return `projscan prove --record-command ${quoteShellArg(input.receipt.proofStatus.failedCommands[0] ?? '<command>')} --exit-code 0 --duration-ms <ms>`;
+    }
+    if (input.staleProof) {
+        return `projscan prove --record-command ${quoteShellArg(input.receipt.proofStatus.staleCommands[0] ?? '<command>')} --exit-code 0 --duration-ms <ms>`;
+    }
+    if (input.receipt.proofStatus.status === 'not-run') {
+        return 'projscan prove --intent "<change intent>" --save-contract .projscan/proof-contract.json';
+    }
+    if (input.missingProof) {
+        return 'projscan prove --record-command "<command>" --exit-code 0 --duration-ms <ms>';
+    }
+    if (input.receipt.scope.status === 'drifted')
+        return 'projscan prove --changed --format markdown';
+    return 'projscan evidence-pack --pr-comment';
+}
+function proofStatusFor(proofCommands, ledger, changedFiles, currentFingerprint) {
     const relevantChangedFiles = proofRelevantChangedFiles(changedFiles);
-    const currentFingerprint = changedFileFingerprint(relevantChangedFiles);
+    const latestLedgerByCommand = latestProofRecordsByCommand(ledger);
     const commandEvidence = proofCommands.map((command) => {
-        const record = latestProofRecordFor(ledger, command);
+        const record = latestLedgerByCommand.get(normalizeProofCommand(command));
         if (!record) {
             return {
                 command,
@@ -320,18 +738,24 @@ function proofStatusFor(proofCommands, ledger, changedFiles) {
                 exitCode: record.exitCode,
                 durationMs: record.durationMs,
                 completedAt: record.completedAt,
+                source: record.source,
+                recordedChangedFiles: record.changedFiles,
+                recordedChangedFileFingerprint: record.changedFileFingerprint,
                 outputSummary: record.outputSummary,
                 ...(record.logPath ? { logPath: record.logPath } : {}),
-                staleReason: 'Recorded changed files differ from current changed files.',
+                staleReason: staleProofReason(record.changedFiles, relevantChangedFiles),
             };
         }
         return {
             command,
             status: record.exitCode === 0 ? 'passed' : 'failed',
             fresh: true,
+            source: record.source,
             exitCode: record.exitCode,
             durationMs: record.durationMs,
             completedAt: record.completedAt,
+            recordedChangedFiles: record.changedFiles,
+            recordedChangedFileFingerprint: record.changedFileFingerprint,
             outputSummary: record.outputSummary,
             ...(record.logPath ? { logPath: record.logPath } : {}),
         };
@@ -364,6 +788,32 @@ function proofStatusFor(proofCommands, ledger, changedFiles) {
         commandEvidence,
     };
 }
+function latestProofRecordsByCommand(records) {
+    const latest = new Map();
+    for (const record of records) {
+        const existing = latest.get(record.normalizedCommand);
+        if (!existing || record.completedAt.localeCompare(existing.completedAt) >= 0) {
+            latest.set(record.normalizedCommand, record);
+        }
+    }
+    return latest;
+}
+function staleProofReason(recordedFiles, currentFiles) {
+    return sameStringSet(recordedFiles, currentFiles)
+        ? 'Recorded changed-file content fingerprint differs from current changed-file content.'
+        : 'Recorded changed files differ from current changed files.';
+}
+function sameStringSet(left, right) {
+    if (left.length !== right.length)
+        return false;
+    const rightSet = new Set(right);
+    return left.every((value) => rightSet.has(value));
+}
+function replayCommandForReceipt(contractPath) {
+    return contractPath
+        ? `projscan prove --changed --contract ${quoteShellArg(contractPath)} --format markdown`
+        : 'projscan prove --changed --format markdown';
+}
 function proofStatusSummary(input) {
     if (input.requiredCount === 0)
         return 'not-run';
@@ -377,8 +827,11 @@ function proofStatusSummary(input) {
         return 'partial';
     return 'passed';
 }
-function proofRelevantChangedFiles(files) {
-    return files.filter((file) => !isGeneratedPath(file));
+function proofCommandsForReceipt(contract) {
+    return (contract?.proofCommands ?? [
+        'projscan assess --mode fix-first --format json',
+        'projscan preflight --mode before_commit --format json',
+    ]);
 }
 function scopeFor(contract, contractPath, changedFiles) {
     if (!contract) {
@@ -400,13 +853,16 @@ function scopeFor(contract, contractPath, changedFiles) {
         ...(contractPath ? [contractPath] : []),
     ]);
     const forbiddenTouched = changedFiles.filter((file) => contract.forbiddenFiles.some((pattern) => pathMatches(file, pattern)));
+    const forbiddenTouchedSet = new Set(forbiddenTouched);
+    const allowedProductionSet = new Set(contract.allowedFiles);
+    const likelyTestSet = new Set(contract.likelyTests);
     const allowedTouched = changedFiles.filter((file) => allowed.has(file));
-    const outsideAllowed = changedFiles.filter((file) => !allowed.has(file));
+    const outsideAllowed = changedFiles.filter((file) => !allowed.has(file) && !isLocalProofArtifactPath(file));
     const classifications = changedFiles.map((file) => classifyChangedFile({
         file,
-        forbidden: forbiddenTouched.includes(file),
-        allowedProduction: contract.allowedFiles.includes(file),
-        expectedTest: contract.likelyTests.includes(file),
+        forbidden: forbiddenTouchedSet.has(file),
+        allowedProduction: allowedProductionSet.has(file),
+        expectedTest: likelyTestSet.has(file),
         contractPath: contractPath === file,
     }));
     const status = forbiddenTouched.length > 0 || outsideAllowed.length > 0 ? 'drifted' : 'within-contract';
@@ -434,8 +890,9 @@ async function resolveContract(rootPath, options) {
     return contract ? { contract, path: DEFAULT_CONTRACT_PATH } : {};
 }
 async function readContract(rootPath, filePath, required) {
-    const fullPath = path.resolve(rootPath, filePath);
+    const fullPath = resolveProofContractPath(rootPath, filePath);
     try {
+        await prepareProofArtifactReadPath(rootPath, fullPath);
         const parsed = JSON.parse(await fs.readFile(fullPath, 'utf-8'));
         if (parsed.schemaVersion !== 1 || !Array.isArray(parsed.allowedFiles) || !parsed.id) {
             throw new Error('invalid Proof Contract shape');
@@ -449,11 +906,28 @@ async function readContract(rootPath, filePath, required) {
     }
 }
 async function writeContract(rootPath, filePath, contract) {
-    const fullPath = path.resolve(rootPath, filePath);
-    await fs.mkdir(path.dirname(fullPath), { recursive: true });
+    const fullPath = resolveProofContractPath(rootPath, filePath);
+    await prepareProofArtifactWritePath(rootPath, fullPath);
     await fs.writeFile(fullPath, `${JSON.stringify(contract, null, 2)}\n`, 'utf-8');
     return filePath;
 }
+function resolveProofContractPath(rootPath, filePath) {
+    const root = path.resolve(rootPath);
+    const requested = filePath.trim();
+    if (!requested)
+        throw new Error('Proof Contract path is required.');
+    const fullPath = path.resolve(root, requested);
+    const relative = path.relative(root, fullPath);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('Proof Contract path must stay inside the project root.');
+    }
+    const normalizedRelative = relative.split(path.sep).join('/');
+    if (normalizedRelative !== DEFAULT_CONTRACT_PATH &&
+        !/^\.projscan\/proof-contracts\/[^/]+\.json$/.test(normalizedRelative)) {
+        throw new Error('Proof Contract path must be .projscan/proof-contract.json or .projscan/proof-contracts/<name>.json.');
+    }
+    return fullPath;
+}
 function forbiddenFilesFor(intent, allowed) {
     const intentLower = intent.toLowerCase();
     const allowedSet = new Set(allowed);
@@ -497,16 +971,26 @@ function readinessFor(input) {
     return hasReviewReceiptSignal(input) ? 'needs-review' : 'ready';
 }
 function hasBlockingReceiptSignal(input) {
-    return input.forbiddenTouched.length > 0 || input.preflightVerdict === 'block' || input.proofStatus === 'failed';
+    return (input.forbiddenTouched.length > 0 ||
+        input.preflightVerdict === 'block' ||
+        input.proofStatus === 'failed' ||
+        input.proofSufficiencyStatus === 'failed');
 }
 function hasReviewReceiptSignal(input) {
     return (input.scopeStatus !== 'within-contract' ||
         isIncompleteProofStatus(input.proofStatus) ||
+        isReviewProofSufficiencyStatus(input.proofSufficiencyStatus) ||
         input.preflightVerdict === 'caution' ||
         input.evidenceGaps.length > 0);
 }
 function isIncompleteProofStatus(status) {
-    return status === 'missing' || status === 'partial' || status === 'stale';
+    return status === 'not-run' || status === 'missing' || status === 'partial' || status === 'stale';
+}
+function isMissingProofStatus(status) {
+    return status === 'not-run' || status === 'missing' || status === 'partial';
+}
+function isReviewProofSufficiencyStatus(status) {
+    return status === 'missing' || status === 'stale' || status === 'weak';
 }
 function riskDeltaDirectionFor(riskDelta) {
     if (riskDelta.delta > 0)
@@ -516,21 +1000,28 @@ function riskDeltaDirectionFor(riskDelta) {
     return 'flat';
 }
 function reviewerDecisionFor(input) {
-    if (input.commitReadiness === 'blocked' || input.proofStatus === 'failed')
+    if (input.commitReadiness === 'blocked' ||
+        input.proofStatus === 'failed' ||
+        input.proofSufficiencyStatus === 'failed')
         return 'stop';
     if (input.commitReadiness === 'ready' &&
         input.proofStatus === 'passed' &&
+        (input.proofSufficiencyStatus === 'strong' || input.proofSufficiencyStatus === 'adequate') &&
         input.scope.status === 'within-contract' &&
         input.preflightVerdict === 'proceed') {
         return 'safe-to-review';
     }
     return 'needs-focused-review';
 }
-function reviewerGuidanceFor(verdict, scope, reviewerDecision, proofStatus) {
+function reviewerGuidanceFor(verdict, scope, reviewerDecision, proofStatus, proofSufficiencyStatus) {
     return firstMatchingGuidance([
         [reviewerDecision === 'stop', 'Stop this proof slice until failed proof commands, forbidden files, or preflight blockers are cleared.'],
+        [proofSufficiencyStatus === 'failed', 'Fix failed proof for the affected risk surface before review.'],
         [proofStatus === 'stale', 'Rerun the required proof commands; the ledger evidence is stale after newer file changes.'],
+        [proofSufficiencyStatus === 'stale', 'Rerun stale proof for the affected risk surface before review.'],
         [isIncompleteProofStatus(proofStatus), 'Record fresh proof-command evidence before approval. Missing or partial proof should not be treated as reviewer-ready.'],
+        [proofSufficiencyStatus === 'missing', 'Record proof for each changed risk surface before approval.'],
+        [proofSufficiencyStatus === 'weak', 'Review weak proof mapping before approval; a command passed but did not prove the changed surface strongly.'],
         [verdict === 'blocked', 'Do not approve until forbidden files or preflight blockers are removed from this proof slice.'],
         [scope.unexpectedProduction.length > 0, 'Review the unexpected production files first. Either update the Proof Contract intentionally or split those edits out.'],
         [hasSensitiveScopeDrift(scope), 'Require explicit reviewer sign-off for config or security-sensitive drift before approving.'],
@@ -758,53 +1249,52 @@ function confidenceReasonForSimulation(confidence, simulationConfidence, trustMe
 function normalizeIntent(value) {
     return value?.trim().replace(/\s+/g, ' ') ?? '';
 }
-function isDocumentationPath(file) {
-    return (file === 'README.md' ||
-        file.startsWith('docs/') ||
-        file.endsWith('.md') ||
-        file.endsWith('.mdx'));
-}
-function isGeneratedPath(file) {
-    return (file.startsWith('.projscan/') ||
-        file.startsWith('.projscan-memory/') ||
-        file.startsWith('.agentloop/') ||
-        file.startsWith('.agentflight/') ||
-        file.startsWith('coverage/') ||
-        file.startsWith('dist/'));
-}
-function isSecuritySensitivePath(file) {
-    return (file === '.env' ||
-        file.startsWith('.env.') ||
-        file.includes('/auth') ||
-        file.includes('/security') ||
-        file.includes('/secrets') ||
-        file.endsWith('.pem') ||
-        file.endsWith('.key'));
-}
-function isConfigPath(file) {
-    const basename = path.posix.basename(file);
-    return (CONFIG_BASENAMES.has(basename) ||
-        CONFIG_SUFFIXES.some((suffix) => basename.endsWith(suffix)) ||
-        file.startsWith('.github/'));
-}
-function isTestPath(file) {
-    return (file.startsWith('test/') ||
-        file.startsWith('tests/') ||
-        file.includes('/__tests__/') ||
-        /\.test\.[cm]?[jt]sx?$/.test(file) ||
-        /\.spec\.[cm]?[jt]sx?$/.test(file));
-}
-function isProductionPath(file) {
-    return (file.startsWith('src/') ||
-        file.startsWith('app/') ||
-        file.startsWith('lib/') ||
-        file.startsWith('packages/') ||
-        file.startsWith('apps/'));
+function isLocalProofArtifactPath(file) {
+    return file.startsWith('.projscan/');
 }
 function pathMatches(file, pattern) {
-    if (pattern.endsWith('/**'))
-        return file.startsWith(pattern.slice(0, -3));
-    return file === pattern;
+    const normalizedFile = normalizeRepoPath(file);
+    const normalizedPattern = normalizeRepoPath(pattern);
+    if (normalizedFile === normalizedPattern)
+        return true;
+    if (!normalizedPattern.includes('*'))
+        return false;
+    let regex = PATH_MATCH_REGEX_CACHE.get(normalizedPattern);
+    if (!regex) {
+        regex = globToRegExp(normalizedPattern);
+        PATH_MATCH_REGEX_CACHE.set(normalizedPattern, regex);
+    }
+    return regex.test(normalizedFile);
+}
+function globToRegExp(pattern) {
+    let source = '^';
+    for (let index = 0; index < pattern.length; index += 1) {
+        const char = pattern[index];
+        if (char === '*') {
+            if (pattern[index + 1] === '*') {
+                if (pattern[index + 2] === '/') {
+                    source += '(?:.*/)?';
+                    index += 2;
+                }
+                else {
+                    source += '.*';
+                    index += 1;
+                }
+            }
+            else {
+                source += '[^/]*';
+            }
+            continue;
+        }
+        source += escapeRegExp(char);
+    }
+    return new RegExp(`${source}$`);
+}
+function escapeRegExp(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, '\\$&');
+}
+function normalizeRepoPath(value) {
+    return value.split(path.sep).join('/').replace(/^\.\//, '');
 }
 function unique(values) {
     return [...new Set(values)];