Architecture Decisions
Decisions are kept as ADRs under ../adr/, maintained per the path model with a canonical governance language (REQ-01-01-11-02).
| ADR | Decision | Status |
|---|---|---|
| ADR-0001 | AGENTS.md is the canonical agent instruction document; CLAUDE.md is a thin adapter; extension points carry no normative rules | accepted |
| ADR-0002 | Structurizr DSL is the C4 model source; embedded views are derived Mermaid | accepted |
| ADR-0003 | The verify loop is its own orchestrator component: sequencer over the stable command interface, never a checker | accepted |
| ADR-0004 | finalise lives in the Formatter & Finaliser — the only mutator of existing source documents, mechanical only, with an injected clock | accepted |
| ADR-0005 | Noun–verb command scheme; every analysis exists exactly once (coverage is trace coverage); report reserved for export products; verify as top-level exception |
accepted |
| ADR-0006 | Trace output is layered — canonical core graph, diagnostics projection, audit products — each with its own stability promise; schema_version in every JSON output |
accepted |
| ADR-0007 | One node identity rule: declared document ID, else repository-relative path; file as attribute everywhere; edges reference node ids |
accepted |
| ADR-0008 | Human-facing reports are assemblies of question units — one unit answers one named question; raw model dumps are machine artefacts, never reports | accepted |
| ADR-0009 | Documentation production policy: new documents are units discriminated by section-kind; code→doc links via the documented-by marker; one generator surface (report units); rustdoc as a gated layer; schema_version per interface |
accepted |
| ADR-0010 | Lifecycle vocabularies: declared states carry intent, computed states carry findings; per-nature vocabularies (stories draft→specified→in-implementation→done, requirements active/retired, prose draft→final via finalise), terminal retired; ADR decision-status stays orthogonal |
accepted |
| ADR-0011 | Configuration boundary: a value becomes configuration on double bookkeeping or legitimate per-repository variance, stays convention as tool identity, stability contract, or check substance; one source feeds engine and reference tools, defaults preserve the present | accepted |
| ADR-0012 | ID policy model: declared triples are the source of truth for relations, the ID is an opaque label; per-family patterns govern shape, uniqueness, and generation, named groups activate optional consistency checks; defaults reproduce the current shapes | accepted |
| ADR-0013 | Stitching model: include directives declare heading levels (absolute or relative), the assembler re-levels whole fragments; heading ownership is corpus policy; site splits cut the assembled outline, never fragment boundaries; PDF is always single-page; arqix:chapter retired |
accepted |
| ADR-0014 | MCP transport: mcp serve implements the required protocol subset directly over stdio (blocking JSON-RPC loop, serde_json), no SDK dependency; scripted-session tests own spec conformance; revisit trigger is a requirement beyond the subset (HTTP/SSE, resources, prompts) |
accepted |
| ADR-0015 | Marker freshness by git arithmetic: a marker is possibly-stale when its target requirement was committed after the marker's own file; exposed as trace freshness, informational in verify |
accepted |
| ADR-0016 | Architecture views are generated from workspace.dsl via a containerised renderer (Kroki) into committed SVGs with a regenerate-and-diff freshness gate; the in-process C4-Mermaid checker is withdrawn |
accepted |
| ADR-0017 | Process profiles and the layered ontology: rules stay code, their activation and binding become configuration, vocabulary becomes layered corpus data (reserved core, module vocabularies, project ontology) validated by an ONT meta-rule family; guarded lifecycle stays core, domain status is declared vocabulary | accepted |
| ADR-0018 | Evidence anchors and derived triples: a claim is a body marker above the supported block plus a derived-triples edge that fmt generates from it; position-bound attributes stay on the marker, the edge joins the validated graph; confidence is a declared vocabulary; only claim markers are lifted |
accepted |
Decision records predating the ADR directory live in the planning packages under docs/en/plans/ (ID scheme, canonical-owner model, atomicity, subject conventions).