diff --git a/notes/epiphany-architectural-teardown.md b/notes/epiphany-architectural-teardown.md new file mode 100644 index 00000000..ab4dd430 --- /dev/null +++ b/notes/epiphany-architectural-teardown.md @@ -0,0 +1,334 @@ +# Epiphany Architectural Teardown + +This note records the May 2026 suspicion pass over Epiphany's live architecture. +It is not a product plan and not a victory lap. It is the red tag on the +machine: stop piling outward features on a control plane whose ownership has +started to sag. + +The core thesis remains sound: Epiphany needs durable typed state, explicit +maps, reviewable evidence, bounded worker output, compaction-safe re-entry, and +native Rust/CultCache/CultNet contracts. The unstable part is the current +Codex app-server Epiphany control plane. It works, but it works by concentrating +too much policy, projection, lifecycle glue, and coordinator sequencing in the +host seam. + +## Plain-Language Map + +### Core Inputs + +- user turns and operator API calls +- repository files and watcher snapshots +- rollout history and latest token telemetry +- retrieval/index manifests and Qdrant/BM25 search results +- specialist job launch requests and runtime-spine job results +- heartbeat state, role memory stores, and reviewable self patches +- local persistent project doctrine in `state/map.yaml`, handoff notes, and + ledgers + +### Durable State Stores + +- `EpiphanyThreadState` in Codex protocol/session/rollout state +- native runtime-spine documents in `state/runtime-spine.msgpack` +- heartbeat physiology in `state/agent-heartbeats.msgpack` +- role dossiers in `state/agents.msgpack` +- distilled project memory in `state/map.yaml`, `state/ledgers.msgpack`, and + handoff notes +- retrieval manifests and optional Qdrant collections outside the thread state + +### Core Transformations + +- prompt projection from durable state into `` +- revision-gated state mutation through `thread/epiphany/update` and accepted + promote/role/reorient gates +- retrieval, distillation, proposal, and promotion policy in `epiphany-core` +- app-server projection of state into scene/jobs/roles/freshness/context/ + graph/planning/pressure/reorient/CRRC/coordinator views +- app-server launch/read-back/acceptance over heartbeat-backed runtime-spine + jobs +- heartbeat and character-loop packet generation over role dossiers + +### Core Outputs + +- model-visible Epiphany state and specialist prompts +- client-visible `thread.epiphanyState` +- operator responses for scene, jobs, roles, freshness, context, graphQuery, + planning, pressure, reorient, CRRC, coordinator, roleResult, and + reorientResult +- `thread/epiphany/stateUpdated` notifications +- runtime-spine job/result/event receipts +- heartbeat/routine artifacts and Face/character-loop packets + +### Stage Ownership + +- Codex protocol currently owns the thread-state shape and app-server protocol + types. +- Codex core owns session storage, rollout persistence, prompt injection, and + the state mutation bridge. +- `epiphany-core` owns retrieval, distillation, proposal, promotion, + runtime-spine, heartbeat, role memory, bridge CLIs, and smoke binaries. +- Codex app-server currently owns most operator projection, fixed-lane + coordinator policy, CRRC recommendation policy, role launch packet assembly, + role/reorient result interpretation, and action availability. + +That last bullet is the rot. The host seam has become an organ. + +## Required Invariants + +- There must be one source of truth for project understanding. +- Derived projections must not become policy authorities. +- Runtime job lifecycle must have one owner. +- Review/acceptance identity must be keyed by stable typed ids, not matching + summaries. +- Public operator surfaces must not expose sealed worker/raw-result payloads by + default. +- App-server must route and adapt; it must not be the Epiphany brain. +- Experimental cognition blobs must not masquerade as stable typed doctrine. +- Read-only surfaces must be views over state, not a multiplying API religion. + +## Architectural Smells + +### 1. App-Server As Hidden Epiphany Brain + +Current mechanism: `vendor/codex/codex-rs/app-server/src/codex_message_processor.rs` +contains the Epiphany endpoint handlers plus a large cluster of +`map_epiphany_*`, `build_epiphany_*`, `load_epiphany_*`, coordinator, CRRC, role +status, and result interpretation helpers. + +Real need: expose operator surfaces through the existing Codex app-server. + +What breaks if deleted: Aquarium/status/coordinator endpoints, fixed role +launch/read-back, CRRC recommendations, and many tests. + +What that proves: the behavior is needed, but its current owner is wrong. The +host seam has absorbed domain policy. + +Simpler architecture: move Epiphany surface derivation and coordinator policy +into `epiphany-core` modules. App-server should parse params, load thread/runtime +inputs, call a domain function, and serialize the response. + +Files to change: + +- `vendor/codex/codex-rs/app-server/src/codex_message_processor.rs` +- `vendor/codex/codex-rs/app-server-protocol/src/protocol/v2.rs` +- new `epiphany-core/src/surfaces/*` +- focused app-server tests moved or narrowed after extraction + +### 2. Duplicated Job Authority + +Current mechanism: `EpiphanyThreadState.job_bindings` stores launcher id, +authority scope, backend kind, and backend job id, while runtime-spine stores +the native job/result lifecycle. App-server overlays bindings onto derived jobs. + +Real need: connect thread state and launched specialist/reorient work. + +What breaks if deleted: roleResult/reorientResult cannot locate runtime jobs. + +What that proves: the link is needed, but lifecycle ownership is duplicated. +Thread state should not mirror runtime job state. + +Simpler architecture: runtime-spine is authoritative for jobs/results. Thread +state stores typed intent/link records only when project understanding needs +the association. + +Files to change: + +- `vendor/codex/codex-rs/protocol/src/protocol.rs` +- `vendor/codex/codex-rs/core/src/codex_thread.rs` +- `epiphany-core/src/runtime_spine.rs` +- app-server role/reorient result handlers and job projection code + +### 3. Projection Endpoint Proliferation + +Current mechanism: scene, jobs, roles, freshness, context, graphQuery, +planning, pressure, reorient, CRRC, and coordinator each have their own endpoint, +response type, mapper, status enums, and tests. + +Real need: clients need compact operator lenses. + +What breaks if deleted: the GUI loses convenient panes and existing API clients +break. + +What that proves: views are needed, not that every lens deserves a first-class +protocol throne. + +Simpler architecture: create a smaller `thread/epiphany/view` contract with +selectable typed lenses plus separate mutation intents. Promote only genuinely +independent commands to separate endpoints. + +Files to change: + +- `vendor/codex/codex-rs/app-server-protocol/src/protocol/v2.rs` +- `vendor/codex/codex-rs/app-server-protocol/src/protocol/common.rs` +- `vendor/codex/codex-rs/app-server/src/codex_message_processor.rs` +- Aquarium/status consumers + +### 4. Stringly Accepted-Result Identity + +Current mechanism: accepted role/reorient findings are detected by evidence +kind/status/summary matching. + +Real need: prevent repeat acceptance and know which finding is already banked. + +What breaks if deleted: repeat-acceptance bugs return. + +What that proves: acceptance needs a stable receipt, not summary matching. + +Simpler architecture: add typed acceptance receipts keyed by runtime +`job_result` id and role/reorient binding identity. Evidence can summarize the +accepted result, but it must not be the identity system. + +Files to change: + +- `vendor/codex/codex-rs/protocol/src/protocol.rs` +- `epiphany-core/src/runtime_spine.rs` +- app-server role/reorient accept/result mapping +- schema catalog documents + +### 5. Raw Worker Output In Public Finding Contracts + +Current mechanism: `ThreadEpiphanyRoleFinding` includes `raw_result: +serde_json::Value` and `self_patch: unknown`. + +Real need: debug malformed worker output and preserve optional self-memory +requests. + +What breaks if deleted: convenient forensic inspection and loosely typed +self-patch handling. + +What that proves: public API is leaking internal accident. Sealed worker output +should not be normal operator surface material. + +Simpler architecture: public findings expose typed projection only. Raw output +stays in artifacts and is opened only by explicit forensic/debug flow. +`selfPatch` should be a typed contract or absent. + +Files to change: + +- `vendor/codex/codex-rs/app-server-protocol/src/protocol/v2.rs` +- app-server finding mappers +- Aquarium result display +- `epiphany-core/src/agent_memory.rs` if selfPatch becomes fully typed + +### 6. Heartbeat/Cognition Blob State + +Current mechanism: heartbeat state has typed participants and scheduler fields, +then stores sleep cycle, memory resonance, incubation, thought lanes, bridge, +appraisals, reactions, and extra data as generic JSON values. + +Real need: prototype Void/Ghostlight-derived routine physiology without freezing +premature schemas. + +What breaks if deleted: Aquarium/status cannot inspect the rich cognition +routine; routine receipts lose stateful continuity. + +What that proves: useful scaffolding, not stable foundation. JSON-shaped +cognition blobs inside CultCache are still blobs. + +Simpler architecture: split stable heartbeat scheduling from experimental +cognition receipts. Type only the fields policy consumes; keep exploratory +thought-weather as receipts/artifacts until its contract hardens. + +Files to change: + +- `epiphany-core/src/heartbeat_state.rs` +- `epiphany-core/src/bin/epiphany-heartbeat-store.rs` +- `schemas/cultnet/*` +- Aquarium heartbeat/routine consumers + +### 7. Generic Backend Plumbing With One Backend + +Current mechanism: `EpiphanyJobBackendKind` exists but only has `Heartbeat`. + +Real need: name the current backend and leave a future escape hatch. + +What breaks if deleted: response shape and mapper tests churn. + +What that proves: one-backend polymorphism is just-in-case architecture. + +Simpler architecture: store `runtime_job_id` / `activation_job_id` directly +until a second backend exists. + +Files to change: + +- `vendor/codex/codex-rs/protocol/src/protocol.rs` +- `vendor/codex/codex-rs/app-server-protocol/src/protocol/v2.rs` +- job launch/result mappers and tests + +### 8. Tests Freeze Implementation Shape + +Current mechanism: many app-server tests assert exact mapper/coordinator shapes +inside the same giant file that implements the policy. + +Real need: prevent regressions in coordination and operator views. + +What breaks if deleted: easy behavior regressions. + +What that proves: tests are needed, but they currently bless the app-server as +policy owner. + +Simpler architecture: move policy tests to `epiphany-core`. App-server tests +should assert routing, serde, error handling, and adapter fidelity. + +Files to change: + +- `vendor/codex/codex-rs/app-server/src/codex_message_processor.rs` +- new `epiphany-core` policy test modules +- app-server protocol fixture tests + +## Ranked Teardown Plan + +### Keep + +- durable typed `EpiphanyThreadState` +- prompt projection from typed state +- revision-gated update/promote/accept writes +- retrieval, distillation, proposal, promotion policy in `epiphany-core` +- native runtime-spine as the future job/result authority +- explicit review gates for semantic findings +- Aquarium as reflection/control surface, not source of truth + +### Cut + +- public `raw_result` exposure from normal role/reorient findings +- one-backend generic `BackendKind` plumbing until another backend exists +- placeholder `specialist-work` job whose purpose is preventing clients from + inventing scheduler state +- any new feature surface that adds another app-server-owned policy mapper + +### Collapse + +- collapse scene/jobs/roles/freshness/context/planning/pressure/reorient/CRRC/ + coordinator into fewer selectable view lenses +- collapse `jobBindings` lifecycle mirror into runtime-spine-owned job lifecycle + plus typed thread-state links +- collapse summary-string acceptance identity into typed acceptance receipts + +### Split + +- split app-server routing from Epiphany domain policy +- split stable heartbeat scheduling from experimental cognition receipts +- split public operator findings from forensic raw worker artifacts +- split protocol surface contracts from local app-server mapper convenience + +### Rebuild + +Rebuild the Epiphany app-server control plane. Not patch. The current surface +works, but it concentrates policy, projection, lifecycle, prompt packet +assembly, coordinator sequencing, and tests in a vendored host file. That is +architectural Jenga with a good demo standing in front of it. + +The next phase is not more outward bridge/UI/Face work. The next phase is +control-plane purification: + +1. extract Epiphany view/coordinator policy into `epiphany-core` +2. make runtime-spine the sole job/result lifecycle authority +3. replace summary-matching acceptance with typed receipts +4. reduce API surface proliferation into intentional view lenses and mutation + intents +5. remove public raw-result leakage from normal operator contracts +6. type or quarantine heartbeat cognition blobs +7. only then resume outward feature work + +This is now top priority because Epiphany is the foundation everything else is +supposed to stand on. You do not get a Perfect Machine by adding another patch +layer and calling the shadow a subsystem. diff --git a/notes/epiphany-fork-implementation-plan.md b/notes/epiphany-fork-implementation-plan.md index 84b13cfb..36c80163 100644 --- a/notes/epiphany-fork-implementation-plan.md +++ b/notes/epiphany-fork-implementation-plan.md @@ -94,11 +94,14 @@ The landed machine now has: - live Phase 6 MVP status smoke coverage through native `epiphany-mvp-status-smoke` The current phase is Phase 6: reflection boundary and observable harness state. -The next phase direction is native-spine extraction: Codex app-server is a -temporary evacuation bridge, not the throne. Epiphany sessions, jobs, results, -events, heartbeats, role memory, and coordinator state move into CultCache-backed -domain documents spoken over CultNet, and new runtime contracts land native -first. +The immediate next phase is foundation cleanup, recorded in +`notes/epiphany-architectural-teardown.md`. The May 2026 suspicion pass found +that the app-server Epiphany control plane has become architectural Jenga: +policy, projection, lifecycle glue, prompt packet assembly, coordinator +sequencing, and tests are concentrated in the Codex host seam. Native-spine +extraction remains the direction, but the first duty is to rebuild/extract the +control plane so Codex app-server becomes an adapter again instead of the +machine's extra brain. ## Boundary Rules @@ -167,8 +170,24 @@ The plan should get shorter after a phase completes, not longer by default. The next unknown is not whether Epiphany can preserve, read, propose, promote, and notify typed state. It can. +The active priority is now the teardown plan in +`notes/epiphany-architectural-teardown.md`. Do not add outward feature surfaces +until there is a source-grounded cleanup slice for the control-plane ownership +problem. + The next unknowns are: +- how to extract Epiphany view/coordinator policy from + `vendor/codex/codex-rs/app-server/src/codex_message_processor.rs` into + `epiphany-core` without breaking the existing operator contracts +- how to make runtime-spine the sole job/result lifecycle authority while + reducing `EpiphanyThreadState.job_bindings` to typed links or intents +- how to replace summary-string accepted-result matching with typed acceptance + receipts keyed by runtime result identity +- how to collapse endpoint proliferation into intentional view lenses and + mutation intents without hiding authority from Aquarium or the operator +- how to remove public `raw_result` leakage from normal role/reorient findings + while preserving explicit forensic debugging - what bridge surface is sufficient for the next Aetheria run: named Unity operations, Aetheria-side editor probes, GUI environment status, Rider context capture, and a Rider plugin MVP - how much controlled runtime/editor access the richer Unity bridge gives implementation and verification lanes before deeper engine probes need another slice - how the landed watcher-backed invalidation telemetry should be consumed without turning freshness into a secret worker @@ -303,19 +322,26 @@ work remains non-authoritative until the human explicitly adopts an objective. ## Phase 6 Direction -Phase 6 should grow observable harness state outward from the typed spine. +Phase 6 must stop growing observable harness state outward until the control +plane is purified. The live surfaces are guardrails and evidence, not +permission to keep stacking protocols on the host seam. -Useful candidates: +Cleanup candidates: -1. Treat the first three-pronged Rider/Epiphany GUI/Unity workflow as landed enough for local bridge testing: Aetheria-side resident Unity editor package, named Unity bridge operations over that package, GUI Environment panel, EpiphanyGraph-backed GUI graph dashboard, Rider context bridge CLI, and a Rider plugin MVP source scaffold now exist. -2. Before the next Aetheria dogfood run, build-verify or package the Rider plugin scaffold when Gradle/wrapper support is available and install the Aetheria-pinned Unity `6000.1.10f1` editor; do not rediscover that Epiphany cannot prove runtime/editor assumptions from source inspection alone. -3. Keep dogfood execution agent-run and auditable through the fixed-lane coordinator and GUI/operator view over the same status/artifact surfaces once the bridges exist. -4. Keep accepted worker findings review-gated; do not convert acceptance into automatic promotion of arbitrary worker output. -5. Keep pre-compaction intervention narrow: steer once at `shouldPrepareCompaction`, latch the compact handoff only after successful steering, then let explicit checkpointing, compact/resume/reorient, and review gates do their jobs. +1. Move Epiphany surface derivation and fixed-lane coordinator policy out of + `codex_message_processor.rs` and into `epiphany-core`. +2. Make runtime-spine the single lifecycle authority for launched jobs and + results; thread state may link to jobs but must not mirror the job table. +3. Replace accepted-result summary matching with typed acceptance receipts. +4. Reduce the scene/jobs/roles/freshness/context/planning/pressure/reorient/ + CRRC/coordinator sprawl into fewer deliberate lenses and mutation intents. +5. Remove normal public raw-result exposure from role/reorient finding + contracts; keep forensic raw payloads explicit and sealed. +6. Split stable heartbeat scheduling from experimental cognition receipt blobs. -Do not spend Phase 6 polishing Phase 5 out of anxiety. The Phase 5 smoke harness -is a regression guardrail, not a ritual drum circle for summoning more tiny -hardening slices. +Do not spend Phase 6 adding another convenience surface because the current ones +work. Passing smokes prove behavior, not architecture. The Perfect Machine gets +fewer thrones, not a new one for every button. ## Aquarium Operator Plan diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index 6e9da7b8..77010f80 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -18,6 +18,7 @@ cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-state -- sta Get-Content '.\state\map.yaml' Get-Content '.\notes\fresh-workspace-handoff.md' Get-Content '.\notes\epiphany-current-algorithmic-map.md' +Get-Content '.\notes\epiphany-architectural-teardown.md' Get-Content '.\notes\epiphany-fork-implementation-plan.md' git status --short --branch git log --oneline -5 @@ -30,6 +31,8 @@ remembers doctrine; the branch remembers the blade. ## Current Orientation - Do not copy exact branch or HEAD from this note. Run `git status --short --branch` and `git log --oneline -5`. +- Top priority is now foundation cleanup, not outward feature work. Read `notes/epiphany-architectural-teardown.md` before touching Epiphany control-plane code. The May 2026 suspicion pass found that the app-server Epiphany control plane has become architectural Jenga: too much policy, projection, lifecycle glue, prompt packet assembly, coordinator sequencing, and test authority lives in `vendor/codex/codex-rs/app-server/src/codex_message_processor.rs`. +- Do not continue Aquarium UI, bridge, Face, or dogfood expansion until the teardown has a source-grounded cleanup slice plan. Epiphany is the foundation; patches on patches are not a purification rite, they are how the altar becomes load-bearing garbage. - Phase 1 through Phase 5 are complete enough. - Phase 6 has read-only `thread/epiphany/scene`, `thread/epiphany/jobs`, `thread/epiphany/roles`, `thread/epiphany/freshness`, `thread/epiphany/context`, `thread/epiphany/graphQuery`, `thread/epiphany/planning`, `thread/epiphany/pressure`, `thread/epiphany/reorient`, `thread/epiphany/crrc`, `thread/epiphany/coordinator`, `thread/epiphany/reorientResult`, and `thread/epiphany/roleResult`; durable `jobBindings` now act as a thin Epiphany-owned launcher seam with launcher id, authority scope, and heartbeat backend/job id. New `thread/epiphany/jobLaunch`, `thread/epiphany/jobInterrupt`, `thread/epiphany/roleLaunch`, and `thread/epiphany/reorientLaunch` writes open typed runtime-spine job receipts under `state/runtime-spine.msgpack` and do not require the Codex SQLite state runtime. Freshness carries watcher-backed invalidation inputs, graphQuery traverses authoritative typed graph neighborhoods and path/symbol matches without mutation, planning projects typed captures/backlog/roadmap/objective drafts without adopting work, roles project implementation/imagination/modeling/verification/reorientation ownership from existing signals without becoming a scheduler, `roleResult` and `reorientResult` read heartbeat-backed typed runtime-spine job results when present, `roleAccept` and `reorientAccept` accept completed heartbeat findings from typed runtime-spine results while remaining explicit review gates, `thread/epiphany/crrc` recommends the next explicit CRRC action without launching, accepting, compacting, scheduling, or mutating, and `thread/epiphany/coordinator` composes those signals into a fixed-lane MVP action recommendation without becoming a writer. - Native `epiphany-mvp-status` is the first dogfood operator view. It starts or reads a thread through app-server and prints scene, planning, pressure, reorient, jobs, roles, Imagination/modeling/verification role result read-backs, reorient result, heartbeat, Face bubbles, and CRRC recommendation as text or machine output. The old Python status module has been cut; native Rust/CultCache/CultNet surfaces are the smoked product path. @@ -347,6 +350,7 @@ Rules now in force: - `epiphany-prepare-compaction` is the native pre-compaction persistence check; run it before and after imminent-compaction persistence passes. - this handoff is a compact re-entry packet. - `notes/epiphany-fork-implementation-plan.md` is the distilled forward plan. +- `notes/epiphany-architectural-teardown.md` is the active foundation-cleanup directive until the app-server control-plane ownership problems are resolved. - `notes/epiphany-rider-unity-integration-plan.md` is the detailed Rider-as-IDE and Unity-as-editor/runtime integration plan. - The stable live surface contract now lives in `state/map.yaml` plus `notes/epiphany-current-algorithmic-map.md`; the stale harness-surface duplicate was cut. - `notes/epiphany-current-algorithmic-map.md` is the source-grounded control-flow map. @@ -363,6 +367,17 @@ that change what the next agent should believe. Do not continue implementation automatically from a rehydrate-only request. +The next real move is foundation cleanup. Start from +`notes/epiphany-architectural-teardown.md`, not from the older outward Phase 6 +bridge/UI trail. The first cleanup slice should be source-grounded and should +target the control-plane ownership problem: extract Epiphany view/coordinator +policy from the vendored app-server host seam into `epiphany-core`, make +runtime-spine the sole job/result lifecycle authority, replace summary-string +acceptance matching with typed receipts, collapse endpoint proliferation into +intentional lenses/mutation intents, remove normal public `raw_result` leakage, +and split stable heartbeat scheduling from experimental cognition receipts. +No Agile confetti. No new balcony on the swaying tower. + The Phase 6 freshness slice is landed. It exposes read-only `thread/epiphany/freshness` from live retrieval summaries plus graph frontier/churn state and, for loaded threads, watcher-backed invalidation @@ -504,7 +519,8 @@ Live `thread/epiphany/scene`, `thread/epiphany/jobs`, `thread/epiphany/roles`, `thread/epiphany/reorient`, `thread/epiphany/crrc`, `thread/epiphany/coordinator`, native `epiphany-mvp-status`, native `epiphany-mvp-coordinator`, and native `epiphany-phase6-graph-query-smoke` / native `epiphany-phase6-planning-smoke` -smokes are now guardrails, not the next organs. +smokes are now guardrails, not the next organs. The architectural teardown says +the next organ is control-plane purification. ## Not Yet @@ -518,8 +534,7 @@ smokes are now guardrails, not the next organs. - broad event stream beyond the landed state update notification - typed repetitive-work queues plus final-answer gates, so batch/tile/import/migration work cannot end merely because the pattern was demonstrated or the partial result sounds tidy -The machine is good enough to move outward. Do not sand the same edge until the -wood disappears. +The machine is no longer cleared to move outward. Fix the foundation first. ## Immediate Re-entry Instruction diff --git a/state/ledgers.msgpack b/state/ledgers.msgpack index 76338071..93ee12c6 100644 Binary files a/state/ledgers.msgpack and b/state/ledgers.msgpack differ diff --git a/state/map.yaml b/state/map.yaml index 4b7252aa..e057386e 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -15,10 +15,12 @@ objective: machinery they touch. The agent must know the machine before it cuts the machine. current: > - Keep EpiphanyAgent focused on harness organs, typed-state reliquaries, - coordinator rites, bridge tools, and backend surfaces while the Aquarium - operator shrine lives in its own sibling repo with its own persistent - interface memory and doctrine. + Stop outward feature work until the architectural teardown in + `notes/epiphany-architectural-teardown.md` is acted on. Epiphany is the + foundation for everything else; the current app-server control plane has + absorbed too much policy, projection, lifecycle glue, and coordinator + sequencing. The next work is foundation cleanup, not another bridge, + Aquarium pane, Face surface, or convenience layer. constraints: - No frontier-scale training tithe. @@ -63,6 +65,7 @@ data_flow: - move historical proof to git, commits, smoke artifacts, or distilled evidence rather than plan prose active_subgoals: + - Top priority: execute the teardown plan in `notes/epiphany-architectural-teardown.md`; rebuild/extract the Epiphany app-server control plane before adding outward features. Move Epiphany view/coordinator policy into `epiphany-core`, make runtime-spine the sole job/result lifecycle authority, replace summary-string acceptance identity with typed receipts, reduce API surface proliferation, remove normal public raw-result leakage, and type or quarantine heartbeat cognition blobs. - Treat Phase 5 update/distill/propose/promote/read/notification as complete enough unless a concrete regression appears. - Preserve read-only boundaries for retrieve, distill, propose, scene, jobs, roles, roleResult, freshness, context, graphQuery, planning, pressure, reorient, crrc, coordinator, and reorientResult. - Keep the landed Phase 6 coordinator, limited safe-boundary CRRC automation, and pre-compaction checkpoint intervention ready for the next bridge-equipped dogfood run. @@ -84,6 +87,7 @@ active_subgoals: - Keep repo trajectory initialization birth-only and review-gated: startup may distill historical direction, self-image, implicit goals, and anti-goals into role-local pressure, but it must not auto-adopt work or keep repainting a living repo with its first silhouette. accepted_design: + - `notes/epiphany-architectural-teardown.md` is the current foundation-cleanup directive. Its suspicion pass supersedes outward Phase 6 expansion as the active priority until the control-plane ownership problems are resolved. - Epiphany is a fork-level modeling architecture, not merely a Codex collaboration mode. - Authoritative Epiphany state lives in Codex protocol/core session and rollout state. - The prompt reads typed state through a bounded `` developer fragment. @@ -264,5 +268,5 @@ rejected_paths: reason: persistent state that accumulates every local truth becomes memory cruft and weakens rehydration current_status: - summary: Phase 1 durable state through Phase 6 coordinator/specialist/CRRC/backend organs are landed. The Aquarium operator shrine has been split into sibling repo `E:\Projects\EpiphanyAquarium` with its own distilled interface doctrine and persistent memory. EpiphanyAgent now also has a Ghostlight-derived heartbeat initiative seam, Epiphany-native character-loop packets over its own role dossiers, VoidBot-derived native routine physiology and cognition lanes in the heartbeat store, a Face lane for public agent thought-weather, and a Discord-independent Face bubble API for Aquarium. Runtime Unity execution remains blocked until the exact project-pinned editor exists. - next_action: Continue Aquarium UI work in `E:\Projects\EpiphanyAquarium`; configure the #aquarium channel id before allowing Face to post; wire Aquarium Face interactions to `epiphany-character-loop` packets before choosing bubble/draft/silence; surface heartbeat `sleepCycle`, `memoryResonance`, `incubation`, `thoughtLanes`, `bridge`, `candidateInterventions`, `appraisals`, and `reactions` from native status in Aquarium; keep EpiphanyAgent changes to backend contracts, typed state, coordinator policy, bridge tools, heartbeat scheduling, and Face guardrails. Keep purging Python/JSON impurity only when the replacement is a typed Rust, CultCache, or CultNet surface with receipts. + summary: Phase 1 durable state through Phase 6 coordinator/specialist/CRRC/backend organs are landed, but the May 2026 architectural teardown found that the app-server Epiphany control plane has become architectural Jenga: policy, projection, lifecycle glue, prompt packet assembly, coordinator sequencing, and tests are concentrated in the host seam. The foundations are conceptually sound, but the control plane must be extracted/rebuilt before outward feature work resumes. + next_action: Treat `notes/epiphany-architectural-teardown.md` as the active top-priority cleanup directive. Start with the control-plane rebuild: extract Epiphany view/coordinator policy from `vendor/codex/codex-rs/app-server/src/codex_message_processor.rs` into `epiphany-core`, make runtime-spine the sole job/result lifecycle authority, replace summary-string acceptance detection with typed acceptance receipts, collapse endpoint proliferation into intentional view lenses/mutation intents, remove normal public `raw_result` leakage, and split stable heartbeat scheduling from experimental cognition receipts. Do not continue Aquarium UI, bridge, Face, or dogfood expansion until this foundation cleanup has a source-grounded slice plan.