# itok — context-cost estimator
Self-contained spec. `itok` is developed inside a larger workspace but designed to leave it as a standalone crate (`git subtree split`). It carries its own law and stands on its own reasoning — no load-bearing reference outside this directory (V26).
## §G GOAL
Estimate the token / context-window cost of files & changes, from the command line, with `git`- and `du`-shaped grammar so a human or an agent who knows those tools needs no teaching.
## §C CONSTRAINTS
- Rust. One bin: `itok`. MIT licensed.
- Offline & deterministic by default; runs fully in a NETWORKLESS SANDBOX (V34). Network only behind the opt-in `--ollama` tier (LAN, keyless), ⊥ in core, ⊥ any paid/authed cloud API (V35).
- ASCII-only source (Trojan-Source, LLM-friendliness).
- Zero deps on any host-project internals ⇒ extraction is a move.
- `SPEC.md`'s FORMAT is owned by `mth`, a sibling crate, ⊥ by §V: a dev-time tool on the `rustfmt`/`clippy` rung (V14/V31). Dev shell provides it; the gate fails hard without it.
- Estimation, ⊥ measurement: no public Claude tokenizer exists ∴ the default is a labelled proxy, never a claim of truth.
- Runtime axis (V41) reads the HARNESS's own on-disk transcript, READ-ONLY. ⊥ store content, ⊥ egress, ⊥ touch credentials (V43/V45).
- Enforcement is opt-in & ADAPTER-shaped: no daemon, no server, no in-flight interception, ⊥ in the request path (V52/V53/V58).
- WORKING principles (V80-V87) bind how the work is done, ⊥ only what is built. Lineage: `pr0d1r2/set-and-setting` `set/skills/principles` (Dalio's Principles + DRY/KISS/SOLID/POLA) — a SEE-ALSO, ⊥ load-bearing: each invariant below stands on its OWN reasoning & its own evidence FROM THIS REPO (V26's rule, applied to an external source). Already-encoded ones are ⊥ restated: truth=V3/V44/V47/V48/V61 · reality=V68/V38 · rootcause & progress=the §B→§V loop · machine=V71/V64/V42 · transparency=§V itself · POLA=V1/V2/V46/V49 · KISS=V20/V21/V24/V25/V35/V58 · DRY=V64/V40/V33/V66 · SOLID=the clippy caps + V33/V43/V52.
## §I INTERFACE
- `itok estimate <path>` — `-s` summarize · `-h` human · `--top N` · `--budget N` · `--bpe` · `--format json` · `-C <dir>`.
- `itok diff [<ref>|<A> <B>|<A>..<B>] [-- <path>]` — `--staged` · `--budget N` · `--exit-code` · `--bpe`.
- `itok show [<commit>] [-- <path>]` | `itok show <commit>:<path>` — one commit's per-file token delta (default HEAD); `<commit>:<path>` = a blob's cost at a ref. Report-only · `--bpe` · `--format json`.
- `itok check` — `--format human|json` · `-C <dir>`. Reads `.context-limits`, pinned `--bpe`, pass/fail.
- `itok doctor <path> | --session [<id>]` — `--model X[,Y...]` (a comma-list narrows to those models, each resolved by V6; ONE unresolvable element FAILS the call, naming it) · `--window N` · `--format json` · `-C <dir>`. Advisory: fit-to-window · balance · noise · estimate confidence. `--session [<id>]` (+ `-h`) retargets it at a CONTEXT: progression (use% · rate · `~turns left`) + per-item `projected`, every figure BORROWED from `headroom` & `top` (V99). V97's two levers: PLANNED, ⊥ BUILT (T77) — B31's marker, applied to the half still owed. A SECOND positional = usage error ∵ this form has no fileset (V2). Reports & suggests; never gates.
- `itok log <path>` — `-n N` · `<A>..<B>` · `--reverse` · `--since` · `--bpe` · `--format json`. Per-commit cost + delta; report-only.
- `itok fit --window N [paths]` — `--by size` · `--bpe` · `--format json`. Greedy subset that fits the budget; emits a pipeable path list.
- `--ollama[=HOSTS]` (estimate/doctor) — exact counts via the server's tokenizer + live model→window. Each host `[scheme://]host[:port]` (default `11434`); a comma-list, `-` (stdin), or `.context-hosts`; a BARE host needs the `=` form (V101); honors `OLLAMA_HOST`. Fleet = union of models. Network, the SLOWEST-REMOTE rung (V4); never on `check`/`log`. No CIDR (V24), no `--ollama-port` (V25).
- `itok trace [<session>]` — `-n N` · `--since D` · `--reverse` · `--format json`. Runtime LOAD EVENTS, 1 line each, chronological. Report-only.
- `itok top [<session>] [-- <path>]` — `-h` · `-s` · `--top N` · `--cost` · `--model X` · `--format json` · `-C <dir>`. `--cost` prices the session's EXACT usage split by `.context-models`' `in/cr/cc` column, in the unit that file declares; `--model` is required for it & each absence names itself (V61). Ranked context OCCUPANCY + dup · stale · cache columns. `-- <path>` = that path's loads (per-path attribution; ⊥ a separate `blame` verb, V46). Report-only.
- `itok headroom [<session>]` — `--model X` · `--window N` · `--task N` · `-h` · `--format json`. `--task N` adds a `tasks left` column (`avail`/N, tilde'd, naming the declared cost); `>= 1` is the can-I-finish question & the VERDICT stays `doctor --session`, which T76 BUILT. `df` for a context: window · used · avail · use% · the rate triple · turns left. Report-only (V91).
- `itok calibrate [<session>]` — `-h` · `--format json` · `-C <dir>`. The context FIT: fixed overhead + scale (`bytes/4`→actual) + the HELD-OUT band + `n`. Too few turns ⇒ `n` & NO factor. Report-only (V102).
- `itok cap [N]` — stdin→stdout token filter. `--footer human|json` · the reduction ladder `--strip` · `--dedup` · `--elide` · `--outline` (V50), each OPT-IN & applied in LADDER order whatever order the flags arrive in, stopping at the first rung that meets the budget; every rung that ran is NAMED in the footer. Announces its elision; resumable (V49/V51) — but a published selector ALWAYS ADVANCES: a rung above `cap` REWRITES the text & a budget nothing fits keeps NOTHING, & in both cases the selector is ABSENT w/ the reason named (B37). `input` counts the CALLER's bytes ⊥ the reduced ones.
- `itok guard` — hook ADAPTER: harness hook JSON on stdin → decision JSON on stdout; reads `.context-policy`. The runtime gate (V52/V53). Signals in JSON, ⊥ via exit code — the harness reads stdout.
- `itok rate [<session>]` — `--statusline` · `--color auto|always|never` · `--format human|json` · `-C <dir>`. Pre-formatted throughput string for a statusline badge: `last_turn,bill/bill,growth/h,growth/d`. Cells 3-4 divide GROWTH (Σ positive window deltas), ⊥ the gross bill (V117). Each value SHORTENED by ceiling (V108). `/h` & `/d` wear `~` when the session age does ⊥ cover the period they name (V110). Rates divide by ACTIVE time — each inter-turn gap capped at 300s — ⊥ by the wall-clock span (V111). `--color` reads `[rate]` thresholds from `itok.toml` (V109); per-metric ANSI: green · amber · red, independently per value; a metric with NO threshold gets NO color opinion (V109). `--statusline` reads the harness statusline payload on STDIN & takes `transcript_path` + `cwd` from it, emitting the wrapped badge `(itok:…)`; color defaults to `always` there ∵ the harness captures the string ∴ `auto` would see no tty. Cell 1 is a LEVEL ⊥ a flow ∴ `--color` renders it as a FILL GAUGE against the MEASURED compaction point (V116), else the window capacity, & only then `[rate].turn` (V114); truecolor ramp where `COLORTERM` allows it, V109's 3 buckets otherwise; no capacity | a zero window ⇒ NO color (V115). `--statusline` also reads `model.id` from the payload ∴ the capacity is the SESSION's, ⊥ a flag's. A 5th cell appears only when the gauge does: `~` + time to the red line at the recent growth rate, FLOORED (V119); json `compact_in_active_seconds`. 0–1 turns = empty HUMAN output (badge hidden) ⊥ empty JSON: `--format json` still returns ONE object w/ `null` where nothing was measured (V9/V47). Report-only (V5).
- `<session>` (`trace` · `top` · `headroom` · `calibrate` · `rate`) = a harness ID | a transcript PATH — path when one EXISTS, else the id resolved as `<id>.jsonl` under the project dir. A NAMED session that resolves to neither is a USAGE error naming both forms tried & the dir searched (V104); an INFERRED absence stays silent.
- Config: `.context-limits` (per-path ceiling), `.context-models` (model → encoding + window + optional `in/cr/cc` RATE column, three integers per 1M tokens, read by `--cost`), `.context-policy` (per-glob/per-tool budget · pins · fuse tiers), `itok.toml` (unified config, V109 — `[rate]` thresholds + `compact`, the observed compaction point overridden by hand as ONE number for every model | a `[rate.compact]` table keyed by `model.id` (V116/V121); future sections migrate the dotfiles above).
- Exit: 0 ok · 1 breach/delta · 2 usage · 7 network (`--ollama`).
## §V INVARIANTS
V1: **convention over novelty.** Default to the form `git`/`du`/`rg` already use, even when a novel one is "better". Convention lives in the model's pretrained prior & in muscle memory ∴ costs 0 to invoke. Novelty is taxed on 4 recurring axes — teaching (paid every session), retry (wrong-guess round-trips), surprisal (low-probability form ⇒ the model hedges), parsing (novel output re-inferred). Ship novelty only when value-added > cost-to-teach.
V2: **near-collision is the expensive failure** ∴ match a convention's SEMANTICS exactly | be visibly different — never almost. A `diff` that looks like `git diff` but acts differently invokes the prior then violates it ⇒ costs more than honest novelty.
V3: **name = estimation; the number self-describes.** Output ALWAYS names its unit & method: `~166k itok (bytes/4)`. `itok` = INPUT tokens (what a file costs fed INTO a model, ⊥ output/generation) ∴ an agent needs no external knowledge — the number says what it is (V15); `i`/`o` is the most burned-in split in computing (V1). The `~` marks a CRUDE estimate — dummy tier ONLY; `--bpe`/`--ollama` drop it (`166k itok (o200k)`, `166k itok (exact)`) ∵ they are a real tokenizer's true count. Tilde presence = the estimate-vs-truth signal at a glance. (`--exact` was the old flag name for the true rung; it is now `--ollama`, V35.) json (T3) carries the same intent structurally (`unit`, `estimated`), ⊥ w/ a tilde in a numeric field (V9).
V4: **precision ladder, ordered FASTEST-LOCAL → SLOWEST-REMOTE.** `dummy` (bytes/4 + word proxy, zero-dep, instant) | `--bpe` (tiktoken, offline, deterministic, the honest proxy) | `--ollama` (a local model's OWN tokenizer, LAN localhost, keyless, exact for that model — V22). Each rung labelled; `dummy` & `--bpe` are honestly "estimation", `--ollama` transcends it. The local rungs (`dummy`, `--bpe`) are the CORE & the only tiers a networkless sandbox needs (V34); `--ollama` is the opt-in remote rung. NO cloud/paid-API rung — a provider `count_tokens` behind an API key is rejected (V35).
V5: **only `check` gates.** It pins `--bpe` ∴ deterministic & cacheable by content hash. `estimate` & `diff` are report-only, exit 0. A gate that varies per run is ⊥ a gate.
V6: **prefix-inference, read-only verbs only.** Unambiguous prefix ⇒ resolve silently (`itok e`, `itok di`, `itok ch`). Ambiguous ⇒ error listing candidates, never silent-pick. Non-prefix typo ⇒ SUGGEST (edit-distance), ⊥ run. Canonical names are the full words; prefixes are convenience, never promised. Any future MUTATING verb requires its full name — no inference into a write. SAME rule binds a name resolved from a DISCOVERED SET: `--model` over an `--ollama` fleet resolves exact > ollama's own `name`=`name:latest` > unique prefix; ambiguous ⇒ error LISTING candidates, absent ⇒ error listing what IS served (V71). Step 2 keeps ollama's grammar EXACTLY where it applies ∵ an almost-match is V2's expensive failure. One prefix grammar, ⊥ a per-domain reinvention (V1). ⊥ `.context-models`: that is a REVIEWED registry & V11 wants an exact row. Write-safety above is untouched ∵ `doctor` is read-only.
V7: **`diff` mirrors `git diff` arg-forms verbatim** — working-tree, `--staged`, `<A> <B>`, `<ref>`, `-- <path>`, `--exit-code`. Zero new mental model (V1).
V8: **`estimate` mirrors `du`** — `-s`/`-h`/`--top` — & operates on git-tracked files by default (like `rg` respects `.gitignore`); explicit paths reach untracked files directly. `du`'s `-d` (recursion depth) & `-a`/ `--all` are ⊥ shipped: `estimate` costs a FLAT fileset (git-tracked list | argv), ⊥ a recursive walk, so depth has nothing to recurse & untracked is a named path away. Add either only when a real need appears.
V9: **porcelain/plumbing split.** Human table MAY evolve; `--format json` (one object per file) is a STABLE contract. Agents parse json; the pretty table stays cosmetic.
V10: **`.context-limits` is opt-in**, ⊥ fail-by-default. Unlike a repo-guard registry, `itok` runs on arbitrary repos ∴ an unregistered path is simply unchecked. `check` gates only what the user registered.
V11: **`.context-models`: unknown model ⇒ FAIL, name an encoding.** No silent fallback to a default BPE — a silent wrong-tokenizer is the V2 failure. A new model is a reviewed row.
V12: **BPE vocab VENDORED**, with license provenance, ⊥ fetched at runtime. Offline-first + opensource both demand the data ship in-tree.
V13: **zero host-internal deps** ∴ extraction = `git subtree split -P crates/itok`, ⊥ surgery. Own `Cargo.toml`, own license, own `SPEC.md`, own vocab. Nothing imported from the monorepo.
V14: **self-checked & dogfooded, & the FORMAT is checked by its OWNER.** `itok check` gates `.context-limits` w/ the binary being built; `mth fmt --check` + `mth check --records .spec-records` gate THIS file's form & structure. itok wears both hats — product & guardrail. The format rules are ⊥ restated in §V: they are TOOLING, the rung `rustfmt`/`clippy` sit on, & a spec that restates its formatter's rules owns a SECOND copy of them (T92's whole point). ONE exception is itok's & stays here: `.spec-records`, the CLOSED-option baseline (V83), ∵ survival across edits is ⊥ derivable from one text ∴ the checker owns the RULE & this repo owns the LIST. The step fails HARD when the binary is absent — V74 degrades a runner whose absence leaves another guard standing, & after T92 nothing else reads this file's structure ∴ a skip would read exactly like a pass (V69, the defect B12 already cost a day).
V15: **`itok` dogfoods its own metric** — it measures token cost ∴ it must be the cheapest tool to learn (V1). A token tool that needed teaching would refute its own thesis.
V16: **budget IS the switch** — `--budget N` on `estimate`/`diff` ⇒ exit nonzero when a file (or a change's delta) exceeds N. A threshold intends a gate ∴ no separate `--guard` boolean. Name = `budget`: ⊥ `--guard` (novel jargon, V1), ⊥ `--max-tokens` (near-collides w/ the API `max_tokens` = GENERATION cap, opposite meaning ∴ V2's expensive failure). Complements `check`: `--budget` is the inline one-shot (no registry, the CI one-liner), `check` is committed policy (`.context-limits`). Both gate; both pin `--bpe` when accuracy matters. `--budget` on `diff` needs no registry ∴ "no commit adds > N tokens" is a review gate anyone can drop into CI.
V17: **`doctor` = advisory pre-flight** — "is this context healthy to hand a model?" Answers *should I?* where `estimate` answers *how much?* & `check` answers *passes policy?*. Report-only, suggests fixes; ⊥ a gate. Name = `doctor` ∵ convention (`brew`/`flutter`/`npm doctor`) is in the prior (V1); ⊥ `sane` (novel, collides w/ the SANE scanner API, reads wrong as a verb). Composes itok-NATIVE signals ONLY: fit-to-window, budget balance (one file dominating), noise ratio (generated/binary/lock share), estimate confidence (dummy-vs-bpe spread — the one signal only itok has, ∵ it owns the estimators). BOUNDARY: dup-detection & vocab/TTR are separate tools — `doctor` stays a thin composer, ⊥ grows tentacles.
V18: **window override** — `--window N` gives context capacity raw; `--model X` resolves it from `.context-models` (extended to model → encoding + window). Explicit `--window` wins over `--model`. Unit = DECIMAL tokens (`1M` = 1_000_000, `200k` = 200_000), one parser shared w/ `--budget` (one unit grammar, less to hold). Name `--window` ⊥ `--size` ∵ "size" primes BYTES (its meaning in `du`/`ls`) but a window is TOKENS ⇒ V2 near-collision. `--size` MAY be a silent alias for muscle memory, ⊥ the documented name.
V19: **`log` = cost across history** — the 5th question (*how did it evolve?*), the creep curve `diff`'s 2 points ! show. Mirrors `git log <path>` verbatim (V1): 1 line/commit that touched the path — sha·date·subject + absolute tokens + delta (like `--stat`'s +/-); `-n N` · `<A>..<B>` · `--reverse` · `--since`. Report-only, exit 0 — raw data like `git log`; judgment (flag N rises) stays OUT (scope). Defaults to `dummy` ∵ whole history = N blobs & `git cat-file -s` gives blob bytes directly (near-free); `--bpe` opt-in for accurate absolutes at N tokenizations. Per-blob-hash cache ∴ a blob is never re-estimated.
V20: **`fit` = greedy pack, ⊥ knapsack** — select the subset of candidates that fills a `--window` budget. Knapsack (NP-hard) only bites when items approach capacity; context files are KB against a 1M-token window ∴ each is a tiny fraction & greedy-by-order ≈ optimal (fractional ≈ integral when item ≪ capacity). Order candidates (argv/manifest order default; `--by size` to fit-most), take while running total ≤ window, emit survivors. Reuses `--window` parser (V18), estimate tiers (V4, dummy default), tracked-default (V8). Output = a pipeable PATH LIST (NUL/newline, `git ls-files`/`rg -l` shape) ∴ `itok fit --window 200k src/ | xargs cat` assembles a context bundle under budget — useful w/o any programmatic assembler. Report-only, exit 0. Name = `fit` (the question *what fits?*) ⊥ `pack` (implies the bin-packing optimization we ⊥ do). It SELECTS ⊥ reports ∴ its own category beside the 5 report verbs.
V21: **optimal fit DEFERRED (⊥ rejected)** — true 0/1 knapsack (max priority under budget for near-capacity large items) & per-file priority tables. Greedy (V20) covers the KB-files-vs-1M-window case; the solver earns its complexity only when large near-capacity items make greedy visibly wrong. Trigger: a real fileset where greedy drops a better-fitting combination.
V22: **`--ollama [HOST]` = self-hosted exact + live windows** — THE slowest-remote rung (V4), keyless & free: `localhost:11434` default, no API key & no payment; TLS AVAILABLE & often WANTED (V23) ∵ content leaves the process. Ladder = dummy|bpe|`--ollama`; NO cloud rung (V35). Gives 2: (1) EXACT counts via the model's OWN tokenizer (`prompt_eval_count` from a `num_predict:0` generate) ∴ a local llama/qwen is measured true, ⊥ by an o200k proxy that is wrong for it; (2) live model→window from `/api/tags`+`/api/show` (`context_length`). `doctor --ollama` w/o `--model` enumerates ALL local models & reports fit-% against each — the answer no static table gives. Honors `OLLAMA_HOST` (V1); bare `--ollama` = `OLLAMA_HOST`|`localhost:11434`, `--ollama HOST` overrides. Applies to `estimate` & `doctor` ONLY — the verbs where an exact count earns its network cost. `diff` (a gate) & `fit` (a packer) stay on margin'd `--bpe`: a gate wants a CONSERVATIVE estimate, ⊥ a true count (V36) — exact there DEFERRED, ⊥ rejected (trigger: a real need for exact deltas/packing). NEVER `check` (V5) | `log` (history×network). Precedence: live endpoint > `.context-models` > error; the table is the offline fallback & the only source for cloud windows. Non-deterministic + network ∴ all remote-tier rules (V4/V23). Content LEAVES the process to the endpoint — LAN self-hosted is the private path vs cloud, a conscious tradeoff.
V23: **network tier feature-gated; the client is BLOCKING & carries TLS.** `--ollama` lives behind a cargo feature (`ollama`) w/ a tiny blocking client (`ureq` 3 + `rustls`, ⊥ an async runtime) ∴ the core ships ZERO network deps, stays small for extraction (V13), & runs in a networkless sandbox (V34). Offline-first is the default BUILD, ⊥ merely the default flag. NO cloud client ships at all (V35). TLS is PRESENT, ⊥ omitted: the exact tier POSTs the FILE'S TEXT to `/api/generate` (V22) ∴ cleartext is a CONFIDENTIALITY exposure, ⊥ a footprint saving — the omission was a missing MITIGATION dressed as hardening, & was published as one (B16). `http://` stays the DEFAULT & stays supported: a LAN box you own ⊥ want a cert. MEASURED, & the intuition runs BACKWARDS — gaining tls SHRANK the tier: ureq 2→3 took it from 60 to 44 runtime packages & 19 `Unicode-3.0` licences to 0, ∵ ureq 2 pulled `url`→`idna`→the ICU stack.
V24: **`--ollama` takes explicit HOSTS, ⊥ a CIDR — no in-tool scanning.** A subnet probe is a PORT SCAN: hostile/noisy/IDS-flagging on any network you ⊥ fully own, sometimes a policy/legal problem — a headline liability for an opensource token tool that buys nothing. Scope-alien too (service discovery ≠ token measurement) & slow+non-deterministic (breaks snappiness). V1: the convention for "find services" is advertise (mDNS) | explicit list, ⊥ scan. So `--ollama` accepts a host, a comma-list, `-` (stdin), or `.context-hosts`; a fleet is the UNION of models & windows across named hosts (`doctor --ollama box1,box2` = which model anywhere holds this). Discovery, if truly wanted, is COMPOSED — `nmap -p11434 …
| … | itok doctor --ollama - .` — a dedicated scanner pipes hosts in; itok never ships a scanner. Considered & rejected, escape hatch recorded.
V25: **port lives in the host (`host[:port]`), ⊥ a `--ollama-port` flag.** `OLLAMA_HOST=1.2.3.4:6666` is Ollama's own form ∴ `host:port` is already in the prior (V1) & universal (ssh/redis/pg/git-remote). A separate `--ollama-port` can't express per-host ports in a fleet list (`box1:11434,box2:6666`) & works in none of stdin/`.context-hosts`. Default port `11434`; a `scheme://` prefix carries TLS for a proxied server — same slot, no new flag. Considered & rejected.
V26: **provenance is a DEV-TIME note, kept OUT of the shipped spec.** A reference to the origin repo's invariants is see-also / derived-from, NEVER load-bearing — each itok invariant stands on its own reasoning. ∴ the SHIPPED, public `SPEC.md` names NO origin-repo invariant number: a cross-repo pointer targets a PRIVATE repo the reader can't see & leaks its numbering, a bare `Vxxx` collides w/ itok's own namespace & reads broken. The reasoning a pointer once cited is folded INLINE & self-contained. The scrub lives IN the monorepo (this file is kept public-clean in place) ∴ extraction stays a pure MOVE (V13), ⊥ surgery. Lineage lives in git history & commit trail, ⊥ the shipped text.
V27: **itok self-guards — its guard config TRAVELS.** The fractal: every extractable unit is a mini-repo. crates/itok/ mirrors a repo root — own `SPEC.md`, `lexicon.txt`, `coverage-baseline.json`, `Cargo.toml`, `rustfmt.toml`, `clippy.toml`, `.gitignore`, + the toolchain & gate it runs on (root `flake.nix`/`flake.lock`/`.envrc` + `.github/workflows/ci.yml`, V62). ∴ `subtree split` carries the GUARDS w/ the code; itok guards itself standalone, ⊥ orphaned. Config that CHANGES a verdict (`rustfmt.toml`'s `max_width`, `clippy.toml`'s thresholds) ! travel beside `Cargo.toml`'s `[lints]`, else the standard gate (V31) silently weakens on extraction — the extracted `cargo fmt --check` reformats to defaults & fails (B1). Reconciles V13 (self-contained) & V14 (dogfooded): in-repo the host RUNS the guards, but the config they read is itok's own.
V28: **⊥ ship a declaration no RUNNER reads.** GENERALISED from its origin: a host-specific unit declaration (`.uow/unit.yml` — ops × globs × phases × deps) described work for a HOST RUNNER, & no such runner exists in the extracted repo ∴ shipping it there was a DEAD FILE that reads as law: a contributor sees a gate declaration, edits it, & nothing runs it (worse, it can DRIFT from the live gate & carry a stale threshold — exactly B4's shape, a `99` floor surviving beside CI's corrected 98). ∴ the public repo carries only what plain tools read: root `flake.nix`/ `flake.lock`/`.envrc` (V62) & `.github/workflows/ci.yml` (V31). The baselines (`lexicon.txt`, `coverage-baseline.json`, `SPEC.md`, `Cargo.toml`) sit at the crate ROOT — where tools expect them & where they land as root after extraction. Root = what-to-guard-against; the how-to-guard is the WORKFLOW here & the unit declaration THERE. Same ops either way (V31) — one verdict, two runners. THE MONOREPO IS GONE (standalone since 2026-07-25) & `.uow/` w/ it ∴ this rule now reads FORWARD, ⊥ back: it is why `hk.pkl` · `flake.nix` · `scripts/` · `.coverage` are `exclude`d from the `.crate` (V39), & why `tests/ci.rs` joined them — a test whose SUBJECT is the dev gate is the same dead-law shape, & it shipped broken until the `package` step measured the tarball.
V29: **the phase split is the HOST RUNNER's, ⊥ the repo's** — fmt · clippy · nextest(lib) on pre-commit; nextest(e2e) · `llvm-cov --fail-under-lines` on pre-push; heavier axes on ci. That ordering is an optimization for an interactive hook (fail fast, cheapest first) ∴ it lives with the runner that HAS hooks (the monorepo). CI has no such gradient — it runs everything on every push — so the standalone gate is FLAT & complete, ⊥ phased. Cargo-native ONLY (V31) either way ∴ the same ops give the same verdict under both; `cargo run` never (a resolved-path bin, ⊥ a nested cargo). The custom guards (hygiene, lexicon, cavekit-spec, ascii) are ⊥ in either — they run in the monorepo via root config (V31). A standalone contributor who wants the gradient uses a git hook | a task runner — a repo-level convention, ⊥ a specced artifact.
V30: **in-repo, itok's config is honored by NEAREST-config cascade** (a host feature): a file under crates/itok/ is measured against crates/itok/ baselines, ⊥ root's (the editorconfig/gitignore cascade, V1). ∴ itok growth is reviewed vs itok ceilings & root config retires its `crates/itok/**` entries. Bootstrap (single root config) → cascade is the dir-walking native tier the host adds; until then root governs by exact-path (the current `crates/itok/SPEC.md` entry).
V31: **the traveling gate is cargo-native + guards that are THEIR OWN CRATE; a HOST-INTERNAL guard is what cannot travel.** The line is OWNERSHIP, ⊥ fanciness — this rule said `custom guards are monorepo-only` & that was the host crates' property mistaken for a law: `repo-guard` & `cavekit-spec` do ⊥ travel ∵ they live in a workspace, ⊥ ∵ they are custom. EVIDENCE: `mth` is the same checker EXTRACTED into its own publishable crate & it travels — an ordinary dependency any repo adopts (T92). So the gate is cargo-native tools (fmt, clippy, nextest, llvm-cov) PLUS any guard that stands alone as a crate. Coverage is a `--fail-under-lines` FLOOR, ⊥ the per-file `coverage-freeze` ratchet (a host bin); `coverage-baseline.json` travels as reference, ⊥ enforced standalone. The floor is the UNIT's OWN coverage (itok ≈ 98%), ⊥ the monorepo WORKSPACE total (siblings inflate it to 99%, B4): a floor copied from the aggregate FAILS the single crate. Two-tier by design — the monorepo is itok's full-guard home; the public repo runs the standard gate. A graft lands public, flows back, & hits the full guards in the monorepo (external contribution, internal tending). Extracting the toolkit is DEFERRED; trigger = the public repo wanting the fancy guards independently. AMENDED by V75: the runner is now the pinned dev shell, ⊥ bare rustup — the OPS stayed cargo-native, only the DELIVERY changed.
V32: **`diff`/`show`/`log` = git's triad, matched to git's CLI.** Three questions at three granularities, git's own split (V1): `diff` = any two points (working · `--staged` · `<A> <B>` · `<A>..<B>`); `show` = ONE commit, deep + per-file (default HEAD, like `git show`); `log` = many commits, one delta-line each. `show <A>..<B>` is ⊥ a thing — a range is `diff` (endpoints) | `log` (walk), & routing it through `show` would be a V2 near-collision. `show <commit>:<path>` = a blob's cost at a ref (`git show`'s object syntax). ∴ each verb means exactly what its git namesake means, no almost.
V33: **`--` path filter & `A..B` are GIT-UNIVERSAL, ⊥ per-verb reinvented.** `-- <path>` narrows show/diff/log to a pathspec (git's rev-vs-path separator); itok is lenient when a bare arg is plainly ⊥ a rev (`itok show <sha> SPEC.md`). `A..B` selects endpoints (`diff`, ≡ `A B`) | a range (`log`), per git. All 3 verbs stand on ONE primitive — `gitref`: the token cost of a file AT a commit (`git cat-file` blob → dummy|bpe). diff compares 2 refs, show does one commit's per-file deltas, log walks a sequence; build it once, share it (⊥ 3 copies).
V34: **runs fully in a NETWORKLESS SANDBOX.** Core/default build ! need ZERO network & ZERO extra auth. Tiers stack fastest-local → slowest-remote (V4): `dummy`·`--bpe` = local core (sandbox-safe, always built); `--ollama` = opt-in remote rung, feature-gated (V23) & doc'd as a SLOWER tier of operation. A no-net sandbox runs the local tiers & every gate (`check`, `--budget`) unchanged ∵ gates pin `--bpe` (V5) & never touch net. This is the north-star axis: content-locality > precision (V36).
V35: **no paid API, no extra auth — cloud `count_tokens` REJECTED.** A provider exact-count (e.g. anthropic `/v1/messages/count_tokens`) needs an API KEY (extra auth) + a paid-tier credential + EGRESSES file content to a third party (DLP/compliance) ∴ ⊥ core, ⊥ any default. The exact rung is `--ollama` instead (local model's own tokenizer, keyless, free, on-LAN — V22); `o200k` (`--bpe`) is the honest LOCAL proxy for cloud models meanwhile. Considered & rejected, escape hatch recorded (like V24/V25): a cloud rung, if ever wanted, is a separate opt-in feature that ! never be default & ! shout its content egress.
V36: **guardrail wants a CONSERVATIVE estimate, ⊥ a true count.** The gate's job = catch context OVERLOAD, ⊥ report exact tokens ∴ a margin'd local estimate (`--bpe` + headroom under the window) is CORRECT, & chasing cloud-exactness was the wrong axis (V35). Exactness ≠ goal; non-overload = goal. `--ollama` exact is a CONVENIENCE for model-fit reporting (doctor/fit), ⊥ a requirement of the gate. Model-fit selection reads a STATIC `.context-models` window (T14, e.g. `qwen3-coder:30b` = 256k) — no net needed to know a model's ceiling.
V37: **the GUARD travels ∴ tests are LAYOUT-AGNOSTIC.** A test ⊥ assume the monorepo path — `CARGO_MANIFEST_DIR.parent().parent()` as the repo root, `crates/itok/…` pathspecs — ∵ extracted, the crate IS the repo root & those overshoot the tree / name absent paths (B2). Derive the git root & the crate's prefix at RUNTIME (`git rev-parse --show-toplevel` / `--show-prefix`) so ONE test passes at `<repo>/crates/itok` AND standalone. V13's "extraction = a move" binds the TESTS too, ⊥ only src; the rehearsal (`subtree split` → clone → run `.uow` guards) is how it is proven (T11). LAYOUT is not the only ambient a test ⊥ assume: repo STATE too — the live `HEAD~1..HEAD` is ⊥ presumed SUBSTANTIAL (a near-zero-delta config commit as HEAD broke a `--budget` breach assertion, B3); drive a delta test from a CONTROLLED range (empty tree → HEAD adds the whole repo), ⊥ ambient history.
V38: **a network backend is CASSETTE-REPLAYED in the gate, ⊥ live.** Record the real HTTP interactions ONCE into a standard `vcr-cassette` file (portable, VCR-interop), replay them offline THROUGH the real client (ureq) via a local stub (a `TcpListener` serving the recorded response) so the full path — client → parse → render — is deterministic & CI-safe with NO server. The LIVE endpoint check is a `#[ignore]` test, run by hand (`--ignored`), ⊥ in the gate. The cassette dep is DEV-only (serde/chrono/ url, ⊥ tokio/async) ∴ V23/V13 hold: the shipped binary stays network-free & tiny. rvcr rejected — it is reqwest+tokio = an async runtime, V23's forbidden shape. ∴ every network feature ALSO runs a CI axis (`--features ollama` clippy+nextest in `hk.pkl`) so the replayed path ⊥ rot.
V39: **publishable = public gate green + honest SemVer + zero private reference.** crates.io needs 4: (1) the STANDARD gate reproduces on plain rustup CI (V31) — fmt · clippy · test · `--features ollama` · `llvm-cov --fail-under-lines`, NO nix & NO host bin, git history fetched FULL (diff/show/log read `HEAD~n`); (2) SemVer tells maturity TRUE — the version is a RUNG on the ladder (V70), ⊥ default `0.0.0`; publication itself is `0.7.0`, ⊥ whatever number the crate happens to carry; (3) metadata complete (`repository`·`homepage`·`documentation`·`readme`· `keywords`·`categories`·`rust-version`) so crates.io/docs.rs render; (4) the shipped `.crate` names NO origin repo (V26) & `exclude`s non-consumer files (dev machinery & baselines) while a `must-package` list names what ! SURVIVE the exclude (B-less blind spot: dropping a file the shipped tests read stays GREEN here ∵ the repo still has it). Publish = `subtree split` (V13) of a crate carrying all four.
V40: **docs render from ONE command registry — `itok docs` emits it, a guard FREEZES it.** itok hand-rolls args (no clap) ∴ verb/flag text scatters across help strings & rots alone (the README did). One registry (verb → synopsis · flags · exit) feeds EVERY view — `--help`, `itok docs` (markdown reference), later man — so a new verb is a ONE-place edit. READ-ONLY, to stdout (V6): `itok docs > README.md` is the USER's redirect, ⊥ the tool writing. Generated = REFERENCE; the NARRATIVE (intro, ladder, mermaid) stays hand-written ABOVE it. A guard diffs `itok docs` vs the committed reference ∴ staleness FAILS the gate (coverage-freeze, V14) — docs cannot rot, ⊥ merely regenerable.
V41: **second axis — RUNTIME, beside the static one.** V1-V40 answer about FILES, ex ante ("what will this cost?"). The runtime axis answers about a CONTEXT, ex post ("what actually got loaded, by what, at what cost?"). Same estimator engine (V4), new frontend. It earns its own verbs ∵ input tokens are billed EVERY turn while output tokens spend ONCE ∴ a file loaded at turn 3 is still charged at turn 40 & runtime waste COMPOUNDS. `itok` = input tokens (V3) ∴ this axis is the name's other half, ⊥ scope creep.
V42: **observe before enforce** — the ORDERING law & the modularization law. Telemetry (read-only, post-hoc, zero interception) ships FIRST & usable ALONE; reduction ships next & usable ALONE (a pipe filter); enforcement ships LAST, tuned from measured numbers. ∵ a fuse threshold guessed w/o data has false-positives that cost MORE than the waste it prevents (a denied legit read = retries + rephrase = burned turns). Each rung ! stand on its own & be shippable alone; none may require the next.
V43: **the transcript is the GROUND TRUTH & is READ-ONLY.** Session data comes from the harness's own on-disk transcript (Claude Code: JSONL under `~/.claude/projects/…`), ⊥ from interception. It already carries the real API `usage` ∴ ACTUAL, ⊥ estimate — the closed loop for free. itok NEVER writes/moves/mutates it. FOREIGN & unversioned schema ∴ parse defensively: unknown fields ignored, malformed record SKIPPED w/ a counted total, ⊥ crash, ⊥ a hard schema assert. ONE reader module, harness-PLUGGABLE (a new harness = a new reader, ⊥ a new tool). The file APPENDS LIVE while a session runs (measured: 1483→1496→1499 lines across 3 consecutive reads) ∴ read a SNAPSHOT & tolerate a TORN TAIL — the last line MAY be half-written. Two reads a second apart otherwise disagree, & a report-only verb that contradicts ITSELF is broken (V5, one level up).
V44: **the ledger is a LOWER BOUND & says so** — V3's honesty rule on the runtime axis. Load events cannot see system prompt, tool schemas, `CLAUDE.md`, or prior turns ∴ report `accounted` vs `total` & label the gap `unaccounted`; NEVER silently attribute the remainder. MEASURED: `usage` is on 100% of assistant records (495/495) ∴ the TOTAL is EXACT & only the ATTRIBUTION is partial — say which, & ⊥ hedge the total as though it were estimated. Every number names its method (V3): `ledger(actual)` ≠ `ledger(bytes/4)`.
V45: **content NEVER enters the ledger & never leaves the box.** Record path · content hash · count · ts · tool · session; ⊥ file bodies, ⊥ message text, ⊥ env, ⊥ credentials. Transcripts hold the user's & their customers' content ∴ a telemetry file that copied it is a NEW leak surface buying nothing — counts answer every question this axis asks. No egress at all (V35): local files & stdout only; itok ships NO uploader, NO endpoint, NO opt-out-shaped default.
V46: **runtime verbs keep top/du/strace grammar** (V1) — `trace` = 1 line per load event, chronological (`-n` · `--since` · `--reverse`, the `git log`/strace shape); `top` = ranked occupancy (`-h` · `-s` · `--top N`, the `du`/`top` shape). Both report-only, exit 0 (V5). `log` stays the PATH-HISTORY verb (V19) & session events are ⊥ routed through it — `git log` means commits, so overloading it is the V2 near-collision. NO `blame` verb: per-path attribution is `top -- <path>` ∵ `git blame` is per-LINE authorship & the almost-match costs more than the flag (V1/V2).
V47: **cache accounting is READ, ⊥ inferred.** `cache_creation` / `cache_read` come from `usage` ∴ prefix re-billing is OBSERVED, ⊥ modelled. Report it as seen & name it; ⊥ a heuristic "you probably busted the cache" (that would be a confident guess, V3). Absent fields ⇒ no cache column, ⊥ a zero (a zero reads as a measurement).
V48: **calibration is REPORTED, ⊥ folded — & the sample is never LAUNDERED.** The correction is reported beside its `n`, ⊥ silently folded into the estimators — the ladder's rungs stay honest & unmodified (V4). Applying it is opt-in & LABELLED as derived: `~186k itok (bytes/4 ×1.12 cal:n=340)`. A factor whose sample is ⊥ stated is a confident lie (V3). CORRECTED, method only: this invariant originally derived the factor from turns where exactly ONE load explained the `usage` delta, DISCARDING the rest. That paid most of the sample to dodge per-item attribution — & a 2-parameter fit needs NO attribution at all ∴ uses every turn & yields the fixed overhead as a second output (V102, MEASURED in T87). "Clean samples" was the wrong MECHANISM, ⊥ the wrong goal; the rules above are what survived.
V49: **`cap` = token-unit filter, visibly ⊥ `head`.** stdin→stdout, pipe shape (V1). `head`/`tail` truncate SILENTLY by bytes/lines; `cap` truncates by TOKENS & ANNOUNCES the elision with a machine-parsable footer ∴ it takes a DIFFERENT NAME, ⊥ `head -t` — an almost-`head` is V2's expensive failure. Usable with no agent & no hook: `cmd | itok cap 10k` is the whole product of its rung (V42).
V50: **reduction ladder mirrors the precision ladder (V4)** — ordered LOSSLESS → LOSSIEST, every applied rung NAMED in the footer: `strip` (ansi · trailing ws) | `dedup` (repeat lines `×N`) | `elide` (base64 · minified · lockfile bodies) | `outline` (code → signatures, bodies dropped) | `cap` (hard truncate). Applied IN ORDER, stopping the moment the budget is met ∴ the CHEAPEST SUFFICIENT rung wins & the reader is told exactly which ran. Lossless rungs are default-safe; lossy rungs are opt-in per policy. NEVER reorder lossy-first — silent structural loss is the failure this ladder exists to avoid.
V51: **truncation is RESUMABLE & IDEMPOTENT.** The elision footer carries the resume selector (offset · line range · omitted count) so the next read CONTINUES, ⊥ restarts at 0. An un-resumable cap costs more than it saves (the reader re-fetches the whole file). Re-running the same cap on the same input yields the same cut (V5's determinism, on the filter).
V52: **`guard` is an ADAPTER, ⊥ a daemon.** Shape: harness hook JSON on stdin → decision JSON on stdout, ONE process per call, no server, no background thread, no state beyond an append-only session file. Harness-specific mapping lives in ONE module (V43's pluggability); every other module is harness-agnostic. ∴ a new agent harness is a new adapter, ⊥ a fork of the tool.
V53: **the gate set is CLOSED & every gate is OPT-IN** — extends V5. Gates = `check` (committed registry) · `--budget` (inline one-shot) · `guard` (runtime policy). Nothing else gates, ever. Enforcement never self-enables: no `.context-policy` & no installed hook ⇒ itok is exactly as report-only as it is today. `guard` obeys V5's determinism for V5's reason — its decision pins a fixed tier, ∵ a gate that varies per run is ⊥ a gate — & takes the CONSERVATIVE estimate (V36), ⊥ the exact count.
V54: **fuse is GRADUATED, w/ hysteresis & a MANDATORY escape hatch.** A binary deny costs more than the waste (retry loops burn turns) ∴ tiers by occupancy: `observe` (ledger only) → `warn` (stderr; the agent reads it & self-corrects) → `cap` (elide, resumable V51) → `deny` (& NAME the cheaper alternative: `itok fit`, a line range, `rg -m`). Plus a RATE fuse over a sliding window (N tokens in M calls = runaway `cat huge.log` / grep into `node_modules`). A trip is STICKY w/ hysteresis ∴ ⊥ flapping on the boundary. There is ALWAYS an override — a trapped agent is worse than a fat one.
V55: **the fuse is judged by its OWN telemetry** — V42's other half. Every trip · cap · override is a ledger event ∴ override-rate & false-positive rate are MEASURABLE. A high override rate means BAD POLICY, ⊥ a bad agent, & is the signal to retune. Enforcement that cannot be measured cannot be tuned ∴ ⊥ shipped.
V56: **pins are ABSOLUTE.** Policy MAY pin paths that are never capped, elided, or denied (`CLAUDE.md`, `SPEC.md`, the law files). A guard that elides the rules it guards under is self-defeating. A pin overrides every tier, including a tripped fuse.
V57: **`.context-policy` is the runtime registry, opt-in like `.context-limits` (V10).** Per-glob & per-tool budgets · pins (V56) · fuse tiers (V54). Absent ⇒ NO enforcement (V53). Reuses the one decimal unit grammar (V18) & DEFINES the glob semantics — `?` one char · `*` WITHIN one path segment · `**` ACROSS segments, incl. zero — ∵ there were NONE to reuse: `.context-limits` matches exact paths & `.context-models` matches names, so this rule cited a reuse that did ⊥ exist until `src/glob.rs`. The siblings MAY adopt it (V64: one definition, ⊥ a second grown quietly elsewhere) ∴ still a third config FILE, ⊥ a third config LANGUAGE. `*` stopping at `/` is LOAD-BEARING: a `*` that crossed separators makes `src/*` silently mean `src/**` ∴ a budget written for ONE directory governs the whole tree — V2's near-collision, in a file where the mistake is invisible until something is denied. A pin matches by the SAME patterns ∴ one matching rule to learn, ⊥ two.
V58: **in-flight MITM proxy DEFERRED (⊥ rejected).** An `ANTHROPIC_BASE_URL` shim would see EVERYTHING billed & could enforce hard — but it sits in the CREDENTIAL path & the STREAMING path: it forwards an API key, buffers SSE, & becomes a new failure mode on EVERY request. The transcript reader (V43) yields ~the same numbers post-hoc at ZERO risk, & the hook adapter (V52) yields enforcement at request granularity ∴ the risky rung buys little. Trigger to revisit: a measured need for a signal only in-flight interception can give. If ever built: own opt-in feature (V23), NEVER default, ⊥ read/store/log credentials (V45), & ! shout what it intercepts. Considered & deferred, escape hatch recorded (like V21/V24/V25).
V59: **runtime data verbs report AGGREGATES, ⊥ verdicts** — V19's rule, carried over. `trace`/`top` may compute re-read waste (same blob loaded N× = N× billed), stale bytes (occupancy × turns-since-touched), dup & cache columns — those are ARITHMETIC. "This is unhealthy, do X" is JUDGMENT & belongs to `doctor` if & when it earns a session target (V17's thin-composer boundary still binds: doctor ⊥ grows tentacles).
V60: **fan-out = N windows, ⊥ one.** Subagent / sidechain sessions each own a SEPARATE context ∴ the ledger keys by session & rolls up to the parent. A 12-agent fan-out is 12 windows & its true cost is the SUM — invisible in any single window, which is exactly why it needs reporting.
V61: **money is a RENDERING, ⊥ a source.** `--cost` multiplies counts by a rate read from `.context-models` (an optional per-model column); itok bundles NO price list ∵ prices change & vary by contract ∴ a built-in would go stale & become a confident lie (V3). Missing rate ⇒ NO money column, ⊥ a guessed one (V11's unknown-model rule). Cache-read tokens bill at a different rate than fresh ones ∴ `--cost` ! use the cache split (V47) or omit the column entirely.
V62: **flake at repo ROOT; the dev shell PROVIDES `itok`.** Root ∵ a flake's source root is its OWN dir ∴ a subdir flake (once `.uow/`) cannot see `Cargo.toml`/`src/` — no `packages.default`, no `nix build`/`nix run`; root is also every Rust project's shape (V1). PROVIDES ∵ itok dogfoods itself (V15): ON PATH, ⊥ `cargo run --`. A SHIM (`exec cargo run -q --manifest-path "$ITOK_MANIFEST" --bin itok -- "$@"`), ⊥ a package in the closure — a package builds the crate to ENTER the shell ∴ one compile error locks you out of the shell you need to fix it, & a pinned package is STALE vs the tree. `ITOK_MANIFEST` resolves at entry from `$PWD` (V37); `ITOK_PROFILE=release`/`ITOK_FEATURES` are the hatches. Dev files `exclude`d from the `.crate` (V39). `packages.*` BUILT (T58): `default` (dummy+bpe) · `itok-minimal` (`--no-default-features` ∴ V23/V13's zero-dep claim is a BUILD, ⊥ a promise) · `itok-ollama`. Rests on a COMMITTED `Cargo.lock` ∵ flakes read git-TRACKED files only & the sandbox has no network. `doCheck = false` ∵ the suite shells to git for `HEAD~n` (V33's `gitref`) & a store source has NO `.git` — that absence IS the reproducibility (V37/B3). `version` READ from `Cargo.toml` ∴ ONE number. BUILT is where this rule STOPS; PUBLISHED is V112's, & the gap between them was 9 green jobs producing nothing anyone could fetch.
V64: **ONE gate definition, many callers — eliminate the second copy, ⊥ freeze it.** `hk.pkl` holds the OPS (which command, which flags, which phase, which order, the coverage floor); the workflow holds ORCHESTRATION ONLY (runner, toolchain, cache, full history) ∵ that half has no local equivalent to disagree with. ∴ one definition is reached 3 ways — `pre-commit`, `pre-push`, `hk check` in CI — & the ops CANNOT drift, having only one copy. Contrast V40, which had to FREEZE a second rendering ∵ `--help` text must live in Rust; here both callers can read the same file, & elimination beats policing (a guard detects drift only AFTER someone writes it). B4 is the cost of the alternative: a stale `99` floor sitting in one declaration beside CI's corrected `98`, both looking authoritative.
V65: **the gate of record stays RUSTUP-REPRODUCIBLE — hk RUNS the ops, ⊥ hides them.** Every step is a plain cargo command a human can paste with nothing but rustup ∴ the hook manager is a CONVENIENCE, ⊥ a dependency of the crate (V13/V31). A contributor without hk loses scheduling, never the ability to reproduce a verdict. Bars, by construction: no step is a script only hk can call, no verdict depends on hk's own logic.
V66: **the gate's schema is VENDORED, ⊥ fetched at eval** — V12's reasoning, on config instead of vocab. hk's documented form amends a `package://` URL fetched over the network at eval time; `pkl/Config.pkl` ships in-tree & `hk.pkl` amends the local path (upstream's own repo does the same). Offline-first is the default BUILD, ⊥ merely the default flag (V34). Re-vendored verbatim on an hk upgrade — the pin in the dev shell, the vendored schema & CI's `HK_VERSION` are ONE version, moved together.
V67: **cargo steps SERIALIZE by `depends`; parallelism is for the rest.** Cargo takes a lock on the target directory ∴ two cargo jobs launched concurrently do ⊥ run concurrently — the second blocks on "Blocking waiting for file lock on build directory", which READS AS A HANG. The chain makes the serialization explicit & intended, ⊥ emergent, & leaves hk free to run any future non-cargo check in parallel. Separate `CARGO_TARGET_DIR` per step is the escape hatch & is ⊥ worth it (full recompiles, multiplied disk).
V68: **hermeticity is PROVEN by running parallel, ⊥ argued from inspection.** `--test-threads=1` is a DIAGNOSTIC (it localizes a race), ⊥ a fix (it hides one) ∴ a suite that needs it has a bug, & the bug is the deliverable. Reading a test for per-process temp dirs & ephemeral ports establishes NOTHING — B5 passed that reading & still raced. The gate runs the suite parallel; a flake found there is fixed at the source, never suppressed by serializing the axis.
V69: **a registry no runner reads is a LIE, ⊥ a guard.** `.file-limits` traveled with the crate (V27) but NOTHING standalone enforced it ∴ its ceilings were hand-maintained & obeyed by no one — it read as law while gating nothing. Same failure as V28's dead declaration, one level down: the danger is ⊥ the missing check, it is the FALSE ASSURANCE that a committed registry provides. ∴ dropped here; file-size ceilings stay a MONOREPO guard, where a runner exists. Re-add standalone ONLY together w/ a checker wired into the gate (V64) — the registry & its caller land in the same commit, ⊥ apart.
V70: **version = MATURITY OF THE GUARANTEE, ⊥ feature count.** Each minor answers ONE question — *what can you rely on at this tag?*: `0.1` builds reproducibly anywhere (`nix build`) · `0.2` cannot regress locally (gate in git hooks) · `0.4` KNOWS what a context costs (M4) · `0.6` can ACT on it (M5-M7) · `0.7` PUBLIC, featureset frozen, CI unproven · `0.8` public gate trustworthy · `1.0` CONTRACT frozen. ODD minors (`0.3`/`0.5`/`0.9`) are RESERVED for fix releases ∴ a bugfix never borrows a milestone's number. The ladder ENFORCES V42 STRUCTURALLY: telemetry is `0.4`, enforcement `0.6` ∴ observe-before-enforce becomes a number you cannot skip, ⊥ a rule to remember. `0.7` freezes the PLANNED featureset; `1.0` freezes the CONTRACT (CLI + json, V9) — additions between them are ALLOWED ∵ they come from public feedback, the POINT of exposing at `0.7`. Pre-1.0 SemVer (minor MAY break) is HONEST ∵ each rung IS a behavior change. crates.io is IMMUTABLE (yank HIDES, ⊥ deletes) ∴ the first public artifact is always an `-rc` — cargo ⊥ selects a pre-release by default — so the pipeline is proven before a permanent number is spent. WHICH rung goes public is ⊥ this rule's business (V107).
V71: **a passing gate says NOTHING; a failing one says what to DO.** SUCCESS = SILENCE (`HK_HIDE_WHEN_DONE`) ∵ output that ALWAYS appears is output nobody reads ∴ the one real failure hides in noise everyone learned to scroll past. FAILURE = LOUD & ACTIONABLE: the tool's own diagnostic + a one-line remediation pointer on steps whose fix is ⊥ obvious from the failing command (`itok`/`ollama`/`no-default-features`/`package`/`coverage`) + a playbook (`AGENTS.md`), for agents & humans alike. FAIL-FAST is LOCAL, ⊥ universal: locally the loop is cheap ∴ the FIRST failure is most useful & `depends` orders steps cheapest-first so it arrives fast; in CI a round-trip costs minutes ∴ `--no-fail-fast`, a COMPLETE list. BYPASS ⊥ a fix: `--no-verify` · `HK=0` · lowering a threshold · `#[allow]` all SHIP THE DEFECT with the alarm off. If the CHECK is wrong, that is a SPEC change — deliberate, in its own commit, ⊥ silent at the failure site.
V72: **a gate step MAY need a binary; the VERDICT may ⊥ need one.** The `hk util` family is native to the runner ∴ free everywhere. A second tier (`typos`·`actionlint`·`zizmor`·`taplo`·`shellcheck`) needs a real binary, & that is allowed — V65 binds the OPS a verdict rests on (cargo, rustup-only), ⊥ every auxiliary lint. Rule: the tool is PINNED in the dev shell & installed at a PINNED version in CI, ⊥ floating ∴ the two runners agree (V64). `actionlint` earns its place specially: the workflow is the ONE file NO local run exercises (V64 keeps orchestration there) ∴ without it, a mistake in the workflow is found only by pushing.
V73: **an exemption NAMES what is deliberate; it is ⊥ a suppression.** `.typos.toml` exempts `esimate` ∵ it is the INPUT to the typo-suggestion tests (V6) — the mistake ! be spelled correctly in both the unit test & the README example — & exempts `pkl/` + `tests/fixtures/` ∵ one is vendored VERBATIM (V66) & the other is a RECORDING (V38): "fixing" either silently forks it. Every exemption carries its REASON in the config file, ⊥ in a commit message nobody reads at the failure site. A suppressed finding w/o a named reason is indistinguishable from a bug (V71's no-bypass rule, applied to config).
V74: **a hook DEGRADES when its runner is absent; it ⊥ BLOCKS.** A gate exists to stop bad commits, ⊥ to stop git. When the runner is missing — outside the dev shell, a fresh clone, a container — the hook prints ONE line to stderr & exits 0: LOUD about being skipped, ∵ a SILENTLY skipped gate is indistinguishable from a passing one (V71). Hard-failing instead makes the repo unusable for anyone who ⊥ installed the toolchain, which is the wrong failure mode for a CONVENIENCE — the gate of record is CI + `hk check` (V65), ⊥ the hook. ∴ the hook command is written BY HAND, ⊥ by `hk install`, whose command assumes its own binary is on PATH (B6).
V75: **CI runs the SAME SHELL, ⊥ a parallel install path** — amends V31. That invariant's bare-rustup CI predated the crate carrying its own ROOT flake (V62); now nix IS this crate's toolchain, ⊥ a host dependency ∴ `nix develop --command hk check` hands CI the EXACT tools pinned in `flake.lock`. One toolchain + one gate definition (V64) ⇒ ZERO version skew between a runner & a laptop, & no per-tool install action that can drift from what the dev shell has. hk stays LOCAL-ONLY as a DIRECT dependency: CI reaches it THROUGH the shell, ⊥ by installing it — same for every linter (V72), which is why the workflow installs none of them. V31's real content SURVIVES: no HOST guard bin travels w/ the crate, & the ops stay plain cargo commands (V65) ∴ a contributor w/o nix reproduces every verdict by hand. ONLY "no nix in CI" is superseded. What CI cannot yet validate (matrix · MSRV · caching · SHA-pinned actions · publish) is LISTED in the workflow, ⊥ silently absent — a gap you can read is ⊥ the same failure as a gap you cannot (V44's honesty rule, on infrastructure).
V76: **the transcript records what was BILLED, ⊥ what exists on disk.** A tool result is TRUNCATED before it enters context & the overflow is spilled to a side file: MEASURED, `persistedOutputSize` 5,749,032 bytes vs `stdout` 30,000 chars — the same event, 190x apart. The CONTEXT COST is the truncated content ∴ NEVER substitute an on-disk size for a load size; that direction overcounts by orders of magnitude & would make the ledger confidently wrong (V3). Corollary: tool-result shapes are TOOL-SPECIFIC & sometimes a bare STRING, ⊥ an object — there is no uniform load record to key on (V43's defensive parse is load-bearing, ⊥ decoration).
V77: **a session read is CONTENT-ADDRESSED & truncated at the last COMPLETE LINE.** The file appends live ∴ hashing the WHOLE file gives a different key every second; hashing the complete-line PREFIX gives the SAME key until a whole new record lands. A torn tail therefore ⊥ change the key, & two reads a second apart AGREE — which is the requirement (V43), ⊥ a nicety: a report-only verb that contradicts itself is broken (V5). Determinism comes from the TRUNCATION, ⊥ from storing anything. The on-disk CACHE is REJECTED, ⊥ merely deferred: MEASURED, a 2.7MB transcript parses in 8ms (file read 0.6ms) ∴ a cache would buy 8ms & cost itok its FIRST user-level state — a home directory to choose (XDG is Linux's convention, ⊥ macOS's `~/Library/Caches` | Windows's `%LOCALAPPDATA%`), an invalidation scheme, a pruning policy, & AMBIENT STATE in a tool that is today a PURE FUNCTION of its inputs (every config it reads is project-local). Stale ambient state is V5's hazard one level up. V19's per-blob-hash rule stands for BLOBS (a git history walk re-estimates the same blob many times); a session is read ONCE per invocation, so the rule does ⊥ transfer. Trigger to revisit: a verb that must re-parse MANY sessions inside an interactive loop, w/ a MEASURED slowness — 100 sessions is 0.8s today, which is ⊥ slow. Considered & rejected, escape hatch recorded.
V78: **the LOAD CLASSES are tool results AND attachments.** Hook output, reminders & injected context are loads too: MEASURED, 266 `hook_success` attachments ≈ 45k itok in one session — invisible today & fully attributable w/o storing any content (V45). Counting only tool results would under-report the accounted share & inflate `unaccounted` (V44) while the data sat right there.
V79: **a fixture PINS its own shape, & the guard stays armed WHERE the data lives.** A fixture that quietly stops representing its case does ⊥ fail — it WEAKENS whatever depends on it, invisibly ∴ each property is asserted (torn tail stays torn · garbage line stays mid-file · spilled size stays >> billed). The transcript guard (V45) & the fixtures INTERLOCK on an INTRINSIC signal — a UUID-shaped id, which every real capture carries & no hand-written fixture has — ⊥ on LOCATION: exempting `tests/fixtures/` would disarm the guard exactly where a real transcript is most likely to be pasted "to make a test easier". Proven by planting one there & watching it fail.
V80: **try to REFUTE before you trust — self-review is ⊥ review.** The context that produced a finding shares its blind spot ∴ cannot audit it; that is STRUCTURAL, ⊥ a matter of care. Every §V invariant & every §B diagnosis earns an attempt to KILL it — ideally by a fresh context that has ⊥ seen the author's reasoning first (reading it ANCHORS the reviewer, so agreement afterwards is worth less than independent agreement). EVIDENCE, this repo: every correction so far arrived via a FAILURE — B5 (hermeticity claimed from READING the fixtures, disproved by running parallel), B6 (a hook installed then blocking every commit), a fixture test that PASSED while asserting nothing — ⊥ one came from someone looking in advance. That is reactive, ⊥ open. Openness ⊥ indecision: once the disconfirming evidence is sought & weighed, DECIDE; reopening a settled question w/o NEW evidence is churn, ⊥ rigour.
V81: **an unresolved disagreement is a HIDDEN DEFECT.** Two assumptions then drive one system until they fail at a boundary — B4's shape exactly (two declarations, two floors, both authoritative). ∴ surface a disagreement WHEN IT APPEARS, naming the competing positions, their evidence, & the decision they affect; SILENCE ⊥ alignment. Verify alignment by BEHAVIOR — re-run the check, inspect the artifact — ⊥ by verbal assent, which hides different readings of the same words. Where agreement is impossible, RECORD the governing decision & the REMAINING RISK (V21/V24/V58's "considered & rejected, escape hatch recorded" is this pattern already). `SPEC.md` IS the sync artifact: a resolution lands in §V so future-me & a fresh agent inherit the SAME assumptions.
V82: **believability is per-DOMAIN & earned by OUTCOME, ⊥ asserted.** Weight a claim by its source's track record IN THAT AREA; an unproven source gets a second verification gate. Applied concretely & uncomfortably: in THIS repo, my assertions-from-inspection have a MEASURED record of being wrong — B5, B6, & a test that passed for the wrong reason ∴ "I read it and it looks correct" carries LOW believability here & earns a verification pass BY DEFAULT (V68 generalized beyond tests). Symmetrically, a claim backed by a RUN — exit code, diff, counted output — needs no such gate. Update the weight on evidence, in both directions.
V83: **best idea wins; make the COMPARISON auditable.** itok already does half — V21/V24/V25/V35/V58 record what was considered & CLOSED, why, & the TRIGGER that would reopen it ∴ a reader can audit the decision rather than merely obey it. CLOSED has TWO states & the TRIGGER tells them apart: V24/V25/V35 are REJECTED (no reopening contemplated), V21/V58 are DEFERRED and say `⊥ rejected` in their own text, each naming a CONDITION. ⊥ interchangeable & ⊥ a §T row: done-when lives on the MILESTONE ∴ a deferral moved to §T loses its trigger & keeps only `maybe someday`, & `.` means PLANNED where a deferral is deliberately UNPLANNED-until-X. The deferred pair is the MORE fragile: a rejection reads as a closed decision, a deferral reads as an unbuilt feature ∴ a byte-cutting pass drops it thinking `⊥ built = ⊥ needed`. The baseline is `.spec-records` (B13). The other half: where several designs compete, score them against EXPLICIT criteria & graft the strongest parts of the losers, ⊥ discard them wholesale. Merit is established by SURVIVING SCRUTINY (V80), ⊥ by gathering agreement — & an idea's source is ⊥ evidence for it.
V84: **evolve or decay — & spec growth is a RECURRING cost.** Propagate a proven improvement to every consumer (⊥ leave it local); keep spec & toolchain current; MEASURE the rate of adaptation ∵ a system that still works but no longer learns is ALREADY decaying. Failing case, named rather than hidden: T49's compaction debt has slid 4x while `SPEC.md` DOUBLED (29k→60k bytes). MEASURED consequence: the spec is re-billed on EVERY turn of EVERY session (~5% of a 112M-token session) ∴ every added byte is a permanent tax on all future work, & compaction is a COST control, ⊥ tidiness. This invariant indicts its own commit: V80-V87 grew the file again ∴ T49 is now DUE, ⊥ deferred.
V85: **drive to a TERMINAL state; a marked blocker IS terminal.** Green gate, or an EXPLICIT blocker carrying evidence + the required next action + who can unblock it. SILENCE is abandonment; a clearly-marked blocker is an honest end state (the workflow's PENDING list, V75, is this shape). The MACHINE BOUNDARY is owned — toolchain, CI, config, deps are PARTS of the system producing the result, ⊥ excuses for a bad one (V71). A handoff closes only w/ an acknowledged owner & a VERIFIABLE completion condition; "done" ⊥ mean "I stopped".
V86: **the 5-step loop IS the SDD loop, ⊥ a parallel ritual.** goals = §G + a §T done-when · problems = observed reality vs goal · diagnose = ROOT CAUSE before fix (§B) · design = §V + plan · do = build & VERIFY against the goal. Do ⊥ skip steps; the common skip is problem→fix w/o diagnosis, which patches a symptom & leaves the disease — B4 recurred precisely because a FIX was copied while the CAUSE (two sources of one number) went unnamed.
V87: **weigh 2nd- & 3rd-order consequences, ⊥ only the 1st.** The immediately pleasant choice is often wrong once downstream effects are counted. Recorded cases: V58 (an in-flight proxy 1st-order SEES EVERYTHING; 2nd-order it sits in the CREDENTIAL & STREAMING path on every request) · V54 (a binary deny 1st-order stops a bad load; 2nd-order it burns retry turns & the agent routes around it) · V45 (a telemetry file that copied content is 1st-order convenient; 2nd-order it is a NEW LEAK SURFACE buying nothing) · V84 (a spec addition is 1st-order clarity; 2nd-order a per-turn tax forever). The generalization: ask what a choice COSTS ON EVERY LATER TURN, ⊥ only what it buys now.
V88: **an unparsable registry row FAILS; it is NEVER skipped.** V11's rule (unknown model ⇒ FAIL, name an encoding) binds EVERY registry, ⊥ only `.context-models`: a row the tool cannot read is a row the AUTHOR believes is enforced ∴ skipping it silently converts a gate into decoration & is strictly WORSE than having no row (V69). Applies to `.context-limits` · `.context-models` · `.context-policy` · `.context-hosts`. The diagnostic ! name the FILE, the LINE & what was expected. Corollary for the reader: `checked:N` is part of the contract (V9) ∵ it is the only way a caller can notice that fewer paths were gated than registered — B7 was found by that number, ⊥ by the exit code.
V89: **itok is SAFE TO RUN CONCURRENTLY — many processes, & threads within one.** VERIFIED: the shipped binary WRITES NOTHING (fs writes are `#[cfg(test)]`, into per-PID temp dirs), mutates no env & no cwd, has no `static mut`, forbids `unsafe` crate-wide, & its ONE shared item is a `OnceLock` — `Sync` by construction ∴ safety is FREE: a pure function of its inputs cannot race. A PROPERTY TO PROTECT, ⊥ an accident — `guard` (V52) is one process per hook call & hooks fire concurrently. Any future write ! be (a) ATOMIC whole-file (temp named by PID, then `rename()`: POSIX-atomic within a filesystem ∴ a reader sees OLD or NEW, never partial) | (b) APPEND-ONLY w/ small records, where the reader already tolerates a torn tail (V43, generalized to our own file). LOCK FILES ⊥ used ∵ a lock held by a KILLED process wedges every instance, & in a git hook a wedge beats a benign race. CONTENT-ADDRESSED keys make a write race BENIGN (same key ⇒ same bytes ⇒ last writer wins IDENTICALLY) ∴ a reason to prefer them. DELETION races TOLERATED: ENOENT ⇒ recompute. Every temp path ! carry the PID (why the suite is parallel-safe, B5). EXERCISED, ⊥ claimed: the `--ollama` fleet runs ONE THREAD PER HOST (T89), itok's FIRST in-process concurrency — each thread owns its result & shares NO mutable state ∴ still pure. & parallel I/O ! ⊥ change the ANSWER: merge in FLEET ORDER, ⊥ completion order, else two runs disagree about a model on two hosts w/ different windows (V5).
V90: **a cache is justified only by CROSS-INVOCATION repetition over an IMMUTABLE key.** Repetition WITHIN one run is MEMOIZATION — no storage, invalidation, or concurrency question ∴ try that first. A MUTABLE key (path+mtime) is where caches rot; an immutable one (git blob SHA, content hash) cannot go stale. Both conditions, or no cache (V77/B8: 8ms of benefit against a new class of ambient state). WHERE, if justified: `.git/<tool>/` for git-derived data — in the repo but ⊥ the WORKING TREE ∴ never in `git status`, dies with the clone (precedent: git-lfs's `.git/lfs`); `~/.itok/` for content-addressed data shared ACROSS clones (the dev-tool dot-dir convention — cargo·rustup·npm·ollama — ⊥ XDG, which is LINUX's & ⊥ macOS's `~/Library/Caches` | Windows's `%LOCALAPPDATA%`). NEVER a working-tree `.itok/`: itok runs on ARBITRARY repos (V10) ∴ an untracked dir in a clone you do ⊥ own surfaces in someone else's `git status`. NEVER both without two DISTINCT lifetimes — two invalidation stories & a precedence rule is where "which is stale?" bugs live.
V91: **`headroom` = `df` for a context; the RATE is per TURN, ⊥ per second.** V8 already binds `estimate` to `du`; `df` is `du`'s sibling & the gap was real — "how much room is LEFT" had no verb. Columns are `df`'s own (window · used · avail · use%) ∴ the layout needs no teaching (V1). loadavg's THREE-WINDOW shape is kept ∵ short vs long reads the TREND at a glance (MEASURED: 958/921/838 itok/turn = rising; 623/915/82 = a burst that had passed) — but the CLOCK is TURNS, ⊥ wall-seconds: context grows per TURN & nothing happens between them ∴ a wall rate would report "load dropping" through an idle hour with the window as full as ever. V2: keep the convention's SEMANTICS, ⊥ its literal unit. NAMING, considered & rejected: `load` — already means a load EVENT here (`LoadEvent`, top's `loads` column) ∴ collides INSIDE the tool, worse than outside (V2); `uptime` — a DURATION, we report a rate; `turns` — names the UNIT ⊥ the question, & a plural reads as a LISTING (`trace`'s job); `free` — the best prior (`free -h`) but `fit` exists ∴ `itok f` would go AMBIGUOUS, breaking a working prefix (V6). `headroom` names the QUESTION & has a free prefix (`h`).
V92: **no window ⇒ NO denominator, ⊥ a guessed one.** `avail`/`use%`/ `turns left` all divide by a capacity that comes from `--window` | `--model` | `.context-models` (V18). Absent ⇒ report `used` alone & SAY the capacity is unknown — V11's rule (unknown model ⇒ FAIL, name an encoding) applied to a denominator: assuming 200k | 1M would make every derived column a FICTION while looking measured (V3/V47).
V93: **`turns left` is an EXTRAPOLATION & says so.** It is `df`'s "how long until full at the current write rate" — arithmetic on a STATED assumption, ⊥ a verdict, so it stays inside V59's boundary. It ! name the assumption ("at the recent rate") & carry the tilde. A zero-window turn is EXCLUDED from the rate, ⊥ treated as a measurement: MEASURED, one turn in a real session reported window 0, which a naive delta rendered as a -387,741 "compaction" that never happened (V47, from a third direction). Note the distribution is HEAVY-TAILED (median 285 vs mean ~900 itok/turn) ∴ a high rate often means ONE big read landed recently, ⊥ that everything is heavy — the triple's SPREAD is the signal, ⊥ any single number.
V94: **cache reads are cheap PER TOKEN & the aggregate is QUADRATIC.** MEASURED (1048 turns, this repo's own session): 379.6M billed input = 99.5% cache READ · 0.001% fresh, & the window grew 32,780 → 720,349 (22x). Total cost = the SUM OF WINDOWS ∴ it is the INTEGRAL of a growing line, ⊥ a constant × turns: mean window 362k against a final 720k. ∴ a reduction's value is `size × turns REMAINING`, ⊥ its one-time load cost — dropping 100k at turn 200 of 1048 avoids 84.8M cache-read tokens, & a 200k CAP would have avoided 185.5M = 49% of the entire bill. EARLIEST reductions dominate. CORRECTED: the first version of this invariant said the ladder "mostly saves CHEAP tokens" & concluded enforcement was worth less than it looks — true per token, WRONG in aggregate, & backwards about V50/V54, which this strengthens. itok bundles NO price list (V61) ∴ it reports the split & the SIZE×TURNS leverage; the reader applies their own rates.
V95: **n=2 is an ANECDOTE; the fuse gets NO new target from it.** Two turns wrote 250,657 each (26% of all cache writes) & the obvious reading — "agents bust the prefix cache constantly, so retarget the fuse" — was DRAFTED & then REFUTED by looking: both sit 19s apart w/ byte-identical write AND read, immediately after `Login expired · Please run /login`. A RE-AUTH left the cache cold; the prefix was re-written from scratch, twice. ⊥ agent behavior · ⊥ context mutation · ⊥ cache pressure · ⊥ the concurrent sessions in OTHER trees (different prefixes ∴ nothing of ours to evict; & eviction of a GROWING context could ⊥ produce identical sizes). ∴ there is currently NO evidence that normal agent behavior causes expensive cache busts here, & V50/V54 keep their shape until there is. The cold-cache event is worth REPORTING (~250x a normal turn's write, one line to explain) & is an OBSERVATION, ⊥ a threshold (V42). This invariant exists ∵ the wrong version was one question away from being specced: V80's refute-first & V82's low-believability-for- inspection both earned their place the day they were written.
V96: **session identity comes from the HARNESS when it offers one.** `newest_transcript` picks by mtime ∴ w/ two sessions in ONE project it can silently read the WRONG one — a report about someone else's context, labelled as yours. MEASURED-adjacent: this machine ran 3 concurrent sessions, saved only by their being in different projects. Prefer an explicit id from the environment; fall back to newest-by-mtime ONLY when none is offered, & SAY which was used (V3) — "the newest transcript" & "your session" are different claims.
V97: **retention is cheap only at ENTRY or at SESSION END; the middle is a TRAP.** Prompt caching makes the prefix append-only in practice: deleting | mutating something EARLY invalidates everything after it & forces a full re-write — MEASURED at ~250k, ~250x a normal turn's write (V95). ∴ "evict the stale stuff", the intuitively obvious lever, COSTS MORE THAN IT SAVES, & the two viable levers are (a) cap BEFORE it enters (V50's ladder, which is why the ladder caps at LOAD ⊥ prunes later) & (b) END the session (which is why a spec that makes a fresh session productive is a COST control, ⊥ only a memory — V84). Harness-owned options (compaction · sub-agent fan-out, V60) are the same two shapes: compaction is a lossy session-end, fan-out is entry-control by giving the expensive work a context that DIES. itok MEASURES all of them & owns only (a).
V98: **`size × turns` is now MEASURED, ⊥ assumed — the stale metric is unblocked.** T32 refused to compute it ∵ the multiplication "assumes every one of those turns re-sent the item, which the transcript does ⊥ record per item". That assumption is now OBSERVED: `cache_read` ≈ the whole window on every warm turn, & the window only GROWS ∴ an item entering at turn N in a T-turn session really does carry ~`size × (T-N)` of cache-read billing. Report it, & state the CAVEAT it rests on — which is now CONDITIONAL, ⊥ blanket: a compaction HAS been seen (B29: 6 auto compactions over 88 transcripts, 2 of them itok's OWN) ∴ "all that has been observed" was FALSE for over a month while this sentence claimed it. RULE: a session whose transcript carries a `compactMetadata` had items LEAVE ∴ its product is an UPPER BOUND & the row says so, naming when; a session carrying none keeps the exact reading. The transcript ANSWERS this per session ∴ the branch is READ, ⊥ promised for later (V3).
V99: **progression advice names V97's TWO levers & names the TRAP as a trap.** A visible `use%` (V91) invites "evict the stale stuff", & V97 measured that backwards: the prefix is append-only in practice ∴ an early deletion re-writes everything after it (~250k, V95). ∴ the suggestion is REJECTED as advice, ⊥ merely omitted — omission leaves the reader to invent it, & the reader's intuition is wrong here. PERMITTED set = V97's two shapes ONLY: cap at ENTRY (V50) · END the session | fan out (V60). `doctor` gains a SESSION TARGET, ⊥ tentacles (V17): every figure comes from `headroom` (T72) | `top` (T75), ⊥ a new estimator. A level that triggers ADVICE is ⊥ a fuse (V42) ∵ ignorable advice costs ~0 when wrong while a deny burns turns (V54) ∴ it needs no tuning data & does ⊥ wait on M6 — but it ! appear only when a level is CROSSED, ⊥ on every run (V71).
V100: **`carried` has TWO directions; they are LABELLED apart.** T75's column is BACKWARD — billing already paid, over OBSERVED turns (V98). `projected` is `size × turns REMAINING`, & its count comes from `headroom`'s `~turns left` (V93) ∴ an extrapolation ON an extrapolation: tilde + the named assumption ("at the recent rate"), like every derived number (V3). TWO names, ⊥ one column w/ a sign — a measured past near-colliding w/ a guessed future is V2's expensive failure & the tilde is the at-a-glance separator. No window ⇒ no `turns left` ⇒ NO `projected` (V92). Both directions inherit V98's caveat AND its condition: a compaction makes them UPPER BOUNDS, & that day has arrived (B29) ∴ the label is read off the session in front of the verb, ⊥ deferred to a reader who notices.
V101: **an optional-value flag carries its value with `=`; the space form is a HEURISTIC that MAY decline.** `--ollama box1` cannot be told from a file named `box1` ∴ the ambiguity is STRUCTURAL, ⊥ a parser weakness, & resolving it by asking the FILESYSTEM would make parsing depend on what happens to exist (V5's determinism, one level up). `--flag=value` is unambiguous by construction & is the GNU prior (V1) ∴ it is the CONTRACT; the looks-like-a-host heuristic (comma-list · `host:port` · `-`) stays as CONVENIENCE. A declined token ! NEVER fall through to the DEFAULT silently (B10) — that turned a named endpoint into a confident `(exact)` count from whatever answered locally. Corollary, V3 on the remote tier: an exact count's meaning depends on WHICH tokenizer produced it ∴ the method label ! name the ENDPOINT — `(exact via 192.0.2.10:11434)`, ⊥ a bare `(exact)`.
V102: **total context is DERIVABLE offline, as a 2-PARAMETER fit w/ a stated BAND.** MEASURED (n=363 turns, fit on the first half, VALIDATED on the unseen second): window = a FIXED 32,074 itok (system prompt + tool schemas — invisible to the transcript, yet read almost directly at turn 1: 31,989 window vs 614 of content) + 1.571 × `bytes/4` of transcript content; held-out error mean 5.0% · max 7.4%. ∴ `unaccounted` (V44) DECOMPOSES into a measured CONSTANT + our own UNDERCOUNT, ⊥ a mystery. Needs NO per-item attribution ∴ strictly better than V48's clean-sample factor, which DISCARDS turns to get one. The transcript beats `--ollama` as the calibrator for a Claude session ∵ `usage` is that model's OWN exact count; ollama stays the calibrator for a LOCAL target. RULES: report the BAND & `n`, ⊥ a point (5% of 340k = ±17k); REFUSE a fit verdict INSIDE the band (V92's no-denominator rule, applied to precision); derive PER SESSION & per harness ∵ the slope absorbs message framing + the STRIPPED `thinking` text (0 bytes stored, an 808-byte signature kept) ∴ it is ⊥ a tokenizer ratio; a compaction breaks the monotonic premise (V98).
V108: **a SHORTENED number uses CEILING, ⊥ floor — a published approximation OVERSTATES, the safe direction.** `shorten(n)`: 0–99 raw digits · 100–999000 `Xk` (`(n+999)/1000`) · 999001+ `Xm` (`(n+999999)/1000000`). Ceiling ∵ "at least this much flowed through" is honest for a flow metric; floor would understate & read as "only this much". Threshold at 100 ⊥ 1000: `100 → 1k` is 2 chars vs 3, already a win; `99 → 99` is already 2 chars. Boundary at 999001 ⊥ 999500: `999000 → 999k` (4 chars), `999001 → 1m` (2 chars) — `1000k` (5 chars) never produced, less chars always wins. The function is PURE & unit-testable in isolation. APPLIED by `rate` (V59's aggregate, ⊥ verdict boundary), & available to any future verb that needs a compact token count.
V109: **`itok.toml` is the unified config — TOML, ONE file, ONE parser.** Project root wins; `~/.config/itok/config.toml` is the global fallback. Sections: `[rate]` (per-metric green/amber thresholds for `rate --color`). FUTURE sections (`[limits]`, `[policy]`, `[models]`) migrate the current dotfiles; migration is a SEPARATE task & the dotfiles keep working — `itok.toml` wins when both exist, ⊥ a merge. Parse via `basic-toml` (dtolnay, ~1k lines). DEP COST, MEASURED ⊥ asserted: the runtime closure goes 25 → 32 packages (`cargo tree -e normal`) ∴ +7, ⊥ the 0 first claimed here. `serde` IS transitive via `serde_json`, but a DIRECT `serde` w/ `derive` pulls `serde_derive` & its macro machinery (`proc-macro2` · `quote` · `syn` · `unicode-ident`) into the NORMAL tree ∵ a proc-macro crate is a normal dep of whatever derives w/ it ∴ "already transitive" was true of the crate & false of the closure. `unicode-ident` re-adds a `Unicode-3.0` obligation the 0.3.0 notices recorded as GONE (docs/THIRD-PARTY-NOTICES.md). GENERALLY: a dep-cost number in this file is READ from the tree, ⊥ reasoned from the manifest (V3). Parse failure = treated as ABSENT, ⊥ error — silent degradation ∵ color is cosmetic & a broken config file ! ⊥ break the measurement (V5's gate-only-when-gating, applied to display). `[rate]` schema: `turn = { green = N, amber = N }` · `total` · `hour` · `day`; below green = green ANSI, below amber = amber, above = red; missing metric = no color opinion for that value.
V104: **a NAMED source that cannot be read is an ERROR; only an INFERRED absence is silent.** The runtime verbs read a transcript either NAMED by the caller | INFERRED from cwd+mtime (V96), & the two absences mean OPPOSITE things: inferred-absent = nothing was asked for ∴ silence is the honest answer; NAMED-absent = the caller asked for something SPECIFIC & got nothing ∴ silence is a LIE that reads as `that session is empty`. ⊥ a loosening of V5: report-only means never gating on CONTENT, ⊥ that a bad ARGUMENT goes unreported — `top --bpe` already exits 2 on the same verb (§I: 2 = usage). The diagnostic NAMES what was tried (both forms + the dir searched) ∵ `not found` alone cannot distinguish a typo'd id from a session that is really gone (V71). MEASURED: all 4 runtime verbs returned EMPTY at exit 0 for every one of itok's OWN 4 sessions (1.6-5.9MB each) & for `/nope/nothing.jsonl` alike. B7's shape on the session path, & V88's `never skipped` never carried here (B14).
V105: **a §T row is LANDABLE ALONE -- its own commit leaves the gate GREEN & the repo HONEST.** A row that cannot land by itself is ⊥ a task, it is HALF of one, & the half that ships first provides FALSE ASSURANCE -- V69's defect one level up: the danger is ⊥ the missing half, it is that the present half READS as working. ∴ a REGISTRY & its CALLER are ONE row, a RULE & its CHECKER are ONE row (V69/V64 say one COMMIT ∴ a task spanning two commits was CUT WRONG). MEASURED: T42 shipped a `.context-policy` parser + 13 green tests that NOTHING read & `-D warnings` refused it as DEAD CODE ∴ the gate ALREADY enforces this & needs no new runner -- what was missing is asking the question when the ROW is WRITTEN, ⊥ when the build goes red. Proven by the gate on the task's OWN commit, ⊥ by a later one.
V106: **what the parser ACCEPTS & the renderer DISPLAYS, the transport ! PERFORM.** A scheme/flag/value the CLI takes & echoes back is a PROMISE ∴ if the build cannot honour it the only honest shapes are (a) make it work or (b) REJECT it at PARSE time w/ a usage error naming the missing capability — NEVER accept, display, then fail at the syscall (B16). The trap is a DEPENDENCY FEATURE FLAG: the surface compiles from one crate & the capability from another crate's cargo features ∴ NOTHING in the type system ties them, & the compiler cannot notice. A test that never exercises the path hides it ∴ a capability the SURFACE names ! have a test that EXERCISES it, or the surface ! decline it. Corollary for docs: an ABSENT mitigation is ⊥ a hardening property — listing it beside a real one (`forbid(unsafe_code)`) puts a weakness in the strengths column, & marking it out of scope tells a reporter ⊥ to tell you.
V107: **publication is a DISTRIBUTION decision, ⊥ a maturity rung.** V70 once ended `∴ the first public artifact is `0.7.0-rc.1``, welding WHO CAN INSTALL IT onto WHAT IT GUARANTEES. Two things that move independently, & fusing them left exactly two moves: wait for `0.7`, or misstate maturity to ship. Both bad, & the second is the one V39 already forbids (SemVer ! tell maturity TRUE). ∴ SPLIT: ship at whatever rung is TRUE, & let the number say what is ⊥ yet done — `0.3.0-rc.1` published w/ `0.4`'s telemetry OPEN says precisely that, & says it to every reader of the version string. The early-exposure ARGUMENT is unchanged & is why this is ⊥ a concession: V70 already justified `0.7` by public feedback, & that argument gets STRONGER the earlier it applies — real use is what finds the next defect, ⊥ another pass over our own tree (V80: the last two were found by a user & by a reader, ⊥ by the gate). `0.7` keeps its OWN meaning, featureset frozen: a promise about SCOPE, ⊥ about audience. PRECONDITION, ⊥ optional: publishing early means the PUBLIC-CLEAN rules bind NOW (V26 provenance · V39's four conditions) ∵ crates.io is immutable & a public history is ⊥ cheaply rewritten.
V110: **a rate whose PERIOD outruns its SAMPLE is an EXTRAPOLATION & wears the `~`.** `rate` divides the session total by its AGE & multiplies by the period ∴ a 1337-second session publishes `707m/d` — a figure no day will bill, printed BARE ∴ reading as MEASURED. RULE: `age < period` ⇒ the value carries `~`; `age >= period` ⇒ bare. This is V3's own tilde ("the `~` marks a CRUDE estimate") carried to the TIME axis, & V92's refusal to invent a denominator carried to one that EXISTS but is too SHORT to license the period asked of it — `calibrate` already refuses a factor under its `n` (V102) ∴ the rule is the repo's, ⊥ a new idea, & `rate` is the sibling it never reached (B11's class). json carries it STRUCTURALLY — `projected_hour`/`projected_day` booleans, ⊥ a tilde in a numeric field (V9). SCOPE: the tilde marks the PROJECTION only. It says NOTHING about the denominator being idle-diluted, which is a distinct defect over the same `age_seconds` (B25) — a badge can be honestly marked & still divide by the wrong number.
V111: **the rate's DENOMINATOR is ACTIVE time — every inter-turn gap CAPPED at 300s & summed — ⊥ the wall-clock span.** First & last stamp bound a span that counts SLEEP: MEASURED, a 2145-turn session spans 337.9h of which 11.2h · 17.2h · 28.3h is work at a 120s · 300s · 900s cap ∴ its span-derived `3m/h` understated the working rate ~20× & two weeks of nights read as throughput. `IDLE_CAP = 300s` is MEASURED, ⊥ picked: over 11 real transcripts (94-2145 turns) the inter-turn gap runs median 4-8s · p90 17-50s · p95 27-305s ∴ 300 sits AT | ABOVE the 95th percentile of EVERY session seen — it credits the gaps that ARE a turn & truncates only the tail where a human left. 900 buys the coffee break; 120 docks a legitimately slow turn (a build inside one tool call). The transcript carries NO per-turn duration (`durationMs` exists on attachments & hooks, NEVER on the assistant message w/ `usage`) ∴ capped gaps are the only measurement available, ∴ the cap is NAMED w/ its percentile here, ⊥ a bare `300` in the source no reader can audit (V3). BIAS, STATED ⊥ hidden: N turns yield N-1 gaps ∴ the first turn's tokens are billed w/ no time credited & the rate runs HIGH by ~1/N — worst where V110 already marks it. ZERO active time ⇒ the rates are ABSENT (`-` in the badge, `null` in json), ⊥ floored to a 1s denominator (B26) ∵ a fabricated divisor publishes `total × period` & V110's tilde cannot redeem digits nobody measured. json keeps BOTH clocks: `age_seconds` is the span, `active_seconds` is what DIVIDES, & V110's marks read the active one ∵ a period is covered by WORK, ⊥ by elapsed calendar.
V112: **an output that EXISTS is ⊥ an output that is CALLABLE — DEFINING a package & PUBLISHING one are two acts, & only the second is what the fleet consumes.** V62 ends at BUILT (`packages.*` green on 3 systems × 3 packages since T58) & the gate was honest about it — every one of those 9 jobs really compiles. What NOTHING checked is whether anyone else can GET the result: CI declared `pr0d1r2.cachix.org` as a SUBSTITUTER in two jobs & `grep cachix-action .github/` found ZERO ∴ CI was a pure CONSUMER of the fleet cache & the itok it built 9 times a run was thrown away. A store path nobody can substitute costs a consumer EXACTLY what no package costs: MEASURED THEN: microlith's `.context-limits` recorded a 23,200-token ceiling naming `itok` as its checker, the rule had had NO runner since it was written, had been raised 11 times unenforced & sat ~37% over — ⊥ ∵ the package was missing but ∵ gating on it meant building itok AND tiktoken from source to lint ONE file. SETTLED SINCE, & the outcome is the stronger evidence: microlith's T38 turned that into an `itok check` step in its own `hk.pkl` off the cached package, ceiling now 36,800 ∴ the consumer's path is proven by a CONSUMER WALKING IT. GENERALLY: any output the SPEC promises to a CONSUMER needs a runner proving the CONSUMER's path, ⊥ ours — `nix build` proves it compiles HERE & says nothing about the cost of calling it THERE (V80: our own tree is where this class hides).
V113: **the cache is a SPEEDUP & NEVER a gate, & its ARMING ORDER is load-bearing.** `cachix-action` installs a nix post-build-hook ∴ it pushes what is realised WHILE ARMED & ! precede `nix build`. Placed AFTER, it arms on a store that already holds everything & pushes NOTHING — silently, & GREEN. That is the failure that LOOKS like success (V71's class, on a cache): the wrong order costs no red ∴ only reading the step's semantics catches it, ⊥ the gate. The push is ARMED by a secret & ! DEGRADE without one ∵ a `pull_request` from a FORK gets NO secrets ∴ a hard-required push fails every outside contribution for a reason ⊥ about the contribution — `authToken` empty ⇒ substituter configured, push skipped, job GREEN. ∴ NOTHING in CI may depend on a push having happened: the 9 `nix build` jobs stay the VERDICT & the cache only changes how long they take. Corollary: a cache that can turn a build RED has made an OPTIMISATION into a correctness input, & then a cache outage is indistinguishable from a broken package.
V114: **badge cell 1 is a LEVEL & cells 2-4 are FLOWS; a level colored by an ABSOLUTE threshold is the WRONG INSTRUMENT.** `rate`'s first value is the last turn's billed input (`input + cache_creation + cache_read`) ∴ by V98 it is the WHOLE WINDOW on a warm turn — `headroom`'s `used`, wearing `rate`'s clothes. V109 colored it from `[rate].turn`, a FIXED token count, which sorts the same 963k into "fine" on a 1M window & "about to compact" on a 200k one ∴ the accent answered everything except the only question a level raises: HOW FULL. RULE: a level is colored against its CAPACITY, a flow against a rate. `[rate].turn` stays HONORED — a user who declared a line owns it — as the FALLBACK rung, ⊥ the instrument: measured compaction point (V116) > capacity (`--window` · `--model` · the payload's `model.id` · `.context-models`) > `[rate].turn` > no color. The capacity ladder is `headroom`'s, EXTRACTED & SHARED ⊥ copied (B4's two-copies class) ∵ two ladders drift & then the badge & `itok headroom` disagree about the same session, which is worse than either being wrong alone.
V115: **an ABSENT level renders NO color — a zero window ! paint bright GREEN.** V93 records a real turn reporting window 0, which a naive delta rendered as a -387,741 compaction that never happened; the SAME zero fed to a fill gauge reads as an EMPTY TANK ∴ the calmest green on the ramp, produced at the moment the measurement went MISSING. That is V47 (absent ⊥ zero) carried to the COLOR channel, & it is worse there than in a digit ∵ color is pre-attentive: nobody re-reads a green they already relaxed at. RULE: no window | no capacity | a ZERO window ⇒ the digits print UNCOLORED, exactly as V109 already answers a metric with no threshold. RAMP COROLLARY: hue alone ! carry the signal — green→red passes through yellow & a deuteranope reads one mush ∴ the top of the ramp earns a SECOND channel (V110's `~` is the badge's precedent for marking a value without spending a cell), ⊥ merely a redder red.
V116: **the auto-compact point is MEASURED from the harness's OWN record, ⊥ assumed as a fraction of the window.** The transcript writes `compactMetadata{trigger,preTokens,postTokens}` at every compaction ∴ the threshold is DATA sitting in a file itok already parses, ⊥ folklore. MEASURED over 88 transcripts, 6 auto compactions: the 200k tier fired at 167,028 & 167,171 (83.5%); the 1M tier at 968,887 · 1,000,217 · 1,000,418 · 1,001,217 (96.9-100.1%) ∴ NO single reserve fraction exists ACROSS tiers, & a 3.2% spread INSIDE the 1M tier says it is ⊥ constant even there. "Window minus 5%", the premise this task began with, is REJECTED as a default: it draws the red line ~36k EARLY on 1M & ~33k LATE on 200k — wrong in both directions, & the late one is the direction that costs a session its plan. SECOND measurement, & why the gauge ! claim exactness: `preTokens` exceeds itok's window for the SAME compaction by 516-3,441 (0.05-0.35%) ∵ it counts the turn that TRIPPED it, which the transcript has ⊥ billed yet ∴ itok's number is a slight UNDERCOUNT of the trigger metric & the gauge is an APPROACH indicator, ⊥ a countdown. RULES: read the point per MODEL from observed compactions; use the LOWEST `trigger:"auto"` `preTokens` seen ∵ it fires EARLIEST ∴ the safe direction (V108's overstate-the-cost logic, applied to a ceiling); report `n`; EXCLUDE `trigger:"manual"` ∵ a human compacting early says nothing about where the machine would have. No observation & no `[rate].compact` ⇒ fall to capacity (V114's ladder), ⊥ to an invented fraction (V92).
V117: **the badge's FLOWS measure GROWTH, ⊥ RE-BILLING — the two carry OPPOSITE signs.** MEASURED over 49 transcripts of 100+ turns: `cache_read` is 92.5-99.8% of billed input (median 98.3%) ∴ `total` is ≈ turns × mean occupancy & RISES with the turn count even when NOTHING new enters. Its `/h` & `/d` inherit that ∴ the published rate climbs FASTEST exactly when the window is fullest & real growth is slowest — the WRONG SIGN for a warning (B30). GROWTH is Σ of POSITIVE window deltas plus the first turn's window: MEASURED, growth/peak = 1.00 median (max 2.08, & only a COMPACTED session exceeds 1) ∴ it RECONSTRUCTS the occupancy it explains, & growth/billed = 0.20% overall. REJECTED as the growth axis: `input + cache_creation` ("what entered"), which overstates fill by 1.45-28.5x (median 3.60) ∵ a cache entry outliving its TTL is RE-CREATED & re-billed as fresh writing ∴ it measures cache TRAFFIC, ⊥ content — the plausible number wrong by a factor nobody would notice (V2). RULES: a ZERO-window turn is EXCLUDED from every delta (V93's phantom -387,741); a NEGATIVE delta is a compaction | an eviction ∴ DROPPED, ⊥ subtracted — growth is what ENTERED, & what LEFT is V116's business.
V118: **`/bill` is a BILL: ⊥ content, & ⊥ money.** `total` printed beside a 963k occupancy reads as "everything in this session" & is off by ~900x ∴ the cell is renamed to the quantity it actually holds, its number UNCHANGED — the fix for a mislabelled measurement is the LABEL, ⊥ the number (V2). What it is ⊥: MONEY. `cache_read` bills at a fraction of the base rate & `cache_creation` at a premium ∴ the money-equivalent runs ~10-15% of the figure, but those multipliers are VENDOR PRICE, ⊥ measurement — they change without notice, & `.context-models` already owns a RATE column for exactly that (V3). OUTPUT is counted NOWHERE by itok & is ⊥ small: 56,423-2,642,850 tokens per session (median 316,292, n=49), billed at a MULTIPLE of input ∴ named here as a KNOWN GAP, ⊥ left to look like zero (V44).
V119: **a published approximation's SAFE DIRECTION follows what it is FOR: a COST overstates, a DEADLINE understates.** V108 rounds a token count UP ∵ "at least this much flowed through" is honest for a flow & a floor would read as "only this much". A TIME REMAINING inverts it: rounding up hands the reader confidence they have ⊥ got, & the failure is SILENT — they start one more big read & the compaction lands mid-task. ∴ `~to compaction` FLOORS: 90 seconds publishes `~1m`, ⊥ `~2m`. Same rule, opposite direction, ∵ it was never about rounding — it is about which way a wrong number HURTS. REFUSALS (V92), & they are most of this feature: NO red line ⇒ NO estimate; ZERO active time | ZERO growth ⇒ NO estimate ∵ a context that is ⊥ filling has no arrival time & ∞ is ⊥ a number; used ≥ the red line ⇒ 0, ⊥ absent — the gauge is already pinned & "you are past it" is a MEASUREMENT, ⊥ a missing one. CLOCK: it divides growth per ACTIVE hour (V111) ∴ the answer is in ACTIVE seconds & the json key SAYS so (`compact_in_active_seconds`) — a wall-clock reading would sell a lunch break as headroom. The badge's 5th cell appears ONLY when the gauge does ∵ it ANNOTATES the gauge: with no red line there is nothing to be early for, & a permanent `-` in a statusline is a widget announcing its own silence (V71).
V120: **a gate's FILE SELECTOR is PART of the gate, & an EMPTY selection is a PASS.** `hk.pkl` declares `pre-push { steps = all }` & `flake.nix` installed `hk run pre-push --from-hook`, which selects STAGED files. At push time NOTHING is staged — committing is what emptied the index — ∴ the selection was EMPTY, every step carrying a `glob` was SKIPPED, & the hook exited 0. MEASURED on a real push: 15 steps ran (whitespace · line endings · BOM · symlinks · private-key · case · size · merge-conflict · links · typos · ripsecrets · package · package-suite) & every `**/*.rs` step — `fmt` · `clippy` · `test` · `doctest` · `itok` · `mth` · `mth-check` · `rustdoc` · `coverage` · `semver` · `ollama` · `no-default-features` — ran NONE (B32). The DECLARATION was true & the RUN was empty ∴ reading `hk.pkl` could never find it, & `docs/INTEGRATION.md`'s step count — which IS checked — counts DECLARED steps ∴ it was right while the gate was hollow. RULE, restated to what is ESTABLISHED (B33): a push-side gate is verified by its own REPORT — the range it names (`Fetching files between …`) & the per-step file counts — ⊥ by reading the config that configures it, ∵ the config was right & the run was empty. The MECHANISM B32 first recorded (`hk run` selects staged files) is RETRACTED: 5 probes refute it & the real cause is still unknown. GENERALLY: a step count is a claim about the DEFINITION; only a RUN's own report is a claim about what executed, & the two diverge silently (V113's shape, on the runner ⊥ the cache).
V121: **a threshold that differs per MODEL is KEYED by model, ⊥ by hope.** `[rate].compact` shipped as ONE number while V116's own measurement says the point it names is ⊥ one number: 167,028 & 167,171 on a 200k window against 968,887-1,001,217 on a 1M one, ~6x ACROSS tiers. A global scalar is therefore a LOADED GUN ∵ config WINS over the session's own record (T101's precedence): set from 1M observations it paints a 200k session GREEN all the way into a compaction — V115's forbidden failure exactly, arriving through the config file instead of through a zero. MEASURED consequence, ⊥ hypothetical: this machine's global `itok.toml` was retuned from 49 sessions & `compact` was left UNSET for precisely this reason ∴ every fresh session gets NO gauge, which is the feature failing safe & still failing. ∴ TWO forms, each obvious for its case: `compact = N` applies to EVERY model & fits a repo pinned to one; `[rate.compact]` keyed by the payload's `model.id` applies to the models it NAMES. RULE: an unlisted model gets NO opinion — ⊥ a nearest neighbour, ⊥ the first entry, ⊥ a mean — & falls through to the session's OWN observation (V116), which is the honest answer & the one that cannot go stale. A threshold guessed from a DIFFERENT model is V2 wearing a config file.
V122: **the precision ladder's tiers agree on DELTAS where they diverge on ABSOLUTES ∴ `--bpe` is licensed for COMPARISON, ⊥ for a count.** MEASURED: three renderings of ONE paragraph (English · 中文 · 文言) counted by `--bpe` (o200k, offline) & by `--ollama` (gpt-oss:20b, EXACT via `prompt_eval_count`) differ by a CONSTANT +67 — ollama's figure carries the chat template's framing — & every DELTA matches TO THE TOKEN: +6 & -17 on the trio, -75 on caveman's 10-prompt corpus (4,068 vs 1,844 chars). Subtracting the constant recovers the o200k numbers EXACTLY. ∴ "which of these two texts costs less" is answerable at the CHEAP rung, offline & with no fleet, while "how much will this cost" is ⊥ — V4's ladder stands & gains a USE for its bottom rung. SCOPE, stated ∵ it is the limit: gpt-oss is OpenAI-family ∴ this is CONFIRMATION inside one vocabulary lineage, ⊥ independence; `devstral-small-2` (Mistral) returned nothing at exit 0 & is UNMEASURED; no Claude tokenizer is public (§C). A SECOND FAMILY agreeing is what would make the ratio a property of the SCRIPTS ⊥ of one vocabulary, & until then every language figure here carries that caveat.
V123: **a RECURRING cost needs a RECURRING runner; a ceiling that can be RAISED is ⊥ one.** MEASURED here: `SPEC.md`'s ceiling has been raised TEN times & the file compacted TWICE, & the eighth, ninth & tenth raises each recorded the SAME intention in prose ("T49/T70 are DUE", "the next raise should be refused until one has run") w/ nothing to enforce it — a rule with no runner (V17's shape), & the same class as B28 (a format rule nothing ran), B31 (a §I flag nothing checked) & B32 (a gate whose selector emptied it). The ASYMMETRY is the mechanism, ⊥ anyone's discipline: raising is ONE line & compacting is a day ∴ the cheap move wins every time the ceiling fires, & the ceiling firing is precisely what puts the raise on the table. ∴ the debt becomes DATA — raises since the last measured reduction, per path — & a traveling guard (V31) caps it at what is ALREADY OWED ∴ the next raise FAILS until a reduction resets the count. RULES: a raise increments; a REDUCTION (the file's own tokens fell against the base) resets to 0; the cap only ever comes DOWN, as `.coverage` & `.context-limits` already do. DEGRADATION, ⊥ a silent skip: with no resolvable base the guard still enforces the CAP, ∵ a check that passes when it cannot look is B32 exactly.
V124: **a linter that reads a FILE is ⊥ an auditor that reads what the file can REACH.** `actionlint` type-checks the workflow — expression types, `run:` bodies via shellcheck, runner labels, cron, action inputs — & knows NOTHING about token scope. `zizmor` audits scope, credential persistence, injection of attacker-controlled context & unpinned `uses:` — & does NO syntax checking at all. ∴ neither SUBSTITUTES for the other, & the tempting economy (one workflow linter, ⊥ two) silently drops whichever half is ⊥ kept. MEASURED here: `actionlint` had been green on every commit for the life of `ci.yml`, & `zizmor` reported 9 findings on FIRST RUN at `--persona=pedantic` (B40) — ⊥ because `actionlint` was failing at its job, but because token scope was never in its job description. GENERALLY: two tools whose findings never overlap are ⊥ redundant, & "we already lint that file" is the sentence that hides the gap.
V125: **run the STRICTER setting & write down what you decline; an exemption with no EXIT is a rule nobody revisits.** `zizmor`'s `pedantic` persona reports code SMELLS — claims about how a file will AGE, ⊥ about what it does today — & this repo runs it as THE setting rather than the default `regular`. RATIONALE: conforming to the stricter reading is what produces the more pristine file, & the 4 findings pedantic added here were ⊥ style — 2 `run:` blocks had their source assembled AROUND an expression instead of reading a variable (safe only ∵ every input HAPPENED to be workflow-authored), & 2 jobs are anonymous ∵ a `name:` renames all 12 required status checks & strands `main` unmergeable (B40). ∴ the price of the stricter setting is a LEDGER — `.github/zizmor.yml` — & each entry carries (a) the finding is REAL, (b) WHY it is declined, (c) the CONDITION that retires it. VERIFIED line-scoped, ⊥ rule-wide: a THIRD anonymous job in the same file is still reported ∴ the entry suppresses an INSTANCE & the audit stays live — the failure mode of every ignore file is disabling the rule while appearing to excuse one case. GENERALLY: a suppression is a CLAIM like any other (V17) & decays like one; the exit condition is its runner.
V492: **a workspace helper duplicates the root deny list to stay detachable.** Cargo lint settings do not cascade into an extracted member, so `dev/` carries the same deny list locally; `publish=false` and release=false keep the helper out of consumers and releases.
## §T TASKS
| id | scope | tasks | done-when |
|----|-------|-------|-----------|
| M1 | offline core — estimate + report | T1-T4, T12 | `itok estimate`/`itok e` green on a real tree, json stable, `--budget` gates |
| M2 | full ladder + gate + extract | T5, T7-T11, T13-T24, T69, T78-T80, T85, T88 | `--bpe`/`--ollama`/`diff`/`check`/`doctor`/`log`/`fit` done, subtree-split rehearsed |
| M3 | publish — crates.io-ready, public CI | T25-T29, T52, T53, T107 | `cargo publish --dry-run` clean, public CI green, no origin-repo ref shipped, docs regenerate, `itok` installs |
| M4 | runtime introspection — read-only ledger (V41, V42) | T30-T38, T49, T72-T77, T86, T87 | `itok trace`/`itok top` green on itok's OWN sessions, accounted-vs-unaccounted stated, calibration factor + `n` reported, zero interception |
| M5 | reduction — the standalone pipe filter | T39-T41 | `cmd \| itok cap 10k` useful w/ no agent & no hook, every applied rung named in the footer, cut is resumable & deterministic |
| M6 | enforcement — policy · guard · fuse | T43-T46 | hook adapter decides from `.context-policy`, fuse graduated + always overridable, every trip/cap/override lands in the ledger |
| M9 | public exposure — ships as `0.3.0-rc.1` | T59 | repo public, `0.3.0-rc.1` published & installed from crates.io, then `0.3.0`; badges resolve |
| M10 | CI hardening — ships as `0.8.0` | T60 | matrix (linux + macos-arm) green over a streak, release automation, MSRV axis |
| M11 | closure — ships as `1.0.0` | T61 | public feedback folded; CLI surface + json contract frozen |
| M8 | local guardrails — ONE gate definition, run by hk | T50, T51, T54-T58, T62-T68, T70, T71, T90-T93, T98, T108, T110-T111 | `hk.pkl` is the only place an op is written; pre-commit/pre-push/CI all reach it; the suite is green run PARALLEL |
| M12 | correctness sweep -- one rule per PATH (B11) | T81-T84, T89, T105 | every rule carried to every sibling path; a gated flag names its feature; the fleet answers in parallel |
| M13 | live awareness — throughput badge | T94-T97, T100-T104, T106 | `itok rate` returns a pre-formatted string a statusline hook can display; `itok.toml` carries color thresholds; cell 1 reads as a FILL GAUGE against the MEASURED compaction point ∴ the badge names the first compaction before it lands |
| M14 | the fleet can CALL it -- a consumable package, ⊥ a dev shim | T99, T109, T112 | `nix build .#default` yields an `itok` binary, CI pushes it to the cache both repos already read, & a consumer flake pinning the `v0.3.2` tag (T112, flake declares `x86_64-darwin`) gates on `itok check` without building itok from source |
| M7 | runtime CI — replay & regression | T47, T48 | a recorded ledger replays deterministically offline ∴ policy A/B w/o an agent; a run over session budget fails CI |
T1|x|crate skeleton: standalone bin, Cargo.toml, MIT license, min deps|V13
T2|x|`estimate` dummy tier: bytes/4 + word proxy, du flags, tracked-by-default|V4,V8
T3|x|`--format json` stable output contract|V9
T4|x|prefix-inference + typo-suggest, read-only verbs only|V6
T5|x|`--bpe` tier: tiktoken, vendored vocab, deterministic|V4,V12
T7|x|`.context-models` table; unknown model ⇒ fail|V11
T8|x|`diff` verb: git arg-forms (`A B`/`A..B`/`--staged`/`-- path`) + `--exit-code`|V7,V2,V32,V33
T9|x|`check` verb: `.context-limits`, pinned bpe, exit codes|V5,V10
T10|x|dogfood: `itok` as host guard unit, pre-commit `itok check`|V14
T11|x|extraction dry-run: build & GUARD isolated, zero host deps, `subtree split` rehearsal|V13,V27,V37
T12|x|`--budget N` inline gate on estimate & diff: exit-on-breach, report overage|V16,V5
T13|x|`doctor` verb: advisory, native signals|V17,V18
T14|x|`.context-models` carries per-model window; `--window` override, shared unit parser|V18,V11
T15|x|`log` verb: per-commit token cost + delta across history, git grammar|V19,V32,V33
T16|x|`fit` verb: greedy subset under `--window`, pipeable path-list output|V20
T17|x|`--ollama` backend: exact via `prompt_eval_count`, live model/window discovery, feature-gated|V22,V23
T18|x|`--ollama` `host[:port]`-list + `.context-hosts` + stdin|V24,V25
T19|x|unit declaration|V28,V29
T20|x|pinned detachable toolchain: `flake.nix`+`flake.lock`+`.envrc`|V28,V62
T21|x|itok baselines at crates/itok/ root: `lexicon.txt`·`coverage-baseline.json` (`.file-limits` dropped by T57|V27,V69
T22|x|`gitref` primitive: token cost of a file AT a commit (`git cat-file` → dummy/bpe), shared by diff/show/log|V33
T23|x|`show` verb: one commit's per-file delta (default HEAD), `-- path`, `<commit>:<path>` blob|V32,V33
T24|x|cassette-replay the ollama backend: `vcr-cassette` dev-dep + ureq replay stub + fixtures|V38,V22,V23
T25|x|metadata: `Cargo.toml` version `0.8.0` + `repository`·`homepage`·`documentation`·`readme`·`keywords`·`categories`·`rust-version`, `exclude` non-consumer files|V39,V13
T26|x|public-clean provenance: scrub SPEC + src comments of origin-repo names & cross-repo invariant pointers (fold inline), header un-names the workspace, `exclude=[".uow"]`|V26,V39
T27|x|bare-rust `.github/workflows/ci.yml`: fmt·clippy·test·`--features ollama`·`llvm-cov --fail-under-lines 98`, `fetch-depth:0`, no nix/uow|V39,V31,V38
T28|x|assemble README = hand narrative + the `itok docs` reference block + badges|V39,V40,V15
T29|x|`itok docs` verb: ONE command registry (verb·synopsis·flags·exit) renders `--help` + a markdown reference|V40,V6,V9
T30|x|session reader module: harness-PLUGGABLE, defensive JSONL parse → load events; unknown fields ignored, malformed records skipped & COUNTED; torn tail tolerated; ⊥ writes to the transcript|V43,V45,V76
T30a|x|stable read: truncate at the last COMPLETE line + a content key over that prefix ∴ a torn tail ⊥ changes the answer; NO cache dir (measured 8ms, B8)|V77,V43
T30b|x|synthetic fixtures under `tests/fixtures/session/`|V43,V45,V76,V79
T30c|x|attachment load class: hook output / reminders / injected context counted beside tool results|V78,V44
T31|x|`trace` verb: 1 line/load event, chronological, `-n`·`--since`·`--reverse`·json|V46,V9,V59
T32|x|`top` verb: ranked occupancy, `-h`·`-s`·`--top N`, dup + stale columns, `-- <path>` per-path attribution (⊥ a `blame` verb)|V46,V59
T33|x|accounted-vs-unaccounted split; method label on every runtime number (`ledger(actual)` ≠ `ledger(bytes/4)`)|V44,V3
T34|x|cache columns read from `usage` (`cache_creation`/`cache_read`); fields absent ⇒ NO column, ⊥ a zero|V47
T35|.|fan-out rollup: ledger keyed by session, sidechain/subagent sessions rolled to parent, SUM reported|V60
T36|x|`calibrate` verb: factor + `n` reported, application opt-in & labelled. DELIVERED by T87 w/ a BETTER method (a 2-parameter fit, ⊥ single-load turns) ∴ closed here rather than left declaring a superseded mechanism as open work — a dead row reads as law (V28/V69)|V48,V4,V102
T37|x|DOGFOOD: run `trace`/`top`/`calibrate` over itok's OWN dev sessions; the measured waste (re-read, stale, cache-bust) sets M6's default thresholds, ⊥ guessed ones|V42,V15
T38|x|`--cost` rendering (V61): `.context-models` gains an optional 4th column `in/cr/cc` — three INTEGERS, per MILLION tokens, in whatever unit the FILE declares ∵ itok bundles no price list & names no currency (V61); `top --cost --model X` renders it. THREE rates ⊥ one, ∵ V61's own clause: cache-read bills at a fraction & cache-creation at a premium ∴ a single rate is a wrong number wearing a currency. Multiplied against the session's EXACT usage split (`input` · `cache_read` · `cache_creation` from the harness's own record), ⊥ against `top`'s ROWS: a row's tokens are `bytes/4` & its cache split is UNATTRIBUTABLE ∴ a per-row price would be a fiction with a decimal point (V3/V44). Integer arithmetic throughout & reported in the DECLARED unit — no float, no `$`, & the method named beside the number. `--model` is REQUIRED ∵ rates are per-model & `Turn` carries no model (adding one is a breaking change for a badge-shaped feature, T101's lesson); absent ⇒ NO money & the report says which absence, unknown ⇒ FAIL (V11)|V61,V11,V47,V3,V44
T39|x|`cap` verb: stdin→stdout token filter + ANNOUNCED elision footer (human/json) carrying a resume selector|V49,V51
T40|x|reduction ladder rungs `strip`·`dedup`·`elide`·`outline`: applied lossless→lossiest, stop at budget, applied rungs named in the footer; lossy rungs opt-in|V50
T41|x|`cap` determinism + resume round-trip tests: same input ⇒ same cut; footer selector actually continues (proptest the tail)|V51,V5
T43|x|the `.context-policy` PARSER **and** the `guard` adapter that reads it, ONE row (V105 -- ex-T42, folded per B15): per-glob & per-tool budgets · pins · fuse tiers, the V18 unit grammar, an unparsable row FAILS naming file+line+expected (V88), absent ⇒ NO enforcement (V53); hook JSON stdin → decision JSON stdout, ONE process per call, no daemon, harness mapping isolated to one module, decision in JSON ⊥ exit code|V52,V53,V57,V18,V88,V105
T44|.|fuse state machine: occupancy tiers observe→warn→cap→deny (deny NAMES a cheaper alternative) + sliding-window RATE fuse + sticky hysteresis + override hatch|V54
T45|.|pins honored absolutely — above every tier & above a tripped fuse|V56
T46|.|fuse telemetry: trip · cap · override are ledger events; `top` reports override-rate as the policy-quality signal|V55
T47|.|ledger REPLAY: recorded events × a policy, offline & deterministic ⇒ policy A/B with no agent & no network|V53,V5
T48|.|session-cost regression gate: a recorded run over its input-token budget fails CI (the `--budget` shape, on a session)|V53,V16
T49|x|SPEC compaction FIRST PASS + the machine to finish it: 25 done-`§T` rows trimmed to what+cites (method lives in the commit, V26), V62/V22/V70/V71/V31 destaled & tightened, `tests/spec_integrity.rs` guard, `.context-limits` turned into a RATCHET. MEASURED gross -2,781 chars; NET -2.1% only ∵ the pass itself added V88+B7+T69. 5 of 86 invariants touched ∴ the BULK is T70|V84,V15,V26
T50|x|flake to repo ROOT (`git mv` out of the unit dir) + dev shell PROVIDES `itok` via a `cargo run` shim|V62,V15,V39
T51|x|drop the unit declaration from the standalone repo|V28,V29,V31
T52|x|`.gitignore` (`/target`, `/.direnv`): cargo packages untracked-not-ignored files ∴ `.direnv/` (5.5MB of vendored nixpkgs source) was landing in `cargo package --list` ⇒ would ship in the `.crate`|V39,V13
T53|x|track `Cargo.lock`: a BIN crate pins its own deps, & nix flakes read git-TRACKED files only ∴ an untracked lock is invisible to a `packages.default` build|V62,V39
T54|x|adopt hk as the gate runner: vendor `pkl/Config.pkl` (⊥ `package://`), `hk.pkl` w/ fast set + `all` amending it, `depends` chain over the cargo steps, `stash = "git"` on pre-commit, dev shell provides hk pinned to the vendored schema's version|V64,V66,V67
T55|x|`ci.yml` = orchestration ONLY, delegating to `hk check --all --check`|V64,V65
T56|x|fix the cassette stub's request drain (B5): read to `Content-Length` before replying, `Connection: close`|V68,V38
T57|x|drop `.file-limits`: no standalone runner reads it ∴ hand-maintained ceilings gating nothing|V69,V28
T58|x|`packages.default`/`itok-minimal`/`itok-ollama` via `buildRustPackage`+`cargoLock.lockFile`|V62,V23
T59|x|public exposure: create the GitHub repo, publish `0.3.0-rc.1` FIRST (immutability -- prove the pipeline before spending a permanent number), install it from crates.io, then `0.3.0`. Brought FORWARD from `0.7`: the tool is operable & real use is what finds the next bugs (V70). RELEASE RUNNER: `cargo-release` + `release.toml`, ⊥ a script -- clean tree, allowed branch, tag scheme, dry-run-by-default, verify, publish, push are ALREADY its job ∴ a second implementation of one rule set is V64s defect. `0.3.0-rc.1` went out BY HAND from prose: 8 commands whose ORDER was remembered ⊥ enforced (V17). The BUMP stays in a PR ∵ `main` needs 12 checks; only the tail (`hook`/`tag`/`publish`/`push`) runs from `main`. `hook` FIRST is load-bearing: `tag`/`publish`/`push` do ⊥ run `pre-release-hook` ∴ starting at `tag` ships whatever the tree holds. From microlith (V84). CLOSED at `0.3.0`: the rc PROVED the pipeline by FAILING in 5 places no dry run reached -- B17 (15 tests red on the published .crate ∵ `--verify` only COMPILES), B18, B19, B20, B21 -- & B17+B18 would have been PERMANENT in a non-pre-release. Each has a runner now ∴ the suffix is spent, ⊥ merely dropped|V70,V39,V64,V17,V84
T60|x|CI hardening for `0.8.0`. Caches (nix store + cargo) keyed on `runner.arch` ∵ `ubuntu-latest` & `ubuntu-24.04-arm` BOTH report `Linux` ∴ one key, two closures, mutual eviction -- fixed BEFORE the matrix ⊥ debugged after. PLATFORM MATRIX: one runner per system `flake.nix` declares (x86_64-linux · aarch64-linux · aarch64-darwin) × 3 packages for `nix build` = 12 concurrent jobs. A matrix REPLICATES the gate, ⊥ divides it: each runner pays the whole cost ∴ wall clock ~flat, compute ×3 -- what it buys is coverage where USERS are, & this repo already shipped 2 defects invisible from one vantage point (B18 · B20). MSRV axis DROPPED as vacuous, ⊥ deferred: an MSRV job can only fail when the declared minimum is BELOW the toolchain CI runs, & `rust-version` == the `flake.lock` pin (1.95 since the 26.05 lock) ∴ it would recompile the identical toolchain for an identical answer (V10). Reopens if the minimum ever drops below the pin. `timeout-minutes` went in as a DIAGNOSTIC & earned it within the hour: fired at 45m16s & produced the log identifying B21. Actions SHA-PINNED (a tag is MUTABLE ∴ whoever owns the action owns every workflow trusting it) + `workflow_dispatch`, both propagated from microlith (V84). The caches are a MODEST win & this record says so ∵ its first version did ⊥: CI was never SLOW -- MEASURED cold, the dev shell materialises in 26s & the gate reaches its first test in 79s. Release automation stays with T59|V70,V39,V64,V75,V84,V10
T61|.|closure: fold public feedback, freeze the CLI surface & the json contract, `1.0.0`|V70,V9
T62|x|gate UX: silent on success (`HK_HIDE_WHEN_DONE`), explicit `fail_fast` locally & `--no-fail-fast` in CI, per-step remediation hints on the non-obvious failures, `AGENTS.md` playbook + CONTRIBUTING pointer|V71,V65
T63|x|external-tool lints: `typos`·`actionlint`·`zizmor`·`taplo`·`shellcheck` pinned in the dev shell + at pinned versions in CI|V72,V73
T64|x|dev shell installs hooks on entry, written BY HAND w/ a runner-missing guard (B6), skipped when a global install exists ∵ git aggregates `hook.*.command` across scopes ⇒ double fire|V71,V74
T65|x|`packages.*` src narrowed via `lib.fileset` to `src/`+`Cargo.toml`+`Cargo.lock` ∴ a doc edit no longer invalidates the build|V62
T66|x|CI = nix: `nix develop --command hk check` + `nix build` of all 3 feature configurations|V75,V64
T67|x|`nixfmt --check` gates `*.nix`: the flake decides what every other step runs with ∴ drift there is drift everywhere. CHECK mode only|V72
T68|x|transcript guards BEFORE the capability: `.gitignore` transcript patterns (fixtures exempt) + a CONTENT-signature hygiene test (a rename defeats a filename pattern|V45,V71
T69|x|`.context-limits`/`.context-models`/`.context-policy`: an unparsable row FAILS w/ file+line+expected, ⊥ silent skip (B7); fractional units (`20.5k`) either parse or are rejected LOUDLY|V88,V11
T70|x|scripted bulk compaction: CPU derives (sizes·citation graph·orphans·stale refs·shared n-grams·must-keep fact sets), ONE inference call rewrites the top-N under a byte budget, CPU VERIFIES every citation/number/identifier survived, named `--allow-drop` for deliberate removals. Seeded by T49's measurements|V84,V73,V80
T71|x|concurrency guard: a test that runs N itok processes at once over the same tree & asserts identical output + zero writes outside `target/`; keeps V89's free property from being lost silently|V89
T72|x|`headroom` verb: `df` columns (window·used·avail·use%) + the rate triple (10/50/200 turns) + `~turns left`; `-h`·`--model`·`--window`·json; zero-window turns excluded from the rate|V91,V92,V93
T73|x|report cold-cache events: a turn whose cache WRITE dwarfs its read is a prefix re-write; name the cost (~250x a normal turn) & leave the cause to the reader. Observation only -- ⊥ a fuse input (V95)|V94,V95,V47
T74|x|session identity: prefer an explicit harness-provided session id over newest-by-mtime; when falling back, SAY so. Two sessions in one project currently resolve to whichever was touched last|V96,V3
T75|x|`top`: add the `size × turns-remaining` column (V98) & state the uncompacted caveat; it is the number that makes early reduction's leverage visible|V98,V94,V59
T76|x|`doctor --session [<id>]`: retarget doctor at a CONTEXT — progression (use% · rate triple · `~turns left`, from T72) + per-item `projected` (T75's carried, forward); paths w/ `--session` = usage error, ⊥ a silent ignore. AFTER T72: no progression number without `headroom`|V99,V100,V17
T77|x|the advice block: V97's two levers ONLY, mid-session eviction NAMED as a trap, no third suggestion; fires only when a level is CROSSED; a test asserts the forbidden advice is absent|V99,V97,V71
T78|x|`--ollama=HOSTS`, & the `=` form generally for optional-value flags ∴ the documented bare `host` becomes reachable; heuristic kept as convenience; tests pin a BARE host & a bare IP|V101,V24,V25
T79|x|remote-tier method label names the ENDPOINT (`exact via HOST`) ∴ a count from an unintended tokenizer is VISIBLE; needs `Method.label` to carry an owned endpoint, ⊥ a `&'static str`|V101,V3,V22
T80|x|`--model` narrowing over an `--ollama` fleet: enumerate ONCE, then exact > `:latest` > unique prefix; ambiguous & not-found errors NAME the candidates. Reuses `fleet_all`'s enumeration, ⊥ a second fetch|V6,V22,V71
T81|x|carry `--model` resolution to `estimate --ollama` (B11a): ONE resolver shared w/ `discover`, ⊥ a second copy|V6,V64
T82|x|name the SKIPPED fleet hosts (B11b): report answered-vs-named ∴ a partial union ⊥ reads as whole, & `no fleet host serves X` says how many answered|V44
T83|x|a DIRECTORY arg is REFUSED w/ its reason, ⊥ counted as 0 (B11d); `fit` never emits an unmeasured path|V47,V8
T84|x|a feature-gated flag is KNOWN, ⊥ unknown (B11e): the diagnostic names the FEATURE + how to get it, & the docs registry marks gated tiers ∴ `--help` ⊥ advertises what this build lacks|V71,V23,V40
T85|x|`--model` comma-list per the §I clause|V6,V24
T86|x|`headroom --task N` -> `tasks left`; arithmetic only|V91,V93,V59
T87|x|`total` estimator per V102: fit fixed-overhead + scale from transcript deltas, report band + `n`, refuse a verdict inside the band; SUPERSEDES T36's clean-sample factor|V102,V48,V44
T88|.|`partition`: pack a fileset into N bins under `--window`, coupling graph read from STDIN (⊥ derived here — V24's compose-don't-scan), cut-set REPORTED loudly (V81); synthetic fixtures w/ KNOWN size+coupling ∵ real code gives no ground truth. Reopens V20's DECLINED `pack` scope (⊥ V21's knapsack trigger — a different problem): itok itself needs ~3 bins at a realistic 48k budget, & fan-out is one of only 2 cheap levers|V20,V60,V97
T89|x|`--ollama` fleet probed in PARALLEL: one `std::thread` per host (⊥ an async runtime, V23; the host list is explicit ∴ no pool, V24), results merged in FLEET ORDER so list-order precedence & determinism are unchanged (V5). MEASURED: one dead host cost +3.05s serially (4.07s vs 1.02s on this fleet). Cost accepted: a model on 2 hosts is now probed twice ∵ per-host INDEPENDENCE is what makes them parallelizable. Per-model `/api/show` stays serial -- separable, measure first|V89,V5,V23,V24
T90|x|`cavekit-spec` as a dev-time FORMAT check, every violation CLEARED (0 today, 92 before B12 -- the count is the point). SUPERSEDED by T92: mth replaced it & the host bin is gone|V13,V31,V74,V79
T91|x|one line per statement + the 1650 cap, ported into `tests/spec_integrity.rs` in the SAME commit as the rewrite (V69), each proven by planting a violation (V79). SUPERSEDED by T92: rules & guards live in `mth` now, & `V103` (which stated them here) is retired|V14,V69,V79
T92|x|`mth` (binary from [microlith](https://github.com/pr0d1r2/microlith)) owns this spec's FORMAT: pinned flake input at a tag, dev-shell wrapper dispatches to the pinned binary or a local `MICROLITH_MANIFEST` override for development. Two hk steps split fmt-vs-structure, `.spec-records` as the V83 baseline, & `tests/spec_integrity.rs` DELETED (400 lines, the ported second copy). HARD-fails absent the binary (V69, ⊥ V74: nothing else reads this structure now). MEASURED: the ported copy sorted §T & never looked at §B ∴ 4 out-of-order rows sat under a green gate until the owner was asked|V14,V31,V64,V69,V39
T93|x|`tests/spec_compact.rs` loses its DERIVATION half to `mth derive` (sizes · citation graph · orphans), w/ the 3 units that tested it. KEPT: `must_keep`/`lost`, the compaction VERIFIER -- `did a rewrite silently drop a fact` is a claim about TWO texts, ⊥ a format rule ∴ it belongs to whoever rewrites. Kept as a printed CAVEAT, ⊥ a filter: V80-V87 are WORKING principles ∴ uncited is NORMAL there & a bare orphan list recommends cutting exactly the invariants that govern the work|V64,V83
T94|x|`rate` verb + `itok.toml` config: pre-formatted throughput string (`last_turn,total/total,rate/h,rate/d`) w/ `shorten()` ceiling (V108); `--color auto\|always\|never` reads `[rate]` thresholds from `itok.toml` (V109) for per-metric ANSI; `--format json` returns `{last_turn,total,per_hour,per_day,turns,age_seconds}`; 0–1 turns = empty output; `Verb::Rate` added to dispatch behind `session` feature; `basic-toml` + `serde` deps (optional w/ session); per-hour/per-day derived from wall-clock session age (`first_turn.ts` to `last_turn.ts`); per-turn billed input = `input + cache_creation + cache_read` from `Turn`; session resolved via `session_at()` pattern. Statusline hook is EXTERNAL (nix-config), ⊥ shipped w/ crate|V108,V109,V5,V59,V9,V3,V46
T95|x|`rate --statusline`: the harness statusline payload on STDIN → `transcript_path` + `cwd`, so the badge names the session the statusline BELONGS to ⊥ infers it (9 transcripts share this repo's dir ∴ V96's newest-by-mtime shows a CONCURRENT session's numbers in both badges). Mapping goes in `hook.rs`, the ONE module that knows a harness (V52) — a shell wrapper reading `transcript_path` w/ `jq` is a SECOND mapping, untested & outside the crate, & adds an unmanaged binary dep invisible to every gate. Payload read via the EXISTING hand-rolled `hook::string_field` ∴ ZERO new deps. Stdin touched ONLY under the flag (the `cli::Input` closure exists for exactly this) ∴ bare `rate` never blocks on a terminal. Emits `(itok:…)`; color defaults to `always` ∵ the harness captures stdout ∴ no tty. A named-but-unreadable transcript stays exit 2 per V104 — stdout is empty ∴ the statusline renders nothing & the diagnostic is on stderr|V52,V104,V96,V64
T96|x|`rate` marks projection per V110: `/h` & `/d` carry `~` when `age_seconds` is under the period (3600/86400), bare when it covers it; json grows `projected_hour`/`projected_day` ⊥ a tilde in a number (V9). Tilde sits INSIDE the colored span ∴ a marked value keeps its threshold color (V109). `shorten()` untouched — the mark is about the DENOMINATOR's reach, ⊥ the digits (V108). Fixture ages pinned either side of each boundary (3599/3600, 86399/86400) ∵ B24's lesson: the fixture ! be cut to the parser's convenience|V110,V3,V9,V108,V109
T97|x|`rate` divides by ACTIVE time per V111: `active_seconds` = Σ of inter-turn gaps each capped at `IDLE_CAP` (300s), replacing the first-to-last span as the denominator for `/h` · `/d` & as what V110's marks measure. `age_seconds` STAYS in json beside it ∴ a reader sees the two clocks apart. MEASURED on the badge that started it: `3m/h` → `57m/h` & `/d` correctly gains the `~` (17.2h of work does ⊥ cover a day)|V111,V110,V5
T98|x|edition 2021 → 2024, MSRV STAYS 1.95: fleet standard, & the two halves fit — nixos 26.05 carries rustc 1.95.0 & the edition needs only 1.85 ∴ the MSRV is the binding constraint & the edition costs NO reach. `std::env::set_var` is `unsafe` from 2024 on & `unsafe_code = "forbid"` is ⊥ negotiable ∴ `resolve_session`'s two AMBIENT inputs (HOME + the harness-offered id) are passed IN to a new `resolve_with` seam, & the two `tracecmd` tests hand it the tree they planted ⊥ write the process env. The lint asked the RIGHT question: a process-wide mutation to answer a question about ONE call is unsound under a parallel runner in ANY edition (B3). Edition badge REGENERATED from Cargo.toml ∴ the number is read, ⊥ written twice (V59)|V13,V79,V59,V64
T99|x|PUBLISH `packages.default`, ∵ a tool the fleet GATES on ! be CALLABLE without building it. THE ROW WAS DRAFTED WRONG & the correction is the finding: `packages.default` was ALREADY defined (V62/T58) & CI ALREADY built 3 packages × 3 systems ∴ the EXPOSE half was done BEFORE this row existed, & the draft read the flake's STALE comment (`needs Cargo.lock committed -- not wired yet`) as the state of the world when the lock has been committed all along. The ONLY missing half was the PUBLISH: `grep cachix-action .github/` found NOTHING ∴ CI DECLARED `pr0d1r2.cachix.org` as a substituter in 2 jobs & never WROTE to it, & the itok it built 9 times a run was DISCARDED. MEASURED cost of that: microlith's `.context-limits` records a 23,200-token ceiling naming `itok` as its checker, NO runner since written, RAISED 11 times unenforced, ~37% over today -- ∵ gating on itok meant building itok AND tiktoken from source to lint ONE file. FIX: `cachix/cachix-action` armed BEFORE `nix build` in the `nix-build` matrix (V113's order), `authToken` from a secret ∴ a fork PR degrades to substituter-only, + the stale flake note deleted. ⊥ REPLACING the shim: the lock-out argument is UNCHANGED (V62) ∴ 2nd output, ⊥ a swap. V105's checker is the `nix build .#default` matrix, which already existed|V4,V13,V62,V105,V112,V113
T100|x|`rate` colors cell 1 as a FILL GAUGE (V114): the capacity ladder EXTRACTED from `headroom` into a shared resolver, & `model.id` picked up from the statusline payload — a field `hook::statusline` had been DROPPING though its own test fixture already carried it ∴ the badge now names the model of the session it belongs to, which is T95's argument one field further. Ramp is INTEGER HSL at S=100 / L=50 over hue 120→0 ∴ only 2 of 6 sectors ever compute & no float enters a deterministic output; a `sqrt` gamma holds green through the flat half & dives over the last fifth ∵ a linear ramp spends its resolution where nothing is at stake. Truecolor `\x1b[38;2;R;G;Bm` behind `COLORTERM`, else V109's 3 buckets cut from the SAME fill fraction ⊥ from `[rate].turn`|V114,V115,V109,V108
T101|x|the gauge's red line is READ, ⊥ guessed (V116): the SESSION's OWN `compactMetadata` records, parsed beside `usage` ∴ ZERO extra IO on a path that runs EVERY turn; the lowest `trigger:"auto"` `preTokens` wins, `[rate].compact` in `itok.toml` overrides it, & json carries `compact_at` + `compact_n` ∴ a consumer sees the point AND how many observations back it. REJECTED: sweeping the project dir for OTHER sessions' compactions -- 22MB here against the 0.75MB transcript the badge already reads ∴ ~30x the render cost, EVERY turn, to answer a question a compacted session answers for free & a fresh one answers with V114's capacity rung. Threshold & consumer land in ONE row ∵ a parser nothing colors is B15's defect exactly|V116,V114,V69,V9
T102|x|`top` & `docs` stop asserting compaction is UNOBSERVED (B29): the caveat becomes CONDITIONAL on the session's own record — a transcript carrying a `compactMetadata` gets `carried`/`projected` labelled UPPER BOUNDS & the compaction's timestamp named, one with none keeps today's wording. The detector is T101's parser ∴ this row is text + a branch, ⊥ new machinery, & it is separate ∵ it changes what a DIFFERENT verb claims|V98,V100,V116,V3
T103|x|`rate`'s flows become GROWTH (V117): the numerator for `/h` & `/d` is Σ of POSITIVE window deltas (zero-window turns excluded, negative deltas dropped), ⊥ `billed_input`; cell 2 is RENAMED `/bill` w/ its number unchanged. V110's tildes & V111's active clock are UNTOUCHED — this changes the NUMERATOR, ⊥ the denominator or the marks. json keeps every existing key at its existing meaning (V9) & GAINS `growth`, `growth_per_hour`, `growth_per_day`, `entered`, `cache_read`, `output` ∴ the three quantities a reader keeps confusing are visible APART, & `total` stays what it always was. `Session` needs NO new field: `fresh_input`/`cache_written`/`cache_read` already exist & `output` is one `total_of` call ∴ nothing here costs a version rung (V39, T101's lesson)|V117,V118,V9,V110,V111,V39
T104|x|`~to compaction`: `(red line - used) / growth per active hour`, the number the gauge (V116) & the growth rate (V117) together make derivable. FLOORED per V119 & tilde'd as an extrapolation ON an extrapolation (V93/V3). Rendered as a 5th badge cell ONLY when a red line resolved, ∴ the badge is 4 cells wide on a session nothing can size; json carries `compact_in_active_seconds` ALWAYS, `null` where the refusals apply (V9). Duration formatting is its OWN unit ladder (`s`/`m`/`h`/`d`, floored) ⊥ `shorten()`, which ceilings ∵ it publishes token counts (V108) — one function rounding both ways by argument is how a direction rule gets lost|V119,V116,V117,V93,V92,V9,V3
T105|x|`§I` flag-coverage guard: extract every flag `§I` names per verb, ask the BINARY, & fail BOTH ways — a flag `§I` promises that the build refuses (B31, & `cap`/`headroom --task` only escape by a hand-written marker), & a flag the build accepts that `§I` never names (the reverse gap, which nothing has ever looked for). Traveling guard in `tests/` ∵ itok ! depend on a host crate (V13/V31). The marker text is the ESCAPE HATCH & stays: a row saying PLANNED is a promise dated, ⊥ broken|V106,V31,V80,V13
T106|x|`[rate].compact` gains a PER-MODEL form (V121): `compact = N` keeps meaning every model, `[rate.compact]` keyed by `model.id` means only the models it names, & an unlisted one falls through to the session's own record ⊥ to a neighbour's number. ONE untagged enum over `u64 \| table`, PROVEN against `basic-toml` before the row was written (V106's lesson: probe the parser, ⊥ assume it) ∴ ZERO new deps — `BTreeMap` is `std` & `serde`'s untagged path works ∵ TOML is self-describing. `red_line` already holds `raw.model` from the statusline payload (T100) ∴ the lookup needs no new plumbing|V121,V116,V115,V109,V9
T107|x|`docs.rs` splits `blurb` (ONE line, what `--help` prints) from `reference` (the paragraph `docs`/README print), & the reference is CUT where it recites §V in prose ∵ the invariant already has a home (V64). MEASURED entry cost: `--help` is 2,570 itok & `rate`'s blurb alone is 3,977 chars of it (~39%) ∴ the tool that bills entry cost charges an agent ~2.5k tokens to read its own help; the struct doc says "one-line blurb" & the module doc calls `usage()` terse, & both are false. Target ~600. REJECTED, both with measurements ∵ each is the plausible move: (a) EXTRACTING the prose to `docs/commands/*.md` + `include_str!` — NOTHING measured shrinks, `must-package` grows by 14 files & B17 is what one missing file costs, & B8 already records this exact shape (a structural change bought by MY editing annoyance); (b) a SECOND LANGUAGE — 文言 is ~18% cheaper than English on pure prose & modern Chinese ~6% DEARER (V122), while ~⅓ of a blurb is ASCII identifiers costing the same in any script, & a translation NO runner can check against the binary goes stale as a silent lie (V2)|V122,V64,V71,V40,V9
T108|x|`.context-ratchet` & the guard that reads it: raises-since-the-last-reduction per registered path, capped at what is already owed (`SPEC.md 8`, `README.md 0` ∵ T107 LOWERED that ceiling — the first reduction this repo records). A SEPARATE file ⊥ a third column in `.context-limits` ∵ B7: that parser SKIPS a row it cannot read & a silently skipped ceiling gates nothing, so widening its shape risks the gate to save a file. Guard sits in `tests/spec_compact.rs` beside the pipe counter, reading the same `ITOK_BASE`/`origin/main` baseline its neighbours do (V31): a raise without an increment FAILS, an increment past the cap FAILS, a reduction resets. Registry & caller in ONE commit (V69) ∵ a counter nothing reads is B15's defect|V123,V31,V69,V42
T109|x|`glob::matches` & `estimate::select_paths` become PUBLIC (#41): consumers had reimplemented both, slightly differently, which is the drift ONE definition exists to prevent (V64). ADDITIVE ∴ a 0.x minor-compatible surface change, & `semver` must pass. Semantics are DOCUMENTED at the item, ⊥ implied: `matches` is the THREE WILDCARDS only (`?` · `*` within a segment · `**` across) & ⊥ gitignore's surface rules — `*.md` matches `README.md` & ⊥ `docs/guide.md`, & a leading `/` or trailing `/` is ⊥ special; `select_paths` is V8's selection — empty ⇒ git-tracked set, explicit paths reach untracked files, each must `stat` (a missing or unstat-able path errs naming it & the OS reason), a directory errs (flat fileset). `walk::bytes` losing the OS error is a SEPARATE issue|V64,V8,V57
T110|x|`dev/` is the unpublished `itok-dev` workspace member: its library owns pure `&str` parsers/renderers and its thin binary owns filesystem/command boundaries; `readme --check\|--fix` and the all-jobs aliases return 0 clean, 1 stale/violation, 2 usage. README markers are whole-line, unique and ordered; each generated value is read from its owner; coverage is truncated to one decimal; runners come from `.github/workflows/ci.yml`; dependency keys begin at the key line; lock nodes match the exact `"name": {` header; scoped hk inputs are the declared union and the all job is `**/*`. The crate duplicates the root deny list to preserve root detachability (V492); `publish=false` and release=false keep it out of consumers and releases|V13,V27,V31,V64,V492
T111|x|adopt characterminator with a reviewed `.ctrm` and `.ctrm-sets`: Markdown keeps only the two deliberate mathematical symbols in `spec-math` plus the existing `zh` preset, while `ctrm fix` owns typographic rewrites. `ctrm check` is not yet a gate because the binary is not supplied by the pinned flake/CI toolchain; revisit when it can be pinned there rather than making local installation part of the verdict|V17,V31,V64,V72
T112|.|release `0.3.2`: tag the commit whose flake declares `x86_64-darwin`, so a consumer pinning a tag stops building itok from source on an Intel Mac (M14's done-when). PATCH ∵ `cargo semver-checks` vs `v0.3.1` = no semver update required & `0.4`'s rung is still open (`T35`) ∴ the fix band (V70); `main` carried an untagged `0.8.0` that skips three open rungs, & this walks it back before crates.io makes it permanent. Bump + CHANGELOG in the PR; publish = owner: the tail from `main` per `release.toml` (`hook` first)|V70,V112,V64
## §B BUGS
id|date|cause|fix
B1|2026-07-24|extraction: `rustfmt.toml`/`clippy.toml` root-only ⇒ standalone `cargo fmt --check` reformats (default width 100 vs 80); traveling gate ⊥ reproduces verdict|V27
B2|2026-07-24|extraction: git-command tests use `CARGO_MANIFEST_DIR.parent().parent()` as repo root + hardcode `crates/itok/…` paths ⇒ standalone `cargo nextest` fails|V37
B3|2026-07-24|`diff --budget` test asserted a breach on live `HEAD~1..HEAD`, presuming a substantial last commit; a near-zero-delta ceiling bump as HEAD gave no breach ⇒ exit 0 ≠ 1, blocking every commit until HEAD grew|V37
B4|2026-07-25|ci.yml `--fail-under-lines 99` copied the monorepo WORKSPACE total; itok ALONE is 98.03% (siblings inflate the aggregate) ⇒ the standalone gate fails coverage. Caught by the T359 proving ground. Floor set to itok's own 98|V31
B5|2026-07-25|cassette replay stub read the request with ONE `read()`; TCP segments the only POST (`/api/generate`) so the body can arrive second ⇒ reply-then-close raced the client's write ⇒ `itok: ollama read ...: Invalid argument (os error 22)`. Flaky 2/3 runs parallel, 3/3 green serial ∴ the deleted unit declaration's `--test-threads=1` had been MASKING it, & the claim that the suite was hermetic (argued from reading temp-dir/port handling) was wrong. Surfaced the first time the new gate ran the ollama axis|V68
B6|2026-07-25|dev-shell auto-install wrote `hk install`'s command, which assumes `hk` on PATH. Outside the shell: `hk: command not found` ⇒ hook exit nonzero ⇒ EVERY git commit in the repo blocked, ⊥ merely ungated. Caught within one minute, by the very next commit failing|V74
B7|2026-07-26|`.context-limits` silently SKIPS a row whose limit it cannot parse: `SPEC.md 20.5k` ⇒ `checked:1` of 2 registered paths, exit 0, NO diagnostic ∴ the ratchet set by T49 gated NOTHING & read as if it did. V11 already forbids exactly this for `.context-models` (unknown model ⇒ FAIL, ⊥ silent fallback); the rule was never carried to the sibling registry. Found by TESTING the new ceiling instead of trusting it (V80)|V88
B8|2026-07-26|SPEC defect, mine: V77 specced an on-disk snapshot cache w/o EVER measuring the cost it was meant to avoid. Measured after: 2.7MB parses in 8ms ∴ the cache bought 8ms & would have cost itok its first user-level state + a cross-platform cache-dir question + invalidation + pruning. Generalized MY workflow annoyance into the tool's runtime. KISS is invariant-level now, ⊥ a preference|V77,V87
B9|2026-07-26|the §T milestone `tasks` column DELETED as a drifting duplicate (measured 25 orphans of 79 rows, stale since T50) — B4's two-copies cause, third instance ∴ eliminated ⊥ policed (V64). REVERSED by B12: the premise "no runner reads it" was FALSE|V64,V69,V84
B10|2026-07-26|`--ollama <bare-host>` SILENTLY ignored: the optional-value heuristic (`src/args.rs`) takes the next token only when it holds `,` \| `:` \| is `-` ∴ `--ollama 192.0.2.10` left the tier bare (⇒ localhost) & swallowed the IP as a PATH — the one form §I documents (`[scheme://]host[:port]`, default `11434`) was the one unreachable. Silent ∴ a different model on localhost would have given a confident `(exact)` count from the wrong tokenizer. Tests pinned `box1,box2` & `SPEC.md` only; a bare host is genuinely ambiguous w/ a path, which is why the heuristic exists & why the gap was invisible. Found by a USER, ⊥ the suite (V80)|V101
B11|2026-07-26|FIVE sites where an EXISTING invariant was never carried to a sibling path -- B7's shape, & w/ B1·B4·B7 the repo's DOMINANT defect class: (a) `--model` prefix resolution landed in `discover.rs` only ∴ `estimate --ollama --model gpt-oss` 404s while `doctor` resolves it (V6; T80, mine & incomplete); (b) a DOWN fleet host skipped w/ byte-identical output ∴ a partial union reads as whole (V44); (c) `(exact)` named no ENDPOINT ∴ a count from an unintended tokenizer was invisible on SUCCESS (V101 = T79); (d) a DIRECTORY arg counted as 0 itok ∴ `fit --window 40k src` emitted `src` as fitting (V47); (e) a feature-gated flag reported `unknown flag` while `--help` advertised it, though `session` names its feature (V71/V23). ZERO new invariants needed ∴ the gap is PROPAGATION & V84 is the rule ignored. All five found by USING the tool in one session|V84,V6,V44,V47,V71
B12|2026-07-26|SPEC defect, mine & CONFIDENT: B9 deleted the milestone mapping on the premise that no runner read it. FALSE — `cavekit-spec` (host crate) enforces "every task belongs to exactly one milestone" & names it the rule most often broken & invisible without a check. MEASURED after: 92 violations, 88 of them a task in no milestone, + 4 §T rows out of id order. ROOT CAUSE ⊥ the deletion: I concluded "no runner reads it" from ITOK'S OWN gate, which by V31 CANNOT invoke a host guard ∴ a partial view stated as complete — V44's rule on my REASONING, & V82 ignored on the one repo I did ⊥ inspect. Compounded ∵ FORMAT.md is ABSENT from both repos while every spec command cites it: I noted the dead reference & moved on rather than reading it as the reason I was guessing — its RANGE syntax makes the mapping cheap, the burden I judged it to be. FIXED: mapping restored w/ ranges, rows sorted, both rules PORTED into `tests/spec_integrity.rs` ∵ itok ⊥ depend on a host crate (V13/V31) — a rule the host enforces the TRAVELING guard must too. Each ported guard proven by planting a violation (V79)|V44,V82,V31,V69,V79
B13|2026-07-28|SPEC defect, mine: V83 named V21/V24/V25/V35/V58 as what was considered `REJECTED` while TWO of its own five examples say `DEFERRED (⊥ rejected)` in their own text & each names the CONDITION that reopens it. The rule that rests on the records mislabelled the records it rests on ∴ a reader auditing V21 finds V83 calling it a rejection & the invariant calling it a deferral, & the honest reading of a contradiction is that one of them is stale. The ported guard carried the same flattening: `AUDIT_RECORDS` held both classes under one name (`the_rejected_option_records_survive`) ∴ nothing anywhere in the repo distinguished them. Found by a READER asking why a deferral is not just a todo, ⊥ by any check -- both classes are load-bearing & the guard fires identically for either, so no test could see it|V83 says CLOSED, then splits it: REJECTED vs DEFERRED-under-a-stated-trigger, w/ why the deferred pair is MORE deletion-prone & why §T cannot hold one (done-when is the MILESTONE's ∴ the trigger is lost, & `.` means PLANNED). Guard & baseline renamed to match (`.spec-records`, `the_closed_option_records_survive`). GENERALLY: a rule that CITES examples ! be re-read against them when they change -- the citation is where the drift hides, ∵ it renders as authoritative either way
B14|2026-07-28|a NAMED `<session>` was resolved as a filesystem PATH ONLY (`src/tracecmd.rs`: `PathBuf::from(s)`) ∴ a harness ID — which is what V96 says identity LOOKS like — became a relative path that never existed; then all 4 runtime verbs turned the miss into `Output::ok("")` ∴ EXIT 0, EMPTY, no diagnostic. MEASURED: itok's own 4 sessions (1.6-5.9MB) each reported NOTHING when named, while the bare verb (inferred) worked — so the dogfood task that needed to read them ALL was unbuildable. The id branch ALREADY existed 3 lines below, in the INFERRED path, & was never carried to the named one. Worse, the comment above one silent return STATED the rule it broke (`Unreadable is NOT the same as empty ... V47`). 4 tests asserted the defect as law, citing V5|resolution takes an ID or a PATH & a named miss is a usage error at exit 2 naming both forms tried (V104); `missing_output` is the ONE place a miss becomes an Output ∴ all 4 verbs answer identically (V64). GENERALLY: this is B7 (silent skip) × B11 (rule never carried to a sibling path) in one defect, the 4th of that class ∴ M12's sweep is ⊥ finished — & a COMMENT stating a rule is ⊥ a guard that enforces it
B15|2026-07-28|§T split T42 (`.context-policy` PARSER) from T43 (`guard`, its ONLY caller) ∴ T42 alone ships a registry NOTHING reads -- V69's exact defect, & V69 already says registry + caller land in the SAME commit, ⊥ apart. The parser & its 13 green tests were WRITTEN before anything noticed ∵ the plan checked T42's cites (V57/V18/V53) & V69 was cited by NO row ∴ nothing pointed at it. Caught MECHANICALLY, ⊥ by review: `-D warnings` refused `src/policy.rs` as dead code (`Policy is never constructed`) ∴ the gate enforced an invariant the DECOMPOSITION had ignored. 5th of the one-rule-never-carried class (B7 · B11 · B12 · B14)|T42 FOLDED into T43 -- registry + caller = ONE row -- & M6's range becomes T43-T46 (V15: a milestone claiming a missing row FAILS). V105 makes landability a property of a §T ROW ∴ the question is asked at DECOMPOSITION time, where it is cheap. GENERALLY: an invariant NOTHING CITES is invisible to a plan that reads only the row it is building -- `mth derive`'s orphan list is exactly that signal, & V69 stayed off it only ∵ §B cites it
B16|2026-08-03|SPEC promised a capability the BUILD could not perform: V25's `scheme://` slot "carries TLS" & `src/render.rs` deliberately KEPT `https://` in the method label ∵ "it says the endpoint is behind TLS", while `ureq` was built `default-features = false` ∴ `ureq-2.12.1/src/lib.rs:414` supplies a `NoTlsConfig` whose `connect()` returns `cannot make HTTPS request because no TLS backend is configured` — so `--ollama=https://…` opened the TCP session & THEN failed. TWO layers modelled a capability the transport lacked & nothing failed until runtime, ∵ the surface & the capability live in different crates' feature flags (V106). INVISIBLE to the suite: the cassette replay serves plain http through a local `TcpListener` ∴ no test ever took the https path. COMPOUNDED in `docs/SECURITY.md`, which listed "no TLS stack" as a hardening property beside `forbid(unsafe_code)` & put plaintext transport OUT OF SCOPE for reports ∴ a missing mitigation was published as a feature AND declared unreportable. Found by a READER, ⊥ the gate (V80). FIXED: ureq 3 + `rustls`, tier 60→44 packages|V106,V23
B17|2026-08-09|the published `.crate` FAILED ITS OWN SUITE: 14 lib units + 1 integration test read itok's OWN git history (tracked set · blob at HEAD · `HEAD~1..HEAD`) & registry source has NO `.git` ∴ a consumer, vendorer \| packager running `cargo test` on it gets 14 reds. B2's FIX is the cause: deriving the repo root at RUNTIME (V37) cured the monorepo-vs-extracted split & silently assumed a repo EXISTS — the rehearsal always unpacked INSIDE a worktree. INVISIBLE to every gate: `cargo package --verify` only COMPILES the tarball, & the `package` step checks WHICH files ship (`must-package`, all 10 present) ⊥ that they WORK. Location-sensitive ∴ the count MOVED with the unpack dir — 4 failures under `target/` (git resolves to THIS repo), 14 outside. Found by hand-running the tarball suite before spending an immutable version, ⊥ by the gate (V80)|gated on `ITOK_DOGFOOD`, an ENV opt-in set by `hk.pkl` + the dev shell — ⊥ an am-I-in-a-repo probe, which would go green in THIS repo the day git detection breaks & would ALSO fire for a vendorer inside THEIR repo. New `package-suite` hk step unpacks the .crate OUTSIDE the worktree & runs its suite with the var UNSET ∴ the gate is now the CONSUMER (V69: the file list was a runner, the suite was not). Its own bring-up hit a STALE GREEN — cargo writes reproducible mtimes ∴ extracted sources look OLDER than a shared `CARGO_TARGET_DIR` & the PREVIOUS binary reran, so a fix present in the tarball failed on a line it no longer occupied; `touch` before test. GENERALLY: `--verify` is a COMPILE, & the tests pass is a claim about a DIFFERENT tree than the one that ships\|V27,V37,V69,V80
B18|2026-08-09|`changed_in` ran a bare `git diff-tree --no-commit-id --name-only -r <c>`, EMPTY -- exit 0, NO diagnostic -- for the two shapes with no single obvious parent: a MERGE (git declines to pick a side) & the ROOT commit (none exists) ∴ `itok show <merge>` reported a confident ZERO for a commit that changed plenty. 4th of the silent-empty class (B7 · B11 · B14); V104 is the rule broken. INVISIBLE STRUCTURALLY ⊥ by oversight: itok's history is LINEAR & branch protection now REQUIRES it ∴ the shape the tool most needs to handle is one its own repo can NEVER contain. Surfaced the first minute a PR existed -- GitHub checks out an EPHEMERAL merge of branch into base for `pull_request` ∴ HEAD is a merge on EVERY PR run, & the repo had zero PRs until today|FIRST-parent `<c>^1..<c>`, matching `showcmd`'s deltas which ALREADY used `<c>~1` ∴ list & numbers from ONE choice ⊥ two; root takes `diff-tree --root`, git's own spelling for diff-against-nothing ∴ no empty-tree hash hardcoded. `-m --first-parent` REJECTED after MEASURING: on a 3-commit fixture it reports the mainline commit's files BESIDE the merged ones. Guards = a BUILT fixture (root · mainline · side · --no-ff merge) ∵ a merge cannot be recorded as a file, both proven by planting the old command (V79). First test needing a WORKING `git` ⊥ a git-shaped error, said out loud ∵ an unannounced environment requirement in the shipped suite is what B17 was. NOT fixed: a bad ref is still empty (no error channel on `Vec<String>`), pinned by a test so the limit is RECORDED ⊥ assumed\|V104,V79,V47
B19|2026-08-09|`-C` is ⊥ isolation & every git call in the tool assumed it was. `git -C <root>` sets the working DIRECTORY; `GIT_DIR`·`GIT_WORK_TREE`·`GIT_INDEX_FILE` set the git DIRECTORY & the ENVIRONMENT WINS -- & git EXPORTS them into everything it runs. itok RUNS FROM HOOKS by design: hk's own gate calls `itok check` from `pre-commit`, & `guard` is a harness hook (V52) ∴ every verb was answering about whatever repo INVOKED it, silently. Passed here only ∵ the two paths COINCIDE in this repo -- `itok -C /other/repo show HEAD` from a hook read the WRONG repository & said nothing. Found by BUILDING a test fixture: `git -C <tmpdir> init/add/commit` inherited the hook's `GIT_DIR` ∴ read files from the temp dir & wrote 4 commits + a moved branch into the repo UNDER TEST, tree = the 3 fixture files. The test that was meant to prove B18 performed the damage it was written to prevent|ONE scrubbed constructor `gitref::git(root)` clearing 9 GIT_* vars, used by every call in `gitref` + `walk` + `testutil`; `tests/spec_compact.rs` carries a SECOND copy ∵ an integration test cannot see a crate-private helper -- a copy that may drift beats a test reading the wrong repo, & the duplication is NAMED ⊥ silent. Fixture also gets `assert_own_repo`: `rev-parse --show-toplevel` ! equal the dir asked for, canonicalised (macOS /var -> /private/var) ∴ a future leak is ONE red test ⊥ a rewritten branch, & it runs BEFORE any commit so the blast radius is bounded. `add -- <file>` replaces `add -A` ∴ one stray path beats every file. PROVEN by running the whole suite under a decoy `GIT_DIR`: 426/426 with it & without\|V104,V79,V52
B20|2026-08-09|the `coverage` step compared cached & measured line-coverage as EXACT STRINGS (`[ "$measured" = "$cached" ]`) & coverage is PLATFORM-DEPENDENT: the IDENTICAL source measured 98.04 on macOS & 98.06 on ubuntu ∴ the check could ⊥ be satisfied on both AT ONCE -- committing either number broke the other machine, & the badge printed a figure no single machine could reproduce. A DEADLOCK off the CI platform: the CI number fails your pre-push, yours fails CI. T60's matrix would make it THREE ∴ this BLOCKED the matrix|ONE decimal, TRUNCATED (`int(x*10)/10`) on BOTH sides & in `scripts/badges.sh`. TRUNCATED ⊥ rounded, & that IS the fix: `%.1f` sends 98.04 -> 98.0 but 98.06 -> 98.1 ∵ they STRADDLE .05 -- the first attempt at this used rounding & would have shipped the same failure. Truncation sends both to 98.0 & FLOORS ∴ the badge understates, the safe direction for a published claim. The `--fail-under-lines 98` FLOOR keeps full precision ∵ it is a threshold, ⊥ a displayed claim. GENERALLY: a published number ! be REPRODUCIBLE on every machine that gates it (V17)\|V17,V64,V75
B21|2026-08-09|hk emitted NOTHING once a `depends`-chained step FAILED under `--no-fail-fast` ∴ CI reported no verdict & the run had to be KILLED. TWO reproductions, both right after the same test failure: 74m17s & 43m26s of silence, logs ending at `error: test run failed` & resuming only at `##[error]The operation was canceled` + `Terminate orphan process: pid (hk)`. INVISIBLE for 3 unbounded hours ∵ GitHub serves NO logs for an in-progress job & defaults to 360min ∴ the ONLY way to READ a hang is to BOUND it -- the timeout went in as a diagnostic & this is what it diagnosed|MINIMAL REPRO (hk 1.51.0, 3 steps): `b` `depends` on `a`, `a` = `exit 1`. Fail-fast: `b` ABORTED, prompt. `--no-fail-fast`: `b` NEVER reports, 3/3 killed at timeout ∴ an INDEPENDENT step completes, a DEPENDENT of a failed step waits FOREVER. FIXED UPSTREAM in hk 1.55.0, VERIFIED on that same fixture: `b` now RUNS to completion ⊥ merely aborts. Reached via `nix-hk` when 26.05 dropped `pkgs.hk` ∴ the dep bump closed this. Flag RESTORED for `push` only -- fail-fast on PRs is a FEATURE (merge blocked either way ∴ time-to-first-signal is all that matters), complete list on main where nobody waits. Timeout stays, now 15min ⊥ 45 (worst job MEASURED 6m40s). GENERALLY: my diagnosis was WRONG first -- I read a 50-min run as cold-build cost & sized it from the nix closure (961MiB/3.2GiB) WITHOUT measuring; true figures are 26s for the shell & 79s to first test ∴ an estimate presented with the confidence of a measurement is the defect\|V17,V80,V85
B22|2026-08-11|`a_stale_harness_id_falls_back_instead_of_failing` asserted INSIDE `if let Ok(..)` over the AMBIENT home & cwd (`resolve_session(None, None)`) ∴ on a machine with no transcript dir for the cwd it took the Err path & checked NOTHING while reporting green -- B3's rule broken in the very file that records B3. VACUOUS on some machines, & the machines disagreed: the `if let` body is covered on linux, ⊥ on macOS. ONE line, & the 98% floor sits exactly between -- linux 98.01% (127 missed) vs macOS 97.99% (128) ∴ `main` was GREEN on linux & RED on macOS simultaneously, invisible ∵ CI was linux-only. Found while adding T60's platform matrix, BEFORE it merged: the matrix paid for itself by exposing the thing it was about to break on|test made HERMETIC -- plant a transcript under a throwaway HOME+cwd (the `planted_transcript`/`resolve_under_home` machinery already beside it), set a STALE `ITOK_SESSION_ID`, assert UNCONDITIONALLY that resolution falls back to `Origin::Newest` & the planted file. Fixture dirs now SUFFIXED per id ∵ they were shared & `newest_in` picks by mtime ∴ one test's file could win another's fallback -- ⊥ a data race (nextest = process per test), worse: a failure that reads as a bug in the tool. MEASURED after: macOS 98.02% (126), the 2 lines covered & the platform gap CLOSED ∴ the number no longer depends on the machine. GENERALLY: a vacuous test & a platform-dependent gate were the SAME defect, and coverage found it where reading did not\|V79,V10,V64
B23|2026-08-14|the `semver` baseline is `git tag --list 'v*' --sort=-v:refname \| head -1` & git's version sort has NO notion of a semver PRE-RELEASE ∴ `v0.3.0-rc.1` sorted ABOVE `v0.3.0` (longer refname wins). Publishing 0.3.0 therefore did ⊥ move the baseline off the rc, & every later run would have diffed against a tag that is both OLDER & the one this toolchain cannot build (the B-record above) ∴ the step would have reported BASELINE UNBUILDABLE FOREVER while looking like it merely had nothing to say. Found by CHECKING a claim ⊥ trusting it: arming this step was the stated point of cutting `v0.3.0`, & it was still skipping afterwards|`git -c versionsort.suffix=-` ∴ `-` introduces a pre-release & `v0.3.0` sorts first. MEASURED both ways on the two REAL tags, & the fix is PROVEN by the step going from `0 checks, 253 skip` to `196 checks: 196 pass` -- its first real verdict in this project's life. GENERALLY: a gate that reports "I examined nothing" is honest but ⊥ self-correcting; nothing fails when the reason it examines nothing is itself a bug, so the SKIP branches earn the same scrutiny as the fail ones\|V17,V10,V80
B24|2026-08-16|`rate`'s `parse_ts` read a transcript stamp as EPOCH DIGITS (`ts.get(..10).parse::<u64>()`) & every transcript writes RFC 3339 (`2026-08-15T06:55:39.102Z`) ∴ the slice was `2026-08-15`, the parse FAILED, `unwrap_or(0)` swallowed it & `age_seconds` was 0 for EVERY real session — then the 1-second floor turned that into `132590m/h` on a 22-hour session ∴ the badge's whole POINT was garbage while its shape looked right. INVISIBLE to 25 green tests ∵ I HAND-WROTE the fixture stamps (`"1000000000"`) to match my own parser ⊥ copied the format the reader emits ∴ the test proved the code agreed with ITSELF. V79 says a fixture pins its own shape & V43 names the transcript GROUND TRUTH; a fixture in a shape the ground truth NEVER produces satisfies neither, & no coverage over it can. Found the FIRST time the verb ran on a real session, one commit after T94 went `x` (V80: the gate did ⊥ find it, USE did)|fixed-offset RFC 3339 reader + Hinnant `days_from_civil`, integer-only ∵ `arithmetic_side_effects` is denied & one subtraction between two machine-written stamps does ⊥ earn a calendar crate. Fixtures RE-CUT to real stamps, & `parse_ts` pinned against values computed OUTSIDE the crate (`date -u -d`) ∴ a reimplementation cannot drift into agreeing with itself again; leap day asserted in 2024 AND in 2100, the century that is ⊥ one. The epoch-digit string is KEPT as a case that ! read 0 — the exact shape that hid this. GENERALLY: a fixture value invented to fit the parser tests NOTHING; its format ! be copied from the PRODUCER & pinned to an authority outside the code under test\|V79,V43,V80
B25|2026-08-18|`rate`'s `/h` & `/d` are LINEAR projections off `age_seconds` & print bare ∴ a 22-minute session read `(itok:128k,11m/total,30m/h,707m/d)` — arithmetic CORRECT (`total × 86400 / 1337`), meaning FICTION, & indistinguishable in the badge from a day actually measured. V3 has marked crude numbers with `~` since the first estimator & V92 refuses a denominator it would have to guess; NEITHER was carried to the verb that divides by TIME (B7 · B11 · B14 · B18's class, now 5 deep) ∴ the badge's two derived values were the only unmarked estimates the tool emits. Found by USE across two live sessions, ⊥ by the gate (V80), one day after B24 fixed the OTHER half of the same denominator|`~` on any period the age does ⊥ cover (V110) + `projected_*` in json. SECOND finding on the same denominator, FIXED one commit later by V111 & recorded here ∵ the numbers are what justified the cap: `age_seconds` is WALL-CLOCK span ∴ it counts sleep — a 2140-turn session spans 337.9h of which 11.2h/17.2h/28.3h is active at a 120s/300s/900s idle cap ∴ its `3m/h` understates the working rate ~20× while the short session's is unaffected (0 idle). Marking is orthogonal to & landed BEFORE the denominator choice: a projection stays a projection whichever clock it divides by, & the marks now read the ACTIVE clock\|V110,V3,V92,V80
B26|2026-08-22|`rate`'s `tp_from` FLOORED the denominator at 1s (`if active == 0 { 1 }`) ∴ an unmeasurable clock published `total × 3600` & `total × 86400`: two turns inside ONE wall-clock second — ordinary at session start ∵ `parse_ts` truncates to seconds — reported 104 tokens as `375k/h`, & json printed that beside `"active_seconds":0` ∴ the object CONTRADICTED itself & no reader could reproduce `per_hour` from the numbers next to it. B24 NAMED this amplifier ("the 1-second floor turned that into `132590m/h`") & fixed only the stamp reader feeding it ∴ the floor OUTLIVED the bug it multiplied — a fix that treats the input & leaves the amplifier is half a fix. The test over it asserted `active_seconds == 0` & `contains("~")`, BOTH true of the garbage ∴ green over a wrong MAGNITUDE|`per_hour`/`per_day` become `Option<u64>`: `-` in the badge, `null` in json (V47/V92 — an absent number is a dash, NEVER a zero), ⊥ a rate over a denominator nobody measured. Tests pin the magnitude & the same-second case by name ∵ a test that pins only the SHAPE cannot fail on the number (V79)\|V47,V92,V79,V110,V111
B27|2026-08-22|B20's fix NARROWED the platform spread & did ⊥ remove it: `coverage` still compared cached & measured as EXACT strings, one decimal apart ∴ 98.18 (macOS) & 98.21 (ubuntu) straddled a TRUNCATION boundary exactly as 98.04 & 98.06 straddled a ROUNDING one, & the deadlock returned one decimal down — CI red on a cache the local gate had just passed. An equality check between two machines that MEASURE differently has NO fixed point ∴ the class survives every attempt to shrink the digit. SOURCE of this spread: 2 lines (`tracecmd` `Origin::Harness` · `rate`'s short-session branch) reached ONLY through dogfood tests, which read whatever transcripts the MACHINE holds — 9 here, 0 on a runner ∴ ambient state deciding coverage, B3's class & B22's exact shape|(a) both lines PLANTED & covered hermetically ∴ the number stops depending on the machine; (b) the comparison goes ONE-SIDED — measured BELOW cache fails (the badge would OVERSTATE), measured above passes, & >0.5 above fails as STALE ∴ the cache is written by the most pessimistic machine gating & every other agrees. GENERALLY: a check between two machines ! be an EQUALITY on a machine-dependent number; it ! bound the direction that can LIE (V17)\|V17,V64,B20,B22,B3
B28|2026-08-30|13 rows carry an UNESCAPED literal `\|` ∴ the POSITIONAL split moves & the last field is ⊥ what the author wrote: `T94`'s cites read `always`, from `--color auto\|always\|never`, & 12 §B rows lose the tail of their `fix`. LATENT TODAY ∵ the flake pins `microlith/v0.6.1` & the rule (its V42) ships AFTER ∴ the gate is GREEN here & goes RED at the next PIN BUMP. FOUND from microlith, whose own shell resolved a NEWER `mth` through `MICROLITH_MANIFEST` -- the shim doing exactly what it is for|⊥ FIXED HERE, deliberately: each row needs a JUDGEMENT about WHICH pipe is literal & in several the extra sits in the LAST field, where the mechanical `escape all but the first 2 & the last` does ⊥ hold. RECORDED so the pin bump meets a KNOWN cost, ⊥ a surprise; FORMAT.md has always required `\|` & nothing enforced it until now. FIXED 2026-09-05, by hand & row by row as this row said it would have to be: 16 rows now escape every literal pipe (the 13 + this record + T106 + B32, both mine & both the same defect within a day of the row being read). The JUDGEMENT the mechanical rule could ⊥ make: 11 §B rows had appended a CITES field that §B's shape (`id\|date\|cause\|fix`) does ⊥ have ∴ the separator before it is escaped & the citations ride INSIDE `fix` — which is what the author wrote & exactly what the positional split was eating. `tests/spec_compact.rs` now COUNTS unescaped pipes per row, proven by planting one (V79), so the rule is enforced HERE ⊥ only at the next pin bump (V31)
B29|2026-09-05|V98, V100 & `top`'s PRINTED caveat all say the `size × turns` premise "holds for UNCOMPACTED sessions, which is all that has been observed" — FALSE since 2026-08-02 at the latest. MEASURED over 88 transcripts on this machine: 6 auto compactions in 5 sessions, TWO of them itok's OWN (`a18102a4`, 2026-08-16) ∴ the claim was stale in the repo that wrote it, & `carried`/`projected` have been silently OVERSTATING for every session that compacted ∵ a dropped item stops being re-sent while `size × turns` keeps billing it for turns it never rode. INVISIBLE ∵ nothing ever LOOKED: the harness records the event (`compactMetadata`), the session parser reads `usage` & walks straight past it, & V98's "the day one is seen they say so" made the trigger a HUMAN noticing rather than a check. Found while measuring the auto-compact point for T101, ⊥ by the suite (V80)|⊥ FIXED HERE, deliberately: T102 owns it ∵ the fix changes what `top` CLAIMS & needs T101's parser to be conditional on the session in front of it, & folding a second verb's output into the badge's PR is exactly the coupling V105 asks a row to avoid. RECORDED now ∴ the next reader of V98 meets the correction, ⊥ the stale sentence
B30|2026-09-05|the badge's `/h` & `/d` have been publishing a rate whose information has the WRONG SIGN. They divide `billed_input`, which is 92.5-99.8% `cache_read` (n=49) ∴ they measure TURN FREQUENCY × OCCUPANCY: a session that adds nothing new but keeps taking turns shows a RISING rate, & the rise accelerates as the window fills ∵ every turn re-bills a bigger prefix. So the number climbs fastest at the moment growth is slowest, & a reader watching it for "am I filling this up" is reading the opposite. Shipped in 0.3.1 (T94) & unnoticed through T96 & T97, both of which corrected the DENOMINATOR (V110's reach, V111's idle time) while the numerator was the defect — two passes over the same expression, each fixing the half that was right. Found by a USER reading their own badge & asking what `total` meant, ⊥ by the suite (V80), & the question was the giveaway: `846m/total` beside `963k` of occupancy is off by ~900x & nothing in the repo had ever said which quantity it was|V117 replaces the numerator w/ growth & renames the cell that stays; T103 builds it. GENERALLY: a badge value survives review by being PLAUSIBLE -- no test can fail on a number that is merely the wrong quantity, & the two passes that fixed the denominator are the evidence that reviewing an expression PART BY PART is how the whole stays wrong
B31|2026-09-05|§I has documented `itok doctor --session [<id>]` — "retargets it at a CONTEXT: progression (use% · rate · `~turns left`) + per-item `projected`" — since the line was written, & the binary answers `itok: unknown flag '--session'` at exit 2. V106 is the rule for exactly this, & the SAME section applies it correctly TWICE within four lines: `cap`'s ladder & `headroom --task` each carry "PLANNED, ⊥ BUILT (T40)/(T76)" beside them. doctor's line carries NO marker ∴ §I promised a surface `--help` refuses, & §I is what the world sees. COMPOUNDED by V100, which legislates `projected`'s LABELLING ("TWO names, ⊥ one column w/ a sign") over a column NO verb prints ∴ an invariant governing an unbuilt thing, which to anyone auditing reads as a description of shipped behaviour. Found while BUILDING T76, ⊥ by the gate — nothing cross-checks §I's flags against the ones the binary accepts, which is V17's "a rule with no runner" on the spec's own surface section|FIXED by BUILDING it (T76), ⊥ by adding the marker: the row was already scheduled & the surface already promised, so the honest close is the feature. GENERALLY: V106's marker is applied BY HAND ∴ its own coverage is unenforced, & the mechanical check is cheap — T105
B32|2026-09-05|the PUSH-side gate has been a no-op for every expensive step since it was written. `flake.nix` installs both hooks from ONE loop w/ ONE command (`hk run $ev --from-hook`), & `hk run` selects STAGED files: correct for `pre-commit`, EMPTY for `pre-push` ∵ the commit that preceded it emptied the index. MEASURED on a real push: 15 of the declared steps ran & all 12 `**/*.rs` steps did ⊥ — so `cargo test`, `clippy`, `coverage` & the SPEC checks were never run by a push, & `hk.pkl`'s `steps = all` was honest about a set nothing selected into. FOUND by CI: T76's PR failed the coverage floor (97.87% vs 98), & the same commit failed `hk check --all --check` LOCALLY in a worktree ∴ the gate could have caught it & was ⊥ asked. COMPOUNDED by the reporting: pushes printed a step LIST w/ no file counts while commits printed `– N files –`, which is the tell, & I read the list as the gate passing — 5 PRs were claimed "gate green on push" on that evidence. `docs/INTEGRATION.md` says `pre-push \| all — 33 steps` & its count is CHECKED, so the doc was right about the definition & wrong about the world (V120)|`--all` on the PUSH hook only, in the same loop that made them identical: a commit selects what it commits, a push selects the tree it publishes. The loop's shared command was the economy that caused this ∴ the fix keeps ONE definition & splits the SCOPE, ⊥ writing two commands. Doc gains the distinction beside the step counts it already checks
B33|2026-09-05|B32's FIX is measured & its CAUSE is ⊥ — & the row states the cause as if it were established, which is the defect. MEASURED, both directions: before the change a real push ran 15 steps & NONE of the 12 `**/*.rs` ones, reporting only `Fetching git status (2 files)`; after it a real push reported `Fetching files between origin/<branch> and HEAD` & `ollama` · `itok` · `mth` ran. ⊥ MEASURED: the reason. B32 says `hk run` selects STAGED files & V120 turned that into a RULE; 5 probes in a plain shell REFUTE it — `hk run pre-push --from-hook` computes `origin/main..HEAD` correctly w/ stdin, w/ `/dev/null` stdin, w/ the hook's positional args, WITHOUT them, & under git's exported `GIT_DIR`/`GIT_WORK_TREE`/`GIT_INDEX_FILE` (B19's env). ∴ the difference lives in the REAL hook invocation & no probe reproduces it; `--all`, the flag the fix added & the message credited, is likely INERT — hk logged the same ref-range fetch w/ & without it. V2 ON MY OWN RECORD: a fix that works wearing an explanation that does ⊥ is WORSE than an unexplained fix ∵ the next reader debugs from the story|⊥ FIXED & ⊥ REVERTED: the change is measured to work, & reverting to chase a cause re-opens the hole. B32's cause is RETRACTED here, V120's rule is restated as what is established, & the open question is NAMED ⊥ dropped: why the real hook fell back to `git status` when no probe does
B34|2026-09-05|TWO surface defects, both found by T105 on its FIRST RUN, one in each direction it was built to look. FORWARD (B31's class, unmarked): §I promised `top --cost` & the binary answers `unknown flag` — T38 owns the RATE column it renders & is `.`, so the row was always planned & the LINE never said so, exactly as doctor's did ⊥. REVERSE, & nothing had EVER looked: `itok check` accepts & ADVERTISES `--format human\|json` — the synopsis `--help` prints carries it & it works — while §I's `check` line named neither it nor `-C`. So the spec was short of the build in one direction & ahead of it in the other, in the same section, & the two escaped for opposite reasons: a promise nobody probed, & a surface nobody wrote down. THIRD finding, from the guard failing its OWN planted test: `check` rejects with `unknown argument` & every other verb with `unknown flag`, & BOTH are right (`check` takes no positionals ∴ a bare word there IS an argument) ∴ a probe pinned to ONE sentence silently stops probing one verb -- it now matches "unknown" + the flag's own name, which no wording can defeat|BOTH fixed in §I: `--cost` takes V106's marker citing T38, `check` gains the flags it already has. The GUARD is the record's point — 6 candidates on the first run, 4 of them parser artefacts (a flag named in another verb's prose, a shared `--ollama` bullet, `--help` as prose about OUTPUT), & the 2 that survived were real. A guard whose first run finds nothing is a guard nobody needed
B35|2026-09-05|B3, NINE WEEKS LATER, in the test beside the one B3 fixed. `exit_code_is_one_when_there_is_a_delta` diffed `HEAD~1..HEAD` & demanded exit 1 ∴ it asserted that WHATEVER SITS ON TOP is big enough to register — & this commit's HEAD was a one-CHARACTER edit, a §T status flipping `.` to `x`, which costs ZERO tokens ∴ the delta was 0, `--exit-code` correctly returned 0, & the gate blocked the push. B3's own fix is two tests further down, w/ the reasoning in a comment ("`HEAD~1..HEAD` couples to the last commit's size... the empty tree is STATE-independent, V37") & the constant it needs sitting INSIDE that test's body where the sibling could ⊥ reach it. ONE rule, ⊥ carried to the path beside it — B11's class, & the 6th of it. Found by the PUSH GATE (B32's repair) on a commit whose only content was correcting a §T status the previous PR forgot to flip|both tests now diff FROM the empty tree & the constant is lifted to the module where both read it (V64). GENERALLY: a fix that lives INSIDE the test it fixed is a fix its neighbours cannot use, & a comment explaining the trap is ⊥ the same as making the trap unreachable
B36|2026-09-05|the ESCAPE HATCH became the HIDING PLACE. §I said `headroom --task` was "PLANNED, ⊥ BUILT (T76): that flag is rejected today", & `tests/surface.rs` carried the matching EXEMPT row — while the flag WORKS: `headroom <session> --window 1M --task 50k` prints `tasks left ~17` & has since T86. The marker was attached to the WRONG SUBJECT: the sentence's PLANNED clause was about the VERDICT ("the verdict stays `doctor --session`"), which T76 has now built, & the `--task` column beside it was never the unbuilt half. T105's guard CANNOT see this: an exemption that is wrong in the BUILT direction skips a probe that would have PASSED ∴ silence, both ways. So the guard I built to stop a hand-written marker going stale trusted a hand-written list that had (V64's shape, on my own fix). FOUND by reading the EXEMPT list after T40 emptied four rows out of it — ⊥ by any check|the guard now PROBES its own exemptions: an EXEMPT pair the build ACCEPTS FAILS, naming the row to delete. §I loses the false claim. GENERALLY: a suppression list is a claim about the world & needs the same runner as the claims it suppresses — an escape hatch nothing audits is a second §I
B37|2026-09-05|`cap`'s resume selector could point at BYTE 0 — a loop wearing a number. A budget too small for the FIRST line keeps nothing ∴ `kept_bytes` is 0 ∴ the footer published `resume: line 1 (byte offset 0)` & a caller following it re-reads the same bytes FOREVER. V51 says the selector exists so the next read CONTINUES; one that ⊥ advance is worse than none ∵ it reads as usable. A TEST ASSERTED IT AS LAW (`a_budget_below_the_first_line_keeps_nothing` pinned `byte offset 0`) — B14's shape, & the second time a test in this repo has frozen a defect. FOUND by T41's round-trip: the promise had never been CASHED, & the first walk of a real footer hit the loop on its first case|no selector when nothing was kept, & the footer names the reason ("nothing fits this budget, so an offset would send the next read round the same bytes"). The old test now asserts the ABSENCE. T41's `follow` walks by OFFSETS ⊥ by bodies ∵ `run` adds a trailing newline & comparing bodies tests the renderer; proptest walks arbitrary line shapes at budgets from 5 (below that is this row's case). GENERALLY: a selector is a PROMISE about the next call, & the only test of a promise is making the call
B38|2026-09-07|README's ONE sentence cashing the library surface — "this is not hypothetical" — pointed at `github.com/pr0d1r2/blackbox`, which 404s: the repo was RENAMED to `sherd`. The REST of the claim holds (`sherd/Cargo.toml` pins `itok = { version = "0.3", default-features = false, features = ["bpe"] }`) ∴ the sentence was CORRECT when written & decayed when ANOTHER repo moved — nothing in this tree changed. INVISIBLE BY DESIGN, ⊥ by oversight: the `links` step is `--offline` (hk.pkl:242-246) on reasoning that holds for a COMMIT gate — "a 404 on someone else's site is not a reason to reject your commit" — but this is a FLEET SIBLING & the sentence asserts a fact about THEIR build. The 404 is the LOUD half & the only half a link check could ever see: had `sherd` merely DROPPED `bpe`, the link would stay 200 & the sentence would be silently false. V112's shape — a promise to a CONSUMER needs a runner proving the CONSUMER's path — applied to PROSE. Found by a reader following the link, ⊥ by the gate (V80)|name & link corrected, & `default-features = false` added ∵ that is what `sherd` pins, so the paragraph matches the manifest it describes. ⊥ FIXED & recorded as such: the RUNNER. An external-URL check needs the network this gate refuses (hk.pkl:244) ∴ it belongs in a SCHEDULED job, ⊥ the commit gate; & the half worth checking — the feature list — needs another repo's manifest fetched, a wider decision than one broken link buys. GENERALLY: a README sentence about ANOTHER repo is a claim whose only owner never reads it, & its decay is silent in the direction that matters
B39|2026-09-07|B38's class, SWEPT — & the sweep found TWO MORE in this repo, both about the SAME sibling. (1) `hk.pkl:320` & `tests/spec_compact.rs:256` each named `github:pr0d1r2/microlith/v0.5.0` while `flake.nix:57` pins `v0.6.1` — & `flake.nix:44-48` DOCUMENTS the move ("26.05 made the old pin UNBUILDABLE... `rustc 1.95.0 is not supported by microlith@0.5.0`") ∴ the commit that moved the pin explained itself at the pin & left two copies of the OLD number in prose elsewhere. (2) V112's evidence clause read PRESENT TENSE — "microlith's `.context-limits` records a 23,200-token ceiling... the rule has had NO runner... sits ~37% over" — & microlith's T38 has SETTLED all three: the ceiling is 36,800 & its `hk.pkl` runs `itok check` off the cached package. The sting is that V112 ASKED FOR THAT FIX & got it ∴ the invariant's own success is what falsified its evidence, & nothing re-read the sentence. All three are COMMENTS \| PROSE, which is precisely why they survived: no test reads them, & B38's runner is still ⊥ built|the version is DELETED from both comments rather than corrected — `flake.nix` owns the tag & a second copy in prose is V64, so the class dies with the duplicate instead of resetting a countdown. V112's clause moves to PAST tense & GAINS the outcome, which is stronger evidence than the complaint was: a consumer's path proven by a CONSUMER WALKING IT. GENERALLY: a number copied out of another repo has no owner in this one, & the fix is to stop copying it, ⊥ to copy it again more recently
B40|2026-09-09|`ci.yml` declared NO `permissions:` block ∴ both jobs ran at whatever the REPOSITORY default grants — a scope set in a settings page, visible in no diff — & both `actions/checkout` steps kept the job token in `.git/config` as an extraheader, where every later step can read it (`zizmor`: 3× `excessive-permissions` @ Medium, 2× `artipacked` @ Low). NEITHER is a mistake `actionlint` is built to see: it type-checks the file & the file is VALID. The gap is ⊥ oversight but SCOPE — the only workflow lint here asked whether the workflow is CORRECT, never what it can REACH (V124). Found by ADDING a tool, ⊥ by the gate (V80), & the question that surfaced it was whether `zizmor` should REPLACE `actionlint`, which trades one blind spot for another|`permissions: contents: read` at workflow level ∵ nothing here writes to the repo ∴ read is the whole requirement, & stating it forces a future step needing more to ASK in the diff; `persist-credentials: false` at both checkouts, safe ∵ nothing pushes & the history the dogfood tests read is already on disk. `zizmor` runs beside `actionlint` at `--persona=pedantic` (V125), which adds 4 more: 2 FIXED — both `run:` blocks read `env:` vars now (`FAIL_FAST`, `PACKAGE`) rather than having the expression engine paste text into their source — & 2 LEDGERED. VERIFIED, ⊥ asserted: pedantic on `ci.yml`@08c6aa7 = 9 (5 medium · 2 low · 2 info), after = 0; & ⊥ vacuous (V10) — deleting `permissions:` → exit 13, `${{ github.event.head_commit.message }}` in a `run:` → HIGH, exit 14. GENERALLY: a default is a decision nobody made, & one that grants a CREDENTIAL is the one worth writing down
B41|2026-09-09|B40's `env:` fix broke `the_workflow_builds_every_feature_configuration`, which asserted the LITERAL string `nix build .#${{ matrix.package }}`. NOTHING about what CI builds changed — the three packages, the matrix & the command all survived; only the SPELLING moved, ∵ the value now arrives via `env:` instead of being pasted into the script. SECOND occurrence: the same guard already had to be rewritten once when three literal `nix build` lines became one matrix job, & its doc comment SAYS so ("keeps the guard pointed at the claim rather than at a formatting choice") — ∴ the intent was recorded & the assertion still did ⊥ match it. A guard that fires on spelling is the mirror of V17: ⊥ a claim with no runner, but a runner watching the wrong thing, & it costs a red gate on a change that was correct|the assertion SPLITS into the two halves that would have to change for the claim to go false — the matrix value REACHES the step (`PACKAGE: ${{ matrix.package }}`) & the build CONSUMES it (`nix build ".#$PACKAGE"`) — ⊥ one literal spanning both. GENERALLY: when a guard fires on a change that preserved the claim, the guard is the defect; & a doc comment stating the right intent is ⊥ evidence the assertion implements it (V80)
B42|2026-09-28|`dispatch`'s doc comment promised "exhaustive over `Verb` -- a new verb is a compile error here until it is wired" while BOTH matches ended in `_ =>`, & `runtime`'s was `_ => trace` ∴ a new `Verb` variant compiled clean & silently ANSWERED AS `trace`. The comment that warned about exactly this was deleted in T94's diff (`Verb::Rate`) & the claim above it survived — V17's shape: a rule stated in a comment & enforced nowhere. `each_runtime_verb_reaches_its_own_module` pins the verbs that EXIST ∴ cannot catch the next one by construction (#13)|the five session verbs move into a nested `Runtime` enum & `Verb` carries `Runtime(Runtime)` ∴ `dispatch` routes them in ONE arm & `runtime` matches `Runtime` — both exhaustive, no catch-all in either; the TYPE SYSTEM now carries the claim, ⊥ the comment. Flat variants were tried first & broke `too_many_lines` (15, clippy.toml) — the nesting is the split the cap asked for. GENERALLY: a catch-all arm is a promise that no future variant needs a decision
B43|2026-10-19|`mthWrapper` selected `microlith.packages.${system}.default`, but the pinned `microlith` flake publishes no `packages.x86_64-darwin` ∴ evaluating the Intel macOS dev shell failed before any gate step ran|build the pinned microlith source directly with `buildRustPackage` for the wrapper, preserving Intel macOS in the supported systems and CI matrix
B44|2026-10-19|the Intel macOS gate's `nix develop` step had a 10-minute timeout even though the job allowed 30 minutes ∴ a cold runner still building the pinned `microlith`, `hk` & `mth` tools was killed before `hk` could start|match the gate step timeout to the 30-minute job bound; keep the job bound as the outer guard while allowing legitimate cold-shell materialisation
B45|2026-10-24|`flake.nix`'s reproducible package fileset included the root manifest and `src/` but omitted the declared `dev/` workspace member ∴ every `nix build` variant copied an incomplete workspace into the store and Cargo failed before compilation with `failed to read .../dev/Cargo.toml`|include `./dev` in the package fileset so the Nix source contains every workspace member\|V80