mustflow 2.103.12 → 2.103.14

package/package.json

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

package/templates/default/i18n.toml

@@ -40,7 +40,7 @@ translations.hi = { path = "locales/hi/.mustflow/context/PROJECT.md", source_rev
 [documents."docs.agent-workflow"]
 source = "locales/en/.mustflow/docs/agent-workflow.md"
 source_locale = "en"
-revision = 24
+revision = 25
 translations.ko = { path = "locales/ko/.mustflow/docs/agent-workflow.md", source_revision = 23, status = "needs_review" }
 translations.zh = { path = "locales/zh/.mustflow/docs/agent-workflow.md", source_revision = 18, status = "needs_review" }
 translations.es = { path = "locales/es/.mustflow/docs/agent-workflow.md", source_revision = 18, status = "needs_review" }
@@ -691,7 +691,7 @@ translations = {}
 [documents."skill.powershell-code-change"]
 source = "locales/en/.mustflow/skills/powershell-code-change/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.shell-code-change"]
@@ -775,13 +775,13 @@ translations = {}
 [documents."skill.completion-evidence-gate"]
 source = "locales/en/.mustflow/skills/completion-evidence-gate/SKILL.md"
 source_locale = "en"
-revision = 5
+revision = 6
 translations = {}
 
 [documents."skill.next-action-menu"]
 source = "locales/en/.mustflow/skills/next-action-menu/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 4
 translations = {}
 
 [documents."skill.evidence-stall-breaker"]

package/templates/default/locales/en/.mustflow/docs/agent-workflow.md

@@ -2,7 +2,7 @@
 mustflow_doc: docs.agent-workflow
 locale: en
 canonical: true
-revision: 24
+revision: 25
 lifecycle: mustflow-owned
 authority: workflow-policy
 ---
