khosra/docs/README.md

# Doc map

Read the one you need. Do not read them all.

| Doc | Contains | Mutability |
|---|---|---|
| `architecture.md` | The six primitives, invariants, per-primitive STATUS | Only via an ADR |
| `state.md` | What exists now: inventory, earn-it counters, latent items | Every feature |
| `decisions.md` | ADR log — one entry per load-bearing choice | Append-only |
| `roadmap.md` | Arcs, earn-triggers, the core freeze point | When an arc completes |
| `content-model.md` | On-disk layout, frontmatter, post types, permalinks | When the disk format changes |
| `conventions.md` | Go style floor, package layout, perf and test rules | Rarely; via ADR if contested |
| `extensions.md` | Extension/plugin contract: target shape + earn gates | When earned or frozen |
| `exploration.md` | Catalog of possible future *engine features*, leaf/trunk verdicts | When a verdict is reached |
| `toolchain.md` | Versions and agent-tooling contracts this was built against | When you deliberately move a version |
| `theme-contract.md` | What the engine promises a theme; the only theme-facing obligation | When the contract is extended — additively only |

Two sibling folders sit **outside** `docs/` because they are storage, not working material:
`../ideas/` (parked ideas, any topic) and `../reference/` (durable facts from conversation). Write
there when asked to park something; open a file only when the human names it. Nothing sweeps them.

## Topic ownership — read before you assert

The inverse of the refresh triggers: those say what to update *after* changing code, this says what
to read *before* writing a rule — including when you are only writing an ADR or a comment about it.
Nearly always exactly one doc; if two seem to apply, the single-source rule is already broken and
that is the finding to report.

| About to assert something about… | Read first |
|---|---|
| plugins, extensions, features-as-packages, stage phases | `extensions.md` |
| a primitive, an invariant, or what is "earned" | `architecture.md` + counters in `state.md` |
| URL paths, permalinks, frontmatter, on-disk layout, post types | `content-model.md` (+ ADR-0008) |
| Go style, package layout, file/function size, test shape | `conventions.md` + `scripts/budgets.env` |
| a dependency | `scripts/allowed-deps.txt` + ADR-0007 |
| a budget or a gate | `scripts/budgets.env` + `scripts/verify.sh` |
| the untrusted boundary, comments, webmentions, form input | ADR-0003 + `extensions.md` |
| language, translation, fallback | ADR-0004 + ADR-0009 |
| deploy, containers, external services | ADR-0010 |
| whether a future feature is worth building | `exploration.md` + `roadmap.md` |
| how the harness works — a gate, counter, budget, the loop | `HARNESS.md` + `scripts/verify.sh` + `CLAUDE.md` |
| a tool version, or why agent tooling stopped working | `toolchain.md` |
| templates, layout, presentation, what a theme can rely on | `theme-contract.md` (+ ADR-0019, ADR-0023) |

## Single-source rule

Each fact lives in exactly one doc. Need it elsewhere? Link. This binds ADRs too: an ADR restating
a rule an owning doc already carries is a duplicate, not a decision — delete it and amend the owner.

Values that have drifted before, and their one home. Everywhere else names the concept and points
here; nothing else may state the value:

| Fact | Sole home |
|---|---|
| Earn-it thresholds (transforms, routes, views, extensions) | the counters table in `state.md` |
| LOC ceilings, size warnings, dependency cap | `scripts/budgets.env` |
| The permalink path shape | `content-model.md` (decision recorded in ADR-0008) |
| Which language is at the root, and the prefix form | ADR-0009 |
| The leaf/trunk definition | `architecture.md` invariant 7 |
| The sovereignty test | `roadmap.md` Governors |
| Package layout and the forbidden package names | `conventions.md` |
| What exists in the code right now | `state.md` inventory |

A value restated in two places is not redundancy for safety; it is a future contradiction waiting for
whichever copy gets edited alone.

`state.md` is the only doc describing the present; the rest describe rules, shapes, or intentions.
When code and `state.md` disagree, the code wins and `state.md` is wrong.

## Refresh triggers

Update in the Document step of the change that caused them. Not later.

| Change | Update |
|---|---|
| Any code change at all | `state.md` inventory + `verified against` line |
| New transform, route, view, extension, or dependency | the counters table in `state.md` |
| A choice expensive to reverse | new ADR in `decisions.md` |
| A primitive becomes real (earned) | STATUS line in `architecture.md` + counters |
| New frontmatter field, post type, or path shape | `content-model.md` |
| New dependency approved | `scripts/allowed-deps.txt` + ADR |
| Budget raised | `scripts/budgets.env` + ADR — once the first feature has shipped. While the harness is still being tuned, edit in place. |
| A latent item fixed | remove from the Latent list in `state.md` |
| Arc finished | `roadmap.md` + a retro line in `state.md` |
| Catalog item accepted or rejected | verdict line in `exploration.md` |
| `CLAUDE.md`, `scripts/` or `.claude/` changed | `HARNESS.md`, same change. Enforced by `verify.sh`. |
| A tool version deliberately moved, or a new external contract relied on | `toolchain.md` |
| The theme contract extended, or embedded templates changed | `theme-contract.md`, same change. Enforced by `verify.sh`. |
| A request spans engine and theme | contract extension here + a written note of the theme's part; never the theme itself |
| A new gate, counter, or budget added | `HARNESS.md` "Why the pieces exist" + a row in one of these tables |
| A rule, value, name or path changed | grep the repo for the old form; every doc naming the concept, same change |
| The disk contract changed | `content-model.md` + `testdata/` fixtures + a written migration step for the site root, which the engine repo cannot touch |
| A doc or ADR mandates what a change made optional | supersede the ADR; do not reword it in place |
| A request reversed a recorded decision | new ADR, or supersede the old one — the request does not win by being newer |
| A request exceeded a convention on purpose | note the deviation where the convention lives |
| An idea floated, not built now | a file in `../ideas/` + its index line. Adopted later: `Status: adopted → <where>` |
| A fact worth keeping surfaced in conversation | a file in `../reference/` + its index line, stating how it was established |

## Staleness

`/refresh-docs` reconciles docs against code and reports drift. Run it after a burst of work,
before a new arc, and any time a doc surprises you.

## House style

Present tense. Terse. Written for a reader who has forgotten everything, including their own
reasoning. No changelog prose, no "recently we…", no preamble. Delete a line before rewriting it.
A doc needing a table of contents is too long.

## Compression contract

Shortening a harness doc removes **words, never instructions**. Same rules, gates, thresholds,
triggers and table rows before and after; the agent must act identically. Redundancy between
`CLAUDE.md` and `SKILL.md` is deliberate — the constitution is always loaded, the skill is not —
and is not duplication to be collapsed.

Deleting a rule, adding one, or narrowing one is a rule change: it needs its own decision and its
own reason, and it never rides along in a compression pass.

Verify before reporting a saving: table rows, headings, list items and checklist boxes must match
the pre-pass file (`git diff --stat`, or a snapshot if the change is uncommitted). Report word count,
not lines — reflowing prose shrinks lines without saving anything.