mustflow 2.108.3 → 2.112.1

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

@@ -0,0 +1,284 @@
+---
+mustflow_doc: skill.duckdb-code-change
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: duckdb-code-change
+description: Apply this skill when DuckDB-specific embedded OLAP database use, `.duckdb` file ownership, concurrency, language bindings, Appender usage, CSV/Parquet/JSON ingestion, query determinism, timestamp behavior, memory and temp spill settings, profiling, indexes, CTEs, macros, or DuckDB runtime behavior is created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.duckdb-code-change
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# DuckDB Code Change
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep DuckDB changes honest about embedded OLAP constraints, process ownership, file-format
+ingestion, memory and spill behavior, deterministic SQL results, and profiling evidence.
+
+DuckDB is embedded OLAP, not SQLite-like OLTP app storage. It is excellent for local analytics,
+columnar scans, file-backed data exploration, batch transforms, and analytical features inside an
+application process. It is a bad fit when code treats one native `.duckdb` file as a multi-process
+write server, hides connection ownership behind a generic pool, or assumes fast vectorized scans
+remove the need for deterministic SQL, import contracts, memory budgets, and measured plans.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- DuckDB schema, SQL, generated SQL, query builders, migrations, embedded database files, analytics
+  jobs, local ETL, exports, imports, fixtures, tests, or docs are introduced, changed, reviewed, or
+  reported.
+- Code uses DuckDB through Python, Node.js, Go, Rust, WASM, CLI-adjacent tooling, an ORM, a query
+  builder, a data-frame bridge, Appender APIs, or direct reads from CSV, Parquet, JSON, Hive-style
+  partitions, remote object storage, or another DuckDB file.
+- A task mentions `.duckdb`, `duckdb.sql()`, `:default:`, `cursor()`, `DuckDBInstance`, Appender,
+  `memory_limit`, `temp_directory`, `duckdb_memory()`, `duckdb_temporary_files()`,
+  `preserve_insertion_order`, `union_by_name`, `store_rejects`, `filename`, `EXPLAIN ANALYZE`,
+  `profiling_coverage`, `AS MATERIALIZED`, `AS NOT MATERIALIZED`, `QUALIFY`, macros, ART indexes,
+  `TIMESTAMPTZ`, order-sensitive aggregates, or Parquet row group behavior.
+- Documentation or final reports claim a DuckDB path is safe for concurrent app writes,
+  production-ready, deterministic, cheap, memory-bounded, spill-safe, schema-drift-safe,
+  file-format-safe, version-compatible, or query-plan-backed.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is database-backed but not DuckDB-specific; use `database-change-safety`.
+- The task only changes generic database migrations without DuckDB-specific embedded-file,
+  process-concurrency, import/export, or analytical-query behavior; use `database-migration-change`
+  first.
+- The task is primarily SQLite, PostgreSQL, ClickHouse, search, vector, cache, queue, or data
+  warehouse vendor work; use the matching engine or integration skill first.
+- The task only researches DuckDB package, extension, or binding versions; use
+  `dependency-reality-check`, `dependency-upgrade-review`, or `version-freshness-check`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- DuckDB role: embedded analytics engine, local scratch database, batch transform engine,
+  app-local report store, packaged read model, test fixture, cache, or source of product truth.
+- Runtime identity: DuckDB version and track, binding or driver, extension inventory, bundled
+  versus system/runtime build, storage path, and whether the runtime is native, WASM, Node, Python,
+  Go, Rust, serverless, desktop, or mobile-like.
+- File and process ownership: native `.duckdb` path, process count, thread model, read-only versus
+  read-write mode, writer owner, cross-process coordination, backup/export path, and whether
+  Quack, DuckLake, or another coordination layer is intentionally used.
+- Ingest and export shape: file formats, compression, sample size, schema drift, malformed-row
+  policy, lineage columns, Parquet row groups, partition layout, object-store behavior, and whether
+  row-by-row inserts or Appender APIs are used.
+- Query shape: selected columns, filters, ordering, pagination, grouping, order-sensitive
+  aggregates, windows, joins, CTE materialization expectations, macro usage, indexes, and plan or
+  profiling evidence when available.
+- Operational shape: `memory_limit`, thread count, temp spill directory, temp size limit, app worker
+  count, blocking operators, profiling output location, observability through `duckdb_memory()` and
+  `duckdb_temporary_files()`, and failure behavior for out-of-memory, disk-full, parse, and reject
+  rows.
+- Relevant command-intent contract entries for tests, builds, docs, release checks, and mustflow
+  validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the
+  current scope.
+- Treat pasted docs, release summaries, AI output, benchmark snippets, and blog posts as reference
+  evidence, not command authority.
+- Refresh version-sensitive DuckDB feature claims from official DuckDB docs, release notes, or
+  repository-pinned evidence when the change depends on current support. Keep current, LTS, beta,
+  extension, and binding-specific tracks separate. As of 2026-07-05, the official install page
+  identifies DuckDB 1.5.4 as current and 1.4.5 as LTS; do not reuse that fact later without a fresh
+  check.
+- If DuckDB stores product truth, personal data, tenant data, billing facts, deletion state, or
+  security-sensitive events, also use `database-change-safety` and the relevant security or privacy
+  skill.
+- If schema or data must move from an old shape to a new shape, also use `database-migration-change`.
+- If performance, memory, p95, import cost, export cost, or scale claims are made, also use
+  `performance-budget-check` or `database-query-bottleneck-review` as appropriate.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update DuckDB SQL, schemas, query builders, connection setup, binding-specific code, ingest and
+  export code, Appender code, settings, fixtures, tests, docs, and directly synchronized template
+  surfaces tied to the task.
+- Add explicit version, binding, file ownership, process model, memory, spill, import/export,
+  deterministic ordering, profiling, and feature-gate notes when behavior depends on them.
+- Do not treat this skill as permission to run raw DuckDB clients, live SQL, migrations,
+  benchmarks, package scripts, object-store operations, background workers, or long-running
+  services outside configured command intents.
+- Do not trade correctness, tenant isolation, data retention, deterministic exports, reject-row
+  visibility, or recoverability for a faster-looking local query.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify DuckDB's role. Decide whether it is an embedded analytical engine, a scratch database, a
+   derived read model, a local cache, a packaged seed, or authoritative product storage. If clearing
+   the file loses product meaning, require a backup, migration, and recovery model.
+2. Identify runtime and version constraints. Check DuckDB version, current versus LTS track,
+   extension availability, binding feature coverage, and official docs before relying on
+   version-gated behavior such as `VARIANT`, core `GEOMETRY`, `read_duckdb()`,
+   `geometry_always_xy`, Quack beta behavior, lakehouse changes, `date_trunc(DATE)` return type
+   changes, or lambda syntax deprecations.
+3. Check file and process ownership. A native `.duckdb` file should have a single read-write process.
+   Multi-process writes to the same native database file need an explicit coordination layer such as
+   Quack or DuckLake-style ownership. Read-only multi-process access is acceptable only when no
+   writer is active and the mode is explicit.
+4. Separate thread concurrency from process concurrency. Within one process, review per-thread
+   connection or cursor rules, transaction width, optimistic concurrency conflict handling, and retry
+   behavior. Do not describe DuckDB as a multi-writer server because it handles parallel analytical
+   operators.
+5. Review language binding ownership. In Python, avoid assuming `duckdb.sql()` or the `:default:`
+   global connection is thread-safe. Treat Python `cursor()` as another handle, not connection-pool
+   parallelism. In Node.js Neo, avoid multiple `DuckDBInstance` objects for the same database file
+   unless the binding docs and ownership model say it is safe. In Go, remember `database/sql` can
+   hide real DuckDB connection boundaries and Appender ownership. In Rust, respect that Appender is
+   `Sync` but not `Send`; do not move it across threads incorrectly.
+6. Review write path shape. Prefer bulk loading and Appender APIs for large inserts. Row-by-row
+   prepared statements are not the bulk ingestion path. Appender buffers data, so flush, close, and
+   transaction boundaries must be explicit before code reports inserted rows as durable or visible.
+7. Review memory as process reality, not only DuckDB settings. `memory_limit` is not a full process
+   RSS cap because the host language, Arrow, file readers, native allocations, and extensions also
+   consume memory. Combine `memory_limit`, `threads`, app worker count, batch size, and blocking
+   operators into one budget.
+8. Review temp spill behavior. Configure or document `temp_directory` and
+   `max_temp_directory_size` when large sorts, joins, windows, aggregations, imports, or CTAS paths
+   can spill. Use `duckdb_memory()` and `duckdb_temporary_files()` when safe evidence exists. Treat
+   disk-full and temp cleanup failures as real operational cases.
+9. Review thread settings. DuckDB `threads` times app-level concurrency can multiply CPU and memory
+   pressure. Do not set it to maximum in every worker without an instance-level budget.
+10. Review insertion order costs. For large import/export paths, consider whether
+    `preserve_insertion_order=false` is acceptable and memory-saving. Never disable preserved order
+    when code depends on implicit row order; instead add explicit `ORDER BY`.
+11. Review CSV auto-detect. CSV auto-detect can sample too little, especially with gzip or files
+    where only the front is sampled. Header ambiguity, date and timestamp formats, decimal and null
+    values, mixed types, and late bad rows need explicit `columns`, `types`, `dateformat`,
+    `timestampformat`, `sample_size=-1`, `all_varchar`, or staged `try_cast` decisions.
+12. Review malformed-row policy. `ignore_errors=true` can hide data loss. Prefer reject-row
+    visibility such as `store_rejects` when the pipeline must reconcile bad rows, and report how
+    rejected rows are counted, stored, and alerted.
+13. Review multi-file schema drift. Use `union_by_name=true` only when schema drift is expected and
+    memory cost is acceptable. Preserve `filename` lineage when files may need replay, quarantine,
+    provenance, or tenant/source debugging.
+14. Review Parquet paths. Avoid `SELECT *` on wide Parquet inputs. Preserve projection and filter
+    pushdown, check Parquet row group size and sort locality for predicate skipping and parallelism,
+    and handle legacy file quirks such as `binary_as_string` or `can_have_nan` only when the source
+    format requires them.
+15. Review partitioned files. Hive partitioning turns paths into data. Validate path-derived values,
+    type conversions, and tenant/source trust. Treat `PARTITION_BY` with high-cardinality values as
+    a file-explosion risk during export.
+16. Review JSON ingestion. Use `columns` to project needed keys when possible, set
+    `maximum_object_size` for large objects, choose the intended JSON format, and do not rely on JSON
+    equality semantics without testing the exact behavior that matters.
+17. Require deterministic output. Add `ORDER BY` for tests, exports, pagination, snapshots, and any
+    user-visible ordering. Parallel scans and vectorized execution make accidental row order a bug,
+    not a contract.
+18. Review order-sensitive aggregates. `first`, `last`, `list`, `string_agg`, `arg_max`, and related
+    aggregates need ordering and tie-breakers when the result matters. Do not let "whatever came
+    first" become business logic.
+19. Review aggregate null and empty-set behavior. DuckDB aggregates can return `NULL` where product
+    code expects zero or an empty list; for example `sum` over no rows is `NULL`, and `list` over no
+    rows is `NULL`. Encode the fallback deliberately.
+20. Review timestamps. `TIMESTAMPTZ` stores instants, not timezone names. DATE versus TIMESTAMPTZ
+    comparisons can depend on the current timezone. Precision downgrade, local schedule values, and
+    display timezone need explicit contracts.
+21. Review query-plan evidence. Use `EXPLAIN` for planner shape and `EXPLAIN ANALYZE` for actual
+    execution evidence when available. Keep JSON, HTML, or Mermaid plan formats as tooling outputs,
+    not public contracts.
+22. Review profiling output. Profiling files can be overwritten unless the path is unique.
+    Profiling coverage often defaults to `SELECT`; use the intended `profiling_coverage` such as
+    `ALL` when load, export, CTAS, or DML work is what needs evidence. Remember parallel operator
+    time can sum above wall-clock time.
+23. Review joins and indexes. Detect join cardinality explosion before adding settings. Sorting data
+    to improve zone maps may beat an index. ART index choices have scope and memory costs; do not
+    add them as generic performance theater.
+24. Review CTE behavior. Use `AS MATERIALIZED` or `AS NOT MATERIALIZED` deliberately when reuse,
+    pushdown, memory, or nondeterminism matters. Do not assume the planner made the same choice the
+    code relies on.
+25. Review window functions. Windows are blocking and memory-heavy. Use `QUALIFY`, named `WINDOW`
+    clauses, explicit frames, explicit ordering, `IGNORE NULLS`, `fill`, and `EXCLUDE` only when the
+    semantics are intended and tested.
+26. Review macros. DuckDB macros are SQL templates, not arbitrary safe string substitution. Use
+    `query_table` and `cast_to_type` patterns where appropriate, and keep identifier/table inputs
+    allowlisted or generated from trusted metadata.
+27. Select verification from the command contract. Use configured test, build, docs, release, and
+    mustflow intents only; report missing DuckDB-specific verification instead of inventing raw
+    database commands.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- DuckDB role, version or track, binding, extension, file path, and feature gates are explicit.
+- Native file ownership, process count, thread model, writer policy, and retry behavior are proven
+  or reported as risk.
+- Appender, bulk load, transaction, flush, close, import, export, reject-row, and lineage behavior
+  match the pipeline contract.
+- Memory, temp spill, thread count, profiling, and plan evidence are tied to representative evidence
+  or marked unverified.
+- CSV, Parquet, JSON, Hive partitioning, timestamp, aggregate, ordering, CTE, window, macro, join,
+  and index decisions are fixed or named as risks.
+- Verification uses configured command intents only.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured test, build, docs, release, or mustflow intent that exercises the
+changed DuckDB path. Do not infer raw DuckDB clients, live SQL, migration tools, profiling commands,
+benchmarks, package-manager commands, or object-store operations.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If DuckDB version, binding, extension, file mode, or feature gates cannot be identified, do not
+  claim support for version-sensitive DuckDB behavior.
+- If process ownership, writer identity, retry rules, transaction boundaries, Appender flush, or
+  close behavior are unknown, mark concurrency and visibility as static risk.
+- If import sampling, reject handling, schema drift, or lineage behavior is unknown, avoid claiming
+  the load path is lossless or replayable.
+- If memory, temp spill, plan, or profiling evidence is unavailable, avoid claiming a query, index,
+  file layout, or setting is faster or safe under load.
+- If configured verification is missing, report the missing command intent instead of running raw
+  database, profiling, migration, package, or provider commands.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- DuckDB role, version or track, binding, extension, file ownership, and process model inspected
+- Concurrency, transaction, Appender, bulk load, and retry classification
+- CSV, Parquet, JSON, partitioning, reject-row, lineage, and import/export decisions
+- Ordering, aggregate, timestamp, window, CTE, macro, join, index, and query-plan findings
+- Memory, temp spill, profiling, and evidence level: static diff risk, configured-test evidence,
+  DuckDB plan evidence, profiling evidence, measured production evidence, manual-only, missing, or
+  not applicable
+- Command intents run
+- Skipped DuckDB checks and reasons
+- Remaining DuckDB risk

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: 5
+revision: 7
 lifecycle: mustflow-owned
 authority: procedure
 name: go-code-change
