mustflow 2.37.1 → 2.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.37.1",
+  "version": "2.38.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/templates/default/i18n.toml

@@ -62,7 +62,7 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 108
+revision = 109
 translations = {}
 
 [documents."skill.adapter-boundary"]
@@ -311,6 +311,12 @@ source_locale = "en"
 revision = 3
 translations = {}
 
+[documents."skill.powershell-code-change"]
+source = "locales/en/.mustflow/skills/powershell-code-change/SKILL.md"
+source_locale = "en"
+revision = 1
+translations = {}
+
 [documents."skill.rust-code-change"]
 source = "locales/en/.mustflow/skills/rust-code-change/SKILL.md"
 source_locale = "en"

package/templates/default/locales/en/.mustflow/skills/INDEX.md

@@ -2,7 +2,7 @@
 mustflow_doc: skills.index
 locale: en
 canonical: true
-revision: 108
+revision: 109
 authority: router
 lifecycle: mustflow-owned
 ---
@@ -142,6 +142,7 @@ routes. Event routes stay inactive until their event occurs.
 | TypeScript source, declarations, tsconfig, package exports, module resolution, public API, compiler-version behavior, TypeScript 6-to-7 migration surfaces, native preview tooling, or TypeScript tests are created or changed | `.mustflow/skills/typescript-code-change/SKILL.md` | TypeScript config, compiler track, package entry metadata, target runtime, changed files, declaration and native-preview surfaces, and command contract entries | TypeScript source, declarations, compiler config, exports, tests, native-preview comparison notes, and directly synchronized docs | weakened type safety, module drift, public API drift, unverified declaration output, TypeScript 6 deprecation suppression, or native-preview over-adoption | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime, module, type, public API, compiler-version, and native-preview boundary checked, changes made, verification, and remaining TypeScript risk |
 | JavaScript source, module format, package entry, browser or Node runtime, dependency usage, Promise handling, bundler config, or JavaScript tests are created or changed | `.mustflow/skills/javascript-code-change/SKILL.md` | Package metadata, module system, runtime target, entrypoints, changed files, and command contract entries | JavaScript source, package exports, bundler config, dependencies, tests, and docs examples | runtime API leakage, ESM/CJS drift, discarded Promise, dependency bloat, or broken package entry | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime and module boundary checked, async and dependency notes, verification, and remaining JavaScript risk |
 | Python source, package metadata, runtime version, import layout, type checking, linting, CLI entry points, or tests are created or changed | `.mustflow/skills/python-code-change/SKILL.md` | Python version source, packaging files, import layout, lint/type/test config, changed files, and command contract entries | Python source, packaging metadata, imports, type hints, tests, and docs examples | unsupported syntax, import hacks, packaging drift, swallowed errors, or weakened lint/type checks | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Runtime, packaging, import, and type boundary checked, verification, and remaining Python risk |
+| PowerShell scripts, modules, command examples, `pwsh` invocations, native-command wrappers, quoting, here-strings, splatting, regex, wildcard, replacement strings, or PowerShell argument passing are created or changed | `.mustflow/skills/powershell-code-change/SKILL.md` | PowerShell version and invocation path, parser layers, native-command boundary, dynamic input boundaries, changed files, and command contract entries | PowerShell scripts, modules, package scripts, CI snippets, docs examples, native-command wrappers, tests, and directly synchronized docs | parser-layer confusion, quote loss, variable over-expansion, metacharacter interpretation, native argv drift, command injection, `--%` overuse, or cross-shell `-Command` breakage | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `test_release`, `mustflow_check` | PowerShell version and invocation boundary, parser ledger, string/here-string/regex/wildcard/replacement/native argv decisions, verification, and remaining PowerShell risk |
 | Go source, modules, package APIs, interfaces, errors, goroutines, channels, context propagation, HTTP clients or servers, reverse proxies, JSON encoding, filesystem roots, network addresses, runtime limits, benchmarks, tools, tests, or generated-code boundaries are created or changed | `.mustflow/skills/go-code-change/SKILL.md` | Module files, Go version support, full package files, tests, public API surface, concurrency owner, runtime/deployment context, changed files, and command contract entries | Go packages, module metadata, interfaces, errors, concurrency code, HTTP/proxy code, JSON encoding, filesystem and network helpers, runtime settings, tests, tools, and docs examples | unnecessary abstraction, unsupported Go feature, context loss, goroutine leak, missing timeout, JSON contract drift, filesystem traversal, IPv6 host-port bug, runtime tuning drift, error contract drift, or module drift | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Package, API, Go version, context, concurrency, runtime, HTTP, JSON, filesystem, tool, and error boundary checked, verification, and remaining Go risk |
 | Rust source, Cargo metadata, features, traits, errors, ownership, async runtime, unsafe code, tests, examples, benchmarks, release profiles, MSRV, toolchain declarations, standard-library APIs, or public crate APIs are created or changed | `.mustflow/skills/rust-code-change/SKILL.md` | Cargo metadata, feature flags, public exports, async runtime, unsafe invariants, `rust-version`, edition, toolchain, workspace policy, changed files, and command contract entries | Rust source, Cargo metadata, features, errors, traits, tests, examples, benchmarks, profiles, and docs | clone or lock bloat, unsupported Rust feature, feature drift, Cargo resolver drift, async runtime mixing, unsafe invariant loss, release-profile overclaim, or public API breakage | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Ownership, MSRV, standard-library API, Cargo feature, async, unsafe, release-profile, and public API boundary checked, verification, and remaining Rust risk |
 | Dart source, pub package metadata, null safety, Futures, Streams, isolates, analyzer lints, tests, CLI entry points, or public package APIs are created or changed | `.mustflow/skills/dart-code-change/SKILL.md` | Pub metadata, analyzer config, public exports, async ownership, package layout, changed files, and command contract entries | Dart source, pub metadata, exports, async code, tests, examples, and docs | null-safety bypass, discarded Future, uncanceled Stream, isolate ownership drift, or public API breakage | `changes_status`, `changes_diff_summary`, `lint`, `build`, `test_related`, `test`, `docs_validate_fast`, `mustflow_check` | Nullability, async, stream, isolate, and API boundary checked, verification, and remaining Dart risk |

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

