NEO Housekeeping Plan — Post-Orion-Audit¶
Katja-approved plan for a full housekeeping pass across repo, workspace, and docs. Nothing here executes until Orion delivers the session closure fix and next session runs clean.
Block 1 — Repo: Dead Files and Orphaned Artifacts¶
These files exist in the repo but serve no active purpose. They create confusion and should be removed.
1A — Dead source files (delete)¶
| File | Reason |
|---|---|
neo_engine/main_loop_Old.py |
Superseded by main_loop.py. Never imported. |
neo_engine/strategy_engine_old.py |
Superseded by strategy_engine.py. Never imported. |
tests/test_main_loop_old.py |
Tests the old file. Remove with it. |
tests/test_task4.py |
Task-numbered test — no matching module or purpose in current architecture. |
tests/test_task5.py |
Same as above. |
Owner: Orion (bundle into a cleanup branch). Katja reviews diff before merge.
1B — Dead run scripts (evaluate)¶
run_scenario_1.py through run_scenario_4.py in repo root — review and confirm whether any are still referenced. If not, delete.
Owner: Vesper reviews, Orion deletes.
1C — Orphaned WAL/SHM files (delete from repo root)¶
The repo root has dozens of .db-shm and .db-wal files for paper DBs that no longer exist. These are SQLite WAL artifacts — zero data, just filesystem noise. Confirm they're in .gitignore (they should be) and delete from working directory.
Owner: Katja deletes from Windows Explorer or VS Code terminal. No git involvement needed — these aren't tracked.
Block 2 — Repo: Markdown Cleanup¶
2A — NEO_Roadmap.md (major rewrite needed)¶
Location: docs/NEO_Roadmap.md
Last updated: 2026-04-10 — 8 days out of date.
Specific problems:
- "Current Status" section describes Phase 4C as active. We are now in Phase 7.
- Phase 3D listed as "Active" — completed months ago.
- Phase 5 (Monitoring & Dashboards) listed as future — the dashboard is live.
- Phase 7 (Market Microstructure Research) described as a future research task — this is our current active phase.
- Agent Desk (Phase 9) references Manus, Codex, ChatGPT/Claude model descriptions that are stale. Current team: Atlas (ChatGPT), Vesper (Claude Sonnet), Orion (Claude Opus).
- Appendix C (Collaboration Model) — outdated agent roles and run standard. References
run_paper_session.py --fresh-dbas the run standard; this is now the live config. - Appendix A readiness checklist — almost all items listed as "Next" are now done.
Action: Vesper rewrites the roadmap to reflect current state. Atlas should sign off on the "where we are / where we're going" framing before final commit.
2B — AGENTS.md (stale constraints)¶
Location: AGENTS.md
Problems:
- "Current development phase: Phase 1 targets only" — still says Phase 1.
- "Do not modify yet: strategy_engine.py, execution_engine.py, xrpl_gateway.py" — all of these have been modified extensively.
- Phase 1 targets list (models.py, config.py, state_manager.py) is no longer a constraint.
Action: Rewrite to reflect current development model (multi-agent, change-control via Vesper/Orion, Katja as captain). Keep the architecture rules section — those are still valid.
2C — AGENT_CHANGE_CONTROL.md (incomplete)¶
Location: AGENT_CHANGE_CONTROL.md
Only has 2 entries (FLAG-012 and atomic replacement). Dozens of changes have been made since without entries. Either: - Backfill with key changes (FLAGS 025–034 implementations), or - Acknowledge it's incomplete and start fresh from the current state, noting it was not maintained consistently
Action: Vesper proposes approach to Katja. Light option: add a note that entries prior to Apr 14 were not logged, and log going forward.
Block 3 — Workspace: Open Flags Cleanup¶
Location: [C] Open Flags.md
Most flags in the file are already resolved. The file needs a resolved → archived pass.
Flags to move to "Resolved Archive" section¶
| Flag | Status |
|---|---|
| FLAG-027 | RESOLVED ✅ |
| FLAG-028 | RESOLVED ✅ |
| FLAG-030 | RESOLVED ✅ |
| FLAG-031 | RESOLVED ✅ |
| FLAG-032 | RESOLVED ✅ |
| FLAG-033 | RESOLVED ✅ |
| FLAG-034 | RESOLVED ✅ |
Flags still active / pending¶
| Flag | Status |
|---|---|
| FLAG-016 | Test suite broken — still open |
| FLAG-029 | Async shutdown warning — still open |
| FLAG-new | Session closure (ended_at never written) — Orion audit in flight |
| FLAG-new | DB corruption on terminal close — Orion audit in flight |
Action: Vesper restructures the file. Resolved flags collapsed to a summary table at the bottom. Active flags at top with current status.
Block 4 — Workspace: CLAUDE.md Update¶
CLAUDE.md needs a pass to reflect where we actually are after today's events:
- S38 closed (Phase 7.2 — reference layer confirmed working, offset calibration needed)
- Session closure bug discovered (Orion audit in flight)
- DB restored from backup
- Phase 7.3 is next (offset calibration) — once session closure is fixed
- Folder structure section needs today's new files added
Action: Vesper updates CLAUDE.md after Orion delivers.
Block 5 — Progress Widget Cleanup¶
The task list visible in the Cowork sidebar is showing stale tasks from weeks ago (items 6–10 visible in Katja's screenshot). These are all complete.
Action: Vesper clears the stale tasks from the progress tracker now (not blocked on Orion).
Block 6 — Engine Code Audit (deeper pass, Orion)¶
After the session closure fix is merged, Orion should do a focused code health audit on the following known concerns before Phase 7.3 begins:
6A — Shutdown sequence ordering¶
The shutdown sequence in _shutdown() has every step wrapped in try/except with log.debug. Any of these could fail silently. After fixing session closure, audit all log.debug calls in the shutdown path and upgrade to log.error where failure should not be silent.
6B — FLAG-016 — test suite¶
Test suite has been broken for a while. Orion should audit which tests are failing, why, and whether they test real behavior or dead code. Fix or remove.
6C — FLAG-029 — async shutdown warning¶
Async shutdown warning has been deferred. Confirm whether it's cosmetic or has failure implications now that we've seen real shutdown corruption.
6D — WAL checkpoint cadence¶
The DB corruption is partly a WAL checkpoint timing issue. Evaluate whether periodic PRAGMA wal_checkpoint(PASSIVE) during session run would reduce the exposure window for terminal-close corruption.
6E — neo_live_session1.db-shm / .db-wal files in repo root¶
Separate from the paper session WAL files — these are live session artifacts. Confirm they're in .gitignore and not being tracked.
Execution Order¶
| Step | What | Owner | Blocked on |
|---|---|---|---|
| 0 | Orion: session closure fix + DB hardening | Orion | Nothing — in flight |
| 1 | Clear stale progress tasks | Vesper | Nothing |
| 2 | Open Flags cleanup (resolved → archive) | Vesper | Nothing |
| 3 | Roadmap rewrite (draft) | Vesper | Nothing |
| 4 | AGENTS.md rewrite | Vesper | Nothing |
| 5 | AGENT_CHANGE_CONTROL.md — propose approach to Katja | Vesper | Nothing |
| 6 | Dead files removal (repo) — branch | Orion | Orion audit delivery |
| 7 | Run script audit (repo) | Vesper + Katja review | Step 6 |
| 8 | WAL/SHM orphan cleanup (repo root) | Katja | Nothing |
| 9 | CLAUDE.md update | Vesper | Orion audit delivery |
| 10 | Roadmap Atlas sign-off | Atlas | Step 3 draft |
| 11 | Engine code audit (6A–6E) | Orion | Step 0 |
Steps 1–5 and 8 can start immediately. Steps 6, 9, 11 wait for Orion.
— Vesper