mustflow 1.15.97

package/dist/core/public-surface-explanation.js

@@ -0,0 +1,49 @@
+import { classifyChangePath } from './change-classification.js';
+const SOURCE_FILES = [
+    'ROADMAP.md',
+    'README.md',
+    '.mustflow/docs/agent-workflow.md',
+    '.mustflow/config/commands.toml',
+    '.mustflow/config/preferences.toml',
+];
+const OVERVIEW_CLASSIFICATION = {
+    kind: 'public_surface_model',
+    category: 'policy',
+    isPublicSurface: false,
+    validationReasons: [],
+    affectedContracts: ['change classification', 'verification selection', 'future public-surface drift checks'],
+    updatePolicy: 'not_applicable',
+    driftChecks: ['docs', 'templates', 'translations', 'examples', 'schemas'],
+};
+function toPosixPath(value) {
+    return value.split('\\').join('/');
+}
+export function explainPublicSurface(relativePath) {
+    if (!relativePath) {
+        return {
+            kind: 'overview',
+            inputPath: null,
+            decision: 'public surfaces are classified from repository-relative paths',
+            reason: 'mustflow needs a shared model for README pages, docs-site pages, installed templates, generated examples, translations, and workflow roots before stronger drift checks can depend on it.',
+            effectiveAction: 'Use mf explain surface <path> to inspect how a changed file should affect future verification and contract checks.',
+            countsAsMustflowVerification: false,
+            sourceFiles: SOURCE_FILES,
+            surface: OVERVIEW_CLASSIFICATION,
+        };
+    }
+    const normalizedPath = toPosixPath(relativePath);
+    const surface = classifyChangePath(normalizedPath).surface;
+    const publicLabel = surface.isPublicSurface ? 'public surface' : 'non-public or internal surface';
+    return {
+        kind: 'classified',
+        inputPath: normalizedPath,
+        decision: `${normalizedPath} is classified as ${surface.kind}`,
+        reason: `The path matches the ${surface.category} ${publicLabel} rule.`,
+        effectiveAction: surface.validationReasons.length > 0
+            ? `Consider verification reasons: ${surface.validationReasons.join(', ')}.`
+            : 'No specific public-surface verification reason is declared for this path yet.',
+        countsAsMustflowVerification: false,
+        sourceFiles: SOURCE_FILES,
+        surface,
+    };
+}

package/dist/core/release-version-validation.js

