mustflow 2.115.15 → 2.115.16

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

@@ -2,8 +2,8 @@ import { renderHelp } from '../../lib/cli-output.js';
 import { t } from '../../lib/i18n.js';
 import { getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../../lib/option-parser.js';
 import { ALLOW_UNTRUSTED_ROOT_OPTION } from '../../lib/run-root-trust.js';
+import { APPROVAL_ACTION_TYPE_SET, APPROVAL_ACTION_TYPES } from '../../../core/approval-actions.js';
 const DEFAULT_ACTIVE_LOCK_WAIT_TIMEOUT_SECONDS = 300;
-const SUPPORTED_RUN_APPROVAL_ACTIONS = new Set(['network_access', 'destructive_command']);
 const RUN_OPTIONS = [
     { name: '--json', kind: 'boolean' },
     { name: '--dry-run', kind: 'boolean' },
@@ -17,7 +17,7 @@ export function hasRunHelpOption(args) {
     return hasCliOptionToken(args, '--help', ['-h']);
 }
 export function getSupportedRunApprovalActions() {
-    return [...SUPPORTED_RUN_APPROVAL_ACTIONS].sort((left, right) => left.localeCompare(right));
+    return [...APPROVAL_ACTION_TYPES].sort((left, right) => left.localeCompare(right));
 }
 function getAllowApprovalValues(parsed) {
     const values = parsed.occurrences
@@ -27,7 +27,7 @@ function getAllowApprovalValues(parsed) {
     return [...new Set(values)];
 }
 function findInvalidApprovalAction(values) {
-    return values.find((value) => !SUPPORTED_RUN_APPROVAL_ACTIONS.has(value)) ?? null;
+    return values.find((value) => !APPROVAL_ACTION_TYPE_SET.has(value)) ?? null;
 }
 export function parseRunArguments(args) {
     const parsed = parseCliOptions(args, RUN_OPTIONS, { allowPositionals: true });
@@ -93,7 +93,11 @@ export function getRunHelp(lang = 'en') {
             { label: ALLOW_UNTRUSTED_ROOT_OPTION, description: t(lang, 'run.help.option.allowUntrustedRoot') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
-        examples: ['mf run test', 'mf run lint --json', 'mf run release_npm_version_available --allow-approval network_access --json'],
+        examples: [
+            'mf run test',
+            'mf run lint --json',
+            'mf run release_npm_publish --allow-approval release --allow-approval network_access --json',
+        ],
         exitCodes: [
             {
                 label: '0',

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

@@ -72,6 +72,7 @@ function reportRunPlanFailure(plan, reporter, lang) {
             break;
         case 'network_requires_approval':
         case 'destructive_requires_approval':
+        case 'explicit_approval_required':
         case 'approval_policy_unreadable':
             message = t(lang, 'run.error.approvalRequired', {
                 intent: plan.intentName,

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

@@ -10,7 +10,10 @@ export function executeRunPreviewCommand(input, reporter, lang, options) {
     const profiler = new RunProfiler();
     const projectRoot = profiler.measure('root_detection', () => resolveMustflowRoot());
     const contract = profiler.measure('command_contract', () => readCommandContract(projectRoot));
-    const plan = profiler.measure('plan_creation', () => createRunPlan(projectRoot, contract, input.intentName, { testTargets: options.testTargets }));
+    const plan = profiler.measure('plan_creation', () => createRunPlan(projectRoot, contract, input.intentName, {
+        testTargets: options.testTargets,
+        approvedActions: input.allowApprovals,
+    }));
     profiler.measure('preview_render', () => {
         if (input.json) {
             reporter.stdout(JSON.stringify(createRunPreview(plan, input.previewMode), null, 2));

package/dist/cli/commands/run.js

@@ -72,5 +72,5 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         }, reporter, lang, options);
         return result.exitCode;
     }
-    return executeRunPreviewCommand({ intentName, json, previewMode }, reporter, lang, options);
+    return executeRunPreviewCommand({ intentName, json, previewMode, allowApprovals: parsedArgs.allowApprovals }, reporter, lang, options);
 }

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

@@ -123,6 +123,7 @@ function readRunIntentMetadata(contract, intent) {
         effects: readArray(intent, 'effects'),
         network: readBoolean(intent, 'network'),
         destructive: readBoolean(intent, 'destructive'),
+        approvalActions: readStringArray(intent, 'approval_actions') ?? [],
         envPolicy: env.policy,
         envAllowlist: env.allowlist,
         testTargets: [],
@@ -133,17 +134,18 @@ function readRunIntentMetadata(contract, intent) {
     };
 }
 function createApprovalBlock(projectRoot, metadata, approvedActions) {
-    const actionTypes = [];
+    const actionTypes = [...metadata.approvalActions];
     if (metadata.network === true) {
         actionTypes.push('network_access');
     }
     if (metadata.destructive === true) {
         actionTypes.push('destructive_command');
     }
-    if (actionTypes.length === 0) {
+    const uniqueActionTypes = [...new Set(actionTypes)];
+    if (uniqueActionTypes.length === 0) {
         return null;
     }
-    const approvalReport = checkRepoApprovalGate(projectRoot, actionTypes);
+    const approvalReport = checkRepoApprovalGate(projectRoot, uniqueActionTypes);
     if (approvalReport.issues.length > 0) {
         return {
             reasonCode: 'approval_policy_unreadable',
@@ -159,7 +161,9 @@ function createApprovalBlock(projectRoot, metadata, approvedActions) {
     }
     const reasonCode = missingActions.includes('destructive_command')
         ? 'destructive_requires_approval'
-        : 'network_requires_approval';
+        : missingActions.includes('network_access')
+            ? 'network_requires_approval'
+            : 'explicit_approval_required';
     return {
         reasonCode,
         detail: `Action ${missingActions.map((action) => JSON.stringify(action)).join(', ')} requires explicit approval before mf run can execute this intent.`,
@@ -193,6 +197,7 @@ function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonC
         effects: metadata?.effects,
         network: metadata?.network,
         destructive: metadata?.destructive,
+        approvalActions: metadata?.approvalActions ?? [],
         envPolicy: metadata?.envPolicy ?? null,
         envAllowlist: metadata?.envAllowlist ?? [],
         testTargets: [],
@@ -277,6 +282,7 @@ export function createRunPlan(projectRoot, contract, intentName, options = {}) {
         effects: metadata.effects,
         network: metadata.network,
         destructive: metadata.destructive,
+        approvalActions: metadata.approvalActions,
         envPolicy: metadata.envPolicy,
         envAllowlist: metadata.envAllowlist,
         testTargets,
@@ -360,6 +366,7 @@ export function createRunPreview(plan, previewMode) {
         effects: plan.effects,
         network: plan.network,
         destructive: plan.destructive,
+        approval_actions: plan.approvalActions,
         env_policy: plan.envPolicy,
         env_allowlist: plan.envAllowlist,
         test_targets: plan.testTargets,

package/dist/cli/lib/templates.js

@@ -72,6 +72,9 @@ function shouldIncludeTemplatePath(relativePath, selectedSkills) {
     return selectedSkills.includes(skillName);
 }
 const SKILL_INDEX_SKILL_PATH_PATTERN = /`\.mustflow\/skills\/([^/]+)\/SKILL\.md`/u;
+const SKILL_NAME_REFERENCE_PATTERN = /`([a-z][a-z0-9-]+)`/gu;
+const SKILL_PATH_REFERENCE_PATTERN = /`\.mustflow\/skills\/([^/]+)\/SKILL\.md`/gu;
+const UNAVAILABLE_SKILL_REFERENCE_FALLBACK = 'the closest installed route for this scope';
 const SKILL_INDEX_HEADING_PATTERN = /^(#{2,3})\s+(.+?)\s*$/u;
 const SKILL_INDEX_ROUTE_CATEGORY_NAMES = [
     'Bug and Failure',
@@ -190,6 +193,16 @@ function filterSkillIndexContent(content, selectedSkills) {
     }
     return filteredLines.join('\n').replace(/\n{3,}/gu, '\n\n');
 }
+function filterUnavailableSkillReferences(content, selectedSkills, knownSkills) {
+    const selectedSkillSet = new Set(selectedSkills);
+    const knownSkillSet = new Set(knownSkills);
+    const replaceUnavailableReference = (reference, skillName) => knownSkillSet.has(skillName) && !selectedSkillSet.has(skillName)
+        ? UNAVAILABLE_SKILL_REFERENCE_FALLBACK
+        : reference;
+    return content
+        .replace(SKILL_PATH_REFERENCE_PATTERN, replaceUnavailableReference)
+        .replace(SKILL_NAME_REFERENCE_PATTERN, replaceUnavailableReference);
+}
 function filterSkillRouteMetadataContent(content, selectedSkills) {
     const selectedSkillSet = new Set(selectedSkills);
     let keepCurrentRoute = true;
@@ -298,6 +311,7 @@ export function getTemplateFiles(template, locale = template.manifest.defaultLoc
         ? path.join(template.templateRoot, template.manifest.localesRoot, template.manifest.defaultLocale)
         : undefined;
     const selectedSkills = selectedSkillNames(template.manifest, profile, options);
+    const knownSkills = templateSkillNames(template.manifest.creates);
     return template.manifest.creates.filter((relativePath) => shouldIncludeTemplatePath(relativePath, selectedSkills)).map((relativePath) => {
         const localePath = localeRoot ? path.join(localeRoot, ...relativePath.split('/')) : undefined;
         const sourceLocalePath = sourceLocaleRoot ? path.join(sourceLocaleRoot, ...relativePath.split('/')) : undefined;
@@ -306,11 +320,16 @@ export function getTemplateFiles(template, locale = template.manifest.defaultLoc
         const fallbackLocalePath = sourceLocalePath && existsSync(sourceLocalePath) ? sourceLocalePath : undefined;
         const commonSourcePath = existsSync(commonPath) ? commonPath : undefined;
         const selectedSourcePath = localizedPath ?? fallbackLocalePath ?? commonSourcePath;
-        const content = selectedSourcePath && relativePath === '.mustflow/skills/INDEX.md'
+        const selectedContent = selectedSourcePath && relativePath === '.mustflow/skills/INDEX.md'
             ? filterSkillIndexContent(readFileSync(selectedSourcePath, 'utf8'), selectedSkills)
             : selectedSourcePath && relativePath === '.mustflow/skills/routes.toml'
                 ? filterSkillRouteMetadataContent(readFileSync(selectedSourcePath, 'utf8'), selectedSkills)
                 : undefined;
+        const content = selectedSourcePath && relativePath === '.mustflow/skills/INDEX.md'
+            ? filterUnavailableSkillReferences(selectedContent ?? '', selectedSkills, knownSkills)
+            : selectedSourcePath && /^\.mustflow\/skills\/[^/]+\/SKILL\.md$/u.test(relativePath)
+                ? filterUnavailableSkillReferences(readFileSync(selectedSourcePath, 'utf8'), selectedSkills, knownSkills)
+                : selectedContent;
         if (localizedPath) {
             return {
                 relativePath,

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

@@ -130,18 +130,7 @@ export const ALLOWED_PROMPT_CACHE_STRATEGIES = new Set(['stable_prefix']);
 export const ALLOWED_PROMPT_CACHE_STABLE_PREFIX_POLICIES = new Set(['hash_verified']);
 export const ALLOWED_PROMPT_CACHE_TASK_READ_POLICIES = new Set(['task_relevant_only']);
 export const ALLOWED_BUDGET_LIMIT_ACTIONS = new Set(['stop_and_handoff', 'stop_and_report']);
-export const ALLOWED_APPROVAL_GATES = new Set([
-    'git_commit',
-    'git_push',
-    'dependency_install',
-    'dependency_upgrade',
-    'network_access',
-    'database_migration',
-    'destructive_command',
-    'secret_access',
-    'release',
-    'cross_repository_change',
-]);
+export { APPROVAL_ACTION_TYPE_SET as ALLOWED_APPROVAL_GATES } from '../../../core/approval-actions.js';
 export const ALLOWED_APPROVAL_ACTIONS = new Set(['stop_and_request_approval']);
 export const ALLOWED_ISOLATION_PREFERENCES = new Set(['none', 'git_worktree', 'sandbox']);
 export const ALLOWED_REFRESH_MODES = new Set(['checkpoint']);

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

@@ -1066,7 +1066,7 @@ function readSkillRouteMetadataFromTomlContent(content, sourceLabel, issues) {
     }
     return metadata;
 }
-function validateTemplateProfileSkillRoutes(profile, files, issues) {
+function validateTemplateProfileSkillRoutes(profile, files, knownSkillNames, issues) {
     const contentByPath = new Map(files.map((file) => [file.relativePath, templateFileContent(file)]));
     const indexContent = contentByPath.get(SKILL_INDEX_PATH);
     const routesContent = contentByPath.get(SKILL_ROUTES_METADATA_PATH);
@@ -1104,6 +1104,17 @@ function validateTemplateProfileSkillRoutes(profile, files, issues) {
             selectedSkillContents.set(skillName, content);
         }
     }
+    for (const [relativePath, content] of contentByPath.entries()) {
+        if (relativePath !== SKILL_INDEX_PATH && !skillRouteName(relativePath)) {
+            continue;
+        }
+        for (const match of content.matchAll(/`([a-z][a-z0-9-]+)`/gu)) {
+            const referencedSkill = match[1];
+            if (referencedSkill && knownSkillNames.has(referencedSkill) && !selectedSkillContents.has(referencedSkill)) {
+                pushStrictIssue(issues, `template profile "${profile}" ${relativePath} references skill "${referencedSkill}" not installed by that profile`);
+            }
+        }
+    }
     for (const route of skillRoutes) {
         const routeSkillName = skillRouteName(route.skillPath);
         if (!routeSkillName) {
@@ -1178,8 +1189,11 @@ function validateStrictTemplateSkillProfiles(issues) {
         pushStrictIssue(issues, `default template skill profiles could not be loaded: ${message}`);
         return;
     }
+    const knownSkillNames = new Set(template.manifest.creates
+        .map((relativePath) => skillRouteName(relativePath))
+        .filter((skillName) => Boolean(skillName)));
     for (const profile of template.manifest.profiles) {
-        validateTemplateProfileSkillRoutes(profile, getTemplateFiles(template, template.manifest.defaultLocale, profile), issues);
+        validateTemplateProfileSkillRoutes(profile, getTemplateFiles(template, template.manifest.defaultLocale, profile), knownSkillNames, issues);
     }
 }
 function listManagedMarkdownDocuments(projectRoot) {

package/dist/core/approval-actions.js

@@ -0,0 +1,13 @@
+export const APPROVAL_ACTION_TYPES = [
+    'git_commit',
+    'git_push',
+    'dependency_install',
+    'dependency_upgrade',
+    'network_access',
+    'database_migration',
+    'destructive_command',
+    'secret_access',
+    'release',
+    'cross_repository_change',
+];
+export const APPROVAL_ACTION_TYPE_SET = new Set(APPROVAL_ACTION_TYPES);

package/dist/core/command-contract-validation.js

@@ -6,6 +6,7 @@ import { COMMAND_PRECONDITION_KINDS } from './command-preconditions.js';
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
 import { MAX_COMMAND_OUTPUT_BYTES, commandMaxOutputBytesLimitMessage } from './command-output-limits.js';
 import { SUCCESS_EXIT_CODES_CONTRACT_DESCRIPTION, successExitCodesAreValid } from './success-exit-codes.js';
+import { APPROVAL_ACTION_TYPE_SET } from './approval-actions.js';
 const COMMAND_INPUT_TYPES = new Set(['path', 'enum', 'boolean', 'integer', 'literal']);
 const COMMAND_INPUT_NAME_PATTERN = /^[a-z][a-z0-9_]*$/u;
 const COMMAND_ARGV_PLACEHOLDER_PATTERN = /^\{([a-z][a-z0-9_]*)\}$/u;
@@ -59,6 +60,57 @@ function validateStringArrayField(table, key, label, issues) {
         issues.push(commandContractIssue(`${label} must be a string array`));
     }
 }
+function validateApprovalActions(intentName, intent, issues) {
+    validateStringArrayField(intent, 'approval_actions', `[commands.intents.${intentName}].approval_actions`, issues);
+    const approvalActions = readStringArray(intent, 'approval_actions');
+    if (!approvalActions) {
+        return;
+    }
+    const unsupported = [...new Set(approvalActions.filter((action) => !APPROVAL_ACTION_TYPE_SET.has(action)))];
+    if (unsupported.length > 0) {
+        issues.push(commandContractIssue(`[commands.intents.${intentName}].approval_actions contains unsupported action types: ${unsupported.join(', ')}`));
+    }
+}
+function readGitSubcommand(argv) {
+    if (normalizeCommandExecutableName(argv[0] ?? '') !== 'git') {
+        return null;
+    }
+    const optionsWithSeparateValue = new Set(['-C', '-c', '--exec-path', '--git-dir', '--work-tree', '--namespace']);
+    for (let index = 1; index < argv.length; index += 1) {
+        const argument = argv[index] ?? '';
+        if (optionsWithSeparateValue.has(argument)) {
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith('-')) {
+            continue;
+        }
+        return argument;
+    }
+    return null;
+}
+function validateSensitiveGitApprovalActions(intentName, intent, issues) {
+    if (intent.status !== 'configured' || intent.run_policy !== 'agent_allowed') {
+        return;
+    }
+    const argv = readStringArray(intent, 'argv');
+    if (!argv) {
+        return;
+    }
+    const gitSubcommand = readGitSubcommand(argv);
+    const requiredAction = gitSubcommand === 'add' || gitSubcommand === 'commit'
+        ? 'git_commit'
+        : gitSubcommand === 'push'
+            ? 'git_push'
+            : null;
+    if (!requiredAction) {
+        return;
+    }
+    const approvalActions = readStringArray(intent, 'approval_actions') ?? [];
+    if (!approvalActions.includes(requiredAction)) {
+        issues.push(commandContractIssue(`Agent-runnable git ${gitSubcommand} intent ${intentName} must include approval_actions = ["${requiredAction}"]`));
+    }
+}
 function validatePositiveIntegerField(table, key, label, issues) {
     if (hasOwn(table, key) && !isPositiveInteger(table[key])) {
         issues.push(commandContractIssue(`${label} must be a positive integer`));
@@ -339,6 +391,8 @@ function validateCommandIntent(intentName, intent, allIntents, issues) {
     validateAllowedStringField(intent, 'env_policy', `[commands.intents.${intentName}].env_policy`, COMMAND_ENV_POLICIES, issues);
     validateBooleanField(intent, 'allow_shell', `[commands.intents.${intentName}].allow_shell`, issues);
     validateStringArrayField(intent, 'env_allowlist', `[commands.intents.${intentName}].env_allowlist`, issues);
+    validateApprovalActions(intentName, intent, issues);
+    validateSensitiveGitApprovalActions(intentName, intent, issues);
     validateBooleanField(intent, ALLOW_ENV_INHERITANCE_RISKS_KEY, `[commands.intents.${intentName}].${ALLOW_ENV_INHERITANCE_RISKS_KEY}`, issues);
     validateBooleanField(intent, ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY, `[commands.intents.${intentName}].${ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY}`, issues);
     validateMaxOutputBytesField(intent, 'max_output_bytes', `[commands.intents.${intentName}].max_output_bytes`, issues);

package/package.json

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

package/schemas/commands.schema.json

@@ -210,6 +210,24 @@
         },
         "network": { "type": "boolean" },
         "destructive": { "type": "boolean" },
+        "approval_actions": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "enum": [
+              "git_commit",
+              "git_push",
+              "dependency_install",
+              "dependency_upgrade",
+              "network_access",
+              "database_migration",
+              "destructive_command",
+              "secret_access",
+              "release",
+              "cross_repository_change"
+            ]
+          }
+        },
         "required_after": {
           "type": "array",
           "items": { "type": "string" }

package/templates/default/common/.mustflow/config/commands.toml

@@ -379,6 +379,14 @@ required_after = ["before_final_report", "commit_message_suggestion"]
 
 [intents.git_commit]
 status = "manual_only"
-description = "Create a Git commit."
-reason = "Creating a commit requires explicit user approval."
-agent_action = "do_not_commit_report_suggestion_only"
+description = "Create an unscoped Git commit."
+reason = "A generic commit cannot safely choose reviewed paths or a commit message."
+agent_action = "author_bounded_repo_specific_stage_and_commit_intents_after_explicit_user_request"
+approval_actions = ["git_commit"]
+
+[intents.git_push]
+status = "manual_only"
+description = "Push an unspecified Git ref."
+reason = "A generic push cannot safely choose the remote and ref."
+agent_action = "author_bounded_repo_specific_push_intent_after_explicit_user_request"
+approval_actions = ["git_push"]

package/templates/default/manifest.toml

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