mustflow 2.22.47 → 2.23.0

package/README.md

@@ -253,8 +253,9 @@ mf run mustflow_update_apply
 | `mf api command-catalog --json` | Print command intent availability and safe `mf run` entrypoints without exposing raw command strings. |
 | `mf api verification-plan --changed --json` | Print a stable, read-only verification plan for changed files without executing commands. |
 | `mf api latest-evidence --json` | Print bounded latest run or verify evidence without raw command output. |
-| `mf api diff-risk --changed --json` | Print a compact changed-file risk and verification summary. |
+| `mf api diff-risk --changed --json` | Print a compact changed-file risk, verification summary, and read-only residual correction signals. |
 | `mf api health --json` | Print a compact workspace health report for quick agent gating. |
+| `mf api locks --json` | Print active `mf run` locks for multi-session coordination. |
 | `mf docs review list` | Show documents still waiting for prose review after agent edits. |
 | `mf docs review add <path>` | Add or refresh a document review queue entry. |
 | `mf docs review comment <path>` | Add multiline review guidance to an existing queue entry. |
@@ -264,6 +265,7 @@ mf run mustflow_update_apply
 | `mf map --stdout` | Print the current mustflow root map to stdout. |
 | `mf map --write` | Create or update `REPO_MAP.md`. |
 | `mf run <intent>` | Run an allowed one-shot command. |
+| `mf run <intent> --wait` | Wait for conflicting active run locks before executing the command. |
 | `mf run <intent> --dry-run --json` | Preview whether an intent is runnable and what command metadata would be used, without executing it. |
 | `mf index` | Build a SQLite index for mustflow docs, skill routes, command rules, command-effect locks, and file fingerprints. Use `--incremental` to reuse a compatible fresh index without rewriting it. |
 | `mf search <query>` | Search docs, skills, skill routes, command rules, and command-effect locks in the SQLite index. |

package/dist/cli/commands/api.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { createClassifyOutput } from './classify.js';
+import { listActiveRunLocks } from '../../core/active-run-locks.js';
 import { createChangeVerificationReport, } from '../../core/change-verification.js';
 import { readUtf8FileInsideWithoutSymlinks } from '../../core/safe-filesystem.js';
 import { createVerificationPlanId } from '../../core/verification-plan-id.js';
@@ -18,8 +19,10 @@ const API_VERIFICATION_PLAN_SCHEMA_VERSION = '1';
 const API_LATEST_EVIDENCE_SCHEMA_VERSION = '1';
 const API_DIFF_RISK_SCHEMA_VERSION = '1';
 const API_HEALTH_SCHEMA_VERSION = '1';
+const API_LOCKS_SCHEMA_VERSION = '1';
 const COMMANDS_RELATIVE_PATH = '.mustflow/config/commands.toml';
 const LATEST_RUN_RELATIVE_PATH = '.mustflow/state/runs/latest.json';
+const LOCKS_RELATIVE_PATH = '.mustflow/state/locks';
 const MUSTFLOW_JSON_MAX_BYTES = 1024 * 1024;
 export function getApiHelp(lang = 'en') {
     return renderHelp({
@@ -50,6 +53,10 @@ export function getApiHelp(lang = 'en') {
                 label: 'health',
                 description: t(lang, 'api.help.action.health'),
             },
+            {
+                label: 'locks',
+                description: t(lang, 'api.help.action.locks'),
+            },
         ],
         options: [
             { label: '--changed', description: t(lang, 'classify.help.option.changed') },
@@ -63,6 +70,7 @@ export function getApiHelp(lang = 'en') {
             'mf api latest-evidence --json',
             'mf api diff-risk --changed --json',
             'mf api health --json',
+            'mf api locks --json',
         ],
         exitCodes: [
             { label: '0', description: t(lang, 'api.help.exit.ok') },
@@ -658,6 +666,150 @@ function getRiskLevel(classification, report) {
     }
     return 'low';
 }
+function uniqueSortedStrings(values) {
+    return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))]
+        .sort((left, right) => left.localeCompare(right));
+}
+function readEvidenceRequirements(parsed) {
+    if (!isRecord(parsed) || !isRecord(parsed.evidence_model) || !Array.isArray(parsed.evidence_model.requirements)) {
+        return [];
+    }
+    return parsed.evidence_model.requirements.filter(isRecord);
+}
+function readEvidenceRemainingRisks(parsed) {
+    if (!isRecord(parsed) || !isRecord(parsed.evidence_model) || !Array.isArray(parsed.evidence_model.remaining_risks)) {
+        return [];
+    }
+    return parsed.evidence_model.remaining_risks.filter(isRecord);
+}
+function readEvidenceReceipts(parsed) {
+    if (!isRecord(parsed) || !isRecord(parsed.evidence_model) || !Array.isArray(parsed.evidence_model.receipts)) {
+        return [];
+    }
+    return parsed.evidence_model.receipts.filter(isRecord);
+}
+function affectedReasonsFromLatest(parsed) {
+    return uniqueSortedStrings(readEvidenceRequirements(parsed).map((requirement) => readString(requirement, 'reason')));
+}
+function affectedIntentsFromLatest(parsed) {
+    const requirementIntents = readEvidenceRequirements(parsed).flatMap((requirement) => [
+        ...(Array.isArray(requirement.selected_intents) ? requirement.selected_intents : []),
+        ...(Array.isArray(requirement.skipped_intents) ? requirement.skipped_intents : []),
+    ]);
+    const receiptIntents = readEvidenceReceipts(parsed).map((receipt) => readString(receipt, 'intent'));
+    return uniqueSortedStrings([...requirementIntents, ...receiptIntents]);
+}
+function repeatedFailureConfidence(seenCount, requiresNewEvidence) {
+    if (requiresNewEvidence || seenCount >= 3) {
+        return 'high';
+    }
+    return seenCount >= 2 ? 'medium' : 'low';
+}
+function createResidualPolicy() {
+    return {
+        single_observation_changes_plan: false,
+        minimum_repeated_samples_for_plan_change: 2,
+        automatic_intent_additions_enabled: false,
+    };
+}
+function createEmptyResidualCorrections(status, issues = []) {
+    return {
+        status,
+        mode: 'read_only',
+        grants_command_authority: false,
+        applies_to_current_plan: false,
+        selected_intent_additions: [],
+        suggested_intent_additions: [],
+        recommended_commands: [],
+        signals: [],
+        policy: createResidualPolicy(),
+        issues,
+    };
+}
+function createResidualCorrections(projectRoot, verificationPlanId) {
+    if (!verificationPlanId) {
+        return createEmptyResidualCorrections('not_enough_evidence');
+    }
+    let parsed;
+    try {
+        parsed = readJsonInsideRoot(projectRoot, LATEST_RUN_RELATIVE_PATH);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return message.includes('ENOENT') ? createEmptyResidualCorrections('not_enough_evidence') : createEmptyResidualCorrections('unavailable', [message]);
+    }
+    if (!isRecord(parsed) || parsed.command !== 'verify' || parsed.kind !== 'verify_run_summary') {
+        return createEmptyResidualCorrections('not_enough_evidence');
+    }
+    const latestPlanId = readString(parsed, 'verification_plan_id') ?? null;
+    const appliesToCurrentPlan = latestPlanId === verificationPlanId;
+    const affectedReasons = affectedReasonsFromLatest(parsed);
+    const affectedIntents = affectedIntentsFromLatest(parsed);
+    const completionVerdict = isRecord(parsed.completion_verdict) ? parsed.completion_verdict : null;
+    const completionStatus = completionVerdict ? readString(completionVerdict, 'status') : null;
+    const signals = [];
+    if (appliesToCurrentPlan && completionStatus && completionStatus !== 'verified') {
+        signals.push({
+            kind: 'latest_unresolved_plan',
+            confidence: 'low',
+            evidence_count: 1,
+            source: 'latest-evidence',
+            verification_plan_id: latestPlanId,
+            affected_reasons: affectedReasons,
+            affected_intents: affectedIntents,
+            detail: `Latest verify evidence for this plan ended with completion verdict ${completionStatus}; do not treat the base plan as complete without new evidence.`,
+            recommendation: 'provide_new_evidence',
+        });
+    }
+    const repeatedFailure = isRecord(parsed.repeated_failure_summary) ? parsed.repeated_failure_summary : null;
+    if (appliesToCurrentPlan && repeatedFailure) {
+        const seenCount = typeof repeatedFailure.seen_count === 'number' && Number.isFinite(repeatedFailure.seen_count)
+            ? Math.max(1, Math.floor(repeatedFailure.seen_count))
+            : 1;
+        const requiresNewEvidence = repeatedFailure.requires_new_evidence === true;
+        if (seenCount >= 2 || requiresNewEvidence) {
+            signals.push({
+                kind: 'repeated_failure',
+                confidence: repeatedFailureConfidence(seenCount, requiresNewEvidence),
+                evidence_count: seenCount,
+                source: 'latest-evidence',
+                verification_plan_id: latestPlanId,
+                affected_reasons: affectedReasons,
+                affected_intents: affectedIntents,
+                detail: 'Latest evidence reports repeated unresolved verification for this plan; collect new evidence or narrow the hypothesis before claiming completion.',
+                recommendation: 'provide_new_evidence',
+            });
+        }
+    }
+    if (appliesToCurrentPlan) {
+        for (const risk of readEvidenceRemainingRisks(parsed).slice(0, 5)) {
+            const detail = readString(risk, 'detail') ?? readString(risk, 'code') ?? 'Latest verify evidence has a remaining risk.';
+            signals.push({
+                kind: 'remaining_risk',
+                confidence: 'low',
+                evidence_count: 1,
+                source: 'latest-evidence',
+                verification_plan_id: latestPlanId,
+                affected_reasons: affectedReasons,
+                affected_intents: affectedIntents,
+                detail,
+                recommendation: 'review_remaining_risk',
+            });
+        }
+    }
+    return {
+        status: signals.length > 0 ? 'available' : 'not_enough_evidence',
+        mode: 'read_only',
+        grants_command_authority: false,
+        applies_to_current_plan: appliesToCurrentPlan,
+        selected_intent_additions: [],
+        suggested_intent_additions: [],
+        recommended_commands: signals.length > 0 ? ['mf api latest-evidence --json'] : [],
+        signals,
+        policy: createResidualPolicy(),
+        issues: [],
+    };
+}
 function createDiffRiskOutput() {
     const mustflowRoot = resolveMustflowRoot();
     let classification = null;
@@ -680,21 +832,32 @@ function createDiffRiskOutput() {
             update_policies: [],
             drift_checks: [],
             required_verification: [],
+            residual_corrections: createResidualCorrections(mustflowRoot, null),
             gap_count: 0,
             gaps: [],
             recommended_commands: [],
             issues: [message],
         };
     }
