156 lines
4.6 KiB
Markdown
156 lines
4.6 KiB
Markdown
# Autonoom uitvoeringsprotocol
|
|
|
|
Dit protocol is ontworpen voor Codex of een vergelijkbare code-agent die de uitgepakte repository als workspace heeft. Het doel is langdurig voortwerken zonder productvragen, terwijl security- en kwaliteitsgrenzen behouden blijven.
|
|
|
|
## Hoofdlus
|
|
|
|
```text
|
|
bootstrap/verify
|
|
→ selecteer eerste uitvoerbare ready taak
|
|
→ lees alleen gekoppelde specs/code/tests
|
|
→ schrijf of verfijn falende tests
|
|
→ implementeer kleinste complete oplossing
|
|
→ relevante tests + lint
|
|
→ docs/traceability/backlog/project state
|
|
→ volledige gate
|
|
→ markeer done
|
|
→ herhaal
|
|
```
|
|
|
|
Commando om de volgende taak te kiezen:
|
|
|
|
```bash
|
|
python scripts/backlog.py next
|
|
```
|
|
|
|
De selectie is deterministisch: bestandsvolgorde in `BACKLOG.yaml`, alleen `status: ready`, alle dependencies `done`.
|
|
|
|
## Geen productonderbrekingen
|
|
|
|
Vraag niet om bevestiging voor keuzes die in ADRs, productdefaults of backlogacceptatie staan. Bij een echt ontbrekend detail:
|
|
|
|
1. kies de veiligste;
|
|
2. kies de eenvoudigste;
|
|
3. kies een omkeerbare implementatie;
|
|
4. behoud bestaande contracts;
|
|
5. documenteer de aanname in taakresultaat of nieuwe ADR.
|
|
|
|
Voorbeelden:
|
|
|
|
- onbekende bron → `review`, niet fetch;
|
|
- ontbrekende locatie → `unknown`, niet gokken;
|
|
- AI niet beschikbaar → deterministische fallback;
|
|
- provider niet gekozen → interface + fixture + lokale importer, providerstap extern blokkeren;
|
|
- rijke frontend niet noodzakelijk → Django template/progressive enhancement.
|
|
|
|
## Externe blokkadeprocedure
|
|
|
|
Een credential, domein, live bronvoorwaardenreview, registry of gelicenseerde bulkdataset mag codewerk niet stoppen. Voor het taakdeel dat extern geblokkeerd is:
|
|
|
|
- implementeer configuratieschema en validatie;
|
|
- maak providerinterface;
|
|
- voeg fictieve fixtures/mocks toe;
|
|
- test succes, fout en disabled state;
|
|
- schrijf exact productiechecklistje;
|
|
- maak/gebruik een aparte `blocked-external` taak;
|
|
- ga onmiddellijk door met de volgende uitvoerbare taak.
|
|
|
|
Markeer nooit een volledige feature als geblokkeerd wanneer alleen de live configuratie ontbreekt.
|
|
|
|
## Werk per taak
|
|
|
|
### 1. Reconnaissance
|
|
|
|
- `python scripts/backlog.py show <ID>`
|
|
- lees requirement- en traceabilityregels;
|
|
- zoek bestaande services, modellen en tests;
|
|
- bevestig architectuurgrenzen;
|
|
- noteer regressierisico's.
|
|
|
|
Geen brede herschrijving zonder aantoonbare noodzaak.
|
|
|
|
### 2. Test-first waar zinvol
|
|
|
|
Voor bugs/securitygrenzen eerst een falende regressietest. Voor nieuwe functionaliteit minstens tests voor:
|
|
|
|
- normale input;
|
|
- lege/ontbrekende input;
|
|
- malformed/aanvallende input;
|
|
- replay/idempotentie;
|
|
- autorisatie/user-scoping;
|
|
- disabled/external dependency unavailable.
|
|
|
|
### 3. Implementatie
|
|
|
|
- pure logica in services;
|
|
- tasks alleen orchestration;
|
|
- adapters zonder writes;
|
|
- transacties rond meerdere afhankelijke writes;
|
|
- machineleesbare foutcategorieën;
|
|
- geen live internet in tests;
|
|
- geen secrets of persoonlijke voorbeelden.
|
|
|
|
### 4. Relevante verificatie
|
|
|
|
```bash
|
|
uv run ruff format .
|
|
uv run ruff check .
|
|
uv run pytest <relevante tests>
|
|
```
|
|
|
|
Herstel oorzaak, niet gate/drempel.
|
|
|
|
### 5. Overdracht in dezelfde wijziging
|
|
|
|
Werk bij:
|
|
|
|
- code en migraties;
|
|
- tests/fixtures;
|
|
- relevante product/architectuur/operationele docs;
|
|
- `TRACEABILITY_MATRIX.md`;
|
|
- `BACKLOG.yaml` resultaatstatus;
|
|
- `PROJECT_STATE.md`.
|
|
|
|
### 6. Volledige gate
|
|
|
|
```bash
|
|
./scripts/codex_verify.sh
|
|
```
|
|
|
|
Pas na een geslaagde gate:
|
|
|
|
```bash
|
|
python scripts/backlog.py set <ID> done --note "<concreet resultaat + tests>"
|
|
./scripts/codex_verify.sh
|
|
```
|
|
|
|
De tweede gate bewijst dat de ledgerwijziging zelf geldig is.
|
|
|
|
## Omgaan met onverwachte defecten
|
|
|
|
Een blocker in bestaande code die de geselecteerde taak verhindert, mag direct worden hersteld. Voeg een regressietest toe en vermeld het in het taakresultaat. Een los, niet-blokkerend defect krijgt een nieuwe taak met uniek ID alleen wanneer het niet veilig binnen de huidige scope past; wijzig de kernprioriteiten niet stilzwijgend.
|
|
|
|
## Stopcriteria
|
|
|
|
Stop de autonome lus alleen wanneer:
|
|
|
|
- geen uitvoerbare `ready` taak meer bestaat;
|
|
- alle resterende taken `blocked-external` of `deferred` zijn;
|
|
- de volledige kwaliteitsgate slaagt;
|
|
- `PROJECT_STATE.md` exact de resterende blokkades en productiechecklist noemt.
|
|
|
|
Stop niet alleen omdat één provider, secret of live bron ontbreekt.
|
|
|
|
## Eindrapport
|
|
|
|
Rapporteer:
|
|
|
|
- afgeronde taak-ID's;
|
|
- belangrijkste gedrag- en datamodelwijzigingen;
|
|
- migraties/configuratieimpact;
|
|
- tests en coverage;
|
|
- externe blokkades met exacte invulstap;
|
|
- eerste resterende taak of “geen uitvoerbare ready taak”.
|
|
|
|
Claim geen productieacceptatie zonder Docker/release-/restore-smoke wanneer die in de taakcriteria staat.
|