mustflow 2.22.16 → 2.22.46

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

@@ -0,0 +1,173 @@
+---
+mustflow_doc: skill.html-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: html-code-change
+description: Apply this skill when HTML, templates, JSX or component markup, forms, controls, dialogs, navigation, tables, media, metadata, SEO head content, or structured data are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.html-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# HTML Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve semantic structure, native controls, keyboard access, focus behavior, form labeling, metadata, and browser-valid markup. Treat non-native interactive markup as suspicious by default; HTML already gives browsers, keyboards, forms, password managers, mobile input, and assistive technology a working contract.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.html`, JSX, TSX, Vue, Svelte, Astro, or template markup changes.
+- The task touches layout landmarks, headings, forms, buttons, links, dialogs, menus, tabs, accordions, custom selects, composite widgets, tables, media, metadata, canonical links, Open Graph, robots, hreflang, viewport, or JSON-LD.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- Only CSS changes and markup semantics are unchanged; use `css-code-change`.
+- The markup is generated and should be changed through a source component or template.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Existing page layout, document shell, head/SEO helpers, metadata builders, canonical URL helpers, sitemap or robots config, form components, interactive control components, and tests.
+- Target framework conventions for rendering, routing, hydration, and metadata.
+- Visible page content, H1 or primary title, main entity, locale, indexing intent, and data sources for title, description, image, author, date, price, rating, availability, and FAQ content when metadata changes.
+- Accessibility and validation tooling declared in the command contract.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Identify the document structure, interactive controls, form ownership, focus path, metadata source, and verification surface.
+- Prefer native HTML elements before adding ARIA or JavaScript behavior.
+- Classify every interactive element by user intent before changing markup.
+- Do not edit metadata, canonical, Open Graph, robots, hreflang, or JSON-LD from a single file in isolation.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Use semantic landmarks, headings, native links, native buttons, and native form controls where possible.
+- Connect labels, help text, error text, required state, autocomplete, and input type explicitly.
+- Keep metadata and structured data consistent with visible page content.
+- Add ARIA only when native semantics cannot express the control and the required role, state, keyboard, and focus behavior are implemented.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read the page shell, route layout, metadata helpers, component patterns, and tests before editing.
+2. Check document outline, landmarks, source order, and heading levels.
+3. Classify each interactive element by intent. Navigation to a URL uses an anchor with `href`. Commands, toggles, submit actions, open/close actions, destructive actions, copy actions, disclosure triggers, and modal triggers use buttons.
+4. Use native form controls for text entry, selection, checkbox, radio, and file input. Use grouped native radio or checkbox controls with fieldset and legend when the group label matters.
+5. Treat composite widgets such as tabs, action menus, comboboxes, listboxes, trees, grids, and custom selects as high-risk. Prefer native HTML or an existing audited component; otherwise implement the complete role, state, focus, and keyboard pattern.
+6. Reject clickable `div` or `span` controls, clickable icons without buttons, anchors without `href`, links used as buttons, nested interactive controls, positive `tabindex`, focusable `aria-hidden` content, and focus outline removal without a replacement focus style.
+7. Use ARIA only when native HTML cannot express the needed semantics. Validate the role is legal for the element, the accessible name exists, required states are present, visual and ARIA states stay synchronized, keyboard behavior matches the widget pattern, and focus behavior is explicit.
+8. For custom legacy button-like elements that cannot be replaced, require `role`, focusability, Enter activation, Space activation, Space scroll prevention, pointer activation, duplicate-event prevention, and visible focus. Use native buttons instead whenever possible.
+9. For dialogs, prefer native dialog when the project can support it. Otherwise implement focus entry, Tab and Shift+Tab containment, Escape behavior, inert or unreachable background content, visible close or cancel control, focus return, and an accessible name.
+10. For tabs, use tablist, tab, and tabpanel semantics only for a real tabbed interface. Require one active tab, panel linkage, roving tabindex, arrow key movement, Home and End where expected, and Enter or Space activation when activation is manual.
+11. For menus, do not use ARIA menu roles for ordinary site navigation. Site navigation is a nav landmark with links. Use ARIA menu patterns only for application-style action menus with a button trigger, expanded state, focus strategy, Escape close behavior, and focus return.
+12. For forms, verify visible label association, help association, error association, required text, native required state, autocomplete, validation timing, invalid state, error summary behavior, and submission behavior.
+13. Use placeholder, title, aria-label, color, icon, or toast-only feedback only as supplementary affordances, not as the only label, required indicator, or error explanation.
+14. For metadata, read visible content and the metadata generation path first. Keep title, description, canonical, Open Graph, Twitter or X card data, robots, hreflang, and JSON-LD aligned with visible content, locale, URL, and indexing intent.
+15. Structured data must describe content visible on the same page. Do not invent ratings, reviews, FAQ items, authors, prices, availability, dates, organizations, product properties, or claims not backed by the page data source.
+16. Ensure every HTML page has a valid non-empty language and responsive viewport that does not disable zoom. Mixed-language passages should identify their language when needed.
+17. Keep inline script and style minimal; move behavior and styling to the existing project layers unless the framework requires an inline boundary.
+18. Choose configured verification intents that cover markup validity, lint, build, accessibility, route rendering, metadata, and docs when available.
+
+<!-- mustflow-section: form-accessibility -->
+## Form Accessibility Rules
+
+- Every user-editable native form control needs a persistent visible label, preferably an explicit label whose `for` value exactly matches the control `id`.
+- Placeholder text, title text, aria-label, icon-only labels, and visual proximity are not substitutes for visible labels unless a strong design constraint is reported and the accessible name remains clear.
+- Help text and error text must be real DOM text with stable IDs and connected through `aria-describedby` when relevant.
+- Required native controls should use native `required`; the required state must also be visible in text or an explained marker. Do not rely on color alone.
+- Use `aria-required` mainly for custom ARIA controls or deliberate compatibility needs; it does not enforce browser validation.
+- Do not set `aria-invalid` before the user has interacted with the field or attempted submission. Set it when validation has determined the field is invalid.
+- Error messages must identify what is wrong and how to fix it when the fix is known. Avoid generic text such as "Invalid" with no recovery instruction.
+- Multiple submit errors should use an error summary near the top of the form or page when the project pattern supports it. Summary items should link to invalid fields, and inline errors should remain next to fields.
+- Use alert or live regions only for dynamic validation or submit feedback that should be announced. Do not spam alerts on every keystroke or place interactive controls inside alerts.
+- Inputs collecting information about the current user should use appropriate autocomplete tokens. Do not blindly disable autocomplete on login, checkout, contact, signup, or account forms.
+
+<!-- mustflow-section: metadata-policy -->
+## Metadata And Structured Data Rules
+
+Before editing page metadata, identify the rendered route, canonical production URL, visible H1 or main title, visible primary entity, locale, indexing intent, and source of page facts.
+
+- Titles must match the visible primary topic, avoid repeated keyword stuffing, avoid stale boilerplate, and use the page's visible language.
+- Descriptions must summarize the actual visible page and must not fabricate claims, guarantees, prices, ratings, dates, or features.
+- Canonical URLs must be absolute production URLs for the preferred version of the same or near-duplicate content. Do not point canonical to staging, localhost, unrelated pages, wrong locale pages, redirects, 404s, noindex pages, or parameter URLs unless explicitly intended.
+- Canonical, sitemap, hreflang, internal links, and social URL metadata should not contradict each other.
+- Open Graph and Twitter or X title, description, URL, and image should come from the same source of truth as page metadata unless a campaign override is documented. Social images must be absolute, crawlable, and representative of the visible page.
+- Prefer JSON-LD for structured data. Validate JSON syntax and ensure required properties for the chosen rich result type are present when rich-result eligibility matters.
+- Robots directives such as noindex, nofollow, nosnippet, or restrictive crawl hints need explicit intent. Before removing one, check whether the page is intentionally private, duplicated, thin, internal, staged, or blocked.
+
+<!-- mustflow-section: rejection-criteria -->
+## Review Rejection Criteria
+
+Reject or revise the patch when any of these appear without strong justification and verification:
+
+- New `div` or `span` interaction where a native link, button, or form control would work.
+- Anchors without `href`, buttons implemented as links, links implemented as buttons, nested interactive controls, clickable icons without native controls, or site navigation using ARIA menu roles.
+- Custom controls without complete accessible name, role, state, keyboard, focus, and hidden-content behavior.
+- Positive `tabindex`, hidden content that remains tabbable, focusable `aria-hidden` content, or invisible focus.
+- Form controls without visible labels, placeholder-only labels, disconnected help or error text, color-only required or error state, premature `aria-invalid`, or autocomplete removed without reason.
+- Metadata or JSON-LD that contradicts visible content, fabricates facts, points canonical or social URL at the wrong page, disables zoom, omits page language, or accidentally noindexes a public page.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Markup communicates the intended structure without relying on visual styling alone.
+- Keyboard and focus behavior are preserved.
+- Forms have labels and errors connected.
+- Metadata and structured data reflect visible content.
+- Hidden content is not reachable by keyboard when it should be inactive.
+- Native controls are used unless a complete custom interaction pattern is justified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing accessibility, browser, or HTML validation intents when relevant.
+
+When configured or manual verification is available, cover keyboard-only navigation with Tab, Shift+Tab, Enter, Space, Escape, Arrow keys, Home, and End where applicable. Confirm visible focus, accessible name, role, value, state, hidden-content behavior, form errors, metadata consistency, and structured data truthfulness.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a custom control cannot meet keyboard and focus requirements, replace it with a native element or report the blocker.
+- If metadata source of truth is unclear, inspect the framework route and SEO helpers before editing.
+- If form validation timing or error ownership is unclear, keep native validation behavior and report the unresolved custom validation boundary.
+- If structured data facts cannot be traced to visible content or a trusted page data source, do not add them.
+- If accessibility verification is unavailable, report the manual keyboard and focus checks that remain.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Semantic, form, focus, and metadata notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining HTML risk

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

