mustflow 2.84.0 → 2.85.4

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.javascript-code-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: javascript-code-change
@@ -84,23 +84,25 @@ Preserve JavaScript module, runtime, package entry, Promise, cleanup, dependency
 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:
+9. For new Node-owned application, server, or private CLI JavaScript, prefer ESM-only with package `"type": "module"` and ordinary `.js` files when the supported runtime allows it. Use `.mjs` and `.cjs` as explicit override markers for mixed or exceptional files, not as a blanket naming convention.
+10. In native Node ESM, write relative and absolute imports with the runtime file extension and explicit directory entry file, such as `./server.js` or `./routes/index.js`. Extensionless imports and automatic directory `index.js` lookup are CommonJS or bundler habits unless a declared loader or bundler owns them.
+11. 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.
+12. 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.
+13. 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.
+14. Treat implicit globals as failures.
+15. Do not discard Promises. Every Promise-producing call must be awaited, returned, joined, or intentionally supervised by the project's detached-task pattern.
+16. Do not leave `.map(async ...)` unjoined. Join with the established Promise aggregation or bounded-concurrency helper when parallel work is intended.
+17. 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.
+18. 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.
+19. 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.
+20. 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.
+21. Do not build package exports or dependency changes without checking consumers, tests, and docs examples.
+22. 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

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.node-code-change
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: node-code-change
@@ -85,19 +85,21 @@ Preserve the actual Node.js runtime, module, package manager, TypeScript executi
    - Yarn PnP, Zero-Install, and immutable installs can make `node_modules` assumptions wrong.
    - Corepack availability depends on the Node/runtime environment; do not assume it exists in every Node version, image, or CI runner.
 5. Determine Node module loading from Node rules, not preference or `tsconfig` alone. `.mjs` and `.mts` are ESM, `.cjs` and `.cts` are CommonJS, and `.js` or `.ts` follows the nearest package `type` after the project's loader/build path is considered.