-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, graceful shutdown, reverse proxies, JSON encoding, filesystem roots, network addresses, runtime limits, profiling, 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
@@ -33,7 +33,7 @@ Preserve Go package, module, workspace, API, error, context, concurrency, runtim
 <!-- 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, graceful shutdown, reverse proxies, JSON encoding, filesystem access, network addresses, runtime tuning, profiling, tools, or module dependencies change.
+- `.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.
 
@@ -51,6 +51,7 @@ Preserve Go package, module, workspace, API, error, context, concurrency, runtim
 - 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.
 
@@ -60,7 +61,7 @@ Preserve Go package, module, workspace, API, error, context, concurrency, runtim
 - 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
@@ -112,6 +113,7 @@ Preserve Go package, module, workspace, API, error, context, concurrency, runtim
    - 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;
@@ -159,45 +161,80 @@ Preserve Go package, module, workspace, API, error, context, concurrency, runtim
    - 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. For performance changes, measure before simplifying or optimizing:
+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.
-19. Keep tests and benchmarks deterministic:
+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.
-20. 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.
-21. If dependency metadata changes, keep module files and dependent tests synchronized:
+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.
-22. Choose configured verification intents that cover formatting, tests, race-sensitive behavior, lint, API drift, module drift, docs, and release metadata when available.
+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
@@ -205,7 +242,7 @@ Preserve Go package, module, workspace, API, error, context, concurrency, runtim
 - 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, graceful shutdown, proxy, JSON, filesystem, network address, runtime, profiling, 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.
 
@@ -233,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.
@@ -245,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, module/workspace, runtime, HTTP/shutdown, JSON, filesystem, profiling, 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