mustflow 2.59.0 → 2.69.0

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

@@ -0,0 +1,398 @@
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord, readMustflowOwnedTomlFile } from './config-loading.js';
+import { readUtf8FileInsideWithoutSymlinks } from './safe-filesystem.js';
+const MUSTFLOW_TEXT_MAX_BYTES = 1024 * 1024;
+const SKILL_INDEX_PATH = '.mustflow/skills/INDEX.md';
+const SKILL_ROUTER_PATH = '.mustflow/skills/router.toml';
+const SKILL_ROUTES_METADATA_PATH = '.mustflow/skills/routes.toml';
+const SKILL_FRONTMATTER_SOURCE = '.mustflow/skills/*/SKILL.md';
+const DEFAULT_MAX_CANDIDATES = 5;
+const DEFAULT_MAX_MAIN = 1;
+const DEFAULT_MAX_ADJUNCTS = 2;
+const PATH_SKILL_HINT_SCORE = 25;
+const DOCS_TREE_MARKDOWN_PATH_PATTERN = /(?:^|\/)(?:docs|docs-site|documentation|\.mustflow\/docs|\.mustflow\/context)\/.+\.(?:md|mdx)$/u;
+const ROOT_DOCUMENT_BASENAMES = [
+    'readme',
+    'changelog',
+    'contributing',
+    'security',
+    'support',
+    'governance',
+    'maintainers',
+    'releasing',
+    'release',
+    'testing',
+    'deployment',
+    'operations',
+    'runbook',
+    'configuration',
+    'troubleshooting',
+    'architecture',
+    'api',
+];
+const ROUTE_TYPE_WEIGHTS = {
+    primary: 18,
+    authoring: 16,
+    adjunct: 8,
+    event: 4,
+};
+function normalizeSkillPath(value) {
+    return value.replace(/\\/gu, '/');
+}
+function skillNameFromPath(skillPath) {
+    const match = /^\.mustflow\/skills\/([^/]+)\/SKILL\.md$/u.exec(skillPath);
+    return match?.[1] ?? skillPath;
+}
+function tokenize(value) {
+    return [
+        ...new Set(value
+            .toLowerCase()
+            .replace(/\.mustflow\/skills\/[^/\s]+\/skill\.md/giu, ' ')
+            .replace(/[^a-z0-9]+/gu, ' ')
+            .split(/\s+/u)
+            .map((token) => token.trim())
+            .filter((token) => token.length >= 3)),
+    ].sort((left, right) => left.localeCompare(right));
+}
+function collectPathSkillHints(paths) {
+    const hints = new Set();
+    for (const pathValue of paths) {
+        const lower = pathValue.toLowerCase();
+        if (/\.(?:cts|mts|ts|tsx)$/u.test(lower) || lower.endsWith('tsconfig.json')) {
+            hints.add('typescript-code-change');
+        }
+        if (/\.(?:cjs|mjs|js|jsx)$/u.test(lower)) {
+            hints.add('javascript-code-change');
+        }
+        if (/\.py$/u.test(lower) || /(?:^|\/)(?:pyproject\.toml|requirements\.txt|poetry\.lock)$/u.test(lower)) {
+            hints.add('python-code-change');
+        }
+        if (/\.go$/u.test(lower) || /(?:^|\/)go\.(?:mod|sum)$/u.test(lower)) {
+            hints.add('go-code-change');
+        }
+        if (/\.rs$/u.test(lower) || /(?:^|\/)(?:cargo\.toml|cargo\.lock)$/u.test(lower)) {
+            hints.add('rust-code-change');
+        }
+        if (/\.ps1$/u.test(lower)) {
+            hints.add('powershell-code-change');
+        }
+        if (DOCS_TREE_MARKDOWN_PATH_PATTERN.test(lower) || isRootDocumentationPath(lower)) {
+            hints.add('docs-update');
+        }
+    }
+    return hints;
+}
+function isRootDocumentationPath(lowercasePath) {
+    const basename = lowercasePath.split('/').pop();
+    if (!basename?.endsWith('.md')) {
+        return false;
+    }
+    const rootName = basename.replace(/\.md$/u, '');
+    return ROOT_DOCUMENT_BASENAMES.includes(rootName);
+}
+function readStringArrayFromTable(table, key) {
+    const value = table[key];
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+        ? value.map((entry) => entry.trim()).filter(Boolean)
+        : [];
+}
+function readFrontmatterBlock(content) {
+    if (!content.startsWith('---')) {
+        return [];
+    }
+    const firstLineEnd = content.indexOf('\n');
+    if (firstLineEnd < 0) {
+        return [];
+    }
+    const end = content.indexOf('\n---', firstLineEnd + 1);
+    if (end < 0) {
+        return [];
+    }
+    return content.slice(firstLineEnd + 1, end).split(/\r?\n/u);
+}
+function readFrontmatterScalar(lines, key) {
+    for (const line of lines) {
+        const match = /^([a-zA-Z0-9_]+):\s*(.*)$/u.exec(line);
+        if (match?.[1] === key) {
+            return match[2].trim().replace(/^["']|["']$/gu, '') || null;
+        }
+    }
+    return null;
+}
+function readFrontmatterList(lines, key) {
+    const values = [];
+    let inList = false;
+    let baseIndent = 0;
+    for (const line of lines) {
+        const keyMatch = new RegExp(`^(\\s*)${key}:\\s*$`, 'u').exec(line);
+        if (keyMatch) {
+            inList = true;
+            baseIndent = keyMatch[1].length;
+            continue;
+        }
+        if (!inList) {
+            continue;
+        }
+        const itemMatch = /^(\s*)-\s+(.+?)\s*$/u.exec(line);
+        if (itemMatch && itemMatch[1].length > baseIndent) {
+            values.push(itemMatch[2].trim().replace(/^["']|["']$/gu, ''));
+            continue;
+        }
+        if (line.trim() && !line.startsWith(' '.repeat(baseIndent + 1))) {
+            break;
+        }
+    }
+    return values;
+}
+function readSkillFrontmatterSummary(content) {
+    const lines = readFrontmatterBlock(content);
+    return {
+        name: readFrontmatterScalar(lines, 'name'),
+        description: readFrontmatterScalar(lines, 'description'),
+        commandIntents: readFrontmatterList(lines, 'command_intents'),
+    };
+}
+function readSkillRouteMetadata(projectRoot) {
+    const metadata = new Map();
+    try {
+        const parsed = readMustflowOwnedTomlFile(projectRoot, SKILL_ROUTES_METADATA_PATH);
+        if (!isRecord(parsed) || !isRecord(parsed.routes)) {
+            return metadata;
+        }
+        for (const [skillName, route] of Object.entries(parsed.routes)) {
+            if (!isRecord(route)) {
+                continue;
+            }
+            metadata.set(skillName, {
+                category: typeof route.category === 'string' ? route.category : null,
+                routeType: typeof route.route_type === 'string' ? route.route_type : 'unknown',
+                priority: Number.isInteger(route.priority) ? Number(route.priority) : 0,
+                appliesToReasons: readStringArrayFromTable(route, 'applies_to_reasons'),
+                mutuallyExclusiveWith: readStringArrayFromTable(route, 'mutually_exclusive_with'),
+            });
+        }
+    }
+    catch {
+        return metadata;
+    }
+    return metadata;
+}
+function readSkillFrontmatterRoutes(projectRoot) {
+    const skillRoot = path.join(projectRoot, '.mustflow', 'skills');
+    if (!existsSync(skillRoot)) {
+        return [];
+    }
+    const routes = [];
+    const skillDirectories = readdirSync(skillRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort((left, right) => left.localeCompare(right));
+    for (const skillDirectory of skillDirectories) {
+        const skillPath = `.mustflow/skills/${skillDirectory}/SKILL.md`;
+        const absoluteSkillPath = path.join(projectRoot, ...skillPath.split('/'));
+        if (!existsSync(absoluteSkillPath)) {
+            continue;
+        }
+        const content = readUtf8FileInsideWithoutSymlinks(projectRoot, absoluteSkillPath, {
+            maxBytes: MUSTFLOW_TEXT_MAX_BYTES,
+        });
+        const summary = readSkillFrontmatterSummary(content);
+        const skillName = summary.name ?? skillDirectory;
+        routes.push({
+            trigger: summary.description ?? skillName,
+            skillPath,
+            requiredInput: '',
+            editScope: '',
+            risk: '',
+            commandIntents: summary.commandIntents,
+            expectedOutput: '',
+        });
+    }
+    return routes;
+}
+function countMatches(needles, haystack) {
+    const haystackSet = new Set(haystack);
+    return needles.filter((needle) => haystackSet.has(needle)).length;
+}
+function routeTextTerms(route, skillName) {
+    return tokenize([
+        skillName,
+        route.trigger,
+        route.requiredInput,
+        route.editScope,
+        route.risk,
+        route.expectedOutput,
+        route.skillPath,
+    ].join(' '));
+}
+function createCandidate(route, metadata, taskTerms, pathTerms, pathSkillHints, reasons) {
+    const skill = skillNameFromPath(route.skillPath);
+    const terms = routeTextTerms(route, skill);
+    const matchedReasons = reasons.filter((reason) => metadata.appliesToReasons.includes(reason));
+    const taskMatches = countMatches(taskTerms, terms);
+    const pathMatches = countMatches(pathTerms, terms);
+    const pathSkillHintMatched = pathSkillHints.has(skill);
+    const breakdown = {
+        reason_match: matchedReasons.length * 35,
+        task_text_match: taskMatches * 6,
+        path_match: pathMatches * 6 + (pathSkillHintMatched ? PATH_SKILL_HINT_SCORE : 0),
+        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 selectionReasons = [
+        ...matchedReasons.map((reason) => `reason:${reason}`),
+        ...(taskMatches > 0 ? [`task_terms:${taskMatches}`] : []),
+        ...(pathMatches > 0 ? [`path_terms:${pathMatches}`] : []),
+        ...(pathSkillHintMatched ? [`path_skill_hint:${skill}`] : []),
+        `route_type:${metadata.routeType}`,
+        `priority:${metadata.priority}`,
+    ];
+    return {
+        skill,
+        skill_path: route.skillPath,
+        trigger: route.trigger,
+        category: metadata.category,
+        route_type: metadata.routeType,
+        priority: metadata.priority,
+        applies_to_reasons: metadata.appliesToReasons,
+        score,
+        score_breakdown: breakdown,
+        selection_reasons: selectionReasons,
+        verification_intents: route.commandIntents,
+    };
+}
+function sortCandidates(left, right) {
+    const score = right.score - left.score;
+    if (score !== 0) {
+        return score;
+    }
+    const priority = right.priority - left.priority;
+    if (priority !== 0) {
+        return priority;
+    }
+    return left.skill.localeCompare(right.skill);
+}
+function isSelectableMain(candidate) {
+    return candidate.route_type === 'primary' || candidate.route_type === 'authoring';
+}
+function selectAdjuncts(main, allCandidates, metadata) {
+    if (!main) {
+        return [];
+    }
+    const mainMetadata = metadata.get(main.skill);
+    const excluded = new Set([main.skill, ...(mainMetadata?.mutuallyExclusiveWith ?? [])]);
+    return allCandidates
+        .filter((candidate) => {
+        return (candidate.route_type === 'adjunct' &&
+            candidate.category === main.category &&
+            !excluded.has(candidate.skill));
+    })
+        .sort(sortCandidates)
+        .slice(0, DEFAULT_MAX_ADJUNCTS);
+}
+function uniqueCandidatePaths(candidates) {
+    return [...new Set(candidates.map((candidate) => candidate.skill_path))];
+}
+function createReadPlan(maxCandidates, selected, candidates) {
+    const selectedCandidates = [selected.main, ...selected.adjuncts].filter((candidate) => candidate !== null);
+    return {
+        selection_limits: {
+            candidates: maxCandidates,
+            main: DEFAULT_MAX_MAIN,
+            adjuncts: DEFAULT_MAX_ADJUNCTS,
+        },
+        stable_kernel: [SKILL_ROUTER_PATH],
+        selected_skill_paths: uniqueCandidatePaths(selectedCandidates),
+        candidate_skill_paths: uniqueCandidatePaths(candidates),
+        fallback_route_metadata: {
+            path: SKILL_ROUTES_METADATA_PATH,
+            read_when: [
+                'router taxonomy is insufficient',
+                'task edits skill routing',
+                'detailed route metadata is needed',
+                'category or confidence is ambiguous',
+                'selected skill paths are empty',
+            ],
+        },
+        expanded_index: {
+            path: SKILL_INDEX_PATH,
+            read_when: [
+                'full route metadata is insufficient',
+                'task edits the expanded route table',
+                'human-readable trigger evidence is needed',
+            ],
+        },
+        avoid_by_default: [SKILL_INDEX_PATH],
+        notes: [
+            'Keep the router kernel in the stable prefix and load selected SKILL.md files in task context.',
+            'Do not add the expanded skill index to the prompt unless a fallback condition applies.',
+            'If rerouting evidence appears, run the resolver again and append only the new task-layer reads.',
+        ],
+    };
+}
+function clampCandidateLimit(value) {
+    if (value === undefined || !Number.isInteger(value)) {
+        return DEFAULT_MAX_CANDIDATES;
+    }
+    return Math.max(1, Math.min(value, 10));
+}
+export function resolveSkillRoutes(projectRoot, input) {
+    const maxCandidates = clampCandidateLimit(input.maxCandidates);
+    const paths = input.paths.map(normalizeSkillPath);
+    const reasons = [...new Set(input.reasons.map((reason) => reason.trim()).filter(Boolean))].sort((left, right) => left.localeCompare(right));
+    const taskTerms = tokenize(input.taskText ?? '');
+    const pathTerms = tokenize(paths.join(' '));
+    const pathSkillHints = collectPathSkillHints(paths);
+    const routes = readSkillFrontmatterRoutes(projectRoot);
+    const metadata = readSkillRouteMetadata(projectRoot);
+    const allCandidates = routes
+        .map((route) => {
+        const skill = skillNameFromPath(route.skillPath);
+        return createCandidate(route, metadata.get(skill) ?? {
+            category: route.category ?? null,
+            routeType: 'unknown',
+            priority: 0,
+            appliesToReasons: [],
+            mutuallyExclusiveWith: [],
+        }, taskTerms, pathTerms, pathSkillHints, reasons);
+    })
+        .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 selected = {
+        main,
+        adjuncts,
+    };
+    return {
+        schema_version: '1',
+        kind: 'skill_route_resolution',
+        input: {
+            task_text_present: Boolean(input.taskText?.trim()),
+            paths,
+            reasons,
+            max_candidates: maxCandidates,
+        },
+        signals: {
+            task_terms: taskTerms,
+            path_terms: pathTerms,
+            reasons,
+            read_shards: [SKILL_ROUTES_METADATA_PATH, SKILL_FRONTMATTER_SOURCE],
+        },
+        selected,
+        candidates,
+        read_plan: createReadPlan(maxCandidates, selected, candidates),
+        source_files: [SKILL_ROUTES_METADATA_PATH, SKILL_FRONTMATTER_SOURCE],
+        gap_notes: [
+            [
+                'This resolver is a read-only routing prepass.',
+                'It narrows skill candidates from route metadata and skill frontmatter',
+                'but does not replace reading the selected SKILL.md.',
+            ].join(' '),
+            'Command execution authority still comes only from .mustflow/config/commands.toml.',
+        ],
+    };
+}

package/dist/core/source-anchors.js

@@ -265,11 +265,90 @@ export function sourceAnchorPathIsGeneratedOrVendor(relativePath) {
 export function sourceAnchorTextContainsSecretLike(value) {
     return textContainsSecretLike(value);
 }
-export function parseSourceAnchorsInContent(relativePath, content) {
+function collectCommentLines(content) {
     const lines = content.split(/\r?\n/);
+    const commentLines = [];
+    let insideBlockComment = false;
+    let stringQuote = null;
+    let escaped = false;
+    let lineIndex = 0;
+    while (lineIndex < lines.length) {
+        const line = lines[lineIndex] ?? '';
+        let index = 0;
+        while (index < line.length) {
+            if (insideBlockComment) {
+                const endIndex = line.indexOf('*/', index);
+                const segmentEnd = endIndex === -1 ? line.length : endIndex;
+                commentLines.push({ lineNumber: lineIndex + 1, text: line.slice(index, segmentEnd) });
+                if (endIndex === -1) {
+                    index = line.length;
+                    continue;
+                }
+                insideBlockComment = false;
+                index = endIndex + 2;
+                continue;
+            }
+            const character = line[index];
+            const nextCharacter = line[index + 1];
+            if (stringQuote) {
+                if (escaped) {
+                    escaped = false;
+                    index += 1;
+                    continue;
+                }
+                if (character === '\\') {
+                    escaped = true;
+                    index += 1;
+                    continue;
+                }
+                if (character === stringQuote) {
+                    stringQuote = null;
+                }
+                index += 1;
+                continue;
+            }
+            if (character === '"' || character === "'" || character === '`') {
+                stringQuote = character;
+                index += 1;
+                continue;
+            }
+            if (character === '/' && nextCharacter === '*') {
+                const commentStart = index + 2;
+                const endIndex = line.indexOf('*/', commentStart);
+                const segmentEnd = endIndex === -1 ? line.length : endIndex;
+                commentLines.push({ lineNumber: lineIndex + 1, text: line.slice(commentStart, segmentEnd) });
+                if (endIndex === -1) {
+                    insideBlockComment = true;
+                    index = line.length;
+                    continue;
+                }
+                index = endIndex + 2;
+                continue;
+            }
+            if (character === '/' && nextCharacter === '/') {
+                commentLines.push({ lineNumber: lineIndex + 1, text: line.slice(index + 2) });
+                break;
+            }
+            if (character === '#' && line.slice(0, index).trim().length === 0) {
+                commentLines.push({ lineNumber: lineIndex + 1, text: line.slice(index + 1) });
+                break;
+            }
+            index += 1;
+        }
+        if (stringQuote !== '`') {
+            stringQuote = null;
+        }
+        escaped = false;
+        lineIndex += 1;
+    }
+    return commentLines;
+}
+export function parseSourceAnchorsInContent(relativePath, content) {
+    const lines = collectCommentLines(content);
     const anchors = [];
     for (let index = 0; index < lines.length; index += 1) {
-        const normalized = stripSourceAnchorCommentPrefix(lines[index] ?? '');
+        const commentLine = lines[index];
+        const normalized = stripSourceAnchorCommentPrefix(commentLine?.text ?? '');
         if (!normalized.startsWith('mf:anchor')) {
             continue;
         }
@@ -278,12 +357,18 @@ export function parseSourceAnchorsInContent(relativePath, content) {
         const fields = new Map();
         const unsupportedFields = [];
         const rawLines = [normalized];
+        let previousLineNumber = commentLine?.lineNumber ?? 0;
         for (let fieldIndex = index + 1; fieldIndex < lines.length; fieldIndex += 1) {
-            const fieldLine = stripSourceAnchorCommentPrefix(lines[fieldIndex] ?? '');
+            const nextCommentLine = lines[fieldIndex];
+            if (!nextCommentLine || nextCommentLine.lineNumber > previousLineNumber + 1) {
+                break;
+            }
+            const fieldLine = stripSourceAnchorCommentPrefix(nextCommentLine.text);
             if (fieldLine.length === 0) {
+                previousLineNumber = nextCommentLine.lineNumber;
                 continue;
             }
-            if (fieldLine.startsWith('@') || /^[A-Za-z_$][\w$]*\s/u.test(fieldLine)) {
+            if (fieldLine.startsWith('mf:anchor') || fieldLine.startsWith('@') || /^[A-Za-z_$][\w$]*\s/u.test(fieldLine)) {
                 break;
             }
             const field = readSourceAnchorField(fieldLine);
@@ -291,6 +376,7 @@ export function parseSourceAnchorsInContent(relativePath, content) {
                 break;
             }
             rawLines.push(fieldLine);
+            previousLineNumber = nextCommentLine.lineNumber;
             if (!SOURCE_ANCHOR_ALLOWED_FIELDS.has(field.key)) {
                 unsupportedFields.push(field.key);
                 continue;
@@ -302,7 +388,7 @@ export function parseSourceAnchorsInContent(relativePath, content) {
             rawId,
             idValid: SOURCE_ANCHOR_ID_PATTERN.test(rawId),
             path: relativePath,
-            lineStart: index + 1,
+            lineStart: commentLine?.lineNumber ?? index + 1,
             fields,
             unsupportedFields,
             rawText: rawLines.join('\n'),

package/package.json

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

package/schemas/README.md

@@ -7,7 +7,7 @@ Current schemas:
 
 - `doctor-report.schema.json`: output of `mf doctor --json`
 - `adapter-compatibility-report.schema.json`: output of `mf adapters status --json`
-- `context-report.schema.json`: output of `mf context --json`
+- `context-report.schema.json`: output of `mf context --json`, including prompt-cache profiles and optional cache audit data
 - `workspace-summary.schema.json`: output of `mf api workspace-summary --json`
 - `command-catalog.schema.json`: output of `mf api command-catalog --json`
 - `verification-plan.schema.json`: output of `mf api verification-plan --changed --json`
@@ -51,7 +51,12 @@ Current schemas:
   `mf line-endings normalize --json`
 - `quality-gaming-report.schema.json`: output of `mf quality check --json`, containing changed-file
   quality-gaming risks such as line stuffing, validation suppressions, test bypass markers, type
-  escapes, generated/vendor logic, and placeholder implementations
+  escapes, generated/vendor logic, empty catch swallowing, and placeholder implementations
+- `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, and source
+  route shards without granting command authority or replacing selected `SKILL.md` reads
+- `route-fixture.schema.json`: parsed `.mustflow/skills/route-fixtures.json`, containing strict
+  skill-route golden cases with required and forbidden route expectations
 - `latest-run-pointer.schema.json`: `.mustflow/state/runs/latest.json` when `mf verify` writes a
   pointer to the latest verify run bundle, including the verify completion verdict, evidence model,
   and coverage matrix