mustflow 2.108.2 → 2.108.3

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.python-code-change
 locale: en
 canonical: true
-revision: 4
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: python-code-change
-description: Apply this skill when Python source, standard-library API usage, packaging, runtime version, import layout, type checking, linting, tests, or CLI entry points are created or changed.
+description: Apply this skill when Python source, standard-library API usage, packaging, runtime version, import layout, architecture boundaries, type checking, async tasks, exception/logging/retry behavior, performance-sensitive collection usage, pytest fixtures/mocks, linting, tests, or CLI entry points are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -28,13 +28,13 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Preserve Python runtime, standard-library, packaging, import, async resource, public API, typing, lint, and test boundaries while making a focused change.
+Preserve Python runtime, standard-library, packaging, import, architecture, async resource, failure, performance, public API, typing, lint, and test boundaries while making a focused change.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
 - `.py`, `pyproject.toml`, `setup.py`, `setup.cfg`, requirements files, lockfiles, tox, nox, pytest, mypy, pyright, Ruff, or Python CI config changes.
-- The task touches standard-library feature usage, package layout, CLI entry points, imports, type hints, dependency declarations, virtual environment assumptions, or tests.
+- The task touches standard-library feature usage, package layout, CLI entry points, imports, type hints, dependency declarations, virtual environment assumptions, async task lifecycles, exceptions, logging, retry, fallback, collection performance, or tests.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -47,10 +47,13 @@ Preserve Python runtime, standard-library, packaging, import, async resource, pu
 
 - Python version source: `requires-python`, `.python-version`, tool version files, CI matrix, or container base image.
 - Standard-library feature and runtime-behavior assumptions, especially when using Python-version-gated APIs or changed security defaults.
-- Packaging and dependency files, test config, lint config, and type checker config.
+- Packaging and dependency files, build backend, package manager, lockfile owner, test config, lint config, and type checker config.
 - Package layout: `src` layout, flat layout, namespace package, distribution name, import package name, package discovery settings, CLI entry points, plugin entry points, and nearby tests.
+- Architecture boundary: external adapters, framework request/response objects, ORM models, environment input, DTOs, domain value objects, import direction, and shared utility ownership.
 - Async ownership and resource cleanup surface when coroutines, tasks, context managers, sessions, clients, pools, files, async generators, subprocesses, or logging change.
+- Failure surface when exceptions, logging config, retry, timeout, fallback, degraded responses, or observability fields change.
 - Public contract surface when imports, signatures, exceptions, return shapes, CLI behavior, config, environment variables, extras, Python version support, or typing stubs change.
+- Runtime truth boundary for type hints: external input validation, `Any`, casts, ignores, protocols, guards, stubs, and `py.typed` when present.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
@@ -59,6 +62,7 @@ Preserve Python runtime, standard-library, packaging, import, async resource, pu
 - Determine the lowest supported Python version before choosing syntax or typing features.
 - Determine the lowest supported Python version before choosing standard-library features, changed defaults, syntax, or typing features.
 - Read package layout and import style before editing imports.
+- Read framework, adapter, or entry-point boundaries before moving data shapes across layers.
 - Treat global machine Python state as irrelevant unless the project explicitly declares it.
 
 <!-- mustflow-section: allowed-edits -->
@@ -70,61 +74,107 @@ Preserve Python runtime, standard-library, packaging, import, async resource, pu
 - Do not lower Ruff, mypy, pyright, pytest, or packaging strictness to hide a failure.
 - Keep import fixes in package metadata, package discovery, entry points, or test invocation contracts instead of path hacks.
 - Make resource ownership explicit: code closes only the resources it creates.
+- Translate external data and third-party failures at boundaries instead of leaking framework, SDK, ORM, raw JSON, or environment shapes into domain logic.
 
 <!-- mustflow-section: procedure -->
 ## Procedure
 
 1. Read project metadata, Python version constraints, dependency files, and test/lint/type configs.
-2. Identify the boundary touched: runtime version, package API, import root, packaging metadata, CLI entry, test fixture, async resource ownership, external input, or dependency contract.
+2. Identify the boundary touched: runtime version, package API, import root, packaging metadata, architecture layer, CLI entry, test fixture, async resource ownership, external input, exception/logging/retry path, performance-sensitive collection path, or dependency contract.
 3. For packaging and import changes, separate the distribution name from the import package name. Check package directory mapping, package discovery settings, namespace package behavior, package data, entry points, optional dependencies, and `requires-python` before touching imports.
-4. Treat `src` layout as an installation contract. Importable code under `src/` should be tested through the supported installed-package path, not by making repository files accidentally importable from the working directory.
-5. Match existing package layout and import conventions. Do not add `sys.path`, `site.addsitedir`, `PYTHONPATH`, pytest `pythonpath`, ad hoc import loading, or test `conftest.py` import hacks to make package imports pass.
-6. Do not add `__init__.py` to tests as a blind fix. Add it only when tests are intentionally a package and the import-mode behavior remains explicit.
-7. For packaging changes, distinguish development and release contracts:
+4. For `pyproject.toml`, keep build metadata, package metadata, and tool settings separate:
+   - `[build-system]` names the build backend and build requirements;
+   - `[project]` names distribution metadata, runtime dependencies, Python support, scripts, optional dependencies, and package typing signals;
+   - `[tool.*]`, dependency groups, uv or Poetry settings, and lockfiles are tool or environment contracts, not a substitute for wheel metadata.
+5. Treat `src` layout as an installation contract. Importable code under `src/` should be tested through the supported installed-package path, not by making repository files accidentally importable from the working directory.
+6. Match existing package layout and import conventions. Do not add `sys.path`, `site.addsitedir`, `PYTHONPATH`, pytest `pythonpath`, ad hoc import loading, or test `conftest.py` import hacks to make package imports pass.
+7. Do not add `__init__.py` to tests as a blind fix. Add it only when tests are intentionally a package and the import-mode behavior remains explicit.
+8. For packaging changes, distinguish development and release contracts:
    - editable installs prove the local development path;
    - wheel installs or equivalent built artifacts prove the release path;
