mustflow 2.103.22 → 2.103.31

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

@@ -0,0 +1,209 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { writeUtf8FileInsideWithoutSymlinks } from '../../core/safe-filesystem.js';
+import { isRecord } from './command-contract.js';
+import { getRepoFlowSourceFingerprint, renderRepoFlowFrontmatter, } from './repo-flow-frontmatter.js';
+import { readMustflowTomlFile } from './toml.js';
+const REPO_FLOW_PATH = 'REPO_FLOW.md';
+const FLOW_IDS = [
+    'working-agreement',
+    'agent-task',
+    'command-execution',
+    'generated-evidence',
+    'contract-surfaces',
+    'edit-first',
+];
+const INPUT_PATHS = [
+    'AGENTS.md',
+    '.mustflow/docs/agent-workflow.md',
+    '.mustflow/config/mustflow.toml',
+    '.mustflow/config/commands.toml',
+    '.mustflow/config/preferences.toml',
+    '.mustflow/skills/router.toml',
+    '.mustflow/skills/routes.toml',
+    '.mustflow/skills/INDEX.md',
+    'README.md',
+    'REPO_MAP.md',
+];
+function getStringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+}
+function readTomlObject(projectRoot, relativePath) {
+    try {
+        const parsed = readMustflowTomlFile(projectRoot, relativePath);
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function readMustflowConfig(projectRoot) {
+    const configPath = path.join(projectRoot, '.mustflow', 'config', 'mustflow.toml');
+    return existsSync(configPath) ? readTomlObject(projectRoot, '.mustflow/config/mustflow.toml') : {};
+}
+function readCommandsConfig(projectRoot) {
+    const configPath = path.join(projectRoot, '.mustflow', 'config', 'commands.toml');
+    return existsSync(configPath) ? readTomlObject(projectRoot, '.mustflow/config/commands.toml') : {};
+}
+function getPresentInputs(projectRoot) {
+    return INPUT_PATHS.filter((relativePath) => existsSync(path.join(projectRoot, ...relativePath.split('/'))));
+}
+function getConfiguredCommandIntents(commandsConfig) {
+    return isRecord(commandsConfig.intents) ? Object.keys(commandsConfig.intents).sort() : [];
+}
+function getGeneratedDocuments(mustflowConfig) {
+    const documentRoots = isRecord(mustflowConfig.document_roots) ? mustflowConfig.document_roots : {};
+    return getStringArray(documentRoots.generated);
+}
+function createRepoFlowRenderModel(projectRoot) {
+    const mustflowConfig = readMustflowConfig(projectRoot);
+    const commandsConfig = readCommandsConfig(projectRoot);
+    const presentInputs = getPresentInputs(projectRoot);
+    const configuredCommandIntents = getConfiguredCommandIntents(commandsConfig);
+    const configuredReadOrder = getStringArray(mustflowConfig.read_order);
+    const configuredOptionalReadOrder = getStringArray(mustflowConfig.optional_read_order);
+    const generatedDocuments = getGeneratedDocuments(mustflowConfig);
+    const flowIds = [...FLOW_IDS];
+    const sourceFingerprint = getRepoFlowSourceFingerprint({
+        presentInputs,
+        configuredCommandIntents,
+        configuredReadOrder,
+        configuredOptionalReadOrder,
+        generatedDocuments,
+        flowIds,
+    });
+    return {
+        presentInputs,
+        configuredCommandIntents,
+        configuredReadOrder,
+        configuredOptionalReadOrder,
+        generatedDocuments,
+        flowIds,
+        sourceFingerprint,
+    };
+}
+function renderList(values, fallback) {
+    return values.length > 0 ? values.map((value) => `- \`${value}\``) : [fallback];
+}
+function renderCommandIntentSummary(intentNames) {
+    const notableIntents = [
+        'mustflow_doctor',
+        'mustflow_check',
+        'lint',
+        'build',
+        'test_related',
+        'docs_validate_fast',
+        'test_release',
+        'repo_map',
+        'repo_flow',
+        'changes_status',
+        'changes_diff_summary',
+    ].filter((intentName) => intentNames.includes(intentName));
+    return renderList(notableIntents, 'No configured command intents were discovered.');
+}
+export function getExpectedRepoFlowSourceFingerprint(projectRoot) {
+    return createRepoFlowRenderModel(projectRoot).sourceFingerprint;
+}
+export function generateRepoFlow(projectRoot) {
+    const model = createRepoFlowRenderModel(projectRoot);
+    return [
+        ...renderRepoFlowFrontmatter(model.flowIds.length, model.sourceFingerprint),
+        '# REPO_FLOW.md',
+        '',
+        'This file is a generated design-flow map for the current mustflow root. It is not command authority, architecture authority, or a replacement for `AGENTS.md`, `.mustflow/config/commands.toml`, or current source files.',
+        'Regenerate it with `mf flow --write` instead of editing it by hand.',
+        '',
+        '## How To Use',
+        '',
+        '- Use this file to understand how work moves through the repository before choosing where to read or edit.',
+        '- Use `REPO_MAP.md` for file and anchor discovery.',
+        '- Use `AGENTS.md` and `.mustflow/config/commands.toml` for binding workflow and command execution rules.',
+        '- Use current source, tests, and docs as the source of truth for implementation details.',
+        '',
+        '## One-Screen Mental Model',
+        '',
+        '```mermaid',
+        'flowchart TD',
+        '  UserTask["User task"] --> Rules["AGENTS.md and workflow policy"]',
+        '  Rules --> Skills["Skill selection"]',
+        '  Skills --> Files["Current source, tests, docs"]',
+        '  Files --> Change["Scoped change"]',
+        '  Change --> Verify["Configured mf run intents"]',
+        '  Verify --> Evidence["Run receipts and final report"]',
+        '```',
+        '',
+        '## Agent Work Flow',
+        '',
+        '```mermaid',
+        'flowchart LR',
+        '  A["Read AGENTS.md"] --> B["Read workflow and config"]',
+        '  B --> C["Select matching skill"]',
+        '  C --> D["Read task source files"]',
+        '  D --> E["Edit the narrowest safe scope"]',
+        '  E --> F["Verify with configured intents"]',
+        '```',
+        '',
+        '### Read Order Inputs',
+        '',
+        ...renderList(model.configuredReadOrder, 'No read_order entries were found in `.mustflow/config/mustflow.toml`.'),
+        '',
+        '### Optional Navigation Inputs',
+        '',
+        ...renderList(model.configuredOptionalReadOrder, 'No optional_read_order entries were found in `.mustflow/config/mustflow.toml`.'),
+        '',
+        '## Command Execution Flow',
+        '',
+        '```mermaid',
+        'flowchart TD',
+        '  Need["Need verification or generation"] --> Contract[".mustflow/config/commands.toml"]',
+        '  Contract --> Eligible["configured + oneshot + agent_allowed"]',
+        '  Eligible --> Run["mf run <intent>"]',
+        '  Run --> Receipt[".mustflow/state/runs/ receipt"]',
+        '```',
+        '',
+        '### Notable Configured Intents',
+        '',
+        ...renderCommandIntentSummary(model.configuredCommandIntents),
+        '',
+        '## Generated and Receipt Flow',
+        '',
+        '```mermaid',
+        'flowchart LR',
+        '  Source["Current repository inputs"] --> Map["REPO_MAP.md"]',
+        '  Source --> Flow["REPO_FLOW.md"]',
+        '  Commands["mf run intents"] --> Receipts[".mustflow/state/runs/"]',
+        '  Map --> Check["mf check --strict"]',
+        '  Flow --> Check',
+        '  Receipts --> Evidence["Evidence review"]',
+        '```',
+        '',
+        '### Generated Surfaces',
+        '',
+        ...renderList(model.generatedDocuments, 'No generated document roots were declared.'),
+        '',
+        '## Public Contract Surfaces',
+        '',
+        '- CLI commands and options live in `src/cli/commands/` and `src/cli/lib/command-registry.ts`.',
+        '- Human-readable CLI strings live in `src/cli/i18n/`.',
+        '- Strict workflow validation lives in `src/cli/lib/validation/`.',
+        '- User-facing command docs live in `docs-site/src/content/docs/*/commands/`.',
+        '- File-role docs live in `docs-site/src/content/docs/*/files/`.',
+        '- Release-sensitive package metadata starts at `package.json`.',
+        '',
+        '## Where To Edit First',
+        '',
+        '- CLI behavior: start at the matching file under `src/cli/commands/`, then sync registry, i18n, tests, and docs.',
+        '- Generated Markdown: start at the generator under `src/cli/lib/`, then sync strict validation and file-role docs.',
+        '- Command authority: start at `.mustflow/config/commands.toml`, then sync docs and command-contract tests.',
+        '- Workflow or skill behavior: start at `.mustflow/skills/router.toml` or the matching `SKILL.md`, then sync route metadata and validation.',
+        '- Release metadata: locate version sources before editing version files.',
+        '',
+        '## Present Flow Inputs',
+        '',
+        ...renderList(model.presentInputs, 'No flow input files were found.'),
+        '',
+    ].join('\n');
+}
+export function writeRepoFlow(projectRoot, content) {
+    writeUtf8FileInsideWithoutSymlinks(projectRoot, path.join(projectRoot, REPO_FLOW_PATH), content);
+}

package/dist/cli/lib/repo-map.js

@@ -23,6 +23,7 @@ const EXCLUDED_PREFIXES = ['.mustflow/backups/'];
 const GENERATED_FILES = new Set(['REPO_MAP.md']);
 const DEFAULT_PRIORITY_PATHS = [
     'AGENTS.md',
+    'REPO_FLOW.md',
     '.mustflow/docs/agent-workflow.md',
     '.mustflow/config/mustflow.toml',
     '.mustflow/config/commands.toml',
@@ -76,6 +77,7 @@ const MACHINE_CONTRACT_ANCHOR_FILE_SET = new Set(MACHINE_CONTRACT_ANCHOR_FILES);
 const DEFAULT_NESTED_ANCHOR_FILES = [
     'AGENTS.md',
     'REPO_MAP.md',
+    'REPO_FLOW.md',
     '.gitattributes',
     '.editorconfig',
     '.mustflow/config/mustflow.toml',
@@ -131,6 +133,7 @@ const NESTED_ROOT_DOC_LABELS = new Map([
 ]);
 const EXACT_ANCHOR_DESCRIPTIONS = new Map([
     ['AGENTS.md', 'Root agent operating rules. Read this before changing files.'],
+    ['REPO_FLOW.md', 'Generated design-flow map. Use it to understand how work moves through the root.'],
     ['.gitattributes', 'Git text, binary, and line-ending policy. Check before normalizing files.'],
     ['.editorconfig', 'Editor formatting defaults such as indentation, charset, and final newline.'],
     ['README.md', 'Human-facing project overview. Use it as context, not as agent policy.'],

package/dist/cli/lib/run-plan.js

@@ -11,6 +11,7 @@ import { checkRepoApprovalGate } from '../../core/repo-approval-gate.js';
 import { normalizeSuccessExitCodes } from '../../core/success-exit-codes.js';
 import { normalizeSafeTestTargetPath, TEST_TARGET_PATH_ERROR } from '../../core/test-target-paths.js';
 import { evaluateCommandPreconditions, } from '../../core/command-preconditions.js';
+import { isWindowsCommandScriptPath } from '../commands/run/windows-command-script.js';
 import { t } from './i18n.js';
 function getSuccessExitCodes(intent) {
     return normalizeSuccessExitCodes(intent.success_exit_codes);
@@ -47,8 +48,8 @@ function normalizeTestTargets(values) {
 function commandAcceptsTestTargets(intent) {
     return isRecord(intent.selection) && intent.selection.accepts_test_targets === true;
 }
-function shouldUseShellForArgvExecutable(executablePath) {
-    return process.platform === 'win32' && executablePath.toLowerCase().endsWith('.cmd');
+function isResolvedWindowsCommandScript(executablePath) {
+    return process.platform === 'win32' && isWindowsCommandScriptPath(executablePath);
 }
 export function isMustflowBuiltinIntent(intent) {
     return readString(intent, 'kind') === 'mustflow_builtin';
@@ -66,6 +67,7 @@ function resolveArgvCommand(projectRoot, contract, intent, commandArgv) {
                 executable: process.execPath,
                 args: [entrypoint, ...args],
                 shell: false,
+                windowsCommandScript: false,
             };
         }
     }
@@ -74,13 +76,15 @@ function resolveArgvCommand(projectRoot, contract, intent, commandArgv) {
         return {
             executable: localBinExecutable,
             args,
-            shell: shouldUseShellForArgvExecutable(localBinExecutable),
+            shell: false,
+            windowsCommandScript: isResolvedWindowsCommandScript(localBinExecutable),
         };
     }
     return {
         executable: command,
         args,
-        shell: shouldUseShellForArgvExecutable(command),
+        shell: false,
+        windowsCommandScript: isResolvedWindowsCommandScript(command),
     };
 }
 function getRunPlanMode(commandArgv, intent) {

package/dist/cli/lib/validation/constants.js

@@ -203,6 +203,14 @@ export const REPO_MAP_PRIVACY_MODE = 'minimal';
 export const REPO_MAP_SOURCE_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/u;
 export const ALLOWED_REPO_MAP_DEGRADED_VALUES = new Set(['true', 'false']);
 export const ALLOWED_REPO_MAP_GIT_LS_FILES_STATUSES = new Set(['ok', 'timeout', 'max_buffer', 'error']);
+export const REPO_FLOW_DOC_ID = 'repo-flow';
+export const REPO_FLOW_LIFECYCLE = 'generated';
+export const REPO_FLOW_GENERATOR = 'mustflow';
+export const REPO_FLOW_RELATIVE_ROOT = '.';
+export const REPO_FLOW_SOURCE_POLICY = 'flow_contract';
+export const REPO_FLOW_PRIVACY_MODE = 'minimal';
+export const REPO_FLOW_SOURCE_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+export const ALLOWED_REPO_FLOW_DEGRADED_VALUES = new Set(['true', 'false']);
 export const SKILL_RESOURCE_MANIFEST = 'resources.toml';
 export const SKILL_RESOURCE_ROOTS = new Set(['references', 'assets', 'scripts']);
 export const ALLOWED_SKILL_RESOURCE_TYPES = new Set(['reference', 'asset', 'script']);
@@ -226,6 +234,8 @@ export const REPO_MAP_REMOTE_OR_BRANCH_PATTERNS = [
     /\bgit@/iu,
     /^\s*(?:Remote|Branch):/imu,
 ];
+export const VOLATILE_REPO_FLOW_PATTERNS = VOLATILE_REPO_MAP_PATTERNS;
+export const REPO_FLOW_REMOTE_OR_BRANCH_PATTERNS = REPO_MAP_REMOTE_OR_BRANCH_PATTERNS;
 export const LOCAL_ABSOLUTE_PATH_PATTERNS = [
     /\b[A-Za-z]:\\(?:Users|Documents and Settings)\\/iu,
     /(?:^|[\s"'(])\/(?:Users|home)\/[A-Za-z0-9._-]+\/[^\s)"']*/imu,

package/dist/cli/lib/validation/index.js

@@ -11,6 +11,7 @@ import { validateSourceAnchorsInProject } from '../../../core/source-anchor-vali
 import { listFilesRecursive, toPosixPath } from '../filesystem.js';
 import { readGitChangedFiles } from '../git-changes.js';
 import { inspectManifestLock } from '../manifest-lock.js';
+import { getExpectedRepoFlowSourceFingerprint } from '../repo-flow.js';
 import { getExpectedRepoMapSourceFingerprint } from '../repo-map.js';
 import { parseTomlText, readMustflowTomlFile } from '../toml.js';
 import { MUSTFLOW_JSON_MAX_BYTES } from '../mustflow-read.js';
@@ -19,7 +20,7 @@ import { VERSIONING_CONFIG_PATH, detectVersionSourcePaths, readDeclaredVersionSo
 import { normalizeTechnologyPreferencesTable, TECHNOLOGY_CONFIG_RELATIVE_PATH, } from '../../../core/technology-preferences.js';
 import { isPromptCacheStableLeafSkillSurface, measurePromptCacheReferenceBlockBytes, } from '../../../core/prompt-cache-rendering.js';
 import { validateSkillRouteFixtures } from '../../../core/skill-route-fixtures.js';
-import { ALLOWED_APPROVAL_ACTIONS, ALLOWED_APPROVAL_GATES, ALLOWED_BUDGET_LIMIT_ACTIONS, ALLOWED_CAPABILITY_STATES, ALLOWED_COMMIT_MESSAGE_STYLES, ALLOWED_COMPACTION_CATEGORIES, ALLOWED_COMPACTION_LONG_LIMIT_ACTIONS, ALLOWED_COMPACTION_RAW_LIMIT_ACTIONS, ALLOWED_COMPACTION_STATE_STORES, ALLOWED_COMPACTION_STRATEGIES, ALLOWED_CONTEXT_AUTHORITIES, ALLOWED_CONTEXT_DOCUMENT_AUTHORITIES, ALLOWED_CONTEXT_READ_POLICIES, ALLOWED_HANDOFF_MODES, ALLOWED_HARNESS_FRESH_CONTEXT_MODES, ALLOWED_HARNESS_MODES, ALLOWED_HARNESS_PHASES, ALLOWED_ISOLATION_PREFERENCES, ALLOWED_MAP_MODES, ALLOWED_MAP_PRIVACY_LEVELS, ALLOWED_PROJECT_PROFILES, ALLOWED_REPO_MAP_DEGRADED_VALUES, ALLOWED_REPO_MAP_GIT_LS_FILES_STATUSES, ALLOWED_PROMPT_CACHE_STABLE_PREFIX_POLICIES, ALLOWED_PROMPT_CACHE_STRATEGIES, ALLOWED_PROMPT_CACHE_TASK_READ_POLICIES, ALLOWED_REFRESH_CHECKPOINTS, ALLOWED_REFRESH_METHODS, ALLOWED_REFRESH_MODES, ALLOWED_REFRESH_STATE_STORES, ALLOWED_SKILL_RESOURCE_TYPES, ALLOWED_SKILL_ROUTE_CATEGORIES, ALLOWED_SKILL_ROUTE_PROFILES, ALLOWED_SKILL_ROUTE_TYPES, ALLOWED_STALE_TEST_ACTIONS, ALLOWED_TEST_AUTHORING_POLICIES, ALLOWED_TEST_DELETION_REASONS, ALLOWED_TESTING_POLICIES, ALLOWED_TRANSLATION_POLICIES, ALLOWED_VERIFICATION_SELECTION_STRATEGIES, ALLOWED_VERSION_SOURCE_AUTHORITIES, ALLOWED_VERSION_SOURCE_KINDS, CAPABILITY_BOOLEAN_FIELDS, CAPABILITY_STATE_FIELDS, CONTEXT_AUTHORITY_DRIFT_PATTERNS, DESIGN_TOKEN_DEFINITION_PATTERNS, FORBIDDEN_RELEASE_VERSIONING_CONTRACT_FIELDS, FORBIDDEN_TEST_DELETION_REASONS, FORBIDDEN_VERIFICATION_SELECTION_AUTHORITY_FIELDS, LOCAL_ABSOLUTE_PATH_PATTERNS, LOCAL_TASK_STATE_ROOTS, RAW_COMMAND_FENCE_PATTERN, RELEASE_VERSIONING_BOOLEAN_FIELDS, REPO_MAP_DOC_ID, REPO_MAP_GENERATOR, REPO_MAP_LIFECYCLE, REPO_MAP_PRIVACY_MODE, REPO_MAP_RELATIVE_ROOT, REPO_MAP_REMOTE_OR_BRANCH_PATTERNS, REPO_MAP_SOURCE_FINGERPRINT_PATTERN, REPO_MAP_SOURCE_POLICY, REQUIRED_AGENT_LOOP_PHASES, REQUIRED_SKILL_SCRIPT_RUN_POLICY, REQUIRED_SKILL_SECTION_IDS, ROUTER_INDEX_FILES, ROUTER_INDEX_PROCEDURE_SECTION_PATTERN, SECRET_LIKE_CONTEXT_PATTERNS, SKILL_COMMAND_PERMISSION_CLAIM_PATTERNS, SKILL_INDEX_PATH, SKILL_PACK_ID_PATTERN, SKILL_RESOURCE_MANIFEST, SKILL_RESOURCE_ROOTS, SKILL_RESOURCE_TYPE_BY_ROOT, SKILL_ROUTE_CATEGORY_LABELS, SKILL_ROUTES_METADATA_PATH, SUPPORTED_SKILL_SCHEMA_VERSION, TEST_AUTHORING_BOOLEAN_FIELDS, VERIFICATION_SELECTION_BOOLEAN_FIELDS, VOLATILE_REPO_MAP_PATTERNS } from './constants.js';
+import { ALLOWED_APPROVAL_ACTIONS, ALLOWED_APPROVAL_GATES, ALLOWED_BUDGET_LIMIT_ACTIONS, ALLOWED_CAPABILITY_STATES, ALLOWED_COMMIT_MESSAGE_STYLES, ALLOWED_COMPACTION_CATEGORIES, ALLOWED_COMPACTION_LONG_LIMIT_ACTIONS, ALLOWED_COMPACTION_RAW_LIMIT_ACTIONS, ALLOWED_COMPACTION_STATE_STORES, ALLOWED_COMPACTION_STRATEGIES, ALLOWED_CONTEXT_AUTHORITIES, ALLOWED_CONTEXT_DOCUMENT_AUTHORITIES, ALLOWED_CONTEXT_READ_POLICIES, ALLOWED_HANDOFF_MODES, ALLOWED_HARNESS_FRESH_CONTEXT_MODES, ALLOWED_HARNESS_MODES, ALLOWED_HARNESS_PHASES, ALLOWED_ISOLATION_PREFERENCES, ALLOWED_MAP_MODES, ALLOWED_MAP_PRIVACY_LEVELS, ALLOWED_PROJECT_PROFILES, ALLOWED_REPO_MAP_DEGRADED_VALUES, ALLOWED_REPO_MAP_GIT_LS_FILES_STATUSES, ALLOWED_REPO_FLOW_DEGRADED_VALUES, ALLOWED_PROMPT_CACHE_STABLE_PREFIX_POLICIES, ALLOWED_PROMPT_CACHE_STRATEGIES, ALLOWED_PROMPT_CACHE_TASK_READ_POLICIES, ALLOWED_REFRESH_CHECKPOINTS, ALLOWED_REFRESH_METHODS, ALLOWED_REFRESH_MODES, ALLOWED_REFRESH_STATE_STORES, ALLOWED_SKILL_RESOURCE_TYPES, ALLOWED_SKILL_ROUTE_CATEGORIES, ALLOWED_SKILL_ROUTE_PROFILES, ALLOWED_SKILL_ROUTE_TYPES, ALLOWED_STALE_TEST_ACTIONS, ALLOWED_TEST_AUTHORING_POLICIES, ALLOWED_TEST_DELETION_REASONS, ALLOWED_TESTING_POLICIES, ALLOWED_TRANSLATION_POLICIES, ALLOWED_VERIFICATION_SELECTION_STRATEGIES, ALLOWED_VERSION_SOURCE_AUTHORITIES, ALLOWED_VERSION_SOURCE_KINDS, CAPABILITY_BOOLEAN_FIELDS, CAPABILITY_STATE_FIELDS, CONTEXT_AUTHORITY_DRIFT_PATTERNS, DESIGN_TOKEN_DEFINITION_PATTERNS, FORBIDDEN_RELEASE_VERSIONING_CONTRACT_FIELDS, FORBIDDEN_TEST_DELETION_REASONS, FORBIDDEN_VERIFICATION_SELECTION_AUTHORITY_FIELDS, LOCAL_ABSOLUTE_PATH_PATTERNS, LOCAL_TASK_STATE_ROOTS, RAW_COMMAND_FENCE_PATTERN, RELEASE_VERSIONING_BOOLEAN_FIELDS, REPO_MAP_DOC_ID, REPO_MAP_GENERATOR, REPO_MAP_LIFECYCLE, REPO_MAP_PRIVACY_MODE, REPO_MAP_RELATIVE_ROOT, REPO_MAP_REMOTE_OR_BRANCH_PATTERNS, REPO_MAP_SOURCE_FINGERPRINT_PATTERN, REPO_MAP_SOURCE_POLICY, REPO_FLOW_DOC_ID, REPO_FLOW_GENERATOR, REPO_FLOW_LIFECYCLE, REPO_FLOW_PRIVACY_MODE, REPO_FLOW_RELATIVE_ROOT, REPO_FLOW_REMOTE_OR_BRANCH_PATTERNS, REPO_FLOW_SOURCE_FINGERPRINT_PATTERN, REPO_FLOW_SOURCE_POLICY, REQUIRED_AGENT_LOOP_PHASES, REQUIRED_SKILL_SCRIPT_RUN_POLICY, REQUIRED_SKILL_SECTION_IDS, ROUTER_INDEX_FILES, ROUTER_INDEX_PROCEDURE_SECTION_PATTERN, SECRET_LIKE_CONTEXT_PATTERNS, SKILL_COMMAND_PERMISSION_CLAIM_PATTERNS, SKILL_INDEX_PATH, SKILL_PACK_ID_PATTERN, SKILL_RESOURCE_MANIFEST, SKILL_RESOURCE_ROOTS, SKILL_RESOURCE_TYPE_BY_ROOT, SKILL_ROUTE_CATEGORY_LABELS, SKILL_ROUTES_METADATA_PATH, SUPPORTED_SKILL_SCHEMA_VERSION, TEST_AUTHORING_BOOLEAN_FIELDS, VERIFICATION_SELECTION_BOOLEAN_FIELDS, VOLATILE_REPO_FLOW_PATTERNS, VOLATILE_REPO_MAP_PATTERNS } from './constants.js';
 import { hasOwn, isPositiveInteger, isSafeRelativePath, pushStrictIssue, pushStrictWarning, validateAllowedStringField, validateBooleanField, validateExactStringArrayField, validateNestedTable, validatePathArrayField, validatePathField, validatePositiveIntegerField, validateRequiredFiles, validateRequiredPathField, validateRequiredStringField, validateStringArrayField, validateStringArrayMembers, validateStringField, validateTable, validateToml, validateWorkspaceRoots } from './primitives.js';
 import { isConfiguredCommandIntent, isDeclaredCommandIntent } from './command-intents.js';
 import { parseSimpleFrontmatter, readFrontmatterList, readSkillSectionIds } from './frontmatter.js';
@@ -1476,6 +1477,57 @@ function validateStrictRepoMap(projectRoot, issues) {
         pushStrictIssue(issues, 'REPO_MAP.md contains remote URL or branch metadata');
     }
 }
+function validateStrictRepoFlow(projectRoot, issues) {
+    const repoFlowPath = path.join(projectRoot, 'REPO_FLOW.md');
+    if (!existsSync(repoFlowPath)) {
+        return;
+    }
+    const content = readStrictMustflowText(projectRoot, 'REPO_FLOW.md', issues);
+    if (content === undefined) {
+        return;
+    }
+    const frontmatter = parseSimpleFrontmatter(content);
+    if (frontmatter.mustflow_doc !== REPO_FLOW_DOC_ID) {
+        pushStrictIssue(issues, `REPO_FLOW.md frontmatter mustflow_doc must be "${REPO_FLOW_DOC_ID}"`);
+    }
+    if (frontmatter.lifecycle !== REPO_FLOW_LIFECYCLE) {
+        pushStrictIssue(issues, `REPO_FLOW.md frontmatter lifecycle must be "${REPO_FLOW_LIFECYCLE}"`);
+    }
+    if (frontmatter.generated_by !== REPO_FLOW_GENERATOR) {
+        pushStrictIssue(issues, `REPO_FLOW.md frontmatter generated_by must be "${REPO_FLOW_GENERATOR}"`);
+    }
+    if (frontmatter.relative_root !== REPO_FLOW_RELATIVE_ROOT) {
+        pushStrictIssue(issues, `REPO_FLOW.md frontmatter relative_root must be "${REPO_FLOW_RELATIVE_ROOT}"`);
+    }
+    if (frontmatter.source_policy !== REPO_FLOW_SOURCE_POLICY) {
+        pushStrictIssue(issues, `REPO_FLOW.md frontmatter source_policy must be "${REPO_FLOW_SOURCE_POLICY}"`);
+    }
+    if (frontmatter.privacy_mode !== REPO_FLOW_PRIVACY_MODE) {
+        pushStrictIssue(issues, `REPO_FLOW.md frontmatter privacy_mode must be "${REPO_FLOW_PRIVACY_MODE}"`);
+    }
+    if (!/^[1-9]\d*$/u.test(frontmatter.flow_count ?? '')) {
+        pushStrictIssue(issues, 'REPO_FLOW.md frontmatter flow_count must be a positive integer');
+    }
+    if (!ALLOWED_REPO_FLOW_DEGRADED_VALUES.has(frontmatter.degraded ?? '')) {
+        pushStrictIssue(issues, 'REPO_FLOW.md frontmatter degraded must be true or false');
+    }
+    if (!REPO_FLOW_SOURCE_FINGERPRINT_PATTERN.test(frontmatter.source_fingerprint ?? '')) {
+        pushStrictIssue(issues, 'REPO_FLOW.md frontmatter source_fingerprint must be sha256:<64 lowercase hex characters>');
+    }
+    else {
+        const currentSourceFingerprint = frontmatter.source_fingerprint;
+        const expectedSourceFingerprint = getExpectedRepoFlowSourceFingerprint(projectRoot);
+        if (expectedSourceFingerprint && currentSourceFingerprint !== expectedSourceFingerprint) {
+            pushStrictIssue(issues, 'REPO_FLOW.md source_fingerprint is stale; regenerate with mf flow --write');
+        }
+    }
+    if (VOLATILE_REPO_FLOW_PATTERNS.some((pattern) => pattern.test(content))) {
+        pushStrictIssue(issues, 'REPO_FLOW.md contains volatile generated metadata');
+    }
+    if (REPO_FLOW_REMOTE_OR_BRANCH_PATTERNS.some((pattern) => pattern.test(content))) {
+        pushStrictIssue(issues, 'REPO_FLOW.md contains remote URL or branch metadata');
+    }
+}
 function validateStrictContextDocuments(projectRoot, limits, issues) {
     const contextRoot = path.join(projectRoot, '.mustflow', 'context');
     const contextFiles = listFilesRecursive(contextRoot).filter((relativePath) => relativePath.endsWith('.md'));
@@ -1590,6 +1642,7 @@ function validateStrict(projectRoot, parsed, issues) {
     validateStrictSkills(projectRoot, parsed.commandsToml, issues);
     validateStrictTemplateSkillProfiles(issues);
     validateStrictRepoMap(projectRoot, issues);
+    validateStrictRepoFlow(projectRoot, issues);
     validateStrictContextDocuments(projectRoot, retentionLimits, issues);
     validateStrictSourceAnchors(projectRoot, issues);
     validateStrictRunReceipt(projectRoot, issues);

package/dist/core/generated-boundary.js

@@ -8,6 +8,7 @@ export const GENERATED_BOUNDARY_SCRIPT_ID = 'generated-boundary';
 export const GENERATED_BOUNDARY_SCRIPT_REF = `${GENERATED_BOUNDARY_PACK_ID}/${GENERATED_BOUNDARY_SCRIPT_ID}`;
 const BUILTIN_GENERATED_PATTERNS = [
     'REPO_MAP.md',
+    'REPO_FLOW.md',
     '.mustflow/config/manifest.lock.toml',
     '.mustflow/state/**',
     '.mustflow/cache/**',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.103.22",
+  "version": "2.103.31",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",
@@ -70,6 +70,7 @@
     "llm",
     "codex",
     "mustflow",
+    "repo-flow",
     "repo-map",
     "repository-template",
     "toml",

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 189
+revision = 197
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -583,7 +583,19 @@ translations = {}
 [documents."skill.astro-code-change"]
 source = "locales/en/.mustflow/skills/astro-code-change/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 5
+translations = {}
+
+[documents."skill.axum-code-change"]
+source = "locales/en/.mustflow/skills/axum-code-change/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
+[documents."skill.babylon-code-change"]
+source = "locales/en/.mustflow/skills/babylon-code-change/SKILL.md"
+source_locale = "en"
+revision = 1
 translations = {}
 
 [documents."skill.auth-permission-change"]
@@ -613,7 +625,7 @@ translations = {}
 [documents."skill.bun-code-change"]
 source = "locales/en/.mustflow/skills/bun-code-change/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.cpp-code-change"]
@@ -643,7 +655,7 @@ translations = {}
 [documents."skill.elysia-code-change"]
 source = "locales/en/.mustflow/skills/elysia-code-change/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.flutter-code-change"]
@@ -658,10 +670,16 @@ source_locale = "en"
 revision = 4
 translations = {}
 
+[documents."skill.godot-code-change"]
+source = "locales/en/.mustflow/skills/godot-code-change/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.hono-code-change"]
 source = "locales/en/.mustflow/skills/hono-code-change/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.html-code-change"]
@@ -688,6 +706,12 @@ source_locale = "en"
 revision = 2
 translations = {}
 
+[documents."skill.vue-code-change"]
+source = "locales/en/.mustflow/skills/vue-code-change/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.python-code-change"]
 source = "locales/en/.mustflow/skills/python-code-change/SKILL.md"
 source_locale = "en"
@@ -739,7 +763,7 @@ translations = {}
 [documents."skill.svelte-code-change"]
 source = "locales/en/.mustflow/skills/svelte-code-change/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.tailwind-code-change"]