mustflow 2.85.4 → 2.99.0

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.go-code-change
 locale: en
 canonical: true
-revision: 3
+revision: 4
 lifecycle: mustflow-owned
 authority: procedure
 name: go-code-change
@@ -35,7 +35,7 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 
 - `.go`, `go.mod`, `go.sum`, `go.work`, build tags, generated code, public package API, tests, benchmarks, goroutines, channels, context propagation, HTTP clients or servers, reverse proxies, JSON encoding, filesystem access, network addresses, runtime tuning, tools, or module dependencies change.
 - The task touches interfaces, error wrapping, package structure, concurrency ownership, cancellation, timeout policy, memory limits, race-sensitive code, benchmark measurement, or module dependencies.
-- Code or docs use Go-version-gated features such as expression operands to `new`, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `os.Root` or `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `go fix` modernizers, `encoding/json/v2`, experimental `GOEXPERIMENT` features, or newer runtime defaults.
+- Code or docs use Go-version-gated features such as expression operands to `new`, range-over-function iterators, generic type aliases, reflect iterators, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `T.ArtifactDir`, `B.ArtifactDir`, `F.ArtifactDir`, `testing/cryptotest.SetGlobalRandom`, `os.Root` or `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `go fix` modernizers, `encoding/json/v2`, experimental `GOEXPERIMENT` features, or newer runtime defaults.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -79,7 +79,7 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 2. Classify the change as package API, internal implementation, dependency, error behavior, context flow, concurrency, HTTP or proxy behavior, JSON encoding, filesystem safety, runtime or deployment behavior, benchmark, tooling, or test-only.
 3. Check the Go version contract before using newer syntax or APIs:
    - treat the `go` directive as a language and module compatibility switch, not decoration;
-   - do not use `new(expr)`, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `os.Root`, `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `go fix` modernizers, `encoding/json/v2`, or any `GOEXPERIMENT` feature unless the repository's supported Go version and build path allow it;
+   - do not use `new(expr)`, range-over-function iterators, generic type aliases, reflect iterator methods, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `T.ArtifactDir`, `B.ArtifactDir`, `F.ArtifactDir`, `testing/cryptotest.SetGlobalRandom`, `os.Root`, `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `go fix` modernizers, `encoding/json/v2`, or any `GOEXPERIMENT` feature unless the repository's supported Go version and build path allow it;
    - distinguish stable standard-library APIs from experimental APIs that require `GOEXPERIMENT`;
    - when `go.mod` or `go.work` changes, report language-version, module-graph, toolchain, and downstream support impact.
 4. Check package boundaries before adding a package or interface:
@@ -125,36 +125,40 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
    - receivers do not close borrowed input channels;
    - multiple senders require a coordinator that closes only after all senders finish;
    - cancellable pipelines must avoid permanently blocking upstream goroutines when downstream stops early.
-12. Keep timeout policy at request, command, API, or operation boundaries. Do not hide arbitrary sleeps or timeouts in reusable helpers unless that helper explicitly owns the policy.
-13. Check HTTP and proxy defaults:
+12. Use iterator functions only for pull-style traversal, not hidden concurrency. Honor the `yield` return value immediately, call the `stop` function from pull iterators, keep resource ownership visible, and keep channels for actual concurrent communication or backpressure.
+13. Keep timeout policy at request, command, API, or operation boundaries. Do not hide arbitrary sleeps or timeouts in reusable helpers unless that helper explicitly owns the policy.
+14. Check HTTP and proxy defaults:
    - set deliberate `http.Client` and `http.Server` timeouts for network-facing code; zero timeout means no limit in important cases;
    - reuse clients and transports instead of creating them per request;
    - prefer reverse-proxy rewrite hooks over deprecated or unsafe director-style mutation when the supported Go version allows it;
    - keep hop-by-hop header, forwarded-host, scheme, cancellation, streaming, and error-mapping behavior explicit.
-14. Keep JSON contracts honest:
+15. Keep JSON contracts honest:
    - choose `omitempty` versus `omitzero` deliberately, especially for `time.Time`, numeric zero, boolean false, and optional fields;
    - use `SetEscapeHTML(false)` only when the JSON is not embedded into HTML and callers expect raw `<`, `>`, or `&`;
    - treat `encoding/json/v2` and `jsontext` as experimental unless the repository explicitly opts into the relevant experiment and migration tests.
-15. Check filesystem and network address helpers:
+16. Check filesystem and network address helpers:
    - use traversal-resistant root APIs when accepting user-controlled relative paths and the supported Go version provides them;
    - do not treat `filepath.Join` plus prefix checks as sufficient against symlinks and TOCTOU;
    - prefer `net/netip` for comparable IP addresses and map keys when supported;
    - use `net.JoinHostPort` instead of string formatting for host and port assembly so IPv6 works.
