CORE

Executable constitutional governance for AI-assisted software development.

Designed for environments where AI action traceability is not optional.

Versioning: SemVer with 2.x denoting an API approaching stability (Beta on PyPI); see the versioning policy.

The Problem

AI coding tools generate code fast. Too fast to stay sane.

Without enforcement, AI-assisted codebases accumulate invisible debt — layer violations, broken architectural contracts, files that grow unbounded. And agents, left unconstrained, will eventually do something like this:

Agent: "This rule keeps failing my change — I'll loosen the rule"
System: Executes.
You:    😱

CORE blocks what its constitution forbids — structurally, before execution, not detected after the fact. Only what the constitution actually declares is blocked, and which surfaces hard-block versus advisory-report is mapped under Current proof status below.

Agent: "This rule keeps failing my change — I'll loosen the rule"
Constitution: BLOCKED — governance.constitution.read_only (.intent/ is never writable at runtime)
System: Write refused before it happens. Violation logged.
You:    😌

CORE is a governance runtime that constrains AI agents with machine-enforced constitutional law — enforcing architectural invariants, blocking invalid mutations automatically, and making autonomous workflows auditable and deterministic.

LLMs operate inside CORE. Never above it.

Requirements

CORE sets specific requirements rather than widening compatibility. A fresh VM (or an otherwise clean machine) is recommended for the one-command install below.

On a fresh machine none of these exist except Python. Step-by-step commands for Ubuntu 24.04, each with the check the installer runs, are in prerequisites on a fresh Ubuntu 24.04. No LLM is needed to install, audit, or run the demo; an LLM is needed only for autonomous code and test generation.

Bring your own Postgres + Qdrant instead of Docker with ./install-core.sh --bare --db-url … --qdrant-url … (see getting started); the Python and Poetry requirements are unchanged on that path.

🎬 See it govern itself — one command

You don't have to take this on faith. On a clean machine that meets the requirements above:

git clone https://github.com/DariuszNewecki/CORE.git
cd CORE && ./install-core.sh

install-core.sh stands up CORE and finishes by offering the consequence-chain demo as an explicit, opt-in command (it never runs it for you). Run it when you're ready — no LLM key required, but it does need Docker:

poetry run core-admin demo consequence-chain

It asks for one confirmation before it creates anything. In a non-interactive shell (CI, ssh host cmd, an agent-driven terminal) add --simulate-confirmation; the report records the confirmation as simulated.

The demo runs entirely inside a disposable clone and disposable, loopback-only Postgres + Qdrant — it never touches your checkout, its git index, your database, or a running daemon. In one isolated run it:

• seeds a function that violates linkage.assign_ids (a blocking rule) into the clone
• lets the real sensor detect it, the real remediator propose a fix.ids repair, and the governed risk classifier auto-approve it as policy-safe (not "human approved")
• executes the proposal through the real proposal route + executor and commits the repair
• reads the exact recorded chain back — finding → proposal → approval authority → execution → committed change → durable consequence → resolved finding — and re-audits clean
• fails closed: every one of those facts is asserted, and any missing link exits non-zero
• tears down all disposable resources when it's done

Every displayed fact belongs to the same proposal — nothing is selected by "latest". The wrapper scripts/demo.sh still works; it just delegates to the command above.

Governance is executable.

📋 Live Audit Trail

Every enforced action records its lineage. Two consequence chains, taken from the CORE database (snapshot of May 2026) — same schema, two different authorities:

Autonomous path — risk-classified as safe, system self-approved

FINDING     → workflow.ruff_format_check       src/api/cli/client.py                2026-05-18 05:15:15 UTC
PROPOSAL    → 8845dacc…   fix.format                                                2026-05-18 05:16:15 UTC
APPROVAL    → risk_classification.safe_auto_approval                                2026-05-18 05:16:15 UTC
EXECUTION   → completed   (1.29s)                                                   2026-05-18 05:17:18 UTC
FILE CHANGE → +105 / -0   98da9038 → fca9a971  src/api/cli/client.py                2026-05-18 05:17:19 UTC

