Claude Opus 5andbdeshi
99f8c730b0
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.
2.6 KiB
Engine design review — open items
Status: parked Raised: 2026-07-28
One review, many decisions. Each item below graduates independently: when one is settled it becomes an
ADR (or a change to its owning doc) and is struck from this list. When the list empties, delete the
file. Graduated so far: site root external to the engine repo (ADR-0011), Effect as the sixth
primitive (ADR-0012), NFC normalisation and slug derivation (ADR-0015), sequence position (ADR-0016),
template composition (ADR-0019), feature locality (ADR-0027). Five more were recorded and then deferred
to deferred-decisions.md: cache validity, declared types, the cascade, taxonomies, extras.
Why it came up
The harness was written for a generic blog engine and then aimed at a site hosting blog posts, webcomics, art, literary writing, standalone pages and IndieWeb status notes, with a featureset meant to keep evolving. Several things that are cheap to decide now get expensive once content exists or the first URL is published.
Decide before Arc 1 writes code
Pagination URL shape. Undecided and permanent — /posts/page/2/ versus a query parameter. ADR-0008
settled the bundle shape only, and ADR-0016 settled that a slug may contain slashes; this is the last
open piece of the permalink space.
Decide during Arc 1–2, as the code arrives
UI chrome strings and Bengali collation. i18n covers content variants, not chrome ("Next chapter", "Read more") — a small message catalog, decided before templates multiply. Separately, byte sort is wrong for Bengali indexes: adopt collation, or decide explicitly that ordering is date-only.
Cheap, whenever
A check command in the engine. Missing required fields per type, image without alt, broken
internal link, dangling series reference, orphaned asset, slug collision, non-normalised filename,
alias colliding with a live URL. A walk over already-loaded bundles. Explicitly not verify.sh:
that gate answers "is the engine sound", this answers "is my content sound", and it runs against a
site root the engine repo cannot see.
Search as a static artifact. A prebuilt index file shipped with the site needs no running service — the most sovereign option available, and it satisfies ADR-0010 trivially because the index is derived. An Effect (ADR-0012) builds it.
No-JS reading experience. Server-rendered prev/next always present; keyboard navigation and prefetch as enhancement only. Decide before the comic reader exists, not after.
Dropped
Binary assets in git. Now purely a decision about the site repo, outside the engine repo entirely, so the harness has no stake in it.