@litfamily/litcodex 1.0.0

package/marketplace/plugins/litcodex/skills/lit-code/references/engineering-risk-signals.md

@@ -0,0 +1,123 @@
+# Engineering Risk Signals
+
+Use this reference during design review and after implementation. A risk signal is not automatically a
+defect; it is a prompt to identify ownership, invariant, and evidence.
+
+## Boundary risks
+
+- The same input is parsed or validated in several layers.
+- Domain code accepts raw dictionaries, generic maps, or untyped JSON.
+- Error translation happens in more than one boundary.
+- Transport, persistence, and domain types share one representation.
+- Configuration defaults silently change production behavior.
+
+Corrective direction: choose one trust boundary, parse once, use domain types internally, and translate
+errors once at the outward boundary.
+
+## State risks
+
+- Boolean combinations encode a hidden state machine.
+- A partially initialized object is publicly usable.
+- State transitions are spread across unrelated methods.
+- Cache, database, and memory can disagree without an authority rule.
+- Retry creates duplicate side effects.
+
+Corrective direction: name the states, constrain transitions, make idempotency explicit, and test crash or
+retry boundaries.
+
+## Concurrency risks
+
+- Work is launched without ownership, cancellation, or join semantics.
+- A timeout stops waiting but not the underlying operation.
+- Shared mutation relies on timing.
+- A channel or queue has no backpressure decision.
+- Tests use sleep to wait for completion.
+
+Corrective direction: bind child work to a lifetime, propagate cancellation, use observable completion
+signals, and verify with race or schedule exploration tools available to the language.
+
+## Error risks
+
+- An exception or error is caught and ignored.
+- Error text is used as a machine-readable code.
+- Context is replaced instead of chained.
+- A library terminates the process.
+- Success output can contain an embedded failure.
+
+Corrective direction: use typed outcomes, preserve causes, let the application boundary choose exit or
+response behavior, and test the outward observable contract.
+
+## Resource risks
+
+- Acquisition and release are far apart.
+- Cleanup runs only on the success path.
+- A background process, file, socket, transaction, or lock has no owner.
+- A pool or client uses unbounded defaults.
+- Temporary artifacts share production paths.
+
+Corrective direction: use lexical lifetime or explicit guards, bound pools and queues, isolate temporary
+state, and capture a cleanup receipt.
+
+## API risks
+
+- Callers pass several adjacent primitives with the same type.
+- Optional parameters change semantic mode.
+- One function both decides policy and performs I/O.
+- A return value mixes data, warnings, and failure without a tagged shape.
+- A supposedly internal type leaks into a public contract.
+
+Corrective direction: introduce semantic value types, separate policy from adapters, model outcomes as
+variants, and inventory downstream consumers before changing public shapes.
+
+## Test risks
+
+- Tests assert implementation order rather than observable behavior.
+- A mock returns exactly what the test later asserts.
+- Only a happy path exists.
+- Fixtures depend on wall time, global environment, or execution order.
+- Snapshot approval hides a semantic change.
+- A regression test passes before the fix is applied.
+
+Corrective direction: prove a failing-first behavior, prefer real values and narrow fakes, control clocks
+and randomness, and add one real-surface scenario.
+
+## Performance risks
+
+- Optimization is justified by intuition rather than a profile.
+- Benchmark input is unlike production.
+- Allocation or caching trades are undocumented.
+- Latency percentiles are replaced by an average.
+- Faster code weakens correctness or cancellation.
+
+Corrective direction: define a budget, capture a baseline, profile the actual workload, change one cause,
+and compare distributions with the same environment.
+
+## Maintainability risks
+
+- A name describes mechanism instead of responsibility.
+- One file changes for unrelated reasons.
+- A helper has one caller and hides a simple operation.
+- A generic abstraction has only one concrete use.
+- Comments repeat syntax instead of stating invariants or decisions.
+- Generated and hand-edited code are indistinguishable.
+
+Corrective direction: keep cohesive ownership, wait for a second use before generalizing, and document the
+reason a constraint exists.
+
+## Review procedure
+
+For each observed signal, write:
+
+```text
+Signal:
+Concrete location:
+Invariant at risk:
+Current evidence:
+Smallest safe correction:
+Verification:
+Decision: fix now | explicitly accept | out of scope
+```
+
+Do not expand scope merely because a signal exists. Fix it now when it blocks the requested behavior,
+makes the requested edit unsafe, or would make verification meaningless. Otherwise report it as a bounded
+risk with a concrete location.

