mustflow 2.99.1 → 2.103.3

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

@@ -0,0 +1,371 @@
+---
+mustflow_doc: skill.c-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: c-code-change
+description: Apply this skill when C source, headers, native build metadata, compiler dialect, C standard version, ABI surfaces, generated bindings, FFI, memory ownership, pointer lifetime, undefined behavior, sanitizer configuration, performance-sensitive C paths, tests, or benchmarks are created, changed, reviewed, or upgraded.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.c-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# C Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve C dialect, target-toolchain, build-graph, API, ABI, FFI, ownership,
+lifetime, pointer provenance, undefined-behavior, concurrency, sanitizer, and
+performance contracts while making a focused C change.
+
+C correctness is not proven by "it compiled locally." A C change is only safe
+when the effective standard, compiler, libc, target architecture, ownership
+rules, and validation evidence are known or explicitly reported as missing.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.c`, C-owned `.h`, generated C glue, C tests, examples, benchmarks, or
+  native C build metadata change.
+- C build metadata changes, including `CMakeLists.txt`, Meson files, Bazel C
+  targets, Make or Autotools files, compiler flags, sanitizer flags, warning
+  policy, linker flags, exported symbols, package config files, or CI matrices.
+- The task touches C standard version, `c17`, `c23`, `gnu23`, compiler or libc
+  compatibility, public C headers, fixed-layout types, generated bindings, FFI,
+  ownership, `malloc`, `realloc`, `free`, raw pointers, arrays, strings, integer
+  overflow, strict aliasing, alignment, atomics, volatile, performance, or
+  benchmark claims.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- C files are read-only context and no C source, header, build, package,
+  binding, test, or benchmark surface changes.
+- A `.c` or `.h` file is compiled as C++ and owned by a C++ target; use
+  `cpp-code-change`.
+- The task is only formatting, comments, or documentation and does not affect a
+  public header, exported symbol, generated binding, FFI surface, build graph,
+  warning policy, sanitizer policy, or documented C contract.
+- A generated C file must be regenerated by a declared project command rather
+  than edited manually.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Changed files and consumed-surface classification: private implementation,
+  private header, public header, shared library, static library, executable,
+  generated binding input, generated binding output, FFI boundary, test,
+  benchmark, or build metadata.
+- Owning build target for every changed C source, header, generated file, native
+  artifact, and installed header.
+- Target compilation identity: C standard or dialect, compiler family and
+  version, libc, ABI, platform, architecture, build type, visibility, linkage,
+  dependency source, warning policy, sanitizer policy, and active build front
+  door when available.
+- Public headers, exported symbols, public structs, fixed-layout types, macros,
+  enum values, constants, generated bindings, FFI functions, ownership/free
+  functions, and downstream consumer expectations when any public surface
+  changes.
+- Ownership, lifetime, allocator, error, callback, thread-safety,
+  synchronization, and performance contracts touched by the change.
+- Configured verification intents from the repository command contract.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Determine the owning C target before editing. Do not treat repository-wide
+  defaults, editor settings, or the local machine compiler as target authority.
+- Determine whether changed `.h` files are C-only, C/C++ dual-use, generated,
+  public, private, or installed.
+- Determine whether the change can affect source API, binary ABI, generated
+  binding API, FFI ABI, behavior, memory safety, thread safety, performance,
+  package consumers, or only private implementation.
+- Refresh external "latest C", compiler support, sanitizer support, or
+  optimization claims before editing docs, package ranges, compatibility text,
+  or upgrade guidance. Treat this skill as a procedure, not as a live standards
+  database.
+- Use only configured command intents for validation. Do not invent native
+  build, test, sanitizer, fuzz, package, or benchmark commands.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep edits scoped to the affected C target, build graph, tests, generated
+  source of truth, and directly synchronized docs or template surfaces.
+- Prefer explicit ownership, pointer+length or begin/end APIs, checked size
+  arithmetic, explicit error channels, and narrow lifetime contracts over
+  hidden globals, implicit buffer length, or manual cleanup spread across many
+  exits.
+- Prefer additive API and ABI changes when existing consumers must keep working.
+- Add focused tests, compile checks, smoke tests, sanitizer coverage, fuzz
+  seeds, or benchmark guards only when they protect the changed C contract and
+  are covered by configured intents.
+- Do not hand-edit generated output unless the project explicitly treats it as
+  authoritative or the user explicitly requests it with the drift risk
+  understood.
+- Do not weaken compiler, warning, sanitizer, ABI, package, test, or
+  compatibility checks to make a patch appear complete.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. **Classify the C boundary.**
+   - Read the changed C files plus nearby headers, tests, build files, package
+     metadata, install/export metadata, and CI hints.
+   - Identify the owning target and active build front door. For CMake, inspect
+     target sources, include directories, compile definitions, compile options,
+     link libraries, install rules, and interface propagation. For Meson,
+     inspect targets, dependencies, options, native or cross files, and install
+     surfaces. For Bazel, inspect C target `srcs`, `hdrs`, deps, copts,
+     visibility, toolchains, and `select()` branches. For Make or Autotools,
+     inspect object rules, included fragments, generated headers, flags,
+     libraries, and install surfaces.
+2. **Record the target compilation identity.**
+   - Record C standard or dialect, compiler, libc, platform, architecture, build
+     type, warning set, sanitizer set, optimization level, visibility, linkage,
+     dependency source, and generated-header source when relevant.
+   - As a source-freshness snapshot checked on 2026-06-26, the finalized C
+     standard is C23, officially ISO/IEC 9899:2024, and the C23
+     `__STDC_VERSION__` value is `202311L`. C2y is draft work, not a finalized
+     standard. Re-check official ISO, WG14, GCC, and Clang sources before using
+     those facts as current external claims.
+   - Do not introduce C23-only features into code that still promises C17, C11,
+     MSVC, embedded, older libc, or mixed C/C++ compatibility without target
+     evidence and a fallback or configure-time failure.
+3. **Classify risk by highest consumed surface.**
+   - Use `internal_only`, `source_api`, `binary_abi`,
+     `static_link_contract`, `generated_binding`, `ffi_boundary`,
+     `semantic_compatibility`, or `performance_resource`.
+   - Do not downgrade risk because the diff is small, compile-clean, or hidden
+     behind macros.
+4. **Check C23 and dialect-specific changes deliberately.**
+   - Before using `bool`, `true`, `false`, `static_assert`, `thread_local`,
+     `nullptr`, `nullptr_t`, `_BitInt`, fixed-underlying-type enums, `auto`,
+     `typeof`, `typeof_unqual`, `constexpr`, empty initializer `{}`,
+     standard attributes, `#embed`, `__has_include`, `#elifdef`, `#warning`,
+     `__VA_OPT__`, `<stdckdint.h>`, `<stdbit.h>`, `memset_explicit`, `strdup`,
+     `strndup`, `memccpy`, `gmtime_r`, `localtime_r`, `timegm`, `free_sized`,
+     `free_aligned_sized`, binary literals, or digit separators, verify
+     compiler, libc, CI, package, and downstream support.
+   - Treat GCC 15 `gnu23` default behavior and Clang C23 support status as
+     toolchain evidence to refresh for the target, not as permission to change
+     portable code.
+   - K&R function definitions are not valid modern C. Prefer explicit
+     prototypes and keep `void f(void)` for no-argument functions in mixed or
+     legacy-compatible code even though C23 tightened `void f()` semantics.
+   - Two's-complement signed representation does not make signed overflow
+     defined. Keep overflow checks explicit.
+5. **Make ownership and allocation contracts visible.**
+   - Classify every pointer as owner, borrowed non-null pointer, borrowed
+     nullable pointer, mutable span, immutable span, callback context, handle,
+     or transferred owner.
+   - Use `malloc(n * sizeof *p)` style only with checked multiplication. Prefer
+     `calloc(n, sizeof *p)`, `reallocarray`, or C23 checked integer operations
+     when the target supports them.
+   - Do not assign `realloc` directly to the original pointer. Use a temporary
+     pointer and update the owner only on success.
+   - Treat `realloc(p, 0)` as unsafe and, in C23, undefined behavior. Split
+     zero-size cases into explicit `free` plus owner-slot update.
+   - Match aligned allocation and deallocation families across platforms.
+6. **Preserve pointer provenance, lifetime, and range rules.**
+   - Do not treat a pointer as only an integer address. Keep object lifetime,
+     provenance, bounds, and alignment visible.
+   - Pointer arithmetic, subtraction, and relational comparison are defined only
+     within the same array object or one-past boundary.
+   - One-past pointers are sentinels, not storage.
+   - Do not use stale pointers after `free`, `realloc`, scope exit, or owner
+     transfer. Prefer APIs that update the caller's pointer slot when ownership
+     ends.
+   - An integer-pointer round trip is not proof that the resulting pointer may
+     access an object.
+   - For unaligned data or representation moves, use `memcpy` instead of
+     pointer casts.
+7. **Keep effective type and aliasing legal.**
+   - Do not type-pun by casting and dereferencing incompatible pointer types.
+     Use `memcpy` for representation moves and let the optimizer remove the
+     copy when legal.
+   - Use character types for byte inspection.
+   - Treat `restrict` as an aliasing contract, not a speed decoration. Add it
+     only when callers cannot pass overlapping objects.
+   - Do not hide aliasing uncertainty behind `volatile`.
+8. **Make arrays, strings, and I/O lengths explicit.**
+   - Pass pointer+length or begin/end pairs for buffers. Do not recover array
+     length from a function parameter with `sizeof`.
+   - Reserve space for the terminating NUL when a buffer stores a C string.
+   - Treat `strncpy` as fixed-width record padding, not as safe string copy.
+   - Check `snprintf`, `read`, `write`, `fread`, `fwrite`, `fclose`, allocator,
+     parser, and system-call return values.
+   - Store `getchar` and similar EOF-capable results in `int`, not `char`.
+   - Cast to `unsigned char` before passing plain byte values to `ctype.h`
+     functions, unless the value is `EOF`.
+   - Use `memmove` when source and destination may overlap; keep `memcpy` only
+     for proven non-overlap.
+9. **Make integer and bit contracts explicit.**
+   - Keep size calculations in unsigned size types with checked multiplication
+     or addition before allocation.
+   - Do not check signed overflow after the overflowing expression has already
+     executed.
+   - Use unsigned types for masks, shifts, and wraparound semantics.
+   - Check shift counts and signed-left-shift assumptions.
+   - Treat C23 `<stdckdint.h>` as a useful option only when target support is
+     proven.
+10. **Review macros, declarations, and public headers.**
+    - Prefer `static inline` functions over macros when type-generic behavior is
+      not required.
+    - For macros, check double evaluation, missing parentheses, statement
+      expression extensions, `do { } while (0)` style, and side-effect
+      arguments.
+    - Use exact function pointer typedefs. Do not cast incompatible function
+      pointers and call through them.
+    - For public headers, review include hygiene, C/C++ compatibility guards
+      when required, exported macros, enum values, struct layout, packing,
+      alignment, fixed-width types, visibility macros, and allocator ownership.
+11. **Keep concurrency and volatile separate.**
+    - Treat data races as undefined behavior.
+    - Use atomics, mutexes, condition variables, or project synchronization
+      primitives for shared state.
+    - Use `volatile` only for the narrow cases it actually owns, such as
+      memory-mapped I/O or signal-adjacent access where the project has a
+      policy. It is not thread synchronization.
+    - When performance and threading interact, inspect false sharing, cache-line
+      layout, allocator contention, and shutdown or cancellation lifetime.
+12. **Make performance changes evidence-driven.**
+    - Require baseline, workload, target metric, profile or benchmark evidence,
+      hypothesis, targeted change, remeasurement, and regression guard when
+      configured verification exists.
+    - Do not claim performance from folklore rewrites such as replacing
+      division by shifts, global `-O3`, broad `inline`, or manual loop unrolling
+      without measurement.
+    - Prefer reducing memory traffic, allocation churn, branch unpredictability,
+      aliasing uncertainty, cache misses, false sharing, and unnecessary copies.
+    - Evaluate `-O2`, `-O3`, LTO, PGO, visibility, `-march`, `-mtune`, and
+      optimization reports as build contracts. Do not use `-Ofast` or
+      `-march=native` for portable release builds without explicit target and
+      correctness evidence.
+13. **Verify through configured intents only.**
+    - Choose validation by highest-risk surface, not diff size.
+    - Report whether configured validation exists for C compile, warning-as-
+      error, optimized build, sanitizer build, public-header compile, downstream
+      consumer compile, link, unit, integration, ABI or symbol diff, generated
+      binding regeneration, FFI smoke, fuzzing, static analysis, cross-compiler
+      matrix, and benchmark scenarios when those surfaces change.
+
+<!-- mustflow-section: rejection-criteria -->
+## Review Rejection Criteria
+
+Reject or revise the patch when any of these appear without strong local
+evidence and risk reporting:
+
+- A changed C file has no identified owning target, active build front door, or
+  compilation identity.
+- A public header, exported symbol, generated binding, FFI surface, library
+  artifact, dialect, warning policy, sanitizer policy, or ABI surface changes
+  without compatibility classification.
+- C23 features are introduced without target compiler, libc, CI, package, and
+  downstream support evidence.
+- API or ABI compatibility is claimed without inspecting public headers,
+  generated bindings, exported symbols, struct layout, calling convention,
+  visibility, allocator boundary, and downstream-style consumer surface when
+  relevant.
+- Ownership transfer, allocation size, `realloc`, zero-size allocation,
+  aligned allocation, free responsibility, or cleanup-on-failure is ambiguous.
+- Pointer arithmetic, pointer comparison, one-past usage, stale pointer usage,
+  integer-pointer round trips, alignment, effective type, or strict aliasing
+  depends on "it works on this machine."
+- `restrict`, `volatile`, `inline`, `-O3`, `-Ofast`, `-march=native`,
+  `__builtin_expect`, `__builtin_prefetch`, LTO, PGO, or manual unrolling is
+  added as a performance claim without contract and evidence.
+- Sanitizer, warning, optimized-build, ABI, FFI, binding, benchmark, or
+  cross-toolchain checks are missing but the output claims those properties were
+  proven.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The owning target, active build graph, and target compilation identity are
+  known or the missing boundary is reported.
+- The highest compatibility risk is stated: internal-only, source API, binary
+  ABI, static-link contract, generated binding, FFI, semantic compatibility, or
+  performance/resource.
+- Ownership, lifetime, pointer provenance, allocator, integer, string, macro,
+  error, concurrency, dialect, and performance impacts are intentional and
+  evidence-backed.
+- Public headers, exported symbols, generated bindings, FFI surfaces, build
+  metadata, tests, docs, and template surfaces are synchronized when they are
+  part of the changed contract.
+- Generated files match their source of truth and generator flow, or drift is
+  reported.
+- No API, ABI, memory-safety, thread-safety, FFI, binding, sanitizer, or
+  performance compatibility is claimed beyond the validation evidence.
+
+<!-- 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 C compile, warning-as-error, optimized-build, sanitizer, public-
+header compile, downstream consumer compile, link, ABI or symbol diff,
+generated-binding regeneration, FFI smoke, fuzzing, static analysis,
+cross-compiler, cross-libc, cross-architecture, and benchmark verification when
+those surfaces changed.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the owning target or active build front door is unclear, stop the risky
+  part and inspect build metadata before editing further.
+- If multiple build graphs own the same changed file and only one can be
+  updated, report the stale graph and compatibility risk.
+- If public API or ABI policy is absent, classify the risk explicitly instead of
+  assuming semver, SONAME, or package compatibility rules.
+- If generated bindings drift, restore source/output alignment or report the
+  generator/source-of-truth gap.
+- If a lifetime, ownership, or aliasing fix creates broad shared ownership,
+  hidden global state, or pointer-range ambiguity, revisit the owner boundary
+  before continuing.
+- If concurrency changes lack a synchronization proof, stop that part and
+  inspect the state owner, guard, lifetime, and shutdown path.
+- If performance measurements are unavailable, report that performance
+  compatibility was not proven.
+- If freshness checks are unavailable for C standard, compiler, libc, sanitizer,
+  or support-status claims, avoid embedding exact "latest" wording and report
+  the gap.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Owning target and compilation identity
+- C standard, dialect, compiler, libc, warning, sanitizer, and optimization
+  notes
+- Highest compatibility risk
+- Ownership, lifetime, pointer provenance, UB, integer, string, macro,
+  concurrency, or performance impact
+- Public API, ABI, binding, FFI, or build-graph impact
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining C risk

