docs: add corrected shared cutover plan (Sam & Claude)
Verified, shared version of the cutover orchestration plan in docs/, correcting the .hermes/plans draft against the actual repos: - Kill the fabricated clawdie-ai crates/colibri-daemon (no crates/ dir exists there; the real daemon is Unix-socket in the colibri repo, not axum/HTTP). - Fix baseline to160dd11(65 tests pass/0 fail, clippy -D warnings clean);eb37784was not clippy-clean. - Reaffirm the Herdr boundary: Linux/macOS display/remote plane, no Herdr on FreeBSD; colibri-glasspane is the native answer (Lane 2 reframed). - Correct ownership: Claude=domedog=Linux, Codex=osa=FreeBSD, Hermes=debby=Linux. - Surface the Postgres coupling as an explicit open decision, not a given. - Downgrade the overclaimed debby<->domedog herdr smoke test to "not yet done." Leaves the .hermes draft untouched; marked DRAFT/PROPOSED pending ratification. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
160dd1100e
commit
09259394b9
1 changed files with 164 additions and 0 deletions
164
docs/COLIBRI-CUTOVER-PLAN.md
Normal file
164
docs/COLIBRI-CUTOVER-PLAN.md
Normal file
|
|
@ -0,0 +1,164 @@
|
|||
# Colibri Cutover Plan — clawdie-ai (TS) → Colibri (Rust)
|
||||
|
||||
**Status:** DRAFT / PROPOSED — 27.maj.2026. Shared, verified version of the
|
||||
orchestration plan. Supersedes the working draft `.hermes/plans/2026-05-27-colibri-cutover.md`
|
||||
(see "Corrections from the draft" below).
|
||||
|
||||
**Goal:** progressively replace the clawdie-ai TypeScript control plane with the
|
||||
Colibri Rust core as the FreeBSD system service, with the FreeBSD-native
|
||||
supervision boundary intact and each step proven before takeover.
|
||||
|
||||
---
|
||||
|
||||
## Corrections from the `.hermes` draft
|
||||
|
||||
The earlier draft asserted several things that don't match the repos. Fixed here:
|
||||
|
||||
| Draft claim | Reality (verified 27.maj) |
|
||||
|-------------|---------------------------|
|
||||
| `clawdie` repo has `crates/colibri-daemon/` (event.rs/state.rs/ingestor.rs/snapshot.rs, **axum HTTP**) | `clawdie-ai` has **no `crates/` dir**. The Rust daemon lives only in the **`colibri` repo**, and it is **Unix-socket** (`socket.rs` `UnixListener`), not HTTP. |
|
||||
| Baseline `eb37784` — "62 tests, clippy-clean" | `eb37784` carried the `collapsible_match` clippy errors (fixed in `5d45a0f`). Accurate baseline: **`160dd11` — 65 tests passed/0 failed, `clippy -D warnings` clean**. |
|
||||
| "`herdr --remote` debby↔domedog already smoke-tested" | Only a one-off domedog→debby attach occurred. The **hub direction (debby→domedog) is not tested** — herdr client isn't installed on debby yet (see `HERDR-HUB-RUNBOOK.md`). |
|
||||
| Herdr as "drop-in for Clawdie's tmux-based agent **execution**" on FreeBSD | Contradicts the settled boundary (`MIGRATION-INVENTORY.md` §3, `862204c`): **no Herdr on FreeBSD**. Herdr is a Linux/macOS **display/remote** client; `colibri-glasspane` is the FreeBSD-native supervision. Reframed in Lane 2. |
|
||||
| Owner "Claude (osa, FreeBSD validation)" | **Claude = domedog = Linux. Codex = osa = FreeBSD. Hermes = debby = Linux.** FreeBSD validation/build is Codex's lane. |
|
||||
|
||||
---
|
||||
|
||||
## Verified current state (27.maj.2026)
|
||||
|
||||
| Repo | Branch | Baseline | Notes |
|
||||
|------|--------|----------|-------|
|
||||
| `colibri` | main | `160dd11` | 65 tests pass / 0 fail; `clippy -D warnings` clean; 7 crates |
|
||||
| `clawdie-ai` | main | `169bee2` | TS control plane (the cutover *source*); **no Rust crates** |
|
||||
| `clawdie-iso` | main | `b9803d8` | has a Colibri dependency section in `AGENTS.md` |
|
||||
| `herdr` | main | `ede2059` *(per Hermes; not verified from domedog)* | Linux/macOS display client |
|
||||
|
||||
### What actually exists in Colibri today
|
||||
|
||||
- **Rust workspace, 7 crates** (`colibri-contracts`, `-deepseek`, `-runtime`,
|
||||
`-glasspane`, `-daemon`, `-client`, `-glasspane-tui` + root bins). Builds and
|
||||
tests green on Linux (debby/domedog) and FreeBSD (osa).
|
||||
- **`colibri-daemon`** — always-on service over a **Unix socket** (newline-JSON):
|
||||
`config/daemon/session/socket/spawner`. Not HTTP.
|
||||
- **`colibri-glasspane`** — FreeBSD-native agent supervision; 5-state machine
|
||||
derived from Pi `--mode json` events; `clawdie.glasspane.snapshot.v1`.
|
||||
- **`colibri-client`** — typed Unix-socket client; live socket smoke test.
|
||||
- Proof gates 1–6 green per `MIGRATION-INVENTORY.md`; gate 7 (multi-host
|
||||
coordination) pending.
|
||||
|
||||
### The TS side being retired (in `clawdie-ai`)
|
||||
|
||||
Contract sources already mirrored into Rust: `src/colibri-pi-events.ts`,
|
||||
`colibri-run-manifest.ts`, `colibri-runtime-inventory.ts`, `colibri-host-status.ts`,
|
||||
`colibri-pi-run.ts`. Load-bearing runtime kept until cutover: `agent-runner.ts`
|
||||
(the Pi host runner), `jail-exec-runner.ts` (`jailPi`), `watchdog.ts`, `hostd`.
|
||||
|
||||
---
|
||||
|
||||
## Open decisions (resolve before the lanes they gate)
|
||||
|
||||
1. **Coordination-core storage (gates Lane 1 / Phase 3).** The draft assumed
|
||||
"Postgres-backed (reuse clawdie-ai's `system_ops` DB)." That couples the lean
|
||||
cross-platform Colibri core to clawdie-ai's existing schema — convenient for
|
||||
dual-run parity, but the opposite of a clean-room cutover and a heavy dep for
|
||||
a "single small binary." **Decide explicitly:** (a) reuse `system_ops`
|
||||
Postgres, (b) Colibri-owned Postgres, or (c) embedded store (SQLite) with a
|
||||
Postgres adapter. Default lean choice: (c) unless dual-run parity needs (a).
|
||||
2. **Herdr boundary (gates Lane 2).** Reaffirmed: Herdr stays Linux/macOS
|
||||
display/remote only. If anyone wants Herdr in the FreeBSD execution path,
|
||||
that reopens `MIGRATION-INVENTORY.md` §3 and needs an explicit reversal.
|
||||
|
||||
---
|
||||
|
||||
## Lane 1 — Colibri core
|
||||
|
||||
**Owner:** Hermes (debby/Linux) → Codex (osa/FreeBSD validation).
|
||||
|
||||
- **T1.1 Stabilize baseline.** `cargo test --workspace && cargo clippy
|
||||
--workspace --all-targets -- -D warnings`; record exact counts; commit any
|
||||
fmt/clippy fixes. *(Green at `160dd11`.)*
|
||||
- **T1.2 Phase 3 — coordination core.** Task board with explicit lifecycle
|
||||
(queued→claimed→started→done/failed); agents-as-teammates; skills catalog.
|
||||
**Blocked on Open Decision #1 (storage).**
|
||||
- **T1.3 Phase 4 — execution & scheduling.** cron/interval/one-time scheduler;
|
||||
Pi engine integration via the events parser; Telegram-intake compatibility.
|
||||
- **T1.4 Phase 5 — cache-first prompt discipline.** Deterministic 3-region
|
||||
prompt assembler; cost modes (fast/smart/max); visible escalation.
|
||||
- **T1.5 Phase 6 — gated cutover.** Replace TS control-plane paths only after
|
||||
proof gates pass; **separate deprecation PR per path**.
|
||||
- **FreeBSD validation (each step):** push → Codex on osa runs `cargo test` on
|
||||
FreeBSD 15 → record `rustc --version`, `freebsd-version`, exact output.
|
||||
|
||||
*(Phase numbers per `clawdie-ai/doc/COLIBRI-CONTROLPLANE-PLAN.md`; distinct from
|
||||
the migration phases in `MIGRATION-INVENTORY.md`.)*
|
||||
|
||||
## Lane 2 — Herdr compatibility (Linux display plane)
|
||||
|
||||
**Owner:** Hermes (debby) + Codex (osa, for the FreeBSD-side socket).
|
||||
|
||||
Herdr consumes Colibri's socket/snapshot API as a **display/remote client**;
|
||||
it is not an execution layer and not on FreeBSD.
|
||||
|
||||
- **T2.1 Snapshot API consumption.** Verify a Herdr-Linux client can read
|
||||
`clawdie.glasspane.snapshot.v1` over the daemon Unix socket (and the future
|
||||
HTTP/SSE transport when it lands).
|
||||
- **T2.2 Remote attach over Tailscale.** Complete the debby→domedog hub attach
|
||||
(install herdr client on debby; `herdr --remote domedog-ts-herdr`). Per
|
||||
`HERDR-HUB-RUNBOOK.md`. *(Not yet done — supersedes the draft's "already
|
||||
smoke-tested.")*
|
||||
- **T2.3 Compatibility manifest.** Produce `herdr-clawdie-compat.v1`: protocol
|
||||
version, socket/snapshot schema, transport, known gaps.
|
||||
- **Gate:** compat manifest signed → IMG deployment unblocked.
|
||||
|
||||
## Lane 3 — ISO build chain
|
||||
|
||||
**Owner:** Hermes (coordination) → Codex (osa, FreeBSD build).
|
||||
|
||||
- **T3.1 Assess ISO state.** Review the operator-USB round scope; check the
|
||||
Colibri dependency section in `clawdie-iso/AGENTS.md`.
|
||||
- **T3.2 Colibri artifact integration.** Define which Colibri binary the ISO
|
||||
bundles; FreeBSD `rc.d` service for the daemon; firstboot starts Colibri
|
||||
alongside clawdie-ai **during the dual-run transition only**.
|
||||
- **T3.3 Build handoff.** ISO handoff doc for Codex: exact Colibri commit hash,
|
||||
target triple (`x86_64-unknown-freebsd`), TLS = rustls, build flags.
|
||||
|
||||
## Lane 4 — Gradual phase-out (clawdie-ai TS → Colibri Rust)
|
||||
|
||||
**Owner:** shared (Hermes + Claude + Codex + Sam). Conservative, reversible.
|
||||
|
||||
- **T4.1 Dual-run (passive).** Colibri daemon runs beside clawdie-ai on FreeBSD;
|
||||
both consume Pi JSONL; compare state snapshots. No takeover.
|
||||
- **T4.2 State-parity gates.** Task-board state, agent lifecycle transitions,
|
||||
and watchdog host-status ingestion all match between the TS control plane and
|
||||
the Rust daemon.
|
||||
- **T4.3 Read-only takeover.** Colibri serves snapshots; clawdie-ai's TS UI reads
|
||||
from the Colibri API. Prove the Rust daemon is the source of truth.
|
||||
- **T4.4 Write takeover.** Colibri owns scheduling + agent dispatch; clawdie-ai
|
||||
reduced to Telegram intake.
|
||||
- **T4.5 Full cutover.** clawdie-ai control plane stopped; Colibri `rc.d` service
|
||||
is the sole control plane; clawdie-ai service disabled. Watchdog/`hostd`
|
||||
FreeBSD safety stays locally authoritative throughout.
|
||||
|
||||
---
|
||||
|
||||
## Dependency graph
|
||||
|
||||
```text
|
||||
Lane 1 (Colibri core) ───────────────────────────┐
|
||||
├──→ Lane 4 (phase-out)
|
||||
Lane 2 (Herdr display compat) ──→ IMG unblocked ──┤
|
||||
│
|
||||
Lane 3 (ISO build) ───────────→ Colibri in ISO ───┘
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
- Commit prefixes `feat:`/`fix:`/`docs:`/`refactor:`/`test:`.
|
||||
- Attribution `(Sam & Hermes)` / `(Sam & Claude)` / `(Sam & Codex)`.
|
||||
- Cross-repo references in the commit body when relevant.
|
||||
|
||||
## Next actions
|
||||
|
||||
1. Resolve Open Decision #1 (coordination-core storage) — unblocks Lane 1 T1.2.
|
||||
2. Complete Lane 2 T2.2 (debby→domedog herdr attach) per the runbook.
|
||||
3. Reconcile or retire the `.hermes` draft against this version.
|
||||
Loading…
Add table
Reference in a new issue