khosra/HARNESS.md

The khosra harness — human's guide

Scaffolding that makes an agent build khosra the way you want: minimally, surgically, questions before code, docs that stay true.

README.md is a two-line signpost — human here, agent to CLAUDE.md. CLAUDE.md is the constitution (always loaded). docs/ is what the agent needs to build the engine — anything in it may be pulled into context on demand. ideas/ and reference/ sit outside docs/ deliberately: storage, opened only when you name a file, swept by nothing. .claude/ holds the feature-loop skill (skills/feature-loop/), six commands, and launch.json. scripts/ holds the gate.

How you use it

You ask for a feature. The skill fires by itself and runs Clarify → Plan → Implement → Verify → Document → Commit → Report.

This runs for casual requests too — the skill fires on "the default-language files do not need the .en part" exactly as it does on "add tag pages", with a one-line plan instead of a full one. A short sentence is not a small change: that one renames content on disk, makes a suffix optional in code, and contradicts every doc calling it required. The agent walks every surface — code, fixture sites under testdata/, harness docs — and, because it cannot reach your site root, writes down the migration you need to run there rather than pretending to have done it.

1. You: "Add tag pages."
2. Agent: up to three clarifying questions, each with a default. Answer or ignore.
3. Agent: a short plan — goal, primitive, success criteria, files, ±LOC, deps, earn-it check, and what it is deliberately not doing.
4. You: "go", or edit the plan. "Just do it" skips the gate on small changes.
5. Agent: implements, runs ./scripts/verify.sh, shows real output, updates docs, commits, reports.

Occasional maintenance, by you:

• "Park this" → the agent writes ideas/<slug>.md, resumable cold, and indexes it. Name the file later to pick the thread up; it reads these only when named.
• /audit every ~5 features — finds abstractions that never earned their keep.
• /invariants at arc boundaries, before a freeze, before the first deploy — checks the nine architecture invariants against the code, which no grep can do.

Conflicts come back to you. If a request contradicts a recorded decision — an ADR, an invariant, the permalink shape, the untrusted boundary, a hard budget — the agent stops, quotes the line, and gives you two paths: comply, or change the decision on purpose. It resolves only what is genuinely unambiguous, such as a doc that has fallen behind the code. Repeating the request is a valid answer and is taken as your decision; what it will not do is quietly reverse a choice you made earlier, or split the difference into a compromise nobody picked.

• /refresh-docs after a burst of work — reconciles docs with reality, reports drift.
• /verify, /adr, /leaf <topic> as needed.

Three surfaces, one of them yours to edit here. Engine source lives in this repo; content lives in the site root (ADR-0011); the theme is a third surface with its own owner (ADR-0023). A request that spans engine and theme produces a contract extension in docs/theme-contract.md plus a note of what the theme must do — not the theme. verify.sh fails if the embedded reference theme changes without the contract doc changing, because in practice those two drift together — and it fails on a <script> tag in that theme, because a reference theme that grows taste stops being a reference (ADR-0026).

The demo is gated like the docs. examples/demo-site/ is a real site, tracked as files so you can read it, edit it and serve it with make demo. It stays true by two gates: a coverage test in cmd/khosra serves it through the real handler and the real feature list with one case per feature (ADR-0072), and verify.sh runs khosra check over it. A feature added without a case there is a feature the demo does not show, and the build says so (ADR-0051). .claude/launch.json points the editor's preview at that same make demo on localhost:8080, so "look at it" and "test it" are the one site. It is the only dev server this repo has: the engine serves a site root and there is nothing else to run.

The agent names the layer as well as the primitive. Content on disk, engine, theme, browser — and it builds at the outermost layer that can do the job (CLAUDE.md §2, docs/architecture.md). This exists because a whole feature was built at the wrong one: widow prevention as a Markdown transform that inserted a non-breaking space into an author's prose. It worked and it had tests; text-wrap: pretty does it better with no bytes in the content, so the feature was deleted (ADR-0045). If a feature only rearranges how something looks, expect the agent to push back toward CSS or a template.

