release/0.5.1: Docs Coherence Plan rollout

.github/workflows/ci.yml

@@ -69,6 +69,13 @@ jobs:
       - name: Check error documentation
         run: uv run python scripts/check_error_docs.py
 
+      # Phase 7 of the Docs Coherence Plan — guard the "default UNTP
+      # version" claim in user-facing docs against drifting away from
+      # DEFAULT_VERSIONS[SchemaFamily.UNTP]. Same script runs in
+      # .pre-commit-config.yaml.
+      - name: Check docs default-version coherence
+        run: uv run python tools/check_doc_default_version.py
+
       # License scanning - ensure all dependencies have compatible licenses
       - name: Check dependency licenses
         run: |

.github/workflows/docs.yml

@@ -21,5 +21,8 @@ jobs:
       - name: Install dependencies
         run: uv sync --group docs
 
-      - name: Build and deploy docs
+      - name: Build docs (strict)
+        run: uv run mkdocs build --strict
+
+      - name: Deploy docs
         run: uv run mkdocs gh-deploy --force

.github/workflows/release.yml

@@ -138,6 +138,25 @@ jobs:
       - name: Validate real fixture
         run: dppvalidator validate tests/fixtures/valid/minimal_dpp.json
 
+      # Full functional smoke against the TestPyPI-installed wheel.
+      # ``scripts/smoke_test.py`` ships ~22 sections (~109 assertions)
+      # across CLI, Python API, compat shim, exporter, plugins,
+      # manifest integrity, doctor, content-negotiation, and the
+      # Phase 9 (0.5.0) contracts (six-code exit surface, D1
+      # statusListIndex int coercion, D2 PartyRoleEnum gradient +
+      # PRT001 advisory, deprecation warnings, UNTP↔CIRPASS round-
+      # trip). DPP_BIN/PY_BIN point the script at the just-installed
+      # binary instead of a dev .venv. This is the deeper second-
+      # pass gate that runs after the lightweight import + CLI
+      # smoke checks above.
+      - name: Run full smoke-test suite against TestPyPI install
+        run: |
+          export DPP_BIN="$(which dppvalidator)"
+          export PY_BIN="$(which python)"
+          echo "DPP_BIN=$DPP_BIN"
+          echo "PY_BIN=$PY_BIN"
+          python scripts/smoke_test.py
+
   publish-pypi:
     name: Publish to PyPI
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -93,3 +93,14 @@ repos:
         language: system
         pass_filenames: false
         stages: [ pre-push ]
+      # Phase 7 of the Docs Coherence Plan — guard against the
+      # "default UNTP version" claim drifting away from the registry.
+      # Runs against user-facing docs (README, AGENTS.md, mkdocs pages,
+      # llms*.txt). See tools/check_doc_default_version.py for the
+      # exempt list and detection algorithm.
+      - id: check-doc-default-version
+        name: check-doc-default-version
+        entry: uv run python tools/check_doc_default_version.py
+        language: system
+        pass_filenames: false
+        files: ^(README\.md|AGENTS\.md|CLAUDE\.md|docs/(?!plans/|adr/0006).*\.(md|txt)|src/dppvalidator/schemas/registry\.py)$

AGENTS.md

@@ -13,6 +13,9 @@
 - **ty** (Astral) for type checking
 - **pytest** for testing
 - **GitHub Actions** for CI/CD
+- Optional extras: `[cli]` (rich CLI formatting), `[rdf]` (SHACL via
+  `rdflib` + `pyshacl`), `[all]` (both). SHACL is opt-in to keep the
+  default install footprint minimal.
 
 ## Directory Structure
 
@@ -21,12 +24,14 @@ src/dppvalidator/      # Main package
 ├── models/            # Pydantic models for DPP entities
 │   ├── v0_6/          # UNTP 0.6.x models (ProductPassport envelope)
 │   ├── v0_7/          # UNTP 0.7.0 models (Product as credentialSubject)
+│   ├── cirpass/v1_3/  # CIRPASS DPP reference structure 1.3.0
 │   └── …              # Top-level shims re-export v0.6 for back-compat
-├── validators/        # Validation logic (per-version dispatch)
-│   ├── rules/v0_6/    # Semantic rules — v0.6
-│   ├── rules/v0_7/    # Semantic rules — v0.7
+├── validators/        # Validation logic (per-version + per-family dispatch)
+│   ├── rules/v0_6/        # Semantic rules — UNTP 0.6
+│   ├── rules/v0_7/        # Semantic rules — UNTP 0.7
+│   ├── rules/cirpass_v1_3/ # Quality rules — CIRPASS 1.3 (CQ*)
 │   └── …
-├── compat/            # Cross-version compat shims
+├── compat/            # Cross-version + cross-family shims (UPG*, MAP*)
 ├── verifier/          # Signature and credential verification
 ├── exporters/         # JSON-LD and EU DPP export formats
 ├── schemas/           # JSON Schema loading + version registry
