brain/docs/adr/ADR-000-adr-process.md

ADR-000 Adopt the ADR process and decision-store boundaries

Status

Accepted, 2026-05-17.

Context

Лидерра already records open product, business, and legal questions in the docs/Открытые_вопросы_v8_3.md registry (identifiers Б-, CTO-, Ю-, Диз-, DO-, OPEN-), each closed only by an explicit owner decision.

Integrating the adr-kit plugin adds a second store, docs/adr/, and the mermaid skill adds a third, docs/architecture/. Without explicit boundaries the three overlap, and a reader cannot tell where a given decision belongs. This ADR is the first written under the new process; it fixes the boundaries so ADR-001 onward have a clear home.

Decision

• docs/adr/ holds Architecture Decision Records — a technical or architectural decision that has already been made: stack choice, structural boundary, data-layer strategy, cross-cutting pattern. One file per decision, named ADR-NNN-kebab-title.md, following the seven-section adr-kit template.
• docs/architecture/ holds diagrams and models (C4, system context), generated with the mermaid skill. Visual, not normative; an ADR may reference a diagram there.
• The docs/Открытые_вопросы registry continues to track unresolved product, business, and legal questions. It is not machine-enforced.
• A registry question that resolves into a technical choice may graduate into an ADR; the registry entry is then closed by the normal owner process.
• An ADR may carry a machine-readable ## Enforcement block; adr-judge applies it to staged diffs at commit time (wired as a lefthook job). Enforcement rules target architecture-level constraints only — they do not duplicate larastan, eslint, or squawk rules.

Alternatives Considered

• Keep every decision in the Открытые_вопросы registry. Rejected: the registry is designed for open questions awaiting a decision, not for recording closed technical choices, and it has no enforcement mechanism.
• Record architecture decisions inside CLAUDE.md. Rejected: CLAUDE.md is the operational map, edited only through the claude-md-management plugin (CLAUDE.md §5 п.10), and would grow without bound if it absorbed every decision rationale.

Consequences

Positive:

• A reader can locate any decision by class: open question, closed decision, or diagram.
• Architecture decisions become version-controlled, reviewable, and — where an Enforcement block exists — machine-checked at commit time.

Negative:

• Three stores must be kept disjoint; a contributor has to know the boundary rule above before adding to any of them.
• An ADR superseded by a later decision must be marked Superseded by ADR-MMM rather than edited in place — process discipline the team has to follow.

Related Decisions

• ADR-001 — first technical ADR written under this process.
• ADR-002 — first data-layer ADR written under this process.

References

• docs/superpowers/plans/2026-05-17-a6-architecture-tooling-integration.md — the integration plan that introduced docs/adr/.
• docs/Открытые_вопросы_v8_3.md — the open-questions registry.
• .claude/adr-kit-guide.md — the adr-kit authoring guide.