mustflow 2.103.21 → 2.103.31

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.svelte-code-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: svelte-code-change
-description: Apply this skill when Svelte or SvelteKit components, routes, load functions, server actions, endpoints, stores, context, runes, SSR boundaries, server-only imports, accessibility warnings, or tests are created or changed.
+description: Apply this skill when Svelte or SvelteKit components, routes, universal or server load functions, form actions, endpoints, hooks, stores, context, runes, props, snippets, bindings, SSR, hydration, streaming, preload, invalidation, server-only imports, env boundaries, adapters, Vite, TypeScript, packaging, accessibility warnings, or tests are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -28,64 +28,78 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Preserve Svelte component reactivity, SvelteKit SSR/server/client boundaries, data secrecy, load/action/endpoint contracts, request-scoped state ownership, accessibility, and generated route behavior. Choose files by data boundary first, not by filename habit.
+Preserve Svelte component reactivity, SvelteKit SSR/server/client execution modes, data secrecy, load/action/endpoint contracts, request-scoped state ownership, hydration, streaming, invalidation, adapter output, accessibility, and generated route behavior. Choose files by data boundary and execution mode first, not by filename habit.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- `.svelte`, `+page`, `+layout`, `+page.server`, `+layout.server`, `+server`, load functions, form actions, endpoints, stores, context, runes, `$app` imports, `$lib/server`, hooks, route params, or Svelte tests change.
-- The task touches state management, SSR errors, browser APIs, forms, routing, progressive enhancement, request-local data, server-only imports, private/public environment variables, or Svelte 5 runes.
+- `.svelte`, `.svelte.ts`, `.svelte.js`, `+page`, `+layout`, `+page.server`, `+layout.server`, `+server`, load functions, form actions, endpoints, stores, context, snippets, bindings, runes, `$app` imports, `$lib/server`, hooks, route params, route matchers, or Svelte tests change.
+- The task touches state management, SSR errors, hydration warnings, browser APIs, forms, routing, progressive enhancement, preload, invalidation, request-local data, server-only imports, private/public environment variables, adapters, Vite, TypeScript, package exports, or Svelte 5 runes.
+- The task upgrades, reviews, or writes docs about Svelte, SvelteKit, Vite, `@sveltejs/vite-plugin-svelte`, `svelte-check`, an adapter, `@sveltejs/package`, or generated Svelte library output.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
 
 - The change is plain CSS or HTML with no Svelte or SvelteKit behavior; use the relevant UI foundation skill.
 - The service code is framework-free and no Svelte boundary changes.
+- The task only updates external framework version prose; use `source-freshness-check` unless the Svelte procedure itself changes.
 
 <!-- mustflow-section: required-inputs -->
 ## Required Inputs
 
-- Package metadata, Svelte config, Vite config, TypeScript config, route segment files, hooks, app types, stores/runes/context, form schema, and tests.
-- Svelte version, route data source, secrecy, request scope, mutation type, serialization requirement, SSR/client boundary, browser dependency, and state owner.
-- Imports from `$lib/server`, `*.server.*`, `$env/static/private`, `$env/dynamic/private`, DB/filesystem/server SDK modules, cookies, auth headers, and `event.locals`.
+- Package metadata, Svelte config, Vite config, TypeScript config, route segment files, hooks, app types, stores/runes/context, form schema, adapter config, package export metadata, and tests.
+- Svelte and SvelteKit version tracks, route data source, secrecy, request scope, mutation type, serialization requirement, SSR/client boundary, browser dependency, state owner, and adapter target.
+- Imports from `$lib/server`, `*.server.*`, `$env/static/private`, `$env/dynamic/private`, DB/filesystem/server SDK modules, cookies, auth headers, `event.locals`, `$app/state`, `$app/navigation`, `$app/forms`, and browser-only libraries.
+- Official or repository-local source evidence before preserving exact latest-version, release-date, Node/Vite requirement, adapter behavior, or compiler behavior claims.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
 ## Preconditions
 
