# SPEC
## §G GOAL
Federation edges. `§F` table, parent→child, chain to a node.
## §N NAV
rel|path|lens
up|.|-
up|src|code nodes — tokens, spec, fed, lens facades & logic
self|src/fed|`§F` parse, edges, chain root→node, `SPEC.md` discovery
sib|src/tokens|-
sib|src/spec|-
sib|src/split|-
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|-
## §V INVARIANTS
V1: `§F` row = `dir|owns|⊥owns|tokens`. 4 cells or ⊥ a row
V2: edge depth = parent + 1 exactly. ⊥ skip levels
V3: `⊥owns` ! present — positive lens decides DESCEND, negative one decides STOP. the negative is the byte that prevents loading
V4: the row codec is `microlith::cells`+`unescape`+`escape` — the grammar is UPSTREAM's ∴ so is the code (`src/spec:V1`, `src/spec:V5`; `microlith/V38`). what stays here is `fed`'s SHAPE, ⊥ the grammar: the trim & the owned cell. this node's own reading cost B11·B12·B13, & the rule it was reading (`\` escapes the next char only when that char is `\` | `|`, literal elsewhere ∴ `C:\path` survives & a cell may END in a backslash) is now cited, ⊥ restated
V5: `tokens` = `-` means UNRECORDED, ⊥ zero
V6: header row (`dir|owns|…`) ⊥ an edge
V7: `§F` parse stops @ next `## §` header
V8: ignore globs — the fixed list (`is_ignored_dir`: `target/`, `.git/`, `node_modules/`, `.direnv/`, …) ⊥ walked, ALWAYS, tracked or ⊥. inside a git work tree what git ignores ⊥ walked too (V22)
V9: a `§T` row states REMAINING work, ⊥ history. "`X` landed, `Y` still open" reads to a machine as "test `X`" & `X` already passes ∴ ⊥ a red test (`.:plan` B2). what landed lives in the commit trail. an ARCHIVE STUB (`id|x|ARCHIVED to SPEC-ARCHIVE.md|cites`, written by `mth archive`) ⊥ history: its text MOVED, & the row stays so a milestone still finds it & every citation still resolves (`microlith/V48`) ∴ ⊥ flagged (B14)
V10: a detector's test ! include a POSITIVE case. asserting only that nothing was found is satisfied by a fn that always finds nothing (B6)
V11: sibling `§F` lenses ! EXHAUSTIVE — every child dir on disk appears as a row. a child absent from `§F` is unreachable by descent & invisible to a reader who trusts the table
V12: sibling `§F` lenses ! DISJOINT — 2 rows ⊥ name the same `dir`. a duplicate makes descent ambiguous & `route` would have to open both
V14: a finished `§T` row is HISTORY & rule depth LOADS `§T` ∴ every chain pays it every turn — MEASURED 106 done rows tree-wide, 45 @ root, & deleting them dropped root 12,420 → 9,922 & the repo 228,835 → 184,174 tok (19%). V9 said this & nothing read it until `check` counted. what a done row CARRIES moves 1st: a measurement → `§R`, which rule depth does ⊥ load ∴ the finding is kept FREE & only the row is paid (`.:R56` came out of a done root `T96` that way)
V15: a `.rs` file (& a `*.sh`, `owned_script_files`) belongs to the NEAREST node above it & to ⊥ ancestor. nodes NEST ∴ unattributed, `src` owns every sibling's file & the root owns the crate, & a report built on that says the root declares every type & depends on everything. a dir that is ⊥ a node ! still reach the node above it, ⊥ vanish (`.:V16`). `seam` & `wave` both ask ∴ it lives w/ the walk, ⊥ in a caller
V13: a parser's test ! cover the char it CONSUMES, ⊥ only the sequence it documents. `escaped_pipe_stays_in_the_cell` covers `\|` & nothing covered a LONE `\` ∴ `split_row()` ate backslashes for the project's whole life behind a green suite (B11). B6 is the same shape — a case nothing asserts is a case that passes
V16: a `§N` lens is a `§F` CELL & is WRITTEN BACK as one — `escape_cell()` is V4's codec in reverse, i.e. `microlith::escape` ∴ `split_row(nav_section(x))` returns `x` (B13). the ROUND TRIP is the assertion, AND the bytes: `microlith::escape` writes the SHORTEST form since `microlith/B44` (0.7.4) ∴ a cell authored in it — `x \& y`, `C:\path` — is copied into `§N` BYTE FOR BYTE (V21). the doubling of every `\` that came before was a 2nd spelling of 1 cell & made `§N` disagree w/ its `§F` (B17)
V17: ONE codec, used in BOTH directions. a reader & a writer that are 2 readings of 1 sentence drift, & B13 is this node's recording of it — `nav_section()` wrote raw while `split_row()` unescaped, & 17 files carried the extra column. importing a codec the upstream EXPORTS as a set (its `B36`: a pipe row is the 1 construct a consumer cannot avoid re-reading) is how that stops being possible, ⊥ a rule to remember
V18: a node is findable by the NAME a reader typed — `spelled()` matches a trailing run of components over `discover()`, & reads ⊥ the CWD ∴ the answer is the same wherever it was typed. it answers a MISS & never CHOOSES: the exact spelling is excluded (it is the one that worked), & 2 nodes ending in 1 name are both returned (`src/cli:V17`)
V19: ignore globs (`target/`, `.git/`, & git's ignore rules per V22) ⊥ walked, ⊥ ceiling-checked. per-FILE ignores too (generated, vendored)
V20: root `§N` — `up` = `-`, `self` = `.`, ⊥ sib
V21: `§N`.lens of `up`|`self` = verbatim copy of that dir's `§F`-row lens. single source. `sib` → V24
V22: a node is a `SPEC.md` git does ⊥ ignore. inside a work tree every walk here — `discover`, the V11 child scan, `rust_files`, `script_files` — skips what `git ls-files --others --ignored --exclude-standard --directory` names, asked ONCE per walk through `src/git` (`src/git:V3`). ⊥ a work tree, or ⊥ git ⇒ the fixed list alone, i.e. the behaviour before. the fixed list is a FLOOR, ⊥ replaced: a tracked `vendor/` stays out (B15)
V23: a node's spec is the file named EXACTLY `SPEC.md`, compared by NAME from `read_dir`, ⊥ by `is_file()` on a joined path — a case-insensitive filesystem (macOS, Windows) answers `is_file()` for `spec.md` too ∴ the same tree federates differently per OS. ONE predicate (`is_node`) for every 'is this dir a node' question (B16)
V24: `sib` row lens = `-`. N co-children ⊥ N×(N−1) copies of N texts: the parent is in every chain & its `§F` holds each once. `sync --check` still flags a missing|extra `sib` (`.:V34`)
## §T TASKS
id|status|task|cites
T4|~|cycle detection over the federation DAG|V2
T8|.|orphan check — a `SPEC.md` no parent `§F` row points at|`.:V3`
T9|.|needs a query→child match rule before it has a signature|`.:V19`
T10|.|promote an invariant from a leaf to the common ancestor|`.:V13`
T11|.|report `§N` that differs from what `§F` derives|`.:V36`
T12|.|BLOCKED — needs Rust source, ⊥ `§F` data. see B9|`.:V73`
T13|~|replace the hand-rolled walk with `itok::walk`/`itok::glob`|`src/fed:V19`
T14|.|blocked — recomputing needs `crate::tokens`, ⊥ in this node's surface. see B10|`.:V21`
T15|.|fixture: 4 levels deep, one module with two parents — self-repo is a tree|`.:V4`
T16|.|parse `§N` rows, line-anchored|`.:V34`
T18|.|`tests/fed.rs` holds 3,649 tok of tests against the 2,000 ceiling — 19 tests over `§F` parsing, discovery, chains & the structural checks, 1 file since `.:T108` gave the node its tree. split by subject|`.:V50`,`.:V124`
## §B BUGS
id|date|cause|fix
B1|2026-08-01|FIXED by replacement. `find_depth_violations` (LLM-authored) hand-rolled its own recursive walk w/ ⊥ ignore globs ∴ descends `target/`, `.git/` — violates `src/fed:V19`. also a 2nd walker in the module that already has `walk()`, the two-readings defect, in the file whose own B-log names it|reuse `discover()`. FIRST CAUSE WRONG: I recorded 'it was ⊥ in the step-2 surface'. VERIFIED FALSE — `discover()` & `walk()` were BOTH in the prompt. the model saw them & duplicated anyway ∴ cause is that nothing ASKED it to reuse. `.:V59` on my own bug record
B2|2026-08-01|FIXED by replacement. LLM-authored test wrote `temp_depth_test` in CWD, ⊥ a real temp dir ∴ races under parallel test runs & leaks the dir if the test panics before cleanup|`std::env::temp_dir()` + unique name, cleanup on drop
B3|2026-08-01|FIXED by replacement. `find_depth_violations` read EVERY `*.md`, ⊥ only `SPEC.md` ∴ a federation table in a README is treated as authoritative|scope to `SPEC.md`, per `.:V5`/`.:V1`
B4|2026-08-01|FIXED & hypothesis CONFIRMED. was twice — `check_edge_depth` & `missing_not_owns`, independent tasks, both re-scan the `§F` section itself — its own `in_f` loop & header skip — instead of calling `edges(text)` & checking `e.dir`. residual two-readings, milder than B1's duplicate walker but real|HYPOTHESIS: step 2 gets the FULL impl body ∴ sees `edges()`'s scan loop & IMITATES it. surface-by-example induces copying. VERIFIED: step 2 given SIGNATURES ⊥ bodies → `depth_violations(&[Edge])`, 5 lines ⊥ 30, COMPOSES w/ `edges()`, `in_f` 6→3. also 20% cheaper (max call 1,438→1,243)
B5|2026-08-01|`c56869e` DELETED `missing_not_owns` (committed 2 commits earlier). I overwrote `src/fed/mod.rs` w/ the pre-experiment file to isolate a variable & the commit swept the loss in. tests 22→21 & I read it as noise ∴ a REGRESSION shipped inside a commit whose message claimed only an improvement|restored by re-running V3 under the new config. GENERALLY: resetting a file to isolate an experiment DISCARDS everything else in it — diff against HEAD before committing an experiment's output, & a falling test count is a finding ⊥ noise
B6|2026-08-01|`sherd apply` committed `detect_cycles(edges) -> Vec::new()` UNATTENDED, w/ a doc comment saying "stub ... satisfies the current test suite". the test asserted only "no cycle in this simple graph" ∴ a fn that always finds nothing passes perfectly. judge approved (the test DID check depth), gates green, committed|(a) gate now compiles `-D warnings` — `unused variable: edges` is how a stub announces itself & would have blocked this exact commit; (b) judge ! require a POSITIVE case for a detector; (c) stub removed. GENERALLY: a detector tested only on the NEGATIVE case is satisfied by returning the negative
B7|2026-08-01|LLM repair reached for `scopeguard::guard` — a crate this repo does ⊥ depend on ∴ `E0433`, & the run was mid-repair when its wall-clock budget ran out|4 lines of local `Drop` replaced it. the model reaches for a crate rather than 4 lines; its surface shows the API but ⊥ the dependency list
B8|2026-08-01|`unused import: Path` in a test module COMMITTED through a `-D warnings` gate. `cargo build` ⊥ compile `#[cfg(test)]` code ∴ the flag never saw it. also `find_exhaustive_violations` is called ONLY by tests — `review::unwired`'s exact case, surfaced by my own check & skimmed past|`RUSTFLAGS` exported so BOTH `build` & `test` deny. T6 wires the fn into `check`. GENERALLY: a flag on one command is ⊥ a flag on the toolchain
B9|2026-08-01|`sherd apply` wrote `find_flat_rs_promotions` filtering `§F` rows on `dir == "." && owns.ends_with(".rs")`. NO `§F` row has `dir == "."` — the shape ⊥ exist. gates green, judge YES, test & impl agreed w/ each other & neither related to `.:V73`. REVERTED|the ROW was wrong, ⊥ the model: `.:V73` is a policy about when to create a dir & answering it needs Rust SOURCE, which `fed` ⊥ read. `classify` says actionable because it parses as "add one fn" ∴ shape is necessary & ⊥ sufficient
B10|2026-08-01|`sherd apply` wrote `find_token_mismatches` summing FILE SIZES in bytes & comparing them to `§F`.tokens. bytes ⊥ tokens; `.:R8` measured bytes/4 48% off on caveman text & §C says counting is `itok`'s job. gate refused the commit for an UNUSED IMPORT, ⊥ for being wrong — luck|discarded. same class as B9: the node cannot compute the invariant, so the model invents a proxy. row now names the blocker
B11|2026-08-21|`split_row()` treats `\` as an escape before ANY char & DROPS it, while V4 only ever defined `\|` ∴ a backslash anywhere in a cell is EATEN, & a cell ending in `\\` yields 5 cells where V1 demands 4, so `edges()` returns NO row & a `§F` edge vanishes w/ no error — B6's shape (something that finds nothing passes cleanly) one level over. MEASURED through `edges()` on a 3-row table: an `owns` of `C:\path notes` parsed as `C:path notes`, a row whose `owns` ended `tail\\` produced NO edge, & 2 of 3 rows survived. FIRST CAUSE WRONG, mine, one commit earlier: I wrote that `cell()` & `split_row()` are a broken CODEC PAIR & that `cell()`'s output makes an edge vanish. VERIFIED FALSE — `cell()`'s only caller is `table()` → `sherd graph --table`, a MARKDOWN render, & nothing parses its output back ∴ the EFFECTS were real & the MECHANISM I named was ⊥. `.:V59`, & B1 is the same correction on this node's own log. FOUND by the ambiguity detector (`.:R55`) flagging the `escape_cell` corpus row 3/3 (`.:R55`), followed from fixture into live code|V4 & V13 restated. T17 fixes `split_row()` & tests through `edges()`. ROOT CAUSE is UPSTREAM: `FORMAT.md` says "literal pipe → escape as backslash-pipe" & is SILENT on what escapes the escape ∴ 3 readings of 1 sentence — ours (any char, lossy), `microlith::id::cells` (a 2-char toggle) & `microlith::id::unescape` (1-char) ∴ its own splitter & decoder are ⊥ inverse either. specified there as `microlith/V38`/`B25` 2026-08-22, ⊥ patched locally (`.:V47`)
B12|2026-08-21|SPEC defect, mine, caught by T17's own test before any code shipped. B11's first restatement of V4 said `\` escapes ONLY before `\|` ∴ a cell ending in a backslash was UNREPRESENTABLE: `tail\\` reads as literal-backslash-then-escaped-pipe, the column break is swallowed & the row drops to 3 cells — the SAME vanishing V4 had just been rewritten to stop. the rule now escapes `\` & `\|` & nothing else, which keeps `C:\path` literal AND makes a trailing backslash expressible|V4 restated a 2nd time. GENERALLY: an escape scheme ! be able to express its own escape char, & the test that finds that is a ROUND TRIP over a cell that ENDS in it
B13|2026-09-19|`nav_section()` wrote the lens RAW while `split_row()` had UNESCAPED it ∴ an `owns` cell holding `\|` came back as `\|` & every `§N` row naming that node gained a 4th column — this repo carried it in 17 `§N` files, every one naming `src/lens` ('s ``depth `rule`\|`why` ``). the V4 tests covered PARSING only; nothing rendered a parsed cell & read it back\|V16: `escape_cell()` in `nav_section()`. GENERALLY: a codec is verified by its ROUND TRIP — `a_lens_holding_a_pipe_stays_one_cell` pushes `|`, `C:\path`, a trailing `\` & `\|` through render then parse
B14|2026-09-28|`completed_tasks()` counted every `x` row in `§T`, INCLUDING the stubs `mth archive` leaves (`T88`, status `x`, task `ARCHIVED to SPEC-ARCHIVE.md`) ∴ `check` reported the V9 finding for rows whose text had already moved, & the only way to clear the finding was to DELETE the row, which breaks `microlith/V48` (a stub keeps id, status & cites so milestones & citations resolve). MEASURED in xenolith: 115 advisory findings after `mth archive`, burying the real ones (pr0d1r2/sherd#60)|V9 restated: a stub ⊥ history. `completed_tasks()` skips a row whose task cell is the stub text; the test covers the stub (skipped) & a full-text done row (still flagged, V10)
B15|2026-10-01|discovery walked every dir ⊥ on `is_ignored_dir`'s fixed name list, whether git tracks it or ⊥ ∴ a repo keeping gitignored scratch checkouts of OTHER repos federated every `SPEC.md` inside them. MEASURED on a consumer w/ 1 tracked `SPEC.md`: `wave` 884 nodes in round 1, `validate`/`check` exit 1 on violations nearly all under ignored dirs (`chain 306843 tok over its ceiling of 2000`), `budget` listing scratch checkouts as over-ceiling chains. every verb reads `discover()` ∴ every verb was noise & `validate` could ⊥ gate (#80)|V22. 1 `ls-files` per walk, the fixed list kept as the floor. GENERALLY: a name list tuned to THIS repo answers 'what is ⊥ source' for this repo only; the repo already records the answer for itself, in `.gitignore`
B16|2026-10-02|`walk()` & `chain()` asked `dir.join("SPEC.md").is_file()` & macOS's case-insensitive APFS answers YES for `spec.md` ∴ a skill doc named `spec.md` in a consumer repo became a node w/ a 308k-tok chain on macOS & ⊥ on Linux. found right after B15, as the only node left on the #80 consumer|V23. `is_node()` matches the entry NAME. `lens::pack`, `split`, `frozen_nodes` & the repo-root walk ask it too, ⊥ their own `is_file()`
B17|2026-10-03|`sync` doubled every backslash copying a `§F` `owns` cell into `§N`: `x \& y` came back `x \\& y`. V16 had PINNED this as intended (decode identical, bytes differ), while V21 says the lens is a VERBATIM copy ∴ 2 rules of this node disagreed & the test sided w/ the wrong one. every caveman `§F` writing `\&` gave each child a `§N` spelled differently from its parent, & the doubled form was then STABLE under `sync --check` (#98)|fixed UPSTREAM, ⊥ locally (V17: 1 codec): `microlith::escape` writes the shortest form (`microlith/B44`, 0.7.4) & the dep requires 0.7.4. V16 restated; the pinned test now asserts the shortest form & #98's repro runs through `sync`. GENERALLY: a test that PINS a surprising output as a decision ! name the rule it trades against, or the trade is invisible