mustflow 2.59.0 → 2.69.0

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

@@ -143,6 +143,12 @@ export const COMMAND_DEFINITIONS = [
         summaryKey: 'command.search.summary',
         loadRunner: async () => (await import('../commands/search.js')).runSearch,
     },
+    {
+        id: 'skill',
+        usage: 'mf skill',
+        summaryKey: 'command.skill.summary',
+        loadRunner: async () => (await import('../commands/skill.js')).runSkill,
+    },
     {
         id: 'dashboard',
         usage: 'mf dashboard',

package/dist/cli/lib/local-index/constants.js

@@ -32,14 +32,13 @@ export const MUSTFLOW_RELATIVE_PATH = '.mustflow/config/mustflow.toml';
 export const INDEX_CONFIG_RELATIVE_PATH = '.mustflow/config/index.toml';
 export const DEFAULT_PROMPT_CACHE_STABLE_READ = [
     'AGENTS.md',
-    '.mustflow/docs/agent-workflow.md',
-    '.mustflow/config/mustflow.toml',
-    '.mustflow/config/commands.toml',
-    '.mustflow/skills/INDEX.md',
+    '.mustflow/skills/router.toml',
 ];
 export const DEFAULT_PROMPT_CACHE_TASK_SOURCES = [
     '.mustflow/context/INDEX.md',
-    'REPO_MAP.md',
+    'skill_route_candidates',
+    'route_metadata_fallback',
+    'repo_map_navigation',
     'matching_skill',
     'relevant_source_files',
 ];

package/dist/cli/lib/local-index/freshness.js

@@ -5,8 +5,9 @@ import { collectDocuments } from './workflow-documents.js';
 export function readStoredSchemaVersion(database) {
     return readMetadataValue(database, 'schema_version');
 }
-export function getStalePaths(projectRoot, database) {
+export function getStalePaths(projectRoot, database, options = {}) {
     const schemaVersion = readStoredSchemaVersion(database);
+    const includeState = options.includeState ?? true;
     if (schemaVersion !== LOCAL_INDEX_SCHEMA_VERSION) {
         return ['.mustflow/cache/mustflow.sqlite'];
     }
@@ -17,6 +18,9 @@ export function getStalePaths(projectRoot, database) {
         for (const row of indexedRows) {
             const indexedPath = toSearchString(row.path);
             const sourceScope = normalizeIndexedFileSourceScope(toSearchString(row.source_scope));
+            if (!includeState && sourceScope === 'state') {
+                continue;
+            }
             try {
                 const current = readIndexedFileRecord(projectRoot, indexedPath, sourceScope);
                 if (current.contentHash !== toSearchString(row.content_hash)) {

package/dist/cli/lib/local-index/index.js

@@ -383,7 +383,7 @@ export async function readLocalIndexPromptContext(projectRoot) {
         const SQL = await loadSqlJs();
         database = new SQL.Database(readFileSync(databasePath));
         const capabilities = readStoredSearchCapabilities(database);
-        const stalePaths = getStalePaths(projectRoot, database);
+        const stalePaths = getStalePaths(projectRoot, database, { includeState: false });
         if (stalePaths.length > 0) {
             return createLocalIndexPromptContextStatus(databasePath, 'stale', stalePaths, capabilities);
         }

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

@@ -28,6 +28,8 @@ const DEFAULT_PRIORITY_PATHS = [
     '.mustflow/config/commands.toml',
     '.mustflow/config/preferences.toml',
     '.mustflow/context/INDEX.md',
+    '.mustflow/skills/router.toml',
+    '.mustflow/skills/routes.toml',
     '.mustflow/skills/INDEX.md',
 ];
 const ROOT_OPTIONAL_MARKDOWN_ANCHOR_FILES = [
@@ -81,6 +83,8 @@ const DEFAULT_NESTED_ANCHOR_FILES = [
     '.mustflow/config/preferences.toml',
     '.mustflow/context/INDEX.md',
     '.mustflow/context/PROJECT.md',
+    '.mustflow/skills/router.toml',
+    '.mustflow/skills/routes.toml',
     '.mustflow/skills/INDEX.md',
     ...ROOT_OPTIONAL_MARKDOWN_ANCHOR_FILES,
     ...MACHINE_CONTRACT_ANCHOR_FILES,
@@ -191,7 +195,9 @@ const EXACT_ANCHOR_DESCRIPTIONS = new Map([
     ['.mustflow/context/INDEX.md', 'Task-specific project context router. Read only when context is needed.'],
     ['.mustflow/context/PROJECT.md', 'Project goals, non-goals, terms, and repository-wide promises for agents.'],
     ['.mustflow/docs/agent-workflow.md', 'Shared workflow policy for agent work.'],
-    ['.mustflow/skills/INDEX.md', 'Index of available procedural skills.'],
+    ['.mustflow/skills/router.toml', 'Stable compact skill-routing kernel for prompt-cache-friendly first-pass selection.'],
+    ['.mustflow/skills/routes.toml', 'Full skill-routing metadata for detailed procedure selection.'],
+    ['.mustflow/skills/INDEX.md', 'Expanded route table for detailed skill selection and route maintenance.'],
 ]);
 function spawnGitLsFiles(command, args, options) {
     const result = spawnSync(command, [...args], options);

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

@@ -21,6 +21,8 @@ export const REQUIRED_FILES = [
     'AGENTS.md',
     '.mustflow/config/mustflow.toml',
     '.mustflow/config/commands.toml',
+    '.mustflow/skills/router.toml',
+    '.mustflow/skills/routes.toml',
     '.mustflow/skills/INDEX.md',
 ];
 export const ALLOWED_MAP_MODES = new Set(['anchors_only']);
@@ -181,6 +183,7 @@ export const SKILL_COMMAND_PERMISSION_CLAIM_PATTERNS = [
 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_ROUTER_PATH = '.mustflow/skills/router.toml';
 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;

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

@@ -17,6 +17,8 @@ import { MUSTFLOW_JSON_MAX_BYTES } from '../mustflow-read.js';
 import { getContractModelDefinitions, validateCandidateContractModelConfig, } from '../../../core/contract-models.js';
 import { VERSIONING_CONFIG_PATH, detectVersionSourcePaths, readDeclaredVersionSources, releaseVersioningIsEnabled, } from '../../../core/version-sources.js';
 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 { 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';
@@ -63,6 +65,7 @@ function validateMustflowConfig(mustflowToml, issues) {
             const stable = validateNestedTable(layers, 'stable', '[prompt_cache.layers.stable]', issues);
             if (stable) {
                 validatePathArrayField(stable, 'read', '[prompt_cache.layers.stable].read', issues);
+                validatePositiveIntegerField(stable, 'target_kb', '[prompt_cache.layers.stable].target_kb', issues);
             }
             const task = validateNestedTable(layers, 'task', '[prompt_cache.layers.task]', issues);
             if (task) {
@@ -511,7 +514,33 @@ function validateManifestLock(projectRoot, issues) {
         issues.push({ message: issue });
     }
 }
-function validateStrictPromptCachePolicy(mustflowToml, issues) {
+function validateStrictStablePromptCacheBudget(projectRoot, promptCache, stableRead, issues) {
+    if (!isPositiveInteger(promptCache.max_stable_prefix_kb)) {
+        return;
+    }
+    const budgetBytes = Number(promptCache.max_stable_prefix_kb) * 1024;
+    let renderedBytes = 0;
+    for (const entry of stableRead) {
+        if (typeof entry !== 'string' || !isSafeRelativePath(entry)) {
+            continue;
+        }
+        const normalizedPath = toPosixPath(entry);
+        const absolutePath = path.join(projectRoot, entry);
+        if (!existsSync(absolutePath)) {
+            pushStrictIssue(issues, `stable prefix document is missing: ${normalizedPath}`);
+            continue;
+        }
+        const content = readStrictMustflowText(projectRoot, entry, issues);
+        if (content === undefined) {
+            continue;
+        }
+        renderedBytes += measurePromptCacheReferenceBlockBytes(entry, content);
+    }
+    if (renderedBytes > budgetBytes) {
+        pushStrictIssue(issues, `stable prefix exceeds [prompt_cache].max_stable_prefix_kb: ${renderedBytes} rendered bytes > ${budgetBytes} budget bytes`);
+    }
+}
+function validateStrictPromptCachePolicy(projectRoot, mustflowToml, issues) {
     if (!mustflowToml || !isRecord(mustflowToml.prompt_cache)) {
         pushStrictIssue(issues, '[prompt_cache] table is required');
         return;
@@ -534,7 +563,11 @@ function validateStrictPromptCachePolicy(mustflowToml, issues) {
         if (typeof entry === 'string' && volatileSources.has(entry)) {
             pushStrictIssue(issues, `[prompt_cache.layers.stable].read must not include volatile path "${entry}"`);
         }
+        if (typeof entry === 'string' && isPromptCacheStableLeafSkillSurface(entry)) {
+            pushStrictIssue(issues, `[prompt_cache.layers.stable].read must not include leaf skill or expanded route surface "${toPosixPath(entry)}"`);
+        }
     }
+    validateStrictStablePromptCacheBudget(projectRoot, promptCache, stable.read, issues);
     if (promptCache.exclude_volatile_state_from_prefix !== true) {
         pushStrictIssue(issues, '[prompt_cache].exclude_volatile_state_from_prefix should be true');
     }
@@ -590,6 +623,11 @@ function validateStrictRouterIndexes(projectRoot, issues) {
         }
     }
 }
+function validateStrictSkillRouteFixtures(projectRoot, issues) {
+    for (const issue of validateSkillRouteFixtures(projectRoot)) {
+        pushStrictIssue(issues, issue.message);
+    }
+}
 function validateSkillIndexRouteShape(content, issues) {
     for (const line of content.split(/\r?\n/u)) {
         if (!line.trim().startsWith('|')) {
@@ -1536,7 +1574,7 @@ function validateStrictStorage(projectRoot, limits, issues) {
 }
 function validateStrict(projectRoot, parsed, issues) {
     const retentionLimits = validateStrictRetentionPolicy(parsed.mustflowToml, issues);
-    validateStrictPromptCachePolicy(parsed.mustflowToml, issues);
+    validateStrictPromptCachePolicy(projectRoot, parsed.mustflowToml, issues);
     validateStrictRefreshPolicy(parsed.mustflowToml, issues);
     validateStrictHarnessPolicy(parsed.mustflowToml, issues);
     validateStrictCommandDefaults(projectRoot, parsed.commandsToml, issues);
@@ -1548,6 +1586,7 @@ function validateStrict(projectRoot, parsed, issues) {
     validateStrictTemplateVersionSync(projectRoot, parsed.preferencesToml, issues);
     validateStrictManagedMarkdownIdentities(projectRoot, issues);
     validateStrictRouterIndexes(projectRoot, issues);
+    validateStrictSkillRouteFixtures(projectRoot, issues);
     validateStrictSkills(projectRoot, parsed.commandsToml, issues);
     validateStrictTemplateSkillProfiles(issues);
     validateStrictRepoMap(projectRoot, issues);

package/dist/core/check-issues.js

@@ -30,6 +30,9 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.command_contract.project_local_bin_bare_executable', /^Strict warning: configured agent-runnable intent [^\s]+ uses bare executable "[^"]+" that matches project-local node_modules\/\.bin/u],
     ['mustflow.prompt_cache.required', /^Strict: \[prompt_cache\] table is required$/u],
     ['mustflow.prompt_cache.volatile_in_stable', /^Strict: \[prompt_cache\.layers\.stable\]\.read must not include volatile path /u],
+    ['mustflow.prompt_cache.leaf_skill_in_stable', /^Strict: \[prompt_cache\.layers\.stable\]\.read must not include leaf skill or expanded route surface /u],
+    ['mustflow.prompt_cache.stable_file_missing', /^Strict: stable prefix document is missing: /u],
+    ['mustflow.prompt_cache.stable_prefix_over_budget', /^Strict: stable prefix exceeds \[prompt_cache\]\.max_stable_prefix_kb: \d+ rendered bytes > \d+ budget bytes$/u],
     ['mustflow.refresh.hash_method_required', /^Strict: \[refresh\]\.default_method should be "hash_check" for cache-friendly refresh$/u],
     ['mustflow.release.template_version_mismatch', /^Strict: templates\/default\/manifest\.toml version "[^"]+" must match package\.json version "[^"]+" when \[release\.versioning\]\.sync_template_version is true$/u],
     ['mustflow.release.template_version_ahead', /^Strict: templates\/default\/manifest\.toml version "[^"]+" must not be ahead of package\.json version "[^"]+"$/u],
@@ -57,6 +60,8 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.skill.route_metadata_category_mismatch', /^Strict: \.mustflow\/skills\/INDEX\.md route "[^"]+" must appear under the .+ category section from \.mustflow\/skills\/routes\.toml$/u],
     ['mustflow.skill.route_metadata_unknown_reference', /^Strict: \.mustflow\/skills\/routes\.toml route "[^"]+" references unknown mutually exclusive route "[^"]+"$/u],
     ['mustflow.skill.route_metadata_asymmetric_exclusion', /^Strict warning: \.mustflow\/skills\/routes\.toml route "[^"]+" lists "[^"]+" as mutually exclusive but the reverse route does not$/u],
+    ['mustflow.skill.route_fixture_invalid', /^Strict: \.mustflow\/skills\/route-fixtures\.json (?:must|is not valid JSON|cases\[\d+\])/u],
+    ['mustflow.skill.route_fixture_mismatch', /^Strict: Skill route fixture "[^"]+" (?:expected|forbids)/u],
     ['mustflow.skill.template_profile_empty_category', /^Strict: template profile "[^"]+" (?:skill index category ".+" has no route rows|route category gate references ".+" without route rows)$/u],
     ['mustflow.skill.template_profile_dead_route', /^Strict: template profile "[^"]+" (?:\.mustflow\/skills\/INDEX\.md route "[^"]+" points to a skill not installed by that profile|\.mustflow\/skills\/routes\.toml route "[^"]+" points to a skill not installed by that profile|skill "[^"]+" is installed but not listed in \.mustflow\/skills\/INDEX\.md)$/u],
     ['mustflow.skill.template_profile_missing_main_route', /^Strict: template profile "[^"]+" skill category ".+" must include at least one primary or authoring route$/u],

package/dist/core/prompt-cache-rendering.js

@@ -0,0 +1,19 @@
+function toPromptCachePosixPath(relativePath) {
+    return relativePath.replace(/\\/gu, '/');
+}
+export function isPromptCacheStableLeafSkillSurface(relativePath) {
+    const normalized = toPromptCachePosixPath(relativePath);
+    return normalized === '.mustflow/skills/INDEX.md'
+        || normalized === '.mustflow/skills/routes.toml'
+        || /^\.mustflow\/skills\/[^/]+\/.+/u.test(normalized);
+}
+export function normalizePromptCacheBlockContent(content) {
+    const normalized = content.replace(/\r\n?/gu, '\n').replace(/\n*$/u, '');
+    return `${normalized}\n`;
+}
+export function renderPromptCacheReferenceBlock(relativePath, content) {
+    return `--- mustflow-cache-block: ${toPromptCachePosixPath(relativePath)} ---\n${normalizePromptCacheBlockContent(content)}`;
+}
+export function measurePromptCacheReferenceBlockBytes(relativePath, content) {
+    return Buffer.byteLength(renderPromptCacheReferenceBlock(relativePath, content), 'utf8');
+}

package/dist/core/public-json-contracts.js

@@ -207,6 +207,32 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         installedCommand: ['mf', 'quality', 'check', '--json'],
         expectedExitCodes: [0, 1],
     },
+    {
+        id: 'skill-route-report',
+        schemaFile: 'skill-route-report.schema.json',
+        producer: 'mf skill route --json',
+        packaged: true,
+        documented: true,
+        installedCommand: [
+            'mf',
+            'skill',
+            'route',
+            '--task',
+            'Change TypeScript CLI output',
+            '--path',
+            'src/cli/index.ts',
+            '--reason',
+            'code_change',
+            '--json',
+        ],
+    },
+    {
+        id: 'route-fixture',
+        schemaFile: 'route-fixture.schema.json',
+        producer: 'parsed .mustflow/skills/route-fixtures.json',
+        packaged: true,
+        documented: true,
+    },
     {
         id: 'latest-run-pointer',
         schemaFile: 'latest-run-pointer.schema.json',

package/dist/core/quality-gaming.js

@@ -15,6 +15,7 @@ const TYPE_ESCAPE_PATTERN = /\b(?:as\s+any|as\s+unknown\s+as|as\s+never|:\s*any\
 const TEST_BYPASS_PATTERN = /(?:\.skip\b|\.only\b|@Disabled\b|@Ignore\b|\bxfail\b|pytest\.mark\.skip|it\.todo\b|test\.todo\b)/u;
 const PLACEHOLDER_PATTERN = /(?:TODO|FIXME|HACK|not\s+implemented|unimplemented|throw\s+new\s+Error\(["'`](?:not implemented|todo|unsupported)|\bpass\s*$)/iu;
 const THROW_PLACEHOLDER_MESSAGE_PATTERN = /(?:not\s+implemented|unimplemented|todo|unsupported)/iu;
+const EMPTY_CATCH_PATTERN = /\bcatch\s*(?:\([^)]*\))?\s*\{\s*\}/u;
 function toPosixPath(value) {
     return value.split(path.sep).join('/');
 }
@@ -236,6 +237,9 @@ function inspectLine(relativePath, candidate, risks) {
             (/\bthrow\s+new\s+Error\s*\(/u.test(codeSurface) && THROW_PLACEHOLDER_MESSAGE_PATTERN.test(text)))) {
         addRisk(risks, 'placeholder_added', 'medium', relativePath, candidate.line, 'Added line looks like a placeholder or unfinished implementation.', null);
     }
+    if (isCode && EMPTY_CATCH_PATTERN.test(codeSurface)) {
+        addRisk(risks, 'empty_catch_swallow_added', 'high', relativePath, candidate.line, 'Added line contains an empty catch block that swallows failures.', null);
+    }
     if (GENERATED_OR_VENDOR_PATTERN.test(relativePath) && isCode && isMeaningfulCodeLine(text)) {
         addRisk(risks, 'generated_or_vendor_logic_added', 'high', relativePath, candidate.line, 'Added executable-looking logic under generated, vendor, or third_party paths.', null);
     }

package/dist/core/skill-route-fixtures.js

@@ -0,0 +1,173 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord } from './config-loading.js';
+import { readUtf8FileInsideWithoutSymlinks } from './safe-filesystem.js';
+import { resolveSkillRoutes } from './skill-route-resolution.js';
+export const SKILL_ROUTE_FIXTURES_PATH = '.mustflow/skills/route-fixtures.json';
+const FIXTURE_MAX_BYTES = 256 * 1024;
+function readStringArray(value, options = {}) {
+    if (!Array.isArray(value) ||
+        (!options.allowEmpty && value.length === 0) ||
+        !value.every((entry) => typeof entry === 'string' && entry.trim().length > 0)) {
+        return null;
+    }
+    return value.map((entry) => entry.trim());
+}
+function readOptionalStringArray(value, pointer, issues) {
+    if (value === undefined) {
+        return [];
+    }
+    const entries = readStringArray(value);
+    if (!entries) {
+        issues.push({ kind: 'invalid', message: `${pointer} must be a non-empty string array when present` });
+        return null;
+    }
+    return entries;
+}
+function readOptionalString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function readOptionalMaxCandidates(value) {
+    return Number.isInteger(value) && Number(value) > 0 && Number(value) <= 10 ? Number(value) : undefined;
+}
+function parseFixtureCase(value, index, issues) {
+    const pointer = `${SKILL_ROUTE_FIXTURES_PATH} cases[${index}]`;
+    if (!isRecord(value)) {
+        issues.push({ kind: 'invalid', message: `${pointer} must be an object` });
+        return null;
+    }
+    const id = readOptionalString(value.id);
+    if (!id) {
+        issues.push({ kind: 'invalid', message: `${pointer}.id must be a non-empty string` });
+        return null;
+    }
+    const paths = readStringArray(value.paths);
+    if (!paths) {
+        issues.push({ kind: 'invalid', message: `${pointer}.paths must be a non-empty string array` });
+        return null;
+    }
+    const reasons = readStringArray(value.reasons);
+    if (!reasons) {
+        issues.push({ kind: 'invalid', message: `${pointer}.reasons must be a non-empty string array` });
+        return null;
+    }
+    let task;
+    if (value.task === undefined || value.task === null) {
+        task = null;
+    }
+    else {
+        const taskValue = readOptionalString(value.task);
+        if (!taskValue) {
+            issues.push({ kind: 'invalid', message: `${pointer}.task must be a non-empty string, null, or omitted` });
+            return null;
+        }
+        task = taskValue;
+    }
+    const maxCandidates = value.max_candidates === undefined ? undefined : readOptionalMaxCandidates(value.max_candidates);
+    if (value.max_candidates !== undefined && maxCandidates === undefined) {
+        issues.push({ kind: 'invalid', message: `${pointer}.max_candidates must be an integer from 1 through 10` });
+        return null;
+    }
+    const requiredCandidates = readOptionalStringArray(value.required_candidates, `${pointer}.required_candidates`, issues);
+    const requiredAdjuncts = readOptionalStringArray(value.required_adjuncts, `${pointer}.required_adjuncts`, issues);
+    const forbiddenCandidates = readOptionalStringArray(value.forbidden_candidates, `${pointer}.forbidden_candidates`, issues);
+    if (!requiredCandidates || !requiredAdjuncts || !forbiddenCandidates) {
+        return null;
+    }
+    const fixture = {
+        id,
+        task,
+        paths,
+        reasons,
+        maxCandidates,
+        requiredMain: readOptionalString(value.required_main),
+        requiredCandidates,
+        requiredAdjuncts,
+        forbiddenCandidates,
+    };
+    if (!fixture.requiredMain &&
+        fixture.requiredCandidates.length === 0 &&
+        fixture.requiredAdjuncts.length === 0 &&
+        fixture.forbiddenCandidates.length === 0) {
+        issues.push({
+            kind: 'invalid',
+            message: `${pointer} must declare required_main, required_candidates, required_adjuncts, or forbidden_candidates`,
+        });
+        return null;
+    }
+    return fixture;
+}
+function formatSkill(value) {
+    return value ?? 'none';
+}
+function validateFixtureCase(projectRoot, fixture) {
+    const report = resolveSkillRoutes(projectRoot, {
+        taskText: fixture.task,
+        paths: fixture.paths,
+        reasons: fixture.reasons,
+        maxCandidates: fixture.maxCandidates,
+    });
+    const issues = [];
+    const candidateSkills = new Set(report.candidates.map((candidate) => candidate.skill));
+    const adjunctSkills = new Set(report.selected.adjuncts.map((candidate) => candidate.skill));
+    if (fixture.requiredMain && report.selected.main?.skill !== fixture.requiredMain) {
+        issues.push({
+            kind: 'mismatch',
+            message: `Skill route fixture "${fixture.id}" expected selected main "${fixture.requiredMain}" but got "${formatSkill(report.selected.main?.skill)}"`,
+        });
+    }
+    for (const skill of fixture.requiredCandidates) {
+        if (!candidateSkills.has(skill)) {
+            issues.push({
+                kind: 'mismatch',
+                message: `Skill route fixture "${fixture.id}" expected candidate "${skill}" within top ${report.input.max_candidates}`,
+            });
+        }
+    }
+    for (const skill of fixture.requiredAdjuncts) {
+        if (!adjunctSkills.has(skill)) {
+            issues.push({
+                kind: 'mismatch',
+                message: `Skill route fixture "${fixture.id}" expected selected adjunct "${skill}"`,
+            });
+        }
+    }
+    for (const skill of fixture.forbiddenCandidates) {
+        if (candidateSkills.has(skill) || adjunctSkills.has(skill) || report.selected.main?.skill === skill) {
+            issues.push({
+                kind: 'mismatch',
+                message: `Skill route fixture "${fixture.id}" forbids selected or candidate skill "${skill}"`,
+            });
+        }
+    }
+    return issues;
+}
+export function validateSkillRouteFixtures(projectRoot) {
+    const fixturePath = path.join(projectRoot, ...SKILL_ROUTE_FIXTURES_PATH.split('/'));
+    if (!existsSync(fixturePath)) {
+        return [];
+    }
+    const issues = [];
+    let parsed;
+    try {
+        parsed = JSON.parse(readUtf8FileInsideWithoutSymlinks(projectRoot, fixturePath, { maxBytes: FIXTURE_MAX_BYTES }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return [{ kind: 'invalid', message: `${SKILL_ROUTE_FIXTURES_PATH} is not valid JSON: ${message}` }];
+    }
+    if (!isRecord(parsed) || parsed.schema_version !== '1' || !Array.isArray(parsed.cases)) {
+        return [{
+                kind: 'invalid',
+                message: `${SKILL_ROUTE_FIXTURES_PATH} must contain schema_version "1" and a cases array`,
+            }];
+    }
+    for (const [index, entry] of parsed.cases.entries()) {
+        const fixture = parseFixtureCase(entry, index, issues);
+        if (!fixture) {
+            continue;
+        }
+        issues.push(...validateFixtureCase(projectRoot, fixture));
+    }
+    return issues;
+}