package/templates/default/locales/en/.mustflow/skills/clarifying-question-gate/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.clarifying-question-gate
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: clarifying-question-gate
@@ -34,6 +34,12 @@ The goal is not to make the user rewrite the prompt. Normalize the request insid
 state the interpretation when it matters, and continue unless a high-cost decision still needs
 confirmation.
 
+This skill also protects the repository from vague imperative requests such as "fix the bug",
+"clean this up", "make it pretty", "speed it up", "add tests", "fix the build", "make an API",
+or "handle errors". Do not execute the literal wording as permission to patch symptoms. Convert
+the request into a reviewable contract for the target, criteria, scope, affected surfaces,
+verification, and stop-or-ask boundary.
+
 <!-- mustflow-section: use-when -->
 ## Use When
 
@@ -49,6 +55,10 @@ confirmation.
   maintenance burden.
 - You are about to add a new dependency, service, folder boundary, storage model, framework pattern,
   persistent state, or broad refactor that the current files do not already require.
+- The request is a terse command that names an activity but not its target behavior, quality
+  criteria, impacted contracts, or proof of completion, for example bug fixing, error handling,
+  refactoring, test repair, type cleanup, performance work, API work, UI polish, documentation,
+  dependency updates, CI repair, or PR preparation.
 - The request can be safely clarified by a short normalized contract instead of a long back-and-forth.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -91,6 +101,13 @@ confirmation.
 - A normalized task contract when the original request is vague enough to risk drift: goal, current
   context, change scope, excluded scope, user-visible behavior, constraints, completion evidence,
   verification, report format, and remaining risks.
