# AAOS — ALAI Agent Operating System

## Executive Summary

AAOS is the enforcement runtime for the ALAI agent system. It turns optional protocols (RAG-first, GOTCHA, evidence tracking, quality gates) into **mandatory runtime gates** that every agent passes through on every lifecycle transition.

**Core insight:** Enforcement belongs at *state transitions*, not at every tool call. Per-tool-call enforcement caused 348 blocks/session (system unusable). AAOS uses 4 gates at 4 transitions — proven workable.

**Spec file:** `~/system/specs/aaos-architecture.md`  
**Deployed:** 2026-04-02  
**MC Task:** #6921

## Architecture Layers

```

Layer 5: INTERFACE     — John (Orchestrator) | MC Dashboard | Slack | CLI
Layer 4: ORCHESTRATION — pi-orchestrator.js | team-coordinator.js | pipeline-engine.js
Layer 3: ENFORCEMENT   — Spawn Gate | Exec Gate | Claim Gate | Close Gate
Layer 2: LIBRARY       — Tool Registry | Skill Registry | RAG Index | Agent Registry | Context Assembler
Layer 1: COMPUTE       — Ollama ANVIL (12 models) | Ollama FORGE (7 models) | Claude API | Local Tools
Layer 0: PERSISTENCE   — SQLite (54 DBs) | Filesystem | HiveMind | Qdrant (vector search)

```

## The 4 Enforcement Gates

<table id="bkmrk-gatewhenchecksimplem"><thead><tr><th>Gate</th><th>When</th><th>Checks</th><th>Implementation</th></tr></thead><tbody><tr><td>**SPAWN GATE**</td><td>Agent creation</td><td>MC task exists &amp; in\_progress, GOTCHA written (H/M), team composition meets minimum, budget check</td><td>`kernel/spawn-gate.js` + pi-orchestrator Step 4.5</td></tr><tr><td>**EXEC GATE**</td><td>During execution</td><td>WIP limit (max 3), tool whitelist, budget cap, timeout</td><td>Existing hooks (`alai-hooks` binary)</td></tr><tr><td>**CLAIM GATE**</td><td>Before "done"</td><td>All claims labeled L0-L4, no L0/L1 in final report, evidence artifacts exist</td><td>`kernel/claim-gate.js`</td></tr><tr><td>**CLOSE GATE**</td><td>Task completion</td><td>QA-19 score meets threshold, metrics recorded to agent\_metrics, learning posted to HiveMind</td><td>`mc.js` done handler</td></tr></tbody></table>

### Trust Levels (ZAKON #21)

<table id="bkmrk-levelmeaningallowed-"><thead><tr><th>Level</th><th>Meaning</th><th>Allowed</th></tr></thead><tbody><tr><td>L0</td><td>Unverified — agent says "done" with no evidence</td><td>❌ Never to CEO</td></tr><tr><td>L1</td><td>Self-Tested — agent ran its own tests</td><td>❌ Never to CEO</td></tr><tr><td>L2</td><td>Peer-Tested — validator or tester confirmed</td><td>✅ Minimum for reports</td></tr><tr><td>L3</td><td>Machine-Verified — exit codes, HTTP responses, DOM checks</td><td>✅ Required for aggregate claims</td></tr><tr><td>L4</td><td>Human-Verified — Alem confirmed</td><td>✅ Gold standard</td></tr></tbody></table>

## Library-in-the-Middle

The Library is a Node.js module (`kernel/library.js`) that unifies access to all existing stores. Agents don't browse `~/system/` looking for files — they call the Context Assembler which returns exactly what they need, within a token budget.

### API

```

const library = require('~/system/kernel/library.js');

// Assemble full context for an agent on a task
library.assemble(taskId, agentId)
→ { coreProtocol, agentPersona, projectContext, ragContext, skillSet, toolWhitelist, rules, tokenBudget }

// Individual registries
library.tools.search(query)          // Search 1310 tools
library.tools.audit(toolName, agentId, taskId)  // Record usage
library.skills.forAgent(agentId)     // Cookbook-matched skills
library.context.rag(query, limit)    // HiveMind semantic search
library.agents.roster(taskType, priority)  // Recommended team composition
library.rules.forTask(taskType)      // Relevant ZAKONs

```

### Token Budgets

