DIRECTORA

Governance Infrastructure // Scrutexity

Immutable ledger. Atomic sign-off. Zero-drift contracts.

What this repo contains · Verify in 60 seconds · Quick start · Where to look · Security

---

Directora is internal Scrutexity infrastructure — the machine behind our outcomes.

Engine published as proof of governance. labbrief_kit/ is the integration surface. Full LabBrief UI remains private.

Not a clinical, legal, or regulatory assessment. PHI-minimizing IDs only (patient_ref, encounter_ref).

Governed. Proof-verified. MIT-Licensed.
This repo ships a 60-second governance proof script + CI gate.

---

What this repo contains

• Directora (FastAPI · Python) — governed server: append-only ledger, atomic sign-off, idempotency replay, contract snapshot drift guard.
• LabBrief kit (TypeScript) — integration kit: schemas + retry policy + idempotency lifecycle + drift detector (kit-only; not the full UI).
• Shared wire contract — shared/brief-api-contract.json is the single contract source of truth.

---

Data Flow

┌──────────────┐
│   LabBrief   │
│  (Client UI) │
└────────┬─────┘
         │
         │ POST /api/brief/sign
         │ (idempotency key + signature)
         │
         ▼
┌──────────────────────────┐
│  Directora (FastAPI)     │
│  ─────────────────────   │
│  • Validate signature    │
│  • Atomic ledger append  │
│  • X-Idempotency headers │
└────────┬────────────────┘
         │
         │ 200 OK (ledger_event_id, binding_hash)
         │ X-Contract-Version
         │ X-Idempotency-Replayed
         │ X-Request-ID
         │
         ▼
┌─────────────────────────────────────┐
│   LabBrief Kit (TypeScript)         │
│   ───────────────────────────────── │
│   • Retry on 503 / 429 / timeout    │
│   • Never retry on 409 / 422 / 4xx  │
│   • Contract drift detection        │
│   • Audit trail consumption         │
└─────────────────────────────────────┘

---

Verify in 60 seconds (the gate)

Run from repo root:

./tests/governance/ultimate-governance-check.sh

Expected output:

✅ GOVERNANCE ARCHITECTURE INTACT
   Directora and LabBrief cannot drift.
   Atomicity, idempotency, and contract versioning all verified.

CI runs the same proof on every PR via .github/workflows/governance-proof.yml.

---

Brief API

Endpoints

GET  /api/brief/pending
GET  /api/brief/provider
POST /api/brief/sign
GET  /api/labs/audit

Signing guarantees

• Atomicity — ledger append is the commit point; no partial state on failure.
• Idempotency — byte-identical replay for the same Idempotency-Key (replay header surfaced).
• Hash-binding — signature binds to canonical Provider Brief JSON (stable artifact).

---

Quick start (local)

Install

python -m venv .venv
source .venv/bin/activate

# Install pinned deps (deployable/reproducible)
pip install -r requirements-lock.txt

Run

uvicorn directora.api.server:app --host 0.0.0.0 --port 8000

Health

curl http://localhost:8000/health

---

Dependency lock (required for deploys)

Directora deploys are pinned and reproducible. Install from requirements-lock.txt (generated from requirements.txt).

To regenerate the lock:

pip install pip-tools
pip-compile requirements.txt -o requirements-lock.txt

---

Where to look

• Ship doc (repo-native): RELEASE.md
• Polished ship doc (HTML): docs/release/release-page.html
• Governance proof (the gate): tests/governance/ultimate-governance-check.sh
• Contract snapshot: shared/brief-api-contract.json
• Release history: CHANGELOG.md
• Ops handoff: HANDOFF.md
• Deployment runbook: DEPLOYMENT.md
• LabBrief integration kit: labbrief_kit/

---

React Animation Component (optional)

This repo includes an optional animated governance-flow React component:

components/ScrutexityFlow.tsx

Only needed if you import it into a React app (Next.js / Vite / CRA).
If you are only running the Python API, ignore this section.

In your React project (the folder with package.json):

npm install framer-motion

---

Security & scope

See THREAT_MODEL.md for attacker models, mitigations, and out-of-scope risks.

Directora does not claim HIPAA, SOC 2, FDA, legal, or regulatory certification. It provides governance mechanisms, auditability patterns, and safer workflow infrastructure.

---

Star History

---

SCRUTEXITY // 2026

Built with precision. Governed by proof.