Claude Opus 5andbdeshi
2041c43b70
{{< include file="notes.md" >}} renders a file from the bundle as Markdown in
place. The included file is converted by the same goldmark instance that is
rendering the page — handed to the transformer in Extend — so its configuration
can never drift from the page's.
Three properties, each tested:
A name containing ".." is refused. os.Root would stop a path leaving the site
root, but path.Join collapses ".." long before the filesystem sees it, so without
this an include could read a template or a stray dotfile from the site root and
publish it. Verified the test fails without the guard: it took three levels of
".." from content/pages/d to reach the root, and the first version of the test
used two, so it passed either way and proved nothing.
An include inside an included file renders nothing and logs. The nested parse is
marked, so one level is all there is and a file including itself is a log line
rather than a stack overflow (ADR-0038, ADR-0029).
A gallery inside an included file still resolves, because the nested parse carries
the same Origin.
The node gained `content` for output a feature produced itself, plus `isContent`
so a failed include renders nothing instead of falling through to a fragment
lookup and complaining about a template that was never meant to exist.
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 |
| what to build next | .scratch/build-queue.md if present, otherwise git log and 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 |
| A queue entry completed | tick it in .scratch/build-queue.md and note anything learned that changes a later entry — uncommitted, so the commit message carries what landed |
| 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.