test(pv): contracts-pv was 0% because CI ran none of pv's tests (#2589)

[noahgift]

contracts-pv read 76 features, 0.0% covered, 0 UNKNOWN hardware. That last
column says the features are hardware-verified and simply ungated. Two causes were
measured at 4bbfeb07f; both are fixed here.

1. pv's CLI tests were DARK — this is why the number was 0%

crates/aprender-contracts-cli/tests/ already held 651 lines of tests that spawn the
pv binary, and CI ran zero of them:

• workspace-test is cargo nextest run --profile ci --workspace --lib — library
  targets only.
• The one explicit integration line in ci.yml names 23 --test targets. None is
  from aprender-contracts-cli.

$ grep -o "cargo test -p [a-z-]* [^&]*--test [a-z_0-9]*" .github/workflows/ci.yml | sort -u | wc -l
23
$ grep -c "aprender-contracts-cli" <that list>
0

A test that never executes is 0% coverage however many lines it has. This is the exact
trap the comment above that line already warns about — it had swallowed pv whole.

2. The tests that did exist EXCLUDED NOTHING

Nearly every one asserted status.success() on a good contract. That assertion is
satisfied unchanged by fn main() { std::process::exit(0) }. Per
project_assertions_exclude_guard, an assertion no wrong behaviour can violate is not a
control.

---

Tranche 1 — tests/pv_surface_gate.rs, 8 tests

