mustflow 2.39.1 → 2.58.1

package/templates/default/locales/en/.mustflow/skills/testability-boundary-review/SKILL.md

@@ -0,0 +1,295 @@
+---
+mustflow_doc: skill.testability-boundary-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: testability-boundary-review
+description: Apply this skill when code is created, changed, reviewed, or reported and testability needs review for hidden decision inputs, direct time or randomness, direct I/O, constructor side effects, static or singleton state, oversized private logic, branch policy sprawl, boolean mode flags, broad option objects, implicit environment or request context, void side effects, swallowed errors, log-only outcomes, cache order dependence, ORM lazy loading, transaction and external-call coupling, hidden event publication, fire-and-forget async work, real-time retry waits, nondeterministic collection order, hidden defaults, mixed validation and policy, scattered authorization, framework magic, smart controllers, conditional DTO mapping, mock-heavy classes, call-order assertions, inheritance coupling, or reflection-only tests.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.testability-boundary-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Testability Boundary Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review whether code can be forced into the important conditions needed for deterministic tests.
+
+The review question is not only "is the logic correct?" It is "can a test stop time, force failure,
+replace the external world, fix random output, run the core decision without a database, and observe
+the result without peeking through private seams?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code review, implementation, or refactor work touches business decisions, validators, services,
+  handlers, repositories, entities, jobs, workers, events, retries, caches, controllers, DTO mappers,
+  framework hooks, constructors, global state, static helpers, or tests.
+- A test would need real time, random values, UUIDs, database sessions, external APIs, files, queues,
+  mail, logs, sleeps, framework containers, reflection, broad mocks, or internal call-order assertions.
+- A class or function looks simple but hides decision inputs in environment variables, current user,
+  locale, timezone, config files, global caches, default values, static singletons, or framework
+  context.
+- A review needs to decide whether to use `dependency-injection`, `pure-core-imperative-shell`,
+  `state-machine-pattern`, `strategy-pattern`, `result-option`, `auth-permission-change`,
+  `failure-integrity-review`, `cache-integrity-review`, or `test-design-guard`.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only designing test cases or classifying RED evidence; use `test-design-guard`.
+- The task is only updating stale, duplicated, flaky, or obsolete tests; use `test-maintenance`.
+- The only issue is hidden construction of a direct external dependency; use `dependency-injection`
+  as the primary skill and this skill only for the broader testability review.
+- The main work is separating deterministic business decisions from side effects; use
+  `pure-core-imperative-shell` as the primary skill.
+- The code is a trivial pure helper with explicit inputs, deterministic output, no hidden state, and
+  no meaningful branch or side effect.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, current diff or target files, and the behavior or decision that should be testable.
+- Decision-input ledger: explicit parameters, hidden reads, time, randomness, identifiers, config,
+  environment, locale, timezone, current actor, permissions, feature flags, cache, and defaults.
+- Side-effect ledger: database, ORM lazy loading, network, filesystem, queue, mail, logs, metrics,
+  events, transactions, retries, timers, background work, and external providers.
+- Observability ledger: returned value, typed error, emitted event, state change, persisted record,
+  outbox message, public response, log-only outcome, or private reflection-only state.
+- Test friction evidence: mocks required, sleeps, framework container setup, reflection, call-order
+  assertions, real infrastructure, test ordering dependence, shared state cleanup, and existing tests.
+- Relevant command-intent contract entries for tests, lint, build, docs, release, and mustflow checks.
+
+<!-- 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 hidden-input, side-effect, observability, or test-friction
+  evidence can be reported without guessing.
+- If the review finds a concrete dependency, pure-core, failure, cache, concurrency, authorization,
+  state-machine, strategy, or test-design issue, use the narrower skill before editing that part.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Make decision inputs explicit through parameters, narrow context values, fixed clocks, fixed
+  identifier or random providers, policy objects, strategy objects, state tables, or small value
+  objects.
+- Move I/O, framework objects, caches, logs, metrics, event publication, timers, retries,
+  transactions, and background execution into shell or adapter boundaries when directly tied to
+  testability.
+- Return observable results such as values, typed errors, state transitions, domain events, effect
+  descriptions, outbox messages, or command results instead of requiring tests to inspect logs,
+  private fields, or collaborator call order.
+- Add or adjust focused tests only when they prove the reviewed testability boundary and follow
+  `test-design-guard`.
+- Do not add broad dependency bags, speculative abstractions, global test hooks, sleeps, reflection
+  helpers, or mock-only tests just to make one test pass.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Ask what the test must be able to control.
+   - Name the conditions a test should force: current time, timezone, random value, UUID, external
+     failure, retry timing, DB result, permission, locale, feature flag, cache state, event output,
+     ordering, or provider response.
+   - If those conditions cannot be controlled without real infrastructure or sleeps, testability is
+     already leaking.
+2. Find hidden decision inputs.
+   - Flag direct `new Date()`, `Date.now()`, `LocalDateTime.now()`, `System.currentTimeMillis()`,
+     `Math.random()`, UUID generation, environment reads, config reads, current-user lookups, locale,
+     timezone, global cache reads, and framework request context inside business decisions.
+   - Prefer passing captured values, a narrow time context, a fixed generator, or an explicit policy
+     input from the boundary.
+3. Split decision from contact with the outside world.
+   - A function that decides and also queries a database, calls an API, reads a file, sends mail,
+     writes a queue, or logs the only outcome forces unit tests into mini integration tests.
+   - Use `pure-core-imperative-shell` when business decisions and side effects are mixed.
+4. Inspect constructors.
+   - Constructors should accept ingredients, not start cooking.
+   - Treat constructors that connect to databases, read files, read environment, fill caches, spawn
+     threads, start timers, or perform network setup as testability hazards.
+5. Inspect static, singleton, and global state.
+   - Shared mutable state makes test order part of behavior.
+   - Look for global registries, mutable singletons, module-level caches, static config, process-wide
+     current user, and global loggers that hold test-specific state.
+6. Treat large private methods as trapped responsibility.
+   - Do not test private methods through reflection.
+   - If private logic has meaningful policy, calculation, parsing, validation, or branching, extract
+     the responsibility behind a small public or module-local boundary with explicit inputs.
+7. Count policy branches, not just branch count.
+   - Nested `if`, `switch`, `when`, or pattern matching may mean different policies are welded into
+     one function.
+   - Use strategy, rule table, state machine, or named policy object when each branch represents a
+     different reason to change or a different test matrix.
+8. Replace boolean mode flags with named concepts.
+   - Flag signatures like `process(user, true, false)`.
+   - Two or more boolean inputs create hidden modes. Use named variants, explicit option types, or
+     separate functions when modes have different behavior contracts.
+9. Shrink trash-can option and context objects.
+   - Broad `RequestOptions`, `Config`, `Context`, or dependency bags hide which fields affect the
+     result.
+   - Keep only the facts required for the decision, and give test fixtures small builders or explicit
+     values instead of giant fake objects.
+10. Make outputs observable.
+    - Void functions that update DB rows, publish events, delete caches, send logs, and call providers
+      force tests to spy on internals.
+    - Prefer returning decision results, typed errors, domain events, effect descriptions, state
+      changes, or command outcomes that shell code can execute.
+11. Do not swallow failures into logs.
+    - `catch { log.warn(...) }` with no returned failure makes tests assert log text instead of
+      behavior.
+    - Use `failure-integrity-review` or `result-option` when expected failures need to be visible as
+      values or errors.
+12. Keep cache outside the policy.
+    - If first call and second call differ because a hidden cache changed, tests become order
+      dependent.
+    - Core decisions should return the same output for the same input whether cache is present or
+      not; cache belongs in the shell or adapter.
+13. Keep ORM behavior out of unit decisions.
+    - Lazy loading, entity hooks, DB sessions, generated row types, and active-record saves can pull
+      real persistence into tests.
+    - Entities may own state and invariants, but query composition and external dependencies belong
+      at repository or service boundaries.
+14. Check transaction and external-call coupling.
+    - External API calls inside DB transactions create test and production uncertainty.
+    - Prefer local state plus outbox or effect descriptions, then execute external effects after
+      commit with idempotency.
+15. Make events visible at one boundary.
+    - Hidden event publication in the middle of a function makes tests verify every side channel.
+    - Prefer returning domain events or publishing once at a clear shell boundary.
+16. Remove fire-and-forget timing from core logic.
+    - `setTimeout`, background job launch, coroutine launch, thread start, unawaited promises, and
+      detached tasks make tests sleep.
+    - Inject a scheduler or executor, or return work descriptions so tests can run them
+      synchronously.
+17. Decouple retry, backoff, timeout, and expiration from real time.
+    - Waiting 30 seconds to prove a retry is not a useful test.
+    - Model retry policy as data or a deterministic calculator, and advance fake time in tests.
+18. Stabilize collection ordering.
+    - If order matters, code should sort with a named key.
+    - If order does not matter, tests should assert as a set or multiset rather than relying on DB,
+      map, set, or parallel iteration order.
+19. Make defaults explicit.
+    - Hidden defaults such as server timezone, default admin, default shipping, default permission,
+      default locale, default currency, and default cache policy multiply test cases silently.
+    - Put defaults at the boundary, name them, and test the fallback path deliberately.
+20. Separate input shape validation from business judgment.
+    - Email format, JSON shape, file size, or required field checks are not the same as eligibility,
+      permission, balance, quota, status, or domain invariants.
+    - Separate structural validation, authorization, and policy decisions so failure reasons can be
+      tested directly.
+21. Centralize authorization evidence.
+    - Scattered controller, service, and repository permission checks create test holes.
+    - Use `auth-permission-change` when protected actions need one policy source, denial cases, or
+      consistent server/database enforcement.
+22. Keep framework magic at the edge.
+    - Annotations, decorators, AOP, interceptors, middleware, dependency containers, ORM hooks, and
+      lifecycle callbacks should not be required to run core decision tests.
+    - A useful testability check is whether the decision can run without the framework container.
+23. Keep controllers as translators.
+    - Controllers should parse requests, call an application boundary, and map results to responses.
+    - If they own business decisions, permissions, error mapping, response formatting, and external
+      calls, tests have to fake a web server to prove a rule.
+24. Treat conditional DTO mapping as policy.
+    - Mapping code that hides fields by status, role, flag, or permission is no longer simple
+      mapping.
+    - Move the policy to a named owner and keep DTO mapping mechanical where possible.
+25. Use mocks as a design sensor.
+    - If a unit test needs more than three mocks, inspect responsibility boundaries.
+    - If it needs five or more mocks, the class is probably talking to too many collaborators.
+    - Prefer fewer, narrower ports and pure decision tests over broad mock choreography.
+26. Prefer outcome assertions over call-order assertions.
+    - Some protocols require order tests. Most business logic should be tested by result, final
+      state, emitted event, persisted command, or rejected effect.
+    - Frequent `A before B` assertions usually mean the responsibility boundary is too procedural.
+27. Prefer composition over deep inheritance for test setup.
+    - Parent constructors, protected state, template methods, and partial overrides create hidden
+      dependencies.
+    - Use composition when tests need to swap behavior or observe a small collaborator.
+28. Treat reflection-only tests as a design failure.
+    - Tests that set private fields, call private methods, or mutate hidden state through reflection
+      are using a back door.
+    - Create a real boundary for the behavior or report that the current design cannot be tested
+      naturally.
+29. Pick the smallest response.
+    - If one hidden input blocks testing, inject that one value instead of reshaping the whole module.
+    - If several smells point to the same root, name the root boundary and fix there.
+    - If changing structure is too risky now, report the exact condition that remains hard to force
+      in tests.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Important test conditions can be forced without real time, real randomness, live infrastructure,
+  sleeps, reflection, broad framework containers, or hidden global state.
+- Decision inputs are explicit or the remaining hidden inputs are named.
+- Core decision behavior has observable values, typed failures, events, effects, or state changes.
+- External I/O, transactions, retries, caches, logging, metrics, scheduling, and framework magic are
+  kept at boundary code or explicitly reported as remaining testability risk.
+- Any new or changed tests assert observable behavior rather than only mock choreography.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer focused tests that prove the newly controllable condition and observable outcome. Use
+`test-design-guard` before adding or reshaping tests.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the behavior cannot be tested without reflection, sleeps, broad mocks, or live infrastructure,
+  report the exact hidden decision input or side effect instead of claiming the testability issue is
+  solved.
+- If extracting a boundary changes behavior, stop and use `behavior-preserving-refactor` or
+  `repro-first-debug` before continuing.
+- If tests still require the framework container, report which framework dependency remains inside
+  the decision.
+- If a command fails, use `failure-triage` before further edits.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Testability boundary reviewed
+- Conditions tests must control
+- Hidden decision inputs found
+- Side effects and framework dependencies found
+- Observability gaps found
+- Mocks, sleeps, reflection, call-order, or global-state risks
+- Fixes made or recommendation
+- Tests or behavior evidence
+- Command intents run
+- Skipped checks and reasons
+- Remaining testability risk

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