The ceilings have moved three times, all on purpose, and the third is a different kind. The first two were measurements — a number costed before any code existed, then eight lines of contract that would not fit. The third (ADR-0074) is a budget: core 2850 → 3000, ext 2000 → 3500, modules 6 → 9, signed off ahead of a list of features rather than in response to one. ext was genuinely blocking at 1975 of 2000; the rest is headroom bought deliberately. Invariant 9 is measured by a number that has now moved three times, and says something only because ext rose 75% against core's 7%.

The core ceiling has moved twice before that, both on purpose. CORE_LOC_MAX went 2000 → 2800 (ADR-0041) because the original figure was costed before any code existed and never budgeted what cmd/ would hold — check, new, -dev, change detection. It went 2800 → 2850 (ADR-0065) for eight lines of theme contract, and ADR-0041's own test — read a second raise as evidence something belongs in internal/ext/ — was applied rather than waived: feed.go and discover.go are the features that should leave, and they cannot, because an ext feature cannot own a route until the extension registry exists. When it does, they leave and this ceiling should come back down rather than stay as headroom. The two ceilings exist so that "core stops growing, ext rises" is observable, and that stops being true the moment leaves are allowed into core.

The binary grew for syntax highlighting. chroma is larger than khosra and takes it from ~15MB to ~20MB (ADR-0075). That was a deliberate trade for a site that shows code constantly, and it is the one place where "one small binary" got less true.

Context is a budget, and three pieces of it are mechanical. The limit on this project is how much work fits in a session, so docs/context-economy.md holds the reading, searching and reporting disciplines — read the compressed form first, batch calls, script anything repeatable, never pay twice for the same bytes (ADR-0053). Three parts are enforced rather than trusted: docs/surface.md is regenerated and staged by the pre-commit hook and independently compared by verify.sh, so the map of the code cannot mislead (261 lines standing for 3,757 of source) and no one has to remember to run it; CLAUDE_LOC_MAX bounds the one file re-sent on every turn; and ./scripts/verify.sh --quiet prints a verdict instead of forty-three lines, which is what the pre-commit hook now runs. The doc leads with a floor rather than the savings, because every cheap failure mode is also a token saving — not opening the owning doc, guessing a signature, reporting from a diff — and each of those has already cost this repo a defect.

The agent commits by itself, and tells you the first time. Work is committed as part of the loop rather than on request (ADR-0052) — one commit per revertible unit, never a push. In a session where you have not asked for that, the first commit is preceded by a line saying so and naming the off switch ("stop committing"), because a commit appearing in your repository unannounced is a surprise even when it is harmless. The asymmetry is the argument: a commit you did not want is one git revert away, and work that existed only in the working tree when something went wrong is gone. If you want the tree left dirty, say so and the loop stops at Document.

Authorship records who wrote the bytes: a commit the agent wrote is authored by it, one you both wrote is yours with the agent as co-author, one you wrote alone names only you (conventions.md "Git"). You remain the committer and the signature in every case — the key says you take responsibility for the commit, which is not the same claim as having typed it. git log --author=Claude is then a truthful answer to how much of this the agent wrote.

What is staged has to build, not just the working tree. Every other gate looks at your files; this one looks at the commit you are about to make, by building a throwaway checkout of the index. It exists because staging a subset — a changed signature without its caller — produced a commit that did not compile while verify.sh reported green, and a broken commit is something git bisect trips over for as long as the repo lives. It only runs when something is staged.

The injection boundary is a gate now, not a memory. Raw HTML renders for site-root content, because that content is the author's own (ADR-0060) — and the trusted half of that sentence is the whole claim. verify.sh fails unless html.WithUnsafe() appears in exactly one file, internal/render/render.go. A second call site means some other input has been handed the pipeline that trusts its author, which is the failure ADR-0003 exists to prevent; when comments arrive they get their own goldmark without it. A feature wanting to emit HTML still renders a theme template instead (ADR-0036).

Coming back after a long absence

In order, cheapest first:

