diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 65f245e..cc63efe 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -16,6 +16,9 @@ Exact head SHA: `TBD` +Review and acceptance are bound to this SHA. Pushing another commit invalidates the +record below until it is updated and the new head is green. + | Check | Result | Evidence or notes | |---|---|---| | Focused regression/contract tests | TBD | | @@ -54,7 +57,13 @@ Use `Not applicable` when this pull request makes no research or performance cla - [ ] Research and performance claims are traceable to exact-head evidence and scoped to what was tested. - [ ] Every commit has a verifiable signature from its actual author or approved integration identity. - [ ] The branch has not been force-pushed and the exact head is ready for review. +- [ ] I understand that green PR checks establish review readiness; maintainer + acceptance, canonical merge verification, and release certification are + separate gates. A green PR gate makes the submission reviewable. Maintainers may add further tests or hardening in separately attributable commits before merge; behavior changes with zero relevant coverage remain blocked. + +See [`docs/RELEASE_PROCESS.md`](../docs/RELEASE_PROCESS.md) for the exact-head +acceptance, merge, tag, snapshot, and publication process. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1a1d2c..fbd900d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,6 +13,7 @@ quality policies, and the BT6 maintainer profile: - [`ci/test-risk-map.json`](ci/test-risk-map.json) - [`ci/conditional-test-policy.json`](ci/conditional-test-policy.json) - [`.aiwg/bt6-maintainer.yaml`](.aiwg/bt6-maintainer.yaml) +- [`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) If this guide and an enforced policy disagree, the enforced policy wins. Update the guide in the same pull request when intentionally changing a standard. @@ -61,12 +62,11 @@ currently fingerprint signing path. Maintainers preserve the original contributor as author when carrying their work and keep maintainer hardening or test commits separately attributable. -Canonical integration must preserve a verifiable signature. Use an exact -fast-forward of the audited signed head, or the repository's configured merge -method after confirming that the resulting canonical commit is verified. Do not -use GitHub rebase merge: GitHub recreates the commits and can publish unsigned -canonical objects even when the pull-request head was signed. Post-merge -reconciliation must verify the commit that actually landed on `main`. +Canonical integration must preserve a verifiable signature. Pull requests use the +repository's configured merge-commit method; squash and rebase merges are not used. +Maintainers confirm the exact accepted head at merge time, then verify the resulting +canonical commit and its post-merge CI on `main`. A signed pull-request head does not +substitute for verification of the commit that actually landed. Verify your local commit before pushing: @@ -108,6 +108,13 @@ critical-module, touched-module, mature-scope, repeat, mutation, packaging, Windows, and supply-chain gates. The full suite remains mandatory for a release; the faster pull-request lane is not a release exemption. +The complete lifecycle, acceptance states, immutable-tag rule, artifact reuse rule, +and publication gates are documented in +[`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md). In particular, a failed tag is +never moved or reused: the corrected candidate receives a new version and signed +tag. Releases publish the exact tested source snapshot and evidence, not a newly +rebuilt archive. + ### Test design standard Each behavior-changing pull request must include: @@ -291,6 +298,12 @@ run deeper gates before merge. Behavior changes with no relevant test coverage remain blocked; contributors are not expected to satisfy release-depth coverage and mutation gates merely to request review. +Acceptance, integration, and release certification are separate decisions. The +maintainer audit and merge must refer to the current exact head; the canonical merge +commit must then be signature-verified and pass post-merge CI. Only a new signed tag +that passes the exhaustive exact-tag suite can identify a release candidate. See +[`docs/RELEASE_PROCESS.md`](docs/RELEASE_PROCESS.md) for the normative sequence. + ## Contributing experiment results To contribute an abliteration result to the community dataset: diff --git a/README.md b/README.md index 2525391..79d3ffb 100644 --- a/README.md +++ b/README.md @@ -867,6 +867,11 @@ run the full Python matrix with 75% repository statement coverage, 60% repositor branch coverage, touched-module regression checks, mature-scope floors, deterministic property/order-repeat checks, selective mutation, package contracts, Windows portability, and supply-chain certification. +The project accepts pull requests and publishes releases through distinct, +exact-SHA-bound gates. See the [contributor guide](CONTRIBUTING.md) and +[pull-request acceptance and release process](docs/RELEASE_PROCESS.md) for merge +signature requirements, immutable failed tags, exact-tag certification, and the +source-only snapshot policy. Nine environment-bound test files run through the separately documented conditional workflow for model downloads, network services, operator UI, CUDA, bitsandbytes, physical Jetson CUDA, MPS, MLX, and least-privileged remote execution. The Jetson diff --git a/docs/RELEASE_PROCESS.md b/docs/RELEASE_PROCESS.md new file mode 100644 index 0000000..ce79e53 --- /dev/null +++ b/docs/RELEASE_PROCESS.md @@ -0,0 +1,103 @@ +# Pull-request acceptance and release process + +OBLITERATUS separates contributor feedback, maintainer acceptance, canonical +integration, and release certification. A green pull-request check is necessary, +but it is not by itself an acceptance or release decision. + +The enforced workflows and machine-readable policies remain authoritative. This +document explains how maintainers apply them. + +## Pull-request states + +1. **Reviewable:** the exact pull-request head is signed, conflict-free, and green + in the contributor-facing checks. Relevant behavior has focused coverage and + the description identifies tests not run, risk surfaces, and evidence limits. +2. **Accepted:** a maintainer audits that immutable head SHA for correctness, + research integrity, security, compatibility, documentation, and applicable + policy/risk-map changes. New commits invalidate the audit and require the new + head to be checked. +3. **Integrated:** the accepted head is merged with the repository's configured + merge-commit method. Squash and rebase merges are not used. The resulting + canonical `main` commit must have a forge-verified signature, and its post-merge + CI must pass before it can become a release candidate. +4. **Release-certified:** an exact signed `v*` tag on a clean canonical commit has + passed every required release gate and its emitted source snapshot and evidence + have been independently verified. + +Maintainers may add test depth or hardening in separately attributable signed +commits before acceptance. Thresholds, assertions, required jobs, or risk mappings +must never be weakened merely to merge a pull request. + +## Acceptance criteria + +A pull request cannot be accepted while any of these conditions applies: + +- its reviewed head SHA differs from the current head; +- a commit lacks a verifiable signature; +- required checks are pending, failing, stale, or attached to another SHA; +- relevant behavior has no meaningful test or contract coverage; +- review threads, conflicts, unexplained generated files, unrelated changes, or + unaddressed trust-boundary risks remain; +- research or performance claims exceed the supplied reproducible evidence; +- dependency, workflow, policy, documentation, or compatibility effects are not + included in the same reviewable change. + +The fast pull-request lane is deliberately narrower than the release suite. It +establishes review readiness without shifting release-depth work to contributors. + +## Release candidate preparation + +After all accepted work is merged, maintainers: + +1. reconcile the hosted pull-request and issue queues; +2. prune merged branches and confirm `main` is clean and synchronized; +3. verify the canonical merge signatures and post-merge CI results; +4. run the exhaustive local or hosted readiness suite against the exact candidate; +5. update the project version and create a new signed annotated version tag. + +Tags are immutable audit records. A failed candidate is not moved, deleted, or +reused. It remains unpublished, and the corrected candidate receives a new patch +version and a new signed tag. + +## Exact-tag release certification + +Pushing a `v*` tag runs the exhaustive release workflow against the tagged commit: + +- Python 3.10, 3.11, and 3.12 tests, import/CLI smoke checks, repository and branch + coverage floors, critical-file floors, mature CPU-scope policy, and touched-module + no-regression comparison; +- deterministic order and hash-seed repeats plus the bounded selective mutation + score gate; +- Windows checkpoint contracts; +- lock, workflow, package, secret, vulnerability, license, and supply-chain policy; +- creation of exactly one deterministic `git archive` source ZIP, a digest-bound + CycloneDX SBOM, `SHA256SUMS`, SLSA provenance, and Sigstore bundles. + +The package job creates the source ZIP once. Downstream validation and publication +must reuse those exact bytes; rebuilding an equivalent archive is not acceptable. +OBLITERATUS releases do not publish wheels, source distributions, executables, or +compiled libraries. + +## Conditional evidence and publication + +Before publication, maintainers manually run the applicable hosted software gates +against the exact tagged commit, including the pinned model/evaluation, disposable +network-service, and operator-UI gates. Hardware or credential-bound gates run only +when their trusted prerequisites are available. An unselected gate is not positive +support evidence, and an approved waiver blocks the associated support claim. + +Publication occurs only after: + +- the complete exact-tag workflow succeeds; +- the source ZIP checksum, SBOM binding, archive contents, and repository + attestations are independently verified; +- applicable conditional evidence is successful and fresh; +- a draft release contains only the tested source ZIP and its checksum, SBOM, and + attestation evidence, with matching digests. + +Publishing triggers the conditional workflow again. That release-event run must +also finish successfully and is retained as the final release record. + +See [Supply-chain policy](SUPPLY_CHAIN_POLICY.md) for artifact verification and +[Conditional test operations](conditional-testing.md) for selection, freshness, +runner isolation, and waiver semantics. diff --git a/docs/SUPPLY_CHAIN_POLICY.md b/docs/SUPPLY_CHAIN_POLICY.md index 37c7bdd..e834a57 100644 --- a/docs/SUPPLY_CHAIN_POLICY.md +++ b/docs/SUPPLY_CHAIN_POLICY.md @@ -28,6 +28,13 @@ archive. Publication must use this same tested and attested ZIP. A commit, dependency lock, snapshot instruction, artifact, checksum manifest, SBOM, or release-policy change invalidates the evidence. +The release is first assembled as a draft and its uploaded asset digests are +compared with the verified workflow outputs. It is published only after the exact-tag +and applicable conditional gates pass. Failed tags remain immutable, unpublished +audit records; a corrected candidate uses a new version. See +[`RELEASE_PROCESS.md`](RELEASE_PROCESS.md) for the complete acceptance and +publication sequence. + Consumers can perform the portable integrity check with: ```bash diff --git a/docs/conditional-testing.md b/docs/conditional-testing.md index 8ea7243..7b3a6b7 100644 --- a/docs/conditional-testing.md +++ b/docs/conditional-testing.md @@ -12,6 +12,12 @@ days, and treats evidence older than eight days as stale. Every workflow run pub a summary showing selected, successful, failed, and not-selected/no-fresh-evidence gates. +For a release, maintainers run the applicable hosted software gates manually against +the exact signed tag before publication. Publishing the release triggers the same +workflow again, and that release-event run is retained as the final freshness record. +Unselected hardware or credential-bound jobs remain explicit non-evidence. See +[`RELEASE_PROCESS.md`](RELEASE_PROCESS.md) for their place in the release sequence. + Unavailable hardware or credential-bound gates may use a committed environment waiver for at most 30 days. Each waiver names one gate, a canonical tracking issue, the reason, its opening and expiry dates, and the support claim it blocks. Invalid,