mustflow 2.22.17 → 2.22.47

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

@@ -0,0 +1,151 @@
+---
+mustflow_doc: skill.dependency-upgrade-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: dependency-upgrade-review
+description: Apply this skill when dependency versions, lockfiles, package manager metadata, security advisory fixes, generated dependency outputs, runtime engine constraints, peer dependency contracts, framework plugins, CI actions, Docker base images, or toolchain versions are upgraded, downgraded, pinned, widened, regenerated, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.dependency-upgrade-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Dependency Upgrade Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review dependency upgrades as runtime, build, security, package, and generated-output contract changes rather than as version-number edits.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A dependency version is upgraded, downgraded, pinned, unpinned, widened, narrowed, replaced, or removed.
+- A lockfile, package manager metadata, workspace constraint, runtime engine, peer dependency, optional dependency, feature flag, or generated dependency output changes.
+- A security advisory, vulnerability scanner, Dependabot, Renovate, package audit, language audit, CI action update, Docker base image update, framework plugin update, formatter/linter/bundler update, ORM update, code generator update, protobuf/OpenAPI generator update, or toolchain update is reviewed or applied.
+- A task claims a dependency change is "only patch", "only devDependency", "safe minor", "security-only", "transitive only", "lockfile only", or "no runtime change".
+- A dependency update touches installation, publish output, generated clients, SDKs, native binaries, browser bundles, serverless or edge runtime, ESM/CJS/module format, Python markers, Go module graph, Cargo features, JVM dependency mediation, .NET target frameworks, Ruby/PHP/Swift lockfiles, Docker images, or CI actions.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- A brand-new dependency is proposed without upgrading an existing declaration; use `dependency-reality-check` first.
+- Code imports or invokes an existing dependency but no dependency metadata, lockfile, runtime version, generated output, or package-manager contract changes.
+- The task only updates prose that mentions a dependency and does not assert supported versions, install commands, runtime behavior, security status, or package metadata.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The dependency or tool being changed, old version or range, new version or range, direct or transitive status, and reason for the change.
+- Ecosystem and package manager: JavaScript or TypeScript, Python, Go, Rust, JVM, .NET, Ruby, PHP, Swift, Docker, CI actions, or another declared system.
+- Package declarations, lockfiles, workspace files, runtime-version files, package-manager config, toolchain files, CI/Docker files, generated outputs, and command contract entries.
+- Release notes, migration notes, changelog, advisory range, fixed range, compatibility notes, or local issue evidence when available from approved context.
+- Impacted runtime paths, build paths, test paths, generated clients, mocks, fixtures, docs examples, deployment images, and package publish output.
+
+<!-- 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 upgrade is classified before editing as patch, minor, major, pre-1.0, security fix, transitive-only, toolchain-only, generated-output, runtime-engine, CI-image, or broad refresh.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Align dependency declarations, lockfiles, generated outputs, compatibility code, tests, docs, and package metadata that are directly required by the upgrade.
+- Prefer the minimum version change that satisfies the feature or advisory.
+- Keep unrelated modernization, formatting churn, dependency family refreshes, and broad package-manager rewrites out of a narrow upgrade.
+- Do not delete and recreate lockfiles to hide the dependency graph change.
+- Do not weaken tests, scanners, coverage gates, type checks, peer warnings, engine checks, or generated-output assertions to make an upgrade pass.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the upgrade and classify it: direct or transitive, runtime or development, patch/minor/major/pre-1.0/security/toolchain/generated/CI-image, and narrow or broad.
+2. Identify the ecosystem and read the matching declaration surfaces.
+   - JavaScript and TypeScript: package metadata, lockfile, workspace files, package-manager config, runtime version, TypeScript config, bundler/framework/test config, generated clients, and publish files.
+   - Python: project metadata, dependency groups, constraints, lockfiles, requirements files, Python version files, test matrix, build backend, and packaging output.
+   - Go: module files, workspace file, checksum file, vendored module metadata, generated code hooks, tool dependencies, and toolchain expectations.
+   - Rust: manifest, lockfile, toolchain file, cargo config, features, default features, target-specific dependencies, build scripts, generated bindings, and crate publish surface.
+   - JVM, .NET, Ruby, PHP, Swift: manifests, lockfiles, package-manager wrappers, toolchain files, dependency mediation rules, generated artifacts, and publish metadata.
+   - Docker and CI: base image tags or digests, action versions, setup-tool versions, cache keys, matrix versions, deployment image metadata, and runtime smoke surfaces.
+3. Build a dependency ledger before editing: old version, new version, direct or transitive path, source registry or image source, lockfile entry, integrity or checksum, engine or platform requirement, peer or feature changes, optional or platform-specific packages, and generated-output changes.
+4. For patch upgrades, verify that the patch does not change runtime defaults, parser strictness, security behavior, peer requirements, engine support, native binaries, module format, generated output, or install scripts.
+5. For minor upgrades, read release notes or migration notes when available. Check new defaults, deprecations, peer and engine changes, plugin compatibility, generated output, bundle size, runtime adapter behavior, and framework integration behavior.
+6. For major upgrades, treat the change as a migration. Require migration notes, public API change classification, config schema review, CLI flag review, plugin API review, codemod or manual migration notes, full caller review, rollback plan, and broad verification.
+7. For pre-1.0 or calendar-versioned packages, do not trust SemVer labels. Classify risk by actual contract changes and release notes.
+8. For security upgrades, keep the patch narrow. Identify advisory id, affected range, fixed range, direct or transitive path, exploit-relevant code path, minimum patched version, scanner recheck, and whether stricter validation, escaping, TLS, redirect, auth, or parser behavior can break callers.
+9. Review the lockfile as a graph, not a blob. Check direct and transitive replacements, newly introduced packages, removed packages, optional/platform packages, source URLs, integrity or checksum changes, peer resolution, engine requirements, native prebuilds, and postinstall or lifecycle scripts.
+10. Review runtime boundaries that dependency upgrades commonly break: ESM/CJS and package `type`, `exports` and conditional exports, browser/node/edge conditions, Node engine support, Python dependency markers and extras, Go module path changes, Cargo feature unification, native builds, SSR/client split, WebView/native split, and generated client or SDK types.
+11. Treat framework, plugin, code generator, formatter, linter, bundler, ORM, protobuf, OpenAPI, GraphQL, database driver, and test-runner upgrades as behavior changes when their output, config schema, plugin API, CLI flags, or generated code can change.
+12. For new dependencies introduced by the upgrade, invoke the `dependency-reality-check` decision path: license, maintainer risk, provenance, lifecycle scripts, binary downloads, package age, transitive size, supply-chain risk, and replacement path.
+13. For Docker base images and CI actions, review them as dependencies. Check image/action source, version pinning policy, digest use when required, runtime version changes, security patch reason, cache impact, and deployment smoke coverage.
+14. Synchronize dependent surfaces: generated code, snapshots, mocks, fixtures, examples, SDK clients, OpenAPI or GraphQL artifacts, README install guidance, migration docs, changelog, Docker/CI docs, and package publish metadata.
+15. Select verification from the command contract based on risk. Patch and narrow transitive changes can use focused checks when they cover the touched path; major, framework, runtime-engine, generated-output, security-sensitive, Docker, or CI-action updates need broader checks.
+16. Report skipped checks explicitly. If the command contract lacks a dependency graph or package verification intent, do not invent raw package-manager commands; report the missing configured intent.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The final state shows exactly which dependency contract changed and why.
+- The lockfile and declaration files agree.
+- Direct and transitive changes are understood, not hidden behind lockfile volume.
+- Runtime engine, peer dependency, optional/platform package, feature, module-format, generated-output, and publish-surface risks are classified.
+- Security fixes are narrow unless the user explicitly accepted a broader modernization.
+- Tests and scanners were not weakened to pass the upgrade.
+
+<!-- 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 the narrowest configured intent that proves the actual upgraded dependency path. Use broader verification for major upgrades, runtime or framework upgrades, security-sensitive dependencies, generated-output changes, publish-surface changes, Docker image changes, CI action changes, and package-manager behavior changes.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If release notes, advisory range, fixed range, or migration guidance are missing, mark the upgrade as higher risk instead of calling it safe.
+- If a lockfile diff introduces unrelated dependency churn, split the change or explain why the graph update is necessary.
+- If peer dependency, engine, optional dependency, native build, or platform warnings appear, resolve or report them. Do not dismiss them because the local machine passed.
+- If tests fail after an upgrade, do not delete tests, skip tests, loosen assertions, lower coverage, disable scanners, or widen permissions unless the behavior contract intentionally changed and the report says so.
+- If a security upgrade requires broad modernization, split the minimum patch from the modernization when possible.
+- If generated output changes, regenerate from the official generator path and explain the generated diff. Do not hand-edit generated dependency output.
+- If configured verification is missing, report the missing command intent instead of inferring a package-manager command.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Dependency upgraded and reason
+- Ecosystem and package manager surface inspected
+- Direct and transitive graph changes
+- Compatibility classification: patch, minor, major, pre-1.0, security, toolchain, generated-output, Docker, or CI action
+- Runtime, peer, engine, module, feature, platform, generated-output, and publish-surface risks
+- Security advisory and fixed-range notes when relevant
+- Surfaces synchronized
+- Command intents run
+- Skipped dependency checks and reasons
+- Remaining dependency upgrade risk

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

