lgtm-specs 0.0.4

package/rules/laws/git/README.md

@@ -0,0 +1,31 @@
+# The Law of Git
+
+These rules define the rigorous communication protocol for Git version control.
+
+## Index
+
+- [GIT-00001: The Atomic Commit](GIT-00001-atomic-commit.md)
+- [GIT-00002: The Imperative Subject](GIT-00002-imperative-subject.md)
+- [GIT-00003: The 50/72 Rule](GIT-00003-formatting-50-72.md)
+- [GIT-00004: Trunk-Based Flow](GIT-00004-trunk-based.md)
+- [GIT-00005: Public History Immutability](GIT-00005-public-immutability.md)
+- [GIT-00006: Cryptographic Identity](GIT-00006-signing.md)
+- [GIT-00007: Reviewer Capital](GIT-00007-reviewer-capital.md)
+- [GIT-00008: Logical Commit Series Structure](GIT-00008-patch-series.md)
+- [GIT-00009: Branch Naming](GIT-00009-branch-naming.md)
+- [GIT-00010: Pull Request Hygiene](GIT-00010-pr-hygiene.md)
+- [GIT-00011: Merge Method (No Squash)](GIT-00011-merge-method.md)
+- [GIT-00012: Conflict Resolution](GIT-00012-conflict-resolution.md)
+- [GIT-00013: Ignore Standards](GIT-00013-ignore-standards.md)
+- [GIT-00014: Large Binaries via LFS](GIT-00014-lfs-large-binaries.md)
+- [GIT-00015: Git Hooks as a Fast Gate](GIT-00015-git-hooks.md)
+- [GIT-00016: Branch Protection Policy](GIT-00016-branch-protection.md)
+- [GIT-00017: Secrets Management](GIT-00017-secrets-management.md)
+- [GIT-00018: CI Enforcement](GIT-00018-ci-enforcement.md)
+- [GIT-00019: Code Review Checklist](GIT-00019-review-checklist.md)
+- [GIT-00020: Issue Reference Standards](GIT-00020-issue-references.md)
+- [GIT-00021: Partial Staging for Atomic Commits](GIT-00021-partial-staging.md)
+- [GIT-00022: Feature Flags for Trunk Discipline](GIT-00022-feature-flags.md)
+- [GIT-00023: Breaking Change Management](GIT-00023-breaking-changes.md)
+- [GIT-00024: Dependency Management in Version Control](GIT-00024-dependency-management.md)
+- [GIT-00025: Large Repository Optimization](GIT-00025-large-repository-optimization.md)

package/rules/laws/go/GO-00001-actor-model.md

@@ -0,0 +1,51 @@
+# The Actor Model (GO-00001)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/01-concurrency.md#concurrency-architecture-the-actor-model)
+**Tags**: #structural #go #concurrency #actor-model
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Do not communicate by sharing memory; instead, share memory by communicating.
+
+## Requirements
+
+1.  **State Isolation**: An Actor (goroutine) owns its state exclusively.
+2.  **Message Passing**: Communicate only via channels.
+3.  **Lifecycle**: Never start a goroutine without a `select { case <-ctx.Done(): return }` loop.
+
+## Anti-Patterns
+
+- **Shared State**: Accessing a map from multiple goroutines without explicit locking (Race Condition).
+- **Leakage**: Goroutines that run forever because they ignore cancellation.
+
+## Examples
+
+**Bad:**
+
+```go
+// Race condition: 'counts' accessed by multiple workers without sync
+func worker(counts map[string]int) {
+  counts["key"]++ // CRASH
+}
+```
+
+**Good:**
+
+```go
+// Safe: State owned by single actor, updated via messages
+func counterActor(ctx context.Context, updates <-chan string) {
+  counts := make(map[string]int)
+  for {
+    select {
+    case <-ctx.Done():
+      return
+    case u, ok := <-updates:
+      if !ok {
+        return
+      }
+      counts[u]++
+    }
+  }
+}
+```

package/rules/laws/go/GO-00002-api-design.md

