sherd 0.6.0

two-axis federation of SPEC.md and source over a dir DAG, for small-context local models
Documentation
# SPEC

## §G GOAL

Brownfield on-ramp. A foreign single-file `SPEC.md` → a federation, rows MOVED ⊥ retyped.

MOTIVATING SHAPE: `init` REFUSES a file that exists & `split` proposes from CODE & never writes ∴ a repo that already HAS a spec — every repo but this one — has ⊥ a path in. the fleet is ~80 repos on one pin & each carries one monolith.

## §N NAV

rel|path|lens
up|.|-
up|src|code nodes — tokens, spec, fed, lens facades & logic
self|src/adopt|foreign single-file spec → federation: row placement, citation rewrite, conservation
sib|src/tokens|-
sib|src/spec|-
sib|src/split|-
sib|src/fed|-
sib|src/lens|-
sib|src/ollama|-
sib|src/tdd|-
sib|src/plan|-
sib|src/wave|-
sib|src/review|-
sib|src/state|-
sib|src/slice|-
sib|src/land|-
sib|src/cli|-
sib|src/code|-
sib|src/debt|-
sib|src/assay|-
sib|src/git|-

## §V INVARIANTS

V1: adoption CONSERVES. ∀ row of the source spec lands EXACTLY ONCE — one node, ⊥ zero & ⊥ two — & the counts in/out are REPORTED, ⊥ assumed. a dropped `§B` row drops the memory of a defect & a COPIED `§V` makes 2 rules that drift, which is the defect federation exists to REMOVE
V2: PLACEMENT is a JUDGEMENT & stays one. the verb PROPOSES a row→node map & writes only from a map handed BACK, exactly as `split` refuses `--apply`. a row 2 nodes cite goes to their common ANCESTOR; a row nobody claims stays @ ROOT & is NAMED there, ⊥ left quietly
V3: a proposed HOME ! be a node the `§F` tables already DECLARE (`src/fed:V11`, `src/fed:V12`). adoption places ROWS onto structure that EXISTS — inventing an edge here defeats exhaustive & disjoint at once, & silently
V4: a MOVED id keeps its NUMBER & gains a NAMESPACE — bare `V9` → `` `NODE:V9` `` (`src/spec:V7`), the owner UPPERCASE here ∵ a lowercase one is what MAKES a citation & this line would then cite a node named `node`. ⊥ RENUMBERING, EVER: every citation elsewhere already names the old number. the FOREIGN slash form (`microlith/V14`) names another repo & is untouched
V5: the OUTPUT is CHECKED before it is offered & the measure is the DELTA, ⊥ the total: a migration ! ADD a violation, & one the tree already CARRIED is the tree's own — REPORTED, ⊥ repaired & ⊥ blamed on the move. a migration whose result the project's own checker rejects has shipped a 2nd dialect (`src/spec:V6` one verb over, & that same test caught a scaffold prompt being read as a citation) — but a brownfield spec generally does ⊥ pass `check` ALREADY, & gating on the total refuses every repo the verb exists for (B1)
V6: adoption is RERUNNABLE. a 2nd run over a migrated tree finds ⊥ to move & says so, exit 0. a foreign repo is EDITED between the proposal & the apply ∴ a verb unsafe to repeat is a verb nobody dares finish
V7: a RECEIVING node gets rows IN ID ORDER — ∀ moved row lands before the 1st resident row numbered higher, ⊥ appended. the receiver already HAS rows once a federation grows past its 1st adoption, & `microlith/V14` checks their order ∴ an append makes V5 refuse a migration over an order the verb itself wrote (B3)
V8: `0 rows read` from a source this reader cannot PARSE is ⊥ the same answer as `0 rows read` from one it parsed — the 1st is checked BEFORE any count is printed & exits 2 (USAGE: the file is in a form the verb does ⊥ accept), the 2nd keeps exit 0 meaning "I read this & there is nothing to move" (`src/spec:V9`, B4). ONE reading, ∀ invocation — propose & `--map` alike, ∵ a path that skips it is the bug back
V9: a MILESTONE RANGE (`T1-T3`) the map would SPLIT is refused UP FRONT & the cell is quoted, ⊥ expanded here: which node keeps the row once its ids land in 2 is a READER's judgement (V2's rule, 1 column over). the citation rewrite works token-by-token ∴ a range becomes `` `CHILD:T1` ``-`T3` & `check` then reports a SYMPTOM 3 steps from the cause (B5). a range NOBODY moves is left alone, or V6's rerun fails forever
V10: a row that CITES a script is claimed by the node that OWNS it, before any lens word is read. citation = `src/split:V7`'s reading (path suffix, or a basename naming exactly 1 script), ONE function shared w/ `split`, ⊥ a copy. a script's owner = the DEEPEST declared node whose dir contains it (`src/fed:V15`'s rule, applied to scripts). ALL resolved scripts in 1 non-root node → that node, the script paths as `why` · in 2+ nodes, or any @ root → ⊥ single home ∴ unplaced, as a tie (V2, T8) · no resolvable script → the lens, unchanged. ∵ the lens matches 4-letter words & a cited script is where the code that row governs LIVES. MEASURED on a shell consumer: 829 of ~1,700 rows cite a script, 233 of 274 cited names resolve to 1 file (#94)
V11: the SOURCE is the NAMED dir's `SPEC.md` — `adopt a/b` reads `a/b/SPEC.md`, `adopt .` the root's — & a home ! be a declared node strictly BELOW it (V3, 1 level down the tree). "stays @ ROOT" (V2) reads "stays @ the SOURCE". the REWRITE is TREE-WIDE: a citation `` `A/B:V9` `` anywhere becomes `` `A/B/X:V9` `` once V9 moves to `a/b/x` (owners UPPER here, V4), & BARE `V9` inside `a/b/x` ∵ there it names its own row. a node the move does ⊥ write into still gets its citations rewritten, or they dangle (B6)

## §T TASKS

id|status|task|cites
T8|.|V2's COMMON ANCESTOR half — a row 2 nodes claim EQUALLY lands @ root today, ⊥ @ the node ABOVE both. `src/parse` & `src/render` tying should mean `src`, & sending it to `.` files a rule about rendering next to the repo's goal. the tie is already DETECTED (`best` returns none on it) ∴ what is missing is the walk up, ⊥ the signal|V2,`src/fed:T10`
T9|.|test file(s) over the 2,000 ceiling since `.:T108` gave `src/adopt` its tree: `tests/adopt.rs` 3,496. split by subject|`.:V50`,`.:V124`

## §B BUGS

id|date|cause|fix
B1|2026-08-25|`checked()` gated on the TOTAL violation count of each output ∴ the 1st real migration attempt — `ashlar`, 85 rows, the 4th foreign repo this project has learned from — was REFUSED, & the 2 violations it named (`` `B2` sorts before `B3` above it ``, & the same for `B1`) were in ashlar's monolith BEFORE the verb ran: its `§B` rows are filed newest-first, which `microlith/V14` forbids. the verb would ⊥ have migrated a single repo in the fleet, ∵ a spec that already passes `check` is a spec that has already been federated. found by RUNNING it on a real repo, ⊥ by any test — the fixture was written well-formed ∵ I wrote it|V5 restated on the DELTA: `introduced()` subtracts what the file already carried, COUNTED ⊥ set-deduped so a doubled message is still new, & `Report.carried` names the pre-existing ones so they are reported rather than absorbed. GENERALLY: a tool for brownfield trees ! be tested against a tree that is actually brown — a fixture the author wrote is a fixture that meets the author's standards
B2|2026-08-25|placement scored the row's RAW TEXT ∴ requalification fed the next proposal: a moved row's cites gain the destination's PATH (`` `GIT:V2` `` w/ the owner spelled UPPER here, ∵ the lower form is a live citation & this row would then cite `ashlar`'s tree), `significant()` splits on non-alphanumerics ∴ the dir NAME becomes a WORD of the row, & it matches that node's own lens. a rerun over the migrated `ashlar` proposed 20 MORE moves — 0 of them earned, every one justified by a path the previous run wrote. V6 says a 2nd run finds ⊥ to move & the 2nd run found 20. found by RUNNING it twice on a real repo; the fixture is 6 rows & its 2nd run happened to be clean|V2's matching now scores the SUBJECT — `subject()` drops backticked `owner:ID` spans before words are taken, ∵ a citation is a LINK ⊥ a subject. GENERALLY: a tool that REWRITES its own input ! be measured on the rewritten form — idempotence is a property of the 2nd run, & `.:V118` already names WRITE as one of its 3 layers
B3|2026-09-19|`add_rows()` APPENDED the batch after a section's resident rows ∴ adopting onto a node that already held `T88` put a moved `T3` below it, & V5's delta check refused the WHOLE migration: `` `T3` sorts before `T88` above it ``. the 1st adoption never shows it — every receiver is a fresh scaffold w/ ⊥ rows — & every fixture is a 1st adoption. found by RUNNING a 2nd adoption on a federation that had grown since its 1st, in a repo outside the fleet's usual set|V7: `in_id_order()` inserts each received row before the 1st resident row numbered higher; non-row lines keep their place. GENERALLY: a fixture of the 1st run cannot catch what only the Nth run meets — `received_rows_land_in_id_order_among_resident_rows` seeds resident rows
B4|2026-09-20|`adopt --check` over a `SPEC.md` whose `§T` is written as a BRACKETED markdown table (`\| T1 \| . \| first task \| -\|`) reported `0 rows read · 0 placed · 0 unplaced`, exit 0 — & in this verb's exit scheme 0 means "⊥ to move" ∴ a repo being WEIGHED for adoption read as ALREADY FEDERATED, the opposite of the truth, in the same words & the same code as the honest answer. `spec::rows()` anchors an id @ the START of a line (`microlith`'s grammar, correctly) ∴ the bracketed dialect is PROSE to it & the file reads EMPTY. MEASURED on a 2-row fixture: 2 id-shaped rows in, 0 read, exit 0 — & `sherd check` said `1 nodes examined · 0 violations` over the same file, so nothing in the toolchain dissented. this is `src/fed:B6`'s shape (something that finds nothing passes cleanly) @ the 1 verb whose whole job is reading a STRANGER's spec|V8 & `src/spec:V9`: a DETECTOR for the id-shaped row this grammar declines, checked before any count & exiting 2 w/ the line numbers & the form that works. `M` is excluded by construction — `row_id()` does ⊥ own it & `microlith::milestones` reads that table. GENERALLY: a reader that cannot parse its input ! say so, ∵ EMPTY & UNREADABLE are different answers & the 2nd is ⊥ a quieter version of the 1st
B5|2026-09-20|`adopt --map` over a monolith whose milestone row lists a RANGE — `\| M1 \| … \| T1-T3 \|`, the form `microlith/V15` documents as the CHEAP way to maintain the column ∴ the form a brownfield spec most likely carries — wrote NOTHING & refused w/ `microlith/V15: T3 is in no milestone`. the rewrite that namespaces moved ids walks TOKEN by token ∴ `T1-T3` became `` `CHILD:T1` ``-`T3`, which expands to NO tasks, ∴ the last root row is claimed by no milestone & THAT is what got reported — a symptom 3 steps from the cause, naming a row that never moved. MEASURED on a 3-row fixture (sherd 0.5.0, microlith 0.7.0): range → rc=1 & 0 files; the same repro w/ `T1, T2, T3` → 3 moved, 2 files written ∴ the shape most likely to be adopted was the 1 shape adopt refused, & for a reason its own message did ⊥ name|V9 & `src/spec:V10`: the gap between what a row CLAIMS & what it SAYS detects the range w/o re-reading the range grammar, & the refusal QUOTES the cell. ⊥ expanded automatically: the ids of 1 milestone may land in 2 nodes & which keeps the row — or whether the table leaves `SPEC.md` entirely, as this repo's own reporter did — is a reader's call. GENERALLY: a rewrite that walks TOKENS silently breaks every construct built from more than one, & the checker downstream reports where the damage SHOWS, ⊥ where it was done
B6|2026-10-03|`adopt <dir>` IGNORED `<dir>`: dispatch handed `adopt_cmd` the repo root & `read_source` read `root/SPEC.md` ∴ whatever dir was named, the source was the ROOT spec & every mapped id living in `a/b/SPEC.md` was refused `the source declares no V94`. a 2nd-level split had no path. MEASURED on a consumer: a node of 535 rows (~119k tok own) split into 10 family children OUTSIDE sherd — 417 rows moved & ~2,300 citations rewritten by script, then every `path:ID` verified by hand. the rewrite also only ever touched the source & the receivers ∴ a 3rd node citing a moved root row in the `.:` form dangled after it moved, & nothing checked it (#104)|V11. source & home set derived from the named node; citations rewritten in every node, & every rewritten file goes through V5's delta check. GENERALLY: a verb taking a `<dir>` argument ! be tested w/ a dir that is ⊥ the root, or the argument is decoration