mustflow 1.30.0 → 1.31.0

package/README.md

@@ -2,9 +2,9 @@
 
 Languages: [English](README.md) · [한국어](docs/i18n/ko/README.md) · [中文](docs/i18n/zh/README.md) · [Español](docs/i18n/es/README.md) · [Français](docs/i18n/fr/README.md) · [हिन्दी](docs/i18n/hi/README.md)
 
-mustflow is a workflow CLI designed for LLM coding agents. It guides agents to enter a repository, understand the correct operating context, run only authorized commands, and verify their work without guessing.
+mustflow is a repository-local work contract and verification CLI for LLM coding agents. It keeps agents inside explicit read, command, and verification boundaries without replacing the host agent's sandbox, approval, checkpoint, model, or tool policies.
 
-The core concept is straightforward: place `AGENTS.md` at the project root and keep detailed workflows under `.mustflow/`. Agents start from `AGENTS.md` and then follow the command contract, skills, project context, and verification rules in sequence.
+The core concept is straightforward: place `AGENTS.md` at the project root and keep detailed workflows under `.mustflow/`. Agents start from `AGENTS.md`, then follow the repository command contract, skills, project context, and verification rules in sequence.
 
 - Documentation site: <https://0disoft.github.io/mustflow/>
 - Human-readable project examples: [`examples/`](examples/)
@@ -268,6 +268,14 @@ npx mf update --dry-run
 npx mf update --apply
 ```
 
+After updating the mustflow package, `mf upgrade` combines the package freshness check with the safe project-file update step. It does not install packages by itself; update npm, pnpm, or Bun first.
+
+```sh
+bun update -g mustflow
+mf upgrade --dry-run
+mf upgrade
+```
+
 Agents should prefer the configured update intents so the repository receives a run receipt.
 
 ```sh
@@ -304,6 +312,8 @@ mf run mustflow_update_apply
 | `mf status` | Inspect installed state and changed or missing files. |
 | `mf update --dry-run` | Calculate a template update plan without writing files. |
 | `mf update --apply` | Apply template updates when nothing is blocked. |
+| `mf upgrade` | Check package freshness, then apply safe bundled template updates when the package is current. |
+| `mf upgrade --dry-run` | Check package freshness and print the safe project update plan without writing files. |
 | `mf help <topic>` | Show installed mustflow help. |
 | `mf dashboard` | Start a local inspection dashboard for status, verification recommendations, release/version-source status, template update readiness, latest run receipt, skill routes, safe preferences, and documentation review. Use `--export-json <path>` or `--export <path>` for a bounded static report. It does not execute commands or apply fixes. |
 | `mf version` | Print the installed mustflow package version. |

package/dist/cli/commands/run.js

@@ -1,17 +1,8 @@
-import { spawnSync } from 'node:child_process';
-import { runCheck } from './check.js';
-import { runClassify } from './classify.js';
-import { runContext } from './context.js';
-import { runDoctor } from './doctor.js';
-import { runHelp } from './help.js';
-import { runImpact } from './impact.js';
-import { runLineEndings } from './line-endings.js';
-import { runMap } from './map.js';
-import { runStatus } from './status.js';
-import { runUpdate } from './update.js';
-import { runVersionSources } from './version-sources.js';
+import { spawn, spawnSync } from 'node:child_process';
+import { performance } from 'node:perf_hooks';
 import { canRunMustflowBuiltinInProcess, isMustflowBinName } from '../../core/command-classification.js';
 import { createCommandEnv } from '../../core/command-env.js';
+import { BoundedOutputBuffer } from '../../core/bounded-output.js';
 import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
 import { readCommandContract, readMustflowConfigIfExists } from '../../core/config-loading.js';
 import { resolveRunReceiptRetentionPolicy } from '../../core/retention-policy.js';
@@ -20,12 +11,14 @@ import { getPackageVersion } from '../lib/package-info.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { createRunPlan, createRunPreview, isMustflowBuiltinIntent, renderRunPreviewText, } from '../lib/run-plan.js';
 import { createRunReceipt, writeRunReceipt } from '../../core/run-receipt.js';
