fix(pv): an empty corpus is refused with exit 2, never reported as PASS (PVL-1, PMAT-1099)

[noahgift]

PVL-1 (PMAT-1099): pv refuses to report over ZERO contracts

Spec: paiml/infra docs/specifications/PVL-001-pv-lean-gate.md §2 row EV-1. Ground truth: PV-LEAN-AUDIT-001 (2026-09-10 10:47Z).

Facts re-verified at HEAD 43b8d8e (genchi genbutsu)

cited fact	HEAD	note
pv lint /nonexistent-path → rc 0, Result: PASS over 0 contracts	VERIFIED	in-tree pv 0.66.0 built by scripts/pv_bin.sh [V]
pv lint <empty dir> → rc 0	VERIFIED	[V]
pv proof-status <empty dir> → rc 0, Proof Status (0 contracts)	VERIFIED	[V]
pv verify-pipeline <empty dir> → "No contracts found", rc 0	VERIFIED (not in the spec row; plan-grill finding, verify_pipeline.rs:26-29)	[V]
`pv lint	coverage	graph ` → walked nothing, rc 0
contract_walk::collect_contracts used by graph, proof-status, lean-status, verify-pipeline; lint and coverage walk on their own	VERIFIED (pmat query --literal "contract_walk::")	[V]

Change