Human-approval path — governor in the loop

FINDING     → purity.docstrings.required       src/cli/commands/audit_reporter.py   2026-05-15 08:28:29 UTC
PROPOSAL    → a4363a81…   fix.docstrings                                            2026-05-16 13:39:34 UTC
APPROVAL    → principal.governor  (cli_admin)                                       2026-05-16 13:53:32 UTC
EXECUTION   → completed   (24.5s)                                                   2026-05-16 13:55:48 UTC
FILE CHANGE → +26 / -0    5a123426 → 71fde489  src/cli/commands/audit_reporter.py   2026-05-16 13:55:49 UTC

Both chains are queryable end-to-end from proposal_consequences and blackboard_entries. The constitution decides which authority applies; the schema is identical. Reproduce them yourself with the Consequence-chain query in the Proof Index.

Architectural Model

CORE separates responsibility across four repository layers — three enforced as constitutional law, and Specs (human intent). This separation is enforced as law — not convention.

📐 Specs — Human Intent (.specs/)

Where humans define what the system is for and why decisions were made. Contains architectural papers, northstar documents, user requirements, architectural decision records, and planning documents. This is the entry point for anyone trying to understand CORE before reading its implementation.

.specs/ is read by humans and searchable by CORE's semantic layer. It is never written by CORE itself.

🧠 Mind — Law (.intent/ + src/mind/)

Defines what is allowed, required, or forbidden. Contains machine-readable constitutional rules, enforcement mappings, phase-aware governance models, and the authority hierarchy (Meta → Constitution → Policy → Code).

Mind never executes. Mind never mutates. Mind defines law.

⚖️ Will — Judgment (src/will/)

Reads constitutional constraints, orchestrates autonomous reasoning, and records every decision with a traceable audit trail. Every operation follows a structured phase pipeline:

INTERPRET → PLAN → GENERATE → VALIDATE → STYLE CHECK → EXECUTE

Will never bypasses Body. Will never rewrites Mind.

🏗️ Body — Execution (src/body/)

Deterministic, atomic components: analyzers, evaluators, file operations, git services, test runners, CLI commands.

Body performs mutations. Body does not judge. Body does not govern.

How CORE Works

Every autonomous operation is governed by the same constitutional loop:

flowchart TD
    A["🟢 GOAL\nHUMAN INTENT"] --> B["📂 CONTEXT\nRepo state • knowledge • history"]
    B --> C["🔒 CONSTRAINTS\nImmutable rules\n260 rules • 15 engines"]
    C --> D["🗺️ PLAN\nStep-by-step reasoning\nRule-aware plan"]
    D --> E["✨ GENERATE\nCode • changes • tool calls"]
    E --> F["✅ VALIDATE\nDeterministic checks\nAST • semantic • intent • style"]
    F -->|Pass| G["▶️ EXECUTE\nApply compliant changes"]
    F -->|Fail| H["🔄 REMEDIATE\nRepair violation\nAutonomy Ladder"]
    H --> E
    G --> I["✓ SUCCESS\nChanges committed"]

    subgraph "SAFETY HALT"
        direction TB
        J["🚨 CONSTITUTIONAL VIOLATION\n→ HARD HALT\n+ FULL AUDIT LOG"]
    end

    E -.->|Any violation| J
    F -.->|Any violation| J

    classDef phase      fill:#f8f9fa,stroke:#495057,stroke-width:2px
    classDef constraint fill:#d1e7ff,stroke:#0d6efd,stroke-width:2.5px
    classDef validate   fill:#fff3cd,stroke:#ffc107,stroke-width:2.5px
    classDef halt       fill:#ffebee,stroke:#dc3545,stroke-width:3px

    class A,B,D,E,G,I phase
    class C constraint
    class F validate
    class J halt

System Guarantees

Within CORE:

