# 03-DESIGN

The authoritative specification. Implementation is built against what is written here.

## Two layers

| Folder | What it is |
|---|---|
| [`00-as-is/`](00-as-is/) | **The mesh that exists today.** Shipped behaviour, described as it is — including behaviour nobody would choose again. |
| [`01-to-be/`](01-to-be/) | **The mesh being built toward.** Every statement traceable to a record in [`02-DECISIONS/`](../02-DECISIONS/). |

They are never mixed. A statement about the future does not belong in an as-is document, and
an as-is document is never edited to describe an intention.

When a to-be design ships, it **does not move**. Its as-is counterpart is written or updated,
the to-be document's status becomes `implemented`, and both stand — one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning, which is
the expensive half.

## Frontmatter

Every design document (not the READMEs) carries:

```yaml
---
layer: as-is | to-be
status: designed | in-progress | implemented | abandoned
code: []                 # owning code repo(s), from 00-META/repos.md
updated: YYYY-MM-DD      # date of the last status change, not of text edits
decisions: []            # 02-DECISIONS/ records this document rests on
---
```

For an as-is document, `status: implemented` is the normal state — it describes something that
runs — and `code:` names where that implementation lives.

Status changes when **implementation state** changes, never because design text was edited. An
`implemented` claim must be defensible from the owning repository's main branch, not from
intent. If it cannot be checked, it is `in-progress`.

Cross-cutting views are generated from this frontmatter by the `hq-status` skill and never
written to disk.

## What belongs here

Functional analysis, architectural description, and specification — **prose and diagrams
only, no code**. A manifest field may be named; a manifest may not be pasted. A document
enters the to-be layer only after the decision behind it is recorded in [`02-DECISIONS/`](../02-DECISIONS/)
and the research that produced it is closed.

Subfolders are encouraged where a layer grows enough to need them.