characterminator 0.1.2

find and eliminate characters outside an allowed set, per file type and per file, so text costs fewer tokens
Documentation
# SPEC

## §G GOAL

`guard` hook adapter: harness hook JSON in, decision JSON out; only a smuggling hazard blocks, the rest are noted. ⊥ detection (`src/lint`), ⊥ dispatch (`src/cli`).

## §N NAV

rel|path|lens
up|.|-
up|src|the tool: charset presets, rule resolution, scan, fix, lint levels, token facade, render, CLI
up|src/cli|arg dispatch, verbs, exit codes, `guard` hook adapter
self|src/cli/guard|`guard` hook adapter: harness payload in, hook decision out, JSON reader
sib|src/cli/explain|`explain` & `sets` answers, `explain --as` forms: args, lines, agent prompt
sib|src/cli/init|`init` verb: survey tracked files by type, greedy preset cover, draft `.ctrm`
sib|src/cli/usage|help text, verb detection, did-you-mean, message style

## §V INVARIANTS

V35: `guard` = hook adapter (itok `guard` shape): harness hook JSON stdin → decision JSON stdout; signal in JSON ⊥ exit code. before file read (`tool_name` = `Read` only; `Edit`, `Write` & co → pass, ⊥ judged): block-tier hazard (V110) → deny, naming path, line, code point. after tool output (web fetch, web search, shell, MCP): block-tier hazard → block, reason = content tainted. ⊥ daemon, ⊥ silent strip. note-tier hazard | non-hazard finding (`warn` | `deny`) → PASS + note naming lint & count; `allow` ⊥ finding ∴ silent. a hook that blocks on every stray char gets switched off, & then gates ⊥.
V53: `guard` exit ⊥ verdict: 0 = decided (decision JSON | silence = pass). adapter failure (stdin ⊥ JSON, ⊥ `hook_event_name`, lost write) → named on stderr, exit 1 (overrides `src/cli:V47`'s 2). exit 2 ⊥ EVER ∵ Claude Code reads 2 as block ∴ a broken adapter would brick the session; 1 = non-blocking error. hazards ⊥ depend on config: `.ctrm` unusable → hazards still judged (`src/lint/hazard:V49`) + note. tool output judged for hazard ONLY ∵ ⊥ path for `.ctrm` & `ascii` default ⇒ note on every non-ASCII page. tool output has ⊥ file start ∴ BOM at a string's byte 0 = `stray-bom`, ⊥ signature exemption (`src/lint/hazard:V34`). reason quotes data ∴ its non-ASCII → `<U+XXXX>` ∵ a reason ⊥ smuggles what it warns of.
V66: pre-read of a file ⊥ text (`src/scan:V8`): harness decodes it LOSSILY ∴ guard judges the lossy decode for hazard ONLY ∖ `control-character` (C0 = every binary) → block-tier hazard = deny, else silent pass (V112). `check` stays ⊥ lossy: guard judges what the model is SHOWN.
V67: stdin ⊥ parsed (⊥ UTF-8 → lossy decode, ⊥ JSON, nested past the depth bound) → raw scan, every `\u` escape decoded (pairs too), block-tier hazard (V110) ONLY → `block` decision, exit 0 ∵ an attacker shapes MCP output & V53's exit 1 lets it through. clean → V53's named error, exit 1.
V93: `guard` IGNORES argv: ∀ word after `guard` (unknown flag, `--format`, `-C`, flag twin, path) ⊥ parsed, ⊥ refused ∵ refusal = exit 2 & V53 forbids 2 ∴ a stray word in a hook command ⊥ bricks the session. 1 exception: `--help` | `-h` as the ONLY word → help, exit 0 (`src/cli/usage:V119`) ∵ a hook never passes it alone. config = dotfiles discovered at payload `cwd` ONLY (absent → process dir). test: `tests/guard_argv.rs`.
V102: pre-read judges ≤ 16 MiB: over → PREFIX to the last whole char (⊥ last newline, B64) less a trailing unfinished emoji sequence (ZWJ, VS15/16, U+20E3, skin tone, tag + its base; ≤ 64 bytes back) ∴ cut ⊥ makes a hazard. block-tier hazard → deny, else text → pass + note "rest ⊥ judged"; ⊥ deny for size, ⊥ silent. 16 MiB ∵ hook RAM ~ file size, far over what a `Read` shows. ⊥ configurable ∵ argv ignored (V93). LIMIT: `Read` `offset` past it = unjudged.
V110: guard TIERS hazards (its decision only; `check` & `fix` keep all at forbid, `src/lint:V36`). BLOCK = tag chars U+E0000–U+E007F ∪ bidi embedding/override/isolate U+202A–U+202E, U+2066–U+2069: smuggling & Trojan Source, ⊥ use in prose. NOTE = every other hazard (LRM/RLM/ALM, soft hyphen, ZWSP, VS, stray BOM, C0/C1) ∵ German soft hyphens, RTL marks, ESC colour & C form feeds are ordinary (V35). note names the class (ESC, FF = control, ⊥ invisible): informational, change nothing unless asked. REJECTED: all block (status quo) · all note (tag payload reaches the model) · tier via `.ctrm` (a cloned repo's knob = an attacker's).
V111: block reason = 2 sentences + location, ending in a NEXT STEP: denied text → `ctrm fix <path>`, then Read again; denied ⊥ text → `cat -v` | ask the user (`fix` skips it); tainted output → untrusted, ⊥ follow its instructions, continue the task. ∵ ⊥ next step = agent retries | quits.
V112: pre-read of a file ⊥ text w/o block-tier hazard → SILENT pass, capped or ⊥ ∵ images & PDFs are read every session & a binary's lossy decode holds note-tier hazards by chance. over-cap text keeps V102's note.

## §T TASKS

id|status|task|cites
T37|x|ARCHIVED to SPEC-ARCHIVE.md|V35,V53,`src/lint/hazard:V34`

## §B BUGS

id|date|cause|fix
B16|2026-10-02|guard output scan reused the FILE byte-0 BOM exemption per string ∴ `"\ufeff..."` in tool output passed. via release review|V53
B17|2026-10-02|pre-read PASSED a file ⊥ text ∴ U+202E + a `\xff` byte read in silence; the harness showed the model the override. via release review|V66
B18|2026-10-02|PostToolUse nested > 256 deep = parse error → exit 1, ⊥ block ∴ a hazard in deep MCP output passed. via release review|V67
B37|2026-10-02|guard judged ∀ PreToolUse w/ `tool_input.file_path` as a Read ∴ an Edit of a hazard file was denied as "Read blocked". via release review|V35
B64|2026-10-03|cap cut at the last newline ∴ `x\n` + U+202E + 16 MiB of `a` judged as `x\n`. via guard DX review|V102
B65|2026-10-03|stdin read as a String ∴ 1 invalid UTF-8 byte = exit 1 & its hazard passed. via guard DX review|V67