Adopt a *_SKIP_REASON declaration convention; tether the roster to a doc

[WilfordGrimley]

Why

docs/pipeline-fidelity-gate.md fired as an audit partly on the precondition that "every empirically-derived constant/threshold/override/skip-reason [is] mapped to its home in the new pipeline, or flagged missing".

That claim could never have been tested, because the skip reasons could not be enumerated. Roughly thirty distinct values existed; ~11 were declared as *_SKIP_REASON constants and the rest were bare inline literals, several of them reaching the database through a dynamic pass-through (skip_reason=outcome.ocr_skip_reason, skip_reason=verdict.skip_reason, skip_reason=skip_reason). No static analysis could produce a complete roster, so the audit checked itself against an incomplete list. Twelve values appeared nowhere in docs/ at all. question_feed.py already documented the problem in a comment.

Meanwhile docs/features/catalog-stats.md and cardpicker/catalog_stats.py both asserted "~11 distinct reasons observed in production". The column actually holds 23.

A set cannot be tethered until it can be enumerated, so this PR does the code half first and the doc half second.

What shipped

1. *_SKIP_REASON at every write site. Every value written to CardScanLog.skip_reason now originates from a module-level constant, including the source behind each dynamic pass-through. Where a string is emitted by several calculators under different anonymous_ids with different meanings (no-evidence, ambiguous, no-text, frame-mismatch), each calculator declares its own prefixed constant — same-value/different-constant is the correct shape, a single shared constant would falsely imply one shared concept.

Pure refactor: no string value changed, and SLOW_PATH_TO_REVIEW_REASON → SLOW_PATH_TO_REVIEW_SKIP_REASON is the only rename (constant name only; "to-review" is untouched).

2. Statically enumerable. Scanning column-0 *_SKIP_REASON = "<literal>" declarations under MPCAutofill/cardpicker/ now yields the complete roster: 38 values from 55 constants. All 23 values present in production are covered.