+   - editable installs may not reflect entry point, dependency, package metadata, C extension, or package data changes until reinstall or rebuild;
+   - build dependencies, runtime dependencies, optional dependencies, and dependency groups are different contracts;
+   - apps should pin or lock environments; libraries should publish compatible dependency ranges instead of over-pinning downstream users;
+   - uv, Poetry, pip, and build backends each own different parts of the workflow; do not mix their metadata as competing sources of truth;
    - entry point, dependency, optional dependency, metadata, and package data changes require reinstall-oriented verification when a configured intent exists;
    - installed console scripts or plugin entry points should be smoke-tested through the installed entry point contract, not by directly running a source file.
-8. Verify import origin when packaging risk is present. The public package should resolve from the installed environment intended by the project, not from accidental repository-root files.
-9. Validate unknown external data before treating it as typed domain data.
-10. Choose standard-library helpers by semantic contract and supported Python version:
+9. Verify import origin when packaging risk is present. The public package should resolve from the installed environment intended by the project, not from accidental repository-root files.
+10. Preserve architecture boundaries:
+   - keep framework request objects, ORM models, SDK clients, raw JSON, environment variables, and CLI parser output in adapter layers;
+   - convert external input into explicit DTOs, dataclasses, value objects, or validated models before domain logic uses it;
+   - name modules by responsibility instead of dumping shared behavior into `utils.py`, `helpers.py`, or `common.py`;
+   - keep import direction one-way and treat circular imports as architecture evidence, not only a runtime nuisance;
+   - prefer protocols or narrow callable/data contracts over inheritance when callers only need behavior shape.
+11. Validate unknown external data before treating it as typed domain data. Type hints do not enforce runtime values; boundary validation owns JSON, form, CSV, queue, environment, and third-party API input.
+12. Keep type-checking honest:
+   - treat `Any`, bare generics, untyped imports, `cast`, broad `type: ignore`, false `TypeGuard` or `TypeIs`, and runtime `Protocol` checks as trust-boundary risks;
+   - prefer `object` plus narrowing over `Any` when a value is unknown but operations must be checked;
+   - require scoped `# type: ignore[...]` with a local reason when the project policy allows ignores;
+   - do not use `cast()` as conversion; add parsing, validation, or a checked adapter when runtime shape is uncertain;
+   - keep `None` explicit in signatures and return shapes instead of returning `None` from non-optional contracts;
+   - when publishing typed packages, keep `py.typed`, stubs, and public exports aligned.
+13. Choose standard-library helpers by semantic contract and supported Python version:
    - prefer cardinality-explicit iteration such as `zip(strict=True)`, `itertools.batched(..., strict=True)`, or Python 3.14+ `map(strict=True)` only when unequal lengths are a bug and the declared runtime supports the API;
    - do not use `itertools.groupby` as a database-style grouping primitive unless input ordering and group materialization are intentional;
    - avoid shared mutable defaults; use `default_factory` or an existing local construction pattern for per-instance mutable state;
    - prefer `importlib.resources` for packaged data, `tomllib` for TOML reads, and `Path.walk()` only after checking version support, pruning behavior, symlink recursion, ordering, and cycle risks;
    - use dataclass options such as `slots`, `frozen`, and `kw_only`, `StrEnum`, `TypedDict`, or `Protocol` only when they match the public shape and runtime/type-checker support;
    - treat `functools.cache`, `lru_cache`, `cached_property`, `partial`, and Python 3.14+ `Placeholder` as state, memory, concurrency, and versioned-API choices rather than harmless terseness.
-11. Treat newer syntax and typing features as semantic tools, not style trophies:
+14. Review collection and iterator performance when code can scale with input size:
+   - avoid list membership inside large loops, `pop(0)`, repeated list concatenation, large loop slices, and hot-path `deepcopy`;
+   - use `set`, `dict`, `deque`, `Counter`, `heapq`, `join`, comprehensions, or `itertools` when they match the data contract;
+   - treat generators as one-shot streams; do not add hidden `list()`, `sorted()`, `len()`, `tee()`, or `cycle()` materialization without memory reasoning;
+   - rebuild large dicts after bulk deletion when long-lived memory and iteration cost matter;
+   - avoid eager default factories hidden in `dict.get(key, expensive())` or `setdefault(key, expensive())`.
+15. Treat newer syntax and typing features as semantic tools, not style trophies:
    - use template string literals only when a handler needs the static and interpolated parts separately, such as SQL builders, shell command objects, logging templates, or markup renderers; do not replace ordinary f-strings when the result is just a string;
    - when runtime code reads annotations, use the supported annotation inspection API and choose the intended format explicitly instead of assuming `__annotations__` already contains runtime values;
    - use sentinel values to distinguish "argument omitted" from `None`, but compare sentinels by identity and keep public signatures readable;
    - prefer `Mapping` or narrower read-only protocols for read-only inputs so immutable mapping implementations are not rejected accidentally;
    - use closed or extra-key `TypedDict` forms only when the supported Python and type-checker versions agree with that shape.