-16. Check runtime and deployment behavior when relevant:
+17. Check runtime and deployment behavior when relevant:
    - set `GOMEMLIMIT` or `debug.SetMemoryLimit` before tuning `GOGC` for container memory pressure, leaving headroom for non-Go memory such as cgo, mmap, and the kernel;
    - question manual `GOMAXPROCS` pins in containers on Go versions with container-aware defaults;
    - use PGO only with representative profiles and keep `default.pgo` ownership clear;
    - treat goroutine leak profiling, SIMD, JSON v2, and other experiments as opt-in evidence-gathering, not default production assumptions;
    - remember that `-race` only finds races on executed paths and carries significant overhead.
-17. Keep tests and benchmarks deterministic:
+18. Keep tests and benchmarks deterministic:
    - do not use elapsed real time to wait for goroutine progress; use explicit synchronization, owned lifecycle waits, fake time, `testing/synctest` when supported, or the repository's established concurrency test helper;
-   - prefer `testing.B.Loop` for new benchmarks when the supported Go version allows it, and keep setup, cleanup, allocation measurement, and compiler optimization boundaries honest.
-18. Keep Go tools and modernization explicit:
+   - prefer `testing.B.Loop` for new benchmarks when the supported Go version allows it, and keep setup, cleanup, allocation measurement, and compiler optimization boundaries honest;
+   - use test artifact directories for files that should survive a test run only when the supported Go version and test invocation preserve artifacts; otherwise use the repository's existing temporary-file or golden-output policy;
+   - for deterministic crypto tests, prefer the standard cryptographic test hook when the supported Go version provides it instead of overriding global readers in production code paths.
+19. Keep Go tools and modernization explicit:
    - prefer the `tool` directive over `tools.go` pinning only when the repository's supported Go version allows it;
    - use `go fix` modernizers as reviewed migrations, not silent drive-by rewrites;
+   - update code generators, schema generators, lint helpers, and reflection-heavy tooling for generic aliases, alias node behavior, and reflect iterator methods only with fixture coverage;
    - prefer standard-library helpers such as `min`, `max`, `clear`, `slices`, `maps`, and `cmp` over new local utility packages when the supported Go version allows them.
-19. If dependency metadata changes, keep module files and dependent tests synchronized. Do not raise the `go` directive, add toolchain requirements, change module path, or introduce direct dependencies unless the task requires it and the final report calls out the support impact.
-20. Choose configured verification intents that cover formatting, tests, race-sensitive behavior, lint, API drift, module drift, docs, and release metadata when available.
+20. If dependency metadata changes, keep module files and dependent tests synchronized. Do not raise the `go` directive, add toolchain requirements, change module path, or introduce direct dependencies unless the task requires it and the final report calls out the support impact.
+21. Choose configured verification intents that cover formatting, tests, race-sensitive behavior, lint, API drift, module drift, docs, and release metadata when available.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -187,6 +191,7 @@ For concurrency-sensitive changes, report whether a configured race or equivalen
 - If a new package becomes a shared bucket, move behavior back to the owning package or name the concrete capability.
 - If a provider-side interface appears only for mocking, delete it or move a minimal interface to the consumer.
 - If tests need sleeps for concurrency, prefer deterministic synchronization or report the gap.
+- If an iterator function ignores `yield` returning false, a pull iterator omits `stop`, or a channel is replaced by an iterator while concurrency or backpressure remains required, restore the ownership contract before accepting the change.
 - If a goroutine has no owner, stop condition, wait path, cancellation path, or error path, do not add it.
 - If a newer Go feature is useful but the repository's `go` directive or CI matrix is lower, keep a fallback, defer the change, or report the required version bump instead of sneaking in the feature.
 - If HTTP clients, servers, or proxies have no timeout or cancellation boundary, stop and make the missing policy explicit before calling the path production-ready.

package/templates/default/locales/en/.mustflow/skills/line-ending-hygiene/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.line-ending-hygiene
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: line-ending-hygiene
@@ -23,7 +23,7 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Detect line-ending drift without silently rewriting a repository, and normalize only when a repository policy and explicit user request make it safe.
+Detect line-ending drift without silently rewriting a repository, distinguish current working-tree drift from Git conversion warnings, and normalize only when a repository policy and explicit user request make it safe.
 
 <!-- mustflow-section: use-when -->
 ## Use When
@@ -32,6 +32,7 @@ Detect line-ending drift without silently rewriting a repository, and normalize
 - A diff or formatter appears to rewrite files only because of line endings.
 - Docker, Linux, WSL, CI, or shell execution fails with `bad interpreter`, `bash\r`, `env: ...\r`, `exec format error`, or similar CRLF-related symptoms.
 - A proposal suggests creating `.gitattributes`, running renormalization, or rewriting tracked files to fix cross-platform line endings.