+import { recordRunPerformanceHistory } from '../../core/run-performance-history.js';
+import { RunProfiler } from '../../core/run-profile.js';
 import { finishRunWriteTracking, startRunWriteTracking } from '../../core/run-write-drift.js';
 function emitOutput(reporter, output, stream) {
     if (!output) {
         return;
     }
-    const text = output.toString().trimEnd();
+    const text = (typeof output === 'object' && 'tail' in output ? output.tail : output.toString()).trimEnd();
     if (text.length === 0) {
         return;
     }
@@ -94,37 +87,37 @@ async function runKnownBuiltinCommand(args, reporter, lang) {
         return undefined;
     }
     if (command === 'check') {
-        return runCheck(commandArgs, reporter, lang);
+        return (await import('./check.js')).runCheck(commandArgs, reporter, lang);
     }
     if (command === 'classify') {
-        return runClassify(commandArgs, reporter, lang);
+        return (await import('./classify.js')).runClassify(commandArgs, reporter, lang);
     }
     if (command === 'context') {
-        return runContext(commandArgs, reporter, lang);
+        return (await import('./context.js')).runContext(commandArgs, reporter, lang);
     }
     if (command === 'doctor') {
-        return runDoctor(commandArgs, reporter, lang);
+        return (await import('./doctor.js')).runDoctor(commandArgs, reporter, lang);
     }
     if (command === 'help') {
-        return runHelp(commandArgs, reporter, lang);
+        return (await import('./help.js')).runHelp(commandArgs, reporter, lang);
     }
     if (command === 'impact') {
-        return runImpact(commandArgs, reporter, lang);
+        return (await import('./impact.js')).runImpact(commandArgs, reporter, lang);
     }
     if (command === 'line-endings') {
-        return runLineEndings(commandArgs, reporter, lang);
+        return (await import('./line-endings.js')).runLineEndings(commandArgs, reporter, lang);
     }
     if (command === 'map') {
-        return runMap(commandArgs, reporter, lang);
+        return (await import('./map.js')).runMap(commandArgs, reporter, lang);
     }
     if (command === 'status') {
-        return runStatus(commandArgs, reporter, lang);
+        return (await import('./status.js')).runStatus(commandArgs, reporter, lang);
     }
     if (command === 'update') {
-        return runUpdate(commandArgs, reporter, lang);
+        return (await import('./update.js')).runUpdate(commandArgs, reporter, lang);
     }
     if (command === 'version-sources') {
-        return runVersionSources(commandArgs, reporter, lang);
+        return (await import('./version-sources.js')).runVersionSources(commandArgs, reporter, lang);
     }
     return undefined;
 }
@@ -179,6 +172,76 @@ function runArgvCommand(command, cwd, maxOutputBytes, env, timeoutSeconds) {
         windowsHide: true,
     });
 }
