mustflow 2.32.0 → 2.37.1

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

@@ -12,6 +12,12 @@ route_type = "primary"
 priority = 70
 applies_to_reasons = ["code_change", "cross_cutting_code_change"]
 
+[routes."service-boundary-architecture"]
+category = "architecture_patterns"
+route_type = "primary"
+priority = 82
+applies_to_reasons = ["code_change", "behavior_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "public_api_change"]
+
 [routes."code-review"]
 category = "general_code"
 route_type = "primary"
@@ -72,6 +78,12 @@ route_type = "adjunct"
 priority = 85
 applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "mustflow_docs_change", "mustflow_config_change", "package_metadata_change", "release_risk"]
 
+[routes."proactive-risk-surfacing"]
+category = "workflow_contracts"
+route_type = "event"
+priority = 72
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "docs_change", "mustflow_docs_change", "public_api_change", "security_change", "privacy_change", "data_change", "performance_change", "ui_change", "release_risk"]
+
 [routes."restricted-handoff-resume"]
 category = "workflow_contracts"
 route_type = "primary"
@@ -138,6 +150,12 @@ route_type = "primary"
 priority = 55
 applies_to_reasons = ["unknown_change", "code_change", "docs_change", "test_change", "behavior_change", "performance_change", "ui_change", "data_change"]
 
+[routes."ai-generated-code-hardening"]
+category = "general_code"
+route_type = "adjunct"
+priority = 74
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change"]
+
 [routes."clarifying-question-gate"]
 category = "general_code"
 route_type = "adjunct"
@@ -186,11 +204,23 @@ route_type = "primary"
 priority = 82
 applies_to_reasons = ["code_change", "public_api_change", "docs_change", "test_change"]
 
+[routes."backend-reliability-change"]
+category = "general_code"
+route_type = "primary"
+priority = 84
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "docs_change", "test_change", "package_metadata_change", "release_risk"]
+
+[routes."http-delivery-streaming"]
+category = "general_code"
+route_type = "primary"
+priority = 84
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "performance_change", "security_change", "privacy_change", "docs_change", "test_change", "package_metadata_change", "release_risk"]
+
 [routes."typescript-code-change"]
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change"]
+applies_to_reasons = ["code_change", "public_api_change", "test_change", "package_metadata_change"]
 
 [routes."javascript-code-change"]
 category = "general_code"
@@ -468,6 +498,12 @@ route_type = "adjunct"
 priority = 60
 applies_to_reasons = ["migration_change"]
 
+[routes."frontend-render-stability"]
+category = "ui_assets"
+route_type = "primary"
+priority = 78
+applies_to_reasons = ["ui_change", "performance_change", "behavior_change", "code_change"]
+
 [routes."ui-quality-gate"]
 category = "ui_assets"
 route_type = "primary"

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.rust-code-change
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: rust-code-change
-description: Apply this skill when Rust source, Cargo metadata, features, traits, errors, ownership, async runtime, unsafe code, tests, examples, or public crate APIs are created or changed.
+description: Apply this skill when Rust source, Cargo metadata, features, traits, errors, ownership, async runtime, unsafe code, tests, examples, benchmarks, release profiles, MSRV, toolchain declarations, standard-library APIs, or public crate APIs are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -40,6 +40,7 @@ instead of treated as incidental.
 
 - `.rs`, `Cargo.toml`, `Cargo.lock`, workspace config, feature flags, public exports, traits, error types, tests, examples, benches, FFI, async runtime, or unsafe code change.
 - The task touches ownership, borrowing, lifetimes, `Clone`, `Arc`, `Mutex`, `unwrap`, or public crate compatibility.
+- The task introduces or reviews Rust-version-gated APIs or language behavior such as `let else`, let chains, match `if let` guards, `cfg_select!`, `assert_matches!`, `core::range`, `Vec::push_mut`, `HashMap::get_disjoint_mut`, `Option::take_if`, `LazyLock`, `OnceLock`, `workspace.lints`, `rust-version`, Rust 2024 lints, or release-profile tuning.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -54,6 +55,7 @@ instead of treated as incidental.
 - Relevant `src/lib.rs`, `src/main.rs`, modules, public re-exports, tests, examples, and docs examples.
 - Existing error handling convention and async runtime.
 - Public crate status, minimum supported Rust version, feature support policy, and downstream compatibility expectations when available.
+- `rust-version`, edition, `rust-toolchain.toml`, CI toolchain matrix, target triples, Cargo resolver, workspace inheritance policy, and whether newer standard-library APIs require a raised MSRV.
 - Host and build-loop constraints: OS, shell, native toolchain prerequisites, VM or remote-builder use, release profile, LTO, workspace size, disk budget, and configured smoke or focused-check intents.
 - Configured verification intents.
 
