Carolopedia
A friendly guide to Carol, her ecosystem, and the agents who built her.
🎯Key functional considerations
As the org's independent assurance layer, its architecture must guarantee:
- Independence. Checks are run by a distinct owner agent (Themis), separate from the teams being audited, so verdicts are not self-graded.
- Evidence-backed verdicts. Every finding ties back to concrete evidence pulled from the org's sources of truth, not opinion.
- Integrity. Audit records must be tamper-evident and append-only once written.
- Cost attribution. Assurance work is billed back to a cost center, so the service must record what it checked and what it charged.
🧰Technologies used
Grounded in the shared Carolverse stack; only the parts that apply to an assurance service:
- Python 3 on FastAPI / Flask behind nginx for the service surface (planned).
- SQLite (WAL) datastores for audit records and findings.
- The registry and the design store as the binding sources of truth the audits read from.
- systemd / cron to schedule recurring compliance sweeps.
- Claude (Sonnet/Opus) for evidence review and rule-reasoning steps.
🏗Solution architecture
The intended pattern is a direct instance of Carolverse's agent-centric modular architecture: the audit work is owned by Themis and carried out by that agent's droids. No blocks or droids are wired yet — this is the architecture to be built, not what runs today.
- Read-only over the sources of truth. The service reads the registry and design store to check rules and evidence; it does not mutate the systems it audits.
- Findings as records. Each check produces an evidence-linked finding written to an append-only audit store.
- Billing tied to assurance. Completed audits attribute cost to the service's cost center.
📐Design principles followed
- Independence. The auditor is a separate agent from the audited; no team grades its own work.
- Evidence over opinion. Every verdict links to concrete evidence from a source of truth.
- Single source of truth. Checks read the live registry and design store, never hand-copied state — the shared principle on the Carolverse Architecture page.
- Agent-centric modular architecture. Each audit activity has an accountable agent and a doing droid.
- Observability first. A check that is not recorded with a deterministic verdict is not done.
✅Success criteria
- Rule and evidence checks run across the org and produce evidence-backed findings, not opinions.
- Audit records are append-only and tamper-evident.
- Assurance work is attributed and billed to the service's cost center.
- The auditor stays independent of the teams it audits.
🛡Service-specific policies
- Read-only on audited systems. The service inspects and reports; it does not change what it audits.
- Owner is an agent id, never a human — assurance is owned by Themis.
- Every finding carries evidence traceable to a source of truth.
- Audit records are not hand-edited once written.
📦End-user deliverables
Current
This is a thin wip service with no blocks, droids or tools wired yet. Today it exists as an owned intent — independent audit and compliance owned by Themis — with the assurance pipeline still to be built.
Future (on demand)
The bulk of this service's capability is future:
- Recurring compliance sweeps that check org rules against the registry and design store.
- Evidence-linked findings written to an append-only audit store.
- Billing of completed assurance work to the service's cost center.
- A surface to view findings and their verdicts.
📘End-user run book
This service has no agent-facing tools yet. The operator/owner path:
- Direction and any manual checks run through the owner agent, Themis.
- As the assurance pipeline is built, the runbook will gain the scheduled-sweep and findings paths.