mustflow 2.39.1 → 2.58.0

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

@@ -0,0 +1,155 @@
+---
+mustflow_doc: skill.quadratic-scan-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: quadratic-scan-review
+description: Apply this skill when code is created, changed, reviewed, or reported and the specific risk is hidden O(N^2) or pairwise work caused by repeated scans, membership checks, code joins, resolver fan-out, render-time lookup, repeated sorting, copying, string building, or helper functions that rescan growing collections.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.quadratic-scan-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Quadratic Scan Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Find hidden O(N^2) work by tracing when one growing collection repeatedly scans, searches, sorts, copies, serializes, or fetches against another growing collection.
+
+The review question is not "is there a loop inside a loop?" That catches only the obvious case. The stronger question is "does this path look at the same growing data from the beginning again for each item?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code is created, changed, reviewed, or reported and the risk is repeated `map`, `filter`, `find`, `some`, `includes`, `indexOf`, membership checks, list joins, group building, tree building, graph traversal, duplicate removal, overlap checks, sorting, cloning, string building, JSON comparison, ORM lazy loading, GraphQL resolver loading, or render-time lookup.
+- A list, table, tree, graph, event log, permission list, tag list, relation list, selected item list, likes/bookmarks/read state, orders, comments, posts, users, rows, files, or queue messages can grow without a small hard cap.
+- A helper called inside a loop or render path has a harmless name such as `isValid`, `getStatus`, `hasPermission`, `getCount`, `findOwner`, `renderRow`, or `resolveField` but may scan a full collection internally.
+- A review or final report claims that an O(N^2)-looking path is fine because the current fixture is small, the code is functional, the list is sorted, the helper is simple, or the data is "only a few items."
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is broader performance triage across I/O, locks, queues, retries, payloads, clients, caches, and observability; use `hot-path-performance-review`.
+- The task is a measured performance budget, benchmark, profiling, latency, throughput, or p95/p99 optimization project; use `performance-budget-check`.
+- The task only changes resource cleanup, retained references, or memory lifetime without repeated-scan complexity; use `memory-lifetime-review`.
+- The only concern is a fixed-size lookup over a small, documented, hard-capped configuration list where the cap is enforced or clearly external to user data.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Outer work: the loop, mapper, reducer, render, resolver, batch, import, export, queue consumer, tree builder, graph traversal, or helper call site that repeats.
+- Inner work: the scan, membership check, lookup, sort, clone, string copy, JSON serialization, DB query, resolver call, or helper body run for each item.
+- Data shape: which collections grow, whether they are user-generated or fixed configuration, maximum known size, duplicate behavior, order requirements, and key fields.
+- Join or membership key: ID, composite key, normalized key, parent ID, foreign key, timestamp bucket, interval boundary, permission key, tag key, or object identity.
+- Current semantic contract: order, duplicates, first or last winner, stable tie-breakers, missing records, authorization filtering, stale data, and partial failure.
+- Evidence level: static review, fixture size, configured test, benchmark, profiler, query count, resolver count, render count, or missing measurement.
+- 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 the fix changes database query shape, indexes, pagination, or transaction behavior, also use the matching database skill.
+- If the pattern appears in UI rendering or derived state, also use the matching UI or framework skill when UI behavior changes.
+- If resolver, queue, cache, or backend operational behavior changes, also use `backend-reliability-change`.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Replace repeated scans with `Set`, `Map`, lookup tables, grouping maps, parent-to-children maps, composite keys, sorted merge, single-pass aggregation, or database-side joins when semantics match.
+- Move repeated lookup preparation out of loops, render functions, resolvers, and per-item helpers into a bounded pre-indexing step.
+- Add small tests or fixtures that preserve order, duplicate handling, first or last winner behavior, missing IDs, and composite-key behavior when changing lookup structure.
+- Add bounded static-review notes or complexity comments only when the code would otherwise look misleading.
+- Do not add caches when an index built from already-loaded data is enough.
+- Do not replace arrays with maps or sets when duplicates, order, stable tie-breakers, or small hard-capped lists make the array behavior intentional.
+
+<!-- mustflow-section: procedure -->
+## 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.
+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.
+
+<!-- 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.
+- 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.
+
+<!-- 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 data shape. Do not infer raw benchmark, profiler, database, 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 the behavior contract that changed with the lookup structure.
+- If duplicate or order semantics are unknown, do not replace a scan with a map or set until the missing semantic decision is reported.
+- If an all-pairs comparison is actually required by the domain, report why the O(N^2) shape is intentional and whether input size is bounded.
+- If measurement requires unconfigured benchmark, profiler, production trace, database, browser, or load-test access, report it as manual evidence instead of running raw commands.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- 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
+- 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
+- Command intents run
+- Skipped measurements and reasons
+- Remaining quadratic-scan risk

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

