bdeshiandClaude Opus 5
ec6e9838f0
docs/content-model.md opens with "Engine specification". It is also where the rule lives that a leading underscore makes a file unaddressable — and the human who owns this site did not know that rule, because nothing in this repository is addressed to an author. Twelve documents named docs/ while being exclusively about building the parser is a signpost pointing at the wrong room. Naming the directory for its audience makes the gap visible instead of hiding it. docs/ is now reserved and deliberately absent: an empty docs/ is an honest statement that end-user documentation does not exist, where docs/ full of parser specs was a claim that it did. HARNESS.md stays at the root. Root holds the three entry points — README.md for a human, CLAUDE.md for an agent, HARNESS.md for whoever maintains the machine — and harness/README.md is the map of the directory, so moving the guide inside would have collided with it for nothing. Mechanical and wide: 100 path references across 24 files. Every verify.sh gate that names a doc by path, the directory lists the dangling-path and ADR-number gates scan, surface.sh's output target, the Makefile, CLAUDE.md's read order, the skill, four commands, and two Go package comments. A first pass with a shell loop silently edited only four files and the rest still said docs/; the fix was to write the file list out and check the remaining count was zero rather than trust the loop's exit status. No rule, threshold, gate or obligation moved — this is a rename, and the gates demonstrated it twice: they stayed green on the new paths, and the ADR-number gate caught ADR-0082 before the entry existed. Deferred, both on the human's call: the end-user documentation site itself, which wants its own decision about where it lives and whether its claims are gated; and moving examples/ under docs/, since demo-site is a live site root that verify.sh, the coverage test and make demo all point at, and moving it would couple a rename to a design nobody has made. 31 files, +146/-106. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
9.5 KiB
Harness doc map
The docs an agent reads to build the engine. Read the one you need. Do not read them all.
This directory was docs/ until ADR-0082 renamed it: docs/ is reserved for documentation written for
whoever uses khosra, which does not exist yet. Everything here is engine- and agent-facing — a
specification, a rule, or a record — and none of it is written for an author.
| 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. One exception: a superseded entry's Status line is annotated in place to name what replaced it, because a reader arriving at the older entry has no other way to learn it was replaced. Never the Decision text — that stands as history |
roadmap.md |
Arcs, earn-triggers, the core freeze point | When an arc completes |
content-model.md |
On-disk layout, frontmatter, post types, permalinks — what the parser accepts today, never a plan | 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 |
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 |
context-economy.md |
How the agent spends context: what to read, in what form, and the floor no saving may cross | When a technique or a gate for one changes |
surface.md |
Generated. Every top-level declaration with its line — read before opening source | Never by hand; make surface |
Sibling folders sit outside harness/ because they are storage, not working material:
../ideas/ (parked ideas, any topic, and exploration.md — the catalog of engine features nobody has asked
for yet) 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 | ideas/exploration.md + roadmap.md |
| what to build next | the harness first (CLAUDE.md §1 read order) and git log for what landed, then .scratch/continue.md for the continuation point and roadmap.md for the arc. The handoff is temporary and ungated: check anything it calls pending with git log -- <the path it names> before planning from it |
| how the harness works — a gate, counter, budget, the loop | HARNESS.md + scripts/verify.sh + CLAUDE.md |
| what one commit contains, and when one happens | conventions.md "Git" (shape) + CLAUDE.md §4 (cadence, ADR-0052) |
| how to read, search, or report without wasting context | context-economy.md (+ ADR-0053) |
| 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, the CLAUDE.md ceiling |
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 — in the same commit, which is what verify.sh compares (ADR-0057) |
| 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 |
| A planned item completed | after the commit lands, delete it from .scratch/continue.md and note anything learned that changes a later one. Never during Document: a handoff written mid-change describes the plan, and an amend moves the commit under it — which is how one was written at 01:06 saying a trim awaited a yes that the 01:12 commit had already done |
| Arc finished | roadmap.md + a retro line in state.md |
| Catalog item accepted or rejected | verdict line in ideas/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 top-level declaration added, renamed or moved | nothing by hand — make surface, which verify.sh then compares |
| 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.