From a7c6afa00a8bc694fab0a6c21ec0fd02bba19f86 Mon Sep 17 00:00:00 2001
From: stacknil <stacknil@proton.me>
Date: Sun, 7 Jun 2026 02:20:39 +0800
Subject: [PATCH] docs(sbom): expose reviewer route contract

---
 scripts/validate-reviewer-routes.py           |  3 ++
 .../sbom-diff-and-risk/docs/reviewer-path.md  | 28 +++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/scripts/validate-reviewer-routes.py b/scripts/validate-reviewer-routes.py
index def2bb2..ed019e0 100644
--- a/scripts/validate-reviewer-routes.py
+++ b/scripts/validate-reviewer-routes.py
@@ -35,6 +35,7 @@
         "projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md",
     },
     Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"): {
+        "scripts/validate-reviewer-routes.py",
         "tools/sbom-diff-and-risk/docs/reviewer-brief.md",
         "tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md",
         "tools/sbom-diff-and-risk/docs/verification.md",
@@ -106,6 +107,8 @@
     ),
     Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"): (
         "Artifact evidence map",
+        "Reviewer route contract",
+        "python scripts/validate-reviewer-routes.py",
         "No network",
         "not current PyPI package truth",
         "not current repository reputation",
diff --git a/tools/sbom-diff-and-risk/docs/reviewer-path.md b/tools/sbom-diff-and-risk/docs/reviewer-path.md
index c229c61..d566804 100644
--- a/tools/sbom-diff-and-risk/docs/reviewer-path.md
+++ b/tools/sbom-diff-and-risk/docs/reviewer-path.md
@@ -12,6 +12,7 @@ where to find it, and what it does not prove.
 | What artifacts does it produce? | [5-minute artifact review](#5-minute-artifact-review) | You can point to JSON, summary, policy, Markdown, and SARIF examples. |
 | Can the examples be reproduced locally? | [15-minute reproduction check](#15-minute-reproduction-check) | `regenerate-example-artifacts.py --check` passes without enrichment. |
 | Can the released tool artifacts be verified? | [Release evidence](#release-evidence) | You can choose the correct GitHub release, checksum, or attestation path. |
+| Are the reviewer routes still valid? | [Reviewer route contract](#reviewer-route-contract) | `python scripts/validate-reviewer-routes.py` passes from the repository root. |
 | Is this enough for a full review? | [Deep review](#deep-review) | You have followed the reproducible checklist in the evidence pack. |
 
 ## 30-second orientation
@@ -122,6 +123,33 @@ For the exact regeneration scope, read
 Stop here if you need reproducible local evidence that the examples still match
 the code.
 
+## Reviewer route contract
+
+From the repository root, run:
+
+```powershell
+python scripts/validate-reviewer-routes.py
+```
+
+This checks that the repository reviewer route still has the expected local
+links, markdown anchors, reviewer-path documents, supporting-project boundary
+files, and required non-claim phrases.
+
+Use this when you change reviewer-facing docs, examples, or supporting project
+entry points. The contract lives in
+[`scripts/validate-reviewer-routes.py`](../../../scripts/validate-reviewer-routes.py)
+and is also enforced by the repository reviewer-route CI workflow.
+
+Expected result:
+
+- the SBOM reviewer path still links to the required evidence surfaces
+- local markdown anchors resolve
+- supporting project reviewer paths and boundary files still exist
+- required non-claims remain present in reviewer-facing docs
+
+Stop here if your review question is whether the reviewer route itself is
+still coherent after documentation changes.
+
 ## Release evidence
 
 Use this section only when the review question is about the released