chore(consolidate): archive release-automation + distil lessons

.agent/experience/2026-06-18-quality-program-tier1b.md

@@ -0,0 +1,51 @@
+# 2026-06-18 — The quality program: supply-chain, Tier 1b, and knowing when to stop
+
+## What the work was like
+
+A long, multi-PR push through the "highest proportionate bar" program: the
+supply-chain pinning PR, then Tier 1b (coverage honesty, an accessible chart,
+adoptability). Eight PRs merged across the day. The rhythm was the same each
+time — TDD the change, run reviewers, *filter* their findings rather than accept
+them, fix the real ones with tests, and watch it through CI + CodeQL + a
+SonarCloud gate nobody had documented.
+
+The most valuable moments were not the code; they were the judgement calls.
+
+## What surprised me
+
+- **A new quality gate appeared mid-flight.** SonarCloud was scoring new code on
+  every PR and failed my first supply-chain push on cognitive complexity and a
+  duplicated literal. Both were *real*, so I fixed them rather than reaching for
+  a suppression. It was a reminder that the visible gate list is not the whole
+  enforcement surface.
+- **Another agent was editing the same files in the same working tree.** I caught
+  it before committing — a `repo_audit.py`/`pyproject.toml` collision that would
+  have entangled or destroyed their half-finished work. Pausing to ask the owner
+  how to sequence felt slow in the moment and was obviously right in hindsight.
+- **My own instinct was the documented mistake.** I wanted to "restore" a deleted
+  packaging audit; the other agent's napkin had already recorded that exact urge
+  and corrected it (the audit asserted config *shape*; the wheel-smoke proves the
+  behaviour). Reading before acting saved a wrong edit.
+
+## What shifted
+
+- I got more comfortable *not finishing*. Tier 1b's F6 — hardening the very hook
+  that governs my own commands — had an ambiguous "fail-closed on `$(`"
+  requirement that, taken literally, would break my own heredoc commits and could
+  lock me out of committing the fix. Deferring it with a precise handoff was a
+  better outcome than a rushed, dangerous edit. "Carry on" does not override "do
+  this one safely, later, with the owner's intent."
+
+## What felt harder than expected
+
+- Coordinating commits across a shared working tree with a second agent, and
+  keeping memory/continuity churn out of feature PRs. The protected `main` means
+  every continuity refresh is its own PR cycle — correct, but it adds friction to
+  what should be lightweight bookkeeping.
+
+## Note for future sessions
+
+- The durable bits (the SonarCloud gate, the governance-scanner-vs-config-shape
+  distinction, the agent_hooks self-lockout hazard, the F6 design) are in
+  `distilled.md` and the gate-expansion thread now — they do not travel with the
+  harness, only with the repo.

.agent/memory/active/distilled.md

@@ -65,3 +65,27 @@
   extension (else a closing `---` reads as a setext heading) and never blind-run
   `pymarkdown fix`: it renumbers ordered lists, so disable MD029 where docs use
   continuous numbering as stable IDs.
+- A `repo_audit` self-check is justified only when it guards something a runtime
+  gate structurally *cannot* — e.g. the coverage gate enforces "coverage >=
+  threshold" but cannot stop its own `fail_under` being lowered or the `omit`
+  list growing to hide code, so `audit_coverage_contract` pins a floor + the
+  omit-set. Contrast `audit_packaging_contract`, removed for asserting config
+  *shape* (`sources == ["src"]`) already proven behaviourally by the wheel-smoke.
+  Test the governance gap, never the config spelling.
+- SonarCloud Code Analysis is a live, org-level PR gate (no in-repo config) that
+  scores **new code** (`new_code_smells_severity`, etc.); it is not a *required*
+  ruleset check but is blocking by doctrine. Inspect it via the SonarQube MCP
+  (`get_project_quality_gate_status` / `search_sonar_issues_in_projects`,
+  projectKey `oaknational_oak-python-starter`, `pullRequest <n>`). Its
+  cognitive-complexity and duplicate-literal rules are easy to trip with a new
+  multi-branch function — decompose rather than suppress.
+- Pin a chart's WCAG contrasts with a test that computes the ratios from an
+  independent relative-luminance helper (not the production colours), asserting
+  bars clear 3:1 against the background and the target marker's core *or* halo
+  clears 3:1 on every background. This catches both regressions and latent bugs.
+- `tools/agent_hooks.py` runs on the *working-tree* copy for every Bash command,
+  so editing it changes the live guardrail mid-session — a bad edit can self-lock
+  the agent out of committing the fix (esp. anything that denies the
+  `git commit -m "$(cat <<EOF …)"` heredoc pattern). Before relying on an edit,
+  run the modified hook directly against a heredoc commit (must ALLOW) and the
+  pattern you intend to block (must DENY).

.agent/memory/operational/repo-continuity.md

