todie · Oct 12, 2026 · Oct 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Comprehensive crate-level documentation and README files across all workspace crates (`crates/ep`, `crates/ep-domain`, `crates/escapement-core`, `crates/escapement-serve`, `crates/blackwall-bridge`).
+- LeanSpec frontmatter and canonical section alignment (`Requirements`, `Design`, `Tasks`, `Verification`, `Notes`) for `SPEC-0001` and `SPEC-0002`.
+- Tri-license documentation block (`Apache-2.0 OR MIT OR CC0-1.0`) across root and crate documentation.
+- Specification registry and authentic Git commit locators in `specs/README.md`.
+- Keep-a-Changelog scaffolding and tracking file `CHANGELOG.md`.
+
+### Changed
+- Restructured root `README.md` to include Crate Responsibility Matrix, Zero-I/O Domain Isolation rules, host throttling invariants, and concrete CLI usage examples.
+- Updated `ROADMAP.md` to reference crate READMEs and formal LeanSpec specifications.
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+## [0.1.0] - 2026-10-12
+
+### Added
+- Metered, deterministic dispatch engine and event reactor workspace in pure Rust.
+- Core dispatch, capability matching, custody DAGs, priority lanes, and token bucket rate limiting in `escapement-core`.
+- Zero-I/O domain types and algebraic state machines in `ep-domain`.
+- Single-writer orchestrator daemon and HTTP service with OpenTelemetry export in `escapement-serve`.
+- Blackwall custody confinement adapter and execution bridge in `blackwall-bridge`.
+- Unified binary CLI entrypoint and registry inspection in `ep`.
+- Formal specifications `SPEC-0001` (Escapement Scheduler) and `SPEC-0002` (Roadmap & Evolution Horizons).
diff --git a/README.md b/README.md
@@ -1,45 +1,83 @@
 # ep — Escapement Scheduler & Deterministic Event Reactor
 
