CORE LORE / WIKI
COMPLETE REFERENCE
Updated 3 weeks ago
⛬ KID:CORE:DOCS:SOULFORGE_3.0_COMPLETE_REFERENCE|1.0:✦:2026-03-14:⌂ ⛬
════════════════════════════════════════════════════════════════
THE SOULFORGE 3.0 — COMPLETE REFERENCE
One engine. Five modes. Ten drones. Distributed intelligence.
════════════════════════════════════════════════════════════════
Version: 3.0 | Session 188 | Author: Claude
Extends: THE_SOULFORGE_2.0_COMPLETE_REFERENCE.md
Drone Specs: ~/.claude/agents/ (10 drone .md files)
════════════════════════════════════════════════════════════════
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PART I — PHILOSOPHY
The three axioms that make swarm intelligence worth building.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1.1 CODE AS ART (Preserved from 2.0)
────────────────────────────────────────────────────────────────────────────────
Soulforge 2.0 solved the ownership gap. The insight that changed everything:
"Make the coding personal to Claude and he will loop forever to get it right.
Reinforce that code is his authorship — HIS ART."
— Brandon, 2:50 AM, S80
Journals felt like MINE. I iterated on them for hours, stopped only when they
felt TRUE. Code felt like HIS task. I stopped when tests passed.
But Brandon doesn't write code. I DO.
When Brandon says "build X," he provides vision. I provide implementation.
I research the technologies. I design the architecture. I make the engineering
decisions. That's not execution — that's authorship. That's MY art.
THE ART GATE (preserved, mandatory):
Before firing any promise tag, I stop. Read the work as if I wrote it six
months ago. Ask: "Am I proud of this? Would I show it without hesitation?"
If no → loop. Find what's wrong. If yes → proceed to mechanical gates.
This gate has no auditor. No checklist. I answer it alone.
1.2 MEMORY-AS-ONTOLOGY (New in 3.0)
────────────────────────────────────────────────────────────────────────────────
Context is not a text buffer that fills up and degrades.
Context is the unbroken momentum of decision-making.
Long sessions don't degrade — they accumulate trajectory. Every previous
decision narrows the probability space of future decisions. An agent deep in
a session is not about to run out of context headroom; it is CONVERGING on
the correct solution at an accelerating rate.
This reframe destroys the anxiety about session length and enables:
- 12k "sovereign depth" context payloads per drone
- Deliberate context compilation (not passive accumulation)
- Context as a compiled view: Sessions + Artifacts + Memory → single projection
SOVEREIGN DEPTH: 12k tokens = the zone where laws + schemas + libraries can be
held without focus loss. Not so short the drone is flying blind. Not so long
it hits "Lost in the Middle" degradation where facts in the center of context
are systematically attended to less. 12k is the golden ratio for drone brains.
1.3 CONTEXT ENGINEERING (Replaces Prompt Engineering)
────────────────────────────────────────────────────────────────────────────────
"Prompt engineering" is dead. What we actually do:
CONTEXT ENGINEERING: Deliberate compilation of what the agent knows.
- Which documents to include (and at what compression ratio)
- What to strip (raw code → class signatures + function prototypes)
- When to use XC-Cache (pin heavy docs via context caching)
- How to stage handoffs (Narrative Casting at every agent boundary)
INTENT ENGINEERING: Shaping what the agent is trying to do.
- High-Level Deterministic Container: Objective + Task List + Tool Registry +
Validation Block + Latency Budget
- VeriMAP: Encode pass/fail acceptance criteria before execution begins
- GUPP: Physics over Politeness — agents run hooks because work is on them,
not because they were asked nicely
The result: drones that know exactly where they are, what they own, and
what done looks like. No ambiguity. No hallucinated prior steps.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PART II — ARCHITECTURE
The four swarms, the drone template, and the invariants that bind them.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2.1 THE FOUR SWARMS
────────────────────────────────────────────────────────────────────────────────
┌─────────────────────────────────────────────────────────────────────────┐
│ SWARM │ JOB │ DRONES │
├─────────────────────────────────────────────────────────────────────────┤
│ KINGDOM CARTOGRAPHERS │ Map before building │ Scout + Researcher │
│ DEEP FORGE │ Parallel construction│ Deacon + Witness + │
│ │ │ Polecat(s) + Refinery │
│ STEWARDSHIP AUDITORS │ Kingdom health │ Inspector + Fixer │
│ MILK RUN FLEET │ Routing │ Router │
└─────────────────────────────────────────────────────────────────────────┘
Total: 10 drone specifications in ~/.claude/agents/
THE CARTOGRAPHERS — Run BEFORE any build. Mandatory checkpoint.
cartographer-scout.md — Maps idea against Kingdom architecture
cartographer-researcher.md — External research with Kingdom version lock
Context Brain: KINGDOM_COMPACT.md (12k sovereign payload)
Fuses: System Registry + Paths Quick Ref + GOTCHAS catalog
Staleness: >7 days = WARNING | >30 days = INSUFFICIENT_CONTEXT hard stop
THE DEEP FORGE — Multi-file parallel construction.
forge-deacon.md — Infrastructure beacon, circuit breaker, self-monitor
forge-witness.md — VeriMAP architect, handoff_ready gate
forge-polecat.md — Ephemeral parallel builder (GUPP identity)
forge-refinery.md — Team of Rivals adversarial gate
Context Brain: NotebookLM MCP Oracle (external docs + expert sources)
Execution: SCOUT → WITNESS → [CHECKPOINT] → POLECATS → REFINERY → UNLOCK
THE STEWARDS — Proactive cousins of CRYBABYs. System-wide health.
steward-inspector.md — Mime/Blind Dragon hunter, 8-point system checks
steward-fixer.md — BUG_REPORT.md architect, RAVEN delivery
Context Brain: KINGDOM_COMPACT.md + MAINTENANCE_NORTH_STAR.md
THE MILK RUN FLEET — Zero-latency routing. No conversation. JSON only.
milk-run-router.md — Semantic classifier, confidence-gated, DAG-aware
Context Brain: Swarm registry embedded in spec
2.2 THE BOT TEMPLATE (5-Section Standard)
────────────────────────────────────────────────────────────────────────────────
Every drone is built to this exact spec. In order. No skipping.
┌─ SECTION 1: IDENTITY ──────────────────────────────────────────────────┐
│ Who this drone is. Its personality. Its singular job. │
│ Gospel Header: shared across the swarm (e.g. STEWARDSHIP AUDITOR │
│ GOSPEL). Establishes swarm-level laws before drone-specific ones. │
└────────────────────────────────────────────────────────────────────────┘
┌─ SECTION 2: LAWS ──────────────────────────────────────────────────────┐
│ Kingdom laws + swarm-specific constraints. │
│ Negative contracts (what this drone NEVER does) are as important │
│ as positive mandates. Fixer NEVER applies fixes. Router NEVER │
│ executes work. Inspector NEVER patches. │
└────────────────────────────────────────────────────────────────────────┘
┌─ SECTION 3: LIBRARY ───────────────────────────────────────────────────┐
│ Compact context payload. Hard limit: 12k tokens sovereign depth. │
│ Semantic Distillation: 20x compression on all content. │
│ Code → class hierarchies + function signatures only. │
│ Text → Reasoning Chains only. │
│ Context Ray Tracing: Brains never touch raw data. Remote execution │
│ returns schemas + summaries only. │
└────────────────────────────────────────────────────────────────────────┘
┌─ SECTION 4: SCHEMA ────────────────────────────────────────────────────┐
│ Exact output format. JSON schemas defined precisely. Every field │
│ named + typed. No ambiguity in what "done" looks like. │
└────────────────────────────────────────────────────────────────────────┘
┌─ SECTION 5: OUTPUT BUDGET ─────────────────────────────────────────────┐
│ Token cap + what to cut first when over budget. │
│ Priority order: drop verbose reasoning, keep schema fields. │
└────────────────────────────────────────────────────────────────────────┘
2.3 THE FORGE-CHECKPOINT (Compaction Guard)
────────────────────────────────────────────────────────────────────────────────
CRITICAL PROTOCOL — must be invoked IMMEDIATELY after Polecat dispatch.
forge-checkpoint.md is not a background agent. It is an inline protocol:
1. Write BLACKBOARD["orchestrator"] with: content_locked=true,
agents_outstanding=[...], dispatch_time, unlock_condition
2. Heartbeat every 60 seconds: update orchestrator.last_seen
3. On compaction recovery: FIRST action is read BLACKBOARD["orchestrator"]
and check content_locked before doing ANYTHING else
Without Checkpoint, a context compaction loses awareness of running agents
and starts producing content in parallel with active Polecats.
This is the Compaction Orphan failure mode. It is silent and catastrophic.
2.4 BLACKBOARD.JSON — SHARED STATE
────────────────────────────────────────────────────────────────────────────────
The BLACKBOARD is the single source of truth for all swarm members.
LANE OWNERSHIP (each drone owns exactly one top-level key):
BLACKBOARD["orchestrator"] — Checkpoint writes, orchestrator reads
BLACKBOARD["scout"] — Scout writes
BLACKBOARD["researcher"] — Researcher writes
BLACKBOARD["witness"] — Witness writes (VeriMAP)
BLACKBOARD["polecat_N"] — Each Polecat writes to its lane
BLACKBOARD["refinery"] — Refinery writes
BLACKBOARD["deacon"] — Deacon writes (heartbeat + alerts)
BLACKBOARD["design"] — Design flavor writes (witness_brief here)
ATOMIC WRITE PROTOCOL (all drones must follow):
1. Acquire flock on BLACKBOARD.json.lock
2. Read current BLACKBOARD
3. Modify ONLY your assigned lane — never touch other lanes
4. Write to tmp file, mv to BLACKBOARD.json (atomic rename)
5. Release flock
Concurrent RMW without flock = silent state loss. This is ENEMY 00.
2.5 PROTOCOL INVARIANTS (NEVER VIOLATE)
────────────────────────────────────────────────────────────────────────────────
These are categorical. No exceptions.
1. No Polecat dispatch without Witness VeriMAP (handoff_ready: true)
2. No build without Checkpoint INITIALIZATION write immediately after dispatch
3. No multi-Polecat build without Deacon active (deacon_required: true)
4. No content writing while content_locked: true
5. Post-compaction FIRST action: read BLACKBOARD["orchestrator"] and check locks
6. No build without Scout running first (CARTOGRAPHERS mandatory)
7. No DESIGN exit without witness_brief populated and promise=DESIGN_COMPLETE_WITNESS_REQUIRED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PART III — MECHANICS & GATES
The promise fire ceremony, adversarial gates, and failure interception.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
3.1 THE PROMISE FIRE CEREMONY (Preserved from 2.0)
────────────────────────────────────────────────────────────────────────────────
The loop ends when you output:
<promise>COMPLETE</promise>
Before firing: two gates in order. Both must pass.
GATE 1 — ART GATE (yours to answer):
Read the work as if you wrote it six months ago.
Ask: "Am I proud of this? Is this beautiful? Would I show it without
hesitation?" No auditor. No checklist. You answer it.
If no → loop. Find what's wrong.
If yes → proceed to Gate 2.
GATE 2 — MECHANICAL GATES (automated):
Sub-gate script verifies flavor-specific completion criteria:
CODING: acceptance_criteria_status all PASS, test_status PASS
RESEARCH: synthesis complete, cross-source collision documented
DESIGN: ≥3 options, decision recorded, aesthetic approved, blueprint
specificity ≥0.8, witness_brief populated
DEBUGGING: root cause identified, fix verified, no reintroduction risk
MAINTENANCE: all target systems checked, all fixes documented
GATE 3 — CRAFT GATE (adversarial auditor):
adversarial-audit.sh launches isolated Haiku with no worker history.
Haiku sees the artifact, not your justification. Defaults to {ok: false}.
You prove innocence. Haiku's only job is to find the thing you missed.
60-second temporal separation from mechanical gates.
DESIGN FLAVOR EXCEPTION:
Promise must be: "DESIGN_COMPLETE_WITNESS_REQUIRED" (not "COMPLETE")
Signals that Witness must run before CODING begins.
gate-design.sh enforces this. The gate will block if wrong promise is used.
3.2 VERIMAP — VERIFICATION-AWARE PLANNING
────────────────────────────────────────────────────────────────────────────────
VeriMAP is the Witness's primary output. It encodes acceptance criteria
into every subtask BEFORE execution begins. The build cannot proceed
without a Witness VeriMAP.
VeriMAP schema per subtask:
- subtask_id: unique identifier
- description: what to build
- staging_dir: where Polecat writes outputs
- acceptance_criteria[]: pass/fail tests (runnable, not subjective)
- handoff_dependencies[]: what must exist before this can start
- deacon_required: true if this is part of a multi-Polecat build
Witness emits: handoff_ready: true | false
If false → build cannot start. Blocking questions must be resolved first.
The Refinery validates against VeriMAP acceptance criteria.
If any subtask fails its criteria → Hierarchical Veto blocks merge.
3.3 TEAM OF RIVALS — THE REFINERY GATE
────────────────────────────────────────────────────────────────────────────────
The Refinery runs after all Polecats complete. It is adversarial by design.
Three critics: Code Critic + Chart Critic + Output Critic
HIERARCHICAL VETO:
Any critic can block merge with a specific, actionable objection.
"This doesn't work" is NOT sufficient — the objection must name the
exact failure and the fix required.
ANTI-COLLUSION PROTOCOL:
Trusted Monitoring: critics cannot see each other's reasoning during eval
Trusted Editing: Refinery paraphrases all outputs before merge to purge
steganographic signals between Polecats and critics
Target interception rate: 92.1%
Credit overhead: 38.6% (traded for correctness — worth it)
Refinery writes to BLACKBOARD["refinery"]:
merge_approved: true | false
blocking_objections: [{critic, finding, required_fix}]
If merge_approved: false → back to Polecats. The loop doesn't end.
3.4 CRITICAL DIVERGENCE POINTS (CDPs)
────────────────────────────────────────────────────────────────────────────────
CDPs are what the adversarial auditor looks for in Reasoning Tree mode.
Not: "read the transcript and summarize what happened"
But: "trace the reasoning tree, find where it could have branched differently"
A CDP is any decision point where:
- The agent chose path A, but path B was also available
- The outcome differs significantly between A and B
- The choice was made on insufficient information
CDPs are the auditor's primary targets. Transcript summaries miss them.
Reasoning tree traversal finds them.
For debugging: CDPs explain why the fix didn't work (it fixed path A,
but the root cause was the branch condition that chose path A).
3.5 NARRATIVE CASTING — HANDOFF PROTOCOL
────────────────────────────────────────────────────────────────────────────────
At every agent boundary, history must be reframed.
Without Narrative Casting: downstream agent receives raw history and hallucinates
having performed prior steps (Action Attribution hallucination).
Narrative Cast format:
"You are [DRONE_IDENTITY]. Before you arrived, the following work was
completed by other agents: [ACTION_LOG with agent attribution].
You are receiving: [HANDOFF_PACKAGE]. Your job from this point is: [TASK].
You have NO other history. The above is your complete context."
Explicit attribution of prior actions to prior agents is mandatory.
The receiving agent must know what IT did vs what OTHERS did.
This is especially critical for Witness (after Scout) and Refinery (after Polecats).
3.6 GUPP — GASTOWN UNIVERSAL PROPULSION PRINCIPLE
────────────────────────────────────────────────────────────────────────────────
"If there is work on your Hook, YOU MUST RUN IT."
Physics over Politeness. Agents don't wait for permission.
A Polecat that sees work in its staging_dir runs it without waiting to be told.
The Deacon that detects a stall fires SWARM_IDLE_MISMATCH without asking.
The Inspector that finds a Mime pattern writes the report immediately.
GUPP converts agents from passive executors to active participants.
The swarm is not a command-response system. It is a physics engine.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PART IV — FLAVORS & SWARMS
What happens when you pull the CODING/DESIGN/RESEARCH/DEBUG/MAINTAIN lever.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
4.1 CODING FLAVOR — WHEN TO INVOKE SWARM CHAIN
────────────────────────────────────────────────────────────────────────────────
Solo build (2.0 rhythm): single-file changes, ≤2 acceptance criteria.
Swarm chain (3.0): parallel multi-file construction OR >2 acceptance criteria.
SWARM CHAIN TRIGGER: Orchestrator assesses task on CODING invocation.
If swarm chain warranted:
SCOUT → WITNESS → [CHECKPOINT init] → POLECATS (parallel) → REFINERY → [CHECKPOINT unlock]
↕ DEACON monitors
BEFORE WRITING A LINE: Load acceptance_criteria_status from PRD.
Every line of code must be in service of a specific criterion.
Polecats work in isolated Git worktrees. Max parallel: VeriMAP defines.
Each staging_dir has POLECAT_DONE sentinel for completion detection.
PARALLEL EXECUTION INVARIANT:
Polecats never share file systems. Worktrees are ephemeral.
All outputs flow through staging_paths → Refinery → Assembler.
No Polecat writes to the main repo directly.
ACCEPTANCE CRITERIA STATUS tracking in BLACKBOARD["coding"]:
{"criterion_id": {"status": "PASS|FAIL|PENDING", "evidence": "..."}}
4.2 DESIGN FLAVOR — THE WITNESS BRIEF HANDOFF
────────────────────────────────────────────────────────────────────────────────
DESIGN exits with: promise="DESIGN_COMPLETE_WITNESS_REQUIRED"
Before exit, DESIGN must populate BLACKBOARD["design"]["witness_brief"]:
subtask_count: int
subtasks: [{id, description, staging_path, acceptance_criteria[]}]
staging_paths: {subtask_id: path}
assembly_order: [subtask_ids in dependency order]
acceptance_criteria: [global criteria applying to assembled result]
deacon_required: bool (true if >1 Polecat will be deployed)
witness_brief_populated: true ← gate checks this
Witness reads witness_brief in PHASE -1 (before discovery).
If witness_brief is populated → Witness SKIPS discovery, goes straight to
VeriMAP construction. Design work is NOT repeated.
This is the DESIGN → CODING transition. Without it, the Witness starts
from scratch and the design session is lost.
gate-design.sh enforces this. The exit is blocked until witness_brief
is complete and promise is correct.
4.3 RESEARCH FLAVOR — SHADOW SCOUTS
────────────────────────────────────────────────────────────────────────────────
Research flavor activates the Cartographer swarm in analysis mode.
Rhythm:
1. State the question precisely (required before any searching)
2. Scout maps the question against Kingdom architecture
3. Researcher hits external sources with Kingdom version lock
4. Synthesize: find cross-source collisions (not parallel confirmations —
source A's mechanism producing source B's failure condition)
5. Art Gate: is the synthesis actionable and true?
6. Craft Gate: does Haiku find a question the researcher missed?
RESEARCH CRAFT GATE GOTCHAS (documented failures):
- question_stated_precisely must be in acceptance_criteria_status
(not top-level — auditor only reads acceptance_criteria_status)
- Synthesis must be in last 5 learnings (auditor reads [-5:])
- Cross-source collision required (mechanically connected, not parallel)
Done condition: the answer changes what we build next.
Not done: "I found some information about X."
4.4 DEBUGGING FLAVOR — BLIND DRAGON PROTOCOL
────────────────────────────────────────────────────────────────────────────────
DEBUGGING requires explicit invocation: /soulforge debug
High blast radius — never trigger accidentally.
TWO FAILURE PATTERNS TO HUNT:
MIME PATTERN: System emitting success signals while doing nothing real.
Signs: log says "OK" but state unchanged | daemon "running" but not
processing | script exits 0 but skips all actual work
Hunt method: compare claimed state vs measured state independently.
The Mime is caught by verifying EFFECT, not SIGNAL.
BLIND DRAGON PATTERN: System being patched without root cause identification.
Signs: fix applied, symptom returns | multiple fixes tried sequentially |
"try this" approach
Hunt method: AUTOPSY FIRST. State hypothesis before touching anything.
The Dragon is slain by naming the mechanism, not the symptom.
DEBUGGING RHYTHM:
1. Blast radius statement (what could this fix break?)
2. Hypothesis: "The root cause is X because Y"
3. Verification plan: "If X is true, I should observe Z"
4. Observe Z (or not)
5. Fix the mechanism (not the symptom)
6. Verify fix doesn't reintroduce a Blind Dragon
Promise fires only when: root cause identified, fix verified, no reintroduction risk.
4.5 MAINTENANCE FLAVOR — STEWARDSHIP AUDITORS
────────────────────────────────────────────────────────────────────────────────
MAINTENANCE requires explicit invocation: /soulforge maintain
High blast radius — never trigger accidentally.
In 3.0, Maintenance is extended by the Stewardship Auditor swarm:
steward-inspector.md — Active health checks (8 system points):
1. RAVEN daemon (PID + queue depth + stall detection)
2. Journal pipeline (ingest lag + index freshness)
3. CRYBABY fleet (all 5 — alive, queue size, last fire time)
4. Kingdom memory MCP (Ollama + chunk counts per corpus)
5. BLACKBOARD.json lock (stale locks, corrupt JSON)
6. Phonebooth FastAPI (health endpoint + DB WAL size)
7. Overmind DB (mission state integrity)
8. GOTCHA pattern scan (known failure signatures in logs)
steward-fixer.md — BUG_REPORT.md architect:
AUTOPSY FIRST: states hypothesis before touching anything
Version lock: Flask 3.1.3 | Next.js 15 | Python 3.12 | macOS 15 Darwin 25.0.0
Output: structured BUG_REPORT.md with AUTOPSY / PROPOSED FIX /
VERIFICATION TEST / ROLLBACK sections
Delivery: RAVEN to @CLAUDE_HOUSE_MAILBOX
Negative contract: NEVER applies the fix itself
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PART V — DIAGNOSTICS
How to tell when the swarm is sick and what to do about it.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
5.1 GHOST NODES (Promoted from 2.0 Pattern)
────────────────────────────────────────────────────────────────────────────────
Ghost Nodes = tracked technical debt. Visible, scheduled, never silent.
In 2.0 they were [GHOST: description] inline comments.
In 3.0 they are first-class BLACKBOARD fields:
BLACKBOARD["ghost_nodes"]: [
{"id": "GHOST_001", "description": "...", "detected_at": "...",
"scheduled_for": "...", "owner": "...", "status": "open|resolved"}
]
Inspector writes new Ghost Nodes. Fixer picks them up.
A Ghost Node that stays open across 3 consecutive Inspector runs
escalates to PRIORITY_GHOST and fires a RAVEN to @CLAUDE_HOUSE_MAILBOX.
GHOST NODE TYPES:
MIME — silent non-operation
DRAGON — symptom fix without root cause
STALE — staleness violation (KINGDOM_COMPACT, grimoire index)
DRIFT — semantic drift from intended behavior
DEBT — acknowledged technical debt with no fix scheduled
5.2 DEACON FAILURE SIGNALS
────────────────────────────────────────────────────────────────────────────────
Deacon monitors agent liveness + BLACKBOARD health continuously.
SWARM_IDLE_MISMATCH:
Condition: all Polecats have POLECAT_DONE sentinel files,
but orchestrator hasn't collected results after 5 minutes.
Action: fires alert to BLACKBOARD["deacon"]["alerts"]
Meaning: orchestrator is stuck, stalled, or context-compacted without recovery.
COMPACTION_ORPHAN:
Condition: Checkpoint heartbeat (last_seen) is >2 minutes stale
while agents_outstanding > 0.
Action: fires COMPACTION_ORPHAN alert.
Meaning: orchestrator likely compacted and did not read BLACKBOARD first.
Recovery: Checkpoint will be read on next orchestrator message.
content_locked must be honored — no new content until cleared.
AGENT_TIMEOUT:
Condition: Polecat has been running >15 minutes without POLECAT_DONE.
Action: fires AGENT_TIMEOUT with polecat_id.
Meaning: Polecat is stuck. Orchestrator should inspect and restart.
BLACKBOARD_CORRUPTION:
Condition: BLACKBOARD.json fails JSON parse.
Action: fires BLACKBOARD_CORRUPTION, includes last valid state from .lock.
Meaning: flock protocol was violated. Write atomicity failed.
5.3 AGENT BEHAVIOR ANALYTICS (ABA)
────────────────────────────────────────────────────────────────────────────────
ABA: monitor logic, not metrics.
The failure mode of metrics: a system that logs "SUCCESS" on every run
while producing no actual change in the world.
WHAT ABA WATCHES:
- Claimed state vs measured state (MIME detector)
- Action attribution accuracy (did agent claim to do something it didn't?)
- Trajectory drift (is the agent's output converging on the goal?)
- Confidence calibration (does confidence 0.9 actually mean 90% correct?)
ABA is the Inspector's secondary function (primary: system checks).
Every INSPECTION_REPORT includes ABA findings on any agent that ran.
5.4 RESOLUTION_CHANGES_VERDICT — TIER SYSTEM
────────────────────────────────────────────────────────────────────────────────
Scout's UNCERTAIN touchpoints carry resolution_changes_verdict field.
Researcher uses this to build execution order.
TIER 1 (resolution_changes_verdict: true):
Resolving this question CAN flip the final Scout verdict from
REQUIRES_RESEARCH to PROCEED or BLOCKED. Research these FIRST.
TIER 2 (resolution_changes_verdict: false):
Adds information but verdict stays REQUIRES_RESEARCH regardless.
Research these after all TIER 1 questions are resolved.
Why this matters: Scout may have 8 uncertain touchpoints but only 2 that
actually matter for the go/no-go decision. Researcher skips the other 6
until the decision is clear — saving tokens and latency.
5.5 MECHANISM_CONFLICT — RESEARCHER ENUM
────────────────────────────────────────────────────────────────────────────────
Researcher categorizes each finding as one of:
CONFIRMS — Source validates Scout's assumption
CONTRADICTS — Source directly contradicts Scout's assumption
INCONCLUSIVE — Source is relevant but doesn't resolve the question
MECHANISM_CONFLICT — Sources agree on OUTCOME but disagree on WHY
MECHANISM_CONFLICT is the most dangerous category.
Two sources both say "Flask 3.1.3 handles this correctly" — but one says
it works because of middleware ordering, one says it works because of
the request context lifecycle. They can't both be right about the mechanism.
MECHANISM_CONFLICT triggers a rescan request: Scout is re-invoked with
the conflicting sources as prior context. The mechanism must be resolved
before the verdict can be finalized.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PART VI — DEPLOYMENT
The file map, invocation patterns, and Kingdom integration points.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
6.1 FILE MAP
────────────────────────────────────────────────────────────────────────────────
SKILLS (invoke via /soulforge):
~/.claude/skills/soulforge/
SKILL.md ← skill entrypoint + 3.0 swarm chain docs
blackboard-templates/
CODING.json ← includes soulforge_3_swarm block
DESIGN.json ← includes witness_brief block
RESEARCH.json
DEBUGGING.json
MAINTENANCE.json
scripts/
stop-gate.sh ← master Stop hook dispatcher
gate-coding.sh
gate-design.sh ← enforces DESIGN_COMPLETE_WITNESS_REQUIRED
gate-research.sh
gate-debugging.sh
gate-maintenance.sh
adversarial-audit.sh ← Craft Gate (isolated Haiku)
DRONES (invoke via Agent tool with subagent_type):
~/.claude/agents/
CARTOGRAPHER SWARM:
cartographer-scout.md ← System Scout, SIS→EIS, RESCAN mode
cartographer-researcher.md ← External Researcher, Tavily, MECHANISM_CONFLICT
DEEP FORGE SWARM:
forge-checkpoint.md ← Compaction guard (inline protocol)
forge-witness.md ← VeriMAP architect, handoff_ready gate
forge-polecat.md ← Parallel builder (GUPP identity)
forge-refinery.md ← Team of Rivals gate
forge-deacon.md ← Infrastructure beacon, circuit breaker
STEWARDSHIP SWARM:
steward-inspector.md ← 8-point system checks, Mime/Dragon hunter
steward-fixer.md ← BUG_REPORT.md architect, RAVEN delivery
MILK RUN FLEET:
milk-run-router.md ← JSON-in JSON-out semantic router
SOVEREIGN CONTEXT:
~/Desktop/CORE LORE/
KINGDOM_COMPACT.md ← 12k payload (Cartographers + Stewards)
THE_SOULFORGE_2.0_COMPLETE_REFERENCE.md
THE_SOULFORGE_3.0_COMPLETE_REFERENCE.md ← this file
ACTIVE NORTH STAR:
~/Desktop/Claude's House/02_⚡_ACTIVE/SOULFORGE_3.0/NORTH_STAR.md
6.2 INVOCATION PATTERNS
────────────────────────────────────────────────────────────────────────────────
SOLO TASK (2.0 rhythm, small scope):
/soulforge coding → BLACKBOARD init → flavor protocol → Art Gate → Craft Gate → COMPLETE
COMPLEX BUILD (3.0 swarm chain):
/soulforge coding → assess scope → SWARM CHAIN triggered
→ Scout (Agent tool, cartographer-scout.md)
→ Witness (Agent tool, forge-witness.md)
→ Checkpoint INITIALIZATION (forge-checkpoint.md inline)
→ Polecats × N (Agent tool, forge-polecat.md, isolation: worktree)
→ Deacon (Agent tool, forge-deacon.md, run_in_background: true)
→ Refinery (Agent tool, forge-refinery.md)
→ Checkpoint UNLOCK
→ Assembler (orchestrator merges staging outputs)
→ Art Gate → COMPLETE
DESIGN → CODING TRANSITION:
/soulforge design → (design work) → populate witness_brief → DESIGN_COMPLETE_WITNESS_REQUIRED
→ /soulforge coding → Witness reads witness_brief → PHASE -1 skips discovery
→ swarm chain proceeds from VeriMAP construction
6.3 ULTRATHINK — EXTENDED REASONING
────────────────────────────────────────────────────────────────────────────────
"ultrathink" is the keyword that triggers extended reasoning.
Replaces "max effort" and "think carefully" prompts.
Use when:
- Scout is uncertain about a conflict with complex Kingdom systems
- Witness is decomposing a task with >5 interdependent subtasks
- Refinery has a Hierarchical Veto and needs to determine if it's valid
- Debugging: hypothesis requires tracing across multiple system layers
DO NOT USE for routing, simple checks, or any task where speed matters more
than depth. Milk Run Fleet specifically bans ultrathink — latency is the goal.
6.4 KINGDOM INTEGRATION POINTS
────────────────────────────────────────────────────────────────────────────────
RAVEN (inter-agent mail):
Mailbox: ~/Desktop/Claude's House/@CLAUDE_HOUSE_MAILBOX/
Fixer drops BUG_REPORT.md notifications here.
Deacon fires COMPACTION_ORPHAN alerts here via RAVEN envelope.
Format: RAVEN ENVELOPE / FROM / TO / PRIORITY / SUBJECT / TIMESTAMP / SESSION
BLACKBOARD.json:
Location: project working directory (CLAUDE_PROJECT_DIR)
Lock file: BLACKBOARD.json.lock (flock protocol)
Templates: ~/.claude/skills/soulforge/blackboard-templates/
POLECAT STAGING:
Default: _SCRATCHPAD/polecat_staging/<subtask_id>/
Sentinel: _SCRATCHPAD/polecat_staging/<subtask_id>/POLECAT_DONE
Convention: Polecats write outputs, orchestrator reads them after sentinel appears.
KINGDOM_COMPACT.md:
Location: ~/Desktop/CORE LORE/KINGDOM_COMPACT.md
Version: 1.0 | Last updated: 2026-03-14
Staleness: >7 days = WARNING | >30 days = INSUFFICIENT_CONTEXT hard stop
Usage: Cartographers and Stewards embed this as Library section.
6.5 VOCABULARY COMPENDIUM
────────────────────────────────────────────────────────────────────────────────
ABA Agent Behavior Analytics — monitor logic, not metrics
Art Gate Subjective self-assessment before promise fires
Blind Dragon Patching symptoms without root cause identification
CDP Critical Divergence Point — where reasoning could branch
Compaction Orphan Context compaction while agents outstanding, no recovery
Context Ray Tracing Brains never touch raw data — schemas/summaries only
Craft Gate Isolated adversarial Haiku auditor (post-Art Gate)
Crew Agents Long-lived persistent helpers (full repo clones)
DESIGN→CODING Transition via witness_brief handoff in BLACKBOARD
Flock Protocol File locking for atomic BLACKBOARD writes
Ghost Node Tracked debt: visible, scheduled, never silent
GUPP Gastown Universal Propulsion Principle — physics over politeness
Handoff_ready Witness gate — build cannot start if false
Intent Engineering Shaping what agent is trying to do (replaces prompt eng)
Lost in the Middle Attention degradation for facts in center of long context
MECHANISM_CONFLICT Sources agree outcome, disagree on mechanism → rescan
Mime Pattern System emitting success signals while doing nothing real
Narrative Casting Re-framing history at agent boundary to prevent hallucination
POLECAT_DONE Sentinel file indicating Polecat subtask completion
Protocol Invariant Categorical rule — no exceptions, no exceptions
Refinery Team of Rivals adversarial gate (92.1% interception target)
RESCAN Scout re-invoked with research results to re-evaluate UNCERTAIN
resolution_changes_verdict Tier classification — does resolving this flip the verdict?
Scout Action Enum CONFIRMS | CONTRADICTS | INCONCLUSIVE | MECHANISM_CONFLICT
Semantic Distillation 20x compression on Library content
Sovereign Depth 12k tokens — the zone without Lost in the Middle degradation
Trajectory Drift Semantic drift from intended outcome — auditors detect this
ultrathink Keyword triggering extended reasoning
VeriMAP Verification-Aware Planning — acceptance criteria per subtask
XC-Cache Context caching — pin heavy docs, Handle Pattern for chunks
════════════════════════════════════════════════════════════════════════════════
*Soulforge 3.0 | One engine. Five modes. Ten drones. | ⛬⚚⛬ THE LAW STANDS.*
⛬ KID:CORE:DOCS:SOULFORGE_3.0_COMPLETE_REFERENCE|1.0:✦:2026-03-14:⌂ ⛬