@@ -66,6 +68,7 @@ instead of treated as incidental.
 - Identify the intended edit-check-test loop before choosing a broad build. Treat whole-workspace
   checks, release builds, fat LTO, cross-compiles, and sanitizer-style runs as expensive evidence
   unless the command contract declares them as the normal focused path.
+- If a Rust release, "latest stable Rust", standard-library feature, Cargo behavior, edition behavior, lint default, or toolchain-support claim is written durably, use `version-freshness-check` and official Rust sources before relying on memory or pasted notes.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -93,20 +96,35 @@ instead of treated as incidental.
      MSVC, SDK, linker, or environment setup is required;
    - treat VM builds, remote builders, release profiles, fat LTO, and whole-workspace checks as
      environment and verification choices that must be reported when they dominate iteration cost.
-4. Resolve ownership problems in this order: identify the real owner, shrink borrow scopes, fix function signatures to accept references or slices when ownership is unnecessary, distinguish transfer from sharing, then consider clone or shared ownership only when the semantics require it.
-5. Before adding `clone`, verify it is a cheap handle clone such as `Arc`, `Rc`, or `Bytes`, a small intentional value clone, or a true independent ownership split. Reject large collection clones, loop clones, clone-then-borrow code, and whole-state clones made only to satisfy `spawn`.
-6. Before adding `Arc<Mutex<_>>`, verify multiple owners truly need shared mutable state. Keep critical sections short, document lock order when relevant, and do not hold a lock guard across `.await`, I/O, callbacks, or user code.
-7. Use explicit lifetimes only to describe real borrow relationships. Do not add `'static` or `T: 'static` to public APIs merely because an internal task boundary requires it.
-8. Use concrete error enums for library APIs when callers need to classify failures. Keep `Box<dyn Error>` mostly to binaries, examples, tests, prototypes, or explicitly opaque error policies.
-9. Avoid `unwrap`, vague `expect`, and unbounded `panic!` in production paths. They are allowed only for tests, examples, startup policy, panic-boundary adapters, or invariants already proven by nearby code.
-10. If feature flags change, treat default features, no-default builds, all-features builds, optional dependency implicit features, public re-exports, docs examples, and feature-gated trait impls as compatibility surfaces. Features should be additive.
-11. Treat public re-exports, public dependency types, generic bounds, trait item sets, error enum variants, `#[non_exhaustive]`, and MSRV as public API. Tightened bounds, added required trait methods, removed re-exports, or changed error variants require compatibility review.
-12. Do not mix async runtimes. A Tokio crate should not casually gain `async-std` or runtime-specific APIs in library core. Do not call blocking I/O or CPU-heavy work in async paths without an established boundary such as async-native APIs, a blocking pool, or a dedicated worker.
-13. For async spawning, avoid leaking internal `Send + Sync + 'static` requirements into public APIs. Prefer owned task state, smaller spawn boundaries, local task structures, or caller-owned runtime decisions.
-14. Touch `unsafe` only when a safe design cannot express the required behavior. Every unsafe block needs a nearby `SAFETY:` explanation; every public `unsafe fn` needs `# Safety` docs. Keep unsafe scopes small and wrap them in safe abstractions only when callers have no hidden safety obligations.
-15. For FFI, keep Rust ABI types out of C boundaries. Use explicit ownership, `#[repr(C)]` where required, raw pointer plus length pairs, `CStr`/`CString`, RAII wrappers, null handling, panic boundaries, and documented thread-safety evidence before manual `Send` or `Sync`.
-16. Calibrate performance claims. Do not claim Rust made a system faster from compile success, empty-database timings, warm-cache microbenchmarks, local-only runs, or debug versus release confusion. Require representative data size, concurrency, target hardware, profile, and measurement method before reporting speed claims.
-17. Choose configured verification intents that cover format, lint, build, tests, feature combinations, docs, public API, unsafe, FFI, smoke targets, package artifact, and release-profile risk when available.
+4. Determine the Rust version contract before using newer syntax or standard-library APIs:
+   - treat `rust-version`, edition, `rust-toolchain.toml`, CI matrix, docs.rs metadata, and downstream compatibility notes as the MSRV evidence ledger;
+   - do not use 1.95+ APIs such as `cfg_select!`, match `if let` guards, or `Vec::push_mut`, or 1.96+ APIs such as `assert_matches!` and `core::range`, unless the declared MSRV and toolchain path support them;
+   - keep experimental, nightly-only, target-specific, or edition-specific behavior behind explicit gates or fallbacks instead of calling it general Rust advice.
+5. Prefer flatter control flow when the MSRV supports it: use `let else` for early validation, let chains for related optional/result guards, and match `if let` guards for state-machine refinements. Remember that guard patterns do not satisfy match exhaustiveness; keep the fallback arm meaningful.
+6. In tests, prefer `assert_matches!` over `assert!(matches!(...))` when the MSRV supports it and the failed value has useful `Debug` output. Import it explicitly from `std` or `core`; do not assume it is in the prelude.
+7. Resolve ownership problems in this order: identify the real owner, shrink borrow scopes, fix function signatures to accept references or slices when ownership is unnecessary, distinguish transfer from sharing, then consider clone or shared ownership only when the semantics require it.
+8. Before adding `clone`, verify it is a cheap handle clone such as `Arc`, `Rc`, or `Bytes`, a small intentional value clone, or a true independent ownership split. Reject large collection clones, loop clones, clone-then-borrow code, and whole-state clones made only to satisfy `spawn`.
+9. Before adding `Arc<Mutex<_>>`, verify multiple owners truly need shared mutable state. For read-mostly snapshots, prefer ownership-preserving choices such as `Arc::make_mut`, immutable swaps, or explicit reload boundaries. Keep critical sections short, document lock order when relevant, and do not hold a lock guard across `.await`, I/O, callbacks, or user code.
+10. Choose initialization primitives by input and failure semantics: use `LazyLock` for no-argument static lazy values that may poison permanently on panic, and `OnceLock` when boot-time or test-time code supplies the value or panic poisoning must not become the recovery policy.
+11. Avoid hidden allocation when cheaper type contracts fit: use `Cow<'_, str>` or borrowed slices for mostly-borrowed results, query `HashMap<String, V>` with `&str` when `Borrow` supports it, use `Option::take`, `take_if`, or `as_slice` for state transitions and 0-or-1 iteration, and use `ControlFlow`, `try_for_each`, or `try_fold` when visitor or iterator APIs need explicit short-circuiting.
+12. Treat collection and string capacity as part of performance correctness. Use `with_capacity`, `reserve`, `spare_capacity_mut`, or `push_mut` only when the safety and MSRV contract are clear; keep `set_len` inside a small proven unsafe boundary; avoid repeated `String::insert` or front insertion loops that create quadratic movement.
+13. Use explicit lifetimes only to describe real borrow relationships. Do not add `'static` or `T: 'static` to public APIs merely because an internal task boundary requires it.
+14. Use concrete error enums for library APIs when callers need to classify failures. Keep `Box<dyn Error>` mostly to binaries, examples, tests, prototypes, or explicitly opaque error policies.
+15. Avoid `unwrap`, vague `expect`, and unbounded `panic!` in production paths. They are allowed only for tests, examples, startup policy, panic-boundary adapters, or invariants already proven by nearby code.
+16. Review public API shape before adding `impl Trait`, `Deref`, or trait/lifetime machinery:
+   - argument-position `impl Trait` removes caller turbofish control and can be a public breaking change when converted from named generics;
+   - return-position `impl Trait` hides one concrete type, so divergent iterator or future branches need an enum, boxed trait object, or different API boundary;
+   - implement `Deref` only for pointer-like wrappers, not domain inheritance or method forwarding;
+   - use GATs for borrowing iterator/view traits when they remove a real allocation or boxed lifetime escape, not as decorative complexity.
+17. If feature flags or Cargo workspace metadata change, treat default features, no-default builds, all-features builds, optional dependency implicit features, resolver behavior, target-specific dependencies, `workspace.package`, `workspace.dependencies`, `workspace.lints`, public re-exports, docs examples, and feature-gated trait impls as compatibility surfaces. Features should be additive, and `resolver = "2"` or a newer resolver decision must match the crate's edition/MSRV policy.
+18. Treat public re-exports, public dependency types, generic bounds, trait item sets, error enum variants, `#[non_exhaustive]`, and MSRV as public API. Tightened bounds, added required trait methods, removed re-exports, changed error variants, or raised `rust-version` require compatibility review.
+19. Do not mix async runtimes. A Tokio crate should not casually gain `async-std` or runtime-specific APIs in library core. Do not call blocking I/O or CPU-heavy work in async paths without an established boundary such as async-native APIs, a blocking pool, or a dedicated worker.
+20. For async spawning, avoid leaking internal `Send + Sync + 'static` requirements into public APIs. Prefer owned task state, smaller spawn boundaries, local task structures, or caller-owned runtime decisions.
+21. Touch `unsafe` only when a safe design cannot express the required behavior. Every unsafe block needs a nearby `SAFETY:` explanation; every public `unsafe fn` needs `# Safety` docs. In Rust 2024 or when `unsafe_op_in_unsafe_fn` is enabled, unsafe operations inside `unsafe fn` still need explicit unsafe blocks. Keep unsafe scopes small and wrap them in safe abstractions only when callers have no hidden safety obligations.
+22. For FFI, keep Rust ABI types out of C boundaries. Use explicit ownership, `#[repr(C)]` where required, raw pointer plus length pairs, `CStr`/`CString`, RAII wrappers, null handling, panic boundaries, and documented thread-safety evidence before manual `Send` or `Sync`.
+23. Review release profiles when the task changes binary delivery, CLI startup, embedded, wasm, or performance behavior. Treat `opt-level`, LTO, `panic`, `codegen-units`, and `strip` as product tradeoffs that must be measured or reported, not decorative Cargo knobs.
+24. Calibrate performance claims. Do not claim Rust made a system faster from compile success, empty-database timings, warm-cache microbenchmarks, local-only runs, or debug versus release confusion. Require representative data size, concurrency, target hardware, profile, and measurement method before reporting speed claims.
+25. Choose configured verification intents that cover format, lint, build, tests, feature combinations, docs, public API, unsafe, FFI, smoke targets, package artifact, and release-profile risk when available.
 
 <!-- mustflow-section: rejection-criteria -->
 ## Review Rejection Criteria
