mustflow 2.107.9 → 2.108.2

package/templates/default/locales/en/.mustflow/skills/deployment-rollout-safety-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.deployment-rollout-safety-review
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: deployment-rollout-safety-review
-description: Apply this skill when server, backend, worker, scheduler, queue consumer, cron, container, VM, serverless, migration, config, feature-flag, cache, deployment pipeline, canary, rollback, release envelope, image digest, deployment history, traffic rollback, health check, readiness/liveness/startup probe, graceful shutdown, artifact promotion, release observability, or post-deploy smoke behavior is created, changed, reviewed, or reported and the risk is whether a deployment can be rolled out, stopped, observed, or rolled back safely.
+description: Apply this skill when CI/CD pipeline gates, required checks, preview deploys, migration checks, server, backend, worker, scheduler, queue consumer, cron, container, VM, serverless, IaC, config, secret handling, feature-flag, cache, canary, rollback, release envelope, image digest, deployment history, traffic rollback, health check, readiness/liveness/startup probe, graceful shutdown, artifact promotion, release observability, or post-deploy smoke behavior is created, changed, reviewed, or reported and the risk is whether a deployment can be rolled out, stopped, observed, or rolled back safely.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -29,13 +29,15 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Review a server deployment as a runtime state transition, not as "the build passed".
+Review a server deployment as a runtime state transition, not as "the build passed" or
+"CI is green".
 
 Deployment failures usually come from changed ordering, config, data, cache, queues, rollback shape,
-permissions, and observability. Rollback is not just restarting an older container. It is the older
-release surviving today's data, config, cache, queue messages, external side effects, and traffic
-state. This skill makes the agent prove that a wrong deploy has small blast radius, is detected
-quickly, can be stopped quickly, and can be rolled back without inventing a recovery plan during the
+permissions, secrets, infrastructure policy, human approvals, and observability. Rollback is not
+just restarting an older container. It is the older release surviving today's data, config, cache,
+queue messages, external side effects, secret versions, and traffic state. This skill makes the
+agent prove that a wrong deploy has small blast radius, is detected quickly, can be stopped quickly,
+and can be rolled back or safely rolled forward without inventing a recovery plan during the
 incident.
 
 <!-- mustflow-section: use-when -->
@@ -43,10 +45,12 @@ incident.
 
 - A change touches server deployment, backend runtime behavior, workers, schedulers, cron, queue
   consumers, containers, VMs, serverless functions, Kubernetes manifests, process managers,
-  deployment pipelines, release gates, canaries, release envelopes, or rollback procedures.
+  CI/CD workflows, preview environments, deployment pipelines, release gates, canaries, release
+  envelopes, or rollback procedures.
 - A change touches DB migration order, config or env vars, feature flags, cache keys, queue or topic
   message formats, external API dependencies, storage paths, startup probes, readiness probes,
-  liveness probes, graceful shutdown, worker drain, deployment locks, or post-deploy smoke checks.
+  liveness probes, graceful shutdown, worker drain, deployment locks, secret scope, IaC policy, or
+  post-deploy smoke checks.
 - A review needs to decide whether code, config, database, cache, queue, and scheduler changes can
   coexist across old and new versions while traffic is still moving.
 
@@ -77,11 +81,26 @@ incident.
 - Deployment model: environment order, artifact promotion path, rolling/blue-green/canary strategy,
   traffic rollback path, old-version retention, deployment history retention, deployment
   concurrency, and deployment lock owner.
+- Pipeline gate model: required status checks, branch protection or merge gate, reviewer or
+  CODEOWNER gate, fast-fail ordering, clean CI environment, test data setup, flaky-test quarantine
+  owner, artifact retention, and security scan coverage.
+- Preview model: preview URL, isolated namespace or schema, ephemeral database or seeded data,
+  teardown policy, cost guardrail, deployment protection, and proof that production secrets and
+  production PII are not exposed.
+- Migration check model: dry-run or shadow database evidence, destructive-change detection,
+  lock or table-rewrite risk, online DDL assumptions, backfill separation, N-1 app compatibility,
+  and rollback or roll-forward boundary.
+- Secret and approval model: environment-scoped secrets, production approval gate, OIDC or
+  short-lived credential path, log masking, rotation or revocation path, external secret store or
+  encryption-at-rest boundary, and least-privilege deploy job permissions.
 - Compatibility model: old code with old data, old code with new data, new code with old data, new
   code with new data, N-1 message compatibility, cache key version, and rollback survivability.
 - Runtime control model: startup/liveness/readiness probes, graceful shutdown behavior, load
   balancer connection draining, worker drain, cron duplicate guard, kill switch, safe flag defaults,
   automatic stop conditions, synthetic transactions, and post-deploy observation window.
