mustflow 2.84.0 → 2.99.0

package/templates/default/locales/en/.mustflow/skills/service-boundary-architecture/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.service-boundary-architecture
 locale: en
 canonical: true
-revision: 1
+revision: 2
 lifecycle: mustflow-owned
 authority: procedure
 name: service-boundary-architecture
-description: Apply this skill when service boundaries, modular-monolith boundaries, data ownership, queue/event boundaries, multi-tenant isolation, failure flow, operational recovery, or large-scale architecture split decisions are designed, reviewed, or changed.
+description: Apply this skill when service boundaries, modular-monolith boundaries, data ownership, queue/event boundaries, multi-tenant isolation, failure flow, independent deployment, operational recovery, disaster recovery, service split evidence, team ownership, cost, toil, or large-scale architecture split decisions are designed, reviewed, or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -39,6 +39,7 @@ This skill protects against the common failure mode where a system is split by n
 - A task designs, reviews, documents, or changes service boundaries, modular-monolith boundaries, bounded contexts, team ownership, API ownership, event ownership, queue ownership, or data ownership.
 - A monolith is being prepared for future split, a microservice split is proposed, or a service/module boundary is causing deploy, data, incident, or team coordination pain.
 - The task touches cross-service transactions, outbox/inbox patterns, idempotency, retries, timeouts, caches, read models, search models, shared databases, operational tools, manual correction, observability, tenancy, hot keys, or failure recovery.
+- A boundary claim needs proof from recent co-change history, independent deployability, dependency direction, database write ownership, synchronous call depth, queue backlog behavior, graceful shutdown, health probe correctness, version compatibility, restore or DR drills, least-privilege access, config blast radius, cost, toil, or team bottlenecks.
 - Architecture docs, decision records, onboarding docs, or skills need durable guidance for large-system design and operational readiness.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -57,6 +58,7 @@ This skill protects against the common failure mode where a system is split by n
 - Data ownership map: which module or service is the source of truth for each core fact, identifier, status, ledger, permission, tenant record, event, and read projection.
 - Current or proposed communication paths: direct calls, APIs, events, queues, shared databases, shared caches, batch jobs, search indexes, analytics stores, files, and admin tools.
 - Failure flows: duplicate requests, partial success, timeout, retry, consumer crash, queue backlog, dead-letter handling, external provider uncertainty, reconciliation, and manual correction.
+- Boundary proof ledger: last 3 months of PR co-change by repository, service, schema, deployment pipeline, and team; independent deploy test; dependency cycle map; table write ownership; synchronous call count; non-core dependency failure behavior; timeout and retry budget; queue oldest age; saturation curve; noisy-neighbor evidence; graceful shutdown; health probe split; old/new version compatibility; trace continuity; user-facing SLOs; local dev setup cost; ADR rationale; least-privilege access; config blast radius; restore and DR drill; cost per feature or customer; toil and approval bottlenecks.
 - Consistency expectations: strong consistency, eventual consistency, tolerated delay, stale reads, cache invalidation, read/write split, search delay, and deletion or retention rules.
 - Tenant, authorization, observability, deployment, migration, and operations requirements.
 - Configured verification intents and any existing architecture decision records or context files.
@@ -82,25 +84,32 @@ This skill protects against the common failure mode where a system is split by n
 
 1. Name the business capabilities and the facts each capability owns. For every core fact, identify exactly one source of truth and the owner responsible for correcting it.
 2. Split first by reason to change, not by noun. Keep code together when it changes together; split only when ownership, release cadence, scale, compliance, failure isolation, or team autonomy makes the boundary useful.
