mustflow 2.32.0 → 2.37.1

package/templates/default/locales/en/.mustflow/skills/api-contract-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.api-contract-change
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: api-contract-change
-description: Apply this skill when HTTP, REST, GraphQL, tRPC, Hono RPC, Elysia Eden, gRPC, protobuf, OpenAPI, API schemas, generated clients, SDKs, status codes, headers, error envelopes, pagination, filtering, sorting, search, or public API examples are created or changed.
+description: Apply this skill when HTTP, REST, GraphQL, tRPC, Hono RPC, Elysia Eden, gRPC, protobuf, OpenAPI, API schemas, generated clients, SDKs, status codes, headers, content negotiation, cache headers, error envelopes, pagination, filtering, sorting, search, or public API examples are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -29,7 +29,7 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Treat an API change as a contract change, not as a route or controller edit. The contract includes request schema, response schema, status code, headers, error shape, auth and permission behavior, pagination, filtering, sorting, search semantics, generated clients, SDKs, mocks, fixtures, examples, and documentation.
+Treat an API change as a contract change, not as a route or controller edit. The contract includes request schema, response schema, status code, headers, content negotiation, cache semantics, error shape, auth and permission behavior, pagination, filtering, sorting, search semantics, generated clients, SDKs, mocks, fixtures, examples, and documentation.
 
 The goal is to keep runtime behavior, type contracts, generated artifacts, callers, tests, and docs aligned.
 
@@ -37,10 +37,11 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 ## Use When
 
 - HTTP, REST, RPC, GraphQL, tRPC, Hono RPC, Elysia Eden, gRPC, protobuf, OpenAPI, AsyncAPI, webhook, callback, public endpoint, internal endpoint, generated client, SDK, schema, mock, fixture, or API docs behavior changes.
-- Request body, query parameters, path parameters, headers, cookies, response body, status codes, redirects, caching headers, rate-limit headers, error envelopes, validation errors, auth errors, or permission errors change.
+- Request body, query parameters, path parameters, headers, cookies, response body, content negotiation, content coding, status codes, redirects, caching headers, rate-limit headers, error envelopes, validation errors, auth errors, or permission errors change.
+- SSE, streaming response, WebTransport handshake, WebSocket fallback, compression negotiation, or delivery headers become part of the API behavior that callers rely on.
 - Pagination, filtering, sorting, search, includes, field selection, sparse fields, expansions, cursor shape, or total-count semantics change.
 - A route is renamed, moved, split, merged, deprecated, versioned, or made more restrictive.
-- A framework-specific API surface changes and may need another skill as a follow-up, such as `hono-code-change`, `elysia-code-change`, `typescript-code-change`, `auth-permission-change`, or `security-regression-tests`.
+- A framework-specific API surface changes and may need another skill as a follow-up, such as `hono-code-change`, `elysia-code-change`, `typescript-code-change`, `http-delivery-streaming`, `auth-permission-change`, or `security-regression-tests`.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -53,7 +54,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 ## Required Inputs
 
 - Changed route, controller, resolver, handler, schema, validator, generated client, SDK, tests, fixtures, mocks, and docs.
-- Current request and response schema, status code map, headers, error envelope, auth and permission behavior, rate-limit behavior, cache behavior, pagination/filter/sort/search contract, and deprecation/versioning policy.
+- Current request and response schema, status code map, headers, content negotiation, content coding, error envelope, auth and permission behavior, rate-limit behavior, cache behavior, streaming or reconnect behavior, pagination/filter/sort/search contract, and deprecation/versioning policy.
 - OpenAPI, GraphQL schema, tRPC router, Hono app type, Elysia Eden type surface, protobuf files, generated clients, SDK examples, frontend callers, mobile callers, integration tests, docs examples, and mock servers when present.
 - Current public consumers, backwards-compatibility expectations, supported client versions, and migration or deprecation policy.
 - Configured verification intents.
@@ -65,6 +66,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 - Identify whether the change is source-compatible, runtime-compatible, behavior-compatible, or breaking for existing callers.
 - Read the schema and generated client source of truth before editing route code.
 - If auth, permission, tenant, object-level access, or API key behavior changes, also apply `auth-permission-change`.
+- If compression, content coding, streaming responses, SSE, WebTransport, WebSocket fallback, proxy buffering, CDN behavior, or browser delivery behavior changes, also apply `http-delivery-streaming`.
 - If the change needs denied-abuse coverage, also apply `security-regression-tests`.
 
 <!-- mustflow-section: allowed-edits -->
@@ -86,7 +88,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
    - auth and permission requirement;
    - response success status and body;
    - error status and body;
-   - relevant headers;
+   - relevant headers, content negotiation, content coding, and cache variance;
    - pagination, filtering, sorting, and search semantics;
    - generated clients, SDK functions, mocks, fixtures, examples, and docs.
 3. Classify each change:
@@ -96,6 +98,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
    - response field removed, renamed, narrowed, widened, or made nullable;
    - status code changed;
    - header added, removed, or changed;
+   - content coding, compression negotiation, streaming, reconnect, or cache-variance behavior changed;
    - error code or envelope changed;
    - pagination cursor or total semantics changed;
    - auth/permission requirement changed;
