CortexBuild — Architecture Overview (C4 + Mermaid)¶

Status legend: ✅ Implemented in cortexbuild-core (Phase 0) · 🟡 Partially implemented / scaffolded · 🔜 Planned (Phase 1/2/3). The OSS engine (cortexbuild-core) exists today; the server, web UI, and VM runtime are later phases (README.md:25–README.md:31).

1. Purpose & audience¶

One-line definition: CortexBuild is the governed harness that renders your team's rules into the AI coding tools you already use (Copilot, Claude Code, Codex, Cursor) and governs the work they produce on your existing repos — new features, services, endpoints, and refactors, plus legacy modernisation and backlog burn-down — with BYO LLM keys, user-controlled approval gates, and generic enterprise best-practices baked in (README.md:3–README.md:5).

This document is the single, authoritative, top-to-bottom architecture map. It is written to be read by two audiences at once:

Audience	What they get from this doc
Human architects / new engineers	A skimmable mental model of every component, data store, and control flow before touching code.
AI agents	Machine-parseable Mermaid graphs + cited `file:line` claims so an agent can reason about the system without hallucinating.

It complements — does not replace — the existing ASCII reference in 01-SYSTEM_ARCHITECTURE.md. Where that doc shows control-plane internals in ASCII, this doc renders the same topology in Mermaid (GitHub-rendering + agent-parseable) and adds C4 context/container layering, the engine's real subpackage map, and the SSoT rendering pipeline.

How to read it: sections 2–4 zoom in (context → containers → engine internals); sections 5–11 explain the core mechanisms (SSoT rendering, agents, onboarding, approvals, learning, data, providers); sections 12–14 cover deployment, cross-cutting concerns, and vocabulary.

2. System context — C4 level 1¶

The two human personas (the same product, toggled by a language layer — docs/01-PRODUCT_SPEC.md:8) talk to CortexBuild, which orchestrates work against external git providers and LLM providers, executing inside a sandboxed runtime.

flowchart TB
    subgraph Humans["People"]
        PM["PM persona — backlog, roadmap, plain language"]
        TL["Tech-lead persona — agent timeline, diffs, detail"]
    end

    CB["CortexBuild<br/>AI agent team + rule SSoT + orchestrator"]

    subgraph External["External systems"]
        GIT["Git providers<br/>GitHub · GitLab · Bitbucket · Azure DevOps"]
        LLM["LLM providers<br/>Anthropic (Claude) · Gemini · OpenAI-compatible (OpenAI/Codex models · gateways · Ollama)"]
        VM["Daytona runtime 🔜<br/>per-project sandbox dev container — planned, Phase 1"]
        TRK["Issue trackers<br/>GitHub Issues · Linear · Jira"]
    end

    PM -->|connect repo, approve roadmap| CB
    TL -->|review PRs, set autonomy| CB
    CB -->|branches · PRs · comments| GIT
    CB -->|invoke models, BYO key| LLM
    CB -->|spawn workspace, run tools| VM
    CB -->|triage tickets| TRK
    VM -->|git push| GIT
    GIT -->|webhooks, PR status| CB

Persona detail and surfaces are defined in docs/01-PRODUCT_SPEC.md:18–:70. Both personas drive one orchestration engine, rule SSoT, recurrence ledger, and approval matrix (README.md:39–README.md:40).

3. Container view — C4 level 2¶

Four product components (README.md:25–README.md:31). Only cortexbuild-core exists today; the rest are later phases.

