CortexBuild — Technical Specification (v0.1)¶
Canonical engineering spec. Tracks GitHub issue #92. Authoritative source for what CortexBuild is, what it must do, and the contracts every component honours. Grounded in the real code under
cortexbuild-core/cortexbuild_core/and the architecture docs underdocs/architecture/. Where a claim describes shipped behaviour it citesfile:line. Forward-looking control-plane behaviour is marked (planned).
| Status | Pre-Alpha (Development Status :: 2 - Pre-Alpha, pyproject.toml:17) |
| Package version | 0.0.1 (pyproject.toml:7) |
| Framework version | 0.0.1 (cortexbuild_core/registry.yaml:17) |
| Python | >=3.11 declared (pyproject.toml:11); 3.12 used in dev (cortexbuild-core/README.md:35) |
| License | Apache-2.0 (pyproject.toml:10) |
| Companion doc | 02-IMPLEMENTATION_GUIDE.md |
In plain English
This is the deep engineering spec — the contracts and components behind the product. If you just want to use CortexBuild, start with Onboard Your Repo instead; come back here when you want to build on or extend the harness.
1. Overview & scope¶
CortexBuild is a team of AI agents that autonomously modernises legacy code
and burns down backlog inside a user's repository, under user-controlled
approval gates (docs/00-EXECUTIVE_SUMMARY.md:18). It is not a new IDE, not
a greenfield generator, and not vendor-locked to one LLM (docs/00-EXECUTIVE_SUMMARY.md:23).
The product is composed of four components:
| # | Component | Repo location | Responsibility | Phase |
|---|---|---|---|---|
| 1 | cortexbuild-core (OSS engine) |
cortexbuild-core/cortexbuild_core/ |
Rule/agent SSoT, multi-tool render, recurrence ledger, brownfield analyser, conformance/ROI, standards layer, CLI | P0–P2 implemented |
| 2 | Orchestrator service (control plane) | not in this repo | FastAPI wave sequencer, provider router, approval gate, audit log, multi-tenant data layer | planned (docs/architecture/01-SYSTEM_ARCHITECTURE.md:84) |
| 3 | Web UI (control plane) | website/ is the marketing site; app UI not in this repo |
Next.js dashboard, task board, approval queue, cost dashboard | planned (docs/architecture/01-SYSTEM_ARCHITECTURE.md:77) |
| 4 | Execution runtime (Dev VM) | not in this repo | Daytona devcontainer per project: repo clone, toolchain install, provider CLIs, audit-logged shell | planned (docs/architecture/01-SYSTEM_ARCHITECTURE.md:93) |
Current phase status. The OSS engine (component 1) is materially built and
tested: the CLI exposes 20+ command groups spanning P0 → P2 tickets
(cortexbuild_core/cli/main.py:56-135), and the test suite contains 64
test_*.py files covering P0/P1/P2 features. The control-plane components
(2–4) and the live LLM provider adapters remain stubs — providers/__init__.py
reads "Interface in P1-01; Claude Code + Copilot CLI Day 1" and
orchestrator/__init__.py reads "Implementation lands in P1".
Scope of this document¶
In-scope: functional + non-functional requirements for both product surfaces;
the SSoT/render contract; the agent + wave model; the provider adapter
contract; the approval/autonomy model; the data model; the brownfield analyser;
conformance + ROI; security; observability. Out-of-scope: UI pixel design,
billing flows, and go-to-market (see docs/00-EXECUTIVE_SUMMARY.md).
2. Goals / non-goals¶
Goals¶
- Two brownfield surfaces — Legacy Modernisation and Backlog
Burn-Down — sharing one orchestration engine, one rule SSoT, one
recurrence ledger, one approval matrix (
docs/00-EXECUTIVE_SUMMARY.md:33). - A rule single-source-of-truth that renders simultaneously to Copilot,
Claude Code, Codex CLI, and Cursor (
docs/00-EXECUTIVE_SUMMARY.md:41). - A multi-agent wave model with an adversarial Critic gate
(
docs/00-EXECUTIVE_SUMMARY.md:40). - A recurrence ledger so agents learn from past failures
(
docs/00-EXECUTIVE_SUMMARY.md:42). - BYO-key, multi-provider LLM access with no lock-in
(
docs/01-PRODUCT_SPEC.md:11). - User-controlled autonomy via a 20-row approval matrix
(
docs/01-PRODUCT_SPEC.md:72).
Non-goals (explicitly not built in v1, docs/01-PRODUCT_SPEC.md:107)¶
- New IDE; code-editing UI (use git + your editor).
- Greenfield project generator.
- Marketplace UI (rule packs distributed via GitHub for now).
- Mobile app; Slack/Teams bot (planned v2).
- Custom LLM training; a debugger; a test-runner UI.
3. Functional requirements¶
Numbered FRs per surface. A = Legacy Modernisation, B = Backlog
Burn-Down. Each FR maps to the flows in docs/01-PRODUCT_SPEC.md:18-71.
Surface A — Legacy Modernisation¶
| FR | Requirement |
|---|---|
| FR-A1 | On repo connect flagged "modernise", run a chat-style onboarding interview (~15 min) capturing business goals, risk tolerance, deprecation horizon (docs/01-PRODUCT_SPEC.md:25). |
| FR-A2 | Run codebase analysis (~10 min): structural scan, convention inference, pain-point mining, architecture map (docs/01-PRODUCT_SPEC.md:29). Implemented passes: analyser.structural.scan (cortexbuild_core/analyser/structural.py:555), analyser.graph (graph.py:58), analyser.debt.compute_heatmap (debt.py:196). |
| FR-A3 | Synthesise a technical-debt heatmap (file × hotfix × age × dependency centrality) and a ROI-ranked modernisation backlog (docs/01-PRODUCT_SPEC.md:34). |
| FR-A4 | Execution loop: user approves/edits roadmap; CortexBuild works issues in dependency order; each issue runs Planner → Critic → Builder → (Tester ∥ Security ∥ Optimizer) → PR (docs/01-PRODUCT_SPEC.md:38). |
| FR-A5 | User reviews PRs in normal GitHub flow; CortexBuild never blocks merge (docs/architecture/01-SYSTEM_ARCHITECTURE.md:71). |
| FR-A6 | Continuous learning: every rejected PR → post-mortem → ledger entry; recurrence patterns become enforced rules; surface an "agent confidence rising" trend (docs/01-PRODUCT_SPEC.md:43). |
Surface B — Backlog Burn-Down¶
| FR | Requirement |
|---|---|
| FR-B1 | On Linear/Jira/GitHub-Issues connect, run a triage pass: classify every ticket S/M/L/XL, required skills, blast radius, autonomous-confidence score (docs/01-PRODUCT_SPEC.md:53). |
| FR-B2 | Autonomous mode (default, S tickets): pick S tickets with confidence ≥ 0.85, run the full wave model, open a PR with self-audit + diffs, mark "in review" (docs/01-PRODUCT_SPEC.md:58). |
| FR-B3 | Assisted mode (M/L tickets): draft a plan, require user approval before execution, re-plan on rejection (docs/01-PRODUCT_SPEC.md:63). |
| FR-B4 | Escalation (XL tickets): flag as too complex, suggest a breakdown, hand back to user (docs/01-PRODUCT_SPEC.md:67). |
Cross-surface FRs (shared engine)¶
| FR | Requirement |
|---|---|
| FR-X1 | Render SSoT: render the rule pack + agents into every enabled tool surface non-destructively; cortexbuild render --check is a drift gate (cortexbuild_core/render/cli.py:36). |
| FR-X2 | Recurrence ledger CRUD with status lifecycle open→pending→implemented→automated→closed (cortexbuild_core/ledger/schema.py:24). |
| FR-X3 | Brownfield onboarding via cortexbuild init (analyse + select adaptive rules + render) (cortexbuild_core/cli/main.py:67). |
| FR-X4 | Conformance + ROI reports, deterministic and offline (cortexbuild_core/conformance/report.py:415, insights/roi.py:242). |
| FR-X5 | Org standards layer: pull/sync/upgrade/downgrade a pinned pack with supply-chain verification (cortexbuild_core/standards/sync.py:223). |
| FR-X6 | Lifecycle verbs (spec, plan, build, test, review, ship, simplify) resolve to skills (cortexbuild_core/registry.yaml:189, lifecycle/resolver.py:135). |
| FR-X7 | Reversible eject: remove CortexBuild from a repo restoring user content (cortexbuild_core/cli/main.py:254). |
4. Non-functional requirements¶
Targets are from the locked product spec NFR table (docs/01-PRODUCT_SPEC.md:119).
Measurement column indicates how each is observed.
| NFR | Target | Measurement |
|---|---|---|
| Latency | First CortexBuild action visible in UI < 5 s of a user message | UI→orchestrator WebSocket timestamp delta |
| Throughput | 10 parallel tasks (single tenant); 50 parallel tasks/tenant (Cloud Team) | Orchestrator task scheduler gauge |
| Availability | 99.5% UI, 99.0% orchestrator (v1); 99.9% (v2) | Uptime monitor (Better Stack, docs/architecture/02-TECH_STACK.md:83) |
| Cost ceiling / task | Configurable; default $5 | Per-task cost meter; budget gate pauses task |
| Audit retention | 90 days free · 1 yr paid · 7 yr enterprise | audit_log table + S3/Athena archival (docs/architecture/02-TECH_STACK.md:36) |
| Time to first PR | ≤ 30 min from repo connect | Onboarding SLA sum (docs/architecture/04-BROWNFIELD_ONBOARDING.md:206) |
| Confidence floor (autonomous PR) | 0.85 (configurable) | Triage confidence score per task |
| PR pass-CI-on-first-try | ≥ 60% (v1) · ≥ 80% (v2) | CI result per PR run |
| Recurrence rate (same bug class/project/month) | < 5% | Ledger query over recurrence classes |
Supporting non-functional contracts realised in code today:
- Determinism / byte-stability. Conformance and ROI reports are offline,
carry no wall-clock, and relativise all paths so two checkouts emit
byte-identical output (
docs/architecture/05-CONFORMANCE.md:39,06-ROI_INSIGHTS.md:46). - Egress safety. All free text is routed through
security.egress.redact_for_egress(cortexbuild_core/security/egress.py:171). - Concurrency safety. Ownership-manifest and audit-log writes take a
portable advisory lock (
cortexbuild_core/concurrency.py,docs/architecture/07-ORG_ROLLOUT.md:30).
5. System components & responsibilities¶
| Component | Responsibilities | Status |
|---|---|---|
core (cortexbuild_core/) |
Rule + agent SSoT; render fan-out; ledger; analyser passes 1–4; conformance; ROI; standards; precedence; context profile; lifecycle; CLI | implemented |
| server (orchestrator) | Stateless API + stateful workers; wave sequencer; provider router; rule rendering port; ledger CRUD; audit emission; multi-tenant (project = tenant) (docs/architecture/01-SYSTEM_ARCHITECTURE.md:84) |
planned |
| web (Next.js 15) | Authenticated dashboard; real-time WebSocket; blocking approval dialogs; PM↔tech-lead persona toggle; write-only BYO-key forms; cost dashboard (docs/architecture/01-SYSTEM_ARCHITECTURE.md:77) |
planned |
| vm (Daytona devcontainer) | One persistent workspace per project; toolchain auto-install; preinstalled provider CLIs; audit-logged shell; egress firewall; pre-op filesystem snapshots (docs/architecture/01-SYSTEM_ARCHITECTURE.md:93) |
planned |
Boundary rule. LLM calls happen from the orchestrator, not the VM, for
cost tracking + key isolation; the VM only ever talks to its repo and the
orchestrator (docs/architecture/01-SYSTEM_ARCHITECTURE.md:101).
6. The rule SSoT model¶
Rules are the single source of truth for every agent instruction. They live as Markdown-with-frontmatter files and are rendered into all tool surfaces; the rendered files are never hand-edited.
Rule file schema¶
A rule is a rule-*.md file with YAML frontmatter, validated by
render.rules.parse_rule_file (cortexbuild_core/render/rules.py:61).
---
id: rule-source-citation # MUST start with "rule-"; filename MUST equal "<id>.md"
severity: high # critical | high | medium | low
applies_to: [planner, builder, critic, pr-reviewer, ...]
enforced_by: [agent system prompts, pr-reviewer]
render_to: all # default propagation target
---
# Title
... rule body markdown ...
(Real example: cortexbuild_core/rules/foundational/rule-source-citation.md:1-7.)
| Field | Required | Validation | Source |
|---|---|---|---|
id |
✅ | string starting rule-; filename must match |
render/rules.py:82,92 |
severity |
✅ | one of critical/high/medium/low (sort order 0–3) |
render/rules.py:26-27,86 |
applies_to |
optional | list of agent ids | rule frontmatter |
enforced_by |
optional | free-form list | rule frontmatter |
render_to |
optional | all (default per registry) |
registry.yaml:220 |
Rule classes¶
| Pack | Directory | Loading | Meaning |
|---|---|---|---|
| Foundational | cortexbuild_core/rules/foundational/ |
always loaded (render/rules.py:130) |
The 43 always-on non-negotiables (e.g. rule-parameterized-sql, rule-critic-gate, rule-secrets-handling). |
| Adaptive | cortexbuild_core/rules/adaptive/ |
loaded only when listed in adaptive_rules_enabled (render/rules.py:133, registry.yaml:224) |
Auto-enabled by the brownfield analyser per detection (e.g. multi-tenant, realtime). |
| Inferred | .cortexbuild/rules/inferred/ (per repo) |
written by Pass-3 synthesis | LLM-proposed conventions with confidence + source: brownfield-analyser (docs/architecture/04-BROWNFIELD_ONBOARDING.md:58). |
Loading is deterministic: rules sort by (severity, id); duplicate ids raise
RuleLoadError (render/rules.py:140-147).
Rendering targets¶
Every enabled rule renders into all four mainstream tool surfaces, defined in
registry.yaml:153:
| Target | Instructions file | Per-agent files | Format |
|---|---|---|---|
copilot |
.github/copilot-instructions.md |
.github/agents/*.agent.md |
markdown + frontmatter |
claude_code |
CLAUDE.md |
.claude/agents/*.md |
markdown |
codex |
AGENTS.md |
— | markdown |
cursor |
— | .cursor/rules/*.mdc |
mdc |
The renderer prepends an auto-generated banner "DO NOT HAND-EDIT THIS FILE"
to every rendered surface (render/renderer.py:22-30).
Drift gate¶
cortexbuild render --check recomputes the expected render and exits non-zero
if any owned/managed content drifts (render/cli.py:62-101). Only
CortexBuild-owned/managed content counts as drift — user content outside the
managed region never does (render/engine.py:9).
Ownership manifest¶
.cortexbuild/ownership.json is the source of truth for which paths CortexBuild
owns, which marker ids live in each managed file, a hash of the managed content,
and whether the file also carries user content (render/ownership.py:13-23,52).
Two write strategies exist (render/ownership.py:38-41):
managed-regions(default) — only the bytes between<!-- BEGIN/END CORTEXBUILD MANAGED -->markers are replaced.separate-files— escape hatch that writes a CortexBuild-owned sidecar and never touches the user's primary file (render/cli.py:46).
Malformed/duplicate markers raise ManagedRegionError so the engine flags
needs-attention instead of clobbering user content (render/ownership.py:56).
7. Agent model¶
Agents are personas rendered from cortexbuild_core/agents/*.md, each bound to
its non-negotiable rules in registry.yaml.
Agent file schema¶
Validated by render.agents.parse_agent_file (cortexbuild_core/render/agents.py:59).
---
id: planner # filename MUST equal "<id>.md"
name: Planner
description: "Use when you need implementation planning..."
tools: [read, search, todo, agent]
agents: [explore] # sub-agents this persona may call
model: default
user_invocable: true
argument_hint: "Describe the feature, bug, or objective to plan end-to-end."
applies_to: [generic]
---
... persona body ...
(Real example: cortexbuild_core/agents/planner.md:1-11.)
| Field | Required | Notes | Source |
|---|---|---|---|
id |
✅ | non-empty; filename must match | render/agents.py:81,90 |
name |
✅ | non-empty | render/agents.py:83 |
description |
✅ | non-empty | render/agents.py:85 |
tools |
optional | list | render/agents.py:96 |
agents |
optional | list → sub_agents |
render/agents.py:100 |
model |
optional | default "default" |
render/agents.py:113 |
user_invocable |
optional | default true |
render/agents.py:114 |
argument_hint |
optional | string | render/agents.py:115 |
applies_to |
optional | scope tag | frontmatter |
The loader auto-discovers *.md, skips README.md, sorts by id, and
rejects duplicate ids (render/agents.py:126-138).
The 10 agents¶
From registry.yaml:28-138:
| Agent | Recommended tier | Core non-negotiables (subset) |
|---|---|---|
planner |
reasoning_heavy | repo-specific-paths, requirement-completeness, plan-confirmation, pre-mortem, critic-gate |
critic |
reasoning_heavy | critic-gate, source-citation, pre-mortem, read-only |
builder |
balanced | parameterized-sql, stale-branch-guard, self-audit-on-complete, secrets-handling, code-simplification |
tester-validator |
balanced | requirement-completeness, synthetic-probes, responsive-layout |
security-compliance |
reasoning_heavy | pii-classification, audit-logging, parameterized-sql, assertive-isolation-tests |
optimizer |
balanced | index-evidence, code-simplification |
pr-reviewer |
reasoning_heavy | contract-parity, test-evidence, rollback-readiness, skill-extraction |
explore |
fast_cheap | read-only, token-efficient-search |
enterprise-orchestrator |
reasoning_heavy | phase-sequence, feedback-loop-mandatory, critic-gate |
recurrence-guard |
balanced | postmortem-input-required, draft-only-no-merge |
Wave model & orchestration sequence¶
The phase sequencer enforces strict ordering with opt-in wave-3 parallelism
(docs/architecture/01-SYSTEM_ARCHITECTURE.md:182, foundational
rule-phase-sequence):
Wave 1a: Planner (sequential)
Wave 1b: Critic (conditional — skipped for trivial low-risk plans)
Wave 2: Builder (sequential — the only writer)
Wave 3: Tester ∥ Security ∥ Optimizer (parallel — all read-only)
Wave 4: PR Reviewer (sequential)
State-machine guarantees: agents never run out of order; each wave blocks on the
previous wave's completion; wave-3 parallelism is opt-in per runtime capability
(docs/architecture/01-SYSTEM_ARCHITECTURE.md:194). The
enterprise-orchestrator agent owns multi-task sequencing
(registry.yaml:122-130).
8. Provider adapter contract¶
The Provider Adapter is the only place that touches provider-specific APIs;
every other component talks to this interface, isolating CortexBuild from LLM
API churn (docs/architecture/03-PROVIDER_ADAPTER.md:5). Status: planned —
providers/__init__.py is a P1 stub; the contract below is the spec the first
implementations must satisfy.
ProviderAdapter Protocol¶
Defined in docs/architecture/03-PROVIDER_ADAPTER.md:79 (target:
cortexbuild_core/providers/base.py):
| Method | Signature (abridged) | Purpose |
|---|---|---|
invoke |
async invoke(prompt, *, system, tools, model_hint, max_tokens=4096, timeout_seconds=300, cache_key=None) -> InvocationResult |
One-shot completion with tool use |
stream |
async stream(...) -> AsyncIterator[StreamChunk] |
Streaming deltas |
estimate_cost |
estimate_cost(prompt, model_hint, expected_output_tokens=1024) -> Decimal |
Pre-invocation budget check |
capabilities |
capabilities() -> set[Capability] |
Declares CODE_EXECUTION, VISION, LONG_CONTEXT_*, PROMPT_CACHING, TOOL_USE, STREAMING, … |
rate_limit_status |
async rate_limit_status() -> RateLimitStatus |
Remaining requests/tokens + reset |
health_check |
async health_check() -> HealthStatus |
Nightly CI smoke test target |
Supporting types: ModelTier (reasoning_heavy/balanced/fast_cheap),
Capability, ToolDef, InvocationResult, StreamChunk, HealthStatus,
RateLimitStatus (docs/architecture/03-PROVIDER_ADAPTER.md:20-77). These tiers
mirror the registry model_tiers block (registry.yaml:20-23).
Model tiers & per-agent routing¶
DEFAULT_AGENT_ROUTING (docs/architecture/03-PROVIDER_ADAPTER.md:141) maps
each agent to a tier (e.g. planner/critic/security/pr-reviewer →
reasoning_heavy; builder/optimizer → balanced; tester/explore →
fast_cheap). Users may override per project, per agent.
Day-1 provider matrix¶
| Provider | Impl | Tier mapping (May 2026) |
|---|---|---|
| Anthropic Claude | ✅ v0 | opus-4.7 / sonnet-4.6 / haiku-4.5 |
| GitHub Copilot CLI | ✅ v0 | --model flag |
| OpenAI Codex CLI | v1 | gpt-5.4 / gpt-5.3-codex / gpt-5-mini |
| Bedrock · Vertex · Azure OpenAI · Ollama | v2 — Bedrock/Vertex/Azure via OpenAI-compatible gateway, no native adapter | varies |
(docs/architecture/03-PROVIDER_ADAPTER.md:124.)
Cost tracking & failure handling¶
Four cost controls: per-agent, per-task, per-project budgets, plus a Redis
prompt cache keyed by cache_key (docs/architecture/03-PROVIDER_ADAPTER.md:157).
Typed errors drive orchestrator responses
(docs/architecture/03-PROVIDER_ADAPTER.md:190):
| Failure | Adapter raises | Orchestrator response |
|---|---|---|
| Timeout | ProviderTimeoutError |
retry once with smaller tier, then next provider |
| 429 | ProviderRateLimitError(retry_after) |
queue + backoff; alternate provider if enabled |
| 401 | ProviderAuthError |
pause project; notify; no retry |
| 5xx | ProviderServerError |
exponential backoff ×3 |
| capability missing | CapabilityNotSupportedError |
re-route to a capable provider |
Every adapter MUST implement health_check(); CI runs a nightly smoke test
across REGISTERED_ADAPTERS and pages on-call on failure
(docs/architecture/03-PROVIDER_ADAPTER.md:166).
9. Approval & autonomy model¶
Autonomy is user-configured per action class. There are 20 action
classes across 3 levels (docs/01-PRODUCT_SPEC.md:72).
Levels¶
| Level | Behaviour |
|---|---|
| Auto | Performed silently; visible in audit log |
| Notify | Performed but UI shows a banner; user can rollback within 5 min |
| Approve | Blocking dialog; agent pauses for explicit yes/no |
Action-class matrix (defaults)¶
| Level | Action classes (defaults, docs/01-PRODUCT_SPEC.md:76) |
|---|---|
| Auto | 1 read/search · 2 create branch · 3 edit files · 4 commit+push to branch · 5 open PR · 6 update PR description · 7 labels/move ticket · 8 comment |
| Notify | 9 install dependency · 10 modify CI/CD · 11 external email/webhook · 12 merge PR→staging · 13 deploy→staging |
| Approve | 14 merge PR→main · 15 deploy→production · 16 spend money · 17 modify prod data · 18 rotate secrets · 19 delete files/branches · 20 sudo command |
Users may shift any row up (more control) or down (more autonomy); going below
the default requires a confirmation dialog (docs/01-PRODUCT_SPEC.md:104).
State machine¶
For every agent-requested action the gate looks up the class level
(docs/architecture/01-SYSTEM_ARCHITECTURE.md:197):
Auto → execute now → audit log
Notify → execute now → notify UI → 5-min rollback window → audit log
Approve → pause agent → UI prompt → user decides → execute+audit OR abort+audit
approvals (id, project_id, run_id, action_class, payload_json, requested_at,
decided_at, decision, decided_by) persists each decision
(docs/architecture/01-SYSTEM_ARCHITECTURE.md:139). Approval timeout: no user
response in 24 h auto-declines (docs/architecture/01-SYSTEM_ARCHITECTURE.md:280).
10. Data model¶
Top-level multi-tenant tables (Postgres), planned for the control plane
(docs/architecture/01-SYSTEM_ARCHITECTURE.md:120). The recurrence-ledger row
shape is already realised in code as a Pydantic model
(cortexbuild_core/ledger/schema.py:32).
| Group | Table | Key columns → purpose |
|---|---|---|
| Tenancy | projects |
id, slug, owner_user_id, repo_url, git_provider, status — a project is the tenant boundary |
users |
id, email, oauth_provider, oauth_id, persona_default — PM vs tech-lead default UI |
|
project_members |
project_id, user_id, role — owner/admin/member/viewer |
|
| Config | provider_keys |
provider, key_ciphertext, kms_key_id — BYO keys, KMS-encrypted at rest |
autonomy_matrix |
project_id, action_class, level — the §9 matrix per project |
|
rule_packs_enabled |
project_id, pack_name, pack_version — which packs are on |
|
| Work | tasks |
source, source_id, title, complexity, confidence, status — triage output |
runs |
task_id, branch_name, status, cost_usd — one execution per task attempt |
|
agent_invocations |
run_id, agent_id, provider, model, prompt_tokens, completion_tokens, latency_ms — per-LLM-call cost/latency |
|
| Approvals | approvals |
see §9 |
| Governance | audit_log |
actor_type, actor_id, action, target, payload_json, ts — every shell op/file edit/API call |
recurrence_ledger |
class, severity, agent, symptom, root_cause, fix, guard_id, status, automation_target |
|
| Rule SSoT | rule_packs |
slug, version, source_url, signed_by, content_hash — signed supply chain |
rendered_targets |
target_tool, target_path, content_hash, rendered_at — drift tracking |
Recurrence-ledger entry (implemented). LedgerEntry
(cortexbuild_core/ledger/schema.py:32) fields: id (kebab slug), title,
class (alias class_), severity, status, agent_responsible,
opened_at, closed_at, postmortem_path, fix_ref, guard_rule,
automation_check, notes. Status lifecycle: open → pending → implemented →
automated → closed (schema.py:24). RecurrenceLedger.add raises on duplicate
ids (schema.py:111).
11. Brownfield analyser¶
Runs once at project setup, then incrementally on every PR merge
(docs/architecture/04-BROWNFIELD_ONBOARDING.md:14). Four analysis passes plus
an interactive interview pass.
| Pass | Name | LLM? | Inputs | Outputs (under .cortexbuild/) |
Implementation |
|---|---|---|---|---|---|
| 1 | Structural scan | no | repo tree, manifests | analysis/structural-report.json |
analyser.structural.scan (structural.py:555); StructuralReport (structural.py:278) |
| 2 | Graph extraction | no | source files (tree-sitter) | analysis/graph.json, analysis/GRAPH_REPORT.md |
analyser.graph (graph.py:58); Python + JS/TS/Go extractors; Louvain communities |
| 3 | Convention inference | yes | sampled god-node files | analysis/conventions.yaml → draft inferred rules |
synthesis.rule_synthesis.synthesise_rules (rule_synthesis.py:302), propose-only |
| 4 | Pain-point mining | optional | 12 mo git log | analysis/debt-heatmap.json (+ .md) |
analyser.debt.compute_heatmap (debt.py:196); cortexbuild debt-heatmap |
| 5 | Interview (interactive) | no | user answers | parameterised rule pack + approval matrix | onboarding wizard (context/wizard.py) |
Pass-1 signals. StructuralReport captures language histogram, frameworks,
databases, CI/container/IaC systems, kubernetes/migrations presence,
tenant_column_hits, and top_level_services/detection_signals that drive
adaptive-rule activation (structural.py:278-295).
Pass-3 safety. Synthesis is propose-only, opt-in, offline by default
(cortexbuild_core/cli/main.py:81). Each inferred rule carries confidence +
source: brownfield-analyser; users promote/demote/discard, and discards are
remembered so the analyser does not churn
(docs/architecture/04-BROWNFIELD_ONBOARDING.md:176).
Privacy. Passes 1–2 are fully local; Pass-3 sends only sampled file content;
Pass-4 sends only commit messages + paths; all LLM calls use the user's key;
outputs are pushed to the user's repo only (docs/architecture/04-BROWNFIELD_ONBOARDING.md:187).
SLA. Total to "ready for work": ~30 min, $6–$23 Opus
(docs/architecture/04-BROWNFIELD_ONBOARDING.md:206).
12. Conformance & ROI¶
Conformance score (cortexbuild conformance)¶
Deterministic, anti-gaming 0–100 maturity score — the equal-weighted mean
(0.2 each) of 5 dimensions, recomputed fresh from on-disk evidence on every
run (docs/architecture/05-CONFORMANCE.md:9; conformance.report.compute_conformance,
report.py:415):
| Dimension | Evidence source |
|---|---|
gates_run |
.cortexbuild/conformance/gate-evidence.json run-records (EXPECTED_GATES, report.py:30) |
drift_clean |
render.engine.check_drift |
ledger_consulted |
.cortexbuild/recurrence-ledger.yaml loads + validates |
profile_complete |
context.score.compute_completeness (score.py:368) |
standards_in_sync |
standards.sync.verify_pack_integrity |
Anti-gaming. The committed report is never read back as input; absence of
evidence scores 0; a skipped gate lowers gates_run, introduced drift lowers
drift_clean (docs/architecture/05-CONFORMANCE.md:22). A gate proves it ran
via record_gate_run(repo_root, gate, status="passed") (report.py:183).
Blocking mode: cortexbuild conformance --fail-under 80 is fail-closed on
the freshly computed score (docs/architecture/05-CONFORMANCE.md:57).
Outputs: .cortexbuild/CONFORMANCE.md + .cortexbuild/conformance.json
(conformance.report.write_conformance, report.py:463).
ROI report (cortexbuild report)¶
Aggregates risk hotspots, adaptive rules proposed, context completeness, and
conformance score + trend into .cortexbuild/ROI_REPORT.md +
.cortexbuild/roi_report.json (docs/architecture/06-ROI_INSIGHTS.md:1;
insights.roi.compute_roi/write_roi, roi.py:242,293). The conformance
trend store at .cortexbuild/insights/trend.jsonl is append-only and
hash-chained: each record carries the previous record's hash; verify_chain
detects any edit/deletion/reorder and surfaces trend_intact = false
(insights.trend.verify_chain, trend.py:79; only whitelisted TREND_METRICS
are persisted, trend.py:29).
13. Security & compliance¶
| Control | Spec | Realisation |
|---|---|---|
| BYO-key handling | Keys encrypted at rest via KMS; never leave the control plane; stored as ciphertext | provider_keys.key_ciphertext/kms_key_id (docs/architecture/01-SYSTEM_ARCHITECTURE.md:129); docs/architecture/02-TECH_STACK.md:63 |
| Tenant isolation | Project = tenant boundary; orchestrator scopes every query by project_id |
docs/architecture/01-SYSTEM_ARCHITECTURE.md:85; enforced by rule-tenant-context-header, rule-assertive-isolation-tests |
| Parameterized SQL | All queries use parameter substitution + type casts | foundational rule-parameterized-sql |
| Secrets in source | Never commit secrets; env/KMS only; ${ENV_VAR} substitution |
foundational rule-secrets-handling |
| PII classification | Geo/identity/biometric columns tagged [PII], retention + permission gate documented |
foundational rule-pii-classification |
| Audit log | Every permission-affecting change writes an audit entry; governance events appended to .cortexbuild/audit-log.yaml |
foundational rule-audit-logging; docs/architecture/07-ORG_ROLLOUT.md:6 |
| Egress redaction | Free text routed through a redactor before leaving the machine | security.egress.redact_for_egress (egress.py:171); telemetry consent gate (egress.py:321-367) |
| Supply chain | Standards packs pinned to exact SHA; re-fetch verifies SHA + content hash; fail-closed on moved/forged tags; optional signing | standards.sync.pull_standards (sync.py:223), standards/signing.py; docs/architecture/08-STANDARDS_UPGRADE.md:44 |
SOC2-relevant controls. Append-only audit trail with 90 d / 1 yr / 7 yr
retention tiers (docs/01-PRODUCT_SPEC.md:127); deterministic, redacted,
byte-stable governance reports; reversible eject + reversible standards
upgrade/downgrade with atomic snapshots (docs/architecture/08-STANDARDS_UPGRADE.md:62).
Compliance posture targets OWASP ASVS, NIST SSDF, ISO 27001-aligned, WCAG 2.2
AA, Azure WAF (docs/01-PRODUCT_SPEC.md:12).
14. Observability & cost¶
| Concern | Mechanism |
|---|---|
| Audit log | Every shell op, file edit, and API call → audit_log (Postgres) + S3/Athena archival (docs/architecture/01-SYSTEM_ARCHITECTURE.md:36) |
| Cost metering | Per agent_invocation: provider, model, prompt/completion tokens, latency, derived cost_usd; rolled up per run and per task (docs/architecture/01-SYSTEM_ARCHITECTURE.md:136) |
| Budget gates | estimate_cost() checked before each invoke; per-agent / per-task / per-project ceilings pause work and notify (docs/architecture/03-PROVIDER_ADAPTER.md:157) |
| Cost dashboard | UI shows $ per task, per agent, per provider (docs/architecture/01-SYSTEM_ARCHITECTURE.md:15) |
| Telemetry | OpenTelemetry → Honeycomb; structlog; Sentry; Langfuse (v2) (docs/architecture/02-TECH_STACK.md:76) — consent-gated (security/egress.py:330) |
| Budget-exceeded failure | Cost meter pauses project; requires explicit unblock (docs/architecture/01-SYSTEM_ARCHITECTURE.md:281) |
Engine-level cost discipline is also enforced as a rule
(rule-cost-budget-gate): new resources/paid APIs/LLM features ship a projected
monthly cost + circuit breaker.
15. Open questions / risks¶
From docs/99-OPEN_QUESTIONS.md:
| # | Question | Status |
|---|---|---|
| Q1 | Product name | ✅ CortexBuild |
| Q2 | Repo location | ✅ fresh private GitHub repo |
| Q3 | Phase-0 time budget | ⏳ awaiting (options A/B/C) |
| Q4 | First brownfield test target | ⏳ awaiting (rec. CortexVigil + 4 OSS) |
| Q5 | CLI distribution channel | ⏳ deferrable (rec. brew + curl-bash) |
| Q6 | Build-vs-buy: VM/auth/jobs/observability/hosting | deferrable per work start |
| Q7 | Pricing / OSS strategy | deferred to post-Phase-2 |
Key risks (docs/00-EXECUTIVE_SUMMARY.md:59):
| Risk | Severity | Mitigation |
|---|---|---|
| LLM provider CLI breakage | High | Adapter pattern + daily smoke tests + pinned versions |
| Token-cost spiral on large repos | High | Per-action model routing + budget gates + graphify indexing |
| Bad-PR floods erode trust | Critical | Mandatory Critic gate + self-audit YAML + confidence threshold |
| Compliance liability | Medium | User-monitored; ToS shields platform; nothing irreversible without approval |
| Provider lock-in | Medium | OSS engine + multi-provider from Day 1 |
16. Appendix¶
Glossary¶
| Term | Meaning |
|---|---|
| SSoT | Single source of truth — the rule/agent files under cortexbuild_core/ from which all tool surfaces are rendered |
| Render | Non-destructive fan-out of SSoT into Copilot/Claude/Codex/Cursor surfaces |
| Drift gate | cortexbuild render --check — fails CI if a rendered surface diverges from SSoT |
| Managed region | The bytes between BEGIN/END CORTEXBUILD MANAGED markers; the only part render rewrites |
| Recurrence ledger | YAML of recurring failure classes + their guards (.cortexbuild/recurrence-ledger.yaml) |
| Foundational / Adaptive / Inferred | Always-on rules / detection-enabled rules / LLM-proposed rules |
| Wave model | Plan → Critic → Build → (Test ∥ Security ∥ Optimize) → PR Review |
| Action class | One of 20 categories of agent action governed by Auto/Notify/Approve |
| Model tier | reasoning_heavy / balanced / fast_cheap routing bucket |
| Conformance score | Deterministic 0–100 adoption-maturity metric across 5 dimensions |
Document cross-links¶
02-IMPLEMENTATION_GUIDE.md— how to build/extend the engine../architecture/00-ARCHITECTURE_OVERVIEW.md— C4 + Mermaid overview../architecture/01-SYSTEM_ARCHITECTURE.md— data model, adapter, failure modes../architecture/02-TECH_STACK.md— stack + revisit triggers../architecture/03-PROVIDER_ADAPTER.md— adapter Protocol../architecture/04-BROWNFIELD_ONBOARDING.md— analyser passes../architecture/05-CONFORMANCE.md·06-ROI_INSIGHTS.md·07-ORG_ROLLOUT.md·08-STANDARDS_UPGRADE.md../01-PRODUCT_SPEC.md— NFRs, approval matrix, success metricsdocs/99-OPEN_QUESTIONS.md— open decisions (internal)