geointel/docs/accuracy-program/06-implementation-roadmap.md

# GeoIntel Accuracy Improvement Program — uitvoerbare roadmap

- Status: **Phase 2 mag starten; release en nationale modelclaim blijven geblokkeerd**
- Bronnen: Phase-1 inventory, lineage, baseline/gaps, risicoregister en metric framework
- Runtime voor training: Tower NVIDIA GeForce RTX 4080 SUPER op `cuda:0`

## Doel en definitie van gereed

Deze roadmap herstelt eerst de bewijs- en vertrouwensketen en bouwt daarna pas een nieuw Belgisch building-corpus en model. “100% getraind” betekent hier: alle vooraf bevroren corpus-, split-, runtime-, metric-, review-, test-, promotion- en deploymentgates zijn aantoonbaar geslaagd voor één expliciete modelscope. Het betekent niet 100% precision/recall en geeft geen claim buiten de geëvalueerde regio's, contexts, imagery editions en objectgroottes.

De volgorde is verplicht. Een work package start pas wanneer zijn dependency-gate groen is. Bij een gefaalde gate blijft productie op de huidige beperkte, expliciet gecommuniceerde Mol/Kempen-scope of schakelt de betrokken capability fail-closed naar `not_configured`. Checkpoints, datasets en bewijs worden nooit overschreven.

## Niet-onderhandelbare regels

1. **Test-first:** ieder bewezen defect uit `04-risk-register.md` krijgt eerst een regressietest die op de huidige foutieve implementatie faalt.
2. **Protected-test isolation:** train, val en calibration mogen tijdens iteraties worden gelezen; test en background-test blijven verzegeld tot één kandidaat-SHA, preprocessingconfig, threshold en gates bevroren zijn.
3. **Geen testgestuurde retraining:** na openen van protected test volgt voor die candidate family geen training, thresholdwijziging, sampleweging of configuratiekeuze meer.
4. **Evidence of fail:** ontbrekend, null of niet-reproduceerbaar bewijs is een gefaalde gate.
5. **Immutable lineage:** iedere dataset-, run-, model- en releaseversie heeft een checksum-bound manifest; legacy gaps blijven zichtbaar als `lineage_incomplete`.
6. **GPU verplicht:** training gebruikt `cuda:0` op de Tower RTX 4080 SUPER met `TRAIN_REQUIRE_CUDA=true`; CPU-fallback is een failure.
7. **Geen claim op file presence:** een `.pt`-bestand of succesvolle smoke maakt een model niet gevalideerd.
8. **Menselijke review is echt menselijk:** automatische QA mag een ontbrekende review nooit als akkoord invullen. De finale productreview door de gebruiker volgt pas nadat alle objectieve gates groen zijn.

## Dependency-overzicht

| Volgorde | Work package | Depends on | Primaire output | Risico's gesloten |
| --- | --- | --- | --- | --- |
| P2-00 | Promotion lock en evidence freeze | Phase 1 | immutable baseline + release lock | claimgrens voor alle risico's |
| P2-01 | Canonical test harness | P2-00 | rode regressietests en uitvoerbare CI-matrix | ACC-R21, R22, basis voor alle fixes |
| P2-02 | CRS, units en geometry integrity | P2-01 | veilig ingest/transform/buffer + data repair | ACC-R01, R02, R07 |
| P2-03 | Coverage, authority en wettelijke scope | P2-02 | trusted source registry en geometry-backed scope | ACC-R03–R06 |
| P2-04 | Transactionele lineage en foutzichtbaarheid | P2-02, P2-03 | complete Run/Dataset lineage en fail-closed persistence | ACC-R08, R15, R17, R23 |
| P2-05 | Protected-split redesign | P2-01, P2-04 | test vault, manifest schema en sampler firewall | ACC-R09, R10, R14, R24 |
| P2-06 | Menselijke labelreview en corpusrebuild | P2-02, P2-03, P2-05 | immutable reviewed `building-be-*` corpus | ACC-R10–R15 |
| P2-07 | Metric framework en reproducible incumbent baseline | P2-04, P2-06 | frozen metrics/gates + paired baseline | ACC-R16, R18, R19 |
| P2-08 | Reproducible CUDA candidate training | P2-05, P2-06, P2-07 | immutable RTX 4080 candidate portfolio | ACC-R14, R16, R17, R24, R25 |
| P2-09 | Calibration-only improvement loop | P2-08 | fixed candidate that passes all pre-test gates | ACC-R12, R13, R16 |
| P2-10 | Eenmalige protected test | P2-09 | signed pass/fail promotion evidence | ACC-R09, R16, R18 |
| P2-11 | Guarded promotion, shadow en redeploy | P2-10 pass | model card, immutable image, rollback | ACC-R17, R19, R25, R27, R29 |
| P2-12 | Monitoring en controlled next cycle | P2-11 | reviewed drift queue zonder self-training | blijvende beheersing |

