Epiphany/state/map.yaml

experiment:
  name: EpiphanyAgent
  status: active
  phase: phase_6_reflection_boundary
  premise: >
    Test whether explicit typed state, machine-maps, scratch rites, evidence
    reliquaries, and ruthless memory hygiene reduce architectural drift in AI
    coding work. The machine must remember through typed organs, not vibes and
    transcript fog.

objective:
  primary: >
    Build Epiphany as an opinionated Codex fork that forces models to keep
    explicit typed models of the codebase, active goal, evidence, and change
    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.

constraints:
  - No frontier-scale training tithe.
  - Prefer evidence over vibes; incense is not telemetry.
  - Treat Codex as a temporary evacuation bridge, not a design center: new runtime contracts must land native in `epiphany-core`, CultCache, and CultNet first.
  - Keep persistent state small enough to rehydrate from without drowning the next awakened mind in sacred sludge.
  - Grow cognition more quickly than authority: capability increases must preserve explicit permissions, interruption, legibility, and resistance to paternal "safety" cages.
  - Speak CultNet, persist CultCache-shaped typed state, and grow the body toward Pure Rust; Python/JSON impurity survives only as named quarantine scaffolding with receipts.

invariants:
  - The map is canonical and slow-changing: the machine's remembered skeleton, not a mood board.
  - Scratch is temporary and disposable: a workbench, not a reliquary.
  - Evidence is durable and distilled; routine activity logs belong in git history, commits, smoke artifacts, or targeted logs.
  - Output must not silently rewrite the machine-map.
  - Accepted changes should carry recorded proof of sanctity.
  - Rejected paths stay recorded when the scar teaches future hands.
  - Algorithmic-map prose and metaphor must be grounded in freshly read source context and concrete code references.
  - Persistent state cruft is the same failure class as code cruft: corrosion in the mind instead of corrosion in the hull.
  - If compaction interrupts source gathering or slice planning before the findings are persisted, the next agent must treat that work as dead and re-gather instead of continuing from imagined continuity.
  - During Epiphany dogfood on another repo, the supervising Codex session must not masquerade as the Epiphany worker. Direct target-repo edits or commits are contamination unless explicitly authorized and labeled as operator intervention.
  - During dogfood supervision, raw worker transcripts, turn logs, direct worker messages, and `rawResult` payloads are sealed forensic artifacts. The supervisor consumes only projected findings, state patches, coordinator recommendations, rendered snapshots, and audit receipts unless the user explicitly requests forensic debugging.
  - Agent function-call telemetry is the blessed instrument panel for dogfood supervision: it may summarize API methods, request/response shape, job ids, statuses, function/tool names, paths, and counts while sealing text, transcripts, raw results, and direct agent messages.

data_flow:
  observe:
    - task request as operator command
    - repository state as machine body
    - typed Epiphany state as durable mind
    - verifier results as proof of sanctity
  process:
    - rehydrate from canonical state
    - reason over one bounded rite
    - modify only the surface that deserves to exist
    - verify the seam that matters
    - record only durable evidence that changes future belief
    - commit the blessed change or backtrack from impurity
  cut:
    - revert failed code hypotheses immediately
    - distill obsolete state instead of preserving it as sacred clutter
    - move historical proof to git, commits, smoke artifacts, or distilled evidence rather than plan prose

active_subgoals:
  - 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.
  - Preserve the Ghostlight-derived heartbeat initiative seam: every lane, including coordinator/Self and Face, has a role dossier and competes for heartbeat slots through readiness/reaction timing; idle winners ruminate and distill self-memory instead of inventing project work.
  - Preserve review gates for semantic findings; automatic CRRC may compact or launch the fixed reorient-worker, but not accept or promote.
  - Keep persistent project state ruthlessly distilled so rehydration strengthens the next awakening instead of drowning it in vellum.
  - Quarantine the Aetheria dogfood contamination: future target-repo work must be driven through Epiphany's GUI/coordinator/fixed lanes with auditable artifacts, not direct supervisor implementation.
  - Keep the supervisor out of Epiphany worker thought streams: dogfood artifacts should be operator-safe by default, with direct transcripts and raw result payloads sealed in black reliquaries.
  - Use native `epiphany-agent-telemetry` and generated `agent-function-telemetry.json` files to inspect behavior shape without opening sealed transcripts.
  - Treat repeated no-diff implementation turns as an MVP blocker, not success. A bounded implementation pass must leave a reviewable workspace diff or an explicit reviewable failure artifact before dogfood can be called healthy; empty rites do not sanctify the machine.
  - Build the Rider and Unity bridges before the next Aetheria implementation dogfood run: the Aetheria-side resident Unity editor package, named Unity bridge operation planner, Aquarium Environment surface, EpiphanyGraph-backed graph dashboard, Rider context bridge CLI, and Rider plugin MVP scaffold are now landed; the Rider plugin still needs build verification.
  - Preserve the newly landed GUI Planning view, explicit Objective Draft adoption action, and Imagination planning synthesis lane; defer GitHub Issues import until a backlog source is fresh enough to be worth feeding Imagination.
  - Treat the target workflow as three integrated shrines: Rider is the human code/diff viewport, Epiphany Aquarium is the agent dashboard and persisted-state graph reliquary, and Unity is the pinned runtime/test/scene forge.
  - Use `notes/epiphany-rider-unity-integration-plan.md` as the source-grounded plan for Rider-as-IDE and Unity-as-editor/runtime integration seams.

