Skip to content

[codex] Add policy decision explainability guide#45

Merged
stacknil merged 1 commit into
mainfrom
codex/add-policy-decision-explainability-guide
May 9, 2026
Merged

[codex] Add policy decision explainability guide#45
stacknil merged 1 commit into
mainfrom
codex/add-policy-decision-explainability-guide

Conversation

@stacknil
Copy link
Copy Markdown
Owner

@stacknil stacknil commented May 9, 2026

Brief Design Summary

This PR adds a reviewer-facing policy decision explainability guide for the JSON policy metadata added in v0.8 work.

The guide explains where decision_reason, policy_rule, severity_source, matched_threshold, and observed_value appear, how reviewers and CI consumers can interpret them, and the non-claims around dependency safety, CVEs, and network behavior.

This PR also fixes stale reviewer-facing v0.6.0 release references now that v0.7.0 is the current GitHub Release, updates the consumer GitHub Actions example to install the v0.7.0 wheel, and keeps the production PyPI decision gate explicitly deferred without adding any publishing path.

No runtime behavior, CLI flags, JSON schema, SARIF/Markdown output behavior, workflows, package metadata, release tags, or PyPI/TestPyPI publishing changed.

Files Changed

  • tools/sbom-diff-and-risk/docs/policy-decision-explainability.md
  • tools/sbom-diff-and-risk/README.md
  • tools/sbom-diff-and-risk/docs/report-schema.md
  • tools/sbom-diff-and-risk/docs/policy-schema.md
  • 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/github-actions-consumer-example.md
  • tools/sbom-diff-and-risk/examples/github-actions-consumer.yml
  • tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md

Validation

  • git diff --check passed.
  • Confirmed relative Markdown links resolve.
  • Broad Unicode Cf/Cc scan found no non-tab/newline control or format characters.
  • Confirmed stale v0.6.0/v0.5.x current-release references are removed from touched reviewer-facing docs and examples.
  • Confirmed package version remains 0.7.0.
  • Confirmed .github/workflows was unchanged and no production PyPI workflow exists.
  • No Python tests run because this is docs/example-only.

Out of Scope

  • No runtime behavior changes
  • No CLI flag changes
  • No JSON schema changes
  • No SARIF behavior changes
  • No repository workflow changes
  • No package version bump
  • No tag or GitHub Release
  • No PyPI/TestPyPI publishing
  • No production PyPI workflow

@stacknil stacknil merged commit 13fa0b6 into main May 9, 2026
5 checks passed
@stacknil stacknil deleted the codex/add-policy-decision-explainability-guide branch May 9, 2026 05:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant