Jens/geointel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Start autonomous Belgium and North Sea RC
GeoIntel CI / docs-smoke (push) Canceled after 0s
Details
GeoIntel CI / contract-smoke (push) Canceled after 0s
Details

Browse Source
This commit is contained in:
Codex
2026-07-18 00:12:34 +02:00
parent 9513f8613e
commit 9c402e0df2
36 changed files with 2235 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/API_CONTRACTS.md
+48 -28
View File
@@ -41,48 +41,68 @@ Any valid GeoJSON geometry object. V1 primarily expects `Polygon` and `MultiPoly
## Health
### GET `/health`
### GET `/health/live`
Returns service status.
Returns process liveness only. It never queries PostgreSQL.
```json
{
"status": "ok",
"service": "geointel-backend",
"version": "0.1.0"
"version": "0.1.0",
"build_sha": null,
"build_time": null
}
```
### GET `/health`
Backward-compatible alias for dependency readiness.
### GET `/health/ready`
Returns dependency readiness. Both readiness routes return HTTP 503 when the
database, PostGIS, single migration head or writable storage check is
degraded. Docker uses `/health/ready`.
```json
{
"status": "ok",
"service": "geointel-backend",
"version": "0.1.0",
"database": "ok",
"postgis": "ok:3.x",
"migration": "ok:202607160001",
"storage": "ok",
"checks": {
"database": "ok",
"postgis": "ok:3.x",
"migration": "ok:202607160001",
"storage": "ok"
}
}
```
### GET `/api/v1/system/capabilities`
Returns enabled feature flags and tool availability.
Returns enabled feature flags and tool availability in the canonical data
envelope. PostGIS and configured YOLO state are derived at runtime.
```json
{
"postgis": true,
"rasterio": true,
"geopandas": true,
"yolo": false,
"sam": false,
"grb": "bounded",
"sentinel": "planned",
"providers": [
{
"provider_name": "grb",
"display_name": "GRB",
"authority_level": "authoritative",
"supported_layers": ["buildings", "roads", "water", "parcels"],
"supported_geometry_types": ["Polygon", "MultiPolygon", "LineString", "MultiLineString"],
"supported_query_modes": ["bbox", "persisted_area"],
"fetch_signature": "POST /api/v1/projects/{project_id}/datasets/grb/acquire",
"configured": true,
"status": "configured",
"limitation_message": "Alleen expliciet begrensde selecties tot 20 km per zijde worden opgehaald.",
"attribution": "Bron: Grootschalig Referentie Bestand Vlaanderen, Digitaal Vlaanderen",
"license_note": "Hergebruik volgens de open-datavoorwaarden en bronvermelding van Digitaal Vlaanderen.",
"not_configured_reason": null
}
]
"data": {
"postgis": true,
"rasterio": true,
"geopandas": true,
"yolo": true,
"yolo_status": "configured",
"sam": false,
"grb": "bounded",
"sentinel": "planned",
"version": "0.1.0",
"build_sha": null,
"providers": []
}
}
```
docs/BUILD_STATUS.md
+50 -26
View File
@@ -1,38 +1,62 @@
# GeoIntel Build Status
Current preparation milestone: M7 Implementation Control Layer.
Updated: 2026-07-17
## Done
## Current state
- Product blueprint.
- Data specifications.
- Architecture specifications.
- API/database/service documentation.
- Codex build plans and prompts.
- Operational readiness docs.
- Autonomy pack.
- M7 build control, regression traps and self-review layer.
GeoIntel is an implemented map-first GeoAI workbench running as an all-in-one
Unraid container with embedded PostGIS, FastAPI, React/MapLibre, local
Ollama integration and optional local YOLO/PyTorch inference.
## Ready for Codex
The active release program is
`docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md`.
Codex can begin with repository verification and backend foundation using the locked build sequence.
## Product scope
## Must Preserve
- Target: all Belgian land and the separately labelled Belgian territorial
sea, EEZ and continental shelf.
- Existing deep regression references: Mol and the Kempen transport region.
- Required new golden areas: Wallonia, Brussels, a cross-region area, coast
and Belgian North Sea.
- Architecture: federated authoritative providers with one coverage matrix;
no assumption that GRB, PICC, UrbIS and NGI are semantically identical.
- GeoIntel is a GeoAI Workbench for the Kempen.
- GRB-first reference strategy.
- FastAPI + React + PostGIS.
- API-driven frontend.
- CRS-aware geospatial processing.
- Fixture mode must be clearly labeled.
## Implemented foundation
## Known Limitations Before Code Build
- Projects, Areas, Datasets, versions, PostGIS vector features and raster
artifacts.
- Map selection, semantic metrics, historical comparison and exports.
- Governed Flemish sources for buildings, context, orthophotos, terrain,
flooding, soil, nature, agriculture, population and policy rasters.
- Detection persistence, local configured YOLO/PyTorch path, QA/QC and review
evidence.
- Segmentation persistence foundation without fake production inference.
- Local Ollama assistant grounded in persisted evidence.
- Single-container Unraid deployment on port 1202.
- Real GRB WFS integration still needs implementation.
- Real YOLO/SAM inference should follow fixture boundary first.
- Sentinel and LiDAR remain post-foundation roadmap items.
- No production authentication in V1.
## Release blockers
## Next Recommended Codex Pass
- Current production backup and isolated restore proof.
- Fail-closed readiness and truthful runtime capability reporting.
- Stale job/run reconciliation and correlated exception logging.
- Temporal compatibility guard for detection QA.
- Production secret/configuration parity, immutable images and rollback.
- Full CI, reproducible dependencies and supply-chain evidence.
- Critical response-model typing and real frontend/browser E2E coverage.
- National and maritime scope/providers/golden areas.
Run `prompts/codex/PASS_00_REPO_AUDIT.md`, then implement backend foundation according to `docs/12-build-control/BUILD_SEQUENCE_LOCK.md`.
## Latest evidence
Run:
```bash
python scripts/capture_release_evidence.py \
--output storage/release-evidence/rc-current/baseline.json \
--release-id rc-belgium-north-sea \
--live-base-url http://192.168.10.150:1202
```
The evidence manifest is runtime output and is deliberately ignored by Git.
The first captured baseline reported one Alembic head (`202607160001`) and
reachable live health/capability routes. Health truthfulness is an open RC-2
blocker until readiness becomes fail-closed.
docs/CODEX_EXECUTION_LOG.md
+39
View File
@@ -1,3 +1,42 @@
## Autonomous RC program for Belgium and the Belgian North Sea (2026-07-17)
- Froze the RC geography as all Belgian land plus the separately labelled
territorial sea, EEZ and continental shelf.
- Retained Mol and the Kempen as validated regression areas instead of the
final product boundary.
- Added `docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md`.
- Added `docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md` with autonomous stop rules,
exact phase gates, evidence requirements and RC-0 through RC-11.
- Removed the need for a separate RC-12 phase. Fresh-install, upgrade,
rollback and runtime evidence remain mandatory inside RC-5 and RC-11.
- Verified the official source families for NGI/IGN, Statbel, SPW Wallonia,
UrbIS Brussels, federal marine planning, RBINS/BMDC and MDK before freezing
the coverage architecture.
- Started RC-0 implementation; the release-evidence command is the first code
gate.
- Implemented and tested `scripts/capture_release_evidence.py`. The first
local/live baseline recorded commit `9513f86`, dirty-state evidence, one
Alembic head `202607160001`, dependency/configuration checksums and reachable
Tower health/capability routes without storing secret values.
- Replaced the obsolete pre-implementation `docs/BUILD_STATUS.md` with the
current RC state and moved runtime release evidence outside Git.
- RC-0 is complete. RC-1 backup/restore safety is active.
- Added atomic custom-format PostgreSQL backup, read-only verification and
generated-database restore-smoke scripts. Their focused safety/syntax tests
pass; Tower backup and isolated restore execution remain the RC-1 live gate.
- Implemented RC-2 truthful runtime state: independent liveness, fail-closed
DB/PostGIS/Alembic/storage readiness, runtime-derived YOLO capability,
request correlation IDs, exception trace logging, SQL logging at WARNING
and all-in-one startup reconciliation for orphaned `running` jobs/runs.
- Docker, Nginx, API contracts and health documentation now use
`/health/ready`; `/health` remains a compatibility readiness alias.
- Validation passed: targeted Ruff, backend compile, 963 backend tests,
frontend typecheck/build, 122-route contract audit, one Alembic head,
complete offline migration SQL and the full readiness gate.
- Local Docker CLI is unavailable on the Windows Codex host. Docker config,
image build, live health truthfulness, backup and restore are therefore
scheduled on the Docker-enabled Tower after push.
## Sprint 229 - Governed ALZ definitive release promotion (2026-07-17)
Implemented:
docs/HEALTHCHECK_CONTRACTS.md
+25 -10
View File
@@ -5,8 +5,15 @@ Elke runtime-component moet een eenvoudige en machineleesbare healthcheck hebben
## Backend
### Endpoint
`GET /health`
### Liveness
`GET /health/live` returns HTTP 200 while the FastAPI process can serve a
request. It has no database or storage dependency.
### Readiness
`GET /health/ready` is the Docker healthcheck. `GET /health` is the
backward-compatible alias.
### Response 200
```json
@@ -15,8 +22,15 @@ Elke runtime-component moet een eenvoudige en machineleesbare healthcheck hebben
"service": "geointel-backend",
"version": "0.1.0",
"database": "ok",
"redis": "ok",
"storage": "ok"
"postgis": "ok:3.x",
"migration": "ok:202607160001",
"storage": "ok",
"checks": {
"database": "ok",
"postgis": "ok:3.x",
"migration": "ok:202607160001",
"storage": "ok"
}
}
```
@@ -25,10 +39,10 @@ Elke runtime-component moet een eenvoudige en machineleesbare healthcheck hebben
{
"status": "degraded",
"service": "geointel-backend",
"database": "unavailable",
"redis": "ok",
"storage": "ok",
"errors": ["database connection failed"]
"database": "degraded",
"postgis": "degraded",
"migration": "degraded",
"storage": "ok"
}
```
@@ -51,7 +65,8 @@ Codex mag kiezen tussen een internal endpoint of CLI-command, maar het contract
Frontend moet een `/status` of settings/statuspanel hebben dat toont: backend bereikbaar, API version, auth status, feature flags en laatste healthchecktijd.
## Storage
Storage healthcheck controleert of upload, originals, derived en exports writable zijn.
De readinesscheck maakt en verwijdert een tijdelijk bestand in `STORAGE_ROOT`.
## Database
Database healthcheck controleert connectie, PostGIS extension en migrationstatus.
De readinesscheck controleert `SELECT 1`, `PostGIS_Version()` en dat de
databaseversie exact overeenkomt met de enige Alembic-head in de image.
docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md
+471
View File
@@ -0,0 +1,471 @@
# Autonomous RC Roadmap: Belgium and the Belgian North Sea
## Mission
Turn the current GeoIntel implementation into a reproducible, demonstrable and
release-candidate-quality map-first workbench for all of Belgium and the
Belgian North Sea.
This file is an executable runbook for Codex. It is both the implementation
order and the release evidence index. Work continues autonomously between
phases. A separate RC-12 phase is deliberately omitted.
## Sources of truth
Read in this order before changing behavior:
1. `AGENTS.md`
2. `docs/CODEX_BOOTSTRAP_PROMPT.md`
3. `docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md`
4. `docs/governance/GEOINTEL_CONSTITUTION.md`
5. `docs/governance/ARCHITECTURE_INVARIANTS.md`
6. `docs/governance/FORBIDDEN_DECISIONS.md`
7. `docs/API_CONTRACTS.md`
8. `docs/DATABASE_IMPLEMENTATION_PLAN.md`
9. `docs/DATA_SPECIFICATION.md`
10. `docs/DATA_SOURCES.md`
11. `docs/STORAGE_ARCHITECTURE.md`
12. `docs/DEFINITION_OF_DONE.md`
## Autonomous execution contract
Codex shall:
- execute phases in order and continue without requesting routine approval;
- use existing service, dataset, vector-feature, raster and job boundaries;
- keep every provider bounded, fail-closed and provenance-complete;
- add or update tests with every behavior change;
- update `docs/CODEX_EXECUTION_LOG.md`, `docs/TODO.md` and `CHANGELOG.md`
after each completed phase;
- run the phase gate and record exact output under
`storage/release-evidence/<release-id>/`;
- commit and push only after the relevant local gate is green;
- deploy only a commit that passed the local gate;
- run browser and live API acceptance after deployment;
- retain Mol/Kempen as regression references while adding Wallonia, Brussels,
cross-region, coast and North Sea golden areas.
Codex stops only when:
- an operation would destructively mutate or delete unbacked production data;
- an external licence, credential or authority decision cannot be derived from
public source metadata;
- an official endpoint fails security validation and no authoritative
alternative exists;
- the same mandatory gate fails three times for the same external reason; or
- continuing would require fabricating data, metrics, provenance or model
output.
For a stop, write the blocker, evidence and exact resume command to the
execution log. Continue with independent work when possible.
## Release priorities
### P0 - release blockers
- truthful health/readiness and capability reporting;
- current backup plus isolated restore proof;
- stale job/run reconciliation and useful logs;
- temporally correct detection QA;
- production secrets, upload limits, configuration parity and rollback;
- full CI and reproducible dependencies;
- fresh install and upgrade proof.
### P1 - national product completeness
- national and maritime scope model;
- governed source coverage matrix;
- Wallonia, Brussels and North Sea adapters;
- nationwide bounded selection and mixed-zone result handling;
- historical compatibility matrix;
- golden areas outside Flanders.
### P2 - quality and maintainability
- typed response models on critical routes;
- frontend unit and browser E2E coverage;
- loading/accessibility/performance hardening;
- retention and operator documentation;
- remaining bounded modularization where protected by tests.
## Global gates
Run after every behavior-changing phase:
```bash
python -m compileall backend/app
cd backend && python -m pytest
cd frontend && npm run typecheck
cd frontend && npm run build
bash scripts/run_readiness_check.sh
cd backend && python -m alembic heads
cd backend && python -m alembic upgrade head --sql
bash -n scripts/live_migration_smoke.sh
docker compose config
```
When Tower is reachable:
```powershell
.\scripts\deploy_tower.ps1
```
Then verify:
```bash
curl -fsS http://192.168.10.150:1202/health/live
curl -fsS http://192.168.10.150:1202/health/ready
curl -fsS http://192.168.10.150:1202/api/v1/system/capabilities
```
The in-app browser acceptance must cover desktop, widescreen and a narrow
viewport. It must inspect console errors, failed requests and the complete
map-select-analyse-export flow.
## Official source baseline
The roadmap starts from these verified official families. Machine endpoints,
editions and licences must still pass source-specific probes before activation.
| Scope | Candidate | Role |
| --- | --- | --- |
| Belgium | NGI/IGN AdminVector and Top10Vector | authoritative boundary and common topographic baseline |
| Belgium | Statbel statistical sectors/population | authoritative statistical geometry and time series |
| Flanders | existing Digitaal Vlaanderen/VMM/DOV/INBO/ALZ adapters | detailed authoritative regional layers |
| Wallonia | SPW Géoportail, PICC, orthophoto, MNT and thematic services | detailed authoritative regional layers |
| Brussels | Paradigm UrbIS and regional environmental geodata | detailed authoritative urban layers |
| North Sea | FPS Marine Environment marine spatial plan | legal/use zones |
| North Sea | RBINS/BMDC and Marine Atlas | marine environment and observations |
| North Sea | MDK/Flemish Hydrography | bathymetry and nautical source candidate |
| North Sea | EMODnet | contextual fallback only when explicitly labelled |
## Phase status
| Phase | State | Purpose |
| --- | --- | --- |
| RC-0 | complete | freeze scope and produce release evidence baseline |
| RC-1 | in progress | backup, restore and data safety |
| RC-2 | verification pending | health, capabilities and stale-runtime correctness |
| RC-3 | pending | temporal detection/QA correctness and observability |
| RC-4 | pending | national/maritime scope and provider coverage contracts |
| RC-5 | pending | deployment, secrets, configuration, fresh install and rollback |
| RC-6 | pending | complete CI, dependency and supply-chain gates |
| RC-7 | pending | critical API envelope typing and contract validation |
| RC-8 | pending | frontend and browser E2E release journeys |
| RC-9 | pending | loading, accessibility and performance hardening |
| RC-10 | pending | retention, cleanup and national data operations |
| RC-11 | pending | final package, upgrade proof, release tag and handoff |
## RC-0 - Scope freeze and evidence baseline
**State: complete.** The read-only baseline command and focused tests pass.
Runtime evidence is stored outside Git under `storage/release-evidence/`.
### Work
- Freeze Belgium plus Belgian North Sea scope.
- Record current commit, migration head, dependency versions, container image,
database/storage sizes and readiness results.
- Create a release-evidence manifest command.
- Replace stale product-status wording that still treats Kempen as the product
boundary.
- Add a coverage matrix schema with `operational`, `partial`,
`not_configured`, `unsupported`.
### Likely files
- `docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md`
- `docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md`
- `docs/BUILD_STATUS.md`
- `docs/DATA_SOURCES.md`
- `scripts/capture_release_evidence.py`
- `backend/tests/test_rc_release_evidence.py`
### Evidence and exit
- scope documents contain Belgium, all three regions and maritime zones;
- evidence command is read-only and deterministic;
- manifest contains commit, dirty state, Alembic head and gate status;
- compile and focused tests pass.
## RC-1 - Backup, restore and data safety
### Work
- Add a safe production backup command for PostgreSQL custom-format dumps.
- Capture schema head, PostGIS version, table counts, model checksums and a
storage checksum inventory without duplicating all large artifacts.
- Reject default/empty production database passwords.
- Add backup verification with `pg_restore --list` and checksums.
- Add an isolated restore drill using a temporary database/container; never
restore over production.
- Document retention, encryption boundary and cleanup.
### Likely files
- `scripts/backup_release_state.sh`
- `scripts/verify_release_backup.sh`
- `scripts/restore_release_backup_smoke.sh`
- `deploy/unraid/README.md`
- `docs/ROLLBACK_AND_RECOVERY.md`
- `backend/tests/test_rc_backup_restore_scripts.py`
### Exit
- current Tower database has a dated, checksum-verified backup;
- isolated restore reaches the recorded Alembic head;
- representative project, dataset, geometry and QA counts reconcile;
- no production application data was mutated by the drill.
## RC-2 - Truthful runtime state
**State: implementation complete, live verification pending.** Local compile,
963 backend tests, frontend typecheck/build and the full readiness gate pass.
### Work
- Split process liveness from dependency readiness.
- Make readiness return HTTP 503 when DB, PostGIS, migration head or writable
storage is unavailable.
- Derive version/build identity and AI capability from runtime configuration.
- Make Docker use the readiness endpoint.
- Reconcile orphaned `running` jobs and analysis runs on process startup.
- Add request IDs and exception logging without exposing secrets or full SQL.
### Likely files
- `backend/app/api/routes/health.py`
- `backend/app/schemas/health.py`
- `backend/app/core/config.py`
- `backend/app/core/logging.py`
- `backend/app/main.py`
- `backend/app/services/runtime_reconciliation_service.py`
- Docker/nginx files and health tests
### Exit
- liveness remains 200 while the process runs;
- readiness is fail-closed;
- live capabilities match the active local YOLO state;
- restart converts impossible orphaned work to a terminal failed state with
`PROCESS_INTERRUPTED`;
- Docker reports unhealthy for a broken database.
## RC-3 - Temporal QA correctness and observability
### Work
- Stop Detection Lab from silently selecting the first raster.
- Require explicit raster/model choice.
- Prevent current reference QA against historical imagery unless a compatible
reference edition/coverage is selected.
- Persist source observation period and QA compatibility decision.
- Add structured request/job/run logs and operator diagnostics.
- Add a stale-runtime report and safe reconciliation command.
### Exit
- no detection run starts with an implicit old raster;
- incompatible temporal QA fails with a clear code;
- compatible current orthophoto/GRB path remains green;
- logs correlate request, job, analysis run and quality check.
## RC-4 - Belgium and North Sea coverage foundation
### Work
1. Persist NGI authoritative Belgium land and administrative scopes.
2. Persist territorial sea, EEZ and continental shelf as distinct scope
layers.
3. Implement the coverage matrix and source authority resolver.
4. Add bounded provider contracts for:
- NGI/Statbel national baseline;
- SPW/PICC/orthophoto/relief for Wallonia;
- UrbIS/environmental context for Brussels;
- federal marine zones and BMDC/MDK marine sources.
5. Normalize the public theme vocabulary without discarding provider-native
semantics.
6. Add Wallonia, Brussels, cross-region, coast and North Sea golden areas.
7. Make mixed-zone selection split into bounded provider requests and merge
only semantically compatible metrics.
### Required rules
- all persistence flows through DatasetService and geospatial services;
- no provider writes directly to feature tables;
- no country-wide startup import;
- no TLS bypass;
- no implicit vertical datum conversion;
- unsupported metrics remain unavailable.
### Likely files
- provider registry/base and new regional provider modules;
- geographic scope and source coverage services;
- dataset/source schemas;
- map source portfolio and scope UI;
- source, API, data and storage documentation;
- source-specific tests and fixtures.
### Exit
- a user can draw within every golden area and receive an honest coverage
matrix;
- at least the common national baseline is operational on land;
- regional detailed layers are operational or explicitly partial;
- maritime legal zones are operational;
- bathymetry remains gated until a source passes strict acquisition evidence.
## RC-5 - Production deployment and rollback
### Work
- align backend, nginx and proxy upload/time limits;
- make every runtime setting intentionally configured, internal or documented;
- reject production default secrets;
- add image labels with version, commit and build time;
- deploy immutable tags in addition to `latest`;
- preserve previous image for one-command rollback;
- prove fresh install against empty volumes;
- prove upgrade from a copied current database/storage state;
- prove rollback without schema or data loss.
### Exit
- Unraid edit fields cover all operator-owned settings;
- fresh install, upgrade and rollback commands are documented and executed;
- deployed UI exposes build identity;
- previous image remains addressable;
- no mutable-only release is accepted.
## RC-6 - CI and supply-chain gates
### Work
- make CI run backend compile/tests, frontend typecheck/build, readiness,
Alembic single-head/offline SQL and Docker config/build;
- add Python and npm dependency vulnerability checks;
- add container scan and SBOM;
- introduce reproducible Python resolution/lock output;
- preserve optional AI dependency separation;
- publish gate artefacts.
### Exit
- a broken compile, test, build, migration or contract blocks CI;
- dependency and container findings have severity policy;
- a clean checkout can reproduce dependency versions and image metadata.
## RC-7 - Critical API contract hardening
### Work
- replace `response_model=dict` first on health, projects, areas, datasets,
jobs, analysis runs, QA, exports and map-critical endpoints;
- retain canonical `{data: ...}` success and canonical error envelopes;
- add OpenAPI response validation tests;
- document intentionally streaming/download responses separately.
### Exit
- all critical map-first routes have concrete response models;
- actual payloads pass FastAPI validation;
- API contract audit and frontend typecheck pass.
## RC-8 - Release journey automation
### Work
- add frontend unit tests for selection, coverage, loading and temporal guards;
- add browser E2E for:
- open Belgium map;
- select each golden area;
- load a theme;
- inspect metric/provenance;
- compare compatible history;
- run a bounded configured detection path;
- export;
- ask Ollama with persisted context;
- include no-data, partial coverage, provider failure and unsupported metric
journeys.
### Exit
- E2E runs against a real backend/PostGIS fixture;
- no workflow depends only on source-text assertion tests;
- console and failed-request audits are clean.
## RC-9 - UX, accessibility and performance
### Work
- replace initial false `missing` source states with explicit loading;
- provide accessible names, labels, keyboard focus and status announcements;
- enforce desktop, widescreen and narrow layouts;
- record API and map-selection budgets for golden areas;
- virtualize or page large panels;
- split large modules only where tests protect behavior.
### Exit
- no core control lacks an accessible name;
- loading, empty, partial, error and ready states are distinct;
- map selection remains usable at target viewports;
- no release journey exceeds its documented budget without a visible warning.
## RC-10 - Data operations and retention
### Work
- define lifecycle for raw, normalized, derived, export, AI and evidence
artifacts;
- add dry-run-first cleanup for stale technical projects, failed work and
superseded caches;
- retain immutable official source editions and release evidence;
- report disk pressure before acquisition;
- schedule nothing implicitly; provide explicit operator commands;
- add source freshness reports for national/regional/maritime families.
### Exit
- cleanup cannot remove release evidence or current authoritative editions;
- every destructive action requires explicit confirmation and a current
backup;
- storage growth and retained provenance are reportable.
## RC-11 - Final release package
### Work
- rerun fresh-install and upgrade proof using the release image;
- rerun backup/isolated restore and rollback proof;
- execute every golden area and core browser journey;
- generate coverage, security, dependency, migration, performance and known
limitation reports;
- update operator/end-user documentation;
- remove stale status documents from active navigation without deleting
historical evidence;
- assign semantic version, create signed/checksummed release manifest, tag,
push and deploy the immutable image.
### Final acceptance
- all P0 findings are closed;
- every mandatory global gate is green;
- backup and isolated restore are proven;
- one Alembic head applies to empty and upgraded PostGIS;
- Belgium and maritime golden areas pass;
- no unsupported metric or unavailable source appears as successful;
- live browser acceptance passes at port 1202;
- remaining P1/P2 limitations are explicit, bounded and non-deceptive.
## Next command
After creating this roadmap, start RC-0 immediately:
```bash
python scripts/capture_release_evidence.py --output storage/release-evidence/rc-current/baseline.json
```
If the command does not exist yet, implementing it and its tests is the first
code task.
docs/RC_SCOPE_FREEZE_BELGIUM_NORTH_SEA.md
+148
View File
@@ -0,0 +1,148 @@
# RC Scope Freeze: Belgium and the Belgian North Sea
## Status and precedence
This document freezes the geographic and release scope for the GeoIntel
release-candidate program. It supersedes the geographic limitation in
`docs/V1_SCOPE_FREEZE.md`. The existing V1 domain, persistence, provenance,
GIS-correctness and no-fake-data rules remain in force.
Mol and the Kempen remain golden regression areas. They are no longer the
product boundary.
## Product identity
GeoIntel RC is a map-first geospatial analysis workbench for:
- the complete land territory of Belgium;
- the Belgian territorial sea;
- the Belgian exclusive economic zone and continental shelf, labelled
according to their legal meaning;
- bounded user-drawn areas that may cross municipal, provincial, regional or
land/sea boundaries.
The primary flow remains:
1. open the map;
2. choose one or more understandable themes;
3. draw or select an area;
4. load only the authoritative or explicitly contextual data available for
that area;
5. calculate source-appropriate metrics;
6. inspect provenance, limitations and time;
7. compare compatible historical editions;
8. export the result or ask the local assistant about persisted evidence.
## Geographic federation
Belgian coverage is a federation of governed adapters. GeoIntel must never
pretend that regional datasets have identical semantics merely because they
can be displayed together.
| Zone | Baseline authority | Detailed authoritative families |
| --- | --- | --- |
| Belgium-wide | NGI/IGN, Statbel, federal geo.be | AdminVector, Top10Vector/CartoWeb, statistical sectors and population |
| Flanders | Digitaal Vlaanderen and competent Flemish agencies | GRB, orthophotos, DHMV, VMM/VHA, DOV, INBO, ALZ |
| Wallonia | Service public de Wallonie | PICC, SPW orthophotos, relief, hydrography, land cover and thematic catalogues |
| Brussels | Brussels Capital Region/Paradigm and competent administrations | UrbIS, BruGIS and Brussels open geodata |
| Belgian North Sea | federal Marine Environment, RBINS/BMDC, MDK and legally competent publishers | maritime plan and zones, marine environment, hydrography and validated bathymetry |
NGI Top10Vector is the preferred common topographic baseline candidate when
its machine access, licence, edition and bounded retrieval contract have been
validated. Regional large-scale products remain preferred where their
authority and semantic detail are higher.
## Required RC coverage
The RC must provide:
- a persisted authoritative Belgium land boundary;
- persisted and legally labelled maritime scope boundaries;
- area selection anywhere inside the combined Belgium/maritime scope;
- a coverage matrix that reports every theme as `operational`, `partial`,
`not_configured` or `unsupported` for the selected zone;
- source, authority, observation time, publication time, CRS, licence,
attribution, coverage and limitation metadata for every result;
- bounded acquisition and analysis; no browser-side source fetch and no
unbounded country-wide request to a public service;
- compatible historical comparison only where editions, units, coverage and
methods are comparable;
- a stable national theme vocabulary while preserving provider-native fields
and semantics.
The minimum common theme vocabulary is:
- administrative context;
- buildings and built environment;
- roads and mobility context;
- surface water and hydrography;
- land cover and land use;
- vegetation, forest and nature;
- population and statistical context;
- elevation and terrain;
- orthophoto/aerial imagery;
- flood or climate context where authoritative data exists;
- maritime planning, marine environment and bathymetry for the Belgian North
Sea where authoritative data exists.
Not every theme must have the same resolution or historical depth in every
zone. Absence or partial coverage must be visible and must not be replaced by
fabricated values.
## Golden release areas
National support is validated through bounded golden areas, not one monolithic
import:
- Mol municipality: existing deep land and AI regression reference;
- Kempen transport region: existing cross-municipality and partition test;
- one Walloon urban/rural boundary-crossing area;
- one Brussels urban area;
- one cross-region or language-boundary area;
- one coastal land/sea area;
- one Belgian North Sea area containing at least two legal/use zones.
Exact golden area identifiers and checksums must be stored in release
evidence. A source is not nationally operational merely because the Mol test
passes.
## Maritime and bathymetry rules
- Territorial sea, EEZ and continental shelf are separate legal scopes.
- TAW, LAT, mDNG, NAP and product-specific vertical references remain
separate dimensions.
- No value is transformed between vertical datums without an authoritative,
tested transformation and an uncertainty statement.
- Bathymetry is bed elevation or depth relative to a stated reference plane.
It is not water volume.
- Water volume requires compatible bed elevation, water-surface elevation,
time, coverage and uncertainty contracts.
- WMTS/WMS imagery may provide visual context but is not an analytical raster
unless pixel values and georeferencing are governed and validated.
## Explicit exclusions from this RC
- automatic whole-country mirroring of every source;
- bypassing TLS, licence or source-integrity failures;
- claiming semantic parity between GRB, PICC, UrbIS and NGI products;
- hidden external downloads at application startup;
- browser-direct provider access;
- production multi-user authentication;
- real-time surveillance or operational maritime navigation;
- unsupported water-volume estimates;
- a separate RC-12 soak phase.
Fresh-install, upgrade, rollback and runtime-stability evidence are mandatory
but are incorporated into RC-5 and RC-11.
## Scope change control
During the RC program, a scope change is allowed only when it:
1. fixes a release blocker;
2. adds missing coverage required by this document;
3. corrects source authority, provenance, CRS, time or metric semantics; or
4. improves verification without adding unrelated product capability.
Every accepted change must update the autonomous roadmap, execution log and
relevant source/API documentation.
docs/ROLLBACK_AND_RECOVERY.md
+21
View File
@@ -11,3 +11,24 @@ Bestanden worden niet stilzwijgend verwijderd. Gebruik soft-delete waar mogelijk
## AI/model rollback
Elke analysis run bewaart model id, version, parameters, confidence threshold en pipeline version.
# RC backup and isolated restore gate
Before any release migration, credential rotation or image promotion:
1. run `scripts/backup_release_state.sh` against the running all-in-one
container;
2. run `scripts/verify_release_backup.sh` read-only;
3. run `scripts/restore_release_backup_smoke.sh` with
`--confirm-isolated-restore`;
4. retain the backup directory and the separate restore-smoke JSON with the
release evidence.
The restore smoke may only create databases whose name starts with
`geointel_restore_verify_`. It refuses the production database name, does not
use `pg_restore --clean` and drops the temporary database unless an operator
explicitly asks to retain it.
Storage and model files are inventoried rather than copied into the database
dump. Release backups must therefore be paired with the persistent storage
volume backup policy. Use `--inventory-mode sha256` for final release
evidence.
docs/TODO.md
+30
View File
@@ -1,5 +1,35 @@
# GeoIntel TODO
## Actief RC-programma: Belgie en de Belgische Noordzee
`docs/RC_ROADMAP_BELGIUM_NORTH_SEA.md` is vanaf 2026-07-17 het enige actieve
releasebord. Mol en de Kempen blijven regressiereferenties, maar de
productscope is nu heel Belgie plus de juridisch correct gelabelde Belgische
maritieme zones.
- [x] RC-0: Belgische en maritieme scopefreeze vastleggen.
- [x] RC-0: autonome roadmap zonder afzonderlijke RC-12 vastleggen.
- [x] RC-0: deterministisch release-evidence manifest implementeren en draaien.
- [ ] RC-1: actuele productiebackup, verificatie en geisoleerde restore bewijzen.
- [ ] RC-2: liveness/readiness/capabilities fail-closed en waarheidsgetrouw maken.
- [ ] RC-2: verweesde jobs en analysis runs na een procesherstart verzoenen.
- [ ] RC-3: expliciete rasterkeuze en temporeel compatibele detectie-QA afdwingen.
- [ ] RC-4: nationale basisdekking, Wallonie, Brussel en Belgische Noordzee via
beheerde providers en golden areas operationaliseren.
- [ ] RC-5: secrets/configuratie/uploadlimieten/immutable deploy en rollback
bewijzen.
- [ ] RC-6: volledige CI, dependency-audit, containerscan en SBOM toevoegen.
- [ ] RC-7: kritieke API-routes concrete responsemodellen geven.
- [ ] RC-8: echte frontend- en browser-E2E-releaseflows toevoegen.
- [ ] RC-9: loading, toegankelijkheid, widescreen/mobile en performance afronden.
- [ ] RC-10: dataretentie, diskdruk en veilige cleanup operationaliseren.
- [ ] RC-11: fresh install, upgrade, rollback, releasepakket, tag en live
acceptatie afronden.
Een aparte RC-12/soakfase wordt niet uitgevoerd. De relevante fresh-install-,
upgrade-, rollback- en runtimebewijzen zijn verplicht opgenomen in RC-5 en
RC-11.
## Actuele V1-productstatus
Dit is het enige actuele afwerkingsbord. De lange sprint- en