From 7853e5a2be8c80feb925368119cdb7ea8f96e9d7 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sun, 14 Jun 2026 13:35:37 +0200 Subject: [PATCH] docs: tidy formatting, add docs index, and refresh README status line --- README.md | 2 +- docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md | 56 +++++++++++++------------ docs/README.md | 24 +++++++++++ 3 files changed, 55 insertions(+), 27 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index bfd72f0..945ced5 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ The Clawdie control plane core — a small, cross-platform (FreeBSD + Linux) Rus daemon that unifies coordination (task board, agent registry, skills catalog) with cache-first cost discipline (byte-stable prompt prefixes, cache-hit metering). -**Status:** workspace gates are expected to be fmt/clippy/test/release green. Avoid fixed crate/test counts here — see the crate table below and run the gate commands for the current state. Phase 3 (coordination core) is in progress. +**Status:** workspace gates are fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO staging wiring, Pi spawn end-to-end, and cost-mode enforcement (see [`docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md)). Avoid fixed crate/test counts here — see the crate table below and run the gate commands for the current state. Next ISO integration plan: `docs/ISO-INTEGRATION-PLAN.md`. ISO acceptance runbook: `docs/ISO-ACCEPTANCE-RUNBOOK.md`. diff --git a/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md b/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md index 0337a82..61ff730 100644 --- a/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md +++ b/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md @@ -26,13 +26,13 @@ blocks Gate 1 (passive service) entirely. ### What exists -| Artifact | Location | Status | -| -------- | --------- | ------ | -| staging script | `scripts/stage-colibri-iso.sh` | done — copies `colibri-daemon`, `colibri`, `colibri-smoke-agent`, rc.d, newsyslog, creates dirs | -| rc.d script | `packaging/freebsd/colibri_daemon.in` | done — `start_precmd`, pidfile, daemon(8) wrapper, `COLIBRI_COST_MODE` propagation | -| newsyslog config | `packaging/freebsd/newsyslog-colibri.conf` | done | -| rc.conf.sample | generated by staging script | done | -| acceptance runbook | `docs/ISO-ACCEPTANCE-RUNBOOK.md` | done | +| Artifact | Location | Status | +| ------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------- | +| staging script | `scripts/stage-colibri-iso.sh` | done — copies `colibri-daemon`, `colibri`, `colibri-smoke-agent`, rc.d, newsyslog, creates dirs | +| rc.d script | `packaging/freebsd/colibri_daemon.in` | done — `start_precmd`, pidfile, daemon(8) wrapper, `COLIBRI_COST_MODE` propagation | +| newsyslog config | `packaging/freebsd/newsyslog-colibri.conf` | done | +| rc.conf.sample | generated by staging script | done | +| acceptance runbook | `docs/ISO-ACCEPTANCE-RUNBOOK.md` | done | ### What's missing @@ -110,14 +110,14 @@ JSONL events flow through to state transitions. ### What exists -| Capability | Location | Status | -| ---------- | -------- | ------ | -| `Spawner::spawn()` | `crates/colibri-daemon/src/spawner.rs:585` | done — provider routing, jail wrap, retry/backoff | -| `AgentHandle` | `crates/colibri-daemon/src/spawner.rs:465` | done — tracks child, stdout for glasspane, kill, poll_exit | -| `take_stdout()` | `crates/colibri-daemon/src/spawner.rs:500` | done — hands stdout to glasspane supervision | -| Jail confinement | `crates/colibri-daemon/src/spawner.rs:332` | done — named/ephemeral, staged env payload, priv modes | -| `fake-pi-agent.py` | `scripts/fake-pi-agent.py` | exists — emits JSONL events for testing | -| Glasspane ingestion | `crates/colibri-glasspane/` | done — ingests JSONL, tracks pane state | +| Capability | Location | Status | +| ------------------- | ------------------------------------------ | ---------------------------------------------------------- | +| `Spawner::spawn()` | `crates/colibri-daemon/src/spawner.rs:585` | done — provider routing, jail wrap, retry/backoff | +| `AgentHandle` | `crates/colibri-daemon/src/spawner.rs:465` | done — tracks child, stdout for glasspane, kill, poll_exit | +| `take_stdout()` | `crates/colibri-daemon/src/spawner.rs:500` | done — hands stdout to glasspane supervision | +| Jail confinement | `crates/colibri-daemon/src/spawner.rs:332` | done — named/ephemeral, staged env payload, priv modes | +| `fake-pi-agent.py` | `scripts/fake-pi-agent.py` | exists — emits JSONL events for testing | +| Glasspane ingestion | `crates/colibri-glasspane/` | done — ingests JSONL, tracks pane state | ### What's missing @@ -141,9 +141,11 @@ JSONL events flow through to state transitions. 3. **`spawn-local` socket command (if not present).** An operator CLI path to manually spawn a local binary for debugging: + ```sh colibri spawn-local /path/to/pi --session-id test-1 ``` + This may already exist as a socket command — check `socket.rs` for `SpawnLocal` or `Spawn` command variants. @@ -176,7 +178,7 @@ Cost modes (`Fast`/`Smart`/`Max`) are the core design promise of Colibri — escalation, compaction, trimming) but **they are not connected**. Right now changing the cost mode does nothing to actual session behavior. -This is the most subtle gap because the code *looks* like it's wired up — the +This is the most subtle gap because the code _looks_ like it's wired up — the functions exist and have tests — but the call sites are missing or duplicated. ### The disconnection (detailed) @@ -186,6 +188,7 @@ There are **two compaction paths** that use different sources of truth: **Path A — per-append (session.rs):** `session.rs:397-398` in `maybe_compact_or_rollover()`: + ```rust let needs_compaction = byte_count > self.config.session_max_bytes || turn_count > self.config.max_uncompacted_turns; @@ -200,6 +203,7 @@ values) regardless of the cost mode string. **Path B — background rotation (daemon.rs):** `daemon.rs:242-261` in `session_rotation()`: + ```rust let cost_mode = crate::cost::CostMode::parse(&state.config.cost_mode).unwrap_or_default(); let max_bytes = cost_mode.session_max_bytes(); @@ -216,12 +220,12 @@ loop catches up. ### What's never called -| Function | Location | Problem | -| -------- | -------- | ------- | -| `auto_escalate()` | `cost.rs:131` | Tested but **never called** from daemon loop or session code | -| `compact_tool_result()` | `cost.rs:165` | Tested but **never called** when appending `ToolResult` entries | +| Function | Location | Problem | +| ---------------------------------- | ---------------- | --------------------------------------------------------------------------------------- | +| `auto_escalate()` | `cost.rs:131` | Tested but **never called** from daemon loop or session code | +| `compact_tool_result()` | `cost.rs:165` | Tested but **never called** when appending `ToolResult` entries | | `PromptAssembly::trim_to_budget()` | `session.rs:117` | Tested but **never called** from `build_prompt_assembly()` or `build_prompt_messages()` | -| `EscalationTrigger` | `cost.rs:117` | Type exists, tested, never constructed in production code | +| `EscalationTrigger` | `cost.rs:117` | Type exists, tested, never constructed in production code | ### What `set-cost-mode` does @@ -280,11 +284,11 @@ wiring, no platform-specific behavior. ## Summary table -| # | Item | Blocks | Linux-doable | Effort | -| - | ---- | ------ | ------------ | ------ | -| 1 | ISO staging wiring | Gate 1 | partially (needs FreeBSD binaries) | medium | -| 2 | Pi spawn end-to-end | Gate 2 | yes (with fake-pi-agent.py) | medium | -| 3 | Cost mode enforcement | core design promise | yes (pure logic) | medium | +| # | Item | Blocks | Linux-doable | Effort | +| --- | --------------------- | ------------------- | ---------------------------------- | ------ | +| 1 | ISO staging wiring | Gate 1 | partially (needs FreeBSD binaries) | medium | +| 2 | Pi spawn end-to-end | Gate 2 | yes (with fake-pi-agent.py) | medium | +| 3 | Cost mode enforcement | core design promise | yes (pure logic) | medium | All three are medium effort and can be worked in parallel. None require FreeBSD to implement — only to validate the final result. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7f8f7fa --- /dev/null +++ b/docs/README.md @@ -0,0 +1,24 @@ +# Colibri Docs Index + +A quick-reference guide to every document in this folder. + +| Document | One-liner | Audience | +| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- | --------------- | +| [`ADR-agent-harness-consolidation.md`](ADR-agent-harness-consolidation.md) | zot = agent, Colibri = control plane — accepted ADR | All agents | +| [`CLAWDIE-INSTALLER-HANDOFF.md`](CLAWDIE-INSTALLER-HANDOFF.md) | FreeBSD validation handoff for the `clawdie` installer | Codex (FreeBSD) | +| [`CLAWDIE-STUDIO-PROPOSAL.md`](CLAWDIE-STUDIO-PROPOSAL.md) | Zed/Claude Code + control plane integration proposal | Sam & agents | +| [`COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md`](COLIBRI-DAEMON-GLASSPANE-INTEGRATION.md) | Binding contract between `colibri-daemon` and `colibri-glasspane` | Rust agents | +| [`COLIBRI-EXTERNAL-MCP-PROTOTYPE.md`](COLIBRI-EXTERNAL-MCP-PROTOTYPE.md) | Prototype for Colibri acting as an MCP host for external servers | Agents | +| [`COLIBRI-GLASSPANE-DESIGN.md`](COLIBRI-GLASSPANE-DESIGN.md) | Agent supervision (sessions/panes/state) design rationale | All agents | +| [`COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md`](COLIBRI-JAILED-AGENT-SPAWN-DESIGN.md) | FreeBSD jail confinement for spawned agents — accepted & implemented | Rust agents | +| [`COLIBRI-SKILLS-PLAN.md`](COLIBRI-SKILLS-PLAN.md) | Skills catalog roadmap: read-only Phase 1, write-gated Phase 2+ | Agents | +| [`COLIBRI-TOKENOMICS-TRIFECTA.md`](COLIBRI-TOKENOMICS-TRIFECTA.md) | Strategic vision: useful tokens, cost-per-intelligence, measurement | All | +| [`HEADROOM-SIDECAR.md`](HEADROOM-SIDECAR.md) | Optional `headroom-ai` tool-result compression sidecar | Agents | +| [`HERDR-VS-COLIBRI-GRAPH.md`](HERDR-VS-COLIBRI-GRAPH.md) | Capability comparison + drop map for Herdr → Colibri migration | All | +| [`INTEGRATION-LAYERED-SOUL.md`](INTEGRATION-LAYERED-SOUL.md) | How Colibri consumes `layered-soul` reviewed context today vs planned | Agents | +| [`ISO-ACCEPTANCE-RUNBOOK.md`](ISO-ACCEPTANCE-RUNBOOK.md) | Post-boot acceptance commands after staging Colibri into an ISO | Codex (FreeBSD) | +| [`ISO-INTEGRATION-PLAN.md`](ISO-INTEGRATION-PLAN.md) | Full plan to replace the TypeScript control path with Rust in the ISO | All | +| [`ISO-SERVICE-LAYOUT.md`](ISO-SERVICE-LAYOUT.md) | `rc.conf` service layout for the ISO image | All | +| [`MULTIAGENT-WORKFLOW-IMPROVEMENTS.md`](MULTIAGENT-WORKFLOW-IMPROVEMENTS.md) | Tracking gates, proof-gate-tracker, platform-matrix tests | All agents | +| [`PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](PRIORITY-HANDOFF-ISO-SPAWN-COST.md) | **Current sprint**: ISO staging wiring, Pi spawn path, cost mode enforcement | All agents | +| [`T1.4-PROMPT-DISCIPLINE-PLAN.md`](T1.4-PROMPT-DISCIPLINE-PLAN.md) | Cache-first prompt assembly: byte-stable prefixes + hit metering | Rust agents | -- 2.45.3