mustflow 2.84.0 → 2.99.0

package/dist/core/test-regression-selector.js

@@ -0,0 +1,335 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { classifyChangeSurface, normalizeChangePath, selectorFallbackForChangedPath, statusFromGitNameStatus, } from './change-surface-classification.js';
+import { inspectDependencyGraph } from './dependency-graph.js';
+export const TEST_REGRESSION_SELECTOR_PACK_ID = 'test';
+export const TEST_REGRESSION_SELECTOR_SCRIPT_ID = 'regression-selector';
+export const TEST_REGRESSION_SELECTOR_SCRIPT_REF = `${TEST_REGRESSION_SELECTOR_PACK_ID}/${TEST_REGRESSION_SELECTOR_SCRIPT_ID}`;
+const DEFAULT_BASE_REF = 'HEAD';
+const DEFAULT_MAX_FILES = 200;
+const DEFAULT_MAX_TESTS = 100;
+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, { includeDocsSite: true });
+}
+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 collectChangedFiles(root, policy, findings, issues) {
+    if (!isInsideGitWorktree(root)) {
+        const message = 'Git worktree is unavailable; regression-selector cannot inspect changed files.';
+        findings.push(makeFinding('test_regression_selector_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('test_regression_selector_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 = `Regression selector matched ${files.length} files; max_files is ${policy.max_files}.`;
+        findings.push(makeFinding('test_regression_selector_max_files_exceeded', 'high', '.', message));
+        issues.push(message);
+    }
+    return files.slice(0, policy.max_files);
+}
+function siblingBase(relativePath) {
+    const normalized = normalizeRelativePath(relativePath);
+    const directory = path.posix.dirname(normalized);
+    const parsed = path.posix.parse(normalized);
+    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 addTestCandidate(root, candidates, pathValue, reason, sourcePath, confidence) {
+    const normalized = normalizeRelativePath(pathValue);
+    const existing = candidates.get(normalized);
+    if (existing) {
+        const reasons = [...new Set([...existing.reasons, reason])];
+        const sourcePaths = [...new Set([...existing.source_paths, sourcePath])];
+        const primaryReason = confidence > existing.confidence ? reason : existing.reason;
+        const primarySourcePath = confidence > existing.confidence ? sourcePath : existing.source_path;
+        candidates.set(normalized, {
+            ...existing,
+            reason: primaryReason,
+            reasons,
+            source_path: primarySourcePath,
+            source_paths: sourcePaths,
+            confidence: Math.max(existing.confidence, confidence),
+        });
+        return;
+    }
+    candidates.set(normalized, {
+        path: normalized,
+        exists: existsSync(path.join(root, ...normalized.split('/'))),
+        reason,
+        reasons: [reason],
+        source_path: sourcePath,
+        source_paths: [sourcePath],
+        confidence,
+    });
+}
+function addChangedFileCandidates(root, changedFiles, candidates) {
+    for (const changedFile of changedFiles) {
+        if (changedFile.surface === 'test' && changedFile.status !== 'deleted') {
+            addTestCandidate(root, candidates, changedFile.path, 'changed_test', changedFile.path, 1);
+        }
+        if (changedFile.surface === 'source' && changedFile.status !== 'deleted') {
+            for (const candidatePath of testCandidatesFor(changedFile.path)) {
+                addTestCandidate(root, candidates, candidatePath, 'sibling_test', changedFile.path, 0.7);
+            }
+        }
+    }
+}
+function addImporterCandidates(root, changedFiles, candidates, 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: Math.max(sourcePaths.length, 50),
+        maxFileBytes: 256 * 1024,
+        maxNodes: 200,
+        maxEdges: 300,
+    });
+    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;
+        }
+        for (const candidatePath of testCandidatesFor(edge.source_path)) {
+            addTestCandidate(root, candidates, candidatePath, 'importer_sibling_test', edge.target_path, 0.6);
+        }
+    }
+}
+function fallbackForChangedFile(changedFile) {
+    return selectorFallbackForChangedPath(changedFile);
+}
+function chooseRecommendedIntent(selectedTests, fallbacks, changedFiles) {
+    if (fallbacks.some((fallback) => fallback.recommended_intent === 'test')) {
+        return 'test';
+    }
+    if (fallbacks.some((fallback) => fallback.recommended_intent === 'test_release')) {
+        return 'test_release';
+    }
+    if (fallbacks.length > 0) {
+        return 'test_related';
+    }
+    if (selectedTests.length > 0 || changedFiles.some((file) => file.surface === 'source' || file.surface === 'test')) {
+        return 'test_related_cached';
+    }
+    return 'changes_status';
+}
+function confidenceFor(selectedTests, fallbacks, changedFiles) {
+    if (fallbacks.length > 0) {
+        return 'low';
+    }
+    if (selectedTests.length === 0 || changedFiles.length === 0) {
+        return 'low';
+    }
+    if (changedFiles.every((file) => file.surface === 'test')) {
+        return 'high';
+    }
+    return 'medium';
+}
+function selectionStatus(selectedTests, fallbacks, changedFiles) {
+    if (fallbacks.length > 0) {
+        return 'fallback';
+    }
+    if (changedFiles.length === 0 || selectedTests.length === 0) {
+        return 'empty';
+    }
+    return 'selected';
+}
+function createRunHint(selectedTests, recommendedIntent) {
+    if (recommendedIntent === 'test_related_cached' && selectedTests.length > 0) {
+        return `MUSTFLOW_TEST_CHANGED_FILES=${selectedTests.map((test) => test.path).join(',')} mf run test_related_cached`;
+    }
+    if (recommendedIntent === 'test_related' || recommendedIntent === 'test_release' || recommendedIntent === 'test') {
+        return `mf run ${recommendedIntent}`;
+    }
+    return null;
+}
+export function createTestRegressionSelectorReport(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_tests: options.maxTests ?? DEFAULT_MAX_TESTS,
+        path_filters: (options.paths ?? []).map(normalizeRelativePath),
+    };
+    const findings = [];
+    const issues = [];
+    const changedFiles = collectChangedFiles(root, policy, findings, issues);
+    const candidates = new Map();
+    addChangedFileCandidates(root, changedFiles, candidates);
+    addImporterCandidates(root, changedFiles, candidates, issues);
+    const fallbackMap = new Map();
+    for (const changedFile of changedFiles) {
+        const fallback = fallbackForChangedFile(changedFile);
+        if (fallback) {
+            fallbackMap.set(`${fallback.reason}:${fallback.path}`, fallback);
+        }
+    }
+    if (findings.some((finding) => finding.code === 'test_regression_selector_max_files_exceeded')) {
+        fallbackMap.set('fallback_truncated:.', {
+            reason: 'fallback_truncated',
+            path: '.',
+            message: 'Changed-file input was truncated by max_files.',
+            recommended_intent: 'test',
+        });
+    }
+    if (changedFiles.length === 0) {
+        fallbackMap.set('no_changed_files:.', {
+            reason: 'no_changed_files',
+            path: '.',
+            message: 'No changed files were detected for regression selection.',
+            recommended_intent: 'changes_status',
+        });
+    }
+    const sortedCandidates = [...candidates.values()].sort((left, right) => Number(right.exists) - Number(left.exists) || right.confidence - left.confidence || left.path.localeCompare(right.path));
+    const selectedTests = sortedCandidates.filter((candidate) => candidate.exists).slice(0, policy.max_tests);
+    const missingCandidates = sortedCandidates.filter((candidate) => !candidate.exists).slice(0, policy.max_tests);
+    const truncated = sortedCandidates.filter((candidate) => candidate.exists).length > selectedTests.length;
+    if (truncated) {
+        const message = `Regression selector found more than ${policy.max_tests} existing test candidates.`;
+        findings.push(makeFinding('test_regression_selector_max_tests_exceeded', 'medium', '.', message));
+        issues.push(message);
+    }
+    const fallbacks = [...fallbackMap.values()].sort((left, right) => left.recommended_intent.localeCompare(right.recommended_intent) || left.path.localeCompare(right.path));
+    const recommendedIntent = chooseRecommendedIntent(selectedTests, fallbacks, changedFiles);
+    const selectorStatus = selectionStatus(selectedTests, fallbacks, changedFiles);
+    const status = findings.some((finding) => finding.severity === 'high' || finding.severity === 'critical')
+        ? 'failed'
+        : 'passed';
+    const summary = {
+        changed_file_count: changedFiles.length,
+        selected_test_count: selectedTests.length,
+        missing_candidate_count: missingCandidates.length,
+        fallback_count: fallbacks.length,
+        selection_status: selectorStatus,
+        confidence: confidenceFor(selectedTests, fallbacks, changedFiles),
+        recommended_intent: recommendedIntent,
+    };
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        pack_id: TEST_REGRESSION_SELECTOR_PACK_ID,
+        script_id: TEST_REGRESSION_SELECTOR_SCRIPT_ID,
+        script_ref: TEST_REGRESSION_SELECTOR_SCRIPT_REF,
+        action: 'select',
+        status,
+        ok: status === 'passed',
+        mustflow_root: root,
+        policy,
+        input_hash: sha256Tagged(JSON.stringify({ policy, changedFiles, selectedTests, fallbacks })),
+        summary,
+        changed_files: changedFiles,
+        selected_tests: selectedTests,
+        missing_candidates: missingCandidates,
+        fallbacks,
+        run_hint: createRunHint(selectedTests, recommendedIntent),
+        truncated,
+        findings,
+        issues,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.84.0",
+  "version": "2.99.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/README.md

