mustflow 2.39.1 → 2.58.1

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

@@ -0,0 +1,193 @@
+---
+mustflow_doc: skill.frontend-stress-layout-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: frontend-stress-layout-review
+description: Apply this skill when frontend UI is created, changed, reviewed, or reported and layout resilience must be checked against hostile content, narrow parent containers, long strings, async media, skeletons, empty and error states, permission variants, scrollbars, mobile viewport and keyboard behavior, safe areas, line clamps, localization, touch input, motion preferences, observers, portals, z-index layers, tables, charts, browser zoom, cascade layers, or reproducible break conditions.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.frontend-stress-layout-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Frontend Stress Layout Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review frontend layout by testing the screen with the data and environment that real users bring, not the friendly fixture that makes the design look correct.
+
+The core question is: "What exact parent size, content shape, loading order, permission set, device condition, or browser setting breaks this UI?" A good review names a reproducible break condition, then either fixes the layout contract or reports the missing stress fixture.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Frontend UI, design system components, dashboards, forms, cards, lists, tables, charts, modals, drawers, toasts, tab bars, bottom CTAs, media slots, portals, or responsive layouts are created, changed, reviewed, or reported.
+- The UI can receive long names, unbroken IDs, URLs, emails, numbers, translated labels, RTL text, missing data, partial data, async images, delayed fonts, third-party widgets, permission-dependent actions, loading skeletons, errors, or empty state data.
+- The affected surface is embedded inside a parent container whose width, height, overflow, transform, zoom, iframe boundary, or scroll container may differ from the viewport.
+- A review or final report claims the UI is responsive, stable, polished, mobile-safe, table-safe, chart-safe, localized, accessible on touch, or visually verified.
+- A bug report says "the UI breaks", "text overlaps", "card jumps", "button wraps weirdly", "modal is clipped", "table is unusable", "chart disappears", "mobile keyboard covers it", or "only happens in production data".
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only first-render performance, LCP discovery, CLS field metrics, INP, bundle size, or per-frame browser work; use the matching web performance, Core Web Vitals, image delivery, bundle pruning, or frame render performance skill first.
+- The task is only state source-of-truth drift, request races, form draft ownership, or query-key correctness; use `frontend-state-ownership-review`.
+- The task is only semantic HTML, CSS syntax, utility extraction, or framework-specific code shape with no layout-stress risk; use the narrower HTML, CSS, utility, or framework skill.
+- No user-facing UI surface, visual state, embedded component, or rendered artifact is affected.
+- Verification would require an unconfigured dev server, browser, screenshot suite, or design tool. Report the missing visual verification boundary instead of inventing raw commands.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, changed UI surface, current diff or target files, framework and styling system signals, and configured command intents.
+- Stress fixture ledger: shortest, longest, unbroken, translated, RTL, empty, null, partial, permission-limited, error, loading, delayed-media, and delayed-font data cases relevant to the surface.
+- Parent container ledger: viewport sizes, embedded parent widths, grid and flex ancestors, overflow ancestors, scroll containers, transformed parents, iframe or zoom contexts, and container query support or absence.
+- Geometry contract ledger: intrinsic media dimensions, `aspect-ratio`, skeleton geometry, line-height, line clamps, min and max sizes, scrollbars, sticky regions, safe-area offsets, keyboard-open height, and reserved layout space.
+- Interaction and state ledger: hover, focus, active, disabled, pending, loading, touch-only, reduced-motion, permission variants, retry buttons, bulk actions, sticky headers, selection bars, portals, menus, dialogs, and tooltips.
+- Evidence level: static CSS and markup evidence, component fixture evidence, screenshot or browser evidence, design-system story evidence, configured tests, or missing stress evidence.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Existing local patterns for responsive constraints, story fixtures, component tests, design tokens, portals, z-index layers, tables, charts, and empty/error/loading states have been searched before adding a new pattern.
+- If a layout stress issue is caused by state ownership, rendering performance, image delivery, accessibility, security, or data contracts, also apply the narrower matching skill for that boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or refine stress fixtures, stories, tests, or review notes for hostile content, narrow containers, empty/error/loading/permission states, mobile keyboard, safe areas, RTL, zoom, tables, charts, portals, and scrollbars.
+- Add responsive constraints such as `min-width: 0`, `minmax(0, 1fr)`, max sizes, `overflow-wrap: anywhere`, stable table scroll wrappers, reserved media dimensions, `aspect-ratio`, `scrollbar-gutter: stable`, explicit `line-height`, logical properties, and safe-area-aware spacing when they match project patterns.
+- Replace viewport-only assumptions with parent-container-aware layout, container queries, intrinsic constraints, or component-level size contracts when the component can be embedded in multiple shells.
+- Fix skeleton, empty, error, permission, pending, disabled, hover, touch, reduced-motion, portal, z-index, table, or chart states only inside the affected UI surface and directly synchronized docs or tests.
+- Do not redesign the product, change design tokens broadly, rewrite the layout system, add a visual testing framework, start a dev server, or introduce browser automation unless the current repository already authorizes that path.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build the stress fixture ledger first.
+   - Include nice data, empty data, partial data, null-ish data, permission-limited data, API error data, retryable error data, long translated labels, RTL text, long unbroken strings, large numbers, long table headers, single-point charts, all-zero charts, null chart points, and delayed media or font cases when relevant.
+   - If no stress fixture exists, report that absence instead of trusting the default screenshot or happy-path story.
+2. Review parent container width before viewport width.
+   - Components often break inside sidebars, split panes, cards, drawers, CMS slots, iframes, and grid cells even when the viewport is wide.
+   - Prefer component constraints and container queries when the layout depends on parent size rather than global viewport breakpoints.
+3. Check flex and grid shrink contracts.
+   - Flex and grid children that contain text, tables, charts, media, or nested rows usually need `min-width: 0` so they can shrink instead of overflowing.
+   - Grid tracks that should shrink often need `minmax(0, 1fr)` instead of a bare `1fr`.
+4. Attack text with hostile content.
+   - Test long unbroken IDs, URLs, emails, Korean or CJK text, long English words, translated button labels, narrow columns, and large numbers.
+   - Use `overflow-wrap: anywhere`, truncation, wrapping, or explicit min and max sizes according to the component contract.
+5. Reserve async media and widget space.
+   - Images, videos, maps, charts, ads, embeds, custom fonts, and third-party widgets should not resize the page after load.
+   - Use intrinsic `width` and `height`, `aspect-ratio`, stable placeholders, or skeleton geometry that matches final content. Keep CLS-sensitive changes routed to the Core Web Vitals skill when field metrics are part of the claim.
+6. Make skeletons honest.
+   - Skeleton blocks must have approximately the same geometry as final content: line count, media box, button area, card height, table row height, chart frame, and list gaps.
+   - A pretty skeleton that collapses or expands differently is a layout bug wearing makeup.
+7. Put empty and error states inside the real component contract.
+   - Empty states should preserve the parent layout, scroll behavior, minimum height, actions, and alignment expected by the loaded component.
+   - Error states need API fail, permission denied, partial failure, retry pending, and retry failed shapes when those states are possible.
+8. Review permission and action variants.
+   - Different roles can change button counts, hidden actions, disabled actions, bulk bars, admin controls, menus, and CTA placement.
+   - Do not let late `display: none` toggles, conditional blocks, or role-based controls shift the primary content unexpectedly.
+9. Account for scrollbars.
+   - Scrollbar appearance can steal width and wrap text, especially in tables, panels, sidebars, and modals.
+   - Use stable scroll containers or `scrollbar-gutter: stable` when the supported browser target and design allow it.
+10. Reject fragile viewport-height math.
+    - Hard-coded `calc(100vh - 64px)` shells break when headers wrap, banners appear, browser chrome changes, or mobile keyboards open.
+    - Prefer dynamic viewport units, parent flex sizing, measured shell contracts, or safe fallback constraints already used by the project.
+11. Test mobile viewport, keyboard, and safe area.
+    - Mobile `100vh` can include or exclude browser UI depending on platform and moment.
+    - Inputs, bottom CTAs, tab bars, sheets, toasts, and sticky footers must survive keyboard-open screens and `safe-area-inset-*`.
+12. Check line clamps and row height.
+    - Clamped titles, metadata, badges, avatars, and action buttons can fight each other inside cards and rows.
+    - Explicit `line-height` on buttons, chips, badges, tabs, labels, and inputs avoids accidental height drift from fonts or localization.
+13. Review localization and writing direction.
+    - Use logical properties where layout depends on start/end rather than left/right.
+    - Check RTL, translated labels, locale number/date formatting, and wider fallback fonts before claiming the layout is internationalized.
+14. Review interaction variants.
+    - Buttons need icon-only, icon+text, loading, pending, disabled, long-label, two-line, and touch target states where relevant.
+    - Hover-only affordances must also work on touch, keyboard, and reduced-motion contexts, and hover should not resize the card.
+15. Keep motion layout-safe.
+    - Animate `transform` and `opacity` when possible instead of `top`, `left`, `width`, or `height`.
+    - Respect `prefers-reduced-motion` for motion that can distract, disorient, or hide state changes.
+16. Watch observer feedback loops.
+    - `ResizeObserver` callbacks that write size-affecting styles can trigger loops or jitter.
+    - Separate measurement from writes and keep observer scope narrow.
+17. Stress portals and layers.
+    - Menus, comboboxes, popovers, dialogs, sheets, and tooltips must survive viewport edges, scroll containers, transformed parents, overflow hidden ancestors, iframes, browser zoom, and nested portals.
+    - Use named z-index layer tokens instead of one-off `9999` values.
+18. Stress tables.
+    - Test twelve columns, long headers, empty cells, long IDs, negative and large numbers, multiple row actions, horizontal scroll, sticky headers, sticky first columns, selection checkboxes, and bulk action bars.
+    - Preserve keyboard, screen reader, and scroll behavior while preventing layout collapse.
+19. Stress charts.
+    - Test empty data, one point, all zeros, negative values, null points, long labels, huge legends, large y-axis numbers, narrow containers, and width-zero mount moments.
+    - Avoid chart initialization that permanently measures a hidden or zero-width container.
+20. Test browser zoom and cascade reality.
+    - At 125%, 150%, and 200% zoom, fixed-height buttons, clipped labels, and cramped tables expose brittle geometry.
+    - Check CSS specificity and `@layer` ordering so fixes actually win without starting a selector arms race.
+21. Name the reproducible break condition.
+    - A review comment should include the triggering data, parent size, state, role, device condition, zoom, or loading order.
+    - "Looks off" is weak; "In a 320px parent with a 64-character order ID and two permission actions, the row action group overlaps the amount" is actionable.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The affected UI surface has an explicit stress fixture ledger or the missing fixtures are reported.
+- Parent container width, flex and grid shrinking, long content, async media, skeletons, empty and error states, permission variants, scrollbars, viewport height, mobile keyboard, safe areas, line clamps, localization, touch input, reduced motion, observer loops, portals, z-index layers, tables, charts, browser zoom, and cascade ordering are fixed, ruled out, or reported where relevant.
+- Layout-stability claims distinguish static evidence, configured test evidence, screenshot or browser evidence, manual-only evidence, and missing evidence.
+- Any review finding names a reproducible break condition rather than only a subjective visual complaint.
+
+<!-- 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 component, story, visual, unit, build, docs, release, or mustflow intent that covers the changed layout-stress boundary. Use browser screenshots, dev servers, design tools, or visual regression suites only when they are configured one-shot intents or explicitly approved by the user.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the break condition cannot be reproduced from current data, fixtures, or configured evidence, report the missing fixture or measurement boundary before changing unrelated layout code.
+- If a fix only works for the viewport but not the parent container, treat the component contract as unresolved.
+- If reserved space for images, skeletons, charts, or widgets conflicts with content semantics or accessibility, keep the semantic path and report the layout tradeoff.
+- If a configured test or build fails after a layout-stress change, preserve the failing intent and output tail, then use `failure-triage` before broadening the fix.
+- If verification requires new browser automation, a running dev server, or visual regression infrastructure, report the missing command-contract support instead of inventing a workflow.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Frontend stress layout surface reviewed
+- Stress fixture ledger
+- Parent container, shrink, text, media, state, permission, scrollbar, mobile viewport, keyboard, safe area, localization, touch, motion, observer, portal, z-index, table, chart, zoom, and cascade checks where relevant
+- Reproducible break conditions found, fixed, or ruled out
+- Layout changes or recommendations
+- Evidence level: configured-test, screenshot or browser evidence, static layout-risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped visual checks and reasons
+- Remaining frontend stress-layout risk

