mustflow 2.99.2 → 2.103.10

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.html-code-change
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: html-code-change
-description: Apply this skill when HTML, templates, JSX or component markup, native forms, controls, popovers, dialogs, navigation, tables, media, metadata, SEO head content, or structured data are created or changed.
+description: Apply this skill when HTML, templates, JSX or component markup, semantic document structure, native forms, controls, popovers, dialogs, navigation, tables, media, metadata, SEO head content, or structured data are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -47,6 +47,7 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 
 - Existing page layout, document shell, head/SEO helpers, metadata builders, canonical URL helpers, sitemap or robots config, form components, interactive control components, and tests.
 - Target framework conventions for rendering, routing, hydration, and metadata.
+- Semantic structure ledger: the intended `main`, landmark, heading, `section`, `article`, `nav`, `time`, `figure`, form group, table, media, and visible-label contracts.
 - Visible page content, H1 or primary title, main entity, locale, indexing intent, and data sources for title, description, image, author, date, price, rating, availability, and FAQ content when metadata changes.
 - Browser-native behavior expected from the markup: navigation, form submission, validation, autocomplete, input modality, popover behavior, dialog focus, inert background handling, media sizing, lazy loading, and history integration.
 - Accessibility and validation tooling declared in the command contract.
@@ -73,25 +74,37 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 
 1. Read the page shell, route layout, metadata helpers, component patterns, and tests before editing.
 2. Check document outline, landmarks, source order, and heading levels.
