mustflow 2.107.3 → 2.108.0

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

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.frontend-localization-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 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.
+description: Apply this skill when frontend UI, product copy, messages, translation keys, message catalogs, metadata, SEO or hreflang, localized routes, notifications, exports, locale handling, fallback, translation workflow, 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
@@ -29,18 +29,20 @@ metadata:
 <!-- 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.
+Review frontend localization by tracing every user-visible string, locale-sensitive value, locale route, direction-sensitive layout choice, translation workflow, 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.
+The core question is: "Can the product say the right thing, in the right grammar, format, direction, tone, URL, search result, 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, URL structure, 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 translation keys, key naming, stale or missing key behavior, 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.
+- UI needs to support long translated labels, pseudo localization, RTL or bidirectional text, locale-specific font fallback, language switching, locale-specific routes, server rendering, hydration, or client/server locale agreement.
+- International SEO changes involve language-specific URLs, canonical links, `hreflang`, `x-default`, locale sitemaps, localized title or meta description, Open Graph, structured data, or automatic locale redirects.
+- Translation workflow, TMS sync, string freeze, glossary, translation memory, screenshot context, placeholder metadata, locale launch readiness, missing-key telemetry, or fallback monitoring is created, changed, reviewed, or reported.
+- A review or final report claims a surface is translated, localization-safe, i18n-ready, l10n-ready, RTL-ready, locale-aware, SEO-localized, or global-ready.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -48,6 +50,7 @@ The core question is: "Can the product say the right thing, in the right grammar
 - 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.
+- The task is only generic SEO unrelated to locale-specific URLs, metadata, hreflang, translated content, or locale routing.
 - 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.
 
@@ -55,12 +58,27 @@ The core question is: "Can the product say the right thing, in the right grammar
 ## 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.
+- Locale model ledger: language, script, region, calendar, numbering system, time zone, currency,
+  measurement unit, explicit user preference, URL locale, cookie or account locale, browser hint,
+  and fallback order.
 - 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.
+- Translation-key ledger: key naming policy, domain or screen namespace, context, source text,
+  translator notes, key reuse, key lifecycle, stale keys, missing keys, fallback behavior, and
+  source-of-truth catalog.
+- Message-shape ledger: full sentence keys, interpolation values, placeholder names and examples, grammatical context, plural categories, select cases, 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.
+- SEO and routing ledger: localized URL shape, route locale priority, automatic redirects, canonical
+  links, `hreflang`, `x-default`, locale sitemap, translated metadata, Open Graph, structured data,
+  and crawler-visible content.
+- Translation workflow ledger: key extraction, static validation, TMS or XLIFF sync, glossary,
+  translation memory, screenshot context, string freeze, human review requirements, AI translation
+  limits, locale launch threshold, and release blocking rules.
+- Operations ledger: missing-key rate, fallback rate, bundle load failures, per-locale error rate,
+  conversion or task metrics, locale-specific support tickets, and safe logging fields such as
+  requested locale, resolved locale, fallback chain, time zone, and currency.
 - Evidence level: static string inventory, catalog diff, pseudo-localization evidence, locale snapshot evidence, configured tests, SSR hydration evidence, or missing evidence.
 
 <!-- mustflow-section: preconditions -->
@@ -69,6 +87,8 @@ The core question is: "Can the product say the right thing, in the right grammar
 - 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.
+- Locale decisions are treated as product state, not only presentation. Do not assume language,
+  country, currency, time zone, and measurement unit are the same setting.
 - 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 -->
@@ -79,7 +99,9 @@ The core question is: "Can the product say the right thing, in the right grammar
 - 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.
+- Add or refine localized route metadata, `hreflang`, canonical, locale sitemap, fallback telemetry,
+  or key lifecycle checks where existing project patterns support them.
+- Do not invent a translation-management system, rewrite all catalogs, install i18n packages, machine-translate production copy, change legal or pricing copy semantics, or broaden product language policy beyond the changed surface.
 
 <!-- mustflow-section: procedure -->
 ## Procedure
@@ -93,74 +115,144 @@ The core question is: "Can the product say the right thing, in the right 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.
+4. Check translation-key lifecycle.
+   - Do not use raw source prose as a stable key when ordinary copy editing would invalidate all
+     translations.
+   - Do not use dictionary keys such as `ok`, `title`, `description`, or `submit` when the key
+     lacks product context.
+   - Check added, renamed, unused, orphaned, and missing keys, including keys that exist only in
+     default-language catalogs or only in the translation platform.
+   - Missing keys and fallback usage should be visible in development, CI, staging, or production
+     diagnostics according to project policy.
+5. 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.
+6. Check plural, select, 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.
+   - Use ICU plural, select, or the project's message system for all supported locale categories and
+     state or gender variants.
    - Give zero-result states their own UX wording when "0 items" would be awkward or misleading.
-6. Check language-specific grammar traps.
+   - Keep complex plural or select branches as complete sentences so translators can move words,
+     variables, and clauses safely.
+7. 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.
+   - Prefer neutral rewrites over collecting sensitive profile attributes such as gender only to
+     satisfy grammar in one message.
+8. Check placeholder and rich-context metadata.
+   - Named placeholders should explain whether the value is a person, organization, URL, amount,
+     count, product name, untranslated brand term, or user-provided text.
+   - Translators need screenshots, character limits, tone, glossary terms, and examples for
+     ambiguous words such as free, open, archive, owner, and plan.
+9. 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.
+10. Check date, time, calendar, 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.
+   - Store instants and local event time-zone identifiers intentionally. Recurring local-time events
+     should not become naive UTC repeats when daylight-saving or civil-time rules matter.
    - Treat `new Date()` in render paths, server-rendered relative time, and client hydration time as mismatch risks.
