Skip to content

CORE Governance Model

CORE is not just a codebase — it is a governed system. Every change, whether written by a human or generated by an AI agent, must follow constitutional rules defined in the .intent/ directory.

Governance in CORE answers one question:

How can a system evolve safely without losing structure, intent, or control?

This document explains exactly how.

🚦 1. Governance Overview

CORE’s governance approach ensures that:

  • No code bypasses constitutional rules.
  • No AI agent can write arbitrary files.
  • No human can modify .intent/ without approval.
  • Every change is audited.
  • Every update to the Mind is justified and validated.

Governance is enforced through:

  1. Policies
  2. Constitutional Auditor
  3. Knowledge Graph
  4. Capability System
  5. Proposal + Ratification workflow

Together, these components prevent drift and guarantee safe evolution.

🧠 2. The Constitutional Layer (.intent/)

The .intent/ directory is the foundation of governance. It is where CORE stores its:

  • Policies (rules)
  • Domains (architectural boundaries)
  • Schemas (validation for policies and configurations)
  • Knowledge (representations of files, symbols, and capabilities)
  • Governance metadata (approvers, thresholds, workflows)
  • Proposals (pending constitutional changes)

Nothing outside .intent/ can override rules defined inside it.

2.1. .intent/ Structure

.intent/
├── mission/                  # Principles and north-star definitions
├── policies/                 # All enforceable rules
├── knowledge/                # Knowledge Graph, symbol metadata
├── config/                   # Environment, runtime, safety rules
├── constitution/             # Approvers, voting, versioning
├── schemas/                  # JSON Schemas
└── proposals/                # Pending constitutional amendments (drafts)

Only the governed workflow is allowed to modify this directory.

Editing .intent/ directly is forbidden.

🔍 3. The Constitutional Auditor (src/mind/governance/)

The Constitutional Auditor is the Mind’s enforcement engine. It runs every time:

  • a crate is generated,
  • a change is proposed,
  • a workflow executes,
  • or a developer explicitly runs core-admin check audit.

3.1. Components of the Auditor

  • audit_context.py — gathers required state
  • auditor.py — orchestrates checks

  • checks/ — dozens of policy checks, including:

  • coverage checks

  • capability coverage
  • ID uniqueness
  • import rules
  • domain placement
  • file header rules
  • drift detection
  • security policies

3.2. Goals of the Auditor

  1. Ensure no change violates constitutional constraints.
  2. Detect drift between implementation and intent.
  3. Enforce schema compliance.
  4. Maintain structural integrity of the project.

If a violation is found, the change is rejected.

🗃 4. Policies: How Rules Are Stored

Policies define allowed and forbidden behavior. They live under:

.intent/policies/

Each policy includes:

  • policy_id — permanent UUID
  • title — human-readable name
  • purpose — why the rule exists
  • rules — enforceable constraints

Example categories:

  • Code Standards — naming, import grouping, formatting
  • Governance Policies — proposal process, ratification requirements
  • Quality Assurance — coverage thresholds, lint rules
  • Domain Boundaries — what can import what

The Auditor loads these and applies them to the Body.

🧬 5. Knowledge Graph (Symbols & Capabilities)

CORE continuously constructs and maintains a Knowledge Graph representing the system.

This graph is built from:

  • # ID: tags inside the code
  • Symbols (functions, classes, modules)
  • Capabilities (semantic actions the system can perform)
  • Relationships and dependencies

Stored in .intent/knowledge/, it enables:

  • drift detection,
  • capability-based reasoning,
  • safe planning for agents,
  • architectural enforcement.

When the Knowledge Graph updates, the Mind gains a new understanding of the system.

🏛 6. The Proposal Workflow (Changing the Constitution)

No one — not even agents — can modify .intent/ directly. Every change must follow the amendment process.

6.1. Step 1 — Create Proposal

A proposal is a YAML file placed in:

.intent/proposals/

Example fields include:

  • target file in .intent/
  • justification
  • content changes
  • signature (human key required)

Proposals are drafts. They have no effect yet.

6.2. Step 2 — Human Signature

The proposal must be signed with a key generated via:

poetry run core-admin keys keygen "your.email@example.com"

CORE verifies that:

  • the signer is authorized,
  • signature matches registered identity,
  • signature belongs to one of the approved approvers.

6.3. Step 3 — Canary Validation

Before applying any constitutional change, CORE runs a canary check:

  • clones the system and .intent/ in memory,
  • applies the proposal to the clone,
  • runs a full audit inside the clone.

If anything fails → proposal rejected. If everything passes → proposal approved.

6.4. Step 4 — Application

If approved, CORE writes the change to .intent/. The live system remains safe at all times.

🛡 7. Protection Mechanisms

CORE includes several layers of defense:

7.1. IntentGuard

Prevent direct writes into .intent/. Only proposal workflows may modify it.

7.2. Audit Gates

Block merges or modifications when:

  • schema violations occur,
  • coverage drops below threshold,
  • ID/capability drift detected,
  • domain boundaries violated.

7.3. Signature & Identity

Every constitutional action must be explicitly signed by a human.

7.4. Reversible & Inspectable

All proposals remain recorded. Nothing disappears.

🔄 8. Governance Lifecycle

8.1. Code Lifecycle (Body)

  • Developer writes code
  • Self-healing fixes metadata
  • Knowledge sync updates symbols
  • Auditor validates
  • Commit allowed only if compliant

8.2. Autonomous Development Lifecycle (Will)

  • Agent generates crate
  • Validation & audit run
  • Crate accepted or rejected

8.3. Constitutional Lifecycle (Mind)

  • Proposal created
  • Human signs
  • Canary check runs
  • Proposal ratified
  • Mind evolves

Each layer is governed differently — but all revolve around the Constitution.

🎯 9. Why Governance Matters

Without governance:

  • AI becomes unsafe
  • Architecture collapses over time
  • Decisions are undocumented
  • Knowledge disappears
  • Code becomes unmaintainable

CORE prevents this through:

  • traceability,
  • constitutional enforcement,
  • permanent intent storage,
  • safe autonomous capabilities,
  • explicit human oversight.

Governance is not a feature — it is the foundation.

📎 Next Steps

Continue with:

This will show how governance interacts with autonomy and the self-healing systems.