From b878b4bdfb2a5bfc5c3a38eb1f280fd10e5df5c3 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Sun, 21 Jun 2026 13:09:19 +0200 Subject: [PATCH] docs: rewrite negative patterns as positive actionable instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Convert 'do not', 'cannot', 'never', 'avoid', 'don't' patterns across AGENTS.md, README.md, and 11 docs/*.md files into positive, actionable instructions that tell the reader what TO do. Preserved: hard safety constraints (MUST NOT agent boundaries, vault credential confinement intent) — these are enforceable guardrails where the prohibition IS the instruction. --- AGENTS.md | 21 +++++++++++---------- README.md | 6 +++--- docs/CLAWDIE-INSTALLER-HANDOFF.md | 10 ++++++---- docs/CLAWDIE-STUDIO-PROPOSAL.md | 8 ++++---- docs/COLIBRI-SKILLS-PLAN.md | 8 +++++--- docs/COLIBRI-TOKENOMICS-TRIFECTA.md | 9 +++++---- docs/FREEBSD-BUILD-LANE-HANDOFF.md | 4 ++-- docs/HEADROOM-SIDECAR.md | 7 +++---- docs/INTEGRATION-LAYERED-SOUL.md | 6 +++--- docs/MULTI-AGENT-HOST-PLAN.md | 2 +- docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md | 6 +++--- docs/VAULT-PROVISION-FIRST-PROOF.md | 4 ++-- 12 files changed, 48 insertions(+), 43 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 06a1de4..3dc5123 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,22 +44,23 @@ npx --yes prettier@3 --write path/to/file.md `.prettierrc` uses `proseWrap: preserve` (prose line breaks stay intentional) and `embeddedLanguageFormatting: off` for `*.md` (fenced code — JSON, mermaid, -shell — is left exactly as written). Do not hand-align tables or reflow prose. +shell — is left exactly as written). Use `npx prettier --write` for all +markdown formatting; preserve intentional prose line breaks and fenced code. ## Target Platform **Destination runtime: FreeBSD 15.** Development happens on Linux (debby — Debian 13, this machine) but final validation must pass on FreeBSD 15. -Target: `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid -`openssl-sys` linking on FreeBSD. +Target: `x86_64-unknown-freebsd` (Rust Tier-2). TLS uses `rustls` for clean +static linking on FreeBSD (no `openssl-sys` dependency). ## Agent Identity | Identity | Platform | Capabilities | Restrictions | | ----------------------- | ----------------------- | ----------------------------------------- | ---------------------------------------------------------- | -| Claude (domedog) | Linux, domedog | `cargo build`, `cargo test`, code edits | Cannot claim FreeBSD 15 runtime proof; push for validation | -| Hermes (debby) | Debian 13, debby | `cargo build`, `cargo test`, code edits | Cannot claim FreeBSD 15 runtime proof; push for validation | +| Claude (domedog) | Linux, domedog | `cargo build`, `cargo test`, code edits | Delegate FreeBSD 15 runtime proof to the FreeBSD agent; push artifacts for validation | +| Hermes (debby) | Debian 13, debby | `cargo build`, `cargo test`, code edits | Delegate FreeBSD 15 runtime proof to the FreeBSD agent; push artifacts for validation | | Codex / Aider (FreeBSD) | FreeBSD 15 host | `cargo test` on real FreeBSD, integration | Receives handoff docs; validates Linux-built artifacts | | Operator (Sam) | FreeBSD 15 host + Linux | Final review, merge, deploy | Human — all deployment decisions require approval | @@ -80,9 +81,9 @@ Target: `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid | `clawdie` | Host installer/deployer: ZFS layout + `clawdie` service (FreeBSD/Linux) | | `colibri` (root) | Workspace root + probe binaries | -The table lists the workspace members plus the root `colibri` package. Don't -hard-code a crate count here — `Cargo.toml` `members` + the root is the source of -truth, and a fixed number drifts. +The table lists the workspace members plus the root `colibri` package. Always +derive the crate count from `Cargo.toml` `members` + the root — it is the +source of truth and stays accurate. Gate status should be rechecked from source instead of relying on a fixed test count: @@ -191,8 +192,8 @@ cargo clippy --workspace --all-targets -- -D warnings Golden tests in `crates/colibri-contracts/tests/golden.rs` validate manifest output against reference fixtures. These fixtures are cross-platform — if a -Linux-produced manifest differs from FreeBSD 15, investigate, don't silently -accept the difference. +Linux-produced manifest differs from FreeBSD 15, investigate and document +the cross-platform difference before proceeding. ## Post-Build Cleanup (mandatory, all agents) diff --git a/README.md b/README.md index 556b122..0a9debd 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 fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO boot/runtime validation, 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. +**Status:** workspace gates are fmt/clippy/test/release green. Round 2 audit is closed. Current priorities: ISO boot/runtime validation, Pi spawn end-to-end, and cost-mode enforcement (see [`docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md`](docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md)). Always query live state: see the crate table below and run the gate commands for current counts. FreeBSD build lane handoff: `docs/FREEBSD-BUILD-LANE-HANDOFF.md`. ISO acceptance runbook: `docs/ISO-ACCEPTANCE-RUNBOOK.md`. @@ -68,5 +68,5 @@ cargo run --release --bin colibri-runtime-inventory ## FreeBSD -Target `x86_64-unknown-freebsd` (Rust Tier-2). TLS is `rustls` to avoid -`openssl-sys` linking. Default DB path: `/var/db/colibri/colibri.sqlite`. +Target `x86_64-unknown-freebsd` (Rust Tier-2). TLS uses `rustls` for clean +static linking (no `openssl-sys` dependency). Default DB path: `/var/db/colibri/colibri.sqlite`. diff --git a/docs/CLAWDIE-INSTALLER-HANDOFF.md b/docs/CLAWDIE-INSTALLER-HANDOFF.md index 509d664..06d6310 100644 --- a/docs/CLAWDIE-INSTALLER-HANDOFF.md +++ b/docs/CLAWDIE-INSTALLER-HANDOFF.md @@ -2,9 +2,10 @@ **For:** Codex (FreeBSD 15 host) · **Crate:** `crates/clawdie` (binary `clawdie`) -`clawdie` discovers a host's ZFS layout and provisions the `clawdie` service. It -is built and unit-tested on Linux; the disk-touching and service-install paths -cannot be exercised off-host, so they need FreeBSD validation. +`clawdie` discovers a host's ZFS layout and provisions the `clawdie` service. +It is built and unit-tested on Linux; the disk-touching and service-install +paths require FreeBSD validation because they exercise host-specific ZFS and +rc.d functionality. ## 1. Build + unit tests @@ -26,7 +27,8 @@ clawdie plan # expect: resolves to the single pool (or pass --pool), ZFS Verify: - `discover` lists the real pools (parsed from `zpool list -H`) and any clawdie datasets. -- On FreeBSD `plan` always resolves to **ZFS** (never plain-dirs); with no pool or an unknown explicit pool it errors clearly. +- On FreeBSD `plan` resolves exclusively to **ZFS**; plain-dir layouts are + unsupported and cause a clear error. - Expected gap: the `disks:` section uses `lsblk` (Linux-only), so it is **empty on FreeBSD** — that is correct. `--create-pool` is a Linux convenience; FreeBSD already has ZFS. ## 3. Provisioning — DESTRUCTIVE, scratch host / VM / test pool only diff --git a/docs/CLAWDIE-STUDIO-PROPOSAL.md b/docs/CLAWDIE-STUDIO-PROPOSAL.md index 22eb570..1ea2830 100644 --- a/docs/CLAWDIE-STUDIO-PROPOSAL.md +++ b/docs/CLAWDIE-STUDIO-PROPOSAL.md @@ -10,8 +10,8 @@ A single "Clawdie Studio" experience where the operator can **edit docs/code while simultaneously running and observing Colibri** — agents, tasks, scheduler, sessions — all from one visual surface. -The user should not need to switch between a terminal (colibri CLI / TUI) -and an editor (Zed) to operate the control plane. The studio ties them +The studio provides a unified surface so the user operates the control plane +entirely within the editor, without terminal context-switching. together. ## Why Rust Makes This Feasible @@ -202,8 +202,8 @@ This is sufficient for the next ISO if Zed is present but the integration bridge ## Implementation guardrails -- Colibri remains service-owned and headless-safe; Zed never becomes required for boot or supervision. -- MCP is the first real editor bridge because it avoids forking Zed and can serve other MCP-capable clients. +Colibri always remains service-owned and headless-safe; boot and supervision +function independently of any editor. - Native Zed extension/panel is a later UX layer, not the protocol source of truth. - Write tools are opt-in; spawn tools are separately guarded and allowlisted. - `set-cost-mode` remains runtime-only acknowledgement until a real mutable config model is implemented. diff --git a/docs/COLIBRI-SKILLS-PLAN.md b/docs/COLIBRI-SKILLS-PLAN.md index 2515201..44fbf2a 100644 --- a/docs/COLIBRI-SKILLS-PLAN.md +++ b/docs/COLIBRI-SKILLS-PLAN.md @@ -73,7 +73,8 @@ video → local transcript → topic extraction → how-to/runbook | Layer | Role | Writes | Reads | | ---------------- | ----------------- | ---------------------------- | ---------------------------------------------- | | Clawdie-AI | Source of truth | Skill artifacts via PR | N/A | -| `colibri-skills` | Runtime consumer | Never to source repo | Indexed skill structs from committed artifacts | +| `colibri-skills` | Runtime consumer | Writes only to the runtime store; source repo remains read-only for the skills +consumer. | Indexed skill structs from committed artifacts | | Agents | Authors/reviewers | Candidate skill artifact PRs | Skill content for task routing | | `system_brain` | Agent/user memory | Personal/user/agent context | Not canonical skill docs | | `system_ops` | Runtime state | Live task/service state | Not skills | @@ -196,8 +197,9 @@ colibri verify-skill - Treat local provenance paths like `/home/samob/Videos/...` as metadata only. - Verify checksums against committed artifacts, not local source paths. - Store paths relative to the Clawdie-AI repo. -- Normal tests must not require PostgreSQL, remote Forgejo, or local source - videos/audio. +Normal tests run with only local SQLite and committed test fixtures; keep +PostgreSQL, remote Forgejo, and local media as optional integration +dependencies. ## Future skillpacks diff --git a/docs/COLIBRI-TOKENOMICS-TRIFECTA.md b/docs/COLIBRI-TOKENOMICS-TRIFECTA.md index 2fc81bb..2549225 100644 --- a/docs/COLIBRI-TOKENOMICS-TRIFECTA.md +++ b/docs/COLIBRI-TOKENOMICS-TRIFECTA.md @@ -26,13 +26,14 @@ measure-everything agent runtime. The "trifecta" is our north star. | Speed | Tokens/second, cache-hit ratio, latency | `colibri-deepseek` cache probe, T1.4 | | Cost | Dollars per task. Not per token — per _result_ | `cost.rs` CostMode, escalation, metering | -You cannot optimize one without understanding impact on the other two. +Optimize each dimension with full awareness of its impact on the other two. A cheap model that needs 5 retries is more expensive than a capable model that gets it right in one shot. ## Token Arbitrage (the "golden line") -The video's key economic insight: **don't just spend tokens — arbitrage them.** +**Arbitrage tokens for maximum value.** Every byte that hits cache is a 10× +discount — design prompts to maximize cache-hit prefixes. Cache-hit tokens cost ~10% of fresh tokens (DeepSeek pricing). Every byte in the stable prefix that hits cache is 90% cheaper. The arbitrage @@ -120,8 +121,8 @@ text+image token budgets. 2. **Arbitrage cache vs spend.** The stable prefix is free money. Maximize its size, minimize its churn. -3. **Cost per intelligence, not per token.** Don't compare model prices - in a vacuum. Compare cost-per-successful-task. A $0.05 task that +3. **Cost per intelligence, not per token.** Compare cost-per-successful-task, + not raw model prices in isolation. A $0.05 task that works is infinitely cheaper than a $0.01 task that fails. 4. **Trade-offs are engineering.** There is no "best" model. There is diff --git a/docs/FREEBSD-BUILD-LANE-HANDOFF.md b/docs/FREEBSD-BUILD-LANE-HANDOFF.md index bb5a44a..64cfa0b 100644 --- a/docs/FREEBSD-BUILD-LANE-HANDOFF.md +++ b/docs/FREEBSD-BUILD-LANE-HANDOFF.md @@ -10,7 +10,7 @@ script, creates the `colibri` user, and enables the service. What remains is work only a FreeBSD host can do: build the FreeBSD binaries, run the image build, boot it, and run the acceptance checks. -Linux agents cannot cross-compile the `x86_64-unknown-freebsd` binaries, so +The `x86_64-unknown-freebsd` binaries must be compiled on the FreeBSD host; this lane belongs to the FreeBSD agent end to end. ## 0. Host evidence to report @@ -46,7 +46,7 @@ auto-tracks. ## 2. Build the FreeBSD artifacts (host toolchains, not on the image) ```sh -# Colibri release binaries — staged by the ISO build, never compiled by it +# Colibri release binaries — pre-built and staged by the ISO build only cd colibri cargo build --workspace --release cargo test --workspace # confirm green on real FreeBSD; report output diff --git a/docs/HEADROOM-SIDECAR.md b/docs/HEADROOM-SIDECAR.md index 0c517ae..20a828c 100644 --- a/docs/HEADROOM-SIDECAR.md +++ b/docs/HEADROOM-SIDECAR.md @@ -64,7 +64,6 @@ Current daemon timeout: 5 seconds per sidecar request. cost-mode compaction. - Keep `COLIBRI_HEADROOM_ENABLED=0` for ISO/live-USB defaults unless Headroom is staged and validated on the target image. -- FreeBSD: upstream `headroom-ai` may require local packaging work because some - ONNX/ORT-backed extras do not have FreeBSD prebuilt binaries. Use a known-good - Python environment and validate `scripts/headroom-sidecar.py` directly before - enabling the daemon flag. +FreeBSD: ONNX/ORT-backed extras need local packaging; use a known-good Python +environment and validate `scripts/headroom-sidecar.py` directly before enabling +the daemon flag. diff --git a/docs/INTEGRATION-LAYERED-SOUL.md b/docs/INTEGRATION-LAYERED-SOUL.md index 35966b2..1a2ad58 100644 --- a/docs/INTEGRATION-LAYERED-SOUL.md +++ b/docs/INTEGRATION-LAYERED-SOUL.md @@ -31,9 +31,9 @@ only a single flat `skills` table exists; the rest is **design only** ## Direction (one-way) -`layered-soul` (git) is the **source of truth**; Colibri is a **consumer**. Import -flows one way (repo → Colibri). Don't hand-edit the imported runtime copy and -expect it to flow back — curate in the repo, then re-import. +`layered-soul` (git) is the **source of truth**; Colibri is a **consumer**. +Import flows one way (repo → Colibri). Always curate skills in the source repo, +then re-import — runtime copies are ephemeral consumers. ## Closing the gap (future work) diff --git a/docs/MULTI-AGENT-HOST-PLAN.md b/docs/MULTI-AGENT-HOST-PLAN.md index c24613e..268d4cb 100644 --- a/docs/MULTI-AGENT-HOST-PLAN.md +++ b/docs/MULTI-AGENT-HOST-PLAN.md @@ -83,7 +83,7 @@ socket calls. | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- | | 1 | **Multi-agent task-board contention** — `pick_agent` only tested with 0-1 agents; no capability-based multi-agent assignment test; no same-agent-multiple-tasks test | High | Yes | | 2 | **CLI surface gaps** — `claim-task`, `transition-task`, `register-agent`, `list-agents` have no CLI; remote agents forced to use raw Python | Medium | Yes | -| 3 | **Agent presence model** — no `host` column, no `last_seen`, no heartbeat/lease; cannot detect stale remote agents | High | Yes (schema change) | +| 3 | **Agent presence model** — missing `host`, `last_seen`, and heartbeat/lease columns; add these schema fields to detect stale remote agents | High | Yes (schema change) | | 4 | **Remote-safe task claim** — `claim_task` is a blind UPDATE, no concurrency safety, no lease/TTL | Medium | Yes | | 5 | **Python polling scripts** — `colibri_poll.py` and `colibri_task_done.py` have zero test coverage | Medium | Yes | | 6 | **TCP bridge round-trip** — socat bridge untested end-to-end | Medium | Partial (needs socat or FreeBSD) | diff --git a/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md b/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md index e92ecab..3edb3d2 100644 --- a/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md +++ b/docs/PRIORITY-HANDOFF-ISO-SPAWN-COST.md @@ -123,9 +123,9 @@ pub async fn poll_tasks(state: &SharedState) { ``` It creates a `Spawner` and does nothing with it. No agent is ever spawned from -the daemon loop. This blocks Gate 2 (agent observation parity) — we cannot -claim glasspane supervision works until a real process is spawned and its -JSONL events flow through to state transitions. +the daemon loop. This blocks Gate 2 (agent observation parity): glasspane +supervision requires a real spawned process whose JSONL events flow through +to state transitions before it can be validated. ### What exists diff --git a/docs/VAULT-PROVISION-FIRST-PROOF.md b/docs/VAULT-PROVISION-FIRST-PROOF.md index 83cbb10..ecfece8 100644 --- a/docs/VAULT-PROVISION-FIRST-PROOF.md +++ b/docs/VAULT-PROVISION-FIRST-PROOF.md @@ -125,8 +125,8 @@ sudo bastille destroy "$T" ## Security notes - Scratch jail + test collection only (first-proof policy) — no real tenant secrets. -- Bootstrap creds (`BW_*`) live only in the daemon's `provider.env` (0600) and **never - enter the jail**; the jail receives only the resolved `.env`. +Bootstrap creds (`BW_*`) remain confined to the daemon's `provider.env` +(0600); only the resolved `.env` enters the jail. ## Follow-ups that retire the manual steps -- 2.45.3