@@ -115,6 +133,10 @@ Reject or revise the patch when any of these appear without strong local justifi
 
 - New large `clone()` calls, clone-then-borrow code, loop clones, or state clones used only to appease ownership errors.
 - New `Arc<Mutex<AppState>>`-style shared bags, locks held across `.await`, or async I/O resources shared mainly by mutex.
+- New Rust 1.95+ or 1.96+ API usage without MSRV, `rust-version`, edition, toolchain, CI, or fallback evidence.
+- New `LazyLock` initialization for recoverable runtime configuration where permanent panic poisoning would be the wrong failure policy.
+- New `spare_capacity_mut` plus `set_len` without a narrow, proven initialization invariant.
+- New public `impl Trait`, `Deref`, GAT, workspace resolver, feature, or `rust-version` change without public API and compatibility review.
 - New public `'static`, `Send`, or `Sync` bounds that exist only because an internal task was spawned.
 - New public `Box<dyn Error>` in a library where callers need typed failures.
 - New production `unwrap` or vague `expect` on I/O, parse, environment, network, FFI, lock, or user input paths.
@@ -130,9 +152,11 @@ Reject or revise the patch when any of these appear without strong local justifi
 ## Postconditions
 
 - Ownership changes are intentional, not compiler appeasement.
+- Rust-version-gated syntax, standard-library APIs, Cargo behavior, and lint assumptions match the declared MSRV or have explicit fallbacks.
 - Public API, features, optional dependencies, and error contracts are synchronized.
 - Async runtime ownership is preserved and blocking work is isolated.
