agent-glovebox: Skill for Claude Code

Writing Tests

A test earns its place by going red the moment a real defect returns — not by executing lines for a coverage number. Every rule below serves that.

Test behavior, not source text

Never grep the implementation as a proxy for what it does. assert "chmod 0444" in script passes whether or not that line ever runs, breaks on a harmless rename, and stays green against a broken implementation that still contains the token. Instead drive the real code path and assert the observable outcome: run the function or script with the real dependency where one can run (a real git in a scratch repo, a real file tree, the real parser, a real CLI against a local server), or where it genuinely cannot, under a stub that records how it was called (a fake install, docker, id on PATH) — and check what actually happened: the file written and its mode/owner, the argv+env a binary was exec'd with, the exit code, the bytes on stdout/stderr, the state left on disk.

The only legitimate exceptions parse data, not imperative logic: validating a config artifact the product ships and loads at runtime (a settings.json, an execpolicy.rules) with its real parser, or pinning a cross-file structural contract two files must agree on when no single process can observe both. A grep of imperative source to confirm it "does X" is never an exception.

A workflow under .github/workflows/ is imperative source, and this repository's own CI is where that rule broke down. A test that opens a workflow, a .github/scripts/ file or a git hook and searches its text for a step name, a flag, a marker comment or a regex is the banned shape, whatever it asserts. It is why a CI change costs a test change here: the tests pin the machinery's spelling, so a rename reds a suite that no defect reached. What the ban forbids is a search of TEXT nothing parsed. Three moves are allowed. Each reads a model some parser built. Parse the file with yaml.safe_load and assert on the DATA MODEL — a job's needs list, an if: string, a trigger's keys. Read a # required-check: or # memoize: marker through tests/_helpers.required_check_verdicts. That helper resolves the marker per job, never anywhere in the file. For a run: body, read its ARGV through .github/scripts/_shell_scan.commands. Assert on a command's words. A flag is a word, so a reflow or an added quote leaves the read alone. A rename still reds it. Best of all, drive the script the step runs and assert what it did. Two excuses license no text search: the cross-file-contract exception above, and "no single process can observe a workflow at run time". The parsed model IS that single process. "--flag" in run_body is the tell. "--flag" in command.words is not.