mustflow 1.18.16 → 1.30.0

package/dist/core/secret-redaction.js

@@ -0,0 +1,39 @@
+export const REDACTED_SECRET_MARKER = '[REDACTED_SECRET]';
+const SECRET_VALUE_PATTERN = '[A-Za-z0-9_./+=:-]{8,}';
+const SECRET_REDACTION_RULES = [
+    {
+        kind: 'secret_key_value',
+        pattern: new RegExp(`\\b((?:api[_-]?key|api[_-]?token|access[_-]?token|auth[_-]?token|secret|password|passwd|private[_-]?key)\\b\\s*[:=]\\s*["']?)(${SECRET_VALUE_PATTERN})`, 'giu'),
+        replace: (_match, prefix) => `${prefix}${REDACTED_SECRET_MARKER}`,
+    },
+    {
+        kind: 'secret_token',
+        pattern: /\b(?:sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}|AKIA[0-9A-Z]{16})\b/gu,
+        replace: () => REDACTED_SECRET_MARKER,
+    },
+];
+export const SECRET_LIKE_PATTERNS = SECRET_REDACTION_RULES.map((rule) => {
+    const flags = rule.pattern.flags.replace('g', '');
+    return new RegExp(rule.pattern.source, flags);
+});
+export function textContainsSecretLike(value) {
+    return SECRET_LIKE_PATTERNS.some((pattern) => pattern.test(value));
+}
+export function redactSecretLikeText(value) {
+    let text = value;
+    let redactionCount = 0;
+    const redactionKinds = new Set();
+    for (const rule of SECRET_REDACTION_RULES) {
+        text = text.replace(rule.pattern, (...match) => {
+            redactionCount += 1;
+            redactionKinds.add(rule.kind);
+            return rule.replace(...match.map(String));
+        });
+    }
+    return {
+        text,
+        redacted: redactionCount > 0,
+        redactionCount,
+        redactionKinds: [...redactionKinds].sort(),
+    };
+}

package/dist/core/source-anchors.js

@@ -1,5 +1,6 @@
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
+import { SECRET_LIKE_PATTERNS, textContainsSecretLike } from './secret-redaction.js';
 export const SOURCE_ANCHOR_EXTENSIONS = new Set(['.cjs', '.go', '.js', '.jsx', '.mjs', '.py', '.rs', '.ts', '.tsx']);
 export const SOURCE_ANCHOR_DEFAULT_EXCLUDED_PATH_PARTS = new Set([
     '.git',
@@ -44,10 +45,7 @@ export const SOURCE_ANCHOR_ALLOWED_RISKS = new Set([
     'xss',
 ]);
 export const SOURCE_ANCHOR_ID_PATTERN = /^[a-z0-9][a-z0-9.-]{0,95}$/u;
-export const SOURCE_ANCHOR_SECRET_LIKE_PATTERNS = [
-    /\b(?:api[_-]?key|api[_-]?token|access[_-]?token|auth[_-]?token|secret|password|passwd|private[_-]?key)\b\s*[:=]\s*["']?[A-Za-z0-9_./+=:-]{8,}/iu,
-    /\b(?:sk-[A-Za-z0-9]{16,}|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{20,}|AKIA[0-9A-Z]{16})\b/u,
-];
+export const SOURCE_ANCHOR_SECRET_LIKE_PATTERNS = SECRET_LIKE_PATTERNS;
 function toPosixPath(value) {
     return value.split(path.sep).join('/');
 }
@@ -189,7 +187,7 @@ export function sourceAnchorPathIsGeneratedOrVendor(relativePath) {
     return parts.some((part) => SOURCE_ANCHOR_GENERATED_PATH_PARTS.has(part));
 }
 export function sourceAnchorTextContainsSecretLike(value) {
-    return SOURCE_ANCHOR_SECRET_LIKE_PATTERNS.some((pattern) => pattern.test(value));
+    return textContainsSecretLike(value);
 }
 export function parseSourceAnchorsInContent(relativePath, content) {
     const lines = content.split(/\r?\n/);

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

@@ -0,0 +1,223 @@
+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 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'),
+    };
+}
+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,
+        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,
+                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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "1.18.16",
+  "version": "1.30.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,8 +6,10 @@ 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
 - `commands.schema.json`: parsed `.mustflow/config/commands.toml`
 - `contract-lint-report.schema.json`: output of `mf contract-lint --json`
 - `classify-report.schema.json`: output of `mf classify --changed --json` and  
@@ -16,17 +18,22 @@ Current schemas:
   `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, 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" }
+        }
+      }
+    }
+  }
+}