mustflow 2.84.0 → 2.85.4

package/dist/core/change-impact.js

@@ -0,0 +1,383 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { inspectDependencyGraph } from './dependency-graph.js';
+export const CHANGE_IMPACT_PACK_ID = 'code';
+export const CHANGE_IMPACT_SCRIPT_ID = 'change-impact';
+export const CHANGE_IMPACT_SCRIPT_REF = `${CHANGE_IMPACT_PACK_ID}/${CHANGE_IMPACT_SCRIPT_ID}`;
+const DEFAULT_BASE_REF = 'HEAD';
+const DEFAULT_MAX_FILES = 200;
+const DEFAULT_MAX_IMPACTS = 300;
+const DEFAULT_MAX_FILE_BYTES = 256 * 1024;
+const SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+function toPosixPath(value) {
+    return value.replace(/\\/gu, '/');
+}
+function normalizeRelativePath(value) {
+    return toPosixPath(value).replace(/^\.\/+/u, '') || '.';
+}
+function sha256Tagged(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function runGit(root, args) {
+    const result = spawnSync('git', [...args], {
+        cwd: root,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        maxBuffer: 16 * 1024 * 1024,
+    });
+    return {
+        ok: result.status === 0,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+        status: result.status,
+    };
+}
+function isInsideGitWorktree(root) {
+    const result = runGit(root, ['rev-parse', '--is-inside-work-tree']);
+    return result.ok && result.stdout.trim() === 'true';
+}
+function makeFinding(code, severity, pathValue, message) {
+    return { code, severity, path: pathValue, message };
+}
+function surfaceForPath(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    const extension = path.extname(normalized).toLowerCase();
+    const basename = path.basename(normalized).toLowerCase();
+    if (normalized.startsWith('.mustflow/')) {
+        return 'workflow';
+    }
+    if (normalized.startsWith('templates/')) {
+        return 'template';
+    }
+    if (normalized.startsWith('schemas/') || basename.endsWith('.schema.json')) {
+        return 'schema';
+    }
+    if (normalized.startsWith('docs') || ['.md', '.mdx'].includes(extension)) {
+        return 'docs';
+    }
+    if (normalized.includes('/i18n/') || normalized.includes('/locales/') || basename.includes('i18n')) {
+        return 'i18n';
+    }
+    if (['package.json', 'bun.lock', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock'].includes(normalized)) {
+        return 'package';
+    }
+    if (/^(?:tsconfig|eslint|vite|vitest|jest|playwright|astro|svelte|tailwind)\b/u.test(basename)) {
+        return 'config';
+    }
+    if (normalized.startsWith('tests/') || /\.test\.[cm]?[jt]sx?$/u.test(normalized)) {
+        return 'test';
+    }
+    if (SOURCE_EXTENSIONS.includes(extension)) {
+        return 'source';
+    }
+    return 'unknown';
+}
+function statusFromCode(code) {
+    if (code.startsWith('A')) {
+        return 'added';
+    }
+    if (code.startsWith('D')) {
+        return 'deleted';
+    }
+    if (code.startsWith('R')) {
+        return 'renamed';
+    }
+    if (code.startsWith('T')) {
+        return 'type_changed';
+    }
+    return 'modified';
+}
+function parseNameStatus(stdout) {
+    const files = [];
+    for (const line of stdout.split(/\r?\n/u)) {
+        if (!line.trim()) {
+            continue;
+        }
+        const [statusCode = 'M', firstPath = '', secondPath = ''] = line.split('\t');
+        const currentPath = normalizeRelativePath(secondPath || firstPath);
+        const previousPath = secondPath ? normalizeRelativePath(firstPath) : null;
+        files.push({
+            path: currentPath,
+            previous_path: previousPath,
+            status: statusFromCode(statusCode),
+            surface: surfaceForPath(currentPath),
+        });
+    }
+    return files;
+}
+function addUntrackedFiles(root, paths, files) {
+    const untracked = runGit(root, ['ls-files', '--others', '--exclude-standard', '--', ...paths]);
+    if (!untracked.ok) {
+        return;
+    }
+    const known = new Set(files.map((file) => file.path));
+    for (const line of untracked.stdout.split(/\r?\n/u)) {
+        const relativePath = normalizeRelativePath(line.trim());
+        if (!relativePath || relativePath === '.' || known.has(relativePath)) {
+            continue;
+        }
+        files.push({
+            path: relativePath,
+            previous_path: null,
+            status: 'untracked',
+            surface: surfaceForPath(relativePath),
+        });
+    }
+}
+function addImpact(root, impacts, candidate, policy, findings, issues) {
+    const normalized = normalizeRelativePath(candidate.path);
+    const key = `${candidate.relationship}:${candidate.source_path}:${normalized}`;
+    if (impacts.has(key)) {
+        return;
+    }
+    if (impacts.size >= policy.max_impacts) {
+        const message = `Change impact found more than ${policy.max_impacts} candidates; remaining candidates were skipped.`;
+        findings.push(makeFinding('change_impact_max_impacts_exceeded', 'high', normalized, message));
+        issues.push(message);
+        return;
+    }
+    impacts.set(key, {
+        ...candidate,
+        path: normalized,
+        exists: existsSync(path.join(root, ...normalized.split('/'))),
+        surface: surfaceForPath(normalized),
+    });
+}
+function siblingBase(relativePath) {
+    const directory = path.posix.dirname(normalizeRelativePath(relativePath));
+    const parsed = path.posix.parse(normalizeRelativePath(relativePath));
+    return directory === '.' ? parsed.name : `${directory}/${parsed.name}`;
+}
+function testCandidatesFor(relativePath) {
+    const base = siblingBase(relativePath);
+    const name = path.posix.basename(base);
+    return [
+        `${base}.test.ts`,
+        `${base}.test.js`,
+        `${base}.spec.ts`,
+        `${base}.spec.js`,
+        `tests/${name}.test.js`,
+        `tests/${name}.test.ts`,
+        `tests/cli/${name}.test.js`,
+    ];
+}
+function sourceCandidatesFor(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    return [
+        normalized.replace(/^tests\/cli\//u, 'src/cli/').replace(/\.test\.[cm]?[jt]sx?$/u, '.ts'),
+        normalized.replace(/^tests\//u, 'src/').replace(/\.test\.[cm]?[jt]sx?$/u, '.ts'),
+    ];
+}
+function addSurfaceImpacts(root, changedFile, impacts, policy, findings, issues) {
+    addImpact(root, impacts, {
+        path: changedFile.path,
+        relationship: 'changed_file',
+        confidence: 1,
+        reason: 'Changed file should be reviewed directly.',
+        source_path: changedFile.path,
+    }, policy, findings, issues);
+    if (changedFile.surface === 'source') {
+        for (const candidatePath of testCandidatesFor(changedFile.path)) {
+            addImpact(root, impacts, {
+                path: candidatePath,
+                relationship: 'sibling_test',
+                confidence: 0.65,
+                reason: 'Nearby test candidate for the changed source path.',
+                source_path: changedFile.path,
+            }, policy, findings, issues);
+        }
+    }
+    if (changedFile.surface === 'test') {
+        for (const candidatePath of sourceCandidatesFor(changedFile.path)) {
+            addImpact(root, impacts, {
+                path: candidatePath,
+                relationship: 'sibling_source',
+                confidence: 0.55,
+                reason: 'Likely source file covered by the changed test path.',
+                source_path: changedFile.path,
+            }, policy, findings, issues);
+        }
+    }
+}
+function addContractImpacts(root, changedFile, impacts, policy, findings, issues) {
+    const contractPaths = changedFile.surface === 'schema'
+        ? ['schemas/README.md', 'src/core/public-json-contracts.ts', 'tests/cli/schema.test.js']
+        : changedFile.surface === 'package' || changedFile.surface === 'template'
+            ? ['tests/cli/package.test.js', 'templates/default/manifest.toml']
+            : changedFile.surface === 'workflow'
+                ? ['.mustflow/config/commands.toml', 'tests/cli/authoring-skill-contracts.test.js']
+                : [];
+    for (const candidatePath of contractPaths) {
+        addImpact(root, impacts, {
+            path: candidatePath,
+            relationship: changedFile.surface === 'workflow' ? 'workflow_surface' : 'contract_test',
+            confidence: 0.7,
+            reason: `Contract surface related to changed ${changedFile.surface} file.`,
+            source_path: changedFile.path,
+        }, policy, findings, issues);
+    }
+}
+function addDependencyImpacts(root, changedFiles, impacts, policy, findings, issues) {
+    const sourcePaths = changedFiles
+        .filter((file) => file.surface === 'source' && file.status !== 'deleted')
+        .map((file) => file.path);
+    if (sourcePaths.length === 0) {
+        return;
+    }
+    const dependencyReport = inspectDependencyGraph(root, {
+        paths: sourcePaths,
+        maxDepth: 1,
+        maxFiles: policy.max_files,
+        maxFileBytes: policy.max_file_bytes,
+        maxNodes: policy.max_impacts,
+        maxEdges: policy.max_impacts,
+    });
+    if (!dependencyReport.ok) {
+        for (const issue of dependencyReport.issues) {
+            issues.push(`dependency-graph: ${issue}`);
+        }
+    }
+    const changedPathSet = new Set(sourcePaths);
+    for (const edge of dependencyReport.edges) {
+        if (!changedPathSet.has(edge.target_path) || changedPathSet.has(edge.source_path)) {
+            continue;
+        }
+        addImpact(root, impacts, {
+            path: edge.source_path,
+            relationship: 'imports_changed_file',
+            confidence: 0.8,
+            reason: `Imports changed file ${edge.target_path} via ${edge.specifier}.`,
+            source_path: edge.target_path,
+        }, policy, findings, issues);
+    }
+}
+function createScriptHints(changedFiles) {
+    const sourcePaths = changedFiles.filter((file) => file.surface === 'source').map((file) => file.path);
+    const hasDocsOrSchema = changedFiles.some((file) => file.surface === 'docs' || file.surface === 'schema');
+    const hints = [];
+    if (sourcePaths.length > 0) {
+        const pathPart = sourcePaths.map((entry) => JSON.stringify(entry)).join(' ');
+        hints.push({
+            script_ref: 'code/dependency-graph',
+            command: `mf script-pack run code/dependency-graph scan ${pathPart} --json`,
+            reason: 'Trace importers and direct dependencies for changed source files.',
+            confidence: 0.85,
+        });
+        hints.push({
+            script_ref: 'repo/related-files',
+            command: `mf script-pack run repo/related-files map ${pathPart} --json`,
+            reason: 'Map nearby source, tests, docs, and config files for changed source paths.',
+            confidence: 0.75,
+        });
+    }
+    if (hasDocsOrSchema) {
+        hints.push({
+            script_ref: 'docs/reference-drift',
+            command: 'mf script-pack run docs/reference-drift check README.md schemas/README.md --json',
+            reason: 'Check documented command, schema, path, and script-pack references after docs or schema changes.',
+            confidence: 0.7,
+        });
+    }
+    return hints;
+}
+function createVerificationHints(changedFiles) {
+    const surfaces = new Set(changedFiles.map((file) => file.surface));
+    const hints = [];
+    const add = (intent, reason, confidence) => {
+        if (!hints.some((hint) => hint.intent === intent)) {
+            hints.push({ intent, reason, confidence });
+        }
+    };
+    if (surfaces.has('source') || surfaces.has('test')) {
+        add('test_related', 'Changed source or tests need related behavior coverage.', 0.85);
+        add('build', 'Changed TypeScript or JavaScript source may affect compiled CLI output.', 0.7);
+    }
+    if (surfaces.has('schema') || surfaces.has('package') || surfaces.has('template')) {
+        add('test_release', 'Package, template, or public schema surfaces changed.', 0.85);
+    }
+    if (surfaces.has('docs') || surfaces.has('schema') || surfaces.has('workflow')) {
+        add('docs_validate_fast', 'Docs, schema docs, or workflow text changed.', 0.75);
+    }
+    if (surfaces.has('workflow') || surfaces.has('template')) {
+        add('mustflow_check', 'Workflow or install template surfaces need strict mustflow validation.', 0.8);
+    }
+    return hints;
+}
+function collectChangedFiles(root, policy, findings, issues) {
+    if (!isInsideGitWorktree(root)) {
+        const message = 'Git worktree is unavailable; change-impact returned an empty impact set.';
+        findings.push(makeFinding('change_impact_git_unavailable', 'low', '.', message));
+        issues.push(message);
+        return [];
+    }
+    const diffArgs = policy.head_ref
+        ? ['diff', '--name-status', '--diff-filter=ACMRTD', policy.base_ref, policy.head_ref, '--', ...policy.path_filters]
+        : ['diff', '--name-status', '--diff-filter=ACMRTD', policy.base_ref, '--', ...policy.path_filters];
+    const diff = runGit(root, diffArgs);
+    if (!diff.ok) {
+        const detail = diff.stderr.trim() || diff.stdout.trim() || `git diff exited with ${diff.status}`;
+        findings.push(makeFinding('change_impact_invalid_ref', 'high', '.', detail));
+        issues.push(detail);
+        return [];
+    }
+    const files = parseNameStatus(diff.stdout);
+    if (!policy.head_ref) {
+        addUntrackedFiles(root, policy.path_filters, files);
+    }
+    files.sort((left, right) => left.path.localeCompare(right.path));
+    if (files.length > policy.max_files) {
+        const message = `Change impact matched ${files.length} files; max_files is ${policy.max_files}.`;
+        findings.push(makeFinding('change_impact_max_files_exceeded', 'high', '.', message));
+        issues.push(message);
+    }
+    return files.slice(0, policy.max_files);
+}
+export function inspectChangeImpact(projectRoot, options = {}) {
+    const root = path.resolve(projectRoot);
+    const policy = {
+        base_ref: options.baseRef ?? DEFAULT_BASE_REF,
+        head_ref: options.headRef ?? null,
+        compare_worktree: options.headRef === undefined || options.headRef === null,
+        max_files: options.maxFiles ?? DEFAULT_MAX_FILES,
+        max_impacts: options.maxImpacts ?? DEFAULT_MAX_IMPACTS,
+        max_file_bytes: options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES,
+        path_filters: (options.paths ?? []).map(normalizeRelativePath),
+    };
+    const findings = [];
+    const issues = [];
+    const changedFiles = collectChangedFiles(root, policy, findings, issues);
+    const impacts = new Map();
+    for (const changedFile of changedFiles) {
+        addSurfaceImpacts(root, changedFile, impacts, policy, findings, issues);
+        addContractImpacts(root, changedFile, impacts, policy, findings, issues);
+    }
+    addDependencyImpacts(root, changedFiles, impacts, policy, findings, issues);
+    const status = findings.some((finding) => finding.severity === 'high' || finding.severity === 'critical')
+        ? 'failed'
+        : 'passed';
+    const inputHash = sha256Tagged(JSON.stringify({ policy, changedFiles }));
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        pack_id: CHANGE_IMPACT_PACK_ID,
+        script_id: CHANGE_IMPACT_SCRIPT_ID,
+        script_ref: CHANGE_IMPACT_SCRIPT_REF,
+        action: 'analyze',
+        status,
+        ok: status === 'passed',
+        mustflow_root: root,
+        policy,
+        input_hash: inputHash,
+        changed_files: changedFiles,
+        impacts: [...impacts.values()].sort((left, right) => right.confidence - left.confidence || left.path.localeCompare(right.path)),
+        script_hints: createScriptHints(changedFiles),
+        verification_hints: createVerificationHints(changedFiles),
+        truncated: findings.some((finding) => finding.code === 'change_impact_max_files_exceeded' ||
+            finding.code === 'change_impact_max_impacts_exceeded'),
+        findings,
+        issues,
+    };
+}

package/dist/core/change-verification.js

@@ -1,6 +1,7 @@
 import { isRecord, readStringArray } from './config-loading.js';
 import { CHANGE_CLASSIFICATION_SURFACE_AUTHORITY, createPathTarget, } from './surface-decision-model.js';
 import { classifyVerificationCandidate, createVerificationPlan, } from './verification-plan.js';
+import { evaluateCommandPreconditions } from './command-preconditions.js';
 import { createVerificationDecisionGraph, } from './verification-decision-graph.js';
 import { createVerificationSchedule, } from './verification-scheduler.js';
 import { createProjectTestSelectionPlan, } from './test-selection.js';
@@ -83,6 +84,22 @@ function readIntentCostExpectedSeconds(commandContract, intent) {
     const expectedSeconds = rawIntent.cost.expected_seconds;
     return Number.isInteger(expectedSeconds) && Number(expectedSeconds) >= 0 ? Number(expectedSeconds) : null;
 }
+function intentHasPreconditions(commandContract, intent) {
+    const rawIntent = commandContract.intents[intent];
+    return isRecord(rawIntent) && Array.isArray(rawIntent.preconditions) && rawIntent.preconditions.length > 0;
+}
+function intentPreconditionsSatisfied(commandContract, projectRoot, intent, cache) {
+    if (!intentHasPreconditions(commandContract, intent)) {
+        return true;
+    }
+    const cached = cache.get(intent);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const satisfied = evaluateCommandPreconditions(projectRoot, commandContract, intent).every((precondition) => precondition.status === 'satisfied');
+    cache.set(intent, satisfied);
+    return satisfied;
+}
 function intentCoverageSignature(commandContract, intent) {
     const rawIntent = commandContract.intents[intent];
     if (!isRecord(rawIntent) || !isRecord(rawIntent.covers)) {
@@ -202,9 +219,10 @@ function minNumber(values) {
     }
     return minimum;
 }
-function selectVerificationCandidates(commandContract, candidates) {
+function selectVerificationCandidates(commandContract, projectRoot, candidates) {
     const runnableCandidates = candidates.filter((candidate) => candidate.status === 'runnable' && candidate.intent.length > 0);
     const selectedIntents = new Set(runnableCandidates.map((candidate) => candidate.intent));
+    const preconditionCache = new Map();
     for (const candidate of runnableCandidates) {
         const isSubsumed = runnableCandidates.some((other) => {
             if (other.intent === candidate.intent) {
@@ -233,7 +251,16 @@ function selectVerificationCandidates(commandContract, candidates) {
         if (group.length < 2) {
             continue;
         }
-        const costs = group.map((candidate) => readIntentCostExpectedSeconds(commandContract, candidate.intent));
+        const preconditionSatisfiedGroup = group.filter((candidate) => intentPreconditionsSatisfied(commandContract, projectRoot, candidate.intent, preconditionCache));
+        const selectableGroup = preconditionSatisfiedGroup.length > 0 ? preconditionSatisfiedGroup : group;
+        if (preconditionSatisfiedGroup.length > 0 && preconditionSatisfiedGroup.length < group.length) {
+            for (const candidate of group) {
+                if (!preconditionSatisfiedGroup.some((entry) => entry.intent === candidate.intent)) {
+                    selectedIntents.delete(candidate.intent);
+                }
+            }
+        }
+        const costs = selectableGroup.map((candidate) => readIntentCostExpectedSeconds(commandContract, candidate.intent));
         if (costs.some((cost) => cost === null)) {
             continue;
         }
@@ -241,11 +268,11 @@ function selectVerificationCandidates(commandContract, candidates) {
         if (minCost === null) {
             continue;
         }
-        const winners = group.filter((candidate) => readIntentCostExpectedSeconds(commandContract, candidate.intent) === minCost);
+        const winners = selectableGroup.filter((candidate) => readIntentCostExpectedSeconds(commandContract, candidate.intent) === minCost);
         if (winners.length !== 1) {
             continue;
         }
-        for (const candidate of group) {
+        for (const candidate of selectableGroup) {
             if (candidate.intent !== winners[0]?.intent) {
                 selectedIntents.delete(candidate.intent);
             }
@@ -316,7 +343,7 @@ export function createChangeVerificationReport(classificationReport, commandCont
     const selectedPlans = plansWithProjectTestSelection.map((plan) => ({
         ...plan,
         selectedCandidates: uniqueVerificationCandidates([
-            ...selectVerificationCandidates(commandContract, plan.candidates),
+            ...selectVerificationCandidates(commandContract, projectRoot, plan.candidates),
             ...testSelectionPlan.selectedCandidates
                 .filter((candidate) => candidate.reason === plan.requirement.reason)
                 .map((candidate) => candidate.candidate),

package/dist/core/config-loading.js

@@ -6,10 +6,17 @@ export const COMMAND_LIFECYCLES = new Set(['oneshot', 'server', 'watch', 'intera
 export const LONG_RUNNING_LIFECYCLES = new Set(['server', 'watch', 'interactive', 'browser', 'background']);
 export const COMMAND_RUN_POLICIES = new Set(['agent_allowed', 'requires_explicit_user_request', 'manual_only']);
 export const COMMANDS_CONFIG_RELATIVE_PATH = '.mustflow/config/commands.toml';
+export const COMMANDS_CONFIG_DIRECTORY_RELATIVE_PATH = '.mustflow/config';
 export const MUSTFLOW_CONFIG_RELATIVE_PATH = '.mustflow/config/mustflow.toml';
+const COMMAND_INCLUDE_DIRECTORY = 'commands';
+const COMMAND_INCLUDE_ALLOWED_TOP_LEVEL_KEYS = new Set(['intents', 'resources']);
+const WINDOWS_RESERVED_PATH_SEGMENTS = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/iu;
 export function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function hasOwn(table, key) {
+    return Object.prototype.hasOwnProperty.call(table, key);
+}
 export function resolveMustflowConfigPath(projectRoot, relativePath) {
     return path.join(projectRoot, ...relativePath.split('/'));
 }
@@ -18,6 +25,119 @@ export function readMustflowOwnedTomlFile(projectRoot, relativePath) {
         maxBytes: 256 * 1024,
     }));
 }
+function normalizeCommandIncludePath(rawPath) {
+    return rawPath.trim().replace(/\\/gu, '/');
+}
+function commandIncludePathIsUnsafe(rawPath) {
+    const normalized = normalizeCommandIncludePath(rawPath);
+    const segments = normalized.split('/').filter((segment) => segment.length > 0);
+    return (normalized.length === 0 ||
+        normalized.includes('\0') ||
+        normalized.startsWith('/') ||
+        path.win32.isAbsolute(rawPath) ||
+        path.posix.isAbsolute(normalized) ||
+        segments.some((segment) => segment === '.' || segment === '..' || WINDOWS_RESERVED_PATH_SEGMENTS.test(segment)) ||
+        !normalized.startsWith(`${COMMAND_INCLUDE_DIRECTORY}/`) ||
+        !normalized.endsWith('.toml'));
+}
+function readCommandIncludePathsFromParsed(root) {
+    if (!hasOwn(root, 'include')) {
+        return [];
+    }
+    if (!isRecord(root.include)) {
+        throw new Error(`[include] in ${COMMANDS_CONFIG_RELATIVE_PATH} must be a TOML table`);
+    }
+    const files = root.include.files;
+    if (!Array.isArray(files) || files.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)) {
+        throw new Error(`[include].files in ${COMMANDS_CONFIG_RELATIVE_PATH} must be a string array`);
+    }
+    const normalizedPaths = [];
+    const seen = new Set();
+    for (const file of files) {
+        const normalized = normalizeCommandIncludePath(file);
+        if (commandIncludePathIsUnsafe(file)) {
+            throw new Error(`Command include path "${file}" must be a relative ${COMMAND_INCLUDE_DIRECTORY}/*.toml path under ${COMMANDS_CONFIG_DIRECTORY_RELATIVE_PATH}`);
+        }
+        if (seen.has(normalized)) {
+            throw new Error(`Duplicate command include path "${normalized}" in ${COMMANDS_CONFIG_RELATIVE_PATH}`);
+        }
+        seen.add(normalized);
+        normalizedPaths.push(normalized);
+    }
+    return normalizedPaths;
+}
+export function readCommandContractIncludePaths(projectRoot) {
+    const parsed = readMustflowOwnedTomlFile(projectRoot, COMMANDS_CONFIG_RELATIVE_PATH);
+    if (!isRecord(parsed)) {
+        throw new Error(`${COMMANDS_CONFIG_RELATIVE_PATH} must contain a TOML table`);
+    }
+    return readCommandIncludePathsFromParsed(parsed).map((includePath) => `${COMMANDS_CONFIG_DIRECTORY_RELATIVE_PATH}/${includePath}`);
+}
+function assertCommandIncludeTable(includePath, parsed) {
+    if (!isRecord(parsed)) {
+        throw new Error(`${COMMANDS_CONFIG_DIRECTORY_RELATIVE_PATH}/${includePath} must contain a TOML table`);
+    }
+    for (const key of Object.keys(parsed)) {
+        if (!COMMAND_INCLUDE_ALLOWED_TOP_LEVEL_KEYS.has(key)) {
+            throw new Error(`${COMMANDS_CONFIG_DIRECTORY_RELATIVE_PATH}/${includePath} may define only [intents] and [resources] tables`);
+        }
+    }
+    return parsed;
+}
+function mergeCommandSection(target, source, sectionName, sourceLabel, seenSources) {
+    if (source === undefined) {
+        return;
+    }
+    if (!isRecord(source)) {
+        throw new Error(`${sourceLabel} [${sectionName}] must be a TOML table`);
+    }
+    for (const [name, value] of Object.entries(source)) {
+        const existingSource = seenSources.get(name);
+        if (existingSource) {
+            throw new Error(`Duplicate command ${sectionName.slice(0, -1)} "${name}" in ${sourceLabel}; already defined in ${existingSource}`);
+        }
+        target[name] = value;
+        seenSources.set(name, sourceLabel);
+    }
+}
+export function readResolvedCommandContractToml(projectRoot) {
+    const parsed = readMustflowOwnedTomlFile(projectRoot, COMMANDS_CONFIG_RELATIVE_PATH);
+    if (!isRecord(parsed)) {
+        throw new Error(`${COMMANDS_CONFIG_RELATIVE_PATH} must contain a TOML table`);
+    }
+    if (hasOwn(parsed, 'intents') && !isRecord(parsed.intents)) {
+        throw new Error(`[intents] table in ${COMMANDS_CONFIG_RELATIVE_PATH} must be a TOML table`);
+    }
+    if (hasOwn(parsed, 'resources') && !isRecord(parsed.resources)) {
+        throw new Error(`[resources] table in ${COMMANDS_CONFIG_RELATIVE_PATH} must be a TOML table`);
+    }
+    const merged = { ...parsed };
+    const mergedIntents = {};
+    const mergedResources = {};
+    const intentSources = new Map();
+    const resourceSources = new Map();
+    const includePaths = readCommandIncludePathsFromParsed(parsed);
+    let sawIntentTable = hasOwn(parsed, 'intents');
+    mergeCommandSection(mergedResources, parsed.resources, 'resources', COMMANDS_CONFIG_RELATIVE_PATH, resourceSources);
+    mergeCommandSection(mergedIntents, parsed.intents, 'intents', COMMANDS_CONFIG_RELATIVE_PATH, intentSources);
+    for (const includePath of includePaths) {
+        const includeRelativePath = `${COMMANDS_CONFIG_DIRECTORY_RELATIVE_PATH}/${includePath}`;
+        const includeTable = assertCommandIncludeTable(includePath, readMustflowOwnedTomlFile(projectRoot, includeRelativePath));
+        sawIntentTable = sawIntentTable || hasOwn(includeTable, 'intents');
+        mergeCommandSection(mergedResources, includeTable.resources, 'resources', includeRelativePath, resourceSources);
+        mergeCommandSection(mergedIntents, includeTable.intents, 'intents', includeRelativePath, intentSources);
+    }
+    if (Object.keys(mergedResources).length > 0) {
+        merged.resources = mergedResources;
+    }
+    if (sawIntentTable) {
+        merged.intents = mergedIntents;
+    }
+    else {
+        delete merged.intents;
+    }
+    return merged;
+}
 export function readMustflowConfig(projectRoot) {
     const parsed = readMustflowOwnedTomlFile(projectRoot, MUSTFLOW_CONFIG_RELATIVE_PATH);
     if (!isRecord(parsed)) {
@@ -30,10 +150,7 @@ export function readMustflowConfigIfExists(projectRoot) {
     return existsSync(configPath) ? readMustflowConfig(projectRoot) : undefined;
 }
 export function readCommandContract(projectRoot) {
-    const parsed = readMustflowOwnedTomlFile(projectRoot, COMMANDS_CONFIG_RELATIVE_PATH);
-    if (!isRecord(parsed)) {
-        throw new Error(`${COMMANDS_CONFIG_RELATIVE_PATH} must contain a TOML table`);
-    }
+    const parsed = readResolvedCommandContractToml(projectRoot);
     if (!isRecord(parsed.intents)) {
         throw new Error(`Missing [intents] table in ${COMMANDS_CONFIG_RELATIVE_PATH}`);
     }