mustflow 2.103.22 → 2.103.31

package/README.md

@@ -143,7 +143,7 @@ mustflow installs and validates an agent workflow for user projects.
 - Records blockers, contradictions, verification gaps, and remaining risks as a structured conflict ledger in verify, evidence, and dashboard reports.
 - Stores bounded failure replay capsules for failed `mf verify` runs so future agents can reproduce the intent, receipt, command fingerprint, and changed-file state without copying raw command output.
 - Writes bounded command receipts under `.mustflow/state/runs/run-*`, atomically updates `.mustflow/state/runs/latest.json`, and rebuilds `.mustflow/state/runs/latest.index.json` for recent retained runs.
-- Generates a concise repository navigation map, `REPO_MAP.md`, with `mf map`.
+- Generates a concise repository navigation map, `REPO_MAP.md`, with `mf map`, and a design-flow map, `REPO_FLOW.md`, with `mf flow`.
 - Indexes and searches mustflow docs, skills, skill routes, command rules, command-effect locks, file fingerprints, and opt-in source anchor metadata with SQLite via `mf index` and `mf search`. The local SQLite file is a rebuildable lookup cache, not a memory store, audit log, command transcript store, command-authority source, or source-content database.
 - Tracks agent-created or agent-modified documentation needing prose review with `mf docs review`.
 - Validates restricted work-item or handoff JSON records with `mf handoff validate` without creating backlog files, storing transcripts, or granting command authority.
@@ -199,7 +199,7 @@ The default template does not create project-owned root documents or contract fi
 
 `mf init` creates `.gitignore` if it is missing. If `.gitignore` exists, mustflow updates only its managed block and preserves user rules.
 
-`REPO_MAP.md` is not copied from the template. Generate it when needed with `mf map --write`. `.mustflow/cache/mustflow.sqlite` is also a regenerable local index created by `mf index`. `.mustflow/review/docs.toml` is not copied from the template; `mf docs review` creates it only when a document is added to the review queue.
+`REPO_MAP.md` and `REPO_FLOW.md` are not copied from the template. Generate them when needed with `mf map --write` and `mf flow --write`. `.mustflow/cache/mustflow.sqlite` is also a regenerable local index created by `mf index`. `.mustflow/review/docs.toml` is not copied from the template; `mf docs review` creates it only when a document is added to the review queue.
 
 If a project already has optional root Markdown files such as `README.md`, `PROJECT.md`, `ROADMAP.md`, `DESIGN.md`, `GOVERNANCE.md`, `TESTING.md`, `DEPLOYMENT.md`, `ARCHITECTURE.md`, or `API.md`, the repository map can use them as navigation anchors. It can also discover purpose-specific machine-readable contracts such as `project.contract.json`, `project.constants.json`, `design-tokens.json`, `openapi.yaml`, `asyncapi.yaml`, `schema.graphql`, and `schema.prisma`. Generic catch-all names like `SSOT.json` are not default anchors. `mf init` does not create or overwrite those project-owned files by default.
 
@@ -290,6 +290,9 @@ mf run mustflow_update_apply
 | `mf skill route` | Resolve compact skill route candidates from task text, paths, and reasons before reading selected skill documents. |
 | `mf map --stdout` | Print the current mustflow root map to stdout. |
 | `mf map --write` | Create or update `REPO_MAP.md`. |
+| `mf flow --stdout` | Print the current mustflow root design-flow map to stdout. |
+| `mf flow --write` | Create or update `REPO_FLOW.md`. |
+| `mf flow --check` | Check whether `REPO_FLOW.md` is current. |
 | `mf quality check` | Inspect changed files for quality-gaming patterns without writing files. |
 | `mf quality check --all` | Inspect every tracked text file for quality-gaming patterns. |
 | `mf script-pack list` | List bundled script packs, script refs, routing hints, side-effect flags, input/output labels, and JSON schema files. |