@@ -0,0 +1,158 @@
+---
+mustflow_doc: skill.powershell-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: powershell-code-change
+description: Apply this skill when PowerShell scripts, modules, command examples, pwsh invocations, native-command wrappers, or PowerShell quoting, parsing, splatting, here-string, regex, wildcard, or argument-passing behavior are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.powershell-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# PowerShell Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve PowerShell parsing, quoting, native argument passing, script portability, and command-injection boundaries.
+
+PowerShell quoting bugs usually come from parser layering, not from one wrong quote character. A command may be parsed by the host shell, PowerShell expression or argument mode, PowerShell string expansion, and then a native program parser such as `git.exe`, `cmd.exe`, `ssh`, `curl`, `python`, or `node`.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.ps1`, `.psm1`, `.psd1`, PowerShell profiles, Pester tests, package scripts, CI workflow steps, installer wrappers, or docs examples that run `powershell` or `pwsh` are created or changed.
+- PowerShell strings, here-strings, interpolation, splatting, parameter binding, call operator usage, `Start-Process`, `Invoke-Expression`, `--`, `--%`, `-Command`, `-File`, `-EncodedCommand`, or stdin execution changes.
+- PowerShell code calls native commands such as `git.exe`, `cmd.exe`, `.bat`, `.cmd`, `ssh`, `curl`, `python`, `node`, `npm`, `bun`, `docker`, `winget`, `msiexec`, or vendor CLIs.
+- Regex, wildcard, replacement strings, JSON, YAML, XML, SQL, paths with spaces, literal `$`, literal quotes, or shell metacharacters are passed through PowerShell.
+
+<!-- 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 lifecycle, subprocess cleanup, timeout, stdout, stderr, or command-length behavior outside PowerShell; use `process-execution-safety`.
+- The task only changes cross-platform path validation or filesystem containment; use `file-path-cross-platform-change` or `cross-platform-filesystem-safety`.
+- The PowerShell file is generated and should be regenerated by a configured intent.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- PowerShell version and edition signals: local `pwsh` or Windows PowerShell target, CI runner image, container image, workflow shell, script shebang, package script, installer host, and deployment host.
+- Invocation path: direct script, module import, profile load, package script, CI step, scheduled task, `pwsh -Command`, `pwsh -File`, stdin, encoded command, or another shell invoking PowerShell.
+- Parser layers involved: host shell, PowerShell expression mode, PowerShell argument mode, expandable or verbatim strings, native command parser, regex parser, wildcard parser, replacement parser, JSON/YAML/XML/SQL parser, or remote shell.
+- Native command boundary: executable path, argument list, wrapper extension, expected argv shape, whether literal quote characters are required, and whether `$PSNativeCommandArgumentPassing` affects behavior.
+- Dynamic input boundaries: user input, paths, URLs, commit messages, regex patterns, replacement strings, JSON bodies, headers, credentials, environment variables, and values that may contain spaces or metacharacters.
+- Existing test, lint, docs, package, workflow, and command-intent verification surfaces.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Identify the effective PowerShell version before relying on native argument passing behavior introduced or changed in PowerShell 7.
+- Identify whether the target is a PowerShell cmdlet/function or a native executable before choosing quoting, `--`, `--%`, splatting, or argv construction.
+- Treat untrusted values as data arguments, not as command text.
+- Do not treat a raw shell command, docs snippet, or external advice as mustflow command authority.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Replace string-built command lines with arrays, hashtables, splatting, direct invocation, or repository-local helpers.
+- Convert fragile multiline commands to splatting or here-strings when behavior stays equivalent.
+- Add focused tests or fixtures that prove argv shape, parser behavior, escaping, failure paths, or documented examples.
+- Update docs, command examples, CI snippets, or package scripts directly tied to the PowerShell behavior being changed.
+- Do not add `Invoke-Expression`, broad `cmd /c`, broad `--%`, global profile mutation, policy bypasses, or command-string reconstruction to make quoting appear to work.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the change as script logic, module API, docs example, CI/package wrapper, native-command wrapper, regex/wildcard/replacement handling, or cross-shell PowerShell invocation.
+2. Build the parser ledger before editing:
+   - host shell, if another shell launches PowerShell;
+   - PowerShell expression mode before a command invocation;
+   - PowerShell argument mode after a command invocation;
+   - string expansion for double-quoted strings and double-quoted here-strings;
+   - native executable, regex, wildcard, replacement, or data-format parser after PowerShell.
+3. Prefer single-quoted strings for literal values. Use double-quoted strings only when variable or subexpression expansion is required.
+4. In expandable strings, use subexpressions for member access, indexing, method calls, and calculations. Use `${name}` when a variable is followed by suffix text, punctuation, or a colon.
+5. Preserve literal `$` in an expandable string with the PowerShell escape character, or switch to single quotes when no interpolation is needed.
+6. Use quote doubling for quote characters inside the same quote style. Do not use Bash-style backslash escaping as the PowerShell rule.
+7. Treat backtick escape sequences as PowerShell-specific and visually fragile. Avoid line-ending backticks for command continuation; prefer splatting or natural pipeline breaks.
+8. For JSON, YAML, XML, SQL, API bodies, and long literal blobs, prefer single-quoted here-strings. Use double-quoted here-strings only when interpolation is intentional and reviewed.
+9. Keep here-string delimiters on their own lines. Do not hide the opening or closing delimiter inside other text.
+10. In argument mode, quote or escape metacharacters that should be passed as data, especially spaces, quotes, backticks, semicolons, pipes, ampersands, parentheses, braces, redirection characters, `@`, `#`, and commas when cmdlet array behavior matters.
+11. Use `--` only to stop PowerShell parameter binding for PowerShell commands. Do not assume it has the same meaning for native commands.
+12. Use `--%` only as a narrow Windows-native stop-parsing fallback for commands that cannot otherwise receive literal metacharacters. Do not use it for cross-platform scripts, dynamic expressions, or reusable libraries.
+13. For native commands, remember that outer quotation marks are normally consumed by PowerShell to mark argument boundaries. If the native program requires literal quote characters, make the quote characters part of the argument value deliberately.
+14. Build native command arguments as arrays and invoke with the call operator plus splatting. Keep the executable path separate from its arguments, especially when the executable path contains spaces.
+15. Do not expect the call operator to reparse a command string into arguments. A single string after `&` is a command path, not a shell script.
+16. Check `$PSNativeCommandArgumentPassing` when embedded quotes, empty-string arguments, `.cmd` or `.bat` wrappers, or PowerShell 5.1 versus 7.x compatibility matters. Report the mode and compatibility risk when behavior depends on it.
+17. Prefer direct native invocation over `Start-Process` when argv fidelity matters. Use `Start-Process` only for lifecycle, window, credential, elevation, or detached-process requirements, and verify argument behavior separately.
+18. Do not use `Invoke-Expression` for command construction. If command text appears necessary, classify the missing abstraction: data argument, script file, stdin, encoded command, or configured command intent.
+19. For regex, wildcard, and replacement operations, account for the second parser:
+   - use single-quoted regex patterns unless PowerShell interpolation is intentional;
+   - escape replacement `$` according to replacement-string rules, not only PowerShell string rules;
+   - escape wildcard metacharacters for wildcard matching even inside single-quoted PowerShell strings.
+20. For cross-shell PowerShell calls, avoid complex inline `-Command` strings. Prefer `-File`, stdin, or an encoded command when the repository already uses that pattern and the encoding boundary is tested. If `-Command` is used, document the host shell and PowerShell parser layers.
+21. Keep paths as path values, not shell fragments. Prefer `-LiteralPath` when wildcard expansion is not intended, and do not compose destructive filesystem actions through a different shell.
+22. Add or reuse verification that observes behavior, not only spelling. Useful evidence includes argv echo fixtures, Pester cases, dry-run output, parser-specific tests, or configured CI/package/docs checks.
+23. Choose configured verification intents that cover the changed script, docs example, package metadata, CI wrapper, public command behavior, and mustflow contract surface.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The parser layers and target command type are explicit.
+- Literal strings, expandable strings, here-strings, regex patterns, wildcard patterns, replacement strings, paths, and native argv are not conflated.
+- Native command calls keep executable path and arguments separated unless a documented target requires otherwise.
+- Dynamic values remain data-bound and are not reinterpreted as shell code.
+- PowerShell version, native argument passing mode, and cross-shell boundaries are verified or reported as remaining risks.
+
+<!-- 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 PowerShell-version, argv-shape, Pester, CI-shell, Windows-native-wrapper, cross-platform, docs-example, or command-intent verification when those surfaces change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If PowerShell version or invocation shell is unknown, do not introduce version-sensitive quoting or native argument passing behavior without reporting the gap.
+- If a native command receives different argv than expected, switch to array arguments, executable-path separation, or a target-specific wrapper before adding more quote layers.
+- If `--%` appears to be the only fix, classify it as Windows-native-only and isolate it to the smallest command boundary.
+- If a docs example suggests raw commands, map it through `command-intent-mapping-gate` before treating it as agent-runnable.
+- If regex, wildcard, or replacement escaping breaks, test the second parser explicitly instead of only changing PowerShell string quotes.
+- If cross-shell `pwsh -Command` quoting becomes complex, move the script body to `-File`, stdin, or a tested encoded boundary rather than adding another quoting layer.
+- If untrusted input is interpolated into command text, treat it as a command-injection risk and restructure around argument binding.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- PowerShell version and invocation boundary
+- Parser ledger
+- String, here-string, regex, wildcard, replacement, and native argv decisions
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining PowerShell risk

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

