SeedPass/docs/dev_control_center.md

SeedPass Dev Control Center

Last updated: 2026-03-10 Branch baseline: beta

This is the single source-of-truth document to decide what to work on next.

1) Current Health Gate

Run before starting any new slice:

git pull --rebase origin beta
PATH=".venv/bin:$PATH" scripts/run_ci_tests.sh

Latest verification in this session:

• origin/beta matched local beta (no new remote commits to pull).
• scripts/run_ci_tests.sh: PASS
  • determinism gate: PASS
  • full suite: 1145 collected
• Focused TUI validation slices:
  • ./.venv/bin/pytest -q src/tests/test_tui_v3_smoke.py src/tests/test_tui_v3_parity.py src/tests/test_typer_cli.py src/tests/test_core_api_services.py
  • latest result in the current v3/CLI/API suite: 181 passed

2) Canonical Status Sources

Use these docs as inputs, but treat this file as the decision layer:

• TUI v3 plan (current working UI roadmap): docs/tui_v3_plan.md
• TUI v2 plan: docs/tui_v2_plan.md
• TUI v2 artifacts remain logic/reference material only unless explicitly reactivated
• Semantic vector index integration plan: docs/semantic_vector_index_plan.md
• Index0 atlas execution plan: docs/index0_atlas_execution_plan_2026-03-05.md
• Atlas/search/graph integration plan: docs/atlas_search_graph_integration_plan_2026-03-05.md
• Nostr communications future capability reference: docs/nostr_comms_reference_and_future_capability_2026-03-05.md
• Cutover memo: docs/tui_v2_cutover_decision.md
• Security readiness: docs/security_readiness_checklist.md
• Supply-chain integrity: docs/supply_chain_release_integrity.md
• QA roadmap: docs/agent_testing_roadmap.md
• Agent TUI testing: docs/ai_agent_tui_testing.md
• KB scale validation: docs/kb_scale_validation.md
• Beta hardening report: docs/beta_hardening_2026-03-02.md

3) What Is Still Open

Parity / Product

• TUI v3 is now the default launch target (seedpass -> v3).
• TUI v3 now owns:
  • startup profile selection / unlock
  • add-new / recover / restore onboarding
  • inspector boards and context-aware lower pane behavior
  • default-shell UX work
• TUI v2 remains available via seedpass tui2, but is no longer the active UI development target.
• Recent v3 hardening shipped (2026-03-10):
  • Bug fixes: replaced sys.exit(0) with os._exit(0) to prevent SIGSEGV on graceful exit; added TTY check to guard against non-interactive stdin preflight/password loops in tui3; fixed missing Binding import in pubkey screen.
  • Action strip rename: "Seed" -> "Profiles" button for clarity.
  • Restore/import guidance: more explicit warning messaging and mode guidance surfaced before recovery paths execute.
  • Profile management polish: improved visual hierarchy, clearer success/failure summaries, and status icon treatment on profile and maintenance screens.
  • Maintenance screen visual polish: status icons, bordered intro cards, stronger visual hierarchy across all maintenance screens.
  • Search graph navigation: multi_hop_neighbors and filtered_neighbors added to SearchService; LinkedItemsPanel enhanced with keyboard navigation, kind filtering, and atlas context display.
  • Sort/filter controls: keyboard shortcuts s/f/\ for cycling sort/filter/clear; active-state toolbar highlighting; Clear All button on the main grid surface.
• Remaining v3 hardening gaps:
  • deeper graph-pivot workflows and richer atlas/search handoff remain
  • additional legacy utility and maintenance affordances can continue moving to v3 as discovered
  • profile-management flows may benefit from further naming and operator-guidance polish
  • maintenance screen mockup-level polish passes may be needed for any new screens added

Security Readiness

• docs/security_readiness_checklist.md still marks:
  • #4 Backup/restore integrity: In Progress
  • #5 Nostr sync security/resilience: In Progress
  • #7 Testing gates/quality thresholds: In Progress
  • #8 Supply chain/release integrity: In Progress
  • #9 Operational runbooks: In Progress
  • #10 External audit/rollout: In Progress

Supply Chain Specific

• docs/supply_chain_release_integrity.md remaining work:
  • execute at least one tagged production release through integrity workflow and record evidence
  • resolve or renew exception GHSA-wj6h-64fc-37mp before expiration
  • enforce release protection rules
  • execute and record maintainer verification runbook

Semantic Search Roadmap

• Semantic index plan drafted and linked:
  • docs/semantic_vector_index_plan.md