@@ -0,0 +1,196 @@
+---
+mustflow_doc: skill.transaction-boundary-integrity-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: transaction-boundary-integrity-review
+description: Apply this skill when code is created, changed, reviewed, or reported and transaction boundaries, database write paths, ORM atomic blocks, unit-of-work code, lock usage, isolation levels, retry handling, rollback behavior, after-commit side effects, outbox patterns, framework transaction annotations, or transactional tests can break business invariants despite a transaction existing.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.transaction-boundary-integrity-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Transaction Boundary Integrity Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review transactions by asking whether the whole business action stays true under failure, concurrency, retries, framework behavior, and external side effects.
+
+The review question is not "is there a transaction?" It is "does the read -> decision -> write sequence, plus every side effect and retry, still preserve the invariant when another request, worker, or failure changes the timing?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code creates, changes, reviews, or reports a database transaction, ORM transaction, unit of work, repository write path, service write workflow, command handler, webhook processor, queue consumer, checkout, credit, inventory, booking, entitlement, permission, approval, status transition, or multi-step business action.
+- The risk is read -> decision -> write integrity, check-then-insert, count-before-add, row lock scope, missing durable constraints, isolation-level assumptions, retry behavior, deadlock handling, rollback behavior, transaction propagation, nested transaction semantics, savepoints, after-commit side effects, outbox or inbox boundaries, external API calls inside transactions, or tests that hide commit behavior.
+- Code or docs claim a path is atomic, transactional, serialized, locked, retry-safe, rollback-safe, isolated, idempotent, durable, committed, or protected from concurrent requests.
+- A transaction-related review needs a focused integrity pass before deeper database-engine, race-condition, backend-reliability, payment, credit-ledger, or state-machine review.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only query latency, index fit, plan shape, projection, pagination, or N+1 behavior; use `database-query-bottleneck-review`.
+- The task is only general stale shared state or lock ordering outside a database or unit-of-work boundary; use `race-condition-review` or `concurrency-invariant-review`.
+- The task is primarily exception honesty, swallowed errors, false success, fallback defaults, or public error shape; use `failure-integrity-review`.
+- The task is primarily retries, queue reliability, provider deadlines, health checks, outbox processing, or operational failure handling; use `backend-reliability-change`.
+- The task is payment, credit, wallet, or ledger specific and the transaction issue is only one part of money-event integrity; use `payment-integrity-review` or `credit-ledger-integrity-review` first.
+- The transaction is a tiny single-row write with no prior decision, no concurrency-sensitive invariant, no external side effect, no retry, and no framework propagation risk.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Business invariant: balance cannot go negative, member count cannot exceed a limit, email must be unique, one coupon can be redeemed once, one order can be fulfilled once, status transitions must be legal, or equivalent rule.
+- Transaction boundary: where the transaction starts and ends, which repository, ORM session, connection, data source, transaction manager, isolation level, propagation mode, savepoint, and lock scope are active.
+- Decision ledger: reads, existence checks, counts, predicate checks, business validations, authorization checks, state reads, and the writes or side effects that depend on them.
+- Durable guard evidence: unique constraints, exclusion constraints, conditional updates, version columns, row locks, parent-row locks, predicate locking, atomic upsert, idempotency records, outbox or inbox records, and affected-row checks.
+- Framework behavior: Spring `@Transactional`, `rollbackFor`, self-invocation, `readOnly`, `REQUIRES_NEW`, `NESTED`, rollback-only, `UnexpectedRollbackException`, Django `atomic()`, `transaction.on_commit()`, SQLAlchemy `Session`, Hibernate flush and `@Version`, or local equivalents.
+- Side-effect ledger: email, cache invalidation, queue publish, message ack, HTTP API call, payment provider call, object storage, file upload, search indexing, notification, analytics, and any after-commit callback.
+- Failure and retry evidence: `serialization_failure`, `deadlock_detected`, optimistic-lock failure, timeout, unknown external outcome, retry budget, idempotency key, compensation, reconciliation, and manual recovery.
+- Test evidence: concurrency tests, transactional tests, commit-time constraint tests, after-commit callback tests, query-count tests, framework integration 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 invariant, isolation, lock, propagation, side-effect, retry, or test evidence can be reported without guessing.
+- Existing local patterns for transactions, unit of work, idempotency, outbox, locks, optimistic locking, retry classification, and transactional tests have been searched before adding new shapes.
+- If the transaction crosses money, authorization, personal data, multi-tenant data, or durable events, also apply the relevant payment, credit, security, database, backend, API, state-machine, or failure skill.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Move the whole read -> decision -> write sequence into the correct transaction, replace app-only checks with durable constraints, add atomic upsert or conditional updates, check affected row counts, add version checks, lock the right row before the decision, narrow transaction scope, and move external side effects to after-commit or outbox patterns when local style supports it.
+- Add retry classification for serialization failures, deadlocks, optimistic-lock failures, and unknown external outcomes only when the full transaction or command can be retried idempotently.
+- Add focused tests for duplicate concurrent inserts, count-limit races, rollback behavior, after-commit behavior, commit-time constraints, transaction propagation, savepoint behavior, optimistic locking, and external side-effect ordering when configured tests can exercise them.
+- Do not add broad SERIALIZABLE, distributed locks, `SELECT ... FOR UPDATE`, `SKIP LOCKED`, `REQUIRES_NEW`, retries, or after-commit callbacks as magic fixes without naming the invariant, lock target, failure behavior, and side-effect ordering.
+- Do not trade correctness, authorization, tenant isolation, idempotency, auditability, or user-visible truth for shorter code or a narrower transaction.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the business invariant before judging the transaction. If the invariant cannot be stated, the transaction cannot be reviewed.
+2. Draw the decision ledger.
+   - Mark every read, `exists()`, `count`, `findBy`, status check, balance check, permission check, uniqueness check, and validation.
+   - Mark the write, insert, update, delete, publish, send, cache change, and response that depends on each decision.
+   - The true boundary is read -> decision -> write, not only the final `UPDATE`.
+3. Reject app-only check-then-act for durable facts.
+   - `exists()` then `insert()` needs a unique constraint, atomic upsert, insert-or-ignore, or equivalent durable guard.
+   - `count < limit` then add may need a parent row lock, counter row, conditional update, exclusion constraint, SERIALIZABLE with retry, or another durable single-writer authority.
+   - "No row found" is not locked by `SELECT ... FOR UPDATE`; absent future rows need constraints, parent locks, predicate protection, or atomic create.
+4. Check lock target and lock timing.
+   - Pessimistic locks are most useful when acquired before the business decision.
+   - A lock after reading and validating can protect the write while leaving the decision stale.
+   - PostgreSQL row locks do not block ordinary reads. Do not assume `FOR UPDATE` makes the row invisible.
+   - `SKIP LOCKED` intentionally skips locked rows and can produce an incomplete view; use it for queue claiming, not ordinary consistency checks.
+5. Check isolation-level assumptions by engine and framework.
+   - READ COMMITTED does not mean one stable world for the whole transaction.
+   - PostgreSQL and MySQL InnoDB REPEATABLE READ differ, especially when locking reads or writes mix with ordinary reads.
+   - SERIALIZABLE is not a global mutex. It can abort the transaction and require a full retry.
+   - Report engine-specific uncertainty instead of claiming isolation behavior from memory.
+6. Review full-transaction retry semantics.
+   - Retry the full transaction or command decision, not only the last failed statement.
+   - Treat `serialization_failure`, `deadlock_detected`, optimistic-lock failure, lock timeout, and unknown provider outcome as separate categories.
+   - Retrying without idempotency can duplicate side effects; not retrying serialization failures can surface false 500s for normal concurrency.
+7. Review rollback triggers and swallowed exceptions.
+   - Frameworks often decide rollback from whether an exception escapes the transactional boundary.
+   - Catching inside the transaction and returning success can commit partial failure.
+   - Spring defaults roll back on runtime exceptions and errors, not every checked exception; review `rollbackFor` and local rules.
+8. Review transaction proxy and propagation behavior.
+   - Spring self-invocation can bypass `@Transactional` proxy behavior.
+   - `readOnly` is usually a hint, not a guaranteed write blocker.
+   - Isolation declarations usually apply only when a new transaction starts.
+   - Inner rollback-only markers can make an outer `REQUIRED` commit fail with `UnexpectedRollbackException`.
+   - `REQUIRES_NEW` commits independently and consumes another connection while the outer transaction may still hold resources.
+   - `NESTED` is typically a savepoint, not an independent commit.
+9. Review Django, SQLAlchemy, and Hibernate lifecycle traps when relevant.
+   - Nested Django `atomic()` blocks do not make inner work durable if an outer block rolls back; `transaction.on_commit()` runs only after a successful outer commit.
+   - SQLAlchemy `Session` can begin transactions implicitly; absence of an explicit `begin` is not proof there is no transaction.
+   - Hibernate flush is not commit. Flush can occur before commit and before queries, so constraint failures or SQL effects may appear earlier than code order suggests.
+   - Hibernate `@Version` or equivalent optimistic lock checks are needed for long user think-time updates where last writer would otherwise win.
+10. Move external side effects out of the transaction boundary.
+    - Email, cache eviction, queue publish, HTTP API calls, payment provider calls, object storage writes, file uploads, and search indexing do not roll back with the database.
+    - Prefer after-commit hooks for non-critical callbacks and outbox records for durable side effects that must eventually happen.
+    - Remember that an after-commit callback failure does not roll back an already committed database transaction.
+11. Review transaction width and resource pressure.
+    - Do not hold locks or connections across HTTP API calls, file uploads, sleeps, large loops, slow calculations, logging sinks, JSON serialization, queue waits, or user-controlled waits.
+    - Timeouts do not undo already-sent external effects.
+    - `REQUIRES_NEW`, nested service calls, and transaction-per-item loops can exhaust connection pools.
+12. Review multi-database and transaction-manager scope.
+    - A transaction annotation or helper may cover only one data source, ORM session, connection, or transaction manager.
+    - Cross-database updates, external services, caches, search indexes, queues, and object storage need outbox, saga, compensation, reconciliation, or manual recovery rather than pretend single-transaction atomicity.
+13. Review advisory and distributed locks.
+    - PostgreSQL session-level advisory locks can survive rollback and require release or session end.
+    - Transaction-level advisory locks release at transaction end and are usually safer for short critical sections.
+    - Distributed locks need durable backstops such as fencing tokens, idempotency keys, conditional writes, unique constraints, or state transitions.
+14. Review transaction tests with suspicion.
+    - Spring transactional tests commonly roll back after each test.
+    - Django `TestCase` wraps tests in transactions and may not run real commit behavior or `on_commit()` callbacks.
+    - Tests that never commit can miss commit-time constraints, after-commit callbacks, lock behavior, deadlocks, serialization failures, and pool pressure.
+15. Check grep bait near the transaction.
+    - Review code around `exists`, `count`, `findBy`, `save`, `flush`, `catch`, `rollbackFor`, `REQUIRES_NEW`, `NESTED`, `readOnly`, `FOR UPDATE`, `SKIP LOCKED`, `on_commit`, `afterCommit`, `@Async`, `Executor`, `RestTemplate`, `WebClient`, `send`, `publish`, and `cache.evict`.
+    - These terms are not bugs by themselves. They are anchors for read-decision-write, propagation, external side-effect, and rollback review.
+16. Label evidence honestly.
+    - Static review can identify transaction boundary risk but cannot prove concurrency safety.
+    - Engine docs, framework docs, plan output, integration tests, and production traces are stronger evidence only when they match the repository version and workload.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The business invariant, transaction boundary, decision ledger, durable guard, side-effect ledger, retry rule, and test evidence are explicit.
+- App-only `exists()`/`count` checks, stale read -> decision -> write sequences, row-lock gaps, isolation assumptions, swallowed rollback triggers, propagation surprises, premature side effects, wide transactions, connection-pool pressure, multi-database drift, advisory-lock scope, and transactional-test blind spots are fixed or reported.
+- External side effects are after commit, outbox-backed, idempotent, compensatable, or explicitly marked as manual recovery risk.
+- Correctness, authorization, tenant isolation, idempotency, ordering, auditability, and user-visible truth remain intact or are reported as tradeoffs.
+- Transaction safety claims are backed by configured evidence, representative framework or database 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 transaction boundary and synchronized template surfaces. Do not infer raw database shells, live lock tests, load tests, chaos tests, provider calls, server processes, watcher processes, or package-manager 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 transaction invariant it exercised before editing again.
+- If the invariant, transaction manager, isolation level, propagation mode, or durable guard is unknown, report static risk instead of claiming the transaction is safe.
+- If a safe fix requires a schema constraint, engine-specific isolation change, outbox worker, idempotency store, saga, compensation path, or provider reconciliation outside the current scope, report the missing durable boundary.
+- If deterministic concurrency or commit-time proof is not configured, report the missing manual evidence and complete the configured checks that are available.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Transaction boundary reviewed
+- Business invariant and decision ledger
+- Durable guard, lock target, isolation, retry, rollback, propagation, savepoint, framework lifecycle, external side-effect, transaction width, multi-database, advisory or distributed lock, and transactional-test findings
+- Transaction-boundary fix made or recommended
+- Evidence level: configured-test evidence, framework evidence, database evidence, static review risk, manual-only, missing, or not applicable
+- Command intents run
+- Skipped transaction diagnostics and reasons
+- Remaining transaction-boundary integrity risk