SPEC-000 — Development process (binding)

This repo is developed spec-driven + behaviour-driven + test-driven.

The three loops

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.
Behaviour-driven: every user-visible requirement gets at least one Gherkin scenario tagged @<ID> in features/*.feature, executed by pytest-bdd.
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

2.5 KiB Raw Blame History