mustflow 2.32.0 → 2.38.0

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/html-code-change/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.html-code-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: html-code-change
-description: Apply this skill when HTML, templates, JSX or component markup, forms, controls, dialogs, navigation, tables, media, metadata, SEO head content, or structured data are created or changed.
+description: Apply this skill when HTML, templates, JSX or component markup, native forms, controls, popovers, dialogs, navigation, tables, media, metadata, SEO head content, or structured data are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -34,7 +34,7 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 ## Use When
 
 - `.html`, JSX, TSX, Vue, Svelte, Astro, or template markup changes.
-- The task touches layout landmarks, headings, forms, buttons, links, dialogs, menus, tabs, accordions, custom selects, composite widgets, tables, media, metadata, canonical links, Open Graph, robots, hreflang, viewport, or JSON-LD.
+- The task touches layout landmarks, headings, forms, buttons, links, popovers, dialogs, menus, tabs, accordions, custom selects, composite widgets, tables, media, metadata, canonical links, Open Graph, robots, hreflang, viewport, or JSON-LD.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -48,6 +48,7 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 - Existing page layout, document shell, head/SEO helpers, metadata builders, canonical URL helpers, sitemap or robots config, form components, interactive control components, and tests.
 - Target framework conventions for rendering, routing, hydration, and metadata.
 - Visible page content, H1 or primary title, main entity, locale, indexing intent, and data sources for title, description, image, author, date, price, rating, availability, and FAQ content when metadata changes.
+- Browser-native behavior expected from the markup: navigation, form submission, validation, autocomplete, input modality, popover behavior, dialog focus, inert background handling, media sizing, lazy loading, and history integration.
 - Accessibility and validation tooling declared in the command contract.
 
 <!-- mustflow-section: preconditions -->
@@ -63,6 +64,7 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 
 - Use semantic landmarks, headings, native links, native buttons, and native form controls where possible.
 - Connect labels, help text, error text, required state, autocomplete, and input type explicitly.
+- Use native validation, input modes, popovers, dialogs, details/summary, and inert behavior when they fit the intended interaction and browser target.
 - Keep metadata and structured data consistent with visible page content.
 - Add ARIA only when native semantics cannot express the control and the required role, state, keyboard, and focus behavior are implemented.
 
@@ -77,16 +79,19 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 6. Reject clickable `div` or `span` controls, clickable icons without buttons, anchors without `href`, links used as buttons, nested interactive controls, positive `tabindex`, focusable `aria-hidden` content, and focus outline removal without a replacement focus style.
 7. Use ARIA only when native HTML cannot express the needed semantics. Validate the role is legal for the element, the accessible name exists, required states are present, visual and ARIA states stay synchronized, keyboard behavior matches the widget pattern, and focus behavior is explicit.
 8. For custom legacy button-like elements that cannot be replaced, require `role`, focusability, Enter activation, Space activation, Space scroll prevention, pointer activation, duplicate-event prevention, and visible focus. Use native buttons instead whenever possible.
