mustflow 2.99.2 → 2.103.3

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

@@ -0,0 +1,278 @@
+---
+mustflow_doc: skill.react-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: react-code-change
+description: Apply this skill when React, React DOM, React Server Components, Server Actions, React Compiler, Hooks, Suspense, Actions, forms, refs, context, concurrent rendering, SSR streaming, resource hints, package metadata, or React-related tests are created, changed, reviewed, or upgraded.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.react-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# React Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve React runtime, rendering, state, effect, compiler, server/client,
+form, resource, accessibility, and package-version contracts when changing
+React projects, especially open-source contribution patches where maintainers
+expect current React guidance and small, compatible changes.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- React components, Hooks, context, refs, Suspense boundaries, transitions,
+  deferred values, forms, Actions, optimistic UI, React DOM metadata, resource
+  hints, SSR streaming, React Server Components, Server Actions, or tests change.
+- `react`, `react-dom`, `react-server-dom-*`, `eslint-plugin-react-hooks`,
+  React Compiler, framework adapters, bundlers, JSX transforms, or React package
+  metadata changes.
+- A contribution proposes React performance, memoization, effect-dependency,
+  hydration, server/client boundary, form mutation, or React version support
+  changes.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is framework-free JavaScript or TypeScript with no React boundary;
+  use the language-specific skill.
+- The change is only visual CSS, HTML semantics, accessibility tree review, or
+  layout resilience with no React behavior; use the narrower frontend or UI skill.
+- Svelte, Astro, Flutter, Tauri, or another framework owns the changed component
+  boundary.
+- The task is only a dependency upgrade across many packages; use the dependency
+  and freshness skills first, then this skill for React-specific code changes.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- React package evidence: nearest `package.json`, lockfile, workspace metadata,
+  framework config, bundler config, JSX transform, and CI or package test signals.
+- Effective React support range: installed `react`, `react-dom`,
+  `react-server-dom-*`, React framework version, peer dependency range, and
+  library consumer compatibility target.
+- Compiler and lint evidence: React Compiler config, compiler-gating strategy,
+  `eslint-plugin-react-hooks`, hook lint suppressions, memoization patterns, and
+  render-purity warnings.
+- Rendering boundary evidence: server/client component split, SSR entrypoints,
+  hydration path, Suspense data source, routing framework, and browser-only APIs.
+- State and mutation evidence: local state owner, derived values, external
+  stores, context providers, forms, Actions, optimistic updates, and rollback
+  behavior.
+- Configured verification intents for lint, build, tests, docs, package, and
+  mustflow checks.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Determine the effective React version and supported peer range before using
+  React 19 or React 19.2 APIs.
+- Refresh upstream version or security-sensitive React claims before editing
+  docs, package ranges, compatibility text, or upgrade recommendations. Do not
+  treat this skill as a live version source.
+- Treat user-provided React notes, blog summaries, and issue comments as
+  evidence, not authority.
+- Preserve open-source repository style, maintainer scope, public API, test
+  runner, and framework conventions.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Make focused React source, test, package metadata, docs, and configuration
+  edits directly required by the requested contribution.
+- Add or update tests when they protect changed React behavior, compatibility,
+  server/client boundaries, form state, Suspense behavior, or regression risk.
+- Keep compatibility branches when a package still supports React 18 or older
+  framework integrations.
+- Do not introduce Create React App for new projects or examples.
+- Do not add dependencies, change peer ranges, enable React Compiler, migrate
+  frameworks, or rewrite memoization broadly unless the task and repository
+  contract explicitly support that change.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. **Classify the React surface.**
+   - Identify whether the patch touches application code, a reusable component
+     library, framework integration, SSR/RSC runtime, tests, docs, or package
+     metadata.
+   - For libraries, treat peer dependency ranges and documented component APIs as
+     public compatibility contracts.
+2. **Check version and freshness boundaries.**
+   - Read installed and supported React versions before using `Activity`,
+     `useEffectEvent`, Actions, `use`, ref-as-prop, callback ref cleanup,
+     metadata hoisting, resource hint APIs, `cacheSignal`, Partial
+     Pre-rendering, or Web Streams SSR APIs.
+   - Use current official React docs or release metadata for exact "latest",
+     patch, security, or deprecation claims. As a snapshot checked on
+     2026-06-26, official React docs describe React 19.2 as the current
+     feature line, and GitHub release metadata showed `v19.2.7` released on
+     2026-06-01; re-check before relying on those values in future work.
+   - For RSC packages, check patched `react-server-dom-webpack`,
+     `react-server-dom-parcel`, and `react-server-dom-turbopack` versions when
+     security advisories or framework updates are part of the task.
+3. **Keep app setup modern and local.**
+   - Do not propose Create React App for new projects. Follow the repository's
+     existing framework or build tool; for new React app examples, prefer the
+     project's chosen framework or modern build-tool pattern.
+   - Do not migrate an existing stack to Next.js, Vite, Parcel, Rsbuild, or a
+     React framework merely because React documentation recommends frameworks
+     for new apps.
+4. **Repair effects by responsibility.**
+   - Use Effects for synchronization with external systems such as timers,
+     subscriptions, DOM or browser APIs, third-party widgets, network
+     connections, and cleanup.
+   - Do not use Effects to copy props/state into derived state, send event-owned
+     mutations, or paper over rendering data flow.
+   - Do not silence `react-hooks/exhaustive-deps` as a default fix. If effect
+     logic contains non-reactive event behavior and React 19.2 is supported, use
+     `useEffectEvent` for that event-like logic only.
+5. **Preserve state ownership.**
+   - Derive renderable values during render when they are computed from current
+     props or state.
+   - Use updater functions for repeated state updates based on the previous
+     value.
+   - Normalize state that can otherwise contradict itself. Avoid duplicated,
+     deeply nested, or derived state unless the repository has a clear owner.
+   - Use `key` for intentional component state reset, and keep component
+     functions at top level so React does not recreate component types on every
+     render.
+6. **Treat memoization and the compiler as contracts, not decoration.**
+   - Do not blanket-add `memo`, `useMemo`, or `useCallback` to look faster.
+     Require profiler, dependency, identity, or compiler evidence.
+   - Do not blanket-remove existing memoization in legacy code without tests;
+     removal can change identity, effect dependencies, and compiler output.
+   - If React Compiler is enabled or proposed, keep components and Hooks pure,
+     keep compiler-powered `eslint-plugin-react-hooks` findings visible, and
+     report when compiler verification is missing.
+7. **Handle context, refs, and external stores deliberately.**
+   - Split frequently changing context values from stable actions or identities;
+     `memo` does not block re-renders caused by context updates.
+   - Use React 19 ref-as-prop and callback-ref cleanup only when the support
+     range allows it. Preserve `forwardRef` where React 18 compatibility matters.
+   - Expose narrow imperative handles with `useImperativeHandle` instead of
+     leaking whole DOM nodes or child internals.
+   - Use `useSyncExternalStore` for external mutable stores or subscriptions
+     instead of ad hoc Effect plus state mirroring.
+8. **Use concurrent and async primitives for the right boundary.**
+   - Use `startTransition` or `useTransition` for non-urgent updates, but do not
+     control text input values through a transition.
+   - Use `useDeferredValue` when stale-but-responsive derived UI is acceptable;
+     use the `initialValue` form only when the React version supports it.
+   - Do not expect Suspense to catch ordinary Effect fetches. Suspense needs
+     lazy code, framework data, or cached Promise reads.
+   - Treat `use` as render-time Promise or context reading, not a normal Hook
+     with the ordinary top-level-only mental model. Do not create fresh Promises
+     in render and pass them to `use`.
+9. **Use React 19 form and Action APIs only when supported.**
+   - Prefer `useActionState`, `useFormStatus`, `useOptimistic`, `<form action>`,
+     and `formAction` for supported React 19 mutation flows with pending,
+     errors, resets, progressive enhancement, and rollback.
+   - Keep explicit error handling, authorization, validation, idempotency, and
+     rollback behavior. Do not hide server failures behind optimistic UI.
+10. **Respect React 19.2 rendering and performance APIs.**
+    - Treat `<Activity>` as hidden UI with preserved state, unmounted effects,
+      and lower-priority hidden updates, not as `display: none` or ordinary
+      conditional rendering.
+    - Use React Performance Tracks, React DevTools, or existing profiler evidence
+      when claiming render, effect, Scheduler, transition, or component
+      performance improvements.
+11. **Keep server rendering and RSC boundaries exact.**
+    - Distinguish Server Components from Server Actions. `"use server"` marks
+      server functions or modules for actions; it is not a Server Component tag.
+    - Keep browser APIs, client state, and event handlers out of Server
+      Components; keep secrets and server-only imports out of Client Components.
+    - Use `cacheSignal` only for RSC cached work where abort or cleanup is
+      meaningful.
+    - For Partial Pre-rendering, `prerender`, `resume`, `resumeAndPrerender`,
+      and streaming APIs, verify the framework/runtime owns those APIs before
+      changing lower-level React DOM server code.
+    - In Node environments, do not assume Web Streams are faster than Node
+      streams; preserve the existing SSR stream API unless the task proves the
+      runtime benefit and compression behavior.
+12. **Use React DOM document and resource APIs close to the owner.**
+    - Metadata, stylesheets with `precedence`, async scripts, `preinit`,
+      `preload`, `preconnect`, and `prefetchDNS` may belong near the component
+      that needs them when React and the framework support that behavior.
+    - Avoid duplicate head managers, resource hint spam, and hints for assets
+      whose timing or priority is unproven.
+13. **Verify through the repository contract.**
+    - Run the smallest configured checks that cover changed React code, package
+      metadata, build output, docs, and tests.
+    - Report missing browser, hydration, SSR, RSC, compiler, profiler, or
+      cross-version React verification when those surfaces changed.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Effective React version, peer range, framework ownership, and compiler/lint
+  status are known or explicitly reported as unknown.
+- Effects, state, memoization, context, refs, forms, Suspense, and async
+  boundaries follow React's current model for the supported version.
+- React 19 and React 19.2 APIs are not introduced into code that still promises
+  older React compatibility.
+- SSR, RSC, Server Action, browser-only, and resource-hint boundaries are
+  preserved.
+- Performance claims have profiler or benchmark evidence, or are reported as
+  unverified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Report missing React-version matrix, browser automation, hydration, SSR/RSC,
+Compiler, performance profiling, or package-consumer verification when those
+surfaces changed.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If React version evidence conflicts, do not assume the newest API is
+  available. Preserve the older-compatible path or report the compatibility
+  decision.
+- If an effect dependency fix causes reconnects, stale closures, or event logic
+  churn, separate reactive synchronization from event-like behavior instead of
+  disabling lint.
+- If a compiler or memoization change shifts behavior, restore the previous
+  identity boundary or add focused evidence before continuing.
+- If Suspense, `use`, Actions, or RSC behavior is framework-owned, read the
+  framework boundary before editing raw React assumptions.
+- If freshness checks are unavailable for a React release, security patch, or
+  deprecation claim, avoid embedding exact "latest" wording and report the gap.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- React surface and supported version checked
+- Compiler, lint, effect, state, memoization, context, ref, form, Suspense, SSR,
+  RSC, and resource-boundary notes
+- Freshness-sensitive React claims checked or left conservative
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining React compatibility or verification risk

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

