mustflow 2.114.6 → 2.114.12

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.12",
   "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/i18n.toml

@@ -10,12 +10,12 @@ status_values = ["current", "stale", "needs_review", "missing"]
 [documents."agents.root"]
 source = "locales/en/AGENTS.md"
 source_locale = "en"
-revision = 21
-translations.ko = { path = "locales/ko/AGENTS.md", source_revision = 21, status = "current" }
-translations.zh = { path = "locales/zh/AGENTS.md", source_revision = 21, status = "needs_review" }
-translations.es = { path = "locales/es/AGENTS.md", source_revision = 21, status = "needs_review" }
-translations.fr = { path = "locales/fr/AGENTS.md", source_revision = 21, status = "needs_review" }
-translations.hi = { path = "locales/hi/AGENTS.md", source_revision = 21, status = "needs_review" }
+revision = 22
+translations.ko = { path = "locales/ko/AGENTS.md", source_revision = 22, status = "current" }
+translations.zh = { path = "locales/zh/AGENTS.md", source_revision = 22, status = "needs_review" }
+translations.es = { path = "locales/es/AGENTS.md", source_revision = 22, status = "needs_review" }
+translations.fr = { path = "locales/fr/AGENTS.md", source_revision = 22, status = "needs_review" }
+translations.hi = { path = "locales/hi/AGENTS.md", source_revision = 22, status = "needs_review" }
 
 [documents."context.index"]
 source = "locales/en/.mustflow/context/INDEX.md"

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/locales/en/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: en
 canonical: true
-revision: 21
+revision: 22
 lifecycle: user-editable
 authority: binding
 ---
@@ -123,6 +123,15 @@ mustflow-managed details are under `.mustflow/`.
 - If the nested repository has no local preferences file, apply the nearest parent mustflow
   preferences as inherited defaults while still following the nested repository's `AGENTS.md` and
   command contract.
+- When this mustflow root is used as a workspace for nested repositories, treat this root's
+  `.mustflow/skills/` router, routes, index, and installed `SKILL.md` files as a shared
+  workspace skill registry. Check the shared registry for task procedures in addition to the
+  nested repository's local routing files.
+- Shared workspace skills provide procedure guidance only. They do not override the nested
+  repository's `AGENTS.md`, command contract, edit scope, safety rules, or source of truth.
+- If a nested repository lacks a local skill index or uses a different local agent convention,
+  do not treat that absence as meaning no applicable workspace-level skill exists; consult the
+  shared workspace registry while keeping child-repository authority local.
 - In repository farms, prefer each child repository's own command contract for repository-owned
   commands. If the parent root intentionally orchestrates children, split parent-owned commands
   into repo-named fragments under `.mustflow/config/commands/`; use

package/templates/default/locales/es/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: es
 canonical: false
-revision: 10
+revision: 11
 lifecycle: user-editable
 authority: binding
 ---
@@ -59,6 +59,9 @@ Los detalles gestionados por mustflow se encuentran en `.mustflow/`.
 - Las reglas de seguridad sobre secretos, privacidad, comandos destructivos y rutas permitidas de edición son acumulativas. Aplica la regla más estricta.  
 - Al entrar en un repositorio anidado, vuelve a leer su `AGENTS.md` y `.mustflow/config/*.toml` antes de editar.  
 - Si el repositorio anidado no tiene un archivo local de preferences, aplica las preferences del mustflow padre más cercano como valores heredados mientras sigues obedeciendo el `AGENTS.md` y el command contract del repositorio anidado.
+- Cuando este mustflow root se use como workspace para repositorios anidados, trata el router, las routes, el index y los archivos `SKILL.md` instalados bajo `.mustflow/skills/` de este root como un shared workspace skill registry. Revisa ese registro compartido para elegir procedimientos de tarea junto con los archivos locales de routing del repositorio anidado.
+- Las shared workspace skills solo orientan el procedimiento. No reemplazan el `AGENTS.md`, el command contract, el alcance de edición, las reglas de seguridad ni la fuente de verdad del repositorio anidado.
+- Si un repositorio anidado no tiene un skill index local o usa una convención local de agentes diferente, no concluyas que no existe ninguna skill de workspace aplicable; consulta el shared workspace registry manteniendo local la autoridad del repositorio hijo.
 - No edites fuera del repositorio hijo seleccionado salvo solicitud explícita.  
 
 ## Compatibilidad con Instrucciones del Host

