mustflow 2.58.1 → 2.68.6

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

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 167
+revision: 169
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -371,9 +371,10 @@ routes. Event routes stay inactive until their event occurs.
 | An unfamiliar codebase area needs an evidence-based map before planning, implementation, or reporting | `.mustflow/skills/codebase-orientation/SKILL.md` | User request, target area, relevant instructions, and current source, test, schema, template, configuration, or documentation files | Read-only orientation notes and any smallest follow-up edit chosen from inspected evidence | stale documentation, wrong ownership boundary, or invented architecture claim | `changes_status`, `changes_diff_summary`, `mustflow_check` | Scope inspected, entrypoints, flow map, ownership boundaries, verification options, risks, unknowns, and smallest safe next step |
 | Large-scope code, docs, tests, content, log, data, or refactor work needs cheap-signal candidate selection before reading or editing many files | `.mustflow/skills/heuristic-candidate-selection/SKILL.md` | User goal, target scope, file-role boundaries, cheap signals, exclusions, scoring factors, batch limit, and verification contract | Candidate discovery, scoring, read plan, bounded batch edits, and directly synchronized surfaces | token waste, false positives, generated-file noise, unimportant cleanup, hallucinated source content, oversized diff, or missed high-impact file | `changes_status`, `changes_diff_summary`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Selection goal, excluded surfaces, cheap signals, scored candidates, selected batch, skipped/deferred files, verification, and remaining selection risk |
 | Assistant-authored, AI-generated, vibe-coded, copied, or broad code changes need a hardening pass for symptom-only fixes, pinpoint hardcoding, exact-value branches, same-defect-class sibling inputs or callers, duplicate helpers, duplicate types or shapes, hidden coupling, circular dependencies, re-export discipline, swallowed errors, excessive nesting, god functions or files, edge cases, and behavior-focused tests | `.mustflow/skills/ai-generated-code-hardening/SKILL.md` | User goal, current diff or target files, reported symptom or failing fixture, existing helpers/types/shapes, sibling inputs or callers, import and export paths, public entrypoints or barrels, error-handling conventions, edge/failure cases, tests, and configured command intents | Small hardening fixes, defect-class rule repair, deduplication into existing single source of truth, boundary notes, focused tests, and directly synchronized docs or contracts | symptom-only patch, pinpoint hardcode, exact literal fixture fix, uninspected sibling input, duplicate abstraction, hidden coupling, circular dependency, accidental public API, string-only tests, over-mocking, fallback sprawl, silent error handling, fan-in/fan-out concentration, or broad rewrite | `changes_status`, `changes_diff_summary`, `test_related`, `test_audit`, `lint`, `build`, `docs_validate_fast`, `test_release`, `mustflow_check` | Sources of truth reused or extended, symptom patch and same-class sibling findings, duplicate/coupling/export/error/complexity/test findings, fixes made, deferred enforcement, verification, and remaining hardening risk |
+| 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