package/dist/cli/commands/flow.js

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { acquireActiveCommandLock, REPO_FLOW_WRITE_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
+import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { generateRepoFlow, getExpectedRepoFlowSourceFingerprint, writeRepoFlow } from '../lib/repo-flow.js';
+import { parseSimpleFrontmatter } from '../lib/validation/frontmatter.js';
+const FLOW_OPTIONS = [
+    { name: '--stdout', kind: 'boolean' },
+    { name: '--write', kind: 'boolean' },
+    { name: '--check', kind: 'boolean' },
+];
+export function getFlowHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf flow [options]',
+        summary: t(lang, 'flow.help.summary'),
+        options: [
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+            { label: '--stdout', description: t(lang, 'flow.help.option.stdout') },
+            { label: '--write', description: t(lang, 'flow.help.option.write') },
+            { label: '--check', description: t(lang, 'flow.help.option.check') },
+        ],
+        examples: ['mf flow --stdout', 'mf flow --write', 'mf flow --check'],
+        exitCodes: [
+            { label: '0', description: t(lang, 'flow.help.exit.ok') },
+            { label: '1', description: t(lang, 'cli.common.invalidInput') },
+        ],
+    }, lang);
+}
+function checkRepoFlow(projectRoot, reporter, lang) {
+    const repoFlowPath = path.join(projectRoot, 'REPO_FLOW.md');
+    if (!existsSync(repoFlowPath)) {
+        reporter.stderr(t(lang, 'flow.check.missing'));
+        return 1;
+    }
+    const content = readFileSync(repoFlowPath, 'utf8');
+    const frontmatter = parseSimpleFrontmatter(content);
+    const expectedFingerprint = getExpectedRepoFlowSourceFingerprint(projectRoot);
+    if (frontmatter.source_fingerprint !== expectedFingerprint) {
+        reporter.stderr(t(lang, 'flow.check.stale'));
+        return 1;
+    }
+    reporter.stdout(t(lang, 'flow.check.current'));
+    return 0;
+}
+export function runFlow(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getFlowHelp(lang));
+        return 0;
+    }
+    const parsed = parseCliOptions(args, FLOW_OPTIONS);
+    if (parsed.error) {
+        printUsageError(reporter, formatCliOptionParseError(parsed.error, lang), 'mf flow --help', getFlowHelp(lang), lang);
+        return 1;
+    }
+    let shouldPrint = hasParsedCliOption(parsed, '--stdout');
+    const shouldWrite = hasParsedCliOption(parsed, '--write');
+    const shouldCheck = hasParsedCliOption(parsed, '--check');
+    if (shouldCheck && (shouldPrint || shouldWrite)) {
+        printUsageError(reporter, t(lang, 'flow.error.checkConflict'), 'mf flow --help', getFlowHelp(lang), lang);
+        return 1;
+    }
+    if (!shouldPrint && !shouldWrite && !shouldCheck) {
+        shouldPrint = true;
+    }
+    const projectRoot = resolveMustflowRoot();
+    if (shouldCheck) {
+        return checkRepoFlow(projectRoot, reporter, lang);
+    }
+    const activeLock = shouldWrite ? acquireActiveCommandLock(projectRoot, 'mf flow --write', REPO_FLOW_WRITE_EFFECTS) : null;
+    if (activeLock && !activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf flow --write', activeLock.conflicts, 'mf flow --help', lang);
+        return 1;
+    }
+    try {
+        const content = generateRepoFlow(projectRoot);
+        if (shouldWrite) {
+            writeRepoFlow(projectRoot, content);
+            reporter.stdout(t(lang, 'flow.wrote'));
+        }
+        if (shouldPrint) {
+            reporter.stdout(content);
+        }
+        return 0;
+    }
+    finally {
+        if (activeLock?.ok) {
+            activeLock.handle.release();
+        }
+    }
+}

package/dist/cli/commands/run/executor.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { BoundedOutputBuffer } from '../../../core/bounded-output.js';
 import { createPendingTimeoutTermination, forceTerminateProcessTree, getKillMethod, terminateProcessTree, } from './process-tree.js';
 import { createOutputLimitError, isOutputLimitExceededError, writeOutputLimitTerminationMarker, writeStreamChunk, writeStreamChunkPrefix, } from './output.js';