<table id="bkmrk-modelmax-context-tok"><thead><tr><th>Model</th><th>Max Context Tokens</th></tr></thead><tbody><tr><td>Claude Opus</td><td>32,000</td></tr><tr><td>Claude Sonnet</td><td>16,000</td></tr><tr><td>Claude Haiku</td><td>4,000</td></tr><tr><td>Ollama 32B</td><td>8,000</td></tr><tr><td>Ollama 8B</td><td>4,000</td></tr></tbody></table>

## Team Composition Rules

Config: `~/system/config/team-templates.json`

<table id="bkmrk-task-typemin-teamreq"><thead><tr><th>Task Type</th><th>Min Team</th><th>Required Roles</th></tr></thead><tbody><tr><td>Trivial fix</td><td>1</td><td>Builder only</td></tr><tr><td>Feature (M priority)</td><td>3</td><td>Builder + Validator + Tester</td></tr><tr><td>Feature (H priority)</td><td>5</td><td>Builder + Validator + 2 Testers + Security</td></tr><tr><td>Architecture</td><td>3</td><td>Architect + Devil's Advocate + Validator</td></tr><tr><td>Deploy</td><td>3</td><td>Builder + DevOps + Validator</td></tr><tr><td>Financial</td><td>3</td><td>Builder + Finance + Validator</td></tr></tbody></table>

## Specialist Agents

22 agents total in `specialist-mapping.json`. Key additions (2026-04-02):

### Builders (Write/Edit access)

<table id="bkmrk-agentcompanydomainex"><thead><tr><th>Agent</th><th>Company</th><th>Domain</th><th>Expertise</th></tr></thead><tbody><tr><td>**Hadi Hariri**</td><td>CodeCraft</td><td>Kotlin/Ktor</td><td>Kotlin, Ktor, coroutines, Gradle, JVM optimization</td></tr><tr><td>**Lee Robinson**</td><td>CodeCraft</td><td>Next.js 15</td><td>App Router, React Server Components, Tailwind, Vercel</td></tr></tbody></table>

### Testers (READ-ONLY — no Write/Edit)

<table id="bkmrk-agentcompanyfocussty"><thead><tr><th>Agent</th><th>Company</th><th>Focus</th><th>Style</th></tr></thead><tbody><tr><td>**Angie Jones**</td><td>Proveo</td><td>Test automation</td><td>Frameworks, E2E, API contracts, regression</td></tr><tr><td>**James Bach**</td><td>Proveo</td><td>Exploratory testing</td><td>Skeptical, edge cases, "what would a real user do?"</td></tr><tr><td>**Lisa Crispin**</td><td>Proveo</td><td>Agile testing</td><td>Business rules, acceptance criteria, Given/When/Then</td></tr><tr><td>**Dorota Huizinga**</td><td>Proveo</td><td>Performance testing</td><td>Load testing, chaos engineering, p50/p95/p99 latencies</td></tr></tbody></table>

### Tester Assignment Rule

- **H-priority:** All 4 testers (minimum 3)
- **M-priority:** Angie Jones + 1 other (minimum 2)
- **L-priority:** Angie Jones (minimum 1)

## Database Schema (New Tables)

All in `~/system/databases/mission-control.db`

### agent\_metrics

```

CREATE TABLE agent_metrics (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  agent_id TEXT NOT NULL,         -- e.g., 'bruce-momjian'
  task_id INTEGER,                -- MC task ID
  qa_score REAL,                  -- QA-19 score (0-19)
  token_count INTEGER,            -- tokens consumed
  duration_seconds INTEGER,       -- wall clock time
  escalated BOOLEAN DEFAULT 0,    -- task escalated to higher model?
  model_used TEXT,                -- e.g., 'sonnet', 'qwen3:32b'
  claim_count INTEGER DEFAULT 0,
  evidence_count INTEGER DEFAULT 0,
  defects_found INTEGER DEFAULT 0,
  trust_level TEXT DEFAULT 'L0',  -- L0-L4
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

```

### team\_composition

```

CREATE TABLE team_composition (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  task_id INTEGER NOT NULL,
  role TEXT NOT NULL,              -- builder, validator, tester, security
  agent_id TEXT NOT NULL,
  assigned_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

```

### library\_usage

```

CREATE TABLE library_usage (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  task_id INTEGER,
  agent_id TEXT,
  tool_name TEXT,
  skill_name TEXT,
  used_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

```

## Pi-Orchestrator Integration

Wired 2026-04-02. Backup: `pi-orchestrator.js.bak-aaos-20260402`