package/templates/default/locales/en/.mustflow/skills/hot-path-performance-review/SKILL.md

@@ -0,0 +1,159 @@
+---
+mustflow_doc: skill.hot-path-performance-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: hot-path-performance-review
+description: Apply this skill when code is created, changed, reviewed, or reported and the main performance risk is ordinary work repeated many times, such as repeated I/O, repeated scans, hidden quadratic lookup, per-item allocation, lock hold time, sequential async waits, unbounded fan-out, or missing observability for hot paths.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.hot-path-performance-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Hot Path Performance Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Catch performance bottlenecks caused by small ordinary operations running many times, waiting on slow boundaries, copying too much data, or holding shared resources too long.
+
+The review question is not only "which line looks slow?" It is "how often does this run, what does each run allocate or fetch, does it cross an external boundary, and does it block a shared resource while waiting?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code is created, changed, reviewed, or reported and the likely risk is repeated work, data-size growth, external round trips, lock or pool wait, allocation churn, serialization cost, cache behavior, queue throughput, retries, timeouts, or missing hot-path instrumentation.
+- A loop, mapper, reducer, stream, LINQ pipeline, iterator chain, ORM access, request handler, worker, queue consumer, renderer, export, report, import, sync, or batch job processes many items.
+- Code calls a database, ORM relation, Redis, filesystem, HTTP API, RPC, object storage, child process, provider SDK, logger, metrics sink, parser, formatter, serializer, compressor, cryptographic function, image processor, or lock from a repeated path.
+- A review or final report claims that a path is fast enough, scalable, bounded, batched, cached, parallel, safe under p95 or p99 load, or not worth optimizing.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is a full performance optimization, benchmark design, latency budget, profiling, bundle-budget, media-delivery, or p95/p99 measurement project; use `performance-budget-check` as the main route.
+- The task only changes cleanup, cancellation, retained references, native handles, or resource lifetime without throughput or latency risk; use `memory-lifetime-review`.
+- The task only changes database schema or query correctness with no hot-path or repeated-access concern; use the matching database skill.
+- The only concern is vague "make it faster" wording without code paths, input scale, repeated execution, external boundaries, or measurement evidence to inspect.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Hot path: the request, loop, render, job, export, import, queue consumer, sync, report, or command path under review.
+- Multipliers: requests, rows, items, files, users, tenants, retries, pages, renders, workers, queue messages, shards, or nested loops that multiply the work.
+- Per-iteration cost: external calls, queries, filesystem reads, allocations, clones, DTO conversions, JSON parse/stringify, logging, formatting, regex, sorting, hashing, image or crypto work, and lock hold time.
+- Boundary ledger: DB, network, cache, filesystem, IPC, provider SDK, queue, logger, metrics sink, transaction, pool, mutex, thread, goroutine, task, or UI main thread crossed by the path.
+- Data-size and tail-latency evidence when available: p50, p95, p99, row count, payload size, allocation count, query count, round-trip count, queue depth, pool wait, lock wait, cache hit rate, retry count, or timeout behavior.
+- Correctness boundaries: order, duplicates, idempotency, authorization, tenant isolation, consistency, partial failure, stale data, cancellation, retry semantics, and error behavior.
+- Relevant command-intent contract entries for build, tests, docs, release checks, and mustflow validation.
+
+<!-- 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.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- If a real optimization, measurement plan, benchmark, profiling change, latency budget, or performance claim is being implemented, also use `performance-budget-check`.
+- If cache, queue, retry, timeout, health, worker, external call, or operational behavior changes, also use `backend-reliability-change`.
+- If database query shape, index fit, transaction scope, pagination, or migration behavior changes, also use the matching database skill.
+- If personal data, authorization variance, tenant keys, logs, or telemetry are part of the performance path, also use `security-privacy-review`.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten batching, projection, lookup tables, bounded concurrency, timeout or cancellation wiring, bulk writes, cache-key boundaries, queue backpressure, transaction or lock narrowing, and focused hot-path tests tied to the task.
+- Add lightweight observability for query count, external-call count, payload size, cache hit rate, queue depth, retry count, pool wait, lock wait, or function timing when repository evidence supports it.
+- Replace repeated scans, per-item clients, unbounded materialization, per-item logging, or repeated parsing with existing project patterns.
+- Do not add speculative caches, broad rewrites, unbounded parallelism, new infrastructure, or benchmark-only code without evidence for the hot path and invalidation boundary.
+- Do not trade correctness, authorization, privacy, ordering, durability, partial-failure behavior, or user trust for speed without explicit product acceptance.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Count the path before judging it. State how many times the code can run after multiplying by requests, rows, items, retries, renders, jobs, pages, tenants, and nested loops.
+2. Build a cost ledger with five columns: iteration count, data size, round-trip count, wait time, and copy or allocation count.
+3. Check repeated external access first.
+   - A loop around DB, ORM, Redis, HTTP, RPC, filesystem, object storage, IPC, provider SDK, logging sink, or child process is the first suspect.
+   - ORM relation access can be a query even when it looks like a property read; treat lazy loading as guilty until query count evidence says otherwise.
+4. Check multi-pass collection code. `map`, `filter`, `reduce`, `forEach`, LINQ, streams, iterator chains, and comprehensions can traverse data several times. Count passes and intermediate arrays before admiring the one-liner.
+5. Check hidden quadratic lookup. A loop containing `includes`, `contains`, `find`, `indexOf`, `some`, `filter`, list membership, row-wise DataFrame work, or another linear scan is often `O(n^2)`. Prefer `Set`, `Map`, lookup tables, sorted merge, or database-side join when semantics match.
+6. Preserve semantics when changing data structures. State order, duplicates, first or last winner, missing IDs, stable sort, tie-breakers, and authorization visibility before replacing arrays with maps or sets.
+7. Check database shape.
+   - Avoid unbounded `SELECT *`, full entity hydration, large JSON/TEXT/BLOB columns, `findAll`, row-by-row saves, and per-item relation access.
+   - Check whether predicates can use indexes. Functions around indexed columns, leading wildcard search, unselective filters, implicit casts, and mismatched sort order often defeat indexes.
+   - Treat large `OFFSET ... LIMIT ...` pages as linearly expensive unless the product truly needs arbitrary jumps. Prefer stable keyset or cursor pagination when possible.
+8. Check transaction and lock hold time. Do not hold DB transactions, mutexes, synchronized blocks, distributed locks, or global locks across network calls, file uploads, JSON conversion, logs, long computation, or user-controlled waits.
+9. Check async shape. Sequential `await` in a loop is still serial work. Independent I/O usually needs bounded concurrency, while `Promise.all` over thousands of items, unbounded goroutines, unbounded futures, or thread-pool bypasses can melt the shared resource.
+10. Reuse expensive clients and sessions. Per-request or per-item HTTP clients, DB clients, ORM clients, SDK clients, connection pools, TLS handshakes, regexes, date formatters, and thread pools are performance traps unless the API requires that lifecycle.
+11. Check cache honesty. A cache needs a bounded key space, invalidation or TTL, max size, authorization dimensions, negative-cache policy, stale behavior, and cache stampede protection such as locking, singleflight, early refresh, or request coalescing.
+12. Check logging and telemetry in hot paths. Repeated debug logs, eager log-string creation, whole-object serialization, high-cardinality metrics, and JSON formatting for discarded logs can dominate CPU and I/O during incidents.
+13. Check string, JSON, DTO, and clone churn. Repeated string concatenation, `JSON.parse(JSON.stringify(...))`, `cloneDeep`, broad object spread, deep copy, repeated DTO-to-DTO conversion, and repeated serialization can move the bottleneck into "clean" mapping code.
+14. Check large value passing and materialization. In value-copy languages or APIs, large structs, arrays, buffers, spread copies, full file reads, full JSON loads, and eager `collect` calls can turn neat code into memory traffic.
+15. Check regex, parsing, formatting, and locale work. Nested or ambiguous regexes, repeated date parsing, timezone conversion, numeric or locale formatting, and per-row formatter creation should be reviewed with worst-case input in mind.
+16. Check CPU-heavy work in request or UI paths. Image resizing, compression, encryption, hashing, diffing, report generation, spreadsheet export, and search indexing may need batching, worker offload, queueing, or streaming, but only with clear backpressure and failure behavior.
+17. Check queues and workers. Moving work to a queue only moves the bottleneck unless consumers batch DB writes, bulk external calls where safe, bound retries, apply jitter, define poison-message handling, and expose backlog.
+18. Check retry and timeout multiplication. A request with several calls, long timeouts, and several retries can become a tail-latency monster. Count worst-case wait and verify idempotency before adding more attempts.
+19. Review tail behavior, not just average. p50 can look fine while p95 or p99 holds locks, connections, workers, or thread-pool slots long enough to hurt everyone else.
+20. Add observability before large optimization when evidence is missing. Prefer query count, external-call count, payload bytes, allocation count, cache hit rate, queue backlog, pool wait, lock wait, retry count, and span timing over guessing.
+21. Rank the likely payoff. Usually fix repeated external round trips, N+1 access, hidden quadratic scans, overfetching, wide transactions, lock hold time, unbounded fan-out, and missing timeouts before micro-optimizing arithmetic.
+22. Label evidence honestly. If there is no configured benchmark or production trace, report the finding as static complexity or hot-path risk, not measured speedup.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Hot path, cost multipliers, data size, round-trip count, wait points, and copy or allocation points are explicit.
+- N+1 queries, repeated external calls, hidden quadratic scans, unbounded materialization, sequential waits, unbounded fan-out, per-item client creation, broad logging, repeated serialization, and lock or transaction hold time are fixed or reported.
+- Cache, queue, retry, timeout, batching, bulk-write, concurrency, pagination, projection, index-fit, and observability behavior are explicit where relevant.
+- Correctness, authorization, tenant isolation, ordering, duplicates, partial failure, cancellation, and stale-data behavior remain intact or are called out as tradeoffs.
+- Performance claims are backed by configured evidence or labeled as static review risk.
+
+<!-- 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 test, build, docs, release, or mustflow intent that covers the changed hot path. Do not infer raw benchmark, profiler, database, server, browser, load-test, or package-manager commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a configured test or build fails, preserve the failing intent and output tail, then fix only the behavior or contract exercised by the failure.
+- If the hot path, multiplier, or data-size boundary is unknown, report the missing evidence instead of adding caches, workers, or concurrency complexity.
+- If optimization conflicts with correctness, authorization, privacy, durability, or ordering, keep correctness and report the tradeoff.
+- If measurement requires unconfigured benchmark, profiler, production trace, database, browser, load-test, or server access, report it as manual evidence instead of running raw commands.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Hot path reviewed
+- Cost ledger: iteration count, data size, round trips, wait time, copy or allocation count
+- Repeated external access, N+1, hidden quadratic scans, and multi-pass collection findings
+- DB, pagination, index-fit, transaction, lock, async, client reuse, cache, queue, retry, timeout, logging, serialization, clone, regex, parsing, formatting, and CPU-heavy work checked where relevant
+- Optimization or review recommendation
+- Evidence level: measured, configured-test evidence, static complexity risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped measurements and reasons
+- Remaining hot-path performance risk

