codex-controller-loop/.agent/controllers/module-mosaic/plan.toon

version: 6
goal_summary: "Refactor the remaining oversized Rust modules into focused directory modules with thin facades, stable public APIs, colocated tests, unchanged controller behavior and persisted formats, then finish with full Rust verification."
steps[8]:
  - id: guardrails
    title: Add Refactor Guardrails
    purpose: Lock down the current behavior that must survive file moves before changing module structure.
    notes: "Completed. Guardrail coverage exists for model, process, storage, app, and UI behavior, including serialized cwd-sensitive TOON tests and the cached session-view shape used by app/UI call sites."
    inputs[7]: src/model.rs,src/process.rs,src/storage/toon.rs,src/app/tests.rs,src/ui/mod.rs,src/app/session.rs,src/app/mod.rs
    outputs[5]: Focused tests covering plan/state/schema behavior in the model boundary,"Focused tests covering codex event parsing, usage snapshots, and stderr filtering","Focused tests covering TOON roundtrips, controller discovery, controller id normalization, and cwd-sensitive discovery flows","Focused app tests covering planning command gating, scrolling, and submission behavior","Focused UI tests covering screen rendering, wrapping, and session selection extraction"
    dependencies[0]:
    verification[1]:
      - label: Targeted guardrail tests
        commands[5]: "cargo test -q model::tests","cargo test -q process::tests","cargo test -q storage::toon::tests","cargo test -q app::tests","cargo test -q ui::tests"
    cleanup_requirements[2]{label,description}:
      Colocate new tests,"Keep each new or moved test with the module that owns the behavior instead of adding another catch-all test file."
      Avoid duplicate fixtures,Reuse existing sample app and model fixtures where possible so the refactor does not create parallel test scaffolding.
    status: done
    attempts: 1
  - id: "model-modules"
    title: Split Shared Model Types
    purpose: "Refactor `src/model.rs` into focused submodules while preserving the existing `crate::model::*` surface."
    notes: "Completed. `src/model.rs` is now a directory facade with focused submodules, stable reexports, and colocated tests protecting schemas, plan helpers, session views, and response types."
    inputs[1]: src/model.rs
    outputs[8]: src/model/mod.rs facade reexporting the stable public model API,"src/model/controller.rs for screen, phase, goal status, step status, and controller state types","src/model/plan.rs for task config, plan structs, and plan mutation helpers","src/model/session.rs for session enums, grouping, cursor, cached session-view, and selection helpers",src/model/usage.rs for usage and status snapshot types,"src/model/response.rs for planner, executor, and controller summary response types",src/model/schema.rs for JSON schema builders,Model tests moved beside their owning submodules
    dependencies[1]: guardrails
    verification[1]:
      - label: Model regression tests
        commands[6]: "cargo test -q model::controller::tests","cargo test -q model::plan::tests","cargo test -q model::session::tests","cargo test -q model::schema::tests","cargo test -q model::usage::tests","cargo test -q"
    cleanup_requirements[3]{label,description}:
      Thin facade,Leave `src/model/mod.rs` as a reexport surface rather than reintroducing large inline implementations there.
      Serde and schema parity,"Keep existing serde attributes, defaults, and JSON schema output unchanged while splitting the code."
      No stale aliases,"Remove transitional imports or compatibility types that only mirror the old single-file layout once the facade exports are wired."
    status: done
    attempts: 3
  - id: "process-modules"
    title: Split Process Execution And Parsing
    purpose: "Refactor `src/process.rs` into focused modules for codex execution, shell execution, usage snapshots, and event parsing."
    notes: "Completed. `src/process.rs` was replaced with focused modules and a stable facade. Public entry points remain unchanged, targeted parser and usage tests pass, and no new process-specific warnings were introduced."
    inputs[2]: src/process.rs,src/model/mod.rs
    outputs[6]: src/process/mod.rs facade preserving the current public functions,src/process/codex.rs for `run_codex_with_schema` and controller id generation,src/process/shell.rs for shell command execution and command summaries,src/process/usage.rs for usage snapshot helpers,src/process/parser.rs for codex JSON line parsing and rendering helpers,Process parsing tests kept with the parser and usage modules
    dependencies[2]: guardrails,"model-modules"
    verification[1]:
      - label: Process regression tests
        commands[3]: "cargo test -q process::parser::tests","cargo test -q process::usage::tests","cargo test -q"
    cleanup_requirements[3]{label,description}:
      Stable process API,"Preserve the current `crate::process::*` entry points so controller and app call sites stay unchanged."
      No parsing drift,"Keep command, tool, thinking, usage, and stderr event behavior identical after extraction."
      Cull moved dead code,Delete obsolete inline helpers in the old file instead of leaving duplicate parser or usage logic behind.
    status: done
    attempts: 1
  - id: "storage-toon-modules"
    title: Split TOON Persistence Helpers
    purpose: "Refactor `src/storage/toon.rs` into focused persistence, discovery, codec, and id helper modules without changing file formats."
    notes: "Completed. `src/storage/toon.rs` is now a focused directory module with stable facade exports, shared codec helpers, preserved cwd-sensitive discovery behavior, and passing targeted plus full test runs."
    inputs[2]: src/storage/toon.rs,src/model/mod.rs
    outputs[6]: src/storage/toon/mod.rs facade preserving the current storage API,src/storage/toon/files.rs for controller file creation and markdown read/write helpers,src/storage/toon/codec.rs for shared TOON read and write helpers,"src/storage/toon/controllers.rs for controller creation, listing, summaries, discovery, and timestamp helpers","src/storage/toon/ids.rs for normalization, uniqueness, fallback, and suffix helpers","Storage tests split between codec, discovery, and id modules"
    dependencies[2]: guardrails,"model-modules"
    verification[1]:
      - label: Storage regression tests
        commands[5]: "cargo test -q storage::toon::codec::tests","cargo test -q storage::toon::controllers::tests","cargo test -q storage::toon::ids::tests","cargo test -q storage::toon::tests","cargo test -q"
    cleanup_requirements[3]{label,description}:
      No format drift,"Keep persisted markdown and TOON content shape byte-compatible except for harmless formatting already produced by existing helpers."
      Single codec path,Route all TOON encoding and decoding through shared codec helpers instead of leaving duplicate inline file logic.
      "Preserve cwd-sensitive tests","Keep the existing cwd mutex and discovery test discipline intact so file-system behavior stays deterministic."
    status: done
    attempts: 1
  - id: "app-runtime-modules"
    title: Split App Runtime Lifecycle
    purpose: "Refactor `src/app/runtime.rs` into focused modules for workspace lifecycle, runtime events, and usage refresh while keeping `App` behavior stable."
    notes: "Completed. `src/app/runtime.rs` now routes through focused runtime modules with stable `impl App` entry points, expanded colocated tests, and a clean repository-wide verification pass after extraction."
    inputs[5]: src/app/runtime.rs,src/app/mod.rs,src/process/mod.rs,src/storage/toon/mod.rs,src/app/session.rs
    outputs[5]: src/app/runtime/mod.rs coordinating the runtime submodules,"src/app/runtime/workspace.rs for open, create, load, picker refresh, and shutdown flows",src/app/runtime/events.rs for draining and applying runtime events plus local session entry helpers,src/app/runtime/usage.rs for usage refresh and state persistence,"Expanded app tests covering event application, usage refresh, workspace open flows, and cached-session reconstruction"
    dependencies[4]: guardrails,"model-modules","process-modules","storage-toon-modules"
    verification[1]:
      - label: App runtime regression tests
        commands[5]: "cargo test -q app::runtime::events::tests","cargo test -q app::runtime::usage::tests","cargo test -q app::runtime::workspace::tests","cargo test -q app::tests","cargo test -q"
    cleanup_requirements[3]{label,description}:
      Stable App methods,Keep the current `impl App` method names and external call sites intact while moving their bodies into submodules.
      Single hydration path,Avoid duplicating workspace state initialization and usage snapshot reconstruction across runtime modules.
      "Contain runtime-only logic",Do not let runtime extraction leak storage or process implementation details into unrelated app modules.
    status: done
    attempts: 1
  - id: "app-workspace-input-modules"
    title: Split Workspace Input Handling
    purpose: "Refactor `src/app/workspace_input.rs` into focused keyboard, mouse, command, and submission modules while preserving interaction behavior."
    notes: "Next execution step. Runtime seams are now stable, so extract interaction logic by ownership boundary while keeping slash commands, planning-mode gating, drag selection, scroll behavior, follow-output resets, warning text, and submission side effects unchanged. Controller recovered this step from stale active state and returned it to todo."
    inputs[5]: src/app/workspace_input.rs,src/app/mod.rs,src/app/tests.rs,src/ui/mod.rs,src/app/runtime/mod.rs
    outputs[6]: src/app/workspace_input/mod.rs coordinating workspace input entry points,"src/app/workspace_input/mouse.rs for selection, drag, and wheel handling",src/app/workspace_input/keyboard.rs for key dispatch and navigation,src/app/workspace_input/commands.rs for slash command handling and planning mode gating,src/app/workspace_input/submission.rs for user message submission and local session entry creation,"Expanded colocated tests covering slash commands, selection, drag, scroll, follow-output reset behavior, and submission ordering"
    dependencies[2]: guardrails,"app-runtime-modules"
    verification[1]:
      - label: Workspace input regression tests
        commands[4]: "cargo test -q app::workspace_input::commands::tests","cargo test -q app::workspace_input::submission::tests","cargo test -q app::tests","cargo test -q"
    cleanup_requirements[3]{label,description}:
      Keep command strings stable,"Do not change existing slash commands, warning text, or planning-mode restrictions during the split."
      No duplicated reset logic,"Centralize selection and follow-output resets instead of copying the same workspace cleanup code into each input module."
      Preserve local entry creation,Keep local session entry generation and submission ordering identical so UI and persistence behavior do not drift.
    status: active
    attempts: 1
  - id: "ui-modules"
    title: Split UI Rendering Helpers
    purpose: Refactor `src/ui/mod.rs` into focused rendering modules while preserving the current exported helpers and TUI behavior.
    notes: "Start after workspace input extraction settles the app-facing seams. Keep `src/ui/mod.rs` as a thin facade, preserve wrapping and selection math exactly, and remove the dead `session_row_cells` helper or relocate its behavior into the owning session-rendering module so no dead-code warning survives."
    inputs[5]: src/ui/mod.rs,src/ui/scroll.rs,src/app/mod.rs,src/model/mod.rs,src/app/workspace_input/mod.rs
    outputs[9]: src/ui/mod.rs thin facade exporting the stable UI entry points,"src/ui/theme.rs for colors, shared styles, and shell block helpers","src/ui/layout.rs for `WorkspaceLayout`, `SessionView`, and layout calculations",src/ui/picker.rs for controller picker rendering,"src/ui/create_controller.rs for create-controller screen rendering",src/ui/workspace.rs for workspace screen orchestration,"src/ui/session.rs for session row rendering, wrapping, and selection extraction helpers","src/ui/sidebar.rs for plan board, status line, and composer helper rendering",UI tests updated to target the new owning modules without changing rendered behavior
    dependencies[4]: guardrails,"model-modules","app-runtime-modules","app-workspace-input-modules"
    verification[1]:
      - label: UI regression tests
        commands[4]: "cargo test -q ui::layout::tests","cargo test -q ui::session::tests","cargo test -q ui::tests","cargo test -q"
    cleanup_requirements[3]{label,description}:
      Thin facade,Keep `src/ui/mod.rs` limited to module wiring and stable reexports instead of leaving business logic there.
      Preserve selection math,"Keep wrapping, selection clipping, and copied session text behavior identical after extraction."
      Remove refactor leftovers,Delete dead rendering helpers and stale imports introduced or exposed by the module split.
    status: todo
    attempts: 0
  - id: "final-integration"
    title: Run Final Cleanup And Verification
    purpose: "Reconcile imports and module wiring, remove leftover compatibility code, and run the full repository quality gate."
    notes: "Final pass after the remaining app and UI splits. Clean wiring and refactor leftovers, confirm that stable APIs remain intact, and rerun the full required verification set after any final lint-driven cleanup that does not change behavior."
    inputs[7]: src/model/mod.rs,src/process/mod.rs,src/storage/toon/mod.rs,src/app/runtime/mod.rs,src/app/workspace_input/mod.rs,src/ui/mod.rs,Cargo.toml
    outputs[3]: Updated module declarations and imports across `src/`,"Removed dead helpers, stale imports, and compatibility shims left from the large-file split","Green formatting, test, and clippy verification for the refactor"
    dependencies[6]: "model-modules","process-modules","storage-toon-modules","app-runtime-modules","app-workspace-input-modules","ui-modules"
    verification[1]:
      - label: Full verification
        commands[3]: "cargo fmt --check","cargo test -q","cargo clippy -q --all-targets --all-features"
    cleanup_requirements[3]{label,description}:
      Remove leftovers,Delete obsolete inline helpers and transitional reexports once the new module structure is wired in cleanly.
      Keep structure intentional,"Do not leave empty modules or one-off directories after the refactor is complete."
      No warning regressions,"Do not introduce new dead-code or stale-import warnings as part of the refactor cleanup."
    status: todo
    attempts: 0