+import { createWindowsCommandScriptSpawn } from './windows-command-script.js';
 const TERMINATION_CONFIRMATION_FALLBACK_MS = 1000;
 function createEmptyOutputSnapshot(maxBytes) {
     return new BoundedOutputBuffer(maxBytes).toSnapshot();
@@ -9,6 +10,23 @@ function createEmptyOutputSnapshot(maxBytes) {
 function createInvalidExecutableError() {
     return Object.assign(new Error('Command executable must not be empty'), { code: 'EINVAL' });
 }
+function normalizeSpawnedCommandInput(command) {
+    if (process.platform === 'win32' && command.windowsCommandScript === true) {
+        const windowsCommand = createWindowsCommandScriptSpawn(command.executable, command.args ?? []);
+        return {
+            executable: windowsCommand.executable,
+            args: windowsCommand.args,
+            shell: windowsCommand.shell,
+            windowsVerbatimArguments: windowsCommand.windowsVerbatimArguments,
+        };
+    }
+    return {
+        executable: command.executable,
+        args: command.args ?? [],
+        shell: command.shell,
+        windowsVerbatimArguments: false,
+    };
+}
 function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
     if (command.executable.trim().length === 0) {
         return Promise.resolve({
@@ -35,12 +53,14 @@ function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, killAfter
         let terminationStarted = false;
         let outputLimitMarkerWritten = false;
         let termination = null;
-        const child = spawn(command.executable, command.args ?? [], {
+        const spawnCommand = normalizeSpawnedCommandInput(command);
+        const child = spawn(spawnCommand.executable, spawnCommand.args, {
             cwd,
             env,
-            shell: command.shell,
+            shell: spawnCommand.shell,
             stdio: ['ignore', 'pipe', 'pipe'],
             windowsHide: true,
+            windowsVerbatimArguments: spawnCommand.windowsVerbatimArguments,
             detached: process.platform !== 'win32',
         });
         childPid = child.pid;
@@ -164,7 +184,12 @@ function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, killAfter
     });
 }
 export function runArgvCommandStreaming(command, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
-    return runSpawnedCommandStreaming({ executable: command?.executable ?? '', args: command?.args ?? [], shell: command?.shell ?? false }, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);
+    return runSpawnedCommandStreaming({
+        executable: command?.executable ?? '',
+        args: command?.args ?? [],
+        shell: command?.shell ?? false,
+        windowsCommandScript: command?.windowsCommandScript ?? false,
+    }, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);
 }
 export function runShellCommandStreaming(command, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
     return runSpawnedCommandStreaming({ executable: command ?? '', shell: true }, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);

package/dist/cli/commands/run/windows-command-script.js

@@ -0,0 +1,23 @@
+export function isWindowsCommandScriptPath(executablePath) {
+    return /\.(?:cmd|bat)$/iu.test(executablePath);
+}
+export function quoteWindowsCommandScriptToken(value) {
+    if (/[\u0000\r\n]/u.test(value)) {
+        throw Object.assign(new Error('Windows command script arguments must not contain NUL or line breaks'), { code: 'EINVAL' });
+    }
+    if (/^[A-Za-z0-9_./:\\@+=,-]+$/u.test(value)) {
+        return value;
+    }
+    return `"${value.replace(/"/gu, '""')}"`;
+}
+export function createWindowsCommandScriptLine(executablePath, args) {
+    return ['call', quoteWindowsCommandScriptToken(executablePath), ...args.map(quoteWindowsCommandScriptToken)].join(' ');
+}
+export function createWindowsCommandScriptSpawn(executablePath, args, comspec = process.env.ComSpec ?? process.env.COMSPEC) {
+    return {
+        executable: comspec && comspec.trim().length > 0 ? comspec : 'cmd.exe',
+        args: ['/d', '/s', '/c', createWindowsCommandScriptLine(executablePath, args)],
+        shell: false,
+        windowsVerbatimArguments: true,
+    };
+}

package/dist/cli/i18n/en.js

@@ -38,6 +38,7 @@ export const enMessages = {
     "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.flow.summary": "Generate REPO_FLOW.md",
     "command.lineEndings.summary": "Inspect and normalize line-ending policy",
     "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.scriptPack.summary": "List, suggest, and run bundled mustflow script packs",
@@ -723,6 +724,16 @@ Read these files before working:
     "map.error.nestedConflict": "Cannot combine --include-nested and --root-only",
     "map.error.invalidDepth": "Invalid value for --depth",
     "map.wrote": "Wrote REPO_MAP.md",
+    "flow.help.summary": "Generate REPO_FLOW.md, a design-flow map for the current mustflow root.",
+    "flow.help.option.stdout": "Print the generated flow map",
+    "flow.help.option.write": "Write REPO_FLOW.md",
+    "flow.help.option.check": "Check whether REPO_FLOW.md is current",
+    "flow.help.exit.ok": "Flow map was generated, written, or checked",
+    "flow.error.checkConflict": "Cannot combine --check with --stdout or --write",
+    "flow.check.missing": "REPO_FLOW.md is missing; regenerate with mf flow --write",
+    "flow.check.stale": "REPO_FLOW.md is stale; regenerate with mf flow --write",
+    "flow.check.current": "REPO_FLOW.md is current",
+    "flow.wrote": "Wrote REPO_FLOW.md",
     "lineEndings.help.summary": "Inspect Git-tracked files for line-ending policy drift and normalize them to LF when requested.",
     "lineEndings.help.option.all": "Inspect every tracked file instead of only changed files",
     "lineEndings.help.option.dryRun": "Preview normalization targets without writing files",

package/dist/cli/i18n/es.js

@@ -38,6 +38,7 @@ export const esMessages = {
     "command.update.summary": "Previsualiza o aplica actualizaciones del flujo de trabajo mustflow",
     "command.upgrade.summary": "Comprueba la versión del paquete y actualiza con seguridad los archivos de flujo instalados",
     "command.map.summary": "Genera REPO_MAP.md",
+    "command.flow.summary": "Genera REPO_FLOW.md",
     "command.lineEndings.summary": "Inspecciona y normaliza la política de finales de línea",
     "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.scriptPack.summary": "List, suggest, and run bundled mustflow script packs",
@@ -723,6 +724,16 @@ Lee estos archivos antes de trabajar:
     "map.error.nestedConflict": "No se pueden combinar --include-nested y --root-only",
     "map.error.invalidDepth": "Valor no valido para --depth",
     "map.wrote": "Se escribio REPO_MAP.md",
+    "flow.help.summary": "Genera REPO_FLOW.md, un mapa de flujo de diseno para la raiz mustflow actual.",
+    "flow.help.option.stdout": "Imprime el mapa de flujo generado",
+    "flow.help.option.write": "Escribe REPO_FLOW.md",
+    "flow.help.option.check": "Comprueba si REPO_FLOW.md esta actualizado",
+    "flow.help.exit.ok": "El mapa de flujo se genero, escribio o comprobo",
+    "flow.error.checkConflict": "No se puede combinar --check con --stdout o --write",
+    "flow.check.missing": "Falta REPO_FLOW.md; regeneralo con mf flow --write",
+    "flow.check.stale": "REPO_FLOW.md esta obsoleto; regeneralo con mf flow --write",
+    "flow.check.current": "REPO_FLOW.md esta actualizado",
+    "flow.wrote": "Se escribio REPO_FLOW.md",
     "lineEndings.help.summary": "Inspect Git-tracked files for line-ending policy drift and normalize them to LF when requested.",
     "lineEndings.help.option.all": "Inspect every tracked file instead of only changed files",
     "lineEndings.help.option.dryRun": "Preview normalization targets without writing files",

package/dist/cli/i18n/fr.js

@@ -38,6 +38,7 @@ export const frMessages = {
     "command.update.summary": "Prévisualise ou applique les mises à jour du flux de travail mustflow",
     "command.upgrade.summary": "Vérifie la version du paquet et met à jour en sécurité les fichiers de workflow installés",
     "command.map.summary": "Génère REPO_MAP.md",
+    "command.flow.summary": "Génère REPO_FLOW.md",
     "command.lineEndings.summary": "Inspecte et normalise la politique de fins de ligne",
     "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.scriptPack.summary": "List, suggest, and run bundled mustflow script packs",
@@ -723,6 +724,16 @@ Lisez ces fichiers avant de travailler :
     "map.error.nestedConflict": "Impossible de combiner --include-nested et --root-only",
     "map.error.invalidDepth": "Valeur non valide pour --depth",
     "map.wrote": "REPO_MAP.md écrit",
+    "flow.help.summary": "Génère REPO_FLOW.md, une carte du flux de conception pour la racine mustflow actuelle.",
+    "flow.help.option.stdout": "Imprime la carte de flux générée",
+    "flow.help.option.write": "Écrit REPO_FLOW.md",
+    "flow.help.option.check": "Vérifie si REPO_FLOW.md est à jour",
+    "flow.help.exit.ok": "La carte de flux a été générée, écrite ou vérifiée",
+    "flow.error.checkConflict": "Impossible de combiner --check avec --stdout ou --write",
+    "flow.check.missing": "REPO_FLOW.md est manquant; régénérez-le avec mf flow --write",
+    "flow.check.stale": "REPO_FLOW.md est obsolète; régénérez-le avec mf flow --write",
+    "flow.check.current": "REPO_FLOW.md est à jour",
+    "flow.wrote": "REPO_FLOW.md écrit",
     "lineEndings.help.summary": "Inspect Git-tracked files for line-ending policy drift and normalize them to LF when requested.",
     "lineEndings.help.option.all": "Inspect every tracked file instead of only changed files",
     "lineEndings.help.option.dryRun": "Preview normalization targets without writing files",

package/dist/cli/i18n/hi.js

@@ -38,6 +38,7 @@ export const hiMessages = {
     "command.update.summary": "mustflow वर्कफ़्लो अपडेट का पूर्वावलोकन करें या लागू करें",
     "command.upgrade.summary": "Package version जाँचें और installed workflow files सुरक्षित रूप से update करें",
     "command.map.summary": "REPO_MAP.md बनाएँ",
+    "command.flow.summary": "REPO_FLOW.md बनाएँ",
     "command.lineEndings.summary": "लाइन-एंडिंग नीति की जाँच और सामान्यीकरण करें",
     "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.scriptPack.summary": "List, suggest, and run bundled mustflow script packs",
@@ -723,6 +724,16 @@ export const hiMessages = {
     "map.error.nestedConflict": "--include-nested और --root-only को साथ नहीं रखा जा सकता",
     "map.error.invalidDepth": "--depth के लिए अमान्य मान",
     "map.wrote": "REPO_MAP.md लिखा गया",
+    "flow.help.summary": "मौजूदा mustflow root के लिए design-flow map REPO_FLOW.md बनाता है।",
+    "flow.help.option.stdout": "Generated flow map print करें",
+    "flow.help.option.write": "REPO_FLOW.md लिखें",
+    "flow.help.option.check": "जांचें कि REPO_FLOW.md current है या नहीं",
+    "flow.help.exit.ok": "Flow map बनाया, लिखा, या check किया गया",
+    "flow.error.checkConflict": "--check को --stdout या --write के साथ नहीं रखा जा सकता",
+    "flow.check.missing": "REPO_FLOW.md missing है; mf flow --write से regenerate करें",
+    "flow.check.stale": "REPO_FLOW.md stale है; mf flow --write से regenerate करें",
+    "flow.check.current": "REPO_FLOW.md current है",
+    "flow.wrote": "REPO_FLOW.md लिखा गया",
     "lineEndings.help.summary": "Inspect Git-tracked files for line-ending policy drift and normalize them to LF when requested.",
     "lineEndings.help.option.all": "Inspect every tracked file instead of only changed files",
     "lineEndings.help.option.dryRun": "Preview normalization targets without writing files",

package/dist/cli/i18n/ko.js

@@ -38,6 +38,7 @@ export const koMessages = {
     "command.update.summary": "mustflow 워크플로우 갱신을 미리 보거나 적용합니다",
     "command.upgrade.summary": "패키지 버전을 확인하고 설치된 워크플로우 파일을 안전하게 갱신합니다",
     "command.map.summary": "REPO_MAP.md를 작성합니다",
+    "command.flow.summary": "REPO_FLOW.md를 작성합니다",
     "command.lineEndings.summary": "줄바꿈 정책을 검사하고 정규화합니다",
     "command.quality.summary": "변경 파일의 품질 지표 꼼수를 검사합니다",
     "command.scriptPack.summary": "mustflow 내장 script pack을 나열, 추천, 실행합니다",
@@ -723,6 +724,16 @@ export const koMessages = {
     "map.error.nestedConflict": "--include-nested와 --root-only는 함께 사용할 수 없습니다",
     "map.error.invalidDepth": "--depth 값이 올바르지 않습니다",
     "map.wrote": "REPO_MAP.md를 작성했습니다",
+    "flow.help.summary": "현재 mustflow 루트의 설계 흐름 지도인 REPO_FLOW.md를 생성합니다.",
+    "flow.help.option.stdout": "생성한 흐름 지도를 출력합니다",
+    "flow.help.option.write": "REPO_FLOW.md를 작성합니다",
+    "flow.help.option.check": "REPO_FLOW.md가 최신인지 확인합니다",
+    "flow.help.exit.ok": "흐름 지도를 생성, 작성, 또는 확인했습니다",
+    "flow.error.checkConflict": "--check는 --stdout 또는 --write와 함께 사용할 수 없습니다",
+    "flow.check.missing": "REPO_FLOW.md가 없습니다. mf flow --write로 다시 생성하세요",
+    "flow.check.stale": "REPO_FLOW.md가 오래되었습니다. mf flow --write로 다시 생성하세요",
+    "flow.check.current": "REPO_FLOW.md가 최신입니다",
+    "flow.wrote": "REPO_FLOW.md를 작성했습니다",
     "lineEndings.help.summary": "Git 추적 파일의 줄바꿈 정책을 검사하고 필요할 때 LF로 정규화합니다.",
     "lineEndings.help.option.all": "변경된 파일만 보지 않고 모든 추적 파일을 검사합니다",
     "lineEndings.help.option.dryRun": "파일을 쓰지 않고 정규화 대상을 미리 봅니다",

package/dist/cli/i18n/zh.js

@@ -38,6 +38,7 @@ export const zhMessages = {
     "command.update.summary": "预览或应用 mustflow 工作流更新",
     "command.upgrade.summary": "检查包版本并安全更新已安装的工作流文件",
     "command.map.summary": "生成 REPO_MAP.md",
+    "command.flow.summary": "生成 REPO_FLOW.md",
     "command.lineEndings.summary": "检查并规范化换行符策略",
     "command.quality.summary": "Inspect changed files for quality-gaming patterns",
     "command.scriptPack.summary": "List, suggest, and run bundled mustflow script packs",
@@ -723,6 +724,16 @@ export const zhMessages = {
     "map.error.nestedConflict": "不能同时使用 --include-nested 和 --root-only",
     "map.error.invalidDepth": "--depth 的值无效",
     "map.wrote": "已写入 REPO_MAP.md",
+    "flow.help.summary": "为当前 mustflow 根生成设计流程图 REPO_FLOW.md。",
+    "flow.help.option.stdout": "输出生成的流程图",
+    "flow.help.option.write": "写入 REPO_FLOW.md",
+    "flow.help.option.check": "检查 REPO_FLOW.md 是否为最新",
+    "flow.help.exit.ok": "流程图已生成、写入或检查",
+    "flow.error.checkConflict": "不能将 --check 与 --stdout 或 --write 组合使用",
+    "flow.check.missing": "REPO_FLOW.md 缺失；请用 mf flow --write 重新生成",
+    "flow.check.stale": "REPO_FLOW.md 已过期；请用 mf flow --write 重新生成",
+    "flow.check.current": "REPO_FLOW.md 是最新的",
+    "flow.wrote": "已写入 REPO_FLOW.md",
     "lineEndings.help.summary": "Inspect Git-tracked files for line-ending policy drift and normalize them to LF when requested.",
     "lineEndings.help.option.all": "Inspect every tracked file instead of only changed files",
     "lineEndings.help.option.dryRun": "Preview normalization targets without writing files",

package/dist/cli/index.js

@@ -45,6 +45,7 @@ function getTopLevelHelp(lang) {
             'mf context --json',
             'mf tech suggest --scope frontend',
             'mf map --write',
+            'mf flow --write',
             'mf search mustflow_check',
             'mf explain authority AGENTS.md',
             'mf explain --why-blocked test',

package/dist/cli/lib/active-command-lock.js

@@ -4,6 +4,9 @@ import { t } from './i18n.js';
 export const REPO_MAP_WRITE_EFFECTS = [
     { type: 'write', mode: 'replace', path: 'REPO_MAP.md', concurrency: 'exclusive' },
 ];
+export const REPO_FLOW_WRITE_EFFECTS = [
+    { type: 'write', mode: 'replace', path: 'REPO_FLOW.md', concurrency: 'exclusive' },
+];
 export const LOCAL_INDEX_WRITE_EFFECTS = [
     {
         type: 'write',
@@ -26,6 +29,7 @@ export const MUSTFLOW_UPDATE_APPLY_EFFECTS = [
 ];
 export const GENERATED_SURFACE_READ_EFFECTS = [
     { type: 'read', mode: 'read', path: 'REPO_MAP.md', concurrency: 'shared' },
+    { type: 'read', mode: 'read', path: 'REPO_FLOW.md', concurrency: 'shared' },
     { type: 'read', mode: 'read', path: '.mustflow/config/manifest.lock.toml', concurrency: 'shared' },
     {
         type: 'read',

package/dist/cli/lib/command-registry.js

@@ -122,6 +122,13 @@ export const COMMAND_DEFINITIONS = [
         contract: commandContract(TEXT_OUTPUT),
         loadRunner: async () => (await import('../commands/map.js')).runMap,
     },
+    {
+        id: 'flow',
+        usage: 'mf flow',
+        summaryKey: 'command.flow.summary',
+        contract: commandContract(TEXT_OUTPUT),
+        loadRunner: async () => (await import('../commands/flow.js')).runFlow,
+    },
     {
         id: 'line-endings',
         usage: 'mf line-endings',

package/dist/cli/lib/repo-flow-frontmatter.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+const REPO_FLOW_DOC_ID = 'repo-flow';
+const REPO_FLOW_LIFECYCLE = 'generated';
+const REPO_FLOW_GENERATOR = 'mustflow';
+const REPO_FLOW_RELATIVE_ROOT = '.';
+const REPO_FLOW_SOURCE_POLICY = 'flow_contract';
+const REPO_FLOW_PRIVACY_MODE = 'minimal';
+export function getRepoFlowSourceFingerprint(input) {
+    const payload = {
+        presentInputs: [...input.presentInputs].sort(),
+        configuredCommandIntents: [...input.configuredCommandIntents].sort(),
+        configuredReadOrder: [...input.configuredReadOrder].sort(),
+        configuredOptionalReadOrder: [...input.configuredOptionalReadOrder].sort(),
+        generatedDocuments: [...input.generatedDocuments].sort(),
+        flowIds: [...input.flowIds].sort(),
+    };
+    const digest = createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+    return `sha256:${digest}`;
+}
+export function renderRepoFlowFrontmatter(flowCount, sourceFingerprint) {
+    return [
+        '---',
+        `mustflow_doc: ${REPO_FLOW_DOC_ID}`,
+        `lifecycle: ${REPO_FLOW_LIFECYCLE}`,
+        `generated_by: ${REPO_FLOW_GENERATOR}`,
+        `relative_root: "${REPO_FLOW_RELATIVE_ROOT}"`,
+        `source_policy: ${REPO_FLOW_SOURCE_POLICY}`,
+        `privacy_mode: ${REPO_FLOW_PRIVACY_MODE}`,
+        `flow_count: ${flowCount}`,
+        'degraded: false',
+        `source_fingerprint: "${sourceFingerprint}"`,
+        '---',
+        '',
+    ];
+}