package/templates/default/locales/en/.mustflow/skills/idempotency-integrity-review/SKILL.md

@@ -0,0 +1,195 @@
+---
+mustflow_doc: skill.idempotency-integrity-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: idempotency-integrity-review
+description: Apply this skill when code is created, changed, reviewed, or reported and repeated requests, retries, webhooks, queue redelivery, schedulers, batch replays, double clicks, external callbacks, timeout recovery, or duplicate business commands could make the same logical operation move money, inventory, credits, coupons, notifications, shipments, state transitions, durable records, or external side effects more than once.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.idempotency-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Idempotency Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review idempotency as duplicate intent integrity, not as an HTTP method checklist.
+
+The review question is not "is this POST protected?" It is "if the same business intent is delivered twice, late, concurrently, after a timeout, or after the caller missed the first response, what internal state or external side effect moves twice?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code creates, changes, reviews, or reports POST, PATCH, DELETE, webhook, callback, queue consumer, scheduler, batch, retry, timeout recovery, mobile app retry, browser refresh, double-click, provider callback, external API call, or background job behavior.
+- The operation can charge, capture, refund, withdraw, grant points, deduct credits, deduct stock, issue coupons, send email, create shipments, grant entitlements, change status, publish events, acknowledge messages, or call providers.
+- Idempotency keys, event IDs, message IDs, request IDs, operation IDs, provider object IDs, inbox or outbox records, dedupe tables, processing states, retry libraries, locks, or duplicate request responses are introduced, changed, reviewed, or claimed safe.
+- A review or final report claims an operation is idempotent, retry-safe, duplicate-safe, exactly-once, safe to replay, safe to reprocess, safe after timeout, protected by frontend disabling, protected by Redis, protected by a lock, or protected by provider idempotency.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is primarily payment-provider, checkout, refund, subscription, settlement, chargeback, or fulfillment integrity; use `payment-integrity-review` first and this skill only for generic duplicate-intent details not covered there.
+- The task is primarily credit, point, wallet, balance, stored-value, ledger, expiry, or reservation integrity; use `credit-ledger-integrity-review` first and this skill only for generic duplicate-intent details not covered there.
+- The task is primarily read -> decision -> write atomicity, isolation, locks, rollback, transaction propagation, or after-commit ordering; use `transaction-boundary-integrity-review` first and this skill as the duplicate-delivery adjunct.
+- The task is primarily stale shared state, lock scope, or generic interleaving with no duplicate logical operation or retry surface; use `race-condition-review` or `concurrency-invariant-review`.
+- The task is primarily swallowed failures, false success, timeout honesty, queue ack/nack honesty, fallback defaults, or public error contracts; use `failure-integrity-review`.
+- The operation is a pure read with no hidden write, usage charge, read receipt, analytics commitment, cache mutation that matters, external call, or durable side effect.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Operation identity ledger: logical operation, actor, tenant, target resource, business operation type, request body hash, idempotency key, event ID, message ID, provider object ID, batch key, scheduler run key, and retry source.
+- Side-effect ledger: every charge, refund, balance change, stock change, coupon issue, shipment, email, notification, entitlement, status transition, file write, queue publish, cache change, provider call, and audit entry.
+- Durable dedupe evidence: unique constraints, idempotency table, inbox table, outbox table, applied event table, ledger source key, conditional update, state guard, provider idempotency key, and response record.
+- Duplicate response policy: cached success response, duplicate conflict response, in-progress response, payload mismatch response, failed validation response, unknown outcome recovery, and caller-visible retry contract.
+- Concurrency and recovery evidence: simultaneous duplicate requests, process restart, TTL expiry, `PROCESSING` stuck state, lease, heartbeat, retry budget, timeout classification, provider lookup, reconciliation, and lock fallback.
+- Queue, webhook, scheduler, and batch evidence: ack timing, redelivery semantics, event ordering, signature checks, event storage, per-aggregate ordering, reprocessing rules, and run-level uniqueness.
+- Test evidence: duplicate request tests, concurrent duplicate tests, timeout-then-retry tests, external-success-internal-failure tests, DB-success-response-failure tests, duplicate webhook tests, stale event tests, ack-failure tests, and configured command intents.
+
+<!-- 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.
+- Required inputs are available, or missing operation identity, durable dedupe, response replay, timeout recovery, queue, webhook, scheduler, batch, or test evidence can be reported without guessing.
+- Existing local patterns for idempotency keys, operation IDs, inbox, outbox, provider keys, ledgers, locks, retries, processing leases, duplicate responses, and reconciliation have been searched before adding new shapes.
+- If the duplicate operation affects money, credits, permissions, personal data, inventory, orders, external providers, or durable events, also apply the relevant payment, credit, security, transaction, state-machine, cache, or failure skill.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or tighten durable idempotency records, request body hash comparison, user and tenant binding, operation-type binding, target-resource binding, unique constraints, atomic insert-or-return behavior, state guards, affected-row checks, inbox records, outbox records, applied-event ledgers, provider result lookup, response replay, processing lease recovery, and focused duplicate tests.
+- Move external side effects behind durable operation records or outbox records when local style supports it.
+- Make retry classification explicit for validation failure, transient failure, timeout with unknown outcome, provider success with local failure, local success with missing response, duplicate in progress, and duplicate completed.
+- Do not treat frontend button disabling, debounce, in-memory flags, Redis TTL alone, provider idempotency alone, or distributed locks alone as final proof of idempotency.
+- Do not make duplicate protection by returning a different success shape unless the caller contract can safely reconcile it.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the logical operation, not only the endpoint.
+   - POST, PATCH, DELETE, webhook, queue consumer, scheduler, batch replay, retry wrapper, and callback handlers can all carry the same duplicate-intent risk.
+   - Ask what "same intent" means in business terms: same order payment attempt, same refund, same point grant, same coupon redemption, same shipment, same notification, same state transition, same imported row, or same provider event.
+2. Start at the side effect.
+   - Find calls and writes named like `charge`, `capture`, `refund`, `withdraw`, `grantPoint`, `deductStock`, `issueCoupon`, `sendEmail`, `createShipment`, `publish`, `ack`, `markPaid`, `fulfill`, and local equivalents.
+   - For each side effect, ask what happens if the exact surrounding handler runs twice, runs concurrently, or runs after the first response is lost.
+3. Review idempotency key scope.
+   - A key is not enough unless it is bound to actor, tenant, operation type, target resource, and request body hash or equivalent semantic fingerprint.
+   - Duplicate key plus changed amount, resource, user, tenant, product, operation, or payload should become a stable mismatch response, not a new operation or silent old response.
+   - Do not accept memory-only stores, process-local maps, or Redis TTL alone for operations that can be retried after restart, failover, delayed callback, or TTL expiry.
+4. Require durable uniqueness at the operation boundary.
+   - App-only `if exists return` followed by `insert` is a race. Use a unique constraint, atomic insert, upsert, conditional write, or durable ledger key.
+   - Review migrations or schema definitions, not just service code, for keys such as `order_id`, `payment_id`, `refund_id`, `event_id`, `message_id`, `idempotency_key`, `campaign_id + user_id`, and `settlement_date + merchant_id`.
+5. Check response replay.
+   - Idempotency is often needed because the caller did not receive the first response.
+   - A duplicate completed request should usually return the original response or an equivalent stable result the caller can reconcile.
+   - A duplicate in-progress request should have an explicit wait, poll, retry-later, or conflict response contract.
+6. Classify failed attempts.
+   - Validation failures, authorization failures, duplicate-key payload mismatches, technical failures before side effects, unknown outcomes after side effects, and durable completed failures need different caching and retry rules.
+   - Caching every failure can block recovery. Re-executing every failure can duplicate side effects.
+7. Treat timeouts as unknown outcomes.
+   - A timeout after submitting a provider request is not proof of failure.
+   - Before retrying charge, refund, shipment, SMS, email, entitlement, or external creation calls, look up provider state by operation key, provider object ID, or idempotency key, then continue from the known result.
+8. Check external API ordering.
+   - External API call before durable local operation record creates duplicate risk when the local process times out or crashes before saving success.
+   - Provider idempotency can protect the provider call while internal follow-up work still duplicates. Internal idempotency remains required.
+9. Review state transitions as conditional operations.
+   - `UPDATE ... SET status = PAID WHERE id = ?` is weaker than `WHERE id = ? AND status = PENDING` or an equivalent state-machine guard.
+   - Late duplicate events should not overwrite terminal, newer, or higher-order states without version, event time, sequence, or transition-order checks.
+10. Review increments and ledger entries.
+    - `+=`, balance increases, point grants, stock deductions, usage counters, retry counters, and mutable totals duplicate naturally.
+    - Require an applied-event table, source ledger key, unique entry identity, conditional update, or state transition that records the event already moved the number.
+11. Review deletion and "read" endpoints for hidden side effects.
+    - DELETE may be final-state idempotent while refund, notification, inventory restoration, audit, or permission side effects still duplicate.
+    - GET endpoints that mark read, accept invites, decrement quota, create download usage, or mutate analytics are not harmless reads under crawler, preview, refresh, or retry behavior.
+12. Review queues and consumers as at-least-once by default.
+    - Consumer code should assume duplicate messages, delayed redelivery, concurrent workers, ack failure after commit, and process death after side effects.
+    - Store message ID, event ID, business key, or source ledger key in an inbox or applied-event table before applying irreversible effects.
+13. Review ack timing.
+    - Ack before durable commit can lose work.
+    - Ack after durable commit can redeliver work.
+    - Prefer accepting redelivery and making the handler idempotent, with dead-letter and retry evidence for poison messages.
+14. Review webhook handlers as replay surfaces.
+    - External providers resend callbacks when they miss acceptable responses.
+    - Store event IDs or provider object/type pairs, verify signatures, bind the event to the expected business object, and guard state transitions against duplicates and stale event order.
+15. Review schedulers and batches.
+    - Jobs are rerun after deploys, crashes, partial failures, and manual operator actions.
+    - Use business keys such as `settlement_date + merchant_id`, `campaign_id + user_id`, import file row identity, period key, or run source ID instead of loose "already processed yesterday" checks.
+16. Review outbox and inbox pairing.
+    - DB change plus message publish can split when either side succeeds alone.
+    - Use an outbox for durable outgoing effects and an inbox or applied-event record for incoming duplicate delivery when the workflow crosses process boundaries.
+17. Review saga compensation.
+    - Compensation actions such as cancel, refund, release stock, revoke entitlement, or restore credits also need idempotency keys tied to the original action.
+    - Double compensation can be worse than the original failure.
+18. Review `PROCESSING` and lease recovery.
+    - A `PROCESSING` row without lease, heartbeat, timeout, owner, or reconciliation can permanently block retries after a crash.
+    - A stale processing record should recover by verifying side effects and either completing, failing safely, or allowing one fenced owner to continue.
+19. Review locks as helpers, not proof.
+    - Distributed locks can expire, split ownership, or pause through stop-the-world events.
+    - Keep durable uniqueness, conditional writes, state guards, idempotency records, or fencing tokens as the final defense.
+20. Check grep bait near the operation.
+    - Review code around `Idempotency-Key`, `request_id`, `event_id`, `message_id`, `operation_id`, `dedupe`, `inbox`, `outbox`, `retry`, `timeout`, `Promise.all`, `ack`, `nack`, `visibility timeout`, `webhook`, `scheduler`, `batch`, `cron`, `PROCESSING`, `SUCCEEDED`, `FAILED`, `lock`, `Redis`, `send`, `publish`, `charge`, `refund`, `grant`, `deduct`, `createShipment`, and `cache`.
+    - These terms are anchors, not automatic bugs.
+21. Require duplicate-path evidence.
+    - Good tests include same request twice, concurrent duplicate requests, first response lost, external success followed by DB failure, DB success followed by response failure, webhook replay, stale event replay, consumer commit followed by ack failure, batch rerun, processing-stuck recovery, and duplicate key with changed payload.
+    - If deterministic proof is not configured, report static risk and missing manual or integration evidence instead of approving the path.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The logical operation, duplicate sources, side effects, durable operation key, payload binding, response replay contract, timeout recovery, processing recovery, queue or webhook dedupe, scheduler or batch dedupe, outbox or inbox boundary, and duplicate-path tests are explicit.
+- Duplicate business requests, changed-payload key reuse, concurrent `exists` then `insert`, duplicate increments, stale state overwrites, provider timeout retries, pre-record external calls, duplicate webhook delivery, queue redelivery, scheduler reruns, double compensation, stuck processing rows, weak locks, and frontend-only guards are fixed or reported.
+- Duplicate safety claims are backed by configured tests, schema evidence, framework evidence, provider documentation matched to current code, or labeled as static review risk.
+
+<!-- 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`
+
+Prefer the narrowest configured test, build, docs, release, or mustflow intent that covers the changed idempotency boundary and synchronized template surfaces. Do not infer raw load tests, live provider calls, queue servers, database shells, webhook tunnels, schedulers, watchers, or manual replay commands outside the command contract.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a configured command fails, preserve the failing intent, failing assertion or output tail, and the duplicate-intent invariant it exercised before editing again.
+- If the logical operation identity cannot be named, report that the path is not reviewable for idempotency yet.
+- If duplicate prevention depends only on frontend disabling, in-memory flags, cache TTL, provider idempotency, distributed locks, or app-only checks, report the missing durable idempotency gate.
+- If a safe fix requires a schema migration, durable idempotency store, inbox, outbox, reconciliation worker, provider lookup, saga state, or integration replay harness outside the current scope, report the missing durable boundary.
+- If deterministic duplicate proof is not configured, report the missing manual evidence and complete the configured checks that are available.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Idempotency boundary reviewed
+- Logical operation, duplicate sources, operation identity, side effects, durable dedupe, payload binding, response replay, failure caching, timeout recovery, external provider, state-transition, increment or ledger, DELETE or hidden-read side-effect, queue, webhook, scheduler or batch, outbox/inbox, compensation, processing lease, lock, and test evidence findings
+- Idempotency fixes made or recommended
+- Evidence level: configured-test evidence, schema evidence, provider or framework evidence, static review risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped idempotency diagnostics and reasons
+- Remaining idempotency-integrity risk