@@ -0,0 +1,115 @@
+---
+mustflow_doc: skill.elysia-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: elysia-code-change
+description: Apply this skill when Elysia routes, schemas, plugins, decorators, derives, guards, auth, error handling, OpenAPI output, Eden clients, or Bun server behavior are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.elysia-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Elysia Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Elysia schema-first runtime validation, type inference, plugin, auth, error, OpenAPI, Eden, and Bun runtime boundaries.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `new Elysia`, route methods, `t.Object`, request or response schemas, `.use`, `.guard`, `.derive`, `.decorate`, `.onError`, auth middleware, OpenAPI, Eden, or Bun server tests change.
+- The task adds API routes, plugins, validators, error envelopes, authentication, or generated client contracts.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only edits framework-free service functions called by Elysia routes; use the relevant language or architecture skill.
+- Another web framework owns the route surface.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Package metadata, Bun lockfile if present, TypeScript config, server entrypoint, route modules, plugin modules, schema/model files, auth/session files, error handling, OpenAPI config, Eden client exports, and tests.
+- Existing response envelope, status-code contract, and strict TypeScript policy.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Identify whether schema is the source of truth for runtime validation and type inference.
+- Inventory method, path, params, query, headers, cookies, body, response statuses, auth, and plugin/decorator dependencies.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Define request and response schemas with the route.
+- Keep framework context at the route boundary and move only framework-free business logic into services.
+- Preserve plugin, decorator, derive, and store inference through Elysia chaining.
+- Keep OpenAPI and Eden clients aligned with route schemas when present.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read server entry, routes, plugins, schemas, auth, error handling, OpenAPI, Eden exports, and tests.
+2. Build a route inventory for the changed surface.
+3. Add or update schemas for every external input and meaningful response status.
+4. Do not annotate handlers with broad `any`, duplicated manual interfaces, or imported `Context` types that erase inference.
+5. Keep request-specific state out of module-level mutable globals.
+6. Centralize expected error envelope and auth failure behavior.
+7. If OpenAPI or Eden is used, confirm the generated contract follows the schema change.
+8. Choose configured verification intents that cover types, server boot, route happy path, validation failure, auth failure, OpenAPI, and Eden inference when available.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Schemas, runtime validation, and inferred types remain one contract.
+- Error and auth responses are consistent.
+- OpenAPI and Eden impact is known.
+- No route relies on unvalidated input or erased context types.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing route, OpenAPI, or Eden verification intents when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If schema and manual types diverge, make schema the source of truth or report the competing contract.
+- If plugin inference breaks after extraction, return context-sensitive code to the Elysia chain or narrow the extraction.
+- If auth behavior is unclear, stop the route change and inspect or request the auth contract.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Schema and type inference notes
+- Auth, error, OpenAPI, or Eden impact
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Elysia risk