-3. Prefer a modular monolith with hard internal boundaries when the team is still discovering the domain. Draw future split lines early, but do not pay distributed-system costs before the boundary pressure is real.
-4. Reject shared database ownership. If another service or module needs data, choose an API, event, read projection, export, or explicitly owned query surface instead of direct table coupling.
-5. Design failure flows before the happy path. Cover partial success, duplicated requests, timeout, unknown external outcome, consumer crash, queue backlog, dead-letter handling, replay, reconciliation, and manual recovery.
-6. Require idempotency for commands that create, charge, reserve, approve, issue, grant, cancel, refund, redeem, or mutate durable state. Use stable request keys and return the previous result for duplicate keys.
-7. Treat queues as storage and backpressure, not magic. Define retry policy, exponential backoff or jitter, max attempts, retention, dead-letter ownership, consumer scaling, ordering expectations, replay safety, and loss tolerance.
-8. Every network call across the boundary needs a timeout, bounded retry policy, fallback or failure result, duplicate-safety story, and observability identifiers.
-9. Treat caches as a consistency tradeoff. Declare which stale values are acceptable, max staleness, invalidation owner, tenant and permission visibility, and whether the cache is allowed to become authority.
-10. Model authorization, tenant isolation, audit, and data visibility at the boundary. Tenant ID must travel through APIs, queues, caches, logs, files, reports, and admin tools when the system is multi-tenant.
-11. For event-driven boundaries, use past-tense fact events such as `OrderCreated` or `PaymentApproved`. Do not disguise commands as events. Include event ID, version, occurred time, publisher, subject, causation or request ID, correlation or trace ID, and compatible schema evolution rules.
-12. Separate transaction data from search, reporting, analytics, and screen-shaped read projections when their consistency, indexing, query, or retention needs diverge.
-13. Define tolerated delay with numbers. Replace vague "real-time" claims with accepted latency or freshness windows such as seconds, minutes, or batch cadence.
-14. Check hot keys and noisy neighbors. Define per-tenant, per-customer, per-room, per-campaign, or per-product limits, queue separation, worker pool separation, connection caps, and external API call caps when one key can dominate load.
-15. Keep domain rules in the owning domain layer. Do not scatter refund windows, cancellation rules, entitlement checks, inventory reservations, or admin overrides across controllers, UI, workers, and jobs.
-16. Plan migrations with expand, dual-write or compatibility, backfill, read switch, verification, and contract removal. Do not rename or remove shared fields in one deployment step.
-17. Plan deletion and retention before data is created. Identify legal retention, anonymization, log masking, backup retention, search/read-model cleanup, and audit exceptions.
-18. Make observability a product feature. Connect API, queue, worker, external provider, database, and admin operations with trace, request, correlation, causation, job, and tenant identifiers. Prefer p95, p99, error rate, queue age, backlog, dependency failure rate, and business success rate over averages.
-19. Make deployment and rollback a boundary decision. Use feature flags, canaries, partial exposure, compatibility windows, and kill switches for risky boundary changes.
-20. Provide operational tools for reality: reconcile external state, retry or quarantine failed messages, correct user/account/order state, revoke permissions, inspect provider responses, and undo manual changes with audit and approval when required.
-21. Record the decision: selected boundary, rejected alternatives, reason, assumptions, failure modes, data owner, operational owner, verification, and revisit triggers.
+3. Prove whether the proposed boundary is real.
+   - Mine recent PRs or change records when available: count repositories, services, DB schemas, deployment pipelines, and teams touched by one small requirement.
+   - Try the independent-deploy thought experiment: if one boundary cannot ship without another service version, shared library, DB migration, frontend deploy, or meeting, it is not independent yet.
+   - Draw dependency direction and cycles. Cycles usually mean the responsibility and data boundary is wrong, not merely that imports need cleaning.
+   - Count how many synchronous services and stores must succeed for one user action. If the answer is "many, or humans fix the database," the consistency boundary may be split in the wrong place.
+4. Prefer a modular monolith with hard internal boundaries when the team is still discovering the domain. Draw future split lines early, but do not pay distributed-system costs before the boundary pressure is real.
+5. Reject shared database ownership. If another service or module needs data, choose an API, event, read projection, export, or explicitly owned query surface instead of direct table coupling. Table write ownership should be explicit for every core fact.
+6. Design failure flows before the happy path. Cover partial success, duplicated requests, timeout, unknown external outcome, consumer crash, queue backlog, dead-letter handling, replay, reconciliation, and manual recovery.
+7. Require idempotency for commands that create, charge, reserve, approve, issue, grant, cancel, refund, redeem, or mutate durable state. Use stable request keys and return the previous result for duplicate keys.
+8. Treat queues as storage and backpressure, not magic. Define retry policy, exponential backoff or jitter, max attempts, retention, dead-letter ownership, consumer scaling, ordering expectations, replay safety, loss tolerance, oldest-message age, and catch-up rate.
+9. Every network call across the boundary needs a timeout, bounded retry policy, fallback or failure result, duplicate-safety story, observability identifiers, and a request-level budget so retries do not multiply across layers.
+10. Treat caches as a consistency tradeoff. Declare which stale values are acceptable, max staleness, invalidation owner, tenant and permission visibility, and whether the cache is allowed to become authority.
+11. Model authorization, tenant isolation, audit, and data visibility at the boundary. Tenant ID must travel through APIs, queues, caches, logs, files, reports, and admin tools when the system is multi-tenant. Service accounts should have only the DB, queue, storage, and API permissions the boundary needs.
+12. For event-driven boundaries, use past-tense fact events such as `OrderCreated` or `PaymentApproved`. Do not disguise commands as events. Include event ID, version, occurred time, publisher, subject, causation or request ID, correlation or trace ID, and compatible schema evolution rules.
+13. Separate transaction data from search, reporting, analytics, and screen-shaped read projections when their consistency, indexing, query, or retention needs diverge.
+14. Define tolerated delay with numbers. Replace vague "real-time" claims with accepted latency or freshness windows such as seconds, minutes, or batch cadence.
+15. Check hot keys and noisy neighbors. Define per-tenant, per-customer, per-room, per-campaign, or per-product limits, queue separation, worker pool separation, connection caps, and external API call caps when one key can dominate load.
+16. Check saturation and graceful degradation. Drive load past normal capacity in a bounded test plan when available, and identify the first bottleneck: worker pool, DB pool, locks, thread pool, queue, disk, external quota, or cache stampede.
+17. Keep domain rules in the owning domain layer. Do not scatter refund windows, cancellation rules, entitlement checks, inventory reservations, or admin overrides across controllers, UI, workers, and jobs.
+18. Plan migrations with expand, dual-write or compatibility, backfill, read switch, verification, and contract removal. Do not rename or remove shared fields in one deployment step. Old and new versions should tolerate unknown fields, missing fields, old messages, and new schema during rollout.
+19. Plan deletion and retention before data is created. Identify legal retention, anonymization, log masking, backup retention, search/read-model cleanup, and audit exceptions.
+20. Make observability a product feature. Connect API, queue, worker, external provider, database, and admin operations with trace, request, correlation, causation, job, and tenant identifiers. Prefer p95, p99, error rate, queue age, backlog, dependency failure rate, and business success rate over averages.
+21. Make deployment, rollback, shutdown, and health checks boundary decisions. Use feature flags, canaries, partial exposure, compatibility windows, kill switches, readiness/liveness/startup separation, graceful drain, and rollback-forward plans for risky boundary changes.
+22. Provide operational tools for reality: reconcile external state, retry or quarantine failed messages, correct user/account/order state, revoke permissions, inspect provider responses, and undo manual changes with audit and approval when required.
+23. Prove recovery, cost, and toil. A backup is not a boundary guarantee until it is restored in a clean environment. DR, config rollback, secret or certificate recovery, per-feature cost, repeated manual work, and single-team or single-person approval bottlenecks should be measured or reported.
+24. Record the decision: selected boundary, rejected alternatives, reason, assumptions, failure modes, data owner, operational owner, verification, cost, toil, and revisit triggers.
 
 <!-- mustflow-section: review-rejection-criteria -->
 ## Review Rejection Criteria
