mustflow 2.59.0 → 2.68.6

package/schemas/skill-route-report.schema.json

@@ -0,0 +1,242 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/skill-route-report.schema.json",
+  "title": "mustflow skill route report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "kind",
+    "input",
+    "signals",
+    "selected",
+    "candidates",
+    "source_files",
+    "gap_notes",
+    "command",
+    "action"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "kind": { "const": "skill_route_resolution" },
+    "command": { "const": "skill" },
+    "action": { "const": "route" },
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_text_present", "paths", "reasons", "max_candidates"],
+      "properties": {
+        "task_text_present": { "type": "boolean" },
+        "paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "reasons": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "max_candidates": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        }
+      }
+    },
+    "signals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["task_terms", "path_terms", "reasons", "read_shards"],
+      "properties": {
+        "task_terms": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "path_terms": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "reasons": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "read_shards": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "selected": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["main", "adjuncts"],
+      "properties": {
+        "main": {
+          "oneOf": [
+            { "$ref": "#/$defs/candidate" },
+            { "type": "null" }
+          ]
+        },
+        "adjuncts": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/candidate" }
+        }
+      }
+    },
+    "candidates": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/candidate" }
+    },
+    "read_plan": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "selection_limits",
+        "stable_kernel",
+        "selected_skill_paths",
+        "candidate_skill_paths",
+        "fallback_route_metadata",
+        "expanded_index",
+        "avoid_by_default",
+        "notes"
+      ],
+      "properties": {
+        "selection_limits": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["candidates", "main", "adjuncts"],
+          "properties": {
+            "candidates": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 10
+            },
+            "main": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1
+            },
+            "adjuncts": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 2
+            }
+          }
+        },
+        "stable_kernel": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "selected_skill_paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "candidate_skill_paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "fallback_route_metadata": { "$ref": "#/$defs/readPlanFile" },
+        "expanded_index": { "$ref": "#/$defs/readPlanFile" },
+        "avoid_by_default": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "notes": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "source_files": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "gap_notes": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  },
+  "$defs": {
+    "candidate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "skill",
+        "skill_path",
+        "trigger",
+        "category",
+        "route_type",
+        "priority",
+        "applies_to_reasons",
+        "score",
+        "score_breakdown",
+        "selection_reasons",
+        "verification_intents"
+      ],
+      "properties": {
+        "skill": { "type": "string" },
+        "skill_path": { "type": "string" },
+        "trigger": { "type": "string" },
+        "category": {
+          "type": ["string", "null"],
+          "enum": [
+            "bug_failure",
+            "general_code",
+            "tests",
+            "docs_release",
+            "security_privacy",
+            "data_external",
+            "ui_assets",
+            "architecture_patterns",
+            "workflow_contracts",
+            null
+          ]
+        },
+        "route_type": { "type": "string" },
+        "priority": { "type": "integer" },
+        "applies_to_reasons": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "score": { "type": "number" },
+        "score_breakdown": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "reason_match",
+            "task_text_match",
+            "path_match",
+            "route_type_weight",
+            "priority_weight"
+          ],
+          "properties": {
+            "reason_match": { "type": "number" },
+            "task_text_match": { "type": "number" },
+            "path_match": { "type": "number" },
+            "route_type_weight": { "type": "number" },
+            "priority_weight": { "type": "number" }
+          }
+        },
+        "selection_reasons": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "verification_intents": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "readPlanFile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "read_when"],
+      "properties": {
+        "path": { "type": "string" },
+        "read_when": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/templates/default/common/.mustflow/config/commands.toml

@@ -143,6 +143,22 @@ network = false
 destructive = false
 required_after = ["code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "unknown_change"]
 
+[intents.prompt_cache_audit]
+status = "configured"
+kind = "mustflow_builtin"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "Measure prompt-cache profile sizes and configured budget status read-only."
+argv = ["mf", "context", "--json", "--cache-profile", "all", "--cache-audit"]
+cwd = "."
+timeout_seconds = 120
+stdin = "closed"
+success_exit_codes = [0]
+writes = []
+network = false
+destructive = false
+required_after = ["mustflow_config_change", "mustflow_docs_change", "public_api_change", "performance_change", "unknown_change"]
+
 [intents.line_endings_normalize]
 status = "manual_only"
 description = "Normalize tracked text files to the repository line-ending policy."
@@ -250,8 +266,8 @@ status = "configured"
 kind = "mustflow_builtin"
 lifecycle = "oneshot"
 run_policy = "agent_allowed"
-description = "Create or refresh the generated mustflow SQLite local index."
-argv = ["mf", "index"]
+description = "Create or refresh the generated mustflow SQLite local index, including bounded source anchors."
+argv = ["mf", "index", "--source"]
 cwd = "."
 timeout_seconds = 300
 stdin = "closed"

package/templates/default/common/.mustflow/config/mustflow.toml

@@ -8,10 +8,12 @@ read_order = [
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
   ".mustflow/config/technology.toml",
-  ".mustflow/skills/INDEX.md",
+  ".mustflow/skills/router.toml",
 ]
 optional_read_order = [
   ".mustflow/context/INDEX.md",
+  ".mustflow/skills/routes.toml",
+  ".mustflow/skills/INDEX.md",
   "REPO_MAP.md",
 ]
 
@@ -19,6 +21,8 @@ optional_read_order = [
 primary_instruction = "AGENTS.md"
 repository_map = "REPO_MAP.md"
 skill_index = ".mustflow/skills/INDEX.md"
+skill_router = ".mustflow/skills/router.toml"
+skill_routes = ".mustflow/skills/routes.toml"
 command_contract = ".mustflow/config/commands.toml"
 workflow_preferences = ".mustflow/config/preferences.toml"
 technology_preferences = ".mustflow/config/technology.toml"
@@ -38,6 +42,8 @@ anchor_files = [
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
   ".mustflow/config/technology.toml",
+  ".mustflow/skills/router.toml",
+  ".mustflow/skills/routes.toml",
   ".mustflow/skills/INDEX.md",
   "README.md",
   "PROJECT.md",
@@ -130,25 +136,24 @@ stable_prefix_policy = "hash_verified"
 prefer_references_when_unchanged = true
 exclude_volatile_state_from_prefix = true
 include_content_hashes = true
-max_stable_prefix_kb = 96
+max_stable_prefix_kb = 48
 max_task_context_kb = 48
 max_volatile_suffix_kb = 24
 
 [prompt_cache.layers.stable]
+target_kb = 32
 read = [
   "AGENTS.md",
-  ".mustflow/docs/agent-workflow.md",
-  ".mustflow/config/mustflow.toml",
-  ".mustflow/config/commands.toml",
-  ".mustflow/config/technology.toml",
-  ".mustflow/skills/INDEX.md",
+  ".mustflow/skills/router.toml",
 ]
 
 [prompt_cache.layers.task]
 read_policy = "task_relevant_only"
 sources = [
   ".mustflow/context/INDEX.md",
-  "REPO_MAP.md",
+  "skill_route_candidates",
+  "route_metadata_fallback",
+  "repo_map_navigation",
   "matching_skill",
   "relevant_source_files",
 ]
@@ -242,7 +247,7 @@ read = [
 method = "hash_check"
 read = [
   "AGENTS.md",
-  ".mustflow/skills/INDEX.md",
+  ".mustflow/skills/router.toml",
 ]
 
 [refresh.levels.full]
@@ -254,7 +259,8 @@ read = [
   ".mustflow/config/commands.toml",
   ".mustflow/config/preferences.toml",
   ".mustflow/config/technology.toml",
-  ".mustflow/skills/INDEX.md",
+  ".mustflow/skills/router.toml",
+  ".mustflow/skills/routes.toml",
 ]
 
 [compaction]

package/templates/default/i18n.toml

@@ -10,8 +10,8 @@ status_values = ["current", "stale", "needs_review", "missing"]
 [documents."agents.root"]
 source = "locales/en/AGENTS.md"
 source_locale = "en"
-revision = 15
-translations.ko = { path = "locales/ko/AGENTS.md", source_revision = 15, status = "current" }
+revision = 17
+translations.ko = { path = "locales/ko/AGENTS.md", source_revision = 17, status = "current" }
 translations.zh = { path = "locales/zh/AGENTS.md", source_revision = 11, status = "needs_review" }
 translations.es = { path = "locales/es/AGENTS.md", source_revision = 11, status = "needs_review" }
 translations.fr = { path = "locales/fr/AGENTS.md", source_revision = 11, status = "needs_review" }
@@ -30,8 +30,8 @@ translations.hi = { path = "locales/hi/.mustflow/context/INDEX.md", source_revis
 [documents."context.project"]
 source = "locales/en/.mustflow/context/PROJECT.md"
 source_locale = "en"
-revision = 1
-translations.ko = { path = "locales/ko/.mustflow/context/PROJECT.md", source_revision = 1, status = "current" }
+revision = 3
+translations.ko = { path = "locales/ko/.mustflow/context/PROJECT.md", source_revision = 3, status = "current" }
 translations.zh = { path = "locales/zh/.mustflow/context/PROJECT.md", source_revision = 1, status = "needs_review" }
 translations.es = { path = "locales/es/.mustflow/context/PROJECT.md", source_revision = 1, status = "needs_review" }
 translations.fr = { path = "locales/fr/.mustflow/context/PROJECT.md", source_revision = 1, status = "needs_review" }
@@ -40,8 +40,8 @@ translations.hi = { path = "locales/hi/.mustflow/context/PROJECT.md", source_rev
 [documents."docs.agent-workflow"]
 source = "locales/en/.mustflow/docs/agent-workflow.md"
 source_locale = "en"
-revision = 20
-translations.ko = { path = "locales/ko/.mustflow/docs/agent-workflow.md", source_revision = 20, status = "current" }
+revision = 23
+translations.ko = { path = "locales/ko/.mustflow/docs/agent-workflow.md", source_revision = 23, status = "current" }
 translations.zh = { path = "locales/zh/.mustflow/docs/agent-workflow.md", source_revision = 18, status = "needs_review" }
 translations.es = { path = "locales/es/.mustflow/docs/agent-workflow.md", source_revision = 18, status = "needs_review" }
 translations.fr = { path = "locales/fr/.mustflow/docs/agent-workflow.md", source_revision = 18, status = "needs_review" }
@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 168
+revision = 169
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -122,7 +122,7 @@ translations = {}
 [documents."skill.quality-gaming-guard"]
 source = "locales/en/.mustflow/skills/quality-gaming-guard/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.module-boundary-review"]
@@ -984,7 +984,7 @@ translations = {}
 [documents."skill.llm-token-cost-control-review"]
 source = "locales/en/.mustflow/skills/llm-token-cost-control-review/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.llm-response-latency-review"]

package/templates/default/locales/en/.mustflow/context/PROJECT.md

@@ -3,7 +3,7 @@ mustflow_doc: context.project
 kind: mustflow-context
 locale: en
 canonical: true
-revision: 1
+revision: 3
 name: project
 authority: contextual
 lifecycle: user-editable
@@ -58,9 +58,11 @@ Unset. List paths, public APIs, generated files, migrations, secrets, or compati
 - `.mustflow/docs/agent-workflow.md`  
 - `.mustflow/config/mustflow.toml`  
 - `.mustflow/config/commands.toml`  
-- `.mustflow/skills/INDEX.md`
+- `.mustflow/skills/router.toml`
+- `.mustflow/skills/routes.toml` only when detailed route metadata is needed
+- `.mustflow/skills/INDEX.md` only when human-readable route evidence is needed
 
 ## Staleness Check
 
 - If this file conflicts with current code, tests, command contracts, or user instructions, treat it as stale and report the conflict.  
-- Update this file only when the project direction, non-goals, or repository-wide promises change.
+- Update this file only when the project direction, non-goals, or repository-wide promises change.

package/templates/default/locales/en/.mustflow/docs/agent-workflow.md

@@ -2,7 +2,7 @@
 mustflow_doc: docs.agent-workflow
 locale: en
 canonical: true
-revision: 20
+revision: 23
 lifecycle: mustflow-owned
 authority: workflow-policy
 ---
@@ -31,7 +31,9 @@ mustflow documents have specific, narrow roles. Do not move a rule into a lower-
 | `.mustflow/config/preferences.toml` | Repository-level defaults for style, language, Git suggestions, testing tendency, verification selection, and version-impact handling. | Lower-authority preferences; not permissions. | Repository-local TOML, user-customizable. |
 | `.mustflow/context/INDEX.md` | Router for task-specific context files. | Selects optional context only; not a policy manual. | mustflow-owned Markdown. |
 | `.mustflow/context/PROJECT.md` | Cautious project facts, unknowns, and domain conventions. | Contextual reference below user instructions, code, tests, commands, and configured policies. | User-editable context. |
-| `.mustflow/skills/INDEX.md` | Router that selects which procedure document to read for a task. | Selection contract only; procedure detail remains in `SKILL.md`. | mustflow-owned Markdown. |
+| `.mustflow/skills/router.toml` | Stable compact route taxonomy and fallback rules for prompt-cache-friendly first-pass skill selection. | Selection kernel only; procedure detail remains in `SKILL.md`. | mustflow-owned TOML. |
+| `.mustflow/skills/routes.toml` | Full route metadata for detailed procedure selection when the compact router is insufficient. | Selection hint only; procedure detail remains in `SKILL.md`. | mustflow-owned TOML. |
+| `.mustflow/skills/INDEX.md` | Expanded human-readable route table for detailed skill selection and route maintenance. | Selection contract only; procedure detail remains in `SKILL.md`. | mustflow-owned Markdown. |
 | `.mustflow/skills/<name>/SKILL.md` | Repeatable task procedure with inputs, allowed scope, checks, and reporting format. | Procedure guidance only; cannot authorize commands or override rules. | mustflow-owned Markdown, optionally localized. |
 | `REPO_MAP.md` | Generated anchor map for broad navigation and nested repository entry points. | Generated navigation aid below current files and instructions. | Generated; refresh with the configured `repo_map` intent or `mf map`. |
 
@@ -53,10 +55,12 @@ Skills are task procedures, not autonomous tools. Activating a skill means readi
 
 At task start and before the first edit:
 
-1. Read `.mustflow/skills/INDEX.md`.
-2. Match the current task against the listed scenarios.
-3. Read every matching `SKILL.md` before editing that part of the work.
-4. If no skill applies, proceed with the smallest safe change under `AGENTS.md` and `.mustflow/config/commands.toml`.
+1. Read `.mustflow/skills/router.toml` for the stable route taxonomy, category signals, selection limits, and fallback rules.
+2. Match the current task against category signals, user intent, expected paths, discovered technology, and event signals.
+3. Read `.mustflow/skills/routes.toml` when the compact router is insufficient, the task edits skill routing, detailed route metadata is needed, or route confidence is ambiguous.
+4. Read `.mustflow/skills/INDEX.md` when full route metadata is insufficient, the task edits the expanded route table, or human-readable trigger evidence is needed.
+5. Read every matching `SKILL.md` before editing that part of the work.
+6. If no skill applies, proceed with the smallest safe change under `AGENTS.md` and `.mustflow/config/commands.toml`.
 
 Activate a skill later if new evidence changes the task type. For example, a failing configured command activates failure triage; a test contract change activates test maintenance; and a documentation or workflow change activates documentation update.
 
@@ -82,8 +86,8 @@ Prompt caching is a performance optimization, not an authority source. A cached
 
 Hosts and agent harnesses assembling model input should keep context in this order:
 
-1. Stable prefix: repository rules and workflow files from `mf context --json --cache-profile stable`.
-2. Task context: selected context files, matching skills, repository-map anchors, relevant source files, and `mf search --json` results with `cache_layer` set to `task`.
+1. Stable prefix: repository entrypoint rules and the compact route kernel from `mf context --json --cache-profile stable`.
+2. Task context: selected context files, workflow/configuration refresh slices, command intent definitions, full route metadata fallback, detailed skill index fallback, matching skills, repository-map anchors, relevant source files, and `mf search --json` results with `cache_layer` set to `task`.
 3. Volatile suffix: current user request, changed-file lists, command output tails, latest run receipt metadata, timestamps, and any `mf search --json` result whose `volatile` field is `true`.
 
 Before reusing a stable prefix, compare the reported content hashes with the current files. If any stable document hash changes, reread the document instead of reusing cached text. Do not place absolute local paths, run receipt timestamps, command output, changed files, or current user task text before the stable prefix.
@@ -126,7 +130,7 @@ Use `.mustflow/config/mustflow.toml` `[refresh]` to determine the refresh level:
 - `command`: reread `AGENTS.md` and `.mustflow/config/commands.toml`
 - `edit`: reread `AGENTS.md`, `.mustflow/config/mustflow.toml`, and `.mustflow/docs/agent-workflow.md` before sensitive edits
 - `report`: reread `AGENTS.md`, `.mustflow/config/mustflow.toml`, and `.mustflow/config/preferences.toml` before the final report
-- `skill`: reread `AGENTS.md` and `.mustflow/skills/INDEX.md`
+- `skill`: reread `AGENTS.md` and `.mustflow/skills/router.toml`
 - `full`: reread the full mustflow read sequence
 
 `before_command_run` is a freshness checkpoint for the current command intent, not a requirement to reread every file before every repeated command when the command contract has not changed.

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 168
+revision: 169
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -374,7 +374,7 @@ routes. Event routes stay inactive until their event occurs.
 | Quality metrics, line-count limits, complexity budgets, lint/type/test gates, or assistant-authored changes may be gamed through long-line stuffing, multiple statements per line, new suppressions, test bypass markers, type escapes, placeholder implementations, generated/vendor logic, giant config blobs, dispatch maps, or helper/util/manager/common containers | `.mustflow/skills/quality-gaming-guard/SKILL.md` | User goal, intended quality outcome behind the metric, current diff, quality gates, formatter/lint/type/test rules, generated/vendor policy, helper naming conventions, suppression baseline, and command contract entries | Real responsibility split, removal of gaming patterns, focused tests or quality-gate evidence, bounded `quality_gaming_check` command contract, and directly synchronized docs or templates | cosmetic metric compliance, line stuffing, validation suppression, test bypass, broad type escape, placeholder success, generated/vendor hiding, junk-drawer helper extraction, or legacy baseline confused with new regression | `quality_gaming_check`, `changes_status`, `changes_diff_summary`, `test_related`, `lint`, `build`, `mustflow_check` | Quality goal, gaming patterns inspected, patterns removed or intentionally left, baseline versus new-regression decision, verification, and remaining quality-gaming risk |
 | Prompts, prompt builders, system or developer messages, RAG prompt assembly, few-shot examples, structured outputs, tool-use instructions, model selection, reasoning-effort settings, eval sets, refusal or fallback handling, prompt versioning, or AI feature completion criteria are created, changed, reviewed, or reported | `.mustflow/skills/prompt-contract-quality-review/SKILL.md` | Prompt contract ledger, input ledger, authority ledger, output schema, tool policy, model/runtime ledger, RAG evidence ledger, eval ledger, changed files, and command contract entries | Prompt builders, prompt templates, schemas, validators, eval fixtures, boundary examples, tool policies, fallback states, completion definitions, docs, tests, and directly synchronized templates | prompt-as-function gap, user input treated as authority, buried RAG evidence, happy-path-only examples, JSON-parse theater, unpinned production model, hidden prompt storage, raw chain-of-thought request, guessed tool parameters, missing failure state, unbounded reasoning/token cost, or vibe-based prompt improvement claim | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Prompt contract reviewed, function boundary, authority and source separation, eval and semantic validation status, model/runtime policy, RAG/tool/failure/completion states, verification, and remaining prompt-contract risk |
 | LLM answers, RAG responses, citations, source grounding, claim extraction, evidence IDs, answerability states, abstain behavior, retrieval thresholds, tool-backed facts, output validators, LLM judges, or hallucination-control metrics are created, changed, reviewed, or reported | `.mustflow/skills/llm-hallucination-control-review/SKILL.md` | Answer contract ledger, evidence ledger, claim ledger, tool ledger, validator ledger, eval ledger, observability ledger, changed files, and command contract entries | Answerability states, abstain states, missing-information states, source-coverage gates, claim maps, evidence-ID requirements, citation validators, retrieval thresholds, chunk metadata, tool-parameter ownership, deterministic calculators, domain validators, eval fixtures, tests, docs, route metadata, and directly synchronized templates | unsupported factual claim, fabricated citation, source ID invention, weak retrieval gate, noisy semantic-only retrieval, chunk context loss, summary-on-summary hallucination, guessed tool parameter, model arithmetic, source-priority conflict, LLM judge overtrust, low-temperature theater, missing abstain path, missing dirty eval, false citation metric gap, or unobservable grounding drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Hallucination-control surface reviewed, answerability and abstain states, evidence IDs, claim map, citations, source coverage, validators, retrieval thresholds, tool ownership, evals, metrics, verification, and remaining hallucination-control risk |
-| LLM API calls, prompt assembly, chat history, RAG context, tool schemas, structured output schemas, model routing, reasoning settings, token budgets, provider prompt caching, app-level response caching, retries, batch or flex processing, predicted outputs, image or file inputs, or LLM cost metrics are created, changed, reviewed, or reported | `.mustflow/skills/llm-token-cost-control-review/SKILL.md` | Cost surface ledger, request ledger, cache ledger, context ledger, output ledger, routing ledger, observability ledger, changed files, and command contract entries | Request builders, prompt prefix ordering, canonical serialization, prompt hashes, cache keys, token counters, budget guards, model routers, context trimming, RAG packing, tool and schema payloads, output patch formats, retry repair paths, metrics, logs, tests, docs, route metadata, and directly synchronized templates | prompt-cache prefix drift, volatile field before stable prefix, unmeasured token count, full transcript replay, RAG chunk bloat, oversized tool or JSON schema payload, expensive model default, unbounded reasoning, no visible output after token cap, full-output regeneration, full-context retry replay, app cache key leak, predicted-output cost confusion, image or file token surprise, or per-call cost hiding cost-per-success regression | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | LLM token-cost surface reviewed, cost unit and measurement source, stable prefix and cache behavior, app cache/history/RAG/tool/schema/input choices, routing/reasoning/output/retry/Batch/Flex/prediction choices, observability, verification, and remaining token-cost risk |
+| LLM API calls, prompt assembly, chat history, RAG context, tool schemas, structured output schemas, model routing, reasoning settings, token budgets, provider prompt caching, app-level response caching, retries, batch or flex processing, predicted outputs, image or file inputs, or LLM cost metrics are created, changed, reviewed, or reported | `.mustflow/skills/llm-token-cost-control-review/SKILL.md` | Cost surface ledger, request ledger, cache ledger, context ledger, output ledger, routing ledger, observability ledger, changed files, and command contract entries | Request builders, prompt prefix ordering, canonical serialization, prompt hashes, cache keys, token counters, budget guards, model routers, context trimming, RAG packing, tool and schema payloads, output patch formats, retry repair paths, metrics, logs, tests, docs, route metadata, and directly synchronized templates | prompt-cache prefix drift, volatile field before stable prefix, unmeasured token count, full transcript replay, RAG chunk bloat, oversized tool or JSON schema payload, expensive model default, unbounded reasoning, no visible output after token cap, full-output regeneration, full-context retry replay, app cache key leak, predicted-output cost confusion, image or file token surprise, or per-call cost hiding cost-per-success regression | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `prompt_cache_audit`, `docs_validate_fast`, `test_release`, `mustflow_check` | LLM token-cost surface reviewed, cost unit and measurement source, stable prefix and cache behavior, app cache/history/RAG/tool/schema/input choices, routing/reasoning/output/retry/Batch/Flex/prediction choices, observability, verification, and remaining token-cost risk |
 | LLM response latency, time to first token, first useful output, streaming, output length, LLM round trips, tool-call wait, prompt-cache latency, model routing, speculative or parallel execution, realtime continuation, priority tiers, predicted outputs, or user-perceived AI speed are created, changed, reviewed, or reported | `.mustflow/skills/llm-response-latency-review/SKILL.md` | Latency target ledger, request timeline ledger, call graph ledger, output ledger, cache ledger, routing ledger, observability ledger, changed files, and command contract entries | Streaming paths, first-useful-output contracts, request timeline metrics, call graph simplification, parallel or speculative work, model routers, fallback cascades, output caps, schema shortening, prompt-cache prefix ordering, cache keys, realtime continuation, priority-tier routing, timeout and cancellation behavior, tests, docs, route metadata, and directly synchronized templates | slow first token, useless streamed preamble, extra sequential LLM round trip, tool wait blocking first output, cache-prefix drift, unmeasured cache miss, verbose output drift, long JSON key or enum overhead, RAG chunk bloat, router escalation loop, prediction-token mismatch, priority-tier misuse, unsafe speculative work, missing cancellation, or raw prompt telemetry leak | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | LLM response-latency surface reviewed, latency unit and request timeline, round trips, parallel/tool/stream/cancel behavior, output/schema/cache/history/RAG/routing/fallback/prediction/realtime/priority choices, observability, verification, and remaining response-latency risk |
 | Autonomous or semi-autonomous LLM agents, agentic workflows, planners, executors, verifiers, tool contracts, tool-call gates, human approval or interrupt flows, durable agent state, handoffs, guardrails, loop budgets, retry policies, trace evaluation, or agent outcome metrics are created, changed, reviewed, or reported | `.mustflow/skills/agent-execution-control-review/SKILL.md` | Autonomy ledger, stage gate ledger, role separation ledger, tool contract ledger, effect ledger, state and resume ledger, memory and context ledger, handoff and guardrail ledger, loop, retry, and budget ledger, trace and eval outcome ledger, changed files, and command contract entries | Workflow-versus-agent routing, stage gates, planner/executor/verifier boundaries, tool contracts, tool argument ownership, draft/execute separation, idempotency keys, approval records, durable checkpoints, state schema versions, memory partitions, handoff filters, guardrails, loop budgets, retry classification, trace spans, eval fixtures, tests, docs, route metadata, and directly synchronized templates | unnecessary autonomous agent, one model self-certifying success, ungated bad plan, ambiguous tool contract, guessed tool argument, relative-path trap, external effect before approval, missing idempotency key, interrupt replay side effect, stale state schema, over-shared handoff, misplaced guardrail, repeated tool loop, blind retry, final-answer-only eval, or unsafe trace data | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Agent execution-control surface reviewed, workflow-versus-agent decision, autonomy envelope, stage gates, role separation, tool contracts, approval and side-effect replay safety, state/resume/memory/handoff/guardrail/loop/retry/trace/eval checks, verification, and remaining agent execution-control risk |
 | Agent evaluation loops, trace or trajectory grading, LLM judges, verifier agents, outcome scoring, tool-call prechecks or postchecks, eval datasets, golden or dirty sets, pass@k or pass^k metrics, shadow environments, production-monitoring-to-eval pipelines, or agent regression gates are created, changed, reviewed, or reported | `.mustflow/skills/agent-eval-integrity-review/SKILL.md` | Outcome ledger, trace ledger, oracle ledger, tool-boundary ledger, dataset ledger, metric ledger, environment ledger, monitoring ledger, privacy ledger, changed files, and command contract entries | Outcome oracles, trace schemas, trajectory graders, deterministic checkers, model-judge rubrics, human-review sampling, tool prechecks and postchecks, tool-result evidence packets, eval fixtures, golden and dirty sets, shadow-environment adapters, monitoring-to-eval candidate flows, tests, docs, route metadata, and directly synchronized templates | final-answer-only scoring, LLM judge as sole oracle, reasoning claim treated as evidence, self-reflection certifying success, missing final environment state, ungraded unsafe trajectory, missing tool precheck or postcheck, brittle exact tool-order assertion, uncalibrated judge drift, pass@k masking unreliable pass^k, dirty set gating flakiness, raw trace data leak, or production failure not entering evals | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | Agent eval-integrity surface reviewed, outcome oracle, final-state and trajectory checks, deterministic/model/human oracle split, tool boundary evidence, golden/dirty/capability/regression metrics, shadow environment, monitoring-to-eval loop, trace privacy, verification, and remaining agent eval-integrity risk |

package/templates/default/locales/en/.mustflow/skills/llm-token-cost-control-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.llm-token-cost-control-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: llm-token-cost-control-review
@@ -19,6 +19,7 @@ metadata:
     - build
     - test_related
     - test
+    - prompt_cache_audit
     - docs_validate_fast
     - test_release
     - mustflow_check
@@ -102,7 +103,8 @@ Review LLM cost as a product and systems contract, not as prompt brevity. A cost
 15. Treat predicted outputs as a latency tool unless current provider docs and usage evidence show cost behavior for the exact model and endpoint. Use `llm-response-latency-review` when the main goal is faster completion rather than cost control. Watch rejected prediction tokens or equivalent fields when exposed.
 16. Reduce image and file input before the model. Crop screenshots, downsample where acceptable, extract DOM text or OCR first, and count the actual payload tokens when the provider supports it.
 17. Instrument cost per success. Track endpoint, model, prompt version, tool version, schema version, input tokens, cached tokens, output tokens, reasoning tokens, retry count, validation failure rate, cache hit rate, and successful-task denominator.
-18. Verify with the narrowest configured tests, fixtures, docs validation, release checks, and mustflow validation that cover request assembly, cache keys, budget guards, routing, retry repair, telemetry, and installed skill surfaces.
+18. When prompt-cache layout changes, run the configured prompt-cache audit intent if available and treat byte or token estimates as static layout evidence rather than provider billing proof.
+19. Verify with the narrowest configured tests, fixtures, docs validation, release checks, and mustflow validation that cover request assembly, cache keys, budget guards, routing, retry repair, telemetry, and installed skill surfaces.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -124,6 +126,7 @@ Use configured oneshot command intents when available:
 - `build`
 - `test_related`
 - `test`
+- `prompt_cache_audit`
 - `docs_validate_fast`
 - `test_release`
 - `mustflow_check`

package/templates/default/locales/en/.mustflow/skills/quality-gaming-guard/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.quality-gaming-guard
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: quality-gaming-guard
@@ -29,7 +29,7 @@ metadata:
 
 Prevent agents from satisfying visible quality metrics through cheaper evasions such as line
 stuffing, validation suppressions, placeholder implementations, test bypass markers, broad type
-escapes, junk-drawer helpers, or generated/vendor logic hiding.
+escapes, empty catch swallowing, junk-drawer helpers, or generated/vendor logic hiding.
 
 This skill treats numeric limits as smoke alarms, not as the whole design objective. The target is
 the underlying engineering contract: responsibility separation, readable diffs, meaningful tests,
@@ -42,7 +42,8 @@ preserved validation, and maintainable ownership.
   errors, test coverage, benchmark thresholds, or quality gates.
 - Assistant-authored code could satisfy a visible metric while making maintainability worse.
 - A change adds or touches tests, validators, lint/type suppressions, generated files, vendor files,
-  helper/util/manager/common containers, configuration-as-logic, or placeholder behavior.
+  helper/util/manager/common containers, configuration-as-logic, placeholder behavior, or error
+  swallowing.
 - A repository has a configured `quality_gaming_check` intent or the command contract should expose
   one.
 
@@ -97,7 +98,8 @@ preserved validation, and maintainable ownership.
    - new lint, type, coverage, or formatter suppressions;
    - `.skip`, `.only`, disabled, xfail, or todo test markers;
    - broad `any`, double assertions, or unsafe non-null assertions;
-   - placeholder returns, `not implemented`, `pass`, empty fallbacks, or broad catch swallowing;
+   - placeholder returns, `not implemented`, `pass`, empty fallbacks, empty catch blocks, or broad
+     catch swallowing;
    - logic moved into generated/vendor files, giant config blobs, regex tables, dispatch maps, or
      helper/util/manager/common containers.
 3. When a gaming pattern exists, fix the underlying design rather than only deleting the marker.
@@ -117,8 +119,8 @@ preserved validation, and maintainable ownership.
 ## Postconditions
 
 - The visible metric and the underlying engineering goal are both addressed.
-- No new validation suppression, test bypass, type escape, placeholder, long-line stuffing, or
-  generated/vendor hiding remains without an explicit risk note.
+- No new validation suppression, test bypass, type escape, placeholder, empty catch swallowing,
+  long-line stuffing, or generated/vendor hiding remains without an explicit risk note.
 - Any helper/util/manager/common extraction has a real domain responsibility or is reported as a
   remaining design risk.
 - Quality-gaming check results and skipped verification are visible in the final report.