diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..d454bcc --- /dev/null +++ b/README.adoc @@ -0,0 +1,325 @@ +// 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 deleted file mode 100644 index 64715a6..0000000 --- a/README.md +++ /dev/null @@ -1,316 +0,0 @@ - - -[![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) - -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 - -
- -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 - -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**: - -| 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 - -```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 - -| 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: - -```bash -conative init -``` - -This creates `.conative/policy.ncl` using Nickel for type-safe -configuration: - -```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 - -| 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 - -```yaml -repos: - - repo: local - hooks: - - id: conative-gating - name: Conative Policy Check - entry: conative scan - language: system - pass_filenames: false -``` - -## Programmatic Validation - -```bash -# Validate structured proposals -conative validate proposal.json --strict -``` - -Proposal format: - -```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 © 2025 Jonathan D.A. Jewell - -# References - -- [Full Architecture Specification](docs/ARCHITECTURE.md) - -- [MAAF Integration](docs/MAAF_INTEGRATION.adoc) - -- [STATE/ECOSYSTEM Schema](docs/STATE_ECOSYSTEM_SCHEMA.adoc) - -# Architecture - -See TOPOLOGY for a visual -architecture map and completion dashboard.