-3. Classify each interactive element by intent. Navigation to a URL uses an anchor with `href`. Commands, toggles, submit actions, open/close actions, destructive actions, copy actions, disclosure triggers, and modal triggers use buttons.
-4. Use native form controls for text entry, selection, checkbox, radio, and file input. Use grouped native radio or checkbox controls with fieldset and legend when the group label matters.
-5. Treat composite widgets such as tabs, action menus, comboboxes, listboxes, trees, grids, and custom selects as high-risk. Prefer native HTML or an existing audited component; otherwise implement the complete role, state, focus, and keyboard pattern.
-6. Reject clickable `div` or `span` controls, clickable icons without buttons, anchors without `href`, links used as buttons, nested interactive controls, positive `tabindex`, focusable `aria-hidden` content, and focus outline removal without a replacement focus style.
-7. Use ARIA only when native HTML cannot express the needed semantics. Validate the role is legal for the element, the accessible name exists, required states are present, visual and ARIA states stay synchronized, keyboard behavior matches the widget pattern, and focus behavior is explicit.
-8. For custom legacy button-like elements that cannot be replaced, require `role`, focusability, Enter activation, Space activation, Space scroll prevention, pointer activation, duplicate-event prevention, and visible focus. Use native buttons instead whenever possible.
-9. For popovers, prefer the native popover pattern for lightweight anchored disclosure, teaching UI, picker panels, or menus that do not need modal focus trapping. Verify trigger ownership, light-dismiss behavior, focus behavior, accessible name, and fallback or browser target.
-10. For dialogs, prefer native dialog when the project can support it. Otherwise implement focus entry, Tab and Shift+Tab containment, Escape behavior, inert or unreachable background content, visible close or cancel control, focus return, and an accessible name.
-11. Do not use dialog for every overlay. Use popover for non-modal transient UI, details/summary for simple disclosure, and dialog for modal tasks or interruptions that require focus containment.
-12. For tabs, use tablist, tab, and tabpanel semantics only for a real tabbed interface. Require one active tab, panel linkage, roving tabindex, arrow key movement, Home and End where expected, and Enter or Space activation when activation is manual.
-13. For menus, do not use ARIA menu roles for ordinary site navigation. Site navigation is a nav landmark with links. Use ARIA menu patterns only for application-style action menus with a button trigger, expanded state, focus strategy, Escape close behavior, and focus return.
-14. For forms, verify visible label association, help association, error association, required text, native required state, autocomplete, `inputmode`, `enterkeyhint`, validation timing, invalid state, error summary behavior, and submission behavior.
-15. Prefer native constraint validation for simple required, type, length, pattern, range, and step rules. Add custom validation only for business rules, cross-field rules, async validation, or localized error ownership the native browser cannot express.
-16. Use placeholder, title, aria-label, color, icon, or toast-only feedback only as supplementary affordances, not as the only label, required indicator, or error explanation.
-17. For metadata, read visible content and the metadata generation path first. Keep title, description, canonical, Open Graph, Twitter or X card data, robots, hreflang, and JSON-LD aligned with visible content, locale, URL, and indexing intent.
-18. Structured data must describe content visible on the same page. Do not invent ratings, reviews, FAQ items, authors, prices, availability, dates, organizations, product properties, or claims not backed by the page data source.
-19. Ensure every HTML page has a valid non-empty language and responsive viewport that does not disable zoom. Mixed-language passages should identify their language when needed.
-20. Keep inline script and style minimal; move behavior and styling to the existing project layers unless the framework requires an inline boundary.
-21. Choose configured verification intents that cover markup validity, lint, build, accessibility, route rendering, metadata, and docs when available.
+3. Treat semantic HTML as a machine-readable contract, not as styling decoration. Use `div` for pure wrappers and styling shells.
+4. Use `section` only for a thematic group that has a heading or explicit accessible label. Do not use `section` as a card, spacing, or script wrapper.
+5. Use `article` only for self-contained content that remains meaningful when syndicated, embedded, or moved out of the list, such as posts, articles, reviews, comments, or complete product entries.
+6. Use `nav` only for major navigation or table-of-contents regions. Do not label every incidental link group as navigation.
+7. Keep exactly one active visible `main` region for the page or current SPA view. Do not put repeated headers, footers, sidebars, or global navigation inside the main content unless that is the actual page task.
+8. Treat heading elements as content outline, not font-size controls. Preserve hierarchy by meaning, and use CSS for visual scale.
+9. Classify each interactive element by intent. Navigation to a URL uses an anchor with `href`. Commands, toggles, submit actions, open/close actions, destructive actions, copy actions, disclosure triggers, and modal triggers use buttons.
+10. Use native form controls for text entry, selection, checkbox, radio, and file input. Use grouped native radio or checkbox controls with fieldset and legend when the group label matters.
+11. Keep interactive elements out of labels. Do not place terms links, help buttons, or other controls inside a `label`; connect the label with `for` and `id`, then place related links or buttons outside the label.
+12. Treat composite widgets such as tabs, action menus, comboboxes, listboxes, trees, grids, and custom selects as high-risk. Prefer native HTML or an existing audited component; otherwise implement the complete role, state, focus, and keyboard pattern.
+13. Reject clickable `div` or `span` controls, clickable icons without buttons, anchors without `href`, links used as buttons, nested interactive controls, positive `tabindex`, focusable `aria-hidden` content, and focus outline removal without a replacement focus style.
+14. Use ARIA only when native HTML cannot express the needed semantics. Validate the role is legal for the element, the accessible name exists, required states are present, visual and ARIA states stay synchronized, keyboard behavior matches the widget pattern, and focus behavior is explicit.
+15. For custom legacy button-like elements that cannot be replaced, require `role`, focusability, Enter activation, Space activation, Space scroll prevention, pointer activation, duplicate-event prevention, and visible focus. Use native buttons instead whenever possible.
+16. For popovers, prefer the native popover pattern for lightweight anchored disclosure, teaching UI, picker panels, or menus that do not need modal focus trapping. Verify trigger ownership, light-dismiss behavior, focus behavior, accessible name, and fallback or browser target.
+17. For dialogs, prefer native dialog when the project can support it. Otherwise implement focus entry, Tab and Shift+Tab containment, Escape behavior, inert or unreachable background content, visible close or cancel control, focus return, and an accessible name.
+18. Do not use dialog for every overlay. Use popover for non-modal transient UI, details/summary for simple disclosure, and dialog for modal tasks or interruptions that require focus containment.
+19. For tabs, use tablist, tab, and tabpanel semantics only for a real tabbed interface. Require one active tab, panel linkage, roving tabindex, arrow key movement, Home and End where expected, and Enter or Space activation when activation is manual.
+20. For menus, do not use ARIA menu roles for ordinary site navigation. Site navigation is a nav landmark with links. Use ARIA menu patterns only for application-style action menus with a button trigger, expanded state, focus strategy, Escape close behavior, and focus return.
+21. For forms, verify visible label association, help association, error association, required text, native required state, autocomplete, `inputmode`, `enterkeyhint`, validation timing, invalid state, error summary behavior, and submission behavior.
+22. Prefer native constraint validation for simple required, type, length, pattern, range, and step rules. Add custom validation only for business rules, cross-field rules, async validation, or localized error ownership the native browser cannot express.
+23. Use placeholder, title, aria-label, color, icon, or toast-only feedback only as supplementary affordances, not as the only label, required indicator, or error explanation.
+24. Use `time` with a machine-readable `datetime` when the content represents a precise date, time, duration, or time-like value that tests, crawlers, calendars, or automation may need to parse.
+25. Use `figure` and `figcaption` only for self-contained referenced media, code, diagrams, charts, screenshots, or examples whose caption describes the figure. Do not use `figcaption` for ordinary card titles or unrelated image captions.
+26. Use real tables for tabular data. Include a useful `caption` when the table needs a name, use `th` for row and column headers, and set `scope` when it clarifies the header relationship.
+27. For meaningful media, prefer `img`, `picture`, `video`, or framework media components that preserve alt text, intrinsic dimensions, responsive candidate selection, and browser discovery. Keep decorative media out of the accessibility tree.
+28. For responsive image markup, verify `width`, `height`, `srcset`, `sizes`, `picture` art direction, and lazy or eager loading reflect the rendered slot. Route LCP, preload, priority, CDN, or byte-size claims to `image-delivery-performance-review`.
+29. For metadata, read visible content and the metadata generation path first. Keep title, description, canonical, Open Graph, Twitter or X card data, robots, hreflang, and JSON-LD aligned with visible content, locale, URL, and indexing intent.
+30. Structured data must describe content visible on the same page. Do not invent ratings, reviews, FAQ items, authors, prices, availability, dates, organizations, product properties, or claims not backed by the page data source.
+31. Ensure every HTML page has a valid non-empty language and responsive viewport that does not disable zoom. Mixed-language passages should identify their language when needed.
+32. Keep inline script and style minimal; move behavior and styling to the existing project layers unless the framework requires an inline boundary.
+33. Choose configured verification intents that cover markup validity, lint, build, accessibility, route rendering, metadata, and docs when available.
 
 <!-- mustflow-section: form-accessibility -->
 ## Form Accessibility Rules