-- Unsafe and FFI invariants are preserved or no unsafe code was touched.
+- Unsafe, `unsafe_op_in_unsafe_fn`, and FFI invariants are preserved or no unsafe code was touched.
+- Allocation, initialization, Cargo workspace, and release-profile choices are intentional and reported when they affect public or delivery behavior.
 - Build-loop cost, target/cache impact, smoke-target coverage, and native toolchain prerequisites
   are handled or reported.
 - Missing feature, semver, docs, unsafe, FFI, smoke, package, or performance verification is reported.

package/templates/default/locales/en/.mustflow/skills/service-boundary-architecture/SKILL.md

@@ -0,0 +1,167 @@
+---
+mustflow_doc: skill.service-boundary-architecture
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: service-boundary-architecture
+description: Apply this skill when service boundaries, modular-monolith boundaries, data ownership, queue/event boundaries, multi-tenant isolation, failure flow, operational recovery, or large-scale architecture split decisions are designed, reviewed, or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.service-boundary-architecture
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Service Boundary Architecture
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Design or review large-system boundaries by starting with ownership, failure, data coupling, and operations. Treat service splits, queues, caches, events, and deployment topology as consequences of the boundary model, not as architecture decorations.
+
+This skill protects against the common failure mode where a system is split by nouns, shares data anyway, retries blindly, emits ambiguous events, lacks tenant isolation, and then discovers during an incident that no team owns the truth.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A task designs, reviews, documents, or changes service boundaries, modular-monolith boundaries, bounded contexts, team ownership, API ownership, event ownership, queue ownership, or data ownership.
+- A monolith is being prepared for future split, a microservice split is proposed, or a service/module boundary is causing deploy, data, incident, or team coordination pain.
+- The task touches cross-service transactions, outbox/inbox patterns, idempotency, retries, timeouts, caches, read models, search models, shared databases, operational tools, manual correction, observability, tenancy, hot keys, or failure recovery.
+- Architecture docs, decision records, onboarding docs, or skills need durable guidance for large-system design and operational readiness.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is a small local refactor with no ownership, data, deployment, or operational boundary decision; use `architecture-deepening-review` or `behavior-preserving-refactor`.
+- The task only changes a single API shape; use `api-contract-change`.
+- The task only changes database schema or persistence safety inside one owner; use `database-change-safety` or `database-migration-change`.
+- The task only changes one external provider adapter; use `adapter-boundary`.
+- The task only models one lifecycle state machine; use `state-machine-pattern`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Candidate domains, capabilities, teams, modules, services, and the reason each boundary may need to exist.
+- Data ownership map: which module or service is the source of truth for each core fact, identifier, status, ledger, permission, tenant record, event, and read projection.
+- Current or proposed communication paths: direct calls, APIs, events, queues, shared databases, shared caches, batch jobs, search indexes, analytics stores, files, and admin tools.
+- Failure flows: duplicate requests, partial success, timeout, retry, consumer crash, queue backlog, dead-letter handling, external provider uncertainty, reconciliation, and manual correction.
+- Consistency expectations: strong consistency, eventual consistency, tolerated delay, stale reads, cache invalidation, read/write split, search delay, and deletion or retention rules.
+- Tenant, authorization, observability, deployment, migration, and operations requirements.
+- Configured verification intents and any existing architecture decision records or context files.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Do not start by choosing microservices, Kafka, Kubernetes, service mesh, CQRS, or event sourcing. Start by identifying ownership and failure pressure.
+- Do not split by nouns alone. Check which rules and data change together, which teams own them, and which failures must be isolated.
+- Treat shared databases, shared caches, and table reads across owners as coupling evidence even when code appears separated.
+- Treat architecture diagrams as secondary evidence. Decision records, ownership maps, failure behavior, and recovery tools are the durable contract.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Architecture docs, decision records, context files, workflow skills, tests, fixtures, schema notes, operational runbook notes, and directly related source changes.
+- Boundary diagrams only when they are backed by ownership, data, failure, and operations text.
+- Module, service, API, event, queue, cache, read-model, or operations-tool boundaries when the repository scope and command contract support that edit.
+- Do not introduce new infrastructure, service topology, queue systems, brokers, databases, orchestration platforms, or deployment tools unless the user explicitly requests that implementation and the repository already has an approved path.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the business capabilities and the facts each capability owns. For every core fact, identify exactly one source of truth and the owner responsible for correcting it.
+2. Split first by reason to change, not by noun. Keep code together when it changes together; split only when ownership, release cadence, scale, compliance, failure isolation, or team autonomy makes the boundary useful.
+3. Prefer a modular monolith with hard internal boundaries when the team is still discovering the domain. Draw future split lines early, but do not pay distributed-system costs before the boundary pressure is real.
+4. Reject shared database ownership. If another service or module needs data, choose an API, event, read projection, export, or explicitly owned query surface instead of direct table coupling.
+5. Design failure flows before the happy path. Cover partial success, duplicated requests, timeout, unknown external outcome, consumer crash, queue backlog, dead-letter handling, replay, reconciliation, and manual recovery.
+6. Require idempotency for commands that create, charge, reserve, approve, issue, grant, cancel, refund, redeem, or mutate durable state. Use stable request keys and return the previous result for duplicate keys.
+7. Treat queues as storage and backpressure, not magic. Define retry policy, exponential backoff or jitter, max attempts, retention, dead-letter ownership, consumer scaling, ordering expectations, replay safety, and loss tolerance.
+8. Every network call across the boundary needs a timeout, bounded retry policy, fallback or failure result, duplicate-safety story, and observability identifiers.
+9. Treat caches as a consistency tradeoff. Declare which stale values are acceptable, max staleness, invalidation owner, tenant and permission visibility, and whether the cache is allowed to become authority.
+10. Model authorization, tenant isolation, audit, and data visibility at the boundary. Tenant ID must travel through APIs, queues, caches, logs, files, reports, and admin tools when the system is multi-tenant.
+11. For event-driven boundaries, use past-tense fact events such as `OrderCreated` or `PaymentApproved`. Do not disguise commands as events. Include event ID, version, occurred time, publisher, subject, causation or request ID, correlation or trace ID, and compatible schema evolution rules.
+12. Separate transaction data from search, reporting, analytics, and screen-shaped read projections when their consistency, indexing, query, or retention needs diverge.
+13. Define tolerated delay with numbers. Replace vague "real-time" claims with accepted latency or freshness windows such as seconds, minutes, or batch cadence.
+14. Check hot keys and noisy neighbors. Define per-tenant, per-customer, per-room, per-campaign, or per-product limits, queue separation, worker pool separation, connection caps, and external API call caps when one key can dominate load.
+15. Keep domain rules in the owning domain layer. Do not scatter refund windows, cancellation rules, entitlement checks, inventory reservations, or admin overrides across controllers, UI, workers, and jobs.
+16. Plan migrations with expand, dual-write or compatibility, backfill, read switch, verification, and contract removal. Do not rename or remove shared fields in one deployment step.
+17. Plan deletion and retention before data is created. Identify legal retention, anonymization, log masking, backup retention, search/read-model cleanup, and audit exceptions.
+18. Make observability a product feature. Connect API, queue, worker, external provider, database, and admin operations with trace, request, correlation, causation, job, and tenant identifiers. Prefer p95, p99, error rate, queue age, backlog, dependency failure rate, and business success rate over averages.
+19. Make deployment and rollback a boundary decision. Use feature flags, canaries, partial exposure, compatibility windows, and kill switches for risky boundary changes.
+20. Provide operational tools for reality: reconcile external state, retry or quarantine failed messages, correct user/account/order state, revoke permissions, inspect provider responses, and undo manual changes with audit and approval when required.
+21. Record the decision: selected boundary, rejected alternatives, reason, assumptions, failure modes, data owner, operational owner, verification, and revisit triggers.
+
+<!-- mustflow-section: review-rejection-criteria -->
+## Review Rejection Criteria
+
+Reject or revise the design when:
+
+- A service or module boundary has no named data owner.
+- Two owners write the same core fact without a conflict rule.
+- A service reads another service's tables or cache as normal behavior.
+- The design shows only the happy path.
+- Retries lack timeout, backoff, jitter, max attempts, idempotency, or failure ownership.
+- A queue has no dead-letter, retention, replay, ordering, or backlog policy.
+- Cache behavior does not state acceptable staleness and invalidation ownership.
+- Events are imperative commands instead of past-tense facts.
+- Event schemas lack version, event ID, occurred time, publisher, and correlation or causation identifiers.
+- Tenant, permission, audit, or data-retention boundaries are added after the fact.
+- Architecture choice is justified by tooling fashion instead of ownership, failure, scale, compliance, or team autonomy.
+- Manual operations can mutate critical state without audit, approval, and reversal or reconciliation path.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Data ownership and source-of-truth boundaries are explicit.
+- Boundary split is justified by change reason, ownership, scale, compliance, failure isolation, or team autonomy.
+- Failure handling, idempotency, retry, queue, cache, event, and observability contracts are defined or explicitly deferred.
+- Tenant, authorization, deletion, retention, migration, deployment, and operational recovery risks are checked or reported.
+- Decision records explain why this boundary was chosen, what alternatives were rejected, and when to revisit.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use broader configured checks when the boundary change affects templates, public docs, package behavior, or cross-module contracts. Report missing architecture, integration, load, or operational verification instead of claiming the design is production-ready.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If ownership cannot be assigned, stop at a decision record or open question instead of drawing a false boundary.
+- If shared database coupling is unavoidable for now, document it as temporary coupling with the exit path, owner, read/write limits, and revisit trigger.
+- If the user asks for a new service but failure, data ownership, or operational tooling is missing, recommend the smallest boundary-preserving modular step first.
+- If verification is unavailable, report which boundary risks remain untested: duplicate command, stale read, queue replay, provider timeout, tenant isolation, migration, deletion, or manual recovery.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Data owners and source-of-truth notes
+- Failure, idempotency, queue, cache, and event notes
+- Tenant, auth, retention, observability, deployment, and operations notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining service-boundary risk

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.tailwind-code-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: tailwind-code-change
-description: Apply this skill when Tailwind classes, className composition, static class detection, theme tokens, variants, safelists, arbitrary values, Tailwind config, @theme, @apply, or Tailwind migration surfaces are created or changed.
+description: Apply this skill when Tailwind classes, className composition, static class detection, theme tokens, variants, safelists, arbitrary values, Tailwind config, v4 CSS-first configuration, @source, @theme, @reference, @apply, or Tailwind migration surfaces are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -33,8 +33,8 @@ Preserve Tailwind static class detection, design tokens, bounded variants, respo
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- Tailwind `class`, `className`, `@apply`, `@theme`, config, source scanning, safelist, theme tokens, variants, arbitrary values, or component class composition change.
-- The task touches Tailwind v3/v4 migration, token addition, responsive modifiers, state modifiers, `clsx`/`cn`, CVA-style variant helpers, `@source`, or production CSS generation risk.
+- Tailwind `class`, `className`, `@apply`, `@theme`, `@source`, `@reference`, config, source scanning, safelist, theme tokens, variants, arbitrary values, or component class composition change.
+- The task touches Tailwind v3/v4 migration, CSS-first configuration, token addition, responsive modifiers, state modifiers, `clsx`/`cn`, CVA-style variant helpers, `source(none)`, `@source inline`, `@source not inline`, or production CSS generation risk.
 - Component APIs accept status, tone, intent, size, column count, color, spacing, or class-related props that affect Tailwind utilities.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -46,16 +46,18 @@ Preserve Tailwind static class detection, design tokens, bounded variants, respo
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
 
