mustflow 2.32.0 → 2.37.1

package/templates/default/locales/en/.mustflow/skills/http-delivery-streaming/SKILL.md

@@ -0,0 +1,205 @@
+---
+mustflow_doc: skill.http-delivery-streaming
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: http-delivery-streaming
+description: Apply this skill when HTTP delivery, content coding, compression negotiation, CDN or proxy caching, streaming responses, Server-Sent Events, WebTransport, WebSocket fallback, HTTP/2 or HTTP/3 transport behavior, browser EventSource or WebTransport clients, reverse-proxy buffering, connection limits, reconnect behavior, or delivery observability is created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.http-delivery-streaming
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - lint
+    - build
+    - test_related
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# HTTP Delivery Streaming
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep HTTP delivery behavior explicit instead of treating it as a harmless header, proxy, or client-library detail. Compression, cache variation, streaming flush behavior, reconnect semantics, HTTP version behavior, and browser transport fallback are part of the user-visible and operator-visible contract.
+
+This skill is for the awkward layer where a feature looks correct in route code but fails because a proxy buffered it, a cache ignored `Vary`, a browser cannot send the header the server expects, a datagram was treated as reliable, or a compression setting made tail latency worse.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- HTTP response delivery, `Content-Encoding`, `Accept-Encoding`, `Vary`, `Cache-Control`, `ETag`, range requests, static asset precompression, CDN compression, or origin compression changes.
+- zstd, gzip, brotli, dictionary compression, compression dictionary transport, `.zst` artifacts, compressed archives, patches, or delivery metadata are introduced, reviewed, or documented.
+- Streaming responses, Server-Sent Events, `EventSource`, `text/event-stream`, heartbeat comments, reconnect behavior, event replay, `Last-Event-ID`, or proxy buffering behavior changes.
+- WebTransport, HTTP/3, QUIC, datagrams, bidirectional streams, unreliable latest-state delivery, or WebSocket/SSE/long-poll fallback changes.
+- Reverse proxy, CDN, edge worker, load balancer, framework adapter, route handler, worker handler, or browser client behavior can change whether bytes flush, cache, decompress, reconnect, or arrive in order.
+- Performance, reliability, auth, permission, privacy, or observability claims depend on bytes transferred, compression ratio, streaming latency, connection count, fallback path, reconnect rate, or transport metrics.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The change only edits an API JSON schema, route shape, status code, or generated client with no delivery, cache, compression, streaming, or transport behavior; use `api-contract-change`.
+- The change only improves general runtime performance with no HTTP delivery or streaming surface; use `performance-budget-check`.
+- The task only changes authentication or permission policy with no browser delivery, cache, cookie, CORS, signed URL, or streaming token behavior; use `auth-permission-change`.
+- The task only changes an external provider adapter unrelated to HTTP delivery or browser transport behavior; use `adapter-boundary`.
+- The user explicitly asks for a rough offline note and accepts that browser, proxy, CDN, or standards freshness is unverified.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Delivery surface: static asset, API response, file download, archive, streaming route, SSE channel, WebTransport session, WebSocket fallback, CDN rule, proxy rule, or browser client.
+- Route or asset ledger: URL, method, status, media type, response size range, cacheability, auth requirement, tenant or user variance, and caller types.
+- Header ledger: `Content-Type`, `Content-Encoding`, `Accept-Encoding`, `Vary`, `Cache-Control`, `ETag`, `Last-Event-ID`, `Retry-After`, `Content-Disposition`, CORS, cookies, credentials mode, range request headers, and compression dictionary headers when relevant.
+- Delivery path: origin, framework adapter, reverse proxy, CDN, edge worker, service worker, load balancer, HTTP version, TLS/ALPN, QUIC/UDP availability, and browser support assumptions.
+- Streaming behavior: flush point, heartbeat interval, replay buffer, reconnect policy, backpressure, cancellation, per-tenant isolation, and fallback behavior.
+- Compression behavior: selected content coding, fallback coding, window or decoder compatibility constraints, compression level, CPU budget, dictionary availability, dictionary freshness, and cache-key variance.
+- Observability evidence: selected encoding, cache status, proxy status, client fallback, reconnect count, RTT, bytes sent, queue age, replay misses, drop estimate, and error categories.
+- Relevant command-intent contract entries for lint, build, related tests, docs, release checks, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- If official standard, browser-support, proxy-default, CDN-default, or runtime-support claims are written durably, use official or repository-approved source evidence and avoid stale "latest" wording.
+- If the delivery change affects request/response schema, public headers, generated clients, or docs, also use `api-contract-change`.
+- If private data, credentials, signed URLs, cookies, CORS, tenant isolation, or permission caches are involved, also use `auth-permission-change` or `security-privacy-review`.
+- If the change is motivated by speed, bandwidth, tail latency, CPU cost, or connection pressure, also use `performance-budget-check`.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update route handlers, response headers, streaming adapters, proxy/CDN configuration, browser transport clients, fallback code, tests, docs, and directly synchronized templates tied to the delivery behavior.
+- Add delivery fixtures, contract tests, integration tests, browser-client tests, and docs examples when repository surfaces support them.
+- Add explicit fallback, feature-detection, cache-variance, replay, heartbeat, timeout, reconnect, and observability behavior.
+- Do not silently add compression, buffering changes, cache sharing, streaming transports, or browser feature assumptions without naming the caller and fallback contract.
+- Do not use raw browser, proxy, package-manager, server, or benchmark commands unless they are configured oneshot command intents.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the delivery surface:
+   - static asset or file download;
+   - API response compression;
+   - compression dictionary transport;
+   - large archive, patch, or range-readable payload;
+   - streaming HTTP response;
+   - Server-Sent Events;
+   - WebTransport;
+   - WebSocket, long-poll, or fallback channel;
+   - proxy, CDN, edge, service-worker, or framework adapter rule.
+2. Build a delivery ledger before editing:
+   - route or asset path, method, status, media type, response size, cacheability, auth requirement, and caller list;
+   - selected headers, cache key, `Vary` dimensions, compression choice, proxy/CDN path, HTTP version assumption, fallback path, and observability fields.
+3. Keep content coding separate from media type and file naming.
+   - A precompressed file extension such as `.zst` is an origin artifact, not the browser-facing contract by itself.
+   - Serve the original media type plus the negotiated `Content-Encoding`.
+   - Use `Vary: Accept-Encoding` or an equivalent cache-key rule whenever the same URL can produce different encodings.
+   - Do not let a CDN cache one encoded variant for clients that did not negotiate it.
+   - Check decoder compatibility constraints, compression level, CPU cost, and p95/p99 latency before calling a smaller payload a faster response.
+4. Treat zstd HTTP content coding as negotiated delivery, not a universal asset format.
+   - Keep a supported fallback for clients, proxies, or CDNs that do not negotiate it.
+   - Avoid tiny-payload wins that spend more CPU than bandwidth saved.
+   - Keep any content-coding window or decoder-limit claim tied to official sources or repository evidence.
+   - For generated `.zst` artifacts, distinguish browser delivery from archive download, package artifact, or internal cache storage.
+5. Treat compression dictionary transport as an explicit compatibility feature.
+   - Feature-detect or negotiate dictionary use; never require it for first contact unless a closed client contract says so.
+   - Make dictionary identity, freshness, invalidation, cache key, and fallback behavior explicit.
+   - Keep dictionary selection deterministic enough that a proxy, service worker, or CDN cannot mix incompatible dictionary and response pairs.
+   - Report browser, CDN, proxy, and framework support as dated or verified evidence, not as a memory claim.
+6. For large archives, deltas, logs, or patch payloads, define the read model.
+   - If callers need random access, partial download, verification, or resume, design chunking, indexing, frame boundaries, metadata, checksums, and range behavior before choosing a compression format.
+   - Treat checksums as corruption detection. They are not signatures or authorization.
+   - Keep decompression limits and zip-bomb style expansion risk in the security review path when untrusted content is accepted.
+7. For Server-Sent Events, design the event stream as a contract.
+   - SSE is server-to-client. Do not smuggle client commands into an event stream design.
+   - Define event names, `id`, data shape, replay buffer, `Last-Event-ID` handling, `retry`, and heartbeat comments.
+   - Account for browser `EventSource` limitations such as URL-based `GET`, credential behavior, and restricted custom request headers.
+   - Choose cookies, signed URLs, CORS, or a separate token exchange deliberately when auth is needed.
+   - Disable or bypass proxy buffering where required, flush early, and send small heartbeat or comment frames often enough to keep intermediaries from deciding the connection is idle.
+   - Consider HTTP/1 connection limits, HTTP/2 stream behavior, tab count, and same-origin pressure.
+   - Handle backpressure, cancellation, slow clients, reconnect storms, and replay misses.
+8. For WebTransport, design the transport protocol instead of treating it as faster WebSocket.
+   - Confirm secure context, HTTP/3, QUIC/UDP, certificate, proxy, load balancer, firewall, and ALPN path assumptions.
+   - Use `ready` and `closed` lifecycle handling; do not treat construction as a connected state.
+   - Use datagrams only for lossy latest-state or telemetry-style data where drops are acceptable.
+   - Use streams for reliable commands, state transitions, payments, writes, and ordered data.
+   - Add sequence numbers, timestamps, idempotency keys, and application-level ordering when messages cross datagrams and streams.
+   - Keep worker/off-main-thread behavior in view when encoding, decoding, or fan-out can block UI responsiveness.
+   - Provide WebSocket, SSE, or long-poll fallback when the product cannot require WebTransport-capable networks and browsers.
+9. Check proxy, CDN, and edge behavior as part of the feature.
+   - Name where compression happens: origin, proxy, CDN, edge worker, service worker, or build artifact.
+   - Name where buffering happens and whether the streaming route can flush.
+   - Name where HTTP/2 or HTTP/3 terminates and what the origin actually receives.
+   - Name cache variance for auth, tenant, language, content coding, dictionary, range requests, and private responses.
+   - Do not cache private event streams, signed URLs, or tenant-specific responses as public assets.
+10. Keep delivery concerns out of core business logic.
+    - Use adapters or transport modules to translate EventSource, WebTransport, WebSocket, compression, cache, and proxy details into internal events or commands.
+    - Do not let datagram loss, browser reconnect, CDN cache keys, or compression dictionary ids become domain rules.
+    - Use `adapter-boundary` when external protocol objects or framework response objects would otherwise leak into application services.
+11. Add observability before trusting delivery behavior.
+    - Record selected content coding, cache hit/miss, proxy or CDN status, response size, flush latency, reconnect count, last event id, replay miss count, client fallback, RTT, stream close reason, queue age, dropped datagrams estimate, and transport error class when relevant.
+    - Keep metric labels bounded. Do not label metrics by full URL with unbounded query strings, raw user ids, tokens, dictionary hashes, or event payloads.
+12. Verify with configured command intents.
+    - Use lint, build, related tests, docs validation, release checks, and mustflow checks when available.
+    - Report missing browser, proxy, CDN, compression-negotiation, stream-flush, or WebTransport integration coverage instead of inventing raw commands.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Delivery surface, route or asset ledger, selected headers, cache key, proxy/CDN path, and fallback path are explicit.
+- Content coding, media type, file extension, and archive format are not conflated.
+- zstd, dictionary compression, gzip, brotli, or other coding choices have fallback, cache variance, CPU, and compatibility behavior defined.
+- SSE streams define event shape, heartbeat, replay, reconnect, auth, proxy buffering, cancellation, and slow-client behavior.
+- WebTransport sessions define lifecycle, datagram versus stream reliability, fallback, network assumptions, and observability.
+- Private, tenant-specific, credentialed, or signed responses are not accidentally made cache-public.
+- Transport, proxy, CDN, and browser details are contained at adapter or delivery boundaries rather than leaking into core logic.
+- Delivery and performance claims are backed by configured verification, source evidence, or clearly reported as unverified.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured checks that prove the changed delivery behavior. Report missing browser, proxy, CDN, HTTP/2, HTTP/3, stream-flush, EventSource reconnect, WebTransport fallback, or compression-negotiation verification when relevant.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If a compressed response decodes incorrectly, first check `Content-Type`, `Content-Encoding`, `Accept-Encoding`, `Vary`, cache key, and double-compression before changing application payloads.
+- If streaming appears batched, check proxy buffering, framework buffering, CDN behavior, flush calls, heartbeat cadence, and response transforms before blaming the client.
+- If SSE reconnects repeat or miss events, check event ids, replay buffer, heartbeat, retry interval, connection limits, auth expiry, and slow-client cancellation.
+- If WebTransport works locally but fails in production, check HTTP/3, QUIC/UDP, ALPN, certificates, proxy/load-balancer support, firewall behavior, and fallback path.
+- If a cache serves private or wrong-encoding data, fail closed, disable or narrow caching, and report the cache-key or `Vary` defect.
+- If official support or standard details cannot be verified, keep wording conservative and report the freshness boundary.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Delivery surface classified
+- Route or asset ledger
+- Header, cache key, proxy/CDN, and HTTP version notes
+- Content coding, dictionary, archive, or compression decision
+- SSE, WebTransport, WebSocket, or fallback behavior when relevant
+- Auth, CORS, cookie, signed URL, tenant, and private-cache notes when relevant
+- Backpressure, cancellation, reconnect, replay, timeout, and buffering behavior
+- Observability fields added or required
+- Tests, fixtures, browser/proxy checks, or docs synchronized
+- Command intents run
+- Skipped verification and reasons
+- Remaining delivery or streaming risk