@@ -356,6 +356,12 @@ Do not store raw full logs, secrets, customer data, or long transcripts in `.mus
 
 ## Reporting
 
+Before a final report after changed files, verification, paused implementation, commit readiness,
+release readiness, deploy preparation, or any completion/readiness claim, apply
+`completion-evidence-gate` when available. If at least one concrete, evidence-backed follow-up action
+remains, apply `next-action-menu` and include the bounded table. If the menu is omitted, state the
+reason plainly: no concrete next action, user opt-out, or speculative-only follow-ups.
+
 Final reports should include:
 
 - Skill selection note, when files were created or modified

package/templates/default/locales/en/.mustflow/skills/completion-evidence-gate/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.completion-evidence-gate
 locale: en
 canonical: true
-revision: 5
+revision: 6
 lifecycle: mustflow-owned
 authority: procedure
 name: completion-evidence-gate
-description: Apply this skill before a final report or completion claim when changed files, verification results, skipped checks, or remaining risks must be tied to concrete repository evidence.
+description: Apply this skill before a final report or completion claim after non-trivial changed-file work, verification, commit, release readiness, paused implementation, or any report where changed files, skipped checks, concrete next actions, or remaining risks must be tied to repository evidence.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -134,8 +134,8 @@ missing, blocked, failed, stale, or only partially relevant.
      verification as menu rows with the gate stated plainly.
    - If no useful follow-up exists, the user asked not to include recommendations, or the only next
      actions are speculative, omit the menu and keep the final report concise.
-   - Do not treat this gate as automatic host behavior: the menu appears only when the skill is
-     selected and its use conditions are met.
+   - Treat route selection that reaches this gate but omits `next-action-menu` despite concrete
+     follow-ups as incomplete final-report routing, not as permission to silently drop the menu.
 8. Write the final report from evidence, not confidence.
    - Name changed files, command intents run, skipped checks with reasons, synchronized or deferred surfaces, and remaining risks.
    - Do not imply that skipped, manual-only, or missing command intents passed.

package/templates/default/locales/en/.mustflow/skills/next-action-menu/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.next-action-menu
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: next-action-menu
-description: Apply this skill when a final report, completion note, repository improvement loop, or follow-up workflow should offer a bounded numbered next-action menu that a user can select with a single digit in the next turn. Use especially after non-trivial completed or paused work, commits, pushes, release or deploy preparation, verification, or remaining approval gates when concrete follow-up actions exist.
+description: Apply this skill when a final report, completion note, repository improvement loop, or follow-up workflow should offer a bounded numbered next-action menu that a user can select with a single digit in the next turn. Use especially after non-trivial code, behavior, test, docs, workflow, release, deploy, commit, push, verification, paused-work, or approval-gated work when concrete follow-up actions exist.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -38,6 +38,9 @@ scope, approval, verification, command contracts, release gates, or safety rules
   follow-up tasks.
 - A non-trivial task is being reported after changed files, a created commit, completed verification,
   push readiness, release or deploy preparation, paused work, or another concrete approval gate.
+- A code, behavior, test, public API, config, workflow, docs, package, security, data, UI, or
+  performance change has been completed or paused and the final report can name a bounded next
+  action such as verify, commit, push, release, deploy, document, or continue a related slice.
 - The user repeatedly asks for "next recommended work", "continue", "proceed", or selects follow-up
   items after previous completion reports.
 - The agent needs to present a bounded backlog that can be selected by a single digit in the next

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.powershell-code-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: powershell-code-change
@@ -56,7 +56,7 @@ PowerShell quoting bugs usually come from parser layering, not from one wrong qu
 - 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.
+- Native command boundary: executable path, argument list, wrapper extension, expected argv shape, whether literal quote characters are required, whether `$PSNativeCommandArgumentPassing` affects behavior, and how the native tool defines nonzero exit codes.
 - File rewrite boundary: target file policy, expected encoding, expected newline style, replacement count, whether the file may contain mixed line endings, and whether the repository declares an EOL policy.
 - 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.
@@ -65,6 +65,7 @@ PowerShell quoting bugs usually come from parser layering, not from one wrong qu
 ## Preconditions
 
 - Identify the effective PowerShell version before relying on native argument passing behavior introduced or changed in PowerShell 7.
+- Treat "latest PowerShell" and lifecycle claims as fresh external facts. Check current Microsoft lifecycle evidence before embedding version-support claims in docs, tests, or recommendations.
 - 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.
@@ -74,6 +75,7 @@ PowerShell quoting bugs usually come from parser layering, not from one wrong qu
 
 - 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.
+- Convert complex inline `pwsh -Command "..."` one-liners into direct PowerShell script bodies, `-File`, stdin, or encoded-command boundaries when nested quotes, pipes, regexes, JSON, or paths make parser layering fragile.
 - Replace lossy text rewrite pipelines with deterministic read/write APIs that preserve or intentionally normalize encoding and newlines.
 - 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.
@@ -102,21 +104,28 @@ PowerShell quoting bugs usually come from parser layering, not from one wrong qu
 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:
+15. When the current shell is already PowerShell, do not wrap a generated command in another `pwsh -Command "..."` string. Emit the script body directly, or use a temporary `.ps1`, stdin, or an encoded command only when another process must launch PowerShell.
+16. If `pwsh -Command` is unavoidable, keep the command body small and free of nested parser hazards. Switch away from inline mode when the command contains nested quotes, dollar signs, braces, parentheses, semicolons, pipes, regex alternation, JSON, YAML, paths with spaces, or Git revspecs.
+17. 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.
+18. Initialize variables before a pipeline. After `|`, provide a command or scriptblock-consuming command such as `ForEach-Object { ... }`; do not put assignments such as `$i = 0` or control-flow keywords where a pipeline command is required.
+19. Prefer the full cmdlet name `ForEach-Object` in generated one-liners and examples. Use the `foreach` language keyword only in a normal script block where its parser role is unambiguous.
+20. 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.
+21. 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.
+22. 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.
+23. 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 mechanical text replacement, count expected matches before writing. If the count is not exactly the intended number, stop and report the mismatch instead of writing a broad replacement.
-21. For repository file rewrites, prefer .NET file APIs with explicit encoding over PowerShell content cmdlets when deterministic output matters. Normalize CRLF and lone CR to LF only when the repository policy expects LF, and write UTF-8 without BOM explicitly. Treat `Set-Content -Encoding utf8` as version-sensitive because Windows PowerShell 5.1 and PowerShell 6+ differ in default UTF-8 BOM behavior.
-22. If line-ending warnings appear after a PowerShell rewrite, do not assume the last read command caused them. Inspect repository EOL policy and per-file EOL evidence, then activate `line-ending-hygiene` for cause analysis or normalization decisions.
-23. 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.
-24. 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.
-25. Add or reuse verification that observes behavior, not only spelling. Useful evidence includes argv echo fixtures, Pester cases, dry-run output, parser-specific tests, deterministic encoding or line-ending checks, or configured CI/package/docs checks.
-26. Choose configured verification intents that cover the changed script, docs example, package metadata, CI wrapper, public command behavior, and mustflow contract surface.
+24. For search patterns sent to tools such as `rg`, keep the regex as one literal string or use fixed-string mode when regex semantics are not needed. Do not repair PowerShell quoting by adding Bash-style backslashes that change the regex parser's input.
+25. Check `$LASTEXITCODE` immediately after each native command whose result matters, before another native command can overwrite it. Interpret tool-specific codes explicitly; for example, `rg` commonly uses exit code `1` for no matches and higher codes for real errors.
+26. Set predictable script-level diagnostics for generated PowerShell examples when logs are parsed by agents: fail PowerShell errors with `$ErrorActionPreference = 'Stop'`, prefer plain text rendering when available, and use native tool no-color flags when the tool supports them.
+27. For mechanical text replacement, count expected matches before writing. If the count is not exactly the intended number, stop and report the mismatch instead of writing a broad replacement.
+28. For repository file rewrites, prefer .NET file APIs with explicit encoding over PowerShell content cmdlets when deterministic output matters. Normalize CRLF and lone CR to LF only when the repository policy expects LF, and write UTF-8 without BOM explicitly. Treat `Set-Content -Encoding utf8` as version-sensitive because Windows PowerShell 5.1 and PowerShell 6+ differ in default UTF-8 BOM behavior.
+29. If line-ending warnings appear after a PowerShell rewrite, do not assume the last read command caused them. Inspect repository EOL policy and per-file EOL evidence, then activate `line-ending-hygiene` for cause analysis or normalization decisions.
+30. 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.
+31. 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.
+32. Add or reuse verification that observes behavior, not only spelling. Useful evidence includes argv echo fixtures, Pester cases, dry-run output, parser-specific tests, deterministic encoding or line-ending checks, or configured CI/package/docs checks.
+33. 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
@@ -124,6 +133,8 @@ PowerShell quoting bugs usually come from parser layering, not from one wrong qu
 - 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.
+- Pipelines do not mix variable initialization or control-flow syntax into the command position after `|`.
+- Native command exit-code handling preserves tool-specific semantics and checks `$LASTEXITCODE` before it can be overwritten.
 - Mechanical rewrites have explicit replacement counts, encoding, and newline decisions.
 - 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.

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

@@ -81,8 +81,8 @@ applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "publi
 [routes."next-action-menu"]
 category = "workflow_contracts"
 route_type = "adjunct"
-priority = 72
-applies_to_reasons = ["unknown_change", "docs_change", "workflow_change", "mustflow_docs_change", "package_metadata_change"]
+priority = 84
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "copy_change", "i18n_change", "workflow_change", "mustflow_docs_change", "mustflow_config_change", "package_metadata_change", "security_change", "privacy_change", "data_change", "migration_change", "performance_change", "ui_change", "release_risk"]
 
 [routes."proactive-risk-surfacing"]
 category = "workflow_contracts"

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.103.12"
+version = "2.103.14"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"