## P2-00 — Promotion lock en evidence freeze

### Uitvoering

- Leg current commit, server commit, container digest, DB migration head, active model path/SHA, modelscope en alle P1-evidencehashes vast.
- Zet `nationally_validated=false` en de actuele Mol/Kempen-scope expliciet in de capability/model-card response; voorkom scopeverruiming zonder promotion report.
- Markeer v56/v58/v62/v66 en andere checkpoints als `candidate/unpromoted`; verander of verwijder geen files.
- Maak een restorebare databaseback-up en inventory van storage references vóór migraties.
- Bewaar de succesvolle GPU-smoke als runtimebewijs met de expliciete claimgrens “geen accuracy-evidence”.

### Exit gate

- Evidence manifest is hash-compleet en read-only gekopieerd naar de release-auditlocatie.
- Production promotion endpoint/config weigert een kandidaat zonder signed promotion report.
- Rollbackdoel (huidige image digest + model SHA + config) is reproduceerbaar vastgelegd.

## P2-01 — Canonical test harness en rode regressies

### Uitvoering

- Maak één repo-root testentrypoint voor Python; verwijder de `backend/scripts` versus root `scripts` shadowing.
- Voeg vóór productcodewijzigingen regressies toe voor:
  - EPSG:31370/3812 als 4326 gelabeld;
  - 100 m buffer als graden;
  - cross-theme coverage union;
  - forged authoritative upload;
  - area-name/YOLO-scope bypass;
  - Area PATCH geometry/CRS;
  - ready-derived dataset zonder PostGIS-features;
  - protected test als samplerinput;
  - metric null/empty truth table;
  - persistence- en frontendfallbacks.
- Vervang stale broncode-stringasserties door behavior/contracttests; wijzig expected output alleen met een gedocumenteerde contractbeslissing.
- Voeg Ruff en een echte frontend `npm run lint` gate toe; behoud typecheck, Vitest en build.
- Laat CI dezelfde Python/Node-versies en commands gebruiken als de pinned build; maak een aparte AI-enabled image gate.

### Verificatiecontract

De CI-matrix bevat minimaal: volledige backend-Pytest, Alembic offline+live PostGIS, Ruff, frontend lint/typecheck/Vitest/build, OpenAPI-contractaudit en de gerichte GIS/AI regressies. De oude implementatie moet de nieuwe regressies aantoonbaar laten falen; pas daarna worden fixes geaccepteerd.

### Exit gate

- Eén canonical commandmatrix is volledig groen in een schone checkout.
- De 17 bestaande failures zijn per contract geclassificeerd en opgelost.
- Geen test wordt geskipt op basis van ontbrekende lokale AI/GIS-dependency zonder expliciete, afzonderlijk rode environment gate.

## P2-02 — CRS-, eenheden- en geometry-integriteit

### Uitvoering

1. Definieer per API/file-ingest het bron-CRS, canonical storage-CRS en output-CRS. Ontbrekende of ambigue CRS faalt met een typed fout.
2. Transformeer EPSG:31370 en EPSG:3812 met `pyproj`/GeoPandas/PostGIS naar EPSG:4326 vóór `from_shape(..., srid=4326)`.
3. Implementeer buffer via een geldige metrische projectie of PostGIS geography; log units en transform.
4. Maak Area PATCH exact conform contract: geometry wordt valide getransformeerd of extra input wordt geweigerd; CRS relabeling zonder transform is onmogelijk.
5. Herleid de vier buiten-domein detections uit originele tile, manifest, EPSG:31370-transform en modeloutput. Bewaar oude rijen/evidence; corrigeer via een auditabele migratie of markeer ze `invalid_legacy_geometry`.
6. Voeg DB constraints/checks toe waar die legitieme EPSG:4326-extents kunnen afdwingen zonder de Noordzee of grensgebieden fout af te wijzen.

