mustflow 2.22.16 → 2.22.46

package/templates/default/locales/en/.mustflow/skills/security-regression-tests/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.security-regression-tests
 locale: en
 canonical: true
-revision: 9
+revision: 11
 lifecycle: mustflow-owned
 authority: procedure
 name: security-regression-tests
@@ -32,11 +32,13 @@ Convert security-sensitive behavior changes into safe negative tests that preser
 
 - Authentication, authorization, session, CSRF, rate-limit, admin, payment, credit, subscription, personal-data, or tenant-boundary behavior changes.
 - Input validation, output encoding, file upload, path handling, webhook callback, redirect, or external URL handling changes.
+- Public action, webhook, callback, replay, job enqueue, idempotency, deduplication, or in-memory intake-store behavior changes.
 - Cookie, JWT, OAuth callback, reset token, invite token, logout, reauthentication, file download, upload processing, business-rule, entitlement, pricing, inventory, database query, ORM bulk operation, or deployment-configuration behavior changes.
 - AI-generated or vibe-coded routes, data access, external fetchers, admin screens, or database rules need denied-case coverage beyond a happy-path test.
 - Cryptography, password hashing, secure randomness, HTTPS/TLS, certificate validation, scanner-gate, or security-invariant behavior changes.
 - Command construction, command recommendation, executable resolution, command-contract linting, or copy-to-clipboard command behavior changes.
 - Filesystem containment, symlink handling, package publishing, build pipeline, or release automation behavior changes.
+- Policy engines, architecture linters, rule-catalog loaders, schema validators, generated compliance reports, or governance gates change how security-sensitive data, API, AI, payment, tier, deployment, ownership, or repository boundaries are approved.
 - A bug fix closes an abuse case and the fix needs a regression test to prevent reintroduction.
 - A review identifies a concrete security-sensitive boundary that can be expressed as a deterministic test.
 - A static analysis alert identifies a concrete data flow, permission boundary, command boundary, artifact boundary, or input-handling bug that can be locked with a local test.
@@ -96,13 +98,18 @@ Convert security-sensitive behavior changes into safe negative tests that preser
    - unsafe external URL, callback, redirect, or server-side request target
    - SSRF-style private network, localhost, link-local metadata, redirect, or DNS re-resolution target
    - missing webhook signature validation or unsafe retry behavior for external callbacks
+   - insecure verifier, authenticator, authorizer, normalizer, or dedupe default where missing configuration silently becomes allow-all, unsigned, no-op, or test-only behavior on a public endpoint
    - CSRF-style state change that relies on browser credentials without an origin, token, or same-site boundary
    - missing rate limit or lockout on login, signup, token reset, invitation, webhook, or expensive generation endpoints
    - client-supplied price, discount, role, owner, entitlement, plan, inventory, seat, refund, coupon, or usage value trusted by the server
    - ORM mass assignment, unscoped `findMany`, `updateMany`, `deleteMany`, unsafe migration default, or missing database policy enforcement
    - unsafe shell command construction, command name interpolation, clipboard command output, or executable lookup
-   - filesystem escape through symlinks, path traversal, archive entries, generated state, or package contents
+   - repository inspection command that unexpectedly executes local Git helpers, hooks, credential helpers, package lifecycle hooks, PATH shims, or other repository-controlled executables
+   - filesystem escape through symlinks, path traversal, archive entries, Git tree entries, generated state, or package contents
    - mismatch between two validators, linters, dashboards, schemas, or release gates that claim the same policy
+   - policy-source mismatch where a validator loads a security rule from the wrong catalog, silently disables a missing rule, or accepts a legacy fallback without an explicit compatibility test
+   - untrusted metadata override where a repository-controlled field, nested duplicate, component, owner, stage, tier, role, or exemption value is treated as trusted ownership or authorization evidence
+   - invalid-but-present security control values where `false`, `0`, `{}`, `[]`, empty strings, or type-mismatched placeholders satisfy required policy fields
    - release or package-publishing pipeline code execution before artifact publication
    - incomplete escaping, quoting, encoding, or sanitization where the safe behavior can be asserted without invoking a real shell or network target
    - stack trace or internal error exposure through a user-visible API, report, dashboard, or command output
