docs: honest status — T18/T19/T20 deferrals, integration-layer scaffold, performance claim caveat

Append DEVIATIONS §4-§6 for the T18 node lifecycle, T19 bin wiring with
clap exit handling, and T20 verification-gate scaffolds. Replace the
placeholder README with a pre-alpha project overview that names the
shipped architecture and the deferred "faster than Bitcoin Core"
empirical validation (G14).

Op: correct
Restores: spec:README.md must reflect implementation state, not
aspiration; DEVIATIONS.md must track deviations from PLAN.md

Author: metaphorics

DEVIATIONS.md

@@ -138,3 +138,46 @@ and names `SipHash-1-3` for GCS element hashing. Bitcoin Core's
 The filters crate follows Bitcoin Core's vector-compatible behavior because the
 Task 9 acceptance test explicitly requires byte-identical filter and header
 matches against `bitcoin/src/test/data/blockfilters.json`.
+
+## §4 — T18 node lifecycle scaffold
+
+The `bitcoin-rs-node` crate landed with the lifecycle skeleton (config
+layering, tracing, metrics in-process, signal-bridge, graceful drain,
+crash-recovery sidecar) but does NOT yet construct chain / utxo /
+mempool / index / p2p / rpc / electrum subsystems. `EventLoop::spin`
+handles shutdown + tick channels only; tick handlers are stubs.
+Subsystem wiring lands in a follow-up.
+
+- Files: `crates/node/src/{config.rs,state.rs,run.rs,event_loop.rs,crash_recovery.rs,signal.rs,shutdown.rs,logging.rs,metrics.rs,bitcoin_conf_compat.rs}`
+- Commit: 33333f9 + 304259f
+
+## §5 — T19 bin wiring + clap exit handling
+
+`bin/bitcoin-rs/src/main.rs` boots `Config::load_from_args` →
+`node::run`. `Config::load_from_args` distinguishes `clap::Error` kinds
+`DisplayHelp` / `DisplayVersion` and calls `err.exit()` so `bitcoin-rs
+--help` and `--version` return exit code 0 — the standard clap idiom.
+A `utreexo` feature was added to `crates/node/Cargo.toml` as a
+passthrough to `dep:bitcoin-rs-utreexo` to make the bin's feature table
+resolvable.
+
+- Files: `bin/bitcoin-rs/{Cargo.toml,src/main.rs,tests/cli_help.rs}`, `crates/node/{Cargo.toml,src/config.rs}`
+- Commit: 47af93b
+
+## §6 — T20 gates scaffold + integration-layer deferral
+
+G1..G14 acceptance tests are scaffolded under
+`bin/bitcoin-rs/tests/gates/`. Live-infrastructure gates (G1, G2, G3,
+G5, G6, G8, G9, G14) are `#[ignore]`d with run instructions in
+doc-comments. Wrapper gates (G4, G7, G10, G11, G12) shell out to
+in-tree crate tests. G13 (lints clean) is `#[ignore]`d because CI
+already runs clippy in a dedicated job; the gate body documents the
+exact invocation.
+
+The `"faster than Bitcoin Core"` performance budget claim (G14) cannot
+be validated in-session — it requires multi-day mainnet IBD benchmarks
+against a reference bitcoind. The gate is scaffolded as a structural
+placeholder. Live infrastructure runs are operator responsibilities.
+
+- Files: `bin/bitcoin-rs/{Cargo.toml,tests/gates/g{01..14}_*.rs}`
+- Commit: 144e2c1 + 61ae824

README.md

@@ -1,13 +1,52 @@
 # bitcoin-rs
 
-Ultra-fast Bitcoin full node in Rust 2024.
+A Rust 2024 Bitcoin full node aiming at faster IBD and a tighter resident set
+than `bitcoind` while remaining consensus-compatible.
 
-Single binary. Native UTXO set (gocoin-shape). Embedded Electrum-style index
-(electrs-shape). Optional utreexo accumulator (utreexod-shape). In-process
-PSBT-only wallet (no private keys). In-process getblocktemplate mining.
-Pruning. BIP157/158 compact filters. coinstats. Four pluggable storage
-backends (RocksDB / MDBX / fjall / redb). SIMD JSON on the RPC hot path.
+## Status
 
-Status: in active implementation. See [`PLAN.md`](PLAN.md).
+**Pre-alpha scaffold.** The workspace has 18 structurally complete crates, but
+the integration layer (`run` loop ↔ chain ↔ utxo ↔ p2p ↔ rpc ↔ electrum) lands
+in following commits. Empirical "faster than Bitcoin Core" validation requires
+live mainnet IBD against reference `bitcoind` and is tracked as verification
+gates G1-G14 in `PLAN.md`.
 
-License: MIT OR Apache-2.0.
+## Architecture highlights
+
+- Consensus parity via vendored Bitcoin Core test vectors and an optional
+  `bitcoinkernel` cross-check gate.
+- Four pluggable storage backends: RocksDB (default), MDBX, fjall, redb —
+  selected at runtime via `--storage-backend`. The 4-backend equivalence test
+  produces an identical aggregate hash on every IBD.
+- 256-shard arena-backed UTXO set (bumpalo + hashbrown) with snapshot format
+  and crash-safe defrag.
+- Optional utreexo (Pollard + Stump + MemForest) for stateless validation.
+- Native Electrum-style index, BIP157/158 filters, coinstats (muhash), pruning
+  with Core's 288-block reorg-safety floor.
+- PSBT-only wallet: no signing key handling, only an external signer trait.
+- `getblocktemplate` mining endpoint.
+- Sync HTTP/1.1 JSON-RPC over sonic-rs with Core-compatible method names;
+  signing methods return -32603 "wallet has no private keys".
+- mimalloc global allocator and a crossbeam-channel event loop.
+
+## Build
+
+```sh
+cargo build --release --features rocksdb,fjall,redb,mdbx
+```
+
+Feature flags: `rocksdb` / `fjall` / `redb` / `mdbx` (defaults all on),
+`kernel` (link against `bitcoinkernel`), `utreexo`, `prometheus-http`.
+
+## Tests
+
+```sh
+cargo test --no-default-features --features rocksdb,fjall,redb
+```
+
+Live-infrastructure gates are `#[ignore]`d; invoke them individually with
+`-- --ignored` after wiring the documented environment.
+
+## License
+
+MIT OR Apache-2.0