mustflow 2.75.2 → 2.85.4

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

@@ -24,6 +24,10 @@ allow_project_local_bin_bare_executables = ["mf", "mustflow"]
 description = "Generated mustflow SQLite local index under .mustflow/cache/."
 concurrency = "exclusive_writer"
 
+[resources.documentation_review_queue]
+description = "Repository-local documentation review queue under .mustflow/review/docs.toml."
+concurrency = "exclusive_writer"
+
 [intents.test]
 status = "configured"
 lifecycle = "oneshot"
@@ -219,6 +223,23 @@ reason = "This repository has not declared its fast documentation validation com
 agent_action = "do_not_guess_report_missing"
 required_after = ["docs_change", "copy_change", "i18n_change"]
 
+[intents.docs_review_add_changed]
+status = "configured"
+kind = "mustflow_builtin"
+lifecycle = "oneshot"
+run_policy = "agent_allowed"
+description = "Add changed documentation review candidates from git status to the review queue."
+argv = ["mf", "docs", "review", "add", "--changed"]
+cwd = "."
+timeout_seconds = 120
+stdin = "closed"
+success_exit_codes = [0]
+writes = [".mustflow/review/docs.toml"]
+effects = [{ type = "write", mode = "replace", path = ".mustflow/review/docs.toml", lock = "documentation_review_queue", concurrency = "exclusive" }]
+network = false
+destructive = false
+required_after = ["docs_change", "mustflow_docs_change", "i18n_change", "copy_change"]
+
 [intents.mustflow_doctor]
 status = "configured"
 kind = "mustflow_builtin"

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 174
+revision = 177
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -80,7 +80,7 @@ translations = {}
 [documents."skill.architecture-deepening-review"]
 source = "locales/en/.mustflow/skills/architecture-deepening-review/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.api-contract-change"]
@@ -469,7 +469,7 @@ translations = {}
 [documents."skill.dependency-upgrade-review"]
 source = "locales/en/.mustflow/skills/dependency-upgrade-review/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 5
 translations = {}
 
 [documents."skill.version-freshness-check"]
@@ -517,7 +517,7 @@ translations = {}
 [documents."skill.astro-code-change"]
 source = "locales/en/.mustflow/skills/astro-code-change/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 4
 translations = {}
 
 [documents."skill.auth-permission-change"]
@@ -601,13 +601,13 @@ translations = {}
 [documents."skill.javascript-code-change"]
 source = "locales/en/.mustflow/skills/javascript-code-change/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.node-code-change"]
 source = "locales/en/.mustflow/skills/node-code-change/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.python-code-change"]
@@ -667,7 +667,7 @@ translations = {}
 [documents."skill.typescript-code-change"]
 source = "locales/en/.mustflow/skills/typescript-code-change/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 5
 translations = {}
 
 [documents."skill.unocss-code-change"]
@@ -787,7 +787,7 @@ translations = {}
 [documents."skill.github-contribution-quality-gate"]
 source = "locales/en/.mustflow/skills/github-contribution-quality-gate/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.facade-pattern"]
@@ -918,7 +918,7 @@ translations = {}
 [documents."skill.security-privacy-review"]
 source = "locales/en/.mustflow/skills/security-privacy-review/SKILL.md"
 source_locale = "en"
-revision = 22
+revision = 23
 translations = {}
 
 [documents."skill.security-regression-tests"]
@@ -963,6 +963,12 @@ source_locale = "en"
 revision = 1
 translations = {}
 
+[documents."skill.cross-agent-session-reference"]
+source = "locales/en/.mustflow/skills/cross-agent-session-reference/SKILL.md"
+source_locale = "en"
+revision = 2
+translations = {}
+
 [documents."skill.secret-exposure-response"]
 source = "locales/en/.mustflow/skills/secret-exposure-response/SKILL.md"
 source_locale = "en"
@@ -981,6 +987,12 @@ source_locale = "en"
 revision = 5
 translations = {}
 
+[documents."skill.test-suite-performance-review"]
+source = "locales/en/.mustflow/skills/test-suite-performance-review/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.vertical-slice-tdd"]
 source = "locales/en/.mustflow/skills/vertical-slice-tdd/SKILL.md"
 source_locale = "en"

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

