Every Tier-A bug shipped in v0.0.145..150 (#604, #655, #628, #648,
#559) had the same shape: a walker function dispatching on `Expr`
subclasses handled N of N+1 cases, the missing case silently fell
through to the default (None / False / no-op), and the enclosing
function silently produced wrong output.  This PR closes the bug
class by making "did you handle every subclass?" a mechanically
checkable contract.

What's in the PR:

1. **`# WALKER_COVERAGE:` checklist comments** on 9 walker
   functions, classifying every one of the 29 Expr subclasses
   declared in `vera/ast.py` with one of four dispositions:

   - **Handled** — explicit `isinstance` branch
   - **Intentionally ignored** — default fall-through is correct
     (e.g. literals in a sub-expression-recursing walker)
   - **Cannot occur** — structurally impossible (e.g. OldExpr in
     body-only walkers, HoleExpr post-typecheck)
   - **MISSING** — open bug, branch should exist

2. **`scripts/check_walker_coverage.py`** — parses each walker's
   `isinstance(_, ast.X)` calls AND its checklist comment text,
   then verifies the union covers every Expr subclass.  Reports
   any gap as `name (lineno): N subclass(es) not in dispatch or
   checklist`.

3. **`walker-coverage` pre-commit hook** — runs the script on
   every commit touching `vera/ast.py`, walker files, or the
   script itself.  A new Expr subclass added to `ast.py` forces
   every walker to either handle it or document its disposition.

4. **11 defensive `isinstance` branches** added to harden against
   future regressions of the bug class.  Masked today by upstream
   guards (type checker rejection, [E602] codegen-skip, closure
   pipeline sibling scans, translator-side registration in
   calls_math/calls_containers), but plugs the gap if any
   upstream mechanism is relaxed:

   - `_scan_io_ops` (compilability.py): +4 (IndexExpr, ArrayLit,
     InterpolatedString, AnonFn body recursion)
   - `_scan_expr_for_handlers` (compilability.py): +5 (same shape
     plus QualifiedCall args)
   - `_infer_expr_wasm_type` (inference.py): +2 (AnonFn → i32,
     ModuleCall → fncall-shape lookup)
   - `_infer_vera_type` (inference.py): +8 (Block, MatchExpr,
     HandleExpr, AssertExpr, AssumeExpr, AnonFn, QualifiedCall,
     ModuleCall — defensive `Fn`/`Unit`/return-type fallbacks)

5. **`vera/README.md` "Walker-completeness convention" section**
   documenting the contract for future contributors.  Also adds a
   step-5 note in "New AST node" reminding contributors that a
   new Expr subclass requires every walker checklist to be
   updated.

6. **#604 ROADMAP cleanup** — removes the stale Order-1 row that
   PR #659 had closed via code fix but didn't delete from
   ROADMAP.md.  Stabilisation tier renumbered 1-6 (was 2-7);
   Agent-integration tier renumbered 7-9 (was 8-10).

7. **#667 filed and added to ROADMAP** as new Order 6 — SMT
   translator coverage expansion (FloatLit / ArrayLit /
   IndexExpr).  Surfaced as latent gap during the walker audit;
   closing requires extending the contract grammar (parser +
   checker work) which is out of scope for this PR per Option A's
   scope decision.

Release prep
- Version bumped to v0.0.151 across __init__.py, pyproject.toml,
  uv.lock, docs/index.html, README.md.
- CHANGELOG.md entry under [0.0.151] with Added + Fixed + Internal
  sections.
- HISTORY.md row added (one-line template-compliant).
- TESTING.md + CONTRIBUTING.md hook count bumped 26 → 27.
- TESTING.md hook-table row added for `check_walker_coverage.py`.

Validation
- `python scripts/check_walker_coverage.py` → 9 walkers cover all
  29 Expr subclasses (clean)
- `pytest tests/ -q` → 3,813 passed, 14 skipped
- `mypy vera/` → clean
- `python scripts/check_doc_counts.py` → consistent (27 hooks)
- `python scripts/check_version_sync.py` → consistent across 6
  files
- Doc sweep across SKILL / CLAUDE / AGENTS / README / vera/README
  / spec / docs / examples / tests → zero stale workarounds, all
  references appropriately tense-framed

Closes #597

Co-Authored-By: Claude <noreply@anthropic.invalid>

CR-1 (`CONTRIBUTING.md:90`) — commit-stage hook count drift.

The heading "**commit-stage** hooks (24, each gated to relevant
files) include:" disagreed with the immediately-preceding
sentence "25 are configured at the commit stage".  Updated to
match (24 -> 25).  Pure doc-consistency fix.