-12. Keep `finally` as cleanup, not outcome selection. Do not add `return`, `break`, or `continue` inside `finally` blocks because they can mask exceptions and cancellation; move result decisions outside cleanup or make suppression an explicit documented contract.
-13. Use explicit lazy imports only for startup-sensitive module-scope dependencies after checking version support and import-time side effects. Do not lazily import plugins, registries, monkey patches, model definitions, ORM mappings, or observability setup whose import side effects are part of startup correctness.
-14. Keep process, archive, and concurrency safety explicit:
+16. Keep `finally` as cleanup, not outcome selection. Do not add `return`, `break`, or `continue` inside `finally` blocks because they can mask exceptions and cancellation; move result decisions outside cleanup or make suppression an explicit documented contract.
+17. Use explicit lazy imports only for startup-sensitive module-scope dependencies after checking version support and import-time side effects. Do not lazily import plugins, registries, monkey patches, model definitions, ORM mappings, or observability setup whose import side effects are part of startup correctness.
+18. Keep process, archive, and concurrency safety explicit:
    - subprocess calls use argument lists, checked failure handling, timeouts, bounded captured output, and a narrow `shell=True` exception when the project already permits it;
    - archive extraction, including `tarfile`, keeps untrusted archive inspection, extraction filters, partial-extract cleanup, and older-runtime defaults visible;
    - `asyncio.TaskGroup`, `asyncio.timeout`, and `asyncio.to_thread` are used only when their cancellation, timeout, blocking-work, and Python-version semantics fit the surrounding lifecycle.
-15. Use runtime diagnostics as evidence, not as permanent workaround code. Interpreter or library diagnostics such as import timing, `tracemalloc`, `faulthandler`, profiling, and allocation tracing should go through configured diagnostic or verification intents when available, and missing intents should be reported instead of adding ad hoc command recipes to the skill.
-16. Preserve async and resource ownership:
+19. Use runtime diagnostics as evidence, not as permanent workaround code. Interpreter or library diagnostics such as import timing, `tracemalloc`, `faulthandler`, profiling, and allocation tracing should go through configured diagnostic or verification intents when available, and missing intents should be reported instead of adding ad hoc command recipes to the skill.
+20. Preserve async and resource ownership:
    - every coroutine is awaited, returned by contract, or scheduled as an owned and tracked task;
    - raw background task creation is allowed only through the project's owner or spawn helper, a task group, or an equivalent lifecycle mechanism;
    - background tasks keep a strong reference, have a shutdown path, and retrieve failures instead of leaving never-retrieved exceptions;
    - cancellation is control flow, so cleanup uses `finally` and cancellation is re-raised after cleanup unless suppression is the documented behavior;
+   - choose `TaskGroup` over `gather()` when sibling task failure must cancel the rest;
+   - bound fan-out with semaphores, queues, worker pools, or an existing local concurrency primitive;
+   - propagate absolute deadlines or remaining budgets through nested calls instead of resetting relative timeouts at every layer;
+   - cancel and await pending tasks after `asyncio.wait()` timeouts;
    - async functions do not call blocking I/O, blocking sleeps, long CPU work, or blocking subprocess waits directly unless the project has an explicit executor or isolation pattern;
    - context managers and async context managers do not suppress exceptions unless suppression is the feature;
    - context-manager helpers that catch exceptions for logging re-raise after logging;
    - early-exit async generators have an explicit close path.
-17. Preserve traceback evidence. Logging inside exception handlers should retain exception information instead of logging only the exception message.
-18. Preserve public contracts:
+21. Preserve failure evidence:
+   - translate external exceptions into domain exceptions at boundaries with `raise ... from exc`;
+   - do not use `except Exception: pass`, broad `BaseException` catches, or fallback returns that hide failures;
+   - use `logger.exception()` only inside exception handlers or preserve exception info explicitly;
+   - configure logging so module loggers propagate through a deliberate root or parent handler, existing loggers are not disabled accidentally, and slow handlers are isolated when request latency matters;
+   - keep retry finite, jittered or backed off where appropriate, idempotent, and owned by one layer;
+   - make fallback a visible degraded path with logs, metrics, or response metadata rather than silent success.
+22. Preserve public contracts:
    - treat public imports, public signatures, exceptions, return shapes, CLI behavior, entry points, config keys, environment variables, dependency metadata, extras, Python version support, and typing stubs as compatibility-sensitive;
    - do not change sync functions into async functions, accepted input shapes, nullable behavior, documented exception types, tuple/dict/dataclass return shapes, config precedence, or environment variable semantics without a compatibility review;
    - typed packages should keep runtime and typing surfaces aligned, including `py.typed` and stubs when present.
-19. Avoid mutable default arguments, broad `except Exception: pass`, broad `BaseException` catches outside process boundaries, global state hidden behind module imports, `finally` masking, and path handling that ignores existing `pathlib` or OS conventions.
-20. Use `# type: ignore[...]` only when tightly scoped, justified, and consistent with local policy.
-21. If packaging, public API, CLI, config, or typing contracts change, synchronize README examples, entry point tests, build metadata, docs, fixtures, and downstream-style examples that describe installation or usage.
-22. Choose configured verification intents that cover formatting, lint, type checking, tests, package build, installed-package smoke checks, and CLI smoke risk when available.
+23. Preserve test truth:
+   - keep pytest fixtures small, with one state-changing responsibility and cleanup coupled to that state;
+   - treat fixture scope and autouse as isolation decisions, not speed knobs;
+   - avoid mutable `parametrize` values unless each case receives a fresh object;
+   - use `tmp_path`, scoped `monkeypatch`, and patch the namespace where code looks up the object;
+   - prefer mock `autospec`, `spec_set`, and `AsyncMock` await assertions so tests cannot lie about signatures or async execution;
+   - use log assertions to check operational signals, not only message text;
+   - use property-based tests when behavior is an invariant over an input space and existing project dependencies support it.
+24. Avoid mutable default arguments, broad `except Exception: pass`, broad `BaseException` catches outside process boundaries, global state hidden behind module imports, `finally` masking, and path handling that ignores existing `pathlib` or OS conventions.
+25. Use `# type: ignore[...]` only when tightly scoped, justified, and consistent with local policy.
+26. If packaging, public API, CLI, config, typing, async, retry, logging, or test contracts change, synchronize README examples, entry point tests, build metadata, docs, fixtures, and downstream-style examples that describe installation or usage.
+27. Choose configured verification intents that cover formatting, lint, type checking, tests, package build, installed-package smoke checks, and CLI smoke risk when available.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -133,10 +183,14 @@ Preserve Python runtime, standard-library, packaging, import, async resource, pu
 - Python-version-gated standard-library features and changed runtime defaults are accepted only when the declared support matrix allows them.
 - Imports work from the project-supported execution path.
 - Packaging changes distinguish development imports from release artifact imports.
