mustflow 1.18.16 → 1.31.0

package/dist/core/verification-decision-graph.js

@@ -0,0 +1,290 @@
+import { isRecord, readString, readStringArray, } from './config-loading.js';
+export const VERIFICATION_DECISION_GRAPH_SCHEMA_VERSION = '1';
+function stableIdPart(value) {
+    return value.trim().replace(/[^A-Za-z0-9_.-]+/gu, '_') || 'none';
+}
+function readBoolean(table, key) {
+    const value = table[key];
+    return typeof value === 'boolean' ? value : null;
+}
+function readTimeoutSeconds(table) {
+    const value = table.timeout_seconds;
+    return Number.isInteger(value) ? Number(value) : null;
+}
+function readCommandEffects(rawIntent) {
+    const effects = rawIntent.effects;
+    if (!Array.isArray(effects)) {
+        return [];
+    }
+    return effects.filter(isRecord).map((effect) => ({
+        type: readString(effect, 'type') ?? null,
+        mode: readString(effect, 'mode') ?? null,
+        path: readString(effect, 'path') ?? null,
+        paths: readStringArray(effect, 'paths') ?? [],
+        lock: readString(effect, 'lock') ?? null,
+        concurrency: readString(effect, 'concurrency') ?? null,
+    }));
+}
+function readNonNegativeNumber(table, key) {
+    const value = table[key];
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function readNonNegativeInteger(table, key) {
+    const value = table[key];
+    return Number.isInteger(value) && Number(value) >= 0 ? Number(value) : null;
+}
+function readCoverageHints(rawIntent) {
+    const covers = rawIntent.covers;
+    if (!isRecord(covers)) {
+        return null;
+    }
+    return {
+        reasons: readStringArray(covers, 'reasons') ?? [],
+        surfaces: readStringArray(covers, 'surfaces') ?? [],
+        paths: readStringArray(covers, 'paths') ?? [],
+        contracts: readStringArray(covers, 'contracts') ?? [],
+    };
+}
+function readSelectionHints(rawIntent) {
+    const selection = rawIntent.selection;
+    if (!isRecord(selection)) {
+        return null;
+    }
+    return {
+        coverage_level: readString(selection, 'coverage_level') ?? null,
+        coverage_confidence: readString(selection, 'coverage_confidence') ?? null,
+        accepts_changed_files: readString(selection, 'accepts_changed_files') ?? null,
+        fallback_intents: readStringArray(selection, 'fallback_intents') ?? [],
+        escalate_to: readStringArray(selection, 'escalate_to') ?? [],
+    };
+}
+function readCostHints(rawIntent) {
+    const cost = rawIntent.cost;
+    if (!isRecord(cost)) {
+        return null;
+    }
+    return {
+        expected_seconds: readNonNegativeInteger(cost, 'expected_seconds'),
+        cold_start_seconds: readNonNegativeInteger(cost, 'cold_start_seconds'),
+        timeout_ratio_expectation: readNonNegativeNumber(cost, 'timeout_ratio_expectation'),
+        cost_tier: readString(cost, 'cost_tier') ?? null,
+    };
+}
+function readRelationHints(rawIntent) {
+    const relations = rawIntent.relations;
+    if (!isRecord(relations)) {
+        return null;
+    }
+    return {
+        subsumes: readStringArray(relations, 'subsumes') ?? [],
+        subsumed_by: readStringArray(relations, 'subsumed_by') ?? [],
+        requires_with: readStringArray(relations, 'requires_with') ?? [],
+        escalate_to: readStringArray(relations, 'escalate_to') ?? [],
+    };
+}
+function readCommandMetadata(commandContract, intent) {
+    if (!intent) {
+        return null;
+    }
+    const rawIntent = commandContract.intents[intent];
+    if (!isRecord(rawIntent)) {
+        return null;
+    }
+    return {
+        status: readString(rawIntent, 'status') ?? null,
+        lifecycle: readString(rawIntent, 'lifecycle') ?? null,
+        run_policy: readString(rawIntent, 'run_policy') ?? null,
+        stdin: readString(rawIntent, 'stdin') ?? null,
+        timeout_seconds: readTimeoutSeconds(rawIntent),
+        writes: readStringArray(rawIntent, 'writes') ?? [],
+        effects: readCommandEffects(rawIntent),
+        required_after: readStringArray(rawIntent, 'required_after') ?? [],
+        network: readBoolean(rawIntent, 'network'),
+        destructive: readBoolean(rawIntent, 'destructive'),
+        covers: readCoverageHints(rawIntent),
+        selection: readSelectionHints(rawIntent),
+        cost: readCostHints(rawIntent),
+        relations: readRelationHints(rawIntent),
+    };
+}
+function candidateDecisionStatus(commandContract, candidate) {
+    if (candidate.status === 'runnable') {
+        return 'runnable';
+    }
+    if (!candidate.intent || candidate.skipReason === 'no_matching_intents') {
+        return 'unknown';
+    }
+    const rawIntent = commandContract.intents[candidate.intent];
+    if (!isRecord(rawIntent)) {
+        return 'blocked';
+    }
+    const status = readString(rawIntent, 'status') ?? 'unknown';
+    if (status === 'manual_only') {
+        return 'manual_only';
+    }
+    if (status === 'unknown') {
+        return 'unknown';
+    }
+    return candidate.skipReason ? 'blocked' : 'skipped';
+}
+function addNode(nodes, node) {
+    if (!nodes.has(node.id)) {
+        nodes.set(node.id, node);
+    }
+}
+function addEdge(edges, edge) {
+    if (!edges.some((item) => item.from === edge.from && item.to === edge.to && item.kind === edge.kind)) {
+        edges.push(edge);
+    }
+}
+function summarize(nodes, edgeCount) {
+    return {
+        nodeCount: nodes.length,
+        edgeCount,
+        runnable: nodes.filter((node) => node.status === 'runnable').length,
+        skipped: nodes.filter((node) => node.status === 'skipped').length,
+        blocked: nodes.filter((node) => node.status === 'blocked').length,
+        manual_only: nodes.filter((node) => node.status === 'manual_only').length,
+        unknown: nodes.filter((node) => node.status === 'unknown').length,
+        selected: nodes.filter((node) => node.kind === 'command_candidate' && node.data.selectionState === 'selected').length,
+        not_selected: nodes.filter((node) => node.kind === 'command_candidate' && node.data.selectionState === 'not_selected')
+            .length,
+        gapCount: nodes.filter((node) => node.kind === 'gap').length,
+    };
+}
+export function createVerificationDecisionGraph(commandContract, requirements, candidates, gaps, schedule) {
+    const nodes = new Map();
+    const edges = [];
+    const candidateNodeByReasonAndIntent = new Map();
+    for (const requirement of requirements) {
+        const reasonNodeId = `classification_reason:${stableIdPart(requirement.reason)}`;
+        addNode(nodes, {
+            id: reasonNodeId,
+            kind: 'classification_reason',
+            label: requirement.reason,
+            status: 'not_applicable',
+            reason: requirement.reason,
+            intent: null,
+            data: {
+                files: requirement.files,
+                surfaces: requirement.surfaces,
+                affectedContracts: requirement.affectedContracts,
+                driftChecks: requirement.driftChecks,
+                updatePolicies: requirement.updatePolicies,
+                source: requirement.source,
+            },
+        });
+        for (const surface of requirement.surfaces) {
+            const surfaceNodeId = `changed_surface:${stableIdPart(requirement.reason)}:${stableIdPart(surface)}`;
+            addNode(nodes, {
+                id: surfaceNodeId,
+                kind: 'changed_surface',
+                label: surface,
+                status: 'not_applicable',
+                reason: requirement.reason,
+                intent: null,
+                data: {
+                    files: requirement.files,
+                },
+            });
+            addEdge(edges, { from: surfaceNodeId, to: reasonNodeId, kind: 'supports' });
+        }
+    }
+    for (const [index, candidate] of candidates.entries()) {
+        const reasonNodeId = `classification_reason:${stableIdPart(candidate.reason)}`;
+        const intentPart = stableIdPart(candidate.intent ?? 'missing_intent');
+        const candidateNodeId = `command_candidate:${stableIdPart(candidate.reason)}:${intentPart}:${index + 1}`;
+        const eligibilityNodeId = `eligibility:${stableIdPart(candidate.reason)}:${intentPart}:${index + 1}`;
+        const status = candidateDecisionStatus(commandContract, candidate);
+        const command = readCommandMetadata(commandContract, candidate.intent);
+        const key = `${candidate.reason}\0${candidate.intent ?? ''}`;
+        candidateNodeByReasonAndIntent.set(key, [...(candidateNodeByReasonAndIntent.get(key) ?? []), candidateNodeId]);
+        addNode(nodes, {
+            id: candidateNodeId,
+            kind: 'command_candidate',
+            label: candidate.intent ?? 'missing intent',
+            status,
+            reason: candidate.reason,
+            intent: candidate.intent,
+            data: {
+                candidateStatus: candidate.status,
+                skipReason: candidate.skipReason,
+                detail: candidate.detail,
+                candidateState: candidate.candidateState ?? null,
+                eligibilityState: candidate.eligibilityState ?? null,
+                selectionState: candidate.selectionState ?? null,
+                command,
+            },
+        });
+        addNode(nodes, {
+            id: eligibilityNodeId,
+            kind: 'eligibility',
+            label: candidate.skipReason ?? 'ok',
+            status,
+            reason: candidate.reason,
+            intent: candidate.intent,
+            data: {
+                code: candidate.skipReason ?? 'ok',
+                detail: candidate.detail,
+            },
+        });
+        addEdge(edges, { from: reasonNodeId, to: candidateNodeId, kind: 'requires' });
+        addEdge(edges, { from: candidateNodeId, to: eligibilityNodeId, kind: 'evaluates' });
+    }
+    for (const entry of schedule.entries) {
+        for (const [index, effect] of entry.effects.entries()) {
+            const effectNodeId = `effect:${stableIdPart(entry.intent)}:${index + 1}`;
+            addNode(nodes, {
+                id: effectNodeId,
+                kind: 'effect',
+                label: effect.lock,
+                status: 'runnable',
+                reason: null,
+                intent: entry.intent,
+                data: {
+                    source: effect.source,
+                    access: effect.access,
+                    mode: effect.mode,
+                    path: effect.path,
+                    lock: effect.lock,
+                    concurrency: effect.concurrency,
+                },
+            });
+            for (const [key, candidateNodeIds] of candidateNodeByReasonAndIntent.entries()) {
+                if (!key.endsWith(`\0${entry.intent}`)) {
+                    continue;
+                }
+                for (const candidateNodeId of candidateNodeIds) {
+                    addEdge(edges, { from: candidateNodeId, to: effectNodeId, kind: 'has_effect' });
+                }
+            }
+        }
+    }
+    for (const gap of gaps) {
+        const reasonNodeId = `classification_reason:${stableIdPart(gap.reason)}`;
+        const gapNodeId = `gap:${stableIdPart(gap.reason)}`;
+        addNode(nodes, {
+            id: gapNodeId,
+            kind: 'gap',
+            label: gap.reason,
+            status: 'unknown',
+            reason: gap.reason,
+            intent: null,
+            data: {
+                files: gap.files,
+                surfaces: gap.surfaces,
+                detail: gap.detail,
+            },
+        });
+        addEdge(edges, { from: reasonNodeId, to: gapNodeId, kind: 'has_gap' });
+    }
+    const sortedNodes = [...nodes.values()].sort((left, right) => left.id.localeCompare(right.id));
+    const sortedEdges = [...edges].sort((left, right) => left.from.localeCompare(right.from) || left.to.localeCompare(right.to) || left.kind.localeCompare(right.kind));
+    return {
+        schema_version: VERIFICATION_DECISION_GRAPH_SCHEMA_VERSION,
+        root: 'verification_decision',
+        summary: summarize(sortedNodes, sortedEdges.length),
+        nodes: sortedNodes,
+        edges: sortedEdges,
+    };
+}

package/dist/core/verification-scheduler.js

@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { commandEffectsConflict, normalizeCommandEffects, } from './command-effects.js';
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
@@ -13,6 +15,79 @@ function toScheduleEffect(effect) {
         concurrency: effect.concurrency,
     };
 }
