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.
51 lines
2.6 KiB
Markdown
51 lines
2.6 KiB
Markdown
# 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.
|