@@ -0,0 +1,193 @@
+---
+mustflow_doc: skill.queue-processing-integrity-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: queue-processing-integrity-review
+description: Apply this skill when code is created, changed, reviewed, or reported and queue, stream, pub/sub, broker, worker, task, job, consumer, producer, webhook handoff, DLQ, retry, redelivery, visibility timeout, offset commit, message ack, nack, reject, delete, publisher confirm, prefetch, rebalance, FIFO group, deduplication, or worker-loss behavior can lose work, duplicate work, hide poison messages, reorder state, exhaust consumers, or falsely claim processing success.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.queue-processing-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Queue Processing Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review queue processing by starting at the success boundary, not at dashboard lag or the top of the handler.
+
+The core question is not "is the worker running?" It is "when does this code declare the message finished, and what state or side effect can still be missing, duplicated, reordered, or invisible after that declaration?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code creates, changes, reviews, or reports queue consumers, producers, stream processors, task workers, pub/sub handlers, delayed jobs, schedulers, webhooks handed to queues, DLQ replayers, retry workers, or batch consumers.
+- Code calls or configures message acknowledgement, negative acknowledgement, reject, delete, visibility timeout, offset commit, publisher confirm, prefetch, concurrency, rebalance listeners, FIFO message groups, deduplication IDs, task acknowledgements, worker-loss behavior, dead-letter routing, or poison-message handling.
+- Kafka, RabbitMQ, SQS, Celery, BullMQ, Sidekiq, Redis streams, Pub/Sub, NATS, Kinesis, Azure queues, or local equivalents appear in the changed path.
+- A review or final report claims queue work is processed, durable, at-least-once, exactly-once, idempotent, retry-safe, backpressured, ordered, dead-lettered, observable, or safe after worker crash.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is primarily duplicate business intent across HTTP retries, webhooks, schedulers, or batch replays; use `idempotency-integrity-review` first and this skill for queue-specific delivery boundaries.
+- The task is primarily swallowed exceptions, false success, unsafe fallback, timeout honesty, cancellation, or public error shape; use `failure-integrity-review` first and this skill for message settlement behavior.
+- The task is primarily transaction isolation, rollback, outbox, after-commit, or read-decision-write atomicity; use `transaction-boundary-integrity-review` first and this skill for broker settlement.
+- The task is primarily database query speed, cache correctness, API latency, or generic hot-path performance with no broker, worker, or redelivery surface.
+- The queue path is read-only telemetry where dropped or duplicate messages are explicitly acceptable and no state, audit, billing, permission, notification, or external side effect depends on it.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Broker and delivery model: queue or stream type, at-least-once or at-most-once assumptions, message identity, partition or group key, ordering requirement, redelivery behavior, and retention or visibility rules.
+- Success boundary: exact ack, delete, commit, confirm, mark-complete, task-ack, batch-commit, or checkpoint call and every fallible operation before and after it.
+- Producer boundary: enqueue, publish, send, transaction commit, outbox write, publisher confirm, broker response, retry behavior, and what happens when DB commit and publish split.
+- Consumer state ledger: DB writes, external calls, emails, payments, inventory, cache writes, file writes, queue publishes, metrics, logs, audit entries, idempotency records, inbox records, and outbox records.
+- Failure and retry policy: transient versus permanent failure, poison message classification, retry budget, backoff, jitter, DLQ threshold, requeue behavior, visibility extension, stuck in-flight recovery, and manual replay policy.
+- Concurrency and ordering evidence: consumer parallelism, batch size, prefetch, thread pool, async handler ownership, per-key ordering, FIFO group cardinality, rebalance behavior, partition revoke handling, and in-progress commit fences.
+- Observability evidence: message id, correlation id, attempt, age or queue delay, processing time, ack or commit decision, retry-after, DLQ reason, poison classification, worker-loss signal, and reconciliation signal.
+- Test evidence: ack-before-work tests, work-before-ack crash tests, duplicate redelivery tests, poison message tests, visibility timeout tests, offset commit tests, publisher failure tests, rebalance tests, DLQ replay 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 broker, success-boundary, producer-boundary, retry, ordering, and observability evidence is available, or the missing evidence can be reported without guessing.
+- Existing local patterns for consumers, producers, inbox, outbox, idempotency, retry, DLQ, partition or group ordering, worker shutdown, and metrics have been searched before adding new shapes.
+- If queue processing moves money, credits, permissions, inventory, personal data, customer notifications, or provider calls, also apply the relevant payment, credit, security, idempotency, transaction, failure, or business-rule skill.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Move ack, delete, commit, or task acknowledgement after durable processing when the local broker contract requires it, and make redelivery safe with idempotent handlers or inbox records.
+- Add or tighten publisher confirmation, outbox writes, inbox or applied-message records, unique message or event keys, conditional state transitions, DLQ routing, poison-message classification, retry budgets, visibility extension, bounded concurrency, prefetch limits, rebalance hooks, and shutdown drains.
+- Separate transient failures from permanent payload failures so invalid messages do not loop forever and temporary outages do not vanish as successful work.
+- Add focused tests for the changed settlement, redelivery, ordering, retry, DLQ, and producer-confirm boundary.
+- Do not replace durable message integrity with dashboard lag checks, log-only errors, frontend disabling, memory-only dedupe, unlimited parallelism, infinite requeue, or broad catch-and-ack behavior.
+- Do not introduce live broker, server, watcher, tunnel, load-test, or manual replay commands outside the configured command contract.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Start at the settlement call.
+   - Search the changed path for `ack`, `nack`, `reject`, `deleteMessage`, `commitSync`, `commitAsync`, `commit`, `checkpoint`, `confirm`, `task ack`, `acks_late`, `autoAck`, `auto.commit`, `visibility`, `prefetch`, `maxReceiveCount`, `MessageGroupId`, `deduplication`, and local equivalents.
+   - Treat these terms as anchors, not automatic bugs.
+2. Build the message lifecycle.
+   - Name the producer, broker, consumer, business handler, durable writes, external side effects, retry path, DLQ path, replay path, and final operator-visible state.
+   - Mark which component owns "received", "started", "durably applied", "externally applied", "settled", "retried", "dead-lettered", and "reconciled".
+3. Reject ack-before-truth.
+   - Ack, delete, commit, or mark-complete before durable work can lose the message when the next line fails.
+   - A `finally` block that always acknowledges is usually a discard policy disguised as cleanup.
+   - A catch block that logs and returns normally can have the same effect if the framework auto-acks normal returns.
+4. Reject unbounded redelivery loops.
+   - Blind nack, reject, requeue, or retry on every failure can keep one poison message burning CPU, network, logs, and downstream systems.
+   - Require permanent-failure classification, retry count, backoff, jitter, DLQ threshold, and a reason that helps replay or discard safely.
+5. Check producer confirmation.
+   - A producer that only calls `send` or `publish` may not know the broker durably accepted the message.
+   - If local DB commit and queue publish are separate, require outbox, transactional publish support, reconciliation, or a reported split-brain risk.
+6. Review async handler ownership.
+   - If processing returns a promise, future, coroutine, goroutine, thread, or background task, settlement must wait for the actual work or explicitly record durable handoff.
+   - Fire-and-forget work after ack is message loss unless the handoff itself is durable and observable.
+7. Review batch settlement.
+   - Batch commit after mixed success can skip failed items.
+   - Per-item failure handling, partial commit boundaries, ordered stop-on-failure behavior, or replay-safe idempotency should be explicit.
+   - Check off-by-one semantics where a committed offset or checkpoint means the next message to read, not the last item processed.
+8. Review SQS-style visibility and delete behavior.
+   - Receiving a message is not finishing it; delete is the success boundary.
+   - Visibility timeout should cover high-percentile processing or be extended with a heartbeat while avoiding recovery delays that are too long.
+   - Check stale receipt handles, in-flight limits, DLQ redrive thresholds, and duplicate processing after timeout.
+9. Review RabbitMQ-style ack behavior.
+   - `autoAck` or equivalent automatic acknowledgement is a loss-prone default for important work.
+   - `multiple=true` or bulk ack can acknowledge earlier concurrent deliveries that have not finished.
+   - Ack should happen on the owning channel or equivalent delivery context.
+   - Prefetch should bound unacknowledged work instead of loading unlimited messages into consumer memory.
+10. Review Kafka-style offset behavior.
+    - Auto-commit can move the durable cursor ahead of handler completion.
+    - Manual commits should reflect only records actually processed.
+    - Long processing should respect poll intervals, pause or resume behavior, worker handoff, and rebalance revoke handling so ownership changes do not lose or duplicate in-flight records unexpectedly.
+11. Review Celery-style task acknowledgement.
+    - Default early acknowledgement can mark a task complete before work runs.
+    - Late acknowledgement helps only when tasks are idempotent and worker-loss behavior is configured for the desired redelivery semantics.
+    - Broad auto-retry over every exception can turn invalid payloads into poison-message loops.
+12. Review ordering and concurrency.
+    - FIFO groups, Kafka partitions, per-tenant locks, entity keys, and aggregate ordering should match the business ordering requirement.
+    - One global group can serialize the whole system; a unique group for every message can destroy per-entity ordering.
+    - Parallel consumers need idempotency and conditional state transitions for redelivery and out-of-order completion.
+13. Review side-effect ordering.
+    - Email, payment, entitlement, stock, file conversion, webhooks, provider calls, and downstream publishes should not be able to run twice without a durable operation key.
+    - If side effects happen before completion markers, crash recovery needs idempotency, provider lookup, reconciliation, or compensation.
+14. Review DLQ as a workflow, not a bucket.
+    - DLQ entries need reason, attempt count, original queue, message identity, safe payload summary, replay eligibility, and alerting or ownership.
+    - A DLQ consumer or replay tool can repeat the same bug if it lacks idempotency, ordering, and poison classification.
+15. Review backpressure and resource bounds.
+    - Unlimited `Promise.all`, unbounded goroutines, huge prefetch, large batch size, or worker pools detached from DB and HTTP pool limits can move the bottleneck from broker lag to consumer collapse.
+    - Bound concurrency by downstream capacity and message processing cost.
+16. Review shutdown, cancellation, and worker loss.
+    - A worker should stop receiving new work, finish or safely abandon in-progress work, and avoid acknowledging work that did not complete.
+    - Cancellation should not be swallowed as success.
+17. Review observability at decision points.
+    - Logs and metrics should record the decision: processed, acknowledged, committed, retried, delayed, dead-lettered, discarded, or unknown.
+    - Useful fields include message id, correlation id, attempt, queue delay, processing duration, ack or commit result, retry-after, DLQ reason, and safe business key.
+    - "Received message" alone is not incident evidence.
+18. Require replay-path evidence.
+    - Good tests or integration checks cover duplicate delivery, handler failure before settlement, settlement failure after durable commit, poison payload, delayed redelivery, visibility expiry, rebalance, worker crash, DLQ replay, and producer publish failure.
+    - If deterministic broker evidence is not configured, report static risk and missing manual or integration proof instead of approving the path.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The producer acceptance boundary, consumer settlement boundary, durable state boundary, retry or DLQ policy, ordering guarantee, resource bounds, shutdown behavior, and replay story are explicit.
+- Ack-before-work, catch-and-ack, finally-ack, auto-ack, stale receipt handle, premature offset commit, batch partial-failure skip, unbounded requeue, poison-message loops, unsafe visibility timeout, in-flight saturation, FIFO group misuse, worker-loss false success, producer publish split, side-effect duplication, and observability gaps are fixed or reported.
+- Queue safety claims are backed by configured tests, broker or framework evidence matched to current code, schema or idempotency evidence, static review evidence, or labeled as manual-only or missing.
+
+<!-- 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 queue processing boundary and synchronized template surfaces. Do not infer raw broker commands, local servers, live queue workers, replay scripts, load tests, watchers, tunnels, or manual dashboards 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 queue-processing invariant it exercised before editing again.
+- If the success boundary cannot be found, report that the queue path is not reviewable for processing integrity yet.
+- If the broker delivery semantics are unknown, report the missing broker contract instead of assuming exactly-once behavior.
+- If safe repair requires schema migration, outbox, inbox, durable dedupe, broker configuration, DLQ operator workflow, visibility heartbeat, rebalance architecture, or integration replay harness outside the current scope, report the missing durable boundary.
+- If deterministic broker proof is not configured, complete available verification and report the missing manual or integration evidence.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Queue processing boundary reviewed
+- Broker model, producer confirm, consumer settlement, durable state, side effects, retry or DLQ policy, visibility or offset or ack behavior, batch behavior, ordering, concurrency, shutdown, observability, and replay evidence findings
+- Queue-processing fixes made or recommended
+- Evidence level: configured-test evidence, schema or idempotency evidence, broker or framework evidence, static review risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped queue diagnostics and reasons
+- Remaining queue-processing-integrity risk

