HSDD ADR: First-Class Architecture Decision Records

An ADR is the durable record of a decision that spans more than one node or must outlive the node that introduced it. Like a contract, it is a standalone, registry-tracked file, not prose buried in a node spec.

Core principle: An ADR has two parts with two jobs, exactly like a contract. The YAML frontmatter is machine-readable metadata projected into the registry. The body carries the decision. A consuming phase reads only the Decision and Consequences, never the Context or the alternatives behind them.

When to Use

• hsdd-spec proposed an ADR-{nnn} during decomposition and the human accepted it. Materialize it as a file here.
• A cross-cutting decision surfaces (auth provider, event bus, cache strategy, error model, data-residency rule) that affects multiple nodes or contracts.
• An ADR must change status: accept a proposal, or supersede/deprecate an old one.
• hsdd/adr/INDEX.md needs regenerating after a change.