codex/docs/keymap-rollout-plan.md

TUI Keymap Additive Rollout Plan

This plan restructures the existing keymap implementation into a reviewable additive stack while preserving the final behavior from revision 0f03e76c.

Goals

• Keep the final behavior effectively identical to 0f03e76c.
• Reorder history to show intent and risk reduction clearly.
• Make each change compile, format cleanly, and pass scoped tests.
• Establish high-confidence behavior characterization before binding rewrites.

Commit Sequence

1. Docs and specification foundation

   • Add/reshape long-term docs that explain how the keymap system works.
   • Include:
     • conceptual model
     • action matrix
     • default keymap template guidance with explicit URL
     • testing strategy notes
   • No functional code change.

2. Additive config primitives (not wired)

   • Introduce keymap config types and schema support in core.
   • Keep runtime behavior unchanged by not consuming these config values yet.
   • Ensure parsing/serialization paths are complete and documented.

3. Behavior characterization tests (pre-rewrite)

   • Add tests that lock down existing event behavior before switching bindings.
   • Cover key event matching and context-sensitive behaviors that must stay stable.
   • Use these tests as the safety net for subsequent rewiring.
   • Run cargo llvm-cov and target full branch coverage for keybinding logic.

4. Binding replacement using characterized behavior

   • Introduce keymap-driven binding resolution and wire call sites.
   • Replace legacy binding checks while preserving characterized behavior.
   • Keep docs in sync with any semantics that became explicit.

5. UX polish and affordances

   • Apply help/footer/tooltip/key-hint refinements once behavior is stable.
   • Keep affordance text concise and formatted for readability.
   • Update snapshots as needed.

Validation Gates Per Commit

For each commit in the sequence:

1. Run formatting (just fmt in codex-rs).
2. Run scoped tests for affected crates (minimum cargo test -p codex-tui for TUI changes and relevant core tests when core changes).
3. Ensure branch compiles cleanly (cargo test path used as compile gate).
4. For characterization and binding commits, run coverage and track branch coverage for keybinding logic (cargo llvm-cov).

JJ Workflow

• Build stack from trunk() with explicit ordered changes.
• Use jj new -A / jj new -B to place changes relative to target revisions.
• Rebase existing implementation changes into the new stack as needed.
• Resolve conflicts immediately and keep each change coherent.
• Use clear jj describe messages with title + explanatory body.

Acceptance Criteria

• Final tip behavior matches 0f03e76c in practice.
• Stack reads top-to-bottom as: docs -> config -> characterization -> rewiring -> UX polish.
• Each commit is independently reviewable with passing checks.