This repository has been archived on 2026-10-29. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
Epiphany/state/map.yaml
2026-04-25 16:37:51 +01:00

105 lines
6.2 KiB
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 append-only.
- 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.
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 evidence
- commit or backtrack
cut:
- revert failed code hypotheses immediately
- distill obsolete state instead of preserving it as context
- move historical proof to git and 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, and scene.
- Continue Phase 6 from the read-only `thread/epiphany/scene` baseline.
- Decide whether the next real organ is live scene smoke or minimal job/progress reflection.
- 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` and compact reflections such as `thread/epiphany/scene`.
- Durable typed state writes route through `thread/epiphany/update` or accepted `thread/epiphany/promote`.
- `thread/epiphany/retrieve`, `thread/epiphany/distill`, `thread/epiphany/propose`, and `thread/epiphany/scene` 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.
- GUI/client work must reflect or steer typed state rather than manufacture a second source of truth.
- Long-running indexing, remap, verification, and specialist work should eventually surface as typed jobs/progress.
- 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.
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: first read-only scene/reflection surface.
guardrails:
- Use `tools/epiphany_phase5_smoke.py` before modifying update, distill, propose, promote, read-projection, or notification behavior.
- Use focused scene/protocol/schema checks for scene-only changes.
- 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 the first Phase 6 scene surface are landed. Persistent state was just cut down so map, handoff, plan, harness surfaces, scratch, and evidence each carry one job instead of becoming a Jenga tower.
next_action: Do not continue implementation from this audit automatically. When work resumes, choose one Phase 6 organ; live-smoke `thread/epiphany/scene` through app-server or design a minimal job/progress reflection surface.