Atomizer/hq/workspaces/manager/MIND_MAP_AUDIT.md

# MIND MAP AUDIT — Atomizer Master Mind Map

Audit target: `atomizer-master-mind-map.excalidraw`  
Audit date: 2026-02-21  
Mind-map text nodes extracted: 385

Scope reviewed:
- `atomizer-master-mind-map.excalidraw` (all text extracted)
- `/home/papa/repos/Atomizer/` (full directory inventory)
- `/home/papa/repos/Atomizer/docs/ARCHITECTURE.md`
- `/home/papa/repos/Atomizer/docs/QUICK_REF.md`
- `/home/papa/repos/Atomizer/docs/protocols/` (all files)
- `/home/papa/repos/Atomizer/docs/plans/` (all files)
- `/home/papa/repos/Atomizer/docs/guides/` (all files)
- `/home/papa/repos/Atomizer/optimization_engine/` (all subdirs/files inventoried)
- `/home/papa/repos/Atomizer/atomizer-dashboard/` (all subdirs/files inventoried)
- `/home/papa/atomizer/` (HQ workspace + configs + bridges + agent workspaces)
- `/home/papa/atomizer/workspaces/manager/context-docs/` (all files)

---

## A. COMPLETENESS AUDIT

### A1) Top-level Atomizer codebase coverage (`/home/papa/repos/Atomizer`)

| Module | Mind map status | Notes |
|---|---|---|
| `optimization_engine/` | ✅ Present | Strongly represented (Z3 + Z4 + ACE + validation + study mgmt). |
| `docs/` | ⚠️ Present but incomplete | Only high-level protocol names are shown; actual docs are much deeper and include many plans/guides not represented. |
| `hq/` | ⚠️ Present but incomplete | Mind map has "Atomizer HQ" concept, but current implemented cluster reality is not accurately represented. |
| `studies/` | ⚠️ Present but incomplete | Mentioned conceptually as study outputs/archives; actual study folder lifecycle and formats are not mapped. |
| `config/` | ✅ Present | Mentioned via spec/config/sampler/paths. |
| `templates/` | ⚠️ Present but incomplete | Mentioned as "Templates System" but no linkage to actual template registries and CLI/template loaders. |
| `atomizer-dashboard/` | ⚠️ Present but incomplete | Dashboard + Canvas shown, but concrete backend/frontend subsystems are mostly missing. |
| `atomizer_field_training_data/` | ❌ Missing | This training-data corpus is central to neural workflow (`OP_05`) and not explicitly represented as a storage domain. |
| `knowledge_base/` | ⚠️ Present but incomplete | "LAC" is present conceptually; concrete structure/use paths are missing. |
| `examples/` | ❌ Missing | Useful onboarding/validation material not represented. |
| `tools/` | ❌ Missing | Significant tooling area (including MCP/NX tooling) is not represented. |
| `tests/` | ❌ Missing | No explicit test/verification zone despite quality emphasis. |
| `projects/` | ❌ Missing | Active project workspace model is not represented. |
| `mcp-server/` | ❌ Missing | No representation of MCP tool layer. |
| `nx_journals/` | ❌ Missing | NX integration mechanics are shown conceptually but journal assets not represented. |
| `archive/` | ⚠️ Present but incomplete | "History/Archive" concepts appear, but archive code/docs split is not represented. |

### A2) Optimization engine completeness (`/home/papa/repos/Atomizer/optimization_engine`)

Directory coverage vs map:
- `19/45` directories are directly represented by name/concept.
- `26/45` are missing as explicit module-level nodes.

#### ✅ Present and generally accurate
- `core/` (`OptimizationRunner`, Optuna integration, method selection)
- `plugins/` + hook framework
- `study/` (`creator`, `state`, `continuation`, `benchmarking`, `reset`)
- `reporting/` (`results_analyzer`, `landscape_analyzer`, `visualizer`, report generation)
- `context/` (`playbook`, `reflector`, `feedback_loop`, `session_state`, `cache_monitor`, `compaction`)
- `gnn/` (neural/graph functions, polar graph, backfill concepts)
- `intake/`, `interview/`, model introspection concept
- `nx/` execution/manipulation layer
- `validation/` and `validators/`

