HARNESS.md described how the ceilings got where they are — a paragraph of
changelog that grew with each raise. The ADR log is where history belongs, so
the section now states what the two ceilings are for, where the values live, and
how to read a raise. Any doc that narrates its own edits will do this again.
theme-contract.md explained parse order three times: once in the fragments
section, once under the stability rule, once under overriding. Once now, with
the other two pointing at it.
content-model.md carried a marker system — `[arc1]` build now, `[spec]` recorded
intent, plus a standing instruction never to build from a `[spec]` section. The
better answer than a stricter marker is no marker: the doc now describes only
what the parser accepts, and the shapes nobody has asked for moved to
ideas/exploration.md, which is storage and out of context by default. There is
nothing left to build speculatively from, so nothing needs to say so. 518 lines
to 469, and rule 6 plus the leaf/trunk test already cover the rest.
A sweep for filler phrasing found almost none — the prose was already tight — so
that part is two rhetorical tics rather than the cull expected. Reporting it
honestly matters more than manufacturing a diff.
No rule, gate, threshold or obligation moved.
Three reference files, each stating whether a fact was measured, read from
source, or asserted — an unattributed number is a rumour.
math-on-the-web: MathML is the only no-JS route, the one pure-Go TeX→MathML
library is an untagged 2023 commit, and writing MathML directly costs nothing
since raw HTML renders.
syntax-highlighting-choices: chroma is two modules and ~5MB, every alternative a
search returns is JavaScript, and custom lexers load from XML at runtime without
a rebuild.
goldmark-behaviours: the seven surprises that caused or nearly caused defects —
strikethrough claiming a single tilde, delimiter runs pairing across whitespace,
per-parse heading id counters, footnote id prefixes, raw HTML being dropped
rather than escaped, the language class already in the output, and ParseFS
globbing.
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.
The cap was arbitrary and the wrong lever: what matters is that a question's
answer changes the code, not how many such questions a request happens to carry.
A request with six real forks now gets six, batched into one turn — splitting
them to look brisk costs the human more than asking once. The instruction to ask
is unchanged and still gated by "each with a default so silence answers".
The rest is numbers the harness had no business holding. Three kinds, swept
across every harness doc, and none of them wanted machinery.
Restated values were the real fault: HARNESS.md carried the ceiling figures,
which docs/README.md's single-source table says live in scripts/budgets.env and
nowhere else. Prose repeating a value is a copy waiting to go stale, which is
exactly the rule I was quoting at everything else. The ADRs keep old and new, as
an append-only log should; the harness names the concept and points.
Illustrative figures — how long verify.sh prints, surface.md against the source,
how much the binary grew — drift every commit and carry no decision, so they now
say "a line per gate", "an order of magnitude smaller", "roughly a third".
Counts that restate their own list are the same fault in miniature: "the three
gates people skip", "six commands", "three pieces of it are mechanical", "two
sibling folders", "three cases, no fourth". Each is a number that goes wrong the
day the list beneath it changes, and none of them was doing any work.
Left alone deliberately: values with no other home — the ~50% overrun, the
72-character subject, 40 lines of stdlib over a dependency, toolchain versions.
Those are the source, not a copy of one.
No gate for this. It would have to guess which four-digit number is a budget
rather than a year, an ADR, an HTTP status or a Go version, and a gate that
fires on correct prose is a defect.
Two stores meant a request landing between them saw a new theme with the
previous index: each half coherent, the pair a state that never existed on disk.
Microseconds, which is why it waited — it closes now because the fix removes
machinery instead of adding it.
web.Snapshot holds both behind one atomic.Pointer that a rebuild stores once. A
Renderer never changes after New, so Refresh and the atomic inside the renderer
are gone; an immutable renderer is the simpler object, and the one place a
change is applied is now the one place it is observed.
web.Handler lost its renderer argument and twenty test construction sites moved
with it. Live reload verified on the real binary through the new path: a
template edit appeared and reverted, two rebuilds for two edits.
Also answers the session's open question: no subagents for fan-out reads. A
verdict arriving without the reading behind it cannot be audited, which is the
thing this harness exists to make possible.
Latent list: 6.
Composing a page from several files is why includes exist, and one endnote list
at its end is what that page wants. ADR-0066 kept the old default only so
existing content would not re-render; both models have now been seen and the
human chose. `include: embed` still asks for the other thing.
One-level needed enforcing on the new path: a spliced fragment's own include
line would otherwise be parsed as a call and expanded a second time, which a
test caught. It is dropped during the splice, matching what embed already did.
chroma at render time, emitting CSS classes rather than inline colour, handed to
a `code` theme fragment. Highlighting works with scripting off, in a feed
reader, in a browser that never runs JavaScript. No lighter pure-Go option
exists — every "alternative to chroma" is JavaScript, which the reference theme
is gated against.
A fence's info string carries the rest: title, numbers, start, hl=3,7-9, and
file=name lines=A-B, which reads the snippet out of a file beside the bundle and
numbers it by that file's own lines. So a post quotes several parts of one
program without the copies drifting from it, and a reader can find what they are
looking at. Verified on the real binary: the same file at lines 5-10 and 12-14,
each numbered as it really is, with different lines tinted.
Not a new package: a new one could not import the key=value parser this repo
already has, because ADR-0069 forbids a feature importing its sibling, and a
second parser for the same syntax is what §6 stops.
Two costs, both stated in the ADR rather than buried. The binary goes from ~15MB
to 19MB, for a project whose story is one small binary. And the reference theme
now carries a token palette — the first thing in it that is a taste rather than
a demonstration — kept to eight classes for that reason.
The demo quotes a shell file, not a Go one: a .go file under examples/ joins the
module and has to compile, which the build gate caught before it shipped.
6 of 9 modules, ext 2188/3500.
core 2850 -> 3000, ext 2000 -> 3500, modules 6 -> 9.
ext was the binding one: 1975 of 2000, with syntax highlighting still to write,
so for that ceiling this is not anticipation but the difference between building
the next feature and not. The other two are bought ahead of a list of features
the human has signed for. DEPS_MAX 9 leaves room for chroma and its regexp2 —
which fill 6 exactly — plus two more.
Worth naming rather than glossing: a ceiling raised on evidence is a
measurement, and one raised on intent is a budget. The first two raises were the
first kind; this is the second, which is weaker. ADR-0041's test still stands —
if core approaches 3000 the question is again what belongs in ext, and the
answer is still feed.go and discover.go, waiting on a feature being able to own
a route.
Invariant 9 is measured by a number that has now moved three times. It says
something only because ext rose 75% where core rose 7%.
FILE_LOC_WARN and FUNC_LOC_WARN are untouched: they are about one file being
readable, and nothing about the plan changes that.
G4 — keyboard and swipe navigation — is out of the plan rather than deferred:
it needs client JS, and the pages already carry prev/next links. The queue says
so, and the one latent row whose trigger named it now names something that will
actually happen: the next edit to base.html.
The memo held one entry per picture ever rendered, for the life of the process.
Correct for one author's laptop, wrong for what this engine is meant to be: a
server that runs for months and serves a whole site to many readers.
Least-recently-used rather than clearing when full, because a site has pages
nobody opens for months and a front page opened every minute — discarding
wholesale throws away exactly the entries about to be asked for again. A map
into a recency-ordered list: reads promote, evictions take the back, both
constant time.
1024 entries is a few hundred kilobytes. Generous enough that a normal site
never evicts, bounded enough that no site can grow the process without limit.
The number is a constant and not a setting, because a knob with one user is a
knob nobody asked for.
Eviction, replacement and the bound are tested, including under -race, since
requests are concurrent and the store is shared.
Latent item cleared. ext 1975/2000.
The test rebuilt the feature list by hand, because a package cannot import a
main, and it drifted three times in one session — the dialect, notation, Compose
— each caught by a failing case rather than by the copy.
The obvious fix was a composition package under internal/ext, and it was the
wrong one: ADR-0069 forbids a feature importing its sibling, so that package
would have failed the gate on its first build and the invariant would have been
weakened one commit after becoming mechanical. Moving the test is smaller and
points the other way — cmd stays the only place a feature is named, which is
what extensions.md asks for, and wire_test.go was already here for the same
reason.
runServe and the test now call one function for the renderer, so there is no
list to keep in step. Four files named a feature before; three do now, all of
them package main, plus a benchmark that deliberately wires one extension to
measure the render path and never claimed to be the shipped list.
The core ceiling paid for it rather than being raised a third time: `given` was
a helper with one caller and is now inlined into the only function that used it.
core 2842/2850.
Latent item cleared — the one that was marked due.
One file held every fragment, and it gained one per feature all session: figure,
gallery, icon, three admonitions, details, aside, contents. A theme author
overriding one had to copy the file or redefine into it, and a diff of the theme
became a diff of everything.
Both forms are supported, because a small theme is happier with one file and the
contract should not force a directory on it. Parse order is embedded file,
embedded directory, site file, site directory, and the last definition wins — so
the directory overrides the file within one source and a site overrides the
binary either way. Verified with a site root using both at once: its
shortcodes.html supplied `icon`, its shortcodes/note.html supplied `note`, the
embedded directory supplied the rest, and with the same name in both the
directory won.
The embedded theme ships the directory only, seven files, so nothing is defined
twice.
parseSet takes globs now and lost a branch doing it. Its old guard — a literal
embedded name must exist — had to go, since shortcodes.html is deliberately
absent; the replacement is stronger, failing at startup when a set matches
nothing anywhere, which also catches a renamed base.html.
Extra holds what the parser does not name (ADR-0002), and title, aliases, tags,
order, slug and draft are all deleted once lifted. date was the one exception,
so a template reading .Extra.date got the raw YAML value sitting beside the
parsed time — two spellings of the same fact, which is how they drift.
One line, and a test that names every lifted key rather than just this one, so
the next field added to Bundle has somewhere to fail if it forgets.
Latent item cleared. It had been waiting on "whatever next reads Extra
generically"; nothing does yet, but the fix was smaller than the row describing
it.
Four of these counters were re-scoped the first time anything tested them, and
every re-scoping was a sentence about what had been wrongly included: transforms
were counting parse-phase work goldmark already orders, views were counting
output formats, effects nearly counted an in-memory swap, extensions counts
packages rather than goldmark's own extensions.
So the fix is not another counter but a required shape. The table gains a fifth
column and verify.sh fails on a row that leaves it empty — watched naming the
offending row. Checked by shape rather than by wording, because a gate that
demands a phrase gets the phrase and not the thinking.
Writing the exclusion up front is the cheapest way to find out whether a counter
measures a mechanism or a symptom, and all eight rows could state one, which is
the first evidence that the counters are now scoped right.
Queue entry G6.
"Every feature is a leaf" was enforced by listing the pairs that happen to exist
today: content, render and web may not import ext, plus a separate check for
siblings. A list only forbids what is already there — a core package added next
month could import a feature and pass, which is how an invariant rots while
staying technically true.
One positive rule now: only cmd/ may import internal/ext/…. It covers packages
that do not exist yet and catches a sibling import in the same breath, since a
feature importing another feature is the other way one stops being deletable.
Four rules become one.
Watched rejecting both kinds before keeping it — a core package importing a
feature, and a feature importing its sibling — and watched passing the tree as
it stands. Test files are excluded, which is right: the demo's own test wires
features on purpose.
Queue entry G5. It was the last architecture invariant held only by hand.
srcset without sizes means a browser assumes 100vw, so a gallery thumbnail in a
16rem column was fetching the 1600px original — the derivative pass was costing
bandwidth on the page it exists to save it on. It now picks the 480w variant.
sizes is the one part of responsive images the engine cannot supply: it states
how wide the picture will *be*, which is a fact about the layout and therefore
the theme's. The reference theme states its own measure and nothing more.
Lazy loading goes on gallery entries and not on a figure, because a figure is
often the first thing on the page and deferring it delays what the reader came
for. Both have demo cases, including that the figure is *not* deferred.
Queue entry G2, which had been sitting unfixed through the whole Markdown arc.
Three fragments added this session needed a word the author did not write: an
untitled :::warn told the reader nothing about being a warning, an untitled
panel fell back to whatever the browser calls <details>, and the contents list
had no label at all — an accessibility gap as much as an untranslated one. None
of them could be fixed, because `t` needs a language and Fragment had none, so
those words could only ever have been English on a site that serves Bengali.
Fragment gains Lang, captured on each call at parse time — a node renderer never
receives the parse context, the same constraint that put pictures and headings
on the node. Five phrase keys follow, and a Bengali page now reads সূচিপত্র,
সতর্কতা and বিস্তারিত where an English one reads Contents, Warning and Details.
The demo's own list.html was the better example of the problem and now shows the
answer: a site's own sentences are not in the engine's phrase table, so a
template needing its own words branches on the language it was given. That is
what theme-contract.md has always told a theme to do, demonstrated rather than
asserted, and a case proves the Bengali listing carries no English.
Two files crossed the size advisory on the way. render.go shed the contract
types to view.go, where state.md already claimed they lived and where the file's
own header said they belonged; shortcodes_test.go split to mirror its sources,
which the one-file-per-source convention already asked for. Both are pure moves.
`include: merge` in frontmatter splices a bundle's includes before the parse, so
a page assembled from several files is one document: one footnote list at its
end, numbered straight through, and an abbreviation defined anywhere reaching
every part. Moving the rendered block afterwards would have meant editing
goldmark's own markup; handing the parser one source gets the right answer from
it instead. Without the flag nothing changes — each fragment stays its own
document with namespaced ids, so no existing content re-renders.
Heading ids are unique under either model. Merging gets that free, because one
parse means one id set, but embedding did not: three `## Description`s across a
page and its fragments produced three identical anchors, and every link to them
landed on the first. A nested parse now shares the parent's id set, so the
second becomes #description-1 — goldmark's own suffixing, reaching across files
because they finally share the set it counts in.
Auditing for other policies the author could not reach found two more.
A heading may declare its anchor: `## Title {#stable-anchor}`. This is the one
that mattered most and nobody had asked for it — a derived id changes when the
text does, so rewording a heading silently broke every link to that anchor,
which is indefensible in an engine whose first value is that published addresses
are permanent.
`::toc{depth=2}` shortens a contents list, because a theme cannot know per page
how deep is useful and the author can.
Deliberately not added: a typographer toggle, a per-picture "do not resample",
icon overrides. No second user for any of them.
The hand-copied wiring in example_test.go drifted for the third time this
session — Compose this time, after the dialect and notation — each caught by a
demo case rather than by the copy. The latent row is now marked due, with what
moving the list would require.
Two defects only a screenshot could find, both mine.
The table of contents did not look like one: list-style:none stripped the
markers and nothing replaced them, so the entries read as two loose links in the
prose. Hairlines above and below make it a block again.
<mark> was using the browser default, black on yellow, which fights a dark page.
It has explicit colours now, and a muted pair in dark mode.
Also records a third, which is not a defect but reads like one: an included
file's footnotes render where the include sits, so the page appears to end and
restart halfway down. That is ADR-0038 working as documented — a fragment is
converted on its own bytes — and the ids are correctly namespaced. Only the
placement is unfortunate, so it goes on the latent list with the trigger that
would justify changing it.
Verified in the browser this time rather than by curl: the aside floats at
1280px and flows inline at 375px, grouped panels close each other with no
script, and dark mode is readable throughout.
notes-on-water had become a kitchen sink: every feature from the last eight
loops on one page, which demonstrates the engine and misrepresents the site.
Now each lands where a real site would put it. The text marks, the abbreviation,
authored <kbd> and the margin note go to writing/typography, which is already
the page about what the engine does to words. Icons and the grouped panels go to
pages/colophon, which is the page about the theme — install instructions are
what tabs are actually for. about gets a lone expando, the-flood gets a chapter
note, and notes-on-water keeps what it is really for: the include and its
namespaced footnotes, the gauge table, the glossary and a contents list over its
own headings.
Seven bundles carry features now instead of two, and the demo cases moved with
them, so each still names the page it proves.
Expandable sections, tabs and asides — three of the things parked earlier — turn
out to be two theme fragments and nine lines of CSS. That is what the container
mechanism bought: they needed no Go.
Tabs without script were the only real problem, and containers do not nest, so
:::tabs wrapping :::tab was never available. Sibling <details> elements sharing a
name attribute are natively mutually exclusive, which is what tabs are, so
grouping is one argument on the same fragment an expando already uses. A browser
too old for grouping opens them independently — the content is never hidden,
which is the failure mode worth caring about.
The aside is beside the text where the viewport has room and in the flow where
it does not, in one media query. No JS anywhere, and the demo case asserts the
page contains no <script> at all.
No ADR: nothing here is expensive to reverse, and the contract grew additively
as its stability rule allows.
`::toc` renders through a `toc` fragment receiving level, text and the id
goldmark already assigns. The engine collects, the theme decides whether that is
a list, a sidebar or nothing — the reference theme emits a flat <ol> with a
level class per entry, so indentation is CSS rather than markup.
A theme cannot enumerate headings, because templates cannot parse HTML, so the
engine is the only thing that can supply them. Collection lives in ext; only the
Heading type and one Fragment field are core.
That is what needed the ceiling: CORE_LOC_MAX 2800 -> 2850, the second raise.
ADR-0041 said to read a second raise as evidence something belongs in ext, and
the test was applied rather than waived. feed.go and discover.go are the
features that should leave core, and they cannot, because an ext feature cannot
own a route until the extension registry exists — which the counter says buys
nothing yet. The thing that should move is blocked on a different decision, so
the honest fix was the ceiling and an ADR saying exactly that. When routes
become ownable, they leave and this comes back down.
Entry text is the heading's words with markup stripped: a link inside a link is
not markup a browser accepts. An entry whose heading has no id is skipped rather
than linked nowhere, and a page with no headings renders no nav at all.
core 2804/2850, ext 1825/2000, 34 gates green, 0 warnings.
`:::name{…}`, a body of Markdown, then `:::`. This spends the form reserved by
ADR-0059 rather than leaving it a promise — and building it back then would have
been a mechanism with no user, which is what the reserve was avoiding.
The body renders first and reaches the theme fragment as .Body, already HTML, so
emphasis, links, subscripts and icons all work inside an admonition. That is one
addition to the theme contract, additive as the stability rule requires, and two
lines of core — which is what the remaining budget allowed.
Rendered by a transformer rather than the node renderer, for the same reason an
include is: rendering a subtree needs the document, and a node renderer never
gets one.
When the theme has no template for a kind, the engine writes the body out
unwrapped. Same principle as an unknown icon keeping its text, and it matters
more here: a theme not knowing one name must never cost an author paragraphs,
and an unstyled aside is a far smaller failure than a missing one.
The leaf parser was parameterised by prefix rather than copied — a second copy of
parsing logic is a stop condition, and the two forms differ by one colon.
Containers do not nest: a `:::` inside closes the one it is in, the same limit an
include carries. Stated in the ADR and the contract rather than left to be found.
core 2796/2800, ext 1743/2000, 34 gates green, 0 warnings.
The engine's half is one call: parse the name, hand it to a single `icon`
fragment, decide nothing else. No icon table in Go, ever. The surveyed engines
split three ways — Unicode (Hugo, Pandoc), a remote image per icon (Jekyll's
jemoji, which fails the sovereignty test outright), and inlined SVG from a
bundled set (MkDocs Material) — and all three are decisions about markup, which
ADR-0036 puts in the theme. A theme wanting Font Awesome ships a sprite in its
own base.html and redefines one fragment: no webfont, no request, no script.
The boundary rules are the whole difficulty, because the colon is the commonest
punctuation in technical prose. A name must start with a letter, hold only
letters, digits, hyphens and underscores, and neither colon may touch an
alphanumeric. Verified on the real binary that 10:30:15, key:value:pair,
"Note: this", a URL and a code span all come through untouched — each of them
would otherwise be a silent edit to someone's sentence.
The literal fallback closes the same hole from the other side: when the theme
renders nothing, the engine writes the author's `:name:` back, so an
unrecognised icon is never deleted from the middle of a paragraph.
An icon needed its own inline node rather than the block one — goldmark
distinguishes the two by type — which also avoids the type switch CLAUDE.md §6
forbids: two kinds, two renderer functions.
The reference theme maps six names to Unicode and ships no sprite, font or
asset. core 2794/2800, ext 1615/2000, 34 gates green.
`*[TERM]: expansion` on its own line, PHP Markdown Extra's form, and every
whole-word use in the document becomes <abbr title="…">.
A transformer rather than an inline parser, because a definition may appear
after the use it explains and a parser only ever sees what it has already read.
A block parser rather than a pattern found later, because the line has to stop
being content — an author would notice that going wrong before anything else.
Whole-word matching is the part that would have bitten: without it a definition
of HTML quietly rewrites HTMLish and xHTML too, so both have cases. Code spans,
autolinks, raw HTML and an already-expanded term are skipped, the longest
definition wins where two could match, and the expansion is escaped into the
attribute so a quoted phrase cannot end it.
Definitions are document-scoped. A term defined in a page does not reach an
included fragment, which is parsed on its own bytes exactly as footnotes are —
stated in content-model.md rather than left to be discovered.
The nesting gate caught firstMatch four levels deep; the inner search is its own
function now, which reads better than it did before the warning.
core 2794/2800, ext 1483/2000, 34 gates green, 0 warnings.
~sub~, ^sup^, ==mark==, and ~~strike~~ moved in from goldmark. Not a
preference: goldmark's strikethrough claims a single tilde as well as a double,
so with it enabled H~2~O rendered as H<del>2</del>O — measured before the
change. Two features cannot share a byte and both be correct, so notation owns
it and the authored syntax stays exactly as ADR-0058 documented.
The second failure was worse and only showed up under test. Under delimiter
rules `x^2 + y^2 = z^2` pairs its carets across the whole expression and renders
x<sup>2 + y</sup>2 — prose silently becoming markup, in exactly the content this
engine is for. So a single run is scanned rather than paired, and may not cross
whitespace: a subscript holds a formula, never a phrase. Pandoc draws the same
line. The cost is that a single run takes its content literally, so there is no
emphasis inside a subscript, which the ADR states rather than leaving to be
discovered.
New package under internal/ext, which is a stop condition and was asked. It
takes the extensions counter to 4, past its threshold, and the answer is still
no: four features attach in three unrelated ways, and two goldmark extenders
compose in goldmark's own extender list, which is already the registry for that
shape.
The example site's hand-copied extender list drifted, exactly as the latent row
added last loop predicted — the demo case failed and named it. Both are now in
step again.
core 2794/2800, ext 1236/2000, 34 gates green, 0 warnings.
Dropping raw HTML was silently destructive. H<sub>2</sub>O rendered as "H2O",
10<sup>6</sup> as "106", <kbd>Ctrl</kbd> as "Ctrl", and khosra check reported
nothing — an author lost meaning with no signal anywhere. Measured on the real
binary before and after.
Invariant 2 already says content from the site root is trusted, so the old gate
was defending the half of the boundary that was never in question while the
untrusted half has no code to defend yet. Chemistry, units, exponents and
keystrokes are what a hard-science site needs and what no Markdown dialect
expresses, so html.WithUnsafe() goes on in internal/render/render.go.
The gate does not disappear; it narrows. verify.sh used to fail on WithUnsafe
appearing anywhere and now fails unless it appears in exactly that one file —
watched doing both, accepting one call site and naming both files when a second
appears. A second pipeline trusting its input is the failure ADR-0003 exists to
prevent, and when comments arrive they get their own goldmark without it. The
gate is the reminder that the split has to be built rather than assumed.
The security test that asserted "raw HTML must still be dropped" now asserts the
property that actually holds and matters more: a shortcode argument stays data
whatever the page around it is allowed to do. ::figure{alt=<b>bold</b>} still
arrives as <b> while the <span> beside it renders.
core 2793/2800, ext 1077/2000, 34 gates green, 0 warnings.
`::name{key=value}` alone on a line, quotes only where a value has spaces,
braces omitted when there are none. The old form cost eleven characters of
punctuation per call and could not carry a body, which admonitions will need.
Generic directives are an existing convention — remark-directive, MyST,
Docusaurus — so this is a syntax authors and tools already know rather than one
more invention, and it reserves `:::name` for containers and `:name[…]` for the
inline dynamic calls that come later.
Retired outright rather than aliased: two syntaxes is two parsers and two test
sets forever. `khosra check` reports every leftover call as fatal and names the
replacement, so migrating a site root is running it until it exits zero — proven
on an unmigrated root, which exits 1 with the file and the fix.
The trigger byte moves from `{` to `:`, which prose uses constantly, so the
parser refuses `3::4`, `: a definition` and `:::note`, each with a case. The
definition-list parser sits at priority 101 and this one at 100, so it gets
first refusal and everything it rejects falls through.
Two things the syntax change would have broken silently. check's alt-text regex
still matched the old form, so the one accessibility check the engine has would
have stopped finding anything — it moves with the syntax and keeps its case. And
a test asserted that hostile arguments fail at the syntax because quotes cannot
be expressed; unquoted values are legal now, so it asserts the property that
actually holds: the fragment escapes them.
Demo migrated. core 2790/2800, ext 1077/2000, 34 gates green, 0 warnings.
Tables, footnotes, definition lists, strikethrough and automatic heading ids.
Which dialect a site is written against is permanent, so ADR-0058 names the
whole set at once — including the four refused, each for a reason rather than a
taste: task lists publish nothing, linkify rewrites plain text into markup that
ADR-0034 forbids the engine to touch, CJK is the wrong script family for a
Bengali site, and the GFM bundle is a package deal for the first two.
Footnotes collided with includes, as the queue predicted but worse. An include
converts its file on its own bytes (ADR-0038), so goldmark numbered its notes
from one again and the page carried two id="fn:1"s — the parent's reference
jumped to the fragment's note. shortcodes.FootnotePrefix stamps the file name on
the nested document and hands it to goldmark's id-prefix function, so the
fragment gets _method-fn:1 and the page keeps fn:1.
Two things nothing tested before. The extender list ships from cmd/khosra, which
no package can import, so the dialect had never been rendered through the list
the binary actually uses — cmd/khosra/wire_test.go now does exactly that,
including that the typographer no longer eats a table's delimiter row. And the
demo carries the dialect and the footnote namespacing as cases, which caught
auto heading ids changing markup in three existing assertions.
The reference theme gains five lines: a rule under each table row, an indent for
definitions, smaller footnotes. core 2790/2800, ext 1058/2000, 34 gates green.
The verified-against sha could only ever be wrong. A commit cannot name itself,
so the line had to be written after the commit it described, which forced a
trailing `state:` commit every time — against conventions.md, which has always
said code, test, state.md row and ADR belong in one commit. Folding those
trailing commits away then left the sha naming a commit that no longer existed.
backup/pre-fold shows the pattern, and 8905686 is the commit that had to name
the survivor afterwards.
Git already knows when each file last changed. The gate now compares the last
commit touching docs/state.md against the last touching a .go file, and the
line is gone. Same intent, nothing to maintain, and no rewrite can invalidate it.
Also records two commit rules the human stated this session: state.md never gets
a commit of its own, and a minor change asked for just after a commit is amended
into it while it is unpushed rather than accumulating as noise.
Per-render reparsing could not keep the site coherent, and did not. Only two of
the four render methods called fresh() — Bundle and Tag never did — so under
-dev on a listing served an edited template while a bundle served the old one.
Verified on the pre-G1 binary: /posts/ answered V2 while /posts/hello/ answered
V1, permanently, not for a window.
Adding the two missing calls would have left four places that must each
remember, and Partial runs during a page's Markdown conversion, so one page could
still mix two themes. So the per-render path is deleted instead: Renderer.reload,
Reload() and fresh() are gone, Refresh is the only thing that replaces a theme,
and -dev on gets its promptness from polling every 250ms. Coherence is now
structural rather than a discipline four methods share.
-poll arrives as ADR-0022 specified it and never delivered: it sets the interval,
and 0 stops watching for an immutable deployment. Watch takes the interval and
settle window as arguments, so the Interval and Settle package variables are
gone and no test mutates package state to control timing.
The theme is reparsed in the watcher's callback rather than inside rebuilder, so
startup parses it exactly once, in New — there is one call site and it is not on
the startup path. The two swaps it leaves are not one transaction; state.md's
latent list carries that gap and its trigger.
Measured on the real binary: bundle, section listing and tag listing all moved
V1 -> V9 together within 1s of editing two templates; -poll 0 served and then
ignored an edit; -dev on -poll 3s kept 3s. core 2780/2800, ext 1027/2000.
The watcher fingerprinted templates/ but a rebuild only re-scanned content, so
editing a template fired a rebuild that changed nothing. ADR-0022 already
promised the opposite — "a template edit in the site root invalidates through
the same path as content" — which makes this a defect against a recorded
decision rather than a missing feature. ADR-0055 records the fix and supersedes
ADR-0048's narrower clause.
The parsed sets and the stylesheet become one parsedTheme behind an
atomic.Pointer, swapped by Refresh once per rebuild instead of per request. A
parse failure keeps the theme that was working, so a typo cannot take the site
down. The swap also retires the in-place field mutation -dev was doing, which
was a data race with every in-flight render.
site.yaml goes the other way and leaves the fingerprint: the settings are copied
by value into the renderer, the handler, the feeds and the sitemap, so applying
a change to some of them is worse than applying it to none. It is restart-only.
Corrects the Effects counter row while proving it did not move: it still said
startup was the only change signal "until queue 21", but queue 21 shipped as
ADR-0048 and put the derivative pass inside rebuilder, so that has been wrong
since. The row now also answers the question ADR-0055 invites — an in-memory
swap is not an Effect, because it writes no artifact and calls nothing outbound.
Measured on the real binary: a template edit went live in ~2s; a typo logged
"keeping the previous theme" and kept answering 200 with the last good markup; a
site.yaml edit now fires no rebuild at all. core 2766/2800, ext 1030/2000,
34 gates green, 0 warnings.
Four small things from one sitting, none of which would be reverted without the
others:
- .claude/launch.json describes the only dev server this repo has: make demo on
localhost:8080. Deliberately not autoPort — examples/demo-site declares
base: http://localhost:8080, so canonical, hreflang, OpenGraph and sitemap URLs
are built from that port, and a reassigned one would make the absolute URLs on
the page wrong while still rendering fine.
- The skill is .claude/skills/feature-loop/, without the khosra- prefix. ADR-0054
records it, because ADR-0030 had named the prefixed form while settling the
project name and decisions.md is append-only.
- Makefile .PHONY was missing quiet and surface, added two commits ago. A file of
either name in the repo root would have silently shadowed the target.
- A latent row: the root listing's title reads "A Khosra Demo · A Khosra Demo",
because base.html joins page title and site title unconditionally and at the
root they are the same string. Found by looking at the served page — no test
asserts a title. Theme layer, one if, and it waits for Phase G4.
Authorship named the human on commits the agent wrote start to finish, with a
Co-Authored-By trailer as the only trace of who did the work. That is backwards:
directing a change is not writing it, and a log that cannot tell the two apart
cannot answer "how much of this did the agent write" — a question worth being
able to ask honestly about a repository built this way.
Three cases, no fourth: agent alone is agent-authored with no trailer, since the
author field already says it; both is the human's with the agent as co-author;
the human alone names only the human. The committer and the GPG signature stay
the human's throughout — the key attests to taking responsibility for a commit,
not to having typed it.
Applied to the whole history in the same sitting: 62 of 63 commits are now
agent-authored, init is the human's with a co-author trailer, and every tree,
message, parent and author date is byte-identical to before. Committer dates were
restored from backup/pre-fold, since the earlier fold had reset all 62 of them to
the moment of the replay.
The state.md sha rides along rather than taking its own commit: rewriting the
history is what invalidated it, and the verify.sh advisory that caught it is the
same one that caught the previous rewrite.
Folding the 24 `state:` commits into the code they described gave every later
commit a new hash, so the verified-against line named 8a2ef08 — a commit only
the backup refs still hold. It is 8900aab in this history. Content unchanged;
the old sha resolved only because backup/pre-fold and origin/main still exist,
which is exactly the kind of advisory that would rot into a lie.
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.
The loop gains a seventh step. Work was being committed all session on a
verbal instruction, which means it was a property of one conversation
rather than of the harness: a fresh session would have left everything in
the working tree and reported success.
Why automatic: a commit is one `git revert` from undone, and work that
only ever existed in the working tree is not recoverable — this session
already lost uncommitted work to a `git checkout` while signing was
broken. Why announced: the safety argument covers the loss, not the
surprise, so a session that did not ask for this gets one prominent line
before the first commit and the off switch, once.
Ownership split so nothing is stated twice: conventions.md "Git" owns
what one commit contains — now one *revertible* unit rather than one
feature, which is the human's correction to the "never bundle two passes"
reading — and CLAUDE.md §4 owns when a commit happens. ADR-0052 records
both, including that no gate can check this: no script can see whether a
sentence was said.
Docs 6 files, +72/-6 lines. No code, no counters moved.
The human asked for a demo extensive enough to review by hand, tracked as files,
and kept current the way docs are. Generated filler cannot be reviewed — you cannot
read a Go function and see what a reader sees — so the generator is deleted and
`examples/demo-site/` is an ordinary site: 33 Markdown files, six pictures,
site.yaml, a template override and static files.
My reason for generating it was ADR-0011, and I had that rule wrong: it puts the
*author's site root* outside this repository, not fixtures. conventions.md already
keeps golden files in testdata/, and this is the same category one size up. Keeping
both a generator and files would have been two sources of truth, so one had to go.
Kept true by two gates rather than by good intentions. A table-driven test in
internal/web serves the directory through the real handler with one case per
feature — thirty-five of them, each naming what it proves — and verify.sh runs
`khosra check` over it and fails on anything fatal. Adding a feature now means
adding it to the demo and adding its case, and the build says so if you don't.
Extensive on purpose: eleven dated posts so a section actually paginates, a
four-chapter series so first/last are not the neighbours, a gallery with three
JPEGs and an SVG so both the resampled and the untouched paths show, a Bengali-only
bundle, a titleless status, a draft, a future date, an include, a nested extras
tree, and a typography page that demonstrates what the engine will not do.
Two expectations of mine were wrong and the demo corrected them: the site's own
list template overrides *tag* listings too, so there are no group headings there —
which turns out to be the better demonstration of ADR-0046, since the theme picking
the flat shape is exactly the point. And template literal text is not escaped, so
an apostrophe stays an apostrophe.
The demo writes a whole site root that exercises every feature: two languages with
a fallback, a series with ordered chapters, a gallery, a figure, an include,
extras, tags across sections, a slug with an alias, an undated page, a draft, a
template override, static files and site.yaml. It generates its filler rather than
copying stored files, because nothing in this repository is content (ADR-0011) — and
that makes it a test of the engine rather than a fixture: anything khosra can do
that the demo cannot express is a gap.
Two things found by generating and then serving it, which is the whole point:
`khosra check` reported the demo's own series as mixing ordered and unordered
members. It was right — the chapter bodies *described* `order: 10` while the
frontmatter never carried it. The checker caught its own author.
And `/` was a **404**. ADR-0008 leaves the root engine-owned, which is right, but
"engine-owned" was never given an answer, so a visitor to the site's own address got
nothing. The root now lists every bundle, newest first, paginated like any other
listing, and 404s only when nothing is published. A hand-written home page stays a
separate decision, recorded as such.
Verified end to end: 23 files written, 12 bundles, 12 derivatives, `check` clean,
and every URL the demo promises answers — including the alias redirecting, the draft
hidden, and the front page rendering through the site's *own* template override.
The theme was supposed to need no engine work. It needed four things, which is
exactly what the audit said would happen if the contract had gaps rather than the
theme (ADR-0046) — a reader could not reach, from any page: another section, the
tags on the page they were reading, the extras beside it, or the same page in
another language.
So the contract grew three fields, all additive: `.Sections` for navigation,
`.Tags` with each term's listing URL, and `.ExtrasURL`, empty when a bundle has
none so a theme never links a 404. Sections arrive through `Renderer.Navigation`, a
callback, because sections change when content does and a copy would go stale — the
nav updates on a rebuild along with everything else.
One flaw only visible by looking at a rendered page: the language switcher pointed
at the canonical host, because `.Alternates` went absolute for hreflang. Those are
two needs, so an Alternate now carries `.URL` (absolute, for machines) and `.Path`
(relative, for a link a person clicks).
The theme now demonstrates every field it is given, including `.First`/`.Last`,
which existed and were never rendered. Still no JavaScript, still one stylesheet.
A test that asserted a page had no sequence nav was matching the inlined
stylesheet rather than the markup, and now matches the element. That is the third
time a loose assertion has passed for the wrong reason.
Polling lives in internal/ext/watch, per the human's call to keep core under its
ceiling rather than raise it a second time — which is what ADR-0041 said a second
raise would mean. It is a poller, deletable without trace, and core stayed at
2671/2800.
A settled change calls the same `rebuilder` that startup calls, because a reload
path that differs from the startup path is a reload path that drifts. The index is
an atomic.Pointer swapped whole, so a request reads the site that was current when
it arrived instead of one being rebuilt underneath it — the alternative, mutating in
place, is a data race with every in-flight request.
Names, sizes and modification times, not contents: reading every file to detect a
change costs more than the rebuild it triggers. Editor droppings are excluded,
because saving in vim writes a swap file, a backup and the number 4913, and each
would otherwise look like a change. A change must hold still for a moment first,
since one save is often several operations.
Verified against the running binary: a page 404s, the file appears, and five seconds
later it serves — one "site root changed" in the log. Then three droppings written
at once produced no rebuild at all.
Two warnings fired and were fixed rather than silenced: `runServe` gave up the
rebuild closure to `rebuilder`, and the fingerprint walk gave up its body to
`record`, where three exclusions read as a list instead of as nesting.
The Dockerfile ships the binary alone. The site root arrives as a volume and is
never copied in — it is somebody's content repository with its own history
(ADR-0011), so the image is the same for every site.
Re-adopts the parked extras entry as ADR-0047: `extras/` inside a bundle is skipped
by the scanner entirely, so a `.md` in there is an asset with no identity and no URL
of its own. The engine enumerates the tree, sorts it by path, classifies by
extension, renders markdown and text, and offers everything else as bytes. One route
with two behaviours — `…/extras/{path}` selects an entry, `?raw` returns the file.
Almost everything it needed already existed, which is the sign the model was right:
the scanner had a directory exclusion, `Assets()` knew which bundles own a
directory, and `Lookup` already decided visibility — so a draft hides its extras
with no new check. A test proves that, including `?raw`.
Two deviations from the parked shape, both because the shape was written before the
code. The directory name is fixed rather than a cascade key, since nothing reads a
section-level setting yet. And an entry is resolved against the *enumeration* rather
than the filesystem: not being in the listing is a stronger answer than os.Root
refusing a path, and cheaper.
Selecting is a link and a full page. No JavaScript is involved, and a
sidebar-and-pane layout is the theme's business — which is the layer rule applied
before writing the feature rather than after.
Three size warnings fired as a result and were fixed by splitting at seams, not by
sharding: render.go gave up its type declarations to view.go, which is the theme
contract in Go and nothing else; serve() split into a dispatcher and serveBundle;
resolve() gave up its language-prefix step to cutLang.
Scaffolds a **directory** bundle — the only shape that can own local files, so the
other kind would hand an author a page their pictures cannot live beside. What it
writes is a draft: title, today's date, `draft: true`. A tool that publishes the
moment it runs publishes by accident, and drafts are honoured now.
This is the first thing that writes into somebody's content directory, so it goes
through os.Root like every read does (ADR-0031), and it never overwrites: an
existing bundle is an error.
Two bugs found by running it rather than by testing it:
A key of `../escape` did not fail. It never left the site root — path.Join collapses
`..` first — but it wrote a real directory *inside* the root and outside content/,
which is not an escape and not a bundle either. Refused outright now, the same guard
the include path needed for the same reason. The test asserts what should be true —
content/ is the only thing this creates — because the weaker assertion I wrote first
would have passed.
`khosra new posts/x -site dir` silently ignored -site, because Go's flag package
stops at the first non-flag argument, and then failed complaining there was no site
root. Parsed in rounds now, so either order works.
main() crossed the function-length warning as a result, so it became a dispatch
table with runServe beside it — the warning was right about the code.
Deleting the widows feature answered one question; the human asked the general one.
So every feature built so far is now audited, with the verdicts as a table in
ADR-0046, and each remaining queue entry carries a layer note before anyone writes
code for it.
The codebase turned out to be otherwise clean, and I checked rather than remembered:
no Go file writes a tag, a class or a style. ADR-0036's rule that all markup comes
from a fragment had already forced that.
One real finding. A tag listing received only `.Groups`, so the engine had decided
that a tag listing *looks* grouped — ADR-0032's own reasoning was "so a busy term
stays readable", which is a readability judgement. It now receives both shapes: the
partition, because a template cannot group for itself, and the flat list, because
choosing between them is markup. `Item` gained `.Section` so a flat listing can still
say where an entry came from.
Two judgement calls recorded rather than left implicit. The typographer stays: turning
`--` into an en dash is a character transformation no stylesheet can express. Chrome
strings stay: translations are data, and the alternative is every theme hardcoding
Bengali month names. The inlined stylesheet is accepted with its cost written down —
bytes per page, no caching — and a trigger for revisiting it.
Two patterns worth reusing came out of this: offer the shape rather than choosing it,
and a split feature is normal — search will be an engine-built index queried by the
browser, not one or the other.
A draft is now not served at all, and neither is a bundle whose date has not
arrived. The filter sits in `Site.Lookup` and `Site.Run`, which is every path to a
bundle — so the files inside an unpublished bundle inherit its status for free,
which is what ADR-0024 asks for and what the asset route was written to allow. A
test asserts the 404 for the bundle *and* its picture, and that nothing leaks into
a listing, a feed or a sitemap.
The clock is read per request rather than at startup, so a scheduled post appears
exactly when its date arrives with nothing to restart and nothing to invalidate.
That first clock read created internal/content/clock.go, which is the only place
`verify.sh` allows `time.Now` — a render that depends on the time is worth being
able to find.
`-dev on` reveals both and reparses the theme before each render. Deliberately not
a bare boolean flag: turning unpublished work into public work should not be one
fumbled argument away. A reload that fails to parse leaves the working template set
in place, so a typo shows an error rather than replacing a good set with a broken one.
The human asked whether widow prevention belonged in the backend at all. It did
not, and it broke two rules already written down: the theme contract says the
engine decides nothing about how something looks, and ADR-0034 says authored body
text is the author's — while this inserted U+00A0 into that text.
The practical harm follows from the layer error rather than from a coding mistake.
The engine cannot see the line box, so joining the last two words is a guess that
can overflow a narrow viewport, and a reader copying the paragraph gets a
non-breaking space in their clipboard. `text-wrap: pretty` and `text-wrap: balance`
in the reference stylesheet know the line box and need no bytes in the content.
108 lines of engine deleted for one CSS declaration. The typographer stays: turning
`--` into an en dash is a text transformation no stylesheet can express, which is
exactly the distinction the new layer test draws.
Also worth recording: this took the Extensions counter from 3 back to 2. A threshold
reached by a feature that should not have existed was never a threshold.
The constitution asks which primitive a feature is. It never asked *where* the
feature belongs, and that let a whole feature get built at the wrong layer.
Four layers, outermost wins: content on disk, engine (facts only the engine can
produce), theme (markup), browser (CSS, then JS). Two rules fall out — the engine
never edits authored text to change how it looks, and a feature needing no engine
fact is not an engine feature. architecture.md carries the table and the test;
CLAUDE.md carries the one-line version, since it is the file always loaded.
The example is named in the docs on purpose. A rule with a scar attached is one an
agent can apply; a rule stated in the abstract gets reasoned around.
The server never fails on a bad bundle — it works around it and logs, which is easy
to miss (ADR-0029). This is the command that looks on purpose, and it exits non-zero
on anything that makes the site wrong rather than merely untidy.
Fatal: content the engine had to drop (unparseable frontmatter, a key two files
claim, an ignored slug or alias) and links that will 404 for a reader. Warnings:
no title, a figure with no alt text, a series where some members declare order and
others do not — that last one because unordered members sort last, so adding order
to one chapter silently moves every chapter that lacks it.
Two things this needed rather than invented. `Scan` and `Site` now *return* what they
worked around instead of only logging it: `ScanReport` and `Site.Problems`, with
`Scan` staying the logging wrapper so nothing else changed. And required-fields-per-type
is deliberately absent — `title` is the only field the engine requires today, so
checking more would mean inventing the type declaration that is still parked. Its
trigger stays where it was.
The link checker asks the same questions the resolver asks — bundle, alias, section
listing, file inside a bundle — because a checker that guesses differently from the
server is worse than no checker. Engine-owned paths are skipped: they are generated,
not authored.
It lives in internal/ext/check, so cmd/ stays wiring and the feature stays deletable.
Verified against the evidence site: clean before, and five findings across five fault
classes after I introduced them on purpose.
The entry said to measure first and put the number in the commit, so: a plain page
renders in 14µs, a twelve-picture gallery in 1.23ms. Of that, ~102µs per picture
was reading, hashing and decoding bytes the previous request had already read.
Remembering that one fact — keyed by path, size and modification time — brings the
same gallery to 63µs. 19.5× faster, 21× fewer bytes allocated, twenty-odd lines.
After which nothing is slow enough to justify caching whole pages, so ADR-0044
declines the page cache and leaves the parked validity model parked, now with a
measurement rather than an intuition behind its trigger.
That parked model has five axes and was written before any code existed. The
problem it would have been built for turned out to be one repeated file read.
Benchmarks live in internal/web so they measure through the real handler, which is
also what conventions.md wants before any cache goes in the render path. The
invalidation risk has its own test: an edited picture is a different key, so the
memo cannot serve yesterday's dimensions. Everything runs clean under -race, since
the map is read by concurrent requests.
Membership is a publication date, not a type declaration (ADR-0043). The parked
feed shape said "every type declared primary", which would have made feeds wait on
declared types a third time — but the thing that distinguishes a feed item is
already on disk. Pages and section landings drop out because they have no date,
which is the right reason. The parked idea stays parked with a sharper trigger:
someone wanting a *dated* bundle kept out.
Built with encoding/xml from typed structs, never a template: XML in html/template
is escaping for the wrong grammar, and that is a correctness trap rather than a
matter of taste.
A bug the evidence found, older than feeds: content.URL("", lang) built "//", so a
whole-site feed's id and alternate link were https://khosra.example// — every
entry identity wrong in every reader. The root is "/" now, with a test, and the
hand-built "/" the resolver carried for the same reason can follow later.
Two counters re-scoped rather than incremented, the same way transforms was:
Views now counts *per-bundle selection* — the thing architecture.md means by the
View layer, still at zero consumers. Output formats are not it: HTML, sitemap XML
and Atom are three functions with nothing to share, so an interface over them
would have one member and no leverage.
Effects stays at 1. A feed is generated per request like the sitemap, so it is not
a second Effect and the runner is not yet due — the next thing that writes files
off the request path is.
Claude Opus 5andbdeshi