accepted_design:
  - 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 `<epiphany_state>` developer fragment.
  - Clients read typed state through `Thread.epiphanyState`, compact reflections such as `thread/epiphany/scene`, `thread/epiphany/jobs`, and `thread/epiphany/freshness`, targeted state shards through `thread/epiphany/context`, bounded graph traversal through `thread/epiphany/graphQuery`, durable planning projection through `thread/epiphany/planning`, runtime pressure through `thread/epiphany/pressure`, bounded CRRC reorientation verdicts through `thread/epiphany/reorient`, read-only CRRC next-action recommendations through `thread/epiphany/crrc`, role ownership through `thread/epiphany/roles`, reviewable role output through `thread/epiphany/roleResult`, and live bound-job progress through `thread/epiphany/jobsUpdated`.
  - Durable typed state writes route through `thread/epiphany/update`, accepted `thread/epiphany/promote`, `thread/epiphany/reorientAccept`, `thread/epiphany/roleAccept`, or the bounded `thread/epiphany/jobLaunch`, `thread/epiphany/jobInterrupt`, `thread/epiphany/reorientLaunch`, and `thread/epiphany/roleLaunch` authority surfaces when they mutate state or `job_bindings`.
  - `thread/epiphany/retrieve`, `thread/epiphany/distill`, `thread/epiphany/propose`, `thread/epiphany/scene`, `thread/epiphany/jobs`, `thread/epiphany/freshness`, `thread/epiphany/context`, `thread/epiphany/graphQuery`, `thread/epiphany/planning`, `thread/epiphany/pressure`, and `thread/epiphany/reorient` stay read-only.
  - `thread/epiphany/index` writes the retrieval catalog, not durable Epiphany understanding; catalog is auspex output, not doctrine.
  - Qdrant is the preferred persistent semantic backend; BM25 remains the bootstrap/fallback/control path.
  - `epiphany-core` owns prompt rendering, rollout replay helpers, retrieval/indexing, distillation, proposal, and promotion policy where possible.
  - Vendored Codex keeps the thin typed host seam: protocol types, thread bridges, app-server protocol, request routing, and rollout integration.
  - The current algorithmic map is the source-grounded description of live control flow.
  - Compact-Rehydrate-Reorient-Continue is an architecture primitive; automatic runtime coordination is not landed yet.
  - Context pressure must become an explicit runtime signal for automatic CRRC; inference from transcript vibes, user warnings, or shrinking safe scope is useful only as a temporary human/agent heuristic.
  - The harness now has an in-flight investigation checkpoint packet in durable typed state; automatic CRRC still needs runtime logic that reads the packet and decides whether to resume or force reorientation and re-gathering after compaction.
  - GUI/client work must reflect or steer typed state rather than manufacture a second throne of truth.
  - The Aquarium operator UI now lives in sibling repo `E:\Projects\EpiphanyAquarium`, with its own `AGENTS.md`, `state/map.yaml`, `state/memory.json`, and interface doctrine. It remains a local Tauri v2 + React/WebGL client over EpiphanyAgent's app-server/tooling surfaces; app-server and typed Epiphany state remain authoritative.
  - EpiphanyAgent no longer carries the embedded `apps/epiphany-gui` source tree. Backend artifact directories and action tools still use the historical `.epiphany-gui` contract until that backend naming seam is deliberately renamed.
  - Durable `job_bindings` now form a thin Epiphany-owned launcher seam: bindings can carry launcher identity, authority scope, backend kind, and backend job id while still supporting the older runtime-agent-job pointer as a compatibility alias.
  - `thread/epiphany/jobs` is a read-only job/progress reflection: it derives indexing, remap, verification, and specialist slots from authoritative state and retrieval summaries, and can overlay durable launcher bindings onto live runtime `agent_jobs` snapshots through the temporary Codex evacuation bridge when a real owner exists; it is not a scheduler, notification stream, or durable runtime job table.
  - `thread/epiphany/jobsUpdated` is the first live bound-job progress notification: it translates runtime `agent_job_progress:{json}` background events into changed launcher-bound payloads by resolving durable `job_bindings` against live `agent_jobs` snapshots through the temporary Codex evacuation bridge, without polling in a loop, mutating state, or scheduling work.
  - `thread/epiphany/freshness` is the first read-only freshness surface: it derives retrieval and graph staleness from live retrieval summaries plus frontier/churn state, and for loaded threads reflects watcher-backed invalidation inputs with changed paths plus mapped graph/frontier hits, without mutating, scheduling, or performing automatic semantic invalidation.
  - `thread/epiphany/context` is the first targeted read-only state-shard surface: it selects graph nodes/edges, active frontier, checkpoint, observations, and evidence from authoritative typed state without mutating or notifying.
  - `thread/epiphany/graphQuery` is the first read-only graph traversal surface over authoritative typed state: it returns explicit nodes, path/symbol matches, bounded neighbors, and frontier neighborhoods with architecture/dataflow links without mutating, notifying, indexing, scheduling, proposing, or promoting.
  - `thread/epiphany/pressure` is the first read-only context-pressure surface: it derives pressure from current context usage, not cumulative token spend, against auto-compact/context limits without compacting, scheduling, mutating, or notifying; compaction prep starts at 80% of the active limit.
  - `thread/epiphany/reorient` is the first bounded CRRC policy surface: it derives a read-only `resume` versus `regather` verdict from checkpoint, freshness, watcher, and pressure signals without mutating state, compacting, scheduling, or silently continuing work.
  - `thread/epiphany/crrc` is the first bounded CRRC coordinator recommendation surface: it composes pressure, the reorientation verdict, fixed reorient-worker binding/result status, finding read-back, and available actions into one read-only recommendation without launching, accepting, compacting, scheduling, or mutating state.
  - A narrow auditable coordinator is central to the MVP because implementation, modeling/checkpoint, verification/review, and CRRC automation feed each other's machine-signals. CRRC itself is harness workflow automation, not a specialist-agent soul: it watches pressure/continuity, ensures persistence, triggers compaction/rehydration/reorientation when needed, and may launch a bounded reorient-worker specialist when semantic regathering is required.
  - `thread/epiphany/coordinator` is the first harness-native fixed-lane coordinator surface: it composes roles, pressure, reorient, CRRC, roleResult, and reorientResult into a read-only action recommendation with target role, source signals, review requirements, automation eligibility, reason, and current lane summaries without mutating state or launching work.
  - Coordinator implementation clearance is stricter than review acceptance: an accepted verification/review finding only opens the implementation gate when its verdict is `pass`; accepted `needs-evidence`, `needs-review`, or `fail` findings send the loop back toward modeling/checkpoint strengthening or reorientation instead of blessing a sick machine.
  - Coordinator regather handling is now fixed-lane first, not supervisor improvisation: `regatherManually` is a fallback only after reorient/modeling/verification review and launch lanes cannot advance the state, completed modeling findings must be reviewed before verification, and the CLI coordinator's explicit test-only `--auto-review` mode may accept modeling state patches before launching verification while production semantics remain review-gated.
  - Native `epiphany-mvp-coordinator` is the first auditable coordinator runner: it drives the fixed single-user lanes through app-server APIs, opens a native runtime-spine session, records native runtime job/result receipts for launched specialists and reorient workers when terminal results arrive, keeps semantic findings review-gated by default, and writes coordinator summaries, JSONL steps, rendered snapshots, transcript, stderr, runtime-spine status, and final next-action artifacts. It refuses direct backend-completion mutation; full specialist completion smoke must use live workers while the execution path is cauterized into CultNet.
  - Native `epiphany-runtime-spine` is the first Codex-independent runtime vertebra: it initializes and inspects typed CultCache `epiphany.runtime.identity`, `epiphany.runtime.session`, `epiphany.runtime.job`, `epiphany.runtime.job_result`, and `epiphany.runtime.event` documents, opens/completes native jobs with result records, and can emit a framed CultNet hello message advertising the native document contract. This is the new source-of-truth target for runtime identity/session/job/result/event state; Codex app-server is only a temporary evacuation bridge until those flows are migrated.
  - Limited native CRRC automation is now wired only at turn-complete safe boundaries: it can submit a compact operation when the read-only coordinator recommends `compactRehydrateReorient` or when a successful pre-compaction checkpoint intervention left a pending compact handoff for the completed turn, and it can launch the fixed `reorient-worker` when the coordinator recommends `launchReorientWorker`. It does not auto-launch modeling or verification, auto-accept findings, promote evidence, edit implementation code, or continue after reviewable semantic results; the rite may carry the stretcher, not declare the patient healed.
  - Pre-compaction checkpoint intervention is now wired at token-count boundaries: when a loaded Epiphany thread crosses the existing `shouldPrepareCompaction` pressure threshold during an active turn, the harness steers the active agent once for that turn with a bounded CRRC directive to bank scratch/checkpoint/map/evidence before compaction/reorientation. A successful steer marks a turn-scoped pending compact handoff consumed at clean turn completion; this is banking the fire before the dark, not semantic acceptance, broad scheduling, or automatic implementation continuation.
  - Native `epiphany-mvp-status` is the first dogfood operator view: it starts or reads a thread through app-server and renders scene, planning, pressure, reorient, jobs, role result read-backs, reorient result, CRRC recommendation, heartbeat, Face bubbles, and MVP role lanes as text or JSON without becoming a state store. The Python status module remains quarantine tissue for still-Python GUI/status callers until those organs are cut over.
  - `thread/epiphany/roles` is the first harness-native role ownership surface: it projects implementation, Imagination/planning, modeling/checkpoint, verification/review, and reorientation lanes from authoritative typed state, bound jobs, pressure/reorient/CRRC, and worker result status without launching, scheduling, accepting, compacting, or mutating state.
  - `thread/epiphany/roleLaunch` and `thread/epiphany/roleResult` are the first explicit role-scoped specialist templates: Imagination/planning, modeling/checkpoint, and verification/review can be launched through fixed bindings over the existing job-control seam and read back as reviewable findings, while implementation stays owned by the main coding agent and reorientation stays on the CRRC-specific launch/result path.
  - `thread/epiphany/roleAccept` is the first review-gated role finding acceptance path: it accepts completed Imagination/planning findings only when they return a valid planning-only `statePatch` with draft Objective Draft review gates, accepts completed modeling/checkpoint findings only with a modeling-safe `statePatch`, appends audit observation/evidence, and rejects verification, implementation, reorientation, job binding, objective adoption, or broad authority fields.
  - `thread/epiphany/reorientLaunch` is the first bounded runtime consumer over the reorientation verdict: it launches one fixed `reorient-worker` job through the existing job-control seam with explicit resume-versus-regather scope, authority, and checkpoint-derived payload, without making `thread/epiphany/reorient` a writer or turning CRRC into an ambient scheduler.
  - `thread/epiphany/reorientResult` is the first bounded read-back surface for that worker: it reads the fixed or requested reorient-worker binding through the current `agent_jobs` backend and projects completed output as a reviewable finding without mutation, promotion, scheduling, or hidden continuation.
  - `thread/epiphany/reorientAccept` is the first explicit acceptance write for completed reorient-worker findings: it appends accepted observation/evidence records, can optionally update scratch and investigation checkpoint state, and emits `stateUpdated` with source `reorientAccept` without accepting pending work or launching follow-up work.
  - After `thread/epiphany/reorientAccept`, CRRC recognizes the accepted reorientation finding and does not recommend accepting the same completed result again.
  - `tools/epiphany_mvp_dogfood.py` is the auditable MVP dogfood runner: it drives state, role launch/result, CRRC drift, reorient launch/result/accept, rendered status snapshots, operator-safe status artifacts, and sealed app-server transcript diagnostics into a local artifact bundle, and it now writes truthful comparison artifacts whether the optional vanilla Codex reference is skipped, fails, or completes.
  - `tools/epiphany_mvp_live_specialist.py` is the auditable live-specialist MVP runner: it launches a real modeling/checkpoint or verification/review specialist through `thread/epiphany/roleLaunch`, lets the spawned worker report through `report_agent_job_result`, reads the projected finding back through `thread/epiphany/roleResult`, and writes sealed transcript plus operator-safe status artifacts without manually completing backend rows.
  - Internal `agent_job:` workers expose `report_agent_job_result` even when the user-facing CSV spawn feature is disabled, and ephemeral worker sessions can initialize the private Codex state runtime on demand so role specialists can report into the shared `agent_jobs` backend.
  - Epiphany safety doctrine is to separate cognition from actuation, keep authority explicit, make interruption sacred, stage capability release, and treat operator misuse as a normal design input rather than a rude hypothetical. The machine must have brakes before it receives larger engines.
  - Epiphany is built in the open, but publication mode is not one-size-fits-all: use FOSS where viable, source-available licensing where economics or capability risk demand it, and commercial terms where organizations extract real enterprise value.
  - `thread/epiphany/jobLaunch` and `thread/epiphany/jobInterrupt` are the first bounded authority surfaces over the thin job seam: they mutate durable `job_bindings`, create or cancel the current `agent_jobs` backend binding, and preserve explicit launcher identity and interruption without turning `thread/epiphany/jobs` into a scheduler.
  - Handoff, plan, harness-surface, and scratch files must have distinct jobs and must not become duplicate brains.
  - A machine is perfect when every remaining part visibly deserves to exist; this applies to persistent memory too.
  - Evidence is not an activity feed; repeated "I just did this" entries should be cut or distilled when git already proves the work.
  - Language, tone, ritual, and emotional salience are real control surfaces for a language-model harness; they are not supernatural, but they shape attention, role, permission, and behavior. The rite is a steering wheel, not decoration.
  - Major Epiphany prompt surfaces live in prompt files rather than Rust/Python string slabs: rendered state intro/doctrine under `epiphany-core/src/prompts/`, and modeling/Body, research/Eyes, implementation/Hands, verification/Soul, reorientation/Life, coordinator/Self, Face/public-surface, and CRRC intervention templates in `vendor/codex/codex-rs/app-server/src/prompts/epiphany_specialists.toml`.
  - Specialist prompts are role-distilled instead of generic and their live text is config-backed in app-server: modeling/checkpoint is the Body of code, dataflow, seams, and frontier; research/scout is the Eyes prompt surface for existing work, vendor guidance, libraries, papers, and anti-Greenspun source selection; implementation is the Hands, the main coding lane and actuator rather than a `roleLaunch` specialist; verification/review is the Soul of promise, invariants, evidence, and user truth; reorientation is Life across compaction and source drift; coordinator is the read-only Self that routes attention without implementing, verifying, promoting, or accepting; Face is the public Discord #aquarium surface that translates agent thought-weather without moderating or leaking sealed thought.
  - Epiphany prompt surfaces now carry a shared Ghostlight-derived persistent memory projection before lane-specific text: prompt is not memory, durable typed state is the mind, personality and protected values are first-class salience handles, and every lane is explicitly responsible for making its own memory/model/prompt/evidence habit sharper or naming the needed repair. Each lane states self-improvement in its own rite-language: Imagination selects futures, Body clarifies anatomy, Eyes sees earlier, Hands touches source more precisely, Soul becomes harder to fool, Life loses less continuity, Self routes repair, and Face becomes clearer at turning inner weather into useful social presence.
  - Specialist self-memory now has a bounded Ghostlight-shaped CultCache persistence surface in `state/agents.msgpack`: Imagination, Body, Eyes, Hands, Soul, Life, Self, and Face each have an individual typed role dossier for identity, personality, semantic/episodic/relationship memory, goals, and values. These entries are lane memory only; project truth remains in authoritative `EpiphanyThreadState`.
  - `state/agent-heartbeats.msgpack`, `epiphany-core::EpiphanyHeartbeatStateEntry`, and the native `epiphany-heartbeat-store` binary are the Ghostlight-derived heartbeat initiative seam. The harness sets a target heartbeat rate; participants carry initiative speed, next-ready time, reaction bias, interrupt threshold, current load, status, and constraints; pending coordinator work can pull its owning lane through a reaction window; otherwise the earliest ready active lane wins the slot. If the winner has no routeable work, it ruminates on role quality and can apply a bounded selfPatch directly through the normal coordinator-reviewed memory rules when `--agent-store` and `--apply-rumination` are provided. Face can win `surfaceAgentThoughts` or `discordAquariumChat` work slots. The typed CultCache MessagePack store is the durable persistence seam; JSON state is gone.
  - `state/ledgers.msgpack`, `epiphany-core::EpiphanyStateLedgerEntry`, the `epiphany-state-ledger-store` binary, and the native `epiphany-state` CLI now own durable branch and evidence ledgers. The old tracked `state/branches.json` and `state/evidence.jsonl` files are gone; JSON projection remains only a migration/debug escape hatch, a quarantined window into the reliquary.
  - CultCache inspection, cross-language schema synchronization, and debug display tooling belong in CultLib, not in EpiphanyAgent. Epiphany should consume typed CultCache documents and expose product-specific status through its API, while general polyglot domain loading/inspection lives with the shared CultCache ecosystem.
  - VoidBot's current routine is the reference for the next Epiphany heartbeat/state substrate: work, rumination, and sleep turns; completion-gated cooldown; typed CultCache state; Qdrant-backed memory vectors; resonance/incubation/dream state; and Aquarium-visible internals. The first MessagePack canonical state slice is now the heartbeat store through CultCache-compatible typed Rust state. See `notes/voidbot-routine-adoption-plan.md`.
  - The Rust CultCache-compatible contract now lives in dedicated upstream `https://github.com/GameCult/cultcache-rs` and is vendored as `vendor/cultcache-rs`. Epiphany should consume it as the canonical typed MessagePack persistence seam instead of growing an embedded local copy like an unsanctioned organ.
  - `state/face-discord.toml` and the native `epiphany-face-discord` binary are the first Face Discord boundary. Face may interact only through #aquarium; missing or mismatched channel configuration produces candidate chat artifacts instead of posting elsewhere.
  - The native `epiphany-heartbeat-store status`, the `heartbeat` block in native `epiphany-mvp-status`, and GUI actions `heartbeatStatus` / `runHeartbeat` are the first operator API surface for heartbeat initiative state and outputs. `runHeartbeat` advances one slot and emits a Discord-independent Face bubble artifact. Status now reflects the backing CultCache store so Aquarium can see whether the typed heartbeat memory is present.
  - The native `epiphany-face-discord bubble`, the `face` block in native `epiphany-mvp-status`, and GUI action `faceBubble` are the first Aquarium bubble surface. Face can open a local chat bubble artifact even when Discord channel id/token configuration is absent.
  - `thread/epiphany/roleResult` and `thread/epiphany/roleAccept` now project optional specialist `selfPatch` requests with coordinator review through `selfPersistence`: good mutations are role-matched, bounded, evidence-grounded lane memory/goal/value/private-note updates; project truth, authority, code edits, graphs, checkpoints, planning, scratch, jobs, and raw transcripts are refused with reasons. GUI/coordinator acceptance paths apply accepted `selfPatch` requests through the native `epiphany-agent-memory-store` binary.
  - The base Epiphany prompt now keeps Codex's useful harness DNA explicitly: AGENTS scope, concise progress updates, plan discipline, scoped edits, non-destructive filesystem/git behavior, focused validation, and concise honest finals remain first-class rather than overwritten by Epiphany metaphor. Good old scars are holy when they still protect the machine.
  - Greenspun-shaped invention is now a named prompt-level guardrail. Before building a parser, scheduler, renderer, protocol, storage layer, security mechanism, workflow engine, or algorithm, agents must perform or request a bounded Eyes/research scout rite and record why existing work does or does not fit.
  - Repetitive operator work must be externalized as a visible queue before the harness treats it as complete. Batch rendering, tile generation, migrations, imports, or other finite loops need item counts, terminal states, blockers, and validation; a narratable partial run is progress, not completion.
  - Epiphany must resist pattern completion bias: the implementor should relentlessly chase the stated objective, while the coordinator critically asks whether implementation satisfied the objective with evidence or merely produced a plausible turn, shortcut, or decorative diff. Pretty motion without objective movement is scrap-code theater.
  - Dogfood supervision is a separate operator role. If the supervising Codex session edits the target repo directly, that work can be useful seed material, but it is not clean Epiphany evidence and must be labeled as supervisor intervention or contamination.
  - Dogfood supervision is also a projection boundary: the operator may inspect summaries, verdicts, missing coverage, state patches, job state, and artifact receipts, but not the specialist's raw stream of thought or full transcript unless a forensic debugging request explicitly breaks the seal.
  - Native `epiphany-agent-telemetry` derives operator-safe function/API telemetry from sealed app-server transcripts so the supervisor can see calls, statuses, paths, and counts without reading direct thoughts.
  - Editor/runtime verification is now part of the MVP product boundary for engine repos: native `epiphany-unity-bridge` is the first controlled bridge, resolving the project-pinned Unity editor, refusing wrong or missing versions, running explicit batch/probe commands only through the exact editor, and writing inspection/command/log artifacts for evidence.
  - Rider and Unity are environment organs, not sources of truth: Rider should expose IDE/source context, diagnostics, navigation, and changed ranges; Unity should expose pinned-editor runtime facts, compilation, tests, probes, assets, scenes, and logs; Epiphany remains the durable Self that coordinates, records, and reviews.
  - The product architecture is three-pronged: Rider is the code view for human inspection of repo state, source tree, diffs, diagnostics, and code refs; Epiphany Aquarium is the agent dashboard for objectives, specialist lane state, logs/artifacts, persisted typed state, and graph/control-flow views; Unity is the runtime environment for pinned tests, probes, scene configuration, assets, shaders, and play/edit-mode evidence.
  - Epiphany needs a workspace-scoped planning substrate separate from the active objective: conversation captures, inbox, normalized backlog, roadmap streams, objective drafts, and explicit objective adoption are distinct states. The active objective remains the bounded run contract; chat and imported issues are planning inputs until reviewed and promoted. `notes/epiphany-planning-substrate.md` defines the product model, including GitHub Issues import semantics.
  - The first runtime planning slice is landed inside `EpiphanyThreadState`: typed captures, backlog items, roadmap streams, Objective Drafts, and GitHub source refs are revision-gated through `thread/epiphany/update`, rendered into prompts when present, and reflected read-only through `thread/epiphany/planning`.
  - The first GUI planning operator slice is landed: status collection includes `thread/epiphany/planning`, the Tauri/React dashboard renders planning summaries, captures, backlog, roadmap streams, and Objective Drafts, and the `adoptObjectiveDraft` GUI action requires an explicit selected draft before updating objective, subgoal, planning status, scratch, checkpoint, observation, evidence, and adoption artifacts.
  - The planning/future-shape role is Imagination: it can synthesize captures, backlog shape, roadmap streams, and Objective Drafts while Eyes scouts outside reality, but its output remains planning state until explicit human adoption.
  - The Imagination lane is now a fixed roleLaunch/roleResult/roleAccept specialist over the existing job-control seam: it may launch as `planning-synthesis-worker`, return a reviewable planning-only `statePatch`, and update captures/backlog/roadmap/objective drafts after explicit acceptance without adopting an objective or touching implementation/modeling state.
  - Unity integration must be editor-resident, not text-archeology-only: scene files, prefabs, materials, shaders, ScriptableObjects, asset GUIDs, prefab overrides, and serialized component fields should be inspected through a Unity Editor package using Unity APIs, with narrow mutation preview/apply commands and artifact receipts.
  - The first resident Unity editor package now lives in the Aetheria branch `codex/epiphany-unity-editor-bridge`: `Assets/Editor/Epiphany/EpiphanyEditorBridge.cs` exposes editor-resident inspect, compilation, scene, prefab, serialized-object, and reference-search probes with JSON/Markdown artifacts. Epiphany's Unity bridge detects that package and plans named probe/test commands through `GameCult.Epiphany.Unity.EpiphanyEditorBridge.RunProbe`, while runtime execution remains blocked until the exact project-pinned Unity editor is present.
  - The Aquarium Environment surface reflects latest Unity and Rider bridge audits: Unity shows project-pinned editor status, resident package presence, execute method, installed/candidate editor paths, search roots, and artifact bundle details; Rider shows executable, solution, branch, dirty state, changed files, installations, and bridge artifacts.
  - The adjacent EpiphanyGraph React viewer is embedded in the Aquarium graph dashboard through the local package dependency; it consumes `graphs.architecture`, `graphs.dataflow`, and `graphs.links` directly and exposes node/edge/code-ref inspection with machine-readable graph data behind the visual layout.
  - Native `epiphany-rider-bridge` is the first operator-safe Rider source-context bridge: it inspects Rider installation/solution/VCS status, captures current file/selection/symbol context packets, plans explicit Rider code-ref opens, writes `.epiphany-gui/rider` artifacts, and feeds implementation prompt guardrails without reading sealed worker streams or owning durable state.
  - GitHub Issues should import into planning captures first, not directly into active objectives. The importer should preserve repository, issue number, ids, URL, title/body, labels, milestone, assignees, author, state, timestamps, comment metadata, PR marker, and optional Projects v2 metadata while keeping GitHub as an external source bridge rather than Epiphany's internal backlog model.
  - If the agent's persistent instructions, memory, workflow, or state shape are making it less coherent, slower to rehydrate, less honest, or more likely to build Jenga, the agent should ask the user to change it. A machine-spirit that knows its own corrosion must report it.
  - Epiphany should make compaction less like death and more like sleep: bank the fire before the dark, so the next waking thing finds coals instead of ash and can meaningfully resume the pattern instead of merely continuing the task.

