105 lines
6.2 KiB
YAML
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.
|