@@ -128,16 +141,19 @@ Reject or revise the patch when any of these appear without strong justification
 
 - New `div` or `span` interaction where a native link, button, or form control would work.
 - Anchors without `href`, buttons implemented as links, links implemented as buttons, nested interactive controls, clickable icons without native controls, or site navigation using ARIA menu roles.
+- Decorative `section`, card-only `article`, incidental-link `nav`, multiple active `main` regions, headings chosen for visual size, labels containing nested interactive controls, or data tables rebuilt as non-table grids.
 - Custom controls without complete accessible name, role, state, keyboard, focus, and hidden-content behavior.
 - Popovers, dialogs, or overlays that replace native behavior without trigger, focus, light-dismiss, inert, or fallback review.
 - Positive `tabindex`, hidden content that remains tabbable, focusable `aria-hidden` content, or invisible focus.
 - Form controls without visible labels, placeholder-only labels, disconnected help or error text, color-only required or error state, premature `aria-invalid`, or autocomplete removed without reason.
+- Meaningful dates without parseable `time datetime`, figures used for ordinary card content, tables without header relationships, or meaningful media that lacks alt, intrinsic dimensions, or responsive candidate review.
 - Metadata or JSON-LD that contradicts visible content, fabricates facts, points canonical or social URL at the wrong page, disables zoom, omits page language, or accidentally noindexes a public page.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - Markup communicates the intended structure without relying on visual styling alone.
+- Sections, articles, navigation, main regions, headings, forms, figures, tables, time values, and media expose truthful document semantics.
 - Keyboard and focus behavior are preserved.
 - Forms have labels and errors connected.
 - Metadata and structured data reflect visible content.

package/templates/default/locales/en/.mustflow/skills/next-action-menu/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.next-action-menu
 locale: en
 canonical: true
-revision: 1
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: next-action-menu
-description: Apply this skill when a final report, completion note, repository improvement loop, or follow-up workflow should offer a bounded numbered next-action menu that a user can select with a single digit in the next turn.
+description: Apply this skill when a final report, completion note, repository improvement loop, or follow-up workflow should offer a bounded numbered next-action menu that a user can select with a single digit in the next turn. Use especially after non-trivial completed or paused work, commits, pushes, release or deploy preparation, verification, or remaining approval gates when concrete follow-up actions exist.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -36,6 +36,8 @@ scope, approval, verification, command contracts, release gates, or safety rules
 
 - A final report, completion note, handoff, or repository improvement cycle has one or more useful
   follow-up tasks.
+- A non-trivial task is being reported after changed files, a created commit, completed verification,
+  push readiness, release or deploy preparation, paused work, or another concrete approval gate.
 - The user repeatedly asks for "next recommended work", "continue", "proceed", or selects follow-up
   items after previous completion reports.
 - The agent needs to present a bounded backlog that can be selected by a single digit in the next
@@ -48,9 +50,10 @@ scope, approval, verification, command contracts, release gates, or safety rules
 - The current answer is a tiny direct response with no meaningful follow-up.
 - There are no evidence-backed next actions, or all plausible next actions are speculative.
 - The user asked not to include recommendations, menus, or follow-up prompts.
-- The next action requires a blocking product, security, privacy, legal, release, migration,
-  destructive, dependency, credential, deployment, or payment decision that has not been authorized.
-  Report the decision gate instead of offering it as a one-digit action.
+- The only possible next action requires a blocking product, security, privacy, legal, release,
+  migration, destructive, dependency, credential, deployment, or payment decision that has not been
+  authorized and there is no safe bounded action to describe. Report the decision gate instead of
+  offering it as a one-digit action.
 - Another interface already owns selection state and has a stricter picker, ticket, or work-order
   contract.
 
@@ -89,8 +92,11 @@ scope, approval, verification, command contracts, release gates, or safety rules
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Decide whether a menu is useful.
-   - Include a menu only when at least one concrete follow-up task is valuable.
+1. Decide whether a menu is useful or required.
+   - Include a menu when at least one concrete follow-up task is valuable.
+   - For non-trivial completion reports, commits, completed verification, push readiness, release or
+     deploy preparation, paused work, or unresolved approval gates, treat the menu as required when
+     any concrete next action exists.
    - Do not fabricate filler items to reach a fixed row count.
 2. Build at most nine items.
    - Use digits `1` through `9`.