@@ -0,0 +1,149 @@
+---
+mustflow_doc: skill.javascript-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: javascript-code-change
+description: Apply this skill when JavaScript source, package module format, runtime boundary, dependency usage, async Promise handling, browser or Node behavior, bundler config, or tests are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.javascript-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# JavaScript Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve JavaScript module, runtime, package entry, Promise, cleanup, dependency, and test boundaries.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.js`, `.mjs`, `.cjs`, package scripts, package exports, bundler config, browser code, Node code, edge code, dependency usage, or JavaScript tests change.
+- The task touches `import`, `require`, `module.exports`, `exports`, `fetch`, `process`, `window`, `document`, `Buffer`, `fs`, `async`, Promise chains, or package entry metadata.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- TypeScript surfaces are changed; use `typescript-code-change`.
+- JavaScript files are generated artifacts that should be regenerated by a declared command.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- `package.json`, lockfile, engines, module `type`, package `exports`, bundler config, lint config, test config, and relevant entrypoints.
+- Target runtime: browser, Node, worker, edge, Bun, or multi-runtime boundary.
+- Runtime adapter files, source entrypoints, package docs examples, and build output layout when package entry or runtime support changes.
+- Async ownership and cleanup surface when Promises, retries, timers, event listeners, streams, abort signals, background tasks, startup, shutdown, or external I/O change.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Determine module system and runtime before editing imports or globals.
+- Treat Promise and dependency changes as behavior changes unless proven otherwise.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep ESM and CommonJS boundaries explicit and localized.
+- Use browser APIs only in browser-safe files and Node APIs only in Node-safe files.
+- Await, return, catch, or intentionally handle every Promise.
+- Prefer existing dependencies and platform APIs over adding a new dependency.
+- Keep runtime-specific APIs behind platform adapters or runtime-specific entrypoints.
+- Keep package entry changes synchronized with declarations, docs examples, build output, and consumer smoke coverage when available.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read package metadata, module type, exports, bundler config, lint config, entrypoints, docs examples, and tests.
+2. Declare the touched boundary: module system, runtime, package entry, browser/Node/edge/Bun split, async flow, dependency, or test-only.
+3. Classify each changed JavaScript file as shared, Node, browser, edge, Bun, or test-only before adding imports or globals.
+4. Keep shared files portable:
+   - do not import or reference `node:*`, `fs`, `process`, `Buffer`, `window`, `document`, `localStorage`, DOM-only APIs, or Node streams directly;
+   - prefer `URL`, `URLSearchParams`, `Uint8Array`, `ArrayBuffer`, `TextEncoder`, `TextDecoder`, Web `Request`/`Response`, Web Streams, and injected dependencies when those fit the existing code.
+5. Keep runtime-specific APIs isolated:
+   - Node files may use Node process, filesystem, Buffer, Node crypto, and Node streams;
+   - browser files may use DOM, window, document, local storage, browser events, and browser fetch;
+   - edge files should be treated as Web API based, not as browser DOM code and not as full Node code;
+   - Bun-specific APIs do not prove Node, browser, or edge compatibility.
+6. Do not use runtime detection as a broad escape hatch in shared code. Prefer explicit runtime entrypoints, adapters, conditional exports, or dependency injection over a file that mixes every runtime branch.
+7. Keep environment access behind existing server/client env helpers. Do not read raw server secrets from client, shared, browser, or edge code, and do not assume `process.env` exists outside Node-oriented code.
+8. Do not mix `import`/`export` with `require`/`module.exports` outside an established interop boundary.
+9. Treat package entry metadata as public contract:
+   - `type`, file extensions, `main`, `module`, `browser`, `exports`, `types`, `typesVersions`, `files`, `bin`, `sideEffects`, and `engines` affect consumers;
+   - adding `exports` can block deep imports and should be classified as public API sensitive;
+   - conditional exports must keep specific conditions before generic fallbacks;
+   - ESM and CJS branches should expose compatible documented shapes when both are supported;
+   - TypeScript declaration output and docs examples must keep pointing at existing package entry files.
+10. For package entry changes, check source entrypoints, build output layout, docs import examples, TypeScript or declaration settings, bundler config, and consumer-style tests. Report missing Node ESM, Node CJS, browser bundle, edge, Bun, or TypeScript consumer verification when those targets are claimed but no configured intent exists.
+11. Treat build targets as syntax/output compatibility, not as permission to use a runtime API. A browser or edge build target does not make Node filesystem, process, Buffer, or native APIs safe.
+12. Treat implicit globals as failures.
+13. Do not discard Promises. Every Promise-producing call must be awaited, returned, joined, or intentionally supervised by the project's detached-task pattern.
+14. Do not leave `.map(async ...)` unjoined. Join with the established Promise aggregation or bounded-concurrency helper when parallel work is intended.
+15. Do not use unbounded parallelism for large external I/O fan-out. Use the local concurrency limit pattern when the workload touches HTTP, database, filesystem, queue, AI, or other external services.
+16. Propagate cancellation when the operation can outlive a request, job, stream, retry loop, timeout, or user action. Accept and forward `AbortSignal` or the repository's established cancellation token when available.
+17. Do not implement timeout as a caller-only race that leaves the real work running. Timeout behavior must cancel or abort the underlying operation when the API supports it.
+18. Put cleanup in a deterministic path. Timers, event listeners, stream readers, Node streams, temp files, locks, transactions, subscriptions, and shutdown drains need success, failure, timeout, and cancellation cleanup coverage when touched.
+19. Do not build package exports or dependency changes without checking consumers, tests, and docs examples.
+20. Choose configured verification intents that cover lint, build, tests, package entry, runtime behavior, async rejection handling, cancellation, and cleanup when available.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Runtime and module boundaries are explicit.
+- Promise failures are not hidden.
+- Runtime-specific APIs do not leak into shared, browser, edge, or package entry code.
+- Package entry changes are synchronized with tests or reported as unverified.
+- Async cancellation and cleanup behavior is covered or reported as a remaining risk.
+- No unnecessary dependency was added.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing browser, Node, edge, Bun, TypeScript-consumer, package-entry, async-cancellation, or cleanup verification intents when they are relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the module system is unclear, inspect package metadata and entrypoints before editing.
+- If runtime globals are needed in shared code, isolate them behind an adapter or report the boundary conflict.
+- If a shared file imports runtime-only APIs, split the runtime entry or adapter before adding more branches.
+- If a package entry change breaks a documented import path, restore compatibility or report the breaking-change requirement.
+- If a Promise is intentionally detached but has no rejection sink, shutdown/drain policy, or tracing context, do not detach it.
+- If cancellation or cleanup cannot be proven, add or reuse the local lifecycle pattern before weakening tests.
+- If dependency compatibility is unclear, classify the change as research or defer it.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Runtime and module notes
+- Async and dependency notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining JavaScript risk

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

