mustflow 1.31.0 → 2.11.0

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

@@ -4,6 +4,7 @@ import { resolveSafeProjectCwd } from '../../core/command-cwd.js';
 import { resolveCommandEnv } from '../../core/command-env.js';
 import { evaluateCommandIntentEligibility, } from '../../core/command-intent-eligibility.js';
 import { isRecord, readPositiveInteger, readString, readStringArray, } from '../../core/config-loading.js';
+import { t } from './i18n.js';
 function getSuccessExitCodes(intent) {
     const value = intent.success_exit_codes;
     if (!Array.isArray(value) || value.length === 0 || value.some((entry) => !Number.isInteger(entry))) {
@@ -95,6 +96,10 @@ function readRunIntentMetadata(contract, intent) {
         envPolicy: env.policy,
         envAllowlist: env.allowlist,
         testTargets: [],
+        manualStartHint: readString(intent, 'manual_start_hint') ?? null,
+        healthCheckUrl: readString(intent, 'health_check_url') ?? null,
+        stopInstruction: readString(intent, 'stop_instruction') ?? null,
+        relatedOneshotChecks: readStringArray(intent, 'related_oneshot_checks') ?? [],
     };
 }
 function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonCode, detail) {
@@ -127,6 +132,11 @@ function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonC
         envPolicy: metadata?.envPolicy ?? null,
         envAllowlist: metadata?.envAllowlist ?? [],
         testTargets: [],
+        suggestedIntentSnippet: createSuggestedIntentSnippet(intentName, metadata, reasonCode),
+        manualStartHint: metadata?.manualStartHint ?? null,
+        healthCheckUrl: metadata?.healthCheckUrl ?? null,
+        stopInstruction: metadata?.stopInstruction ?? null,
+        relatedOneshotChecks: metadata?.relatedOneshotChecks ?? [],
     };
 }
 export function createRunPlan(projectRoot, contract, intentName, options = {}) {
@@ -179,8 +189,53 @@ export function createRunPlan(projectRoot, contract, intentName, options = {}) {
         envPolicy: metadata.envPolicy,
         envAllowlist: metadata.envAllowlist,
         testTargets,
+        suggestedIntentSnippet: null,
+        manualStartHint: metadata.manualStartHint,
+        healthCheckUrl: metadata.healthCheckUrl,
+        stopInstruction: metadata.stopInstruction,
+        relatedOneshotChecks: metadata.relatedOneshotChecks,
     };
 }
