claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/stack-agents/go/references/performance-profiling.md

@@ -0,0 +1,250 @@
+# Performance Profiling
+
+> Reference document for go-performance-reviewer. Loaded on demand via Read tool.
+
+## pprof Workflow
+
+### Setup
+
+```go
+import _ "net/http/pprof" // register handlers on DefaultServeMux
+
+func main() {
+    // Option 1: Separate debug server
+    go func() {
+        log.Println(http.ListenAndServe("localhost:6060", nil))
+    }()
+
+    // Option 2: Add to existing mux (Go 1.22+ enhanced ServeMux)
+    mux.HandleFunc("GET /debug/pprof/", pprof.Index)
+    mux.HandleFunc("GET /debug/pprof/cmdline", pprof.Cmdline)
+    mux.HandleFunc("GET /debug/pprof/profile", pprof.Profile)
+    mux.HandleFunc("GET /debug/pprof/symbol", pprof.Symbol)
+    mux.HandleFunc("GET /debug/pprof/trace", pprof.Trace)
+}
+```
+
+### Profile Types
+
+| Profile | URL / Flag | What It Shows |
+|---------|-----------|---------------|
+| CPU | `/debug/pprof/profile?seconds=30` | Where CPU time is spent |
+| Heap | `/debug/pprof/heap` | Current memory allocations |
+| Allocs | `/debug/pprof/allocs` | All past allocations (even freed) |
+| Goroutine | `/debug/pprof/goroutine` | All goroutine stacks |
+| Block | `/debug/pprof/block` | Where goroutines block on sync |
+| Mutex | `/debug/pprof/mutex` | Mutex contention |
+| Threadcreate | `/debug/pprof/threadcreate` | OS thread creation |
+
+### Collection and Analysis
+
+```bash
+# Collect CPU profile (30 seconds)
+go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30
+
+# Collect heap profile
+go tool pprof http://localhost:6060/debug/pprof/heap
+
+# Interactive commands
+(pprof) top 20          # top 20 functions by cost
+(pprof) list funcName   # source-level annotation
+(pprof) web             # open flame graph in browser
+(pprof) peek funcName   # callers and callees
+
+# From test
+go test -cpuprofile cpu.prof -memprofile mem.prof -bench .
+go tool pprof cpu.prof
+```
+
+## benchstat Workflow
+
+Statistically rigorous benchmark comparison.
+
+```bash
+# Run benchmarks with multiple iterations
+go test -bench=BenchmarkProcess -count=6 -benchmem > old.txt
+
+# Make changes, then run again
+go test -bench=BenchmarkProcess -count=6 -benchmem > new.txt
+
+# Compare
+benchstat old.txt new.txt
+```
+
+**Output interpretation:**
+
+```
+name          old time/op    new time/op    delta
+Process-8     12.3ms ± 2%    8.7ms ± 1%   -29.27%  (p=0.002 n=6+6)
+
+name          old alloc/op   new alloc/op   delta
+Process-8     4.80kB ± 0%    1.20kB ± 0%   -75.00%  (p=0.002 n=6+6)
+
+name          old allocs/op  new allocs/op  delta
+Process-8       45.0 ± 0%      12.0 ± 0%   -73.33%  (p=0.002 n=6+6)
+```
+
+| Field | Meaning |
+|-------|---------|
+| `± N%` | Variation across runs (lower = more stable) |
+| `delta` | Percentage change (negative = improvement) |
+| `p=0.002` | p-value: < 0.05 means statistically significant |
+| `n=6+6` | Sample sizes used |
+
+**Rules:**
+- Always use `-count=6` or higher (minimum for statistical significance)
+- If `p > 0.05`, the change is not statistically significant — don't claim improvement
+- Run on quiet machine, no other CPU-heavy processes
+- Use `-benchtime=2s` for fast benchmarks to get stable numbers
+
+## Escape Analysis
+
+Understand what allocates on the heap vs stack.
+
+```bash
+go build -gcflags="-m" ./...
+go build -gcflags="-m -m" ./... # more verbose
+```
+
+**Output examples:**
+
+```
+./main.go:15:6: can inline NewUser
+./main.go:20:6: &User{} escapes to heap    # heap allocation!
+./main.go:25:6: result does not escape      # stays on stack
+```
+
+**Common escape causes:**
+
+| Pattern | Escapes? | Fix |
+|---------|----------|-----|
+| Return pointer to local | Yes | Return value if small |
+| Store in interface | Yes | Use concrete type |
+| Closure captures variable | Yes | Pass as parameter |
+| Slice append beyond cap | Yes | Pre-allocate |
+| Send to channel | Yes | Use sync.Pool |
+
+```go
+// ESCAPES — pointer returned
+func newUser(name string) *User {
+    u := User{Name: name} // escapes to heap
+    return &u
+}
+
+// STAYS ON STACK — value returned
+func newPoint(x, y int) Point {
+    return Point{X: x, Y: y} // allocated on stack
+}
+
+// ESCAPES — stored in interface
+func process(v any) { ... }
+func main() {
+    n := 42
+    process(n) // n escapes to heap (boxed into interface)
+}
+```
+
+## alloc_objects — Finding Hot Allocators
+
+```bash
+go tool pprof -alloc_objects http://localhost:6060/debug/pprof/heap
+
+(pprof) top 10
+Showing nodes accounting for 1523456 allocs
+      flat  flat%   sum%        cum   cum%
+    892340 58.57% 58.57%     892340 58.57%  encoding/json.(*Decoder).Token
+    234567 15.40% 73.97%     234567 15.40%  bytes.(*Buffer).grow
+    123456  8.10% 82.07%     123456  8.10%  fmt.Sprintf
+```
+
+**Common allocation hot spots and fixes:**
+
+| Hot Spot | Fix |
+|----------|-----|
+| `fmt.Sprintf` | `strconv.Itoa`, `strconv.FormatInt`, string concat |
+| `json.Marshal/Unmarshal` | Pre-allocated buffer, `json.NewEncoder`, sonic/jsoniter |
+| `bytes.Buffer.grow` | Pre-sized `bytes.NewBuffer(make([]byte, 0, expectedSize))` |
+| `append` growing | Pre-allocate with `make([]T, 0, n)` |
+| String concatenation in loop | `strings.Builder` |
+
+## GC Tuning
+
+### GOGC
+
+Controls GC frequency. Default: `GOGC=100` means GC triggers when heap doubles.
+
+```bash
+GOGC=200 ./myapp    # less frequent GC, more memory, less CPU
+GOGC=50  ./myapp    # more frequent GC, less memory, more CPU
+GOGC=off ./myapp    # disable GC (for short-lived batch jobs only!)
+```
+
+| GOGC Value | Heap Growth Before GC | Tradeoff |
+|------------|----------------------|----------|
+| 50 | 50% growth | Low memory, high CPU |
+| 100 (default) | 100% growth | Balanced |
+| 200 | 200% growth | High memory, low CPU |
+| 400+ | 400%+ growth | For memory-rich servers |
+
+### GOMEMLIMIT (Go 1.19+)
+
+Hard ceiling on total Go memory. GC works harder as it approaches the limit.
+
+```bash
+GOMEMLIMIT=512MiB ./myapp   # GC gets aggressive near 512MB
+GOMEMLIMIT=2GiB ./myapp     # for container with 2GB memory limit
+```
+
+**Best practice for containers:**
+
+```bash
+# Container has 4GB memory
+# Reserve ~20% for non-Go memory (OS, cgo, etc.)
+GOMEMLIMIT=3200MiB GOGC=100 ./myapp
+```
+
+### Runtime Metrics
+
+```go
+import "runtime/metrics"
+
+func collectGCMetrics() {
+    samples := []metrics.Sample{
+        {Name: "/gc/cycles/total:gc-cycles"},
+        {Name: "/gc/heap/allocs:bytes"},
+        {Name: "/gc/heap/goal:bytes"},
+        {Name: "/memory/classes/total:bytes"},
+    }
+    metrics.Read(samples)
+}
+```
+
+## Caching Decision Tree
+
+| Scenario | Solution | When |
+|----------|----------|------|
+| Process-local, bounded size | `sync.Map` or samber/hot | Single instance, < 100k entries |
+| Process-local, eviction needed | samber/hot (LRU, LFU, ARC, etc.) | Need TTL or size-based eviction |
+| Distributed, shared across instances | Redis | Multi-instance, needs consistency |
+| Static assets | CDN (Cloudflare, CloudFront) | Images, JS, CSS, fonts |
+| Computed results, cross-request | Process-local + Redis fallback | Expensive computation |
+| Database query results | Application-level cache | Repeated queries, read-heavy |
+
+```go
+// samber/hot — in-memory cache with eviction
+import "github.com/samber/hot"
+
+cache := hot.NewHotCache[string, *User](hot.LRU, 10000)
+cache.SetWithTTL("user:42", user, 5*time.Minute)
+
+if user, ok := cache.Get("user:42"); ok {
+    return user, nil
+}
+```
+
+## When to Use
+
+Apply when reviewing performance-sensitive code or investigating performance issues. Flag violations as:
+- **CRITICAL**: Missing pprof endpoint in production service, GOGC=off in long-running service
+- **WARNING**: Benchmark without -count (no statistical rigor), missing GOMEMLIMIT in containers
+- **SUGGESTION**: Could use sync.Pool for hot-path allocations, pre-allocate slices, use strings.Builder