@@ -109,7 +112,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 
 ## API Style Policy
 
-- REST and HTTP APIs must keep method semantics, status code meanings, headers, content type, cache behavior, redirects, and error envelope stable.
+- REST and HTTP APIs must keep method semantics, status code meanings, headers, content type, content coding, cache behavior, redirects, streaming behavior, and error envelope stable.
 - OpenAPI changes must include every status/body/header variant that callers rely on. A schema-only success response is not enough when errors are part of the contract.
 - GraphQL must not be forced into a REST envelope. Preserve GraphQL `data`, `errors`, `extensions`, partial response, nullability, and resolver error propagation semantics.
 - GraphQL nullable-to-non-null and non-null-to-null changes are contract changes. Nullability can change whether partial data survives an error.
@@ -128,7 +131,7 @@ The goal is to keep runtime behavior, type contracts, generated artifacts, calle
 - Pagination must define cursor opacity, sort stability, page size limits, `next` and `previous` meaning, empty page behavior, total-count semantics, and whether filters affect counts.
 - Filtering and sorting must define allowed fields, default sort, null ordering, case sensitivity, timezone or locale behavior, invalid filter behavior, and whether unknown fields are rejected or ignored.
 - Search must define query normalization, tokenization, ranking stability expectations, highlight fields, typo tolerance, permissions, and private-data exclusion.
-- Headers such as cache-control, etag, location, retry-after, rate-limit, pagination links, content-disposition, and deprecation headers are contract surfaces.
+- Headers such as content-type, content-encoding, vary, cache-control, etag, location, retry-after, rate-limit, pagination links, content-disposition, and deprecation headers are contract surfaces.
 
 ## Dependent Surface Checklist
 
@@ -144,6 +147,7 @@ Check every relevant surface before finalizing:
 - API docs, README snippets, changelog, migration notes, deprecation notices, role matrix, and status-code docs;
 - auth and permission checks;
 - rate limits, cache keys, cache headers, search indexes, pagination cursors, and background jobs;
+- streaming delivery, SSE event ids, reconnect behavior, proxy or CDN delivery settings, content-coding variants, and fallback clients when they are caller-visible;
 - observability dashboards, audit logs, analytics events, and alerting that parse status or error codes.
 
 ## Strongly Forbidden Patterns
@@ -152,6 +156,7 @@ Check every relevant surface before finalizing:
 - Returning raw database rows as API responses.
 - Treating TypeScript inference as proof that runtime JSON is compatible.
 - Changing status codes without updating callers, docs, tests, and audit expectations.
+- Changing content encoding, streaming flush, reconnect, cache variance, or fallback behavior without updating callers, docs, tests, and delivery verification.
 - Treating generated clients as disposable when they are the public API.
 - Mixing GraphQL partial-response semantics with REST success/error envelopes.
 - Adding required request fields in a minor-compatible change without a default or compatibility path.
@@ -166,7 +171,7 @@ Check every relevant surface before finalizing:
 ## Postconditions
 
 - The API contract source of truth is known.
-- Request, response, status, header, error, auth, permission, pagination, filtering, sorting, and search impacts are classified.
+- Request, response, status, header, content negotiation, cache, error, auth, permission, pagination, filtering, sorting, and search impacts are classified.
 - Breaking or compatibility-sensitive changes are named.
 - Generated clients, mocks, fixtures, tests, docs, and examples are synchronized or explicitly reported as skipped.
 - Framework-specific protocol semantics are preserved.
@@ -204,7 +209,7 @@ Prefer the narrowest configured checks that exercise the changed contract from a
 - API style and contract source of truth
 - Changed operations or endpoints
 - Compatibility classification
-- Request, response, status, header, error, auth, permission, pagination, filter, sort, and search notes
+- Request, response, status, header, content negotiation, cache, error, auth, permission, pagination, filter, sort, and search notes
 - Generated client, SDK, mock, fixture, docs, and caller surfaces synchronized
 - Files changed
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/auth-permission-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.auth-permission-change
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: auth-permission-change
-description: Apply this skill when authentication, authorization, permissions, roles, tenants, sessions, JWTs, OAuth or OIDC, API keys, route guards, admin access, database policies, or object-level access control are created or changed.
+description: Apply this skill when authentication, authorization, permissions, roles, tenants, sessions, JWTs, OAuth or OIDC, API keys, route guards, admin access, database policies, object-level access control, signed delivery URLs, credentialed event streams, or private cache behavior are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -39,6 +39,7 @@ Authentication answers who the requester is. Authorization answers what that pri
 - Authentication, authorization, role, permission, capability, policy, tenant, workspace, organization, session, JWT, OAuth, OIDC, API key, invite, reset token, route guard, admin, impersonation, audit, or database policy behavior changes.
 - A route, resolver, controller, service, command handler, job, webhook, API client, generated SDK, UI guard, or database query starts relying on user, tenant, role, ownership, membership, or resource identity.
 - A change affects object-level access control, multi-tenant isolation, shared resources, signed URLs, exports, search, autocomplete, background jobs, webhooks, or admin/support tooling.
