Document Tauri React GUI plan

This commit is contained in:
Meta Vens 2026-04-29 15:55:53 +01:00
commit d3840fad2e
4 changed files with 75 additions and 12 deletions

View file

@ -118,6 +118,7 @@ These boundaries are more important than the individual method names:
- `thread/epiphany/roleLaunch` is a bounded authority surface for fixed modeling/checkpoint and verification/review templates, not a broad scheduler or specialist marketplace.
- `thread/epiphany/roleResult` is a read-only result projection, not a promotion gate, state writer, scheduler, or hidden continuation trigger.
- The GUI may render and steer typed state, but it must not manufacture canonical understanding.
- The MVP GUI target is a local Tauri v2 + React operator app over the existing app-server APIs. Tauri owns windowing and local lifecycle; app-server and typed Epiphany state remain authoritative.
- The app-server remains a host seam; Epiphany-owned machinery should live in `epiphany-core` where practical.
- Qdrant is the preferred persistent semantic backend; BM25 remains the bootstrap/fallback/control path.
@ -238,6 +239,64 @@ Do not spend Phase 6 polishing Phase 5 out of anxiety. The Phase 5 smoke harness
is a regression guardrail, not a ritual drum circle for summoning more tiny
hardening slices.
## GUI Operator Plan
Build the MVP GUI as a local Tauri v2 + React operator console.
The GUI is not the source of truth. It is a desktop window over the same
app-server surfaces already proved by the CLI status, coordinator, dogfood, and
live-specialist runners. Its job is to make the single-user loop usable without
terminal handling, not to invent a parallel state model.
Initial shape:
1. Scaffold `apps/epiphany-gui` as a Tauri v2 app with a React frontend.
2. Start by consuming existing app-server JSON-RPC surfaces rather than adding new protocol unless the UI exposes a real missing primitive.
3. Make the first screen an operator console, not a landing page:
- active thread and workspace
- coordinator recommendation and reason
- pressure, CRRC, and reorientation status
- fixed role lanes for implementation, modeling/checkpoint, verification/review, and reorientation
- reviewable role and reorient findings
- job/progress list
- artifact bundle list with links to summaries, transcripts, stderr, and comparison files
4. Add explicit action buttons only for already-bounded authority surfaces:
- refresh status
- run status snapshot
- run coordinator pass
- launch fixed modeling/checkpoint role
- launch fixed verification/review role
- launch fixed reorient-worker when recommended
- accept a completed reorientation finding after review
- open artifact folder/file
5. Keep semantic acceptance gated. The GUI may launch bounded work and display
findings, but it must not auto-promote evidence, auto-accept worker output,
invent arbitrary specialists, or continue implementation after unresolved
drift.
Implementation slices:
1. **Read-only shell**: scaffold Tauri/React, connect to a running app-server,
render the same data as `tools/epiphany_mvp_status.py`, and provide artifact
file links.
2. **Bounded operator actions**: add buttons for the existing coordinator,
roleLaunch, roleResult, reorientLaunch, reorientResult, and reorientAccept
flows, preserving review gates.
3. **Dogfood launcher**: wrap `tools/epiphany_mvp_dogfood.py` and
`tools/epiphany_mvp_coordinator.py` as explicit operator actions that write
artifact bundles and stream progress/status into the GUI.
4. **Usability pass**: make the current recommendation, blocked lane, pending
review, and next safe action visually obvious enough that the user can test
the product without reading transcripts unless something smells wrong.
Verification:
- Keep the existing CLI smokes as backend guardrails.
- Add a GUI smoke that starts the app-server against a smoke thread, opens the
Tauri webview, verifies the operator console renders scene/coordinator/roles,
and checks at least one bounded action produces an auditable artifact.
- Use screenshots for layout regressions once the first screen exists.
## Later Phases
These remain later work:
@ -248,7 +307,7 @@ These remain later work:
- richer role ergonomics after the fixed single-user coordinator proves useful
- mutation gates that warn or block broad writes when map freshness is stale
- broader CRRC runtime coordination beyond the landed narrow safe-boundary compact, fixed reorient-worker launch, and pre-compaction checkpoint steering actions
- GUI workflows for graph, evidence, job, invariant, and frontier steering
- richer GUI workflows for graph, evidence, job, invariant, and frontier steering after the operator console proves useful
Do not start these from vibes. Each one needs a source-grounded slice plan and a
clear invariant that says what it must not break.