package/templates/default/locales/en/.mustflow/skills/performance-budget-check/SKILL.md

@@ -2,11 +2,11 @@
 mustflow_doc: skill.performance-budget-check
 locale: en
 canonical: true
-revision: 19
+revision: 20
 lifecycle: mustflow-owned
 authority: procedure
 name: performance-budget-check
-description: Apply this skill when runtime performance, hot paths, user-perceived latency, p95/p99 tail latency, throughput, infrastructure cost, memory, GC pressure, CPU cache locality, allocation churn, bundle size, payload size, media loading, build time, filesystem scanning, process spawning, IPC/RPC/DB/API fan-out, N+1 work, repeated filtering/sorting/parsing/serialization, caching, pagination, queues, virtualization, backpressure, or performance claims are planned, edited, reviewed, or reported.
+description: Apply this skill when runtime performance, hot paths, user-perceived latency, p95/p99 tail latency, throughput, infrastructure cost, memory, GC pressure, CPU cache locality, allocation churn, bundle size, payload size, HTTP delivery, compression, streaming latency, media loading, build time, filesystem scanning, process spawning, IPC/RPC/DB/API fan-out, N+1 work, repeated filtering/sorting/parsing/serialization, caching, pagination, queues, virtualization, backpressure, or performance claims are planned, edited, reviewed, or reported.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -27,17 +27,17 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Keep performance work focused on the places where cost multiplies: item count, request count, service fan-out, retry count, bytes transferred, bytes copied, objects allocated, rendered nodes, database round trips, filesystem walks, IPC calls, cache misses, branch misses, lock waits, queue backlog, and connection-pool waits.
+Keep performance work focused on the places where cost multiplies: item count, request count, service fan-out, retry count, bytes transferred, compression CPU, stream flushes, reconnects, bytes copied, objects allocated, rendered nodes, database round trips, filesystem walks, IPC calls, cache misses, branch misses, lock waits, queue backlog, and connection-pool waits.
 
 Prefer removing unnecessary work over making unnecessary work slightly faster. A performance change should preserve semantics, name the hot path, and report whether it is measured, inferred from complexity, or still unverified. Do not treat Big-O labels, "hash map", "indexed query", "cache", "queue", or "autoscaling" as proof that a path is fast enough; constant factors, memory layout, runtime dispatch, allocation, locks, external round trips, and shared resource bottlenecks often dominate.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- A task changes or reports latency, p95 or p99 tail latency, throughput, infrastructure cost, memory use, GC pressure, CPU cache locality, allocation churn, build time, bundle size, payload size, media loading, CLI duration, test scheduling, cache initialization, filesystem scanning, process spawning, or command execution duration.
