docs: one-command onboarding bullet in §10 (0.12.0)

[vpciii]

The one idea worth keeping from the (withdrawn) PR #22/#24 expansion exchange, captured at the right scale.

Change: a single sub-bullet under §10 (Dependencies are decisions), next to "Lockfiles are committed / Builds are reproducible":

One-command onboarding. A substantial project bootstraps from a clone to a working environment with a single documented, reproducible command (make setup, a devcontainer, a Nix flake — the tool is the project's choice). Reproducible builds aren't reproducible if the setup isn't: "works on my machine" is a defect in the onboarding path.

Deliberately minimal — not a new numbered practice, no ADR, no adversarial review. It's a clarifying point that's neither expensive-to-reverse nor future-constraining (scale-to-work). The developer entry point is the one thing §6/§10's reproducible-build guidance genuinely left unsaid.

Cuts 0.12.0. No summary/decision-guide change (it's a sub-bullet below summary altitude). This is the last methodology change for now — calling it done at this scope and revisiting after it's been in practice longer.

🤖 Generated with Claude Code

[claude]

Claude finished @vpciii's task in 2m 15s —— View job

---

Review: one-command onboarding bullet (§10)

• Read governing artifacts (methodology.md §10, ADR 0003, "Changing this document", CHANGELOG conventions, ADR 0018 summary rule)
• Review the diff against this project's own standards
• Post findings

---

The change reads well and the content is sound — and it's notably careful to stay consistent with ADR 0003, which explicitly rejected a tooling mandate for §10. The "make setup / devcontainer / Nix flake — the project's choice" phrasing honors that ("weigh and record, not a particular tool"). Conventional-commit subject ✓, CHANGELOG updated in the same PR with the correct *Adoption: reference-only* impact line and version-link footer ✓. The decision to leave templates/global-CLAUDE.md untouched is defensible: the summary's §10 line enumerates only weigh/lockfiles/ADR, so a fourth sub-bullet is genuinely below summary altitude (ADR 0018 triggers only when summarized content changes).

One judgment call worth surfacing before merge — the ADR question the PR preemptively waves off:

§10's practice list is defined by an Accepted ADR; this adds a fourth bullet without one. ADR 0003 (adr/0003-dependencies-are-decisions.md:19-32) enumerates §10 as exactly three bullets — adding-is-a-decision, lockfiles-committed, updates-deliberate. This PR inserts a fourth normative bullet (methodology.md:426-431) that asserts a new requirement ("a substantial project bootstraps from a clone … with a single … command"; "works on my machine is a defect"). The methodology's own governance is explicit on this:

"If a practice changes, update the relevant document and record the change in an ADR … Each such ADR declares an adoption impact." (methodology.md:531-537)
"If you find yourself arguing for or against a practice that isn't listed here, that is a sign you need an ADR, not a longer methodology doc." (methodology.md:556-559)

The PR body is an argument for a practice (it cites the withdrawn #22/#24 exchange) — which is precisely the signal that last line names. And the precedent cuts the same way: comparably-scoped additions in this repo got ADRs — ADR 0014 (refactoring into the decision guide), ADR 0016 (postmortems get a home). A new §10 bullet is in the same weight class.

The scale-to-work / reversible-by-default defense is real — a docs sub-bullet is cheap to reverse, and I don't think this is a blocker. But the tension is genuine: either this is a practice change (→ a short ADR, or a one-line amendment to ADR 0003's "Decision" list to keep §10 traceable to its ADR), or the methodology's "record the change in an ADR" rule wants a small carve-out for sub-bullet clarifications. Right now §10 has a normative bullet that no ADR records, which is the kind of doc/decision drift §1 exists to prevent.

Add a short ADR (or amend ADR 0003) for the §10 onboarding bullet →

Minor (non-blocking): the CHANGELOG entry's meta-narrative about the "(withdrawn) PR #22/#24 expansion exchange that cleared the bar" is more process-journal than consumer-facing changelog — the adoption-impact line is the part a consuming project needs. Trimming the backstory would tighten it, but it's stylistic.
· docs/one-command-onboarding-bullet