@@ -0,0 +1,37 @@
+# API Design (GO-00002)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/02-api-design.md#2-interface-design)
+**Tags**: #structural #go #interface #isp
+**Related**: [ISP](../../constitution/CONS-00004-isp.md)
+
+## Definition
+
+Accept Interfaces, Return Structs.
+
+## Requirements
+
+1.  **Consumer-Defined**: Interfaces should be defined where they are used, not where they are implemented.
+2.  **Concrete Returns**: Functions should return structs to allow future expansion (adding methods) without breaking callers.
+
+## Anti-Patterns
+
+- **Preemptive Interfaces**: Defining `IService` inside the `service` package that mirrors the struct methods exactly.
+- **Returning Interfaces**: `func New() StoreInterface`. This locks the implementation and forces all callers to update if the interface changes.
+
+## Examples
+
+**Bad:**
+
+```go
+type Storer interface { Save() }
+func NewStore() Storer { ... } // Returns interface
+```
+
+**Good:**
+
+```go
+func NewStore() *Store { ... } // Returns struct
+// Interface defined by consumer:
+type Saver interface { Save() }
+func UseStore(s Saver) { ... }
+```

package/rules/laws/go/GO-00003-error-handling.md

@@ -0,0 +1,43 @@
+# Error Handling (GO-00003)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/04-errors.md#error-handling)
+**Tags**: #behavioral #go #errors #resilience
+**Related**: [Transparency](../../constitution/CONS-00027-transparency.md)
+
+## Definition
+
+Errors are values and must be handled explicitly using modern Go patterns.
+
+## Requirements
+
+1.  **Wrapping**: Use `fmt.Errorf("doing x: %w", err)` to add context.
+2.  **Checks**: Use `errors.Is(err, Target)` for sentinel checks. Never use `==`.
+3.  **Aggregation**: Use `errors.Join(err1, err2)` (Go 1.20+) for collecting errors (e.g., in defer cleanup).
+
+## Anti-Patterns
+
+- **Raw Returns**: Returning `err` without context (makes debugging impossible).
+- **Type Assertions**: Using `err.(MyError)` without `errors.As`.
+
+## Examples
+
+**Bad:**
+
+```go
+func Close() error {
+  err1 := f.Close()
+  err2 := net.Close()
+  if err1 != nil { return err1 } // Swallows err2
+  return err2
+}
+```
+
+**Good:**
+
+```go
+func Close() error {
+  err1 := f.Close()
+  err2 := net.Close()
+  return errors.Join(err1, err2)
+}
+```

package/rules/laws/go/GO-00004-context.md

@@ -0,0 +1,45 @@
+# Context Propagation (GO-00004)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/03-resilience.md#1-context-propagation-the-red-thread)
+**Tags**: #runtime #go #concurrency #context
+**Related**: [Resilience](../../constitution/CONS-00026-resilience.md)
+
+## Definition
+
+The `context.Context` is the "Red Thread" that binds a request's lifecycle.
+
+## Requirements
+
+1.  **First Argument**: Every function doing I/O must accept `ctx context.Context` as the first arg.
+2.  **ErrGroup**: Use `golang.org/x/sync/errgroup` to manage groups of goroutines with shared cancellation.
+3.  **Respect**: Check `ctx.Err()` or `select <-ctx.Done()` before doing work.
+
+## Anti-Patterns
+
+- **Background**: Using `context.Background()` inside a request handler.
+- **Unmanaged Goroutines**: `go func()` without a mechanism to cancel it via context.
+
+## Examples
+
+**Bad:**
+
+```go
+go func() {
+  doWork() // No cancellation context
+}()
+```
+
+**Good:**
+
+```go
+g, ctx := errgroup.WithContext(ctx)
+g.Go(func() error {
+  return doWork(ctx)
+})
+g.Go(func() error {
+  return doOtherWork(ctx)
+})
+if err := g.Wait(); err != nil {
+    return fmt.Errorf("worker failed: %w", err)
+}
+```

package/rules/laws/go/GO-00005-performance.md

@@ -0,0 +1,40 @@
+# Runtime Performance (GO-00005)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/05-performance.md#performance--efficiency)
+**Tags**: #runtime #go #performance #efficiency
+**Related**: [Efficiency](../../constitution/CONS-00025-efficiency.md)
+
+## Definition
+
+Optimize for the Runtime (Garbage Collector and Allocator).
+
+## Requirements
+
+1.  **Pre-allocation**: Use `make([]T, 0, capacity)` to avoid resize copying.
+2.  **Reuse**: Use `sync.Pool` for short-lived buffers.
+3.  **Value Semantics**: Pass small structs by value; huge structs by pointer.
+
+## Anti-Patterns
+
+- **Append Loops**: Appending to a nil slice inside a loop without pre-alloc.
+- **Interface Boxing**: Assigning large values to `interface{}` in hot paths.
+
+## Examples
+
+**Bad:**
+
+```go
+var list []int
+for i := 0; i < 1000; i++ {
+  list = append(list, i) // Resizes multiple times
+}
+```
+
+**Good:**
+
+```go
+list := make([]int, 0, 1000) // One allocation
+for i := 0; i < 1000; i++ {
+  list = append(list, i)
+}
+```

