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.