mustflow 2.108.2 → 2.108.8

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

@@ -2,11 +2,11 @@
 mustflow_doc: skill.go-code-change
 locale: en
 canonical: true
-revision: 4
+revision: 7
 lifecycle: mustflow-owned
 authority: procedure
 name: go-code-change
-description: Apply this skill when Go source, modules, package APIs, interfaces, errors, goroutines, channels, context propagation, HTTP clients or servers, reverse proxies, JSON encoding, filesystem roots, network addresses, runtime limits, benchmarks, tests, tools, or generated code boundaries are created or changed.
+description: Apply this skill when Go source, modules, workspaces, package APIs, package layout, internal boundaries, interfaces, structs, errors, goroutines, channels, context propagation, HTTP clients or servers, Gin engines, router groups, middleware chains, request binding, validation, recovery, access logging, CORS, cookies, trusted headers, graceful shutdown, reverse proxies, database/sql request integration, JSON encoding, filesystem roots, network addresses, runtime limits, profiling, benchmarks, tests, tools, or generated code boundaries are created or changed.
 metadata:
   mustflow_schema: "1"
   mustflow_kind: procedure
@@ -28,13 +28,13 @@ metadata:
 <!-- mustflow-section: purpose -->
 ## Purpose
 
-Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JSON, filesystem, and test boundaries without adding needless abstraction.
+Preserve Go package, module, workspace, API, error, context, concurrency, runtime, HTTP, JSON, filesystem, performance, and test boundaries without adding needless abstraction.
 
 <!-- mustflow-section: use-when -->
 ## Use When
 