-6. Treat `type`, `main`, `exports`, `imports`, file extensions, and conditional export changes as package entry contract changes. Adding `exports` can block deep imports and should be classified as compatibility-sensitive unless all previously supported paths remain exported or the release is intentionally breaking.
-7. For conditional exports, keep condition order deliberate, include a `default` fallback when multi-runtime or bundler consumers are intended, and avoid splitting `import` and `require` into separate stateful implementations unless dual package hazards are tested.
-8. For `imports`, use `#` aliases only for package-internal paths, and keep TypeScript paths, bundler aliases, test runner aliases, and declaration output aligned.
-9. For JSON imports, `require(esm)`, top-level await, `.mts`, `.cts`, `.d.mts`, and `.d.cts`, verify the minimum Node version, TypeScript module resolution, generated output, and consumer path before changing code.
-10. Do not replace an existing TypeScript pipeline with native Node TypeScript execution unless the task explicitly asks for that migration. Node native TypeScript execution is limited type stripping; it does not typecheck, read `tsconfig`, resolve path aliases, emit declarations, downlevel syntax, transform decorators or enums, or support TSX as a full build pipeline.
-11. If native Node TypeScript execution is intentionally used, keep syntax erasable-only, use `import type` for type-only imports, avoid runtime TypeScript features that require transforms, and keep the configured typecheck/build pipeline for application and library code.
-12. Detect the actual test runner from scripts, config files, dependencies, and CI. Do not migrate Jest, Vitest, Playwright, or another runner to `node:test` just because Node has a built-in runner. Watch, coverage, mock, snapshot, worker, and cleanup behavior are runner-specific.
-13. Treat watch mode and snapshot update modes as development or review actions, not final verification. Use the configured oneshot intents and report when no configured runner-specific intent exists.
-14. Before using Node APIs in deployment code, classify the target as Node server, Docker, serverless Node, edge runtime, static build, or multi-runtime package. Edge runtimes are not full Node.js runtimes.
-15. Inspect native and install-sensitive dependencies when package metadata or runtime imports touch `.node`, `binding.gyp`, `node-gyp`, `preinstall`, `install`, `postinstall`, `prepare`, optional dependencies, peer dependencies, OS, CPU, libc, or Node ABI boundaries.
-16. Treat optional dependencies and optional peers as absent until code handles absence. Do not require optional packages directly without fallback or error handling that matches the existing project pattern.
-17. Treat the Node permission model as a trusted-code seatbelt, not a sandbox for untrusted code. If permission flags are introduced or changed, map required filesystem, network, child process, worker, native addon, WASI, inspector, and temporary directory access explicitly.
-18. Choose configured verification intents that cover lint, build, tests, package metadata, release-sensitive package output, docs examples, and mustflow contract checks when available. Report missing consumer fixture, ESM, CJS, TypeScript consumer, native dependency, deployment, or permission verification.
+6. For new Node applications, servers, and private CLIs, prefer an explicit ESM-only package with `"type": "module"` and ordinary `.js` source/output files when the supported runtime allows it. Do not rename every file to `.mjs` just to mean ESM; reserve `.mjs` and `.cjs` for exceptional per-file overrides or mixed-module boundaries.
+7. In native Node ESM code, require fully specified relative and absolute import specifiers, including file extensions and directory indexes such as `./feature/index.js`. Do not carry CommonJS extensionless or directory-main assumptions into Node ESM unless a bundler or loader owns that resolution.
+8. Treat `type`, `main`, `exports`, `imports`, file extensions, and conditional export changes as package entry contract changes. Adding `exports` can block deep imports and should be classified as compatibility-sensitive unless all previously supported paths remain exported or the release is intentionally breaking.
+9. For conditional exports, keep condition order deliberate, include a `default` fallback when multi-runtime or bundler consumers are intended, and avoid splitting `import` and `require` into separate stateful implementations unless dual package hazards are tested.
+10. For `imports`, use `#` aliases only for package-internal paths, and keep TypeScript paths, bundler aliases, test runner aliases, and declaration output aligned.
+11. For JSON imports, `require(esm)`, top-level await, `.mts`, `.cts`, `.d.mts`, and `.d.cts`, verify the minimum Node version, TypeScript module resolution, generated output, and consumer path before changing code.
+12. Do not replace an existing TypeScript pipeline with native Node TypeScript execution unless the task explicitly asks for that migration. Node native TypeScript execution is limited type stripping; it does not typecheck, read `tsconfig`, resolve path aliases, emit declarations, downlevel syntax, transform decorators or enums, or support TSX as a full build pipeline.
+13. If native Node TypeScript execution is intentionally used, keep syntax erasable-only, use `import type` for type-only imports, avoid runtime TypeScript features that require transforms, and keep the configured typecheck/build pipeline for application and library code.
+14. Detect the actual test runner from scripts, config files, dependencies, and CI. Do not migrate Jest, Vitest, Playwright, or another runner to `node:test` just because Node has a built-in runner. Watch, coverage, mock, snapshot, worker, and cleanup behavior are runner-specific.
+15. Treat watch mode and snapshot update modes as development or review actions, not final verification. Use the configured oneshot intents and report when no configured runner-specific intent exists.
+16. Before using Node APIs in deployment code, classify the target as Node server, Docker, serverless Node, edge runtime, static build, or multi-runtime package. Edge runtimes are not full Node.js runtimes.
+17. Inspect native and install-sensitive dependencies when package metadata or runtime imports touch `.node`, `binding.gyp`, `node-gyp`, `preinstall`, `install`, `postinstall`, `prepare`, optional dependencies, peer dependencies, OS, CPU, libc, or Node ABI boundaries.
+18. Treat optional dependencies and optional peers as absent until code handles absence. Do not require optional packages directly without fallback or error handling that matches the existing project pattern.
+19. Treat the Node permission model as a trusted-code seatbelt, not a sandbox for untrusted code. If permission flags are introduced or changed, map required filesystem, network, child process, worker, native addon, WASI, inspector, and temporary directory access explicitly.
+20. Choose configured verification intents that cover lint, build, tests, package metadata, release-sensitive package output, docs examples, and mustflow contract checks when available. Report missing consumer fixture, ESM, CJS, TypeScript consumer, native dependency, deployment, or permission verification.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions

package/templates/default/locales/en/.mustflow/skills/routes.toml

@@ -406,7 +406,7 @@ applies_to_reasons = ["code_change", "public_api_change", "test_change", "packag
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change", "package_metadata_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "migration_change", "security_change", "package_metadata_change", "release_risk"]
 
 [routes."docker-code-change"]
 category = "general_code"
