P1: Complete Python static validation parity with TypeScript

[tomdps]

Parent

Epic #243. This is the static-validation tracking parent between accepted optional-tool execution (#211) and language-service containment (#217).

Goal

Close the remaining mechanical Python validation gaps that are currently implemented for TypeScript: file/function metrics, import-cycle and layer policy, general symbol-use evidence, and entrypoint-aware dead-code reachability.

This parent is complete only when Python exposes truthful equivalents with exact after-state behavior, policy/config wiring, outcomes/provenance, focused tests, packed-install evidence, and no second import parser or silent unsupported pass.

Current verified gap on dev (6ed9e0e)

Python already has compiler syntax, authoritative mypy/Pyright types, source hygiene, Ruff lint/format, canonical import-edge validation, relevant-test evidence, pytest, and shared clone duplication. The remaining TypeScript validation capabilities absent or materially weaker in Python are:

• typescript.file-length
• typescript.function-metrics
• import-cycle diagnostics and configurable import-layer rules
• general reference/type-use evidence needed beyond CALLS
• automatic/configured entrypoint reachability, unused-file evidence, and non-call export usage in dead-code validation

Shared clone.duplication already covers .py/.pyi; do not create a duplicate Python clone check. Ruff is the Python lint/format authority; do not recreate TypeScript ESLint/plugin mechanics.

Child sequence

• P1: Add Python file-length and function-metrics parity #292 — Python file-length and function-metrics parity
• P1: Add Python import-cycle and layer-policy parity #293 — Python import-cycle and layer-policy parity
• P1: Add graph-core Python symbol-reference evidence #294 — graph-core Python symbol-reference evidence
• P1: Complete Python dead-code reachability and entrypoint parity #295 — Python dead-code reachability and entrypoint parity
• Close this parent only after all four children are merged to dev and the parent acceptance matrix is reconciled

The graph-reference child must precede dead-code completion. Metrics and import policy are independent but remain sequential under epic #243's one-active-run rule.

Cross-cutting contracts

1. Every check reads after-state content through ValidationFileView; overlays, created/deleted files, introduced mode, and explicit scopes must remain exact.
2. Canonical Python project context from P0 — Resolve Python projects, interpreters, environments, and tools canonically #246 and exact-state graph lifecycle from Hypothetical (validate pre-write) evaluation must be comprehensive — graph-backed checks are silently skipped #197 are reused; no root-scoped rediscovery.
3. Rust graph-core remains the sole Python import parser/resolver. Validation consumes canonical directed edges and may not add a TypeScript-side Python import grammar.
4. Syntax/version-sensitive structural analysis uses the selected exact interpreter or graph-core facts with explicit protocol/provenance; no ambient PATH or package install.
5. Missing, malformed, stale, unsupported, timeout, crash, or incomplete evidence is a typed non-pass/degraded result, never an empty clean result.
6. Check ids, manifests, policy schema, status/scan/measure/ASP projections, contracts, fixtures, package exports, docs, and packlists move together where affected.
7. Default severities match the corresponding accepted TypeScript behavior unless a separately measured policy decision changes both; this tracker does not promote speculative dead-code evidence to error.

Parent acceptance criteria

• .py/.pyi file length and executable Python function metrics have deterministic thresholds, ranges/provenance, overlay behavior, and policy composition.
• Canonical Python import edges produce deterministic cycles and layer-rule findings, including explicit TYPE_CHECKING policy behavior.
• Graph-core emits contract-bound general Python reference evidence without converting ambiguous/dynamic names into false certainty.
• Python dead code models configured and automatic project entrypoints, file reachability, callable/type/value use, stubs, tests, and explicit unsupported dynamic cases.
• Registry/manifests/capability ledger and packed-install receipts enumerate every new check and outcome; no source mutation, install, network, orphan process, or temp/cache residue occurs.
• Focused tests, npm run build, npm run lint, package proof, and configured opcore-ci proof pass on the merged dev state after every child.

Non-goals

• Python semantic LSP inspect/edit work owned by feat(inspect-edit): scope and isolate language-service projects #217/P1 — Add truthful Python LSP semantic inspection and navigation #248/P1 — Make Python rename and module moves semantic and atomic #249
• strict severity promotion owned by measured policy work such as chore(policy): shadow-run strict severity policy (cycles/dead-code as error) and publish the counts #285/policy(validation): fail hard on TS import cycles; split dead-code into proven/introduced/evidence tiers #288
• a Python-only clone implementation
• automatic fixes, installs, security/SAST claims, all-stack claims, or readiness wording

Execution rule

Immediately before each child, review current origin/dev, refine that child against the merged predecessor, and keep exactly one implementation run active. Every child requires a clean scoped PR to dev, green GitHub checks, focused behavioral proof, configured opcore-ci, merge, issue closure, and parent/epic bookkeeping before the next child starts.