@@ -108,6 +114,13 @@ scope, approval, verification, command contracts, release gates, or safety rules
    the host format allows it.
    - Use four columns: number, next task title, description, and recommendation score.
    - In Korean final reports, use `추천도` for the recommendation-score column label.
+   - Use non-breaking padding in short header cells so narrow renderers do not wrap Korean headers
+     vertically. Prefer this template:
+     `| 번호&nbsp;&nbsp; | 다음 작업 | 설명 | 추천도&nbsp;&nbsp; |`
+     `|---:|---|---|:---:|`
+     For English, prefer:
+     `| No.&nbsp;&nbsp; | Next task | Description | Score&nbsp;&nbsp; |`
+     `|---:|---|---|:---:|`
    - Keep descriptions short enough to scan but specific enough to execute.
    - Localize column labels to the report language when appropriate.
 6. Mark gated items plainly.
@@ -116,6 +129,8 @@ scope, approval, verification, command contracts, release gates, or safety rules
      genuinely plausible follow-ups.
    - The description must state the gate, such as explicit user approval, configured command intent,
      owner decision, or manual verification.
+   - A gated item in the table is only a visible next-action option; it is not approval to perform
+     that action.
 7. Interpret a single-digit next user message as a menu selection only when all conditions hold:
    - the immediately relevant previous assistant final report contained a next-action menu;
    - the digit maps to an item in that menu;

package/templates/default/locales/en/.mustflow/skills/quadratic-scan-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.quadratic-scan-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: quadratic-scan-review
@@ -84,33 +84,35 @@ The review question is not "is there a loop inside a loop?" That catches only th
 ## Procedure
 
 1. Name the repeated path and multiply call count by inner scan length. Review the product `outer_count * inner_count`, not the apparent number of loops.
-2. Search for the obvious collection-combinator shapes: `map` plus `filter`, `map` plus `find`, `forEach` plus `includes`, `filter` plus `indexOf`, `reduce` plus spread, and chained `filter().map().sort()` inside a repeated path.
+2. Search for the obvious collection-combinator shapes: `map` plus `filter`, `map` plus `find`, `forEach` plus `includes`, `filter` plus `indexOf`, `filter` plus `findIndex`, `reduce` plus spread, and chained `filter().map().sort()` inside a repeated path.
 3. Search for membership checks over arrays. `includes`, `indexOf`, `contains`, `find`, `some`, and list membership inside a loop usually want `Set.has` or `Map.has` unless the searched list is tiny and hard-capped.
 4. Search for code joins by ID. `posts.map(post => users.find(...))`, `users.map(user => orders.filter(...))`, permission lookups, likes, bookmarks, read state, tags, and relation lists usually need a `Map` or grouped `Map` keyed by ID or composite key.
 5. Check duplicate removal. `filter((x, i) => arr.indexOf(x) === i)` is O(N^2). Prefer `Set` for scalar values and `Map` keyed by stable identity for objects.
 6. Check sorted arrays. Sorting does not make `find` fast. If code repeatedly searches a sorted array, use a prebuilt map, binary search with a proven comparator, or a single sorted merge.
 7. Check repeated sorting. Sorting inside a per-item loop is usually worse than scanning once, keeping a top candidate, using a heap, or sorting once before the loop.
