chore(governance): stamp nine merged ADRs Accepted + pin the invariant in smoke #114

Merged

core-labs merged 1 commit from chore/adr-status-governance into main

2026-07-25 21:55:33 +00:00

core-labs commented

2026-07-25 21:44:10 +00:00

Owner

Closes the governance gap surfaced three times during the Tier-S / assessment review.

The defect

Nine ADRs — 0254, 0256–0263 — were merged into main and left stamped Proposed. Two carried an explicit ratify-on-merge predicate their own merge had already discharged, and ADR-0256 governs deduction_serving_enabled, ratified True on 2026-07-24 and serving live traffic. The governance record asserted "not yet decided" about a decision already in force.

Same asymmetry PR #113 found one file over in workbench/api.py: the honest path degrades, the stale record lies. An unwritten ADR is a visible gap; a Proposed one that is actually in force is a false statement.

The stamps

Each records the actual ratifying act — Accepted — ratified by Joshua Shay via <merge> (<sha>, <date>) — derived from the commit that added the file and verified an ancestor of main, not assumed. Merge authority is yours alone (AGENTS.md: no merge automation), so the merge is the ratifying act and naming it is traceable rather than decorative.

ADR	ratifying merge
0254	PR #103 → `da3447e9`
0256	`1a6ccaf9`; flag flipped separately at `5dd61803`
0257 / 0258 / 0259 / 0260	PR #107 `9405cf19` / #108 `dd2245a7` / #109 `5224b5e0` / #111 `2a82c8a3`
0261	`a8488e9c`
0262 / 0263	`0ae54ebb`

No ADR content changed. No flag changed. ADR-0262's stamp says so explicitly: accepting it does not enable curriculum_serving_enabled, which stays False pending ratified volume — eleven bands re-measured today against the live loader, still 24×–73× short, identical to the S6 figures.

The pin

tests/test_adr_status_governance.py, in the smoke (pre-push) suite. Two independent invariants:

A default-ON flag is not governed by a Proposed ADR. The flag → ADR mapping is derived by walking core/config.py for <name>: bool = True and reading ADR refs out of the preceding comment block — deliberately not a hand-written table, which would be the identical second-copy-of-a-closed-set defect ADR-0256's own arc just fixed.
A ratify-on-merge predicate cannot coexist with Proposed. Self-discharging — the file being on main is the merge having happened.

Plus test_config_flag_parse_is_not_vacuous, because a derivation that silently parses zero flags would make every other assertion pass on an empty set.

Binding scope today is exactly one flag/ADR pair (only 1 of 32 runtime bool flags is both default-True and ADR-citing). Narrow by construction, and it widens automatically the next time an earned path is ratified ON.

Two orphans registered in passing

tests/test_adr_index.py (5) and tests/test_ratification_ceremony.py (14) landed in #113 in no curated suite. full is the directory tests/, so they ran there and nowhere that gates — 19 tests outside every gate, including the ceremony, the one mechanism that can move the curriculum-volume constraint. Registered into smoke and teaching respectively. Fifth instance of this shape (stale suite tuple, stale lane roster, masked lane pin, unregistered grounding label, now unregistered files).

Deliberately not fixed

The 312-file ADR corpus has 27 unparseable status lines plus draft/ratified/active/accepted. variants. A closed-vocabulary assertion would fail on ~35 pre-existing files and get muted or xfailed — and a muted gate reads as coverage. Scope is therefore exactly the load-bearing ADRs, failing loudly on any of those it cannot parse. The normalization sweep is recorded as an open item in docs/research/adr-status-governance-2026-07-25.md §6 and is a good delegation candidate: mechanical docs work with a test as its acceptance criterion.

[Verification]: smoke 555 passed in 137.73s (236 baseline + 314 + 5, +1.2s runtime); governance pin 314 passed in 1.18s standalone and mutation-checked — reverting ADR-0256 to Proposed fails both invariants independently (2 failed / 312 passed); orphans 19 passed; ruff clean. Pre-push gate green on the way out (deductive 285 passed / 50.29s). Canonical Python 3.12.13, uv sync --locked.

Not merged, per standing policy.