#### ⚠️ Present but incomplete/inaccurate
- Hook lifecycle details are incomplete/wrong for current core runner (details in Section B).
- "Inline calculations" and `post_calculation` are shown as default lifecycle; in code this is mainly in the `future/` LLM runner path.
- Neural subsystem is represented conceptually, but many implementation modules are not mapped (`processors/surrogates/*`, `gradient_optimizer.py`, ensemble/auto-trainer stack).
- Spec system is present at concept level, but concrete implementation modules are missing (`config/spec_models.py`, `config/spec_validator.py`, `schemas/atomizer_spec_v2.json`).

#### ❌ Missing entirely (important)
- `processors/surrogates/` family (`neural_surrogate.py`, `auto_trainer.py`, ensemble/generic/adaptive components)
- `config/spec_models.py`, `config/spec_validator.py`, `config/migrator.py`, `config/setup_wizard.py`
- `utils/` operational modules (`dashboard_db.py`, `realtime_tracking.py`, `study_archiver.py`, `study_cleanup.py`, `trial_manager.py`)
- `model_discovery/`
- `hooks/nx_cad/*` and `hooks/nx_cae/*` granular modules
- `extractors/` concrete breadth is underrepresented (large extractor library beyond a generic "OP2/F06 parsing")

### A3) Dashboard completeness (`/home/papa/repos/Atomizer/atomizer-dashboard`)

Directory coverage vs map:
- `18/36` directories represented by concept.
- `18/36` missing.

#### ✅ Present and accurate
- Dashboard web UI exists (`frontend`) with analytics/monitoring concepts.
- Canvas `SpecRenderer` exists and is central.
- WebSocket real-time streams exist.
- Intake/introspection/spec API layers exist.

#### ⚠️ Present but incomplete
- Mind map does not capture backend route/service decomposition:
  - `backend/api/routes/*` (spec/intake/nx/optimization/context/devloop/etc.)
  - `backend/api/services/*` (spec manager, interview engine, nx introspection, session manager)
  - `backend/api/websocket/optimization_stream.py`
- Frontend architecture is far richer than the map shows:
  - `components/canvas/*` (nodes, panels, palette, visualization)
  - `hooks/*` (spec store, websocket, optimization stream, chat/tooling)
  - multiple pages (`Studio`, `CanvasView`, `Dashboard`, `Analysis`, `Results`, `Setup`, `Insights`)

#### ❌ Missing entirely
- Claude Code integration route/services (`routes/claude_code.py`, services around Claude sessions).
- DevLoop UI integration (`components/devloop`, `routes/devloop.py`).
- Intake UI implementation details (`components/intake/*`) beyond generic "file drop" notion.

### A4) Documentation completeness

#### Protocol docs (`/home/papa/repos/Atomizer/docs/protocols`)
- All protocol files are effectively missing at file-level in the map.
- The map references OP/SYS identifiers, but does not map the actual protocol corpus structure:
  - `operations/OP_01..OP_08`
  - `system/SYS_10..SYS_18`
  - `extensions/EXT_01..EXT_04`

Status: ⚠️ Present at label level, ❌ missing at module/file level.

#### Plans/guides
- `docs/plans/*` and `docs/guides/*` are largely unrepresented as architecture assets.
- These docs include key implementation/reality indicators (Studio plan, introspection plan, unified config, dashboard implementation status, neural workflow guides).

Status: ❌ Missing as a first-class architecture layer.

### A5) Agent system completeness (`/home/papa/atomizer` + context docs)

#### ✅ Present concepts
- OpenClaw multi-agent orchestration concept.
- Job queue and Syncthing bridge concept.
- Trust boundaries / approval gates concept.

#### ⚠️ Present but inaccurate
- Current production-like state is **8-agent multi-instance cluster** (Discord-heavy), not 13-agent fully active operation.
- Slack-first framing is now mixed/outdated relative to current implemented state.

#### ❌ Missing entirely
- Discord bridge and multi-instance cluster mechanics:
  - `config/openclaw-discord.json`
  - `discord-bridge/` implementation
  - cluster operational docs (`docs/hq/08-SYSTEM-IMPLEMENTATION-STATUS.md`)
- Mission control / taskboard orchestration system:
  - `mission-control/` and `workspaces/shared/taskboard.json`
- Agent workspace protocol surface (`workspaces/*/AGENTS.md`, `TOOLS.md`, `MEMORY.md`, shared skills/protocols)
- Manager founding context-docs are not represented as a roadmap-vs-reality lens.

---

## B. ACCURACY AUDIT

### B1) Data flow and lifecycle correctness

#### ⚠️ Trial lifecycle in map is not fully accurate for active core runner
Map shows 10-step lifecycle including `pre_mesh` and `post_calculation` each trial.