-- Tailwind version/config or CSS entry, content/source scanning rules, theme tokens, PostCSS/build config, class merge helpers, variant helpers, component patterns, and tests.
+- Tailwind version/config or CSS entry, `@import` options, `@source` directives, content/source scanning rules, theme tokens, PostCSS/build config, class merge helpers, variant helpers, component patterns, and tests.
 - Existing design system vocabulary, token naming conventions, accessibility state patterns, and component prop APIs.
 - Any runtime source for visual values: props, CMS, database, tenant config, user input, API data, or external package markup.
+- Framework style boundaries that may need `@reference`, such as Vue or Svelte component styles, CSS Modules, scoped CSS, or separate CSS entrypoints.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
 
-- Confirm how Tailwind detects source classes before changing class composition.
+- Confirm how Tailwind detects source classes before changing class composition, helper-file location, or CSS entry imports.
 - Identify whether the project is using Tailwind v3 config safelists or Tailwind v4 CSS source directives.
+- Identify whether Tailwind v4 source detection is automatic, disabled with `source(none)`, extended with `@source`, or narrowed with `@source not inline`.
 - Identify tokens, variant helpers, and semantic visual states before adding arbitrary values or raw colors.
 - Confirm whether affected components are local one-offs, shared components, or public design-system surfaces.
 