+- Framework, ORM, SDK, raw input, and environment data stay outside the domain core unless intentionally adapted.
+- Runtime validation, type hints, and published typing metadata agree at public and external-input boundaries.
 - Async tasks, context managers, files, clients, pools, subprocesses, and generators have visible ownership and cleanup.
+- Exceptions, logs, retries, timeouts, and fallback paths preserve cause, deadline, idempotency, and degraded-state evidence.
+- Collection and iterator changes have size, copy, and materialization behavior reviewed when relevant.
 - Public API, CLI, config, environment, dependency metadata, and typing contract changes are called out.
 - Type and lint strictness are not weakened.
-- Tests or skipped verification are tied to the changed behavior.
+- Tests or skipped verification are tied to the changed behavior, with fixture/mock/async/logging risks named when relevant.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -158,13 +212,18 @@ Report missing package, type, or test intents rather than inventing raw tool com
 - If import resolution fails, inspect package metadata and test invocation before adding path hacks.
 - If a test only passes because repository root, `src`, or `tests` is injected into import paths, reject the fix and repair packaging or test layout instead.
 - If packaging correctness matters but only repository-root tests can run, report that wheel or installed-artifact verification is missing.
+- If build backend, package manager, lockfile, dependency group, optional dependency, or editable-install behavior is ambiguous, keep the existing owner and report the missing packaging contract instead of migrating tools.
 - If the supported Python version blocks a syntax choice, rewrite to the supported form.
 - If the supported Python version blocks a standard-library feature, changed default, diagnostic flag, or helper API, use the supported equivalent or report the runtime-support decision instead of silently raising `requires-python`.
 - If template strings, annotation runtime access, lazy imports, sentinels, immutable mappings, or typed extra keys are useful but version-gated, keep a fallback or report the required support bump instead of smuggling the newer feature into a lower-runtime project.
 - If third-party stubs or package metadata are wrong, document the local workaround and keep it narrow.
+- If `Any`, `cast`, `type: ignore`, runtime `Protocol`, or type guard behavior is needed, keep it local, justified, and backed by runtime validation or tests where the type claim can lie.
+- If performance risk appears in collections, generators, copies, or caches, report the input-size assumption or use an existing benchmark/profile intent when configured.
 - If a background task lacks owner, shutdown, strong reference, or exception retrieval, do not add it.
 - If cancellation or context-manager behavior is swallowed accidentally, restore propagation or document the intentional suppression contract.
+- If retry, timeout, or fallback lacks idempotency, deadline, owner layer, or degraded-state evidence, keep the failure explicit instead of adding hidden recovery.
 - If resource cleanup cannot be proven, use the project's context manager, exit stack, fixture, or lifecycle pattern before broadening tests.
+- If tests require broad fixtures, autouse state, unscoped monkeypatching, bare mocks, or mutable parametrization, narrow the test seam before trusting the result.
 - If public contracts change without compatibility evidence, stop and report the breaking-change or deprecation requirement.
 
 <!-- mustflow-section: output-format -->
@@ -173,7 +232,7 @@ Report missing package, type, or test intents rather than inventing raw tool com
 - Boundary checked
 - Runtime and packaging assumptions
 - Files changed
-- Type, lint, and import notes
+- Architecture, type, lint, import, async, failure, performance, and test notes
 - Command intents run
 - Skipped checks and reasons
 - Remaining Python risk

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -526,7 +526,7 @@ applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "pe
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "ui_change", "package_metadata_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "ui_change", "performance_change", "package_metadata_change", "release_risk"]
 
 [routes."javascript-code-change"]
 category = "general_code"
@@ -538,7 +538,7 @@ applies_to_reasons = ["code_change", "public_api_change", "test_change"]
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
 
 [routes."powershell-code-change"]
 category = "general_code"
@@ -550,13 +550,13 @@ applies_to_reasons = ["code_change", "test_change", "docs_change", "package_meta
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "data_change", "performance_change", "package_metadata_change", "release_risk"]
 
 [routes."rust-code-change"]
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "data_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
 
 [routes."axum-code-change"]
 category = "general_code"

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.rust-code-change
 locale: en
 canonical: true
-revision: 6
+revision: 7
 lifecycle: mustflow-owned
 authority: procedure
 name: rust-code-change
-description: Apply this skill when Rust source, Cargo metadata, features, traits, errors, ownership, async runtime, unsafe code, tests, examples, benchmarks, release profiles, MSRV, toolchain declarations, standard-library APIs, or public crate APIs are created or changed.
+description: Apply this skill when Rust source, Cargo metadata, features, traits, errors, ownership, borrowing, lifetimes, Clone/Rc/Arc/Mutex/RefCell use, async tasks, channels, cancellation, unsafe code, allocation, zero-copy, tests, examples, benchmarks, release profiles, MSRV, toolchain declarations, standard-library APIs, or public crate APIs are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -28,7 +28,7 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Preserve Rust ownership, error, trait, feature, async runtime, unsafe, and public crate boundaries while making a focused change. A Rust change is successful only when it clarifies ownership and contracts, not when it merely silences the borrow checker.
+Preserve Rust ownership, error, trait, feature, async runtime, unsafe, performance, and public crate boundaries while making a focused change. A Rust change is successful only when it clarifies owners, state, failure contracts, and allocation behavior, not when it merely silences the borrow checker.
 
 Rust's compiler feedback can be especially useful for AI-assisted work because it rejects many
 invalid states with concrete errors. That benefit has a real cost: compile time, target-directory