@@ -69,6 +69,19 @@ Current schemas:
   file hashes, language metadata, symbol names, declaration kinds, line ranges, signatures, export
   flags, source-anchor navigation metadata, static return metadata, and stable input-limit finding
   codes
+- `dependency-graph-report.schema.json`: output of
+  `mf script-pack run code/dependency-graph scan <path...> --json`, containing bounded relative
+  TypeScript and JavaScript import graph nodes, edges, cycle hints, target flags, depth, importer
+  counts, policy limits, and stable input-limit finding codes
+- `import-cycle-report.schema.json`: output of
+  `mf script-pack run code/import-cycle check <path...> --json`, containing bounded relative
+  TypeScript and JavaScript import cycles with exact cycle paths, import line evidence, policy
+  limits, and stable cycle or input-limit finding codes
+- `change-impact-report.schema.json`: output of
+  `mf script-pack run code/change-impact analyze [path...] --json`, containing git-diff changed
+  files, surface classifications, bounded impact candidates, script-pack hints with related
+  verification intent and selected-test fallback evidence, verification intent hints, policy limits,
+  and stable git or input-limit finding codes
 - `code-symbol-read-report.schema.json`: output of
   `mf script-pack run code/symbol-read read <path> --start-line <line> --json`, containing a
   focused source snippet selected by source anchor, outline symbol line, or explicit line range with
