feat: harden governed PyTorch training programme

docs/AI_PIPELINES.md

@@ -1,5 +1,14 @@
 # AI Pipelines
 
+The cross-task PyTorch scope, capability matrix and national promotion waves are
+defined in `docs/PYTORCH_MODEL_PROGRAM.md`. PyTorch is used only for trainable
+imagery tasks; authoritative GIS measurements remain source-derived. The
+single-class tile exporter accepts explicit `--class-name`,
+`--reference-source` and `--reference-layer` bindings and persists them in its
+evidence summary. Production Tower training uses `TRAIN_DEVICE=cuda:0` with
+`TRAIN_REQUIRE_CUDA=true`, which fails closed without CUDA and records the
+PyTorch/CUDA runtime in `training_summary.json`.
+
 ## 1. Object Detection Pipeline
 
 ```text

docs/CODEX_EXECUTION_LOG.md

@@ -1,3 +1,13 @@
+## 2026-07-26 - PyTorch programme clarification and training hardening
+
+- Clarified that PyTorch governs trainable imagery models and does not replace authoritative terrain, flood, land-use, road, water or change analyses.
+- Audited Tower: CUDA PyTorch runs on the RTX 4080 SUPER; only the building corpus currently has promotion evidence. The active building candidate measures roughly 0.61 mean F1 on the expanded independent portfolio and zero detections on three pure-empty background samples.
+- Generalized the tile exporter with explicit canonical class, reference source and reference layer evidence so regional authorities cannot be silently mixed.
+- Added fail-closed `TRAIN_REQUIRE_CUDA` behavior and PyTorch/CUDA runtime evidence to training summaries.
+- Added `docs/PYTORCH_MODEL_PROGRAM.md` with the task matrix and national training waves.
+- Verification: 14 focused exporter/training tests passed.
+- Open: nationwide building training cannot honestly start until spatially disjoint, temporally compatible GRB/PICC/URBIS plus orthophoto samples have been materialized and reviewed.
+
 ## 2026-07-19 - GeoIntel 1.0.0 final release closeout
 
 - Promoted the current clean `main` revision to semantic version `1.0.0` in

docs/PYTORCH_MODEL_PROGRAM.md

@@ -0,0 +1,52 @@
+# PyTorch model programme
+
+## Principle
+
+PyTorch is the governed CUDA runtime for trainable image models. It is not a
+replacement for authoritative GIS processing. Terrain, flood depth, land-use
+classes, road length, water area and vector/raster change remain deterministic
+source-derived analyses.
+
+## Capability matrix
+
+| Capability | Method | Current state | Promotion requirement |
+|---|---|---|---|
+| Building localisation | YOLO detection on orthophoto | Operational for `building`; validated only in Mol/Kempen | geographically independent Belgian train/validation/test portfolio, including Flanders, Wallonia and Brussels |
+| Building footprint | official GRB/PICC/URBIS geometry | Operational where the governed source covers the AOI | no neural model; source coverage and freshness gates |
+| Roads and water | official vectors and thematic rasters | Operational by provider zone | no detector unless a separately justified imagery use case and reviewed labels exist |
+| Land use / vegetation | official classified rasters | Operational where source coverage exists | no neural model; preserve official class semantics |
+| Terrain / flood / bathymetry | numeric raster analysis | Operational or explicit `not_configured` per source | no neural model; source and CRS validation |
+| Solar panels or other imagery objects | dedicated detector | Unvalidated local asset only | task-specific labels, negative corpus, independent hold-outs and promotion report |
+| Segmentation | dedicated YOLO-seg/SAM model | `not_configured` | reviewed polygon/mask corpus and segmentation QA; detection boxes are not valid mask labels |
+
+## Training rules
+
+1. One model contract per task and canonical class set.
+2. Training, validation and test samples are separated geographically; an AOI
+   or overlapping image tile may occur in only one split.
+3. Reference labels identify authority, source, layer, observation/publication
+   date, CRS and checksum.
+4. Production training requires NVIDIA CUDA and fails closed when unavailable.
+5. Every challenger is evaluated on positive AOIs, pure-empty negatives and
+   difficult contextual negatives. Promotion is never based on training loss.
+6. A model remains `not_configured` outside its independently proven geography
+   and classes.
+
+## Executable waves
+
+1. **Building Belgium corpus:** prepare spatially disjoint samples from GRB
+   (Flanders), PICC (Wallonia) and URBIS (Brussels) against temporally compatible
+   orthophotos. Keep complete municipalities outside training as test areas.
+2. **Building challenger:** train on Tower using PyTorch CUDA, compare against
+   the active model at fixed thresholds and retain the current model unless all
+   promotion gates pass.
+3. **Additional imagery task intake:** admit solar panels or another class only
+   after an explicit use case and reviewed labels exist. Never infer new classes
+   from the building corpus.
+4. **Segmentation intake:** build a polygon/mask corpus and independent QA before
+   enabling YOLO-seg or SAM.
+
+The tile exporter accepts explicit `--class-name`, `--reference-source` and
+`--reference-layer` values and records them in dataset evidence. The production
+training wrapper supports `TRAIN_REQUIRE_CUDA=true` and records CUDA and PyTorch
+runtime evidence in every training summary.

docs/TODO.md

@@ -1,5 +1,14 @@
 # GeoIntel TODO
 
+## PyTorch-modelprogramma
+
+- [x] Scheid trainbare beeldtaken van deterministische GIS-analyses.
+- [x] Generaliseer de single-class tile-export op klasse, referentiebron en referentielaag.
+- [x] Laat productietraining fail-closed stoppen wanneer vereiste CUDA ontbreekt.
+- [ ] Materialiseer geografisch gescheiden GRB/PICC/URBIS-gebouwcorpora met temporeel passende orthofoto's.
+- [ ] Train en evalueer een Belgische gebouwchallenger onafhankelijk; promoveer alleen zonder achtergrondregressie.
+- [ ] Houd zonnepanelen en segmentatie `not_configured` tot gereviewde taaklabels en hold-outs bestaan.
+
 ## Actieve post-RC datadekkingsfase
 
 - [x] Voeg een interactieve, data-gedreven projectatlas toe aan de statuswerkruimte met toegankelijke navigatie, echte readiness-toestanden en reduced-motion ondersteuning.