DOC15_Addendum_A_Audit_Synthesis_v1.3.md
Current Specs/DOC15/DOC15_Addendum_A_Audit_Synthesis_v1.3.md
ELNOR REPO READER TEXT MIRROR
Original path: Current Specs/DOC15/DOC15_Addendum_A_Audit_Synthesis_v1.3.md
Source repo: /Users/OpenClaw1/Elnor/Elnor Specs
Git branch: main
Git commit: dbaa25962edc11ab30e8d4ca1715f9ae5bf77331
Generated: 2026-06-09T01:23:58.539Z
---
# DOC 15 — Addendum A
# Audit Synthesis & Integration Placement Guide
## Companion to DOC15 (Cognitive Infrastructure Layer Specification)
**Version:** 1.3 (2026-03-04)
**Auditors:** Claude Code (Opus 4.6), Codex, Gemini
**Synthesized by:** Claude (Opus 4.6) for Will (ELNOR Principal Architect)
### What This Document Is
This is the integration placement guide for DOC15. It catalogs all 106 existing memory, context, and self-learning systems across the ELNOR codebase and spec corpus, maps each to a CIL module and migration action, identifies blockers, and provides the Phase 0 checklist. DOC15 references this document by system ID (e.g., "MemoryService wraps MEM-01 through MEM-09").
### Living Document Policy
This document must be updated when:
- Any spec it covers (DOC1–DOC14, ELNOR Core) changes in ways that affect memory, context, or learning systems
- New systems are added to the codebase
- CIL implementation reveals inaccuracies in the overlay placement map
### Reconciliation Log
| Date | Version | Change | Affected Sections |
|---|---|---|---|
| 2026-03-04 | 1.0 | Initial synthesis from three audits | All |
| 2026-03-04 | 1.1 | Added DOC14 v2+v3 mechanism-level mapping (§10), renamed to DOC15 Addendum A, added version tracking | §header, §10 (new) |
| 2026-03-04 | 1.2 | R2 reconciliation: Added P0-5/P0-6/P0-7 blockers, updated Phase 0 checklist, panels-first change | §2, §9 |
| 2026-03-04 | 1.3 | R3 reconciliation: Top-10 wrap-first rule adopted (§9 updated), feature flag simplification noted, Operation Compiler touchpoints added to §10, prompt lineage/review outcome signals added | §2, §9, §10 |
---
## §1 — Executive Summary
Three independent forensic audits were conducted across the ELNOR codebase and spec corpus on 2026-03-04. This document synthesizes their findings into a single integration placement guide that DOC15 must reference during implementation.
### What Was Found
| Metric | Claude Code | Codex | Gemini |
|---|---|---|---|
| Memory systems identified | 106 | 84 | 12 |
| Context assembly steps | 27 | 23 | 9 |
| Self-learning mechanisms | 30 | 20 | 7 |
| Functional domains | 19 | 18 | ~10 |
| Implementation: Built | 62 | 52 | N/A (spec-focused) |
| Implementation: Spec-only | 22 | 18 | Majority |
| Implementation: Partial | 6 | — | — |
| Single-writer violations | 4 | — | 2 (different set) |
Claude Code's audit is the master reference for system IDs, file paths, and line numbers. Codex confirms coverage with slightly less granularity. Gemini adds architectural insights about integration seams and risks that the code-level audits don't surface.
### The Five Critical Findings
1. **The system is far richer than DOC15 assumed.** 106 memory systems across 19 domains means CIL cannot "replace" existing memory — it must wrap, extend, and govern what's already there. The overlay placement map (§3) is the roadmap.
2. **Four single-writer violations exist in production code.** Q-backend writes directly to OpenClaw config, Q UI settings, stop requests (fallback), and test-runtime memory. CIL must not introduce a fifth.
3. **Schema coverage is dangerously uneven.** Core governance systems (standing orders, corrections, user profile, preferences, patterns, vocabulary) have **no Zod schemas** — they're untyped JSON. These are always-injected context items. CIL cannot wrap them safely without schemas first.
4. **Three context managers already compete before CIL arrives.** The EC Context Assembler, the OCM (Operations Context Manager from Running Brief v6), and OpenClaw's native MEMORY.md all try to manage context. CIL's ContextPlanner must be the arbiter, not a fourth competitor.
5. **The nightly job is deterministic and fast today.** All three existing nightly jobs (memory loop, panel aggregation, friction rollup) are pure JSON/JSONL processing with no LLM calls. CIL's replay and candidate generation phases will add LLM-dependent work to this pipeline. Budget gates are essential.
---
## §2 — P0 Blockers (Must Resolve Before Any CIL Code)
These four items gate Phase 0. No CIL scaffolding should be written until they are resolved.
### P0-1: Formalize Schemas for Untyped Governance Stores
**Affected systems:** MEM-02 (User Profile), MEM-03 (Preferences), MEM-04 (Patterns), MEM-05 (Vocabulary), MEM-10 (Standing Orders), MEM-11 (Corrections)
**Current state:** All six are untyped JSON objects read directly from disk. Standing orders and corrections are always injected into every context assembly — they are the highest-impact memory surfaces in the system. Yet they have no Zod schemas in the contracts package.
**Why this blocks CIL:** MemoryService cannot wrap these stores without knowing their shape. ContextPlanner cannot apply Authority Memory vs. Heuristic Memory precedence if it can't distinguish standing orders (Authority) from learned patterns (Heuristic) by schema type. The Profile Registry cannot seed from existing configs if those configs have no typed contract.
**Required action:** Create Zod schemas for all six stores in `packages/contracts/src/schemas.ts`. Migrate existing files to validate against these schemas. Add schema_version fields. This is a coding task, not an architectural decision — the shapes already exist in code, they just aren't formalized.
**Estimated effort:** 1–2 days for a coding agent.
### P0-2: Resolve LearningSignal Schema Collision
**Affected systems:** MEM-39 (DOC8 `DOC8LearningSignalSchema`), MEM-103 (DOC15 `LearningSignalSchema`)
**Current state:** DOC8 already has a built, typed learning signal schema with 6 event types (`friction_detected`, `prevented_friction`, `regression_triggered`, `canary_confirmed`, `canary_ineffective`, `health_anomaly`). DOC15 proposes a different `LearningSignalSchema` with different fields (`signal_id`, `profile_id`, `signal_type`, `source_type`, `payload`, `labels`).
**Why this blocks CIL:** Two competing signal schemas means two competing write paths. The LearningPipeline cannot wrap both without a clear merge or bridge strategy.
**Required action:** Define one of three strategies:
- **Merge:** Unify into a single schema that covers both DOC8 and DOC15 signal types. DOC8's existing signals become CIL signal types.
- **Bridge:** Keep DOC8's schema for friction-specific signals. CIL's schema is a superset that ingests DOC8 signals via a normalizing adapter.
- **Replace:** CIL's schema replaces DOC8's. Existing friction signals are migrated.
**Recommendation:** Bridge strategy. DOC8's friction engine is built and working. Don't break it. Add a normalizing adapter that converts `DOC8LearningSignalSchema` events into `LearningSignalSchema` events at ingestion time. Both schemas coexist; CIL reads through the bridge.
**Estimated effort:** 1 day for schema design, 2 days for adapter implementation.
### P0-3: Define CIL Storage Paths Without Semantic Duplication
**Affected systems:** All CIL storage under `ELNOR_MEMORY/system/cil/`
**Current state:** No path collision exists (confirmed by all three audits). The risk is semantic duplication — creating parallel stores that duplicate truth already living in existing paths.
**Why this blocks CIL:** If `knowledge.sqlite` becomes the place where "what the system has learned" canonically lives, it rivals DOC1's `memory_index.json`. If `profile_state.json` duplicates what `learning_controls.json` already governs, you have split truth.
**Required action:** For every CIL storage artifact, explicitly declare whether it is:
- **NEW** — no existing analog (e.g., `profiles/` directory, `replay snapshots`)
- **INDEX** — derived index over existing data (e.g., `knowledge.sqlite` as index over `memory_index.json` + learned heuristics)
- **EXTENSION** — new data attached to an existing artifact (e.g., profile_state extending learning_controls)
**The rule (from ChatGPT's review):** Canonical truth stays in append-only EC-owned files. SQLite is a derived index only. If SQLite is lost or corrupted, rebuild from canonical logs.
**Estimated effort:** 1 day for path design document.
### P0-4: Bootstrap Profile Registry from Existing Precursors
**Affected systems:** 7 existing profile-like config systems identified
**Current state (Claude Code audit, Q6):**
| Precursor | Path | What It Does | Maps To |
|---|---|---|---|
| Task Profiles (MEM-07) | `ELNOR_MEMORY/core/task_profiles.json` | Per-task-type execution configs | ProfileDefinitionSchema |
| Learning Controls (MEM-43) | `ELNOR_MEMORY/system/learning/learning_controls.json` | Auto-escalate, context cautions toggles | Profile policy fields |
| Freshness Policy (MEM-57) | `ELNOR_MEMORY/system/freshness/freshness_policy.json` | TTL, search, injection caps | ContextPlanner config |
| Source Tiers (MEM-58) | `ELNOR_MEMORY/system/freshness/source_tiers.json` | Host reliability ranking | ContextPlanner config |
| Model Registry (MEM-56) | `ELNOR_MEMORY/system/freshness/model_registry.json` | Per-model capabilities/costs | Profile model selection |
| Panel Taxonomy (MEM-69) | `ELNOR_MEMORY/system/panels/taxonomy.json` | Category gate behaviors | Profile learning policy |
| Agent Configs | `ELNOR_MEMORY/agents/*.json` | Per-agent behavior settings | Per-agent profile traits |
**Why this blocks CIL:** The Profile Registry should not be invented from scratch. These 7 systems already function as profiles. Phase 0 must seed the registry from these existing configs.
**Required action:** For each precursor, define the mapping to ProfileDefinitionSchema fields. Write a bootstrap script that generates the initial 11 profile JSON files. Note: Task profiles (MEM-07) is empty. Domain profiles have different shapes than CIL profiles. This is design work, not automated conversion.
**Estimated effort:** 2–3 days.
### P0-5: SQLite Dependency Resolution *(R2 new — from Claude Code red-team)*
**Current state:** The ELNOR codebase uses no SQLite anywhere. All storage is flat JSON/JSONL with in-memory caching.
**Why this blocks CIL:** DOC15 v1 specified `knowledge.sqlite` as the MemoryService query index. Introducing SQLite adds a native dependency (better-sqlite3 requires native compilation) or a WASM dependency (sql.js, slower).
**Resolution (adopted in R2):** Defer SQLite. Phase 0-1 uses an in-memory Map index built from `knowledge_nodes.jsonl` at boot. When knowledge node count exceeds 500 (likely Phase 2+), migrate to SQLite. No dependency needed for Phase 0.
**Estimated effort:** 0 days (deferred).
### P0-6: ContextFacts Builder Implementation *(R2 new — from Claude Code red-team)*
**Current state:** No `buildContextFacts()` function exists. No `DispatchInput` type exists. 8 of 17 ContextFacts fields are available from current dispatch inputs. 3 are partial. 6 require DOC12/DOC14 infrastructure that doesn't exist.
**Why this blocks CIL:** ContextFacts is the linchpin — ProfileRegistry resolves against it, ContextPlanner plans from it, caches key off its hash. If it can't be constructed, CIL can't activate.
**Required action:** Implement a minimal `buildContextFacts()` that populates available fields from current dispatch inputs. Phase 0 profiles must use only available fields in their matchers.
**Estimated effort:** 1-2 days.
### P0-7: Dispatch Orchestrator Interception Point *(R2 new — from Claude Code red-team)*
**Current state:** There is no single dispatch funnel. EC has multiple dispatch paths. Chat dispatch goes Q-backend → Gateway, bypassing EC entirely. The chat path (highest volume) cannot be intercepted by CIL without routing changes.
**Why this blocks Phase 1:** CIL's `executeDispatch()` must be wired into dispatch paths. But the most common path bypasses EC.
**Resolution (adopted in R2):** Phase 0-2: CIL applies to EC-routed dispatches only (panels, tasks, self-healing). Phase 3+: EC provides a context-planning RPC that Q-backend calls before chat dispatch.
**Required action:** Create `apps/ec-service/src/dispatch/orchestrator.ts` with the `executeDispatch()` stub. Wire into EC panel/task command handlers with feature flag guard.
**Estimated effort:** 2-3 days.
---
## §3 — Merged Overlay Placement Map
This is the canonical integration table. Claude Code system IDs (MEM-XX, C-XX, SLN/SLE/SLU-XX) are the master reference. Each row specifies exactly what CIL does to the system.
### Legend
- **WRAP** — CIL facade around existing code; no behavior change initially
- **EXTEND** — Add CIL features on top of existing code
- **REPLACE** — Existing code replaced by CIL module (rare, high-risk)
- **SEED** — Use existing data to populate CIL knowledge nodes
- **SCHEMA_FIRST** — Must formalize schema before any CIL work (P0 blocker)
- **NO_CHANGE** — CIL does not touch this system
- **NEW** — New CIL implementation, no existing analog
### 3.1 Memory Systems → CIL Module Mapping
| ID | System | Owner | Built? | CIL Module | Action | Phase | Risk |
|---|---|---|---|---|---|---|---|
| MEM-01 | Memory Index | DOC1 | Built | MemoryService | WRAP | 0 | Med |
| MEM-02 | User Profile | DOC1 | Built | MemoryService | SCHEMA_FIRST | 0 | **High** |
| MEM-03 | Preferences | DOC1 | Built | MemoryService | SCHEMA_FIRST | 0 | **High** |
| MEM-04 | Patterns | DOC1 | Built | MemoryService | SCHEMA_FIRST | 0 | **High** |
| MEM-05 | Vocabulary | DOC1 | Built | MemoryService | SCHEMA_FIRST | 0 | Med |
| MEM-06 | Smart Defaults | DOC1 | Built? | LearningPipeline | VERIFY_FIRST | 0 | Med |
| MEM-07 | Task Profiles | DOC1 | Built | MemoryService | SEED → Profiles | 1 | Med |
| MEM-08 | Task Templates | DOC1 | Built | MemoryService | WRAP | 1 | Low |
| MEM-09 | Domain Profiles | DOC1 | Built | MemoryService+ContextPlanner | EXTEND | 1 | Med |
| MEM-10 | Standing Orders | DOC1 | Built | **AuthorityMemory** | SCHEMA_FIRST | 0 | **High** |
| MEM-11 | Corrections | DOC1 | Built | **AuthorityMemory** | SCHEMA_FIRST | 0 | **High** |
| MEM-12 | Pending Rules | DOC1 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-13 | Pending Index | DOC1 | Built | LearningPipeline+MemoryService | WRAP | 0 | Low |
| MEM-14 | Memory Relations | DOC1 | Built | MemoryService+ContextPlanner | WRAP | 0 | Med |
| MEM-15 | Memory Conflicts | DOC1 | Built | MemoryService+LearningPipeline | WRAP | 0 | Low |
| MEM-16 | Memory Gaps | DOC1 | Built | LearningPipeline | WRAP | 0 | Low |
| MEM-17 | Memory Audit Trail | DOC1 | Built | MemoryService | WRAP | 0 | Low |
| MEM-18 | Running Brief | DOC1/v6 | Built | ContextPlanner | EXTEND | 1 | Med |
| MEM-19 | Handoff Briefs | DOC1 | Built | ContextPlanner | WRAP | 1 | Low |
| MEM-20 | Flush Artifacts | DOC1 | Built | ContextPlanner | WRAP | 1 | Low |
| MEM-21 | CRS Capsules | DOC1 | Partial | MemoryService+ContextPlanner | EXTEND | 2 | Med |
| MEM-22 | Memory Snapshots | DOC1 | Built | MemoryService | WRAP | 0 | Low |
| MEM-23 | Archived Memories | DOC1 | Built | MemoryService | WRAP | 0 | Low |
| MEM-24 | Context Assembly Log | DOC1 | Built | ContextPlanner | WRAP | 0 | Low |
| MEM-25 | Injection Log | DOC1 | Built | ContextPlanner | WRAP | 0 | Low |
| MEM-26 | Session Start Settings | DOC1 | Built | ContextPlanner | WRAP | 1 | Low |
| MEM-27 | Memory Resilience Settings | DOC1 | Built | MemoryService+LearningPipeline+ContextPlanner | EXTEND | 1 | Med |
| MEM-28 | Extraction Config | DOC1 | Built | LearningPipeline+MemoryService | WRAP | 1 | Low |
| MEM-29 | Extraction Log | DOC1 | Built | MemoryService | WRAP | 1 | Low |
| MEM-30 | Extraction Errors | DOC1 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-31 | Extraction Quality | DOC1 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-32–35 | DOC7 Bucket System | DOC7 | Spec | ContextPlanner | EXTEND | 2 | **High** |
| MEM-36 | Friction Events | DOC8 | Built | LearningPipeline | WRAP | 0 | Low |
| MEM-37 | Friction Actions | DOC8 | Built | LearningPipeline | WRAP | 0 | Low |
| MEM-38 | Friction State | DOC8 | Built | LearningPipeline | WRAP | 0 | Low |
| MEM-39 | Learning Signals (DOC8) | DOC8 | Built | LearningPipeline | BRIDGE | 0 | Med |
| MEM-40 | Regressions | DOC8 | Built | LearningPipeline | EXTEND | 2 | Med |
| MEM-41 | Predictions | DOC8 | Partial | LearningPipeline | EXTEND | 2 | Med |
| MEM-42 | System Health | DOC8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-43 | Learning Controls | DOC8 | Built | LearningPipeline | SEED → Profiles | 1 | Low |
| MEM-44 | Learning Rollup | DOC8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-45 | Learning Reflections | DOC8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-46 | Promotion Candidates | DOC8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-47 | Pending Learning | DOC8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-48 | Deferred Queue | DOC8 | Built | LearningPipeline | EXTEND | 1 | Low |
| MEM-49 | Learning Aggregates | Core | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-50 | Impact Events | DOC6/8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-51 | Impact Ledger | DOC6/8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-52 | Micro Feedback | DOC6/8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-53 | Self Reports | DOC6/8 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-54 | Autopilot Reports | DOC1/8 | Built | LearningPipeline+MemoryService | WRAP | 1 | Low |
| MEM-55 | Maintenance Journal | DOC1 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-56 | Model Registry | DOC2 | Built | ContextPlanner+MemoryService | SEED → Profiles | 0 | Low |
| MEM-57 | Freshness Policy | DOC2 | Built | ContextPlanner | SEED → Profiles | 0 | Low |
| MEM-58 | Source Tiers | DOC2 | Built | ContextPlanner | WRAP | 0 | Low |
| MEM-59 | Search Runs | DOC2 | Built | LearningPipeline+ContextPlanner | WRAP | 1 | Low |
| MEM-60 | Verified Facts | DOC2 | Built | MemoryService+ContextPlanner | WRAP | 1 | Low |
| MEM-61–68 | Panel System | DOC6 | Built | LearningPipeline+ContextPlanner | WRAP | 1 | Med |
| MEM-69 | Panel Taxonomy | DOC6 | Built | LearningPipeline | SEED → Profiles | 1 | Low |
| MEM-70 | Panel Leaderboards | DOC6 | Built | LearningPipeline | WRAP | 1 | Low |
| MEM-71–75 | DOC9 Repair System | DOC9 | Spec | LearningPipeline+MemoryService | EXTEND | 2 | **High** |
| MEM-76–77 | Route Hints/Blocklist | DOC10 | Spec | ContextPlanner | EXTEND | 2 | Med |
| MEM-78 | STOP State | DOC10 | Built | NO_CHANGE | — | — | Low |
| MEM-79 | Room Learning Policy | DOC12 | Spec | LearningPipeline | EXTEND | 2 | Med |
| MEM-80 | Cost Registry | DOC13 | Built | NO_CHANGE | — | — | Low |
| MEM-81 | Integration Report | DOC4 | Built | ContextPlanner (degraded) | WRAP | 1 | Low |
| MEM-82 | Capability Registry | DOC4 | Built | ContextPlanner | WRAP | 1 | Med |
| MEM-83–84 | OpenClaw Native | DOC11 | Built | **NEVER TOUCH** | — | — | — |
| MEM-85 | Scheduler State | DOC8 | Built | NO_CHANGE | — | — | Low |
| MEM-86 | Command Queue | Core | Built | NO_CHANGE (all CIL uses) | — | — | Low |
| MEM-88 | Workspace Bindings | Core | Built | ContextPlanner+MemoryService | WRAP | 0 | Low |
| MEM-90 | DocMeta Index | Core | Partial | ContextPlanner | WRAP | 1 | Med |
| MEM-94 | Findings Ledger | DOC14 | Spec | LearningPipeline | EXTEND | 2 | Med |
| MEM-95–100 | CANDOR Systems | DOC14 | Spec | ContextPlanner+LearningPipeline | EXTEND | 3 | **High** |
| MEM-101 | CIL Knowledge Nodes | DOC15 | Spec | MemoryService | NEW | 1 | Med |
| MEM-102 | CIL Profile Definitions | DOC15 | Spec | ProfileRegistry | NEW | 0 | Med |
| MEM-103 | CIL Learning Signals | DOC15 | Spec | LearningPipeline | NEW (via BRIDGE) | 0 | Med |
| MEM-106 | SOUL.md | Core | Partial | **NEVER MUTATE** | — | — | — |
### 3.2 Authority Memory Classification
Per ChatGPT's accepted refinement, memory systems must be classified as Authority or Heuristic. Based on the audit:
**Authority Memory (governs — never outranked by heuristic):**
- MEM-10: Standing Orders — always injected, user-created, priority-based
- MEM-11: Corrections — always injected, user-created, never-rules and factual overrides
- MEM-02: User Profile — always injected (should transition to Authority once schema formalized)
- MEM-03: Preferences — always injected
- MEM-106: SOUL.md — foundational personality, never mutated by CIL
**Heuristic Memory (suggests — can be overridden by Authority):**
- MEM-01: Memory Index entries (learned from conversations)
- MEM-04: Patterns (extracted behavioral patterns)
- MEM-05: Vocabulary (extracted terminology)
- MEM-07: Task Profiles (learned execution preferences)
- MEM-09: Domain Profiles (derived from usage)
- MEM-60: Verified Facts (evidence-backed but TTL-limited)
- MEM-101: CIL Knowledge Nodes (all learned heuristics)
**Precedence chain (from ChatGPT, adopted):**
1. OpenClaw native runtime semantics (MEM-83/84/106) — NEVER TOUCHED
2. SOUL.md (MEM-106)
3. Authority Memory: Standing Orders (MEM-10), Corrections (MEM-11), Never-Rules
4. Task/room/bootstrap state
5. Heuristic Memory: CIL knowledge nodes, learned patterns, model preferences
6. Recent summary chain / recent turns
---
## §4 — Single-Writer Violations & Remediation
Four violations identified by Claude Code. CIL must not introduce a fifth.
| # | Violation | Location | Severity | Remediation |
|---|---|---|---|---|
| 1 | Q-backend writes Q dashboard state directly | q-backend server.ts:6812,7827,8150,8835,8957,9206 | Medium | Accept as Q-local UX state. CIL ignores these paths. |
| 2 | Q-backend writes OpenClaw config/model files directly | q-backend server.ts:8161,9894,15148,16990,17537,17662 | **High** | Route through EC command queue. P1 fix. |
| 3 | Q-backend fallback writes stop request file | q-backend server.ts:19912 | Medium | Accept as emergency path. Document race condition. |
| 4 | Test-runtime memory fallback mutates memory_index directly on EC 503 | q-backend server.ts:10524 | **High** | Remove or gate behind explicit test-mode flag. P1 fix. |
**CIL rule:** All CIL module writes go through EC command queue. No exceptions. No "emergency fallback" writes.
---
## §5 — Context Assembly Pipeline Map
27 built steps + 4 spec-only steps, in execution order. This is where ContextPlanner must intercept.
### 5.1 Current Pipeline (What Exists Today)
```
USER MESSAGE ARRIVES
│
▼
C01: Chat Intake Normalization (q-backend:20058)
│
├──► C02: Session-Start Context Probe (ec:7987)
│ └─ Inject if should_inject=true, bounded by flush_token_budget
│
▼
C03: EC Context Card — PRIMARY ASSEMBLY (ec:6783)
│
├──► C04: Memory Scoring & Ranking (ec:6990-7119)
│ └─ Terms + tags + topic + recency + confidence + calibrated_confidence
│ + relation_boost + usage_signals + project_linkage
│
├──► C05: Progressive Summarization & Truncation (ec:6696)
│ └─ Iterative demotion then truncation waterfall
│
├──► C06: Injection Text Construction + Audit (ec:7222-7525)
│ └─ Section ordering: standing_orders → corrections → mistakes
│ → pending_rules → warm_results → warnings
│
▼
C07: Q Local Memory Fallback (q-backend:6068)
│ └─ ONLY fires when EC unavailable (503/timeout/offline)
│ Top-8 keyword match, core/trusted weighting
│
├──► C08: Freshness Planning & Verification (q-backend:20550)
│ └─ Deterministic route: must_search/should_search/no_search
│ injection_token_cap: 800-1200
│
├──► C09: Q Awareness Builder (q-backend: buildQAwarenessContext)
│
├──► C10: OpenClaw Awareness Builder (q-backend: buildOpenClawAwarenessContext)
│
▼
C11: Context Merge / Recompute (q-backend:20419)
│ └─ Combine: session-start + freshness + memory + Q-awareness
│ + settings-awareness + OpenClaw-awareness
│
├──► C12: Auto Memory-Gap Logging (q-backend:20627 → EC log_memory_gap)
│
├──► C13: Date/Time Runtime Short-Circuit (q-backend:20651)
│
▼
C14: Gateway Preflight & Model Ref Resolution (q-backend:20657)
│
▼
C15: Gateway Chat Dispatch (q-backend:20696)
│ └─ WebSocket → OpenClaw
│
├──► C16: Gateway Failure Classification & Degradation
│
├──► C17: Direct Model Route (Fallback — no gateway)
│
▼
POST-DISPATCH
│
├──► C18: Model Verification Synthesis
├──► C19: Cost Preflight + Postflight Guard
├──► C20: Gateway Usage Extraction Fallback
├──► C21: Chat History Persistence (Q-local write)
├──► C22: Async Extraction Trigger (→ EC /api/memory/extract)
└──► C23: Running Brief Update + Handoff Artifact
```
### 5.2 Where CIL ContextPlanner Intercepts
Based on all three audits and the dispatch ordering fix from Gemini's review:
```
USER MESSAGE ARRIVES
│
▼
C01: Chat Intake Normalization
│
▼
┌────────────────────────────────────────────┐
│ NEW: CIL PRE-DISPATCH STAGE │
│ │
│ 1. Resolve ContextFacts from intake │
│ 2. Resolve applicable profiles │
│ 3. Query MemoryService (knowledge nodes) │
│ 4. Run non-context pre-dispatch caps │
│ (guards, contamination checks) │
│ 5. Run ContextPlanner.plan() │
│ (consumes context-mutating caps │
│ internally, produces sealed plan) │
│ │
│ ContextPlanner DRIVES steps C03-C06 │
│ (replaces ad-hoc scoring with profile- │
│ governed, budget-sealed planning) │
└────────────────────────────────────────────┘
│
▼
C03-C06: EC Context Assembly (driven by ContextPlan)
│
C08: Freshness (driven by ContextPlan budget allocation)
│
C09-C10: Awareness builders (unchanged)
│
C11: Context Merge (ContextPlan manifest replaces string-concat)
│
C14-C15: Gateway Dispatch
│
▼
┌────────────────────────────────────────────┐
│ NEW: CIL POST-DISPATCH STAGE │
│ │
│ 1. Run post-dispatch caps │
│ (attention_gap_detection, etc.) │
│ 2. Emit learning signals (async, │
│ fire-and-forget to in-memory buffer) │
│ 3. Record profile activity │
│ 4. Register passive signal hooks │
│ (finding_exported, etc.) │
└────────────────────────────────────────────┘
│
▼
C18-C23: Existing post-dispatch (unchanged)
```
### 5.3 Spec-Only Pipeline Steps (Not Yet Implemented)
| Step | Owner | What It Adds | Phase |
|---|---|---|---|
| C24: DOC7 Bucket Injection | DOC7 | Full bucket-based context with materialization | 2 |
| C25: DOC12 Room Context Packet | DOC12 | Fresh room bootstrap with surface isolation | 2 |
| C26: Running Brief v6 Unified Pipeline | RB v6 | 5-layer injection with surface-scoped slots | 2 |
| C27: DOC14v3 Hierarchical Memory | DOC14 | 3-level pressure-based injection | 3 |
ContextPlanner must be designed to accommodate these four additions when they're implemented. The ContextPlan schema should have extension points for bucket directives, room bootstrap, surface slot allocation, and hierarchical level selection.
---
## §6 — Self-Learning Pipeline Map
### 6.1 The Three Learning Loops (from ChatGPT, adopted)
The audit confirms these three loops are already partially implemented but not explicitly separated:
**Loop 1: Operational Repair** (Goal: stop breaking)
- SLE03–SLE07: Friction event emitters (7 channels, 14 types, 3 severities)
- SLE04: Friction action recording (8 action types)
- SLN03: Nightly friction rollup → state → clusters → regressions
- SLS01: DOC9 friction-to-repair pipeline (spec-only)
- All deterministic. No LLM calls on hot path.
**Loop 2: Reviewer Quality** (Goal: improve review quality)
- SLE11: Panel impact/micro-feedback/self-report capture
- SLN04: Panel nightly aggregation → leaderboards
- SLS03: DOC14v3 finding judgment learning (spec-only)
- SLS04: DOC14v3 topology outcome learning (spec-only)
- NEW: CIL terminal-turn replay, shadow rollouts, LLM-as-judge
- Requires LLM calls (nightly only, budget-gated).
**Loop 3: Memory Governance** (Goal: keep memory sane)
- SLN02: Nightly memory loop (transitions, pruning, archive)
- SLE08: Memory gap detection
- SLE09: Conversation extraction
- SLU01–SLU04: User-initiated teach/promote/resolve/convert
- SLN05: Mistakes file ingestion
- NEW: CIL knowledge node promotion, retirement, contradiction detection
- Mostly deterministic. Knowledge promotion may use LLM for candidate generation.
### 6.2 Nightly Job Ordering (Current → CIL Extended)
```
NIGHTLY SCHEDULER (2 AM local, configurable)
│
▼
Phase 1: Memory Loop (SLN02) — EXISTING, NO CHANGE
│ └─ Maturity transitions, pruning/archive, deferred queue, autopilot report
│ Duration: seconds. No LLM calls.
│
▼
Phase 2: Panel Aggregation (SLN04) — EXISTING, NO CHANGE
│ └─ Leaderboards, failure mode rollup, team digest
│ Duration: seconds. No LLM calls.
│
▼
Phase 3: Friction Rollup (SLN03) — EXISTING, NO CHANGE
│ └─ State derivation, clusters, anomalies, regressions, canary lifecycle
│ Duration: seconds. No LLM calls.
│
▼
Phase 4: CIL Profile Maintenance — NEW
│ └─ Update profile maturity tiers, flag dormant profiles
│ Duration: sub-second. No LLM calls.
│
▼
Phase 5: CIL Knowledge Governance — NEW
│ └─ Promote validated signals → knowledge nodes (may use LLM for candidate gen)
│ Retire stale nodes, detect contradictions
│ Duration: seconds to low minutes. Budget-gated.
│
▼
Phase 6: CIL Replay & Candidates — NEW (budget-gated)
│ └─ Terminal-turn replay, LLM-as-judge evaluation
│ Max holdout rooms: 5/night. Max CPU seconds: 300. Max retries: 2.
│ Duration: minutes. LLM calls required. Most expensive phase.
│
▼
Phase 7: Compile-to-Preset Check — NEW (Phase 4+, deferred)
└─ Check if any winning strategies are stable enough to compile
into deterministic presets
```
---
## §7 — Key Architectural Constraints for DOC15
These constraints emerged from the audits and must be respected in the spec.
### 7.1 The Three Existing Context Managers
Gemini flagged this: before CIL arrives, ELNOR already has three systems trying to manage context:
1. **EC Context Assembler** (C03-C06) — the primary built pipeline
2. **OCM (Operations Context Manager)** from Running Brief v6 — surface-scoped summaries replacing the broken global running brief
3. **OpenClaw's native MEMORY.md** — Gateway's own session/memory state
**CIL's ContextPlanner is NOT a fourth context manager.** It is the arbiter that drives the first two while never touching the third. It produces a ContextPlan that C03-C06 execute. It respects OCM surface isolation. It never writes to OpenClaw's native state.
### 7.2 The OCM Surface Isolation Rule
From Grok's Running Brief remediation finding: the old global running brief is dead. Context summaries are now strictly isolated per UI surface (room vs. chat vs. panel). CIL's ContextPlanner must enforce this:
- Surface change is not history continuity
- Room bootstrap is not the Running Brief
- ContextPlanner must include `surface_kind` and `surface_id` in ContextFacts
- No cross-surface context bleeding, even if the same profile applies to both surfaces
### 7.3 The DOC3 Autonomy-First Override
Gemini flagged: DOC3 Patch R7 explicitly removes most human-in-the-loop approval gates in favor of "autonomy-first" defaults. DOC1 (ELNOR Core §14) mandates tiered consent. These contradict.
**CIL's LearningPipeline must respect the R7 override for operational capabilities** (document edits, tool execution, search) while maintaining approval gates for **memory promotion and profile changes** (which are not operational actions — they're governance actions). The distinction: doing work doesn't need approval; changing what the system remembers or how it behaves does.
### 7.4 The Cost System Firewall
DOC13 explicitly states: budget exhaustion must NOT trigger DOC8/DOC9 learning or repair. Cost events are not friction events. CIL must maintain this firewall. If a dispatch fails because of cost cap, that's a budget decision, not a quality signal. Don't let the LearningPipeline learn from it.
### 7.5 Schema Version Discipline
Claude Code found: `MemoryRecordSchema` is at version 4 with explicit version tracking. But 6 governance stores have no schema at all. DOC8's friction schemas are well-versioned. DOC15's proposed schemas have no version fields.
**Rule for DOC15:** Every CIL schema must include a `schema_version` field. Every CIL storage artifact must include the schema version in its header. Migration scripts must handle version upgrades.
### 7.6 The Monolithic File Risk
Both EC server.ts (21,725 lines) and Q-backend server.ts are monoliths. CIL modules must be separate files under `apps/ec-service/src/services/` — not additional functions in the monolith. Phase 0 scaffolding should create these files immediately, even if they're initially just re-exports of existing functions.
### 7.7 Existing Test Coverage
Claude Code found strong test coverage for: DOC1 memory resilience, freshness router/cache/executor, DOC8 friction schemas/engine/nightly rollup, DOC6 panel self-improvement, extraction pipeline.
Weak coverage for: cross-service failure modes, Q fallback paths, spec-only systems (DOC7/DOC9/DOC12/DOC14).
**CIL Phase 0 must add tests for:** profile resolution, ContextMatcher evaluation, signal bridge from DOC8 to CIL format. These are the new hot-path additions.
---
## §8 — Training Engine Data Requirements
This section catalogs what the Training Engine (DOC15 §8, Phase 5+) would need to read. The purpose is to ensure operational data capture is designed with future Training Engine consumption in mind.
### 8.1 Data Sources the Training Engine Would Consume
| Data Source | System IDs | Available Today? | Queryable? | Structured? |
|---|---|---|---|---|
| Room transcripts | MEM-61/62 (panel runs/turns) | Built (panels) / Spec (rooms) | Yes (JSONL) | Yes |
| Chat history | MEM-92 | Built | Yes (JSONL) | Partially (untyped) |
| Finding judgments | MEM-94 | Spec-only | Will be (JSONL) | Yes (schema defined) |
| Friction events | MEM-36 | Built | Yes (JSONL, cursor-based) | Yes (Zod schema) |
| Learning signals | MEM-39 | Built | Yes (JSONL) | Yes (Zod schema) |
| Model registry | MEM-56 | Built | Yes (JSON) | Yes (Zod schema) |
| Context assembly logs | MEM-24 | Built | Yes (JSONL) | Partially |
| Injection logs | MEM-25 | Built | Yes (JSONL) | Partially |
| Panel feedback | MEM-63 | Built | Yes (JSONL) | Yes (Zod schema) |
| Promotion candidates | MEM-46 | Built | Yes (JSONL) | Partially |
| Scratchpad archives | NEW (Phase 2) | Not yet | Will be | Will be |
| Memory conflicts | MEM-15 | Built | Yes (JSONL) | Yes (Zod schema) |
| Memory gaps | MEM-16 | Built | Yes (JSONL) | Yes (Zod schema) |
| Cost tracking | MEM-80 | Built | Yes (JSON) | Yes (Zod schema) |
| Repair sessions | MEM-71 | Spec-only | Will be (JSONL) | Yes (schema defined) |
| Profile state history | MEM-102 | Spec-only (DOC15) | Will be | Will be |
### 8.2 Data Gaps That Must Be Closed
1. **Chat history (MEM-92) is untyped JSONL.** Training Engine needs structured metadata: session ID, model used, agent ID, workspace, timestamp, token counts. Add a `ChatTurnSchema` before Phase 2.
2. **Context assembly logs (MEM-24) lack ContextFacts snapshots.** When CIL adds ContextFacts, ensure the assembly log captures the full ContextFacts object per turn. This lets the Training Engine correlate context decisions with outcomes.
3. **Room transcripts (DOC12/DOC14) are spec-only.** The Training Engine's most valuable corpus (multi-agent red-team sessions) doesn't exist in code yet. Room substrate must be built before Training Engine has anything to train on.
4. **Scratchpads don't exist yet.** Phase 2 adds them. Archive format must be queryable by process type, agent role, and time range.
---
## §9 — Phase 0 Checklist (Derived from Audit, Updated for R2)
Based on the P0 blockers (including R2 additions P0-5/P0-6/P0-7) and the overlay placement map:
### Week 1: Extraction + Schema Formalization (P0-1, P0-3, P0-5)
- [ ] **Extraction:** Create `apps/ec-service/src/services/` directory
- [ ] **Extraction:** Extract memory-read helpers from server.ts into `services/memory-helpers.ts`
- [ ] **Extraction:** Extract context-assembly helpers from server.ts into `services/context-helpers.ts`
- [ ] **Extraction:** Verify all existing tests pass after extraction
- [ ] Create `StandingOrderSchema` (Zod) from existing MEM-10 shape
- [ ] Create `CorrectionSchema` (Zod) from existing MEM-11 shape
- [ ] Create `UserProfileSchema` (Zod) from existing MEM-02 shape
- [ ] Create `PreferencesSchema` (Zod) from existing MEM-03 shape
- [ ] Create `PatternsSchema` (Zod) from existing MEM-04 shape
- [ ] Create `VocabularySchema` (Zod) from existing MEM-05 shape
- [ ] Add `schema_version` fields to all new schemas
- [ ] Migrate existing JSON files to validate against schemas
- [ ] Create 10 Phase 0 CIL schemas in `packages/contracts/src/cil-schemas.ts`
- [ ] Create `ELNOR_MEMORY/system/cil/` directory structure (P0-3)
- [ ] Register all CIL canonical paths in `packages/contracts/src/canonical.ts`
- [ ] Confirm no SQLite dependency needed for Phase 0 (P0-5 — in-memory index)
### Week 2: Modules + Profiles + Bridge (P0-2, P0-4, P0-6, P0-7)
- [ ] Implement `services/profile-registry.service.ts` — boot validation, evaluateMatcher(), specificity scoring
- [ ] Implement `TraitDefinitionSchema` and trait merge at boot
- [ ] Design and write 11 initial profile JSON files (Phase 0-available ContextFacts fields ONLY)
- [ ] Create `capability_registry.json` with boot validation
- [ ] Implement `buildContextFacts()` for EC-routed dispatches (P0-6)
- [ ] Design and implement DOC8 signal bridge adapter (P0-2) with cost firewall filter
- [ ] Create dispatch orchestrator stub in `apps/ec-service/src/dispatch/orchestrator.ts` (P0-7)
- [ ] Wire orchestrator stub into EC panel/task command handlers with feature flag guard
- [ ] Add feature flags: `cil_enabled`, `cil_profiles_active`, `cil_memory_active`, `cil_context_active`, `cil_learning_active`
### Week 3: Shadow Logging + Tests
- [ ] Wire ProfileRegistry.resolve() into EC dispatch path (shadow: log result, don't use it)
- [ ] Log profile resolution results for every dispatch
- [ ] Tests: evaluateMatcher() (all match types, undefined field handling, Phase 0 field restriction)
- [ ] Tests: Profile resolution (specificity, deny-by-default, PROFILE_RESOLUTION_AMBIGUOUS, dormancy skip)
- [ ] Tests: DOC8 signal bridge (normalization, cost firewall, lossless field preservation)
- [ ] Tests: Boot validation (trait conflicts, capability registry violations, protected path enforcement)
- [ ] Tests: Signal spool (sync append, async flush, startup reconciliation)
- [ ] Verify: Zero semantic behavior change — existing tests pass, shadow logs show plausible results
- [ ] Verify: `CIL_ACTIVE` remains false; shadow mode only
---
## §10 — DOC14/CANDOR Mechanism-Level Integration Map
The original audit (§3) compressed DOC14/CANDOR into 7 high-level rows (MEM-94 through MEM-100). This section breaks those out to mechanism granularity for DOC15 implementation.
### 10.1 DOC14 v2 Global Ports (§5) — Mechanisms Available to All of Q and EC
| Mechanism | DOC14 v2 Section | CANDOR Source | Storage Path | Schema | CIL Module | CIL Capability ID | Phase |
|---|---|---|---|---|---|---|---|
| Strength Sentinel | §5.1 | CANDOR §12B | N/A (compute-only) | N/A | ContextPlanner | `strength_sentinel` | 1 |
| Concept Registry (CRG v2) | §5.2 | CANDOR §2 | `ELNOR_MEMORY/system/context/buckets/concept_registries/<hash>.json` | `ConceptRegistryNodeSchema` | ContextPlanner + MemoryService | `concept_registry_build` | 1 |
| Attention Gap Detection | §5.3 | CANDOR §12B | Per-room compute | N/A | LearningPipeline | `attention_gap_detection` | 1 |
| Never-Compress Classes NC-1–NC-6 | §5.4 | CANDOR §22 | ContextPlan.never_compress[] | (Plan field) | ContextPlanner | `never_compress_enforcement` | 0 |
| Delta Digest + Decision Pack | §5.6 | CANDOR §7 | Panel output blocks | DOC6 schemas | (DOC6, not CIL) | N/A | 2 |
| Unpatchable Insights | §5.7 | CANDOR §7 | Panel output | DOC6 schemas | (DOC6, not CIL) | N/A | 2 |
| Evidence Gate | §5.8 | CANDOR §5 | Findings Ledger validation | `RoomFindingSchema` | LearningPipeline | `evidence_gate` | 0 |
### 10.2 DOC14 v3 Delta — New Mechanisms
| Mechanism | v3 Section | Storage Path | Schema | CIL Module | CIL Capability ID | Phase |
|---|---|---|---|---|---|---|
| review_target_kind field | §2 | ContextFacts + RedTeamPolicySchema | `ContextFactsSchema.review_target_kind` | ProfileRegistry (matcher input) | (ContextFacts field) | 1 |
| evidence_domain switching | §2 | ContextFacts | `ContextFactsSchema.evidence_domain` | ProfileRegistry (matcher input) | (ContextFacts field) | 1 |
| Hierarchical Memory (3-level) | §3 | DOC7 bucket field extension | `hierarchical_levels` on ContextBucketSchema | ContextPlanner | `hierarchical_compression` | 1 |
| Collaborative Ref Cache | §3 | `ELNOR_MEMORY/system/rooms/<room_id>/shared_ref_cache/` | Cache entry schema (v3 §3) | ContextPlanner | `collaborative_ref_cache` | 2 |
| Findings Promotion Rules | §4, Rules 1–3 | Findings Ledger + critique cache | `max_findings_per_turn_by_severity`, `why_this_matters` | LearningPipeline | `finding_promotion_gate` | 1 |
| Non-Promoted Critique Cache | §4, Rule 4 | `ELNOR_MEMORY/system/rooms/<room_id>/critique_cache.jsonl` | RoomFindingSchema + cache_reason | (Room substrate) | N/A | 1 |
| Superseded Observation GC | §4, Rule 5 | Findings Ledger | status: archived | (Room substrate) | N/A | 1 |
| Summary Chain Versioning | §5 | Room checkpoint | `room_summary_epoch`, `summary_freshness_hash` | (DOC12 room schema) | N/A | 1 |
| Lean Annotation Hard Limits | §6 | DOC11 transport | (DOC11 spec change) | N/A (DOC11 owns) | N/A | 1 |
| dissent_scope_framing | §6 | Lean annotation field | z.enum(["this_turn_only","round","room"]) | N/A (DOC11 owns) | N/A | 1 |
| Dissent Quality Judge (Layer 3) | §7 | `ELNOR_MEMORY/system/rooms/<room_id>/judge_log.jsonl` | Judge decision schema | LearningPipeline | `dissent_quality_judge` | 1 |
| Room Self-Monitoring (room_health) | §8 | Room state (room_health object) | `room_health` schema (v3 §8) | (EC compute-only) | N/A | 1 |
| Trace Lineage UI | §9 | N/A (Q frontend) | N/A | N/A (Q UI) | N/A | 1 |
| Workspace Isolation | §10 | `~/.openclaw/workspaces/room_<id>/` | RoomParticipantSchema extension | N/A (DOC12 launch) | N/A | 1 |
| Semantic Dedup (local embedding) | §11 | Finding record (embedding vector) | `semantic_dedup_enabled` on RedTeamPolicySchema | ContextPlanner | `semantic_dedup` | 2 |
| Finding Judgments Learning | §12 | `ELNOR_MEMORY/learning/finding_judgments.jsonl` | `FindingJudgmentSchema` | LearningPipeline | (Signal source) | 1 |
| Topology Outcome Learning | §13 | (Append-only signal) | `TopologyOutcomeSignalSchema` | LearningPipeline | (Signal source) | 2 |
| Context Coherence Check | §14 | Per-room compute + friction event | EC compute + `FrictionEventSchema` | LearningPipeline | `context_coherence_check` | 1 |
### 10.3 CANDOR v1.3 Mechanisms NOT Ported (Deferred or Superseded)
| Mechanism | CANDOR Section | Reason Not Ported |
|---|---|---|
| Director Protocol (§19) | Full orchestration protocol with role archetypes | Superseded by DOC12 room coordinator + CIL profiles |
| Separate CANDOR_MEMORY/ store | §22 | Superseded — EC single-writer, all storage under ELNOR_MEMORY/ |
| Three-tier memory (episodic/procedural/factual) | §10 | Replaced by CIL Authority/Heuristic split + knowledge nodes |
| Compositional prompt modules | §10 | Deferred — Training Engine (DOC15 §10) may revisit |
| Independent reviewer pipeline execution | §3 | Superseded by DOC12 multi-agent rooms |
| Adaptive Intelligence (§21) | Self-awareness, context budget forecasting | Partially covered by CIL overhead watchdog + room_health; full version deferred |
### 10.4 Systems That May Consolidate Under CIL
The audit identified potential overlaps across DOC14 and existing systems. These should be evaluated during Phase 2 for consolidation:
| System A | System B | Overlap | Consolidation Path |
|---|---|---|---|
| DOC14 Finding Judgments (MEM-94) | DOC8 Micro Feedback (MEM-52) | Both capture user quality signals | Unify under LearningPipeline signal taxonomy |
| DOC14 room_health | DOC8 system_health (MEM-42) | Both track quality degradation | Room-scoped vs. system-scoped; keep separate but share signal format |
| DOC14 Concept Registry (MEM-100) | DOC7 Bucket system-managed buckets (MEM-32) | Both track structured document content | Concept Registry becomes a DOC7 bucket type (already proposed in v2 §5.2) |
| DOC14 Topology Outcomes (MEM-99) | DOC8 Predictions (MEM-41) | Both predict/evaluate performance | Predictions are pre-task; topology outcomes are post-task. Complement, don't duplicate. |
---
*End of DOC 15 — Addendum A: Audit Synthesis & Integration Placement Guide v1.1*
*Reference this document by system ID in DOC15 and other specs.*