+- For terse implementation commands, a normalized execution contract with:
+  - the observed target or failure source;
+  - the intended behavior or quality criterion;
+  - the changed and explicitly excluded surfaces;
+  - public contracts, data, security, UX, dependency, or generated outputs that may be affected;
+  - the verification plan and evidence that will close the task;
+  - the condition that requires stopping, asking, or handing off to a narrower skill.
 - Source tags for contract entries: `user_confirmed`, `repository_derived`, `safe_assumption`, or
   `unresolved`.
 
@@ -141,7 +158,27 @@ confirmation.
      `instruction-conflict-scope-check`.
    - `insufficient_evidence`: more repository reading, reproduction, or scoped analysis is needed
      before asking or implementing.
-5. Build a normalized task contract when the user request is underspecified but executable:
+5. Normalize terse implementation commands before editing:
+   - For bug, error, build, CI, or failing-test requests, identify the observed failure source,
+     distinguish implementation defects from test or environment defects, and define the regression
+     evidence before changing code.
+   - For refactor, cleanup, naming, comment, folder, type, or duplicate-removal requests, preserve
+     behavior as the default invariant and name the readability, responsibility, type-safety, or
+     dependency-direction criterion being improved.
+   - For performance requests, identify the suspected or measured bottleneck, baseline, workload,
+     and verification signal before optimizing.
+   - For API, response shape, auth, permission, logging, error, cache, database, migration, or
+     dependency requests, identify compatibility, data, security, lifecycle, and rollback surfaces
+     before implementation.
+   - For UI, accessibility, responsive, form, modal, routing, search, filtering, pagination, or
+     state-management requests, identify the user path, visible states, failure states, device or
+     input constraints, and verification evidence.
+   - For docs, README, env var, deploy, release, or PR requests, identify the source of truth,
+     affected install or automation surfaces, required verification, and any maintainer-facing
+     limitation text.
+   - Do not treat "minimal fix" as the default when a symptom-only patch would leave the affected
+     flow, contract, or regression coverage broken.
+6. Build a normalized task contract when the user request is underspecified but executable:
    - goal;
    - current context;
    - change scope;