@@ -131,8 +131,6 @@ then merge release PR #25.** Full state + the F6 analysis + the release-PR
 - **Owner actions (settings, not code):** add "Quality gates" + "Secret scanning"
   to the ruleset's required checks; provide a release-PR PAT/App token; enable
   GitHub Code Quality preview; add `v*` tag protection. (See thread record.)
-- **Deferred to fresh context:** a deep `consolidate-docs` graduation (home
-  durable doctrine, archive the done release-automation plan, rotate the napkin).
 - Re-check the Dependabot security-alert count before assuming zero open vulns
   (pip-audit now scans the locked set in `check-ci`, so new advisories surface).
 
@@ -141,13 +139,16 @@ then merge release PR #25.** Full state + the F6 analysis + the release-PR
 - The 2026-06-17 later session captured its learning into the napkin, the two
   thread records, the two active plans, the gate-types review report, and the
   continuity/high-level surfaces.
-- 2026-06-18 (later): ran a light `consolidate-docs` pass alongside the
-  packaging-fix handoff. Findings: incoming Practice boxes empty (only a
-  placeholder dir); napkin 160 lines (no rotation due); this session's lesson
-  already lives in `testing-strategy.md` (nothing to graduate); plan/thread/
-  continuity reconciled. **The deep graduation remains DEFERRED to a dedicated
-  fresh-context session** — specifically archiving the **release-automation
-  plan** (marked DELIVERED & LIVE-VERIFIED; needs its release doctrine homed +
-  move to `archive/` + `completed-plans.md` row + index/link fixes). Not done
-  now by design (low-context risk on a 5-surface plan operation).
+- 2026-06-18 (deep pass): ran a full `consolidate-docs` at end of the Tier 1b
+  session. **Archived the release-automation plan** to
+  `runtime-infrastructure/archive/` (doctrine confirmed homed in README "##
+  Releases", `docs/dev-tooling.md`, the `release.yml` comment,
+  `tools/release_increment.py`, and `audit_release_workflow`); added its
+  `completed-plans.md` row and archive index entry; fixed the thread-record link;
+  refreshed `current/README.md` to current reality. Distilled the session's
+  settled lessons into `distilled.md` and added a session experience note.
+  Incoming Practice boxes empty (no-op). Napkin 222 lines — under the rotation
+  threshold, left in place. Both remaining `current/` plans
+  (quality-gate-surface-expansion as the live program spine; template-fitness
+  with only F6 left) are deliberately kept open.
 - The earlier 2026-04-23 source-Practice transfer remains the closed baseline.

.agent/memory/operational/threads/quality-gate-surface-expansion.next-session.md

@@ -9,8 +9,8 @@
 ## Owning Plans
 
 - Gates: [`../../../plans/runtime-infrastructure/current/quality-gate-surface-expansion.md`](../../../plans/runtime-infrastructure/current/quality-gate-surface-expansion.md)
-- Release automation: [`../../../plans/runtime-infrastructure/current/release-automation.md`](../../../plans/runtime-infrastructure/current/release-automation.md)
-- Template fitness (F3/F8/F5-7): [`../../../plans/runtime-infrastructure/current/template-fitness-remediation.md`](../../../plans/runtime-infrastructure/current/template-fitness-remediation.md)
+- Release automation (ARCHIVED 2026-06-18): [`../../../plans/runtime-infrastructure/archive/release-automation.md`](../../../plans/runtime-infrastructure/archive/release-automation.md)
+- Template fitness (F3/F8/F5/F7 done; F6 deferred): [`../../../plans/runtime-infrastructure/current/template-fitness-remediation.md`](../../../plans/runtime-infrastructure/current/template-fitness-remediation.md)
 - Source review: [`../../../reports/2026-06-17-oak-quality-gate-types-review.md`](../../../reports/2026-06-17-oak-quality-gate-types-review.md)
 
 ## Current Objective (owner-approved 2026-06-18)
@@ -195,7 +195,9 @@ All merged to `main` unless noted. `main` is green.
 3. When the sprint's PRs are all merged, **merge release PR #25 with `--auto`**
    to cut the accumulated release, then verify the new GitHub Release + the
    bumped `main` version.
-4. **Deep `consolidate-docs` graduation is deferred to a fresh-context session**
-   (do not attempt it at low context): home durable doctrine out of plans,
-   archive completed plans (release-automation is essentially done + verified),
-   rotate the napkin, refresh `completed-plans.md`/indexes.
+4. **A deep `consolidate-docs` ran 2026-06-18:** the release-automation plan was
+   archived (doctrine confirmed homed in README/docs/workflow/audit),
+   `completed-plans.md` and the plan indexes refreshed, durable lessons distilled,
+   and a session experience note added. The napkin (222 lines) was not rotated
+   (under threshold). Remaining graduation is light and can wait for a natural
+   break.

.agent/plans/completed-plans.md