+- A PowerShell, formatter, scaffold, generated update, or mechanical rewrite is suspected of changing line endings.
 - A user asks why line-ending warnings appear.
 - A user asks to normalize tracked files to the repository line-ending policy.
 
@@ -47,6 +48,7 @@ Detect line-ending drift without silently rewriting a repository, and normalize
 
 - The warning text or changed-file evidence.
 - Current `.gitattributes` or equivalent repository line-ending policy.
+- Per-file EOL evidence from Git when available, including index EOL, working-tree EOL, and attribute result.
 - Current changed-file status.
 - Whether the request is diagnosis-only, policy authoring, or explicit tracked-file normalization.
 - The configured command intents for line-ending checks and manual normalization.
@@ -66,25 +68,30 @@ Detect line-ending drift without silently rewriting a repository, and normalize
 - Do not rewrite binary files, generated archives, dependency folders, or unrelated source files.
 - Do not change formatting, indentation, or content while handling line endings.
 - Do not create `.gitattributes`, run repository-wide renormalization, or commit line-ending changes as an automatic fallback from a build, Docker, clone, scaffold, or script failure.
+- Do not change local Git EOL configuration or run repository-wide renormalization in a dirty worktree unless the user explicitly requests that scope and reviews the resulting diff.
 
 <!-- mustflow-section: procedure -->
 ## Procedure
 
 1. Inspect the changed-file status before deciding whether line endings are the actual issue.
-2. Use the `line_endings_check` intent when it is configured and agent-runnable.
-3. If no LF policy is declared, report the missing policy instead of normalizing files.
-4. If a runtime error mentions CRLF symptoms, classify it as a line-ending/platform issue before treating it as a missing executable, missing dependency, Docker image problem, or shell bug.
-5. If drift is found, report the affected tracked files and whether normalization was only previewed.
-6. If a policy file needs to be created or changed, keep that as an explicit policy change with reviewable scope. Do not smuggle a new repository-wide policy into an unrelated bug fix.
-7. Use normalization only after an explicit user request, and treat `line_endings_normalize` as manual-only unless the repository declares otherwise.
-8. After any normalization, re-run the line-ending check and a relevant validation intent for the touched scope.
-9. Keep the final report focused on policy, files changed, checks run, and remaining risk.
+2. Inspect the repository EOL policy before blaming a specific write command. A root `.gitattributes` rule such as `* text=auto eol=lf` is the durable source of truth; local Git settings are secondary evidence.
+3. Inspect per-file EOL evidence for any named file before assigning cause. Treat `i/lf w/lf attr/text=auto eol=lf` as currently clean. Treat `w/crlf` or mixed working-tree evidence as actual drift. Treat Git's "LF will be replaced by CRLF" wording as a future-conversion warning from configuration, not proof that the working tree is already CRLF.
+4. Use the `line_endings_check` intent when it is configured and agent-runnable.
+5. If no LF policy is declared, report the missing policy instead of normalizing files.
+6. If a runtime error mentions CRLF symptoms, classify it as a line-ending/platform issue before treating it as a missing executable, missing dependency, Docker image problem, or shell bug.
+7. If a PowerShell or formatter rewrite is involved, separate the read step from the write step. Reading a file does not prove it changed line endings; the writer API, Git checkout policy, previous edits, or generated output may be the actual source.
+8. If drift is found, report the affected tracked files and whether normalization was only previewed.
+9. If a policy file needs to be created or changed, keep that as an explicit policy change with reviewable scope. Do not smuggle a new repository-wide policy into an unrelated bug fix.
+10. Use normalization only after an explicit user request, and treat `line_endings_normalize` as manual-only unless the repository declares otherwise.
+11. After any normalization, re-run the line-ending check and a relevant validation intent for the touched scope.
+12. Keep the final report focused on policy, per-file EOL evidence, files changed, checks run, and remaining risk.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - The agent has not silently rewritten the working tree.
 - The agent has not silently created or changed a repository-wide line-ending policy.
+- The agent has not attributed a line-ending warning to a specific tool without per-file EOL evidence.
 - Any normalization is tied to a declared repository policy.
 - Remaining CRLF, mixed line endings, missing policy, or manual-only command gaps are reported.
 
@@ -112,6 +119,7 @@ If normalization touched code, documentation, templates, or release surfaces, al
 ## Output Format
 
 - Line-ending policy found
+- Per-file EOL evidence inspected
 - Policy changes made or deferred
 - Files with CRLF or mixed line endings
 - Files normalized

