mustflow 2.116.1 → 2.116.2

package/templates/default/locales/en/.mustflow/skills/parser-engineering-review/references/tree-serialization-compatibility-checklist.md

@@ -0,0 +1,164 @@
+# Tree Serialization and Compatibility Checklist
+
+Use this checklist when a CST, AST, HIR, analysis index, or related tree snapshot is serialized,
+cached, exchanged across versions, deserialized from untrusted bytes, migrated, or fuzzed.
+
+## Contents
+
+1. [Artifact lifetime contract](#artifact-lifetime-contract)
+2. [Memory model and wire schema](#memory-model-and-wire-schema)
+3. [Header and early rejection](#header-and-early-rejection)
+4. [Schema evolution and presence](#schema-evolution-and-presence)
+5. [Bounded decoding](#bounded-decoding)
+6. [Two-phase graph reconstruction](#two-phase-graph-reconstruction)
+7. [Validation layers](#validation-layers)
+8. [Deterministic encoding](#deterministic-encoding)
+9. [Cross-version and migration matrix](#cross-version-and-migration-matrix)
+10. [Identity and snapshot scope](#identity-and-snapshot-scope)
+11. [Fuzz targets and oracles](#fuzz-targets-and-oracles)
+12. [Invariants and handoffs](#invariants-and-handoffs)
+
+## Artifact lifetime contract
+
+Decide first whether the artifact is:
+
+- a disposable cache that may reject incompatible data and regenerate;
+- a build or IDE exchange artifact with a bounded compatibility window;
+- a durable user or ecosystem format requiring migration and unknown-data preservation.
+
+Name readers, writers, retention, privacy, trust boundary, regeneration source, and supported version
+matrix. Do not burden a disposable cache with indefinite migration or treat durable data as safely
+discardable.
+
+## Memory model and wire schema
+
+Separate runtime nodes from the wire contract. Define stable integer widths, signedness, byte order,
+string encoding, node-kind numbers, field numbers, union tags, presence, list lengths, reference IDs,
+and ordering rules. Never serialize pointers, allocator slots, object padding, host enum ordinals, or
+compiler-dependent layouts as a portable format.
+
+Keep encoder and decoder adapters between the wire schema and current in-memory representation. A
+node-class refactor must not silently reinterpret old bytes.
+
+## Header and early rejection
+
+Validate a bounded fixed header before decompression, allocation, or graph construction. Include
+applicable magic, schema major and minor, language or dialect identity, feature bitmap, payload and
+expanded lengths, compression mode, checksum or digest, producer diagnostics, and artifact class.
+
+Treat producer version as evidence for diagnostics, not permission to trust the payload. Reject
+unsupported mandatory features, impossible lengths, incompatible major versions, and policy limits
+before expensive work.
+
+## Schema evolution and presence
+
+- Assign stable node-kind and field numbers. Reserve removed numbers and never reuse them for a new
+  meaning.
+- Distinguish absent fields from fields explicitly set to their default when migration or semantics
+  can observe presence.
+- Add optional fields with safe reader behavior. Do not add required fields that older writers cannot
+  provide inside a claimed compatibility window.
+- Define unknown field and unknown variant behavior: preserve, skip, quarantine, or reject by field
+  criticality and artifact contract.
+- Keep migrations pure, ordered, restartable, and independently testable. Preserve extensions that a
+  migration does not understand when the durable-format contract requires round trips.
+
+## Bounded decoding
+
+Charge limits before allocation and expansion. Bound compressed and expanded bytes, strings, node
+count, children per node, total edges, reference tables, diagnostics, nesting, work units, and wall-
+clock deadline. Use an explicit stack when attacker-controlled depth could overflow the call stack.
+
+Require integer arithmetic for lengths and offsets to reject overflow, overlap, truncation, and
+out-of-range slices. A checksum detects corruption; it does not establish safe structure or meaning.
+
+## Two-phase graph reconstruction
+
+Decode bounded tables and node records without creating raw pointers. In a second phase, resolve IDs
+and verify:
+
+- reference range and expected target kind;
+- ID uniqueness and owning document, item, or body;
+- single structural parent where a tree contract requires it;
+- absence of structural cycles;
+- list cardinality and source-order constraints;
+- separation of ownership edges from symbol, use-def, or control-flow references.
+
+Do not expose a partially linked graph to visitors, destructors, plugins, or semantic consumers.
+
+## Validation layers
+
+Keep four results distinct:
+
+1. wire validity: lengths, tags, encoding, checksum, and feature framing;
+2. structural validity: node kinds, fields, IDs, edges, cycles, and cardinality;
+3. semantic validity: scopes, symbol kinds, types, effects, and source relationships;
+4. phase validity: invariants promised by CST, AST, typed HIR, MIR, or another declared layer.
+
+A successful decoder proves only the earlier layers it actually checked. Run the owning tree or IR
+verifier before publishing the artifact as usable.
+
+## Deterministic encoding
+
+Make one supported writer emit canonical bytes for the same declared semantic or syntax identity.
+Normalize map order, string tables, temporary IDs, diagnostic order, feature ordering, and equivalent
+encodings. Do not make readers depend on field arrival order unless the wire schema requires it.
+
+Define whether source spelling, trivia, positions, nondeterministic analysis facts, and producer-only
+metadata participate in the canonical identity. Keep semantic and exact-source hashes separate.
+
+## Cross-version and migration matrix
+
+Maintain golden artifacts from every supported writer version and verify every promised reader and
+writer pairing. Cover oldest-supported to current migrations, current writer to older compatible
+reader where promised, unknown fields, retired fields, optional presence, unsupported features, and
+corrupt headers.
+
+Compare migration chains with direct construction of the latest schema. Make the support window and
+rejection diagnostic executable rather than relying on prose compatibility claims.
+
+## Identity and snapshot scope
+
+Do not serialize raw snapshot-local IDs as durable semantic identity. Namespace serialized IDs by
+artifact and owner, remap them on load, and preserve explicit origin or definition identities only
+when their stability contract spans the artifact boundary.
+
+Bind cached analysis to source or tree fingerprint, language options, dependency generations, schema
+version, and producer contract. Reject a structurally valid cache whose semantic dependency capsule
+does not match the current workspace.
+
+## Fuzz targets and oracles
+
+Keep complementary bounded targets:
+
+- raw bytes for framing, length, decoder, and rejection safety;
+- schema-aware near-valid records for deep structural validation;
+- valid generated trees for semantic verifier, encode, decode, rewrite, and migration paths;
+- API sequences such as decode, verify, rewrite, encode, reload, and discard-old-snapshot.
+
+Use oracles beyond crashes:
+
+- decode then encode produces canonical bytes for accepted artifacts;
+- encode then decode preserves the declared semantic and source-aware identity;
+- migrations agree with direct latest-schema construction;
+- repeated canonical encoding is deterministic;
+- invalid graphs are rejected by the correct validation layer;
+- work, memory, depth, and output stay within budgets;
+- stale handles and snapshot references do not resolve after replacement.
+
+Keep raw mutation, structured generation, campaign feedback, corpora, minimization, sanitizer lanes,
+and long-running execution under `fuzz-harness-review`. This checklist owns tree-format semantics and
+oracles, not campaign authority.
+
+## Invariants and handoffs
+
+- Every artifact declares cache, exchange, or durable lifetime semantics.
+- Every accepted payload passes bounded wire, structural, semantic, and phase checks as applicable.
+- Every schema number and presence rule has an evolution contract.
+- Every durable identity is distinct from runtime pointers and snapshot-local IDs.
+- Every compatibility claim names tested reader and writer versions.
+- Every fuzz claim names a semantic, determinism, validation, or resource oracle beyond coverage.
+- Use `parser-engineering-review` for CST and AST wire or snapshot contracts.
+- Use `compiler-engineering-review` for persisted HIR, MIR, IR, and compiler metadata semantics.
+- Use `fuzz-harness-review` for maintained campaigns, mutators, corpora, and sanitizer execution.
+- Use the matching public-contract or data-migration skill for durable external formats.

package/templates/default/locales/en/.mustflow/skills/parser-engineering-review/references/tree-traversal-rewrite-checklist.md

@@ -0,0 +1,209 @@
+# Tree Traversal and Rewrite Checklist
+
+Use this checklist when syntax or semantic trees are visited, transformed, rewritten, structurally
+shared, incrementally remapped, or used as keys for cached analysis.
+
+## Contents
+
+1. [Responsibility split](#responsibility-split)
+2. [Traversal policy](#traversal-policy)
+3. [Immutable snapshot boundary](#immutable-snapshot-boundary)
+4. [Traversal context](#traversal-context)
+5. [Transformation result algebra](#transformation-result-algebra)
+6. [Edit collection and conflict resolution](#edit-collection-and-conflict-resolution)
+7. [Structural sharing and source fidelity](#structural-sharing-and-source-fidelity)
+8. [Handles and identity across snapshots](#handles-and-identity-across-snapshots)
+9. [Analysis invalidation](#analysis-invalidation)
+10. [Rewrite termination](#rewrite-termination)
+11. [Tree and graph traversal](#tree-and-graph-traversal)
+12. [Transactional commit and verification](#transactional-commit-and-verification)
+13. [Test matrix](#test-matrix)
+14. [Invariants and handoffs](#invariants-and-handoffs)
+
+## Responsibility split
+
+Keep three contracts distinct even when a library uses different names:
+
+| Role | Reads | Produces | Must not do |
+| --- | --- | --- | --- |
+| Visitor | One immutable snapshot | Observations or side-table facts | Mutate the traversed structure |
+| Transformer | One immutable snapshot | A new snapshot or typed change result | Edit nodes in place or resolve rule conflicts implicitly |
+| Rewriter | Snapshot, rules, edit policy | Validated transactional commit | Apply a match immediately without conflict and termination policy |
+
+A visitor is not a weak rewriter, and a rewriter is not a visitor with writable nodes. Name the role
+in APIs, ownership types, tests, and diagnostics.
+
+## Traversal policy
+
+Declare the policy as data or typed configuration:
+
+- preorder, postorder, enter and leave callbacks, or an explicitly mixed schedule;
+- structural nodes, tokens, trivia, missing and error nodes, and synthetic nodes included or skipped;
+- source-written versus expanded or generated forms;
+- child field order and list order;
+- one visit per ownership edge or one visit per unique shared node;
+- cancellation, early stop, depth budget, and error propagation;
+- behavior for a node kind unknown to the visitor implementation.
+
+Fail closed in development and contract tests when a closed node union gains an unhandled variant.
+Do not let a default branch silently omit new syntax from security, refactoring, or semantic passes.
+
+## Immutable snapshot boundary
+
+- Give a visitor read-only access to a versioned snapshot and write observations to a separate result
+  builder or generation-aware side table.
+- Make a transformer return a new root while reusing unchanged immutable subtrees. Do not mutate the
+  child list currently being traversed.
+- Collect rewrite proposals against one base snapshot. Do not let an early proposal change what later
+  matchers see unless the rewrite contract explicitly starts another bounded epoch.
+- Invalidate iterators, wrappers, positions, and parent views when their owning snapshot changes.
+- If in-place mutation is unavoidable, require a generation-checked cursor and make every existing
+  iterator unusable after mutation. Do not expose this as the ordinary tree API.
+
+## Traversal context
+
+Pass context explicitly rather than hiding it in mutable visitor fields. Include applicable facts:
+
+- document and snapshot generation;
+- parent kind, named child field, list index, and ownership path;
+- scope owner, language mode, expected node category, and source region;
+- cancellation and work budget;
+- traversal policy and rewrite epoch.
+
+Use immutable context frames or scoped push and pop guards whose cleanup is guaranteed on early
+return and error. Never infer a semantic parent from an obsolete parent pointer.
+
+## Transformation result algebra
+
+Do not overload null with several outcomes. Use typed results such as:
+
+- `Keep` for unchanged identity and structure;
+- `Replace(node)` for one category-compatible replacement;
+- `Delete` only where the parent field is optional or repeated;
+- `Splice(nodes)` only in a repeated slot with compatible element kinds;
+- `Stop(result)` for successful bounded early termination;
+- `Error(diagnostic)` for a failed transformation with no commit.
+
+Validate result kind and cardinality at the parent boundary. Reject deletion of a required child,
+splicing into a scalar field, or replacing an expression with a declaration before a malformed
+intermediate tree becomes observable.
+
+## Edit collection and conflict resolution
+
+Represent every proposal with rule identity, base snapshot, target handle, expected kind, parent
+field, source or structural anchor, replacement, priority, and provenance. Then:
+
+1. collect candidates without mutation;
+2. reject stale or unresolved targets;
+3. group overlapping parent, child, sibling, and source-range edits;
+4. resolve conflicts under one documented policy;
+5. sort accepted edits deterministically;
+6. apply them to a private new snapshot;
+7. verify and publish atomically.
+
+Define whether outer replacement suppresses inner edits, deeper edits win, or a conflict is an error.
+Rule registration order must not become accidental precedence. A failed commit exposes neither a
+partial tree nor partially updated side tables.
+
+## Structural sharing and source fidelity
+
+- Keep reusable persistent nodes free of parent pointers and absolute positions. Derive snapshot-
+  specific parents and positions through ephemeral wrappers or indexed views.
+- Preserve syntax origins, token ownership, trivia, missing tokens, and delimiter relationships when
+  replacing source-aware nodes.
+- Reuse an original node only when all structural children, payload, recovery state, and relevant
+  source references are unchanged.
+- Distinguish generated text from original slices. Do not copy a parent's full span onto a synthetic
+  child or claim user authorship for inserted syntax.
+- Reconcile leading, trailing, and dangling trivia at edit boundaries under a deterministic policy.
+
+## Handles and identity across snapshots
+
+Separate allocation identity, snapshot-local node identity, persistent syntax identity, and semantic
+definition identity. A byte offset or structural hash is not any of those identities.
+
+A durable handle should carry document identity, expected snapshot or generation, node key, expected
+kind, and optional owner or field anchor. Resolve it through the current snapshot into a state such as
+`Alive`, `Replaced`, `Deleted`, `Ambiguous`, `WrongDocument`, or `OutOfDate`; do not return one null for
+every failure class.
+
+Inherit persistent identity only from actual subtree reuse or one unambiguous bounded reconciliation.
+Match within an owner using kind, field role, stable token anchors, sibling alignment, and structure.
+When candidates tie, allocate a new identity. Copy and move identity require edit-lineage evidence;
+final text alone cannot prove user intent.
+
+Mark recovery regions and their ancestor chain unstable. Avoid aggressively transferring identity
+through rapidly changing missing and error nodes.
+
+## Analysis invalidation
+
+Each transformation declares:
+
+- node fields, ownership regions, symbols, control flow, and source relations it reads;
+- structure, names, effects, types, scopes, or origins it may change;
+- analyses proven preserved and the proof boundary;
+- analyses invalidated, recomputed, or weakened;
+- deleted-node keys and snapshot generations retired at commit.
+
+Default unproven analyses to invalid. Syntax identity survival does not prove symbol, type, control-
+flow, macro, language-option, or cross-file dependency facts remain valid.
+
+## Rewrite termination
+
+Bound every repeated rewrite by at least one explicit mechanism:
+
+- a well-founded cost that strictly decreases;
+- stage direction that forbids returning to an earlier form;
+- rule and node application history within an epoch;
+- repeated structural-state detection;
+- maximum epochs, proposals, committed edits, and work units.
+
+Reject self-recreating and mutually inverse rule cycles. For canonicalization, require idempotence:
+running the completed rewrite again produces no structural or semantic change. If a pass intentionally
+is not idempotent, name its finite convergence contract.
+
+## Tree and graph traversal
+
+Walk ownership children as a tree or forest. Treat symbol links, use-def relations, control-flow
+edges, parent maps, and cross-file references as separate graphs with their own visited set, cycle
+policy, ordering, and budget. Do not recursively follow all references with the ownership visitor.
+
+For graphs, state whether work is per node, edge, path, strongly connected component, block, or
+program point. Shared targets and cycles are ordinary graph structure, not tree exceptions.
+
+## Transactional commit and verification
+
+Before commit, verify proposal freshness and replacement category. After private construction, run
+the phase verifier for node kinds, required children, cycles, parent ownership, identities, spans,
+origins, recovery states, and side-table generation. Publish the new root and compatible analysis
+generation together or publish neither.
+
+Keep diagnostics tied to rule identity and the smallest input/output boundary. A later crash must not
+be the first evidence that an earlier rewrite broke the tree.
+
+## Test matrix
+
+- Assert preorder, postorder, enter/leave, token/trivia, generated-node, error-node, and stop behavior.
+- Add a new node variant and prove exhaustive visitors or contract tests reject missing handling.
+- Exercise every typed transformation outcome in scalar, optional, and repeated fields.
+- Generate overlapping parent/child and sibling edits; permute rule registration and candidate order.
+- Compare old-snapshot traversal with new-snapshot output and prove no inserted node is accidentally
+  revisited in the same epoch.
+- Verify unchanged subtrees are shared and changed wrappers, positions, and handles become stale.
+- Test ambiguous reconciliation, copy, move, deletion, recovery zones, generation reuse, and ABA-like
+  slot reuse.
+- Compare preserved analyses with independent full recomputation.
+- Run rewrite idempotence, cycle, work-budget, cancellation, rollback, and verifier-failure cases.
+- Apply randomized edit sequences and compare incremental trees and handles with fresh reconstruction.
+
+## Invariants and handoffs
+
+- Every traversal has a declared order, edge model, inclusion policy, and budget.
+- Every visitor is read-only and every transformation creates a new validated snapshot.
+- Every edit conflict and rewrite cycle reaches a deterministic bounded outcome.
+- Every durable handle is resolved against document and generation context.
+- Every preserved analysis is explicitly justified; all others are invalidated.
+- Use `parser-engineering-review` for syntax-tree traversal, source-aware transforms, and snapshots.
+- Use `compiler-engineering-review` for IR pass preservation, CFG, SSA, and semantic refinement.
+- Use `name-resolution-integrity-review` for symbol identity and binding-side-table disagreements.
+- Use `fuzz-harness-review` when traversal or rewrite fuzzing becomes a maintained campaign.

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.race-condition-review
 locale: en
 canonical: true
-revision: 3
+revision: 4
 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, fencing tokens, idempotency state records, atomic file creation, event or outbox ordering, inbox or dedupe consumers, per-key serialization, queue duplicates, shutdown, cancellation, timers, close/send races, shared collections, object reuse, fake immutability, sleep-based race tests, log ordering, and state-machine transitions.
+description: Apply this skill when code is created, changed, reviewed, reproduced, or reported and shared state can be observed across interleaving execution flows, including logical race versus data-race classification, forbidden-outcome assertions, deterministic schedule gates, record and replay, happens-before evidence, check-then-act, read-modify-write, stale reads after await or I/O, lock scope and order, mutex, semaphore, condition, channel, atomic and memory ordering choices, CAS and ABA, concurrent memory reclamation, linearizability, database transaction races, distributed locks, queues, shutdown, cancellation, object reuse, and schedule-sensitive tests.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -33,6 +33,10 @@ Find race conditions by tracing which shared facts can become stale before code
 
 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.
 
+Distinguish a logical race condition from an unsynchronized conflicting memory access. A dynamic
+data-race detector can expose the latter on executed paths without proving that higher-level
+check-then-act, ordering, ownership, or linearizability invariants are safe.
+
 <!-- mustflow-section: use-when -->
 ## Use When
 
@@ -62,6 +66,17 @@ The review question is not "does this code use threads?" The stronger question i
 - Idempotency and ownership rule: business idempotency key, processing/succeeded/failed record state, duplicate-in-progress behavior, fencing token or generation owner, and whether same-key work is serialized while unrelated keys can run concurrently.
 - Evidence surface: existing tests, fixtures, schema constraints, command intents, logs, metrics, sequence numbers, request ids, transaction ids, versions, or manual-only concurrency evidence.
 - Incident file when a concurrency failure was observed: test name, seed, worker or thread count, scheduler settings, timeout, input, build hash, OS/runtime version, environment slice, and exact failure time when available.
+- Defect classification and oracle: forbidden outcome, logical race, data race, lifetime violation,
+  deadlock, starvation, or ordering failure, plus the exact assertion that distinguishes failure.
+- Schedule evidence: actor count, deterministic gate decisions, scheduler seed, decision trace,
+  synchronization edges, input and schedule reductions, and record/replay trace when available.
+- Native-memory evidence when applicable: compiler and flags, architecture, optimization level,
+  atomic orderings, linearization point, allocator behavior, address reuse, reclamation protocol,
+  and sanitizer class.
+
+Read [references/race-reproduction-memory-model-checklist.md](references/race-reproduction-memory-model-checklist.md)
+when an incident is intermittent, native threads or lock-free structures are involved, primitive
+selection is disputed, or a race-free or linearizable claim needs schedule evidence.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -84,9 +99,19 @@ The review question is not "does this code use threads?" The stronger question i
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Preserve the incident file before changing code when a race was observed.
-   - Capture the failing test or workflow name, random seed, worker or thread count, scheduler or CPU-affinity setting when relevant, timeout, input, build hash, OS/runtime version, environment variables that affect scheduling, and exact failure time.
-   - Do not replace a missing incident file with "ran many times"; repeated passing runs are weaker than one reproducible failing condition.
+1. Classify and preserve the incident before changing code.
+   - Define one machine-checkable forbidden outcome such as two successful reservations for one
+     unit, a callback after close, a removed object becoming visible again, or a history with no
+     valid sequential explanation.
+   - Distinguish a logical race condition, data race, lifetime violation, deadlock, starvation, and
+     ordering failure. Do not treat one detector class as proof about the others.
+   - Capture the failing test or workflow name, input, worker or thread count, deterministic gate or
+     scheduler decisions, random seed, timeout, executable and build hash, compiler and flags,
+     linked runtime, OS, architecture, CPU count, allocator, optimization level, environment values
+     that affect scheduling, and exact failure time when available.
+   - Treat a dynamic detector pass as evidence only for the paths and schedule that executed. Do not
+     replace a missing incident capsule with "ran many times"; repeated passing runs are weaker than
+     one reproducible failing condition.
 2. 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.
 3. 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.
@@ -113,6 +138,16 @@ The review question is not "does this code use threads?" The stronger question i
    - Double-checked locking needs a memory-ordering story in runtimes where construction visibility is not automatically safe.
 10. 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 which write becomes visible to which read through a continuous happens-before edge. A
+     relaxed flag does not publish ordinary payload by itself, and several atomics do not form one
+     transaction over a multi-field invariant.
+   - Keep retryable compare-and-swap calculations free of external effects until the update wins, or
+     bind those effects to an idempotent durable identity.
+   - Treat pointer equality, object identity, and object lifetime as separate claims. CAS-based
+     structures need an ABA and tag-wrap story plus a memory-reclamation protocol such as a verified
+     hazard, epoch, RCU, or reference-counting design.
+   - Name each operation's linearization point and validate completed histories against a sequential
+     model when final-state assertions cannot expose an invalid intermediate history.
    - Check acquire/release or stronger memory ordering where the language exposes it, and report missing expertise or evidence instead of guessing.
 11. 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.
@@ -140,11 +175,23 @@ The review question is not "does this code use threads?" The stronger question i
     - 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.
 17. 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.
-    - Shake the schedule, not only the load: widen context-switch windows with configured deterministic barriers, fake schedulers, controlled yields, delay injection, or repeated stress harnesses only when the repository command contract allows them.
-    - Logging can hide or change a race. Log order is not event order across threads, processes, async tasks, buffers, or machines.
-    - Use happens-before logs at handoff points such as queue push/pop, mutex unlock/lock, atomic release/acquire, promise/future completion, channel send/receive, callback registration/execution, plus monotonic sequence numbers, request ids, transaction ids, version columns, or state transition logs when ordering is evidence.
-    - Treat race detectors, thread sanitizers, deterministic record/replay, profilers, kernel tracing, or stress tools as configured or manual diagnostics only; never infer raw commands from the tool names.
+   - `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.
+   - Shake the schedule, not only the load: widen context-switch windows with configured deterministic barriers, fake schedulers, controlled yields, delay injection, or repeated stress harnesses only when the repository command contract allows them.
+   - Reduce the reproducer to the smallest useful actors, shared object, operations, and arbiter.
+     Force meaningful windows after shared reads, validation, lock release, compare-and-swap load,
+     cancellation checks, removal, and publication rather than delaying arbitrary function entries.
+   - Explore schedules systematically when a bounded scheduler exists. For randomized disruption,
+     preserve both the seed and the actual decision trace; seed alone may not replay after thread,
+     timer, or random-call counts change.
+   - Minimize the failing input and the schedule. Remove unrelated operations, actors, switches, and
+     delay points while preserving the same forbidden outcome and defect class.
+   - Logging can hide or change a race. Log order is not event order across threads, processes, async tasks, buffers, or machines.
+   - Prefer bounded per-actor event buffers over a contended global logger. Build a happens-before
+     graph from actor-local order and synchronization edges such as queue push/pop, mutex
+     unlock/lock, atomic release/acquire, promise or future completion, channel send/receive,
+     callback registration/execution, and thread start/join. A timestamp order alone is not a
+     visibility proof.
+   - Treat race detectors, thread sanitizers, deterministic record/replay, profilers, kernel tracing, or stress tools as configured or manual diagnostics only; never infer raw commands from the tool names.
 18. 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.
@@ -159,6 +206,10 @@ The review question is not "does this code use threads?" The stronger question i
 - Database, cache, queue, event, filesystem, cancellation, shutdown, timer, close/send, collection, and object-reuse races are checked where relevant.
 - Idempotency processing states, duplicate-in-progress behavior, fencing tokens, outbox/inbox handoffs, and per-key serialization are checked where relevant.
 - Tests or configured verification cover the highest-risk concurrency invariant when feasible.
+- Incident evidence distinguishes logical races, data races, lifetime failures, and other timing
+  defects without treating a detector pass as universal proof.
+- The highest-risk reproducer has a forbidden-outcome oracle, bounded actor model, replayable
+  schedule evidence, and minimized input or named evidence gaps when feasible.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -184,17 +235,23 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 - 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.
+- If a detector finds a data race, preserve that finding without inflating it into every possible
+  business impact; if the detector is clean, do not upgrade the result to logical race safety.
+- If a schedule cannot replay, preserve the full decision trace and environment capsule before
+  changing the code or shrinking the reproducer further.
 
 <!-- mustflow-section: output-format -->
 ## Output Format
 
 - Shared state and invariant reviewed
-- Incident file captured or reported missing
+- Defect class, forbidden outcome, and incident capsule captured or reported missing
+- Actor model, schedule gates, replay evidence, and input or schedule minimization
 - 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
 - Idempotency record states, fencing token, inbox or dedupe, per-key serialization, and duplicate-in-progress checks where relevant
 - Race fixes made or recommended
+- Primitive choice, happens-before graph, memory ordering, ABA, reclamation, and linearizability evidence where relevant
 - Tests or verification evidence
 - Command intents run
 - Skipped concurrency diagnostics and reasons