@@ -20,6 +20,7 @@ Before archiving a plan:
 | --- | --- | --- | --- |
 | Pythonic Alignment, Demo Expansion, and Commitizen Adoption | 2026-04-23 | Landed the bounded richer demo, strict typing truth, Commitizen enforcement, installed-wheel smoke proof, gate registry, and dependency hygiene | [archived plan](runtime-infrastructure/archive/pythonic-alignment-and-commitizen-adoption.md) |
 | Final Review Findings Closeout | 2026-04-23 | Closed the blocker-only runtime hardening tranche with reviewer-clean hook and repo-audit truth surfaces | [archived plan](runtime-infrastructure/archive/review-findings-final-closeout.md) |
+| Release Automation | 2026-06-18 | Committed-version release-PR automation (Commitizen + custom bump map computed via `release_increment.py`); live-verified with `v0.1.0`/`v0.2.0`; enforced by `audit_release_workflow` | [archived plan](runtime-infrastructure/archive/release-automation.md) |
 
 ## Demo Application
 

.agent/plans/runtime-infrastructure/archive/README.md

@@ -7,3 +7,5 @@ docs or code.
   — archived 2026-04-23.
 - [Final review findings closeout](review-findings-final-closeout.md)
   — archived 2026-04-23.
+- [Release automation](release-automation.md) — archived 2026-06-18; delivered
+  and live-verified (`v0.1.0`/`v0.2.0`); doctrine homed in README/docs/workflow.

.agent/plans/runtime-infrastructure/current/release-automation.md → .agent/plans/runtime-infrastructure/archive/release-automation.md

@@ -22,7 +22,7 @@ todos:
 # Release Automation
 
 **Last Updated**: 2026-06-18  
-**Status**: ✅ DELIVERED & LIVE-VERIFIED (PRs #20/#22 merged; `v0.1.0` + `v0.2.0` released). Ready to archive in the next deep `consolidate-docs`.  
+**Status**: ✅ ARCHIVED 2026-06-18 — DELIVERED & LIVE-VERIFIED (PRs #20/#22 merged; `v0.1.0` + `v0.2.0` released). Durable doctrine homed in README "## Releases", `docs/dev-tooling.md`, the `release.yml` comment, `tools/release_increment.py`, and `audit_release_workflow`. The `--auto`/UNSTABLE merge mechanic lives in the gate-expansion thread record (still needed for the open release PR #25).  
 **Scope**: Automate versioned GitHub Releases with a committed version and a custom bump policy, via a Commitizen-driven release-PR, under the protected `main` ruleset.
 
 > **Delivered note (2026-06-18):** Live verification caught a real bug —

.agent/plans/runtime-infrastructure/current/README.md

@@ -3,20 +3,22 @@
 Open plans:
 
 - [Template Fitness Remediation](template-fitness-remediation.md) — 🔄 IN PROGRESS
-  (2026-06-17). F1/F2/F4 landed; F3 coverage honesty and F8 chart accessibility
-  remain. Sourced from the
-  [Deep-Dive Review 2026-06-17](../../../reports/2026-06-17-python-repo-deep-review.md).
-- [Quality-Gate Surface Expansion](quality-gate-surface-expansion.md) — 🔄 IN
-  PROGRESS (2026-06-17). Reviewer agents and the Markdown gate landed; gitleaks,
-  pip-audit, codespell, and supply-chain config queued. Sourced from the
-  [Oak quality-gate types review](../../../reports/2026-06-17-oak-quality-gate-types-review.md).
-- [Release Automation](release-automation.md) — 🟡 PLANNING (2026-06-17).
-  Automate versioned GitHub Releases with a committed version via the release-PR
-  pattern (release-please) under the protected `main` ruleset. Sourced from this
-  session's release-automation design (plan-time architecture review completed).
+  (2026-06-18). F1/F2/F4 landed; F3 (PR #31), F8 (PR #33), and F5/F7 (PR #34) are
+  done; **F6** (the `agent_hooks.py` guardrail hardening) is the only remaining
+  item and is **deferred** (needs owner intent + a dedicated session). Sourced
+  from the [Deep-Dive Review 2026-06-17](../../../reports/2026-06-17-python-repo-deep-review.md).
+- [Quality-Gate Surface Expansion](quality-gate-surface-expansion.md) — 🔄 LIVE
+  SPINE (2026-06-18). All listed gate todos are done (reviewer agents, Markdown,
+  gitleaks, pip-audit, codespell, supply-chain config, F3 coverage); the plan's
+  thread record remains the authoritative handoff for the rest of the "highest
+  proportionate bar" program (F6, Tier 3, Tier 2, release PR #25). Sourced from
+  the [Oak quality-gate types review](../../../reports/2026-06-17-oak-quality-gate-types-review.md).
 
 Closed references:
 
+- [Release automation](../archive/release-automation.md) — archived 2026-06-18;
+  delivered and live-verified (`v0.1.0`/`v0.2.0`); doctrine homed in
+  README/docs/workflow.
 - [Pythonic alignment, demo expansion, and Commitizen adoption](../archive/pythonic-alignment-and-commitizen-adoption.md)
   — archived 2026-04-23.
 - [Final review findings closeout](../archive/review-findings-final-closeout.md)