openmapstack 0.2.0__tar.gz

openmapstack-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaak Laineste
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openmapstack-0.2.0/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: openmapstack
+Version: 0.2.0
+Summary: Validate, run, and inspect reproducible OpenMapStack projects
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema<5,>=4
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: geo
+Requires-Dist: duckdb>=1.2; extra == "geo"
+Provides-Extra: visual
+Requires-Dist: playwright>=1.40; extra == "visual"
+Provides-Extra: all
+Requires-Dist: openmapstack[geo,visual]; extra == "all"
+Dynamic: license-file
+
+# openmapstack
+
+**Geospatial questions →  reproducible, validated GIS analysis project (with very nice interactive map).**
+
+Install:
+```bash
+npx skills add jaakla/openmapstack -g
+```
+
+OpenMapStack gives your favorite AI agent: Claude Code, Codex, Cursor, OpenCode, and 50+ other agents a production workflow from **authoritative data discovery** through analysis to interactive web and GIS deliverables. Material workflows become inspectable and repeatable well-defined projects in a `yaml` file with pinned sources, explicit assumptions and CRS choices, deterministic processing, isolated overrides, machine-readable validation, and surfaced provenance.
+
+It is open-first and cloud-native by default, built on shoulders of the awesome Open GIS stack: STAC for discovery; GeoParquet, COG, and PMTiles for storage and delivery; DuckDB and PostGIS for compute; and QGIS, MapLibre, and Martin for presentation. It also uses GDAL/OGR, GeoPandas, xarray/rioxarray, PDAL, routing engines, spatial SQL, and pragmatic hosted services when scale or reliability requires them.
+
+## What's in this repo
+
+- [SKILL.md](SKILL.md) — the skill entry point: triggers, global defaults, format and compute decision matrices, anti-patterns, and a quick triage guide.
+- [references/data-sources.md](references/data-sources.md) - lists OSM, Overture, Sentinel/Landsat, regional portals, STAC catalogs and others.
+- [references/services-and-scale.md](references/services-and-scale.md) - depending on case use local installs or hosted/SaaS services for global-scale basemaps, elevation, routing, geocoding, place search, and postcodes.
+- [references/formats-and-crs.md](references/formats-and-crs.md) - how to choose formats, conversions, projections, EPSG codes.
+- [references/processing.md](references/processing.md) - when and how to use GDAL/OGR, GeoPandas, xarray, DuckDB, PostGIS, PDAL and other open geo processing tools.
+- [references/analytics.md](references/analytics.md) — do vector/raster analytics, terrain, hydrology, network, point clouds, geocoding etc.
+- [references/web-delivery.md](references/web-delivery.md) — renderer selection for maps, PMTiles, MVT, Martin, TiTiler, MapLibre, deck.gl, kepler.gl, and lonboard formats and engines.
+- [references/qgis.md](references/qgis.md) — QGIS desktop, plugins, PyQGIS, Processing, QGIS MCP.
+- [references/validation-and-ops.md](references/validation-and-ops.md) — validation, manifests, attribution, and deployment checks, including the machine-readable reproducible-project contract.
+- [references/project-spec.md](references/project-spec.md) — the specific`openmapstack-project/v1` schema: compiling any material analysis into a reproducible GIS project (`project.yaml`, pipeline, source provenance, overrides, validation, semantic presentation, QGIS output).
+- [templates/](templates/) — ready scaffolds (`project.yaml`, `pipeline.py`, `presentation.yaml`, `validation.yaml`) for new projects.
+- [examples/tartu-development/](examples/tartu-development/) — a fully-worked reproducible project matching the acceptance scenario: source provenance + timestamps, explicit assumptions, two verified project overrides (a scenario attribute change with prior-value verification, and hypothetical scenario geometry), deterministic pipeline, machine-readable validation, and semantic presentation.
+- [evals/](evals/) — the eval suite grading whether an agent reaches the right analytical answer, respects the GIS-method guardrails, and reruns reproducibly, with the `openmapstack-project/v1` contract as the substrate that makes those independently checkable: `python evals/run.py --mode fixture` runs deterministic, no-LLM checks against real generated artifacts (analytical correctness against known geospatial truth, metric CRS, source immutability, schema, overrides, validation integrity, presentation contract, and clean reruns), plus adversarial cases and a pluggable live-agent benchmark (Claude Code, Codex, and any OpenAI-compatible API such as OpenRouter — URL and model via `OPENAI_COMPATIBLE_*` env, API key as a secret).
+- [`openmapstack/`](openmapstack/) — the installable `openmapstack validate/run/inspect` CLI for auditing and executing `openmapstack-project/v1` projects, plus [`openmapstack/checks/`](openmapstack/checks/): the reusable, semantic check library. All but five of its checks are oracle-free, so the same functions that grade the eval suite also grade a user's own project on data this repository has never seen.
+- [`.claude-plugin/`](.claude-plugin/) — Claude Code plugin and marketplace manifests, so the repository can also be installed with `/plugin install`. Validated in CI by [`.github/workflows/plugin.yml`](.github/workflows/plugin.yml).
+
+My local Estonia-specific guidance (Maa- ja Ruumiamet, ETAK, EPSG:3301 / L-EST97) is included for convenience. But all the global sources are incuded for world-wide coverage.
+
+## Install
+
+The recommended way is the [skills CLI](https://github.com/vercel-labs/skills), which works for Claude Code, Cursor, OpenCode, Codex, and 50+ other agents.
+
+### Recommended: skills CLI
+
+Install globally (available in every project):
+
+```bash
+npx skills add jaakla/openmapstack -g
+```
+
+Update later with `npx skills update open-map-stack`. Remove with `npx skills remove open-map-stack`.
+
+### Claude Code plugin (optional)
+
+Claude Code users can install the same repository as a plugin instead. This adds
+versioned installs, `/plugin update`, and project-scoped installs that a team
+picks up from a repository's `.claude/settings.json`:
+
+```bash
+/plugin marketplace add jaakla/openmapstack
+/plugin install open-map-stack@open-map-stack
+```
+
+The repository is its own marketplace, so no separate marketplace repo is
+needed. The plugin wraps the same root `SKILL.md` — nothing is duplicated, and
+the skills-CLI install path above keeps working unchanged.
+
+### Install the project CLI
+
+The skills installer loads the agent instructions; the Python package provides
+the project commands. From a clone of this repository:
+
+```bash
+python3 -m pip install .
+openmapstack --version
+```
+
+For development, the commands can also run directly without installation:
+
+```bash
+python3 -m openmapstack --help
+```
+
+### Manual install (fallback)
+
+If you'd rather not use the CLI, clone directly into your agent's skills directory. For Claude Code:
+
+```bash
+# User-level (every project)
+git clone https://github.com/jaakla/openmapstack.git ~/.claude/skills/open-map-stack
+
+# Project-level (one repo)
+git clone https://github.com/jaakla/openmapstack.git .claude/skills/open-map-stack
+```
+
+### Verify
+
+Start Claude Code and run `/skills open-map-stack` should appear in the list. The expected layout is:
+
+```
+<skills-dir>/open-map-stack/
+├── SKILL.md
+├── references/
+│   ├── analytics.md
+│   ├── data-sources.md
+│   ├── formats-and-crs.md
+│   ├── processing.md
+│   ├── project-spec.md
+│   ├── qgis.md
+│   ├── services-and-scale.md
+│   ├── spatial-sql.md
+│   ├── validation-and-ops.md
+│   └── web-delivery.md
+├── templates/
+│   ├── project.yaml
+│   ├── pipeline.py
+│   ├── presentation.yaml
+│   └── validation.yaml
+├── examples/
+│   └── tartu-development/
+└── .claude-plugin/          # Claude Code plugin + marketplace manifests
+    ├── plugin.json
+    └── marketplace.json
+```
+
+## Use
+
+The skill auto-activates when you ask Claude about geospatial work — terms like GIS, OpenStreetMap, Overture, Sentinel, Landsat, LiDAR, GeoTIFF, shapefile, GeoPackage, raster/vector tiles, isochrones, spatial joins, EPSG codes, and projections will all trigger it. You don't need to invoke it manually, but sometimes hinting "use open-map-stack skills" helps.
+
+Example prompts that engage the skill:
+
+- "Pull all buildings in Tartu from Overture and publish them as a PMTiles layer."
+- "Compute average NDVI for these polygons from Sentinel-2 over the last 12 months."
+- "Reproject this GeoTIFF from EPSG:3301 to EPSG:3857 as a COG."
+- "Set up an OSRM routing server from a Estonia OSM extract."
+- "Build an isochrone API around these points."
+
+If you want to force the skill to load, you can reference it explicitly:
+
+> Use the open-map-stack skill to convert this shapefile to GeoParquet.
+
+## Project CLI
+
+The CLI operates on an `openmapstack-project/v1` manifest. A project directory may
+be supplied in place of its `project.yaml` file.
+
+```bash
+# Audit the complete artifact, including outputs, report, and run record.
+openmapstack validate path/to/project.yaml
+
+# Check the produced artifacts without requiring a golden answer.
+openmapstack verify path/to/project.yaml
+
+# Run the one canonical pipeline, then validate what it produced.
+openmapstack run path/to/project.yaml
+
+# Review sources, versions, overrides, ordered steps, outputs, and latest run.
+openmapstack inspect path/to/project.yaml
+```
+
+Useful automation options:
+
+```bash
+openmapstack validate project.yaml --json --output validation/cli-report.json
+openmapstack validate project.yaml --strict       # warnings also return non-zero
+openmapstack validate project.yaml --preflight    # skip not-yet-generated artifacts
+openmapstack run project.yaml --dry-run
+openmapstack run project.yaml --json
+openmapstack inspect project.yaml --json
+```
+
+### `openmapstack verify` — check the analysis, not just the paperwork
+
+`validate` audits the manifest and its bookkeeping. `verify` runs the check
+library in `openmapstack/checks/` against what the pipeline actually produced:
+geometry read back through DuckDB Spatial, dataset CRS read from the artifact
+rather than the manifest's claim, validation evidence recomputed from the
+geodata it summarises, and QGIS project structure and runtime loading where
+PyQGIS is available.
+
+```bash
+openmapstack verify path/to/project.yaml
+openmapstack verify path/to/project.yaml --rerun     # + rebuild from source and compare
+openmapstack verify path/to/project.yaml --json --output validation/verify-report.json
+openmapstack verify path/to/project.yaml --strict    # warnings and not-testable also return 1
+```
+
+These checks require no repository-owned golden answer, so they work on data
+neither this repository nor the model has seen. They establish bounded
+structural, provenance, artifact, and reproducibility predicates; they do not
+prove every project-specific analytical answer.
+
+`--rerun` is the strongest signal available without a known answer. It rebuilds
+the project in an empty workspace from only the manifest, the declared
+immutable inputs, and the declared dependencies, runs the one canonical
+entrypoint, re-hashes the sources, and compares the outputs semantically. A
+pipeline that cannot reproduce itself, or that mutates its own declared
+immutable inputs, is not trustworthy whatever its numbers say.
+
+The check plan is derived from the manifest rather than configured, so a
+project cannot opt out of a check by omitting it: a declared output is a
+checked output. A check whose dependency is missing reports `not_testable` and
+is counted separately — never a silent pass. A mixture of executed and
+`not_testable` checks has aggregate status `warning`, and every report includes
+`applicable`, `executed`, and `execution_rate` coverage. Install
+`openmapstack[geo]` for the DuckDB-backed geodata checks; PyQGIS comes from a
+system QGIS install.
+
+See [the applicability reference](docs/verify-applicability.md) for the exact
+plan conditions, dependencies, current regression evidence, and deliberate
+exclusions. In particular, browser/dashboard checks are not yet part of the
+automatic `verify` plan.
+
+Project-specific known answers can be declared under
+`validation.expectations[]`. The five allowlisted checks cover row count,
+feature presence/absence, one feature-field value, and field range. New
+expectations start as `attestation.status: unverified`; they produce a warning
+and are not executed. The JSON report supplies the exact
+`expected_expectation_sha256` an independent reviewer must bind, together with
+the current `runs.latest.inputs_hash`. Changing the expected check, arguments,
+inputs, or a retained local evidence file invalidates the attestation and
+returns it to warning status. See
+[the project contract](references/project-spec.md#26-validation).
+
+`validate` checks manifest structure, source retrieval/version/licensing data,
+CRS declarations, processing graph resolution, override provenance and files,
+output existence, validation-report parity/status propagation, override
+application results, and run-record identity/hashes. GIS-specific checks such as
+geometry validity remain the pipeline's responsibility; the CLI verifies that
+each declared check appears exactly once with an explicit result.
+
+Normal validation warnings return exit code 0 so known limitations remain
+representable. Failures return 1; malformed invocation or an unstartable runtime
+returns 2. `--strict` makes warnings return 1.
+
+## What this skill will and won't do
+
+**Will:**
+- Recommend modern, cloud-native formats (GeoParquet, COG, PMTiles) and flag legacy patterns (Shapefile output, MBTiles for new deployments).
+- Push spatial joins to DuckDB / PostGIS instead of Python loops.
+- Discover data via STAC before downloading.
+- Preserve license metadata (OSM ODbL, Overture per-source, Sentinel attribution).
+- Pin dataset versions for reproducibility (Overture releases, STAC item IDs, OSM extract dates).
+- Compile material multi-stage analysis into a reproducible GIS project (`project.yaml` + pipeline + overrides + validation), deriving the final map/dashboard from it.
+
+**Won't:**
+- Trigger on simple location lookups ("what city is this?") or casual map references with no analytical work.
+- Default to proprietary services when an open/self-hosted option fits the scale, quality, privacy, and budget.
+
+## License
+
+Licensed under the [MIT License](LICENSE).
+
+## Contributing
+
+Issues and PRs welcome at [github.com/jaakla/openmapstack](https://github.com/jaakla/openmapstack). When adding a new tool or workflow, place it in the matching reference file and add a one-row entry to the relevant decision matrix in [SKILL.md](SKILL.md).

openmapstack-0.2.0/README.md

@@ -0,0 +1,251 @@
+# openmapstack
+
+**Geospatial questions →  reproducible, validated GIS analysis project (with very nice interactive map).**
+
+Install:
+```bash
+npx skills add jaakla/openmapstack -g
+```
+
+OpenMapStack gives your favorite AI agent: Claude Code, Codex, Cursor, OpenCode, and 50+ other agents a production workflow from **authoritative data discovery** through analysis to interactive web and GIS deliverables. Material workflows become inspectable and repeatable well-defined projects in a `yaml` file with pinned sources, explicit assumptions and CRS choices, deterministic processing, isolated overrides, machine-readable validation, and surfaced provenance.
+
+It is open-first and cloud-native by default, built on shoulders of the awesome Open GIS stack: STAC for discovery; GeoParquet, COG, and PMTiles for storage and delivery; DuckDB and PostGIS for compute; and QGIS, MapLibre, and Martin for presentation. It also uses GDAL/OGR, GeoPandas, xarray/rioxarray, PDAL, routing engines, spatial SQL, and pragmatic hosted services when scale or reliability requires them.
+
+## What's in this repo
+
+- [SKILL.md](SKILL.md) — the skill entry point: triggers, global defaults, format and compute decision matrices, anti-patterns, and a quick triage guide.
+- [references/data-sources.md](references/data-sources.md) - lists OSM, Overture, Sentinel/Landsat, regional portals, STAC catalogs and others.
+- [references/services-and-scale.md](references/services-and-scale.md) - depending on case use local installs or hosted/SaaS services for global-scale basemaps, elevation, routing, geocoding, place search, and postcodes.
+- [references/formats-and-crs.md](references/formats-and-crs.md) - how to choose formats, conversions, projections, EPSG codes.
+- [references/processing.md](references/processing.md) - when and how to use GDAL/OGR, GeoPandas, xarray, DuckDB, PostGIS, PDAL and other open geo processing tools.
+- [references/analytics.md](references/analytics.md) — do vector/raster analytics, terrain, hydrology, network, point clouds, geocoding etc.
+- [references/web-delivery.md](references/web-delivery.md) — renderer selection for maps, PMTiles, MVT, Martin, TiTiler, MapLibre, deck.gl, kepler.gl, and lonboard formats and engines.
+- [references/qgis.md](references/qgis.md) — QGIS desktop, plugins, PyQGIS, Processing, QGIS MCP.
+- [references/validation-and-ops.md](references/validation-and-ops.md) — validation, manifests, attribution, and deployment checks, including the machine-readable reproducible-project contract.
+- [references/project-spec.md](references/project-spec.md) — the specific`openmapstack-project/v1` schema: compiling any material analysis into a reproducible GIS project (`project.yaml`, pipeline, source provenance, overrides, validation, semantic presentation, QGIS output).
+- [templates/](templates/) — ready scaffolds (`project.yaml`, `pipeline.py`, `presentation.yaml`, `validation.yaml`) for new projects.
+- [examples/tartu-development/](examples/tartu-development/) — a fully-worked reproducible project matching the acceptance scenario: source provenance + timestamps, explicit assumptions, two verified project overrides (a scenario attribute change with prior-value verification, and hypothetical scenario geometry), deterministic pipeline, machine-readable validation, and semantic presentation.
+- [evals/](evals/) — the eval suite grading whether an agent reaches the right analytical answer, respects the GIS-method guardrails, and reruns reproducibly, with the `openmapstack-project/v1` contract as the substrate that makes those independently checkable: `python evals/run.py --mode fixture` runs deterministic, no-LLM checks against real generated artifacts (analytical correctness against known geospatial truth, metric CRS, source immutability, schema, overrides, validation integrity, presentation contract, and clean reruns), plus adversarial cases and a pluggable live-agent benchmark (Claude Code, Codex, and any OpenAI-compatible API such as OpenRouter — URL and model via `OPENAI_COMPATIBLE_*` env, API key as a secret).
+- [`openmapstack/`](openmapstack/) — the installable `openmapstack validate/run/inspect` CLI for auditing and executing `openmapstack-project/v1` projects, plus [`openmapstack/checks/`](openmapstack/checks/): the reusable, semantic check library. All but five of its checks are oracle-free, so the same functions that grade the eval suite also grade a user's own project on data this repository has never seen.
+- [`.claude-plugin/`](.claude-plugin/) — Claude Code plugin and marketplace manifests, so the repository can also be installed with `/plugin install`. Validated in CI by [`.github/workflows/plugin.yml`](.github/workflows/plugin.yml).
+
+My local Estonia-specific guidance (Maa- ja Ruumiamet, ETAK, EPSG:3301 / L-EST97) is included for convenience. But all the global sources are incuded for world-wide coverage.
+
+## Install
+
+The recommended way is the [skills CLI](https://github.com/vercel-labs/skills), which works for Claude Code, Cursor, OpenCode, Codex, and 50+ other agents.
+
+### Recommended: skills CLI
+
+Install globally (available in every project):
+
+```bash
+npx skills add jaakla/openmapstack -g
+```
+
+Update later with `npx skills update open-map-stack`. Remove with `npx skills remove open-map-stack`.
+
+### Claude Code plugin (optional)
+
+Claude Code users can install the same repository as a plugin instead. This adds
+versioned installs, `/plugin update`, and project-scoped installs that a team
+picks up from a repository's `.claude/settings.json`:
+
+```bash
+/plugin marketplace add jaakla/openmapstack
+/plugin install open-map-stack@open-map-stack
+```
+
+The repository is its own marketplace, so no separate marketplace repo is
+needed. The plugin wraps the same root `SKILL.md` — nothing is duplicated, and
+the skills-CLI install path above keeps working unchanged.
+
+### Install the project CLI
+
+The skills installer loads the agent instructions; the Python package provides
+the project commands. From a clone of this repository:
+
+```bash
+python3 -m pip install .
+openmapstack --version
+```
+
+For development, the commands can also run directly without installation:
+
+```bash
+python3 -m openmapstack --help
+```
+
+### Manual install (fallback)
+
+If you'd rather not use the CLI, clone directly into your agent's skills directory. For Claude Code:
+
+```bash
+# User-level (every project)
+git clone https://github.com/jaakla/openmapstack.git ~/.claude/skills/open-map-stack
+
+# Project-level (one repo)
+git clone https://github.com/jaakla/openmapstack.git .claude/skills/open-map-stack
+```
+
+### Verify
+
+Start Claude Code and run `/skills open-map-stack` should appear in the list. The expected layout is:
+
+```
+<skills-dir>/open-map-stack/
+├── SKILL.md
+├── references/
+│   ├── analytics.md
+│   ├── data-sources.md
+│   ├── formats-and-crs.md
+│   ├── processing.md
+│   ├── project-spec.md
+│   ├── qgis.md
+│   ├── services-and-scale.md
+│   ├── spatial-sql.md
+│   ├── validation-and-ops.md
+│   └── web-delivery.md
+├── templates/
+│   ├── project.yaml
+│   ├── pipeline.py
+│   ├── presentation.yaml
+│   └── validation.yaml
+├── examples/
+│   └── tartu-development/
+└── .claude-plugin/          # Claude Code plugin + marketplace manifests
+    ├── plugin.json
+    └── marketplace.json
+```
+
+## Use
+
+The skill auto-activates when you ask Claude about geospatial work — terms like GIS, OpenStreetMap, Overture, Sentinel, Landsat, LiDAR, GeoTIFF, shapefile, GeoPackage, raster/vector tiles, isochrones, spatial joins, EPSG codes, and projections will all trigger it. You don't need to invoke it manually, but sometimes hinting "use open-map-stack skills" helps.
+
+Example prompts that engage the skill:
+
+- "Pull all buildings in Tartu from Overture and publish them as a PMTiles layer."
+- "Compute average NDVI for these polygons from Sentinel-2 over the last 12 months."
+- "Reproject this GeoTIFF from EPSG:3301 to EPSG:3857 as a COG."
+- "Set up an OSRM routing server from a Estonia OSM extract."
+- "Build an isochrone API around these points."
+
+If you want to force the skill to load, you can reference it explicitly:
+
+> Use the open-map-stack skill to convert this shapefile to GeoParquet.
+
+## Project CLI
+
+The CLI operates on an `openmapstack-project/v1` manifest. A project directory may
+be supplied in place of its `project.yaml` file.
+
+```bash
+# Audit the complete artifact, including outputs, report, and run record.
+openmapstack validate path/to/project.yaml
+
+# Check the produced artifacts without requiring a golden answer.
+openmapstack verify path/to/project.yaml
+
+# Run the one canonical pipeline, then validate what it produced.
+openmapstack run path/to/project.yaml
+
+# Review sources, versions, overrides, ordered steps, outputs, and latest run.
+openmapstack inspect path/to/project.yaml
+```
+
+Useful automation options:
+
+```bash
+openmapstack validate project.yaml --json --output validation/cli-report.json
+openmapstack validate project.yaml --strict       # warnings also return non-zero
+openmapstack validate project.yaml --preflight    # skip not-yet-generated artifacts
+openmapstack run project.yaml --dry-run
+openmapstack run project.yaml --json
+openmapstack inspect project.yaml --json
+```
+
+### `openmapstack verify` — check the analysis, not just the paperwork
+
+`validate` audits the manifest and its bookkeeping. `verify` runs the check
+library in `openmapstack/checks/` against what the pipeline actually produced:
+geometry read back through DuckDB Spatial, dataset CRS read from the artifact
+rather than the manifest's claim, validation evidence recomputed from the
+geodata it summarises, and QGIS project structure and runtime loading where
+PyQGIS is available.
+
+```bash
+openmapstack verify path/to/project.yaml
+openmapstack verify path/to/project.yaml --rerun     # + rebuild from source and compare
+openmapstack verify path/to/project.yaml --json --output validation/verify-report.json
+openmapstack verify path/to/project.yaml --strict    # warnings and not-testable also return 1
+```
+
+These checks require no repository-owned golden answer, so they work on data
+neither this repository nor the model has seen. They establish bounded
+structural, provenance, artifact, and reproducibility predicates; they do not
+prove every project-specific analytical answer.
+
+`--rerun` is the strongest signal available without a known answer. It rebuilds
+the project in an empty workspace from only the manifest, the declared
+immutable inputs, and the declared dependencies, runs the one canonical
+entrypoint, re-hashes the sources, and compares the outputs semantically. A
+pipeline that cannot reproduce itself, or that mutates its own declared
+immutable inputs, is not trustworthy whatever its numbers say.
+
+The check plan is derived from the manifest rather than configured, so a
+project cannot opt out of a check by omitting it: a declared output is a
+checked output. A check whose dependency is missing reports `not_testable` and
+is counted separately — never a silent pass. A mixture of executed and
+`not_testable` checks has aggregate status `warning`, and every report includes
+`applicable`, `executed`, and `execution_rate` coverage. Install
+`openmapstack[geo]` for the DuckDB-backed geodata checks; PyQGIS comes from a
+system QGIS install.
+
+See [the applicability reference](docs/verify-applicability.md) for the exact
+plan conditions, dependencies, current regression evidence, and deliberate
+exclusions. In particular, browser/dashboard checks are not yet part of the
+automatic `verify` plan.
+
+Project-specific known answers can be declared under
+`validation.expectations[]`. The five allowlisted checks cover row count,
+feature presence/absence, one feature-field value, and field range. New
+expectations start as `attestation.status: unverified`; they produce a warning
+and are not executed. The JSON report supplies the exact
+`expected_expectation_sha256` an independent reviewer must bind, together with
+the current `runs.latest.inputs_hash`. Changing the expected check, arguments,
+inputs, or a retained local evidence file invalidates the attestation and
+returns it to warning status. See
+[the project contract](references/project-spec.md#26-validation).
+
+`validate` checks manifest structure, source retrieval/version/licensing data,
+CRS declarations, processing graph resolution, override provenance and files,
+output existence, validation-report parity/status propagation, override
+application results, and run-record identity/hashes. GIS-specific checks such as
+geometry validity remain the pipeline's responsibility; the CLI verifies that
+each declared check appears exactly once with an explicit result.
+
+Normal validation warnings return exit code 0 so known limitations remain
+representable. Failures return 1; malformed invocation or an unstartable runtime
+returns 2. `--strict` makes warnings return 1.
+
+## What this skill will and won't do
+
+**Will:**
+- Recommend modern, cloud-native formats (GeoParquet, COG, PMTiles) and flag legacy patterns (Shapefile output, MBTiles for new deployments).
+- Push spatial joins to DuckDB / PostGIS instead of Python loops.
+- Discover data via STAC before downloading.
+- Preserve license metadata (OSM ODbL, Overture per-source, Sentinel attribution).
+- Pin dataset versions for reproducibility (Overture releases, STAC item IDs, OSM extract dates).
+- Compile material multi-stage analysis into a reproducible GIS project (`project.yaml` + pipeline + overrides + validation), deriving the final map/dashboard from it.
+
+**Won't:**
+- Trigger on simple location lookups ("what city is this?") or casual map references with no analytical work.
+- Default to proprietary services when an open/self-hosted option fits the scale, quality, privacy, and budget.
+
+## License
+
+Licensed under the [MIT License](LICENSE).
+
+## Contributing
+
+Issues and PRs welcome at [github.com/jaakla/openmapstack](https://github.com/jaakla/openmapstack). When adding a new tool or workflow, place it in the matching reference file and add a one-row entry to the relevant decision matrix in [SKILL.md](SKILL.md).

openmapstack-0.2.0/openmapstack/__init__.py

@@ -0,0 +1,6 @@
+"""Command-line tooling for reproducible OpenMapStack projects."""
+
+from .validation import Check, ValidationResult, validate_project
+
+__all__ = ["Check", "ValidationResult", "validate_project"]
+__version__ = "0.2.0"

openmapstack-0.2.0/openmapstack/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

openmapstack-0.2.0/openmapstack/checks/__init__.py

@@ -0,0 +1,112 @@
+"""Reusable, semantic checks over an `openmapstack-project/v1` artifact.
+
+Every check has the signature:
+
+    def fn(workspace: Path, **args) -> AssertionResult
+
+and inspects real files in `workspace` (a project directory) rather than
+assistant prose. Checks never raise for expected "could not check"
+conditions — they return `not_testable` instead, matching the four-state
+vocabulary (`passed | failed | warning | not_testable`) required of
+`validation/latest-report.json` itself in `references/project-spec.md`
+section 6.
+
+Two callers share this library, deliberately:
+
+- `evals/run.py` grades eval cases with it (`contract_ci`, `mutation_tests`,
+  `agent_benchmark`, `integration_visual`);
+- `openmapstack verify` grades a *user's own* project with it.
+
+That is the point of it living in the shipped package rather than under
+`evals/`. All but a handful of these checks are oracle-free: they hold for
+any correct project on any data, so they transfer to data this repository
+has never seen. The exceptions — the ones that need a known answer — are
+`geodata.row_count(equals=)`, `feature_present`, `feature_absent`,
+`feature_field_equals`, and `field_range`. On user data those are reachable
+only through allowlisted, input-bound `validation.expectations` attestations,
+never from an answer the pipeline computed and certified for itself.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+STATUSES = ("passed", "failed", "warning", "not_testable")
+
+
+@dataclass
+class AssertionResult:
+    status: str  # passed | failed | warning | not_testable
+    detail: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if self.status not in STATUSES:
+            raise ValueError(f"invalid assertion status: {self.status!r}")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"status": self.status, "detail": self.detail, **self.data}
+
+
+def passed(detail: str = "", **data: Any) -> AssertionResult:
+    return AssertionResult("passed", detail, data)
+
+
+def failed(detail: str = "", *, code: str | None = None, **data: Any) -> AssertionResult:
+    """``code`` is a stable, machine-readable failure identifier (e.g.
+    ``feature_present``). Mutation cases can require the *specific* failure
+    they inject, not merely status ``failed``, via ``expect_code`` in
+    ``expected.yaml``."""
+    if code is not None:
+        data["code"] = code
+    return AssertionResult("failed", detail, data)
+
+
+def warning(detail: str = "", *, code: str | None = None, **data: Any) -> AssertionResult:
+    if code is not None:
+        data["code"] = code
+    return AssertionResult("warning", detail, data)
+
+
+def not_testable(detail: str = "", *, code: str | None = None, **data: Any) -> AssertionResult:
+    if code is not None:
+        data["code"] = code
+    return AssertionResult("not_testable", detail, data)
+
+
+def load_project_yaml(workspace: Path, project_dir: str = ".") -> dict[str, Any] | None:
+    path = workspace / project_dir / "project.yaml"
+    if not path.exists():
+        return None
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            value = yaml.safe_load(fh)
+    except (OSError, yaml.YAMLError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def load_json(path: Path) -> dict[str, Any] | None:
+    if not path.exists():
+        return None
+    with path.open("r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+def project_root(workspace: Path, project_dir: str = ".") -> Path:
+    return workspace / project_dir
+
+
+def get_in(data: dict, dotted: str, default: Any = None) -> Any:
+    """Fetch a nested dict value using a dotted path, e.g. 'project.status'."""
+    cur: Any = data
+    for part in dotted.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            return default
+        cur = cur[part]
+    return cur