+function writeStreamChunk(reporter, stream, chunk) {
+    if (stream === 'stdout') {
+        if (reporter.writeStdout) {
+            reporter.writeStdout(chunk);
+            return;
+        }
+        reporter.stdout(chunk.toString().trimEnd());
+        return;
+    }
+    if (reporter.writeStderr) {
+        reporter.writeStderr(chunk);
+        return;
+    }
+    reporter.stderr(chunk.toString().trimEnd());
+}
+function runArgvCommandStreaming(command, cwd, env, timeoutSeconds, stdoutTailBytes, stderrTailBytes, reporter) {
+    return new Promise((resolve) => {
+        const stdout = new BoundedOutputBuffer(stdoutTailBytes);
+        const stderr = new BoundedOutputBuffer(stderrTailBytes);
+        let settled = false;
+        let timedOut = false;
+        let childError;
+        let childPid;
+        let timeout;
+        const child = spawn(command?.executable ?? '', command?.args ?? [], {
+            cwd,
+            env,
+            shell: command?.shell ?? false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            detached: process.platform !== 'win32',
+        });
+        childPid = child.pid;
+        const finish = (status, signal) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            resolve({
+                status,
+                signal,
+                error: timedOut ? Object.assign(new Error('Command timed out'), { code: 'ETIMEDOUT' }) : childError,
+                stdout: stdout.toSnapshot(),
+                stderr: stderr.toSnapshot(),
+                pid: childPid,
+            });
+        };
+        child.stdout?.on('data', (chunk) => {
+            stdout.append(chunk);
+            writeStreamChunk(reporter, 'stdout', chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr.append(chunk);
+            writeStreamChunk(reporter, 'stderr', chunk);
+        });
+        child.once('error', (error) => {
+            childError = error;
+        });
+        child.once('close', (status, signal) => {
+            finish(status, signal);
+        });
+        timeout = setTimeout(() => {
+            timedOut = true;
+            terminateProcessTree(childPid);
+        }, timeoutSeconds * 1000);
+    });
+}
 function runShellCommand(command, cwd, maxOutputBytes, env, timeoutSeconds) {
     return spawnSync(command ?? '', {
         cwd,
@@ -192,6 +255,61 @@ function runShellCommand(command, cwd, maxOutputBytes, env, timeoutSeconds) {
         windowsHide: true,
     });
 }
+function runShellCommandStreaming(command, cwd, env, timeoutSeconds, stdoutTailBytes, stderrTailBytes, reporter) {
+    return new Promise((resolve) => {
+        const stdout = new BoundedOutputBuffer(stdoutTailBytes);
+        const stderr = new BoundedOutputBuffer(stderrTailBytes);
+        let settled = false;
+        let timedOut = false;
+        let childError;
+        let childPid;
+        let timeout;
+        const child = spawn(command ?? '', {
+            cwd,
+            env,
+            shell: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+            detached: process.platform !== 'win32',
+        });
+        childPid = child.pid;
+        const finish = (status, signal) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            resolve({
+                status,
+                signal,
+                error: timedOut ? Object.assign(new Error('Command timed out'), { code: 'ETIMEDOUT' }) : childError,
+                stdout: stdout.toSnapshot(),
+                stderr: stderr.toSnapshot(),
+                pid: childPid,
+            });
+        };
+        child.stdout?.on('data', (chunk) => {
+            stdout.append(chunk);
+            writeStreamChunk(reporter, 'stdout', chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr.append(chunk);
+            writeStreamChunk(reporter, 'stderr', chunk);
+        });
+        child.once('error', (error) => {
+            childError = error;
+        });
+        child.once('close', (status, signal) => {
+            finish(status, signal);
+        });
+        timeout = setTimeout(() => {
+            timedOut = true;
+            terminateProcessTree(childPid);
+        }, timeoutSeconds * 1000);
+    });
+}
 function getRunStatus(error, exitCode, successExitCodes) {
     const errorWithCode = error;
     if (errorWithCode?.code === 'ETIMEDOUT') {
@@ -281,7 +399,9 @@ export function getRunHelp(lang = 'en') {
  * invariant: Execution requires configured status, oneshot lifecycle, agent_allowed policy, and closed stdin.
  * risk: config, security, state
  */
-export async function runRun(args, reporter, lang = 'en') {
+export async function runRun(args, reporter, lang = 'en', options = {}) {
+    const executorStartedAtMs = performance.now();
+    const profiler = new RunProfiler();
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getRunHelp(lang));
         return 0;
@@ -310,36 +430,69 @@ export async function runRun(args, reporter, lang = 'en') {
         printUsageError(reporter, t(lang, 'cli.error.unexpectedArgument', { argument: extra[0] }), 'mf run --help', getRunHelp(lang), lang);
         return 1;
     }
-    const projectRoot = resolveMustflowRoot();
-    const contract = readCommandContract(projectRoot);
-    const plan = createRunPlan(projectRoot, contract, intentName);
+    const projectRoot = profiler.measure('root_detection', () => resolveMustflowRoot());
+    const contract = profiler.measure('command_contract', () => readCommandContract(projectRoot));
+    const plan = profiler.measure('plan_creation', () => createRunPlan(projectRoot, contract, intentName, { testTargets: options.testTargets }));
     if (previewMode) {
-        if (json) {
-            reporter.stdout(JSON.stringify(createRunPreview(plan, previewMode), null, 2));
-        }
-        else {
-            reporter.stdout(renderRunPreviewText(plan, previewMode));
-        }
+        profiler.measure('preview_render', () => {
+            if (json) {
+                reporter.stdout(JSON.stringify(createRunPreview(plan, previewMode), null, 2));
+            }
+            else {
+                reporter.stdout(renderRunPreviewText(plan, previewMode));
+            }
+        });
+        profiler.writeLatest({
+            projectRoot,
+            intent: intentName,
+            status: plan.ok ? 'previewed' : 'blocked',
+            previewMode,
+        });
         return plan.ok ? 0 : 1;
     }
     if (!plan.ok) {
         reportRunPlanFailure(plan, reporter, lang);
+        profiler.writeLatest({
+            projectRoot,
+            intent: intentName,
+            status: 'blocked',
+            previewMode: null,
+        });
         return 1;
     }
-    const runReceiptPolicy = resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot));
-    const env = createCommandEnv(projectRoot, { policy: plan.envPolicy, allowlist: plan.envAllowlist });
+    const runReceiptPolicy = profiler.measure('retention_policy', () => resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot)));
+    const env = profiler.measure('environment', () => createCommandEnv(projectRoot, { policy: plan.envPolicy, allowlist: plan.envAllowlist }));
     const lifecycleValue = plan.lifecycle ?? 'oneshot';
     const runPolicyValue = plan.runPolicy ?? 'agent_allowed';
-    const writeTracker = startRunWriteTracking(projectRoot, contract, intentName);
+    const writeTracker = profiler.measure('write_drift_before', () => startRunWriteTracking(projectRoot, contract, intentName));
+    const stdoutTailBytes = Math.min(runReceiptPolicy.stdoutTailBytes, plan.maxOutputBytes);
+    const stderrTailBytes = Math.min(runReceiptPolicy.stderrTailBytes, plan.maxOutputBytes);
+    let streamedOutput = false;
+    const childStartedAtMs = performance.now();
     const startedAt = new Date();
-    const result = plan.commandArgv && isMustflowBuiltinIntent(plan.intent)
-        ? ((await runBuiltinArgvInProcess(plan.commandArgv, plan.cwd, lang)) ??
-            runArgvCommand(plan.argvCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds))
-        : plan.commandArgv
-            ? runArgvCommand(plan.argvCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds)
-            : runShellCommand(plan.shellCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds);
+    const result = await profiler.measureAsync('child_command', async () => {
+        if (plan.commandArgv && isMustflowBuiltinIntent(plan.intent)) {
+            const builtinResult = await runBuiltinArgvInProcess(plan.commandArgv, plan.cwd, lang);
+            if (builtinResult) {
+                return builtinResult;
+            }
+        }
+        if (plan.commandArgv) {
+            if (!json) {
+                streamedOutput = true;
+                return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, stdoutTailBytes, stderrTailBytes, reporter);
+            }
+            return runArgvCommand(plan.argvCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds);
+        }
+        if (!json) {
+            streamedOutput = true;
+            return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, stdoutTailBytes, stderrTailBytes, reporter);
+        }
+        return runShellCommand(plan.shellCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds);
+    });
+    const childDurationMs = performance.now() - childStartedAtMs;
     const finishedAt = new Date();