+- A change affects credentialed EventSource/SSE streams, WebTransport sessions, WebSocket fallback, signed delivery URLs, private file delivery, CDN/proxy cache keys, CORS credentials, cookies, or auth tokens embedded in delivery URLs.
 - A change modifies status code behavior for auth failures, especially 401, 403, or policy-driven 404.
 - A permission model, role matrix, API docs, admin docs, migration, or tests need to stay aligned with authorization behavior.
 
@@ -56,7 +57,7 @@ Authentication answers who the requester is. Authorization answers what that pri
 - Auth middleware, framework hooks, gateway checks, session config, cookie config, JWT verifier, OAuth/OIDC callback, API key verifier, and logout or revocation code when relevant.
 - Route guards, client guards, server controllers, resolvers, command handlers, services, policy functions, role or permission tables, database queries, RLS, views, stored procedures, and ORM scopes.
 - Tenant, organization, workspace, project, membership, invite, suspension, ownership, sharing, and admin-support data models.
-- Background jobs, queue payloads, webhooks, import/export flows, search or autocomplete indexes, signed URL generation, storage keys, CDN cache, and permission caches when they can expose protected data.
+- Background jobs, queue payloads, webhooks, import/export flows, search or autocomplete indexes, signed URL generation, storage keys, SSE or streaming channels, WebTransport sessions, WebSocket fallback, CDN cache, proxy cache, and permission caches when they can expose protected data.
 - Audit logs, admin action logs, impersonation records, denied-access logs, API docs, role matrix docs, migrations, and tests.
 - Configured verification intents.
 
@@ -68,6 +69,7 @@ Authentication answers who the requester is. Authorization answers what that pri
 - Treat client-provided `userId`, `tenantId`, `workspaceId`, `role`, `isAdmin`, object id, API key label, token claim, and local storage value as untrusted.
 - Find the current policy source of truth. If authorization is scattered across routes, do not add another scattered condition without first considering a central policy function.
 - Know whether the product intentionally hides resource existence with 404 or exposes permission denial with 403.
+- If SSE, WebTransport, WebSocket fallback, signed URL, CORS, cookie, CDN cache, proxy cache, or streaming delivery behavior changes, use `http-delivery-streaming` for the transport contract while this skill checks access control.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -88,7 +90,7 @@ Authentication answers who the requester is. Authorization answers what that pri
    - route guards, client redirects, server controllers, resolvers, services, command handlers, policy calls, and admin tools;
    - tenant resolver, membership schema, role assignment, invite flow, suspension, ownership, sharing, and impersonation model;
    - database queries, tenant scopes, ownership joins, soft-delete filters, RLS, views, stored procedures, and ORM helpers;
-   - background jobs, queues, webhooks, import/export, file storage, signed URLs, search, autocomplete, caches, audit logs, docs, migrations, and tests.
+   - background jobs, queues, webhooks, import/export, file storage, signed URLs, SSE or streaming channels, WebTransport sessions, WebSocket fallback, search, autocomplete, caches, CDN or proxy cache rules, audit logs, docs, migrations, and tests.
 3. Write the permission decision inputs for each protected action: principal, tenant, resource, action, and context.
 4. Separate identity from permission:
    - `req.user`, a valid session, verified email, valid JWT, OAuth scope, or API key proves identity only;
@@ -104,12 +106,14 @@ Authentication answers who the requester is. Authorization answers what that pri
    - tenant-scoped queries must include tenant or membership constraints;
    - pending, suspended, removed, revoked, deleted, disabled, and invited states must not be treated as active access;
    - shared links, exports, signed URLs, previews, search, cache, and CDN entries must stay inside the permission model.
+   - event streams, WebTransport sessions, WebSocket fallback channels, private downloads, and reconnect URLs must not bypass tenant, resource, role, token expiry, or revocation policy.
 10. Check session, JWT, OAuth/OIDC, and API key contracts when touched:
    - sessions need expiry, refresh, rotation, logout, revocation, cookie flags, and CSRF posture;
    - JWTs need signature verification, algorithm allowlist, issuer, audience, subject, expiry, not-before, key rotation, and stale-claim handling;
    - OAuth/OIDC needs exact redirect binding, state, nonce, PKCE when relevant, provider account binding, and safe account linking;
    - API keys need hashing, prefix-only display, owner type, scope, tenant/resource constraints, expiry, rotation, revocation, last-used, rate limit, and audit.
 11. Check dependent surfaces: API routes, controllers, services, DB schema, DB queries, RLS, UI navigation, UI actions, API clients, audit logs, notifications, jobs, webhooks, search, file storage, docs, migrations, monitoring, and tests.
+    - For credentialed delivery surfaces, check whether EventSource can supply the intended credentials, whether CORS and cookies match the policy, whether signed URLs expire and scope correctly, and whether caches vary on auth, tenant, and private response dimensions.
 12. Require denial-first tests for changed protected actions when the project has a usable test surface. Cover anonymous, expired, revoked, no role, wrong tenant, wrong owner, suspended or removed member, stale cache, shared-link, read-only API key, org admin, global admin, and impersonating admin cases as applicable.
 13. Update docs and role matrices when external behavior, status codes, role names, permission names, admin scope, or API errors change.
 14. Report the policy source of truth, server/database enforcement, client UX-only guards, test coverage, skipped checks, and remaining permission risk.