+function formatTomlString(value) {
+    return JSON.stringify(value);
+}
+function formatTomlStringArray(values) {
+    return `[${values.map(formatTomlString).join(', ')}]`;
+}
+function createSuggestedIntentSnippet(intentName, metadata, reasonCode) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(intentName)) {
+        return null;
+    }
+    let commandLines;
+    if (reasonCode === 'blocked_shell_background_pattern') {
+        commandLines = [`argv = ${formatTomlStringArray(['TODO_REPLACE_WITH_FINITE_COMMAND'])}`];
+    }
+    else if (metadata?.shellCommand) {
+        commandLines = [`mode = "shell"`, `cmd = ${formatTomlString(metadata.shellCommand)}`];
+    }
+    else {
+        commandLines = [`argv = ${formatTomlStringArray(metadata?.commandArgv ?? ['TODO_REPLACE_WITH_COMMAND'])}`];
+    }
+    const lifecycle = metadata?.lifecycle && metadata.lifecycle !== 'oneshot' ? metadata.lifecycle : 'oneshot';
+    const configuredCwd = reasonCode === 'cwd_outside_project' ? '.' : metadata?.configuredCwd ?? '.';
+    return [
+        `[intents.${intentName}]`,
+        `status = "manual_only"`,
+        `lifecycle = ${formatTomlString(lifecycle)}`,
+        `run_policy = "requires_explicit_user_request"`,
+        `description = "TODO: describe when this intent should run."`,
+        ...commandLines,
+        `cwd = ${formatTomlString(configuredCwd)}`,
+        `timeout_seconds = ${metadata?.timeoutSeconds ?? 600}`,
+        `stdin = "closed"`,
+        `success_exit_codes = ${metadata?.successExitCodes ? `[${metadata.successExitCodes.join(', ')}]` : '[0]'}`,
+        `writes = ${metadata?.writes ? formatTomlStringArray(metadata.writes) : '[]'}`,
+        `network = ${metadata?.network ?? false}`,
+        `destructive = ${metadata?.destructive ?? false}`,
+        `reason = "Review this suggested intent before enabling agent execution."`,
+        `agent_action = "do_not_guess_report_missing"`,
+    ].join('\n');
+}
 export function createRunPreview(plan, previewMode) {
     return {
         schema_version: '1',
@@ -213,9 +268,14 @@ export function createRunPreview(plan, previewMode) {
         env_allowlist: plan.envAllowlist,
         test_targets: plan.testTargets,
         success_exit_codes: plan.successExitCodes,
+        suggested_intent_snippet: plan.suggestedIntentSnippet,
+        manual_start_hint: plan.manualStartHint,
+        health_check_url: plan.healthCheckUrl,
+        stop_instruction: plan.stopInstruction,
+        related_oneshot_checks: plan.relatedOneshotChecks,
     };
 }
-export function renderRunPreviewText(plan, previewMode) {
+export function renderRunPreviewText(plan, previewMode, lang = 'en') {
     const lines = [
         `mf run ${previewMode}`,
         `Intent: ${plan.intentName}`,
@@ -223,6 +283,21 @@ export function renderRunPreviewText(plan, previewMode) {
     ];
     if (!plan.ok) {
         lines.push(`Reason: ${plan.reasonCode}${plan.detail ? ` (${plan.detail})` : ''}`);
+        if (plan.suggestedIntentSnippet) {
+            lines.push('', `${t(lang, 'run.label.suggestedIntentSnippet')}:`, plan.suggestedIntentSnippet);
+        }
+        if (plan.manualStartHint) {
+            lines.push('', `Manual start: ${plan.manualStartHint}`);
+        }
+        if (plan.healthCheckUrl) {
+            lines.push(`Health check: ${plan.healthCheckUrl}`);
+        }
+        if (plan.stopInstruction) {
+            lines.push(`Stop: ${plan.stopInstruction}`);
+        }
+        if (plan.relatedOneshotChecks.length > 0) {
+            lines.push(`Related oneshot checks: ${plan.relatedOneshotChecks.join(', ')}`);
+        }
         return lines.join('\n');
     }
     lines.push(`Mode: ${plan.mode}`);

package/dist/cli/lib/templates.js

@@ -79,6 +79,21 @@ function filterSkillIndexContent(content, selectedSkills) {
     })
         .join('\n');
 }
+function filterSkillRouteMetadataContent(content, selectedSkills) {
+    const selectedSkillSet = new Set(selectedSkills);
+    let keepCurrentRoute = true;
+    return content
+        .split(/\r?\n/u)
+        .filter((line) => {
+        const match = /^\[routes\."([^"]+)"\]\s*$/u.exec(line.trim());
+        if (match) {
+            keepCurrentRoute = selectedSkillSet.has(match[1] ?? '');
+            return keepCurrentRoute;
+        }
+        return keepCurrentRoute;
+    })
+        .join('\n');
+}
 function isAllowedTemplateCreateTarget(relativePath) {
     const normalizedPath = normalizeTemplateTargetPath(relativePath);
     if (normalizedPath.startsWith('/') ||
@@ -176,7 +191,9 @@ export function getTemplateFiles(template, locale = template.manifest.defaultLoc
         const indexSourcePath = localizedPath ?? fallbackLocalePath ?? commonPath;
         const content = relativePath === '.mustflow/skills/INDEX.md'
             ? filterSkillIndexContent(readFileSync(indexSourcePath, 'utf8'), selectedSkills)
-            : undefined;
+            : relativePath === '.mustflow/skills/routes.toml'
+                ? filterSkillRouteMetadataContent(readFileSync(indexSourcePath, 'utf8'), selectedSkills)
+                : undefined;
         if (localizedPath) {
             return {
                 relativePath,

package/dist/cli/lib/validation/command-intents.js

@@ -0,0 +1,11 @@
+import { isRecord } from '../command-contract.js';
+export function isDeclaredCommandIntent(commandsToml, intentName) {
+    return Boolean(commandsToml && isRecord(commandsToml.intents) && isRecord(commandsToml.intents[intentName]));
+}
+export function isConfiguredCommandIntent(commandsToml, intentName) {
+    if (!commandsToml || !isRecord(commandsToml.intents)) {
+        return false;
+    }
+    const intent = commandsToml.intents[intentName];
+    return isRecord(intent) && intent.status === 'configured';
+}

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

@@ -0,0 +1,238 @@
+import { COMMIT_MESSAGE_STYLES, TEST_AUTHORING_POLICIES } from '../preferences-options.js';
+import { VERSION_SOURCE_AUTHORITIES, VERSION_SOURCE_KINDS, } from '../../../core/version-sources.js';
+import { SKILL_ROUTE_CATEGORY_LABELS } from '../../../core/skill-route-alignment.js';
+export { SKILL_ROUTE_CATEGORY_LABELS };
+export const REQUIRED_SKILL_SECTION_IDS = [
+    'purpose',
+    'use-when',
+    'do-not-use-when',
+    'required-inputs',
+    'preconditions',
+    'allowed-edits',
+    'procedure',
+    'postconditions',
+    'verification',
+    'failure-handling',
+    'output-format',
+];
+export const SKILL_SECTION_MARKER_PATTERN = /^<!--\s*mustflow-section:\s*([a-z][a-z0-9-]*)\s*-->\s*\r?\n##\s+.+$/gimu;
+export const TEST_SELECTION_CONFIG_PATH = '.mustflow/config/test-selection.toml';
+export const REQUIRED_FILES = [
+    'AGENTS.md',
+    '.mustflow/config/mustflow.toml',
+    '.mustflow/config/commands.toml',
+    '.mustflow/skills/INDEX.md',
+];
+export const ALLOWED_MAP_MODES = new Set(['anchors_only']);
+export const ALLOWED_MAP_PRIVACY_LEVELS = new Set(['minimal']);
+export const ALLOWED_CONTEXT_READ_POLICIES = new Set(['task_relevant_only']);
+export const ALLOWED_CONTEXT_AUTHORITIES = new Set(['contextual']);
+export const ALLOWED_CONTEXT_DOCUMENT_AUTHORITIES = new Set(['contextual', 'derived', 'external', 'router']);
+export const CAPABILITY_STATE_FIELDS = ['repo_map', 'preferences', 'context', 'local_index', 'work_items', 'services'];
+export const CAPABILITY_BOOLEAN_FIELDS = ['workflow', 'command_contract', 'skills'];
+export const ALLOWED_CAPABILITY_STATES = new Set(['disabled', 'optional', 'required', 'generated_optional']);
+export const REQUIRED_AGENT_LOOP_PHASES = ['orient', 'plan', 'act', 'verify', 'report', 'handoff'];
+export const ALLOWED_HANDOFF_MODES = new Set(['report_only', 'work_item_optional']);
+export const ALLOWED_PROJECT_PROFILES = new Set(['minimal', 'patterns', 'oss', 'team', 'product', 'library']);
+export const RELEASE_VERSIONING_BOOLEAN_FIELDS = [
+    'impact_check',
+    'suggest_bump',
+    'auto_bump',
+    'require_user_confirmation',
+    'sync_template_version',
+    'sync_docs_examples',
+    'sync_tests',
+];
+export const FORBIDDEN_RELEASE_VERSIONING_CONTRACT_FIELDS = [
+    'path',
+    'paths',
+    'source',
+    'sources',
+    'version_source',
+    'version_sources',
+    'authority',
+    'kind',
+    'command_intents',
+    'run_policy',
+    'argv',
+    'cmd',
+    'release',
+    'tag',
+    'push',
+    'commit',
+];
+export const ALLOWED_VERSION_SOURCE_KINDS = new Set(VERSION_SOURCE_KINDS);
+export const ALLOWED_VERSION_SOURCE_AUTHORITIES = new Set(VERSION_SOURCE_AUTHORITIES);
+export const ALLOWED_COMMIT_MESSAGE_STYLES = new Set(COMMIT_MESSAGE_STYLES);
+export const VERIFICATION_SELECTION_BOOLEAN_FIELDS = [
+    'prefer_related_tests',
+    'skip_docs_only_full_test',
+    'skip_low_risk_code_full_test',
+    'skip_translation_only_full_test',
+    'skip_copy_only_full_test',
+    'report_skipped',
+];
+export const FORBIDDEN_VERIFICATION_SELECTION_AUTHORITY_FIELDS = [
+    'intents',
+    'command_intents',
+    'required_after',
+    'status',
+    'lifecycle',
+    'run_policy',
+    'argv',
+    'cmd',
+    'writes',
+    'network',
+    'destructive',
+];
+export const ALLOWED_VERIFICATION_SELECTION_STRATEGIES = new Set(['risk_based', 'targeted', 'full']);
+export const ALLOWED_TEST_SELECTION_RISKS = new Set(['low', 'medium', 'high', 'release_sensitive', 'security_sensitive']);
+export const FORBIDDEN_TEST_SELECTION_COMMAND_AUTHORITY_FIELDS = [
+    'argv',
+    'cmd',
+    'command',
+    'commands',
+    'command_intents',
+    'destructive',
+    'intents',
+    'lifecycle',
+    'network',
+    'required_after',
+    'run_policy',
+    'status',
+    'writes',
+];
+export const TEST_AUTHORING_BOOLEAN_FIELDS = ['prefer_existing_tests', 'require_new_test_rationale'];
+export const ALLOWED_TEST_AUTHORING_POLICIES = new Set(TEST_AUTHORING_POLICIES);
+export const ALLOWED_TESTING_POLICIES = new Set(['behavior_contract']);
+export const ALLOWED_TEST_DELETION_REASONS = new Set([
+    'behavior_removed',
+    'public_contract_changed',
+    'duplicate_coverage',
+    'implementation_detail_removed',
+    'obsolete_snapshot',
+]);
+export const FORBIDDEN_TEST_DELETION_REASONS = new Set([
+    'only_to_make_tests_pass',
+    'without_behavior_rationale',
+    'without_reporting',
+    'without_running_relevant_validation',
+]);
+export const ALLOWED_STALE_TEST_ACTIONS = new Set(['update_remove_or_report']);
+export const ALLOWED_HARNESS_MODES = new Set(['single_session', 'long_running_optional']);
+export const ALLOWED_HARNESS_FRESH_CONTEXT_MODES = new Set(['hash_check_before_reread', 'reread']);
+export const ALLOWED_HARNESS_PHASES = new Set(['plan', 'work', 'verify', 'judge', 'handoff']);
+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 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']);
+export const ALLOWED_REFRESH_METHODS = new Set(['hash_check', 'reread_if_changed']);
+export const ALLOWED_REFRESH_STATE_STORES = new Set(['none', 'cache']);
+export const ALLOWED_COMPACTION_STRATEGIES = new Set(['tiered']);
+export const ALLOWED_COMPACTION_STATE_STORES = new Set(['none', 'cache']);
+export const ALLOWED_COMPACTION_CATEGORIES = new Set([
+    'decisions',
+    'constraints',
+    'open_questions',
+    'files_discussed',
+    'commands_discussed',
+    'risks',
+    'next_steps',
+    'rejected_options',
+]);
+export const ALLOWED_COMPACTION_LONG_LIMIT_ACTIONS = new Set(['recompact_oldest', 'delete_oldest', 'archive_oldest']);
+export const ALLOWED_COMPACTION_RAW_LIMIT_ACTIONS = new Set(['prune_after_compaction', 'report']);
+export const ALLOWED_REFRESH_CHECKPOINTS = new Set([
+    'session_start',
+    'task_start',
+    'before_first_edit',
+    'before_command_run',
+    'after_instruction_file_change',
+    'root_change',
+    'after_compaction',
+    'before_final_report',
+]);
+export const ALLOWED_TRANSLATION_POLICIES = new Set([
+    'source_only',
+    'update_source_mark_targets_stale',
+    'machine_translate_requires_review',
+]);
+export const RAW_COMMAND_FENCE_PATTERN = /```(?:sh|bash|shell|zsh|powershell|ps1|cmd)\s+[\s\S]*?```/giu;
+export const SKILL_COMMAND_PERMISSION_CLAIM_PATTERNS = [
+    /\b(?:this\s+skill|skill\s+documents?|skills?)\s+(?:authorizes?|grants?|allows?|permits?)\s+(?:agents?\s+)?(?:to\s+)?(?:run|execute)\b/iu,
+    /\b(?:agents?\s+)?(?:may|can|are\s+allowed\s+to|is\s+allowed\s+to|is\s+permitted\s+to|have\s+permission\s+to)\s+(?:run|execute)\s+(?:raw\s+)?(?:shell\s+)?commands?\b/iu,
+    /\bcommand\s+execution\s+(?:is\s+)?(?:authorized|allowed|permitted)\s+by\s+(?:this\s+)?skill\b/iu,
+];
+export const ROUTER_INDEX_PROCEDURE_SECTION_PATTERN = /^##\s+(?:Use When|Do Not Use When|Required Inputs|Preconditions|Allowed Edits|Procedure|Postconditions|Verification|Failure Handling|Output Format|사용 조건|사용하지 않는 경우|필요한 입력|사전 조건|허용 수정 범위|절차|사후 조건|검증|실패 대응|출력 형식)\s*$/imu;
+export const ROUTER_INDEX_FILES = ['.mustflow/skills/INDEX.md', '.mustflow/context/INDEX.md'];
+export const SKILL_INDEX_PATH = '.mustflow/skills/INDEX.md';
+export const SKILL_ROUTES_METADATA_PATH = '.mustflow/skills/routes.toml';
+export const SUPPORTED_SKILL_SCHEMA_VERSION = '1';
+export const SKILL_PACK_ID_PATTERN = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)+$/u;
+export const ALLOWED_SKILL_ROUTE_CATEGORIES = new Set(Object.keys(SKILL_ROUTE_CATEGORY_LABELS));
+export const ALLOWED_SKILL_ROUTE_TYPES = new Set(['primary', 'adjunct', 'event', 'authoring']);
+export const ALLOWED_SKILL_ROUTE_PROFILES = new Set(['minimal', 'patterns', 'oss', 'team', 'product', 'library']);
+export const CONTEXT_AUTHORITY_DRIFT_PATTERNS = [
+    /^##\s+(?:Command Policy|Command Permissions|Allowed Commands|Denied Commands|File Edit Policy|Protected Paths|Forbidden Files|Execution Rules|Mandatory Rules|Binding Rules|명령 정책|명령 권한|허용 명령|금지 명령|파일 편집 정책|보호 경로|금지 파일|실행 규칙|필수 규칙)\s*$/imu,
+    /\b(?:must not|do not|never)\s+(?:edit|modify|write|delete)\s+(?:files?\s+)?(?:outside|under|inside|in)\b/iu,
+];
+export const REPO_MAP_DOC_ID = 'repo-map';
+export const REPO_MAP_LIFECYCLE = 'generated';
+export const REPO_MAP_GENERATOR = 'mustflow';
+export const REPO_MAP_RELATIVE_ROOT = '.';
+export const REPO_MAP_SOURCE_POLICY = 'anchors_only';
+export const REPO_MAP_PRIVACY_MODE = 'minimal';
+export const REPO_MAP_SOURCE_FINGERPRINT_PATTERN = /^sha256:[a-f0-9]{64}$/u;
+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']);
+export const SKILL_RESOURCE_TYPE_BY_ROOT = {
+    references: 'reference',
+    assets: 'asset',
+    scripts: 'script',
+};
+export const REQUIRED_SKILL_SCRIPT_RUN_POLICY = 'requires_command_contract';
+export const VOLATILE_REPO_MAP_PATTERNS = [
+    /\bGenerated\s+(?:at|on):/iu,
+    /\bLast\s+updated:/iu,
+    /\bUpdated\s+at:/iu,
+    /\bgenerated_at\b/iu,
+    /\btimestamp\b/iu,
+    /\bfile\s+count\b/iu,
+    /\bchanged\s+files\b/iu,
+];
+export const REPO_MAP_REMOTE_OR_BRANCH_PATTERNS = [
+    /https?:\/\//iu,
+    /\bgit@/iu,
+    /^\s*(?:Remote|Branch):/imu,
+];
+export const LOCAL_ABSOLUTE_PATH_PATTERNS = [
+    /\b[A-Za-z]:\\(?:Users|Documents and Settings)\\/iu,
+    /(?:^|[\s"'(])\/(?:Users|home)\/[A-Za-z0-9._-]+\/[^\s)"']*/imu,
+];
+export const SECRET_LIKE_CONTEXT_PATTERNS = [
+    /\b(?:api[_-]?key|api[_-]?token|access[_-]?token|auth[_-]?token|secret|password|passwd|private[_-]?key)\b\s*[:=]\s*["']?[A-Za-z0-9_./+=:-]{8,}/iu,
+    /\b(?:sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}|AKIA[0-9A-Z]{16})\b/u,
+];
+export const DESIGN_TOKEN_DEFINITION_PATTERNS = [
+    /^\s*(?:colors?|palette|spacing|radius|radii|typography|fonts?|shadows?|breakpoints?)\s*[:=]\s*(?:\{|\[|["']?#|\d)/imu,
+    /^\s*(?:primary|secondary|accent|background|foreground|surface|brand|text|muted)\s*[:=]\s*["']?#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})\b/imu,
+    /^\s*--[a-z0-9-]+:\s*[^;]+;/imu,
+    /^\s*(?:border[_-]?radius|font[_-]?(?:family|size)|line[_-]?height|space[-_]\d+)\s*[:=]\s*/imu,
+];
+export const LOCAL_TASK_STATE_ROOTS = new Set(['worklogs', 'plans', 'tasks', 'work-items']);