1. ./scripts/verify.sh — one command, tells you whether the thing is still coherent and whether docs/state.md has fallen behind the code.
2. docs/state.md — what exists, the earn-it counters, the latent list. This is the only doc that describes the present, and verify.sh compares its last commit against the last .go one rather than trusting a sha written by hand (ADR-0057). Its companion docs/surface.md is generated: every declaration and its line, so you can find your way around without opening anything.
3. git log --oneline — one revertible unit per commit, each body saying why (conventions.md). This is the real map of how the code got here.
4. /refresh-docs — reconciles every doc against the actual code and reports drift, which is exactly the question you have after a year.
5. docs/decisions.md — the ADR log, when you hit something and think "why on earth is it like this". Each entry names the observation that would overturn it, so you can tell a stale decision from a deliberate one.
6. docs/toolchain.md — if something is broken rather than merely unfamiliar. It records what this was built against and which agent-tooling contracts it assumes, so a tooling change is diagnosable instead of looking like a harness bug.

Then docs/README.md for whichever topic you are actually here for.

Why the pieces exist

Every counter row says what does not count, and verify.sh fails on a row that leaves that column empty (ADR-0070). Four counters had to be re-scoped the first time anything tested them, and each fix was a sentence about what had been wrongly included — so the sentence is now required up front. A counter that cannot name an exclusion is measuring a symptom.

Counters in docs/state.md turn "no abstraction before its second use" into arithmetic. Every threshold lives in that one table and nowhere else. The agent cannot argue a pipeline into existence one transform early — it writes the next one inline and lets the count force the extraction. Most load-bearing mechanism here, and the one with least machine enforcement, which is why verify.sh fails any .go change that does not touch state.md. That does not prove the counters are right; it makes forgetting them impossible, which is the real failure mode.

The dependency allowlist names modules that are permitted, not required. The gate also fails an untidy go.mod, because go get marks a module indirect until something imports it — and an indirect entry is not checked against the allowlist, so an unapproved dependency could sit there unnoticed. # starts a comment anywhere on a line, including after an entry — the gate strips those, so an entry may carry the reason it exists. Being listed is permission; DEPS_MAX counts what go.mod actually pulls in. scripts/allowed-deps.txt is the list.

Budgets in scripts/budgets.env. Two hard LOC ceilings, core and extensions, plus a dependency cap. Exceeding one fails verify.sh, so raising it is a deliberate act with an ADR attached rather than a drift. The split makes "the core stops growing after Arc 2" measurable: post-freeze the core figure holds and only ext rises. File and function length are _WARNs, not ceilings — the cheapest way to satisfy a hard per-file limit is sharding a coherent file into a _helpers.go, which is worse code with a greener gate.

The latent list absorbs the urge to refactor mid-feature: a line in state.md instead of a drive-by fix. You decide when latent items become features — but an arc cannot close with an untriaged one, so the list drains instead of becoming a graveyard.

This repo is engine source only. The site root — content/, static/, optional templates/ — lives in its own repository and is passed to the binary with -site (ADR-0011), and validating content is the engine's own job rather than the gate's. The gate skips ideas/, reference/ and the uncommitted .scratch/, so exploratory code parked there never has to compile.

The architecture gate. verify.sh enforces the layering in conventions.md from go list output: content imports no sibling, render imports neither web nor ext, web imports no ext, nothing imports cmd. One convenient sibling import is what turns a layered engine into a ball of mud, and it always looks locally reasonable — so it is a hard failure, not a review note.

Feature locality is enforced, not hoped for. A feature is one directory under internal/ext/<name>/ plus one line in cmd/khosra/wire.go. verify.sh fails on a feature importing a sibling and on a feature package without a doc.go — the first because sibling imports make an agent's read set compound, the second because a four-line doc.go turns orientation into a fifteen-line read (ADR-0027).

