{"slug": "core-deterministic-governance-rules-for-ai-generated-code-pip-installable", "title": "Core – Deterministic governance rules for AI-generated code (pip installable)", "summary": "CORE, an open-source governance runtime for AI-assisted software development, enforces deterministic constitutional rules to block unsafe AI actions before execution. The tool, available on PyPI, provides auditable consequence chains and separates human-defined specs from machine-enforced layers to prevent architectural violations and unauthorized mutations.", "body_md": "Executable constitutional governance for AI-assisted software development.Designed for environments where AI action traceability is not optional.\n\n*Versioning: SemVer with 2.x denoting an API approaching stability (Beta on PyPI); see the versioning policy.*\n\nAI coding tools generate code fast. Too fast to stay sane.\n\nWithout 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:\n\n```\nAgent: \"I'll delete the production database to fix this bug\"\nSystem: Executes.\nYou:    😱\n```\n\nCORE 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.)\n\n```\nAgent: \"I'll delete the production database to fix this bug\"\nConstitution: BLOCKED — Violates data.ssot.database_primacy\nSystem: Execution halted. Violation logged.\nYou:    😌\n```\n\nCORE 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.\n\n**LLMs operate inside CORE. Never above it.**\n\nYou don't have to take this on faith. On a clean machine with Docker:\n\n```\ngit clone https://github.com/DariuszNewecki/CORE.git\ncd CORE && ./install-core.sh\n```\n\n`install-core.sh`\n\nstands up CORE and finishes by running the consequence-chain demo **live** — no LLM key required. It:\n\n- commits a function that violates\n`linkage.assign_ids`\n\n(a blocking rule) - watches CORE's audit\n**block** it - has CORE propose a fix, the governor approve it, and CORE execute it and commit the repair\n- re-audits to confirm\n**clean** - prints the full causal chain it recorded: finding → proposal → approval → execution → file change\n\nRe-run it any time with `scripts/demo.sh`\n\n.\n\nGovernance is executable.\n\nEvery enforced action records its lineage. Two consequence chains, pulled live from the CORE database — same schema, two different authorities:\n\n**Autonomous path** — risk-classified as safe, system self-approved\n\n```\nFINDING     → workflow.ruff_format_check       src/api/cli/client.py                2026-05-18 05:15:15 UTC\nPROPOSAL    → 8845dacc…   fix.format                                                2026-05-18 05:16:15 UTC\nAPPROVAL    → risk_classification.safe_auto_approval                                2026-05-18 05:16:15 UTC\nEXECUTION   → completed   (1.29s)                                                   2026-05-18 05:17:18 UTC\nFILE CHANGE → +105 / -0   98da9038 → fca9a971  src/api/cli/client.py                2026-05-18 05:17:19 UTC\n```\n\n**Human-approval path** — governor in the loop\n\n```\nFINDING     → purity.docstrings.required       src/cli/commands/audit_reporter.py   2026-05-15 08:28:29 UTC\nPROPOSAL    → a4363a81…   fix.docstrings                                            2026-05-16 13:39:34 UTC\nAPPROVAL    → principal.governor  (cli_admin)                                       2026-05-16 13:53:32 UTC\nEXECUTION   → completed   (24.5s)                                                   2026-05-16 13:55:48 UTC\nFILE CHANGE → +26 / -0    5a123426 → 71fde489  src/cli/commands/audit_reporter.py   2026-05-16 13:55:49 UTC\n```\n\nBoth chains are queryable end-to-end from `proposal_consequences`\n\nand `blackboard_entries`\n\n. The constitution decides which authority applies; the schema is identical. Reproduce them yourself with the [Consequence-chain query](https://dariusznewecki.github.io/CORE/proof-index/#consequence-chain-query) in the Proof Index.\n\nCORE separates responsibility across four repository layers — three enforced as constitutional law, and Specs (human intent). This separation is enforced as law — not convention.\n\nWhere 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.\n\n`.specs/`\n\nis read by humans and searchable by CORE's semantic layer. It is never written by CORE itself.\n\nDefines 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`\n\n).\n\nMind never executes. Mind never mutates. Mind defines law.\n\nReads constitutional constraints, orchestrates autonomous reasoning, and records every decision with a traceable audit trail. Every operation follows a structured phase pipeline:\n\n```\nINTERPRET → PLAN → GENERATE → VALIDATE → STYLE CHECK → EXECUTE\n```\n\nWill never bypasses Body. Will never rewrites Mind.\n\nDeterministic, atomic components: analyzers, evaluators, file operations, git services, test runners, CLI commands.\n\nBody performs mutations. Body does not judge. Body does not govern.\n\nEvery autonomous operation is governed by the same constitutional loop:\n\n``` php\nflowchart TD\n    A[\"🟢 GOAL\\nHUMAN INTENT\"] --> B[\"📂 CONTEXT\\nRepo state • knowledge • history\"]\n    B --> C[\"🔒 CONSTRAINTS\\nImmutable rules\\n215 rules • 15 engines\"]\n    C --> D[\"🗺️ PLAN\\nStep-by-step reasoning\\nRule-aware plan\"]\n    D --> E[\"✨ GENERATE\\nCode • changes • tool calls\"]\n    E --> F[\"✅ VALIDATE\\nDeterministic checks\\nAST • semantic • intent • style\"]\n    F -->|Pass| G[\"▶️ EXECUTE\\nApply compliant changes\"]\n    F -->|Fail| H[\"🔄 REMEDIATE\\nRepair violation\\nAutonomy Ladder\"]\n    H --> E\n    G --> I[\"✓ SUCCESS\\nChanges committed\"]\n\n    subgraph \"SAFETY HALT\"\n        direction TB\n        J[\"🚨 CONSTITUTIONAL VIOLATION\\n→ HARD HALT\\n+ FULL AUDIT LOG\"]\n    end\n\n    E -.->|Any violation| J\n    F -.->|Any violation| J\n\n    classDef phase      fill:#f8f9fa,stroke:#495057,stroke-width:2px\n    classDef constraint fill:#d1e7ff,stroke:#0d6efd,stroke-width:2.5px\n    classDef validate   fill:#fff3cd,stroke:#ffc107,stroke-width:2.5px\n    classDef halt       fill:#ffebee,stroke:#dc3545,stroke-width:3px\n\n    class A,B,D,E,G,I phase\n    class C constraint\n    class F validate\n    class J halt\n```\n\nWithin CORE:\n\n- No file outside an autonomy lane can be modified\n- No structural rule can be bypassed silently\n- No atomic action can execute outside the governed executor (inline authorization is deferred to the audit→consequence loop)\n- Decisions are phase-aware and logged with decision traces (audit persistence is best-effort — see\n*Current proof status*) - No agent can amend constitutional law\n\nIf 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.\n\nCORE'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:\n\n| Surface | Mode | Behaviour |\n|---|---|---|\n`.intent/` writes |\nhard invariant | blocked — the governance directory is immutable to all components |\n| Constitutional rules | always-blocking | block a commit regardless of strict mode |\n| Policy rules | strict vs. default | block only when `strict_mode=True` ; otherwise report |\n| Capability tier | advisory today | reports a \"would-deny\" signal; does not yet block (ADR-079) |\n| Stateless CI (GitHub Action) | rule subset | skips `knowledge_gate` + `llm_gate` (they need DB / LLM state) and reports the skip |\n| Action audit trail | best-effort | recorded when the DB write succeeds; a write-action failure is surfaced (`AUDIT_GAP` ), not silent |\n\nThe 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.\n\n| Primitive | Purpose |\n|---|---|\n| Document | Persisted, validated artifact |\n| Rule | Atomic normative statement |\n| Phase | When the rule is evaluated |\n| Authority | Who may define or amend it |\n\nEnforcement strengths: **Blocking** · **Reporting** · **Advisory**\n\n| Engine | Method |\n|---|---|\n`ast_gate` |\nDeterministic structural analysis (AST) |\n`regex_gate` |\nPattern-based text enforcement |\n`glob_gate` |\nPath and boundary enforcement |\n`cli_gate` |\nCLI surface and command-shape enforcement |\n`artifact_gate` |\nDeclared-vs-discovered artifact completeness |\n`workflow_gate` |\nPhase-sequencing and coverage checks |\n`knowledge_gate` |\nResponsibility and ownership validation |\n`action_gate` |\nAtomic-action invariants |\n`passive_gate` |\nSubstrate-enforced rules (DB/runtime marker) |\n`taxonomy_gate` |\nCapability-id ↔ atomic-action coherence (ADR-079 D9) |\n`contracts_gate` |\nCross-cutting data-contract coherence (context-level; ADR-102) |\n`llm_gate` |\nLLM-assisted semantic checks |\n`IntentGuard` * |\nRuntime write authorization (not audit) |\n\n*Runtime Gate per `.specs/papers/CORE-Gate.md`\n\n, kept here for visibility.\n\nDeterministic when possible. LLM only when necessary.\n\n215 rules across 51 rule documents. 209 are mapped to enforcement engines; 6 test-quality rules are still pending mappings. \"Mapped\" means engine-bound — not enforced in every mode: stateless CI skips `knowledge_gate`\n\nand `llm_gate`\n\n, which need the knowledge graph and an LLM provider.\n\nCORE progresses through defined levels. Each adds capability while remaining constitutionally bounded.\n\n```\nA0 — Self-Awareness       ✅  Knows what it is and where it lives\nA1 — Self-Healing         ✅  Fixes known structural issues automatically\nA2 — Governed Generation  ✅  Natural language → constitutionally aligned code\nA3 — Governed Autonomy    ✅  Daemon finds, proposes, and fixes violations unattended  ← current\nA4 — Self-Replication     🔮  Writes CORE.NG from its own understanding of itself\n```\n\n| Dependency | Version |\n|---|---|\n| Python | 3.12+ |\n| PostgreSQL | ≥ 14 |\n| Qdrant | latest |\n| Docker | for services |\n| Poetry | for deps |\n\nHonest status — what works today.CORE governsitselfend to end (the demo above), and audits any repo thathas a— in CI via the`.intent/`\n\nconstitution[GitHub Action], or locally with`core-admin code audit --offline`\n\ninside that repo.`pip install core-runtime`\n\ngives you the`core-admin`\n\nCLI.\n\nGovern your own repo (BYOR):from the CORE source tree, two commands bootstrap a fitted constitution. (1)`core-admin project onboard <path> --write`\n\ndelivers the machinery floor (no LLM, no database). (2)`core-admin project scout <path> --write`\n\nreads 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 --offline`\n\ninside that repo enforces the ratified rules immediately. Source-tree only for now — the machinery floor and`project scout`\n\nare not yet bundled in the wheel ([#674]).\n\nFastest way to see CORE today: run it on itself, below.\n\n**Full local runtime** — one command. Clone, then run the installer:\n\n```\ngit clone https://github.com/DariuszNewecki/CORE.git\ncd CORE\n./install-core.sh\n```\n\n`install-core.sh`\n\nchecks 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.\n\n## Prefer to run the steps yourself?\n\n```\npoetry install\ncp .env.example .env\ndocker compose up -d\ndocker compose exec -T postgres psql -U postgres -d core < infra/sql/db_schema_live.sql\npoetry run core-admin code audit --offline   # offline mode needs no running services\n```\n\nFull setup — services, schema, vector sync, first audit — is in [Getting Started](https://dariusznewecki.github.io/CORE/getting-started/).\n\nFull documentation, architecture deep-dive, and governance reference:\n[dariusznewecki.github.io/CORE](https://dariusznewecki.github.io/CORE/)\n\nTo understand what CORE is for before reading its implementation, start here:\n`.specs/northstar/CORE-What-It-Does.md`\n\n**Current Release:** v2.7.0 — Bounded Autonomy\n\nActive 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.\n\nAll four A3 integrity gates are now closed. No enforcement logic or operational threshold lives in `src/`\n\n— governance is declared in `.intent/`\n\nand enforced from there. The autonomous loop is circuit-breaker protected; systematic errors surface as signals rather than unbounded churn.\n\n| Gate | Meaning | Status |\n|---|---|---|\n| G1 — Loop closure | Round-trip autonomous fix demonstrated | ✅ |\n| G2 — Convergence | Circuit-breaker; resolution rate > creation rate | ✅ |\n| G3 — Consequence chain | Causality queryable end-to-end | ✅ |\nG4 — Governance in `.intent/` |\nNo enforcement logic or thresholds in `src/` |\n✅ |\n\n**Build fast with AI. Stay constitutionally aligned.**", "url": "https://wpnews.pro/news/core-deterministic-governance-rules-for-ai-generated-code-pip-installable", "canonical_source": "https://github.com/DariuszNewecki/CORE", "published_at": "2026-06-29 20:45:54+00:00", "updated_at": "2026-06-29 20:51:53.028774+00:00", "lang": "en", "topics": ["ai-safety", "ai-tools", "ai-agents", "developer-tools"], "entities": ["CORE", "Dariusz Newecki", "PyPI", "GitHub", "SemVer"], "alternates": {"html": "https://wpnews.pro/news/core-deterministic-governance-rules-for-ai-generated-code-pip-installable", "markdown": "https://wpnews.pro/news/core-deterministic-governance-rules-for-ai-generated-code-pip-installable.md", "text": "https://wpnews.pro/news/core-deterministic-governance-rules-for-ai-generated-code-pip-installable.txt", "jsonld": "https://wpnews.pro/news/core-deterministic-governance-rules-for-ai-generated-code-pip-installable.jsonld"}}