• Current implementation status:
  • Phase A complete (local derived index + profile-scoped manifest/records + config flag)
  • Phase B baseline complete (CLI + API surfaces + initial tests)
  • Phase C complete baseline (legacy + TUI v2 semantic workflows and mode toggles)
  • Next: incremental mutation hooks + hybrid quality hardening

Search / Graph Integration Roadmap

• New cross-system plan drafted and linked:
  • docs/atlas_search_graph_integration_plan_2026-03-05.md
• Purpose:
  • unify index0, tags, links, and local semantic search into one search/navigation model
• Phase A baseline landed:
  • SearchService added in src/seedpass/core/api.py
  • unified result payload with score breakdown, match reasons, safe excerpts, tags, and linked-hit summaries
  • deterministic filter/sort pipeline added for keyword / hybrid / semantic search modes
  • v3 entry grid now routes through the unified search path instead of branching search logic in the widget layer
  • focused regression coverage added in src/tests/test_core_api_services.py and src/tests/test_tui_v3_smoke.py
• Phase B baseline landed:
  • SearchService.linked_neighbors(...) and relation_summary(...) now provide explicit outgoing/incoming graph navigation data
  • v3 grid now preserves active search query across refresh/filter/sort changes
  • v3 grid now exposes explicit in-app filter/mode/sort controls instead of palette-only command flow
  • v3 inspector now includes a linked-items panel with direct open-entry actions
  • focused regression coverage expanded in src/tests/test_core_api_services.py and src/tests/test_tui_v3_smoke.py
• Phase B extended (2026-03-10):
  • SearchService.multi_hop_neighbors(...) for multi-hop linked graph traversal beyond direct neighbors
  • SearchService.filtered_neighbors(...) for kind-filtered neighbor queries
  • LinkedItemsPanel keyboard navigation: arrow keys to move through linked items, open via enter
  • LinkedItemsPanel kind filter: filter displayed linked items by entry kind
  • LinkedItemsPanel atlas context display: show atlas metadata alongside linked entries
  • sort/filter keyboard shortcuts landed: s cycles sort, f cycles filter, \ clears filter
  • main grid toolbar now highlights active sort/filter state visually
  • Clear All button on the grid for single-action filter/sort reset
  • focused regression coverage updated in src/tests/test_core_api_services.py and src/tests/test_tui_v3_smoke.py
• Next planned implementation:
  • deeper atlas/search handoff and graph-aware result workflows
  • broader agent-facing atlas navigation and deeper search/navigation integration

Future Capability: Nostr Communications

• Research/reference doc added:
  • docs/nostr_comms_reference_and_future_capability_2026-03-05.md
• Purpose:
  • capture the relevant NIPs for future DMs and team/community chat in SeedPass
  • align that capability with managed deterministic identities, index0, and future institutional knowledge workflows
• Current planning direction:
  • prefer NIP-17 + NIP-44 + NIP-59 for private DMs
  • evaluate NIP-29 as the strongest candidate for managed institutional group chat
  • treat NIP-28 and NIP-72 as public/community-oriented layers
• Not current implementation work:
  • this is documented as a future addition and should not preempt the current v3/search/index0/security priorities

Index0 Atlas Roadmap

• New architecture/spec track drafted:
  • docs/index0_atlas_execution_plan_2026-03-05.md
• Phase 0 implementation spec drafted:
  • docs/index0_phase0_spec_2026-03-05.md
• Phase 1 foundation slice landed:
  • reserved _system.index0 namespace normalization
  • deterministic index0 merge helper
  • Nostr manifest optional index0 metadata support
  • focused tests in src/tests/test_index0_core.py
• Phase 1 CRUD/link emission slice landed:
  • deterministic index0_event emission from entry create/modify/archive/restore/delete flows
  • deterministic index0_event emission from link add/remove flows
  • writer-head updates and hierarchy-aware scope derivation from active profile path
  • focused regression coverage in src/tests/test_index0_events.py
• Phase 1 checkpoint/manifest slice landed:
  • deterministic daily checkpoint rebuild from canonical index0_event streams
  • bounded checkpoint retention per writer
  • manifest index0 publication of checkpoint hashes and stream heads during sync
  • focused regression coverage in src/tests/test_index0_checkpoints.py
• Phase 1 canonical views slice landed:
  • deterministic synced children_of, counts_by_kind, and recent_activity views
  • view rebuild runs in the same compaction path as checkpoints
  • lightweight atlas read helpers landed in core
  • focused regression coverage in src/tests/test_index0_views.py
