mustflow 2.22.46 → 2.22.49

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

@@ -23,6 +23,62 @@ 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: 'locks',
+        schemaFile: 'locks.schema.json',
+        producer: 'mf api locks --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'locks', '--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.49",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/schemas/README.md

@@ -8,6 +8,13 @@ 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`
+- `locks.schema.json`: output of `mf api locks --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,149 @@
+{
+  "$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" },
+    "residual_corrections": { "$ref": "#/$defs/residualCorrections" },
+    "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" }
+      }
+    },
+    "residualCorrections": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "mode",
+        "grants_command_authority",
+        "applies_to_current_plan",
+        "selected_intent_additions",
+        "suggested_intent_additions",
+        "recommended_commands",
+        "signals",
+        "policy",
+        "issues"
+      ],
+      "properties": {
+        "status": { "enum": ["not_enough_evidence", "available", "unavailable"] },
+        "mode": { "const": "read_only" },
+        "grants_command_authority": { "const": false },
+        "applies_to_current_plan": { "type": "boolean" },
+        "selected_intent_additions": { "$ref": "#/$defs/stringArray" },
+        "suggested_intent_additions": { "$ref": "#/$defs/stringArray" },
+        "recommended_commands": { "$ref": "#/$defs/stringArray" },
+        "signals": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/residualSignal" }
+        },
+        "policy": { "$ref": "#/$defs/residualPolicy" },
+        "issues": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "residualPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "single_observation_changes_plan",
+        "minimum_repeated_samples_for_plan_change",
+        "automatic_intent_additions_enabled"
+      ],
+      "properties": {
+        "single_observation_changes_plan": { "const": false },
+        "minimum_repeated_samples_for_plan_change": { "const": 2 },
+        "automatic_intent_additions_enabled": { "const": false }
+      }
+    },
+    "residualSignal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "confidence",
+        "evidence_count",
+        "source",
+        "verification_plan_id",
+        "affected_reasons",
+        "affected_intents",
+        "detail",
+        "recommendation"
+      ],
+      "properties": {
+        "kind": { "enum": ["latest_unresolved_plan", "repeated_failure", "remaining_risk"] },
+        "confidence": { "enum": ["low", "medium", "high"] },
+        "evidence_count": { "type": "integer", "minimum": 1 },
+        "source": { "const": "latest-evidence" },
+        "verification_plan_id": {
+          "type": ["string", "null"],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "affected_reasons": { "$ref": "#/$defs/stringArray" },
+        "affected_intents": { "$ref": "#/$defs/stringArray" },
+        "detail": { "type": "string" },
+        "recommendation": { "enum": ["provide_new_evidence", "review_remaining_risk"] }
+      }
+    }
+  }
+}

package/schemas/health.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/health.schema.json",
+  "title": "mustflow health API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "status",
+    "installed",
+    "check_ok",
+    "command_contract_ok",
+    "runnable_count",
+    "git_status",
+    "changed_file_count",
+    "latest_run_exists",
+    "blockers",
+    "warnings",
+    "recommended_next_commands"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api health" },
+    "mustflow_root": { "type": "string" },
+    "status": { "enum": ["ok", "degraded", "blocked"] },
+    "installed": { "type": "boolean" },
+    "check_ok": { "type": "boolean" },
+    "command_contract_ok": { "type": "boolean" },
+    "runnable_count": { "type": "integer", "minimum": 0 },
+    "git_status": { "enum": ["available", "unavailable"] },
+    "changed_file_count": { "type": ["integer", "null"], "minimum": 0 },
+    "latest_run_exists": { "type": "boolean" },
+    "blockers": { "$ref": "#/$defs/stringArray" },
+    "warnings": { "$ref": "#/$defs/stringArray" },
+    "recommended_next_commands": { "$ref": "#/$defs/stringArray" }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/schemas/latest-evidence.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/latest-evidence.schema.json",
+  "title": "mustflow latest evidence API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "latest",
+    "manifest",
+    "policy",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api latest-evidence" },
+    "mustflow_root": { "type": "string" },
+    "latest": { "$ref": "#/$defs/latest" },
+    "manifest": { "$ref": "#/$defs/manifest" },
+    "policy": { "$ref": "#/$defs/policy" },
+    "issues": { "$ref": "#/$defs/stringArray" }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "latest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "exists",
+        "path",
+        "kind",
+        "status",
+        "intent",
+        "reason",
+        "verification_plan_id",
+        "completion_verdict_status",
+        "manifest_path",
+        "receipt_path",
+        "run_dir",
+        "exit_code",
+        "timed_out",
+        "duration_ms",
+        "summary"
+      ],
+      "properties": {
+        "exists": { "type": "boolean" },
+        "path": { "const": ".mustflow/state/runs/latest.json" },
+        "kind": { "enum": ["run_receipt", "verify_run_summary", "unknown", null] },
+        "status": { "type": ["string", "null"] },
+        "intent": { "type": ["string", "null"] },
+        "reason": { "type": ["string", "null"] },
+        "verification_plan_id": { "type": ["string", "null"] },
+        "completion_verdict_status": { "type": ["string", "null"] },
+        "manifest_path": { "type": ["string", "null"] },
+        "receipt_path": { "type": ["string", "null"] },
+        "run_dir": { "type": ["string", "null"] },
+        "exit_code": { "type": ["integer", "null"] },
+        "timed_out": { "type": ["boolean", "null"] },
+        "duration_ms": { "type": ["integer", "null"], "minimum": 0 },
+        "summary": {
+          "anyOf": [
+            { "type": "null" },
+            { "type": "object" }
+          ]
+        }
+      }
+    },
+    "manifest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "path", "receipt_count", "error"],
+      "properties": {
+        "status": { "enum": ["available", "missing", "unavailable", "not_applicable"] },
+        "path": { "type": ["string", "null"] },
+        "receipt_count": { "type": ["integer", "null"], "minimum": 0 },
+        "error": { "type": ["string", "null"] }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["raw_output_included", "hidden_reasoning_included", "max_bytes"],
+      "properties": {
+        "raw_output_included": { "const": false },
+        "hidden_reasoning_included": { "const": false },
+        "max_bytes": { "type": "integer", "minimum": 1 }
+      }
+    }
+  }
+}