package/templates/default/locales/en/.mustflow/skills/llm-hallucination-control-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.llm-hallucination-control-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: llm-hallucination-control-review
@@ -44,6 +44,9 @@ Keep unsupported factual claims from leaving an LLM feature by turning answerabi
 ## Do Not Use When
 
 - The task is mainly prompt wording, prompt builder structure, output schema shape, model settings, few-shot examples, or agent completion wording; use `prompt-contract-quality-review`.
+- The task is an end-to-end RAG failure and it is not yet clear whether ingestion, retrieval,
+  context assembly, prompt construction, generation, citation validation, or answerability failed;
+  use `rag-pipeline-triage` first.
 - The main risk is token spend, provider prompt-cache hit rate, chat-history bloat, RAG context size, model routing cost, reasoning budget, retry replay, or cost observability; use `llm-token-cost-control-review`.
 - The main risk is time to first token, first useful output, streaming latency, LLM round trips, tool wait, prompt-cache latency, model routing speed, realtime continuation, priority tier, predicted-output latency, or user-perceived response speed; use `llm-response-latency-review`.
 - The main risk is autonomous agent execution control, tool-call approval, durable resume behavior, planner/executor/verifier separation, handoffs, guardrail placement, loop budgets, retry classification, or trace outcome evaluation; use `agent-execution-control-review`.

package/templates/default/locales/en/.mustflow/skills/motion-system-contract-review/SKILL.md