@@ -154,46 +191,46 @@ confirmation.
    - remaining risks.
    Tag each non-obvious contract entry as `user_confirmed`, `repository_derived`,
    `safe_assumption`, or `unresolved`. Do not add new product requirements while normalizing.
-6. Ask about observable completion before feature shape when success is unclear:
+7. Ask about observable completion before feature shape when success is unclear:
    - what behavior proves the task is done;
    - which user path, command, test, screenshot, migration state, or registry/release state closes it.
-7. Ask about scope only when plausible scopes have different cost or risk:
+8. Ask about scope only when plausible scopes have different cost or risk:
    - minimal symptom fix, root-cause fix, or broader cleanup;
    - prototype, maintainable production path, or release-ready path.
-8. Ask about existing users and data before changing persistence, lifecycle, deletion, migration,
+9. Ask about existing users and data before changing persistence, lifecycle, deletion, migration,
    retention, cache, API compatibility, or old-client behavior.
-9. Ask about failure UX before implementing user-visible success flows where failure handling is a
+10. Ask about failure UX before implementing user-visible success flows where failure handling is a
    product decision: retry, queue, message, audit/log-only, rollback, partial success, or manual
    recovery.
-10. Ask about security and authorization before relying on UI hiding, client-side checks, roles,
+11. Ask about security and authorization before relying on UI hiding, client-side checks, roles,
    invites, team boundaries, file access, billing state, or admin features.