-- For route work, read the sibling `+layout`, `+page`, `+page.server`, and `+server` files as one boundary.
-- Classify every data access by origin, secrecy, request scope, mutation, browser dependency, and serialization before choosing a SvelteKit file.
-- Treat all route files as potentially server-executed until proven otherwise.
+- For route work, read sibling and parent `+layout`, `+layout.server`, `+page`, `+page.server`, `+server`, hooks, app types, and route matcher files as one boundary.
+- Classify every data access by origin, secrecy, request scope, mutation, browser dependency, serialization, invalidation dependency, and adapter support before choosing a SvelteKit file.
+- Treat universal route files as server-executed and browser-executed until proven otherwise.
+- Refresh official package or vendor sources before preserving exact "latest", Node/Vite minimum, adapter, or release-note claims; otherwise keep those facts out of durable skill text or mark them as snapshot-only in the report.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
 
-- Keep secrets, private environment, database clients, and cookie-authenticated data in server-only files.
-- Use browser APIs only behind client-safe lifecycle or environment guards.
+- Keep secrets, private environment, database clients, server SDKs, cookie-authenticated data, and request identity in server-only files.
+- Use browser APIs only behind client-safe lifecycle, dynamic import, event, action, or environment boundaries.
 - Keep state local unless shared ownership is justified.
-- Preserve form actions and progressive enhancement instead of replacing all forms with client-only fetch.
+- Preserve form actions and progressive enhancement instead of replacing page forms with client-only fetch.
 - Use context for request-scoped component-tree sharing instead of module singletons.
-- Use `$derived` for computed display values and `$effect` only for browser-side effects and cleanup.
+- Use `$derived` for computed display values and `$effect` only for browser-side effects, subscriptions, DOM, timers, observers, third-party browser libraries, and cleanup.
+- Keep SvelteKit, Vite, TypeScript, adapter, `svelte-check`, and package export surfaces synchronized when toolchain behavior changes.
 
 <!-- mustflow-section: procedure -->
 ## Procedure
 
