From 80b525c240ca5956ff48e96e5f6398d71ab49f79 Mon Sep 17 00:00:00 2001 From: Jim Cresswell Date: Thu, 18 Jun 2026 11:33:50 +0100 Subject: [PATCH] chore(consolidate): archive release-automation; distil lessons; experience note Deep consolidate-docs at the end of the Tier 1b session: - Archive the delivered, live-verified release-automation plan to runtime-infrastructure/archive/ (durable doctrine confirmed homed in README "## Releases", docs/dev-tooling.md, the release.yml comment, tools/release_increment.py, and audit_release_workflow). Add its completed-plans.md row + archive index entry; fix the thread-record link. - Refresh current/README.md to reality (F3/F8/F5/F7 done, F6 deferred; the gate-expansion plan is the live program spine). - Distil the session's settled lessons into distilled.md (governance-scanner vs config-shape audits, the SonarCloud new-code gate, WCAG-contrast-as-test, the agent_hooks self-lockout hazard). - Add a session experience note; update the Deep Consolidation Status. Incoming Practice boxes empty (no-op); napkin (222 lines) under the rotation threshold, left in place. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../2026-06-18-quality-program-tier1b.md | 51 +++++++++++++++++++ .agent/memory/active/distilled.md | 24 +++++++++ .agent/memory/operational/repo-continuity.md | 23 +++++---- ...ity-gate-surface-expansion.next-session.md | 14 ++--- .agent/plans/completed-plans.md | 1 + .../runtime-infrastructure/archive/README.md | 2 + .../release-automation.md | 2 +- .../runtime-infrastructure/current/README.md | 24 +++++---- 8 files changed, 112 insertions(+), 29 deletions(-) create mode 100644 .agent/experience/2026-06-18-quality-program-tier1b.md rename .agent/plans/runtime-infrastructure/{current => archive}/release-automation.md (96%) diff --git a/.agent/experience/2026-06-18-quality-program-tier1b.md b/.agent/experience/2026-06-18-quality-program-tier1b.md new file mode 100644 index 0000000..0e0b78a --- /dev/null +++ b/.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. diff --git a/.agent/memory/active/distilled.md b/.agent/memory/active/distilled.md index d4c34a9..97053d1 100644 --- a/.agent/memory/active/distilled.md +++ b/.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 `). 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 < **Delivered note (2026-06-18):** Live verification caught a real bug — diff --git a/.agent/plans/runtime-infrastructure/current/README.md b/.agent/plans/runtime-infrastructure/current/README.md index f3df6c8..5bf7b59 100644 --- a/.agent/plans/runtime-infrastructure/current/README.md +++ b/.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)