@@ -0,0 +1,155 @@
+---
+mustflow_doc: skill.motion-system-contract-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: motion-system-contract-review
+description: Apply this skill when UI motion, animation, transition, microinteraction, motion design systems, WAAPI, CSS animation or transition, Framer Motion, GSAP, view transition, hover/press/focus animation, reduced-motion behavior, animation interruption, or motion state settlement is planned, edited, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.motion-system-contract-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Motion System Contract Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Review UI motion as an explicit state-transition contract instead of decorative prose.
+Motion must not own product state. It may visualize a state change, but the logical state,
+async result, permission, selection, route, or persisted value must be owned outside the animation.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- UI motion, animation, transition, microinteraction, motion recipe, or design-system motion token work is created, edited, reviewed, or reported.
+- The work mentions CSS `animation`, CSS `transition`, `@keyframes`, `animation-fill-mode`, Web Animations API, Framer Motion, GSAP, View Transitions, or component-library motion props.
+- Hover, press, focus, drag, route transition, viewport entry, loading, async success, async failure, toast, dialog, carousel, skeleton, or list reorder motion behavior is part of the change.
+- Reduced motion, interruption, cancellation, settlement, timeline tracks, transform, opacity, filter, layout animation, additive composition, or channel collision needs review.
+- Natural-language animation directions need conversion into observable roles, semantic events, logical from-state and to-state, timeline tracks, and failure policies.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is only per-frame rendering jank, style recalculation, layout thrash, paint cost, or INP delay after the motion contract is already clear; use `frame-render-performance-review`.
+- The task is only first-paint, navigation flicker, hydration flash, blank first render, or state loss across navigation; use `frontend-render-stability`.
+- The task is only general UI polish, layout stress, copy, or visual state coverage without motion-specific behavior; use `ui-quality-gate` or `frontend-stress-layout-review`.
+- The task is only semantic HTML, keyboard operation, focus management, accessible names, or accessibility-tree evidence; use `frontend-accessibility-tree-review`.
+- The change has no user-facing motion, transition, animated state change, or animation-adjacent behavior.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Motion slot, surface, component, route, or design-system recipe being changed.
+- Source role, target roles, semantic event, and whether the event is interaction, component-state, signal, viewport, or timer driven.
+- Logical from-state and to-state, including the source of truth for each state.
+- Timeline tracks with target, channel, range, keyframes, easing, duration, delay, and composition mode when available.
+- Interruption policy for same event, opposite event, unrelated event, route change, unmount, and async cancellation.
+- Settlement policy that explains what durable state is applied after motion completes and which animation effects are cleared.
+- Reduced motion policy and the fallback behavior for no-animation or low-motion users.
+- Binding approach for targets, such as component refs, roles, slots, data attributes, or brittle CSS selectors.
+- Async signal ownership for loading, success, failure, retry, optimistic update, and rollback feedback.
+- Evidence level: static contract review, unit or integration test, story fixture, browser runtime proof, DevTools trace, or reported gap.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The motion behavior is tied to a user-visible state, event, or feedback path.
+- The nearest workflow instructions and configured command intents have been checked.
+- Nearby frontend, accessibility, render performance, and state ownership skills have been considered for overlap.
+- The review can inspect enough code, design-system config, docs, story fixtures, or tests to distinguish logical state from animation effects.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update motion recipes, component motion props, CSS keyframes, transition declarations, animation lifecycle handlers, reduced-motion rules, story fixtures, tests, and directly synchronized docs or templates.
+- Replace brittle selector binding with explicit role/ref/slot/data binding when the local pattern supports it.
+- Add or tighten state, signal, interruption, settlement, reduced-motion, and failure policies near the motion owner.
+- Add focused tests or fixtures that prove state ownership, async signal timing, interruption behavior, reduced motion, and settlement.
+- Do not introduce a new animation framework, global motion DSL, or design-system schema unless the task explicitly asks for that broader architecture.
+- Do not make animation completion the only owner of business, navigation, permission, payment, async result, or persistence state.
+- Do not claim runtime visual proof from a static code review.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Convert animation prose into a contract ledger. Natural-language instructions such as "click makes it pop" are not the source of truth. Record the motion slot, roles, event, from-state, to-state, tracks, policies, and evidence.
+2. Identify the logical state owner before evaluating the animation. Name whether state lives in component state, URL, server cache, form draft, store, DOM attribute, design-system primitive, async signal, or browser capability.
+3. Classify the trigger event as interaction, component-state, signal, viewport, or timer. Do not let a timer pretend to be a real success, failure, permission, or completion signal.
+4. For async success and failure motion, require actual result signals. Loading shimmer, success check, error shake, retry pulse, optimistic success, and rollback motion must follow real async state, not elapsed time alone.
+5. Require explicit from-state and to-state values. If either side is unknown, report the gap before reviewing easing or visual style.
+6. Model the timeline as tracks. For each track, record target role, channel, range, keyframes, easing, duration, delay, fill, and composition.
+7. Check same target and channel overlap. Two tracks writing the same channel over the same time range are a collision unless additive composition is explicit and allowed by the motion profile.
+8. Treat additive composition as opt-in. Confirm all involved tracks, tokens, and runtime APIs support additive behavior. Reject accidental accumulate behavior when the platform or library semantics are unclear.
+9. Keep layout channels off by default. Prefer `transform` and `opacity`; challenge width, height, top, left, margin, padding, grid, or text-flow animation unless there is a measured and accessible reason.
+10. Define interruption policy for same, opposite, and unrelated events. Decide whether to restart, reverse, finish, cancel, queue, merge, or ignore. Include route change, unmount, gesture cancel, and rapid repeat input.
+11. Define settlement policy. On completion, apply durable target state through the state owner, then remove temporary animation effects, inline styles, classes, handles, timers, and observers.
+12. Do not use `animation-fill-mode: forwards`, WAAPI fill, or library fill behavior as durable UI state. Fill may visually bridge the end of a track, but it must not be the source of truth after settlement.
+13. Require reduced motion behavior. Respect `prefers-reduced-motion` and product settings where present. Replace motion with instant state, opacity-only feedback, shorter duration, or non-motion affordances as appropriate.
+14. Check input capability and parity. Hover motion requires hover and fine-pointer capability and must not be the only access path; keyboard, touch, and assistive interaction paths need equivalent state or feedback.
+15. Prefer role/ref binding over brittle selectors. Recipes should bind to component slots, refs, semantic roles, or stable data hooks, not `nth-child`, layout-depth selectors, or visual-only class chains.
+16. Define lifecycle and failure behavior. Development may throw on impossible recipes, but production should skip-effect-and-report animation failures while preserving the core UI action.
+17. Separate contract review from runtime proof. Report whether evidence is static, test-backed, story-backed, browser-observed, or missing.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Motion intent has a state-transition contract, not only animation prose.
+- Logical state owner, semantic event class, from-state, to-state, tracks, interruption, settlement, reduced motion, binding, lifecycle, and failure policies are named.
+- Any same target/channel collision, false async signal, fill-mode state lie, layout-channel risk, hover-only behavior, selector-binding drift, or missing reduced-motion path is fixed or reported.
+- Verification and evidence level are reported honestly.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use focused tests, story fixtures, or browser checks only when the repository command contract exposes them as configured oneshot commands or the user explicitly authorizes that verification path.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the logical state owner cannot be found, stop motion-specific edits and report the missing state owner before changing animation timing.
+- If from-state or to-state is unknown, keep the motion conservative and record the unknown transition instead of inventing a recipe.
+- If async success or failure is timer-driven, route the issue to the async state owner and avoid success/failure motion until real signals exist.
+- If reduced-motion behavior is missing, add an explicit policy or report it as a release-blocking accessibility risk for user-facing motion.
+- If a same target/channel collision exists and additive composition is unsupported or unclear, remove, sequence, or split the conflicting tracks.
+- If runtime proof is unavailable, report static contract evidence and the skipped visual verification instead of claiming the animation works.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Motion surfaces reviewed
+- State owner and semantic event class
+- From-state and to-state contract
+- Timeline tracks and channel collision result
+- Interruption, settlement, reduced-motion, lifecycle, and failure policies
+- Binding approach and selector drift risk
+- Async signal and false-feedback risk
+- Verification run
+- Skipped checks and reasons
+- Remaining motion contract risk

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