flowchart TB
    subgraph Client["Browser"]
        WEB["cortexbuild-web 🔜 Phase 2<br/>Next.js 15 · Tailwind · shadcn/ui<br/>task board · agent timeline · approval queue · cost dashboard"]
    end

    subgraph ControlPlane["Control plane 🔜 Phase 2"]
        SRV["cortexbuild-server<br/>Python 3.12 · FastAPI<br/>multi-tenant · approval gates · audit · billing"]
        CORE["cortexbuild-core ✅ Phase 0<br/>rule SSoT engine · agents · orchestrator<br/>analyser · providers · conformance · insights"]
        PG[("Postgres 16<br/>projects · tasks · runs · audit · ledger")]
        RD[("Redis 7<br/>cache · queue · prompt dedupe")]
        S3[("S3<br/>audit archive · artefacts")]
    end

    subgraph Runtime["Execution 🔜 Phase 1"]
        VM["cortexbuild-vm<br/>Daytona dev container<br/>repo clone · toolchain · provider CLIs"]
    end

    subgraph Ext["External"]
        GIT["Git provider"]
        LLM["LLM provider APIs"]
    end

    WEB <-->|REST commands + queries| SRV
    WEB <-.->|WebSocket progress + approvals| SRV
    SRV --> CORE
    SRV --> PG
    SRV --> RD
    SRV --> S3
    SRV -->|spawn workspace| VM
    SRV -->|invoke via provider router| LLM
    VM -->|git push · gh pr create| GIT
    VM -.->|emit audit events| SRV

Protocols and stores are taken from 01-SYSTEM_ARCHITECTURE.md:18–:46 (REST + WebSocket; Postgres + Redis) and 02-TECH_STACK.md:32–:35 (Postgres 16, Redis 7, S3). The rule-rendering and recurrence-ledger logic the server hosts is literally cortexbuild-core (01-SYSTEM_ARCHITECTURE.md:89).

4. The OSS engine — `cortexbuild-core` internals¶

The engine is a Typer-based CLI plus a set of cohesive subpackages under cortexbuild-core/cortexbuild_core/. Responsibilities below are inferred from the package layout and module names (verified by directory listing).

Subpackage	Responsibility	Key modules
`render` ✅	SSoT render engine + drift check + ownership manifest	`engine.py`, `renderer.py`, `ownership.py`, `cli.py`
`rules` ✅	Foundational + adaptive rule fragments (the SSoT)	`rules/foundational/`, `rules/adaptive/`
`agents` ✅	10 generic agent persona files	`planner.md` … `recurrence-guard.md`
`ledger` ✅	Recurrence-ledger schema + store + CLI	`schema.py`, `store.py`, `cli.py`
`analyser` ✅	Brownfield structural scan, graph, debt heatmap	`structural.py`, `graph.py`, `debt.py`
`orchestrator` 🟡	Wave-based phase sequencing + agent routing	(scaffold `__init__.py`)
`providers` 🟡	Provider-adapter Protocol + model-tier routing	(scaffold `__init__.py`)
`conformance` ✅	Deterministic 0-100 maturity score	`report.py`, `cli.py`
`insights` ✅	ROI report + hash-chained conformance trend	`roi.py`, `trend.py`
`standards` ✅	Org standards pull/sync, signing, drift gate	`sync.py`, `lock.py`, `signing.py`
`context` ✅	Project Context Profile schema + completeness score	`schema.py`, `score.py`, `interview.py`
`synthesis` ✅	Pass-3 propose-only inferred-rule synthesis	`rule_synthesis.py`
`learning` ✅	Propose-only skill extraction	`skill_extraction.py`
`cli` ✅	Root Typer app wiring all subcommands	`main.py`, `onboard.py`
`init` ✅	Repo clone + bootstrap + autocommit	`clone.py`, `autocommit.py`
`adopt` / `reconcile` / `precedence` ✅	Brownfield discovery, conflict merge, provenance	`engine.py`, `canonical.py`, `model.py`
`security` ✅	Egress redaction boundary	`egress.py`
`audit` ✅	Audit log schema + governance	`log.py`, `governance.py`
`memory` / `skills` / `hooks` 🟡	Agent memory backends, skill packs, lifecycle hooks	`backend.py`, `render/hooks.py`