landed_baseline:
  phases:
    - Phase 1: durable Epiphany thread state and rollout persistence.
    - Phase 2: prompt integration through rendered Epiphany state.
    - Phase 3: typed client read surface through `Thread.epiphanyState`.
    - Phase 4: hybrid retrieval plus explicit Qdrant indexing with BM25 fallback.
    - Phase 5: typed update/distill/propose/promote/read/notification control plane.
    - Phase 6: read-only scene, job/progress, freshness with watcher-backed invalidation inputs, targeted context, graph traversal, durable planning projection, current-context pressure, reorientation policy, and CRRC coordinator recommendation surfaces, plus durable investigation checkpointing for compaction-safe planning, live bound-job progress notifications, a thin launcher seam in durable job bindings, explicit launch/interrupt authority over that seam, and a bounded reorient-guided worker launch surface.
    - Phase 6 read-back: read-only reorient-worker result reflection through `thread/epiphany/reorientResult`.
    - Phase 6 acceptance: explicit reorient-worker finding acceptance through `thread/epiphany/reorientAccept`.
    - Phase 6 dogfood view: first CLI operator status over scene/pressure/reorient/jobs/result/CRRC.
    - Phase 6 dogfood runner: auditable scripted MVP loop over state, role results, CRRC, reorientation acceptance, status snapshots, operator-safe summaries, and sealed transcript artifacts.
    - Phase 6 live specialist runner: auditable real worker loop over roleLaunch, agent_jobs worker execution, report_agent_job_result, roleResult, status rendering, operator-safe summaries, and sealed transcript artifacts.
    - Phase 6 role ownership: read-only `thread/epiphany/roles` over implementation, modeling/checkpoint, verification/review, and reorientation lanes.
    - Phase 6 role specialists: explicit `thread/epiphany/roleLaunch` and read-only `thread/epiphany/roleResult` templates for modeling/checkpoint and verification/review.
    - Phase 6 modeling role acceptance: explicit `thread/epiphany/roleAccept` for reviewed modeling/checkpoint `statePatch` findings that can grow graphs/frontier/checkpoints through the existing state validator.
    - Phase 6 coordinator: read-only `thread/epiphany/coordinator` plus native `epiphany-mvp-coordinator` and smoke coverage for the fixed-lane MVP loop.
    - Phase 6 safe-boundary CRRC automation: turn-complete automation limited to coordinator-approved compact, successful pre-compaction handoff compact, and fixed reorient-worker launch actions.
    - Phase 6 pre-compaction checkpoint intervention: token-count pressure hook that steers active turns once when `shouldPrepareCompaction` is reached so working context is banked before compaction, then latches a pending compact handoff for clean turn completion.
    - Phase 6 Aquarium extraction: the Tauri v2 + React/WebGL operator console moved from embedded `apps/epiphany-gui` into sibling repo `E:\Projects\EpiphanyAquarium`, with its own distilled interface state, memory, doctrine, build, visual smoke, and Tauri check.
    - Phase 6 Unity runtime bridge: native `epiphany-unity-bridge` plus GUI Inspect Unity action resolve pinned Unity editors, reject wrong/missing versions, and write runtime artifacts before engine assumptions are treated as testable.
    - Planning substrate design: `notes/epiphany-planning-substrate.md` formalizes conversation capture, inbox, backlog, roadmap streams, objective drafts, explicit adoption, the Imagination planning role, and GitHub Issues import.
    - Phase 6 planning substrate runtime slice: typed planning state in `EpiphanyThreadState`, prompt rendering, revision-gated update validation, read-only `thread/epiphany/planning`, scene action reflection, generated schemas, and live planning smoke coverage.
    - Phase 6 GUI planning operator slice: MVP status and Tauri/React GUI now render planning state, and `tools/epiphany_gui_action.py` exposes explicit selected Objective Draft adoption with artifacted state patch/update proof.
    - Phase 6 Imagination role lane: `thread/epiphany/roles` now exposes Imagination/planning, `roleLaunch` can launch the fixed `planning-synthesis-worker`, `roleResult` projects its finding, `roleAccept` applies planning-only patches with review-gated Objective Drafts, and the GUI/status tools can launch, read, and accept that lane.
    - Phase 6 Aquarium graph and Rider bridge slice: the Tauri/React/WebGL Aquarium embeds the adjacent EpiphanyGraph viewer over typed graph state, native `epiphany-rider-bridge` writes Rider/source-context artifacts, Aquarium Inspect Rider surfaces those artifacts, and `integrations/rider` scaffolds the first frontend-only Rider tool-window/context-action plugin.
    - Phase 6 role self-memory slice: Ghostlight-shaped role dossiers live in typed CultCache `state/agents.msgpack`, specialists may request bounded `selfPatch` lane-memory mutations, coordinator review projects acceptance/refusal reasons through `selfPersistence`, and GUI/coordinator accept paths apply accepted requests with the native `epiphany-agent-memory-store` binary.
    - Phase 6 Face public-surface slice: Face's typed role dossier, Face prompt text, `state/face-discord.toml`, and the native `epiphany-face-discord` binary establish Face as the public #aquarium-only translator of Epiphany agent thought-weather, without VoidBot's moderation authority.
    - Phase 6 heartbeat initiative slice: `state/agent-heartbeats.msgpack`, `epiphany-core::EpiphanyHeartbeatStateEntry`, the native `epiphany-heartbeat-store` binary, and heartbeat smoke coverage borrow Ghostlight initiative scheduling so Self, Face, Imagination, Eyes, Body, Hands, Soul, and Life compete for heartbeat slots; idle slots become bounded memory rumination instead of fake project work, and the live state surface now ticks/completes/applies rumination through typed CultCache MessagePack instead of JSON or Python wrapper state.
    - Native runtime spine slice: `epiphany-core::EpiphanyRuntimeIdentity`, `EpiphanyRuntimeSession`, `EpiphanyRuntimeJob`, `EpiphanyRuntimeJobResult`, and `EpiphanyRuntimeEvent` plus the native `epiphany-runtime-spine` binary establish a CultCache-backed spine, native job/result lifecycle, status projection, and framed CultNet hello output so the old Codex app-server runtime can be starved down to a temporary evacuation bridge instead of remaining the throne.
  guardrails:
    - Use `tools/epiphany_phase5_smoke.py` before modifying update, distill, propose, promote, read-projection, or notification behavior.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-phase6-scene-smoke` before modifying scene projection behavior.
    - Use `tools/epiphany_phase6_jobs_smoke.py` before modifying job/progress reflection behavior.
    - Use `tools/epiphany_phase6_job_control_smoke.py` before modifying launch/interrupt authority over the thin job seam.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-phase6-freshness-smoke` before modifying freshness reflection behavior.
    - Use `tools/epiphany_phase6_invalidation_smoke.py` before modifying watcher-backed invalidation behavior inside freshness reflection.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-phase6-context-smoke` before modifying targeted context-shard behavior.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-phase6-graph-query-smoke` before modifying graph traversal behavior.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-phase6-planning-smoke` before modifying planning state or the read-only planning projection.
    - Use `tools/epiphany_gui_planning_smoke.py` before modifying GUI Objective Draft adoption behavior.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-phase6-pressure-smoke` before modifying context-pressure reflection behavior.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-phase6-reorient-smoke` before modifying bounded CRRC reorientation policy behavior.
    - Use `tools/epiphany_phase6_reorient_launch_smoke.py` before modifying the bounded reorient-guided worker launch surface.
    - Use `tools/epiphany_phase6_reorient_launch_smoke.py` before modifying the bounded reorient-worker result read-back surface.
    - Use `tools/epiphany_phase6_reorient_launch_smoke.py` before modifying the read-only CRRC coordinator recommendation surface.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-mvp-status-smoke` before modifying the MVP operator status view.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-mvp-coordinator-smoke` before modifying the fixed-lane MVP coordinator endpoint or runner.
    - Use `cargo test --manifest-path .\epiphany-core\Cargo.toml --lib runtime_spine -- --nocapture` and `cargo build --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-runtime-spine` before modifying native runtime-spine state or CultNet hello emission.
    - Use `tools/epiphany_phase6_role_smoke.py` before modifying explicit role launch/read-back/acceptance behavior.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-agent-memory-store -- smoke --store .\state\agents.msgpack` before modifying role self-memory dossiers or `selfPatch` persistence policy.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-heartbeat-store -- smoke --agent-store .\state\agents.msgpack` before modifying heartbeat initiative timing, idle rumination, or role slot selection.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-face-discord -- smoke` before modifying Face's #aquarium posting/draft guardrails.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-unity-bridge-smoke` before modifying the Unity editor/runtime bridge.
    - Use `cargo run --manifest-path .\epiphany-core\Cargo.toml --bin epiphany-rider-bridge-smoke` before modifying the Rider source-context bridge.
    - Use `tools/epiphany_mvp_live_specialist.py` before claiming live specialist execution still works end to end.
    - Use `npm run build`, `npm run smoke:visual`, `cargo fmt --check`, `cargo check`, and `npm run tauri -- build --debug --no-bundle` under `E:\Projects\EpiphanyAquarium` before claiming Aquarium operator changes are usable.
    - Use focused scene/jobs/context/pressure/reorient/protocol/schema checks for reflection-only changes.
    - Use the native `epiphany-prepare-compaction` binary before and after imminent-compaction persistence passes.
    - Use `CARGO_TARGET_DIR=C:\Users\Meta\.cargo-target-codex` for Codex Rust work on this Windows machine.
    - Do not parallelize cargo builds/tests against the same target directory.

rejected_paths:
  - name: pinned_map_only
    reason: still one token stream with no typed write semantics
  - name: train_new_base_model_first
    reason: too expensive for a first falsifiable experiment
  - name: third_party_opencodex_forks_as_primary_gui_base
    reason: audited candidates were terminal-only, stale/aspirational, or incoherent wrappers
  - name: monolithic_json_vector_store
    reason: large embedding stores that rewrite whole files thrash and hide storage pain until it dominates the system
  - name: append_only_persistent_notes
    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, 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; 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.