# SPEC
## §G GOAL
Arg dispatch and exit codes. `main.rs` is a shim over `run`.
## §N NAV
rel|path|lens
up|.|-
up|src|code nodes — tokens, spec, fed, lens facades & logic
self|src/cli|arg dispatch, usage, exit codes
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/code|-
sib|src/debt|-
sib|src/assay|-
sib|src/git|-
## §C CONSTRAINTS
- dispatch only. logic lives in the node that owns it (`src/cli:V14`).
- exit codes are a CONTRACT — scripts read them.
## §V INVARIANTS
V1: exit 0 clean · 1 violation · 2 usage. ∀ verb obeys it
V2: a MISS is exit 2 naming what was tried, ⊥ exit 0 empty (`.:V20`)
V3: usage names commands that EXIST. inventing a verb in help or a message gives one operation two names (`.:plan` B3)
V4: `-v`/`--verbose` is a MODE, positional-agnostic ⊥ an argument
V5: repo root = the dir holding `.git` AND `SPEC.md`, ⊥ CWD. `sherd` is a shim over `cargo run` ∴ CWD is wherever it was typed
V6: a test reaches only the repo it was HANDED. V5 walks up ∴ a test naming no fixture finds whatever tree the runner sits in, & the crate root IS one — green about its LOCATION, ⊥ the code (B1)
V7: usage names EVERY verb that dispatches, ⊥ merely only verbs that exist (V3's converse, B2). a reachable verb missing from usage is undiscoverable @ the one place a user looks
V12: ABSENCE is ⊥ a finding. a check over an OPTIONAL artefact reports "none required" & counts 0 when it is missing, & fails only when it exists & cannot be read. B3 is the 2 halves conflated: a fresh `init` tree failed `validate` ∵ it had no slice registry to drift from
V14: the binary is a SHIM — `main` holds nothing & dispatch carries no logic; every verb calls the node that owns the work. cited from 4 files as a root `V41` that was never written (`src/spec:B2`)
V13: a GENERATOR is tested by running it TWICE. once proves it writes; the 2nd run is what proves it wrote the SAME thing, & `sync`·`slice`·`sherd-dev readme` are all gates whose `--check` half is meaningless if the fix half is ⊥ a fixed point (B4)
V15: a path from ARGV is ⊥ a location til resolved ABSOLUTE against the CWD, ONCE, before any walk | join reads it. `parent()` climbs a relative path to `""` ∴ an upward walk from one runs out of parents & returns its own START — the ARGUMENT — as the answer, & the caller then joins that argument on a 2nd time (`code/code`, B9). V5 says WHERE the root is; this says what the INPUT ! be. B5·B7·B9 are 1 family & each fix named a different half of the input — WHICH repo · WHICH position · WHICH FORM
V16: `--version`/`-V` answer on STDOUT w/ exit 0 & name the version `Cargo.toml` declares, ⊥ a 2nd spelling of it. a binary that cannot say what it is forces its wrapper to parse the usage banner (B10)
V17: a MISS ! teach the spelling that WORKS. `[dir]` is ROOT-relative (V15) ∴ `seam code` typed in `src/` looks for `<root>/code` & misses w/ `src/code` right there — honest, & a dead end (B9's RESIDUE). the fix is the MESSAGE, ⊥ the resolution: trying the CWD next makes what an argument MEANS depend on where the caller stands, which is B5·B7's ambiguity re-admitted. a name NO node carries gets ⊥ invented suggestion (V2); a name SEVERAL carry is LISTED, ⊥ guessed (`.:V20`)
V18: `mod.rs` is DISPATCH — `USAGE`, `run_args` & the refusals that answer for a verb itself. a verb FAMILY lives in its own file beside it (`check`·`validate`·`measure`·`plumb`·`steps`·`author`·`adopt`·`propose`·`args`·`parse`) & a new verb joins the family it shares a subject with. its TESTS live in the `tests/` tree — `tests/<family>.rs`, `tests/dispatch.rs` for `mod.rs`, `tests/fixtures.rs` for what 2+ families share — each included as `#[cfg(test)] #[path] mod tests;` ∴ still a child module & reaches private fns (`.:V124`). `.:V50` bills per FILE & a worker loads the file it edits ∴ 1 file of 20,521 tok made every verb cost every other verb. split 2026-09-27, ⊥ raised
V19: `budget`·`check`·`validate --format json` are PLUMBING as `src/plan:V25` defines it — 1 object, fixed keys, `version` & `ok`, paths ROOT-relative w/ the root `.`. text stays PORCELAIN, byte-identical to before json. both forms render 1 COLLECTED report ∴ a number ⊥ in one & ⊥ the other; `ok` & the exit code are 1 decision. what was ⊥ measured is NAMED, ⊥ an empty list (`.:V48`). a rule the text ⊥ names is `null`, ⊥ invented
V20: a fixer & its `--check` resolve ONE target set: `[dir]` from ANY argument (B7), the SUBTREE under it, w/ & w/o the flag. a check that examines nodes the fix never touches certifies a tree nobody rewrote (B13)
V21: argv GRAMMAR is clap derive in `parse.rs` — 1 variant of `Cmd` per verb, a flag is a FIELD ∴ position, value set & arity are the type's, ⊥ a scan. `run_args` only ROUTES a parsed `Cli`; hand-parsing argv anywhere else is B14's shape back. a parse failure is clap's usage error = exit 2 (V1) & `--help`/`--version` its exit 0 (V16). `--help` prints `USAGE` verbatim (the README Commands source, V7); each verb's own `--help`, completions & the man page are generated from the same tree. a verb w/ no `[dir]` of its own still takes a trailing `At` dir ∵ `root_for` resolves the root from ANY dir argument (V15, B7). `parse.rs` is the ONE list `sherd-dev` reads for V7 & `.:V115`
## §T TASKS
id|status|task|cites
T3|.|`sherd validate` — compose DAG, id, budget & coverage checks, examined counts|`.:V48`
T4|.|`sherd init` — scaffold a `SPEC.md` w/ `§F` rows from child dirs|`.:V5`
T5|.|`sherd route "<query>"` — resolve a query to a node, exit 3 ambiguous|V2
T6|.|`sherd check` drift spec↔code|`.:V21`
T7|.|`sherd graph --json` — plumbing as `src/plan:V25` defines it|`.:V83`,`src/plan:V25`
T8|.|`sherd review` verb over the last commit|`.:V48`
T14|.|3 test files over the 2,000 ceiling: `tests/check.rs` 3,552 (16 tests — `check`·`validate`·`review` together) · `tests/measure.rs` 2,387 · `tests/args.rs` 2,216. `review` is the separable subject in `check` — its own code file & test file. decide per file SPLIT or RAISE-w/-reason|`.:V50`,V18
## §B BUGS
id|date|cause|fix
B1|2026-08-22|2 tests pass ONLY ∵ the runner sits in this checkout: V5's walk finds THIS repo when handed none. MEASURED proving T71's dep swap — `git archive HEAD` to a non-repo dir, same tree: 280 pass, `repo_root_finds…` & `review_of_a_real_revision…` fail ∴ the suite in the crate TARBALL is red & a nix sandbox build cannot run it, which is why `packages.default` stayed absent|V6. T9 hands both a fixture & asserts the cwd is ⊥ a repo. GENERALLY: a test that DISCOVERS its input is green about WHERE it ran
B2|2026-08-23|`oneshot` DISPATCHES & is absent from usage. V3 binds one direction — usage ! name only verbs that EXIST — & the converse went unwritten ∴ a verb reachable, documented in `.:README` & measured in `.:R30` was invisible to `sherd` w/ no args, the one place a user looks. found by reading the README against the binary while writing `dev`, ⊥ by any check|V7 states the converse & `sherd-dev readme` GENERATES the list from dispatch (`.:V115`) ∴ neither direction can drift again. GENERALLY: a rule written as one implication leaves the other half unguarded, & the unguarded half is where the defect goes
B3|2026-08-23|`validate` counted a MISSING `.sherd-slices` as 1 drift ∴ a repo `sherd init` had just scaffolded FAILED `sherd validate` — the 2 verbs of rung 0.2 & 0.3 contradicting each other on a fresh tree. absence is LEGAL & was read as a finding; the error path counted 1 w/o asking WHICH error|V12. a registry that cannot be READ stays a failure; one that does ⊥ exist reports "none required" & counts 0. GENERALLY: an error branch that counts a failure ! distinguish "could ⊥ look" from "⊥ there"
B4|2026-08-23|`sync` was ⊥ IDEMPOTENT: `upsert_section` spliced strings & appended 1 newline per run ∴ every §N grew by a blank line & `sync` reported "rewritten" forever. a 2nd defect underneath: the anchor (`§F`) precedes the section (`§N`) in a well-formed doc ∴ the insert branch fired BEFORE the replace branch & a 2nd `§N` was appended each run. caught by a test asserting the 2nd run is a no-op, ⊥ by running it once|V13. rebuilt on the SECTION LIST — parse, replace-or-insert, re-render w/ exactly 1 blank line between sections ∴ idempotence holds BY CONSTRUCTION. replace is checked BEFORE insert. GENERALLY: a generator ! be tested by running it TWICE; once proves only that it writes
B5|2026-08-24|a `[dir]` naming ANOTHER repository resolved its root from the CWD ∴ `sherd check /tmp/ashlar` reported THIS crate's 18 nodes & 29 `.rs` files & exited 0 — confidently, about the wrong tree, w/ nothing in the output saying so. `budget` had the same cause & a different symptom: it filters `discover(root)` by the given dir ∴ 0 nodes examined, exit 2, & the message blamed the DIR for naming no node when the truth is nobody looked there. `split` survived ∵ it passes the dir straight through. FOUND by dogfooding a 4th foreign repo (`ashlar`, 24 `.rs`, 1 unfederated `SPEC.md`) — the 4th stranger, the 4th distinct defect, & ⊥ by any test|V5. `root_for(args)` — when the 1st argument names an EXISTING DIRECTORY the root is the one ABOVE IT; a non-dir 1st arg (`HEAD` for `review`, `--check` for `sync`) leaves the CWD walk alone, & an in-repo path resolves to the root it always did. 1 change in dispatch fixes every `[dir]` verb at once ∵ they all read the same `root`. GENERALLY: a tool that accepts a PATH accepts a tree it was ⊥ launched from, & every ambient fact it resolves — root, ceilings, config — is then a guess about the wrong one
B6|2026-08-24|2 verbs read an EMPTY answer as a good one, both found on the 4th foreign repo. `fed` on an unfederated `SPEC.md` printed NOTHING & exited 0 ∴ silence reads as "no problems" rather than "no `§F` table" — `src/fed:B6`'s shape (something that finds nothing passes cleanly) met from the other side. `slice --list` w/ no `.sherd-slices` died w/ a bare `No such file or directory (os error 2)`: no path, no hint that the registry is OPTIONAL, & exit 2 — while `validate` has printed "slice: no registry (none required)" for that SAME condition all along ∴ 2 readings of 1 absence, & `V12` was written for exactly this & applied to only 1 of them|V12,`.:V48`. `fed` states what it examined & points at `split`; `slice_cmd` checks `is_file()` first & reports "none required", exit 0, & a real read error now names the PATH. GENERALLY: every verb ! be run against a repo that has NONE of the thing it looks for — our own tree has all of them, so absence is the case only a stranger tests
B7|2026-08-24|`B5`'s fix was INCOMPLETE & the same stranger showed it 1 command later: `root_for` read `args[1]` only ∴ `sherd plan --triage <dir>` — a FLAG at position 1 — found no dir & answered about the CWD, printing THIS crate's `src/plan`·`src/spec`·`src/tdd` rows for a foreign repo, while plain `plan <dir>` had been correct all along. `sync --check <dir>` & `split --apply <dir>` share the shape. ALSO `debt` conflated an ABSENT `.lint-debt` w/ a MALFORMED one — "no `density`/`shape` rows to read" for a file that does ⊥ exist, `B6` again 1 verb over|V5. scan EVERY argument for the 1st existing directory, ⊥ position 1. GENERALLY: a fix expressed as a POSITION is a fix for the invocations someone thought of — `B5` was found & fixed & re-broken inside 1 session ∵ the 1st form tried put the dir where the code looked. the test now pins 4 orderings, ⊥ 1
B8|2026-08-24|`budget` & `validate` FAILED a stranger against a ceiling nobody wrote. ashlar has no `.context-limits` ∴ every node took `DEFAULT_NODE` 2,000 & the report read `chain 7484 · ceiling 2000 · OVER by 5484`, exit 1, w/ nothing saying the file was ABSENT or the number a default. `Ceilings::load`'s own doc has said "a missing file is a COLD START" since it was written — the loader knew & the CALLER could ⊥ ask. 4th instance of 1 shape today (`B6` `fed`+`slice`, `B7` `debt`, this): every verb resolves its own ambient facts & each decides absence alone|V12. `Ceilings::is_cold()`; over a cold default is REPORTED (`.:V48`) & ⊥ counted against the verdict. an unlisted PATH inside an EXISTING file still takes the default — `.:V6` requires it, or a row silently skipped gates nothing — & the test pins cold vs warm vs unlisted-in-warm. GENERALLY: a DEFAULT is a suggestion until someone writes the file it lives in, & a gate that cannot tell "unset" from "set to this" fails people for rules they never adopted
B9|2026-09-19|`root_for` scanned argv for the 1st `p.is_dir()` & handed THAT PATH — possibly relative — to `repo_root_from`, whose walk climbs by `parent()` to `""`, which holds no `.git` ∴ the walk returned its own START & the ARGUMENT became the root; `arg_dir` then joined the argument on again. MEASURED: `seam src` @ root exit 2 `src matched no node` · `seam code` @ `src/` exit 2 `code/code matched no node` · `seam ./code` → `./code/./code` — the DOUBLING is the proof. `./x` resolved only from the repo ROOT ∴ "use `./`" was ⊥ a workaround, just the 1 cwd where both readings agree. ∀ `[dir]` verb: budget·seam·lens·check·fed. 3rd of `B5`/`B7`'s family & ⊥ caught by either, ∵ both were tested w/ ABSOLUTE fixture paths only. NOTE this is `src/cli:B9`, ⊥ `.:B9`|V15. resolve the candidate against the CWD before the walk; `root_for_from(args,cwd)` takes the dir a cmd was typed in ∴ a test is HANDED it (V6) ⊥ mutating the process CWD. LEXICAL `join` ⊥ `canonicalize`: canonicalize rewrites symlinks (macOS `/var/folders` → `/private/var`) ∴ the root would stop comparing equal to the path it was given & 2 existing tests would need weakening. RESIDUE: `arg_dir` is ROOT-relative BY DESIGN & pinned by a test ∴ `seam code` @ `src/` now names an honest absolute path & still exits 2 — the root-relative `seam src/code` is the spelling that works
B10|2026-09-20|`sherd --version` & `-V` fell through to `Some(other)` ∴ both printed the USAGE banner on STDERR & exited 2 — the code V1 reserves for a MALFORMED invocation — so there was no way to ask the binary what it is, & asking a tool its version is ⊥ a usage error. MEASURED on the flake build: `sherd --version; echo exit=$?` → banner, `exit=2`, same for `-V`. every sibling in the toolchain answers (`microlith 0.7.0`, `itok 0.3.1`, `hk 1.58.1`) ∴ a CI gate recording the version of every tool it ran could record all of them BUT ours, & a wrapper's only recourse was parsing the banner or shelling out to the package manager|V16. a dispatch arm beside `--help`'s printing `sherd {VERSION}`, `VERSION` being `env!("CARGO_PKG_VERSION")` ∴ it cannot drift from the manifest, & the test reads the manifest rather than restating the number. `dev`'s verb check excludes it as it already excludes `--help`: a FLAG answering ABOUT the binary is ⊥ a verb & belongs in no Commands table. GENERALLY: the fall-through arm decides what an UNRECOGNISED argument means, & the conventions the world already has for one — `--version`, `--help` — are exactly the cases it gets wrong by default
B11|2026-09-30|`adopt` & `sync` answered an INPUT error w/ their VERDICT code. MEASURED on 0.5.2: `adopt <dir> --map <missing>` 1, a map line that is ⊥ `<id> <node>` 1, `adopt` on a dir w/ no `SPEC.md` 1, `sync` on a node whose `SPEC.md` cannot be read 1. §I defines `adopt` 1 as "a migration PENDING or WRITTEN" & `sync` 1 as "it wrote" ∴ a wrapper re-running on 1 re-ran a verb that had read nothing. `coverage` & `debt` already answer a reading they could ⊥ take w/ 2|V1. could ⊥ read its input → 2: `adopt_unusable` for no source & a missing or malformed map; `sync_cmd` for any node it cannot read or write. a map `adopt` READ & refuses stays 1 — a verdict about this tree
B12|2026-10-03|`plan_cmd` loaded the state store, cleared every `plan` key, wrote 1 `plan/<rank>` per step & SAVED, on both the text & `--format json` paths, though `src/plan:V7` says `plan` is stateless. NOTHING read those keys: `apply` re-derives the plan, & the only other use of the kind was `apply` clearing it. so a read-only verb rewrote `<git-common-dir>/sherd-state`, shared by every worktree (`src/state:V4`), & the suite's `plan` tests wrote into the checkout that ran them (#79)|`plan_with` takes the store it may READ & writes nothing; `plan_cmd` loads it & hands it over. pinned by a test that runs both forms over a temp store & compares its bytes. `apply`'s `clear_kind("plan")` stays til the model half thaws (`.:V117`): it clears nothing now
B13|2026-10-25|`sync [dir]` & `sync --check [dir]` examined DIFFERENT nodes (#154): the fixer stopped at `[dir]` while its check walked every node, & dispatch read the dir from `args[1]` alone ∴ `--check` at position 1 hid it. MEASURED w/ `args[1]` restored: `sync --check <a>` exits 1 on a stale sibling `b` nobody named. `B7`'s shape, 1 verb it missed|V20. `[dir]` from ANY argument; `fed::discover(dir)` w/ & w/o `--check`; a dir w/ no node is still handed over ∴ an unreadable `SPEC.md` is exit 2 (B11). pinned through `sync_cmd` (subtree, stale sibling left alone) & through `run_args` (both flag orders)
B14|2026-10-29|argv was HAND-PARSED in `run_args`: each verb scanned `args` for its own flags & dir, so position, value set & arity lived in scattered scans ∴ B7 (flag at position 1), B9 (relative dir) & B13 (dir read from `args[1]` alone) were 1 shape recurring per verb|V21: grammar is clap derive in `parse.rs`, `run_args` only routes a parsed `Cli`
B15|2026-11-01|`absolutize_dir` made every `[dir]` that exists under the CWD absolute ∴ `seam code` @ `src/` answered from `src/code`, exit 0, where V17 & B9's RESIDUE require a miss that teaches: what an argument MEANS came to depend on where the caller stood. all `[dir]` verbs (seam·lens·budget·fed·wave·sync). MEASURED against 0.5.4. green ∵ nothing called it|V17. absolutize only when the dir named ANOTHER repository, the case it exists for; the `here` is HANDED (V6) & a spawned-binary test pins both halves
B16|2026-11-01|`review` was the 1 verb w/ no `[dir]` left w/o an `At` ∴ `review <rev> <dir>` exit 2, measured working on 0.5.4, while V21 says every such verb takes one. `Cli`'s rustdoc was also published as the man page's NAME: clap derive reads a doc comment as `about`, & the test asserted only `.TH sherd`|V21. `At` on `Review`; `about` spelled & pinned to `USAGE`'s headline
B17|2026-11-02|`absolutize_dir` compared roots as SPELLINGS: a `[dir]` climbing back to its own root walks to `src/..` ≠ `repo`, read as ANOTHER repository ∴ `lens ../src/code` @ `src/` & `budget ..` answered CWD-relative, exit 0, where 0.5.4 missed. B15's shape through 1 path form. MEASURED against 0.5.4|V17. `same_dir` compares canonical paths & neither travels on (B9); a spawned-binary test pins it