mustflow 2.58.1 → 2.68.6

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

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

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.',
+        ],
+    };
+}