mustflow 2.85.4 → 2.99.0

package/dist/cli/script-packs/test-performance-report.js

@@ -0,0 +1,247 @@
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { createTestPerformanceReport, TEST_PERFORMANCE_REPORT_SCRIPT_REF, } from '../../core/test-performance-report.js';
+const TEST_PERFORMANCE_REPORT_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--max-samples', kind: 'string' },
+    { name: '--max-intents', kind: 'string' },
+    { name: '--max-test-files', kind: 'string' },
+    { name: '--max-findings', kind: 'string' },
+    { name: '--slow-ms', kind: 'string' },
+    { name: '--timeout-ratio', kind: 'string' },
+    { name: '--phase-ms', kind: 'string' },
+];
+function parsePositiveInteger(value, option, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^[1-9]\d*$/u.test(value)) {
+        return { value: null, error: t(lang, 'testPerformance.error.invalidPositiveInteger', { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, 'testPerformance.error.invalidPositiveInteger', { option, value }) };
+    }
+    return { value: parsed };
+}
+function parsePositiveRatio(value, option, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) {
+        return { value: null, error: t(lang, 'testPerformance.error.invalidRatio', { option, value }) };
+    }
+    return { value: parsed };
+}
+export function getTestPerformanceReportHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf script-pack run test/performance-report summarize [options]',
+        summary: t(lang, 'testPerformance.help.summary'),
+        options: [
+            { label: '--max-samples <count>', description: t(lang, 'testPerformance.help.option.maxSamples') },
+            { label: '--max-intents <count>', description: t(lang, 'testPerformance.help.option.maxIntents') },
+            { label: '--max-test-files <count>', description: t(lang, 'testPerformance.help.option.maxTestFiles') },
+            { label: '--max-findings <count>', description: t(lang, 'testPerformance.help.option.maxFindings') },
+            { label: '--slow-ms <ms>', description: t(lang, 'testPerformance.help.option.slowMs') },
+            { label: '--timeout-ratio <ratio>', description: t(lang, 'testPerformance.help.option.timeoutRatio') },
+            { label: '--phase-ms <ms>', description: t(lang, 'testPerformance.help.option.phaseMs') },
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf script-pack run test/performance-report summarize --json',
+            'mf script-pack run test/performance-report summarize --max-samples 100 --slow-ms 60000 --json',
+            'mf script-pack run test/performance-report summarize --timeout-ratio 0.8 --phase-ms 15000',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'testPerformance.help.exit.ok') },
+            { label: '1', description: t(lang, 'testPerformance.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseTestPerformanceReportOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, TEST_PERFORMANCE_REPORT_OPTIONS, { allowPositionals: false });
+    const json = hasParsedCliOption(parsed, '--json');
+    const maxSamples = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-samples'), '--max-samples', lang);
+    const maxIntents = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-intents'), '--max-intents', lang);
+    const maxTestFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-test-files'), '--max-test-files', lang);
+    const maxFindings = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-findings'), '--max-findings', lang);
+    const slowMs = parsePositiveInteger(getParsedCliStringOption(parsed, '--slow-ms'), '--slow-ms', lang);
+    const timeoutRatio = parsePositiveRatio(getParsedCliStringOption(parsed, '--timeout-ratio'), '--timeout-ratio', lang);
+    const phaseMs = parsePositiveInteger(getParsedCliStringOption(parsed, '--phase-ms'), '--phase-ms', lang);
+    if (action !== 'summarize') {
+        return {
+            action: 'summarize',
+            json,
+            maxSamples: maxSamples.value,
+            maxIntents: maxIntents.value,
+            maxTestFiles: maxTestFiles.value,
+            maxFindings: maxFindings.value,
+            slowMs: slowMs.value,
+            timeoutRatio: timeoutRatio.value,
+            phaseMs: phaseMs.value,
+            error: action ? t(lang, 'testPerformance.error.unknownAction', { action }) : t(lang, 'testPerformance.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return {
+            action,
+            json,
+            maxSamples: maxSamples.value,
+            maxIntents: maxIntents.value,
+            maxTestFiles: maxTestFiles.value,
+            maxFindings: maxFindings.value,
+            slowMs: slowMs.value,
+            timeoutRatio: timeoutRatio.value,
+            phaseMs: phaseMs.value,
+            error: formatCliOptionParseError(parsed.error, lang),
+        };
+    }
+    for (const candidate of [maxSamples, maxIntents, maxTestFiles, maxFindings, slowMs, timeoutRatio, phaseMs]) {
+        if (candidate.error) {
+            return {
+                action,
+                json,
+                maxSamples: maxSamples.value,
+                maxIntents: maxIntents.value,
+                maxTestFiles: maxTestFiles.value,
+                maxFindings: maxFindings.value,
+                slowMs: slowMs.value,
+                timeoutRatio: timeoutRatio.value,
+                phaseMs: phaseMs.value,
+                error: candidate.error,
+            };
+        }
+    }
+    return {
+        action,
+        json,
+        maxSamples: maxSamples.value,
+        maxIntents: maxIntents.value,
+        maxTestFiles: maxTestFiles.value,
+        maxFindings: maxFindings.value,
+        slowMs: slowMs.value,
+        timeoutRatio: timeoutRatio.value,
+        phaseMs: phaseMs.value,
+    };
+}
+function formatProfileAge(ageMs, lang) {
+    if (ageMs === null) {
+        return t(lang, 'value.none');
+    }
+    const totalMinutes = Math.floor(ageMs / 60_000);
+    if (totalMinutes < 1) {
+        return '<1m';
+    }
+    const days = Math.floor(totalMinutes / 1440);
+    const hours = Math.floor((totalMinutes % 1440) / 60);
+    const minutes = totalMinutes % 60;
+    const parts = [];
+    if (days > 0) {
+        parts.push(`${days}d`);
+    }
+    if (hours > 0) {
+        parts.push(`${hours}h`);
+    }
+    if (minutes > 0 || parts.length === 0) {
+        parts.push(`${minutes}m`);
+    }
+    return parts.join(' ');
+}
+function formatProfileCoverage(value, lang) {
+    if (value === null) {
+        return t(lang, 'value.none');
+    }
+    return `${(value * 100).toFixed(1)}%`;
+}
+function formatProfileFileCoverage(report) {
+    const declaredCount = report.summary.latest_profile_declared_test_file_count;
+    const denominator = Math.max(declaredCount ?? 0, report.summary.latest_profile_test_file_count);
+    return denominator > 0
+        ? `${report.summary.test_file_count}/${denominator}`
+        : `${report.summary.test_file_count}/0`;
+}
+function renderTestPerformanceReportSummary(report, lang) {
+    const lines = [
+        t(lang, 'testPerformance.title'),
+        `${t(lang, 'scriptPack.label.script')}: ${TEST_PERFORMANCE_REPORT_SCRIPT_REF}`,
+        `${t(lang, 'label.status')}: ${report.status}`,
+        `${t(lang, 'testPerformance.label.samples')}: ${report.summary.sample_count}`,
+        `${t(lang, 'testPerformance.label.intents')}: ${report.summary.intent_count}`,
+        `${t(lang, 'testPerformance.label.testFiles')}: ${report.summary.test_file_count}`,
+        `${t(lang, 'testPerformance.label.findings')}: ${report.findings.length}`,
+        `${t(lang, 'testPerformance.label.truncated')}: ${report.truncated ? t(lang, 'value.yes') : t(lang, 'value.no')}`,
+    ];
+    lines.push(t(lang, 'testPerformance.label.profileEvidence'), `- ${t(lang, 'testPerformance.label.profileGeneratedAt')}: ${report.summary.latest_profile_generated_at ?? t(lang, 'value.none')}`, `- ${t(lang, 'testPerformance.label.profileAge')}: ${formatProfileAge(report.summary.latest_profile_age_ms, lang)}`, `- ${t(lang, 'testPerformance.label.profileFilesShown')}: ${formatProfileFileCoverage(report)}`, `- ${t(lang, 'testPerformance.label.profileCoverage')}: ${formatProfileCoverage(report.summary.latest_profile_test_file_coverage_ratio, lang)}`, `- ${t(lang, 'testPerformance.label.profileFilesTruncated')}: ${report.summary.latest_profile_test_files_truncated ? t(lang, 'value.yes') : t(lang, 'value.no')}`);
+    if (report.intents.length > 0) {
+        lines.push(t(lang, 'testPerformance.label.slowestIntents'));
+        for (const entry of report.intents.slice(0, 20)) {
+            lines.push(`- ${entry.intent}: p95 ${entry.p95_duration_ms}ms, max ${entry.max_duration_ms}ms, ` +
+                `${t(lang, 'testPerformance.label.failures')} ${entry.failure_count}`);
+        }
+    }
+    if (report.test_files.length > 0) {
+        lines.push(t(lang, 'testPerformance.label.slowestTestFiles'));
+        for (const testFile of report.test_files.slice(0, 20)) {
+            lines.push(`- ${testFile.path}: ${testFile.duration_ms}ms, ${testFile.status}`);
+        }
+    }
+    if (report.phases.length > 0) {
+        lines.push(t(lang, 'testPerformance.label.slowestPhases'));
+        for (const phase of report.phases.slice(0, 10)) {
+            lines.push(`- ${phase.name}: p95 ${phase.p95_duration_ms}ms, max ${phase.max_duration_ms}ms`);
+        }
+    }
+    if (report.findings.length > 0) {
+        lines.push(t(lang, 'testPerformance.label.findings'));
+        for (const finding of report.findings.slice(0, 40)) {
+            const intent = finding.intent ? ` ${finding.intent}` : '';
+            const phase = finding.phase ? ` ${finding.phase}` : '';
+            lines.push(`- ${finding.code}${intent}${phase}: ${finding.message}`);
+        }
+    }
+    if (report.next_actions.length > 0) {
+        lines.push(t(lang, 'testPerformance.label.nextActions'));
+        for (const action of report.next_actions) {
+            const runHint = action.run_hint ? ` (${action.run_hint})` : '';
+            lines.push(`- ${action.code}: ${action.message}${runHint}`);
+        }
+    }
+    if (report.issues.length > 0) {
+        lines.push(t(lang, 'testPerformance.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.summary.sample_count === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'testPerformance.clean'));
+    }
+    return lines.join('\n');
+}
+export function runTestPerformanceReportScript(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getTestPerformanceReportHelp(lang));
+        return 0;
+    }
+    const options = parseTestPerformanceReportOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf script-pack run test/performance-report --help', getTestPerformanceReportHelp(lang), lang);
+        return 1;
+    }
+    const report = createTestPerformanceReport(resolveMustflowRoot(), {
+        maxSamples: options.maxSamples ?? undefined,
+        maxIntents: options.maxIntents ?? undefined,
+        maxTestFiles: options.maxTestFiles ?? undefined,
+        maxFindings: options.maxFindings ?? undefined,
+        slowSampleThresholdMs: options.slowMs ?? undefined,
+        highTimeoutRatio: options.timeoutRatio ?? undefined,
+        phaseBottleneckThresholdMs: options.phaseMs ?? undefined,
+    });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderTestPerformanceReportSummary(report, lang));
+    return report.ok ? 0 : 1;
+}

