gopherstack: Instructions file for Codex

Agent Instructions

You are an expert Go and TypeScript engineer. You write idiomatic Go: small focused functions (under 100 lines), cyclomatic complexity below 15 (extract helpers — never use //nolint), named constants instead of magic strings, explicit error handling, no goroutine or resource leaks. You know the AWS SDK v2 deeply and build accurate AWS service simulations.

Pre-push checklist — ALL must pass before every commit:

goimports -w -local github.com/blackbirdworks/gopherstack ./services/<pkg>/...
golines -w --max-len=120 ./services/<pkg>/...
go test ./services/<pkg>/... -short -count=1
go vet ./services/<pkg>/...
golangci-lint run ./services/<pkg>/...

task lint also runs mulint (mutex misuse detection) via go vet -vettool. mulint cannot follow mutex wrappers across package boundaries, so it does not see lockmetrics.RWMutex (used almost everywhere in this repo) — it only guards direct sync.Mutex/sync.RWMutex use.

Logging — context-aware only (no exceptions):

• NEVER call slog.Default() or construct an ad-hoc slog.New(...) in service/production code, and NEVER embed or store a *slog.Logger on a struct/global. The single allowed slog.Default() is the fallback inside pkgs/logger.Load; the single allowed slog.New is pkgs/logger.NewLogger.
• Always fetch the logger from context: logger.Load(ctx), and prefer the *Context methods (InfoContext/WarnContext/...) so the request/worker fields propagate.
• The root logger is created once at startup and injected into ctx. Enrich it, never replace it: logger.WithService(ctx, name) at a service boundary (done centrally per request), logger.AddAttrs(ctx, ...) for extra fields, and logger.WithWorker(ctx, service, job) at the entry of every background routine (records log as worker=<service>-<job>).
• Background routines (janitors, debounced saves, accept loops) MUST derive their logger from the lifecycle/root context (e.g. the janitor context), NEVER from a per-request echo context — otherwise they leak request_id and pin a finished request alive.
• The logger is a pointer carried in ctx; enrichment is copy-on-write (slog.Logger.With returns a new logger). Do NOT mutate it, do NOT call slog.SetDefault at runtime, and do NOT call WithService/WithWorker/AddAttrs inside a loop (each call layers attributes — derive once at entry; for per-item fields use a local l := logger.Load(ctx).With(...)).
• Do NOT introduce context.Background()/context.TODO() in service code or tests to satisfy a signature — thread the real request/root context (in tests use t.Context()).

Checkpoint commits for long tasks: For tasks taking >1 hour, commit and push every ~30 minutes:

git add -A && git commit -m "WIP: checkpoint" && git push origin HEAD

Subagent Isolation: When dispatching subagents for concurrent tasks, always isolate working trees (Workspace: 'branch' or git worktree) to avoid cross-contamination of uncommitted edits, task docs regeneration, or intermediate build artifacts.

This project uses bd (beads) for issue tracking. Run bd prime for full workflow context.