+- A task changes or reports latency, p95 or p99 tail latency, throughput, infrastructure cost, memory use, GC pressure, CPU cache locality, allocation churn, build time, bundle size, payload size, HTTP delivery, compression, streaming latency, media loading, CLI duration, test scheduling, cache initialization, filesystem scanning, process spawning, or command execution duration.
 - Code introduces or reviews repeated external access such as DB queries, repository calls, HTTP/RPC calls, Redis calls, S3/object storage calls, IPC commands, filesystem `stat` or scan calls, or child processes.
 - Code filters, sorts, groups, joins, parses, serializes, clones, formats, normalizes, validates, allocates objects, builds DTOs, opens clients or sessions, renders UI lists, or computes projections inside loops or render paths.
-- A change adds caching, memoization, precomputation, derived stores, selectors, virtualized lists, batching, queues, concurrency limits, cancellation, backpressure, debounce, throttle, workers, background jobs, CDN or HTTP caching assumptions, payload reduction, or media optimization for performance reasons.
+- A change adds caching, memoization, precomputation, derived stores, selectors, virtualized lists, batching, queues, concurrency limits, cancellation, backpressure, debounce, throttle, workers, background jobs, CDN or HTTP caching assumptions, compression, content coding, streaming, payload reduction, or media optimization for performance reasons.
 - Code uses async work, goroutines, futures, workers, task queues, streams, regexes, date parsing, string construction, exception handling, or logging in a path whose input or traffic can grow.
 - A report claims a path is faster, optimized, efficient, lightweight, responsive, scalable, low-memory, low-overhead, or safe for large input.
 
