# SPEC
## §G GOAL
`sherd` (cmd `sherd`) — two-axis federation of `SPEC.md` + Rust source over a dir DAG, so a 128k local model works at one altitude & pulls deeper only when measured cost says it must.
MOTIVATING NUMBER: `itok` = 135,096 tok (28,462 spec + 106,634 code) vs 102,529 working on the target box. An 11,291-line CLI ⊥ fit its own best-case hardware.
TARGET: most modules BUILDABLE on the 20B (V106) — ⊥ merely readable by it. context was the binding constraint & after T41 is ⊥: the fattest chain is 9,886 of 102,529 working = 9.6% (R41). competence is what binds now: `src/tdd:T13` has ONE merit win & it did ⊥ survive review ∴ the loop's MERGEABLE & the gate's disagree, & the loop is the optimistic one. rung `0.5` (V114) is where they ! agree, measured.
## §F FEDERATION
dir|owns|⊥owns|tokens
src|code nodes — tokens, spec, fed, lens facades & logic|inference harness, endpoint config|-
dev|repo-maintaining tooling, `publish = false` — README generation|anything a consumer installs|-
## §N NAV
rel|path|lens
up|-|-
self|.|-
## §C CONSTRAINTS
- lang: Rust **edition 2024**. stable. MSRV **1.95** = the FLEET PIN (`nixpkgs-lock` → nixos-26.05). ⊥ a number copied from a sibling: `itok`/`microlith` declare 1.96 & MEASURED compile clean on 1.95 ∴ their floor is a mirror of an old pin, ⊥ a minimum.
- nixpkgs rev FOLLOWED from `nixpkgs-lock`, ⊥ spelled here. one rev, ~80 repos.
- target model: `gpt-oss:20b`, 131,072 ctx, local. ⊥ cloud fallback.
- inference: local HTTP (Ollama) only. ⊥ network otherwise. the CODE-WRITING executor is an ADAPTER (V123): named & swappable, ⊥ in the deterministic core ∴ a wave ? be driven by the local model | an external command, & the core stays offline either way.
- deterministic core: parse/DAG/budget/ceiling = pure Rust, ⊥ model. model ? prose gen & drift judgement only. DEFAULT features are EMPTY ∴ the installed binary carries ⊥ HTTP client, ⊥ TLS, ⊥ network code; `ollama` is 1 flag away & named when a verb needs it.
- separator = **directory**. dir tree ! source of truth. ⊥ manifest, ⊥ name-encoded grouping (`core-parse` ⊥ imply parent).
- federation edge = parent dir → child dir, depth **+1 exactly**. ⊥ skip.
- graph ! DAG. cycle ⊥. re-parent (2+ parents) OK.
- intra-file spec ops = `microlith` lib dep (crates.io 0.6, zero-dep, pure fn over `&str`). ⊥ reimpl parse/fmt/check/anchors.
- token counting = `itok` lib dep (crates.io 0.3). ⊥ own tokenizer, ⊥ own bytes/4.
- fs walk + ignore globs = `itok::walk`/`itok::glob`. ⊥ reimpl.
- SPEC syntax = FORMAT **4.1.0**, sections `G C I R V T B` fixed & ordered + `§F`/`§N`. `§F`/`§N` are microlith's, ⊥ invented locally (V47).
- layout: **one crate**. module = **dir + `mod.rs`** (the `default.nix` shape — dir is the unit, entry is conventional). ⊥ 2018 `foo.rs`+`foo/`: that puts the facade OUTSIDE the dir it fronts ∴ module entry & its `SPEC.md` land in different federation nodes.
- node = dir = Rust module. all three aligned or a flat `.rs` owns spec it cannot hold.
- repo partitions **set** \| **setting** \| **human** (`set-and-setting` vocabulary). default pack = set.
- caveman encoding ∀ generated spec text. MEASURED 22% saving ⊥ 75% (R23) — it disciplines saying LESS, ⊥ encodes denser.
- gate runner = `hk` (from `nix-hk`; nixos-26.05 ships none — landed on master after branch-off). ops DECLARED in `hk.pkl`, ⊥ a shell body in `.githooks`. schema VENDORED `pkl/Config.pkl` ∴ the gate runs w/ ⊥ network.
- SETTING as contract (V82), one line each: `rustfmt` 80 col + edition 2024 · `clippy -D warnings` · `cargo test` · `sherd slice/check/budget` · coverage · lint ratchet · hygiene & linters, named in `hk.pkl`.
- CODE limits as contract (V82), `clippy.toml` @ root + `[lints.clippy]` denies: fn ≤15 lines · cognitive ≤7 · nesting ≤4 · args ≤4 · fn bools ≤1 · struct bools ≤3 · trait bounds ≤3 · type complexity ≤150 · `unwrap`/`expect`/`panic`/`indexing_slicing`/`todo`/`unimplemented`/`dbg_macro`/`arithmetic_side_effects` DENY · `unsafe_code` FORBID. thresholds are Sandi Metz adapted; reasoning RESTATED here, ⊥ cited to a sibling — an id that resolves in no namespace this repo can reach reads authoritative & is ⊥ checkable.
- ⊥ global index file. discovery by walk.
- platforms (`paradigm/V28`, owner 2026-10-24): `aarch64-darwin` · `x86_64-darwin` · `x86_64-linux` · `aarch64-linux`; macOS floor 14.0 (V126).
## §I INTERFACES
- cmd: `sherd init [dir] [--stdout]` → scaffold `SPEC.md` @ dir, `§F` rows from child dirs. REFUSES an existing file, exit 1, ⊥ `--force`
- cmd: `sherd lens <dir> [--depth rule|why|all]` → context pack. default `rule`
- cmd: `sherd lens <dir> --json` → `{chain:[],body:{},children:[],tokens:{},examined:{}}` (0.3)
- cmd: `sherd route "<query>"` → dir + the words that matched. RANKED: the node matching MORE of the query wins, a tie is ambiguous, & ROOT is never an answer. 0 hit / 2 miss / 3 ambiguous
- cmd: `sherd coverage [--check|--record]` → the coverage floor vs `.coverage`, via `cargo llvm-cov` | `swift test` for a SwiftPM package (`src/debt:V10`). 0 held / 1 fell / 2 unmeasurable
- cmd: `sherd debt [--check|--record]` → the lint ratchet: density & shape vs `.lint-debt`. 0 held / 1 rose / 2 unmeasurable
- cmd: `sherd check [dir] [--format text|json]` → drift spec↔code + file ceilings. 0 clean / 1 violation / 2 usage
- cmd: `sherd split [dir]` → PROPOSE a federation from the CODE'S structure: dirs · `pub mod` · naming families w/ their shared hub. spec rows attach as EVIDENCE about a node, ⊥ as the reason for it. writes ⊥ ever; `--apply` refuses, ∵ which module owns which rule is a JUDGEMENT
- cmd: `sherd adopt <dir> [--map FILE] [--check]` → MIGRATE a foreign single-file `SPEC.md` onto a federation: PROPOSE which node owns each `§V`/`§T`/`§B`/`§R` row, REWRITE citations to the namespaced form, emit node files `check` ACCEPTS. writes ⊥ w/o `--map`; `--check` reports & writes ⊥. the proposal PRINTS the map file itself ∴ `adopt <dir> > map` → edit → `adopt <dir> --map map`. 0 ⊥ to move / 1 a migration PENDING or WRITTEN (`sync`'s rule 1 verb over) / 2 usage
- cmd: `sherd sync [dir] [--check]` → regen `§N` from the `§F` above it, ∀ node in the subtree under `[dir]` (default: the repo). exit 1 IF IT WROTE, ∵ a generated section that had to change means the committed tree was STALE. `--check` reports & writes ⊥, yet exits 1 IF a node is stale
- cmd: `sherd graph [--tree|--table|--dot|--mermaid]` → federation DAG. `--mermaid` = the generated architecture diagram, the default
- cmd: `sherd lens <dir> [--depth rule|why|all]` → default `rule`
- cmd: `sherd budget [dir] [--format text|json]` → node/chain/lens/file token table. exit 1 over
- cmd: `sherd seam [dir]` → PROPOSE the SEAM a parallel build needs: per node, the public types its siblings ! name before any node is written. report-only, writes ⊥ — WHICH types are shared is a JUDGEMENT (R57)
- cmd: `sherd wave [dir] [--format json]` → the SCHEDULE a parallel build follows: ready set per round over the CODE dag (`use crate::`, ⊥ `§F`), DEPTH & WIDTH. EDGES & BLOCKING counted apart (`src/wave:V4`). report-only; a cycle is NAMED, exit 0. `--format json` → `rounds` · `blocked` · `cycles` · `edges` · `unresolved` · `depth` · `width` (`src/wave:V6`-`src/wave:V9`)
- cmd: `sherd validate [--format text|json]` → structural + edges + ceilings + slice drift, & REPORTS what it examined. exit 1 fail
- cmd: `sherd fed [dir]` → the federation edges a node DECLARES, ⊥ the ones it has
- cmd: `sherd review [rev]` → mechanical checks on what a commit ADDED (default `HEAD`). ADVISORY: a finding ⊥ fail the cmd, ∵ intent is the reader's call
- cmd: `sherd slice [--check|--list]` → regen distilled slices from source. `--check` exit 1 on DRIFT, & a slice is never hand-edited
- cmd: `sherd outcome <node> <kept|reverted>` → record whether a node's work survived review. feeds believability (`src/land`)
- cmd: `sherd plan [--triage]` → next 3 steps + what would INVALIDATE each. `--triage` = unmanaged rows w/ a proposed home
- cmd: `sherd apply [--land]` → execute step 1 ONLY, commit to a run branch, STOP. ⊥ main (`.:B12`)
- cmd: `sherd land [--push]` → fast-forward main to the run branch IF it earned it: gate green + believability
- cmd: `sherd ask <dir> <q>` → ask the endpoint from a node's lens pack. the pack is the whole prompt
- cmd: `sherd tdd <dir> <Vn> <task>` → red → judge → green → gate → repair. the LOOP the §G target is about
- cmd: `sherd oneshot <dir> <Vn> <task>` → the MONOLITH arm: 1 call, whole repo. exists to be COMPARED against `tdd` (R29/R30), ⊥ recommended
- cmd: `sherd completions <shell>` → shell completion script on stdout (bash·zsh·fish·elvish·powershell), generated from the clap grammar (`src/cli:V21`)
- cmd: `sherd man` → the man page, roff, on stdout, generated from the same grammar
- file: `SPEC.md` ∀ dir any depth. `§G §C §I §R §V §T §B` + `§F` + `§N`
- file: `§F FEDERATION` pipe table `dir|owns|⊥owns|tokens` — child dir depth +1. `⊥owns` = what it does NOT own + where that lives
- file: `§N NAV` pipe table `rel|path|lens`, `rel` ∈ `up`|`self`|`sib`. generated, ⊥ hand-edit
- file: `SPEC.why.md` ∀ dir w/ rationale — `<id>|<rationale>`, addressed by `§V`/`§B` id
- file: `.context-limits` — per-path ceilings, `itok` format, reused ⊥ reinvented
- file: `.spec-records` — closed-option baseline, `microlith --records`
- file: `.claude/commands/sit.md` — `/sit`, ONE oversight cycle. loop-safe, halts w/ a recorded reason
- file: `.claude/commands/titrate.md` — `/titrate`, granularity descent. attempt → enrich pack | split task. floor = VERIFIABILITY ⊥ size
- file: `.sherd-frontier` — `shape rung= kind= pack= sig= tests= tried= kept=`. TRACKED, ⊥ `.sherd-state`: learning that dies at the clone boundary ⊥ learning
- file: `AGENTS.md` — supervisor class. auto-loaded by Codex & Claude, ⊥ reachable by a worker prompt (V97)
- env: `SHERD_MODEL` (`gpt-oss:20b`), `SHERD_ENDPOINT` (`http://localhost:11434`)
- lib: `microlith::check_spec(&text,&records)`, `microlith::fmt`, `::anchors`
- lib: `itok::estimate`, `itok::walk`, `itok::glob`
- violation: `<file>:<line>: sherd/<Vn>: <msg>` + `why` + `mechanical`|`judgment`. `--format json` carries `kind` as data
## §R RESEARCH
id|topic|finding|src
R1|crates.io name|`sherd` taken (BBCode parser, lib-only, `bin_names: []`). BIN name `sherd` free on brew, debian, PATH ∴ package≠bin|crates.io API, formulae.brew.sh, sources.debian.org
R2|cargo workspace|`members=["crates/*"]` ERRORS on a hub dir w/o `Cargo.toml`. per-depth globs + cross-nested path deps build clean|cargo 1.96.1, tested
R3|rust module form|`mod.rs` = the `default.nix` shape. private sibling → `error[E0603]` ∴ COMPILER enforces the facade, ⊥ grep|cargo 1.96.1, tested
R4|itok size|`SPEC.md` 28,462 tok + code 106,634 = 135,096 ∴ 103% of a 128k window. an 11,291-line CLI ⊥ fit|itok 0.2.0 `--bpe`
R5|spec fatness|itok 656B/rule × 103 rules. rationale = 80% of §V (microlith 73%) ∴ per-row FATNESS is the multiplier, ⊥ rule count|measured over both §V
R6|federation yield|dir federation moves 41% of itok §V bytes; intermediate hubs absorb 9.5%; sherd own §V 64% stays root|classified 103 + 55 rules
R7|inline tests|42% of itok+microlith `src/` is `#[cfg(test)]`; `tracecmd.rs` 65% ∴ whole-file ceiling ranks a SMALL module worst|measured per file
R8|tokenizer drift|bytes/4 measured 48% LOW on caveman-encoded `SPEC.md` (5,761 real vs 3,890 est) ∴ ⊥ ever a gate|itok `--bpe` vs bytes/4
R9|gpt-oss:20b arch|24 layers, 8 KV heads, k/v len 64, sliding_window 128, ctx 131,072, 32 experts/4 used, MXFP4, 20.9B|ollama `/api/show` @ 192.168.0.181
R10|target box|24GB M5 Pro: ctx 131,072 ALLOCATED, 11.98G of 24G resident, 100% GPU, ⊥ CPU spill, ollama 0.32.3|ollama `/api/ps`, measured
R11|KV cost|KV/tok = 2 × layers × kv_heads × head_dim × bytes. sliding-window halves it (12 of 24 layers full) ∴ 24GB needs NO KV quant|derived from R9 + R10
R12|32k models|any 32k-ctx model leaves 4,225 working after 28,543 entry cost ∴ unusable for SDD at EVERY hw tier, incl M64|derived from R9/R11
R13|microlith §R|FORMAT 4.1.0 §R = RESEARCH (`id\|topic\|finding\|src`), ⊥ records. closed options live in `.spec-records`|microlith 0.4.0 `check.rs`, FORMAT.md
R14|prompt cache|identical prefix → prefill 4.60s → 0.04s (~115x). cache is per-PREFIX & survives across requests|ollama 0.32.3 @ .181, measured
R15|edit locality|an edit invalidates all prefill AFTER it. same 7k pack: cached 0.04s · edit TAIL 0.49s · edit HEAD 4.61s (full cold)|measured, 3 runs
R16|prefill dominance|workload is prefill-bound ⊥ decode-bound. 7k: 4.60s prefill vs 1.83s decode. 28k: 30.32s vs 5.74s = 83% prefill|measured @ .181
R17|prefill superlinear|1,519 tok/s @ 7k → 1,233 @ 15k → 941 @ 28k. 4.09x tokens costs 6.59x time ∴ small packs pay off faster than linearly|measured, 3 points
R18|facet shares|itok SET 47.4% / SETTING 49.9% / HUMAN 2.7%; nanokit 49.1 / 47.6 / 3.3 ∴ ~half a repo never loads for impl work|measured, 2 repos (`nanokit` = `microlith`, renamed 2026-08-01)
R19|tests dominate|tests 34.0% itok · 24.9% nanokit = largest single facet. 42% of it INLINE in `#[cfg(test)]` ∴ ⊥ reachable by the dir axis|measured per file
R20|fleet duplication|guard-infra near-identical absolute size across unrelated repos: 16,058 vs 15,218 tok ∴ same scaffolding copied. × 54 repos ≈ 840k tok duplicated|measured, 2 of 54
R21|human docs grow|`set-and-setting` human 24,965 vs itok 5,236 = 4.8x. CHANGELOG alone 13,762 — append-only, never needed to implement|measured
R22|mermaid density|mermaid 71 tok vs 40 tok prose for the same info = 1.8x. bytes/tok: prose 4.15 · README 3.51 · mermaid 3.20 · caveman SPEC 2.95|measured
R23|caveman saving|MEASURED 22%, ⊥ the 75% FORMAT.md claims (10 / 13 / 35% on 3 invariants vs faithful prose). symbols cost 1-3 tok for 2-3 bytes ∴ the saving is STRUCTURAL (omit rationale), ⊥ encodative. n=3, own comparators|measured
R24|profile shares|itok by profile: implement 47.4% · tdd 81.4% · refactor 80.9% · harden 31.2% · document 17.5%. tdd @ ONE node = 6.1% ∴ 13x from composing facet × horizontal|derived from R18
R25|widening cost|same 11.6k pack: APPEND a facet 4.12s (prefix cached, only new tok prefill) · PREPEND 8.60s (full cold) = 2.1x ∴ optional facets belong at the END|measured @ .181
R27|notation cost|NOTATION slice 182 tok vs whole `FORMAT.md` 892 ∴ slicing saves 80%. doc comments in the surface cost 78 tok & were what let the judge tell prose from path|measured
R28|tdd loop cost|3 round-trips · 3,707 tok · max single call 1,651 vs 157,071 monolithic = 95x. step 3 (gates) = 0 tok. +15% max-call for notation+docs turned 3 failed runs into a correct one|measured, `sherd tdd` on src/fed V2
R29|premise gate|HEAD-TO-HEAD same node/invariants. monolith 1/2 green (V2 `E0425`, V3 green) · decomposed 2/2. TOTAL tok comparable (2,659 vs 2,712) ∴ decomposition ⊥ save total. MAX SINGLE CALL 2,659 vs 1,243 = 2.1x — that is the whole benefit, & it is the binding constraint|measured, `sherd oneshot` vs `sherd tdd`
R30|quality parity|when the monolith SUCCEEDS its output matches the decomposed form — `missing_not_owns(&e)`, `in_f`=3, composed ⊥ duplicated ∴ decomposition's win is FITTING, ⊥ quality, at this task size|measured
R31|scale curve|MONO call grows w/ BODIES, DECOMP max bounded by SIGNATURES. impl 375→5,218 tok: ratio 1.1x · 1.1x · 1.2x · 1.6x · 1.9x · 3.4x (predicted, no inference)|computed over 6 nodes
R32|scale, measured|large node (impl 5,218): MONO 9,029 tok one call, FAILED `E0425` · DECOMP max 3,155, GREEN = 2.9x on max call. small node (impl 1,118): 2.1x ∴ the gap WIDENS w/ node size|measured
R33|total ⊥ cheaper|DECOMP total varies w/ retries — 8,558 (5 trips) & 12,909 (7 trips) vs MONO 9,029 ∴ total cost is ⊥ a reliable win. MAX CALL is the consistent one|measured
R34|target box moved|target = 192.168.0.24, ollama 0.32.1, `gpt-oss:20b` 11.98G resident, `size_vram` = `size` ∴ 100% GPU ⊥ CPU spill, ctx 131,072 ALLOCATED. same residency profile as R10 (.181, 0.32.3) ∴ the KV arithmetic of R11 carries over unchanged|`/api/ps` + `/api/version` @ .24, measured
R35|prefill is 4x slower here|373 tok/s @ 9,048 · 320 @ 17,846 · 247 @ 36,070 vs R17's 1,519 / 1,233 / 941 ∴ .24 is 3.8-4.1x SLOWER at every size. superlinearity HOLDS: 3.99x tokens costs 6.03x time (R17: 4.09x → 6.59x) ∴ R17's SHAPE generalizes across hardware, its RATE ⊥. a rate is a fact about ONE box|`/api/generate` `prompt_eval_*`, 3 sizes, cache defeated by a unique prefix
R36|prefill dominance rises|decode 26-33 tok/s (`pace decode` carried 50 from .181). 36k pack = 146.3s prefill vs ~13s for a 400-tok reply = 92% prefill, where R16 measured 83% @ 28k on .181 ∴ SLOWER hardware makes the small-pack thesis STRONGER, ⊥ weaker — the penalty for a fat pack scales with how slow prefill is|derived from R35 + measured `eval_duration`
R37|judge is STABLE|blind lens, 3 runs × 2 arms × 5 items = 30 calls @ ~420 tok: 5/5 stubs REJECTED & 5/5 working fns ACCEPTED, identical ∀ 3 runs. zero variance ∴ `P(kept\|shape)` is a REAL parameter at this shape, ⊥ a coin flip — a known-good rung STAYS known-good ∴ exploit (`/sit`) is distinct from search (`/titrate`)|`cargo test -- --ignored`, 3 runs @ .24, both arms
R38|the corpus is BELOW the frontier|perfect separation on BOTH arms w/ ⊥ a single miss ∴ this task sits comfortably inside competence & LOCATES NOTHING. a test that never fails measures no boundary. next titration ! go UP (harder judge: longer fn, weaker invariant, ⊥-obvious stub) or SIDEWAYS (generation, where `src/tdd:T13` still reads 0 merit wins), ⊥ repeat this one|derived from R37
R39|judge boundary LOCATED|blind lens titration, 4 rungs, 2 runs IDENTICAL: `0-tells` 10/10 · `1-bare` 10/10 · `2-vague` 7/10 · `3-subtle` 6/8. ∴ the boundary is real AND stable AT THE EDGE, ⊥ only deep inside competence — R37 had only shown stability at 100%|`cargo test -- --ignored blind_lens_titration`, 2 runs @ .24, 76 calls
R40|invariant PRECISION is the axis, ⊥ prompt help|stripping `blind_prompt`'s enumerated tells cost NOTHING (10/10 → 10/10) though every recorded stub matches a clause near-verbatim ∴ the checklist was ⊥ doing the work — HYPOTHESIS FALSIFIED. vague `§V` wording costs 30%, the largest single drop, vs 25% for stubs no clause reaches ∴ cheapest lever on delegation = sharper `§V` rows, ⊥ prompt engineering. `src/lens:B1` & `src/plan:B1` reached this from the other direction|derived from R39
R41|context stopped binding|T41 made `--depth rule` select: whole repo 170,822 → 109,363 tok (-36%), root 11,576 → 7,638, `src/tdd` 17,127 → 9,886 (-42%). 13 of 13 chains were OVER ceiling, now 0 ∴ the fattest chain is 9.6% of working budget & R4's motivating number no longer describes THIS repo. what remains unsolved is competence, ⊥ context|`sherd budget` before/after T41
R42|precision drives WRITING too|generation titration, 5 pure fns × sharp\|vague × 3 runs, graded by `rustc` on HIDDEN tests the writer never saw: sharp 12/15 · vague 6/15 = 2.0x. per-item results IDENTICAL ∀ 3 runs ∴ deterministic, ⊥ underpowered — R40's judging effect carries to writing|`cargo test -- --ignored generation_titration`, 30 calls @ .24
R43|the TYPE is the cheaper channel|the 2x splits 3 ways, ⊥ evenly: `working` & `bucket` sharp 3/3 vague 0/3 — their rule is MAGIC NUMBERS (`ENTRY_COST`, 4 bucket bounds) no signature carries ∴ prose is the only channel. `verdict` & `for_path` 3/3 BOTH — `enum Verdict{Fits{slack},Over{by}}` & named params already encode the rule ∴ vague prose costs NOTHING. `is_yes` 0/3 both = beyond the frontier at every wording|derived from R42
R44|sharp wording is 3.3x|extended corpus, 11 pure fns × sharp\|vague × 3 runs, 66 calls, graded by `rustc` on HIDDEN tests: sharp 30/33 (91%) · vague 9/33 (27%). at SHARP wording the 20B wrote 10 of 11 correct ∴ the frontier for `one pure fn from a fixed signature` is FAR wider than assumed — `src/tdd:T13` 0 merit wins is evidence about the TASK SHAPE `sherd tdd` uses, ⊥ about capability|`generation_titration`, 66 calls @ .24
R45|the type ! carry the DECIDING rule, ⊥ the answer SHAPE|R43 pre-registered as classes, scored 8/11. `checked_working` predicted Type & behaved Prose: `Option<u64>` says CAN FAIL, ⊥ FAILS BELOW 28,543 ∴ shape ⊥ content. `parse_limit` & `escape_cell` predicted Beyond, both PASSED @ sharp ∴ a 3-rule parser & an escaper are INSIDE. both frontier misses erred PESSIMISTIC. `is_yes` alone is beyond at any wording|derived from R44
R46|plan coverage is 3 of 78|`sherd plan`: 3 actionable rows across the whole repo (`src/tdd` T13 — itself a MEASUREMENT row —, `src/ollama` T3, `src/review` T3), 69 unmanaged: 26 root rows w/ no `mod.rs` · 23 edit specs\|wiring ⊥ add a fn · 9 need `main.rs` · 7 write beyond their module · 2 replace ⊥ append · 2 research. ∴ ANY per-node `sherd tdd` experiment is bounded by TASKS ⊥ by clock, & 2 usable nodes is ⊥ a sample (`src/plan:B8` measured 5 of 21; it is now 3 of 78)|`sherd plan`, measured
R47|code size, ⊥ one runner|`src/tdd/mod.rs` 62,963B code (~4x V50's 4,000 tok) + 25,612B tests (~3x the 2,000). `src/cli` 25,122B, `src/ollama` 23,032B, both over. longest fns: `drive_from` 313 lines · `run_sampled` 100 · `expected_calls` 75 · `oneshot` 63. ⊥ a function-size rule anywhere, & V50's file rule has no runner (B11)|`wc`, split @ col-0 `#[cfg(test)]` as `split_module` does
R48|the density map named a NODE|`src/tdd` structural violations cluster into 3 concerns ⊥ spread evenly: the LOOP (`drive_from` 267 lines/cognitive 21 · `run_sampled` 85 · `oneshot` 54) · SOURCE READING (`expected_calls` 70/14 · `signatures` 50/12 · `split_module`) · the experiment harness. & the source-reading cluster SPANS `src/review` too (`public_fns` · `unwired`) ∴ V109 produced a CROSS-NODE finding, ⊥ a file-size complaint — the duplication is ⊥ inside `src/tdd` & a purely internal split would have preserved it|derived from the T85 map
R49|node context changes NOTHING|T82 re-run, fixed harness, 66 calls, 0 errors: `bare` 30/33 · `ctx` 30/33 @ a 10,009-tok pack. the SAME single item (`is_yes`) failed 3/3 in BOTH ∴ a TRUE null, ⊥ two noisy sets cancelling. BOUNDED: these items are self-contained BY DESIGN ∴ this says context is SAFE, ⊥ that context is useless — a task needing the node's spec would be a different measurement. `is_yes` has now failed across 4 conditions (sharp·vague·bare·ctx) ∴ T81 has a stable frontier item to dissect|`context_titration`, 66 calls @ .24
R50|coverage is 64.76%, ⊥ 98|MEASURED once the flake carried `cargo-llvm-cov` + `llvmPackages.llvm` (nixpkgs rustc ships no `llvm-tools-preview`): lines 64.76% · regions 65.01% · fns 70.80%. by node: `code` 98.3 · `lens` 94.5 · `spec` 92.5 · `tokens` 88.9 · `state` 88.0 · `fed` 87.1 · `ollama` 70.9 · `tdd` 69.0 · `plan` 66.5 · `slice` 63.6 · `review` 63.0 · `land` 55.2 · `assay` 54.0 · `cli` 0.0. `src/cli` alone is 445 uncovered lines ≈ 11% of the crate ∴ a 98% floor is 33 points & weeks away, & would gate every commit red meanwhile|`cargo llvm-cov --summary-only`, measured
R51|a self-authored test is ANTI-correlated|T83, 33 measurements, impl written BLIND in both arms so the ONLY variable is which tests grade it. hidden 30/33 · own 26/33. the 2x2: own PASS+hidden PASS 23 · own PASS+hidden FAIL 3 · own FAIL+hidden PASS 6 · own FAIL+hidden FAIL 0 · own ⊥ compiled 1. ∴ the model's own test caught 0 of 3 wrong impls & REJECTED 7 of 30 correct ones — worse than a coin flip, which would have caught ~1.5|`authorship_titration`, 66 calls @ .24
R52|it fails hardest where it matters|`is_yes` — the ONE item beyond the frontier @ any wording (R45) — failed hidden 3/3 & its own test CLEARED it 3/3 ∴ when the model cannot write the fn, it cannot write a test that detects that either. `for_path` & `escape_cell` had CORRECT impls rejected by their own tests 3/3 each ∴ the test encodes a different reading of the invariant than the impl does, deterministically|derived from R51
R53|the mutation remedy is REFUTED|33/33 authored tests KILLED a known-wrong stub — 0 survived, 0 ⊥ compiled. control: the hidden tests kill all 11 stubs ∴ the mutants are real. the check proposed after T83 would have caught NONE of its failures: the tests are ⊥ vacuous|`authored_tests_vs_mutants`, 33 calls @ .24
R54|the failure is OVER-specification|`escape_cell`'s authored test demands `" a \| b "` → `"a\\\|b"` (spaces round the PIPE gone, where the row trims the CELL) & that an already-escaped pipe stays. NEITHER is in the invariant ∴ a correct impl FAILS it 3/3. the model fills an underspecified row w/ plausible unstated rules; the impl — blind, same text — fills them differently|`target/authored-tests.txt`
R55|the detector re-found R54's row, BLIND & mechanically|T97, 11 rows × 3 runs, 66 calls, every run IDENTICAL. ONE row flagged — `escape_cell` 3/3 — & it is R54's row, which a HUMAN found by reading raw output after the fact. the GAP: the row says pipe → `\|` & cell trimmed, & is SILENT on an ALREADY-escaped pipe ∴ the impl escapes it twice, the test demands it stay, & BOTH readings are in the row (`FORMAT.md`'s own rule is silent identically). the invented rule MOVES — R54's test demanded 2, this one demands 1 — & the row is flagged either way. ⊥ reproduced: R52's `for_path`, 0/3 here ∴ that was pooled, ⊥ per-item. 2 of 11 rows yield NO verdict, deterministically: `sign` 3/3 ⊥ compiled (`[i64; 10]` holding 9 elements — an ordinary compile error, ⊥ a `.:src/tdd:B12` name mismatch) & `abort_budget_ms` 3/3 HUNG ∴ `src/assay:B2` was ⊥ a one-off & `src/assay:V6` paid for itself on run 1|`cargo test --test ambiguity -- --ignored`, 66 calls @ .24
R56|an ignored body reads as uncovered|MEASURED `.coverage` 75.50 → 75.11 when the `#[ignore]`d titrations moved from `src/assay` inline tests to `tests/`. an ignored test body counts in the coverage DENOMINATOR & never runs ∴ every experiment added inline LOWERS the number & a better instrument reads worse. carried out of `T96` when that row went — the row was history, the measurement is not|`tests/`, `cargo llvm-cov`
R57|seam-first beats dep-order|a sibling repo built 7 federated nodes in PARALLEL, 1 worker per node, after ONE commit declared every node's public TYPES: 27 commits, 277 tests, 7,003 lines, 1 integration break (a type gained a field after a consumer had written fixtures against it). scheduling the SAME DAG by dependency instead = 5 deep, ≤3 nodes ever in flight|measured 2026-09-17, repo anonymous
R58|what B29 actually cost|`V50` counted every line below a file's 1st `#[cfg(test)]` as TESTS ∴ the CODE number was measured over the HEAD of the file only. RE-MEASURED @ T107, 32 `.rs` files, 24 → 26 over an advisory ceiling: `src/cli/mod.rs` code UNDER 4,000 → 20,082 & tests 30,289 → 14,227 · `src/plan/mod.rs` 4,468 → 10,729 & 16,879 → 10,619 · `src/code/mod.rs` 4,405 → 7,699 · `src/fed/mod.rs` 4,243 → 5,984 · `src/spec/mod.rs` UNDER → 5,425 · `dev/src/badge.rs` UNDER → 5,945. `src/cli` is the case: its 1st marker is a `#[cfg(test)] fn repo_root()` on line 330 ∴ 20,082 tok of DISPATCH counted as test weight & the largest code file in the tree reported NO code violation. B29 was found on `src/plan` @ 337 lines & is 4x that here ∴ the row UNDERSTATED its own scale, ∵ it was written from the 1 file that happened to show it|`sherd check` before & after T107, `38e1ae4`
## §V INVARIANTS
V1: ∀ `§F` row → child dir exists ∈ fs
V2: ∀ `§F` row → child depth = parent depth + 1
V3: ∀ dir w/ `SPEC.md` & non-root → ≥1 parent `§F` row points at it
V4: federation graph ! DAG. cycle → `validate` exit 1
V5: root `SPEC.md` ! exist @ repo root
V6: node pack ≤ `budget.node` tokens (default 2000)
V7: chain pack (root→dir) ≤ `budget.chain` (default 8000)
V8: lens pack (chain + child `§F` lens) ≤ `budget.lens` (default 12000)
V9: node over `budget.node` → `check` emit split hint naming candidate child dirs
V10: ids namespaced by dir path — `src/plan:V3` ≠ `src/spec:V3` (both real, both V3). bare id = current node
V11: cross-node cite ! namespaced. bare cross-node cite → exit 1
V12: ∀ id monotonic **within node**. ⊥ reuse. APPEND ⊥ insert
V13: invariant crossing 2+ children → ! live @ common ancestor, ⊥ duplicated per child
V14: bug @ leaf → `§B` @ leaf. cause spans 2+ nodes → invariant promoted to ancestor
V15: `lens` output self-contained @ its altitude — ⊥ require sibling|child body to act
V16: dir w/ source & ⊥ own `SPEC.md` → ! covered by nearest ancestor `§F`.lens, else `validate` warn
V17: token count via `itok` tier ≥ `bpe`. `dummy` (bytes/4) ⊥ for any gate
V18: parse/DAG/budget/ceiling ⊥ call model. `--offline` → all cmds but prose gen work
V19: `route` descend one edge per step, reload only that child. ⊥ load whole tree
V20: `route` ambiguous → exit 3 + candidates. `route` miss → exit 2 naming what was tried. ⊥ exit 0 empty
V21: `§F`.tokens stale (≠ recomputed ±10%) → `check` flag
V24: ∀ emitted token number ! carry method label. ⊥ bare int
V25: `ollama` tier unreachable → fall back `bpe` + warn stderr. ⊥ fall to `dummy`, ⊥ silent
V26: `§F`.tokens written & checked by same tier. tier switch → recompute all
V27: this repo ! valid federation. `sherd validate` on self exit 0, CI gate
V30: bootstrap — parse/DAG/budget land before self-spec written. ⊥ claim dogfood til self-validate green
V34: ∀ non-root `SPEC.md` ! carry `§N` — `up` ≥1, `self` = 1, `sib` = ∀ co-child — lens `-`, read it in the parent `§F` (`src/fed:V24`)
V36: `§F` authoritative, `§N` generated. mismatch → `§F` wins, `sync` rewrites. ⊥ hand-edit `§N`
V39: multi-parent → `up` 2+ rows. `sib` = union ∀ parent, deduped
V40: `§N` alone ! answer "where am I, what is beside me" ⊥ opening another file
— two axes —
V42: federation has 2 axes. **horizontal** = dir depth. **vertical** = detail (`rule` → `why` → evidence). node over budget → vertical FIRST, horizontal only if rule-only still over.
V43: `§V`/`§B` statement = rule + rationale. rule inline @ `SPEC.md`, rationale @ `SPEC.why.md` keyed by id.
V44: vertical split lossless **by reference ⊥ by deletion**. ∀ id ∈ `SPEC.md` → row ∈ `SPEC.why.md` | explicit `-`. rationale is where closed-option records live
V45: `lens --depth rule` default. `why` pulled on demand, ⊥ resident.
V46: budget sized against MEASURED entry cost, ⊥ raw window. measured: harness overhead ~28,543 tok before any file ∴ `budget.lens` + entry ≤ 40% of 131,072
— guards learned from `itok`/`microlith` §B —
V47: `§F`/`§N` are FORMAT extensions, canonical in microlith ≥ 0.7.0 (`microlith/V39`). a further section letter ! be negotiated upstream first. ⊥ ship a dialect microlith cannot read
V48: ∀ report ! state what was EXAMINED, ⊥ only what failed. node discovered & ⊥ parsed = FAIL, ⊥ skip.
V49: split (either axis) ! PROVE item-set preserved before write — ids(parent) ⊆ ⋃ ids(children ∪ parent′), asserted pre-write.
V50: `.rs` file **code** > `ceiling.file` (default 4000 tok) → `check` violation, kind `judgment`. tests counted separately vs `ceiling.test` (2000). ⊥ one ceiling over both
V51: `mod.rs`/`lib.rs` ceiling = `ceiling.mod` (default 1500) — tighter. it COMPOSES, ⊥ implements (`default.nix` does the same).
V52: ceiling forces a REVIEW, ⊥ a shrink. raise = reviewed event, reason in the commit.
V53: `split` proposal ! report COUPLING after the cut, ⊥ sizes alone.
V54: `Mechanical` ⊥ mean easy — it means the tool computes the SINGLE answer. where to cut a module is ⊥ computable ∴ every `split` direction is `Judgment`.
V55: ∀ printed id qualified (`sherd/V13`) — an unqualified id lands in the CONSUMER's namespace where it names a different rule. coordinates stay `file:line:`, id beside the message ⊥ inside them
V56: guard & rule ! share a UNIT. ceiling in `itok` tokens, cap in chars, order in lines — each states its unit at the point it gates
V57: CI globs by DATA DEPENDENCY ⊥ file extension. a step's glob ! name every input its tests read
V58: grammar ⊥ ship til run over a corpus. `§F`/`§N` recognition measured over the 54-spec fleet & FP rate reported. a false positive naming the wrong rule costs more than a false negative
V59: "X absorbs Y" ! name a MEASUREMENT ⊥ a belief. ⊥ delete|skip building Y til capability parity vs Y is written down.
V60: premise MEASURED (R29/R32/R33): decomposition bounds the MAX CALL ∴ the claim is FITTING. ⊥ cheaper in total (varies w/ retries), ⊥ better in quality when both succeed. monolith 1/3 green vs decomposed 3/3
V61: ∀ guard proven by a PLANTED violation + a companion proving it accepts real shapes. ⊥ proven by reading it
V62: sibling divergence report — near-duplicate invariants across sibling nodes = V13 promotion candidates.
V63: registry-owned identifier checked by ASKING the registry, before it appears anywhere a user can run
— lens = decidable, ⊥ descriptive —
V64: sibling `§F` lenses ! EXHAUSTIVE — ⋃ child domains + what parent keeps = parent domain.
V65: sibling `§F` lenses ! DISJOINT — 2 siblings claiming one ground → `route` ! open both ∴ V19 one-edge descent unsound. overlap → `validate` exit 1
V66: ∀ `§F` row ! state `⊥owns` + where it lives.
V67: lens written in vocabulary of the QUESTION ⊥ the implementation.
V68: `§F`.lens length scales w/ P(descend) × cost of a wrong descend, ⊥ w/ child size.
V69: ∀ `§V`/`§R`/`§B` row inline ≤ `cap.row` (default 200B). rationale by reference → `SPEC.why.md`.
V70: `cap.row` enforced BEFORE rationale is written, ⊥ after.
— module as unit —
V71: facade dir named by CAPABILITY ⊥ vendor — `src/tokens/` ⊥ `src/itok/`. vendor named in `owns`/`⊥owns`
V72: ∀ external dep ! have ONE call site — its facade `mod.rs`. siblings private ∴ **compiler** enforces it (`error[E0603]`), ⊥ grep.
V77: federation's payoff on local hw is CACHE LOCALITY, ⊥ only fit. root+ancestor prefix byte-identical across ∀ node ∴ stays hot; only the leaf re-prefills.
V82: SETTING enters a pack as CONTRACT ⊥ implementation — one line per guard (`line cap 80`, `clippy pedantic`, `coverage floor 98`). ~200 tok replaces ~31k.
V83: structural diagram GENERATED from `§F` (`graph --mermaid`), ⊥ authored.
V84: guard-infra encoding FLEET standard is materializable (flake input, content-addressed). repo-specific facts — tests, `.context-limits`, baselines — STAY. ⊥ materialize what encodes THIS repo
V100: a principle a machine can CHECK belongs in a gate or a shape, ⊥ a prompt. ∴ prefer structure > gate > prompt, & a principle that becomes a check should LEAVE the slice
V96: assets classed by AUDIENCE, ⊥ only by concern. **worker** → the 20B prompt · **supervisor** → the higher agent only · **human** → readers.
V97: audience enforced by DISCOVERY, ⊥ convention. `.claude/`, `.github/`, `.codex/` ⊥ walked ∴ a `SPEC.md` dropped there can never become a node & can never reach a prompt
V92: TWO brains, split by what each can do. local 20B writes code from a narrow context; the higher agent JUDGES.
V98: a run duration is a FLOOR, ⊥ a ceiling. finish the cycle in flight, then check the clock
V99: a run ENDS in a summary commit — cycles, what was applied & judged, anchors planted, halt cause, cost, what is next. autonomous means the report ! survive where a human finds it, same argument as V95
V95: a halt is COMMITTED (`--allow-empty`), ⊥ only printed. autonomous means nobody reads stdout ∴ the reason must survive in git where a human finds it later
V93: the loop STOPS on: nothing actionable · same row failed 2x · `check` unclean · 2 aborts @ 10x · 2 reverts in a row.
V94: nothing actionable → MAINTENANCE, ⊥ done. §B w/o §V · claims w/o runners · duplication · unmanaged rows · budgets · stale §R
V91: ONE primitive at every axis — a cheap summary that supports a decision + a pointer to the expensive thing. horizontal `§F` owns/⊥owns → child. vertical rule → `SPEC.why.md`. facet contract line → implementation
V74: §C claims ! have a runner. — a constraint no check reads is a comment
V75: format facts read from the CHECKER's own source, ⊥ a vendored `FORMAT.md`.
V101: a dep ! resolve to an IMMUTABLE artifact — registry version + lock checksum. a new path dep ! carry a §B-recorded reason
V102: a gate ! declare its OP SET as data, ⊥ bury it in a hook body.
V103: the criterion ⊥ WEAKEN as the rung narrows — a rung-4 task judged against the same `§V` as a rung-1 one, else the descent proves nothing. success below the verifiability floor is recorded UNVERIFIED, ⊥ kept
V104: a declared LIMIT ! have a runner that EXITS NONZERO — V74's shape, widened from §C to any number the spec names. V6/V7/V8 declare ceilings, `.context-limits` carries them, `sherd budget` PRINTS them & exits 0 ∴ 4 nodes drifted over unseen (B7). & a path w/ NO ceiling row is UNCHECKED ⊥ unlimited: absence ! read as violation or default, ⊥ as permission
V105: a declared OPTION ! CHANGE BEHAVIOUR. testable ∀ flag: same input, two settings, DIFFERENT output — a flag whose branches agree is a claim w/ no runner (V74)
V106: BUILDABLE on the 20B = (a) chain + the file it edits fits working budget & (b) ∃ a rung where the output SURVIVES REVIEW (⊥ merely the gate) & (c) setup cost < writing it by hand. a module claimed buildable w/o (b) & (c) measured is a wish (`.:B4`: name the denominator)
V107: push the invariant into the TYPE & the SIGNATURE before sharpening its prose — & the type ! carry the DECIDING rule, ⊥ merely the SHAPE of the answer.
V108: an experiment comparing 2 conditions ! differ in exactly ONE variable.
V109: clippy violation DENSITY = a 3rd dir-promotion trigger (V73 has 2). a file whose fns keep tripping `too_many_lines`/`cognitive_complexity` holds several concerns, & the CLUSTER names the SEAM — where V50 says only `too big` & leaves the boundary to eye. limits ∴ ⊥ hygiene: they are how federation boundaries are DISCOVERED ⊥ guessed
V110: decomposition is ⊥ uniformly costly — BREADTH & DEPTH differ & the rule must ⊥ discourage the cheap direction w/ the dear one. prefer siblings. ∀ proposed split ! carry `sherd budget` before/after
V111: a test the WRITER authored ⊥ grade that writer.
V112: test-vs-impl DISAGREEMENT measures the INVARIANT, ⊥ the code. both written blind from ONE row, they disagreed 7 of 33 (R51), & the disagreements are gaps the row left open (R54) ∴ 2 calls + a compile is a mechanical AMBIGUITY DETECTOR for a `§V` row. it grades the SPEC — & unlike a mutation gate (refuted, R53) needs no reference answer
V113: GENERATED means a RUNNER regenerates it, ⊥ that it was generated once. an artefact spliced by hand & never re-spliced is indistinguishable from a hand-written one the day after, & the sentence claiming otherwise is the most misleading line on the page (B16). ∀ generated block ! carry markers, a generator, & a `--check` in the gate
V114: an EVEN minor is STABLE; an ODD minor is FUNCTIONAL & ⊥ for PRODUCTION. parity classifies the RELEASE, ⊥ the work in it — it answers *may I run this tag in production?*. RETIRES @ `1.0`, where every minor after is stable by definition
V115: §I is what SHIPS. ∀ verb the binary dispatches appears in §I, & ∀ §I cmd either dispatches or carries its rung
V116: a COUNT derived from a tool's output is ⊥ a measurement until the tool is known to have RUN. `cargo clippy` prints no warnings for a target that fails to compile, `cargo llvm-cov` reports no lines for a suite that did ⊥ build, & every such silence reads as GOOD NEWS to a ratchet. ∀ step deriving a number ! refuse on the tool's own error before comparing (B18)
V117: the MODEL half is FROZEN until rung `0.7` (V114). `src/ollama`·`src/tdd`·`src/assay` WORK & no further development lands there before the mechanical surface is published. an open §T row in those 3 nodes is 0.7 work BY LOCATION, ⊥ by a label anyone has to maintain
V118: IDEMPOTENCE has 3 LAYERS & we have broken each exactly once. (1) WRITE — `f(f(x))=f(x)`, stated at `src/cli:V13`, broken by `src/cli:B4`. (2) MEASUREMENT — the number ! be a fn of the TREE ALONE: `src/debt:B1` (clippy is silent on a target that ⊥ COMPILE ∴ 270→180 read as debt PAID) & `src/ollama:B8` (coverage 75.35 vs 75.26 on ONE tree ∵ the suite shares `.sherd-state` & line execution depends on run ORDER). (3) FEEDBACK — a measurement ! ⊥ read what its own generator WROTE, or generating MOVES the number & nothing converges (`src/split:V3`). a ratchet asserts MONOTONE over a measurement ∴ a measurement that is ⊥ a fn of the tree makes the ratchet a guard firing on NOISE, & a ratchet ! also measure the SHIPPED config — `default = []` here, while every count we keep is `--all-features` (B20), & every one of the 3 was found by a HUMAN reading a number that ⊥ move the way the tree did
V119: `V50` is measured PER `.rs` FILE ∴ a node may hold a 2nd `.rs` BESIDE `mod.rs` & `§C`'s ban is on the 2018 `foo.rs`+`foo/` shape — a facade OUTSIDE the dir it fronts — ⊥ on a 2nd file INSIDE it. `src/cli` does, split by verb family (#39, `src/cli:V18`) — this states it is allowed, ⊥ that it is usual
V120: SIZE EQUALITY across nodes is ⊥ a health signal & optimising it costs boundaries. what IS a signal is size PLUS a lopsided `§B` count
V121: agentic debt resolution splits in 2 & only 1 half is a PIPELINE. the MECHANICAL half has a named transform ∴ detect → name the SHAPE → hand the model both → gate → repair, & every stage already exists (`src/review` detects, `src/debt` measures, `src/tdd` drives, `src/land` gates). the JUDGEMENT half does ⊥: `src/cli` B5·B6·B7·B8 — wrong root, absence-as-success, a position-shaped fix, a default read as a gate — are DESIGN defects, no catalogue detects them, & all 4 came from pointing the tool at a stranger & READING. the shapes are worth mining as a BY-PRODUCT of mechanical work; building the catalogue AS A PROJECT on the presumption is `.:B24` one level up — run what exists & measure what it leaves, before building
V122: a workflow ! be AUDITED, ⊥ merely PARSED — & the audit runs at the STRICTER persona w/ a LEDGER for what it declines. `actionlint` type-checks (expr types, `run:` via shellcheck, runner labels, cron) & knows ⊥ about token SCOPE; `zizmor` audits scope · credential persistence · template injection · pinning & does NO syntax check ∴ neither substitutes for the other & swapping them trades a blind spot for a blind spot. `--persona=pedantic` reports SMELLS — claims about how a file AGES, ⊥ about what it does today — & conforming to the stricter reading is what produces the pristine file. ∀ DECLINED finding lands in `.github/zizmor.yml` w/ its reason AND its EXIT CONDITION, ∵ an ignore w/ no exit ≡ one nobody revisits (V74 pointing the other way), & line numbers are part of the match ∴ drift RE-OPENS it.
V73: dir promotion has 2 triggers — (a) V50 code ceiling, (b) module owns SPEC worth its own node even under ceiling. vendor facades are (b): few hundred lines carrying V17/V24/V25. ⊥ promote every `.rs`
V123: the EXECUTOR is an ADAPTER & sherd owns everything AROUND it: the code DAG, ready set, worktrees, ceilings, gate & merge order stay DETERMINISTIC & offline (V18). WHO writes the code is NAMED — local model | external command — & swapping it changes ⊥ about scheduling.
V124: TESTS live in a `tests/` tree beside the code they test, ⊥ inline `mod tests { }`. include as `#[cfg(test)] #[path = "tests/x.rs"] mod tests;` — a CHILD module ∴ private fns stay reachable; the crate `tests/` dir sees `pub` only & widening a published API to test it is the wrong trade. a `tests/` file NOTHING reaches is ⊥ compiled ∴ its tests pass by ⊥ existing — every one ! be reached (B33). V50 measures a file under a `tests` path component as tests in FULL
V125: a gate step that RUNS this repo's binary ! first prove the binary was built from THIS tree. cargo judges freshness by the mtimes of the files its dep-info lists, & a binary built from `cargo package`'s unpacked copy lists `target/package/sherd-<ver>/src/…`, which never changes ∴ `cargo run` calls it fresh forever & every dogfood step judges OLD code. `scripts/fresh-binary.sh` refuses when `sherd.d` or `sherd-dev.d` names a `package/sherd` path, & every step that runs either binary depends on it (B34)
V126: `paradigm/V28` via `pklith` checks (owner 2026-10-24). flake `systems` = the 4. `.cargo/config.toml` `[env] MACOSX_DEPLOYMENT_TARGET = { value = "14.0", force = true }`. `cargo-deployment-target` judges it @ COMMIT. `cargo-universal` (both Macs' release bins `lipo`-joined = arm64 + x86_64, each minos 14.0) @ RELEASE ONLY: `pre-release-hook` → `hk run release`, built from CLEAN, on macOS only — a release from any other host REFUSES, ⊥ skips
## §T TASKS
id|status|task|cites
T3|.|capability-parity audit `microlith` vs what `sherd` needs. write the comparison BEFORE relying on it|V59
T12|.|id namespacing + resolver `path:Vn`|V10,V11
T19|.|route ambiguous exit 3 / miss exit 2|V20
T23|.|coverage gap warn for un-specced source dirs|V16
T28|.|backprop: bug → leaf `§B`, decide promote|V14
T37|.|`sherd sync` + exit 1 when wrote|I,V36
T42|.|cross-file losslessness proof, asserted pre-write|V49,V44
T46|.|coupling report after proposed split|V53
T47|.|violation renderer `file:line: sherd/Vn:` + why + mechanical\|judgment + json `kind`|V55,V54
T48|.|sibling-divergence detector for V13|V62
T49|x|`§F`/`§N` upstream to FORMAT/microlith before shipping a dialect. done = microlith claims both as canonical letters (`microlith/V39`) & publishes them in `FORMAT-EXTENSIONS.md`, rendered from the constants its checker reads (`microlith/V40`), since microlith 0.7.0 (`7c2c92c`). routing them on to cavekit FORMAT.md is microlith's task, ⊥ ours|V47
T50|.|corpus run over 54-spec fleet, FP rate reported|V58
T52|.|planted-violation test ∀ guard + accepts-real-shapes companion|V61
T58|.|`cap.row` gate — inline `§V`/`§R`/`§B` text over 200B|V69,V70
T59|.|PAY THE DEBT: record rationale for V1-V63 into `SPEC.why.md` before it accretes inline. rationale currently lives only in the design conversation|V69,V70,V44
T64|.|setting-as-contract extraction — guard files → one line each|V82
T67|.|materializability audit: which guard files are fleet standard vs repo facts|V84,R20
T68|.|report caveman 22%-⊥-75% upstream to cavekit FORMAT.md|R23
T73|.|`/titrate` machinery — `.sherd-frontier` record, believability re-keyed node → SHAPE, cost ledger w/ the denominator named (`.:B4`)|V103,V60
T76|.|BUILDABILITY SWEEP: `sherd tdd` @ every node, N=3, record (node, rung, kept/tried) → `.sherd-frontier`. answers WHICH modules are buildable, ⊥ whether the idea works|V106,V103,R37
T80|.|audit `§V` rows for what a TYPE could carry instead (V107). the rows that need prose precision are the ones no signature can hold|V107,R43
T81|.|`is_yes` is the ONLY item beyond reach @ sharp wording (R45) — find WHY. 3 conjoined rules (first line · case-insensitive · trim) or something else? it is the one datapoint about what the frontier is MADE of|V107,R45
T86|.|build the FILE-ceiling runner V50 never had into `sherd check`, wire it like `budget`. §I already claims `check` does it (B11)|V50,V104,B11
T88|.|`no-commit-to-branch --branch main` in the PRE-COMMIT set only — ⊥ `all`, or CI on `main` fails itself (microlith's note). AGENTS.md claims it & nothing enforces it (B12)|V74,B12
T89|.|pub-fn ↔ test PAIRING via `sherd review` — reuse `public_fns`/`expected_calls`, ⊥ reimpl. catches what a % hides: a fn w/ NO test, carried by its neighbours|V72,V16
T91|~|`src/cli` FIRST: 445 lines, 0 tests, 0% — found twice by different instruments (T85 density map, R50 coverage). biggest single lever on the floor & the node w/ no test module at all|R50,V16
T92|~|`src/tdd`: move `RECORDED`/`VAGUE`/`SUBTLE`/`GEN_CORPUS`/`grade`/the titrations behind `#[cfg(test)]` — they are FIXTURES in the impl half — & decompose `drive_from` (267 lines, cognitive 21, worst in the repo). the source-reading half leaves via T93, ⊥ internally (R48)|V50,V109,V110,R48
T103|~|LADDER rungs as work: 0.4 = `split`+`sync` DONE · 0.5 = the MECHANICAL surface correct & reusable, measured on a foreign repo · 0.6 = settle · 0.7 = the model half resumes (V117) — & @ 0.7 the 1st question is `src/assay:T6`, whether a FIX SHAPE beats a `§V` ROW: the 4th variable of the `.:R44` gap & the only one untried (V121). 0.1-0.3 reached|V114,V117,V121
T104|.|lint ratchet ! also count `--no-default-features` — 131 warnings on the SHIPPED binary are uncounted today|V118,B20
T106|.|`wave` EXECUTION @ rung 0.7 — fan the scheduled rounds out to N workers, 1 worktree each, gate & merge in topological order; executor NAMED ⊥ assumed|V123,V117,R57,`src/wave:T1`,`src/ollama:T13`
T107|x|V50 splits a file @ the 1st `#[cfg(test)]` ∴ code BELOW a test module counts as tests (B29). sum every non-test region, re-measure|V50
T108|.|move each node's inline `mod tests { }` into its `tests/` tree per V124, 1 PR per node — none left outside the freeze; `src/assay`·`src/ollama`·`src/tdd` @ `0.7` (V117)|V124,V50
T109|x|flake inputs `nixpkgs-lock` & `nix-hk` fetched over GIT — `git+https://github.com/pr0d1r2/<repo>?ref=main&shallow=1`, ⊥ `github:`. a Claude Code cloud session's proxy 403s the ARCHIVE tarball `github:` downloads, even for a public repo, & passes plain git reads ∴ `nix develop` dies before eval. `flake.lock` still pins rev + `narHash`; both `follows` unchanged. done = `nix develop -c cargo test` in a cloud session w/ ⊥ `--override-input` (#96)|C
T110|x|`zizmor` hk step in a Claude Code cloud session (`CLAUDE_CODE_REMOTE=true`): run w/ `GH_TOKEN` & `GITHUB_TOKEN` UNSET — the cloud sets both to the placeholder `proxy-injected`, zizmor sends it & GitHub 401s — ∴ git reads go out anonymously; still unreachable → `--offline`, cloud ONLY. split by exit code: a FINDING keeps today's message, a run that never audited prints `zizmor could not run: <reason>` & still exits non-zero ⊥ a finding it never made. local & GitHub CI unchanged. done = `hk check --all` green in a cloud session (#100)|C
T111|.|x86_64-darwin in CI: GitHub's Intel macOS runners are retired; `paradigm/T19` has pipelith pick CI systems & actlith render them, & `ci.yml` is hand-written ∴ adopting that is its own PR. until then x86_64-darwin = eval + the release's x86_64 slice, built ⊥ run|V126
## §B BUGS
id|date|cause|fix
B1|2026-08-01|`fed::walk` hand-rolled while §C says fs walk = `itok::walk`/`itok::glob`, ⊥ reimpl. wrote it w/o reading itok's walk API — the exact belief-⊥-measurement trap V59 names, committed in the first commit that could commit it. ⊥ caught by `check`: no runner reads §C|V74. port to `itok::walk` or amend §C w/ the measured reason itok's walk ⊥ fit
B2|2026-08-01|`§R` written as RECORDS w/ `id\|state\|record`. FORMAT 4.1.0 §R = RESEARCH `id\|topic\|finding\|src`. assumed from a stale local `FORMAT.md` (6 sections) while the dep shipped 4.1.0 (7). 16 violations on first `sherd check`, all real|read the CHECKER's own `SECTIONS`/`CANONICAL_WORDS`, ⊥ a vendored copy. §R now RESEARCH; closed options → `.spec-records` (R13)
B3|2026-08-01|SPEC defect, mine: `src/lens:V8` written as a STATIC partition — SET = impl+spec+agents, SETTING = tests+guardrails — & committed. TDD breaks it: the test IS the work ∴ `tests` ∈ set, & nothing about the file changed. facet (property of the FILE) conflated w/ profile (property of the TASK). MEASURED after: `tdd` loads 81.4% of itok, `refactor` 80.9% ∴ the axis nearly collapses for 2 of 5 profiles|`src/lens:V8` now names the classification only; `src/lens:V13` adds PROFILE as the task-dependent selection; `src/lens:V14` records that facet × horizontal = 6.1% where facet alone = 81.4%. found by a READER asking about TDD, ⊥ by any check — no gate reads a partition's fitness for a workflow
B4|2026-08-01|SPEC defect, mine, repeated across ~6 commit messages: claimed "95x on the binding constraint" comparing our max call to 157,071 — which is `itok`'s WHOLE-REPO tdd profile, ⊥ what a one-call prompt needs. MEASURED baseline for the same task = 2,659 tok ∴ real ratio 2.1x. compared against a straw man nobody would build|`sherd oneshot` built as the honest monolith arm; R29/R30 carry the measurement; V60 restated. GENERALLY: a ratio ! name what is in the DENOMINATOR & that thing ! be something someone would actually do
B5|2026-08-05|HEAD stopped COMPILING w/ ⊥ sherd commit. `67fa9ad` (08-02 10:26) imported `microlith`'s inner `violation` module & the gate passed; microlith privatized it 9h later (`421ab02`, 08-02 19:16) ∴ E0603 on a tree already judged green, & already pushed. `../microlith` was a path dep ∴ no version could hold it still, & `Cargo.lock` read `0.4.0` for a sibling saying `0.5.0`|`microlith` = crates.io `0.5` + lock checksum (V101). `itok` too (T71) ∴ none left. `src/spec:B1` carries the import half
B6|2026-08-18|gate ran `build` + `test` ONLY, from the first commit that had a hook — no fmt, no clippy — ∴ an entirely unformatted tree & 18 clippy findings accrued behind a verdict that read green every time. the ops lived as a shell BODY in `.githooks/pre-commit` ∴ the SET of checks was never reviewable data & nobody could see what was ⊥ there|ops → `hk.pkl`, file-scoped & readable; fmt + clippy gated & the debt paid (`790bcf6`). V102. `-D warnings` moved off `RUSTFLAGS` so it stops reaching `../itok`
B7|2026-08-18|`.context-limits` declares per-node chain ceilings & `sherd budget` PRINTED the table w/o comparing against them or failing — T10 sat `.` from the first commit ∴ every chain drifted over unseen. w/ the comparison RUNNING it is 13 of 13, ⊥ the 4 first counted: root alone grew 10,060 → 11,576 in ONE session & every chain pays root|V104. T10 built the runner (exit 1). `src/land`/`src/slice` inherit `src` by longest prefix — they are over an INHERITED ceiling, ⊥ unbounded as this row first claimed
B8|2026-08-18|`lens::pack` reads the WHOLE `SPEC.md` ∀ chain member & consults `Depth` only to APPEND `SPEC.why.md` ∴ `--depth rule` — §I's documented DEFAULT — selected nothing, & `§R`/`§B` archive has ridden in every pack & every budget since the command existed. MEASURED 33% of root, 59% of `src/tdd`, 58% of `src/plan`. `rule_depth` was written, tested & correct in `src/tdd` the whole time, called only by the tdd worker path|V105. T41 moves `rule_depth` to the owner & makes `Depth` select; T75 re-measures after
B9|2026-08-18|`sherd lens <dir>` passes `PathBuf::from(d)` straight to `pack` while `budget`/`fed` go through `arg_dir`, which T10 fixed to resolve against ROOT ∴ `lens .` reports a 2-node chain where `budget` reports 1 node for the same target, & from a subdirectory `lens` reads a truncated chain w/ no error. the same relative-vs-absolute defect T10 fixed, one command over, missed because the fix was applied to the HELPER & ⊥ to every caller|T78. GENERALLY: fixing a shared helper ! be followed by finding who does ⊥ use it
B11|2026-08-19|V50 declared a `.rs` file code ceiling from the first commit & `check()` runs ONLY `spec::check` + `unreflected_bugs` ∴ it has no runner — while §I claims `sherd check` does "drift spec↔code + file ceilings", which is FALSE. 3rd of this family in one week (B6 gate ops nobody declared, B7 chain ceilings nobody compared). MEASURED 4x over @ `src/tdd` (R47), unseen for the project's life|V104. T86 builds the runner; T85'"'"'s clippy limits catch the FUNCTION half V50 never covered
B12|2026-08-19|`AGENTS.md` says "Branch only. Never commit to `main`" & nothing enforces it ∴ ~20 commits landed on `main` in one session, mine, unchallenged & unremarked until a reader asked about something else. the rule was READ by the agent it governs & still lost to convenience|V74 again — a rule w/ no runner is a comment. T88 gates it in the PRE-COMMIT set only (⊥ `all`: CI runs `check --all` on `main` & would fail itself)
B13|2026-08-19|TWO readings of "parse Rust source" shipped across nodes: `src/tdd` has `signatures` (declarations + shapes) · `expected_calls` (call sites) · `split_module` (test boundary), `src/review` has `public_fns` (declarations) · `unwired` (declarations vs calls). both line-oriented heuristics over the same text, both already w/ §B rows for reading it wrong (`src/tdd:B13`, `src/tdd:B18`, `src/review:B2`) ∴ the founding defect §C names, in the repo that exists to end it. unseen until the T85 density map crossed a node boundary — no per-file gate can see a duplication that spans two files|T93 promotes `src/code` as the ONE owner. `split_module`'s own doc already says "two readings of one rule is the defect this project exists to end"
B14|2026-08-19|writing `src/assay/SPEC.md` in T94 I RESTATED 3 invariants that already existed — `V1`≡`.:src/tdd:V27`, `V3`≡`.:V103`, `V4`≡`.:V108` — instead of moving them ∴ two readings of one rule, the founding defect §C names, introduced ONE COMMIT after B13 recorded it & inside a node created to END a duplication. a new node's spec is written from the concern, ⊥ from the rows the concern already had, & nothing checks that|V74. T95 deleted the dupes. GENERALLY: promoting a node ! START by listing the rows that already own the concern — authoring fresh guarantees a second reading
B15|2026-08-23|`cargo build --no-default-features` FAILS — 4 errors, `src/assay` & `src/land` reach `crate::tdd` which is `ollama`-gated ∴ the featureless build has been broken since the feature split, while `Cargo.toml` DOCUMENTS it as "the deterministic, networkless core that §C demands". a claim in a manifest w/ no runner, unseen ∵ nothing ever built that configuration|T99 moved the gate cluster to `src/land` — its owner: `land` DECIDES whether work earned its merge — & gated `cargo build --no-default-features` in `hk.pkl`. `src/assay` is now feature-gated w/ the loop it measures. V74 again — & found by writing `default-features = false` in `dev/Cargo.toml`, ⊥ by any check
B16|2026-08-23|`.:README` Architecture said "generated by `sherd graph` — never hand-drawn, so it cannot drift" & had drifted: 7 nodes drawn, 17 real, missing `plan`·`review`·`state`·`slice`·`land`·`cli`·`code`·`assay`·`dev`. GENERATED once, by hand, then never again — the claim named a PROPERTY of the output & no runner held it. same shape as the badges one commit earlier, in the same file, w/ the sentence asserting the opposite ∴ a reader was told to trust the stalest thing on the page|V113. `sherd-dev readme` splices all 4 blocks from `fed::tree`/`mermaid`/`table` + the badge facts, gated by `readme-generated`. GENERALLY: "generated" is a claim about the LAST run, ⊥ about the artefact — it needs a checker like every other rule (V74)
B17|2026-08-23|§I specifies 9 cmds & the binary dispatches 14: `init`·`route`·`split`·`sync`·`validate` are SPECCED & unbuilt, while `apply`·`ask`·`fed`·`land`·`oneshot`·`outcome`·`plan`·`review`·`slice`·`tdd` SHIP & §I never names them. drift in BOTH directions, in the section a spec-driven repo can least afford wrong. `src/cli:V7` gained a runner for usage-vs-dispatch the same day & §I-vs-dispatch — one layer up — still had none ∴ 10 verbs shipped unannounced|V115. T102 builds the runner in `sherd-dev`, which already reads dispatch arms for V7. GENERALLY: a fix applied at one layer ! be followed by asking which layer above it has the same hole (`src/fed:B9` again)
B19|2026-08-23|1st run against a FOREIGN repo (`rekall`) & the ignore list was tuned to OUR tree: `result/` (a nix build symlink) & `pkl/` (the vendored hk schema) were advised as missing `§F` rows ∴ a stranger is told to federate their build dir. `route` on an UNFEDERATED repo answered "no node matched" — true & useless, ∵ w/ 1 node & root excluded ⊥ query can EVER hit ∴ the asker rephrases a query that cannot succeed. neither is visible from inside a repo shaped by the tool that reads it|both fixed + `result-*`·`vendor` added. `route` names the real cause & points at `sherd init`. GENERALLY: a default tuned on 1 tree is a claim about ALL trees — the 2nd repo is where it gets tested, & `.:T103`'s rung 0.5 exists ∵ of exactly this
B24|2026-08-24|we have hand-applied ONE transform 34 times across 2 commits (`len()` check + positional index → slice pattern) & a 2nd that removed 24 index sites in 1 commit, & NOTHING recorded either ∴ the 3rd author to meet the shape re-derives it. asked whether AST "cops" w/ autocorrect were the answer & MEASURED the premise 1st: `cargo clippy --fix --workspace --all-targets --all-features` changes NOTHING on this tree — 252 warnings before & after, 0 diff — ∵ every warning we carry is marked ⊥ machine-applicable. the autocorrecting cop framework already SHIPS & our residue is exactly the half it declines\|`src/review:V9`. `fix_shapes` NAMES 3 mined shapes & applies none. EVIDENCE that naming is the right half: 2 of my own first attempts at these rewrites were REFUSED — `hits.first().map_or(..)` by clippy's `explicit_auto_deref`, `d.first().map(\|x| x.rule)` by `E0507` — ∴ the correct rewrite needs a TYPE, which means rustc, ⊥ a text scanner. our hand-rolled `fn_body` also broke twice in 1 hour (char literal `'{'`, lifetime `<'a>`) ∴ ⊥ hand-roll more parsing. GENERALLY: before building a tool, run the one that exists & measure what it leaves
B25|2026-08-30|the SUITE committed to the repo it was running in. git exports an ABSOLUTE `GIT_DIR` to hooks when the checkout is a WORKTREE (unset in a normal one) & every child inherits it ∴ `cargo test` under the pre-commit hook handed `TestRepo` a `GIT_DIR` aimed at the real repository. `current_dir` sets where git RUNS, ⊥ which repo it ACTS ON — env beats discovery ∴ `init`+`add -A`+`commit -m root` landed a commit deleting 90 files & leaving the fixture `SPEC.md`. invisible on `main` ∵ there `GIT_DIR` is unset|`TestRepo::command` env_removes the 8 exported `GIT_*`; 2 regression tests. GENERALLY: a fixture that shells out ! clear the env its runner exports — cwd is ⊥ isolation
B26|2026-08-30|the DEFAULT build warned & every gate step read GREEN. `f6793df` emptied `default` ∴ `apply` (`ollama`-gated) stopped compiling by default & took `preflight` — its only non-test caller — with it, while `run_args`'s `mut` existed only for the gated `-v` removal. 2 warnings rode through 11 gate steps, `cargo release hook`, the published `.crate` AND its verify. `clippy` denies warnings but runs `--all-features` ∴ never compiles this config; `no-default-features` compiles it & accepted warnings ∴ the shipping config was the one nothing held to a standard|`preflight` + its 3 tests gated w/ `apply`; `mut` shadowed under the feature. `no-default-features` gains `RUSTFLAGS=-D warnings` — safe only ∵ V101 made `itok` a REGISTRY dep & cargo caps lints for those, ⊥ for path deps. GENERALLY: a feature split ! be followed by asking which config the GATE actually compiles
B27|2026-08-31|`cargo release push` could ⊥ push a TAG ∴ the release stopped 1 step from done, twice. git hands `pre-push` `<local ref> <local sha> ...` & for a tag that sha is the ANNOTATED TAG OBJECT, ⊥ a commit; hk 1.55.0 feeds it to merge-base w/o peeling → `object is no commit object` @ hk `src/git.rs:1678`. our hook `exec`s hk on EVERY ref shape ∴ inherited the crash. workaround was `--no-verify`, which the hook's own text forbids — & the gate ⊥ REFUSED here, it CRASHED (`src/tdd:V26`: a gate that ⊥ RUN is an ERROR, ⊥ a breach)|hook peels `^{commit}` & SKIPS only when every pushed ref is a tag ALREADY reachable from `origin/main` — that commit passed this hook & CI already; a tag is a pointer to it. a branch ref, or a tag OFF trunk, still pays the gate. 3 cases MEASURED before trusting it. GENERALLY: a hook that `exec`s one tool on every ref shape inherits that tool's ref-shape bugs
B28|2026-09-09|both workflows ran at whatever the REPOSITORY DEFAULT token scope grants — no `permissions:` block in `ci.yml` or `links.yml` since either was written — & all 3 `actions/checkout` steps left the job token in `.git/config` as an extraheader, readable by every later step in the job. a `run:` block also had its own source ASSEMBLED around `${{ github.event_name … }}` by the template engine ⊥ read from a variable. invisible ∵ the ONLY workflow check was `actionlint`, which type-checks the file & knows ⊥ about scope, credentials or injection ∴ 9 findings sat in 2 files that passed every commit of their lives|V122. `permissions: contents: read` @ both roots · `persist-credentials: false` @ 3 checkouts · the expression evaluates into `env:` & the shell reads `$FAIL_FAST` · 3 jobs NAMED after their own ids, ∵ a name that DIFFERS renames every status context & any branch protection citing the old ones strands `main` unmergeable. `zizmor --persona=pedantic -c .github/zizmor.yml` in the gate (34 steps), verified live by planting an injection (HIGH) & a 4th anonymous job. GENERALLY: a linter that PARSES a file says nothing about what that file can REACH
B29|2026-09-20|`V50` splits a `.rs` file into code & tests @ the FIRST `#[cfg(test)]` & counts EVERYTHING after it as tests ∴ production code written BELOW a test module is measured as test weight, & the code ceiling it was written under never saw it. FOUND by splitting `wave` out of `src/plan` (issue #21): 337 lines of scheduler LEFT the file & its `code` number did ⊥ move — 4,468 tok before & after — while `tests` fell 20,093 → 16,879. ∴ the 1 number a reader would check to judge the split reported NO change, & had been reporting the wrong half for as long as the scheduler had been there. `split_module()` is honest about what it does (`src/code`) & `V50` reads it as if a file held exactly 1 test module @ the end — a TRUE fn & a FALSE assumption about the shape of the input|T107 sums every non-test region. recorded ⊥ fixed here: the fix re-measures every `.rs` file in the tree & that is its own change w/ its own numbers. GENERALLY: a measurement is only as true as its assumption about the SHAPE of what it measures, & `4,468 before, 4,468 after` is what a measurement looks like when it is measuring the wrong region
B30|2026-09-30|`hk`'s `package-suite` unpacked `ls target/package/*.crate \| head -1` ∴ the OLDEST tarball: `target/package` keeps every release's `.crate` & `sherd-0.5.0-rc.1` sorts first. MEASURED in this checkout on #68's push: it compiled `sherd v0.5.0-rc.1` & reported 311 passing, while the tree's own crate carries 383. green on code 3 releases old, & the step named nothing it tested. CI unpacks a fresh target w/ 1 tarball ∴ only local runs were wrong|V48. the step reads `package.name` & `package.version` w/ `taplo`, unpacks exactly `<name>-<version>.crate`, refuses when that file is absent, & prints `package-suite: testing <name>-<version>.crate`
B31|2026-09-30|`check`, `validate` & `land`'s gate each did `let Ok(text) = read_to_string(SPEC.md) else { continue }` ∴ a DISCOVERED node whose spec could ⊥ be read was skipped & the tree passed. REPRODUCED on a 2-node repo whose `a/SPEC.md` is ⊥ UTF-8: `check` printed `2 nodes examined · 0 violations`, exit 0; `validate` `2 nodes · 0 structural`, exit 0 — V48 violated by the verbs that enforce it — & PINNED: `a_node_whose_spec_cannot_be_read_is_skipped` (2026-08-23) asserted the skip & cited V48 for it, though V48 has read `FAIL, ⊥ skip` since 2026-08-01. the same skip sits in `fed`, `plan` & `cli/propose` readers; fixing the 3 JUDGES makes them unable to report such a tree green|V48. the unreadable node counts as 1 violation in `check` & `validate`, printed as `<path>: sherd/V48: cannot read -- <error>`; `land::gate_with` counts it in `sherd check: FAIL`. the other readers still skip, but can no longer be the only witness
B32|2026-09-30|every scripted toolchain in the suite (6 helpers: `land` gate & git, `debt` debt & coverage, `cli` measure, `tdd`) was `fs::write` + chmod + EXEC at once, while other test threads spawn processes. on Linux a child forked while the script was still open for writing holds that descriptor until it execs, & exec of a file open for writing fails `ETXTBSY` ∴ the verb under test saw a toolchain that would ⊥ start. MEASURED: #75's ubuntu-latest gate, `package-suite`, `the_coverage_verb_checks_the_default_build_when_it_has_a_floor` got `could not read a coverage total`, exit 2 ⊥ 1 — the same test passed on arm & macOS in that run & on ubuntu in #67–#74. inferred from the mechanism, ⊥ reproduced: macOS has no `ETXTBSY` for scripts|`testrepo::write_script` writes, chmods & PROBES the script (`--sherd-probe`, which every script answers w/ exit 0 & no state change) until it execs, retrying on `ExecutableFileBusy`; after one exec no process holds the write descriptor. all 6 helpers call it
B33|2026-10-03|`src/adopt:V10` (#94) SHIPPED IN 0.5.3 W/ ⊥ CODE. PR #95 committed the spec row & `src/adopt/tests/script.rs`, & NO `#[path]` mod reached that file ∴ cargo never compiled it, its 3 tests never ran, & the gate was green over a feature that did ⊥ exist. the commit message described `split::cited_scripts` & `by_script` in detail; `git log -S by_script` finds them in NO commit, & `src/split` `§I` lists `cited_scripts` as lib. MEASURED: `git show v0.5.3:src/adopt/mod.rs` names ⊥ script, & the CHANGELOG entry for #94 shipped. AGENTS.md's list of vacuous passes, 4th entry: a test file nothing compiles is a suite that passes by ⊥ existing|V124: a `tests/` file ! be REACHED by a `#[path]` mod, & `tests/reached.rs` fails on any one that is ⊥. V10 implemented. GENERALLY: a commit message is a CLAIM, ⊥ a measurement — the diff is what shipped
B34|2026-10-03|`target/debug/sherd` was built from `target/package/sherd-<ver>/src` after a release, & cargo kept calling it FRESH ∵ its dep-info named the unpacked copy, whose mtimes never move. every `cargo run --bin sherd` gate step — `check`, `budget`, `slice`, `nav`, `lint-debt`, `coverage`, & `readme-generated` through `sherd-dev` — then judged a binary built from code ⊥ in the tree. RECORDED 3×: 2026-09-01 (`readme-generated` disagreed w/ a correct README), 2026-09-30 (`coverage` printed the pre-#67 1-row format ∴ the default-build floor was ⊥ checked), 2026-10-03 (`sherd.d` named `target/package/sherd-0.5.3` at session start, cleared by hand). the only visible sign each time was output in an OLD format; a stale binary whose format had ⊥ changed passes SILENTLY (#78)|V125. a step that fails on the dep-info, ⊥ on the symptom, & names the fix (`cargo clean -p sherd -p sherd-dev`). GENERALLY: a check that runs an artifact ! verify the artifact came from what it is checking
B35|2026-11-01|CI `gate` died in `lint-debt` w/ "clippy did not COMPILE" (`src/debt:V3`) while `test` was compiling beside it. both steps depended only on `clippy`, so hk ran them CONCURRENTLY & `sherd debt`s nested `cargo clippy` shared the target dir w/ `cargo test`. `lint-debt` alone passes locally (396 warnings, 13.4 per KLoC) ∴ the count was fine & the race was the cause. inferred from the log ordering, ⊥ reproduced|`test` now `depends` on `lint-debt` as well, serialising the cargo steps as the `hk.pkl` header says they must be. GENERALLY: a new cargo step ! be chained, ⊥ left beside a sibling
B36|2026-11-02|CI `gate` STILL died in `lint-debt` w/ "clippy did not COMPILE" after `B35`s chaining of `test`. ⊥ reproduced locally: `hk check --step lint-debt` passes (396 warnings, 13.4 per KLoC) & `cargo clippy --workspace --all-targets --all-features` has no `error` line. the CAUSE IS UNKNOWN. `measure` returned `None` w/ ⊥ output on three paths (spawn failure, an `error:` line, an empty tree) ∴ the CI log held nothing to diagnose, & B35 was inferred from ordering alone|`measure` now checks the exit STATUS as `V3` says, & prints the launch error, the `error` lines & the last 5 stderr lines before returning `None`. the next red run names its cause. GENERALLY: a gate that refuses ! say WHY, else the next fixer guesses
B37|2026-11-02|CI `gate` `lint-debt` died w/ "clippy did not COMPILE" — `B36`s diagnostics named the cause: `could not execute process .../ring-*/build-script-build (never executed)`, ENOENT. the `actions/cache` `restore-keys` fell back to ANY `cargo-<os>-<arch>-` entry, restoring a `target/` whose build scripts were linked against a nix store path the current `flake.lock` toolchain no longer has ∴ exec fails w/ ENOENT. ⊥ reproducible locally (no stale cache)|`.github/workflows/ci.yml`: key is `flake.lock` hash then `Cargo.lock` hash, & `restore-keys` falls back only within the same `flake.lock`. GENERALLY: a build cache ! be keyed on the toolchain at EVERY fallback level, ⊥ only the exact key
B38|2026-11-02|§I promised `lens --facet` & `graph --json`, neither ever implemented (`src/lens:T6`, `src/cli:T7`): the hand parser ignored both ∴ they read as working, MEASURED on 0.5.4 (4 `--facet` values, 1 pack). `src/cli:V21` now refuses them, exit 2, as written in §I. V115 compares verbs, ⊥ flags ∴ nothing caught it|§I names the flags that exist; the unbuilt half stays in §T
B39|2026-11-04|PR #165 (`hallucinogen/issue-129`, closes #129) sat w/ CI GREEN at head `ba95b2af9891e611c15699929361ceed72c8c75f` from 2026-11-03T18:03Z & never merged; the loop then braked this repo 12h for trips ⊥ turning into merges. TWO halves, both in the LOOP, ⊥ in this tree. (a) coderabbit APPROVED that head 2026-11-03T20:37:03Z & posted a COMMENTED review on the same commit 4s later; every cycle the loop logged "coderabbit's approval of <head> never came (30m)" ∴ it reads the LATEST bot review's state, ⊥ whether ANY approval covers the head. inferred from the GitHub reviews API, ⊥ from loop code. (b) ∴ it fell back to an accord-review trip, which found discord & committed — logged "agent produced 1 new commit(s)" at 04:14 & again at 06:14 — yet the branch head is still the same head: the accord commit is ⊥ pushed, so the next cycle reviews the SAME head, finds the SAME discord & pays again ($1.09 list for the 04:14 trip). the 06:14 commit `6c2f37d` is real: ⊥ test exercised `without_tasks` matching the section letter (reverting to `contains("§T")` stayed green) & `CHANGELOG.md` lacked the smaller `lens`/`budget` output|⊥ fixable here. the loop ! count any bot APPROVED on the current head as approval, & ! push an accord commit (or route it to the fix path) instead of dropping it. #165 lands when `6c2f37d`s test + changelog reach its branch. GENERALLY: a review step whose output is never published repeats forever at full cost
B40|2026-11-10|`cargo release hook` @ the 0.6.0 tail → `error: no such command: release`. `5093642` (2026-11-07, `hallucinogen`, "nix flake update (pin refresh) + drop update-pins cron") DELETED `pkgs.cargo-release` from the dev shell — a 5-line removal its message ⊥ names. MEASURED why it went: nixpkgs-lock `e2466bb` (nixos-26.05 `c56a87d8`) ships cargo-release 1.1.7, which needs rustc 1.97, & rustc 1.95.0 ∴ the channel's own package fails to build; `3bb0017` had 1.1.6 & built. ⊥ caught: no gate step runs a tool the RELEASE alone needs, so a shell w/o it stays green until a release|`nix-cargo-release` input (held 1.1.6, cachix, follows our `nixpkgs-lock`) + its overlay ∴ `pkgs.cargo-release` in the shell again, `cargo release --version` = 1.1.6. drop the input when the channel's cargo-release builds (`nix-cargo-release/T2`)