EPIC: Production-grade Python support and developer tooling

[tomdps]

Goal

Complete Opcore's production Python developer-tooling slice end to end, one sequential tracer at a time, with compiler truth, canonical project/import/overlay state, truthful optional tools, bounded semantics, safe semantic edits, and release-commit-bound evidence. The epic is not complete at a phase boundary, child merge, opened PR, narrow test, or generated receipt. No readiness/parity wording is authorized before #251's final matrix proves the exact candidate.

Non-negotiable Python contracts

1. Compiler truth first. Syntax uses the canonical selected repository interpreter/compiler; zero diagnostics is success only with machine-readable execution/provenance evidence.
2. One authoritative type checker. Each canonical project runs exactly one explicitly selected mypy or Pyright authority, never arbitrary precedence or fallback.
3. Canonical project semantics. Every Python command reuses one per-file project/interpreter/config/environment context.
4. One exact after-state. Validation, graph, tools, semantics, and edit planning observe the same immutable overlay/file-view identity and complete source/config/support-file universe.
5. One import truth. Rust graph-core owns Python import parsing/resolution; TypeScript consumers reuse materialized facts and never recreate a parser/resolver.
6. Truthful optional tools. Ruff/pytest/mypy/Pyright/provider states are degraded only when an enabled check/capability actually consumes them; disabled/not-applicable/skipped is not pass.
7. Bounded semantics and atomic edits. Semantic requests have typed ambiguity/resource/lifecycle failure, no silent text fallback, checksum-bound preview/validation/apply, and verified rollback for handled failures.
8. Evidence authorizes wording. Public claims follow same-candidate installed receipts, OS/interpreter/tool cells, representative repositories, provenance, and capability-ledger truth. Wording never authorizes itself.

Validation/semantic execution must not install/sync/download tools or environments, rewrite source/config/lock/environment files, leak temp/cache state, expose a public opcore asp group, claim sandbox/security/SAST, claim all-stack/old-tool replacement/automatic fixes/AI authorship, or emit a blended score.

Current core issue status

• P0 — Make Python syntax validation compiler-truthful #244 — compiler-truthful syntax, merged through PR feat: P0 — Make Python syntax validation compiler-truthful #252
• P0 — Resolve Python projects, interpreters, environments, and tools canonically #246 — canonical project/interpreter/config resolver, merged through PR feat: add canonical Python project-context resolver #254
• fix(python): share import resolution between validation and graph #209 — canonical graph-core Python import extraction/materialization, merged through PR fix(python): share import resolution with graph #255
• Hypothetical (validate pre-write) evaluation must be comprehensive — graph-backed checks are silently skipped #197 — exact hypothetical overlay graph/file-view lifecycle, merged through PR feat: Hypothetical (validate pre-write) evaluation must be comprehensive — graph-backed checks are silently skipped #276 as 9b2e740923b1023db45589ed19c25bde44d8939d
• P0 — Harden Python type checking and configuration semantics #245 — one authoritative type gate; closed after merged P0: Make mypy the exact authoritative Python type gate #256/P0: Complete the authoritative Python type gate with Pyright #257 evidence
• fix(python): make ruff and pytest toolchain status honest #211 — truthful Ruff/pytest execution; tracking parent
• feat(inspect-edit): scope and isolate language-service projects #217 — bounded inspect/edit language-service lifecycle; tracking parent
• P1 — Add truthful Python LSP semantic inspection and navigation #248 — managed Python semantic inspection; tracking parent
• P1 — Make Python rename and module moves semantic and atomic #249 — semantic Python rename/module/package move; tracking parent
• P2 — Ship honest Python readiness, setup, receipts, and cross-platform cutover #251 — release matrix/setup/provenance/receipts/claims; maintainer-owned tracking parent

Closed duplicate issues #247/#250 remain historical pointers only. #197 and #209 are accepted prerequisites; #211 is the active optional-tool tracker after #245. Do not recreate duplicate work or point a dependency at a superseded issue.

Strict sequential execution graph

Only one implementation run may be active. Immediately before each child: inspect current origin/dev, re-read the parent/child/dependencies/current code, refine the issue body, verify no duplicate/stale dependency, then implement and require merge into dev, focused behavior proof, clean scoped diff, and configured opcore-ci proof before advancing.

Overlay graph

