# docs/ — AGENTS.md

## Purpose

Human-readable documentation for the CORREX project: architecture decisions, module specs, QA run plans, schemas, epics, and design references. Not source of truth for build status — source of truth is git log + live code.

## Ownership

Maintained alongside the features they describe. Any agent shipping a significant feature must update or create the relevant doc.

## Local Contracts

- `architecture/` — stable, high-level architectural docs (context layers, event model, replay model, security boundaries).
- `decisions/` — ADRs (adr-NNNN-*.md). Append-only. Never delete or retroactively alter a decided ADR; write a superseding one instead.
- `qa/` — QA run plans (QA-*.md). Each maps to a shipped feature. `TEMPLATE.md` is the canonical shape. `ENV.md` describes the required live environment. `README.md` explains the QA process.
- `specs/` — feature specs by date-slug. Inputs for planned or in-flight work.
- `schemas/` — canonical JSON schemas for structured outputs (analysis, brief_echo, design, execution_plan, impl_plan). Shared across the router and validator.
- `epics/`, `modules/`, `diagrams/`, `design/`, `reviews/`, `visual/` — supporting reference material.

**⚠️ STALE / DO NOT TRUST FOR STATUS:**
- `docs/plans/` — gitignored. Contains old implementation plans. Never reflects current build state.
- `docs/future/` — gitignored. Speculative, may be outdated. Verify any claim against git log + live code.

## Work Guidance

- QA plans live in `qa/`. Use `qa/TEMPLATE.md` as the starting shape when creating a new one.
- ADRs go in `decisions/`. Follow the existing numbering sequence.
- Specs go in `specs/` under a `YYYY-MM-DD-<slug>/` directory.
- Never trust `docs/plans/` or `docs/future/` for feature status. Always verify against `git log` and live source.

## Verification

_None yet._

## Child DOX Index

No child AGENTS.md (leaf directory).