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

A RATCHET: measure a property of the tree, compare it to a recorded floor, and refuse a move in the wrong direction.

## §N NAV

rel|path|lens
up|.|-
up|src|code nodes — tokens, spec, fed, lens facades & logic
self|src/debt|a ratchet — measure, compare to a recorded floor, refuse the wrong way
sib|src/tokens|-
sib|src/spec|-
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/assay|-
sib|src/git|-

## §C CONSTRAINTS

- one statement of each INPUT. the gate and the loop read the same flags, the same file set, the same denominator (B1).
- ⊥ a 2nd tree walker. this node owns the one `.rs` walk (`src/fed::rust_files`) & calls it.

## §V INVARIANTS

V1: a ratchet ! measure the thing it wants MOVED. counting warnings punishes the SPLIT that fixes a long fn — 269 lines is 1 warning, 5 pieces of 50 are 5 ∴ `shape` = Σ(len−15), where the same split reads 254 → 175 (`B3`)
V2: the number is a RATIO, ⊥ an absolute. an absolute cap TAXES adding code: 200 clean lines + 1 `unwrap` FAILED the old gate, which is backwards. `.coverage` has always worked this way ∴ the ratchets agree on their own shape (`B4`)
V3: a count from a tool that did ⊥ RUN is ⊥ a measurement. clippy emits 0 warnings for a target that fails to COMPILE ∴ 270 → 180 read as debt PAID (`B1`), & `Command::output()` returns `Ok` for a process that RAN & FAILED (`src/review:V7`). check the STATUS, then the count
V4: the measured configuration ! be the SHIPPED one. `default = []` here & every count is `--all-features` ∴ 131 warnings on the installed binary were invisible for a day (`B2`)
V5: a PREDICTOR is tested against the thing PREDICTED, ⊥ against a value someone wrote down. `src/land::lint_debt_ok` diverged from `hk` on flags, file set & denominator at once & reported 10.8 where the gate computed 14.6 (`B6`); the test now reads `hk.pkl`'s own text ∴ it fails when the gate moves
V6: a ratchet's FIX half may only lower. `pre-commit` runs the fast set in fix mode ∴ a fix recording whatever it measures files down its own teeth — it writes the raise it exists to refuse, & the gate never fails twice for one debt
V7: a RAISE is recorded WITH ITS CAUSE or it is ⊥ recorded. the file is the audit trail & a bare number is a number nobody can argue with
V8: a CEILING is per `.rs` FILE & the halves are counted SEPARATELY — 4,000 code, 2,000 tests. a module w/ a big suite & a small impl is a different thing from the reverse, & 1 number over the pair cannot tell them apart (`.:V50`)
V9: COVERAGE is the same ratchet MIRRORED — a floor that may only RISE where the lint ratios are ceilings that may only fall — ∴ it lives here & `hk` CALLS it. it was written twice in `hk.pkl` (check & fix, a copy-paste) & the recording path was a HAND EDIT: 14 commits touched `.coverage` on 2026-08-24 & every one was a `perl -pi -e`, ⊥ once through `hk run fix`, ∵ that means re-running `llvm-cov`. once the floor was LOWERED to match a drop & caught by READING, ⊥ by any guard (B7). `--record` refuses a fall; a text substitution refuses nothing. HUNDREDTHS, ⊥ tenths: `.coverage` has always carried 2 decimals & rounding to 1 moves the floor by up to 5 hundredths, more than most real changes. a toolchain that did ⊥ RUN is an ERROR, ⊥ a floor breach (`src/tdd:V26`)
V10: a SwiftPM package — `Package.swift` @ root & ⊥ `Cargo.toml` — is measured by `swift test --enable-code-coverage`, then the llvm-cov JSON `swift test --show-codecov-path` names: Σ `covered` / Σ `count` of `summary.lines` over the `data[0].files[]` whose path, relative to the root, is under `Sources/`, rounded to hundredths as llvm-cov prints. env `SHERD_SWIFT` (`swift`). same floor, exit codes & `.coverage` format as cargo. ONE build ∴ `lines` only; `lines-default` is a cargo feature split. BOTH runs' STATUS is checked before the file is READ ∵ an earlier run's JSON is still on disk (V3, `.:V118`). a `Cargo.toml` @ root WINS ∴ a cargo repo measures byte-for-byte as before. ⊥ `data[0].totals` ∵ totals count `Tests/` & the `.build/` derived `test_entry_point.swift`, where `cargo llvm-cov` drops `tests/` — MEASURED on age-plugin-se a7bae66: totals 3648/3804 = 95.90%, `Sources/` 995/1135 = 87.67% ∴ a floor over test code reads high. `Sources/` is SwiftPM's default target dir; a file outside the root (a `.build/checkouts` dependency) ⊥ counts, & a target whose `path:` is outside `Sources/` is ⊥ measured — stated ⊥ hidden. 0 lines under `Sources/` is ⊥ a measurement. `.coverage` row `exclude <path> <reason>` drops one `Sources/` file from numerator & denominator; a row w/o a reason is ⊥ an exclusion
V11: a `.coverage` row `exclude <path>:<function> <reason>` drops ONE function from numerator & denominator; the target splits @ its 1st `:` ∴ a Swift name keeps its own. `<function>` = the LAST word of `swift demangle --simplified` (`SHERD_SWIFT`, asked only when such a row exists) over a `data[0].functions[]` name whose `filenames[0]` is `<path>` ∴ `static Keys.load(tag:)` is `Keys.load(tag:)` & `closure #1 in helper()` goes w/ `helper()` — a row names a DECLARATION, ⊥ a mangled symbol, which changes w/ every signature. a name w/ an operator's space ⊥ matchable. COUNTING: llvm-cov's `summary.lines` is ⊥ distinct lines — it is Σ over the file's function GROUPS (records sharing a 1st region; max lines & max covered within one) of each group's OWN line count, & a closure's lines count for the closure AND again for its function. MEASURED: Σ reproduces `summary.lines` exactly on all 22 files of a toy package & age-plugin-se 963b701 ∴ a function leaves by EXACTLY what llvm-cov added for it: its group's lines, recomputed from its `regions` as llvm's `LineCoverageIterator` does (a line is mapped when a code region starts on it or a counted region wraps into it, ⊥ when its 1st segment opens a skipped region, an inactive `#if`), each matched group ONCE however many rows match it — ⊥ a line set, which would undercount what the file total holds. the groups ! sum to the file's own `summary.lines` before anything is subtracted, else ⊥ a measurement (V3). a row matching ⊥ function, & a file row matching ⊥ measured `Sources/` file, is exit 2 ∵ a stale exclusion explains lines that are gone. CAP: `excluded <n>` = the most `Sources/` lines file & function rows may remove; absent = 0. measured > `<n>` → `--check` 1 & `--record` writes NOTHING (a floor raised by lines over the cap was ⊥ earned). `--record` rewrites `<n>` DOWN to the measured total & never up — the floor's mirror (V6, V9): a raise is a hand edit in a reviewed commit w/ its reason (V7). ∴ the floor may only rise & the gap hidden in exclusions may only shrink. a cargo tree reads neither row

