One idea at a time: definition, necessity, priority, layer, recommendation. Every
row is now shipped, scheduled, parked with a trigger, or dropped with a reason —
so both tracking files are gone rather than left as a parallel backlog.
Roughly a third already shipped. A quarter needed only a theme fragment or CSS,
including several the list assumed were features: arbitrary `theme.*` frontmatter
attributes already reach templates through Extra (verified), native lazy loading
already ships and is deliberately absent on lead figures, and in-page timelines
are a theme-defined container.
roadmap.md gains an "Order of work" — nine bodies of work in sequence, because the
sections this review added had accumulated without one. Item 0 is a decision, not
work: core sits at ~2965 of 3000 and logging alone wants the remainder, so
discover.go moves out *and* the ceiling rises with an ADR. feed.go and
web/extras.go cannot move; they are resolver cases, and three parked items now
wait on that same seam decision.
Two ADRs came out of it.
ADR-0083: the dependency rule described a practice it forbade. "Stdlib first,
always" and "usually 40 lines of stdlib" would, read literally, have argued
against all five modules here — every one is a format or algorithm somebody else
specified, and their allowlist comments say so. Surfaced when this agent proposed
hand-rolling Reed–Solomon for QR encoding. The test is now whether you can verify
it, not whether you can write it, with compute-versus-hold as the counterweight.
conventions.md and allowed-deps.txt contradicted it and were realigned.
ADR-0084: the Effect primitive said every Effect is "idempotent and re-runnable
from scratch" — true of derivatives, false of anything outbound, since a sent
message cannot be recalled. Split into artifact-producing and outbound, the latter
idempotent only against a delivery ledger, at-least-once with a dedupe key, and
ledgers in a -state directory distinct from the disposable cache. Asked for as
forward-looking design so webmentions need no redesign; recorded as a shape rather
than built, the way extensions.md records the Extension struct. Also fixed a
STATUS claiming Effects were "not buildable yet" when the derivative pass has
inhabited them since ADR-0042.
Findings that were defects rather than ideas: the Atom feed emits no <author>,
which RFC 4287 requires. HTML comments in content are published verbatim —
verified — so anything commented out is already public, and a check warning is
scheduled rather than the engine deleting authored bytes. `Page` has no Date, so a
theme cannot mark up dt-published or show an article's own date.
A frontmatter naming rule after this agent proposed `archive` alongside the
accepted `archived`: no near-homograph keys, and name the benefit rather than the
vendor.
reference/microformats-and-indieweb.md is new and is the reference asked for —
microformats2 properties and IndieWeb rel values mapped to where a theme puts
them, with spec URLs, marked scheduled. rel="me" is the highest-value lowest-cost
item in that space and needs no endpoint at all.
Four things this agent got wrong and the human caught: asserting "the engine never
fetches" from a sentence scoped to the content repo, twice; inventing a
data-sovereignty argument for an item he had filed as "a cool geeky thing", when
the raw Markdown in his git already is the sovereignty; the archive naming; and
claiming microformats could be fully implemented today.
15 files, +556/-385. No code changed. Nothing was scheduled that this agent could
not name a consumer for.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Ideas were spread across six places with real duplication and one list that was
about to be lost. Consolidated by merging the duplication, not the categories.
The 130-item feature-list triage lived in .scratch/, which is gitignored — 130
verified verdicts a scratchpad cleanup would have deleted. It is now
ideas/feature-list-triage.md with the header the ideas gates require, indexed,
and out of agent context by default like everything there. exploration.md's
Verdicts table was empty and designed for exactly this; it now carries one row per
body of work with a pointer, rather than 130 rows nobody could skim.
Deferred triggers had no single owner: continue.md restated them and drifted,
still listing the extension registry as pending after ADR-0081 built it.
deferred-decisions.md now holds the only trigger table, covering the two it
already described plus math, corrections, write routes and the registry's
remaining fields. continue.md links to it. Two rows record couplings worth not
rediscovering: the View layer may pull a minimal settings cascade in with it,
because the Views counter says selection resolves *through* the cascade; and
ADR-0081's seam mounts GET only, so Arc 3's first write endpoint extends it.
Corrections per post is dropped in its cheap form and parked in its real one. A
hand-maintained frontmatter list was rejected for an authoring reason rather than
a technical one — a half-remembered list of corrections misleads where none would
not, because two entries imply those were the only two. Deriving it from
repository history is the shape worth waiting for, and the file records what must
be settled first: whether the engine may read local git history at all, that it
needs a dependency or a subprocess, and that not every commit is a correction.
Not merged, on purpose: latent items stay in state.md because they describe
shipped code and are gated against .go commits; arcs stay in roadmap.md because
they are sequencing decisions. One file would have flattened four levels of
authority and made pending work cheap to load, which is the opposite of why
ideas/ sits outside harness/ at all. harness/README.md now says which list owns
what, in both the topic table and the single-source table.
7 files. No rule or threshold moved.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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>
Two structural changes, both about what an agent may pull into context.
exploration.md catalogues engine features nobody has asked for. That is storage,
not working material, so it moves to ideas/ where nothing sweeps it and it is
opened only when named — the same rule the other parked material already
follows. Six references repointed; the ideas gates then demanded an index line
and a status, and both were supplied rather than exempted.
build-queue.md was 516 lines, nearly all of it entries 0-23 finished months of
work ago, with the plan buried at the top. It becomes .scratch/continue.md at
49: where the code is, what is planned, and the findings worth carrying that no
doc owns — chiefly that silent damage to prose is this engine's recurring
failure mode, and that three defects this arc were invisible to curl.
Docs and HARNESS point at the new names. No rule, gate or threshold changed.
Adopts ideas/token-conservation.md, parked 2026-07-28, plus the disciplines
the human added: read the compressed form first, discover by mechanism,
shrink output at the source, never pay twice for the same bytes.
docs/context-economy.md owns all of it and leads with a floor, because
every cheap failure mode is also a token saving — skipping the owning doc,
guessing a signature, reporting from a diff, thinning a test — and each has
already cost this repo a defect. Frugality is for presentation and
discovery, never for the artifact or the evidence.
Mechanical, not remembered:
- scripts/surface.sh generates docs/surface.md — every top-level
declaration with its line, 261 lines standing for 3757 of source. The
pre-commit hook regenerates and stages it, so it cannot be stale, and
verify.sh compares independently for a clone that never set
core.hooksPath. The hook refuses a commit with unstaged .go changes,
since what it generated describes the working tree, not the commit.
- verify.sh --quiet: 48 lines of gate output become 1. The hook uses it.
- CLAUDE_LOC_MAX=150, the only budget billed per turn rather than per read.
Both new gates were watched failing before being kept: a doctored
surface.md, and CLAUDE_LOC_MAX temporarily set to 5.
state.md's inventory loses its LOC column. It had already drifted on six
files (content.go 381→450, render.go 447→454, web.go 206→217, check
216→223, watch 129→137, chrome 105→110) which is what a number written in
two places does; the generated file owns sizes now, the table owns purpose.
The subagent question is recorded there as the one open decision, with the
case for and against written out in the idea file.
Twenty-seven ADRs existed before a line of Go. Five specified the shape of
unbuilt mechanisms — cache validity, declared types, the settings cascade,
taxonomies, extras — which breaks the rule against abstraction before a
second concrete use, in prose where the counters cannot see it. They move to
ideas/deferred-decisions.md as recorded intent and return shaped by whatever
implements them.
Citations retargeted throughout; where one was decoration the rule now stands
on its own reasoning. Type declarations and the cascade drop to [spec] with
the MVP behaviour stated instead, so the first prompts have less to build.
conventions.md names http.ServeMux as the router, closing a hole that invited
hand-rolling a path splitter. The ADR gate now checks a number is registered
in the log rather than headed by an entry, so withdrawals resolve and invented
numbers still fail. Two architecture invariants corrected: identity no longer
implies a required language suffix, and the duplicated permalink clause is gone.
bdeshiandClaude Opus 5