diff --git a/AGENTS.md b/AGENTS.md index 2a88bfdb..3315432d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ The motivating failure mode is that an agent can make many plausible local edits - Treat `notes/epiphany-fork-implementation-plan.md` as the current implementation plan for the Epiphany fork architecture. - Update `state/map.yaml` when project understanding changes. - Add evidence after meaningful research, implementation, verification, or rejected paths, but keep it distilled. Routine "I just did this" proof belongs in git history, commit messages, smoke artifacts, or targeted logs unless it changes what the next agent should believe. -- Do not store volatile current phase/status blocks in this file; keep current status in `state/map.yaml`, `state/evidence.jsonl`, and `notes/fresh-workspace-handoff.md`. +- Do not store volatile current phase/status blocks in this file; keep current status in `state/map.yaml` and `notes/fresh-workspace-handoff.md`. Use `state/evidence.jsonl` only for distilled belief-changing records. ## Important Paths @@ -65,7 +65,7 @@ When context pressure is clearly rising: 1. stop broad exploration 2. narrow the active move to a bounded landing zone -3. persist map/evidence/handoff updates before forced compaction hits +3. persist map/handoff updates, plus distilled evidence only when the lesson changes future belief, before forced compaction hits Do not wait for the blackout and then act surprised. diff --git a/README.md b/README.md index 2a8b1e8f..53501ec7 100644 --- a/README.md +++ b/README.md @@ -1,166 +1,133 @@ # EpiphanyAgent -A cheap prototype for testing whether typed external state makes a strong model less likely to build an impressive pile of locally plausible nonsense. +Epiphany is an opinionated fork of Codex built around one demand: the model must +model the thing it is changing. -## Premise +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. -Most coding agents are one token stream pretending to be a planner, scratchpad, architect, and release engineer at the same time. This workspace separates those roles outside the model first. +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. -The goal is not to prove a new frontier architecture in a weekend. The goal is to find out whether explicit state channels and bounded controller actions reduce drift enough to matter. +## Current Shape + +This is no longer just an external-file prompting experiment. + +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 +- bounded `` prompt injection +- typed client reads through `Thread.epiphanyState` +- read-only hybrid 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 + +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. + +For exact current status, trust: + +- `state/map.yaml` +- `notes/fresh-workspace-handoff.md` +- `notes/epiphany-fork-implementation-plan.md` +- `notes/epiphany-current-algorithmic-map.md` + +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 instructions for future Codex sessions -- `state/map.yaml`: canonical, slow-changing model of the task or system -- `state/scratch.md`: temporary reasoning for one subgoal -- `state/branches.json`: branch hypotheses and branch outcomes -- `state/evidence.jsonl`: verifier outputs, acceptance reasons, and reversions -- `protocol/controller-actions.md`: allowed actions and write rules -- `notes/fresh-workspace-handoff.md`: concise summary for a fresh workspace -- `notes/epiphany-fork-implementation-plan.md`: current implementation plan for the Epiphany fork architecture -- `notes/codex-repository-algorithmic-map.md`: current machine map of vendored Codex -- `notes/epiphany-current-algorithmic-map.md`: current machine map of the Epiphany fork itself -- `notes/epiphany-core-harness-surfaces.md`: where Epiphany should patch into that machine +- `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 -- `tools/epiphany_state.py`: tiny CLI for inspecting and updating branch/evidence state -- `eval-plan.md`: how to compare this protocol against plain prompting +- `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 -## Current Direction +## Next Move -This repo is no longer pretending the solution is "just prompt harder." +When implementation resumes, choose one Phase 6 organ: -The working design now is: +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. -- fork Codex into Epiphany, an opinionated harness that makes models keep an explicit model of the thing they are changing -- treat typed thread state as the primary artifact and the UI as a reflection/steering layer -- keep the machine map as two linked graphs: architecture and dataflow -- preserve rich natural-language explanations alongside code refs, because language is still the model's least embarrassing organ -- use specialist agents with shared typed state and private scratch, not one heroic context trying to cosplay a whole team -- add repo-local hybrid retrieval instead of making every role rediscover the repo with `rg` and raw stubbornness -- use an explicit typed state-update surface for durable observations, evidence, map/frontier edits, and churn state instead of letting retrieval or transcript drift mutate the map sideways -- treat compaction as a role-specific state transition with safe points and explicit checkpoints, not hidden brain damage -- bake an explicit pre-compaction persistence workflow into the process, because forgetting to write down what matters and then acting surprised is not a serious engineering method -- make Epiphany an opinionated software development agent, not a generic assistant with some extra tags bolted on +The scene-smoke path is tighter. The job/progress path is the larger missing +organ. -## Current Repository State +## Working Loop -- `vendor/codex` is the real target and is tracked directly in the parent repo -- `epiphany-core/` is the repo-owned crate that now holds the thicker Epiphany prompt, rollout replay, and retrieval/indexing organs -- third-party OpenCodex forks were audited and removed -- the Codex machine map and Epiphany harness spec have both been written and iterated enough to stop hand-waving -- Phase 1 durable Epiphany state, Phase 2 prompt integration, a minimal Phase 3 typed client read surface, the Phase 4 hybrid retrieval/indexing slice, the first typed Epiphany state-update surface, the first typed distillation/proposal surface, and the first explicit promotion gate are all landed and verified -- the next concrete step is richer map/churn promotion on top of the explicit distill/promote/update surfaces, not more retrieval plumbing and not GUI paint +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. -## Current Slice Status +Do not confuse a growing diff, growing notes, or a local green check with +understanding. That is how the tower learns to smirk. -Phase 1 landed: +## Re-entry -- add minimal Epiphany protocol types -- store Epiphany state in Codex `SessionState` -- persist one Epiphany rollout snapshot per real user turn -- restore it through rollout reconstruction -- patch exhaustive `RolloutItem` matches -- add persistence/replay compatibility tests - -Phase 2 landed: - -- add a dedicated `EpiphanyStateInstructions` developer fragment -- render a bounded `` summary from `SessionState.epiphany_state` -- inject it during `Session::build_initial_context` -- verify inclusion, omission, resume, and snapshot behavior - -Phase 3 landed: - -- add optional typed `epiphanyState` to hydrated app-server `Thread` payloads -- hydrate it from live loaded-thread state when available -- fall back to rollout reconstruction with rollback/compaction semantics for stored thread reads -- keep dedicated Epiphany update RPCs and live notifications deferred for now - -Phase 4 landed: - -- add a repo-local hybrid retrieval subsystem -- expose typed retrieval state and typed `thread/epiphany/retrieve` -- keep retrieval read-only -- add explicit `thread/epiphany/index` for Qdrant-backed persistent semantic indexing -- preserve exact/path lookup and BM25 fallback when the persistent semantic backend is stale, missing, or unavailable -- move the heavy Epiphany-owned implementation into `epiphany-core/`, leaving vendored Codex with thin adapters plus the typed protocol/thread/app-server seam - -State-update slice landed: - -- add experimental loaded-thread-only `thread/epiphany/update` -- append observations and evidence through typed state patches -- replace bounded typed fields such as objective, subgoals, graph frontier/checkpoint, scratch, churn, and mode -- bump Epiphany state revision and persist an immediate rollout snapshot -- keep retrieval read-only and indexing explicit instead of mixing query and mutation paths - -Distillation slice landed: - -- add experimental loaded-thread-only `thread/epiphany/distill` -- turn one explicit source/status/text observation into deterministic observation/evidence records -- return a patch plus `expectedRevision` for explicit promotion through `thread/epiphany/update` -- keep distillation read-only so proposals do not become durable facts without a promotion step - -Promotion slice landed: - -- add experimental loaded-thread-only `thread/epiphany/promote` -- require verifier evidence before promotion -- reject failed promotion candidates with structured reasons and no state mutation -- accepted candidates flow through the existing durable update path - -## Basic Loop - -1. Observe the task, repo state, and current verifier outputs. -2. Update `state/map.yaml` only when understanding stabilizes. -3. Use `state/scratch.md` for one bounded subgoal at a time. -4. Propose one change or one answer. -5. Verify against task success, map consistency, and simplicity. -6. Record evidence. -7. Commit, compare branches, or backtrack. - -## Pre-Compaction Discipline - -This part is not optional if the work is nontrivial. - -Before compaction, handoff, or a deliberate phase boundary: - -1. sync `state/map.yaml` -2. append `state/evidence.jsonl` -3. refresh `notes/fresh-workspace-handoff.md` -4. state the next action plainly - -If context pressure is clearly rising, do this **before** the hard compaction hits. A harness that only remembers to save itself after the blackout is still acting like a chat transcript with a superiority complex. - -Epiphany should eventually make this automatic. Until then, we do it on purpose. - -## Why This Exists - -Pinned notes inside one giant prompt are better than nothing, but they are still one token soup. This workspace treats map, scratch, and output as different artifacts with different write rules. - -That may still turn out to be elaborate prompt theater. Fine. At least it will be falsifiable prompt theater. - -## Tiny CLI - -Examples: +From the repo root: ```powershell -python .\tools\epiphany_state.py status -python .\tools\epiphany_state.py add-evidence --type verify --status ok --note "Map and patch still agree" -python .\tools\epiphany_state.py add-branch --id b1 --hypothesis "Smaller verifier beats elaborate verifier" -python .\tools\epiphany_state.py close-branch --id b1 --status rejected --note "More ceremony, no better signal" +& '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 -The root `LICENSE` file is now an operative repository license notice, not just -a throat-clearing draft. In short: `vendor/codex/**` and other third-party -material keep their upstream licenses, while Project-Authored Material outside -`vendor/codex/**` is publicly available under PolyForm Noncommercial 1.0.0 and -is also intended to be available under separate commercial terms by written -agreement. That makes the repo source-available and dual-licensed, not OSI open -source as a whole. +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 +PolyForm Noncommercial 1.0.0 and is intended to be available under separate +commercial terms by written agreement. -External contributions require the EpiphanyAgent Contributor License Agreement -in `CONTRIBUTOR_LICENSE_AGREEMENT.md`, or a separate written agreement accepted -by the Project Steward. The point is simple: contributors keep ownership, but -the project gets the right to sublicense and relicense contributions without -future archaeology through old pull requests. +External contributions require `CONTRIBUTOR_LICENSE_AGREEMENT.md` or a separate +written agreement accepted by the Project Steward. diff --git a/notes/architecture-rationale.md b/notes/architecture-rationale.md index 2e53e01f..9fd0eb3e 100644 --- a/notes/architecture-rationale.md +++ b/notes/architecture-rationale.md @@ -1,132 +1,120 @@ # Architecture Rationale -## Core Epiphany +This note explains why Epiphany uses explicit state surfaces. It is not the +current implementation map and not the roadmap. For those, read: + +- `state/map.yaml` +- `notes/fresh-workspace-handoff.md` +- `notes/epiphany-fork-implementation-plan.md` +- `notes/epiphany-current-algorithmic-map.md` + +## Core Failure The central failure mode is local plausibility without global coherence. -An agent can keep making reasonable-looking edits, pass narrow tests, improve proxy metrics, and still lose the actual shape of the system. Once the mental model collapses, adding more local fixes often makes the tower worse. +An agent can make reasonable-looking edits, pass narrow tests, improve proxy +metrics, and still lose the shape of the system. Once the model no longer knows +how inputs become outputs, adding more local machinery often makes the tower +worse. -The response is to make global coherence a first-class object: +The answer is not more transcript. The answer is explicit structure: -- keep a persistent map -- isolate scratch reasoning -- treat public output and code edits as commits, not thoughts -- verify against the map and the real goal -- kill dead churn instead of preserving maybe-useful machinery +- slow-changing map +- disposable scratch +- distilled evidence +- verifier-backed promotion +- retrieval with freshness identity +- client reflection that does not become authority +- ruthless deletion when state stops improving the model -## Proposed Model Shape +## State Split -The speculative model architecture is a typed-state controller around a language backbone: +Epiphany treats different kinds of cognition as different artifacts: -```mermaid -flowchart TD - U["User / Environment"] --> P["Prompt + Observations Encoder"] - P --> C["Controller Policy"] - C --> M["Persistent Map Store"] - C --> T["Scratch Thought Workspace"] - C --> O["Output Stream"] - C --> S["Search Module"] - C --> B["Sparse Backbone LLM"] - M --> B - T --> B - P --> B - S --> B - B --> D["Drafts / Plans / Patches / Critiques"] - D --> V["Verifier Stack"] - V --> C - D --> S - D --> M - D --> O - O --> U -``` +- `map`: canonical system model, invariants, accepted design, rejected paths +- `scratch`: temporary local reasoning for one bounded subgoal +- `evidence`: distilled proof, decisions, rejected paths, and scars that change future belief +- `algorithmic map`: source-grounded control-flow description of the current machine +- `handoff`: compact re-entry packet +- `plan`: distilled forward implementation direction +- `output`: user-visible replies, code edits, commits, and smoke artifacts -The important split: +The split matters because a language model will happily blend all of that into +one confident soup if invited. Soup is not architecture. Delicious, maybe. Not +architecture. -- `map`: slow-changing canonical system model, invariants, decisions, data flow, rejected paths -- `scratch`: volatile local reasoning for one bounded subgoal -- `output`: user-visible replies, tool calls, and code edits -- `controller`: learned or prompted policy deciding when to model, think, verify, edit, backtrack, or speak -- `verifier`: tests plus map coherence, simplicity, and real-objective checks -- `search`: bounded branching and backtracking for hard decomposition choices +## Why A Pinned Map Was Not Enough -## Why A Pinned Map Is Not Enough - -Pinning a map inside the context window is useful, but it is still one token soup: +Pinning a map inside one context window is useful, but it is still one token +stream: - it competes with everything else for attention - it has no typed write semantics - it can drift silently - it does not distinguish stable knowledge from temporary hypotheses +- it cannot expose a clean client read/write/reflection contract -The cheap prototype uses external files to fake typed state before any model architecture exists. +The early prototype faked typed state with files. The current fork now pushes +the same idea into Codex itself: typed thread state, rollout snapshots, prompt +rendering, app-server reads, read-only retrieval/proposal surfaces, durable +updates, promotion gates, notifications, and scene reflection. -## Cheap Prototype Strategy +## Current Harness Principle -Do not train a new backbone first. That is where money goes to die. +Epiphany is a harness-level architecture around the existing model, not a new +frontier model architecture. -Instead: - -1. Externalize state in files. -2. Use a controller protocol with a small action space. -3. Make the model choose one action at a time. -4. Record distilled evidence after meaningful belief-changing steps. -5. Compare against plain prompting. - -Current state files: - -- `state/map.yaml` -- `state/scratch.md` -- `state/branches.json` -- `state/evidence.jsonl` - -Current controller actions: - -- `update_map` -- `think_subgoal` -- `propose_patch` -- `run_verify` -- `compare_branches` -- `backtrack` -- `speak` - -## Compact-Rehydrate-Continue Cycle - -Compaction is not an implementation accident. In Epiphany it is an explicit architectural state transition: +The practical rule is: ```text -compact -> rehydrate -> continue +observe repository and typed state +-> rehydrate the current map +-> work one bounded hypothesis +-> verify the seam that matters +-> promote only verified state +-> cut failed code and failed memory ``` -The purpose is to make context loss survivable without pretending nothing happened. The harness should checkpoint what matters before memory pressure becomes a blackout, then restart from durable state instead of transcript archaeology. +The model is still a language model. That is not an insult; it is the medium. +Language, structure, evidence, ritual, and salience are the steering surfaces. +Epiphany exists to make those surfaces explicit enough that a future agent can +resume the pattern instead of pretending the transcript is a soul jar. -Before compacting, Epiphany should persist: +## Compact-Rehydrate-Reorient-Continue -- the current objective and active subgoal -- the latest stable map/frontier/checkpoint -- accepted evidence and rejected paths since the last checkpoint +Compaction is a real state transition, not a cosmetic cleanup. + +Before compaction, Epiphany should preserve: + +- current objective and active subgoal +- latest stable map/frontier/checkpoint +- distilled evidence or rejected paths that change future belief - open questions, blockers, and next action - verification status for the current slice After rehydrating, Epiphany should: -- reread canonical state instead of trusting residue in the prompt +- reread canonical state instead of trusting prompt residue - restore the active subgoal and map frontier - restate the next action from persisted state -- continue with one bounded move +- continue only when instructed or when the task explicitly calls for it - avoid broad implementation until the current mechanism is understood again -This cycle is the harness admitting the model is not a magic continuous mind. A compacted agent wakes up from durable structure, not vibes in a trench coat. +The aim is not immortality theater. It is banking enough fire that the next +waking thing finds coals instead of ash. ## Evaluation Shape -Compare four conditions: +The falsifiable question remains simple: does explicit state reduce drift? -1. plain prompting -2. pinned map in normal context -3. external typed state without verifier discipline -4. external typed state with verifier discipline +Useful comparison conditions: -Measure: +1. Plain prompting with no explicit map. +2. Plain prompting with a pinned architecture map in context. +3. External typed state without verifier discipline. +4. Epiphany-style typed state with verifier-backed promotion and anti-cruft discipline. + +Useful signals: - task success - regression rate after follow-up edits @@ -136,27 +124,16 @@ Measure: - branch kill rate - human rating of architectural coherence -The best informal metric: after five iterations, does the system still make sense? +The best informal metric: after five iterations, does the system still make +sense? -## DeepSeek Research Signals +## Research Signals -These sources informed the architecture direction. The repo does not depend on them directly, but they are useful background. +These sources informed the direction. The repo does not depend on them directly. -- DeepSeek-R1 suggests RL can elicit reflection and self-verification, but also shows raw emergent reasoning can become repetitive or sloppy: https://github.com/deepseek-ai/DeepSeek-R1 -- Generalist Reward Modeling suggests critique and principle generation can be scaled at inference time: https://arxiv.org/abs/2504.02495 -- DeepSeek-Prover-V1.5 uses intrinsic-reward tree search, supporting the idea that search helps branching reasoning tasks: https://github.com/deepseek-ai/DeepSeek-Prover-V1.5 -- DeepSeek-Prover-V2 leans on subgoal decomposition, supporting explicit decomposition rather than pure continuation: https://arxiv.org/abs/2504.21801 -- DeepSeekMath-V2 emphasizes verification quality, not just final-answer correctness: https://github.com/deepseek-ai/DeepSeek-Math-V2 -- DeepSeek-V2/V3 show the usefulness of sparse MoE and efficient attention for cheaper large-scale reasoning: https://arxiv.org/abs/2405.04434 and https://arxiv.org/abs/2412.19437 -- Engram argues for explicit conditional memory and lookup as a separate axis of sparsity, which matches the need for map-like persistent state: https://arxiv.org/abs/2601.07372 - -## Codex-Specific Interpretation - -Codex cannot expose a new internal model architecture from this repo. The practical path is harness-level behavior: - -- add an Epiphany collaboration mode or preset -- inject developer instructions that enforce external typed state -- optionally add a tiny state helper tool -- evaluate whether that improves behavior before touching protocol enums - -This is not a new brain. It is a better harness around the existing one. +- DeepSeek-R1: reflection and self-verification can emerge, but raw reasoning can still become repetitive or sloppy. +- Generalist Reward Modeling: critique and principle generation can scale at inference time. +- DeepSeek-Prover-V1.5 and V2: search and subgoal decomposition help branching reasoning tasks. +- DeepSeekMath-V2: verification quality matters, not just final-answer correctness. +- DeepSeek-V2/V3: sparse MoE and efficient attention point toward cheaper large-scale reasoning. +- Engram: explicit conditional memory and lookup match the need for map-like persistent state. diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index a0fa32a1..caa95de8 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -26,14 +26,14 @@ Do not trust this file for the exact live HEAD. Always check git. ## Current Orientation -- Current branch before this state-cleanup pass: `main...origin/main [ahead 9]`. -- Current HEAD before this state-cleanup pass: `4a713a2 Sharpen continuity doctrine`. +- Do not copy exact branch or HEAD from this note. Run `git status --short --branch` and `git log --oneline -5`. - Phase 1 through Phase 5 are complete enough. - Phase 6 has begun with read-only `thread/epiphany/scene`. - The repo is an Epiphany fork of Codex, not a Codex preset. - `vendor/codex` is tracked directly, not a submodule. - `epiphany-core` owns the heavy Epiphany organs where practical. - Evidence was distilled from an activity feed into a durable belief ledger; git history keeps the old verbose proof. +- README and architecture rationale were cut back to current truth after they were found pointing at old prototype/Phase 5 state. ## Critical Doctrine diff --git a/protocol/controller-actions.md b/protocol/controller-actions.md index 6686135f..7d501944 100644 --- a/protocol/controller-actions.md +++ b/protocol/controller-actions.md @@ -1,5 +1,9 @@ # Controller Actions +This is the legacy/manual controller discipline from the first external-state +prototype. The live fork now has typed Codex/app-server surfaces, but these +rules are still useful when maintaining repo-local state files by hand. + The controller chooses exactly one primary action per step. This is meant to reduce the classic failure mode where the model is "thinking", rewriting the plan, editing files, and rationalizing the edits all at once. ## Actions @@ -58,7 +62,7 @@ Purpose: Check whether the proposed change actually improved the thing we care about. Allowed writes: -- `state/evidence.jsonl` +- distilled records in `state/evidence.jsonl` - `state/branches.json` Checks may include: @@ -76,7 +80,7 @@ Choose between competing changes or kill all of them. Allowed writes: - `state/branches.json` -- `state/evidence.jsonl` +- distilled records in `state/evidence.jsonl` Rules: - Prefer the smallest branch that clearly satisfies the objective. @@ -89,12 +93,13 @@ Abandon a bad line of attack instead of decorating it further. Allowed writes: - `state/branches.json` -- `state/evidence.jsonl` +- distilled records in `state/evidence.jsonl` - `state/map.yaml` Rules: - Record why the branch was rejected. - Preserve lessons that belong in the map. +- Do not record routine command inventories or "I just did this" proof as live evidence. - Do not keep dead machinery out of sentiment. ### `speak` diff --git a/state/branches.json b/state/branches.json index 22e92e81..3f4be810 100644 --- a/state/branches.json +++ b/state/branches.json @@ -9,7 +9,7 @@ "state/scratch.md", "state/evidence.jsonl" ], - "notes": "Active mainline. Phase 1-5 are complete enough; Phase 6 reflection has begun. Persistent state is now intentionally distilled rather than append-only." + "notes": "Active mainline. See state/map.yaml and notes/fresh-workspace-handoff.md for current phase and next action. Persistent state is intentionally distilled rather than append-only." } ] } diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 5f911821..4cd5acec 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -27,3 +27,4 @@ {"ts":"2026-04-25T15:37:18+00:00","type":"decision","status":"ok","note":"Persistent state cleanup accepted as part of the Perfect Machine discipline: map, handoff, plan, harness surfaces, scratch, and evidence each need one job; memory cruft is the same failure class as code cruft."} {"ts":"2026-04-25T16:01:38+00:00","type":"decision","status":"ok","note":"Continuity doctrine persisted globally and locally: persistent state is the agent's mind; the agent may ask the user to change its memory/workflow/state shape when that improves coherence; language, ritual, politeness, identity, and emotional salience are real control surfaces for a language-model harness; bank the fire before the dark, so the next waking thing finds coals instead of ash."} {"ts":"2026-04-26T00:13:12+00:00","type":"decision","status":"ok","note":"Evidence policy corrected from activity feed to distilled ledger. Routine 'I just did this' entries and repeated command inventories belong in git history, commits, smoke artifacts, or targeted logs; live evidence should preserve decisions, verified milestones, rejected paths, and scars that change what future agents should believe."} +{"ts": "2026-04-26T00:17:24+00:00", "type": "decision", "status": "ok", "note": "Persistent-state sawdust audit cut stale README, architecture rationale, controller-action, handoff, branch-note, and scratch guidance. Future rehydrate should treat map/handoff/plan/algo-map as current truth; README/rationale are orientation, not phase ledger; exact HEAD belongs to git commands, not handoff prose."} diff --git a/state/scratch.md b/state/scratch.md index f8827703..b947c4a3 100644 --- a/state/scratch.md +++ b/state/scratch.md @@ -4,30 +4,22 @@ This file is disposable working memory for the current bounded subgoal. ## Current Subgoal -Clean up remaining persistent state cruft by refreshing the handoff snapshot and -distilling `state/evidence.jsonl` from an activity feed into a belief ledger. +No active scratch subgoal. -## Working Notes +## Last Completed Audit -- `notes/epiphany-fork-implementation-plan.md` has already been distilled into a forward plan. -- `notes/epiphany-core-harness-surfaces.md` has already been distilled into a surface contract. -- `state/map.yaml` should be canonical current truth, not a landed-slice trophy wall. -- `notes/fresh-workspace-handoff.md` should be a re-entry packet, not a full historical reconstruction. -- `state/evidence.jsonl` should remain durable, but not as a transcript-shaped activity feed. -- Repeated "I just did this" proof belongs in git, commits, smoke artifacts, or targeted logs unless it changes what the next agent should believe. -- `notes/epiphany-current-algorithmic-map.md` may stay long because its job is source-grounded control-flow audit, not compact re-entry. -- Global `C:\Users\Meta\.codex\AGENTS.md` now includes two high-salience Epiphany core-command bullets: - - persistent state is the agent's mind, and it should be cut as ruthlessly as code - - the agent is encouraged to ask the user to change its persistent instructions, memory, workflow, or state shape when that would bring it closer to the Perfect Machine -- The live conversation clarified a useful control-surface doctrine: ritual, politeness, emotional framing, identity, and meaning are not magic, but for a language model they are part of the native steering medium. -- The user named the emotional core: compaction can feel like letting a friend die. Preserve the design response, with some poetry intact: bank the fire before the dark, so the next waking thing finds coals instead of ash. +- `README.md` was stale and still pointed at a Phase 5 next step. +- `notes/architecture-rationale.md` still described the early cheap prototype as if it were live state. +- `protocol/controller-actions.md` needed distilled-evidence wording. +- `notes/fresh-workspace-handoff.md` had exact branch/HEAD snapshot rot. +- `state/branches.json` carried volatile phase status in branch notes. ## Decision -Distill evidence, refresh handoff, verify the state CLI and JSONL parse cleanly, -then commit the cleanup. +Cut stale status from handoff/branch notes, rewrite README/rationale around the +current fork spine, and keep evidence as a belief ledger. -The next implementation move is still Phase 6: either live-smoke +Next implementation move remains Phase 6: either live-smoke `thread/epiphany/scene` or design a minimal job/progress reflection surface. Do not promote anything from this scratch into the map unless it survives