### Exit gate

- CRS/units regressies en live PostGIS-tests slagen.
- Runtime-audit meldt zero ongeclassificeerde invalid/empty/wrong-SRID/out-of-domain geometry.
- De vier legacy detection-ID's zijn traceerbaar vóór en na migratie; geen stille overschrijving.

## P2-03 — Coverage-, authority- en scopevertrouwen

### Uitvoering

- Herstructureer coverage zodat alleen datasets die source, theme, layer én zone matchen aan de coverage union deelnemen.
- Introduceer immutable `source_registry_id`, trust class, provider adapter en bronversie. Caller metadata blijft descriptief en kan nooit official authority verlenen.
- Migreer user uploads naar `manual/untrusted` tenzij hun acquisition/job lineage een governed adapter bewijst.
- Vervang displaynaam-gebaseerde legal zones door stable codes en geometry-backed predicates.
- Vervang YOLO-name-substringcontrole door model-card scope geometry/zone IDs met expliciete containment-policy.
- Maak API/UI onderscheid tussen `available`, `covered`, `authoritative`, `runtime_ready` en `model_validated_for_scope`.

### Exit gate

- Forged-source-, mixed-theme-, rename- en scope-bypasstests slagen.
- Bestaande source records hebben een auditbare trust classification.
- Een AOI buiten Mol/Kempen kan het actieve model niet uitvoeren door naam of metadata te manipuleren.

## P2-04 — Transactionele lineage en zichtbare failures

### Uitvoering

- Maak een verplicht `RunManifest` met model-ID/version/SHA, dataset/version/SHA, tile-manifest/SHA, source imagery/reference versions, CRS/transform, preprocessing, threshold, NMS/max-det, seed, runtime/container/GPU en code commit.
- Maak derived vector persistence atomair: AnalysisRun, Dataset, DatasetVersion, artifact en vector_features gaan samen van `processing` naar `ready`; elke verplichte write failure maakt de run failed.
- Classificeer `observed_at` en `source_version` per bronfamilie als required/not-applicable/unknown-with-reason en voer een provenance-safe backfill uit.
- Markeer historische detection runs zonder volledige lineage als `lineage_incomplete`; vul modelversies niet afgeleid of op basis van huidige config in.
- Verwijder silent catches: UI krijgt een typed error/stale state met run ID; services mogen geen success/ready rapporteren na persistence failure.

### Exit gate

- Nieuwe analyses zijn van UI-resultaat tot tile, bron, model en container volledig traceerbaar.
- Fault-injection geeft failed/incomplete, nooit ready/success.
- Lineage-audit heeft zero ongeclassificeerde verplichte gaps voor nieuwe records en een expliciete legacybucket.

## P2-05 — Protected-split redesign en manifest firewall

### Uitvoering

1. Definieer één versioned corpusmanifest met immutable sample-ID, image/label SHA, bronfeature-ID, region/context, provider/edition, imagery/reference time, CRS/resolution, tile/stride/overlap, split en reviewstatus.
2. Bereken splits op buffered AOI's vóór tiles worden geëxporteerd. Controleer geometry overlap, contextbuffer, feature-ID's, image/label hashes en perceptuele near-dupes.
3. Verplaats protected test en background-test naar een afzonderlijke read-only locatie/credential die de training- en samplerprocessen niet kunnen lezen.
4. Splits de huidige orchestrator:
   - `train/val/calibration loop`: fit, early stopping, threshold en error taxonomy;
   - `release evaluation`: alleen frozen kandidaat/config en protected credentials.
5. Laat de failure-driven sampler uitsluitend calibration-aggregaten en train-only contextcatalogi lezen. Hij moet hard falen zodra een assessment testdata, test-ID's of een protected pad bevat.
6. Log iedere protected access met candidate SHA, config SHA, operator/runner, timestamp en output SHA.

### Exit gate