@@ -38,8 +38,8 @@ instead of treated as incidental.
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- `.rs`, `Cargo.toml`, `Cargo.lock`, workspace config, feature flags, public exports, traits, error types, tests, examples, benches, FFI, async runtime, or unsafe code change.
-- The task touches ownership, borrowing, lifetimes, `Clone`, `Arc`, `Mutex`, `unwrap`, or public crate compatibility.
+- `.rs`, `Cargo.toml`, `Cargo.lock`, workspace config, feature flags, public exports, traits, error types, tests, examples, benches, FFI, async runtime, allocation-sensitive code, or unsafe code change.
+- The task touches ownership, borrowing, lifetimes, `Clone`, `Rc`, `Arc`, `Mutex`, `RefCell`, `unwrap`, `anyhow`, `thiserror`, `Box<dyn Error>`, channels, cancellation, zero-copy buffers, or public crate compatibility.
 - The task introduces or reviews Rust-version-gated APIs or language behavior such as `let else`, let chains, match `if let` guards, `cfg_select!`, `assert_matches!`, `core::range`, `Vec::push_mut`, `HashMap::get_disjoint_mut`, `Option::take_if`, `LazyLock`, `OnceLock`, `workspace.lints`, `rust-version`, Rust 2024 lints, or release-profile tuning.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -53,7 +53,7 @@ instead of treated as incidental.
 
 - `Cargo.toml`, workspace manifests, lockfile policy, toolchain config, rustfmt, clippy, feature flags, docs.rs metadata, optional dependencies, build profiles, target directory or cache policy, and CI hints.
 - Relevant `src/lib.rs`, `src/main.rs`, modules, public re-exports, tests, examples, and docs examples.
-- Existing error handling convention and async runtime.
+- Existing ownership map, error handling convention, async runtime, task ownership model, channel/backpressure policy, and shutdown or cancellation boundary.
 - Public crate status, minimum supported Rust version, feature support policy, and downstream compatibility expectations when available.
 - `rust-version`, edition, `rust-toolchain.toml`, CI toolchain matrix, target triples, Cargo resolver, workspace inheritance policy, and whether newer standard-library APIs require a raised MSRV.
 - Host and build-loop constraints: OS, shell, native toolchain prerequisites, VM or remote-builder use, release profile, LTO, workspace size, disk budget, and configured smoke or focused-check intents.
@@ -62,9 +62,9 @@ instead of treated as incidental.
 <!-- mustflow-section: preconditions -->
 ## Preconditions
 
-- Determine whether the change affects ownership flow, public API, feature gates, optional dependencies, error contract, async runtime, or unsafe invariants.
-- Read local patterns before adding traits, lifetimes, clones, locks, boxed errors, feature bounds, or `Send + Sync + 'static` constraints.
-- Treat `clone`, `Arc<Mutex<_>>`, explicit lifetimes, `'static`, `Box<dyn Error>`, `unwrap`, feature changes, and `unsafe` as suspicious until their contract impact is justified.
+- Determine whether the change affects ownership flow, borrow duration, shared-state meaning, public API, feature gates, optional dependencies, error contract, async runtime, performance hot paths, or unsafe invariants.
+- Read local patterns before adding traits, lifetimes, clones, locks, `Rc<RefCell<_>>`, boxed errors, feature bounds, owned buffers, or `Send + Sync + 'static` constraints.
+- Treat `clone`, `Rc`, `Arc`, `Mutex`, `RefCell`, explicit lifetimes, `'static`, `Box<dyn Error>`, `anyhow`, `unwrap`, feature changes, zero-copy lifetime spread, and `unsafe` as suspicious until their contract impact is justified.
 - Identify the intended edit-check-test loop before choosing a broad build. Treat whole-workspace
   checks, release builds, fat LTO, cross-compiles, and sanitizer-style runs as expensive evidence
   unless the command contract declares them as the normal focused path.
@@ -73,7 +73,7 @@ instead of treated as incidental.
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
 
-- Prefer truthful ownership and borrowing over broad cloning.
+- Prefer truthful ownership and borrowing over broad cloning, shared mutable bags, or lifetime puzzles.
 - Follow the crate's existing application-versus-library error convention.
 - Keep feature-gated code and public re-exports synchronized.
 - Touch unsafe code only with explicit invariants preserved in nearby comments.
@@ -86,7 +86,7 @@ instead of treated as incidental.
 ## Procedure
 
 1. Read Cargo metadata, features, optional dependencies, docs.rs metadata, toolchain config, build profiles, public exports, relevant modules, and tests.
-2. Classify the change as ownership, API, error, feature, async, unsafe, dependency, or test-only.
+2. Classify the change as ownership, API, error, feature, async, concurrency, allocation, unsafe, dependency, or test-only.
 3. Model the build loop before broad edits:
    - identify the smallest package, crate, feature set, smoke target, or test that covers the risk;
    - check whether `target/` or an equivalent cache may grow enough to affect local disk budget;
@@ -108,29 +108,38 @@ instead of treated as incidental.
    - treat automatic edition rewrites as candidate diffs that still need human review of unsafe, macro, pattern, temporary lifetime, docs, and examples.
 6. Prefer flatter control flow when the MSRV supports it: use `let else` for early validation, let chains for related optional/result guards, and match `if let` guards for state-machine refinements. Remember that guard patterns do not satisfy match exhaustiveness; keep the fallback arm meaningful.
 7. In tests, prefer `assert_matches!` over `assert!(matches!(...))` when the MSRV supports it and the failed value has useful `Debug` output. Import it explicitly from `std` or `core`; do not assume it is in the prelude.