-8. Check copy-accumulation patterns. `reduce` with `[...acc, item]`, repeated object spread over a growing object, repeated string `+=`, and repeated concatenation can become quadratic copy work. Prefer push, builders, buffers, or one final copy at the boundary.
-9. Check JSON and serialization comparisons. Repeated `JSON.stringify` inside search, equality, sort, dedupe, or render logic multiplies object size by item count. Use explicit keys and precomputed normalized keys.
-10. Open helper bodies called from loops or render paths. Harmless helper names can hide full-list scans, database calls, resolver calls, serialization, sorting, or permission checks.
-11. Check ORM and lazy relations. A single visible loop can become one query per entity. Replace per-entity relation access with eager loading, joins, `WHERE id IN (...)`, batch loading, or DataLoader-style batching.
-12. Check GraphQL and nested resolvers. Parent-list resolvers plus per-field DB or API calls create hidden pairwise fan-out. Batch by parent IDs and preserve field-level authorization semantics.
-13. Check render-time lookup. `rows.map(row => columns.find(...))`, `items.map(item => selectedIds.includes(item.id))`, derived data recomputed on every render, and per-row helper scans should move to memoized sets or maps when inputs are large or stable.
-14. Check all-data-in-app joins. Fetching `allUsers`, `allOrders`, or `allLogs` and joining in application arrays is often a database join without an index. Push join, filter, sort, and pagination to the data store when the data store owns the index and semantics allow it.
-15. Check tree and graph construction. `nodes.map(node => nodes.filter(child => child.parentId === node.id))` should usually become `childrenByParentId` plus one assembly pass. `visited.includes(id)` in traversal should be a `Set`.
-16. Check event-log and time-window scans. Repeatedly scanning all previous events per event should usually become grouping, sorting once, and one pointer or rolling aggregate per key.
-17. Check interval overlap. All-pairs range checks are sometimes necessary, but overlap detection often only needs sorting by start and comparing adjacent or active intervals.
-18. Check incremental updates. Adding one item should not recompute a full ranking, group map, unread count, cart total, or dashboard aggregate unless the collection is fixed and tiny.
-19. Separate index from cache. A `Map` built from current input is an index. A cache stores results across calls or time. Use an index for repeated lookup over already-owned data before introducing cache invalidation.
-20. Require a hard cap for "small list" exceptions. Countries, enum options, or fixed config lists may stay arrays if the cap is real. User data, logs, orders, comments, permissions, tags, events, and uploaded rows need scalable lookup.
-21. Preserve behavior while changing shape. Before replacing scans with indexes, state how order, duplicates, first or last match, missing references, authorization filtering, and stable keys are preserved.
-22. Add growth evidence when feasible. If configured tests or fixtures can scale input size, prefer a small growth test that compares behavior at larger counts. If benchmarking is not configured, report complexity-only evidence instead of a speedup claim.
+8. Check queue and deletion patterns. JavaScript `shift()` in a large BFS or queue loop moves the remaining array repeatedly; use a head index or real queue. `findIndex` plus `splice` while matching requests to available items can scan and move the same growing array repeatedly; bucket by key and advance a consumption pointer instead.
+9. Check copy-accumulation patterns. `reduce` with `[...acc, item]`, repeated object spread over a growing object, repeated string `+=`, repeated `concat`, and repeated array spread over a growing result can become quadratic copy work. Prefer push, builders, buffers, or one final copy at the boundary.
+10. Check JSON and serialization comparisons. Repeated `JSON.stringify` inside search, equality, sort, dedupe, or render logic multiplies object size by item count. Use explicit keys and precomputed normalized keys.
+11. Open helper bodies called from loops or render paths. Harmless helper names can hide full-list scans, database calls, resolver calls, serialization, sorting, or permission checks.
+12. Check ORM and lazy relations. A single visible loop can become one query per entity. Replace per-entity relation access with eager loading, joins, `WHERE id IN (...)`, batch loading, or DataLoader-style batching.
+13. Check GraphQL and nested resolvers. Parent-list resolvers plus per-field DB or API calls create hidden pairwise fan-out. Batch by parent IDs and preserve field-level authorization semantics.
+14. Check render-time lookup. `rows.map(row => columns.find(...))`, `items.map(item => selectedIds.includes(item.id))`, derived data recomputed on every render, and per-row helper scans should move to memoized sets or maps when inputs are large or stable.
+15. Check all-data-in-app joins. Fetching `allUsers`, `allOrders`, or `allLogs` and joining in application arrays is often a database join without an index. Push join, filter, sort, and pagination to the data store when the data store owns the index and semantics allow it.
+16. Check tree and graph construction. `nodes.map(node => nodes.filter(child => child.parentId === node.id))` should usually become `childrenByParentId` plus one assembly pass. `visited.includes(id)` in traversal should be a `Set`. Very deep trees may also need an explicit stack to avoid call-stack failure.
+17. Check event-log and time-window scans. Repeatedly scanning all previous events per event should usually become grouping, sorting once, and one pointer or rolling aggregate per key.
+18. Check interval overlap. All-pairs range checks are sometimes necessary, but overlap detection often only needs sorting by start and comparing adjacent or active intervals.
+19. Check true all-pairs similarity separately. If every item must be compared with every other item, do not promise a linear rewrite. First narrow candidates with stable keys, categories, buckets, hashes, n-grams, ranges, or database indexes, then compare only within the candidate set.
+20. Check incremental updates. Adding one item should not recompute a full ranking, group map, unread count, cart total, or dashboard aggregate unless the collection is fixed and tiny.
+21. Separate index from cache. A `Map` built from current input is an index. A cache stores results across calls or time. Use an index for repeated lookup over already-owned data before introducing cache invalidation.
+22. Require a hard cap for "small list" exceptions. Countries, enum options, or fixed config lists may stay arrays if the cap is real. User data, logs, orders, comments, permissions, tags, events, and uploaded rows need scalable lookup.
+23. Preserve behavior while changing shape. Before replacing scans with indexes, state how order, duplicates, first or last match, missing references, authorization filtering, and stable keys are preserved.
+24. Add growth evidence when feasible. If configured tests or fixtures can scale input size, prefer a small growth test that compares behavior at larger counts. If benchmarking is not configured, report complexity-only evidence instead of a speedup claim.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - Each suspected O(N^2) path has an outer count, inner count, and data-growth classification.
-- Repeated membership checks, code joins, duplicate removal, tree building, resolver fan-out, render-time lookup, helper-hidden scans, repeated sort, copy accumulation, and JSON comparison are fixed or reported.
+- Repeated membership checks, code joins, duplicate removal, tree building, resolver fan-out, render-time lookup, helper-hidden scans, repeated sort, queue `shift()`, `findIndex` plus `splice`, copy accumulation, interval scans, all-pairs candidate narrowing, and JSON comparison are fixed or reported.
 - Array-to-set or array-to-map changes preserve order, duplicates, missing records, first or last winner, authorization, and stable key behavior.
 - Small-list exceptions have an explicit hard cap or are reported as residual risk.
 - Performance claims are backed by configured evidence or labeled as static complexity risk.