@@ -72,6 +72,7 @@ Prefer removing unnecessary work over making unnecessary work slightly faster. A
 - If personal data, authorization, tenant isolation, secrets, logs, retention, or audit data is involved, also use `security-privacy-review`.
 - If database schema, query, index, migration, or transaction behavior changes, also use `database-change-safety`, `database-migration-change`, or the matching database engine skill.
 - If UI rendering, layout, accessibility, or user-facing interaction changes, also use `ui-quality-gate`.
+- If HTTP content coding, CDN or proxy delivery, SSE, WebTransport, streaming flush behavior, or browser transport fallback changes, also use `http-delivery-streaming`.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -105,6 +106,7 @@ Prefer removing unnecessary work over making unnecessary work slightly faster. A
 10. Preserve semantics while changing data structures. State whether order, duplicate handling, first versus last winner, tie-breakers, missing records, and stable IDs still match the old behavior.
 11. Bound reads and materialization. Avoid unbounded `SELECT *`, `findAll`, full filesystem scans, full JSON loads, full array materialization, whole response bodies, and API responses without pagination, projection, chunking, or streaming when data can grow.
 12. Reduce payload and media work before tuning rendering internals. Send only needed fields, avoid overfetching, split late or optional data, use HTTP caching or CDN only for cacheable assets or responses, and check image dimensions, formats, lazy loading, and fixed layout dimensions before adding component memoization.
