Epiphany/state/map.yaml

experiment:
  name: EpiphanyAgent
  status: active
  phase: phase_6_reflection_boundary
  premise: >
    Test whether explicit typed state, maps, scratch, evidence, and ruthless
    state hygiene reduce architectural drift in AI coding work.

objective:
  primary: >
    Build Epiphany as an opinionated fork of Codex that forces models to keep
    explicit typed models of the codebase, active goal, evidence, and change
    machinery they are working on.
  current: >
    Build the three-pronged Rider/Epiphany GUI/Unity development workflow so
    the next Aetheria run has a code view, agent dashboard, and runtime
    evidence path instead of source-only guesswork.

constraints:
  - No frontier-scale training budget.
  - Prefer evidence over vibes.
  - Keep Codex as the host seam and `epiphany-core` as the repo-owned heavy organ where practical.
  - Keep persistent state small enough to rehydrate from without drowning the next agent.
  - Grow cognition more quickly than authority: capability increases must preserve explicit permissions, interruption, legibility, and resistance to paternal "safety" cages.

invariants:
  - The map is canonical and slow-changing.
  - Scratch is temporary and disposable.
  - Evidence is durable and distilled; routine activity logs belong in git history, commits, smoke artifacts, or targeted logs.
  - Output must not silently redefine the map.
  - Accepted changes should have recorded evidence.
  - Rejected paths stay recorded when the lesson matters.
  - 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.
  - If compaction interrupts source gathering or slice planning before the findings are persisted, the next agent must treat that work as lost 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 safe 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
    - repository state
    - typed Epiphany state
    - verifier results
  process:
    - rehydrate from canonical state
    - reason over one bounded subgoal
    - modify only the surface that deserves to exist
    - verify the seam that matters
    - record only durable evidence that changes future belief
    - commit or backtrack
  cut:
    - revert failed code hypotheses immediately
    - distill obsolete state instead of preserving it as context
    - 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, 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 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 turn instead of bloating it.
  - 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.
  - Use `tools/epiphany_agent_telemetry.py` 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.
  - Build the Rider and Unity bridges before the next Aetheria implementation dogfood run: Aetheria-side resident Unity editor package, named Unity bridge operations over that package, GUI Environment panel, Rider context bridge, and Rider plugin MVP.
  - Treat the target workflow as three integrated surfaces: Rider is the human code/diff view, Epiphany GUI is the agent dashboard and persisted-state graph view, and Unity is the pinned runtime/test/scene environment.
  - 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`, 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/pressure`, and `thread/epiphany/reorient` stay read-only.
  - `thread/epiphany/index` writes the retrieval catalog, not durable Epiphany understanding.
  - 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 source of truth.
  - The MVP GUI target is a local Tauri v2 + React operator console over existing app-server APIs. Tauri owns windowing and local lifecycle; React renders the operator surface; app-server and typed Epiphany state remain authoritative.
  - `apps/epiphany-gui` is the first GUI shell: a Tauri v2 + React app that invokes the existing MVP status bridge, renders coordinator/CRRC/pressure/reorient/role/job/finding status, lists dogfood and GUI action artifact bundles, prepares a durable Epiphany checkpoint for a resumable operator thread, and exposes bounded buttons for status snapshots, coordinator plans, fixed modeling/verification/reorient launch and read-back, and explicit review-gated reorient acceptance.
  - 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 current backend adapter 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 current backend adapter, 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 likely central to the MVP because implementation, modeling/checkpoint, verification/review, and CRRC automation depend on each other's signals. CRRC itself is harness workflow automation, not a specialist-agent role: 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 clears the implementation lane 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 treating the review as a green light.
  - 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.
  - `tools/epiphany_mvp_coordinator.py` is the first auditable coordinator runner: it drives the fixed single-user lanes through app-server APIs, may auto-launch modeling, verification, or reorient-worker jobs, keeps semantic findings review-gated by default, and writes coordinator summaries, JSONL steps, rendered snapshots, transcript, stderr, and final next-action artifacts.
  - 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.
  - 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 still steering plus compaction handoff, not semantic acceptance, broad scheduling, or automatic implementation continuation.
  - `tools/epiphany_mvp_status.py` is the first dogfood operator view: it starts or reads a thread through app-server and renders scene, pressure, reorient, jobs, role result read-backs, reorient result, CRRC recommendation, and MVP role lanes as text or JSON without becoming a state store.
  - `thread/epiphany/roles` is the first harness-native role ownership surface: it projects implementation, 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: 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 currently accepts only completed modeling/checkpoint findings with a valid `statePatch`, applies only modeling-safe fields such as graphs/frontier/checkpoints/scratch/investigation checkpoint plus audit observation/evidence, and rejects verification 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 sqlite 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.
  - 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.
  - Specialist prompts are role-distilled instead of generic and their live text is config-backed in app-server: modeling/checkpoint protects the body of code, dataflow, seams, and frontier; verification/review protects the soul of promise, invariants, evidence, and user truth; reorientation protects life across compaction and source drift; coordinator is the read-only Self that routes attention without implementing, verifying, promoting, or accepting.
  - 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.
  - `tools/epiphany_agent_telemetry.py` 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: `tools/epiphany_unity_bridge.py` 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 GUI 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.
  - 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 adjacent EpiphanyGraph React viewer is the preferred seed for GUI graph/control-flow diagramming because 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.
  - 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.
  - 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, 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 `tools/epiphany_mvp_coordinator.py` 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 GUI operator shell: Tauri v2 + React console under `apps/epiphany-gui` over the existing status bridge and artifact bundles, with visual smoke, durable checkpoint preparation, fixed lane launch/read-back controls, and explicit review-gated reorient acceptance.
    - Phase 6 Unity runtime bridge: `tools/epiphany_unity_bridge.py` plus GUI Inspect Unity action resolve pinned Unity editors, reject wrong/missing versions, and write runtime artifacts before engine assumptions are treated as testable.
  guardrails:
    - Use `tools/epiphany_phase5_smoke.py` before modifying update, distill, propose, promote, read-projection, or notification behavior.
    - Use `tools/epiphany_phase6_scene_smoke.py` 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 `tools/epiphany_phase6_freshness_smoke.py` before modifying freshness reflection behavior.
    - Use `tools/epiphany_phase6_invalidation_smoke.py` before modifying watcher-backed invalidation behavior inside freshness reflection.
    - Use `tools/epiphany_phase6_context_smoke.py` before modifying targeted context-shard behavior.
    - Use `tools/epiphany_phase6_graph_query_smoke.py` before modifying graph traversal behavior.
    - Use `tools/epiphany_phase6_pressure_smoke.py` before modifying context-pressure reflection behavior.
    - Use `tools/epiphany_phase6_reorient_smoke.py` 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 `tools/epiphany_mvp_status_smoke.py` before modifying the MVP operator status view.
    - Use `tools/epiphany_mvp_coordinator_smoke.py` before modifying the fixed-lane MVP coordinator endpoint or runner.
    - Use `tools/epiphany_phase6_role_smoke.py` before modifying explicit role launch/read-back behavior.
    - Use `tools/epiphany_unity_bridge_smoke.py` before modifying the Unity editor/runtime 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 `apps/epiphany-gui` before claiming GUI operator changes are usable.
    - Use focused scene/jobs/context/pressure/reorient/protocol/schema checks for reflection-only changes.
    - Use `tools/epiphany_prepare_compaction.py` 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 GUI/coordinator/specialist/CRRC MVP surfaces are landed. The Aetheria supervised run found and fixed real harness wounds in coordinator policy, no-diff audits, stale job/result projection, and reorient acceptance. The Unity incident proved the next blocker is environment access, so `notes/epiphany-rider-unity-integration-plan.md` now governs a three-pronged bridge-building pass: Rider code view, Epiphany GUI agent dashboard, and Unity runtime environment, with Unity integration treated as a resident editor package rather than text-only file inspection.
  next_action: Implement the three-pronged Rider/Epiphany GUI/Unity workflow before further Aetheria implementation dogfood: Aetheria-side resident Unity editor package, named Unity bridge operations over that package, GUI Environment panel, EpiphanyGraph-backed GUI graph dashboard, Rider context bridge, then Rider plugin MVP. The next dogfood run should happen only after Epiphany can gather Rider/source context and Unity/editor runtime evidence through auditable bridges. Do not let implementation workers invoke Unity directly or refactor Unity-owned serialized scene/prefab state as raw text when an editor API path exists; use bridge artifacts as evidence of either a pinned-editor run, runtime/editor facts, or a missing-runtime blocker. Do not inspect raw worker transcripts or `rawResult` payloads unless the user explicitly requests forensic debugging.