@@ -0,0 +1,165 @@
+---
+mustflow_doc: skill.quality-gaming-guard
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: quality-gaming-guard
+description: Apply this skill when quality metrics, line-count limits, complexity budgets, lint/type/test gates, or agent-authored changes may be gamed instead of satisfying the intended engineering goal.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.quality-gaming-guard
+  command_intents:
+    - quality_gaming_check
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - lint
+    - build
+    - mustflow_check
+---
+
+# Quality Gaming Guard
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent agents from satisfying visible quality metrics through cheaper evasions such as line
+stuffing, validation suppressions, placeholder implementations, test bypass markers, broad type
+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,
+preserved validation, and maintainable ownership.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A task mentions line counts, file size, method size, class size, complexity, lint warnings, type
+  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, placeholder behavior, or error
+  swallowing.
+- A repository has a configured `quality_gaming_check` intent or the command contract should expose
+  one.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is documentation-only and does not define or change a quality gate.
+- The task is a normal code review with no quality metric or agent-gaming risk; use the narrower
+  review or language skill.
+- The repository has no observable files, command contract, or diff evidence to inspect.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal and the intended quality outcome behind any numeric metric.
+- Current changed-file list and diff summary.
+- Relevant quality gates, formatter rules, lint/type/test command intents, and command-contract
+  entries.
+- Nearby source, tests, generated/vendor policy, helper naming conventions, and existing
+  suppression baseline.
+- Any failing command output or previous workaround evidence.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- The intended quality goal has been separated from the visible metric.
+- Higher-priority repository instructions and `.mustflow/config/commands.toml` have been checked.
+- Command execution remains governed by configured command intents only.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Refactor code toward real responsibility ownership instead of only reducing line counts.
+- Add or strengthen focused tests that prove the behavior or quality invariant being protected.
+- Remove newly introduced suppressions, broad type escapes, test bypass markers, placeholder
+  implementations, or metric-stuffing shapes when they are in scope.
+- Add or update the bounded `quality_gaming_check` command contract only when the repository can run
+  it as a one-shot, read-only intent.
+- Do not weaken tests, assertions, type checking, lint rules, benchmarks, schema validation, or
+  command gates to make a metric pass.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the real engineering goal behind the visible metric. Examples: separate domain ownership,
+   keep diffs reviewable, preserve validation strength, keep tests meaningful, or make a hot path
+   cheaper.
+2. Inspect the diff for gaming patterns:
+   - long-line stuffing after line-count limits;
+   - multiple statements on one line;
+   - 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, 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.
+   Split by domain responsibility, ownership, input/output boundary, policy owner, or dependency
+   direction.
+4. Prefer formatter, lint, type, test, and architecture evidence that checks multiple dimensions
+   together. Do not rely on one numeric gate as proof of design quality.
+5. For legacy code, distinguish existing baseline from new regression. Existing debt can be reported
+   while new debt should be removed or explicitly justified.
+6. If `quality_gaming_check` is configured, run it after the relevant implementation change. Treat a
+   nonzero result as a real quality-gaming finding unless the specific file is intentionally
+   excluded by current repository policy.
+7. Run the narrowest configured verification intents that cover the changed code, tests, command
+   contract, and public behavior.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The visible metric and the underlying engineering goal are both addressed.
+- 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.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `quality_gaming_check`
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `lint`
+- `build`
+- `mustflow_check`
+
+Use broader configured tests only when the changed behavior or gate is cross-cutting and no narrower
+intent covers it.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If `quality_gaming_check` reports risks, inspect the file and either remove the gaming pattern or
+  report why the repository policy intentionally permits it.
+- If the check is missing, report that the repository has no configured quality-gaming guard instead
+  of inventing a command.
+- If a metric conflicts with the real engineering goal, report the conflict and prefer the stronger
+  maintainability contract over a cosmetic number.
+- If legacy baseline violations are too broad to fix safely, prevent new violations and report the
+  ratchet boundary.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Quality goal behind the metric
+- Gaming patterns inspected
+- Gaming patterns removed, prevented, or intentionally left
+- Baseline versus new-regression decision
+- Command intents run
+- Skipped checks and reasons
+- Remaining quality-gaming risk

package/templates/default/locales/en/.mustflow/skills/router.toml

