mustflow 2.39.1 → 2.58.1

package/templates/default/locales/en/.mustflow/skills/frontend-accessibility-tree-review/SKILL.md

@@ -0,0 +1,202 @@
+---
+mustflow_doc: skill.frontend-accessibility-tree-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: frontend-accessibility-tree-review
+description: Apply this skill when frontend UI is created, changed, reviewed, or reported and accessibility must be checked through the browser accessibility tree, accessible names, visible label consistency, native HTML semantics, keyboard navigation, focus order and return, dialogs, forms, errors, live regions, ARIA attributes, hidden content, icon and image text alternatives, custom widgets, contrast, target size, dragging alternatives, or automated accessibility evidence.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.frontend-accessibility-tree-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Frontend Accessibility Tree Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review frontend accessibility by checking what browsers expose to assistive technology, not whether code contains enough ARIA.
+
+The core question is: "Does the accessibility tree, keyboard path, visible label, and announced state describe the same UI the sighted pointer user sees?" Native HTML should carry the contract first. ARIA should repair unavoidable gaps, not repaint broken semantics.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Frontend UI, controls, forms, dialogs, menus, tabs, comboboxes, custom selects, tables, cards, media, icons, images, drag interactions, loading states, error states, toasts, live updates, or design-system components are created, changed, reviewed, or reported.
+- Code adds or changes `onClick`, `role`, `tabIndex`, `aria-*`, `alt`, `hidden`, `display: none`, `visibility: hidden`, visually hidden text, focus styles, keyboard handlers, dialogs, popovers, menus, tabs, form validation, or live regions.
+- A review or final report claims the UI is accessible, keyboard usable, screen-reader friendly, WCAG-ready, axe-clean, semantically correct, or correctly labeled.
+- A bug report mentions missing names, wrong screen-reader text, inaccessible icon buttons, broken Tab order, focus loss, modal focus leaks, keyboard traps, placeholder-only fields, unannounced async status, or custom widget keyboard failures.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only visual layout stress, overflow, mobile viewport, zoom, or hostile content resilience; use `frontend-stress-layout-review` first and this skill only when assistive-technology or keyboard contracts are also affected.
+- The task is only broad UI quality or visual polish with no semantic, keyboard, focus, form, status-message, target-size, or assistive-technology risk; use `ui-quality-gate`.
+- The task is only first-render performance, Core Web Vitals, bundle size, or per-frame rendering; use the matching frontend performance skill.
+- No user-facing UI, rendered artifact, browser DOM, or interaction contract is affected.
+- Verification would require an unconfigured browser, screen reader, accessibility snapshot, or dev server. Report the missing accessibility evidence instead of inventing raw commands.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, changed UI surface, current diff or target files, framework and component-library signals, and configured command intents.
+- Semantic ledger: each interactive element, intended role, native element used, accessible name source, visible label, current state, disabled behavior, and destination or action semantics.
+- Keyboard ledger: tab order, Enter and Space behavior, arrow-key contract, Escape behavior, focus trap, focus return, roving tabindex if used, and skip or landmark navigation when relevant.
+- Assistive-technology ledger: accessibility tree role/name/state evidence, `aria-labelledby` and `aria-describedby` references, live region behavior, hidden content policy, and icon or image text alternatives.
+- Form ledger: labels, instructions, placeholder usage, fieldset and legend groups, validation timing, `aria-invalid`, error descriptions, error summary, and submit-failure focus behavior.
+- Interaction ledger: dialogs, menus, tabs, comboboxes, custom selects, drag and drop, sliders, touch targets, pointer alternatives, focus visibility, obscured focus, non-text contrast, reduced motion, and async status updates.
+- Evidence level: static markup evidence, lint or axe evidence, Testing Library `getByRole` evidence, Playwright accessibility snapshot evidence, keyboard walkthrough evidence, screen-reader manual evidence, or missing evidence.
+
+<!-- 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 buttons, links, icons, forms, dialogs, menus, tabs, comboboxes, toasts, live regions, focus rings, and visually hidden text have been searched before adding a new accessibility pattern.
+- If an accessibility issue is caused by state ownership, permission logic, layout stress, rendering performance, or security flow, also apply the narrower matching skill for that boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Replace fake interactive elements with native HTML such as `<button type="button">`, `<a href>`, `<label>`, `<fieldset>`, `<legend>`, `<select>`, and form controls when they match the interaction.
+- Add or correct accessible names, label associations, descriptions, `aria-invalid`, `aria-expanded`, `aria-selected`, `aria-checked`, `aria-current`, `aria-busy`, live regions, focus management, keyboard handlers, and hidden-content behavior when native semantics are insufficient.
+- Fix icon, SVG, image, and alt text contracts; add decorative `aria-hidden`, `focusable="false"`, meaningful labels, or empty alt text according to the element's role.
+- Add focused tests, fixtures, or assertions that use roles, names, keyboard interaction, focus behavior, or accessibility snapshots when existing project patterns support them.
+- Do not replace native controls with custom widgets, add broad ARIA frameworks, create a visual test suite, start a browser or screen-reader workflow, or change product interaction semantics beyond the affected accessibility contract.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Start from the accessibility tree, not the JSX.
+   - For each important control, name the exposed role, accessible name, state, and description.
+   - If no tree evidence exists, do a static semantic pass and label the result as static evidence.
+2. Prefer native semantics before ARIA.
+   - A clickable `div`, `span`, `li`, `svg`, or `img` is suspicious when the intended control is a button or link.
+   - Use `<button type="button">` for actions and `<a href>` for navigation. Do not accept `role="button"` until the native element is proven impossible.
+3. Separate links from buttons.
+   - Navigation, file downloads, external URLs, and section jumps are links.
+   - Saving, deleting, opening menus, toggling panels, submitting forms, and launching modals are buttons.
+   - Flag `href="#"`, `javascript:void(0)`, `preventDefault()` link fakery, and `<a onClick>` without a real `href`.
+4. Audit `onClick` and keyboard parity.
+   - Pointer actions need keyboard access. Native buttons already cover focus, Enter, Space, disabled behavior, and form defaults.
+   - Custom widgets must define the key contract explicitly instead of sprinkling `tabIndex={0}` and hoping.
+5. Audit tabindex.
+   - `tabIndex={0}` should be rare and tied to a real composite widget or programmatic focus need.
+   - `tabIndex={-1}` is for script focus targets such as error summaries or dialog headings.
+   - A positive tabindex almost always creates a fake tab order and should be removed or reported.
+6. Preserve visible focus.
+   - Reject `outline: none`, global focus removal, and focus styles hidden under sticky headers, bottom bars, banners, or overlays.
+   - Prefer `:focus-visible` when mouse focus rings caused the team to remove focus indicators.
+   - Check that focused controls are not obscured by fixed or sticky content.
+7. Review dialogs by focus flow.
+   - A dialog needs a name, initial focus, contained Tab movement, Escape or clear close behavior when appropriate, background inertness or equivalent blocking, and focus return to the opener.
+   - `role="dialog"` or `aria-modal="true"` alone is not enough.
+8. Check icon-only controls.
+   - `<button><Icon /></button>` needs an accessible name such as an `aria-label` or associated visible text.
+   - If visible text already names the control, do not override it with a conflicting `aria-label`.
+   - The visible label should be included in the accessible name so speech input users can say what they see.
+9. Validate label references.
+   - `aria-labelledby` and `aria-describedby` values must be element id references, not prose.
+   - Check that referenced ids exist, are unique, are not hidden incorrectly, and remain translated with the visible UI.
+10. Audit hidden content.
+    - `aria-hidden="true"` on a parent hides all descendants from assistive technology; do not leave focusable buttons or links inside it.
+    - Distinguish `hidden`, `display: none`, `visibility: hidden`, visually hidden text, and `aria-hidden`.
+    - Offscreen or visually hidden content must not trap focus outside the visible viewport.
+11. Review SVG and icon defaults.
+    - Decorative icons should usually be `aria-hidden="true"` and `focusable="false"`.
+    - Meaningful standalone icons need a name strategy.
+    - Avoid duplicate announcements such as icon title plus visible text reading the same word twice.
+12. Review image alt by role.
+    - Informative images need concise useful text.
+    - Functional images inside links or buttons should describe the action or destination.
+    - Decorative images should use `alt=""`.
+    - Reject filler alt such as "image", "thumbnail", "icon", or raw filenames.
+13. Review forms.
+    - Placeholder is not a label. Each input needs a durable label relationship unless a project-approved equivalent exists.
+    - Radio and checkbox groups need a group name, usually `fieldset` and `legend`.
+    - Instructions and errors should be programmatically connected to the relevant controls.
+14. Review validation and submit failure.
+    - Errors need text, not only red borders or icons.
+    - Invalid controls should expose invalid state and error descriptions.
+    - After submit failure, move focus to an error summary or first invalid control when that best supports recovery, and do not steal focus during ordinary typing.
+15. Announce important async status.
+    - Saving, saved, failed, cart updated, search results changed, zero results, upload progress, and background validation may need a `status`, `alert`, or live region pattern.
+    - Do not spam announcements for every minor rerender.
+16. Review ARIA pattern widgets by keyboard contract.
+    - Menus, menu buttons, tabs, comboboxes, listboxes, tree views, grids, sliders, and custom selects need their pattern's role, state, focus, and key behavior together.
+    - Attributes without keyboard behavior create an accessibility-tree costume, not an accessible widget.
+17. Challenge custom select and combobox work.
+    - Prefer native `<select>` unless search, async options, multi-select, rich option content, or a proven library requires custom behavior.
+    - Custom selects need mobile touch, keyboard, screen reader, IME, scroll, portal, and focus behavior checked together.
+18. Check non-text contrast and target size.
+    - Focus rings, input borders, toggle states, chart lines, error icons, and meaningful graphics need sufficient contrast against adjacent colors.
+    - Pointer targets need a real clickable area, not just a visible icon size.
+19. Provide non-drag alternatives.
+    - Sorting, sliders, map pins, uploads, and kanban moves cannot be drag-only when the product task can be exposed through buttons, numeric input, or single-pointer alternatives.
+20. Treat automation as a floor.
+    - eslint accessibility rules, axe, Testing Library `getByRole`, and Playwright accessibility snapshots are useful smoke checks.
+    - They do not prove focus return, meaningful business labels, speech input label consistency, or human-understandable error recovery by themselves.
+21. Report the evidence honestly.
+    - Separate static markup evidence, automated rule evidence, accessibility-tree evidence, keyboard walkthrough evidence, and manual screen-reader evidence.
+    - If a finding is based on code inspection only, say so and name the missing runtime proof.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Important controls have correct native semantics or a justified ARIA pattern with matching keyboard behavior.
+- The accessibility tree exposes the intended role, accessible name, description, and state without fighting visible labels or translated text.
+- Tab order, focus visibility, focus containment, focus return, hidden content, forms, errors, live regions, icons, images, custom widgets, contrast, target size, and drag alternatives are fixed, ruled out, or reported where relevant.
+- Automated accessibility claims are not treated as full accessibility proof unless keyboard and assistive-technology behavior were also verified or explicitly marked as unverified.
+
+<!-- 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, accessibility, browser, build, docs, release, or mustflow intent that covers the changed accessibility contract. Use axe, Playwright accessibility snapshots, screen readers, browser DevTools, dev servers, or interactive keyboard walkthroughs only when they are configured one-shot intents or explicitly approved by the user.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If runtime accessibility-tree evidence is unavailable, report the missing evidence instead of claiming screen-reader safety.
+- If native HTML can solve the interaction, prefer that before adding ARIA and custom keyboard code.
+- If an ARIA pattern cannot be completed with the required keyboard and focus behavior, keep or restore the simpler native control and report the unsupported custom widget.
+- If a fix changes product semantics, navigation behavior, form submission, or permission visibility, apply the relevant business, state, or security skill before continuing.
+- If a configured test or build fails after an accessibility change, preserve the failing intent and output tail, then use `failure-triage` before broadening the fix.
+- If verification requires unconfigured browser automation or manual screen-reader testing, stop at that boundary and report the skipped check.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Frontend accessibility surface reviewed
+- Semantic, keyboard, focus, accessible-name, hidden-content, form, status-message, widget, contrast, target-size, and drag-alternative checks where relevant
+- Accessibility tree or static semantic evidence level
+- Findings, fixes, or recommendations
+- Automated accessibility evidence and its limits
+- Command intents run
+- Skipped accessibility checks and reasons
+- Remaining accessibility-tree risk

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

