diff --git a/AGENTS.md b/AGENTS.md index de145ccb..99506d42 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,16 +15,19 @@ The motivating failure mode is that an agent can make many plausible local edits - Update `state/map.yaml` when project understanding changes. - Append evidence after meaningful research, implementation, verification, or rejected paths. -## Current Recommendation +## Current Status -Do not start with full protocol enum surgery. +The old preset-backed TUI experiment is no longer the active path. -Start by implementing a lightweight preset-backed Epiphany mode in the vendored Codex repo: +What is already landed in vendored Codex: -- add an `epiphany.md` collaboration-mode template -- add an `Epiphany` collaboration preset backed by `ModeKind::Default` -- patch the TUI to display the active preset name so the mode is visible to users -- only add `ModeKind::Epiphany` later if the preset-backed experiment proves useful +- Phase 1 durable Epiphany thread state +- Phase 2 prompt integration +- a minimal Phase 3 typed app-server/client read surface via `Thread.epiphanyState` + +Current next phase: + +- Phase 4 repo-local hybrid retrieval ## Important Paths @@ -51,6 +54,32 @@ rg -n "builtin_collaboration_mode_presets|fn plan_preset|fn default_preset" .\ve rg -n "collaboration_mode_label|collaboration_mode_indicator|set_collaboration_mask" .\vendor\codex\codex-rs\tui\src\chatwidget.rs ``` +## Session Bootstrap And Re-entry Protocol + +On fresh session load, do this before wandering off into implementation: + +1. read: + - `state/map.yaml` + - `notes/fresh-workspace-handoff.md` + - `notes/codex-epiphany-mode-plan.md` +2. run: + - `& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_state.py' status` +3. restate the current next action from the persisted state before starting edits + +After compaction, resume, or any suspicious loss of continuity: + +1. rerun `epiphany_state.py status` +2. reread `state/map.yaml` and `notes/fresh-workspace-handoff.md` +3. treat the persisted next action as authoritative unless fresh evidence in the repo contradicts it + +When context pressure is clearly rising: + +1. stop broad exploration +2. narrow the active move to a bounded landing zone +3. persist map/evidence/handoff updates before forced compaction hits + +Do not wait for the blackout and then act surprised. + ## Operating Discipline - Before substantial edits, restate the current mechanism and intended change. @@ -59,3 +88,4 @@ rg -n "collaboration_mode_label|collaboration_mode_indicator|set_collaboration_m - Revert or discard changes that do not clearly improve the target. - If the diff grows while understanding shrinks, stop implementation and switch to diagnosis. - Keep maps and prose together; do not replace useful maps with prose-only explanations. +- Before handoff, compaction, or phase boundaries, sync `state/map.yaml`, append `state/evidence.jsonl`, refresh `notes/fresh-workspace-handoff.md`, and make the next action explicit. diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 2e17dc43..527fc8a7 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -36,3 +36,4 @@ {"ts": "2026-04-24T00:39:29+01:00", "type": "implementation", "status": "ok", "note": "Implemented the Phase 3 typed client exposure slice in vendored Codex. Added a shared core helper to reconstruct the latest surviving EpiphanyThreadState from rollout items, exposed live thread epiphany_state through CodexThread, added optional Thread.epiphany_state in app-server protocol v2, hydrated thread/start, thread/resume, thread/fork, thread/read, thread/unarchive, and detached review-thread startup from live state or rollout, patched exhaustive Thread test fixtures, and documented the new field in app-server/README.md."} {"ts": "2026-04-24T00:39:29+01:00", "type": "verification", "status": "ok", "note": "Verified the Phase 3 slice with the Windows CARGO_TARGET_DIR workaround. cargo fmt --all passed; cargo test -p codex-core -p codex-app-server-protocol -p codex-app-server -p codex-analytics -p codex-exec -p codex-tui --lib --no-run passed; and targeted tests passed for codex-core latest_epiphany_state_from_rollout_items, codex-app-server load_epiphany_state_from_rollout_path_reads_latest_snapshot, and codex-app-server-protocol serialize_client_response."} {"ts": "2026-04-24T00:44:53+01:00", "type": "decision", "status": "ok", "note": "Patched the Epiphany spec and handoff workflow to make compaction pressure-aware instead of purely reactive. Added the rule that the harness should detect rising context pressure before the hard limit, checkpoint at the next safe point when pressure is high, and persist immediately when pressure is critical rather than waiting for forced compaction to erase live reasoning."} +{"ts": "2026-04-24T00:47:37+01:00", "type": "decision", "status": "ok", "note": "Updated the repo-local AGENTS.md to carry the operational bootstrap and re-entry protocol explicitly. Fresh sessions and post-compaction resumes should reread the persisted state files, run tools/epiphany_state.py status immediately, restate the persisted next action before edits, and treat rising context pressure as a cue to checkpoint before forced compaction."} diff --git a/state/map.yaml b/state/map.yaml index 593869d2..e27feca9 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -77,6 +77,7 @@ accepted_design: - Phase 3 read-surface slice is landed: app-server protocol Thread payloads now carry optional typed epiphany_state hydrated from live CodexThread state when available and otherwise reconstructed from rollout with rollback/compaction semantics; dedicated Epiphany update RPCs and live notifications remain deferred - Epiphany should be an opinionated software development agent: pre-compaction and pre-handoff persistence of map, evidence, and next action are part of the workflow, not optional operator folklore - compaction handling should be pressure-aware rather than reactive: when context pressure rises, Epiphany should narrow the active move and persist checkpoints before forced compaction actually hits + - repo-local AGENTS instructions should carry the session bootstrap and re-entry protocol explicitly, including running epiphany_state.py status on fresh load and after compaction rejected_paths: - name: pinned_map_only