mustflow 2.114.6 → 2.114.11

package/dist/cli/commands/skill.js

@@ -111,7 +111,29 @@ function createSkillRouteScriptPackSuggestions(mustflowRoot, report, paths) {
         issues: suggestionReport.issues,
     };
 }
+function routeDependencyReason(candidate) {
+    return candidate.selection_reasons.find((reason) => reason.startsWith('route_dependency:')) ?? null;
+}
+function conflictHintCandidates(report) {
+    const candidates = [
+        ...(report.selected.main ? [report.selected.main] : []),
+        ...report.selected.adjuncts,
+        ...report.candidates,
+    ];
+    const seenSkills = new Set();
+    return candidates.filter((candidate) => {
+        if (seenSkills.has(candidate.skill) || candidate.route_card.route_dependencies.conflicts_with.length === 0) {
+            return false;
+        }
+        seenSkills.add(candidate.skill);
+        return true;
+    });
+}
 function renderSkillRouteReport(report, lang, warnings = []) {
+    const dependencyReads = report.selected.adjuncts
+        .map((candidate) => ({ candidate, reason: routeDependencyReason(candidate) }))
+        .filter((entry) => entry.reason !== null);
+    const conflictHints = conflictHintCandidates(report);
     const lines = [
         'mustflow skill route',
         `${t(lang, 'label.mustflowRoot')}: ${resolveMustflowRoot()}`,
@@ -125,7 +147,19 @@ function renderSkillRouteReport(report, lang, warnings = []) {
     }
     else {
         for (const candidate of report.candidates) {
-            lines.push(`- ${candidate.skill} (${candidate.route_type}, score ${candidate.score.toFixed(1)})`, `  path: ${candidate.skill_path}`, `  reasons: ${candidate.selection_reasons.join(', ') || t(lang, 'value.none')}`);
+            lines.push(`- ${candidate.skill} (${candidate.route_type}, score ${candidate.score.toFixed(1)})`, `  path: ${candidate.skill_path}`, `  reasons: ${candidate.selection_reasons.join(', ') || t(lang, 'value.none')}`, `  matched_dimensions: ${candidate.matched_dimensions.join(', ') || t(lang, 'value.none')}`);
+        }
+    }
+    if (dependencyReads.length > 0) {
+        lines.push('', 'Dependency reads');
+        for (const { candidate, reason } of dependencyReads) {
+            lines.push(`- ${candidate.skill}`, `  reason: ${reason}`, `  path: ${candidate.skill_path}`);
+        }
+    }
+    if (conflictHints.length > 0) {
+        lines.push('', 'Conflict hints');
+        for (const candidate of conflictHints) {
+            lines.push(`- ${candidate.skill}`, `  conflicts_with: ${candidate.route_card.route_dependencies.conflicts_with.join(', ')}`, `  path: ${candidate.skill_path}`);
         }
     }
     lines.push('', 'Read plan', ...report.read_plan.selected_skill_paths.map((skillPath) => `- read selected skill: ${skillPath}`), `- avoid by default: ${report.read_plan.avoid_by_default.join(', ') || t(lang, 'value.none')}`, `- fallback route metadata: ${report.read_plan.fallback_route_metadata.path}`, '', 'Source files', ...report.source_files.map((sourceFile) => `- ${sourceFile}`));

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

@@ -683,6 +683,63 @@ function readOptionalStringArray(value, label, issues) {
     }
     return value.map((entry) => entry.trim());
 }
+function readOptionalSlugArray(value, label, issues) {
+    const values = readOptionalStringArray(value, label, issues);
+    for (const value of values) {
+        if (!/^[a-z][a-z0-9_-]*$/u.test(value)) {
+            pushStrictIssue(issues, `${label} entry "${value}" must use lowercase slug text`);
+        }
+    }
+    return values;
+}
+function readSkillRouteMetadataContexts(value, label, issues) {
+    if (value !== undefined && !isRecord(value)) {
+        pushStrictIssue(issues, `${label}.contexts must be a TOML table`);
+    }
+    const contexts = isRecord(value) ? value : {};
+    return {
+        fileTypes: readOptionalSlugArray(contexts.file_types, `${label}.contexts.file_types`, issues),
+        frameworks: readOptionalSlugArray(contexts.frameworks, `${label}.contexts.frameworks`, issues),
+        layers: readOptionalSlugArray(contexts.layers, `${label}.contexts.layers`, issues),
+        patternCategories: readOptionalSlugArray(contexts.pattern_categories, `${label}.contexts.pattern_categories`, issues),
+        positiveTerms: readOptionalSlugArray(contexts.positive_terms, `${label}.contexts.positive_terms`, issues),
+        negativeTerms: readOptionalSlugArray(contexts.negative_terms, `${label}.contexts.negative_terms`, issues),
+    };
+}
+function readSkillRouteUnlockRules(value, label, issues) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value) || value.some((entry) => !isRecord(entry))) {
+        pushStrictIssue(issues, `${label} must be an array of TOML tables`);
+        return [];
+    }
+    return value
+        .map((entry, index) => {
+        const signal = typeof entry.signal === 'string' ? entry.signal.trim() : '';
+        const skill = typeof entry.skill === 'string' ? entry.skill.trim() : '';
+        if (!/^[a-z][a-z0-9_-]*$/u.test(signal)) {
+            pushStrictIssue(issues, `${label}[${index}].signal must use lowercase slug text`);
+        }
+        if (!/^[a-z][a-z0-9-]*$/u.test(skill)) {
+            pushStrictIssue(issues, `${label}[${index}].skill must be a skill folder name`);
+        }
+        return { signal, skill };
+    })
+        .filter((entry) => entry.signal && entry.skill);
+}
+function readSkillRouteMetadataDependencies(value, label, issues) {
+    if (value !== undefined && !isRecord(value)) {
+        pushStrictIssue(issues, `${label}.dependencies must be a TOML table`);
+    }
+    const dependencies = isRecord(value) ? value : {};
+    return {
+        requiresSkills: readOptionalSlugArray(dependencies.requires_skills, `${label}.dependencies.requires_skills`, issues),
+        suggestsAdjuncts: readOptionalSlugArray(dependencies.suggests_adjuncts, `${label}.dependencies.suggests_adjuncts`, issues),
+        conflictsWith: readOptionalSlugArray(dependencies.conflicts_with, `${label}.dependencies.conflicts_with`, issues),
+        unlocksOn: readSkillRouteUnlockRules(dependencies.unlocks_on, `${label}.dependencies.unlocks_on`, issues),
+    };
+}
 function validateSkillRouteMetadataTable(skillName, route, issues) {
     const label = `${SKILL_ROUTES_METADATA_PATH} routes.${skillName}`;
     const rawCategory = typeof route.category === 'string' ? route.category : undefined;
@@ -693,6 +750,8 @@ function validateSkillRouteMetadataTable(skillName, route, issues) {
     const profiles = readOptionalStringArray(route.profiles, `${label}.profiles`, issues);
     const appliesToReasons = readOptionalStringArray(route.applies_to_reasons, `${label}.applies_to_reasons`, issues);
     const mutuallyExclusiveWith = readOptionalStringArray(route.mutually_exclusive_with, `${label}.mutually_exclusive_with`, issues);
+    const contexts = readSkillRouteMetadataContexts(route.contexts, label, issues);
+    const dependencies = readSkillRouteMetadataDependencies(route.dependencies, label, issues);
     if (!category) {
         pushStrictIssue(issues, `${label}.category must be one of ${[...ALLOWED_SKILL_ROUTE_CATEGORIES].join(', ')}`);
     }
@@ -718,6 +777,8 @@ function validateSkillRouteMetadataTable(skillName, route, issues) {
         routeType,
         priority: route.priority,
         mutuallyExclusiveWith,
+        contexts,
+        dependencies,
     };
 }
 function readSkillRouteMetadata(projectRoot, issues) {
@@ -759,6 +820,16 @@ function readSkillRouteMetadata(projectRoot, issues) {
     }
     return metadata;
 }
+function validateAdjunctRouteDependency(metadata, issues, skillName, targetSkill, relation) {
+    const targetRoute = metadata.get(targetSkill);
+    if (!targetRoute || targetRoute.routeType === 'adjunct') {
+        return;
+    }
+    pushStrictIssue(issues, [
+        `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" ${relation} route "${targetSkill}"`,
+        ` must point to an adjunct route, found "${targetRoute.routeType ?? 'unknown'}"`,
+    ].join(''));
+}
 function validateSkillRouteMetadataAlignment(metadata, routeSkillNames, expectedSkillNames, issues) {
     for (const skillName of routeSkillNames) {
         if (!metadata.has(skillName)) {
@@ -783,6 +854,47 @@ function validateSkillRouteMetadataAlignment(metadata, routeSkillNames, expected
                 pushStrictWarning(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" lists "${otherSkillName}" as mutually exclusive but the reverse route does not`);
             }
         }
+        for (const requiredSkill of route.dependencies.requiresSkills) {
+            if (requiredSkill === skillName) {
+                pushStrictIssue(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" cannot require itself`);
+            }
+            else if (!metadata.has(requiredSkill)) {
+                pushStrictIssue(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" requires unknown route "${requiredSkill}"`);
+            }
+        }
+        for (const adjunctSkill of route.dependencies.suggestsAdjuncts) {
+            if (adjunctSkill === skillName) {
+                pushStrictIssue(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" cannot suggest itself as an adjunct`);
+            }
+            else if (!metadata.has(adjunctSkill)) {
+                pushStrictIssue(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" suggests unknown adjunct route "${adjunctSkill}"`);
+            }
+            else {
+                validateAdjunctRouteDependency(metadata, issues, skillName, adjunctSkill, 'suggests adjunct');
+            }
+        }
+        for (const conflictingSkill of route.dependencies.conflictsWith) {
+            if (conflictingSkill === skillName) {
+                pushStrictIssue(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" cannot conflict with itself`);
+            }
+            else if (!metadata.has(conflictingSkill)) {
+                pushStrictIssue(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" conflicts with unknown route "${conflictingSkill}"`);
+            }
+            else if (!metadata.get(conflictingSkill)?.dependencies.conflictsWith.includes(skillName)) {
+                pushStrictWarning(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" conflicts with "${conflictingSkill}" but the reverse route does not`);
+            }
+        }
+        for (const unlockRule of route.dependencies.unlocksOn) {
+            if (unlockRule.skill === skillName) {
+                pushStrictIssue(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" cannot unlock itself`);
+            }
+            else if (!metadata.has(unlockRule.skill)) {
+                pushStrictIssue(issues, `${SKILL_ROUTES_METADATA_PATH} route "${skillName}" unlocks unknown route "${unlockRule.skill}" on signal "${unlockRule.signal}"`);
+            }
+            else {
+                validateAdjunctRouteDependency(metadata, issues, skillName, unlockRule.skill, `unlocks on signal "${unlockRule.signal}"`);
+            }
+        }
     }
 }
 function validateSkillIndexRoutes(projectRoot, commandsToml, skillFiles, issues) {

package/dist/core/check-issues.js

@@ -1,3 +1,10 @@
+const ROUTE_METADATA_UNKNOWN_REFERENCE_PATTERN = new RegExp('^Strict: \\.mustflow\\/skills\\/routes\\.toml route "[^"]+" ' +
+    '(?:references unknown mutually exclusive route|requires unknown route|' +
+    'suggests unknown adjunct route|conflicts with unknown route|unlocks unknown route) ' +
+    '"[^"]+"(?: on signal "[^"]+")?$', 'u');
+const ROUTE_METADATA_INVALID_DEPENDENCY_PATTERN = new RegExp('^Strict: \\.mustflow\\/skills\\/routes\\.toml route "[^"]+" ' +
+    '(?:suggests adjunct|unlocks on signal "[^"]+") route "[^"]+" ' +
+    'must point to an adjunct route, found "[^"]+"$', 'u');
 const CHECK_ISSUE_ID_RULES = [
     ['mustflow.command_contract.intent_table_missing', /^Missing \[intents\] table in \.mustflow\/config\/commands\.toml$/u],
     ['mustflow.command_contract.intent_not_table', /^Intent [^\s]+ must be a TOML table$/u],
@@ -58,8 +65,13 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.skill.route_metadata_unlisted', /^Strict: \.mustflow\/skills\/routes\.toml route "[^"]+" is not listed in \.mustflow\/skills\/INDEX\.md$/u],
     ['mustflow.skill.route_metadata_missing_document', /^Strict: \.mustflow\/skills\/routes\.toml route "[^"]+" points to a missing skill document$/u],
     ['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_unknown_reference',
+        ROUTE_METADATA_UNKNOWN_REFERENCE_PATTERN,
+    ],
+    ['mustflow.skill.route_metadata_invalid_dependency', ROUTE_METADATA_INVALID_DEPENDENCY_PATTERN],
     ['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_metadata_asymmetric_conflict', /^Strict warning: \.mustflow\/skills\/routes\.toml route "[^"]+" conflicts with "[^"]+" 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],

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

@@ -13,6 +13,10 @@ const DEFAULT_MAX_CANDIDATES = 5;
 const DEFAULT_MAX_MAIN = 1;
 const DEFAULT_MAX_ADJUNCTS = 2;
 const PATH_SKILL_HINT_SCORE = 25;
+const PATTERN_SIGNAL_TERM_SCORE = 12;
+const PATTERN_SIGNAL_MAX_SCORE = 48;
+const NEGATIVE_SIGNAL_TERM_PENALTY = -25;
+const NEGATIVE_SIGNAL_MAX_PENALTY = -75;
 const DOCS_TREE_MARKDOWN_PATH_PATTERN = /(?:^|\/)(?:docs|docs-site|documentation|\.mustflow\/docs|\.mustflow\/context)\/.+\.(?:md|mdx)$/u;
 const ROOT_DOCUMENT_BASENAMES = [
     'readme',
@@ -33,6 +37,12 @@ const ROOT_DOCUMENT_BASENAMES = [
     'architecture',
     'api',
 ];
+const EMPTY_ROUTE_DEPENDENCIES = {
+    requires_skills: [],
+    suggests_adjuncts: [],
+    conflicts_with: [],
+    unlocks_on: [],
+};
 const ROUTE_TYPE_WEIGHTS = {
     primary: 18,
     authoring: 16,
@@ -101,6 +111,46 @@ function readStringArrayFromTable(table, key) {
         ? value.map((entry) => entry.trim()).filter(Boolean)
         : [];
 }
+function readRouteSignalProfile(route) {
+    const contexts = route.contexts;
+    if (!isRecord(contexts)) {
+        return {
+            positiveTerms: [],
+            negativeTerms: [],
+        };
+    }
+    return {
+        positiveTerms: tokenize(readStringArrayFromTable(contexts, 'positive_terms').join(' ')),
+        negativeTerms: tokenize(readStringArrayFromTable(contexts, 'negative_terms').join(' ')),
+    };
+}
+function readRouteUnlockRules(table) {
+    const value = table.unlocks_on;
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter(isRecord)
+        .map((entry) => {
+        return {
+            signal: typeof entry.signal === 'string' ? entry.signal.trim() : '',
+            skill: typeof entry.skill === 'string' ? entry.skill.trim() : '',
+        };
+    })
+        .filter((entry) => entry.signal && entry.skill);
+}
+function readRouteDependencies(route) {
+    const dependencies = route.dependencies;
+    if (!isRecord(dependencies)) {
+        return EMPTY_ROUTE_DEPENDENCIES;
+    }
+    return {
+        requires_skills: readStringArrayFromTable(dependencies, 'requires_skills'),
+        suggests_adjuncts: readStringArrayFromTable(dependencies, 'suggests_adjuncts'),
+        conflicts_with: readStringArrayFromTable(dependencies, 'conflicts_with'),
+        unlocks_on: readRouteUnlockRules(dependencies),
+    };
+}
 function readFrontmatterBlock(content) {
     if (!content.startsWith('---')) {
         return [];
@@ -174,6 +224,8 @@ function readSkillRouteMetadata(projectRoot) {
                 priority: Number.isInteger(route.priority) ? Number(route.priority) : 0,
                 appliesToReasons: readStringArrayFromTable(route, 'applies_to_reasons'),
                 mutuallyExclusiveWith: readStringArrayFromTable(route, 'mutually_exclusive_with'),
+                signalProfile: readRouteSignalProfile(route),
+                dependencies: readRouteDependencies(route),
             });
         }
     }
@@ -271,6 +323,10 @@ function countMatches(needles, haystack) {
     const haystackSet = new Set(haystack);
     return needles.filter((needle) => haystackSet.has(needle)).length;
 }
+function collectMatchedTerms(needles, haystack) {
+    const haystackSet = new Set(haystack);
+    return [...new Set(needles.filter((needle) => haystackSet.has(needle)))].sort((left, right) => left.localeCompare(right));
+}
 function routeTextTerms(route, skillName) {
     return tokenize([
         skillName,
@@ -282,6 +338,65 @@ function routeTextTerms(route, skillName) {
         route.skillPath,
     ].join(' '));
 }
+function createExcerptReference(skillPath, section) {
+    return {
+        source_path: skillPath,
+        section,
+        read_when: [
+            'candidate scores tie within the same route category',
+            'matched dimensions are too broad to choose a single skill',
+            'task language overlaps a listed negative or conflicting signal',
+        ],
+    };
+}
+function createRouteCard(skillPath, matchedDimensions, routeDependencies) {
+    return {
+        source: 'route_metadata_and_skill_frontmatter',
+        index_read_policy: 'fallback_only',
+        compact_fields: [
+            'skill',
+            'skill_path',
+            'trigger',
+            'category',
+            'route_type',
+            'priority',
+            'applies_to_reasons',
+            'score_breakdown',
+            'selection_reasons',
+            'verification_intents',
+            'route_dependencies',
+        ],
+        matched_dimensions: matchedDimensions,
+        route_dependencies: routeDependencies,
+        use_when_excerpt: createExcerptReference(skillPath, 'use-when'),
+        do_not_use_excerpt: createExcerptReference(skillPath, 'do-not-use-when'),
+        read_strategy: [
+            'Read the selected SKILL.md before editing matching scope.',
+            'For close ties, compare only Use When and Do Not Use When excerpts before loading full competing skills.',
+            'Use route_dependencies to add required or suggested adjunct skill reads without loading the expanded index.',
+            'Keep .mustflow/skills/INDEX.md out of the prompt unless route metadata and excerpts are insufficient.',
+        ],
+    };
+}
+function createPatternSignalBreakdown(signalProfile, taskTerms, pathTerms) {
+    if (signalProfile.positiveTerms.length === 0 && signalProfile.negativeTerms.length === 0) {
+        return {
+            positiveMatches: [],
+            negativeMatches: [],
+            patternScore: 0,
+            negativePenalty: 0,
+        };
+    }
+    const inputTerms = [...new Set([...taskTerms, ...pathTerms])];
+    const positiveMatches = collectMatchedTerms(signalProfile.positiveTerms, inputTerms);
+    const negativeMatches = collectMatchedTerms(signalProfile.negativeTerms, inputTerms);
+    return {
+        positiveMatches,
+        negativeMatches,
+        patternScore: Math.min(positiveMatches.length * PATTERN_SIGNAL_TERM_SCORE, PATTERN_SIGNAL_MAX_SCORE),
+        negativePenalty: Math.max(negativeMatches.length * NEGATIVE_SIGNAL_TERM_PENALTY, NEGATIVE_SIGNAL_MAX_PENALTY),
+    };
+}
 function createCandidate(route, metadata, taskTerms, pathTerms, pathSkillHints, reasons) {
     const skill = skillNameFromPath(route.skillPath);
     const terms = routeTextTerms(route, skill);
@@ -289,19 +404,38 @@ function createCandidate(route, metadata, taskTerms, pathTerms, pathSkillHints,
     const taskMatches = countMatches(taskTerms, terms);
     const pathMatches = countMatches(pathTerms, terms);
     const pathSkillHintMatched = pathSkillHints.has(skill);
+    const patternSignals = createPatternSignalBreakdown(metadata.signalProfile, taskTerms, pathTerms);
     const breakdown = {
         reason_match: matchedReasons.length * 35,
         task_text_match: taskMatches * 6,
         path_match: pathMatches * 6 + (pathSkillHintMatched ? PATH_SKILL_HINT_SCORE : 0),
+        pattern_signal_match: patternSignals.patternScore,
+        negative_signal_penalty: patternSignals.negativePenalty,
         route_type_weight: ROUTE_TYPE_WEIGHTS[metadata.routeType] ?? 0,
         priority_weight: Math.max(0, Math.min(metadata.priority, 100)) / 5,
     };
     const score = Object.values(breakdown).reduce((total, value) => total + value, 0);
+    const matchedDimensions = [
+        ...(matchedReasons.length > 0 ? ['reason'] : []),
+        ...(taskMatches > 0 ? ['task_terms'] : []),
+        ...(pathMatches > 0 ? ['path_terms'] : []),
+        ...(pathSkillHintMatched ? ['path_skill_hint'] : []),
+        ...(patternSignals.positiveMatches.length > 0 ? ['pattern_signal'] : []),
+        ...(patternSignals.negativeMatches.length > 0 ? ['negative_signal'] : []),
+        ...(metadata.routeType !== 'unknown' ? ['route_type'] : []),
+        ...(metadata.priority > 0 ? ['priority'] : []),
+    ];
     const selectionReasons = [
         ...matchedReasons.map((reason) => `reason:${reason}`),
         ...(taskMatches > 0 ? [`task_terms:${taskMatches}`] : []),
         ...(pathMatches > 0 ? [`path_terms:${pathMatches}`] : []),
         ...(pathSkillHintMatched ? [`path_skill_hint:${skill}`] : []),
+        ...(patternSignals.positiveMatches.length > 0
+            ? [`pattern_terms:${patternSignals.positiveMatches.join('|')}`]
+            : []),
+        ...(patternSignals.negativeMatches.length > 0
+            ? [`negative_terms:${patternSignals.negativeMatches.join('|')}`]
+            : []),
         `route_type:${metadata.routeType}`,
         `priority:${metadata.priority}`,
     ];
@@ -316,6 +450,8 @@ function createCandidate(route, metadata, taskTerms, pathTerms, pathSkillHints,
         score,
         score_breakdown: breakdown,
         selection_reasons: selectionReasons,
+        matched_dimensions: matchedDimensions,
+        route_card: createRouteCard(route.skillPath, matchedDimensions, metadata.dependencies),
         verification_intents: route.commandIntents,
     };
 }
@@ -333,20 +469,107 @@ function sortCandidates(left, right) {
 function isSelectableMain(candidate) {
     return candidate.route_type === 'primary' || candidate.route_type === 'authoring' || candidate.route_type === 'external';
 }
-function selectAdjuncts(main, allCandidates, metadata) {
+function hasDependencySignal(signal, dependencySignals, taskTerms, pathTerms) {
+    if (dependencySignals.has(signal)) {
+        return true;
+    }
+    const inputTerms = new Set([...taskTerms, ...pathTerms]);
+    const signalTerms = signal
+        .split('_')
+        .map((term) => (term === 'changed' ? 'change' : term))
+        .filter((term) => term !== 'or');
+    return signalTerms.length > 0 && signalTerms.every((term) => inputTerms.has(term));
+}
+function collectDependencySignals(paths, reasons, taskTerms, pathTerms) {
+    const dependencySignals = new Set(reasons);
+    const inputTerms = new Set([...taskTerms, ...pathTerms]);
+    if (inputTerms.has('output') &&
+        (inputTerms.has('machine') || inputTerms.has('json') || inputTerms.has('jsonl') || inputTerms.has('cli'))) {
+        dependencySignals.add('machine_output_changed');
+    }
+    if (inputTerms.has('schema') ||
+        inputTerms.has('fixture') ||
+        paths.some((pathValue) => /(?:^|\/)(?:schemas|fixtures|tests\/fixtures)(?:\/|$)/u.test(pathValue))) {
+        dependencySignals.add('schema_or_fixture_changed');
+    }
+    if (inputTerms.has('followup') ||
+        (inputTerms.has('follow') && inputTerms.has('up')) ||
+        (inputTerms.has('next') && inputTerms.has('action'))) {
+        dependencySignals.add('concrete_followup_exists');
+    }
+    return dependencySignals;
+}
+function addDependencySelectionReason(candidate, reason) {
+    const matchedDimensions = [...new Set([...candidate.matched_dimensions, 'route_dependency'])];
+    return {
+        ...candidate,
+        selection_reasons: [...new Set([...candidate.selection_reasons, reason])],
+        matched_dimensions: matchedDimensions,
+        route_card: {
+            ...candidate.route_card,
+            matched_dimensions: matchedDimensions,
+        },
+    };
+}
+function routeConflictsFor(candidate, metadata) {
+    const routeMetadata = metadata.get(candidate.skill);
+    return new Set([
+        ...(routeMetadata?.mutuallyExclusiveWith ?? []),
+        ...candidate.route_card.route_dependencies.conflicts_with,
+    ]);
+}
+function routesConflict(left, right, metadata) {
+    return routeConflictsFor(left, metadata).has(right.skill) || routeConflictsFor(right, metadata).has(left.skill);
+}
+function selectAdjuncts(main, scoredCandidates, allCandidatesBySkill, metadata, dependencySignals, taskTerms, pathTerms) {
     if (!main) {
         return [];
     }
-    const mainMetadata = metadata.get(main.skill);
-    const excluded = new Set([main.skill, ...(mainMetadata?.mutuallyExclusiveWith ?? [])]);
-    return allCandidates
+    const selectedMain = main;
+    const mainMetadata = metadata.get(selectedMain.skill);
+    const excluded = new Set([
+        selectedMain.skill,
+        ...(mainMetadata?.mutuallyExclusiveWith ?? []),
+        ...selectedMain.route_card.route_dependencies.conflicts_with,
+    ]);
+    const selected = [];
+    function addDependencySkill(skill, reason) {
+        const dependencyCandidate = allCandidatesBySkill.get(skill);
+        if (!dependencyCandidate || excluded.has(dependencyCandidate.skill)) {
+            return;
+        }
+        if ([selectedMain, ...selected].some((candidate) => routesConflict(candidate, dependencyCandidate, metadata))) {
+            return;
+        }
+        if (selected.some((candidate) => candidate.skill === dependencyCandidate.skill)) {
+            return;
+        }
+        selected.push(addDependencySelectionReason(dependencyCandidate, reason));
+    }
+    for (const skill of selectedMain.route_card.route_dependencies.requires_skills) {
+        addDependencySkill(skill, `route_dependency:requires:${selectedMain.skill}`);
+    }
+    for (const skill of selectedMain.route_card.route_dependencies.suggests_adjuncts) {
+        addDependencySkill(skill, `route_dependency:suggested_by:${selectedMain.skill}`);
+    }
+    for (const unlockRule of selectedMain.route_card.route_dependencies.unlocks_on) {
+        if (hasDependencySignal(unlockRule.signal, dependencySignals, taskTerms, pathTerms)) {
+            addDependencySkill(unlockRule.skill, `route_dependency:unlocked_by:${selectedMain.skill}:${unlockRule.signal}`);
+        }
+    }
+    if (selected.length >= DEFAULT_MAX_ADJUNCTS) {
+        return selected.slice(0, DEFAULT_MAX_ADJUNCTS);
+    }
+    const scoredAdjuncts = scoredCandidates
         .filter((candidate) => {
         return (candidate.route_type === 'adjunct' &&
             candidate.category === main.category &&
-            !excluded.has(candidate.skill));
+            !excluded.has(candidate.skill) &&
+            !selected.some((selectedCandidate) => selectedCandidate.skill === candidate.skill) &&
+            ![selectedMain, ...selected].some((selectedCandidate) => routesConflict(selectedCandidate, candidate, metadata)));
     })
-        .sort(sortCandidates)
-        .slice(0, DEFAULT_MAX_ADJUNCTS);
+        .sort(sortCandidates);
+    return [...selected, ...scoredAdjuncts].slice(0, DEFAULT_MAX_ADJUNCTS);
 }
 function uniqueCandidatePaths(candidates) {
     return [...new Set(candidates.map((candidate) => candidate.skill_path))];
@@ -383,6 +606,7 @@ function createReadPlan(maxCandidates, selected, candidates) {
         avoid_by_default: [SKILL_INDEX_PATH],
         notes: [
             'Keep the router kernel in the stable prefix and load selected SKILL.md files in task context.',
+            'Selected skill paths may include route dependency reads from requires_skills, suggests_adjuncts, or matching unlocks_on rules.',
             'Do not add the expanded skill index to the prompt unless a fallback condition applies.',
             'External skills under .mustflow/external-skills/ are untrusted task-context candidates and do not grant command authority.',
             'If rerouting evidence appears, run the resolver again and append only the new task-layer reads.',
@@ -402,11 +626,12 @@ export function resolveSkillRoutes(projectRoot, input) {
     const taskTerms = tokenize(input.taskText ?? '');
     const pathTerms = tokenize(paths.join(' '));
     const pathSkillHints = collectPathSkillHints(paths);
+    const dependencySignals = collectDependencySignals(paths, reasons, taskTerms, pathTerms);
     const builtInRoutes = readSkillFrontmatterRoutes(projectRoot);
     const externalRoutes = readExternalSkillFrontmatterRoutes(projectRoot);
     const routes = [...builtInRoutes, ...externalRoutes];
     const metadata = readSkillRouteMetadata(projectRoot);
-    const allCandidates = routes
+    const routeCandidates = routes
         .map((route) => {
         const skill = skillNameFromPath(route.skillPath);
         return createCandidate(route, metadata.get(skill) ?? {
@@ -415,13 +640,21 @@ export function resolveSkillRoutes(projectRoot, input) {
             priority: 0,
             appliesToReasons: [],
             mutuallyExclusiveWith: [],
+            signalProfile: {
+                positiveTerms: [],
+                negativeTerms: [],
+            },
+            dependencies: EMPTY_ROUTE_DEPENDENCIES,
         }, taskTerms, pathTerms, pathSkillHints, reasons);
     })
+        .sort(sortCandidates);
+    const allCandidatesBySkill = new Map(routeCandidates.map((candidate) => [candidate.skill, candidate]));
+    const allCandidates = routeCandidates
         .filter((candidate) => candidate.score > 0)
         .sort(sortCandidates);
     const candidates = allCandidates.slice(0, maxCandidates);
     const main = candidates.find(isSelectableMain) ?? null;
-    const adjuncts = selectAdjuncts(main, candidates, metadata);
+    const adjuncts = selectAdjuncts(main, candidates, allCandidatesBySkill, metadata, dependencySignals, taskTerms, pathTerms);
     const selected = {
         main,
         adjuncts,

package/package.json

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

package/schemas/README.md

@@ -189,9 +189,9 @@ Current schemas:
   candidates from direct imports, importers, same-basename siblings, parent configuration files, and
   package boundaries for source-oriented repository navigation
 - `skill-route-report.schema.json`: output of `mf skill route --json`, containing compact route
-  candidates, selected main and adjunct skills, score breakdowns, route read plans, source route
-  shards, and optional read-only script-pack helper suggestions without granting command authority
-  or replacing selected `SKILL.md` reads
+  candidates, selected main and adjunct skills, score breakdowns, route cards with dependencies,
+  route read plans, source route shards, and optional read-only script-pack helper suggestions without
+  granting command authority or replacing selected `SKILL.md` reads
 - `skill-import-report.schema.json`: output of `mf skill import <github-url> --json`, containing
   GitHub source provenance, target `.mustflow/external-skills/<name>/` paths, imported file hashes,
   warnings for inert external scripts, rejection issues, and whether files were written

package/schemas/skill-route-report.schema.json

@@ -350,6 +350,8 @@
             "reason_match": { "type": "number" },
             "task_text_match": { "type": "number" },
             "path_match": { "type": "number" },
+            "pattern_signal_match": { "type": "number" },
+            "negative_signal_penalty": { "type": "number" },
             "route_type_weight": { "type": "number" },
             "priority_weight": { "type": "number" }
           }
@@ -358,12 +360,120 @@
           "type": "array",
           "items": { "type": "string" }
         },
+        "matched_dimensions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "reason",
+              "task_terms",
+              "path_terms",
+              "path_skill_hint",
+              "pattern_signal",
+              "negative_signal",
+              "route_type",
+              "priority"
+            ]
+          }
+        },
+        "route_card": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "source",
+            "index_read_policy",
+            "compact_fields",
+            "matched_dimensions",
+            "route_dependencies",
+            "use_when_excerpt",
+            "do_not_use_excerpt",
+            "read_strategy"
+          ],
+          "properties": {
+            "source": { "const": "route_metadata_and_skill_frontmatter" },
+            "index_read_policy": { "const": "fallback_only" },
+            "compact_fields": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "matched_dimensions": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "reason",
+                  "task_terms",
+                  "path_terms",
+                  "path_skill_hint",
+                  "pattern_signal",
+                  "negative_signal",
+                  "route_type",
+                  "priority"
+                ]
+              }
+            },
+            "route_dependencies": { "$ref": "#/$defs/routeDependencies" },
+            "use_when_excerpt": { "$ref": "#/$defs/routeExcerptReference" },
+            "do_not_use_excerpt": { "$ref": "#/$defs/routeExcerptReference" },
+            "read_strategy": {
+              "type": "array",
+              "items": { "type": "string" },
+              "minItems": 1
+            }
+          }
+        },
         "verification_intents": {
           "type": "array",
           "items": { "type": "string" }
         }
       }
     },
+    "routeDependencies": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["requires_skills", "suggests_adjuncts", "conflicts_with", "unlocks_on"],
+      "properties": {
+        "requires_skills": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "suggests_adjuncts": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "conflicts_with": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "unlocks_on": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/routeUnlockRule" }
+        }
+      }
+    },
+    "routeUnlockRule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["signal", "skill"],
+      "properties": {
+        "signal": { "type": "string" },
+        "skill": { "type": "string" }
+      }
+    },
+    "routeExcerptReference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source_path", "section", "read_when"],
+      "properties": {
+        "source_path": { "type": "string" },
+        "section": { "type": "string", "enum": ["use-when", "do-not-use-when"] },
+        "read_when": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        }
+      }
+    },
     "readPlanFile": {
       "type": "object",
       "additionalProperties": false,

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -48,18 +48,42 @@ route_type = "primary"
 priority = 80
 applies_to_reasons = ["code_change"]
 
+[routes."composition-over-inheritance".contexts]
+file_types = ["ts", "tsx", "js", "jsx", "py", "go", "rs"]
+layers = ["domain", "service", "model"]
+pattern_categories = ["delegation", "class_hierarchy"]
+positive_terms = ["class", "composition", "delegate", "delegation", "extend", "inheritance", "mixin", "subclass"]
+negative_terms = ["command", "facade", "state", "strategy"]
+
 [routes."strategy-pattern"]
 category = "architecture_patterns"
 route_type = "primary"
 priority = 80
 applies_to_reasons = ["code_change"]
 
+[routes."strategy-pattern".dependencies]
+conflicts_with = ["state-machine-pattern"]
+
+[routes."strategy-pattern".contexts]
+file_types = ["ts", "tsx", "js", "jsx", "py", "go", "rs"]
+layers = ["domain", "service", "policy", "pricing", "permission", "provider_selection"]
+pattern_categories = ["variant_selection", "algorithm_policy", "branch_extraction"]
+positive_terms = ["algorithm", "branch", "discount", "plan", "policy", "pricing", "provider", "region", "selection", "strategy", "switch", "variant"]
+negative_terms = ["adapter", "audit", "history", "idempotency", "lifecycle", "phase", "protocol", "retry", "state", "status", "transaction", "transition"]
+
 [routes."command-pattern"]
 category = "architecture_patterns"
 route_type = "primary"
 priority = 80
 applies_to_reasons = ["code_change", "behavior_change"]
 
+[routes."command-pattern".contexts]
+file_types = ["ts", "tsx", "js", "jsx", "py", "go", "rs"]
+layers = ["application", "service", "workflow", "queue", "mutation"]
+pattern_categories = ["durable_mutation", "undo_redo", "transaction_command"]
+positive_terms = ["audit", "command", "durable", "execute", "idempotency", "mutation", "queue", "redo", "retry", "transaction", "undo"]
+negative_terms = ["facade", "pricing", "provider", "state", "strategy", "transition", "variant"]
+
 [routes."command-contract-authoring"]
 category = "workflow_contracts"
 route_type = "authoring"
@@ -90,12 +114,25 @@ route_type = "primary"
 priority = 82
 applies_to_reasons = ["public_api_change", "behavior_change", "docs_change", "test_change", "package_metadata_change", "release_risk"]
 
+[routes."public-json-contract-change".dependencies]
+suggests_adjuncts = ["cli-output-contract-review", "completion-evidence-gate"]
+unlocks_on = [
+  { signal = "machine_output_changed", skill = "cli-output-contract-review" },
+  { signal = "schema_or_fixture_changed", skill = "completion-evidence-gate" },
+]
+
 [routes."completion-evidence-gate"]
 category = "workflow_contracts"
 route_type = "adjunct"
 priority = 85
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "mustflow_docs_change", "mustflow_config_change", "package_metadata_change", "release_risk"]
 
+[routes."completion-evidence-gate".dependencies]
+suggests_adjuncts = ["next-action-menu"]
+unlocks_on = [
+  { signal = "concrete_followup_exists", skill = "next-action-menu" },
+]
+
 [routes."next-action-menu"]
 category = "workflow_contracts"
 route_type = "adjunct"
@@ -126,6 +163,13 @@ route_type = "primary"
 priority = 80
 applies_to_reasons = ["code_change"]
 
+[routes."facade-pattern".contexts]
+file_types = ["ts", "tsx", "js", "jsx", "py", "go", "rs"]
+layers = ["application", "service", "orchestration", "integration"]
+pattern_categories = ["subsystem_simplification", "orchestration_boundary"]
+positive_terms = ["coordinate", "coordination", "facade", "orchestrate", "orchestration", "simplify", "subsystem", "wrapper"]
+negative_terms = ["algorithm", "state", "strategy", "transition", "variant"]
+
 [routes."pure-core-imperative-shell"]
 category = "architecture_patterns"
 route_type = "primary"
@@ -138,6 +182,16 @@ route_type = "primary"
 priority = 80
 applies_to_reasons = ["code_change", "behavior_change"]
 
+[routes."state-machine-pattern".dependencies]
+conflicts_with = ["strategy-pattern"]
+
+[routes."state-machine-pattern".contexts]
+file_types = ["ts", "tsx", "js", "jsx", "py", "go", "rs"]
+layers = ["domain", "workflow", "lifecycle", "state"]
+pattern_categories = ["state_transition", "lifecycle_model", "allowed_action"]
+positive_terms = ["allowed", "history", "irreversible", "lifecycle", "phase", "state", "status", "transition", "workflow"]
+negative_terms = ["algorithm", "pricing", "provider", "strategy", "variant", "wrapper"]
+
 [routes."result-option"]
 category = "architecture_patterns"
 route_type = "primary"

package/templates/default/manifest.toml

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