mustflow 2.22.17 → 2.22.47

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

@@ -0,0 +1,199 @@
+---
+mustflow_doc: skill.css-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: css-code-change
+description: Apply this skill when CSS, Sass, Less, CSS Modules, CSS-in-JS, global styles, cascade layers, selector specificity, design tokens, layout, responsive behavior, focus styles, animation, color, or component styling are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.css-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# CSS Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve cascade order, specificity discipline, resilient responsive layout, design tokens, focus visibility, contrast, reduced motion, browser compatibility, and layout stability. Treat CSS as a long-lived system, not a screenshot patch.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.css`, Sass, Less, CSS Modules, CSS-in-JS, global styles, reset, theme variables, cascade layers, selectors, design tokens, component styles, animations, or responsive rules change.
+- The task touches specificity, `!important`, inline styles, negative margins, layout shift, browser compatibility, dark mode, focus style, contrast, typography, zoom, text scaling, or motion preference.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- Styling is entirely Tailwind utility usage; use `tailwind-code-change`.
+- Styling is entirely UnoCSS utility usage; use `unocss-code-change`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Global CSS entrypoints, reset/base styles, cascade layer strategy, token files, theme config, component CSS, parent layout styles, browserslist, build config, and style lint config.
+- Existing responsive, dark mode, accessibility, focus, reduced-motion, breakpoint, and design-token conventions.
+- Target surfaces for narrow viewports, 200% zoom, text scaling, delayed media, third-party markup, and browser compatibility.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Identify the cascade layer, selector scope, token source, layout constraints, and browser target before editing.
+- Prefer low-specificity selectors, parent layout fixes, and existing semantic tokens.
+- Identify whether the style belongs in global CSS, token/theme CSS, component-scoped CSS, CSS Modules, or a third-party wrapper.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add styles in the correct layer or module.
+- Use class-level selectors, custom properties, design tokens, intrinsic sizing, flex, grid, container queries, or media queries according to local patterns.
+- Preserve visible focus, contrast, text scaling, reduced motion, and reserved space for late-loaded media.
+- Use narrow exceptions for legacy/third-party markup, runtime geometry, rich text/prose wrappers, and urgent accessibility overrides when lower-specificity or token-based fixes cannot solve the issue.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read global style entrypoints, tokens, component styles, parent layout styles, and build/lint config.
+2. Map the cascade: reset, base, tokens, layout, components, utilities, overrides.
+3. Do not patch visible symptoms with stronger specificity. Resolve conflicts by checking layer order, import order, token choice, component boundary, parent layout, and selector scope first.
+4. Do not add ID selectors for styling, selectors with more than two combinators, or new `!important` unless an allowed exception is documented.
+5. Do not use negative margin to repair normal content flow. Fix parent layout, spacing, alignment, or intrinsic sizing instead.
+6. Do not add inline styles for color, spacing, typography, focus, dark mode, or responsive layout. Inline styles are for runtime geometry such as drag positions, virtualized offsets, and measured canvas/SVG values.
+7. Use existing color, spacing, font, radius, shadow, z-index, and breakpoint tokens before adding literals.
+8. Keep raw color values out of component CSS. Add or reuse semantic tokens for surfaces, text, borders, actions, danger states, focus, disabled states, and dark mode.
+9. Avoid raw pixel values for typography, spacing, layout dimensions, and radius. Allow narrow values such as one-pixel borders, intrinsic icon/media dimensions, and established breakpoint tokens.
+10. Make layout responsive through constraints, `min-width: 0`, min/max sizing, flex/grid, wrapping, gap, intrinsic media dimensions, container/media queries, and content-based rules rather than fixed viewport assumptions.
+11. Do not set fixed width on page, section, container, card, modal, or form layouts. Do not set fixed height on components that contain text.
+12. Do not use viewport-only typography. Use bounded responsive type patterns that survive small screens and large displays.
+13. Do not use `overflow: hidden` to hide layout bugs. Allow it only for intentional clipping such as avatars, media crops, masks, or animation containers.
+14. Reserve dimensions or aspect ratio for images, videos, iframes, ads, embeds, skeletons, fonts, and lazy content that could cause layout shift.
+15. Preserve visible focus, sufficient contrast, 200% text resize behavior, text-spacing stress, keyboard navigation, and reduced-motion behavior.
+16. If hover styling changes an interactive affordance, provide a matching focus-visible affordance.
+17. Prefer outline and outline-offset for focus indicators. Do not rely only on shadows when ancestors may clip overflow.
+18. Respect reduced motion for parallax, large transforms, auto-scroll, route transitions, autoplay carousels, skeleton shimmer, and looping decorative animation.
+19. Check browser compatibility before adding new CSS features. Use progressive enhancement for newly available features and avoid limited-availability features unless the project browser target allows them.
+20. Choose configured verification intents that cover style lint, build, visual states, accessibility, and browser target risk when available.
+
+<!-- mustflow-section: cascade-specificity-policy -->
+## Cascade And Specificity Policy
+
+- Keep component styling overrideable with low-specificity class selectors.
+- Do not use IDs as styling weight. IDs are for anchors, form/ARIA relationships, or JavaScript hooks.
+- Do not write DOM-path selectors that break when markup gains or loses a wrapper.
+- Use low-specificity contextual selectors for rich text or CMS areas. Prefer patterns that keep specificity easy to override.
+- Do not add global overrides for local component problems when component-scoped styling or tokens can solve the issue.
+- New `!important` requires an explicit exception for immutable third-party/legacy markup, third-party inline style override, urgent accessibility protection, or equivalent narrow reason.
+
+<!-- mustflow-section: responsive-layout-policy -->
+## Responsive Layout Policy
+
+- Layout must survive narrow screens, 200% zoom, increased text size, longer localized text, delayed media loading, and reduced motion.
+- Prefer fluid width plus max constraints over fixed width.
+- Prefer min-height, padding, and line-height over fixed height for text-containing controls.
+- Prefer content-based layout, flex/grid, `minmax`, wrapping, and `clamp` over breakpoint patching.
+- Avoid `100vw` except for deliberate full-bleed designs; otherwise prefer normal containing-block width.
+- Avoid absolute positioning for normal document flow. Use it only for overlays, decorative placement, controls anchored to known boxes, or measured geometry.
+
+<!-- mustflow-section: token-accessibility-policy -->
+## Token And Accessibility Policy
+
+- Name visual values by role, not by raw color or numeric value.
+- Search existing tokens before adding a value. If a new value has product meaning, theme impact, repeated use, or dark-mode behavior, add it at the token source.
+- Body text and normal UI text should meet the project contrast target; large text and meaningful non-text UI indicators must remain distinguishable against adjacent colors.
+- Do not communicate state by color alone. Pair color with text, icon shape, border, position, or another non-color signal when meaning matters.
+- Never remove focus indication without replacing it in the same change.
+- Verify focus, error, selected, disabled, hover, active, and dark-mode states when token or component color changes.
+
+<!-- mustflow-section: browser-compatibility-policy -->
+## Browser Compatibility Policy
+
+- New CSS features require browser-target awareness before use.
+- Widely supported features may be used normally.
+- Newly available features need a fallback or progressive enhancement path.
+- Limited-availability features are blocked unless the repository browser target explicitly allows them.
+- Feature queries are enhancements only. Keep an accessible fallback outside the query and layer the new behavior inside it.
+
+<!-- mustflow-section: exception-policy -->
+## Exception Policy
+
+Allowed exceptions include:
+
+- Legacy or third-party markup that cannot be changed.
+- Runtime geometry such as drag positions, virtualized list offsets, canvas/SVG measurements, or measured transforms.
+- Accessibility emergency overrides such as focus visibility or reduced-motion protection.
+- Rich text, CMS, or prose styling scoped to a wrapper with low specificity.
+- Essential two-dimensional layouts such as data tables, maps, diagrams, code blocks, canvas, games, and design tools.
+
+Every exception must explain why a lower-specificity, token-based, or layout-level fix is not enough and must include a removal condition when practical.
+
+<!-- mustflow-section: review-rejection-criteria -->
+## Review Rejection Criteria
+
+Reject the change when:
+
+- It adds styling ID selectors, long descendant chains, or unexplained `!important`.
+- It repairs normal document flow with negative margins or absolute positioning.
+- It uses fixed width for containers or fixed height for text-containing UI.
+- It hides layout bugs with `overflow: hidden`.
+- It adds unsized media, embeds, ads, or lazy content that can shift layout.
+- It hardcodes raw component colors, spacing, font sizes, radius, or shadows without an exception.
+- It removes focus styling, creates hover-only affordances, or clips the focus indicator.
+- It adds motion without reduced-motion behavior.
+- It uses a new CSS feature without compatibility/fallback review.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Selectors remain maintainable and low-specificity.
+- Tokens are used or new literals are justified.
+- Responsive, zoom, text-scaling, focus, contrast, motion, compatibility, and layout-shift risks are checked or reported.
+- Exceptions are narrow, explained, and not used as a normal styling path.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing visual, accessibility, or browser compatibility verification intents when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a style requires `!important` or high specificity, inspect the cascade conflict before adding it.
+- If a raw token is missing, report whether a token should be added or the existing system should be reused.
+- If visual verification is unavailable, report the unverified viewport, zoom, contrast, or motion states.
+- If layout only works for the current screenshot, stop and rework it around content, constraints, and parent layout.
+- If a new CSS feature fails in the target browser or WebView, add a fallback or remove the feature.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Cascade, token, and responsive notes
+- Accessibility and layout-stability notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining CSS risk

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

