mustflow 2.22.17 → 2.22.47

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

@@ -0,0 +1,156 @@
+---
+mustflow_doc: skill.go-code-change
+locale: en
+canonical: true
+revision: 2
+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.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.go-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Go Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Go package, module, API, error, context, concurrency, 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.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only reads Go files and makes no edit.
+- A generated file is the only affected file and must be regenerated by a declared project command instead of edited manually.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- `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.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- 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.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep interfaces small and preferably owned by the consuming side.
+- Return concrete provider types from provider packages unless the package intentionally hides multiple implementations as its public API.
+- Keep domain and use-case packages free of SQL, HTTP transport, queue, cloud SDK, ORM, and vendor persistence types unless those types are the explicit public API.
+- 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.
+
+<!-- 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:
+   - 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;
+   - shrink an interface to the methods the immediate consumer calls;
+   - 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:
+   - 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:
+   - 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;
+   - 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:
+   - 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;
+   - blocking sends, receives, waits, retry loops, worker loops, and external calls must observe cancellation or be proven non-blocking.
+9. 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.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Package ownership and exported API impact are clear.
+- Context, goroutine, channel, and error ownership are explicit.
+- Tests cover the changed behavior without sleeps as synchronization.
+- Module drift is reported when dependency verification cannot run.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+For concurrency-sensitive changes, report whether a configured race or equivalent verification intent exists.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If an import cycle appears, revisit package boundaries instead of adding a workaround package.
+- If a new package becomes a shared bucket, move behavior back to the owning package or name the concrete capability.
+- If a provider-side interface appears only for mocking, delete it or move a minimal interface to the consumer.
+- If tests need sleeps for concurrency, prefer deterministic synchronization or report the gap.
+- If a goroutine has no owner, stop condition, wait path, cancellation path, or error path, do not add it.
+- 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.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Package and API impact
+- Context/concurrency/error notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Go risk

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

@@ -0,0 +1,117 @@
+---
+mustflow_doc: skill.hono-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: hono-code-change
+description: Apply this skill when Hono apps, routes, middleware, validators, RPC clients, bindings, context variables, auth boundaries, or runtime adapters are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.hono-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# Hono Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve Hono runtime, middleware, validation, context binding, auth, typed route, and response contract boundaries.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `new Hono`, `app.get`, `app.post`, `app.use`, `c.env`, `c.get`, `c.set`, validators, RPC clients, middleware, adapters, or Hono route tests change.
+- The task touches Cloudflare Workers, Bun, Node, edge-compatible routes, bindings, variables, auth middleware, or response schemas.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only touches framework-agnostic service code behind a Hono handler; use the relevant language or architecture skill.
+- Another HTTP framework is used instead of Hono.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Package metadata, TypeScript config, runtime adapter config, worker or server entrypoint, routes, middleware, env/binding types, schemas, client types, and tests.
+- Target runtime matrix: Cloudflare, Bun, Node, edge-compatible, or single runtime.
+- Existing response envelope and error contract.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Confirm runtime before using platform APIs.
+- Identify `Bindings` for runtime-provided values and `Variables` for request-local middleware values.
+- Identify auth, validation, and error response boundaries before adding routes.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep runtime-specific APIs isolated behind adapters or runtime-specific files.
+- Register middleware in an order that preserves logging, CORS, security headers, body limits, auth, validation, and handler behavior.
+- Trust only validated request data in handlers.
+- Keep success and failure envelopes consistent.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read app entrypoint, runtime adapter, route modules, middleware, schemas, client type exports, and tests.
+2. Map the route boundary: method, path, runtime, auth, params, query, headers, cookies, body, variables, bindings, response statuses, and content types.
+3. Do not put Node-only, Bun-only, or Cloudflare-only APIs in shared routes.
+4. Keep auth middleware above protected routes and wildcard or fallback routes after specific routes.
+5. Separate `Bindings` from `Variables`; do not store request-local state in globals.
+6. Use validator output rather than rereading unvalidated request bodies.
+7. Preserve typed route or RPC inference by keeping handler responses in the framework's typed response path.
+8. Choose configured verification intents that cover type checks, route tests, auth failure, validation failure, and runtime env mocks when available.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Runtime-specific APIs are isolated.
+- Middleware order and auth boundary are clear.
+- Request validation and response envelope are preserved.
+- Typed route or RPC contract impact 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 multi-runtime or route-level verification intents when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If runtime target is unclear, inspect adapter and deployment config before editing.
+- If a route needs a broader permission, binding, or auth change, switch to the relevant security or contract skill.
+- If typed route inference breaks, repair schema and response shape before adding more routes.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Runtime and middleware notes
+- Validation and response contract notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining Hono risk

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

@@ -0,0 +1,173 @@
+---
+mustflow_doc: skill.html-code-change
+locale: en
+canonical: true
+revision: 2
+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.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.html-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# HTML Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve semantic structure, native controls, keyboard access, focus behavior, form labeling, metadata, and browser-valid markup. Treat non-native interactive markup as suspicious by default; HTML already gives browsers, keyboards, forms, password managers, mobile input, and assistive technology a working contract.
+
+<!-- mustflow-section: use-when -->
+## 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.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- Only CSS changes and markup semantics are unchanged; use `css-code-change`.
+- The markup is generated and should be changed through a source component or template.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- 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.
+- Accessibility and validation tooling declared in the command contract.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Identify the document structure, interactive controls, form ownership, focus path, metadata source, and verification surface.
+- Prefer native HTML elements before adding ARIA or JavaScript behavior.
+- Classify every interactive element by user intent before changing markup.
+- Do not edit metadata, canonical, Open Graph, robots, hreflang, or JSON-LD from a single file in isolation.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- 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.
+- 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.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read the page shell, route layout, metadata helpers, component patterns, and tests before editing.
+2. Check document outline, landmarks, source order, and heading levels.
+3. Classify each interactive element by intent. Navigation to a URL uses an anchor with `href`. Commands, toggles, submit actions, open/close actions, destructive actions, copy actions, disclosure triggers, and modal triggers use buttons.
+4. Use native form controls for text entry, selection, checkbox, radio, and file input. Use grouped native radio or checkbox controls with fieldset and legend when the group label matters.
+5. Treat composite widgets such as tabs, action menus, comboboxes, listboxes, trees, grids, and custom selects as high-risk. Prefer native HTML or an existing audited component; otherwise implement the complete role, state, focus, and keyboard pattern.
+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.
+
+<!-- mustflow-section: form-accessibility -->
+## Form Accessibility Rules
+
+- Every user-editable native form control needs a persistent visible label, preferably an explicit label whose `for` value exactly matches the control `id`.
+- Placeholder text, title text, aria-label, icon-only labels, and visual proximity are not substitutes for visible labels unless a strong design constraint is reported and the accessible name remains clear.
+- Help text and error text must be real DOM text with stable IDs and connected through `aria-describedby` when relevant.
+- Required native controls should use native `required`; the required state must also be visible in text or an explained marker. Do not rely on color alone.
+- Use `aria-required` mainly for custom ARIA controls or deliberate compatibility needs; it does not enforce browser validation.
+- Do not set `aria-invalid` before the user has interacted with the field or attempted submission. Set it when validation has determined the field is invalid.
+- Error messages must identify what is wrong and how to fix it when the fix is known. Avoid generic text such as "Invalid" with no recovery instruction.
+- 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.
+
+<!-- mustflow-section: metadata-policy -->
+## Metadata And Structured Data Rules
+
+Before editing page metadata, identify the rendered route, canonical production URL, visible H1 or main title, visible primary entity, locale, indexing intent, and source of page facts.
+
+- Titles must match the visible primary topic, avoid repeated keyword stuffing, avoid stale boilerplate, and use the page's visible language.
+- Descriptions must summarize the actual visible page and must not fabricate claims, guarantees, prices, ratings, dates, or features.
+- Canonical URLs must be absolute production URLs for the preferred version of the same or near-duplicate content. Do not point canonical to staging, localhost, unrelated pages, wrong locale pages, redirects, 404s, noindex pages, or parameter URLs unless explicitly intended.
+- Canonical, sitemap, hreflang, internal links, and social URL metadata should not contradict each other.
+- Open Graph and Twitter or X title, description, URL, and image should come from the same source of truth as page metadata unless a campaign override is documented. Social images must be absolute, crawlable, and representative of the visible page.
+- Prefer JSON-LD for structured data. Validate JSON syntax and ensure required properties for the chosen rich result type are present when rich-result eligibility matters.
+- Robots directives such as noindex, nofollow, nosnippet, or restrictive crawl hints need explicit intent. Before removing one, check whether the page is intentionally private, duplicated, thin, internal, staged, or blocked.
+
+<!-- mustflow-section: rejection-criteria -->
+## Review Rejection Criteria
+
+Reject or revise the patch when any of these appear without strong justification and verification:
+
+- 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.
+- 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.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Markup communicates the intended structure without relying on visual styling alone.
+- Keyboard and focus behavior are preserved.
+- Forms have labels and errors connected.
+- Metadata and structured data reflect visible content.
+- Hidden content is not reachable by keyboard when it should be inactive.
+- Native controls are used unless a complete custom interaction pattern is justified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing accessibility, browser, or HTML validation intents when relevant.
+
+When configured or manual verification is available, cover keyboard-only navigation with Tab, Shift+Tab, Enter, Space, Escape, Arrow keys, Home, and End where applicable. Confirm visible focus, accessible name, role, value, state, hidden-content behavior, form errors, metadata consistency, and structured data truthfulness.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a custom control cannot meet keyboard and focus requirements, replace it with a native element or report the blocker.
+- If metadata source of truth is unclear, inspect the framework route and SEO helpers before editing.
+- If form validation timing or error ownership is unclear, keep native validation behavior and report the unresolved custom validation boundary.
+- If structured data facts cannot be traced to visible content or a trusted page data source, do not add them.
+- If accessibility verification is unavailable, report the manual keyboard and focus checks that remain.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Semantic, form, focus, and metadata notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining HTML risk

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

@@ -0,0 +1,149 @@
+---
+mustflow_doc: skill.javascript-code-change
+locale: en
+canonical: true
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: javascript-code-change
+description: Apply this skill when JavaScript source, package module format, runtime boundary, dependency usage, async Promise handling, browser or Node behavior, bundler config, or tests are created or changed.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.javascript-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - test
+    - docs_validate_fast
+    - mustflow_check
+---
+
+# JavaScript Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Preserve JavaScript module, runtime, package entry, Promise, cleanup, dependency, and test boundaries.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- `.js`, `.mjs`, `.cjs`, package scripts, package exports, bundler config, browser code, Node code, edge code, dependency usage, or JavaScript tests change.
+- The task touches `import`, `require`, `module.exports`, `exports`, `fetch`, `process`, `window`, `document`, `Buffer`, `fs`, `async`, Promise chains, or package entry metadata.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- TypeScript surfaces are changed; use `typescript-code-change`.
+- JavaScript files are generated artifacts that should be regenerated by a declared command.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- `package.json`, lockfile, engines, module `type`, package `exports`, bundler config, lint config, test config, and relevant entrypoints.
+- Target runtime: browser, Node, worker, edge, Bun, or multi-runtime boundary.
+- Runtime adapter files, source entrypoints, package docs examples, and build output layout when package entry or runtime support changes.
+- Async ownership and cleanup surface when Promises, retries, timers, event listeners, streams, abort signals, background tasks, startup, shutdown, or external I/O change.
+- Configured verification intents.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Determine module system and runtime before editing imports or globals.
+- Treat Promise and dependency changes as behavior changes unless proven otherwise.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Keep ESM and CommonJS boundaries explicit and localized.
+- Use browser APIs only in browser-safe files and Node APIs only in Node-safe files.
+- Await, return, catch, or intentionally handle every Promise.
+- Prefer existing dependencies and platform APIs over adding a new dependency.
+- Keep runtime-specific APIs behind platform adapters or runtime-specific entrypoints.
+- Keep package entry changes synchronized with declarations, docs examples, build output, and consumer smoke coverage when available.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Read package metadata, module type, exports, bundler config, lint config, entrypoints, docs examples, and tests.
+2. Declare the touched boundary: module system, runtime, package entry, browser/Node/edge/Bun split, async flow, dependency, or test-only.
+3. Classify each changed JavaScript file as shared, Node, browser, edge, Bun, or test-only before adding imports or globals.
+4. Keep shared files portable:
+   - do not import or reference `node:*`, `fs`, `process`, `Buffer`, `window`, `document`, `localStorage`, DOM-only APIs, or Node streams directly;
+   - prefer `URL`, `URLSearchParams`, `Uint8Array`, `ArrayBuffer`, `TextEncoder`, `TextDecoder`, Web `Request`/`Response`, Web Streams, and injected dependencies when those fit the existing code.
+5. Keep runtime-specific APIs isolated:
+   - Node files may use Node process, filesystem, Buffer, Node crypto, and Node streams;
+   - browser files may use DOM, window, document, local storage, browser events, and browser fetch;
+   - edge files should be treated as Web API based, not as browser DOM code and not as full Node code;
+   - Bun-specific APIs do not prove Node, browser, or edge compatibility.
+6. Do not use runtime detection as a broad escape hatch in shared code. Prefer explicit runtime entrypoints, adapters, conditional exports, or dependency injection over a file that mixes every runtime branch.
+7. Keep environment access behind existing server/client env helpers. Do not read raw server secrets from client, shared, browser, or edge code, and do not assume `process.env` exists outside Node-oriented code.
+8. Do not mix `import`/`export` with `require`/`module.exports` outside an established interop boundary.
+9. Treat package entry metadata as public contract:
+   - `type`, file extensions, `main`, `module`, `browser`, `exports`, `types`, `typesVersions`, `files`, `bin`, `sideEffects`, and `engines` affect consumers;
+   - adding `exports` can block deep imports and should be classified as public API sensitive;
+   - conditional exports must keep specific conditions before generic fallbacks;
+   - ESM and CJS branches should expose compatible documented shapes when both are supported;
+   - TypeScript declaration output and docs examples must keep pointing at existing package entry files.
+10. For package entry changes, check source entrypoints, build output layout, docs import examples, TypeScript or declaration settings, bundler config, and consumer-style tests. Report missing Node ESM, Node CJS, browser bundle, edge, Bun, or TypeScript consumer verification when those targets are claimed but no configured intent exists.
+11. Treat build targets as syntax/output compatibility, not as permission to use a runtime API. A browser or edge build target does not make Node filesystem, process, Buffer, or native APIs safe.
+12. Treat implicit globals as failures.
+13. Do not discard Promises. Every Promise-producing call must be awaited, returned, joined, or intentionally supervised by the project's detached-task pattern.
+14. Do not leave `.map(async ...)` unjoined. Join with the established Promise aggregation or bounded-concurrency helper when parallel work is intended.
+15. Do not use unbounded parallelism for large external I/O fan-out. Use the local concurrency limit pattern when the workload touches HTTP, database, filesystem, queue, AI, or other external services.
+16. Propagate cancellation when the operation can outlive a request, job, stream, retry loop, timeout, or user action. Accept and forward `AbortSignal` or the repository's established cancellation token when available.
+17. Do not implement timeout as a caller-only race that leaves the real work running. Timeout behavior must cancel or abort the underlying operation when the API supports it.
+18. Put cleanup in a deterministic path. Timers, event listeners, stream readers, Node streams, temp files, locks, transactions, subscriptions, and shutdown drains need success, failure, timeout, and cancellation cleanup coverage when touched.
+19. Do not build package exports or dependency changes without checking consumers, tests, and docs examples.
+20. Choose configured verification intents that cover lint, build, tests, package entry, runtime behavior, async rejection handling, cancellation, and cleanup when available.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Runtime and module boundaries are explicit.
+- Promise failures are not hidden.
+- Runtime-specific APIs do not leak into shared, browser, edge, or package entry code.
+- Package entry changes are synchronized with tests or reported as unverified.
+- Async cancellation and cleanup behavior is covered or reported as a remaining risk.
+- No unnecessary dependency was added.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `mustflow_check`
+
+Report missing browser, Node, edge, Bun, TypeScript-consumer, package-entry, async-cancellation, or cleanup verification intents when they are relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the module system is unclear, inspect package metadata and entrypoints before editing.
+- If runtime globals are needed in shared code, isolate them behind an adapter or report the boundary conflict.
+- If a shared file imports runtime-only APIs, split the runtime entry or adapter before adding more branches.
+- If a package entry change breaks a documented import path, restore compatibility or report the breaking-change requirement.
+- If a Promise is intentionally detached but has no rejection sink, shutdown/drain policy, or tracing context, do not detach it.
+- If cancellation or cleanup cannot be proven, add or reuse the local lifecycle pattern before weakening tests.
+- If dependency compatibility is unclear, classify the change as research or defer it.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Boundary checked
+- Runtime and module notes
+- Async and dependency notes
+- Files changed
+- Command intents run
+- Skipped checks and reasons
+- Remaining JavaScript risk