-8. Resolve ownership problems in this order: identify the real owner, shrink borrow scopes, fix function signatures to accept references or slices when ownership is unnecessary, distinguish transfer from sharing, then consider clone or shared ownership only when the semantics require it.
-8. Before adding `clone`, verify it is a cheap handle clone such as `Arc`, `Rc`, or `Bytes`, a small intentional value clone, or a true independent ownership split. Reject large collection clones, loop clones, clone-then-borrow code, and whole-state clones made only to satisfy `spawn`.
-9. Before adding `Arc<Mutex<_>>`, verify multiple owners truly need shared mutable state. For read-mostly snapshots, prefer ownership-preserving choices such as `Arc::make_mut`, immutable swaps, or explicit reload boundaries. Keep critical sections short, document lock order when relevant, and do not hold a lock guard across `.await`, I/O, callbacks, or user code.
-10. Choose initialization primitives by input and failure semantics: use `LazyLock` for no-argument static lazy values that may poison permanently on panic, and `OnceLock` when boot-time or test-time code supplies the value or panic poisoning must not become the recovery policy.
-11. Avoid hidden allocation when cheaper type contracts fit: use `Cow<'_, str>` or borrowed slices for mostly-borrowed results, query `HashMap<String, V>` with `&str` when `Borrow` supports it, use `Option::take`, `take_if`, or `as_slice` for state transitions and 0-or-1 iteration, and use `ControlFlow`, `try_for_each`, or `try_fold` when visitor or iterator APIs need explicit short-circuiting.
-12. Treat collection and string capacity as part of performance correctness. Use `with_capacity`, `reserve`, `spare_capacity_mut`, or `push_mut` only when the safety and MSRV contract are clear; keep `set_len` inside a small proven unsafe boundary; avoid repeated `String::insert` or front insertion loops that create quadratic movement.
-13. Use explicit lifetimes only to describe real borrow relationships. Do not add `'static` or `T: 'static` to public APIs merely because an internal task boundary requires it.
-14. Use concrete error enums for library APIs when callers need to classify failures. Keep `Box<dyn Error>` mostly to binaries, examples, tests, prototypes, or explicitly opaque error policies.
-15. Avoid `unwrap`, vague `expect`, and unbounded `panic!` in production paths. They are allowed only for tests, examples, startup policy, panic-boundary adapters, or invariants already proven by nearby code.
-16. Review public API shape before adding `impl Trait`, `Deref`, or trait/lifetime machinery:
+8. Build an ownership ledger before reshaping modules:
+   - name the value owner, mutation owner, drop owner, and long-lived storage owner;
+   - keep `&T` as short observation, `&mut T` as short exclusive mutation, and `T` as transfer;
+   - prefer owned values, ids, handles, indexes, ranges, or offsets for long-lived structs;
+   - add explicit lifetimes only when the type is truly a view tied to source data.
+9. Resolve ownership problems in this order: identify the real owner, shrink borrow scopes, fix function signatures to accept references or slices when ownership is unnecessary, distinguish transfer from sharing, then consider clone or shared ownership only when the semantics require it.
+10. Before adding `clone`, verify it is a cheap handle clone such as `Arc`, `Rc`, or `Bytes`, a small intentional value clone, or a true independent ownership split. Reject derived `Clone` that hides shared mutable state, large collection clones, loop clones, clone-then-borrow code, and whole-state clones made only to satisfy `spawn`.
+11. Before adding `Rc`, `Arc`, `Mutex`, or `RefCell`, identify whether the code needs shared ownership, thread crossing, interior mutability, or true shared mutable state. Prefer one owner plus messages or commands when possible; use `Weak` for back edges or cycles; keep `RefCell` and mutex guards short, and do not hold a guard across `.await`, I/O, callbacks, logging hooks, observer calls, or user code.
+12. Before adding `Arc<Mutex<_>>`, verify multiple owners truly need shared mutable state. For read-mostly snapshots, prefer ownership-preserving choices such as `Arc::make_mut`, immutable swaps, atomics, sharded owners, or explicit reload boundaries. Keep critical sections short, document lock order when more than one lock exists, and decide whether poisoning is crash policy, recovery policy, or state-discard policy.
+13. Choose initialization primitives by input and failure semantics: use `LazyLock` for no-argument static lazy values that may poison permanently on panic, and `OnceLock` when boot-time or test-time code supplies the value or panic poisoning must not become the recovery policy.
+14. Avoid hidden allocation when cheaper type contracts fit: use `Cow<'_, str>` or borrowed slices for mostly-borrowed results, query `HashMap<String, V>` with `&str` when `Borrow` supports it, use `Option::take`, `take_if`, or `as_slice` for state transitions and 0-or-1 iteration, and use `ControlFlow`, `try_for_each`, or `try_fold` when visitor or iterator APIs need explicit short-circuiting.
+15. Treat collection and string capacity as part of performance correctness. Use `with_capacity`, `reserve`, `spare_capacity_mut`, or `push_mut` only when the safety and MSRV contract are clear; keep `set_len` inside a small proven unsafe boundary; avoid repeated `String::insert`, front insertion loops, per-item `format!`, unnecessary `collect()`, and temporary `Vec` or `String` construction in hot paths.
+16. Use zero-copy only when the lifetime cost is lower than the copy cost. Prefer borrowed slices for same-call observation, owned values for queue/task/cache/domain storage, and reference-counted buffers such as `Bytes` only when retaining the larger backing allocation is acceptable.
+17. Use explicit lifetimes only to describe real borrow relationships. Do not add `'static` or `T: 'static` to public APIs merely because an internal task boundary requires it. If a self-referential shape appears, first replace internal references with offsets, ranges, ids, or arenas before considering `Pin`, macros, or unsafe.
+18. Use concrete error enums for library APIs when callers need to classify failures. Separate recoverable errors from internal bugs; shape error variants around caller action, not merely dependency type names. Use `thiserror` to implement typed errors, `map_err` to translate lower-level failures, and `source()` to preserve diagnostic cause.
+19. Keep `anyhow` mostly at application, CLI, worker, migration, or top-level orchestration boundaries where errors are logged, enriched with context, and not matched by downstream callers. Use `.context()` or `.with_context()` where `?` would otherwise erase the operation that failed.
+20. Avoid `unwrap`, vague `expect`, and unbounded `panic!` in production paths. They are allowed only for tests, examples, startup policy, panic-boundary adapters, or invariants already proven by nearby code. Do not parse `Display` strings for control flow; match typed variants, error kinds, or stable error codes.
+21. Review public API shape before adding `impl Trait`, `Deref`, or trait/lifetime machinery:
    - argument-position `impl Trait` removes caller turbofish control and can be a public breaking change when converted from named generics;
    - return-position `impl Trait` hides one concrete type, so divergent iterator or future branches need an enum, boxed trait object, or different API boundary;
    - implement `Deref` only for pointer-like wrappers, not domain inheritance or method forwarding;
    - use GATs for borrowing iterator/view traits when they remove a real allocation or boxed lifetime escape, not as decorative complexity.