@@ -0,0 +1,67 @@
+schema_version = "1"
+purpose = "Stable skill-routing kernel for prompt-cache-friendly first-pass selection."
+full_routes = ".mustflow/skills/routes.toml"
+expanded_index = ".mustflow/skills/INDEX.md"
+skill_root = ".mustflow/skills"
+selection_limit = 5
+main_limit = 1
+adjunct_limit = 2
+fallback_policy = "read_full_routes_when_uncertain"
+
+[read_when]
+full_routes = [
+  "router taxonomy is insufficient",
+  "task edits skill routing",
+  "detailed route metadata is needed",
+  "category or confidence is ambiguous",
+]
+expanded_index = [
+  "full route metadata is insufficient",
+  "task edits the expanded route table",
+  "human-readable trigger evidence is needed",
+]
+
+[algorithm]
+steps = [
+  "Classify the task by file paths, user intent, discovered technology, and event signals.",
+  "Pick at most one primary route category and at most two adjunct categories.",
+  "Read full_routes only when this kernel cannot identify a narrow route set.",
+  "Read selected SKILL.md files before editing the matching scope.",
+  "Reroute when changed files, command failures, security, data, tests, docs, or release risk appears.",
+]
+
+[categories.bug_failure]
+label = "Bug and Failure"
+signals = ["command_failure", "failing_test", "repro", "regression", "crash", "error_log"]
+
+[categories.general_code]
+label = "General Code"
+signals = ["code_change", "behavior_change", "public_api_change", "runtime", "performance"]
+
+[categories.tests]
+label = "Tests"
+signals = ["test_change", "regression_guard", "fixture", "snapshot", "coverage"]
+
+[categories.docs_release]
+label = "Documentation and Release"
+signals = ["docs_change", "copy_change", "release_risk", "readme", "changelog"]
+
+[categories.security_privacy]
+label = "Security and Privacy"
+signals = ["security_change", "privacy_change", "auth", "secret", "permission", "exposure"]
+
+[categories.data_external]
+label = "Data and External I/O"
+signals = ["data_change", "migration_change", "database", "filesystem", "process", "dependency"]
+
+[categories.ui_assets]
+label = "UI and Assets"
+signals = ["ui_change", "web_asset_change", "image_asset_change", "layout", "accessibility"]
+
+[categories.architecture_patterns]
+label = "Architecture and Patterns"
+signals = ["cross_cutting_code_change", "refactor", "boundary", "pattern", "module_split"]
+
+[categories.workflow_contracts]
+label = "Workflow and Contracts"
+signals = ["mustflow_config_change", "mustflow_docs_change", "workflow_change", "package_metadata_change"]

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -156,6 +156,12 @@ route_type = "adjunct"
 priority = 74
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change"]
 
+[routes."quality-gaming-guard"]
+category = "general_code"
+route_type = "adjunct"
+priority = 76
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change"]
+
 [routes."module-boundary-review"]
 category = "general_code"
 route_type = "adjunct"

package/templates/default/locales/en/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: en
 canonical: true
-revision: 15
+revision: 17
 lifecycle: user-editable
 authority: binding
 ---
@@ -21,13 +21,17 @@ mustflow-managed details are under `.mustflow/`.
 4. `.mustflow/config/commands.toml`
 5. `.mustflow/config/preferences.toml` if present
 6. `.mustflow/config/technology.toml` if present
-7. `.mustflow/skills/INDEX.md`
+7. `.mustflow/skills/router.toml`
 8. `.mustflow/context/INDEX.md` only when the task needs project, product, domain,
    UI, backend, data, security, or operations context
 9. The matching `.mustflow/context/<name>.md` files, only when selected by the context index
-10. The matching `.mustflow/skills/<name>/SKILL.md`
-11. `REPO_MAP.md` only when broader repository navigation is needed
-12. Relevant source, test, and documentation files
+10. `.mustflow/skills/routes.toml` only when the compact router is insufficient, the task edits
+    skill routing, detailed route metadata is needed, or route confidence is ambiguous
+11. `.mustflow/skills/INDEX.md` only when route metadata is insufficient, the task edits the
+    expanded route table, or human-readable trigger evidence is needed
+12. The matching `.mustflow/skills/<name>/SKILL.md`
+13. `REPO_MAP.md` only when broader repository navigation is needed
+14. Relevant source, test, and documentation files
 
 ## Core Rules
 
@@ -65,8 +69,12 @@ mustflow-managed details are under `.mustflow/`.
 - If `DESIGN.md` exists, read it only for UI, visual design, layout, design-token, or accessibility
   work. Do not create a `DESIGN.md` if one does not exist.
 - Read the matching skill document when one applies to the task.
-- Before creating or modifying any file, use `.mustflow/skills/INDEX.md` to decide whether one or more skills apply.
-  This skill-selection gate is mandatory even for small or seemingly obvious tasks.
+- Before creating or modifying any file, use `.mustflow/skills/router.toml` to decide which route
+  category and skill procedure may apply. Read `.mustflow/skills/routes.toml` only when the compact
+  router is insufficient, the task edits skill routing, detailed route metadata is needed, or route
+  confidence is ambiguous. Read `.mustflow/skills/INDEX.md` only when full route metadata is
+  insufficient, the task edits the expanded route table, or human-readable trigger evidence is
+  needed. This skill-selection gate is mandatory even for small or seemingly obvious tasks.
 - `mf doctor`, `mf check`, and other health checks do not satisfy the skill-selection gate. They
   confirm repository health; they do not determine which task procedure applies.
 - If a matching skill applies, read the matching `SKILL.md` before editing that scope. After

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