- Canary protected sample verschijnt in geen enkel train/val/calibration manifest, log, cache of sampleroutput.
- Minimum cross-splitafstand voldoet aan de vooraf vastgelegde contextbuffer; 24 huidige near-pairs zijn opgelost of met objectief geometrisch bewijs als onafhankelijk geclassificeerd.
- Testcredentials zijn tijdens training technisch niet beschikbaar.

## P2-06 — Menselijke review en immutable corpusrebuild

### 1. Review de bestaande kandidaatdata

- Genereer contact sheets/kaartoverlays voor een vooraf geregistreerde, gestratificeerde reviewqueue: regio, provider, dense urban, suburban, rural, industrial, coast, forest/heath, rail/port/quarry, pure-empty, hard negative, kleine objecten, extreme aspectratio en providerseams.
- Beoordeel expliciet de 521 kleine labels, extreme aspectgroepen, sub-resolution/post-imagery exclusions en zeer dichte PICC/UrbIS-labelgebieden.
- Sla accept/reject/repair/uncertain op met reviewer, reason code, native feature-ID, image/label version en checksum. `uncertain` blijft uitgesloten of in een afzonderlijke non-training queue.

### 2. Provision onafhankelijke AOI's

- Vul iedere vereiste region/context-cel uit het bevroren corpuscontract; voeg Brussels pure-background toe en breid moeilijke negatives uit zonder protected voorbeelden te kopiëren.
- Gebruik officiële imagery/reference adapters en leg acquisition edition/periode vast.
- Houd train-only uitbreidingen ruimtelijk onafhankelijk van val/calibration/test/background-test en van elkaar waar het contract dat vereist.

### 3. Herbouw en freeze

- Pas temporal/resolution/providersemantics toe op GRB, PICC en UrbIS; post-imagery en niet-resolveerbare features krijgen een expliciete rejection reason.
- Exporteer deterministisch met ingevulde dataset-YAML/class/tile/stride/overlap-velden.
- Run geometry, label, density, class, blank/variance, duplicate/near-duplicate, split-distance, temporal en provenance audits.
- Freeze een nieuwe corpusversie; verander v56/v66 niet.

### Exit gate

- Representatieve menselijke review is volledig; zero unresolved Critical/High findings.
- Elke verplichte region/context/background-cel voldoet aan het vooraf bevroren contract.
- Zero cross-split leakage/near-duplicate violations; timestamps en unknowns zijn expliciet.
- Corpus, reviewrecords, manifests, YAML en auditrapporten zijn SHA-bound en immutable.

## P2-07 — Metric framework en reproduceerbare incumbent baseline

### Uitvoering

- Implementeer de truth table uit `05-metric-framework.md` voor empty/no-match/undefined cases; null kan een gate nooit stil passeren.
- Meet detection precision, recall, F1 en AP op bevroren IoU-contracten; voeg objectgrootte, dichtheid, region, provider, context en pure-background strata toe.
- Behandel calibration en test afzonderlijk. Selecteer threshold/NMS/tile-overlap op calibration met worst-region/worst-context vóór aggregate.
- Evalueer het actieve model als incumbent op exact dezelfde niet-protected calibrationportfolio en bewaar paired AOI-resultaten.
- Maak FP/FN contact sheets en error taxonomy: label/temporal mismatch, tile-edge, small object, dense cluster, roof displacement, source seam, context confusion en model miss.
- Freeze alle numeric gates vóór protected test. Bestaande minimale gates mogen alleen vóór test en op basis van reviewed baseline distributions worden aangescherpt; nooit versoepeld na testinzage.

### Exit gate

- Twee baseline-runs met dezelfde inputs leveren dezelfde sample/split hashes en metrics binnen vooraf vastgelegde tolerantie.
- Alle strata hebben een waarde of expliciete failstatus; zero silently ignored nulls.
- Gateconfig, evaluator, incumbent SHA en calibrationresultaat zijn immutable.

## P2-08 — Reproduceerbare CUDA-training op RTX 4080 SUPER

### Uitvoering