@@ -139,6 +143,7 @@ Authentication answers who the requester is. Authorization answers what that pri
 - Relaxing permissions without denial-case tests or a written migration and audit plan.
 - Letting role changes ship without permission-cache or token-staleness handling.
 - Creating shared links, signed URLs, exports, search results, or CDN responses outside tenant and resource policy.
+- Creating credentialed event streams, WebTransport sessions, WebSocket fallback channels, signed delivery URLs, or private caches outside tenant and resource policy.
 - Logging impersonation without separate actor and subject.
 - Backfilling broad permissions to every existing user because migration is easier.
 
@@ -150,6 +155,7 @@ Authentication answers who the requester is. Authorization answers what that pri
 - Tenant isolation, resource ownership, sharing, admin scope, and status-code behavior are explicit.
 - Client guards are described as UX only.
 - Session, token, OAuth/OIDC, API key, cache, audit, docs, migration, and tests are synchronized when touched.
+- Signed URL, event-stream, WebTransport, WebSocket fallback, CORS, cookie, CDN/proxy cache, and reconnect behavior remains inside the permission model when touched.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -187,6 +193,7 @@ Prefer the narrowest configured test intent that covers the changed protected ac
 - Server/database enforcement notes
 - Client guard UX-only notes
 - Tenant, ownership, sharing, admin, token/session/API-key, cache, and audit notes
+- Event stream, WebTransport, WebSocket fallback, signed URL, CORS, cookie, and CDN/proxy cache notes when relevant
 - Tests or denial cases covered
 - Files changed
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/backend-reliability-change/SKILL.md

