mustflow 1.18.16 → 1.31.0

package/dist/cli/lib/validation.js

@@ -4,7 +4,7 @@ import { isRecord } from './command-contract.js';
 import { validateCommandContractConfig, validateCommandContractStrictDefaults, } from '../../core/command-contract-validation.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, findSkillIndexRoutePathColumn, parseSkillIndexRoutes, readBacktickValues, } from '../../core/skill-route-alignment.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';
 import { validateTemplateVersionSync } from '../../core/release-version-validation.js';
 import { validateSourceAnchorsInProject } from '../../core/source-anchor-validation.js';
 import { listFilesRecursive, toPosixPath } from './filesystem.js';
@@ -13,6 +13,7 @@ import { inspectManifestLock } from './manifest-lock.js';
 import { COMMIT_MESSAGE_STYLES, TEST_AUTHORING_POLICIES } from './preferences-options.js';
 import { generateRepoMap } from './repo-map.js';
 import { readTomlFile } from './toml.js';
+import { getContractModelDefinitions, validateCandidateContractModelConfig, } from '../../core/contract-models.js';
 import { VERSIONING_CONFIG_PATH, VERSION_SOURCE_AUTHORITIES, VERSION_SOURCE_KINDS, detectVersionSourcePaths, readDeclaredVersionSources, releaseVersioningIsEnabled, } from '../../core/version-sources.js';
 export { describeCheckIssues, getCheckIssueId, } from '../../core/check-issues.js';
 const REQUIRED_SKILL_SECTION_IDS = [
@@ -29,6 +30,7 @@ const REQUIRED_SKILL_SECTION_IDS = [
     'output-format',
 ];
 const SKILL_SECTION_MARKER_PATTERN = /^<!--\s*mustflow-section:\s*([a-z][a-z0-9-]*)\s*-->\s*\r?\n##\s+.+$/gimu;
+const TEST_SELECTION_CONFIG_PATH = '.mustflow/config/test-selection.toml';
 const REQUIRED_FILES = [
     'AGENTS.md',
     '.mustflow/config/mustflow.toml',
@@ -98,6 +100,22 @@ const FORBIDDEN_VERIFICATION_SELECTION_AUTHORITY_FIELDS = [
     'destructive',
 ];
 const ALLOWED_VERIFICATION_SELECTION_STRATEGIES = new Set(['risk_based', 'targeted', 'full']);
+const ALLOWED_TEST_SELECTION_RISKS = new Set(['low', 'medium', 'high', 'release_sensitive', 'security_sensitive']);
+const FORBIDDEN_TEST_SELECTION_COMMAND_AUTHORITY_FIELDS = [
+    'argv',
+    'cmd',
+    'command',
+    'commands',
+    'command_intents',
+    'destructive',
+    'intents',
+    'lifecycle',
+    'network',
+    'required_after',
+    'run_policy',
+    'status',
+    'writes',
+];
 const TEST_AUTHORING_BOOLEAN_FIELDS = ['prefer_existing_tests', 'require_new_test_rationale'];
 const ALLOWED_TEST_AUTHORING_POLICIES = new Set(TEST_AUTHORING_POLICIES);
 const ALLOWED_TESTING_POLICIES = new Set(['behavior_contract']);
@@ -1078,6 +1096,9 @@ function validateSkillIndexRoutes(projectRoot, commandsToml, skillFiles, issues)
     const routedSkillPaths = new Set();
     const expectedSkillPaths = new Set(skillFiles.map((relativePath) => `.mustflow/skills/${relativePath}`));
     const seenSkillPaths = new Set();
+    for (const warning of findSkillRouteConflictWarnings(skillRoutes)) {
+        pushStrictWarning(issues, `${SKILL_INDEX_PATH} ${warning}`);
+    }
     for (const route of skillRoutes) {
         if (!route.skillPath.startsWith('.mustflow/skills/') || !route.skillPath.endsWith('/SKILL.md')) {
             pushStrictIssue(issues, `${SKILL_INDEX_PATH} route "${route.skillPath}" must point to .mustflow/skills/<name>/SKILL.md`);
@@ -1222,6 +1243,114 @@ function validateStrictVerificationSelectionAuthority(preferencesToml, issues) {
         }
     }
 }
+function validateNoTestSelectionCommandAuthorityFields(label, table, issues) {
+    for (const field of FORBIDDEN_TEST_SELECTION_COMMAND_AUTHORITY_FIELDS) {
+        if (hasOwn(table, field)) {
+            pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label}.${field} cannot define command authority; use .mustflow/config/commands.toml`);
+        }
+    }
+}
+function validateTestSelectionIntentReference(value, label, commandsToml, issues) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} must be a command intent name`);
+        return;
+    }
+    if (!isDeclaredCommandIntent(commandsToml, value)) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} references unknown command intent "${value}"`);
+        return;
+    }
+    if (!isConfiguredCommandIntent(commandsToml, value)) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} references command intent "${value}" that is not configured`);
+    }
+}
+function validateTestSelectionRule(rule, index, commandsToml, issues) {
+    const label = `rules[${index}]`;
+    if (!isRecord(rule)) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} must be a TOML table`);
+        return;
+    }
+    validateNoTestSelectionCommandAuthorityFields(label, rule, issues);
+    validateRequiredStringField(rule, 'id', `${TEST_SELECTION_CONFIG_PATH} ${label}.id`, issues);
+    validateRequiredStringField(rule, 'reason', `${TEST_SELECTION_CONFIG_PATH} ${label}.reason`, issues);
+    validateRequiredStringField(rule, 'risk', `${TEST_SELECTION_CONFIG_PATH} ${label}.risk`, issues);
+    validateAllowedStringField(rule, 'risk', `${TEST_SELECTION_CONFIG_PATH} ${label}.risk`, ALLOWED_TEST_SELECTION_RISKS, issues);
+    const match = validateNestedTable(rule, 'match', `${TEST_SELECTION_CONFIG_PATH} ${label}.match`, issues);
+    if (!hasOwn(rule, 'match')) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} must define match`);
+    }
+    if (match) {
+        validateNoTestSelectionCommandAuthorityFields(`${label}.match`, match, issues);
+        validatePathArrayField(match, 'paths', `${TEST_SELECTION_CONFIG_PATH} ${label}.match.paths`, issues);
+        validateStringArrayField(match, 'surfaces', `${TEST_SELECTION_CONFIG_PATH} ${label}.match.surfaces`, issues);
+        if (!hasOwn(match, 'paths')) {
+            pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label}.match must define paths`);
+        }
+        if (!hasOwn(match, 'surfaces')) {
+            pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label}.match must define surfaces`);
+        }
+    }
+    const select = validateNestedTable(rule, 'select', `${TEST_SELECTION_CONFIG_PATH} ${label}.select`, issues);
+    if (!hasOwn(rule, 'select')) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} ${label} must define select`);
+    }
+    if (select) {
+        validateNoTestSelectionCommandAuthorityFields(`${label}.select`, select, issues);
+        validateTestSelectionIntentReference(select.intent, `${label}.select.intent`, commandsToml, issues);
+        validateTestSelectionIntentReference(select.fallback_intent, `${label}.select.fallback_intent`, commandsToml, issues);
+        validatePathArrayField(select, 'test_targets', `${TEST_SELECTION_CONFIG_PATH} ${label}.select.test_targets`, issues);
+    }
+}
+function validateStrictTestSelectionConfig(projectRoot, commandsToml, issues) {
+    const configPath = path.join(projectRoot, ...TEST_SELECTION_CONFIG_PATH.split('/'));
+    if (!existsSync(configPath)) {
+        return;
+    }
+    let parsed;
+    try {
+        parsed = readTomlFile(configPath);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        pushStrictIssue(issues, `Invalid TOML in ${TEST_SELECTION_CONFIG_PATH}: ${message}`);
+        return;
+    }
+    if (!isRecord(parsed)) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} must contain a TOML table`);
+        return;
+    }
+    validateNoTestSelectionCommandAuthorityFields('root', parsed, issues);
+    validateRequiredStringField(parsed, 'schema_version', `${TEST_SELECTION_CONFIG_PATH}.schema_version`, issues);
+    if (parsed.schema_version !== '1') {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH}.schema_version must be "1"`);
+    }
+    if (!Array.isArray(parsed.rules) || parsed.rules.length === 0) {
+        pushStrictIssue(issues, `${TEST_SELECTION_CONFIG_PATH} must define [[rules]]`);
+        return;
+    }
+    for (const [index, rule] of parsed.rules.entries()) {
+        validateTestSelectionRule(rule, index, commandsToml, issues);
+    }
+}
+function validateStrictCandidateContractModelConfigs(projectRoot, issues) {
+    for (const model of getContractModelDefinitions()) {
+        const configPath = path.join(projectRoot, ...model.filePath.split('/'));
+        if (!existsSync(configPath)) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = readTomlFile(configPath);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            pushStrictIssue(issues, `Invalid TOML in ${model.filePath}: ${message}`);
+            continue;
+        }
+        for (const issue of validateCandidateContractModelConfig(model, parsed)) {
+            pushStrictIssue(issues, issue.message);
+        }
+    }
+}
 function validateStrictReleaseVersioningAuthority(preferencesToml, issues) {
     if (!preferencesToml || !isRecord(preferencesToml.release)) {
         return;
@@ -1597,6 +1726,8 @@ function validateStrict(projectRoot, parsed, issues) {
     validateStrictCommandDefaults(projectRoot, parsed.commandsToml, issues);
     validateStrictReleaseVersioningAuthority(parsed.preferencesToml, issues);
     validateStrictVerificationSelectionAuthority(parsed.preferencesToml, issues);
+    validateStrictCandidateContractModelConfigs(projectRoot, issues);
+    validateStrictTestSelectionConfig(projectRoot, parsed.commandsToml, issues);
     validateStrictVersionSources(projectRoot, parsed.preferencesToml, parsed.versioningToml, issues);
     validateStrictTemplateVersionSync(projectRoot, parsed.preferencesToml, issues);
     validateStrictManagedMarkdownIdentities(projectRoot, issues);

package/dist/core/adapter-compatibility.js

@@ -0,0 +1,235 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+const ADAPTER_SCHEMA_VERSION = '1';
+const MAX_HOST_INSTRUCTION_BYTES = 256 * 1024;
+const MAX_CURSOR_RULE_FILES = 100;
+const HOST_INSTRUCTION_FILES = [
+    { host: 'claude_code', path: 'CLAUDE.md' },
+    { host: 'gemini_cli', path: 'GEMINI.md' },
+    { host: 'github_copilot', path: '.github/copilot-instructions.md' },
+];
+const ADAPTER_SURFACE_DEFINITIONS = [
+    { host: 'claude_code', path: 'CLAUDE.md', kind: 'host_instruction_file' },
+    { host: 'gemini_cli', path: 'GEMINI.md', kind: 'host_instruction_file' },
+    { host: 'github_copilot', path: '.github/copilot-instructions.md', kind: 'host_instruction_file' },
+    { host: 'cursor', path: '.cursor/rules/', kind: 'host_instruction_file' },
+    { host: 'generic', path: '.vscode/settings.json', kind: 'editor_settings' },
+    { host: 'generic', path: '.github/workflows/', kind: 'ci_configuration' },
+    { host: 'generic', path: 'Makefile', kind: 'command_adapter' },
+    { host: 'generic', path: 'justfile', kind: 'command_adapter' },
+    { host: 'generic', path: 'Justfile', kind: 'command_adapter' },
+    { host: 'generic', path: 'Taskfile.yml', kind: 'command_adapter' },
+    { host: 'generic', path: 'package.json#scripts', kind: 'package_manager_scripts' },
+];
+const HOST_AGENT_CONFLICT_PATTERNS = [
+    /\bignore\s+AGENTS\.md\b/iu,
+    /\bdo\s+not\s+(?:read|follow|use)\s+AGENTS\.md\b/iu,
+    /\boverride\s+AGENTS\.md\b/iu,
+    /\binstead\s+of\s+AGENTS\.md\b/iu,
+    /\bAGENTS\.md\s+(?:does\s+not|doesn't)\s+apply\b/iu,
+];
+const DIRECT_COMMAND_PATTERNS = [
+    /\b(?:npm|pnpm|bun|yarn)\s+(?:run\s+)?(?:test|build|lint|check)\b/iu,
+    /\bdeno\s+task\b/iu,
+    /\bcargo\s+(?:test|build|check|clippy)\b/iu,
+    /\bgo\s+test\b/iu,
+    /\bmake\s+[A-Za-z0-9_-]+\b/iu,
+    /\bjust\s+[A-Za-z0-9_-]+\b/iu,
+];
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function resolveProjectPath(projectRoot, relativePath) {
+    return path.join(projectRoot, ...relativePath.split('/'));
+}
+function fileExists(projectRoot, relativePath) {
+    return existsSync(resolveProjectPath(projectRoot, relativePath));
+}
+function packageScriptsExist(projectRoot) {
+    const packageJsonPath = resolveProjectPath(projectRoot, 'package.json');
+    if (!existsSync(packageJsonPath)) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        return !!parsed.scripts && typeof parsed.scripts === 'object';
+    }
+    catch {
+        return false;
+    }
+}
+function surfaceExists(projectRoot, surfacePath) {
+    if (surfacePath === 'package.json#scripts') {
+        return packageScriptsExist(projectRoot);
+    }
+    const relativePath = surfacePath.endsWith('/') ? surfacePath.slice(0, -1) : surfacePath;
+    return fileExists(projectRoot, relativePath);
+}
+function makeHostFile(definition, status) {
+    return {
+        host: definition.host,
+        path: definition.path,
+        status,
+        instruction_role: 'host_instruction',
+        authority: 'host_specific',
+        mustflow_authority: 'advisory',
+        lifecycle: 'user_editable',
+        generated_by_mustflow: false,
+        binding_to_host: status === 'present',
+        mustflow_command_authority: false,
+    };
+}
+function makeFinding(severity, code, pathValue, message, requiredChange) {
+    return {
+        severity,
+        code,
+        path: pathValue,
+        message,
+        required_change: requiredChange,
+    };
+}
+function readHostInstruction(projectRoot, relativePath) {
+    const fullPath = resolveProjectPath(projectRoot, relativePath);
+    if (!existsSync(fullPath)) {
+        return { status: 'absent', text: null };
+    }
+    try {
+        const stat = lstatSync(fullPath);
+        if (stat.isSymbolicLink()) {
+            return {
+                status: 'symlink_not_read',
+                text: null,
+                finding: makeFinding('warning', 'host_instruction_symlink_not_read', relativePath, 'Host instruction path is a symbolic link, so mustflow did not read its target.', false),
+            };
+        }
+        if (!stat.isFile()) {
+            return {
+                status: 'unreadable',
+                text: null,
+                finding: makeFinding('warning', 'host_instruction_not_regular_file', relativePath, 'Host instruction path exists but is not a regular file.', false),
+            };
+        }
+        if (stat.size > MAX_HOST_INSTRUCTION_BYTES) {
+            return {
+                status: 'too_large_not_read',
+                text: null,
+                finding: makeFinding('warning', 'host_instruction_too_large_not_read', relativePath, 'Host instruction file is larger than the read limit, so mustflow reported metadata only.', false),
+            };
+        }
+        return { status: 'present', text: readFileSync(fullPath, 'utf8') };
+    }
+    catch {
+        return {
+            status: 'unreadable',
+            text: null,
+            finding: makeFinding('warning', 'host_instruction_unreadable', relativePath, 'Host instruction file could not be read.', false),
+        };
+    }
+}
+function collectCursorRuleDefinitions(projectRoot) {
+    const cursorRulesPath = resolveProjectPath(projectRoot, '.cursor/rules');
+    if (!existsSync(cursorRulesPath)) {
+        return [];
+    }
+    try {
+        const stat = lstatSync(cursorRulesPath);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            return [{ host: 'cursor', path: '.cursor/rules/' }];
+        }
+        return readdirSync(cursorRulesPath, { withFileTypes: true })
+            .filter((entry) => entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdc')))
+            .map((entry) => ({ host: 'cursor', path: `.cursor/rules/${entry.name}` }))
+            .sort((left, right) => left.path.localeCompare(right.path))
+            .slice(0, MAX_CURSOR_RULE_FILES);
+    }
+    catch {
+        return [{ host: 'cursor', path: '.cursor/rules/' }];
+    }
+}
+function inspectHostInstruction(definition, text) {
+    if (!text) {
+        return [];
+    }
+    const findings = [
+        makeFinding('info', 'host_instruction_present', definition.path, 'Host-specific instruction file is present. It may guide that host, but it is not mustflow command authority.', false),
+    ];
+    if (HOST_AGENT_CONFLICT_PATTERNS.some((pattern) => pattern.test(text))) {
+        findings.push(makeFinding('warning', 'host_instruction_conflicts_with_agents', definition.path, 'Host instruction appears to tell agents to ignore or override AGENTS.md. Resolve the instruction conflict before relying on the host adapter.', true));
+    }
+    if (DIRECT_COMMAND_PATTERNS.some((pattern) => pattern.test(text))) {
+        findings.push(makeFinding('warning', 'host_instruction_direct_command_hint', definition.path, 'Host instruction mentions direct tool commands. Agents must still use configured mustflow command intents for project verification.', false));
+    }
+    return findings;
+}
+function buildAdapterSurfaces(projectRoot) {
+    return ADAPTER_SURFACE_DEFINITIONS.map((definition) => ({
+        host: definition.host,
+        path: definition.path,
+        kind: definition.kind,
+        present: surfaceExists(projectRoot, definition.path),
+        generated_by_mustflow: false,
+        generation_policy: 'explicit_user_request_only',
+        mustflow_command_authority: false,
+    }));
+}
+export function inspectAdapterCompatibility(projectRoot) {
+    const hostDefinitions = [...HOST_INSTRUCTION_FILES, ...collectCursorRuleDefinitions(projectRoot)];
+    const hostFiles = [];
+    const findings = [
+        makeFinding('info', 'command_authority_boundary', '.mustflow/config/commands.toml', 'Project command authority remains .mustflow/config/commands.toml; host-specific files cannot authorize command execution.', false),
+        makeFinding('info', 'adapter_generation_not_default', null, 'mustflow does not generate host adapters, editor settings, CI files, Makefile, justfile, Taskfile.yml, or package-manager scripts by default.', false),
+        makeFinding('info', 'runtime_policy_not_repo_visible', null, 'Host approval and sandbox policies are runtime settings, so this report can only inspect repository-visible compatibility hints.', false),
+    ];
+    for (const definition of hostDefinitions) {
+        const read = readHostInstruction(projectRoot, definition.path);
+        hostFiles.push(makeHostFile(definition, read.status));
+        if (read.finding) {
+            findings.push(read.finding);
+        }
+        findings.push(...inspectHostInstruction(definition, read.text));
+    }
+    const adapterSurfaces = buildAdapterSurfaces(projectRoot);
+    const compatibilityNotes = findings.filter((finding) => !finding.required_change);
+    const requiredChanges = findings.filter((finding) => finding.required_change);
+    const doesNotGenerate = ADAPTER_SURFACE_DEFINITIONS.map((definition) => definition.path);
+    return {
+        schema_version: ADAPTER_SCHEMA_VERSION,
+        command: 'adapters_status',
+        ok: true,
+        mustflow_root: projectRoot,
+        agents_file: {
+            path: 'AGENTS.md',
+            present: fileExists(projectRoot, 'AGENTS.md'),
+            authority: 'binding',
+            lifecycle: 'user_editable',
+            generated_by_mustflow: fileExists(projectRoot, '.mustflow/config/manifest.lock.toml'),
+        },
+        summary: {
+            host_instruction_files: hostFiles.filter((file) => file.status === 'present').length,
+            adapter_surfaces_present: adapterSurfaces.filter((surface) => surface.present).length,
+            compatibility_notes: compatibilityNotes.length,
+            conflicts: requiredChanges.filter((finding) => finding.code === 'host_instruction_conflicts_with_agents').length,
+            required_changes: requiredChanges.length,
+        },
+        host_files: hostFiles,
+        adapter_surfaces: adapterSurfaces,
+        findings,
+        compatibility_notes: compatibilityNotes,
+        required_changes: requiredChanges,
+        runtime_policy: {
+            approval_policy: 'not_repo_visible',
+            sandbox_policy: 'not_repo_visible',
+            stricter_than_mustflow: 'unknown',
+            note: 'Repository files cannot prove host runtime approval or sandbox strictness.',
+        },
+        boundaries: {
+            command_authority: '.mustflow/config/commands.toml',
+            host_files_are_command_authority: false,
+            adapter_generation: 'explicit_user_request_only',
+            does_not_generate: doesNotGenerate,
+        },
+    };
+}
+export function formatAdapterPath(relativePath) {
+    return toPosixPath(relativePath);
+}

package/dist/core/bounded-output.js

@@ -0,0 +1,38 @@
+export class BoundedOutputBuffer {
+    #maxTailBytes;
+    #chunks = [];
+    #tailBytes = 0;
+    #bytes = 0;
+    constructor(maxTailBytes) {
+        this.#maxTailBytes = Math.max(0, maxTailBytes);
+    }
+    append(chunk) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, 'utf8');
+        this.#bytes += buffer.byteLength;
+        if (this.#maxTailBytes === 0 || buffer.byteLength === 0) {
+            return;
+        }
+        this.#chunks.push(buffer);
+        this.#tailBytes += buffer.byteLength;
+        while (this.#tailBytes > this.#maxTailBytes && this.#chunks.length > 0) {
+            const first = this.#chunks[0];
+            const overflow = this.#tailBytes - this.#maxTailBytes;
+            if (!first) {
+                break;
+            }
+            if (first.byteLength <= overflow) {
+                this.#chunks.shift();
+                this.#tailBytes -= first.byteLength;
+                continue;
+            }
+            this.#chunks[0] = first.subarray(overflow);
+            this.#tailBytes -= overflow;
+        }
+    }
+    toSnapshot() {
+        return {
+            bytes: this.#bytes,
+            tail: Buffer.concat(this.#chunks, this.#tailBytes).toString('utf8'),
+        };
+    }
+}

package/dist/core/change-classification.js

@@ -1,3 +1,8 @@
+export const PUBLIC_SURFACE_UPDATE_POLICIES = [
+    'update',
+    'update_or_mark_stale',
+    'not_applicable',
+];
 function surface(kind, category, isPublicSurface, validationReasons, affectedContracts, updatePolicy, driftChecks) {
     return {
         kind,
@@ -9,7 +14,8 @@ function surface(kind, category, isPublicSurface, validationReasons, affectedCon
         driftChecks,
     };
 }
-const UNKNOWN_SURFACE = surface('unclassified_path', 'unknown', false, [], [], 'not_applicable', []);
+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,
@@ -28,6 +34,7 @@ const CHANGE_CLASSIFICATION_RULES = [
     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'])),
@@ -73,6 +80,12 @@ export function listChangeClassificationRuleDescriptors() {
         surface: classificationRule.surface,
     }));
 }
+export function listChangeClassificationValidationReasons() {
+    return uniqueSorted([
+        ...CHANGE_CLASSIFICATION_RULES.flatMap((classificationRule) => classificationRule.surface.validationReasons),
+        ...UNKNOWN_SURFACE.validationReasons,
+    ]);
+}
 export function createChangeClassificationReport(source, relativePaths) {
     const files = uniqueSorted(relativePaths.map(normalizeStatusPath).filter((filePath) => filePath.length > 0));
     const classifications = files.map(classifyChangePath);