-- `.go`, `go.mod`, `go.sum`, `go.work`, build tags, generated code, public package API, tests, benchmarks, goroutines, channels, context propagation, HTTP clients or servers, reverse proxies, JSON encoding, filesystem access, network addresses, runtime tuning, tools, or module dependencies change.
-- The task touches interfaces, error wrapping, package structure, concurrency ownership, cancellation, timeout policy, memory limits, race-sensitive code, benchmark measurement, or module dependencies.
+- `.go`, `go.mod`, `go.sum`, `go.work`, build tags, generated code, public package API, tests, benchmarks, goroutines, channels, context propagation, HTTP clients or servers, Gin engines, router groups, middleware chains, request binding, validation, recovery, access logging, CORS, cookies, trusted headers, graceful shutdown, reverse proxies, database/sql request integration, JSON encoding, filesystem access, network addresses, runtime tuning, profiling, tools, or module dependencies change.
+- The task touches interfaces, structs, zero-value behavior, error wrapping, package structure, `internal` boundaries, import direction, concurrency ownership, cancellation, timeout policy, memory limits, race-sensitive code, benchmark measurement, or module dependencies.
 - Code or docs use Go-version-gated features such as expression operands to `new`, range-over-function iterators, generic type aliases, reflect iterators, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `T.ArtifactDir`, `B.ArtifactDir`, `F.ArtifactDir`, `testing/cryptotest.SetGlobalRandom`, `os.Root` or `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `go fix` modernizers, `encoding/json/v2`, experimental `GOEXPERIMENT` features, or newer runtime defaults.
 
 <!-- mustflow-section: do-not-use-when -->
@@ -49,7 +49,9 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 - `go.mod`, `go.sum`, `go.work`, build tooling, lint config, and CI hints.
 - All files in the changed package, including `_test.go`, build-tagged files, examples, and generated-file markers.
 - The public API surface when exported identifiers, errors, or package paths change.
+- Package ownership, import direction, `internal` visibility, module path, major-version suffix, workspace usage, and whether the project is an importable library, self-contained server, tool, or monorepo.
 - Runtime and deployment context when the change touches HTTP, goroutines, timers, memory, `GOMAXPROCS`, cgroups, race detection, PGO, profiling, or container behavior.
+- Gin or other Go HTTP framework context when relevant: framework version, minimum Go version, engine construction, route registration order, group creation order, middleware chain order, trusted proxy settings, recovery owner, logger query-string policy, route-pattern metric policy, CORS policy, cookie policy, trusted header boundary, context reuse boundaries, binding method, validator tags, body-size policy, upload limits, database call context, and response/error ownership.
 - Minimum supported Go version, `go` directive, `toolchain` directive, `GOEXPERIMENT`, and whether the feature is stable, experimental, or repository-pinned.
 - Configured verification intents.
 
@@ -59,7 +61,7 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 - Inspect the whole package before adding names or methods.
 - Determine whether the change affects exported API, concurrency ownership, or dependency graph.
 - Identify generated files and avoid direct edits unless explicitly requested.
-- If a Go release, "latest Go", standard-library feature, runtime default, experimental package, or toolchain claim is written durably, use `version-freshness-check` and official Go sources.
+- If a Go release, "latest Go", standard-library feature, runtime default, experimental package, toolchain claim, or Go framework version claim such as Gin release or minimum-Go support is written durably, use `version-freshness-check` with official Go, package registry, or framework-owned sources.
 
 <!-- mustflow-section: allowed-edits -->
 ## Allowed Edits
@@ -67,6 +69,9 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 - Keep interfaces small and preferably owned by the consuming side.
 - Return concrete provider types from provider packages unless the package intentionally hides multiple implementations as its public API.
 - Keep domain and use-case packages free of SQL, HTTP transport, queue, cloud SDK, ORM, and vendor persistence types unless those types are the explicit public API.
+- Use `internal` to protect implementation freedom for server and tool packages that are not meant to be imported.
+- Keep structs, constructors, and zero values aligned with invariants: make the zero value useful, harmless, or impossible to misuse.
+- Split domain, storage, JSON, and transport DTO shapes when they have different owners, lifetimes, validation rules, or compatibility contracts.
 - Preserve context propagation across API and goroutine boundaries.
 - Return actionable errors and wrap causes when callers need `errors.Is` or `errors.As`.
 - Add table-driven tests when they clarify behavior.
@@ -76,43 +81,58 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 ## Procedure
 
 1. Read module files, package files, tests, build tags, and generated-code markers.
-2. Classify the change as package API, internal implementation, dependency, error behavior, context flow, concurrency, HTTP or proxy behavior, JSON encoding, filesystem safety, runtime or deployment behavior, benchmark, tooling, or test-only.
+2. Classify the change as module or workspace metadata, package API, package layout, internal implementation, dependency, error behavior, context flow, concurrency, HTTP or proxy behavior, JSON encoding, filesystem safety, runtime or deployment behavior, performance measurement, benchmark, tooling, or test-only.
 3. Check the Go version contract before using newer syntax or APIs:
    - treat the `go` directive as a language and module compatibility switch, not decoration;
    - do not use `new(expr)`, range-over-function iterators, generic type aliases, reflect iterator methods, `errors.AsType`, `sync.WaitGroup.Go`, `testing/synctest`, `testing.B.Loop`, `T.ArtifactDir`, `B.ArtifactDir`, `F.ArtifactDir`, `testing/cryptotest.SetGlobalRandom`, `os.Root`, `os.OpenInRoot`, `omitzero`, `go.mod` `tool`, `go fix` modernizers, `encoding/json/v2`, or any `GOEXPERIMENT` feature unless the repository's supported Go version and build path allow it;
    - distinguish stable standard-library APIs from experimental APIs that require `GOEXPERIMENT`;
-   - when `go.mod` or `go.work` changes, report language-version, module-graph, toolchain, and downstream support impact.
+   - when `go.mod` or `go.work` changes, report language-version, module-graph, workspace, toolchain, and downstream support impact.
 4. Check package boundaries before adding a package or interface:
+   - treat a module as a release, version, and distribution boundary, not a folder-cleanup tool;
+   - treat `go.work` as a local multi-module development surface unless the repository explicitly supports committing and verifying workspace mode;
+   - keep module paths stable and use the required major-version suffix for v2+ modules;
+   - prefer `internal` for server implementation packages that are not intended as public imports;
+   - check import direction before function bodies: domain packages should not import HTTP status codes, ORM rows, SQL drivers, queues, cloud SDKs, or vendor transport shapes unless that dependency is the package's explicit contract;
    - reject shared bucket packages named `common`, `util`, `types`, `interfaces`, `api`, or `models` unless the repository already has a specific local convention with a narrower meaning;
    - put an interface in the package that consumes the methods, not in the package that merely implements them;
    - create an interface only after a real consumer needs that exact method set;
    - shrink an interface to the methods the immediate consumer calls;
    - reject provider-side interfaces that exist only for mocks;
    - reject provider constructors that return interfaces by default; prefer concrete exported types such as `*Client`, `*Store`, or `*Service`;
+   - use generics for reusable containers, algorithms, and type-safe plumbing, not as a substitute for clear domain boundaries;
    - verify that a package split reduces a real dependency direction problem or creates a coherent capability instead of hiding imports.
 5. If exported identifiers or package paths change, classify the public API impact:
    - treat exported functions, variables, constants, types, methods, struct fields, interfaces, interface method sets, sentinel errors, typed errors, module path, package import path, and minimum Go version as contracts;
    - assume exported symbols in a v1+ module are public API unless the package is internal or local evidence proves otherwise;
    - do not remove, rename, or change exported signatures, exported field types, exported interface methods, or observable error behavior without an explicit breaking-change plan;
-   - adding a method to an exported interface is breaking for external implementations even when adding a method to a concrete type would be safe.
+   - adding a method to an exported interface is breaking for external implementations even when adding a method to a concrete type would be safe;
+   - changing exported struct fields or JSON tags can be an API change even when function signatures stay stable.
 6. Preserve error contracts:
    - use `errors.Is` and `errors.As` semantics as observable API when documented or already tested;
    - do not compare error strings;
+   - do not rely on `err == sentinel` when callers may receive wrapped errors;
    - do not expose dependency sentinel or typed errors through wrapping unless the package intentionally supports them as API;
    - treat a change between observable wrapping and non-observable formatting as API-sensitive;
+   - keep public response messages separate from internal error causes. Do not return `err.Error()` to clients when the error may contain SQL, file paths, URLs, tokens, dependency details, or stack context;
+   - classify context cancellation, context deadlines, dependency timeouts, and domain failures at package boundaries instead of letting infrastructure errors leak upward unchanged;
+   - keep typed error pointer/value behavior consistent and avoid typed-nil errors behind an `error` interface;
+   - use `errors.Join` or multiple `%w` only when callers are expected to use `errors.Is` or `errors.As` rather than simple unwrap behavior;
    - use `errors.AsType` only when the supported Go version allows it and the shorter form preserves the same typed-error contract;
    - add tests for documented sentinel or typed errors when the error behavior changes.
-7. If goroutines or channels change, name the owner, stop condition, cancellation path, wait path, error path, close responsibility, and test synchronization.
+7. If goroutines or channels change, name the owner, stop condition, cancellation path, wait path, error path, panic policy, close responsibility, backpressure boundary, and test synchronization.
 8. Choose the right goroutine primitive:
    - use `sync.WaitGroup.Go` only for tasks that do not return errors and must not panic;
+   - call manual `WaitGroup.Add` before starting the goroutine and do not copy a `WaitGroup` after first use;
    - use an errgroup-style boundary when work needs error propagation, context cancellation, or concurrency limits;
    - do not hand-roll `WaitGroup` plus error channel plus cancellation plus semaphore unless the local code already owns that exact pattern and tests cover it;
    - treat buffered-channel semaphores as semantic backpressure, not just a performance knob; changing capacity can change ordering and pressure;
+   - do not treat a channel as a data-race shield for maps, slices, pointers, or structs still shared across goroutines;
    - treat `TryLock` as suspicious unless skipping the work is genuinely correct and observable.
 9. Reject fire-and-forget goroutines unless they are owned by a long-lived object with a shutdown path, joined before return, managed by a group with a wait path, or explicitly documented as safely detached.
 10. Preserve context propagation:
    - request-scoped functions accept `ctx` first and pass it down;
    - do not store request context in structs;
+   - do not use `context.Value` as dependency injection, optional parameters, or a hidden configuration bag;
    - do not pass nil context;
    - do not introduce `context.Background()` inside request or operation depth unless it is a true process root with a documented owner;
    - derived contexts must release their cancel function on every path;
@@ -124,41 +144,97 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
    - the sender that knows all sends are complete closes the channel;
    - receivers do not close borrowed input channels;
    - multiple senders require a coordinator that closes only after all senders finish;
-   - cancellable pipelines must avoid permanently blocking upstream goroutines when downstream stops early.
+   - cancellable pipelines must avoid permanently blocking upstream goroutines when downstream stops early;
+   - buffered channels are not durable queues and must not hide unbounded producer or retry behavior;
+   - avoid busy-loop `select` statements with a `default` branch unless skipping work immediately is the intended behavior and CPU impact is bounded.
 12. Use iterator functions only for pull-style traversal, not hidden concurrency. Honor the `yield` return value immediately, call the `stop` function from pull iterators, keep resource ownership visible, and keep channels for actual concurrent communication or backpressure.
 13. Keep timeout policy at request, command, API, or operation boundaries. Do not hide arbitrary sleeps or timeouts in reusable helpers unless that helper explicitly owns the policy.
 14. Check HTTP and proxy defaults:
-   - set deliberate `http.Client` and `http.Server` timeouts for network-facing code; zero timeout means no limit in important cases;
+   - use an explicit `http.Server` for production-facing servers rather than bare convenience helpers;
+   - set deliberate `ReadHeaderTimeout`, request/body read policy, `WriteTimeout`, `IdleTimeout`, `MaxHeaderBytes`, `BaseContext`, `ConnState`, and `ErrorLog` where the server owns those behaviors; zero timeout means no limit in important cases;
+   - protect request bodies separately from headers with size limits and route-appropriate read deadlines;
+   - treat `WriteTimeout` carefully for SSE, long polling, chunked streaming, and large downloads; streaming paths need heartbeat, flush, per-write deadline, and disconnect behavior instead of a single short global timeout;
+   - do not treat `http.TimeoutHandler` as cancellation of the underlying business work; pass `r.Context()` through database, RPC, cache, queue, and outbound HTTP calls;
+   - do not use `ResponseWriter` or request bodies after `ServeHTTP` returns; background work must copy the needed payload and use a lifecycle context that is not the finished request context;
+   - design graceful shutdown as a state transition: drain readiness, stop new traffic, wait for `Shutdown`, fall back to `Close` only after the shutdown budget, and keep the main goroutine alive until shutdown completes;
+   - track WebSocket, hijacked, upgraded, or long-lived connections separately because ordinary `Shutdown` does not wait for them;
    - reuse clients and transports instead of creating them per request;
    - prefer reverse-proxy rewrite hooks over deprecated or unsafe director-style mutation when the supported Go version allows it;
    - keep hop-by-hop header, forwarded-host, scheme, cancellation, streaming, and error-mapping behavior explicit.
-15. Keep JSON contracts honest:
+15. Check Gin and Go HTTP framework boundaries when relevant:
+   - prefer explicit production server construction around the framework engine; do not treat `Run`, `RunTLS`, or convenience helpers as graceful shutdown, timeout, or lifecycle policy;
+   - treat `gin.Default()` as a demo convenience unless local production policy really accepts its logger and recovery defaults; production paths usually need explicit request id, trace id, structured logging, panic reporting, security headers, timeout, metrics, and recovery ownership;
+   - centralize error response, access log, and metrics ownership. Handlers may classify failures, but one final responder should map typed errors to status, code, safe message, log level, retryability, and exposed details;
+   - use `c.Error` only when a later middleware owns normalization. Do not mix scattered `c.JSON(500, ...)`, `AbortWithError`, and a separate logger that reads a different error source;
+   - preserve `errors.Is` and `errors.As` across service and transport boundaries so domain failures, context deadlines, client cancellations, dependency timeouts, and programmer bugs stay distinguishable;
+   - use custom recovery when production needs panic id, request id, route pattern, user or tenant id, stack capture, error tracking, and a safe generic response. Recovery middleware does not catch panics in goroutines started by the handler;
+   - log structured request fields from a fixed schema such as request id, trace id, method, route pattern, status, latency, client IP, user or tenant id, error code, error kind, panic marker, and body size. Use `c.FullPath()` or an equivalent route pattern for logs and metrics, not raw high-cardinality paths;
+   - treat 4xx, validation, auth denial, not found, timeout, client cancellation, 5xx, dependency failure, and panic as different observability classes instead of logging every non-2xx as the same error;
+   - register middleware before the routes and child groups that must receive it. `group.Use()` and parent middleware added after route or child-group creation must not be assumed to retrofit existing handlers;
+   - review middleware order around `c.Next()`: before-next code wraps inbound work, after-next code observes completed downstream work, and response writers or transactions must be finalized in the right phase;
+   - after `Abort` or `AbortWithStatusJSON`, return from the current middleware or handler unless the remaining local code is intentionally safe to run;
+   - do not pass the original `*gin.Context` into goroutines, store it in structs, or keep it after the request. Extract immutable values and use `c.Request.Context()` only for work that should die with the request;
+   - treat `c.Copy()` as a shallow request-context snapshot, not a deep copy of request data, cancellation semantics, pointers, maps, slices, body bytes, or framework writer state;
+   - keep response writes in the original handler flow. Background work should report through channels, queues, or owned result stores rather than calling `c.JSON`, `c.Error`, `c.Abort`, `c.Writer`, `c.Query`, `c.PostForm`, or multipart parsing from another goroutine;
+   - forward `c.Request.Context()` to database, cache, RPC, outbound HTTP, and long-running work that should respect disconnects or timeouts; for work that must outlive the request, use a queue or an explicit detached lifecycle context with its own timeout and wait or retry policy;
+   - configure trusted proxies before relying on `ClientIP()` for rate limits, admin allowlists, geo policy, audit, or abuse controls; do not trust client-supplied forwarding headers by default, and treat `ClientIP()` as an auxiliary signal rather than authentication;
+   - when using trusted platform headers, require an outer network boundary that prevents direct origin-server access. Strip client-supplied identity, scheme, host, and forwarding headers at the edge before reinjecting trusted values;
+   - review CORS as browser response exposure, not API authentication. Parse and compare Origin by scheme, host, and port; avoid substring checks, origin reflection with credentials, wildcard assumptions for credentialed requests, missing `Vary: Origin`, and exposure of internal request or response headers;
+   - keep cookie policy explicit: narrow domain, `Secure`, `HttpOnly`, `SameSite`, `Path`, and host-only behavior for session cookies. Do not derive cookie `Secure` from `c.Request.TLS` when TLS terminates before the Go process;
+   - treat logger query-string handling as a privacy boundary. Avoid logging tokens, emails, OAuth codes, magic links, redirect parameters, search terms, or payment callback data from query strings;
+   - make route wildcard, escaped-path, raw-path, unescape, trailing-slash redirect, fixed-path redirect, and method-not-allowed behavior explicit when identifiers, file paths, signed URLs, or reverse proxies can change path meaning;
+   - use `ShouldBind` variants instead of `Bind` or `MustBind` when the endpoint owns JSON error shape, status code, validation response, logging, or security behavior;
+   - pick the binding source deliberately: URI params, query, headers, form, multipart, and JSON body should not all feed one domain model or permission object through a vague auto-binding path;
+   - use request DTOs with explicit `json`, `form`, `uri`, and `header` tags and `binding` validator tags. Do not bind directly into database, ORM, or domain models that contain server-owned fields such as owner, role, status, plan, hash, or tenant ids;
+   - distinguish field presence from zero values for booleans, numbers, and optional strings. Use pointers, presence types, or custom validators when `false`, `0`, or empty string can be a valid submitted value;
+   - reject or explicitly account for unknown JSON fields, duplicate keys, large numeric identifiers, and `map[string]any` float conversion when the endpoint makes money, identity, permission, or audit decisions;
+   - if request bodies are read by logging, HMAC, audit, or multiple bind passes, set a route-appropriate size limit first and restore or share the bytes deliberately. Treat `ShouldBindBodyWith` as whole-body memory retention, not a free parser cache;
+   - treat `MaxMultipartMemory` as a memory buffering threshold, not a full upload size limit. Enforce total request size, verify content, discard client filenames, and use server-owned storage names.
+16. Check database integration from handlers when relevant:
+   - open `*sql.DB` once at process or application startup, inject the long-lived pool, and close it during shutdown, not per request;
+   - set `SetMaxOpenConns`, `SetMaxIdleConns`, `SetConnMaxLifetime`, and `SetConnMaxIdleTime` from database capacity, app instance count, and traffic shape instead of relying on unbounded defaults;
+   - pass request or operation context to `QueryContext`, `QueryRowContext`, `ExecContext`, `BeginTx`, and driver or ORM APIs that support it;
+   - close `Rows`, check `rows.Err()`, handle transaction commit and rollback paths explicitly, and keep query timeout, retry, and pool-wait observability visible;
+   - expose pool pressure through `DBStats` or local metrics when handler latency may be caused by connection waits rather than slow business code.
+17. Keep JSON contracts honest:
    - choose `omitempty` versus `omitzero` deliberately, especially for `time.Time`, numeric zero, boolean false, and optional fields;
    - use `SetEscapeHTML(false)` only when the JSON is not embedded into HTML and callers expect raw `<`, `>`, or `&`;
    - treat `encoding/json/v2` and `jsontext` as experimental unless the repository explicitly opts into the relevant experiment and migration tests.
-16. Check filesystem and network address helpers:
+18. Check filesystem and network address helpers:
    - use traversal-resistant root APIs when accepting user-controlled relative paths and the supported Go version provides them;
    - do not treat `filepath.Join` plus prefix checks as sufficient against symlinks and TOCTOU;
    - prefer `net/netip` for comparable IP addresses and map keys when supported;
    - use `net.JoinHostPort` instead of string formatting for host and port assembly so IPv6 works.
-17. Check runtime and deployment behavior when relevant:
+19. Check runtime and deployment behavior when relevant:
    - set `GOMEMLIMIT` or `debug.SetMemoryLimit` before tuning `GOGC` for container memory pressure, leaving headroom for non-Go memory such as cgo, mmap, and the kernel;
    - question manual `GOMAXPROCS` pins in containers on Go versions with container-aware defaults;
    - use PGO only with representative profiles and keep `default.pgo` ownership clear;
    - treat goroutine leak profiling, SIMD, JSON v2, and other experiments as opt-in evidence-gathering, not default production assumptions;
    - remember that `-race` only finds races on executed paths and carries significant overhead.
-18. Keep tests and benchmarks deterministic:
+20. For performance changes, measure before simplifying or optimizing:
+   - require profile or benchmark evidence before accepting a more complex hot-path change;
+   - inspect CPU, heap, allocation, goroutine, block, and mutex evidence according to the symptom instead of assuming CPU is the bottleneck;
+   - treat allocation reduction as GC-pressure reduction only when benchmark or profile evidence supports it;
+   - use escape-analysis findings to explain heap movement instead of assuming pointers are faster than values;
+   - use `sync.Pool` only for disposable temporary objects that may vanish at any time, not as a durable cache or lifecycle owner.
+21. Keep tests and benchmarks deterministic:
    - do not use elapsed real time to wait for goroutine progress; use explicit synchronization, owned lifecycle waits, fake time, `testing/synctest` when supported, or the repository's established concurrency test helper;
    - prefer `testing.B.Loop` for new benchmarks when the supported Go version allows it, and keep setup, cleanup, allocation measurement, and compiler optimization boundaries honest;
+   - compare benchmark changes across repeated runs and include `B/op` and `allocs/op` when allocation behavior is part of the claim;
    - use test artifact directories for files that should survive a test run only when the supported Go version and test invocation preserve artifacts; otherwise use the repository's existing temporary-file or golden-output policy;
    - for deterministic crypto tests, prefer the standard cryptographic test hook when the supported Go version provides it instead of overriding global readers in production code paths.
-19. Keep Go tools and modernization explicit:
+22. Keep Go tools and modernization explicit:
    - prefer the `tool` directive over `tools.go` pinning only when the repository's supported Go version allows it;
    - use `go fix` modernizers as reviewed migrations, not silent drive-by rewrites;
    - update code generators, schema generators, lint helpers, and reflection-heavy tooling for generic aliases, alias node behavior, and reflect iterator methods only with fixture coverage;
    - prefer standard-library helpers such as `min`, `max`, `clear`, `slices`, `maps`, and `cmp` over new local utility packages when the supported Go version allows them.
-20. If dependency metadata changes, keep module files and dependent tests synchronized. Do not raise the `go` directive, add toolchain requirements, change module path, or introduce direct dependencies unless the task requires it and the final report calls out the support impact.
-21. Choose configured verification intents that cover formatting, tests, race-sensitive behavior, lint, API drift, module drift, docs, and release metadata when available.
+23. If dependency metadata changes, keep module files and dependent tests synchronized:
+   - do not raise the `go` directive, add toolchain requirements, change module path, or introduce direct dependencies unless the task requires it and the final report calls out the support impact;
+   - treat `go.sum` as checksum evidence, not a package lockfile and not disposable noise;
+   - treat `replace`, especially local-path `replace`, as temporary main-module or workspace-only wiring unless the repository documents a release plan for it;
+   - verify vendor output is regenerated by a configured intent when vendoring is part of the repository contract;
+   - check private module settings before adding private import paths so module names do not leak through public proxy or checksum lookups.
+24. Choose configured verification intents that cover formatting, tests, race-sensitive behavior, lint, API drift, module drift, docs, and release metadata when available.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -166,7 +242,7 @@ Preserve Go package, module, API, error, context, concurrency, runtime, HTTP, JS
 - Package ownership and exported API impact are clear.
 - Context, goroutine, channel, and error ownership are explicit.
 - Go-version-gated syntax, standard-library APIs, runtime defaults, experiments, and module metadata are compatible with the repository's supported Go version.
-- HTTP timeout, proxy, JSON, filesystem, network address, runtime, test-time, benchmark, and tool decisions are explicit where touched.
+- HTTP timeout, graceful shutdown, proxy, Gin route and middleware order, error response ownership, recovery, access logging, CORS, cookie, trusted header, Gin context lifetime, binding, validation, database integration, JSON, filesystem, network address, runtime, profiling, test-time, benchmark, and tool decisions are explicit where touched.
 - Tests cover the changed behavior without sleeps as synchronization.
 - Module drift is reported when dependency verification cannot run.
 
@@ -194,7 +270,7 @@ For concurrency-sensitive changes, report whether a configured race or equivalen
 - If an iterator function ignores `yield` returning false, a pull iterator omits `stop`, or a channel is replaced by an iterator while concurrency or backpressure remains required, restore the ownership contract before accepting the change.
 - If a goroutine has no owner, stop condition, wait path, cancellation path, or error path, do not add it.
 - If a newer Go feature is useful but the repository's `go` directive or CI matrix is lower, keep a fallback, defer the change, or report the required version bump instead of sneaking in the feature.
-- If HTTP clients, servers, or proxies have no timeout or cancellation boundary, stop and make the missing policy explicit before calling the path production-ready.
+- If HTTP clients, servers, proxies, or Gin handlers have no timeout, cancellation, trusted-proxy, error response owner, recovery owner, log schema, CORS, cookie, trusted-header, context-lifetime, binding-source, body-size, database context, or middleware-order boundary, stop and make the missing policy explicit before calling the path production-ready.
 - If JSON tag changes alter omitted fields, zero values, HTML escaping, or experimental JSON behavior, treat the change as an API contract risk.
 - If a public error stops satisfying documented `errors.Is` or `errors.As` checks, restore the contract or report the breaking-change requirement.
 - If wrapping would expose a dependency error as public API, keep the dependency error internal or document the intentional contract.
@@ -206,7 +282,7 @@ For concurrency-sensitive changes, report whether a configured race or equivalen
 - Boundary checked
 - Package and API impact
 - Context/concurrency/error notes
-- Go version, runtime, HTTP, JSON, filesystem, benchmark, and tool notes when relevant
+- Go version, module/workspace, runtime, HTTP/shutdown, Gin route/middleware/error/recovery/logging/CORS/cookie/context/binding, database, JSON, filesystem, profiling, benchmark, and tool notes when relevant
 - Files changed
 - Command intents run
 - Skipped checks and reasons

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: 4
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: python-code-change
-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.
+description: Apply this skill when Python source, standard-library API usage, packaging, runtime version, import layout, architecture boundaries, type checking, async tasks, exception/logging/retry behavior, performance-sensitive collection usage, pytest fixtures/mocks, 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, standard-library, packaging, import, async resource, public API, typing, lint, and test boundaries while making a focused change.
+Preserve Python runtime, standard-library, packaging, import, architecture, async resource, failure, performance, 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 standard-library feature usage, 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, async task lifecycles, exceptions, logging, retry, fallback, collection performance, or tests.
 
 <!-- mustflow-section: do-not-use-when -->
 ## Do Not Use When
@@ -47,10 +47,13 @@ Preserve Python runtime, standard-library, packaging, import, async resource, pu
 
 - 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.
+- Packaging and dependency files, build backend, package manager, lockfile owner, 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.
+- Architecture boundary: external adapters, framework request/response objects, ORM models, environment input, DTOs, domain value objects, import direction, and shared utility ownership.
 - Async ownership and resource cleanup surface when coroutines, tasks, context managers, sessions, clients, pools, files, async generators, subprocesses, or logging change.
+- Failure surface when exceptions, logging config, retry, timeout, fallback, degraded responses, or observability fields change.
 - Public contract surface when imports, signatures, exceptions, return shapes, CLI behavior, config, environment variables, extras, Python version support, or typing stubs change.
+- Runtime truth boundary for type hints: external input validation, `Any`, casts, ignores, protocols, guards, stubs, and `py.typed` when present.
 - Configured verification intents.
 
 <!-- mustflow-section: preconditions -->
@@ -59,6 +62,7 @@ Preserve Python runtime, standard-library, packaging, import, async resource, pu
 - 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.
+- Read framework, adapter, or entry-point boundaries before moving data shapes across layers.
 - Treat global machine Python state as irrelevant unless the project explicitly declares it.
 
 <!-- mustflow-section: allowed-edits -->
@@ -70,61 +74,107 @@ Preserve Python runtime, standard-library, packaging, import, async resource, pu
 - Do not lower Ruff, mypy, pyright, pytest, or packaging strictness to hide a failure.
 - Keep import fixes in package metadata, package discovery, entry points, or test invocation contracts instead of path hacks.
 - Make resource ownership explicit: code closes only the resources it creates.
+- Translate external data and third-party failures at boundaries instead of leaking framework, SDK, ORM, raw JSON, or environment shapes into domain logic.
 
 <!-- mustflow-section: procedure -->
 ## Procedure
 
 1. Read project metadata, Python version constraints, dependency files, and test/lint/type configs.
-2. Identify the boundary touched: runtime version, package API, import root, packaging metadata, CLI entry, test fixture, async resource ownership, external input, or dependency contract.
+2. Identify the boundary touched: runtime version, package API, import root, packaging metadata, architecture layer, CLI entry, test fixture, async resource ownership, external input, exception/logging/retry path, performance-sensitive collection path, or dependency contract.
 3. For packaging and import changes, separate the distribution name from the import package name. Check package directory mapping, package discovery settings, namespace package behavior, package data, entry points, optional dependencies, and `requires-python` before touching imports.
-4. Treat `src` layout as an installation contract. Importable code under `src/` should be tested through the supported installed-package path, not by making repository files accidentally importable from the working directory.
-5. Match existing package layout and import conventions. Do not add `sys.path`, `site.addsitedir`, `PYTHONPATH`, pytest `pythonpath`, ad hoc import loading, or test `conftest.py` import hacks to make package imports pass.
-6. Do not add `__init__.py` to tests as a blind fix. Add it only when tests are intentionally a package and the import-mode behavior remains explicit.
-7. For packaging changes, distinguish development and release contracts:
+4. For `pyproject.toml`, keep build metadata, package metadata, and tool settings separate:
+   - `[build-system]` names the build backend and build requirements;
+   - `[project]` names distribution metadata, runtime dependencies, Python support, scripts, optional dependencies, and package typing signals;
+   - `[tool.*]`, dependency groups, uv or Poetry settings, and lockfiles are tool or environment contracts, not a substitute for wheel metadata.
+5. Treat `src` layout as an installation contract. Importable code under `src/` should be tested through the supported installed-package path, not by making repository files accidentally importable from the working directory.
+6. Match existing package layout and import conventions. Do not add `sys.path`, `site.addsitedir`, `PYTHONPATH`, pytest `pythonpath`, ad hoc import loading, or test `conftest.py` import hacks to make package imports pass.
+7. Do not add `__init__.py` to tests as a blind fix. Add it only when tests are intentionally a package and the import-mode behavior remains explicit.
+8. For packaging changes, distinguish development and release contracts:
    - editable installs prove the local development path;
    - wheel installs or equivalent built artifacts prove the release path;
+   - editable installs may not reflect entry point, dependency, package metadata, C extension, or package data changes until reinstall or rebuild;
+   - build dependencies, runtime dependencies, optional dependencies, and dependency groups are different contracts;
+   - apps should pin or lock environments; libraries should publish compatible dependency ranges instead of over-pinning downstream users;
+   - uv, Poetry, pip, and build backends each own different parts of the workflow; do not mix their metadata as competing sources of truth;
    - entry point, dependency, optional dependency, metadata, and package data changes require reinstall-oriented verification when a configured intent exists;
    - 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. Choose standard-library helpers by semantic contract and supported Python version:
+9. 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.
+10. Preserve architecture boundaries:
+   - keep framework request objects, ORM models, SDK clients, raw JSON, environment variables, and CLI parser output in adapter layers;
+   - convert external input into explicit DTOs, dataclasses, value objects, or validated models before domain logic uses it;
+   - name modules by responsibility instead of dumping shared behavior into `utils.py`, `helpers.py`, or `common.py`;
+   - keep import direction one-way and treat circular imports as architecture evidence, not only a runtime nuisance;
+   - prefer protocols or narrow callable/data contracts over inheritance when callers only need behavior shape.
+11. Validate unknown external data before treating it as typed domain data. Type hints do not enforce runtime values; boundary validation owns JSON, form, CSV, queue, environment, and third-party API input.
+12. Keep type-checking honest:
+   - treat `Any`, bare generics, untyped imports, `cast`, broad `type: ignore`, false `TypeGuard` or `TypeIs`, and runtime `Protocol` checks as trust-boundary risks;
+   - prefer `object` plus narrowing over `Any` when a value is unknown but operations must be checked;
+   - require scoped `# type: ignore[...]` with a local reason when the project policy allows ignores;
+   - do not use `cast()` as conversion; add parsing, validation, or a checked adapter when runtime shape is uncertain;
+   - keep `None` explicit in signatures and return shapes instead of returning `None` from non-optional contracts;
+   - when publishing typed packages, keep `py.typed`, stubs, and public exports aligned.
+13. 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. Treat newer syntax and typing features as semantic tools, not style trophies:
+14. Review collection and iterator performance when code can scale with input size:
+   - avoid list membership inside large loops, `pop(0)`, repeated list concatenation, large loop slices, and hot-path `deepcopy`;
+   - use `set`, `dict`, `deque`, `Counter`, `heapq`, `join`, comprehensions, or `itertools` when they match the data contract;
+   - treat generators as one-shot streams; do not add hidden `list()`, `sorted()`, `len()`, `tee()`, or `cycle()` materialization without memory reasoning;
+   - rebuild large dicts after bulk deletion when long-lived memory and iteration cost matter;
+   - avoid eager default factories hidden in `dict.get(key, expensive())` or `setdefault(key, expensive())`.
+15. Treat newer syntax and typing features as semantic tools, not style trophies:
    - use template string literals only when a handler needs the static and interpolated parts separately, such as SQL builders, shell command objects, logging templates, or markup renderers; do not replace ordinary f-strings when the result is just a string;
    - when runtime code reads annotations, use the supported annotation inspection API and choose the intended format explicitly instead of assuming `__annotations__` already contains runtime values;
    - use sentinel values to distinguish "argument omitted" from `None`, but compare sentinels by identity and keep public signatures readable;
    - prefer `Mapping` or narrower read-only protocols for read-only inputs so immutable mapping implementations are not rejected accidentally;
    - use closed or extra-key `TypedDict` forms only when the supported Python and type-checker versions agree with that shape.
