mustflow 1.15.97

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

@@ -0,0 +1,193 @@
+---
+mustflow_doc: skill.adapter-boundary
+locale: en
+canonical: true
+revision: 3
+lifecycle: mustflow-owned
+authority: procedure
+name: adapter-boundary
+description: Apply this skill when external systems, protocols, SDKs, databases, webhooks, queues, files, caches, framework requests or responses, AI models, browser storage, or provider data cross into or out of core logic and need ports, adapters, translation, error mapping, timeout, retry, idempotency, security, or observability boundaries.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.adapter-boundary
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Adapter Boundary
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep external-world language, protocols, failures, and operational concerns out of core logic. Core logic speaks in internal use-case and domain terms; adapters translate external requests, responses, rows, messages, errors, identities, and provider behavior at the boundary.
+
+This skill is not just a wrapper pattern. A good adapter boundary absorbs provider details, validates or maps untrusted input, classifies failures, applies timeouts and retry policy, preserves idempotency where needed, and records safe observability evidence without leaking secrets or personal data.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code receives input from HTTP, CLI, webhooks, message queues, scheduled jobs, browser events, uploaded files, external databases, or external APIs.
+- Code calls external APIs, payment providers, email or SMS providers, file storage, object storage, databases, caches, search engines, analytics, AI models, queues, or browser storage.
+- Provider SDK types, framework request or response objects, database rows, external event objects, raw model responses, or provider error types are visible in domain, application, service, or use-case code.
+- A new or changed port, repository, gateway, provider module, controller, worker, webhook handler, mapper, or integration test is needed.
+- The boundary needs timeout, retry, rate-limit, idempotency, signature verification, duplicate handling, logging, metrics, redaction, or provider-version decisions.
+- An optional external integration may be disabled and needs either a safe neutral adapter or an explicit disabled result without leaking provider absence inward.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is a pure calculation, value object, internal formatter, or data-only refactor with no external boundary.
+- The only problem is hidden construction or global lookup of a dependency; use `dependency-injection` first, then return here only if external data, errors, or protocol behavior also need a boundary.
+- The operation coordinates several already-translated ports, repositories, queues, caches, or providers behind one caller-facing workflow; use `facade-pattern` for that high-level entry point while keeping this skill for each external boundary.
+- The task is a disposable one-off script that is not imported, repeated, tested, used in production, or connected to external systems.
+- The repository already has a more specific local integration skill that fully covers the boundary.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The external system or protocol and whether it is inbound, outbound, or both.
+- The internal use case, domain action, or read model that should receive translated data.
+- Existing local patterns for ports, adapters, repositories, controllers, workers, mappers, result types, retries, idempotency, logging, and tests.
+- Provider-specific risk: write effects, duplicate delivery, unknown statuses, money, time, identifiers, secrets, personal data, files, untrusted URLs, rate limits, or provider version changes.
+- Relevant command-intent contract entries for tests, builds, docs, template checks, release checks, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- The boundary direction and owner are clear enough to avoid putting provider names or external protocol terms into core logic.
+- If the local layout is unfamiliar, use `pattern-scout` or `codebase-orientation` before introducing new folders or naming conventions.
+- If the change also introduces hidden collaborators or concrete construction, use `dependency-injection` for that part of the work.
+- If the integration is optional and disabled by explicit configuration, use `null-object-pattern` only when the neutral behavior is safe and honest; required providers must fail closed.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Define narrow internal ports in the consuming application or domain language.
+- Add inbound adapters that parse, verify, validate, translate, and map protocol results.
+- Add outbound adapters that call providers and translate requests, responses, errors, identifiers, and operational metadata.
+- Add mapper, error-mapper, fixture, fake-port, contract-test, and adapter-test files directly needed by the boundary.
+- Add or update assembly-root wiring when a new adapter implementation is introduced.
+- Do not copy provider APIs into ports, return provider SDK objects, expose database rows as domain objects, or add a broad catch-all `ExternalAdapter`.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the boundary.
+   - Inbound: HTTP route, controller, webhook, CLI command, queue consumer, scheduler, browser event, uploaded file, or external data import.
+   - Outbound: provider SDK, HTTP API, database, cache, file storage, search engine, message publisher, email/SMS/push provider, payment provider, AI model, or browser storage.
+2. Name the internal capability in business language. Use names such as `PaymentGateway`, `EmailSender`, `ObjectStorage`, `UserStore`, `OrderReader`, `SummaryGenerator`, or `EventPublisher`. Keep provider names such as Stripe, Prisma, SendGrid, S3, OpenAI, or Redis inside adapter implementation names.
+3. Design the port from the consumer's need, not from the provider's API.
+   - Keep ports small and split unrelated reasons to change.
+   - Use internal input and output types only.
+   - Do not include SDK types, ORM model types, HTTP request objects, provider response objects, or provider error classes.
+4. Build inbound adapters as translators, not business-rule containers.
+   - Parse and validate external input.
+   - Verify signatures, authentication evidence, request size, file constraints, and allowed URL or host rules where relevant.
+   - Extract only the values needed by the use case.
+   - Map use-case results back to the protocol response.
+   - Keep pricing, permission decisions, state transitions, inventory policy, subscription policy, and other business rules in the application or domain layer.
+5. Build outbound adapters as provider translators, not pass-through wrappers.
+   - Create provider requests from internal input.
+   - Set timeouts and retry policy where appropriate.
+   - Pass idempotency keys for writes when the provider supports them.
+   - Distinguish timeout, network error, rate limit, authentication failure, authorization failure, invalid request, business rejection, provider outage, and unknown provider error.
+   - Return internal `Result` values or local error types instead of throwing provider errors for expected failures.
+   - For optional disabled integrations, return an honest skipped or disabled outcome, or wire a safe null object at the assembly boundary. Do not return fake provider success.
+6. Convert external data immediately at the boundary.
+   - Map provider responses, database rows, queue messages, file metadata, model outputs, and browser storage values into internal types.
+   - Keep external identifiers distinct from internal identifiers.
+   - Represent money in integer minor units and explicit currency.
+   - Convert dates and times explicitly according to the repository's time policy.
+   - Copy only fields that internal code actually uses.
+7. Separate mappers when translation grows.
+   - Split request mapping, response mapping, error mapping, and fixture builders once they become non-trivial or repeated.
+   - Keep provider-version differences inside adapter or mapper files.
+8. Treat databases, caches, and queues as external systems.
+   - Core logic should use stores, readers, writers, or publishers rather than raw clients.
+   - Database rows are persistence shapes, not domain objects.
+   - Queue messages and integration events are external envelopes until parsed and translated.
+   - Cache keys, time-to-live values, invalidation rules, and stale-data policy must be explicit.
+9. Keep database transactions and external side effects separate by default.
+   - Do not call external APIs inside database transactions unless a local rule explicitly justifies the risk.
+   - Use explicit states, an outbox, an action ledger, or a reconciliation path when database changes and external effects must be coordinated.
+10. Harden webhooks and duplicate delivery.
+    - Verify signatures before trusting payloads.
+    - Preserve the raw body or safe raw reference when needed for verification and replay.
+    - Use provider event identifiers or action keys to prevent duplicate effects.
+    - Translate external event types into internal commands or events before calling the use case.
+11. Keep AI model boundaries explicit.
+    - Keep provider request format, model name, temperature, token limits, safety settings, and raw response parsing inside adapter or configuration code.
+    - Validate structured output before returning it.
+    - Return internal purpose-level outputs such as summaries, classifications, recommendations, or extracted fields.
+12. Make observability safe and useful.
+    - Log adapter name, provider, operation, correlation id, safe idempotency-key hash, provider request id, duration, retry count, outcome, and local error kind when available.
+    - Do not log API keys, tokens, card data, passwords, identity numbers, raw personal data, full email bodies, full payment requests, full provider responses, or unredacted payloads.
+    - Add metrics for latency, failures, retries, rate limits, duplicate handling, and ambiguous or unknown provider outcomes when the boundary is operationally important.
+13. Test at the right layer.
+    - Use fake ports in use-case tests; they should not call real external systems.
+    - Test adapters with provider fixtures, mock clients, or local test doubles for request mapping, response mapping, error mapping, timeout, retry, idempotency, redaction, and duplicate handling.
+    - Add contract or sandbox tests for critical providers when local fixtures cannot catch provider drift.
+14. Verify with the narrowest configured command intents that cover changed source, tests, templates, docs, release metadata, and mustflow checks.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Core logic has no provider SDK imports, framework request or response objects, ORM clients, database rows, provider response objects, or provider error classes.
+- Ports are named in internal business language and expose only internal input, output, and error types.
+- Inbound adapters validate and translate before calling use cases.
+- Outbound adapters translate internal requests, provider responses, and provider failures before returning.
+- Timeouts, retry policy, idempotency, duplicate handling, security checks, and redacted observability are explicit where the risk requires them.
+- Tests cover core behavior through fakes and adapter behavior through mapping, error, and boundary tests.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured test or build intent that proves the affected boundary. Use documentation and release checks when skill routes, templates, public docs, package metadata, or installed-file surfaces change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a port starts mirroring a provider API, narrow it to the consuming use case and move provider details back into the adapter.
+- If an adapter becomes a pass-through wrapper, add explicit mapping and error translation or remove the false boundary.
+- If an adapter begins making business decisions, move the policy into the application or domain layer.
+- If timeout, retry, or idempotency behavior cannot be made safe, fail closed and report the remaining manual or reconciliation requirement.
+- If sensitive data appears in logs, fixtures, metrics, receipts, or test output, stop and route the sensitive surface through the repository's security and privacy review path.
+- If the provider behavior is unknown or drift-prone, keep claims local to verified fixtures or contract evidence and report what still needs live verification.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary classified
+- Internal port or use-case input selected
+- Provider or protocol details contained
+- Inbound validation and translation handled
+- Outbound request, response, and error mapping handled
+- Timeout, retry, idempotency, and duplicate behavior handled or explicitly deferred
+- Security and redaction surfaces checked
+- Tests, fixtures, fakes, or contract checks added or reused
+- Command intents run
+- Skipped checks and reasons
+- Remaining boundary leakage or provider risk