@@ -3,7 +3,7 @@ mustflow_doc: context.project
 kind: mustflow-context
 locale: ko
 canonical: false
-revision: 2
+revision: 4
 name: project
 authority: contextual
 lifecycle: user-editable
@@ -58,7 +58,9 @@ source_refs:
 - `.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`
+- 사람이 읽을 라우트 근거가 필요할 때만 `.mustflow/skills/INDEX.md`
 
 ## 오래된 내용 확인
 

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

@@ -2,7 +2,7 @@
 mustflow_doc: docs.agent-workflow
 locale: ko
 canonical: false
-revision: 28
+revision: 31
 lifecycle: mustflow-owned
 authority: workflow-policy
 ---
@@ -44,7 +44,9 @@ mustflow 문서는 각각 명확한 역할을 갖습니다. 단순히 편하게
 | `.mustflow/config/preferences.toml` | 스타일, 언어, Git 제안, 테스트 작성 성향, 검증 선택, 버전 영향의 기본값입니다. | 권한이 아닌 낮은 권위의 선호 설정입니다. | 저장소별로 사용자가 조정할 수 있는 TOML 파일입니다. |
 | `.mustflow/context/INDEX.md` | 작업별 컨텍스트 파일을 선택하는 라우터입니다. | 선택형 컨텍스트만 고르며 정책 설명서는 아닙니다. | mustflow가 소유하는 Markdown 문서입니다. |
 | `.mustflow/context/PROJECT.md` | 신중한 프로젝트 사실, 미지점, 도메인 관습을 기록합니다. | 사용자 지시, 코드, 테스트, 명령 계약, 설정된 정책보다 낮은 권위의 참고 자료입니다. | 사용자가 수정 가능한 컨텍스트 문서입니다. |
-| `.mustflow/skills/INDEX.md` | 작업에 맞는 절차 문서를 선택하는 라우터입니다. | 선택 계약만 담당하며 자세한 절차는 `SKILL.md`에 둡니다. | mustflow가 소유하는 Markdown 문서입니다. |
+| `.mustflow/skills/router.toml` | 프롬프트 캐시에 친화적인 첫 스킬 선택을 위한 안정적인 압축 라우트 범주와 fallback 규칙입니다. | 선택 kernel만 담당하며 자세한 절차는 `SKILL.md`에 둡니다. | mustflow가 소유하는 TOML 파일입니다. |
+| `.mustflow/skills/routes.toml` | 압축 router만으로 부족할 때 사용하는 전체 라우트 메타데이터입니다. | 선택 힌트만 담당하며 자세한 절차는 `SKILL.md`에 둡니다. | mustflow가 소유하는 TOML 파일입니다. |
+| `.mustflow/skills/INDEX.md` | 상세 스킬 선택과 라우트 유지보수를 위한 사람이 읽는 확장 라우트 표입니다. | 선택 계약만 담당하며 자세한 절차는 `SKILL.md`에 둡니다. | mustflow가 소유하는 Markdown 문서입니다. |
 | `.mustflow/skills/<name>/SKILL.md` | 반복 작업의 입력, 허용 범위, 검사, 보고 형식을 담은 절차입니다. | 절차 안내일 뿐이며 명령 실행 권한을 부여하거나 다른 규칙을 덮어쓰지 않습니다. | mustflow가 소유하는 Markdown 문서이며, 필요 시 언어별로 설치됩니다. |
 | `REPO_MAP.md` | 넓은 탐색과 하위 저장소 진입점을 위한 생성 앵커 지도입니다. | 현재 파일과 현재 지시보다 낮은 생성 탐색 보조 자료입니다. | 생성 파일이며 `repo_map` 인텐트 또는 `mf map`으로 갱신합니다. |
 
@@ -68,9 +70,11 @@ mustflow 문서는 각각 명확한 역할을 갖습니다. 단순히 편하게
 3. `.mustflow/config/mustflow.toml`
 4. `.mustflow/config/commands.toml`
 5. `.mustflow/config/preferences.toml`이 있으면 읽기
