Sync CLAUDE.md and decisions log with the amended brief

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
2026-09-17 00:38:54 -07:00
co-authored by Claude Fable 5.1
parent 0612d80aa2
commit fbc0f218dc
2 changed files with 22 additions and 17 deletions
+20 -13
View File
@@ -5,8 +5,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Current state ## Current state
Boxmaker is a sovereign personal agent harness written in Rust. There is no Rust code yet. Work Boxmaker is a sovereign personal agent harness written in Rust. There is no Rust code yet. Work
proceeds one milestone per session (M0 to M7, table in `docs/milestones.md`). M0 is mostly done; proceeds one milestone per session (M0 to M7, table in `docs/milestones.md`). M0 is done; check for `AGENTS.md` and `Cargo.toml` to see whether M1 has started.
check for `AGENTS.md` and `Cargo.toml` to see whether M1 has started.
- `docs/design.md` is the binding design brief. If it looks wrong or conflicts with a measurement, - `docs/design.md` is the binding design brief. If it looks wrong or conflicts with a measurement,
stop and say so. Changes to it land as their own commit and are recorded in `docs/decisions.md`, stop and say so. Changes to it land as their own commit and are recorded in `docs/decisions.md`,
@@ -25,9 +24,10 @@ requests, check `GET /slots?model=ornith-1.5-35b-a3b` so you do not evict someon
## Commands (planned in M1, not yet present) ## Commands (planned in M1, not yet present)
- `make gate` runs `cargo fmt --check`, clippy with warnings denied, `cargo test`, `cargo-deny`, - `make gate` runs offline: `cargo fmt --check`, clippy with warnings denied, `cargo test`,
and a check that fails on any source file over 500 lines. Run it before calling any work done, `cargo-deny`, and a check that fails on any source file over 500 lines. Run it before calling
and report the exit status and last lines. any work done, and report the exit status and last lines.
- `make verify-device` runs the checks that need straylight, such as the baseline token budget.
- Single test: `cargo test -p <crate> <test_name>`. - Single test: `cargo test -p <crate> <test_name>`.
- `bxctl` is the owner CLI (`bxctl chat` from M2, `bxctl reindex` from M5). - `bxctl` is the owner CLI (`bxctl chat` from M2, `bxctl reindex` from M5).
@@ -42,15 +42,16 @@ Separate binaries in one Cargo workspace. Each role holds as little authority as
JSONL audit log. JSONL audit log.
- `gatewayd` is the Mattermost channel. Outbound only, no listening port; approvals arrive as - `gatewayd` is the Mattermost channel. Outbound only, no listening port; approvals arrive as
replies or reactions over the WebSocket. replies or reactions over the WebSocket.
- `inferproxy` is a ~100-line byte forwarder to `llama-server`. Drop it if M0 shows - `inferproxy` is a ~100-line byte forwarder from a Unix socket to the shared `llama-server`
`llama-server` can serve a Unix socket on the same host. router on the host. It is required, because `loopd` has no network.
- `proto` holds shared types. `toolkit` holds tool container entrypoints. - `proto` holds shared types. `toolkit` holds tool container entrypoints.
Structural rules that span crates: Structural rules that span crates:
- No crate depends on another role's crate. Crates depend only on `proto`. - No crate depends on another role's crate. Crates depend only on `proto`.
- Authority is encoded in types. A tool can't run without a `Decision`, and only `brokerd`'s - Authority is encoded in types. A tool can't run without a `Decision`. It is defined in
policy module can construct one (covered by a compile-fail test). `brokerd` with a private field and no `Deserialize`, so only the policy module can construct
one (covered by a compile-fail test). `proto` carries a plain `DecisionRecord`.
- No source file over 500 lines. - No source file over 500 lines.
- Files are the source of truth (`sessions/`, `memory/`, `grants/`, `audit/`). SQLite is only - Files are the source of truth (`sessions/`, `memory/`, `grants/`, `audit/`). SQLite is only
for rebuildable indexes and queues. for rebuildable indexes and queues.
@@ -63,14 +64,20 @@ its KV cache, so any change to an earlier byte of the prompt forces an expensive
- Each turn's request must be a strict extension of the previous one. Volatile content (time, - Each turn's request must be a strict extension of the previous one. Volatile content (time,
heartbeat notes, memory refreshes, recalled memory) goes only in the newest message, never in heartbeat notes, memory refreshes, recalled memory) goes only in the newest message, never in
the system prompt or earlier history. the system prompt or earlier history.
- Assistant messages are logged and replayed exactly as the server returned them, including
`reasoning_content` and `tool_calls`.
- The `tools` array is fixed per epoch; changing it re-reads the whole prompt. Other tools are
found with `find_tool` and called through the `call_tool` meta-tool. Never prompt the model to
call an undeclared tool: the server's grammar forces the call into a declared one.
- Tool results are size-capped when first appended and never trimmed later. - Tool results are size-capped when first appended and never trimmed later.
- The baseline (system prompt, tool schemas, `memory/core.md`) stays at 3,000 tokens or less, - The baseline (system prompt, tool schemas, `memory/core.md`) stays at 3,000 tokens or less,
measured with the server's tokenizer. Extra tool schemas are added through `find_tool`, not measured with the server's tokenizer.
put in the baseline.
- Compaction happens only when the session is idle, and starts a new epoch - Compaction happens only when the session is idle, and starts a new epoch
(`sessions/<id>/<epoch>.jsonl`). Old logs are kept. (`sessions/<id>/<epoch>.jsonl`). Old logs are kept.
- Main session, subagents and scheduled jobs each use their own server slot. - Every request carries `id_slot`, and a session never changes slot. The server is shared, so
- Streaming always. Timeouts are "no bytes for N seconds", never total deadlines. slots are not reserved: a cold cache is a normal event that `loopd` logs, never an error.
- Streaming always, with `return_progress: true`. Timeouts are "no bytes for N seconds", never
total deadlines, plus a longer limit for waiting on a busy slot or a model load.
## Working rules from the brief ## Working rules from the brief
+2 -4
View File
@@ -18,6 +18,7 @@ Newest first. A decision that changes `docs/design.md` lands in the same commit
|---|---| |---|---|
| Secret store backend, and where the v0 file's key lives. straylight has no secrets manager today. | M3 | | Secret store backend, and where the v0 file's key lives. straylight has no secrets manager today. | M3 |
| Whether cloud-led sessions are ever allowed, and for which data classes. | M6 | | Whether cloud-led sessions are ever allowed, and for which data classes. | M6 |
| Where the M5b embedding model runs. The brief says a separate `llama-server` instance, but under the shared router it would be a third model against `--models-max 2` and could unload Ornith or Laguna. | M5b |
## Applied to the design brief ## Applied to the design brief
@@ -40,7 +41,4 @@ Approved by the owner on 2026-09-17. One commit each.
## Proposed changes to the design brief ## Proposed changes to the design brief
From M0 and the kickoff review. None is applied yet. Each lands as its own commit once the owner agrees. None pending.
| # | Change | Evidence |
|---|---|---|