# Process — overview

How work moves through hal-hq, and who may do what. Every other document in this folder is a
playbook: trigger, who runs it, steps, outputs. Engineers and agents follow the same
playbooks; agents must not act outside them.

## The audiences

| Audience | Contract |
|---|---|
| **Engineers** | Read and write everything. hal-hq is the single source of truth for mission, research, design, decisions and issue diagnosis. |
| **Agents** | The same rights as engineers, exercised through these playbooks. |
| **Anyone else** | This repository is public and written for them, but it is not a support channel. Nothing here identifies the mesh it describes. |

## The knowledge flow

```
idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIGN/01-to-be ──► built (code repo)
 │            │                                      │
 │            │                                      └─► 03-DESIGN/00-as-is once shipped
 │            └────► abandoned (recorded, kept)
 └─(small/obvious, decision recorded in DECISIONS.md)────► 03-DESIGN directly

symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment

how-we-build.md ──► constitution sync ──► knowledge base ──► injected into design meetings
```

## The two design layers

`03-DESIGN` holds two layers that are never mixed:

| Layer | What it is | Changes when |
|---|---|---|
| `00-as-is/` | The mesh that exists today. Describes shipped behaviour, including behaviour nobody would choose again. | Something ships, or an as-is claim is found to be wrong. |
| `01-to-be/` | The mesh being built toward. Every statement traceable to a record in `02-DECISIONS/`. | A decision is taken or amended. |

A to-be document that ships does not move. Its as-is counterpart is written or updated, the
to-be document's frontmatter goes to `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.

## The playbooks

| # | Playbook | Trigger |
|---|---|---|
| [01](01-research.md) | Research | An idea worth investigating before committing to design |
| [02](02-graduation.md) | Graduation & design change | Research concludes, or a design must change |
| [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown |
| [04](04-build-handoff.md) | Build handoff | A design is ready to be built |
| [05](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces |

## Status lives in frontmatter

Research overviews, design docs, issue reports and decision records each carry their status as
YAML frontmatter (schemas in the section READMEs and playbooks). There are **no central status
files**. `DECISIONS.md` is a ledger of decisions as they were taken — an index and a home for
decisions too small to warrant a record — and is explicitly *not* a status board. Cross-cutting
views are generated on demand by the `hal-status` skill and never written to disk.