Rendered from docs/interfaces/headwater-probe.md in the Headwater corpus. Every document on this half of the site is typed by the taxonomy the descriptor names: corpus.json.

headwater probe

Synopsis

headwater probe plan [--tier regression|campaign|documentation] [--arm present|absent|no-hook|no-skills|no-claude-md|mcp]
                      [--category name] [--exclude probe]... [--repetitions n] [--seed n]
headwater probe plan [--tier regression|campaign|documentation] --arm <arm> --delta
headwater probe plan --instrument
headwater probe plan --folds
headwater probe plan --answer-keys <probe>
headwater probe record <path>
headwater probe grade <path>
headwater probe stale

plan takes no path. record and grade take one transcript path. stale takes no operand. Each subcommand refuses an unknown word.

Description

headwater probe is the four-part measurement harness. plan composes a selection from the declared probes, tier, arms, category and budget. record reads a transcript and confirms its structure without evaluating an expectation. grade evaluates the declared expectations. stale compares committed transcript read sets with the current corpus.

Probe output never changes an exit status. A probe is a measurement, not a build gate. No subcommand opens a network connection or writes a file.

The harness reads the selection again when it grades a transcript. This prevents a result from grading against probes that the current corpus no longer declares.

Preconditions

All subcommands require a readable .headwater/probe.yml, a readable taxonomy lock and a loadable corpus. record and grade also require a readable transcript path. stale requires committed probe transcripts to report, but it succeeds when none exist.

Options

Subcommand	Options	What it does
plan	--tier <regression\|campaign\|documentation>	Select the tier. The default is regression. A paired tier refuses a probe whose predicate names a document that its own ablation removes. Every tier refuses one whose document sits under the instrument, which every arm removes.
plan	--arm <present\|absent\|no-hook\|no-skills\|no-claude-md\|mcp>	Narrow the declared arms to one arm. An arm the tier does not declare refuses the run and names the arms it does declare. A paired tier refuses a narrowing to one arm that it declares.
plan	--delta	Plan nothing, and print the delta of the --arm arm against the present tree, as the tier declares it. Each line is - <path> for a path that the arm removes, or + <path> for a path that it adds. The option reads .headwater/probe.yml and does not load the corpus. It needs --arm. A script that builds the tree of an arm reads this output, so that the script does not parse the declaration again.
plan	--instrument	Plan nothing, and print each path of the instrument sequence of .headwater/probe.yml on its own line. Every arm of every tier removes these paths. The option reads .headwater/probe.yml and does not load the corpus. It cannot be used with --delta. A script that removes the instrument from a tree reads this output, so that the script does not parse the declaration. A declaration with no instrument prints nothing.
plan	--folds	Plan nothing, and print each path of the folds sequence of .headwater/probe.yml on its own line. A fold is a file outside docs/ that names a probe and does not state its answer. The seal keeps these files. The option reads .headwater/probe.yml and does not load the corpus. It cannot be used with --delta, --instrument or --answer-keys. A script that seals a workspace reads this output, so that the script does not parse the declaration. A declaration with no folds prints nothing.
plan	--answer-keys <probe>	Plan nothing, and print each path that the answer_keys mapping of .headwater/probe.yml declares for the probe, on its own line. An answer key is a document that an earlier session wrote in answer to the task of the probe. The seal removes these documents. The option reads .headwater/probe.yml and does not load the corpus. It cannot be used with --delta, --instrument or --folds. A script that seals a workspace reads this output. A probe with no answer key prints nothing.
plan	--category <name>	Narrow the selection to one declared category.
plan	--exclude <probe>	Remove one probe from the selection, by its identifier. Repeat the option for more than one probe. The selection digest excludes the probe. An identifier that is not in the selection refuses the run.
plan	--repetitions <n>	Plan fewer repetitions than the tier declares, for a pilot. A number above the declared count refuses the run, and so does 0.
plan	--seed <n>	Record the caller's rotation seed. It does not select a subset. The default is 0.
record	<path>	Read and report the transcript at the path.
grade	<path>	Grade the transcript at the path against the current regression selection. When the transcript names part of the selection, the grade uses that part.
stale	none	Report which committed transcript read sets changed.
every	--no-color	Force plain text on both streams: bold and dim weight plus glyphs, no escape sequence. The default already senses whether each stream is a terminal, and renders color only there. All four subcommands, plan, record, grade and stale, color their own report under a terminal. A refusal on standard error colors under a terminal for all four.

Global --root selects the repository. --help, --version, --wide and --no-banner are handled by the binary before or around the subcommand.

Exit status

0 when a subcommand completes, including when a probe refuses a run or a transcript contains findings. An arm, tier or category that a declaration or the corpus does not carry refuses the run at this status. Probe results never gate.

1 when the command line is invalid, or a required file cannot be read. A tier, arm or category name outside this engine's closed set makes the command line invalid. It is also 1 when the budget declaration is malformed or the corpus cannot load. Under --delta, an arm that the tier does not run is also 1, because a script builds a tree from the output. Under --instrument, --folds or --answer-keys, a malformed or unsafe declaration is 1, and nothing is printed on standard output. The message names the refusal.

1, and never 101, when standard output or standard error cannot be written, and one sentence on standard error names a failed standard output.

Environment

No environment variable reaches a probe subcommand. The tier, repository and seed come from the command line, and the budget comes from .headwater/probe.yml. No model, key or endpoint is read.

Files

Path	How this verb treats it
.headwater/probe.yml	read by plan, grade and stale to load the tier budgets
.headwater/taxonomy.lock	read by every subcommand through the corpus loader
.headwater/taxonomy.yml	read by every subcommand through the corpus loader
the corpus	read to select probes and to rebuild transcript read sets
.headwater/imports/	read by every subcommand where .headwater/taxonomy.yml declares an import, for the anchors that an imported snapshot supplies. An imports entry that does not read stops the verb with exit 1, and so does an at path outside the repository root.
the path each harvests.<name>.at names	read by every subcommand where .headwater/taxonomy.yml declares a pinned corpus export, for the anchors that export supplies. A harvests entry that does not read stops the verb with exit 1, and so does an at path outside the repository root. A pin with no digest binds no anchor. An absent file binds no anchor, and neither does a file that fails the pinned digest or is not an export.
the transcript path	read by record and grade
committed probe transcripts	read by stale

No subcommand writes a file. Output goes to standard output.

See also

Spec 5 defines the three tiers, probe categories and transcript contract.

Spec 15 defines the recorder and the six members of a probe run identity.

headwater sweep reports coherence findings and never evaluates a probe expectation.

The command surface lists the verbs and contracts that headwater generate derives.