CR-2 (`scripts/check_walker_coverage.py:167`) — auto-discover
walker files instead of hardcoded list.

The hardcoded `WALKER_FILES` list silently skipped any new
walker file added without updating the list — replicating the
exact silent-skip class this script was written to close.
Verified by inspection: nothing forced contributors adding a
new walker file to also touch this list.

Replaced with `_discover_walker_files()` which globs
`vera/**/*.py` for files containing the `WALKER_COVERAGE:`
marker.  Returns a sorted `list[Path]` (same shape as the
hardcoded list it replaces) so downstream code referencing
`WALKER_FILES` is unchanged.

Validation
- `python scripts/check_walker_coverage.py` -> 9 walkers cover
  all 29 Expr subclasses (clean — same output as pre-fix)
- Discovered file list matches the pre-fix hardcoded list
  exactly (6 files, same paths)

This also addresses the #1 critical finding from the
pr-review-toolkit audit run before this commit.

Refs #597 #668

Co-Authored-By: Claude <noreply@anthropic.invalid>

… block

CR-3 (`scripts/check_walker_coverage.py:146-159`) — restrict
`extract_checklist_classes` to the WALKER_COVERAGE block only.

Pre-fix the helper ran `CHECKLIST_LINE_RE.findall(body_src)` over
the entire walker function body, including any function code
after the docstring close.  A `# Foo → bar`-shaped comment
elsewhere in the function body could silently count as
"checklist coverage" for a class named Foo — the exact silent-
skip class this script was written to close.

Also independently flagged as item #4 in the pr-review-toolkit
audit posted earlier on this PR.

Post-fix `extract_checklist_classes` first locates the
`WALKER_COVERAGE:` marker, then slices `body_src` from there
through the closing `"""` of the enclosing docstring (since
our convention puts WALKER_COVERAGE at the trailing end of the
docstring, the next `"""` is the natural block terminator).
The regex then scans only that slice.

Edge-case behaviour:
- No marker found → caller already filters to walkers
  containing the marker, but defensive `return set()` covers
  the case anyway.
- No closing `"""` after the marker → falls back to
  end-of-body.  Single-quoted triple delimiters `'''` are not
  used by any walker today, so the fallback preserves the
  pre-fix coverage detection if convention drifts; the cost
  is accepting matches in post-block code, same as pre-fix.

Validation
- `python scripts/check_walker_coverage.py` → 9 walkers cover
  all 29 Expr subclasses (clean — same output as before)
- Spot-check: every WALKER_COVERAGE block correctly reports
  29 checklist entries (one per Expr subclass) via the
  anchored extraction

Refs #597 #668

Co-Authored-By: Claude <noreply@anthropic.invalid>

Following user direction to pull all 7 deferred pr-review
findings into this PR rather than file a follow-up.  The 4
small code fixes (items 2/3/5/8) plus 2 new test files
(items 6/7) land here.

Code fixes:

- **#2 ModuleCall path-drop** (`vera/wasm/inference.py:289-292`
  and `:~973`) — both `_infer_expr_wasm_type::ModuleCall` and
  `_infer_vera_type::ModuleCall` previously synthesised a fake
  `ast.FnCall(name=expr.name, args=expr.args)` for dispatch,
  silently dropping `expr.path: tuple[str, ...]`.  If a
  regression ever flowed a ModuleCall to either helper, the
  fake-FnCall lookup could match a same-name local fn from a
  different module — silent wrong-answer rather than safe
  failure.  Now both return `None` so the unknown-type surfaces
  cleanly.

- **#3 AnonFn placeholder** (`vera/wasm/inference.py:~967`) —
  `_infer_vera_type::AnonFn` previously returned the literal
  string `"Fn"` as a placeholder.  No callsite recognised
  `"Fn"` as a real Vera type; downstream type-arg mangling
  paths (`vera/wasm/calls.py:1525,1533`) would feed it into
  mangled names like `option_map$Int_Fn`.  Now returns `None`
  for the same reason.

- **#5 Factually wrong "closure pipeline" comments**
  (`vera/codegen/compilability.py:~236, ~393`, both WALKER_
  COVERAGE checklists + inline pre-branch comments) — the
  `AnonFn` defensive branches were described as "masked today
  by closure pipeline running its own scan", but pr-review
  surfaced that `vera/codegen/closures.py::_compile_lifted_
  closure` does NOT call `_scan_io_ops` or
  `_scan_body_for_state_handlers` on lifted bodies.  The
  AnonFn branch is the PRIMARY defence, not redundant.
  Comments now state this directly.

