mustflow 2.74.3 → 2.74.5

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

@@ -0,0 +1,199 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+export function isScriptPackSuggestionPhase(value) {
+    return ['before_change', 'during_change', 'after_change', 'review'].includes(value);
+}
+function uniqueSortedStrings(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function uniqueSortedPhases(values) {
+    return uniqueSortedStrings(values);
+}
+function uniqueSortedSurfaces(values) {
+    return uniqueSortedStrings(values);
+}
+function normalizeReportPath(mustflowRoot, value) {
+    const absolute = path.resolve(mustflowRoot, value);
+    const relative = path.relative(mustflowRoot, absolute);
+    return relative.startsWith('..') || path.isAbsolute(relative)
+        ? value.replace(/\\/gu, '/')
+        : (relative.replace(/\\/gu, '/') || '.');
+}
+export function classifyScriptPackPathSurface(relativePath) {
+    const normalized = relativePath.replace(/\\/gu, '/').replace(/^\.\/+/u, '');
+    const surfaces = [];
+    if (normalized === 'REPO_MAP.md' ||
+        normalized === '.mustflow/config/manifest.lock.toml' ||
+        normalized.startsWith('dist/') ||
+        normalized.startsWith('build/') ||
+        normalized.startsWith('coverage/') ||
+        normalized.startsWith('.mustflow/cache/') ||
+        normalized.startsWith('.mustflow/state/')) {
+        surfaces.push('generated');
+    }
+    if (normalized.startsWith('.mustflow/config/') || normalized.startsWith('config/')) {
+        surfaces.push('config');
+    }
+    if (normalized.startsWith('.mustflow/skills/') || normalized.includes('/.mustflow/skills/')) {
+        surfaces.push('skill');
+    }
+    if (normalized.startsWith('templates/')) {
+        surfaces.push('template');
+    }
+    if (normalized.startsWith('schemas/') || normalized.endsWith('.schema.json')) {
+        surfaces.push('schema');
+    }
+    if (normalized === 'README.md' ||
+        normalized === 'CHANGELOG.md' ||
+        normalized.endsWith('.md') ||
+        normalized.startsWith('docs/') ||
+        normalized.startsWith('docs-site/')) {
+        surfaces.push('docs');
+    }
+    if (normalized.startsWith('tests/') || normalized.endsWith('.test.js') || normalized.endsWith('.test.ts')) {
+        surfaces.push('test');
+    }
+    if (normalized === 'package.json' ||
+        normalized === 'bun.lock' ||
+        normalized === 'package-lock.json' ||
+        normalized.startsWith('.github/workflows/')) {
+        surfaces.push('package');
+    }
+    if (normalized.startsWith('src/') || normalized.endsWith('.ts') || normalized.endsWith('.tsx')) {
+        surfaces.push('source');
+    }
+    return surfaces.length > 0 ? uniqueSortedSurfaces(surfaces) : ['unknown'];
+}
+function readChangedPaths(mustflowRoot, issues) {
+    const result = spawnSync('git', ['status', '--short'], {
+        cwd: mustflowRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    if (result.status !== 0) {
+        const detail = result.stderr.trim() || result.stdout.trim() || `git status exited with ${result.status}`;
+        issues.push(`Could not read changed paths: ${detail}`);
+        return [];
+    }
+    return result.stdout
+        .split(/\r?\n/u)
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const renamed = /\s->\s(?<target>.+)$/u.exec(line);
+        return renamed?.groups?.target ?? line.slice(3).trim();
+    })
+        .filter((entry) => entry.length > 0);
+}
+function surfacesForScript(script) {
+    const surfaces = new Set();
+    const searchable = [
+        script.ref,
+        script.usage,
+        ...script.useWhen,
+        ...script.inputs,
+        ...script.outputs,
+        ...script.relatedSkills,
+    ].join(' ');
+    const addIf = (surface, pattern) => {
+        if (pattern.test(searchable)) {
+            surfaces.add(surface);
+        }
+    };
+    addIf('docs', /docs|readme|release|copy|text|prompt/u);
+    addIf('schema', /json|schema|contract/u);
+    addIf('template', /template|install|manifest/u);
+    addIf('skill', /skill|workflow/u);
+    addIf('generated', /generated|protected|vendor|cache|boundary/u);
+    addIf('config', /config|command/u);
+    addIf('package', /package|release/u);
+    addIf('source', /code|source|path/u);
+    return uniqueSortedSurfaces(surfaces);
+}
+function confidenceForScore(score) {
+    if (score >= 7) {
+        return 'high';
+    }
+    if (score >= 4) {
+        return 'medium';
+    }
+    return 'low';
+}
+export function createScriptPackSuggestionReport(mustflowRoot, options) {
+    const issues = [];
+    const changedPaths = options.changed ? readChangedPaths(mustflowRoot, issues) : [];
+    const inputPaths = uniqueSortedStrings([...options.paths, ...changedPaths].map((value) => normalizeReportPath(mustflowRoot, value)));
+    const analyzedPaths = inputPaths.map((entry) => ({ path: entry, surfaces: classifyScriptPackPathSurface(entry) }));
+    const requestedSurfaces = new Set(analyzedPaths.flatMap((entry) => entry.surfaces));
+    const suggestions = options.scripts
+        .map((script) => {
+        let score = 0;
+        const reasons = [];
+        const matchedPhases = options.phases.filter((phase) => script.phases.includes(phase));
+        if (matchedPhases.length > 0) {
+            score += matchedPhases.length * 3;
+            reasons.push(`Matches requested phase: ${matchedPhases.join(', ')}`);
+        }
+        const matchedSkills = options.skills.filter((skill) => script.relatedSkills.includes(skill));
+        if (matchedSkills.length > 0) {
+            score += matchedSkills.length * 4;
+            reasons.push(`Matches related skill: ${matchedSkills.join(', ')}`);
+        }
+        const scriptSurfaces = surfacesForScript(script);
+        const matchedSurfaces = scriptSurfaces.filter((surface) => requestedSurfaces.has(surface));
+        if (matchedSurfaces.length > 0) {
+            score += matchedSurfaces.length * 2;
+            reasons.push(`Matches changed surface: ${matchedSurfaces.join(', ')}`);
+        }
+        if (inputPaths.length > 0 && script.inputs.includes('path')) {
+            score += 1;
+            reasons.push('Accepts explicit path inputs.');
+        }
+        if (script.readOnly && !script.mutates && !script.network) {
+            score += 1;
+            reasons.push('Read-only, non-mutating, offline helper.');
+        }
+        if (score === 0) {
+            return null;
+        }
+        return {
+            script_ref: script.ref,
+            score,
+            confidence: confidenceForScore(score),
+            usage: script.usage,
+            phases: script.phases,
+            matched_phases: uniqueSortedPhases(matchedPhases),
+            matched_skills: uniqueSortedStrings(matchedSkills),
+            matched_surfaces: uniqueSortedSurfaces(matchedSurfaces),
+            reasons,
+            read_only: script.readOnly,
+            mutates: script.mutates,
+            network: script.network,
+            risk_level: script.riskLevel,
+            cost: script.cost,
+            report_schema_file: script.reportSchemaFile,
+            run_hint: script.usage,
+        };
+    })
+        .filter((suggestion) => suggestion !== null)
+        .sort((left, right) => right.score - left.score || left.script_ref.localeCompare(right.script_ref));
+    const status = issues.length > 0 ? 'partial' : suggestions.length > 0 ? 'suggested' : 'empty';
+    return {
+        schema_version: '1',
+        command: 'script-pack',
+        action: 'suggest',
+        status,
+        ok: true,
+        mustflow_root: mustflowRoot,
+        input: {
+            phases: uniqueSortedPhases(options.phases),
+            skills: uniqueSortedStrings(options.skills),
+            paths: inputPaths,
+            changed: options.changed,
+        },
+        analyzed_paths: analyzedPaths,
+        suggestions,
+        issues,
+    };
+}

package/package.json

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

package/schemas/README.md

@@ -29,7 +29,8 @@ Current schemas:
 - `onboard-commands-report.schema.json`: output of `mf onboard commands --json`, containing
   review-only command-intent suggestions that do not grant command authority or write files
 - `next-report.schema.json`: output of `mf next --json`, containing the next safe action,
-  changed-file verification gaps, and read-only command recommendations
+  changed-file verification gaps, read-only command recommendations, and optional read-only
+  script-pack helper suggestions
 - `evidence-report.schema.json`: output of `mf evidence --changed --json`, containing verification
   requirements, risk-priced evidence assessment, latest bounded evidence, failure replay capsules,
   conflict ledgers, receipts, remaining risks, and gaps without running commands
@@ -57,11 +58,18 @@ Current schemas:
   quality-gaming risks such as line stuffing, validation suppressions, test bypass markers, type
   escapes, generated/vendor logic, empty catch swallowing, and placeholder implementations
 - `script-pack-catalog.schema.json`: output of `mf script-pack list --json`, containing bundled
-  script-pack ids, script refs, action names, usage strings, and associated report schemas
+  script-pack ids, script refs, action names, usage strings, workflow phases, read-only and
+  side-effect flags, input and output capability labels, related skill names, cost and risk hints,
+  and associated report schemas
+- `script-pack-suggestion-report.schema.json`: output of `mf script-pack suggest --json`, containing
+  path, skill, phase, and changed-file evidence used to recommend optional script-pack helpers
 - `text-budget-report.schema.json`: output of
   `mf script-pack run core/text-budget check <path...> --json`, containing
   exact text-budget metrics, input content hashes, policy metadata, findings, and JSON Pointer field
   checks for bounded user-facing strings and generated text
+- `generated-boundary-report.schema.json`: output of
+  `mf script-pack run repo/generated-boundary check <path...> --json`, containing candidate path
+  classifications for generated, ignored, protected, vendor, and cache boundaries before or after edits
 - `skill-route-report.schema.json`: output of `mf skill route --json`, containing compact route
   candidates, selected main and adjunct skills, score breakdowns, route read plans, and source
   route shards without granting command authority or replacing selected `SKILL.md` reads

package/schemas/generated-boundary-report.schema.json

@@ -0,0 +1,148 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/generated-boundary-report.schema.json",
+  "title": "mustflow generated-boundary report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "pack_id",
+    "script_id",
+    "script_ref",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "policy",
+    "input_hash",
+    "targets",
+    "findings",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "pack_id": { "const": "repo" },
+    "script_id": { "const": "generated-boundary" },
+    "script_ref": { "const": "repo/generated-boundary" },
+    "action": { "const": "check" },
+    "status": { "enum": ["passed", "failed", "error"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "policy": { "$ref": "#/$defs/policy" },
+    "input_hash": { "$ref": "#/$defs/sha256" },
+    "targets": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/target" }
+    },
+    "findings": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/finding" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[a-f0-9]{64}$"
+    },
+    "category": {
+      "enum": ["generated", "ignored", "protected", "vendor", "cache", "outside_root"]
+    },
+    "patternSource": {
+      "enum": ["mustflow_config", "builtin"]
+    },
+    "patternMatch": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["category", "pattern", "source"],
+      "properties": {
+        "category": { "$ref": "#/$defs/category" },
+        "pattern": { "type": "string" },
+        "source": { "$ref": "#/$defs/patternSource" }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "config_path",
+        "config_loaded",
+        "generated_patterns",
+        "ignored_patterns",
+        "protected_patterns",
+        "builtin_generated_patterns",
+        "builtin_vendor_patterns",
+        "builtin_cache_patterns",
+        "builtin_protected_patterns"
+      ],
+      "properties": {
+        "config_path": { "const": ".mustflow/config/mustflow.toml" },
+        "config_loaded": { "type": "boolean" },
+        "generated_patterns": { "$ref": "#/$defs/stringArray" },
+        "ignored_patterns": { "$ref": "#/$defs/stringArray" },
+        "protected_patterns": { "$ref": "#/$defs/stringArray" },
+        "builtin_generated_patterns": { "$ref": "#/$defs/stringArray" },
+        "builtin_vendor_patterns": { "$ref": "#/$defs/stringArray" },
+        "builtin_cache_patterns": { "$ref": "#/$defs/stringArray" },
+        "builtin_protected_patterns": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["input", "path", "exists", "kind", "matched_boundaries", "matched_patterns"],
+      "properties": {
+        "input": { "type": "string" },
+        "path": { "type": "string" },
+        "exists": { "type": ["boolean", "null"] },
+        "kind": { "enum": ["file", "directory", "missing", "other", "unknown"] },
+        "matched_boundaries": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/category" }
+        },
+        "matched_patterns": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/patternMatch" }
+        }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "severity", "message", "path", "boundary", "pattern", "source"],
+      "properties": {
+        "code": {
+          "enum": [
+            "generated_boundary_generated_path",
+            "generated_boundary_ignored_path",
+            "generated_boundary_protected_path",
+            "generated_boundary_vendor_path",
+            "generated_boundary_cache_path",
+            "generated_boundary_path_outside_root",
+            "generated_boundary_unreadable_path"
+          ]
+        },
+        "severity": { "enum": ["low", "medium", "high", "critical"] },
+        "message": { "type": "string" },
+        "path": { "type": "string" },
+        "boundary": { "$ref": "#/$defs/category" },
+        "pattern": { "type": ["string", "null"] },
+        "source": {
+          "anyOf": [
+            { "$ref": "#/$defs/patternSource" },
+            { "type": "null" }
+          ]
+        }
+      }
+    }
+  }
+}

