vpciii · vpciii · Jun 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,30 @@ See [ADR 0009](./adr/0009-methodology-as-versioned-dependency.md).
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-06-21
+
+### Added
+
+- **§12 Deterministic onboarding** — a substantial project bootstraps with
+  one documented, reproducible command; "works on my machine" is a defect;
+  the tool (Make / devcontainer / Nix / script) is a per-project choice, not
+  a mandate. The one genuinely-new idea with no existing home (running-system
+  determinism is §6/§10; the developer's entry path was not stated). The
+  methodology-consistent answer to PR #22's six-practice expansion, which an
+  adversarial review BLOCKed for duplicating ADR 0014/0020 (violating ADR
+  0022), contradicting the no-premature-tooling exclusion, and inverting
+  scale-to-work. (ADR 0023) *Adoption: reference-only; optionally add a
+  one-command setup where a substantial project lacks one.*
+
+### Changed
+
+- **"Automate what is checkable" sharpened** — names formatting/style among
+  the machine-enforced checks and adds the review principle: if a machine can
+  settle it, human review spends its attention on behavior, intent, and the
+  artifacts, not style (folds in the useful core of PR #22's automated-gates /
+  code-review ideas without a new practice). Summaries synced (ADR 0018).
+  (ADR 0023) *Adoption: reference-only.*
+
 ## [0.11.0] - 2026-06-20
 
 ### Added
@@ -292,7 +316,8 @@ See [ADR 0009](./adr/0009-methodology-as-versioned-dependency.md).
 Decisions made before this changelog are recorded in git history and in
 `adr/0001`–`adr/0005`.
 
-[Unreleased]: https://github.com/vpciii/methodology/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/vpciii/methodology/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/vpciii/methodology/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/vpciii/methodology/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/vpciii/methodology/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/vpciii/methodology/compare/v0.8.0...v0.9.0

diff --git a/README.md b/README.md
@@ -23,7 +23,7 @@ to your shell profile for terminal use.
 
 | Path | What |
 |---|---|
-| `methodology.md` | The canonical development methodology (11 practices + the reasoning + a decision guide). |
+| `methodology.md` | The canonical development methodology (12 practices + the reasoning + a decision guide). |
 | `planning.md` | The planning methodology — the pre-spec phase (problem framing → betting), sibling to `methodology.md`. Converges to a `spec.md`. (ADR 0010) |
 | `adopting.md` | Bringing an **existing** codebase onto the methodology — the forward-only bootstrap path. (ADR 0012) |
 | `CHANGELOG.md` | Human-facing record of changes to the methodology, under SemVer (ADR 0009). |

diff --git a/adr/0023-incorporate-delivery-ideas-judgment-scaled.md b/adr/0023-incorporate-delivery-ideas-judgment-scaled.md
@@ -0,0 +1,112 @@
+# ADR 0023: Incorporate modern-delivery ideas, judgment-scaled (counter to PR #22)
+
+- **Status:** Proposed
+- **Date:** 2026-06-21
+- **Deciders:** vpc
+
+> This is the methodology-consistent **alternative** to PR #22, which
+> proposed six new numbered practices and was BLOCKed by an adversarial
+> review (`docs/reviews/pr22_adversarial_review.md`). Accept one or the
+> other, not both.
+
+## Context
+
+PR #22 proposed adding six numbered practices — deterministic environments,
+automated quality gates, continuous deployment, continuous refactoring, code
+review culture, and documentation-as-code — and an ADR mandating them as
+"non-negotiable standards."
+
+A cross-model adversarial review (round 8 of the trial,
+`docs/reviews/pr22_adversarial_review.md`) returned **BLOCK**, and the
+findings hold:
+
+- **Three duplicate existing practices/ADRs.** Continuous refactoring is
+  already the decision-guide row + ADR 0014; documentation-as-code is already
+  the "Keep the artifacts honest" same-PR rule + ADR 0020; code-review
+  substance is already ADR 0015. Re-stating them as new practices creates
+  second homes for the same rules — the hazard ADR 0022 names, one ADR after
+  adopting it.
+- **Two contradict standing exclusions.** Naming formatters and mandating a
+  CI/CD provider globally violates "No premature tech-stack or tooling
+  commitments"; mandatory continuous deployment imports the heavyweight
+  delivery machinery the "no formal SRE/ITIL" exclusion keeps out, and it has
+  no deployable-service scoping (§6 has one), so it breaks on libraries,
+  CLIs, and this docs repo.
+- **The framing inverts the methodology's stance** — "non-negotiable" against
+  "scale the ceremony / apply judgment."
+
+But the *underlying ideas* have merit. The question this ADR answers is: what
+is genuinely new and durable enough to add, and where does it belong?
+
+## Decision
+
+**1. Add exactly one new practice — §12 Deterministic onboarding** —
+tool-agnostic and judgment-scaled: a substantial project bootstraps with one
+documented, reproducible command; "works on my machine" is a defect; the tool
+(Make / devcontainer / Nix / script) is a per-project choice, not a mandate.
+This is the one idea from PR #22 with no existing home — the running system's
+determinism is covered (§6 config-in-env, §10 lockfiles) but the *developer's
+entry path* is not.
+
+**2. Refine the existing "Automate what is checkable" rule** to fold in the
+useful nugget of PR #22's §13/§16: formatting/style is machine-enforced, and
+*if a machine can catch it, human review shouldn't spend attention on it* —
+review goes to behavior, intent, and the artifacts (ADR 0015). This is a
+sharpening of an existing rule, not a new practice.
+
+**3. Add nothing else.** Continuous refactoring (ADR 0014), documentation-as-
+code (ADR 0020 + same-PR rule), and code-review substance (ADR 0015) are
+already covered — re-adding them would violate ADR 0022. Continuous
+deployment stays a per-project deployment/tooling decision (the standing
+exclusion) and is already implied by §4 (main always shippable) + §11
+(reversible); it does not become a global practice.
+
+**4. Keep the document self-consistent in the same PR** (what PR #22 missed):
+update the `§1–§11` → `§1–§12` references and the README practice count, and
+sync the `global-CLAUDE.md` / `methodology.mdc` summaries (ADR 0018).
+
+## Alternatives considered
+
+- **PR #22 as written** (six mandated practices) — rejected per the
+  adversarial review: duplication (ADR 0022), tooling-commitment and
+  lightweight-ops contradictions, missing CD scoping, scale-to-work
+  inversion, and self-inconsistency.
+- **Status quo / PR #22's own "Option B"** — partially adopted: most of the
+  six *is* already covered, so the bar for a *new* practice is "a genuine,
+  durable, tool-agnostic gap." Only deterministic onboarding clears it.
+- **Fold deterministic onboarding into §6 or §10** instead of a new practice
+  — considered; rejected because the developer entry path is distinct from
+  running-system parity (§6) and build reproducibility (§10), and neither
+  currently states it. A short dedicated practice is clearer than stretching
+  an existing one.
+
+## Consequences
+
+- The methodology gains one tool-agnostic, judgment-scaled practice (12
+  total) and a sharper automate-what's-checkable rule — no duplication, no
+  tooling mandate.
+- The genuinely-good ideas from PR #22 are captured where they belong, and
+  the already-covered ones are explicitly confirmed as present (reducing the
+  temptation to re-add them).
+- The document stays self-consistent (references + summaries updated in this
+  PR), unlike PR #22.
+
+## Adoption impact
+
+*Reference-only* for the principle. *Per-project (optional):* a substantial
+project that lacks a one-command setup adds one; the tool choice, if
+non-trivial, is its own project ADR. Forward-only — no backfill.
+
+## References
+
+- `docs/reviews/pr22_adversarial_review.md` (the BLOCK this answers).
+- ADR 0014 (refactoring already in the decision guide), ADR 0020
+  (user-facing docs ride along), ADR 0015 (review checklist), ADR 0022
+  (single source of truth), ADR 0018 (summaries change in the same PR).
+- `methodology.md` §4, §6, §10, §11; DORA / Accelerate (Forsgren et al.,
+  2018).
+
+---
+
+> Following the format proposed by Michael Nygard in
+> [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions).
diff --git a/methodology.md b/methodology.md
@@ -56,7 +56,7 @@ both.
 
 To get oriented in any project, in order:
 
-1. **This document** — the practices (§1–§11) and why they exist.
+1. **This document** — the practices (§1–§12) and why they exist.
 2. The project's **`docs/architecture.md`** — the current shape of the
    system at a glance (components, boundaries, data stores, external
    dependencies). It tells you *how the system is now*; the ADRs tell
@@ -152,9 +152,11 @@ consistent diff (see ADR 0008):
   honest by the same-PR rule, not equality (ADR 0022).
 - **ADRs are append-only** — supersede, never rewrite history.
 - **Automate what is checkable.** Anything a machine can verify —
-  tests, type-checks, lint, commit-message format, spec-criterion
-  coverage (§5) — is enforced in CI, not left to memory or review
-  diligence.
+  tests, type-checks, lint, formatting/style, commit-message format,
+  spec-criterion coverage (§5) — is enforced in CI, not left to memory
+  or review diligence. **If a machine can settle it, human review should
+  not spend attention on it:** style and formatting are the tool's job,
+  so review goes to behavior, intent, and the artifacts (ADR 0015).
 
 ---
 
@@ -457,6 +459,35 @@ undo.
 Why this lasts: cheap, fast recovery is what makes continuous delivery
 viable. The principle is independent of any flag system or platform.
 
+### 12. Deterministic onboarding
+
+A substantial project bootstraps locally with **one documented,
+reproducible command** — the same inputs produce the same working
+environment for any contributor, human or agent. The point is a
+known-good entry path, not a particular tool.
+
+- **One command, written down.** `make setup`, `bin/setup`, a
+  devcontainer, a Nix flake — the mechanism is a project tooling choice
+  (recorded where the project records such choices; a non-trivial one is
+  its own ADR, §1, §10). The *principle* is that onboarding is one
+  reproducible step, not a tribal-knowledge checklist.
+- **"Works on my machine" is a defect.** If the setup path fails or
+  depends on undocumented global state, the onboarding is broken and is
+  fixed like any other defect — not worked around per person.
+- **Scale to the work.** A throwaway script needs none of this; it earns
+  its keep on work someone — a teammate, a future you, an agent — will
+  set up again.
+
+- Reference: the [DORA](https://dora.dev/) / *Accelerate* research
+  (Forsgren et al., 2018) ties low-friction environments to delivery
+  performance.
+- Lives in: the project's setup command + a short note in `README.md`.
+
+Why this lasts: reproducible builds (§10) and config-in-the-environment
+(§6) already make the *running* system deterministic; this extends the
+same determinism to the *developer's* entry point — independent of any
+specific environment manager.
+
 ---
 
 ## The artifacts as a durable semantic interface

diff --git a/templates/global-CLAUDE.md b/templates/global-CLAUDE.md
@@ -50,6 +50,10 @@ precedence over this file. An accepted ADR beats both.
   `$METHODOLOGY_HOME/templates/adr/_template.md`.
 - **Small PRs, trunk-based.** Short branches to `main`; split past ~300
   lines of diff.
+- **Deterministic onboarding.** A substantial project bootstraps with one
+  documented, reproducible command; "works on my machine" is a defect.
+  The tool (Make / devcontainer / Nix) is a per-project choice, not a
+  mandate.
 - **Reversible by default.** Prefer flags / expand-contract migrations
   / backward-compatible APIs. Every non-trivial change has a known undo;
   genuinely irreversible actions are called out and decided with an ADR.
@@ -75,8 +79,9 @@ precedence over this file. An accepted ADR beats both.
   hand-sync two *verbatim* copies by memory — generate or equality-check
   them; curated summaries and per-project template copies are derivatives
   kept honest by the same-PR rule); ADRs are append-only (supersede,
-  never edit); whatever is machine-checkable is enforced in CI, not left
-  to memory.
+  never edit); whatever is machine-checkable (tests, types, lint,
+  formatting) is enforced in CI, not left to memory — and if a machine
+  settles it, review spends its attention on behavior, not style.
 - **Operational feedback.** An incident produces ≥1 of: a now-passing
   regression test, a new/updated ADR, or a spec update.
 

diff --git a/templates/methodology.mdc b/templates/methodology.mdc
@@ -45,14 +45,15 @@ skip the ceremony — a good commit message is enough.
 - **Spec-first for non-trivial work:** `spec.md` → `plan.md` → `tasks.md`, sign-off between stages.
 - **Decisions get ADRs** (expensive to reverse / multi-component / future-constraining).
 - **Small PRs, trunk-based;** split past ~300 lines of diff.
+- **Deterministic onboarding:** one documented, reproducible setup command; "works on my machine" is a defect; the tool is a per-project choice, not a mandate.
 - **Reversible by default:** flags / expand-contract migrations / backward-compatible APIs; call out and ADR anything irreversible.
 - **Tests as specification:** new behavior ships with tests; fixes ship a regression test (fails before, passes after — failing run cited in the PR). Test behavior, not implementation. Spec success criteria carry stable ids traced to tests, CI-checked for coverage.
 - **Current-state & spec freeze:** keep `docs/architecture.md` honest (the system's shape *now*) in the same PR as any structural change; a spec freezes at `Implemented` (a historical record) — later contradictions go to a test, a new spec, or an ADR.
 - **Security & secrets:** secrets never in the repo (env / secret manager); rotate leaks; trust boundaries & authz are ADR-worthy; security bugs ship a regression test.
 - **Dependencies are decisions:** weigh maintenance/license/supply-chain; commit lockfiles; ADR non-trivial deps.
 - **Ubiquitous language:** use the project's domain terms exactly.
 - **Conventional Commits + SemVer** (`feat: fix: docs: refactor: test: chore: perf: build: ci:`; `!` for breaking).
-- **Keep artifacts honest:** docs — user-facing docs included — change in the same PR as the behavior; a fact lives in one place (don't hand-sync two verbatim copies by memory — generate or equality-check; curated summaries and per-project template copies are derivatives kept honest by the same-PR rule); ADRs append-only; enforce machine-checkable rules in CI.
+- **Keep artifacts honest:** docs — user-facing docs included — change in the same PR as the behavior; a fact lives in one place (don't hand-sync two verbatim copies by memory — generate or equality-check; curated summaries and per-project template copies are derivatives kept honest by the same-PR rule); ADRs append-only; enforce machine-checkable rules (tests, types, lint, formatting) in CI — and if a machine settles it, review spends attention on behavior, not style.
 
 ## Author of record