@@ -0,0 +1,177 @@
+---
+mustflow_doc: skill.next-action-menu
+locale: en
+canonical: true
+revision: 1
+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.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.next-action-menu
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Next Action Menu
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Turn useful follow-up work into a compact, selectable menu after a task is reported complete or
+paused.
+
+The menu should make the next turn cheaper for the user without pretending that a digit can bypass
+scope, approval, verification, command contracts, release gates, or safety rules.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A final report, completion note, handoff, or repository improvement cycle has one or more useful
+  follow-up tasks.
+- 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
+  user turn.
+- Follow-up tasks differ in value, risk, or urgency enough that ranking helps the user choose.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The current answer is a tiny direct response with no meaningful follow-up.
+- There are no evidence-backed next actions, or all plausible next actions are speculative.
+- The user asked not to include recommendations, menus, or follow-up prompts.
+- The next action requires a blocking product, security, privacy, legal, release, migration,
+  destructive, dependency, credential, deployment, or payment decision that has not been authorized.
+  Report the decision gate instead of offering it as a one-digit action.
+- Another interface already owns selection state and has a stricter picker, ticket, or work-order
+  contract.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The completed or paused task goal and the evidence gathered during the task.
+- Current changed-file, verification, skipped-check, and remaining-risk evidence.
+- The skills used and any next-step candidates produced by those skills.
+- Command contract limits, approval requirements, and release or publish constraints that affect
+  follow-up actions.
+- A freshness boundary for the menu: which final report or latest assistant answer the selection
+  belongs to.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Completion evidence has been calibrated when the menu follows changed files or verification claims.
+- Follow-up items are grounded in current repository evidence, user direction, or explicit skipped
+  checks.
+- High-risk actions remain gated by the user's direct authorization and the repository command
+  contract.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Prefer no edits. This skill normally shapes final reporting and next-turn interpretation.
+- Update workflow docs, skill procedures, templates, or tests only when the menu behavior itself is
+  being added, changed, or synchronized.
+- Do not add autonomous loops, background workers, hidden state files, transcript logs, or persistent
+  task queues solely to remember menu items.
+- Do not convert a menu choice into a command permission, release approval, push approval, deploy
+  approval, destructive action, or dependency-install approval.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Decide whether a menu is useful.
+   - Include a menu only when at least one concrete follow-up task is valuable.
+   - Do not fabricate filler items to reach a fixed row count.
+2. Build at most nine items.
+   - Use digits `1` through `9`.
+   - Use fewer than nine rows when fewer real next actions exist.
+   - Keep each item a bounded task instruction, not a vague theme such as "improve quality".
+3. Rank items by user value, risk reduction, unblock value, confidence, and effort.
+4. Assign a recommendation score:
+   - `A`: high-value, low-ambiguity, safe to start next under current scope.
+   - `B`: valuable and reasonably clear, with manageable verification.
+   - `C`: useful but less urgent, broader, or dependent on more evidence.
+   - `D`: defer unless the user specifically wants this branch.
+   - `E`: low value or blocked by notable uncertainty.
+   - `F`: not recommended now; include only when explicitly useful as a warning or rejected option.
+5. Render the menu as a Markdown table after the completion evidence and skill-selection note when
+   the host format allows it.
+   - Use four columns: number, next task title, description, and recommendation score.
+   - In Korean final reports, use `추천도` for the recommendation-score column label.
+   - Keep descriptions short enough to scan but specific enough to execute.
+   - Localize column labels to the report language when appropriate.
+6. Mark gated items plainly.
+   - Commit, push, publish, deploy, release, destructive cleanup, dependency upgrade, credential
+     work, migration, billing, auth, privacy, or cross-repository edits may appear only when they are
+     genuinely plausible follow-ups.
+   - The description must state the gate, such as explicit user approval, configured command intent,
+     owner decision, or manual verification.
+7. Interpret a single-digit next user message as a menu selection only when all conditions hold:
+   - the immediately relevant previous assistant final report contained a next-action menu;
+   - the digit maps to an item in that menu;
+   - the menu is still fresh for the current repository, branch, and task context;
+   - the selected item does not bypass approvals, command contracts, or safety rules.
+8. If a digit is stale, ambiguous, unmapped, or conflicts with newer user instructions, do not guess.
+   Ask for clarification or report that no active menu item can be selected.
+9. After a valid selection, treat the selected row as the new user task, then re-run normal
+   instruction refresh, skill selection, repository evidence gathering, and verification selection.
+10. If the selected row is high-risk or gated, stop at the gate and ask for the missing approval or
+    decision before performing that action.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The menu offers only real, bounded next actions.
+- Single-digit follow-up behavior is convenient but cannot override newer user instructions, safety
+  rules, or command contracts.
+- High-risk actions are visibly gated instead of hidden behind a number.
+- The next selected task can be executed as a normal mustflow task with fresh instruction and skill
+  selection.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use narrower configured checks when the menu behavior changes code, tests, templates, or public docs.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If there are no concrete next actions, omit the menu instead of padding it.
+- If every valuable next action is gated, show the gate and do not present the digit as sufficient
+  approval.
+- If a selected digit no longer matches current state, ask for confirmation before acting.
+- If follow-up items become broad backlog planning, switch to `repo-improvement-loop` or
+  `idea-triage`.
+- If a menu item would require task-instruction repair before execution, use
+  `clarifying-question-gate` or `task-instruction-authoring` before implementation.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Menu included or omitted, with reason
+- Numbered next-action rows, when included
+- Recommendation scores and gate labels
+- Active-menu freshness boundary
+- Selected digit interpretation, when applicable
+- Skills used for the selected follow-up task
+- Command intents run
+- Skipped checks and reasons
+- Remaining selection, approval, or stale-context risk

