ClaimOps AI

Governed health-insurance reimbursement intake + exception investigation. Deterministic systems first; LLM only where semantic reasoning is required.

Scope lock

• Product: ClaimOps AI (not ClaimLens, not OpsCore, no rename churn)
• Workflow: reimbursement intake → deterministic verification → AI investigation → HITL → governed action → audit
• Go is the authoritative backend (edge, lifecycle, validation, tenancy, audit); Go application-owned cognitive orchestration (internal/investigate + provider-neutral ModelClient). Python is spec artifacts + bounded future service per ADR-001.
• Agent count: 1 Investigation Agent (bounded, provider-neutral). No APPROVE/DENY/PAY by AI, ever.
• LLM provider: Groq (qwen/qwen3.8-27b, code default) contracted per ADR-002, wiring deferred behind ModelClient (stub/FakeModelClient until key); no Ollama.

Prerequisites

• Go 1.27+, Python 3.12 + uv, Docker (Postgres, Mockoon)

Setup

# Python spec suite (no network)
uv sync --group dev
uv run ruff check .
uv run pytest tests/unit -q

# Go backend (the golden contract is enforced here)
cd apps/api && go build ./... && go test ./...

# Local services (one at a time, never compose for dev)
docker start claimops-postgres      # postgres:16 on :5433
docker start claimops-mockoon       # mocked externals on :3001
# Postgres integration tests need a live DB:
TEST_POSTGRES_DSN=postgres://claimops_app:claimops_app@localhost:5433/claimops \
  go test ./internal/repository/postgres/ -count=1
# External contract tests need Mockoon:
go test ./internal/adapters/http/ -count=1

Layout

apps/api/               Go Fiber edge + deterministic core + investigate (authoritative)
  cmd/api/              main (wiring lives in internal/app for testability)
  cmd/agent/            Agent service :8081 (POST /v1/investigations, read-only registry)
  internal/
    investigate/        cognitive orchestration (orchestrate Loop + ModelClient seam)
    claims/             Claim aggregate + state machine (stdlib-only)
    validation/         six pure validators (stdlib-only)
    workflow/           tenant-scoped store + Apply + domain events + WorkflowProvider
    ports/              Policy/Claims/Provider/Risk outbound interfaces
    adapters/http/      typed clients (timeouts, request IDs, strict decode)
    contracts/external/ wire DTOs (aliases of ports types)
    repository/postgres pgx repo, txn-local tenant context, RLS
    evidence/           source-grounded evidence model
    middleware/         request ID, tenant gate; handlers/; config/; observability/
packages/domain/        Python specification artifacts (Pydantic strict, demoted per ADR-001)
tools/                  Python tooling that is NOT spec artifacts:
  parsers/liteparse/    production parse shim — executed by the Go adapter, copied
                        into the worker image; a Python runtime is required in prod
  corpus/               generator for fixtures/parser_eval/ (sole reproducer)
fixtures/               golden_cases.json — language-independent behavior contract
fixtures/parser_eval/   45-case parser corpus, committed and sha256-verified
mocks/mockoon/          claims-systems.json — 4 systems × 7 scenarios
infra/postgres/         migrations 001–010 (schema+RLS, grants, evidence, documents,
                        outbox, roles, reports, investigations, workflow launches)
scripts/ci/             anti-fake-green + credential-isolation gates run by CI
tests/unit/             Python golden suite (no network)
workflows/              claim-investigation.yaml (durable business coordination, GCW)
docs/adr/               001 go-first, 002 groq provider, 004 external boundary,
                        005 document intelligence, 006 push worker deploy,
                        007 parser policy, 008 agent mutation boundary,
                        009 ocr-confidence-hitl, 011 claim expiry contract

Phase progression

• ✅ Deterministic domain + Postgres RLS + external contracts/Mockoon
• ✅ Parser contract → corpus → LiteParse → benchmark → report → ADR
• ✅ Deterministic chain #44-#47 + ordering #50 + contracts #53 + tools #54 + orchestration #66 → eval v1 ✓
• ✅ Durable claim submission — claim row + claim.submitted event + outbox record committed in one tenant-scoped transaction (#172)
• ✅ Golden behavioral contract expanded to 19 cases; the Go coverage registry fails a fixture case that has no Go assertion
• ✅ Claim expiry contract ratified (ADR-011); supply-chain advisory cleared (pillow 13.0.0)
• Next: release-qualification gate (release is NOT QUALIFIED) → Phase-3 E2E remainder → Groq live qualification

Standing rules

• Deterministic > structured > rules > retrieval > LLM. No LLM for arithmetic, state, auth, money, policy, mutation, retry, idempotency.
• Every entity carries tenant_id; RLS enforced in Postgres (FORCE), transaction-local set_config on pooled connections.
• Every bug → fixture + test + failure classification.
• Atomic commits; no direct-to-main; docs live with the change.