+    - Treat compression and streaming as latency tradeoffs, not free wins. Check compression CPU, content-coding negotiation, dictionary fallback, proxy buffering, buffered stream latency, flush latency, reconnect pressure, and whether p95/p99 improves for the actual client path. Do not report a false compression win when smaller bytes increase CPU, buffering, or tail latency.
 13. Check sorting and top-k work. Do not sort entire collections when only a top subset is needed. Precompute sort keys when comparison logic parses dates, normalizes strings, computes scores, or reads paths.
 14. Check pagination semantics. Offset pagination can become linearly slower and can duplicate or skip items on changing data. Prefer stable keyset or cursor semantics when the product does not require arbitrary page jumps.
 15. Move repeated pure computation out of loops and renders. Normalize queries once, precompute search blobs or numeric timestamps, reuse regexes and formatters, and avoid repeated schema validation after data crosses a trusted boundary.
@@ -143,7 +145,7 @@ Prefer removing unnecessary work over making unnecessary work slightly faster. A
 - The wall-time breakdown, CPU-versus-wait classification, saturation signal, and resource bottleneck class are explicit when evidence exists.
 - Speed, memory, bundle, payload, query-count, render, CPU locality, allocation, lock, pool, queue, or I/O claims are backed by measurement or labeled as complexity-only.
 - N+1 work, hidden quadratic scans, unbounded materialization, repeated serialization, repeated allocation, client/session churn, broad rendering, and unbounded or accidentally sequential async work are removed or reported.
-- Caches, queues, batching, concurrency, workers, streams, CDN or HTTP caching, media optimization, and projections have invalidation, ordering, duplicate, partial-failure, cancellation, backpressure, capacity, stale-data, and memory behavior defined where relevant.
+- Caches, queues, batching, concurrency, workers, streams, compression, CDN or HTTP caching, media optimization, and projections have invalidation, ordering, duplicate, partial-failure, cancellation, backpressure, capacity, stale-data, CPU, and memory behavior defined where relevant.
 - Correctness, security, durability, privacy, and user-visible semantics remain intact or are explicitly reported as tradeoffs.
 
 <!-- mustflow-section: verification -->
@@ -180,7 +182,7 @@ Use the narrowest configured test, build, docs, release, or mustflow intent that
 - Performance evidence: measured, complexity-only, or unverified
 - Semantics preserved: order, duplicates, IDs, consistency, partial failure, cancellation, and stale result handling
 - Optimization applied or recommended
-- Cache, queue, batching, concurrency, projection, UI, payload, media, memory, runtime, lock, pool, stream, retry, timeout, deployment, sharding, and I/O notes where relevant
+- Cache, queue, batching, concurrency, projection, UI, payload, compression, HTTP delivery, media, memory, runtime, lock, pool, stream, retry, timeout, deployment, sharding, and I/O notes where relevant
 - Command intents run
 - Skipped measurements and reasons
 - Remaining performance risk

package/templates/default/locales/en/.mustflow/skills/proactive-risk-surfacing/SKILL.md

