feat(dogfood): sweep every shipped interface with the deterministic toolchain, and ban hand-rolled argv parsing

[noahgift]

What was missing

Neither existing skill covered the shipped surface. Measured before writing this:

	apr-dogfood (828 lines)	pre-release
mcp / MCP	0	0
/v1/, curl, endpoint, route	0	0
distinct apr subcommands referenced	26 of 103	—

The 0.63.0 audit that probed 104 CLI commands, 9 MCP tools and 45 routes was done by hand. It was never reproducible.

pass=209  fail=0  skip=1  (skip 0%)   rc=0
--twice: DETERMINISTIC, byte-identical receipts

It uses the deterministic toolchain — it does not reimplement it

pv       contract validation   (never yq, never a python YAML walk)
bashrs   shell quality         (never shellcheck)
probar   endpoint testing      (never a hand-rolled curl loop)
pmat     code search/quality   (never grep for discovery)

Each is asserted present with its version, not skipped-if-missing — a sweep that silently drops its verification tools reports a clean pass having checked less.

The first draft violated this. It parsed contracts/apr-mcp-tool-schemas-v1.yaml with python and counted tools: entries by hand — muda by CLAUDE.md's explicit rule, and redundant, because FALSIFY-MCP-008 already asserts byte-identity between the codegen constants and the live tools/list response at four layers. Reimplementing a weaker version of an existing falsifier is the opposite of dogfooding. It's pv validate now, plus pv lint contracts/. The live endpoint probe runs probar llm test. The script bashrs-lints its own source.

Enumerated at runtime, never from a list

surface	source of truth	count
binaries	cargo build --message-format=json	26
apr subcommands	apr --help	105
HTTP routes	the ("GET","/path",handler) table	34
MCP tools	const NAME in aprender-mcp/src/tools/	9

A written-down list is the defect this repo keeps finding — the falsification spec asserts "exactly 36 top-level commands" and finds 0 because the enum moved file; CLAUDE.md has claimed 77, 103, and 111. Grepping source is no better: a regex over clap Subcommand enums reports 0 subcommands for simular, which is a clap-derive CLI. Every enumeration is vacuity-guarded.

A pass must exclude an outcome. --help exiting 0 isn't a pass — a binary printing nothing also exits 0. Each binary must also reject an unknown flag.

Hand-rolled parsers: fixed and banned

check_no_hand_rolled_parsers.sh bans the construct, structurally and ratcheted — complementary to the behavioural probe. Self-test 3/3 including two false-positive controls (a clap CLI that also calls env::args() must not be flagged).

Four were hand-rolled; three converted here (aprender-ptx-debug is #2520). Baseline 4 → 1.

aprender-zram-generator was the sharp one: --help printed 0 bytes and an unknown flag was accepted at exit 0 — so a typo'd flag was treated as one of its directory arguments. It's a systemd generator; the three positional dirs are preserved exactly and --help now explains the protocol.

What the first run found

aprender-train-lora and trueno-zram panicked on any argument. Each declared a short option twice — -m for both model and method, -p for both pages and pattern. clap's check is #[cfg(debug_assertions)], so release builds don't panic — they ship the ambiguity. Verified on a release build, plan --help listed both -m, --model and -m, --method.

Two bugs in this script, found while writing it

1. It parsed apr --help with loose indentation, scraping wrapped description lines — apr yet), apr clip.wav counted as subcommands; 114 vs a real 105.
2. It built binary paths from cargo metadata's target_directory. In a worktree that reports /mnt/nvme-raid0/... while cargo writes to <worktree>/target/debug — .cargo/config.toml holds the redirect and is gitignored. It was probing binaries from a different tree — the repo's own binary-pinning doctrine, violated by my first draft. It asks cargo now.

Route enumeration was wrong once too: globbing every "/..." literal gave 284; reading the table gives 34.

Verification

dogfood --self-test	3/3 (incl. permissive-CLI caught)
ban --self-test	3/3 (incl. 2 false-positive controls)
--twice	byte-identical receipts
full sweep	209 pass, 0 fail, rc=0
pv lint contracts/	0 errors
cargo test (3 converted crates)	226 passed, 0 failed
clippy --all-targets	0 errors
cargo fmt --check	rc=0

_{Sequencing note: check_shell_lint_ratchet.sh (#2511, not yet on main) baselines the repo-wide bashrs count; these two scripts add 13, all documented false-positive classes on embedded python/awk — bash -n is clean on both. Needs a re-baseline when both land.}

Refs #2503

[noahgift]

Superseded by #2527, which consolidates this with the other guard PRs. All four inserted into the same guard-runner-labels block in ci.yml, so merging them separately meant one conflict per merge — and each rebase is another push competing with the merge queue. Resolved once in #2527; the commits are carried over unchanged.