add spec system: sdd/bdd/tdd loops, trace enforcement, envelope+config specs

2026-07-13 12:53:38 +02:00
parent 1879992b22
commit f1578cbd99
11 changed files with 682 additions and 0 deletions
@@ -0,0 +1,69 @@
+# SPEC-000 — Development process (binding)
+
+This repo is developed spec-driven + behaviour-driven + test-driven.
+
+## The three loops
+
+1. **Spec-driven**: every behavior exists first as a numbered
+   requirement (`<AREA>-NN`) in `specs/SPEC-NNN-*.md`. No code without
+   a requirement. Requirements are never deleted — a dead requirement
+   is marked `(withdrawn: <successor or reason>)` in its title line
+   and keeps its ID forever.
+2. **Behaviour-driven**: every *user-visible* requirement gets at
+   least one Gherkin scenario tagged `@<ID>` in `features/*.feature`,
+   executed by pytest-bdd.
+3. **Test-driven**: implementation starts at a red test. Unit tests
+   cover the non-visible requirements (arithmetic, invariants,
+   parsing).
+
+Change flow: spec change → feature/test red → implementation green →
+refactor.
+
+## Requirement format
+
+```
+### ENV-01 — Model answer reaches the user (coverage: feature)
+
+Normative statement first. Rationale after.
+```
+
+Coverage classes:
+
+- `feature` — needs an `@<ID>` tag in some `.feature` file.
+- `test` — the ID must appear in a test file (docstring or comment
+  of the covering test).
+- `manual` — needs a row in `manual-verification.md` with date and
+  result before the increment demo.
+
+## Enforcement
+
+`tools/trace.py` (stdlib-only) runs in `make check` (and `make
+trace`). It fails the build when a declared requirement lacks its
+coverage class artifact, when a feature tag references an undeclared
+ID, or when an ID is declared twice. Code fences in spec files are
+ignored by trace (the example above does not declare ENV-01).
+
+## Test substrate
+
+BDD scenarios run against the **responder seam**: a
+`FakeModelResponder` subclass with scripted model output — no live
+Discord, no live OpenAI (see DECISIONS.md D-002). Discord-event
+behavior is covered by unit tests with mocked discord.py objects.
+
+## ADRs
+
+Decisions inside the set architecture go to `DECISIONS.md` as
+`D-NNN — title — one-paragraph rationale`. The stack itself is not
+re-litigated there.
+
+## Spec map
+
+- SPEC-000 process (this file, no IDs)
+- SPEC-001 responder + envelope — ENV-NN
+- SPEC-002 memory — MEM-NN (lands with FDB-007)
+- SPEC-003 safety/privacy/abuse — SAF-NN (lands with FDB-014)
+- SPEC-004 images — IMG-NN (lands with FDB-009/010)
+- SPEC-005 self-tasking — TSK-NN (lands with FDB-011)
+- SPEC-006 staff/operator controls — OPS-NN (lands with FDB-005)
+- SPEC-007 deploy/hosts — DEP-NN (lands with FDB-017, mostly manual)
+- SPEC-008 config — CFG-NN