package/rules/laws/go/GO-00006-packages.md

@@ -0,0 +1,29 @@
+# Clean Packages (GO-00006)
+
+**Source**: [Standard Go Project Layout](../../../docs/meta/languages/go/08-config-layout.md#1-the-standard-layout)
+**Tags**: #structural #go #architecture #naming
+**Related**: [Deep Modules](../../constitution/CONS-00009-deep-modules.md)
+
+## Definition
+
+Package names must describe _what_ they provide. Project layout must follow the Standard Go Layout.
+
+## Requirements
+
+1.  **Layout**: Use `/cmd` for entry points, `/internal` for private logic, `/pkg` for public libraries.
+2.  **Naming**: Reject `utils`, `common`. Use domain-driven names (`auth`, `cryptography`).
+3.  **Encapsulation**: Put business logic in `internal/` to prevent accidental external dependency.
+
+## Anti-Patterns
+
+- **Flat Structure**: Putting everything in root for a complex app.
+- **Bucket Packages**: Dumping unrelated functions into `common`.
+
+## Examples
+
+**Bad:**
+`package utils`
+
+**Good:**
+`cmd/server/main.go`
+`internal/auth/service.go`

package/rules/laws/go/GO-00007-circuit-breakers.md

@@ -0,0 +1,43 @@
+# Circuit Breakers (GO-00007)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/03-resilience.md#2-circuit-breakers--rate-limiting)
+**Tags**: #runtime #go #resilience #reliability
+**Related**: [Fallacies](../../constitution/CONS-00019-fallacies.md)
+
+## Definition
+
+Fail fast when dependencies are unhealthy to prevent cascading failures.
+
+## Requirements
+
+1.  **Wrap Calls**: Wrap all external network calls in a Circuit Breaker.
+2.  **State Machine**: Implement Closed -> Open -> Half-Open states.
+3.  **Fast Failure**: Return "Circuit Open" error immediately without network IO when open.
+
+## Anti-Patterns
+
+- **Blind Retries**: Retrying a down service 10 times, DDoSing it.
+- **Manual Reset**: Requiring human intervention to close the circuit (should be automatic after timeout).
+
+## Examples
+
+**Bad:**
+
+```go
+func Call() error {
+  return http.Get(url) // Can hang or fail repeatedly
+}
+```
+
+**Good:**
+
+```go
+func Call() error {
+  if breaker.IsOpen() {
+    return ErrCircuitOpen
+  }
+  err := http.Get(url)
+  breaker.Record(err)
+  return err
+}
+```

package/rules/laws/go/GO-00008-safety.md

@@ -0,0 +1,39 @@
+# Concurrency Safety (GO-00008)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/06-safety.md#implementation-safety)
+**Tags**: #behavioral #go #concurrency #safety
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Go's built-in types (Map, Slice) are NOT safe for concurrent access.
+
+## Requirements
+
+1.  **Maps & Slices**: Protect shared maps/slices with a `sync.Mutex` or `sync.RWMutex`.
+2.  **Pointers**: Always pass synchronization primitives (`sync.Mutex`, `sync.WaitGroup`) by pointer. Copying them breaks the lock.
+3.  **Atomics**: Use `sync/atomic` for simple counters to avoid Mutex overhead.
+
+## Anti-Patterns
+
+- **Race Conditions**: Reading and writing a map from different goroutines without a lock.
+- **Copied Locks**: `func foo(mu sync.Mutex)` (Pass by value).
+
+## Examples
+
+**Bad:**
+
+```go
+// Lock is copied!
+func foo(mu sync.Mutex) {
+  mu.Lock()
+}
+```
+
+**Good:**
+
+```go
+func foo(mu *sync.Mutex) {
+  mu.Lock()
+}
+```

package/rules/laws/go/GO-00009-table-driven-test.md

@@ -0,0 +1,48 @@
+# Table-Driven Tests (GO-00009)
+
+**Source**: [Unit Testing Guidelines](../../../docs/meta/languages/go/07-testing.md#2-table-driven-tests)
+**Tags**: #operational #go #testing #tdd
+**Related**: [Test Structure](GO-00015-aaa-pattern.md)
+
+## Definition
+
+Use table-driven tests to exercise the same logic with varying data.
+
+## Requirements
+
+1.  **Data Only**: The test case struct must contain only data (inputs, expected outputs). It must NOT contain functions or setup logic.
+2.  **Identical Arrange**: The setup block inside the loop must be identical for every case.
+3.  **No Conditionals**: If you need `if tc.flag` to change the mock setup, you must NOT use a table test. Use a standalone test.
+
+## Anti-Patterns
+
+- **Logic in Structs**: `struct { setup func() }`. This hides the test behavior.
+- **Branching Tests**: A single test loop trying to handle "Success" and "Not Found" where the mock calls differ entirely.
+
+## Examples
+
+**Bad:**
+
+```go
+cases := []struct {
+  setup func() // Logic hidden here
+}{ ... }
+```
+
+**Good:**
+
+```go
+cases := []struct {
+  name string
+  in   int
+  want int
+}{ ... }
+
+for _, tc := range cases {
+  t.Run(tc.name, func(t *testing.T) {
+    // Identical Arrange/Act/Assert
+    got := Do(tc.in)
+    require.Equal(t, tc.want, got)
+  })
+}
+```

package/rules/laws/go/GO-00010-escape-analysis.md

@@ -0,0 +1,37 @@
+# Escape Analysis (GO-00010)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/05-performance.md#2-compiler-optimizations)
+**Tags**: #runtime #go #performance #compiler
+**Related**: [Efficiency](../../constitution/CONS-00025-efficiency.md)
+
+## Definition
+
+Ensure variables are allocated on the stack instead of the heap where possible to reduce GC pressure.
+
+## Requirements
+
+1.  **Check**: Use `go build -gcflags="-m"` to verify escape decisions.
+2.  **Pointers**: Avoid returning pointers to small structs; return by value to keep them on the stack.
+
+## Anti-Patterns
+
+- **Blind Allocation**: Assuming everything is on the stack.
+- **Interface Boxing**: Assigning a small value to an `interface{}` causes it to escape.
+
+## Examples
+
+**Bad:**
+
+```go
+func NewPoint(x, y int) *Point {
+  return &Point{x, y} // Escapes to heap
+}
+```
+
+**Good:**
+
+```go
+func NewPoint(x, y int) Point {
+  return Point{x, y} // Stays on stack
+}
+```

package/rules/laws/go/GO-00011-retry.md

@@ -0,0 +1,45 @@
+# Retry Strategy (GO-00011)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/03-resilience.md#3-retry-with-backoff)
+**Tags**: #runtime #go #resilience #reliability
+**Related**: [Fallacies](../../constitution/CONS-00019-fallacies.md)
+
+## Definition
+
+Handle transient failures gracefully with exponential backoff and jitter.
+
+## Requirements
+
+1.  **Transient Only**: Only retry errors that are likely to succeed later (Network, 503). Never retry 400 Bad Request.
+2.  **Backoff**: Use exponential backoff (1s, 2s, 4s).
+3.  **Jitter**: Add random jitter (+/- 10%) to prevent Thundering Herd.
+
+## Anti-Patterns
+
+- **Immediate Retry**: `for { try() }` (CPU spin).
+- **Infinite Retry**: Retrying forever without a deadline.
+
+## Examples
+
+**Bad:**
+
+```go
+for i := 0; i < 3; i++ {
+  if err := connect(); err == nil {
+    break
+  }
+}
+```
+
+**Good:**
+
+```go
+backoff := time.Second
+for i := 0; i < 3; i++ {
+  if err := connect(); err == nil {
+    break
+  }
+  time.Sleep(backoff + jitter(backoff))
+  backoff *= 2
+}
+```

package/rules/laws/go/GO-00012-rate-limiting.md

@@ -0,0 +1,42 @@
+# Rate Limiting (GO-00012)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/03-resilience.md#2-circuit-breakers--rate-limiting)
+**Tags**: #runtime #go #resilience #reliability
+**Related**: [Safety](../../constitution/CONS-00015-safety.md)
+
+## Definition
+
+Protect internal resources and downstream services from overload.
+
+## Requirements
+
+1.  **Inbound**: Reject requests if the system is overloaded (Load Shedding).
+2.  **Outbound**: Limit the rate of calls to external APIs.
+3.  **Library**: Use `golang.org/x/time/rate`.
+
+## Anti-Patterns
+
+- **Unbounded Work**: Spawning a goroutine for every incoming HTTP request without limit.
+- **Sleep**: Using `time.Sleep` for rate limiting (imprecise).
+
+## Examples
+
+**Bad:**
+
+```go
+for req := range requests {
+  go process(req) // OOM risk
+}
+```
+
+**Good:**
+
+```go
+limiter := rate.NewLimiter(rate.Every(time.Second), 10)
+for req := range requests {
+  if err := limiter.Wait(ctx); err != nil {
+    return
+  }
+  go process(req)
+}
+```

package/rules/laws/go/GO-00013-io-buffering.md

@@ -0,0 +1,43 @@
+# I/O Buffering (GO-00013)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/05-performance.md#3-io-optimization)
+**Tags**: #runtime #go #performance #io
+**Related**: [Efficiency](../../constitution/CONS-00025-efficiency.md)
+
+## Definition
+
+Reduce the number of system calls by buffering Input/Output operations.
+
+## Requirements
+
+1.  **Read**: Wrap `io.Reader` in `bufio.NewReader`.
+2.  **Write**: Wrap `io.Writer` in `bufio.NewWriter` and ensure `Flush()` is called.
+
+## Anti-Patterns
+
+- **Syscall Spam**: Calling `Read()` byte-by-byte on a raw file descriptor.
+- **Unbuffered Network**: Writing small packets to a TCP connection one by one.
+
+## Examples
+
+**Bad:**
+
+```go
+f, _ := os.Open("file.txt")
+b := make([]byte, 1)
+for {
+  n, _ := f.Read(b) // Syscall per byte
+  if n == 0 {
+    break
+  }
+}
+```
+
+**Good:**
+
+```go
+f, _ := os.Open("file.txt")
+r := bufio.NewReader(f)
+b := make([]byte, 1024)
+n, _ := r.Read(b) // Bulk read
+```

package/rules/laws/go/GO-00014-memory-layout.md

@@ -0,0 +1,41 @@
+# Memory Layout (GO-00014)
+
+**Source**: [btcwallet Engineering Guide](../../../docs/meta/languages/go/05-performance.md#2-compiler-optimizations)
+**Tags**: #runtime #go #performance #memory
+**Related**: [Efficiency](../../constitution/CONS-00025-efficiency.md)
+
+## Definition
+
+Minimize memory usage by optimizing struct field order.
+
+## Requirements
+
+1.  **Alignment**: Order struct fields from largest size (int64, pointers) to smallest (bool) to minimize padding bytes.
+2.  **Linter**: Use `fieldalignment` to detect inefficiency.
+
+## Anti-Patterns
+
+- **Padding Waste**: `struct { bool; int64; bool }` wastes 14 bytes (on 64-bit).
+
+## Examples
+
+**Bad:**
+
+```go
+type User struct {
+  isAdmin bool   // 1 byte + 7 padding
+  id      int64  // 8 bytes
+  active  bool   // 1 byte + 7 padding
+} // Total: 24 bytes
+```
+
+**Good:**
+
+```go
+type User struct {
+  id      int64  // 8 bytes
+  isAdmin bool   // 1 byte
+  active  bool   // 1 byte
+  // + 6 padding
+} // Total: 16 bytes
+```

package/rules/laws/go/GO-00015-aaa-pattern.md

@@ -0,0 +1,49 @@
+# AAA Pattern (GO-00015)
+
+**Source**: [Unit Testing Guidelines](../../../docs/meta/languages/go/07-testing.md#1-aaa-arrange-act-assert)
+**Tags**: #operational #go #testing #readability
+**Related**: [Test Isolation](GO-00018-test-isolation.md)
+
+## Definition
+
+Tests must follow the Arrange-Act-Assert structure.
+
+## Requirements
+
+1.  **Structure**: Separate the test body into three distinct sections separated by blank lines.
+2.  **Order**: Always Arrange first, then Act, then Assert.
+3.  **Visuals**: Use blank lines to make the phases obvious.
+
+## Anti-Patterns
+
+- **Mixed Logic**: Interleaving setup and assertions.
+- **Wall of Code**: No visual separation.
+
+## Examples
+
+**Bad:**
+
+```go
+func TestLogic(t *testing.T) {
+  x := setup()
+  if !x.Run() {
+    t.Fail()
+  }
+  x.cleanup()
+}
+```
+
+**Good:**
+
+```go
+func TestLogic_Success(t *testing.T) {
+  // Arrange
+  s := NewService()
+
+  // Act
+  err := s.Run()
+
+  // Assert
+  require.NoError(t, err)
+}
+```