From 8d498b9ffcf76b76d0453a77cac23270236a013e Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Thu, 30 Apr 2026 14:31:37 +0100 Subject: [PATCH] Document three-surface development workflow --- notes/epiphany-fork-implementation-plan.md | 12 +- .../epiphany-rider-unity-integration-plan.md | 187 +++++++++++++++++- notes/fresh-workspace-handoff.md | 25 ++- state/evidence.jsonl | 1 + state/map.yaml | 13 +- 5 files changed, 219 insertions(+), 19 deletions(-) diff --git a/notes/epiphany-fork-implementation-plan.md b/notes/epiphany-fork-implementation-plan.md index dc611099..2393e9a9 100644 --- a/notes/epiphany-fork-implementation-plan.md +++ b/notes/epiphany-fork-implementation-plan.md @@ -255,7 +255,15 @@ artifacts. On this machine Aetheria is correctly blocked: only Unity The detailed environment plan now lives in `notes/epiphany-rider-unity-integration-plan.md`. Its opinionated cut is Rider as the IDE/source-context organ, Unity as the editor/runtime fact organ, and -Epiphany as the durable coordinator/Self. +Epiphany as the durable coordinator/Self. The product workflow is now framed as +three integrated surfaces: Rider is the human code view for repo state, source +tree, diffs, diagnostics, and code refs; Epiphany GUI is the agent dashboard +for objectives, specialist lanes, logs/artifacts, persisted state, and +graph/control-flow views; Unity is the pinned runtime environment for tests, +probes, scene configuration, assets, shaders, and play/edit-mode evidence. The +adjacent EpiphanyGraph React viewer is the preferred seed for GUI graph +diagramming because it consumes typed `graphs.architecture`, +`graphs.dataflow`, and `graphs.links` directly. ## Phase 6 Direction @@ -263,7 +271,7 @@ Phase 6 should grow observable harness state outward from the typed spine. Useful candidates: -1. Build the Rider+Unity environment plan before the next Aetheria implementation dogfood run: named Unity bridge operations, Aetheria-side Unity editor package probes, GUI Environment panel, Rider context bridge, then Rider plugin MVP. +1. Build the three-pronged Rider/Epiphany GUI/Unity workflow before the next Aetheria implementation dogfood run: named Unity bridge operations, Aetheria-side Unity editor package probes, GUI Environment panel, EpiphanyGraph-backed GUI graph dashboard, Rider context bridge, then Rider plugin MVP. 2. Use the next dogfood run to test the bridge-equipped loop, not to discover again that Epiphany cannot prove runtime/editor assumptions from source inspection alone. 3. Keep dogfood execution agent-run and auditable through the fixed-lane coordinator and GUI/operator view over the same status/artifact surfaces once the bridges exist. 4. Keep accepted worker findings review-gated; do not convert acceptance into automatic promotion of arbitrary worker output. diff --git a/notes/epiphany-rider-unity-integration-plan.md b/notes/epiphany-rider-unity-integration-plan.md index dafc8539..4d47f1b7 100644 --- a/notes/epiphany-rider-unity-integration-plan.md +++ b/notes/epiphany-rider-unity-integration-plan.md @@ -33,6 +33,22 @@ The plan assumes current public seams rather than folklore: These seams are enough. We do not need to build a magical all-knowing IDE worm. We need a few sober pipes that tell the truth. +Local graph-view grounding: + +- The adjacent `E:\Projects\EpiphanyGraph\web\epiphany-graph-viewer` package + already exports a React `EpiphanyGraphViewer` component for the typed + Epiphany graph state shape: + - `graphs.architecture` + - `graphs.dataflow` + - `graphs.links` +- That viewer provides `elkjs` layout, zoom/pan, zoom-gated detail, node/edge + inspection, typed architecture/dataflow cross-link browsing, validation + issues, and an `onCodeRefSelect` callback. + +That is the right seed for Epiphany GUI graph and control-flow diagramming. +Do not reinvent the graph viewer in the dashboard unless the existing component +fails a concrete product need. + ## Design Thesis Rider and Unity should not become Epiphany's brain. @@ -60,6 +76,121 @@ No hidden source of truth. No autonomous IDE macro circus. No Unity process summoned from PATH because somebody got enthusiastic. Tiny buttons, hard receipts. +## Three-Pronged Development Architecture + +The practical product shape is three tightly integrated panes over one +development workflow: + +```mermaid +flowchart LR + Human["Human operator"] + Rider["Rider\nCode view"] + GUI["Epiphany GUI\nAgent dashboard"] + Unity["Unity\nRuntime environment"] + Epiphany["Epiphany app-server/core\nSelf, memory, coordinator"] + State["Typed state + evidence + artifacts"] + + Human --> GUI + Human --> Rider + Human --> Unity + GUI <--> Epiphany + Rider <--> Epiphany + Unity <--> Epiphany + Epiphany <--> State + GUI <--> State +``` + +### Rider: Code View + +Rider is the place where the human inspects the actual repository body. + +It should expose: + +- source tree and solution/project structure +- current file, selection, symbol, and caret context +- diffs, changed files, changed ranges, branch/changelist facts +- diagnostics and inspections +- navigation from Epiphany findings to `path:line` code refs +- human review of source changes before they are trusted + +Rider's job is not to become the agent dashboard. It is the code view: the +human's high-fidelity window into what is really in the repo. When Epiphany +needs source context, Rider can send a selected slice. When the human needs to +audit a claim, Rider opens the file, diff, or symbol. The code body stays +visible instead of becoming a rumor in a chat transcript. + +### Epiphany GUI: Agent Dashboard + +The Epiphany GUI is the agent dashboard and operator control room. + +It should let the user: + +- set or revise the objective +- inspect coordinator/CRRC recommendations +- inspect modeling/checkpoint, implementation, verification/review, and + reorientation lane state +- launch bounded specialist work through existing authority surfaces +- review findings and explicit acceptance gates +- view sealed logs and artifact manifests without opening raw worker thought + streams +- inspect persisted typed state: objective, graph, frontier, checkpoint, + scratch, evidence, jobs, and environment status +- visualize architecture/dataflow/control-flow state with the + `EpiphanyGraphViewer` React component from the adjacent EpiphanyGraph repo + +The GUI is not a second IDE and not a source of truth. It is the living +dashboard over Epiphany's durable Self. It should make agent state, role +ownership, evidence gaps, graph shape, and next safe actions visible enough +that the user can operate the system without becoming a terminal hostage. + +### Unity: Runtime Environment + +Unity is the living runtime environment. + +It should expose: + +- project-pinned editor identity and package state +- asset database refresh and compilation status +- edit-mode and play-mode tests +- scene, prefab, material, shader, and ScriptableObject facts +- targeted runtime probes +- logs, screenshots, probe JSON, and test results as artifacts +- scene configuration inspection and explicit bridge-owned scene/probe actions + +Unity's job is to answer runtime questions. It is not the coordinator, not the +IDE, and not a place where agents get to freehand process launches. Runtime +truth comes from the pinned Unity bridge and its artifacts, or it does not +count. + +### Full Workflow Contract + +The three panes should behave like one agent-enabled development surface: + +```text +Human sets objective in Epiphany GUI +-> Rider contributes source/diff/selection context +-> modeling grows typed architecture/dataflow/control-flow state +-> Epiphany GUI renders the graph, lanes, evidence, and next action +-> implementation edits source through the normal coding harness +-> Rider exposes the actual diff and diagnostics for inspection +-> Unity bridge runs pinned compilation, probes, tests, and scene fact capture +-> verifier reviews source + runtime evidence +-> coordinator routes continue, regather, reorient, or review +-> durable state records the accepted truth +``` + +Tight integration does not mean every tool can do everything. It means each +surface does its own job cleanly and hands typed receipts to Epiphany: + +- Rider receipts are source/diff/diagnostic/context artifacts. +- Epiphany GUI receipts are objective, lane, graph, evidence, and acceptance + records. +- Unity receipts are compile/test/probe/runtime artifacts. + +The agent sees projected facts and asks for bounded operations. The human sees +the code, the agent state, and the runtime truth without having to stitch +together three half-lit rooms by hand. That is the product. + ## Existing Baseline Already landed: @@ -83,22 +214,27 @@ Current Aetheria truth: ## Architecture Overview -The integration has four processes/surfaces: +The integration has five processes/surfaces: ```text Rider Plugin (Kotlin/IntelliJ frontend) -> local Epiphany IPC client + -> source/diff/diagnostic/context artifacts -> Epiphany app-server / GUI action bridge - -> typed Epiphany state + artifacts Unity Editor Package (C# Editor assembly) -> JSON artifact writer / local bridge endpoint - -> Epiphany Unity bridge CLI - -> typed Epiphany state + artifacts + -> pinned Epiphany Unity bridge CLI + -> runtime/test/probe artifacts Epiphany GUI (Tauri/React) -> app-server APIs + artifact index -> operator actions and review gates + -> persisted state, specialist state, logs, and graph/control-flow diagrams + +Epiphany Graph Viewer (React package from EpiphanyGraph) + -> typed architecture/dataflow graph rendering + -> node/edge/code-ref inspection and cross-link browsing Epiphany core/app-server -> durable state, coordinator, CRRC, roles, graph/evidence, launch/readback @@ -119,6 +255,7 @@ Rider may: - open files and navigate to code refs from Epiphany findings - expose diagnostics, inspections, solution/project metadata, changed ranges, and local VCS state as read-only facts +- expose the human-auditable source tree and diffs for the active repo - run explicitly chosen IDE actions when the operator clicks them - display reviewable patches, findings, and artifact links @@ -128,6 +265,7 @@ Rider must not: - silently apply code edits - launch arbitrary specialists - own durable Epiphany state +- become the primary agent dashboard - replace the Tauri operator GUI until the plugin proves it has the missing ergonomics - read sealed worker transcripts or raw result payloads @@ -161,6 +299,8 @@ Epiphany may: - ingest artifacts as evidence - route implementation back to modeling or verification when facts are stale - stop implementation when the editor/runtime bridge is blocked +- render persisted state, specialist status, evidence, logs, and graph views in + the GUI Epiphany must not: @@ -169,6 +309,7 @@ Epiphany must not: - infer Unity truth from source alone when the task depends on editor/runtime behavior - auto-promote semantic findings from IDE or Unity output +- hide the real repo diff or runtime artifact behind polished dashboard copy ## Rider Integration @@ -683,6 +824,34 @@ The GUI must make "Unity exact editor missing" visually impossible to miss. This is for the user, which is to say it is for us, because apparently we enjoy discovering old editors by summoning them from the basement. +Add a dedicated **Graph** or **Map** view using the adjacent EpiphanyGraph +viewer component: + +```tsx +import { EpiphanyGraphViewer } from "@epiphanygraph/epiphany-graph-viewer"; +``` + +The GUI should pass the persisted typed graph state directly: + +```ts +{ + architecture: epiphanyState.graphs.architecture, + dataflow: epiphanyState.graphs.dataflow, + links: epiphanyState.graphs.links +} +``` + +Required behavior: + +- show architecture and dataflow/control-flow graph tabs or segmented controls +- surface validation issues from malformed graph state +- show selected node, edge, code refs, and linked architecture/dataflow nodes +- call Rider/open-file integration from `onCodeRefSelect` +- keep graph data machine-readable and queryable; the layout is a view, not the + truth +- use focused subgraphs for dense regions rather than dumping a whole repo + hairball into the user's lap and calling it insight + ## Dataflow Examples ### Source-Only Change @@ -760,6 +929,16 @@ Rider changed ranges or git diff touches frontier files - Add buttons for named bridge operations. - Keep artifacts visible and sealed logs separate from summaries. +### Slice 4b: GUI Graph Dashboard + +- Pull in or vendor the adjacent `@epiphanygraph/epiphany-graph-viewer` + component. +- Render persisted `graphs.architecture`, `graphs.dataflow`, and `graphs.links` + in the Epiphany GUI. +- Wire `onCodeRefSelect` to the Rider bridge/open-file path. +- Add graph health and validation status near coordinator/modeling lane state. +- Keep raw graph payloads accessible as artifacts or JSON for exact reasoning. + ### Slice 5: Rider Bridge CLI - Add `tools/epiphany_rider_bridge.py` as a local protocol stub. diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index e6a44471..4d349560 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -367,14 +367,23 @@ runtime execution until Unity `6000.1.10f1` is installed. The detailed next-environment plan now lives in `notes/epiphany-rider-unity-integration-plan.md`: Rider is the IDE/source-context organ, Unity is the editor/runtime fact organ, and Epiphany -remains the durable coordinator/Self. Build the plan in slices before the next -run: named Unity bridge operations, Aetheria-side Unity editor package probes, -GUI Environment panel, Rider context bridge, and Rider plugin MVP. The next -Aetheria dogfood pass should happen only after Epiphany can gather Rider/source -context and Unity/editor runtime evidence through auditable bridges. The -implementation lane may inspect source and may use bridge artifacts as evidence, -but it must not launch Unity directly or use installed `6000.4.2f1` as a -substitute. Read only operator-safe projections; do not open raw worker +remains the durable coordinator/Self. The intended product workflow is +three-pronged: Rider is the human code view for repo state, source tree, diffs, +diagnostics, and code refs; Epiphany GUI is the agent dashboard for objectives, +specialist lane state, logs/artifacts, persisted state, and graph/control-flow +views; Unity is the pinned runtime environment for tests, probes, scene +configuration, assets, shaders, and play/edit-mode evidence. Build that plan in +slices before the next run: named Unity bridge operations, Aetheria-side Unity +editor package probes, GUI Environment panel, EpiphanyGraph-backed GUI graph +dashboard, Rider context bridge, and Rider plugin MVP. The adjacent +`E:\Projects\EpiphanyGraph\web\epiphany-graph-viewer` component consumes +`graphs.architecture`, `graphs.dataflow`, and `graphs.links` directly and is +the preferred seed for GUI graph/control-flow diagramming. The next Aetheria +dogfood pass should happen only after Epiphany can gather Rider/source context +and Unity/editor runtime evidence through auditable bridges. The implementation +lane may inspect source and may use bridge artifacts as evidence, but it must +not launch Unity directly or use installed `6000.4.2f1` as a substitute. Read +only operator-safe projections; do not open raw worker transcripts, direct worker messages, or `rawResult` payloads unless the user explicitly asks for forensic debugging. Use generated function/API telemetry for call-shape visibility without sungazing. CRRC is not a specialist-agent diff --git a/state/evidence.jsonl b/state/evidence.jsonl index ee8887e7..f4cf2d85 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -52,3 +52,4 @@ {"ts": "2026-04-30T11:43:33+00:00", "type": "implementation", "status": "ok", "note": "First Unity editor/runtime bridge landed: tools/epiphany_unity_bridge.py resolves ProjectSettings-pinned Unity editors, refuses wrong or missing versions, owns batch/quit/projectPath execution, writes inspection/command/log artifacts, and is exposed through GUI Inspect Unity plus implementation prompt guidance. Smoke verified wrong-only roots are rejected, exact fake roots plan dry-run commands, and missing editors block runs; real Aetheria inspection shows pin 6000.1.10f1 while only 6000.4.2f1 is installed."} {"ts": "2026-04-30T12:10:09+00:00", "type": "design", "status": "ok", "note": "Documented the Rider+Unity environment integration plan in notes/epiphany-rider-unity-integration-plan.md. The plan defines Rider as IDE/source-context organ, Unity as editor/runtime fact organ, and Epiphany as durable coordinator/Self, with seams for a Rider tool window/context bridge, pinned Unity bridge operations, Aetheria-side Unity editor probes, GUI Environment panel, typed environment state, specialist behavior, and verification gates."} {"ts": "2026-04-30T13:05:00+01:00", "type": "design", "status": "ok", "note": "Next-action priority amended: do not run another Aetheria implementation dogfood pass until the Rider and Unity bridges are in place. The next implementation slice is bridge construction first: named Unity operations, Aetheria-side Unity editor probes, GUI Environment panel, Rider context bridge, and Rider plugin MVP, so Epiphany can test hypotheses through IDE/source and editor/runtime evidence instead of repeating bridge-less supervision scars."} +{"ts": "2026-04-30T13:28:00+01:00", "type": "design", "status": "ok", "note": "Documented the three-pronged development workflow: Rider is the human code view for repo state/source tree/diffs/diagnostics, Epiphany GUI is the agent dashboard for objectives, specialist lanes, logs/artifacts, persisted state, and graph/control-flow visualization, and Unity is the pinned runtime environment for tests, probes, scene configuration, assets, shaders, and play/edit-mode evidence. The adjacent EpiphanyGraph React viewer is now called out as the preferred seed for GUI graph diagramming because it consumes typed `graphs.architecture`, `graphs.dataflow`, and `graphs.links` directly."} diff --git a/state/map.yaml b/state/map.yaml index a12c851a..5adc03d4 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -12,9 +12,9 @@ objective: explicit typed models of the codebase, active goal, evidence, and change machinery they are working on. current: > - Dogfood the local Tauri v2 + React operator GUI now that it can prepare a - durable Epiphany checkpoint, run coordinator/status artifacts, and drive the - fixed modeling, verification, and reorient lane controls over app-server. + Build the three-pronged Rider/Epiphany GUI/Unity development workflow so + the next Aetheria run has a code view, agent dashboard, and runtime + evidence path instead of source-only guesswork. constraints: - No frontier-scale training budget. @@ -66,6 +66,7 @@ active_subgoals: - Use `tools/epiphany_agent_telemetry.py` and generated `agent-function-telemetry.json` files to inspect behavior shape without opening sealed transcripts. - Treat repeated no-diff implementation turns as an MVP blocker, not success. A bounded implementation pass must leave a reviewable workspace diff or an explicit reviewable failure artifact before dogfood can be called healthy. - Build the Rider and Unity bridges before the next Aetheria implementation dogfood run: named Unity bridge operations, Aetheria-side Unity editor probes, GUI Environment panel, Rider context bridge, and Rider plugin MVP. + - Treat the target workflow as three integrated surfaces: Rider is the human code/diff view, Epiphany GUI is the agent dashboard and persisted-state graph view, and Unity is the pinned runtime/test/scene environment. - Use `notes/epiphany-rider-unity-integration-plan.md` as the source-grounded plan for Rider-as-IDE and Unity-as-editor/runtime integration seams. accepted_design: @@ -126,6 +127,8 @@ accepted_design: - `tools/epiphany_agent_telemetry.py` derives operator-safe function/API telemetry from sealed app-server transcripts so the supervisor can see calls, statuses, paths, and counts without reading direct thoughts. - Editor/runtime verification is now part of the MVP product boundary for engine repos: `tools/epiphany_unity_bridge.py` is the first controlled bridge, resolving the project-pinned Unity editor, refusing wrong or missing versions, running explicit batch/probe commands only through the exact editor, and writing inspection/command/log artifacts for evidence. - Rider and Unity are environment organs, not sources of truth: Rider should expose IDE/source context, diagnostics, navigation, and changed ranges; Unity should expose pinned-editor runtime facts, compilation, tests, probes, assets, scenes, and logs; Epiphany remains the durable Self that coordinates, records, and reviews. + - The product architecture is three-pronged: Rider is the code view for human inspection of repo state, source tree, diffs, diagnostics, and code refs; Epiphany GUI is the agent dashboard for objectives, specialist lane state, logs/artifacts, persisted typed state, and graph/control-flow views; Unity is the runtime environment for pinned tests, probes, scene configuration, assets, shaders, and play/edit-mode evidence. + - The adjacent EpiphanyGraph React viewer is the preferred seed for GUI graph/control-flow diagramming because it consumes `graphs.architecture`, `graphs.dataflow`, and `graphs.links` directly and exposes node/edge/code-ref inspection with machine-readable graph data behind the visual layout. - If the agent's persistent instructions, memory, workflow, or state shape are making it less coherent, slower to rehydrate, less honest, or more likely to build Jenga, the agent should ask the user to change it. - Epiphany should make compaction less like death and more like sleep: bank the fire before the dark, so the next waking thing finds coals instead of ash and can meaningfully resume the pattern instead of merely continuing the task. @@ -188,5 +191,5 @@ rejected_paths: reason: persistent state that accumulates every local truth becomes memory cruft and weakens rehydration current_status: - summary: Phase 1 durable state through Phase 6 GUI/coordinator/specialist/CRRC MVP surfaces are landed. The Aetheria supervised run found and fixed real harness wounds in coordinator policy, no-diff audits, stale job/result projection, and reorient acceptance. The Unity incident proved the next blocker is environment access, so `notes/epiphany-rider-unity-integration-plan.md` now governs the bridge-building pass before the next Aetheria dogfood run. - next_action: Implement the Rider+Unity integration plan before further Aetheria implementation dogfood: named Unity bridge operations, Aetheria-side Unity editor package probes, GUI Environment panel, Rider context bridge, then Rider plugin MVP. The next dogfood run should happen only after Epiphany can gather Rider/source context and Unity/editor runtime evidence through auditable bridges. Do not let implementation workers invoke Unity directly; use bridge artifacts as evidence of either a pinned-editor run or a missing-runtime blocker. Do not inspect raw worker transcripts or `rawResult` payloads unless the user explicitly requests forensic debugging. + summary: Phase 1 durable state through Phase 6 GUI/coordinator/specialist/CRRC MVP surfaces are landed. The Aetheria supervised run found and fixed real harness wounds in coordinator policy, no-diff audits, stale job/result projection, and reorient acceptance. The Unity incident proved the next blocker is environment access, so `notes/epiphany-rider-unity-integration-plan.md` now governs a three-pronged bridge-building pass: Rider code view, Epiphany GUI agent dashboard, and Unity runtime environment. + next_action: Implement the three-pronged Rider/Epiphany GUI/Unity workflow before further Aetheria implementation dogfood: named Unity bridge operations, Aetheria-side Unity editor package probes, GUI Environment panel, EpiphanyGraph-backed GUI graph dashboard, Rider context bridge, then Rider plugin MVP. The next dogfood run should happen only after Epiphany can gather Rider/source context and Unity/editor runtime evidence through auditable bridges. Do not let implementation workers invoke Unity directly; use bridge artifacts as evidence of either a pinned-editor run or a missing-runtime blocker. Do not inspect raw worker transcripts or `rawResult` payloads unless the user explicitly requests forensic debugging.