GameCult/Eureka
Watch
9
0
Fork
You've already forked Eureka
 0
Code Issues Pull requests 3 Projects Releases Packages Wiki Activity Actions

Publish Eureka, the Claude Code faculty pipeline skill

Browse source 
Eureka is extracted from the Aetheria CultCache migration and is the Claude
Code counterpart of Epiphany. It covers the faculty loop, brief templates,
the cut map shape, the postmortem template, the worked example, a dated
comparison with Epiphany, and a changelog tying each rule to its evidence.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-15 20:15:10 +02:00
commit eea514aa31
9 changed files with 1061 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

21
LICENSE Normal file
View file

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Meta Vens
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

53
README.md Normal file
View file

@ -0,0 +1,53 @@
# Eureka
Eureka is a Claude Code skill. It runs foundation changes (migrations, rebuilds,
teardowns, cross-repo and cross-runtime work) as a faculty pipeline:
- **Self** routes the work.
- **Imagination** maps the cut.
- **Hands** executes one cut at a time.
- **Soul** tries to falsify what Hands promised.
- **Mind Steward** keeps memory honest.
- **The operator** rules on real forks.
It is the Claude Code counterpart of [Epiphany](https://github.com/GameCult/Epiphany)
and shares Epiphany's faculty vocabulary.
The pipeline was extracted from the Aetheria CultCache migration
(2026-09-12..15). In that migration, 29 of 32 independent Soul passes found real
defects that the implementing agent's own tests had passed.
`references/postmortem-cultcache.md` has the evidence, and
`references/changelog.md` records every change to the skill along with the
evidence behind it.
## Install
Clone into your Claude Code skills directory:
```bash
git clone https://github.com/GameCult/Eureka.git ~/.claude/skills/eureka
```
Claude Code discovers the skill by the `name` and `description` in `SKILL.md`.
## Layout
- `SKILL.md`: the pipeline (the faculties, the loop, Self's discipline, and
git/tooling rules).
- `references/briefs.md`: brief templates for Imagination, Hands, Soul, Mind
Steward and Eyes.
- `references/cut-map.md`: the shape of the target document and the cut map.
- `references/postmortem-template.md`
- `references/postmortem-cultcache.md`: the worked example.
- `references/epiphany-comparison-2026-09-15.md`: a dated, source-grounded
comparison with Epiphany.
- `references/changelog.md`
## Status
Eureka currently keeps pipeline state in committed documents and memory. A
campaign in Epiphany (`notes/eureka-pipeline-state-target.md`) is adding typed
pipeline state. Epiphany owns the schemas and admission. Each campaign's store
is committed in the repo where the task runs. A per-session `eureka-state` MCP
server lets Eureka agents admit and query that state. This skill will be rewired
to use it once that campaign lands.

277
SKILL.md Normal file
View file

@ -0,0 +1,277 @@
---
name: eureka
description: Eureka runs a foundation change as a faculty pipeline for Claude Code agents. It is the skill counterpart of Epiphany. The root agent acts as Self and routes the work. The target shape is written first, Imagination maps the cut, Hands executes one cut at a time, Soul verifies by trying to falsify what Hands promised, a Mind Steward keeps memory honest at phase boundaries, and the operator rules on real forks. Use it for any migration, rebuild, teardown, cross-repo or cross-runtime change, infrastructure swap, or multi-cut refactor, especially on shared GameCult substrate (CultLib, CultCache, CultNet, CultMesh, CultMath). Also use it when the operator says "Eureka", "map the cut", "Imagination pass", "Soul pass", "Hands", "mini Epiphany loop", or "make this migration look like the last one", or asks to plan and land a change too big for one diff, even without naming the pipeline.
---
# Eureka
Eureka is the pipeline used by Claude Code agents. It sits next to **Epiphany**,
the running organism in `F:\Projects\Epiphany`, and shares its faculty
vocabulary. The difference is substrate:
- **Epiphany** keeps its findings in typed, admitted state that can be queried
by exact filter. Semantic search over that state is planned through voidbot;
Epiphany removed her own vector stack in `856648de`.
- **Eureka** currently keeps them in committed docs (the target and the cut
map), subagent reports and memory files.
Giving Eureka agents typed state tools is the intended next step; see
`references/changelog.md`.
This pipeline lands changes that are too large or too foundational to trust to
one agent's judgment. It turns "migrate X" into a sequence of small, verified
ownership changes. Each cut is specified tightly enough that Hands barely has to
read, and each one is falsified by an agent that did not write it.
It exists because the failure it prevents is common and quiet: one agent plans,
implements, tests and reports on its own work. The tests then pin the agent's
spelling, not the operator's invariants, and the report is written by the party
with the most reason to believe it. In the Aetheria CultCache migration
(2026-09-12..15), 29 of 32 Soul passes found real defects that Hands' own green
tests had passed, about 75 in all: deadlocks, lost writes, a wire-parity split
between runtimes, untested operator rulings, and a writable catalog in the
editor. See `references/postmortem-cultcache.md` for the evidence.
## The faculties
Faculties are postures, not personalities. The root agent is **Self**. It routes
work, keeps the maps, commits the maps, and talks to the operator. Delegate every
other faculty to a subagent with its own brief. A faculty that grades its own
work has lost the point.
| Faculty | Runs against | Produces | Must not |
|---|---|---|---|
| **Imagination** | the Body (source, docs, probes), plus the target | the cut map: the target shape specified to `file:line` | commit code, choose a product fork silently |
| **Hands** | one cut of the map | small pushed commits, a report with evidence | redesign the spec, work around a fork, update the map |
| **Soul** | Hands' *executed* commits | findings, CONFIRMED or PLAUSIBLE, each with `file:line` and a failure scenario | edit, commit, or review a plan (a pass on a plan is Imagination) |
| **Mind Steward** | memory surfaces | named mutations and proposals | touch Body code, restate what an owner doc already records |
| **Eyes** (optional) | history, transcripts, logs | a facts file with evidence pointers | conclude or recommend |
| **Operator** | forks and product meaning | rulings | (not an agent) |
The operator's doctrine defines the faculties. Read the Soul and Imagination
lines of the operational litany in `~/.claude/CLAUDE.md`. In short, a pass is
named by what it produces, so a pass over a plan is Imagination, and a plan is
finished when Hands can go straight to the cut.
## The loop
### 0. Map the substrate, scope, target
- **Map the real substrate before you propose anything.** Run parallel read-only
exploration of the old system and the new one, of any prior attempts and why
they failed (git history, rollbacks), and of every consumer across repos.
- Write the **target document**: the ends, not the means. Name the invariants
that must survive (wire parity, one owner per decision, what the operator
refuses to lose), the canonical implementations, and what is explicitly **not**
a consumer. For example, AetheriaEve was "taxidermy", and saying so up front
saved every later pass from considering it.
- State the scope boundary out loud. The earlier Aetheria attempt failed because
it bundled cache, mesh, eve and daemons into one change. One foundation per
pipeline.
- Dispatch the Mind Steward before the first consequential action.
### 1. Imagination maps the cut
Brief an Imagination agent to produce the **cut map**: an ordered list of cuts
against the current Body. Each cut carries:
- repo and branch;
- **deletes first**, with exact paths and line counts;
- keeps and moves;
- adds;
- per-file changes with `file:line` against a named HEAD;
- an **authority map** for anything that changes ownership: owner, inputs,
outputs, derived state, forbidden writers, shared paths, deletion line;
- **verification**: exact builds, tests with the rule each one pins, negative
greps, and what only the operator can check;
- a subtraction-ledger estimate.
**Subtraction comes from a consumer audit of the public surface,** not from
taste:
- Count real use across every project the operator works in before sizing or
cutting a feature, not only one runtime's repos. Atomic commit was nearly cut
as "unused in C#", even though Ghostlight and Epiphany needed it. Call counts
decided whether compare-exchange was in scope.
- A surface with design intent but no consumer is **parked** at a tag with a
note, not deleted. SoA was parked at `parked/cultcache-soa`.
- A capability the operator has needed across projects is reshaped, not
removed, even when its current consumers are only tests.
- Where the operator's own original code exists, it is the style bar.
**Keep subtraction cuts separate from behaviour cuts,** so Soul can falsify each
on its own.
**Before specifying a domain concept, ask the operator what it is *for*.** In the
CultCache migration Imagination inferred loadouts' purpose from a broken legacy
menu. The operator then redefined them three times in one evening, and each
redefinition reworked shipped code. Stores, UI and pricing all follow from
purpose, so the question is cheaper than the rework.
**Design order as data, not as scheduling.** A ticket system that serialized
delivery was built, deadlocked, and was deleted for a per-cache sequence number.
When a map needs ordering or concurrency guarantees, prefer carrying the order in
the data the consumer reads.
Imagination must establish mechanism claims by running code: probes, scratch
builds, decoding a real file. It must not reason from names. A map built on
unprobed claims is where bad cuts come from. Real forks come back as **explicit
operator questions with a recommended option**, never chosen silently.
Iterate the map with further Imagination passes, not Soul passes, until Hands
could go straight to the cut. Commit the map; it is the durable record of the
means.
Templates are in `references/briefs.md` and `references/cut-map.md`.
### 2. Operator rulings
Bundle the open questions. Give each one options and a recommendation, and say
what depends on the answer. Record every ruling in the map, dated, with the
operator's words when they carry meaning the paraphrase would lose. When a ruling
supersedes an earlier one, mark the old text as history instead of leaving two
live designs.
Distinguish a real fork from a default. "Should I use the conventional thing" is
not a question. "3-5 are not decisions," as the operator put it, is the failure
of asking about non-decisions.
### 3. Hands executes one cut
Brief Hands with the cut's section of the map, the standing rulings restated
briefly, and the verification. The brief says:
- **Follow the spec, do not redesign.** If the Body contradicts the spec, fix the
smallest thing that keeps the spec's intent true and report the discrepancy. If
it is a real fork, **stop and report**.
- **Gaps are filled in their owner, never worked around locally.** If CultMath
lacks a function, CultMath gets it; the consumer does not grow a helper.
- **Delete before adding.** No shims, no compatibility layers the map did not
name.
- Small commits, each pushed, with explicit paths. See the git rules below.
- **Every operator ruling and every new rule gets a test that fails under its own
mutation.** Hands runs the mutations against the final spelling of the code and
restores afterwards.
- Report: commits (and which don't build), verification output, mutation
results, spec discrepancies, forks, structural delta. Hands never updates the
map.
Parallel Hands are fine when they touch different repos or worktrees. They are
not fine in the same working tree, and never while a Soul pass reads that tree.
### 4. Soul falsifies
Brief Soul on the exact commit range, with the operator invariants and Hands'
promises listed as claims to falsify. Point it at the specific places a shortcut
would hide. Soul:
- reruns builds, tests and captures itself instead of trusting the report;
- reruns a selection of Hands' mutations, and designs its own that are not plain
reverts;
- builds scratch probes to reach behaviour the tests cannot see: round-trip every
document type, decode a legacy file independently, compile the shader with the
real compiler, run the other runtime's decoder;
- checks the invariant at the layer where it would actually fail (wire bytes,
another runtime, the editor, the GPU), not only in the unit test;
- reports each finding as CONFIRMED or PLAUSIBLE, with `file:line`, a failure
scenario and severity, then lists the promises that held.
Soul works read-only. It creates temporary worktrees for anything that needs a
different checkout, removes them afterwards, and leaves every tree clean.
### 5. Triage and repeat
For each Soul finding, decide:
- **fix now:** brief Hands with the finding and the target shape;
- **operator fork:** ask, with a recommendation;
- **record as a follow-up:** the map gets the item, the file and the reason it can
wait.
Run Soul again on the fix batch. **Do not cap the Soul loop early on a foundation
cut.** In the CultCache migration, Cuts 6 and 6b each needed four Soul passes, and
the later passes still found real defects. Stop when a pass finds nothing that
blocks, or only findings the operator chooses to record.
When the same kind of finding recurs, the brief was missing context. Fix the
brief template, not only the instance. That is how "operator rulings each need
their own failing mutation" entered the Hands brief.
**A release or tag is a cut and gets its Soul pass before the tag is pushed.**
The CultCache release cut skipped Soul. Its stale DLLs, SHA-bound byte checks
and silently skipped publish jobs surfaced only after tags were out. CultLib
1.0.58 shipped a wire-parity defect that was found and corrected 74 minutes
later.
### 6. Land, record, steward
After each cut:
- Self updates the map's status header: what landed at which SHAs, what was
verified, what Soul found, what was recorded.
- Self reconciles the subtraction ledger against what actually landed. A miss is
allowed, but it must be explained. The CultCache core missed its size target
by roughly 1,200 lines, and nobody looked, because the ledger stopped being
updated after Cut 4.
- Self commits and pushes the map. Hands and Soul never touch it.
- At phase boundaries, a Mind Steward pass moves durable rulings to their owners,
retires superseded memory, and falsifies at least one persisted claim.
At the end, Self writes the postmortem (see `references/postmortem-template.md`)
and reconciles the target doc with the Body.
## Self's discipline
- **Keep the maps committed and current.** Hands will read stale text as live
design. After a ruling changes a design, sweep the map and the target doc for the
old version the same day.
- **One owner per decision, in code too.** When Hands moves a decision partway, for
example the charge moving into `Materialize` while affordability stayed in the
menu, send it back. Split authority is the defect Soul most often finds.
- **Relay findings plainly.** The operator reads Self's summaries, not the agent
reports. Say what broke, how it would fail, and what is being done.
- **Choose models by how critical the pass is.** Put the scarce strong model on
Imagination and on Soul passes over cuts that put the foundation at risk. Hands,
search, probes and stewards take the default model. A cheaper Soul model does not
soften its brief: it still attacks, invariants first. When Fable ran out
mid-migration, Opus carried every faculty and Soul still found the defects.
- **A subtraction budget is pressure, not a metric.** Say so when you set it, so
Hands knows escalating a miss with an argument is allowed. Treat a suspiciously
clean hit as a sign that unrelated code was deleted to meet the number.
- **Track Soul's hit rate, not the ceremony.** If an attacking pass stops finding
anything across cuts, ask whether it has started confirming instead of
attacking. Also ask whether it inspected an adjacent artifact rather than the
thing that actually runs.
- **Never claim an agent's result before its notification arrives.**
## Git and tooling rules (scars)
- **Stage explicit paths. Never `git add -A`.** It swept an untracked local
settings file into history.
- **Write commit messages with the Write tool to a uniquely named scratch file,
then `git commit -F`.** PowerShell 5 here-strings break `-m` quoting, and its
`Out-File`/`Set-Content` write a BOM into message files.
Shared filenames like `msg1.txt` collided between parallel agents.
- **Push at most three tags per push.** GitHub skips tag-triggered workflows when
one push carries more tags, so the npm and PyPI publish jobs silently never ran.
- **Keep release byte checks commit-independent.** Exclude the source revision
and Source Link from the version, build non-incrementally, and use `/Brepro` for
native code. A committed DLL otherwise always carries its parent's SHA.
- **Run long builds detached, with a log and a PID, and poll.** Unity batchmode
and similar builds must never be one attached call. Revert incidental asset
churn afterwards, such as Unity's SDF font asset.
- **Before a mass-spawn or process-launching probe, read how the child chooses its
role.** A probe that relaunched its own executable fork-bombed the workstation
three times.
- **Pin sibling checkouts with a guard that checks revision and cleanliness.**
Scope the guard to projects that actually reference the sibling.
## Adapting the pipeline
Small cuts can merge Imagination into Self when the map is already current, but
never merge Soul into Hands. Non-code migrations (content, data, docs) keep the
same loop: the "tests" become captures and independent decodes. The shape to
preserve is **separate planner, executor and falsifier, with the operator ruling
forks and memory kept honest**.
Record changes to this skill in `references/changelog.md`, with the evidence that
motivated each one.

173
references/briefs.md Normal file
View file

@ -0,0 +1,173 @@
# Brief templates
These are starting points. Fill in every `<>` placeholder. Each brief should let
its agent act without asking what the invariants are. Paste standing rulings in
short form rather than pointing at a long document the agent may skim.
## Contents
- Imagination: map or refresh a cut
- Hands: execute a cut
- Soul: falsify executed work
- Mind Steward: phase boundary
- Eyes: gather evidence
---
## Imagination: map or refresh a cut
```
You are Imagination for <migration>. Map <cut or cuts> in <map path> so Hands
can go straight to the cut with little reading.
Edit only <sections>. Do not commit; the root agent commits. Do not change code
in any repo. Scratch probes in <scratchpad> are fine.
Read first:
- <target doc>
- <map status header lines>
- <sections that constrain this one>
Body facts to verify (not trust):
- <repo@SHA>
- <tags>
- <API or behaviour claims>
Every mechanism claim must come from a probe or a source read, not a name.
Standing rulings: <short list>.
Spec standard, matching the existing cuts:
- repo and branch
- deletes first, with exact paths and line counts
- keeps and moves
- adds
- per-file changes with file:line against HEAD <sha>
- an authority map for any ownership change (owner, inputs, outputs, derived
state, forbidden writers, shared paths, deletion line)
- verification: builds, tests with the rule each one pins, Unity or other
runtimes, negative greps, and the operator checks
If the cut is too large for one Hands pass, split it with an explicit order and
a verification step for each part.
Where only the operator can decide, list an explicit question with a
recommended option.
Report: what changed (briefly), operator questions, findings you could not
assign to a cut, and the HEAD you pinned to.
```
## Hands: execute a cut
```
You are Hands for <cut>. The spec is <section> of <map> at <sha>. Read it and
the status header. Follow the spec; do not redesign it. If the Body contradicts
it, fix the smallest thing that keeps its intent true and report the
discrepancy. If you hit a real operator fork, stop and report.
Repo/branch: <repo> <branch> at HEAD <sha>. Check that git status is clean
first. Pinned siblings: <repo@sha>. Do not change them.
Standing rulings: <short list>.
- Gaps are filled in their owner, never with local helpers.
- Delete before adding. No shims.
Every rule the spec or the operator names gets a test that fails under its own
mutation. Run the mutations against the final spelling of the code and restore
afterwards.
Commits:
- Small and pushed.
- Stage explicit paths only; never `git add -A`.
- Write each message with the Write tool to <scratchpad>/<cut>-<n>.txt, then run
`git commit -F`.
- End each message with the attribution trailer.
- Check each message with `git log -1 --format=%B`.
- Say in the message which commits don't build.
Verification: <exact builds, tests, captures, negative greps>.
- Long builds run detached, with a log in the scratchpad; poll the log.
- Revert incidental asset churn.
Budget: if the cut can't land coherently, stop at a pushed, building commit
boundary with no half-deleted authority, and report what remains.
Don't update the map.
Report:
- commits (and which don't build)
- verification output
- mutation results
- spec discrepancies you fixed
- forks
- structural delta (lines, dependencies and formats removed or added)
- what remains
```
## Soul: falsify executed work
```
You are Soul for <cut>. Soul preserves invariants by falsifying the promises
Hands made about executed work: shortcuts, split authority, trivial tests.
Report findings only.
- Do not edit or commit.
- Restore after every mutation and leave the tree clean.
- Use a temporary detached worktree for other checkouts, and remove it
afterwards.
- Do not run <expensive runtime> unless told.
Scope: <repo> <branch>, commits <range> (base <sha>). Spec: <section>.
Operator invariants: <short list>.
Hands promised:
1. <promise>
2. <promise>
...
Falsify specifically:
- <the load-bearing claim, and what would make it false>
- <where split authority could hide>
- <which tests might pin spelling instead of behaviour; rerun N mutations,
including ones that are not plain reverts>
- <the layer where the invariant really fails: wire bytes, another runtime's
decoder, the editor, the compiler, a legacy file decoded independently>
- <leftover greps>
- rerun the builds, tests and captures yourself
Report each finding as CONFIRMED or PLAUSIBLE, with file:line, a failure
scenario and severity. Then give a short list of the promises that held.
```
## Mind Steward: phase boundary
```
Phase boundary: <what landed, SHAs>. The authoritative record is <map, target>;
don't edit those.
Surfaces: <memory dirs and files>.
Candidates for durable memory: <rulings, scars>. Check each against its owner
doc first and don't duplicate what the owner records. Retire or supersede stale
claims instead of adding corrections next to them.
Falsify at least one persisted claim against the Body.
Report: surfaces inspected, the claim you checked, mutations made, and proposals
for operator-owned surfaces.
```
## Eyes: gather evidence
```
You are Eyes. Read only. Write findings to <scratchpad>/<name>.md and return a
short summary.
Sources:
- <repos and ranges>
- <transcripts> (grep with targeted patterns; never read whole)
- <docs>
Produce facts with evidence pointers (SHA, file:line, transcript line). Mark
anything inferred as "(inferred)".
```

46
references/changelog.md Normal file
View file

@ -0,0 +1,46 @@
# Changelog
Record each change to the skill together with the evidence that motivated it.
## 2026-09-15: renamed to Eureka; postmortem rules folded in
- **Rename.** The operator named the skill-and-MCP form of the pipeline
**Eureka**. Epiphany stays the name of the running organism, and Eureka keeps
the faculty vocabulary.
- **Operator observation: typed state.** What makes Epiphany special is that
findings are stored in typed state that can be queried semantically. Claude
agents can be given the same state tools. Eureka's likely next step is to
replace doc, report and memory findings with typed state documents (findings,
rulings, cuts, Soul verdicts) behind MCP tools.
- **Operator observation: Imagination.** Eureka's Imagination has a more clearly
defined target-mapping role than Epiphany's. Epiphany may want to adopt it.
- **Epiphany comparison.** A source-grounded model of Epiphany at `71324718` is
kept as `epiphany-comparison-2026-09-15.md`. It is a dated snapshot, not live
truth. Epiphany's own `notes/faculty-workflow-lessons-2026-09-04.md:146-176`
proposes the typed forms of Eureka's habits (Verdict HOLDS/FALSIFIED/UNPROVEN,
Rulings, a landed-names digest, steward triggers). Start from those schemas
when Eureka gets typed state.
- **Rules added from the postmortem:**
- Soul runs before any release or tag.
- Ask what a domain concept is for before specifying it.
- Carry order as data, not as scheduling.
- Reconcile the subtraction ledger at every landing.
- Count consumers across every project the operator uses, not just one
runtime.
## 2026-09-15: initial formalization
Extracted from the Aetheria CultCache migration (Cuts 0-10, 2026-09-12..15). The
evidence is `postmortem-cultcache.md` and the Aetheria repo's
`docs/cultcache-migration-cut.md`.
- **Soul is distinct from Imagination.** An operator correction: "Making another
pass on the cut map is still Imagination."
- **Target shape finish line:** Hands barely reads.
- **Each operator ruling needs its own failing mutation.** In Cut 10, Soul removed
the availability rule, the price rule and the all-or-nothing fit rule, and all
15 tests still passed.
- **Don't cap Soul early.** Cuts 6 and 6b each needed four Soul passes.
- **Git and tooling scars:** explicit staging, message files, the 3-tag limit,
commit-independent byte checks, detached builds, and the process-probe role
check.

75
references/cut-map.md Normal file
View file

@ -0,0 +1,75 @@
# Cut map shape
A migration keeps two documents in the repo it changes.
- **Target** (`docs/<migration>-target.md`): the ends. It holds the invariants,
the canonical implementations, what is not a consumer, and the durable design
truths the migration produces. When the migration closes, the target is
reconciled with the Body and outlives the map.
- **Cut map** (`docs/<migration>-cut.md`): the means. It is a status header
followed by one section per cut. It is history once the migration closes.
## Status header
The header owns progress. Self updates it in every landing commit.
```
Status: cut map. Ends are owned by <target>; this document owns the means.
<for each landed cut>
Cut N landed at <repo> <sha range>. Verified: <builds/tests/captures>. Soul
found <defects>, all fixed | recorded. Recorded, not fixed: <items, why>.
Rulings (operator, <date>):
- **QN-M <choice>:** <ruling>. <quote if the wording carries meaning>.
(Supersedes <earlier ruling>; the old text below is history.)
Open: <operator checks, pending Soul passes, questions>.
Follow-ups outside this migration: <item, file, reason it can wait>.
```
## Per-cut section
```
### Cut N. <name>
- **Repo/branch:** <repo> <branch> from <base>. Depends on <cuts, releases>.
- **First:** <captures or pins taken before any edit>.
- **Deletes first:** <path (lines)>, ...
- **Keeps and moves:** ...
- **Adds:** ...
- **Per-file changes:** <file:line against HEAD sha>: <change>.
- **Authority map:**
- Owner:
- Inputs:
- Outputs:
- Derived state:
- Forbidden writers:
- Shared paths:
- Deletion line:
- **Verification:**
- builds: <exact projects>
- tests: <name> pins <rule>
- negative: <rg pattern, verified to not collide with legitimate names>
- operator: <play smoke steps; Studio click-through>
- **Operator questions:** QN-1 <question>. A: ... B: ... **Recommended: A**, because ...
```
## Subtraction ledger
One row per cut: the lines removed, the lines added, and the dependencies,
formats and targets removed or added. Compare the estimate with what landed in
the postmortem.
## Notes from use
- **Test negative greps before publishing them.** `\.loadout\b` matched the
legitimate schema name `aetheria.loadout`.
- **State the capture method with the capture.** PowerShell `>` writes a BOM and
CRLF, and the comparison must use the same method on both sides.
- **Prefer normalizers that parse the format.** Ones that split on text leave
false diffs, as the census normalizer did when it split on `, ` and glued the
first maker to its kind column.
- **When a later ruling changes a design, sweep the whole map.** Rewrite the header
and routing tables, and mark the older spec text as history, so no one reads two
live designs.

325
references/epiphany-comparison-2026-09-15.md Normal file
View file

@ -0,0 +1,325 @@
# Epiphany pipeline model (source-grounded) vs. the Eureka skill
Written 2026-09-15 by a read-only Modeling/Eyes pass. Epiphany HEAD is `71324718`
(2026-09-14), branch as checked out, worktree clean. The voidbot MCP was not
used; everything below comes from a direct Grep/Read of `F:\Projects\Epiphany`.
`.epiphany-run/` was ignored as stale.
**Resolved (Mind Steward, 2026-09-15).** While this pass ran, the skill was
renamed from `epiphany-pipeline` to `eureka`, and its frontmatter and changelog
were then updated, so the drift this pass saw no longer exists.
**Not covered by this pass: MCP.** Epiphany has an rmcp *client* only
(`epiphany-tool-mcp-runtime/Cargo.toml:18`, `client` feature). It has no MCP
server.
---
## 0. What Epiphany actually is (one paragraph)
Epiphany is a Rust workspace. It is a library (`epiphany-core`, 55,650 lines of
tracked `.rs`) plus a release bundle that owns 9 `[[bin]]` targets
(Cargo.toml). It schedules **LLM worker passes** (Modeling, Research/Eyes,
Imagination, Mind plan-review, Verification/Soul, Reorientation, Persona)
through a **pure priority projection over typed CultCache state**. Each pass
returns a closed typed decision, and a per-family admission owner commits it
to the Mind store with batch compare-and-swap. The "pipeline" is state-driven,
not conversational: nobody writes a brief. The coordinator derives the next
action from which typed obligation exists.
---
## 1. Faculties and organs
| Faculty | Embodiment in source | Status |
|---|---|---|
| **Self** | `resident_self.rs` (3,105 lines): typed pressure, grant, lease, cooldown (`cooldown_seconds` :284), retry, settlement. `surfaces/coordinator_decision.rs:7-103` `recommend_coordinator_action`, a pure priority function. Binaries `epiphany-mvp-coordinator`, `epiphany-swarm`. | Implemented as deterministic code, not an agent. map.yaml calls it "partial". |
| **Modeling** | Worker role `modeling`; instructions at `current_work.rs:2885` (Body), `:3063` (proposal), `:3189` (frontier-verdict). Output schemas in `epiphany-openai-runtime/src/lib.rs:937-968`. Writes keyed RepoModel docs (`repo_model_documents.rs`). | Implemented. |
| **Eyes** | Worker role `research`, `current_work.rs:1610`. Immutable GitHub source identity. Evidence enters Mind as keyed evidence/observation documents. | Implemented. Launched only for an explicit external-evidence obligation (algorithmic map :856). |
| **Imagination** | Worker role `imagination`, `current_work.rs:1170` (frontier planning candidate), `:2738` (Persona-feedback consideration); `imagination_consideration.rs`. It proposes, and the next organ can only be Eyes or Imagination (`6e600e8d`, algorithmic map :876-883). | Implemented. |
| **Mind** (admission) | `reasoning_context.rs` commit owner: atomic batch CAS plus `EpiphanyMindCommitReceipt`. A **Mind plan-review worker** (`current_work.rs:1327`) adopts, refuses, or holds an Imagination candidate. anatomy.md:49-52 says this is a stateless admission procedure, not a sub-agent. | Implemented. |
| **Soul** | Worker role `verification`, `current_work.rs:1466` ("Audit only the exact typed Hands consequence..."). `soul_gateway.rs:3-58`: `SoulVerdictReceipt` (verdict is a `String`) and `RepoFrontierVerificationRequest`, which binds the Hands intent, patch, command and commit receipt IDs. | Implemented as a model pass over sealed receipts. |
| **Hands** | `hands_gateway.rs`: `HandsActionIntent`, and Patch/Command/Commit receipts. Writers are `runtime_spine.rs:7386,7422,7456`. **Every caller is in `current_work.rs` tests** (lines 4383-4471, inside `#[cfg(test)]` from :3309). `ContinueImplementation` is emitted by `coordinator_decision.rs:92-96`, but **Resident Self excludes it from the launchable set** (`resident_self.rs:974-993`, which returns `None`). No code path in core, OpenAI runtime or tool-mcp runtime produces Hands receipts. The writers are still re-exported as public crate API (`lib.rs:230-232`), even though their only callers are tests. | **Types and verification input only; no live actuator in the current tree (verified by grep).** map.yaml:275 still says "hands: proven for bounded consequences" and cites historical c011-era runs. |
| **Persona** | `persona_*.rs` (6 files) plus `epiphany-persona-service` (Projector, Persona, Interpreter stages) and `epiphany-persona-discord-permit`. | Implemented, "partial" per map.yaml. |
| **Continuity** | `reorientation_work.rs` worker (`:475`, "Decide resume or regather"). `EpiphanyCoordinatorDeathRecovery`, archived session tombstones. | Implemented as a worker plus runtime tombstones. |
| **Mind Steward** | **No code.** It exists only as agent doctrine: `AGENTS.md:81-103` requires a Codex/Claude `mind_steward` sub-agent over `state/map.yaml`, the handoff, and the algorithmic map. | Docs/agent-procedure only. |
| **Nervous system** | Heartbeat store `state/agent-heartbeats.msgpack`, Resident Self grants/cooldown, runtime-spine jobs. AGENTS.md:197-201 heartbeat physiology rules. | "partial" (map.yaml organ_readiness). |
| **Substrate Gate** | `substrate_gate.rs`: grants/refusals, and `HandsActionIntent.substrate_gate_grant_receipt_id`. | Implemented (types). |
| **Operator** | Not an organ. See §5. | — |
The docs-only faculty surfaces are the Mind Steward and the dependency matrix.
`notes/organ-dependency-contracts.md` still says "every embodied sub-agent
depends on all the others", but the code matrix was deleted in `2aeab7a9`.
## 2. Routing and scheduling
- **The priority projection is pure** (`coordinator_decision.rs:7-103`; algorithmic map :1128-1143), in this order:
1. Mind missing, then Reorientation, then operator regather;
2. frontier Planning stages (Imagination, then Mind review, then commit);
3. proposal, Body, and frontier-verdict Modeling;
4. Verification;
5. Research;
6. Imagination considerations;
7. Hands-ready;
8. otherwise await a proposal.
"No default Modeling job, latest lane, accepted-at comparison, runtime event,
or generic interrupt can manufacture work" (:1142).
- **Input:** `current_work.rs` projects one pulled CultCache snapshot into
family obligations. Each family carries an `EpiphanyAgentPassAttemptProjection`
(Launch/Wait/Review) (:1183-1197). A failed attempt changes the projection
digest, so Resident Self grants exactly one fresh pressure. Replaying an
unchanged failure is idempotent.
- **Launch:** Resident Self converts the action into a grant
(`resident_self_current_work_action`, :965-1001). The coordinator launches a
worker process. The sealed typed worker launch document owns family identity
(`edb5c3a3`).
- **Briefing:** the instruction is a **one-sentence hardcoded string per family**
(`current_work.rs:1170,1327,1466,1610,2738,2885,3063,3189`;
`reorientation_work.rs:475`). The OpenAI runtime appends the sealed typed
projection (`dynamic_prompt_context`), a family output contract text, and
tool/evidence mandates (`epiphany-openai-runtime/src/lib.rs:326-339, 922-935`).
There are no free-form briefs. Context is the sealed `EpiphanyReasoningBasis`
(algorithmic map :1029-1035). The legacy prompt-TOML specialist prompts exist
only in `.epiphany-run` (stale).
- **Tracked residue:** `epiphany-state-model/src/prompts/*.md` (2 files) is still
tracked although the package was deleted in `07529fb5`.
## 3. Verification
- **Chain:** Hands receipts, then a `RepoFrontierVerificationRequest` (binds the
exact receipt IDs, frontier item hash, and model projection digest), then a
Verification worker pass, then `SoulVerdictReceipt`, then a derived frontier
Modeling request (`runtime_spine.rs:7154-7215`).
- **Gate vocabulary:** `"pass"` resolves to `Resolved`;
`"needs-review"|"needs-evidence"|"fail"` map to `Blocked`; anything else is an
error (`runtime_spine.rs:7197-7200`). This is a string match, not an enum. The
verdict must byte-match the worker result's verdict, summary, risks and
evidence (:7207-7214).
- **Anti-self-report:**
- The Verification projection is sealed. Since `24023265` it is the sole Hands
receipt input, so Soul cannot reread mutable runtime state (map.yaml:46-65).
- Provider success cannot launder malformed output: native decoding and family
admission are final (`553f79d9`).
- A structurally valid but semantically refused result writes a typed
admission-refusal and schedules a retry (algorithmic map :1390-1394).
- `a01c6842` deleted the coordinator's "same-function always-approved Hands
review".
- **What is absent:**
- No mutation testing anywhere (grep for mutants found nothing).
- No requirement that Verification runs a different model or worker identity
than Hands (grep found no distinctness check). Independence comes from
separate job/launch/basis, not from an adversarial brief.
- No CONFIRMED/PLAUSIBLE grading.
- The Soul brief is one sentence, "Audit only the exact typed Hands
consequence", so it is an audit, not a falsification mandate.
- No INTEGRATE / INTEGRATE_WITH_FOLLOWUPS verdicts.
- **Repo-development verification** (humans/Codex building Epiphany itself):
- Focused `cargo` tests per cut, recorded as counts in map.yaml (for example
"Core 152/152").
- Idunn CI gate on Yggdrasil with SHA-256 test receipts (algorithmic map
:1414-1418).
- Live "capstones" (Ox10..Ox17, Capstone 17) as end-to-end falsification. Each
failure is sealed as evidence and never resumed (:1440-1502).
- **Lessons doc:** `notes/faculty-workflow-lessons-2026-09-04.md` records that a
Soul **writing tests** produced the best findings (:49-55), and proposes a
typed `Verdict {HOLDS|FALSIFIED|UNPROVEN}` (:151-152). That is **not
implemented**.
## 4. Plans and maps
- Durable **executive map:** `state/map.yaml`, 292 lines, AGENTS.md:60-80. It
holds objective, invariants, `current_status` (one cut entry per landed SHA
with net lines and verification), `active_subgoals`, `organ_readiness`,
`forbidden_actions`, and `memory_policy`. It plays the role of the skill's
**status header**, but it is YAML, not CultCache.
- **Mechanism map:** `notes/epiphany-current-algorithmic-map.md` (1,526 lines)
carries owner/inputs/outputs/invariant tables (:841-862) and per-SHA cut
narratives. **Campaign plan:** `notes/epiphany-fork-implementation-plan.md`
(945). **Handoff:** `notes/fresh-workspace-handoff.md` (2,343 lines).
- **Evidence ledger:** `state/ledgers.msgpack` via `state_ledger.rs`. It is a
single-key CultCache entry holding `Vec<branches>` and
`Vec<evidence{ts,type,status,note}>`, and each append rewrites the entry
(:52-64). The CLI is `epiphany-state add-evidence`.
- **In-runtime plans:** Imagination frontier candidates, then a Mind plan
decision (adopt/refuse/hold) as keyed `RepoFrontierRoute`, plus `repository_scope`
and `authorized_paths` ceilings (`5b799b12`). These are typed and CAS'd.
- **No per-migration target doc or cut map** in the skill's sense. Cuts are
recorded after the fact in map.yaml and the algorithmic map, not specified
ahead of time to file:line.
- **Operator rulings:** there is no typed ruling artifact. In the runtime, the
operator objective enters via `coordinator_objective_intake.rs:45-78`
(`UserObjectiveIntake`, which refuses to replace an existing objective). In
repo development, rulings live as prose invariants in map.yaml and AGENTS.md.
The lessons doc (:153-158) proposes "Rulings as a first-class artifact". That
is **not implemented**.
## 5. Operator interaction
- `RegatherManually` is the only operator-question action. It fires when an
accepted continuity decision sets `operator_regather_required`
(`coordinator_decision.rs:27-32`, `current_work.rs:533-539`).
- `PrepareCheckpoint` fires when Mind is missing and requires an operator
objective (:10-15).
- The consent/approval surface is the canonical **swarm brake** plus
**deployment brake**, and Idunn operator grants that open and expire
(map.yaml:40-41). `forbidden_actions` (map.yaml) forbids speculative
deployment grants.
- "Humans talk to Face" (AGENTS.md:189-192). The Aquarium UI moved to a sibling
repo (`apps/README.md`) and is not in this body. The former Discord operator
bridge is deleted (algorithmic map :1507).
- There is no bundled fork/question document with a recommendation, and no
ruling write-back path besides objective intake and brake/grant transactions.
## 6. Memory
- **Runtime Mind:** keyed CultCache documents in the runtime `.cc` store, with
singleton objective/focus/mode/RepoModel binding and keyed evidence,
invariants, checkpoints, Persona memories and more (algorithmic map :981-1001).
Merge law :1105-1114. There is no aggregate head and no semantic cache
(`856648de` deleted Qdrant/Ollama/Postgres projection).
- **Persona memory:** `admit_persona_state_notes` writes keyed Mind documents
(`persona_conversation.rs:1018`). The repo publishes
`schemas/cultnet/gamecult.persona_state.v0.schema.json` but does not consume it
(consistent with `F:\Projects\CLAUDE.md`).
- **Repo-development memory:** map.yaml, handoff, and ledger, maintained by the
agent-side `mind_steward` procedure (AGENTS.md:81-103, 144-151, 216-221). No
steward organ exists in code, and nothing triggers the steward structurally.
The lessons doc :165-168 proposes boundary triggers; they are **not
implemented**.
- `epiphany-agent-memory-store` was removed in `387afe49` (verified: that commit
deletes it along with about 28 other bins).
## 7. Observability
- **Eve surface:** only Model Atlas has one (`atlas/eve_surface.rs`, 1,597
lines). Coordinator status uses string `operator_status()` values
(`resident_self.rs:582-593`) and the `epiphany-state status` CLI.
perfect-machine-audit-roadmap.md:53 lists "Eve/CultUI operator interface" as
**open**.
- **Audit:** `epiphany-model-runtime audit-decision` / `list-decisions`
reconstruct any terminal pass from typed records without transcripts
(algorithmic map :1403-1409). CultMesh projects reasoning basis, decision
context, and commit receipt read-only (map.yaml:118).
- **Budgets:**
- Time: one outer worker budget; Persona `--turn-timeout-seconds`, default
600s (algorithmic map :1041-1047).
- Tokens: recorded on receipts only (`input_tokens`, `output_tokens`,
`reasoning_output_tokens`, `cached_input_tokens`, from
`epiphany-model-adapter/src/native.rs:153-167`). No token-budget enforcement
was found.
- `reasoning_effort` is an optional per-request field.
- No model-selection-by-criticality policy.
- **Build/verify footprint:** each cut in map.yaml records verification output
size (for example "Verification generated 6.349 GiB across 7,376 files";
map.yaml:79-80).
## 8. Failure handling
- **Typed failure terminality:** `EpiphanyModelPassFailure`, bound to the sealed
context. One shared failure owner covers role, reorient, and Persona
(`bb823c54`, algorithmic map :1082-1097).
- **Retry:** a changed attempt digest yields one fresh grant, and proposal
attempt ordinals are contiguous (:1191-1197). Admission refusal writes a typed
refusal and a retry with prior refusals in context (:1390-1396).
- **Crash:** `EpiphanyCoordinatorDeathRecovery` competes with success/failure
receipts through one `EpiphanyCoordinatorRunTerminality` identity (:1220-1231).
Archived session tombstones prevent identity resurrection (:941-951).
- **Compaction (agent-side):** AGENTS.md:153-180 re-entry rite.
- **Schema epochs:** hard cuts refuse old writable stores, with no migrator or
dual reader (for example Runtime v45 / Mind v11, map.yaml:76).
- **Wrong organ output:** refusal documents; no Mind write; the run is sealed and
never resumed (Ox10/12/13/15/16 narratives, algorithmic map :1440-1502).
- **Scars recorded in-repo:**
- capstone narratives;
- `faculty-workflow-lessons` (integration is a gated sequence, :116-125; push
gated on the result line, not the launch, :127-135);
- AGENTS.md build-economy rules (:250-277).
## 9. Scale and structure
- **Workspace members** (Cargo.toml): 5 crates plus the root release bundle, with
9 `[[bin]]`: release, state, repository-body, swarm, persona-service,
persona-discord-permit, mvp-coordinator, model-runtime, tool-mcp-runtime. That
is down from about 75 core bins; `387afe49` alone removed about 28.
- **Tracked source:** 77 `.rs` files, **65,113 lines**. The giants are
`runtime_spine.rs` 8,899; `current_work.rs` 5,714; `openai-runtime/lib.rs`
3,350; `resident_self.rs` 3,105; `reasoning_context.rs` 2,715.
- **Liability observations:**
- The repo-local `target/` is **39 GiB** across 113,504 files. AGENTS.md:117-123
says builds should use the shared `C:\Users\Meta\.cargo-target-codex` target,
so this root is exactly the kind of unowned output root the build-economy
rules forbid (AGENTS.md:273-277).
- The git-ignored `.epiphany-run/` sandbox is **105 GiB**. It is stale, not a tool
(per `F:\Projects\CLAUDE.md`), but it is the single largest disk liability in the
repository. Together with `target/`, about 144 GiB of output sits beside 65k
lines of source.
- The deployed package still lists "26 binaries plus witness" (algorithmic map
:1418, historical `d2ca6630`).
- Untracked empty crate directories remain: `epiphany-openai-auth-spine`,
`epiphany-openai-codex-spine`, `epiphany-release-construction`,
`epiphany-self-policy` (0 files each).
- Tracked orphan prompts remain in `epiphany-state-model/src/prompts/`.
- The `.gitignore` still names deleted crates (`epiphany-openai-adapter`,
`epiphany-codex-bridge`, `apps/epiphany-gui`).
- Note bulk: notes/ totals about 10.6k lines. The handoff alone is 2,343 lines
and repeats cut narratives also in map.yaml and the algorithmic map. That
is triple-recorded cut history.
- The Model Atlas code (about 10k lines under `atlas/`) is "code-complete",
but Gate 1 is paused and it is operationally unaccepted.
- The ledger uses `.msgpack` single-file stores, not `.cc`.
## 10. Known gaps and stale docs
- **Hands claimed "proven"** (map.yaml:275) while current source has no live
receipt producer and Resident Self won't launch `ContinueImplementation`
(§1). Verified by grep.
- **No accepted end-to-end run on the current package.** The objective
(map.yaml:7) is still diagnosing the Aug 25 Luna connector failure. Capstone
17 and Atlas Gate 1 are open, and production is inactive and braked.
- `notes/epiphany-anatomy.md:61-62` still expects "typed continuity packets,
recovery receipts, compaction checkpoints, stale-turn repairs". Those contracts
were deleted in `ca2d2cf2` and `fed4b857` (map.yaml:183).
- `notes/organ-dependency-contracts.md` describes the dependency matrix deleted
in `2aeab7a9`.
- `notes/perfect-machine-audit-roadmap.md` (dated 2026-08-12) cites the deleted
"coordinator state transaction" and old test counts (684/684). It is still
listed as "Active Design Reference" in `notes/README.md:28`.
- The `README.md` "What She Is" list names "heartbeat, sleep, memory"
machinery, and the Continuity/Substrate Gate receipt families are partly
deleted (inferred mismatch; not line-audited).
- `docs/epiphany_body_whitepaper` is explicitly marked historical (README:220).
- `faculty-workflow-lessons` proposes 7 typed artifacts: faculty artifact
schemas, rulings, landed-names digest, owner-scoped edit queues, steward
triggers, Self budget, swarm visibility. **None exist in code** (grep for
verdict/ruling/digest types found only `SoulVerdictReceipt` with a string
verdict).
- The skill frontmatter name mismatches its directory (see header).
---
## Comparison table: Eureka skill vs. Epiphany
| Dimension | Skill (Eureka) | Epiphany | Evidence |
|---|---|---|---|
| **Self / router** | Root LLM agent routes by judgment, keeps and commits maps, talks to operator. | Deterministic pure priority function over typed obligations; Resident Self grants/leases/cooldowns. No LLM router. | Skill SKILL.md:24-27, 210-232. Epiphany `coordinator_decision.rs:7-103`, `resident_self.rs:965-1001`. |
| **Unit of work** | A "cut" from a hand-authored cut map (repo-scale refactor). | A typed family obligation (Body Modeling, frontier item, Verification request...) in a RepoModel graph. | cut-map.md:31-56. Algorithmic map :1128-1197. |
| **Planning artifact** | Target doc (ends) and cut map (means), specified ahead to file:line with authority maps and a subtraction ledger. | Imagination candidate, then Mind plan-review adopt/refuse/hold, then keyed `RepoFrontierRoute` with `repository_scope`/`authorized_paths`. Repo dev records cuts **after** landing in map.yaml. | SKILL.md:60-112. `current_work.rs:1170,1327`; `5b799b12`; map.yaml:45-188. |
| **Briefs** | Rich templates: invariants, promises to falsify, standing rulings, git rules. | One-sentence hardcoded instruction per family, plus sealed typed projection, output schema text, and tool mandates. | briefs.md:16-173. `current_work.rs:1466` etc.; `openai-runtime/lib.rs:326-339,922-935`. |
| **Hands** | Subagent commits and pushes small cuts, runs its own mutations, reports structural delta. | Typed Intent/Patch/Command/Commit receipts with path ceilings; **no live producer in current source**; `ContinueImplementation` not launchable. | SKILL.md:126-147. `hands_gateway.rs`; writers only in `current_work.rs` tests (:3309+); `resident_self.rs:974-993`. |
| **Soul independence** | Different agent; adversarial brief listing Hands' promises; reruns builds; designs non-revert mutations; probes at the failing layer. | Separate worker/job over a **sealed** receipt projection; audit-framed one-line brief; no mutation testing; no distinct-model/worker check. | SKILL.md:149-167. `current_work.rs:1466`; `24023265`; grep (no mutants, no distinctness). |
| **Verdict shape** | Findings CONFIRMED/PLAUSIBLE, with file:line, scenario and severity, plus promises that held. | `SoulVerdictReceipt.verdict: String`; "pass" becomes Resolved, "needs-review/needs-evidence/fail" become Blocked; byte-equality with the worker result. | SKILL.md:163-164. `soul_gateway.rs:13`; `runtime_spine.rs:7197-7214`. |
| **Self-report protection** | Structural: a different agent reruns everything. Rule "never claim a result before its notification". | Structural: sealed basis/context; native decode plus family admission final; provider success can't launder; typed refusal; always-approved review deleted. | SKILL.md:232. Algorithmic map :1049-1072, :1390-1396; `a01c6842`. |
| **Soul loop cap** | Explicitly uncapped on foundation cuts; track hit rate. | Retry is per failed attempt (one fresh grant per changed digest); no concept of repeated Soul passes over the same consequence. | SKILL.md:178-185. Algorithmic map :1191-1197. |
| **Operator rulings** | Bundled questions with options and a recommendation; dated rulings in the map; superseded text marked history. | No typed ruling artifact. Objective intake (refuses replacement); `RegatherManually`; brakes and expiring Idunn grants. | SKILL.md:114-124; cut-map.md:22-25. `coordinator_objective_intake.rs:45-78`; `coordinator_decision.rs:27-32`; map.yaml:40-41. Lessons doc :153-158 (proposed). |
| **Consent / approval gates** | Operator rules forks; git push per cut without further gating. | Swarm brake, deployment brake, Substrate Gate grants, Bifrost signed receipts for public consequence. | map.yaml:33-42; `substrate_gate.rs`; `HandsActionIntent.substrate_gate_grant_receipt_id`. |
| **Memory / steward** | Mind Steward subagent at phase boundaries; falsifies one claim; names mutations. | Runtime: keyed CultCache Mind with CAS merge law. Repo dev: same steward procedure as agent doctrine only; no steward organ or structural trigger. | briefs.md:142-158. Algorithmic map :981-1124; AGENTS.md:81-103. |
| **Durable state format** | Markdown docs committed in the changed repo. | Runtime `.cc` typed documents (CultCache); repo dev uses YAML map, markdown notes, and a msgpack ledger. | cut-map.md:3-10. `reasoning_context.rs`; `state/map.yaml`; `state_ledger.rs:14-64`. |
| **Audit / provenance** | Commit SHAs, Soul reports, postmortem from evidence. | Transcript-free `audit-decision` / `list-decisions` from sealed basis, context and commit receipt; SHA-256 CI test receipts. | postmortem-template.md. Algorithmic map :1403-1418. |
| **Observability** | Status header in the map; Self relays summaries. | map.yaml `current_status`; `epiphany-state status`; string operator statuses; Eve only for Atlas; operator Eve UI open. | cut-map.md:12-29. `resident_self.rs:582-593`; `atlas/eve_surface.rs`; audit-roadmap.md:53. |
| **Budgets** | Model choice by criticality; subtraction budget as pressure. | One outer time budget per pass; tokens recorded, not enforced; per-cut net-lines and verification-GiB recorded. | SKILL.md:220-227. Algorithmic map :1041-1047; `model-adapter/native.rs:153-167`; map.yaml:79-80. |
| **Failure / recovery** | Stop at a building commit boundary; triage into fix, fork or follow-up; git scars. | Typed `EpiphanyModelPassFailure`; death recovery; tombstones; epoch hard cuts; failed capstones sealed and never resumed. | briefs.md:92-93; SKILL.md:169-176, 234-254. Algorithmic map :1082-1097, :1220-1231, :1440-1502. |
| **Compaction / re-entry** | Maps committed; steward at boundaries. | AGENTS.md re-entry rite plus steward; runtime Reorientation worker decides resume or regather from a sealed continuity projection. | AGENTS.md:130-180; `reorientation_work.rs:475`. |
| **Build economy** | Detached builds with log and PID; tag-push limit; reproducible byte checks. | One package per entrypoint; focused single-package cargo only; Idunn owns broad builds; interrupted builds settled before retry. | SKILL.md:247-249. AGENTS.md:250-277. |
| **Scale evidence** | 1 migration: 114 subagents; 29/32 Soul passes found defects (about 75). | 2,269 commits; about 65k tracked Rust lines; 9 bins; no accepted current-package end-to-end capstone. | postmortem-cultcache.md:10-22. `git log`; Cargo.toml; map.yaml:7, 114-118. |
| **What each proposes but lacks** | Nothing typed: all artifacts are prose and habits. | Lessons doc proposes typed Verdict, Rulings, landed-names digest, edit queues, steward triggers, and a Self budget, matching the skill's habits; none are implemented. | faculty-workflow-lessons-2026-09-04.md:146-176. |

46
references/postmortem-cultcache.md Normal file
View file

@ -0,0 +1,46 @@
# Worked example: Aetheria CultCache migration (2026-09-12..15)
The full postmortem lives with the Body it describes, in
`F:\Projects\Aetheria\docs\cultcache-migration-postmortem.md`. The means and ends
documents sit beside it: `cultcache-migration-cut.md` and
`cultcache-migration-target.md`. Read those when you need detail. This file keeps
only the evidence behind the skill's rules, so that the reasons for the rules
survive.
**Scale:** 114 subagents ran: 50 Hands, 32 Soul, 3 Imagination, 23
Eyes/Explore and 6 Mind Stewards. Aetheria went +5.6k / −36.9k lines.
**Soul:** 29 of 32 passes found at least one real defect that Hands' tests
passed, about 75 in all. These included:
- five deadlocks or hangs;
- four lost-write or data-loss paths;
- a wire-parity split (nil map keys that Python rejects);
- semantics copied from docs instead of the compiler (`step` NaN);
- untested operator rulings.
Cut 3 took six passes, and Cuts 6 and 6b took four each. The one cut without a
Soul pass, the Cut 7 release, is where the release defects surfaced late.
**Model budget:** the only Fable agent, the first Imagination pass, hit its limit
before Cut 1. Opus ran everything else, including every Soul pass, and the hit
rate held.
**Operator corrections that became rules:**
- A pass over a plan is Imagination, not Soul.
- Probe every mechanism claim ("the effects you listed don't follow from the
causes").
- Count capability consumers across projects; atomic commit and compare-exchange
were nearly cut.
- Delete what only duplicates an owner (the generator).
- Order belongs in data, not in scheduling: tickets were built, deadlocked and
were deleted.
- Ask what a domain concept is for: loadouts were redefined three times in one
evening.
**Incidents that became rules:**
- A probe fork-bombed the workstation.
- A message file written by PowerShell 5 carried a BOM.
- A shared message filename collided.
- `git add -A` swept a local file into history.
- A push of more than 3 tags skipped publishing.
- An incremental DLL went stale.

45
references/postmortem-template.md Normal file
View file

@ -0,0 +1,45 @@
# Postmortem template
Write the postmortem when the migration closes, from evidence: commits, the cut
map, Soul reports and transcripts. Use an Eyes pass to gather facts first. Report
the delta and the scars, not a victory lap.
```
# <Migration> postmortem
## Summary
What changed, the scale (lines, dependencies, formats), and the state at
writing (landed, and what the operator still owes).
## Scope and invariants
The target in brief, what was excluded, and why the earlier attempt failed if
there was one.
## Timeline
One row per cut: dates, SHA ranges, Soul passes, and the notable finding.
## Structural delta
Estimate against actual, per repo. What was deleted, added and parked.
## What Soul caught
Defects that green tests had passed, grouped by kind (concurrency, wire parity,
lifecycle and globals, untested rulings, split authority, spec errors). Say how
each would have failed.
## Operator corrections
Where the operator corrected the agents' understanding or overturned a plan, and
what context was missing that made the wrong answer look right.
## Incidents
Machine, tooling and process failures, with their cost and the rule each one
produced.
## What worked
Only what should be repeated, stated as practice.
## What to change in the pipeline
Concrete edits to the skill, each with its evidence.
## Open follow-ups
Item, owner, file, and why it can wait.
```