mustflow 2.31.0 → 2.37.1

package/templates/default/locales/en/.mustflow/skills/dependency-upgrade-review/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.dependency-upgrade-review
 locale: en
 canonical: true
-revision: 1
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: dependency-upgrade-review
-description: Apply this skill when dependency versions, lockfiles, package manager metadata, security advisory fixes, generated dependency outputs, runtime engine constraints, peer dependency contracts, framework plugins, CI actions, Docker base images, or toolchain versions are upgraded, downgraded, pinned, widened, regenerated, reviewed, or reported.
+description: Apply this skill when dependency versions, lockfiles, package manager metadata, security advisory fixes, generated dependency outputs, runtime engine constraints, Python runtime support, peer dependency contracts, framework plugins, TypeScript compiler tracks, CI actions, Docker base images, or toolchain versions are upgraded, downgraded, pinned, widened, regenerated, reviewed, or reported.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -39,6 +39,8 @@ Review dependency upgrades as runtime, build, security, package, and generated-o
 - A security advisory, vulnerability scanner, Dependabot, Renovate, package audit, language audit, CI action update, Docker base image update, framework plugin update, formatter/linter/bundler update, ORM update, code generator update, protobuf/OpenAPI generator update, or toolchain update is reviewed or applied.
 - A task claims a dependency change is "only patch", "only devDependency", "safe minor", "security-only", "transitive only", "lockfile only", or "no runtime change".
 - A dependency update touches installation, publish output, generated clients, SDKs, native binaries, browser bundles, serverless or edge runtime, ESM/CJS/module format, Python markers, Go module graph, Cargo features, JVM dependency mediation, .NET target frameworks, Ruby/PHP/Swift lockfiles, Docker images, or CI actions.
+- A Python runtime support floor, CI matrix, container image, `requires-python`, standard-library feature expectation, or security-default expectation changes as part of an upgrade.
+- A TypeScript upgrade touches TypeScript 6 transition deprecations, TypeScript 7 native preview, `@typescript/native-preview`, `tsgo`, compiler API consumers, declaration emit, framework typecheck wrappers, or editor language-service behavior.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -92,11 +94,15 @@ Review dependency upgrades as runtime, build, security, package, and generated-o
 9. Review the lockfile as a graph, not a blob. Check direct and transitive replacements, newly introduced packages, removed packages, optional/platform packages, source URLs, integrity or checksum changes, peer resolution, engine requirements, native prebuilds, and postinstall or lifecycle scripts.
 10. Review runtime boundaries that dependency upgrades commonly break: ESM/CJS and package `type`, `exports` and conditional exports, browser/node/edge conditions, Node engine support, Python dependency markers and extras, Go module path changes, Cargo feature unification, native builds, SSR/client split, WebView/native split, and generated client or SDK types.
 11. Treat framework, plugin, code generator, formatter, linter, bundler, ORM, protobuf, OpenAPI, GraphQL, database driver, and test-runner upgrades as behavior changes when their output, config schema, plugin API, CLI flags, or generated code can change.
