fix(repo): unify Drive paths, align docs with v2 architecture

- Remove duplicate SwarmDriveManager from drive.py; route get_default_drive
  and create_scoped_pool through swarm_manager (shared swarms/<id>/drive/)
- Fix __init__.py imports; dreaming defaults use get_default_drive_path()
- Rewrite SWARM.md, ARCHITECTURE.md, funnel docs, rules-and-patterns for
  Growth Merge + Memory Bank + framework skills
- Repair docs.json nav to existing pages; fix broken pool.* import examples
- Add create_scoped_pool regression test; ruff-clean scripts/examples

Author: PabloTheThinker

CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to this project are documented here. The product is
 
 ## Unreleased
 
+### Fixed — Repo-wide consistency audit (2026-06-18)
+
+- **Drive path unification (P0)** — removed duplicate `SwarmDriveManager` from `drive.py`; `get_default_drive()` and `create_scoped_pool()` now use `swarm_manager.get_or_create_pool()` → shared `swarms/<id>/drive/` (aligns MCP, memory bank, Experience Graph).
+- **`__init__.py`** — `SwarmDriveManager` / `get_swarm_drive_manager` imported from `swarm_manager` only.
+- **Dreaming defaults** — `ingestion.py` / `dilation.py` use `get_default_drive_path()` / `get_genomes_dir()` instead of legacy `~/.agentdrive/pool/`.
+- **Docs** — `ARCHITECTURE.md`, `CAPABILITY_FUNNEL.md`, `SWARM.md`, `FOR_AI_MODELS.md`, `rules-and-patterns.md`, `SETTINGS.md`, `ASSESSMENT.md`, `DEVELOPERS.md`, `HELP.md` updated for v2 shared Drive + full capability funnel.
+- **`docs/docs.json`** — navigation trimmed to existing pages; added Memory Bank, Capability Funnel, Skills Library groups.
+- **Tests** — `test_create_scoped_pool_uses_shared_swarm_drive` in `test_shared_swarm_drive.py`.
+- **Examples/scripts** — ruff clean across `scripts/` and `examples/`.
+
 ### Fixed — CI ruff lint + format (2026-06-18)
 
 - **ruff check** — removed unused imports (`json`, `list_projects`, `ingest_from_operation`, `ingest_observation_mirror`, `PathTraversalError`); fixed import ordering across cognition, memory, learning, and test modules.

DEVELOPERS.md

@@ -1,6 +1,6 @@
 # DEVELOPERS — One-Command Bring-Up
 
-This is the contributor's quick-start. For high-level orientation read [`VISION.md`](VISION.md), then [`ARCHITECTURE.md`](ARCHITECTURE.md). For the project's public framing read [`README.md`](README.md).
+This is the contributor's quick-start. For high-level orientation read [`VISION.md`](VISION.md), then [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) and [`docs/CAPABILITY_FUNNEL.md`](docs/CAPABILITY_FUNNEL.md). For the project's public framing read [`README.md`](README.md).
 
 ## Prerequisites
 

HELP.md