@@ -116,6 +123,7 @@ Convert security-sensitive behavior changes into safe negative tests that preser
    - missing capability or scoped permission object where a sensitive operation depends on broad user, role, or global authorization state
    - missing invariant policy where a sensitive state change could violate a non-negotiable rule such as last-owner, entitlement, paid-order, refund, or retention constraints
    - missing idempotency key, action ledger, or outbox/inbox record where repeated execution of a side effect could charge, refund, notify, grant, revoke, publish, or delete more than once
+   - unbounded public request identifiers, idempotency keys, webhook event ids, replay ids, provider names, request ids, or header values retained in process memory without length, entry-count, TTL, eviction, or cleanup on rejected requests
    - exposed debug, admin, metrics, storage, GraphQL, development console, root container user, default credential, or fork pull-request secret path that can be checked locally
 3. Search for existing tests that already cover the same boundary. Strengthen the existing test when that gives clearer coverage than adding a new one.
 4. Build the smallest safe negative test data: at least one allowed control case when useful, and one denied case that proves the boundary rejects the abuse condition.
@@ -124,24 +132,27 @@ Convert security-sensitive behavior changes into safe negative tests that preser
 7. For CSRF and browser-credential state changes, assert that the mutating operation rejects missing or mismatched token, origin, or same-site evidence according to the project framework.
 8. For rate limits and lockouts, use injected time, local stores, or fake counters to prove repeated attempts are bounded without slowing the suite.
 9. For session, JWT, OAuth, reset, invite, logout, or reauthentication boundaries, assert the denied condition directly: invalid signature, expired token, wrong issuer, wrong audience, missing state, revoked token, reused token, or missing recent authentication.
