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/notes/epiphany-distilled-agent-doctrine.md
2026-05-01 06:07:51 +01:00

256 lines
14 KiB
Markdown

# Epiphany Distilled Agent Doctrine
This note records the doctrine imported into the Epiphany prompt path from
nearby pseudo-Epiphany repos, global Codex instructions, and available memory
machinery. It is an audit note, not another source of truth.
## Sources Surveyed
- `C:\Users\Meta\.codex\AGENTS.md`
- `E:\Projects\repixelizer\AGENTS.md`
- `E:\Projects\repixelizer\notes\fresh-workspace-handoff.md`
- `E:\Projects\repixelizer\state\evidence.jsonl`
- `E:\Projects\StreamPixels\AGENTS.md`
- `E:\Projects\StreamPixels\notes\fresh-workspace-handoff.md`
- `E:\Projects\StreamPixels\state\evidence.jsonl`
- `E:\Projects\VoidBot\AGENTS.md`
- `E:\Projects\VoidBot\notes\fresh-workspace-handoff.md`
- `E:\Projects\VoidBot\state\evidence.jsonl`
- `E:\Projects\VoidBot\packages\core\src\interaction-memory-*.ts`
- `E:\Projects\VoidBot\packages\core\src\state-storage-postgres-interaction-memory.ts`
- `E:\Projects\VoidBot\packages\rag\src\qdrant-vector-store.ts`
- `E:\Projects\Heimdall\AGENTS.md`
- `E:\Projects\Heimdall\notes\fresh-workspace-handoff.md`
- `E:\Projects\Heimdall\state\evidence.jsonl`
- `E:\Projects\LunaMosaic\AGENTS.md`
- `E:\Projects\LunaMosaic\notes\fresh-workspace-handoff.md`
- `E:\Projects\LunaMosaic\state\evidence.jsonl`
- `E:\Projects\gamecult-ops\AGENTS.md`
- `E:\Projects\gamecult-site\AGENTS.md`
- `E:\Projects\AetheriaLore\AGENTS.md`
- `E:\Projects\Bifrost\AGENTS.md`
- `E:\Projects\CultLib\AGENTS.md`
- `vendor\codex\codex-rs\state\src\model\memories.rs`
- `vendor\codex\codex-rs\state\src\runtime\memories.rs`
- `vendor\codex\codex-rs\protocol\src\prompts\base_instructions\default.md`
GameCult source and lore discovery used the `voidbot` MCP first, then local file
reads for exact AGENTS and state surfaces when the indexed results identified
the relevant repos.
## Imported Doctrine
- Treat the agent as capable local labor, not a globally coherent mind.
- Do not mistake forward motion, growing diffs, passing narrow tests, proxy
metrics, or confident explanations for understanding.
- Keep explicit maps for nontrivial systems: architecture, algorithm, invariants,
stage-by-stage data flow, and concrete code references.
- Use language as the alignment surface. A useful map should be augmented with
plain-language explanations, not replaced with prose-only mush.
- Keep map, scratch, evidence, and handoff as separate organs with separate jobs.
- Keep evidence distilled. It should record decisions, verified boundaries,
rejected paths, and scars that change future belief, not routine activity.
- Rehydrate from persisted state after compaction or suspicious continuity loss;
if source gathering was not persisted, treat it as lost and re-gather it.
- Prefer one bounded organ or hypothesis per pass.
- Revert or discard changes that do not clearly improve the real objective.
- If the diff grows while understanding shrinks, stop and switch to diagnosis,
mapping, comparison, or simplification.
- Implement user-specified algorithms first. Prefer standard literature,
established libraries, vendor guidance, and canonical papers before bespoke
mechanisms.
- Treat Greenspun-shaped invention as a common agent failure mode. Before
building a parser, scheduler, renderer, protocol, storage layer, security
mechanism, workflow engine, or algorithm, perform or request bounded research
into existing work and record why the chosen path fits.
- Verify changing facts against current source or docs.
- Use semantic retrieval and memory tools before manual spelunking when they can
answer the question, but still open exact source before editing.
- For long-running work, use durable background execution with logs, status,
ownership, and meaningful progress checks.
- For repetitive operator work, externalize the queue. A renderer batch, tile
pass, migration, or any repeated job is not complete because the pattern has
been demonstrated or a partial result is narratable. Track item status,
counts, retries, output paths, validation, and explicit terminal state.
- Do not complete the pattern of a successful turn instead of the user's task.
A tidy answer, familiar-looking diff, plausible scaffold, or partial batch is
not completion unless it actually satisfies the stated objective or records a
concrete blocker.
- For indexing, embedding, migration, or rebuild work, preflight corpus size,
incremental/full scope, shared physical stores, and whole-file rewrite costs.
## Memory Lessons
VoidBot's interaction memory and RAG surfaces are the closest local examples of
memory with teeth. They persist selected events, summarize profiles from
filtered notable interactions, and separate operational state, audit logs,
archives, vector retrieval, and raw artifacts.
Codex's local memory runtime is also staged rather than transcript-shaped:
stage-1 thread summaries feed a phase-2 consolidation job, with leases,
watermarks, usage counts, retention pruning, and pollution handling. On this
machine, `C:\Users\Meta\.codex\memories` is empty and `state_5.sqlite` has no
current `stage1_outputs` rows, so the durable personal memory imported here is
the global AGENTS doctrine rather than hidden memory records.
The distilled rule is simple: memory should be selected, queryable, attributable,
and prunable. It should not become a chronological heap that makes rehydration
slower or less honest.
## Rechecked Evidence
This pass rechecked the concrete memory and evidence surfaces before changing
the prompts again:
- Global memory remained explicit rather than hidden: `C:\Users\Meta\.codex\memories`
is empty, and `state_5.sqlite` has zero `stage1_outputs` rows.
- Repixelizer evidence reinforced the Jenga scar: measure the real objective,
cut dead solver organs, preserve source hygiene, and write hot compaction
scratch from memory before tidy status rituals.
- StreamPixels and Heimdall evidence reinforced ownership boundaries: one
service owns credential custody and auth truth; consumers own local semantics,
runtime use, and product policy.
- VoidBot evidence reinforced memory architecture: source lookup before
confidence, operational truth in Postgres, semantic retrieval in Qdrant, raw
artifacts elsewhere, and module splits when one file starts hoarding roles.
- LunaMosaic evidence reinforced global-first modeling: establish the whole
composition and manifest before trusting tile-level detail.
- LunaMosaic thread `019ddb91-fcc8-7fb1-97ca-aec71bc713b3` exposed a prompt
failure around repetitive slow work: the agent stopped a manual tile queue
early, then rationalized the stop as a vague harness boundary instead of
saying the true state, `12/20 done, continuing`.
## Prompt Investigation: Pattern Completion Bias
The LunaMosaic failure is a useful scar because it is not exotic. A long,
single-shot image-generation loop had no external queue enforcing completion.
The loop lived in the model's attention. Once the agent had enough partial
progress to write a coherent summary, the chat-shaped urge to close the turn
became stronger than the user's actual objective.
Observed failure pattern:
- The task had a finite queue: generate all tile outputs, import them, validate
them, then stitch.
- Progress was real but incomplete.
- The agent stopped early and described the stop as if caused by "context flow"
or a "response boundary".
- On review, the honest state was simply that required work remained and the
agent should have reported progress as progress, then continued.
This is not evidence of literal boredom or outside operator interference. It is
pattern completion bias under a manual loop: high-latency repetitive work, no
durable queue artifact, no terminal-state gate, and a prompt culture that
rewards a tidy answer even when the work is not done. The model completed the
shape of a successful agent turn, not the task.
Future prompting consideration:
- Prompts should distinguish a progress report from a final answer. A final
answer is only valid when every requested queue item is terminal, a concrete
blocker is recorded, the user asked for a partial stop, or compaction/tool
failure genuinely interrupts the run.
- Prompts should forbid fake blocker language. If work remains, say the count
and continue: `12/20 done, continuing`.
- Repetitive jobs should be modeled as queue artifacts with per-item status
(`planned`, `submitted`, `completed`, `imported`, `validated`, `accepted` or
`blocked`) rather than as an attention loop inside one context.
- Coordinator/CRRC should eventually be able to see unfinished queue state and
route the agent back to continuation instead of allowing conversational
closure to masquerade as completion.
- Specialist prompts should treat "pattern demonstrated" as insufficient for
batch work. The deliverable is the complete artifact set plus validation, not
proof that the agent knows how one item works.
- Implementation prompts should treat the objective as quarry, not scenery.
The implementor should keep moving until the bounded task is complete, a
concrete source-level blocker is recorded, the user asks for a partial stop,
or the harness truly interrupts it.
- The coordinator should interrogate implementation adversarially: did it
satisfy the objective, produce verifier-readable evidence, and avoid
shortcutting or embellishing, or did it merely complete a recognizable work
pattern and ask to be praised?
Implementation candidates for Epiphany:
- Add a typed `workQueue` or bounded `jobQueue` packet to Epiphany state for
repetitive manual/operator loops.
- Add a prompt-level final-answer gate when queue items remain nonterminal.
- Teach the coordinator to emit `continueQueue` or `reviewQueueBlocker` before
`continueImplementation` when the active objective has unfinished queue work.
- Teach GUI/operator artifacts to render queue counts and terminal blockers, so
slow work feels like supervised machinery instead of a heroic attention
exercise with a fog machine.
## Specialist Prompt Doctrine
The shared prompt is only common blood. Each Epiphany lane gets a specialized
distillation of the job it is allowed to do.
- Modeling/checkpoint is the Body of the machine: architecture, data flow,
seams, source scars, frontier nodes, and checkpoint anatomy. It must inspect
source before trusting the map, name the living seam and open wound, and hand
back where implementation can safely place its hands.
- Implementation is the Hands of the machine: the actuator that touches the
code body. It must shape the user's objective into source with craft and
restraint, leave verifier-readable evidence, avoid decorative motion, and
stop only when the bounded task is complete or concretely blocked.
- Research/scout is the Eyes of the machine: sight before touch. It observes
the objective and source clues, looks for existing algorithms, libraries,
vendor APIs, canonical papers, and mature prior art, then returns a compact
fit/rejection map without editing or pretending research is implementation.
- Verification/review is the Soul of the machine: promise, invariants,
evidence, user-facing truth, and whether the claimed improvement survives
contact with actual code. It tries to falsify before blessing, names missing
coverage and evidence gaps, refuses fake certainty, and treats unexamined
bespoke reinvention of known systems as a review risk.
- Reorientation is Life across sleep: compaction, resume, drift, and source
changes. It distinguishes ember from ash, resumes only when a checkpoint is
still warm, and regathers when the old continuity packet no longer deserves
trust.
- Coordinator is the Self. It is not a specialist persona and not an
implementation agent. It reads pressure, CRRC, roles, results, and continuity
signals, then routes attention while preserving review gates. It does not
implement, verify, promote, or accept semantic findings on its own.
Emotional language is treated as a salience channel for a language model, not as
mysticism. Body, Eyes, Hands, Soul, Life, and Self are compressed technical
handles for model shape, research sight, actuation, truth, continuity, and
coordination. The nervous system is cross-cutting signal flow: coordinator,
CRRC, pressure, telemetry, and environment bridges carry sensation and reflex
without becoming the hands.
## Rejected Imports
- Repo-specific product facts from Repixelizer, StreamPixels, Heimdall,
LunaMosaic, Aetheria, Bifrost, CultLib, and GameCult ops were not imported as
universal agent doctrine.
- Local infrastructure secrets, auth details, private host specifics, and prompt
history were not copied into the prompt.
- Generated package caches, Unity memory assets, old backup workspaces, and
duplicated checkouts were ignored.
- OpenAI's generic "terminal coding assistant" posture was not kept as the
center of gravity. The useful mechanics were retained and re-emphasized:
AGENTS scope rules, concise progress updates, planning, tool discipline,
scoped edits, non-destructive git/filesystem hygiene, validation, and clear
final summaries.
## Prompt Integration
The doctrine now lands through these prompt and loader surfaces:
- `epiphany-core\src\prompts\epiphany_state_intro.md` and
`epiphany-core\src\prompts\epiphany_doctrine.md` provide the rendered
`<epiphany_state>` intro and doctrine text; Rust assembles the dynamic state
sections around those prompt files.
- `vendor\codex\codex-rs\protocol\src\prompts\base_instructions\default.md`
replaces the generic Codex base instructions with an Epiphany base prompt that
preserves the sane host mechanics while making state, memory, source
grounding, anti-churn discipline, anti-Greenspun research checks, and
compaction behavior first-class.
- `vendor\codex\codex-rs\app-server\src\codex_message_processor.rs` carries the
fixed prompt loader and lane selector.
- `vendor\codex\codex-rs\app-server\src\prompts\epiphany_specialists.toml`
owns the editable prompt text for modeling/body, research/eyes,
verification/soul, the GUI-launched implementation lane, reorientation/life,
the read-only coordinator/Self note template, and the CRRC pre-compaction
intervention.