mustflow 2.84.0 → 2.99.0

package/dist/core/change-impact.js

@@ -0,0 +1,355 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { classifyChangeSurface, normalizeChangePath, selectorFallbackReasonForChangedPath, statusFromGitNameStatus, } from './change-surface-classification.js';
+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;
+function normalizeRelativePath(value) {
+    return normalizeChangePath(value);
+}
+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 statusFromCode(code) {
+    return statusFromGitNameStatus(code);
+}
+function surfaceForPath(relativePath) {
+    return classifyChangeSurface(relativePath);
+}
+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 selectorRelevantFiles = changedFiles.filter((file) => ['source', 'test', 'schema', 'config', 'package', 'template', 'workflow', 'unknown'].includes(file.surface));
+    const hasDocsOrSchema = changedFiles.some((file) => file.surface === 'docs' || file.surface === 'schema');
+    const hints = [];
+    if (selectorRelevantFiles.length > 0) {
+        const expectedFallbackReasons = [
+            ...new Set(selectorRelevantFiles.map(selectorFallbackReasonForChangedPath).filter((reason) => reason !== null)),
+        ].sort();
+        const relatedIntents = createVerificationHints(changedFiles).map((hint) => hint.intent);
+        hints.push({
+            script_ref: 'test/regression-selector',
+            command: 'mf script-pack run test/regression-selector select --base HEAD --json',
+            reason: expectedFallbackReasons.length > 0
+                ? 'Select likely regression tests and expose explicit fallback reasons for unsafe changed surfaces.'
+                : 'Select likely regression tests for changed source and test surfaces before choosing a cached related-test shortcut.',
+            confidence: expectedFallbackReasons.length > 0 ? 0.9 : 0.8,
+            related_intents: relatedIntents,
+            expected_fallback_reasons: expectedFallbackReasons,
+        });
+    }
+    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-surface-classification.js

