DESIGN.md.template

# {{PROJECT_NAME}} — Design & Decision Record

> Status: working document. When ratified, the loop treats this as **frozen ground truth**.
> Pairs with [`MANIFESTO.md`](../MANIFESTO.md): manifesto = public intent; this = engineering record.

## 1. What this project is

{{2–3 paragraphs: problem, audience, success shape}}

## 2. The wedge

> **We compete with {{X}}, not with {{Y}}.**

{{Why this framing — competitive landscape in one paragraph}}

## 3. Locked decisions

| Decision | Lock |
|----------|------|
| Product scope | {{e.g. library / service / CLI}} |
| Primary language | {{e.g. TypeScript}} |
| Distribution | {{e.g. npm, binary, Docker}} |
| Architecture | {{e.g. single core + adapters}} |
| API style | {{e.g. sync, REST, embedded}} |
| Reliability bar | {{e.g. every line tested; property tests; DST}} |
| Test runner | {{e.g. bun test, pytest, go test}} |
| Beachhead | {{e.g. dev/test first; production earned later}} |

Do not re-litigate locked rows without explicit human amendment to this file.

## 4. Principles

1. **{{Principle}}** — {{explanation}}
2. **{{Principle}}** — {{explanation}}
3. **{{Principle}}** — {{explanation}}

## 5. Architecture

```
{{ASCII or tree diagram — modules, trust boundaries}}
```

### Trust boundaries

| Boundary | Modules | Gate |
|----------|---------|------|
| Guarded core | {{paths}} | {{heavy tests, CODEOWNERS, coverage threshold}} |
| Open edges | {{paths}} | {{standard gate}} |

**Honesty discipline:** guarded modules stay small because they are genuinely minimal — not because complexity was swept elsewhere.

## 6. Feature roadmap (ordered)

### Phase / milestone 1 — {{name}}

- {{deliverable}}
- Acceptance: see `loop/ACCEPTANCE.md`

### Phase / milestone 2 — {{name}}

- {{deliverable}}

### Later (explicit deferrals)

- {{item}} — reason deferred

## 7. Open questions

- [ ] {{question}} — owner: human; do not silently decide in loop

## 8. Deliberately rejected

Record alternatives the brainstorm considered so the loop does not reopen them:

- **{{Alternative}}** — rejected because {{reason}}

## 9. References

- {{Prior art, papers, repos to study}}