-12. Keep `finally` as cleanup, not outcome selection. Do not add `return`, `break`, or `continue` inside `finally` blocks because they can mask exceptions and cancellation; move result decisions outside cleanup or make suppression an explicit documented contract.
-13. Use explicit lazy imports only for startup-sensitive module-scope dependencies after checking version support and import-time side effects. Do not lazily import plugins, registries, monkey patches, model definitions, ORM mappings, or observability setup whose import side effects are part of startup correctness.
-14. Keep process, archive, and concurrency safety explicit:
+16. Keep `finally` as cleanup, not outcome selection. Do not add `return`, `break`, or `continue` inside `finally` blocks because they can mask exceptions and cancellation; move result decisions outside cleanup or make suppression an explicit documented contract.
+17. Use explicit lazy imports only for startup-sensitive module-scope dependencies after checking version support and import-time side effects. Do not lazily import plugins, registries, monkey patches, model definitions, ORM mappings, or observability setup whose import side effects are part of startup correctness.
+18. 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.
-15. 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.
-16. Preserve async and resource ownership:
+19. 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.
+20. 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;
    - cancellation is control flow, so cleanup uses `finally` and cancellation is re-raised after cleanup unless suppression is the documented behavior;
+   - choose `TaskGroup` over `gather()` when sibling task failure must cancel the rest;
+   - bound fan-out with semaphores, queues, worker pools, or an existing local concurrency primitive;
+   - propagate absolute deadlines or remaining budgets through nested calls instead of resetting relative timeouts at every layer;
+   - cancel and await pending tasks after `asyncio.wait()` timeouts;
    - async functions do not call blocking I/O, blocking sleeps, long CPU work, or blocking subprocess waits directly unless the project has an explicit executor or isolation pattern;
    - 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.