- Bouw één pinned AI image voor PyTorch/CUDA/Ultralytics; leg image digest, SBOM, driver/runtime, GPU, peak VRAM en code commit vast.
- Voer VRAM-preflight uit voor iedere kandidaatconfig; OOM/failure blijft als artifact en mag niet stil naar CPU vallen.
- Train een vooraf begrensde matrix zoals vastgelegd in `PYTORCH_TRAINING_ROADMAP_BELGIUM.md`; wijzig matrix noch primary metric na resultaten te zien.
- Seed Python/NumPy/PyTorch/Ultralytics; gebruik deterministic algorithms waar ondersteund en registreer afwijkingen.
- Training leest uitsluitend train; val kiest epochs/checkpoint; calibration kiest threshold/NMS/tile policy. Protected testmount/credential ontbreekt.
- Sla per run config, stdout/stderr, curves, checkpoints, optimizer state, dataset/corpus SHA, seed, runtime en peak VRAM op. Kopieer checkpoints immutably; overschrijf active model nooit.
- Herhaal de winnende configuratie clean-room vanaf dezelfde base weights en corpus om reproduceerbaarheid te toetsen.

### Exit gate

- Alle geplande kandidaten hebben complete run manifests of expliciete failure artifacts.
- Minstens één kandidaat en zijn clean-room rerun voldoen aan vooraf bevroren reproducibilitytoleranties.
- GPU-evidence toont RTX 4080 SUPER/`cuda:0`; zero CPU fallback; protected-accesslog blijft leeg.

## P2-09 — Calibration-only verbeterloop

De loop mag worden herhaald, maar alleen binnen de volgende state machine:

```text
reviewed immutable corpus
  -> CUDA train
  -> validation checkpoint selection
  -> calibration + error taxonomy
  -> all pre-test gates pass?
       no  -> provision independent train-only AOIs / reviewed labels
              -> freeze new corpus version -> CUDA train
       yes -> freeze candidate SHA + preprocessing + threshold + gates
              -> P2-10 protected test
```

### Regels

- Calibrationresultaten mogen aangeven welke regio/context faalt, maar nooit protected sample-ID's of testresultaten.
- Nieuwe voorbeelden komen uit onafhankelijk geprovisioneerde train-only AOI's en doorlopen dezelfde provenance, temporal en human-reviewgates.
- Een corpuswijziging maakt een nieuwe immutable corpusversie en een nieuwe run family; bestaande evidence blijft behouden.
- De loop stopt niet op aggregate F1 alleen. Iedere regionale/context-, background-, lineage-, runtime- en reviewgate moet groen zijn.
- Indien geen betrouwbare labels of onafhankelijke AOI's beschikbaar zijn, is de correcte status `blocked/not_validated`, niet een afgezwakte gate.

### Exit gate

- Eén candidate SHA passeert alle vooraf bevroren validation/calibration-, regional/context-, pure-background-calibration-, runtime-, lineage- en reviewgates.
- Candidate, threshold, NMS, tileconfig, corpus en evaluator zijn daarna read-only bevroren.

## P2-10 — Eenmalige protected-testbeslissing

### Voorwaarden vóór openen

- P2-00 tot P2-09 zijn groen.
- Candidate/model SHA, container digest, corpus SHA, preprocessing, threshold, evaluator en numeric gates zijn gesigneerd/bevroren.
- Test/background-test manifesthashes bestaan, maar hun inhoud was niet toegankelijk voor train/calibration runners.
- Promotion policy specificeert vooraf wat pass, fail en infrastructure-invalid betekent.

### Uitvoering

- Start één isolated release-evaluation job met read-only protected credentials op `cuda:0`.
- Bereken alle bevroren regionale/context/object-size en background-test metrics; produceer contact sheets en machine-readable gate decision.
- Een infrastructure-invalid run mag uitsluitend opnieuw worden uitgevoerd wanneer bewijs aantoont dat geen bruikbaar modelresultaat is vrijgegeven; de incidentbeslissing wordt gelogd.

### Beslissing

- **Pass:** ga naar P2-11; resultaten mogen niet worden gebruikt om alsnog threshold/config te wijzigen.
- **Fail:** release blijft blocked. Train deze candidate family niet verder op basis van het testresultaat. Archiveer de beslissing; een volgende poging vereist een nieuw vooraf geregistreerd ontwikkelprogramma en een nieuwe onaangeroerde protected portfolio.

### Exit gate

- Exact één geldig access event en één immutable report voor candidate SHA.
- Geen write naar corpus/training config na testopening.
- Alle gates zijn groen; anders is P2-11 niet bereikbaar.

## P2-11 — Guarded promotion, shadow en redeploy

