mustflow 2.103.21 → 2.103.31

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

@@ -0,0 +1,219 @@
+---
+mustflow_doc: skill.axum-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: axum-code-change
+description: Apply this skill when Axum routers, handlers, extractors, state, extensions, middleware, Tower or Tower-HTTP layers, CORS, cookies, headers, WebSockets, body limits, rejections, error responses, Tokio tasks or locks, SQLx pools, Rust HTTP API tests, or Axum version migrations are created, changed, reviewed, or upgraded.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.axum-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Axum Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Axum's router, extractor, response, state, middleware, Tower, Tokio runtime, SQLx pool, HTTP security, and API error-contract boundaries while making focused Rust web-server changes.
+
+Axum work is not "ordinary Rust plus routes". Rust prevents many memory errors, but it does not prevent CORS-as-auth mistakes, body stream double reads, request-local state leaks, Tower layer ordering bugs, service errors that close connections, unbounded spawned work, lock contention, or database pool starvation.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `Router`, `route`, `nest`, `merge`, `fallback`, `method_not_allowed_fallback`, `route_layer`, `Router::layer`, `with_state`, handler functions, extractors, middleware, response types, rejection handling, or Axum route tests change.
+- The task touches `State`, `Extension`, `FromRef`, `FromRequestParts`, `FromRequest`, `Json`, `Path`, `Query`, `Form`, `Bytes`, `String`, `Request`, `TypedHeader`, cookies, CORS, CSRF, auth, session, tenant, request id, tracing, body limits, WebSocket, or SSE behavior.
+- Tower or Tower-HTTP layers are added or changed, including `ServiceBuilder`, `TraceLayer`, request id propagation, timeout, CORS, compression, decompression, body limit, sensitive headers, concurrency limit, buffer, load shed, or custom `Service`/`Layer` implementations.
+- Tokio tasks, locks, channels, `spawn`, `spawn_blocking`, semaphores, bounded queues, SQLx pools, transactions, or connection acquisition behavior affect Axum request paths.
+- Axum, axum-extra, tower, tower-http, tokio, SQLx, Hyper, or HTTP crate versions are upgraded or migration guidance is applied.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- Rust service code behind handlers changes with no Axum route, extractor, response, middleware, or runtime request-path effect; use `rust-code-change` or the relevant architecture/data skill.
+- The project uses Hono, Elysia, Express, Fastify, Actix, Rocket, or another web framework instead of Axum.
+- The task only updates external version prose; use source-freshness or dependency guidance unless the Axum procedure itself changes.
+- Generated Rust route files should be regenerated by a declared command rather than edited.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Cargo manifests, lockfile policy, feature flags, toolchain and MSRV evidence, Axum-related crate versions, runtime target, server entrypoint, router modules, handlers, middleware, extractors, state types, error types, response envelope, and tests.
+- Current official or repository-local source evidence before preserving exact "latest", release-date, or migration claims. Distinguish docs.rs for the crate version in use from GitHub `main` or unreleased branches.
+- Route ledger: method, path, nesting, fallback, layer scope, auth boundary, params, query, headers, cookies, body type, response statuses, content types, rejection behavior, CORS, cache, timeout, tracing, and public client contract.
+- Runtime ledger: Tokio executor assumptions, blocking or CPU-heavy work, spawned tasks, locks, channels, pool sizes, DB limits, external calls, connection or transaction lifetime, request cancellation, shutdown, and observability.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Read Cargo metadata and affected router, handler, extractor, middleware, state, error, and test files before editing.
+- Identify the Axum crate version and target migration range before applying version-specific guidance. Do not mix docs.rs for one version with GitHub `main` examples from another track.
+- Apply `rust-code-change` alongside this skill when ownership, MSRV, feature flags, unsafe, FFI, public crate API, or Cargo workspace behavior changes.
+- Apply security, API contract, database, or performance skills when the Axum change also changes auth, public API semantics, migrations, persistence, queueing, or measured performance claims.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep handlers thin around validated request data, typed state, explicit response envelopes, and framework-free service logic.
+- Keep app-wide resources in `State`, request-derived values in request extensions, and substate extraction through intentional `FromRef`.
+- Keep CORS, cookies, CSRF, headers, body limits, auth, tracing, timeouts, and error envelopes as explicit route or layer policy.
+- Use Tower layers only with a clear order, scope, error conversion, backpressure, body, and tracing contract.
+- Keep SQLx pool, HTTP client, and other cheap-clone handles as handles. Do not wrap them in broad `Arc<Mutex<_>>` merely to share them.
+- Keep version-specific guidance behind a version gate and omit durable exact version claims unless refreshed from official sources.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read Cargo metadata, Axum-related crate versions, server entrypoint, router composition, state types, extractors, middleware stack, error and response types, SQLx pool setup, Tokio task boundaries, and tests.
+2. Apply the Version Gate:
+   - identify current `axum`, `axum-extra`, `tower`, `tower-http`, `tokio`, `sqlx`, Hyper, and HTTP crate versions from project manifests or lockfiles;
+   - use official docs for the version actually in use before applying migration or release-specific behavior;
+   - treat docs.rs `latest`, GitHub `main`, blog posts, and pasted release notes as different evidence tracks until reconciled;
+   - for Axum 0.8 projects, check route capture syntax such as `/{id}` and `/{*rest}`, custom extractor signatures without stale `async_trait` assumptions, stricter optional extractor behavior, and any MSRV or handler `Sync` requirements that the project version declares;
+   - do not use `without_v07_checks()` as a migration bypass. If it appears, require a reason that literal colon or asterisk paths are intended.
+3. Build a route ledger from router composition:
+   - methods and paths, static versus dynamic route precedence, wildcard placement, nested prefixes, original URI needs, fallback versus method-not-allowed behavior, route grouping, route tests, and public URL changes;
+   - layer scope and timing: `Router::layer` and `route_layer` apply to already registered routes, and URI rewrite or path normalization must happen before routing when needed.
+4. Review handler contracts:
+   - keep handler inputs within Axum's extractor rules and the project response envelope;
+   - prefer concrete API results such as `Result<Json<T>, AppError>` or project equivalents when success and failure shapes matter;
+   - avoid raw `StatusCode`, string errors, or leaked `anyhow` details as public error responses;
+   - remember that handler `Err` values are usually response values, while Tower service errors must be converted to responses.
+5. Review extractors and request body ownership:
+   - extractors run left to right;
+   - body-consuming extractors such as `Json`, `Bytes`, `String`, `Form`, multipart, raw `Request`, or custom `FromRequest` extractors must be last and unique;
+   - auth, tenant, request id, and header/cookie-only extractors should use `FromRequestParts` unless they truly need the body;
+   - optional extractors must distinguish missing, malformed, expired, unauthorized, and forbidden states instead of turning security failures into anonymous access;
+   - if extractor rejections need a project JSON envelope, use `Result<Extractor, Rejection>` locally or a custom extractor rather than assuming a handler-level error catches them.
+6. Review state and extensions:
+   - use `State` for app-wide resources such as pools, config, clients, key sets, metrics, or service registries;
+   - use request extensions for current user, tenant, request id, trace context, or middleware-derived request-local values;
+   - avoid `Extension` for required app state because missing or mismatched extensions fail at runtime;
+   - ensure `State` clones are cheap handles such as `Arc`, pool, or client handles;
+   - use `FromRef` for intentional substate boundaries, not as a hidden service locator or a way to clone large values per request;
+   - remember that `Router<S>` means the router is still missing state `S`, not that it already owns that state.
+7. Review response and error boundaries:
+   - keep success and error content types consistent for public APIs;
+   - map internal, validation, auth, permission, not-found, conflict, rate-limit, upstream, timeout, and server-bug failures to explicit public codes;
+   - avoid tuple status overrides when inner response creation can fail unless the body has already been made infallible;
+   - convert fallible Tower middleware errors with `HandleErrorLayer` or an equivalent response mapping when the chosen layer changes service error type;
+   - distinguish `tower::timeout` error behavior from `tower_http::timeout` response behavior before swapping them.
+8. Review middleware and Tower layers:
+   - prefer `ServiceBuilder` when layer order is non-trivial;
+   - place request id creation before tracing and propagation after tracing when using Tower-HTTP request id layers;
+   - mark sensitive request headers before trace logging and sensitive response headers before they can be logged;
+   - use `from_fn_with_state` when Axum middleware needs app state;
+   - for reusable middleware, consider Tower `Layer`/`Service` contracts, including `poll_ready`, `call`, backpressure, cloning, error type, and body type;
+   - be explicit about whether CORS, compression, decompression, body limit, timeout, auth, trace, and request id layers apply globally, to a route group, or to a single route.
+9. Review CORS, cookies, headers, and browser security:
+   - do not treat CORS as authentication or authorization;
+   - reject permissive or very-permissive CORS in production unless the public unauthenticated contract justifies it;
+   - credentials plus reflected origin requires a strict allowlist and correct cache variation such as `Vary: Origin`;
+   - signed cookies are integrity-protected, not encrypted; use private cookies or opaque server-side session ids for sensitive data;
+   - cookie jar changes must be returned with the response;
+   - set `Secure`, `HttpOnly`, `SameSite`, `Path`, and `Domain` deliberately, and prefer host-only `__Host-` session cookies when appropriate;
+   - CORS and `SameSite` do not replace CSRF defenses for cookie-authenticated unsafe methods;
+   - do not log raw `Authorization`, `Cookie`, `Set-Cookie`, API keys, bearer tokens, or session ids.
+10. Review body limits, uploads, and raw body paths:
+    - decide whether limits apply to wire size, decompressed size, JSON size, multipart part size, or streaming duration;
+    - do not rely on default body limits for custom body readers, third-party extractors, uploads, webhooks, GraphQL, or streaming endpoints;
+    - for webhook signatures, decide whether raw body verification or parsed JSON is the source of truth and read the body only once;
+    - keep decompression and body limit order explicit.
+11. Review Tokio runtime and shared resources:
+    - do not hold locks, DB connections, transactions, or request-local guards across external awaits, channel waits, uploads, rendering, or slow validation;
+    - use `tokio::sync::Mutex` only when awaiting while locked is truly intended, and still keep critical sections short;
+    - remember that `RwLock` can block readers behind a queued writer;
+    - bound spawned work with a semaphore, bounded channel, worker queue, or explicit service limit;
+    - use `spawn_blocking` only for bounded blocking work and report that started blocking tasks cannot be freely aborted;
+    - move long CPU jobs, crawlers, encoders, or unbounded fan-out to workers or queues instead of request tasks.
+12. Review SQLx or pool-backed data access:
+    - create pools at application startup and share cheap cloned handles;
+    - do not wrap `Pool`, `PgPool`, `MySqlPool`, `SqlitePool`, reqwest `Client`, or similar handles in broad mutexes;
+    - size pools from DB limits, app instance count, acquire wait, slow acquire threshold, p95 query time, and saturation evidence rather than "bigger is faster";
+    - release pool connections and transactions before external HTTP, file upload, template rendering, channel waits, or long CPU work;
+    - avoid holding transactions around retryable or unbounded external side effects.
+13. Choose configured verification intents that cover type checking, build, route happy paths, auth failures, validation and rejection failures, body limit behavior, CORS/cookie/header behavior, middleware order, timeout/error mapping, pool contention, and runtime smoke paths when available.
+
+<!-- mustflow-section: rejection-criteria -->
+## Review Rejection Criteria
+
+Reject or revise a change when:
+
+- Axum 0.8 route syntax, extractor signatures, optional extractor behavior, handler requirements, or MSRV assumptions are applied without checking the project version.
+- `/:id` or `/*rest` style paths are added to an Axum 0.8 route without an explicit literal-path reason.
+- `without_v07_checks()` is used to silence migration failures rather than to allow intentional literal colon or asterisk paths.
+- Auth, tenant, request id, or header/cookie-only extractors consume the request body.
+- Multiple body-consuming extractors are used, or a body-consuming extractor is not last.
+- Missing, malformed, expired, unauthorized, and forbidden auth states are collapsed into one optional path.
+- `Extension` is used for required app-wide state that could be `State`.
+- Request-local user, tenant, session, or trace data is stored in app state or module globals.
+- `FromRef` clones large data per request or hides arbitrary global dependencies.
+- Handler errors leak internal error text, SQL, upstream details, secrets, or inconsistent content types.
+- Fallible Tower middleware errors are not converted to responses.
+- Auth layers can miss later-registered protected routes, or auth converts ordinary 404/405 behavior unintentionally.
+- CORS is treated as an access-control boundary, or credentials are allowed with reflected origins without an allowlist.
+- Cookie changes are not returned with the response, or sensitive cookie values are only signed when confidentiality is required.
+- Sensitive headers can be logged by trace or error output.
+- Body limits, decompression order, upload limits, or webhook raw-body ownership are unclear.
+- Pools or HTTP clients are wrapped in broad mutexes, locks or DB connections are held across slow awaits, or spawned work is unbounded.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Route, fallback, layer, extractor, body, state, extension, response, rejection, and middleware behavior are intentional and reported.
+- CORS, cookies, headers, CSRF, body limits, tracing, timeouts, and sensitive logging boundaries are explicit.
+- Tokio tasks, locks, blocking work, SQLx pools, transactions, and external calls preserve backpressure and resource release.
+- Version-specific guidance is either refreshed from official sources for the project version or omitted from durable claims.
+- Missing route-level, middleware, security, body-limit, rejection, pool, runtime, or load-style verification is reported.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing Axum route, rejection-envelope, CORS/cookie/header, middleware-order, timeout/error, body-limit, WebSocket, pool-contention, backpressure, load, or runtime smoke verification intents when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If handler type errors appear, inspect extractor order, body consumption, `Send` future requirements, state type, response type, and captured `!Send` values before adding clones, boxes, or broad bounds.
+- If route behavior is unclear, build or inspect the route ledger before changing handlers.
+- If auth, CORS, cookie, CSRF, or sensitive header behavior is unclear, stop that path and inspect the security boundary before broadening access.
+- If body parsing or webhook verification fails, choose one raw-body owner and one parsed-body owner instead of trying to read the body twice.
+- If Tower layer errors or timeouts fail to compile, decide whether the layer should be infallible, mapped through `HandleErrorLayer`, or replaced with a response-producing Tower-HTTP layer.
+- If pool wait, lock contention, or spawned work risk cannot be tested by configured intents, report the operational risk and the missing smoke or load coverage.
+- If official source freshness cannot be checked for a version, release, or migration claim, omit the claim from durable skill text and report it as unverified snapshot context.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Axum version, route, handler, extractor, state, and response notes
+- Middleware, Tower, CORS, cookie, header, body-limit, tracing, and timeout notes
+- Tokio, lock, task, SQLx pool, transaction, and backpressure notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Axum risk

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