- **Imports (line 66-72):** `library.js` + `spawn-gate.js` with graceful degradation
- **Spawn Gate (Step 4.5, line 3288):** Advisory check before task claim — logs warning if gate fails, doesn't block pi-orch
- **Library Context (line 770-782):** RAG preloading via `library.assemble()` injected into `buildPrompt()`
- **Prompt Template (line 928):** `aaosContextBlock` added between contextBlock and projectContextBlock

**Graceful degradation:** If AAOS modules fail to load, pi-orchestrator works exactly as before.

## Infrastructure Status

<table id="bkmrk-componentstatusdetai"><thead><tr><th>Component</th><th>Status</th><th>Details</th></tr></thead><tbody><tr><td>Docker</td><td>✅ UP</td><td>v29.2</td></tr><tr><td>Qdrant</td><td>✅ UP</td><td>3 collections (sessions, knowledge, hivemind) on port 6333</td></tr><tr><td>Ollama ANVIL</td><td>✅ UP</td><td>12 models on localhost:11434</td></tr><tr><td>Ollama FORGE</td><td>✅ UP</td><td>7 models on 10.0.0.2:11434</td></tr><tr><td>Tool Shed</td><td>✅ UP</td><td>240 tools on port 3050</td></tr><tr><td>HiveMind</td><td>✅ UP</td><td>25,309 entries, keyword search working</td></tr><tr><td>Hooks Binary</td><td>✅ UP</td><td>15.7MB arm64, 4 blocking + 1 advisory gate</td></tr></tbody></table>

## Enforcement Configuration

File: `~/.claude/hooks/config/enforcement.json`

<table id="bkmrk-hookzakonmode-hopbui"><thead><tr><th>Hook</th><th>ZAKON</th><th>Mode</th></tr></thead><tbody><tr><td>HopBuild</td><td>\#5</td><td>BLOCKING</td></tr><tr><td>RAG-First</td><td>\#12</td><td>BLOCKING</td></tr><tr><td>QA-19</td><td>\#14</td><td>BLOCKING</td></tr><tr><td>Evidence</td><td>\#21</td><td>BLOCKING</td></tr><tr><td>Agent Testing</td><td>\#20</td><td>ADVISORY (promote to blocking after 2 weeks)</td></tr></tbody></table>

## File Map

### New Files (created 2026-04-02)

```

~/system/kernel/library.js                — Library-in-the-Middle (283 lines)
~/system/kernel/spawn-gate.js             — SPAWN GATE enforcement
~/system/kernel/claim-gate.js             — CLAIM GATE enforcement
~/system/config/team-templates.json       — Team composition rules (6 types)
~/system/specs/aaos-architecture.md       — Full architecture spec (1060 lines)
~/system/agents/definitions/hadi-hariri.md + .yaml    — Kotlin/Ktor specialist
~/system/agents/definitions/lee-robinson.md + .yaml   — Next.js 15 specialist
~/system/agents/definitions/james-bach.md + .yaml     — Exploratory tester
~/system/agents/definitions/lisa-crispin.md + .yaml   — Agile tester
~/system/agents/definitions/dorota-huizinga.md + .yaml — Performance tester
~/system/agents/identities/{hadi,lee,james,lisa,dorota}-*.md — Full identities

```

### Modified Files

```

~/system/tools/mc.js                      — CLOSE GATE metrics recording in done handler
~/system/kernel/pi-orchestrator.js        — AAOS wiring (spawn-gate + library context)
~/system/agents/specialist-mapping.json   — 5 new agents (total: 22)
~/system/databases/mission-control.db     — 3 new tables

```

## Metrics &amp; Learning Loop

Every task completion records to `agent_metrics`:

- Agent ID, task ID, model used
- Duration (seconds from mc.js start to done)
- QA-19 score (if available)
- Evidence count (files in `/tmp/evidence-{id}/`)
- Trust level (L0-L4, based on evidence presence and force flag)

Every non-forced completion also posts a learning entry to HiveMind (knowledge type).

## Success Criteria

1. Zero agents complete a task without RAG preloading (measured by SPAWN GATE rejection count)
2. Zero L0/L1 claims reach Alem (measured by CLAIM GATE + CEO-reported false claims)
3. Every H-priority task has 3+ testers (measured by team\_composition table)
4. Agent quality improves over time (measured by avg QA-19 score per agent, monthly)
5. Token efficiency improves (measured by qa\_score / token\_count ratio, monthly)