Area	What is gated
pv validate decision table	All 25 diagnostic rules the validator can emit (SCHEMA-001..017, PROVABILITY-001, BEAT-001..007), both directions: tripped → reached through the CLI at its measured severity with the exit code that severity implies; clean contract → none of them.
Exhaustiveness	The rule universe is read out of validator.rs, so a new rule enters the loop rather than falling outside it.
Reachability	All 38 subcommands pv --help advertises must exit 0 for pv <cmd> --help — the apr test llm class (#2527).
Input rejection	Each of the 16 contract-taking subcommands must exit non-zero on a nonexistent path, malformed YAML, an empty file, and well-formed YAML that is not a contract (64 assertions). This is the assertion the pre-existing suite never made.
Version pinning	pv --version reports this crate's version, resolved via CARGO_BIN_EXE_pv so it cannot fall back to a stale PATH pv (#2552).

Severities and exit codes were measured against the binary, not assumed.

The exhaustiveness guard earned its keep on first run

It failed immediately, naming BEAT-001 as ungated. Widening the extractor then exposed
BEAT-002..007, which are emitted through a local closure rather than a rule: "..."
literal and were invisible to the first version — this guard's own universe had been
built from the wrong side. The extractor now takes its universe from the rule-id
shape, not from one syntactic form.

Mutation verification — 4 mutations, each proven to ENGAGE first

Every mutation asserts a non-empty git diff before any verdict is read. A sed that
silently fails to match reads exactly like "the guard is fine".

#	Mutation	Result
M1	delete the violation-print loop in commands/validate.rs	gate rc=101 (3 RED); library -p aprender-contracts rc=0, 55 passed
M2	replace validate.rs's error return with Ok(())	gate rc=101 (2 RED) on the exit-code half
M3	rename SCHEMA-013 → SCHEMA-999	exhaustiveness guard RED, naming the orphan
M4	disable the BEAT_INCUMBENTS membership arm	RED on exactly the BEAT-002 membership row
CONTROL	restored tree	rc=0, 8/8 green

M1 is the load-bearing result. The gate goes RED while the library tests stay GREEN
— mechanical proof that this covers CLI surface the library tests cannot see, i.e. it is
new coverage rather than a duplicate of validator_tests.rs.

All four were re-run after the complexity refactor of the help parser, since the old
proof does not transfer across a refactor.

CI wiring — without it, a passing gate is still 0%

pv_surface_gate, cli_integration (64 tests, green) and ground_truth (34, green) are
added to the integration line.

book_coverage is deliberately not wired: it is RED at 4bbfeb07f —

Failed to parse contracts/binding.yaml: Failed to parse YAML: missing field `metadata`

It walks contracts/*.yaml and chokes on binding.yaml, a binding registry rather than
a contract. It rotted precisely because nothing watched it. Fixing it is separate work
and belongs near #2554's schema changes.

Contract

contracts/pv-cli-surface-v1.yaml, kind: pattern, 8 falsification tests carrying the
measured mutation results. pv validate → 0 errors, 0 warnings.

Gates

Gate	Result
cargo test -p aprender-contracts-cli --test pv_surface_gate	rc=0, 8/8
--test cli_integration	rc=0, 64/64
--test ground_truth	rc=0, 34/34
cargo fmt --all -- --check	rc=0
pv validate contracts/pv-cli-surface-v1.yaml	rc=0
pv lint contracts/	0 errors, 947 warnings — byte-identical to my measured origin/main baseline, so this contract adds none
pmat pre-commit gates	fmt / complexity / docs PASS

The 942 warning figure in circulation is stale; re-measured at 947 on origin/main
before and after. (Task 2's agent independently measured 947.)

Deliberately NOT in this tranche

pv lint's warning ratchet (its numeric baseline belongs in the Makefile gate, not a
unit test, and a run over 1229 contracts is too slow for the integration step),
pv diff semver suggestions, pv score, pv certify, pv coverage, and the content
of the generator subcommands' output (kani/probar/coq/flux/tla/…). Those are
tranche 2.

Judgement on CLUS-004 (#2596): do not land it here

The ticket proposes that expressing clustering invariants as a pv contract "closes two
zeros with one ticket". It does not, for two independent reasons:

1. Category error. contracts-pv's 76 features are pv's own CLI features. Adding a
   YAML file that pv validates exercises the clustering code, not pv. It would move the
   clustering zero and leave contracts-pv at 0%.
2. Its input does not exist. docs/audits/surface_audit_clustered.csv — the 830-row
   matrix both Recluster the surface audit with aprender-core: a real sklearn-parity falsifier, and contracts-pv's first coverage #2591 and CLUS-004: express the clustering invariants as a pv contract — one ticket closes two zeros #2596 recluster — is not in the tree (docs/audits/ holds
   only the two 0.63.0 dogfood markdown files). CLUS-004 also needs sklearn as a
   differential oracle and thresholds "set from measurement"; none of that is available
   here, and forcing it would produce exactly the round-number threshold CLUS-004: express the clustering invariants as a pv contract — one ticket closes two zeros #2596 warns
   against.

CLUS-004 is good work on its own merits under epic:clustering. It is not
contracts-pv coverage, and pairing them would make bisection harder for no gain.

Note for reviewers

• ci.yml is touched (one command appended to the single integration line, plus a
  comment). Per the warning in that file's own comment, only one PR at a time may edit
  that physical line — if another PR in flight also edits it, land them in sequence.
• Clippy note: cargo clippy -p aprender-contracts-cli --all-targets -- -D warnings is
  already rc=101 on origin/main with 72 pre-existing disallowed_methods
  (unwrap) findings in contract_walk.rs, equations.rs, graph.rs, certify.rs,
  verify_pipeline.rs and tests/book_coverage.rs. This PR's new file contributes
  0 of them. CI's lint step does not currently reach this crate's non-lib targets;
  that pre-existing debt is out of scope here but worth its own ticket.

Refs #2589, #2552, #2527, #2596

[noahgift]

Superseded by #2617, which folds this PR together with the other two pv release blockers.

Why folded rather than landed separately — two collisions were measured between these
three PRs, so landing them independently was not viable:

1. Textual: pv --version cannot tell you WHICH pv you have (item 3 carved out of #2558) #2559 and pv enforces provable contracts for the whole stack and has zero coverage of itself (76 features, 0%) #2589 both append to the single integration-test line in ci.yml.
   Only one PR at a time may edit that physical line without a merge-queue conflict.
2. Semantic: pv enforces provable contracts for the whole stack and has zero coverage of itself (76 features, 0%) #2589 ships an exhaustiveness guard over pv's diagnostic rules that goes RED
   the moment pv validate accepts competitor: THIS-DOES-NOT-EXIST, demand_score: 99999, intake_status: banana — 0 errors #2555 lands, because pv validate accepts competitor: THIS-DOES-NOT-EXIST, demand_score: 99999, intake_status: banana — 0 errors #2555 adds CRUX-001 and CRUX-002. Reproduced by
   copying pv validate accepts competitor: THIS-DOES-NOT-EXIST, demand_score: 99999, intake_status: banana — 0 errors #2555's schema files onto pv enforces provable contracts for the whole stack and has zero coverage of itself (76 features, 0%) #2589's tree.

Neither PR could see the other's problem. Folding resolves both in-tree before CI runs, and
costs one workspace-test (~58 min) instead of three.

An adversarial pass on all three returned unsound, and #2617 closes what it measured —
including a fatal one: adding a contract took the corpus 1778 → 1781, so check_readme_claims.sh
(a required check) failed until three README figures were bumped. All three PRs were
auto-merge armed at the time and would have sat blocked.

Closing is reversible and the branch is untouched.