-17. Preserve traceback evidence. Logging inside exception handlers should retain exception information instead of logging only the exception message.
-18. Preserve public contracts:
+21. Preserve failure evidence:
+   - translate external exceptions into domain exceptions at boundaries with `raise ... from exc`;
+   - do not use `except Exception: pass`, broad `BaseException` catches, or fallback returns that hide failures;
+   - use `logger.exception()` only inside exception handlers or preserve exception info explicitly;
+   - configure logging so module loggers propagate through a deliberate root or parent handler, existing loggers are not disabled accidentally, and slow handlers are isolated when request latency matters;
+   - keep retry finite, jittered or backed off where appropriate, idempotent, and owned by one layer;
+   - make fallback a visible degraded path with logs, metrics, or response metadata rather than silent success.
+22. 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.
-19. Avoid mutable default arguments, broad `except Exception: pass`, broad `BaseException` catches outside process boundaries, global state hidden behind module imports, `finally` masking, and path handling that ignores existing `pathlib` or OS conventions.
-20. Use `# type: ignore[...]` only when tightly scoped, justified, and consistent with local policy.
-21. 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.
-22. Choose configured verification intents that cover formatting, lint, type checking, tests, package build, installed-package smoke checks, and CLI smoke risk when available.
+23. Preserve test truth:
+   - keep pytest fixtures small, with one state-changing responsibility and cleanup coupled to that state;
+   - treat fixture scope and autouse as isolation decisions, not speed knobs;
+   - avoid mutable `parametrize` values unless each case receives a fresh object;
+   - use `tmp_path`, scoped `monkeypatch`, and patch the namespace where code looks up the object;
+   - prefer mock `autospec`, `spec_set`, and `AsyncMock` await assertions so tests cannot lie about signatures or async execution;
+   - use log assertions to check operational signals, not only message text;
+   - use property-based tests when behavior is an invariant over an input space and existing project dependencies support it.
+24. Avoid mutable default arguments, broad `except Exception: pass`, broad `BaseException` catches outside process boundaries, global state hidden behind module imports, `finally` masking, and path handling that ignores existing `pathlib` or OS conventions.
+25. Use `# type: ignore[...]` only when tightly scoped, justified, and consistent with local policy.
+26. If packaging, public API, CLI, config, typing, async, retry, logging, or test contracts change, synchronize README examples, entry point tests, build metadata, docs, fixtures, and downstream-style examples that describe installation or usage.
+27. 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
@@ -133,10 +183,14 @@ Preserve Python runtime, standard-library, packaging, import, async resource, pu
 - 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.