-6. `.mustflow/skills/INDEX.md`
-7. 현재 작업과 맞는 `.mustflow/skills/<name>/SKILL.md`
-8. 관련 소스, 테스트, 문서 파일
+6. `.mustflow/skills/router.toml`
+7. 압축 router만으로 부족하거나 스킬 라우팅을 수정하거나 상세 라우트 메타데이터가 필요하거나 라우트 확신도가 애매할 때 `.mustflow/skills/routes.toml`
+8. 전체 라우트 메타데이터만으로도 부족하거나 확장 라우트 표를 수정하거나 사람이 읽을 트리거 근거가 필요할 때 `.mustflow/skills/INDEX.md`
+9. 현재 작업과 맞는 `.mustflow/skills/<name>/SKILL.md`
+10. 관련 소스, 테스트, 문서 파일
 
 `REPO_MAP.md`는 넓은 저장소 탐색이 필요할 때만 읽습니다. 이 파일은 전체 파일 목록이 아니라 `AGENTS.md`, `README.md`, `package.json`, `SKILL.md`, 주요 설정 파일 같은 앵커를 찾아 에이전트가 처음 볼 위치를 줄이기 위한 생성 지도입니다. 전체 파일 목록이 필요하면 `git ls-files`나 편집기 파일 탐색기를 사용합니다. `node_modules`, `dist`, `build`, `.git`, 캐시, 대용량 산출물은 제외합니다.
 
@@ -95,10 +99,12 @@ mustflow 문서는 각각 명확한 역할을 갖습니다. 단순히 편하게
 
 작업 시작 시점과 첫 수정 전에는 다음 순서를 따릅니다.
 
-1. `.mustflow/skills/INDEX.md`를 읽습니다.
-2. 현재 사용자 요청과 예상 변경 파일을 색인의 시나리오와 비교합니다.
-3. 맞는 시나리오가 하나 이상 있으면 해당 `SKILL.md`를 읽은 뒤 그 범위를 수정합니다.
-4. 맞는 스킬이 없으면 새 스킬을 추측하지 않고 `AGENTS.md`와 `.mustflow/config/commands.toml`을 기준으로 가장 작은 안전한 변경을 수행합니다.
+1. `.mustflow/skills/router.toml`에서 안정적인 라우트 범주, 범주 신호, 선택 제한, fallback 규칙을 읽습니다.
+2. 현재 사용자 요청, 예상 변경 파일, 발견한 기술 스택, 이벤트 신호를 범주 신호와 비교합니다.
+3. 압축 router만으로 부족하거나 스킬 라우팅을 수정하거나 상세 라우트 메타데이터가 필요하거나 라우트 확신도가 애매하면 `.mustflow/skills/routes.toml`을 읽습니다.
+4. 전체 라우트 메타데이터만으로도 부족하거나 확장 라우트 표를 수정하거나 사람이 읽을 트리거 근거가 필요하면 `.mustflow/skills/INDEX.md`를 읽습니다.
+5. 맞는 시나리오가 하나 이상 있으면 해당 `SKILL.md`를 읽은 뒤 그 범위를 수정합니다.
+6. 맞는 스킬이 없으면 새 스킬을 추측하지 않고 `AGENTS.md`와 `.mustflow/config/commands.toml`을 기준으로 가장 작은 안전한 변경을 수행합니다.
 
 작업 중 새 근거가 생겨 작업 유형이 바뀌면 그때 스킬을 다시 선택합니다. 예를 들어 설정된 명령이 실패하면 실패 원인 추적 스킬을, 테스트 계약이 바뀌면 테스트 유지보수 스킬을, 문서나 워크플로가 바뀌면 문서 수정 스킬을 읽습니다.
 
@@ -160,8 +166,8 @@ mustflow는 LLM 제공자의 입력 캐시 적중을 보장하지 않습니다.
 
 호스트나 에이전트 실행 하네스가 모델 입력을 조립할 때는 다음 순서를 지켜야 합니다.
 
