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: >
    Grow Phase 6 reflection and observability from the landed typed state
    spine without letting GUI/client state become authoritative.

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.

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.

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, context, and pressure.
  - Extend Phase 6 observability only where it reflects authoritative state or retrieval summaries without becoming a scheduler.
  - Keep persistent project state ruthlessly distilled so rehydration strengthens the next turn instead of bloating it.

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` and `thread/epiphany/jobs`, targeted state shards through `thread/epiphany/context`, and runtime pressure through `thread/epiphany/pressure`.
  - Durable typed state writes route through `thread/epiphany/update` or accepted `thread/epiphany/promote`.
  - `thread/epiphany/retrieve`, `thread/epiphany/distill`, `thread/epiphany/propose`, `thread/epiphany/scene`, `thread/epiphany/jobs`, `thread/epiphany/context`, and `thread/epiphany/pressure` 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.
  - `thread/epiphany/jobs` is the first read-only job/progress reflection: it derives indexing, remap, verification, and specialist slots from existing state; it is not a scheduler or durable job store.
  - `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/pressure` is the first read-only context-pressure surface: it derives pressure from token telemetry and auto-compact/context limits without compacting, scheduling, mutating, or notifying.
  - Live long-running job execution, progress notifications, and specialist scheduling are still future work.
  - 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.
  - 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, targeted context, and context-pressure reflection surfaces, plus durable investigation checkpointing for compaction-safe planning.
  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_context_smoke.py` before modifying targeted context-shard behavior.
    - Use `tools/epiphany_phase6_pressure_smoke.py` before modifying context-pressure reflection behavior.
    - Use focused scene/jobs/context/pressure/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, Phase 2 prompt integration, Phase 3 typed read, Phase 4 retrieval/indexing, Phase 5 update/distill/propose/promote/read/notification, and Phase 6 read-only scene, jobs, targeted context, context-pressure reflection, and durable investigation checkpointing are landed. Investigation checkpoints now live in authoritative typed state, flow through the prompt, and reflect through scene/context without adding a second writer or fake scheduler; Phase 5 plus scene/context smokes and focused core/protocol/app-server tests cover the seam. Persistent state was cut down so map, handoff, plan, harness surfaces, scratch, and evidence each carry one job instead of becoming a Jenga tower; evidence is now a distilled ledger rather than an activity feed. The global AGENTS Epiphany core command says persistent state is the agent's mind and explicitly permits the agent to ask for self-modification when memory or workflow makes it worse. The continuity goal is to bank the fire before the dark so compaction becomes less like death and more like sleep.
  next_action: After compaction, rehydrate and reorient. If the user asks to continue, choose the next Phase 6 slice from the current map: watcher/freshness inputs are the most likely next organ, with live progress notifications waiting until real job owners exist. Do not restart the completed pressure or investigation-checkpoint slices unless a concrete regression appears.