-10. For upload and download boundaries, use local fixture files and fake storage. Assert authorization, content signature, MIME, size, filename, path, metadata stripping, and conversion resource-limit behavior without using live user files.
-11. For business-rule boundaries, use server-side fixtures that try manipulated price, discount, role, owner, entitlement, plan, inventory, seat, refund, coupon, or usage fields. Assert that state remains unchanged or is recalculated from trusted server data.
-12. For database and ORM boundaries, assert scoped queries or policies through observable behavior: cross-tenant rows stay invisible, bulk update or delete affects only owned rows, mass-assigned privileged fields are ignored, and unsafe migration defaults cannot create elevated access.
-13. For cryptography and token-generation boundaries, assert behavior through the project-owned API rather than hard-coding private implementation details: password verifiers reject plaintext or fast-hash storage, token generation uses injected secure randomness or a deterministic test double, and custom cryptography shortcuts are absent where the project exposes that decision.
-14. For transport-security boundaries, assert configuration rejects disabled certificate validation or insecure HTTP for sensitive endpoints when the project owns that configuration.
-15. For architecture-drift boundaries, write the test around the security invariant, not the refactor shape: unauthorized access stays denied, sensitive output stays omitted, and side effects remain scoped after the generated structure changes.
-16. For parser, validator, serializer, path, command, or workflow boundaries, consider a bounded property-based or fuzz-style regression when the invariant is clearer than a list of hand-written examples. Keep generators local, deterministic under the test runner, size-limited, and focused on the defensive invariant.
-17. When adding a fuzzing or property-based testing dependency, keep dependency metadata, lockfiles, test selection rules, and package tests synchronized. Prefer an existing project dependency when it can express the invariant cleanly.
-18. Use mocks or local fakes for external requests, uploads, redirects, webhooks, payment providers, file systems, shell commands, package registries, and CI workflows. Do not contact live suspicious endpoints or publish real artifacts.
-19. Name the test after the defensive expectation, such as `cannot_read_other_users_invoice` or `rejects_private_network_callback_url`.
-20. Keep assertions tied to observable behavior: status code, returned error shape, unchanged database state, missing side effect, sanitized output, rejected job, or invariant preserved for all generated cases.
-21. Avoid dumping long exploit strings into the test. Use minimal representative inputs or generated values that prove the validation or boundary rule without becoming an offensive payload corpus.
-22. For command and filesystem boundaries, assert the denied side effect directly: no injected command appears in a runnable recommendation, no repository-local shim is executed, no background shell pattern is counted runnable, no symlink target outside the root is read or written.
-23. For plan/apply, capability, invariant, time, and idempotency boundaries, assert the safety contract directly: planning produces no side effect, commit rejects stale or unauthorized capability, invalid transitions preserve state, injected time controls expiry, and repeated side-effect keys do not repeat the effect.
-24. For workflow scanner fixes, prefer repository-local assertions for durable contracts: action references are pinned to commit SHAs or digest-pinned containers, privileged permissions are job-scoped, fork pull requests do not receive secrets, deployment or scanner jobs can be manually rerun when useful, and dependency scans exclude fixture-only manifests unless intentionally included.
-25. For deployment and configuration fixes, prefer local config assertions: debug flags are off for production, sample credentials are absent, public admin or metrics endpoints are not enabled by default, storage is not public, containers do not run as root when the project controls that setting, and HTTPS requirements are preserved.
-26. For scanner-driven fixes, include a regression only when the rule reflects a durable project contract. Do not add brittle tests that merely assert the scanner's current wording, line number, or severity.
-27. If the project lacks enough context to write a deterministic test, output a concrete test proposal instead of inventing fixtures or behavior.
+10. For public webhook, callback, and action-intake defaults, assert missing verifier, authenticator, or authorizer configuration fails registration or setup. If an intentionally unsafe local/test mode exists, require the test to pass that mode explicitly and name it in the fixture.
+11. For public idempotency, deduplication, replay, rate-limit, and request-tracking stores, assert malformed rejected requests do not permanently claim keys, oversized keys are rejected or normalized before retention, and default memory stores have observable bounds such as entry eviction, TTL, or a configured capacity.
+12. For upload and download boundaries, use local fixture files and fake storage. Assert authorization, content signature, MIME, size, filename, path, metadata stripping, and conversion resource-limit behavior without using live user files.
+13. For business-rule boundaries, use server-side fixtures that try manipulated price, discount, role, owner, entitlement, plan, inventory, seat, refund, coupon, or usage fields. Assert that state remains unchanged or is recalculated from trusted server data.
+14. For database and ORM boundaries, assert scoped queries or policies through observable behavior: cross-tenant rows stay invisible, bulk update or delete affects only owned rows, mass-assigned privileged fields are ignored, and unsafe migration defaults cannot create elevated access.
+15. For cryptography and token-generation boundaries, assert behavior through the project-owned API rather than hard-coding private implementation details: password verifiers reject plaintext or fast-hash storage, token generation uses injected secure randomness or a deterministic test double, and custom cryptography shortcuts are absent where the project exposes that decision.
+16. For transport-security boundaries, assert configuration rejects disabled certificate validation or insecure HTTP for sensitive endpoints when the project owns that configuration.
+17. For architecture-drift boundaries, write the test around the security invariant, not the refactor shape: unauthorized access stays denied, sensitive output stays omitted, and side effects remain scoped after the generated structure changes.
+18. For policy-engine or governance-linter boundaries, add denied cases that prove the invariant cannot be bypassed by newly named entities, spoofed duplicate fields, self-declared ownership metadata, missing or misplaced rule files, or invalid-but-present values. Include an allowed control case when it clarifies the intended trusted source.
+19. For parser, validator, serializer, path, command, or workflow boundaries, consider a bounded property-based or fuzz-style regression when the invariant is clearer than a list of hand-written examples. Keep generators local, deterministic under the test runner, size-limited, and focused on the defensive invariant.
+20. When adding a fuzzing or property-based testing dependency, keep dependency metadata, lockfiles, test selection rules, and package tests synchronized. Prefer an existing project dependency when it can express the invariant cleanly.
+21. Use mocks or local fakes for external requests, uploads, redirects, webhooks, payment providers, file systems, shell commands, package registries, Git helpers, and CI workflows. Do not contact live suspicious endpoints or publish real artifacts.
+22. Name the test after the defensive expectation, such as `cannot_read_other_users_invoice` or `rejects_private_network_callback_url`.
+23. Keep assertions tied to observable behavior: status code, returned error shape, unchanged database state, missing side effect, sanitized output, rejected job, or invariant preserved for all generated cases.
+24. Avoid dumping long exploit strings into the test. Use minimal representative inputs or generated values that prove the validation or boundary rule without becoming an offensive payload corpus.
+25. For command and filesystem boundaries, assert the denied side effect directly: no injected command appears in a runnable recommendation, no repository-local shim or Git helper is executed, no background shell pattern is counted runnable, no symlink target outside the root is read or written, and no Git tree or archive path writes outside the intended destination.
+26. For plan/apply, capability, invariant, time, and idempotency boundaries, assert the safety contract directly: planning produces no side effect, commit rejects stale or unauthorized capability, invalid transitions preserve state, injected time controls expiry, and repeated side-effect keys do not repeat the effect.
+27. For workflow scanner fixes, prefer repository-local assertions for durable contracts: action references are pinned to commit SHAs or digest-pinned containers, privileged permissions are job-scoped, fork pull requests do not receive secrets, deployment or scanner jobs can be manually rerun when useful, and dependency scans exclude fixture-only manifests unless intentionally included.
+28. For deployment and configuration fixes, prefer local config assertions: debug flags are off for production, sample credentials are absent, public admin or metrics endpoints are not enabled by default, storage is not public, containers do not run as root when the project controls that setting, and HTTPS requirements are preserved.
+29. For scanner-driven fixes, include a regression only when the rule reflects a durable project contract. Do not add brittle tests that merely assert the scanner's current wording, line number, or severity.
+30. If the project lacks enough context to write a deterministic test, output a concrete test proposal instead of inventing fixtures or behavior.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

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

