mustflow 2.59.0 → 2.69.0

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 = 170
 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"]
@@ -921,12 +921,24 @@ source_locale = "en"
 revision = 3
 translations = {}
 
+[documents."skill.skill-refresh"]
+source = "locales/en/.mustflow/skills/skill-refresh/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.skill-authoring"]
 source = "locales/en/.mustflow/skills/skill-authoring/SKILL.md"
 source_locale = "en"
 revision = 8
 translations = {}
 
+[documents."skill.task-instruction-authoring"]
+source = "locales/en/.mustflow/skills/task-instruction-authoring/SKILL.md"
+source_locale = "en"
+revision = 2
+translations = {}
+
 [documents."skill.template-install-surface-sync"]
 source = "locales/en/.mustflow/skills/template-install-surface-sync/SKILL.md"
 source_locale = "en"
@@ -984,7 +996,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: 170
 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 |
@@ -560,7 +560,9 @@ routes. Event routes stay inactive until their event occurs.
 | GitHub issue, pull request, review thread, or maintainer-facing comment content is drafted, opened, revised, or answered | `.mustflow/skills/github-contribution-quality-gate/SKILL.md` | Target repository, intended GitHub action, repository rules and templates, duplicate search, evidence, verification level, and desired result | Issue, pull request, review reply, or comment draft plus posting gate report | maintainer time waste, duplicate report, unsupported claim, public security leak, unverified AI content, or wrong support channel | `changes_status`, `changes_diff_summary`, `mustflow_check` | Gate decision, repository rules found, duplicate and context check, evidence, missing evidence, draft, and final self-check |
 | Repository, host, user, nested-project, command-contract, preference, or generated instruction sources conflict or make safe scope unclear | `.mustflow/skills/instruction-conflict-scope-check/SKILL.md` | Conflicting instruction sources, affected scope, direct user request, command contract entries, and nearest instruction files | Workflow docs, skills, templates, tests, reports, and selected repository scope | authority drift, unsafe scope expansion, wrong repository edit, or unauthorized command | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Conflicts reviewed, chosen priority rule, narrowed or skipped actions, clarification changes, and remaining authority risk |
 | `.mustflow/context/PROJECT.md` needs cautious project context | `.mustflow/skills/project-context-authoring/SKILL.md` | Supported project facts | `.mustflow/context/PROJECT.md` | authority drift | `mustflow_check` | Updated cautious context |
+| Existing `SKILL.md` files or skill packages are refreshed from stale, external, vendor, runtime, or version-sensitive guidance while preserving the original behavior contract | `.mustflow/skills/skill-refresh/SKILL.md` | Target skill, current behavior contract, runtime mode, source ledger, package ledger, synchronized template surfaces, and command contract entries | Skill body, helper files, route metadata, template copy, locale metadata, profile membership, package tests, and directly tied docs | trigger drift, stale vendor claim, runtime incompatibility, copied external prose, helper-script mismatch, user-edit overwrite, non-idempotent refresh, or template drift | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Skill refreshed, runtime mode, source freshness, semantic change classification, synchronized surfaces, version impact, verification, and remaining route/source/provenance/runtime risk |
 | Skill procedures or routes are created or maintained | `.mustflow/skills/skill-authoring/SKILL.md` | Repeated task evidence | `.mustflow/skills/**` | overlap and command drift | `mustflow_check`, `docs_validate` | Skill route and procedure changes |
+| Work instructions for coding agents, Codex tasks, work orders, issues, PR requests, automations, implementation briefs, reviews, proofs, cleanup tasks, or operational-readiness tasks are drafted, reviewed, or improved | `.mustflow/skills/task-instruction-authoring/SKILL.md` | Target agent surface, task family, goal, scope, constraints, durable rules, risk class, verification expectations, and required output | Instruction artifacts, work-order bodies, issue bodies, templates, docs, skills, checklists, and directly synchronized workflow surfaces | vague goal, delegated product decision, missing acceptance evidence, unsafe raw command, proof theater, review blade drift, overlong one-off policy, or operational-readiness gap | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `mustflow_check` | Instruction family, missing decisions, final instruction or rubric, durable guidance decision, verification expectations, and remaining ambiguity or operational risk |
 
 When introducing a new skill, link it here and define the specific trigger and route fields.
 Avoid including raw shell commands in skill documents; instead, reference the command intent

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`