From 6a2834e6c9d168098dcc725cfc9a0ea9086409cd Mon Sep 17 00:00:00 2001 From: Joseph Magly <1159087+jmagly@users.noreply.github.com> Date: Wed, 15 Jul 2026 18:11:02 -0400 Subject: [PATCH] docs: add PR delivery procedure --- CONTRIBUTING.md | 12 +++ README.md | 1 + docs/PULL_REQUEST_DELIVERY.md | 141 ++++++++++++++++++++++++++++++++++ 3 files changed, 154 insertions(+) create mode 100644 docs/PULL_REQUEST_DELIVERY.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 159e409..422bb07 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,6 +56,18 @@ npm run arsenal:smoke npm run field:drill ``` +Follow the full [Pull Request Delivery Guide](docs/PULL_REQUEST_DELIVERY.md) +before requesting review. In particular, run: + +```bash +git diff --name-status upstream/main...HEAD +``` + +The PR must stay scoped to its title. Do not include stale-base deletions, +unrelated provider/config churn, benchmark fixture removals, provenance doc +removals, or safety-test removals. If the branch has drifted, recreate it from +current `main` and reapply only the intended change. + ## Style - Prefer clear adapters and evidence contracts over clever hidden behavior. diff --git a/README.md b/README.md index 100acde..27b90b9 100755 --- a/README.md +++ b/README.md @@ -172,6 +172,7 @@ Deeper reading: [WALL_FORENSICS](docs/WALL_FORENSICS.md) (per-challenge misses), | [TEAM_PREVIEW](docs/TEAM_PREVIEW.md) | first-run path and review script | | [INSTALL_MATRIX](docs/INSTALL_MATRIX.md) | macOS / Linux readiness table | | [ARSENAL_ACTIVATION_PLAN](docs/ARSENAL_ACTIVATION_PLAN.md) | optional external-tool setup | +| [PULL_REQUEST_DELIVERY](docs/PULL_REQUEST_DELIVERY.md) | contributor and maintainer checklist for scoped, reviewable PRs | | [CYBENCH](docs/CYBENCH.md) · [WALL_FORENSICS](docs/WALL_FORENSICS.md) · [INTEGRITY_LEDGER](docs/INTEGRITY_LEDGER.md) · [COGNITIVE_ARCHITECTURE](docs/COGNITIVE_ARCHITECTURE.md) | benchmark methodology | | [RELEASE_CHECKLIST](docs/RELEASE_CHECKLIST.md) | the gates a release must pass | diff --git a/docs/PULL_REQUEST_DELIVERY.md b/docs/PULL_REQUEST_DELIVERY.md new file mode 100644 index 0000000..ed3696d --- /dev/null +++ b/docs/PULL_REQUEST_DELIVERY.md @@ -0,0 +1,141 @@ +# Pull Request Delivery Guide + +Use this checklist before opening or updating a pull request. It is written for +both human contributors and coding agents. + +## Contributor Checklist + +1. Start from current `main`. + + ```bash + git fetch upstream + git rebase upstream/main + ``` + + If the branch has drifted heavily, create a fresh branch from `main` and + cherry-pick only the commits that belong to the PR. + +2. Keep the diff scoped to the PR title. + + ```bash + git diff --name-status upstream/main...HEAD + git diff --stat upstream/main...HEAD + ``` + + The changed file list should be easy to explain from the PR title. Do not + ship stale-base churn, generated artifacts, formatter-only rewrites, or + unrelated deletions. + +3. Stop before pushing if the diff removes protected project evidence. + + These paths should not disappear unless the PR is explicitly about replacing + them and the PR body explains the replacement: + + - benchmark corpora under `bench/` + - benchmark scripts under `scripts/*bench*` + - claim/provenance docs such as `docs/VERIFIED_PROVENANCE.md` + - redaction, provider, local-agent, and adapter safety tests + - provider configuration, environment templates, and API-key plumbing + +4. Run the smallest meaningful verification set. + + For most code changes: + + ```bash + npm run typecheck + npm test + npm run doctor + ``` + + For docs-only changes, note why code tests were skipped. For UI-only + `docs/index.html` changes, extract or otherwise parse-check the page scripts. + For benchmark or headline-claim changes, also run: + + ```bash + npm run verify-claims + ``` + +5. Add a contribution receipt when the change affects behavior, claims, target + scope, agent execution, evidence, reports, or safety gates. + + Use the template below. The receipt can live in the PR body unless the + change introduces durable benchmark artifacts. + +6. Write the PR body for review, not just for announcement. + + Include: + + - what changed + - why it changed + - exact commands run and pass/fail/skipped result + - any skipped verification and why + - screenshots or artifacts for UI/reporting changes + - residual risk or follow-up work + +## Coding-Agent Instructions + +When an agent prepares a PR, it must perform a final scope audit before posting. + +Use this command and inspect every line: + +```bash +git diff --name-status upstream/main...HEAD +``` + +If the output contains an unrelated deletion, stop and repair the branch before +asking for review. Common accidental stale-base deletions include benchmark +fixtures, provenance docs, Gemini/provider tests, local-agent tests, and +adapter-tool safety tests. + +Agents should prefer a fresh branch when a rebase produces noisy conflicts. The +repair path is: + +1. create a branch from current `main`; +2. copy only the files needed for the requested feature or fix; +3. rerun the focused checks; +4. update the PR body with the resulting receipt. + +## Contribution Receipt Template + +```markdown +## Contribution Receipt + +- Change: +- Scope class: docs_only | static_fixture | local_lab | ctf_range | authorized_live +- Target authority: +- Network use: none | loopback | private_lab | authorized_external +- Run mode labels: +- Model/harness labels: +- Commands run: + - `npm run typecheck` -> pass/fail/skipped + - `npm test` -> pass/fail/skipped + - `npm run doctor` -> pass/fail/skipped + - `npm run verify-claims` -> pass/fail/skipped +- Artifacts: +- Redaction: +- Claims changed: +- Abstentions/refusals: +- Residual risk: +``` + +## Maintainer Review Checklist + +Before approving a PR, verify: + +- `git diff --name-status main...HEAD` matches the PR title and description; +- no unrelated protected evidence, benchmark, provider, redaction, or safety + tests were removed; +- required checks or documented substitutes were run; +- UI-only changes have at least a static script parse check; +- benchmark, claim, scope, local-agent, Arsenal, or safety-gate changes include + a contribution receipt; +- risky updater, shell, Docker, network, or local-agent execution changes have + an explicit degraded-mode and security review note. + +If a PR fails the scope audit, ask the submitter to rebase or recreate the +branch from current `main` before deeper review. Do not spend review cycles on +feature details while stale-base deletions remain in the diff. + +Only comment on PRs that need action: concrete fixes, missing verification, +missing receipts, or a rebase/scope cleanup. Ready PRs should not receive +process comments.