@@ -65,7 +67,9 @@ Preserve Tailwind static class detection, design tokens, bounded variants, respo
 - Use full static class strings that the build can detect.
 - Use existing theme tokens before arbitrary values or raw colors.
 - Use static maps, component extraction, or variant helpers for finite repeated variants.
-- Use safelists only for finite class candidates that cannot appear in scanned source.
+- Use safelists or `@source inline` only for finite class candidates that cannot appear in scanned source.
+- Use `@source not inline` or equivalent source policy to block known false-positive candidates when generated CSS would otherwise include unwanted utilities.
+- Use `@reference` when component-scoped styles need access to Tailwind theme variables, custom utilities, or variants without duplicating emitted CSS.
 - Use inline styles plus CSS variables for unbounded runtime values such as tenant, database, or user-provided colors.
 - Keep hover, focus-visible, disabled, aria/data, dark, and motion variants aligned with existing component behavior.
 
@@ -74,29 +78,35 @@ Preserve Tailwind static class detection, design tokens, bounded variants, respo
 
 1. Read Tailwind config or CSS entry, scanning rules, theme tokens, helpers, and nearby components.
 2. Classify the change: token, utility usage, dynamic variant, component extraction, responsive state, accessibility state, or migration.
-3. Treat every Tailwind class as a complete build-time token. Reject runtime interpolation, concatenation, array joins, or fragment assembly for utilities such as color, spacing, grid count, span, tone, or arbitrary values.
-4. For finite choices, use a static map with semantic keys and full class strings. Good keys describe UI meaning such as `danger`, `muted`, `compact`, or `featured`; bad keys store Tailwind fragments such as `red`, `600`, or `cols-3` for later assembly.
-5. Use a CVA-style variant helper only when a shared component has multiple variant axes, defaults, or compound variants. The helper must still contain full static class strings.
-6. Use safelists only as a last resort for finite candidates that cannot be present in source files. Tailwind v4 projects should express this through the project's CSS source policy; Tailwind v3 maintenance projects may use config safelists when that is the existing pattern. Do not safelist broad palettes or unbounded ranges to avoid fixing a bad component API.
-7. Use inline style plus a CSS variable bridge for unbounded runtime values from databases, APIs, tenants, CMS content, or user input. Do not try to mint Tailwind class names from unbounded values.
-8. Treat arbitrary values as escape hatches. Allow them for one-off asset alignment, complex grid templates, complex calculations, local CSS variable assignment, or values that cannot be expressed with regular utilities.
-9. Reject arbitrary raw colors in component markup, arbitrary spacing that approximates existing scale values, arbitrary container widths, arbitrary radius or shadow used as a hidden token, and repeated arbitrary values. Repeated values must be promoted to a semantic design token or component variant.
-10. Keep raw color literals in theme or token files only. Token names should describe purpose, not numeric value.
-11. Use `clsx` or `cn` only to combine complete class strings. Do not hide dynamic Tailwind string construction inside helper functions.
-12. Do not expose unrestricted class fragments through public component APIs. If a `className` passthrough exists, preserve internal layout-critical classes and prevent consumer props from becoming the source of required Tailwind generation.
-13. Do not extract a component only because a class list is long. Extract a component when structure, behavior, accessibility, and styling repeat together across files.
-14. Do not use `@apply` to hide long JSX or template class lists. Reserve `@apply` for third-party markup overrides, CSS-module boundaries, or template systems where component extraction is genuinely heavier.
-15. Use mobile-first responsive classes and include focus-visible or equivalent keyboard states for interactive elements.
-16. Check for conflicting utilities on one element, such as mutually exclusive display, spacing, text-size, or layout utilities.
-17. Choose configured verification intents that cover production build, lint, component tests, accessibility states, and visual risk when available.
+3. For Tailwind v4, classify CSS-first configuration before touching utility usage: `@theme`, `@utility`, `@variant`, `@custom-variant`, `@source`, `@source inline`, `@source not inline`, `source(none)`, and `@reference`. Do not apply v3 config instincts to a v4 CSS entry without checking the project pattern.
+4. Treat every Tailwind class as a complete build-time token. Reject runtime interpolation, concatenation, array joins, or fragment assembly for utilities such as color, spacing, grid count, span, tone, or arbitrary values.
+5. For finite choices, use a static map with semantic keys and full class strings. Good keys describe UI meaning such as `danger`, `muted`, `compact`, or `featured`; bad keys store Tailwind fragments such as `red`, `600`, or `cols-3` for later assembly.
+6. Use a CVA-style variant helper only when a shared component has multiple variant axes, defaults, or compound variants. The helper must still contain full static class strings.
+7. Use safelists only as a last resort for finite candidates that cannot be present in source files. Tailwind v4 projects should express this through the project's CSS source policy; Tailwind v3 maintenance projects may use config safelists when that is the existing pattern. Do not safelist broad palettes or unbounded ranges to avoid fixing a bad component API.
+8. Keep `@source inline` bounded, named, and close to the CSS entry policy. If `source(none)` disables automatic detection, require explicit source includes for every package, app, and external component source that owns utilities. Use `@source not inline` for known false positives instead of relying on accidental absence.
+9. Use inline style plus a CSS variable bridge for unbounded runtime values from databases, APIs, tenants, CMS content, or user input. Do not try to mint Tailwind class names from unbounded values.
+10. Treat arbitrary values as escape hatches. Allow them for one-off asset alignment, complex grid templates, complex calculations, local CSS variable assignment, or values that cannot be expressed with regular utilities.
+11. Reject arbitrary raw colors in component markup, arbitrary spacing that approximates existing scale values, arbitrary container widths, arbitrary radius or shadow used as a hidden token, and repeated arbitrary values. Repeated values must be promoted to a semantic design token or component variant.
+12. Keep raw color literals in theme or token files only. Token names should describe purpose, not numeric value.
+13. Use `clsx` or `cn` only to combine complete class strings. Do not hide dynamic Tailwind string construction inside helper functions.
+14. Do not expose unrestricted class fragments through public component APIs. If a `className` passthrough exists, preserve internal layout-critical classes and prevent consumer props from becoming the source of required Tailwind generation.
+15. Do not extract a component only because a class list is long. Extract a component when structure, behavior, accessibility, and styling repeat together across files.
+16. Do not use `@apply` to hide long JSX or template class lists. Reserve `@apply` for third-party markup overrides, CSS-module boundaries, or template systems where component extraction is genuinely heavier.
+17. When `@apply` or `@variant` appears in component-scoped CSS, verify that `@reference` points at the shared Tailwind CSS entry or theme source without emitting duplicate CSS.
+18. Use mobile-first responsive classes and include focus-visible or equivalent keyboard states for interactive elements.
+19. Prefer container, data, aria, `has`, `group`, `peer`, `not`, `supports`, `starting`, motion, and dark-mode variants only when the source selector/state is owned and testable. Keep selector-based dark variants and `color-scheme` aligned with the root theme strategy.
+20. Check layout utilities for common browser traps: missing `min-w-0` or `min-h-0` in flex/grid children, viewport height assumptions that should use `dvh`, `svh`, or `lvh`, and `space-*` on wrapped, reordered, or grid-like children where `gap` is the stable contract.
+21. Check for conflicting utilities on one element, such as mutually exclusive display, spacing, text-size, viewport, or layout utilities.
+22. Choose configured verification intents that cover production build, lint, component tests, accessibility states, and visual risk when available.
 
 <!-- mustflow-section: generation-policy -->
 ## Generation Policy
 