-12. For new dependencies introduced by the upgrade, invoke the `dependency-reality-check` decision path: license, maintainer risk, provenance, lifecycle scripts, binary downloads, package age, transitive size, supply-chain risk, and replacement path.
-13. For Docker base images and CI actions, review them as dependencies. Check image/action source, version pinning policy, digest use when required, runtime version changes, security patch reason, cache impact, and deployment smoke coverage.
-14. Synchronize dependent surfaces: generated code, snapshots, mocks, fixtures, examples, SDK clients, OpenAPI or GraphQL artifacts, README install guidance, migration docs, changelog, Docker/CI docs, and package publish metadata.
-15. Select verification from the command contract based on risk. Patch and narrow transitive changes can use focused checks when they cover the touched path; major, framework, runtime-engine, generated-output, security-sensitive, Docker, or CI-action updates need broader checks.
-16. Report skipped checks explicitly. If the command contract lacks a dependency graph or package verification intent, do not invent raw package-manager commands; report the missing configured intent.
+12. For Python runtime upgrades, treat `requires-python`, CI matrices, base images, dependency markers, wheels, packaging output, standard-library API availability, and security-default changes as one compatibility contract. Review version-gated standard-library usage and changed defaults before assuming the upgrade is only a dependency resolution change.
+13. For Python upgrades that adopt newer standard-library behavior, call out affected paths such as archive extraction, subprocess handling, async lifecycle, import/resource loading, typing surfaces, data-class shapes, and diagnostic flags. Keep fallbacks or compatibility wording when the repository still supports older interpreters.
+14. For TypeScript upgrades, classify the compiler track explicitly: stable `typescript` and `tsc`, TypeScript 6 transition release, TypeScript 7 native preview via `@typescript/native-preview` and `tsgo`, editor extension preview, or framework-owned wrapper. Do not treat a native preview package as a stable replacement for the `typescript` package unless the repository policy says so.
+15. For TypeScript 6, review deprecations as future TypeScript 7 removals. For TypeScript 7 native preview, review unsupported compiler API, transformer, language-service plugin, watch/incremental, declaration emit, framework wrapper, and generated-output risks before changing dependency declarations or scripts.
+16. For new dependencies introduced by the upgrade, invoke the `dependency-reality-check` decision path: license, maintainer risk, provenance, lifecycle scripts, binary downloads, package age, transitive size, supply-chain risk, and replacement path.
+17. For Docker base images and CI actions, review them as dependencies. Check image/action source, version pinning policy, digest use when required, runtime version changes, security patch reason, cache impact, and deployment smoke coverage.
+18. Synchronize dependent surfaces: generated code, snapshots, mocks, fixtures, examples, SDK clients, OpenAPI or GraphQL artifacts, README install guidance, migration docs, changelog, Docker/CI docs, and package publish metadata.
+19. Select verification from the command contract based on risk. Patch and narrow transitive changes can use focused checks when they cover the touched path; major, framework, runtime-engine, generated-output, security-sensitive, Docker, CI-action, Python runtime, or TypeScript compiler-track updates need broader checks.
+20. Report skipped checks explicitly. If the command contract lacks a dependency graph, package verification, Python runtime matrix, TypeScript declaration, or compiler-comparison intent, do not invent raw package-manager commands; report the missing configured intent.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -105,6 +111,8 @@ Review dependency upgrades as runtime, build, security, package, and generated-o
 - The lockfile and declaration files agree.
 - Direct and transitive changes are understood, not hidden behind lockfile volume.
 - Runtime engine, peer dependency, optional/platform package, feature, module-format, generated-output, and publish-surface risks are classified.
+- Python runtime upgrades classify standard-library availability, changed defaults, packaging output, and security-behavior impact.
+- TypeScript compiler-track changes distinguish stable compiler upgrades from native-preview comparison work.
 - Security fixes are narrow unless the user explicitly accepted a broader modernization.
 - Tests and scanners were not weakened to pass the upgrade.
 
@@ -134,6 +142,7 @@ Prefer the narrowest configured intent that proves the actual upgraded dependenc
 - If tests fail after an upgrade, do not delete tests, skip tests, loosen assertions, lower coverage, disable scanners, or widen permissions unless the behavior contract intentionally changed and the report says so.
 - If a security upgrade requires broad modernization, split the minimum patch from the modernization when possible.
 - If generated output changes, regenerate from the official generator path and explain the generated diff. Do not hand-edit generated dependency output.
+- If TypeScript 7 native preview is introduced, keep stable TypeScript verification unless the repository explicitly adopts the preview path and all compiler API, framework wrapper, declaration, and generated-output risks are covered.
 - If configured verification is missing, report the missing command intent instead of inferring a package-manager command.
 
 <!-- mustflow-section: output-format -->
@@ -144,6 +153,8 @@ Prefer the narrowest configured intent that proves the actual upgraded dependenc
 - Direct and transitive graph changes
 - Compatibility classification: patch, minor, major, pre-1.0, security, toolchain, generated-output, Docker, or CI action
 - Runtime, peer, engine, module, feature, platform, generated-output, and publish-surface risks
+- Python runtime, standard-library, packaging, and changed-default risks when relevant
+- TypeScript compiler-track and native-preview risks when relevant
 - Security advisory and fixed-range notes when relevant
 - Surfaces synchronized
 - Command intents run

package/templates/default/locales/en/.mustflow/skills/frontend-render-stability/SKILL.md