@@ -418,7 +418,7 @@ applies_to_reasons = ["code_change", "public_api_change", "test_change", "securi
 category = "general_code"
 route_type = "primary"
 priority = 82
-applies_to_reasons = ["code_change", "public_api_change", "docs_change", "test_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "docs_change", "test_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change"]
 
 [routes."backend-reliability-change"]
 category = "general_code"
@@ -436,7 +436,7 @@ applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "pe
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change", "package_metadata_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "ui_change", "package_metadata_change"]
 
 [routes."javascript-code-change"]
 category = "general_code"
@@ -652,13 +652,13 @@ applies_to_reasons = ["code_change", "security_change", "migration_change"]
 category = "data_external"
 route_type = "primary"
 priority = 55
-applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "cross_cutting_code_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "cross_cutting_code_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "package_metadata_change"]
 
 [routes."tauri-code-change"]
 category = "data_external"
 route_type = "primary"
 priority = 90
-applies_to_reasons = ["code_change", "security_change", "public_api_change"]
+applies_to_reasons = ["code_change", "behavior_change", "ui_change", "security_change", "privacy_change", "data_change", "public_api_change", "package_metadata_change", "release_risk"]
 
 [routes."process-execution-safety"]
 category = "data_external"
@@ -696,6 +696,12 @@ route_type = "adjunct"
 priority = 40
 applies_to_reasons = ["test_change", "behavior_change"]
 
+[routes."test-suite-performance-review"]
+category = "tests"
+route_type = "primary"
+priority = 58
+applies_to_reasons = ["performance_change", "test_change", "workflow_change", "mustflow_config_change", "package_metadata_change", "unknown_change"]
+
 [routes."test-maintenance"]
 category = "tests"
 route_type = "primary"
@@ -880,13 +886,13 @@ applies_to_reasons = ["ui_change", "docs_change", "code_change"]
 category = "ui_assets"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["ui_change", "docs_change", "code_change"]
+applies_to_reasons = ["ui_change", "docs_change", "code_change", "behavior_change", "public_api_change", "migration_change", "package_metadata_change"]
 
 [routes."unocss-code-change"]
 category = "ui_assets"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["ui_change", "docs_change", "code_change"]
+applies_to_reasons = ["ui_change", "docs_change", "code_change", "behavior_change", "migration_change", "performance_change", "package_metadata_change"]
 
 [routes."flutter-code-change"]
 category = "ui_assets"
@@ -898,13 +904,13 @@ applies_to_reasons = ["ui_change", "code_change", "public_api_change"]
 category = "ui_assets"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["ui_change", "docs_change", "code_change"]
+applies_to_reasons = ["ui_change", "docs_change", "code_change", "behavior_change", "migration_change", "package_metadata_change"]
 
 [routes."svelte-code-change"]
 category = "ui_assets"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["ui_change", "code_change", "public_api_change"]
+applies_to_reasons = ["ui_change", "code_change", "behavior_change", "public_api_change", "data_change", "security_change", "privacy_change", "test_change", "package_metadata_change"]
 
 [routes."pattern-scout"]
 category = "architecture_patterns"

package/templates/default/locales/en/.mustflow/skills/security-privacy-review/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.security-privacy-review
 locale: en
 canonical: true
-revision: 22
+revision: 23
 lifecycle: mustflow-owned
 authority: procedure
 name: security-privacy-review
@@ -193,9 +193,11 @@ Catch security, privacy, and disclosure risks introduced by ordinary code, docum
 32. For filesystem changes, distinguish lexical containment from the real target. Check symlinks, generated state, package contents, and file APIs that may follow links before claiming a path stays inside the repository.
 33. For code-scanning alerts, group findings by root cause and rule. Fix the underlying pattern, not only the exact flagged line, and separate repository-setting alerts such as branch protection or maintainer activity from code changes.
     - For incomplete escaping or encoding findings, search the same sink class for adjacent ad hoc sanitizer patterns such as first-occurrence `.replace`, non-global replacement, hand-escaped slashes, quotes, backslashes, path separators, or mixed URL encoders. Replace the pattern with a domain-owned transformation and add a regression test or narrow source-pattern guard when the behavior is release-sensitive.
+    - For ReDoS or inefficient-regular-expression findings, identify whether attacker-controlled text, repository files, generated output, logs, Markdown, YAML, or source code can reach the expression. Prefer a bounded parser, token scanner, structured parser, or anchored non-overlapping expression over nested quantifiers, repeated alternatives that can match the same prefix, or optional whitespace loops. Add a long malformed input case or equivalent static guard before claiming the backtracking risk is fixed.
 34. For workflow scanner alerts, check action pinning, `persist-credentials`, job-level permissions, reusable workflow permissions, fork pull-request secret exposure, artifact upload boundaries, and privileged identity timing before treating the warning as cosmetic.
 35. For pinned action references, distinguish tag objects from the commit that implements the tag. Verify pinned SHAs against the action repository so scanner tooling does not report an imposter or non-member commit.
 36. For dependency scanner alerts, separate production dependency manifests from fixtures, examples, generated test repositories, and intentionally vulnerable samples. Narrow the scan scope before treating fixture-only alerts as product vulnerabilities.