flowchart TB
    CLI["cli/main.py — cortexbuild root CLI"]

    subgraph SSoT["SSoT authoring"]
        RULES["rules/ — foundational + adaptive"]
        AGENTS["agents/ — 10 personas"]
        REG["registry.yaml — agent + target registry"]
    end

    subgraph Engine["Render engine"]
        RENDER["render/engine.py + renderer.py"]
        OWN["render/ownership.py — managed regions + manifest"]
    end

    subgraph Brownfield["Brownfield analysis"]
        ANALYSER["analyser/ — structural · graph · debt"]
        SYNTH["synthesis/ — inferred rules"]
        CONTEXT["context/ — project profile"]
        ADOPT["adopt · reconcile · precedence"]
    end

    subgraph Learning["Learning + governance"]
        LEDGER["ledger/ — recurrence ledger"]
        LEARN["learning/ — skill extraction"]
        AUDIT["audit/ — audit log"]
    end

    subgraph Reporting["Reporting"]
        CONF["conformance/ — maturity score"]
        INSIGHTS["insights/ — ROI + trend"]
        STD["standards/ — org packs + drift gate"]
    end

    ORCH["orchestrator/ — wave sequencer + routing"]
    PROV["providers/ — adapter Protocol + router"]

    CLI --> RENDER
    CLI --> ANALYSER
    CLI --> LEDGER
    CLI --> CONF
    CLI --> INSIGHTS
    CLI --> STD
    REG --> RENDER
    RULES --> RENDER
    AGENTS --> RENDER
    RENDER --> OWN
    ANALYSER --> SYNTH --> RULES
    ANALYSER --> CONTEXT
    ADOPT --> RECON_NOTE["MERGE_REPORT.md"]
    LEDGER --> LEARN
    ORCH --> PROV
    ANALYSER --> CONF
    LEDGER --> INSIGHTS

CLI subcommand wiring is in cortexbuild-core/cortexbuild_core/cli/main.py:59–:135 (render, ledger, init, lifecycle, skills, synthesize-rules, debt-heatmap, context, precedence, adopt, reconcile, onboard, standards, conformance, report, rollout).

5. Rule SSoT & rendering pipeline¶

Write once, render everywhere. Rule fragments and agent personas are the single source of truth; cortexbuild render projects them into every enabled AI-tool surface. Hand-editing rendered files is forbidden — they are regenerated (registry.yaml:9–:10).

flowchart LR
    subgraph Source["Single source of truth"]
        F["rules/foundational/*.md"]
        A["rules/adaptive/*.md"]
        P["agents/*.md — 10 personas"]
        R["registry.yaml — targets + bindings"]
    end

    ENG["render engine<br/>render/engine.py · renderer.py"]
    MAN["ownership manifest<br/>.cortexbuild/ownership.json"]

    subgraph Targets["Rendered tool surfaces"]
        CP[".github/copilot-instructions.md<br/>+ .github/agents/*.agent.md"]
        CL["CLAUDE.md + .claude/agents/*.md"]
        CX["AGENTS.md — Codex"]
        CU[".cursor/rules/*.mdc"]
    end

    F --> ENG
    A --> ENG
    P --> ENG
    R --> ENG
    ENG --> MAN
    ENG --> CP
    ENG --> CL
    ENG --> CX
    ENG --> CU
    MAN -.->|cortexbuild render --check<br/>drift gate, exit 1| ENG

Key mechanics:

Mechanism	Detail	Source
`cortexbuild render`	Non-destructive render to all enabled targets	`render/cli.py`
`--check` drift gate	Check-only; exit 1 if any rendered file is stale; CI gate	`render/cli.py` (`--check`)
Managed regions	Single-file Markdown surfaces update only bytes between `<!-- BEGIN/END CORTEXBUILD MANAGED -->`; user content outside preserved byte-for-byte	`registry.yaml:143`–`:151`
Ownership manifest	`.cortexbuild/ownership.json` tracks owned vs managed-region vs sidecar files; drift compares only owned content	`render/engine.py` (module docstring)
`--separate-files`	Escape hatch: write managed content to a CortexBuild-owned sidecar instead of in-file regions	`registry.yaml:148`–`:150`
Per-rule propagation	`default_rule_propagation: all`; per-rule `render_to` overrides	`registry.yaml:218`–`:220`

The four render targets and their formats are declared in registry.yaml:153–:181 (Copilot markdown_with_frontmatter, Claude markdown, Codex markdown, Cursor mdc).

