thePR0M3TH3AN/SeedPass
1
0 Fork 0
mirror of https://github.com/PR0M3TH3AN/SeedPass.git synced 2026-10-28 08:22:03 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
a9e31215eaec773335e9cfec9a4e893d5ce6d328
SeedPass/docs/tui_v2_cutover_decision.md
T
thePR0M3TH3ANandClaude Opus 5 eb67dac576 docs: bridge README to the TypeScript rebuild; banner the Python-era docs 
The README had zero mentions of the TypeScript implementation -- on the
branch proposing to make it the main line, a reader (including PR #989's
reviewers) would find only the Python product. A bridge section near the top
now says what the rebuild is, its status (under independent review; do not
put irreplaceable secrets in it yet), and where the migration guide, the
vault/identity spec, and the cutover plan live. Deliberately a bridge, not a
rewrite: everything below it still accurately describes the Python version,
which is what install.sh installs today. Advertising the TS implementation
as the product before its review lands would be docs describing an
aspirational state -- the exact failure mode this branch has been stamping
out.

The 14 Python-era planning docs most likely to mislead (tui_v2/v3,
index0/atlas, semantic) carry a one-line legacy banner so a reader can tell
a historical record from a living document.

The full TS-first rewrite -- README, landing page, docs triage, CI scoping,
dependabot config -- is specced as a merge-day checklist under the cutover
item in TODO.md, so main never advertises a stale product in either
direction.

Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Tkj4rzKBA3uhfgk7kqjsb8
2026-08-18 14:07:53 -04:00

3.8 KiB
Raw Blame History

TUI v2 Cutover Decision Memo

Legacy (Python implementation). This document describes the Python version, which retires to legacy/ after the TypeScript cutover (PR #989). The TypeScript interactive mode follows the classic v1 menus; TUI v2/v3, index0/atlas, and semantic search were not ported. Kept as historical record.

Date: March 2, 2026
Branch: beta
Decision owner: SeedPass maintainers

Decision

Current branch state: seedpass default interactive routing launches TUI v2 first.
Legacy fallback remains intentionally available during hardening:

  • seedpass --legacy-tui
  • seedpass legacy
  • seedpass tui2 --fallback-legacy

Decision Update (March 2, 2026)

Cutover readiness has improved materially since the initial memo draft:

  • parity checklist now marks full legacy workflow coverage complete
  • Textual interaction suites and parity matrix coverage are in place
  • CI now includes both runtime smoke and stronger coverage gates for TUI v2 critical paths
  • deterministic Nostr failure-mode resilience tests have been expanded

Given this state, the default routing decision on beta is now technically aligned with implemented gates. Remaining work is focused on release hardening and operational risk controls, not core TUI parity.

Gate Status Snapshot

  1. Parity closure: Pass
  • docs/tui_v2_parity_checklist.md marks Full legacy workflow coverage: Yes.
  • Evidence:
    • artifacts/agent_tui_test/20260302T135526Z/report.json
    • artifacts/agent_tui2_test/20260302T135526Z/report.json
  1. Test coverage and CI gates: Pass (expanded)
  • Runtime smoke:
    • scripts/tui2_check_smoke.sh
  • Critical module gate (default in CI runner):
    • scripts/check_critical_coverage.py
    • includes src/seedpass/core/api.py >= 85%
  • Focused TUI v2 gate:
    • scripts/tui2_coverage_gate.sh
    • enforces:
      • src/seedpass/tui_v2/app.py >= 78%
      • src/seedpass/core/api.py >= 85%
  1. Large-vault validation: Pass
  • src/tests/test_tui_v2_large_vault_validation.py
  • src/tests/test_tui_v2_kb_scale_stress.py
  1. Docs/help alignment: Pass (ongoing maintenance)
  • keybinding/palette help updated with landed parity commands
  • cutover/fallback command paths documented in parity/checklist docs
  1. Release safety fallback: Pass
  • legacy fallback command/flag paths retained for one-release safety window

Remaining Blockers (Cutover Hardening)

These are now the main blockers for promoting from beta hardening to broad release confidence:

  1. Nostr resilience soak validation (beyond deterministic unit tests)
  • deterministic failure-mode suite now exists:
    • src/tests/test_nostr_resilience_failure_modes.py
  • still recommended:
    • optional real-relay soak lane and outage/retry drift capture across environments
  1. Supply-chain and release-integrity completion
  • complete pending items in docs/supply_chain_release_integrity.md:
    • release-protection enforcement
    • GHSA exception disposition documentation
    • maintainer verification runbook evidence
  1. Operational runbooks and staged rollout evidence
  • incident/runbook readiness still open in docs/security_readiness_checklist.md
  • staged rollout + rollback drill evidence still needs explicit record

Rollout Recommendation

For the next production-facing release:

  1. Keep TUI v2 default route.
  2. Keep legacy fallback enabled for one release.
  3. Publish release notes with explicit fallback instructions.
  4. Require passing:
    • scripts/run_ci_tests.sh
    • scripts/tui2_coverage_gate.sh
    • parity bug-bash harnesses (ai_tui_agent_test.py, ai_tui2_agent_test.py)

Rollback Plan

If a cutover regression is detected:

  • switch default interactive route back to legacy TUI in CLI callback routing
  • keep TUI v2 as opt-in path while patching regressions
  • publish incident note with repro, mitigation, and re-enable criteria
Reference in new issue View Git Blame Copy Permalink