Closes the governance gap surfaced three times during the Tier-S / assessment review. ## The defect Nine ADRs — **0254, 0256–0263** — were merged into `main` and left stamped `Proposed`. Two carried an explicit `ratify-on-merge` predicate their own merge had already discharged, and **ADR-0256 governs `deduction_serving_enabled`, ratified `True` on 2026-07-24 and serving live traffic.** The governance record asserted "not yet decided" about a decision already in force. Same asymmetry PR #113 found one file over in `workbench/api.py`: the honest path degrades, the stale record lies. An unwritten ADR is a visible gap; a `Proposed` one that is actually in force is a false statement. ## The stamps Each records the **actual** ratifying act — `Accepted — ratified by Joshua Shay via <merge> (<sha>, <date>)` — derived from the commit that added the file and verified an ancestor of `main`, not assumed. Merge authority is yours alone (`AGENTS.md`: no merge automation), so the merge *is* the ratifying act and naming it is traceable rather than decorative. | ADR | ratifying merge | |---|---| | 0254 | PR #103 → `da3447e9` | | 0256 | `1a6ccaf9`; flag flipped separately at `5dd61803` | | 0257 / 0258 / 0259 / 0260 | PR #107 `9405cf19` / #108 `dd2245a7` / #109 `5224b5e0` / #111 `2a82c8a3` | | 0261 | `a8488e9c` | | 0262 / 0263 | `0ae54ebb` | **No ADR content changed. No flag changed.** ADR-0262's stamp says so explicitly: accepting it does **not** enable `curriculum_serving_enabled`, which stays `False` pending ratified volume — eleven bands re-measured today against the live loader, still 24×–73× short, identical to the S6 figures. ## The pin `tests/test_adr_status_governance.py`, in the **`smoke`** (pre-push) suite. Two independent invariants: 1. **A default-ON flag is not governed by a `Proposed` ADR.** The flag → ADR mapping is **derived** by walking `core/config.py` for `<name>: bool = True` and reading ADR refs out of the preceding comment block — deliberately not a hand-written table, which would be the identical second-copy-of-a-closed-set defect ADR-0256's own arc just fixed. 2. **A `ratify-on-merge` predicate cannot coexist with `Proposed`.** Self-discharging — the file being on `main` *is* the merge having happened. Plus `test_config_flag_parse_is_not_vacuous`, because a derivation that silently parses zero flags would make every other assertion pass on an empty set. Binding scope today is exactly one flag/ADR pair (only 1 of 32 runtime bool flags is both default-True and ADR-citing). Narrow by construction, and it widens automatically the next time an earned path is ratified ON. ## Two orphans registered in passing `tests/test_adr_index.py` (5) and `tests/test_ratification_ceremony.py` (14) landed in #113 in **no** curated suite. `full` is the directory `tests/`, so they ran there and nowhere that gates — 19 tests outside every gate, including the ceremony, the one mechanism that can move the curriculum-volume constraint. Registered into `smoke` and `teaching` respectively. **Fifth instance** of this shape (stale suite tuple, stale lane roster, masked lane pin, unregistered grounding label, now unregistered files). ## Deliberately not fixed The 312-file ADR corpus has **27 unparseable status lines** plus `draft`/`ratified`/`active`/`accepted.` variants. A closed-vocabulary assertion would fail on ~35 pre-existing files and get muted or `xfail`ed — and a muted gate reads as coverage. Scope is therefore exactly the load-bearing ADRs, failing loudly on any of *those* it cannot parse. The normalization sweep is recorded as an open item in `docs/research/adr-status-governance-2026-07-25.md` §6 and is a good delegation candidate: mechanical docs work with a test as its acceptance criterion. [Verification]: smoke **555 passed in 137.73s** (236 baseline + 314 + 5, +1.2s runtime); governance pin **314 passed in 1.18s** standalone and **mutation-checked** — reverting ADR-0256 to `Proposed` fails both invariants independently (2 failed / 312 passed); orphans 19 passed; `ruff` clean. Pre-push gate green on the way out (deductive 285 passed / 50.29s). Canonical **Python 3.12.13**, `uv sync --locked`. Not merged, per standing policy.

core-labs added 1 commit 2026-07-25 21:44:12 +00:00

chore(governance): stamp nine merged ADRs Accepted + pin the invariant efd3bee9ce

Nine ADRs (0254, 0256-0263) were merged into main and left stamped Proposed.
Two carried an explicit ratify-on-merge predicate their own merge had already
discharged, and ADR-0256 governs deduction_serving_enabled, which was ratified
True on 2026-07-24 and is serving live traffic. So the governance record
asserted "not yet decided" about a decision already in force.

That is the asymmetry the assessment arc (#113) found one file over in
workbench/api.py: the honest path degrades, the stale record lies. An unwritten
ADR is a visible gap; a Proposed one that is actually in force is a false
statement.

Each stamp records the ACTUAL ratifying act -- "Accepted, ratified by Joshua
Shay via <merge> (<sha>, <date>)" -- derived from the commit that added the file
and verified an ancestor of main, not assumed. Merge authority is Shay's alone
(AGENTS.md: no merge automation), so the merge IS the ratifying act.

No ADR content changed. No flag changed. ADR-0262's stamp says so explicitly:
accepting it does NOT enable curriculum_serving_enabled, which stays False
pending ratified volume -- eleven bands re-measured today, still 24x-73x short.

tests/test_adr_status_governance.py pins two independent invariants in the
smoke (pre-push) suite:

1. A default-ON flag is not governed by a Proposed ADR. The flag -> ADR mapping
   is DERIVED by walking core/config.py for `<name>: bool = True` and reading
   ADR refs from the preceding comment block -- not a hand-written table, which
   would be the same second-copy-of-a-closed-set defect ADR-0256's arc fixed.
2. A ratify-on-merge predicate cannot coexist with Proposed. Self-discharging:
   the file being on main IS the merge having happened.

Plus a vacuity guard, because a derivation that parses zero flags would make
every other assertion pass on an empty set.

Registered two orphans found in passing: test_adr_index.py (5) and
test_ratification_ceremony.py (14) landed in #113 in NO curated suite, so 19
tests -- including the one mechanism that can move curriculum volume -- ran
only under `full`, which gates nothing. Fifth instance of this shape.

Deliberately NOT fixed, recorded in the research doc: the 312-file corpus has
27 unparseable status lines and draft/ratified/active variants. A closed-vocab
assertion would fail on ~35 pre-existing files and get muted, and a muted gate
reads as coverage.

[Verification]: smoke 555 passed in 137.73s (236 baseline + 314 + 5, +1.2s);
governance pin 314 passed in 1.18s standalone and MUTATION-CHECKED -- reverting
ADR-0256 to Proposed fails both invariants independently (2 failed/312 passed);
orphans 19 passed; ruff clean. Canonical Python 3.12.13, uv sync --locked.