{"id":51224788,"url":"https://github.com/saagpatel/proof-pr","last_synced_at":"2026-06-28T10:03:10.947Z","repository":{"id":366096281,"uuid":"1275058115","full_name":"saagpatel/proof-pr","owner":"saagpatel","description":"Proof-carrying pull request receipt standard and CLI.","archived":false,"fork":false,"pushed_at":"2026-06-20T09:15:04.000Z","size":64,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T09:15:26.687Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saagpatel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-20T07:39:47.000Z","updated_at":"2026-06-20T09:10:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/saagpatel/proof-pr","commit_stats":null,"previous_names":["saagpatel/proof-pr"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/saagpatel/proof-pr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fproof-pr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fproof-pr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fproof-pr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fproof-pr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saagpatel","download_url":"https://codeload.github.com/saagpatel/proof-pr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saagpatel%2Fproof-pr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34884278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-28T10:03:10.294Z","updated_at":"2026-06-28T10:03:10.936Z","avatar_url":"https://github.com/saagpatel.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# proof-pr\n\n`proof-pr` is a small standard and future CLI for pull requests that carry their\nown proof bundle: risk tier, files touched, verification commands, screenshots,\nhealth checks, security posture, rollback notes, and a machine-readable receipt.\n\nThe v0 target consumer is agent-generated PRs in a solo/operator workflow. The\nformat is intentionally portable enough for open-source maintainers and internal\nteams later, but v0 optimizes for fast human review of agent-created changes.\n\n## Current Contents\n\n- `docs/proof-pr-v1.md` - v0 standard, Markdown block, risk tiers, CLI plan, and\n  GitHub Action follow-up.\n- `docs/example-receipts.md` - example receipt patterns by risk tier and PR\n  shape.\n- `docs/release-checklist.md` - release preflight and verification checklist.\n- `PUBLICATION.md` - public safety posture and publication checks.\n- `schemas/proof-pr.v1.schema.json` - machine-readable receipt schema.\n- `examples/` - compact historical receipts from real PRs.\n- `examples/proof-pr-self-template.config.example.json` - config template for\n  using proof-pr to document its own PRs.\n- `src/proof_pr/` - dependency-free CLI and receipt validator package.\n- `scripts/` - source-checkout compatibility wrappers.\n- `scripts/test_examples_cli.py` - CLI smoke tests over the bundled examples.\n- `examples/proof-pr.config.example.json` - sample command config for a\n  dashboard truth/schema consumer PR.\n- `docs/github-action-validation.md` - GitHub Action validation plan and example.\n- `docs/stable-dogfood-contract.md` - v0.2 candidate contract for consumer\n  adoption, triggers, and enforcement modes.\n- `.github/workflows/proof-pr-receipt.yml` - reusable workflow that validates a\n  receipt, uploads proof artifacts, and writes a job summary.\n- `.github/workflows/proof-pr-validate.yml` - self-check workflow that validates\n  receipts and gates public git metadata for live history/tags.\n- `docs/dogfood-sample-dashboard.md` - first local dogfood run notes.\n\n## Install\n\nFrom a local checkout inside a virtual environment:\n\n```bash\npython3 -m venv .venv\n. .venv/bin/activate\npython3 -m pip install .\nproof-pr validate examples/pr-*.json\nproof-pr render examples/pr-024-sample-dashboard-rollups.json\n```\n\nFrom GitHub (pin to a tag — consumers should not track `main` tip):\n\n```bash\n# Latest release\npython3 -m pip install \"git+https://github.com/saagpatel/proof-pr.git@v0.2.14\"\n\n# Or track main tip (not recommended for production use)\npython3 -m pip install git+https://github.com/saagpatel/proof-pr.git\n```\n\n## Validate\n\n```bash\npython3 scripts/validate_receipts.py examples/pr-*.json\npython3 scripts/proof_pr.py validate examples/pr-*.json\npython3 scripts/proof_pr.py render examples/pr-024-sample-dashboard-rollups.json\npython3 scripts/check_public_git_metadata.py --ref HEAD --ref 'refs/tags/v*'\nproof-pr check-public-git-metadata --ref HEAD --ref 'refs/tags/v*'\n```\n\nThe validator is intentionally lightweight. It checks structure, required\nfields, enum values, and the tier/evidence basics. It does not decide whether a\nclaim is true; the receipt author still owns honest evidence.\n\n## CLI Usage\n\n```bash\npython3 scripts/proof_pr.py init --cwd /path/to/repo --tier T2 --summary \"Short PR summary\" --output proof-pr.json\npython3 scripts/proof_pr.py init --cwd /path/to/repo --tier T3 --example \"Workflow dogfood\" --summary \"Short PR summary\" --output proof-pr.json\npython3 scripts/proof_pr.py collect proof-pr.json --cwd /path/to/repo --config examples/proof-pr.config.example.json --suggest-example\npython3 scripts/proof_pr.py run --receipt proof-pr.json --cwd /path/to/repo --id tests --kind test -- python3 -m pytest -q\npython3 scripts/proof_pr.py run-config proof-pr.json --cwd /path/to/repo --config examples/proof-pr.config.example.json --finalize\npython3 scripts/proof_pr.py finalize proof-pr.json --require-ready\npython3 scripts/proof_pr.py render proof-pr.json\npython3 scripts/proof_pr.py render proof-pr.json --head-sha \u003cpr-head-sha\u003e\npython3 scripts/proof_pr.py render --full-commands proof-pr.json\npython3 scripts/proof_pr.py receipt-hygiene proof-pr.json\npython3 scripts/proof_pr.py receipt-hygiene proof-pr.json --explain\npython3 scripts/proof_pr.py receipt-hygiene proof-pr.json --explain --check public-git-metadata --fix-only\npython3 scripts/proof_pr.py receipt-hygiene proof-pr.json --json\npython3 scripts/proof_pr.py examples\npython3 scripts/proof_pr.py examples --json\npython3 scripts/proof_pr.py examples --json --tier T3\npython3 scripts/test_receipt_hygiene_cli.py\npython3 scripts/test_example_pattern_cli.py\npython3 scripts/proof_pr.py validate proof-pr.json\nproof-pr check-public-git-metadata --ref HEAD --ref 'refs/tags/v*'\nproof-pr check-public-git-metadata --base-ref origin/main --ref HEAD\nproof-pr check-public-git-metadata --base-ref origin/main --ref HEAD --summary-format text\nproof-pr collect-public-git-metadata --receipt proof-pr.json --base-ref origin/main --ref HEAD\n```\n\nThe CLI is local-only in v0. It can draft receipt identity and diff stats, run\nconfigured commands into log artifacts, synthesize the final review decision,\nrender the Markdown block, and validate examples. It does not update PR bodies,\nupload artifacts, or enforce merges yet.\n\nBy default, `render` compacts long command lines so PR bodies stay scannable.\nUse `--full-commands` when a reviewer wants complete commands inline; receipt\nJSON always keeps the full command array.\n\nUse `--head-sha` when rendering a PR body or CI summary for a committed receipt\nwhose `subject.head_sha_status` is `pending_commit`. The JSON can remain honest\nabout its commit-time placeholder while the rendered block anchors to the final\nPR or check-run SHA.\n\n`init` attaches a suggested `producer.example_pattern` from the receipt tier, or\nan explicit one from `--example`. `collect --suggest-example` refreshes that\nmetadata after config changes the risk tier or changed surfaces. `render` shows\nthe selected pattern as authoring guidance; it is not evidence and does not\nclaim that the PR copied the example correctly.\n\n`finalize` is intentionally conservative: failed required proof rejects the\nreceipt, blocked required proof keeps it in revise, skipped/stale/partial\nrequired proof remains partial, and unresolved limitations prevent a ready\ndecision unless `--allow-limitations` is set. The default draft limitation is\ncleared during finalization after evidence has been collected.\n\n`check-public-git-metadata` is a public-release guardrail. It fails when selected\nrefs contain commit or annotated-tag email metadata outside GitHub noreply\npatterns, and it is enforced by this repository's self-check workflow. Use\n`--base-ref origin/main --ref HEAD` to check only newly introduced commits in\nolder repos whose existing public history is not fully noreply-clean.\nUse `--summary-format text` or `--summary-format json` when the check output is\nbeing copied into CI summaries or receipts; the summary records whether the\nscope was `full` or `introduced`, the checked refs, the base ref, and tag scope.\n\nUse `collect-public-git-metadata` when a receipt should carry that result as a\nnormal `security` evidence item. The command upserts `public-git-metadata`\nwithout changing the receipt schema, so public metadata posture remains review\nevidence rather than supply-chain provenance.\n\nUse `receipt-hygiene` as a read-only pre-review nudge. It inspects an existing\nreceipt and suggests missing standard evidence for the risk tier, starting with\npublic git metadata, secrets posture, workflow permission posture, and rollback\nspecificity. Add `--explain` to include copyable commands and compact receipt\npatch examples for missing evidence. Add `--check \u003cid\u003e` to focus on one finding\nand `--fix-only` to print just the remediation command/patch block. Add\n`--strict` when a repo wants hygiene warnings to fail CI.\nThe reusable workflow writes these suggestions to the job summary by default in\nadvisory mode, followed by a focused public git metadata fix block when that\nfinding exists. If no focused fix is needed, `--fix-only` prints a clean\nno-action-needed note and exits successfully.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaagpatel%2Fproof-pr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaagpatel%2Fproof-pr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaagpatel%2Fproof-pr/lists"}