mustflow 2.74.3 → 2.74.5

package/schemas/script-pack-suggestion-report.schema.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/script-pack-suggestion-report.schema.json",
+  "title": "mustflow script-pack suggestion report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "action",
+    "status",
+    "ok",
+    "mustflow_root",
+    "input",
+    "analyzed_paths",
+    "suggestions",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "script-pack" },
+    "action": { "const": "suggest" },
+    "status": { "type": "string", "enum": ["suggested", "empty", "partial"] },
+    "ok": { "type": "boolean" },
+    "mustflow_root": { "type": "string" },
+    "input": { "$ref": "#/$defs/input" },
+    "analyzed_paths": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/analyzedPath" }
+    },
+    "suggestions": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/suggestion" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "phase": {
+      "type": "string",
+      "enum": ["before_change", "during_change", "after_change", "review"]
+    },
+    "surface": {
+      "type": "string",
+      "enum": [
+        "config",
+        "docs",
+        "generated",
+        "package",
+        "schema",
+        "skill",
+        "source",
+        "template",
+        "test",
+        "unknown"
+      ]
+    },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["phases", "skills", "paths", "changed"],
+      "properties": {
+        "phases": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/phase" }
+        },
+        "skills": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "changed": { "type": "boolean" }
+      }
+    },
+    "analyzedPath": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "surfaces"],
+      "properties": {
+        "path": { "type": "string" },
+        "surfaces": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/surface" },
+          "minItems": 1
+        }
+      }
+    },
+    "suggestion": {
+      "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/phase" },
+          "minItems": 1
+        },
+        "matched_phases": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/phase" }
+        },
+        "matched_skills": {
+          "type": "array",
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        },
+        "matched_surfaces": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/surface" }
+        },
+        "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/templates/default/common/.mustflow/config/commands.toml

@@ -143,6 +143,38 @@ network = false
 destructive = false
 required_after = ["code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "unknown_change"]
 
+[intents.script_pack_list]
+status = "configured"
+kind = "mustflow_builtin"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "List bundled mustflow script-pack utilities and routing metadata read-only."
+argv = ["mf", "script-pack", "list", "--json"]
+cwd = "."
+timeout_seconds = 120
+stdin = "closed"
+success_exit_codes = [0]
+writes = []
+network = false
+destructive = false
+required_after = ["before_task", "docs_change", "public_api_change", "unknown_change"]
+
+[intents.script_pack_suggest_changed]
+status = "configured"
+kind = "mustflow_builtin"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "Suggest bundled mustflow script-pack utilities for current changed files read-only."
+argv = ["mf", "script-pack", "suggest", "--changed", "--json"]
+cwd = "."
+timeout_seconds = 120
+stdin = "closed"
+success_exit_codes = [0]
+writes = []
+network = false
+destructive = false
+required_after = ["before_task", "docs_change", "public_api_change", "mustflow_docs_change", "unknown_change"]
+
 [intents.prompt_cache_audit]
 status = "configured"
 kind = "mustflow_builtin"

package/templates/default/i18n.toml

@@ -691,7 +691,7 @@ translations = {}
 [documents."skill.completion-evidence-gate"]
 source = "locales/en/.mustflow/skills/completion-evidence-gate/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.evidence-stall-breaker"]
@@ -709,7 +709,7 @@ translations = {}
 [documents."skill.public-json-contract-change"]
 source = "locales/en/.mustflow/skills/public-json-contract-change/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.provenance-license-gate"]
@@ -846,7 +846,7 @@ translations = {}
 [documents."skill.repo-improvement-loop"]
 source = "locales/en/.mustflow/skills/repo-improvement-loop/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.requirement-regression-guard"]
@@ -954,7 +954,7 @@ translations = {}
 [documents."skill.template-install-surface-sync"]
 source = "locales/en/.mustflow/skills/template-install-surface-sync/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.restricted-handoff-resume"]

package/templates/default/locales/en/.mustflow/skills/completion-evidence-gate/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.completion-evidence-gate
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: completion-evidence-gate
@@ -67,6 +67,7 @@ missing, blocked, failed, stale, or only partially relevant.
 - Requirement, bug, issue, or external-advice sources that influenced the work.
 - Command intents run, exit status, and whether the evidence came from `mf run` receipts or lower-confidence direct shell output.
 - Command intents skipped, missing, unknown, manual-only, failed, timed out, or judged not applicable.
+- Optional script-pack discovery evidence when the command contract exposes `script_pack_list`.
 - Synchronized surfaces expected by the changed contract: source, tests, fixtures, schemas, templates, manifests, docs, release metadata, generated output, and localized copies.
 - Known remaining risks, unverified assumptions, blocked decisions, and rollback notes.
 
@@ -108,6 +109,8 @@ missing, blocked, failed, stale, or only partially relevant.
      `evidence-stall-breaker` when that pattern affected the task.
 5. Check synchronization coverage.
    - For behavior or contract changes, verify whether code, tests, schemas, templates, manifests, docs, fixtures, examples, package metadata, release notes, and localized copies agree.
+   - When `.mustflow/config/commands.toml` exposes `script_pack_list`, use it as read-only discovery before choosing optional script-pack checks for the changed surfaces.
+   - Treat `repo/generated-boundary` as a useful candidate before or after path-sensitive edits, but run any selected script only when the repository command contract and script metadata allow it.
    - Use `contract-sync-check`, `cli-output-contract-review`, `api-contract-change`, `release-publish-change`, or a narrower skill when a missing surface needs real follow-up work.
 6. Calibrate completion language.
    - Use `verified` only when the relevant configured checks passed and every required surface is covered.

package/templates/default/locales/en/.mustflow/skills/public-json-contract-change/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.public-json-contract-change
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: public-json-contract-change
@@ -61,6 +61,7 @@ Protect automation consumers from silent JSON, JSONL, stream, schema, fixture, a
 - The task matches the Use When conditions and does not match the Do Not Use When exclusions.
 - Existing JSON tests, schemas, docs examples, package fixtures, and compatibility fixtures have been inspected before changing the contract.
 - Command execution remains governed by `.mustflow/config/commands.toml`; this skill does not authorize raw commands.
+- If `.mustflow/config/commands.toml` exposes `script_pack_list`, it may be used only as read-only discovery for optional script-pack checks.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -87,7 +88,9 @@ Protect automation consumers from silent JSON, JSONL, stream, schema, fixture, a
 10. Use snapshot and golden-output files only as review aids. Add or preserve assertions for field presence, primitive types, enum values, null versus missing semantics, stream split, exit code, and schema validation where existing test structure supports it.
 11. Synchronize schemas, fixtures, examples, package file lists, docs, templates, and release notes when the contract changes. If a surface is intentionally stale or deferred, record why.
 12. Route version impact through the repository versioning policy when the change is breaking, deprecating, package-visible, or template-visible.
-13. Verify with the narrowest configured command intents that cover JSON contract, docs, package, and mustflow metadata changes.
+13. Before final verification, use `script_pack_list` when the command contract exposes it to discover optional JSON, schema, or repository-boundary script-pack checks relevant to the changed public contract.
+14. Run selected scripts only when both the repository command contract and the script metadata allow the action.
+15. Verify with the narrowest configured command intents that cover JSON contract, docs, package, and mustflow metadata changes.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

package/templates/default/locales/en/.mustflow/skills/repo-improvement-loop/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.repo-improvement-loop
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: repo-improvement-loop
@@ -61,6 +61,7 @@ The goal is not to generate many interesting ideas. The goal is to find the high
 - Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
 - If unfamiliar areas are involved, enough repository evidence has been inspected to avoid inventing architecture, entrypoints, or user flows.
 - If external AI output, issue text, webpages, or pasted recommendations are used, `external-prompt-injection-defense` has been applied first.
+- If `.mustflow/config/commands.toml` exposes `script_pack_list`, it may be used only as read-only discovery for optional script-pack checks.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -80,6 +81,8 @@ The goal is not to generate many interesting ideas. The goal is to find the high
    - Use recursive mode only as one bounded cycle at a time unless a larger explicit budget is provided.
 2. Inspect repository evidence before scoring candidates.
    - Read the smallest set of current files needed to understand project purpose, user path, command contracts, tests, release surface, and existing work in progress.
+   - When the command contract exposes `script_pack_list`, use it to discover relevant read-only script-pack helpers before selecting or verifying a candidate improvement.
+   - Prefer `repo/generated-boundary` as a candidate helper when an improvement might touch generated output, protected paths, vendor files, caches, or files outside the project root.
    - If the area is unfamiliar, use `codebase-orientation` before proposing changes.
 3. Generate repository-specific improvement questions.
    - High-leverage: Which small change creates the largest user or maintainer benefit?
@@ -102,7 +105,8 @@ The goal is not to generate many interesting ideas. The goal is to find the high
    - Use `pattern-scout` when local precedent is needed before adding a new shape.
    - Use `contract-sync-check` when behavior, templates, manifests, schemas, tests, or public docs must stay aligned.
 7. Verify the selected improvement with the narrowest configured command intents that cover the changed surfaces.
-8. Report the cycle and name the next improvement question revealed by the work.
+8. Run selected script-pack helpers only when the repository command contract and script metadata allow them.
+9. Report the cycle and name the next improvement question revealed by the work.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

package/templates/default/locales/en/.mustflow/skills/template-install-surface-sync/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.template-install-surface-sync
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: template-install-surface-sync
@@ -61,6 +61,7 @@ Keep the source repository's mustflow workflow files, install templates, manifes
 - Canonical source locale and template locale policy are known.
 - Existing template manifest and nearby tests have been inspected before adding or removing installed files.
 - Command execution remains governed by `.mustflow/config/commands.toml`; this skill does not authorize raw commands.
+- If `.mustflow/config/commands.toml` exposes `script_pack_list`, it may be used only as read-only discovery for optional script-pack checks.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -85,8 +86,10 @@ Keep the source repository's mustflow workflow files, install templates, manifes
 8. Check install/update behavior. If new files, profile membership, conflict policy, or managed targets change, inspect init/update tests and package tests that assert installed output, manifest lock behavior, backups, or diff previews.
 9. Check package and release surfaces. Installed template files must be included in package output and covered by release-sensitive tests when the package includes templates.
 10. Check public docs and examples only when they list installed files, profiles, init/update behavior, or workflow expectations.
-11. Keep generated files generated. Refresh generated maps or package output only with configured intents, and report generated surfaces that are stale but outside the current allowed command set.
-12. Verify with related tests first, then release and docs checks when package, template, manifest, or docs surfaces changed.
+11. When the command contract exposes `script_pack_list`, use it to discover optional script-pack helpers before editing or verifying template surfaces. `repo/generated-boundary` is useful for checking candidate template, manifest, generated-output, vendor, cache, or protected paths.
+12. Keep generated files generated. Refresh generated maps or package output only with configured intents, and report generated surfaces that are stale but outside the current allowed command set.
+13. Run selected script-pack helpers only when the repository command contract and script metadata allow them.
+14. Verify with related tests first, then release and docs checks when package, template, manifest, or docs surfaces changed.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.74.3"
+version = "2.74.5"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"