@@ -110,6 +119,9 @@ Reject or revise the design when:
 - A service or module boundary has no named data owner.
 - Two owners write the same core fact without a conflict rule.
 - A service reads another service's tables or cache as normal behavior.
+- A small requirement routinely changes many repositories, services, schemas, pipelines, or teams.
+- A service cannot be deployed, rolled back, or tested without synchronized changes in another boundary.
+- Dependency graphs contain cycles with no explicit ownership decision.
 - The design shows only the happy path.
 - Retries lack timeout, backoff, jitter, max attempts, idempotency, or failure ownership.
 - A queue has no dead-letter, retention, replay, ordering, or backlog policy.
@@ -117,6 +129,8 @@ Reject or revise the design when:
 - Events are imperative commands instead of past-tense facts.
 - Event schemas lack version, event ID, occurred time, publisher, and correlation or causation identifiers.
 - Tenant, permission, audit, or data-retention boundaries are added after the fact.
+- Health checks only prove process liveness, graceful shutdown is untested, or old and new versions cannot run together.
+- Backup, restore, DR, least privilege, config rollback, cost, or toil claims have no proof path.
 - Architecture choice is justified by tooling fashion instead of ownership, failure, scale, compliance, or team autonomy.
 - Manual operations can mutate critical state without audit, approval, and reversal or reconciliation path.
 
