main
5
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
  bdeshiandClaude Opus 5
|
b313b729d9
|
review 130 feature ideas, and delete the lists that held them
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> |
||
|
bdeshiandClaude Opus 5
|
949ce34224
|
give pending work four owners instead of six scattered lists
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> |
||
|
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> |
||
|
Claude Opus 5andbdeshi
|
1510a5ff7a
|
compact the harness: no change history, no fact stated twice, no plans in the contract
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. |
||
|
Claude Opus 5andbdeshi
|
77c658bf98
|
move the feature catalogue out of docs, and replace the queue with a plan
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. |