### Uitvoering

1. Genereer model card en promotion report met task, class, scope, imagery/reference versions, known limitations, metrics per stratum, calibration, test, runtime, lineage en rollbackmodel.
2. Kopieer de kandidaat naar een immutable model-ID/version/SHA-pad; overschrijf het actieve `.pt`-bestand niet.
3. Bouw/push één immutable GPU image vanaf een gepushte commit/tag; leg image digest en SBOM vast.
4. Migreer DB/schema via backup, dry-run en restoretest; voer PostGIS extension-upgrade alleen volgens P2-evidence uit.
5. Draai production preflight: exact modelhash, CUDA required, bounded tile inference, CRS/georeferencing, persistence en restart.
6. Start shadowvergelijking binnen exact de gevalideerde scope; shadowoutput is niet publiek en kan de protected-testbeslissing niet aanpassen.
7. Laat UI/API alleen de bewezen scope/classes/status zien; segmentatie en solar blijven `not_configured`.
8. Activeer pas na shadow- en rollbackgate; monitor en behoud één-command rollback naar vorige image/model/config.

### Exit gate

- Commit/tag, image digest, model SHA, config SHA, migration head en promotion report verwijzen wederzijds naar elkaar.
- End-to-end selectie → inference → persisted result → uitschuifbare inzichten → export is getest met correcte lineage en zichtbare error states.
- Restart en rollback slagen zonder data- of evidenceverlies.
- De gedeclareerde scope is exact de geslaagde testscope, nooit “heel België” door implicatie.

## P2-12 — Monitoring en gecontroleerde volgende cyclus

### Uitvoering

- Monitor per region/context/provider/imagery edition/object size: input drift, confidence, density, QA mismatches, latency/VRAM en persistence failures.
- Maak een menselijke reviewqueue met FP/FN/uncertain voorbeelden; production outputs worden nooit automatisch training labels.
- Een volgende training gebruikt alleen een reviewed, opnieuw gefreezede labelrelease en herstart bij P2-05/P2-06.
- Bewaar oude datasets, modellen, run manifests, promotion reports en rollbackimages volgens retentiebeleid.
- Widening van scope of class is een nieuwe releaseclaim en doorloopt opnieuw P2-06 tot P2-11 met een onaangeroerde testportfolio.

### Exit gate

- Alerts, reviewqueue, ownership en rollbackrunbook zijn operationeel getest.
- Er bestaat geen automatische self-training of silent promotion path.
- Periodieke audits kunnen ieder publiek resultaat terugvoeren naar bron, tile, model, config en releasebeslissing.

## Verplichte release-evidence

P2-11 blijft geblokkeerd zolang één van deze artifacts ontbreekt:

- canonical CI commandmatrix en logs;
- CRS/coverage/authority/scope regressierapport;
- DB migration, backup/restore en legacy-quarantainerapport;
- trusted source registry en lineage completeness audit;
- immutable corpus, split/duplicate/temporal/label audits en human-reviewmanifest;
- pinned AI image digest/SBOM en RTX 4080 CUDA run manifests;
- reproducible incumbent/candidate calibrationrapporten;
- vooraf bevroren gateconfig;
- één protected-test/background-test accesslog en report;
- model card, signed promotion report, shadow report en rollbacktest;
- bijgewerkte API/contracts, limitations, execution log en TODO.

## Stop-the-line criteria

Stop de betrokken pipeline en behoud `release blocked` wanneer:

- protected data vóór de freeze wordt gelezen of in sampler/training evidence voorkomt;
- een geometry zonder betrouwbare CRS of een meteroperatie in graden wordt verwerkt;
- user metadata officiële authority kan verlenen;
- model/dataset/tile/config hashes ontbreken;
- een verplichte metric null/ontbrekend is;
- menselijke labelreview Critical/High findings openlaat;
- training niet aantoonbaar op de vereiste NVIDIA GPU draait;
- een regio/context/background-gate faalt;
- de protected test faalt;
- deploy commit, image, model, DB migration en promotion report niet exact aan elkaar gebonden zijn.

Alleen bewijs kan een gate openen. Een nieuwe training, hogere epoch count of gunstig aggregate cijfer kan een ontbrekende lineage-, split-, regionale, menselijke of deploymentgate niet compenseren.