+    - For lockfile CVEs, inspect the manifest and lockfile together. Identify the direct parent that keeps the vulnerable transitive package in the graph, update the narrowest direct dependency or override needed to reach the fixed range, and confirm the vulnerable package version no longer appears in the resolved graph before claiming the alert is fixed.
 37. For deployment settings, check debug mode, sample admin accounts, default credentials, public admin panels, open metrics endpoints, public storage, root container users, HTTPS enforcement, and exposed GraphQL or development consoles.
 38. For runtime and framework security updates, check that supported versions are documented, end-of-life versions are rejected, dependency locks exist where appropriate, security patches can be tested and deployed quickly, and rollback or redeploy can happen without manual dashboard memory. Do not treat a fashionable or high-performance runtime as safe unless the patch path is operationally credible.
 39. For transport security, check HTTPS/TLS requirements, certificate validation, insecure HTTP downgrade paths, disabled verification flags, and whether sensitive traffic can bypass the secure channel.

package/templates/default/locales/en/.mustflow/skills/test-suite-performance-review/SKILL.md

@@ -0,0 +1,314 @@
+---
+mustflow_doc: skill.test-suite-performance-review
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: test-suite-performance-review
+description: Apply this skill when test-suite runtime, CI feedback latency, test selection, shard balance, worker scheduling, retry policy, flaky-test handling, fixture setup, database or container test lifecycle, coverage or artifact overhead, test-result caching, test discovery, or test performance claims are planned, edited, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.test-suite-performance-review
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - build
+    - test_related
+    - test
+    - test_audit
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Test Suite Performance Review
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Make test suites faster without turning the default verification path into wishful thinking.
+
+The review question is not "can the suite run in parallel?" It is "where is the wall-clock time
+actually spent, which tests are safe to skip or run later, which workers are waiting, which shared
+resources are saturated, and what evidence keeps a faster path trustworthy?"
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Test or CI runtime, developer-loop feedback time, shard balance, worker count, test discovery,
+  coverage collection, trace or artifact generation, retry policy, flaky-test handling, or test
+  result caching is created, changed, reviewed, or reported.
+- A task changes command contracts, CI workflows, test runner configuration, test grouping, test
+  selection, test scheduling, package scripts, fixture setup, database setup, container lifecycle,
+  browser test behavior, or coverage and report defaults for performance reasons.
+- A report claims tests are faster, optimized, selected, cached, parallelized, sharded, hermetic,
+  stable, less flaky, or safer to run on every PR.
+- A test suite is slow because of repeated process startup, full-directory discovery, repeated
+  migration or seed work, per-test containers, sleeps, external internet calls, huge artifacts,
+  tail shards, or over-broad full-suite execution.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task only adds or updates behavior tests; use `test-design-guard` or `test-maintenance`.
+- The task only reviews whether production code is testable; use `testability-boundary-review`.
+- The task is ordinary application hot-path performance with no test runner, fixture, CI, or
+  verification-loop behavior; use `performance-budget-check`.
+- The user only wants a one-time local command result and no persistent test or CI behavior changes.
+- The proposed change weakens verification by deleting tests, skipping failed tests, removing
+  assertions, disabling coverage gates, or hiding flaky tests without an evidence-based policy.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Suite surface: local command, CI job, package script, test runner, shard system, coverage job,
+  browser test job, database-backed test job, or release gate.
+- Timing ledger: discovery, process startup, shared setup, fixture creation, test body, database or
+  container setup, cleanup, coverage, report generation, artifact upload, queue wait, shard tail,
+  and idle-worker time when available.
+- Test timing evidence: p50 and p95 per test or file, longest tests, previous failures, flaky
+  history, shard start and finish times, worker utilization, retry count, and timeout outliers.
+- Selection ledger: changed files, dependency graph, runtime coverage or touched-file evidence,
+  newly added tests, previous failed tests, unsafe-change fallback rules, and scheduled full-suite
+  safety net.
+- Isolation ledger: time, randomness, UUIDs, locale, timezone, environment variables, home
+  directory, filesystem paths, network, database, containers, queues, browser profiles, caches,
+  module state, and runner process reuse.
+- Resource ledger: CPU, memory, DB connections, browser processes, containers, network, filesystem,
+  GPU, SQLite or PostgreSQL locks, port allocation, and any scarce resource that needs a token or
+  affinity rule.
+- Cache ledger: declared inputs, cache keys, volatile values, hit rate, miss reasons, runner-local
+  cache, remote cache, result-cache eligibility, and invalidation behavior.
+- Relevant command-intent entries for tests, builds, docs, release checks, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the
+  current scope.
+- Required inputs are available, or missing timing, selection, cache, isolation, or resource
+  evidence can be reported without guessing.
+- If a change touches production behavior or test coverage meaning, use the matching behavior,
+  test-design, security, data, or release skill before accepting the performance change.
+- If test result caching or selected-test execution is introduced, the full-suite fallback and
+  scheduled full-suite safety net are defined first.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or refine test timing collection, historical duration stores, selected-test manifests,
+  dependency-to-test maps, runner scheduling, shard assignment, worker limits, retry classification,
+  fixture lifecycle, local stubs, fake timers, cache keys, coverage defaults, and CI report policy.
+- Add or adjust tests, fixtures, docs, command contracts, release checks, and template surfaces
+  directly tied to the test-suite performance behavior.
+- Move expensive setup from per-test to per-worker, per-module, or per-session scope only when
+  mutable state still has a cheap isolation layer.
+- Do not remove tests, weaken assertions, disable failure artifacts, or mark flaky tests as normal
+  success to make a suite look faster.
+- Do not add unbounded parallelism, shared database schemas, cross-test mutable fixtures, or result
+  caches when hidden inputs are not declared.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Measure before optimizing.
+   - Split elapsed time into discovery, process startup, shared setup, fixture creation, test body,
+     database or container setup, cleanup, coverage, report generation, artifact upload, queue wait,
+     shard tail, and idle-worker time.
+   - Report p50 and p95 per test or file when available. Average-only timing hides the last slow
+     shard, and the last slow shard decides CI wall time.
+2. Classify the bottleneck.
+   - Discovery bottleneck: full tree scans, broad classpath scans, fixtures and generated files in
+     search paths, or missing precomputed test manifests.
+   - Startup bottleneck: one process, JVM, Python, Node, browser, container, or dependency-injection
+     graph per test instead of a safe persistent worker.
+   - Fixture bottleneck: repeated migrations, seed data, model loads, browser profile setup, or
+     container creation.
+   - Scheduling bottleneck: file-count sharding, no historical duration data, no work stealing,
+     huge test files, or worker count beyond the resource optimum.
+   - Artifact bottleneck: coverage, screenshots, videos, traces, full logs, HTML reports, or upload
+     work paid on every PR path instead of only failure, retry, nightly, or release paths.
+3. Replace blanket full-suite execution with selected execution only when fallback is explicit.
+   - Include affected tests from changed files, new tests, and previous failed tests.
+   - Fall back to the full suite for changes to lockfiles, compiler or runtime settings, test runner
+     configuration, shared fixtures, migrations, database schema, generated contracts, package
+     metadata that affects runtime, or any change the selector cannot understand.
+   - Keep a scheduled full-suite path for nightly, release, or pre-merge confidence.
+4. Do not build impact analysis from imports alone.
+   - Combine static dependency evidence with previous runtime evidence such as touched files,
+     classes, schemas, config keys, fixtures, resources, and test-to-source mappings.
+   - Prefer file or class granularity when method-level tracing costs more than it saves.
+   - Treat dynamic imports, reflection, generated code, config-driven branches, and framework magic
+     as reasons to widen selection or fall back.
+5. Run likely failures early.
+   - Order previous failed tests, recently changed tests, tests near the changed code, historically
+     flaky tests, and long tests before low-risk tests.
+   - Use early-fail jobs for fast developer feedback, but keep a separate full-data job that
+     continues collecting remaining failures when the workflow needs all failures.
+6. Cache only hermetic test results.
+   - A successful test result can be reused only when the test binary, test code, affected product
+     code, fixtures, environment, toolchain, locale, timezone, and declared resources match.
+   - Do not include volatile values such as commit SHA, build number, wall-clock time, random temp
+     roots, or runner-specific paths in cache keys unless they truly affect output.
+   - Do include language version, compiler flags, runtime flags, timezone, locale, dependency lock
+     content, fixture versions, and DB schema version when they affect behavior.
+   - Track cache hit rate and miss reasons after adding a cache; a cache with invisible misses is
+     performance theater.
+7. Preserve warm local and remote caches.
+   - Avoid clearing dependency caches, transformed source caches, test discovery indexes, compiled
+     output, and package caches at the start of every CI job.
+   - Prefer runner-local SSD caches or content-hash restore over slow network-volume scans.
+8. Avoid full discovery on every run.
+   - Generate or maintain package-level test manifests when the project can do so safely.
+   - Exclude fixtures, snapshots, generated output, archived tests, vendored code, and build output
+     from discovery paths.
+   - For JVM and similar ecosystems, prefer explicit include patterns over broad classpath scanning
+     when the runner supports it.
+9. Reuse workers before increasing worker count.
+   - Keep interpreters, JIT, dependency injection, ASTs, browser engines, and database clients warm
+     across multiple tests when isolation allows it.
+   - Reset static state, module caches, timers, environment, and global fixtures between tests.
+   - Replace workers only after measured memory leaks, not by default after every test.
+10. Size work units for the scheduler.
+    - Do not send thousands of tiny remote jobs where queue setup, sandbox setup, input transfer,
+      and result collection cost more than the test body.
+    - Bundle micro-tests by package, runtime, or fixture affinity while preserving per-test result
+      reporting.
+11. Shard by historical duration, not file count.
+    - Use recent successful durations, trimmed means, or exponential moving averages.
+    - Assign longest tests first to the currently lightest shard.
+    - Give new tests a directory or type median, and cap timeout outliers so one historic failure
+      does not poison future placement.
+12. Add work stealing when static shards still leave idle workers.
+    - Let early workers take not-yet-started work from overloaded shards.
+    - Keep tests that share expensive setup together unless the tail cost is worse than duplicated
+      setup.
+13. Split huge files below the file level when supported.
+    - File-level sharding is fake parallelism when one file contains most of the runtime.
+    - Confirm that the runner actually honors case-level sharding; unsupported sharding can cause
+      every shard to run the whole suite.
+14. Schedule by resource tokens and affinity.
+    - Tag tests by CPU, memory, DB connections, browser processes, containers, GPU, filesystem, and
+      network pressure.
+    - Use resource tokens or locks for scarce shared resources instead of disabling all parallelism.
+    - Keep expensive fixture groups together when setup reuse beats perfect load balance.
+15. Tune worker count empirically.
+    - Compare worker counts such as 1, 2, 4, and 8 on the same commit.
+    - Stop increasing workers when wall time stops improving, memory peaks rise sharply, DB waits
+      increase, browser tests swap, or flaky rate rises.
+16. Make database and container setup worker-scoped.
+    - Prefer one DB server or service container per worker, with per-test schemas, databases,
+      transactions, savepoints, namespaces, ports, or fixture copies.
+    - Do not let all workers share the same mutable schema unless the suite is intentionally
+      serialized.
+    - Build a migrated and seeded template DB or snapshot once, then clone it per worker when
+      migrations or seed data dominate.
+17. Reset mutable state cheaply.
+    - Prefer transaction rollback or savepoints for tests whose side effects stay inside one DB
+      connection.
+    - Use DB clone, schema clone, or container snapshot for tests that cross processes, queues,
+      external workers, sequence assertions, or asynchronous effects.
+    - Use tmpfs only for non-persistent state with explicit size limits.
+18. Replace sleeps with readiness and fake time.
+    - Treat fixed sleeps as performance bugs.
+    - Wait for real readiness: health endpoints, logs, successful queries, event receipt, or port
+      plus protocol-level checks.
+    - For timers, retries, expiry, and scheduled work, inject clocks or use fake timers instead of
+      waiting in real time.
+19. Remove external internet from the default CI path.
+    - Use local stubs, fixtures, mocks, recorded responses, or contract-specific jobs.
+    - Block unrelated images, fonts, analytics, and third-party requests in UI tests unless the test
+      is specifically about that delivery behavior.
+20. Control hidden inputs.
+    - Inject time, random seeds, UUID generation, locale, timezone, environment, and current user.
+    - Report seed values on failure so a failed run can be reproduced.
+21. Move expensive evidence off the default path.
+    - Collect full coverage, videos, traces, screenshots, full logs, and HTML reports only where
+      they pay for themselves: failures, first retry, nightly, release, or dedicated coverage jobs.
+    - Merge shard reports after tests finish rather than blocking each shard on heavy reporting.
+22. Retry narrowly and honestly.
+    - Retry only the failed test or case, once, in a fresh worker when possible.
+    - Preserve first-failure logs and artifacts.
+    - Classify retry success as flaky success, not normal success.
+23. Use speculative tail duplication only for hermetic shards.
+    - If the last shard exceeds its historical p95 while workers are idle, a scheduler may duplicate
+      that shard and accept the first result.
+    - Do not duplicate non-hermetic tests, tests with side effects, or tests that consume scarce
+      external resources.
+24. Garbage-collect the test portfolio.
+    - Track duration, unique behavior coverage, defect-finding history, flaky rate, owner, and last
+      meaningful update.
+    - Move low-value duplicates from PR paths to nightly paths before deleting them.
+    - Quarantine flaky tests with owner and expiry; do not let quarantine become permanent silence.
+25. Verify the faster path and the fallback path.
+    - A selector, cache, shard rule, retry policy, or fixture reuse change is not complete until the
+      default fast path and the fallback or full path both have evidence or a reported missing
+      command intent.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The test-suite bottleneck is classified by timing, selection, scheduling, cache, fixture, DB,
+  container, artifact, retry, or resource evidence.
+- The optimization goal is explicit: faster first failure, shorter PR wall time, lower CI cost,
+  lower flaky rate, smaller artifact overhead, or faster local feedback.
+- Selected-test execution has a full-suite fallback for unsafe or unknown changes.
+- Caches declare inputs, omit irrelevant volatile values, and report hit rate or miss reasons when
+  evidence exists.
+- Worker count, resource tokens, shard placement, fixture affinity, and retry behavior preserve
+  test isolation and failure evidence.
+- Any speed claim is measured, complexity-only, or explicitly unverified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `build`
+- `test_related`
+- `test`
+- `test_audit`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrowest configured test, build, docs, release, or mustflow intent that proves the changed
+test-suite behavior. If the repository exposes a profiling or cached-test intent, use it only when
+the command contract marks it configured, oneshot, and agent-allowed.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If timing evidence is missing, add bounded measurement or report the missing evidence before
+  changing scheduling, caching, or selection policy.
+- If selection cannot understand a change, fall back to the full suite.
+- If a cache key is uncertain, prefer a cache miss over a false hit.
+- If worker reuse causes order dependence, leaked state, or flaky failures, isolate the leaked
+  resource before widening reuse.
+- If parallelism makes tests slower, check shared DB, browser, memory, filesystem, and container
+  contention before increasing workers again.
+- If a retry hides a real failure, preserve first-failure evidence and classify the result as flaky.
+- If configured verification is missing, report the missing intent instead of inventing raw runner
+  commands.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Suite surface and feedback goal
+- Timing breakdown and bottleneck class
+- Selection policy and full-suite fallback
+- Scheduling, sharding, worker, and resource-token decisions
+- Fixture, DB, container, filesystem, time, randomness, network, and isolation notes
+- Cache key, hit-rate, and miss-reason notes
+- Retry and flaky-test policy
+- Coverage, trace, log, screenshot, video, report, and artifact policy
+- Speed evidence: measured, complexity-only, or unverified
+- Command intents run
+- Skipped command intents and reasons
+- Remaining test-suite performance risk

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