package/packages/stack-agents/go/references/refactoring-mechanics.md

@@ -0,0 +1,127 @@
+# Refactoring Mechanics (behavior-preserving Go transforms)
+
+> Reference document for go-reviewer and go-modernizer. Loaded on demand via Read tool.
+> Upstream: golang.org/x/tools · github.com/uber-go/gopatch · github.com/dave/dst
+
+A refactor is a transform that changes structure while provably preserving
+behavior. In Go, "provably" means a construction-guaranteed tool did the edit —
+not a freehand keystroke and not a text substitution. Pick the *weakest* tool
+that can express the change, gate the risk against the blast radius's own test
+coverage (see the safety net in `testing-patterns.md`), and never let a
+refactor and a behavior change share a commit.
+
+## Part 1 — The tool-escalation ladder
+
+Two rules govern the whole ladder:
+
+1. **Least-powerful tool first.** A `gofmt -r` rule you can read in one line is
+   safer than a hand-written AST walk. Climb only when the rung below cannot
+   express the transform.
+2. **NEVER `sed`/`perl` a structural Go change.** Text tools rewrite *inside*
+   string literals and comments, split identifiers that share a prefix, and
+   have zero idea what scope a name lives in. Every rung below is
+   syntax-aware; a regex is not. This rule has no exceptions.
+
+Rungs, weakest first — each with a runnable command and its one-line trap:
+
+1. **gopls code actions** — the blessed path for structural edits (Rename,
+   Extract function/variable, Inline, "fill struct", organize imports). Drive
+   them from the editor or the gopls MCP, not a shell. A CLI form exists —
+   `gopls codeaction -kind=refactor.extract -exec ./pkg/file.go` — but it is
+   *illustrative/debugging-only*; do not build a migration on it.
+   Gotcha: code actions are single-file and cursor-scoped; they do not sweep a package.
+2. **`gofmt -r`** — expression-pattern rewriting from the stdlib, no install.
+   `gofmt -r 'fmt.Sprintf("%d", a) -> fmt.Sprint(a)' -w .`
+   Gotcha: single-letter names are wildcards, but the rule matches **expressions only** — it cannot rewrite statements, add imports, or restructure control flow.
+3. **`eg`** — example-based rewriting driven by a before/after template.
+   `go install golang.org/x/tools/cmd/eg@latest` then `eg -t template.go -w ./...`
+   Gotcha: like `gofmt -r` it transforms **expressions only** (a `before`/`after` function pair); it is not a migration engine.
+4. **`gopatch`** — semantic patches (a diff-shaped `@@ ... @@` grammar) that
+   *can* touch statements and imports.
+   `gopatch -p rewrite.patch ./...`
+   Gotcha: **beta, ~80% coverage** — treat it as an escalation rung for a specific pattern, not a whole-codebase migration tool; diff every result.
+5. **go/analysis + `analysistest.RunWithSuggestedFixes`** — when a transform
+   *recurs*, write an analyzer that emits a `SuggestedFix` and pin it with a
+   golden-fixture test (`RunWithSuggestedFixes` applies the fix and diffs
+   against `testdata/.../*.golden`). Ship it via `go vet -vettool=` or
+   `go fix -fixtool=`.
+   Gotcha: real engineering cost — only worth it above roughly a dozen call sites or a permanent lint.
+6. **`go fix` / `//go:fix inline`** *(Go 1.26+)* — mark a wrapper or moved
+   function `//go:fix inline`; `go fix ./...` then inlines every call, in this
+   and downstream packages. The canonical low-risk way to retire a deprecated
+   API or a v1→v2 import.
+   `go fix ./...`
+   Gotcha: the `inline` fixer and the `//go:fix` directive land in **Go 1.26** — gate on the toolchain the way go-modernizer gates every rewrite; it is a no-op on older `go`.
+7. **`dave/dst`** — a decorated syntax tree for AST surgery that must survive
+   round-tripping. Reach here only when no rung above fits.
+   `import "github.com/dave/dst/decorator"` (parse → mutate → `decorator.Print`)
+   Gotcha: use `dst`, **not** raw `go/ast` — `go/ast` attaches comments by byte offset and mangles their placement the moment you move a node.
+8. **`deadcode -whylive`** — not a rewriter but the removal companion: proves
+   what a deletion orphans and why a symbol is still reachable.
+   `go install golang.org/x/tools/cmd/deadcode@latest` then `deadcode -whylive=pkg.Symbol ./...`
+   Gotcha: it reasons over a build's reachability; unexported code hit only by reflection or `//go:linkname` can read as dead when it is not.
+
+**Always finish with `goimports -w .`** after any mechanical transform — every
+rung above can leave the import block stale, and a clean import list is the
+cheapest signal that the edit type-checks.
+
+## Part 2 — Smell → fix → tool → risk catalog
+
+For *target shapes*, this table points at `design-patterns.md` rather than
+re-teaching them; only the net-new **move/graft mechanics** are taught below it.
+
+| Smell | Go fix (target shape) | Tool rung | Risk |
+|-------|----------------------|-----------|------|
+| Long positional constructor | Options struct — `design-patterns.md` §1 | gopls Extract + `gofmt -r` on call sites | Med |
+| Package binds a concrete dependency | Consumer-side interface — `design-patterns.md` §5 | manual + `type A = B` alias | Med |
+| Deep `if`/`else` nesting | Guard clauses — `design-patterns.md` §14 | gopls Extract / Inline | Low |
+| Embedding for reuse | Composition — `design-patterns.md` §8 | gopls + manual | Low |
+| Deprecated API called everywhere | `//go:fix inline` wrapper | `go fix` (1.26+) | Low |
+| Repeated expression idiom | Template rewrite | `gofmt -r` → `eg` | Low |
+| Type belongs in another package | `type A = B` alias move (below) | manual + `gopatch` for sites | Med |
+| New logic tangled with untested legacy | Sprout (below) | manual + new tests | Low |
+| Legacy call needs pre/post logic | Wrap (below) | gopls Rename + manual | Low |
+
+**Move a type across packages via a temporary alias.** Moving `Foo` from
+`pkg/old` to `pkg/new` in one shot breaks every importer. Instead: (1) define
+`Foo` in `pkg/new`; (2) in `pkg/old` leave `type Foo = new.Foo` — an *alias*,
+not a copy, so old importers keep compiling and stay type-identical; (3)
+migrate importers to `pkg/new` (a `gopatch` or `//go:fix inline` job); (4)
+delete the alias. Each step compiles green and is separately committable.
+
+**Sprout Method/Class.** When new behavior must land inside a hairy, untested
+function, do not edit that function's guts. Write the new behavior as a *new*
+function or type with its own tests, and call it from the one place the old
+code needs it. The risky legacy body is touched by one line, not rewritten.
+
+**Wrap Method.** To add pre/post behavior to an existing call without editing
+its body: rename the original (gopls Rename) to `fooCore`, then add a new `Foo`
+with the original name that does the new work around a call to `fooCore`.
+Callers are unchanged; the old behavior is preserved verbatim inside `fooCore`.
+
+## Part 3 — Hard-rule gotchas
+
+**After ANY rename, grep beyond the compiler.** gopls Rename guarantees the
+code *compiles* — nothing more. It is blind to string-encoded uses of the name:
+after renaming a field or type, grep the struct tags (`json:`, `db:`, `yaml:`,
+`gorm:`), every `reflect`-based access (`FieldByName`, `MethodByName`,
+`Tag.Get`), and any `text/template`/`html/template` files that name the old
+identifier. Those keep compiling and fail at runtime.
+
+**Never mix structural and behavioral changes in one commit.** A commit is
+either a refactor (behavior byte-identical) or a behavior change — never both.
+Reviewers and `git bisect` rely on that line. Concretely: **split a move from
+an optimization.** Move the code in one commit, then optimize it in the next;
+a move buried inside a perf change is unreviewable and un-revertable.
+
+**Break import cycles with a consumer-side interface *before* moving code.**
+If relocating a type would create an import cycle, do not fight the move —
+first define the small interface at the *consumer* (`design-patterns.md` §5) so
+the dependency inverts, *then* move. Ordering matters: the seam comes first.
+
+Every transform above is only as safe as the tests guarding its blast radius.
+Before touching code, size that blast radius's coverage and pick your caution
+tier per the **Coverage-Adaptive Refactoring Safety Net** in
+`testing-patterns.md` — below 40% you write characterization tests and install
+seams before any transform, and restrict yourself to construction-guaranteed
+tools from the ladder above.