-9. Check numbers, currency, percent, and units.
+11. 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.
+   - For prices, invoices, receipts, taxes, and billing text, distinguish display currency,
+     settlement or charge currency, tax inclusion, rounding, exchange-rate snapshot, and legal
+     document requirements.
+12. 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.
+   - Align client filtering, database collation, and search-engine analyzers so search results do
+     not differ by layer.
+13. Check names, addresses, phone numbers, and user data.
+   - Do not force global users into first-name/last-name, state/ZIP-only addresses, numeric phone
+     numbers, numeric postal codes, ASCII-only names, or fixed short field limits.
+   - Treat names, phone numbers, postal codes, and identifiers as display strings unless the domain
+     has a validated canonical structure.
+14. 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.
+15. 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.
+   - Ensure document or route shells set compatible `lang` and `dir` values, not only leaf text.
    - 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.
+16. 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.
+17. 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.
+18. 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.
+19. Check locale routing and preference priority.
+   - Prefer explicit user or URL locale over `Accept-Language` or browser hints. Browser hints
+     should not overwrite a user's saved or URL-selected language.
+   - Define priority across URL locale, account preference, cookie, browser hint, and default
+     locale so server and client choose the same locale.
+   - Avoid one URL serving many languages unless cache, SEO, and `Vary` behavior are explicitly
+     designed.
+20. 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.
+21. 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.
+   - Separate locale fallback, namespace fallback, key fallback, runtime bundle-load fallback, and
+     SEO fallback. They solve different failures and need different evidence.
+22. Check international SEO.
+   - Locale variants should have crawler-visible, stable URLs when SEO matters.
+   - Check `lang`, localized title and meta description, Open Graph, canonical URL,
+     self-referencing and reciprocal `hreflang`, `x-default`, locale sitemap, and structured data
+     when those surfaces exist.
+   - Do not canonical every translated page to the source-language URL unless the product intends
+     those localized pages not to be indexed.
+   - Avoid forced automatic redirects that prevent users or crawlers from reaching other locale
+     versions.
+23. 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.
+24. 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.
+25. Check image, media, and culturally loaded assets.
+   - Text embedded in images, screenshots, app-store assets, email headers, PDFs, videos, and
+     onboarding media bypasses normal translation pipelines unless assets are locale-keyed.
+   - Review flags-as-language selectors, culturally loaded symbols, gestures, holidays, maps,
+     colors, and people imagery when the surface is public or high-trust.
+26. 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.
+27. Check translation workflow and release gates.
+   - Key extraction, catalog validation, placeholder parity, ICU syntax, unused-key cleanup,
+     missing-key blocking, TMS or XLIFF sync, glossary, translation memory, screenshot context,
+     string freeze, human review, and locale launch thresholds should be named when the task claims
+     production localization readiness.
+   - AI or machine translation may be a draft input, but legal, billing, privacy, security,
+     medical, tax, refund, and marketing claims need the review path required by the product.
+28. Check operations and telemetry.
+   - Per-locale missing-key rate, fallback rate, bundle load failure, error rate, conversion,
+     support tickets, search traffic, refund or billing contacts, and localized-route crawl health
+     should be observable for launched locales when the project has such telemetry.
+   - Logs may include requested locale, resolved locale, fallback chain, time zone, currency, and
+     route locale, but should not become user fingerprinting or leak sensitive content.
+29. 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.
+   - If a claim is static-only, say which runtime locale, time zone, RTL, pseudo-localization, SEO,
+     translation workflow, 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.
+- Messages use full translation units, named interpolation, contextual keys, plural, select, zero handling, tone consistency, and grammar-safe dynamic values where relevant.
+- Translation keys, locale routes, fallback behavior, SEO metadata, `hreflang`, canonical behavior, translation workflow, and missing-key telemetry are fixed, ruled out, or reported where relevant.
+- Dates, times, numbers, currencies, units, names, addresses, 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, SEO, translation workflow, operations telemetry, and export evidence.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -183,9 +275,9 @@ Use the narrowest configured unit, component, i18n, screenshot, build, docs, rel
 ## 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 the project has no plural, formatter, collation, segmentation, localized-route, SEO, pseudo-localization, translation-workflow, 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 translation changes alter accessibility names, focus recovery, layout geometry, payment meaning, legal copy, SEO indexing, privacy disclosures, 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.
 
@@ -194,9 +286,9 @@ Use the narrowest configured unit, component, i18n, screenshot, build, docs, rel
 
 - 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
+- Locale model, translation-key, message-shape, plural, select, zero, grammar, tone, formatter, search, sort, normalization, segmentation, RTL, bidi, font, locale routing, SEO, SSR, fallback, backend-error, rich-text, workflow, operations, 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
+- Evidence level: static inventory, catalog, configured test, pseudo-localization, screenshot, SEO, SSR, translation workflow, operations telemetry, export, manual-only, missing, or not applicable
 - Command intents run
 - Skipped localization checks and reasons
 - Remaining localization risk