@@ -0,0 +1,198 @@
+import path from 'node:path';
+export const CHANGE_SOURCE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
+const PACKAGE_LOCKFILES = new Set(['bun.lock', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'deno.lock']);
+function toPosixPath(value) {
+    return value.replace(/\\/gu, '/');
+}
+export function normalizeChangePath(value) {
+    return toPosixPath(value).replace(/^\.\/+/u, '') || '.';
+}
+export function statusFromGitNameStatus(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';
+}
+export function classifyChangeSurface(relativePath, options = {}) {
+    const normalized = normalizeChangePath(relativePath);
+    const extension = path.extname(normalized).toLowerCase();
+    const basename = path.basename(normalized).toLowerCase();
+    if (normalized.startsWith('.github/workflows/')) {
+        return 'workflow';
+    }
+    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') ||
+        (options.includeDocsSite === true && normalized.startsWith('docs-site/')) ||
+        ['.md', '.mdx'].includes(extension)) {
+        return 'docs';
+    }
+    if (normalized.includes('/i18n/') || normalized.includes('/locales/') || basename.includes('i18n')) {
+        return 'i18n';
+    }
+    if (normalized === 'package.json' || PACKAGE_LOCKFILES.has(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) ||
+        /\.spec\.[cm]?[jt]sx?$/u.test(normalized)) {
+        return 'test';
+    }
+    if (CHANGE_SOURCE_EXTENSIONS.includes(extension)) {
+        return 'source';
+    }
+    return 'unknown';
+}
+export function selectorFallbackReasonForChangedPath(changedPath) {
+    const normalized = normalizeChangePath(changedPath.path);
+    const basename = path.posix.basename(normalized).toLowerCase();
+    if (changedPath.status === 'deleted') {
+        return 'fallback_deleted';
+    }
+    if (changedPath.status === 'renamed') {
+        return 'fallback_renamed';
+    }
+    if (changedPath.status === 'type_changed') {
+        return 'fallback_type_changed';
+    }
+    if (PACKAGE_LOCKFILES.has(normalized)) {
+        return 'fallback_lockfile';
+    }
+    if (basename === 'package.json') {
+        return 'fallback_package_metadata';
+    }
+    if (changedPath.surface === 'template') {
+        return 'fallback_template';
+    }
+    if (isGeneratedContractPath(normalized)) {
+        return 'fallback_generated_contract';
+    }
+    if (isSharedTestFixturePath(normalized)) {
+        return 'fallback_shared_test_fixture';
+    }
+    if (isMigrationOrDatabasePath(normalized)) {
+        return 'fallback_migration_or_database';
+    }
+    if (normalized.startsWith('.github/workflows/')) {
+        return 'fallback_ci_workflow';
+    }
+    if (normalized.startsWith('.mustflow/')) {
+        return 'fallback_mustflow_workflow';
+    }
+    if (isCompilerOrRunnerConfigPath(normalized) || changedPath.surface === 'config') {
+        return 'fallback_compiler_or_runner_config';
+    }
+    if (changedPath.surface === 'unknown') {
+        return 'fallback_unknown';
+    }
+    return null;
+}
+export function selectorFallbackForChangedPath(changedPath) {
+    const reason = selectorFallbackReasonForChangedPath(changedPath);
+    if (reason === null) {
+        return null;
+    }
+    return {
+        reason,
+        path: changedPath.path,
+        message: selectorFallbackMessage(reason),
+        recommended_intent: selectorFallbackRecommendedIntent(reason),
+    };
+}
+function isSharedTestFixturePath(normalized) {
+    return (normalized.startsWith('tests/fixtures/') ||
+        normalized.startsWith('test/fixtures/') ||
+        normalized.startsWith('fixtures/') ||
+        /(?:^|\/)(?:test-)?setup\.[cm]?[jt]s$/u.test(normalized) ||
+        /(?:^|\/)(?:global-)?setup\.[cm]?[jt]s$/u.test(normalized));
+}
+function isMigrationOrDatabasePath(normalized) {
+    const basename = path.posix.basename(normalized).toLowerCase();
+    return (normalized.includes('/migrations/') ||
+        normalized.startsWith('migrations/') ||
+        normalized.includes('/db/') ||
+        normalized.includes('/database/') ||
+        basename === 'schema.prisma' ||
+        basename.endsWith('.sql'));
+}
+function isGeneratedContractPath(normalized) {
+    const basename = path.posix.basename(normalized).toLowerCase();
+    return (normalized.startsWith('schemas/') ||
+        basename.endsWith('.schema.json') ||
+        basename === 'openapi.json' ||
+        basename === 'openapi.yaml' ||
+        basename === 'openapi.yml' ||
+        basename === 'asyncapi.json' ||
+        basename === 'asyncapi.yaml' ||
+        basename === 'asyncapi.yml' ||
+        basename === 'schema.graphql');
+}
+function isCompilerOrRunnerConfigPath(normalized) {
+    const basename = path.posix.basename(normalized).toLowerCase();
+    return /^(?:tsconfig|eslint|vite|vitest|jest|playwright|astro|svelte|tailwind|webpack|rollup|babel|nyc|c8)\b/u.test(basename);
+}
+function selectorFallbackMessage(reason) {
+    switch (reason) {
+        case 'fallback_deleted':
+            return 'Deleted files can invalidate stale tests, public exports, and static dependency mappings.';
+        case 'fallback_renamed':
+            return 'Renamed files can leave stale import paths, test mappings, and documentation references behind.';
+        case 'fallback_type_changed':
+            return 'Type-changed files can change executable behavior in ways static test narrowing cannot classify.';
+        case 'fallback_lockfile':
+            return 'Lockfile changes can alter dependency resolution, toolchain behavior, and package artifacts.';
+        case 'fallback_package_metadata':
+            return 'Package metadata can change runtime entrypoints, scripts, dependencies, files, and release behavior.';
+        case 'fallback_template':
+            return 'Template changes can alter installed workflow contracts and downstream repository behavior.';
+        case 'fallback_generated_contract':
+            return 'Schema, OpenAPI, GraphQL, or generated-contract changes need contract and release-sensitive verification.';
+        case 'fallback_shared_test_fixture':
+            return 'Shared test fixtures or setup files can affect many tests outside the static source map.';
+        case 'fallback_migration_or_database':
+            return 'Migration, database, or SQL changes can alter shared test state and runtime contracts.';
+        case 'fallback_ci_workflow':
+            return 'CI workflow changes can alter job ordering, environment, caches, and selected-test safety.';
+        case 'fallback_mustflow_workflow':
+            return 'Mustflow workflow changes can alter command contracts, routing, skills, or verification policy.';
+        case 'fallback_compiler_or_runner_config':
+            return 'Compiler, bundler, lint, or test-runner config changes are unsafe for static test narrowing.';
+        case 'fallback_unknown':
+            return 'Unknown change surfaces need the configured fallback path instead of selected-test confidence.';
+        default:
+            return 'Changed files need the configured fallback path instead of selected-test confidence.';
+    }
+}
+function selectorFallbackRecommendedIntent(reason) {
+    switch (reason) {
+        case 'fallback_lockfile':
+        case 'fallback_package_metadata':
+        case 'fallback_template':
+        case 'fallback_generated_contract':
+            return 'test_release';
+        case 'fallback_migration_or_database':
+        case 'fallback_unknown':
+            return 'test';
+        default:
+            return 'test_related';
+    }
+}

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),