package/templates/default/locales/en/.mustflow/skills/race-condition-review/SKILL.md

@@ -0,0 +1,188 @@
+---
+mustflow_doc: skill.race-condition-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: race-condition-review
+description: Apply this skill when code is created, changed, reviewed, or reported and shared state can be observed across interleaving execution flows, including check-then-act, read-modify-write, stale reads after await or I/O, lock scope and order, tryLock, timeout or retry behavior, cache miss fill, lazy initialization, atomics and memory ordering, database transaction races, uniqueness, distributed locks, idempotency, atomic file creation, event or outbox ordering, queue duplicates, shutdown, cancellation, timers, close/send races, shared collections, object reuse, fake immutability, sleep-based race tests, log ordering, and state-machine transitions.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.race-condition-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Race Condition Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Find race conditions by tracing which shared facts can become stale before code acts on them.
+
+The review question is not "does this code use threads?" The stronger question is "does code read a shared value, keep a meaning in its head for more than one step, and then let another execution flow change that meaning before the action?" Race bugs appear in async servers, queues, database writes, caches, filesystems, timers, shutdown paths, and event streams even when the language runtime has a single event loop.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code is created, changed, reviewed, or reported and shared state, durable state, cached state, process state, collection state, socket state, file state, queue state, or lifecycle state can be touched by more than one request, worker, callback, timer, retry, queue delivery, or async continuation.
+- Code reads state and later acts on that read after `await`, I/O, a database call, callback invocation, event publish, lock release, timer scheduling, queue insertion, retry, cancellation, shutdown, or another function call.
+- Code uses check-then-act, read-modify-write, `++`, `+=`, `push`, `append`, `map[key] = value`, `get` then `set`, lazy initialization, double-checked locking, cache miss fill, sequence generation, state status changes, close/send operations, or object pooling.
+- Code adds or changes locks, mutexes, synchronized blocks, distributed locks, atomic values, compare-and-swap, transaction isolation, row locks, unique constraints, idempotency keys, outbox or inbox processing, retry policies, queue consumers, timers, cancellation, or shutdown behavior.
+- A review or final report claims a path is race-free, atomic, thread-safe, event-loop-safe, idempotent, lock-protected, transaction-protected, retry-safe, or safe under concurrent requests.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only changes local immutable values inside one call stack with no shared owner, durable store, callback, async yield, queue, timer, lock, or lifecycle boundary.
+- The task is only object retention or cleanup risk; use `memory-lifetime-review` first and this skill only if cleanup races, cancellation races, or close/send races also matter.
+- The task is only expected failure, retry, idempotency, cache, queue, or outbox behavior in a backend surface; use `backend-reliability-change` first and this skill as the interleaving adjunct.
+- The task is only lifecycle transition modeling; use `state-machine-pattern` first and this skill only when stale concurrent transitions or duplicate side effects matter.
+- The only concern is query speed, allocation churn, or hot-path latency with no stale-read or shared-state interleaving risk.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Shared state surface: variable, object, collection, cache, file, socket, stream, database row, table, queue, message, state field, lock, atomic, timer, cancellation token, shutdown flag, or external side effect.
+- Invariant: the fact that must stay true across more than one line, field, row, message, event, callback, or operation.
+- Interleaving points: `await`, I/O, database calls, callbacks, hooks, plugin calls, event publish, queue insert, lock release, timer scheduling, retry, cancellation, shutdown, close, send, and other function calls after a state read.
+- Synchronization boundary: lock scope, atomic operation, compare-and-swap, transaction, row lock, unique constraint, conditional update, singleflight, idempotency record, outbox, or file atomic create/rename behavior.
+- Ordering and duplication rules: event order, queue delivery semantics, duplicate messages, same-user or same-resource concurrency, retry replay, cancellation timing, timer overlap, and shutdown drain behavior.
+- Evidence surface: existing tests, fixtures, schema constraints, command intents, logs, metrics, sequence numbers, request ids, transaction ids, versions, or manual-only concurrency 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.
+- Required inputs are available, or missing state, invariant, isolation, lock, idempotency, or ordering facts can be reported without guessing.
+- Existing local patterns for locks, atomics, database transactions, state machines, idempotency, queues, outbox/inbox, cancellation, shutdown, tests, and logging have been searched before adding new primitives.
+- If the race affects authorization, personal data, money, orders, external side effects, or audit records, also apply the relevant security, backend reliability, database, or API skill.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Replace check-then-act and read-modify-write sequences with atomic create, atomic conditional update, compare-and-swap, row lock, unique constraint, idempotency guard, singleflight, or a correctly scoped lock when local style supports it.
+- Narrow lock scope to protect the whole invariant and remove slow callbacks, hooks, events, network calls, logs, JSON conversion, or plugin execution from inside locks where possible.
+- Add global lock order, state transition guards, outbox or inbox guards, duplicate-message handling, cancellation and close idempotence, timer ownership checks, iterator snapshot handling, snapshot iteration, copy-on-write, or object ownership boundaries tied to the task.
+- Add focused tests, fixtures, schema constraints, or docs that prove the concurrency invariant when the repository has a configured way to exercise it.
+- Do not replace a real atomicity requirement with `sleep`, arbitrary delay, best-effort retry, log ordering, comments, or a distributed lock that is not backed by a durable data invariant.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the shared fact. State the exact value or invariant another execution flow could change: balance, status, cache entry, uniqueness, queue offset, file existence, socket state, collection membership, timer owner, shutdown flag, or object ownership.
+2. Build a stale-read ledger.
+   - For each shared state read, mark every later `await`, I/O, DB call, callback, event publish, queue insertion, lock release, timer, retry, cancellation, shutdown, close, send, or function call before the action.
+   - Ask whether the read is still true after each interleaving point. If the answer relies on hope, the path is not race-safe.
+3. Catch check-then-act.
+   - Treat patterns such as `if exists then create`, `if balance >= amount then withdraw`, `if status == pending then approve`, duplicate email checks, coupon redemption, order number generation, and filesystem `exists` then `open` as unsafe until proven atomic.
+   - Prefer atomic conditional updates, atomic create, insert with unique constraint, compare-and-swap, row locks, or file creation modes that fail when the target already exists.
+4. Catch read-modify-write.
+   - `++`, `+=`, `push`, `append`, `map[key] = value`, collection mutation, get-then-set, and counter updates are shared-state writes, not harmless syntax.
+   - Use atomic operations only when the invariant is one variable. If the invariant spans fields, rows, objects, or messages, use a transaction, lock, state machine, or conditional write that protects the whole fact.
+5. Do not trust a single event loop after `await`.
+   - In JavaScript, Python async, UI runtimes, and coroutine systems, a state read before `await` can be stale after the continuation resumes.
+   - Re-read, validate a version, hold the correct synchronization boundary, or move the decision into an atomic operation.
+6. Review lock scope by invariant, not by field.
+   - A lock around one setter does not protect a multi-field or multi-row rule if reads and writes outside the lock can observe intermediate state.
+   - Keep callbacks, hooks, events, plugin calls, external I/O, logging, JSON conversion, and long calculations outside locks unless the invariant truly requires them.
+   - Define and follow a global lock order when more than one lock can be acquired.
+7. Treat `tryLock`, timeout, and retry as risk multipliers.
+   - Check what partial state remains when lock acquisition fails, times out, or is retried.
+   - Verify rollback, idempotency, duplicate side-effect prevention, and retry budget. A retry can make a race rarer or louder, not correct.
+8. Review cache miss fill and lazy initialization.
+   - Multiple misses for the same key should not all rebuild, fetch, insert, or publish the same value unless duplication is harmless and bounded.
+   - Use singleflight, promise memoization with failure cleanup, once initialization, durable uniqueness, or explicit cache-authority rules.
+   - Double-checked locking needs a memory-ordering story in runtimes where construction visibility is not automatically safe.
+9. Review atomics and memory ordering.
+   - Atomics protect a specific operation on a specific value. They do not automatically make surrounding objects, arrays, maps, or multi-field invariants safe.
+   - Check acquire/release or stronger memory ordering where the language exposes it, and report missing expertise or evidence instead of guessing.
+10. Review database races.
+    - A database transaction does not erase a race by itself. Check isolation level, row locks, predicate locks, uniqueness, conditional updates, and whether `SELECT` then `UPDATE` can be invalidated before commit.
+    - Prefer `UPDATE ... WHERE status = ...`, insert-or-ignore/upsert with unique constraints, version columns, row locks, or serializable isolation when the invariant requires it.
+    - Application-level duplicate checks are advisory only; unique facts belong in the database or another durable single-writer authority.
+11. Review distributed locks as debt.
+    - Lock expiry, process pauses, network delay, clock skew, and split ownership can let two workers believe they own the same work.
+    - Keep data correct if the distributed lock breaks: unique constraints, idempotency keys, fencing tokens, conditional writes, or state transitions should still reject stale owners.
+12. Review event, queue, and outbox ordering.
+    - Publishing an event before or after a state change can split the world unless a durable outbox or equivalent boundary ties them together.
+    - Queue consumers should assume duplicates, reordering, delayed delivery, redelivery after timeout, and concurrent work for the same user or resource.
+    - Use inbox deduplication, per-aggregate ordering, conditional state transitions, or idempotent side effects where needed.
+13. Review filesystem races.
+    - `exists` then `open`, temp file name selection, cleanup by path, and replace-in-place can race.
+    - Prefer atomic create, safe temporary file APIs, same-directory temp files, fsync where durability matters, and atomic rename or replace semantics appropriate to the platform.
+14. Review shutdown, cancellation, timers, close, and send.
+    - Shutdown should define who stops accepting work, who drains, who cancels, and who owns in-flight side effects.
+    - Cancellation must be idempotent and safe when completion happens at the same time.
+    - Timers and schedulers need one current owner; old timers should not update new state.
+    - WebSocket, channel, stream, socket, queue, and emitter paths need a clear rule for close/send races and double close.
+15. Review shared collections and object reuse.
+    - Iteration over a collection that another flow can mutate needs a lock, snapshot, immutable copy, version check, or concurrent collection semantics.
+    - Object pooling, buffer reuse, mutable DTO reuse, and reused request contexts are unsafe if async work can still hold references.
+    - Fake immutable objects with mutable internals, getters, shared maps, or cached arrays should be treated as mutable shared state.
+16. Review tests and logs with suspicion.
+    - `sleep`-based race tests are usually probability tests. Prefer deterministic barriers, fake schedulers, controlled promises, version assertions, unique constraints, or repeated stress only as supplementary evidence.
+    - Logging can hide or change a race. Log order is not event order across threads, processes, async tasks, buffers, or machines.
+    - Use monotonic sequence numbers, request ids, transaction ids, version columns, or state transition logs when ordering is evidence.
+17. Escalate broad status fields into state-machine review.
+    - If values such as `pending`, `processing`, `done`, `failed`, `cancelled`, `closed`, or `deleted` drive behavior, draw allowed transitions and reject stale concurrent transitions.
+    - Use `state-machine-pattern` when the race fix needs a transition table, event union, transition log, retry reconciliation, or effect ordering.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Shared state reads, interleaving points, and stale-read risks are identified or ruled out.
+- Check-then-act and read-modify-write paths are atomic, guarded, constrained, or explicitly reported as residual risk.
+- Locks protect whole invariants, have a clear ordering rule, and avoid slow or reentrant work where possible.
+- Database, cache, queue, event, filesystem, cancellation, shutdown, timer, close/send, collection, and object-reuse races are checked where relevant.
+- Tests or configured verification cover the highest-risk concurrency invariant when feasible.
+
+<!-- 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 proves the changed concurrency invariant. Do not infer raw stress, load, database, queue, thread sanitizer, profiler, server, watcher, or sleep-loop 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 shared-state invariant it exercised before editing again.
+- If the invariant cannot be named, stop and report that the code is not reviewable for races yet.
+- If a fix requires a schema constraint, isolation change, outbox, queue contract, state-machine transition, or idempotency store outside the current scope, report the missing durable boundary instead of adding a local lock that cannot enforce it.
+- If deterministic race proof is not configured, report the missing manual evidence and complete the configured checks that are available.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Shared state and invariant reviewed
+- Interleaving points checked
+- Check-then-act and read-modify-write findings
+- Async stale-read, lock scope/order, tryLock/timeout/retry, cache/lazy init, atomic/memory ordering, database transaction, uniqueness, distributed lock, idempotency, filesystem, event/outbox, queue, shutdown, cancellation, timer, close/send, shared collection, object reuse, fake immutable, test, log, and state-machine checks where relevant
+- Race fixes made or recommended
+- Tests or verification evidence
+- Command intents run
+- Skipped concurrency diagnostics and reasons
+- Remaining race-condition risk