mustflow 2.22.15 → 2.22.16

package/dist/cli/commands/check.js

@@ -69,5 +69,6 @@ export function runCheck(args, reporter, lang = 'en') {
     for (const issue of issues) {
         reporter.stderr(issue);
     }
+    reporter.stderr(t(lang, 'check.result.failed', { count: issues.length }));
     return 1;
 }

package/dist/cli/commands/context.js

@@ -86,10 +86,10 @@ export async function runContext(args, reporter, lang = 'en') {
     }
     const context = getAgentContext(mustflowRoot);
     reporter.stdout(t(lang, 'context.title'));
-    reporter.stdout(`${t(lang, 'label.installed')}: ${context.installed ? 'yes' : 'no'}`);
+    reporter.stdout(`${t(lang, 'label.installed')}: ${context.installed ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
     reporter.stdout(`${t(lang, 'label.mustflowRoot')}: ${context.mustflow_root}`);
-    reporter.stdout(`${t(lang, 'label.commandContract')}: ${context.command_contract.exists ? 'present' : 'missing'}`);
+    reporter.stdout(`${t(lang, 'label.commandContract')}: ${context.command_contract.exists ? t(lang, 'value.present') : t(lang, 'value.missing')}`);
     reporter.stdout(`${t(lang, 'label.runnableIntents')}: ${context.command_contract.runnable_intents.length}`);
-    reporter.stdout(`${t(lang, 'label.latestRun')}: ${context.latest_run.exists ? 'present' : 'missing'}`);
+    reporter.stdout(`${t(lang, 'label.latestRun')}: ${context.latest_run.exists ? t(lang, 'value.present') : t(lang, 'value.missing')}`);
     return 0;
 }

package/dist/cli/commands/doctor.js

@@ -223,20 +223,32 @@ function getDiagnosticLabel(id, lang) {
             return t(lang, 'doctor.diagnostic.latestRun');
     }
 }
+function getDiagnosticStatusLabel(status, lang) {
+    switch (status) {
+        case 'ok':
+            return t(lang, 'doctor.status.ok');
+        case 'warn':
+            return t(lang, 'doctor.status.warn');
+        case 'fail':
+            return t(lang, 'doctor.status.fail');
+        case 'info':
+            return t(lang, 'doctor.status.info');
+    }
+}
 function renderDoctorOutput(output, lang) {
     const lines = [];
     lines.push(t(lang, 'doctor.title'));
     lines.push(`${t(lang, 'label.mustflowRoot')}: ${output.mustflow_root}`);
-    lines.push(`${t(lang, 'label.installed')}: ${output.installed ? 'yes' : 'no'}`);
-    lines.push(`${t(lang, 'doctor.label.strict')}: ${output.strict ? 'yes' : 'no'}`);
-    lines.push(`${t(lang, 'doctor.label.check')}: ${output.check.ok ? 'passed' : 'failed'}`);
+    lines.push(`${t(lang, 'label.installed')}: ${output.installed ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
+    lines.push(`${t(lang, 'doctor.label.strict')}: ${output.strict ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
+    lines.push(`${t(lang, 'doctor.label.check')}: ${output.check.ok ? t(lang, 'value.passed') : t(lang, 'value.failed')}`);
     lines.push(`${t(lang, 'doctor.label.issues')}: ${output.check.issue_count}`);
-    lines.push(`${t(lang, 'label.commandContract')}: ${output.context.command_contract_exists ? 'present' : 'missing'}`);
+    lines.push(`${t(lang, 'label.commandContract')}: ${output.context.command_contract_exists ? t(lang, 'value.present') : t(lang, 'value.missing')}`);
     lines.push(`${t(lang, 'label.runnableIntents')}: ${output.context.runnable_intents.length}`);
     lines.push('', t(lang, 'doctor.section.health'));
     for (const diagnostic of output.diagnostics) {
         const action = diagnostic.action && diagnostic.status !== 'ok' ? ` (${t(lang, 'doctor.actionLabel')}: ${diagnostic.action})` : '';
-        lines.push(`- [${diagnostic.status}] ${getDiagnosticLabel(diagnostic.id, lang)}: ${diagnostic.summary}${action}`);
+        lines.push(`- [${getDiagnosticStatusLabel(diagnostic.status, lang)}] ${getDiagnosticLabel(diagnostic.id, lang)}: ${diagnostic.summary}${action}`);
     }
     if (output.check.issues.length > 0) {
         lines.push('', t(lang, 'doctor.section.issueList'));

package/dist/cli/commands/explain.js

@@ -14,11 +14,12 @@ import { explainSourceAnchor } from '../../core/source-anchor-explanation.js';
 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';
+import { createRunPlan, } from '../lib/run-plan.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 why <target> [options]',
+        usage: 'mf explain <topic> [target] [options] | mf explain verify --reason <event> [options] | mf explain why <target> [options] | mf explain --why-blocked <intent> [options]',
         summary: t(lang, 'explain.help.summary'),
         options: [
             { label: '--json', description: t(lang, 'cli.option.json') },
@@ -33,6 +34,8 @@ export function getExplainHelp(lang = 'en') {
             'mf explain asset-optimization --json',
             'mf explain command test',
             'mf explain command lint --json',
+            'mf explain --why-blocked deploy',
+            'mf explain --why-blocked lint --json',
             'mf explain retention',
             'mf explain retention --json',
             'mf explain verify --reason code_change',
@@ -92,6 +95,43 @@ async function getCommandExplainOutput(projectRoot, commandName) {
         decision: effectGraph ? { ...decision, effectGraph } : decision,
     };
 }
+function getWhyBlockedExplainOutput(projectRoot, commandName) {
+    const contract = readCommandContract(projectRoot);
+    const plan = createRunPlan(projectRoot, contract, commandName);
+    const commandDecision = explainCommandIntent(contract, commandName, { projectRoot });
+    const blockedRunPlan = {
+        runnable: plan.ok,
+        reasonCode: plan.reasonCode,
+        detail: plan.detail,
+        status: plan.intentStatus,
+        lifecycle: plan.lifecycle,
+        runPolicy: plan.runPolicy,
+        configuredCwd: plan.configuredCwd,
+        timeoutSeconds: plan.timeoutSeconds,
+        mode: plan.mode,
+        writes: plan.writes ?? [],
+        suggestedIntentSnippet: plan.suggestedIntentSnippet,
+    };
+    const decision = {
+        ...commandDecision,
+        decision: plan.ok
+            ? `command intent "${commandName}" is not blocked for mf run`
+            : `command intent "${commandName}" is blocked for mf run`,
+        effectiveAction: plan.ok
+            ? `Run mf run ${commandName} when this intent is required for the changed behavior.`
+            : plan.suggestedIntentSnippet
+                ? 'Review the suggested command contract snippet before enabling agent execution.'
+                : commandDecision.effectiveAction,
+        blockedRunPlan,
+    };
+    return {
+        schema_version: EXPLAIN_SCHEMA_VERSION,
+        command: 'explain',
+        topic: 'why',
+        mustflow_root: projectRoot,
+        decision,
+    };
+}
 function getRetentionExplainOutput(projectRoot) {
     return {
         schema_version: EXPLAIN_SCHEMA_VERSION,
@@ -393,6 +433,13 @@ function renderExplainDecision(output, lang) {
         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 ('blockedRunPlan' in output.decision && output.decision.blockedRunPlan) {
+        const plan = output.decision.blockedRunPlan;
+        lines.push('', t(lang, 'explain.label.blockedRunPlan'), `- runnable: ${plan.runnable ? t(lang, 'value.yes') : t(lang, 'value.no')}`, `- reason_code: ${plan.reasonCode ?? t(lang, 'value.none')}`, `- detail: ${plan.detail ?? t(lang, 'value.none')}`, `- status: ${plan.status ?? t(lang, 'value.none')}`, `- lifecycle: ${plan.lifecycle ?? t(lang, 'value.none')}`, `- run_policy: ${plan.runPolicy ?? t(lang, 'value.none')}`, `- configured_cwd: ${plan.configuredCwd ?? t(lang, 'value.none')}`, `- timeout_seconds: ${plan.timeoutSeconds ?? t(lang, 'value.none')}`, `- mode: ${plan.mode ?? t(lang, 'value.none')}`, `- writes: ${plan.writes.join(', ') || t(lang, 'value.none')}`);
+        if (plan.suggestedIntentSnippet) {
+            lines.push('', `${t(lang, 'run.label.suggestedIntentSnippet')}:`, plan.suggestedIntentSnippet);
+        }
+    }
     if ('boundary' in output.decision) {
         lines.push('', t(lang, 'explain.label.authorityBoundary'), `- role: ${output.decision.boundary.role}`);
         if (output.decision.boundary.canDefine.length > 0) {
@@ -508,6 +555,23 @@ 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-blocked') {
+        if (!targetArg) {
+            printUsageError(reporter, t(lang, 'explain.error.missingCommand'), 'mf explain --help', getExplainHelp(lang), lang);
+            return 1;
+        }
+        if (rest.length > 0) {
+            printUsageError(reporter, t(lang, 'cli.error.unexpectedArgument', { argument: rest[0] }), 'mf explain --help', getExplainHelp(lang), lang);
+            return 1;
+        }
+        const output = getWhyBlockedExplainOutput(resolveMustflowRoot(), targetArg);
+        if (json) {
+            reporter.stdout(JSON.stringify(output, null, 2));
+            return 0;
+        }
+        reporter.stdout(renderExplainDecision(output, lang));
+        return 0;
+    }
     if (topic === 'why') {
         const projectRoot = resolveMustflowRoot();
         const output = await getWhyExplainOutput(projectRoot, targetArg, rest, lang, reporter);

package/dist/cli/commands/index.js

@@ -58,8 +58,8 @@ function renderIndexSummary(result, lang) {
         `source_anchors: ${result.source_anchor_count}`,
         `source_anchor_risk_signals: ${result.source_anchor_risk_signal_count}`,
         `index_mode: ${result.index_mode}`,
-        `reused_existing: ${result.reused_existing ? 'yes' : 'no'}`,
-        `${t(lang, 'label.wroteFiles')}: ${result.wrote_files ? 'yes' : 'no'}`,
+        `reused_existing: ${result.reused_existing ? t(lang, 'value.yes') : t(lang, 'value.no')}`,
+        `${t(lang, 'label.wroteFiles')}: ${result.wrote_files ? t(lang, 'value.yes') : t(lang, 'value.no')}`,
     ];
     if (result.dry_run) {
         lines.push(t(lang, 'index.dryRunNoFiles'));

package/dist/cli/commands/run.js

@@ -97,10 +97,16 @@ function createPlanCommandHash(plan) {
     };
     return `sha256:${createHash('sha256').update(JSON.stringify(payload)).digest('hex')}`;
 }
-function renderActiveLockConflictMessage(intentName, conflicts) {
+function renderActiveLockConflictMessage(intentName, conflicts, lang) {
     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}`;
+    const detail = first
+        ? t(lang, 'run.error.activeLockConflictDetail', {
+            lock: first.lock,
+            intent: first.conflictsWithIntent,
+            pid: first.conflictsWithPid,
+        })
+        : t(lang, 'run.error.activeLockConflictUnknown');
+    return t(lang, 'run.error.activeLockConflict', { intent: intentName, detail });
 }
 export function getRunHelp(lang = 'en') {
     return renderHelp({
@@ -205,7 +211,7 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
     }
     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));
+        reporter.stderr(renderCliError(renderActiveLockConflictMessage(intentName, activeRunLock.conflicts, lang), 'mf run --dry-run --json', lang));
         writeLatestProfile(profiler, options, {
             projectRoot,
             intent: intentName,

package/dist/cli/commands/status.js

@@ -53,7 +53,7 @@ export function runStatus(args, reporter, lang = 'en') {
         return 0;
     }
     reporter.stdout(t(lang, 'status.title'));
-    reporter.stdout(`${t(lang, 'label.installed')}: ${status.installed ? 'yes' : 'no'}`);
+    reporter.stdout(`${t(lang, 'label.installed')}: ${status.installed ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
     reporter.stdout(`${t(lang, 'label.manifestLock')}: ${status.manifestLock}`);
     reporter.stdout(`${t(lang, 'label.trackedFiles')}: ${status.trackedFiles}`);
     reporter.stdout(`${t(lang, 'label.changedFiles')}: ${status.changedFiles.length}`);

package/dist/cli/commands/verify.js

@@ -919,18 +919,24 @@ function renderVerifyOutput(output, lang) {
         `${t(lang, 'verify.label.reason')}: ${output.reason}`,
         `${t(lang, 'verify.label.planSource')}: ${output.plan_source ?? t(lang, 'value.none')}`,
         `${t(lang, 'verify.label.status')}: ${output.status}`,
-        `completion verdict: ${output.completion_verdict.status} (${output.completion_verdict.primary_reason})`,
-        `matched: ${output.summary.matched}`,
-        `ran: ${output.summary.ran}`,
-        `passed: ${output.summary.passed}`,
-        `failed: ${output.summary.failed}`,
-        `skipped: ${output.summary.skipped}`,
+        `${t(lang, 'verify.label.completionVerdict')}: ${output.completion_verdict.status} (${output.completion_verdict.primary_reason})`,
+        `${t(lang, 'verify.label.matched')}: ${output.summary.matched}`,
+        `${t(lang, 'verify.label.ran')}: ${output.summary.ran}`,
+        `${t(lang, 'verify.label.passed')}: ${output.summary.passed}`,
+        `${t(lang, 'verify.label.failed')}: ${output.summary.failed}`,
+        `${t(lang, 'verify.label.skipped')}: ${output.summary.skipped}`,
     ];
     if (output.parallelism) {
         const cpuAvailable = output.parallelism.cpu_available ?? t(lang, 'value.none');
-        lines.push(`parallelism: requested ${output.parallelism.requested}, effective ${output.parallelism.effective}, repository max ${output.parallelism.repository_max}, cpu available ${cpuAvailable}, mode ${output.parallelism.mode}`);
+        lines.push(`${t(lang, 'verify.label.parallelism')}: ${t(lang, 'verify.parallelism.summary', {
+            requested: output.parallelism.requested,
+            effective: output.parallelism.effective,
+            repositoryMax: output.parallelism.repository_max,
+            cpuAvailable,
+            mode: output.parallelism.mode,
+        })}`);
         if (output.parallelism.capped) {
-            lines.push(`parallelism note: ${output.parallelism.note}`);
+            lines.push(`${t(lang, 'verify.label.parallelismNote')}: ${output.parallelism.note}`);
         }
     }
     lines.push('', t(lang, 'verify.label.results'));

package/dist/cli/i18n/en.js

@@ -20,6 +20,10 @@ export const enMessages = {
     "value.yes": "yes",
     "value.no": "no",
     "value.none": "none",
+    "value.present": "present",
+    "value.missing": "missing",
+    "value.passed": "passed",
+    "value.failed": "failed",
     "command.adapters.summary": "Inspect host adapter compatibility without generating adapter files",
     "command.init.summary": "Copy the default mustflow agent workflow",
     "command.check.summary": "Validate mustflow files",
@@ -54,6 +58,7 @@ export const enMessages = {
     "check.help.exit.fail": "Validation failed or the command received invalid input",
     "check.result.passed": "mustflow check passed",
     "check.result.strictPassed": "mustflow strict check passed",
+    "check.result.failed": "mustflow check failed: {count} issue(s) found.",
     "contractLint.help.summary": "Inspect .mustflow/config/commands.toml for command-contract errors and warnings.",
     "contractLint.help.option.coverage": "Also report required_after coverage for change-classification reasons",
     "contractLint.help.option.suggest": "Suggest non-runnable intent snippets from package.json, Makefile, or justfile",
@@ -484,6 +489,10 @@ export const enMessages = {
     "doctor.section.issueList": "Issue list:",
     "doctor.section.suggestedCommands": "Suggested commands:",
     "doctor.actionLabel": "run",
+    "doctor.status.ok": "ok",
+    "doctor.status.warn": "warn",
+    "doctor.status.fail": "fail",
+    "doctor.status.info": "info",
     "doctor.diagnostic.install": "Install",
     "doctor.diagnostic.validation": "Validation",
     "doctor.diagnostic.skillRoutes": "Skill routes",
@@ -680,6 +689,9 @@ Read these files before working:
     "run.error.timedOut": 'Command "{intent}" timed out after {seconds} seconds',
     "run.error.outputLimitExceeded": 'Command "{intent}" exceeded max_output_bytes: {message}',
     "run.error.startFailed": 'Command "{intent}" failed to start: {message}',
+    "run.error.activeLockConflict": "mf run {intent} is blocked by an active run lock: {detail}",
+    "run.error.activeLockConflictDetail": "{lock} conflicts with active intent {intent} (pid {pid})",
+    "run.error.activeLockConflictUnknown": "unknown active lock conflict",
     "search.help.summary": "Search the local SQLite index for the mustflow workflow.",
     "search.help.option.limit": "Set the number of results to print. Default: 10, max: 50",
     "search.help.option.scope": "Select indexed workflow data, source anchors, or both. Default: workflow",
@@ -771,6 +783,15 @@ Read these files before working:
     "verify.label.planSource": "Plan source",
     "verify.label.status": "Status",
     "verify.label.results": "Results",
+    "verify.label.completionVerdict": "Completion verdict",
+    "verify.label.matched": "Matched",
+    "verify.label.ran": "Ran",
+    "verify.label.passed": "Passed",
+    "verify.label.failed": "Failed",
+    "verify.label.skipped": "Skipped",
+    "verify.label.parallelism": "Parallelism",
+    "verify.label.parallelismNote": "Parallelism note",
+    "verify.parallelism.summary": "requested {requested}, effective {effective}, repository max {repositoryMax}, CPU available {cpuAvailable}, mode {mode}",
     "verify.error.missingReason": "Missing verification reason",
     "verify.error.conflictingInputs": "Use only one of --reason, --from-classification, --from-plan, or --changed",
     "verify.error.writePlanRequiresChanged": "--write-plan requires --changed",
@@ -810,6 +831,7 @@ Read these files before working:
     "explain.label.publicSurface": "Public surface",
     "explain.label.validationReasons": "Validation reasons",
     "explain.label.affectedContracts": "Affected contracts",
+    "explain.label.blockedRunPlan": "Blocked run plan",
     "explain.error.missingTopic": "Missing explain topic",
     "explain.error.missingCommand": "Missing command intent",
     "explain.error.missingSkill": "Missing skill id",

package/dist/cli/i18n/es.js

@@ -20,6 +20,10 @@ export const esMessages = {
     "value.yes": "sí",
     "value.no": "no",
     "value.none": "ninguno",
+    "value.present": "presente",
+    "value.missing": "faltante",
+    "value.passed": "superado",
+    "value.failed": "fallido",
     "command.adapters.summary": "Inspecciona compatibilidad de adaptadores sin generar archivos",
     "command.init.summary": "Copia el flujo de trabajo de agente mustflow predeterminado",
     "command.check.summary": "Valida los archivos mustflow",
@@ -54,6 +58,7 @@ export const esMessages = {
     "check.help.exit.fail": "La validación falló o el comando recibió una entrada no válida",
     "check.result.passed": "comprobacion mustflow superada",
     "check.result.strictPassed": "comprobacion estricta de mustflow superada",
+    "check.result.failed": "comprobacion mustflow fallida: se encontraron {count} problema(s).",
     "contractLint.help.summary": "Inspecciona .mustflow/config/commands.toml para encontrar errores y advertencias del contrato de comandos.",
     "contractLint.help.option.coverage": "También informa cobertura required_after para razones de clasificación de cambios",
     "contractLint.help.option.suggest": "Sugiere fragmentos de intent no ejecutables desde package.json, Makefile o justfile",
@@ -484,6 +489,10 @@ export const esMessages = {
     "doctor.section.issueList": "Lista de problemas:",
     "doctor.section.suggestedCommands": "Comandos sugeridos:",
     "doctor.actionLabel": "ejecutar",
+    "doctor.status.ok": "ok",
+    "doctor.status.warn": "advertencia",
+    "doctor.status.fail": "fallo",
+    "doctor.status.info": "info",
     "doctor.diagnostic.install": "Instalación",
     "doctor.diagnostic.validation": "Validación",
     "doctor.diagnostic.skillRoutes": "Rutas de skills",
@@ -680,6 +689,9 @@ Lee estos archivos antes de trabajar:
     "run.error.timedOut": 'El comando "{intent}" agotó el tiempo después de {seconds} segundos',
     "run.error.outputLimitExceeded": 'El comando "{intent}" superó max_output_bytes: {message}',
     "run.error.startFailed": 'No se pudo iniciar el comando "{intent}": {message}',
+    "run.error.activeLockConflict": "mf run {intent} está bloqueado por un bloqueo de ejecución activo: {detail}",
+    "run.error.activeLockConflictDetail": "{lock} entra en conflicto con la intención activa {intent} (pid {pid})",
+    "run.error.activeLockConflictUnknown": "conflicto de bloqueo de ejecución activo desconocido",
     "search.help.summary": "Busca en el índice SQLite local del flujo de trabajo mustflow.",
     "search.help.option.limit": "Define la cantidad de resultados que se imprimen. Predeterminado: 10, máximo: 50",
     "search.help.option.scope": "Selecciona datos del flujo de trabajo indexados, anchors de código fuente o ambos. Predeterminado: workflow",
@@ -771,6 +783,15 @@ Lee estos archivos antes de trabajar:
     "verify.label.planSource": "Fuente del plan",
     "verify.label.status": "Estado",
     "verify.label.results": "Resultados",
+    "verify.label.completionVerdict": "Veredicto de finalización",
+    "verify.label.matched": "Coincidencias",
+    "verify.label.ran": "Ejecutadas",
+    "verify.label.passed": "Superadas",
+    "verify.label.failed": "Fallidas",
+    "verify.label.skipped": "Omitidas",
+    "verify.label.parallelism": "Paralelismo",
+    "verify.label.parallelismNote": "Nota de paralelismo",
+    "verify.parallelism.summary": "solicitado {requested}, efectivo {effective}, máximo del repositorio {repositoryMax}, CPU disponible {cpuAvailable}, modo {mode}",
     "verify.error.missingReason": "Falta la razón de verificación",
     "verify.error.conflictingInputs": "Usa solo uno de --reason, --from-classification, --from-plan o --changed",
     "verify.error.writePlanRequiresChanged": "--write-plan requiere --changed",
@@ -810,6 +831,7 @@ Lee estos archivos antes de trabajar:
     "explain.label.publicSurface": "Superficie publica",
     "explain.label.validationReasons": "Razones de validacion",
     "explain.label.affectedContracts": "Contratos afectados",
+    "explain.label.blockedRunPlan": "Plan de ejecución bloqueado",
     "explain.error.missingTopic": "Falta el tema de explicación",
     "explain.error.missingCommand": "Falta la intención de comando",
     "explain.error.missingSkill": "Falta el id de skill",

package/dist/cli/i18n/fr.js

@@ -20,6 +20,10 @@ export const frMessages = {
     "value.yes": "oui",
     "value.no": "non",
     "value.none": "aucun",
+    "value.present": "présent",
+    "value.missing": "manquant",
+    "value.passed": "réussi",
+    "value.failed": "échoué",
     "command.adapters.summary": "Inspecte la compatibilité des adaptateurs sans générer de fichiers",
     "command.init.summary": "Copie le flux de travail d'agent mustflow par défaut",
     "command.check.summary": "Valide les fichiers mustflow",
@@ -54,6 +58,7 @@ export const frMessages = {
     "check.help.exit.fail": "La validation a échoué ou la commande a reçu une entrée non valide",
     "check.result.passed": "vérification mustflow réussie",
     "check.result.strictPassed": "vérification stricte mustflow réussie",
+    "check.result.failed": "vérification mustflow échouée : {count} problème(s) trouvé(s).",
     "contractLint.help.summary": "Inspecte .mustflow/config/commands.toml pour trouver les erreurs et avertissements du contrat de commandes.",
     "contractLint.help.option.coverage": "Signale aussi la couverture required_after des raisons de classification",
     "contractLint.help.option.suggest": "Suggère des fragments d'intent non exécutables depuis package.json, Makefile ou justfile",
@@ -484,6 +489,10 @@ export const frMessages = {
     "doctor.section.issueList": "Liste des problèmes :",
     "doctor.section.suggestedCommands": "Commandes suggérées :",
     "doctor.actionLabel": "exécuter",
+    "doctor.status.ok": "ok",
+    "doctor.status.warn": "alerte",
+    "doctor.status.fail": "échec",
+    "doctor.status.info": "info",
     "doctor.diagnostic.install": "Installation",
     "doctor.diagnostic.validation": "Validation",
     "doctor.diagnostic.skillRoutes": "Routage des skills",
@@ -680,6 +689,9 @@ Lisez ces fichiers avant de travailler :
     "run.error.timedOut": 'La commande "{intent}" a expiré après {seconds} secondes',
     "run.error.outputLimitExceeded": 'La commande "{intent}" a dépassé max_output_bytes : {message}',
     "run.error.startFailed": 'Impossible de démarrer la commande "{intent}" : {message}',
+    "run.error.activeLockConflict": "mf run {intent} est bloqué par un verrou d'exécution actif : {detail}",
+    "run.error.activeLockConflictDetail": "{lock} entre en conflit avec l'intention active {intent} (pid {pid})",
+    "run.error.activeLockConflictUnknown": "conflit de verrou d'exécution actif inconnu",
     "search.help.summary": "Recherche dans l'index SQLite local du flux de travail mustflow.",
     "search.help.option.limit": "Définit le nombre de résultats à imprimer. Par défaut : 10, max : 50",
     "search.help.option.scope": "Sélectionne les données de workflow indexées, les anchors de source, ou les deux. Par défaut : workflow",
@@ -771,6 +783,15 @@ Lisez ces fichiers avant de travailler :
     "verify.label.planSource": "Source du plan",
     "verify.label.status": "État",
     "verify.label.results": "Résultats",
+    "verify.label.completionVerdict": "Verdict de complétion",
+    "verify.label.matched": "Correspondants",
+    "verify.label.ran": "Exécutés",
+    "verify.label.passed": "Réussis",
+    "verify.label.failed": "Échoués",
+    "verify.label.skipped": "Ignorés",
+    "verify.label.parallelism": "Parallélisme",
+    "verify.label.parallelismNote": "Note de parallélisme",
+    "verify.parallelism.summary": "demandé {requested}, effectif {effective}, maximum du dépôt {repositoryMax}, CPU disponible {cpuAvailable}, mode {mode}",
     "verify.error.missingReason": "Raison de vérification manquante",
     "verify.error.conflictingInputs": "Utilisez un seul de --reason, --from-classification, --from-plan ou --changed",
     "verify.error.writePlanRequiresChanged": "--write-plan nécessite --changed",
@@ -810,6 +831,7 @@ Lisez ces fichiers avant de travailler :
     "explain.label.publicSurface": "Surface publique",
     "explain.label.validationReasons": "Raisons de validation",
     "explain.label.affectedContracts": "Contrats affectes",
+    "explain.label.blockedRunPlan": "Plan d'exécution bloqué",
     "explain.error.missingTopic": "Sujet d'explication manquant",
     "explain.error.missingCommand": "Intention de commande manquante",
     "explain.error.missingSkill": "Identifiant de skill manquant",

package/dist/cli/i18n/hi.js

@@ -20,6 +20,10 @@ export const hiMessages = {
     "value.yes": "हाँ",
     "value.no": "नहीं",
     "value.none": "none",
+    "value.present": "मौजूद",
+    "value.missing": "गुम",
+    "value.passed": "पास",
+    "value.failed": "फेल",
     "command.adapters.summary": "एडाप्टर फ़ाइलें बनाए बिना होस्ट संगतता जाँचें",
     "command.init.summary": "डिफ़ॉल्ट mustflow एजेंट वर्कफ़्लो कॉपी करें",
     "command.check.summary": "mustflow फ़ाइलों की जाँच करें",
@@ -54,6 +58,7 @@ export const hiMessages = {
     "check.help.exit.fail": "सत्यापन विफल हुआ या कमांड को अमान्य इनपुट मिला",
     "check.result.passed": "mustflow check पास हुआ",
     "check.result.strictPassed": "mustflow strict check पास हुआ",
+    "check.result.failed": "mustflow check फेल हुआ: {count} समस्या मिली।",
     "contractLint.help.summary": ".mustflow/config/commands.toml में command-contract errors और warnings जाँचें.",
     "contractLint.help.option.coverage": "change-classification reasons के लिए required_after coverage भी report करें",
     "contractLint.help.option.suggest": "package.json, Makefile, या justfile से non-runnable intent snippets सुझाएँ",
@@ -484,6 +489,10 @@ export const hiMessages = {
     "doctor.section.issueList": "समस्या सूची:",
     "doctor.section.suggestedCommands": "सुझाई गई कमांड:",
     "doctor.actionLabel": "चलाएँ",
+    "doctor.status.ok": "ठीक",
+    "doctor.status.warn": "चेतावनी",
+    "doctor.status.fail": "फेल",
+    "doctor.status.info": "जानकारी",
     "doctor.diagnostic.install": "इंस्टॉल",
     "doctor.diagnostic.validation": "सत्यापन",
     "doctor.diagnostic.skillRoutes": "स्किल रूट",
@@ -680,6 +689,9 @@ export const hiMessages = {
     "run.error.timedOut": 'कमांड "{intent}" {seconds} सेकंड बाद time out हुई',
     "run.error.outputLimitExceeded": 'कमांड "{intent}" ने max_output_bytes सीमा पार की: {message}',
     "run.error.startFailed": 'कमांड "{intent}" शुरू नहीं हो सकी: {message}',
+    "run.error.activeLockConflict": "mf run {intent} सक्रिय रन लॉक के कारण रुका है: {detail}",
+    "run.error.activeLockConflictDetail": "{lock} सक्रिय intent {intent} से टकराता है (pid {pid})",
+    "run.error.activeLockConflictUnknown": "अज्ञात सक्रिय रन लॉक टकराव",
     "search.help.summary": "mustflow वर्कफ़्लो के लिए स्थानीय SQLite इंडेक्स में खोजें।",
     "search.help.option.limit": "प्रिंट किए जाने वाले परिणामों की संख्या सेट करें। डिफ़ॉल्ट: 10, अधिकतम: 50",
     "search.help.option.scope": "इंडेक्स किए गए वर्कफ़्लो डेटा, source anchors, या दोनों चुनें। डिफ़ॉल्ट: workflow",
@@ -771,6 +783,15 @@ export const hiMessages = {
     "verify.label.planSource": "Plan source",
     "verify.label.status": "Status",
     "verify.label.results": "Results",
+    "verify.label.completionVerdict": "Completion verdict",
+    "verify.label.matched": "Matched",
+    "verify.label.ran": "Ran",
+    "verify.label.passed": "Passed",
+    "verify.label.failed": "Failed",
+    "verify.label.skipped": "Skipped",
+    "verify.label.parallelism": "Parallelism",
+    "verify.label.parallelismNote": "Parallelism note",
+    "verify.parallelism.summary": "requested {requested}, effective {effective}, repository max {repositoryMax}, CPU available {cpuAvailable}, mode {mode}",
     "verify.error.missingReason": "Verification reason missing है",
     "verify.error.conflictingInputs": "--reason, --from-classification, --from-plan, या --changed में से केवल एक इस्तेमाल करें",
     "verify.error.writePlanRequiresChanged": "--write-plan के लिए --changed चाहिए",
@@ -810,6 +831,7 @@ export const hiMessages = {
     "explain.label.publicSurface": "Public surface",
     "explain.label.validationReasons": "Validation reasons",
     "explain.label.affectedContracts": "Affected contracts",
+    "explain.label.blockedRunPlan": "Blocked run plan",
     "explain.error.missingTopic": "Explain topic गुम है",
     "explain.error.missingCommand": "Command intent गुम है",
     "explain.error.missingSkill": "Skill id गुम है",

package/dist/cli/i18n/ko.js

@@ -20,6 +20,10 @@ export const koMessages = {
     "value.yes": "예",
     "value.no": "아니요",
     "value.none": "없음",
+    "value.present": "있음",
+    "value.missing": "없음",
+    "value.passed": "통과",
+    "value.failed": "실패",
     "command.adapters.summary": "어댑터 파일을 만들지 않고 호스트 호환성을 확인합니다",
     "command.init.summary": "기본 mustflow 에이전트 워크플로우를 복사합니다",
     "command.check.summary": "mustflow 파일을 검사합니다",
@@ -54,6 +58,7 @@ export const koMessages = {
     "check.help.exit.fail": "검증 실패 또는 잘못된 입력이 제공되었습니다",
     "check.result.passed": "mustflow 검사 통과",
     "check.result.strictPassed": "mustflow 엄격 검사 통과",
+    "check.result.failed": "mustflow 검사 실패: 문제 {count}개를 찾았습니다.",
     "contractLint.help.summary": ".mustflow/config/commands.toml의 명령 계약 오류와 경고를 확인합니다.",
     "contractLint.help.option.coverage": "변경 분류 이유에 대한 required_after 연결 상태도 보고합니다",
     "contractLint.help.option.suggest": "package.json, Makefile, justfile에서 실행 불가 후보 조각을 제안합니다",
@@ -484,6 +489,10 @@ export const koMessages = {
     "doctor.section.issueList": "문제 목록:",
     "doctor.section.suggestedCommands": "추천 명령:",
     "doctor.actionLabel": "명령",
+    "doctor.status.ok": "정상",
+    "doctor.status.warn": "주의",
+    "doctor.status.fail": "실패",
+    "doctor.status.info": "정보",
     "doctor.diagnostic.install": "설치",
     "doctor.diagnostic.validation": "검증",
     "doctor.diagnostic.skillRoutes": "스킬 라우팅",
@@ -680,6 +689,9 @@ export const koMessages = {
     "run.error.timedOut": '명령 "{intent}"가 {seconds}초 뒤 시간 초과되었습니다',
     "run.error.outputLimitExceeded": '명령 "{intent}"가 max_output_bytes 제한을 넘었습니다: {message}',
     "run.error.startFailed": '명령 "{intent}"를 시작하지 못했습니다: {message}',
+    "run.error.activeLockConflict": "mf run {intent} 실행이 활성 실행 잠금 때문에 차단되었습니다: {detail}",
+    "run.error.activeLockConflictDetail": "{lock} 잠금이 실행 중인 {intent} 의도와 충돌합니다(pid {pid})",
+    "run.error.activeLockConflictUnknown": "알 수 없는 활성 실행 잠금 충돌",
     "search.help.summary": "로컬 SQLite 색인에서 mustflow 워크플로우를 검색합니다.",
     "search.help.option.limit": "출력할 검색 결과 수를 설정합니다. 기본값: 10, 최대: 50",
     "search.help.option.scope": "색인된 워크플로 데이터, 소스 앵커, 또는 둘 다를 선택합니다. 기본값: workflow",
@@ -771,6 +783,15 @@ export const koMessages = {
     "verify.label.planSource": "계획 원본",
     "verify.label.status": "상태",
     "verify.label.results": "결과",
+    "verify.label.completionVerdict": "완료 판정",
+    "verify.label.matched": "일치",
+    "verify.label.ran": "실행",
+    "verify.label.passed": "통과",
+    "verify.label.failed": "실패",
+    "verify.label.skipped": "생략",
+    "verify.label.parallelism": "병렬 실행",
+    "verify.label.parallelismNote": "병렬 실행 참고",
+    "verify.parallelism.summary": "요청 {requested}, 실제 {effective}, 저장소 상한 {repositoryMax}, 사용 가능 CPU {cpuAvailable}, 모드 {mode}",
     "verify.error.missingReason": "검증 이유가 없습니다",
     "verify.error.conflictingInputs": "--reason, --from-classification, --from-plan, --changed 중 하나만 사용하세요",
     "verify.error.writePlanRequiresChanged": "--write-plan에는 --changed가 필요합니다",
@@ -810,6 +831,7 @@ export const koMessages = {
     "explain.label.publicSurface": "공개 표면",
     "explain.label.validationReasons": "검증 이유",
     "explain.label.affectedContracts": "영향받는 계약",
+    "explain.label.blockedRunPlan": "차단된 실행 계획",
     "explain.error.missingTopic": "설명할 주제가 없습니다",
     "explain.error.missingCommand": "설명할 명령 의도가 없습니다",
     "explain.error.missingSkill": "설명할 스킬 식별자가 없습니다",

package/dist/cli/i18n/zh.js

@@ -20,6 +20,10 @@ export const zhMessages = {
     "value.yes": "是",
     "value.no": "否",
     "value.none": "无",
+    "value.present": "存在",
+    "value.missing": "缺失",
+    "value.passed": "通过",
+    "value.failed": "失败",
     "command.adapters.summary": "不生成适配器文件，检查宿主兼容性",
     "command.init.summary": "复制默认的 mustflow 代理工作流",
     "command.check.summary": "验证 mustflow 文件",
@@ -54,6 +58,7 @@ export const zhMessages = {
     "check.help.exit.fail": "验证失败，或命令收到了无效输入",
     "check.result.passed": "mustflow 检查已通过",
     "check.result.strictPassed": "mustflow 严格检查已通过",
+    "check.result.failed": "mustflow 检查失败：发现 {count} 个问题。",
     "contractLint.help.summary": "检查 .mustflow/config/commands.toml 中的命令契约错误和警告。",
     "contractLint.help.option.coverage": "同时报告变更分类原因的 required_after 覆盖情况",
     "contractLint.help.option.suggest": "从 package.json、Makefile 或 justfile 建议不可运行的 intent 片段",
@@ -484,6 +489,10 @@ export const zhMessages = {
     "doctor.section.issueList": "问题列表：",
     "doctor.section.suggestedCommands": "建议命令：",
     "doctor.actionLabel": "运行",
+    "doctor.status.ok": "正常",
+    "doctor.status.warn": "警告",
+    "doctor.status.fail": "失败",
+    "doctor.status.info": "信息",
     "doctor.diagnostic.install": "安装",
     "doctor.diagnostic.validation": "验证",
     "doctor.diagnostic.skillRoutes": "技能路由",
@@ -680,6 +689,9 @@ export const zhMessages = {
     "run.error.timedOut": '命令 "{intent}" 在 {seconds} 秒后超时',
     "run.error.outputLimitExceeded": '命令 "{intent}" 超过 max_output_bytes：{message}',
     "run.error.startFailed": '命令 "{intent}" 启动失败：{message}',
+    "run.error.activeLockConflict": "mf run {intent} 被活动运行锁阻止：{detail}",
+    "run.error.activeLockConflictDetail": "{lock} 与活动 intent {intent} 冲突（pid {pid}）",
+    "run.error.activeLockConflictUnknown": "未知的活动运行锁冲突",
     "search.help.summary": "搜索本地 SQLite 索引中的 mustflow 工作流。",
     "search.help.option.limit": "设置要输出的结果数量。默认值：10，最大：50",
     "search.help.option.scope": "选择已索引的工作流数据、源码 anchors，或两者。默认值：workflow",
@@ -771,6 +783,15 @@ export const zhMessages = {
     "verify.label.planSource": "计划来源",
     "verify.label.status": "状态",
     "verify.label.results": "结果",
+    "verify.label.completionVerdict": "完成判定",
+    "verify.label.matched": "匹配",
+    "verify.label.ran": "已运行",
+    "verify.label.passed": "已通过",
+    "verify.label.failed": "已失败",
+    "verify.label.skipped": "已跳过",
+    "verify.label.parallelism": "并行度",
+    "verify.label.parallelismNote": "并行度说明",
+    "verify.parallelism.summary": "请求 {requested}，实际 {effective}，仓库上限 {repositoryMax}，可用 CPU {cpuAvailable}，模式 {mode}",
     "verify.error.missingReason": "缺少验证原因",
     "verify.error.conflictingInputs": "只能使用 --reason、--from-classification、--from-plan 或 --changed 其中之一",
     "verify.error.writePlanRequiresChanged": "--write-plan 需要 --changed",
@@ -810,6 +831,7 @@ export const zhMessages = {
     "explain.label.publicSurface": "公共表面",
     "explain.label.validationReasons": "验证原因",
     "explain.label.affectedContracts": "受影响契约",
+    "explain.label.blockedRunPlan": "被阻止的运行计划",
     "explain.error.missingTopic": "缺少 explain 主题",
     "explain.error.missingCommand": "缺少命令意图",
     "explain.error.missingSkill": "缺少技能标识",

package/dist/cli/index.js

@@ -35,6 +35,7 @@ function getTopLevelHelp(lang) {
             'mf map --write',
             'mf search mustflow_check',
             'mf explain authority AGENTS.md',
+            'mf explain --why-blocked test',
             'mf impact --changed',
             'mf upgrade --dry-run',
             'mf verify --changed --plan-only --json',

package/dist/cli/lib/filesystem.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 export { ensureFileTargetInsideWithoutSymlinks, ensureInside, ensureInsideWithoutSymlinks, readFileInsideWithoutSymlinks, readUtf8FileInsideWithoutSymlinks, writeFileInsideWithoutSymlinks, writeUtf8FileInsideWithoutSymlinks, } from '../../core/safe-filesystem.js';
 import { readFileInsideWithoutSymlinks, writeFileInsideWithoutSymlinks, } from '../../core/safe-filesystem.js';
 export function toPosixPath(value) {
-    return value.split(path.sep).join('/');
+    return value.replace(/\\/gu, '/');
 }
 export function copyFileInsideWithoutSymlinks(sourceParentPath, sourcePath, targetParentPath, targetPath) {
     const content = readFileInsideWithoutSymlinks(sourceParentPath, sourcePath);

package/dist/cli/lib/local-index/index.js

@@ -2311,10 +2311,10 @@ export async function searchLocalIndex(projectRoot, query, options = {}) {
     catch {
         return searchLocalWorkflowFilesDirectly(projectRoot, databasePath, normalizedQuery, limit, scope);
     }
-    const cacheLayers = readCacheLayerSets(projectRoot);
     let capabilities = searchCapabilities(false);
     const results = [];
     try {
+        const cacheLayers = readCacheLayerSets(projectRoot);
         const stalePaths = getStalePaths(projectRoot, database);
         capabilities = readStoredSearchCapabilities(database);
         const indexedMatches = getIndexedSearchMatches(database, normalizedQuery);

package/dist/cli/lib/npm-version-check.js

@@ -1,3 +1,4 @@
+import path from 'node:path';
 const DEFAULT_NPM_REGISTRY_URL = 'https://registry.npmjs.org';
 const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 3_000;
 const PACKAGE_MANAGER_COMMANDS = [
@@ -37,6 +38,7 @@ const PACKAGE_MANAGER_COMMANDS = [
         },
     },
 ];
+const PACKAGE_MANAGER_IDS = PACKAGE_MANAGER_COMMANDS.map((entry) => entry.id);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -102,23 +104,31 @@ function getTimeoutMs() {
     const parsed = rawValue ? Number(rawValue) : DEFAULT_VERSION_CHECK_TIMEOUT_MS;
     return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : DEFAULT_VERSION_CHECK_TIMEOUT_MS;
 }
-function detectPackageManagerId() {
-    const signals = [
-        process.env.npm_config_user_agent,
-        process.env.npm_execpath,
-        process.execPath,
-        process.argv[1],
-        import.meta.url,
-    ]
-        .filter((signal) => typeof signal === 'string' && signal.length > 0)
-        .map((signal) => signal.toLowerCase());
-    for (const id of ['bun', 'pnpm', 'yarn', 'deno', 'npm']) {
-        if (signals.some((signal) => signal.includes(id))) {
+function packageManagerFromUserAgent(userAgent) {
+    const firstToken = userAgent?.trim().toLowerCase().split(/\s+/u)[0] ?? '';
+    for (const id of PACKAGE_MANAGER_IDS) {
+        if (firstToken === id || firstToken.startsWith(`${id}/`)) {
             return id;
         }
     }
     return null;
 }
+function packageManagerFromExecutablePath(executablePath) {
+    if (!executablePath) {
+        return null;
+    }
+    const normalized = path
+        .basename(executablePath)
+        .toLowerCase()
+        .replace(/\.(?:cmd|ps1|exe|cjs|mjs|js)$/u, '')
+        .replace(/-cli$/u, '');
+    return PACKAGE_MANAGER_IDS.find((id) => normalized === id) ?? null;
+}
+function detectPackageManagerId() {
+    return (packageManagerFromUserAgent(process.env.npm_config_user_agent) ??
+        packageManagerFromExecutablePath(process.env.npm_execpath) ??
+        packageManagerFromExecutablePath(process.execPath));
+}
 function getPackageInstallCommands(packageName) {
     const detectedId = detectPackageManagerId();
     const commands = [...PACKAGE_MANAGER_COMMANDS];

package/dist/core/active-run-locks.js

@@ -195,7 +195,7 @@ function acquireMutex(projectRoot) {
     const root = activeLockRoot(projectRoot);
     const mutex = activeLockMutexDirectory(projectRoot);
     mkdirSync(root, { recursive: true });
-    const startedAt = Date.now();
+    let startedAt = Date.now();
     while (true) {
         try {
             mkdirSync(mutex);
@@ -215,11 +215,13 @@ function acquireMutex(projectRoot) {
                     const staleByAge = Number.isFinite(ownerStartedAt) && Date.now() - ownerStartedAt > LOCK_MUTEX_STALE_MS;
                     if (!isProcessLive(ownerPid) || staleByAge) {
                         rmSync(mutex, { recursive: true, force: true });
+                        startedAt = Date.now();
                         continue;
                     }
                 }
                 catch {
                     rmSync(mutex, { recursive: true, force: true });
+                    startedAt = Date.now();
                     continue;
                 }
                 throw new Error('active_run_lock_mutex_busy');

package/dist/core/command-preconditions.js

@@ -108,13 +108,14 @@ function listProjectFiles(projectRoot) {
     walk(projectRoot);
     return files.sort((left, right) => left.localeCompare(right));
 }
-function matchingSourceFiles(projectRoot, patterns) {
+function matchingSourceFiles(projectRoot, patterns, context) {
     const safePatterns = patterns.filter((pattern) => !relativePathIsUnsafe(pattern));
     const matchers = safePatterns.map(globToRegExp);
     if (matchers.length === 0) {
         return [];
     }
-    return listProjectFiles(projectRoot).filter((filePath) => matchers.some((matcher) => matcher.test(filePath)));
+    context.projectFiles ??= listProjectFiles(projectRoot);
+    return context.projectFiles.filter((filePath) => matchers.some((matcher) => matcher.test(filePath)));
 }
 function evaluatePathExists(projectRoot, declaration, satisfyIntent) {
     const pathValue = declaration.path;
@@ -158,7 +159,7 @@ function evaluatePathExists(projectRoot, declaration, satisfyIntent) {
         satisfyIntent,
     };
 }
-function evaluateArtifactFreshness(projectRoot, declaration, satisfyIntent) {
+function evaluateArtifactFreshness(projectRoot, declaration, satisfyIntent, context) {
     const artifact = declaration.artifact;
     if (!artifact || declaration.sources.length === 0) {
         return {
@@ -200,7 +201,7 @@ function evaluateArtifactFreshness(projectRoot, declaration, satisfyIntent) {
             satisfyIntent,
         };
     }
-    const sourceFiles = matchingSourceFiles(projectRoot, declaration.sources);
+    const sourceFiles = matchingSourceFiles(projectRoot, declaration.sources, context);
     if (sourceFiles.length === 0) {
         return {
             kind: declaration.kind,
@@ -215,9 +216,26 @@ function evaluateArtifactFreshness(projectRoot, declaration, satisfyIntent) {
         };
     }
     const artifactMtime = statSync(artifactPath).mtimeMs;
-    const newest = sourceFiles
-        .map((source) => ({ source, mtime: statSync(path.join(projectRoot, ...source.split('/'))).mtimeMs }))
-        .sort((left, right) => right.mtime - left.mtime)[0];
+    let newest = null;
+    for (const source of sourceFiles) {
+        const mtime = statSync(path.join(projectRoot, ...source.split('/'))).mtimeMs;
+        if (!newest || mtime > newest.mtime) {
+            newest = { source, mtime };
+        }
+    }
+    if (!newest) {
+        return {
+            kind: declaration.kind,
+            label: declaration.label,
+            status: 'unknown',
+            detail: 'no readable source files matched the freshness precondition.',
+            path: null,
+            artifact,
+            sources: declaration.sources,
+            newestSource: null,
+            satisfyIntent,
+        };
+    }
     const stale = newest.mtime > artifactMtime;
     return {
         kind: declaration.kind,
@@ -238,13 +256,14 @@ export function evaluateCommandPreconditions(projectRoot, contract, intentName)
     if (!isRecord(intent)) {
         return [];
     }
+    const context = { projectFiles: null };
     return readPreconditionDeclarations(intent).map((declaration) => {
         const satisfyIntent = createSatisfyIntentSummary(contract, declaration.satisfyIntent);
         if (declaration.kind === 'path_exists') {
             return evaluatePathExists(projectRoot, declaration, satisfyIntent);
         }
         if (declaration.kind === 'artifact_freshness') {
-            return evaluateArtifactFreshness(projectRoot, declaration, satisfyIntent);
+            return evaluateArtifactFreshness(projectRoot, declaration, satisfyIntent, context);
         }
         return {
             kind: declaration.kind,

package/dist/core/run-performance-history.js

@@ -276,15 +276,28 @@ function createSamplesFile(samples) {
 function serialize(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
+function serializedHistorySize(samples, today) {
+    return (Buffer.byteLength(serialize(createSamplesFile(samples)), 'utf8') +
+        Buffer.byteLength(serialize(createSummary(samples, today)), 'utf8'));
+}
 function enforceSizeLimit(samples, today) {
-    let pruned = [...samples];
-    let summary = createSummary(pruned, today);
-    while (pruned.length > 0 &&
-        Buffer.byteLength(serialize(createSamplesFile(pruned)), 'utf8') + Buffer.byteLength(serialize(summary), 'utf8') > MAX_TOTAL_BYTES) {
-        pruned = pruned.slice(1);
-        summary = createSummary(pruned, today);
+    if (serializedHistorySize(samples, today) <= MAX_TOTAL_BYTES) {
+        return samples;
+    }
+    let low = 1;
+    let high = samples.length;
+    let firstFittingIndex = samples.length;
+    while (low <= high) {
+        const middle = Math.floor((low + high) / 2);
+        const candidate = samples.slice(middle);
+        if (serializedHistorySize(candidate, today) <= MAX_TOTAL_BYTES) {
+            firstFittingIndex = middle;
+            high = middle - 1;
+            continue;
+        }
+        low = middle + 1;
     }
-    return pruned;
+    return samples.slice(firstFittingIndex);
 }
 export function recordRunPerformanceHistory(projectRoot, receipt) {
     const sample = createSample(receipt);

package/dist/core/validation-ratchet.js

@@ -146,7 +146,7 @@ export function createValidationRatchetRisks(report, projectRoot) {
             if (SNAPSHOT_PATH.test(classification.path) && diff.added.length + diff.removed.length >= 20) {
                 addRisk('snapshot_mass_updated', 'medium', classification.path, riskDetail(classification.path, 'changes a large snapshot region; review that the update does not hide a regression.'));
             }
-            if (GOLDEN_PATH.test(`${classification.path} `) && diff.added.length + diff.removed.length >= 20) {
+            if (GOLDEN_PATH.test(classification.path) && diff.added.length + diff.removed.length >= 20) {
                 addRisk('golden_output_replaced', 'medium', classification.path, riskDetail(classification.path, 'replaces a broad golden or expected-output region; review the behavioral reason.'));
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.22.15",
+  "version": "2.22.16",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/explain-report.schema.json

@@ -360,9 +360,62 @@
         },
         "effectGraph": {
           "$ref": "#/$defs/commandEffectGraph"
+        },
+        "blockedRunPlan": {
+          "$ref": "#/$defs/blockedRunPlan"
         }
       }
     },
+    "blockedRunPlan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "runnable",
+        "reasonCode",
+        "detail",
+        "status",
+        "lifecycle",
+        "runPolicy",
+        "configuredCwd",
+        "timeoutSeconds",
+        "mode",
+        "writes",
+        "suggestedIntentSnippet"
+      ],
+      "properties": {
+        "runnable": { "type": "boolean" },
+        "reasonCode": {
+          "type": ["string", "null"],
+          "enum": [
+            "intent_not_table",
+            "status_not_configured",
+            "lifecycle_not_oneshot",
+            "run_policy_not_agent_allowed",
+            "stdin_not_closed",
+            "missing_timeout",
+            "missing_command_source",
+            "unsafe_intent_name",
+            "blocked_shell_background_pattern",
+            "blocked_long_running_command_pattern",
+            "cwd_outside_project",
+            "max_output_bytes_exceeds_limit",
+            null
+          ]
+        },
+        "detail": { "type": ["string", "null"] },
+        "status": { "type": ["string", "null"] },
+        "lifecycle": { "type": ["string", "null"] },
+        "runPolicy": { "type": ["string", "null"] },
+        "configuredCwd": { "type": ["string", "null"] },
+        "timeoutSeconds": { "type": ["integer", "null"] },
+        "mode": { "type": ["string", "null"] },
+        "writes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "suggestedIntentSnippet": { "type": ["string", "null"] }
+      }
+    },
     "commandEffectGraph": {
       "type": "object",
       "additionalProperties": false,

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.22.15"
+version = "2.22.16"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"