[codex] Sync policy JSON reviewer docs

Author: stacknil

tools/sbom-diff-and-risk/docs/reviewer-brief.md

@@ -15,7 +15,7 @@ Dependency review often needs evidence that is stable enough for code review, CI
 | Area | What exists |
 | --- | --- |
 | Deterministic local analysis | Compares CycloneDX, SPDX, `requirements.txt`, and conservative `pyproject.toml` inputs without hidden network access by default. |
-| Reviewer output | Produces JSON and Markdown reports for dependency diffs, heuristic risk buckets, and policy outcomes. |
+| Reviewer output | Produces JSON and Markdown reports for dependency diffs, heuristic risk buckets, and policy outcomes. It can also write compact `summary.json` and policy-only `policy.json` sidecars for CI consumers. |
 | Security tooling output | Emits a conservative SARIF subset for selected high-signal findings and explicit policy violations. |
 | Provenance-aware reporting | Optionally records PyPI provenance and integrity evidence when `--enrich-pypi` is enabled. |
 | Scorecard signals | Optionally records OpenSSF Scorecard evidence when `--enrich-scorecard` is enabled and a repository mapping is explicit enough. |
@@ -29,6 +29,7 @@ Dependency review often needs evidence that is stable enough for code review, CI
 | How can a reviewer reproduce the core evidence? | [reviewer-evidence-pack.md](reviewer-evidence-pack.md) for demo, release, TestPyPI, and SARIF verification paths. |
 | What is the stable JSON shape? | [report-schema.md](report-schema.md) documents the machine-readable report structure and `summary` contract. |
 | How are policy findings explained? | [policy-decision-explainability.md](policy-decision-explainability.md) documents the policy decision metadata in JSON reports. |
+| Can CI consume compact policy decisions? | [policy-decision-ci-cookbook.md](policy-decision-ci-cookbook.md), [examples/sample-policy.json](../examples/sample-policy.json), and [examples/github-actions-policy-consumer.yml](../examples/github-actions-policy-consumer.yml) show the policy sidecar path. |
 | Are default runs offline? | CLI docs, tests for no-enrichment behavior, and explicit enrichment flags. |
 | Can code scanning consume the output? | `docs/github-code-scanning.md` and `examples/sample-sarif.sarif`. |
 | Can the tool's own artifacts be verified? | `docs/self-provenance.md` for workflow artifact attestations. |

tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md

@@ -37,8 +37,8 @@ sbom-diff-risk compare `
   --out-md outputs/report.md
 ```
 
-Expected output files:
-
+Expected output files:
+
 - `outputs/report.json`
 - `outputs/summary.json`
 - `outputs/report.md`
@@ -55,8 +55,33 @@ No differences means the sample path reproduced the committed example output.
 
 `examples/sample-summary.json` is the summary-only artifact for the same run
 and is expected to match `examples/sample-report.json`'s `summary` object.
-
-Generate the strict-policy SARIF sample:
+
+Generate the strict-policy JSON sidecar:
+
+```powershell
+sbom-diff-risk compare `
+  --before examples/cdx_before.json `
+  --after examples/cdx_after.json `
+  --policy examples/policy-strict.yml `
+  --out-json outputs/policy-report.json `
+  --policy-json outputs/policy.json
+```
+
+The strict policy example returns exit code `1` because it intentionally
+produces blocking local policy findings. The JSON artifacts are still written.
+
+Compare the sidecar output against the checked-in sample:
+
+```powershell
+Compare-Object (Get-Content examples/sample-policy.json) (Get-Content outputs/policy.json)
+```
+
+`examples/sample-policy.json` is expected to match the policy-related sections
+from `outputs/policy-report.json`, including `summary.policy`, policy finding
+lists, and `rule_catalog`. It intentionally omits full report `components` and
+`risks`.
+
+Generate the strict-policy SARIF sample:
 
 ```powershell
 sbom-diff-risk compare `
@@ -86,6 +111,9 @@ and suppressions.
 For CI job-summary examples that consume policy decision metadata, see
 [policy-decision-ci-cookbook.md](policy-decision-ci-cookbook.md).
 
+For a copyable GitHub Actions example that captures `outputs/policy.json`, see
+[../examples/github-actions-policy-consumer.yml](../examples/github-actions-policy-consumer.yml).
+
 For CI dashboard, job-summary, and local-threshold examples that consume
 `outputs/summary.json`, see
 [summary-json-ci-cookbook.md](summary-json-ci-cookbook.md).