diff --git a/.agent/memory/active/napkin.md b/.agent/memory/active/napkin.md index 2cc7117..efceac4 100644 --- a/.agent/memory/active/napkin.md +++ b/.agent/memory/active/napkin.md @@ -35,6 +35,15 @@ - The harness auto-mode classifier **blocks `gh workflow run Release -f increment=...`** — agent-forced release version. Rely on the computed increment from a real merge. +- **Consolidation must reach the STRATEGIC index, not just continuity/threads.** + A deep `consolidate-docs` pass refreshed continuity, thread records, and the + collection README but left `high-level-plan.md` + `roadmap.md` at a mid-program + snapshot — the top-level strategic surfaces are easy to forget. Add them to the + consolidation sweep. (Caught when the owner asked for a strategic retrospective.) +- **The sharp strategic question is proportionality, not more rigor.** For a + "lightweight template foundation", the VISION's clone/rename/adapt promise is + validated by construction, not by a real adoption — so the next high-value move + is a first-adoption dry-run (`docs/first-adoption-dry-run.md`), not more gates. ## Session: 2026-06-18 (final) — program COMPLETE: F6 + Tier 3 + Tier 2 + deps + v0.3.0 diff --git a/.agent/memory/operational/repo-continuity.md b/.agent/memory/operational/repo-continuity.md index d41c1f2..27d0453 100644 --- a/.agent/memory/operational/repo-continuity.md +++ b/.agent/memory/operational/repo-continuity.md @@ -176,4 +176,12 @@ over-block). Full state in the release-model experience note. Incoming Practice boxes empty (no-op). Napkin 294 lines — under the rotation threshold, left in place; `distilled.md` unchanged (durable lessons already homed in docs). +- 2026-06-18 (final, strategic tier): refreshed the **strategic index** — + `high-level-plan.md` (strand table + next intentions) and `roadmap.md` had + stayed at a mid-program snapshot that the previous consolidation pass missed + (it reached continuity/threads/collection-README but not the top-level index). + Both now reflect program completion + the continuous-release model, and reframe + the next move as **proving the clone/rename/adapt promise** (new + `docs/first-adoption-dry-run.md`) and **watching proportionality**. Also fixed a + stale "release-PR automation" line in `docs/using-this-template.md`. - The earlier 2026-04-23 source-Practice transfer remains the closed baseline. diff --git a/.agent/plans/high-level-plan.md b/.agent/plans/high-level-plan.md index 38e390e..730995a 100644 --- a/.agent/plans/high-level-plan.md +++ b/.agent/plans/high-level-plan.md @@ -2,7 +2,7 @@ plan_id: high-level-plan type: strategic-index status: active -last_updated: 2026-06-17 +last_updated: 2026-06-18 --- # High-Level Plan @@ -15,21 +15,29 @@ Execution detail belongs in collection roadmaps and active plans. | Strand | Goal | Current state | | --- | --- | --- | -| Agentic engineering | Keep the Practice, planning, review, and adapter estate coherent | Baseline landed; reviewer agents registered with a Pythonicity lens; maintain and refine | -| Runtime infrastructure | Keep validation, audits, reports, and quality gates truthful | CI live; template-fitness F1/F2/F4 landed (F3/F8 remain); quality-gate-surface-expansion in progress (Markdown gate landed; gitleaks/pip-audit/codespell/supply-chain queued) | -| Demo application | Keep `activity-report` useful without redefining repo identity | Baseline landed; intentionally bounded | +| Agentic engineering | Keep the Practice, planning, review, and adapter estate coherent | Mature; reviewer agents + the Practice/memory/continuity estate carried a multi-session, multi-PR program; the `agent_hooks` safety rail was hardened (F6). Maintain and refine. | +| Runtime infrastructure | Keep validation, audits, reports, and quality gates truthful | The "highest proportionate bar" program is **complete**: full `check-ci` gate suite + gitleaks/SonarCloud/CodeQL, a **self-guarding `repo_audit`** (pins the gates' own config), supply-chain SHA-pinning, branch coverage, and **continuous release on merge (PR-merge-only)** via the release bot. Required status checks + `v*` tag protection enforced. **Tier 4 deliberately deferred.** | +| Demo application | Keep `activity-report` useful without redefining repo identity | Bounded by design; now WCAG 2.2 AA accessible and exercised by Hypothesis property tests + the wheel smoke. | ## Immediate next intentions -1. Finish the template-fitness remediation: F3 coverage honesty and F8 chart - accessibility (F4 CI is landed). See - [runtime-infrastructure/current/template-fitness-remediation.md](runtime-infrastructure/current/template-fitness-remediation.md). -2. Continue the quality-gate-surface-expansion: gitleaks, pip-audit, codespell, - supply-chain config. See - [runtime-infrastructure/current/quality-gate-surface-expansion.md](runtime-infrastructure/current/quality-gate-surface-expansion.md). -3. Preserve coherence across the Practice surfaces as the template evolves. -4. Keep the runtime and repo-audit foundations truthful. -5. Resist demo-application sprawl while keeping the seeded example executable. +1. **Prove the core VISION promise.** The clone/rename/adapt outcome is validated + by construction (rename guide + `repo_audit`-as-checklist), not yet by a real + adoption. Run the + [first-adoption dry-run](../../docs/first-adoption-dry-run.md), fork → rename → + adapt, and feed the friction back into the template. +2. **Watch proportionality.** The bar is the *highest **proportionate*** one — a + lightweight template foundation, not a feature product. Resist adding rigor + that raises adopter cognitive load without proportionate value; Tier 4 stays + deferred unless explicitly requested. +3. **Owner action:** enable the GitHub Code Quality org preview (the last + governance setting). See + [docs/repository-governance.md](../../docs/repository-governance.md). +4. **Deferred residuals when warranted:** the `agent_hooks` glued-operator / + bare-subshell bypasses (need a quote-aware tokeniser — safety-critical, its own + session); physically archive the two completed `current/` plans. +5. Preserve Practice-surface coherence and keep the runtime/repo-audit foundations + truthful; resist demo-application sprawl. ## Read order diff --git a/.agent/plans/roadmap.md b/.agent/plans/roadmap.md index 6f5cdd8..c5116af 100644 --- a/.agent/plans/roadmap.md +++ b/.agent/plans/roadmap.md @@ -10,8 +10,12 @@ The repo grows in three layers: ## Near term +- **prove the clone/rename/adapt promise** with a real first-adoption dry-run + (see [docs/first-adoption-dry-run.md](../../docs/first-adoption-dry-run.md)) and + trim or document whatever friction it surfaces +- keep the (now substantial) gate, release, and `repo_audit` machinery honest — + and proportionate to a template, not a feature product - preserve planning, memory, and adapter parity -- keep repo audit and hooks honest - maintain a small but complete demo surface ## Ongoing constraint diff --git a/docs/first-adoption-dry-run.md b/docs/first-adoption-dry-run.md new file mode 100644 index 0000000..1e91840 --- /dev/null +++ b/docs/first-adoption-dry-run.md @@ -0,0 +1,72 @@ +# First-adoption dry-run + +A structured exercise to prove this template delivers its core promise — that it +can be **cloned, renamed, and adapted without dragging old product history** — and +to catch anywhere the rigor has become disproportionate for a *template +foundation* rather than a feature product. + +Run it once, end-to-end, against a throwaway fork. The real output is the +**friction log** at the bottom, which feeds back into the template. + +This is the validation wrapper around the step-by-step +[rename guide](using-this-template.md); it does not duplicate those steps. + +## Why bother + +The clone/rename/adapt outcome is currently validated *by construction* — the +rename guide plus `repo_audit` acting as a rename checklist — not by a real +adoption. Until someone forks it and follows through, friction and heaviness stay +invisible. This dry-run makes them visible while they are cheap to fix. + +## Setup + +- Install the prerequisites from the README (`uv`, the pinned Python, `gitleaks`). +- Clone into a throwaway location; you will not keep the result. +- Pick a target identity from the + [three names](using-this-template.md#the-three-names). + +## Walkthrough + +1. **Baseline.** Run `uv sync`, then + `uv run python -m oaknational.python_repo_template.devtools check`. Confirm the + gates pass out of the box with no manual fix-ups, and note how long a cold + `check` takes (the wheel smoke dominates) — that wait is part of the adopter + experience. +2. **Rename.** Work through the rename guide's + [ordered steps](using-this-template.md#ordered-steps). After each step, `check` + should point you at exactly the surfaces you still need to change. Watch for the + opposite failure too: any surface that needed renaming but the audit did *not* + flag is a gap to close in `repo_audit`. +3. **Adapt.** Replace or delete the `activity-report` demo and relax the + demo-specific audits as the guide describes. Confirm you can remove the demo + without fighting the gates, and that nothing forces you to keep Oak-specific + content you do not want. +4. **Understand the release model from the docs alone.** Without asking anyone, + confirm from README "## Releases", `docs/dev-tooling.md`, and + [docs/repository-governance.md](repository-governance.md) what a new project + needs to release — and what to change if you do *not* have the Oak Semantic + Release Bot (an adopter outside Oak supplies their own GitHub App + secrets, or + a simpler trigger). If publishing to PyPI, also read + [docs/publishing-to-pypi.md](publishing-to-pypi.md). +5. **First green PR and release.** Open a PR on the renamed repo, let it merge, and + confirm CI is green and a release is cut without manual intervention. + +## Acceptance checklist + +- [ ] A cold `check` passes on a fresh clone with no manual fix-ups. +- [ ] After the rename, `check` is green and `repo_audit` passes. +- [ ] The audit flagged every surface that needed renaming (no silent misses). +- [ ] The demo was cleanly replaceable or removable. +- [ ] The release model was understandable from the docs alone. +- [ ] A first release was cut from a PR merge without manual steps. + +## Friction log + +Record every snag, surprise, or "this felt heavier than a template should be": + +- Replace this line with real entries as you hit them. + +For each entry, decide one of: **trim** (remove the rigor), **document** (add a +note to the rename guide or `dev-tooling.md`), or **accept** (it is proportionate; +leave it). Heaviness with no proportionate value is a signal to simplify — the +template's identity is a *lightweight foundation*, not a feature product. diff --git a/docs/using-this-template.md b/docs/using-this-template.md index 1c20828..710cb86 100644 --- a/docs/using-this-template.md +++ b/docs/using-this-template.md @@ -52,12 +52,15 @@ in which case also rename the `src/oaknational/` directory and the 7. **Re-run `check` until green**, then commit on a branch and open a PR — the same workflow the template models. +To pressure-test your adoption (and the template itself), work through the +[first-adoption dry-run](first-adoption-dry-run.md) and log any friction. + ## What you are keeping The value of the template is the *infrastructure*, not the demo: the `src/` layout, the single `devtools` gate surface, the full blocking gate sequence (format, type-check, lint, markdown, spell-check, import-linter, dependency-hygiene, pip-audit, repo-audit, build, test, coverage), the -SHA-pinned CI with Dependabot, the release-PR automation, the secret-scanning -gate, and the `.agent/` working method. Those stay as-is; only the names and the +SHA-pinned CI with Dependabot, the continuous-release-on-merge automation, the +secret-scanning gate, and the `.agent/` working method. Those stay as-is; only the names and the demo change.