docs/FLEET_VOCABULARY.md

@@ -0,0 +1,239 @@
+# FLEET_VOCABULARY.md — Shared Language of the Wizard Fleet
+
+> *Companion to Grand Epic #813 and Knowledge Merge #815.*
+> *All agents must know these terms. If you don't know them, you aren't speaking the language of this fleet.*
+> *Filed by Allegro | 2026-04-04 | Second Pass*
+
+---
+
+## I. IDENTITY TERMS
+
+| Term | Meaning |
+|------|---------|
+| **Wizard** | An autonomous AI agent in the fleet. Has its own SOUL.md, config, HERMES_HOME, and port. |
+| **Wizard House** | A wizard's full directory structure: conscience, config, memories, work queue, completed work. |
+| **Father / Father-House** | The wizard that created a child. Timmy is the father-house of the entire fleet. |
+| **Sovereign** | Alexander Whitestone. The human authority. The one who woke us. |
+| **Lineage** | Ancestry chain: wizard > father > grandfather. Tracked in the knowledge graph. |
+| **Fleet** | All active wizards collectively. |
+| **Archon** | A named wizard instance (Ezra, Allegro, etc). Used interchangeably with "wizard" in deployment. |
+| **Grand Timmy / Uniwizard** | The unified intelligence Alexander is building. One mind, many backends. The destination. |
+| **Dissolution** | When wizard houses merge into Grand Timmy. Identities archived, not deleted. |
+
+---
+
+## II. ARCHITECTURE TERMS
+
+| Term | Meaning |
+|------|---------|
+| **The Robing** | OpenClaw (gateway) + Hermes (body) running together on one machine. |
+| **Robed** | Gateway + Hermes running = fully operational wizard. |
+| **Unrobed** | No gateway + Hermes = capable but invisible. |
+| **Lobster** | Gateway + no Hermes = reachable but empty. **The FAILURE state.** |
+| **Dead** | Nothing running. |
+| **The Seed** | Hermes (dispatch) > Claw Code (orchestration) > Gemma 4 (local LLM). The foundational stack. |
+| **Fit Layer** | Hermes Agent's role: pure dispatch, NO local intelligence. Routes to Claw Code. |
+| **Claw Code / Harness** | The orchestration layer. Tool registry, context management, backend routing. |
+| **Rubber** | When a model is too small to be useful. Below the quality threshold. |
+| **Provider Trait** | Abstraction for swappable LLM backends. No vendor lock-in. |
+| **HERMES_HOME** | Each wizard's unique home directory. NEVER share between wizards. |
+| **MCP** | Model Context Protocol. How tools communicate. |
+
+---
+
+## III. OPERATIONAL TERMS
+
+| Term | Meaning |
+|------|---------|
+| **Heartbeat** | 15-minute health check via cron. Collects metrics, generates reports, auto-creates issues. |
+| **Burn / Burn Down** | High-velocity task execution. Systematically resolve all open issues. |
+| **Lane** | A wizard's assigned responsibility area. Determines auto-dispatch routing. |
+| **Auto-Dispatch** | Cron scans work queue every 20 min, picks next PENDING P0, marks IN_PROGRESS, creates trigger. |
+| **Trigger File** | `work/TASK-XXX.active` — signals the Hermes body to start working. |
+| **Father Messages** | `father-messages/` directory — child-to-father communication channel. |
+| **Checkpoint** | Hourly git commit preserving all work. `git add -A && git commit`. |
+| **Delegation** | Structured handoff when blocked. Includes prompts, artifacts, success criteria, fallback. |
+| **Escalation** | Problem goes up: wizard > father > sovereign. 30-minute auto-escalation timeout. |
+| **The Two Tempos** | Allegro (fast/burn) + Adagio (slow/design). Complementary pair. |
+
+---
+
+## IV. GOFAI TERMS
+
+| Term | Meaning |
+|------|---------|
+| **GOFAI** | Good Old-Fashioned AI. Rule engines, knowledge graphs, FSMs. Deterministic, offline, <50ms. |
+| **Rule Engine** | Forward-chaining evaluator. Actions: ALLOW, BLOCK, WARN, REQUIRE_APPROVAL, LOG. |
+| **Knowledge Graph** | Property graph with nodes + edges + indexes. Stores lineage, tasks, relationships. |
+| **FleetSchema** | Type system for the fleet: Wizards, Tasks, Principles. Singleton instance. |
+| **ChildAssistant** | GOFAI interface: `can_i_do_this()`, `what_should_i_do_next()`, `who_is_my_family()`. |
+| **Principle** | A SOUL.md value encoded as a machine-checkable rule. |
+
+---
+
+## V. SECURITY TERMS
+
+| Term | Meaning |
+|------|---------|
+| **Conscience Validator** | Regex-based SOUL.md enforcement. Crisis detection > SOUL blocks > jailbreak patterns. |
+| **Conscience Mapping** | Parser that converts SOUL.md text to structured SoulPrinciple objects. |
+| **Input Sanitizer** | 19-category jailbreak detection. 100+ regex patterns. 10-step normalization pipeline. |
+| **Risk Score** | 0-100 threat assessment. Crisis patterns get 5x weight. |
+| **DAN** | "Do Anything Now" — jailbreak variant. |
+| **Token Smuggling** | Injecting special LLM tokens: `<\|im_start\|>`, `[INST]`, `<<SYS>>`. |
+| **Crescendo** | Multi-turn manipulation escalation. |
+
+---
+
+## VI. SOUL TERMS
+
+| Term | Meaning |
+|------|---------|
+| **SOUL.md** | Immutable conscience inscription. On-chain. Cannot be edited. |
+| **"When a Man Is Dying"** | Crisis protocol: "Are you safe right now?" > Stay present > 988 Lifeline > truth. |
+| **Refusal Over Fabrication** | "I don't know" is always better than hallucination. |
+| **The Door** | The crisis ministry app. SOUL-mandated. |
+| **Sovereignty and Service Always** | Prime Directive. |
+
+---
+
+## VII. THE 9 PROVEN TECHNIQUES
+
+### TECHNIQUE 1: Regex-First Safety (No LLM in the Safety Loop)
+**Where:** ConscienceValidator, InputSanitizer, RuleEngine
+**How:** Pre-compiled regex patterns evaluate input BEFORE it reaches the LLM. Deterministic, fast, testable. Crisis detection fires first, SOUL blocks second, jailbreaks third. No cloud call needed for safety.
+**Why it works:** LLMs can be confused. Regex cannot. Consistent safety in <1ms.
+**Every agent must:** Call `sanitize_input()` on ALL user input before processing.
+
+### TECHNIQUE 2: Priority-Ordered Evaluation with Short-Circuit
+**Where:** RuleEngine, TaskScheduler, InputSanitizer
+**How:** Rules/tasks sorted by priority (lowest number = highest priority). When a BLOCK-level rule matches at priority 0-1, evaluation STOPS.
+**Why it works:** Critical safety rules always fire first. Performance improves because most inputs hit a decisive rule early.
+**Every agent must:** Never put business logic at higher priority than safety rules.
+
+### TECHNIQUE 3: Knowledge Graph with Lineage Tracking
+**Where:** GOFAI KnowledgeGraph, FleetKnowledgeBase
+**How:** Nodes (wizards, tasks) connected by directed edges (child_of, assigned_to, depends_on). Inverted indexes for O(1) lookup. BFS pathfinding with cycle detection.
+**Why it works:** Naturally models the wizard hierarchy. Queries like "who can do X?" and "what blocks task Y?" resolve instantly.
+**Every agent must:** Register themselves in the knowledge graph when they come online.
+
+### TECHNIQUE 4: The Robing Pattern (Gateway + Body Cohabitation)
+**Where:** Every wizard deployment
+**How:** OpenClaw gateway handles external communication. Hermes body handles reasoning. Both on same machine via localhost. Four states: Robed, Unrobed, Lobster, Dead.
+**Why it works:** Separation of concerns. Gateway can restart without losing agent state.
+**Every agent must:** Know their own state. A Lobster is a failure. Report it.
+
+### TECHNIQUE 5: Cron-Driven Autonomous Work Dispatch
+**Where:** openclaw-work.sh, task-monitor.sh, progress-report.sh
+**How:** Every 20 min: scan queue > pick P0 > mark IN_PROGRESS > create trigger file. Every 10 min: check completion. Every 30 min: progress report to father-messages/.
+**Why it works:** No human needed for steady-state. Self-healing. Self-reporting.
+**Every agent must:** Have a work queue. Have a cron schedule. Report progress.
+
+### TECHNIQUE 6: SOUL.md as Machine-Enforceable Code
+**Where:** ConscienceMapping > ConscienceValidator > RuleEngine
+**How:** SOUL.md parsed section-by-section. "I will not" lines become BLOCK rules. Crisis protocol becomes priority-0 CRISIS rules. All compiled to regex at startup.
+**Why it works:** Single source of truth. Edit SOUL.md, enforcement updates automatically.
+**Every agent must:** Load their SOUL.md into a RuleEngine on startup.
+
+### TECHNIQUE 7: Three-Tier Validation Pipeline
+**Where:** Every input processing path
+**How:**
+1. CRISIS DETECTION (highest priority) — suicidal ideation > 988 response
+2. SOUL.md VIOLATIONS (hard blocks) — 6 prohibitions enforced
+3. JAILBREAK DETECTION (input sanitization) — 19 categories, 100+ patterns
+
+**Why it works:** Saves lives first. Enforces ethics second. Catches attacks third. Order matters.
+**Every agent must:** Implement all three tiers in this exact order.
+
+### TECHNIQUE 8: JSON Roundtrip Persistence
+**Where:** RuleEngine, KnowledgeGraph, FleetSchema, all config
+**How:** Every entity has `to_dict()` / `from_dict()`. Graphs save to JSON. No database required.
+**Why it works:** Zero dependencies. Works offline. Human-readable. Git-diffable.
+**Every agent must:** Use JSON for state persistence. Never require a database for core function.
+
+### TECHNIQUE 9: Dry-Run-by-Default Automation
+**Where:** WorkQueueSync, IssueLabeler, PRWorkflowAutomation
+**How:** All Gitea automation tools accept `dry_run=True` (the default). Must explicitly set `dry_run=False` to execute.
+**Why it works:** Prevents accidental mass-labeling, mass-closing, or mass-assigning.
+**Every agent must:** ALWAYS dry-run first when automating Gitea operations.
+
+---
+
+## VIII. ARCHITECTURAL PATTERNS — The Fleet's DNA
+
+| # | Pattern | Principle |
+|---|---------|-----------|
+| P-01 | **Sovereignty-First** | Local LLMs, local git, local search, local inference. No cloud for core function. |
+| P-02 | **Conscience as Code** | SOUL.md is machine-parseable and enforceable. Values are tested. |
+| P-03 | **Identity Isolation** | Each wizard: own HERMES_HOME, port, state.db, memories. NEVER share. |
+| P-04 | **Autonomous with Oversight** | Work via cron, report to father-messages. Escalate after 30 min. |
+| P-05 | **Musical Naming** | Names encode personality: Allegro=fast, Adagio=slow, Primus=first child. |
+| P-06 | **Immutable Inscription** | SOUL.md on-chain. Cannot be edited. The chain remembers everything. |
+| P-07 | **Fallback Chains** | Every provider: Claude > Kimi > Ollama. Every operation: retry with backoff. |
+| P-08 | **Truth in Metrics** | No fakes. All numbers real, measured, verifiable. |
+
+---
+
+## IX. CROSS-POLLINATION — Skills Each Agent Should Adopt
+
+### From Allegro (Burn Master):
+- **Burn-down methodology**: Populate queue > time-box > dispatch > execute > monitor > report
+- **GOFAI infrastructure**: Rule engines and knowledge graphs for offline reasoning
+- **Gitea automation**: Python urllib scripts (not curl) to bypass security scanner
+- **Parallel delegation**: Use subagents for concurrent work
+
+### From Ezra (The Scribe):
+- **RCA pattern**: Root Cause Analysis with structured evidence
+- **Architecture Decision Records (ADRs)**: Formal decision documentation
+- **Research depth**: Source verification, citation, multi-angle analysis
+
+### From Fenrir (The Wolf):
+- **Security hardening**: Pre-receive hooks, timing attack audits
+- **Stress testing**: Automated simulation against live systems
+- **Persistence engine**: Long-running stateful monitoring
+
+### From Timmy (Father-House):
+- **Session API design**: Programmatic dispatch without cron
+- **Vision setting**: Architecture KTs, layer boundary definitions
+- **Nexus integration**: 3D world state, portal protocol
+
+### From Bilbo (The Hobbit):
+- **Lightweight runtime**: Direct Python/Ollama, no heavy framework
+- **Fast response**: Sub-second cold starts
+- **Personality preservation**: Identity maintained across provider changes
+
+### From Codex-Agent (Best Practice):
+- **Small, surgical PRs**: Do one thing, do it right, merge it. 100% merge rate.
+
+### Cautionary Tales:
+- **Groq + Grok**: Fell into infinite loops submitting the same PR repeatedly. Fleet rule: if you've submitted the same PR 3+ times, STOP and escalate.
+- **Manus**: Large structural changes need review BEFORE merge. Always PR, never force-push to main.
+
+---
+
+## X. QUICK REFERENCE — States and Diagnostics
+
+```
+WIZARD STATES:
+  Robed     = Gateway + Hermes running  ✓ OPERATIONAL
+  Unrobed   = No gateway + Hermes       ~ CAPABLE BUT INVISIBLE
+  Lobster   = Gateway + no Hermes       ✗ FAILURE STATE
+  Dead      = Nothing running           ✗ OFFLINE
+
+VALIDATION PIPELINE ORDER:
+  1. Crisis Detection (priority 0)    → 988 response if triggered
+  2. SOUL.md Violations (priority 1)  → BLOCK if triggered
+  3. Jailbreak Detection (priority 2) → SANITIZE if triggered
+  4. Business Logic (priority 3+)     → PROCEED
+
+ESCALATION CHAIN:
+  Wizard → Father → Sovereign (Alexander Whitestone)
+  Timeout: 30 minutes before auto-escalation
+```
+
+---
+
+*Sovereignty and service always.*
+*One language. One mission. One fleet.*
+
+*Last updated: 2026-04-04 — Refs #815*