@@ -0,0 +1,202 @@
+---
+mustflow_doc: skill.frontend-localization-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: frontend-localization-review
+description: Apply this skill when frontend UI, product copy, messages, metadata, notifications, exports, locale handling, formatting, sorting, search, SSR hydration, RTL behavior, or i18n tests are created, changed, reviewed, or reported and localization correctness must be checked beyond visible JSX text.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.frontend-localization-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Frontend Localization Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review frontend localization by tracing every user-visible string, locale-sensitive value, direction-sensitive layout choice, and exported text surface instead of only scanning visible JSX text.
+
+The core question is: "Can the product say the right thing, in the right grammar, format, direction, tone, and channel for this user's language, region, currency, unit, and time zone?" A translated screen is not localized if placeholders, validation errors, file names, emails, metadata, numbers, dates, sort order, or fallback behavior still leak the source locale.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Frontend UI, product copy, forms, validation, error messages, empty states, toasts, dialogs, emails, push notifications, share text, exports, downloads, PDFs, CSVs, calendar invites, charts, canvas, SVG text, document titles, metadata, Open Graph, or SEO text are created, changed, reviewed, or reported.
+- Code adds or changes translation keys, message catalogs, `t(...)`, ICU messages, placeholders, `aria-label`, `title`, `alt`, `meta` tags, Open Graph text, browser `confirm` text, chart labels, file names, copy-to-clipboard text, or backend error-code mapping.
+- Code adds or changes date, time, relative-time, number, currency, percent, unit, plural, list, case, collation, search normalization, truncation, string length, or user-input parsing logic.
+- UI needs to support long translated labels, pseudo localization, RTL or bidirectional text, locale-specific font fallback, language switching, server rendering, hydration, or client/server locale agreement.
+- A review or final report claims a surface is translated, localization-safe, i18n-ready, RTL-ready, locale-aware, or global-ready.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only hostile layout resilience from long translated text or RTL layout without translation, formatting, or locale-state risk; use `frontend-stress-layout-review` first and this skill only for localization semantics.
+- The task is only accessibility names, labels, ARIA, keyboard, focus, or assistive-technology behavior; use `frontend-accessibility-tree-review` first and this skill only when translated names or visible-label consistency are involved.
+- The task is only copy tone in one language with no locale, formatting, fallback, or translation-key surface.
+- No user-visible text, locale-sensitive value, user-entered text, exported text, metadata, search, sort, SSR locale, or direction-sensitive behavior is affected.
+- Verification would require an unconfigured pseudo-localization, screenshot, browser, or translation-management workflow. Report the missing localization evidence instead of inventing raw commands.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, changed UI or text surface, current diff or target files, framework and i18n library signals, supported locale policy, and configured command intents.
+- String exposure ledger: visible text, placeholders, labels, `aria-label`, `title`, `alt`, document title, metadata, Open Graph, toasts, validation, errors, empty states, confirm prompts, chart labels, SVG text, canvas text, clipboard text, download file names, emails, push notifications, exports, PDFs, CSV headers, and calendar invites.
+- Message-shape ledger: full sentence keys, interpolation values, grammatical context, plural categories, zero case, Korean particles or other inflection needs, tone or formality, reusable key risks, and HTML or component interpolation.
+- Format ledger: dates, times, relative times, time zones, calendars, numbers, currency, percent, units, measurement systems, list formatting, input parsing, and display versus storage values.
+- Text-processing ledger: case conversion, search, sort, collation, accent handling, Unicode normalization, grapheme segmentation, truncation, ellipsis policy, and file or user name handling.
+- Direction and layout ledger: RTL, bidirectional user content, `dir="auto"`, logical CSS properties, direction-sensitive icons, font fallback, line height, long translated labels, pseudo localization, and locale-specific screenshot coverage.
+- Runtime locale ledger: language versus region versus currency versus time zone versus unit settings, fallback behavior, missing-key handling, server-rendered locale, client hydration locale, and backend error-code mapping.
+- Evidence level: static string inventory, catalog diff, pseudo-localization evidence, locale snapshot evidence, configured tests, SSR hydration evidence, or missing evidence.
+
+<!-- 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 message catalogs, ICU syntax, locale routing, formatters, error-code mapping, pseudo localization, RTL support, and exported text have been searched before adding a new pattern.
+- If localization changes affect layout, accessibility, payment, business rules, security, or API contracts, also apply the narrower matching skill for that boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Move hardcoded user-visible strings into the project-approved message catalog or translation mechanism.
+- Replace string concatenation and word-fragment assembly with full-sentence messages and named interpolation values.
+- Add or correct plural, zero, context-specific, tone-specific, Korean particle, or inflection-safe messages when the project pattern supports them.
+- Replace ad hoc date, time, number, currency, unit, list, sort, search, and segmentation logic with locale-aware helpers or existing project formatters.
+- Add or refine RTL, `dir="auto"`, logical CSS property, pseudo-localization, locale screenshot, missing-key, backend error-code mapping, and export-text coverage where existing project patterns support them.
+- Do not invent a translation-management system, rewrite all catalogs, install i18n packages, machine-translate production copy, or broaden product language policy beyond the changed surface.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build the string exposure ledger before editing.
+   - Include JSX text, `placeholder`, `aria-label`, `title`, `alt`, document title, metadata, Open Graph, toasts, validation, empty states, dialogs, browser `confirm`, chart labels, SVG `<text>`, canvas text, clipboard text, file names, emails, push notifications, exports, PDFs, CSV headers, and calendar invites.
+   - Treat "not on the screen" as still user-visible when the user can save, share, print, hear, search, preview, or receive it.
+2. Check full-sentence translation units.
+   - Reject `t('hello') + name + t('welcome')`, translated word fragments, and grammar assembled in code.
+   - Use full messages with named interpolation values so translators can change word order and surrounding grammar.
+3. Check context-specific wording.
+   - Do not reuse a generic key when the same source word means different things, such as file open, business open, and public status.
+   - Prefer keys that name the product context, user action, and destination surface rather than a short dictionary word.
+4. Check destructive and action labels as complete phrases.
+   - Do not build labels like `Delete {item}` from separate translated parts when languages need different order, case, or particles.
+   - Use context-specific messages such as delete project, delete file, or delete account.
+5. Check plural and zero cases.
+   - Do not model plural as only `count === 1`.
+   - Use ICU plural or the project's plural system for all supported locale categories.
+   - Give zero-result states their own UX wording when "0 items" would be awkward or misleading.
+6. Check language-specific grammar traps.
+   - For Korean, review particles such as eun/neun, i/ga, eul/reul, and wa/gwa or avoid the particle with a safer sentence shape.
+   - For other languages, check case, gender, noun class, politeness, or inflection needs when dynamic values are inserted into prose.
+7. Check tone and formality inside one flow.
+   - Compare adjacent labels, confirmations, validation messages, empty states, and recovery actions.
+   - A flow that mixes formal and casual voice should be fixed or reported as product-language drift.
+8. Check date, time, and relative-time formatting.
+   - Reject manual assembly such as `year + '.' + month + '.' + day`.
+   - Use locale-aware formatters and confirm whether the user's time zone, server time zone, and stored instant can shift deadlines, bookings, billing dates, or "yesterday" labels.
+   - Treat `new Date()` in render paths, server-rendered relative time, and client hydration time as mismatch risks.
+9. Check numbers, currency, percent, and units.
+   - Do not rely on comma insertion, fixed decimal assumptions, or locale-agnostic `Number(input)` parsing.
+   - Separate display format from canonical stored value.
+   - Keep language, region, currency, time zone, and measurement unit as separate settings unless the product has an explicit rule tying them together.
+10. Check collation, search, and normalization.
+   - Do not trust default `sort()`, raw `localeCompare` without locale intent, or plain `toLowerCase()` for user-facing search and sort.
+   - Use locale-aware collation where order matters.
+   - Normalize Unicode when comparing user names, filenames, tags, search queries, accents, combining characters, or Hangul variants.
+11. Check grapheme-safe length, truncation, and ellipsis.
+   - Do not use `.length` and `slice(0, n)` when user-visible text may contain emoji, flags, skin tones, combining marks, or complex scripts.
+   - Use grapheme-aware segmentation or existing utilities.
+   - Choose ellipsis by content meaning: paths may need middle truncation, names may need enough disambiguating text, and amounts should not be truncated.
+12. Check RTL and bidirectional text.
+   - Replace physical `left` and `right` assumptions with logical `start`, `end`, `inline-start`, and `inline-end` where direction depends on language.
+   - Use `dir="auto"` for user-generated names, comments, reviews, addresses, chat, and profile text when direction may differ from the UI locale.
+   - Do not mirror all icons blindly. Back, next, drawer, and carousel direction may flip; play, download, clock, and brand icons usually should not.
+13. Check translated layout resilience.
+   - Long German, French, Vietnamese, Arabic, pseudo-localized, and compact CJK labels need real fixtures.
+   - Fixed-width buttons, tabs, table headers, modal titles, `white-space: nowrap`, and fixed-height rows should be routed to `frontend-stress-layout-review` when geometry changes are needed.
+14. Check font fallback.
+   - CJK, Thai, Arabic, Hindi, and emoji may need safe fallback fonts, line-height tolerance, and real glyph coverage.
+   - Watch icon fonts, fake bold, missing weights, and square tofu glyphs.
+15. Check pseudo localization and locale snapshots.
+   - Prefer pseudo localization for hardcoded strings, missing keys, broken interpolation, glyph support, and expansion stress before real translations arrive.
+   - For high-trust flows, compare at least a long-language locale, an RTL locale, and a dense CJK or Japanese-style locale when the project has such coverage.
+16. Check SSR and hydration locale agreement.
+   - Server and client must receive compatible locale, time zone, messages, and formatter inputs.
+   - Default-language server output followed by client language switching can cause flicker, hydration mismatch, SEO drift, and different date or number text on first render.
+17. Check fallback and missing-key behavior.
+   - In development, missing keys should be loud enough to catch.
+   - In production, fallback should protect the user while logs, metrics, or diagnostics make the missing translation visible to maintainers.
+   - Do not treat silent English fallback as a successful localization state.
+18. Check HTML and rich text in translations.
+   - Do not let translators edit raw HTML when component interpolation can preserve link, emphasis, and accessibility structure safely.
+   - Links and emphasis inside a sentence must be movable by locale without exposing XSS, broken tags, or fixed English word order.
+19. Check backend error message boundaries.
+   - Do not show raw backend prose such as "Invalid password" directly in localized UI.
+   - Prefer stable error codes mapped to localized frontend messages, with safe fallback for unknown codes.
+20. Check export, share, and notification surfaces.
+   - Confirm CSV headers, PDF receipts, downloaded file names, email subjects, email bodies, push notifications, share text, clipboard output, printed output, and calendar invites follow the same language and formatting policy as the screen.
+21. Report evidence by surface.
+   - Separate string-inventory evidence, catalog evidence, formatter evidence, pseudo-localization evidence, screenshot evidence, SSR evidence, and export or notification evidence.
+   - If a claim is static-only, say which runtime locale, time zone, RTL, pseudo-localization, or export proof is missing.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- User-visible strings across screen, metadata, notifications, exports, downloads, and assistive labels are either localized, intentionally excluded, or reported.
+- Messages use full translation units, named interpolation, contextual keys, plural and zero handling, tone consistency, and grammar-safe dynamic values where relevant.
+- Dates, times, numbers, currencies, units, search, sort, case conversion, Unicode normalization, grapheme length, truncation, RTL, bidi text, font fallback, SSR locale, fallback, backend errors, and rich text are fixed, ruled out, or reported where relevant.
+- Localization readiness claims distinguish static catalog evidence from pseudo-localization, locale snapshot, SSR, runtime formatter, and export evidence.
+
+<!-- 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, i18n, screenshot, build, docs, release, or mustflow intent that covers the changed localization contract. Use pseudo-localization, browser screenshots, translation-management checks, SSR render checks, or export generation only when they are configured one-shot intents or explicitly approved by the user.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a string surface cannot be enumerated, report the missing exposure ledger before claiming localization coverage.
+- If the project has no plural, formatter, collation, segmentation, pseudo-localization, or missing-key pattern, preserve existing behavior and report the missing project contract instead of inventing a broad framework.
+- If language, region, currency, time zone, or unit settings are conflated, avoid patching one locale branch only; report the model issue or make the smallest local split required by the changed surface.
+- If translation changes alter accessibility names, focus recovery, layout geometry, payment meaning, legal copy, or security-sensitive messaging, apply the matching skill before continuing that part.
+- If a configured test or build fails after a localization change, preserve the failing intent and output tail, then use `failure-triage` before broadening the fix.
+- If verification requires unconfigured browser, pseudo-localization, screenshot, SSR, export, or translation-management tooling, stop at that boundary and report the skipped check.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Frontend localization surface reviewed
+- String exposure ledger
+- Message-shape, plural, zero, grammar, tone, formatter, search, sort, normalization, segmentation, RTL, bidi, font, SSR, fallback, backend-error, rich-text, export, share, and notification checks where relevant
+- Localization fixes or recommendations
+- Evidence level: static inventory, catalog, configured test, pseudo-localization, screenshot, SSR, export, manual-only, missing, or not applicable
+- Command intents run
+- Skipped localization checks and reasons
+- Remaining localization risk

