VacatureRadar/docs/ai/AUTONOMOUS_EXECUTION_PROTOCOL.md

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

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:

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

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

./scripts/codex_verify.sh

Pas na een geslaagde gate:

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.