ADR-023: Method docs live beside the tree, not inside it


Status	Accepted; reference semantics revised by ADR-025 - the manual is read at latest (`main`), the pin records the state a repo last aligned to
Date	2026-07-29
Author	Łukasz Bodurka
Tags	structure, repo-layout, distribution, reference

Context

The shipped tree promised to be "the client repo at day zero", yet it carried documents no adopted repo has a reason to own: the adoption checkmap describes how a repo gets ON the standard (a process the client has, by definition, finished), the repo assessment is a procedure the transition agent runs from a checkout of this repo, and the taxonomy and decision checklist were already adapt: reference - "do not copy" - while physically sitting in the copyable tree. Worse, the reference class was internally contradictory: reference entries carried required: true and self-verify checked file existence in the client repo, mechanically forcing a copy of the thing the class says is never copied. Every copied method doc also drifts on every standard revision - the exact failure ADR-004 kills for decision records.

Options considered

A - Reference-in-tree. Flip the method docs to adapt: reference and leave them in the tree. Minimal churn, but the tree keeps lying about being the client layout, and the reference-but-shipped ambiguity grows instead of dying.
B - Method docs move out of the tree (chosen). The tree becomes literally what a client repo looks like; the method manual lives beside it and reaches clients by reference at the pinned version.
C - Keep copying. Every client carries method docs that go stale on each revision. Rejected on ADR-004's own logic.

Decision

Option B. Concretely:

The standard's method manual lives at docs/method/: the adoption checkmap, the repo assessment, the taxonomy, the decision checklist, ways of working, and the changelog process. It is versioned with the standard and rendered on the docs site from the same source.
The shipped tree carries only two kinds of documents: client-authored artifacts (PRODUCT, ARCHITECTURE, PRINCIPLES, personas, backlog, records, ideas, journeys, research, runbooks, specs, conventions - shells and merge-content the client owns) and operating manuals for shipped tools (docs/self-verify.md beside the verifier, specs/enforcement.md beside the guards).
Clients adopt the method manual by reference at the pinned version - the ADR-004 mechanism, extended from decision records to method docs. The manifest carries them in a references section (id, path, purpose, rule); self-verify notes them and never checks for files, and tree-check verifies each referenced path resolves in this repo.
The spec's taxonomy wording follows: the map of where knowledge lands is the standard's, adopted by reference - not a file every client must carry.

Consequences

Positive: the tree is exactly "what you get" - the reference-but-shipped class is gone by construction; method revisions reach every client instantly (they read the pin, not a copy); the manifest's reference semantics finally match ADR-004's words.
Negative: reading the method now needs the standards checkout or the pinned link (offline clients keep only their own artifacts); every existing link to the old tree paths had to be re-pointed once (this change); update-to-version deltas for references are metadata-only.

Revisit when

Offline clients - who lose access to the method manual without the standards checkout or a pinned link, the negative cost this record accepts - become a use case the project actually needs to support.