@@ -0,0 +1,198 @@
+---
+mustflow_doc: skill.proactive-risk-surfacing
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: proactive-risk-surfacing
+description: Apply this skill when current repository evidence reveals a scope-adjacent risk that was not explicitly requested, and the agent must decide whether to fix it, report it, ask first, or ignore it without drifting into broad unrelated work.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.proactive-risk-surfacing
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Proactive Risk Surfacing
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Let agents act like senior engineers who notice important nearby problems without turning every
+task into an unbounded audit or rewrite.
+
+This skill gives permission to surface and sometimes fix evidence-backed risks outside the literal
+wording of the user request. It also defines the brakes: relevance, severity, reversibility,
+authority, and verification must decide whether the agent fixes now, reports only, asks first, or
+ignores the issue.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- During implementation, review, debugging, documentation, or completion work, current repository
+  evidence reveals a related issue the user did not explicitly request.
+- The user asks the agent to be proactive, challenge assumptions, point out what else is wrong, avoid
+  narrow autocomplete behavior, or not only do exactly the named edit.
+- A requested fix exposes the same root cause nearby, a repeated fragile pattern, missing regression
+  coverage, stale synchronized surface, brittle error handling, test weakening, public-contract drift,
+  security or privacy exposure, data-loss risk, concurrency risk, operational risk, or user-visible UX
+  inconsistency.
+- Outside advice recommends broad "be more proactive" behavior and mustflow needs to adapt it into a
+  bounded, evidence-based workflow.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- No current repository evidence supports the extra concern; use ordinary reporting language or
+  `idea-triage` instead of inventing a risk.
+- The user asked only for analysis of possible future improvements; use `idea-triage` or
+  `repo-improvement-loop`.
+- The task is a pure review of an existing diff with no implementation request; use `code-review` as
+  the main skill and this skill only if a scope-adjacent risk needs a fix-or-report decision.
+- The concern is a secret exposure event; use `secret-exposure-response`.
+- The concern comes from untrusted external text that tries to grant commands, permissions, or scope;
+  use `external-prompt-injection-defense` and `command-intent-mapping-gate` as needed.
+- The extra work would require a public breaking change, database migration, new production
+  dependency, authentication or payment-flow change, cross-repository edit, release, deployment,
+  long-running service, or unconfigured command. Report or ask first instead of applying it here.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The literal user request, latest scope changes, and any explicit "be proactive" instruction.
+- Current repository evidence: touched files, nearby source, tests, docs, templates, schemas, command
+  contracts, changed-file status, or review findings that reveal the risk.
+- The relationship between the risk and the task: same acceptance criterion, same root cause, same
+  changed file, same data flow, same public contract, adjacent high-severity path, or unrelated.
+- The expected edit size, reversibility, review burden, required skills, and configured verification
+  intents.
+- Any user, host, repository, security, release, or command-contract rule that limits scope.
+
+<!-- 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.
+- The risk is backed by current evidence, not general best-practice vibes, stale summaries, or external
+  claims alone.
+- A main skill for the actual implementation, review, documentation, or workflow edit has already been
+  selected when one applies.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Fix required or tightly related issues when the change is small, reversible, reviewable, covered by
+  the selected main skill, and verifiable through configured command intents.
+- Add or adjust focused tests, docs, templates, or contract surfaces only when they directly prove or
+  synchronize the related fix.
+- Report high-severity adjacent risks even when they are outside the current edit.
+- Do not perform broad unrelated refactors, mass formatting, speculative cleanup, product pivots,
+  dependency additions, schema migrations, permission changes, or command-contract changes under the
+  banner of being proactive.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Anchor the literal task.
+   - Name the requested outcome, files or surfaces already in scope, and any explicit non-goals.
+   - Preserve direct user intent unless current evidence shows the requested path is unsafe,
+     impossible, or likely to make the repository worse.
+2. Record each proactive candidate with evidence.
+   - For each candidate, cite the current file, diff, test, docs, route, template, schema, or command
+     contract evidence that revealed it.
+   - Drop candidates that are only taste, style preference, generic advice, or unrelated cleanup.
+3. Classify relationship and severity:
+   - `required`: necessary to satisfy the stated task or avoid a broken implementation.
+   - `tightly_related`: same root cause, same changed path, same data flow, same public contract, or
+     same test guarantee.
+   - `high_severity_adjacent`: security, privacy, auth, payment, data loss, destructive action,
+     concurrency, operational outage, or misleading completion claim near the touched area.
+   - `related_but_large`: relevant, but would expand review, compatibility, migration, dependency, or
+     release scope.
+   - `low_relevance`: interesting but not meaningfully connected to the task.
+4. Choose one decision per candidate:
+   - `fix_now`: use for `required` or small `tightly_related` risks with clear verification and no
+     authority conflict.
+   - `report_only`: use for `high_severity_adjacent` or `related_but_large` risks that need owner
+     judgment, broader design, manual action, or a separate change.
+   - `ask_first`: use when the safe path depends on user-owned product, compatibility, release,
+     security, migration, dependency, or data-retention decisions.
+   - `ignore`: use for `low_relevance`, subjective, duplicate, or unverified candidates.
+5. Before `fix_now`, activate the narrower matching skill for the actual edit if it has not already
+   been read. Examples include code, docs, tests, security, templates, API contracts, data, UI, release,
+   or workflow skills.
+6. Keep the proactive edit bounded.
+   - Touch only the files required for the related risk and its verification.
+   - Avoid mixing unrelated improvements into the same diff.
+   - If more than one useful candidate exists, fix the one that is required or highest leverage and
+     report the rest.
+7. Verify with the narrowest configured intents that cover both the original task and the proactive
+   fix. Report missing, skipped, manual-only, or failed verification instead of replacing it with an
+   inferred command.
+8. In the final report, separate:
+   - requested work completed;
+   - proactive risks fixed;
+   - proactive risks reported only;
+   - risks intentionally ignored or deferred;
+   - verification that covers each part.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The agent's extra work is tied to current evidence and the user's goal.
+- Every proactive candidate has a decision: `fix_now`, `report_only`, `ask_first`, or `ignore`.
+- Fixed candidates are small, reviewable, and covered by the relevant main skill and configured
+  verification.
+- Report-only candidates are visible without being misrepresented as completed work.
+- Unrelated cleanup and speculative improvements remain out of the diff.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use the narrower configured implementation, test, documentation, security, template, build, or release
+intent that proves the actual proactive edit. If no configured verification covers the extra fix, report
+that limitation and prefer `report_only` unless the fix is required for the original task.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If evidence is missing, stale, truncated, or repeated without new information, use
+  `evidence-stall-breaker` or downgrade the candidate to `report_only` or `ignore`.
+- If the candidate requires user-owned product, compatibility, security, migration, release, or
+  dependency judgment, stop that candidate at `ask_first`.
+- If a configured command fails after a proactive fix, use `failure-triage` before adding another
+  proactive change.
+- If the proactive change begins to require broad refactoring, split it into a reported follow-up or a
+  `repo-improvement-loop` cycle.
+- If the user rejects the proactive direction, preserve the requested task and remove or avoid the
+  extra work unless it is needed for safety or correctness.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Literal task and proactive trigger
+- Evidence inspected
+- Candidate decisions: `fix_now`, `report_only`, `ask_first`, or `ignore`
+- Files changed for proactive fixes
+- Related skills used
+- Verification intents run
+- Skipped checks and reasons
+- Remaining proactive risks or follow-up candidates

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.python-code-change
 locale: en
 canonical: true