- **#8 Dead `is not None` guards** (`vera/wasm/inference.py:~954,
  ~961`) — `Block.expr` and `HandleExpr.body.expr` are non-
  Optional in the AST schema (`vera/ast.py:470, 481`).  The
  guards in the `_infer_vera_type` defensive branches were
  unreachable defensive code.  Removed; direct calls now.

Test additions:

- **#6 Synthetic-AST tests for defensive branches**
  (`tests/test_walker_defensive_branches_597.py`, 21 tests,
  296 lines) — direct AST invocation pinning each of the 11
  defensive branches plus the 5 pr-review fixes.  Without
  these the defensive branches have 0% coverage (`coverage
  run` confirmed) — a future refactor breaking one would
  land silently.

- **#7 Unit tests for the enforcement script**
  (`tests/test_check_walker_coverage_597.py`, 12 tests, 255
  lines) — pins the script's parsing logic: Expr subclass
  extraction, isinstance flattening (incl. tuple form),
  checklist-block anchoring (incl. CR-3 regression test:
  `# Foo → bar` outside the WALKER_COVERAGE block must not
  be counted), section-header tolerance, auto-discovery
  invariants, end-to-end exit code.

CHANGELOG/HISTORY:

- Extended the v0.0.151 entry with two new sub-sections under
  "Fixed" (pr-review follow-ups) and a new "Tests" section
  documenting the two regression-test files.

Doc counts (auto-validated by `check_doc_counts.py`):

- TESTING.md total: 3,827 → 3,860 tests (+33), 29 → 31 files
- TESTING.md table: two new rows for the test files
- ROADMAP.md: 3,827 → 3,860
- README.md: 3,827 → 3,860

Validation:

- `pytest tests/ -q` → 3,846 passed, 14 skipped (+33 net new)
- `mypy vera/` → clean
- `python scripts/check_walker_coverage.py` → 9 walkers cover
  all 29 Expr subclasses (clean)
- `python scripts/check_doc_counts.py` → consistent across all
  surfaces

Refs #597 #668

Co-Authored-By: Claude <noreply@anthropic.invalid>

…nctionDef

CR-4 (`scripts/check_walker_coverage.py:95, 104, 120, 231`) —
type-annotation narrowing inconsistency.

The runtime walker loop at line 106 accepts both
`ast.FunctionDef` and `ast.AsyncFunctionDef`:

    if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):

but four function signatures + local declarations narrow the
type to `ast.FunctionDef` only:

- `find_walker_functions` return type
- `walkers` list-declaration inside `find_walker_functions`
- `extract_isinstance_classes` parameter type
- `walkers` list-declaration inside `main`

This passes mypy today because Python's `ast` module's type
relationship between `FunctionDef` and `AsyncFunctionDef`
doesn't trigger strict variance checks here, but the
inconsistency is documentation-misleading — a reader looking
at the signatures would conclude async-def walkers aren't
supported, while at runtime they are.

Fix: widen all four annotations to
`ast.FunctionDef | ast.AsyncFunctionDef`.  Mechanical change,
no behaviour difference.

Validation
- `python scripts/check_walker_coverage.py` -> clean (9 walkers
  cover all 29 Expr subclasses)
- `pytest tests/test_check_walker_coverage_597.py
  tests/test_walker_defensive_branches_597.py -q` -> 33 passed

Refs #597 #668

Co-Authored-By: Claude <noreply@anthropic.invalid>

…s inventory count

CR-5 (`scripts/check_walker_coverage.py:129-147`) — make
isinstance collection scope-aware.

Pre-fix `extract_isinstance_classes` used `ast.walk(fn_node)`,
which recursively visits nested `FunctionDef` /
`AsyncFunctionDef` / `ClassDef` bodies.  No walker has nested
helpers today, but a future refactor introducing one (e.g. a
local helper with its own `isinstance(x, ast.SomeExpr)` check)
would have its inner isinstance counted as outer-walker
coverage — silently making the outer walker appear to cover a
class it doesn't actually handle.

Replaced with `_IsinstanceCollector(ast.NodeVisitor)` that:
- Overrides `visit_Call` to detect `isinstance(_, ast.X)` /
  `isinstance(_, (ast.X, ast.Y))` patterns
- Overrides `visit_FunctionDef`, `visit_AsyncFunctionDef`, and
  `visit_ClassDef` to return without `generic_visit`, pruning
  nested scopes
