diff --git a/docs/FLEET_VOCABULARY.md b/docs/FLEET_VOCABULARY.md new file mode 100644 index 0000000..c0d544d --- /dev/null +++ b/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]`, `<>`. | +| **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*