-11. Ask before adding or swapping dependencies, services, queues, databases, auth providers, design
+12. Ask before adding or swapping dependencies, services, queues, databases, auth providers, design
    systems, state managers, or major folder boundaries.
-12. Ask about verification when there is no declared command intent or when the user expects a
+13. Ask about verification when there is no declared command intent or when the user expects a
     specific proof beyond the repository's configured checks.
-13. Keep the question set short:
+14. Keep the question set short:
     - ask at most three questions at once;
     - ask only one question when its answer may make later questions irrelevant;
     - each question must name the decision, the recommended choice, the consequence of that choice,
       and one meaningful alternative;
     - avoid open-ended prompts like "how should I implement this?" unless no responsible options can
       be framed from repository evidence.
-14. Do not ask bad engineering-delegation questions:
+15. Do not ask bad engineering-delegation questions:
     - "Should I add tests?"
     - "Should I handle errors?"
     - "Should I follow existing style?"
     - "Should I check current files?"
     - "Should I preserve existing behavior?"
-15. Use prompt rewriting only as an exception:
+16. Use prompt rewriting only as an exception:
     - the user explicitly asks for a prompt, issue, PR body, work order, or handoff for another
       agent;
     - the current request is too broken to execute and a normalized contract plus confirmation is the
       smallest safe next step.
     Otherwise, show the normalized contract only when it materially reduces drift, then proceed in
     the same conversation.
