From 9ff0ad3bf2d8e0df2aa984966eab7a92997fc753 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 20 Jun 2026 01:06:42 +0100 Subject: [PATCH] Document repo swarm MVP migration --- notes/README.md | 3 + notes/epiphany-repo-swarm-mvp-contract.md | 109 ++++++++++++++++++++++ notes/fresh-workspace-handoff.md | 1 + state/ledgers.msgpack | Bin 307576 -> 307925 bytes 4 files changed, 113 insertions(+) diff --git a/notes/README.md b/notes/README.md index 26e86468..29da0893 100644 --- a/notes/README.md +++ b/notes/README.md @@ -14,6 +14,9 @@ contract docs. - `codex-auth-spine-inventory.md`: retained Codex auth/model transport keeper list. - `epiphany-fork-implementation-plan.md`: current campaign plan. - `epiphany-safety-architecture.md`: capability, autonomy, and governance boundaries. +- `epiphany-repo-swarm-mvp-contract.md`: repo-swarm autonomy contract and + migration plan from current front doors to an MVP that can run Epiphany swarms + for repositories. ## Contract Maps diff --git a/notes/epiphany-repo-swarm-mvp-contract.md b/notes/epiphany-repo-swarm-mvp-contract.md index 64ff2f99..58eac811 100644 --- a/notes/epiphany-repo-swarm-mvp-contract.md +++ b/notes/epiphany-repo-swarm-mvp-contract.md @@ -684,6 +684,115 @@ work through Self, executes through Hands, verifies through Soul, admits state through Mind, and publishes reviewed outcomes through Bifrost while private state stays sealed. +### Migration Thesis + +The migration is not from "agent with scripts" to "agent with more scripts." +It is from Codex-operated proof rites to an Epiphany-owned repo organism: + +```text +typed Body birth + -> local Verse online + -> Persona-facing idea intake + -> Imagination-authored concrete plan + -> Self-owned scheduler physiology + -> Substrate Gate scoped access + -> Hands branch-local consequence + -> Soul verification + -> Modeling map update + -> Mind state admission + -> Gjallar/Eve operator-safe sight + -> Bifrost publication and credit + -> upstream-main sync proof +``` + +The current front doors prove most of that artery in isolated rites. The MVP is +the point where the artery can run as a repo swarm: the human talks to the +project Persona, the swarm turns the idea into work, the branch changes under +typed authority, proof is published without private-state leakage, and upstream +main is proven rather than assumed. + +### MVP Status Board + +Use this board to decide whether a new slice belongs in the MVP or is a later +temptation wearing clean robes. + +| Surface | Current status | MVP migration requirement | +| --- | --- | --- | +| Repo Body birth | `epiphany-repo init` exists and writes repo-local stores plus branch workbench intent. | Keep birth startup-only, review-gated, and branch-oriented. | +| Local Verse online | `epiphany-swarm online` seeds repo-local CultMesh, standing-faculty SoA, topology, liveness, Eve, and tool sight. | Keep private Verse sealed while exposing operator-safe repo status. | +| Persona/Bifrost intake | `epiphany-work accept` records pressure and candidate action refs without Hands authority. | Add a repo Persona intake mouth so humans can talk to the project instead of hand-authoring CLI work items. | +| Imagination planning | `derive-plan` deterministically creates append-only worklog plans; `plan` remains manual quarantine scaffolding. | Replace operator-authored shell details with model-authored, typed Imagination action items for richer safe command families. | +| Self scheduling | `tick` and `serve` prove one-step branch-local advancement, brake refusal, active-turn refusal, cooldown, and stale-turn recovery. | Wire the same pulse into a usable repo-swarm run surface and optional Idunn-hosted lifecycle without taking Idunn's authority. | +| Branch-local Hands work | `adopt` and `execute` create approved Hands gates, run planned commands, stage declared paths, commit on `epiphany/*`, and write receipts. | Keep mutation branch-contained and receipt-backed; broaden only through typed plan families, not ad hoc shell freedom. | +| Soul/Modeling/Mind closure | `close` verifies the Hands commit and writes deterministic Soul, Modeling, and Mind receipts. | Add richer model-authored closure where useful, while preserving deterministic local closure for simple mechanical work. | +| Repo work sight | `overview` emits compact proof rows and mirrors latest `epiphany.cultmesh.repo_work_overview.v0`. | Project queue and multiple-work-item rows through Gjallar/Eve so Persona and peers can see current gate, blocker, and next safe action. | +| Publication | `publish` routes Bifrost/GitHub receipts from closure or explicit Soul/Mind refs. | Keep publication Bifrost-owned; do not let scheduler publish. | +| Upstream main sync | `sync` proves the published commit is contained by upstream main after explicit merge/sync authority. | Treat upstream-main sync as a required final proof for published work. | +| Daemon survival | Idunn service lifecycle receipts and runbooks exist outside repo-work tick authority. | Preserve Idunn as lifecycle owner; repo swarm may request or inspect service state, not impersonate daemon keeping. | +| Global tools | The daemon tool directory exposes globally invokable typed capabilities with host-owned execution receipts. | Ensure any agent can discover and request any authorized daemon-hosted tool through CultMesh without moving execution ownership into the caller. | + +### Authority Matrix + +The MVP succeeds only if each organ keeps its throne small enough to deserve it. + +| Organ or surface | Owns | Does not own | +| --- | --- | --- | +| Persona | Public conversation, project-facing speech, social pressure intake. | Durable state, direct repo mutation, publication, daemon lifecycle. | +| Imagination | Future-shape, concrete action plans, candidate work decomposition. | Shell execution, verification verdicts, state admission. | +| Self | Scheduling, routing, one-step branch-local advancement, active-turn/cooldown physiology. | Publication, merge, daemon service control, cross-repo mutation. | +| Substrate Gate | Scoped repo access grants and refusals. | Durable belief, verification truth, public speech. | +| Hands | Patches, commands, commits, PR receipts within granted branch/path scope. | Claiming correctness, map admission, upstream merge. | +| Soul | Verification verdicts, regression checks, refusal receipts. | Editing the Body, admitting durable state. | +| Modeling | Source-grounded map/checkpoint updates after verified consequence. | Acting on the Body, publishing, accepting itself into memory. | +| Mind | Durable state admission, rejection, and state-commit receipts. | Substrate access, public speech, service survival. | +| Gjallar | Whole-Verse/operator-safe sight rows over advertised state. | Discovery ownership, service lifecycle, mutation, private-state inspection. | +| Odin | Discovery, rendezvous, schema and surface awareness. | Provider ownership, daemon survival, repo mutation. | +| Idunn | Daemon/service lifecycle physiology, runbooks, scheduler service aftercare. | Repo work planning, branch commits, publication. | +| Bifrost | Publication, credit, ledger, merge/sync authority receipts. | Local branch implementation, private thought, daemon survival. | +| Eve/CultUI | Interface projection of typed state. | Source of truth or hidden action authority. | + +### Tool Availability Doctrine + +Every daemon-hosted tool in the local CultMesh network should be available to +any authorized agent at any time through typed capability discovery, invocation +intent, and receipt. This is global ergonomics, not global ownership. + +The hosting daemon owns execution. The caller owns the request. CultMesh carries +the capability surface and the receipt trail. If Hands asks Soul to verify, Soul +still owns the verification receipt. If Persona asks Hands for repo action, +Hands still owns the action gate. If Self asks Idunn for service health, Idunn +still owns the service lifecycle proof. This is how the swarm gets wide tool +reach without turning into one huge permission blob. + +For the repo-swarm MVP, global tool sight is complete enough when: + +- Gjallar/Odin can list daemon-hosted capabilities with host, operation, + authority gate, input contract, receipt contract, Eve surface, and readiness. +- Any standing agent can submit a typed invocation intent for an authorized + capability. +- The host daemon refuses unavailable, unauthorized, or sick-host requests with + typed receipts. +- Invocation results include compact readbacks for common status tools without + opening raw local Verse state or private worker thought. +- No wrapper, caller, or dashboard becomes the executor merely because it can + see the tool. + +### Sync To Upstream Main Doctrine + +Published work is not complete merely because a branch exists, a PR exists, or +a publication receipt exists. A repo swarm's public work item reaches the +upstream-complete state only when: + +- Bifrost or maintainer authority records publication/merge permission. +- The Hands commit being published is known. +- The configured upstream ref, normally `origin/main`, resolves. +- Git ancestry proves the Hands commit is contained by upstream main. +- `epiphany-work sync` writes a receipt with `upstreamMainSynced=true`. + +Until that proof exists, the compact gate should say publication or sync is +still blocking. Do not let cheerful PR-shaped artifacts impersonate mainline +truth. The Omnissiah can smell stale branches. + ### Current State: The Blessed Chain The repo swarm can already prove the following chain on a fresh repo Body: diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index fa8971ea..11e8fd78 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -103,6 +103,7 @@ remembers doctrine; the branch remembers the blade. - 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` is the repo-swarm MVP authority map and migration plan. It states the live thirteen-front-door chain from `epiphany-repo init` through `epiphany-work derive-plan`, `close`, `overview`, `tick`, `publish`, and `sync`, documents the operator-safe proof receipts already proved with `privateStateExposed=false`, and names the remaining MVP organs: model-authored Persona-to-plan depth, richer Gjallar/Eve presentation over repo work overview rows, optional execute-to-close handoff, richer published proof bundles, and richer model-authored closure. Autonomous branch-local work inside the owned repo Body is in scope and desired; Bifrost gates publication/merge/escalation, Idunn owns daemon lifecycle, and `epiphany-work tick` may only advance one safe receipt-backed branch-local step per pulse before stopping at closure or publication gates. `epiphany-work derive-plan` now consumes accepted Persona/Bifrost pressure and writes an Imagination/Self action plan in deterministic `append-worklog` quarantine mode with `operatorAuthoredShellDetails=false`; disposable smoke proved accept -> derive-plan -> run -> adopt -> execute -> close, changed only `EPIPHANY_WORKLOG.md`, ended `closed:passed`, and reported no private-state exposure. `epiphany-work overview` now reads the repo work receipt chain and writes an Eyes/Gjallar-owned sight/proof bundle with current gate, blocker, next safe action, branch, changed paths, commit SHA, Soul verdict, compact rows, and private-state seal; it also mirrors a typed `epiphany.cultmesh.repo_work_overview.v0` document into the repo-local Verse when a local Verse store is known. Disposable smokes proved pre-plan `awaiting-plan`/`plan-receipt-missing`, post-close `awaiting-publication`/`bifrost-publication-missing`, and latest-key CultMesh readback through `epiphany-verse-query smoke` as `latestRepoWorkOverview=repo-work-overview-verse-overview-request`, `latestRepoWorkGate=awaiting-publication`, `latestRepoWorkBlocker=bifrost-publication-missing`, with no private-state exposure. The tick pulse reads the repo-local CultMesh swarm brake and writes `refused-by-swarm-brake` without creating run/adopt/execute receipts when the brake is engaged. It also writes active-turn and last-completed scheduler receipts, refuses live duplicate pulses as `refused-active-turn`, refuses explicit completion-anchored cooldown as `refused-by-cooldown`, clears stale active markers after `--active-timeout-seconds`, and records `physiology.recoveredActiveTurn.recovered=true` when recovery proceeds. `epiphany-work serve` wraps that tick artery in Self-owned cadence: bounded `--max-iterations` proof mode writes `work-scheduler-serve-.json`, unbounded service mode relies on per-pulse tick receipts, and unbounded zero-second polling is refused. `epiphany-work close` consumes branch-local execute receipts, verifies the Hands commit, writes Soul verdict plus Modeling summary plus Mind gateway/state-commit receipts, and seals `work-close-.json` without granting publication, merge, service lifecycle, cross-repo mutation, or private-state exposure. `epiphany-work publish --closure-receipt` can consume the closure's Soul/Mind ids, while tick no-ops once closure exists before Bifrost publication authority. +- 2026-06-20: The same repo-swarm note now carries the explicit migration thesis, MVP status board, authority matrix, local CultMesh tool availability doctrine, and upstream-main sync doctrine. Use that note when answering "are we headed toward a functional swarm?" The answer is yes, but only if the remaining cuts preserve the typed organ ownership: Persona is the mouth, Imagination plans, Self schedules, Hands acts, Soul verifies, Modeling maps, Mind admits, Gjallar sees, Odin discovers, Idunn keeps daemon physiology alive, Bifrost publishes and credits, and Eve/CultUI renders without becoming truth. - `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 db7f60f4d75577d13a2dc92b76633c4e5b4d3497..ab0d4ee8d03aa3db2b3c7f083d3cb835e36171ab 100644 GIT binary patch delta 330 zcmX|+FHgik6vSz%Iz`R_<|R02FPoB_IE%gn0VhZh@7is