6. Agent roster & wave model¶

Ten generic agents ship in the foundational pack (cortexbuild_core/agents/, registry.yaml:28–:139). Each binds to a set of non-negotiable rules.

#	Agent	Scope	Recommended tier
1	`planner`	Implementation planning, task breakdown, dependency mapping	reasoning_heavy
2	`critic`	Adversarial plan review between Planner and Builder; read-only	reasoning_heavy
3	`builder`	Implement features/fixes; the only writer	balanced
4	`tester-validator`	Correctness, regression, end-to-end parity, synthetic probes	balanced
5	`security-compliance`	OWASP ASVS / NIST SSDF review; PII, secrets, isolation	reasoning_heavy
6	`optimizer`	Scalability, reliability, performance, cloud-cost	balanced
7	`pr-reviewer`	Final merge gate: correctness, coverage, rollback	reasoning_heavy
8	`explore`	Fast read-only repo Q&A sub-agent	fast_cheap
9	`recurrence-guard`	Convert a post-mortem into a permanent automated guard	balanced
10	`enterprise-orchestrator`	Wave-based multi-task orchestration	reasoning_heavy

Per-agent default model routing is in 03-PROVIDER_ADAPTER.md:140–:153.

Wave model (01-SYSTEM_ARCHITECTURE.md:182–:195; orchestrator scope registry.yaml:124). Builder is the sole writer (Wave 2); Wave 3 analyzers are all read-only so they run in parallel; the Critic gate (Wave 1b) is conditional — skipped for trivial low-risk plans.

flowchart TB
    START([Task ready]) --> PLAN["Wave 1a — Planner<br/>sequential"]
    PLAN --> CRITIC{"Wave 1b — Critic<br/>medium+ risk?"}
    CRITIC -->|trivial / low-risk| BUILD
    CRITIC -->|review needed| CREV["Critic adversarial review"]
    CREV -->|request-changes / block| PLAN
    CREV -->|approve| BUILD["Wave 2 — Builder<br/>sequential · only writer"]
    BUILD --> PAR{"Wave 3 — read-only analyzers<br/>parallel"}
    PAR --> T["Tester-Validator"]
    PAR --> S["Security-Compliance"]
    PAR --> O["Optimizer"]
    T --> PRR["Wave 4 — PR Reviewer<br/>sequential merge gate"]
    S --> PRR
    O --> PRR
    PRR -->|approve| DONE([PR ready to merge])
    PRR -->|blocking findings| BUILD

7. Brownfield onboarding sequence¶

Connect-repo → analyse → infer rules → render pack → first roadmap. The analyser runs a 4-pass pipeline (structural, graph, convention inference, pain-point mining) then an interactive interview (04-BROWNFIELD_ONBOARDING.md:12–:162).

sequenceDiagram
    actor User
    participant UI as Web UI 🔜
    participant Orc as Orchestrator
    participant VM as Daytona VM 🔜
    participant LLM as LLM provider

    User->>UI: Connect repo URL
    UI->>Orc: POST /projects
    Orc->>VM: Create workspace
    VM->>VM: Clone repo · detect toolchain · install tools
    VM->>VM: Pass 1 structural · Pass 2 graph — local, no LLM
    VM-->>Orc: structural + graph report
    Orc->>LLM: Pass 3 convention inference — sampled files
    LLM-->>Orc: inferred rule fragments + confidence
    Orc->>Orc: Pass 4 pain-point mining — git log
    Orc-->>UI: Technical debt heatmap + interview Q1..Qn
    User->>UI: Answer goals · risk tolerance · tracker
    UI->>Orc: POST answers
    Orc->>Orc: Render rule pack to .cortexbuild/
    Orc->>VM: Push .cortexbuild init commit
    VM->>VM: git push origin
    Orc-->>UI: First modernisation roadmap
    User->>UI: Approve roadmap
    UI->>Orc: POST /run/start

