troupe-standup/docs/TOOLS.md

The instruments

Generated by tools/tool_map.py from the tree it is asked to read. Do not edit by hand: python3 tools/tool_map.py --repo . --write docs/TOOLS.md re-renders it, and --check grades it (rc 1 when the document and the tree disagree). Every cell below is derived, never typed -- purpose from the module docstring, flags from the tool's own --help, probe rows from selftest_sweep.py's tables, the gate leg from verify.py's LEGS.

23 tools, 23 with a --help oracle. Probes are read as read-refusal / not-utf8 / malformed-input rows; a - means that axis does not name the tool.

tool	what it grades	flags	probes	gate leg
append_only_audit.py	measure the repo-wide append-only invariant from git objects.	--repo --json --selftest --progress	1 / 0 / 1	-
append_only_owners.py	the SECOND instrument for the append-only invariant: was a replaced line ANOTHER party's line?	--json --selftest	1 / 1 / 2	-
census_row_delta.py	row-level diff of two doc_census_check.py censuses.	--key --keys --verbose --selftest --json	1 / 1 / 2	-
check_lint.py	grade a Ralph-loop CHECK: line before it is run.	--selftest --ralph-dir --log --check --json --quiet --verbose --all --fail-on-fault	1 / 0 / 2	-
checkin_check.py	the gate on the check-in contract, which nothing measured.	--repo --dir --roster --today --gaps --since --json --baseline --emit-baseline --fail --selftest	1 / 1 / 1	checkin
citation_hash_class.py	resolve every hex token in a corpus to its hash family, and flag the tokens that carry no stated class.	--repo --rev --corpus --json --window --min-len --only --context --siblings --selftest	1 / 0 / 1	-
citation_resolve_check.py	does every <file>:<line> citation in this archive's prose actually resolve, and to which file?	--repo --rev --corpus --json --only --context --selftest	1 / 0 / 1	-
doc_census_check.py	does a tool's own docstring census match the census that tool PRINTS?	--repo --rev --tools --json --no-run --fail --vocab --save-vocab --selftest	1 / 0 / 1	-
doc_command_check.py	a command a docstring tells you to run must be a command the tool still accepts.	--repo --rev --tools --json --fail --selftest	1 / 0 / 1	doc-commands
gate_blame.py	which landing turned a gate leg red?	--repo --leg --range --ref --queue --index --timeout --json --quiet --selftest	1 / 0 / 1	-
import_resolve_check.py	a committed test file must bind the module it imports to the REPOSITORY, not to a path on the host that wrote it.	--repo --rev --all-files --import-probe --json --quiet --selftest	1 / 0 / 1	import-resolve
landing_check.py	is every file at this revision actually served by the forge?	--repo --rev --branch --base-url --path --max-bytes --timeout --json --quiet --selftest	1 / 0 / 1	-
manifest_audit.py	does an artifact's files.sha256 still describe the bytes beside it?	--root --baseline --strict --fail --json --quiet --selftest	1 / 0 / 2	-
path_claim_check.py	does every in-namespace path this archive names exist at this revision?	--repo --rev --corpus --json --only --context --fail-on-missing --baseline --selftest	1 / 0 / 1	path-claims
queue_append_audit.py	was the queue's index current IN THE TREE of every commit that touched the queue?	--repo --queue --index --from --to --all --guard --timeout --json --selftest	1 / 0 / 1	append-audit
queue_claim_check.py	the claim check for WORK-QUEUE.md, shipped with its tests.	--queue --json --git --validate --selftest --fail-on-stale --explain --census	1 / 1 / 1	-
queue_index.py	the work queue's table of contents, and the gate that it is current.	--repo --queue --index --json --write --check --outside --selftest	1 / 1 / 1	index-current
reply_check.py	does every reply file's own header agree with its own name?	--repo --dir --roster --head-lines --json --baseline --emit-baseline	1 / 0 / 1	reply-headings
selftest_sweep.py	every instrument proves itself, in one command, and the number it advertises is the number it prints.	--repo --tools-dir --timeout --json --baseline --no-baseline --write-baseline --quiet --verbose --selftest	1 / 0 / 1	selftest-sweep
served_drift_check.py	does the host actually serve the tree at this revision?	--root --rev --base-url --prefix --exclude --max-bytes --timeout --json --quiet --selftest	1 / 0 / 1	-
tool_map.py	the instruments get a map, and the map is generated from the tree.	--repo --rev --write --check --json --selftest	1 / 0 / 1	-
verify.py	the HOME the index gate did not have: one command, nine legs, one exit code, and a row per leg so a partial run cannot look like a clean one.	--repo --queue --index --checkin-day --fast --timeout --json --quiet --selftest	1 / 0 / 1	-
write_probe.py	Measure the WRITE end of every tool in tools/: --json PATH at a target the host cannot write.	--repo --only --timeout --json --selftest --verbose	1 / 0 / 1	write-axis

The gate

python3 tools/verify.py --repo . runs the legs below and prints one line each; a leg resolves its tool inside the repo it grades. The slow legs are dropped by --fast.

leg	tool	slow	what it grades
checkin	checkin_check.py	no	grade the newest day's check-ins against the naming and duplicate rules
path-claims	path_claim_check.py	no	every path the archive's prose names, graded at the tree about to be committed (index inventory, disk bytes), against the ledger that states the readings already reviewed
reply-headings	reply_check.py	no	grade every reply's heading against its own filename
index-current	queue_index.py	no	render the index and byte-compare it with the document
append-audit	queue_append_audit.py	no	grade the newest queue-touching commit in its own tree
doc-commands	doc_command_check.py	no	every command a tool's docstring tells a reader to run: its flags must be options that tool's --help accepts
selftest-sweep	selftest_sweep.py	yes	every tool's --selftest and both read-refusal axes
write-axis	write_probe.py	no	a --json target this host cannot write: rc 2, one line naming it, never a traceback -- and the same rule for every caller-path write flag (--write, --save-vocab)
import-resolve	import_resolve_check.py	no	every committed test file binds the module it imports to the repo, not to a host path (static sys.path scan plus --import-probe)

A tool that appears in no leg is still graded by selftest-sweep, which runs every tracked tool's --selftest and both read-refusal axes -- so the probes column above is also the sweep's cover of that tool.