swarm-orchestrator: Instructions file for Claude Code

CLAUDE.md

Swarm Orchestrator v13: an evidence-first coding agent. Every claim of completed work must resolve to machine-captured evidence in a tamper-evident ledger. Quality gates run and auto-resolve under a ratchet. Local model selection is measured, never guessed. Full rationale lives in docs/build-guide.md; read it before structural work.

Commands

• npm run typecheck : tsc, strict, no emit
• npm run lint : Biome check
• npm run format : Biome format, write
• npm test : Vitest, full suite
• npm run gates : all of the above in sequence; this is the definition of green
• npm run dev : run the CLI from source against a scratch workspace

Run npm run gates before claiming any task complete. Paste the real output. Never summarize gate results from memory.

Architecture Map

• src/agent-run.ts : one task start to finish (policy guard, tools, chokepoint, loop, gates). The CLI and every parallel worker call this same function; a worker differs in its directory, its chain, and one optional tool, the peer trail, which the single-agent path is never offered and which leaves its prompt byte-identical.
• src/core : agent loop. Plan, act, verify. All stochastic inputs (clock, random, model) injected via interfaces, never imported directly.
• src/tools : read, write, edit, shell, search, list. Every call goes through the chokepoint in src/tools/chokepoint.ts: ledger record, provenance tag, policy-guard enforcement. No tool may bypass it. The guard is a lexical path and program policy, not a sandbox: what a run actually executes under is measured by the containment self-test in src/exec and recorded as an execution-envelope record.
• src/exec : process execution shared by tools and gates: the environment a child is given (built, never inherited), the process-group lifecycle that stops what a command started, the containment self-test that decides a run's execution mode, and the container backend that mode can be earned against. Imported by src/tools and src/gates; imports neither.
• src/evidence : append-only JSONL ledger, hash chain, content-addressed blob store, evidence DAG, bundle export, embedded verifier, HTML review renderer.
• src/gates : gate definitions as data, runner, auto-resolve loop with ratchet, escalation.
• src/providers : the only module allowed to import the Vercel AI SDK. Frontier plus OpenAI-compatible local (Ollama, rapid-mlx). Local endpoint discovery.
• src/select : hardware probe, static shortlist fit, calibration micro-eval, bandit reward log.
• src/workers : phase 6 scale-out. Git worktree per worker, each running the ordinary loop from src/agent-run.ts, and a merge queue that lands them sequentially under the ratchet. Nothing here is imported by the single-agent path.
• src/tui : Ink single-screen UI. Renders exclusively from ledger projections.
• src/config : Zod-validated swarm.toml, zero-config defaults.