-    const writeDrift = finishRunWriteTracking(writeTracker);
+    const writeDrift = profiler.measure('write_drift_after', () => finishRunWriteTracking(writeTracker));
     const exitCode = typeof result.status === 'number' ? result.status : null;
     const runStatus = getRunStatus(result.error, exitCode, plan.successExitCodes);
     let killMethod = null;
@@ -347,7 +500,7 @@ export async function runRun(args, reporter, lang = 'en') {
         killMethod = getKillMethod();
         terminateProcessTree(result.pid);
     }
-    const receipt = createRunReceipt({
+    const receipt = profiler.measure('receipt_create', () => createRunReceipt({
         intent: intentName,
         status: runStatus,
         timedOut: runStatus === 'timed_out',
@@ -372,16 +525,36 @@ export async function runRun(args, reporter, lang = 'en') {
         stdout: result.stdout,
         stderr: result.stderr,
         writeDrift,
+        executorOverheadMs: Math.max(0, Math.round((performance.now() - executorStartedAtMs - childDurationMs) * 1000) / 1000),
+        phaseTimings: profiler.getReceiptPhases(),
+        selectionSummary: {
+            strategy: plan.testTargets.length > 0 ? 'project_test_selection' : 'direct_intent',
+            changed_file_count: 0,
+            changed_surface_counts: {},
+            selected_target_count: Math.max(1, plan.testTargets.length),
+            fallback_used: false,
+        },
         stdoutTailBytes: runReceiptPolicy.stdoutTailBytes,
         stderrTailBytes: runReceiptPolicy.stderrTailBytes,
+    }));
+    if (options.writeLatestReceipt !== false) {
+        profiler.measure('receipt_write', () => writeRunReceipt(projectRoot, receipt));
+    }
+    profiler.measure('performance_history_write', () => recordRunPerformanceHistory(projectRoot, receipt));
+    profiler.writeLatest({
+        projectRoot,
+        intent: intentName,
+        status: runStatus,
+        previewMode: null,
     });
-    writeRunReceipt(projectRoot, receipt);
     if (json) {
         reporter.stdout(JSON.stringify(receipt, null, 2));
         return runStatus === 'passed' ? 0 : 1;
     }
-    emitOutput(reporter, result.stdout, 'stdout');
-    emitOutput(reporter, result.stderr, 'stderr');
+    if (!streamedOutput) {
+        emitOutput(reporter, result.stdout, 'stdout');
+        emitOutput(reporter, result.stderr, 'stderr');
+    }
     if (result.error) {
         const errorWithCode = result.error;
         if (errorWithCode.code === 'ETIMEDOUT') {

package/dist/cli/commands/upgrade.js

@@ -0,0 +1,65 @@
+import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { checkNpmLatestVersion } from '../lib/npm-version-check.js';
+import { readPackageMetadata } from '../lib/package-info.js';
+import { runUpdate } from './update.js';
+export function getUpgradeHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf upgrade [options]',
+        summary: t(lang, 'upgrade.help.summary'),
+        options: [
+            { label: '--dry-run', description: t(lang, 'upgrade.help.option.dryRun') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: ['mf upgrade', 'mf upgrade --dry-run'],
+        exitCodes: [
+            { label: '0', description: t(lang, 'upgrade.help.exit.ok') },
+            { label: '1', description: t(lang, 'upgrade.help.exit.fail') },
+        ],
+    }, lang);
+}
+function printPackageCheck(check, reporter, lang) {
+    reporter.stdout(`${check.packageName} ${check.currentVersion}`);
+    reporter.stdout(check.updateAvailable
+        ? t(lang, 'version.check.latestAvailable', { version: check.latestVersion })
+        : t(lang, 'version.check.upToDate', { version: check.latestVersion }));
+    if (check.updateAvailable) {
+        reporter.stdout('');
+        reporter.stdout(t(lang, 'version.check.updateCommand'));
+        reporter.stdout(check.updateCommand);
+    }
+}
+export async function runUpgrade(args, reporter, lang = 'en') {
+    if (args.includes('--help') || args.includes('-h')) {
+        reporter.stdout(getUpgradeHelp(lang));
+        return 0;
+    }
+    const supported = new Set(['--dry-run']);
+    const unsupported = args.filter((arg) => !supported.has(arg));
+    if (unsupported.length > 0) {
+        printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf upgrade --help', getUpgradeHelp(lang), lang);
+        return 1;
+    }
+    const dryRun = args.includes('--dry-run');
+    reporter.stdout(t(lang, 'upgrade.title'));
+    reporter.stdout('');
+    reporter.stdout(t(lang, 'upgrade.packageSection'));
+    try {
+        const packageCheck = await checkNpmLatestVersion(readPackageMetadata());
+        printPackageCheck(packageCheck, reporter, lang);
+        if (packageCheck.updateAvailable) {
+            reporter.stdout('');
+            reporter.stdout(t(lang, 'upgrade.packageUpdateRequired'));
+            reporter.stdout(t(lang, 'upgrade.noFilesWritten'));
+            return 1;
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        reporter.stderr(renderCliError(t(lang, 'upgrade.warning.versionCheckFailed', { message }), 'mf version --check', lang));
+        reporter.stderr(t(lang, 'upgrade.warning.continueWithBundledTemplate'));
+    }
+    reporter.stdout('');
+    reporter.stdout(t(lang, 'upgrade.projectSection'));
+    return runUpdate([dryRun ? '--dry-run' : '--apply'], reporter, lang);
+}

package/dist/cli/commands/verify.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { createClassifyOutput } from './classify.js';
 import { runRun } from './run.js';
@@ -9,6 +9,8 @@ import { t } from '../lib/i18n.js';
 import { readLocalCommandEffectGraph, readLocalPathSurfaces, } from '../lib/local-index.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 const VERIFY_SCHEMA_VERSION = '1';
+const VERIFY_RUN_DIR = path.join('.mustflow', 'state', 'runs', 'verify-latest');
+const LATEST_RUN_RECEIPT_PATH = path.join('.mustflow', 'state', 'runs', 'latest.json');
 function createBufferedOutput() {
     const stdout = [];
     const stderr = [];
@@ -139,6 +141,13 @@ function parseVerifyArgs(args) {
 function uniqueStrings(values) {
     return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
 }
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function sanitizeIntentFilePart(value) {
+    const sanitized = value.replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^_+|_+$/g, '');
+    return sanitized.length > 0 ? sanitized.slice(0, 80) : 'intent';
+}
 function readStringArray(value) {
     if (!Array.isArray(value)) {
         return [];
@@ -343,13 +352,17 @@ function candidateResultKey(candidate) {
         ? `intent:${candidate.intent}`
         : `missing:${candidate.reason}:${candidate.skipReason ?? ''}:${candidate.detail ?? ''}`;
 }
-function createSkippedResults(candidates, scheduledIntents) {
+function createSkippedResults(candidates, scheduledIntents, gaps) {
     const seen = new Set();
     const results = [];
+    const activeGapReasons = new Set(gaps.map((gap) => gap.reason));
     for (const candidate of candidates) {
         if (candidate.status === 'runnable' || (candidate.intent && scheduledIntents.has(candidate.intent))) {
             continue;
         }
+        if (candidate.candidateState === 'gap' && !activeGapReasons.has(candidate.reason)) {
+            continue;
+        }
         const key = candidateResultKey(candidate);
         if (seen.has(key)) {
             continue;
@@ -363,9 +376,19 @@ function createSkippedResults(candidates, scheduledIntents) {
     }
     return results;
 }
-async function runVerificationIntent(intent, lang) {
+function testTargetsByScheduledIntent(report) {
+    return new Map(report.test_selection.selected
+        .filter((candidate) => candidate.status === 'runnable' &&
+        candidate.testTargetsApplied &&
+        candidate.appliedTestTargets.length > 0)
+        .map((candidate) => [candidate.intent, candidate.appliedTestTargets]));
+}
+async function runVerificationIntent(intent, lang, testTargets = []) {
     const output = createBufferedOutput();
-    const exitCode = await runRun([intent, '--json'], output.reporter, lang);
+    const exitCode = await runRun([intent, '--json'], output.reporter, lang, {
+        writeLatestReceipt: false,
+        testTargets,
+    });
     const rawStdout = output.stdout().trim();
     let receipt = null;
     let status = exitCode === 0 ? 'passed' : 'failed';
@@ -419,17 +442,64 @@ function getVerificationStatus(summary) {
     }
     return 'passed';
 }
+function writeVerifyRunReceipts(projectRoot, output) {
+    const runDir = path.join(projectRoot, VERIFY_RUN_DIR);
+    const intentDir = path.join(runDir, 'intents');
+    const receipts = [];
+    rmSync(runDir, { recursive: true, force: true });
+    mkdirSync(intentDir, { recursive: true });
+    for (const [index, result] of output.results.entries()) {
+        let receiptPath = null;
+        if (result.intent && result.receipt) {
+            const fileName = `${String(index + 1).padStart(3, '0')}-${sanitizeIntentFilePart(result.intent)}.json`;
+            const absoluteReceiptPath = path.join(intentDir, fileName);
+            receiptPath = toPosixPath(path.join(VERIFY_RUN_DIR, 'intents', fileName));
+            writeFileSync(absoluteReceiptPath, `${JSON.stringify({ ...result.receipt, receipt_path: receiptPath }, null, 2)}\n`, 'utf8');
+        }
+        receipts.push({
+            intent: result.intent,
+            status: result.status,
+            skipped: result.skipped,
+            receipt_path: receiptPath,
+        });
+    }
+    const manifest = {
+        schema_version: '1',
+        command: 'verify',
+        reason: output.reason,
+        reasons: output.reasons,
+        plan_source: output.plan_source,
+        status: output.status,
+        summary: output.summary,
+        receipts,
+    };
+    writeFileSync(path.join(runDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    const latest = {
+        schema_version: '1',
+        command: 'verify',
+        kind: 'verify_run_summary',
+        reason: output.reason,
+        reasons: output.reasons,
+        plan_source: output.plan_source,
+        status: output.status,
+        summary: output.summary,
+        run_dir: toPosixPath(VERIFY_RUN_DIR),
+        manifest_path: toPosixPath(path.join(VERIFY_RUN_DIR, 'manifest.json')),
+    };
+    writeFileSync(path.join(projectRoot, LATEST_RUN_RECEIPT_PATH), `${JSON.stringify(latest, null, 2)}\n`, 'utf8');
+}
 async function createVerifyOutput(input, planSource, projectRoot, lang) {
     const contract = readCommandContract(projectRoot);
     const report = createChangeVerificationReport(input.classificationReport, contract, projectRoot);
     const scheduledIntents = new Set(report.schedule.entries.map((entry) => entry.intent));
+    const scheduledTestTargets = testTargetsByScheduledIntent(report);
     const results = [];
     for (const entry of report.schedule.entries) {
-        results.push(await runVerificationIntent(entry.intent, lang));
+        results.push(await runVerificationIntent(entry.intent, lang, scheduledTestTargets.get(entry.intent) ?? []));
     }
-    results.push(...createSkippedResults(report.candidates, scheduledIntents));
+    results.push(...createSkippedResults(report.candidates, scheduledIntents, report.gaps));
     const summary = summarizeResults(results);
-    return {
+    const output = {
         schema_version: VERIFY_SCHEMA_VERSION,
         command: 'verify',
         mustflow_root: projectRoot,
@@ -440,6 +510,8 @@ async function createVerifyOutput(input, planSource, projectRoot, lang) {
         summary,
         results,
     };
+    writeVerifyRunReceipts(projectRoot, output);
+    return output;
 }
 async function createPlanOnlyOutput(input, projectRoot) {
     const contract = readCommandContract(projectRoot);

package/dist/cli/i18n/en.js

@@ -27,6 +27,7 @@ export const enMessages = {
     "command.contractLint.summary": "Lint the command contract",
     "command.status.summary": "Show local mustflow install status",
     "command.update.summary": "Preview or apply mustflow workflow updates",
+    "command.upgrade.summary": "Check the package version and safely update installed workflow files",
     "command.map.summary": "Generate REPO_MAP.md",
     "command.lineEndings.summary": "Inspect and normalize line-ending policy",
     "command.run.summary": "Run a configured oneshot command",
@@ -658,6 +659,17 @@ Read these files before working:
     "version.check.upToDate": "latest {version}; already up to date",
     "version.check.updateCommand": "Update command:",
     "version.error.checkFailed": "Could not check npm for a newer version: {message}",
+    "upgrade.help.summary": "Check whether the installed mustflow package is current, then safely apply bundled workflow template updates when possible.",
+    "upgrade.help.option.dryRun": "Check package status and print the project update plan without writing files",
+    "upgrade.help.exit.ok": "The package was current and the project update check completed",
+    "upgrade.help.exit.fail": "A package update is required, a project update blocker was found, or input was invalid",
+    "upgrade.title": "mustflow upgrade",
+    "upgrade.packageSection": "Package:",
+    "upgrade.projectSection": "Project template:",
+    "upgrade.packageUpdateRequired": "Update the mustflow package first, then run `mf upgrade` again.",
+    "upgrade.noFilesWritten": "No project files were written.",
+    "upgrade.warning.versionCheckFailed": "Could not check npm for a newer version: {message}",
+    "upgrade.warning.continueWithBundledTemplate": "Continuing with the bundled template in the current CLI.",
     "classify.help.summary": "Classify changed paths, public surfaces, and required validation reasons without modifying files.",
     "classify.help.option.changed": "Read paths from git status --short --untracked-files=all",
     "classify.help.exit.ok": "Change classification was inspected and printed",