- Entry is `visit` on each body statement (skipping fn_node
  itself, which would trigger the FunctionDef pruning)

3 regression tests added in
`tests/test_check_walker_coverage_597.py`:
- `test_nested_function_isinstance_not_counted`
- `test_nested_async_function_isinstance_not_counted`
- `test_nested_class_isinstance_not_counted`

Each constructs a synthetic walker with a nested
def/async-def/class containing `isinstance(x,
ast.BinaryExpr)`, and asserts only the outer walker's
isinstance (`ast.IntLit`) is collected.

CR-6 (`TESTING.md:416`) — Validation Scripts count drift.

`Twelve scripts` -> `Thirteen scripts` to reflect
`check_walker_coverage.py` added by this PR.  The table row
for the script was already added in the earlier commit; only
the prose count needed bumping.

Doc counts auto-updated:
- TESTING.md total tests: 3,860 -> 3,863 (+3 CR-5 regression
  tests)
- TESTING.md `test_check_walker_coverage_597.py` row: 12 -> 15
  tests, 255 -> 311 lines
- ROADMAP.md / README.md: 3,860 -> 3,863

Validation
- `python scripts/check_walker_coverage.py` -> 9 walkers cover
  all 29 Expr subclasses (clean — same as pre-fix)
- `pytest tests/test_check_walker_coverage_597.py
  tests/test_walker_defensive_branches_597.py -v` -> 36 passed
- `python scripts/check_doc_counts.py` -> consistent

Refs #597 #668

Co-Authored-By: Claude <noreply@anthropic.invalid>

CR-7 (`.pre-commit-config.yaml:127`) — pre-commit hook trigger
regex narrower than script's auto-discovery glob.

The walker-coverage script auto-discovers via
`(ROOT / "vera").rglob("*.py")` (any Python file under `vera/`
containing the `WALKER_COVERAGE:` marker — fix that already
landed for CR-2).  The pre-commit hook's `files:` regex,
however, restricted triggering to a hardcoded list of subpaths
(`vera/ast.py`, `vera/wasm/.*\.py`, `vera/checker/.*\.py`,
`vera/codegen/.*\.py`, `vera/smt.py`, plus the script itself).

All 6 current walker files match the existing regex by
coincidence — verified by cross-checking each discovered path
against the regex.  But a future walker landing outside the
listed subpaths (e.g. `vera/transform.py` or `vera/parser/foo.py`)
would be auto-discovered by the script but edits to it wouldn't
trigger the hook — replicating the registry-drift silent-skip
class this PR is meant to close, just at a different layer.

Fix: widen the regex to `(vera/.*\.py$|scripts/check_walker_coverage\.py$)`
so it matches every Python file under `vera/`, plus the
enforcement script itself.  Verified:
- All 6 current walker files still match
- Hypothetical future locations (`vera/transform.py`,
  `vera/parser/foo.py`, `vera/__init__.py`) now match
- Non-walker files (`tests/test_foo.py`, `README.md`) still
  don't match

Skipping the duplicate CR-6 finding (TESTING.md "Twelve scripts"
→ "Thirteen scripts") — already fixed in `c1321c7`; current
state at TESTING.md:416 reads "Thirteen scripts" as required.

Validation
- Regex spot-check on 12 paths (6 actual walkers + 3 hypothetical
  future locations + 3 non-walker controls) — all match the
  expected behaviour
- `python scripts/check_walker_coverage.py` -> clean (9 walkers
  cover all 29 Expr subclasses)
- `python scripts/check_doc_counts.py` -> consistent

Refs #597 #668

Co-Authored-By: Claude <noreply@anthropic.invalid>

CR-8 (`TESTING.md:416-432`) — heading-vs-table mismatch.

My earlier CR-6 fix in `c1321c7` bumped the prose count from
"Twelve scripts" to "Thirteen scripts" but I incorrectly
claimed the table row was "already added in an earlier commit".
The CHANGELOG-style row I'd added (line 472, in the pre-commit
hooks list) was for a different table.  The "Validation
Scripts" inventory table at lines 418-432 was still at 12 rows.

Added the missing row for `check_walker_coverage.py` between
`check_doc_counts.py` and `check_licenses.py` (grouping it with
the other "doc / cross-tree consistency" checks), with a
description matching the style of adjacent rows.

Validation
- TESTING.md table now lists 13 scripts, matching the heading
- `python scripts/check_doc_counts.py` -> consistent

Refs #597 #668

Co-Authored-By: Claude <noreply@anthropic.invalid>