package/templates/default/locales/en/.mustflow/skills/artifact-integrity-check/SKILL.md

@@ -0,0 +1,121 @@
+---
+mustflow_doc: skill.artifact-integrity-check
+locale: en
+canonical: true
+revision: 3
+lifecycle: mustflow-owned
+authority: procedure
+name: artifact-integrity-check
+description: Apply this skill when a task creates, replaces, packages, references, or reports on generated artifacts or binary assets.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.artifact-integrity-check
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_release
+    - build
+    - mustflow_check
+---
+
+# Artifact Integrity Check
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Ensure generated artifacts, packaged files, media assets, reports, and downloadable outputs exist, match their intended source, and are not reported as verified without evidence.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A task creates, replaces, moves, deletes, packages, or references an artifact or binary asset.
+- A final report claims that a file was generated, optimized, exported, included in a package, or safe to use.
+- A build or packaging step writes files that may be stale, missing, oversized, or excluded from distribution.
+- A document, README, manifest, or test points to a generated file or asset path.
+- A release, package publish, workflow, or trusted publishing path can modify artifacts before publication.
+- A code-scanning or workflow-security alert involves published artifacts, uploaded artifacts, SARIF files, package tarballs, Pages output, cache contents, or release credentials.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is source-only and does not mention generated, packaged, exported, or binary files.
+- Another narrower skill already verifies the exact artifact path, package surface, and output claim.
+- The user explicitly asks for a conceptual plan without producing or validating files.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Artifact paths or expected output locations.
+- Source files, generation steps, or package rules that should produce the artifact.
+- Any size, format, hash, manifest, package, or documentation expectation.
+- Relevant command-intent contract entries for build, packaging, validation, or asset optimization.
+- Workflow steps, action references, publish credentials, OIDC permissions, package registry identity, and pre-publish lifecycle scripts when artifacts are released.
+- Code-scanning artifact paths, upload steps, credential scope, and whether the uploaded artifact can contain checkout credentials, generated secrets, or tampered package contents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update only the artifact, source reference, manifest, package metadata, test, or documentation needed to keep the artifact claim true.
+- Do not commit generated caches, transient build output, or local state unless the repository explicitly versions that artifact.
+- Do not invent hashes, dimensions, file sizes, export results, or package inclusion evidence.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. List each artifact or binary asset affected by the task and the claim being made about it.
+2. Identify whether the artifact is source-controlled, generated, packaged, ignored local state, or external output.
+3. Check that source references, manifests, package includes, docs links, and tests point to the same path and format.
+4. For publish workflows, inspect code that runs before artifact publication. Treat mutable third-party actions, lifecycle scripts, package manifests, and generated files as artifact mutation points.
+5. For workflow artifact alerts, check whether checkout credentials persist into the workspace, whether artifacts are uploaded after untrusted code runs, and whether the job permission is broader than the artifact operation needs.
+6. Verify existence, format, and expected inclusion using the narrowest configured command intent available.
+7. If a generated artifact is stale or missing, regenerate it only through a configured command intent or report the missing command.
+8. If an artifact should not be versioned, ensure the final report does not imply that it was committed or distributed.
+9. Report artifact evidence precisely: path checked, command intent run, and any remaining unverified attribute.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Every artifact claim in code, docs, manifests, tests, and the final report is backed by observed evidence or explicitly marked unverified.
+- Generated and ignored outputs are not treated as project truth unless the repository declares them versioned.
+- Package or distribution claims are verified with the relevant configured intent when available.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_release`
+- `build`
+- `mustflow_check`
+
+Use a narrower configured asset or documentation validation intent when it better covers the artifact.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the artifact cannot be generated or inspected, report the missing tool, command intent, or source file.
+- If package inclusion and source references disagree, fix the manifest or docs before reporting the artifact as shipped.
+- If a privileged release workflow runs mutable actions or repository-controlled code before publishing, report the artifact integrity risk or isolate and pin the publish path before claiming the package is trustworthy.
+- If an artifact is too large, stale, or in the wrong format, report the issue and avoid claiming it is production-ready.
+- If verification would require external services or unavailable tools, stop at that boundary and name the unchecked artifact property.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Artifact paths checked
+- Artifact source or generation path
+- Inclusion, format, or size evidence
+- Command intents run
+- Skipped artifact checks and reasons
+- Remaining artifact integrity risk

package/templates/default/locales/en/.mustflow/skills/behavior-preserving-refactor/SKILL.md

@@ -0,0 +1,182 @@
+---
+mustflow_doc: skill.behavior-preserving-refactor
+locale: en
+canonical: true
+revision: 11
+lifecycle: mustflow-owned
+authority: procedure
+name: behavior-preserving-refactor
+description: Apply this skill when refactoring should reduce change cost while preserving existing behavior and keeping behavior changes separate.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.behavior-preserving-refactor
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Behavior-Preserving Refactor
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Guide refactoring that lowers future change cost without silently changing runtime behavior.
+
+Refactoring is not cleanup for aesthetics. It is a controlled way to make code easier to understand, test, and change while keeping bug fixes, feature work, and behavior changes separate.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- The user asks to refactor, clean up, reorganize, simplify, split, extract, rename, remove duplication, or improve structure.
+- A planned change risks mixing renames, moves, extractions, deduplication, bug fixes, and feature behavior in one diff.
+- Existing code is hard to change because responsibilities, names, branches, dependencies, or tests are unclear.
+- Existing inheritance, base classes, abstract classes, template methods, protected state, or subclass variants make behavior harder to test or change.
+- Existing handlers, repositories, adapters, jobs, or services mix business decisions with database access, network calls, logging, current time, generated identifiers, randomness, environment reads, or framework objects.
+- Existing controllers, handlers, jobs, or services mix one state-changing intent with authorization, transactions, idempotency, audit logs, outbox events, retries, concurrency checks, and external side effects.
+- Existing controllers, handlers, workers, command handlers, or services repeat the same multi-step subsystem sequence and should move behind a stable facade without changing behavior.
+- Existing lifecycle state changes are scattered across direct assignments, handlers, repositories, jobs, UI checks, SQL conditions, or provider callbacks.
+- Existing code repeats presence checks for optional collaborators such as loggers, analytics clients, caches, optional notifications, or no-op processors.
+- The task touches legacy or weakly tested code and needs a safer refactoring order.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The requested task is primarily a bug fix or failure diagnosis; use `repro-first-debug` first.
+- The change introduces new folders, modules, routing, data models, or external service boundaries before refactoring scope is clear; use `structure-discovery-gate`.
+- The task is only to review an already completed diff; use `diff-risk-review` or `code-review`.
+- The target code is about to be deleted, the requirement is still unclear, or the next step requires a product decision rather than a refactor.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The refactoring goal, target files or area, and the concrete pain being reduced.
+- Current behavior evidence, such as tests, examples, fixtures, command output, or observed input and output cases.
+- Existing local patterns for naming, file boundaries, dependencies, and tests.
+- Current changed-file list when the worktree is already dirty.
+- Relevant command-intent contract entries for verification.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- The expected behavior to preserve is known, or the unknown behavior has been reported before edits begin.
+- If the area is unfamiliar, `codebase-orientation` or `pattern-scout` has been used to avoid inventing a parallel structure.
+- If tests are absent or weak, the first safe step is to add characterization coverage, capture input and output cases, or explicitly report the verification gap.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Rename unclear identifiers when the rename improves call-site meaning without changing behavior.
+- Extract small functions, policies, or helpers when they have a clear concept, inputs, outputs, and test value.
+- Flatten conditional flow when it preserves the same guard conditions and error behavior.
+- Separate responsibilities, dependencies, or side effects in the smallest useful step.
+- Move domain decisions toward pure functions or narrow policy objects, and keep I/O, clocks, network calls, process spawning, persistence, and logging in the imperative edge.
+- Add or update tests that preserve current behavior or make the refactoring safe.
+- Do not mix behavior changes, bug fixes, new features, broad formatting churn, or unrelated cleanup into the refactor.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+Before broad hotspot scans, compress candidates before reading files.
+
+- Exclude generated files, bundled files, lock files, dependency directories, large fixtures, snapshots, build outputs, minified files, and source maps before ranking candidates.
+- Use `[refactoring.hotspots]` preferences as scan limits: `large_file_candidate_kb` for the first size signal, `history_days` for recent change and bug-fix history, and the candidate limits for how many files to inspect at each depth.
+- Prefer overlapping low-cost signals over a single metric: size, recent change frequency, bug-fix history, import/export count, TODO/FIXME/HACK count, type or lint bypasses, missing nearby tests, and architecture-boundary imports.
+- Treat strong combinations as higher priority, such as large files with frequent changes and no tests, small security/payment/permission files with repeated bug fixes, large React client components with many effects, and API/controller files that mix validation, authorization, business logic, database access, and response formatting.
+- Do not read every candidate. Keep the first pass to the configured primary limit, narrow to the configured structure-review limit, and read full file contents only for the configured full-file limit.
+- When opening a candidate, inspect imports, exports, declarations, TODO or type-bypass neighborhoods, and the largest or most branch-heavy function before reading the full file.
+
+1. Diagnose whether refactoring is needed.
+   - Name the real problem: change cost, unclear responsibility, repeated bug risk, test difficulty, dependency coupling, or confusing flow.
+   - Do not refactor only because code looks long, old, or stylistically uneven.
+2. Identify behavior that must stay fixed.
+   - Prefer existing tests or examples.
+   - If coverage is missing, record representative input and output cases or add focused characterization tests before structural edits.
+   - Treat suspected bugs as separate follow-up fixes unless the user explicitly asks to change behavior.
+3. Choose the safest refactoring ladder.
+   - Start with names and local clarity.
+   - Then extract small concepts with clear inputs and outputs.
+   - Then flatten conditions or isolate policies.
+   - Then remove duplication only when the duplicated code changes for the same reason.
+   - Move files, introduce abstractions, or split modules only after local behavior is easier to see.
+4. Check duplication before merging code.
+   - Keep duplication when code only looks similar or will change for different reasons.
+   - Prefer common code only when it represents the same rule, simplifies call sites, and does not add parameter or branch complexity.
+   - Prefer explicit duplication over a misleading abstraction.
+5. Check extracted functions and names.
+   - Extract only concepts that can be named precisely.
+   - Avoid vague names such as `process`, `handle`, `do`, or `helper` unless they match established local style.
+   - Boolean functions should read naturally at call sites and reveal the condition being tested.
+6. Prefer the low-ceremony structural pattern that matches the pain:
+   - Dependency injection when direct construction, global lookup, or hidden imports of tools, clients, clocks, file systems, processes, loggers, configuration, random generators, identifiers, queues, or external SDKs makes behavior hard to test. Use `dependency-injection` before editing that boundary.
+   - Adapter or translator boundaries when external formats leak into core logic. Use `adapter-boundary` when provider data, protocols, errors, timeouts, retries, idempotency, security, or observability are part of the boundary.
+   - Composition over inheritance when behavior can be assembled from small explicit collaborators. Use `composition-over-inheritance` before editing `extends`, base classes, abstract classes, template methods, protected state, mixins, or subclass combinations.
+   - Command pattern when a state-changing user or system intent needs a traceable execution unit with explicit payload, context, authorization, transaction boundary, idempotency, outbox, audit, retry, or concurrency behavior. Use `command-pattern` before editing that execution unit.
+   - Pure core with an imperative shell when business decisions, validation, authorization, pricing, eligibility, state transitions, or domain events are mixed with I/O, time, generated identifiers, randomness, environment reads, or framework objects. Use `pure-core-imperative-shell` before editing that split.
+   - State machine pattern when status, state, phase, step, or stage controls allowed behavior and transitions are scattered or assigned directly. Use `state-machine-pattern` before editing lifecycle transitions.
+   - Strategy pattern when repeated branches choose among interchangeable algorithms, policies, pricing rules, scoring methods, provider choices, or feature variants that share one purpose. Use `strategy-pattern` before editing that strategy family.
+   - Result and Option values when expected failures, meaningful absence, null returns, thrown business failures, or ambiguous success flags make behavior hard to follow. Use `result-option` before editing that return-shape contract.
+   - Null Object pattern when repeated nullable checks around an optional collaborator can be replaced by a same-interface neutral implementation without hiding required failures. Use `null-object-pattern` before editing that optional dependency boundary.
+   - Injected time context when current time affects preserved behavior.
+7. Handle conditional complexity by finding the policy.
+   - Use early exits for simple guard conditions when they preserve behavior.
+   - Separate state, type, permission, and exceptional-rule branches when they are mixed.
+   - Avoid replacing clear branches with a strategy object, table, or abstraction before the policy boundary is proven.
+8. Keep commits and reports reviewable.
+   - Separate renames, moves, extractions, deduplication, tests, and behavior changes when possible.
+   - If behavior changes are discovered, stop and report them as a separate fix path.
+9. Verify with the narrowest configured command intents that cover the changed code and contract surfaces.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Existing behavior is preserved or any behavior change is clearly separated and reported.
+- The refactor has a named purpose tied to lower change cost, lower defect risk, or better testability.
+- The diff is small enough for a reviewer to distinguish mechanical changes from semantic changes.
+- Tests or verification evidence cover the behavior most likely to regress.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Choose the narrowest configured test or build intent that proves the refactored behavior. Use documentation and release checks only when the refactor changes public docs, templates, schemas, package metadata, or release-sensitive surfaces.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If current behavior cannot be observed, stop before broad restructuring and report the missing safety evidence.
+- If a refactor uncovers a bug, keep the refactor behavior-preserving and propose the fix as a separate change.
+- If deduplication creates more options, branches, or vague names, undo or postpone that abstraction.
+- If tests fail after a supposedly behavior-preserving edit, diagnose the behavior difference before continuing.
+- If the next useful step is a large module move or public boundary change, use `structure-discovery-gate` and `contract-sync-check` before proceeding.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Refactoring goal
+- Behavior preservation evidence
+- Structural risk signals found
+- Facade extraction used or intentionally avoided
+- Refactoring ladder chosen
+- Structural pattern used or intentionally avoided
+- Changes made or analysis-only recommendation
+- Behavior changes intentionally excluded
+- Verification intents run
+- Skipped checks and reasons
+- Remaining risks or follow-up fix path

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

@@ -0,0 +1,115 @@
+---
+mustflow_doc: skill.code-review
+locale: en
+canonical: true
+revision: 4
+lifecycle: mustflow-owned
+authority: procedure
+name: code-review
+description: Apply this skill when reviewing code changes, scope, risks, or verification gaps.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.code-review
+  command_intents:
+    - test
+    - test_related
+    - test_audit
+    - lint
+---
+
+# Code Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Verify that a change aligns with the request and ensure that no behavioral risks or verification gaps persist.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code changes, diffs, pull requests, or potential regression risks require review.
+- The primary objective is risk assessment rather than implementing new behavior.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task involves only wording, translation, or formatting changes.
+- No changed files or diffs are available for review.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Modified files or diffs
+- User-specified review criteria
+- `AGENTS.md`
+- `.mustflow/docs/agent-workflow.md`
+- `.mustflow/config/commands.toml`
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Required inputs are available, or missing inputs can be reported without guessing.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep edits within the scope described by this skill, the user request, and the matching route in `.mustflow/skills/INDEX.md`.
+- Do not broaden command permission, invent project facts, or change unrelated workflow files.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Review the list of modified files.
+2. Identify any unrelated or extraneous edits.
+3. Assess the impact on behavior, configuration, commands, and documentation.
+4. Review test relevance:
+   - missing tests for new functionality
+   - obsolete tests for removed functionality
+   - redundant tests that fail to address new risks
+   - weakened or insufficient assertions
+   - snapshot updates lacking a clear rationale
+   - tests that inadvertently reintroduce removed behavior
+5. Verify the existence of relevant command intents.
+6. Document findings categorized by severity.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The expected output can be produced with clear evidence, executed command intents, skipped checks, and remaining risks.
+- Any missing command intent, unknown input, or authority conflict is reported instead of hidden.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Follow `.mustflow/docs/agent-workflow.md#command-execution-policy`.
+
+Related command intents:
+
+- `test`
+- `test_related`
+- `test_audit`
+- `lint`
+
+Avoid introducing raw shell commands; reference the command intent names defined in `.mustflow/config/commands.toml`.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a command intent is missing, restricted to manual execution, disabled, or unknown, report the status rather than guessing.
+- Document any skipped verifications and the associated remaining risks.
+- Immediately halt and report if sensitive data or destructive command risks are identified.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Summary
+- Findings categorized by severity
+- List of reviewed files
+- Command intents executed
+- Skipped command intents and justifications
+- Notes on test relevance
+- Identified remaining risks