@@ -46,14 +51,16 @@ tests/                 # Test suite
     └── upstream/     # SHA-pinned upstream samples
 ```
 
-## UNTP version handling
+## Schema family + version handling
 
-dppvalidator supports **UNTP DPP 0.6.x and 0.7.0** in the same release.
+dppvalidator supports **UNTP DPP 0.6.x and 0.7.0** and the **CIRPASS
+DPP reference structure 1.3.0** (`SchemaFamily.CIRPASS`) in the same
+release.
 
 - Version detection: `validators/detection.py` is the only place that
   decides the version of a payload.
 - Default version: `schemas.registry.DEFAULT_SCHEMA_VERSION` (currently
-  `0.6.1`); call `dppvalidator.compat.active_version()` from feature
+  `0.7.0`); call `dppvalidator.compat.active_version()` from feature
   code instead of hardcoding the literal.
 - Adding a new version: see
   [`.claude/rules/untp-versioning.md`](.claude/rules/untp-versioning.md)

CHANGELOG.md

@@ -5,14 +5,100 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.1] - 2026-05-10
+
+Documentation-only patch. No runtime behaviour changed; no API,
+schema, validator, or CLI surface was touched. The release executes
+the [Docs Coherence Plan](https://github.com/artiso-ai/dppvalidator/blob/main/docs/plans/DOCS_COHERENCE_PLAN.md)
+end-to-end: every public source now agrees on the active default
+version, the canonical seven-layer taxonomy, and the error-code
+prefix table.
+
+### Added
+
+- [ADR 0006](https://github.com/artiso-ai/dppvalidator/blob/main/docs/adr/0006-validation-layer-taxonomy.md)
+  pinning the canonical "seven layers + Layer 0 detection" taxonomy
+  and the non-layer error-code prefix list (`PRS`, `DET`, `VER`,
+  `UPG`, `MAP`, `PRT`).
+- New error-page coverage for codes that ship in 0.5.0 but had no
+  reference page: `DET001` (family mismatch), `MAP001`–`MAP005`
+  (cross-family migration warnings).
+- `tools/check_doc_default_version.py` — CI guard that walks the
+  user-facing docs surface and asserts every "default UNTP version"
+  claim matches `DEFAULT_VERSIONS[SchemaFamily.UNTP]`. Wired into
+  pre-commit and `ci.yml` lint.
+- `tests/unit/test_doc_error_code_coverage.py` — asserts every error
+  code emitted by `src/` has a `docs/errors/<CODE>.md` page and an
+  `mkdocs.yml` nav entry, and the prefix allow-list agrees with
+  ADR 0006.
+- `mkdocs build --strict` is now a hard gate in
+  [`.github/workflows/docs.yml`](.github/workflows/docs.yml).
+
+### Changed
+
+- Default UNTP version flipped `0.6.1` → `0.7.0` across every
+  user-facing surface (README, mkdocs index/concepts/guides/FAQ,
+  AGENTS.md, both `llms*.txt`). The runtime default already lived at
+  `0.7.0` in [`schemas/registry.py`](https://github.com/artiso-ai/dppvalidator/blob/main/src/dppvalidator/schemas/registry.py)
+  since 0.5.0; the docs caught up.
+- Error-code prefix `MOD` → `MDL` in every doc that referenced it
+  (the source code has emitted `MDL001`–`MDL099` since 0.5.0; only
+  the docs lagged).
+- The README + concept-page mermaid diagrams now render the full
+  seven-layer flow (Detection → Schema → Model → JSON-LD →
+  Semantic → Vocabulary → Plugin → Signature) instead of the older
+  five-layer dispatch path.
+- `SIG001`–`SIG099` is documented as **reserved**: the verifier
+  currently surfaces untyped error strings via
+  `VerificationResult.errors`; the `SIG` prefix is held for the
+  future structured-code migration.
+- README hero, `mkdocs.yml site_description`, and both `llms*.txt`
+  framings now name **CIRPASS DPP reference structure 1.3.0**
+  alongside UNTP 0.6.x / 0.7.0; previous wording mentioned only
+  UNTP.
+- `docs/changelog.md` is now a one-line `pymdownx.snippets` include
+  of the root `CHANGELOG.md` — single source of truth, both
+  surfaces stay in sync at build time.
+- Root `llms.txt` and `llms-ctx.txt` are symlinks into `docs/`; the
+  two copies can no longer drift.
+- FAQ error-prefix table extended from 7 rows to 12 (adds `DET`,
+  `VER`, `UPG`, `MAP`, `PRT`; clarifies `SIG` reservation).
+- `AGENTS.md` directory tree adds `models/cirpass/v1_3/` and
+  `validators/rules/cirpass_v1_3/`; "UNTP version handling" section
+  renamed to "Schema family + version handling" and now names
+  `SchemaFamily.CIRPASS`; `[rdf]` / `[cli]` / `[all]` extras called
+  out.
+
+### Removed
+
+- Scratch artefacts that had drifted into `docs/`: `docs/dpp/*.json`
+  (raw schema fixtures duplicated under `tests/fixtures/`),
+  `docs/uv/uv.md` and `docs/windsurf/cascade-reference.md`
+  (third-party docs copies),
+  `docs/dpp_validator_description.md` (early marketing draft).
+- Internal planning documents moved out of the published docs site
+  into `docs/plans/` (already in `exclude_docs:`):
+  `IMPLEMENTATION_PLAN.md`, `IMPROVEMENT_ROADMAP.md`,
+  `REFACTORING_PLAN.md`, `STRATEGIC_ROADMAP.md`,
+  `UNTTP_PLUGIN_PLAN.md`, `VC_WALLET_ROADMAP.md`. Their content is
+  unchanged; the relocation closes the mkdocs `--strict` orphan
+  gap.
+
+### Maintenance
+
+- All cross-document references in this `CHANGELOG.md` rewritten as
+  GitHub-absolute URLs so the snippet-included copy at
+  [`docs/changelog.md`](https://artiso-ai.github.io/dppvalidator/changelog/)
+  resolves cleanly under `mkdocs build --strict`.
+
 ## [0.5.0] - 2026-05-09 (Preview)
 
 This release adds **end-to-end CIRPASS-2 reference structure v1.3.0**
 support alongside UNTP DPP 0.6.x / 0.7.0 and ships the cross-family
 forward / reverse shims, the EUDPP v1.9.x ontology rebase, two pilot
 profiles (Textile v2 built-in, Tyres GPL plugin), and a six-code CLI
 exit surface. The migration plan is at
-[`docs/plans/CIRPASS_2_MIGRATION.md`](docs/plans/CIRPASS_2_MIGRATION.md);
+[`docs/plans/CIRPASS_2_MIGRATION.md`](https://github.com/artiso-ai/dppvalidator/blob/main/docs/plans/CIRPASS_2_MIGRATION.md);
 each phase has its own implementation log there.
 
 **Status: Preview / unstable.** The Pydantic v0.7 model layer has
@@ -39,7 +125,7 @@ correctness check.
   `src/dppvalidator/vocabularies/data/ontologies/`; 6 fresh
   manifest entries, every IRI rebased onto the canonical
   `https://w3id.org/eudpp#` fragment namespace per
-  [ADR 0002](docs/adr/0002-canonical-eudpp-iri.md).
+  [ADR 0002](https://github.com/artiso-ai/dppvalidator/blob/main/docs/adr/0002-canonical-eudpp-iri.md).
 - **CIRPASS reference Pydantic models** at
   `dppvalidator.models.cirpass.v1_3.*` (20 classes — Actor,
   ActorRoleAssignment, ConnectorRelation, Material, LifeCycleAssessment,
@@ -140,7 +226,7 @@ correctness check.
 
 The Pydantic v0.7 model layer has documented drift from the upstream
 JSON Schema, catalogued as drift items D3–D27 in
-[Phase 8.9 of the migration plan](docs/plans/CIRPASS_2_MIGRATION.md).
+[Phase 8.9 of the migration plan](https://github.com/artiso-ai/dppvalidator/blob/main/docs/plans/CIRPASS_2_MIGRATION.md).
 Schema validation (Layer 1) catches every contract violation; the
 drift is confined to the Python API ergonomics layer and will be
 fully reconciled in 0.6.0 (Phase 10 tasks 10.9–10.15). Specifically:
@@ -198,7 +284,7 @@ fully reconciled in 0.6.0 (Phase 10 tasks 10.9–10.15). Specifically:
 This release adds first-class support for **UNTP DPP 0.7.0** alongside
 the existing 0.6.x. Both wire formats coexist and are auto-detected
 from `@context` / `$schema` URLs. The plan is captured in
-[`docs/plans/UNTP_0.7.0_MIGRATION.md`](docs/plans/UNTP_0.7.0_MIGRATION.md);
+[`docs/plans/UNTP_0.7.0_MIGRATION.md`](https://github.com/artiso-ai/dppvalidator/blob/main/docs/plans/UNTP_0.7.0_MIGRATION.md);
 each phase has its own implementation log there.
 
 ### Added
@@ -249,8 +335,8 @@ each phase has its own implementation log there.
   `MANIFEST.json` now carry both an SHA-pinned `source_url` and a
   human-friendly `production_url` (e.g. `untp.unece.org`).
 - **Documentation**. New
-  [`docs/concepts/untp-versions.md`](docs/concepts/untp-versions.md)
-  and [`docs/guides/migration-0-6-to-0-7.md`](docs/guides/migration-0-6-to-0-7.md);
+  [`docs/concepts/untp-versions.md`](https://github.com/artiso-ai/dppvalidator/blob/main/docs/concepts/untp-versions.md)
+  and [`docs/guides/migration-0-6-to-0-7.md`](https://github.com/artiso-ai/dppvalidator/blob/main/docs/guides/migration-0-6-to-0-7.md);
   refreshed schema, JSON-LD, validation, CLI, FAQ, and index pages
   with both v0.6 and v0.7 examples.