diff --git a/CHANGELOG.md b/CHANGELOG.md index 01a5520..dba035a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,17 @@ See [ADR 0009](./adr/0009-methodology-as-versioned-dependency.md). ## [Unreleased] +### Added + +- **Expanded methodology with 6 new modern delivery practices** (ADR 0023): + - Deterministic Dev Environments (One-Command Onboarding) + - Automated Quality Gates (Strict linting/formatting in CI) + - Continuous Deployment (Zero-touch automated releases) + - Continuous Refactoring (The Boy Scout Rule) + - Code Review Culture (Blameless, behavior-focused) + - Documentation as Code (Treating docs like code) + - *Adoption impact:* Per-project action. Projects must verify they have a deterministic setup command, automated style checks in CI, and automated deployment pipelines. + ## [0.11.0] - 2026-06-20 ### Added diff --git a/adr/0023-expand-practices-for-modern-delivery.md b/adr/0023-expand-practices-for-modern-delivery.md new file mode 100644 index 0000000..2bc363e --- /dev/null +++ b/adr/0023-expand-practices-for-modern-delivery.md @@ -0,0 +1,42 @@ +# ADR 0023: Expand methodology with modern delivery practices + +- **Status:** Accepted +- **Date:** 2026-06-21 +- **Deciders:** vpciii, Antigravity + +## Context + +The current methodology provides a highly robust, tool-agnostic foundation for software engineering that works well for human-agent teams. It distills time-tested practices such as ADRs, Spec-first development, TDD, and Trunk-based development. + +However, during a review of the methodology against empirical DevOps research (such as DORA metrics) and friction points in day-to-day development, a few gaps emerged. Specifically, the methodology did not explicitly mandate deterministic local environments, completely automated linting/formatting, continuous deployment (CD), or explicit code review culture guidelines. While some of these were implicitly supported by Trunk-based development and Twelve-Factor guidelines, making them explicit numbered practices ensures they are treated as non-negotiable standards rather than optional enhancements. + +## Decision + +We will expand the methodology to include six additional core practices: +1. **Deterministic Dev Environments** (One-Command Onboarding) +2. **Automated Quality Gates** (Strict linting/formatting in CI) +3. **Continuous Deployment** (Zero-touch automated releases) +4. **Continuous Refactoring** (The Boy Scout Rule) +5. **Code Review Culture** (Blameless, behavior-focused, async-first) +6. **Documentation as Code** (Treating docs like code) + +## Alternatives considered + +- **Option A: Embed these into existing practices** — We considered expanding "Trunk-based development" to include Continuous Deployment and Code Review Culture, and expanding "Twelve-Factor" to cover Deterministic Environments. This was rejected because these concepts are distinct enough to warrant their own dedicated focus. Hiding them under other headings diminishes their importance. +- **Option B: Maintain the status quo** — Keep the list at 11 practices to prioritize brevity. Rejected because the lack of explicit guidance on local environments and CI/CD quality gates frequently leads to "works on my machine" issues and bikeshedding during code review. + +## Consequences + +- **Easier:** Onboarding new developers (and AI agents) becomes instantly deterministic. Code reviews become faster and less contentious because formatting and style are strictly automated. Tech debt is managed continuously. +- **Harder:** Initial project setup requires slightly more investment to configure DevContainers/Nix/Makefiles, CI pipelines for CD, and strict linters. +- **New constraints:** PRs cannot be merged if they fail style checks, and code must be left cleaner than it was found. + +## Adoption impact + +*Reference-only* for the methodology itself (arrives by reading `methodology.md`). +*Per-project action* required: Projects must verify they have a deterministic setup command, automated style checks in CI, and automated deployment pipelines to fully comply with the new practices. + +## References + +- [DORA Metrics / Accelerate (Forsgren et al.)](https://dora.dev/) +- [The Boy Scout Rule](https://deviq.com/principles/boy-scout-rule) diff --git a/docs/reviews/pr22_adversarial_review.md b/docs/reviews/pr22_adversarial_review.md new file mode 100644 index 0000000..c8894e1 --- /dev/null +++ b/docs/reviews/pr22_adversarial_review.md @@ -0,0 +1,59 @@ +# Adversarial Review: Methodology PR #22 (ADR 0023) + +> Reversed-role run: Gemini / Antigravity authored; Claude (Opus 4.8) adversary. Reviewed cold against the existing methodology (§1–§11, the "What is intentionally not here" section, and ADRs 0014/0018/0020/0022). + +### 1. "Non-negotiable standards" contradicts the methodology's foundational scale-to-work philosophy + +* **Claim Refuted:** ADR 0023 Context — making these "explicit numbered practices ensures they are treated as **non-negotiable standards** rather than optional enhancements," and §12–§14 state them as universal "must." +* **Grounding:** `methodology.md` → "A note on practice vs. ceremony": "**Scale the ceremony to the work.** A one-off script, a throwaway experiment, or a five-minute fix does not need a spec and an ADR… Apply judgment." The entire document is framed around judgment, not non-negotiable mandates. +* **Defect:** The change inverts the methodology's core stance. Mandating DevContainers, CD pipelines, and CI style-gates as non-negotiable for *every* project directly contradicts "apply judgment / scale the ceremony." A throwaway script or a single-file library now nominally "must" have a deployment pipeline and a DevContainer to "fully comply" (ADR Adoption impact). This is the ceremony-for-its-own-sake the methodology explicitly warns against. + +### 2. Naming specific tools and mandating CI/CD violates "No premature tech-stack or tooling commitments" + +* **Claim Refuted:** §13 "Use tools like Prettier, Black, or GoFmt"; §14 "Merging to `main` triggers a pipeline that deploys to production"; ADR Adoption impact requiring "automated deployment pipelines." +* **Grounding:** `methodology.md` → "What is intentionally not here": "**No premature tech-stack or tooling commitments.** Each tooling choice — stack, security scanner, flag system, **CI provider** — gets an ADR in the project that makes it, when it is made, not before." And the preamble: "**document the artifact, not the tool.**" +* **Defect:** The existing 11 practices never mandate a tool — they name tools only as illustrative "today" instances with the durable principle separated out. These new practices bake tool categories and a CI/CD provider commitment into the *global* methodology, the exact coupling the document exists to prevent. The PR never reconciles §12–§14 with the standing "intentionally not here" section, leaving a direct internal contradiction. + +### 3. §14 Continuous Deployment has no deployable-service scoping and breaks for most project types + +* **Claim Refuted:** §14 — "`main` must not only be shippable, it should be deployed automatically… Merging to `main` triggers a pipeline that deploys to production," stated universally. +* **Grounding:** `methodology.md` §6 (Twelve-Factor) is explicitly scoped: "Applies to deployable services; **skip for libraries, CLIs, and one-off scripts.**" §8 keeps operational machinery "deliberately lightweight," and "What is intentionally not here" excludes "formal SRE / ITIL machinery." +* **Defect:** A large class of projects the methodology covers — libraries, CLIs, one-off tools, and *this very methodology repo* (a markdown/docs repo) — have nothing to "deploy to production." §14 provides no scoping clause analogous to §6's, so as written it is inapplicable-to-incoherent for those projects, and it imports precisely the heavyweight delivery machinery §8 / the exclusions deliberately keep out. + +### 4. §15 Continuous Refactoring duplicates ADR 0014 and the decision guide — a single-source-of-truth violation + +* **Claim Refuted:** §15 introduces "Continuous Refactoring / the Boy Scout Rule" as a new numbered practice. +* **Grounding:** Refactoring is *already* a first-class concept: the decision-guide row "Restructure code without changing behavior (refactor, tech-debt paydown) → no spec; keep the suite green; an ADR only if it closes off future options" (ADR 0014), resting on §5 and §11. And ADR 0022 (just adopted): "a fact lives in one place." +* **Defect:** §15 creates a *second* home for the refactoring rule without referencing ADR 0014 or the decision-guide row, and partially restates §5's "protected by tests." This is the hand-maintained duplication ADR 0022 was written to forbid — introduced one ADR later, against the methodology's freshest rule. + +### 5. §17 Documentation as Code duplicates "Keep the artifacts honest" and ADR 0020 + +* **Claim Refuted:** §17 — docs "live in the repository," go through "the same review process," and "a feature is not complete until its documentation is updated." +* **Grounding:** `methodology.md` → "Keep the artifacts honest": "**Docs change in the same PR as the behavior they describe**… User-facing documentation is bound the same way… (ADR 0020)." The artifact map already places docs in-repo. +* **Defect:** §17 is near-verbatim the existing same-PR docs rule plus ADR 0020, again with no cross-reference — a third instance of the ADR-0022 duplication hazard. It adds a numbered practice where a one-line pointer to the existing rule would do, inflating the document it claims to be improving. + +### 6. §16 Code Review Culture imports framework-flavored team-process vocabulary the methodology excludes + +* **Claim Refuted:** §16 — "async-first," "PR bottlenecks," "high team velocity and **psychological safety**," "Approve with suggestions — Do not block." +* **Grounding:** `methodology.md` → "What is intentionally not here": "**No agent personas or role-playing workflows.** They are framework-flavored." The document centers the **author-of-record** model ("AI assistants may draft; the human accepts") and is written for solo human + AI as much as teams. Review substance is already specified by ADR 0015 (spec conformance, test honesty, artifacts ride along). +* **Defect:** §16 grafts team-culture framing (velocity, psychological safety, async-first) onto a methodology that deliberately avoids framework-flavored process and often describes a single author of record — for whom "PR bottlenecks / team velocity" is inapplicable. "Approve with suggestions, don't block on trivia" also sits in unacknowledged tension with the substantive merge gate of ADR 0015; the practice neither cites nor reconciles it. + +### 7. The PR leaves the document internally inconsistent — stale self-references and un-synced summaries + +* **Claim Refuted:** Implicit claim that the expansion is complete and consistent (the PR changes only `methodology.md`, the ADR, and `CHANGELOG.md`). +* **Grounding:** After adding §12–§17, `methodology.md:59` still reads "the practices (**§1–§11**)" and `README.md:26` still reads "**11 practices**" — neither updated (README is not even in the changed-file set). Per ADR 0018, `templates/global-CLAUDE.md` and `templates/methodology.mdc` "change in the **same PR** as any change [they summarize]" — neither was touched. And "Keep the artifacts honest" forbids leaving a doc its own change makes wrong. +* **Defect:** The PR violates the methodology's own honesty rule *in the act of expanding the methodology*: it ships stale "11 practices / §1–§11" references and skips the same-PR summary sync ADR 0018 mandates. The expansion is not self-consistent. + +### 8. ADR marked "Accepted" on an unmerged PR, with a model listed as a decider + +* **Claim Refuted:** ADR header — "**Status:** Accepted" and "**Deciders:** vpciii, Antigravity," while PR #22 is open and unmerged. +* **Grounding:** `methodology.md` → "Author of record": "AI assistants may draft; **the human accepts.**" An accepted ADR is the output of human sign-off, recorded on merge — not a default the draft asserts about itself. +* **Defect:** A draft ADR pre-declaring its own status "Accepted" (and crediting a model as co-decider) inverts the author-of-record rule. The status should be `Proposed` until the human accepts; otherwise the append-only ADR log records an acceptance that never independently happened. + +*** + +### VERDICT: BLOCK + +The six practices encode genuinely good ideas (deterministic environments, automated gates, continuous refactoring, docs-as-code) — but as written they **misfit this methodology** at a structural level, and that is what a BLOCK is for. Three of them (§15, §17, and parts of §16) **duplicate existing practices and ADRs** (0014, 0020, the decision guide), violating the single-source-of-truth rule (ADR 0022) the project adopted one ADR earlier. Two of them (§13, §14) **directly contradict the standing "No premature tech-stack or tooling commitments" and lightweight-operations exclusions**, and §14 lacks the deployable-service scoping that would keep it from breaking on libraries, CLIs, and this very docs repo. The whole set is framed as "non-negotiable," inverting the methodology's foundational *scale-the-ceremony / apply-judgment* stance. Finally, the PR leaves the document **internally inconsistent** (stale "11 practices / §1–§11" references, un-synced ADR-0018 summaries) and the ADR pre-declares its own "Accepted" status against the author-of-record rule. + +**To resolve:** fold the non-duplicative, genuinely-new ideas (deterministic environments; automated style gates) into existing practices as *judgment-scaled, tool-agnostic* guidance rather than tool-named universal mandates; drop or down-convert §15/§17 to pointers to ADR 0014 / 0020; reconcile §16 with ADR 0015 and shed the team-velocity framing; add deployable-service scoping to any CD guidance; update the §1–§n self-references and the ADR-0018 summaries in the same PR; and set the ADR to `Proposed`. Equally valid is **Option B from the ADR (status quo)** — the methodology already covers most of this implicitly, and "apply judgment" was a feature, not a gap. diff --git a/methodology.md b/methodology.md index 46b7962..f83691e 100644 --- a/methodology.md +++ b/methodology.md @@ -457,6 +457,56 @@ 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 Dev Environments + +A project must be bootstrappable locally with a single, deterministic command (e.g., `bin/setup`, `make install`, or via DevContainers/Nix). Onboarding should take minutes, not days. +- **No unrecorded global state** — Avoid dependencies that require undocumented global installations. +- **"It works on my machine" is a bug** — If the setup command fails, the onboarding process itself is broken and must be fixed as a priority. + +Why this lasts: A zero-friction entry point is essential for both human contributors and AI agents. Frictionless onboarding supports high-velocity trunk-based development. + +### 13. Automated Quality Gates + +Formatting, linting, and static analysis must be completely automated, configured out-of-the-box, and enforced in CI. +- **Zero-configuration formatters** — Use tools like Prettier, Black, or GoFmt. +- **If a machine can catch it, a human shouldn't review it** — Code reviews should never involve debates over style, syntax, or formatting. +- **Enforced, not just suggested** — PRs cannot be merged if they fail style checks. + +Why this lasts: It eliminates bikeshedding, speeds up code review, and ensures codebase consistency regardless of the contributor (human or AI). + +### 14. Continuous Deployment (CD) + +Trunk-based development (§4) is made safe by automating the release process. `main` must not only be shippable, it should be deployed automatically. +- **Zero-touch automated releases** — Merging to `main` triggers a pipeline that deploys to production (or a staging equivalent). +- **Fast feedback** — Deployments must be fast and frequent to minimize the delta between code written and code running in production. + +Why this lasts: CD removes the fear of releasing, shrinks batch sizes, and forces the team to build robust testing (§5) and reversible changes (§11). + +### 15. Continuous Refactoring + +Refactoring is a continuous, daily habit, not a scheduled sprint task or a separate phase. Apply the "Boy Scout Rule" — always leave the code cleaner than you found it. +- **Protected by tests** — The robust executable specifications (§5) provide the safety net required to refactor aggressively. +- **Small, incremental improvements** — Pay down technical debt continuously rather than waiting for a massive rewrite. + +Why this lasts: Codebases naturally rot. Continuous refactoring ensures the architecture remains malleable and the code remains readable over time. + +### 16. Code Review Culture + +Code reviews should be fast, asynchronous-first, and blameless. The focus should be on architecture, intent, and verifiable behavior. +- **Review for behavior, not style** — Rely on the automated quality gates (§13) for formatting. +- **Assume positive intent** — Collaboration should be constructive. +- **Approve with suggestions** — Do not block a PR for trivial changes; use non-blocking suggestions or follow-up commits. + +Why this lasts: A healthy review culture prevents PR bottlenecks and maintains high team velocity and psychological safety. + +### 17. Documentation as Code + +Technical documentation is treated as a first-class citizen alongside code and tests. +- **Lives in the repository** — Runbooks, API specs, and usage guides live in the same repository as the code they describe. +- **Same review process** — Documentation changes go through the same PR and review process. A feature is not complete until its documentation is updated (§2). + +Why this lasts: Docs kept in separate wikis or external tools inevitably drift. Keeping them close to the code ensures they evolve together. + --- ## The artifacts as a durable semantic interface