-1. Read route segment files, parent layouts, stores/runes/context, hooks, app types, and tests.
-2. Identify Svelte version and whether the code uses runes or legacy reactivity.
-3. Before choosing a file, classify every data access with: origin, secrecy, request scope, mutation, browser dependency, and serialization.
-4. If data requires DB, filesystem, private env, cookies, auth headers, `event.locals`, server SDKs, or request-local identity, keep it in server-only code: `+page.server`, `+layout.server`, `+server`, `hooks.server`, or `$lib/server`.
-5. If data is public and can be safely fetched by the browser without secrets, universal load is allowed.
-6. If the operation is a page form mutation, prefer `+page.server` actions over a custom JSON endpoint.
-7. If the operation is a public HTTP API, webhook, mobile API, stream, file response, or non-page endpoint, use `+server`.
-8. If the value is UI-only state such as modal open, selected tab, draft input, accordion state, hover state, or local editing state, keep it in component `$state` or local context.
-9. If a value is computed from reactive inputs, use `$derived`. Do not use `$effect` to copy or synchronize derived state.
-10. Use `$effect`, lifecycle hooks, event handlers, actions, or dynamic imports for browser-only APIs and browser-only libraries. Do not touch `window`, `document`, `localStorage`, `matchMedia`, canvas, or browser-only imports in SSR top-level code.
-11. Keep request-specific user/session/auth state out of module-level mutable variables, global stores, exported `$state`, and load/action side effects.
-12. Do not write to stores from load functions.
-13. Keep server load return values intentionally serializable and minimal. Do not pass secrets, raw sessions, tokens, hidden DB fields, or whole service responses to the browser.
-14. Prefer `$app/state` over legacy `$app/stores` in SvelteKit projects that use the newer SvelteKit state API.
-15. Do not hide SSR errors by disabling SSR unless the user explicitly accepts that product and architecture change.
-16. Treat accessibility compiler warnings as real findings unless a local false-positive reason is documented.
+1. Read route segment files, parent layouts, route matchers, stores/runes/context, hooks, app types, Svelte/Vite/TypeScript config, adapter config, package metadata, and tests.
+2. Identify Svelte and SvelteKit version tracks and whether the code uses runes, legacy reactivity, or mixed migration mode.
+3. Before choosing a file, classify every data access with: origin, secrecy, request scope, mutation, browser dependency, serialization, dependency tracking, invalidation trigger, and adapter support.
+4. Keep DB, filesystem, private env, cookies, auth headers, `event.locals`, server SDKs, and request-local identity in server-only code: `+page.server`, `+layout.server`, `+server`, `hooks.server`, `$lib/server`, or `*.server.*`.
+5. Treat `+page.ts` and `+layout.ts` as universal. They may run during SSR and later in the browser; do not import browser-only packages, private env, DB clients, or server modules there.
+6. If `+page.server` and universal `+page` or `+layout` coexist, check that server-load data is intentionally passed through the universal `load` return value when the page component needs it.
+7. Keep `load` side-effect-free. Do not increment counters, mark reads, mutate stores, write analytics, or change module state from `load`; preload and navigation can run it before the user commits.
+8. Avoid `await parent()` waterfalls. Start independent fetches before awaiting parent data, and keep auth checks in `hooks.server` or route-specific server load when child data must not execute first.
+9. Use SvelteKit-provided `fetch` inside load when dependency tracking, SSR response inlining, and hydration reuse matter. For custom clients, register `depends(...)` keys and invalidate the exact URL or dependency key.
+10. Use page form actions for page-owned mutations. Preserve `fail(...)`, `redirect(303, ...)`, `use:enhance`, `update()`, `applyAction()`, focus reset, and invalidation behavior when enhancing forms.
+11. Use `+server` for public HTTP APIs, webhooks, mobile APIs, streams, file responses, and custom response contracts. Do not create a JSON endpoint for a normal page form unless there is a non-page consumer.
+12. For streaming load data, finish auth, redirects, and headers before streaming starts. Handle promise rejections, check adapter and proxy buffering, and stream only data whose late failure does not change page policy.
+13. Preserve hydration markers and valid HTML structure. Do not use HTML minifiers, CDN rewrites, or edge transforms that remove Svelte hydration comments without verifying hydration.
+14. If navigation reuses page or layout components, make route-dependent values `$derived` from `data`, `$app/state`, or URL state; use `{#key ...}` only when a real remount boundary is intended.
+15. Put SSR-affecting filters, search, pagination, sorting, and shareable state in URL search params. Keep temporary UI state local or snapshot-like.
+16. Use `$state` only for state that should update UI, `$derived`, or `$effect`. Keep large immutable payloads, table rows, CMS payloads, parser outputs, and third-party data as plain values or `$state.raw` with reassignment.
+17. Do not destructure `$state` or proxy objects when live reactivity is required. Read fields at the use site or derive a narrow value.
+18. Use `SvelteMap`, `SvelteSet`, `SvelteDate`, `SvelteURL`, or reassignment patterns when reactive special objects are required; do not expect ordinary `Map`, `Set`, `Date`, `URL`, or class internals to be deeply tracked.
+19. Use `$derived` or `$derived.by` for filtering, sorting, totals, validation results, labels, and view models. Do not use `$effect` to copy or synchronize derived state.
+20. Keep `$effect` dependencies narrow and synchronous. Read dependencies before `await`, `setTimeout`, or callbacks; use `untrack` for incidental logging, snapshots, or non-dependency reads.
+21. Return cleanup from effects that create subscriptions, intervals, observers, sockets, editors, charts, canvas loops, or external library instances.
+22. Treat props as parent-owned. Use callback props for changes and `$bindable` only for narrow form-control-like two-way APIs. Preserve wrapper binding chains or convert them to explicit callbacks.
+23. In Svelte 5, treat DOM event handlers as props. When spreading rest props through wrappers, intentionally compose external handlers with internal policy instead of relying on spread order.
+24. Treat snippets as typed render callbacks. Require optional snippet guards, pass row or slot-like data as parameters, and avoid hidden parent-state capture in reusable library components.
+25. Check SvelteKit, Vite, TypeScript, adapter, and package output as one toolchain boundary. Do not edit generated `.svelte-kit/tsconfig.json`; fix `svelte.config`, `kit.alias`, package exports, `types`, `svelte` conditions, `files`, and CSS side effects at their source.
 
 <!-- mustflow-section: data-boundary-policy -->
 ## Data Boundary Policy
@@ -94,6 +108,7 @@ Preserve Svelte component reactivity, SvelteKit SSR/server/client boundaries, da
 - Public external APIs and public CMS data may live in universal load only when the browser may call them directly without secrets.
 - DB, filesystem, private env, server SDKs, cookies, auth headers, sessions, and `event.locals` belong in server-only files.
 - User-specific data must be read server-side and narrowed before being serialized into `data`.