• Atlas consumer slice landed:
  • AtlasService added in src/seedpass/core/api.py
  • v3 palette can open an atlas/wayfinder screen backed by the service layer
  • v3 main workspace now shows an always-visible atlas strip in the shell chrome
  • v3 atlas screen now supports direct entry jumps and quick filter jumps
  • focused regression coverage updated in src/tests/test_core_api_services.py and src/tests/test_tui_v3_smoke.py
• Current accomplishments summary:
  • v3 is the default UI and owns unlock/onboarding/maintenance/profile/security flows
  • semantic index is integrated as a local derived retrieval layer
  • canonical tags and typed links already exist at the entry model level
  • index0 now covers canonical atlas events, checkpoints, manifest metadata, synced views, service reads, and first v3 consumers
• Intent:
  • add canonical encrypted atlas state inside the existing payload for audit, hierarchy wayfinding, and future KB/chat navigation
• Key implementation direction:
  • reserved _system.index0 namespace inside the synced payload
  • deterministic merge + checkpointed hash-chain validation
  • rebuildable wayfinder views layered on top
• Sequencing:
  • Phase 0 spec/schema is drafted
  • Phase 1 foundation + CRUD/link emission + checkpoint/manifest publication + first canonical views are implemented
  • atlas read service layer and first v3 consumers are implemented
  • first actionable v3 wayfinder navigation flows are implemented
  • next implementation slice: broader agent-facing atlas workflows and deeper search/navigation handoff, plus any later event-pruning compaction policy
  • implementation phases should not preempt current TUI cutover-critical or security-readiness blockers

4) Recommended Next Steps (Priority Order)

1. Continue deeper graph navigation and atlas/search handoff: : multi-hop graph pivots, kind-filtered navigation, and richer atlas-aware result workflows built on the new multi_hop_neighbors and filtered_neighbors service methods.
2. Continue TUI v3 utility/maintenance carryover: : any remaining settings-linked operational flows, discoverable security maintenance, and final maintenance-screen polish for new screens added going forward.
3. Resume Index0 Atlas and graph follow-on work: : agent-facing atlas workflows, deeper search/navigation handoff, event-pruning compaction policy.
4. Continue security-readiness blockers in parallel where they do not conflict with the v3 path.

5) Next Slice Definition (Recommended Immediate Work)

Slice A: “Search Graph Navigation” — COMPLETED (2026-03-10)

All exit criteria met:

• SearchService.linked_neighbors, multi_hop_neighbors, filtered_neighbors, and relation_summary are implemented
• v3 exposes explicit sort/filter/clear affordances via s/f/\ keyboard shortcuts and toolbar highlighting
• linked items can be viewed, filtered by kind, and opened via keyboard from the inspector panel
• focused search/atlas/v3 suites green at 181 passed

Slice B: “Deep Graph + Atlas Handoff”

Deliverables:

• Deepen multi-hop graph traversal with richer pivot UX (breadcrumb trail, back navigation, grouped by relation type).
• Extend atlas/search handoff so graph-pivot results flow through the unified SearchService result model.
• Continue expanding inspector linked-items panel with atlas context and relation-type labels.
• Keep the atlas/search/graph plan and control center synchronized with shipped behavior as this slice lands.

Exit criteria:

• multi-hop graph navigation is accessible from the inspector without leaving the main workspace
• atlas context is surfaced alongside linked items in the inspector panel
• focused search/atlas/v3 suites stay green

Progress update (2026-03-02):

• Matrix added: docs/tui_v2_legacy_parity_matrix.md
• Managed-account session parity landed in TUI v2:
  • managed-load (optional: entry_id)
  • managed-exit
  • service wrappers and tests added
• Nostr maintenance parity landed in TUI v2:
  • nostr-reset-sync-state
  • nostr-fresh-namespace
  • service wrappers and tests added
• Nostr pubkey utility parity landed in TUI v2:
  • npub (alias: nostr-pubkey)
  • displays active profile npub (+ QR payload) in sensitive panel
  • tests added for success and validation paths
• Full legacy workflow coverage closed with bug-bash evidence:
  • python scripts/ai_tui2_agent_test.py --scenario extended --verbose => PASS
  • python scripts/ai_tui_agent_test.py --scenario extended --verbose => PASS
• Coverage gates strengthened for TUI v2 critical path:
  • scripts/run_ci_tests.sh now enables critical coverage gate by default.
  • scripts/check_critical_coverage.py default thresholds now include src/seedpass/core/api.py=85.
  • new focused gate scripts/tui2_coverage_gate.sh enforces:
    • src/seedpass/tui_v2/app.py >= 78%
    • src/seedpass/core/api.py >= 85%