@@ -0,0 +1,144 @@
+---
+mustflow_doc: skill.frontend-render-stability
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: frontend-render-stability
+description: Apply this skill when frontend navigation flicker, theme flash, hydration flash, blank initial render, unstable loading shell, route transition jank, BFCache breakage, browser-native navigation regression, or first-paint instability is reported, created, edited, reviewed, or verified.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.frontend-render-stability
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Frontend Render Stability
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Diagnose and fix visible frontend instability by proving which layer flashes first: document navigation, theme or CSS application, hydration, first-render data, loading layout, font or media loading, or view-transition behavior.
+
+This skill is symptom-first. It is not an Astro, SvelteKit, CSS, or performance checklist by itself. Use it to decide the root cause order, then activate the narrower framework, markup, CSS, UI, or performance skill before editing that surface.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A user reports page flicker, theme flash, flash of unstyled content, dark-mode flash, blank page before content, hydration flash, route transition jank, state loss across navigation, layout shift during loading, or slow first visible render.
+- A change adds, removes, or reviews client-side routing, view transitions, prefetching, shared layouts, persistent shells, early theme initialization, root HTML templates, hydration boundaries, skeletons, font loading, or first-render data flow.
+- An Astro, SvelteKit, React, Vue, or other frontend app needs evidence that navigation keeps the common UI and theme stable instead of replacing the whole document unnecessarily.
+- Browser-only state, local storage, cookies, media queries, locale, time, randomness, or async client effects affect initial HTML, hydration, or theme selection.
+- A change may replace browser-native navigation, form submission, history, scrolling, focus restoration, BFCache eligibility, event delivery, or image/font loading with JavaScript behavior.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is ordinary visual polish with no navigation, first-paint, hydration, loading, or route-transition symptom; use `ui-quality-gate` or `css-code-change`.
+- The task is only framework-specific routing, content, or data behavior with no visible instability; use the matching framework skill.
+- The change is purely backend performance, database latency, or queue throughput with no browser render impact; use `performance-budget-check`.
+- A configured browser, visual, or performance verification intent is missing. Do not invent ad hoc dev-server, watcher, or browser-session steps inside this skill; report the missing intent.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Symptom description, affected routes, whether it happens on first load, client-side navigation, hard reload, theme toggle, slow network, reduced motion, or reduced data.
+- App framework, version signals, root HTML or layout files, route/link components, router configuration, root CSS, theme initialization, font loading, and affected components.
+- Evidence from current files or allowed verification showing whether navigation requests a new document, whether the shared shell persists, and when theme and CSS are applied.
+- Data-loading ownership for above-the-fold content: SSR or static data, route load function, streamed data, client effect, store initialization, or browser-only fetch.
+- Native browser contracts affected by the change: anchors, forms, history, scroll restoration, focus, BFCache, HTTP cache, service worker, preload hints, passive event listeners, Pointer Events, ResizeObserver, IntersectionObserver, or abortable requests.
+- Configured verification intents and any project-approved visual, browser, or build checks.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and the command contract have been checked.
+- The symptom is tied to a visible render, navigation, first-paint, or loading behavior, not only subjective animation preference.
+- Framework-specific API names and browser features are verified against project dependencies or current official documentation before relying on them in code or durable docs.
+- Any external advice, snippets, or AI output is treated as input, not authority.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Root HTML templates, app shells, layouts, route links, router configuration, early theme scripts, root CSS, theme tokens, font and media loading hints, skeleton or loading state layout, hydration boundaries, route data loaders, and tests or docs directly tied to render stability.
+- Browser-native behavior restoration such as semantic links/forms, reserved media geometry, `fetchpriority` where appropriate, passive event listeners, abortable stale requests, focus restoration, BFCache-safe lifecycle handling, and reduced JavaScript work before first paint.
+- Framework-specific edits only after using the matching skill, such as `astro-code-change`, `svelte-code-change`, `html-code-change`, `css-code-change`, or `ui-quality-gate`.
+- Keep fixes local to the proven instability layer. Do not migrate frameworks, disable SSR, convert the app to an SPA, add a client router, add animation libraries, or broaden preload behavior without evidence and a reported tradeoff.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the symptom by phase: hard reload, same-document navigation, cross-document navigation, first paint, hydration, data arrival, loading placeholder, font swap, media load, theme toggle, or view-transition animation.
+2. Prove or rule out a full document reload before optimizing animation. Inspect link behavior and router configuration first. In browser evidence, a new `document` request during an internal navigation usually means the shared shell, CSS, and theme are being replaced.
+3. If full reload is not intended, inspect the framework-native navigation path before adding custom JavaScript:
+   - Astro: check whether `<ClientRouter />` is intentionally present, whether links opt out with `data-astro-reload`, whether persistent shared UI needs `transition:persist`, whether `astro:before-swap` or `astro:after-swap` must preserve theme state, and whether prefetch policy is bounded.
+   - SvelteKit: check whether internal links or GET forms are using normal SvelteKit navigation, whether `data-sveltekit-reload`, `rel="external"`, or direct `window.location` forces a reload, whether `data-sveltekit-preload-data` or `data-sveltekit-preload-code` is appropriate, and whether `onNavigate` view-transition work can finish quickly.
+   - Other frameworks: use their native router, layout persistence, and preload primitives before adding a second navigation layer.
+4. If the symptom is a theme or color flash, inspect first-paint ordering. Theme state that changes global colors must be applied on `document.documentElement` before first paint when possible, with `color-scheme`, root `html, body` backgrounds, and CSS tokens matching the same state. Do not rely on component mount or a late store subscription for initial theme.
+5. If CSP is active, check the framework's supported nonce, hash, or template mechanism before adding inline early scripts. Do not weaken CSP just to hide a flash.
+6. If hydration flashes or mismatches appear, compare server-rendered markup with first client state. Remove time, randomness, locale, timezone, viewport, localStorage, and browser-only values from SSR-visible initial markup unless they are serialized or guarded with an intentional placeholder.
+7. If above-the-fold content appears blank until client effects run, move first-render data to the framework's route loader, server data, static generation, or serialized initial data when that matches secrecy and freshness rules. Use client effects for enhancement, subscriptions, and browser-only work, not required initial page data.
+8. If a client effect fetches required first-screen data, check whether it can move to server/static/route data. When it must stay client-side, abort stale requests, ignore obsolete responses, and keep the previous stable shell until the new result is ready.
+9. If loading UI shifts layout, reserve final geometry for skeletons, images, videos, embeds, ads, fonts, and lazy content. Loading states should preserve the app shell and task context rather than replacing the page with an unrelated blank screen.
+10. For LCP media, avoid accidental lazy loading, reserve dimensions, and use project-approved priority hints only for the actual first-viewport candidate. Do not preload every hero-like asset.
+11. Check whether JavaScript replaced a browser-native contract. Prefer anchors for navigation, forms for form submission, CSS for simple states, native scroll behavior where acceptable, Pointer Events over duplicate mouse/touch stacks, passive listeners for scroll-blocking inputs, and observers over polling.
+12. Preserve BFCache and history behavior where possible. Avoid unconditional `unload` handlers, global synchronous storage work during navigation, and stale global state that assumes every navigation creates a fresh document.
+13. If view transitions are used, treat motion as progressive enhancement. Keep names unique where required, avoid duplicate rendered `view-transition-name` values, respect reduced motion, and disable or narrow transitions that conceal content state changes or stall navigation.
+14. Check font and CSS delivery only after document reload, theme order, hydration, and data timing are understood. Use project-approved font loading, preloads, `font-display`, and root background policies without bypassing existing asset strategy.
+15. Choose the narrowest configured verification intents that cover the changed layer. If a real browser, visual diff, network-panel, throttled-load, BFCache, or INP check would be required but no configured one-shot intent exists, report that gap instead of claiming visual proof.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The report names the proven or most likely instability layer and the layers ruled out.
+- Navigation behavior is intentional: full document reload is either removed, preserved with a reason, or reported as an unresolved product decision.
+- Theme, CSS, font, hydration, data, loading, and transition changes preserve accessibility, reduced motion, state ownership, and framework boundaries.
+- Native browser contracts are preserved, restored, or explicitly traded off with a reason.
+- Any framework-specific changes have used the matching framework skill.
+- Visual verification is current and explicit, or the missing configured visual/browser intent is reported.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Use broader configured tests only when route behavior, SSR/client boundaries, public docs, templates, or shared UI contracts change. Use visual or browser verification only through configured one-shot intents or an explicit user-approved workflow.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the symptom cannot be reproduced from current evidence, report the reproduction gap and avoid adding speculative router, animation, or preload code.
+- If the fix would require a new router, SSR disablement, framework migration, CSP weakening, global preload policy, or development server workflow, stop and report the architectural or command-contract decision needed.
+- If JavaScript is fighting browser defaults, remove the unnecessary ownership first before adding more lifecycle hooks, timers, polling, or global state.
+- If official framework docs conflict with snippets or older advice, follow the current project version and official docs, then report the source-freshness boundary.
+- If verification fails after a render-stability change, use `failure-triage` before broadening the fix.
+- If the route is stable but visual polish remains, hand off to `ui-quality-gate` or `css-code-change` instead of expanding this skill.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Symptom and affected phase
+- Evidence inspected
+- Instability layer found or ruled out
+- Framework-specific skills used
+- Files changed
+- Command intents run
+- Skipped visual or browser checks and reason
+- Remaining render-stability risk

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.go-code-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: go-code-change
-description: Apply this skill when Go source, modules, package APIs, interfaces, errors, goroutines, channels, context propagation, tests, or generated code boundaries are created or changed.
+description: Apply this skill when Go source, modules, package APIs, interfaces, errors, goroutines, channels, context propagation, HTTP clients or servers, reverse proxies, JSON encoding, filesystem roots, network addresses, runtime limits, benchmarks, tests, tools, or generated code boundaries are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -28,13 +28,14 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Preserve Go package, module, API, error, context, concurrency, and test boundaries without adding needless abstraction.
+Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JSON, filesystem, and test boundaries without adding needless abstraction.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- `.go`, `go.mod`, `go.sum`, `go.work`, build tags, generated code, public package API, tests, benchmarks, goroutines, channels, or context propagation change.
-- The task touches interfaces, error wrapping, package structure, concurrency ownership, or module dependencies.
+- `.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.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -48,6 +49,8 @@ Preserve Go package, module, API, error, context, concurrency, and test boundari
 - `go.mod`, `go.sum`, `go.work`, build tooling, lint config, and CI hints.
 - All files in the changed package, including `_test.go`, build-tagged files, examples, and generated-file markers.
 - The public API surface when exported identifiers, errors, or package paths change.
+- Runtime and deployment context when the change touches HTTP, goroutines, timers, memory, `GOMAXPROCS`, cgroups, race detection, PGO, profiling, or container behavior.
+- Minimum supported Go version, `go` directive, `toolchain` directive, `GOEXPERIMENT`, and whether the feature is stable, experimental, or repository-pinned.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
@@ -56,6 +59,7 @@ Preserve Go package, module, API, error, context, concurrency, and test boundari
 - Inspect the whole package before adding names or methods.
 - Determine whether the change affects exported API, concurrency ownership, or dependency graph.
 - Identify generated files and avoid direct edits unless explicitly requested.
+- If a Go release, "latest Go", standard-library feature, runtime default, experimental package, or toolchain claim is written durably, use `version-freshness-check` and official Go sources.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -66,13 +70,19 @@ Preserve Go package, module, API, error, context, concurrency, and test boundari
 - Preserve context propagation across API and goroutine boundaries.
 - Return actionable errors and wrap causes when callers need `errors.Is` or `errors.As`.
 - Add table-driven tests when they clarify behavior.
+- Keep runtime and deployment tuning close to the process owner; do not hide memory, CPU, timeout, or profiling policy in unrelated helpers.
 
 <!-- mustflow-section: procedure -->
 ## Procedure
 
 1. Read module files, package files, tests, build tags, and generated-code markers.
-2. Classify the change as package API, internal implementation, dependency, error behavior, context flow, concurrency, or test-only.
-3. Check package boundaries before adding a package or interface:
+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;
+   - 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:
    - reject shared bucket packages named `common`, `util`, `types`, `interfaces`, `api`, or `models` unless the repository already has a specific local convention with a narrower meaning;
    - put an interface in the package that consumes the methods, not in the package that merely implements them;
    - create an interface only after a real consumer needs that exact method set;
@@ -80,41 +90,79 @@ Preserve Go package, module, API, error, context, concurrency, and test boundari
    - reject provider-side interfaces that exist only for mocks;
    - reject provider constructors that return interfaces by default; prefer concrete exported types such as `*Client`, `*Store`, or `*Service`;
    - verify that a package split reduces a real dependency direction problem or creates a coherent capability instead of hiding imports.
-4. If exported identifiers or package paths change, classify the public API impact:
+5. If exported identifiers or package paths change, classify the public API impact:
    - treat exported functions, variables, constants, types, methods, struct fields, interfaces, interface method sets, sentinel errors, typed errors, module path, package import path, and minimum Go version as contracts;
    - assume exported symbols in a v1+ module are public API unless the package is internal or local evidence proves otherwise;
    - do not remove, rename, or change exported signatures, exported field types, exported interface methods, or observable error behavior without an explicit breaking-change plan;
    - adding a method to an exported interface is breaking for external implementations even when adding a method to a concrete type would be safe.
-5. Preserve error contracts:
+6. Preserve error contracts:
    - use `errors.Is` and `errors.As` semantics as observable API when documented or already tested;
    - do not compare error strings;
    - do not expose dependency sentinel or typed errors through wrapping unless the package intentionally supports them as API;
    - treat a change between observable wrapping and non-observable formatting as API-sensitive;
+   - use `errors.AsType` only when the supported Go version allows it and the shorter form preserves the same typed-error contract;
    - add tests for documented sentinel or typed errors when the error behavior changes.
-6. If goroutines or channels change, name the owner, stop condition, cancellation path, wait path, error path, close responsibility, and test synchronization.
-7. Reject fire-and-forget goroutines unless they are owned by a long-lived object with a shutdown path, joined before return, managed by a group with a wait path, or explicitly documented as safely detached.
-8. Preserve context propagation:
+7. If goroutines or channels change, name the owner, stop condition, cancellation path, wait path, error path, close responsibility, and test synchronization.
+8. Choose the right goroutine primitive:
+   - use `sync.WaitGroup.Go` only for tasks that do not return errors and must not panic;
+   - use an errgroup-style boundary when work needs error propagation, context cancellation, or concurrency limits;
+   - do not hand-roll `WaitGroup` plus error channel plus cancellation plus semaphore unless the local code already owns that exact pattern and tests cover it;
+   - treat buffered-channel semaphores as semantic backpressure, not just a performance knob; changing capacity can change ordering and pressure;
+   - treat `TryLock` as suspicious unless skipping the work is genuinely correct and observable.
+9. Reject fire-and-forget goroutines unless they are owned by a long-lived object with a shutdown path, joined before return, managed by a group with a wait path, or explicitly documented as safely detached.
+10. Preserve context propagation:
    - request-scoped functions accept `ctx` first and pass it down;
    - do not store request context in structs;
    - do not pass nil context;
    - do not introduce `context.Background()` inside request or operation depth unless it is a true process root with a documented owner;
    - derived contexts must release their cancel function on every path;
+   - use cancellation causes when callers or logs need to distinguish shutdown, rate limit, dependency timeout, parent cancellation, and explicit abort;
+   - use `context.WithoutCancel` only for short bounded cleanup such as audit or log flush work; add a fresh timeout or wait boundary because it does not inherit cancellation or deadline;
+   - when `context.AfterFunc` bridges a context-unaware API, design the stop function and completion wait separately because stopping does not wait for an already-running callback;
    - blocking sends, receives, waits, retry loops, worker loops, and external calls must observe cancellation or be proven non-blocking.
-9. Preserve channel ownership:
+11. Preserve channel ownership:
    - the sender that knows all sends are complete closes the channel;
    - 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.
-10. 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.
-11. Keep concurrency tests deterministic. Do not use elapsed real time to wait for goroutine progress; use explicit synchronization, owned lifecycle waits, fake time, or the repository's established concurrency test helper.
-12. 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.
-13. Choose configured verification intents that cover formatting, tests, race-sensitive behavior, lint, API drift, and module drift when available.
+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:
+   - 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:
+   - 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:
+   - 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:
+   - 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:
+   - 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 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;
+   - 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.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - Package ownership and exported API impact are clear.
 - Context, goroutine, channel, and error ownership are explicit.
+- Go-version-gated syntax, standard-library APIs, runtime defaults, experiments, and module metadata are compatible with the repository's supported Go version.
+- HTTP timeout, proxy, JSON, filesystem, network address, runtime, test-time, benchmark, and tool decisions are explicit where touched.
 - Tests cover the changed behavior without sleeps as synchronization.
 - Module drift is reported when dependency verification cannot run.
 
@@ -130,7 +178,7 @@ Use configured oneshot command intents when available:
 - `docs_validate_fast`
 - `mustflow_check`
 
-For concurrency-sensitive changes, report whether a configured race or equivalent verification intent exists.
+For concurrency-sensitive changes, report whether a configured race or equivalent verification intent exists. For Go-version-gated features, report whether the repository has a configured matrix, build, or test path for the selected Go version.
 
 <!-- mustflow-section: failure-handling -->
 ## Failure Handling
@@ -140,6 +188,9 @@ For concurrency-sensitive changes, report whether a configured race or equivalen
 - 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 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.
+- If JSON tag changes alter omitted fields, zero values, HTML escaping, or experimental JSON behavior, treat the change as an API contract risk.
 - If a public error stops satisfying documented `errors.Is` or `errors.As` checks, restore the contract or report the breaking-change requirement.
 - If wrapping would expose a dependency error as public API, keep the dependency error internal or document the intentional contract.
 - If a generated file must change but no generator intent exists, report the missing command contract.
@@ -150,6 +201,7 @@ For concurrency-sensitive changes, report whether a configured race or equivalen
 - Boundary checked
 - Package and API impact
 - Context/concurrency/error notes
+- Go version, runtime, HTTP, JSON, filesystem, benchmark, and tool notes when relevant
 - Files changed
 - Command intents run
 - Skipped checks and reasons

package/templates/default/locales/en/.mustflow/skills/heuristic-candidate-selection/SKILL.md

@@ -0,0 +1,165 @@
+---
+mustflow_doc: skill.heuristic-candidate-selection
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: heuristic-candidate-selection
+description: Apply this skill when a large folder, repository, documentation set, or refactor request needs cheap-signal candidate selection before reading or editing many files.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.heuristic-candidate-selection
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Heuristic Candidate Selection
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Prevent agents from opening every file in a large scope before they know which files are likely to matter.
+
+Use cheap repository signals to rank candidate files, calibrate the ranking with small samples, read only the selected batch, and verify that the selected change actually improved the targeted risk.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- The user asks to find sparse, stale, incomplete, weak, outdated, duplicate, oversized, risky, or refactor-worthy files across a broad folder or repository.
+- A request such as "fill in thin docs", "improve weak documents", "refactor files with too much code", "clean up this folder", "audit this area", or "find what to fix first" would otherwise tempt the agent to read many files.
+- The task needs candidate discovery before implementation, especially for documentation sets, content collections, tests, frontend components, backend services, logs, data files, migrations, or monorepo packages.
+- The next safe edit depends on separating file discovery, target selection, precise reading, and modification.
+- The user values efficient navigation, bounded context, or batch-by-batch work over a broad manual sweep.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task names one or two exact files and the required edit is already clear.
+- A failing command, stack trace, or reproduction path already identifies the first files to inspect; use `repro-first-debug` or `failure-triage`.
+- The task is only to orient in an unfamiliar area without ranking candidates; use `codebase-orientation`.
+- The task is only to choose a local precedent after the target file is known; use `pattern-scout`.
+- The user explicitly asks for exhaustive manual review of every file and accepts the cost.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User goal, target scope, and whether the output should be analysis-only, candidate list, or implementation batch.
+- File-type and role boundaries, such as source, tests, docs, schemas, configs, generated files, assets, logs, data, migrations, or package surfaces.
+- Cheap signals available without reading every full file: file names, sizes, line counts, symbol or heading outlines, changed-file summaries, recent churn, inbound or outbound dependency hints, search hits, TODO-like markers, entrypoints, schema or config centrality, test proximity, user-facing routes, and generated-file markers.
+- Exclusion rules for generated output, vendored code, lockfiles, snapshots, build artifacts, caches, and intentionally tiny adapter, index, barrel, or marker files.
+- Risk and importance factors for the domain, such as user-visible route, public API, schema ownership, money, permission, data mutation, external I/O, runtime configuration, search exposure, internal-link centrality, or recent work-in-progress.
+- Batch limit, folder quota, confidence threshold, and verification intents relevant to the selected surface.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- Candidate selection is needed before reading complete files.
+- Missing cheap-signal sources can be reported without inventing a ranking.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Analysis-only mode may produce a ranked candidate list, read plan, batch plan, and excluded-surface notes without changing files.
+- Implementation mode may edit only the selected bounded batch and directly synchronized files required by the chosen change.
+- Add or update lightweight audit helpers, fixtures, or docs only when the repository already has an appropriate owned surface or the user asked for reusable automation.
+- Do not read, summarize, or modify a whole large folder just because it is in scope.
+- Do not modify generated files, external dependencies, lockfiles, snapshots, or broad shared utilities unless the selected task explicitly requires that surface and the matching skill allows it.
+- Do not fill unknown source material, book summaries, external facts, API behavior, or domain claims from model memory. Mark such targets as `needs_source`, `needs_runtime_check`, or `needs_domain_decision`.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Define the selection job.
+   - Restate the user goal, target scope, intended deliverable, batch size, and whether edits are allowed now.
+   - Decide whether candidates should optimize for risk, importance, certainty, repair value, or low-cost cleanup.
+2. Classify file roles before scoring.
+   - Separate human-authored source from generated output, dependency folders, build artifacts, caches, snapshots, lockfiles, vendored code, and intentionally small glue files.
+   - Treat config, schema, route, permission, payment, data mutation, migration, queue, webhook, cache, and external-adapter files as high-impact even when small.
+3. Gather cheap signals before opening full files.
+   - Prefer file metadata, changed-file summaries, search hits, symbol or heading outlines, import or dependency hints, route maps, schema names, test names, warning summaries, and bounded head or tail previews.
+   - Use configured command receipts and declared generated maps only as evidence or navigation aids; they do not replace current files or command contracts.
+   - For documentation and content, score body-like content separately from frontmatter, imports, exports, component wrappers, links, images, quotes, code blocks, placeholders, and duplicated descriptions.
+   - For code, score churn, entrypoint proximity, dependency centrality, missing nearby tests, TODO-like markers, type bypasses, exception density, mutation paths, async or concurrency hints, config and schema ownership, and public-contract exposure.
+4. Build a candidate score instead of using one metric.
+   - Combine risk, importance, certainty, and estimated fix cost.
+   - Calibrate small-file findings by file role so index files, barrel exports, type declarations, marker files, and config shims are not treated as broken merely because they are short.
+   - For large-file refactors, prefer symbol outlines, export lists, responsibility clusters, churn, dependency centrality, and test coverage gaps before reading the whole file.
+   - For documentation gaps, compare each file to its sibling folder pattern and expected document role before calling it thin.
+5. Avoid tunnel vision.
+   - Limit candidates per folder or package so one noisy directory does not consume the whole batch.
+   - Include a small random or representative sample from lower-scored files to expose blind spots in the scoring formula.
+   - Select good sibling examples as references before editing weak files.
+6. Choose the read batch.
+   - Produce a ranked list with path, score drivers, role classification, likely risk, and why this candidate is worth reading now.
+   - Select only the top bounded batch plus any directly required sibling examples or one-step dependencies.
+   - Keep candidate selection separate from editing; do not justify edits by retrofitting the ranking after reading.
+7. Read precisely.
+   - Open only selected files, relevant symbols, relevant sections, head or tail previews, and direct dependencies needed to validate the candidate.
+   - If a candidate proves healthy, mark it `skipped_healthy` and move on instead of forcing a change.
+   - If evidence is insufficient, mark it `needs_source`, `needs_runtime_check`, `needs_domain_decision`, or `needs_larger_scope` rather than guessing.
+8. Edit the selected batch only when implementation is in scope.
+   - Preserve frontmatter, imports, exports, public APIs, routes, schemas, component contracts, and file identity unless the chosen change explicitly requires them.
+   - For documents with missing source evidence, add safe scaffolding such as reading questions, verification prompts, known context, application ideas, and follow-up checks instead of invented summaries.
+   - For code refactors, keep behavior-preserving changes separate from behavior changes and activate narrower code, test, security, data, UI, or pattern skills as soon as their trigger appears.
+9. Verify and re-audit.
+   - Run the narrowest configured verification intents that cover the changed surfaces.
+   - Compare the post-change state to the original selection signals when an audit score, warning count, TODO count, test proximity, or candidate risk was the reason for the work.
+   - Stop if the diff grows beyond the selected batch, the scoring evidence was wrong, or verification fails and needs triage.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Broad-scope work starts from cheap signals and a bounded candidate list, not full-file reading.
+- Selected candidates have explicit score drivers, role classification, and read reasons.
+- Healthy candidates can be skipped without edits.
+- Edited files stay inside the selected batch and directly required synchronized surfaces.
+- The final report distinguishes selected, modified, skipped, deferred, and unsafe-to-guess candidates.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use narrower configured test, build, documentation, package, or mustflow intents when they better prove the selected surface. Do not invent verification commands from package scripts, external advice, or model memory.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If cheap signals are unavailable or contradictory, report the missing evidence and fall back to a smaller manual sample instead of reading the whole scope.
+- If many candidates tie, use folder quotas, importance factors, and representative sampling rather than expanding the batch until it becomes unreviewable.
+- If generated files, lockfiles, snapshots, vendored code, or build output dominate the candidate list, tighten exclusions and restart candidate selection.
+- If selected documentation lacks trustworthy source material, do not summarize the missing source; mark the file for source-backed follow-up or add only safe reading and verification scaffolding.
+- If a refactor candidate touches a public API, schema, config, permission, money, data, external I/O, or migration boundary, activate the narrower matching skill before editing.
+- If the batch diff becomes too large or mixes unrelated concerns, stop and report a smaller next batch.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Selection goal and mode
+- Target scope and excluded surfaces
+- Cheap signals gathered
+- Scoring factors and calibration sample
+- Ranked candidates with score drivers
+- Selected read batch and batch limits
+- Files modified, skipped healthy, or deferred with reason
+- Post-change audit or comparison result when applicable
+- Command intents run
+- Skipped checks and reasons
+- Remaining selection, evidence, or batch-size risk