3. Tethered. check_skip_reason_roster_tether() + _declared_skip_reasons() in .github/scripts/docs_lint.py, following check_calculator_roster_tether() (#562) in structure, error style and allowlist convention. The doc it checks is the new docs/reference/skip-reasons.md.

Why docs/reference/: docs/features/ documents user-visible product surfaces (catalog-stats, moderation, grid-selector); this is an internal vocabulary enumeration with no UI of its own, which is what reference/vote-weight-matrix.md and reference/funnel-spec.md already are. Indexed in docs/README.md and docs/MANIFEST.md.

Matching is on the literal value, not the constant name — the opposite choice from the calculator tether's full-identity-over-family rule, for a different reason rather than an inconsistent one: here the string IS the production datum (millions of rows key on it) while the constant name is an internal handle a refactor may legitimately change. Each tether matches the thing whose change would break production. docs/documentation-process.md's "Roster tethers" section now states that generalisation.

SKIP_REASON_ROSTER_ALLOWLIST is empty: every declared value has a real entry, including retired and report-only ones, because "nothing writes this any more" is exactly what an enumeration loses first.

4. Both false counts fixed — and replaced with no count rather than a corrected one. A hardcoded number nothing derives is what rotted last time; compute_skip_breakdown() is a plain GROUP BY that never needed the figure.

Verification

• cardpicker/tests/: 3036 passed, 9 skipped. docs-lint clean, mypy clean (230 files), black/ruff/isort/prettier clean.
• Byte-identical proof. An AST-level equivalence check parses each touched module at origin/master and at HEAD, inlines every *_SKIP_REASON binding (cross-module imports included), constant-folds the affected f-string, strips the declarations/__all__/docstrings, and compares the trees. All 13 touched modules: IDENTICAL. A row written after this change carries byte-identical text to one written before.
• New test cardpicker/tests/test_skip_reason_roster.py (42 cases) pins every declared value against a hand-written expected set — deliberately hand-written, since deriving it from the constants it guards would assert nothing — and re-runs the linter's own derivation so the two can't disagree.
• Fail-then-pass demo. Deleted the unmapped-layout-class, transfer-sha256-mismatch and fetch-budget-exhausted entries from the doc: linter exits 3, naming each reason and its declaration site. Restored: docs-lint: clean, exit 0.

Stated honestly rather than forced

local_phash.find_best_match is PROTECTED CORE and returns no-hashable-candidates / no-clear-winner as inline literals; they cannot be declared at source without editing a protected file. They are mirrored in the consuming module — the one place where declaration is not co-located with origin. A new literal added to find_best_match would reach CardScanLog without failing lint. That gap is recorded in the doc and closes only with an owner exception.

local_lands_identify is report-only (it never writes a CardScanLog row) and composes f"{PREFIX}{reason}" from that same protected-core return. Its five values are declared and documented anyway — they were the largest cluster of skip-reason strings with no named home, i.e. the exact defect this closes — and the prefix constant's comment records that a scan-log write must not be added there until the composition is replaced.

local_ocr and local_fallback return skip-reason-shaped strings that never reach CardScanLog (the fallback write branch was retired 2026-07-29); local_fallback is protected core in any case.

Notes for review

Diff is mechanical by design — two other branches are in flight touching image_evidence.py. Rebased onto aa56e4c0.

🤖 Generated with Claude Code

https://claude.ai/code/session_013NhYmT1PxCcyemA16dFDxN

[WilfordGrimley]

Rebased onto master (post-#569), conflicts resolved

Two textual conflicts, plus one semantic conflict git could not see.

1. image_evidence.py — the expected one

#569 hoisted the legal-line compute into _extract_legal_line and left the old block storage-only. Resolved by keeping master's hoisted structure and applying this PR's intent to it — the two inline literals became EXTRACTOR_FETCH_FAILED_SKIP_REASON / EXTRACTOR_NO_TEXT_SKIP_REASON. _extract_legal_line itself writes no skip reasons, so nothing else moved.

2. docs/features/catalog-stats.md — panel table

Both sides edited the same rows. Took this PR's skipBreakdown cell (the de-counted one) and master's participation cell (#572's card-denominated pointer). Neither intent dropped.

3. catalog_stats.py — silent breakage the AST proof caught

#568 landed new code (distinctCardsRoutedToReview) that imports and uses SLOW_PATH_TO_REVIEW_REASON — the one constant this PR renames. Git auto-merged the file cleanly because master only added lines while this branch only touched the docstring, so the rename and the new references never textually collided.

Result would have been ImportError: cannot import name 'SLOW_PATH_TO_REVIEW_REASON' at import time — the module is imported by the catalog-stats view and the hourly warm_catalog_stats job. Fixed by carrying the rename into all 13 new reference sites (catalog_stats.py, test_catalog_stats.py, docs/features/catalog-stats.md).

This is exactly what the byte-identical proof is for, and it is the argument for keeping it in the review loop rather than treating it as a one-off.

4. multi-faced-v1 removed from the pinned roster

#565 deleted the border-colour "multi-faced" gate and deliberately did not replace SINGLE_FACED_ONLY_SKIP_REASON (its own comment says so). EXPECTED_SKIP_REASONS pins declarations, so the entry had to go — but ~3,409 production CardScanLog rows still carry the value, so it keeps its row in docs/reference/skip-reasons.md, now marked Retired. It is the one value in the roster with no live declaration, and the doc says that explicitly. Dropping it from the doc instead would have lost exactly what this PR exists to preserve.

Re-verification after rebase

• Byte-identical proof re-run and re-implemented (the original script was not committed). Parses each touched module at origin/master and at HEAD, inlines every *_SKIP_REASON binding — cross-module imports and the LANDS_PHASH_SKIP_REASON_PREFIX composition included — strips declarations/__all__/docstrings, constant-folds f-strings and + concatenation, compares parse trees.
  All 14 touched modules: IDENTICAL. A CardScanLog row written after this change carries byte-identical text to one written before.
• cardpicker/tests/: 3148 passed, 11 skipped, 0 failed.
• test_skip_reason_roster.py: 41 passed (was 42 — one case less, being the retired multi-faced-v1).
• docs-lint clean; ruff, isort, black, mypy, prettier all pass.

The suite cannot run on unmodified master at all right now — the two-0096 migration conflict makes pytest-django fail to build the test database. These runs layer #576 (the hotfix) on top, which is the state this PR will actually merge into.