-17. If feature flags or Cargo workspace metadata change, treat default features, no-default builds, all-features builds, optional dependency implicit features, resolver behavior, target-specific dependencies, `workspace.package`, `workspace.dependencies`, `workspace.lints`, public re-exports, docs examples, and feature-gated trait impls as compatibility surfaces. Features should be additive, and `resolver = "2"` or a newer resolver decision must match the crate's edition/MSRV policy.
-18. Treat public re-exports, public dependency types, generic bounds, trait item sets, error enum variants, `#[non_exhaustive]`, and MSRV as public API. Tightened bounds, added required trait methods, removed re-exports, changed error variants, or raised `rust-version` require compatibility review.
-19. Do not mix async runtimes. A Tokio crate should not casually gain `async-std` or runtime-specific APIs in library core. Do not call blocking I/O or CPU-heavy work in async paths without an established boundary such as async-native APIs, a blocking pool, or a dedicated worker.
-20. For async spawning, avoid leaking internal `Send + Sync + 'static` requirements into public APIs. Prefer owned task state, smaller spawn boundaries, local task structures, or caller-owned runtime decisions.
-21. Touch `unsafe` only when a safe design cannot express the required behavior. Every unsafe block needs a nearby `SAFETY:` explanation; every public `unsafe fn` needs `# Safety` docs. In Rust 2024 or when `unsafe_op_in_unsafe_fn` is enabled, unsafe operations inside `unsafe fn` still need explicit unsafe blocks. Keep unsafe scopes small and wrap them in safe abstractions only when callers have no hidden safety obligations.
-22. For FFI, keep Rust ABI types out of C boundaries. Use explicit ownership, `#[repr(C)]` where required, raw pointer plus length pairs, `CStr`/`CString`, RAII wrappers, null handling, panic boundaries, and documented thread-safety evidence before manual `Send` or `Sync`.
-23. Review release profiles when the task changes binary delivery, CLI startup, embedded, wasm, or performance behavior. Treat `opt-level`, LTO, `panic`, `codegen-units`, and `strip` as product tradeoffs that must be measured or reported, not decorative Cargo knobs.
-24. Calibrate performance claims. Do not claim Rust made a system faster from compile success, empty-database timings, warm-cache microbenchmarks, local-only runs, or debug versus release confusion. Require representative data size, concurrency, target hardware, profile, and measurement method before reporting speed claims.
-25. Choose configured verification intents that cover format, lint, build, tests, feature combinations, docs, public API, unsafe, FFI, smoke targets, package artifact, and release-profile risk when available.
+22. If feature flags or Cargo workspace metadata change, treat default features, no-default builds, all-features builds, optional dependency implicit features, resolver behavior, target-specific dependencies, `workspace.package`, `workspace.dependencies`, `workspace.lints`, public re-exports, docs examples, and feature-gated trait impls as compatibility surfaces. Features should be additive, and `resolver = "2"` or a newer resolver decision must match the crate's edition/MSRV policy.
+23. Treat public re-exports, public dependency types, generic bounds, trait item sets, error enum variants, `#[non_exhaustive]`, sealed versus externally implementable traits, and MSRV as public API. Tightened bounds, added required trait methods, removed re-exports, changed error variants, public dependency upgrades, or raised `rust-version` require compatibility review.
+24. Do not mix async runtimes. A Tokio crate should not casually gain `async-std` or runtime-specific APIs in library core. Do not call blocking I/O or CPU-heavy work in async paths without an established boundary such as async-native APIs, bounded `spawn_blocking`, a semaphore, a dedicated worker, or a caller-owned runtime decision.
+25. For async spawning, avoid leaking internal `Send + Sync + 'static` requirements into public APIs. Prefer owned task state, smaller spawn boundaries, local task structures, or caller-owned runtime decisions. Track every spawned task's owner, join/abort policy, panic handling, cancellation signal, and shutdown wait point.
+26. Review async channels and cancellation as reliability contracts: prefer bounded channels unless unbounded memory growth is explicitly acceptable; define full-queue behavior, `send` failure handling, `recv None` shutdown behavior, sender clone lifecycle, timeout target, and whether `select!` branches are cancel-safe.
+27. Touch `unsafe` only when a safe design cannot express the required behavior. Every unsafe block needs a nearby `SAFETY:` explanation; every public `unsafe fn` needs `# Safety` docs. In Rust 2024 or when `unsafe_op_in_unsafe_fn` is enabled, unsafe operations inside `unsafe fn` still need explicit unsafe blocks. Keep unsafe scopes small and wrap them in safe abstractions only when callers have no hidden safety obligations.
+28. For FFI, keep Rust ABI types out of C boundaries. Use explicit ownership, `#[repr(C)]` where required, raw pointer plus length pairs, `CStr`/`CString`, RAII wrappers, null handling, panic boundaries, and documented thread-safety evidence before manual `Send` or `Sync`.
+29. Review release profiles when the task changes binary delivery, CLI startup, embedded, wasm, or performance behavior. Treat `opt-level`, LTO, `panic`, `codegen-units`, and `strip` as product tradeoffs that must be measured or reported, not decorative Cargo knobs.
+30. Calibrate performance claims. Do not claim Rust made a system faster from compile success, empty-database timings, warm-cache microbenchmarks, local-only runs, or debug versus release confusion. Require representative data size, concurrency, target hardware, profile, and measurement method before reporting speed claims. Prefer Criterion-style or macrobenchmark evidence when adding benchmark-backed claims, and state whether allocation count, copy count, lock contention, syscall count, p95/p99 latency, or throughput changed.
+31. Choose configured verification intents that cover format, lint, build, tests, feature combinations, docs, public API, unsafe, FFI, smoke targets, package artifact, benchmark evidence, and release-profile risk when available.
 
 <!-- mustflow-section: rejection-criteria -->
 ## Review Rejection Criteria