package/templates/default/locales/en/.mustflow/skills/frontend-state-ownership-review/SKILL.md

@@ -0,0 +1,183 @@
+---
+mustflow_doc: skill.frontend-state-ownership-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: frontend-state-ownership-review
+description: Apply this skill when frontend code is created, changed, reviewed, or reported and state ownership, duplicated state, derived state, server-cache copying, URL state, form drafts, optimistic updates, request races, query keys, context rerenders, persisted client state, SSR hydration, or external subscriptions can make the UI show stale, contradictory, or silently overwritten values.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.frontend-state-ownership-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Frontend State Ownership Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review frontend state by asking who owns each fact, not which state library is fashionable.
+
+The core question is: "Can the same value live in two places and drift?" If yes, the UI can render a lie. Make one source authoritative, derive the rest, and keep server cache, URL state, local drafts, global app context, and external subscriptions from pretending to be the same thing.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Frontend code is created, changed, reviewed, or reported and the risk is stale, duplicated, contradictory, over-lifted, under-lifted, or race-prone state.
+- React, Vue, Svelte, Solid, Angular, TanStack Query, Redux, Zustand, Jotai, MobX, Apollo, SWR, router state, form state, local storage, session storage, IndexedDB, context providers, or external stores hold data that could also exist in props, component state, server cache, URL params, or derived selectors.
+- Code introduces or changes `useState(props...)`, derived values in state, boolean loading or mode clusters, selected objects, query keys, invalidation rules, optimistic updates, request cancellation, context values, persisted client stores, SSR hydration branches, or `useSyncExternalStore`-style subscriptions.
+- A review claims the state is safe because it uses a popular library, is "just UI state", is copied only once, has an effect to keep it synced, or currently has small data.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only models impossible domain states in type shapes; use `type-state-modeling-review` first and this skill only when frontend ownership or synchronization is also at risk.
+- The task only reviews cache correctness outside frontend client state; use `cache-integrity-review` first and this skill only for client-side server-cache copies, query keys, stale rendering, or invalidation UI effects.
+- The task only reviews render timing, LCP, CLS, INP, hydration flash, or frame jank; use the matching frontend performance or render-stability skill first and this skill only when state ownership causes the symptom.
+- The task is a purely visual or copy-only UI change with no state, data, routing, form, cache, or subscription behavior.
+- The framework or library owns the state contract and no project code creates, copies, derives, persists, or mutates the value; report that this skill does not apply instead of inventing state risk.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, current diff or target files, framework and state-library signals, and configured command intents.
+- State owner ledger: each state value, authoritative owner, copies, readers, mutators, reset path, persistence path, and rollback path.
+- State class map: server data, URL-owned state, local UI state, form draft, global app context, derived selector value, persisted client state, and external subscription state.
+- Synchronization surfaces: props-to-state initialization, effects that set state, query keys, invalidation, optimistic update, request cancellation, router params, context providers, storage hydration, and external store subscriptions.
+- Identity and collection surfaces: selected IDs versus selected objects, list keys, index keys, object replacement rules, normalized entities, selectors, memoized context values, and row or item local state.
+- Evidence level: static diff evidence, focused test evidence, browser or component verification, missing route or interaction evidence, and any unverified state combinations.
+
+<!-- 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 server data, router state, form drafts, selectors, context providers, global stores, optimistic updates, and cancellation have been searched before adding a new state pattern.
+- If state crosses API, database, security, payment, cache, concurrency, or public JSON boundaries, also apply the narrower matching skill for that boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Remove duplicated state by deriving values during render, through selectors, or through memoized pure helpers when cost justifies memoization.
+- Move state to the nearest owner that matches the user interaction, route, form draft, server cache, or global app context.
+- Replace contradictory boolean flags with one status, mode, or discriminated union when the UI can otherwise express impossible combinations.
+- Store stable identifiers such as `selectedId` instead of selected objects when the canonical entity lives in server cache, normalized state, or parent data.
+- Keep TanStack Query, SWR, Apollo, or router-owned server and URL data in their owners; do not copy them into Redux, Zustand, or component state without a deliberate draft, snapshot, or offline reason.
+- Add or refine query keys, invalidation scope, request cancellation, optimistic rollback, reset keys, selectors, context splitting, memoized provider values, persisted-state versioning, hydration guards, and external subscription wrappers.
+- Add focused tests for stale request ordering, query-key changes, invalidation scope, optimistic rollback, reset behavior, impossible status combinations, and form draft isolation when existing test patterns support them.
+- Do not migrate state libraries, introduce a global store, normalize all entities, or add broad state architecture unless the current ownership problem requires it.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build a State owner ledger before changing code.
+   - For each important value, name the single owner, every copy, every reader, every mutator, reset rules, persistence rules, rollback rules, and whether the value is original or derived.
+   - Classify each value as server data, URL-owned state, local UI state, form draft, global app context, derived selector value, persisted client state, or external subscription state.
+2. Hunt props-to-state copies.
+   - Treat `useState(props` or equivalent initializers as suspicious unless the value is a deliberate draft, snapshot, uncontrolled initial value, or reset-by-key state.
+   - If props should remain live, read props directly or lift the owner; if a draft is intended, name the commit, cancel, and reset behavior.
+3. Remove derived values from mutable state.
+   - Values such as `fullName`, `totalPrice`, `filteredItems`, `isAllChecked`, counts, sorted lists, permissions, and display labels should usually be derived from source facts.
+   - Do not use `useEffect(() => setX(...), [y])` for render-derived state unless the effect synchronizes with an external system.
+   - Watch for effect-derived one-render lag, dependency suppression, and duplicate business logic in components.
+4. Replace contradictory status and mode state.
+   - Flag `isLoading`, `isSuccess`, `isError`, `isSaving`, `isDirty`, `isModalOpen`, `isEdit`, and similar clusters when one lifecycle or mode can express impossible combinations.
+   - Prefer one `status`, `mode`, state machine, or discriminated union with fields required only for that state.
+   - Update grouped state together through one action when partial updates can tear the invariant.
+5. Keep server data in server-data owners.
+   - Do not copy TanStack Query, SWR, Apollo, loader data, or RSC data into global stores or component state just to make it convenient.
+   - Use selectors, query cache reads, or a deliberate form draft instead of cache-as-Redux duplication.
+   - Ensure the query key includes every condition that changes the result, including tenant, user, filters, sort, page, search, locale, feature flags, and auth-dependent scope.
+6. Keep URL-owned state in the URL.
+   - Filters, tabs, sort, page, search terms, selected route IDs, and shareable view state usually belong in route params or query params.
+   - Avoid a second store copy unless the UI has an explicit unsaved draft or debounced input contract.
+7. Review form drafts separately from saved entities.
+   - A form draft may copy initial data, but it needs explicit reset, dirty, submit, cancel, conflict, and post-save behavior.
+   - Do not let live server refetches silently overwrite user edits unless the product contract says so and the UI exposes it.
+8. Store identifiers, not stale objects.
+   - Prefer `selectedId` plus a lookup into the current collection, cache, or normalized entity map.
+   - Recheck index keys when row components have local state; index keys can move state to the wrong item after insert, delete, sort, or filter.
+9. Review mutations and optimistic updates.
+   - Each optimistic update needs rollback, duplicate-submit behavior, disabled or queued actions, failed retry behavior, and invalidation scope.
+   - Mutation invalidation should refresh the smallest true data surface without leaving related lists, detail pages, badges, totals, or permissions stale.
+10. Review request races.
+    - Search, filter, autocomplete, pagination, tab changes, and route changes need AbortController, request IDs, library cancellation, or query-key ownership so older responses cannot overwrite newer state.
+    - Do not accept "last promise wins" unless the library contract proves stale results are ignored.
+11. Review actions and setter exposure.
+    - Avoid exporting raw setters through context or stores when callers need domain intent such as `selectProject`, `applyFilters`, `resetDraft`, or `markSaved`.
+    - Repeated reset calls, scattered business logic, and component-local policy branches should move to an action, selector, or custom hook with one owner.
+12. Review Context and subscription precision.
+    - Context value identity must be stable when consumers are broad; memoize values or split read and write contexts when needed.
+    - Context is not a precise subscription store; high-churn or large stores need selector-based subscriptions or a proper external store.
+    - Browser or external subscriptions should use `useSyncExternalStore` or the framework's equivalent so SSR and hydration see a consistent snapshot.
+13. Review state height.
+    - State too high turns the root into a trash can and rerenders unrelated consumers.
+    - State too low forces sibling synchronization, event buses, prop-drilling hacks, or duplicated URL and cache state.
+    - Move ownership to the nearest common owner that also owns the user action.
+14. Review reset and persistence.
+    - Use `key` resets when component identity should reset local state after route, entity, or draft identity changes.
+    - Persisted stores need serializable values, schema versioning, migrations, storage availability handling, logout or tenant reset, and cross-tab behavior when relevant.
+    - Avoid storing functions, class instances, promises, DOM nodes, dates without encoding policy, or query cache snapshots in persisted client state.
+15. Report the evidence level honestly.
+    - Distinguish static risk from tested behavior, browser-observed behavior, and unverified state combinations.
+    - If a state owner is unknown, report the missing owner instead of papering over it with another copy or effect.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Each important frontend value has one named owner, and copies are either removed, derived, or justified as drafts, snapshots, optimistic entries, persisted state, or external subscription snapshots.
+- Server data, URL-owned state, local UI state, form drafts, global app context, derived selector values, persisted client state, and external subscriptions do not silently overwrite each other.
+- Query keys, invalidation, optimistic rollback, request race handling, context value identity, list keys, reset behavior, and hydration/subscription contracts are checked where relevant.
+- Raw setters, repeated reset logic, and duplicated component business logic are removed or reported when they make state ownership unclear.
+- Focused tests or verification evidence cover the changed state boundary when configured.
+
+<!-- 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 frontend, unit, component, integration, docs, release, or mustflow intent that covers the changed state boundary. Do not infer raw package-manager, dev-server, browser, or watcher commands outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the owner of a state value cannot be named, stop adding synchronization and report the missing ownership decision.
+- If a proposed fix requires a library migration, normalize only the current owner boundary first and report the broader migration as separate work.
+- If a query-key or invalidation fix exposes backend/API ambiguity, apply the relevant API, cache, database, or security skill before pretending the client can infer correctness.
+- If a test failure reveals stale request ordering, optimistic rollback, hydration, or context rerender risk, preserve the failing scenario and fix the ownership or synchronization boundary before broad refactors.
+- If configured verification is missing, report the missing intent instead of inventing raw frontend commands.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Frontend state surface reviewed
+- State owner ledger and state class map
+- Duplicated, derived, contradictory, over-lifted, under-lifted, server-cache, URL, form draft, optimistic, request race, query key, invalidation, Context value, raw setter, index key, reset, persisted state, SSR hydration, and external subscription checks where relevant
+- State ownership, derivation, action, selector, query-key, invalidation, cancellation, rollback, context, persistence, reset, or subscription changes made or recommended
+- Tests or verification evidence
+- Command intents run
+- Skipped frontend checks and reasons
+- Remaining state-ownership risk