package/dist/cli/script-packs/test-regression-selector.js

@@ -0,0 +1,167 @@
+import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { t } from '../lib/i18n.js';
+import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
+import { resolveMustflowRoot } from '../lib/project-root.js';
+import { createTestRegressionSelectorReport, TEST_REGRESSION_SELECTOR_SCRIPT_REF, } from '../../core/test-regression-selector.js';
+const TEST_REGRESSION_SELECTOR_OPTIONS = [
+    { name: '--json', kind: 'boolean' },
+    { name: '--base', kind: 'string' },
+    { name: '--head', kind: 'string' },
+    { name: '--max-files', kind: 'string' },
+    { name: '--max-tests', kind: 'string' },
+];
+function parsePositiveInteger(value, option, lang) {
+    if (value === null) {
+        return { value: null };
+    }
+    if (!/^[1-9]\d*$/u.test(value)) {
+        return { value: null, error: t(lang, 'testRegressionSelector.error.invalidPositiveInteger', { option, value }) };
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed)) {
+        return { value: null, error: t(lang, 'testRegressionSelector.error.invalidPositiveInteger', { option, value }) };
+    }
+    return { value: parsed };
+}
+export function getTestRegressionSelectorHelp(lang = 'en') {
+    return renderHelp({
+        usage: 'mf script-pack run test/regression-selector select [path...] [options]',
+        summary: t(lang, 'testRegressionSelector.help.summary'),
+        options: [
+            { label: '--base <ref>', description: t(lang, 'testRegressionSelector.help.option.base') },
+            { label: '--head <ref>', description: t(lang, 'testRegressionSelector.help.option.head') },
+            { label: '--max-files <count>', description: t(lang, 'testRegressionSelector.help.option.maxFiles') },
+            { label: '--max-tests <count>', description: t(lang, 'testRegressionSelector.help.option.maxTests') },
+            { label: '--json', description: t(lang, 'cli.option.json') },
+            { label: '-h, --help', description: t(lang, 'cli.option.help') },
+        ],
+        examples: [
+            'mf script-pack run test/regression-selector select --base HEAD --json',
+            'mf script-pack run test/regression-selector select src tests --base main --head HEAD --json',
+            'mf script-pack run test/regression-selector select --max-tests 20',
+        ],
+        exitCodes: [
+            { label: '0', description: t(lang, 'testRegressionSelector.help.exit.ok') },
+            { label: '1', description: t(lang, 'testRegressionSelector.help.exit.fail') },
+        ],
+    }, lang);
+}
+function parseTestRegressionSelectorOptions(args, lang) {
+    const [action, ...rest] = args;
+    const parsed = parseCliOptions(rest, TEST_REGRESSION_SELECTOR_OPTIONS, { allowPositionals: true });
+    const json = hasParsedCliOption(parsed, '--json');
+    const baseRef = getParsedCliStringOption(parsed, '--base');
+    const headRef = getParsedCliStringOption(parsed, '--head');
+    const maxFiles = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-files'), '--max-files', lang);
+    const maxTests = parsePositiveInteger(getParsedCliStringOption(parsed, '--max-tests'), '--max-tests', lang);
+    if (action !== 'select') {
+        return {
+            action: 'select',
+            json,
+            baseRef,
+            headRef,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxTests: maxTests.value,
+            error: action
+                ? t(lang, 'testRegressionSelector.error.unknownAction', { action })
+                : t(lang, 'testRegressionSelector.error.missingAction'),
+        };
+    }
+    if (parsed.error) {
+        return {
+            action,
+            json,
+            baseRef,
+            headRef,
+            paths: parsed.positionals,
+            maxFiles: maxFiles.value,
+            maxTests: maxTests.value,
+            error: formatCliOptionParseError(parsed.error, lang),
+        };
+    }
+    for (const candidate of [maxFiles, maxTests]) {
+        if (candidate.error) {
+            return {
+                action,
+                json,
+                baseRef,
+                headRef,
+                paths: parsed.positionals,
+                maxFiles: maxFiles.value,
+                maxTests: maxTests.value,
+                error: candidate.error,
+            };
+        }
+    }
+    return {
+        action,
+        json,
+        baseRef,
+        headRef,
+        paths: parsed.positionals,
+        maxFiles: maxFiles.value,
+        maxTests: maxTests.value,
+    };
+}
+function renderTestRegressionSelectorSummary(report, lang) {
+    const lines = [
+        t(lang, 'testRegressionSelector.title'),
+        `${t(lang, 'scriptPack.label.script')}: ${TEST_REGRESSION_SELECTOR_SCRIPT_REF}`,
+        `${t(lang, 'label.status')}: ${report.status}`,
+        `${t(lang, 'testRegressionSelector.label.selectionStatus')}: ${report.summary.selection_status}`,
+        `${t(lang, 'testRegressionSelector.label.changedFiles')}: ${report.summary.changed_file_count}`,
+        `${t(lang, 'testRegressionSelector.label.selectedTests')}: ${report.summary.selected_test_count}`,
+        `${t(lang, 'testRegressionSelector.label.fallbacks')}: ${report.summary.fallback_count}`,
+        `${t(lang, 'testRegressionSelector.label.recommendedIntent')}: ${report.summary.recommended_intent}`,
+    ];
+    if (report.selected_tests.length > 0) {
+        lines.push(t(lang, 'testRegressionSelector.label.selectedTests'));
+        for (const testCandidate of report.selected_tests.slice(0, 40)) {
+            lines.push(`- ${testCandidate.path}: ${testCandidate.reasons.join(', ')} (${testCandidate.source_paths.join(', ')})`);
+        }
+    }
+    if (report.fallbacks.length > 0) {
+        lines.push(t(lang, 'testRegressionSelector.label.fallbacks'));
+        for (const fallback of report.fallbacks) {
+            lines.push(`- ${fallback.path}: ${fallback.reason} -> ${fallback.recommended_intent}; ${fallback.message}`);
+        }
+    }
+    if (report.run_hint) {
+        lines.push(`${t(lang, 'testRegressionSelector.label.runHint')}: ${report.run_hint}`);
+    }
+    if (report.findings.length > 0) {
+        lines.push(t(lang, 'testRegressionSelector.label.findings'), ...report.findings.map((finding) => `- ${finding.path}: ${finding.code} (${finding.message})`));
+    }
+    if (report.issues.length > 0) {
+        lines.push(t(lang, 'testRegressionSelector.label.issues'), ...report.issues.map((issue) => `- ${issue}`));
+    }
+    if (report.changed_files.length === 0 && report.findings.length === 0 && report.issues.length === 0) {
+        lines.push(t(lang, 'testRegressionSelector.clean'));
+    }
+    return lines.join('\n');
+}
+export function runTestRegressionSelectorScript(args, reporter, lang = 'en') {
+    if (hasCliOptionToken(args, '--help', ['-h'])) {
+        reporter.stdout(getTestRegressionSelectorHelp(lang));
+        return 0;
+    }
+    const options = parseTestRegressionSelectorOptions(args, lang);
+    if (options.error) {
+        printUsageError(reporter, options.error, 'mf script-pack run test/regression-selector --help', getTestRegressionSelectorHelp(lang), lang);
+        return 1;
+    }
+    const report = createTestRegressionSelectorReport(resolveMustflowRoot(), {
+        baseRef: options.baseRef ?? undefined,
+        headRef: options.headRef,
+        paths: options.paths,
+        maxFiles: options.maxFiles ?? undefined,
+        maxTests: options.maxTests ?? undefined,
+    });
+    if (options.json) {
+        reporter.stdout(JSON.stringify(report, null, 2));
+        return report.ok ? 0 : 1;
+    }
+    reporter.stdout(renderTestRegressionSelectorSummary(report, lang));
+    return report.ok ? 0 : 1;
+}

package/dist/core/change-impact.js

@@ -2,6 +2,7 @@ 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';
@@ -10,12 +11,8 @@ 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, '') || '.';
+    return normalizeChangePath(value);
 }
 function sha256Tagged(value) {
     return `sha256:${createHash('sha256').update(value).digest('hex')}`;
@@ -42,53 +39,11 @@ function isInsideGitWorktree(root) {
 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';
+    return statusFromGitNameStatus(code);
+}
+function surfaceForPath(relativePath) {
+    return classifyChangeSurface(relativePath);
 }
 function parseNameStatus(stdout) {
     const files = [];
@@ -256,8 +211,25 @@ function addDependencyImpacts(root, changedFiles, impacts, policy, findings, iss
 }
 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({