• Hypothetical (validate pre-write) evaluation must be comprehensive — graph-backed checks are silently skipped #197 — exact hypothetical graph/file-view evaluation accepted after PR feat: Hypothetical (validate pre-write) evaluation must be comprehensive — graph-backed checks are silently skipped #276, focused exact-state reproductions, cleanup proof, and local opcore-ci

Type gate — parent #245

• P0: Make mypy the exact authoritative Python type gate #256 — authoritative mypy tracer
• P0: Complete the authoritative Python type gate with Pyright #257 — authoritative Pyright and mixed-project tracer
• Close P0 — Harden Python type checking and configuration semantics #245 after both children map every original acceptance cell

Truthful tools — parent #211

• P1: Run truthful opt-in Ruff lint and format checks #258 — opt-in real Ruff lint/format
• P1: Collect and execute truthful opt-in relevant pytest tests #259 — opt-in real pytest collect/execute over graph candidates
• Close fix(python): make ruff and pytest toolchain status honest #211 after candidate/execution/status/metrics truth is proven

Language-service containment — parent #217

• P1: Bound read-only inspect projects and warm-session lifecycle #260 — bounded snapshot-free read-only inspect and warm lifecycle
• P1: Bound edit-preview projects and touched-file snapshots #261 — bounded one-at-a-time mutable edit preview lifecycle
• Close feat(inspect-edit): scope and isolate language-service projects #217 after lifecycle/resource/fault evidence passes

Semantic inspect — parent #248

• P1: Add managed Python semantics for definition and references #262 — managed/configured provider plus definition/references
• P1: Add Python type intelligence routes #263 — type definition/hover/signature/implementations
• P1: Add Python symbols, call hierarchy, and rename capability truth #264 — symbols/call hierarchy/rename capability truth
• Close P1 — Add truthful Python LSP semantic inspection and navigation #248 after every route/state/provenance/cleanup cell passes

Semantic edit — parent #249

• P1: Preview Python semantic rename as checksummed WorkspaceEdit #265 — checksummed semantic rename preview
• P1: Apply Python semantic rename atomically with rollback #266 — validation-bound atomic apply and rollback
• P1: Make Python single-module moves import-aware or refuse #267 — semantic single-module move
• P1: Make Python package-subtree moves atomic and import-aware #268 — atomic package-subtree move
• Close P1 — Make Python rename and module moves semantic and atomic #249 after no-fallback/path/rollback/import-completeness proof passes

Release — parent #251

Maintainer/subagent-owned by default. Do not launch Zeroshot for this parent or a child without explicit user re-delegation after that child's JIT review.

• P2: Define and project the canonical Python capability ledger #269 — canonical capability/readiness ledger
• P2: Make Python setup dry-run-first, exact, reversible, and manager-aware #270 — exact reversible setup/disable/uninstall UX
• P2: Prove managed semantic artifacts and offline runtime provenance #271 — managed semantic artifact provenance
• P2: Prove every claimed Python path from a clean packed install #272 — isolated packed public-path receipts
• P2: Add native OS, Python, and toolchain matrix evidence #273 — native platform/interpreter/tool cells
• P2: Audit representative public Python repositories #274 — representative pinned repository audit
• P2: Gate Python claims and publish on the exact proven candidate #275 — same-candidate public-claim/publication gate
• Close P2 — Ship honest Python readiness, setup, receipts, and cross-platform cutover #251 only from release-commit-bound proof

Dependency chain

#244 + #246 + #209 -> #197 -> #256 -> #257 -> #245 close -> #258 -> #259 -> #211 close -> #260 -> #261 -> #217 close -> #262 -> #263 -> #264 -> #248 close -> #265 -> #266 -> #267 -> #268 -> #249 close -> #269 -> #270 -> #271 -> #272 -> #273 -> #274 -> #275 -> #251 close -> final epic audit.

#244 has one accepted deferred resolver integration: #246's canonical resolver satisfies it; no separate repair issue remains.

Final epic closure

Before closing #243:

• every active core issue above and every child is closed by merged dev PR evidence;
• no stale dependency points to a closed duplicate or an unaccepted predecessor;
• every predecessor PR/commit and focused/real-tool/packed proof is linked;
• source, packed, platform, representative-repo, provenance, setup, status/help/docs/descriptor/metrics/receipt cells agree on each capability;
• opcore-ci and release gates pass against the exact release candidate;
• protected native/package/release artifacts are restored from any out-of-scope churn;
• no hidden fallback, orphan process/temp state, unsupported-cell rounding, or forbidden claim remains.

Only then update every checkbox, determine public copy from #251's matrix, and close #243.