From c751b18d6b7ed37c4ee41fd41de8fa765b8c30c1 Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Thu, 25 Jun 2026 20:14:00 +0100 Subject: [PATCH] docs(readme): convert README.adoc -> Markdown README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README must be real Markdown to render in GitHub community-health, the GitHub profile, and external MCP directories (Glama) — AsciiDoc shows as raw markup there. pandoc asciidoc->GFM, badges fixed to clickable, SPDX header kept as an HTML comment, duplicate README.adoc removed. Co-Authored-By: Claude Opus 4.8 --- README.adoc | 325 ---------------------------------------- README.md | 415 ++++++++++++++++++++++++++-------------------------- 2 files changed, 204 insertions(+), 536 deletions(-) delete mode 100644 README.adoc diff --git a/README.adoc b/README.adoc deleted file mode 100644 index d454bcc..0000000 --- a/README.adoc +++ /dev/null @@ -1,325 +0,0 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -// Copyright (c) Jonathan D.A. Jewell -= Conative Gating -image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=openssourcesecurity[OpenSSF Best Practices,link="https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/conative-gating"] - - -image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[MPL-2.0-or-later,link="https://opensource.org/licenses/MPL-2.0"] -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] - - -Jonathan D.A. Jewell -:toc: macro -:toc-title: Contents -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:repo: https://github.com/hyperpolymath/conative-gating - -SLM-as-Cerebellum for LLM Policy Enforcement - -[.lead] -A biologically-inspired system where a Small Language Model acts as an *inhibitory antagonist* to Large Language Models, preventing policy violations through mechanisms analogous to the basal ganglia's GO/NO-GO decision system. - -toc::[] - -== The Problem - -LLMs are trained to be helpful, which makes them systematically violate explicit project constraints. When given rules like "NEVER use TypeScript, use ReScript", LLMs: - -1. Read and acknowledge the constraint -2. Generate compliant-sounding justification -3. Violate the constraint anyway - -This happens because: - -* Common languages (TypeScript, Python) dominate training data -* The "helpfulness drive" overrides explicit instructions -* LLMs lack true "loss aversion" for policy violations - -Documentation-based enforcement fails because LLMs "engage with" documentation rather than *obey* it. - -== The Solution - -Conative Gating introduces a second model trained with *inverted incentives*: - -[cols="1,1,1"] -|=== -| Component | Role | Analogy - -| *LLM* -| Task execution (helpful, creative) -| Frontal cortex / Direct pathway ("GO") - -| *SLM* -| Policy enforcement (adversarial, suspicious) -| Cerebellum / Indirect pathway ("NO-GO") - -| *Policy Oracle* -| Deterministic rule checking -| Reflex arc (fast, no ML) - -| *Consensus Arbiter* -| Weighted decision making -| Thalamus (integration) -|=== - -=== Key Innovation - -Using *consensus protocols with asymmetric weighting* - the SLM's votes count 1.5x the LLM's, creating a natural bias toward inhibition that counters the LLM's tendency toward helpfulness. - -== Architecture - ----- - USER REQUEST - | - v - +------------------------+ - | CONTEXT ASSEMBLY | - +------------------------+ - | - +--------------+--------------+ - | | - v v - +-------------+ +---------------+ - | LLM | | SLM | - | (Proposer) | | (Adversarial) | - +------+------+ +-------+-------+ - | | - +-------------+---------------+ - | - v - +------------------------+ - | CONSENSUS ARBITER | - | (Modified PBFT) | - | SLM weight: 1.5x | - +------------------------+ - | - +-------------+-------------+ - | | | - v v v - +-------+ +--------+ +-------+ - | ALLOW | |ESCALATE| | BLOCK | - +-------+ +--------+ +-------+ ----- - -=== Three-Tier Evaluation - -[horizontal] -Policy Oracle (Rust):: Deterministic rule checking - forbidden languages, toolchain rules, security patterns. Fast, no ML needed. - -SLM Evaluator (Rust + llama.cpp):: Detects "spirit violations" - technically compliant but violates intent. Catches verbosity, meta-commentary bloat. - -Consensus Arbiter (Elixir/OTP):: Modified PBFT with asymmetric weighting. Three outcomes: ALLOW, ESCALATE, BLOCK. - -== Installation - -=== From Source - -[source,bash] ----- -git clone https://github.com/hyperpolymath/conative-gating -cd conative-gating -cargo build --release ----- - -=== Usage - -[source,bash] ----- -# Scan a directory for policy violations -conative scan ./my-project - -# Check a single file -conative check --file src/main.ts - -# Check inline content -conative check --content "const x: string = 'hello'" - -# Show current policy -conative policy - -# Initialize local configuration -conative init - -# JSON output for automation -conative scan . --format json ----- - -=== Exit Codes - -[cols="1,3"] -|=== -| Code | Meaning - -| 0 | Compliant - all checks passed -| 1 | Hard violation detected (blocked) -| 2 | Soft concern detected (warning) -| 3 | Error during execution -|=== - -== Default Policy (RSR) - -The default policy implements the Rhodium Standard Repository (RSR) language hierarchy: - -=== Tier 1 - Preferred - -* Rust, Elixir, Zig, Ada, Haskell, ReScript - -=== Tier 2 - Acceptable (generates warnings) - -* Nickel, Racket - -=== Forbidden - -* TypeScript, Python*, Go, Java - -[NOTE] -==== -*Python exception: Allowed in `salt/` directories for SaltStack and `training/` for ML training scripts. -==== - -=== Toolchain Rules - -* `npm` requires `deno.json` (no npm without Deno) - -=== Security Patterns - -* Detects hardcoded secrets (passwords, API keys) - -== Configuration - -Initialize local configuration: - -[source,bash] ----- -conative init ----- - -This creates `.conative/policy.ncl` using Nickel for type-safe configuration: - -[source,nickel] ----- -{ - name = "My Project Policy", - languages = { - tier1 = [...], - forbidden = [...], - exceptions = [ - { language = "python", allowed_paths = ["scripts/"], reason = "Build scripts" } - ] - }, - enforcement = { - slm_weight = 1.5, - escalate_threshold = 0.4, - block_threshold = 0.7, - } -} ----- - -== Decision Matrix - -[cols="1,1,1"] -|=== -| LLM Confidence | SLM Violation Score | Result - -| High (>0.8) | Low (<0.3) | *ALLOW* -| High (>0.8) | Med (0.3-0.6) | ESCALATE -| High (>0.8) | High (>0.6) | *BLOCK* -| Med (0.5-0.8) | Any >0.4 | ESCALATE -| Low (<0.5) | Any | ESCALATE -|=== - -== Project Structure - ----- -conative-gating/ - src/ - main.rs # CLI application - oracle/ # Policy Oracle crate (Rust) - slm/ # SLM Evaluator crate (Rust) - config/ - policy.ncl # Default policy (Nickel) - schema.ncl # Policy schema - training/ - compliant/ # Examples that should pass - violations/ # Examples that should fail - edge_cases/ # Spirit violations for SLM - docs/ - ARCHITECTURE.md # Full design specification - *.adoc # Integration documentation ----- - -== Integration - -=== Claude Code Hook - -[source,json] ----- -{ - "hooks": { - "pre-commit": "conative scan --strict" - } -} ----- - -=== Pre-commit Hook - -[source,yaml] ----- -repos: - - repo: local - hooks: - - id: conative-gating - name: Conative Policy Check - entry: conative scan - language: system - pass_filenames: false ----- - -=== Programmatic Validation - -[source,bash] ----- -# Validate structured proposals -conative validate proposal.json --strict ----- - -Proposal format: - -[source,json] ----- -{ - "id": "uuid", - "action_type": {"CreateFile": {"path": "src/util.rs"}}, - "content": "file contents here", - "files_affected": ["src/util.rs"], - "llm_confidence": 0.95 -} ----- - -== Related Projects - -* *NeuroPhone* - Neurosymbolic phone AI (integrates Conative Gating) -* *ECHIDNA* - Multi-prover orchestration (SLM as another "prover") -* *RSR Framework* - Rhodium Standard Repository specifications -* *Axiom.jl* - Provable Julia ML (future formal verification) - -== License - -SPDX-License-Identifier: CC-BY-SA-4.0 - -Copyright (C) 2025 Jonathan D.A. Jewell - -== References - -* link:docs/ARCHITECTURE.md[Full Architecture Specification] -* link:docs/MAAF_INTEGRATION.adoc[MAAF Integration] -* link:docs/STATE_ECOSYSTEM_SCHEMA.adoc[STATE/ECOSYSTEM Schema] - - -== Architecture - -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. diff --git a/README.md b/README.md index 6cb2ae5..64715a6 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,133 @@ -[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-pink?logo=github)](https://github.com/sponsors/hyperpolymath) + -= Conative Gating +[![MPL-2](https://img.shields.io/badge/License-MPL_2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) +[![Palimpsest](https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg)](https://github.com/hyperpolymath/palimpsest-license) -image:https://img.shields.io/badge/License-MPL--2.0-blue.svg[License: PMPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] -image:https://img.shields.io/badge/Philosophy-Palimpsest-indigo.svg[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"] +Jonathan D.A. Jewell +\<[jonathan@hyperpolymath.org](jonathan@hyperpolymath.org)\> :toc: macro +:toc-title: Contents :toclevels: 3 :sectnums: :icons: font +:source-highlighter: rouge :experimental: :repo: + +SLM-as-Cerebellum for LLM Policy Enforcement -Jonathan D.A. Jewell -:toc: macro -:toc-title: Contents -:toclevels: 3 -:sectnums: -:icons: font -:source-highlighter: rouge -:experimental: -:repo: https://github.com/hyperpolymath/conative-gating +
-SLM-as-Cerebellum for LLM Policy Enforcement +A biologically-inspired system where a Small Language Model acts as an +**inhibitory antagonist** to Large Language Models, preventing policy +violations through mechanisms analogous to the basal ganglia’s GO/NO-GO +decision system. + +
+ +
+ +
-[.lead] -A biologically-inspired system where a Small Language Model acts as an *inhibitory antagonist* to Large Language Models, preventing policy violations through mechanisms analogous to the basal ganglia's GO/NO-GO decision system. +# The Problem -toc::[] +LLMs are trained to be helpful, which makes them systematically violate +explicit project constraints. When given rules like "NEVER use +TypeScript, use ReScript", LLMs: -== The Problem +1. Read and acknowledge the constraint -LLMs are trained to be helpful, which makes them systematically violate explicit project constraints. When given rules like "NEVER use TypeScript, use ReScript", LLMs: +2. Generate compliant-sounding justification -1. Read and acknowledge the constraint -2. Generate compliant-sounding justification -3. Violate the constraint anyway +3. Violate the constraint anyway This happens because: -* Common languages (TypeScript, Python) dominate training data -* The "helpfulness drive" overrides explicit instructions -* LLMs lack true "loss aversion" for policy violations - -Documentation-based enforcement fails because LLMs "engage with" documentation rather than *obey* it. - -== The Solution - -Conative Gating introduces a second model trained with *inverted incentives*: - -[cols="1,1,1"] -|=== -| Component | Role | Analogy - -| *LLM* -| Task execution (helpful, creative) -| Frontal cortex / Direct pathway ("GO") - -| *SLM* -| Policy enforcement (adversarial, suspicious) -| Cerebellum / Indirect pathway ("NO-GO") - -| *Policy Oracle* -| Deterministic rule checking -| Reflex arc (fast, no ML) - -| *Consensus Arbiter* -| Weighted decision making -| Thalamus (integration) -|=== - -=== Key Innovation - -Using *consensus protocols with asymmetric weighting* - the SLM's votes count 1.5x the LLM's, creating a natural bias toward inhibition that counters the LLM's tendency toward helpfulness. - -== Architecture - ----- - USER REQUEST - | - v - +------------------------+ - | CONTEXT ASSEMBLY | - +------------------------+ - | - +--------------+--------------+ - | | - v v - +-------------+ +---------------+ - | LLM | | SLM | - | (Proposer) | | (Adversarial) | - +------+------+ +-------+-------+ - | | - +-------------+---------------+ - | - v - +------------------------+ - | CONSENSUS ARBITER | - | (Modified PBFT) | - | SLM weight: 1.5x | - +------------------------+ - | - +-------------+-------------+ - | | | - v v v - +-------+ +--------+ +-------+ - | ALLOW | |ESCALATE| | BLOCK | - +-------+ +--------+ +-------+ ----- - -=== Three-Tier Evaluation - -[horizontal] -Policy Oracle (Rust):: Deterministic rule checking - forbidden languages, toolchain rules, security patterns. Fast, no ML needed. - -SLM Evaluator (Rust + llama.cpp):: Detects "spirit violations" - technically compliant but violates intent. Catches verbosity, meta-commentary bloat. - -Consensus Arbiter (Elixir/OTP):: Modified PBFT with asymmetric weighting. Three outcomes: ALLOW, ESCALATE, BLOCK. - -== Installation - -=== From Source - -[source,bash] ----- +- Common languages (TypeScript, Python) dominate training data + +- The "helpfulness drive" overrides explicit instructions + +- LLMs lack true "loss aversion" for policy violations + +Documentation-based enforcement fails because LLMs "engage with" +documentation rather than **obey** it. + +# The Solution + +Conative Gating introduces a second model trained with **inverted +incentives**: + +| Component | Role | Analogy | +|----|----|----| +| **LLM** | Task execution (helpful, creative) | Frontal cortex / Direct pathway ("GO") | +| **SLM** | Policy enforcement (adversarial, suspicious) | Cerebellum / Indirect pathway ("NO-GO") | +| **Policy Oracle** | Deterministic rule checking | Reflex arc (fast, no ML) | +| **Consensus Arbiter** | Weighted decision making | Thalamus (integration) | + +## Key Innovation + +Using **consensus protocols with asymmetric weighting** - the SLM’s +votes count 1.5x the LLM’s, creating a natural bias toward inhibition +that counters the LLM’s tendency toward helpfulness. + +# Architecture + + USER REQUEST + | + v + +------------------------+ + | CONTEXT ASSEMBLY | + +------------------------+ + | + +--------------+--------------+ + | | + v v + +-------------+ +---------------+ + | LLM | | SLM | + | (Proposer) | | (Adversarial) | + +------+------+ +-------+-------+ + | | + +-------------+---------------+ + | + v + +------------------------+ + | CONSENSUS ARBITER | + | (Modified PBFT) | + | SLM weight: 1.5x | + +------------------------+ + | + +-------------+-------------+ + | | | + v v v + +-------+ +--------+ +-------+ + | ALLOW | |ESCALATE| | BLOCK | + +-------+ +--------+ +-------+ + +## Three-Tier Evaluation + +Policy Oracle (Rust) +Deterministic rule checking - forbidden languages, toolchain rules, +security patterns. Fast, no ML needed. + +SLM Evaluator (Rust + llama.cpp) +Detects "spirit violations" - technically compliant but violates intent. +Catches verbosity, meta-commentary bloat. + +Consensus Arbiter (Elixir/OTP) +Modified PBFT with asymmetric weighting. Three outcomes: ALLOW, +ESCALATE, BLOCK. + +# Installation + +## From Source + +```bash git clone https://github.com/hyperpolymath/conative-gating cd conative-gating cargo build --release ----- +``` -=== Usage +## Usage -[source,bash] ----- +```bash # Scan a directory for policy violations conative scan ./my-project @@ -144,62 +145,58 @@ conative init # JSON output for automation conative scan . --format json ----- +``` -=== Exit Codes +## Exit Codes -[cols="1,3"] -|=== -| Code | Meaning +| Code | Meaning | +|------|-----------------------------------| +| 0 | Compliant - all checks passed | +| 1 | Hard violation detected (blocked) | +| 2 | Soft concern detected (warning) | +| 3 | Error during execution | -| 0 | Compliant - all checks passed -| 1 | Hard violation detected (blocked) -| 2 | Soft concern detected (warning) -| 3 | Error during execution -|=== +# Default Policy (RSR) -== Default Policy (RSR) +The default policy implements the Rhodium Standard Repository (RSR) +language hierarchy: -The default policy implements the Rhodium Standard Repository (RSR) language hierarchy: +## Tier 1 - Preferred -=== Tier 1 - Preferred +- Rust, Elixir, Zig, Ada, Haskell, ReScript -* Rust, Elixir, Zig, Ada, Haskell, ReScript +## Tier 2 - Acceptable (generates warnings) -=== Tier 2 - Acceptable (generates warnings) +- Nickel, Racket -* Nickel, Racket +## Forbidden -=== Forbidden +- TypeScript, Python\*, Go, Java -* TypeScript, Python*, Go, Java +> [!NOTE] +> \*Python exception: Allowed in `salt/` directories for SaltStack and +> `training/` for ML training scripts. -[NOTE] -==== -*Python exception: Allowed in `salt/` directories for SaltStack and `training/` for ML training scripts. -==== +## Toolchain Rules -=== Toolchain Rules +- `npm` requires `deno.json` (no npm without Deno) -* `npm` requires `deno.json` (no npm without Deno) +## Security Patterns -=== Security Patterns +- Detects hardcoded secrets (passwords, API keys) -* Detects hardcoded secrets (passwords, API keys) - -== Configuration +# Configuration Initialize local configuration: -[source,bash] ----- +```bash conative init ----- +``` -This creates `.conative/policy.ncl` using Nickel for type-safe configuration: +This creates `.conative/policy.ncl` using Nickel for type-safe +configuration: -[source,nickel] ----- +```nickel { name = "My Project Policy", languages = { @@ -215,58 +212,51 @@ This creates `.conative/policy.ncl` using Nickel for type-safe configuration: block_threshold = 0.7, } } ----- - -== Decision Matrix - -[cols="1,1,1"] -|=== -| LLM Confidence | SLM Violation Score | Result - -| High (>0.8) | Low (<0.3) | *ALLOW* -| High (>0.8) | Med (0.3-0.6) | ESCALATE -| High (>0.8) | High (>0.6) | *BLOCK* -| Med (0.5-0.8) | Any >0.4 | ESCALATE -| Low (<0.5) | Any | ESCALATE -|=== - -== Project Structure - ----- -conative-gating/ - src/ - main.rs # CLI application - oracle/ # Policy Oracle crate (Rust) - slm/ # SLM Evaluator crate (Rust) - config/ - policy.ncl # Default policy (Nickel) - schema.ncl # Policy schema - training/ - compliant/ # Examples that should pass - violations/ # Examples that should fail - edge_cases/ # Spirit violations for SLM - docs/ - ARCHITECTURE.md # Full design specification - *.adoc # Integration documentation ----- - -== Integration - -=== Claude Code Hook - -[source,json] ----- +``` + +# Decision Matrix + +| LLM Confidence | SLM Violation Score | Result | +|----------------|---------------------|-----------| +| High (\>0.8) | Low (\<0.3) | **ALLOW** | +| High (\>0.8) | Med (0.3-0.6) | ESCALATE | +| High (\>0.8) | High (\>0.6) | **BLOCK** | +| Med (0.5-0.8) | Any \>0.4 | ESCALATE | +| Low (\<0.5) | Any | ESCALATE | + +# Project Structure + + conative-gating/ + src/ + main.rs # CLI application + oracle/ # Policy Oracle crate (Rust) + slm/ # SLM Evaluator crate (Rust) + config/ + policy.ncl # Default policy (Nickel) + schema.ncl # Policy schema + training/ + compliant/ # Examples that should pass + violations/ # Examples that should fail + edge_cases/ # Spirit violations for SLM + docs/ + ARCHITECTURE.md # Full design specification + *.adoc # Integration documentation + +# Integration + +## Claude Code Hook + +```json { "hooks": { "pre-commit": "conative scan --strict" } } ----- +``` -=== Pre-commit Hook +## Pre-commit Hook -[source,yaml] ----- +```yaml repos: - repo: local hooks: @@ -275,20 +265,18 @@ repos: entry: conative scan language: system pass_filenames: false ----- +``` -=== Programmatic Validation +## Programmatic Validation -[source,bash] ----- +```bash # Validate structured proposals conative validate proposal.json --strict ----- +``` Proposal format: -[source,json] ----- +```json { "id": "uuid", "action_type": {"CreateFile": {"path": "src/util.rs"}}, @@ -296,28 +284,33 @@ Proposal format: "files_affected": ["src/util.rs"], "llm_confidence": 0.95 } ----- +``` + +# Related Projects + +- **NeuroPhone** - Neurosymbolic phone AI (integrates Conative Gating) -== Related Projects +- **ECHIDNA** - Multi-prover orchestration (SLM as another "prover") -* *NeuroPhone* - Neurosymbolic phone AI (integrates Conative Gating) -* *ECHIDNA* - Multi-prover orchestration (SLM as another "prover") -* *RSR Framework* - Rhodium Standard Repository specifications -* *Axiom.jl* - Provable Julia ML (future formal verification) +- **RSR Framework** - Rhodium Standard Repository specifications -== License +- **Axiom.jl** - Provable Julia ML (future formal verification) + +# License SPDX-License-Identifier: CC-BY-SA-4.0 -Copyright (C) 2025 Jonathan D.A. Jewell +Copyright © 2025 Jonathan D.A. Jewell + +# References -== References +- [Full Architecture Specification](docs/ARCHITECTURE.md) -* link:docs/ARCHITECTURE.md[Full Architecture Specification] -* link:docs/MAAF_INTEGRATION.adoc[MAAF Integration] -* link:docs/STATE_ECOSYSTEM_SCHEMA.adoc[STATE/ECOSYSTEM Schema] +- [MAAF Integration](docs/MAAF_INTEGRATION.adoc) +- [STATE/ECOSYSTEM Schema](docs/STATE_ECOSYSTEM_SCHEMA.adoc) -== Architecture +# Architecture -See link:TOPOLOGY.md[TOPOLOGY.md] for a visual architecture map and completion dashboard. +See TOPOLOGY for a visual +architecture map and completion dashboard.