claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/stack-agents/go/references/error-wrapping.md

@@ -0,0 +1,230 @@
+# Error Wrapping
+
+> Reference document for go-error-reviewer. Loaded on demand via Read tool.
+
+## The fmt.Errorf %w Pattern
+
+The primary mechanism for adding context to errors while preserving the error chain.
+
+```go
+func (r *UserRepository) FindByID(ctx context.Context, id int64) (*User, error) {
+    row := r.db.QueryRow(ctx, "SELECT ... WHERE id = $1", id)
+    var u User
+    if err := row.Scan(&u.ID, &u.Name, &u.Email); err != nil {
+        if errors.Is(err, pgx.ErrNoRows) {
+            return nil, fmt.Errorf("UserRepository.FindByID: %w", domain.ErrNotFound)
+        }
+        return nil, fmt.Errorf("UserRepository.FindByID: %w", err)
+    }
+    return &u, nil
+}
+```
+
+## Wrapping Depth Rule
+
+**One wrap per function boundary.** Each function that propagates an error adds exactly one layer of context.
+
+```go
+// Repository layer
+func (r *Repo) Save(ctx context.Context, u *User) error {
+    _, err := r.db.Exec(ctx, query, u.ID, u.Name)
+    if err != nil {
+        return fmt.Errorf("Repo.Save: %w", err) // ONE wrap
+    }
+    return nil
+}
+
+// Service layer
+func (s *Service) CreateUser(ctx context.Context, u *User) error {
+    if err := s.repo.Save(ctx, u); err != nil {
+        return fmt.Errorf("Service.CreateUser: %w", err) // ONE wrap
+    }
+    return nil
+}
+
+// Handler layer
+func (h *Handler) HandleCreate(w http.ResponseWriter, r *http.Request) {
+    if err := h.svc.CreateUser(r.Context(), user); err != nil {
+        // Log the full chain, respond with appropriate status
+        h.logger.Error("create user failed", "error", err)
+        // err message: "Service.CreateUser: Repo.Save: connection refused"
+    }
+}
+```
+
+## Context Format
+
+The standard wrapping format is `TypeName.MethodName: %w`.
+
+```go
+// CORRECT — clear provenance
+return fmt.Errorf("UserRepository.FindByID: %w", err)
+return fmt.Errorf("OrderService.PlaceOrder: %w", err)
+return fmt.Errorf("AuthMiddleware.Validate: %w", err)
+
+// ALSO ACCEPTABLE — shorter, for internal helpers
+return fmt.Errorf("findByID: %w", err)
+return fmt.Errorf("validate email: %w", err)
+
+// WRONG — redundant "error" / "failed"
+return fmt.Errorf("error in UserRepository.FindByID: %w", err) // "error" redundant
+return fmt.Errorf("failed to find user by ID: %w", err)        // "failed to" noise
+return fmt.Errorf("UserRepository: FindByID: %w", err)         // use dot, not colon
+
+// WRONG — no context at all
+return fmt.Errorf("%w", err) // pointless wrap, just return err
+return err                    // OK if same package, no context needed
+```
+
+## When to Wrap vs Return As-Is
+
+**Decision table:**
+
+| Situation | Action | Why |
+|-----------|--------|-----|
+| Crossing package boundary | Wrap | Caller needs to know where error originated |
+| Crossing layer boundary (repo→service) | Wrap | Each layer adds its context |
+| Within same package, different func | Optional | Wrap if func name adds useful context |
+| Within same function, sequential ops | Don't re-wrap | Already at the right context level |
+| Returning sentinel directly | Don't wrap | `return ErrNotFound` is clear enough |
+| Returning sentinel with context | Wrap | `fmt.Errorf("user %d: %w", id, ErrNotFound)` |
+
+```go
+// SAME PACKAGE — wrapping is optional
+func (s *Service) process(ctx context.Context, data []byte) error {
+    parsed, err := s.parse(data)
+    if err != nil {
+        return err // same package, parse already has context
+    }
+    return s.store(ctx, parsed)
+}
+
+// CROSSING BOUNDARY — always wrap
+func (h *Handler) Process(w http.ResponseWriter, r *http.Request) {
+    if err := h.svc.Process(r.Context(), body); err != nil {
+        return fmt.Errorf("Handler.Process: %w", err)
+    }
+}
+```
+
+## Chain Inspection
+
+### errors.Unwrap
+
+Manually traverses one level of the error chain.
+
+```go
+err := fmt.Errorf("outer: %w", fmt.Errorf("inner: %w", io.EOF))
+
+unwrapped := errors.Unwrap(err)
+// unwrapped.Error() == "inner: end of file"
+
+unwrapped2 := errors.Unwrap(unwrapped)
+// unwrapped2 == io.EOF
+```
+
+### Multi-Error Unwrap (Go 1.20+)
+
+Errors created with `errors.Join` implement `Unwrap() []error`.
+
+```go
+err := errors.Join(
+    fmt.Errorf("step 1: %w", ErrNotFound),
+    fmt.Errorf("step 2: %w", ErrTimeout),
+)
+
+// errors.Is checks ALL errors in the tree
+errors.Is(err, ErrNotFound) // true
+errors.Is(err, ErrTimeout)  // true
+
+// Custom multi-error
+type MultiError struct {
+    Errors []error
+}
+
+func (e *MultiError) Error() string { ... }
+
+func (e *MultiError) Unwrap() []error {
+    return e.Errors
+}
+```
+
+## %w vs %v
+
+| Verb | Chain preserved? | Caller can inspect? | Use when |
+|------|-----------------|--------------------|----|
+| `%w` | Yes | Yes — `errors.Is`/`errors.As` work | Default choice — expose error chain |
+| `%v` | No | No — chain is broken | Intentionally hiding implementation details |
+
+```go
+// %w — preserves chain (default choice)
+return fmt.Errorf("UserService.Create: %w", err)
+// Caller can: errors.Is(err, pgx.ErrNoRows) → true
+
+// %v — breaks chain (intentional hiding)
+return fmt.Errorf("external API error: %v", err)
+// Caller cannot inspect the original error
+// Use when: internal implementation detail should not leak
+```
+
+**When to use %v (break chain):**
+- External API errors that should be opaque to callers
+- Implementation details that may change (DB driver errors in a service layer)
+- Security-sensitive errors (don't expose internal error messages to HTTP responses)
+
+## Anti-Patterns
+
+### Double Wrapping
+
+```go
+// WRONG — redundant context
+func (s *Service) Get(ctx context.Context, id int64) (*User, error) {
+    user, err := s.repo.FindByID(ctx, id)
+    if err != nil {
+        return nil, fmt.Errorf("Service.Get: failed to get user: %w", err)
+        //                      ^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^
+        //                      context     redundant "failed to get user"
+    }
+    return user, nil
+}
+
+// CORRECT
+return nil, fmt.Errorf("Service.Get: %w", err)
+```
+
+### Wrapping Then Checking
+
+```go
+// WRONG — wrap then check loses the type info
+wrapped := fmt.Errorf("context: %w", err)
+if wrapped == ErrNotFound { // always false for wrapped errors
+    // ...
+}
+
+// CORRECT — check before wrapping, or use errors.Is on wrapped
+if errors.Is(err, ErrNotFound) {
+    return nil, fmt.Errorf("Service.Get: %w", domain.ErrNotFound)
+}
+return nil, fmt.Errorf("Service.Get: %w", err)
+```
+
+### String Comparison
+
+```go
+// WRONG — fragile, breaks on wrapping
+if err.Error() == "not found" {
+    // ...
+}
+
+// CORRECT
+if errors.Is(err, ErrNotFound) {
+    // ...
+}
+```
+
+## When to Use
+
+Apply when reviewing error propagation through function and package boundaries. Flag violations as:
+- **CRITICAL**: Using `%v` where `%w` is needed (breaks caller inspection), comparing error strings
+- **WARNING**: Missing context on wrap, double-wrapping with redundant messages, wrapping at every call within same function
+- **SUGGESTION**: Could simplify by returning unwrapped within same package, inconsistent context format

package/packages/stack-agents/go/references/gopls-driving.md

@@ -0,0 +1,62 @@
+# Driving gopls (semantic navigation)
+
+> Reference document for go-reviewer, go-error-reviewer, go-concurrency-reviewer. Loaded on demand via Read tool. Opt-in — requires the gopls MCP server.
+> Upstream: https://github.com/golang/tools/tree/master/gopls · https://github.com/samber/cc-skills-golang
+
+Grep finds text. gopls resolves the build: accurate references, interface satisfaction, and reference blast-radius that a regex cannot compute. This is exactly the accuracy gap on interface- and blast-radius findings. gopls is the Go team's language server; it exposes eight `go_*` tools over MCP. It is an external binary plus a registration step, so treat it as strictly opt-in — never assume it is wired.
+
+## Setup (opt-in)
+
+**Requires:** the `gopls` MCP server. This capability is inert until it is registered.
+
+```bash
+go install golang.org/x/tools/gopls@latest   # the binary
+claude mcp add gopls -- gopls mcp            # register it with Claude Code
+```
+
+The server MUST be registered under the exact name `gopls`. The tools resolve as `mcp__gopls__go_*`; that namespace only exists if the server name is `gopls`. Register it under any other name and none of the tools below are callable.
+
+If the server is not registered, everything below is inert — fall back to grep for references and `go doc` for external symbol contracts, exactly as the Evidence Gate already prescribes. Never assume the server is wired: probe with `go_workspace` first, and if it errors, drop to the grep + `go doc` path for the whole review.
+
+## The eight tools
+
+| Tool | Params | Use for |
+|------|--------|---------|
+| `go_workspace` | `{}` | Modules, packages, and layout of the workspace. Probe first — a clean return means the server is live. |
+| `go_search` | `{"query"}` | Fuzzy-find a symbol by name, workspace-wide. Locate a definition before reading it. |
+| `go_file_context` | `{"file"}` | A file's own symbols plus its intra-package dependencies. The semantic replacement for reading a file to orient. |
+| `go_package_api` | `{"packagePaths":[]}` | A package's exported API surface. Resolves interface satisfaction and public contracts. |
+| `go_symbol_references` | `{"file","symbol"}` | Every reference to a symbol, workspace-wide. The blast-radius tool — run before touching any definition. |
+| `go_diagnostics` | `{"files":[]}` | Compiler + analyzer diagnostics for the listed files. NOT pushed automatically — you must call it after every edit. |
+| `go_vulncheck` | `{"pattern":"./..."}` | Reachable vulnerabilities via govulncheck. Run only when `go.mod` / `go.sum` changed. |
+| `go_rename_symbol` | *(params inferred: `file`, `symbol`, `newName` — confirm against your running server; upstream mcp.md/matrix.md do not publish the signature)* | Rename a symbol and every reference to it. Blocks any rename that would break interface satisfaction. |
+
+## Read → Edit workflow order
+
+**Reading (orient before you judge):**
+`go_workspace` (probe + layout) → `go_search` (find the symbol) → `go_file_context` (the file's own symbols + local deps) → `go_package_api` (the exported surface / interface contracts).
+
+**Editing (blast-radius before you touch, verify after):**
+1. `go_symbol_references` on the definition to establish the full blast radius **BEFORE** you change anything. Every caller you would break is here.
+2. Make the edit.
+3. `go_diagnostics` on the changed files — **MANDATORY**. Diagnostics are not pushed to you; an unrun diagnostic is an unverified edit.
+4. Fix what it reports and re-run `go_diagnostics` until clean.
+5. `go_vulncheck` **only if `go.mod` changed** — a new or bumped dependency can pull in a reachable CVE.
+
+## Load-bearing gotchas
+
+- **Disk-only, no unsaved buffer.** The server sees files as they are on disk. Write your edit before you query — an unsaved change is invisible to `go_symbol_references`, `go_diagnostics`, and every other tool.
+- **Results reflect ONLY the queried file's build config.** A query on `foo_windows.go` resolves under the Windows build; it will miss references in `bar_linux.go`. For cross-platform blast radius, re-run the reference query under the other GOOS / build-tag combinations — do not trust a single-config answer as complete.
+- **References and call-hierarchy are static-dispatch only.** Calls made through an interface method or a function value are INVISIBLE to `go_symbol_references` — it resolves concrete, statically-dispatched calls, not dynamic ones. When a symbol is reached via an interface or a `func` field, corroborate the call sites manually (grep the method name, trace the interface) before you trust the reported blast radius.
+- **Rename blocks interface-breaking changes.** `go_rename_symbol` refuses a rename that would break interface satisfaction — a rejection is signal, not a bug. It tells you the symbol participates in an interface contract you had not accounted for.
+- **Scope = workspace + go.sum-pinned deps.** The server sees your workspace and the dependencies pinned in `go.sum`. A package that is not yet imported is out of scope; `go_search` / `go_package_api` will not find it. For a symbol in a not-yet-imported package, fall back to `go doc <pkg>` per the Evidence Gate instead of concluding it does not exist.
+
+## Access-path ranking
+
+Prefer the MCP path. It is the production interface.
+
+1. **MCP (preferred)** — the `go_*` tools above. This is the path these agents use.
+2. **Native LSP (bonus, experimental)** — enable with `ENABLE_LSP_TOOL=1`. Auto-pushes diagnostics as you edit, but it is experimental; use it only as a convenience layer over MCP, never as the sole path.
+3. **CLI (`gopls codeaction`, etc.)** — debugging-only. Reach for the `gopls` command line to diagnose the server itself, never as the production navigation path.
+
+Whatever the path, a gopls result is a valid VERIFIED citation — the same standing as a `file:line` you Read. When gopls is not wired, none of this applies: grep and `go doc` remain the citation sources. Never assume the server is wired; confirm it, then use it.

package/packages/stack-agents/go/references/goroutine-lifecycle.md

@@ -0,0 +1,351 @@
+# Goroutine Lifecycle
+
+> Reference document for go-concurrency-reviewer. Loaded on demand via Read tool.
+
+## Spawn Patterns
+
+Always spawn goroutines with a clear exit path. Never fire-and-forget.
+
+```go
+// CORRECT — goroutine with context cancellation
+func (s *Service) StartWorker(ctx context.Context) {
+    go func() {
+        for {
+            select {
+            case <-ctx.Done():
+                return // clean exit
+            case job := <-s.jobs:
+                s.process(ctx, job)
+            }
+        }
+    }()
+}
+
+// CORRECT — goroutine with WaitGroup for lifecycle tracking
+func (s *Service) StartWorkers(ctx context.Context, n int) {
+    s.wg.Add(n)
+    for range n {
+        go func() {
+            defer s.wg.Done()
+            for {
+                select {
+                case <-ctx.Done():
+                    return
+                case job := <-s.jobs:
+                    s.process(ctx, job)
+                }
+            }
+        }()
+    }
+}
+
+// WRONG — fire and forget, no exit path
+func (s *Service) StartWorker() {
+    go func() {
+        for job := range s.jobs { // blocks forever if channel never closed
+            s.process(context.Background(), job)
+        }
+    }()
+}
+```
+
+## Shutdown Mechanisms
+
+### Context Cancellation (preferred)
+
+```go
+ctx, cancel := context.WithCancel(context.Background())
+defer cancel() // cancels all child goroutines
+
+go worker(ctx)
+go worker(ctx)
+
+// Later: cancel() signals all workers to stop
+```
+
+### Done Channel
+
+```go
+type Server struct {
+    done chan struct{}
+}
+
+func (s *Server) Start() {
+    s.done = make(chan struct{})
+    go s.run()
+}
+
+func (s *Server) Stop() {
+    close(s.done) // signal all goroutines
+}
+
+func (s *Server) run() {
+    ticker := time.NewTicker(time.Second)
+    defer ticker.Stop()
+    for {
+        select {
+        case <-s.done:
+            return
+        case <-ticker.C:
+            s.tick()
+        }
+    }
+}
+```
+
+### Signal-Based Shutdown
+
+```go
+func main() {
+    ctx, stop := signal.NotifyContext(context.Background(),
+        syscall.SIGINT, syscall.SIGTERM)
+    defer stop()
+
+    srv := NewServer()
+    go func() {
+        if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
+            log.Fatal("listen", "error", err)
+        }
+    }()
+
+    <-ctx.Done() // block until signal
+    log.Info("shutting down")
+
+    shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+
+    if err := srv.Shutdown(shutdownCtx); err != nil {
+        log.Error("shutdown", "error", err)
+    }
+    log.Info("shutdown complete")
+}
+```
+
+## Graceful Shutdown Pattern
+
+Full production-ready graceful shutdown with multiple components:
+
+```go
+func run(ctx context.Context) error {
+    ctx, cancel := context.WithCancel(ctx)
+    defer cancel()
+
+    g, ctx := errgroup.WithContext(ctx)
+
+    // HTTP server
+    srv := &http.Server{Addr: ":8080", Handler: mux}
+    g.Go(func() error {
+        if err := srv.ListenAndServe(); err != http.ErrServerClosed {
+            return err
+        }
+        return nil
+    })
+    g.Go(func() error {
+        <-ctx.Done()
+        shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+        defer cancel()
+        return srv.Shutdown(shutdownCtx)
+    })
+
+    // Background worker
+    g.Go(func() error {
+        return worker.Run(ctx) // must respect ctx.Done()
+    })
+
+    // Metrics flusher
+    g.Go(func() error {
+        <-ctx.Done()
+        return metrics.Flush(context.Background())
+    })
+
+    return g.Wait()
+}
+```
+
+## Leak Prevention
+
+Every goroutine must have a guaranteed exit path. Common leak patterns:
+
+### Leak: Blocked Channel Read
+
+```go
+// LEAK — ch may never receive a value
+func leaky() {
+    ch := make(chan int)
+    go func() {
+        val := <-ch // blocks forever if nobody sends
+        process(val)
+    }()
+    // function returns, ch goes out of scope, goroutine leaks
+}
+
+// FIXED — use context or done channel
+func fixed(ctx context.Context) {
+    ch := make(chan int)
+    go func() {
+        select {
+        case val := <-ch:
+            process(val)
+        case <-ctx.Done():
+            return
+        }
+    }()
+}
+```
+
+### Leak: Blocked Channel Write
+
+```go
+// LEAK — unbuffered channel, nobody reads
+func leaky() {
+    ch := make(chan result)
+    go func() {
+        ch <- doWork() // blocks forever if nobody reads
+    }()
+    // function returns without reading from ch
+}
+
+// FIXED — buffered channel of 1
+func fixed() {
+    ch := make(chan result, 1) // won't block even if nobody reads
+    go func() {
+        ch <- doWork()
+    }()
+}
+```
+
+### Leak: Forgotten Ticker
+
+```go
+// LEAK — ticker not stopped
+func leaky() {
+    ticker := time.NewTicker(time.Second)
+    go func() {
+        for range ticker.C {
+            // ...
+        }
+    }()
+}
+
+// FIXED — stop ticker on exit
+func fixed(ctx context.Context) {
+    ticker := time.NewTicker(time.Second)
+    go func() {
+        defer ticker.Stop()
+        for {
+            select {
+            case <-ctx.Done():
+                return
+            case <-ticker.C:
+                // ...
+            }
+        }
+    }()
+}
+```
+
+## goleak Integration
+
+Detect goroutine leaks in tests.
+
+```go
+import "go.uber.org/goleak"
+
+// Option 1: TestMain — checks all tests in package
+func TestMain(m *testing.M) {
+    goleak.VerifyTestMain(m)
+}
+
+// Option 2: Per-test — more granular
+func TestNoLeak(t *testing.T) {
+    defer goleak.VerifyNone(t)
+    // test code...
+}
+
+// Option 3: Ignore known goroutines
+func TestMain(m *testing.M) {
+    goleak.VerifyTestMain(m,
+        goleak.IgnoreTopFunction("database/sql.(*DB).connectionOpener"),
+        goleak.IgnoreAnyFunction("go.opencensus.io/stats/view.(*worker).start"),
+    )
+}
+```
+
+## Worker Pool Pattern
+
+Bounded concurrency using a semaphore channel.
+
+```go
+func ProcessAll(ctx context.Context, items []Item, maxWorkers int) error {
+    g, ctx := errgroup.WithContext(ctx)
+    g.SetLimit(maxWorkers) // errgroup built-in limiter (Go 1.20+)
+
+    for _, item := range items {
+        g.Go(func() error {
+            return process(ctx, item)
+        })
+    }
+
+    return g.Wait()
+}
+
+// Manual semaphore pattern (pre-errgroup.SetLimit)
+func ProcessAll(ctx context.Context, items []Item, maxWorkers int) error {
+    sem := make(chan struct{}, maxWorkers)
+    g, ctx := errgroup.WithContext(ctx)
+
+    for _, item := range items {
+        sem <- struct{}{} // acquire
+        g.Go(func() error {
+            defer func() { <-sem }() // release
+            return process(ctx, item)
+        })
+    }
+
+    return g.Wait()
+}
+```
+
+## Error Propagation with errgroup
+
+```go
+func FetchAll(ctx context.Context, urls []string) ([]Response, error) {
+    results := make([]Response, len(urls))
+    g, ctx := errgroup.WithContext(ctx)
+
+    for i, url := range urls {
+        g.Go(func() error {
+            resp, err := fetch(ctx, url)
+            if err != nil {
+                return fmt.Errorf("fetch %s: %w", url, err)
+            }
+            results[i] = resp // safe: each goroutine writes to unique index
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err // returns first error, cancels remaining via ctx
+    }
+    return results, nil
+}
+```
+
+## Decision Table: Goroutine Lifecycle Tools
+
+| Need | Tool | Why |
+|------|------|-----|
+| Wait for N goroutines | `sync.WaitGroup` | Simple count-based waiting |
+| Wait + first error cancels all | `errgroup.Group` | Combines WaitGroup + context cancel |
+| Bounded parallelism | `errgroup.SetLimit(n)` | Limits concurrent goroutines |
+| Background worker with shutdown | `context.WithCancel` | Parent controls lifecycle |
+| Periodic task | `time.Ticker` + select | Cancelable periodic execution |
+| OS signal handling | `signal.NotifyContext` | Converts signal to context cancel |
+| HTTP server shutdown | `srv.Shutdown(ctx)` | Drains in-flight requests |
+
+## When to Use
+
+Apply when reviewing goroutine creation, lifecycle management, and shutdown patterns. Flag violations as:
+- **CRITICAL**: Goroutine without exit path (leak), fire-and-forget with no cancellation, missing WaitGroup/errgroup
+- **WARNING**: No graceful shutdown for long-running services, ticker without Stop, blocked channel without timeout
+- **SUGGESTION**: Could use errgroup.SetLimit instead of manual semaphore, missing goleak in tests