@gobing-ai/spur 0.3.41 → 0.3.43

package/plugins/sp/skills/code-simplification/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: code-simplification
+description: "Simplify code for clarity without changing behavior. Use when refactoring for readability or reducing complexity."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - simplify
+  openclaw:
+    emoji: "🧹"
+see_also:
+  - sp:code-review
+  - sp:code-implementation
+  - sp:test-driven-development
+---
+
+# code-simplification — the simplification competency
+
+Reduce complexity while preserving **exact** behavior. The goal is not fewer lines — it is code a
+new reader understands faster. Every simplification must pass one test: *would a teammate understand
+this version quicker than the original, and produce the same output for every input?* If either
+answer is no, don't make the change.
+
+This is a **technique** skill: it guides edits to source, it does not write task sections. When the
+simplification lands inside a task, the `## Solution` change-map and status transitions stay with the
+spine and `sp:code-implementation` — this skill owns *how to simplify well*.
+
+## When to use
+
+- A feature works and tests pass, but the implementation reads heavier than it needs to.
+- Review flagged readability or complexity (`sp:code-review` → this skill for the fix).
+- Deep nesting, long functions, unclear names, or duplicated logic in code you just touched.
+- Consolidating related logic that drifted apart under time pressure.
+
+Do **not** use this skill for:
+
+- **Already-clean code** — simplifying for its own sake is churn, not improvement.
+- **Code you don't yet understand** — comprehend first (see Step 1); you cannot preserve behavior
+  you can't describe.
+- **Hot paths where the simpler form is measurably slower** — clarity does not outrank a real,
+  measured performance requirement.
+- **Throwaway code about to be rewritten** — simplifying code you're deleting wastes effort.
+
+## Five principles
+
+1. **Preserve behavior exactly.** Only how the code reads changes — never inputs, outputs, side
+   effects, error behavior, ordering, or edge cases. Unsure a change is behavior-preserving? Don't
+   make it. If a "simplification" needs a test edited to pass, you changed behavior — revert.
+2. **Follow project conventions.** Read `AGENTS.md` / `CLAUDE.md` and match neighboring code: import
+   style, declaration form, naming, error handling, type-annotation depth. Simplification that
+   breaks codebase consistency is churn, not simplification.
+3. **Prefer clarity over cleverness.** Explicit beats compact when the compact form needs a mental
+   pause to parse. A one-line nested ternary is not simpler than a five-line `if` chain.
+4. **Maintain balance.** Over-simplification is a real failure mode: don't inline a helper that gave
+   a concept a name, don't merge two clear functions into one tangled one, don't strip an abstraction
+   that earns its keep for testability or a second caller, and don't optimize for line count.
+5. **Scope to what changed** (R3 — surgical changes). Default to recently-modified code. No drive-by
+   refactors of unrelated code unless the operator widens the scope; unscoped edits create noisy
+   diffs and regressions in code you never meant to touch.
+
+## The process
+
+### Step 1 — Understand before touching (Chesterton's Fence)
+
+Before changing or removing anything, know why it exists. Answer these; if you can't, read more
+context first — you are not ready to simplify:
+
+- What is this code's single responsibility? What calls it, and what does it call?
+- What are its edge cases and error paths? Which tests pin the expected behavior?
+- Why might it be shaped this way — a performance constraint, a platform quirk, a historical reason?
+  Check `git blame` / `git log` for the original context.
+
+#### Over-Engineering Classifier & Reserved Pattern Audit
+
+When encountering complex or indirect abstractions (factories, strategies, deep wrappers), classify them before acting:
+
+1. **Accidental LLM Over-Engineering**: Generic wrappers over single primitives, factory-for-a-factory, or single-implementation interfaces introduced during broad AI generation without sufficient local context.
+2. **Intentional Reserved Patterns**: Architectural extension points, framework contracts, or documented anchors reserved for upcoming roadmap features.
+
+#### HITL Confirmation Gate for Over-Engineering Removal
+
+If an abstraction appears to be accidental over-engineering:
+
+```text
+IF abstraction has 0 callers or adds indirection without distinct value →
+  Formulate proposal:
+    - Target: file:line and symbol signature
+    - Reason: why it appears over-engineered
+    - Pros: reduced cognitive load, fewer lines, simpler debugging
+    - Cons / Risks: re-implementation cost if reserved for planned features
+    - Recommendation & Rationale: explicit recommendation (Remove vs Keep)
+  Present proposal to user → DO NOT delete until operator confirms.
+```
+
+### Step 2 — Identify opportunities
+
+Each pattern below is a concrete signal, not a vague smell. Match against the target code.
+
+**Structural complexity**
+
+| Pattern | Signal | Move |
+|---------|--------|------|
+| Deep nesting (3+ levels) | Control flow hard to follow | Guard clauses / extracted helpers |
+| Long function (50+ lines) | Multiple responsibilities | Split into focused, named functions |
+| Nested ternaries | Needs a mental stack to parse | `if`/`else`, `switch`, or a lookup map |
+| Boolean-flag params (`fn(true, false)`) | Opaque call sites | Options object or separate functions |
+| Repeated conditional | Same check in many places | Extract a well-named predicate |
+
+**Naming & readability**
+
+| Pattern | Signal | Move |
+|---------|--------|------|
+| Generic names (`data`, `result`, `tmp`) | No intent conveyed | Rename for content (`userProfile`) |
+| Misleading name | `get*` that also mutates | Rename to the real behavior |
+| Comment restating the code | `// increment counter` over `count++` | Delete it |
+| Comment carrying intent | `// retry: the API is flaky under load` | Keep it — the code can't say why |
+
+**Redundancy & Over-engineering**
+
+| Pattern | Signal | Move |
+|---------|--------|------|
+| Duplicated logic (local) | Same shape in 2+ places within scope | Extract local helper function |
+| Duplicated logic (cross-module) | Common pattern across files | Follow 5-Stage Common Pattern Consolidation |
+| Dead code | Unreachable branch, unused var, commented block | Remove after confirming it's dead |
+| Pass-through wrapper | Adds indirection, no value | Inline it (after HITL confirmation) |
+| Over-engineered pattern | Factory-for-a-factory, one-strategy strategy | Replace with direct approach (after HITL confirmation) |
+
+#### 5-Stage Common Pattern Consolidation Protocol
+
+When identical or structurally near-identical operations repeat across multiple locations:
+
+1. **Identify Candidate Patterns**: Locate repeated operations across files/modules within the allowed scope.
+2. **Operator Confirmation Gate**: Present proposed shared helper/utility signature, suggested module location (e.g. `utils/`, `helpers/`, or shared domain module), affected files/lines, and coupling trade-offs to the end user.
+3. **Implement Shared Unit**: After confirmation, author the shared helper/class in the appropriate shared location with dedicated unit tests in isolation.
+4. **Refactor Call-Sites**: Replace repeating logic site-by-site with invocations of the shared helper.
+5. **Regression Verification**: Run the project validation command (`--check <cmd>`) to verify all callers pass existing and unit tests cleanly.
+
+A couple of stack-native examples (the discipline is stack-agnostic; these happen to be `bun:test` TS):
+
+```typescript
+// nested conditionals → guard clauses (same behavior, shallower)
+function process(data: Input) {
+  if (data == null) throw new TypeError('data is null');
+  if (!isValid(data)) throw new ValidationError('invalid data');
+  return doWork(data);
+}
+
+// manual accumulation → intent-revealing builtin
+const activeUsers = users.filter((u) => u.isActive);
+
+// redundant boolean round-trip
+function isValid(input: string): boolean {
+  return input.length > 0 && input.length < 100;
+}
+```
+
+### Step 3 — Apply incrementally
+
+One simplification at a time. After each: run the **narrowest** test that covers it (`bun test <file>`
+or the stack's equivalent). Passes → keep or continue; fails → revert that one change and reconsider.
+Never batch untested simplifications — if something breaks you must know which change caused it.
+
+**Separate refactoring from feature work.** A change that simplifies *and* adds behavior is two
+changes; split them. **Rule of 500:** a refactor touching 500+ lines wants a codemod / AST transform,
+not hand edits — manual work at that scale is error-prone and unreviewable.
+
+### Step 4 — Verify the result
+
+Step back and judge the whole diff, not each edit:
+
+- Is the result genuinely easier to understand, or just shorter?
+- Did you introduce a pattern inconsistent with the codebase?
+- Is the diff clean and reviewable, with nothing unrelated mixed in?
+
+If the "simplified" version is harder to follow or review, revert it. Not every attempt succeeds, and
+a failed simplification honestly reverted beats a clever one shipped.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It works, don't touch it." | Working code that's hard to read is hard to fix when it breaks. The cost lands on every future change, not today. |
+| "Fewer lines is always simpler." | Comprehension speed is the metric, not line count. A dense one-liner can be the harder version. |
+| "I'll simplify this unrelated code too while I'm here." | Unscoped edits create noisy diffs and regressions in code you didn't mean to change. Stay in scope (R3). |
+| "The original author must have had a reason." | Maybe — check `git blame` (Chesterton's Fence). But accumulated complexity often has no reason; it's residue of iteration under pressure. |
+| "This abstraction might be useful later." | Speculative abstraction is complexity without a caller (R2). Remove it or confirm with operator; re-add when a second use actually arrives. |
+| "I'll delete this generic wrapper immediately without asking." | Over-engineered abstractions may be intentional reserved patterns; classify and confirm with pros/cons/recommendation first. |
+| "I'll refactor while I add this feature." | Mixed diffs are harder to review, revert, and read in history. Two changes, two commits. |
+| "The types make it self-documenting." | Types document structure, not intent. A well-named function says *why* a signature can't. |
+
+## Red Flags
+
+- Deleting an abstraction without checking if it's an intentional reserved pattern or confirming with the user.
+- Extracting shared utilities across modules without operator confirmation or isolated unit tests.
+- A simplification that required editing a test to pass — you changed behavior, not form.
+- The "simplified" code is longer or harder to follow than the original.
+- Renaming to your taste instead of the project's conventions.
+- Removing error handling because it "makes the code cleaner."
+- Simplifying code whose purpose you can't state in one sentence.
+- Many simplifications batched into one large, un-testable commit.
+- Refactoring outside the task's scope without being asked.
+
+## Verification
+
+After a simplification pass, confirm — with evidence, not assertion:
+
+- [ ] All existing tests pass **without modification** (paste the command + result).
+- [ ] Potential over-engineering evaluated, classified, and confirmed with operator before removal.
+- [ ] Common pattern extractions confirmed with operator, backed by isolated unit tests, and regression verified across call-sites.
+- [ ] Build succeeds; lint/format clean (no style regressions).
+- [ ] Each simplification is an incremental, reviewable change; the diff has nothing unrelated.
+- [ ] The result follows project conventions (`AGENTS.md` / `CLAUDE.md`).
+- [ ] No error handling was removed or weakened; no dead code left behind (unused imports, dead branches).
+- [ ] A reviewer (`sp:code-review`) would call the change a net improvement.
+
+## See also
+
+- **`sp:code-review`** — review the simplified diff; the review that flagged complexity hands the fix here.
+- **`sp:code-implementation`** — the implement step that produced the code being simplified.
+- **`sp:test-driven-development`** — the tests that pin behavior are the safety net that makes simplification safe.

package/plugins/sp/skills/code-testing/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: code-testing
+description: "The testing competency — run tests, measure coverage, categorize gaps, extend the suite with targeted tests across Bun/TS, Python, Go. Triggers: \"write tests\", \"measure coverage\", \"what's untested\", \"coverage gap\", \"extend the test suite\", \"run the tests\"."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  interactions:
+    - technique
+  competency: testing
+  openclaw:
+    emoji: "🧪"
+---
+
+# code-testing — the testing competency
+
+Run existing tests, measure what is covered, categorize the gaps, and extend the suite with targeted
+tests — language-agnostic spine with per-stack adapters. This is the deep competency the
+spine (`sp:spur-dev`) dispatches to at its `test` step (via `/sp:dev-unit`). It owns
+*how to test and measure coverage well*, not *when* (the spine decides that).
+
+## When to use
+
+- **Run + measure** — execute the suite, read the coverage report, identify untested paths.
+- **Gap-fill** — add targeted tests to close a coverage gap on existing code.
+- **The pipeline's `test` step** — `/sp:dev-unit <wbs>` dispatches here.
+
+Do **not** use this skill for:
+
+- **Writing the implementation** — that is `sp:code-implementation`.
+- **Test-first design (red-green-refactor)** — that is `sp:test-driven-development` (composed with this skill).
+- **Functional / requirements verification + review** — that is `sp:code-verification`.
+- **Driving the lifecycle** — that is the spine, `sp:spur-dev`.
+
+## Behavior
+
+This skill behaves as a **technique**: detect the stack → load the one matching adapter → run the
+suite → parse coverage → categorize gaps (untested branch, missing boundary, absent error path) →
+extend with the narrowest tests that close the highest-value gaps. Coverage is a signal, not the
+goal: it favors behavior-meaningful tests over line-chasing.
+
+Full procedure: **[references/unit-testing.md](references/unit-testing.md)** — file-focused vs
+task-scoped workflows, gap categorization, coverage-vs-quality rules, escalation. Per-stack
+mechanics (commands, coverage parsing, idioms, gotchas) live in the adapters:
+[references/stacks/](references/stacks/) — `bun-ts.md`, `python.md`, `go.md`.
+
+When a test is red, apply the **[test-loop breaker](references/test-loop-breaker.md)** before
+re-running it. Keep command output bounded without hiding the exit status by following
+**[test-output discipline](references/test-output-discipline.md)**.
+
+## Targeted-test-first verification loop
+
+When iterating on a red test, run the **narrow** target before any full-suite gate so the loop does
+not re-run the entire workspace on every attempt (task 0436 R2). Full-suite re-runs during a fix
+loop are the dominant verification cost on a long chain.
+
+1. Run the narrow target: `bun test <file> --test-name-pattern <test>` (or the stack-equivalent
+   single-test filter in the matching adapter).
+2. Loop on that narrow target until green.
+3. **Then** run the single full `spur-check` (or `bun run check`) as the final gate.
+
+Do not re-run the full suite per iteration, and do not run a full gate before the narrow target is
+green. Target: full `spur-check` runs ≤2 per task.
+
+## Composition with the discipline + implementation skills
+
+- **`sp:test-driven-development`** — they compose: TDD *designs* the tests (red-green-refactor, behavior naming,
+  mock-at-boundary); this skill *runs and extends* the suite for coverage. TDD is the how-to-design;
+  this skill is the run/measure/gap-fill.
+- **`sp:code-implementation`** — the implement step writes code; this step proves it. The per-stack
+  adapters here are also the stack-idiom reference `code-implementation` consults cross-skill.
+
+## Per-stack adapters
+
+| Detected by | Stack | Adapter |
+|-------------|-------|---------|
+| `bun.lock` / `bunfig.toml` | Bun + TypeScript | [stacks/bun-ts.md](references/stacks/bun-ts.md) |
+| `pyproject.toml` / `pytest` | Python | [stacks/python.md](references/stacks/python.md) |
+| `go.mod` | Go | [stacks/go.md](references/stacks/go.md) |
+
+## Gotchas
+
+1. **Coverage is a signal, not the target.** A test that survives a business-rule change is the
+   wrong test — assert intent, not implementation.
+2. **One adapter per run.** Detect the stack, load the single matching adapter; do not mix idioms.
+3. **Escalate to debugging when a failure needs root-causing**, not more test authoring
+   (`sp:code-implementation`'s debugging reference).
+
+## See also
+
+- **`sp:spur-dev`** — the spine that dispatches this competency at the `test` step.
+- **`sp:code-implementation`** — writes the code this skill tests; consults these stack adapters.
+- **`sp:test-driven-development`** — the test-first discipline this skill composes with.
+- **`sp:code-verification`** — functional/requirements verification + review (a distinct gate).
+- **[Verification Before Completion](../spur-dev/references/cross-cutting.md#verification-before-completion)** — no "coverage met / tests pass" claim without fresh, pasted evidence run this turn.
+
+## Platform Notes
+
+### Claude Code
+
+Invoked via `/sp:dev-unit <wbs>` (which the pipeline's `test` step calls), or directly via
+`Skill(skill="sp:code-testing", args="<target>")`. Run the test/coverage commands via the Bash tool.
+
+### Codex / OpenClaw / OpenCode / Antigravity
+
+Invoke this skill directly for testing technique; run the stack's test commands via the Bash tool.
+The skill is the SSOT; the command and pipeline step are thin wrappers.

package/plugins/sp/skills/code-testing/references/stacks/bun-ts.md

@@ -0,0 +1,165 @@
+---
+name: stacks/bun-ts
+description: "Stack adapter for Bun + TypeScript (and Node/TS) — test command, V8 coverage parsing, the V8 coverage-gap diagnostic, framework idioms. Loaded by unit-testing.md when the project uses bun/vitest/jest."
+see_also:
+  - unit-testing
+---
+
+# Stack adapter: Bun + TypeScript
+
+Mechanics for the [unit-testing.md](../unit-testing.md) spine when the project is Bun/TS (or Node/TS).
+The spine owns the procedure; this file owns Bun/TS commands, parsing, idioms, and gotchas.
+
+## Test + coverage command
+
+```bash
+bun test --coverage
+```
+
+Bun reports per-file `% Funcs` and `% Lines` (V8 coverage):
+
+```
+File          | % Funcs | % Lines | Uncovered Line #s
+--------------|---------|---------|------------------
+auth.ts       |   80.00 |   92.31 | 23-27
+--------------|---------|---------|------------------
+All files     |   77.00 |   90.48 |
+```
+
+Spur target: **per-file line ≥ 90% and function ≥ 90%** (`bunfig.toml`), suite fully passing.
+
+## Test-file convention
+
+Tests live in `<workspace>/tests/**/*.test.ts` next to the code (AGENTS.md). Use `bun:test`
+(`import { test, expect, describe } from "bun:test"`). For a loose source file with no test, create
+`tests/<name>.test.ts`.
+
+## Idioms
+
+**Branch / parameterized tests** — one test per branch:
+
+```typescript
+import { test, expect } from 'bun:test';
+
+for (const [user, amount, expected] of [
+  ['vip', 150, 120],
+  ['vip', 50, 45],
+  ['regular', 100, 100],
+] as const) {
+  test(`discount: ${user} on ${amount} → ${expected}`, () => {
+    expect(calculateDiscount(makeUser(user), amount)).toBe(expected);
+  });
+}
+```
+
+**Mock at the boundary** — inject the dependency; do not mock internal collaborators:
+
+```typescript
+test('fetchUser returns null on 404', async () => {
+  const result = await fetchUser(999, async () => ({ status: 404 }));
+  expect(result).toBeNull();
+});
+```
+
+**Inline coverage-exclusion rationale** (the accept-lower-coverage case):
+
+```typescript
+// NOTE: unreachable in production — the adapter guarantees a non-null row here.
+if (row == null) throw new Error('unreachable: adapter contract violated');
+```
+
+## Coverage-gap diagnostic (V8)
+
+Bun uses V8 function coverage, which produces artifacts that look like missing tests but are
+instrumentation/code-structure issues. **Rule these out before writing tests** — otherwise you write
+tests that cannot move the metric.
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `% Funcs` < threshold while `% Lines` ≥ threshold; child classes show "uncovered" | Implicit/synthetic constructor on a class that `extends` without an explicit `constructor()` | Add an explicit empty constructor with the sanctioned suppression (snippet 1) |
+| `% Funcs` < threshold; flagged functions are module-level arrows never called directly | Anonymous/unused arrow at module scope counted as an uncovered function | `export` the arrow as a named pure function and test it, or inline it (snippet 2) |
+| Coverage swings between runs; some files missing from the report entirely | File never imported by any test path, so V8 doesn't see it | Ensure the test (or a barrel imported by the test) statically imports every target module (snippet 3) |
+| Worker/temp paths in coverage output; `coverageExclude` in `bunfig.toml` has no effect | Dynamic `import()` spawns a worker; V8 tracks worker coverage globally and ignores `coverageExclude` | Prefer a mock module-loader over real `import()`; if required, clean up in `afterAll` and accept temp paths when failures == 0 (snippet 4) |
+
+### Snippet 1 — explicit empty constructor
+
+```typescript
+class Derived extends Base {
+  // biome-ignore lint/complexity/noUselessConstructor: V8 function coverage requires explicit constructor
+  constructor() {
+    super();
+  }
+}
+```
+
+This is the **only** sanctioned use of `biome-ignore lint/complexity/noUselessConstructor` in this
+project. Do not generalize it.
+
+### Snippet 2 — promote module-level arrows
+
+```typescript
+// Before: anonymous arrow at module scope, counted as an uncovered function
+const transform = (x: number) => x * 2;
+export function run(input: number[]) { return input.map(transform); }
+
+// After option A: export the pure function and test it directly
+export const transform = (x: number) => x * 2;
+
+// After option B: inline into the only caller, removing the module-level entry point
+export function run(input: number[]) {
+  return input.map((x) => x * 2);
+}
+```
+
+### Snippet 3 — ensure targets are loaded
+
+```typescript
+// In a test entry or a barrel imported by tests
+import '../src/foo';
+import '../src/bar';
+import '../src/baz';
+// Or maintain src/index.ts re-exporting everything, then `import '../src'` once.
+```
+
+V8 only counts files that are actually loaded. A barrel is the lowest-maintenance way to cover the
+whole module surface.
+
+### Snippet 4 — avoid the `import()` worker leak
+
+```typescript
+// Prefer: inject a loader so production code uses import() but tests use a mock
+type Loader = (id: string) => Promise<unknown>;
+export async function loadAndRun(id: string, load: Loader = (i) => import(i)) {
+  return load(id);
+}
+
+// In tests, pass a mock loader — no real import(), no worker thread
+test('loadAndRun uses the injected loader', async () => {
+  const result = await loadAndRun('ignored', async () => ({ ok: true }));
+  expect(result).toEqual({ ok: true });
+});
+```
+
+If real `import()` cannot be avoided: place teardown in `afterAll` (not `afterEach`) and treat temp
+paths in the coverage output as benign when the suite reports `0` failures.
+
+### When to escalate instead of patch
+
+- The diagnostic matches no symptom in the table → escalate (spine § Escalation).
+- Applying the matching fix moves the metric < 1% → likely a different root cause; escalate to debugging.
+- The fix would require disabling type/lint checks beyond snippet 1's sanctioned suppression → stop
+  and surface to the operator.
+
+## Node + TypeScript/JS (Vitest / Jest)
+
+When the project is Node-based (no `bun.lock`) the spine is identical; only the command and reporter
+change.
+
+| Framework | Command | Coverage report |
+|-----------|---------|-----------------|
+| Vitest | `npx vitest run --coverage` | `% Stmts / % Branch / % Funcs / % Lines` table (istanbul or v8 provider) |
+| Jest | `npx jest --coverage` | same table shape |
+
+Vitest with the `v8` provider shares the V8 gotchas above (synthetic constructors, module loading).
+With the istanbul provider, branch coverage is reported directly — prefer it for branch-sensitive
+code. Test files: `*.test.ts` / `*.spec.ts` per the project's existing convention.

package/plugins/sp/skills/code-testing/references/stacks/go.md

@@ -0,0 +1,88 @@
+---
+name: stacks/go
+description: "Stack adapter for Go — go test coverprofile command, per-function coverage parsing, table-driven test and interface-mocking idioms. Loaded by unit-testing.md for go.mod projects."
+see_also:
+  - unit-testing
+---
+
+# Stack adapter: Go
+
+Mechanics for the [unit-testing.md](../unit-testing.md) spine when the project is Go.
+
+## Test + coverage command
+
+```bash
+go test -v ./...                                         # run + interpret
+go test -coverprofile=coverage.out ./... && \
+  go tool cover -func=coverage.out                       # per-function coverage
+```
+
+`-func` output lists per-function and total coverage:
+
+```
+spur/internal/auth/auth.go:21:   ValidateEmail   100.0%
+spur/internal/auth/auth.go:42:   Login            66.7%
+total:                           (statements)     88.4%
+```
+
+Use the per-function column to target the lowest-covered functions first. `go tool cover
+-html=coverage.out` opens a line-level view for pinpointing branches.
+
+## Test-file convention
+
+Tests live beside the code as `<name>_test.go` in the same package. Use the standard `testing`
+package; no external runner.
+
+## Idioms
+
+**Table-driven tests** — the canonical Go pattern; one row per branch/edge:
+
+```go
+func TestValidateEmail(t *testing.T) {
+    tests := []struct {
+        name    string
+        email   string
+        wantErr bool
+    }{
+        {"valid standard", "user@example.com", false},
+        {"missing @", "userexample.com", true},
+        {"empty", "", true},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            if err := ValidateEmail(tt.email); (err != nil) != tt.wantErr {
+                t.Errorf("ValidateEmail(%q) err = %v, wantErr %v", tt.email, err, tt.wantErr)
+            }
+        })
+    }
+}
+```
+
+**Mock at the boundary via interfaces** — inject a fake implementing the dependency interface:
+
+```go
+func TestCreateUser_setsID(t *testing.T) {
+    repo := &MockRepository{SaveFunc: func(u *User) error { u.ID = 123; return nil }}
+    if err := NewUserService(repo).CreateUser(&User{Name: "Test"}); err != nil {
+        t.Fatalf("CreateUser() err = %v", err)
+    }
+}
+```
+
+**Inline coverage-exclusion rationale** — Go has no built-in line-exclusion pragma; document the
+unreachable branch in a comment and exclude the file/function at the report level if needed:
+
+```go
+// unreachable in production: the adapter guarantees a non-nil row here.
+if row == nil {
+    panic("unreachable: adapter contract violated")
+}
+```
+
+## Notes
+
+- Go reports **statement** coverage, not branch coverage — a fully-covered statement count can still
+  miss a branch. For branch-sensitive logic, ensure the table has a row per branch and read the
+  `-html` view to confirm both sides of each conditional are green.
+- Generated code (protobuf, mocks) is conventionally excluded by build tag or a `//go:generate`
+  boundary; do not chase coverage on it.