docs: refresh cookbook appendix counts + reciprocal cross-reference

Walking 6aca7d9 (cookbook test-coverage appendix) surfaced two
findings: (1) two stale test counts since fox wrote the appendix at
2026-05-10 13:11 EDT; (2) the appendix and docs/calculator-test-
patterns.md are complementary lenses but had no explicit
cross-reference. Both fixed in this docs-only commit.

Stale counts refreshed
======================

- `tests/test_phi_alignment_probe.py` "14 tests" → "23 tests".
  Drift cause: my `a4b3056` (2026-05-10 14:08 EDT) added 9
  pattern-backfill tests after fox's appendix snapshot at 13:11
  EDT (~57 min lag).
- `tests/test_t3_bound_calculator.py` "51 tests" → "53 tests".
  Drift cause: my `581ad90` (2026-05-10 ~13:50 EDT) added 2
  KAT-fixture-gap closures after fox's appendix snapshot.

Both refreshes preserve the trajectory by noting the
``+9 from a4b3056`` / ``+2 from 581ad90`` provenance inline. Same
durability pattern fox used in `018a2a1` for the alias-count
refresh + my `6f1dbed` ditto.

Per the appendix-author's own ``unit-test density`` heuristic,
the refreshed counts confirm both files keep their ≥1× test/code
ratio. ``test_phi_alignment_probe.py`` jumps from 268/200 ≈ 1.34
to 419/200 ≈ 2.10× (closer to the contract-defining-foundation
ratio fox flagged for warrant_chain.py at 3.6×).

Missing entry added
====================

`tests/test_substrate_fork_score.py` (renamed from
`test_v8_fork_score.py` in `a4058a4` per the 2026-05-10 v-prefix
retirement) wasn't listed in fox's appendix. The file is the
``arborist substrate score`` CLI surface coverage — adapter tests
+ 4 in-process build_parser CLI tests + 1 real subprocess
invocation. Distinct from `test_fork_score.py` (fox's pure-function
unit tests for ScoredFork at 18 tests).

Added under "Substrate-paper-spec'd primitives" section alongside
test_fork_score.py.

Reciprocal cross-reference
==========================

`docs/calculator-test-patterns.md` (the per-pattern CHECKLIST for
new tests) and `docs/warrant-substrate-cookbook.md § Appendix`
(the per-discipline INDEX of existing tests) are complementary,
not duplicative:

  - Checklist answers: "what should my new tests cover?"
  - Index answers: "where are the tests for X?"

Added each-direction cross-reference paragraphs:

- Cookbook appendix § "Cross-reference" subsection naming
  calculator-test-patterns.md as the checklist for new code.
  When adding a new substrate-paper-spec'd primitive: walk the
  checklist to design the test file, then add a row to the
  appendix under the matching discipline.
- calculator-test-patterns.md § "What this doc is NOT" expanded
  with a bullet pointing readers at the cookbook appendix as
  the existing-test inventory.

Closes the gap where future shifts might find one without the
other and miss half the discipline.

Hygiene
=======
- make test → 1986 passed, 45 skipped.
- Both docs are reference-only; no test or code surface change.
This commit is contained in:
russell@unturf.com 2026-05-10 13:57:00 -04:00
parent e1ac7c2ea2
commit 6cbbf9505e
No known key found for this signature in database
2 changed files with 42 additions and 4 deletions

View file

@ -277,6 +277,13 @@ their own surface.
- A list of every pattern in the repo. Verifier tests, parser
tests, retrieval tests have their own structures appropriate
to their domains; this doc is calculator-style only.
- A coverage inventory. The per-discipline test-file index lives
at `docs/warrant-substrate-cookbook.md` § "Appendix —
test-coverage cross-reference". This doc is the **checklist
for new tests**; the cookbook appendix is the **index of
existing tests** keyed by substrate discipline. Walk both:
this doc designs the test file, the cookbook appendix records
it under the matching discipline.
The "When to use" caveat at the top is the load-bearing line:
**don't retrofit these patterns onto verifier-style tests**.

View file

@ -491,10 +491,18 @@ than waiting for bench-time STRICT-rate drift to surface it.
### Substrate-paper-spec'd primitives (#000012 + #000018 + #000034)
- `tests/test_anchor_prg.py` — 27 tests for φ_PRG HMAC-SHA-512
expansion (#000035 Phase 1).
- `tests/test_phi_alignment_probe.py` — 14 tests for φ_linear
Hessian-alignment probe (#000034 Phase 1a).
- `tests/test_t3_bound_calculator.py` — 51 tests for the
expansion (#000035 Phase 1). Covers KAT regression, hand-formula
(first-block matches direct ``hmac.new``), prefix-extending
closure invariant, output-length monotonicity per dim_h.
- `tests/test_phi_alignment_probe.py`**23 tests** (was 14;
+9 from `a4b3056` 2026-05-10 pattern backfill) for φ_linear
Hessian-alignment probe (#000034 Phase 1a). Covers KAT
regression, hand-formula (uniform baseline), monotonicity in
W concentration + dim_h, closure (a_top + a_bot ≡
full-spectrum on dense decomposition), Lanczos eigenvalue
ordering invariant.
- `tests/test_t3_bound_calculator.py`**53 tests** (was 51;
+2 from `581ad90` 2026-05-10 KAT-fixture-gap closure) for the
T3 per-window covert-channel bound calculator (#000036 §11);
pins the closed-form B1/B2/B3 formulas, monotonicity in each
input, recommendation-text mode transitions, and the §11
@ -504,6 +512,13 @@ than waiting for bench-time STRICT-rate drift to surface it.
(#000012 Phase 1a); pins SIGNAL_FLOOR (5pp) + HARD_REGRESSION_FLOOR
(5pp), score = sum-of-breakdown closure, security_risk inert
under default iota=0 (opt-in), NEG_INF_REGRESSION hard-reject.
- `tests/test_substrate_fork_score.py` — 27 tests covering the
``arborist substrate score`` CLI surface (renamed from
``test_v8_fork_score.py`` in `a4058a4` per the 2026-05-10
v-prefix retirement). Adapter tests + 4 in-process CLI tests
via ``build_parser()`` + 1 real subprocess invocation
catching entry-point / sys.argv drift the in-process tests
miss.
- `tests/test_weights.py` — 16 tests for WeightSet defaults
(each weight value pinned to its docstring rationale; PR that
flips alpha=1.0→0.5 fires this test), greek-letter and
@ -556,3 +571,19 @@ contract-with-tests-per-rule.
The ratio is a code-review heuristic: a new substrate-paper-spec'd
primitive without ≥1× test/code ratio is suspect on landing.
### Cross-reference
This appendix is the **per-discipline INDEX** — start here when
auditing "where are the tests for X?". The complementary
**per-pattern CHECKLIST** for new calculator-style code lives at
`docs/calculator-test-patterns.md`: KAT regression, hand-formula,
monotonicity, closure, parametrized invalid-input, CLI subprocess,
doc parity, module-export shape — with a 9-item checklist for new
modules and an explicit "doesn't apply to verifier-style code"
caveat. Codified 2026-05-10 from the three-module pattern bench
(t3_bound_calculator + phi_alignment_probe + anchor_prg).
When adding a new substrate-paper-spec'd primitive: walk the
checklist in `calculator-test-patterns.md` to design the test
file, then add a row here under the matching discipline.