--- name: compuse-toolbox description: Use when about to hand-roll a one-off shell/Python utility for a recurring chore - finding or killing a process (pgrep -f, pkill -f); a gate's REAL exit status, not a pipe's; git across repos - branch/sync/dirty, tracked vs gitignored vs untracked, merge-conflict markers; error lines in a noisy CI log; did CI finish on my commit and pass; filtering JSONL or tallying a field over a corpus; mining a Claude Code transcript for turns or calls; is this text already present; a repo sweep that skips no gitignored file; a Windows UTF-16/BOM log grep cannot find; a rate-capped transfer or hung job; a repeated ssh key/BatchMode one-liner, scp; do old and new behave the same; the latest backup or log, not ls sort tail; could a RED baseline ever fail; disk a deleted git worktree never gave back; duplicated CLAUDE.md sections; how many source files a codebase owns; which memory level holds a fact; how often a new guard would fire on real history, and was it right; a guard's finding judged against a control. --- # compuse-toolbox A small set of tested Python jigs for recurring computer-use chores. Reach for one BEFORE hand-rolling a throwaway `pgrep`/`awk`/`jq`/`json.loads` one-liner - the jig has already handled the edge cases (self-match, exit-code traps, wrapper argv) that the one-liner gets wrong. Each jig is a self-contained PEP 723 script: run it with `uv run` (uv provisions its deps) - the one exception is `gate`, which must be launched with plain `python3`, see its row below - and get its full arguments from `--help`. Run from the skill directory, or give the full path. The jigs sit in the skill's `scripts/` directory. **From a script you commit, name the marketplace clone, never the plugin cache.** The base directory a session announces is a version directory under `/cache/`: it names one plugin version, changes on every update, and is deleted 14 days after it is superseded. A script that hard-codes it, globs across its versions or picks one (`sort -V`, `tail -1`, `find -quit`) breaks, or quietly runs a stale copy - or a copy of a skill that has since moved to another plugin. The marketplace clone has no version in its path: ```bash TOOLBOX="${CLAUDE_CODE_PLUGIN_CACHE_DIR:-$HOME/.claude/plugins}/marketplaces/bitranox-skills/plugins/bitranox/skills/compuse-toolbox/scripts" [ -f "$TOOLBOX/ci_wait.py" ] || { echo "compuse-toolbox not found at $TOOLBOX - add it: /plugin marketplace add bitranox/bitranox-skills" >&2; exit 2; } uv run "$TOOLBOX/ci_wait.py" --sha "$(git rev-parse HEAD)" ``` The plugins root is `~/.claude/plugins` unless `CLAUDE_CODE_PLUGIN_CACHE_DIR` moves it; in Python build the same path from that variable or `Path.home()`. The clone is what `/plugin marketplace update` pulls, so it can be AHEAD of the version a running session loaded. A marketplace added from a local directory has no clone there: read its `installLocation` from `known_marketplaces.json` in the plugins root. Where no marketplace exists - CI, a server, a machine without Claude Code - copy the one file into the repository with a header naming its source path and plugin version, and refresh it on purpose. Such a script then runs that copy everywhere, workstations included - preferring the clone where it exists makes local runs and CI run different versions of the same jig. Never download it from a branch when the script runs: that executes whatever the branch holds at that moment. ## Tools | Tool | Use it when you would otherwise hand-roll... | Invoke | |---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `procsig` | `pgrep -f` / `pkill -f` - which self-matches the shell running it and can kill your own session | `uv run scripts/procsig.py --exe [--kill]` (exit 0 = a match other than itself, 1 = none, 2 = empty needle, unknown signal, no /proc, or a signal not delivered) | | `git_state` | a `git rev-parse` + `git status` branch/sync/dirty check before a risky commit or bulk op; or "which copies of this file across a tree are tracked-and-modified, gitignored, untracked, or outside any repo?" | `uv run scripts/git_state.py [REPO ...] [--root DIR] [--json]` / `--files CLAUDE.md --root DIR [--json]` | | `conflict_scan` | a `grep -rn '^<<<<<<<'` sweep for merge-conflict markers, one `path:line: text` row per marker (exit 0 clean / 1 markers / 2 a path or directory could not be read; a dangling or looping symlink is skipped with a stderr note, not an error; a symlinked directory met inside a walked tree is not followed and is named on stderr); a lone ======= outside a <<<<<<< ... >>>>>>> span is skipped only as a heading rule - a setext underline (text above, a blank line or end of file below) or a whole RST overline/title/underline block - and with text on both sides it still counts | `uv run scripts/conflict_scan.py [PATH ...]` | | `ci_wait` | waiting for GitHub Actions to finish on a commit you just pushed - every workflow that fired for it, not whichever shows up first - before tagging a release. Refuses a sha that is not the full 40 characters, because a short one silently matches nothing and the poll loop then spins to its deadline looking busy; an empty match is a verdict, not a keep-waiting, though a just-pushed commit gets a grace period (`--appear-grace`, 120s) to have runs at all. A FAILING `gh` gets a grace budget of its own instead of ending the wait, because an HTTP 502 from the API is weather and not a verdict; a sustained outage still ends it, reported as `error` with gh's message rather than as a timeout. An all-green answer is CONFIRMED after a short settle (`--settle`, 20s) before it is returned, because the runs for one push are not created at the same instant, so an early all-terminal poll can be a partial set read as the whole one; a failure is reported at once, since a later run cannot rescue it. The settle BOUNDS that window rather than closing it: a run created after the confirmation is outside what any wait can see, so raise `--settle` on a repo whose workflows register slowly. Runs are asked for by sha on the server, so an older run of that sha is never outside the `--limit` window; every `gh` call is bounded by a timeout and `--timeout` is a wall-clock deadline; a run that concluded `skipped` does not fail a push, but a push where every run was skipped is reported as failed (nothing ran). `--repo` is optional and falls back to the current directory's repo | `uv run scripts/ci_wait.py --sha $(git rev-parse HEAD) [--repo OWNER/REPO]` | | `ci_triage` | piping a build/CI log through `grep`/`sed`/`awk` to find the error lines | `python3 scripts/ci_triage.py --file LOG [--step NAME]` (NAME is the gh step name or the `##[group]` header text, and every job's copy of the step is triaged) (exit 0 clean, 1 error lines found or `--cmd` exited non-zero, 2 tool error or `--step` not found) | | `pushcheck` | **you are about to push and want to know whether this repo is even public, and whether the push PUBLISHES something private** - a local path, an internal hostname, an operator's username or an RFC1918 address. It answers BOTH halves: visibility comes from the REMOTE, never the directory name, because a tree that files repos under `public/` and `private/` folders is a convention that drifts - measured, a folder named `public/...` held a private repo, and a name-based guess is also wrong the other way, calling a public repo private and waving the scan through. Scans only ADDED lines, in EVERY commit of the range rather than the endpoint diff (a leak added and then removed inside the range is still published), so a commit that REMOVES a leak stays pushable. Every non-answer fails closed: unknown visibility, an unreadable range and an EMPTY range are refusals, and the report always states how many lines it read, because "no findings" after examining nothing is indistinguishable from a clean result. Documentation-safe values (RFC5737 ranges, `example.com`, loopback, `/home/user/`) are deliberately not findings; pass your own infrastructure names with `--denylist-file`, which is never shipped, and exclude a security fixture's own sample values with `--exclude` (a project that TESTS for private-looking strings necessarily contains them, and an exclusion that matches nothing is reported rather than silently ignored) | `uv run scripts/pushcheck.py --repo . --json`
`uv run scripts/pushcheck.py --range origin/main..HEAD --denylist-file ~/.config/infra.txt` | | `backstop` | **you kicked off a background agent or a long job and do not want to sit watching it** - what shouts at you if it hangs and never comes back, but stays quiet if it finished. Arms a deadline that alerts ONLY on non-completion, and REFUSES to arm when its exit signal is ALREADY true - the trap that makes a hand-rolled waiter report success on its first poll while covering nothing. Watches the last artifact the worker writes, a git HEAD moving off a base, or a sentinel. A done-file counts as finished only once it is NON-EMPTY and its size has HELD for one poll, so a worker that touches its report early and appends cannot make the backstop stand down mid-write. Refuses (exit 2) a non-finite or non-positive `--deadline`/`--interval`, a `--base` that is not a 7+ hex sha, and a `--repo` that is not the repository root (a subdirectory, or a nested checkout whose `.git` is gone, would read the parent's HEAD); a `--repo` that vanishes mid-run exits 2 (signal LOST), never a TIMEOUT | `uv run scripts/backstop.py --deadline 2400 --done-file report.md --cancel-file .done --label 'task 30'`
`uv run scripts/backstop.py --deadline 1800 --repo /path/to/worktree --base 8d9e72e` | | `enforced` | **a config setting is supposed to restrict something - does any code actually DECIDE on it, or is it only declared, parsed and read?** Classifies every mention: DECISION (compared to, or branched on) and CLAMP (a min/max cap) ENFORCE; declaration, config-file, plain reference, test, docstring and comment do not - so both-empty IS the answer rather than a hit count that cannot tell a reader from an enforcer. Catches the field that is typed, schema-validated and bounds nothing, which reads as safety because it is loud when malformed and mute when ignored. Whole-name AST matching, and it follows one alias hop. Exit 0 enforced, 1 parsed but never enforced, 2 not found or incomplete (an unreadable file or directory and no decision elsewhere) | `uv run scripts/enforced.py planner_kinds --root src/`
`uv run scripts/enforced.py on_auth_failure --root . --json` | | `confound` | **you changed a few things between runs, one number came out different, and you want to write down WHICH change caused it - can that table actually say?** Reports which pairwise comparisons may carry a causal claim and which are CONFOUNDED because more than one thing moved. `--claim disk` answers the sentence you were about to write and NAMES what else moved. Two rules easy to miss by eye: a setting recorded on one run and ABSENT on the other DIFFERS, and an isolated setting whose outcome did NOT move supports nothing - two identical runs have no difference for anything to have caused. It sees only confounds among the things you thought to RECORD, so it is a floor and never a proof. Every --arm starts with a LABEL; a missing label, a key given twice, an outcome on some arms but not all, and outcomes in different units under --outcome-tolerance are refused (exit 2) | `uv run scripts/confound.py --claim model --arm 'a model=opus tokens=23556 outcome=read 23554' --arm 'b model=fable tokens=23557 outcome=read 0'` | | `transcript_index` | **something you worked out in an old session but never wrote down** - full-text search across EVERY past Claude Code transcript at once, rather than opening them one at a time. Indexes narrated prose only: tool calls and their output are NOT indexed, so a miss means it was never said in words, not that it never happened | `uv run scripts/transcript_index.py index`
`uv run scripts/transcript_index.py search "zpool scrub"` (each word literal, all required; `--fts` for raw FTS5 syntax; exit 2 = query error or a query with no letter or digit, never a miss) | | `jsonl_grep` | a `json.loads` loop to filter a JSONL by type/role or extract a field - or a hand-rolled walk over a whole CORPUS of transcripts to learn what values a field really takes | `uv run scripts/jsonl_grep.py [--type ...]` / ` --type assistant --field message.model --count` (walks the `*.jsonl` below ``, or reads stdin; exit 3 = read nothing, 2 = bad arguments or a named path missing beside one that was read; any existing path is read, so `<(cmd)` works; JSON null counts as `null`) | | `transcript_tail` | parsing a Claude Code transcript JSONL - for the last user/assistant text, or for the WHOLE session: every text turn, or every call of one named tool with its input, each carrying the JSONL line it came from | `uv run scripts/transcript_tail.py [--role ...]` / `--all` (every turn; each row has `kind` prompt/tool_result/text) / `--all --role user --prompts-only` (what a person typed) / `--tool Agent` (every call, with input) / `--json` | | `claim_check` | a `grep -c` / `grep -l` sweep to decide whether some text is already present in a set of files | `uv run scripts/claim_check.py FILE... --pattern P --control C` | | `grep_all` | a repo-wide `grep -r` that must be COMPLETE - it silently skips gitignored files | `uv run scripts/grep_all.py PATTERN [PATH ...] [--glob G]` | | `gate` | running gates then acting on the result - ` \| grep summary && git push`. Also the three ways a CORRECT exit status still proves nothing: a shared default log two concurrent runs both append to, a filter that matched ZERO tests, which exits 0 and reads as a pass, and - when it runs in the BACKGROUND - a completion notification that reports THIS runner's status rather than the gate's, so read the `[FAIL] (rc=N)` line or the log | `python3 scripts/gate.py [--log L] [--summary RE] --gate C [--gate C ...] [--then C]` (NOT `uv run` - see below; the default log is per-invocation, and a gate that ran 0 tests is REFUSED - pytest, cargo, unittest and go test are recognised, any other runner is judged on its exit status alone; a malformed invocation is a usage error, exit 2; exit = the single failing gate's OWN code, so a taxonomy code such as 2 survives, else 1) | | `winlog` | `iconv`/`strings -e l` on a WINDOWS log whose text `grep` cannot find, or that `cat`s with spaces between the letters - UTF-16, BOM, or MIXED encodings | `uv run scripts/winlog.py read FILE [--grep DONE-OK] [--tail 20] [--json]` (exit 1 = no match) | | `transfer` | a `curl --limit-rate` / `rsync --bwlimit` big-file download or host-to-host copy that must respect a REAL speed limit (the units differ per tool: `curl 8M` is 8 MiB/s = 67 Mbit, `rsync --bwlimit` is KiB/s), or judging whether a long job has hung | `python3 scripts/transfer.py fetch URL --rate 8Mbit` / `push F user@host:/d/ --rate 8Mbit` / `check --file F --pid N` (`--pid` is Linux-only; `--cmd CMD` runs with no shell - wrap a pipeline in `sh -c '...'`) | | `fleet_ssh` | an `ssh -i -o BatchMode=yes -o ConnectTimeout=N` one-liner retyped per call, or an scp whose login user has to go INSIDE the path (`root@host:/p`) and gets forgotten | `uv run scripts/fleet_ssh.py [--user U] HOST [cmd]` / `--scp SRC DST` (exactly two paths; more is refused, exit 2) (add `--trust-changing-host-keys` for a fleet you reimage) | | `diffbehave` | a loop that runs an OLD and a NEW version of a script (or two CLIs meant to be equivalent) on the same inputs and diffs stdout/stderr/exit code by eye - or proving a hand-rolled detector is not a rubber stamp that always says SAME. A side that did not run at all (not found, exit 126/127, a missing script operand) is ERROR, exit 2, never DIFFER, so a typo cannot satisfy `--expect-differ` | `python3 scripts/diffbehave.py --a "OLD_CMD" --b "NEW_CMD" --case-file CASES.jsonl` / `--expect-differ N` (known-negative check) | | `adjudicate` | confirming a claim about a guard by running the ONE input that shows it. A guard that fires on your probe has told you nothing until you know it does NOT fire on an input differing only in the thing claimed - without that second run, "it fired" and "it fires on everything" are the same observation. Runs the subject on a probe AND a control and scores the pair in THREE buckets: CONFIRMED (probe fired, control did not), REFUTED (probe did not fire), UNUSABLE (both fired - the control did not discriminate, so nothing was measured). UNUSABLE is the one that gets lost: folded into REFUTED it reads as a clean sweep over broken controls, so any UNUSABLE claim makes the whole run exit 1 and the report cannot be mistaken for all-clear | `python3 scripts/adjudicate.py --hook HOOK.py --name N --probe STDIN --control STDIN` / `--claim-file CLAIMS.jsonl` / `--fired-when nonzero\|match --fired-pattern RX` / `--json` (exit 1 = a control did not discriminate; exit 2 = usage error, or a side timed out / could not be launched - verdict ERROR, never counted as fired, or a non-positive `--timeout`; NOT `uv run`, whose env lacks a hook's optional deps) | | `newest` | "which backup/log/snapshot is the latest?" answered with `ls \| sort \| tail -1` - a longer name sharing the same date prefix sorts AFTER a shorter, newer one, so it silently picks the wrong file OR directory; ALSO when a later pass (compression, re-encoding, a fixup job) rewrote the files, because mtime then records THAT pass and not the content - the default run warns when the two keys disagree about the answer; under `--name-timestamp` the reported age comes from the stamp too (read as UTC, `Z` or not, so a local-time stamp reports an age off by the UTC offset), and a stamped path that no longer exists is skipped, never picked | `uv run scripts/newest.py /backups/nightly-*` / `--all` (every match, newest first) / `--json` / `--name-timestamp` (key on a fixed-width stamp in the FILENAME) | | `redcheck` | reading by hand every notes/rules file a machine feeds an agent at startup, to answer "does the agent ALREADY know this, so my baseline/RED prompt cannot really fail?" - it assembles that startup context itself (the `CLAUDE.md` + `CLAUDE.local.md` chain and memory bodies, gitignored ones included) and names the file that already teaches your scenario; also flags a scenario that hands over its own answer (ships in `process-test-driven-development`, not here) | `uv run ../process-test-driven-development/scripts/redcheck.py --scenario S.txt --corpus-cascade . --json` (exit 1 = already covered; 3 = a named corpus (either flag) assembled 0 documents, or an --answer yielded no terms) / `--answer A.txt --corpus docs/` | | `wtclean` | `du \| sort -rh` then `rm -rf` hunting for the disk space a DELETED worktree never gave back - `git worktree remove` drops the checkout and leaves its per-topic build cache sitting outside it, gigabytes each, listed by nothing (ships in `git-worktrees`, not here) | `uv run ../git-worktrees/scripts/wtclean.py my-feature` (plan, with sizes) / `my-feature --apply` / `--cache-dir DIR` | | `claudemd_variance` | "which `## ` sections are duplicated across my CLAUDE.md files, and where should they live?" - hand-splitting, hashing and grouping them, then guessing the common ancestor instead of computing it (ships in `meta-consolidate-claude-md`, not here) | `uv run ../meta-consolidate-claude-md/scripts/claudemd_variance.py --root ~/src` / `--json` / `--min-members 1` | | `srccount` | "how big is this codebase - how many source files do we actually own?" answered with `find DIR -name '*.py' -not -path '*/.venv/*' \| wc -l`. That exclusion list IS the instrument: vendored trees outnumber first-party source by one to two orders of magnitude, so whatever it misses (`venv-*/`, `site-packages/`, a checked-in upstream tree) DOMINATES the answer instead of nudging it, and the command still exits 0 with a confident wrong number. Excludes on EVIDENCE, not just names - a dir holding `pyvenv.cfg` or `CACHEDIR.TAG` is a venv or a build cache whatever it is called - always reports the excluded share, and always breaks the count down per extension AND per directory so a dominant subtree or a wrong `--ext` cannot be quoted by mistake. A directory it cannot read is "could not count" (exit 2, listed as skipped), never a smaller number. `--audit` asks the other question: is that skip list still right for THIS tree | `uv run scripts/srccount.py --root DIR [--root DIR2] [--ext .py] [--json]` / `--audit --root DIR` (exit 1 = nothing matched in ANY root, usually the wrong `--ext`) | | `mem_levels` | "which curated memory levels exist, what sits at each, and which level holds this fact?" answered by walking every `CLAUDE.local.md` with a hand-rolled `mem:` regex - a `[a-z0-9-]+` class does not merely truncate a DOTTED slug, it fails to match the line at all, so the pointer goes invisible and its body reads as an orphan | `uv run scripts/mem_levels.py --root ANCHOR [--slug S] [--json]` (exit 1 = no level holds that slug, 2 = --root is not a tree anchor or a level could not be read) | | `anchor_edit` | a Python one-liner that edits a file by `str.replace`, `partition`, or a span computed between two markers, in a SCRIPT or across many files - the interactive Edit tool already refuses a non-unique anchor, these do not. All three have success-shaped no-match branches, so a missed anchor writes a file that looks edited and is not, or edits the wrong one entirely. Refuses an absent or ambiguous anchor, makes a span state how many lines it removes and what must survive, splices the new text verbatim, and backs up (byte-exact) a file git could not restore - uncommitted, skip-worktree and assume-unchanged work included. Keeps CRLF line endings; exit 1 = refused, 2 = usage or IO error. `insert` takes `--after\|--before` and **`--after` is the DEFAULT**, so an omitted direction lands the text AFTER the anchor: to PRECEDE a block, anchor on its opening line and pass `--before` | `uv run scripts/anchor_edit.py replace F --anchor-file old.txt --new-file new.txt` / `insert F --anchor-file a.txt --new-file n.txt --before` / `replace-span F --start-file s.txt --end-file e.txt --new-text '' --expect-removed-lines 3 --must-keep 'def survivor('` / `--json` / `--dry-run` | | `mutation_arm` | "does this test actually assert anything?" - proving a test is not vacuous by breaking the code and requiring it to go red. Hand-rolling the arm is where it goes wrong: the verdict gets read off a grep of the log, where a `pytest.raises(X)` SOURCE line echoed in the traceback makes X look raised while the summary says DID NOT RAISE; the arm fails on an EARLIER assertion and reads as the one you meant; and a single mutation is absorbed by layered validation, so a covered line reads as uncovered. Mutates by exact anchor (several at once, as ONE arm), runs the named test, reports the failing ASSERTION from pytest's summary, and restores from a copy taken first - never `git checkout --`, which discards uncommitted work. `--timeout` bounds the arm, because a mutation can make a test SPIN rather than fail when the test's only exit is the behaviour being mutated: unbounded, one such arm hangs the whole battery and reports nothing, and killing it by hand skips the restore and leaves a mutated file on disk. A timeout is its own verdict, never `killed`, and the restore still runs when it fires - the copy is taken before the first edit and put back in a `finally`, so a bounded arm never leaves a mutated file behind the way a hand-kill does. Every arm also runs with bytecode writing OFF and purges the cached `.pyc` for each mutated source before and after, and REFUSES rather than run when one cannot be removed: a length-preserving mutation applied in the same second the file was last edited leaves a cache that the restored source does not invalidate, so a later run fails against bytecode no source file contains while grep and `inspect.getsource` agree the code is right, and a cache predating the mutation is served IN PLACE of it, which measured SURVIVED 6 of 6 while the mutant never ran | `.venv/bin/python scripts/mutation_arm.py --mutate src/x.py old.txt new.txt --test tests/t.py::test_y --timeout 90` (the PROJECT's interpreter, which has pytest; under `uv run` every arm is INCONCLUSIVE) / repeat `--mutate` for one multi-layer arm / `--json`. Exit 0 killed, 1 survived, 2 the arm never ran (including a pytest that exited 1 without reporting a failure), timed out, could not write the source, a file was not UTF-8, or the restore failed | | `guard_replay` | shipping a PreToolUse hook or guard on the strength of its unit tests. They prove it fires on the hazard you thought of; they cannot tell you whether it is QUIET on ordinary work, nor whether the times it speaks are times worth speaking - and those are two different questions, both of which have been answered wrong here on shipped hooks. Replays every real call in your Claude Code transcript corpus through the guard's OWN function - Bash by default, or `--tool Write` / `--tool Edit` to price a guard on what gets WRITTEN rather than run (Edit contributes the REPLACEMENT text, since that is what is about to land) - or `--field file_path` to price a guard on WHERE a write lands rather than on its text, because a path guard replayed on content measures the wrong question while reporting a confident rate; a tool whose payload it cannot read REFUSES and names the ones it knows, because reporting an empty corpus blames your history for a question the tool could not ask - with the cwd each command actually ran under (a guard that resolves paths answers differently per session dir), and reports the FIRING RATE and the PRECISION separately: how much of ordinary work it would interrupt, and how many of those calls a gate really refused. `--sample` prints firings to read, because a percentage tells you volume and never whether the warnings are right - spread evenly across the corpus, because the walk is file by file and so a first-N sample is one PROJECT's habits wearing the whole run's clothes. A sample is for seeing what the firings LOOK like; it cannot establish a ratio among them. Reading 40 of 557 put a residual at ~10 percent where all 557 put it at ~2, and the 517 unread held the shapes that mattered - so when a proportion is the answer you need, classify every firing. The corpus is the Claude Code transcript JSONL under `~/.claude/projects` (`--root` points elsewhere) - NOT shell history, which carries neither a cwd nor any record of what a gate did. Your predicate is called as `f(command)`, or with a second argument chosen by the parameter's NAME - `cwd` receives the call's directory and `tool_name` the tool being replayed, positional or keyword-only; any other name is left at its default - and anything truthy counts as a firing | `uv run scripts/guard_replay.py --module ../../hooks/my-guard.py --func notice` / `--tool Write` / `--tool Edit --field file_path` / `--sample 5` / `--root DIR` / `--json` (exit 1 = never fired, 2 = usage error: tool or field unreadable, bad --block-pattern, module will not import, 3 = corpus unread, 4 = the predicate raised on some command) | | `corpus_prompts` | pricing a rule that reads a PROMPT - a router trigger, a nudge, a classifier gate - by hand-walking `~/.claude/projects` for what people actually typed. `guard_replay` answers the same question for tool CALLS and cannot answer it here: a prompt has no gate, so its precision column means nothing, and the question becomes which prompts a rule speaks on. It diffs two predicates by their firing SETS rather than their counts, because two rules can fire the same number of times on different prompts, so a count diff of zero is exactly the shape that hides a narrowing that also admitted something new. Which records count is measured rather than assumed: most `type: user` records are the assistant's own tool traffic wearing the user role, `entrypoint` separates a person at a terminal from a headless SDK node, and `origin` is too rare on real transcripts to filter on. Your predicate is called as `f(text)` - the prompt TEXT alone, no record and no second argument, unlike guard_replay's `f(command, cwd)`, because a prompt has no cwd that changes its meaning. The prompts come back RAW: whether one is a slash command or an envelope is the caller's rule, and a second copy of that judgement here would drift from the one the hooks use | `uv run scripts/corpus_prompts.py --count`
`uv run scripts/corpus_prompts.py --module ../../hooks/g.py --func notice --module-b old.py --json` (exit 1 = the corpus held no prompt; 2 = a missing --root, a predicate option without its module, --count with --module, or an unreadable transcript; `--sample N` shows N FIRINGS) | | `mdwrap` | re-flowing ONE paragraph of a long markdown file (TODO, design note, CLAUDE.md) to a column width by hand, and rewrapping the neighbours by accident - it takes an ANCHOR rather than a line-length rule, refuses an anchor that is missing or matches two paragraphs, and a paragraph that is a list, a heading, a blockquote, inside a code fence or holds a hard line break, and any wrap that would leave a line Markdown reads as a new block (a `---`/`===` underline, a thematic break, a fence, an HTML tag), keeps the file's line endings, and reports the changed line range. A one-item `* `/`+ `/`1. ` list counts as a list, and no wrapped line ends in a backslash (a hard break). Writes atomically, or in place for a hard-linked file or a directory that refuses the temp file (JSON `write`). Dry-run unless `--apply` (exit 1 = refused, 2 = error) | `uv run scripts/mdwrap.py --file TODO.md --anchor 'NEXT STEP:' --width 100` / `--apply` / `--json` | | `renamescope` | `sed -i 's/old/new/g'` across a file without knowing WHICH functions the hits land in - you give it the functions you SET OUT to change and it reports the hits that fall outside them, which is the finding, because there the substitution does not break, it changes meaning. It REPORTS only; the rename stays yours to run | `uv run scripts/renamescope.py src/net.py --name mac --intended _apply_iface` / `--regex RE` (indent with `[ \t]*`, not `\s*`) / `--intended file.py::func` for a name defined in several files / `--json` | | `statusrot` | a memory entry still saying "shipped" / "deployed" / "TODO, not started" / "tracked as #34" long after that stopped being true - it sweeps the fact store for status claims and reports each as a CANDIDATE needing confirmation, never a verdict (ships in `meta-dream-tree`, not here) | `uv run ../meta-dream-tree/statusrot.py scan --chain DIR` (or `--level FILE`) / `--json` | | `factedit` | rewording a memory fact's always-loaded hook or replacing its body by hand - which level owns the slug, is the new hook under the cap, and does it still parse (ships in `meta-dream-tree`, not here) | `uv run ../meta-dream-tree/factedit.py show --slug SLUG` / `check --hook '...'` | Per-tool arguments live in each tool's `--help` (loaded only when used, so this index stays small). ## Why a jig over a one-liner - **`procsig` cannot self-match.** It reads `/proc` directly and always excludes its own process and every ancestor, so it structurally cannot signal the shell that launched it - the failure mode `pkill -f X` has whenever the shell's own command line contains `X`. Its exit code ignores itself and its ancestors too, so `procsig --cmdline X && echo running` is not fooled by its own argv. - **`procsig --cmdline` also never searches a command STRING a shell was handed.** Exclusion covers only self and ancestors, and a SIBLING shell quoting the needle is neither: one such match killed a live command mid-run. So `bash -c ''` and every equivalent is searched only up to the flag that introduces the string, and an argv that MIGHT hold one but cannot be classified with certainty is skipped entirely rather than assumed harmless. The bias is deliberate and one-way - a miss costs you one `kill `, a false match kills the wrong process - so if an expected process is absent from the listing, match it with `--exe` or `--comm`. Full rules in the tool's `--help`. - **`claim_check` refuses to answer "no" blindly.** A content check's dangerous result is the NEGATIVE, because "not present" and "I never really looked" print the same. So every query carries a CONTROL pattern that MUST match; if the control misses, the verdict is BROKEN (exit 2), not ABSENT (exit 1), and no answer is given. A path it could not read - a typo, a binary, UTF-16 without a BOM - blocks ABSENT the same way, because a control hit in the other files says nothing about one never read: with no hit anywhere the verdict is BROKEN. A hit in the files it DID read is still PRESENT (exit 0), with the unread paths listed on stderr as `skipped:`, since an unread file cannot undo a match. That converts a silent false all-clear into a loud failure - the exact shape behind a `grep -c` whose `file:count` output was never parsed, and a threshold set above the whole distribution so no pair could ever match. - **`grep_all` cannot silently under-report.** In a Claude Code session `grep` routes to a gitignore-aware backend, so a repo-wide sweep drops ignored files and the miss reads as a clean result. `grep_all` walks the filesystem itself and then reports how many of its hits git considers ignored, which is exactly the number a normal grep would have missed. Measured on this tree: 73 pointer blocks found, 55 of them gitignored, against 17 from the session grep. A zero in that stderr line means the two agree and your earlier grep was safe. "Ignored" is judged from where you pointed it: a match in a nested repo or linked worktree inside a directory the outer repo ignores counts as missed when you searched the outer repo. When git cannot answer - no git, a failing check-ignore, or a repo git refuses to read (dubious ownership, a broken `.git` file) - the line says the count is UNKNOWN and the exit is 2, and every file or directory it could not read is listed as NOT READ. - **`gate` reports the gate's OWN exit status, never a pipe's.** ` | grep summary && git push` exits with `grep`'s status, so a red gate whose log still holds a green-looking line reads as success and the `&&` fires; writing `rc=$?` after the pipe records the same wrong status. `gate` runs each command with no shell and no pipe, so `returncode` is the gate's, sends output to a log, and greps the summary from that log AFTERWARDS - then runs `--then` only on a real pass. The plugin already BLOCKS the masked form (`hooks/block-masked-gate-exit.py`); this is the safe form to reach for instead of hand-rolling per-gate `rc=$?` capture and temp files each time. Launch this one with plain `python3`, not `uv run`: it declares no dependencies, and `uv run` puts its own ephemeral interpreter on the environment the CHILD gates inherit - measured, a gate shelling out to `python3 -m pytest` then died with `No module named pytest` and reported a false RED. The same holds for `ci_triage --cmd`, `transfer check --cmd` and `diffbehave`, which run your commands too, and for `adjudicate`, which runs the hook on its own interpreter (under `uv run`, one without the hook's optional PyYAML/lxml); each declares `LAUNCH_WITH = "python3"`, which is what the nudge suggests. Every other jig here is fine under `uv run`. - **`winlog` decodes a Windows log per SEGMENT, because one file can hold two encodings.** PowerShell writes UTF-16 from `Tee-Object`/`Out-File` but UTF-8 or ANSI from `Set-Content`, so a log created by one and appended to by the other is MIXED - with no BOM to announce it. Nothing errors: `grep` just finds nothing and `cat` prints `D O N E - O K`. A wait loop keyed on that marker then reports "not finished" for a run that finished, and times out on SUCCESS exactly as it would on failure. `iconv -f UTF-16LE` is not the fix: on a real mixed log it decoded the UTF-16 tail fine, exited 0, and silently turned the ASCII head into CJK mojibake - the header and the `running as NT-AUTORITAET\SYSTEM` line, which was the evidence that the task ran elevated. Partial, silent, and reported as success. `file` calls such a log plain `data`, so it will not even confirm the diagnosis. `winlog` decodes each segment on its own, keeps both halves (umlauts included), normalizes CRLF, and prints what it found on stderr - naming a MIXED file so it gets fixed at the WRITER instead of worked around in every reader. - **`fleet_ssh` keeps the key and the login the same identity.** scp carries the login user INSIDE the path and has no `--user` flag, so a wrapper that reads `--user` only to pick the key hands scp a destination naming nobody: it logs in as the LOCAL user while offering the other user's key. On a host that accepts root and refuses your account that is `Permission denied (publickey)` from a command line where the flag looks honoured. It also keeps `BatchMode=yes` on always, because `-i ` alone still falls back to a PASSWORD PROMPT when the key is rejected and hangs an unattended run, and it picks a key by READABILITY - a shared key path can exist and be root-only on this box, which fails as `Permission denied` with EMPTY stdout far from the cause. Host-key checking stays at ssh's strict default; `--trust-changing-host-keys` is the opt-in for a fleet you reimage, and it keeps that churn in a separate known-hosts file rather than `/dev/null`, which would make every connect a first connect. It drops a changed key's stale entry, under the name ssh says it recorded (an ssh_config alias or a non-default port is stored under the resolved name), and says so only when the file changed; it never re-runs the command: with strict checking off a changed key, and even a key marked @revoked, is only a warning and the command has already RUN, so a retry would apply it twice. - **`git_state --files` cannot conflate tracked-and-ignored.** `git status --porcelain -- ` is EMPTY for a gitignored file and for a tracked-clean file ALIKE, so a naive per-file check reads them as the same thing - and only the tracked one is restorable with `git checkout`. `--files` classifies with `git ls-files --error-unmatch` (tracked) and `git check-ignore --no-index` (ignored) instead, and asks `check-ignore` only about the paths `ls-files` did NOT report tracked - so TRACKED WINS the tracked-and-ignored case deliberately, not by relying on git's own default (which happens to also hide tracked files from `check-ignore`, but only without `--no-index`). Batches at most 4 git calls PER REPO regardless of file count, never 2 per file. `git_state`'s repo-state mode reads porcelain v2 (no `rev-parse --short` 2-rev footgun). - **`diffbehave` answers "does this behave differently" by RUNNING both sides, never by reading them.** An `ast.dump` diff is identifier-sensitive, so a rename alone reads as a behaviour change, and neither a line count nor a `grep -c` executes anything either - none of the three can answer the question, only running both sides on the same input and diffing what happened can. Its `--expect-differ N` flag is the other half: a hand-rolled detector verified only against cases where it already agrees has proved nothing, so the tool fails unless at least N cases come back DIFFER - a comparison that can only ever say AGREE is a rubber stamp, not a check. A case where EITHER side did not run (it could not be started, or exited 126/127 as a launcher does for not-found and not-executable) is ERROR and exits 2 - never AGREE, and never the DIFFER a typo on one side would otherwise hand `--expect-differ`. Both sides timing out is ERROR too; one side timing out while the other answers is DIFFER, because that side ran and hung. - **`adjudicate` scores a claim against a CONTROL, and keeps three answers rather than two.** Running the one input that shows a claim proves the claim and the guard are compatible, not that the guard is discriminating - so it runs a second input differing only in the thing claimed. The third bucket is the point: when BOTH sides fire, the control did not discriminate and the run measured nothing, which is not the same as the claim being refuted. Collapsing the two reported 10 claims refuted where the truth was 7 refuted plus 3 never tested, and a report of refuted claims is acted on by deleting the finding. Any UNUSABLE claim exits 1 for that reason. A side that times out or cannot be launched is a fourth verdict, ERROR (exit 2), never scored as firing, since a hung probe would otherwise read CONFIRMED. It also says WHICH END is at fault, because two different causes give that one verdict: one unusable claim among several is a control that does not differ in the claimed way, while EVERY claim unusable is the subject firing on every input - which under the default `--fired-when output` is what a program that always prints a banner looks like, and the fix there is `--fired-when nonzero` or `match`, not a rewritten control. Re-run it after every fix: a fix that turns the suite green has twice not closed the finding it was for. - **`newest` never compares names.** `ls | sort | tail -1` looks like "the newest" and is not: a longer name sharing the same date prefix sorts AFTER a shorter one, so an extra word beats the date. Pruning the wrong file this way is loud and gets noticed; VERIFYING against the wrong baseline is silent, which is the expensive half. `newest` sorts by mtime only (files and directories alike), breaks a genuine tie by input order - deterministic, not directory-listing luck - and reports the AGE of what it picked, because the newest member of a stale set is still stale and a bare path gives no way to notice that. - **`redcheck` catches a RED that cannot fail, which reads exactly like one that can.** A scenario-based RED (a prompt, not code) fails for two reasons a code RED never has: the agent is handed a config cascade and shipped reference material before it ever sees the scenario, so a lesson already documented there gets answered from that, not from the scenario; and prose that names the trap or pre-diagnoses the cause hands over its own answer. Both make a RED pass for the wrong reason with nothing in the transcript to say so. `redcheck` checks a scenario for both leaks BEFORE an agent dispatch is spent on it, reporting which corpus document already teaches the lesson or which phrase telegraphs the answer. `--corpus-cascade DIR` assembles the first corpus for you rather than leaving you to enumerate it: the `CLAUDE.md` and `CLAUDE.local.md` chain from DIR up to the filesystem root plus the memory fact bodies on it, read by walking the filesystem, because those files are routinely gitignored and a gitignore-aware search returns a small corpus in which everything looks clean. A hit is strong evidence and names the file; a clean result only means not caught, since term overlap cannot see a paraphrase; exit 3 means the corpus was empty and nothing was checked. Ships in `process-test-driven-development`, indexed here so this table stays the one place that answers "is there already a tool for this?". - **`wtclean` reclaims what removing a worktree leaves behind, which nothing else lists.** A per-worktree build cache is deliberately kept OUTSIDE the checkout - that is the point of giving each worktree its own - so `git worktree remove` does not touch it and it survives every cleanup at gigabytes a time. Nothing enumerates them, so they are normally found by running out of disk and then hunting by hand with `du` and `rm -rf`, which is the dangerous way to do it. `wtclean` names the worktree and its caches together with sizes, deletes nothing until `--apply`, then removes exactly what it listed rather than re-scanning; it refuses a symlinked target, a checkout holding uncommitted work, and a topic that is a path rather than a name. Ships in `git-worktrees`, indexed here so this table stays the one place that answers "is there already a tool for this?". - **`claudemd_variance` computes a lift target instead of eyeballing one.** Deduplicating CLAUDE.md content without checking WHERE it truly belongs is how a false line gets promoted to an ancestor that binds every repo below - the common ancestor of a group's member paths is not the directory you happened to be looking at, and the common ancestor of a SINGLE file is its own parent directory, never the filesystem root. `claudemd_variance` splits every CLAUDE.md into `## ` sections, hashes each body (whitespace-normalised, so a reflow does not read as a different variant), groups the identical ones, and reports each group's true common ancestor plus the largest variant's share - the same "60-75% means one dominant version" signal `bitranox:meta-consolidate-claude-md`'s own variance table keys on. It enumerates by a plain filesystem WALK and never shells out at all, so - unlike a hand-rolled version built on the session's own `grep` - it cannot silently drop a gitignored CLAUDE.md. Ships in `meta-consolidate-claude-md`, indexed here so this table stays the one place that answers "is there already a tool for this?". - **`transcript_tail` reads a FINISHED session, not only its last turn.** A record's content shape varies - user `content` is a plain string or a list of `tool_result` blocks, assistant `content` a list of thinking/text/tool_use blocks - so a one-line parser flattens the wrong one and returns empty without saying so. That is the tail mode. The whole-transcript modes exist because the tail alone cannot answer the questions a session review actually asks: "what did the user ask across the run?" (`--all --role user --prompts-only`: most user records are tool output, not prompts) and "which `Agent` dispatches went out, with what input?" both need every record, and answering them from the tail means writing one throwaway extractor per question - four of them in a single session, because a raw field dump (`jsonl_grep --field message.content`) hands back block JSON rather than the text. `--all` returns every text turn and `--tool NAME` every call of one tool with its input, each row carrying the 1-based JSONL LINE it came from, so a finding is addressable (`sed -n 'p'`) instead of searched for again. The line count includes blank and unparseable lines for exactly that reason, an unparseable one is counted onto stderr rather than vanishing, and a mode that matched nothing exits 1 instead of printing nothing and succeeding. - **`jsonl_grep --count` answers a corpus question directly, and says what it reached.** "What values does this field actually take across every transcript?" is the DIRECT instrument for questions that otherwise get settled by inference, and answering it meant hand-rolling a walk over ~1500 files each time - one session built three designs for a value the corpus named in one command once it was finally asked. A NEGATIVE is the dangerous result, because "the field holds nothing" and "I never really looked" print the same, so the scan reports how many files it READ on stderr and exits 3 when it read none. Point it at a directory and it walks the `*.jsonl` below it, streaming each file rather than loading it. - **`guard_replay`'s sample shows you shapes, never proportions.** The corpus is walked file by file, so firings arrive grouped by project. The sample is therefore drawn EVENLY across them rather than from the front, which stops it being whichever project sorts first - but a spread sample is still a sample. Measured 2026-08-30: 40 of 557 firings put a residual at ~10 percent and all 557 put it at ~2, and the unread remainder held four firings that were a live regression in the guard being measured. Read the sample to learn what the firings look like, then classify the whole set when the answer is a ratio or a residual. - **`guard_replay` asks the second question too.** A guard's unit tests are written from the same imagination as the guard, so they cannot report its rate on real work or its precision when it speaks. Both have been measured wrong here after the tests were green: one arm fired on 7.8% of 60,517 real commands because routine nested-sub-repo work is structurally identical to the hazard, and a later version was checked for its RATE alone, leaving 131 of its 344 firings with nothing to warn about. Rate and precision are separate columns for that reason. Read the precision figure for what it asks - "did a GATE refuse this call" is the right question for a guard about commands that cannot succeed as written, and the wrong one for a guard whose hazard is a plausible-but-wrong RESULT, which is never followed by a block and scores 0% while being useful. - **The others encode the trap.** `ci_triage` strips ANSI, isolates a step (exit 2 if the step is absent, never a silent whole-log fallback) and fails a `--cmd` that exits non-zero even when it printed no keyword; `ci_wait` refuses a short sha before it polls, so the loop cannot spin on a filter that matches nothing; `jsonl_grep` parses JSONL by field, not by fragile text slicing. ## Building or enhancing a jig Each jig is one import-safe core function plus a thin `argparse` CLI, shipped with a pytest test. When a jig is insufficient in use, ENHANCE it (add a RED regression test for the gap, then fix), rather than hand-rolling around it - so the tool matures and cannot silently regress.