package/schemas/next-report.schema.json

@@ -116,6 +116,146 @@
         }
       }
     },
+    "script_pack_suggestions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "input", "analyzed_paths", "suggestions", "issues"],
+      "properties": {
+        "status": { "type": "string", "enum": ["suggested", "empty", "partial"] },
+        "input": { "$ref": "#/$defs/scriptPackSuggestionInput" },
+        "analyzed_paths": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/scriptPackAnalyzedPath" }
+        },
+        "suggestions": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/scriptPackSuggestion" }
+        },
+        "issues": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
     "verification_plan_id": { "type": ["string", "null"] }
+  },
+  "$defs": {
+    "scriptPackPhase": {
+      "type": "string",
+      "enum": ["before_change", "during_change", "after_change", "review"]
+    },
+    "scriptPackSurface": {
+      "type": "string",
+      "enum": [
+        "config",
+        "docs",
+        "generated",
+        "package",
+        "schema",
+        "skill",
+        "source",
+        "template",
+        "test",
+        "unknown"
+      ]
+    },
+    "scriptPackSuggestionInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["phases", "skills", "paths", "changed"],
+      "properties": {
+        "phases": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/scriptPackPhase" }
+        },
+        "skills": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "changed": { "type": "boolean" }
+      }
+    },
+    "scriptPackAnalyzedPath": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "surfaces"],
+      "properties": {
+        "path": { "type": "string" },
+        "surfaces": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/scriptPackSurface" },
+          "minItems": 1
+        }
+      }
+    },
+    "scriptPackSuggestion": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "script_ref",
+        "score",
+        "confidence",
+        "usage",
+        "phases",
+        "matched_phases",
+        "matched_skills",
+        "matched_surfaces",
+        "reasons",
+        "read_only",
+        "mutates",
+        "network",
+        "risk_level",
+        "cost",
+        "report_schema_file",
+        "run_hint"
+      ],
+      "properties": {
+        "script_ref": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*/[a-z0-9]+(?:-[a-z0-9]+)*$"
+        },
+        "score": { "type": "integer", "minimum": 0 },
+        "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
+        "usage": { "type": "string" },
+        "phases": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/scriptPackPhase" },
+          "minItems": 1
+        },
+        "matched_phases": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/scriptPackPhase" }
+        },
+        "matched_skills": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        },
+        "matched_surfaces": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/scriptPackSurface" }
+        },
+        "reasons": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "read_only": { "type": "boolean" },
+        "mutates": { "type": "boolean" },
+        "network": { "type": "boolean" },
+        "risk_level": { "type": "string", "enum": ["low", "medium", "high"] },
+        "cost": { "type": "string", "enum": ["low", "medium", "high"] },
+        "report_schema_file": {
+          "anyOf": [
+            { "type": "string", "pattern": "^[a-z0-9-]+\\.schema\\.json$" },
+            { "type": "null" }
+          ]
+        },
+        "run_hint": { "type": "string" }
+      }
+    }
   }
 }

package/schemas/script-pack-catalog.schema.json

@@ -56,6 +56,38 @@
           "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
           "minItems": 1
         },
+        "use_when": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "phases": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["before_change", "during_change", "after_change", "review"]
+          },
+          "minItems": 1
+        },
+        "read_only": { "type": "boolean" },
+        "mutates": { "type": "boolean" },
+        "network": { "type": "boolean" },
+        "inputs": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$" },
+          "minItems": 1
+        },
+        "outputs": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$" },
+          "minItems": 1
+        },
+        "related_skills": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        },
+        "risk_level": { "type": "string", "enum": ["low", "medium", "high"] },
+        "cost": { "type": "string", "enum": ["low", "medium", "high"] },
         "report_schema_file": {
           "anyOf": [
             { "type": "string", "pattern": "^[a-z0-9-]+\\.schema\\.json$" },