-1. 안정 접두부: `mf context --json --cache-profile stable`에서 얻은 저장소 규칙과 작업 흐름 문서입니다.
-2. 작업 컨텍스트: 선택된 컨텍스트 파일, 맞는 스킬, 저장소 지도 앵커, 관련 소스 파일, 그리고 `cache_layer`가 `task`인 `mf search --json` 결과입니다.
+1. 안정 접두부: `mf context --json --cache-profile stable`에서 얻은 저장소 진입 규칙과 압축 route kernel입니다.
+2. 작업 컨텍스트: 선택된 컨텍스트 파일, 작업 흐름과 구성 refresh 조각, 명령 인텐트 정의, 전체 라우트 메타데이터 fallback, 상세 스킬 색인 fallback, 맞는 스킬, 저장소 지도 앵커, 관련 소스 파일, 그리고 `cache_layer`가 `task`인 `mf search --json` 결과입니다.
 3. 변동 접미부: 현재 사용자 요청, 변경 파일 목록, 명령 출력 끝부분, 최신 실행 기록 메타데이터, 시각 정보, 그리고 `volatile` 값이 `true`인 `mf search --json` 결과입니다.
 
 안정 접두부를 재사용하기 전에는 보고된 콘텐츠 해시를 현재 파일과 비교합니다. 안정 문서의 해시가 하나라도 바뀌면 캐시된 텍스트를 재사용하지 말고 해당 문서를 다시 읽어야 합니다. 절대로 로컬 경로, 실행 기록 시각, 명령 출력, 변경 파일, 현재 사용자 작업 문구는 안정 접두부보다 앞에 두지 않습니다.
@@ -204,7 +210,7 @@ mustflow 지침은 다음 지점에서 다시 확인합니다.
 - `command`: `AGENTS.md`와 `.mustflow/config/commands.toml`을 다시 읽습니다.
 - `edit`: 민감한 수정 전에 `AGENTS.md`, `.mustflow/config/mustflow.toml`, `.mustflow/docs/agent-workflow.md`를 다시 읽습니다.
 - `report`: 최종 보고 전에 `AGENTS.md`, `.mustflow/config/mustflow.toml`, `.mustflow/config/preferences.toml`을 다시 읽습니다.
-- `skill`: `AGENTS.md`와 `.mustflow/skills/INDEX.md`를 다시 읽습니다.
+- `skill`: `AGENTS.md`와 `.mustflow/skills/router.toml`을 다시 읽습니다.
 - `full`: mustflow 필수 읽기 순서 전체를 다시 읽습니다.
 
 `before_command_run`은 현재 명령 인텐트에 대한 최신성 확인 지점입니다. 명령 계약이 바뀌지 않았다면 같은 명령을 반복할 때마다 모든 파일을 다시 읽으라는 뜻이 아닙니다.

package/templates/default/locales/ko/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: ko
 canonical: false
-revision: 22
+revision: 24
 lifecycle: user-editable
 authority: binding
 ---
@@ -21,13 +21,15 @@ mustflow가 관리하는 세부 문서와 설정은 `.mustflow/` 폴더 아래
 4. `.mustflow/config/commands.toml`  
 5. `.mustflow/config/preferences.toml` (있다면)  
 6. `.mustflow/config/technology.toml` (있다면)  
-7. `.mustflow/skills/INDEX.md`  
+7. `.mustflow/skills/router.toml`
 8. 프로젝트, 제품, 도메인, UI, 백엔드, 데이터, 보안, 운영 컨텍스트가 필요한 경우  
    `.mustflow/context/INDEX.md`  
 9. 컨텍스트 색인에서 선택된 `.mustflow/context/<name>.md` 파일  
-10. 현재 작업과 관련된 `.mustflow/skills/<name>/SKILL.md`  
-11. 넓은 저장소 탐색이 필요할 때만 `REPO_MAP.md`  
-12. 관련 소스, 테스트, 문서 파일
+10. 압축 router만으로 판단이 부족하거나 스킬 라우팅을 수정하거나 상세 라우트 메타데이터가 필요하거나 라우트 확신도가 애매한 경우에만 `.mustflow/skills/routes.toml`
+11. 라우트 메타데이터만으로 부족하거나 확장 라우트 표를 수정하거나 사람이 읽을 트리거 근거가 필요한 경우에만 `.mustflow/skills/INDEX.md`
+12. 현재 작업과 관련된 `.mustflow/skills/<name>/SKILL.md`
+13. 넓은 저장소 탐색이 필요할 때만 `REPO_MAP.md`
+14. 관련 소스, 테스트, 문서 파일
 
 ## 핵심 규칙
 
