mustflow 2.22.46 → 2.22.47

package/dist/cli/commands/verify.js

@@ -6,6 +6,7 @@ import { readUtf8FileInsideWithoutSymlinks, writeJsonFileInsideWithoutSymlinks }
 import { createVerifyCompletionVerdict, } from '../../core/completion-verdict.js';
 import { createExternalEvidenceRisks, } from '../../core/external-evidence.js';
 import { createRepeatedFailureRisks, createVerificationFailureFingerprint, updateRepeatedFailureState, } from '../../core/repeated-failure.js';
+import { createVerificationPlanId } from '../../core/verification-plan-id.js';
 import { countReproEvidenceVerdictEffects, createReproEvidenceRisks, } from '../../core/repro-evidence.js';
 import { createVerifyEvidenceModel } from '../../core/verification-evidence.js';
 import { createScopeDiffRisks } from '../../core/scope-risk.js';
@@ -24,6 +25,9 @@ import { readLocalCommandEffectGraphs, readLocalPathSurfaces, readLocalSourceAnc
 import { resolveMustflowRoot } from '../lib/project-root.js';
 export { planErrorMessageKey, readInputFromClassificationReport } from './verify/input.js';
 const VERIFY_SCHEMA_VERSION = '1';
+function hashTextSha256(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
 function createBufferedOutput() {
     const stdout = [];
     const stderr = [];
@@ -569,49 +573,6 @@ function readPreviousVerifyLatestSummary(projectRoot) {
         return null;
     }
 }
-function hashTextSha256(content) {
-    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
-}
-function stableJson(value) {
-    if (Array.isArray(value)) {
-        return `[${value.map((entry) => stableJson(entry)).join(',')}]`;
-    }
-    if (value && typeof value === 'object') {
-        const record = value;
-        return `{${Object.keys(record)
-            .sort((left, right) => left.localeCompare(right))
-            .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
-            .join(',')}}`;
-    }
-    return JSON.stringify(value) ?? 'null';
-}
-function getCandidateIntentNames(report) {
-    return [...new Set(report.candidates.map((candidate) => candidate.intent).filter((intent) => Boolean(intent)))]
-        .sort((left, right) => left.localeCompare(right));
-}
-function createVerificationPlanId(report, contract) {
-    const relatedIntents = Object.fromEntries(getCandidateIntentNames(report).map((intent) => [intent, contract.intents[intent] ?? null]));
-    const fingerprintSource = {
-        schema_version: '1',
-        algorithm: 'mustflow.verify_plan_id.v1',
-        report: {
-            source: report.source,
-            files: report.files,
-            classification_summary: report.classification_summary,
-            requirements: report.requirements,
-            candidates: report.candidates,
-            gaps: report.gaps,
-            schedule: report.schedule,
-            test_selection: report.test_selection,
-        },
-        command_contract: {
-            defaults: contract.defaults,
-            resources: contract.resources,
-            intents: relatedIntents,
-        },
-    };
-    return hashTextSha256(stableJson(fingerprintSource));
-}
 function toParallelismReport(settings) {
     return {
         requested: settings.requested,

package/dist/cli/i18n/en.js

@@ -24,6 +24,7 @@ export const enMessages = {
     "value.missing": "missing",
     "value.passed": "passed",
     "value.failed": "failed",
+    "command.api.summary": "Print stable machine-readable API reports for agents",
     "command.adapters.summary": "Inspect host adapter compatibility without generating adapter files",
     "command.init.summary": "Copy the default mustflow agent workflow",
     "command.check.summary": "Validate mustflow files",
@@ -86,6 +87,18 @@ export const enMessages = {
     "context.help.option.cacheProfile": "Print a prompt-cache profile: stable, task, volatile, or all",
     "context.help.exit.ok": "Context was inspected and printed",
     "context.title": "mustflow context",
+    "api.help.summary": "Print stable machine-readable API reports for the current mustflow root.",
+    "api.help.action.workspaceSummary": "Print a read-only workspace briefing for coding agents",
+    "api.help.action.commandCatalog": "Print command intent availability without exposing raw command execution strings",
+    "api.help.action.verificationPlan": "Print a read-only verification plan for changed files",
+    "api.help.action.latestEvidence": "Print bounded latest run or verify evidence for agents",
+    "api.help.action.diffRisk": "Print a compact changed-file risk and verification summary",
+    "api.help.action.health": "Print a compact workspace health summary",
+    "api.help.exit.ok": "The API report was inspected and printed",
+    "api.error.missingAction": "Specify an api action: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, or health",
+    "api.error.unknownAction": "Unknown api action: {action}",
+    "api.error.actionRequiresJson": "{action} requires --json",
+    "api.error.actionRequiresChanged": "{action} currently requires --changed",
     "label.installed": "Installed",
     "label.mustflowRoot": "mustflow root",
     "label.commandContract": "Command specification",

package/dist/cli/i18n/es.js

@@ -24,6 +24,7 @@ export const esMessages = {
     "value.missing": "faltante",
     "value.passed": "superado",
     "value.failed": "fallido",
+    "command.api.summary": "Imprime informes API estables legibles por máquinas para agentes",
     "command.adapters.summary": "Inspecciona compatibilidad de adaptadores sin generar archivos",
     "command.init.summary": "Copia el flujo de trabajo de agente mustflow predeterminado",
     "command.check.summary": "Valida los archivos mustflow",
@@ -86,6 +87,18 @@ export const esMessages = {
     "context.help.option.cacheProfile": "Imprime un perfil de caché de prompt: stable, task, volatile o all",
     "context.help.exit.ok": "El contexto se inspeccionó e imprimió",
     "context.title": "contexto mustflow",
+    "api.help.summary": "Imprime informes API estables legibles por máquinas para la raíz mustflow actual.",
+    "api.help.action.workspaceSummary": "Imprime un briefing de workspace de solo lectura para agentes de código",
+    "api.help.action.commandCatalog": "Imprime disponibilidad de intents de comandos sin exponer cadenas de ejecución sin procesar",
+    "api.help.action.verificationPlan": "Imprime un verification plan de solo lectura para archivos cambiados",
+    "api.help.action.latestEvidence": "Imprime evidencia bounded del último run o verify para agentes",
+    "api.help.action.diffRisk": "Imprime un resumen compacto de riesgo y verificación para archivos cambiados",
+    "api.help.action.health": "Imprime un resumen compacto de salud del workspace",
+    "api.help.exit.ok": "El informe API se inspeccionó e imprimió",
+    "api.error.missingAction": "Especifica una acción api: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk o health",
+    "api.error.unknownAction": "Acción api desconocida: {action}",
+    "api.error.actionRequiresJson": "{action} requiere --json",
+    "api.error.actionRequiresChanged": "{action} actualmente requiere --changed",
     "label.installed": "Instalado",
     "label.mustflowRoot": "raíz mustflow",
     "label.commandContract": "Especificación de comandos",

package/dist/cli/i18n/fr.js

@@ -24,6 +24,7 @@ export const frMessages = {
     "value.missing": "manquant",
     "value.passed": "réussi",
     "value.failed": "échoué",
+    "command.api.summary": "Imprime des rapports API stables lisibles par machine pour les agents",
     "command.adapters.summary": "Inspecte la compatibilité des adaptateurs sans générer de fichiers",
     "command.init.summary": "Copie le flux de travail d'agent mustflow par défaut",
     "command.check.summary": "Valide les fichiers mustflow",
@@ -86,6 +87,18 @@ export const frMessages = {
     "context.help.option.cacheProfile": "Imprime un profil de cache de prompt : stable, task, volatile ou all",
     "context.help.exit.ok": "Le contexte a été inspecté et imprimé",
     "context.title": "contexte mustflow",
+    "api.help.summary": "Imprime des rapports API stables lisibles par machine pour la racine mustflow actuelle.",
+    "api.help.action.workspaceSummary": "Imprime un briefing de workspace en lecture seule pour les agents de code",
+    "api.help.action.commandCatalog": "Affiche la disponibilité des intents de commande sans exposer les chaînes d'exécution brutes",
+    "api.help.action.verificationPlan": "Affiche un verification plan en lecture seule pour les fichiers modifiés",
+    "api.help.action.latestEvidence": "Affiche les dernières preuves bounded de run ou verify pour les agents",
+    "api.help.action.diffRisk": "Affiche un résumé compact du risque et de la vérification des fichiers modifiés",
+    "api.help.action.health": "Affiche un résumé compact de santé du workspace",
+    "api.help.exit.ok": "Le rapport API a été inspecté et imprimé",
+    "api.error.missingAction": "Indiquez une action api : workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk ou health",
+    "api.error.unknownAction": "Action api inconnue : {action}",
+    "api.error.actionRequiresJson": "{action} exige --json",
+    "api.error.actionRequiresChanged": "{action} exige actuellement --changed",
     "label.installed": "Installé",
     "label.mustflowRoot": "racine mustflow",
     "label.commandContract": "Spécification des commandes",

package/dist/cli/i18n/hi.js

@@ -24,6 +24,7 @@ export const hiMessages = {
     "value.missing": "गुम",
     "value.passed": "पास",
     "value.failed": "फेल",
+    "command.api.summary": "एजेंटों के लिए स्थिर machine-readable API रिपोर्ट प्रिंट करें",
     "command.adapters.summary": "एडाप्टर फ़ाइलें बनाए बिना होस्ट संगतता जाँचें",
     "command.init.summary": "डिफ़ॉल्ट mustflow एजेंट वर्कफ़्लो कॉपी करें",
     "command.check.summary": "mustflow फ़ाइलों की जाँच करें",
@@ -86,6 +87,18 @@ export const hiMessages = {
     "context.help.option.cacheProfile": "prompt cache profile प्रिंट करें: stable, task, volatile, या all",
     "context.help.exit.ok": "संदर्भ जाँचा और प्रिंट किया गया",
     "context.title": "mustflow संदर्भ",
+    "api.help.summary": "वर्तमान mustflow रूट के लिए स्थिर machine-readable API रिपोर्ट प्रिंट करें।",
+    "api.help.action.workspaceSummary": "कोडिंग एजेंटों के लिए read-only workspace briefing प्रिंट करें",
+    "api.help.action.commandCatalog": "raw command execution strings दिखाए बिना command intent availability प्रिंट करें",
+    "api.help.action.verificationPlan": "बदली गई फ़ाइलों के लिए read-only verification plan प्रिंट करें",
+    "api.help.action.latestEvidence": "agents के लिए bounded latest run या verify evidence प्रिंट करें",
+    "api.help.action.diffRisk": "बदली गई files के लिए compact risk और verification summary प्रिंट करें",
+    "api.help.action.health": "workspace health की compact summary प्रिंट करें",
+    "api.help.exit.ok": "API रिपोर्ट जाँची और प्रिंट की गई",
+    "api.error.missingAction": "api action बताएँ: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, या health",
+    "api.error.unknownAction": "अज्ञात api action: {action}",
+    "api.error.actionRequiresJson": "{action} के लिए --json चाहिए",
+    "api.error.actionRequiresChanged": "{action} को अभी --changed चाहिए",
     "label.installed": "इंस्टॉल किया गया",
     "label.mustflowRoot": "mustflow रूट",
     "label.commandContract": "कमांड विनिर्देश",

package/dist/cli/i18n/ko.js

@@ -24,6 +24,7 @@ export const koMessages = {
     "value.missing": "없음",
     "value.passed": "통과",
     "value.failed": "실패",
+    "command.api.summary": "에이전트용 안정적 JSON API 보고서를 출력합니다",
     "command.adapters.summary": "어댑터 파일을 만들지 않고 호스트 호환성을 확인합니다",
     "command.init.summary": "기본 mustflow 에이전트 워크플로우를 복사합니다",
     "command.check.summary": "mustflow 파일을 검사합니다",
@@ -86,6 +87,18 @@ export const koMessages = {
     "context.help.option.cacheProfile": "프롬프트 캐시 프로필을 출력합니다: stable, task, volatile, all",
     "context.help.exit.ok": "맥락을 확인하고 출력했습니다",
     "context.title": "mustflow 맥락",
+    "api.help.summary": "현재 mustflow 루트의 안정적 JSON API 보고서를 출력합니다.",
+    "api.help.action.workspaceSummary": "코딩 에이전트용 읽기 전용 workspace briefing을 출력합니다",
+    "api.help.action.commandCatalog": "원본 실행 문자열을 노출하지 않고 command intent 실행 가능성을 출력합니다",
+    "api.help.action.verificationPlan": "변경 파일에 대한 읽기 전용 verification plan을 출력합니다",
+    "api.help.action.latestEvidence": "에이전트용 bounded 최신 run 또는 verify evidence를 출력합니다",
+    "api.help.action.diffRisk": "변경 파일 risk와 verification 요약을 작게 출력합니다",
+    "api.help.action.health": "workspace health 요약을 작게 출력합니다",
+    "api.help.exit.ok": "API 보고서를 확인하고 출력했습니다",
+    "api.error.missingAction": "api 작업을 지정하세요: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk 또는 health",
+    "api.error.unknownAction": "알 수 없는 api 작업: {action}",
+    "api.error.actionRequiresJson": "{action}에는 --json이 필요합니다",
+    "api.error.actionRequiresChanged": "{action}은 현재 --changed가 필요합니다",
     "label.installed": "설치됨",
     "label.mustflowRoot": "mustflow 루트",
     "label.commandContract": "명령 계약",

package/dist/cli/i18n/zh.js

@@ -24,6 +24,7 @@ export const zhMessages = {
     "value.missing": "缺失",
     "value.passed": "通过",
     "value.failed": "失败",
+    "command.api.summary": "为代理输出稳定的机器可读 API 报告",
     "command.adapters.summary": "不生成适配器文件，检查宿主兼容性",
     "command.init.summary": "复制默认的 mustflow 代理工作流",
     "command.check.summary": "验证 mustflow 文件",
@@ -86,6 +87,18 @@ export const zhMessages = {
     "context.help.option.cacheProfile": "输出提示缓存配置文件：stable、task、volatile 或 all",
     "context.help.exit.ok": "已检查并输出上下文",
     "context.title": "mustflow 上下文",
+    "api.help.summary": "为当前 mustflow 根目录输出稳定的机器可读 API 报告。",
+    "api.help.action.workspaceSummary": "为代码代理输出只读 workspace 简报",
+    "api.help.action.commandCatalog": "输出命令 intent 可用性，但不暴露原始执行字符串",
+    "api.help.action.verificationPlan": "为已变更文件输出只读 verification plan",
+    "api.help.action.latestEvidence": "为代理输出 bounded 最新 run 或 verify evidence",
+    "api.help.action.diffRisk": "为已变更文件输出紧凑 risk 和 verification 摘要",
+    "api.help.action.health": "输出紧凑 workspace health 摘要",
+    "api.help.exit.ok": "已检查并输出 API 报告",
+    "api.error.missingAction": "请指定 api 操作：workspace-summary、command-catalog、verification-plan、latest-evidence、diff-risk 或 health",
+    "api.error.unknownAction": "未知 api 操作：{action}",
+    "api.error.actionRequiresJson": "{action} 需要 --json",
+    "api.error.actionRequiresChanged": "{action} 当前需要 --changed",
     "label.installed": "已安装",
     "label.mustflowRoot": "mustflow 根目录",
     "label.commandContract": "命令规范",

package/dist/cli/index.js

@@ -23,6 +23,7 @@ function getTopLevelHelp(lang) {
         ],
         examples: [
             'mf --lang ko help',
+            'mf api workspace-summary --json',
             'mf adapters status --json',
             'mf init --dry-run',
             'mf doctor --json',

package/dist/cli/lib/command-registry.js

@@ -1,4 +1,10 @@
 export const COMMAND_DEFINITIONS = [
+    {
+        id: 'api',
+        usage: 'mf api',
+        summaryKey: 'command.api.summary',
+        loadRunner: async () => (await import('../commands/api.js')).runApi,
+    },
     {
         id: 'adapters',
         usage: 'mf adapters',

package/dist/core/public-json-contracts.js

@@ -23,6 +23,54 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         documented: true,
         installedCommand: ['mf', 'context', '--json'],
     },
+    {
+        id: 'workspace-summary',
+        schemaFile: 'workspace-summary.schema.json',
+        producer: 'mf api workspace-summary --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'workspace-summary', '--json'],
+    },
+    {
+        id: 'command-catalog',
+        schemaFile: 'command-catalog.schema.json',
+        producer: 'mf api command-catalog --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'command-catalog', '--json'],
+    },
+    {
+        id: 'verification-plan',
+        schemaFile: 'verification-plan.schema.json',
+        producer: 'mf api verification-plan --changed --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'verification-plan', '--changed', '--json'],
+    },
+    {
+        id: 'latest-evidence',
+        schemaFile: 'latest-evidence.schema.json',
+        producer: 'mf api latest-evidence --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'latest-evidence', '--json'],
+    },
+    {
+        id: 'diff-risk',
+        schemaFile: 'diff-risk.schema.json',
+        producer: 'mf api diff-risk --changed --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'diff-risk', '--changed', '--json'],
+    },
+    {
+        id: 'health',
+        schemaFile: 'health.schema.json',
+        producer: 'mf api health --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'health', '--json'],
+    },
     {
         id: 'run-receipt',
         schemaFile: 'run-receipt.schema.json',

package/dist/core/verification-plan-id.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+function hashTextSha256(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableJson(entry)).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort((left, right) => left.localeCompare(right))
+            .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
+            .join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+function getCandidateIntentNames(report) {
+    return [...new Set(report.candidates.map((candidate) => candidate.intent).filter((intent) => Boolean(intent)))]
+        .sort((left, right) => left.localeCompare(right));
+}
+export function createVerificationPlanId(report, contract) {
+    const relatedIntents = Object.fromEntries(getCandidateIntentNames(report).map((intent) => [intent, contract.intents[intent] ?? null]));
+    const fingerprintSource = {
+        schema_version: '1',
+        algorithm: 'mustflow.verify_plan_id.v1',
+        report: {
+            source: report.source,
+            files: report.files,
+            classification_summary: report.classification_summary,
+            requirements: report.requirements,
+            candidates: report.candidates,
+            gaps: report.gaps,
+            schedule: report.schedule,
+            test_selection: report.test_selection,
+        },
+        command_contract: {
+            defaults: contract.defaults,
+            resources: contract.resources,
+            intents: relatedIntents,
+        },
+    };
+    return hashTextSha256(stableJson(fingerprintSource));
+}

package/package.json

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

package/schemas/README.md

@@ -8,6 +8,12 @@ Current schemas:
 - `doctor-report.schema.json`: output of `mf doctor --json`
 - `adapter-compatibility-report.schema.json`: output of `mf adapters status --json`
 - `context-report.schema.json`: output of `mf context --json`
+- `workspace-summary.schema.json`: output of `mf api workspace-summary --json`
+- `command-catalog.schema.json`: output of `mf api command-catalog --json`
+- `verification-plan.schema.json`: output of `mf api verification-plan --changed --json`
+- `latest-evidence.schema.json`: output of `mf api latest-evidence --json`
+- `diff-risk.schema.json`: output of `mf api diff-risk --changed --json`
+- `health.schema.json`: output of `mf api health --json`
 - `run-receipt.schema.json`: output of `mf run <intent> --json` and `.mustflow/state/runs/latest.json`,
   including bounded declared-write drift metadata, a safe latest-run performance summary, and optional
   structured phase timings and selection summaries

package/schemas/command-catalog.schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/command-catalog.schema.json",
+  "title": "mustflow command catalog API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "command_contract",
+    "execution_policy",
+    "intents",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api command-catalog" },
+    "mustflow_root": { "type": "string" },
+    "command_contract": { "$ref": "#/$defs/commandContract" },
+    "execution_policy": { "$ref": "#/$defs/executionPolicy" },
+    "intents": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/intent" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "commandContract": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "exists", "parse_error", "total_intents", "runnable_count", "blocked_count"],
+      "properties": {
+        "path": { "const": ".mustflow/config/commands.toml" },
+        "exists": { "type": "boolean" },
+        "parse_error": { "type": ["string", "null"] },
+        "total_intents": { "type": "integer", "minimum": 0 },
+        "runnable_count": { "type": "integer", "minimum": 0 },
+        "blocked_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "executionPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "command_authority",
+        "run_entrypoint",
+        "preview_entrypoint",
+        "direct_commands_allowed",
+        "requires_configured_oneshot_agent_allowed"
+      ],
+      "properties": {
+        "command_authority": { "const": ".mustflow/config/commands.toml" },
+        "run_entrypoint": { "const": "mf run <intent>" },
+        "preview_entrypoint": { "const": "mf run <intent> --dry-run --json" },
+        "direct_commands_allowed": { "const": false },
+        "requires_configured_oneshot_agent_allowed": { "const": true }
+      }
+    },
+    "intent": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "description",
+        "kind",
+        "status",
+        "lifecycle",
+        "run_policy",
+        "runnable",
+        "reason_code",
+        "detail",
+        "run_command",
+        "preview_command",
+        "mode",
+        "cwd",
+        "timeout_seconds",
+        "kill_after_seconds",
+        "max_output_bytes",
+        "success_exit_codes",
+        "required_after",
+        "writes",
+        "effect_count",
+        "network",
+        "destructive",
+        "accepts_test_targets",
+        "env_policy",
+        "env_allowlist",
+        "precondition_count",
+        "active_lock_conflict_count",
+        "stale_active_lock_count",
+        "agent_action",
+        "manual_start_hint",
+        "health_check_url",
+        "stop_instruction",
+        "related_oneshot_checks"
+      ],
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": ["string", "null"] },
+        "kind": { "type": ["string", "null"] },
+        "status": { "type": ["string", "null"] },
+        "lifecycle": { "type": ["string", "null"] },
+        "run_policy": { "type": ["string", "null"] },
+        "runnable": { "type": "boolean" },
+        "reason_code": { "type": ["string", "null"] },
+        "detail": { "type": ["string", "null"] },
+        "run_command": { "type": ["string", "null"] },
+        "preview_command": { "type": ["string", "null"] },
+        "mode": { "enum": ["argv", "shell", null] },
+        "cwd": { "type": ["string", "null"] },
+        "timeout_seconds": { "type": ["integer", "null"], "minimum": 1 },
+        "kill_after_seconds": { "type": ["integer", "null"], "minimum": 1 },
+        "max_output_bytes": { "type": ["integer", "null"], "minimum": 1 },
+        "success_exit_codes": {
+          "anyOf": [
+            { "type": "null" },
+            {
+              "type": "array",
+              "items": { "type": "integer", "minimum": 0 }
+            }
+          ]
+        },
+        "required_after": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "writes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "effect_count": { "type": "integer", "minimum": 0 },
+        "network": { "type": ["boolean", "null"] },
+        "destructive": { "type": ["boolean", "null"] },
+        "accepts_test_targets": { "type": "boolean" },
+        "env_policy": { "type": ["string", "null"] },
+        "env_allowlist": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "precondition_count": { "type": "integer", "minimum": 0 },
+        "active_lock_conflict_count": { "type": "integer", "minimum": 0 },
+        "stale_active_lock_count": { "type": "integer", "minimum": 0 },
+        "agent_action": { "type": ["string", "null"] },
+        "manual_start_hint": { "type": ["string", "null"] },
+        "health_check_url": { "type": ["string", "null"] },
+        "stop_instruction": { "type": ["string", "null"] },
+        "related_oneshot_checks": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/schemas/diff-risk.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/diff-risk.schema.json",
+  "title": "mustflow diff risk API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "source",
+    "status",
+    "risk_level",
+    "changed_file_count",
+    "changed_files",
+    "public_surface_count",
+    "validation_reasons",
+    "update_policies",
+    "drift_checks",
+    "required_verification",
+    "gap_count",
+    "gaps",
+    "recommended_commands",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api diff-risk" },
+    "mustflow_root": { "type": "string" },
+    "source": { "$ref": "#/$defs/source" },
+    "status": { "enum": ["available", "unavailable"] },
+    "risk_level": { "enum": ["none", "low", "medium", "high", "unknown"] },
+    "changed_file_count": { "type": "integer", "minimum": 0 },
+    "changed_files": { "$ref": "#/$defs/stringArray" },
+    "public_surface_count": { "type": "integer", "minimum": 0 },
+    "validation_reasons": { "$ref": "#/$defs/stringArray" },
+    "update_policies": { "$ref": "#/$defs/stringArray" },
+    "drift_checks": { "$ref": "#/$defs/stringArray" },
+    "required_verification": { "$ref": "#/$defs/stringArray" },
+    "gap_count": { "type": "integer", "minimum": 0 },
+    "gaps": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/gap" }
+    },
+    "recommended_commands": { "$ref": "#/$defs/stringArray" },
+    "issues": { "$ref": "#/$defs/stringArray" }
+  },
+  "$defs": {
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "command"],
+      "properties": {
+        "kind": { "const": "changed" },
+        "command": { "const": "mf verify --changed --plan-only --json" }
+      }
+    },
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "gap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["reason", "files", "surfaces", "detail"],
+      "properties": {
+        "reason": { "type": "string" },
+        "files": { "$ref": "#/$defs/stringArray" },
+        "surfaces": { "$ref": "#/$defs/stringArray" },
+        "detail": { "type": "string" }
+      }
+    }
+  }
+}