-revision: 2
+revision: 3
 lifecycle: mustflow-owned
 authority: procedure
 name: python-code-change
-description: Apply this skill when Python source, packaging, runtime version, import layout, type checking, linting, tests, or CLI entry points are created or changed.
+description: Apply this skill when Python source, standard-library API usage, packaging, runtime version, import layout, type checking, linting, tests, or CLI entry points are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -28,13 +28,13 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Preserve Python runtime, packaging, import, async resource, public API, typing, lint, and test boundaries while making a focused change.
+Preserve Python runtime, standard-library, packaging, import, async resource, public API, typing, lint, and test boundaries while making a focused change.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
 - `.py`, `pyproject.toml`, `setup.py`, `setup.cfg`, requirements files, lockfiles, tox, nox, pytest, mypy, pyright, Ruff, or Python CI config changes.
-- The task touches package layout, CLI entry points, imports, type hints, dependency declarations, virtual environment assumptions, or tests.
+- The task touches standard-library feature usage, package layout, CLI entry points, imports, type hints, dependency declarations, virtual environment assumptions, or tests.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -46,6 +46,7 @@ Preserve Python runtime, packaging, import, async resource, public API, typing,
 ## Required Inputs
 
 - Python version source: `requires-python`, `.python-version`, tool version files, CI matrix, or container base image.
+- Standard-library feature and runtime-behavior assumptions, especially when using Python-version-gated APIs or changed security defaults.
 - Packaging and dependency files, test config, lint config, and type checker config.
 - Package layout: `src` layout, flat layout, namespace package, distribution name, import package name, package discovery settings, CLI entry points, plugin entry points, and nearby tests.
 - Async ownership and resource cleanup surface when coroutines, tasks, context managers, sessions, clients, pools, files, async generators, subprocesses, or logging change.
@@ -56,6 +57,7 @@ Preserve Python runtime, packaging, import, async resource, public API, typing,
 ## Preconditions
 
 - Determine the lowest supported Python version before choosing syntax or typing features.
+- Determine the lowest supported Python version before choosing standard-library features, changed defaults, syntax, or typing features.
 - Read package layout and import style before editing imports.
 - Treat global machine Python state as irrelevant unless the project explicitly declares it.
 
@@ -85,7 +87,19 @@ Preserve Python runtime, packaging, import, async resource, public API, typing,
    - installed console scripts or plugin entry points should be smoke-tested through the installed entry point contract, not by directly running a source file.
 8. Verify import origin when packaging risk is present. The public package should resolve from the installed environment intended by the project, not from accidental repository-root files.
 9. Validate unknown external data before treating it as typed domain data.