+- Server load return values must be intentionally serializable and minimal.
 - Page forms should use form actions by default.
 - External clients, webhooks, mobile apps, streaming responses, and custom HTTP responses belong in `+server`.
 - Browser-only values belong in component effects, event handlers, dynamic imports, or browser actions.
@@ -105,18 +120,22 @@ Preserve Svelte component reactivity, SvelteKit SSR/server/client boundaries, da
 - `+page.server.ts` and `+layout.server.ts` are for server-only page data.
 - `+page.server.ts` actions are for page-owned form mutations.
 - `+server.ts` is for HTTP endpoints, webhooks, non-page APIs, streams, files, and custom responses.
+- Route matchers, optional params, rest params, and route groups are public URL and layout/auth behavior, not only folder naming.
 - Do not create a JSON endpoint for a normal page form unless there is a non-page consumer.
 - Do not wrap server-only imports in browser guards. Fix the import graph.
 
 <!-- mustflow-section: runes-state-policy -->
 ## Runes And State Policy
 
-- Use `$state` for local interactive UI state.
-- Use `$derived` for calculations from props, route data, page state, or local state.
-- Use `$effect` only for browser-side effects, subscriptions, DOM, canvas, analytics, third-party browser libraries, and cleanup.
+- Use `$state` for owned interactive UI state.
+- Use `$state.raw` only when reassignment, not internal mutation, is the update model.
+- Use `$state.snapshot` before sending proxy state to serializers, workers, chart libraries, equality tools, or external APIs that should see plain data.
+- Use `$derived` for calculations from props, route data, page state, URL state, or local state.
+- Use `$effect` only for browser-side effects, subscriptions, DOM, canvas, analytics, timers, third-party browser libraries, and cleanup.
 - Use stores for external streams or manual subscribe/unsubscribe interop, not ordinary component state.
 - Use context for parent-owned values shared down the component tree, especially request-scoped layout data.
 - Do not reassign reactive context objects after placing them in context; update their properties or pass getter functions when needed.
+- Use stable keys for changing lists. Do not use array indexes as keys when rows can reorder, insert, delete, transition, or own child state.
 
 <!-- mustflow-section: ssr-debug-policy -->
 ## SSR Debug Policy
@@ -127,7 +146,7 @@ When SSR breaks, inspect in this order:
 2. `$lib/server`, `*.server.*`, DB, filesystem, admin SDK, or server-only import chains.
 3. Request-local state stored in module singletons, stores, or exported `$state`.
 4. Browser API access at module top-level or during SSR render.
-5. Hydration mismatch from time, randomness, locale, timezone, localStorage, or browser-only initial state.
+5. Hydration mismatch from invalid HTML, removed comments, time, randomness, locale, timezone, localStorage, or browser-only initial state.
 6. Route-level SSR disabling only after the product accepts an SPA-like shell.
 
 <!-- mustflow-section: hard-bans -->
@@ -137,18 +156,21 @@ When SSR breaks, inspect in this order:
 - Do not move required first-render page data into lifecycle hooks or `$effect`.
 - Do not import `$lib/server`, `*.server.*`, private env modules, DB clients, filesystem, or admin SDKs from universal/client route files or shared client utilities.
 - Do not mutate module-scope variables, global stores, or exported `$state` with user/session/request data during SSR, load, or actions.
-- Do not use `$effect` to compute derived values.
+- Do not use `$effect` to compute derived values or synchronize state mirrors.
 - Do not put browser-only library imports at top level when the package touches browser globals during import.
 - Do not serialize secrets, raw sessions, access tokens, hidden DB fields, or whole service responses through load data.
+- Do not edit generated `.svelte-kit` files as source.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - Server/client and SSR boundaries are explicit.
-- State owner and derived/effect behavior are clear.
+- Route, load, action, endpoint, invalidation, and streaming behavior are clear.
+- State owner, derived/effect behavior, props ownership, snippets, and binding behavior are clear.
 - Forms remain progressive unless intentionally changed.
 - Private data stays server-only and serialized data is intentionally minimal.
 - Request-scoped sharing uses load data, props, or context instead of module singletons.
+- Adapter, Vite, TypeScript, and package output impacts are reported when touched.
 - Accessibility warnings are resolved or justified.
 
 <!-- mustflow-section: verification -->
@@ -163,7 +185,7 @@ Use configured oneshot command intents when available:
 - `docs_validate_fast`
 - `mustflow_check`
 
