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

`SPEC.md` structure. Sole call site for `microlith`.

## §N NAV

rel|path|lens
up|.|-
up|src|code nodes — tokens, spec, fed, lens facades & logic
self|src/spec|`microlith` facade, §-section split, structural check, fmt
sib|src/tokens|-
sib|src/split|-
sib|src/fed|-
sib|src/adopt|-
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|-

## §C CONSTRAINTS

- ⊥ reimpl parse, fmt, id, citation check — `microlith` owns them, zero-dep pure fn (R3).
- `microlith::` named here & nowhere else (`.:V72`).

## §V INVARIANTS

V1: what `microlith` owns is ADAPTED, ⊥ reimplemented. two implementations of one format is the defect `microlith` exists to end
V2: `§F`/`§N` ⊥ belong here — they are sherd additions, they live in `fed`
V3: parity vs `microlith` ! be MEASURED before claiming absorption (`.:V59`). currently BELIEF
V5: what is imported from `microlith` is what its ROOT re-exports. an inner module path is ⊥ contract — the dep may privatize it & does (E0603, B1). same for RENDERING: print the dep's own `Display`, ⊥ recompose its parts
V4: a `§B` row whose fix names no `§V` is UNREFLECTED — pain w/o reflection. it will recur & the log becomes a list of things that happened, ⊥ a set of guards. advisory: some bugs warrant no rule & forcing one manufactures invariants to silence a gate
V6: a SCAFFOLD emits ⊥ ids & ⊥ inference. a seeded `T1` is `T1` FOREVER (ids monotonic, never reused) & a task citing a placeholder rule is a spec that lies from commit one ∴ prompts are PROSE a human replaces. `§G` is never guessed from a dir name, & an `§F` row's owns/⊥owns are prompts, ⊥ a model's guess. its own test is `check` on the output: a generator whose output its checker rejects has shipped a 2nd dialect — & that test caught the prompt "numbered from V1" being read as a CITATION
V7: a CITATION is a LINK & `check` resolves it. canonical owner is the node PATH from root — `.` for root, `src/tdd` for a node — ∵ `.:V10` already said so & nothing enforced it: 3 spellings ran side by side (`src/tdd` 31 · `tdd` 20 · `sherd/fed` 2) & 24 bare ones named a dir that ⊥ exist. the FOREIGN form is a SLASH — `microlith/V14` names a rule in another repo ∴ ⊥ resolvable here & never rewritten. a DEAD id may be named only in PROSE, never in citation form: quoting a dead id in citation form inside the row that RECORDS it makes the record itself a dangling link — this checker flagged its own author for that, twice, within the hour
V8: a BULLET declares the id it opens with — `- C1:` in `§C`, `- I2:` in `§I` — exactly as a row line does, ∵ FORMAT.md writes both sections as bullet lists & `citation_at` already ACCEPTS `C` & `I` ∴ a citation the parser takes ! be one `check` can resolve. prose mentioning an id mid-line ⊥ declares it (B4)
V9: a line an id does ⊥ OPEN but that CARRIES one in a bracketed table cell (`| T1 | . | task | - |`) is UNREADABLE, ⊥ absent — `unreadable_rows()` names it & the LINE it sits on. the id shape is `row_id()`'s, handed the terminator it would have had, ⊥ a 2nd reading of it (V1) ∴ `M` stays out: `microlith::milestones` reads that table & flagging it would refuse every spec keeping one (`src/adopt:B4`)
V10: a milestone row has 2 readings & BOTH are needed — what it CLAIMS (`milestones()`, ranges EXPANDED, microlith's) & what it SAYS (`milestone_cells()`, the cell AS WRITTEN). they differ exactly when a RANGE is in play ∴ the gap IS the detector, & a message quotes the cell a reader would search for (`src/adopt:B5`)
V11: `rule_depth` keeps only REMAINING work in `§T`: a row `x` (done) & an `ARCHIVED` stub ⊥ ship in a pack ∵ `src/fed:V9` already reads §T as remaining work & a done row bills every worker for history. the FILE keeps them ∴ `check` still resolves a citation to a finished row; only the pack drops them.
V12: `upsert_section` trims a section's heading & body AS ONE, then joins w/ exactly 1 blank line ∴ an EMPTY section is its heading alone & ⊥ run of 2 blank lines anywhere (markdownlint MD012). a hand-collapsed file reads back unchanged ∴ `sync --check` & the linter agree (B5)

## §T TASKS

id|status|task|cites
T2|.|capability-parity audit vs `microlith`, written down|V3
T3|.|`--records` baseline wiring for closed-option survival|V1
T4|.|check closed-option records survive an edit, via `--records`|`.:V44`
T5|.|`SPEC.why.md` format — one rationale per `§V`/`§B` id|`.:V43`
T10|.|test file(s) over the 2,000 ceiling since `.:T108` gave `src/spec` its tree: `tests/spec.rs` 2,221. split by subject|`.:V50`,`.:V124`

## §B BUGS

id|date|cause|fix
B1|2026-08-05|facade re-exported through the dep's INNER path — `microlith::violation::{Violation, NAMESPACE}` — & `check` recomposed `{NAMESPACE}/{rule}: {msg}`, which `Violation: Display` already prints. the dep trimmed its lib to root verbs ∴ E0603 & a HEAD that ⊥ compile (`.:B5`). the recomposition was a 2nd reading of an id the dep owns — V1 applied to output, ⊥ only to logic|import `microlith::Violation`; print `{v}` w/ the caller's coords prefixed. V5, runner @ T7
B2|2026-08-23|the anchor CITATION has 3 spellings in source & nothing rejects any of them: `src/tdd` 19 · `tdd` 3 · `src/fed` 14 · `sherd/fed` 2 · `fed` 1 · `src/cli` 14 · `cli` 2, & `assay` 8 / `plan` 7 appear ONLY bare. 24 of 81 citations are non-canonical ∴ any tool reading them UNDER-COUNTS silently — & `src/split:V4` rests the whole `--apply` design on the qualified form being reliable, while `src/split:V6` reads these same citations as a migration & split signal. found by grepping source for anchors, ⊥ by `check`, which validates that a `§B` names a `§V` (V4) & never that the NAME resolves|V7. `spec::citations` parses `owner:ID`, `spec::declares` answers whether a spec holds that row, & `check` resolves every one. FIXED: 24 bare citations canonicalized to `src/X`, the one bare-`microlith` owner rewritten to the slash form, & the root `V41` — cited from 4 files SINCE THE FIRST COMMIT, never written, no history of it ever existing — became `src/cli:V14`, the shim rule nobody had written down. 38 dead links, 0 after. GENERALLY: a link nothing resolves is a comment, & `.:V10` had stated the form for weeks w/ nothing reading it
B3|2026-08-23|deleting 106 finished `§T` rows broke 10 CITATIONS in one command — 6 of them — root `T79`·`T82`·`T83`·`T84`·`T97` & `dev` `T2` — were cited as PROVENANCE by rows that survived, & `src/assay:T4` turned out to name 2 experiments as "remaining" that had both already run. caught by V7's resolver, ONE COMMIT after it was built & by nothing else|V7. each citation repointed at the `§R` row that HOLDS the finding — the §R text already named the experiment in prose ∴ nothing was lost, & `src/tdd:V28` dropped its citation entirely ∵ it carries the measurement itself & names the commit. GENERALLY: a row may be DELETED only once what cites it points somewhere that survives, & the checker that proves it is the same one V7 built
B4|2026-09-19|`declares()` matched only a line OPENING w/ the id, while `citation_at` accepts `C` & `I` ids ∴ `` `NODE:C1` `` pointing at a real `- C1:` bullet was reported `resolves to no row` — the parser took a citation `check` could never resolve, & bare `C` ids went unchecked ∴ constraints were uncitable across nodes. found splitting a monolith's `§C` across nodes: every moved constraint became uncitable from its old neighbours|V8: `declares()` reads past a leading `- `. GENERALLY: the grammar a PARSER accepts & the grammar a RESOLVER declares ! be the same set — `a_bullet_declares_the_id_it_opens_with` pins both `C` & `I`
B5|2026-10-03|`upsert_section` rendered a section as `heading\n` + its body trimmed, & an EMPTY section's body trims to nothing ∴ the heading kept its own newline & the `\n\n` join added 2 more → 2 blank lines under every empty `§V`/`§T`/`§B`. markdownlint MD012 refuses that, & collapsing it by hand made `sync --check` report STALE ∴ a repo that lints Markdown could commit neither form. MEASURED on a consumer: 9 node specs scaffolded from `init`'s layout, every one w/ an empty section hit it; workaround was deleting the empty sections (#106)|V12. heading & body trimmed together. GENERALLY: a joiner that owns the spacing between parts needs every part to carry NONE of its own, & the empty part is where that shows