benbrownandClaude Fable 5
6e169ab819
The cross-harness skill shipped (PR #17/#19) with README/CLAUDE.md/AGENTS.md
coverage, but the mdBook — the public disclosure surface — had zero mention
of it. By this project's own standard that is a parity defect: the flagship
consumable feature was undocumented where it is disclosed.
- New chapter "Consume it: the peltier skill" (docs/src/skill.md): install
paths and the harness matrix, the ZeroClaw script-blocking variant, the
gate order verify mode enforces, the refusal doctrine, and exactly which
of these claims CI asserts. Numbers carry their CI and workload.
- SUMMARY.md, architecture.md (layout now lists the skill + mirror),
reproduce.md, introduction.md: cross-links to the chapter.
- docs.yml: pull requests now BUILD the book (never deploy) — a broken
chapter or dangling include is a red PR check, not a post-merge surprise.
Also closes an audit finding: the book rebuilds when results/** changes,
since case-study chapters {{#include}} evidence files from there.
Book build verified locally with mdbook 0.4.x (skill.html renders).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3.2 KiB
Architecture
Peltier is split into a trust layer (Rust, the agent cannot write it) and an untrusted proposer (the agent). The split is structural, not advisory: the guarantees hold even if the proposer is adversarial.
crates/ Trust layer — agent has NO write access (SPEC §10)
bench-runner/ Interleaved A/B timing, bootstrap CIs, A/A calibration,
service-mode latency (coordinated-omission correct)
diff-test/ Equivalence gates, corpus hash-pinning, per-target spec
ledger/ Append-only SQLite attempt ledger (enforced by triggers)
report/ ROI: speedup CI → cores → dollars, methodology inline
verdict/ The pipeline in one command: gates → bench → ledger row
harnessd/ The one door the agent talks through (7 JSON ops)
agent/ Untrusted proposer (Claude Agent SDK, Python)
playbook/ Optimization classes 1–7, tried strictly cheapest-first
config/ accept.toml (thresholds), pricing.toml (ROI inputs)
targets/ Vendored OSS targets — the only agent-writable path
corpora/ Hash-pinned golden-replay inputs (read-only to agent)
results/ Calibration evidence, case studies, generated reports
.claude/skills/ The trust layer as a consumable Agent Skill — mirrored
byte-identically at .agents/skills/ (CI-enforced); see
"Consume it: the peltier skill"
The seven-tool boundary
The agent never runs a shell, never writes a file, never touches the
ledger directly. It speaks to harnessd — the only door — through exactly
seven JSON operations:
| Tool | What it can do |
|---|---|
read_profile |
Read a target's ranked hotspots (read-only) |
read_ledger |
Read prior attempts — the anti-double-attempt memory |
read_playbook |
Read an optimization class's preconditions/procedure |
read_target_source |
Read a workspace file at the pinned commit (windowed) |
propose_patch |
Submit a unified diff — path-allowlisted, then git apply |
run_verdict |
Launch the gate+bench pipeline (detached) |
read_verdict |
Poll the append-only ledger for the result |
Note what is absent: no write outside targets/<name>/workspace, no
shell, no way to run the bench or write the ledger except through the
verdict binary, which only records a pass after the full gated pipeline.
The data flow of one attempt
profile ─▶ agent hypothesizes ─▶ propose_patch ─▶ [path allowlist + git apply]
│
ledger row ◀─ verdict ◀─ bench (interleaved A/B) ◀─ gates (tests, golden,
(append-only) vs pristine-rebuilt fuzz, sanitizers)
baseline
The baseline is rebuilt from a pristine checkout every session — never from the agent's workspace — so a patch cannot poison its own comparison. The verdict is decided by the CI-lower-bound rule and written to an append-only ledger the agent cannot mutate.
The next chapters walk each stage: measurement, equivalence gates, the agent loop, and the isolation that makes the boundary load-bearing.