@@ -2,7 +2,7 @@
 mustflow_doc: skill.typescript-code-change
 locale: en
 canonical: true
-revision: 4
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: typescript-code-change
@@ -91,19 +91,22 @@ Preserve TypeScript's type, runtime validation, module, build, and public API bo
 11. For type tests, prefer `@ts-expect-error` with a short reason. Do not use `@ts-ignore` in implementation code. Implementation `@ts-expect-error` needs an owner, removal condition, and risk report.
 12. If a public API changes, trace every consumer-visible import specifier, runtime export, type export, declaration output, docs example, type-only export, overload, generic default, interface field, enum or literal member, class member, and package entry condition.
 13. Treat `exports`, `types`, `typings`, `typesVersions`, package `type`, file extensions, path aliases, declaration import paths, and barrel exports as public API surfaces. Adding or tightening `exports` can break existing deep imports.
-14. If ESM/CJS behavior changes, verify package `type`, `main`, `module`, `browser`, `exports`, condition order, extension rules, generated JS, and generated declaration files together.
-15. Inspect generated declarations when package surfaces change. Declaration files must not leak source-only aliases, private paths, workspace-only package names, unpublished internal paths, or accidental public re-exports.
-16. For TypeScript 6 migration work, treat deprecation warnings as future TypeScript 7 removal risk. `ignoreDeprecations` is a temporary compatibility valve, not proof that the project is ready for 7.0. Prefer removing deprecated options and updating resolver or module choices to match the project runtime.
-17. Treat TypeScript 6 `--stableTypeOrdering` as a migration comparison tool for declaration and error-order differences, not as a permanent performance-neutral default. If it changes errors or declaration output, look for inference or declaration-stability issues instead of snapshotting noise.
-18. For TypeScript 7 migration work, keep the tracks separate:
+14. For TypeScript that emits code for native Node ESM, prefer `.ts` source plus package `"type": "module"` and `module`/`moduleResolution` set to `NodeNext` or the repository's fixed Node mode. Do not rename every source file to `.mts` just to mean ESM; reserve `.mts` and `.cts` for explicit per-file module overrides or mixed-package boundaries.
+15. In TypeScript source that targets native Node ESM, write relative imports using the emitted runtime specifier, usually `.js`, such as `import { createApp } from "./app.js"` from `app.ts`. Do not write extensionless relative imports or `.ts` runtime specifiers unless a declared loader, bundler, or runtime explicitly owns that behavior.
+16. Use `moduleResolution: "Bundler"` only when a bundler such as Vite, esbuild, Rollup, or a framework build system owns final module resolution. Do not use bundler resolution to model code that Node will execute directly without that bundler.
+17. If ESM/CJS behavior changes, verify package `type`, `main`, `module`, `browser`, `exports`, condition order, extension rules, generated JS, and generated declaration files together.
+18. Inspect generated declarations when package surfaces change. Declaration files must not leak source-only aliases, private paths, workspace-only package names, unpublished internal paths, or accidental public re-exports.
+19. For TypeScript 6 migration work, treat deprecation warnings as future TypeScript 7 removal risk. `ignoreDeprecations` is a temporary compatibility valve, not proof that the project is ready for 7.0. Prefer removing deprecated options and updating resolver or module choices to match the project runtime.
+20. Treat TypeScript 6 `--stableTypeOrdering` as a migration comparison tool for declaration and error-order differences, not as a permanent performance-neutral default. If it changes errors or declaration output, look for inference or declaration-stability issues instead of snapshotting noise.
+21. For TypeScript 7 migration work, keep the tracks separate:
    - TS6 stable API track: `@typescript/typescript6` and `tsc6` for compiler API, transformer, ESLint, framework wrapper, and peer-dependency compatibility.
    - TS7 RC compiler track: `typescript@rc` and `tsc` for RC compiler verification.
    - TS7 nightly track: `@typescript/native-preview` and `tsgo` for nightly diagnostics only.
    - Future TS7 stable track: stable `typescript` once upstream publishes TypeScript 7 on the normal stable path.