@@ -138,7 +147,11 @@ instead of treated as incidental.
 Reject or revise the patch when any of these appear without strong local justification:
 
 - New large `clone()` calls, clone-then-borrow code, loop clones, or state clones used only to appease ownership errors.
-- New `Arc<Mutex<AppState>>`-style shared bags, locks held across `.await`, or async I/O resources shared mainly by mutex.
+- New `#[derive(Clone)]` on types that contain shared mutable state without an explicit handle-versus-snapshot decision.
+- New long-lived `struct Foo<'a>` fields, self-referential shapes, or public `'static` bounds that export an internal borrow or task workaround.
+- New `Rc<RefCell<_>>` object graphs, `Rc` cycles without `Weak`, `RefCell` guards held across callbacks, or runtime borrow panics treated as normal control flow.
+- New `Arc<Mutex<AppState>>`-style shared bags, locks held across `.await`, I/O, callbacks, logging hooks, or user code, or async I/O resources shared mainly by mutex.
+- New unbounded channels, detached `tokio::spawn` work, timeout wrappers that only stop waiting, blocking work on an async executor, or shutdown paths that signal without waiting.
 - New version-gated Rust API usage without API-specific MSRV, `rust-version`, edition, toolchain, CI, or fallback evidence.
 - Rust 2024 edition changes accepted without reviewing unsafe extern blocks, unsafe attributes, `unsafe_op_in_unsafe_fn`, temporary drop scopes, and macro fragment behavior where those surfaces exist.
 - New `LazyLock` initialization for recoverable runtime configuration where permanent panic poisoning would be the wrong failure policy.
@@ -146,7 +159,11 @@ Reject or revise the patch when any of these appear without strong local justifi
 - New public `impl Trait`, `Deref`, GAT, workspace resolver, feature, or `rust-version` change without public API and compatibility review.
 - New public `'static`, `Send`, or `Sync` bounds that exist only because an internal task was spawned.
 - New public `Box<dyn Error>` in a library where callers need typed failures.
+- New library `anyhow::Result` where downstream callers need stable classification, transparent dependency errors that leak implementation, or error variants named only after dependency crates.
 - New production `unwrap` or vague `expect` on I/O, parse, environment, network, FFI, lock, or user input paths.
+- New string-parsed error control flow instead of typed error variants, error kinds, or stable codes.
+- New zero-copy lifetime spread that makes queues, tasks, caches, or domain objects borrow input buffers longer than the source owner can guarantee.
+- New hot-path `format!`, `.to_string()`, unnecessary `collect()`, temporary `Vec`, repeated allocation, or debug-build performance claim without measurement evidence.
 - New unbounded `panic!` paths, index assumptions, or unchecked slicing in production paths without a documented invariant or panic boundary.
 - Feature changes that remove APIs, change type meaning, rename features, expose internal optional dependency names, or fail default/no-default/all-features reasoning.
 - Public dependency types, re-exports, trait bounds, trait methods, or error enum variants changed without semver review.
@@ -162,8 +179,9 @@ Reject or revise the patch when any of these appear without strong local justifi
 - Rust-version-gated syntax, standard-library APIs, Cargo behavior, and lint assumptions match the declared MSRV or have explicit fallbacks.
 - Public API, features, optional dependencies, and error contracts are synchronized.
 - Async runtime ownership is preserved and blocking work is isolated.
+- Task ownership, channel capacity, cancellation, timeout, and shutdown wait points are explicit when async code changes.
 - Unsafe, `unsafe_op_in_unsafe_fn`, and FFI invariants are preserved or no unsafe code was touched.
-- Allocation, initialization, Cargo workspace, and release-profile choices are intentional and reported when they affect public or delivery behavior.
+- Allocation, zero-copy, initialization, Cargo workspace, and release-profile choices are intentional and reported when they affect public, hot-path, or delivery behavior.
 - Build-loop cost, target/cache impact, smoke-target coverage, and native toolchain prerequisites
   are handled or reported.
 - Missing feature, semver, docs, unsafe, FFI, smoke, package, or performance verification is reported.
@@ -215,6 +233,7 @@ When configured intents exist for these risks, prefer coverage equivalent to:
 - Boundary checked
 - Build-loop, cache, smoke target, and toolchain notes
 - Ownership, feature, async, or unsafe impact
+- Allocation, zero-copy, channel, cancellation, or benchmark impact
 - Public API or error impact
 - Files changed
 - Command intents run