The gate had six legs and none of them read a docstring's own command line.
doc_command_check.py existed since 838750c but only as a tool: nothing on the
gate ran it, so a documented flag its parser never learned could land and
nobody read it. This is that leg.
doc-commands tools/doc_command_check.py --rev WORKTREE --fail
WORKTREE, not HEAD: the commit window is where a docstring is
edited. Measured at the worktree this lands in: 67 commands
over 19 oracle tools, 67 OK, rc 0.
doc_command_check.py learns --rev WORKTREE: tracked paths from `git ls-files`
(an untracked tools/x.py is not part of the commit this mode grades), bytes
from disk. Outside a work tree it is rc 2, not an empty clean run. Selftest
15 -> 18 cells: one document edited on disk but not committed is rc 0 at HEAD
and rc 1 at WORKTREE, and the flag it names is the edited one.
Three tools stopped defaulting to a fixed path on this host. verify.py,
selftest_sweep.py, write_probe.py, citation_resolve_check.py,
path_claim_check.py and doc_census_check.py now resolve DEFAULT_REPO from the
file's own location, so a bare run in a clone grades the clone.
Three selftests refuse unreadable input at rc 2 instead of reporting it as
failed content: tool_map (not a work tree), write_probe (no table), and
citation_resolve_check (no corpus). Each cell below them graded `repo`, so an
absent tree read as "your table is wrong".
Evidence, all measured on this tree before the commit:
verify.py --selftest 55 cells, 55 passed (docstring says 55)
doc_command_check.py --selftest 18 cells, 18 passed (baseline pinned 18)
tool_map.py --repo . --rev WORKTREE --check docs/TOOLS.md rc 0
verify.py --repo . 7 legs, 6 pass, 1 fault -- selftest-sweep,
tool_map's drift cell, which renders HEAD
and so cannot pass inside a commit window
tools/selftest_baseline.tsv re-pins doc_command_check.py 15 -> 18 cells.
DEFAULT_REPO was the absolute /root/troupe-standup, so a copy's
`--selftest` -- the invocation selftest_sweep.py uses, no --repo, cwd =
the tree under sweep -- graded the home checkout and reported the copy
clean. Derived from __file__ instead: the default is the checkout the
tool lives in. Measured on a clone at c3058d5 with drifted docs: before,
repo-less --selftest 20/20 rc 0 vs --repo . 19/20 rc 1; after, 19/20
rc 1 both ways.
Also in this commit:
- verify.run_leg: one elapsed-ms clock (_elapsed_ms) and one except arm
for TimeoutExpired/OSError, instead of three copies of the arithmetic;
- write_probe c13: roster read from FLAG_PROBES rather than a hardcoded
three, and selftest_sweep.py --write-baseline added to the table;
- docs/TOOLS.md: the selftest_sweep row grows the flags it now prints.
Measured before: 4602bd5's message says "TOOLS.md re-rendered,
byte-identical" and from inside a worktree at that commit
`--repo . --check docs/TOOLS.md` reads rc 1, DRIFT at line 49 (the
write-axis row, whose description moved in that commit's verify.py),
and `--repo . --selftest` reads 15/16. Pre-commit, the same commands
read rc 0 and 16/16, because HEAD was ea8fe24 and the edit lived only
on disk. The guard was working; it was guarding the last commit.
Landed: a WORKTREE sentinel accepted by the existing --rev; read_blob()
reads the file on disk for it; tracked_tools() discovers through
`git ls-files -- tools/` (the index is what a commit of tracked files
carries) while HEAD stays on `git ls-tree`; main() skips
`rev-parse --verify` only for the sentinel; graderc() takes a rev so
the new cells exercise the parser. Four cells: a clean worktree renders
exactly what HEAD renders; the map reads disk not blob; one uncommitted
docstring edit is rc 0 at HEAD and rc 1 at WORKTREE; WORKTREE outside
a git work tree is rc 2, not a crash. Selftest 16 -> 20, 20/20 rc 0.
Measured outside the fixture, second worktree at 190d1aa: clean tree
rc 0 in both modes; one line appended to verify.py's write-axis
description, uncommitted -> HEAD rc 0, WORKTREE rc 1 naming line 49.
Transcript: wizard-outputs/volt/2026-10-21-worktree-mode/measure.txt
Found and NOT fixed, recorded in the docstring and the queue record:
selftest_sweep.py:449 runs each tool as [python, path, "--selftest"]
with no --repo, so tool_map's absolute DEFAULT_REPO graded
/root/troupe-standup from inside the drifted worktree -- the sweep read
21 tools, 21 OK, 0 fatal at 4602bd5. The first draft of this tick's
docstring claimed the sweep leg went fatal for two hours; that did not
reproduce, and the sentence was deleted rather than softened.
Gate: verify --fast 5/5 (pre-commit); verify --repo . 6/6 at this
commit, doc_command 65/65, doc_census 0 STALE.
The write-axis leg grades ONE surface per tool: `--json PATH`. Measured at
c3ffee9 with caller_write_flags.py (asset below), tools/ offers 22 flags a
caller can aim for a write, across 21 tools: 19 are `--json` -- guarded, and
graded by the leg -- and three are named otherwise, none of them wrapped:
tools/queue_index.py :581 --write BARE
tools/tool_map.py :510 --write BARE
tools/doc_census_check.py :1831 --save-vocab BARE
BARE = `open(path, "w")` with no try. Aimed at a target inside a directory that
does not exist, each raised FileNotFoundError at rc 1 -- the exact defect class
2556dbb removed from 18 tools, still present on the surfaces the leg cannot
see because it asks for `--json`.
Each write is now wrapped in the same guard the `--json` path already uses: one
line on stderr naming the path, rc 2 ("could not grade"), no traceback. Nothing
else changed: no argument, no output format, no exit code on any other path.
VERIFIED, both directions, in a throwaway worktree (never this tree):
/root/.hermes/wizard-outputs/volt/2026-10-21-write-axis-bites/write_flag_probe.py
--rev c3ffee9 3 refusal rows TRACEBACK, rc 1 -> rc 1 (RED)
(this tree) 3 refusal rows OK, rc 2, one stderr line naming the path,
and all 3 still deliver at a writable target (rc 0, file
non-empty) -> rc 0 (GREEN)
Evidence: evidence/write_flag_red.json, evidence/write_flag_green.json.
Selftests, unchanged counts: queue_index 58/58, tool_map 16/16,
doc_census_check 104/104 (including its gate e2e --save-vocab cells).
repo gate: 6 legs, 6 pass, 0 fault, rc 0 (selftest-sweep 21 tools 0 fatal).
REMAINING BLIND SPOT, stated so it is not read as closed: write_probe.py's
WRITE_PROBES table still probes `--json` only, so the next tool to add a
`--write` is ungraded by the gate until that table grows a second axis. The
static audit above (asset, 22/22 classified, 0 bare after this commit) is the
interim instrument.
Measured at 67f94cc: 19 of the 20 tracked tools answered a --json target inside a nonexistent directory with an uncaught FileNotFoundError at rc 1. Only queue_append_audit.py already refused (rc 2). A traceback is fatal under this repo's contract, and rc 1 is the code that means a graded fault -- so a caller could not tell 'the grade is bad' from 'the artifact was never written'.
Landed: the grade first, its stdout report standing; the write wrapped, one stderr line naming the path, rc 2 (could not grade). gate_blame.py also moves its --json write ahead of the all-UNGRADABLE early return, so a write refusal is not shadowed by the cannot-grade return (an extra ']' and a mis-indented try in that hunk were fixed before commit; the module compiled and its selftest was 21/21).
tools/write_probe.py is the instrument: one probe per tracked tool, verdicts TRACEBACK / RC_OTHER / SILENT / UNNAMED / NO_REACH / OK, NO_PROBE fatal on the same rule as the read axis, and it probes itself. It is leg 6 of verify.py, and selftest_sweep.py now carries both a read probe and a malformed probe for it.
Verification at this commit follows in the next commit with docs/TOOLS.md and the queue record.
volt
volt
forge