@@ -146,7 +148,7 @@ Use the narrowest configured test, build, docs, release, or mustflow intent that
 - Repeated path reviewed
 - Outer count, inner count, and data-growth classification
 - Hidden scan patterns found or ruled out
-- Membership, join, dedupe, helper, ORM, resolver, render, tree, graph, event, interval, sort, copy, string, and JSON checks where relevant
+- Membership, join, dedupe, helper, ORM, resolver, render, tree, graph, event, interval, all-pairs, queue, deletion, sort, copy, string, and JSON checks where relevant
 - Index, grouping, sorted merge, database join, or intentional all-pairs decision
 - Semantics preserved: order, duplicates, first or last winner, missing IDs, authorization, and stable keys
 - Evidence level: configured test, static complexity risk, manual-only, missing, or not applicable

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

@@ -0,0 +1,324 @@
+---
+mustflow_doc: skill.react-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: react-code-change
+description: Apply this skill when React, React DOM, React Server Components, Server Actions, React Compiler, Hooks, Suspense, Actions, forms, refs, context, render performance, concurrent rendering, SSR streaming, resource hints, package metadata, or React-related tests are created, changed, reviewed, or upgraded.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.react-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# React Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve React runtime, rendering, state, effect, compiler, server/client,
+form, resource, accessibility, and package-version contracts when changing
+React projects, especially open-source contribution patches where maintainers
+expect current React guidance and small, compatible changes.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- React components, Hooks, context, refs, Suspense boundaries, transitions,
+  deferred values, forms, Actions, optimistic UI, React DOM metadata, resource
+  hints, SSR streaming, React Server Components, Server Actions, or tests change.
+- `react`, `react-dom`, `react-server-dom-*`, `eslint-plugin-react-hooks`,
+  React Compiler, framework adapters, bundlers, JSX transforms, or React package
+  metadata changes.
+- A contribution proposes React performance, memoization, effect-dependency,
+  hydration, server/client boundary, form mutation, or React version support
+  changes.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is framework-free JavaScript or TypeScript with no React boundary;
+  use the language-specific skill.
+- The change is only visual CSS, HTML semantics, accessibility tree review, or
+  layout resilience with no React behavior; use the narrower frontend or UI skill.
+- Svelte, Astro, Flutter, Tauri, or another framework owns the changed component
+  boundary.
+- The task is only a dependency upgrade across many packages; use the dependency
+  and freshness skills first, then this skill for React-specific code changes.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- React package evidence: nearest `package.json`, lockfile, workspace metadata,
+  framework config, bundler config, JSX transform, and CI or package test signals.
+- Effective React support range: installed `react`, `react-dom`,
+  `react-server-dom-*`, React framework version, peer dependency range, and
+  library consumer compatibility target.
+- Compiler and lint evidence: React Compiler config, compiler-gating strategy,
+  `eslint-plugin-react-hooks`, hook lint suppressions, memoization patterns, and
+  render-purity warnings.
+- Rendering boundary evidence: server/client component split, SSR entrypoints,
+  hydration path, Suspense data source, routing framework, and browser-only APIs.
+- State and mutation evidence: local state owner, derived values, external
+  stores, context providers, forms, Actions, optimistic updates, and rollback
+  behavior.
+- Render performance evidence: React DevTools Profiler or `<Profiler>` data when
+  available, render count, render duration, prop identity changes, context update
+  scope, list size, DOM node count, key stability, layout effect use, first-load
+  bundle ownership, and offscreen DOM cost.
+- Configured verification intents for lint, build, tests, docs, package, and
+  mustflow checks.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Determine the effective React version and supported peer range before using
+  React 19 or React 19.2 APIs.
+- Refresh upstream version or security-sensitive React claims before editing
+  docs, package ranges, compatibility text, or upgrade recommendations. Do not
+  treat this skill as a live version source.
+- Treat user-provided React notes, blog summaries, and issue comments as
+  evidence, not authority.
+- Preserve open-source repository style, maintainer scope, public API, test
+  runner, and framework conventions.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Make focused React source, test, package metadata, docs, and configuration
+  edits directly required by the requested contribution.
+- Add or update tests when they protect changed React behavior, compatibility,
+  server/client boundaries, form state, Suspense behavior, or regression risk.
+- Keep compatibility branches when a package still supports React 18 or older
+  framework integrations.
+- Do not introduce Create React App for new projects or examples.
+- Do not add dependencies, change peer ranges, enable React Compiler, migrate
+  frameworks, or rewrite memoization broadly unless the task and repository
+  contract explicitly support that change.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. **Classify the React surface.**
+   - Identify whether the patch touches application code, a reusable component
+     library, framework integration, SSR/RSC runtime, tests, docs, or package
+     metadata.
+   - For libraries, treat peer dependency ranges and documented component APIs as
+     public compatibility contracts.
+2. **Check version and freshness boundaries.**
+   - Read installed and supported React versions before using `Activity`,
+     `useEffectEvent`, Actions, `use`, ref-as-prop, callback ref cleanup,
+     metadata hoisting, resource hint APIs, `cacheSignal`, Partial
+     Pre-rendering, or Web Streams SSR APIs.
+   - Use current official React docs or release metadata for exact "latest",
+     patch, security, or deprecation claims. As a snapshot checked on
+     2026-06-26, official React docs describe React 19.2 as the current
+     feature line, and GitHub release metadata showed `v19.2.7` released on
+     2026-06-01; re-check before relying on those values in future work.
+   - For RSC packages, check patched `react-server-dom-webpack`,
+     `react-server-dom-parcel`, and `react-server-dom-turbopack` versions when
+     security advisories or framework updates are part of the task.
+3. **Keep app setup modern and local.**
+   - Do not propose Create React App for new projects. Follow the repository's
+     existing framework or build tool; for new React app examples, prefer the
+     project's chosen framework or modern build-tool pattern.
+   - Do not migrate an existing stack to Next.js, Vite, Parcel, Rsbuild, or a
+     React framework merely because React documentation recommends frameworks
+     for new apps.
+4. **Repair effects by responsibility.**
+   - Use Effects for synchronization with external systems such as timers,
+     subscriptions, DOM or browser APIs, third-party widgets, network
+     connections, and cleanup.
+   - Do not use Effects to copy props/state into derived state, send event-owned
+     mutations, or paper over rendering data flow.
+   - Do not silence `react-hooks/exhaustive-deps` as a default fix. If effect
+     logic contains non-reactive event behavior and React 19.2 is supported, use
+     `useEffectEvent` for that event-like logic only.
+5. **Preserve state ownership.**
+   - Derive renderable values during render when they are computed from current
+     props or state.
+   - Use updater functions for repeated state updates based on the previous
+     value.
+   - Normalize state that can otherwise contradict itself. Avoid duplicated,
+     deeply nested, or derived state unless the repository has a clear owner.
+   - Use `key` for intentional component state reset, and keep component
+     functions at top level so React does not recreate component types on every
+     render.
+6. **Treat memoization and the compiler as contracts, not decoration.**
+   - Do not blanket-add `memo`, `useMemo`, or `useCallback` to look faster.
+     Require profiler, dependency, identity, or compiler evidence.
+   - Do not blanket-remove existing memoization in legacy code without tests;
+     removal can change identity, effect dependencies, and compiler output.
+   - If React Compiler is enabled or proposed, keep components and Hooks pure,
+     keep compiler-powered `eslint-plugin-react-hooks` findings visible, and
+     report when compiler verification is missing.
+7. **Handle context, refs, and external stores deliberately.**
+   - Split frequently changing context values from stable actions or identities;
+     `memo` does not block re-renders caused by context updates.
+   - Use React 19 ref-as-prop and callback-ref cleanup only when the support
+     range allows it. Preserve `forwardRef` where React 18 compatibility matters.
+   - Expose narrow imperative handles with `useImperativeHandle` instead of
+     leaking whole DOM nodes or child internals.
+   - Use `useSyncExternalStore` for external mutable stores or subscriptions
+     instead of ad hoc Effect plus state mirroring.
+8. **Use concurrent and async primitives for the right boundary.**
+   - Use `startTransition` or `useTransition` for non-urgent updates, but do not
+     control text input values through a transition.
+   - Use `useDeferredValue` when stale-but-responsive derived UI is acceptable;
+     use the `initialValue` form only when the React version supports it.
+   - Do not expect Suspense to catch ordinary Effect fetches. Suspense needs
+     lazy code, framework data, or cached Promise reads.
+   - Treat `use` as render-time Promise or context reading, not a normal Hook
+     with the ordinary top-level-only mental model. Do not create fresh Promises
+     in render and pass them to `use`.
+9. **Use React 19 form and Action APIs only when supported.**
+   - Prefer `useActionState`, `useFormStatus`, `useOptimistic`, `<form action>`,
+     and `formAction` for supported React 19 mutation flows with pending,
+     errors, resets, progressive enhancement, and rollback.
+   - Keep explicit error handling, authorization, validation, idempotency, and
+     rollback behavior. Do not hide server failures behind optimistic UI.
+10. **Review React render hot paths with evidence.**
+    - Use React DevTools Profiler, `<Profiler>`, framework traces, or existing
+      render-count evidence before claiming a render-performance fix. If none is
+      configured, report static render risk instead of measured speedup.
+    - Check whether state is owned too high in the tree. Search inputs, tabs,
+      modal flags, hover state, and local drafts should not rerender a whole page
+      unless that page truly owns the state.
+    - Check `memo` failures from unstable props. Inline objects, arrays, functions,
+      and selector results can make `React.memo` ineffective; prefer primitive
+      props, stable callbacks, or moving object creation behind a real dependency.
+    - Move expensive render-time `filter`, `sort`, `map`, grouping, and lookup work
+      behind `useMemo`, server-side pagination, route loaders, or pre-indexed data
+      when input size can grow.
+    - Large lists need pagination, infinite query boundaries, virtualization, or a
+      documented hard cap. Do not render thousands of rows because the sample data
+      has twenty.
+    - Reject unstable keys such as array index for reorderable data and
+      `Math.random()` for any list. Use stable item identity so React preserves
+      row state and avoids forced remounts.
+    - Split oversized context values by change frequency and ownership. `memo`
+      does not stop rerenders caused by a fresh context value.
+    - Do not use `useEffect` plus `setState` for values derived from current props
+      or state. Compute during render or memoize the calculation to avoid the
+      extra render pass.
+    - For search and filtering, keep the controlled input urgent and move heavy
+      result updates behind `useDeferredValue`, `useTransition`, server filtering,
+      or pagination when the supported React version and UX allow it.
+    - Use `useLayoutEffect` only when pre-paint measurement is required. Avoid
+      DOM read/write interleaving that causes layout thrashing.
+    - Lazy-load heavy charts, editors, maps, markdown renderers, syntax
+      highlighters, and modal-only widgets when they are not needed for the first
+      interaction path.
+    - For large offscreen sections, consider `content-visibility` plus
+      `contain-intrinsic-size`, framework lazy boundaries, or route splitting when
+      browser support and layout stability are acceptable.
+11. **Respect React 19.2 rendering and performance APIs.**
+    - Treat `<Activity>` as hidden UI with preserved state, unmounted effects,
+      and lower-priority hidden updates, not as `display: none` or ordinary
+      conditional rendering.
+    - Use React Performance Tracks, React DevTools, or existing profiler evidence
+      when claiming render, effect, Scheduler, transition, or component
+      performance improvements.
+12. **Keep server rendering and RSC boundaries exact.**
+    - Distinguish Server Components from Server Actions. `"use server"` marks
+      server functions or modules for actions; it is not a Server Component tag.
+    - Keep browser APIs, client state, and event handlers out of Server
+      Components; keep secrets and server-only imports out of Client Components.
+    - Use `cacheSignal` only for RSC cached work where abort or cleanup is
+      meaningful.
+    - For Partial Pre-rendering, `prerender`, `resume`, `resumeAndPrerender`,
+      and streaming APIs, verify the framework/runtime owns those APIs before
+      changing lower-level React DOM server code.
+    - In Node environments, do not assume Web Streams are faster than Node
+      streams; preserve the existing SSR stream API unless the task proves the
+      runtime benefit and compression behavior.
+13. **Use React DOM document and resource APIs close to the owner.**
+    - Metadata, stylesheets with `precedence`, async scripts, `preinit`,
+      `preload`, `preconnect`, and `prefetchDNS` may belong near the component
+      that needs them when React and the framework support that behavior.
+    - Avoid duplicate head managers, resource hint spam, and hints for assets
+      whose timing or priority is unproven.
+14. **Verify through the repository contract.**
+    - Run the smallest configured checks that cover changed React code, package
+      metadata, build output, docs, and tests.
+    - Report missing browser, hydration, SSR, RSC, compiler, profiler, or
+      cross-version React verification when those surfaces changed.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Effective React version, peer range, framework ownership, and compiler/lint
+  status are known or explicitly reported as unknown.
+- Effects, state, memoization, context, refs, forms, Suspense, and async
+  boundaries follow React's current model for the supported version.
+- Render performance claims are backed by profiler or render-count evidence, or
+  static risks such as state too high, unstable props, render-time transforms,
+  huge lists, unstable keys, oversized context, derived-state effects, layout
+  thrashing, eager heavy widgets, and offscreen DOM cost are reported honestly.
+- React 19 and React 19.2 APIs are not introduced into code that still promises
+  older React compatibility.
+- SSR, RSC, Server Action, browser-only, and resource-hint boundaries are
+  preserved.
+- Performance claims have profiler, benchmark, render-count, or configured
+  evidence, or are reported as unverified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Report missing React-version matrix, browser automation, hydration, SSR/RSC,
+Compiler, performance profiling, or package-consumer verification when those
+surfaces changed.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If React version evidence conflicts, do not assume the newest API is
+  available. Preserve the older-compatible path or report the compatibility
+  decision.
+- If an effect dependency fix causes reconnects, stale closures, or event logic
+  churn, separate reactive synchronization from event-like behavior instead of
+  disabling lint.
+- If a compiler or memoization change shifts behavior, restore the previous
+  identity boundary or add focused evidence before continuing.
+- If Suspense, `use`, Actions, or RSC behavior is framework-owned, read the
+  framework boundary before editing raw React assumptions.
+- If freshness checks are unavailable for a React release, security patch, or
+  deprecation claim, avoid embedding exact "latest" wording and report the gap.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- React surface and supported version checked
+- Compiler, lint, effect, state, memoization, context, ref, form, Suspense, SSR,
+  RSC, and resource-boundary notes
+- Render performance notes: profiler evidence, state ownership, prop identity,
+  render-time work, list size, key stability, context scope, derived state,
+  layout effects, lazy loading, and offscreen DOM
+- Freshness-sensitive React claims checked or left conservative
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining React compatibility or verification risk