+- Infrastructure and observability model: rendered manifests or plan output, policy checks, image
+  digest pinning, resource requests and limits, probe presence, privileged or hostPath use,
+  plaintext-secret checks, release-labeled logs, metrics, traces, alerts, and dashboard slices.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -99,6 +118,9 @@ incident.
 - Add or update deploy runbooks, release checklists, pipeline metadata, smoke tests, probe tests,
   config validation, feature-flag defaults, rollback notes, canary gates, and deployment safety
   tests when they match the repository style.
+- Add or update preview-deploy guardrails, migration preflight notes, manifest or IaC validation
+  fixtures, secret-scope checks, required-check documentation, and release evidence templates when
+  they are already within the task scope.
 - Add local code guards for startup config validation, readiness separation, shutdown handling,
   worker drain, cache-key versioning, and deployment attribution when the task scope includes the
   affected runtime code.
@@ -115,131 +137,171 @@ incident.
    external APIs, permissions, config, and feature flags. If the ledger is unknown, report that the
    deployment blast radius is unknown instead of guessing.
 
-2. Build the release envelope.
+2. Check the merge and CI gate before the deploy gate.
+   Required status checks, protected branches, review or CODEOWNER gates, and stale-review handling
+   should stop unreviewed or partially verified production changes. Order checks so cheap failures
+   happen before slow checks: format, lint, typecheck, unit tests, build, security scans,
+   integration or contract tests, then focused end-to-end smoke. Require a clean reproducible CI
+   environment, explicit test database setup, seeded data, dependency and container scan coverage,
+   IaC or configuration scans when those files changed, secret scanning, and a named owner or SLA for
+   flaky-test quarantine. A flaky test silently bypassed by the merge gate is a deployment-safety
+   risk, not a testing nuisance.
+
+3. Build the release envelope.
    Rollback needs more than an image tag. Bind image digest, chart or manifest revision, values
    file hash, ConfigMap name or version, Secret version, migration range, feature flag snapshot,
    ingress or router weight, deployer, and deployment time under one `release_id` when the platform
    exposes those facts. If only a mutable tag such as `latest` identifies production, report that
    rollback identity is not reproducible.
 
-3. Separate artifact promotion from environment rebuilds.
+4. Make preview deployment a rehearsal, not just a link.
+   Preview deploys should use an isolated namespace, schema, or ephemeral database with explicit
+   seed data and teardown. Do not allow production secrets, production OAuth callbacks, production
+   webhooks, or production PII in preview. Name deployment protection, access control, teardown
+   failure alerts, and cost cleanup. Run or identify the preview checks that matter for the changed
+   flow: smoke, selected E2E, API compatibility, accessibility, visual regression, and thin DAST or
+   security probes where the repository owns them.
+
+5. Separate artifact promotion from environment rebuilds.
    Verify whether staging and production receive the same artifact identity. Prefer promoting one
-   built artifact over rebuilding per environment. If per-environment rebuild is unavoidable, name
-   the drift risk and require commit SHA, dependency lock, image digest, and build input evidence.
-   Treat image tags as human labels and image digests as the rollback proof.
+   built immutable artifact over rebuilding per environment. If per-environment rebuild is
+   unavoidable, name the drift risk and require commit SHA, dependency lock, build run, SBOM or
+   package inventory when available, image digest, and build input evidence. Treat image tags as
+   human labels and image digests as the rollback proof.
 
-4. Preserve rollback history and warm capacity.
+6. Preserve rollback history and warm capacity.
    For platform-managed rollbacks, check whether old revisions, ReplicaSets, Helm release history,
    blue/green environments, or rollout controller history are retained long enough to be useful.
    Do not treat a rollback path as safe if the old version is immediately scaled to zero, cold, or
    deleted. Prefer traffic rollback to an already-warm old version before rebuilding or pulling a
    replacement during an incident.
 