package/templates/default/locales/fr/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: fr
 canonical: false
-revision: 10
+revision: 11
 lifecycle: user-editable
 authority: binding
 ---
@@ -60,6 +60,9 @@ Les détails gérés par mustflow se trouvent dans `.mustflow/`.
 - Les règles de sécurité sur les secrets, la vie privée, les commandes destructrices et les chemins d’édition autorisés sont cumulatives. Appliquer la règle la plus stricte.  
 - Lors de la navigation vers un dépôt imbriqué, relire le `AGENTS.md` de ce dépôt et `.mustflow/config/*.toml` avant d’éditer.  
 - Si le dépôt imbriqué n’a pas de fichier preferences local, appliquer les preferences du mustflow parent le plus proche comme valeurs héritées tout en continuant de suivre le `AGENTS.md` et le command contract du dépôt imbriqué.
+- Lorsque ce mustflow root sert de workspace pour des dépôts imbriqués, traiter le router, les routes, l’index et les fichiers `SKILL.md` installés sous `.mustflow/skills/` dans ce root comme un shared workspace skill registry. Consulter ce registre partagé pour les procédures de tâche en plus des fichiers de routing locaux du dépôt imbriqué.
+- Les shared workspace skills ne fournissent qu’un guidage de procédure. Elles ne remplacent pas le `AGENTS.md`, le command contract, le périmètre d’édition, les règles de sécurité ni la source de vérité du dépôt imbriqué.
+- Si un dépôt imbriqué n’a pas d’index de skills local ou utilise une convention d’agent locale différente, ne pas conclure qu’aucune skill de workspace ne s’applique ; consulter le shared workspace registry tout en gardant l’autorité du dépôt enfant locale.
 - Ne pas éditer en dehors du dépôt enfant sélectionné, sauf demande explicite.  
 
 ## Compatibilité avec les instructions du host

package/templates/default/locales/hi/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: hi
 canonical: false
-revision: 10
+revision: 11
 lifecycle: user-editable
 authority: binding
 ---