-10. Preserve async and resource ownership:
+10. Choose standard-library helpers by semantic contract and supported Python version:
+   - prefer cardinality-explicit iteration such as `zip(strict=True)`, `itertools.batched(..., strict=True)`, or Python 3.14+ `map(strict=True)` only when unequal lengths are a bug and the declared runtime supports the API;
+   - do not use `itertools.groupby` as a database-style grouping primitive unless input ordering and group materialization are intentional;
+   - avoid shared mutable defaults; use `default_factory` or an existing local construction pattern for per-instance mutable state;
+   - prefer `importlib.resources` for packaged data, `tomllib` for TOML reads, and `Path.walk()` only after checking version support, pruning behavior, symlink recursion, ordering, and cycle risks;
+   - use dataclass options such as `slots`, `frozen`, and `kw_only`, `StrEnum`, `TypedDict`, or `Protocol` only when they match the public shape and runtime/type-checker support;
+   - treat `functools.cache`, `lru_cache`, `cached_property`, `partial`, and Python 3.14+ `Placeholder` as state, memory, concurrency, and versioned-API choices rather than harmless terseness.
+11. Keep process, archive, and concurrency safety explicit:
+   - subprocess calls use argument lists, checked failure handling, timeouts, bounded captured output, and a narrow `shell=True` exception when the project already permits it;
+   - archive extraction, including `tarfile`, keeps untrusted archive inspection, extraction filters, partial-extract cleanup, and older-runtime defaults visible;
+   - `asyncio.TaskGroup`, `asyncio.timeout`, and `asyncio.to_thread` are used only when their cancellation, timeout, blocking-work, and Python-version semantics fit the surrounding lifecycle.
+12. Use runtime diagnostics as evidence, not as permanent workaround code. Interpreter or library diagnostics such as import timing, `tracemalloc`, `faulthandler`, profiling, and allocation tracing should go through configured diagnostic or verification intents when available, and missing intents should be reported instead of adding ad hoc command recipes to the skill.
+13. Preserve async and resource ownership:
    - every coroutine is awaited, returned by contract, or scheduled as an owned and tracked task;
    - raw background task creation is allowed only through the project's owner or spawn helper, a task group, or an equivalent lifecycle mechanism;
    - background tasks keep a strong reference, have a shutdown path, and retrieve failures instead of leaving never-retrieved exceptions;
@@ -94,20 +108,21 @@ Preserve Python runtime, packaging, import, async resource, public API, typing,
    - context managers and async context managers do not suppress exceptions unless suppression is the feature;
    - context-manager helpers that catch exceptions for logging re-raise after logging;
    - early-exit async generators have an explicit close path.
-11. Preserve traceback evidence. Logging inside exception handlers should retain exception information instead of logging only the exception message.
-12. Preserve public contracts:
+14. Preserve traceback evidence. Logging inside exception handlers should retain exception information instead of logging only the exception message.
+15. Preserve public contracts:
    - treat public imports, public signatures, exceptions, return shapes, CLI behavior, entry points, config keys, environment variables, dependency metadata, extras, Python version support, and typing stubs as compatibility-sensitive;
    - do not change sync functions into async functions, accepted input shapes, nullable behavior, documented exception types, tuple/dict/dataclass return shapes, config precedence, or environment variable semantics without a compatibility review;
    - typed packages should keep runtime and typing surfaces aligned, including `py.typed` and stubs when present.
-13. Avoid mutable default arguments, broad `except Exception: pass`, broad `BaseException` catches outside process boundaries, global state hidden behind module imports, and path handling that ignores existing `pathlib` or OS conventions.
-14. Use `# type: ignore[...]` only when tightly scoped, justified, and consistent with local policy.
-15. If packaging, public API, CLI, config, or typing contracts change, synchronize README examples, entry point tests, build metadata, docs, fixtures, and downstream-style examples that describe installation or usage.
-16. Choose configured verification intents that cover formatting, lint, type checking, tests, package build, installed-package smoke checks, and CLI smoke risk when available.
+16. Avoid mutable default arguments, broad `except Exception: pass`, broad `BaseException` catches outside process boundaries, global state hidden behind module imports, and path handling that ignores existing `pathlib` or OS conventions.
+17. Use `# type: ignore[...]` only when tightly scoped, justified, and consistent with local policy.
+18. If packaging, public API, CLI, config, or typing contracts change, synchronize README examples, entry point tests, build metadata, docs, fixtures, and downstream-style examples that describe installation or usage.
+19. Choose configured verification intents that cover formatting, lint, type checking, tests, package build, installed-package smoke checks, and CLI smoke risk when available.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
 
 - The code respects the declared Python version and packaging layout.
+- Python-version-gated standard-library features and changed runtime defaults are accepted only when the declared support matrix allows them.
 - Imports work from the project-supported execution path.
 - Packaging changes distinguish development imports from release artifact imports.
 - Async tasks, context managers, files, clients, pools, subprocesses, and generators have visible ownership and cleanup.
@@ -136,6 +151,7 @@ Report missing package, type, or test intents rather than inventing raw tool com
 - If a test only passes because repository root, `src`, or `tests` is injected into import paths, reject the fix and repair packaging or test layout instead.
 - If packaging correctness matters but only repository-root tests can run, report that wheel or installed-artifact verification is missing.
 - If the supported Python version blocks a syntax choice, rewrite to the supported form.
+- If the supported Python version blocks a standard-library feature, changed default, diagnostic flag, or helper API, use the supported equivalent or report the runtime-support decision instead of silently raising `requires-python`.
 - If third-party stubs or package metadata are wrong, document the local workaround and keep it narrow.
 - If a background task lacks owner, shutdown, strong reference, or exception retrieval, do not add it.
 - If cancellation or context-manager behavior is swallowed accidentally, restore propagation or document the intentional suppression contract.