@@ -87,10 +100,30 @@ Current schemas:
   `mf script-pack run docs/reference-drift check [path...] --json`, containing checked
   documentation references to `mf` commands, script-pack refs, schema files, repository paths,
   and stable stale-reference finding codes
+- `link-integrity-report.schema.json`: output of
+  `mf script-pack run docs/link-integrity check [path...] --json`, containing checked Markdown
+  and MDX inline links, local file and anchor resolution status, skipped external URL metadata,
+  and stable missing-link finding codes
+- `test-performance-report.schema.json`: output of
+  `mf script-pack run test/performance-report summarize --json`, containing retained run
+  performance evidence, slow intent summaries, timeout-pressure findings, selected-test fallback
+  signals, and phase bottleneck summaries from `.mustflow/state`
+- `test-regression-selector-report.schema.json`: output of
+  `mf script-pack run test/regression-selector select --json`, containing changed files, likely
+  regression-test candidates with selection evidence, conservative fallback reasons, confidence,
+  and recommended verification intent hints
 - `config-chain-report.schema.json`: output of
   `mf script-pack run repo/config-chain inspect <path...> --json`, containing nearby package,
   TypeScript, ESLint, Prettier, Vite, Vitest, Tailwind, Jest, Playwright, and mustflow config files
   with static inheritance, reference, workspace, dynamic-config, path, and content-hash metadata