package/packages/stack-agents/go/references/rest-openapi-patterns.md

@@ -0,0 +1,160 @@
+# REST / OpenAPI Patterns (swaggo + oapi-codegen)
+
+> Reference document for go-reviewer. Loaded on demand via Read tool.
+> Upstream: https://github.com/swaggo/swag · https://github.com/oapi-codegen/oapi-codegen
+
+REST is the dominant Go API surface. There are two honest ways to keep the code
+and the OpenAPI spec in sync, and they pull in opposite directions — pick by who
+owns the contract.
+
+## Two paths — pick by who owns the contract
+
+**Code-first (swaggo/swag)** — annotations on handlers *generate* the spec. The
+Go code is the source of truth; the spec is a build artifact. Fastest for a team
+that owns both ends and iterates quickly. This is the **primary path** here.
+
+- Lead with **swag v1** (stable, OpenAPI 2.0 / Swagger). It is what almost every
+  gin/echo/fiber integration targets today.
+- swag **v2 (currently RC)** adds OpenAPI 3.x — treat it as preview, switch when
+  it goes GA. Don't put an RC on the critical path of a shipping service.
+
+**Spec-first (oapi-codegen)** — hand-write the OpenAPI 3.x document, then
+*generate* server interfaces, request/response types, and clients from it. The
+spec is the source of truth; the code conforms to it. Prefer this when the
+contract is the deliverable — versioned in review, published to other teams, or
+consumed by clients you don't control — because the compiler then enforces that
+handlers match the contract instead of the contract trailing the code.
+
+```bash
+# spec-first: generate a chi/echo/gin server + models from openapi.yaml
+go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen \
+    -generate types,chi-server -package api openapi.yaml > api/gen.go
+```
+
+You implement the generated `ServerInterface`; a missing or mis-typed handler is
+a compile error, not a silent drift. The rest of this doc covers the code-first
+swag path, since that is where the review footguns cluster.
+
+## swag annotation cheatsheet
+
+Annotations sit in a `//` comment block directly above the handler. Run
+`swag init` to parse them into `docs/`.
+
+| Annotation | Syntax | Gotcha |
+|------------|--------|--------|
+| `@Summary` | `@Summary Create a user` | One line; shows as the operation title. |
+| `@Description` | `@Description Longer prose, may span lines` | Free text; no markup guarantees. |
+| `@Tags` | `@Tags users` | Groups routes in the UI; keep names stable. |
+| `@Param` | `@Param body body CreateUserReq true "payload"` | A **body** param must name a **struct** — a primitive (`string`, `int`) in body silently emits a broken/empty schema. |
+| `@Param` (query/path) | `@Param id path string true "user id"` | `path`/`query`/`header`/`formData` take primitives fine. |
+| `@Success` | `@Success 200 {object} UserResp` | `{object}` / `{array}` must reference a real Go type, not a shape. |
+| `@Failure` | `@Failure 404 {object} ErrResp` | Document the error envelope too, or consumers guess it. |
+| `@Router` | `@Router /users/{id} [get]` | Path + method in brackets; must match the actual route. |
+| `@Security` | `@Security BearerAuth` | Names a scheme from `@securityDefinitions`; see below. |
+
+Three traps that produce a spec which *looks* fine but lies:
+
+1. **Named body struct.** `@Param body body string true "..."` compiles and runs;
+   the generated schema is broken. Body params must reference a named struct.
+2. **The blank-import trap.** `swag init` writes a `docs` package, but nothing
+   imports it — so you must add `import _ "yourmodule/docs"` (usually in `main.go`)
+   or the UI serves an *empty* spec with no error.
+3. **Stale `docs/`.** Annotations are not checked against `docs/` at build time.
+   Re-run `swag init` on **every** annotation change or the published contract
+   drifts from the code. Enforce it in CI:
+
+```bash
+swag fmt                                   # normalize annotation formatting
+swag init                                  # regenerate docs/
+git diff --exit-code docs/                 # fail the build if docs/ is stale
+```
+
+## UI wiring — one line per router
+
+Each framework has a thin adapter that mounts Swagger UI at a route. Import the
+generated `docs` package (blank import) first, then:
+
+- **gin** — `r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))` (`swaggo/gin-swagger`)
+- **echo** — `e.GET("/swagger/*", echoSwagger.WrapHandler)` (`swaggo/echo-swagger`)
+- **fiber** — `app.Get("/swagger/*", fiberSwagger.WrapHandler)` (`swaggo/fiber-swagger`)
+- **chi** — `r.Get("/swagger/*", httpSwagger.WrapHandler)` (`swaggo/http-swagger`)
+- **net/http** — `mux.Handle("/swagger/", httpSwagger.WrapHandler)` (`swaggo/http-swagger`)
+
+Whichever you use: **gate the route** behind auth middleware in production, or
+compile it out of prod builds. An open `/swagger` endpoint hands attackers a
+complete map of your API surface.
+
+## Security schemes
+
+Declare schemes once, in the package-level general API comment (usually above
+`main`), then reference them per route with `@Security`:
+
+```go
+// @securityDefinitions.apikey  BearerAuth
+// @in                          header
+// @name                        Authorization
+// @description                 "Bearer {token}"
+//
+// @securityDefinitions.oauth2.accessCode  OAuth2
+// @tokenUrl                                https://auth.example.com/token
+// @authorizationUrl                        https://auth.example.com/authorize
+//
+// @securityDefinitions.apikey  ApiKeyAuth   // @in header, @name X-API-Key
+// @securityDefinitions.basic   BasicAuth
+```
+
+swag supports `apikey` (used for Bearer/JWT via the `Authorization` header),
+`oauth2` (its `implicit`/`accessCode`/`password`/`application` flows), and
+`basic`. Then, on **every** protected handler:
+
+```go
+// @Security BearerAuth
+// @Router   /users/{id} [get]
+```
+
+A missing `@Security` understates auth in the public contract: the route renders
+with no lock icon and consumers reasonably assume it is open. This is a contract
+bug even when the middleware is correctly enforcing auth at runtime.
+
+## Struct tags that shape the schema
+
+The generated schema reads Go struct tags. Get these right or the spec misleads —
+or leaks:
+
+```go
+type User struct {
+    ID        string `json:"id"        example:"u_123"`
+    Email     string `json:"email"     format:"email" example:"a@b.com"`
+    CreatedAt string `json:"createdAt" format:"date-time"`
+    Password  string `json:"-"         swaggerignore:"true"` // never in the spec
+    internalR string `swaggerignore:"true"`                  // internal-only field
+}
+```
+
+- `json:"..."` sets the property name (and `json:"-"` drops it from JSON).
+- `example:"..."` / `format:"..."` populate the schema's example and `format`.
+- **`swaggerignore:"true"`** keeps a field out of the generated spec entirely.
+  Put it on every secret or internal field — a password, token, or internal flag
+  that isn't ignored leaks straight into the public documentation. `json:"-"`
+  hides it from the JSON wire, but swag may still emit it in the schema unless
+  `swaggerignore` is also set.
+
+## Review Checklist (go-reviewer)
+
+- **CRITICAL** — Swagger UI exposed ungated in production (gate it behind auth
+  middleware, or disable/compile-out the route in prod builds).
+- **CRITICAL** — Secret or internal field not `swaggerignore:"true"` (leaks into
+  the public spec).
+- **WARNING** — Protected route missing `@Security` (contract understates auth;
+  no lock icon, consumers assume open).
+- **WARNING** — Stale `docs/` vs annotations (contract drift; add a CI freshness
+  gate: `swag init` + `git diff --exit-code docs/`).
+- **WARNING** — Primitive `@Param` body instead of a named struct (silently
+  produces a broken spec).
+
+## Further Reading
+
+- swaggo/swag: https://github.com/swaggo/swag
+- swag annotation reference: https://github.com/swaggo/swag#declarative-comments-format
+- oapi-codegen: https://github.com/oapi-codegen/oapi-codegen
+- OpenAPI Specification: https://spec.openapis.org/