Actual core runner (`optimization_engine/core/runner.py`) executes:
1. `pre_solve`
2. model update
3. `post_mesh`
4. solve
5. `post_solve`
6. extraction
7. `post_extraction`
8. constraints/objective composition
9. `custom_objective`

Evidence:
- `optimization_engine/core/runner.py:362`
- `optimization_engine/core/runner.py:378`
- `optimization_engine/core/runner.py:395`
- `optimization_engine/core/runner.py:443`
- `optimization_engine/core/runner.py:506`

`post_calculation` exists mainly in future/LLM path:
- `optimization_engine/future/llm_optimization_runner.py:294`

Verdict: ⚠️ Partially accurate, but currently overstates default lifecycle behavior.

### B2) Agent topology claim is outdated/inaccurate

Map claim: "13 AGENTS (OpenClaw Multi-Agent)" and Slack-centered operation.

Current implemented config and status indicate **8 agents** and strong Discord routing:
- `config/openclaw-discord.json` agent IDs at lines 19, 29, 38, 47, 56, 65, 74, 83
- `dashboard/SPEC.md:32` ("8 agents")
- `docs/hq/08-SYSTEM-IMPLEMENTATION-STATUS.md:11` (8 independent OpenClaw processes)

Verdict: ⚠️ Roadmap intent is represented as current state; should be split into "current" vs "target".

### B3) Protocol numbering consistency mismatch

Map references:
- Operations OP_01–OP_11
- System SYS_10–SYS_20

Primary protocol docs in repo (`docs/protocols/README.md`) currently include:
- OP_01..OP_08
- SYS_10..SYS_18

Additional OP_09/10/11 and SYS_19/20 exist in HQ skill/workspace protocol layer under `/home/papa/atomizer/skills/atomizer-protocols/protocols/`.

Verdict: ⚠️ Partially accurate but conflates primary repo protocol set with HQ extension protocol set.

### B4) Neural architecture claims are partly aspirational and path-outdated

- Concepts are directionally right (GNN, hybrid switching, uncertainty, training/export pipeline).
- But some documented file references are stale (e.g., `atomizer-field/...` references; no `atomizer-field` directory in `/home/papa/repos/Atomizer`).
- Performance numbers (4.5ms, 2200x, <3% error) appear as hard facts without direct benchmark provenance in current map.

Verdict: ⚠️ Good conceptual framing, but should separate verified metrics from target/benchmark claims.

### B5) Dashboard/Canvas sync claim is mostly accurate

Map claim: "Spec ↔ Canvas ↔ Backend ↔ Claude, WebSocket real-time updates"

Evidence in code:
- Spec API + sync route (`backend/api/routes/spec.py`)
- Canvas `SpecRenderer` (`frontend/src/components/canvas/SpecRenderer.tsx`)
- Spec WebSocket hook (`frontend/src/hooks/useSpecWebSocket.ts`)
- Optimization stream websocket (`backend/api/websocket/optimization_stream.py`, `frontend/src/hooks/useOptimizationStream.ts`)

Verdict: ✅ Accurate at architecture level.

### B6) Failure mode claims are mixed

- NX crash continuation: supported by `study/continuation.py` and resume flow.
- Disk optimization protocol: exists (`OP_07`) and utilities (`study_archiver.py`, cleanup modules).
- "Agent failure → circuit breaker (2 retries max)" is not clearly implemented as a concrete engine behavior in inspected runtime code.

Verdict: ⚠️ Mixed; some claims are real, some are policy/plan-level rather than implemented behavior.

### B7) Ordering/zone labeling quality issue

- Z7 appears before Z6 in the canvas text order.

Verdict: ⚠️ Not a functional bug, but hurts readability and narrative flow.

---

## C. STRUCTURAL CRITIQUE

### C1) Zone organization quality

Current map is strong as a single narrative board, but it mixes:
- current implementation
- planned future state
- company operating model
- protocol taxonomy
- performance claims

in one layer, with no visual distinction.

This is the main structural weakness.

### C2) Recommended grouping model

Use 4 super-layers (with explicit badges):
1. `Runtime (Now)`
2. `Roadmap (Planned)`
3. `Governance/Process`
4. `Interfaces & Data Contracts`

This prevents roadmap items (13-agent full company, OP/SYS full expansion) from being misread as already live.

### C3) Flow direction critique

Left→right is workable for technical flow, but the map currently has at least 3 competing flows:
- optimization data pipeline
- HQ orchestration/agent workflow
- product evolution roadmap