+- `env-contract-report.schema.json`: output of
+  `mf script-pack run repo/env-contract scan [path...] --json`, containing code, CI, docs, config,
+  and env-example references for environment-variable contract drift without reading secret env files
+  or printing env values
+- `secret-risk-scan-report.schema.json`: output of
+  `mf script-pack run repo/secret-risk-scan scan [path...] --json`, containing plausible
+  hardcoded-secret findings with detector names, paths, line numbers, and redacted fingerprints
+  without printing secret values
 - `text-budget-report.schema.json`: output of
   `mf script-pack run core/text-budget check <path...> --json`, containing
   exact text-budget metrics, input content hashes, policy metadata, findings, and JSON Pointer field
@@ -98,6 +131,27 @@ Current schemas:
 - `generated-boundary-report.schema.json`: output of
   `mf script-pack run repo/generated-boundary check <path...> --json`, containing candidate path
   classifications for generated, ignored, protected, vendor, and cache boundaries before or after edits
+- `repo-merge-conflict-scan-report.schema.json`: output of
+  `mf script-pack run repo/merge-conflict-scan check [path...] --json`, containing checked files,
+  redaction-safe Git merge conflict marker locations, marker summaries, and stable conflict-marker
+  finding codes
+- `repo-git-ignore-audit-report.schema.json`: output of
+  `mf script-pack run repo/git-ignore-audit audit [path...] --json`, containing Git ignore source
+  metadata, explicit path visibility status, ignore-rule evidence, tracked-path caveats, and stable
+  ignored-path finding codes without reading ignored file content
+- `repo-manifest-lock-drift-report.schema.json`: output of
+  `mf script-pack run repo/manifest-lock-drift check [path...] --json`, containing manifest-lock
+  metadata, locked file existence, hash comparison status, and stable drift finding codes without
+  rewriting `.mustflow/config/manifest.lock.toml`
+- `skill-route-audit-report.schema.json`: output of
+  `mf script-pack run repo/skill-route-audit audit --json`, containing source skill, route metadata,
+  skill index, default template skill copy, manifest profile, and i18n metadata drift findings
+- `repo-version-source-report.schema.json`: output of
+  `mf script-pack run repo/version-source inspect --json`, containing detected version sources,
+  release-versioning preference status, source authority counts, and missing-source findings
+- `repo-approval-gate-report.schema.json`: output of
+  `mf script-pack run repo/approval-gate check --action <type> --json`, containing approval policy
+  decisions, required-action findings, and unreadable policy issues
 - `related-files-report.schema.json`: output of
   `mf script-pack run repo/related-files map <path...> --json`, containing conservative related-file
   candidates from direct imports, importers, same-basename siblings, parent configuration files, and