-    let report = null;
     const issues = [];
+    let contract = null;
     try {
-        report = createChangeVerificationReport(classification, readCommandContract(mustflowRoot), mustflowRoot);
+        contract = readCommandContract(mustflowRoot);
     }
     catch (error) {
         issues.push(error instanceof Error ? error.message : String(error));
     }
+    let report = null;
+    if (contract) {
+        try {
+            report = createChangeVerificationReport(classification, contract, mustflowRoot);
+        }
+        catch (error) {
+            issues.push(error instanceof Error ? error.message : String(error));
+        }
+    }
     const requiredVerification = report ? report.schedule.entries.map((entry) => entry.intent) : [];
+    const verificationPlanId = report && contract ? createVerificationPlanId(report, contract) : null;
     return {
         schema_version: API_DIFF_RISK_SCHEMA_VERSION,
         command: 'api diff-risk',
@@ -709,6 +872,7 @@ function createDiffRiskOutput() {
         update_policies: classification.summary.updatePolicies,
         drift_checks: classification.summary.driftChecks,
         required_verification: requiredVerification,
+        residual_corrections: createResidualCorrections(mustflowRoot, verificationPlanId),
         gap_count: report?.gaps.length ?? 0,
         gaps: report?.gaps.map((gap) => ({
             reason: gap.reason,
@@ -757,6 +921,68 @@ function createHealthOutput() {
         recommended_next_commands: workspace.recommended_next_commands,
     };
 }
+function createLocksOutput() {
+    const mustflowRoot = resolveMustflowRoot();
+    try {
+        const state = listActiveRunLocks(mustflowRoot);
+        const activeLocks = state.activeRecords.map((record) => ({
+            run_id: record.run_id,
+            intent: record.intent,
+            pid: record.pid,
+            started_at: record.started_at,
+            command_hash: record.command_hash,
+            effects: record.effects,
+            writes: record.writes,
+        }));
+        const staleLocks = state.staleRecords.map((record) => ({
+            run_id: record.runId,
+            intent: record.intent,
+            pid: record.pid,
+            reason: record.reason,
+        }));
+        const recommendedCommands = activeLocks.length > 0 ? ['mf api locks --json', 'mf run <intent> --wait'] : [];
+        return {
+            schema_version: API_LOCKS_SCHEMA_VERSION,
+            command: 'api locks',
+            mustflow_root: mustflowRoot,
+            status: activeLocks.length > 0 ? 'active' : staleLocks.length > 0 ? 'stale' : 'clear',
+            lock_root: LOCKS_RELATIVE_PATH,
+            active_count: activeLocks.length,
+            stale_count: staleLocks.length,
+            active_locks: activeLocks,
+            stale_locks: staleLocks,
+            policy: {
+                source: 'active-run-locks',
+                conflict_model: 'command_effects_and_writes',
+                direct_commands_bypass_locks: true,
+                wait_entrypoint: 'mf run <intent> --wait',
+            },
+            recommended_commands: recommendedCommands,
+            issues: [],
+        };
+    }
+    catch (error) {
+        return {
+            schema_version: API_LOCKS_SCHEMA_VERSION,
+            command: 'api locks',
+            mustflow_root: mustflowRoot,
+            status: 'unavailable',
+            lock_root: LOCKS_RELATIVE_PATH,
+            active_count: 0,
+            stale_count: 0,
+            active_locks: [],
+            stale_locks: [],
+            policy: {
+                source: 'active-run-locks',
+                conflict_model: 'command_effects_and_writes',
+                direct_commands_bypass_locks: true,
+                wait_entrypoint: 'mf run <intent> --wait',
+            },
+            recommended_commands: [],
+            issues: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
 function validateJsonOnlyAction(action, args, reporter, lang) {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getApiHelp(lang));
@@ -837,6 +1063,13 @@ function runHealth(args, reporter, lang) {
     reporter.stdout(JSON.stringify(createHealthOutput(), null, 2));
     return 0;
 }
+function runLocks(args, reporter, lang) {
+    if (!validateJsonOnlyAction('locks', args, reporter, lang)) {
+        return args.includes('--help') || args.includes('-h') ? 0 : 1;
+    }
+    reporter.stdout(JSON.stringify(createLocksOutput(), null, 2));
+    return 0;
+}
 export function runApi(args, reporter, lang = 'en') {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getApiHelp(lang));
@@ -869,6 +1102,9 @@ export function runApi(args, reporter, lang = 'en') {
     if (action === 'health') {
         return runHealth(rest, reporter, lang);
     }
+    if (action === 'locks') {
+        return runLocks(rest, reporter, lang);
+    }
     printUsageError(reporter, t(lang, 'api.error.unknownAction', { action }), 'mf api --help', getApiHelp(lang), lang);
     return 1;
 }

package/dist/cli/commands/run.js

@@ -18,6 +18,13 @@ import { getRunStatus, runArgvCommandStreaming, runShellCommandStreaming } from
 import { emitOutput, isOutputLimitExceededError } from './run/output.js';
 import { createPendingTimeoutTermination, getKillMethod, terminateProcessTree } from './run/process-tree.js';
 import { assembleRunReceipt } from './run/receipt.js';
+const DEFAULT_ACTIVE_LOCK_WAIT_TIMEOUT_SECONDS = 300;
+const ACTIVE_LOCK_WAIT_POLL_MS = 1_000;
+function delay(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
 function getRunPlanDetail(plan, lang, fallbackKey) {
     return plan.detail ?? t(lang, fallbackKey);
 }
@@ -117,6 +124,77 @@ function renderActiveLockConflictMessage(intentName, conflicts, lang) {
         : t(lang, 'run.error.activeLockConflictUnknown');
     return t(lang, 'run.error.activeLockConflict', { intent: intentName, detail });
 }
+function parseRunArguments(args) {
+    const supportedBooleanOptions = new Set(['--json', '--dry-run', '--plan-only', '--wait', ALLOW_UNTRUSTED_ROOT_OPTION]);
+    const supportedValueOptions = new Set(['--wait-timeout']);
+    const positional = [];
+    const unsupported = [];
+    let waitTimeoutSeconds = DEFAULT_ACTIVE_LOCK_WAIT_TIMEOUT_SECONDS;
+    let invalidWaitTimeout = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (supportedBooleanOptions.has(arg)) {
+            continue;
+        }
+        if (supportedValueOptions.has(arg)) {
+            const value = args[index + 1];
+            if (!value || value.startsWith('-')) {
+                invalidWaitTimeout = true;
+                continue;
+            }
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed <= 0) {
+                invalidWaitTimeout = true;
+            }
+            else {
+                waitTimeoutSeconds = parsed;
+            }
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            unsupported.push(arg);
+            continue;
+        }
+        positional.push(arg);
+    }
+    const [intentName, ...extra] = positional;
+    return {
+        json: args.includes('--json'),
+        dryRun: args.includes('--dry-run'),
+        planOnly: args.includes('--plan-only'),
+        allowUntrustedRoot: args.includes(ALLOW_UNTRUSTED_ROOT_OPTION),
+        wait: args.includes('--wait'),
+        waitTimeoutSeconds,
+        intentName: intentName ?? null,
+        extra,
+        unsupported,
+        invalidWaitTimeout,
+    };
+}
+async function acquireActiveRunLockWithOptionalWait(input) {
+    const startedAt = Date.now();
+    let reportedWait = false;
+    while (true) {
+        const result = acquireActiveRunLock(input.projectRoot, input.contract, input.intentName, { commandHash: input.commandHash });
+        if (result.ok || !input.enabled || result.conflicts.length === 0) {
+            return result;
+        }
+        if (!input.json && !reportedWait) {
+            const [first] = result.conflicts;
+            input.reporter.stderr(t(input.lang, 'run.progress.waitingForActiveLock', {
+                intent: input.intentName,
+                activeIntent: first?.conflictsWithIntent ?? 'unknown',
+                seconds: input.waitTimeoutSeconds,
+            }));
+            reportedWait = true;
+        }
+        if (Date.now() - startedAt >= input.waitTimeoutSeconds * 1000) {
+            return result;
+        }
+        await delay(Math.min(ACTIVE_LOCK_WAIT_POLL_MS, Math.max(1, input.waitTimeoutSeconds * 1000 - (Date.now() - startedAt))));
+    }
+}
 function createRunProgressReporter(input) {
     if (!input.enabled) {
         return () => undefined;
@@ -150,6 +228,8 @@ export function getRunHelp(lang = 'en') {
             { label: '--dry-run', description: t(lang, 'run.help.option.dryRun') },
             { label: '--plan-only', description: t(lang, 'run.help.option.planOnly') },
             { label: '--json', description: t(lang, 'run.help.option.json') },
+            { label: '--wait', description: t(lang, 'run.help.option.wait') },
+            { label: '--wait-timeout <seconds>', description: t(lang, 'run.help.option.waitTimeout') },
             { label: ALLOW_UNTRUSTED_ROOT_OPTION, description: t(lang, 'run.help.option.allowUntrustedRoot') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
@@ -180,23 +260,31 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         reporter.stdout(getRunHelp(lang));
         return 0;
     }
-    const supportedOptions = new Set(['--json', '--dry-run', '--plan-only', ALLOW_UNTRUSTED_ROOT_OPTION]);
-    const unsupported = args.filter((arg) => arg.startsWith('-') && !supportedOptions.has(arg));
+    const parsedArgs = parseRunArguments(args);
+    const unsupported = parsedArgs.unsupported;
     if (unsupported.length > 0) {
         printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf run --help', getRunHelp(lang), lang);
         return 1;
     }
-    const json = args.includes('--json');
-    const dryRun = args.includes('--dry-run');
-    const planOnly = args.includes('--plan-only');
-    const allowUntrustedRoot = args.includes(ALLOW_UNTRUSTED_ROOT_OPTION);
+    if (parsedArgs.invalidWaitTimeout) {
+        printUsageError(reporter, t(lang, 'run.error.invalidWaitTimeout'), 'mf run --help', getRunHelp(lang), lang);
+        return 1;
+    }
+    const json = parsedArgs.json;
+    const dryRun = parsedArgs.dryRun;
+    const planOnly = parsedArgs.planOnly;
+    const allowUntrustedRoot = parsedArgs.allowUntrustedRoot;
     const previewMode = dryRun ? 'dry-run' : planOnly ? 'plan-only' : null;
     if (dryRun && planOnly) {
         printUsageError(reporter, t(lang, 'run.error.conflictingPreviewModes'), 'mf run --help', getRunHelp(lang), lang);
         return 1;
     }
-    const positional = args.filter((arg) => !supportedOptions.has(arg));
-    const [intentName, ...extra] = positional;
+    if (parsedArgs.wait && previewMode) {
+        printUsageError(reporter, t(lang, 'run.error.waitRequiresExecution'), 'mf run --help', getRunHelp(lang), lang);
+        return 1;
+    }
+    const intentName = parsedArgs.intentName;
+    const extra = parsedArgs.extra;
     if (!intentName) {
         printUsageError(reporter, t(lang, 'run.error.missingIntent'), 'mf run --help', getRunHelp(lang), lang);
         return 1;
@@ -243,7 +331,17 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         });
         return 1;
     }
-    const activeRunLock = profiler.measure('active_lock_acquire', () => acquireActiveRunLock(projectRoot, contract, intentName, { commandHash: createPlanCommandHash(plan) }));
+    const activeRunLock = await profiler.measureAsync('active_lock_acquire', () => acquireActiveRunLockWithOptionalWait({
+        enabled: parsedArgs.wait,
+        waitTimeoutSeconds: parsedArgs.waitTimeoutSeconds,
+        projectRoot,
+        contract,
+        intentName,
+        commandHash: createPlanCommandHash(plan),
+        json,
+        reporter,
+        lang,
+    }));
     if (!activeRunLock.ok) {
         reporter.stderr(renderCliError(renderActiveLockConflictMessage(intentName, activeRunLock.conflicts, lang), 'mf run --dry-run --json', lang));
         writeLatestProfile(profiler, options, {

package/dist/cli/i18n/en.js

@@ -94,8 +94,9 @@ export const enMessages = {
     "api.help.action.latestEvidence": "Print bounded latest run or verify evidence for agents",
     "api.help.action.diffRisk": "Print a compact changed-file risk and verification summary",
     "api.help.action.health": "Print a compact workspace health summary",
+    "api.help.action.locks": "Print active mf run locks for multi-session coordination",
     "api.help.exit.ok": "The API report was inspected and printed",
-    "api.error.missingAction": "Specify an api action: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, or health",
+    "api.error.missingAction": "Specify an api action: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health, or locks",
     "api.error.unknownAction": "Unknown api action: {action}",
     "api.error.actionRequiresJson": "{action} requires --json",
     "api.error.actionRequiresChanged": "{action} currently requires --changed",
@@ -674,12 +675,15 @@ Read these files before working:
     "run.help.option.dryRun": "Print a non-executing command plan",
     "run.help.option.planOnly": "Alias for --dry-run",
     "run.help.option.json": "Print the run record or command plan as JSON",
+    "run.help.option.wait": "Wait for conflicting active run locks before executing",
+    "run.help.option.waitTimeout": "Maximum seconds to wait for active run locks. Default: 300",
     "run.help.option.allowUntrustedRoot": "Allow one execution from a root with a missing or invalid manifest lock after manual review",
     "run.help.exit.ok": "The command completed with an allowed exit code",
     "run.help.exit.fail": "The command was invalid, refused, timed out, or failed",
     "run.label.suggestedIntentSnippet": "Suggested command contract snippet",
     "run.progress.started": "Running {intent} (timeout: {seconds}s)...",
     "run.progress.timeoutWarning": "Still running {intent}... ({seconds}s elapsed, {percent}% of timeout)",
+    "run.progress.waitingForActiveLock": "Waiting to run {intent}; active intent {activeIntent} holds a conflicting lock (timeout: {seconds}s)",
     "run.error.missingIntent": "Missing command name",
     "run.error.unknownIntent": "Unknown command: {intent}",
     "run.error.statusNotConfigured": 'Command "{intent}" is {status}; only configured commands can be run',
@@ -702,6 +706,8 @@ Read these files before working:
     "run.error.maxOutputBytes": 'Command "{intent}" has invalid max_output_bytes. {detail}',
     "run.error.maxOutputBytesDetail": "The output limit must stay within the allowed maximum.",
     "run.error.conflictingPreviewModes": "Use either --dry-run or --plan-only, not both",
+    "run.error.invalidWaitTimeout": "--wait-timeout must be a positive integer",
+    "run.error.waitRequiresExecution": "--wait can only be used when executing a command, not with --dry-run or --plan-only",
     "run.error.untrustedRootMissing": "Refused to execute commands because {path} is missing. Run mf init/update to install the workflow, or pass --allow-untrusted-root after reviewing AGENTS.md and .mustflow/config/commands.toml.",
     "run.error.untrustedRootInvalid": "Refused to execute commands because the manifest lock is invalid: {detail}. Restore or regenerate it, or pass --allow-untrusted-root after reviewing AGENTS.md and .mustflow/config/commands.toml.",
     "run.error.timedOut": 'Command "{intent}" timed out after {seconds} seconds',

package/dist/cli/i18n/es.js

@@ -94,8 +94,9 @@ export const esMessages = {
     "api.help.action.latestEvidence": "Imprime evidencia bounded del último run o verify para agentes",
     "api.help.action.diffRisk": "Imprime un resumen compacto de riesgo y verificación para archivos cambiados",
     "api.help.action.health": "Imprime un resumen compacto de salud del workspace",
+    "api.help.action.locks": "Imprime bloqueos mf run activos para coordinar varias sesiones",
     "api.help.exit.ok": "El informe API se inspeccionó e imprimió",
-    "api.error.missingAction": "Especifica una acción api: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk o health",
+    "api.error.missingAction": "Especifica una acción api: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health o locks",
     "api.error.unknownAction": "Acción api desconocida: {action}",
     "api.error.actionRequiresJson": "{action} requiere --json",
     "api.error.actionRequiresChanged": "{action} actualmente requiere --changed",
@@ -674,12 +675,15 @@ Lee estos archivos antes de trabajar:
     "run.help.option.dryRun": "Imprime un plan de comando sin ejecutarlo",
     "run.help.option.planOnly": "Alias de --dry-run",
     "run.help.option.json": "Imprime el registro de ejecución o el plan de comando como JSON",
+    "run.help.option.wait": "Espera bloqueos activos en conflicto antes de ejecutar",
+    "run.help.option.waitTimeout": "Segundos máximos para esperar bloqueos activos. Predeterminado: 300",
     "run.help.option.allowUntrustedRoot": "Permite una ejecución desde una raíz con bloqueo de manifiesto ausente o inválido tras revisión manual",
     "run.help.exit.ok": "El comando se completo con un codigo de salida permitido",
     "run.help.exit.fail": "El comando no era válido, fue rechazado, agotó el tiempo o falló",
     "run.label.suggestedIntentSnippet": "Snippet sugerido para el contrato de comandos",
     "run.progress.started": "Ejecutando {intent} (timeout: {seconds}s)...",
     "run.progress.timeoutWarning": "{intent} sigue ejecutándose... ({seconds}s transcurridos, {percent}% del timeout)",
+    "run.progress.waitingForActiveLock": "Esperando para ejecutar {intent}; el intent activo {activeIntent} mantiene un bloqueo en conflicto (timeout: {seconds}s)",
     "run.error.missingIntent": "Falta el nombre del comando",
     "run.error.unknownIntent": "Comando desconocido: {intent}",
     "run.error.statusNotConfigured": 'El comando "{intent}" está en estado {status}; sólo se pueden ejecutar comandos configurados',
@@ -702,6 +706,8 @@ Lee estos archivos antes de trabajar:
     "run.error.maxOutputBytes": 'El comando "{intent}" tiene max_output_bytes no válido. {detail}',
     "run.error.maxOutputBytesDetail": "El límite de salida debe permanecer dentro del máximo permitido.",
     "run.error.conflictingPreviewModes": "Usa --dry-run o --plan-only, no ambos",
+    "run.error.invalidWaitTimeout": "--wait-timeout debe ser un entero positivo",
+    "run.error.waitRequiresExecution": "--wait solo se puede usar al ejecutar un comando, no con --dry-run o --plan-only",
     "run.error.untrustedRootMissing": "Se rechazó ejecutar comandos porque falta {path}. Ejecuta mf init/update para instalar el flujo, o usa --allow-untrusted-root tras revisar AGENTS.md y .mustflow/config/commands.toml.",
     "run.error.untrustedRootInvalid": "Se rechazó ejecutar comandos porque el bloqueo de manifiesto no es válido: {detail}. Restáuralo o regenéralo, o usa --allow-untrusted-root tras revisar AGENTS.md y .mustflow/config/commands.toml.",
     "run.error.timedOut": 'El comando "{intent}" agotó el tiempo después de {seconds} segundos',

package/dist/cli/i18n/fr.js

@@ -94,8 +94,9 @@ export const frMessages = {
     "api.help.action.latestEvidence": "Affiche les dernières preuves bounded de run ou verify pour les agents",
     "api.help.action.diffRisk": "Affiche un résumé compact du risque et de la vérification des fichiers modifiés",
     "api.help.action.health": "Affiche un résumé compact de santé du workspace",
+    "api.help.action.locks": "Affiche les verrous mf run actifs pour coordonner plusieurs sessions",
     "api.help.exit.ok": "Le rapport API a été inspecté et imprimé",
-    "api.error.missingAction": "Indiquez une action api : workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk ou health",
+    "api.error.missingAction": "Indiquez une action api : workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health ou locks",
     "api.error.unknownAction": "Action api inconnue : {action}",
     "api.error.actionRequiresJson": "{action} exige --json",
     "api.error.actionRequiresChanged": "{action} exige actuellement --changed",
@@ -674,12 +675,15 @@ Lisez ces fichiers avant de travailler :
     "run.help.option.dryRun": "Imprime un plan de commande sans l'exécuter",
     "run.help.option.planOnly": "Alias de --dry-run",
     "run.help.option.json": "Imprime l'enregistrement d'exécution ou le plan de commande en JSON",
+    "run.help.option.wait": "Attend les verrous actifs en conflit avant d'exécuter",
+    "run.help.option.waitTimeout": "Nombre maximal de secondes d'attente des verrous actifs. Par défaut : 300",
     "run.help.option.allowUntrustedRoot": "Autorise une seule exécution depuis une racine sans verrou de manifeste valide après revue manuelle",
     "run.help.exit.ok": "La commande s'est terminée avec un code de sortie autorisé",
     "run.help.exit.fail": "La commande était non valide, refusée, expirée ou a échoué",
     "run.label.suggestedIntentSnippet": "Extrait suggéré de contrat de commande",
     "run.progress.started": "Exécution de {intent} (timeout : {seconds}s)...",
     "run.progress.timeoutWarning": "{intent} est toujours en cours... ({seconds}s écoulées, {percent}% du timeout)",
+    "run.progress.waitingForActiveLock": "Attente avant d'exécuter {intent} ; l'intention active {activeIntent} détient un verrou en conflit (timeout : {seconds}s)",
     "run.error.missingIntent": "Nom de commande manquant",
     "run.error.unknownIntent": "Commande inconnue : {intent}",
     "run.error.statusNotConfigured": 'La commande "{intent}" est {status} ; seules les commandes configurées peuvent être exécutées',
@@ -702,6 +706,8 @@ Lisez ces fichiers avant de travailler :
     "run.error.maxOutputBytes": 'La commande "{intent}" a une valeur max_output_bytes non valide. {detail}',
     "run.error.maxOutputBytesDetail": "La limite de sortie doit rester dans le maximum autorisé.",
     "run.error.conflictingPreviewModes": "Utilisez --dry-run ou --plan-only, pas les deux",
+    "run.error.invalidWaitTimeout": "--wait-timeout doit être un entier positif",
+    "run.error.waitRequiresExecution": "--wait ne peut être utilisé que lors de l'exécution d'une commande, pas avec --dry-run ou --plan-only",
     "run.error.untrustedRootMissing": "Exécution refusée car {path} est absent. Lancez mf init/update pour installer le workflow, ou ajoutez --allow-untrusted-root après avoir relu AGENTS.md et .mustflow/config/commands.toml.",
     "run.error.untrustedRootInvalid": "Exécution refusée car le verrou de manifeste est invalide : {detail}. Restaurez-le ou régénérez-le, ou ajoutez --allow-untrusted-root après avoir relu AGENTS.md et .mustflow/config/commands.toml.",
     "run.error.timedOut": 'La commande "{intent}" a expiré après {seconds} secondes',

package/dist/cli/i18n/hi.js

@@ -94,8 +94,9 @@ export const hiMessages = {
     "api.help.action.latestEvidence": "agents के लिए bounded latest run या verify evidence प्रिंट करें",
     "api.help.action.diffRisk": "बदली गई files के लिए compact risk और verification summary प्रिंट करें",
     "api.help.action.health": "workspace health की compact summary प्रिंट करें",
+    "api.help.action.locks": "multi-session coordination के लिए active mf run locks प्रिंट करें",
     "api.help.exit.ok": "API रिपोर्ट जाँची और प्रिंट की गई",
-    "api.error.missingAction": "api action बताएँ: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, या health",
+    "api.error.missingAction": "api action बताएँ: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health, या locks",
     "api.error.unknownAction": "अज्ञात api action: {action}",
     "api.error.actionRequiresJson": "{action} के लिए --json चाहिए",
     "api.error.actionRequiresChanged": "{action} को अभी --changed चाहिए",
@@ -674,12 +675,15 @@ export const hiMessages = {
     "run.help.option.dryRun": "कमांड चलाए बिना उसका plan प्रिंट करें",
     "run.help.option.planOnly": "--dry-run का alias",
     "run.help.option.json": "Run record या command plan को JSON के रूप में प्रिंट करें",
+    "run.help.option.wait": "चलाने से पहले conflicting active run locks के लिए wait करें",
+    "run.help.option.waitTimeout": "active run locks के लिए wait करने की maximum seconds. Default: 300",
     "run.help.option.allowUntrustedRoot": "Manual review के बाद missing या invalid manifest lock वाली root से एक execution allow करें",
     "run.help.exit.ok": "कमांड अनुमत exit code के साथ पूरी हुई",
     "run.help.exit.fail": "कमांड अमान्य थी, अस्वीकार हुई, timed out हुई या विफल हुई",
     "run.label.suggestedIntentSnippet": "Suggested command contract snippet",
     "run.progress.started": "{intent} चल रहा है (timeout: {seconds}s)...",
     "run.progress.timeoutWarning": "{intent} अभी भी चल रहा है... ({seconds}s बीते, timeout का {percent}%)",
+    "run.progress.waitingForActiveLock": "{intent} चलाने के लिए wait कर रहे हैं; active intent {activeIntent} conflicting lock रखता है (timeout: {seconds}s)",
     "run.error.missingIntent": "कमांड नाम नहीं दिया गया",
     "run.error.unknownIntent": "अज्ञात कमांड: {intent}",
     "run.error.statusNotConfigured": 'कमांड "{intent}" {status} है; केवल configured कमांड चलाई जा सकती हैं',
@@ -702,6 +706,8 @@ export const hiMessages = {
     "run.error.maxOutputBytes": 'कमांड "{intent}" में max_output_bytes अमान्य है। {detail}',
     "run.error.maxOutputBytesDetail": "Output limit अनुमत maximum के अंदर रहनी चाहिए।",
     "run.error.conflictingPreviewModes": "--dry-run या --plan-only में से एक इस्तेमाल करें, दोनों नहीं",
+    "run.error.invalidWaitTimeout": "--wait-timeout positive integer होना चाहिए",
+    "run.error.waitRequiresExecution": "--wait केवल command execute करते समय इस्तेमाल हो सकता है, --dry-run या --plan-only के साथ नहीं",
     "run.error.untrustedRootMissing": "{path} missing है, इसलिए commands execute करने से मना किया गया। Workflow install करने के लिए mf init/update चलाएँ, या AGENTS.md और .mustflow/config/commands.toml review करने के बाद --allow-untrusted-root पास करें।",
     "run.error.untrustedRootInvalid": "Manifest lock invalid है, इसलिए commands execute करने से मना किया गया: {detail}. इसे restore या regenerate करें, या AGENTS.md और .mustflow/config/commands.toml review करने के बाद --allow-untrusted-root पास करें।",
     "run.error.timedOut": 'कमांड "{intent}" {seconds} सेकंड बाद time out हुई',

package/dist/cli/i18n/ko.js

@@ -94,8 +94,9 @@ export const koMessages = {
     "api.help.action.latestEvidence": "에이전트용 bounded 최신 run 또는 verify evidence를 출력합니다",
     "api.help.action.diffRisk": "변경 파일 risk와 verification 요약을 작게 출력합니다",
     "api.help.action.health": "workspace health 요약을 작게 출력합니다",
+    "api.help.action.locks": "여러 세션 조율용 활성 mf run 잠금을 출력합니다",
     "api.help.exit.ok": "API 보고서를 확인하고 출력했습니다",
-    "api.error.missingAction": "api 작업을 지정하세요: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk 또는 health",
+    "api.error.missingAction": "api 작업을 지정하세요: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health 또는 locks",
     "api.error.unknownAction": "알 수 없는 api 작업: {action}",
     "api.error.actionRequiresJson": "{action}에는 --json이 필요합니다",
     "api.error.actionRequiresChanged": "{action}은 현재 --changed가 필요합니다",
@@ -674,12 +675,15 @@ export const koMessages = {
     "run.help.option.dryRun": "실행하지 않고 명령 계획을 출력합니다",
     "run.help.option.planOnly": "--dry-run과 같은 동작입니다",
     "run.help.option.json": "실행 결과 또는 명령 계획을 JSON으로 출력합니다",
+    "run.help.option.wait": "충돌하는 활성 실행 잠금이 풀릴 때까지 기다린 뒤 실행합니다",
+    "run.help.option.waitTimeout": "활성 실행 잠금을 기다릴 최대 초입니다. 기본값: 300",
     "run.help.option.allowUntrustedRoot": "잠금 파일이 없거나 올바르지 않은 루트에서 수동 검토 후 이번 실행만 허용합니다",
     "run.help.exit.ok": "명령이 허용된 종료 코드로 완료되었습니다",
     "run.help.exit.fail": "명령이 잘못되었거나, 거부되었거나, 시간 초과되었거나, 실패했습니다",
     "run.label.suggestedIntentSnippet": "제안 명령 계약 조각",
     "run.progress.started": "{intent} 실행 중(timeout: {seconds}초)...",
     "run.progress.timeoutWarning": "{intent} 계속 실행 중... ({seconds}초 경과, timeout의 {percent}%)",
+    "run.progress.waitingForActiveLock": "{intent} 실행 대기 중; 활성 intent {activeIntent}가 충돌하는 잠금을 보유 중입니다(timeout: {seconds}초)",
     "run.error.missingIntent": "명령 이름이 없습니다",
     "run.error.unknownIntent": "알 수 없는 명령: {intent}",
     "run.error.statusNotConfigured": '명령 "{intent}"의 상태는 {status}입니다. 설정된 상태(configured)인 명령만 실행할 수 있습니다',
@@ -702,6 +706,8 @@ export const koMessages = {
     "run.error.maxOutputBytes": '명령 "{intent}"의 max_output_bytes 값이 올바르지 않습니다. {detail}',
     "run.error.maxOutputBytesDetail": "출력 상한은 허용된 최댓값 안에 있어야 합니다.",
     "run.error.conflictingPreviewModes": "--dry-run과 --plan-only 중 하나만 사용하세요",
+    "run.error.invalidWaitTimeout": "--wait-timeout은 양의 정수여야 합니다",
+    "run.error.waitRequiresExecution": "--wait는 --dry-run 또는 --plan-only가 아닌 실제 명령 실행에만 사용할 수 있습니다",
     "run.error.untrustedRootMissing": "{path}이 없어 명령 실행을 거부했습니다. mf init/update로 워크플로우를 설치하거나, AGENTS.md와 .mustflow/config/commands.toml을 검토한 뒤 --allow-untrusted-root를 붙이세요.",
     "run.error.untrustedRootInvalid": "잠금 파일이 올바르지 않아 명령 실행을 거부했습니다: {detail}. 파일을 복구하거나 다시 생성하거나, AGENTS.md와 .mustflow/config/commands.toml을 검토한 뒤 --allow-untrusted-root를 붙이세요.",
     "run.error.timedOut": '명령 "{intent}"가 {seconds}초 뒤 시간 초과되었습니다',

package/dist/cli/i18n/zh.js

@@ -94,8 +94,9 @@ export const zhMessages = {
     "api.help.action.latestEvidence": "为代理输出 bounded 最新 run 或 verify evidence",
     "api.help.action.diffRisk": "为已变更文件输出紧凑 risk 和 verification 摘要",
     "api.help.action.health": "输出紧凑 workspace health 摘要",
+    "api.help.action.locks": "输出用于多会话协调的活动 mf run 锁",
     "api.help.exit.ok": "已检查并输出 API 报告",
-    "api.error.missingAction": "请指定 api 操作：workspace-summary、command-catalog、verification-plan、latest-evidence、diff-risk 或 health",
+    "api.error.missingAction": "请指定 api 操作：workspace-summary、command-catalog、verification-plan、latest-evidence、diff-risk、health 或 locks",
     "api.error.unknownAction": "未知 api 操作：{action}",
     "api.error.actionRequiresJson": "{action} 需要 --json",
     "api.error.actionRequiresChanged": "{action} 当前需要 --changed",
@@ -674,12 +675,15 @@ export const zhMessages = {
     "run.help.option.dryRun": "输出命令计划但不执行",
     "run.help.option.planOnly": "--dry-run 的别名",
     "run.help.option.json": "将运行记录或命令计划输出为 JSON",
+    "run.help.option.wait": "执行前等待冲突的活动运行锁释放",
+    "run.help.option.waitTimeout": "等待活动运行锁的最大秒数。默认值：300",
     "run.help.option.allowUntrustedRoot": "人工复核后，允许从缺失或无效清单锁的根目录执行一次命令",
     "run.help.exit.ok": "命令已以允许的退出码完成",
     "run.help.exit.fail": "命令无效、被拒绝、超时或失败",
     "run.label.suggestedIntentSnippet": "建议的命令契约片段",
     "run.progress.started": "正在运行 {intent}（超时：{seconds} 秒）...",
     "run.progress.timeoutWarning": "{intent} 仍在运行...（已用 {seconds} 秒，达到超时的 {percent}%）",
+    "run.progress.waitingForActiveLock": "正在等待运行 {intent}；活动 intent {activeIntent} 持有冲突锁（超时：{seconds} 秒）",
     "run.error.missingIntent": "缺少命令名称",
     "run.error.unknownIntent": "未知命令：{intent}",
     "run.error.statusNotConfigured": '命令 "{intent}" 的状态为 {status}；只能运行已配置的命令',
@@ -702,6 +706,8 @@ export const zhMessages = {
     "run.error.maxOutputBytes": '命令 "{intent}" 的 max_output_bytes 无效。{detail}',
     "run.error.maxOutputBytesDetail": "输出限制必须保持在允许的最大值内。",
     "run.error.conflictingPreviewModes": "只能使用 --dry-run 或 --plan-only，不能同时使用",
+    "run.error.invalidWaitTimeout": "--wait-timeout 必须是正整数",
+    "run.error.waitRequiresExecution": "--wait 只能用于实际执行命令，不能与 --dry-run 或 --plan-only 一起使用",
     "run.error.untrustedRootMissing": "已拒绝执行命令，因为缺少 {path}。请运行 mf init/update 安装工作流，或在检查 AGENTS.md 和 .mustflow/config/commands.toml 后传入 --allow-untrusted-root。",
     "run.error.untrustedRootInvalid": "已拒绝执行命令，因为清单锁无效：{detail}。请恢复或重新生成它，或在检查 AGENTS.md 和 .mustflow/config/commands.toml 后传入 --allow-untrusted-root。",
     "run.error.timedOut": '命令 "{intent}" 在 {seconds} 秒后超时',

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

@@ -268,6 +268,16 @@ export function inspectActiveRunLocks(projectRoot, contract, intentName) {
         staleRecords,
     };
 }
+export function listActiveRunLocks(projectRoot) {
+    const records = readActiveRecords(projectRoot);
+    const staleRecords = records.map(staleRecordFor).filter((record) => record !== null);
+    const activeRecords = records.filter((record) => !staleRecords.some((stale) => stale.runId === record.run_id));
+    return {
+        records,
+        activeRecords,
+        staleRecords,
+    };
+}
 export function acquireActiveRunLock(projectRoot, contract, intentName, options = {}) {
     const effects = normalizeCommandEffects(projectRoot, contract, intentName);
     if (effects.length === 0) {

package/dist/core/public-json-contracts.js

@@ -71,6 +71,14 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         documented: true,
         installedCommand: ['mf', 'api', 'health', '--json'],
     },
+    {
+        id: 'locks',
+        schemaFile: 'locks.schema.json',
+        producer: 'mf api locks --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'locks', '--json'],
+    },
     {
         id: 'run-receipt',
         schemaFile: 'run-receipt.schema.json',

package/package.json

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

package/schemas/README.md

@@ -14,6 +14,7 @@ Current schemas:
 - `latest-evidence.schema.json`: output of `mf api latest-evidence --json`
 - `diff-risk.schema.json`: output of `mf api diff-risk --changed --json`
 - `health.schema.json`: output of `mf api health --json`
+- `locks.schema.json`: output of `mf api locks --json`
 - `run-receipt.schema.json`: output of `mf run <intent> --json` and `.mustflow/state/runs/latest.json`,
   including bounded declared-write drift metadata, a safe latest-run performance summary, and optional
   structured phase timings and selection summaries

package/schemas/diff-risk.schema.json

@@ -37,6 +37,7 @@
     "update_policies": { "$ref": "#/$defs/stringArray" },
     "drift_checks": { "$ref": "#/$defs/stringArray" },
     "required_verification": { "$ref": "#/$defs/stringArray" },
+    "residual_corrections": { "$ref": "#/$defs/residualCorrections" },
     "gap_count": { "type": "integer", "minimum": 0 },
     "gaps": {
       "type": "array",
@@ -69,6 +70,80 @@
         "surfaces": { "$ref": "#/$defs/stringArray" },
         "detail": { "type": "string" }
       }
+    },
+    "residualCorrections": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "mode",
+        "grants_command_authority",
+        "applies_to_current_plan",
+        "selected_intent_additions",
+        "suggested_intent_additions",
+        "recommended_commands",
+        "signals",
+        "policy",
+        "issues"
+      ],
+      "properties": {
+        "status": { "enum": ["not_enough_evidence", "available", "unavailable"] },
+        "mode": { "const": "read_only" },
+        "grants_command_authority": { "const": false },
+        "applies_to_current_plan": { "type": "boolean" },
+        "selected_intent_additions": { "$ref": "#/$defs/stringArray" },
+        "suggested_intent_additions": { "$ref": "#/$defs/stringArray" },
+        "recommended_commands": { "$ref": "#/$defs/stringArray" },
+        "signals": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/residualSignal" }
+        },
+        "policy": { "$ref": "#/$defs/residualPolicy" },
+        "issues": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "residualPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "single_observation_changes_plan",
+        "minimum_repeated_samples_for_plan_change",
+        "automatic_intent_additions_enabled"
+      ],
+      "properties": {
+        "single_observation_changes_plan": { "const": false },
+        "minimum_repeated_samples_for_plan_change": { "const": 2 },
+        "automatic_intent_additions_enabled": { "const": false }
+      }
+    },
+    "residualSignal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "confidence",
+        "evidence_count",
+        "source",
+        "verification_plan_id",
+        "affected_reasons",
+        "affected_intents",
+        "detail",
+        "recommendation"
+      ],
+      "properties": {
+        "kind": { "enum": ["latest_unresolved_plan", "repeated_failure", "remaining_risk"] },
+        "confidence": { "enum": ["low", "medium", "high"] },
+        "evidence_count": { "type": "integer", "minimum": 1 },
+        "source": { "const": "latest-evidence" },
+        "verification_plan_id": {
+          "type": ["string", "null"],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "affected_reasons": { "$ref": "#/$defs/stringArray" },
+        "affected_intents": { "$ref": "#/$defs/stringArray" },
+        "detail": { "type": "string" },
+        "recommendation": { "enum": ["provide_new_evidence", "review_remaining_risk"] }
+      }
     }
   }
 }

package/schemas/locks.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/locks.schema.json",
+  "title": "mustflow active locks API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "status",
+    "lock_root",
+    "active_count",
+    "stale_count",
+    "active_locks",
+    "stale_locks",
+    "policy",
+    "recommended_commands",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api locks" },
+    "mustflow_root": { "type": "string" },
+    "status": { "enum": ["clear", "active", "stale", "unavailable"] },
+    "lock_root": { "const": ".mustflow/state/locks" },
+    "active_count": { "type": "integer", "minimum": 0 },
+    "stale_count": { "type": "integer", "minimum": 0 },
+    "active_locks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/activeLock" }
+    },
+    "stale_locks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/staleLock" }
+    },
+    "policy": { "$ref": "#/$defs/policy" },
+    "recommended_commands": { "$ref": "#/$defs/stringArray" },
+    "issues": { "$ref": "#/$defs/stringArray" }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "activeLock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["run_id", "intent", "pid", "started_at", "command_hash", "effects", "writes"],
+      "properties": {
+        "run_id": { "type": "string" },
+        "intent": { "type": "string" },
+        "pid": { "type": "integer" },
+        "started_at": { "type": "string" },
+        "command_hash": {
+          "type": ["string", "null"],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "effects": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/effect" }
+        },
+        "writes": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "effect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "access", "mode", "path", "lock", "concurrency"],
+      "properties": {
+        "source": { "type": "string" },
+        "access": { "type": "string" },
+        "mode": { "type": "string" },
+        "path": { "type": ["string", "null"] },
+        "lock": { "type": "string" },
+        "concurrency": { "type": "string" }
+      }
+    },
+    "staleLock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["run_id", "intent", "pid", "reason"],
+      "properties": {
+        "run_id": { "type": "string" },
+        "intent": { "type": "string" },
+        "pid": { "type": "integer" },
+        "reason": { "type": "string" }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "conflict_model", "direct_commands_bypass_locks", "wait_entrypoint"],
+      "properties": {
+        "source": { "const": "active-run-locks" },
+        "conflict_model": { "const": "command_effects_and_writes" },
+        "direct_commands_bypass_locks": { "const": true },
+        "wait_entrypoint": { "const": "mf run <intent> --wait" }
+      }
+    }
+  }
+}

package/templates/default/i18n.toml

@@ -56,7 +56,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 81
+revision = 82
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -137,6 +137,12 @@ source_locale = "en"
 revision = 1
 translations = {}
 
+[documents."skill.version-freshness-check"]
+source = "locales/en/.mustflow/skills/version-freshness-check/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.line-ending-hygiene"]
 source = "locales/en/.mustflow/skills/line-ending-hygiene/SKILL.md"
 source_locale = "en"

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 81
+revision: 82
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -151,6 +151,7 @@ routes. Event routes stay inactive until their event occurs.
 | Database migration files, schema migration history, ORM schema migrations, generated clients, schema dumps, SQL snapshots, backfills, rolling deploy compatibility, expand-and-contract changes, destructive database changes, migration rollback claims, or production database migration procedures are created, changed, reviewed, or reported | `.mustflow/skills/database-migration-change/SKILL.md` | Source schema, target schema, migration files, migration history, generated clients, schema dumps, SQL snapshots, affected queries, deployment shape, database engine, table size or lock assumptions, backfill plan, rollback type, validation query, and command contract entries | Migration files, ORM schemas, generated clients, schema dumps, SQL snapshots, backfill code, validation checks, seeds, fixtures, compatibility code, docs, tests, and directly synchronized examples | data loss, drop-plus-add rename, old/new app incompatibility, unsafe rolling deploy, unbounded backfill, production lock, generated-client drift, migration-history drift, false rollback claim, ORM autogenerate mistake, or destructive contract mixed with expand phase | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Migration phase, old/new schema compatibility, backfill and validation plan, rollback classification, ORM/generated/schema dump surfaces, dependent surfaces, verification, and remaining database-migration risk |
 | Dependency versions, lockfiles, package-manager metadata, workspace constraints, runtime engines, peer dependencies, optional dependencies, security advisory fixes, generated dependency output, framework plugins, CI actions, Docker base images, package manager behavior, or toolchain versions are upgraded, downgraded, pinned, widened, regenerated, reviewed, or reported | `.mustflow/skills/dependency-upgrade-review/SKILL.md` | Dependency name, old and new versions or ranges, direct or transitive path, ecosystem and package manager, declaration files, lockfiles, runtime or toolchain files, advisory or release-note evidence, generated outputs, callers, docs, package output, Docker or CI surfaces, and command contract entries | Package declarations, lockfiles, generated outputs, compatibility code, tests, docs, package metadata, Docker or CI files, and directly synchronized examples | lockfile churn, hidden transitive replacement, peer or engine break, module-format drift, native or optional package break, framework or generator output drift, unsafe broad security update, weakened tests, Docker or CI runtime drift, or unreviewed supply-chain change | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Upgrade reason, ecosystem surface, direct and transitive graph changes, compatibility classification, runtime/peer/engine/module/feature/platform/generated-output risks, synchronized surfaces, verification, and remaining dependency-upgrade risk |
 | Dependency, package, runtime, framework, tool, command, plugin, service, platform capability, supported-version policy, security patch path, ecosystem maturity claim, maintainer-risk assumption, runtime portability claim, edge or serverless compatibility claim, critical-path library choice, package script, lifecycle hook, binary download, lockfile, audit result, or supply-chain-sensitive dependency surface is assumed, added, removed, imported, invoked, installed, audited, or documented | `.mustflow/skills/dependency-reality-check/SKILL.md` | Assumed dependency or capability, declaration files, version or feature expectation, role criticality, supported-version or end-of-life evidence, patchability expectation, runtime compatibility boundary, maintainer and ecosystem evidence when available, lockfile entry, package script or lifecycle hook, audit or provenance evidence, and relevant command intents | Package metadata, lockfiles, imports, scripts, command contracts, docs, tests, runtime policy notes, portability notes, and reports | unavailable dependency, hallucinated or lookalike package, fragile single-maintainer core dependency, experimental technology in a survival path, unsupported runtime, unclear security patch path, runtime-specific API leakage into core logic, stale version claim, lifecycle script risk, audit suppression, lockfile drift, or install guidance mismatch | `changes_status`, `changes_diff_summary`, `build`, `test_release`, `mustflow_check` | Dependency checked, ecosystem and maintainer-risk boundary reviewed, supported-version, patchability, and runtime-portability boundary reviewed, supply-chain surface reviewed, declarations synchronized, verification, and remaining dependency risk |
+| Generated or edited code, configuration, CI workflows, package metadata, install instructions, examples, Docker images, framework setup, runtime declarations, toolchain declarations, or migration-sensitive snippets introduce explicit external version references, action refs, package ranges, runtime versions, framework majors, Docker image tags, or scaffold commands that may be stale | `.mustflow/skills/version-freshness-check/SKILL.md` | Versioned reference, owning files, repository version policy, approved freshness source, compatibility context, migration risk, and command contract entries | Package metadata, lockfiles, CI workflows, Dockerfiles, runtime files, framework config, docs, examples, templates, tests, and version-decision reports | stale default version, false latest claim, accidental major migration, repository policy mismatch, unsupported generated example, floating-tag drift, or unverified security/support claim | `changes_status`, `changes_diff_summary`, `build`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Versioned surfaces checked, repository policy and freshness source, selected version track, compatibility classification, approval need, synchronized surfaces, verification, and remaining version-freshness risk |
 | External systems, protocols, SDKs, databases, webhooks, queues, files, object storage, signed upload or download URLs, caches, API response models, framework requests or responses, server actions, route handlers, edge functions, worker handlers, AI models, browser storage, search engines, analytics tools, email platforms, no-code tools, observability backends, trace or request context, or provider data cross the core boundary or need port/adapter translation, error mapping, timeout, retry, circuit-breaker, bulkhead, idempotency, reconciliation, security, core-state ownership, vendor portability, or observability handling | `.mustflow/skills/adapter-boundary/SKILL.md` | External system or protocol, inbound/outbound direction, delivery boundary, internal use case, local port/adapter patterns, provider risk, provider failure policy, core-state ownership risk, vendor portability risk, observability identifier policy, API contract risk, changed files, and command contract entries | Ports, adapters, mappers, controllers, workers, stores, gateways, response mappers, telemetry mappers, timeout and retry policies, circuit breakers, bulkhead boundaries, tests, fixtures, assembly wiring, and directly synchronized docs or templates | provider leakage, framework business-rule leakage, telemetry backend leakage, storage-key leakage, screen-shaped API coupling, pass-through wrapper, SaaS dashboard as truth source, search or analytics policy leakage, queue contract leakage, unclassified external failure, duplicate side effect, unsafe retry, missing timeout, missing circuit breaker, missing bulkhead, unresolved unknown provider outcome, broken identifier propagation, secret or personal-data leak, or untested integration drift | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Boundary classification, delivery adapter responsibility, internal port, provider containment, core-state ownership, vendor portability, validation and mapping, API response mapping, observability identifier flow, timeout/retry/circuit-breaker/bulkhead/idempotency handling, reconciliation behavior, security notes, verification, and remaining provider risk |
 | Tauri frontend invokes, Rust commands, capabilities, permissions, scopes, plugins, filesystem, dialog, shell, opener, updater, sidecar, or mobile native permissions are created or changed | `.mustflow/skills/tauri-code-change/SKILL.md` | Frontend call sites, Tauri config, Rust commands, capability and permission files, plugin config, changed files, and command contract entries | Tauri frontend, Rust commands, capabilities, permissions, scopes, plugins, tests, and docs | broad native permission, untrusted IPC input, filesystem escape, shell or updater risk, or WebView/native boundary drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | IPC, permission, scope, filesystem, shell, updater, and native boundary checked, verification, and remaining Tauri risk |
 | File path handling, cross-platform path behavior, path helpers, safe filesystem wrappers, temp or cache paths, atomic writes, locks, archive extraction, uploads, downloads, scanners, CLI/API/schema path contracts, snapshots, generated outputs, or package artifact paths are created, changed, reviewed, or reported | `.mustflow/skills/file-path-cross-platform-change/SKILL.md` | Path ledger, trust classes, accepted path representation, base root, path helpers, safe filesystem wrappers, temp/cache helpers, lock policy, archive policy, upload/download policy, scanner policy, CLI/API/schema/snapshot/generated/package surfaces, platform expectations, and command contract entries | Path validators, helpers, wrappers, schemas, CLI/API parsing, snapshots, fixtures, docs, tests, generated-output paths, package artifact paths, archive extraction, scanner bounds, temp/cache handling, locks, and cleanup code | path traversal, base containment bypass, drive-relative path bug, reserved-name bug, case-collision bug, symlink or junction escape, unsafe archive extraction, non-atomic write claim, stale lock, scanner loop, cleanup data loss, path contract drift, or package artifact path drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Path contract, path ledger, trust classes, root policy, Windows/macOS/Linux/archive/upload/download/scanner/lock/temp/cache/atomic/cleanup decisions, synchronized contract surfaces, verification, and remaining path risk |

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -228,6 +228,12 @@ route_type = "adjunct"
 priority = 45
 applies_to_reasons = ["code_change", "docs_change", "security_change"]
 
+[routes."version-freshness-check"]
+category = "data_external"
+route_type = "adjunct"
+priority = 68
+applies_to_reasons = ["code_change", "docs_change", "package_metadata_change", "mustflow_config_change", "release_risk"]
+
 [routes."file-path-cross-platform-change"]
 category = "data_external"
 route_type = "primary"

package/templates/default/locales/en/.mustflow/skills/version-freshness-check/SKILL.md

@@ -0,0 +1,141 @@
+---
+mustflow_doc: skill.version-freshness-check
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: version-freshness-check
+description: Apply this skill when generated or edited code, configuration, CI workflows, package metadata, install instructions, examples, Docker images, framework setup, runtime declarations, toolchain declarations, or migration-sensitive snippets introduce explicit external version references that may be stale.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.version-freshness-check
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - build
+    - test_related
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Version Freshness Check
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent agents from writing stale external version references from memory, while avoiding blind upgrades that ignore repository policy, compatibility, or migration cost.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Generated or edited files introduce explicit external version references, action refs, package ranges, runtime versions, framework majors, Docker image tags, toolchain versions, setup actions, scaffold commands, install commands, or migration examples.
+- CI workflows, release workflows, Dockerfiles, package metadata, lockfiles, runtime files, framework configuration, README examples, docs, tests, fixtures, or templates mention external versions such as GitHub Actions refs, Node, Bun, Deno, Python, Rust, Tauri, Astro, Next, SvelteKit, Electron, Docker images, package managers, SDKs, plugins, or generators.
+- An agent proposes a versioned dependency, tool, framework, action, image, or runtime based on memory, copied snippets, older project examples, or user-provided text that may be stale.
+- The task asks whether a newer stable, recommended, LTS, or security-patched version should replace a version the agent was about to write.
+- A patch claims a version is latest, current, recommended, stable, LTS, supported, deprecated, end-of-life, or migration-safe.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The version reference is purely repository-local, such as an internal schema revision, fixture id, or package version already handled by `date-number-audit`.
+- The task only preserves an existing pinned external version without touching code, docs, examples, package metadata, CI, Docker, runtime declarations, or compatibility claims.
+- The task is a deliberate dependency upgrade, downgrade, lockfile refresh, or security advisory fix; use `dependency-upgrade-review` as the main skill and this skill only for freshness-specific claims if needed.
+- The task only checks whether a dependency exists or whether a package name is real; use `dependency-reality-check` first.
+- The user explicitly requests an offline-only draft and accepts that version freshness will be reported as unverified.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The versioned external reference being introduced, changed, preserved, or reported.
+- Files that own or repeat the version: package metadata, lockfiles, workflow files, Dockerfiles, runtime files, framework config, docs, examples, templates, fixtures, and tests.
+- Repository version policy if present: pinned ranges, lockfile expectations, LTS policy, security patch policy, supported runtime matrix, migration notes, downgrade constraints, or organization rules.
+- Approved freshness evidence when available: official docs, upstream repository releases, package registry metadata, image registry metadata, official migration notes, security advisory ranges, or existing repository-maintained snapshots.
+- Compatibility context: new project or existing project, patch/minor/major difference, framework adapter/plugin compatibility, runtime engine support, generated output, migration burden, rollback path, and whether the version touches a survival path.
+- Relevant command-intent contract entries for build, tests, docs, packaging, or mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Freshness evidence can be gathered from allowed local files, configured tooling, approved connectors, official sources, package metadata, registry metadata, or the user-provided source text. If none is available, the check must be reported as unverified rather than guessed.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Align versioned references across package metadata, workflow files, runtime declarations, templates, docs, examples, and tests when the repository policy and compatibility classification support the change.
+- Replace stale generated defaults with a verified stable, recommended, LTS, or repository-pinned value when the change is compatible and within scope.
+- Add conservative wording when a version was not refreshed or when multiple legitimate version tracks exist.
+- Do not force the newest major version, floating tag, or broad range when the repository pins a different supported track.
+- Do not claim a version is current, latest, stable, recommended, LTS, deprecated, or secure unless the claim was refreshed or clearly marked as snapshot-only.
+- Do not add package-manager, registry, browser, or network commands to the skill. Use configured command intents or report missing verification.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build a version ledger before editing: each external version reference, where it appears, whether it is new or existing, and whether it is code, config, CI, Docker, package metadata, docs, template, fixture, or test data.
+2. Check repository policy before upstream freshness: package and lock metadata, runtime files, CI matrices, Docker tags, supported-version docs, migration notes, existing examples, and command contracts.
+3. Identify the intended track for each reference: repository-pinned, lockfile-resolved, latest stable, recommended major, LTS, security-patched minimum, compatibility range, floating tag, digest-pinned image, or snapshot-only example.
+4. Refresh stale-sensitive external facts with the highest-authority allowed source available. Prefer official docs, upstream releases, package registry metadata, official migration notes, official image metadata, or user-provided current evidence over secondary summaries.
+5. If freshness cannot be checked with the available tools or permissions, keep the version conservative, avoid current-version claims, and report the unchecked source boundary.
+6. Compare the proposed value, repository policy, and upstream evidence. Classify the difference as `same`, `patch`, `minor`, `major`, `migration-required`, `security-minimum`, `policy-pinned`, `floating`, or `unknown`.
+7. Treat major, migration-required, pre-1.0, framework, runtime-engine, CI-action, Docker-image, generator, native, security-sensitive, and survival-path changes as higher risk even when the version number looks small.
+8. For new projects or new examples, prefer the verified stable or officially recommended track unless the repository policy pins another track.
+9. For existing projects, do not cross a major, migration-required, engine, framework, CI-image, or generated-output boundary without user approval or explicit repository policy.
+10. For patch, security-minimum, and low-risk minor differences, update only when the declaration, examples, lockfile policy, and verification surface can stay aligned. Otherwise report the proposed change and leave the pinned value unchanged.
+11. For GitHub Actions and CI tools, review the action source, major tag policy, runtime support, cache behavior, permissions, and organization pinning rule. Do not assume a newer major is safe only because it exists.
+12. For framework and runtime majors such as Astro, Tauri, Electron, Next, SvelteKit, Node, Bun, Deno, Python, Rust, or Java, check migration notes, config schema, plugin and adapter compatibility, generated files, security model, deployment target, and rollback path before recommending a major change.
+13. For Docker images, decide whether the project prefers semver tags, distro tags, LTS tags, date tags, or digests. Do not replace a digest or pinned base image with a floating tag unless the repository policy says so.
+14. Synchronize every accepted version decision across package metadata, lockfiles when intentionally updated, CI, Docker, runtime files, docs, examples, templates, tests, and release notes.
+15. Run the narrowest configured verification that covers the changed versioned surface. Use broader verification for major, migration-required, runtime, framework, generated-output, package-publish, Docker, CI, or security-sensitive changes.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Every touched external version reference has a ledger entry with repository policy, freshness evidence, compatibility classification, and final decision.
+- Stale model defaults are not silently written as if they were current.
+- Repository-pinned versions are preserved unless the task, policy, and compatibility classification support changing them.
+- Major or migration-required changes are either explicitly approved, deferred with a recommendation, or left unchanged with the risk reported.
+- Docs and examples do not make unverifiable current-version claims.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `build`
+- `test_related`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Choose the narrowest configured intent that proves the changed versioned surface. Report missing dependency, package, docs, Docker, CI, or release verification instead of inventing commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If repository policy and upstream evidence disagree, preserve the repository policy unless the user explicitly chooses a migration or the existing version is outside a required security or support range.
+- If official sources conflict, prefer the source that owns the artifact being referenced and report the conflict.
+- If a freshness check requires network, credentials, or a connector that is not available, report the boundary and avoid current-version claims.
+- If a proposed major or migration-required version is better for greenfield work but risky for the existing project, present both choices and ask before changing the project.
+- If verification fails after a freshness update, do not weaken tests, lower type checks, delete lockfiles, or widen ranges to make the update pass. Revert or narrow the version decision unless the behavior change is intentional.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Versioned surfaces checked
+- Repository version policy found or missing
+- Freshness source checked or unavailable
+- Proposed and selected version track
+- Compatibility classification: `same`, `patch`, `minor`, `major`, `migration-required`, `security-minimum`, `policy-pinned`, `floating`, or `unknown`
+- User approval needed or not, with reason
+- Surfaces synchronized
+- Command intents run
+- Skipped freshness or verification checks and reasons
+- Remaining version freshness risk

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.22.47"
+version = "2.23.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -48,6 +48,7 @@ creates = [
   ".mustflow/skills/dependency-injection/SKILL.md",
   ".mustflow/skills/dependency-reality-check/SKILL.md",
   ".mustflow/skills/dependency-upgrade-review/SKILL.md",
+  ".mustflow/skills/version-freshness-check/SKILL.md",
   ".mustflow/skills/diff-risk-review/SKILL.md",
   ".mustflow/skills/pure-core-imperative-shell/SKILL.md",
   ".mustflow/skills/result-option/SKILL.md",
@@ -147,6 +148,7 @@ minimal = [
   "database-migration-change",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-update",
   "external-prompt-injection-defense",
@@ -200,6 +202,7 @@ patterns = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-update",
   "external-prompt-injection-defense",
@@ -263,6 +266,7 @@ oss = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-prose-review",
   "docs-update",
@@ -335,6 +339,7 @@ team = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-update",
   "external-prompt-injection-defense",
@@ -395,6 +400,7 @@ product = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-update",
   "external-prompt-injection-defense",
@@ -463,6 +469,7 @@ library = [
   "dependency-injection",
   "dependency-reality-check",
   "dependency-upgrade-review",
+  "version-freshness-check",
   "diff-risk-review",
   "docs-prose-review",
   "docs-update",