-5. Split deploy order from migration order.
+7. Split deploy order from migration order.
    For DB changes, check expand/migrate/read-write/switch/contract sequencing. New code must tolerate
    old data, old code must tolerate expanded schema or new data, and contraction must wait until old
    code is impossible. Check migration lock timeout, batch size, retryability, partial progress
    markers, rollback preview evidence, point-in-time recovery practice, database config backup, and
-   rollback limits. Treat destructive rollback SQL as a data-loss risk, not a recovery guarantee.
+   rollback limits. Require dry-run or shadow database evidence when the repository has a migration
+   surface. Treat destructive rollback SQL as a data-loss risk, not a recovery guarantee.
 
-6. Treat config changes as code changes.
+8. Treat config and IaC changes as code changes.
    Diff config and environment variables. Require startup validation for missing, misspelled, empty,
    malformed, or incompatible values. A service should fail fast before accepting traffic when a
    required setting is unsafe. Prefer versioned or immutable config names over in-place config
    mutation, and name whether env-var, mounted-file, or subpath-style config updates require pod or
-   process restart.
-
-7. Separate startup, liveness, and readiness.
+   process restart. For infrastructure files, review rendered manifests or plans rather than only
+   source snippets. Check resource requests and limits, probes, privileged mode, hostPath mounts,
+   plaintext secrets, IAM or service account scope, image digest pinning, and policy validation
+   coverage.
+
+9. Keep secrets out of the wrong stage.
+   Test, preview, staging, and production jobs should use environment-scoped secrets with the
+   smallest permission set that can complete that job. Prefer OIDC or short-lived credentials over
+   long-lived cloud keys in CI. Production secrets should require the production environment gate,
+   and preview jobs should not be able to read them. Check secret masking, rotation or revocation
+   notes, external secret store or encryption-at-rest boundary, and whether platform-native secrets
+   also need RBAC, namespace, and audit controls.
+
+10. Separate startup, liveness, and readiness.
    Startup should protect slow boots, liveness should detect stuck processes, and readiness should
    gate whether the instance can serve real dependencies. Do not count "process is running" as
    deployment readiness. Keep liveness conservative enough that overload or long GC pauses do not
    turn a recoverable incident into a restart loop.
 
-8. Check graceful shutdown before rolling traffic.
+11. Check graceful shutdown before rolling traffic.
    Verify SIGTERM or platform shutdown handling for in-flight requests, DB transactions, uploads,
    payment or webhook callbacks, and streaming responses. The app shutdown timeout must be shorter
    than load balancer connection draining.
 
-9. Drain workers deliberately.
+12. Drain workers deliberately.
    Queue workers need a stop-accepting-new-work phase, a current-work completion or checkpoint phase,
    and an idempotent retry path for interrupted work. Ack, delete, offset commit, and visibility
    timeout behavior must match the shutdown path. Rollback should name consumer pause, in-flight
    work completion, idempotency-key checks, and dead-letter or quarantine inspection for worker and
    scheduler surfaces.
 
-10. Prove message compatibility.
+13. Prove message compatibility.
    Producers and consumers are rarely deployed at the exact same instant. Message format changes need
    N-1 message compatibility, tolerant readers, versioned fields, defaults for missing data, and a
    plan for queued old messages. Unknown event types should not crash old consumers; require
    quarantine, dead-letter, or ignore policy that preserves investigation evidence.
 
-11. Design external side effects as compensation.
+14. Design external side effects as compensation.
     Emails, payment authorizations, third-party webhooks, provider state, and object-storage writes
     do not disappear when code rolls back. Require outbox, idempotency key, state machine,
     reconciliation, or compensation notes for side effects that cannot be undone by reverting code.
 
-12. Keep API compatibility wider than the deploy window.
+15. Keep API compatibility wider than the deploy window.
     Server versions and clients do not change at the same instant. Check N-1 and N+1 compatibility
     for request fields, response fields, enum values, error codes, API versions, and mobile or SDK
     clients. Removing fields, narrowing enums, or adding required inputs can make rollback fail even
     when the old container starts.
 