package/templates/default/locales/en/.mustflow/skills/file-path-cross-platform-change/SKILL.md

@@ -0,0 +1,147 @@
+---
+mustflow_doc: skill.file-path-cross-platform-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: file-path-cross-platform-change
+description: Apply this skill when file path handling, cross-platform path behavior, path helpers, safe filesystem wrappers, temp or cache paths, atomic writes, locks, archive extraction, uploads, downloads, scanners, CLI/API/schema path contracts, snapshots, generated outputs, or package artifact paths are created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.file-path-cross-platform-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# File Path Cross-Platform Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Treat file paths as security boundaries and operating-system contracts, not as ordinary strings.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Code accepts, stores, serializes, validates, normalizes, joins, resolves, compares, scans, extracts, uploads, downloads, writes, deletes, locks, packages, or reports paths.
+- Path behavior appears in CLI arguments, API request or response schemas, config files, snapshots, fixtures, generated output, package artifacts, logs, manifests, caches, temp directories, upload or download flows, archive extraction, or scanner output.
+- A change claims path traversal safety, base-directory containment, symlink safety, junction or reparse-point safety, archive extraction safety, atomic write behavior, durable write behavior, lock ownership, cleanup safety, deterministic scanning, or Windows/macOS/Linux compatibility.
+- A test or docs example includes paths that must behave consistently across Windows, macOS, Linux, CI, containers, archives, package artifacts, or user machines.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only changes in-memory labels and no path is interpreted by an OS, runtime, CLI, API, archive, scanner, package manager, or filesystem helper.
+- The task only changes Git line-ending policy; use `line-ending-hygiene`.
+- A generated artifact is only referenced or packaged and no path validation, path generation, or artifact path contract changes; use `artifact-integrity-check`.
+- The task is only a narrow low-level filesystem helper change with no public path contract; `cross-platform-filesystem-safety` can be used as the narrower adjunct.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Every path input and output, including user input, CLI args, API fields, config fields, archive entries, generated files, temp files, cache paths, lock files, uploaded filenames, download filenames, scanner roots, package artifact paths, and logs.
+- The path owner and trust class: user-controlled, repository-owned, generated, temp, cache, archive-contained, package artifact, external file, or unknown.
+- The base directory or allowed root, expected relative/absolute policy, symlink and reparse-point policy, case-sensitivity policy, invalid-name policy, atomic-write policy, lock policy, archive extraction policy, scanner bounds, cleanup policy, and platform expectations.
+- Current path helpers, safe filesystem wrappers, temp/cache helpers, archive helpers, upload/download helpers, scanners, schema validators, snapshots, and tests.
+- Relevant command-intent entries for build, 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.
+- Existing path helpers and safe filesystem wrappers have been inspected before adding a new helper.
+- Security and privacy review is applied first when paths can expose secrets, personal data, uploaded files, downloaded files, or files outside an owned root.
+- The path contract is classified before editing: internal helper, public CLI, public API, schema, generated output, snapshot, package artifact, archive, upload/download, scanner, temp/cache, lock, or cleanup.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update path validators, path helpers, safe filesystem wrappers, schemas, CLI parsing, API contracts, snapshots, fixtures, docs, tests, package metadata, generated-output paths, archive extraction, scanner bounds, temp/cache handling, locks, and cleanup code that are directly needed for safe path behavior.
+- Prefer existing repository path helpers and one shared path contract over ad hoc string manipulation.
+- Keep path display format stable for users and automation. Prefer repository-relative paths in output unless absolute paths are required for local diagnosis.
+- Do not broaden filesystem access, cleanup roots, scanner roots, archive extraction roots, package artifact globs, or upload/download destinations to make a path bug disappear.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Build a path ledger. List every path field, argument, helper, schema, snapshot, generated output, package artifact, archive entry, upload/download filename, scanner root, temp/cache path, lock file, and cleanup target touched by the change.
+2. Classify each path by trust and owner: trusted repository path, user input, generated state, template path, package artifact, temporary file, cache file, archive-contained path, external path, uploaded name, downloaded name, scanner root, or unknown.
+3. Define the allowed root and representation. Decide whether the contract accepts relative paths, absolute paths, URLs, file URLs, archive entry names, package-relative paths, repository-relative paths, or display-only paths.
+4. Reject dangerous path text before filesystem access: null bytes, empty names where not allowed, absolute paths where relative paths are required, dot segments where not allowed, Windows device names, drive-relative paths, UNC roots, namespace prefixes, alternate data streams, trailing dots or spaces, reserved characters, and mixed separator bypasses.
+5. Treat Windows drive-relative paths such as `C:tmp.txt` as relative to a drive current directory, not as `C:\tmp.txt`.
+6. Treat Windows reserved names as reserved even with extensions. Names such as `CON`, `PRN`, `AUX`, `NUL`, `COM1`, and `LPT1` must not become ordinary user filenames.
+7. Treat macOS and Windows case-insensitive defaults as compatibility risks. Decide whether to reject case-only collisions, preserve spelling, normalize display only, or rely on the host filesystem.
+8. Do not solve containment with string prefixes. Establish the base real path, resolve or canonicalize the candidate parent when possible, then use path-aware relative containment with a separator boundary.
+9. For new files whose final path does not exist yet, canonicalize the existing parent directory and verify that parent remains inside the allowed root.
+10. Recheck symlink, junction, reparse-point, and final-target behavior at the operation boundary where the runtime allows it. Do not claim race-free behavior from normalize-then-open code alone.
+11. For uploads and downloads, separate displayed filename from storage key. Validate extension, size, content type, magic bytes when relevant, path separators, Unicode aliasing, reserved names, collision policy, overwrite policy, and tenant or user ownership.
+12. For archive extraction, validate every entry before extraction. Reject absolute entries, parent traversal, empty names, platform-reserved names, symlink entries unless explicitly supported, hard links unless explicitly supported, duplicate or case-colliding entries, oversized entries, zip bombs, and extraction outside the target root.
+13. Do not call extract-all behavior on untrusted archives unless the helper performs per-entry validation and bounded extraction.
+14. For atomic writes, create the temporary file in the target directory on the same filesystem, use an unpredictable temp name, write, flush, close, replace or rename, and flush the parent directory when the platform and helper support it.
+15. Scope atomicity claims. Cross-filesystem moves, network filesystems, Windows sharing violations, antivirus/indexer locks, and missing directory fsync support can downgrade a claim to best effort.
+16. For Windows replace or rename failures caused by sharing violations, use bounded retry or report the platform limitation. Do not turn every transient lock into silent data loss.
+17. For locks and mutexes, define owner token, stale lock policy, crash recovery, deletion race handling, PID reuse handling, and whether the lock works on local filesystems only. Do not treat a PID file alone as proof of ownership.
+18. For scanners, set max depth, max file count, max file size, binary-file handling, ignored directories, hidden-file policy, permission-error behavior, symlink traversal policy, loop detection, deterministic ordering, and output path format.
+19. For temp and cache paths, keep them under an owned root, avoid global temp rename into a target location, include cleanup bounds, and avoid leaking user data through predictable names.
+20. For CLI, API, schema, snapshot, docs, and package artifact path changes, update every contract surface together. Path spelling, separators, slash policy, absolute/relative policy, escaping, sorting, and error messages are part of the contract.
+21. Add focused tests for the riskiest path shapes: traversal, absolute input, drive-relative input, UNC-like input, reserved names, trailing dots or spaces, case collision, symlink escape, archive traversal, duplicate archive entries, scanner loop, large file cap, and cleanup boundary.
+22. Select verification from the command contract based on risk. Public CLI/API/schema/package artifact changes need broader checks than internal helper-only changes.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Path trust classes, accepted path representation, invalid-name policy, case policy, root boundary, symlink and reparse-point policy, archive policy, upload/download policy, scanner policy, atomic-write policy, lock policy, temp/cache policy, and cleanup policy are explicit.
+- Path contracts are synchronized across helpers, schemas, CLI/API docs, snapshots, fixtures, generated outputs, package artifacts, tests, and reports.
+- Any race-safety, atomicity, durability, lock, or cross-platform claim is scoped to what the current runtime and helpers can actually guarantee.
+- Platform behavior that was not tested is 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 focused tests for helper-only path changes. Use release or package checks when CLI output, schemas, snapshots, generated outputs, package artifacts, template paths, or installed workflow files change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If root containment is unclear, stop before writing, deleting, extracting, scanning, or opening and report the ambiguous path owner.
+- If the platform cannot prove symlink-safe behavior, fail closed or report the exact remaining gap.
+- If archive entries cannot be validated before extraction, do not extract the archive.
+- If atomic replace, file fsync, parent directory fsync, no-follow open, lock ownership, or final-target verification is unavailable, downgrade the claim and keep the operation bounded.
+- If Windows, macOS, Linux, container, CI, or network-filesystem behavior differs and cannot be tested, state the untested platform boundary.
+- If cleanup might remove user data or files outside generated state, do not proceed without a tighter owned root.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Path contract changed
+- Path ledger and trust classes
+- Accepted representation and base-root policy
+- Windows, macOS, Linux, archive, upload/download, scanner, lock, temp/cache, atomic-write, and cleanup decisions
+- CLI/API/schema/snapshot/generated-output/package artifact surfaces synchronized
+- Tests or fixtures added or reused
+- Command intents run
+- Skipped platform checks and reasons
+- Remaining file path cross-platform risk

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