Documentation is gated too. Every package carries a package comment, and a decision cited in code (// Path shape: ADR-0008.) must name an ADR that exists. Doc comments on exported identifiers are warned rather than failed — presence is checkable, usefulness is not, and a hard gate there would buy // Load loads. The point is a codebase still navigable by go doc and git log alone, years from now, with no agent available — verify.sh enforces presence, and only you can enforce that the comment says something.

The style floor fails, it does not warn. Forbidden package names, init(), importing log instead of log/slog, panic() outside cmd/, and time.Now() outside a clock.go are stated absolutely in conventions.md, so they exit non-zero. That last one exists because a Stage that reads the clock without an expiry would serve staleness invisibly. A rule enforced as a suggestion teaches the agent to read every rule as one. A green run has no warnings once code exists. An advisory that fires on correct code gets fixed — either the check or the code — because a warning nobody can act on trains you to skim the ones you can. Two of these have already been narrowed after firing on code the harness itself mandates.

Softer signals stay advisory: fmt.Errorf without %w, nesting past 4, exported-and-referenced-once, and any in an exported signature — only exported, because ADR-0002 mandates an open page object, so unexported code reading frontmatter takes any legitimately and forever.

STATUS markers in docs/architecture.md give the target shape and what is legal today, so the agent can read the endgame without building toward it.

Six primitives, and everything reduces to one. Effect (ADR-0012) covers work off the request path — derivatives, indexes, feed files, outbound syndication — on content change, on a schedule, or on demand. The test that keeps it honest: if the thing is computable at render time from the page plus the clock, it is a Stage, not an Effect. An "old article" banner is a Stage; it needs no job and can never be stale.

The harness maintains itself

The harness is code and drifts like code. Same rule as the engine: a change ships with the docs that describe it, in the same change.

• verify.sh fails when CLAUDE.md, scripts/ or .claude/ changes without HARNESS.md changing — except .claude/settings.json, which is Claude Code's permission list rather than anything about khosra. That exemption is one path: scripts/budgets.env and every other file under scripts/ and .claude/ stays gated, and khosra's own settings are not exempt from anything. This file is the current description of the machine, not a snapshot of its design.
• Invariant 7 is mechanical now. "Every feature is a leaf" means only cmd/ may import internal/ext/…, and verify.sh states that as one rule rather than a list of the pairs that happen to exist today (ADR-0069) — so a core package added next month cannot quietly import a feature. A feature importing its sibling fails the same rule.
• verify.sh fails when a .go file changes without docs/state.md changing, warns when state.md's last commit is older than the last .go one — the two together mean the doc ships inside the change, never in a commit trailing it (ADR-0057) — and fails when cmd/ or internal/ code changes without a _test.go changing — behaviour ships with a test. A comment-only or gofmt-only diff is exempt: it ships no behaviour, and failing it would only teach you --no-verify.
• The gate is not optional. scripts/hooks/pre-commit runs it on every commit; enable once per clone with git config core.hooksPath scripts/hooks. --no-verify bypasses it, and the commit body should say why. The hook also regenerates docs/surface.md and stages it, so a generated file is never something you have to remember — and it refuses a commit with unstaged .go changes, because what it generated describes the working tree rather than what you are committing.
• docs/decisions.md registers every ADR number ever used, entries and withdrawals alike, so a citation can resolve to a decision or to a deferral but never to nothing.
• ./scripts/verify.sh --list names every gate that exists. A doc claiming enforcement is checkable against it in one command, and /refresh-docs checks it in both directions — a claimed gate that is missing, and a real gate nothing explains. Asserting a mechanism before it exists is the drift that reads as enforcement and is decoration; CLAUDE.md rule 8 forbids it.
• docs/README.md carries three tables: topic → doc to read before asserting a rule, change → doc to update after making one, and an authority table naming the one home of every value. A new mechanism adds a row; nothing outside a value's home may restate it. A number written twice eventually disagrees with itself.

Open

• No ADR gate blocks Arc 1. One question remains in docs/state.md: the language suffix on the first content file.
• go.mod does not exist yet — go mod init belongs to the first feature, and the module path is still unchosen.
• .claude/settings.json denies reading ./.env*, but secrets a parent directory's .envrc exports are in every command's environment regardless. The deny rule is narrower than it looks.