diff --git a/README.md b/README.md index 6497021..b51da03 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,9 @@ For a repository-level reviewer overview, use the SBOM tool from the supporting diagnostics projects and points reviewers to the right evidence path. +For the shortest boundary check before adding or reviewing new material, use +the [repository scope map](docs/repo-scope-map.md). + ## Supporting Diagnostics Projects These projects are internal supporting material for reviewer depth. They are @@ -160,6 +163,8 @@ they do not prove the same thing. [`docs/pypi-production-publishing-decision.md`](tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md) - Reviewer route contract: [`scripts/validate-reviewer-routes.py`](scripts/validate-reviewer-routes.py) +- Repository scope map: + [`docs/repo-scope-map.md`](docs/repo-scope-map.md) The TestPyPI Trusted Publishing dry-run has been validated. Production PyPI publishing is intentionally deferred. diff --git a/docs/repo-scope-map.md b/docs/repo-scope-map.md new file mode 100644 index 0000000..65fe390 --- /dev/null +++ b/docs/repo-scope-map.md @@ -0,0 +1,21 @@ +# Repository scope map + +Use this map as the shortest boundary check before adding new reviewer-facing +material to this repository. + +## Flagship + +- `sbom-diff-and-risk` + +## Supporting diagnostics + +- `precipitation-anomaly-diagnostics` +- `precipitation-anomaly-diagnostics-lab` +- `python-weather-diagnostics-toolkit` + +## What this repo does not claim + +- not a climate portfolio +- not a vulnerability scanner +- not a CVE resolver +- not a production PyPI release claim diff --git a/docs/reviewer-brief.md b/docs/reviewer-brief.md index f6c0931..78dcdda 100644 --- a/docs/reviewer-brief.md +++ b/docs/reviewer-brief.md @@ -24,7 +24,7 @@ workflows, but they are not part of the `sbom-diff-and-risk` release surface. | Review question | Start here | Stop when | | --- | --- | --- | -| What is the repository shape? | This brief and the root [README](../README.md). | You can distinguish the flagship SBOM tool from the supporting diagnostics projects. | +| What is the repository shape? | This brief, the root [README](../README.md), and the [repository scope map](repo-scope-map.md). | You can distinguish the flagship SBOM tool from the supporting diagnostics projects. | | What should I review for the SBOM tool? | The SBOM [reviewer path](../tools/sbom-diff-and-risk/docs/reviewer-path.md). | You have chosen the right 30-second, 5-minute, 15-minute, release, or deep-review route. | | Can the SBOM examples be reproduced? | The SBOM [example artifact regeneration guide](../tools/sbom-diff-and-risk/docs/example-artifact-regeneration.md). | `python scripts/regenerate-example-artifacts.py --check` passes. | | Can the released SBOM artifacts be verified? | The SBOM [verification guide](../tools/sbom-diff-and-risk/docs/verification.md). | You know whether to use checksums, release verification, or workflow artifact attestations. | @@ -50,6 +50,8 @@ workflows, but they are not part of the `sbom-diff-and-risk` release surface. - Release evidence: `sbom-diff-and-risk` release notes, GitHub release verification docs, TestPyPI Trusted Publishing dry-run notes, and intentionally deferred production PyPI decision docs. +- Scope map: `docs/repo-scope-map.md` keeps the flagship/supporting split and + repository non-claims explicit. - Non-goals: vulnerability scanning, CVE resolution, exploitability scoring, package safety verdicts, hidden enrichment, or production PyPI claims. diff --git a/scripts/validate-reviewer-routes.py b/scripts/validate-reviewer-routes.py index 34ed49f..d6c0610 100644 --- a/scripts/validate-reviewer-routes.py +++ b/scripts/validate-reviewer-routes.py @@ -13,6 +13,7 @@ DOCS_TO_VALIDATE = ( Path("README.md"), Path("docs/reviewer-brief.md"), + Path("docs/repo-scope-map.md"), Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"), Path("projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md"), Path("projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md"), @@ -42,6 +43,7 @@ REQUIRED_LINK_TARGETS = { Path("README.md"): { "docs/reviewer-brief.md", + "docs/repo-scope-map.md", "tools/sbom-diff-and-risk/docs/reviewer-path.md", "tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md", "projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md", @@ -50,12 +52,14 @@ }, Path("docs/reviewer-brief.md"): { "README.md", + "docs/repo-scope-map.md", "tools/sbom-diff-and-risk/docs/reviewer-path.md", "tools/sbom-diff-and-risk/docs/example-artifact-regeneration.md", "projects/precipitation-anomaly-diagnostics/docs/reviewer-path.md", "projects/precipitation-anomaly-diagnostics-lab/docs/reviewer-path.md", "projects/python-weather-diagnostics-toolkit/docs/reviewer-path.md", }, + Path("docs/repo-scope-map.md"): set(), Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"): { ".github/workflows/reviewer-route-contract-ci.yml", "scripts/validate-reviewer-routes.py", @@ -128,6 +132,19 @@ "supporting diagnostics projects", "production PyPI publishing remains intentionally deferred", ), + Path("docs/repo-scope-map.md"): ( + "Flagship", + "sbom-diff-and-risk", + "Supporting diagnostics", + "precipitation-anomaly-diagnostics", + "precipitation-anomaly-diagnostics-lab", + "python-weather-diagnostics-toolkit", + "What this repo does not claim", + "not a climate portfolio", + "not a vulnerability scanner", + "not a CVE resolver", + "not a production PyPI release claim", + ), Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"): ( "Artifact evidence map", "Reviewer route contract",