-13. Add a kill switch, not just a flag.
+16. Add a kill switch, not just a flag.
    Feature flags that only select a new path are not enough. Require a fast disable path, a safe
-   default when flag lookup fails, and an owner who can flip it during the observation window.
-
-14. Define the canary cohort.
+   default when flag lookup fails, an owner who can flip it during the observation window, rollout
+   percentages or cohorts, and an expiry or removal plan so release flags do not become permanent
+   hidden branches.
+
+17. Run production preflight before touching traffic.
+    Preflight should name the active incident status, deployment window, error budget or SLO burn,
+    DB replication lag, queue depth, cache health, dependency health, cloud quota, feature flag
+    defaults, rollback target digest, migration compatibility, alert mute state, and on-call owner.
+    If the system is already degraded, default to blocking or narrowing the deploy rather than adding
+    another variable to an incident.
+
+18. Define the canary cohort.
     Percent-only canaries can hide the exact risky traffic. Name which users, tenants, regions,
     routes, worker partitions, queues, payment methods, or dependency paths receive the new version.
     Prefer a cohort that exercises the changed behavior without making the blast radius vague.
 
-15. Measure canaries by version and by user harm.
+19. Measure canaries by version and by user harm.
     A small canary can disappear in global averages. Require metrics split by service version,
     release id, route, cohort, or worker partition where safe. Prefer user-impact signals such as
     5xx, p95 or p99 latency, login failure, payment failure, order failure, queue backlog, or retry
     explosion over CPU-only rollback triggers.
 
-16. Make automatic stop conditions numeric.
+20. Make automatic stop conditions numeric.
     Before rollout, define stop or rollback thresholds for error rate, p95 or p99 latency, login or
     payment failure, queue backlog, retry rate, dependency timeout, and saturation. "Watch it" is not
     a stop condition.
 
-17. Verify read and write paths separately.
+21. Verify read and write paths separately.
     A read-only health check can pass while writes are broken. Add or identify smoke checks and
     synthetic transactions that cover the changed read path, changed write path, and visible business
     result without corrupting production data.
 
-18. Preserve release attribution in logs and telemetry.
+22. Preserve release attribution in logs and telemetry.
     Deployment logs and runtime logs should expose commit SHA, image tag or digest, config version,
     chart or manifest revision, config version, migration version, feature flag state, deployment
     environment, deployment id, service version, and instance. Log format changes must not silently
     break alerts, dashboards, or search queries.
 
-19. Version cache keys and narrow invalidation.
+23. Version cache keys and narrow invalidation.
     Cache changes need cache key versioning or compatibility. Avoid blanket flushes unless the cold
     DB load has been budgeted. Prefer narrow, gradual invalidation with fallback behavior named.
     Old code must not deserialize new cache payloads without a compatibility plan.
 
-20. Guard scheduler duplication.
+24. Guard scheduler duplication.
     Cron and scheduled jobs can overlap during rolling deploys. Check singleton locks, leader
     election, idempotency keys, deployment locks, and duplicate execution behavior for old and new
     versions.
 
-21. Treat CRDs and operators as schema rollouts.
+25. Treat CRDs and operators as schema rollouts.
     Custom resources, operators, storage versions, conversion strategies, and controller downgrade
     behavior can block rollback even when application pods are healthy. When those surfaces change,
     require stored-object migration, old-client compatibility, and operator downgrade notes.
 
-22. Use deployment locks per service and environment.
+26. Use deployment locks per service and environment.
     Two deploys, migrations, or production commands against the same service/environment need an
     explicit conflict rule. Name the lock scope and the operator-visible owner.
 
-23. Make production commands boring.
+27. Make production commands boring.
     Any production command touched by the change should have dry-run output, bounded target scope,
     explicit confirmation or ticket reference, and refusal behavior for ambiguous environment,
     tenant, region, or time range.
 
-24. Reserve post-deploy observation time.
+28. Reserve post-deploy observation time.
     Deployment is not done when traffic flips. Require a post-deploy observation window with owners
     available, synthetic transaction results, dashboards, logs, queue backlog, dependency health, and
     stop-condition status checked.
@@ -257,13 +319,22 @@ incident.
 ## Review Checklist
 
 - Deployment resource ledger is complete enough to name the blast radius.