+- Framework, ORM, SDK, raw input, and environment data stay outside the domain core unless intentionally adapted.
+- Runtime validation, type hints, and published typing metadata agree at public and external-input boundaries.
 - Async tasks, context managers, files, clients, pools, subprocesses, and generators have visible ownership and cleanup.
+- Exceptions, logs, retries, timeouts, and fallback paths preserve cause, deadline, idempotency, and degraded-state evidence.
+- Collection and iterator changes have size, copy, and materialization behavior reviewed when relevant.
 - Public API, CLI, config, environment, dependency metadata, and typing contract changes are called out.
 - Type and lint strictness are not weakened.
-- Tests or skipped verification are tied to the changed behavior.
+- Tests or skipped verification are tied to the changed behavior, with fixture/mock/async/logging risks named when relevant.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -158,13 +212,18 @@ Report missing package, type, or test intents rather than inventing raw tool com
 - If import resolution fails, inspect package metadata and test invocation before adding path hacks.
 - 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 build backend, package manager, lockfile, dependency group, optional dependency, or editable-install behavior is ambiguous, keep the existing owner and report the missing packaging contract instead of migrating tools.
 - 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 template strings, annotation runtime access, lazy imports, sentinels, immutable mappings, or typed extra keys are useful but version-gated, keep a fallback or report the required support bump instead of smuggling the newer feature into a lower-runtime project.
 - If third-party stubs or package metadata are wrong, document the local workaround and keep it narrow.
