Documentation

Docs are split by the question they answer (frostyard/core's four-category shape, core ADR-0025):

Directory	Question	Contents
adr/	Why did we choose this?	Repo-local Architecture Decision Records — immutable once accepted; superseded, never edited. Org-wide decisions live in frostyard/core — see org-adrs.md
design/	How does it fit together?	Living documents describing the current architecture
specs/	What exactly is the contract?	Precise, testable interface definitions
plans/	When/in what order do we build?	Roadmaps and phase plans; updated as work lands

Index

Decisions (ADRs)

Org-wide decisions binding this repo are listed in org-adrs.md.

• 0001 — ACMM conformance via canonical aliases — one canonical file per criterion behind committed relative symlinks (the alias registry), real trees for directory criteria, the docs-integrity gate, and the CI, release, and agent-governance surfaces added with it

Design

• Overview — purpose, architecture, key patterns, configuration, downstream consumers (the entry-point doc)
• Quality loop — declare → review → gate → learn → observe, wired to ci.yml, the docs gate, .memory/, and the release path (docs/quality.md is its alias)

Specs

• Reporter package — the Reporter interface, ProgressEvent JSON Lines format, and exact per-implementation output formatting
• PR review rubric — the checklist every review applies, rows = the repo's verifiable gates (docs/review-rubric.md is its alias)
• PR acceptance metric — the monthly acceptance-rate definition and rules (docs/metrics.md is its alias)

Plans

Shipped work; kept for the decision context they carry:

• clix design and clix implementation — the CLI convenience module built on this package, shipped as frostyard/clix
• Reporter extraction design and implementation plan — extracting reporter from nbc into this module
• Reporter examples design and implementation plan — the _examples/ programs

Conventions

• New docs start from their category's TEMPLATE.md (in each directory).
• New decision → new ADR with the next number; if it reverses an old one, mark the old one Superseded by NNNN rather than editing it. Decisions that bind more than this repo become ADRs in frostyard/core plus a line in org-adrs.md.
• Design docs are updated in place to always reflect reality.
• Specs change only alongside the code that implements them.
• Cross-links between categories are mandatory in both directions.
• Adding a doc means adding it to the index above; node scripts/check-docs.mjs (CI's docs-gate job) fails on an unindexed doc, a dead relative link, or a broken alias.
• Conformance aliases (docs/metrics.md, docs/review-rubric.md, docs/quality.md — ADR-0001) are not docs: never index or edit them; edit their targets.