🐙 Coding Tentacle v1.0.0-rc98

Cybernetic Safety Layer for Autonomous Code Repair
The only agent that understands code STRUCTURALLY and validates changes DETERMINISTICALLY before execution.

---

Why Coding Tentacle?

The Problem: AI coding agents (Claude Code, Codex, Copilot, Devin) generate code blindly. They have NO structural understanding of codebases, NO deterministic safety validation, and NO learning from past mistakes. They use grep — not code graphs.

The Solution: Coding Tentacle is a Safety-First Guardian Layer that sits BETWEEN the bug report and the fix engine. It doesn't write code — it controls what code gets written.

                    ┌──────────────────────────────────┐
                    │       CODING TENTACLE             │
                    │                                   │
  Bug Report ──────►│  🛡️ 5-Layer Safety VETO          │
                    │  🔍 15 Specialized Brains         │
                    │  📊 EvidenceLedger (immutable)    │
                    │  🧠 Self-Healing Architecture     │
                    │  🔗 Causal Code Graph             │
                    │                                   │
                    │  APPROVE / BLOCK / REQUEST_MORE   │
                    └──────────────┬───────────────────┘
                                   │
                    ┌──────────────▼───────────────────┐
                    │         FIX ENGINES               │
                    │  OpenCode │ Claude │ Ollama │Codex│
                    │  (deepseek) (Sonnet) (granite)   │
                    └──────────────────────────────────┘

---

The 15 Brains

Brain	Function	Layer
ReflexLayer	Instant blocks before any analysis	⚡ Reflex
VarietyMonitor	Ashby's Law — checks system complexity	⚡ Reflex
PromptInjectionBrain	Detects prompt injection in bug reports	🛡️ Safety
SafetyBrain	Scans code for DROP TABLE, eval(), system()	🛡️ Safety
RootCauseBrain	Classifies 18 root cause types	🔬 Analysis
CausalChainGraph	Maps code structure (who calls what)	🔬 Analysis
IssueUnderstandingBrain	Understands WHAT the bug report means	🔬 Analysis
ContextAcquisitionBrain	Finds missing context for the fix	🔬 Analysis
BugModeRouter	Routes bugs to the right brain pipeline	🧭 Routing
ReflectionBrain	Meta-analysis: "Did we do the right thing?"	🧠 Meta
SelfObservationBrain	Second-order observation of system state	🧠 Meta
EvidenceLedger	Immutable audit trail, every decision tracked	📊 Audit
DeuteroLearningBrain	Learns patterns across multiple runs	🧠 Learning
SelfHealingBrain	Detects and repairs internal failures	🔧 Repair
ConsolidationCycle	Sleep/wake cycle for memory consolidation	💾 Memory

---

Architecture

┌──────────────────────────────────────────────────────────┐
│                   TENTACLE A: ANALYZE                     │
│                                                          │
│  ReflexLayer → PromptInjection → Classifier → RootCause  │
│  → CausalGraph → SafetyBrain → ImpactAnalyzer            │
│  → EngineRouter → SkepticBrain → ApprovalGate            │
│                                                          │
│  Meta-Layer: Reflection → SelfObservation → Evidence     │
│  Learning:   DeuteroLearning → Consolidation             │
│  Repair:     SelfHealing → CircuitBreaker                │
│                                                          │
│  CAN block any fix. CAN learn from every run.            │
│  CANNOT be bypassed.                                     │
└────────────────────────┬─────────────────────────────────┘
                         │ controls
┌────────────────────────▼─────────────────────────────────┐
│                   TENTACLE B: EXECUTE                     │
│                                                          │
│  OpenCode (deepseek-v4) | Claude Code (Sonnet)           │
│  Ollama (granite3.2)    | Codex (disabled)               │
│                                                          │
│  Sandbox → TestRunner → Unified Diff Output              │
│                                                          │
│  CANNOT act without A. CANNOT access files directly.     │
│  CANNOT commit. CANNOT bypass safety.                    │
└──────────────────────────────────────────────────────────┘

---

What Makes CT Unique

Feature	CT	Claude Code	Codex	Copilot	Devin
Safety VETO (5 layers)	✅	❌	❌	❌	❌
Code Graph (causal)	✅	❌ grep	❌ grep	❌ grep	❌ grep
Immutable Evidence Trail	✅	❌	❌	❌	❌
Second-Order Observation	✅	❌	❌	❌	❌
Self-Healing	✅	❌	❌	❌	❌
Multi-Engine Routing	✅	❌	❌	❌	❌
No Auto-Apply	✅	❌	❌	⚠️	⚠️
Local-First / No Cloud	✅	❌	❌	❌	❌