@@ -247,7 +247,7 @@ Use existing project style. If style is unclear, apply the defaults in `.mustflo
 
 ## Documentation Review Queue
 
-When an agent creates or modifies user-facing, workflow, template, context, or skill documentation, record the touched document with `mf docs review add <path>` unless the user explicitly says not to track it. The queue is stored in `.mustflow/review/docs.toml` and is created only when needed.
+When an agent creates or modifies user-facing, workflow, template, context, or skill documentation, record the touched document with `mf docs review add <path>` unless the user explicitly says not to track it. When the command contract exposes a configured `docs_review_add_changed` intent, agents may use it to run `mf docs review add --changed` and queue every changed documentation candidate from `git status` in one bounded step. The queue is stored in `.mustflow/review/docs.toml` and is created only when needed.
 
 Review completion may come from a human, an LLM, a tool, or an external process. Record only the broad reviewer kind plus free-form identifiers such as reviewer ID, provider, model, command intent, and summary. Do not maintain a fixed list of specific LLM products.
 

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

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 174
+revision: 177
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -212,6 +212,10 @@ refer to `AGENTS.md` and `.mustflow/config/commands.toml` to implement the most
   inputs, direct time or randomness, direct I/O, constructor side effects, static or singleton
   state, mock-heavy tests, sleeps, framework magic, reflection-only tests, or other code shapes
   that make important conditions hard to force in tests.
+- Use `test-suite-performance-review` as a primary route when test-suite runtime, CI feedback
+  latency, selected-test execution, shard balance, worker scheduling, fixture or database setup,
+  retry policy, flaky-test handling, result caching, discovery, coverage, or artifact overhead
+  needs optimization without weakening verification.
 - Use `quadratic-scan-review` as an adjunct when the suspected performance smell is specifically
   hidden O(N^2) work from repeated scans, membership checks, code joins, helper-body lookups,
   render-time lookup, resolver fan-out, repeated sort, or copy accumulation over growing data.
@@ -447,6 +451,7 @@ routes. Event routes stay inactive until their event occurs.
 | User requirements, acceptance criteria, issue reports, bug reports, product notes, compatibility promises, or examples must be preserved as regression coverage before or during implementation | `.mustflow/skills/requirement-regression-guard/SKILL.md` | Requirement source, observable behavior, existing tests or fixtures, implementation scope, changed files, and command contract entries | Focused tests, fixtures, examples, schemas, docs, and implementation changes directly tied to the requirement | untested requirement, invented acceptance criteria, weakened tests, hidden behavior drift, or unverifiable implementation claim | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `test_audit`, `docs_validate_fast`, `test_release`, `mustflow_check` | Requirement sources, coverage map, guards added or reused, implementation changes, deferred requirements, verification, and remaining regression risk |
 | The user explicitly requests TDD, test-first work, red-green-refactor, RED/GREEN, or one observable behavior slice at a time | `.mustflow/skills/vertical-slice-tdd/SKILL.md` | TDD trigger, first behavior contract, existing tests, expected RED category, baseline status, and command contract entries | One focused test or fixture, the smallest implementation for the current slice, and directly synchronized docs when needed | invalid RED, broad slice, premature refactor, unrelated cleanup, or verification claim without configured command evidence | `changes_status`, `changes_diff_summary`, `test_related`, `test_audit`, `test`, `lint`, `build`, `mustflow_check` | Slice scope, existing coverage, RED category evidence, GREEN verification, refactors after GREEN, deferred slices, and remaining TDD risk |
 | New tests or test cases are designed, TDD RED or GREEN evidence is reported, or test-case choices are made for requirements, bugs, refactors, security boundaries, schemas, templates, or public docs | `.mustflow/skills/test-design-guard/SKILL.md` | Contract source, existing coverage, intended RED evidence, candidate cases, baseline status, and command contract entries | Tests, fixtures, helpers, and directly synchronized contract docs | invalid RED, happy-path-only coverage, speculative edge cases, weak assertions, mock-only confidence, or implementation-detail coupling | `test_related`, `test_audit`, `test`, `lint`, `build`, `test_release`, `mustflow_check` | RED category, selected test shape, evidence-backed cases, rejected speculation, verification objective, commands, and remaining test-design risk |
+| Test-suite runtime, CI feedback latency, test selection, shard balance, worker scheduling, retry policy, flaky-test handling, fixture setup, database or container test lifecycle, coverage or artifact overhead, test-result caching, test discovery, or test performance claims are planned, edited, reviewed, or reported | `.mustflow/skills/test-suite-performance-review/SKILL.md` | Suite surface, timing ledger, p50 and p95 evidence, selection ledger, isolation ledger, resource ledger, cache ledger, and command contract entries | Test timing collection, selected-test manifests, dependency-to-test maps, shard and worker scheduling, fixture lifecycle, DB/container setup, fake timers, stubs, cache keys, coverage defaults, CI reports, docs, and directly synchronized templates | faster-but-weaker verification, selector without full fallback, import-only impact analysis, cache false hit, volatile cache key, cold-cache theater, full discovery scan, per-test process startup, file-count sharding, idle workers, resource contention, shared DB schema, fixed sleeps, external internet dependency, hidden time/random/locale input, artifact tax, retry hiding real failure, or permanent flaky quarantine | `changes_status`, `changes_diff_summary`, `build`, `test_related`, `test`, `test_audit`, `docs_validate_fast`, `test_release`, `mustflow_check` | Suite surface, feedback goal, timing bottleneck, selection and fallback policy, scheduling and resource-token decisions, fixture and isolation notes, cache and retry policy, artifact policy, speed evidence, verification, and remaining test-suite performance risk |
 | Tests are added, updated, removed, or audited | `.mustflow/skills/test-maintenance/SKILL.md` | Changed behavior or stale-test evidence | Test files and related source | contract drift | `test`, `test_related`, `test_audit`, `snapshot_update`, `lint`, `build` | Test rationale and verification |
 
 ### Documentation and Release
@@ -522,7 +527,7 @@ routes. Event routes stay inactive until their event occurs.
 | Tailwind classes, class composition, theme tokens, variants, arbitrary values, Tailwind config, `@theme`, `@apply`, or migration surfaces are created or changed | `.mustflow/skills/tailwind-code-change/SKILL.md` | Tailwind config or CSS entry, source scanning rules, theme tokens, class helpers, changed files, and command contract entries | Tailwind config, theme tokens, utility classes, component class maps, tests, and docs examples | production class loss, arbitrary-value sprawl, token bypass, weak focus state, or hidden `@apply` drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Class detection, token, responsive, state, and production CSS boundary checked, verification, and remaining Tailwind risk |
 | UnoCSS config, presets, extraction, shortcuts, rules, variants, safelist, blocklist, attributify, transformers, or utility usage are created or changed | `.mustflow/skills/unocss-code-change/SKILL.md` | UnoCSS config, presets, extraction rules, shortcuts, safelist, blocklist, changed files, and command contract entries | UnoCSS config, utility usage, rules, shortcuts, safelist, blocklist, tests, and docs examples | extractor miss, runtime-only utility, safelist explosion, unbounded shortcut, or production CSS loss | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Extraction, safelist, shortcut, variant, and production CSS boundary checked, verification, and remaining UnoCSS risk |
 | Flutter widgets, screens, routing, state management, async UI, platform channels, assets, responsive layout, accessibility, or Flutter tests are created or changed | `.mustflow/skills/flutter-code-change/SKILL.md` | App root, route config, widget tree, state owner, platform files, assets, changed files, and command contract entries | Flutter widgets, routes, state, platform channels, assets, tests, and docs examples | impure build, lifecycle leak, navigation drift, layout breakage, inaccessible UI, or platform boundary drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | State, lifecycle, layout, accessibility, platform, and asset boundary checked, verification, and remaining Flutter risk |
-| Astro config, pages, layouts, components, islands, hydration directives, content collections, routes, adapters, MDX, or Astro build behavior are created or changed | `.mustflow/skills/astro-code-change/SKILL.md` | Astro config, route tree, layouts, content schema, components, adapter config, changed files, and command contract entries | Astro pages, layouts, islands, content collections, adapters, tests, and docs examples | unnecessary hydration, build/runtime data mix, route URL drift, content schema drift, or adapter mismatch | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Build/runtime, route, content, hydration, and adapter boundary checked, verification, and remaining Astro risk |
+| Astro config, package metadata, pages, layouts, components, islands, hydration directives, content collections, routes, adapters, request pipeline, `src/fetch.*`, route cache, MDX, Markdown processing, migration, or Astro build behavior are created or changed | `.mustflow/skills/astro-code-change/SKILL.md` | Astro config, current and target Astro version when migrating, route tree, request pipeline, cache rules, Markdown processor, layouts, content schema, components, adapter config, changed files, and command contract entries | Astro pages, layouts, islands, content collections, adapters, request pipeline, route cache, Markdown, tests, and docs examples | unnecessary hydration, build/runtime data mix, route URL drift, request pipeline omission, cache data exposure, Markdown drift, content schema drift, or adapter mismatch | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Build/runtime, route, request pipeline, cache, Markdown, content, hydration, and adapter boundary checked, verification, and remaining Astro risk |
 | Svelte or SvelteKit components, routes, load functions, server actions, stores, runes, SSR boundaries, accessibility warnings, or tests are created or changed | `.mustflow/skills/svelte-code-change/SKILL.md` | Svelte config, route segment files, stores/runes, hooks, app types, changed files, and command contract entries | Svelte components, routes, load/actions, stores, SSR/client boundaries, tests, and docs examples | SSR/client leakage, browser global crash, state owner drift, form degradation, or ignored accessibility warning | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | SSR, server/client, state, form, and accessibility boundary checked, verification, and remaining Svelte risk |
 | Web image assets are added, converted, resized, or replaced | `.mustflow/skills/web-asset-optimization/SKILL.md` | Image asset request and target path | Web image assets | asset quality and size | `asset_optimize`, `build` | Optimized asset notes |
 
@@ -553,6 +558,7 @@ routes. Event routes stay inactive until their event occurs.
 | Current repository evidence reveals a scope-adjacent bug, missing test, stale synchronized surface, public-contract drift, security or privacy exposure, data-loss risk, brittle error handling, concurrency risk, operational risk, or UX inconsistency outside the literal request | `.mustflow/skills/proactive-risk-surfacing/SKILL.md` | Literal user request, current evidence, risk relationship, severity, expected edit size, authority boundary, and verification options | Fix-or-report decision, small related fixes, focused tests or synchronized surfaces, and final proactive risk notes | scope creep, speculative cleanup, hidden broad refactor, ignored high-severity risk, or false completion claim | `changes_status`, `changes_diff_summary`, `test_related`, `docs_validate_fast`, `test_release`, `mustflow_check` | Candidate decisions: fix now, report only, ask first, or ignore; files changed, verification, and remaining proactive risks |
 | A final report or completion claim needs current evidence for changed files, requirements, command receipts, skipped checks, synchronized surfaces, or remaining risks | `.mustflow/skills/completion-evidence-gate/SKILL.md` | User goal, changed-file evidence, skills used, verification results, skipped checks, synchronized surfaces, and remaining risks | Final report evidence and the smallest missing in-scope evidence surface only | false completion, stale receipts, hidden skipped checks, unsupported readiness claim, or contract drift | `changes_status`, `changes_diff_summary`, `test_related`, `test`, `test_audit`, `lint`, `build`, `docs_validate_fast`, `docs_validate`, `test_release`, `mustflow_check` | Completion status, requirement evidence map, changed and synchronized surfaces, commands run, skipped checks, and final wording boundary |
 | A task is incomplete, blocked, paused, resumed, handed off, context-compacted, or needs bounded restart evidence without storing raw logs, secrets, hidden reasoning, transcripts, or authority-changing summaries | `.mustflow/skills/restricted-handoff-resume/SKILL.md` | Current goal, latest controlling instruction, changed files, command intents run or skipped, verification evidence, blocker or next safe action, and handoff or retention policy | Final report handoff evidence or explicitly configured handoff surface only | stale summary treated as authority, hidden reasoning leak, secret leak, raw log storage, unrelated work history, or missing restart point | `changes_status`, `changes_diff_summary`, `mustflow_check` | Task status, files touched, commands run/skipped, stale-summary check, next safe action or blocker, excluded raw content, and remaining resume risk |
+| A Codex or Hermes local session ID needs read-only reference for task evidence, restart context, failure diagnosis, or continuation planning across agent applications | `.mustflow/skills/cross-agent-session-reference/SKILL.md` | Session ID, source app evidence, current repository root, user goal, redaction requirements, available official session tools or read-only local storage evidence | Bounded session evidence summaries, continuation prompts, current-repository follow-up work, and directly synchronized reports only | foreign session mutation, transcript-as-authority drift, secret exposure, unrelated history dump, stale storage schema, or dispatching work into another app | `changes_status`, `changes_diff_summary`, `mustflow_check` | Source application confidence, read-only access method, extracted evidence, redactions, current verification, next safe action or ambiguity, and remaining stale-session or privacy risk |
 | Declared behavior must stay aligned across code, schemas, templates, tests, and docs | `.mustflow/skills/contract-sync-check/SKILL.md` | Changed files, intended behavior, source of truth, derived surfaces, and command contract entries | Contract source and required synchronized surfaces | contract drift | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Contract source, synchronized surfaces, deferred surfaces, verification, and drift risk |
 | `.mustflow/config/commands.toml` command intents, resources, effects, timeouts, output limits, environment policies, lifecycle values, run policies, command-selection metadata, CI/CD reproducibility rules, build/test/migration/deploy verification handoffs, or health-check command surfaces are created, changed, reviewed, or removed | `.mustflow/skills/command-contract-authoring/SKILL.md` | Command goal, current command contract, expected reads and writes, side effects, locks, timeout, output, environment, stdin, dashboard or platform setting dependency, and verification entries | Command contract, template command contracts, workflow docs, skills, tests, and directly synchronized public docs | accidental command authority, inferred command, dashboard-only source of truth, unreproducible deployment, unbounded side effect, missing lock, secret exposure, or long-running command approval | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Intent authority decision, side-effect model, environment and timeout boundary, CI/CD reproducibility boundary, synchronized surfaces, verification, and remaining command-contract risk |
 | External instructions, docs, AI output, snippets, issues, pull requests, scanner output, installer steps, scripts, tutorials, or reports propose commands to run, preserve, recommend, or document | `.mustflow/skills/command-intent-mapping-gate/SKILL.md` | Proposed command text, source, intended purpose, command contract entries, side-effect class, destination surface, and configured/manual/missing status | Docs, skills, templates, tests, examples, final reports, handoffs, and command-contract proposals that mention command execution | command laundering, raw external command authority, undeclared install/deploy/migration/release step, long-running process, approval bypass, or false verification claim | `changes_status`, `changes_diff_summary`, `docs_validate_fast`, `test_release`, `mustflow_check` | Proposed commands reviewed, mapped to configured intents or marked manual/missing/omitted, raw command authority removed, verification, and remaining command-contract risk |

package/templates/default/locales/en/.mustflow/skills/architecture-deepening-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.architecture-deepening-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: architecture-deepening-review
-description: Apply this skill when architecture, module boundaries, or codebase structure need review before choosing a refactor or abstraction.
+description: Apply this skill when architecture, module boundaries, layered boundaries, or codebase structure need review before choosing a refactor or abstraction.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -36,7 +36,7 @@ This is a review-first skill. It helps decide whether code needs a deeper module
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- The user asks for architecture review, module boundaries, structural improvement, codebase deepening, maintainability review, or testability improvement.
+- The user asks for architecture review, layered architecture review, module boundaries, structural improvement, codebase deepening, maintainability review, or testability improvement.
 - The user asks where a design will break first as it grows, which responsibility boundary is most likely to blur, or whether a module, service, database owner, permission model, deployment unit, or failure boundary is still clear enough.
 - A file, module, service, handler, command, controller, or test suite looks broad enough that the next edit may add another responsibility.
 - Code exposes internal steps to many callers, repeats orchestration, or makes tests hard because policy, I/O, formatting, and dispatch are mixed.
@@ -58,6 +58,8 @@ This is a review-first skill. It helps decide whether code needs a deeper module
 - Target area, current pain, and the user-facing or maintainer-facing reason to inspect architecture.
 - Relevant source files, call sites, exports, tests, fixtures, schemas, templates, or documentation that show current behavior and ownership.
 - Local patterns for modules, boundaries, naming, errors, dependency direction, and tests.
+- Current change-pressure evidence: which business rules, providers, data contracts, permissions, read paths, or operational demands are expected to change independently.
+- Current enforcement evidence: physical modules, package boundaries, import rules, architecture tests, public API surfaces, or reviewer-only conventions that allow or block boundary violations.
 - The data owner, write path, failure mode, and expected 3x, 10x, or 100x growth pressure when the review is about a design rather than only a file split.
 - Current changed-file list when the worktree is already dirty.
 - Relevant command-intent contract entries for verification.
@@ -87,39 +89,51 @@ This is a review-first skill. It helps decide whether code needs a deeper module
 2. Inspect local evidence before judging.
    - Read imports, exports, public functions, call sites, related tests, and nearby module conventions.
    - Prefer evidence from current code and tests over generic architecture advice.
-3. Identify one to three candidate boundaries.
+3. Reject layer theater before proposing deeper structure.
+   - Do not treat `controller`, `service`, `repository`, `domain`, `infra`, or similar folder names
+     as architecture evidence by themselves.
+   - Check whether one business change forces edits across many technical folders. If yes, rank the
+     feature or capability boundary before adding another technical layer.
+   - Check whether dependency direction is enforced by modules, packages, import rules, architecture
+     tests, or build boundaries. Reviewer memory is weak evidence.
+   - Treat caller-owned ports, narrow use-case interfaces, adapter mappings, and explicit public
+     module surfaces as stronger boundary evidence than broad infrastructure-owned interfaces.
+   - Mark pass-through services, table-shaped repositories, generic CRUD bases, and `common`,
+     `shared`, or `utils` growth as smells unless they hide real policy, translation, transaction,
+     test, or provider complexity.
+4. Identify one to three candidate boundaries.
    - Each candidate must name the responsibility it would hide or clarify.
    - Reject candidates that only rename, wrap, or move code without lowering caller complexity or test cost.
-4. Force the design through the ownership and failure questions before scoring.
+5. Force the design through the ownership and failure questions before scoring.
    - Name the first likely mixed-responsibility boundary. Common early failures are business rules leaking into controllers, repositories, external adapters, UI components, or framework-specific handlers.
    - Name the final owner for important data. The owner is the module that protects the invariant, not necessarily the module that reads the value most often.
    - Separate original state from cache, search index, analytics, summary, AI output, provider response, or other derived state.
    - Identify every direct write path for high-impact fields such as status, role, permission, balance, quota, plan, entitlement, deleted state, payment state, or ownership.
    - Ask whether a failure creates a visible failure state or silently creates false success. High-impact paths such as authorization, payment, entitlement, deletion, and destructive administration should fail closed.
    - Ask whether duplicate requests, retries, webhook redelivery, queue replay, or worker restart can repeat a harmful effect. If yes, require an idempotency, ledger, outbox, or reconciliation boundary before calling the design safe.
-5. Check growth pressure in concrete stages.
+6. Check growth pressure in concrete stages.
    - At 3x scale, look first for implementation-quality failures: missing indexes, N+1 reads, large responses, synchronous file or image work, repeated external calls, and insufficient connection pools.
    - At 10x scale, look first for ownership and state failures: write hot spots, queue delay, cache invalidation, server-local files, scattered permission rules, external API rate limits, and deployment units that change for unrelated reasons.
    - At 100x scale, look first for partitioning and operational failures: data split boundaries, tenant or region hot spots, retry storms, external dependency isolation, long deploy recovery, missing observability, and manual-only recovery paths.
-6. Check scaling direction without forcing premature distribution.
+7. Check scaling direction without forcing premature distribution.
    - A small team may start with one larger server or a simple server set, but request handlers should not depend on process memory, local uploads, duplicate cron execution, in-transaction external calls, or server-specific job state.
    - Application servers should be able to become stateless. Databases may start with vertical scaling, but the design should not block read replicas, read models, queue-backed work, or future data partitioning.
    - Horizontal scaling is only real if any server can handle the same request, workers can safely duplicate or retry work, and database writes do not all converge on an uncontrolled hot spot.
-7. Score each candidate from 1 to 9.
+8. Score each candidate from 1 to 9.
    - User value: whether the structure protects a user-visible or public contract.
    - Maintenance value: whether future changes become smaller or less error-prone.
    - Blast radius: how many callers, files, schemas, templates, or docs would change.
    - Testability: whether behavior can be proven with existing or focused tests.
    - Reversibility: whether the change can be undone without a public migration.
    - Evidence confidence: whether the diagnosis is supported by local code, tests, or repeated change patterns.
-5. Choose the next action.
+9. Choose the next action.
    - Recommend one smallest structural move, or explicitly stop at analysis-only when the evidence is not strong enough.
    - If implementation proceeds, use the narrower matching skill before editing that boundary.
-6. Keep the structure move shallow-to-deep.
+10. Keep the structure move shallow-to-deep.
    - Start with caller simplification, naming, and responsibility boundaries.
    - Then extract a focused facade, policy, strategy, pure core, adapter, result type, or dependency boundary only when it clearly removes real complexity.
    - Avoid turning a broad file into many vague files with the same responsibilities.
-7. Verify and report.
+11. Verify and report.
    - Run the narrowest configured command intents that cover the changed surface.
    - Report skipped checks, unknown behavior evidence, and any candidate intentionally deferred.
 
@@ -128,6 +142,8 @@ This is a review-first skill. It helps decide whether code needs a deeper module
 
 - The output contains a ranked architecture candidate list or one scoped structural change.
 - Any chosen change has a named reason tied to lower change cost, lower defect risk, or better testability.
+- Layered-architecture claims are backed by change-pressure, dependency-direction, public-surface,
+  and enforcement evidence rather than folder names alone.
 - Important data has a named owner, write path, original-or-derived classification, and failure behavior when the reviewed design touches durable state.
 - Growth pressure is either checked at 3x, 10x, and 100x or explicitly marked not relevant to the current architecture decision.
 - Behavior changes are excluded or explicitly moved to a separate follow-up.
@@ -164,6 +180,7 @@ Use documentation and release checks only when the review or chosen change touch
 
 - Review target and current pain
 - Evidence inspected
+- Layering, change-pressure, and boundary-enforcement evidence
 - Data owner, write path, and original-versus-derived state when relevant
 - Failure mode, idempotency, and recovery boundary when relevant
 - 3x, 10x, and 100x growth pressure when relevant

package/templates/default/locales/en/.mustflow/skills/astro-code-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.astro-code-change
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: astro-code-change
-description: Apply this skill when Astro config, pages, layouts, components, islands, hydration directives, content collections, dynamic routes, adapters, MDX, RSS, sitemap, canonical URL, draft, pagination, or build behavior are created or changed.
+description: Apply this skill when Astro config, package metadata, pages, layouts, components, islands, hydration directives, content collections, dynamic routes, adapters, request pipeline, advanced routing, route cache, MDX, Markdown processing, RSS, sitemap, canonical URL, draft, pagination, migration, or build behavior are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -28,15 +28,15 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Preserve Astro's static-first model, island hydration boundary, routing contract, content collection schema, canonical URL, RSS, sitemap, adapter, and client bundle boundaries.
+Preserve Astro's static-first model, island hydration boundary, routing contract, request pipeline, content collection schema, canonical URL, RSS, sitemap, adapter, cache, and client bundle boundaries.
 
 The default is no-hydration. Add browser JavaScript only after proving that native HTML, CSS, standard links, forms, details/summary, or a small `.astro` script cannot provide the required behavior.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- `astro.config.*`, `src/pages`, `.astro`, content config, live config, collections, layouts, components, MDX, routes, endpoints, adapters, integrations, islands, or hydration directives change.
-- The task adds or changes a page, blog/docs content, interactive UI, SSR/on-demand rendering, framework component, search/filter UI, route behavior, RSS feed, sitemap, canonical URL, draft handling, or pagination.
+- `astro.config.*`, package metadata, `src/pages`, `src/fetch.*`, `.astro`, content config, live config, collections, layouts, components, MDX, Markdown processor config, routes, endpoints, adapters, integrations, islands, route cache, or hydration directives change.
+- The task adds or changes a page, blog/docs content, interactive UI, SSR/on-demand rendering, framework component, search/filter UI, request pipeline behavior, route behavior, RSS feed, sitemap, canonical URL, draft handling, migration, or pagination.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -47,20 +47,23 @@ The default is no-hydration. Add browser JavaScript only after proving that nati
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
 
-- Package metadata, Astro version, framework integrations, TypeScript config, pages, layouts, components, content config, content files, integrations, adapter config, env declarations, public assets, and tests.
-- Astro config values that affect routing and URLs: `site`, `base`, `trailingSlash`, `output`, `adapter`, sitemap integration, MDX integration, and framework integrations.
+- Package metadata, current Astro version, target Astro version when migration is intended, framework integrations, TypeScript config, pages, layouts, components, content config, content files, integrations, adapter config, env declarations, public assets, and tests.
+- Astro config values that affect routing, URLs, rendering, request handling, Markdown, and cache: `site`, `base`, `trailingSlash`, `output`, `adapter`, `fetchFile`, `markdown`, `compressHTML`, `cache`, `routeRules`, sitemap integration, MDX integration, and framework integrations.
 - Content collection names, loader bases, schemas, slug/id policy, draft fields, date fields, canonical fields, and route files that turn collection entries into pages.
-- Current output mode, prerender/SSR policy, hydration conventions, route priority, endpoint layout, RSS generation, sitemap generation, and content schema.
+- Current output mode, prerender/SSR policy, hydration conventions, route priority, endpoint layout, request pipeline or middleware layout, RSS generation, sitemap generation, and content schema.
+- Markdown processor decision, remark/rehype/recma plugins, custom Markdown imports, heading id policy, syntax-highlighting expectations, and Markdown or MDX snapshots when content rendering changes.
+- Cache provider, route cache rules, cache-key inputs, invalidation path, deployment topology, and authenticated or personalized routes when `cache` or `routeRules` change.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
 
 - Read Astro config, content config, and the affected route tree before changing routing, content, canonical, RSS, sitemap, or hydration behavior.
-- Identify the Astro major version before applying migration rules. Astro v6 changes must be checked against the v6 upgrade guide instead of inferred from older routing or adapter habits.
+- Identify current and target Astro major versions before applying migration rules. Apply only the official major upgrade guide deltas crossed by the change, and keep ordinary Astro edits on the version-neutral policies below.
 - Identify build-time versus request-time data before adding data access.
 - Identify which UI truly needs browser JavaScript and which UI truly needs framework state before adding a framework island.
 - Treat file movement under `src/pages`, route parameter changes, and content slug changes as URL contract changes.
+- Treat `src/fetch.ts` and `src/fetch.js` as reserved advanced-routing entrypoint candidates unless `fetchFile` disables or moves that entrypoint.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -73,18 +76,23 @@ The default is no-hydration. Add browser JavaScript only after proving that nati
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Read package metadata and Astro config first. Record Astro version, framework integrations, `site`, `base`, `trailingSlash`, `output`, adapter, sitemap integration, MDX integration, and any framework integration.
-   - For Astro v6 migrations, check removed or changed surfaces before editing call sites: `Astro.glob()` replacement with `import.meta.glob()` or content collections, `.cjs` and `.cts` config removal, `astro:ssr-manifest`, `RouteData.generate()`, old adapter hooks, old `NodeApp` paths, Zod 4 schema effects, and numeric dynamic route params.
-2. Read `src/content.config.*` when content, docs, blog, RSS, sitemap, canonical, or route generation is involved. Record each collection name, loader base, schema fields, slug/id policy, draft field, and date fields.
-3. Build a route ledger from `src/pages`: static pages, dynamic pages, rest routes, endpoints, prerendered routes, on-demand routes, and possible route-priority collisions.
-4. Classify the change: static route, dynamic route, endpoint, content collection, integration, adapter, SSR/on-demand, island, script, asset, RSS, sitemap, canonical, or docs/content.
-5. Apply the hydration policy below before adding or changing any `client:*` directive.
-6. Apply the routing and rendering policy below before adding dynamic routes, catch-all routes, endpoints, adapter changes, or `prerender` changes.
-7. Apply the content, SEO, and feed policy below before changing frontmatter, schemas, slugs, drafts, canonical URLs, pagination, RSS, or sitemap behavior.
-8. Do not put runtime-only data such as logged-in user state, request-local data, private API responses, or live inventory into build-time collections.
-9. Do not enable request-time rendering without the adapter and deployment contract that support it.
-10. Keep `set:html` or raw HTML injection behind a trusted and sanitized content boundary.
-11. Choose configured verification intents that cover content schema, build, routes, hydration, adapter/runtime, and bundle risk when available.
+1. Read package metadata and Astro config first. Record current and target Astro versions, framework integrations, `site`, `base`, `trailingSlash`, `output`, adapter, `fetchFile`, `markdown`, `compressHTML`, `cache`, `routeRules`, sitemap integration, MDX integration, and any framework integration.
+2. Apply the Version Gate before using migration guidance:
+   - If the task is not changing the Astro major version, do not run stale major-specific deltas as routine review noise.
+   - If the task crosses one or more Astro majors, check the official Astro upgrade guide for each crossed major and record which deltas apply.
+   - If a version-specific claim cannot be refreshed from official Astro docs, omit it or report it as unchecked instead of writing it as current.
+3. Read `src/content.config.*` when content, docs, blog, RSS, sitemap, canonical, or route generation is involved. Record each collection name, loader base, schema fields, slug/id policy, draft field, and date fields.
+4. Build a route ledger from `src/pages`: static pages, dynamic pages, rest routes, endpoints, prerendered routes, on-demand routes, and possible route-priority collisions.
+5. Classify the change: static route, dynamic route, endpoint, content collection, integration, adapter, SSR/on-demand, request pipeline, island, script, asset, RSS, sitemap, canonical, cache, Markdown, migration, or docs/content.
+6. Apply the hydration policy below before adding or changing any `client:*` directive.
+7. Apply the routing, request pipeline, and rendering policies below before adding dynamic routes, catch-all routes, endpoints, adapter changes, `src/fetch.*`, or `prerender` changes.
+8. Apply the content, SEO, and feed policy below before changing frontmatter, schemas, slugs, drafts, canonical URLs, pagination, RSS, or sitemap behavior.
+9. Apply the cache policy below before changing `cache`, `routeRules`, route-level cache behavior, or cache provider configuration.
+10. Apply the Markdown and compiler policy below before changing Markdown processing, MDX, generated markup, `compressHTML`, HTML snapshots, or whitespace-sensitive content.
+11. Do not put runtime-only data such as logged-in user state, request-local data, private API responses, or live inventory into build-time collections.
+12. Do not enable request-time rendering without the adapter and deployment contract that support it.
+13. Keep `set:html` or raw HTML injection behind a trusted and sanitized content boundary.
+14. Choose configured verification intents that cover content schema, build, routes, hydration, adapter/runtime, cache, Markdown, request pipeline, and bundle risk when available.
 
 ## Hydration Policy
 
@@ -102,7 +110,7 @@ The default is no-hydration. Add browser JavaScript only after proving that nati
 
 - In static output, every dynamic route must have `getStaticPaths`.
 - In on-demand or SSR dynamic routes, do not use `getStaticPaths`; read `Astro.params`, perform the request-time lookup, and handle missing entries with an explicit 404 or redirect path.
-- `getStaticPaths` params must match bracket parameter names exactly. Param values must be strings, except rest parameters may use `undefined`; numeric params are invalid in Astro 6.
+- `getStaticPaths` params must match bracket parameter names exactly. Route param values are a string contract; rest parameters may use `undefined`.
 - Custom slugs containing `/` require a rest route such as a catch-all route. Do not force slash-containing slugs into a single named parameter route.
 - Treat changes under `src/pages` as public URL changes, including endpoint names and extension-bearing endpoint paths.
 - Check route priority when adding static routes, named parameters, rest parameters, catch-all routes, and endpoints that could claim the same URL.
@@ -111,6 +119,35 @@ The default is no-hydration. Add browser JavaScript only after proving that nati
 - Do not switch the whole project to server output for one page unless the deployment and route contract require it.
 - Do not assume SSR dynamic routes appear in sitemap output automatically.
 
+## Request Pipeline Policy
+
+- Do not create `src/fetch.ts` or `src/fetch.js` just because a project uses Astro 7 or advanced routing. Add or modify a custom fetch entrypoint only when the request pipeline contract requires it.
+- If `src/fetch.*` already exists, check whether it is an intentional advanced-routing entrypoint, an accidental reserved-name collision, or disabled or moved through `fetchFile`.
+- Prefer preserving Astro's default request pipeline unless there is a named reason to compose handlers directly.
+- When direct handler composition is used, record a request pipeline ledger: trailing slash, redirects, sessions, actions, user middleware, rendering, i18n, cache, and any intentionally omitted stage.
+- Place session handling before any handler that reads or mutates session state.
+
+## Cache Policy
+
+- Treat `cache` and `routeRules` changes as data-exposure risks, not only performance changes.
+- Do not cache authenticated, personalized, locale-sensitive, cookie-dependent, header-dependent, or query-dependent responses unless the cache key, invalidation, and privacy boundary are explicit.
+- Check whether the deployment is single-instance or multi-instance before relying on in-memory route cache behavior.
+- When route cache behavior changes, use `cache-integrity-review` as an adjunct when available and report `HIT`, `MISS`, `STALE`, or equivalent cache evidence only when verified.
+
+## Markdown And Compiler Policy
+
+- When an Astro major migration changes Markdown processing, choose explicitly between the current processor and the new default processor. Keep the unified pipeline when remark, rehype, recma, MDX, or custom Markdown plugin compatibility is unproven.
+- Check heading ids, code blocks, syntax highlighting, link rewriting, frontmatter rendering, and Markdown or MDX snapshots when the processor changes.
+- Treat stricter compiler output, invalid HTML nesting, non-void tag closure, CSS serialization, and whitespace between inline elements as user-visible migration risks.
+- When `compressHTML` changes or defaults differ, verify important rendered text does not lose intended spaces between inline elements.
+
+## Astro Major Migration Deltas
+
+- For v5 to v6 migrations, check removed or changed surfaces before editing call sites: `Astro.glob()` replacement with `import.meta.glob()` or content collections, `.cjs` and `.cts` config removal, `astro:ssr-manifest`, `RouteData.generate()`, old adapter hooks, old `NodeApp` paths, Zod 4 schema effects, and numeric dynamic route params.
+- For v6 to v7 migrations, check `src/fetch.*` or `fetchFile`, direct request handler composition, `cache`, `routeRules`, `advancedRouting`, `logger`, `queuedRendering`, `rustCompiler`, `markdown.processor`, `compressHTML`, removed or changed `@astrojs/db` usage, transition internals, and `getContainerRenderer()` imports from integration roots.
+- For v6 to v7 migrations with custom Vite config, Rollup hooks, or Astro integrations that call Vite APIs, also use `dependency-upgrade-review` when available.
+- Keep each migration delta scoped to the crossed major version. Do not copy old delta checks into ordinary Astro UI, content, or route edits.
+
 ## Content SEO Feed Policy
 
 - Every frontmatter field used by routes, SEO, RSS, sitemap, pagination, filtering, or canonical URLs must be declared in the content collection schema.
@@ -134,8 +171,12 @@ Reject or revise a change when:
 - `client:only` is used because SSR broke, instead of isolating the browser-only dependency.
 - Static output dynamic routes lack `getStaticPaths`.
 - On-demand or SSR dynamic routes use `getStaticPaths`.
-- Route params do not match bracket names, non-rest params are not strings, rest params use values other than strings or `undefined`, or Astro 6 routes still rely on numeric params.
+- Route params do not match bracket names, non-rest params are not strings, or rest params use values other than strings or `undefined`.
 - A content slug with `/` is mapped through a non-rest route.
+- `src/fetch.*` is added without a named request pipeline requirement, or direct handler composition omits a needed pipeline stage.
+- Route cache is enabled for authenticated, personalized, locale-sensitive, cookie-dependent, header-dependent, or query-dependent responses without an explicit cache key and invalidation boundary.
+- Markdown processor changes skip plugin compatibility or rendered-output checks.
+- Compiler or `compressHTML` changes are accepted without checking invalid HTML nesting, non-void tag closure, CSS serialization, or whitespace-sensitive rendered text when those surfaces are affected.
 - Draft filtering differs between lists, detail pages, RSS, sitemap, or pagination.
 - Canonical URLs are built by ad hoc string concatenation.
 - RSS or sitemap includes drafts, stale paths, wrong trailing slash paths, or paths that the route ledger cannot produce.
@@ -147,7 +188,7 @@ Reject or revise a change when:
 
 - Build-time and runtime data are separated.
 - Client JavaScript is limited to needed islands.
-- Route, endpoint, canonical URL, RSS, sitemap, draft, and content schema impact is known.
+- Route, endpoint, request pipeline, cache, canonical URL, RSS, sitemap, draft, Markdown, and content schema impact is known.
 - SSR or adapter changes are verified or reported.
 
 <!-- mustflow-section: verification -->
@@ -162,15 +203,18 @@ Use configured oneshot command intents when available:
 - `docs_validate_fast`
 - `mustflow_check`
 
-Report missing framework validation, route preview, content schema, RSS, sitemap, canonical, or client bundle verification intents when relevant.
+Report missing framework validation, route preview, request pipeline, cache, Markdown, content schema, RSS, sitemap, canonical, or client bundle verification intents when relevant.
 
-When verifiable, report counts for added hydration directives, added island risk, generated public content pages, excluded drafts, RSS items, sitemap URLs, and duplicate canonical URLs.
+When verifiable, report counts for added hydration directives, added island risk, generated public content pages, excluded drafts, RSS items, sitemap URLs, duplicate canonical URLs, route cache rules, and affected Markdown or MDX outputs.
 
 <!-- mustflow-section: failure-handling -->
 ## Failure Handling
 
 - If an island is added only to work around static markup, revisit the markup and content boundary first.
 - If SSR is requested without adapter evidence, stop and report the deployment contract gap.
+- If custom request pipeline work lacks a pipeline ledger, create the ledger before changing unrelated routing or middleware.
+- If cache rules can expose private or personalized data, stop and route through cache integrity review before optimizing performance.
+- If Markdown processor compatibility is unknown, keep the existing processor path or report the migration blocker.
 - If content schema drift appears, fix schema and sample content before adding more pages.
 - If draft, canonical, RSS, sitemap, or pagination drift appears, fix the shared content and route contract before adding new entries.
 - If a route collision appears, resolve the route ledger before changing unrelated rendering code.
@@ -179,7 +223,7 @@ When verifiable, report counts for added hydration directives, added island risk
 ## Output Format
 
 - Boundary checked
-- Build/runtime, route, endpoint, content, hydration, canonical, RSS, sitemap, and draft notes
+- Build/runtime, route, endpoint, request pipeline, cache, Markdown, content, hydration, canonical, RSS, sitemap, and draft notes
 - Files changed
 - Command intents run
 - Skipped checks and reasons