@@ -0,0 +1,116 @@
+---
+mustflow_doc: skill.flutter-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: flutter-code-change
+description: Apply this skill when Flutter widgets, screens, routing, state management, async UI, platform channels, assets, responsive layout, accessibility, or Flutter tests are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.flutter-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Flutter Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Flutter widget, state owner, build purity, async lifecycle, navigation, platform channel, asset, responsive layout, and accessibility boundaries.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Flutter `lib/**.dart`, widgets, screens, routing, state management, platform channels, assets, tests, integration tests, or platform project files change.
+- The task touches `StatefulWidget`, `StatelessWidget`, `setState`, `BuildContext`, navigation, `FutureBuilder`, `StreamBuilder`, controllers, subscriptions, `MethodChannel`, `pubspec.yaml` assets, or responsive layout.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is pure Dart package or CLI logic with no Flutter UI/lifecycle surface; use `dart-code-change`.
+- The task only reads Flutter code for orientation.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- `pubspec.yaml`, analyzer config, app root, route config, state management setup, target screen, parent widgets, assets, platform channel files, and tests.
+- Existing state management, navigation, accessibility, theming, and responsive layout conventions.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Identify widget tree owner, state owner, route owner, async source, platform boundary, asset declaration, and verification surface.
+- Keep `build` as UI description, not a side-effect runner.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Put network calls, subscriptions, controllers, timers, analytics, navigation side effects, and snackbars in the proper lifecycle or event boundary.
+- Use the project's existing state management and routing style.
+- Use constraints and layout information rather than device-name assumptions.
+- Dispose controllers, streams, timers, animations, and subscriptions.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read app root, route config, parent widgets, state owner, target widget, platform files, assets, and tests.
+2. Classify the change: widget layout, state, async lifecycle, navigation, platform channel, asset, accessibility, or test-only.
+3. Do not create futures, streams, controllers, listeners, or side effects inside `build`.
+4. Keep `setState` narrow and synchronous; do not put awaited work inside the `setState` callback.
+5. After async gaps, ensure the widget is still mounted before using context or state, and prefer disposing owners so dead widgets are not touched.
+6. Keep navigation consistent with the project's router.
+7. If platform channel or native permission changes, verify Dart interface, native implementation, serialization shape, and error shape together.
+8. Check small width, wide width, long text, text scaling, keyboard/open input states, and screen-reader semantics when relevant.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Widget build remains pure.
+- State owner and async lifecycle are clear.
+- Layout responds to constraints and text scaling.
+- Platform, asset, and accessibility risks are checked or reported.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing widget, integration, golden, or platform verification intents when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a lifecycle fix requires repeated mounted checks, inspect ownership and disposal before adding more guards.
+- If layout only works for one viewport, redesign with constraints before finishing.
+- If platform permissions or channels are unclear, stop that part and inspect native config.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- State, lifecycle, layout, and accessibility notes
+- Platform or asset impact
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Flutter risk