+- If `Any`, `cast`, `type: ignore`, runtime `Protocol`, or type guard behavior is needed, keep it local, justified, and backed by runtime validation or tests where the type claim can lie.
+- If performance risk appears in collections, generators, copies, or caches, report the input-size assumption or use an existing benchmark/profile intent when configured.
 - 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.
+- If retry, timeout, or fallback lacks idempotency, deadline, owner layer, or degraded-state evidence, keep the failure explicit instead of adding hidden recovery.
 - If resource cleanup cannot be proven, use the project's context manager, exit stack, fixture, or lifecycle pattern before broadening tests.
+- If tests require broad fixtures, autouse state, unscoped monkeypatching, bare mocks, or mutable parametrization, narrow the test seam before trusting the result.
 - If public contracts change without compatibility evidence, stop and report the breaking-change or deprecation requirement.
 
 <!-- mustflow-section: output-format -->
@@ -173,7 +232,7 @@ Report missing package, type, or test intents rather than inventing raw tool com
 - Boundary checked
 - Runtime and packaging assumptions
 - Files changed
-- Type, lint, and import notes
+- Architecture, type, lint, import, async, failure, performance, and test notes
 - Command intents run
 - Skipped checks and reasons
 - Remaining Python risk

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

@@ -36,6 +36,12 @@ route_type = "primary"
 priority = 40
 applies_to_reasons = ["code_change", "behavior_change"]
 