@@ -0,0 +1,53 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord } from './config-loading.js';
+import { readTomlFile } from './toml.js';
+import { evaluateVersionSync } from './version-sync-policy.js';
+export const PACKAGE_JSON_VERSION_SOURCE_PATH = 'package.json';
+export const DEFAULT_TEMPLATE_MANIFEST_PATH = 'templates/default/manifest.toml';
+function releaseVersioningSyncsTemplateVersion(preferencesToml) {
+    if (!preferencesToml || !isRecord(preferencesToml.release)) {
+        return false;
+    }
+    const { versioning } = preferencesToml.release;
+    return isRecord(versioning) && versioning.sync_template_version === true;
+}
+function readPackageJsonVersion(filePath) {
+    try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
+        return isRecord(parsed) && typeof parsed.version === 'string' ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readTomlRootVersion(filePath) {
+    try {
+        const parsed = readTomlFile(filePath);
+        return isRecord(parsed) && typeof parsed.version === 'string' ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * mf:anchor core.release-version-validation
+ * purpose: Validate release version synchronization between package and installed template metadata.
+ * search: sync_template_version, package.json version, template manifest version
+ * invariant: Template version synchronization is checked only when the repository preference enables it.
+ * risk: dependency, data_consistency
+ */
+export function validateTemplateVersionSync(projectRoot, preferencesToml, changedPaths) {
+    const packageVersion = readPackageJsonVersion(path.join(projectRoot, PACKAGE_JSON_VERSION_SOURCE_PATH));
+    const templateVersion = readTomlRootVersion(path.join(projectRoot, DEFAULT_TEMPLATE_MANIFEST_PATH));
+    const syncTemplateVersion = releaseVersioningSyncsTemplateVersion(preferencesToml);
+    return evaluateVersionSync({
+        packageVersion,
+        templateVersion,
+        syncTemplateVersion,
+        changedPaths,
+    }).issues.map((issue) => ({
+        message: issue.message,
+        severity: issue.severity,
+    }));
+}

package/dist/core/retention-explanation.js

@@ -0,0 +1,74 @@
+import { isRecord, readPositiveInteger, readString, } from './config-loading.js';
+import { readNestedRetentionTable, readRetentionTable, resolveRetentionLimits, resolveRunReceiptRetentionPolicy, } from './retention-policy.js';
+const RETENTION_POLICY_SOURCE_FILES = [
+    'AGENTS.md',
+    '.mustflow/docs/agent-workflow.md',
+    '.mustflow/config/mustflow.toml',
+];
+function readBoolean(table, key) {
+    const value = table?.[key];
+    return typeof value === 'boolean' ? value : null;
+}
+function summarizeRawEvents(retention) {
+    const rawEvents = readNestedRetentionTable(retention, 'raw_events');
+    return {
+        store: rawEvents ? readString(rawEvents, 'store') ?? null : null,
+        maxFileMb: rawEvents ? readPositiveInteger(rawEvents, 'max_file_mb') ?? null : null,
+        maxTotalMb: rawEvents ? readPositiveInteger(rawEvents, 'max_total_mb') ?? null : null,
+        maxAgeDays: rawEvents ? readPositiveInteger(rawEvents, 'max_age_days') ?? null : null,
+        onLimit: rawEvents ? readString(rawEvents, 'on_limit') ?? null : null,
+    };
+}
+function summarizeKnowledge(retention, maxFileKb) {
+    const knowledge = readNestedRetentionTable(retention, 'knowledge');
+    return {
+        enabled: readBoolean(knowledge, 'enabled'),
+        store: knowledge ? readString(knowledge, 'store') ?? null : null,
+        maxFileKb,
+        maxTotalMb: knowledge ? readPositiveInteger(knowledge, 'max_total_mb') ?? null : null,
+    };
+}
+function summarizeRetention(mustflowToml) {
+    const retention = readRetentionTable(mustflowToml);
+    const limits = resolveRetentionLimits(mustflowToml);
+    const runReceipts = resolveRunReceiptRetentionPolicy(mustflowToml);
+    return {
+        enabled: readBoolean(retention, 'enabled') ?? false,
+        rawEvents: summarizeRawEvents(retention),
+        runReceipts,
+        knowledge: summarizeKnowledge(retention, limits.knowledgeMaxFileKb),
+        context: {
+            maxFileKb: limits.contextMaxFileKb,
+        },
+        repoMap: {
+            maxFileKb: limits.repoMapMaxFileKb,
+            failIfLarger: limits.repoMapFailIfLarger,
+        },
+    };
+}
+function describeRetentionDecision(retention) {
+    if (!retention.enabled) {
+        return {
+            decision: 'retention policy is not enabled',
+            reason: 'the [retention] table is missing or does not set enabled = true.',
+            effectiveAction: 'Treat retention as unavailable and avoid assuming raw events, run receipts, or knowledge files are preserved.',
+        };
+    }
+    return {
+        decision: 'retention policy is enabled',
+        reason: `run receipts are stored as ${retention.runReceipts.store} with stdout and stderr tails capped at ` +
+            `${retention.runReceipts.stdoutTailBytes} bytes and ${retention.runReceipts.stderrTailBytes} bytes.`,
+        effectiveAction: 'Use bounded run receipts for verification evidence, and do not treat raw event storage as available unless the configured store permits it.',
+    };
+}
+export function explainRetentionPolicy(mustflowToml) {
+    const retention = summarizeRetention(isRecord(mustflowToml) ? mustflowToml : undefined);
+    const description = describeRetentionDecision(retention);
+    return {
+        kind: 'retention',
+        ...description,
+        countsAsMustflowVerification: false,
+        sourceFiles: RETENTION_POLICY_SOURCE_FILES,
+        retention,
+    };
+}

package/dist/core/retention-policy.js

@@ -0,0 +1,57 @@
+import { isRecord, readPositiveInteger, readString } from './config-loading.js';
+export const ALLOWED_RETENTION_STORES = new Set(['none', 'cache', 'repo_local_ignored']);
+export const ALLOWED_RETENTION_ON_LIMIT = new Set(['report', 'compact_then_archive']);
+export const DEFAULT_RETENTION_LIMITS = {
+    repoMapMaxFileKb: 128,
+    repoMapFailIfLarger: true,
+    runReceiptMaxFileKb: 128,
+    contextMaxFileKb: 8,
+    knowledgeMaxFileKb: 128,
+};
+export const DEFAULT_RUN_RECEIPT_TAIL_BYTES = 64 * 1024;
+export function readRetentionTable(mustflowToml) {
+    return mustflowToml && isRecord(mustflowToml.retention) ? mustflowToml.retention : undefined;
+}
+export function readNestedRetentionTable(retention, key) {
+    if (!retention || !isRecord(retention[key])) {
+        return undefined;
+    }
+    return retention[key];
+}
+export function readRetentionStore(retention, tableName) {
+    const table = readNestedRetentionTable(retention, tableName);
+    return table ? readString(table, 'store') : undefined;
+}
+function readPositiveIntegerWithDefault(table, key, fallback) {
+    return table ? readPositiveInteger(table, key) ?? fallback : fallback;
+}
+function readBooleanWithDefault(table, key, fallback) {
+    const value = table?.[key];
+    return typeof value === 'boolean' ? value : fallback;
+}
+export function resolveRetentionLimits(mustflowToml) {
+    const retention = readRetentionTable(mustflowToml);
+    const repoMap = readNestedRetentionTable(retention, 'repo_map');
+    const runReceipts = readNestedRetentionTable(retention, 'run_receipts');
+    const context = readNestedRetentionTable(retention, 'context');
+    const knowledge = readNestedRetentionTable(retention, 'knowledge');
+    return {
+        repoMapMaxFileKb: readPositiveIntegerWithDefault(repoMap, 'max_file_kb', DEFAULT_RETENTION_LIMITS.repoMapMaxFileKb),
+        repoMapFailIfLarger: readBooleanWithDefault(repoMap, 'fail_if_larger', DEFAULT_RETENTION_LIMITS.repoMapFailIfLarger),
+        runReceiptMaxFileKb: readPositiveIntegerWithDefault(runReceipts, 'max_file_kb', DEFAULT_RETENTION_LIMITS.runReceiptMaxFileKb),
+        contextMaxFileKb: readPositiveIntegerWithDefault(context, 'max_file_kb', DEFAULT_RETENTION_LIMITS.contextMaxFileKb),
+        knowledgeMaxFileKb: readPositiveIntegerWithDefault(knowledge, 'max_file_kb', DEFAULT_RETENTION_LIMITS.knowledgeMaxFileKb),
+    };
+}
+export function resolveRunReceiptRetentionPolicy(mustflowToml) {
+    const retention = readRetentionTable(mustflowToml);
+    const runReceipts = readNestedRetentionTable(retention, 'run_receipts');
+    return {
+        store: readString(runReceipts ?? {}, 'store') ?? 'repo_local_ignored',
+        maxFileKb: readPositiveIntegerWithDefault(runReceipts, 'max_file_kb', DEFAULT_RETENTION_LIMITS.runReceiptMaxFileKb),
+        maxItems: readPositiveIntegerWithDefault(runReceipts, 'max_items', 1),
+        maxTotalMb: readPositiveIntegerWithDefault(runReceipts, 'max_total_mb', 1),
+        stdoutTailBytes: readPositiveIntegerWithDefault(runReceipts, 'keep_stdout_tail_bytes', DEFAULT_RUN_RECEIPT_TAIL_BYTES),
+        stderrTailBytes: readPositiveIntegerWithDefault(runReceipts, 'keep_stderr_tail_bytes', DEFAULT_RUN_RECEIPT_TAIL_BYTES),
+    };
+}

package/dist/core/run-receipt.js

@@ -0,0 +1,77 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_RUN_RECEIPT_TAIL_BYTES } from './retention-policy.js';
+const RUN_RECEIPT_SCHEMA_VERSION = '1';
+const RUN_RECEIPT_DIR = path.join('.mustflow', 'state', 'runs');
+const LATEST_RUN_RECEIPT = 'latest.json';
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function truncateTextByBytes(text, maxBytes) {
+    const buffer = Buffer.from(text, 'utf8');
+    if (buffer.byteLength <= maxBytes) {
+        return { text, truncated: false };
+    }
+    return {
+        text: buffer.subarray(buffer.byteLength - maxBytes).toString('utf8'),
+        truncated: true,
+    };
+}
+function summarizeOutput(output, maxOutputBytes, tailBytes) {
+    if (!output) {
+        return {
+            bytes: 0,
+            truncated: false,
+            tail: '',
+        };
+    }
+    const text = output.toString();
+    const bytes = Buffer.byteLength(text, 'utf8');
+    const tailLimit = Math.min(tailBytes, maxOutputBytes);
+    const tail = truncateTextByBytes(text, tailLimit);
+    return {
+        bytes,
+        truncated: tail.truncated,
+        tail: tail.text,
+    };
+}
+function getReceiptRelativePath() {
+    return toPosixPath(path.join(RUN_RECEIPT_DIR, LATEST_RUN_RECEIPT));
+}
+export function createRunReceipt(input) {
+    const relativeCwd = path.relative(input.projectRoot, input.cwd);
+    const stdoutTailBytes = input.stdoutTailBytes ?? DEFAULT_RUN_RECEIPT_TAIL_BYTES;
+    const stderrTailBytes = input.stderrTailBytes ?? DEFAULT_RUN_RECEIPT_TAIL_BYTES;
+    return {
+        schema_version: RUN_RECEIPT_SCHEMA_VERSION,
+        command: 'run',
+        intent: input.intent,
+        status: input.status,
+        timed_out: input.timedOut,
+        started_at: input.startedAt.toISOString(),
+        finished_at: input.finishedAt.toISOString(),
+        duration_ms: input.finishedAt.getTime() - input.startedAt.getTime(),
+        cwd: relativeCwd.length > 0 ? toPosixPath(relativeCwd) : '.',
+        lifecycle: input.lifecycle,
+        run_policy: input.runPolicy,
+        mode: input.mode,
+        argv: input.argv,
+        cmd: input.cmd,
+        timeout_seconds: input.timeoutSeconds,
+        max_output_bytes: input.maxOutputBytes,
+        success_exit_codes: input.successExitCodes,
+        exit_code: input.exitCode,
+        signal: input.signal,
+        error: input.error,
+        kill_method: input.killMethod,
+        stdout: summarizeOutput(input.stdout, input.maxOutputBytes, stdoutTailBytes),
+        stderr: summarizeOutput(input.stderr, input.maxOutputBytes, stderrTailBytes),
+        receipt_path: getReceiptRelativePath(),
+    };
+}
+export function writeRunReceipt(projectRoot, receipt) {
+    const receiptDir = path.join(projectRoot, RUN_RECEIPT_DIR);
+    const latestPath = path.join(receiptDir, LATEST_RUN_RECEIPT);
+    mkdirSync(receiptDir, { recursive: true });
+    writeFileSync(latestPath, `${JSON.stringify(receipt, null, 2)}\n`);
+}

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

@@ -0,0 +1,100 @@
+const SKILL_ROUTE_SOURCE_FILES = [
+    '.mustflow/skills/INDEX.md',
+    '.mustflow/skills/*/SKILL.md',
+    '.mustflow/config/commands.toml',
+    '.mustflow/docs/agent-workflow.md',
+];
+const MARKDOWN_TABLE_SEPARATOR_PATTERN = /^:?-{3,}:?$/u;
+export const SKILL_INDEX_ROUTE_COLUMN_COUNT = 7;
+export const SKILL_INDEX_SKILL_PATH_COLUMN_INDEX = 1;
+export const SKILL_INDEX_VERIFICATION_INTENTS_COLUMN_INDEX = 5;
+export const SKILL_INDEX_ROUTE_COLUMNS = 'Trigger, Skill Document, Required Input, Edit Scope, Risk, Verification Intents, Expected Output';
+function splitMarkdownTableRow(line) {
+    return line
+        .trim()
+        .replace(/^\|/u, '')
+        .replace(/\|$/u, '')
+        .split('|')
+        .map((cell) => cell.trim());
+}
+function isMarkdownTableSeparator(cells) {
+    return cells.length > 0 && cells.every((cell) => MARKDOWN_TABLE_SEPARATOR_PATTERN.test(cell));
+}
+export function readBacktickValues(value) {
+    return [...value.matchAll(/`([^`]+)`/gu)].map((match) => match[1].trim()).filter(Boolean);
+}
+export function findSkillIndexRoutePathColumn(cells) {
+    return cells.findIndex((cell) => readBacktickValues(cell).some((value) => value.startsWith('.mustflow/skills/') && value.endsWith('/SKILL.md')));
+}
+export function parseSkillIndexRoutes(content) {
+    const routes = [];
+    for (const line of content.split(/\r?\n/u)) {
+        if (!line.trim().startsWith('|')) {
+            continue;
+        }
+        const cells = splitMarkdownTableRow(line);
+        if (isMarkdownTableSeparator(cells)) {
+            continue;
+        }
+        const skillPathColumn = findSkillIndexRoutePathColumn(cells);
+        if (skillPathColumn < 0) {
+            continue;
+        }
+        const [skillPath] = readBacktickValues(cells[skillPathColumn]);
+        if (!skillPath) {
+            continue;
+        }
+        routes.push({
+            trigger: cells[0] ?? '',
+            skillPath,
+            requiredInput: cells[2] ?? '',
+            editScope: cells[3] ?? '',
+            risk: cells[4] ?? '',
+            commandIntents: readBacktickValues(cells[SKILL_INDEX_VERIFICATION_INTENTS_COLUMN_INDEX] ?? ''),
+            expectedOutput: cells[6] ?? '',
+        });
+    }
+    return routes;
+}
+function pluralize(count, singular, plural) {
+    return count === 1 ? singular : plural;
+}
+export function isSkillRouteAlignmentIssue(issue) {
+    return (issue.includes('.mustflow/skills/INDEX.md route') ||
+        issue.includes('.mustflow/skills/INDEX.md has duplicate route') ||
+        issue.endsWith(' is not listed in .mustflow/skills/INDEX.md'));
+}
+export function summarizeSkillRouteAlignment(issues) {
+    const skillRouteIssues = issues.filter(isSkillRouteAlignmentIssue);
+    const issueCount = skillRouteIssues.length;
+    return {
+        status: issueCount === 0 ? 'ok' : 'fail',
+        issueCount,
+        issues: skillRouteIssues,
+        summary: `${issueCount} skill index/body alignment ${pluralize(issueCount, 'issue', 'issues')}`,
+        action: issueCount === 0 ? null : 'mf check --strict',
+    };
+}
+export function explainSkillRouteAlignment(issues) {
+    const alignment = summarizeSkillRouteAlignment(issues);
+    if (alignment.status === 'ok') {
+        return {
+            kind: 'skill_routes',
+            decision: 'skill index and skill bodies are aligned',
+            reason: 'strict validation found every skill route points to a procedure body and every skill body is listed in the skill index.',
+            effectiveAction: 'Use .mustflow/skills/INDEX.md to choose relevant skill procedures before editing.',
+            countsAsMustflowVerification: false,
+            sourceFiles: SKILL_ROUTE_SOURCE_FILES,
+            alignment,
+        };
+    }
+    return {
+        kind: 'skill_routes',
+        decision: 'skill index and skill bodies are not aligned',
+        reason: 'strict validation found skill routes or procedure bodies that do not agree with each other.',
+        effectiveAction: 'Fix the skill index/body mismatch, then run mf check --strict or mf doctor --strict.',
+        countsAsMustflowVerification: false,
+        sourceFiles: SKILL_ROUTE_SOURCE_FILES,
+        alignment,
+    };
+}

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

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { parseSkillIndexRoutes } from './skill-route-alignment.js';
+const SKILL_INDEX_PATH = '.mustflow/skills/INDEX.md';
+const SKILL_ROUTE_SOURCE_FILES = [
+    SKILL_INDEX_PATH,
+    '.mustflow/skills/<skill>/SKILL.md',
+    '.mustflow/config/commands.toml',
+];
+function readFrontmatterLines(content) {
+    if (!content.startsWith('---')) {
+        return [];
+    }
+    const end = content.indexOf('\n---', 3);
+    if (end < 0) {
+        return [];
+    }
+    return content.slice(3, end).split(/\r?\n/u);
+}
+function readFrontmatterScalar(content, key) {
+    for (const line of readFrontmatterLines(content)) {
+        const match = /^\s*([^:#]+):\s*(.+?)\s*$/u.exec(line);
+        if (!match) {
+            continue;
+        }
+        if (match[1].trim() === key) {
+            return match[2].trim().replace(/^["']|["']$/gu, '') || null;
+        }
+    }
+    return null;
+}
+function readFrontmatterList(content, key) {
+    const lines = readFrontmatterLines(content);
+    const values = [];
+    let keyIndent;
+    for (const line of lines) {
+        const keyMatch = /^(\s*)([^:#]+):\s*$/u.exec(line);
+        if (keyMatch) {
+            keyIndent = keyMatch[2].trim() === key ? keyMatch[1].length : undefined;
+            continue;
+        }
+        if (keyIndent === undefined) {
+            continue;
+        }
+        const valueMatch = /^(\s*)-\s*(.+?)\s*$/u.exec(line);
+        if (!valueMatch || valueMatch[1].length <= keyIndent) {
+            keyIndent = undefined;
+            continue;
+        }
+        values.push(valueMatch[2].trim().replace(/^["']|["']$/gu, ''));
+    }
+    return values;
+}
+function skillNameFromPath(skillPath) {
+    const match = /^\.mustflow\/skills\/([^/]+)\/SKILL\.md$/u.exec(skillPath);
+    return match?.[1] ?? skillPath;
+}
+function targetMatchesRoute(target, route, skillContent) {
+    const skillName = skillNameFromPath(route.skillPath);
+    const normalizedTarget = target.replace(/\\/gu, '/');
+    if (normalizedTarget === skillName || normalizedTarget === route.skillPath) {
+        return true;
+    }
+    if (!skillContent) {
+        return false;
+    }
+    return (readFrontmatterScalar(skillContent, 'name') === target ||
+        readFrontmatterScalar(skillContent, 'skill_id') === target ||
+        readFrontmatterScalar(skillContent, 'mustflow_doc') === target);
+}
+function routeToSummary(route, skillContent) {
+    const declaredCommandIntents = skillContent ? readFrontmatterList(skillContent, 'command_intents') : [];
+    return {
+        skill: skillNameFromPath(route.skillPath),
+        skillPath: route.skillPath,
+        trigger: route.trigger,
+        requiredInput: route.requiredInput,
+        editScope: route.editScope,
+        risk: route.risk,
+        verificationIntents: route.commandIntents,
+        expectedOutput: route.expectedOutput,
+        declaredCommandIntents,
+    };
+}
+export function explainSkillRoute(projectRoot, target) {
+    const indexPath = path.join(projectRoot, ...SKILL_INDEX_PATH.split('/'));
+    const indexContent = existsSync(indexPath) ? readFileSync(indexPath, 'utf8') : '';
+    const routes = parseSkillIndexRoutes(indexContent);
+    for (const route of routes) {
+        const absoluteSkillPath = path.join(projectRoot, ...route.skillPath.split('/'));
+        const skillContent = existsSync(absoluteSkillPath) ? readFileSync(absoluteSkillPath, 'utf8') : null;
+        if (!targetMatchesRoute(target, route, skillContent)) {
+            continue;
+        }
+        const summary = routeToSummary(route, skillContent);
+        return {
+            kind: 'skill_route',
+            inputSkill: target,
+            decision: `skill route "${summary.skill}" is declared`,
+            reason: 'the skill index contains a route for the requested skill and exposes its trigger, scope, risk, checks, and output contract.',
+            effectiveAction: `Read ${summary.skillPath} before editing work that matches: ${summary.trigger}`,
+            countsAsMustflowVerification: false,
+            sourceFiles: [SKILL_INDEX_PATH, route.skillPath, '.mustflow/config/commands.toml'],
+            route: summary,
+        };
+    }
+    return {
+        kind: 'skill_route',
+        inputSkill: target,
+        decision: `skill route "${target}" is not declared`,
+        reason: 'the skill index has no matching route for the requested folder name, skill_id, mustflow_doc, or skill path.',
+        effectiveAction: 'Use mf explain skills to inspect route alignment, then update .mustflow/skills/INDEX.md only if a real repeatable procedure exists.',
+        countsAsMustflowVerification: false,
+        sourceFiles: SKILL_ROUTE_SOURCE_FILES,
+        route: null,
+    };
+}

package/dist/core/source-anchor-explanation.js

@@ -0,0 +1,33 @@
+import { collectSourceAnchorSummaries } from './source-anchors.js';
+const SOURCE_FILES = [
+    'ROADMAP.md',
+    '.mustflow/docs/agent-workflow.md',
+    '.mustflow/config/mustflow.toml',
+    '.mustflow/config/commands.toml',
+];
+export function explainSourceAnchor(projectRoot, anchorId) {
+    const anchors = collectSourceAnchorSummaries(projectRoot);
+    const anchor = anchors.find((candidate) => candidate.id === anchorId) ?? null;
+    if (!anchor) {
+        return {
+            kind: 'missing',
+            inputAnchor: anchorId,
+            decision: `source anchor "${anchorId}" is not indexed by direct source inspection`,
+            reason: 'mustflow found no structured inline anchor with that id in inspectable source files. Source anchors are optional and disabled for automatic source modification.',
+            effectiveAction: 'Use normal code search or add a short structured source anchor only when a human-approved code change calls for one.',
+            countsAsMustflowVerification: false,
+            sourceFiles: SOURCE_FILES,
+            anchor: null,
+        };
+    }
+    return {
+        kind: 'found',
+        inputAnchor: anchorId,
+        decision: `source anchor "${anchorId}" is a navigation-only code coordinate`,
+        reason: 'structured source anchors help agents find important code locations, but they cannot define workflow rules, command permission, or verification authority.',
+        effectiveAction: 'Use this anchor to navigate to the source location, then trust the current code, tests, AGENTS.md, and commands.toml over the anchor text.',
+        countsAsMustflowVerification: false,
+        sourceFiles: SOURCE_FILES,
+        anchor,
+    };
+}