Privacy boundary: Passes 1–2 are fully local; Pass 3 sends only sampled file content; Pass 4 sends only commit messages + paths (04-BROWNFIELD_ONBOARDING.md:187–:195). SLA: ~30 min, $6–$23 to "ready for work" (04-BROWNFIELD_ONBOARDING.md:197–:206).

8. Approval gate state machine¶

Autonomy is user-configured per action class. The spec defines 20 action classes mapped to 3 levels — Auto / Notify / Approve (docs/01-PRODUCT_SPEC.md:76–:105).

stateDiagram-v2
    [*] --> LookupLevel: Agent requests action
    LookupLevel --> Auto: level = Auto
    LookupLevel --> Notify: level = Notify
    LookupLevel --> Approve: level = Approve

    Auto --> ExecuteSilent: execute now
    ExecuteSilent --> Audited

    Notify --> ExecuteBanner: execute now + UI banner
    ExecuteBanner --> RollbackWindow: 5-min rollback window
    RollbackWindow --> Audited: kept
    RollbackWindow --> RolledBack: user undoes
    RolledBack --> Audited

    Approve --> PauseAgent: block + prompt user
    PauseAgent --> UserDecision
    UserDecision --> ExecuteApproved: yes
    UserDecision --> Aborted: no
    ExecuteApproved --> Audited
    Aborted --> Audited

    Audited --> [*]

Level	Behaviour	Example action classes
Auto	Performed silently; visible in audit log	read code, create branch, edit files, open PR (`PRODUCT_SPEC.md:80`–`:85`)
Notify	Performed + UI banner; 5-min rollback window	install dependency, modify CI/CD, merge to staging (`:86`–`:90`)
Approve	Blocking dialog; agent waits for yes/no	merge to main, deploy to prod, spend money, rotate secrets, delete (`:91`–`:97`)

Defaults are conservative; users may shift any row, but lowering below default requires a confirmation dialog (PRODUCT_SPEC.md:104–:105).

9. Recurrence ledger & continuous learning loop¶

Every rejected PR / incident becomes a post-mortem, which becomes a ledger entry, which the recurrence-guard agent converts into a new enforced rule — re-rendered everywhere (docs/01-PRODUCT_SPEC.md:43–:46; 01-SYSTEM_ARCHITECTURE.md:282).

flowchart LR
    INC["Rejected PR / incident"] --> PM["Post-mortem capture"]
    PM --> LED["ledger/ — recurrence_ledger entry<br/>class · severity · root_cause · fix"]
    LED --> THRESH{"≥2 occurrences<br/>same class?"}
    THRESH -->|no| WATCH["Track only"]
    THRESH -->|yes| GUARD["recurrence-guard agent<br/>draft rule + lint/test"]
    GUARD --> RULE["New rule fragment<br/>rules/adaptive or inferred"]
    RULE --> RENDER["cortexbuild render"]
    RENDER --> ALL["Enforced in Copilot · Claude · Codex · Cursor"]
    ALL -.->|agents stop repeating class| INC

The ledger store is cortexbuild_core/ledger/store.py + schema.py; the guard is draft-only and never merges its own PR (registry.yaml:132–:138, non-negotiables rule-postmortem-input-required, rule-draft-only-no-merge). Auto-promotion of a recurring class to an enforced rule is an explicit failure-mode response (01-SYSTEM_ARCHITECTURE.md:282).

10. Data model¶

Top-level tables from 01-SYSTEM_ARCHITECTURE.md:120–:148. Tenancy boundary is the project.