@@ -0,0 +1,289 @@
+---
+mustflow_doc: skill.backend-reliability-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: backend-reliability-change
+description: Apply this skill when backend APIs, workers, jobs, queues, caches, database write paths, external service calls, health checks, observability, feature flags, idempotency, retries, outbox/inbox processing, or operational failure handling are created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.backend-reliability-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Backend Reliability Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep backend changes safe under retries, slow dependencies, duplicate messages, partial failures,
+cache misses, operational probes, and production debugging pressure.
+
+Backend reliability is not a framework feature. It is the set of small contracts that stop one
+request, job, tenant, cache miss, retry loop, or external provider outage from turning into a
+system-wide incident. Prefer explicit idempotency, bounded waiting, database-enforced facts,
+low-cardinality telemetry, and reversible rollout switches over optimistic controller code.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A backend route, RPC handler, command handler, webhook, mutation, job, worker, queue consumer,
+  scheduled task, or integration path is created, changed, reviewed, or reported.
+- Code handles write APIs, retries, timeouts, cancellation, external HTTP/RPC/database/cache calls,
+  payment or provider calls, health checks, readiness, startup, graceful degradation, or fallback
+  behavior.
+- Code changes idempotency keys, request fingerprints, duplicate handling, final response replay,
+  outbox publishing, inbox deduplication, dead-letter queues, poison messages, queue retention,
+  backoff, jitter, or consumer concurrency.
+- Code changes database uniqueness, constraints, indexes, soft-delete uniqueness, cursor
+  pagination, lock usage, table-backed queues, `FOR UPDATE SKIP LOCKED`, advisory locks,
+  distributed locks, or transaction boundaries.
+- Code changes cache keys, cache TTLs, negative caching, request coalescing, stampede prevention,
+  cache authority, tenant-aware caching, or stale-data behavior.
+- Code changes logs, metrics, traces, correlation ids, OpenTelemetry baggage, audit records,
+  alert inputs, feature flags, rollout gates, kill switches, or operational admin actions.
+- A final report claims a backend path is safe to retry, resilient, scalable, observable,
+  production-ready, fault-tolerant, idempotent, cache-safe, queue-safe, or easy to debug.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only an architecture split or service ownership decision with no concrete backend
+  implementation surface; use `service-boundary-architecture`.
+- The task is only an API schema/status/header change with no operational failure behavior; use
+  `api-contract-change`.
+- The task is only database-engine-specific DDL, query, or migration work; use the matching
+  database skill first, then this skill only for retries, queues, cache, observability, or
+  operational behavior around that database path.
+- The task is purely frontend rendering, styling, or browser delivery behavior.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Backend surface: route, handler, worker, queue, scheduled job, database write path, cache path,
+  provider integration, health probe, feature flag, or admin operation.
+- Trigger shape: user request, webhook, retry, scheduled run, queue message, backfill, migration,
+  manual operator action, startup, shutdown, or dependency callback.
+- Idempotency boundary: principal, tenant, resource, action, request fingerprint, key storage,
+  in-progress state, final response, conflict behavior, TTL, and replay contract.
+- External-call boundary: dependency owner, deadline, cancellation propagation, connect/request/read
+  or write timeout support, retryable errors, retry budget, backoff, jitter, and fallback behavior.
+- Persistence and transaction boundary: unique facts, constraints, indexes, lock scope, transaction
+  length, outbox/inbox tables, query evidence, pagination keys, and migration safety needs.
+- Queue or async boundary: delivery semantics, ordering assumptions, duplicate handling, poison
+  handling, dead-letter policy, retention, backlog metrics, consumer concurrency, and replay tools.
+- Cache boundary: key dimensions, tenant/auth scope, TTL, jitter, negative caching, coalescing,
+  stale/error behavior, invalidation, and whether cached data is allowed to be wrong.
+- Observability boundary: request id, trace id, correlation id, log fields, metrics labels,
+  alert inputs, sensitive data exclusions, audit fields, and debugging path.
+- Rollout boundary: feature flag, kill switch, default state, rollout scope, rollback or disable
+  behavior, and user-visible degradation.
+- Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow
+  validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the
+  current scope.
+- If request/response schema, status code, headers, pagination, cache headers, or generated clients
+  change, also use `api-contract-change`.
+- If service ownership, data source of truth, tenant isolation, event contract, or module split
+  decisions change, also use `service-boundary-architecture`.
+- If database schema, migration, query plan, index, transaction isolation, or engine-specific lock
+  behavior changes, also use `database-migration-change`, `database-change-safety`, or the matching
+  database engine skill.
+- If authentication, authorization, object-level access, tenant isolation, secrets, personal data,
+  logs, telemetry, retention, or audit behavior changes, also use `auth-permission-change`,
+  `security-privacy-review`, or `security-regression-tests`.
+- If performance, p95/p99 latency, throughput, queue depth, connection pool pressure, cache hit
+  rate, or cost is claimed, also use `performance-budget-check`.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update backend handlers, services, workers, retry policy, timeout policy, idempotency storage,
+  outbox/inbox code, cache boundaries, health endpoints, observability fields, flags, tests, docs,
+  and directly synchronized templates tied to the reliability behavior.
+- Add or tighten tests for duplicate requests, retry replay, same idempotency key with a different
+  request fingerprint, timeout/cancellation, dependency failure, queue redelivery, cache miss,
+  stale data, object-level denial, DTO allowlists, and kill-switch behavior.
+- Do not replace missing reliability contracts with comments that say "should be idempotent",
+  "eventually consistent", "handled by the queue", or "covered by Kubernetes" without executable
+  behavior, storage constraints, or operational evidence.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the backend surface and failure multiplier. Name whether the change is a write API,
+   read API, webhook, provider call, worker, queue consumer, cache path, database write path, health
+   probe, admin action, or rollout gate. Identify what repeats under failure: user retries,
+   client retries, load balancer retries, server retries, queue redelivery, scheduled reruns, or
+   operator replay.
+2. For write APIs and side effects, build an idempotency ledger.
+   - Scope the idempotency key by tenant, principal, action, and resource so one actor cannot replay
+     another actor's operation.
+   - Store the idempotency key, request fingerprint or hash, processing state, final status/body or
+     result reference, timestamps, TTL, and owner.
+   - Return the saved result for the same key and same request fingerprint after the operation
+     commits. Reject or conflict the same key with a different request fingerprint.
+   - Define the in-progress response when the first request is still running. Avoid running the
+     side effect twice just because the first response was lost.
+3. Bound all external waiting.
+   - Propagate an end-to-end deadline or cancellation signal across internal calls, DB calls, cache
+     calls, provider calls, and queue work when the platform supports it.
+   - Configure connect, request, read, and write timeouts separately when the client exposes them;
+     otherwise document the closest supported boundary.
+   - Retry only operations that are idempotent or guarded by an idempotency key. Use bounded retry
+     counts, exponential backoff, jitter, and a retry budget. Avoid stacked retries at every layer.
+   - Define fallback, degradation, or user-visible failure behavior instead of waiting forever.
+4. Split operational health checks.
+   - Keep `/live` shallow: process is running and the event loop or runtime is not wedged. Do not
+     put database, cache, or external-provider checks in liveness.
+   - Put dependency availability in `/ready` only when traffic should be removed if the dependency
+     is unavailable. Make readiness cheap, bounded, and resistant to cascading probe load.
+   - Use `/startup` or an equivalent startup probe when initialization can legitimately take longer
+     than normal liveness timing.
+5. Enforce facts in the database, not only in application code.
+   - Use a unique constraint or unique index for facts that must be globally unique. Do not rely on
+     a read-then-insert check in application code.
+   - For soft deletes, use a partial unique index or an explicit active-state uniqueness strategy
+     when the database supports it.
+   - Handle duplicate-key conflicts as a normal path. Convert the database decision into the same
+     domain result a retried request should see.
+   - For PostgreSQL query and index changes, gather `EXPLAIN ANALYZE` with buffer evidence when
+     available, inspect `pg_stat_statements` or equivalent workload evidence when present, and
+     respect online index, lock-timeout, and expand-contract migration procedures.
+   - For pagination, prefer a stable compound cursor over deep `OFFSET` when data can grow or
+     mutate while users page.
+6. Keep observability useful and low-risk.
+   - Use structured logs with request id, trace id, correlation id, tenant-safe identifiers, route
+     name, operation name, dependency name, result class, duration, retry count, and idempotency
+     outcome where useful.
+   - Do not put secrets, tokens, raw request bodies, full personal data, payment data, or unbounded
+     payloads in logs, traces, metrics, OpenTelemetry baggage, queue dead letters, or audit comments.
+   - Keep metrics labels low-cardinality. Do not label metrics by user id, email, raw URL, request
+     body, trace id, order id, idempotency key, or provider payload id. Put high-cardinality details
+     in logs or traces instead.
+   - Follow one request through API, queue, worker, provider, and database with the same correlation
+     or trace id when possible.
+7. Treat cache as a consistency and failure contract.
+   - Include tenant, auth, locale, variant, and resource dimensions in cache keys when they affect
+     visibility or meaning.
+   - Define TTL, invalidation, stale-data allowance, error fallback, hit/miss metrics, max size, and
+     cache authority. Name when a cached value may be wrong and for how long.
+   - Add stampede protection: request coalescing, single-flight, prewarming, TTL jitter, soft TTLs,
+     or bounded regeneration. Use negative caching for expensive missing values only with a short
+     and intentional TTL.
+8. Make async consumers safe for at-least-once delivery.
+   - Assume messages can be delivered more than once, out of order, after the original request
+     timed out, or after a deploy.
+   - Use an inbox table or equivalent durable deduplication keyed by event id or message id for
+     side-effecting consumers.
+   - Use an outbox pattern or equivalent transactional publication when a database state change and
+     event publish must agree.
+   - Define poison-message handling, dead-letter storage, retry schedule, jitter, retention, replay,
+     backlog age, and consumer scaling triggers.
+   - For PostgreSQL table-backed queues, prefer row locks such as `FOR UPDATE SKIP LOCKED` when the
+     schema and workload fit. Treat distributed locks as a last resort after unique constraints,
+     state machines, row locks, or advisory locks are ruled out.
+9. Keep authorization and DTO boundaries server-side.
+   - Check object-level authorization on every backend path that accepts a resource id, event id,
+     object id, file id, tenant id, or provider id. Do not trust client-side filtering or hidden UI.
+   - Return allowlisted DTOs instead of raw ORM entities, provider payloads, or internal records.
+     Keep public response fields separate from database columns.
+10. Put risky behavior behind controllable rollout gates.
+   - Use server-side feature flags for risky paths, external provider changes, queue consumers,
+     cache authority changes, and new failure behavior.
+   - Include a kill switch, safe default, rollout scope, audit or metric evidence, and cleanup plan.
+     Do not use a flag to hide an unsafe migration or permanent forked behavior.
+11. Select verification from the command contract.
+   - Prefer focused tests that prove duplicate execution, timeout, retry, queue redelivery, cache
+     miss, BOLA denial, DTO allowlist, health-probe split, and kill-switch behavior.
+   - Run configured test, build, docs, release, and mustflow intents only. Report missing backend
+     reliability verification instead of inventing raw service, database, or cluster commands.
+
+<!-- mustflow-section: forbidden-patterns -->
+## Strongly Avoid
+
+- Accepting the same idempotency key with a different request fingerprint.
+- Retrying a non-idempotent provider call without an idempotency key or durable side-effect guard.
+- Adding retries without a deadline, bounded attempt count, backoff, jitter, and retry budget.
+- Letting every layer retry the same failing dependency.
+- Putting database, cache, provider, or queue checks in liveness.
+- Treating a queue as proof that backpressure, retention, dead letters, or replay are solved.
+- Publishing an event outside the same durable boundary as the state change it describes when the
+  event is critical.
+- Using application read-then-insert logic as the uniqueness guarantee.
+- Returning raw ORM entities or provider payloads from an API.
+- Logging tokens, raw request bodies, personal data, or high-cardinality metric labels.
+- Using distributed locks as the first solution to duplicate work.
+- Relying on `OFFSET` pagination for large or frequently mutated result sets.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+- Prefer the narrowest configured test intent that exercises the changed reliability contract:
+  duplicate request replay, different request fingerprint conflict, dependency timeout, bounded
+  retry, queue redelivery, cache miss or stampede guard, health-probe split, object-level denial,
+  DTO allowlist, and kill-switch behavior.
+- Use `test_related` for code or behavior changes when related tests cover the touched backend
+  surface. Use `test` only when the reliability behavior crosses broad shared infrastructure.
+- Use `docs_validate_fast` when skill, workflow, docs, examples, or template text changes.
+- Use `test_release` when package metadata, template manifest, install surface, release notes, or
+  version metadata changes.
+- Use `mustflow_check` after mustflow-owned skill, route, template, or command-contract changes.
+- Report missing evidence explicitly when the repository has no configured provider, database,
+  queue, load, cluster, or integration check for the changed reliability surface.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If verification fails, preserve the failing intent, failing assertion or output tail, and the
+  backend reliability surface it exercised before editing again.
+- If the failure involves missing or stale required skill sections, route metadata, template
+  manifest entries, i18n metadata, or installed-template sync, fix the contract surface first and
+  rerun the same configured intent.
+- If a runtime test reveals duplicate execution, unbounded retry, stale cache authority, liveness
+  dependency checks, missing object-level authorization, raw DTO exposure, or telemetry leakage,
+  treat the failure as a contract bug. Do not weaken the test without stronger repository evidence.
+- If the needed proof requires live provider, queue, database, Kubernetes, or load-test access not
+  configured in `.mustflow/config/commands.toml`, stop at local verification and report the missing
+  operational evidence instead of inventing commands.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Idempotency, retry, timeout, queue, cache, database, health-probe, observability, auth, DTO, and
+  rollout behavior have been classified or explicitly marked out of scope.
+- Duplicate execution, partial failure, slow dependency, redelivery, stale cache, and operational
+  debugging paths have concrete behavior, not just prose promises.
+- Sensitive data and high-cardinality telemetry risks have been checked.
+- Tests, docs, templates, and release metadata changed by the backend reliability behavior are
+  synchronized.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+Include in the final report when this skill is used:
+
+- Backend surface and selected reliability boundary.
+- Idempotency, retry/timeout, queue/cache/database, health-probe, observability, auth/DTO, and
+  rollout decisions that changed or were verified.
+- Tests or configured command intents run.
+- Remaining backend reliability risk, especially missing load, provider, database, or cluster
+  evidence.

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.css-code-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: css-code-change
-description: Apply this skill when CSS, Sass, Less, CSS Modules, CSS-in-JS, global styles, cascade layers, selector specificity, design tokens, layout, responsive behavior, focus styles, animation, color, or component styling are created or changed.
+description: Apply this skill when CSS, Sass, Less, CSS Modules, CSS-in-JS, global styles, cascade layers, selector specificity, design tokens, container queries, browser-native state selectors, layout, responsive behavior, focus styles, animation, color, or component styling are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -34,7 +34,7 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 ## Use When
 
 - `.css`, Sass, Less, CSS Modules, CSS-in-JS, global styles, reset, theme variables, cascade layers, selectors, design tokens, component styles, animations, or responsive rules change.