These should be separated into parallel swimlanes rather than interwoven in one horizontal direction.

### C4) Missing relationship edges

Important edges absent or too implicit:
- `AtomizerSpec schema` ↔ `spec_models.py/spec_validator.py` ↔ `dashboard spec APIs`
- `training_data_exporter` ↔ `atomizer_field_training_data/` ↔ `neural_surrogate`
- `mission-control/taskboard` ↔ `agent orchestration`
- `docs/protocols` (canonical) ↔ `skills/atomizer-protocols` (operational overlays)
- `Discord/OpenClaw cluster status docs` ↔ infrastructure zone

---

## D. PROPOSED CHANGES

1. [ADD] Split each major zone into `NOW` and `TARGET` bands.
2. [ADD] New explicit node group: `Spec Contract Layer` with:
   - `optimization_engine/schemas/atomizer_spec_v2.json`
   - `optimization_engine/config/spec_models.py`
   - `optimization_engine/config/spec_validator.py`
   - `atomizer-dashboard/backend/api/routes/spec.py`
3. [ADD] New explicit node group: `Surrogate Runtime Layer` with `processors/surrogates/*` and training/export feedback loop.
4. [ADD] New node group for `Taskboard/Mission Control` (`/home/papa/atomizer/mission-control`, `workspaces/shared/taskboard.json`).
5. [ADD] New `Platform Runtime` block showing current 8-agent OpenClaw multi-instance + Discord bridge reality.
6. [MOVE] Put Z6 before Z7 in board order.
7. [MOVE] Move roadmap phases out of core architecture flow into a dedicated "Evolution" strip.
8. [FIX] Trial lifecycle to match current core runner (or label current one as "LLM/Future path").
9. [FIX] Agent count/state labeling: "Current: 8 active" and "Target: 13 full company".
10. [FIX] Protocol counts: distinguish canonical repo protocols (`OP_01..08`, `SYS_10..18`) from HQ extension protocols (`OP_09..11`, `SYS_19..20`).
11. [FIX] Replace/annotate stale `atomizer-field` path references with current paths (or mark as external planned module).
12. [FIX] Mark performance numbers as `benchmarked on <date>/<study>` or `target`.
13. [EXPAND] Dashboard architecture with backend route/service and frontend canvas/store/websocket decomposition.
14. [EXPAND] Optimization engine internal packages: `config/`, `processors/`, `utils/`, `validation/validators`.
15. [EXPAND] Infrastructure: include Discord/OpenClaw config files and bridge implementation.
16. [EXPAND] Include tests/quality toolchain as a first-class architecture concern.
17. [REMOVE] Unqualified hard claims that are not code-backed (e.g., specific retry/circuit-breaker behavior) unless source-linked.

---

## E. INNOVATIVE SUGGESTIONS

1. Add a **"Truth Overlay"**:
   - Green border = implemented and source-verified.
   - Yellow border = implemented but partial.
   - Blue border = planned.
   - Red border = known mismatch/debt.

2. Add a **"Source Pin"** mini-label on each non-trivial node:
   - Example: `runner.py:362` or `openclaw-discord.json:19`.
   - This turns the map into a navigable architecture index.

3. Add a **"Time Stamp"** to volatile zones (agents, infra, roadmap):
   - `Verified: 2026-02-21`.

4. Add a **"10-minute onboarding path"** (numbered route):
   - 1) Inputs/Spec
   - 2) Runner lifecycle
   - 3) Dashboard/spec sync
   - 4) Neural acceleration path
   - 5) HQ orchestration path

5. Add a **dual-lane architecture**:
   - Lane A: Technical optimization runtime
   - Lane B: Human/agent orchestration runtime
   - Join points explicitly shown (approval gates, deliverables, KB ingestion).

6. Add a **contract matrix sidebar**:
   - File contracts: `atomizer_spec.json`, `study.db`, `history.json`, `model_introspection.json`, report outputs.
   - Producer/consumer per contract.

7. Add a **risk/fragility overlay**:
   - Mark components known to be brittle (cross-OS sync, bridge/routing constraints, token/provider dependencies).

8. Add a **"planned vs decommissioned" marker** for legacy artifacts (old dashboard paths, old bridge assumptions, old protocol doc locations).

---

## Bottom Line

The map is impressive as a vision artifact, but currently it blends roadmap and reality too aggressively.  
As a living architectural blueprint, it needs a strict `Now vs Target` separation, tighter source anchoring, and fuller module coverage in the optimization engine/dashboard/agent runtime layers.