@@ -0,0 +1,186 @@
+---
+mustflow_doc: skill.svelte-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: svelte-code-change
+description: Apply this skill when Svelte or SvelteKit components, routes, load functions, server actions, endpoints, stores, context, runes, SSR boundaries, server-only imports, accessibility warnings, or tests are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.svelte-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Svelte Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Svelte component reactivity, SvelteKit SSR/server/client boundaries, data secrecy, load/action/endpoint contracts, request-scoped state ownership, accessibility, and generated route behavior. Choose files by data boundary first, not by filename habit.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.svelte`, `+page`, `+layout`, `+page.server`, `+layout.server`, `+server`, load functions, form actions, endpoints, stores, context, runes, `$app` imports, `$lib/server`, hooks, route params, or Svelte tests change.
+- The task touches state management, SSR errors, browser APIs, forms, routing, progressive enhancement, request-local data, server-only imports, private/public environment variables, or Svelte 5 runes.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is plain CSS or HTML with no Svelte or SvelteKit behavior; use the relevant UI foundation skill.
+- The service code is framework-free and no Svelte boundary changes.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Package metadata, Svelte config, Vite config, TypeScript config, route segment files, hooks, app types, stores/runes/context, form schema, and tests.
+- Svelte version, route data source, secrecy, request scope, mutation type, serialization requirement, SSR/client boundary, browser dependency, and state owner.
+- Imports from `$lib/server`, `*.server.*`, `$env/static/private`, `$env/dynamic/private`, DB/filesystem/server SDK modules, cookies, auth headers, and `event.locals`.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- For route work, read the sibling `+layout`, `+page`, `+page.server`, and `+server` files as one boundary.
+- Classify every data access by origin, secrecy, request scope, mutation, browser dependency, and serialization before choosing a SvelteKit file.
+- Treat all route files as potentially server-executed until proven otherwise.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep secrets, private environment, database clients, and cookie-authenticated data in server-only files.
+- Use browser APIs only behind client-safe lifecycle or environment guards.
+- Keep state local unless shared ownership is justified.
+- Preserve form actions and progressive enhancement instead of replacing all forms with client-only fetch.
+- Use context for request-scoped component-tree sharing instead of module singletons.
+- Use `$derived` for computed display values and `$effect` only for browser-side effects and cleanup.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read route segment files, parent layouts, stores/runes/context, hooks, app types, and tests.
+2. Identify Svelte version and whether the code uses runes or legacy reactivity.
+3. Before choosing a file, classify every data access with: origin, secrecy, request scope, mutation, browser dependency, and serialization.
+4. If data requires DB, filesystem, private env, cookies, auth headers, `event.locals`, server SDKs, or request-local identity, keep it in server-only code: `+page.server`, `+layout.server`, `+server`, `hooks.server`, or `$lib/server`.
+5. If data is public and can be safely fetched by the browser without secrets, universal load is allowed.
+6. If the operation is a page form mutation, prefer `+page.server` actions over a custom JSON endpoint.
+7. If the operation is a public HTTP API, webhook, mobile API, stream, file response, or non-page endpoint, use `+server`.
+8. If the value is UI-only state such as modal open, selected tab, draft input, accordion state, hover state, or local editing state, keep it in component `$state` or local context.
+9. If a value is computed from reactive inputs, use `$derived`. Do not use `$effect` to copy or synchronize derived state.
+10. Use `$effect`, lifecycle hooks, event handlers, actions, or dynamic imports for browser-only APIs and browser-only libraries. Do not touch `window`, `document`, `localStorage`, `matchMedia`, canvas, or browser-only imports in SSR top-level code.
+11. Keep request-specific user/session/auth state out of module-level mutable variables, global stores, exported `$state`, and load/action side effects.
+12. Do not write to stores from load functions.
+13. Keep server load return values intentionally serializable and minimal. Do not pass secrets, raw sessions, tokens, hidden DB fields, or whole service responses to the browser.
+14. Prefer `$app/state` over legacy `$app/stores` in SvelteKit projects that use the newer SvelteKit state API.
+15. Do not hide SSR errors by disabling SSR unless the user explicitly accepts that product and architecture change.
+16. Treat accessibility compiler warnings as real findings unless a local false-positive reason is documented.
+
+<!-- mustflow-section: data-boundary-policy -->
+## Data Boundary Policy
+
+- Public route params and public query values may live in universal load until they drive private DB/API access.
+- Public external APIs and public CMS data may live in universal load only when the browser may call them directly without secrets.
+- DB, filesystem, private env, server SDKs, cookies, auth headers, sessions, and `event.locals` belong in server-only files.
+- User-specific data must be read server-side and narrowed before being serialized into `data`.
+- Page forms should use form actions by default.
+- External clients, webhooks, mobile apps, streaming responses, and custom HTTP responses belong in `+server`.
+- Browser-only values belong in component effects, event handlers, dynamic imports, or browser actions.
+
+<!-- mustflow-section: route-boundary-policy -->
+## Route Boundary Policy
+
+- `+page.ts` and `+layout.ts` are universal. They may run on the server and in the browser.
+- `+page.server.ts` and `+layout.server.ts` are for server-only page data.
+- `+page.server.ts` actions are for page-owned form mutations.
+- `+server.ts` is for HTTP endpoints, webhooks, non-page APIs, streams, files, and custom responses.
+- Do not create a JSON endpoint for a normal page form unless there is a non-page consumer.
+- Do not wrap server-only imports in browser guards. Fix the import graph.
+
+<!-- mustflow-section: runes-state-policy -->
+## Runes And State Policy
+
+- Use `$state` for local interactive UI state.
+- Use `$derived` for calculations from props, route data, page state, or local state.
+- Use `$effect` only for browser-side effects, subscriptions, DOM, canvas, analytics, third-party browser libraries, and cleanup.
+- Use stores for external streams or manual subscribe/unsubscribe interop, not ordinary component state.
+- Use context for parent-owned values shared down the component tree, especially request-scoped layout data.
+- Do not reassign reactive context objects after placing them in context; update their properties or pass getter functions when needed.
+
+<!-- mustflow-section: ssr-debug-policy -->
+## SSR Debug Policy
+
+When SSR breaks, inspect in this order:
+
+1. Private env imports.
+2. `$lib/server`, `*.server.*`, DB, filesystem, admin SDK, or server-only import chains.
+3. Request-local state stored in module singletons, stores, or exported `$state`.
+4. Browser API access at module top-level or during SSR render.
+5. Hydration mismatch from time, randomness, locale, timezone, localStorage, or browser-only initial state.
+6. Route-level SSR disabling only after the product accepts an SPA-like shell.
+
+<!-- mustflow-section: hard-bans -->
+## Hard Bans
+
+- Do not add route-level SSR disabling to fix `window is not defined`.
+- Do not move required first-render page data into lifecycle hooks or `$effect`.
+- Do not import `$lib/server`, `*.server.*`, private env modules, DB clients, filesystem, or admin SDKs from universal/client route files or shared client utilities.
+- Do not mutate module-scope variables, global stores, or exported `$state` with user/session/request data during SSR, load, or actions.
+- Do not use `$effect` to compute derived values.
+- Do not put browser-only library imports at top level when the package touches browser globals during import.
+- Do not serialize secrets, raw sessions, access tokens, hidden DB fields, or whole service responses through load data.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Server/client and SSR boundaries are explicit.
+- State owner and derived/effect behavior are clear.
+- Forms remain progressive unless intentionally changed.
+- Private data stays server-only and serialized data is intentionally minimal.
+- Request-scoped sharing uses load data, props, or context instead of module singletons.
+- Accessibility warnings are resolved or justified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing Svelte check, SSR render, form action, or browser verification intents when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a browser API breaks SSR, move it to a client-safe boundary instead of disabling SSR by default.
+- If data source ownership is unclear, inspect route server files and hooks before editing.
+- If accessibility warnings require an ignore, include the specific reason in the code or report.
+- If server-only imports leak into universal/client files, move the boundary instead of adding runtime guards.
+- If request-local data is stored globally, move it to server load, actions, context, or persistent storage with user scoping.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- SSR/server/client and state notes
+- Form/action/accessibility impact
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Svelte risk

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

@@ -0,0 +1,164 @@
+---
+mustflow_doc: skill.tailwind-code-change
+locale: en
+canonical: true
+revision: 2
+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.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.tailwind-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Tailwind Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Tailwind static class detection, design tokens, bounded variants, responsive/state behavior, accessibility states, and production build output. Treat Tailwind utilities as build-time tokens, not runtime strings.
+
+<!-- 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.
+- 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 -->
+## Do Not Use When
+
+- Styling is plain CSS without Tailwind utilities; use `css-code-change`.
+- Utility generation is UnoCSS, not Tailwind; use `unocss-code-change`.
+
+<!-- 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.
+- 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.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Confirm how Tailwind detects source classes before changing class composition.
+- Identify whether the project is using Tailwind v3 config safelists or Tailwind v4 CSS source directives.
+- 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.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- 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 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.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+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.
+
+<!-- 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.
+- 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.
+
+<!-- mustflow-section: token-policy -->
+## Token Policy
+
+- Use existing tokens and approved utilities first.
+- Add a design token when a value repeats, has product meaning, appears in more than one component, supports theming, or has a designer-owned name.
+- Do not add value-named tokens such as pixel-width or random-color names. Name tokens by role, surface, status, container, spacing purpose, or component meaning.
+- Keep component markup free of raw hex, RGB, OKLCH, arbitrary color, and arbitrary shadow values unless the file is itself a token/theme definition.
+
+<!-- mustflow-section: review-rejection-criteria -->
+## Review Rejection Criteria
+
+Reject the change when:
+
+- A Tailwind utility is assembled from runtime fragments.
+- A raw color appears outside a token or theme file.
+- An arbitrary value appears without a narrow reason.
+- 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.
+- A public component exposes unconstrained Tailwind class fragments.
+- A safelist covers broad palettes, broad numeric ranges, or unknown runtime values.
+- Conflicting utilities are present on the same element.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- All generated utilities are visible to Tailwind's detector, a static map, a variant helper, or an intentional finite safelist.
+- Arbitrary values are rare, justified, and not repeated without token promotion.
+- Runtime visual values are constrained by semantic variants or bridged through CSS variables.
+- Interactive states include keyboard and disabled behavior where relevant.
+- Production-build class loss risk is checked or reported.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing production CSS or visual verification intents when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If production styling disappears, inspect dynamic class generation and source scanning first.
+- If arbitrary values accumulate, stop and consider whether the design token system is missing a token.
+- If helper utilities erase class visibility, rewrite to static maps or report the build risk.
+- If a component API requires arbitrary Tailwind fragments, narrow it to semantic variants or report the public API risk.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Class detection and token notes
+- Responsive and accessibility state notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Tailwind risk