+- Merge and CI gates include required checks, branch protection or equivalent merge policy,
+  fast-fail ordering, clean test data, flaky-test ownership, and security scan coverage.
 - Release envelope binds image digest, config, Secret, migration, flag, traffic, deployer, and time
   under a stable release identity where those platform concepts exist.
+- Preview deploys are isolated, seeded, protected, cleaned up, and kept away from production secrets
+  and production PII.
 - Same artifact is promoted across environments or rebuild drift is explicitly controlled.
 - Rollback history is retained, the old version can stay warm when needed, and traffic rollback is
   separated from rebuilding or repulling code.
-- DB migration, code deploy, data backfill, cache, queue, and rollback order are separated.
-- Required config is validated at startup and deployment config diff is inspectable.
+- DB migration, migration dry-run or shadow evidence, code deploy, data backfill, cache, queue, and
+  rollback order are separated.
+- Required config is validated at startup, deployment config diff is inspectable, and rendered
+  manifests or IaC plans are policy-checked for resources, probes, privileges, secrets, and digest
+  pinning.
+- Secrets are environment-scoped, production-gated, least-privilege, short-lived where possible,
+  masked in logs, and rotatable.
 - Startup, liveness, and readiness probes answer different questions.
 - Graceful shutdown, load balancer connection draining, worker drain, and interrupted work retry are
   compatible.
@@ -272,6 +343,8 @@ incident.
 - External side effects have idempotency, reconciliation, or compensation instead of rollback
   overclaim.
 - Feature flag lookup failure chooses the safe default and a kill switch can stop the change.
+- Production preflight checks active incidents, error budget, queue depth, DB lag, dependency
+  health, quota, rollback target, feature defaults, alert mute state, and owner availability.
 - Canary cohort, version-split telemetry, and automatic stop condition are concrete, numeric, and
   tied to the changed flow.
 - Read smoke, write smoke, synthetic transaction, deployment logs, and post-deploy metrics are
@@ -315,7 +388,8 @@ When reporting a review or change, include:
 - Skills used.
 - Deployment resources touched.
 - Rollout and rollback risks found or guarded.
-- Config, migration, cache, queue, probe, shutdown, canary, and observation decisions.
+- CI, preview, artifact promotion, config, secret, migration, IaC, cache, queue, probe, shutdown,
+  canary, rollback, and observation decisions.
 - Verification commands run and their result.
 - Remaining manual deployment checks, especially production-only smoke, canary, and observation
   steps that cannot be executed locally.

package/templates/default/locales/en/.mustflow/skills/frontend-component-library-review/SKILL.md

