# SPEC.md Canonical Format Specification

`SPEC.md` is the single source of truth for Spec-Driven Development (SDD). All sections are written in Caveman encoding.

---

## 1. Document Sections

### §G — Goal
One single line in Caveman dialect stating the product intent.
```markdown
# §G
build distributed rate limiter with sliding-window Redis Lua script.
```

### §C — Constraints
Hard constraints, technology stack limits, and explicit out-of-scope declarations.
```markdown
# §C
- Go 1.22+ stdlib + go-redis/v9.
- ⊥ external dependencies outside Redis.
- memory overhead ≤ 50MB @ 100k keys.
- out of scope: clustering, dynamic cluster topology changes.
```

### §I — Interfaces
Public membranes: CLI commands, API endpoints, environment variables, or exported signatures.
```markdown
# §I
api: POST /v1/limiter/check → 200 {allowed:bool, remaining:int, reset_ms:int}
cmd: `limiter-cli bench --rate=<n>` → stdout benchmark summary
env: REDIS_URL ! set
```

### §R — Research Log (Optional)
Distilled external facts, primary documentation links, or RFC references.
```markdown
# §R
id|domain|finding|source
R1|redis lua|reclaim memory via `redis.replicate_commands()`|redis.io/docs/manual/programmability/lua-api
R2|token bucket|GCRA algorithm reduces atomic roundtrips to 1|en.wikipedia.org/wiki/Generic_cell_rate_algorithm
```

### §V — Invariants
Non-negotiable behavioral invariants. Numbered monotonically `V1`, `V2`, ...
```markdown
# §V
V1: ∀ check req → atomic sliding window evaluate in Redis Lua
V2: Redis down → fail open (return allowed:true with header warning)
V3: latency p99 ≤ 2ms @ 10k rps
```

### §T — Tasks
Ordered pipe table of implementation tasks. Numbered `T1`, `T2`, ...
- Status: `.` todo, `~` wip, `x` done.
- `cites`: Invariants (`V<n>`) or Interfaces (`I.<name>`) that the task must satisfy.
```markdown
# §T
id|status|task|cites
T1|x|scaffold Redis client with fallback|V2,I.api
T2|~|implement sliding window Lua script|V1
T3|.|expose HTTP endpoint & healthcheck|I.api
```

### §B — Bug Log
Feedback memory capturing bugs and regressions found during build/check/production.
```markdown
# §B
id|date|cause|fix
B1|2026-04-20|lua script script error on empty redis key|V1
```

---

## 2. Sectioned Ownership
- `spec` is the sole mutator of `SPEC.md`.
- `build` flips only task status (`.` → `~` → `x`).
- `check` is strictly read-only.
- `backprop` appends `§B` rows and drafts `§V` lines.