mustflow 2.22.5 → 2.22.12

package/dist/cli/lib/local-index/workflow-documents.js

@@ -0,0 +1,204 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { listFilesRecursive, toPosixPath } from '../filesystem.js';
+import { readMustflowTextFile } from '../mustflow-read.js';
+import { MAX_SNIPPET_BYTES_PER_DOCUMENT } from './constants.js';
+import { sha256Text } from './hashing.js';
+export function getExistingIndexablePaths(projectRoot) {
+    const paths = new Set();
+    const addIfExists = (relativePath) => {
+        if (existsSync(path.join(projectRoot, ...relativePath.split('/')))) {
+            paths.add(relativePath);
+        }
+    };
+    addIfExists('AGENTS.md');
+    for (const relativePath of listFilesRecursive(path.join(projectRoot, '.mustflow', 'docs'))) {
+        if (relativePath.endsWith('.md')) {
+            paths.add(toPosixPath(path.join('.mustflow', 'docs', relativePath)));
+        }
+    }
+    for (const relativePath of listFilesRecursive(path.join(projectRoot, '.mustflow', 'context'))) {
+        if (relativePath.endsWith('.md')) {
+            paths.add(toPosixPath(path.join('.mustflow', 'context', relativePath)));
+        }
+    }
+    for (const relativePath of listFilesRecursive(path.join(projectRoot, '.mustflow', 'skills'))) {
+        if (relativePath === 'INDEX.md' || relativePath.endsWith('/SKILL.md')) {
+            paths.add(toPosixPath(path.join('.mustflow', 'skills', relativePath)));
+        }
+    }
+    for (const relativePath of listFilesRecursive(path.join(projectRoot, '.mustflow', 'config'))) {
+        if (relativePath.endsWith('.toml')) {
+            paths.add(toPosixPath(path.join('.mustflow', 'config', relativePath)));
+        }
+    }
+    return Array.from(paths).sort((left, right) => left.localeCompare(right));
+}
+export function readText(projectRoot, relativePath) {
+    return readMustflowTextFile(projectRoot, relativePath);
+}
+function getDocumentType(relativePath) {
+    if (relativePath === 'AGENTS.md') {
+        return 'agent_rules';
+    }
+    if (relativePath.startsWith('.mustflow/config/')) {
+        return 'config';
+    }
+    if (relativePath === '.mustflow/skills/INDEX.md') {
+        return 'skill_index';
+    }
+    if (relativePath === '.mustflow/context/INDEX.md') {
+        return 'context_index';
+    }
+    if (relativePath.startsWith('.mustflow/context/')) {
+        return 'context';
+    }
+    if (relativePath.endsWith('/SKILL.md')) {
+        return 'skill';
+    }
+    if (relativePath.startsWith('.mustflow/docs/')) {
+        return 'workflow_doc';
+    }
+    return 'document';
+}
+function parseFrontmatter(content) {
+    if (!content.startsWith('---')) {
+        return {};
+    }
+    const end = content.indexOf('\n---', 3);
+    if (end === -1) {
+        return {};
+    }
+    const result = {};
+    const rawFrontmatter = content.slice(3, end);
+    for (const line of rawFrontmatter.split(/\r?\n/)) {
+        const separatorIndex = line.indexOf(':');
+        if (separatorIndex === -1) {
+            continue;
+        }
+        const key = line.slice(0, separatorIndex).trim();
+        const value = line.slice(separatorIndex + 1).trim();
+        if (key.length > 0 && value.length > 0) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function getTitle(relativePath, content) {
+    const heading = content.match(/^#\s+(.+)$/mu)?.[1]?.trim();
+    return heading && heading.length > 0 ? heading : path.posix.basename(relativePath);
+}
+function getSections(content) {
+    return [...content.matchAll(/^##\s+(.+)$/gmu)].map((match) => match[1]?.trim()).filter((value) => Boolean(value));
+}
+function truncateUtf8(value, maxBytes) {
+    const buffer = Buffer.from(value, 'utf8');
+    if (buffer.byteLength <= maxBytes) {
+        return value;
+    }
+    return buffer.subarray(0, maxBytes).toString('utf8').replace(/\uFFFD$/u, '');
+}
+export function collectDocumentsFromPaths(projectRoot, relativePaths) {
+    return relativePaths.map((relativePath) => {
+        const content = readText(projectRoot, relativePath);
+        const frontmatter = parseFrontmatter(content);
+        const revision = Number.parseInt(frontmatter.revision ?? '', 10);
+        return {
+            path: relativePath,
+            type: getDocumentType(relativePath),
+            title: getTitle(relativePath, content),
+            locale: frontmatter.locale ?? null,
+            revision: Number.isInteger(revision) ? revision : null,
+            contentHash: sha256Text(content),
+            contentSnippet: truncateUtf8(content, MAX_SNIPPET_BYTES_PER_DOCUMENT),
+            sections: getSections(content),
+        };
+    });
+}
+export function collectDocuments(projectRoot) {
+    return collectDocumentsFromPaths(projectRoot, getExistingIndexablePaths(projectRoot));
+}
+export function collectSkills(documents) {
+    return documents
+        .filter((document) => document.type === 'skill')
+        .map((document) => ({
+        name: document.path.split('/').at(-2) ?? document.title,
+        path: document.path,
+        title: document.title,
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function normalizeMarkdownCell(value) {
+    return value
+        .replace(/<br\s*\/?>/giu, ' ')
+        .replace(/`([^`]+)`/gu, '$1')
+        .replace(/\s+/gu, ' ')
+        .trim();
+}
+function parseMarkdownTableRow(line) {
+    return line
+        .trim()
+        .replace(/^\|/u, '')
+        .replace(/\|$/u, '')
+        .split('|')
+        .map((cell) => normalizeMarkdownCell(cell));
+}
+function isMarkdownSeparatorRow(cells) {
+    return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/u.test(cell));
+}
+function skillNameFromPath(skillPath) {
+    return skillPath.split('/').at(-2) ?? path.posix.basename(skillPath, '.md');
+}
+export function splitVerificationIntents(value) {
+    return value
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean)
+        .sort((left, right) => left.localeCompare(right));
+}
+export function skillRouteKey(route) {
+    return `${route.skillName}\u0000${route.trigger}`;
+}
+export function collectSkillRoutes(projectRoot) {
+    const indexPath = path.join(projectRoot, '.mustflow', 'skills', 'INDEX.md');
+    if (!existsSync(indexPath)) {
+        return [];
+    }
+    const content = readMustflowTextFile(projectRoot, '.mustflow/skills/INDEX.md');
+    const routes = [];
+    let inRouteTable = false;
+    for (const line of content.split(/\r?\n/u)) {
+        if (!line.trim().startsWith('|')) {
+            if (inRouteTable && line.trim() === '') {
+                inRouteTable = false;
+            }
+            continue;
+        }
+        const cells = parseMarkdownTableRow(line);
+        if (cells.includes('Skill Document') && cells.includes('Trigger')) {
+            inRouteTable = true;
+            continue;
+        }
+        if (!inRouteTable || isMarkdownSeparatorRow(cells) || cells.length < 7) {
+            continue;
+        }
+        const [trigger, skillPath, requiredInput, editScope, risk, verificationIntents, expectedOutput] = cells;
+        if (!skillPath?.startsWith('.mustflow/skills/') || !skillPath.endsWith('/SKILL.md')) {
+            continue;
+        }
+        routes.push({
+            skillName: skillNameFromPath(skillPath),
+            skillPath,
+            trigger: trigger ?? '',
+            requiredInput: requiredInput ?? '',
+            editScope: editScope ?? '',
+            risk: risk ?? '',
+            verificationIntents: splitVerificationIntents(verificationIntents ?? ''),
+            expectedOutput: expectedOutput ?? '',
+        });
+    }
+    return routes.sort((left, right) => {
+        const skillOrder = left.skillName.localeCompare(right.skillName);
+        return skillOrder === 0 ? left.trigger.localeCompare(right.trigger) : skillOrder;
+    });
+}

package/dist/cli/lib/manifest-lock.js

@@ -2,11 +2,9 @@ import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { ensureFileTargetInsideWithoutSymlinks, ensureInside, readFileInsideWithoutSymlinks, readUtf8FileInsideWithoutSymlinks, writeUtf8FileInsideWithoutSymlinks, } from './filesystem.js';
+import { isRecord } from './command-contract.js';
 import { parseTomlText, stringifyToml } from './toml.js';
 export const MANIFEST_LOCK_RELATIVE_PATH = '.mustflow/config/manifest.lock.toml';
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function readString(table, key, label) {
     const value = table[key];
     if (typeof value !== 'string' || value.trim().length === 0) {

package/dist/cli/lib/repo-map-frontmatter.js

@@ -0,0 +1,53 @@
+import { createHash } from 'node:crypto';
+const REPO_MAP_DOC_ID = 'repo-map';
+const REPO_MAP_LIFECYCLE = 'generated';
+const REPO_MAP_GENERATOR = 'mustflow';
+const REPO_MAP_RELATIVE_ROOT = '.';
+const REPO_MAP_SOURCE_POLICY = 'anchors_only';
+const REPO_MAP_PRIVACY_MODE = 'minimal';
+export function getRepoMapSourceFingerprint(input) {
+    const payload = {
+        depth: input.depth,
+        includeNested: input.includeNested,
+        gitLsFilesStatus: input.gitLsFilesStatus,
+        priorityPaths: [...input.configuredPriorityPaths].sort(),
+        anchors: input.anchors.map((anchor) => anchor.relativePath).sort(),
+        nestedRepositories: input.nestedRepositories
+            .map((repository) => ({
+            relativePath: repository.relativePath,
+            mustflow: repository.mustflow,
+            agentRules: repository.agentRules,
+            repoMap: repository.repoMap,
+            mustflowConfig: repository.mustflowConfig,
+            commandContract: repository.commandContract,
+            contextIndex: repository.contextIndex,
+            skillIndex: repository.skillIndex,
+            rootDocuments: repository.rootDocuments.map((document) => document.relativePath).sort(),
+            machineContracts: [...repository.machineContracts].sort(),
+            manifests: [...repository.manifests].sort(),
+            commandAdapters: [...repository.commandAdapters].sort(),
+            editingPolicies: [...repository.editingPolicies].sort(),
+        }))
+            .sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
+    };
+    const digest = createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+    return `sha256:${digest}`;
+}
+export function renderRepoMapFrontmatter(anchorCount, sourceFingerprint, gitLsFilesStatus) {
+    const degraded = gitLsFilesStatus !== 'ok';
+    return [
+        '---',
+        `mustflow_doc: ${REPO_MAP_DOC_ID}`,
+        `lifecycle: ${REPO_MAP_LIFECYCLE}`,
+        `generated_by: ${REPO_MAP_GENERATOR}`,
+        `relative_root: "${REPO_MAP_RELATIVE_ROOT}"`,
+        `source_policy: ${REPO_MAP_SOURCE_POLICY}`,
+        `privacy_mode: ${REPO_MAP_PRIVACY_MODE}`,
+        `anchor_count: ${anchorCount}`,
+        `degraded: ${degraded ? 'true' : 'false'}`,
+        `git_ls_files_status: ${gitLsFilesStatus}`,
+        `source_fingerprint: "${sourceFingerprint}"`,
+        '---',
+        '',
+    ];
+}

package/dist/cli/lib/repo-map.js

@@ -1,17 +1,12 @@
 import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
 import { existsSync, lstatSync, readdirSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { toPosixPath } from './filesystem.js';
+import { getRepoMapSourceFingerprint, renderRepoMapFrontmatter, } from './repo-map-frontmatter.js';
 import { writeUtf8FileInsideWithoutSymlinks } from '../../core/safe-filesystem.js';
+import { isRecord } from './command-contract.js';
 import { readMustflowTomlFile } from './toml.js';
 const DEFAULT_DEPTH = 3;
-const REPO_MAP_DOC_ID = 'repo-map';
-const REPO_MAP_LIFECYCLE = 'generated';
-const REPO_MAP_GENERATOR = 'mustflow';
-const REPO_MAP_RELATIVE_ROOT = '.';
-const REPO_MAP_SOURCE_POLICY = 'anchors_only';
-const REPO_MAP_PRIVACY_MODE = 'minimal';
 const GIT_LS_FILES_TIMEOUT_MS = 5_000;
 const GIT_LS_FILES_MAX_BUFFER_BYTES = 1_048_576;
 const EXCLUDED_SEGMENTS = new Set([
@@ -196,9 +191,6 @@ const EXACT_ANCHOR_DESCRIPTIONS = new Map([
     ['.mustflow/docs/agent-workflow.md', 'Shared workflow policy for agent work.'],
     ['.mustflow/skills/INDEX.md', 'Index of available procedural skills.'],
 ]);
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function getStringArray(value) {
     return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
 }
@@ -624,52 +616,6 @@ function countNestedEntrypoints(repository) {
         ...repository.editingPolicies,
     ].filter(Boolean).length;
 }
-function getSourceFingerprint(depth, includeNested, configuredPriorityPaths, gitLsFilesStatus, anchors, nestedRepositories) {
-    const payload = {
-        depth,
-        includeNested,
-        gitLsFilesStatus,
-        priorityPaths: [...configuredPriorityPaths].sort(),
-        anchors: anchors.map((anchor) => anchor.relativePath).sort(),
-        nestedRepositories: nestedRepositories
-            .map((repository) => ({
-            relativePath: repository.relativePath,
-            mustflow: repository.mustflow,
-            agentRules: repository.agentRules,
-            repoMap: repository.repoMap,
-            mustflowConfig: repository.mustflowConfig,
-            commandContract: repository.commandContract,
-            contextIndex: repository.contextIndex,
-            skillIndex: repository.skillIndex,
-            rootDocuments: repository.rootDocuments.map((document) => document.relativePath).sort(),
-            machineContracts: [...repository.machineContracts].sort(),
-            manifests: [...repository.manifests].sort(),
-            commandAdapters: [...repository.commandAdapters].sort(),
-            editingPolicies: [...repository.editingPolicies].sort(),
-        }))
-            .sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
-    };
-    const digest = createHash('sha256').update(JSON.stringify(payload)).digest('hex');
-    return `sha256:${digest}`;
-}
-function renderRepoMapFrontmatter(anchorCount, sourceFingerprint, gitLsFilesStatus) {
-    const degraded = gitLsFilesStatus !== 'ok';
-    return [
-        '---',
-        `mustflow_doc: ${REPO_MAP_DOC_ID}`,
-        `lifecycle: ${REPO_MAP_LIFECYCLE}`,
-        `generated_by: ${REPO_MAP_GENERATOR}`,
-        `relative_root: "${REPO_MAP_RELATIVE_ROOT}"`,
-        `source_policy: ${REPO_MAP_SOURCE_POLICY}`,
-        `privacy_mode: ${REPO_MAP_PRIVACY_MODE}`,
-        `anchor_count: ${anchorCount}`,
-        `degraded: ${degraded ? 'true' : 'false'}`,
-        `git_ls_files_status: ${gitLsFilesStatus}`,
-        `source_fingerprint: "${sourceFingerprint}"`,
-        '---',
-        '',
-    ];
-}
 function renderSourceQuality(gitLsFilesStatus) {
     if (gitLsFilesStatus === 'ok') {
         return [];
@@ -701,7 +647,14 @@ export function generateRepoMap(projectRoot, options = {}) {
         .filter((anchor) => Boolean(anchor));
     const otherAnchors = anchors.filter((anchor) => !priorityPathSet.has(anchor.relativePath));
     const anchorCount = anchors.length + nestedRepositories.reduce((total, repository) => total + countNestedEntrypoints(repository), 0);
-    const sourceFingerprint = getSourceFingerprint(depth, mapConfig.includeNested, configuredPriorityPaths, gitLsFilesStatus, anchors, nestedRepositories);
+    const sourceFingerprint = getRepoMapSourceFingerprint({
+        depth,
+        includeNested: mapConfig.includeNested,
+        configuredPriorityPaths,
+        gitLsFilesStatus,
+        anchors,
+        nestedRepositories,
+    });
     return [
         ...renderRepoMapFrontmatter(anchorCount, sourceFingerprint, gitLsFilesStatus),
         '# REPO_MAP.md',

package/dist/cli/lib/run-root-trust.js

@@ -0,0 +1,27 @@
+import { MANIFEST_LOCK_RELATIVE_PATH, readManifestLock } from './manifest-lock.js';
+export const ALLOW_UNTRUSTED_ROOT_OPTION = '--allow-untrusted-root';
+export function assessRunRootTrust(projectRoot) {
+    const readResult = readManifestLock(projectRoot);
+    if (readResult.kind === 'present') {
+        return {
+            trusted: true,
+            reason: 'manifest_lock_present',
+            manifestLockPath: readResult.lockPath,
+            detail: null,
+        };
+    }
+    if (readResult.kind === 'invalid') {
+        return {
+            trusted: false,
+            reason: 'manifest_lock_invalid',
+            manifestLockPath: readResult.lockPath,
+            detail: readResult.message,
+        };
+    }
+    return {
+        trusted: false,
+        reason: 'manifest_lock_missing',
+        manifestLockPath: readResult.lockPath,
+        detail: MANIFEST_LOCK_RELATIVE_PATH,
+    };
+}

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

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { isRecord } from '../command-contract.js';
 import { validateCommandContractConfig, validateCommandContractStrictDefaults, } from '../../../core/command-contract-validation.js';
+import { describeCheckIssues } from '../../../core/check-issues.js';
 import { ALLOWED_RETENTION_ON_LIMIT, ALLOWED_RETENTION_STORES, DEFAULT_RETENTION_LIMITS, readNestedRetentionTable, readRetentionTable, resolveRetentionLimits, } from '../../../core/retention-policy.js';
 import { formatManagedMarkdownLabel, getManagedMarkdownExpectation, } from '../../../core/authority-resolution.js';
 import { SKILL_INDEX_ROUTE_COLUMN_COUNT, SKILL_INDEX_ROUTE_COLUMNS, SKILL_INDEX_SKILL_PATH_COLUMN_INDEX, findSkillRouteConflictWarnings, findSkillIndexRoutePathColumn, parseSkillIndexRoutes, readBacktickValues, } from '../../../core/skill-route-alignment.js';
@@ -1641,12 +1642,15 @@ function collectCheckIssues(projectRoot, options = {}) {
 }
 export function checkMustflowProjectReport(projectRoot, options = {}) {
     const issues = collectCheckIssues(projectRoot, options);
-    const errors = issues.filter((issue) => issue.severity !== 'warning').map((issue) => issue.message);
-    const warnings = issues.filter((issue) => issue.severity === 'warning').map((issue) => issue.message);
+    const errorIssues = issues.filter((issue) => issue.severity !== 'warning');
+    const warningIssues = issues.filter((issue) => issue.severity === 'warning');
+    const errors = errorIssues.map((issue) => issue.message);
+    const warnings = warningIssues.map((issue) => issue.message);
     return {
         issues: errors,
         warnings,
         allMessages: [...errors, ...warnings],
+        issueDetails: describeCheckIssues([...errorIssues, ...warningIssues]),
     };
 }
 export function checkMustflowProject(projectRoot, options = {}) {

package/dist/core/change-classification-policy.js

@@ -0,0 +1,47 @@
+export const CHANGE_CLASSIFICATION_POLICY_VERSION = '1';
+function surface(kind, category, isPublicSurface, validationReasons, affectedContracts, updatePolicy, driftChecks) {
+    return {
+        kind,
+        category,
+        isPublicSurface,
+        validationReasons,
+        affectedContracts,
+        updatePolicy,
+        driftChecks,
+    };
+}
+export const UNKNOWN_CHANGE_REASON = 'unknown_change';
+export const UNKNOWN_SURFACE = surface('unclassified_path', 'unknown', false, [UNKNOWN_CHANGE_REASON], ['unclassified repository path'], 'not_applicable', ['classification rule coverage']);
+function rule(id, match, changeKinds, surfaceContract) {
+    return {
+        id,
+        match,
+        changeKinds,
+        surface: surfaceContract,
+    };
+}
+export const CHANGE_CLASSIFICATION_RULE_DEFINITIONS = [
+    rule('readme_page', /^README\.md$/u, ['documentation'], surface('readme_page', 'documentation', true, ['docs_change', 'copy_change'], ['public documentation', 'command examples'], 'update', ['link targets', 'command examples', 'package metadata references'])),
+    rule('docs_site_translation', /^docs-site\/src\/content\/docs\/(?!en\/)[^/]+\//u, ['documentation', 'translation'], surface('docs_site_translation', 'documentation', true, ['docs_change', 'i18n_change'], ['documentation site', 'localized content', 'navigation links'], 'update_or_mark_stale', ['source page parity', 'navigation links', 'localized examples'])),
+    rule('docs_site_page', /^docs-site\/src\/content\/docs\//u, ['documentation'], surface('docs_site_page', 'documentation', true, ['docs_change'], ['documentation site', 'navigation links', 'localized content'], 'update', ['navigation links', 'localized copies', 'command examples'])),
+    rule('installed_template_translation', /^templates\/[^/]+\/locales\/[^/]+\//u, ['installed_template', 'translation'], surface('installed_template_translation', 'installed-template', true, ['i18n_change', 'template_version_change'], ['installed template files', 'localized workflow documents', 'template i18n metadata'], 'update_or_mark_stale', ['template i18n metadata', 'localized frontmatter', 'source revision'])),
+    rule('installed_template', /^templates\/[^/]+\//u, ['installed_template'], surface('installed_template', 'installed-template', true, ['template_version_change', 'packaging_change'], ['installed template files', 'package contents', 'template manifest'], 'update', ['template manifest', 'package inventory', 'localized copies'])),
+    rule('workflow_root', /^(AGENTS\.md|\.mustflow\/(?:docs|context|skills|config)\/)/u, ['workflow'], surface('workflow_root', 'workflow', true, ['mustflow_docs_change', 'mustflow_config_change'], ['agent workflow contract', 'command contract', 'installed workflow files'], 'update', ['strict workflow validation', 'installed template parity', 'skill route alignment'])),
+    rule('host_instruction', /^(CLAUDE\.md|GEMINI\.md|\.github\/copilot-instructions\.md|\.cursor\/rules\/[^/]+\.(?:md|mdc))$/u, ['workflow', 'host_instruction'], surface('host_instruction', 'workflow', true, ['mustflow_docs_change'], ['host instruction compatibility', 'agent workflow contract', 'command contract boundary'], 'update_or_mark_stale', ['host instruction conflicts', 'command contract boundary'])),
+    rule('example', /^examples\//u, ['example'], surface('example', 'example', true, ['docs_change', 'public_api_change'], ['generated examples', 'human-readable examples'], 'update', ['example commands', 'linked docs', 'public behavior claims'])),
+    rule('schema_contract', /^schemas\//u, ['schema'], surface('schema_contract', 'contract', true, ['public_api_change', 'release_risk'], ['JSON schema', 'machine-readable output contract'], 'update', ['schema tests', 'documented JSON fields', 'package inventory'])),
+    rule('package_metadata', /^package\.json$/u, ['package_metadata'], surface('package_metadata', 'release', true, ['package_metadata_change', 'release_risk'], ['npm package metadata', 'published package contents'], 'update', ['package metadata tests', 'version source discovery', 'published file inventory'])),
+    rule('test_fixture', /^tests\/fixtures\//u, ['test_fixture'], surface('test_fixture', 'test', false, ['test_change'], ['regression fixture inputs'], 'not_applicable', ['fixture safety', 'test route coverage'])),
+    rule('test_contract', /^tests\//u, ['test'], surface('test_contract', 'test', false, ['test_change'], ['test behavior contract'], 'not_applicable', ['related test selection'])),
+    rule('implementation', /^(src|scripts)\//u, ['implementation'], surface('implementation', 'code', false, ['code_change'], ['runtime behavior when exported through CLI or package output'], 'not_applicable', ['related tests', 'build output'])),
+];
+export function listChangeClassificationPolicyRuleDescriptors() {
+    return CHANGE_CLASSIFICATION_RULE_DEFINITIONS.map((classificationRule) => ({
+        id: classificationRule.id,
+        patternKind: 'regexp',
+        pattern: classificationRule.match.source,
+        patternFlags: classificationRule.match.flags,
+        changeKinds: classificationRule.changeKinds,
+        surface: classificationRule.surface,
+    }));
+}

package/dist/core/change-classification.js

@@ -1,47 +1,21 @@
+import { CHANGE_CLASSIFICATION_RULE_DEFINITIONS, UNKNOWN_SURFACE, listChangeClassificationPolicyRuleDescriptors, } from './change-classification-policy.js';
 export const PUBLIC_SURFACE_UPDATE_POLICIES = [
     'update',
     'update_or_mark_stale',
     'not_applicable',
 ];
-function surface(kind, category, isPublicSurface, validationReasons, affectedContracts, updatePolicy, driftChecks) {
+function compileRule(definition) {
     return {
-        kind,
-        category,
-        isPublicSurface,
-        validationReasons,
-        affectedContracts,
-        updatePolicy,
-        driftChecks,
-    };
-}
-const UNKNOWN_CHANGE_REASON = 'unknown_change';
-const UNKNOWN_SURFACE = surface('unclassified_path', 'unknown', false, [UNKNOWN_CHANGE_REASON], ['unclassified repository path'], 'not_applicable', ['classification rule coverage']);
-function rule(id, match, changeKinds, surfaceContract) {
-    return {
-        id,
+        id: definition.id,
         patternKind: 'regexp',
-        pattern: match.source,
-        patternFlags: match.flags,
-        match,
-        changeKinds,
-        surface: surfaceContract,
+        pattern: definition.match.source,
+        patternFlags: definition.match.flags,
+        match: definition.match,
+        changeKinds: definition.changeKinds,
+        surface: definition.surface,
     };
 }
-const CHANGE_CLASSIFICATION_RULES = [
-    rule('readme_page', /^README\.md$/u, ['documentation'], surface('readme_page', 'documentation', true, ['docs_change', 'copy_change'], ['public documentation', 'command examples'], 'update', ['link targets', 'command examples', 'package metadata references'])),
-    rule('docs_site_translation', /^docs-site\/src\/content\/docs\/(?!en\/)[^/]+\//u, ['documentation', 'translation'], surface('docs_site_translation', 'documentation', true, ['docs_change', 'i18n_change'], ['documentation site', 'localized content', 'navigation links'], 'update_or_mark_stale', ['source page parity', 'navigation links', 'localized examples'])),
-    rule('docs_site_page', /^docs-site\/src\/content\/docs\//u, ['documentation'], surface('docs_site_page', 'documentation', true, ['docs_change'], ['documentation site', 'navigation links', 'localized content'], 'update', ['navigation links', 'localized copies', 'command examples'])),
-    rule('installed_template_translation', /^templates\/[^/]+\/locales\/[^/]+\//u, ['installed_template', 'translation'], surface('installed_template_translation', 'installed-template', true, ['i18n_change', 'template_version_change'], ['installed template files', 'localized workflow documents', 'template i18n metadata'], 'update_or_mark_stale', ['template i18n metadata', 'localized frontmatter', 'source revision'])),
-    rule('installed_template', /^templates\/[^/]+\//u, ['installed_template'], surface('installed_template', 'installed-template', true, ['template_version_change', 'packaging_change'], ['installed template files', 'package contents', 'template manifest'], 'update', ['template manifest', 'package inventory', 'localized copies'])),
-    rule('workflow_root', /^(AGENTS\.md|\.mustflow\/(?:docs|context|skills|config)\/)/u, ['workflow'], surface('workflow_root', 'workflow', true, ['mustflow_docs_change', 'mustflow_config_change'], ['agent workflow contract', 'command contract', 'installed workflow files'], 'update', ['strict workflow validation', 'installed template parity', 'skill route alignment'])),
-    rule('host_instruction', /^(CLAUDE\.md|GEMINI\.md|\.github\/copilot-instructions\.md|\.cursor\/rules\/[^/]+\.(?:md|mdc))$/u, ['workflow', 'host_instruction'], surface('host_instruction', 'workflow', true, ['mustflow_docs_change'], ['host instruction compatibility', 'agent workflow contract', 'command contract boundary'], 'update_or_mark_stale', ['host instruction conflicts', 'command contract boundary'])),
-    rule('example', /^examples\//u, ['example'], surface('example', 'example', true, ['docs_change', 'public_api_change'], ['generated examples', 'human-readable examples'], 'update', ['example commands', 'linked docs', 'public behavior claims'])),
-    rule('schema_contract', /^schemas\//u, ['schema'], surface('schema_contract', 'contract', true, ['public_api_change', 'release_risk'], ['JSON schema', 'machine-readable output contract'], 'update', ['schema tests', 'documented JSON fields', 'package inventory'])),
-    rule('package_metadata', /^package\.json$/u, ['package_metadata'], surface('package_metadata', 'release', true, ['package_metadata_change', 'release_risk'], ['npm package metadata', 'published package contents'], 'update', ['package metadata tests', 'version source discovery', 'published file inventory'])),
-    rule('test_fixture', /^tests\/fixtures\//u, ['test_fixture'], surface('test_fixture', 'test', false, ['test_change'], ['regression fixture inputs'], 'not_applicable', ['fixture safety', 'test route coverage'])),
-    rule('test_contract', /^tests\//u, ['test'], surface('test_contract', 'test', false, ['test_change'], ['test behavior contract'], 'not_applicable', ['related test selection'])),
-    rule('implementation', /^(src|scripts)\//u, ['implementation'], surface('implementation', 'code', false, ['code_change'], ['runtime behavior when exported through CLI or package output'], 'not_applicable', ['related tests', 'build output'])),
-];
+const CHANGE_CLASSIFICATION_RULES = CHANGE_CLASSIFICATION_RULE_DEFINITIONS.map(compileRule);
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
@@ -93,14 +67,7 @@ export function classifyChangePath(relativePath) {
     };
 }
 export function listChangeClassificationRuleDescriptors() {
-    return CHANGE_CLASSIFICATION_RULES.map((classificationRule) => ({
-        id: classificationRule.id,
-        patternKind: classificationRule.patternKind,
-        pattern: classificationRule.pattern,
-        patternFlags: classificationRule.patternFlags,
-        changeKinds: classificationRule.changeKinds,
-        surface: classificationRule.surface,
-    }));
+    return listChangeClassificationPolicyRuleDescriptors();
 }
 export function listChangeClassificationValidationReasons() {
     return uniqueSorted([

package/dist/core/check-issues.js

@@ -86,11 +86,15 @@ export function getCheckIssueId(message) {
     }
     return null;
 }
-export function describeCheckIssues(messages) {
-    return messages.map((message) => ({
-        id: getCheckIssueId(message),
-        severity: message.startsWith('Strict warning: ') ? 'warning' : 'error',
-        mode: message.startsWith('Strict') ? 'strict' : 'base',
-        message,
-    }));
+export function describeCheckIssues(issues) {
+    return issues.map((issue) => {
+        const message = typeof issue === 'string' ? issue : issue.message;
+        const severity = message.startsWith('Strict warning: ') ? 'warning' : 'error';
+        return {
+            id: typeof issue === 'string' ? getCheckIssueId(message) : issue.id ?? getCheckIssueId(message),
+            severity: typeof issue === 'string' ? severity : issue.severity ?? severity,
+            mode: message.startsWith('Strict') ? 'strict' : 'base',
+            message,
+        };
+    });
 }