-- The task touches specificity, `!important`, inline styles, negative margins, layout shift, browser compatibility, dark mode, focus style, contrast, typography, zoom, text scaling, or motion preference.
+- The task touches specificity, `!important`, inline styles, negative margins, layout shift, browser compatibility, dark mode, focus style, contrast, typography, zoom, text scaling, container queries, browser-native state selectors, viewport units, content visibility, or motion preference.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -48,6 +48,7 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 - Global CSS entrypoints, reset/base styles, cascade layer strategy, token files, theme config, component CSS, parent layout styles, browserslist, build config, and style lint config.
 - Existing responsive, dark mode, accessibility, focus, reduced-motion, breakpoint, and design-token conventions.
 - Target surfaces for narrow viewports, 200% zoom, text scaling, delayed media, third-party markup, and browser compatibility.
+- Browser-native capabilities in use or available for the target: cascade layers, `:where`, `:is`, `:has`, container queries, logical properties, `dvh`/`svh`/`lvh`, `color-scheme`, `content-visibility`, `contain-intrinsic-size`, `text-wrap`, and view-transition styling.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
@@ -62,6 +63,7 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 
 - Add styles in the correct layer or module.
 - Use class-level selectors, custom properties, design tokens, intrinsic sizing, flex, grid, container queries, or media queries according to local patterns.