@@ -0,0 +1,318 @@
+---
+mustflow_doc: skill.babylon-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: babylon-code-change
+description: Apply this skill when Babylon.js, WebGPU or WebGL engine setup, Scene lifecycle, cameras, lights, meshes, materials, textures, shaders, glTF or GLB loading, AssetContainer usage, loaders, Havok or Physics V2, LOD, instancing, thin instances, picking, render loops, Inspector debugging, or Babylon-related tests are created, changed, reviewed, or upgraded.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.babylon-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Babylon Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Babylon.js engine, Scene, render loop, asset pipeline, material, physics, lifecycle,
+memory, and large-scene performance contracts while making focused web 3D changes.
+
+Babylon work is not ordinary frontend canvas work. Many failures come from treating WebGPU as an
+automatic speed switch, leaving WebGL fallback undefined, loading every asset directly into the
+Scene, using visual meshes as physics shapes, keeping every object pickable, mutating material
+defines at runtime, or disposing meshes without owning materials, textures, observers, and render
+loops.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Babylon.js engine setup, `Engine`, `WebGPUEngine`, `EngineFactory`, canvas bootstrapping,
+  resize handling, render loops, scene creation, cameras, lights, shadows, render targets,
+  post-processes, frame graph, Inspector, Playground reproductions, or WebXR setup changes.
+- Meshes, `TransformNode`, instances, thin instances, LOD, octrees, occlusion queries, picking,
+  pointer interactions, collision, culling, large-world or geospatial rendering, Gaussian splats,
+  particles, or tile/chunk streaming change.
+- Materials, PBR/OpenPBR, clear coat, refraction, transparency, OIT, KTX2, environment maps,
+  shaders, WGSL/GLSL, material plugins, shader compilation, or material dirty behavior changes.
+- glTF/GLB import, module-level loader functions, dynamic loader registration, decoder deployment,
+  `AssetContainer`, `instantiateModelsToScene`, Draco, Meshopt, KTX2, progressive loading, skins,
+  animation retargeting, or asset pipeline docs/tests change.
+- Physics V2, Havok, rigid bodies, shapes, aggregates, motion types, pre-step, forces, impulses,
+  thin-instance physics, collision callbacks, raycasts, shape casts, or physics tests change.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change is framework-free TypeScript, JavaScript, HTML, CSS, React, Vue, Svelte, or Astro with
+  no Babylon engine, canvas, asset, rendering, physics, or 3D lifecycle boundary.
+- The task only edits static 3D assets, textures, or design prose without changing Babylon code,
+  loading behavior, rendering configuration, or package metadata.
+- Three.js, PlayCanvas, Godot, Unity, Bevy, raw WebGPU, or another renderer owns the boundary; use
+  the matching renderer, language, or asset skill instead.
+- The task only asks whether an exact Babylon release number is current; use source-freshness
+  guidance unless Babylon code or durable skill text changes too.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Package and runtime evidence: nearest package metadata, lockfile, package manager, bundler,
+  TypeScript config, target browsers/devices, framework integration, test setup, and CI signals.
+- Effective Babylon support range: installed or declared `@babylonjs/core`, loaders, serializers,
+  GUI, materials, inspector, Havok, WebGPU, WebXR, and related packages or CDN URLs.
+- Engine ledger: WebGPU/WebGL selection, async initialization, fallback policy, canvas ownership,
+  render loop owner, resize owner, context-lost policy, feature detection, and target adapters.
+- Scene ledger: Scene lifetime, cameras, render targets, lights, shadows, post-processes, active
+  mesh evaluation, render groups, observables, pointer picking, debug/Inspector hooks, and disposal
+  owner.
+- Asset ledger: glTF/GLB source, loader registration, decoder hosting, compression extensions,
+  KTX2 policy, `AssetContainer` cache, instantiation plan, skin/skeleton usage, and CDN/range
+  request behavior when progressive assets are used.
+- Performance ledger: expected object counts, draw calls, active mesh evaluation, GPU frame time,
+  render target time, shader compile time, physics time, texture memory, profiler counters, and
+  target-device evidence when performance is claimed.
+- Physics ledger: Havok initialization, body/shape/material ownership, motion types, collision
+  filtering, pre-step use, force versus impulse, callback cost, raycast result reuse, and shape
+  complexity.
+- Configured verification intents for lint, build, tests, docs, package, and mustflow checks.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Identify the Babylon package family and supported version range before using current APIs,
+  migration guidance, Frame Graph, WebGPU non compatibility mode, module-level loader functions,
+  Physics V2/Havok, or newly released rendering features.
+- Refresh official Babylon docs, release notes, typedoc, Khronos glTF specs, browser compatibility
+  tables, or package metadata before embedding exact "latest", browser-support, or release-date
+  claims. Do not treat this skill as a live version source.
+- Determine whether the project is an app, product viewer, game, editor, geospatial/digital-twin
+  viewer, library, reusable component, or asset pipeline before changing engine, loader, package,
+  or performance surfaces.
+- Apply framework-specific skills alongside this skill when React, Vue, Svelte, Astro, Nuxt,
+  routing, SSR, hydration, or component lifecycle owns the canvas mount/unmount boundary.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Make focused Babylon source, test, package metadata, docs, template, and configuration edits
+  directly required by the requested change.
+- Add or update tests when they protect engine selection, WebGPU fallback, render loop cleanup,
+  loader registration, asset ownership, disposal, physics behavior, or package compatibility.
+- Keep fallback, compatibility, and older API paths when the app or package still supports
+  browsers, devices, or Babylon versions where the newer path is unavailable.
+- Do not switch a project from WebGL to WebGPU-only, remove fallback, enable WebGPU fast paths,
+  enable expensive rendering features, replace physics backends, or move asset hosting unless the
+  task and repository contract explicitly support that change.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. **Classify the Babylon surface.**
+   - Identify whether the patch touches engine startup, framework integration, scene graph,
+     lighting, materials, shaders, asset loading, physics, interaction, performance, docs, tests,
+     package metadata, or release-sensitive templates.
+   - For reusable packages, treat engine factory options, component props, asset URLs, loader
+     expectations, peer ranges, emitted events, and cleanup behavior as public contracts.
+2. **Check version, package, and import boundaries.**
+   - Read Babylon package versions and import style before using module-level loader functions,
+     side-effect imports, WebGPU APIs, Physics V2, Inspector, GUI, serializers, or addon packages.
+   - Prefer module-level loader functions such as asset-container and scene load helpers when the
+     project already uses ESM tree-shaking. Avoid importing all loaders or legacy barrels unless
+     the package size contract allows it.
+   - Verify required side-effect imports for loaders, physics, ray picking, occlusion, inspector,
+     or scene extensions. IDE type visibility does not prove the production bundle registers the
+     runtime behavior.
+3. **Review engine setup and fallback.**
+   - Treat WebGPU initialization as asynchronous. Do not build scenes, attach resize handlers,
+     start render loops, open Inspector, initialize XR, or load assets before the selected engine is
+     ready.
+   - Preserve WebGL fallback unless project evidence proves WebGPU-only deployment is intentional.
+     Browser support tables do not guarantee the user's OS, GPU, driver, secure context, adapter,
+     or blocked-device list supports the needed features.
+   - Distinguish WebGPU compatibility mode concepts from Babylon's engine `compatibilityMode`.
+     Babylon non compatibility mode should be enabled only when material, skeleton, shadow, vertex
+     buffer, and global state are stable enough to reuse bundles.
+   - If WebGPU fast paths are used, inspect bundle creation counters and repeated material or
+     buffer dirtiness instead of assuming WebGPU is faster.
+4. **Own render loop and scene lifecycle.**
+   - Keep engine, scene, canvas, render loop, resize, observers, debug panels, and route/component
+     mount lifetimes explicit.
+   - Make render-loop registration idempotent. Avoid starting another `runRenderLoop` on every
+     framework remount, hot reload, tab reactivation, or route change.
+   - Dispose scenes, containers, observers, custom event listeners, render targets, materials,
+     textures, physics bodies, and caches according to an ownership ledger. `mesh.dispose()` alone
+     rarely proves memory cleanup.
+   - Decide whether WebGL context-loss recovery is required before changing `doNotHandleContextLost`.
+     Disabling recovery saves memory only by moving recovery responsibility to the app.
+5. **Review Scene structure by cost owner.**
+   - Use `TransformNode` for non-rendering parents, anchors, glTF roots, tile roots, rig parents,
+     and effect pivots. Do not use empty meshes as folders.
+   - Keep cameras, render targets, mirrors, minimaps, portals, thumbnails, shadows, and post-process
+     passes visible in the cost model. Another camera or render target often means drawing the scene
+     again.
+   - Keep static meshes and materials marked static only when their transforms and shader defines
+     will not change. `freezeWorldMatrix`, `material.freeze`, and `freezeActiveMeshes` are
+     contracts, not generic speed buttons.
+6. **Review lights, shadows, and post-processing.**
+   - Treat clustered lighting as a way to reduce light evaluation cost, not as permission to enable
+     unlimited real-time shadows.
+   - Limit shadow generators to lights and objects that need dynamic shadows. Keep directional
+     shadow frustums, min/max Z, ortho scale, map size, cascades, and refresh rate deliberate.
+   - Gate volumetrics, glow, SSAO, outline, dynamic IBL shadows, area lights, textured area lights,
+     splats, particles, and HTML-in-Canvas by target device and frame budget.
+7. **Review materials, textures, shaders, and transparency.**
+   - Do not use full PBR, clear coat, glass, subsurface, refraction, transparency, OIT, or expensive
+     post-processes on every object by default. Assign expensive features to hero surfaces.
+   - Treat PNG, JPG, and WebP as transfer formats, not GPU memory optimization. Use KTX2/Basis
+     policies when VRAM and texture upload are the real bottlenecks.
+   - Choose KTX2 modes by texture class. Avoid applying ETC1S blindly to normal, metallic,
+     roughness, or other non-color data where UASTC or another policy is needed.
+   - Prefer prefiltered environment textures for release builds instead of runtime HDR/EXR
+     prefilter work unless startup cost is acceptable.
+   - Avoid runtime material define churn. Use uniforms for value changes, prebuilt variants for
+     structural changes, preload shader compilation for important materials, and restore
+     `scene.blockMaterialDirtyMechanism` after batched edits.
+   - For WebGPU custom shaders, check WGSL, GLSL conversion, sampler binding, attribute lists,
+     texture array restrictions, viewport bounds, and unsupported texture formats.
+8. **Review glTF and asset loading.**
+   - Prefer `LoadAssetContainerAsync` when the code needs delayed attachment, pooling, cloning,
+     repeated instantiation, route-level ownership, or predictable cleanup.
+   - Do not treat `loadedMeshes[0]` as the first visual mesh for glTF. Account for the loader-added
+     root node before measuring bounds, assigning materials, adding collisions, or changing pivots.
+   - Treat Draco, Meshopt, KTX2, and progressive GLB as runtime contracts, not only export flags.
+     Check decoder hosting, CSP/offline constraints, workers, CPU decode time, CDN cache keys, and
+     HTTP range support.
+   - For skins and animation retargeting, check skeleton nodes, linked bone transforms, reference
+     pose, root motion, scale, socket ownership, and whether code mutates the linked transform node
+     rather than a transient bone value.
+9. **Review LOD, culling, instances, and large scenes.**
+   - Start with instrumentation: active mesh evaluation, draw calls, GPU frame time, render target
+     time, shader compile time, and physics time. Do not add LOD or occlusion blindly.
+   - Split large worlds into cells, chunks, tiles, sectors, or streaming roots with separate
+     bounding, LOD, loading, disposal, and interaction ownership.
+   - Use regular instances when per-instance object control matters. Use thin instances for large,
+     mostly static repeated objects with deliberate buffer and bounding design.
+   - Build thin-instance buffers in bulk, update only changed ranges when possible, and avoid
+     rebuilding `Float32Array` or GPU buffers every frame.
+   - Keep thin-instance roots spatially chunked. One visible instance should not keep an entire
+     forest, city, or catalog alive.
+   - Separate positive and negative determinant instance batches. Mirrored transforms can break
+     batching or rendering assumptions.
+   - Choose culling strategies per mesh class. Sphere-only, standard, and optimistic strategies
+     trade CPU precision against false-positive GPU work.
+   - Use occlusion queries only for large expensive objects where asynchronous, delayed visibility
+     decisions and rendering group ordering are acceptable.
+10. **Review picking, interaction, and per-frame allocation.**
+    - Keep only interactive meshes pickable. Disable pointer move picking when hover behavior is not
+      needed, and prefer proxy interaction layers for dense models.
+    - Avoid creating math objects, arrays, matrices, colors, raycast results, or thin-instance
+      buffers inside hot render loops. Reuse `TmpVectors`, `copyFrom`, `set`, mutable refs, and
+      preallocated arrays where the code path is per-frame.
+    - Keep pointer actions, observables, callbacks, and external event buses removable and scoped to
+      the owning scene or component.
+11. **Review Physics V2 and Havok boundaries.**
+    - Use Physics V2 concepts: body, shape, material, aggregate, constraint, and motion type are
+      separate design decisions.
+    - Initialize Havok and plugin state explicitly, including WASM/package deployment. Do not assume
+      a JavaScript import alone wires every physics extension in a tree-shaken bundle.
+    - Use simple shapes, convex hulls, or compounds for dynamic bodies. Reserve mesh shapes for
+      static terrain or static concave geometry where the triangle cost is acceptable.
+    - Reuse shapes for repeated bodies when appropriate. Do not treat `PhysicsAggregate` convenience
+      as an object-pool or native-memory strategy.
+    - Choose static, dynamic, and animated motion types by intent. Do not fight the physics engine
+      by directly transforming dynamic bodies every frame.
+    - Enable pre-step only for the bodies and frames that must sync node transforms into physics.
+    - Use impulses for instantaneous events and forces for continuous effects. Do not encode game
+      state in sleep status.
+    - Keep collision callbacks lightweight and filtered. Prefer world-level callbacks with
+      filtering when that is the cheaper design. Reuse raycast result objects and masks.
+12. **Keep public and package surfaces synchronized.**
+    - If engine selection, asset loading, material behavior, physics behavior, component props,
+      browser support, package ranges, or performance claims change, synchronize docs, examples,
+      tests, and package metadata.
+    - Avoid exact latest-version wording unless official sources were refreshed in the current task.
+      Prefer support-range wording such as "Babylon.js 9.x" only when the project actually supports
+      that range.
+13. **Verify through the repository contract.**
+    - Run the smallest configured checks that cover Babylon code, package output, docs, tests, and
+      release-sensitive template output.
+    - Report missing browser, WebGPU/WebGL, target-device, visual, physics, asset-pipeline,
+      memory-leak, WebXR, Inspector, profiler, or package-consumer verification when those surfaces
+      changed.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Effective Babylon package, browser, engine, loader, asset, and physics compatibility are known or
+  explicitly reported as unknown.
+- Engine initialization, render loop ownership, scene lifecycle, observer cleanup, disposal, and
+  context-loss behavior are intentional.
+- Asset loading, decoder hosting, compression, material, shader, LOD, culling, instancing, picking,
+  and physics choices match the target scale and device budget.
+- Performance claims have instrumentation, profiler, benchmark, target-device, frame-time, memory,
+  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 Babylon browser smoke, WebGPU/WebGL fallback, visual regression, target-device
+profiling, asset decoder, glTF/GLB loading, WebXR, physics, memory/disposal, Inspector, or package
+consumer verification when those surfaces changed.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If WebGPU behavior fails, separate async engine readiness, feature support, fallback selection,
+  shader binding, texture format, viewport bounds, bundle churn, and custom shader conversion
+  before reverting to broad renderer changes.
+- If a model loads incorrectly, inspect loader registration, root node handling, decoder hosting,
+  compression extension support, skeleton linked nodes, material slots, texture URLs, and CDN/range
+  behavior before changing unrelated scene code.
+- If frame time regresses, identify whether the bottleneck is active mesh evaluation, draw calls,
+  shader compile, material dirty, fill rate, render targets, shadows, post-processes, picking,
+  physics, or GC before adding generic optimizations.
+- If memory grows, inspect ownership of containers, meshes, materials, textures, render targets,
+  observers, event listeners, physics bodies, caches, context-lost recovery, and framework remounts.
+- If physics behavior is unstable, inspect shape complexity, motion type, pre-step, transform
+  ownership, collision filtering, callback work, and force versus impulse use.
+- If official source freshness cannot be checked for a version, browser, release, or API claim,
+  omit the claim from durable skill text and report it as unverified snapshot context.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Babylon surface and supported version checked
+- Engine, WebGPU/WebGL fallback, render loop, Scene lifecycle, disposal, context-loss, and
+  observer notes
+- Asset loading, glTF/GLB, decoder, compression, material, shader, texture, transparency, and
+  environment notes
+- LOD, culling, instancing, thin-instance, picking, large-scene, physics, Havok, and performance
+  notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Babylon, WebGPU/WebGL, asset, physics, performance, or verification risk