-16. If no blocking question remains, proceed without ceremony. State only the assumptions that matter
+17. If no blocking question remains, proceed without ceremony. State only the assumptions that matter
     to review or rollback.
-17. If a blocking question remains unanswered, do not implement around it. Offer the smallest safe
+18. If a blocking question remains unanswered, do not implement around it. Offer the smallest safe
     non-blocked action, such as read-only analysis, a plan, a reproduction, or a narrow preparatory
     refactor when another selected skill supports it.
 
@@ -207,6 +244,8 @@ confirmation.
 - Safe assumptions are narrow, reversible, and reported.
 - Any normalized contract preserves the user's original request separately from repository-derived
   facts and safe assumptions.
+- Terse commands are expanded into target, criterion, scope, affected-surface, verification, and
+  stop-or-ask boundaries before implementation.
 - Prompt rewriting is not used as a substitute for proceeding in the current task.
 - The final work can be judged against observable success criteria or a reported verification gap.
 

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.completion-evidence-gate
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: completion-evidence-gate
@@ -70,6 +70,8 @@ missing, blocked, failed, stale, or only partially relevant.
 - Optional script-pack discovery evidence when the command contract exposes `script_pack_list`.
 - Synchronized surfaces expected by the changed contract: source, tests, fixtures, schemas, templates, manifests, docs, release metadata, generated output, and localized copies.
 - Known remaining risks, unverified assumptions, blocked decisions, and rollback notes.
+- Concrete follow-up candidates, if any, plus whether a bounded `next-action-menu` should be
+  included or intentionally omitted.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
@@ -118,11 +120,18 @@ missing, blocked, failed, stale, or only partially relevant.
    - Use `implemented but unverified` when the files changed but no relevant configured verification was run.
    - Use `blocked` when required evidence cannot be produced without a missing decision, unavailable environment, manual-only command, failed prerequisite, or user approval.
    - Use `not complete` when a required acceptance criterion is not implemented or verification contradicts the claim.
-7. Write the final report from evidence, not confidence.
+7. Decide whether a next-action menu is warranted.
+   - If there are concrete, evidence-backed follow-up tasks that would make the next user turn
+     cheaper, read and apply `next-action-menu` before final reporting.
+   - If no useful follow-up exists, the user asked not to include recommendations, or the only next
+     actions are speculative or approval-gated, 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.
+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.
    - Do not hide lower-confidence evidence when direct shell commands were used instead of configured intents.
-8. If the gate reveals missing required work that is safe and in scope, do that work before final reporting. Otherwise report the gap plainly.
+9. If the gate reveals missing required work that is safe and in scope, do that work before final reporting. Otherwise report the gap plainly.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -131,6 +140,8 @@ missing, blocked, failed, stale, or only partially relevant.
 - Every user requirement is mapped to proof, a limitation, or an explicit out-of-scope decision.
 - Skipped, missing, failed, stale, or manual-only verification is visible.
 - Contract, template, schema, docs, test, and release drift is either resolved or named as remaining risk.
+- Useful follow-up tasks either appear through `next-action-menu` or are intentionally omitted with a
+  clear reason when the menu conditions are not met.
 - No unconfigured command, hidden transcript, broad log, or invented tool result is treated as proof.
 
 <!-- mustflow-section: verification -->
@@ -178,4 +189,5 @@ instead of replacing it with an inferred command.
 - Lower-confidence evidence, if any
 - Stalled or repeated observations, if any
 - Remaining risks
+- Next-action menu included or omitted, with reason
 - Final wording boundary