powershell-code-change

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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