View file

@ -35,6 +35,7 @@ Do not trust this file for the exact live HEAD. Always check git.
- Pre-compaction checkpoint intervention is now landed. On token-count events for loaded Epiphany threads, when pressure reaches the existing `shouldPrepareCompaction` threshold, the harness steers the active turn once with a CRRC checkpoint directive so the agent banks working context before compaction/reorientation. This is still bounded steering, not automatic semantic acceptance, a broad scheduler, or implementation continuation.
- `tools/epiphany_mvp_dogfood.py` is the first auditable dogfood runner. It drives a bounded state/role/CRRC/reorientation loop and writes local artifacts under `.epiphany-dogfood/mvp-loop`, including raw app-server transcript, rendered snapshots, final status, vanilla-reference prompt/output, and comparison notes. The runner now writes truthful vanilla/comparison artifacts whether the optional vanilla reference is skipped, fails, or completes.
- `tools/epiphany_mvp_live_specialist.py` is the first auditable live-specialist runner. It launches a real role specialist through `thread/epiphany/roleLaunch`, lets the spawned worker report through `report_agent_job_result`, reads it back through `thread/epiphany/roleResult`, and writes local artifacts under `.epiphany-dogfood/live-specialist`.
- The MVP GUI plan is now Tauri v2 + React under `apps/epiphany-gui`, talking to existing app-server APIs. It is an operator console over typed state and artifact surfaces, not a new source of truth.
- Internal `agent_job:` workers now get the reporting tool independent of the user-facing CSV spawn feature, and ephemeral worker sessions can initialize the sqlite state runtime on demand so specialist reports land in the shared backend.
- Durable in-flight investigation checkpointing is now landed in authoritative typed state, writable through `thread/epiphany/update` or accepted `thread/epiphany/promote`, rendered into the prompt, and reflected through scene/context.
- The repo is an Epiphany fork of Codex, not a Codex preset.
@ -298,13 +299,14 @@ The fixed-lane coordinator MVP is testable, and the first pre-compaction CRRC
intervention is now wired. Limited safe-boundary CRRC execution still handles
compact and fixed reorient-worker launch actions after a turn ends; the
token-count hook now handles the earlier danger zone by steering active loaded
turns once when `shouldPrepareCompaction` is reached. The next real move is
continued agent-run dogfooding, then the smallest local GUI/operator view over
the same status and artifact surfaces so the user does not have to operate the
machine from a terminal. CRRC is not a specialist-agent persona; the
reorient-worker it may launch is the specialist. Do not turn the coordinator
into a broad hidden dispatcher, arbitrary marketplace, alternate job backend,
automatic semantic acceptance path, or GUI-as-source-of-truth.
turns once when `shouldPrepareCompaction` is reached. The next real move is the
first Tauri v2 + React operator console slice over the same status,
coordinator, role, reorient, job, and artifact surfaces so the user does not
have to operate the machine from a terminal. Start read-only, then add bounded
buttons for already-existing authority surfaces. CRRC is not a specialist-agent
persona; the reorient-worker it may launch is the specialist. Do not turn the
coordinator into a broad hidden dispatcher, arbitrary marketplace, alternate
job backend, automatic semantic acceptance path, or GUI-as-source-of-truth.
Live `thread/epiphany/scene`, `thread/epiphany/jobs`, `thread/epiphany/roles`,
`thread/epiphany/freshness`, `thread/epiphany/context`,