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
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;
check for `AGENTS.md` and `Cargo.toml` to see whether M1 has started.
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.
- `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`,
@@ -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)
- `make gate` runs `cargo fmt --check`, clippy with warnings denied, `cargo test`, `cargo-deny`,
and a check that fails on any source file over 500 lines. Run it before calling any work done,
and report the exit status and last lines.
- `make gate` runs offline: `cargo fmt --check`, clippy with warnings denied, `cargo test`,
`cargo-deny`, and a check that fails on any source file over 500 lines. Run it before calling
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>`.
- `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.
- `gatewayd` is the Mattermost channel. Outbound only, no listening port; approvals arrive as
replies or reactions over the WebSocket.
- `inferproxy` is a ~100-line byte forwarder to `llama-server`. Drop it if M0 shows
`llama-server` can serve a Unix socket on the same host.
- `inferproxy` is a ~100-line byte forwarder from a Unix socket to the shared `llama-server`
router on the host. It is required, because `loopd` has no network.
- `proto` holds shared types. `toolkit` holds tool container entrypoints.
Structural rules that span crates:
- 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
policy module can construct one (covered by a compile-fail test).
- Authority is encoded in types. A tool can't run without a `Decision`. It is defined in
`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.
- Files are the source of truth (`sessions/`, `memory/`, `grants/`, `audit/`). SQLite is only
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,
heartbeat notes, memory refreshes, recalled memory) goes only in the newest message, never in
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.
- 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
put in the baseline.
measured with the server's tokenizer.
- Compaction happens only when the session is idle, and starts a new epoch
(`sessions/<id>/<epoch>.jsonl`). Old logs are kept.
- Main session, subagents and scheduled jobs each use their own server slot.
- Streaming always. Timeouts are "no bytes for N seconds", never total deadlines.
- Every request carries `id_slot`, and a session never changes slot. The server is shared, so
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
+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 |
| 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
@@ -40,7 +41,4 @@ Approved by the owner on 2026-09-17. One commit each.
## 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.
| # | Change | Evidence |
|---|---|---|
None pending.