CLAUDE.md

CourtMitra MissionOS

Citizen-side grievance/legal-action autopilot for India. A user describes a problem once (WhatsApp / Telegram / browser); the system turns it into a mission, builds the evidence file, grounds it in Indian law/procedure, picks an official route, drafts + sends approved actions, follows up, and records the outcome.

Prime directive

Complete the entire loop, automatically and honestly. Intake → evidence → facts → cited route → consented action → real send → public case page → follow-up → reply → resolution → ledger. The reliability spine and safety gates exist to make that automated loop trustworthy — never polish a subsystem while the loop is broken. A demo that closes one real loop beats ten half-built modules.

Deep specs live in (read on demand, do not load wholesale):

• courtmitra_missionos_full_idea.md — product, UX, issue adapters.
• courtmitra_missionos_architecture_plan_v0_2_third_audit.md — full architecture, data model (§9, §30), endpoints (§10, §30.15), state machine (§30.6).
• Phase build specs (PHASE_1_*.md, PHASE_2_*.md) — scope fence; build Phase 1 only until told otherwise.

Non-negotiable invariants (these prevent regressions)

1. Hexagonal. packages/domain imports NO framework/SDK (openai, @nestjs/*, playwright, qdrant, supabase, google/meta clients). It depends only on packages/ports interfaces. Adapters implement ports; apps/api wires them.
2. Everything external is an Action. Workflows NEVER call Gmail/WhatsApp/Telegram/Meta/Playwright directly. They create/execute an Action. The ActionExecutor is the only place side-effects happen, and it checks — in order — consent, idempotency key, adapter capability, rate limit, then sets proof_state.
3. No fake submissions. proof_state must reflect reality (draft_only, ready_for_user_submission, sent_by_email, posted_to_social, user_confirmed_external_submission, receipt_verified, failed). The UI must never imply more than proof_state supports. Indian gov portals have no citizen write API → packet + supervised browser + user-confirmed receipt only.
4. No legal claim without a cited source. Generated legal/route text must carry cited_chunk_ids + quote spans that literally exist in the source (exact substring check, not the model's self-report). No Tier-1/2 source → neutral admin language only, never presented as law.
5. No public output without redaction + consent. Run Presidio redaction before any share/publish. Consent is gated by a canonical action_preview_hash; if a regenerated payload's hash ≠ the approved hash, block and re-request approval.
6. Contracts-first. All LLM/API I/O is Zod schemas in packages/contracts (single source of truth). API routes and the frontend import these schemas — never redefine DTOs. OpenAPI is generated, not hand-written.
7. Idempotent writes + webhooks. Every write endpoint accepts Idempotency-Key; every provider webhook is deduped by provider event ID in webhook_events before processing.
8. Every schema change is a Drizzle migration. No ad-hoc DB edits. Seed route rules + curated citations.

Locked tech stack — use these, not the alternatives

Layer	Use	Do NOT use
Monorepo	pnpm + Turborepo	—
Web	Next.js (App Router)	—
API	NestJS + Fastify	(don't mix in Express)
DB / ORM	Postgres + Drizzle (Neon or local Docker; Supabase only with keep-alive)	raw SQL clients
AI layer	Vercel AI SDK 6 (ToolLoopAgent, tool-approval, structured outputs) behind LlmPort; Mastra optional	OpenAI Agents SDK (TS support lags — Python-first)
RAG/search	pgvector + Postgres FTS + curated citations	Qdrant (Phase 2 upgrade)
Evidence extraction	vision-LLM on screenshots/PDF images	Docling/Tesseract (Phase 2)
Workflows	Inngest (durable sleeps + event fns). Payload ≤256KB → pass refs, not blobs	—
Email	Resend (DKIM/SPF/DMARC) + reply token	raw SMTP; Gmail restricted scopes (CASA cost)
Channels	WhatsApp Cloud API + Telegram Bot API + browser, all behind ChannelPort	single-channel coupling
Auth	ONE of Supabase Auth / Better Auth + Google OAuth; channel identity first, browser merge via magic-link	SMS OTP
Redaction	Microsoft Presidio + custom Aadhaar/PAN/UPI/IFSC recognizers	regex-only
Storage / Obs	R2 or Supabase Storage / OpenTelemetry + Langfuse	—

Repo structure

apps/{web, api, worker}
packages/{domain, ports, adapters, db, contracts, prompts, ui}

domain = entities/use-cases/policies (pure). ports = interfaces only. adapters = openai/whatsapp/telegram/resend/storage/meta. contracts = Zod + OpenAPI. prompts = versioned prompts + evals (no inline prompts in controllers).

Commands (scaffolding must expose these; keep them green)

pnpm dev            # web + api + worker
pnpm build          # turbo build all
pnpm typecheck      # tsc --noEmit across packages
pnpm lint           # eslint incl. dependency-boundary rules
pnpm test           # vitest (unit + integration via Testcontainers)
pnpm db:migrate     # drizzle migrations
pnpm db:seed        # route rules + curated citations
pnpm test:contracts # zod/openapi contract tests — MUST pass before UI work

Run pnpm typecheck && pnpm lint && pnpm test:contracts before considering any task done.

Conventions

• TypeScript strict; no any in domain/contracts. Validate every LLM output against its Zod schema; on failure, retry/repair, never pass through.
• Errors: typed Result/exception at adapter edge; domain throws domain errors. Log with the trace ID that links message → mission → workflow → LLM call → action.
• Naming follows the data model in architecture §9/§30 (snake_case tables, the documented state/event enums). Don't invent parallel names.
• Append to mission_events; read UI state from mission_status_snapshots (don't recompute).
• Money/dates in evidence: preserve original text + extracted value; never lose original-language proof.
• Timezone: Asia/Kolkata for all deadlines.

Safety & compliance (hard gates)

• Approval-first: no send/post/share without a recorded consent grant whose hash matches the outgoing payload.
• Public case pages are private-link only in Phase 1 (no live social, no indexing) — contains defamation/intermediary risk. Never label an entity "fraud/scam/criminal"; use "user reports / unresolved / alleged".
• Stop-and-refer (emergency, criminal, domestic violence, child safety, active fraud) → human_review_items, halt automation, surface helpline guidance.
• "Legal information & workflow assistance, not a lawyer-client relationship" disclaimer on legal outputs. Never guarantee outcomes.
• DPDP: deliver consent notice at first contact; support data export + erasure; cross-user aggregation (swarm, Phase 2) needs its own consent basis.

Model & delegation policy

Default to the cheapest model that will not regress the task. Reserve expensive reasoning for where it matters.

• Haiku (or the read-only Explore agent): file discovery, grep/lookups, mechanical transforms, dependency tracing, log scanning.
• Sonnet: implementation — CRUD endpoints, adapters, UI components, tests, migrations, boilerplate from a clear spec.
• Opus (main/advisor): architecture, data-model & schema design, the Action/consent/proof spine, RAG/legal-grounding logic, safety policies, ambiguous tradeoffs, and reviewing the above before merge.

How to delegate: spawn subagents with explicit model: frontmatter (haiku/sonnet), or pass model to the Task tool. Keep menial, well-specified work off the main reasoning model. Escalate to Opus only when a task touches an invariant above or the spec is ambiguous. Always run an Opus/advisor review pass on anything touching consent, proof_state, redaction, or legal grounding.

Scope fence

Build Phase 1 only. Do NOT start: complaint swarm, live social publishing, company resolver portal, Qdrant/rerank RAG upgrade, ASR/voice, Indic translation services, supervised Playwright portal automation, eCourts/CNR, or the AI-run public account. These are Phase 2 — see PHASE_2_*.md.