-Report missing Svelte check, SSR render, form action, or browser verification intents when relevant.
+Report missing Svelte check, SSR render, hydration, form action, browser, adapter, package, or preview-mode verification intents when relevant.
 
 <!-- mustflow-section: failure-handling -->
 ## Failure Handling
@@ -173,13 +195,16 @@ Report missing Svelte check, SSR render, form action, or browser verification in
 - If accessibility warnings require an ignore, include the specific reason in the code or report.
 - If server-only imports leak into universal/client files, move the boundary instead of adding runtime guards.
 - If request-local data is stored globally, move it to server load, actions, context, or persistent storage with user scoping.
+- If exact framework, adapter, Vite, Node, or release claims cannot be refreshed from official sources, omit them from durable skill text and report them as unverified snapshot context.
+- If streaming, hydration, adapter output, package exports, or preview-mode behavior cannot be verified by configured intents, report the missing runtime smoke coverage.
 
 <!-- mustflow-section: output-format -->
 ## Output Format
 
 - Boundary checked
-- SSR/server/client and state notes
-- Form/action/accessibility impact
+- SSR/server/client, route, load, action, invalidation, and streaming notes
+- Runes, state, props, snippet, binding, and accessibility notes
+- Adapter, Vite, TypeScript, and package-output notes when touched
 - Files changed
 - Command intents run
 - Skipped checks and reasons

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