+[routes."split-refactor-residual-path-review"]
+category = "architecture_patterns"
+route_type = "adjunct"
+priority = 79
+applies_to_reasons = ["unknown_change", "code_change", "behavior_change", "test_change", "public_api_change", "performance_change", "ui_change", "data_change"]
+
 [routes."composition-over-inheritance"]
 category = "architecture_patterns"
 route_type = "primary"
@@ -526,7 +532,7 @@ applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "pe
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "ui_change", "package_metadata_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "ui_change", "performance_change", "package_metadata_change", "release_risk"]
 
 [routes."javascript-code-change"]
 category = "general_code"
@@ -538,7 +544,7 @@ applies_to_reasons = ["code_change", "public_api_change", "test_change"]
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "data_change", "migration_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
 
 [routes."powershell-code-change"]
 category = "general_code"
@@ -550,13 +556,13 @@ applies_to_reasons = ["code_change", "test_change", "docs_change", "package_meta
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "data_change", "performance_change", "package_metadata_change", "release_risk"]
 
 [routes."rust-code-change"]
 category = "general_code"
 route_type = "primary"
 priority = 85
-applies_to_reasons = ["code_change", "public_api_change", "test_change"]
+applies_to_reasons = ["code_change", "behavior_change", "public_api_change", "test_change", "docs_change", "data_change", "performance_change", "security_change", "privacy_change", "package_metadata_change", "release_risk"]
 
 [routes."axum-code-change"]
 category = "general_code"
@@ -990,6 +996,12 @@ route_type = "adjunct"
 priority = 80
 applies_to_reasons = ["ui_change", "behavior_change", "code_change", "performance_change", "data_change", "test_change", "public_api_change"]
 
+[routes."ui-state-resurrection-review"]
+category = "ui_assets"
+route_type = "adjunct"
+priority = 83
+applies_to_reasons = ["unknown_change", "ui_change", "behavior_change", "code_change", "performance_change", "data_change", "test_change", "public_api_change", "docs_change", "package_metadata_change", "release_risk"]
+
 [routes."frontend-stress-layout-review"]
 category = "ui_assets"
 route_type = "adjunct"