mustflow 2.22.13 → 2.22.15

package/README.md

@@ -275,7 +275,7 @@ mf run mustflow_update_apply
 | `mf verify --reason <event>` | Run configured verification intents selected by `required_after` metadata. |
 | `mf verify --reason <event> --plan-only --json` | Print the required verification plan without running commands. |
 | `mf explain authority [path]` | Explain managed Markdown authority decisions without modifying files. |
-| `mf explain skill <skill_id>` | Explain the trigger, scope, risk, checks, and output contract for one skill route. |
+| `mf explain skill <skill_id>` | Explain the trigger, scope, risk, checks, output contract, and selection evidence for one skill route. |
 | `mf explain skills` | Explain the strict skill index/body alignment summary used by `mf doctor --strict`. |
 | `mf explain surface [path]` | Explain how a path maps to public-surface and validation categories. |
 

package/dist/cli/commands/explain-verify.js

@@ -107,7 +107,7 @@ export async function getVerifyExplainOutput(schemaVersion, projectRoot, reasons
     const readModel = await readLatestLocalVerificationReadModelQueries(projectRoot);
     const requirements = plans.map((plan) => {
         const candidates = plan.candidates.map((candidate) => {
-            const command = candidate.intent ? explainCommandIntent(contract, candidate.intent).intent : null;
+            const command = candidate.intent ? explainCommandIntent(contract, candidate.intent, { projectRoot }).intent : null;
             return {
                 intent: candidate.intent.length > 0 ? candidate.intent : null,
                 status: candidate.status,
@@ -211,6 +211,13 @@ export function renderVerifyExplainDecision(decision, lang) {
             if (candidate.requiredAfter.length > 0) {
                 lines.push(`    required_after: ${candidate.requiredAfter.join(', ')}`);
             }
+            if (candidate.command && candidate.command.preconditions.length > 0) {
+                lines.push(`    preconditions: ${candidate.command.preconditions.length}`);
+                for (const precondition of candidate.command.preconditions) {
+                    const target = precondition.path ?? precondition.artifact ?? precondition.label ?? precondition.kind;
+                    lines.push(`      - ${precondition.kind} ${target}: ${precondition.status}`);
+                }
+            }
             if (candidate.effectGraph) {
                 lines.push(`    effect_graph: ${candidate.effectGraph.status}`, `    index_fresh: ${candidate.effectGraph.indexFresh ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
                 if (candidate.effectGraph.refreshHint) {

package/dist/cli/commands/explain.js

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
@@ -13,9 +15,10 @@ import { checkMustflowProject } from '../lib/validation.js';
 import { readLocalCommandEffectGraph, readLocalPathSurface, } from '../lib/local-index.js';
 import { explainVerifyArgErrorMessage, explainVerifyPlanErrorMessage, getVerifyExplainOutput, parseExplainVerifyArgs, readExplainVerifyPlanReasons, renderVerifyExplainDecision, } from './explain-verify.js';
 const EXPLAIN_SCHEMA_VERSION = '1';
+const LATEST_RUN_RECEIPT_RELATIVE_PATH = '.mustflow/state/runs/latest.json';
 export function getExplainHelp(lang = 'en') {
     return renderHelp({
-        usage: 'mf explain <topic> [target] [options] | mf explain verify --reason <event> [options] | mf explain verify --from-plan <path> [options]',
+        usage: 'mf explain <topic> [target] [options] | mf explain verify --reason <event> [options] | mf explain why <target> [options]',
         summary: t(lang, 'explain.help.summary'),
         options: [
             { label: '--json', description: t(lang, 'cli.option.json') },
@@ -34,6 +37,9 @@ export function getExplainHelp(lang = 'en') {
             'mf explain retention --json',
             'mf explain verify --reason code_change',
             'mf explain verify --from-plan verify-plan.json --json',
+            'mf explain why command test --json',
+            'mf explain why verify --reason code_change --json',
+            'mf explain why latest-failure --json',
             'mf explain skill code-review',
             'mf explain skill mustflow.core.code-review --json',
             'mf explain skills',
@@ -76,7 +82,7 @@ function getAnchorExplainOutput(projectRoot, anchorId) {
     };
 }
 async function getCommandExplainOutput(projectRoot, commandName) {
-    const decision = explainCommandIntent(readCommandContract(projectRoot), commandName);
+    const decision = explainCommandIntent(readCommandContract(projectRoot), commandName, { projectRoot });
     const effectGraph = decision.intent ? await readLocalCommandEffectGraph(projectRoot, commandName) : undefined;
     return {
         schema_version: EXPLAIN_SCHEMA_VERSION,
@@ -124,6 +130,237 @@ async function getSurfaceExplainOutput(projectRoot, pathArg) {
         decision: { ...decision, readModel },
     };
 }
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function stringField(record, key) {
+    const value = record[key];
+    return typeof value === 'string' ? value : null;
+}
+function integerField(record, key) {
+    const value = record[key];
+    return typeof value === 'number' && Number.isInteger(value) ? value : null;
+}
+function recordField(record, key) {
+    const value = record[key];
+    return isJsonRecord(value) ? value : null;
+}
+function latestFailureDecision(latestFailure, decision, reason, effectiveAction) {
+    return {
+        kind: 'latest_failure',
+        decision,
+        reason,
+        effectiveAction,
+        countsAsMustflowVerification: false,
+        sourceFiles: [
+            LATEST_RUN_RECEIPT_RELATIVE_PATH,
+            '.mustflow/config/mustflow.toml',
+            '.mustflow/docs/agent-workflow.md',
+        ],
+        latestFailure,
+    };
+}
+function getLatestFailureExplainOutput(projectRoot) {
+    const latestPath = path.join(projectRoot, ...LATEST_RUN_RECEIPT_RELATIVE_PATH.split('/'));
+    const sourcePath = LATEST_RUN_RECEIPT_RELATIVE_PATH;
+    if (!existsSync(latestPath)) {
+        return {
+            schema_version: EXPLAIN_SCHEMA_VERSION,
+            command: 'explain',
+            topic: 'why',
+            mustflow_root: projectRoot,
+            decision: latestFailureDecision({
+                path: sourcePath,
+                present: false,
+                valid: false,
+                failed: false,
+                status: null,
+                intent: null,
+                exitCode: null,
+                errorKind: null,
+                durationMs: null,
+                summary: 'No latest mf run receipt is available.',
+            }, 'latest run receipt is missing', 'mustflow has no bounded latest run metadata to explain.', 'Run a configured mf run or mf verify command before treating latest-run state as evidence.'),
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(latestPath, 'utf8'));
+    }
+    catch {
+        return {
+            schema_version: EXPLAIN_SCHEMA_VERSION,
+            command: 'explain',
+            topic: 'why',
+            mustflow_root: projectRoot,
+            decision: latestFailureDecision({
+                path: sourcePath,
+                present: true,
+                valid: false,
+                failed: false,
+                status: null,
+                intent: null,
+                exitCode: null,
+                errorKind: null,
+                durationMs: null,
+                summary: 'The latest mf run receipt is not valid JSON.',
+            }, 'latest run receipt is invalid', 'mustflow could not read bounded latest run metadata safely.', 'Ignore the latest-run state and rerun the intended configured command to create a fresh receipt.'),
+        };
+    }
+    if (!isJsonRecord(parsed)) {
+        return {
+            schema_version: EXPLAIN_SCHEMA_VERSION,
+            command: 'explain',
+            topic: 'why',
+            mustflow_root: projectRoot,
+            decision: latestFailureDecision({
+                path: sourcePath,
+                present: true,
+                valid: false,
+                failed: false,
+                status: null,
+                intent: null,
+                exitCode: null,
+                errorKind: null,
+                durationMs: null,
+                summary: 'The latest mf run receipt is not a JSON object.',
+            }, 'latest run receipt is invalid', 'mustflow could not read bounded latest run metadata safely.', 'Ignore the latest-run state and rerun the intended configured command to create a fresh receipt.'),
+        };
+    }
+    const status = stringField(parsed, 'status');
+    const intent = stringField(parsed, 'intent');
+    const exitCode = integerField(parsed, 'exit_code');
+    const performance = recordField(parsed, 'performance');
+    const resultSummary = performance ? recordField(performance, 'result_summary') : null;
+    const errorKind = resultSummary ? stringField(resultSummary, 'error_kind') : null;
+    const durationMs = integerField(parsed, 'duration_ms') ?? (performance ? integerField(performance, 'duration_ms') : null);
+    if (!status) {
+        return {
+            schema_version: EXPLAIN_SCHEMA_VERSION,
+            command: 'explain',
+            topic: 'why',
+            mustflow_root: projectRoot,
+            decision: latestFailureDecision({
+                path: sourcePath,
+                present: true,
+                valid: false,
+                failed: false,
+                status: null,
+                intent,
+                exitCode,
+                errorKind,
+                durationMs,
+                summary: 'The latest mf run receipt does not include a status field.',
+            }, 'latest run receipt is invalid', 'mustflow could not read bounded latest run metadata safely.', 'Ignore the latest-run state and rerun the intended configured command to create a fresh receipt.'),
+        };
+    }
+    const failed = status !== 'passed';
+    return {
+        schema_version: EXPLAIN_SCHEMA_VERSION,
+        command: 'explain',
+        topic: 'why',
+        mustflow_root: projectRoot,
+        decision: latestFailureDecision({
+            path: sourcePath,
+            present: true,
+            valid: true,
+            failed,
+            status,
+            intent,
+            exitCode,
+            errorKind,
+            durationMs,
+            summary: `Latest bounded run receipt status is ${status}.`,
+        }, failed ? 'latest run did not pass' : 'latest run is not a failure', failed
+            ? 'the latest bounded run receipt reports a non-passing status without exposing stdout or stderr tails.'
+            : 'the latest bounded run receipt does not report a failure status.', failed
+            ? 'Inspect the configured command result and rerun the narrowest relevant intent after fixing the cause.'
+            : 'Do not treat this as a failure explanation; choose the next verification from current changes and command contracts.'),
+    };
+}
+function withWhyTopic(output) {
+    return { ...output, topic: 'why' };
+}
+async function getWhyExplainOutput(projectRoot, targetArg, rest, lang, reporter) {
+    switch (targetArg) {
+        case 'command':
+        case 'intent': {
+            const [commandName, ...extra] = rest;
+            if (!commandName) {
+                printUsageError(reporter, t(lang, 'explain.error.missingCommand'), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            if (extra.length > 0) {
+                printUsageError(reporter, t(lang, 'cli.error.unexpectedArgument', { argument: extra[0] }), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            return withWhyTopic(await getCommandExplainOutput(projectRoot, commandName));
+        }
+        case 'verify': {
+            const parsed = parseExplainVerifyArgs([...rest]);
+            if (parsed.error) {
+                printUsageError(reporter, explainVerifyArgErrorMessage(parsed.error, lang), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            const selectedInputCount = [parsed.reason, parsed.fromPlan].filter(Boolean).length;
+            if (selectedInputCount > 1) {
+                printUsageError(reporter, t(lang, 'verify.error.conflictingInputs'), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            if (selectedInputCount === 0) {
+                printUsageError(reporter, t(lang, 'verify.error.missingReason'), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            try {
+                if (parsed.fromPlan) {
+                    const reasons = readExplainVerifyPlanReasons(projectRoot, parsed.fromPlan);
+                    return withWhyTopic(await getVerifyExplainOutput(EXPLAIN_SCHEMA_VERSION, projectRoot, reasons, null, parsed.fromPlan));
+                }
+                return withWhyTopic(await getVerifyExplainOutput(EXPLAIN_SCHEMA_VERSION, projectRoot, [parsed.reason], parsed.reason, null));
+            }
+            catch (error) {
+                printUsageError(reporter, explainVerifyPlanErrorMessage(error, lang), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+        }
+        case 'skill': {
+            const [skillName, ...extra] = rest;
+            if (!skillName) {
+                printUsageError(reporter, t(lang, 'explain.error.missingSkill'), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            if (extra.length > 0) {
+                printUsageError(reporter, t(lang, 'cli.error.unexpectedArgument', { argument: extra[0] }), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            return withWhyTopic(getSkillExplainOutput(projectRoot, skillName));
+        }
+        case 'skills':
+            if (rest.length > 0) {
+                printUsageError(reporter, t(lang, 'cli.error.unexpectedArgument', { argument: rest[0] }), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            return withWhyTopic(getSkillsExplainOutput(projectRoot));
+        case 'surface': {
+            const [pathArg, ...extra] = rest;
+            if (extra.length > 0) {
+                printUsageError(reporter, t(lang, 'cli.error.unexpectedArgument', { argument: extra[0] }), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            return withWhyTopic(await getSurfaceExplainOutput(projectRoot, pathArg));
+        }
+        case 'latest-failure':
+        case 'latest-run':
+            if (rest.length > 0) {
+                printUsageError(reporter, t(lang, 'cli.error.unexpectedArgument', { argument: rest[0] }), 'mf explain --help', getExplainHelp(lang), lang);
+                return null;
+            }
+            return getLatestFailureExplainOutput(projectRoot);
+        default:
+            printUsageError(reporter, t(lang, targetArg ? 'explain.error.unknownTopic' : 'explain.error.missingTopic', { topic: targetArg ?? '' }), 'mf explain --help', getExplainHelp(lang), lang);
+            return null;
+    }
+}
 function formatNullable(value, lang) {
     if (value === null) {
         return t(lang, 'value.none');
@@ -152,6 +389,10 @@ function renderExplainDecision(output, lang) {
     if ('verification' in output.decision) {
         lines.push(...renderVerifyExplainDecision(output.decision, lang));
     }
+    if ('latestFailure' in output.decision) {
+        const latest = output.decision.latestFailure;
+        lines.push('', 'Latest run failure', `- path: ${latest.path}`, `- present: ${latest.present ? t(lang, 'value.yes') : t(lang, 'value.no')}`, `- valid: ${latest.valid ? t(lang, 'value.yes') : t(lang, 'value.no')}`, `- failed: ${latest.failed ? t(lang, 'value.yes') : t(lang, 'value.no')}`, `- status: ${latest.status ?? t(lang, 'value.none')}`, `- intent: ${latest.intent ?? t(lang, 'value.none')}`, `- exit_code: ${latest.exitCode ?? t(lang, 'value.none')}`, `- error_kind: ${latest.errorKind ?? t(lang, 'value.none')}`, `- duration_ms: ${latest.durationMs ?? t(lang, 'value.none')}`, `- summary: ${latest.summary}`);
+    }
     if ('boundary' in output.decision) {
         lines.push('', t(lang, 'explain.label.authorityBoundary'), `- role: ${output.decision.boundary.role}`);
         if (output.decision.boundary.canDefine.length > 0) {
@@ -170,6 +411,17 @@ function renderExplainDecision(output, lang) {
     if ('intent' in output.decision && output.decision.intent) {
         const intent = output.decision.intent;
         lines.push('', t(lang, 'explain.label.commandIntent'), `- ${t(lang, 'explain.label.commandName')}: ${intent.name}`, `- status: ${intent.status ?? t(lang, 'value.none')}`, `- lifecycle: ${intent.lifecycle ?? t(lang, 'value.none')}`, `- run_policy: ${intent.runPolicy ?? t(lang, 'value.none')}`, `- stdin: ${intent.stdin ?? t(lang, 'value.none')}`, `- timeout_seconds: ${intent.timeoutSeconds ?? t(lang, 'value.none')}`, `- mode: ${intent.mode}`, `- cwd: ${intent.cwd ?? t(lang, 'value.none')}`, `- writes: ${intent.writes.join(', ') || t(lang, 'value.none')}`, `- network: ${formatNullable(intent.network, lang)}`, `- destructive: ${formatNullable(intent.destructive, lang)}`, `- success_exit_codes: ${intent.successExitCodes.join(', ') || t(lang, 'value.none')}`, `- required_after: ${intent.requiredAfter.join(', ') || t(lang, 'value.none')}`);
+        if (intent.preconditions.length > 0) {
+            lines.push('- preconditions:');
+            for (const precondition of intent.preconditions) {
+                const target = precondition.path ?? precondition.artifact ?? precondition.label ?? precondition.kind;
+                lines.push(`  - ${precondition.kind} ${target}: ${precondition.status}`);
+                lines.push(`    detail: ${precondition.detail}`);
+                if (precondition.satisfyIntent) {
+                    lines.push(`    satisfy_intent: ${precondition.satisfyIntent.intent} (${precondition.satisfyIntent.runnable ? 'runnable' : 'not_runnable'})`);
+                }
+            }
+        }
     }
     if ('effectGraph' in output.decision && output.decision.effectGraph) {
         const graph = output.decision.effectGraph;
@@ -216,6 +468,8 @@ function renderExplainDecision(output, lang) {
         else {
             lines.push(`- skill: ${route.skill}`, `- path: ${route.skillPath}`, `- trigger: ${route.trigger}`, `- required_input: ${route.requiredInput}`, `- edit_scope: ${route.editScope}`, `- risk: ${route.risk}`, `- verification_intents: ${route.verificationIntents.join(', ') || t(lang, 'value.none')}`, `- declared_command_intents: ${route.declaredCommandIntents.join(', ') || t(lang, 'value.none')}`, `- expected_output: ${route.expectedOutput}`);
         }
+        const evidence = output.decision.selectionEvidence;
+        lines.push('', 'Skill selection evidence', `- matched_by: ${evidence.matchedBy.join(', ') || t(lang, 'value.none')}`, `- required_inputs: ${evidence.requiredInputs.join(', ') || t(lang, 'value.none')}`, `- missing_inputs: ${evidence.missingInputs.join(', ') || t(lang, 'value.none')}`, `- candidate_adjuncts: ${evidence.candidateAdjuncts.join(', ') || t(lang, 'value.none')}`, `- unmatched_paths: ${evidence.unmatchedPaths.join(', ') || t(lang, 'value.none')}`, `- gap_notes: ${evidence.gapNotes.join(' | ') || t(lang, 'value.none')}`);
     }
     if ('surface' in output.decision) {
         const surface = output.decision.surface;
@@ -254,6 +508,19 @@ export async function runExplain(args, reporter, lang = 'en') {
     const json = args.includes('--json');
     const positional = args.filter((arg) => arg !== '--json');
     const [topic, targetArg, ...rest] = positional;
+    if (topic === 'why') {
+        const projectRoot = resolveMustflowRoot();
+        const output = await getWhyExplainOutput(projectRoot, targetArg, rest, lang, reporter);
+        if (!output) {
+            return 1;
+        }
+        if (json) {
+            reporter.stdout(JSON.stringify(output, null, 2));
+            return 0;
+        }
+        reporter.stdout(renderExplainDecision(output, lang));
+        return 0;
+    }
     if (topic === 'verify') {
         const verifyArgs = targetArg === undefined ? rest : [targetArg, ...rest];
         const parsed = parseExplainVerifyArgs(verifyArgs);

package/dist/cli/commands/run.js

@@ -1,4 +1,6 @@
+import { createHash } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
+import { acquireActiveRunLock } from '../../core/active-run-locks.js';
 import { createCommandEnv } from '../../core/command-env.js';
 import { createCorrelationId } from '../../core/correlation-id.js';
 import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
@@ -86,6 +88,20 @@ function writeLatestProfile(profiler, options, input) {
     }
     profiler.writeLatest(input);
 }
+function createPlanCommandHash(plan) {
+    const payload = {
+        mode: plan.mode,
+        cwd: plan.relativeCwd,
+        argv: plan.commandArgv ?? null,
+        cmd: plan.shellCommand ?? null,
+    };
+    return `sha256:${createHash('sha256').update(JSON.stringify(payload)).digest('hex')}`;
+}
+function renderActiveLockConflictMessage(intentName, conflicts) {
+    const [first] = conflicts;
+    const detail = first ? `${first.lock} conflicts with active intent ${first.conflictsWithIntent} (pid ${first.conflictsWithPid})` : 'unknown active lock conflict';
+    return `mf run ${intentName} is blocked by an active run lock: ${detail}`;
+}
 export function getRunHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf run <intent> [options]',
@@ -187,88 +203,104 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         });
         return 1;
     }
-    const runReceiptPolicy = profiler.measure('retention_policy', () => resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot)));
-    const env = profiler.measure('environment', () => createCommandEnv(projectRoot, { policy: plan.envPolicy, allowlist: plan.envAllowlist }));
-    const writeTracker = profiler.measure('write_drift_before', () => startRunWriteTracking(projectRoot, contract, intentName, {
-        additionalDeclaredPaths: options.additionalDeclaredWritePaths,
-    }));
-    const stdoutTailBytes = Math.min(runReceiptPolicy.stdoutTailBytes, plan.maxOutputBytes);
-    const stderrTailBytes = Math.min(runReceiptPolicy.stderrTailBytes, plan.maxOutputBytes);
-    let streamedOutput = false;
-    const childStartedAtMs = performance.now();
-    const startedAt = new Date();
-    const result = await profiler.measureAsync('child_command', async () => {
-        if (plan.commandArgv) {
+    const activeRunLock = profiler.measure('active_lock_acquire', () => acquireActiveRunLock(projectRoot, contract, intentName, { commandHash: createPlanCommandHash(plan) }));
+    if (!activeRunLock.ok) {
+        reporter.stderr(renderCliError(renderActiveLockConflictMessage(intentName, activeRunLock.conflicts), 'mf run --dry-run --json', lang));
+        writeLatestProfile(profiler, options, {
+            projectRoot,
+            intent: intentName,
+            status: 'blocked',
+            previewMode: null,
+        });
+        return 1;
+    }
+    try {
+        const runReceiptPolicy = profiler.measure('retention_policy', () => resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot)));
+        const env = profiler.measure('environment', () => createCommandEnv(projectRoot, { policy: plan.envPolicy, allowlist: plan.envAllowlist }));
+        const writeTracker = profiler.measure('write_drift_before', () => startRunWriteTracking(projectRoot, contract, intentName, {
+            additionalDeclaredPaths: options.additionalDeclaredWritePaths,
+        }));
+        const stdoutTailBytes = Math.min(runReceiptPolicy.stdoutTailBytes, plan.maxOutputBytes);
+        const stderrTailBytes = Math.min(runReceiptPolicy.stderrTailBytes, plan.maxOutputBytes);
+        let streamedOutput = false;
+        const childStartedAtMs = performance.now();
+        const startedAt = new Date();
+        const result = await profiler.measureAsync('child_command', async () => {
+            if (plan.commandArgv) {
+                streamedOutput = !json;
+                return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
+            }
             streamedOutput = !json;
-            return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
+            return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
+        });
+        const childDurationMs = performance.now() - childStartedAtMs;
+        const finishedAt = new Date();
+        const writeDrift = profiler.measure('write_drift_after', () => finishRunWriteTracking(writeTracker));
+        const exitCode = typeof result.status === 'number' ? result.status : null;
+        const runStatus = getRunStatus(result.error, exitCode, plan.successExitCodes);
+        let killMethod = null;
+        let termination = null;
+        if (runStatus === 'timed_out') {
+            termination = result.termination ?? createPendingTimeoutTermination(getKillMethod());
+            killMethod = termination.method;
+            if (!result.termination && result.pid) {
+                terminateProcessTree(result.pid);
+            }
         }
-        streamedOutput = !json;
-        return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
-    });
-    const childDurationMs = performance.now() - childStartedAtMs;
-    const finishedAt = new Date();
-    const writeDrift = profiler.measure('write_drift_after', () => finishRunWriteTracking(writeTracker));
-    const exitCode = typeof result.status === 'number' ? result.status : null;
-    const runStatus = getRunStatus(result.error, exitCode, plan.successExitCodes);
-    let killMethod = null;
-    let termination = null;
-    if (runStatus === 'timed_out') {
-        termination = result.termination ?? createPendingTimeoutTermination(getKillMethod());
-        killMethod = termination.method;
-        if (!result.termination && result.pid) {
-            terminateProcessTree(result.pid);
+        const receipt = profiler.measure('receipt_create', () => assembleRunReceipt({
+            correlationId: options.correlationId ?? createCorrelationId('run'),
+            intentName,
+            runStatus,
+            startedAt,
+            finishedAt,
+            projectRoot,
+            plan,
+            result,
+            exitCode,
+            killMethod,
+            termination,
+            writeDrift,
+            executorOverheadMs: Math.max(0, Math.round((performance.now() - executorStartedAtMs - childDurationMs) * 1000) / 1000),
+            phaseTimings: profiler.getReceiptPhases(),
+            stdoutTailBytes: runReceiptPolicy.stdoutTailBytes,
+            stderrTailBytes: runReceiptPolicy.stderrTailBytes,
+        }));
+        if (options.writeLatestReceipt !== false) {
+            profiler.measure('receipt_write', () => writeRunReceipt(projectRoot, receipt));
         }
-    }
-    const receipt = profiler.measure('receipt_create', () => assembleRunReceipt({
-        correlationId: options.correlationId ?? createCorrelationId('run'),
-        intentName,
-        runStatus,
-        startedAt,
-        finishedAt,
-        projectRoot,
-        plan,
-        result,
-        exitCode,
-        killMethod,
-        termination,
-        writeDrift,
-        executorOverheadMs: Math.max(0, Math.round((performance.now() - executorStartedAtMs - childDurationMs) * 1000) / 1000),
-        phaseTimings: profiler.getReceiptPhases(),
-        stdoutTailBytes: runReceiptPolicy.stdoutTailBytes,
-        stderrTailBytes: runReceiptPolicy.stderrTailBytes,
-    }));
-    if (options.writeLatestReceipt !== false) {
-        profiler.measure('receipt_write', () => writeRunReceipt(projectRoot, receipt));
-    }
-    if (options.recordPerformanceHistory !== false) {
-        profiler.measure('performance_history_write', () => recordRunPerformanceHistory(projectRoot, receipt));
-    }
-    writeLatestProfile(profiler, options, {
-        projectRoot,
-        intent: intentName,
-        status: runStatus,
-        previewMode: null,
-    });
-    if (json) {
-        reporter.stdout(JSON.stringify(receipt, null, 2));
-        return runStatus === 'passed' ? 0 : 1;
-    }
-    if (!streamedOutput) {
-        emitOutput(reporter, result.stdout, 'stdout');
-        emitOutput(reporter, result.stderr, 'stderr');
-    }
-    if (result.error) {
-        const errorWithCode = result.error;
-        if (errorWithCode.code === 'ETIMEDOUT') {
-            reporter.stderr(t(lang, 'run.error.timedOut', { intent: intentName, seconds: plan.timeoutSeconds }));
-            return 1;
+        if (options.recordPerformanceHistory !== false) {
+            profiler.measure('performance_history_write', () => recordRunPerformanceHistory(projectRoot, receipt));
+        }
+        writeLatestProfile(profiler, options, {
+            projectRoot,
+            intent: intentName,
+            status: runStatus,
+            previewMode: null,
+        });
+        if (json) {
+            reporter.stdout(JSON.stringify(receipt, null, 2));
+            return runStatus === 'passed' ? 0 : 1;
         }
-        if (isOutputLimitExceededError(result.error)) {
-            reporter.stderr(t(lang, 'run.error.outputLimitExceeded', { intent: intentName, message: result.error.message }));
+        if (!streamedOutput) {
+            emitOutput(reporter, result.stdout, 'stdout');
+            emitOutput(reporter, result.stderr, 'stderr');
+        }
+        if (result.error) {
+            const errorWithCode = result.error;
+            if (errorWithCode.code === 'ETIMEDOUT') {
+                reporter.stderr(t(lang, 'run.error.timedOut', { intent: intentName, seconds: plan.timeoutSeconds }));
+                return 1;
+            }
+            if (isOutputLimitExceededError(result.error)) {
+                reporter.stderr(t(lang, 'run.error.outputLimitExceeded', { intent: intentName, message: result.error.message }));
+                return 1;
+            }
+            reporter.stderr(t(lang, 'run.error.startFailed', { intent: intentName, message: result.error.message }));
             return 1;
         }
-        reporter.stderr(t(lang, 'run.error.startFailed', { intent: intentName, message: result.error.message }));
-        return 1;
+        return runStatus === 'passed' ? 0 : 1;
+    }
+    finally {
+        activeRunLock.handle.release();
     }
-    return runStatus === 'passed' ? 0 : 1;
 }

package/dist/cli/commands/verify.js

@@ -12,6 +12,7 @@ import { createScopeDiffRisks } from '../../core/scope-risk.js';
 import { countValidationRatchetVerdictEffects, createValidationRatchetRisks, } from '../../core/validation-ratchet.js';
 import { finishRunWriteBatchTracking, startRunWriteBatchTracking, } from '../../core/run-write-drift.js';
 import { readCommandContract } from '../../core/config-loading.js';
+import { evaluateCommandPreconditions, } from '../../core/command-preconditions.js';
 import { DEFAULT_VERIFY_PARALLELISM, parseVerifyArgs, resolveVerifyParallelism, } from './verify/args.js';
 import { createInputFromChanged, createSyntheticClassificationReport, planErrorMessageKey, readInputFromClassificationReport, resolveVerifyInputPath, writeChangedPlan, } from './verify/input.js';
 import { readExternalEvidenceFile, readReproEvidenceFile } from './verify/evidence-input.js';
@@ -879,9 +880,22 @@ async function createPlanOnlyOutput(input, projectRoot) {
     }
     const scheduledIntents = Array.from(new Set(report.schedule.entries.map((entry) => entry.intent)));
     const graphsByIntent = await readLocalCommandEffectGraphs(projectRoot, scheduledIntents);
+    const preconditionsByIntent = new Map(scheduledIntents.map((intent) => [intent, evaluateCommandPreconditions(projectRoot, contract, intent)]));
     const firstGraph = graphsByIntent.get(firstEntry.intent);
     if (!firstGraph) {
-        return { ...report, correlation_id: input.correlationId, verification_plan_id: verificationPlanId, requirements };
+        return {
+            ...report,
+            correlation_id: input.correlationId,
+            verification_plan_id: verificationPlanId,
+            requirements,
+            schedule: {
+                ...report.schedule,
+                entries: report.schedule.entries.map((entry) => ({
+                    ...entry,
+                    preconditions: preconditionsByIntent.get(entry.intent) ?? [],
+                })),
+            },
+        };
     }
     return {
         ...report,
@@ -893,6 +907,7 @@ async function createPlanOnlyOutput(input, projectRoot) {
             entries: report.schedule.entries.map((entry) => ({
                 ...entry,
                 effectGraph: graphsByIntent.get(entry.intent) ?? firstGraph,
+                preconditions: preconditionsByIntent.get(entry.intent) ?? [],
             })),
         },
     };