diff --git a/CHANGELOG.md b/CHANGELOG.md index 01a5520..c27a3ba 100644 --- 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 index b67a541..4e86a35 100644 --- 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 new file mode 100644 index 0000000..d7e2e9d --- /dev/null +++ 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 index 46b7962..fdbe424 100644 --- 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 index 81e2667..9de1f71 100644 --- 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 index 953ed3d..4a39507 100644 --- a/templates/methodology.mdc +++ b/templates/methodology.mdc @@ -45,6 +45,7 @@ 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. @@ -52,7 +53,7 @@ skip the ceremony — a good commit message is enough. - **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