@@ -0,0 +1,154 @@
+---
+mustflow_doc: skill.python-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: python-code-change
+description: Apply this skill when Python source, packaging, runtime version, import layout, type checking, linting, tests, or CLI entry points are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.python-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Python Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Python runtime, packaging, import, async resource, 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 package layout, CLI entry points, imports, type hints, dependency declarations, virtual environment assumptions, or tests.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only edits generated Python output that should not be maintained manually.
+- The repository does not contain Python behavior and the file is only documentation.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Python version source: `requires-python`, `.python-version`, tool version files, CI matrix, or container base image.
+- Packaging and dependency files, 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.
+- Async ownership and resource cleanup surface when coroutines, tasks, context managers, sessions, clients, pools, files, async generators, subprocesses, or logging change.
+- Public contract surface when imports, signatures, exceptions, return shapes, CLI behavior, config, environment variables, extras, Python version support, or typing stubs change.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Determine the lowest supported Python version before choosing syntax or typing features.
+- Read package layout and import style before editing imports.
+- Treat global machine Python state as irrelevant unless the project explicitly declares it.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep existing packaging tools and layout unless the user explicitly asks for a packaging migration.
+- Add or adjust type hints at public boundaries, complex return values, and external input boundaries.
+- Follow existing test style, fixtures, parametrization, and lint/type strictness.
+- 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.
+
+<!-- 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.
+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:
+   - editable installs prove the local development path;
+   - wheel installs or equivalent built artifacts prove the release path;
+   - 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. 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;
+   - 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.
+11. Preserve traceback evidence. Logging inside exception handlers should retain exception information instead of logging only the exception message.
+12. 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.
+13. Avoid mutable default arguments, broad `except Exception: pass`, broad `BaseException` catches outside process boundaries, global state hidden behind module imports, and path handling that ignores existing `pathlib` or OS conventions.
+14. Use `# type: ignore[...]` only when tightly scoped, justified, and consistent with local policy.
+15. 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.
+16. 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
+
+- The code respects the declared Python version and packaging layout.
+- Imports work from the project-supported execution path.
+- Packaging changes distinguish development imports from release artifact imports.
+- Async tasks, context managers, files, clients, pools, subprocesses, and generators have visible ownership and cleanup.
+- 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.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing package, type, or test intents rather than inventing raw tool commands.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- 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 the supported Python version blocks a syntax choice, rewrite to the supported form.
+- If third-party stubs or package metadata are wrong, document the local workaround and keep it narrow.
+- 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 resource cleanup cannot be proven, use the project's context manager, exit stack, fixture, or lifecycle pattern before broadening tests.
+- If public contracts change without compatibility evidence, stop and report the breaking-change or deprecation requirement.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Runtime and packaging assumptions
+- Files changed
+- Type, lint, and import notes
+- Command intents run
+- Skipped checks and reasons
+- Remaining Python risk