@@ -59,6 +59,9 @@ mustflow द्वारा प्रबंधित विवरण `.mustflow/
 - secrets, गोपनीयता, destructive commands, और अनुमत संपादन मार्गों के सुरक्षा नियम संचयी होते हैं। अधिक सख्त नियम अपनाएं।  
 - nested रिपॉजिटरी में जाने पर संपादन से पहले उसका `AGENTS.md` और `.mustflow/config/*.toml` फिर से पढ़ें।  
 - यदि nested repository में local preferences file नहीं है, तो nested repository के `AGENTS.md` और command contract का पालन करते हुए निकटतम parent mustflow preferences को inherited defaults के रूप में लागू करें।
+- जब यह mustflow root nested repositories के लिए workspace के रूप में उपयोग हो, तो इस root के `.mustflow/skills/` router, routes, index, और installed `SKILL.md` files को shared workspace skill registry मानें। nested repository की local routing files के साथ इस shared registry को भी task procedures चुनने के लिए देखें।
+- Shared workspace skills केवल procedure guidance देती हैं। वे nested repository के `AGENTS.md`, command contract, edit scope, safety rules, या source of truth को override नहीं करतीं।
+- यदि किसी nested repository में local skill index नहीं है या वह अलग local agent convention उपयोग करती है, तो यह न मानें कि कोई workspace-level skill लागू नहीं है; child-repository authority को local रखते हुए shared workspace registry देखें।
 - स्पष्ट अनुरोध के बिना चुनी हुई child रिपॉजिटरी के बाहर संपादन न करें।  
 
 ## होस्ट-विशिष्ट निर्देश अनुकूलता

package/templates/default/locales/ko/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: ko
 canonical: false
-revision: 28
+revision: 29
 lifecycle: user-editable
 authority: binding
 ---
@@ -74,6 +74,9 @@ mustflow가 관리하는 세부 문서와 설정은 `.mustflow/` 폴더 아래
 - 보안, 비밀 정보, 개인정보, 파괴적 명령, 수정 가능 경로 등 안전 규칙은 누적 적용하며 더 엄격한 규칙을 따릅니다.  
 - 상위 작업 공간에서 하위 저장소로 진입한 경우, 하위 저장소의 `AGENTS.md`와 `.mustflow/config/*.toml`을 다시 읽은 뒤 작업합니다.  
 - 하위 저장소에 로컬 preferences 파일이 없다면, 하위 저장소의 `AGENTS.md`와 command contract를 계속 따르면서 가장 가까운 상위 mustflow preferences를 상속 기본값으로 적용합니다.
+- 이 mustflow 루트를 하위 저장소 작업 공간으로 사용하는 경우, 이 루트의 `.mustflow/skills/` router, routes, index, 설치된 `SKILL.md` 파일을 공유 workspace skill registry로 취급합니다. 하위 저장소의 로컬 라우팅 파일과 함께 이 공유 registry도 확인해 현재 작업에 맞는 절차를 선택합니다.
+- 공유 workspace skill은 절차 안내일 뿐입니다. 하위 저장소의 `AGENTS.md`, command contract, 수정 범위, 안전 규칙, source of truth를 덮어쓰지 않습니다.
+- 하위 저장소에 로컬 skill index가 없거나 다른 로컬 agent convention을 사용하더라도, 적용 가능한 workspace-level skill이 없다고 단정하지 않습니다. 하위 저장소의 권한은 로컬에 둔 채 공유 workspace registry를 함께 확인합니다.
 - repository farm에서는 각 하위 저장소가 소유한 명령은 해당 저장소의 command contract를 우선합니다. 상위 루트가 하위 저장소를 의도적으로 orchestration해야 한다면 상위 소유 명령을 `.mustflow/config/commands/` 아래 repo 이름별 fragment로 나누고, `mf workspace command-fragments`로 읽기 전용 안내를 확인합니다.  
 - 명시적 요청 없이 선택한 하위 저장소 밖의 파일은 수정하지 않습니다.
 

package/templates/default/locales/zh/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: zh
 canonical: false
-revision: 10
+revision: 11
 lifecycle: user-editable
 authority: binding
 ---
@@ -60,6 +60,9 @@ authority: binding
 - 针对 secrets、隐私、破坏性命令和允许编辑路径的安全规则为累加，执行更严格的规则。  
 - 进入嵌套仓库时，编辑前应重新阅读该仓库的 `AGENTS.md` 和 `.mustflow/config/*.toml`。  
 - 如果嵌套仓库没有本地 preferences 文件，在继续遵循该仓库 `AGENTS.md` 和 command contract 的同时，使用最近父级 mustflow preferences 作为继承默认值。
+- 当此 mustflow root 被用作嵌套仓库的 workspace 时，应将此 root 下 `.mustflow/skills/` 的 router、routes、index 以及已安装的 `SKILL.md` 文件视为 shared workspace skill registry。除嵌套仓库的本地 routing 文件外，也要检查该共享 registry 来选择任务流程。
+- Shared workspace skills 只提供流程指导，不会覆盖嵌套仓库的 `AGENTS.md`、command contract、编辑范围、安全规则或事实来源。
+- 如果嵌套仓库没有本地 skill index，或使用不同的本地 agent convention，不要因此认定没有适用的 workspace-level skill；在保持子仓库权限本地化的前提下检查 shared workspace registry。
 - 未经明确请求，不得编辑所选子仓库之外的内容。  
 
 ## 宿主专用指令兼容性

package/templates/default/manifest.toml

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