@@ -514,7 +514,7 @@ These are production optional advanced extensions. Core AgentDrive (three drives
 
 **Deep reference & mental models**:
 - `CONCEPTS.md` (the single best deep, agent-and-human-friendly explanation of the three-tier model, genomes, living loops, quarantine, reconciliation, and the new Lineage-enhanced components)
-- `ARCHITECTURE.md`
+- `docs/ARCHITECTURE.md`
 - `GENOME-SPEC.md`
 - `docs/AGENTDRIVE-V2-INHERITANCE.md`
 - `docs/SETTINGS.md`

docs/ARCHITECTURE.md

@@ -2,28 +2,47 @@
 
 **AgentDrive** is a local-first platform that gives AI agents structural, compounding memory — not just retrieval.
 
-For the single capability funnel (Observe → Graph → Skills → Genomes), see **`docs/CAPABILITY_FUNNEL.md`**.
+For the capability funnel, see **`docs/CAPABILITY_FUNNEL.md`**.
 
 For model onboarding rules, see **`docs/FOR_AI_MODELS.md`**.
 
 ---
 
-## Core subsystems (what stays)
+## Core subsystems
 
 | Layer | Location | Purpose |
 |-------|----------|---------|
 | **Drive engine** | `src/agentdrive/drive/` | Swarm-scoped persistence, ingest, query |
 | **Operations registry** | `src/agentdrive/operations/registry.py` | Canonical MCP/CLI surface + auto-learning |
 | **Experience Graph** | `src/agentdrive/evolution/experience_graph.py` | TypedEdges, cycles, fabric reasoning |
+| **Growth merge** | `src/agentdrive/learning/growth_merge.py` | Cross-surface pattern compounding |
+| **Memory Bank** | `src/agentdrive/memory/` | Deep AI databank (`memories.jsonl`, relations) |
+| **Framework skills** | `src/agentdrive/learning/framework_skills.py` | Route learned/fused playbooks per task |
 | **Multiverse cognition** | `src/agentdrive/cognition/` | Parallel timelines → governed collapse |
-| **Memory Bank** | `src/agentdrive/memory/` | Deep AI databank + graph memory triage |
-| **Skills + learning** | `src/agentdrive/skills/`, `learning/auto_absorb.py` | Distillation, inheritance, auto-absorb, fusion |
+| **Skills + learning** | `src/agentdrive/skills/`, `learning/auto_absorb.py` | Distillation, inheritance, fusion |
 | **Codebase mirrors** | `src/agentdrive/codebase/` | Pattern recognition + mimicry |
 | **Golden path** | `golden_path.py` | Install → doctor → MCP → verify |
-| **Event bus + sessions** | `events.py`, `session_events.py` | TUI/CLI observability |
 | **MCP adapter** | `adapters/mcp_server.py` | Any-model tool surface |
 
-Historical module names (`pool/`, `AgentDrivePool`) remain in code; product docs use **Drive**.
+**Naming:** Product surface is **Drive** (`AgentDrive`, `get_swarm_drive_path`). The YAML config key `pool:` and some method names (`get_pool_stats`) are historical — they refer to the same engine under `src/agentdrive/drive/`.
+
+---
+
+## Capability funnel
+
+```
+Observe / Decide
+       ↓
+Experience Graph
+       ↓
+Growth Merge
+       ↓
+Memory Bank
+       ↓
+Skills (learned + fused)
+       ↓
+Genomes / DNA
+```
 
 ---
 
@@ -32,15 +51,22 @@ Historical module names (`pool/`, `AgentDrivePool`) remain in code; product docs
 ```
 ~/.agentdrive/
 ├── config.yaml
-├── genomes/                    # Global genome registry
-├── swarms/<swarm_id>/
-│   ├── drive/                  # Graph + multiverse + meta_evolution
-│   │   └── memory_bank/        # Deep AI memory databank (memories.jsonl)
-│   └── <subagent_id>/pool/     # Isolated sub-agent DNA (optional)
-├── codebase-patterns/<project>/  # Mirror-neuron observations
-└── agents/<agent>/sessions/    # Chat session event logs
+├── genomes/                         # Global genome registry
+├── skills/                          # User + inherited learned skills
+├── codebase-patterns/<project>/     # Mirror-neuron observations
+├── learnings/                       # Operational JSONL logs
+└── swarms/<swarm_id>/
+    └── drive/                       # Shared per-swarm Drive (v2)
+        ├── ingest.jsonl
+        ├── genomes/
+        ├── memory_bank/             # memories.jsonl + relations.sqlite3
+        └── meta_evolution/          # Experience Graph + multiverse sessions
 ```
 
+**Swarm model (v2 / Milestone 2a):** All sub-agents in a swarm share one Drive at `swarms/<swarm_id>/drive/`. Sub-agents namespace writes via Genome author tagging (`sub:<id>`), not separate directories. MCP `create_scoped_pool()` and `SwarmDriveManager` use the same path.
+
+Legacy v1 trees (`swarms/<id>/<subagent>/pool/`) may exist on disk from older sessions; new provisioning always uses the shared `drive/` layout.
+
 ---
 
 ## Integration surfaces
@@ -50,23 +76,14 @@ Historical module names (`pool/`, `AgentDrivePool`) remain in code; product docs
 - **TUI** — default operator shell when no `--cli`
 - **Harness** — in-process outcome capture for adapters
 
-See `docs/MCP.md`, `docs/INTEGRATION.md`, `docs/GOLDEN_PATH.md`.
+See `docs/MCP.md`, `docs/INTEGRATION.md`, `docs/GOLDEN_PATH.md`, `docs/MEMORY_BANK.md`.
 
 ---
 
 ## Archived / legacy (do not extend)
 
 - `archive/ui-webpage-legacy-*` — superseded web templates
-- `archive/development-history/` — stabilization sprint reports, stale `BUILD_STATUS.md` / `MISSION_PLAN.md`
+- `archive/development-history/` — stabilization sprint reports
 - `src/agentdrive/backup/` — still referenced by tests; migrate before removal
 
----
-
-## Consolidation direction
-
-1. One capability funnel (documented in `CAPABILITY_FUNNEL.md`)
-2. Pool → Drive naming in user-facing docs (code rename is incremental)
-3. Split `cli.py` / `mcp_server.py` into focused modules
-4. Expand multiverse + graph test coverage
-
-See `CHANGELOG.md` Unreleased for recent work.
+See `CHANGELOG.md` for recent work.

docs/ASSESSMENT.md

@@ -7,7 +7,7 @@
 
 ## Executive summary
 
-AgentDrive crossed a meaningful product threshold: **a new operator can install, wire MCP, run the memory loop, and use a terminal that feels alive while the agent works.** The UX-PROPOSAL’s five patterns are all shipped at v1. The codebase is in strong shape — **618 tests collected, full suite green** — with multiverse, auto-learning, and codebase-mirror coverage added since the June 8 snapshot.
+AgentDrive crossed a meaningful product threshold: **a new operator can install, wire MCP, run the memory loop, and use a terminal that feels alive while the agent works.** The UX-PROPOSAL’s five patterns are all shipped at v1. The codebase is in strong shape — **655+ tests collected, full suite green** — with multiverse, auto-learning, and codebase-mirror coverage added since the June 8 snapshot.
 
 What you have now is not a demo shell. It is a **local-first agent memory platform** with a coherent operator surface (CLI + TUI + MCP), observable sessions, and a credible first-run story. The main gap is no longer “does the terminal feel broken?” but “which surface do we deepen next — terminal v2, web, or external adapters?”
 
@@ -67,7 +67,7 @@ Every chat session writes `~/.agentdrive/agents/<agent>/sessions/<id>/events.jso
 
 1. Coherent operator story — golden path + TUI gate + MCP + verify
 2. Event-bus architecture — lanes compose; session recording is automatic
-3. Test discipline — 618 tests, per-lane + multiverse + auto-learning suites
+3. Test discipline — 655+ tests, per-lane + multiverse + auto-learning + memory bank suites
 4. Unified dispatch — CLI, REPL, slash, skills share handlers
 5. Low TODO debt — ~3 TODOs across ~22k LOC
 

docs/CAPABILITY_FUNNEL.md

@@ -2,7 +2,7 @@
 
 **Single mental model for how intelligence compounds in AgentDrive.**
 
-Public product: **AgentDrive**. Internal engine modules still use historical names (`pool/`, `AgentDrivePool`) — treat **Drive** as the product-facing term and **Pool** as the persistence/query engine behind it.
+Public product: **AgentDrive**. Python module is `agentdrive.drive` (`AgentDrive` class). Some config keys and method names still say `pool` (e.g. YAML `pool:`, `get_pool_stats()`) — treat **Drive** as the product term.
 
 ---
 
@@ -124,10 +124,11 @@ Each swarm gets isolated storage:
 
 ```
 ~/.agentdrive/swarms/<swarm_id>/
-├── drive/          # Experience Graph + meta_evolution + multiverse sessions
-└── <subagent_id>/pool/   # Per-sub-agent DNA (when isolation_level=subagent)
+└── drive/          # Shared swarm Drive: graph, memory_bank, ingest, genomes
 ```
 
+Sub-agents share this Drive; writes are attributed via Genome author field (`sub:<id>`). Truly air-gapped children need an explicit custom `drive_path`.
+
 The funnel runs **per swarm**. Cross-swarm sharing is policy-gated (`docs/SETTINGS.md`).
 
 ---

docs/FOR_AI_MODELS.md

@@ -41,7 +41,11 @@ These rules turn stateless tool-calling into compounding intelligence.
 
 ## Capability funnel (how work compounds)
 
-All serious work flows one direction: **Observe/Decide → Experience Graph → Skills → Genomes/DNA**. Retrieval can jump levels; writes should land at the right tier. Full routing table: **`docs/CAPABILITY_FUNNEL.md`**. Architecture overview: **`docs/ARCHITECTURE.md`**.
+All serious work flows one direction:
+
+**Observe/Decide → Experience Graph → Growth Merge → Memory Bank → Skills → Genomes/DNA**
+
+Retrieval can jump levels; writes should land at the right tier. Full routing table: **`docs/CAPABILITY_FUNNEL.md`**. Architecture overview: **`docs/ARCHITECTURE.md`**.
 
 ---
 

docs/SETTINGS.md

@@ -86,7 +86,7 @@ agentdrive config edit
 ### Via Python API (agents or scripts)
 
 ```python
-from agentdrive.pool.settings import (
+from agentdrive.drive.settings import (
     get_pool_settings_manager,
     PoolSettings,
     get_effective_pool_settings,
@@ -187,7 +187,7 @@ pool:
 ## Viewing Effective Policy at Runtime
 
 ```python
-from agentdrive.pool.settings import get_effective_pool_settings
+from agentdrive.drive.settings import get_effective_drive_settings
 print(get_effective_pool_settings("my-swarm").to_dict())
 ```