• Nothing is self-approved outside the safe-auto-approval envelope (five fix.* actions and test generation, .py files under src/ and tests/ only) — every other change waits for a human
• No structural rule can be bypassed silently
• No atomic action can execute outside the governed executor (inline authorization is deferred to the audit→consequence loop)
• Decisions are phase-aware and logged with decision traces (audit persistence is best-effort — see Current proof status)
• No agent can amend constitutional law

If a blocking rule fails, execution halts with no partial state. Reporting and advisory rules surface findings and continue — what blocks versus what reports depends on the mode.

Current proof status

CORE's guarantee semantics are split across modes by design. This is the honest map of what each surface does, so a single binary claim ("CORE blocks violations") is not mistaken for the whole picture:

The hard invariants and constitutional rules block unconditionally; the policy, capability, and stateless tiers are weaker by design and labelled here so the boundary is legible rather than implied.

Constitutional Primitives

Enforcement strengths: Blocking · Reporting · Advisory

Enforcement Engines

*Runtime Gate per .specs/papers/CORE-Gate.md, kept here for visibility.

Deterministic when possible. LLM only when necessary.

260 rules across 60 rule documents. 250 are mapped to enforcement engines; the other 10 are advisory rules that are mapping-exempt by design (#820), so every rule that requires a mapping has one. "Mapped" means engine-bound — not enforced in every mode: stateless CI skips knowledge_gate and llm_gate, which need the knowledge graph and an LLM provider.

The Autonomy Ladder

CORE progresses through defined levels. Each adds capability while remaining constitutionally bounded.

A0 — Self-Awareness       ✅  Knows what it is and where it lives
A1 — Self-Healing         ✅  Fixes known structural issues automatically
A2 — Governed Generation  ✅  Natural language → constitutionally aligned code
A3 — Governed Autonomy    ⚠️  Loop is built and governed; unattended reliability unproven  ← current
A4 — Self-Replication     ⏸️  Conceptual. Not on active roadmap.

Advancement is not declared — it is measured. A level is complete when the system demonstrates it operationally, not when the capability exists. A3's mechanism is built and governed: the four A3 plan gates are closed, the loop is circuit-breaker protected, the consequence chain is queryable end-to-end, and every threshold lives in .intent/. What is not yet measured is unattended convergence, which is what production-readiness gate G4 asks for. A3's checkmark is withheld until G4 carries signed evidence — see the G4 row and the Project Status section below for the current state of that evidence.

Production Readiness

CORE does not claim a status it has not earned. The gates are defined in URS-production-readiness; the current verdict and per-gate evidence live in the attestation manifest. This table is generated from that manifest — do not edit it by hand.

Production readiness: NOT ATTESTED. All gates must hold simultaneously, and each met gate must carry dated, human-signed evidence. There is no composite score.

Progress: 2/15 met · 12 partial · 1 not demonstrated.

The full gate definitions and acceptance criteria are in URS-production-readiness.md; the evidence and blockers behind each status are in production-readiness.yaml.

Quick Start

Honest status — what works today. CORE governs itself end to end (the demo above), and audits any repo that has a .intent/ constitution — in CI via the GitHub Action, or locally with core-admin code audit --offline inside that repo. pip install core-runtime gives you the core-admin CLI.

Govern your own repo (BYOR): getting a constitution into an existing repo is not a zero-infrastructure step today. project onboard (delivers the machinery floor) and project scout (proposes fitted rules — via LLM, or a curated four-rule menu without one — each of which you ratify) are core-cli commands (pip install core-cli) that talk to a running CORE API, which needs Postgres + Qdrant behind it (ADR-146). The BYOR quickstart walks that path end to end. Once a repo carries a .intent/, everything downstream is service-free: core-admin project adopt-pack core/starter-python --write adds a ready-made rule pack, and core-admin code audit --offline enforces the rules immediately — both from a plain pip install core-runtime (2.11.0 or later). Starting a new project needs no services at all: core-admin project new myproject --write creates it with the machinery floor, then adopt a pack and audit — step by step.

Fastest way to see CORE today: run it on itself, below.

Upgrading an existing database? Supported since 2.10.2 and always operator-run — CORE never migrates on its own, and the installer and every service start refuse a database that is not current. Procedure: Upgrading an existing CORE database.

Full local runtime — one command. Clone, then run the installer:

git clone https://github.com/DariuszNewecki/CORE.git
cd CORE
./install-core.sh

install-core.sh checks prerequisites, installs dependencies, starts Postgres + Qdrant, applies the schema, and finishes by offering the opt-in core-admin demo consequence-chain command — an isolated run that has CORE find, propose, approve, fix, and verify a violation and record the consequence chain. Installation never runs it for you; run it yourself when ready (needs Docker, no LLM API key).

poetry install
cp .env.example .env
docker compose up -d
docker compose exec -T postgres psql -U postgres -d core < schema.sql
poetry run core-admin code audit --offline   # offline mode needs no running services

Full setup — services, schema, vector sync, first audit — is in Getting Started.

Documentation

Full documentation, architecture deep-dive, and governance reference: dariusznewecki.github.io/CORE

To understand what CORE is for before reading its implementation, start here: .specs/northstar/CORE-What-It-Does.md

Issue Tracker Guide

CORE's tracker mixes governance-internal bookkeeping with ordinary engineering work, so labels do double duty. type:*, priority:*, status:*, band:*, and the *-debt labels are CORE's own governed taxonomy — they say what kind of work an issue is and where it sits relative to the roadmap (roadmap marks epics on a named milestone; technical-debt/governance-debt mark known gaps CORE is carrying forward deliberately, not bugs; band:E marks outward-facing/adoption work). Two standard labels tell you where to actually start: good-first-issue is scoped enough to attempt without deep repo context, and help-wanted is open to outside contribution but assumes you've read the ADR(s) it links. If an issue carries neither — and especially if it carries type:question — it's a live design question awaiting a maintainer decision, not something to open a PR against yet.

Project Status

Current Release: v2.11.0 — a new governed project with no services: project new, packs shipped in the wheel, adopt-pack and project new fixed for pip installs, zero-rule audits fail closed

Active work: A3 Governed Autonomy. The mechanism is built — the daemon runs continuously, finds constitutional violations in its own codebase, proposes fixes, routes them through the governed proposal lifecycle, executes approved fixes, and verifies the result. Each of those steps is demonstrable on demand: core-admin demo consequence-chain exercises the full finding → proposal → approval → execution → consequence → re-audit path in an isolated run, and both chains in the Live Audit Trail above came out of the real database.

What is not yet demonstrated is that the same loop closes unattended over a long window. That is gate G4, and the standing bar for it is a soak whose throughput condition — at least one completed finding → proposal → consequence chain — is declared before the run starts.

Last completed attempt: the 72-hour soak of 2026-07-23 → 2026-07-26 (baseline f7430b25) ran clean at the process level — no restarts, ~35 workers, 68,495 blackboard entries — and produced zero completed chains out of 16,445 findings. The one actionable class inherited a remediation attempt count at the file-level cap, so the circuit breaker abandoned it before a proposal could be created. The breaker did its job; the governed loop did not close. That run is retained as evidence of continuity and was explicitly not accepted as G4 evidence.

"Demonstrable on demand" and "reliable unattended" are different claims, and CORE only makes the first one today.

All four A3 integrity gates were closed in May 2026. No enforcement logic or operational threshold lives in src/ — governance is declared in .intent/ and enforced from there. The autonomous loop is circuit-breaker protected; systematic errors surface as signals rather than unbounded churn.

These are the A3 plan's closure gates (CORE-A3-plan.md, closed 2026-05), a different vocabulary from the fifteen production-readiness gates above — the A3 gates say the autonomous loop exists and is governed; the readiness gates say whether it is proven fit to ship, and today it is not. A3 plan gates closed is why the ladder still reads "A3 ← current"; G4 unmet is why it reads ⚠️ rather than ✅.

License