Skip to content

python-reference-checkpoint.md

Latest commit

 

History

History
78 lines (61 loc) · 3.68 KB

python-reference-checkpoint.md

File metadata and controls

78 lines (61 loc) · 3.68 KB
Raw

Python Phase 7H Reference Checkpoint

Date: 2026-07-26

Status: frozen reference implementation; not a release or adoption decision.

Decision

The Python implementation stops after Phase 7H. It is retained as executable reference material for a clean Rust successor, not as a product to install, extend through Phase 7I, or make compatible with future work.

The repository preserves the Phase 7 contracts, isolated Codex evidence, fixtures, and test harnesses because they establish useful product boundaries: provider-native workflow remains primary; Switchboard is an auxiliary tmux navigator; completed provider results remain the visible tip; provider history remains canonical; and filesystem ownership is explicit.

This checkpoint does not create a release, a tag, an installation path, or a normal-workflow adoption. The normal workflow remains native Codex, Claude Code, and tmux.

Retained evidence

  • Phase 7B through 7H contracts and acceptance records, including the isolated Codex navigator, workstream, native-rollover, attention, and input-fenced history studies.
  • Sanitized fixtures and deterministic tests that record provider capability, action order, private-surface isolation, result-tip preservation, and cleanup expectations.
  • The narrow product direction established by the terminal-market research: preserve the directly interactive native provider TUI and use tmux as the presentation substrate rather than replacing the provider interface.

Historical acceptance proves isolated technical behavior only. It does not prove the application is ready for daily use or that any user data has been adopted.

Why this is not a viable product checkpoint

The final review identified material gaps that should be redesigned rather than patched forward in Python:

  • Result observation and durable attention are separate persistence steps, so a crash can leave a completed result without its attention record.
  • Surface focus and persisted view coordination are not one atomic operation; a race can focus a different live view than the revision recorded by the controller.
  • The navigator lacks viewport/recovery completeness and can omit threadless state; retirement can leave no obvious next view.
  • Each navigator window can start duplicate controller and Codex observer activity instead of sharing one generation-scoped owner.
  • Some CLI error paths still expose implementation tracebacks rather than a durable operator-facing diagnostic.
  • The live fixture does not make Switchboard artifact-digest verification or provider-process leak detection strong enough for a release claim.
  • A legacy local 0.3.4 hook deployment and its separate 0.3.5 broken-pipe maintenance branch are operational history, not part of this Phase 7 checkpoint and must not be merged into it as a compatibility path.

Handoff to Rust

The successor should be a clean implementation in a new repository, with no schema, API, or runtime compatibility obligation to this code. It should begin with a single generation-scoped control owner and thin navigator/control clients, then re-establish the retained contracts through fresh tests and isolated live evidence. The Python code may be used as behavioral reference, not as a component to embed or a release candidate to revive.

Phase 7I remains a useful end-to-end acceptance specification, but it is not approved to proceed in this repository.

Checkpoint validation

The checkpoint requires the automated suite, lint and formatting checks, compile validation, Git whitespace check, reproducible source/wheel builds, package-content audit, and a clean-wheel lifecycle smoke. These checks validate the reference artifact only; they do not change its non-release status.