erDiagram
    users ||--o{ project_members : has
    projects ||--o{ project_members : has
    projects ||--o{ provider_keys : configures
    projects ||--o{ autonomy_matrix : configures
    projects ||--o{ tasks : owns
    tasks ||--o{ runs : spawns
    runs ||--o{ agent_invocations : records
    projects ||--o{ approvals : gates
    runs ||--o{ approvals : requests
    projects ||--o{ audit_log : writes
    projects ||--o{ recurrence_ledger : accrues
    rule_packs ||--o{ rendered_targets : renders
    projects ||--o{ rendered_targets : receives

    users {
        uuid id PK
        string email
        string oauth_provider
        string persona_default
    }
    projects {
        uuid id PK
        string slug
        uuid owner_user_id FK
        string repo_url
        string git_provider
        string status
    }
    project_members {
        uuid project_id FK
        uuid user_id FK
        string role
    }
    provider_keys {
        uuid id PK
        uuid project_id FK
        string provider
        bytes key_ciphertext
        string kms_key_id
    }
    autonomy_matrix {
        uuid project_id FK
        int action_class
        string level
        string updated_by
    }
    tasks {
        uuid id PK
        uuid project_id FK
        string source
        string title
        string complexity
        float confidence
        string status
    }
    runs {
        uuid id PK
        uuid task_id FK
        string branch_name
        string status
        decimal cost_usd
    }
    agent_invocations {
        uuid id PK
        uuid run_id FK
        string agent_id
        string provider
        string model
        int prompt_tokens
        int completion_tokens
        int latency_ms
    }
    approvals {
        uuid id PK
        uuid project_id FK
        uuid run_id FK
        int action_class
        json payload_json
        string decision
        string decided_by
    }
    audit_log {
        uuid id PK
        uuid project_id FK
        uuid run_id FK
        string actor_type
        string action
        string target
        json payload_json
    }
    recurrence_ledger {
        uuid id PK
        uuid project_id FK
        string class
        string severity
        string agent
        string root_cause
        string fix
        string guard_id
        string status
    }
    rule_packs {
        uuid id PK
        string slug
        string version
        string source_url
        string content_hash
    }
    rendered_targets {
        uuid project_id FK
        string target_tool
        string target_path
        string content_hash
    }

11. Provider adapter abstraction¶

The adapter is the only code that touches provider-specific APIs — the moat against LLM provider churn (03-PROVIDER_ADAPTER.md:3–:7). Every component talks to the ProviderAdapter Protocol (03-PROVIDER_ADAPTER.md:79–:122).

Protocol summary (cortexbuild_core/providers/base.py):

Member	Purpose
`name: str`	Adapter identity, e.g. `claude_code`, `copilot_cli`
`async invoke(...)`	One-shot completion with `model_hint: ModelTier`
`async stream(...)`	Token streaming
`estimate_cost(...)`	Pre-flight cost for budget gates
`capabilities() -> set[Capability]`	`CODE_EXECUTION`, `VISION`, `LONG_CONTEXT_*`, `TOOL_USE`, …
`async rate_limit_status()`	Remaining requests/tokens
`async health_check()`	Daily CI smoke test

Routing is by model tier — reasoning_heavy / balanced / fast_cheap (03-PROVIDER_ADAPTER.md:20–:23):

flowchart TB
    AG["Agent invocation<br/>agent_id + model_hint"] --> ROUTER["Provider router<br/>orchestrator/agent_routing.py"]
    ROUTER --> TIER{"ModelTier"}
    TIER -->|reasoning_heavy| RH["Opus 4.7 · GPT-5.4<br/>planner · critic · security · pr-reviewer"]
    TIER -->|balanced| BAL["Sonnet 4.6 · GPT-5.3-codex<br/>builder · optimizer · recurrence-guard"]
    TIER -->|fast_cheap| FC["Haiku 4.5 · GPT-5-mini<br/>explore · tester-validator"]
    RH --> ADAPT["Selected ProviderAdapter"]
    BAL --> ADAPT
    FC --> ADAPT
    ADAPT --> LLM["LLM provider API — BYO key"]
    ADAPT -.->|estimate_cost before invoke| BUDGET["Budget gate"]

Provider availability: native Anthropic (Claude) is Day-1 (✅ v0); native Gemini and any OpenAI-compatible endpoint (covering OpenAI/Codex models, gateways, and local servers such as Ollama) follow; Bedrock, Vertex, and Azure OpenAI are reached only through an OpenAI-compatible gateway (no native adapter). Copilot, Claude Code, Codex, and Cursor are host tools CortexBuild renders into — render targets, not LLM providers (03-PROVIDER_ADAPTER.md:126–:134). Cost controls layer per-agent → per-task → per-project budgets plus a Redis prompt cache (03-PROVIDER_ADAPTER.md:158–:164).

12. Deployment topology¶

Three trust zones: the control plane (CortexBuild-operated), the per-project VM (sandboxed), and external git + LLM providers. LLM calls originate from the control-plane router — not the VM — for cost tracking + key isolation (01-SYSTEM_ARCHITECTURE.md:100–:104).

flowchart TB
    subgraph CPZone["Control plane — CortexBuild operated"]
        SRV["Orchestrator / server"]
        ROUTER["Provider router + KMS secrets"]
        STORES[("Postgres · Redis · S3")]
    end

    subgraph VMZone["Per-project VM — Daytona sandbox 🔜 planned, Phase 1"]
        WS["Workspace: repo clone · toolchain · provider CLIs"]
        FW["Egress firewall — git + LLM only"]
    end

    subgraph ExtZone["External"]
        GIT["Git provider"]
        LLM["LLM provider APIs"]
    end

    SRV --> ROUTER
    SRV --> STORES
    SRV -->|spawn + supervise| WS
    ROUTER -->|invoke models| LLM
    WS -->|git push · gh pr create| GIT
    WS --> FW
    WS -.->|emit audit events| SRV

Boundary table — what runs where (01-SYSTEM_ARCHITECTURE.md:106–:118):

Concern	Control Plane	VM	Git Provider	LLM API
Repo clone	—	✅	source	—
Code edit	—	✅	—	—
LLM call	✅ router	—	—	target
Rule rendering	✅	—	—	—
PR open	orchestrates	✅ `gh pr create`	target	—
Approval dialog	✅	—	—	—
Audit log write	✅	emits events	—	—
Recurrence ledger	✅	—	—	—
Secrets storage	✅ KMS	env at runtime	—	—

12.1 Local & self-hosted model operation¶

CortexBuild supports local and self-hosted OpenAI-compatible model endpoints in addition to cloud providers. The proven scope here is the LLM egress path — not the entire toolchain. LLM egress is locality-gated into three tiers (cortexbuild-core/cortexbuild_core/llm/locality_gate.py, cortexbuild-core/cortexbuild_core/llm/endpoint_config.py):

Loopback (on-box) — a model served on 127.0.0.0/8/::1/localhost runs zero-egress with no consent prompt (redaction still applies).
Self-hosted LAN — an off-box LAN endpoint requires an explicit operator trust declaration before any call is allowed.

The trust declaration is a YAML file at .cortexbuild/llm-trusted-lan.yaml:

trusted_lan_endpoints:
  - "http://10.0.1.50:8080"       # vLLM on internal GPU server
  - "https://llm.internal:8443"   # TLS-terminated LAN endpoint

Only endpoints listed here are permitted for the LAN tier. An unlisted endpoint is refused fail-closed (treated as an unknown tier, which resolves to CLOUD with the full consent gate). - Cloud — public providers pass the full consent gate.

The gate is fail-closed: an unclassifiable or undeclared endpoint is denied. If you expose an OpenAI-compatible endpoint from hardware such as an NVIDIA DGX Spark, CortexBuild reaches it through the same generic endpoint path — there is no Spark-specific adapter, partnership, or certification. NVIDIA and Microsoft are unaffiliated third parties named here for industry context only.

13. Cross-cutting concerns¶

Concern	Approach	Source
Security — BYO keys	Keys encrypted at rest via KMS; never leave control plane; VM only sees env at runtime	`01-SYSTEM_ARCHITECTURE.md:61`–`:62`, `:118`
Tenant isolation	Project = tenant boundary; per-project VM + per-project rows	`01-SYSTEM_ARCHITECTURE.md:86`
Egress redaction	All report free-text routed through `security/egress.py` redactor — no secret/PII leaks into reports	`05-CONFORMANCE.md:46`–`:49`
Observability — audit log	Every shell op, file edit, API call → Postgres + S3	`01-SYSTEM_ARCHITECTURE.md:36`–`:38`
Cost control — budget gates	`estimate_cost()` pre-flight; per-agent/task/project budgets; pause on breach	`03-PROVIDER_ADAPTER.md:158`–`:164`
Conformance	Deterministic 0-100 maturity score; absence of evidence = 0; anti-gaming	`05-CONFORMANCE.md:9`–`:30`
Reliability	Documented failure modes with detection + response (summary below)	`01-SYSTEM_ARCHITECTURE.md:272`–`:284`

Failure-modes summary (full table 01-SYSTEM_ARCHITECTURE.md:272–:284):

Failure	Detection	Response
LLM provider timeout	300s adapter timeout	Retry once with smaller tier; surface if both fail
Provider rate limit	HTTP 429	Queue + backoff; route to alternate if enabled
VM crash	Daytona health check	Restart workspace; resume from checkpoint (planned runtime, Phase 1)
Git push rejected	`git push` exit code	Open issue; pause project; notify
Approval timeout	No response in 24h	Auto-decline; surface in dashboard
Budget exceeded	Cost meter	Pause project; require explicit unblock
Recurring same-class failure	Ledger query	Auto-promote to enforced rule; stop attempting class

14. Glossary¶

Term	Definition
SSoT (Single Source of Truth)	Rule fragments + agent personas authored once under `rules/` and `agents/`, rendered to every AI-tool surface by `cortexbuild render` (`registry.yaml:9`).
Wave model	Strict phase sequencing: Plan → Critic (conditional) → Build → (Tester ∥ Security ∥ Optimizer) → PR Reviewer; Builder is the sole writer (`01-SYSTEM_ARCHITECTURE.md:182`).
Recurrence ledger	Append-only record of failure classes; ≥2 occurrences trigger an enforced rule via `recurrence-guard` (`01-SYSTEM_ARCHITECTURE.md:282`).
Adaptive rule	A rule auto-enabled by the brownfield analyser per detection (e.g. multi-tenant columns detected) — lives in `rules/adaptive/` (`04-BROWNFIELD_ONBOARDING.md:121`–`:124`).
Inferred rule	A draft rule synthesised by Pass-3 convention inference with a `confidence` score and `source: brownfield-analyser` (`04-BROWNFIELD_ONBOARDING.md:60`–`:84`).
Conformance score	Deterministic 0-100 maturity score over five equal-weighted dimensions; absence of evidence scores 0 (`05-CONFORMANCE.md:9`–`:30`).
Approval matrix	User-configured autonomy ceiling: 20 action classes × {Auto, Notify, Approve} (planned control plane, Phase 2) (`01-PRODUCT_SPEC.md:76`–`:105`).
Brownfield	An existing codebase with implicit conventions — CortexBuild's only wedge; greenfield is explicitly out of scope (`04-BROWNFIELD_ONBOARDING.md:3`–`:10`).
Managed region	Bytes between `<!-- BEGIN/END CORTEXBUILD MANAGED -->` markers; the only part of a shared file the renderer rewrites (`registry.yaml:143`–`:147`).

Document	Covers
`01-SYSTEM_ARCHITECTURE.md`	ASCII reference: control-plane internals, data model SQL, sequence + state diagrams
`02-TECH_STACK.md`	Tech-stack decision log (backend, frontend, data, execution, auth)
`03-PROVIDER_ADAPTER.md`	Full `ProviderAdapter` Protocol, provider matrix, routing, failure handling
`04-BROWNFIELD_ONBOARDING.md`	4-pass analyser + interview gates + `.cortexbuild/` output
`05-CONFORMANCE.md`	Deterministic conformance maturity score + anti-gaming
`06-ROI_INSIGHTS.md`	ROI report + hash-chained conformance trend
`../00-EXECUTIVE_SUMMARY.md`	Business case, wedge, defensible edge
`../01-PRODUCT_SPEC.md`	Locked decisions, surfaces, approval matrix, NFRs
`../technical-spec/` 🔜	Detailed technical specification (to be created)

Generated for GitHub issue #91. Every behavioural claim cites file:line in the sources above. Mermaid blocks render on GitHub and are agent-parseable; node labels avoid raw parentheses to keep the syntax valid.