> ## 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.md) | Record architecture decisions |
| [0001](/docs/adr/0001-two-branch-model.md) | Two-branch model with tag-driven releases |
| [0002](/docs/adr/0002-dual-development-pathways.md) | Dual development pathways: traditional + AI-assisted |
| [0003](/docs/adr/0003-conversation-branching-via-new-thread-and-state-seeding.md) | Branch conversations as new threads seeded via checkpointer state |
| [0004](/docs/adr/0004-hierarchical-plan-and-objective.md) | Depth-ordered plan tree + per-turn editable Objective |
| [0005](/docs/adr/0005-user-feedback-frame.md) | One turn-anchored feedback table with a frontend-owned instrument |
| [0006](/docs/adr/0006-programmatic-api-access.md) | Authenticate programmatic API clients with personal access tokens |
| [0007](/docs/adr/0007-build-identity-from-release-tag.md) | Stamp the build identity from the release tag and keep it apart from the API contract version |
| [0008](/docs/adr/0008-user-facing-release-notes.md) | Curated release notes are a committed file, announced on deploy |
| [0009](/docs/adr/0009-cluster-hosted-llm-experiments.md) | Cluster-hosted LLM experiments |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.