mustflow 2.108.2 → 2.108.8

package/dist/core/repo-toolchain-provenance.js

@@ -0,0 +1,421 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { isRecord, readMustflowOwnedTomlFile } from './config-loading.js';
+export const REPO_TOOLCHAIN_PROVENANCE_PACK_ID = 'repo';
+export const REPO_TOOLCHAIN_PROVENANCE_SCRIPT_ID = 'toolchain-provenance';
+export const REPO_TOOLCHAIN_PROVENANCE_SCRIPT_REF = `${REPO_TOOLCHAIN_PROVENANCE_PACK_ID}/${REPO_TOOLCHAIN_PROVENANCE_SCRIPT_ID}`;
+const DEFAULT_MAX_FILE_BYTES = 256 * 1024;
+const NODE_VERSION_FILES = ['.node-version', '.nvmrc'];
+const PACKAGE_LOCKFILES = ['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb'];
+const PYTHON_LOCKFILES = ['uv.lock', 'poetry.lock', 'Pipfile.lock'];
+const RUST_LOCKFILES = ['Cargo.lock'];
+const GO_LOCKFILES = ['go.sum'];
+const STATIC_SOURCE_PATHS = [
+    'package.json',
+    'pyproject.toml',
+    'go.mod',
+    'rust-toolchain.toml',
+    'rust-toolchain',
+    'mise.toml',
+    '.mise.toml',
+    '.tool-versions',
+    '.python-version',
+    ...NODE_VERSION_FILES,
+    ...PACKAGE_LOCKFILES,
+    ...PYTHON_LOCKFILES,
+    ...RUST_LOCKFILES,
+    ...GO_LOCKFILES,
+    'Dockerfile',
+];
+function sha256(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function normalizeRelativePath(value) {
+    return value.replace(/\\/gu, '/').replace(/^\.\/+/u, '');
+}
+function lineForOffset(content, offset) {
+    let line = 1;
+    for (let index = 0; index < offset; index += 1) {
+        if (content.charCodeAt(index) === 10) {
+            line += 1;
+        }
+    }
+    return line;
+}
+function safeReadText(root, relativePath, maxFileBytes, issues) {
+    const normalized = normalizeRelativePath(relativePath);
+    const absolute = path.join(root, ...normalized.split('/'));
+    try {
+        const stats = statSync(absolute);
+        if (!stats.isFile()) {
+            return null;
+        }
+        if (stats.size > maxFileBytes) {
+            issues.push(`${normalized} exceeds max_file_bytes (${stats.size} > ${maxFileBytes}).`);
+            return null;
+        }
+        return readFileSync(absolute, 'utf8');
+    }
+    catch (error) {
+        if (!existsSync(absolute)) {
+            return null;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(`Could not read ${normalized}: ${message}`);
+        return null;
+    }
+}
+function firstLine(content, pattern) {
+    const match = pattern.exec(content);
+    return match && match.index >= 0 ? lineForOffset(content, match.index) : null;
+}
+function uniqueStrings(values) {
+    return [...new Set([...values].filter((value) => value.trim().length > 0))].sort((left, right) => left.localeCompare(right));
+}
+function addSource(sources, source) {
+    if (typeof source.value !== 'string' || source.value.trim().length === 0) {
+        return;
+    }
+    sources.push({ ...source, value: source.value.trim() });
+}
+function scanPackageJson(root, sources, scannedPaths, issues) {
+    const relativePath = 'package.json';
+    scannedPaths.add(relativePath);
+    const content = safeReadText(root, relativePath, DEFAULT_MAX_FILE_BYTES, issues);
+    if (content === null) {
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(`Could not parse ${relativePath}: ${message}`);
+        return;
+    }
+    if (!isRecord(parsed)) {
+        return;
+    }
+    addSource(sources, {
+        kind: 'package_manager',
+        source_kind: 'package_json',
+        path: relativePath,
+        line: firstLine(content, /"packageManager"\s*:/u),
+        key: 'packageManager',
+        value: parsed.packageManager,
+    });
+    const engines = isRecord(parsed.engines) ? parsed.engines : undefined;
+    addSource(sources, {
+        kind: 'node',
+        source_kind: 'package_json',
+        path: relativePath,
+        line: firstLine(content, /"node"\s*:/u),
+        key: 'engines.node',
+        value: engines?.node,
+    });
+    const devEngines = isRecord(parsed.devEngines) ? parsed.devEngines : undefined;
+    const packageManager = isRecord(devEngines?.packageManager) ? devEngines?.packageManager : undefined;
+    addSource(sources, {
+        kind: 'package_manager',
+        source_kind: 'package_json',
+        path: relativePath,
+        line: firstLine(content, /"packageManager"\s*:/u),
+        key: 'devEngines.packageManager.name',
+        value: packageManager?.name,
+    });
+}
+function scanLineFile(root, relativePath, kind, sourceKind, key, sources, scannedPaths, issues) {
+    scannedPaths.add(relativePath);
+    const content = safeReadText(root, relativePath, DEFAULT_MAX_FILE_BYTES, issues);
+    if (content === null) {
+        return;
+    }
+    const value = content
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .find((line) => line.length > 0 && !line.startsWith('#'));
+    addSource(sources, { kind, source_kind: sourceKind, path: relativePath, line: value ? 1 : null, key, value });
+}
+function scanGoMod(root, sources, scannedPaths, issues) {
+    const relativePath = 'go.mod';
+    scannedPaths.add(relativePath);
+    const content = safeReadText(root, relativePath, DEFAULT_MAX_FILE_BYTES, issues);
+    if (content === null) {
+        return;
+    }
+    for (const [key, pattern] of [
+        ['go', /^go\s+([^\s]+)/mu],
+        ['toolchain', /^toolchain\s+([^\s]+)/mu],
+    ]) {
+        const match = pattern.exec(content);
+        addSource(sources, {
+            kind: 'go',
+            source_kind: 'go_mod',
+            path: relativePath,
+            line: match && match.index >= 0 ? lineForOffset(content, match.index) : null,
+            key,
+            value: match?.[1],
+        });
+    }
+}
+function scanRustToolchain(root, sources, scannedPaths, issues) {
+    for (const relativePath of ['rust-toolchain.toml', 'rust-toolchain']) {
+        scannedPaths.add(relativePath);
+        const content = safeReadText(root, relativePath, DEFAULT_MAX_FILE_BYTES, issues);
+        if (content === null) {
+            continue;
+        }
+        const channel = /channel\s*=\s*["']([^"']+)["']/u.exec(content)?.[1] ?? content.trim().split(/\s+/u)[0];
+        addSource(sources, {
+            kind: 'rust',
+            source_kind: 'rust_toolchain',
+            path: relativePath,
+            line: firstLine(content, /channel\s*=|^\s*[^\s#]+/u),
+            key: 'channel',
+            value: channel,
+        });
+    }
+}
+function scanPyproject(root, sources, scannedPaths, issues) {
+    const relativePath = 'pyproject.toml';
+    scannedPaths.add(relativePath);
+    if (!existsSync(path.join(root, relativePath))) {
+        return;
+    }
+    try {
+        const parsed = readMustflowOwnedTomlFile(root, relativePath);
+        if (!isRecord(parsed)) {
+            return;
+        }
+        const project = isRecord(parsed.project) ? parsed.project : undefined;
+        addSource(sources, {
+            kind: 'python',
+            source_kind: 'pyproject_toml',
+            path: relativePath,
+            line: null,
+            key: 'project.requires-python',
+            value: project?.['requires-python'],
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        issues.push(`Could not parse ${relativePath}: ${message}`);
+    }
+}
+function scanToolVersionFile(root, sources, scannedPaths, issues) {
+    const relativePath = '.tool-versions';
+    scannedPaths.add(relativePath);
+    const content = safeReadText(root, relativePath, DEFAULT_MAX_FILE_BYTES, issues);
+    if (content === null) {
+        return;
+    }
+    for (const [index, line] of content.split(/\r?\n/u).entries()) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        const [name, value] = trimmed.split(/\s+/u);
+        const kind = name === 'nodejs' ? 'node' : name === 'python' ? 'python' : name === 'golang' ? 'go' : name === 'rust' ? 'rust' : null;
+        if (!kind) {
+            continue;
+        }
+        addSource(sources, {
+            kind,
+            source_kind: 'tool_versions',
+            path: relativePath,
+            line: index + 1,
+            key: name,
+            value,
+        });
+    }
+}
+function scanMise(root, sources, scannedPaths, issues) {
+    for (const relativePath of ['mise.toml', '.mise.toml']) {
+        scannedPaths.add(relativePath);
+        const content = safeReadText(root, relativePath, DEFAULT_MAX_FILE_BYTES, issues);
+        if (content === null) {
+            continue;
+        }
+        for (const [tool, kind] of [
+            ['node', 'node'],
+            ['nodejs', 'node'],
+            ['python', 'python'],
+            ['go', 'go'],
+            ['golang', 'go'],
+            ['rust', 'rust'],
+            ['bun', 'bun'],
+        ]) {
+            const pattern = new RegExp(`^\\s*${tool}\\s*=\\s*["']?([^"'\\n#]+)`, 'mu');
+            const match = pattern.exec(content);
+            addSource(sources, {
+                kind,
+                source_kind: 'mise_toml',
+                path: relativePath,
+                line: match && match.index >= 0 ? lineForOffset(content, match.index) : null,
+                key: tool,
+                value: match?.[1],
+            });
+        }
+    }
+}
+function scanDockerAndCi(root, sources, scannedPaths, issues) {
+    for (const relativePath of ['Dockerfile', '.github/workflows/ci.yml', '.github/workflows/ci.yaml']) {
+        scannedPaths.add(relativePath);
+        const content = safeReadText(root, relativePath, DEFAULT_MAX_FILE_BYTES, issues);
+        if (content === null) {
+            continue;
+        }
+        const sourceKind = relativePath === 'Dockerfile' ? 'dockerfile' : 'ci_workflow';
+        for (const [kind, key, pattern] of [
+            ['node', 'node-version', /node-version:\s*['"]?([^'"\n]+)/u],
+            ['python', 'python-version', /python-version:\s*['"]?([^'"\n]+)/u],
+            ['go', 'go-version', /go-version:\s*['"]?([^'"\n]+)/u],
+            ['rust', 'rust-toolchain', /toolchain:\s*['"]?([^'"\n]+)/u],
+            ['docker', 'FROM', /^FROM\s+([^\s]+)/mu],
+        ]) {
+            const match = pattern.exec(content);
+            addSource(sources, {
+                kind,
+                source_kind: sourceKind,
+                path: relativePath,
+                line: match && match.index >= 0 ? lineForOffset(content, match.index) : null,
+                key,
+                value: match?.[1],
+            });
+        }
+    }
+}
+function detectLockfiles(root, scannedPaths) {
+    const lockfiles = [...PACKAGE_LOCKFILES, ...PYTHON_LOCKFILES, ...RUST_LOCKFILES, ...GO_LOCKFILES].filter((relativePath) => {
+        scannedPaths.add(relativePath);
+        return existsSync(path.join(root, relativePath));
+    });
+    return uniqueStrings(lockfiles);
+}
+function createFindings(sources, lockfiles) {
+    const findings = [];
+    const nodeSources = sources.filter((source) => source.kind === 'node' && source.source_kind !== 'ci_workflow');
+    const nodeValues = uniqueStrings(nodeSources.map((source) => source.value));
+    if (nodeValues.length > 1) {
+        findings.push({
+            code: 'conflicting_node_version_sources',
+            severity: 'medium',
+            path: nodeSources[0]?.path ?? 'package.json',
+            message: 'Multiple local Node version declarations were detected. Review which source owns the runtime contract.',
+            json_pointer: null,
+            metric: 'node_version_source_count',
+            actual: nodeValues.length,
+            expected: 1,
+        });
+    }
+    const packageLockfiles = lockfiles.filter((lockfile) => PACKAGE_LOCKFILES.includes(lockfile));
+    if (packageLockfiles.length > 1) {
+        findings.push({
+            code: 'conflicting_package_manager_lockfiles',
+            severity: 'high',
+            path: packageLockfiles[0] ?? 'package.json',
+            message: 'Multiple JavaScript package-manager lockfiles were detected.',
+            json_pointer: null,
+            metric: 'package_manager_lockfile_count',
+            actual: packageLockfiles.length,
+            expected: 1,
+        });
+    }
+    const packageManagerSources = sources.filter((source) => source.kind === 'package_manager');
+    if (packageManagerSources.length > 0 && packageLockfiles.length === 0) {
+        findings.push({
+            code: 'package_manager_without_lockfile',
+            severity: 'medium',
+            path: packageManagerSources[0]?.path ?? 'package.json',
+            message: 'A package manager is declared, but no JavaScript lockfile was detected.',
+            json_pointer: null,
+            metric: 'package_manager_lockfile_count',
+            actual: 0,
+            expected: 1,
+        });
+    }
+    if (sources.some((source) => source.kind === 'node') && packageManagerSources.length === 0) {
+        findings.push({
+            code: 'toolchain_declared_without_package_manager',
+            severity: 'low',
+            path: sources.find((source) => source.kind === 'node')?.path ?? 'package.json',
+            message: 'Node is declared, but no package manager provenance was detected.',
+            json_pointer: null,
+            metric: 'package_manager_source_count',
+            actual: 0,
+            expected: 1,
+        });
+    }
+    for (const source of sources.filter((entry) => entry.source_kind === 'ci_workflow')) {
+        const localSameKind = sources.some((entry) => entry.kind === source.kind && entry.source_kind !== 'ci_workflow');
+        if (!localSameKind) {
+            findings.push({
+                code: 'runtime_declared_in_ci_only',
+                severity: 'low',
+                path: source.path,
+                message: `${source.kind} runtime appears in CI, but no local repository contract was detected.`,
+                json_pointer: null,
+                metric: null,
+                actual: null,
+                expected: null,
+            });
+        }
+    }
+    return findings;
+}
+function createSummary(sources, lockfiles, findings) {
+    const runtimeKinds = uniqueStrings(sources.filter((source) => source.kind !== 'package_manager').map((source) => source.kind));
+    return {
+        source_count: sources.length,
+        runtime_count: runtimeKinds.length,
+        package_manager_count: sources.filter((source) => source.kind === 'package_manager').length,
+        lockfile_count: lockfiles.length,
+        ci_source_count: sources.filter((source) => source.source_kind === 'ci_workflow').length,
+        finding_count: findings.length,
+    };
+}
+export function inspectRepoToolchainProvenance(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const issues = [];
+    const scannedPaths = new Set(STATIC_SOURCE_PATHS);
+    const sources = [];
+    scanPackageJson(root, sources, scannedPaths, issues);
+    for (const nodePath of NODE_VERSION_FILES) {
+        scanLineFile(root, nodePath, 'node', 'node_version_file', nodePath, sources, scannedPaths, issues);
+    }
+    scanLineFile(root, '.python-version', 'python', 'python_version_file', '.python-version', sources, scannedPaths, issues);
+    scanPyproject(root, sources, scannedPaths, issues);
+    scanGoMod(root, sources, scannedPaths, issues);
+    scanRustToolchain(root, sources, scannedPaths, issues);
+    scanToolVersionFile(root, sources, scannedPaths, issues);
+    scanMise(root, sources, scannedPaths, issues);
+    scanDockerAndCi(root, sources, scannedPaths, issues);
+    const lockfiles = detectLockfiles(root, scannedPaths);
+    const sortedSources = sources.sort((left, right) => left.path.localeCompare(right.path) || left.key.localeCompare(right.key));
+    const findings = createFindings(sortedSources, lockfiles);
+    const summary = createSummary(sortedSources, lockfiles, findings);
+    const status = issues.length > 0 ? 'error' : findings.length > 0 ? 'failed' : 'passed';
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        pack_id: REPO_TOOLCHAIN_PROVENANCE_PACK_ID,
+        script_id: REPO_TOOLCHAIN_PROVENANCE_SCRIPT_ID,
+        script_ref: REPO_TOOLCHAIN_PROVENANCE_SCRIPT_REF,
+        action: 'inspect',
+        status,
+        ok: status === 'passed',
+        mustflow_root: root,
+        input: {
+            scanned_paths: uniqueStrings(scannedPaths),
+            max_file_bytes: DEFAULT_MAX_FILE_BYTES,
+        },
+        input_hash: sha256(JSON.stringify({ summary, sources: sortedSources, lockfiles, findings, issues })),
+        summary,
+        sources: sortedSources,
+        lockfiles,
+        findings,
+        issues,
+    };
+}

package/dist/core/script-pack-suggestions.js

@@ -11,7 +11,7 @@ const CODE_NAVIGATION_SCRIPT_REFS = new Set([
     'repo/related-files',
 ]);
 const CONFIG_CHAIN_SURFACES = new Set(['config', 'package', 'source', 'test']);
-const CONFIG_FILE_PATTERN = /(?:^|\/)(?:\.gitignore|\.env\.(?:example|sample|template|defaults)|\.dev\.vars\.example|tsconfig(?:\..*)?\.json|eslint\.config\.[cm]?[jt]s|\.eslintrc(?:\.json)?|\.prettierrc(?:\.json)?|prettier\.config\.[cm]?[jt]s|vite\.config\.[cm]?[jt]s|vitest\.config\.[cm]?[jt]s|tailwind\.config\.[cm]?[jt]s|jest\.config\.[cm]?[jt]s|playwright\.config\.[cm]?[jt]s|astro\.config\.mjs|svelte\.config\.js|wrangler\.(?:toml|jsonc?)|vercel\.json|netlify\.toml|Dockerfile|docker-compose\.ya?ml|compose\.ya?ml)$/u;
+const CONFIG_FILE_PATTERN = /(?:^|\/)(?:\.gitignore|\.env\.(?:example|sample|template|defaults)|\.dev\.vars\.example|\.nvmrc|\.node-version|\.python-version|\.tool-versions|mise\.toml|\.mise\.toml|pyproject\.toml|go\.mod|rust-toolchain(?:\.toml)?|Makefile|Taskfile\.ya?ml|justfile|Justfile|tsconfig(?:\..*)?\.json|eslint\.config\.[cm]?[jt]s|\.eslintrc(?:\.json)?|\.prettierrc(?:\.json)?|prettier\.config\.[cm]?[jt]s|vite\.config\.[cm]?[jt]s|vitest\.config\.[cm]?[jt]s|tailwind\.config\.[cm]?[jt]s|jest\.config\.[cm]?[jt]s|playwright\.config\.[cm]?[jt]s|astro\.config\.mjs|svelte\.config\.js|wrangler\.(?:toml|jsonc?)|vercel\.json|netlify\.toml|Dockerfile|docker-compose\.ya?ml|compose\.ya?ml)$/u;
 export function isScriptPackSuggestionPhase(value) {
     return ['before_change', 'during_change', 'after_change', 'review'].includes(value);
 }
@@ -70,7 +70,15 @@ export function classifyScriptPackPathSurface(relativePath) {
     }
     if (normalized === 'package.json' ||
         normalized === 'bun.lock' ||
+        normalized === 'bun.lockb' ||
         normalized === 'package-lock.json' ||
+        normalized === 'npm-shrinkwrap.json' ||
+        normalized === 'pnpm-lock.yaml' ||
+        normalized === 'yarn.lock' ||
+        normalized === 'uv.lock' ||
+        normalized === 'poetry.lock' ||
+        normalized === 'Cargo.lock' ||
+        normalized === 'go.sum' ||
         normalized.startsWith('.github/workflows/')) {
         surfaces.push('package');
     }
@@ -267,6 +275,15 @@ function createRunHint(script, analyzedPaths) {
     if (script.ref === 'repo/version-source') {
         return 'mf script-pack run repo/version-source inspect --json';
     }
+    if (script.ref === 'repo/toolchain-provenance') {
+        return 'mf script-pack run repo/toolchain-provenance inspect --json';
+    }
+    if (script.ref === 'repo/automation-surface') {
+        return 'mf script-pack run repo/automation-surface inspect --json';
+    }
+    if (script.ref === 'repo/dependency-surface') {
+        return 'mf script-pack run repo/dependency-surface inspect --json';
+    }
     if (script.ref === 'repo/approval-gate') {
         return 'mf script-pack run repo/approval-gate check --action <action_type> --json';
     }
@@ -386,6 +403,21 @@ export function createScriptPackSuggestionReport(mustflowRoot, options) {
             score += 2;
             reasons.push('Prioritizes deploy-surface inspection for push, tag, release, docs, and package publication follow-up.');
         }
+        if (script.ref === 'repo/toolchain-provenance' &&
+            (requestedSurfaces.has('package') || requestedSurfaces.has('config'))) {
+            score += 2;
+            reasons.push('Prioritizes toolchain provenance for runtime, package-manager, lockfile, Docker, and CI contract surfaces.');
+        }
+        if (script.ref === 'repo/automation-surface' &&
+            (requestedSurfaces.has('package') || requestedSurfaces.has('config'))) {
+            score += 2;
+            reasons.push('Prioritizes automation surface inspection for package scripts, workflows, and command-intent mapping.');
+        }
+        if (script.ref === 'repo/dependency-surface' &&
+            (requestedSurfaces.has('package') || requestedSurfaces.has('config'))) {
+            score += 2;
+            reasons.push('Prioritizes dependency surface inspection for manifests, lockfiles, update automation, and audit policy evidence.');
+        }
         if (script.ref === 'repo/security-pattern-scan' &&
             (hasSourcePath ||
                 requestedSurfaces.has('config') ||

package/package.json

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

package/schemas/README.md

@@ -165,6 +165,16 @@ Current schemas:
 - `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-toolchain-provenance-report.schema.json`: output of
+  `mf script-pack run repo/toolchain-provenance inspect --json`, containing repository-visible
+  runtime, package-manager, lockfile, Docker, and CI toolchain provenance evidence
+- `repo-automation-surface-report.schema.json`: output of
+  `mf script-pack run repo/automation-surface inspect --json`, containing package scripts,
+  task-runner entries, CI workflows, mustflow command intents, risk classifications, and
+  command-contract coverage findings
+- `repo-dependency-surface-report.schema.json`: output of
+  `mf script-pack run repo/dependency-surface inspect --json`, containing dependency manifests,
+  lockfiles, update automation, audit, license, and SBOM policy surfaces
 - `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

package/schemas/repo-automation-surface-report.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/repo-automation-surface-report.schema.json",
+  "title": "mustflow repo automation-surface report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "input",
+    "input_hash",
+    "summary",
+    "surfaces",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "repo" },
+    "script_id": { "const": "automation-surface" },
+    "script_ref": { "const": "repo/automation-surface" },
+    "action": { "const": "inspect" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "input": { "$ref": "#/$defs/input" },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "surfaces": { "type": "array", "items": { "$ref": "#/$defs/surface" } },
+    "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
+    "issues": { "type": "array", "items": { "type": "string" } }
+  },
+  "$defs": {
+    "sha256": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["scanned_paths", "max_file_bytes"],
+      "properties": {
+        "scanned_paths": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "max_file_bytes": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "surface_count",
+        "mustflow_intent_count",
+        "raw_surface_count",
+        "agent_allowed_intent_count",
+        "manual_only_intent_count",
+        "risky_surface_count",
+        "long_running_surface_count"
+      ],
+      "properties": {
+        "surface_count": { "type": "integer", "minimum": 0 },
+        "mustflow_intent_count": { "type": "integer", "minimum": 0 },
+        "raw_surface_count": { "type": "integer", "minimum": 0 },
+        "agent_allowed_intent_count": { "type": "integer", "minimum": 0 },
+        "manual_only_intent_count": { "type": "integer", "minimum": 0 },
+        "risky_surface_count": { "type": "integer", "minimum": 0 },
+        "long_running_surface_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "surface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "path",
+        "line",
+        "name",
+        "command_hint",
+        "category",
+        "risks",
+        "mapped_intent",
+        "agent_allowed"
+      ],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "kind": { "enum": ["ci_workflow", "make_target", "mise_task", "mustflow_intent", "package_script", "taskfile_task"] },
+        "path": { "type": "string", "minLength": 1 },
+        "line": { "type": ["integer", "null"], "minimum": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "command_hint": { "type": ["string", "null"] },
+        "category": {
+          "enum": [
+            "bootstrap",
+            "check",
+            "clean",
+            "db",
+            "deploy",
+            "deps",
+            "dev_server",
+            "doctor",
+            "fix",
+            "release",
+            "smoke",
+            "test",
+            "watch",
+            "workflow",
+            "unknown"
+          ]
+        },
+        "risks": {
+          "type": "array",
+          "items": {
+            "enum": ["destructive", "git_state", "interactive", "long_running", "network", "release", "secret", "writes"]
+          }
+        },
+        "mapped_intent": { "type": ["string", "null"] },
+        "agent_allowed": { "type": ["boolean", "null"] }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message", "path", "json_pointer", "metric", "actual", "expected"],
+      "properties": {
+        "code": {
+          "enum": [
+            "dangerous_automation_surface",
+            "long_running_automation_surface",
+            "raw_command_without_mustflow_intent",
+            "mustflow_intent_manual_boundary"
+          ]
+        },
+        "severity": { "enum": ["low", "medium", "high", "critical"] },
+        "message": { "type": "string" },
+        "path": { "type": "string", "minLength": 1 },
+        "json_pointer": { "type": ["string", "null"] },
+        "metric": { "type": ["string", "null"] },
+        "actual": { "type": ["number", "null"] },
+        "expected": { "type": ["number", "null"] }
+      }
+    }
+  }
+}