package/schemas/change-impact-report.schema.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/change-impact-report.schema.json",
+  "title": "mustflow change-impact report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "policy",
+    "input_hash",
+    "changed_files",
+    "impacts",
+    "script_hints",
+    "verification_hints",
+    "truncated",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "code" },
+    "script_id": { "const": "change-impact" },
+    "script_ref": { "const": "code/change-impact" },
+    "action": { "const": "analyze" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "policy": { "$ref": "#/$defs/policy" },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "changed_files": { "type": "array", "items": { "$ref": "#/$defs/changedFile" } },
+    "impacts": { "type": "array", "items": { "$ref": "#/$defs/impact" } },
+    "script_hints": { "type": "array", "items": { "$ref": "#/$defs/scriptHint" } },
+    "verification_hints": { "type": "array", "items": { "$ref": "#/$defs/verificationHint" } },
+    "truncated": { "type": "boolean" },
+    "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
+    "issues": { "type": "array", "items": { "type": "string" } }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "surface": {
+      "enum": ["source", "test", "docs", "schema", "config", "package", "template", "workflow", "i18n", "unknown"]
+    },
+    "selectorReason": {
+      "enum": [
+        "changed_test",
+        "sibling_test",
+        "importer_sibling_test",
+        "fallback_lockfile",
+        "fallback_package_metadata",
+        "fallback_template",
+        "fallback_compiler_or_runner_config",
+        "fallback_shared_test_fixture",
+        "fallback_migration_or_database",
+        "fallback_generated_contract",
+        "fallback_ci_workflow",
+        "fallback_mustflow_workflow",
+        "fallback_deleted",
+        "fallback_renamed",
+        "fallback_type_changed",
+        "fallback_package_or_template",
+        "fallback_schema",
+        "fallback_workflow_or_config",
+        "fallback_deleted_or_renamed",
+        "fallback_unknown",
+        "fallback_truncated",
+        "no_changed_files"
+      ]
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "base_ref",
+        "head_ref",
+        "compare_worktree",
+        "max_files",
+        "max_impacts",
+        "max_file_bytes",
+        "path_filters"
+      ],
+      "properties": {
+        "base_ref": { "type": "string" },
+        "head_ref": { "type": ["string", "null"] },
+        "compare_worktree": { "type": "boolean" },
+        "max_files": { "type": "integer", "minimum": 1 },
+        "max_impacts": { "type": "integer", "minimum": 1 },
+        "max_file_bytes": { "type": "integer", "minimum": 1 },
+        "path_filters": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "changedFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "previous_path", "status", "surface"],
+      "properties": {
+        "path": { "type": "string" },
+        "previous_path": { "type": ["string", "null"] },
+        "status": { "enum": ["added", "modified", "deleted", "renamed", "type_changed", "untracked"] },
+        "surface": { "$ref": "#/$defs/surface" }
+      }
+    },
+    "impact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "exists", "surface", "relationship", "confidence", "reason", "source_path"],
+      "properties": {
+        "path": { "type": "string" },
+        "exists": { "type": "boolean" },
+        "surface": { "$ref": "#/$defs/surface" },
+        "relationship": {
+          "enum": [
+            "changed_file",
+            "imports_changed_file",
+            "sibling_test",
+            "sibling_source",
+            "contract_doc",
+            "contract_test",
+            "package_surface",
+            "workflow_surface"
+          ]
+        },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "reason": { "type": "string" },
+        "source_path": { "type": "string" }
+      }
+    },
+    "scriptHint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["script_ref", "command", "reason", "confidence"],
+      "properties": {
+        "script_ref": { "type": "string" },
+        "command": { "type": "string" },
+        "reason": { "type": "string" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "related_intents": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "expected_fallback_reasons": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/selectorReason" }
+        }
+      }
+    },
+    "verificationHint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["intent", "reason", "confidence"],
+      "properties": {
+        "intent": { "type": "string" },
+        "reason": { "type": "string" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message", "path"],
+      "properties": {
+        "code": {
+          "enum": [
+            "change_impact_git_unavailable",
+            "change_impact_invalid_ref",
+            "change_impact_max_files_exceeded",
+            "change_impact_max_impacts_exceeded"
+          ]
+        },
+        "severity": { "enum": ["low", "medium", "high", "critical"] },
+        "message": { "type": "string" },
+        "path": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/commands.schema.json

@@ -47,6 +47,18 @@
     "resources": {
       "type": "object",
       "additionalProperties": { "$ref": "#/$defs/resource" }
+    },
+    "include": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["files"],
+      "properties": {
+        "files": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^commands/(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+\\.toml$" },
+          "uniqueItems": true
+        }
+      }
     }
   },
   "$defs": {