@@ -126,7 +140,7 @@ Reject or revise the design when:
 - Data ownership and source-of-truth boundaries are explicit.
 - Boundary split is justified by change reason, ownership, scale, compliance, failure isolation, or team autonomy.
 - Failure handling, idempotency, retry, queue, cache, event, and observability contracts are defined or explicitly deferred.
-- Tenant, authorization, deletion, retention, migration, deployment, and operational recovery risks are checked or reported.
+- Tenant, authorization, deletion, retention, migration, deployment, graceful shutdown, health checks, version compatibility, restore, DR, cost, toil, and operational recovery risks are checked or reported.
 - Decision records explain why this boundary was chosen, what alternatives were rejected, and when to revisit.
 
 <!-- mustflow-section: verification -->
@@ -160,7 +174,7 @@ Use broader configured checks when the boundary change affects templates, public
 - Boundary checked
 - Data owners and source-of-truth notes
 - Failure, idempotency, queue, cache, and event notes
-- Tenant, auth, retention, observability, deployment, and operations notes
+- Co-change, independent deploy, dependency, data ownership, sync-call, saturation, noisy-neighbor, tenant, auth, retention, observability, deployment, health, shutdown, version compatibility, restore, DR, cost, toil, and operations notes
 - Files changed
 - Command intents run
 - Skipped checks and reasons

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

@@ -0,0 +1,323 @@
+---
+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.
+   - When the command contract exposes `test_related_profile`, run it before policy changes that
+     depend on local verification timing. Then read the retained evidence with
+     `mf script-pack run test/performance-report summarize --json` before changing scheduling,
+     caching, timeout, worker, fixture, or selected-test behavior.
+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.
+
+When a profiling intent has run, prefer the read-only `test/performance-report` script-pack as the
+first report surface. Its `next_actions` field should guide whether the next safe step is collecting
+profile evidence, resolving previous failures, inspecting slow intents or phases, reviewing timeout
+pressure, or investigating selected-test fallback behavior.
+
+<!-- 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: 6
 lifecycle: mustflow-owned
 authority: procedure
 name: typescript-code-change
@@ -91,19 +91,26 @@ 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. For `tsconfig` updates, make defaults explicit when they affect emitted shape, ambient types, or module semantics. Check `rootDir`, `include`, `exclude`, `types`, `lib`, `target`, `module`, `moduleResolution`, `verbatimModuleSyntax`, `noUncheckedSideEffectImports`, declaration output, and framework wrapper defaults together instead of relying on a compiler-major default.
+19. Treat `types` as an ambient-global allowlist. Add only the runtime or test environment globals the project actually uses, such as Node, Bun, DOM, Vitest, Jest, or Playwright. Do not restore broad ambient discovery just to hide missing imports or environment drift.
+20. Use import attributes, subpath imports, and deferred module evaluation only when the runtime, bundler, and compiler track all support the exact syntax. `import defer` is a side-effect and startup-order choice, not a generic lazy-loading trick; use it only for namespace imports whose module evaluation can safely wait until first export access.
+21. Use `using` or `await using` only when the target runtime or transform path supports explicit resource management and the object really owns a disposable resource. Do not replace visible `try/finally`, context-manager, or framework cleanup contracts with `using` if the surrounding lifecycle, error propagation, or generated JS cannot be verified.
+22. 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.
+23. 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.
+24. 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.
+25. 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.
+26. 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.
+27. 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.
+28. 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.
+29. 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
@@ -151,6 +158,7 @@ Reject or revise the patch when any of these appear without explicit evidence an
 - Validator schemas and exported types are duplicated without a single source of truth.
 - Generated declarations expose source-only aliases, internal module paths, workspace-only packages, or accidental barrel exports.
 - Package entry metadata changes without checking runtime entry, type entry, declaration output, and supported resolver modes.
+- `tsconfig` defaults, ambient `types`, import attributes, `import defer`, or explicit resource management syntax are adopted without runtime, bundler, compiler-track, and generated-output evidence.
 - `skipLibCheck` or weakened strictness is used as release validation for a library/package.
 - TypeScript 6-to-7 migration warnings are silenced instead of classified and either fixed or reported.
 - TS7 RC or nightly output differences are accepted as harmless without classification.