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.
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: "I'll delete the production database to fix this bug"
System: Executes.
You: 😱
CORE makes that class of violation impossible — structurally blocked before execution, not detected after the fact. (Which surfaces hard-block versus advisory-report is mapped under Current proof status below.)
Agent: "I'll delete the production database to fix this bug"
Constitution: BLOCKED — Violates data.ssot.database_primacy
System: Execution halted. 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.
You don't have to take this on faith. On a clean machine with Docker:
git clone https://github.com/DariuszNewecki/CORE.git
cd CORE && ./install-core.shinstall-core.sh stands up CORE and finishes by running the consequence-chain demo live — no LLM key required. It:
- commits a function that violates
linkage.assign_ids(a blocking rule) - watches CORE's audit block it
- has CORE propose a fix, the governor approve it, and CORE execute it and commit the repair
- re-audits to confirm clean
- prints the full causal chain it recorded: finding → proposal → approval → execution → file change
Re-run it any time with scripts/demo.sh.
Governance is executable.
Every enforced action records its lineage. Two consequence chains, pulled live from the CORE database — 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.
CORE separates responsibility across four repository layers — three enforced as constitutional law, and Specs (human intent). This separation is enforced as law — not convention.
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.
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.
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.
Deterministic, atomic components: analyzers, evaluators, file operations, git services, test runners, CLI commands.
Body performs mutations. Body does not judge. Body does not govern.
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\n255 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
Within CORE:
- No file outside an autonomy lane can be modified
- 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.
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:
| Surface | Mode | Behaviour |
|---|---|---|
.intent/ writes |
hard invariant | blocked — the governance directory is immutable to all components |
| Constitutional rules | always-blocking | block a commit regardless of strict mode |
| Policy rules | strict vs. default | block only when strict_mode=True; otherwise report |
| Capability tier | advisory today | reports a "would-deny" signal; does not yet block (ADR-079) |
| Stateless CI (GitHub Action) | rule subset | skips knowledge_gate + llm_gate (they need DB / LLM state) and reports the skip |
| Action audit trail | best-effort | recorded when the DB write succeeds; a write-action failure is surfaced (AUDIT_GAP), not silent |
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.
| Primitive | Purpose |
|---|---|
| Document | Persisted, validated artifact |
| Rule | Atomic normative statement |
| Phase | When the rule is evaluated |
| Authority | Who may define or amend it |
Enforcement strengths: Blocking · Reporting · Advisory
| Engine | Method |
|---|---|
ast_gate |
Deterministic structural analysis (AST) |
regex_gate |
Pattern-based text enforcement |
glob_gate |
Path and boundary enforcement |
cli_gate |
CLI surface and command-shape enforcement |
artifact_gate |
Declared-vs-discovered artifact completeness |
workflow_gate |
Phase-sequencing and coverage checks |
knowledge_gate |
Responsibility and ownership validation |
action_gate |
Atomic-action invariants |
passive_gate |
Substrate-enforced rules (DB/runtime marker) |
taxonomy_gate |
Capability-id ↔ atomic-action coherence (ADR-079 D9) |
contracts_gate |
Cross-cutting data-contract coherence (context-level; ADR-102) |
llm_gate |
LLM-assisted semantic checks |
IntentGuard* |
Runtime write authorization (not audit) |
*Runtime Gate per .specs/papers/CORE-Gate.md, kept here for visibility.
Deterministic when possible. LLM only when necessary.
255 rules across 58 rule documents. 247 are mapped to enforcement engines; the other 8 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.
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 ✅ Daemon finds, proposes, and fixes violations unattended ← current
A4 — Self-Replication 🔮 Writes CORE.NG from its own understanding of itself
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: 0/15 met · 11 partial · 1 not met · 1 not demonstrated · 2 not started.
| Gate | Status | Primary gap |
|---|---|---|
| G1 — Fresh-install proof | CI-automated fresh-install absent; manual cold-room only | |
| G2 — Constitutional enforcement is deterministic and regression-tested | Per-rule known-violating + known-compliant fixtures not universally applied | |
| G3 — Layer integrity is machine-enforced and blocking | Several layer rules at reporting severity (no_body_to_will, will.no_direct_database_access); reporting-only set not formally documented | |
| G4 — Autonomous loop reliability demonstrated by soak | ❌ not demonstrated | No 72h soak run; two loop bugs fixed 2026-07-05 |
| G5 — Mutation-lane equivalence and lifecycle safety | ❌ not met | RemediationCeremony(write=True) bypasses the governed lifecycle (#818); claim.proposal path unaudited this cycle; approval_authority population unverified |
| G6 — Risk model is governed, correct, and regression-tested | else-branch safety net exists for future StepKinds; known set handled but exhaustive-handling not independently audited | |
| G7 — Circuit breakers operate at the correct granularity | Flow-level and worker-level circuit breakers not formally audited | |
| G8 — Integration tests for the governed mutation chain | ⬜ not started | No end-to-end integration test of the governed mutation chain (cognitive delegate -> write -> sandbox -> evidence). Integration INFRASTRUCTURE exists — the specific chain test does not. |
| G9 — Enforcement integrity fails closed | Unmapped non-advisory rules can still yield PASS (#822); empty-graph vacuous-pass guard not built | |
| G10 — Operator observability | Questions 4 (failure diagnosis) and 5 (rollback) not confirmed answerable by a non-author without source access | |
| G11 — Upgrade and migration safety | ⬜ not started | Schema-as-dump (db_schema_live.sql); core._migrations records only (id, applied_at) — no delta path, no version sequence. Most critical structural gap. |
| G12 — Runtime trust boundary is audited and documented | Rate-limiting posture not fully documented; user-facing route safety not fully confirmed per-route | |
| G13 — Documentation for operators | No operator runbook; CLAUDE.md is comprehensive for Claude Code but is not an operator document | |
| G14 — Source reversibility | Source-restoration-after-completed-mutation not proven by test; rollback-vs-forward audit distinction not verified | |
| G15 — Release integrity | Release-gating checks not fully enforced as a blocking pre-publish gate; release provenance (tag/SHA/check-run) not queryable |
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.
| Dependency | Version |
|---|---|
| Python | 3.12+ |
| PostgreSQL | ≥ 14 |
| Qdrant | latest |
| Docker | for services |
| Poetry | for deps |
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 withcore-admin code audit --offlineinside that repo.pip install core-runtimegives you thecore-adminCLI.Govern your own repo (BYOR):
pip install core-runtimeand two commands bootstrap a fitted constitution. (1)core-admin project onboard <path> --writedelivers the machinery floor (no LLM, no database). (2)core-admin project scout <path> --writereads your source, proposes candidate rules via LLM, and requires you to ratify each before delivery — no LLM means a curated four-rule menu instead.core-admin code audit --offlineinside that repo enforces the ratified rules immediately. The machinery floor is bundled in the wheel — both commands work from a plainpip install core-runtime.Fastest way to see CORE today: run it on itself, below.
Full local runtime — one command. Clone, then run the installer:
git clone https://github.com/DariuszNewecki/CORE.git
cd CORE
./install-core.shinstall-core.sh checks prerequisites, installs dependencies, starts Postgres + Qdrant, applies the schema, and finishes by showing CORE govern itself — a violation found, proposed, approved, fixed, and verified, with the consequence chain recorded. No LLM API key needed for the demo.
Prefer to run the steps yourself?
poetry install
cp .env.example .env
docker compose up -d
docker compose exec -T postgres psql -U postgres -d core < infra/sql/db_schema_live.sql
poetry run core-admin code audit --offline # offline mode needs no running servicesFull setup — services, schema, vector sync, first audit — is in Getting Started.
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
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.
Current Release: v2.9.1 — CLI Client Parity
Active work: A3 Governed Autonomy — the daemon runs continuously, finds constitutional violations in its own codebase, proposes fixes, executes approved fixes, and verifies the result. The governor's role is to define intent, review proposals that require architectural judgment, and approve constitutional changes.
All four A3 integrity gates are now closed. 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.
| Gate | Meaning | Status |
|---|---|---|
| G1 — Loop closure | Round-trip autonomous fix demonstrated | ✅ |
| G2 — Convergence | Circuit-breaker; resolution rate > creation rate | ✅ |
| G3 — Consequence chain | Causality queryable end-to-end | ✅ |
G4 — Governance in .intent/ |
No enforcement logic or thresholds in src/ |
✅ |
Build fast with AI. Stay constitutionally aligned.