+- Use browser-native selectors, layout, and containment features as progressive enhancement when they reduce JavaScript ownership and fit the browser target.
 - Preserve visible focus, contrast, text scaling, reduced motion, and reserved space for late-loaded media.
 - Use narrow exceptions for legacy/third-party markup, runtime geometry, rich text/prose wrappers, and urgent accessibility overrides when lower-specificity or token-based fixes cannot solve the issue.
 
@@ -77,17 +79,22 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 7. Use existing color, spacing, font, radius, shadow, z-index, and breakpoint tokens before adding literals.
 8. Keep raw color values out of component CSS. Add or reuse semantic tokens for surfaces, text, borders, actions, danger states, focus, disabled states, and dark mode.
 9. Avoid raw pixel values for typography, spacing, layout dimensions, and radius. Allow narrow values such as one-pixel borders, intrinsic icon/media dimensions, and established breakpoint tokens.
-10. Make layout responsive through constraints, `min-width: 0`, min/max sizing, flex/grid, wrapping, gap, intrinsic media dimensions, container/media queries, and content-based rules rather than fixed viewport assumptions.
-11. Do not set fixed width on page, section, container, card, modal, or form layouts. Do not set fixed height on components that contain text.
-12. Do not use viewport-only typography. Use bounded responsive type patterns that survive small screens and large displays.
-13. Do not use `overflow: hidden` to hide layout bugs. Allow it only for intentional clipping such as avatars, media crops, masks, or animation containers.
-14. Reserve dimensions or aspect ratio for images, videos, iframes, ads, embeds, skeletons, fonts, and lazy content that could cause layout shift.
-15. Preserve visible focus, sufficient contrast, 200% text resize behavior, text-spacing stress, keyboard navigation, and reduced-motion behavior.
-16. If hover styling changes an interactive affordance, provide a matching focus-visible affordance.
-17. Prefer outline and outline-offset for focus indicators. Do not rely only on shadows when ancestors may clip overflow.
-18. Respect reduced motion for parallax, large transforms, auto-scroll, route transitions, autoplay carousels, skeleton shimmer, and looping decorative animation.
-19. Check browser compatibility before adding new CSS features. Use progressive enhancement for newly available features and avoid limited-availability features unless the project browser target allows them.
-20. Choose configured verification intents that cover style lint, build, visual states, accessibility, and browser target risk when available.
+10. Make layout responsive through constraints, `min-width: 0`, `min-height: 0`, min/max sizing, flex/grid, wrapping, gap, intrinsic media dimensions, container/media queries, logical properties, and content-based rules rather than fixed viewport assumptions.
+11. Prefer named containers and container queries when a component responds to its actual slot, not the whole viewport. Keep media queries for page-level viewport decisions.
+12. Do not set fixed width on page, section, container, card, modal, or form layouts. Do not set fixed height on components that contain text.
+13. Use dynamic viewport units intentionally: `dvh` for current viewport height, `svh` for stable small viewport layout, and `lvh` only when the larger viewport behavior is intended. Avoid hard `100vh` for mobile app shells unless the target proves safe.
+14. Do not use viewport-only typography. Use bounded responsive type patterns that survive small screens and large displays.
+15. Do not use `overflow: hidden` to hide layout bugs. Allow it only for intentional clipping such as avatars, media crops, masks, or animation containers.
+16. Reserve dimensions or aspect ratio for images, videos, iframes, ads, embeds, skeletons, fonts, and lazy content that could cause layout shift.
+17. Prefer `:where` to keep wrapper and rich-text selector specificity low. Use `:has` only when it improves state ownership and the fallback remains usable for target browsers.
+18. Use `content-visibility` only for offscreen or below-the-fold content whose skipped rendering will not hide focus targets, search-relevant initial content, or accessibility-critical relationships. Pair it with `contain-intrinsic-size` to avoid layout jumps.
+19. Use `color-scheme` with theme tokens so native controls, scrollbars, and form UI match the active theme before component JavaScript runs.
+20. Preserve visible focus, sufficient contrast, 200% text resize behavior, text-spacing stress, keyboard navigation, and reduced-motion behavior.
+21. If hover styling changes an interactive affordance, provide a matching focus-visible affordance.
+22. Prefer outline and outline-offset for focus indicators. Do not rely only on shadows when ancestors may clip overflow.
+23. Respect reduced motion for parallax, large transforms, auto-scroll, route transitions, autoplay carousels, skeleton shimmer, and looping decorative animation.
+24. Check browser compatibility before adding new CSS features. Use progressive enhancement for newly available features and avoid limited-availability features unless the project browser target allows them.
+25. Choose configured verification intents that cover style lint, build, visual states, accessibility, and browser target risk when available.
 
 <!-- mustflow-section: cascade-specificity-policy -->
 ## Cascade And Specificity Policy
