…ent skips

Adds `scripts/check_e602_clean.py` — a pre-commit + CI gate that
fails when any compile of an example or conformance program emits
`[E602]` (body unsupported) or `[E604]` (param unsupported) outside
an explicit allowlist.

## Why

The `[E602]` warning channel was the project's only signal for
silent translator-skip failures (the cross-cutting pattern tracked
by #626).  Several long-standing instances of it were buried in
every WASM compile — five prelude combinators (`option_unwrap_or` /
`result_unwrap_or` / `option_map` / `option_and_then` /
`result_map`), plus six in `examples/*.vera` and
`tests/conformance/*.vera` — making it impossible to spot a new
genuine silent skip without manually sifting through expected noise.

The gate makes a new silent skip a hard build failure unless
explicitly allowlisted with a tracking-issue reference.  Removing
the noise unblocks the "convert silent failures to loud failures"
goal in the issue body.

## What the first run surfaced

8 silent skips in existing example + conformance programs that
were previously hidden by the noise.  Filed as #655:

- **Shape A** (7 functions: `option_unwrap_or`, `result_unwrap_or`,
  `identity`, `const`, `is_some`, `are_equal`, `cmp_sign`) —
  spurious warnings on generic decls; mono clones work end-to-end.
  Same root cause as #604's `_unwrap_or` half.
- **Shape B** (1 function: `head` in `examples/refinement_types.vera`)
  — genuine codegen gap.  Calling `head([1,2,3])` actually fails
  with `unknown func: $head` because the IndexExpr translator
  returns None for `@NonEmptyArray.0[0]` (refinement-of-Array
  alias).

All 11 (5 prelude + 6 newly-surfaced; counting `option_unwrap_or` /
`result_unwrap_or` once even though they appear in both groups
above conceptually) are allowlisted with their tracking issue
(#604 for the prelude, #655 for the rest).  The allowlist is
meant to shrink over time as the underlying bugs are fixed.

## Refined diagnosis of #604

During the investigation that triggered Layer 1, the original
"5 functions silently skipped" framing in #604 was refined.  Only
3 of 5 actually fail at runtime (`option_map` / `option_and_then` /
`result_map` — mono produces wrong type-arg suffix → call_indirect
signature mismatch).  The other 2 (`option_unwrap_or` /
`result_unwrap_or`) work end-to-end via mono; the warning is
spurious.  See the investigation comment on #604.

## Files changed

- **`scripts/check_e602_clean.py`** (new) — the gate.  Compiles
  each `.vera` file with `compile --wat --json` and parses the
  envelope for `[E602]` / `[E604]` warnings, filtering against
  `ALLOWED_SKIPS`.
- **`.pre-commit-config.yaml`** — wired `e602-clean` hook to fire
  on changes to `examples/*.vera`, `tests/conformance/*.vera`,
  `vera/*.py`, `vera/grammar.lark`, `vera/prelude.py`, or the
  check script itself.
- **`.github/workflows/ci.yml`** — added the check to the lint job,
  between `check_html_examples.py` and `check_site_assets.py`.
- **`KNOWN_ISSUES.md`** — refined the #604 entry to reflect the
  new diagnosis; added a row for #655.
- **`CONTRIBUTING.md`**, **`TESTING.md`** — hook count 25 → 26
  reflecting the new commit-stage hook.
- **`CHANGELOG.md`** — `[Unreleased]` entries under `### Added`.

## Validation

- `python scripts/check_e602_clean.py` — `Scanned 120 files, Clean: 120, Allowlisted skips suppressed: 11 known functions`
- `python scripts/check_doc_counts.py` — `Documentation counts are consistent (..., 26 hooks, ...)`
- `python scripts/check_limitations_sync.py` — `Limitation tracking is consistent (35 in KNOWN_ISSUES.md, ...)`

Files #655 (Layer-1 finding details).

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

Four valid findings, all fixed:

1. **`CONTRIBUTING.md` line 90** — contradictory hook count.
   Line 88 said "24 are configured at the commit stage" but
   line 90's parenthetical said "(23, each gated to relevant
   files)".  Updated 23 → 24 for consistency.

2. **`TESTING.md` Pre-commit Hooks "Full list"** — was missing
   the new `check_e602_clean.py` row.  Added row between
   `check_html_examples.py` and `check_doc_counts.py` with the
   description and #626 link.  Also updated the CI Pipeline
   table's lint job description to include `check_e602_clean.py`
   in the script enumeration.

3. **`scripts/check_e602_clean.py` module docstring** — referenced
   only `#604` even though the allowlist now also covers `#655`
   entries.  Expanded the docstring to enumerate both groups (5
   prelude tracked by `#604`, 6 user-code cases tracked by
   `#655`) with per-group rationale so the file's scope is
   clear without diving into ``ALLOWED_SKIPS``.

4. **`scripts/check_e602_clean.py` subprocess timeout** — the
   `subprocess.run` call had no timeout, so a pathological
   compile (infinite loop, Z3 stall) could block the gate
   indefinitely.  Added `timeout=60` and a `TimeoutExpired`
   handler that surfaces the timeout as a `("TIMEOUT", file,
   reason)` failure tuple, treated as a hard failure in
   `_scan_paths` like `PARSE_ERROR`.  60s budget matches the
   longest existing per-file timeout in any check script
   (`check_html_examples.py`'s `vera verify` invocation).

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

…k` conformance programs

CodeRabbit found a real gap: the gate parsed the compile JSON
envelope but never checked `envelope["ok"]`, so a well-formed
JSON envelope indicating a hard compile failure (parse error,
type error, unresolved symbol) was treated as clean as long as
no `[E602]` / `[E604]` warnings fired.  A `vera compile` that
fails entirely could slip through the gate.

Fixed by checking `envelope.get("ok", True)` after parse;
when False, surface a `("COMPILE_ERROR", file, msg)` failure
tuple using the first diagnostic's `[error_code]` +
description.  Falls back to `result.stderr` (truncated to 200
chars) if the envelope has no diagnostics.

`_scan_paths` now treats `COMPILE_ERROR` identically to
`PARSE_ERROR` and `TIMEOUT` — all three are hard failures
distinct from per-function `[E602]` / `[E604]` skips.

## Surfaced finding from the new check

Running the strengthened gate found one previously-hidden case:
`tests/conformance/ch03_typed_holes.vera` triggers `[E614]
Program contains a typed hole; fill all holes before compiling`
— **by design**.  The conformance program exists specifically to
demonstrate that the compiler rejects programs with unfilled
typed holes at compile time.  This is the canonical
`level: "check"` shape — a conformance program required to pass
`vera check` but NOT to compile.

## How the script now handles `level: check`

Reads `tests/conformance/manifest.json` and filters conformance
programs to those declared `level: "verify"` or `level: "run"` —
the levels where successful compilation is a requirement.  The
4 `level: "check"` programs (typed_holes plus three others) are
skipped entirely.

Net effect: the gate now scans 116 files (34 examples + 82
verify/run-level conformance, down from 86 total conformance).
A `level: "check"` program that fails compilation is by design;
a `level: "verify"` or `level: "run"` program that emits an
unexpected `[E602]` / `[E604]` (or fails compilation outright)
is a hard fail.

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

…isted file (#626 Layer 1)

CodeRabbit found that the manifest-driven conformance filter silently
masked two state-inconsistency cases:

1. Missing `tests/conformance/manifest.json` → conformance list
   stayed empty; the gate scanned only examples.  No error surfaced.

2. Manifest entry referencing a file that doesn't exist on disk →
   silently dropped.  A partial scan set hides regressions in the
   missing program.

Both cases now fail fast with clear stderr messages:

- Missing manifest: "ERROR: conformance manifest not found at <path>"
  before any compile work.
- Missing files: collect all manifest entries with missing files
  first, then print one row per missing file with its entry id +
  filename, then refuse to run with rationale.  Collecting first
  surfaces the full discrepancy in one message rather than aborting
  on the first missing file.

Validated both paths by (a) temporarily moving the manifest aside
and (b) appending a fake entry referencing a nonexistent file —
both produce the expected error and exit 1.

CodeRabbit found that the gate's stderr summary collapsed two
distinct failure categories into a single "unexpected [E602]/[E604]
skips" message: per-function silent skips (the gate's core
purpose) and file-level hard failures (PARSE_ERROR / TIMEOUT /
COMPILE_ERROR — file couldn't be evaluated at all).  The wording
was inaccurate when hard failures were present; a user reading
the summary couldn't tell whether the gate had found a new
silent skip or whether the compile pipeline itself was broken.

Split into two categories with distinct semantics + reporting:

- `skip_failures` — unexpected per-function [E602]/[E604]
  warnings outside the allowlist.  The core silent-skip detection
  the gate exists for.
- `hard_failures` — file-level: COMPILE_ERROR, PARSE_ERROR,
  TIMEOUT.  File couldn't be evaluated at all.

`_scan_paths` now returns `(clean, skip_failures, hard_failures)`
instead of `(clean, failures)`.  `main` prints hard failures
first (file-level problems before per-function detail), each
section with its own rationale paragraph.  Exit code 1 if either
category is non-empty.

Verified both empty (clean run) and non-empty (manifest-listed
missing file from CodeRabbit #3 testing) produce the expected
output.

…parsing

Two more valid CodeRabbit findings, both fixed:

## Stale-allowlist tracking

ALLOWED_SKIPS entries that never matched any warning during a
scan were silently suppressing nothing — and would silently mask
a future regression that re-introduces the same skip.  Mirrors
the pattern already in scripts/check_skill_examples.py.

Added a 'used_allowlist: set[str]' parameter to _scan_paths that
records each fn_name → allowlist match.  main collates 'set(ALLOWED_SKIPS) -
used_allowlist' and prints a 'STALE ALLOWLIST ENTRIES' section
with each stale entry's [code], tracking issue, and reason —
plus rationale paragraph telling the user to remove the entry
unless the affected program is being deliberately removed.  Exit
code 1 on any stale entries.

Verified by injecting a fake 'fake_stale_fn' entry: gate prints
the stale section + rationale + exits 1.

## Manifest-defensive parsing

The manifest_path.open + json.load chain previously assumed (a)
the file was valid UTF-8, (b) the parsed JSON was a list, (c)
every entry was a dict, (d) every dict had a 'file' key.  A
malformed manifest would crash with a Python traceback rather
than the structured stderr diagnostic the gate promises.

Three new defensive checks:

- 'except UnicodeDecodeError' on the open + 'except
  json.JSONDecodeError' on the parse, each producing a structured
  error message with file path + cause.
- 'isinstance(manifest, list)' check after parse with
  '{type}'.__name__ wording.
- Per-entry: 'isinstance(entry, dict)' check + explicit
  'entry.get("file")' validation with 'isinstance + non-empty
  string' shape check.  Errors include the entry id (or
  '<entry N>' fallback) for debugging.

Verified all three paths empirically: invalid JSON, JSON object
instead of array, and entry missing 'file' all produce clean
ERROR messages + exit 1.

Validated final clean run: 'Allowlisted skips suppressed: 11
known functions (11 matched, 0 stale)' — no behaviour change
when allowlist is current and manifest is well-formed.