NEEDLE CLAUDE.md

NEEDLE Project Conventions

Overview

NEEDLE (Navigates Every Enqueued Deliverable, Logs Effort) is a Rust bead worker binary. It automates bead processing by running the bf CLI (bead-forge) to select, claim, dispatch an AI agent, and handle outcomes.

MSRV

Minimum Supported Rust Version: 1.75 (2023-12-28).

Pinned in rust-toolchain.toml. Do not add dependencies that require a newer Rust edition without updating MSRV and rust-toolchain.toml.

Module Dependency Graph

cli
 └─ worker
     ├─ strand ─ bead_store ─ types
     ├─ claim  ─ bead_store, telemetry, types
     ├─ prompt ─ config, types
     ├─ dispatch ─ config, telemetry, types
     ├─ outcome  ─ bead_store, config, telemetry, types
     ├─ health   ─ config, telemetry, types
     ├─ bead_store ─ types
     ├─ telemetry  ─ types
     └─ config     ─ types

Leaf modules (no internal deps): types, config, telemetry, bead_store, health.

Code Style

• No unwrap() or expect() in non-test code — use ? with anyhow.
• All public functions return Result<T>.
• Telemetry must be emitted at every state transition and outcome.
• Match arms must be exhaustive — no catch-all _ on outcome enums.
• Run cargo clippy --all-targets -- -D warnings before committing.
• Run cargo fmt before committing.

Testing

• Unit tests live in #[cfg(test)] modules in each source file.
• Integration tests live in tests/.
• Do not use tokio_test::block_on — use #[tokio::test].
• Test the public interface, not internals.

Test Isolation Policy

CRITICAL: Any integration test that spawns the compiled needle binary as a real subprocess via Command::new(CARGO_BIN_EXE_needle) MUST isolate both $HOME and the Explore strand's scan root.

The Explore strand (enabled by default via ExploreConfig::default_enabled()) scans workspace_root (defaulting to $HOME) for bead workspaces. Without isolation, a test's spawned binary will leak into the real user environment and scan real repos, contaminating both the test and production bead stores.