khosra/harness/conventions.md

Conventions

The style floor. Do not ask about anything here — read it and comply. Disagreement is legitimate but goes through an ADR, not a diff.

Language and dependencies

• Go, current stable release. Stdlib first, with the balance CLAUDE.md rule 2 states (ADR-0083): what you can verify by reading it, not everything you could technically write.
• net/http, html/template, log/slog, os, io/fs, embed. Routing is http.ServeMux with Go 1.22+ patterns — GET /{section}/{slug}/ and {path...} for multi-segment slugs — so no router library is needed. No web framework, ORM, or config library — flags plus environment variables, parsed in one place. The site root (-site, KHOSRA_SITE) is the only required setting; default templates are embedded so a bare site root renders (ADR-0011).
• New dependency = ADR + human approval + scripts/allowed-deps.txt. verify.sh enforces it.
• Prefer 40 lines of obvious code over a dependency doing it in one call — unless those lines would be subtly wrong in cases the author cannot predict (why YAML is a dependency, ADR-0020), or the task is one somebody else specified, where the work is verification rather than authorship (ADR-0083).

Package layout

cmd/khosra/      main, flag parsing, explicit wiring — the only place things are assembled
internal/content/ bundles, frontmatter, slugs, queries — knows the disk, not HTTP
internal/render/  markdown, transforms, templates — knows content, not HTTP
internal/web/     handlers, routing, headers, caching — knows both, exposes neither
internal/ext/     extensions, one package each — earned at its counter (see extensions.md)

Dependencies point inward. internal/content imports nothing from the others; cmd imports everything and is imported by nothing. A feature under internal/ext/ may import internal/content and internal/render, and must not import internal/web, cmd/, or another feature — sibling imports are what make an agent's read set compound (ADR-0027). Every internal/ext/* package carries a doc.go; verify.sh fails without one. Routes reach web by assembly in cmd/khosra/wire.go, so web never learns features exist. No utils, helpers, common, shared, manager, base, impl, core — a package name not describing a domain is a smell. Flat until a package exceeds FILE_LOC_WARN; do not pre-partition, and a single-file package therefore warns at the same point it wants splitting.

Naming and shape

• Functions under FUNC_LOC_WARN, ideally under 20. Nesting depth under 4. File length is not a target: one coherent file beats two split to satisfy a counter. Values: scripts/budgets.env.
• No init(). No package-level mutable state. No singletons. Wire explicitly in cmd.
• Accept interfaces only where a second implementation exists; return concrete types.
• ctx context.Context first when a call can block or be cancelled — not decoratively.
• Never call time.Now() outside a clock.go. A render that reads the clock is only true for a while, and an injected accessor is what makes that expressible later; verify.sh fails on any other caller, because a forgotten expiry serves staleness silently.
• Comments explain why, never what. Delete a comment narrating the next line. One stating a non-obvious invariant is worth ten describing control flow.
• No two frontmatter keys may be near-homographs. archive and archived differ by one letter and would have meant "submit this page's outbound links" and "this content is stale" — proposed in the same review and caught only by the human. A key is a word an author types from memory months later, so distinctness matters more than brevity. Name the benefit, never the vendor: preserve_links, not wayback.
• Shell scripts end in .sh, with exactly one exception: scripts/hooks/pre-commit. git locates a hook by exact filename, so a .sh suffix makes it invisible and the gate stops running on every commit while still appearing to exist — verified by renaming it in a throwaway repository and watching a commit succeed with the hook silent. The name belongs to git, not to this convention. Consequence worth remembering: a repo-wide sweep filtered by --include='*.sh' walks past that file, which is how a stale path survived in it (ADR-0082), so verify.sh now checks the paths inside scripts/ whether or not they are quoted.

Documentation

Written for a maintainer working alone, years from now, with no agent to explain anything. verify.sh fails on a missing package comment and on a citation naming an ADR that does not exist; a missing doc comment on an exported identifier is a warning, because no gate can tell // Load loads. from a useful sentence, and a gate whose cheapest satisfaction is noise buys noise.