@@ -0,0 +1,299 @@
+---
+mustflow_doc: skill.frontend-component-library-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: frontend-component-library-review
+description: Apply this skill when a frontend component library, design system package, UI kit, shared component package, token system, primitive layer, variant API, theming surface, Storybook or docs site, package exports, public CSS or data attributes, accessibility behavior, controlled or uncontrolled component contract, visual regression suite, codemod, SemVer policy, or breaking-change plan is created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.frontend-component-library-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Frontend Component Library Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review frontend component libraries as public API platforms, not collections of pretty
+components copied from a design file.
+
+The core question is: "Can multiple product teams upgrade this package without guessing which
+tokens, props, slots, DOM shape, CSS variables, keyboard behavior, exports, docs examples, and
+release notes are contractual?" If the answer is unclear, the library is a shared copy-paste
+folder wearing a package name.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A design system, component library, UI kit, shared React, Vue, Svelte, Web Component, CSS, or
+  framework-agnostic component package is created, changed, reviewed, or reported.
+- Code or docs touch design tokens, CSS variables, theme modes, brand themes, density, contrast,
+  motion settings, primitive components, compound components, slots, variant props, polymorphic
+  `as` or `asChild`, public data attributes, `className` escape hatches, or package exports.
+- Button, Link, TextField, Dialog, Popover, Menu, Select, Combobox, Tabs, Tooltip, Toast, Table,
+  Data Grid, Icon, Badge, Card, Alert, or similar reusable components gain public behavior.
+- Storybook, docs, examples, props tables, visual regression stories, interaction tests,
+  accessibility tests, type tests, SSR or hydration checks, bundle-size checks, changelog entries,
+  migration guides, deprecation warnings, or codemods define consumer-facing behavior.
+- A review or final report claims a component library is reusable, accessible, themeable,
+  design-system-ready, stable, backward compatible, SemVer-safe, or ready for external teams.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is ordinary app UI with no reusable package, public component API, token contract, or
+  cross-team consumer surface. Use the framework, UI quality, layout, or accessibility skill.
+- The task only checks accessibility-tree semantics, keyboard behavior, labels, forms, dialogs, or
+  ARIA for a specific UI. Use `frontend-accessibility-tree-review` first.
+- The task only checks frontend state drift in an application. Use `frontend-state-ownership-review`
+  first.
+- The task only checks localization, RTL text behavior, translated layout stress, or locale SEO.
+  Use `frontend-localization-review` or `frontend-stress-layout-review` first.
+- The task only changes package metadata or exports without component-library contracts. Use the
+  matching package, public API, or CLI contract skill.
+- Verification would require unconfigured Storybook, browser, screenshot, visual-regression, or
+  package-manager commands. Report the missing evidence instead of inventing commands.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, target package or library, framework signals, consumer audience, current diff or
+  target files, package manager and build signals, and configured command intents.
+- Package API ledger: public entrypoints, `package.json` exports, documented imports, deep-import
+  policy, peer dependencies, side-effect CSS, generated styles, tree-shaking claims, SSR support,
+  and bundle boundaries.
+- Token ledger: primitive tokens, semantic tokens, component tokens, aliases, generated outputs,
+  CSS variables, TypeScript types, platform exports, descriptions, deprecations, owners, contrast
+  checks, and source-of-truth files.
+- Primitive behavior ledger: dialog, popover, menu, select, combobox, tabs, tooltip, toast, focus
+  scope, portal, scroll lock, typeahead, roving focus, escape behavior, outside interaction, and
+  restore-focus contracts.
+- Component contract ledger: props, slots, compound parts, refs, events, DOM ownership, data
+  attributes, CSS variable hooks, `className` or style overrides, polymorphic behavior, default
+  element, form participation, and documented examples.
+- State contract ledger: controlled and uncontrolled pairs such as `value`, `defaultValue`,
+  `onValueChange`, `open`, `defaultOpen`, `onOpenChange`, reset rules, disabled behavior, loading
+  behavior, and duplicate-submit policy.
+- Variant and theming ledger: semantic variant axes, impossible combinations, required accessible
+  names, brand, light and dark mode, density, contrast, reduced motion, forced colors, responsive
+  behavior, and theme-resolution order.
+- Docs and test ledger: Storybook stories, anatomy docs, do and do-not guidance, accessibility and
+  keyboard docs, controlled examples, theme-token docs, migration docs, type tests, behavior tests,
+  visual regression matrix, accessibility automation, manual evidence, SSR, hydration, and bundle
+  checks.
+- Release ledger: SemVer classification, public API definition, deprecation warnings, migration
+  guide, codemods, changelog, consumer upgrade path, and known breaking-change inventory.
+
+<!-- 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.
+- Existing local patterns for tokens, primitives, variant helpers, styling, package exports, docs,
+  tests, and release notes have been searched before inventing a new component-library pattern.
+- If the change touches app data, auth, payments, notifications, deployment, database, or security
+  behavior, also apply the narrower matching skill for that boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Create or refine component-library skill, docs, tests, route metadata, package metadata, template
+  copies, token docs, story contracts, migration notes, or release notes directly tied to the
+  changed component-library surface.
+- Tighten public API boundaries by documenting exports, removing undocumented example deep imports,
+  making internal paths private, or marking such changes as breaking when consumers may rely on
+  them.
+- Add focused tests for exports, types, roles and names, keyboard behavior, controlled and
+  uncontrolled state, variant constraints, token output, visual regression stories, SSR, hydration,
+  and bundle boundaries when existing project patterns support them.
+- Do not migrate the library to a new framework, styling engine, primitive library, package manager,
+  Storybook setup, or token compiler unless the current task explicitly requires that migration.
+- Do not treat `className`, raw `style`, hex-color props, arbitrary DOM selectors, or undocumented
+  internal files as harmless flexibility when they become consumer contracts.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Decide whether this is a component library or ordinary app UI.
+   - A library has downstream consumers, public imports, reusable components, upgrade risk, docs
+     examples, and package or workspace boundaries.
+   - If it is just one screen, route to the narrower app UI skill and report that this skill does
+     not apply.
+2. Build the public API ledger first.
+   - List public exports, documented imports, package entrypoints, peer dependencies, CSS side
+     effects, token exports, generated files, and documented slot or DOM hooks.
+   - Treat docs examples as public API. Consumers copy them.
+   - Flag undocumented deep imports such as `dist/internal/*`, helper hooks, generated class files,
+     or internal token maps. Blocking existing deep imports can be breaking.
+3. Separate top-level library layers.
+   - Prefer clear boundaries for tokens, primitives, components, icons, utilities, docs, testing,
+     and codemods.
+   - Reject a structure where every reusable concern lands in `components/*` and the Button prop
+     list becomes the escape hatch for the whole system.
+4. Review token architecture.
+   - Separate primitive tokens such as raw colors and spacing, semantic tokens such as
+     action-background and text-primary, and component tokens only when component-specific tuning
+     is truly needed.
+   - Product components should usually consume semantic tokens, not Figma variable names, raw hex
+     values, or one-off pixel literals.
+   - Token source, generated CSS variables, generated TypeScript types, docs tables, platform
+     outputs, deprecations, and contrast checks must agree.
+5. Review theming as value substitution, not logic spread.
+   - Prefer root attributes, classes, or scopes that swap CSS variable values.
+   - Keep brand, mode, density, contrast, and motion as independent axes unless the product has a
+     documented reason to bundle them.
+   - Flag per-component `theme.mode === ...` branches, theme-object reads on every component, and
+     theme names that encode every axis into one untestable mega-theme.
+6. Review primitives before styled components.
+   - Dialog, Popover, Menu, Select, Combobox, Tabs, Tooltip, Toast, and similar primitives own
+     accessibility behavior, focus, keyboard, portal, layering, scroll, and dismissal policy.
+   - Styled components should wrap or compose primitive behavior without weakening it.
+   - If the project hand-rolls a primitive, require the same behavior ledger a proven primitive
+     library would have supplied.
+7. Treat accessibility as public API.
+   - Native elements, accessible names, labels, keyboard behavior, focus management, form
+     participation, disabled behavior, live regions, and high contrast behavior are contractual.
+   - `role`, `aria-*`, and data attributes imply behavior promises. Attributes without keyboard
+     and focus behavior are not accessibility.
+   - Route detailed accessibility fixes to `frontend-accessibility-tree-review`.
+8. Review component state contracts.
+   - Controlled and uncontrolled modes need consistent pairs: `value` with `onValueChange`,
+     `defaultValue` for initial internal state, `open` with `onOpenChange`, and `defaultOpen`.
+   - Do not mix controlled and uncontrolled ownership silently.
+   - Components should not couple to app stores, routers, data-fetching libraries, or form
+     libraries except through explicit adapters.
+9. Review variant API shape.
+   - Keep axes semantic and small, such as tone, emphasis, size, loading, icon-only, and disabled.
+   - Prevent impossible combinations with types, runtime guards, docs, or component split.
+   - Require an accessible name for icon-only controls, block duplicate submit when loading, and
+     review polymorphic `as` or `asChild` combinations for semantic breakage.
+10. Review styling contracts.
+    - Stable slots, data attributes, CSS variables, and documented class hooks are safer than
+      consumers styling incidental DOM shape.
+    - Decide which DOM parts are public and which are internal.
+    - If internal DOM, class names, or data attributes appear in docs, tests, examples, or consumer
+      code, changing them may be breaking.
+11. Review component-specific traps.
+    - Button: native button behavior, `type`, loading duplicate-submit policy, icon-only names,
+      disabled versus `aria-disabled`, and focus-visible styling.
+    - TextField: durable label, description, error wiring, `aria-invalid`, required, readOnly,
+      disabled, prefix and suffix, clear button, password reveal, and form reset behavior.
+    - Dialog: name, initial focus, focus containment, restore focus, Escape, outside interaction,
+      background inertness, scroll lock, nested overlays, and portal container.
+    - Select and Combobox: do not conflate them. Review typeahead, search, highlighted option,
+      selected option, groups, disabled items, mobile fallback, IME, scroll, and form behavior.
+    - Table and Data Grid: separate semantic table from product-grade grid behavior such as
+      sorting, pagination, virtualization, editing, export, and fetching.
+    - Icon: `currentColor`, tree-shaking, viewBox consistency, decorative `aria-hidden`, and
+      meaningful label strategy.
+12. Review docs as executable specs.
+    - Storybook or docs should show anatomy, when to use, when not to use, variants, controlled and
+      uncontrolled examples, accessibility names, keyboard behavior, theme tokens, form behavior,
+      migration notes, and do-not patterns.
+    - Props tables are not enough.
+    - Happy-path-only stories are weak contracts; important states need stories that tests can
+      target.
+13. Review test layers.
+    - Type and export tests catch public API drift.
+    - Behavior tests should use roles, names, keyboard events, state changes, and form behavior
+      instead of brittle internal selectors.
+    - Accessibility automation is a floor, not proof. Manual keyboard, focus, screen-reader smoke,
+      forced-colors, reduced-motion, and target-size evidence may still be needed.
+    - Visual regression should cover a representative matrix, not every combinatorial explosion.
+      Keep failures diagnosable.
+    - SSR, hydration, bundle size, tree-shaking, and CSS side-effect checks matter when the package
+      claims app-framework or library-mode support.
+14. Classify breaking changes broadly.
+    - Public API includes exports, props, prop meaning, defaults, event timing, refs, CSS variables,
+      token names, slot names, data attributes, documented DOM hooks, keyboard behavior, form
+      behavior, theme resolution order, peer dependency ranges, generated files, and docs examples.
+    - Removing, renaming, narrowing, changing defaults, changing ref targets, changing event order,
+      blocking deep imports, deleting CSS variables, or changing documented data attributes may be
+      major-version work.
+15. Plan migrations before removals.
+    - Prefer deprecation warnings and docs in a compatible release before removal.
+    - Provide migration notes and codemods for broad prop, import, token, or slot renames.
+    - Keep examples, changelog, tests, and generated docs aligned with the migration path.
+16. Report the evidence level honestly.
+    - Separate static package inspection, docs inspection, type-test evidence, behavior-test
+      evidence, visual-regression evidence, accessibility evidence, browser evidence, and
+      consumer-upgrade evidence.
+    - If an evidence path is unconfigured, name the missing configured intent or manual review
+      instead of claiming readiness.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Public API, token, primitive behavior, component contract, state contract, variant, theming,
+  styling, docs, test, and release ledgers are fixed, ruled out, or reported.
+- Component-library consumers can tell what is safe to import, style, theme, override, test, and
+  rely on across upgrades.
+- Breaking-change risk is classified across code, tokens, CSS, docs, tests, package exports, and
+  runtime behavior.
+- Missing Storybook, browser, visual, accessibility, package, or consumer-upgrade evidence is named
+  instead of hidden.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured unit, component, docs, release, build, package, visual, accessibility,
+or mustflow intent that covers the changed component-library contract. Do not infer raw Storybook,
+browser, package-manager, visual-regression, or dev-server commands outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the public API ledger cannot be built, stop treating the change as SemVer-safe and report the
+  missing source of truth.
+- If token source, generated CSS variables, generated types, and docs disagree, fix the source and
+  generated-surface contract before changing individual components.
+- If a component requires custom primitive behavior but keyboard and focus behavior are unknown,
+  route to `frontend-accessibility-tree-review` or report the missing evidence.
+- If a variant or theming change creates impossible combinations, narrow the API, split the
+  component, or report the product decision needed.
+- If tests fail, preserve the configured intent name and failure evidence, then fix the contract
+  surface rather than weakening tests.
+- If release impact is unclear, apply `date-number-audit` before editing versions or release notes.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Component-library surface reviewed
+- Package API, token, primitive, component, state, variant, theming, styling, docs, test, and release
+  ledgers
+- Findings, fixes, or recommendations
+- Breaking-change and migration classification
+- Evidence level by docs, types, behavior, accessibility, visual, package, browser, and consumer
+  upgrade surface
+- Narrower skills used or deferred
+- Command intents run
+- Skipped component-library checks and reasons
+- Remaining component-library contract risk