package/marketplace/plugins/litcodex/skills/lit-code/references/go/README.md

@@ -0,0 +1,90 @@
+
+# Go Programmer
+
+Production Go in 2026. **Boring on purpose, strict by tooling, illegal states unrepresentable by convention.**
+
+## Philosophy
+
+Go gives you fewer type-system tools than Python, TypeScript, or Rust:
+
+- No sum types — only `interface{}` with type-switch.
+- No exhaustiveness check from the compiler — only the `exhaustive` linter.
+- No `Option<T>` — only `nil` and the eternal trap of "is this nil interface or nil concrete?".
+- No `Result<T, E>` — only `(T, error)`, no compiler enforcement of unwrapping.
+- No newtype that prevents primitive coercion — `type UserID string` is still implicitly convertible from a literal when used carelessly.
+
+**This is the whole point of the skill.** Where the language is weak, the linter bundle becomes the type checker, and code patterns become the type system. Treat `golangci-lint v2` with the configuration in `golangci-strict.md` as if it were `tsc --strict` or `basedpyright`. Treat `nilaway` and `go test -race` as if they were Miri.
+
+The skill enforces five non-negotiables:
+
+1. **Parse-don't-validate at every boundary.** HTTP/RPC/CLI/config gets parsed into a domain struct constructed only via `New*(...)` smart constructors. Once inside the domain, no further validation. See `data-modeling.md`.
+2. **`(T, error)` everywhere.** No panics in library code. No bare `_ = err`. Errors are wrapped with `%w` and asserted with `errors.Is` / `errors.As`. Typed error structs for anything a caller can branch on. See `error-handling.md`.
+3. **Sealed interfaces for variants.** Sum types via a sealed unexported method, dispatched through a `type switch`, with the `exhaustive` linter checking completeness. See `type-patterns.md`.
+4. **`context.Context` is the first parameter.** Always. No `context.Background()` inside leaf functions. No goroutine without context-driven shutdown. No `time.Now()` in domain code — inject a clock. See `concurrency.md`.
+5. **Generated, not hand-written, for external contracts.** `sqlc` for DB, `oapi-codegen` for OpenAPI servers and clients, `protoc-gen-go` + `protoc-gen-connect-go` for RPC. Hand-rolled marshalling is a regression. See `sqlc-pgx.md`, `grpc-connect.md`.
+
+## Hard rules — tooling
+
+| Category | Use | Never |
+|---|---|---|
+| Go version | **1.23+** (range-over-func, iter package, slog stable) | <1.22 |
+| Module | `go modules` + `go work` for monorepos | dep, GOPATH layouts |
+| Format | **`gofumpt`** (stricter gofmt) + `goimports -local <module>` | bare `gofmt` |
+| Linter | **`golangci-lint v2`** with the strict bundle in `golangci-strict.md` | bare `go vet` |
+| Nil checker | **`nilaway`** (Uber, stable since 2024) in CI | hope |
+| Vet bundle | `go vet` + `fieldalignment` + `shadow` | "tests cover it" |
+| Tests | `go test -race -shuffle=on -count=1` | `-count` cache, no race |
+| Goroutine leaks | `go.uber.org/goleak` in `TestMain` | "looks fine" |
+| Mock | `go.uber.org/mock` (gomock successor) | hand-written stubs |
+| DB | `sqlc` + `jackc/pgx/v5` | `database/sql` + `gorm` |
+| HTTP framework | **`gin-gonic/gin`** (de facto, ~48% of Go API repos) — `go-chi/chi` for minimalist, `connectrpc/connect-go` for RPC | `echo` (smaller eco), `fiber` (fasthttp = non-stdlib), `gorilla/mux` (in maintenance mode) |
+| RPC | **`connectrpc/connect-go`** (gRPC-compatible, HTTP/1.1-friendly, browser-friendly) | hand-rolled `grpc-go` unless you specifically need bidi streaming features Connect lacks |
+| Validation | `go-playground/validator/v10` for HTTP boundary + `bufbuild/protovalidate-go` for proto + smart constructors for domain | ad-hoc `if len(s) == 0` chains |
+| Config | `caarlos0/env/v11` (struct-tag env) | `viper` unless you actually need file+env+flag merging |
+| Logging | **`log/slog`** (stdlib, Go 1.21+) | logrus, zap, zerolog (all superseded) |
+| CLI | `spf13/cobra` | hand-rolled `os.Args` parsing past 2 flags |
+| TUI | `charm.land/bubbletea/v2` + `bubbles/v2` + `lipgloss/v2` — see `bubbletea-v2.md` for CJK/IME | bubbletea v1 if you need IME |
+
+A single CI command should be the gate:
+
+```bash
+gofumpt -l . && \
+  golangci-lint run ./... && \
+  nilaway ./... && \
+  go test -race -shuffle=on -count=1 ./...
+```
+
+If any of these fails, the change is not done. Period. The bundle is set up so a clean run actually means clean — see `golangci-strict.md` for the per-linter rationale and the deliberate `nolint:` policy.
+
+## Hard rules — code
+
+Read these per-file references for the canonical patterns:
+
+- **Types & data** → `type-patterns.md`, `data-modeling.md` — branded named types, smart constructors with unexported fields, sealed interfaces as sum types.
+- **Errors** → `error-handling.md` — sentinel vs typed struct, `errors.Is/As`, `%w` wrapping, no panic in libraries, the `errorlint` ruleset.
+- **Concurrency** → `concurrency.md` — `context.Context` discipline, `errgroup`, `sync.OnceValue`, `goleak`, `-race`, channel selection rules.
+- **HTTP backend** → `backend-stack.md` — `gin` server skeleton, middleware ordering, SSE/streaming with `http.Flusher`, structured slog logging, graceful shutdown — distilled from the CLIProxyAPI codebase (a real proxy serving OpenAI/Gemini/Claude APIs).
+- **RPC** → `grpc-connect.md` — when to pick Connect vs grpc-go, codegen pipeline, protovalidate, streaming.
+- **DB** → `sqlc-pgx.md` — compile-time-safe SQL via sqlc + pgx connection pool + migrations via goose + testcontainers in CI.
+- **CLI** → `cobra-stack.md` — cobra layout, slog integration, graceful shutdown on signals, fang-style colored help.
+- **TUI** → `bubbletea-v2.md` — v2 model, `SetVirtualCursor(false)` + `tea.View{Cursor}` for CJK IME, why v1 was broken for Korean/Japanese/Chinese input.
+- **Testing** → `testing.md` — table-driven tests, `require` vs `assert`, `autogold` snapshots, `gopter` property tests, `testcontainers` for integration, `goleak` for goroutine leaks.
+- **Bootstrap** → `bootstrap.md` — `new-project.go` invocation, project layout (`cmd/`, `internal/`, `pkg/`), Taskfile, CI.
+- **Strict config** → `golangci-strict.md` — the canonical `.golangci.yml` with the full linter whitelist and per-linter rationale.
+- **One-liners** → `one-liners.md` — `go run` scripts with `//go:build ignore`, `gorun`-style invocation.
+
+## The 250 pure LOC ceiling
+
+Same rule as Python/Rust/TS: a `.go` file whose pure LOC (non-blank, non-comment) exceeds 250 is architecturally broken. Go encourages many small files in a single package, so this is *more* natural here than elsewhere — split by responsibility, keep one cohesive type and its methods per file.
+
+The `cmd/server/main.go` is the most common violator. Refactor it: `main.go` only wires `os.Args` → `cmd.Execute()`. Anything else lives in `internal/`.
+
+## Existing codebases — non-strict project
+
+When editing an existing `.go` file that doesn't follow these rules: **write new code in strict style, don't refactor existing code in the same change.** Use the `lit-burnoff` skill for branch-scope cleanup.
+
+## Activation
+
+This skill activates whenever you write or modify any `.go` file, `go.mod`, `go.sum`, `.golangci.yml`, `Taskfile.yml`, or any of the codegen specs (`*.proto`, `*.sql` next to `sqlc.yaml`, `openapi.yaml` next to `oapi-codegen.yaml`). Even one-off scripts get the strict treatment — that is what `//go:build ignore` + `go run` is for: production hygiene with throwaway ergonomics.
+
+The references contain the recipes. **Read them before writing code. Re-read them when the model drifts.** The post-write architectural review loop is non-negotiable.