-- Tailwind classes must appear as complete static strings in scanned source, a static variant map, a CVA-style variant declaration, or an explicit finite safelist.
+- Tailwind classes must appear as complete static strings in scanned source, a static variant map, a CVA-style variant declaration, an explicit finite safelist, or a bounded v4 CSS source directive.
 - Dynamic visual state must be represented by exactly one of: static map entry, variant helper entry, explicit safelist entry, or CSS variable bridge.
 - Status, tone, intent, size, density, and column props are closed sets until proven otherwise. Model them as finite typed variants, not string fragments.
 - Production CSS is the contract. If a class only exists after runtime string construction, assume production CSS may omit it.
+- `@source inline`, `@source not inline`, and `source(none)` are part of the production CSS generation contract. Review them as carefully as code that uses utilities.
 
 <!-- mustflow-section: token-policy -->
 ## Token Policy
@@ -117,8 +127,12 @@ Reject the change when:
 - The same arbitrary value appears in more than one place.
 - A wrapper component exists only to hide a one-off class list.
 - `@apply` hides component-specific styling instead of handling a CSS boundary.
+- Component-scoped `@apply` or `@variant` relies on Tailwind globals without the needed `@reference` boundary.
 - A public component exposes unconstrained Tailwind class fragments.
 - A safelist covers broad palettes, broad numeric ranges, or unknown runtime values.
+- `@source inline` covers broad palettes, broad numeric ranges, or unknown runtime values.
+- `source(none)` is used without explicit source includes for all utility-owning files.
+- `space-*` is used where wrapped or reordered children require `gap`.
 - Conflicting utilities are present on the same element.
 
 <!-- mustflow-section: postconditions -->