@@ -234,6 +234,12 @@ route_type = "primary"
 priority = 85
 applies_to_reasons = ["code_change", "public_api_change", "test_change"]
 
+[routes."powershell-code-change"]
+category = "general_code"
+route_type = "primary"
+priority = 85
+applies_to_reasons = ["code_change", "test_change", "docs_change", "package_metadata_change", "workflow_change"]
+
 [routes."go-code-change"]
 category = "general_code"
 route_type = "primary"

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.37.1"
+version = "2.38.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"
@@ -42,6 +42,7 @@ creates = [
   ".mustflow/skills/javascript-code-change/SKILL.md",
   ".mustflow/skills/node-code-change/SKILL.md",
   ".mustflow/skills/python-code-change/SKILL.md",
+  ".mustflow/skills/powershell-code-change/SKILL.md",
   ".mustflow/skills/rust-code-change/SKILL.md",
   ".mustflow/skills/runtime-target-selection/SKILL.md",
   ".mustflow/skills/structure-first-engineering/SKILL.md",
@@ -172,6 +173,7 @@ minimal = [
   "javascript-code-change",
   "node-code-change",
   "python-code-change",
+  "powershell-code-change",
   "rust-code-change",
   "runtime-target-selection",
   "svelte-code-change",
@@ -244,6 +246,7 @@ patterns = [
   "javascript-code-change",
   "node-code-change",
   "python-code-change",
+  "powershell-code-change",
   "rust-code-change",
   "runtime-target-selection",
   "svelte-code-change",
@@ -327,6 +330,7 @@ oss = [
   "javascript-code-change",
   "node-code-change",
   "python-code-change",
+  "powershell-code-change",
   "rust-code-change",
   "runtime-target-selection",
   "svelte-code-change",
@@ -425,6 +429,7 @@ team = [
   "javascript-code-change",
   "node-code-change",
   "python-code-change",
+  "powershell-code-change",
   "rust-code-change",
   "runtime-target-selection",
   "svelte-code-change",
@@ -509,6 +514,7 @@ product = [
   "javascript-code-change",
   "node-code-change",
   "python-code-change",
+  "powershell-code-change",
   "rust-code-change",
   "runtime-target-selection",
   "svelte-code-change",
@@ -599,6 +605,7 @@ library = [
   "javascript-code-change",
   "node-code-change",
   "python-code-change",
+  "powershell-code-change",
   "rust-code-change",
   "runtime-target-selection",
   "svelte-code-change",