• Every package has a package comment. What it owns, what it does not, and which packages may import it. For internal/ext/* that is the four-line doc.go shape in extensions.md.
• Every exported identifier has a doc comment (warned, not gated). The exported surface of a 2000-line core is small, and go doc ./... is the only navigation tool that still works when nothing else does. A comment that restates the name (// Load loads.) is worse than none: say what it returns on absence, what it costs, what it assumes.
• Cite the ADR where the decision lives in the code. // Path shape: ADR-0008. at the point that builds a URL, // Visibility inherits: ADR-0024. at the guard. Twenty-seven decisions are unreachable from code otherwise, and the next maintainer changes something whose reasoning they never saw. verify.sh fails on a citation naming an ADR that does not exist.
• Comment the trap, not the mechanism. NFC normalisation, the settle window, parse order for template overrides, the old ∪ new membership rule — each is a line of code that looks arbitrary and is not. Those are the comments worth writing.

Errors

• Log levels mean these things, and Error is not "look at this". Error: the engine could not do what was asked — a request or build step failed, startup is aborting. Warn: it worked around something wrong in content or config and still served, which is all of ADR-0029's category. Info: lifecycle and one line per request. Debug: off by default, per-request detail while diagnosing. A log line addresses an operator, not its author; if it cannot be acted on, it is Debug or it is nothing.
• Wrap with %w at package boundaries, with operation and path: parse %s: %w.
• Never log and return the same error. Handle it, or return it.
• Request-time render failure degrades: log, serve what exists, never 500 on a missing field. Startup failure is fatal and loud. Content authoring errors name the file and line.

Tests

• Behaviour ships with a test. A change to cmd/ or internal/ carries a _test.go change in the same commit; verify.sh fails otherwise. Test the observable contract, not coverage for its own sake — one test proving the new behaviour is enough, and a refactor with no behaviour change needs only the existing tests to still pass (touch them or say why not).
• Table-driven. Golden files in testdata/, regenerated behind a -update flag.
• Test the observable contract: URL in → bytes out; file on disk → page struct. Do not test private helpers, and do not add a seam solely to make something testable.
• Needing a mock means the design is probably wrong — use a testdata directory with os.DirFS/fstest.MapFS.
• One end-to-end test per route beats ten unit tests of render internals.

Performance

Correct and small first; fast where measured. The render path is the only hot path.

• Write to io.Writer, never build pages by string concatenation.
• Parse templates once per rebuild, never per request and never inside a render method — the parsed set is swapped whole so every page serves one snapshot, with no exception for -dev (ADR-0055, ADR-0056).
• No sync.Pool, caching layer, or goroutines in the render path until a benchmark justifies it and the number goes in the commit message.
• No reflection in the hot path. Extra lookups are map reads, not reflection.
• Benchmarks live next to what they measure, added only when a decision depends on them.

Frontend output

Semantic HTML working with zero JavaScript. Progressive enhancement only. No build step for CSS. Page-specific styles and scripts come from the bundle (styles/scripts frontmatter). Respect prefers-reduced-motion. Every image gets width, height, and alt. Payload discipline is a feature of this project, not an optimisation.

Git

One revertible unit per commit: what would be undone together belongs together, what would be undone alone gets its own commit. Usually that is one feature — code, test, state.md row and ADR in one commit, because reverting the code without the doc leaves a lie. A correction to something that was already wrong beforehand is a separate unit even when it lands in the same sitting.

Imperative subject under 72 characters; body says why, and carries the numbers the change earned. Committing happens by itself and needs no request (CLAUDE.md §4); pushing never does.

Never a state: commit. state.md is part of the change, not a follow-up to it — nothing about a change is knowable only after committing it, now that currency is compared rather than declared (ADR-0057). A doc commit of its own is for a correction to something that was already wrong.

Amend rather than accumulate. A minor change the human asks for just after a commit — a comment removed, a wording fixed, a line they decided against — is amended into it while it is still unpushed. History records units of work, not the order in which someone noticed things.

Authorship names who wrote the bytes, not who asked for them.

Who wrote the change	Author	Trailer
the agent alone	Claude Opus 5 <noreply@anthropic.com>	none — the author field already says it
both	the human	Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
the human alone	the human	none

Directing a change is not writing it: a one-sentence request that the agent implements in full is agent-authored. The committer stays the human in every case, and so does the signature — the key attests to taking responsibility for the commit, which is a different claim from having written it. git log --author=Claude is then an honest answer to "how much of this did the agent write", which is the whole point of recording it.