> ## Documentation Index
> Fetch the complete documentation index at: https://dev.haico.gr/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Decision Records

> Why HAI-Co² keeps ADRs, how they are recorded, the status lifecycle, and the index of accepted decisions.

This section records the load-bearing architectural decisions behind HAI-Co². Each ADR is a
short [MADR](https://adr.github.io/madr/)-style record that captures **one decision**: why it
was made, what was chosen, and the consequences.

## Why we keep ADRs

* **Audit trail.** A year from now, someone will ask *"why did we pick X over Y?"*, and the answer
  lives next to the code instead of in chat history.
* **Onboarding.** A new contributor can read this section and understand the project's structural
  choices without reading every PR.

## Status lifecycle

| Status                 | Meaning                                                      |
| ---------------------- | ------------------------------------------------------------ |
| `proposed`             | Drafted in a PR; not yet merged or acted on.                 |
| `accepted`             | Merged and in effect. Default state for live ADRs.           |
| `deprecated`           | Superseded by changing circumstances; not directly replaced. |
| `superseded by NNNN-…` | Overridden by a newer ADR.                                   |

**Never edit an accepted ADR's decision.** To change direction, open a *new* ADR, summarise what
changed, and mark the old one `superseded by NNNN-…`. The old record stays intact as history.

## Index

| #                                                                         | Decision                                                          |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [0000](/docs/adr/0000-record-architecture-decisions)                           | Record architecture decisions                                     |
| [0001](/docs/adr/0001-two-branch-model)                                        | Two-branch model with tag-driven releases                         |
| [0002](/docs/adr/0002-dual-development-pathways)                               | Dual development pathways: traditional + AI-assisted              |
| [0003](/docs/adr/0003-conversation-branching-via-new-thread-and-state-seeding) | Branch conversations as new threads seeded via checkpointer state |
| [0004](/docs/adr/0004-hierarchical-plan-and-objective)                         | Depth-ordered plan tree + per-turn editable Objective             |
| [0005](/docs/adr/0005-user-feedback-frame)                                     | One turn-anchored feedback table with a frontend-owned instrument |
| [0006](/docs/adr/0006-programmatic-api-access)                                 | Authenticate programmatic API clients with personal access tokens |

When writing a new ADR, copy the [template](/docs/adr/template) and give it the next 4-digit number.