256 lines
14 KiB
Markdown
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.
|