## §T TASKS

id|status|task|cites
T4|.|test file(s) over the 2,000 ceiling since `.:T108` gave `src/debt` its tree: `tests/debt.rs` 3,910. split by subject|`.:V50`,`.:V124`

## §B BUGS

id|date|cause|fix
B1|2026-08-23|the LINT RATCHET counted a BROKEN BUILD as an improvement. `cargo clippy` emits no warnings for a target that fails to COMPILE ∴ when a test target broke, the count fell 270 → 180 & the step read that as debt paid. MEASURED live: a `write_spec` rename left one call site dangling, & 90 warnings from `#[cfg(test)]` code in `src/*` silently stopped being counted. the `fix` half is worse — it would have RECORDED 180 as the new floor, filing the ratchet's teeth down w/ a number nobody earned|`.:V116`. both halves now capture clippy's output, refuse on `^error`, & say the count is ⊥ a measurement. PROVEN by planting a broken test: exit 101 naming the cause, exit 0 when restored. GENERALLY: a metric derived from a TOOL'S OUTPUT ! first check the tool RAN — `.:V26` for a subprocess, & the 4th recording of that shape (B17/B20/B24 in the siblings)
B2|2026-08-23|the lint ratchet counts `--all-features` & we SHIP `default = []` ∴ the measured configuration is ⊥ the installed one. MEASURED: `cargo clippy --all-features` = 0 warnings, plain `cargo clippy` = 131 — incl. `plan::preflight` DEAD (reached only under `ollama`) & an unneeded `mut` in `cli::run_args`. the featureless step asks only whether it BUILDS (B15), which it does ∴ the shipped binary's warnings have been invisible since the default flipped to `[]` (`.:V113`) & the ratchet has been green over a config nobody installs. found by reading `cargo run` stderr while measuring something else, ⊥ by any gate|`.:V118`. T104 — count both configs. B18 stopped the ratchet reading a BROKEN build as progress; this is the same fault one level out: reading the WRONG build
B3|2026-08-23|the lint ratchet COUNTS warnings ∴ `too_many_lines` PUNISHES the split it exists to force: `tdd::drive_run` is 269 lines & ONE warning, & 5 pieces of 50 would be FIVE ∴ every honest refactor of the worst function in the tree makes the number WORSE & the gate refuses it. found by looping paydown to exhaustion & asking why no round paid — ⊥ by any run. MEASURED: 76 fns over the limit, 2,822 lines in them, 1,682 EXCESS. 17 of the 76 are 16-19 lines ∴ a count also weighs "1 line over" the same as 269|`.:V118`. a 2nd ratchet, `shape` = Σ(len−15), beside `total`; NEITHER may rise ∴ strictly stronger than one number. splitting 269 into 5×50 reads 254 → 175, which is the progress it is. the count STAYS ∵ it still catches a new site; the 2 answer different questions & 1 number let a safety fix pay for a shape regression. GENERALLY: a ratchet ! measure the thing it wants MOVED, & `B2` is the same fault on the other axis — measuring the wrong build vs measuring the wrong property
B4|2026-08-23|the lint ratchet was an ABSOLUTE count ∴ it taxed ADDING code: a commit of 200 CLEAN lines + 1 `unwrap` FAILED, which is backwards — the tree got cleaner per line & the gate refused it. MEASURED at the switch: 271 warnings & 1,682 excess lines over 15,909 lines of Rust = 1 warning per 58 lines, & 1 line in 10 inside a fn past the limit. the same 200-line commit reads 17.0 → 16.8 as a RATIO & passes|`.:V118`,B21. `.lint-debt` now gates 2 RATIOS — `density` (warnings/KLoC) & `shape` (excess lines as a share of the tree) — & records `count`/`excess`/`loc` as context. `.coverage` has worked this way since it existed: a percentage that may ⊥ fall, w/ the line count unbounded ∴ the 2 ratchets in this repo now agree on their own shape. RISK stated ⊥ hidden: a ratio can be DILUTED by clean-but-pointless code; the recorded absolutes make that visible & `.:V50`'s code ceiling is the answer if it ever happens. `src/land::lint_debt_ok` compares the SAME ratio ∵ a loop predicting the gate ! read the number the gate reads (`src/tdd:B30`)
B5|2026-08-24|`V50` sets a CODE CEILING — 4,000 tok impl, 2,000 tests, counted separately — & NOTHING computes it: `check` reports 0 violations & has since the row was written. it is cited in 5 source files as the rule that forced a split, ∴ it has been enforced by being QUOTED at an author, which is `V100`'s PROMPT tier, the weakest of the 3 it ranks by measurement. MEASURED once asked: 4 of 14 nodes over the impl ceiling (`assay` 13,413 · `cli` 12,510 · `tdd` 10,534 · `ollama` 7,695) & 11 of 14 over the test ceiling, `plan` @ 15,578 = 7.8x. FOUND by a question about 2 nodes' sizes, ⊥ by any gate|`.:V119`. T105 builds it. NOTE before enforcing: 11 of 14 over the TEST ceiling says 2,000 was set before the suite reached this size ∴ re-derive that number from measurement rather than reshaping the tree to fit a figure nobody has revisited. same class as `src/plan:B16` — root POLICY no gate reads
B6|2026-08-24|`src/land::lint_debt_ok` exists so `sherd tdd` predicts what `hk` will do (`src/tdd:B30`) & it diverged from the gate on ALL THREE inputs at once, in the commit that converted it to a ratio (`B4`): the FLAGS (⊥ `--workspace`, ⊥ `--all-features` ∴ a different BUILD, `B2`'s shape), the FILE SET (`^src/` where the gate counts `^(src\|dev)/`), & the DENOMINATOR (`src` = 15,600 lines where the gate divides by `src`+`dev` = 17,375). MEASURED: the loop reported PASS @ 10.8 where the gate computed 14.6 ∴ it would call a candidate MERGEABLE that `hk` then refuses — B30 verbatim, one commit after the row was cited as the reason the fn exists. the numerators AGREED only by accident: `dev/` carries 0 warnings today. FOUND by asking whether a `src/debt` node was sensible, ⊥ by any run|`.:B24`'s shape. `GATE_ARGS`, `MEASURED` \& `gate_counts` are 1 statement of each input, & the test asserts them against `hk.pkl`'s OWN TEXT rather than against a remembered ratio — a test hardcoding today's number passes while the 2 drift again. both now report 14.7 on the same tree. GENERALLY: a predictor ! be tested against the thing predicted, ⊥ against a value someone wrote down — & the rule is now stated 3x (2 in `hk.pkl`, 1 here), which is the argument for a node that owns it
B7|2026-08-24|the coverage floor was RECORDED BY HAND 14 times on 1 day & once in the WRONG DIRECTION. `hk`'s `fix` half refuses a drop, & I never invoked it — it re-runs `llvm-cov`, so every recording was a `perl -pi -e 's{^lines 92\.28$}{lines 92.27}'` instead. that bypasses the guard entirely, & @ 92.21 → 92.19 I wrote the drop down, then caught it by reading my own output: "filing down the ratchet's own teeth". a guard nothing invokes is a guard that ⊥ run (`src/plan:V12`), & here it was ergonomics that stopped it being invoked\|V9. `sherd coverage [--check|--record]`, & `hk.pkl` calls it — 23 lines of shell → 5. MEASURED before deciding, ∵ the case AGAINST was "it works & the move costs ratio": warm `llvm-cov` is 19s & the outer `cargo run` adds ~5s to a step that already costs 19 ∴ the earlier "2 minutes" was the whole `pre-push` set, off by 6x, & it was the load-bearing half of the objection. GENERALLY: a guard the tool makes EXPENSIVE to invoke is a guard people route around, & the routing leaves no trace in the file it protects
B8|2026-09-30|the COVERAGE floor measured `--all-features` alone ∴ V4 held for neither ratchet: `default = []` is what `cargo install` ships, & its coverage was never read. MEASURED on d324d0a, clean clone: all-features 90.80% (770 of 8,372 missed), default 93.27% (373 of 5,539). the 2 disagree per node — `src/land` missed 56 lines in the default build against 14 w/ all features, ∵ its gate ran only under `src/tdd` tests & those need `ollama`. that gap hid a shipped refusal (`src/land:B6`)|V4,V9. `.coverage` carries a 2nd row, `lines-default`, & `sherd coverage` checks & records EVERY build w/ a row; a missing `lines-default` is reported, ⊥ failed (`src/cli:V12`). library: `debt::Build`, `coverage_of`, `recorded_floor_of`, `record_coverage_of`; the old 3 are the `All` case. the LINT half of V4 is still `.:T104`