bunqueue: Instructions file for Claude Code

bunqueue

MANDATORY — SKEPTIC AGENT: before every git commit and every git push, invoke the skeptic agent and wait for its verdict. It must read the complete staged diff, identify at least three potential failure points per changed file, and verify race conditions, error handling, idempotency, type safety and test coverage. FAIL blocks commit and push; CONDITIONAL requires the user's explicit confirmation. The project profile is .claude/agents/skeptic.md.

ENGLISH ONLY: keep all repository content in English, including source comments, tests, technical documentation, user documentation and agent configuration.

"When I report a bug, don't start by trying to fix it. Instead, start by writing a test that reproduces the bug. Then, have subagents try to fix the bug and prove it with a passing test."

MANDATORY: After ANY code modification, run the isolated validation before committing:

bun run test:sandbox

It builds the current worktree once and runs ALL THREE required suites concurrently in separate disposable containers:

bun test --parallel=4                   # Unit tests (four isolated file workers)
bun scripts/tcp/run-all-tests.ts        # TCP integration tests (~50 suites)
bun scripts/embedded/run-all-tests.ts   # Embedded integration tests (~35 suites)

Never commit without all three passing. No exceptions.

MANDATORY for core queue semantics: run the real-broker model before the sandbox:

bun run test:model

Run it after every change to lifecycle transitions, SQLite/write buffering, startup or stall recovery, priority/FIFO/LIFO/delay scheduling, FIFO groups, dependencies, dedup/custom IDs, leases, limits, TTL, counters, temporal indexes, or jobIndex. The fast-check model executes generated command histories against a fresh TCP broker and SQLite database, including actual SIGKILL restarts. It checks conservation, no loss/resurrection/duplicate active lease, retry and stall bounds, legal transitions, ordering, resource limits, counter/index coherence, idempotent recovery, and DLQ exactly-once.

On failure, retain the seed, minimized command history, and replay path. If the engine is wrong, add a deterministic test/repro-model-*.test.ts that fails before changing runtime code; if the specification is wrong, correct the model with evidence. Never weaken an invariant to make a campaign green. Deeper replay (BUNQUEUE_MODEL_COMMANDS is only the real bound with BUNQUEUE_MODEL_SIZE=max; at fast-check's default size a history has at most 10 commands):

BUNQUEUE_MODEL_RUNS=500 BUNQUEUE_MODEL_COMMANDS=150 BUNQUEUE_MODEL_SIZE=max \
BUNQUEUE_MODEL_SEED=-1959189325 bun run test:model

Replay one failure exactly with the seed, path and size fast-check prints: BUNQUEUE_MODEL_SEED=<seed> BUNQUEUE_MODEL_PATH=<path> BUNQUEUE_MODEL_SIZE=<size> bun run test:model.

This targeted command does not replace bun run test:sandbox; the full bun test --parallel=4 unit command inside the sandbox runs the model again.

MANDATORY: After ANY modification under sdk/, run before handoff (and run again before committing if the SDK changed afterward):

bun run test:sandbox:sdk

It runs every official external SDK's native tests and shared protocol conformance checks in isolated disposable containers. SDK changes require both full gates (test:sandbox and test:sandbox:sdk); targeted native tests do not replace either one. Review artifacts/test-sandbox-sdk/<timestamp>/summary.md and its JSON/NDJSON artifacts before handoff.