• contract_walk.rs: ZeroContracts { path, filter } (Display 0 contracts under <path>), ZERO_CONTRACTS_EXIT = 2, collect_corpus() (dir walked · single file = one-contract corpus · missing path = empty), require_contracts(), exit_code_for().
• lib.rs: a ZeroContracts dispatch error exits 2 (nothing was measured — clap's usage-error code); every other error keeps exit 1 (measured, failed).
• lint.rs: refuse_empty_corpus() reads the gate named validate (count = parsed + parse errors) before any report is printed. A shape-only match was measured refusing every VALID corpus, because duplicate-stems reuses the Validate detail with zeros. lint/gates.rs: a single file is linted as a one-contract corpus (no cache beneath a file).
• coverage.rs, graph.rs, proof_status.rs (--kind filtering to zero is refused and named), lean_status.rs, verify_pipeline.rs (returns the error instead of process::exit, which had killed the crate's unit-test binary).
• contracts/work/PMAT-1099.yaml (kind: pattern): 3 equations, 3 obligations, 5 falsifiers — every if_fails carries the mutation actually run.

RED → GREEN (measured)

• RED at HEAD, implementation stashed: cargo test -p aprender-contracts-cli --test pvl_zero_contracts → FAILED. 1 passed; 14 failed (a9db650) [V]
• GREEN (1ca5d39): same command → ok. 15 passed; 0 failed; cargo test -p aprender-contracts-cli (every target) → 204 passed / 0 failed; cargo test -p aprender-contracts --lib → 1501 passed [V]
• target/debug/pv lint contracts/ → Result: PASS, validate contracts: 1766, errors: 0, rc 0 [V]
• scripts/check_contract_test_binding.sh → PASS, 539 refs resolved, ratchet unchanged [V]
• make gate (post-commit; touched crates aprender-contracts + aprender-contracts-cli → selection 4 > cap 3 → full cargo check --workspace --tests) → rc 0, 41 checks / 0 failed, 436 s [V]. NOTE: run before the commits it reported no files touched vs origin/main — nothing to select — it reads commits, so a pre-commit gate run measures nothing there.
• done_when ("$PV" lint /nonexistent-pvl-path; test $? -ne 0) in this worktree → rc 2 [V]. It reads ~/src/aprender's checkout, so it turns green on merge, not before.

Mutations (each applied on 1ca5d39, measured, reverted; git status clean after each) [V]

#	mutation	prediction	measured
001	require_contracts removed from collect_corpus	proof-status/graph/lean-status/verify-pipeline RED, lint+coverage GREEN	7 passed; 8 failed — exactly those 8
002	lint guard call removed	only lint_* RED	0 passed; 2 failed (filter lint_)
003	exit_code_for → always 1	every *_is_refused RED, controls GREEN	0 passed; 13 failed (filter is_refused)
004	require_contracts → always Err	both controls RED	0 passed; 2 failed (filter control_)
005	post---kind guard removed	the kind-filter case RED	0 passed; 1 failed
Restore → 15 passed every time.

Jidoka

make gate RED once: pmat complexity, lint::run cognitive 30 > 25 with the guard inline (HEAD was already at 25). Extracted refuse_empty_corpus() and moved the single-file cache rule into build_config() → run back to 25. Logged in .pmat/jidoka.jsonl.

Review lanes

• Plan grill (agy /teamwork-preview, conversation 8006e793-4cdc-4a41-bcc5-d571e5eccd58): PASS-with-changes — keep exit 2; add single-file handling (else pv_surface_gate goes red for the wrong reason); include lean-status + verify-pipeline; no fixture or caller depends on an empty dir passing; the != 2 control was vacuous → controls now require exit 0 AND a printed count of 1. All adopted.
• Pre-merge 3-lane quorum on this diff: receipt to follow in docs/audits/PVL-1-receipt.md.

Routing

phase	class	route.sh	executed as
1 plan grill	plan	route=agy-plan w=1.00 basis=absent effort=1[U]	paiml-agy-delegate (teamwork, width 1)
2–3 impl	impl	route=agy-goal w=1.00 basis=absent note=fable-binding effort=1[U]	direct — PVL-001 §4.9: subagents read-only, orchestrator is the sole writer
4 review	review	route=agy-quorum w=1.00 basis=absent effort=1[U]	paiml-agy-delegate (quorum, width 3)
4 push/PR/receipt	orchestration	route=self w=100.00 basis=absent	self

Not changed / findings not asked for

• apr pv embeds dispatch(); its own exit mapping is untouched (exit code there [U]).
• duplicate-stems reusing the Validate detail shape with zeros is what made a shape-only guard wrong — a dedicated variant would remove the trap [A].
• pmat work start re-serialised docs/roadmaps/roadmap.yaml (816+/1469−); the diff was trimmed to the one added entry (G-6) [V].
• The 0.66.0-chain PR ci(release): CUDA apr assets built inside rust:1.93.0-bullseye on gx10/yoga — glibc 2.31 floor; the native v0.66.0 x86_64 asset needs GLIBC_2.43 and does not start on 22.04 #3086 finished CI while this waited: gate and workspace-test pass; the non-required present check fails as it did before [V].

Refs PMAT-1099

Pre-merge review quorum (3 agy lanes) → 3/3 FAIL → fixed in cf2967d

lane	conversation	verdict	load-bearing finding
1	ae646ee3-00b3-4364-aaee-76c2f0b68908	FAIL	--watch bypasses the guard (run_watch loops run_lint+print_report, lint.rs:344); measured a report over 0 contracts
2	a8b61a5b-2eb6-4215-8bd9-d717dbdead97	FAIL	same bypass, measured; contracts: 0, errors: 0 confirmed as the right emptiness signal
3	7ba5404a-cd2b-43a1-8bcd-803612cb8fa5	FAIL	--watch (lint.rs:46) AND --diff HEAD <empty> → exit 0 "Nothing to lint" (lint.rs:72)

Verified at HEAD by the orchestrator [V]: lint::run returns into run_watch at :46-65 and into run_diff_check at :72-76, both before refuse_empty_corpus at :101. Fixed in cf2967d — guard after every watch tick; --diff says "nothing changed" only over a non-empty corpus.

RED→GREEN [V] (guard stashed with git stash push -- src/commands/lint.rs, tests present):

cargo test -p aprender-contracts-cli --test pvl_zero_contracts -- lint_watch_empty_dir_is_refused lint_diff_empty_dir_is_refused
→ test result: FAILED. 0 passed; 2 failed   (watch: code -1, killed at 20 s after repeated "Result: PASS" over 0 contracts; diff: exit 0)
git stash pop
cargo test -p aprender-contracts-cli --test pvl_zero_contracts
→ test result: ok. 17 passed; 0 failed

Lane dissent NOT acted on (spec-mandated, escalated in the receipt): all three lanes say exit 2 is ambiguous with clap's usage error. PVL-001 row EV-1 says "0 contracts → exit 2". Kept at 2. Lane models: not recorded by agy [U]. This fix commit has NOT been re-reviewed by a quorum (session budget at andon) — the PR stays unmerged until the next PVL run re-quorums it.

Second review quorum (3 agy lanes on 8bb0c29) → 3/3 FAIL → fixed in 3f573c3

lane	conversation	verdict	load-bearing finding
1	39742bf6-db16-4911-a826-435d2f325b10	FAIL	walker drops unparsable files: unparsable-only dir → 0 contracts (exit 2) in --diff, exit 1 in lint; contract lacks watch/diff falsifier; receipt count 1767 vs 1766
2	7a9f134e-3afd-45de-8939-a994ca055898	FAIL	same divergence measured for proof-status; --diff nothing-changed path parsed the whole corpus; FALSIFY-002 harness stale (4 tests, not 2)
3	d12f6807-7a19-4b20-b8bb-1fd8daa56b72	FAIL	same; lint reports (exit 1) over an unparsable-only dir — that is "measured and failed", kept; receipt line numbers were cited at f99b9b6 (stated in the row)

Verified at HEAD by the orchestrator [V]: collect_contracts skipped Err from parse_contract (contract_walk.rs, pre-fix :128) and every *playbook* stem (:125) — contracts/apr-page-examples-qwen-qa-playbook-v1.yaml and …-state-machine-playbooks-v1.yaml are real contracts lint parses. Fixed in 3f573c3: ONE file rule (provable_contracts::lint::collect_yaml_files, now public) for the walker, coverage and the diff probe; a broken file is ParseErrors (exit 1, named); lint --diff probes without parsing.

Measured [V] (target/debug/pv … contracts/): lint contracts: 1767, errors: 0; proof-status Proof Status (1767 contracts) rc 0; coverage Contracts: 1767; lint --diff HEAD contracts/ rc 0 in 31 ms.

Mutations [V] (contracts/work/PMAT-1099.yaml v1.1.0, exact commands in each if_fails): 006 → FAILED. 2 passed; 2 failed (watch, diff) → ok. 4 passed; 007 → FAILED. 0 passed; 2 failed (unparsable_only, mixed_dir) → ok. 2 passed; 002 re-measured → 2 passed; 2 failed → ok. 4 passed.

Not acted on: the exit-2/clap ambiguity (spec-mandated, escalated in the receipt). A third 3-lane quorum runs on 3f573c3 before any merge.

Third review quorum (3 agy lanes on 3f573c3) → 3/3 PASS

lane	conversation	verdict	what it measured
1	f9537cc7-f322-4701-8572-0308022c69f2	PASS	lint / proof-status / coverage all 1767 over contracts/; broken-only and mixed scratch dirs exit 1 naming the file for every command; --diff over an empty dir exits 2; no caller depends on the old skip
2	a1db2c27-c233-4088-90a8-6465087ece2e	PASS	same; has_contract_files is the lint engine's rule; 20 s watch deadline sound
3	4adf9381-1862-43a6-bf91-e38f686455e4	PASS	same; tests fail without the fixes (checked at a9db650)

lane-reduce.sh --width 3 --not-before <launch> → agreed: true; artifact docs/audits/quorum-PMAT-1099.json, session receipt docs/audits/PVL-1-receipt.md (commit a81d1e5, docs only). Non-blocking note from all three lanes: the collect_from_real_contracts_dir unit test cannot see a walker that drops broken files (the corpus has none) — the integration falsifiers (FALSIFY-PVL-1-007) do.

guard-cargo on a81d1e5 → wired in 7bb3ee0 → STOP(workflow-merge)

BSE-17's self-test (rows 8/9) refused the PR: scripts/tree_reader_unwired_baseline.txt drifted … > aprender-contracts-cli --test pvl_zero_contracts — the falsifier copies contracts/softmax-kernel-v1.yaml, so it is a tree-reader, and the full tier runs --workspace --lib only: no workflow would ever have executed it. Ledgering it as "reads the tree and nothing runs it" would ship PVL-1's gate as a test CI never runs, so it is wired into the same cargo test -p X --test Y chain as pv_surface_gate (ci.yml, one line) and the derived registry is regenerated with scripts/check_tree_reader_tests.sh --update. Local: check_tree_reader_tests.sh rc 0, ci_test_tier.sh --self-test 15/15 [V].

This PR now touches .github/workflows/ci.yml. Per PVL-001 §4.5 it ends in STOP(workflow-merge: aprender PR 3093): operator merge from the web UI once gate and workspace-test are green. The code under review is unchanged since the third quorum's 3/3 PASS (3f573c3); the wiring commit is orchestrator-owned and is verified by CI itself.

🤖 Generated with Claude Code

[github-actions]

§13.11 rung 1 — quorum shadow verdict

S13-SHADOW pr=3093 head=0828696272e5d72e53c2f1af38acd6d44c89850b verdict=REFUSE class=Q1 arm_rc=1

Shadow mode: this records a verdict and merges nothing. A refusal
to arm is not a block (§13 adds zero rows to §7) — the pull request is
exactly as green as it was.

[noahgift]

quorum-review (AD-04): three PASS — agreed

{
 "ticket": "PMAT-1099",
 "head": "5f6acd76b376606a8365a770903f462484ce15cb",
 "width": 3,
 "executor": "agy",
 "agreed": true,
 "lanes": [
  {
   "lane": 1,
   "verdict": "PASS",
   "findings": 5
  },
  {
   "lane": 2,
   "verdict": "PASS",
   "findings": 3
  },
  {
   "lane": 3,
   "verdict": "PASS",
   "findings": 5
  }
 ]
}