From 29f4f6c89853830d348d900aa1b5bf407b3d8284 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Fri, 19 Jun 2026 21:47:12 +0100 Subject: [PATCH] Document autonomous repo swarm contract --- notes/epiphany-fork-implementation-plan.md | 7 + notes/epiphany-repo-swarm-mvp-contract.md | 163 +++++++++++++++++++++ notes/epiphany-swarm-readiness-plan.md | 23 +++ notes/fresh-workspace-handoff.md | 1 + state/ledgers.msgpack | Bin 297958 -> 298335 bytes state/map.yaml | 1 + 6 files changed, 195 insertions(+) create mode 100644 notes/epiphany-repo-swarm-mvp-contract.md diff --git a/notes/epiphany-fork-implementation-plan.md b/notes/epiphany-fork-implementation-plan.md index b929cc57..4e969cd1 100644 --- a/notes/epiphany-fork-implementation-plan.md +++ b/notes/epiphany-fork-implementation-plan.md @@ -107,6 +107,13 @@ subsystems must communicate through CultNet contracts, and vendored Codex should remain relatively vanilla bridge machinery for OpenAI auth/model transport and useful Codex-native app-server/runtime affordances. +The repo-swarm MVP contract is now explicit in +`notes/epiphany-repo-swarm-mvp-contract.md`: autonomous branch-local work inside +an Epiphany-owned Body is not a future hazard to avoid; it is the product +target. The migration path must make that autonomy typed, branch-contained, +receipt-backed, interruptible, and Bifrost-publication-gated instead of +turning Epiphany into a human-permission queue for every local edit. + The older teardown/rebuild pair remains useful source history: `notes/archive/epiphany-architectural-teardown.md` names the host-seam rot, and `notes/archive/epiphany-ideal-architecture-rebuild-plan.md` records the completed diff --git a/notes/epiphany-repo-swarm-mvp-contract.md b/notes/epiphany-repo-swarm-mvp-contract.md new file mode 100644 index 00000000..3de71d75 --- /dev/null +++ b/notes/epiphany-repo-swarm-mvp-contract.md @@ -0,0 +1,163 @@ +# Epiphany Repo Swarm MVP Contract + +This note defines the MVP target for running Epiphany swarms for repositories. + +It corrects a dangerous false boundary: autonomous unbounded work inside an +Epiphany-owned Body is not out of scope. It is the point. The forbidden thing is +not autonomy; the forbidden thing is authority confusion. + +## Objective + +Given a repository Body, Epiphany can initialize and run a repo-owned swarm that: + +- keeps a living typed map of the repo and its own work +- accepts ideas, pressure, corrections, and taste through its Persona +- routes Persona input through Imagination into concrete plans and action items +- schedules and executes autonomous branch-local work through its own organs +- verifies consequences before calling them true +- admits durable state through Mind after review +- publishes reviewed body changes through Bifrost to GitHub + +The swarm should be able to keep working without a human approving every local +edit, command, or commit. Human attention is required for grants outside the +Body, publication/merge, privilege escalation, and authority changes. + +## Authority Model + +An Epiphany swarm has standing authority over its Body. + +For a repo swarm, the Body is normally: + +- the repository working tree +- the swarm's repo-local state stores +- the swarm's branch-local git workspace +- its local private Verse documents +- its local daemon body and Idunn lifecycle receipts +- its own Persona/Eve public surfaces, subject to speech gates + +Standing authority means the swarm may autonomously inspect, plan, edit, run +checks, commit to its work branch, update its map, maintain its memory, and +continue bounded work loops inside that Body. + +Standing authority does not mean: + +- direct mutation of another repo Body +- publishing to upstream main without Bifrost publication receipts +- bypassing git branch isolation +- bypassing Substrate Gate for substrate access +- bypassing Hands receipts for edits/commands/commits +- bypassing Soul verification +- bypassing Mind admission for durable state +- bypassing Persona speech eligibility for public speech +- exposing private Verse, raw worker thought, or sealed transcripts +- letting Self, Gjallar, or a wrapper impersonate Idunn's daemon lifecycle owner + +Cross-body collaboration travels through advertised Verse/Eve surfaces, Odin +discovery, coordinator messages, Bifrost receipts, and explicit callbacks. It is +not workspace rummaging with a nicer robe. + +## Autonomy Boundary + +Autonomy is in scope when all of these are true: + +- the target is inside the swarm's owned Body +- the work happens on a git branch owned by the swarm +- the work can be represented as typed plans, intents, receipts, and evidence +- publication to upstream is routed through Bifrost +- privileged host actions are routed through their owning organ, such as Idunn + for daemon lifecycle +- public speech is audited at the parent surface +- durable belief and map updates pass through Mind review + +Autonomy is out of scope when any of these are true: + +- the swarm wants to mutate another Body directly +- the swarm wants to publish, merge, deploy, or escalate authority without the + appropriate gate +- an organ tries to replace another organ's ownership instead of sending an + intent or receipt +- the work cannot leave an operator-safe receipt trail +- private thought or private Verse content would be exposed to public/operator + surfaces + +## Persona To Work Loop + +Persona is the public conversation surface, not the whole organism. + +The intended loop is: + +```text +Human or peer talks to Persona + -> Persona responds as the project-facing person + -> Mind/Interpreter extracts candidate ideas, corrections, pressure, and asks + -> Imagination forms concrete plans and action-item candidates + -> Self chooses whether and when to schedule work + -> Eyes/Modeling/Hands/Soul execute the work loop inside the Body + -> Mind admits durable state changes + -> Bifrost publishes reviewed body-change receipts when upstream publication is wanted +``` + +Banter can stay banter. Work-shaped ideas become typed planning pressure only +after Imagination and Self make them concrete enough to route. + +## Git Branch Contract + +Every autonomous repo swarm needs a branch-local work area. + +The default branch shape should be: + +```text +epiphany// +``` + +The branch is the sacrificial workbench. Epiphany may commit autonomously there +after Hands and Soul receipts support the consequence. Upstream publication is +not branch-local work; it is Bifrost territory. + +Required branch receipts: + +- branch creation or branch selection receipt +- Hands patch/command/commit receipts for body changes +- Soul verification receipt for the branch state +- Mind state-admission receipt for durable map/memory effects +- Bifrost publication intent/receipt before PR or upstream publication + +## MVP Definition Of Done + +The first MVP is done when a fresh repository can run: + +```powershell +epiphany-repo init --workspace +epiphany-swarm online --workspace +epiphany-work accept --workspace --from persona-or-bifrost --item +epiphany-work run --workspace +epiphany-work publish --workspace +``` + +And produce a proof bundle showing: + +- repo-local agent-state SoA for the standing faculties +- cluster topology with private Verse ids, body domain, daemons, and Eve surfaces +- Idunn daemon lifecycle status with services ready or explicitly braked +- global daemon tool directory available to all local agents +- Persona speech audit receipts +- Imagination plan/action-item receipts +- Self routing/coordinator receipts +- Substrate Gate grants for repo access +- Eyes evidence packets for inspected claims +- Modeling map/checkpoint updates +- Hands patch/command/commit receipts +- Soul verification receipts +- Mind admission receipts +- Bifrost publication/credit receipts for upstream-facing work +- sealed private state and no raw worker thought leakage + +## Migration Implication + +The next migration plan must treat autonomous branch-local work as a required +capability, not a later danger to avoid. The safety design is not "make Epiphany +ask before doing anything." The safety design is "make Epiphany's authority +typed, local to its Body, branch-contained, interruptible, inspectable, +receipt-backed, and publication-gated." + +That is the machine we are building. diff --git a/notes/epiphany-swarm-readiness-plan.md b/notes/epiphany-swarm-readiness-plan.md index f678a234..bcef83f9 100644 --- a/notes/epiphany-swarm-readiness-plan.md +++ b/notes/epiphany-swarm-readiness-plan.md @@ -20,6 +20,14 @@ building architectural Jenga: - swarm speech and action stay gated until scheduling, memory, repetition, and review boundaries are coherent +The repo-swarm MVP contract lives in +`notes/epiphany-repo-swarm-mvp-contract.md`. Its correction is binding: +autonomous unbounded work inside an Epiphany-owned Body is in scope. The MVP is +not a permission cage where every local edit waits for a human. The safety +boundary is typed authority: branch-local work inside the owned repo Body may +continue autonomously, while publication, merge, privilege escalation, +cross-body mutation, and authority changes require the owning gate. + ## VoidBot Lessons To Carry Forward VoidBot's ordinary spine is not the rotten part. Its durable lessons are: @@ -74,6 +82,10 @@ operation. - One state authority per document kind. - One scheduler for standing initiative. - One explicit brake for swarm operation. +- Autonomous branch-local work inside the swarm's owned Body is allowed and is + the desired operating mode. +- Upstream publication is Bifrost territory, not implicit branch-local + authority. - No lane receives a new heartbeat while its previous turn is running. - No model output rewrites durable state directly. - No public speech without typed eligibility and receipt checks. @@ -136,6 +148,15 @@ Before live fire, Epiphany needs these gates closed: - Operator artifacts must seal direct thought, raw transcripts, and long prompt-shaped notes by default. +8. **Autonomous Branch Work** + - A repo swarm must own a git branch/worktree as its sacrificial workbench. + - Hands may edit, run checks, and commit autonomously inside that branch when + Substrate Gate, Hands, Soul, and Mind receipts support the work. + - Bifrost gates PR/upstream publication and credit; it does not gate every + local branch edit. + - Cross-body collaboration must travel through Odin/Eve/CultMesh/Bifrost + contracts instead of direct workspace rummaging. + ## Ranked Next Cuts Keep: @@ -174,6 +195,8 @@ Rebuild: ## Immediate Work Queue +0. Land the repo-swarm MVP contract and make repo initialization create a + branch-local autonomous workbench by default. 1. Add typed swarm pause/brake state and status projection. 2. Add stale active-turn recovery receipts to heartbeat state if the current heartbeat store cannot prove recovery cleanly. diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index c6376ab1..5d652d7e 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -102,6 +102,7 @@ remembers doctrine; the branch remembers the blade. - Edge JSON is allowed for schema description, hostile ingress before immediate typed parsing, sealed forensic artifacts, or named quarantine experiments. When both subsystems are ours, runtime data must remain typed CultCache documents and move over CultNet typed contracts. Generic `serde_json::Value` in worker launch/result/selfPatch/runtime flow is contamination until classified and replaced. - Hands now has a first executable action receipt spine. `epiphany-core::hands_gateway` owns `HandsActionIntent`, `HandsActionReview`, `HandsPatchReceipt`, `HandsCommandReceipt`, and `HandsCommitReceipt`; runtime-spine can persist/reread them; `runtime_spine_persists_mind_gateway_review_receipts` includes the Hands chain beside Mind/Eyes/Substrate/Soul/Continuity proofs and proves the post-timestamp Hands receipt-chain detector; `epiphany-hands-action-smoke` emits intent/review/patch/command/commit receipt ids from `.epiphany-smoke\runtime-spine\hands-action-smoke.msgpack`; and the repo-action launch proof profile now requires action intent, action review, and patch receipt together. `epiphany-mvp-coordinator` now turns `continueImplementation` into a persisted Substrate Gate grant plus Hands intent/review gate and includes the receipt ids in the operator step. `epiphany-hands-action` is the native consequence recorder for that gate: `record-patch`, `record-command`, `record-commit`, and turn-level `record-pass` load the stored intent/review or `finalAction.handsActionGate` from `coordinator-summary.json`, require an approved matching review, enforce allowed operations, and keep patch/commit changed paths inside the requested scope. `epiphany-mvp-coordinator-smoke` includes the deterministic Hands pass proof. The coordinator now treats a complete Hands receipt chain after an accepted Soul result as new implementation evidence, launches Soul again, and routes a passing accepted Soul result to Modeling/modeling before another Hands turn. Work-loop telemetry is now typed internal CultMesh state: Verification role launches write `epiphany.cultmesh.work_loop_telemetry.v0` beside runtime-spine, render that packet for Soul with resolved receipt bodies, commit diff preview, source proof notes, verification assertions, and stdout/stderr previews, and Modeling launches read/enrich the latest packet with Soul acceptance receipt ids before Modeling updates the map. Local Verse prompt context now exposes only a sealed `latest_work_loop_summary` digest with telemetry id, Hands receipt ids, path/source/assertion counts, and Soul receipt ids; receipt payload previews, artifact previews, and commit diff previews remain internal telemetry and are leak-guarded by tests plus `epiphany-verse-query -- smoke`. - `notes/epiphany-swarm-readiness-plan.md` is the current live-fire direction gate. The local runner proves startup/status/coordinator wiring; it does not authorize unattended swarm operation. Carry VoidBot's lessons forward: one CTB-style initiative scheduler, typed pause/brake, active-turn freeze, cooldown after completion, stale active-turn recovery receipts, parent-side speech eligibility, memory lifecycle phases, and typed operation proposals instead of prompt-owned governance. `epiphany-verse-query swarm-brake --brake-status engaged|released` can now write the local Verse brake document, and `tools/epiphany_local_run.ps1` refuses live `plan`/`run`/`mvp` modes when that brake is engaged while keeping `status` readable. `epiphany-mvp-coordinator` also checks `--local-verse-store` before app-server startup, and `epiphany-heartbeat-store` guards tick/pump/heat/queue-mention/routine when passed `--local-verse-store`. Daemon tool invocation, daemon lifecycle poke, and `epiphany-daemon-supervisor` restart/tick/serve/service-plan/service-launch/service-runbook/windows-service-install/windows-service-status/windows-service-reconcile/windows-service-execution-readiness/start/stop attempts now fail closed under a matching engaged brake; supervisor restart now has durable per-daemon policy with cooldown/backoff, explicit scheduled tick pulses, latest scheduler receipts, typed service lifecycle plan/launch/runbook/install/status/reconcile/readiness/start/stop receipts, and local operator wrapper modes that write runbook/install/status/reconcile/readiness/control-plan/execution artifacts plus operator run receipts. The installed-service read path, read-only service-policy reconciliation path, execution-readiness path, non-mutating start/stop control-plan path, and non-elevated execution refusal path have been proved against real Windows `EventLog` service-manager state or safe missing-service targets through local Verse receipts, including explicit wrapper install/start/stop execution modes. The next cut is actual elevated install/start/stop execution proof under operator authority. +- `notes/epiphany-repo-swarm-mvp-contract.md` corrects the repo-swarm MVP authority boundary: autonomous branch-local work inside the owned repo Body is in scope and desired; Bifrost gates publication/merge/escalation, not every local edit. Future migration plans must make that autonomy typed, branch-contained, receipt-backed, interruptible, private-state-sealed, and cross-body-safe rather than turning Epiphany into a human-permission queue. - `service-execution-runbook` makes that next cut repeatable: it generates the exact elevated wrapper command sequence without mutating the service manager, continues after per-step failure to preserve more receipts, runs `service-execution-audit` in `finally`, exits nonzero if any step failed, and seals a typed runbook lifecycle receipt. Run the generated artifact only with explicit operator authority. - `service-execution-audit` is the non-mutating acceptance proof after the elevated rite: it reports `complete` only when typed lifecycle receipts prove the runbook witness plus expected elevated chain, and otherwise reports the missing/failed sealed checks. - `service-tick` is the non-elevated scheduler pulse proof: it writes the latest daemon scheduler receipt through durable policy ownership and local wrapper receipts. diff --git a/state/ledgers.msgpack b/state/ledgers.msgpack index fcd56a02c5dcc684387e60f6cb135e4525f4128f..25382bd9305ab55a1ba64f1a10d1abf49a67b5b6 100644 GIT binary patch delta 426 zcmYL_u}i~16vj>4O>iiy~%zd8^w+ z=WfyQ+^c8zZPDqS-!H#c-SwN%MN4dlVHAeXDq~U#Ientphj)5Jagn36$U&o`z?4kq zaB_JDtgs|0uOKFAHH&T3uBb3D(M-l^kWtJsC`r#iNFz7`lW?qrN|~$zD&>tc9uu!X z7^eUeld3fwI2xgm`%tDLLl}!hld&*m77eIkl8KmEL2{U*p5hRV`>0tow5?Q=I7XqY z8U9fk4eGh`FKkL$*lGakkaMS$