<!-- project-knowledge rules v1 — canonical: https://mojzis.github.io/clauding/rules/v1/ -->
## Project knowledge

Knowledge lives in `docs/`: small, dense, linked, tagged markdown files.
Follow in every change.

**QA → `QA.md`** at the project root (and in each subproject).
Before claiming done:
1. Run the tier your change requires (see its selection table).
2. Compare the result against that tier's `expect`: collected count, skips, warnings, duration.
3. Run the relevant oracles. On diff vs main, explain every difference.
4. End with a QA report: what ran, how it compares to `expect`, oracles, what wasn't run and why.

These don't count as evidence: reasoning, tests you weakened, mocks of the unit under test,
new skips, "output exists". If you move a baseline on purpose, update `expect` in the same commit.
You may add oracles as `status: proposed`. Only a human confirms them.

**Writing: `docs/style.md`.** Read it before writing any doc. Summary: dense, no filler,
diagrams and schemas over prose.

**Current state → `docs/architecture.md`.**
How the system is *now*: components, data flow, boundaries, invariants.
It's a living doc: keep it true. No history in it.

**Decisions → `docs/adr/NNNN-slug.md`.**
ADRs record changes from the architecture baseline onward. Write one when choosing
between real alternatives, adding a dependency, or changing a public interface or
data shape. Accepting an ADR means updating `architecture.md` in the same change.
Never rewrite an accepted ADR. Supersede it and link both ways.

**Papercuts → `docs/papercuts/slug.md`.**
Anything that slowed you or the human down: a confusing error, a flaky step,
a missing script, a misleading doc. Log it when you hit it. Fix inline only if trivial.

**Small files.** One concept per file, ~<150 lines. Split rather than grow.
Link related files relatively. A file nothing links to is a smell.

**Frontmatter on every doc:**
```yaml
---
title: Invoice computation
tags: [billing, domain]
code: [src/pkg/billing.py::compute_invoice, src/pkg/io/]
---
```

**Tags** only from `docs/tags.md`. If none fits, add one there in the same change.

**Freshness.** Docs point at code via `code:`, never the reverse.
If you change or move anything listed in some doc's `code:`, update that doc in the same commit.
Before a task: find docs whose `tags`/`code` touch the area, and read their open papercuts.