+function isObject(value) {
+    return !!value && typeof value === 'object';
+}
+function readJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function getUndeclaredWriteIntent(value) {
+    if (!isObject(value) || typeof value.intent !== 'string') {
+        return null;
+    }
+    const writeDrift = value.write_drift;
+    if (!isObject(writeDrift) || writeDrift.has_undeclared_changes !== true) {
+        return null;
+    }
+    return value.intent;
+}
+function resolveStateRelativePath(projectRoot, relativePath) {
+    if (typeof relativePath !== 'string' || relativePath.length === 0 || path.isAbsolute(relativePath)) {
+        return null;
+    }
+    const normalized = relativePath.replaceAll('\\', '/');
+    if (!normalized.startsWith('.mustflow/state/runs/')) {
+        return null;
+    }
+    const resolved = path.resolve(projectRoot, normalized);
+    const relative = path.relative(projectRoot, resolved);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return null;
+    }
+    return resolved;
+}
+function readVerifyManifestUndeclaredWriteIntents(projectRoot, latest) {
+    const manifestPath = resolveStateRelativePath(projectRoot, latest.manifest_path);
+    if (!manifestPath) {
+        return new Set();
+    }
+    const manifest = readJsonFile(manifestPath);
+    if (!isObject(manifest) || manifest.command !== 'verify' || !Array.isArray(manifest.receipts)) {
+        return new Set();
+    }
+    const intents = new Set();
+    for (const entry of manifest.receipts) {
+        if (!isObject(entry)) {
+            continue;
+        }
+        const receiptPath = resolveStateRelativePath(projectRoot, entry.receipt_path);
+        if (!receiptPath) {
+            continue;
+        }
+        const intent = getUndeclaredWriteIntent(readJsonFile(receiptPath));
+        if (intent) {
+            intents.add(intent);
+        }
+    }
+    return intents;
+}
+function readLatestUndeclaredWriteIntents(projectRoot) {
+    const latestPath = path.join(projectRoot, '.mustflow', 'state', 'runs', 'latest.json');
+    const parsed = readJsonFile(latestPath);
+    const directIntent = getUndeclaredWriteIntent(parsed);
+    if (directIntent) {
+        return new Set([directIntent]);
+    }
+    if (!isObject(parsed) || parsed.command !== 'verify') {
+        return new Set();
+    }
+    return readVerifyManifestUndeclaredWriteIntents(projectRoot, parsed);
+}
 function entriesConflict(left, right) {
     const conflicts = [];
     for (const leftEffect of left.effects) {
@@ -33,7 +108,8 @@ function entriesConflict(left, right) {
 function addEntryToBatches(batches, batchEntries, entry) {
     for (let batchIndex = 0; batchIndex < batchEntries.length; batchIndex += 1) {
         const existingEntries = batchEntries[batchIndex] ?? [];
-        const hasConflict = existingEntries.some((existing) => entriesConflict(entry, existing).length > 0);
+        const hasConflict = !entry.parallelEligible ||
+            existingEntries.some((existing) => !existing.parallelEligible || entriesConflict(entry, existing).length > 0);
         if (hasConflict) {
             continue;
         }
@@ -55,14 +131,24 @@ function addEntryToBatches(batches, batchEntries, entry) {
     });
 }
 export function createVerificationSchedule(projectRoot, commandContract, candidates) {
+    const latestUndeclaredWriteIntents = readLatestUndeclaredWriteIntents(projectRoot);
     const runnableIntents = uniqueSorted(candidates
         .filter((candidate) => candidate.status === 'runnable' && candidate.intent.length > 0)
         .map((candidate) => candidate.intent));
     const baseEntries = runnableIntents.map((intent) => {
         const effects = normalizeCommandEffects(projectRoot, commandContract, intent).map(toScheduleEffect);
+        const hasExplicitEffects = effects.length > 0 && effects.every((effect) => effect.source === 'effects');
+        const hasUndeclaredWriteDrift = latestUndeclaredWriteIntents.has(intent);
+        const parallelEligible = hasExplicitEffects && !hasUndeclaredWriteDrift;
         return {
             intent,
             status: 'runnable',
+            parallelEligible,
+            parallelReason: hasUndeclaredWriteDrift
+                ? 'undeclared_write_drift'
+                : hasExplicitEffects
+                    ? 'explicit_effects'
+                    : 'missing_explicit_effects',
             effects,
             locks: uniqueSorted(effects.map((effect) => effect.lock)),
             conflicts: [],
@@ -82,11 +168,19 @@ export function createVerificationSchedule(projectRoot, commandContract, candida
     }
     return {
         runner: 'serial_mf_run_receipts',
+        failurePolicy: {
+            mode: 'batch_boundary',
+            startedBatch: 'wait_for_completion',
+            nextBatch: 'stop_on_failure',
+        },
         batches,
         entries,
         notes: [
             'Batches explain resource compatibility for planning only.',
-            'mf run still writes the latest receipt to a single path, so execute copied commands serially.',
+            'Only entries backed by explicit effects are marked parallel eligible; writes fallback remains serial-only.',
+            ...uniqueSorted(latestUndeclaredWriteIntents).map((intent) => `Latest receipt for ${intent} reported undeclared writes; it is not parallel eligible.`),
+            'If a future parallel batch has already started, let it finish and stop before the next batch on failure.',
+            'mf verify still executes copied commands serially and writes the latest run summary after the batch completes.',
         ],
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "1.18.16",
+  "version": "1.31.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",
@@ -30,6 +30,8 @@
     "test": "bun run test:full",
     "test:fast": "bun run build && node scripts/run-cli-tests.mjs fast",
     "test:related": "bun run build && node scripts/run-cli-tests.mjs related",
+    "test:related:cached": "node scripts/run-cli-tests.mjs related-cached",
+    "test:related:profile": "bun run build && node scripts/run-cli-tests.mjs related-profile",
     "test:cli": "bun run build && node scripts/run-cli-tests.mjs cli",
     "test:coverage": "bun run build && node scripts/run-cli-tests.mjs coverage",
     "test:audit": "node scripts/audit-tests.mjs --json",

package/schemas/README.md

@@ -6,27 +6,38 @@ mustflow files and command output.
 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`
-- `run-receipt.schema.json`: output of `mf run <intent> --json` and `.mustflow/state/runs/latest.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
 - `commands.schema.json`: parsed `.mustflow/config/commands.toml`
 - `contract-lint-report.schema.json`: output of `mf contract-lint --json`
+- `dashboard-export.schema.json`: bounded static export written by `mf dashboard --export-json <path>`,
+  including output policy, redaction and truncation metadata, and the dashboard harness report
 - `classify-report.schema.json`: output of `mf classify --changed --json` and  
   `mf classify <path...> --json`
 - `impact-report.schema.json`: output of `mf impact --changed --json` and  
   `mf impact <path...> --json`
 - `line-endings-report.schema.json`: output of `mf line-endings check --json` and  
   `mf line-endings normalize --json`
+- `handoff-validation-report.schema.json`: output of  
+  `mf handoff validate <path> --json`
 - `version-sources-report.schema.json`: output of `mf version-sources --json`
 - `docs-review-list.schema.json`: output of `mf docs review list --json`
 - `explain-report.schema.json`: output of `mf explain authority --json`, `mf explain command --json`,  
-  `mf explain retention --json`, `mf explain skills --json`, and `mf explain surface --json`
+  `mf explain verify --reason <event> --json`, `mf explain retention --json`, `mf explain skills --json`,
+  and `mf explain surface --json`. Verify explanations include the shared `decisionGraph` evidence model.
 - `verify-report.schema.json`: output of `mf verify --reason <event> --json`
 - `change-verification-report.schema.json`: output of `mf verify --reason <event> --plan-only --json` and  
-  `mf verify --from-plan <path> --plan-only --json`
+  `mf verify --from-plan <classify-report.json> --plan-only --json`, including the `decision_graph` that links
+  changed surfaces, classification reasons, command candidates, eligibility, selected or not-selected state,
+  effects, and gaps.
+  Local-index command-effect graphs are explanation-only and cannot grant command authority.
 
 These schemas define stable, automation-facing fields. Human-readable command  
 output is intentionally excluded.
 
 The published schema surface is tracked in `src/core/public-json-contracts.ts`.  
 Release tests verify consistency between this manifest, `schemas/*.schema.json`,  
-`npm pack --dry-run --json`, and the installed package’s JSON command output.
+`npm pack --dry-run --json`, and the installed package’s JSON command output.

package/schemas/adapter-compatibility-report.schema.json

@@ -0,0 +1,184 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/adapter-compatibility-report.schema.json",
+  "title": "mustflow adapter compatibility report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "ok",
+    "mustflow_root",
+    "agents_file",
+    "summary",
+    "host_files",
+    "adapter_surfaces",
+    "findings",
+    "compatibility_notes",
+    "required_changes",
+    "runtime_policy",
+    "boundaries"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "adapters_status" },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "agents_file": { "$ref": "#/$defs/agentsFile" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "host_files": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/hostFile" }
+    },
+    "adapter_surfaces": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/adapterSurface" }
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "compatibility_notes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "required_changes": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "runtime_policy": { "$ref": "#/$defs/runtimePolicy" },
+    "boundaries": { "$ref": "#/$defs/boundaries" }
+  },
+  "$defs": {
+    "agentsFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "present", "authority", "lifecycle", "generated_by_mustflow"],
+      "properties": {
+        "path": { "const": "AGENTS.md" },
+        "present": { "type": "boolean" },
+        "authority": { "const": "binding" },
+        "lifecycle": { "const": "user_editable" },
+        "generated_by_mustflow": { "type": "boolean" }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "host_instruction_files",
+        "adapter_surfaces_present",
+        "compatibility_notes",
+        "conflicts",
+        "required_changes"
+      ],
+      "properties": {
+        "host_instruction_files": { "type": "integer", "minimum": 0 },
+        "adapter_surfaces_present": { "type": "integer", "minimum": 0 },
+        "compatibility_notes": { "type": "integer", "minimum": 0 },
+        "conflicts": { "type": "integer", "minimum": 0 },
+        "required_changes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "hostFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "host",
+        "path",
+        "status",
+        "instruction_role",
+        "authority",
+        "mustflow_authority",
+        "lifecycle",
+        "generated_by_mustflow",
+        "binding_to_host",
+        "mustflow_command_authority"
+      ],
+      "properties": {
+        "host": { "enum": ["claude_code", "gemini_cli", "github_copilot", "cursor", "generic"] },
+        "path": { "type": "string" },
+        "status": { "enum": ["absent", "present", "unreadable", "symlink_not_read", "too_large_not_read"] },
+        "instruction_role": { "const": "host_instruction" },
+        "authority": { "const": "host_specific" },
+        "mustflow_authority": { "const": "advisory" },
+        "lifecycle": { "const": "user_editable" },
+        "generated_by_mustflow": { "const": false },
+        "binding_to_host": { "type": "boolean" },
+        "mustflow_command_authority": { "const": false }
+      }
+    },
+    "adapterSurface": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "host",
+        "path",
+        "kind",
+        "present",
+        "generated_by_mustflow",
+        "generation_policy",
+        "mustflow_command_authority"
+      ],
+      "properties": {
+        "host": { "enum": ["claude_code", "gemini_cli", "github_copilot", "cursor", "generic"] },
+        "path": { "type": "string" },
+        "kind": {
+          "enum": [
+            "host_instruction_file",
+            "editor_settings",
+            "ci_configuration",
+            "command_adapter",
+            "package_manager_scripts"
+          ]
+        },
+        "present": { "type": "boolean" },
+        "generated_by_mustflow": { "const": false },
+        "generation_policy": { "const": "explicit_user_request_only" },
+        "mustflow_command_authority": { "const": false }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["severity", "code", "path", "message", "required_change"],
+      "properties": {
+        "severity": { "enum": ["info", "warning"] },
+        "code": { "type": "string" },
+        "path": { "type": ["string", "null"] },
+        "message": { "type": "string" },
+        "required_change": { "type": "boolean" }
+      }
+    },
+    "runtimePolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["approval_policy", "sandbox_policy", "stricter_than_mustflow", "note"],
+      "properties": {
+        "approval_policy": { "const": "not_repo_visible" },
+        "sandbox_policy": { "const": "not_repo_visible" },
+        "stricter_than_mustflow": { "const": "unknown" },
+        "note": { "type": "string" }
+      }
+    },
+    "boundaries": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "command_authority",
+        "host_files_are_command_authority",
+        "adapter_generation",
+        "does_not_generate"
+      ],
+      "properties": {
+        "command_authority": { "const": ".mustflow/config/commands.toml" },
+        "host_files_are_command_authority": { "const": false },
+        "adapter_generation": { "const": "explicit_user_request_only" },
+        "does_not_generate": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}