-[![License: Apache-2.0 OR MIT](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue.svg)](https://github.com/unsigned-gg/.github)
+[![License: Apache-2.0 OR MIT OR CC0-1.0](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT%20OR%20CC0--1.0-blue.svg)](https://github.com/unsigned-gg/.github)
 
 > Metered, deterministic dispatch engine and event reactor for autonomous agent constellations.  
-> Pure-Rust, zero-dependency core dispatch, capability matching, custody DAGs, and tick scheduling.  
-> Dual-licensed under `Apache-2.0 OR MIT` and dedicated to the open testbed of mutual cooperation between man and machine.
+> Pure-Rust workspace with zero-dependency core dispatch, capability matching, custody DAGs, and tick scheduling.  
+> Tri-licensed under `Apache-2.0 OR MIT OR CC0-1.0` and dedicated to the open testbed of mutual cooperation between man and machine.
 
 ## Philosophy & Foundations
 
-- **Champion Inspiration:** Carl Lerche & Leslie Lamport
+- **Champion Inspiration:** Carl Lerche, Leslie Lamport, and Mara Bos.
 - **Zero Days Open Source Initiative (ZOSI):** Absolute machine sympathy, deterministic scheduling, and low-level mechanical efficiency.
 - **Contract:** Zero zombies, strictly bounded memory queues, deterministic custody handoffs, and provable termination.
 
-## Workspace Architecture
+## Architectural Invariants & Machine Sympathy
 
-- **`crates/ep`**: Unified binary CLI and runtime interfaces.
-- **`crates/ep-domain`**: Zero-I/O domain models, validation, and algebraic state machines.
-- **`crates/escapement-core`**: Core deterministic dispatch engine, custody DAGs, task registry, capability matching, and telemetry.
-- **`crates/escapement-serve`**: HTTP and gRPC orchestration server with Tempo/Jaeger OpenTelemetry tracing.
-- **`crates/blackwall-bridge`**: Sandbox confinement adapter and isolated process execution bridge.
+1. **Substantive Systems Implementation:** Fully functional deterministic scheduler and event reactor with zero vanity stubs.
+2. **Zero-I/O Domain Isolation:** The `ep-domain` crate maintains zero dependencies on `std::fs`, `std::net`, `std::process`, or asynchronous runtimes. All domain models and state transitions execute entirely in memory.
+3. **Controlled Language (ASD-STE100):** Documentation and specifications follow Simplified Technical English standards for precision and clarity.
+4. **Host Throttling (`-j 2` Mandatory):** All cargo invocations on multi-agent hosts MUST specify `-j 2` to prevent CPU starvation and memory exhaustion.
+5. **Deterministic Topological Scheduling:** Task execution DAGs validate cycle freedom and resolve deterministic execution order sorted by `(priority, submit_time, node_id)`.
+6. **Zero Zombie Custody:** Admitted tasks transition through atomic compare-and-swap handoffs. No task remains unassigned without an active timeout watch.
+7. **Monotonic Integer Metering:** Capabilities and rate limits use discrete integer token buckets refilled monotonically on tick boundaries without floating-point arithmetic.
 
-## Roadmap & Specifications
+## Crate Responsibility Matrix
 
-- **Roadmap Overview**: See [`ROADMAP.md`](ROADMAP.md) for current capabilities and development horizons.
-- **Formal Specifications**: See [`specs/`](specs/) for architectural contracts and operational invariants:
-  - [`SPEC-0001: Escapement Scheduler & Deterministic Event Reactor`](specs/SPEC-0001-escapement-scheduler.md)
-  - [`SPEC-0002: Escapement Protocol Roadmap & Evolution Horizons`](specs/SPEC-0002-roadmap.md)
+| Crate | Path | Responsibility |
+| :--- | :--- | :--- |
+| **`ep`** | [`crates/ep`](crates/ep) | Unified CLI binary and runtime interface. Dispatches commands, inspects registries, and manages local daemon instances. |
+| **`ep-domain`** | [`crates/ep-domain`](crates/ep-domain) | Pure zero-I/O domain types, algebraic state machines, and validation logic. |
+| **`escapement-core`** | [`crates/escapement-core`](crates/escapement-core) | Core deterministic dispatch engine, custody DAGs, capability matching, token buckets, priority lanes, WAL persistence, and telemetry. |
+| **`escapement-serve`** | [`crates/escapement-serve`](crates/escapement-serve) | Single-writer orchestrator daemon, HTTP and gRPC orchestration server with OpenTelemetry tracing export. |
+| **`blackwall-bridge`** | [`crates/blackwall-bridge`](crates/blackwall-bridge) | Sandbox confinement adapter and isolated process execution bridge for Blackwall run custody. |
+
+## CLI Usage
+
+### Inspect Local Registry
+```bash
+# Print escapement banner and query active agents in the registry
+cargo run -j 2 -p ep
+```
+
+### Run Orchestrator Daemon
+```bash
+# Start the single-writer HTTP orchestrator daemon on port 8080
+cargo run -j 2 -p escapement-serve -- --config escapement.toml
+```
+
+### Submit Dispatched Run to Blackwall Bridge
+```bash
+# Verify isolated process custody through blackwall bridge
+cargo test -j 2 -p blackwall-bridge
+```
 
 ## Building & Verification
 
-All cargo invocations on multi-agent hosts MUST specify `-j 2`:
+All cargo invocations on host `ceres` MUST specify `-j 2`:
 
 ```bash
-cargo build -j 2
-cargo test -j 2
+# Compile entire workspace under host throttling
+cargo build -j 2 --workspace
+
+# Run full test suite (162 unit and integration tests)
+cargo test -j 2 --workspace
+
+# Generate local workspace documentation
+cargo doc -j 2 --workspace --no-deps
 ```
 
+## Formal Specifications & Roadmap
+
+- **Roadmap Overview**: See [`ROADMAP.md`](ROADMAP.md) for evolution horizons and milestones.
+- **Formal Specifications**: See [`specs/`](specs/) for LeanSpec contracts and operational invariants:
+  - [`SPEC-0001: Escapement Scheduler & Deterministic Event Reactor`](specs/SPEC-0001-escapement-scheduler.md) (`unsigned-gg/ep@6765df9:specs/SPEC-0001-escapement-scheduler.md`)
+  - [`SPEC-0002: Escapement Protocol Roadmap & Evolution Horizons`](specs/SPEC-0002-roadmap.md) (`unsigned-gg/ep@6765df9:specs/SPEC-0002-roadmap.md`)
+
 ## License
 
-Dual-licensed under `Apache-2.0 OR MIT`.
+Tri-licensed under `Apache-2.0 OR MIT OR CC0-1.0`.
 
 ## Principles
 
-See the [unsigned-gg principles](https://github.com/unsigned-gg/.github) for the architectural doctrine and community standards.
+See the [unsigned-gg principles](https://github.com/unsigned-gg/.github) for architectural doctrine and community standards.
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -5,20 +5,21 @@
 
 ---
 
-## Current State (v1.0.0 Foundation)
+## Current State (v0.1.0 Foundation)
 
-- **v1.0.0 core shipped**: 162 unit tests passing, clippy clean (`-D warnings`), 5 crates.
-- **`escapement-core`**: Zero-dependency pure-Rust engine:
+- **Foundation Core Shipped**: 162 unit tests passing, clippy clean (`-D warnings`), 5 crates documented.
+- **[`escapement-core`](crates/escapement-core/README.md)**: Zero-dependency pure-Rust engine:
   - Deterministic DAG topological resolver (`plan.rs`) with Kahn's algorithm and `BTreeSet` tie-breaking.
   - Nine-state atomic task lifecycle state machine (`dispatch.rs`).
   - BLAKE3 cryptographic custody provenance and chain propagation (`custody.rs`).
   - Strongly typed wire protocol (`protocol.rs`) with version negotiation (`PROTOCOL_VERSION = "0.1"`).
   - Leaky token-bucket metering and weighted fair queueing scheduler (`metering.rs`, `lanes.rs`).
   - Append-only Write-Ahead Log (WAL) persistence and crash recovery (`persistence.rs`).
   - Adaptive backpressure, tenant budgets, and scale-to-zero waker hooks (`backpressure.rs`, `budget.rs`, `waker.rs`).
-- **`blackwall-bridge`**: Landlock sandbox execution adapter.
-- **`ep-domain`**: Zero-I/O domain types and algebraic state models.
-- **`escapement-serve`**: Daemon prototype with HTTP endpoints (`/healthz`, `/dispatch`, `/jobs`) and OTLP tracing.
+- **[`blackwall-bridge`](crates/blackwall-bridge/README.md)**: Landlock sandbox execution adapter.
+- **[`ep-domain`](crates/ep-domain/README.md)**: Zero-I/O domain types and algebraic state models.
+- **[`escapement-serve`](crates/escapement-serve/README.md)**: Single-writer daemon prototype with HTTP endpoints (`/health`, `/v1/tasks/admit`, `/v1/plans/submit`) and OTLP tracing.
+- **[`ep`](crates/ep/README.md)**: Unified CLI runtime interface.
 
 ---
 

diff --git a/crates/blackwall-bridge/README.md b/crates/blackwall-bridge/README.md
@@ -0,0 +1,61 @@
+# blackwall-bridge (Blackwall Custody & Confinement Adapter)
+
+Integration layer between the Escapement scheduler and Blackwall's isolated process execution and custody verification engine.
+
+Part of [unsigned.gg](https://unsigned.gg).
+
+| Attribute | Specification |
+|---|---|
+| Status | Functional, integration tests passing |
+| Roadmap Phase | Phase 1 (Core Engine Foundation) |
+| Layer | Layer 2 (Execution Bridge) |
+| Depends On | `escapement-core`, `ep-domain` |
+| Invariants | [`SPEC-0001 §4 Landlock Isolation`](../../specs/SPEC-0001-escapement-scheduler.md) |
+
+## Overview
+
+- **Crate Type:** `lib`
+- **License:** `Apache-2.0 OR MIT OR CC0-1.0`
+
+This crate maps an escapement [`Task`](../escapement-core/src/dispatch.rs) to a Blackwall run specification (prompt, provider, model, max turns, timeout) and maps Blackwall run records back to cryptographic [`CustodyRef`](../escapement-core/src/custody.rs) hashes.
+
+## Core Modules
+
+| Module | Description |
+| :--- | :--- |
+| **`execution`** | Manages plan execution pipelines and process lifecycle boundaries. |
+| **`receive`** | Ingests completed run records from external workers into custody storage. |
+| **`serve`** | Optional MCP tool dispatch interface (`POST /v1/mcp/tools/dispatch`). Enabled via `serve` feature flag. |
+| **`settle`** | Verifies task settlement, final token expenditures, and BLAKE3 custody proofs. |
+
+## Invariants & Design
+
+1. **Subprocess Isolation:** The bridge executes the `blackwall` binary via `std::process::Command`, maintaining strong isolation without external network transport dependencies.
+2. **Cryptographic Settlement:** Completed runs yield a 256-bit BLAKE3 hash representing execution history, verified before transitioning tasks to `Completed`.
+3. **Controlled Error Propagation:** Non-zero exit codes from child sandboxes map to structured `BridgeError` variants without panics.
+
+## Feature Flags
+
+- **`serve`**: Activates HTTP serve bridge and MCP tool dispatch endpoints (`ServeBridge`, `ServeConfig`).
+
+## Usage Example
+
+```rust
+use blackwall_bridge::{BridgeConfig, RunHandle};
+use escapement_core::dispatch::Task;
+
+let config = BridgeConfig::default();
+// Bridge dispatches task into isolated blackwall sandbox
+```
+
+## Verification
+
+Run all bridge integration tests under host throttling:
+
+```bash
+cargo test -j 2 -p blackwall-bridge
+```
+
+## License
+
+Tri-licensed under `Apache-2.0 OR MIT OR CC0-1.0`.
diff --git a/crates/ep-domain/README.md b/crates/ep-domain/README.md
@@ -0,0 +1,36 @@
+# ep-domain (Zero-I/O Domain Models)
+
+Pure zero-I/O domain models, algebraic state machines, and validation assertions for `ep`.
+
+Part of [unsigned.gg](https://unsigned.gg).
+
+| Attribute | Specification |
+|---|---|
+| Status | Functional, unit tests passing |
+| Roadmap Phase | Phase 1 (Core Engine Foundation) |
+| Layer | Layer 0 (Zero-I/O Domain Models) |
+| Depends On | None (Pure Domain, zero workspace deps) |
+| Invariants | [`SPEC-0001 §3 Zero-I/O Isolation`](../../specs/SPEC-0001-escapement-scheduler.md) |
+
+## Architectural Invariants
+
+1. **Zero-I/O Isolation:** This crate contains zero dependencies on `std::fs`, `std::net`, `std::process`, or asynchronous runtimes (`#![forbid(unsafe_code)]`).
+2. **Pure Data Transformations:** All state models, transitions, and validation checks execute entirely in memory.
+3. **Deterministic Serialization:** Models implement `Serialize` and `Deserialize` using `serde` for stable transport encoding.
+4. **Controlled Language (ASD-STE100):** State models and transitions follow explicit, unambiguous definitions.
+
+## Key Types
+
+- [`EpState`](src/lib.rs): Core protocol versioning and state identity representation.
+
+## Verification
+
+Run domain tests under host throttling:
+
+```bash
+cargo test -j 2 -p ep-domain
+```
+
+## License
+
+Tri-licensed under `Apache-2.0 OR MIT OR CC0-1.0`.
diff --git a/crates/ep/README.md b/crates/ep/README.md
@@ -0,0 +1,52 @@
+# ep (CLI & Runtime Interface)
+
+Unified CLI binary and runtime interface for the Escapement scheduler and deterministic event reactor.
+
+Part of [unsigned.gg](https://unsigned.gg).
+
+| Attribute | Specification |
+|---|---|
+| Status | Functional CLI binary |
+| Roadmap Phase | Phase 2 (Unified CLI & Ergonomics) |
+| Layer | Layer 3 (Runtime Interface & CLI) |
+| Depends On | `escapement-core`, `escapement-serve`, `blackwall-bridge`, `ep-domain` |
+| Invariants | [`SPEC-0002 §3 Phase 2`](../../specs/SPEC-0002-roadmap.md) |
+
+## Overview
+
+- **Binary Name:** `ep`
+- **Crate Type:** `bin`, `lib`
+- **License:** `Apache-2.0 OR MIT OR CC0-1.0`
+
+This crate re-exports the workspace primitives and provides the command-line entry point for managing agent registrations, inspecting dispatch queues, and launching orchestrator nodes.
+
+## Re-exported Modules
+
+- `ep::bridge`: Blackwall custody and confinement adapter (`blackwall-bridge`).
+- `ep::core`: Core dispatch engine, custody tracking, and DAG solver (`escapement-core`).
+- `ep::EpState`: Zero-I/O domain types (`ep-domain`).
+
+## CLI Usage
+
+```bash
+# Display CLI version and registered agent count
+cargo run -j 2 -p ep
+
+# Inspect task queue and state
+cargo run -j 2 -p ep -- status
+```
+
+## Architectural Invariants
+
+1. **Host Throttling:** Multi-agent hosts require `-j 2` on all build and test invocations.
+2. **Thin Binary:** All core scheduling algorithms reside in `escapement-core` and domain models in `ep-domain`. The CLI provides only argument parsing, environment loading, and terminal output.
+
+## Verification
+
+```bash
+cargo test -j 2 -p ep
+```
+
+## License
+
+Tri-licensed under `Apache-2.0 OR MIT OR CC0-1.0`.