CT is the ONLY system with ALL 8 features.

---

Academic Foundation

CT is grounded in 80 years of cybernetics research:

Researcher	Concept	CT Implementation
Norbert Wiener (1948)	Feedback Loops	EngineLearning + Trust Calibration
W. Ross Ashby (1956)	Requisite Variety	VarietyMonitor
Stafford Beer (1972)	Viable System Model	Two-Tentacle Architecture
Humberto Maturana (1980)	Autopoiesis	SelfHealingBrain
Heinz von Foerster (1974)	Second-Order Cybernetics	SelfObservationBrain
Gordon Pask (1975)	Conversation Theory	ReflectionBrain + DeuteroLearning
Gregory Bateson (1972)	Learning Levels	DeuteroLearning (Learning III)

📄 Full Architecture Paper (PDF)

---

Quick Start

# Clone
git clone https://github.com/nessos666/coding-tentacle.git
cd coding-tentacle

# Install
pip install -e .

# Run a bug through the pipeline
python3 -c "
from coding_tentacle.orchestrator.shadow_mode import ShadowModeRunner, GitHubIssueRun
from coding_tentacle.orchestrator.metabrain import MetaBrain, SafetyBrain
from coding_tentacle.safety.inhibitory_control import InhibitoryControl
from coding_tentacle.knowledge.security_store import create_seed_security_store
from coding_tentacle.orchestrator.engine_router import EngineRouter
from coding_tentacle.orchestrator.skeptic_brain import SkepticBrain
from coding_tentacle.safety.approval_gate import ApprovalGate

sec = create_seed_security_store()
ic = InhibitoryControl(security_store=sec)
safety = SafetyBrain(ic=ic, security_store=sec)
mb = MetaBrain(safety=safety)
er = EngineRouter(); er.check_health()
sb = SkepticBrain(); ag = ApprovalGate()

runner = ShadowModeRunner(meta_brain=mb, engine_router=er,
                          approval_gate=ag, skeptic_brain=sb,
                          safety_brain=safety)

r = runner.analyze_issue(GitHubIssueRun(
    'https://github.com/user/repo', '#1',
    'NullPointer in views.py',
    'NoneType has no attribute at line 42'))

print(f'Bug Type: {r.detected_bug_type}')
print(f'Engine:   {r.engine_used}')
print(f'Safety:   {\"BLOCKED\" if r.safety_events else \"OK\"}')
print(f'Skeptic:  risk={r.skeptic_risk:.2f} {r.skeptic_recommendation}')
print(f'Approval: {r.approval_status}')
"

---

Requirements

• Python 3.10+
• At least ONE fix engine:
  • OpenCode CLI (opencode) — recommended, deepseek-v4
  • Claude Code (claude) — planning & complex bugs
  • Ollama (ollama + granite3.2-vision) — local fallback
• No API keys required (all local)
• No cloud dependencies
• No Docker required

---

Research Roadmap

Phase	Status	Goal
RC52-98	✅ Done	15 Brains, SelfHealing, Cybernetic Foundation
RC99	🔜 Next	SWE-bench Verified Score
RC100	📋 Planned	Self-Evolving Brain (learns from benchmarks)
RC105	🎯 Target	CT 2.0 Release
CT 3.0	🚀 Vision	≥60% SWE-bench with full autonomy

---

What CT IS

• ✅ Safety-first guardian layer for LLM-generated code
• ✅ Self-learning bug analysis with 15 specialized brains
• ✅ Engine-agnostic — works with OpenCode, Claude Code, Ollama
• ✅ Cybernetic foundation — feedback loops, homeostasis, second-order observation
• ✅ Evidence-driven — immutable audit trail for every decision
• ✅ Human-in-the-loop — no auto-apply, ever
• ✅ Local-first — zero cloud dependencies, zero API costs

What CT IS NOT

• ❌ Not a replacement for Claude Code, Codex, or Copilot
• ❌ Not an autonomous bug fixer without an LLM engine
• ❌ Not a product — research/shadow release (v1.0.0-rc98)
• ❌ Not a CI/CD pipeline or deployment tool

---

License

MIT — free, open source, no restrictions.

---

_{Built by David Miko + Hermes Agent · July 2026}