@@ -47,7 +49,7 @@ mustflow가 관리하는 세부 문서와 설정은 `.mustflow/` 폴더 아래
 - `.mustflow/context/` 파일은 프로젝트 방향과 도메인 약속을 설명하는 작업별 컨텍스트입니다. 코드, 테스트, 명령 계약, 사용자 지시를 대신하는 최종 기준으로 보지 않습니다.  
 - `DESIGN.md`가 있으면 UI, 시각 디자인, 레이아웃, 디자인 토큰, 접근성 작업에서만 읽습니다. 없는 `DESIGN.md`를 임의로 생성하지 않습니다.  
 - 작업과 맞는 스킬이 있으면 해당 `SKILL.md`를 읽고 따릅니다.  
-- 파일을 만들거나 수정하기 전에 `.mustflow/skills/INDEX.md`를 기준으로 현재 작업에 적용 가능한 스킬이 하나 이상 있는지 판단합니다. 이 스킬 선택 단계는 작업이 작거나 명백해 보이는 경우에도 반드시 거쳐야 합니다.
+- 파일을 만들거나 수정하기 전에 `.mustflow/skills/router.toml`로 현재 작업에 맞는 라우트 범주와 스킬 절차가 있는지 먼저 판단합니다. 압축 router만으로 부족하거나, 스킬 라우팅을 수정하거나, 상세 라우트 메타데이터가 필요하거나, 라우트 확신도가 애매할 때만 `.mustflow/skills/routes.toml`을 읽습니다. 전체 라우트 메타데이터만으로도 부족하거나, 확장 라우트 표를 수정하거나, 사람이 읽을 트리거 근거가 필요할 때만 `.mustflow/skills/INDEX.md`를 읽습니다. 이 스킬 선택 단계는 작업이 작거나 명백해 보이는 경우에도 반드시 거쳐야 합니다.
 - `mf doctor`, `mf check` 같은 상태 점검 명령은 스킬 선택 단계를 대신하지 않습니다. 이 명령들은 저장소 상태를 확인할 뿐, 현재 작업에 어떤 절차가 필요한지 결정하지 않습니다.
 - 적용되는 스킬이 있으면 해당 범위를 편집하기 전에 맞는 `SKILL.md`를 읽습니다. 파일을 만들거나 수정한 뒤에는 최종 보고에 짧은 스킬 선택 기록을 포함합니다. 사용한 스킬 이름, 설치된 스킬 중 맞는 항목이 없었다는 사실, 또는 색인상 그럴듯한 스킬이 현재 프로필에 설치되어 있지 않다는 누락 중 해당 내용을 밝힙니다.
 - 명령 실패나 문서 변경 등 작업 중 새 근거가 생겨 스킬이 필요해지면, 해당 범위를 계속하기 전에 반드시 맞는 `SKILL.md`를 읽습니다.  

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.58.1"
+version = "2.68.6"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -10,6 +10,7 @@ creates = [
   ".mustflow/context/INDEX.md",
   ".mustflow/context/PROJECT.md",
   ".mustflow/skills/INDEX.md",
+  ".mustflow/skills/router.toml",
   ".mustflow/skills/routes.toml",
   ".mustflow/skills/adapter-boundary/SKILL.md",
   ".mustflow/skills/api-contract-change/SKILL.md",
@@ -23,6 +24,7 @@ creates = [
   ".mustflow/skills/behavior-preserving-refactor/SKILL.md",
   ".mustflow/skills/code-review/SKILL.md",
   ".mustflow/skills/ai-generated-code-hardening/SKILL.md",
+  ".mustflow/skills/quality-gaming-guard/SKILL.md",
   ".mustflow/skills/module-boundary-review/SKILL.md",
   ".mustflow/skills/change-blast-radius-review/SKILL.md",
   ".mustflow/skills/business-rule-leakage-review/SKILL.md",
@@ -211,6 +213,7 @@ minimal = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -339,6 +342,7 @@ patterns = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -478,6 +482,7 @@ oss = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -632,6 +637,7 @@ team = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -772,6 +778,7 @@ product = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",
@@ -918,6 +925,7 @@ library = [
   "behavior-preserving-refactor",
   "code-review",
   "ai-generated-code-hardening",
+  "quality-gaming-guard",
   "module-boundary-review",
   "change-blast-radius-review",
   "business-rule-leakage-review",