• Nostr deterministic resilience suite expanded:
  • new tests in src/tests/test_nostr_resilience_failure_modes.py cover:
    • no encrypted data sync attempt
    • publish-without-event fallback error handling
    • preservation of relay-provided publish errors
    • snapshot-missing warning path
    • snapshot-fetch exception warning path
• Cutover memo refreshed with current gate status and blockers:
  • docs/tui_v2_cutover_decision.md updated (March 2, 2026)
  • documents parity-complete status, strengthened CI gates, and remaining hardening blockers
• Supply-chain and runbook docs centralized for closure work:
  • docs/release_verification_runbook.md
  • docs/release_protection_policy.md
  • docs/operational_runbooks.md
  • docs/staged_rollout_runbook.md
  • docs/agent-handoffs/incidents/2026-02-15-relay-health-preflight-job.md
• Discoverability parity improved in TUI v2:
  • added full palette command reference (help-commands, alias commands)
  • help now also renders in-app command reference in entry detail pane
  • focused TUI gate remains green with improved app coverage (79.97%)
• Session affordance parity improved in TUI v2:
  • added session-status, lock, and unlock <password> palette commands
  • left pane now displays explicit session lock state and managed-session indicator
  • lock state blocks open/reveal/QR workflows until unlock succeeds
  • interaction + matrix tests extended for usage, success, and failure paths
• UI refresh progress (mockup-aligned) now in active implementation:
  • shell scaffold + top ribbon + action strip
  • grid modernization (table-like rows/heading)
  • core + advanced inspector boards
  • advanced inspector actions: copy <field> (optional: confirm) and export-field <field> <path> (optional: confirm)
  • density controls: d key and density <compact|comfortable>
  • profile tree scaffold visible in left pane
• Online-mode defaults updated:
  • profiles now default to online (offline_mode = false by default)
  • one-time onboarding notice added for first online profile load with settings guidance

Current UI refresh remaining queue:

1. Keep strict mockup parity Open count at zero: : preserve 2FA copy URL command/board affordance coverage.
2. Finish remaining Minor Gap board polish: : UI Board, Password, Stored Password, Note geometry/rhythm and action-chip treatment.
3. Final UI-board density/viewport balance polish: : keep both dense table rows and usable lower inspector in common terminal sizes.
4. Continue semantic indicator wording/placement tuning (baseline compact ribbon pass is now landed) for readability under narrow terminals.
5. Execute strict closeout pass from: : docs/tui_v2_ui_refresh_plan.md section "15) Mockup Board Parity Audit (2026-03-02)".
6. Keep default list focus + hotkey reliability + compact responsive regression green: : test_tui2_textual_default_focus_keeps_sensitive_hotkeys_active. : test_tui2_textual_compact_layout_hides_link_panel_and_can_restore.
7. Keep SSH/PGP/Nostr board-fidelity regression green: : test_tui2_textual_ssh_pgp_nostr_boards_show_action_fidelity.
8. Keep Seed/Managed Seed board-fidelity regression green: : test_tui2_textual_seed_and_managed_seed_boards_show_fidelity.
9. Preserve micro-alignment density (table/header/panel spacing) in ongoing UI slices.
10. Keep Note/2FA metadata consistency regression green: : test_tui2_textual_note_and_totp_boards_include_common_metadata.
11. Preserve table/header/action micro-copy consistency introduced in latest polish.
12. Track strict closeout statuses (Done / Minor Gap / Open) per board and re-evaluate after each slice.
13. Keep compact discoverability regression green (inline notes/tags fallback when side card is collapsed).
14. Keep viewport-height balance regression green (activity fallback + layout rebalance on short screens).
15. Preserve icon-enhanced board title hierarchy introduced in typography polish pass.
16. Keep strict scorecard at Open=0 and advance Minor Gap -> Done boards incrementally.

6) Working Rule

When priorities conflict:

1. Keep CI green.
2. Close user-visible parity gaps.
3. Raise security/testing gates.
4. Then optimize docs and process.

7) Active UI Parity Focus (Mockup-Coupled)

Use this order for current TUI v2 design iterations:

1. Preserve upper table density while retaining usable lower inspector in the same viewport.
2. Normalize shared inspector header metadata/actions across all kinds.
3. Complete board-specific action affordance fidelity: : Password/Stored Password -> Note/2FA -> Seed -> SSH/PGP/Nostr.
4. Keep each slice test-gated: : poetry run pytest -q src/tests/test_tui_v2_textual_interactions.py src/tests/test_tui_v2_action_matrix.py
5. Capture screenshot evidence after each slice in: : artifacts/ui_eval/current_tui2_after*.png.