@@ -0,0 +1,179 @@
+---
+mustflow_doc: skill.dart-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: dart-code-change
+description: Apply this skill when Dart source, pub package metadata, null safety, async Futures or Streams, isolates, analyzer lints, tests, CLI entry points, or public package APIs are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.dart-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Dart Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Dart null-safety, async, stream, isolate, package API, analyzer, and test boundaries. Treat `!`, `late`, `dynamic`, broad casts, `.cast<T>()`, `.asBroadcastStream()`, and `unawaited()` as risk markers, not fixes.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.dart`, `pubspec.yaml`, `analysis_options.yaml`, lockfiles, `lib`, `bin`, `test`, `example`, or public exports change.
+- The task touches nullable types, `!`, `late`, `dynamic`, casts, raw generics, `Future`, `Stream`, `StreamController`, `StreamSubscription`, isolates, analyzer lints, pub package layout, package exports, `bin` entrypoints, README examples, or package versioning.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is Flutter widget or platform UI behavior; use `flutter-code-change` and this skill only as an adjunct for shared Dart package/API risk.
+- Dart files are read only for orientation.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- `pubspec.yaml`, analyzer config, package layout, public export files, `lib/src` exports, examples, README snippets, CLI entrypoints, tests, and lockfile policy.
+- Existing null-safety, async, exception, and package API conventions.
+- SDK constraints, dependency constraints, executables, public dependency types, and versioning policy when package API changes.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Identify whether the change affects public exports, `lib/src` exposure, internal implementation, CLI behavior, async lifecycle, package metadata, or tests.
+- Treat nullable values, decoded data, map lookups, user input, streams, subscriptions, ports, and isolate messages as boundaries that need explicit ownership and validation.
+- Classify any public nullability, callback, `Future<T>`, `Stream<T>`, generic bound, or default-value change before editing.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Narrow nullable values at boundaries and keep core logic non-null where truthful.
+- Use `unawaited` only when detached behavior is intentional, documented, and has local error handling.
+- Cancel subscriptions, close controllers, and document isolate message shape where relevant.
+- Keep public API changes synchronized with examples and docs.
+- Strengthen analyzer boundaries when the project already uses strict linting; do not weaken analyzer or lint rules to pass the current patch.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read package metadata, analyzer config, public exports, nearby implementation, tests, and examples.
+2. Classify the touched boundary: nullability, public API, package layout, async `Future`, `Stream`, isolate, exception mapping, or test-only.
+3. Identify every nullable boundary: JSON decode, HTTP response, DB row, environment variable, CLI args, platform channel, isolate message, external callback, cache miss, map lookup, and dependency lookup.
+4. Accept external or decoded data as `Object?` at the boundary, validate it in a parser or codec layer, and let only typed domain objects leave that boundary. Do not let `dynamic` flow into internal code.
+5. Distinguish missing optional data from invalid required data. Optional business facts may stay nullable; required facts should be validated once and remain non-nullable afterward.
+6. Do not use `!`, `dynamic`, `late`, broad `as` casts, raw generic types, or `.cast<T>()` as shortcuts around design uncertainty.
+7. Allow `!` only when the same local block has a visible guard proving non-null and flow analysis cannot express it. Prefer early return, throw, or local-variable promotion.
+8. Avoid `late` fields for initialization-order problems. Prefer constructor injection, async factory construction, explicit state objects, or stored `Future<T>` initialization. `late final` still needs read-after-initialize evidence when public behavior depends on it.
+9. Replace broad JSON and collection casts with checked parsers that report the failing field path when feasible.
+10. Ensure every `Future` is awaited, returned, stored for later awaiting or cancellation, or intentionally detached with documented `unawaited` plus local error handling.
+11. Use `Future<void>` for public async APIs that complete later or can fail but do not produce a value. Avoid public `void async` except where a framework callback type requires it.
+12. Ensure every stream subscription, controller, sink, timer, socket, file watcher, receive port, or isolate has an owner and explicit shutdown path. Await cleanup futures when the API exposes them.
+13. Do not use `.asBroadcastStream()` to hide accidental multiple listens. Determine whether the source is truly broadcast, or create an explicit fan-out owner.
+14. For `StreamController`, connect external resource creation and pause/resume/cancel behavior to the controller lifecycle when buffering or resource usage matters.
+15. For `async*` functions wrapping external resources or upstream subscriptions, release resources in a `finally` path.
+16. For long-lived isolates, define startup, request and response message shapes, error propagation, shutdown messages, receive-port closing, and isolate termination.
+17. Do not import another package's `src` implementation. Treat symbols exported from this package's public libraries as public API even when their files live under `lib/src`.
+18. If public exports change, update examples, README snippets, CLI smoke surfaces, and tests that represent consumer behavior when present.
+19. Choose configured verification intents that cover analyzer, formatting, tests, package build, dependency bounds, publish dry-run, examples, CLI behavior, and public API risk when available.
+
+<!-- mustflow-section: null-safety-policy -->
+## Null-Safety Policy
+
+- `!`, `late`, `dynamic`, broad `as`, raw generic types, `.cast<T>()`, and nullable-to-non-nullable casts are risk markers.
+- Nullable values should be narrowed at the boundary. Core domain objects should be non-nullable when the value is required.
+- `Object?` is preferred over `dynamic` for raw external input because it forces validation before use.
+- Required fields that are missing should fail at the parser or constructor boundary. Do not make required domain fields nullable only to avoid validation.
+- `late` should not hide initialization order. Use it only when local construction or framework lifecycle makes the initialization proof clear and the risk is reported.
+- Public API nullability changes require compatibility classification before version changes.
+
+<!-- mustflow-section: async-resource-policy -->
+## Async And Resource Policy
+
+- Every future expression must be awaited, returned, stored for later awaiting or cancellation, or intentionally detached with documented `unawaited` and local error handling.
+- `unawaited` must not be used only to silence analyzer warnings. Detached work needs an error sink and a reason.
+- `Future` error handling should be attached before the future completes; prefer straightforward `await` with try/catch where local recovery is needed.
+- Every `StreamSubscription` needs an owner and a lifecycle method that cancels it.
+- Every `StreamController`, sink, timer, socket, watcher, port, or isolate needs an explicit close, cancel, kill, or shutdown path.
+- Long-lived isolates must define message contracts, errors, shutdown, port ownership, and termination behavior.
+
+<!-- mustflow-section: public-api-policy -->
+## Package Public API Policy
+
+Public surface includes importable files under `lib`, exports from the main library, exported `lib/src` symbols, public classes, functions, typedefs, extensions, enums, constructors, fields, getters, setters, generic bounds, callback signatures, future and stream element types, documented errors, and `bin` executables.
+
+- Do not treat `lib/src` as public unless a public library exports it.
+- Do not import another package's `lib/src`.
+- Nullability, required named parameters, default values, generic bounds, callback signatures, `Future<T>` and `Stream<T>` element types, dependency types in public signatures, CLI args, stdout/stderr shape, and exit codes are compatibility-sensitive.
+- If a public API exposes a dependency type, dependency constraints become part of the public contract. Check lower-bound and upper-range compatibility when configured verification exists.
+- README and `example` code are consumer smoke surfaces. Keep them aligned with public API changes.
+- CLI entries under `bin` are public behavior. Command names, args, exit codes, and output formats need compatibility review.
+
+<!-- mustflow-section: rejection-criteria -->
+## Review Rejection Criteria
+
+Reject or revise the patch when any of these appear without explicit evidence and risk reporting:
+
+- New `!`, `late`, `dynamic`, raw generic types, broad `as`, `.cast<T>()`, nullable-to-non-nullable casts, or analyzer ignores used only to make errors disappear.
+- Decoded JSON, platform messages, isolate messages, CLI args, environment values, map lookups, or external callbacks trusted without boundary parsing.
+- Required domain values made nullable instead of validating the boundary.
+- A future expression is neither awaited, returned, stored, nor intentionally detached with error handling.
+- Public `void async` is added where `Future<void>` would preserve completion and error signaling.
+- Stream subscriptions, controllers, ports, timers, sockets, watchers, or isolates are created without cleanup ownership.
+- `.asBroadcastStream()` is used to hide a design problem around multiple listeners.
+- Public nullability, generic bound, callback, `Future<T>`, `Stream<T>`, export, CLI, SDK constraint, dependency constraint, or executable behavior changes without compatibility classification.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Nullability and async ownership are explicit.
+- Public package API impact is known.
+- Analyzer and tests were preserved or skipped with reason.
+- No safety boundary was hidden behind `!`, `dynamic`, `late`, casts, `unawaited`, or analyzer ignores without a risk note.
+- Examples, README snippets, CLI entrypoints, and package metadata are synchronized when public behavior changes.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing package publish or analyzer verification intents rather than inventing tool commands.
+
+When the repository exposes configured intents for these surfaces, cover strict analyzer checks, tests, package dry-run, dependency lower and upper bound checks, example or README analysis, CLI smoke behavior, and consumer-style public-import checks.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If nullable data cannot be narrowed safely, report the missing validation boundary.
+- If stream or isolate lifetime is unclear, avoid adding more asynchronous ownership until the owner is identified.
+- If public API compatibility is unclear, report the consumer risk and the changed public symbols or executables.
+- If analyzer/lint rules block the patch, fix the code or report the real boundary issue instead of weakening analysis.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Nullability, async, stream, or API notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Dart risk

package/templates/default/locales/en/.mustflow/skills/database-migration-change/SKILL.md

@@ -0,0 +1,178 @@
+---
+mustflow_doc: skill.database-migration-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: database-migration-change
+description: Apply this skill when database migration files, schema migration history, ORM schema migrations, generated clients, schema dumps, SQL snapshots, backfills, rolling deploy compatibility, expand-and-contract changes, destructive database changes, migration rollback claims, or production database migration procedures are created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.database-migration-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Database Migration Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep database migrations safe for running systems by checking deploy compatibility, data preservation, backfill behavior, generated artifacts, ORM contracts, and rollback reality.
+
+Do not treat migration authoring as "make a file that applies locally." Treat it as "old code and new code must survive the same database during rollout."
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A database migration file, migration history entry, schema dump, ORM schema, SQL snapshot, generated client, seed, fixture, schema validator, or migration documentation is created or changed.
+- A change adds, removes, renames, splits, merges, backfills, rewrites, validates, constrains, indexes, foreign-keys, type-changes, defaults, nullable rules, enum values, tables, columns, generated columns, triggers, views, functions, row-level policies, or data migrations.
+- A task mentions rolling deploy, expand-and-contract, online migration, backfill, production schema change, rollback, down migration, migration lock, DDL transaction, generated ORM client, migration drift, schema drift, or database migration safety.
+- Prisma, Drizzle, TypeORM, Rails Active Record, Django migrations, Alembic, Diesel, Ecto, Flyway, Liquibase, Knex, Sequelize, SQLx, or another migration tool changes schema, generated output, migration metadata, or deployment behavior.
+- A final report claims a database migration is safe, reversible, applied, validated, production-ready, no-downtime, rollback-safe, or tested from an old schema.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change only edits query logic or persisted data model code without a migration, generated schema artifact, or migration claim; use `database-change-safety`.
+- The migration is not database-backed, such as file layout, template, cache, content, URL, export, import, or platform migration; use `migration-safety-check`.
+- The task only discusses database design without changing or reporting migration behavior.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Source schema, target schema, migration files, migration history table or metadata, generated clients, schema dumps, SQL snapshots, seeds, fixtures, and affected queries.
+- Migration tool and ecosystem: Prisma, Drizzle, TypeORM, Rails, Django, Alembic, Diesel, Ecto, Flyway, Liquibase, Knex, Sequelize, SQLx, raw SQL, or another declared tool.
+- Deployment shape: single-step deploy, rolling deploy, blue-green, multiple app versions, background workers, read replicas, multiple services, serverless functions, mobile clients, or external integrations.
+- Database engine and operational surface: PostgreSQL, MySQL, SQLite, SQL Server, managed database, migration lock behavior, DDL transaction behavior, online DDL options, table size, expected lock time, statement timeout, lock timeout, and restore capability when known.
+- Data preservation needs, compatibility window, backfill size, batch strategy, restart marker, validation query, rollback type, and whether old code can run after the new schema lands.
+- Relevant command-intent entries for build, generated-output checks, tests, docs, release, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- The migration is classified before editing as expand, backfill, switch, contract, destructive, data-only, schema-only, generated-output-only, ORM metadata-only, or rollback documentation.
+- If personal data, tenant isolation, authorization, audit, retention, or secrets are involved, also use `security-privacy-review`.
+- If public API response shape changes because of the migration, also use `api-contract-change`.
+- If file paths or storage keys change with the database migration, also use `file-path-cross-platform-change`.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update migration files, ORM schema files, generated client expectations, schema dumps, SQL snapshots, seeds, fixtures, compatibility code, backfill code, validation checks, docs, and tests directly required by the migration.
+- Prefer expand-and-contract for live systems: add compatible shape, backfill safely, switch reads and writes, then contract only after compatibility is proven.
+- Keep destructive cleanup separate from expansion unless the repository explicitly proves a single-step deployment is safe.
+- Do not weaken tests, delete migration history, hand-edit generated client output, suppress migration drift, or claim rollback safety for lossy changes.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the migration surface: schema DDL, data migration, backfill, generated client, schema dump, ORM metadata, seed, fixture, migration docs, or deploy procedure.
+2. Read the tool-specific source of truth before editing.
+   - Prisma: schema file, migrations directory, generated client use, migration history expectations, production deploy flow, and drift behavior.
+   - Drizzle: schema exports, generated SQL, snapshot or meta files, migration journal, generated client or query types, and runtime schema imports.
+   - TypeORM: entity metadata, migration files, data-source config, production synchronization setting, generated SQL, and runtime entity loading.
+   - Rails: migration files, schema dump, model validations, historical migration model usage, seeds, fixtures, callbacks, and deploy order.
+   - Django: migration files, state operations, historical models, schema editor behavior, generated SQL when relevant, and data migration functions.
+   - Alembic or SQLAlchemy: migration revisions, autogenerate output, branch heads, model metadata, downgrade functions, naming conventions, and generated SQL.
+   - Diesel, Ecto, Flyway, Liquibase, Knex, Sequelize, SQLx, and raw SQL: migration history, checked-in SQL, generated metadata, compile-time query checks, rollback files, and schema dumps.
+3. Build a migration ledger: old shape, new shape, rows affected, old code behavior, new code behavior, rollback expectation, generated artifact changes, dependent callers, and validation query.
+4. Classify compatibility.
+   - Old code on old schema.
+   - Old code on expanded schema.
+   - New code on expanded schema.
+   - New code after backfill.
+   - New code after contract.
+   If any required state fails, the migration is not rolling-deploy safe.
+5. For column add, decide nullability, default behavior, backfill strategy, write path, read fallback, index need, and when a future `NOT NULL` or constraint can be enforced.
+6. For column drop, first prove all reads, writes, generated clients, old app versions, jobs, analytics, exports, seeds, fixtures, docs, and external consumers stopped using the column. Treat drop as a contract phase, not as the first migration.
+7. For rename, do not implement rename as drop plus add unless data loss is explicitly intended and approved. Prefer add new column, dual-write or copy, backfill, switch reads, validate, then drop old column later.
+8. For type changes, check whether the database rewrites the table, whether old values can fail conversion, whether indexes or constraints rebuild, whether application serializers change, and whether API or generated client types change.
+9. For nullable and default changes, distinguish schema default from application default. Avoid assuming existing rows are backfilled by a new default.
+10. For constraints and foreign keys, use staged validation when the database supports it. Add the constraint without validating existing rows when appropriate, backfill or repair data, then validate in a separate phase.
+11. For indexes, check table size, write load, lock behavior, concurrent or online index support, uniqueness validation, existing duplicates, and whether generated ORM queries will use the index.
+12. For enum changes, check old code behavior, generated client unions, database enum migration limits, default values, serialization, API compatibility, and whether removing or renaming values requires a data migration first.
+13. For table split, table merge, or relationship rewrite, preserve stable identifiers, foreign keys, audit references, external IDs, permissions, search documents, exports, and old-to-new mapping until all callers switch.
+14. For backfills, make them bounded, restartable, observable, and validated. Define batch size, ordering key, checkpoint, retry behavior, idempotency, timeout, lock expectation, dead-letter or manual review behavior, and validation queries.
+15. Do not run or recommend full-table updates on production-sized data without measured volume, lock expectation, batch plan, timeout policy, and recovery plan.
+16. Keep external side effects out of database migrations unless the repository has an explicit recovery model. Sending emails, calling payment APIs, deleting files, or mutating external providers from a migration usually breaks rollback.
+17. Check generated surfaces after schema changes: ORM clients, types, SQL snapshots, schema dumps, OpenAPI or GraphQL projections, API mocks, fixtures, seeds, admin screens, analytics, ETL, BI queries, and docs examples.
+18. Review ORM-specific traps.
+   - Prisma generated client and migration history must match the migration files that production applies.
+   - Drizzle schema exports and generated SQL or snapshots must not drift.
+   - TypeORM production `synchronize` must not be used as a migration strategy.
+   - Django rename detection and autogeneration must be reviewed so rename does not become delete and create.
+   - Alembic autogenerate output is a candidate, not a reviewed migration.
+   - Rails migrations should not depend on current model callbacks or validations when historical data can outlive current model code.
+19. Decide rollback honestly.
+   - Reversible: schema-only and data-preserving.
+   - Forward-fix preferred: partial live migration can be corrected without restoring.
+   - Restore required: deletes, table merges, generated IDs, hashing, encryption, irreversible type conversions, external side effects, or lossy transforms.
+   Do not promise rollback for changes that cannot reconstruct old values.
+20. Rehearse from the previous production-like schema when possible. A migration that only applies to a freshly generated schema is not enough.
+21. Check dependent surfaces: application code, background jobs, cron tasks, workers, ETL, reports, admin tools, data exports, imports, mobile or older clients, webhooks, API clients, generated SDKs, test fixtures, seeds, docs, and monitoring.
+22. Select verification from the command contract. Major schema changes, generated client changes, rollback-sensitive changes, security-sensitive migrations, and production deployment changes need broader verification than local schema-only edits.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Source schema, target schema, migration files, generated artifacts, schema dumps, seeds, fixtures, and dependent code agree.
+- Expand, backfill, switch, and contract phases are separated or explicitly proven unnecessary.
+- Old-code/new-schema and new-code/expanded-schema compatibility is classified.
+- Backfill and validation behavior is bounded, restartable, and checkable where relevant.
+- Rollback claims distinguish schema rollback, data rollback, app rollback, forward-fix, and restore-required cases.
+- Destructive changes and production lock risks are either deferred, measured, or reported as remaining risk.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer configured migration dry-run, generated-output, schema-diff, or database test intents when the command contract exposes them. Do not invent raw migration commands inside the skill.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If old/new application compatibility is unknown, do not call the migration rolling-deploy safe.
+- If production table size, lock behavior, or validation cost is unknown, report the operation as production-risky.
+- If an autogenerator proposes drop/create for a rename, stop and rewrite the migration plan.
+- If a migration is lossy, do not claim rollback beyond restore or forward corrective migration.
+- If generated clients or schema dumps drift, fix the source of truth and regenerated surfaces together.
+- If configured verification is missing, report the missing command intent instead of inferring package-manager, ORM, or migration-tool commands.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Database migration changed
+- Tool and database engine surface inspected
+- Source schema, target schema, and migration phase
+- Old-code/new-schema and new-code/expanded-schema compatibility
+- Backfill, validation, lock, timeout, and rollback classification
+- ORM/generated client/schema dump/snapshot surfaces synchronized
+- Dependent surfaces checked
+- Command intents run
+- Skipped migration checks and reasons
+- Remaining database migration risk