Oleksandr Kozachuk
70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
# 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
|