-19. Keep compiler API consumers, language-service plugins, custom transformers, and framework typecheck wrappers on the TS6 API track until their owners explicitly support the TS7 API surface. Treat TS7 RC `tsc` as compiler verification, not proof that JavaScript compiler API consumers can migrate.
-20. When comparing TS6 `tsc6`, TS7 RC `tsc`, and optional TS7 nightly `tsgo`, classify differences before editing code: real type error, declaration emit order or printback noise, unsupported option, unsupported API, watch or incremental behavior gap, language-service gap, generated-output drift, or framework wrapper mismatch.
-21. Do not treat faster TS7 RC or nightly results as sufficient verification. Keep the repository's existing `tsc`, `tsc6`, or framework typecheck as the compatibility baseline until repository policy explicitly adopts a different compiler track.
-22. Choose the narrowest configured verification intents that cover typecheck, lint, tests, build output, declarations, package contract risk, and downstream-style consumer risk.
+22. Keep compiler API consumers, language-service plugins, custom transformers, and framework typecheck wrappers on the TS6 API track until their owners explicitly support the TS7 API surface. Treat TS7 RC `tsc` as compiler verification, not proof that JavaScript compiler API consumers can migrate.
+23. When comparing TS6 `tsc6`, TS7 RC `tsc`, and optional TS7 nightly `tsgo`, classify differences before editing code: real type error, declaration emit order or printback noise, unsupported option, unsupported API, watch or incremental behavior gap, language-service gap, generated-output drift, or framework wrapper mismatch.
+24. Do not treat faster TS7 RC or nightly results as sufficient verification. Keep the repository's existing `tsc`, `tsc6`, or framework typecheck as the compatibility baseline until repository policy explicitly adopts a different compiler track.
+25. Choose the narrowest configured verification intents that cover typecheck, lint, tests, build output, declarations, package contract risk, and downstream-style consumer risk.
 
 <!-- mustflow-section: assertion-policy -->
 ## Assertion Policy