@@ -432,6 +432,24 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["code_change", "public_api_change", "test_change", "package_metadata_change"]
 
+[routes."c-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "performance_change", "security_change", "package_metadata_change", "release_risk"]
+
+[routes."shell-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "workflow_change", "security_change", "package_metadata_change", "release_risk"]
+
+[routes."structured-config-change"]
+category = "workflow_contracts"
+route_type = "primary"
+priority = 84
+applies_to_reasons = ["code_change", "docs_change", "workflow_change", "mustflow_config_change", "package_metadata_change", "test_change", "security_change", "release_risk"]
+
 [routes."node-code-change"]
 category = "general_code"
 route_type = "primary"
@@ -966,6 +984,12 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["ui_change", "docs_change", "code_change", "behavior_change", "migration_change", "package_metadata_change"]
 
+[routes."react-code-change"]
+category = "ui_assets"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["ui_change", "code_change", "behavior_change", "public_api_change", "data_change", "security_change", "privacy_change", "performance_change", "test_change", "package_metadata_change", "release_risk"]
+
 [routes."svelte-code-change"]
 category = "ui_assets"
 route_type = "primary"

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

@@ -0,0 +1,279 @@
+---
+mustflow_doc: skill.shell-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: shell-code-change
+description: Apply this skill when POSIX sh, Bash, shell scripts, shebangs, GitHub Actions run blocks, package script shell snippets, grep/sed/awk/find/xargs pipelines, shell quoting, word splitting, globbing, traps, exit-status handling, or shell portability/security behavior are created, changed, reviewed, or upgraded.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.shell-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+    - line_endings_check
+---
+
+# Shell Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve shell dialect contracts, expansion safety, file-name safety, exit-status integrity,
+CI runner behavior, and command-injection boundaries when editing shell code or shell-shaped
+documentation.
+
+Shell bugs usually come from an unstated execution boundary: a file says `sh` while using Bash,
+a GitHub Actions `run` block is preprocessed by YAML and expression interpolation before the
+runner shell sees it, or a pipeline treats filenames as line-delimited text.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.sh`, `.bash`, `.bats`, installer scripts, release scripts, hook scripts, Docker entrypoints,
+  package scripts, Make recipes, or docs examples containing POSIX sh or Bash snippets are created
+  or changed.
+- GitHub Actions, CI, or workflow `run` blocks contain shell code, shell options, environment files,
+  heredocs, matrix variables, checkout-dependent shell logic, or context interpolation.
+- Code or docs use shell quoting, parameter expansion, command substitution, globbing, word
+  splitting, redirection, pipes, traps, `set` options, `test`, `case`, loops, subshells, functions,
+  `eval`, `sh -c`, `bash -c`, or sourced files.
+- Shell snippets combine `grep`, `sed`, `awk`, `find`, `xargs`, `sort`, `date`, `stat`, `readlink`,
+  `realpath`, `mktemp`, `rm`, `cp`, `mv`, `sudo`, or platform-specific core utilities.
+- A change claims POSIX portability, Bash-only behavior, GNU/Linux behavior, macOS/BSD behavior,
+  GitHub-hosted runner behavior, or cross-platform shell compatibility.
+- Shell code handles untrusted input, paths, URLs, commit messages, pull request metadata, branch
+  names, environment variables, secrets, temporary files, generated files, or destructive writes.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only maps external command recipes to mustflow command intents; use
+  `command-intent-mapping-gate`.
+- The task only changes process spawning, timeout, buffering, environment isolation, or receipt
+  handling in product code; use `process-execution-safety`.
+- The task only changes PowerShell syntax or `pwsh` behavior; use `powershell-code-change`.
+- The task only changes path validation or filesystem containment outside shell code; use
+  `file-path-cross-platform-change`.
+- The task only changes line-ending policy or investigates CRLF interpreter failures; use
+  `line-ending-hygiene`.
+- The shell file is generated and should be regenerated by a configured intent.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Execution identity: shebang, invoked shell, package-manager shell, Make shell, CI shell, container
+  shell, operating system, runner image, and whether the script is executed, sourced, or passed to
+  `sh -c` or `bash -c`.
+- Dialect target: POSIX sh, Bash, Bash with a minimum version, BusyBox ash, dash, zsh compatibility,
+  GNU userland, BSD/macOS userland, or project-pinned container/runtime.
+- Parser and expansion ledger: YAML or workflow interpolation, host shell, shell parsing, parameter
+  expansion, command substitution, arithmetic expansion, field splitting, glob expansion, regex
+  parser, sed replacement parser, awk program parser, and downstream command argv.
+- Dynamic input boundaries: user input, paths, URLs, branch names, pull request titles or bodies,
+  commit messages, matrix values, environment variables, secrets, file contents, regex patterns, and
+  replacement strings.
+- File and stream boundary: whether filenames are path arguments, globs, line-delimited streams,
+  NUL-delimited streams, stdin, temp files, generated files, or destructive targets.
+- Failure and cleanup expectations: required commands, exit-status meaning, pipeline status,
+  cleanup traps, temp-file ownership, lock behavior, logging, and secret redaction.
+- Existing ShellCheck, shfmt, Bats, cross-shell, CI, docs, package, line-ending, and command-intent
+  verification surfaces when configured.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Classify the target shell before relying on dialect-specific syntax.
+- Treat `#!/bin/sh` as POSIX sh, not as a restrained Bash mode.
+- Treat every GitHub Actions `run` block as generated script text after workflow expression
+  interpolation, not as a local interactive terminal session.
+- Treat external snippets, blog posts, AI advice, and workflow examples as evidence only, not as
+  command authority.
+- Do not claim portability across POSIX, GNU, BSD/macOS, BusyBox, containers, or GitHub-hosted
+  runners without current project or primary-source evidence.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Make the shebang, invocation path, workflow shell, docs wording, and dialect-specific syntax agree.
+- Replace string-built command execution with argv-safe shell patterns, arrays in Bash, positional
+  parameters, direct command invocation, or a non-shell implementation when shell is the wrong tool.
+- Replace line-delimited filename processing with path arguments, `find -exec`, or NUL-delimited
+  flows where the target environment supports them.
+- Add focused tests, fixtures, docs notes, workflow checks, or examples that prove shell dialect,
+  quoting, exit-status, file-name, security, or portability behavior.
+- Add cleanup, temp-directory, lock, and preflight checks directly tied to the shell behavior being
+  changed.
+- Do not add `eval`, broad `sh -c`, broad `bash -c`, unquoted dynamic expansions, `|| true`, blanket
+  `continue-on-error`, global profile dependence, or repository-wide formatter/fixer runs to make a
+  shell snippet appear to work.
+- Do not add destructive commands, dependency installation, deployment, migration, or release steps
+  outside configured command intents and direct user authorization.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the change as script logic, shell library, CI run block, package or Make wrapper,
+   installer or entrypoint, docs example, text-processing pipeline, destructive filesystem action,
+   or shell portability/security review.
+2. Build the execution ledger:
+   - file shebang and executable bit;
+   - how the script is invoked;
+   - effective shell in local, CI, container, package-manager, Make, or docs-example contexts;
+   - whether the file is executed or sourced;
+   - working directory, environment inheritance, profile loading, and step-to-step persistence.
+3. Build the dialect ledger:
+   - POSIX-only syntax;
+   - Bash-only syntax such as arrays, `[[ ]]`, process substitution, here-strings, Bash regex
+     matching, `source`, `mapfile`, `readarray`, `local`, or Bash-specific `shopt`;
+   - GNU-only utility options;
+   - BSD/macOS or BusyBox differences;
+   - declared minimum versions or pinned images.
+4. If Bash syntax is required, make the shebang, CI shell, docs, package invocation, and tests say
+   Bash. If POSIX sh is required, remove Bash-only syntax instead of hoping the target `/bin/sh`
+   accepts it.
+5. Treat `set -e`, `errexit`, `ERR` traps, `nounset`, and `pipefail` as partial tools, not a proof of
+   correct failure handling. Review important commands with explicit status handling.
+6. Remember that `pipefail` is not portable to older POSIX sh targets. If POSIX compatibility matters,
+   avoid relying on it for correctness.
+7. For pipelines, identify whether the last command's status is enough. Preserve individual status
+   evidence when the producing command, filtering command, and consuming command have different
+   failure meanings.
+8. Quote parameter expansions by default. Leave expansions unquoted only when intentional field
+   splitting or globbing is documented and tested.
+9. Keep lists as real argument lists. In Bash, prefer arrays for command argv. In POSIX sh, use
+   positional parameters, `case`, files, stdin, or another language instead of simulating arrays with
+   strings.
+10. Do not parse human-oriented command output such as directory listings as data input. Use globs,
+    `find`, path arguments, or structured command output.
+11. Handle filenames as path values, not newline-delimited text. Review spaces, tabs, newlines,
+    leading dashes, glob characters, quotes, backslashes, empty matches, and missing matches.
+12. Prefer `find -exec ... {} +` for portable batched path handling. Use NUL-delimited flows only
+    when both producer and consumer support them in the declared target environment.
+13. When using `xargs`, account for default whitespace parsing, no-input behavior, argument length
+    limits, batching, parallelism, and exit-code remapping. Do not use default `xargs` for arbitrary
+    filenames.
+14. For `grep`, distinguish no match from error. Do not let an expected no-match status fail CI or
+    let a read error look like no match.
+15. For `sed`, avoid assuming in-place editing syntax is portable. Prefer writing to an owned temp
+    file and replacing deliberately when cross-platform behavior or line endings matter.
+16. For `awk`, pass dynamic values as data variables instead of interpolating shell strings into the
+    program text. Keep shell quoting, awk quoting, regex syntax, and replacement semantics separate.
+17. For `find`, review prune ordering, traversal roots, symlink behavior, destructive actions,
+    time predicates, GNU-only predicates, and whether traversal should stop after the first match.
+18. For `date`, `stat`, `readlink`, `realpath`, `grep -P`, `sed -i`, `find -printf`, `find -maxdepth`,
+    `xargs -r`, and similar utilities, decide whether the target is GNU, BSD/macOS, BusyBox, or
+    POSIX. Replace nonportable options or declare and verify the dependency.
+19. Review locale-sensitive behavior for regex ranges, sorting, character classes, byte-oriented
+    token parsing, and reproducible packaging. Set locale only when the code truly needs byte or
+    deterministic semantics.
+20. For `test`, `[ ]`, `[[ ]]`, arithmetic, and `case`, choose the construct for the declared
+    dialect. Avoid `test` `-a`, `-o`, and parenthesized expression tricks; split conditions with
+    shell operators.
+21. Treat command substitution as scalar capture. Do not use it to preserve file contents, trailing
+    newlines, binary-like data, or arbitrary line lists.
+22. Use `read` with explicit `IFS` and raw mode when preserving line content matters. Account for a
+    final line without a trailing newline.
+23. Review subshell boundaries. Pipeline loops, grouped commands, command substitutions, sourced
+    files, and subshells can change whether variables, traps, `cd`, and options persist.
+24. For temporary files, use owned unpredictable temp files or directories, restrictive permissions
+    when sensitive data is involved, and cleanup traps that preserve the original exit status.
+25. For destructive operations, require non-empty variables, safe prefix or root checks, explicit
+    `--` where supported, and a narrow target. Do not run destructive globs against ambiguous roots.
+26. For GitHub Actions, separate workflow expression interpolation from shell expansion. Pass
+    untrusted GitHub context values through environment variables or files, then treat them as data.
+27. For GitHub Actions environment and output files, account for step lifetime, multiline delimiter
+    collisions, reserved variables, and echo portability. Do not assume values written for later
+    steps are available in the current shell.
+28. For GitHub Actions runner behavior, check shell defaults, job containers, checkout depth, fork
+    and Dependabot permissions, secrets availability, runner image drift, and platform-specific
+    userland before changing shell code.
+29. Keep secrets out of trace output, logs, process arguments, environment dumps, temp files, and
+    diagnostic artifacts. Disable tracing around sensitive commands and redact only as a backup.
+30. Treat `eval`, dynamic `source`, dynamic `.` loading, `sh -c`, remote shell strings, and workflow
+    expression injection as command-injection risks unless the command text is fully trusted and
+    bounded.
+31. If the shell code becomes complex enough to need structured data parsing, concurrency,
+    rollback, JSON mutation, long-lived state, or rich error recovery, consider moving the logic to
+    a project-supported runtime and leaving shell as a thin launcher.
+32. Verify with behavior evidence, not only spelling. Useful evidence includes shell lint, format,
+    cross-shell execution, Bats or similar tests, CI dry-run or provider evidence, path-shape
+    fixtures, line-ending checks, docs validation, package checks, and configured release checks.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The effective shell, dialect, invocation path, and portability claim are explicit.
+- Parser and expansion boundaries are separated from downstream regex, sed, awk, find, xargs, and
+  GitHub Actions expression boundaries.
+- Dynamic values remain data-bound and are not reinterpreted as shell code.
+- Filename handling survives spaces, newlines, leading dashes, glob characters, and empty matches or
+  the unsupported cases are stated.
+- Exit-status, pipeline, cleanup, temp-file, destructive-action, logging, and secret-handling
+  behavior are verified or reported as remaining risk.
+- CI shell defaults, runner image, checkout, permissions, and environment-file behavior are checked
+  when workflow shell code changes.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+- `line_endings_check`
+
+Report missing ShellCheck, shfmt, Bats, cross-shell, POSIX sh, Bash-version, GNU/BSD/BusyBox,
+GitHub Actions, fork-PR, checkout-depth, secret-redaction, path-shape, destructive-dry-run, or
+line-ending verification when those surfaces change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the target shell is unknown, do not introduce dialect-specific syntax without reporting the
+  gap or narrowing the invocation.
+- If POSIX portability and Bash convenience conflict, choose one contract explicitly instead of
+  writing a hybrid script.
+- If a pipeline passes while an upstream command failed, restructure the status handling before
+  adding more output checks.
+- If arbitrary filenames cannot be represented safely by the chosen pipeline, change the data flow
+  or state the unsupported filename class.
+- If GNU/BSD/BusyBox behavior differs and cannot be tested, state the platform boundary instead of
+  claiming cross-platform support.
+- If GitHub Actions context interpolation can turn untrusted metadata into shell code, move the
+  value to a data channel and verify the quoting boundary.
+- If `set -x`, logs, or diagnostic files can expose secrets, stop copying raw output and preserve
+  only redacted, bounded evidence.
+- If a docs example suggests raw commands, map it through `command-intent-mapping-gate` before
+  treating it as agent-runnable.
+- If CRLF, shebang, or executable-bit failures appear, activate `line-ending-hygiene` and verify
+  per-file EOL evidence before normalizing.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Shell execution and dialect boundary
+- Parser, expansion, and downstream utility ledger
+- POSIX, Bash, GNU/BSD/BusyBox, and GitHub Actions compatibility decisions
+- Quoting, word-splitting, globbing, command-substitution, and status-handling decisions
+- Filename, temp-file, cleanup, destructive-action, logging, and secret-handling decisions
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining shell portability, security, CI, or line-ending risk