078ec8eedfd98aa56c704380ecef3005c22f0ecb
10
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
  bdeshiandClaude Opus 5
|
078ec8eedf
|
check bare paths in scripts/, and record why one file has no .sh
Two answers to "add .sh to sh files". Exactly one file lacks the suffix: scripts/hooks/pre-commit. git locates a hook by exact filename, so renaming it would leave a gate that looks present and does nothing — verified in a throwaway repository, where hooks/pre-commit printed and hooks/pre-commit.sh was ignored while the commit succeeded regardless. The name belongs to git, so the file keeps it and conventions.md now states the exception rather than leaving it as an inconsistency someone will try to tidy again. The extension was never the defect anyway. The dangling-path gate had only ever matched backticked citations, so `git add docs/surface.md` in the hook — an argument, not a citation — survived the docs/ rename and surfaced as a fatal inside a commit that otherwise succeeded. That gate now also reads paths in scripts/ unquoted, which is the check that would have caught it. Proven both ways: restoring the exact bug fails the gate with "reference to a path that does not exist: docs/surface.md", and a working tree passes. The first attempt did not catch it — docs had been dropped from the alternation because the directory no longer exists, which is precisely the class of stale reference worth failing on, so docs is in the bare pattern on purpose. Backslashes are stripped before comparing, so a path written as a regex — \.claude/settings\.json — is checked as the file it means rather than flagged as the file it is not. Prose is still checked only inside backticks: a sentence saying "under harness/" makes a point no filesystem can verify, while a script naming a path either has it right or is broken. One gate label changed with it. `pass "harness/HARNESS.md coupling"` read fine while the directory was docs/ and now parses as a filename, which the new check duly flagged; it is "harness and HARNESS.md move together". No doc cited the old label. 4 files. No rule or threshold moved — one gate widened, one convention written down. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
bdeshiandClaude Opus 5
|
07cf655d09
|
fix the pre-commit hook's path, missed by the rename
ADR-0082 moved docs/ to harness/ and left scripts/hooks/pre-commit staging docs/surface.md. The hook runs on every commit, so the very commit that did the rename hit it: `git add docs/surface.md` failed with a fatal, the commit otherwise succeeded, and surface.md went in only because it had been staged by hand beforehand. The sweep missed it because the file has no extension and the grep that found every other reference was filtered by --include='*.sh'. HARNESS.md now says so where the hook is described, since the next rename will make the same mistake for the same reason. Verified by this commit: the hook ran, regenerated harness/surface.md, and staged it without error. 2 files. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
bdeshiandClaude Opus 5
|
ec6e9838f0
|
rename docs/ to harness/, and reserve docs/ for the reader
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> |
||
|
bdeshiandClaude Opus 5
|
9349c54d2e
|
let a feature own a route, and serve the site's own files at exact paths
Addresses like /.well-known/security.txt are fixed by somebody else's spec. None is a bundle, none belongs under /static/, and core had no way to serve one. This is the trigger the extension registry has been held for, in those words: ADR-0042 called core's generic derived-file route "the seam to revisit when a second feature wants output of its own", and state.md's counter note said to build the registry "when a feature wants a route". Raw passthrough is that feature, so the seam is built rather than worked around. Only Routes, not the seven-field Extension struct extensions.md describes. Five of the other six fields have no implementor and building them would be the speculation rule 6 forbids. It also kept the change inside the core budget, which had 65 lines left: the seam is ~30 core lines and the feature's own code lands in internal/ext/, where there is room. Core is 2965/3000. A feature returns map[string]http.Handler; core mounts each as an exact pattern and learns nothing about who owns it. A path core already answers is skipped with a warning, not overridden — http.ServeMux panics on a duplicate pattern, so a site shipping root/robots.txt would otherwise take the server down at startup. Verified: server alive, engine keeps /robots.txt, warning logged, zero panics. Templating is opt-in by filename. A .tmpl suffix is stripped from the URL and the file is rendered with text/template — never html/template, which would turn an ampersand in a contact address into & and a JSON quote into ". Opt-in by name rather than by sniffing the type, because a key or a signature may contain anything and a pass choosing for itself which files to rewrite would eventually eat one. The data is the site's own declarations and nothing more, which is the point: a security.txt naming its canonical URL should not repeat what site.yaml already says. Headers come from root/_headers.yaml, exact paths only. Globs are a second-use feature and the concrete need is a handful of .well-known names. The manifest is not served, by the leading-underscore rule that already means "not addressable" everywhere else — no special case was added for it. A manifest that will not parse is logged and ignored; the files still serve. Found while counting: the Extensions row read 4 while five packages existed. notation landed in ADR-0061/0062 and was never counted, though the prose beside the number already named all five. Corrected to 6. That is the latent item about counters having no mechanical check, demonstrating itself. Not done, and logged as latent: khosra check cannot report a root/ file shadowing an engine path, because verify.sh fails a feature that imports a sibling and the reserved paths live in passthrough. The startup warning fires on every boot, which is louder than a check finding. Evidence against the demo with a fresh binary: /pubkey answers with its declared text/plain despite having no extension; /.well-known/security.txt answers with Canonical filled from site.yaml's base, plus the declared CORS header; /humans.txt gets a derived type; /_headers.yaml is 404; / and a bundle page are untouched. Eight unit tests cover layout, absence, interpolation, non-escaping, declared and derived headers, a broken template, and a broken manifest. 24 files, +514/-46. Extensions 4 (miscounted) → 6. Routing cases unmoved: exact paths are mux entries, not resolver cases. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
bdeshiandClaude Opus 5
|
64e53f28c8
|
give a page the assets its own content asked for, and write down the rule
Two decisions and one mechanism. The human wants demos, games and runnable
embeds to carry real CSS and JS while every ordinary page stays scriptless, and
wants adding an asset to be theme work rather than a rebuild.
The mechanism reuses what already had that property. A theme defines
`assets:<name>` beside its other fragments; shortcodes record their own name as
they are opened; after conversion the engine renders each matching fragment once
into Page.Assets. So a gallery calling one shortcode forty times carries its
stylesheet once, and a page that called nothing carries nothing. Frontmatter
`use:` reaches the same fragments without a call.
Considered and rejected: templates/assets.yaml, which reads more declaratively
and buys a parser, a contract shape and a rebuild for conditional markup; and a
table in Go mapping shortcode to files, which would hardcode exactly what was
deliberately made data-driven.
Collection is parse-phase, so no transform counter moves — goldmark's extender
list is already the ordered pipeline for parse work, which state.md's counter
says in its "does not count" column.
Separately, styles/scripts are lifted at last. They sat in content-model.md's
table unread, and the theme contract listed them under "what the engine
provides", which was aspirational rather than true. Both are bundle-relative: a
name with .. or a leading / is dropped and logged, the refusal ::include and a
code block's file= already make. The engine builds the URLs because a theme must
not construct an address.
ADR-0080 writes the antifeature list down, with its single exception inside it.
An antifeature nobody recorded does not bind anything, and each of these dies to
one reasonable-looking request at a time. The exception is author-invoked and
cannot fire by accident.
The reference theme emits the stylesheets and no script element at all. That was
the human's correction to a first attempt which had page.html emitting the tag
and verify.sh narrowed to permit it — narrowing the gate to fit the code was
backwards, and the narrowing was also wrong, passing a probe with a hardcoded src
because it filtered whole lines and every line carries {{define}}. verify.sh is
untouched. examples/demo-site redefines the head block instead, so the JavaScript
half is demonstrated by a site rather than built into the binary, which is a
better demonstration and a stronger property.
Evidence, against the demo site with a freshly built binary: the sandbox page
carries its own css and js at bundle-relative URLs; colophon calls ::tally twice
and carries tally.css once with zero scripts; about calls it never and carries
neither; listings unaffected. Plus a table test for the escape refusal, which
until now had only the running server behind it.
19 files, +355/-86. No counter moves. Demo is 31 bundles.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
|
||
|
bdeshiandClaude Opus 5
|
69f43e5791
|
enable task lists, superseding the decision that excluded them
ADR-0058 kept task lists out as "a note-taking affordance, not a publishing one". That reasoning measured the wrong axis: a checklist inside a published technical piece — setup steps, a runbook, a what-I-tried list — is publishing, and nothing else in the dialect expresses "this item is done" without the author hand-writing an entity. ADR-0078 supersedes that half and records why. The half of ADR-0058 that mattered is untouched: extension.GFM stays refused, because the bundle drags linkify in with the tables it is wanted for, and linkify rewrites an author's plain text into markup — the line ADR-0034 draws. One named extension is not a bundle, and wire.go now says so where the temptation to reach for GFM will next appear. ADR-0058's Status line names its successor, so a reader arriving there learns the task-list sentence no longer holds. Same in-place Status annotation the mutability rule allows, Decision text untouched. Checkboxes render disabled: static markup, nothing clickable, nothing stored. A reader with scripting off sees the same page, which is the property the whole theme is built on. goldmark adds no class to the list, so theme.css finds it with :has rather than the engine inventing markup to be styled by. Demo carries the case ADR-0051 requires — a colophon checklist of what this build does and does not do, including the unticked "ship a single byte of JavaScript", which is true of that page and asserted by the test's absent list. No counter moves: state.md's counters are explicit that an upstream extension enabled in the list is dialect, not a feature of this engine — only a package under internal/ext/ counts. 8 files, +55/-10. 1 line of engine code. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
bdeshiandClaude Opus 5
|
4fff6fcd43
|
stop the harness deferring to a marker system it deleted
/refresh-docs step 4 told the agent to check content-model.md's `[spec]` versus
`[live]` markers. The `[spec]`/`[arc1]` system was deleted in
|
||
|
bdeshiandClaude Opus 5
|
be92b4b957
|
correct five claims about behaviour this engine does not have
All five were found by checking content-model.md against the parser rather than by any gate, which is the point: verify.sh catches a dangling path and a missing ADR number, never a sentence that is merely untrue. The Scaffolding section documented `khosra demo <empty dir>` writing a generated site. ADR-0051 deleted that generator eleven commits ago in favour of the tracked site in examples/, so the paragraph described a subcommand main.go never dispatched — and justified itself with "nothing in the engine repository is content", which the committed demo site contradicts. Deleted rather than rewritten: what the demo is belongs to state.md's inventory, and restating it here would have broken the single-source rule to fix a smaller problem. ADR-0050 is where that claim originated and it still read "Status: accepted", so a reader arriving there had no way to learn the generator was gone. Its Status line now names ADR-0051 as superseding that half. This deviates from decisions.md being append-only, so the exception is recorded in the mutability column where the convention lives: a Status line may be annotated in place, the Decision text never. "The parser does not read `slug` yet" was false and contradicted by the frontmatter table twelve lines above it in the same file. Deleted. The Sequences section and the Sequence doc comment both said `draft` is not honoured "because no bundle carries it yet". Two errors: the demo site carries one, and draft is honoured — membership resolves through Lookup, which is the single place ADR-0024 hides unpublished bundles. The doc now says what actually happens, including that prev/next closes over the gap. state.md said draft "lands in Extra unread". It is lifted to Bundle.Draft and deleted from Extra, and content_test.go already asserted it. Evidence: a three-chapter series with a draft middle, served by a freshly built binary. The landing lists First Rain and Third Rain; chapter one's next points at three/, not two/; the draft's own URL is 404. That absence has no test, so it is now a latent item with the reason it is safe by construction. 6 files, +25/-25. No counter moves. surface.md regenerated: the comment gained a line and shifted ten declaration numbers. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
bdeshiandClaude Opus 5
|
8f5d479f06
|
stop the handoff outranking the log, and gate the pointers into it
A session picked up work from .scratch/continue.md and offered the human a doc trim that was already in HEAD. The handoff was written at 01:06 saying the trim awaited a yes; the commit containing the trim was amended at 01:12, underneath it. Five defects made that possible, and four of them are the harness's. The read order inverted trust: docs/README.md sent the next session to the handoff "if present, otherwise git log" — consulting the one ungated file instead of the record that cannot lie, which is backwards from every other rule here, where the code beats state.md and generated surface.md beats memory. The handoff is now step 4 of CLAUDE.md's read order, explicitly after the harness and never instead of it, and anything it calls pending is checked with git log -- <path> first. The tick fired too early. "A planned item completed → tick it in continue.md" sat in the Document step, so it recorded the plan's version of events while the commit could still move; an amend, a squash or a late fix moves it. Reconciling now happens after the commit exists, and a completed item is deleted rather than ticked, because a ticked item still reads as an item. HARNESS.md authorised the drift outright — it said the file holds "what is done", which is exactly what continue.md's own header promises it never records. It is now described as what it is: a temporary handoff, uncommitted, ungated, discardable, holding the continuation point and the carried findings. state.md still pointed at .scratch/build-queue.md, replaced two commits earlier. The dangling-path gate missed it because .scratch was absent from its alternation, so no pointer into the handoff directory was ever checked. It is included now, guarded on the directory existing — a fresh clone has no handoff and must stay green. Both directions were run: present with a stale pointer fails, absent with docs naming it passes. The gate then flagged its own explanatory comment, which is why that one path is written without backticks. No gate can compare an uncommitted file against anything, so the file's job is narrowed instead of enforced, and HARNESS.md now says which mechanism stands in for the missing gate rather than implying one exists. 6 files, +47/-9. No rule, threshold or counter moved. CLAUDE.md 138 → 142 of 150. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |
||
|
bdeshiandClaude Opus 5
|
02268f9121
|
init
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> |