-9. For dialogs, prefer native dialog when the project can support it. Otherwise implement focus entry, Tab and Shift+Tab containment, Escape behavior, inert or unreachable background content, visible close or cancel control, focus return, and an accessible name.
-10. For tabs, use tablist, tab, and tabpanel semantics only for a real tabbed interface. Require one active tab, panel linkage, roving tabindex, arrow key movement, Home and End where expected, and Enter or Space activation when activation is manual.
-11. For menus, do not use ARIA menu roles for ordinary site navigation. Site navigation is a nav landmark with links. Use ARIA menu patterns only for application-style action menus with a button trigger, expanded state, focus strategy, Escape close behavior, and focus return.
-12. For forms, verify visible label association, help association, error association, required text, native required state, autocomplete, validation timing, invalid state, error summary behavior, and submission behavior.
-13. Use placeholder, title, aria-label, color, icon, or toast-only feedback only as supplementary affordances, not as the only label, required indicator, or error explanation.
-14. For metadata, read visible content and the metadata generation path first. Keep title, description, canonical, Open Graph, Twitter or X card data, robots, hreflang, and JSON-LD aligned with visible content, locale, URL, and indexing intent.
-15. Structured data must describe content visible on the same page. Do not invent ratings, reviews, FAQ items, authors, prices, availability, dates, organizations, product properties, or claims not backed by the page data source.
-16. Ensure every HTML page has a valid non-empty language and responsive viewport that does not disable zoom. Mixed-language passages should identify their language when needed.
-17. Keep inline script and style minimal; move behavior and styling to the existing project layers unless the framework requires an inline boundary.
-18. Choose configured verification intents that cover markup validity, lint, build, accessibility, route rendering, metadata, and docs when available.
+9. For popovers, prefer the native popover pattern for lightweight anchored disclosure, teaching UI, picker panels, or menus that do not need modal focus trapping. Verify trigger ownership, light-dismiss behavior, focus behavior, accessible name, and fallback or browser target.
+10. For dialogs, prefer native dialog when the project can support it. Otherwise implement focus entry, Tab and Shift+Tab containment, Escape behavior, inert or unreachable background content, visible close or cancel control, focus return, and an accessible name.
+11. Do not use dialog for every overlay. Use popover for non-modal transient UI, details/summary for simple disclosure, and dialog for modal tasks or interruptions that require focus containment.
+12. For tabs, use tablist, tab, and tabpanel semantics only for a real tabbed interface. Require one active tab, panel linkage, roving tabindex, arrow key movement, Home and End where expected, and Enter or Space activation when activation is manual.
+13. For menus, do not use ARIA menu roles for ordinary site navigation. Site navigation is a nav landmark with links. Use ARIA menu patterns only for application-style action menus with a button trigger, expanded state, focus strategy, Escape close behavior, and focus return.
+14. For forms, verify visible label association, help association, error association, required text, native required state, autocomplete, `inputmode`, `enterkeyhint`, validation timing, invalid state, error summary behavior, and submission behavior.
+15. Prefer native constraint validation for simple required, type, length, pattern, range, and step rules. Add custom validation only for business rules, cross-field rules, async validation, or localized error ownership the native browser cannot express.
+16. Use placeholder, title, aria-label, color, icon, or toast-only feedback only as supplementary affordances, not as the only label, required indicator, or error explanation.
+17. For metadata, read visible content and the metadata generation path first. Keep title, description, canonical, Open Graph, Twitter or X card data, robots, hreflang, and JSON-LD aligned with visible content, locale, URL, and indexing intent.
+18. Structured data must describe content visible on the same page. Do not invent ratings, reviews, FAQ items, authors, prices, availability, dates, organizations, product properties, or claims not backed by the page data source.
+19. Ensure every HTML page has a valid non-empty language and responsive viewport that does not disable zoom. Mixed-language passages should identify their language when needed.
+20. Keep inline script and style minimal; move behavior and styling to the existing project layers unless the framework requires an inline boundary.
+21. Choose configured verification intents that cover markup validity, lint, build, accessibility, route rendering, metadata, and docs when available.
 
 <!-- mustflow-section: form-accessibility -->
 ## Form Accessibility Rules
@@ -101,6 +106,7 @@ Preserve semantic structure, native controls, keyboard access, focus behavior, f
 - Multiple submit errors should use an error summary near the top of the form or page when the project pattern supports it. Summary items should link to invalid fields, and inline errors should remain next to fields.
 - Use alert or live regions only for dynamic validation or submit feedback that should be announced. Do not spam alerts on every keystroke or place interactive controls inside alerts.
 - Inputs collecting information about the current user should use appropriate autocomplete tokens. Do not blindly disable autocomplete on login, checkout, contact, signup, or account forms.
+- Use `type`, `inputmode`, `autocomplete`, `enterkeyhint`, `min`, `max`, `step`, `minlength`, `maxlength`, and `pattern` as contracts for keyboards, password managers, autofill, and native validation. Do not replace them with JavaScript-only parsing when the browser can enforce the basic rule.
 
 <!-- mustflow-section: metadata-policy -->
 ## Metadata And Structured Data Rules
@@ -123,6 +129,7 @@ Reject or revise the patch when any of these appear without strong justification
 - New `div` or `span` interaction where a native link, button, or form control would work.
 - Anchors without `href`, buttons implemented as links, links implemented as buttons, nested interactive controls, clickable icons without native controls, or site navigation using ARIA menu roles.
 - Custom controls without complete accessible name, role, state, keyboard, focus, and hidden-content behavior.
+- Popovers, dialogs, or overlays that replace native behavior without trigger, focus, light-dismiss, inert, or fallback review.
 - Positive `tabindex`, hidden content that remains tabbable, focusable `aria-hidden` content, or invisible focus.
 - Form controls without visible labels, placeholder-only labels, disconnected help or error text, color-only required or error state, premature `aria-invalid`, or autocomplete removed without reason.
 - Metadata or JSON-LD that contradicts visible content, fabricates facts, points canonical or social URL at the wrong page, disables zoom, omits page language, or accidentally noindexes a public page.