From e7fdd472eed7e7b82887942d04940225d2a60dc7 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sun, 26 Apr 2026 07:10:48 +0100 Subject: [PATCH] Rewrite README for repo visitors --- README.md | 157 ++++++++++++++++-------------------------------------- 1 file changed, 47 insertions(+), 110 deletions(-) diff --git a/README.md b/README.md index f1b5f7ea..32963f1e 100644 --- a/README.md +++ b/README.md @@ -1,149 +1,86 @@ # EpiphanyAgent -Epiphany is an opinionated fork of Codex built around one demand: the model must -model the thing it is changing. +Epiphany is an opinionated fork of Codex built around one demand: the model +must model the thing it is changing. -The failure mode this repo is hunting is not "the model cannot write code." It -can. Annoyingly well. The failure mode is local plausibility after global -coherence has already wandered into traffic wearing headphones. +The problem this repo is chasing is not "LLMs can't write code." They can. The +problem is that they can keep making plausible local moves after the global +design has already wandered off and died in a ditch. Epiphany answers that by moving important state out of transcript fog and into -typed, inspectable surfaces: maps, scratch, evidence, retrieval state, -observations, graph/frontier state, churn pressure, and client reflections. +typed, inspectable surfaces: maps, evidence, retrieval state, graph/frontier +state, churn pressure, and compact client reflections. The goal is not maximal +output. The goal is a machine whose parts visibly deserve to exist. -## Current Shape +## What Exists Now -This is no longer just an external-file prompting experiment. +The current spine is real, not aspirational: -The landed spine now includes: - -- durable `EpiphanyThreadState` in vendored Codex protocol/core session state -- rollout snapshots and replay reconstruction for resume, rollback, fork, and compaction +- durable `EpiphanyThreadState` in the vendored Codex protocol/core session +- rollout snapshots and replay for resume, rollback, fork, and compaction - bounded `` prompt injection - typed client reads through `Thread.epiphanyState` -- read-only hybrid retrieval through `thread/epiphany/retrieve` +- read-only retrieval through `thread/epiphany/retrieve` - explicit semantic indexing through `thread/epiphany/index` - durable typed writes through `thread/epiphany/update` - read-only observation distillation through `thread/epiphany/distill` - read-only map/churn proposal through `thread/epiphany/propose` - verifier-backed promotion through `thread/epiphany/promote` - successful-write notifications through `thread/epiphany/stateUpdated` -- first Phase 6 reflection through read-only `thread/epiphany/scene` -- repo-owned heavy organs in `epiphany-core/`, with vendored Codex kept as the host seam where practical +- read-only reflection surfaces through `thread/epiphany/scene`, `jobs`, `freshness`, `context`, and `pressure` +- durable investigation checkpointing for compaction-safe planning +- repo-owned heavy Epiphany organs in `epiphany-core/`, with vendored Codex kept as the host seam where practical -Phase 1 through Phase 5 are complete enough. Phase 6 is about reflection and -observable harness state, not more anxious polishing of the Phase 5 control -plane. +Phase 1 through Phase 6 are landed enough for the current experiment. The open +questions are now about observability, invalidation, coordination, authority, +and safe capability growth, not whether typed state can exist at all. -For exact current status, trust: +## Repo Tour -- `state/map.yaml` -- `notes/fresh-workspace-handoff.md` -- `notes/epiphany-fork-implementation-plan.md` -- `notes/epiphany-current-algorithmic-map.md` +If you want the human-readable map of the project, start here: -Git history and smoke artifacts carry proof. `state/evidence.jsonl` carries only -distilled belief-changing evidence, not every little victory lap with a timestamp. - -## Core Artifacts - -- `AGENTS.md`: project-specific operating discipline for future Codex sessions -- `state/map.yaml`: canonical current project map and accepted design -- `state/scratch.md`: disposable working memory for one bounded subgoal -- `state/branches.json`: branch hypotheses and outcomes, not volatile phase status -- `state/evidence.jsonl`: distilled durable evidence, decisions, rejected paths, and scars -- `notes/fresh-workspace-handoff.md`: compact re-entry packet -- `notes/epiphany-fork-implementation-plan.md`: distilled forward implementation plan -- `notes/epiphany-current-algorithmic-map.md`: source-grounded live control-flow map -- `notes/epiphany-core-harness-surfaces.md`: stable surface contract - `notes/architecture-rationale.md`: why the map/scratch/evidence architecture exists -- `notes/epiphany-safety-architecture.md`: capability, authority, and anti-cage design doctrine -- `notes/codex-repository-algorithmic-map.md`: background map of the vendored Codex substrate -- `protocol/controller-actions.md`: legacy/manual controller discipline for local state maintenance -- `tools/epiphany_state.py`: compact state inspection and distilled evidence helper -- `eval-plan.md`: evaluation sketch for comparing Epiphany discipline against plain prompting +- `notes/epiphany-current-algorithmic-map.md`: source-grounded control flow of the live machine +- `notes/epiphany-fork-implementation-plan.md`: distilled forward plan +- `notes/epiphany-safety-architecture.md`: capability, authority, interruption, and anti-cage doctrine +- `state/map.yaml`: canonical current project map and accepted design -## Next Move +If you want the code: -When implementation resumes, choose one Phase 6 organ: +- `epiphany-core/`: repo-owned Epiphany logic +- `vendor/codex/`: vendored Codex host substrate +- `tools/`: smoke tests and state helpers -1. Live-smoke `thread/epiphany/scene` through app-server. -2. Design and land a minimal read-only job/progress reflection surface for indexing, remap, verification, and future specialist work. +If you are an agent or you are steering one, read `AGENTS.md`. That file is +for operating discipline, re-entry protocol, and session hygiene. The README is +for people, which is a lower-crime use of everyone's time. -The scene-smoke path is tighter. The job/progress path is the larger missing -organ. +## Design Stance -## Working Loop +Epiphany is built on a few stubborn ideas: -1. Rehydrate from canonical state before touching code. -2. Restate the current mechanism and intended change before substantial edits. -3. Keep one bounded hypothesis per iteration. -4. Verify the seam that matters. -5. Revert failed regression or benchmark fixes immediately. -6. Record only distilled evidence that changes future belief. -7. Commit completed work before it rots in the worktree. +- externalized state is better than pretending the transcript is a brain +- local plausibility is not the same thing as global coherence +- evidence should survive, but activity feed sludge should not +- cognition should grow faster than authority +- interruption, legibility, and explicit permissions matter more as the machine becomes more coherent -Do not confuse a growing diff, growing notes, or a local green check with -understanding. That is how the tower learns to smirk. +This repo is not trying to make the model louder. It is trying to make it less +likely to build a Jenga tower and call it understanding. -## Re-entry - -From the repo root: - -```powershell -& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_state.py' status -Get-Content '.\state\map.yaml' -Get-Content '.\notes\fresh-workspace-handoff.md' -Get-Content '.\notes\epiphany-current-algorithmic-map.md' -Get-Content '.\notes\epiphany-fork-implementation-plan.md' -git status --short --branch -git log --oneline -5 -Get-Content '.\state\evidence.jsonl' -Tail 8 -``` - -After compaction or resume, rehydrate and reorient first. Do not continue -implementation just because a note names a next move. - -## Verification - -Use focused checks for the surface being changed. - -For Phase 5 control-plane behavior changes: - -```powershell -& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_phase5_smoke.py' -``` - -For Codex Rust work on this Windows machine: - -```powershell -$env:CARGO_TARGET_DIR='C:\Users\Meta\.cargo-target-codex' -``` - -Do not parallelize cargo builds or tests against the same target directory. - -## Licensing +## License The root `LICENSE` is the operative repository notice. In short: `vendor/codex/**` and other third-party material keep their upstream licenses; -Project-Authored Material outside `vendor/codex/**` is publicly available under +project-authored material outside `vendor/codex/**` is publicly available under PolyForm Noncommercial 1.0.0 and is intended to be available under separate commercial terms by written agreement. External contributions require `CONTRIBUTOR_LICENSE_AGREEMENT.md` or a separate -written agreement accepted by the Project Steward. - -This repo is built in the open. That is the value. It is not a blood oath to -donate every useful organ to any company that wants cheaper leverage. +written agreement accepted by the project steward. The publishing stance is: -- FOSS where that is viable and does not sabotage the project. -- Source-available where the economics or capability profile make full - unrestricted release irresponsible or simply stupid. -- Commercial terms where an organization is extracting real enterprise value - from the work. - -If that sounds less romantic than "just open everything," good. Romance does -not pay for infrastructure, steward a hard project, or answer the question of -whether a capability should diffuse before its governance exists. +- FOSS where that is viable +- source-available where the economics or capability profile make unrestricted release a bad idea +- commercial terms where organizations are extracting real enterprise value