package/templates/default/locales/en/.mustflow/skills/observability-debuggability-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.observability-debuggability-review
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: observability-debuggability-review
-description: Apply this skill when code is created, changed, reviewed, or reported and logs, metrics, traces, spans, events, dashboards, alerts, runbooks, telemetry context, sampling, redaction, external dependency calls, queues, batch jobs, caches, pools, rate limits, feature flags, releases, or partial-success paths need review for whether an operator can narrow an incident quickly without high-cardinality metric explosions, missing denominators, lost trace context, or unsafe telemetry data.
+description: Apply this skill when code is created, changed, reviewed, or reported and logs, metrics, traces, spans, events, dashboards, alerts, runbooks, telemetry context, collectors, exporters, telemetry queues, canaries, sampling, redaction, external dependency calls, queues, batch jobs, caches, pools, rate limits, feature flags, releases, or partial-success paths need review for whether an operator can narrow an incident quickly without high-cardinality metric explosions, missing denominators, lost trace context, silent telemetry loss, or unsafe telemetry data.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -39,6 +39,7 @@ The review question is not "does the code emit telemetry?" It is "when this path
 - Code creates, changes, reviews, or reports logs, structured events, metrics, spans, traces, trace context, baggage, telemetry attributes, dashboards, alerts, runbooks, sampling, redaction, observability exporters, or custom collectors.
 - HTTP handlers, API clients, database calls, cache layers, queues, workers, cron jobs, batch jobs, pipelines, webhook handlers, payment or order flows, file processing, feature flags, experiments, rate limits, pools, or external dependencies need incident evidence.
 - Code claims a path is observable, debuggable, monitored, traced, metered, alerted, operationally safe, SLO-ready, dashboard-ready, or easy to troubleshoot.
+- The telemetry pipeline itself can drop, delay, sample, parse-fail, mis-route, or hide logs, metrics, traces, events, or dashboards while product systems appear healthy.
 - A change adds retries, timeouts, cancellation, queue settlement, idempotency, external side effects, partial completion, fallback behavior, cache fallback, rate limiting, or release gating where telemetry can hide or reveal the real failure.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -60,6 +61,7 @@ The review question is not "does the code emit telemetry?" It is "when this path
 - Trace and event model: span boundaries, parent-child relationships, async propagation, queue or worker propagation, external call spans, per-attempt spans, span events, feature flag attributes, release attributes, and sampling policy.
 - Log model: event names, stable error categories, reason codes, severity, structured fields, safe identifiers, redaction, public versus internal message split, and whether matching counters exist for repeated log events.
 - Operational domains: HTTP golden signals, dependency health, DB queries, transactions, queues, batch jobs, pipelines, caches, pools, rate limits, feature flags, releases, migrations, partial-success and compensation paths.
+- Telemetry pipeline evidence: generated signals, accepted signals, dropped signals, export failures, queue utilization, queue oldest age, retry backlog, scrape failures, collector restarts, ingestion canary lag, parser or mapping failures, searchable count, DLQ oldest age, sampling keeps and drops, storage retention, and dashboard read-path status.
 - Privacy and retention constraints: secrets, tokens, cookies, authorization headers, raw request bodies, personal data, payment data, prompt or document text, baggage propagation, telemetry sink boundary, and retention policy.
 - Verification evidence: existing tests, schema checks, telemetry fixtures, instrumentation tests, runbook docs, dashboard definitions, alert rules, configured command intents, and any manual-only production evidence boundary.
 
