From 6e633246207818c992a81682a9ff77655de742f4 Mon Sep 17 00:00:00 2001 From: Max Moldovan Date: Thu, 10 Sep 2026 11:55:07 +0930 Subject: [PATCH] docs: record what branch protection now enforces, and cairn the 0.2.0 release Protection was enabled on main on 2026-09-10 and read back from the host API: pull request required, one approving code-owner review, ten required checks, no force push or deletion, administrators may bypass. The process record and the contributing guide described it as intended and unverified, which was accurate while it was off and understates it now. The release itself had no decision record. The cairn carries the version call (0.2.0 rather than 0.1.1, because three items stop working calls from working), the three rejected alternatives including removing the retired T argument as its own notice promised, and the forward cost -- a deprecation with no scheduled removal, and two documented limitations that ship with the release. --- CONTRIBUTING.md | 8 +- dev/PROCESS.md | 4 +- tools/ledger/INDEX.md | 1 + ...ease-020-guards-and-scoped-claims.cairn.md | 115 ++++++++++++++++++ 4 files changed, 122 insertions(+), 6 deletions(-) create mode 100644 tools/ledger/r-package/2026-09-10-release-020-guards-and-scoped-claims.cairn.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4cd3762..8fa2d18 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,10 +28,10 @@ author. ## Review Every pull request is reviewed under `REVIEW.md` and needs one approving -review from an author who did not write it. Branch protection on `main` is the intended -enforcement mechanism for that rule and for the required checks; this -repository does not record the host configuration, so confirm it on the -repository before relying on it. +review from an author who did not write it. Branch protection on `main` enforces this: a pull request is +required, one approving code-owner review, the ten required checks green, and +no force push or deletion. Administrators may bypass, so the rule binds the +ordinary workflow rather than every possible push. ## Reporting diff --git a/dev/PROCESS.md b/dev/PROCESS.md index 3e6a7b5..dc1a458 100644 --- a/dev/PROCESS.md +++ b/dev/PROCESS.md @@ -22,7 +22,7 @@ this process applies from 2026-09-02. | Design | `spec.md`: requirements, design, flagged concerns | same directory; the package-level specification is `dev/specification.md` | flagged concerns resolved before engineering starts; the other author signs off | the authors | | Build | `plan.md`: files that change, order of work, risks, proof | same directory, committed before code; a departure is recorded in the same commit as the change that causes it | a reader unfamiliar with the change could implement it from the plan alone | the author of the change | | Test | the diff, its tests, the evidence register | `acir/tests/`, `acir/inst/evidence/register.csv`, `.github/workflows/` | the four gates below, locally before the pull request and again in CI | CI, deterministically | -| Deploy | review findings ranked by severity | the pull-request thread, under `REVIEW.md` | one approving review from an author who did not write the change; branch protection is the intended enforcement, see the correspondence table below | the reviewing author | +| Deploy | review findings ranked by severity | the pull-request thread, under `REVIEW.md` | one approving review from an author who did not write the change; branch protection enforces it, see the correspondence table below | the reviewing author | | Maintain | incident record | a new `intent.md` | a bench breach or a numerical disagreement re-enters at Plan | the authors | ## The four gates @@ -90,7 +90,7 @@ and is a review finding in its own right. | Feedback loop before reporting done | the four gates, run locally and in CI | in use | | Continuous evaluation of agent configuration | not applicable to the repository | not used | | Review loop under a written policy | `REVIEW.md`; approval by a human author is required | in use | -| Hooks as approval gates | intended branch protection on `main`: pull request required, one approving review, the required checks green, no force push | intended; the host configuration is not recorded in this repository and has not been verified here | +| Hooks as approval gates | branch protection on `main`: pull request required, one approving code-owner review, ten required checks green, no force push or deletion | in use, enabled 2026-09-10 and read back from the host API; administrators may bypass | | An agent inside CI/CD | not used; CI is deterministic | not used | | Control bands in maintenance | `bench.yaml` compares every run with `baseline.csv`; a breach is triaged by the authors and re-enters as an intent | in use, with a manual response | | Recurring security scans | not used; the package opens no network connection (`SECURITY.md`) | not used | diff --git a/tools/ledger/INDEX.md b/tools/ledger/INDEX.md index 119d23a..e1fe143 100644 --- a/tools/ledger/INDEX.md +++ b/tools/ledger/INDEX.md @@ -10,6 +10,7 @@ ## Cairns +- [2026-09-10 T3 open] [acir 0.2.0 releases the guards and the scoped evidence claims, with the near-zero limitation documented rather than closed](r-package/2026-09-10-release-020-guards-and-scoped-claims.cairn.md) - [2026-09-09 T3 open] [The near-zero observation Gram ships documented for 0.1.0, and the scale guard is queued as its own work package](r-package/2026-09-09-near-zero-gram-documented-not-guarded.cairn.md) - [2026-09-02 T4 open] [acir 0.1.0 is tagged at parity with the reference implementation, with every performance budget met, before the remaining plan steps](r-package/2026-09-02-release-0.1.0-parity-milestone.cairn.md) - [2026-08-14 T3 open] [An unresolved causal influence range is right-censored, and is reported as a bound](r-package/2026-08-14-censored-range-not-missing.cairn.md) diff --git a/tools/ledger/r-package/2026-09-10-release-020-guards-and-scoped-claims.cairn.md b/tools/ledger/r-package/2026-09-10-release-020-guards-and-scoped-claims.cairn.md new file mode 100644 index 0000000..839832a --- /dev/null +++ b/tools/ledger/r-package/2026-09-10-release-020-guards-and-scoped-claims.cairn.md @@ -0,0 +1,115 @@ +--- +id: 2026-09-10-release-020-guards-and-scoped-claims +schema_version: 1.4 +date: 2026-09-10 +tier: T3 +classification: open +export_status: local_only +consensus_mode: none +domain: r-package +project: aciR +status: accepted +title: "acir 0.2.0 releases the guards and the scoped evidence claims, with the near-zero limitation documented rather than closed" +tags: [release, versioning, guards, evidence, governance] +triggers: + - adr_class_commitment + - release_reconciliation + - breaking_change_with_deprecation +reversal_cost: medium +decision_pressure: publication +review_due: null +review_trigger: "at the next release, or when the observation-scale guard work package lands and changes what is refused" +supersedes: [] +superseded_by: null +related: [2026-09-02-release-0.1.0-parity-milestone, 2026-09-09-near-zero-gram-documented-not-guarded] +--- + +## Status + +Released 2026-09-10. Tag `acir-v0.2.0` is annotated, sits on `6461892` (the +merge of the release pull request), and its tree is byte-identical to the +candidate that returned `Status: 1 NOTE` from `R CMD check --as-cran` locally, +where the single note is `New submission`. Ten checks green on that commit, read +back from the host API rather than inferred. `main` then opened at `0.2.0.9000` +and branch protection was enabled and read back the same way. + +## Alternatives considered + +| Option | One-line description | +|---|---| +| A | Patch release 0.1.1, treating the work as documentation corrections | +| B (CHOSEN) | Minor release 0.2.0, on the ground that three changes stop working calls from working | +| C | Hold the corrections unreleased until the observation-scale guard closes the near-zero case | +| D | Remove the retired `T` argument at 0.2.0, as the expiring deprecation notice promised | + +## Rationale for rejection + +### Option A + +`API_STABILITY.md` states that at 0.x the interface may change with the change +announced under a "Breaking changes" heading. Three of this release's items make +previously working calls fail: the declared R floor moved to 4.1.0 so +installation on 4.0.x is refused; a degenerate observation-noise Gram is refused +wherever it occurs, where before it returned numbers; and overflow in a +recursion raises rather than returning a silent non-finite value. A patch +release asserts that nothing a caller wrote stops working, which would be false. + +### Option C + +The near-zero case cannot be closed by a threshold chosen under release +pressure -- the reasoning is in the companion cairn. Holding an otherwise +finished release for it would have kept the corrected claims off the public +record for the sake of a limitation that is now stated in the help, in NEWS, in +five tests and in a work package. Correct claims shipped beat correct claims +withheld. + +### Option D + +The notice said `T` would be accepted "until 0.2.0", so arriving here forced a +choice. Removing it would break callers at the same release that already carries +three breaks, for an alias that costs nothing to keep. The promise was retired +instead of the argument, and NEWS records that no removal version is scheduled. +The cost is a deprecation with no end date, which the 1.0 planning inherits. + +## Implemented option (B) + +Version, citation metadata and the software-metadata record all read 0.2.0 and +R 4.1.0. `NAMESPACE` is byte-identical to the `acir-v0.1.0` tag, so no exported +surface moved. The fixture and evidence subtrees hash identically to the +pre-release `main`, and the only R file the release touched carries a +deprecation message and its roxygen. No graded quantity changed. + +## Forward cost + +- The release ships a documented route on which the implicit stepper returns a + collapsed posterior from a near-degenerate observation model, and a flooring + policy that can return a value of order 1e21 with a warning. Both are stated; + neither is closed. +- The `T` alias now has no scheduled removal. Semantic versioning is promised + from 1.0, so the removal needs a home in the 1.0 plan or the promise erodes. +- Branch protection binds the ordinary workflow from this release onward: each + author now needs the other's approval, and administrators may bypass. The + process record was corrected to describe what the host actually enforces. +- The evidence register carries 68 rows of which 40 are behavioural-only, and + the fixture producer route remains static and unexercised. Both are recorded + gaps that a reader of the register will meet, and the next release is when + they are most likely to be read closely. + +## References + +### Methodological + +- Preston-Werner, T. *Semantic Versioning 2.0.0*. https://semver.org/ -- the 0.x clause under which a minor bump carries breaking change before 1.0. + +### Empirical + +- `acir/NEWS.md`, `# acir 0.2.0` -- the Breaking changes heading and its three items. +- `acir/API_STABILITY.md` -- the 0.x interface promise this release is measured against. +- Local release-candidate check, 2026-09-10: `R CMD build` then `R CMD check --as-cran` returned `Status: 1 NOTE` (`New submission`); tests, examples with `--run-donttest`, and all three vignette rebuilds passed; the installed candidate reported version 0.2.0 and `citation("acir")` followed it. +- Subtree hashes against the pre-release `main`: fixtures and evidence register identical; all of `R/` except `aci-model.R` identical. + +### Operational + +- Cairn: `2026-09-09-near-zero-gram-documented-not-guarded.cairn.md` -- why the near-zero limitation ships documented. +- Cairn: `2026-09-02-release-0.1.0-parity-milestone.cairn.md` -- the release this one succeeds. +- Work package: `dev/work/2026-09-10-release-0.2.0/plan.md`, and `dev/work/2026-09-09-observation-scale-guard/intent.md` for the deferred guard.