@@ -0,0 +1,305 @@
+---
+mustflow_doc: skill.vue-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: vue-code-change
+description: Apply this skill when Vue, Nuxt, Pinia, Vue Router, Vue SFCs, Composition API, reactivity, props, emits, slots, v-model, SSR, hydration, lazy hydration, Vite/Vue toolchain, or Vue-related tests are created, changed, reviewed, or upgraded.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.vue-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Vue Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Vue and Nuxt component, reactivity, state, routing, SSR, hydration, lazy-hydration,
+toolchain, and package-version contracts when changing Vue projects. Review Vue code by asking
+which value is being tracked, which component owns it, which runtime renders it first, and whether
+the server and client will agree.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.vue` files, Vue SFC macros, Composition API, Options API, composables, custom directives,
+  Pinia stores, Vue Router routes or guards, Nuxt pages/layouts/components/plugins/middleware,
+  Vite Vue config, `vue-tsc`, or Vue-related tests change.
+- The task touches reactive state, `ref`, `reactive`, `shallowRef`, `computed`, `watch`,
+  `watchEffect`, `defineProps`, reactive props destructure, `defineModel`, `defineEmits`,
+  fallthrough attributes, slots, template refs, provide/inject, Teleport, Suspense, SSR,
+  hydration, lazy hydration, ClientOnly behavior, or route lazy loading.
+- A contribution proposes Vue performance, hydration, state ownership, component API, Pinia,
+  router, Nuxt, Vite, TypeScript, or Vue version support changes.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is framework-free JavaScript or TypeScript with no Vue, Nuxt, Pinia, or router
+  boundary; use the language-specific skill.
+- The task is only plain HTML/CSS layout, accessibility, localization, or image delivery with no
+  Vue behavior; use the narrower frontend or UI skill.
+- React, Svelte, Astro, Tauri, Flutter, or another framework owns the changed component boundary.
+- The task is only a dependency upgrade across many packages; use dependency and freshness skills
+  first, then this skill for Vue-specific code and compatibility surfaces.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Package and toolchain evidence: nearest `package.json`, lockfile, package manager, `engines`,
+  Vite config, Nuxt config, Vue plugin config, TypeScript config, `vue-tsc` setup, test config,
+  and CI signals.
+- Effective support range: installed `vue`, `@vue/compiler-sfc`, `@vitejs/plugin-vue`, `nuxt`,
+  `pinia`, `vue-router`, `vue-tsc`, TypeScript, Vite, and Node versions or declared ranges.
+- Component contract evidence: props, emits, `v-model` names and modifiers, slots, fallthrough
+  attributes, template refs, public component methods, provide/inject values, and accessibility
+  IDs.
+- Reactivity evidence: large reactive data, deep watchers, computed return identity, raw/proxy
+  mixing, shallow APIs, `markRaw`, `toRaw`, `customRef`, watcher cleanup, flush timing, and async
+  watcher dependencies.
+- SSR and hydration evidence: Nuxt or Vue SSR entrypoints, server/client data source, browser-only
+  APIs, third-party imports, random/time/locale output, Teleport target, custom directives,
+  ClientOnly usage, lazy hydration strategy, and critical interaction path.
+- State and routing evidence: Pinia store ownership, `storeToRefs`, store composition, use outside
+  components, route object watches, route params/query ownership, route lazy loading, and form or
+  URL state.
+- Configured verification intents for lint, build, tests, docs, package, and mustflow checks.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Determine whether the project is Vue-only, Nuxt, a component library, a plugin, or a reusable
+  package before changing component, SSR, or package surfaces.
+- Determine the supported Vue and Nuxt ranges before using Vue 3.5+ or Nuxt 4.x features such as
+  reactive props destructure, lazy hydration strategies, `useId`, `data-allow-mismatch`,
+  `useTemplateRef`, `onWatcherCleanup`, or Nuxt delayed hydration props.
+- Refresh official Vue, Nuxt, Vite, Pinia, and Vue Router docs before embedding exact "latest",
+  Node-version, migration, beta, or compatibility claims. Do not treat this skill as a live version
+  source.
+- Treat user-provided Vue notes, blog posts, AI output, and issue comments as evidence, not
+  authority.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Make focused Vue source, test, package metadata, docs, template, and configuration edits directly
+  required by the requested change.
+- Add or update tests when they protect changed component APIs, reactivity behavior, watcher
+  cleanup, store ownership, routing, SSR, hydration, lazy hydration, or package compatibility.
+- Keep older-compatible code paths when a package or app still supports Vue versions before a
+  feature was introduced.
+- Do not migrate Vue to Nuxt, disable SSR, add ClientOnly wrappers, add global stores, enable
+  component auto-import changes, or switch router/store/toolchain majors unless the task and
+  repository contract explicitly support that change.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. **Classify the Vue surface.**
+   - Identify whether the patch touches app code, Nuxt route/layout code, a component library,
+     composables, Pinia stores, Vue Router, Vite/tooling, SSR/hydration, docs, tests, or package
+     metadata.
+   - For libraries, treat props, emits, slots, `v-model`, exposed methods, CSS side effects, and
+     peer ranges as public contracts.
+2. **Check version and toolchain boundaries.**
+   - Read `vue`, `@vue/compiler-sfc`, `nuxt`, `pinia`, `vue-router`, `vite`, `vue-tsc`,
+     TypeScript, and Node constraints before using current APIs or writing compatibility text.
+   - Do not assume Vite type-checks Vue SFCs. Look for a configured `vue-tsc --noEmit` or
+     equivalent typecheck surface, and report the missing intent when absent.
+   - Keep Vue ecosystem upgrades grouped when compatibility is involved: Vue, compiler-sfc,
+     Vite plugin, Nuxt, Pinia, Router, vue-tsc, TypeScript, and Node engines can constrain each
+     other.
+3. **Review reactivity by subscription width.**
+   - Avoid wrapping large API responses, large tables, log arrays, permission trees, or deeply
+     nested JSON in deep `reactive()` unless the UI needs deep mutation tracking.
+   - Use `shallowRef` or `shallowReactive` only as a root-state boundary, and update by root
+     replacement. Do not bury shallow state inside deep reactive trees.
+   - Do not stringify, spread, or debug-print huge reactive objects in render or computed paths;
+     that makes the effect subscribe to too much.
+   - Keep raw and proxy identities from mixing in `Set`, `Map`, selected rows, memo caches, and
+     equality checks. Prefer stable ids over object references.
+4. **Review computed, watch, and watchEffect contracts.**
+   - Keep computed getters pure. Do not perform API calls, DOM writes, analytics, or state
+     mutations inside computed getters.
+   - Treat computed output as derived read-only state. Mutate the source state, not the computed
+     result.
+   - Avoid returning fresh objects or arrays from computed values when downstream stability matters;
+     compare with the previous value when Vue version support allows old-value reuse.
+   - Do not watch large reactive objects directly unless deep behavior is intentional and bounded.
+     Prefer getter sources for the exact primitive, id, length, param, or selector that matters.
+   - Avoid `deep: true` as a default. Vue 3.5+ supports numeric deep traversal, but the better
+     fix is often a narrower getter or `watchEffect` that reads only used fields.
+   - In async `watchEffect`, read dependencies before the first `await`. Later reads are not
+     dependency-tracked.
+   - Add cleanup for watcher fetches, timers, subscriptions, and observers. Use `onWatcherCleanup`
+     only in the synchronous part of Vue 3.5+ watchers, or use the callback `onCleanup` argument.
+   - Use `flush: 'post'` only when the watcher must read owner DOM after Vue updates it; avoid
+     `flush: 'sync'` for high-churn sources such as arrays.
+5. **Review component API contracts.**
+   - Keep props as one-way inputs. Do not mutate nested object or array props from children unless
+     the component is explicitly a tightly coupled compound component.
+   - Separate controlled and uncontrolled behavior. Use `modelValue` or named `v-model` for
+     live parent ownership, `defaultValue` or `initialValue` for one-time initialization, and a
+     `resetKey` or explicit action for reset semantics.
+   - For Vue 3.5+ reactive props destructure, same-block reads are reactive, but passing a
+     destructured prop to `watch` or a composable needs a getter such as `() => foo` or input
+     normalization with `toValue`.
+   - Avoid mixing boolean props with string modes. Keep booleans for true/false state and string
+     unions for variants or modes.
+   - Treat `defineModel({ default })` as a possible parent-child desynchronization risk. Prefer
+     required models or parent-owned initialization for form components.
+   - Declare public emits. Undeclared listeners can fall through to DOM roots and cause duplicate
+     or misplaced native event handling.
+   - Prefer object event payloads for public component events so future fields can be added without
+     positional argument churn.
+   - Treat `$attrs` as public API routing, not a dumping ground. With wrappers, bind attrs and
+     listeners to the actual interactive element.
+   - Treat slot names and slot props as public APIs. Keep `#default`, named slots, and scoped slot
+     data explicit.
+6. **Review render and list performance.**
+   - Keep child props stable. Do not pass a changing global value such as `activeId` to every row
+     when each child only needs a boolean such as `active`.
+   - Use stable primitive keys, not indexes or objects, for reorderable lists.
+   - Do not combine `v-if` and `v-for` on the same element. Move filtering to computed output or
+     gate the parent container.
+   - Copy before sorting or reversing arrays in computed values. Do not mutate source arrays while
+     deriving render output.
+   - Large lists need pagination, virtualization, route-level splitting, or a documented hard cap.
+   - Avoid renderless or provider component stacks inside thousands of list rows when a composable
+     or plain helper can own the reusable logic.
+7. **Review composables and provide/inject.**
+   - Design composable inputs to accept plain values, refs, and getters when the use case calls
+     for all three. Normalize with `toValue` inside a tracked effect when dependency tracking is
+     required.
+   - Return refs or `toRefs`-compatible shapes when callers are expected to destructure the result.
+   - For provide/inject, prefer readonly state plus explicit mutation functions when descendants
+     should not mutate shared state directly.
+   - Use template refs and component refs as escape hatches. Prefer props/emits first, and expose
+     only intentional public methods with `defineExpose`.
+8. **Review Pinia and router ownership.**
+   - Use `storeToRefs()` for reactive state/getter destructuring; actions may be destructured.
+   - Keep page-local UI state out of Pinia unless it must survive navigation or be shared across
+     independent surfaces.
+   - Do not create mutually recursive setup stores that read each other's state during setup.
+     Move cross-store reads into computed values or actions.
+   - When using stores outside components, verify Pinia is installed before `useStore()` runs.
+     In SSR, pass or use the request's active Pinia instance instead of a shared singleton.
+   - Watch specific route params, query fields, or names rather than the entire route object.
+   - Use route lazy loading for route components when initial bundle size matters, and verify the
+     router major and typed-route integration before changing route tooling.
+9. **Review SSR and hydration determinism.**
+   - Treat SSR as the same app running on server and client. First-render output must be
+     deterministic across both sides.
+   - Do not store request-specific state in module-scope singletons, exported reactive objects, or
+     global stores during SSR. Create app, router, store, and request context per request.
+   - Move browser-only APIs, DOM libraries, timers, observers, sockets, analytics, maps, editors,
+     and chart initialization behind client-safe lifecycle or dynamic import boundaries.
+   - Do not let `Math.random()`, `Date.now()`, timezone, locale, viewport, localStorage, auth
+     fallback, or A/B bucket values alter SSR-visible first markup unless the value is serialized
+     or intentionally client-only.
+   - Check invalid HTML nesting before blaming hydration. Browser parsers can rewrite SSR HTML
+     before Vue hydrates it.
+   - Use `useId` for SSR-stable form and accessibility IDs when the supported Vue version allows it.
+   - Use `data-allow-mismatch` only for narrowly intentional mismatches such as unavoidable dates,
+     not as a blanket hydration-warning silencer.
+   - For SSR Teleport, use a dedicated target and ensure teleported markup is injected or delayed
+     intentionally. Avoid targeting `body` casually.
+   - For custom directives that affect SSR-visible attributes, provide an SSR path instead of
+     relying only on client DOM hooks.
+10. **Review Nuxt client-only and lazy hydration boundaries.**
+    - Do not use `<ClientOnly>` as a default mismatch fix. It removes default slot content from
+      server rendering and can affect first HTML, CSS, SEO, LCP, and layout.
+    - Distinguish lazy code loading from lazy hydration. Nuxt `Lazy` component prefixes delay code
+      loading; hydration strategies decide when existing SSR HTML becomes interactive.
+    - Avoid delayed hydration for above-the-fold controls, forms, navigation, search, login,
+      checkout, add-to-cart, or any component users may interact with immediately.
+    - For delayed hydration, pick one strategy per component and check Nuxt constraints: SFC usage,
+      explicit template props, no broad prop spread, and no direct `#components` import path when
+      the strategy depends on auto-imported lazy components.
+    - Treat prop changes and shared `v-model` as hydration triggers. Do not put shared model state
+      on many lazy-hydrated components without measuring the cascade.
+    - Do not use `hydrate-never` on interactive components.
+11. **Keep public and package surfaces synchronized.**
+    - If component APIs, router behavior, store contracts, SSR behavior, hydration behavior,
+      package metadata, or toolchain ranges change, synchronize docs, tests, examples, and template
+      metadata.
+    - Avoid exact latest-version wording unless official sources were refreshed in the current
+      task. Prefer support-range wording such as "Vue 3.5+" or "Nuxt 4.x" only when the project
+      actually supports that range.
+12. **Verify through the repository contract.**
+    - Run the smallest configured checks that cover Vue code, TypeScript/SFC type checks, build
+      output, tests, docs, and release-sensitive template output.
+    - Report missing browser, hydration, SSR, Nuxt, Pinia, Router, vue-tsc, performance profiling,
+      or package-consumer verification when those surfaces changed.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Effective Vue, Nuxt, Pinia, Router, Vite, TypeScript, vue-tsc, and Node compatibility are known
+  or explicitly reported as unknown.
+- Reactivity, computed, watcher, component API, composable, store, router, SSR, hydration, and lazy
+  hydration boundaries follow the supported version's model.
+- Large data, wide subscriptions, unstable computed identity, raw/proxy mixing, prop mutation,
+  broad route watches, stale watcher responses, and ClientOnly misuse are fixed or reported.
+- SSR-visible output is deterministic, intentionally client-only, or narrowly marked as an
+  intentional mismatch.
+- Performance claims have profiler, benchmark, render-count, bundle, or configured evidence, or
+  are reported as static risk.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Report missing Vue SFC typecheck, browser, hydration, SSR, Nuxt route, Pinia store, Router,
+performance, or package-consumer verification when those surfaces changed.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If version evidence conflicts, do not assume the newest Vue or Nuxt API is available. Preserve
+  the older-compatible path or report the compatibility decision.
+- If a reactivity fix makes code faster by dropping required updates, restore the correct owner
+  boundary and report the performance tradeoff.
+- If a watcher or route fetch can race, keep the stale-response scenario visible and add cleanup,
+  cancellation, request identity, or query-key ownership.
+- If hydration fails, fix deterministic markup, SSR data, browser-only imports, invalid HTML, or
+  request-local state before adding ClientOnly or `data-allow-mismatch`.
+- If a Nuxt lazy-hydration change breaks first interaction, remove the delay for that component or
+  report the product tradeoff.
+- If configured verification is missing, report the missing intent instead of inventing raw
+  package-manager, dev-server, browser, or watcher commands.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Vue surface and supported version checked
+- Toolchain, SFC typecheck, reactivity, computed, watcher, component API, composable, Pinia,
+  Router, SSR, hydration, lazy-hydration, and performance notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Vue, Nuxt, hydration, toolchain, or verification risk