Epic: QGIS project generation, validation, and override round-trip

[jaakla]

Context

QGIS is valuable as a professional desktop inspection and editing surface for Open-GIS projects, but its runtime, packaging, datasource, styling, and edit round-trip requirements are substantial enough to evolve independently from the core reproducible-project contract in #4.

This future epic owns QGIS support. QGIS work must not block completion of the core open-gis-project/v1 manifest, pipeline, validation CLI, or standardized web/report views.

Goal

Provide an optional, production-quality QGIS companion generated from the same canonical project artifacts and derived datasets as every other view, without creating hidden analytical state or mutating immutable sources.

Scope

Project generation

• Generate project.qgz from project.yaml, presentation semantics, derived datasets, and override layers.
• Use portable project-relative datasource paths.
• Generate valid GeoPackage datasource strings with explicit layername= parameters.
• Include appropriate regional tiled basemaps with attribution.
• Preserve layer grouping, ordering, visibility, labels, legends, and semantic styling.

Web/QGIS parity

• Define deterministic mappings from semantic presentation roles to QGIS styles.
• Keep layer-tree groups and categorized styles aligned with the standardized web view.
• Add parity checks for source layers, derived layers, override layers, categories, colors, and visibility defaults.

Runtime validation

• Pin and document a supported QGIS/PyQGIS runtime.
• Validate that the project loads and that every required layer returns isValid().
• Distinguish failed, warning, and not_testable; never infer success from archive generation or process exit code alone.
• Add deterministic fixture and CI coverage for static validation, plus an appropriate PyQGIS-enabled integration job.

Editable override round-trip

• Make designated override/scenario layers editable without exposing immutable source layers for mutation.
• Export deliberate QGIS edits into canonical project overrides or open-gis-override-bundle/v1.
• Preserve feature identity, asserted prior values, author, timestamps, rationale, evidence, geometry origin, and base-run/source preconditions.
• Support canonical importer validation and pipeline reruns after edits.
• Detect conflicts when the source version or base run has changed.

Documentation and examples

• Document supported QGIS versions, installation, generation, validation, editing, and troubleshooting.
• Provide a worked example demonstrating generation, inspection, an editable override, export, canonical application, and rerun.

Acceptance criteria

• A project can generate a portable project.qgz from canonical artifacts with no independent analytical state.
• All required layers load as valid in the pinned PyQGIS runtime.
• Layer groups, styling, categories, labels, and default visibility match declared presentation semantics and the web view.
• Source layers remain immutable; only designated override layers are editable.
• A QGIS edit can be exported with complete provenance and applied canonically through the pipeline.
• Stale base-run/source preconditions are rejected rather than silently rebased.
• Static and runtime validation produce explicit machine-readable results.
• A clean-environment worked example completes generation → edit → export → apply → rerun.

Non-goals

• Defining the core open-gis-project/v1 manifest and reproducibility contract; that remains in Reproducible GIS Projects, Not One-Off Answers #4.
• General HTML dashboard editing; tracked separately by feat: add local-first edit mode and draft override bundles to HTML dashboard #8 and its implementation PR.
• Browser-side DuckDB Spatial/Wasm or other edge-compute execution.
• Requiring QGIS for projects whose requested outputs are web views, reports, or data products only.

Relationship to existing work

• Extracted from Reproducible GIS Projects, Not One-Off Answers #4 so core reproducible-project support can complete independently.
• Dashboard draft override authoring is tracked in feat: add local-first edit mode and draft override bundles to HTML dashboard #8.
• Canonical override import/application should be shared by dashboard and QGIS workflows rather than implemented twice.

[jaakla]

Do a test with map screenshot from map data location and appropriate zoom - it has to match with html view content-wise (no layers in completely wrong place) and in visual styling (with minor differences).
Layers and map view needs to have explicit and validate CRS, which matches with data.