@@ -150,15 +152,21 @@ The review question is not "does the code emit telemetry?" It is "when this path
 17. Check telemetry self-observability.
     - Exporters, collectors, custom metric collectors, log sinks, trace queues, and sampling pipelines need dropped, failed, queued, scrape error, and export latency evidence when they can blind operators.
     - If telemetry failure can hide product failure, treat missing self-metrics as an operational risk.
-18. Check sampling policy.
+18. Check signal pipeline loss and read-path visibility.
+    - Compare produced, accepted, exported, stored, and query-visible signal counts when the path depends on logs, metrics, traces, or events for diagnosis.
+    - Use canary events or synthetic heartbeats when "no telemetry" could mean no traffic, collector failure, broken parser, dropped queue, retention gap, or dashboard read failure.
+    - Track event timestamp versus observed timestamp, queue oldest age, DLQ oldest age, parser or mapping failures by service and version, and duplicate or sequence-gap evidence.
+    - Separate telemetry write-path health from read-path health. A sink can store data that dashboards cannot query, and dashboards can be healthy while new signals are not arriving.
+    - If collector, sink, dashboard, or production telemetry checks are outside repository commands, report the manual-only boundary.
+19. Check sampling policy.
     - Head sampling can drop rare errors and slow traces.
     - Error, slow, retry-exhausted, high-latency, partial-success, DLQ, and compensation-failure traces often need keep rules, tail sampling, or explicit event evidence.
     - If sampling is outside the repository, report the manual-only evidence boundary instead of assuming critical traces are retained.
-19. Check privacy before telemetry leaves the process.
+20. Check privacy before telemetry leaves the process.
     - Redact or classify tokens, passwords, authorization headers, cookies, raw bodies, emails, phone numbers, payment data, personal identifiers, prompt text, confidential document text, provider payloads, and full SQL before logger, metric, trace, baggage, or exporter entry.
     - Baggage should be small, safe, low-lifetime, and intentional. Do not use it as a general request metadata bag.
     - Report sink-side masking as insufficient when sensitive data can already leave the process unredacted.
-20. Require telemetry tests or contract evidence where feasible.
+21. Require telemetry tests or contract evidence where feasible.
     - Good tests assert stable event names, bounded label values, denominator counters, trace-context propagation, redaction, sampling flags, feature flag attributes, release attributes, and failure-category mapping.
     - Source-level guards can prevent raw URL or user id metric labels when runtime telemetry tests are not available.
     - If dashboards, alerts, production traces, or load evidence are manual-only, complete available checks and report the evidence gap.
@@ -166,7 +174,7 @@ The review question is not "does the code emit telemetry?" It is "when this path
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
-- The changed path has an incident question, signal ledger, metric model, trace and log correlation model, cardinality boundary, privacy boundary, and evidence level.
+- The changed path has an incident question, signal ledger, metric model, trace and log correlation model, telemetry pipeline survival boundary, cardinality boundary, privacy boundary, and evidence level.
 - Missing denominators, average-only latency, success-only logs, uncorrelated logs, raw URL labels, raw user labels, raw SQL telemetry, lost async trace context, attempt and operation collapse, generic timeout or cancellation buckets, missing dependency names, missing queue age, missing batch last-success timestamp, missing pool saturation, missing release attribution, decorative metrics, unsafe baggage, telemetry self-blindness, and sampling that drops critical failures are fixed or reported.
 - Observability claims are backed by configured tests, schema or fixture evidence, local telemetry conventions, dashboard or alert files, static review evidence, or labeled as manual-only or missing.
 
@@ -200,7 +208,7 @@ Prefer the narrowest configured test, build, docs, release, or mustflow intent t
 ## Output Format
 
 - Observability boundary reviewed
-- Incident question, signal ledger, metric model, trace and log correlation, cardinality, identity propagation, attempts versus operation, timeout or cancellation classification, external dependency, DB and transaction, idempotency and partial success, queue or batch, cache, pool saturation, rate limit, feature or release attribution, alert or runbook, telemetry self-observability, sampling, privacy, and test evidence findings
+- Incident question, signal ledger, metric model, trace and log correlation, cardinality, identity propagation, attempts versus operation, timeout or cancellation classification, external dependency, DB and transaction, idempotency and partial success, queue or batch, cache, pool saturation, rate limit, feature or release attribution, alert or runbook, telemetry self-observability, signal pipeline survival, sampling, privacy, and test evidence findings
 - Observability fixes made or recommended
 - Evidence level: configured-test evidence, telemetry fixture evidence, dashboard or alert file evidence, static review risk, manual-only, missing, or not applicable
 - Command intents run