AI Swarm

src/lib/ai/swarm.ts coordinates role-specific AI work over a shared scratchpad. The launch pipeline is deterministic around safety: model-backed steps may draft or research, but the reviewer/verifier step does not call an LLM.

Canonical Roles

• Researcher: retrieves and summarizes relevant facts.
• Citator: gathers source spans and source-grounded citation material.
• Drafter: produces work product from prior outputs.
• Reviewer: runs deterministic verification over the drafter output.

demandPackagePipeline() wires the canonical Researcher + Citator -> Drafter -> Reviewer flow. The reviewer requires citations by default for this pipeline.

Safety Contract

• Every step writes to a shared scratchpad that later steps receive as ## Prior Agent Outputs.
• Reviewer steps run runTruthGuard() and verifySwarmOutput().
• Citation-required reviewer steps refuse output with no retrieved source spans, no inline [S#] references, dangling citations, or blocking Truth Guard issues.
• Refusals are structured with code, message, and requiredActions; callers should show these instead of unsafe generated work.
• Reviewer steps do not spend tokens and do not create an LLM run.

Product Guidance

• Use requiresCitations: true for legal, medical, deadline, damages, settlement, and client-facing work product.
• Route approved swarm outputs through the AI review queue before mutating case records, documents, portal updates, or outbound communications.
• Keep source retrieval firm-scoped and case-scoped before invoking the swarm.
• Treat a blocked reviewer status as a hard stop. Do not fall back to displaying the draft.

Verification

Focused coverage lives in src/__tests__/lib/swarm.test.ts.

Run:

npm run test:run -- swarm truth-guard ai-output-envelope
npx eslint src/lib/ai/swarm.ts src/__tests__/lib/swarm.test.ts
npm run typecheck