@@ -96,6 +103,7 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 - Do not use IDs as styling weight. IDs are for anchors, form/ARIA relationships, or JavaScript hooks.
 - Do not write DOM-path selectors that break when markup gains or loses a wrapper.
 - Use low-specificity contextual selectors for rich text or CMS areas. Prefer patterns that keep specificity easy to override.
+- Use `:where` for low-specificity grouping and `@layer` for order. Do not use `:is` or `:has` to smuggle in heavy selectors when a class boundary would be clearer.
 - Do not add global overrides for local component problems when component-scoped styling or tokens can solve the issue.
 - New `!important` requires an explicit exception for immutable third-party/legacy markup, third-party inline style override, urgent accessibility protection, or equivalent narrow reason.
 
@@ -107,6 +115,7 @@ Preserve cascade order, specificity discipline, resilient responsive layout, des
 - Prefer min-height, padding, and line-height over fixed height for text-containing controls.
 - Prefer content-based layout, flex/grid, `minmax`, wrapping, and `clamp` over breakpoint patching.
 - Avoid `100vw` except for deliberate full-bleed designs; otherwise prefer normal containing-block width.
+- Avoid `100vh` for mobile app shells when browser chrome can change the visual viewport. Choose `dvh`, `svh`, or a layout-owned min-height intentionally.
 - Avoid absolute positioning for normal document flow. Use it only for overlays, decorative placement, controls anchored to known boxes, or measured geometry.
 
 <!-- mustflow-section: token-accessibility-policy -->
@@ -151,6 +160,7 @@ Reject the change when:
 - It uses fixed width for containers or fixed height for text-containing UI.
 - It hides layout bugs with `overflow: hidden`.
 - It adds unsized media, embeds, ads, or lazy content that can shift layout.
+- It uses `content-visibility` without an intrinsic-size fallback or on content that must be immediately reachable.
 - It hardcodes raw component colors, spacing, font sizes, radius, or shadows without an exception.
 - It removes focus styling, creates hover-only affordances, or clips the focus indicator.
 - It adds motion without reduced-motion behavior.