claude-flow 3.10.1 → 3.10.4

package/.claude/worktrees/adr-120-impl/plugins/ruflo-agent/README.md

@@ -1,99 +0,0 @@
-# ruflo-agent
-
-Agent runtimes for ruflo — one mental model, two backends (a third planned):
-
-| Runtime | Tools | Runs on | Trust | Best for |
-|---|---|---|---|---|
-| **WASM** (`rvagent`) | `wasm_agent_*` / `wasm_gallery_*` | local WASM sandbox | sandboxed — no host fs/net | untrusted code; portable/replayable RVF containers; fast, free, offline |
-| **Managed** (Anthropic cloud) | `managed_agent_*` | Anthropic-managed container | cloud-isolated | long-running/async tasks; real container with packages + network; persistent filesystem + transcript across turns; no local setup |
-| **SDK** (planned — ADR-116) | `sdk_agent_*` | your process / your filesystem | full host trust | a real Claude agent loop (hooks, subagents, MCP, sessions, skills) on the local repo — the in-process version of `claude -p`; the killer combo is `mcpServers: { ruflo: { command: "npx", args: ["ruflo","mcp","start"] } }` (a local stdio MCP server → the agent gets ruflo's 314 tools, zero deployment) |
-
-`wasm_agent_*` is the **safe default** (sandboxed). `managed_agent_*` needs `ANTHROPIC_API_KEY` (or `CLAUDE_API_KEY`) + Claude Managed Agents beta access — every `managed_agent_*` tool degrades gracefully with a structured "use `wasm_agent_create` for a local no-key runtime" error when the key is absent.
-
-Design: [ADR-115](../../v3/docs/adr/ADR-115-managed-agents-rvagent-backend.md) (the cloud runtime + the planned SDK runtime); [ADR-070](../../v3/implementation/adrs/ADR-070-rvagent-wasm-completion.md) (the WASM runtime); plugin contract [`docs/adrs/0001-wasm-contract.md`](./docs/adrs/0001-wasm-contract.md).
-
-> Renamed from `ruflo-wasm` (it only covered the local WASM runtime). The `wasm_agent_*` / `wasm_gallery_*` tool *names* are unchanged.
-
-## Install
-
-```
-/plugin marketplace add ruvnet/ruflo
-/plugin install ruflo-agent@ruflo
-```
-
-## Commands
-
-- `/wasm` — list running WASM agents and browse the gallery (local runtime)
-- `/managed-agent` — list Managed Agent cloud sessions, check status, fetch a transcript, clean up (cloud runtime)
-
-## Skills
-
-- `wasm-agent` — create and manage sandboxed WASM agents (local)
-- `wasm-gallery` — browse and publish agents in the community gallery
-- `managed-agent` — run an Anthropic Claude Managed Agent (cloud) — create / prompt / status / events / list / terminate
-
-## MCP surface (16 tools)
-
-### WASM runtime — `v3/@claude-flow/cli/src/mcp-tools/wasm-agent-tools.ts` (10)
-
-| Tool | Purpose |
-|------|---------|
-| `wasm_agent_create` | Spin up a sandboxed WASM agent |
-| `wasm_agent_prompt` | Send a prompt to the agent |
-| `wasm_agent_tool` | Invoke a tool inside the sandbox |
-| `wasm_agent_list` | List active WASM agents |
-| `wasm_agent_terminate` | Stop a WASM agent |
-| `wasm_agent_files` | Read/write files in the sandbox |
-| `wasm_agent_export` | Export agent state (RVF container) |
-| `wasm_gallery_list` | Browse community-published WASM agents |
-| `wasm_gallery_search` | Search the gallery |
-| `wasm_gallery_create` | Publish a WASM agent to the gallery |
-
-### Managed (cloud) runtime — `v3/@claude-flow/cli/src/mcp-tools/managed-agent-tools.ts` (6, ADR-115)
-
-| Tool | Purpose | WASM counterpart |
-|------|---------|------------------|
-| `managed_agent_create` | Provision Agent + Environment + Session (`POST /v1/agents`, `/v1/environments`, `/v1/sessions`). Accepts `model` / `system` / `name` / `networking` / `packages` / `initScript` / `mcpServers` / `skills`. | `wasm_agent_create` |
-| `managed_agent_prompt` | Send a user turn (`POST /v1/sessions/{id}/events`), poll until the session goes idle (default 180 s, cap 600 s) → `{finished, status, stopReason, assistantText, toolUses[], eventCount}` | `wasm_agent_prompt` |
-| `managed_agent_status` | Session lifecycle state (idle/running/error, title, last error) | — |
-| `managed_agent_events` | Full server-persisted event log + a summary (the transcript/artifact view) | `wasm_agent_files` |
-| `managed_agent_list` | List Managed Agent sessions on the org (id, status, title) — see which are still billing | `wasm_agent_list` |
-| `managed_agent_terminate` | `DELETE /v1/sessions/{id}` (± the environment) — **always call when done**; a cloud session bills container time + tokens until deleted | `wasm_agent_terminate` |
-
-> Beta API (`anthropic-beta: managed-agents-2026-04-01`); `multiagent` / `define-outcomes` on the agent config are research preview. `mcpServers` for a cloud agent must point at a **publicly reachable** URL — a local `ruflo mcp start` is not reachable from Anthropic's cloud (deploy/tunnel an HTTP ruflo MCP server first). Managed sessions cost LM tokens + container time and are rate-limited per org.
-
-## Compatibility & degradation
-
-- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
-- **WASM runtime:** built on `@ruvector/rvagent-wasm` + `@ruvector/ruvllm-wasm` (declared in `@claude-flow/cli`'s `optionalDependencies` per [ADR-070](../../v3/implementation/adrs/ADR-070-rvagent-wasm-completion.md)). Without those packages, the `wasm_agent_*` tools fall through to graceful-degradation no-ops.
-- **Managed runtime:** plain `fetch` against the Managed Agents REST API — no extra SDK dependency. Without `ANTHROPIC_API_KEY` / `CLAUDE_API_KEY`, every `managed_agent_*` tool returns a structured error pointing at the `wasm_agent_*` fallback (the CLI/MCP server stays up).
-- **Verification:** `bash plugins/ruflo-agent/scripts/smoke.sh` is the contract (12 structural checks). CI: `.github/workflows/ruflo-agent-smoke.yml`. Behavioral guard for the cloud tools: `v3/@claude-flow/cli/__tests__/managed-agent-tools.test.ts` (no-network).
-
-## Sandbox / trust
-
-WASM agents run with **no host filesystem access** by default; `wasm_agent_files` exposes a sandboxed virtual filesystem only. Managed agents run in Anthropic's cloud container (isolated from your machine). The planned SDK runtime would run in *your* process with full host trust — which is why `wasm_agent_*` stays the default and the SDK runtime, when built, will be opt-in.
-
-For prompt-injection defense on output flowing back to the host LLM, the [ruflo-aidefence 3-gate pattern](../ruflo-aidefence/docs/adrs/0001-aidefence-contract.md) applies.
-
-## Namespace coordination
-
-This plugin owns the `wasm-gallery` AgentDB namespace (kebab-case, per [ruflo-agentdb ADR-0001 §"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed. `wasm-gallery` indexes published WASM agents (manifest, version, signature, download count); accessed via `memory_*` (namespace-routed).
-
-## Verification
-
-```bash
-bash plugins/ruflo-agent/scripts/smoke.sh
-# Expected: "12 passed, 0 failed"
-```
-
-## Architecture Decisions
-
-- [`ADR-0001` — ruflo-agent plugin contract](./docs/adrs/0001-wasm-contract.md) (WASM runtime: 10-tool MCP surface, ADR-070 integration, sandbox isolation, smoke as contract)
-- [`ADR-115`](../../v3/docs/adr/ADR-115-managed-agents-rvagent-backend.md) — Claude Managed Agents as the cloud runtime (+ the planned SDK runtime, ADR-116)
-
-## Related Plugins
-
-- `ruflo-agentdb` — namespace convention owner
-- `ruflo-aidefence` — 3-gate pattern applies to agent output flowing back to the host LLM
-- `ruflo-ruvector` — the ruvector substrate that ships `@ruvector/rvagent-wasm`
-- `ruflo-cost-tracker` — record completed Managed Agent sessions (LM tokens + container time)

package/.claude/worktrees/adr-120-impl/plugins/ruflo-agent/scripts/smoke.sh

@@ -1,104 +0,0 @@
-#!/usr/bin/env bash
-set -u
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-PASS=0
-FAIL=0
-step() { printf "→ %s ... " "$1"; }
-ok()   { printf "PASS\n"; PASS=$((PASS+1)); }
-bad()  { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-
-step "1. plugin.json is ruflo-agent 0.2.0 with both-runtime keywords"
-P="$ROOT/.claude-plugin/plugin.json"
-v=$(grep -E '"version"' "$P" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-n=$(grep -E '"name"' "$P" | grep -oE 'ruflo-agent' | head -1)
-if [[ "$v" != "0.2.0" ]]; then bad "expected version 0.2.0, got '$v'";
-elif [[ "$n" != "ruflo-agent" ]]; then bad "expected name ruflo-agent";
-else
-  miss=""
-  # local WASM runtime (rvagent) + cloud runtime (managed-agents) keywords
-  for k in mcp rvagent-wasm ruvllm-wasm managed-agents anthropic; do
-    grep -q "\"$k\"" "$P" || miss="$miss $k"
-  done
-  [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
-fi
-
-step "2. both skills + agent + command present with valid frontmatter"
-miss=""
-for s in wasm-agent wasm-gallery; do
-  f="$ROOT/skills/$s/SKILL.md"
-  [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
-  for k in 'name:' 'description:'; do
-    grep -q "^$k" "$f" || miss="$miss $s-no-$k"
-  done
-done
-[[ -f "$ROOT/agents/wasm-specialist.md" ]] || miss="$miss missing-agent"
-[[ -f "$ROOT/commands/wasm.md" ]] || miss="$miss missing-command"
-[[ -z "$miss" ]] && ok || bad "$miss"
-
-step "3. all 10 wasm_* MCP tools referenced"
-miss=""
-for t in wasm_agent_create wasm_agent_prompt wasm_agent_tool wasm_agent_list wasm_agent_terminate wasm_agent_files wasm_agent_export wasm_gallery_list wasm_gallery_search wasm_gallery_create; do
-  grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
-done
-[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
-
-step "4. README pins @claude-flow/cli to v3.6"
-grep -qE "@claude-flow/cli.*v3\.6|v3\.6.*claude-flow/cli" "$ROOT/README.md" \
-  && ok || bad "v3.6 pin missing"
-
-step "5. README defers to ruflo-agentdb namespace convention"
-grep -q "ruflo-agentdb" "$ROOT/README.md" \
-  && grep -q "Namespace convention" "$ROOT/README.md" \
-  && ok || bad "namespace coordination block incomplete"
-
-step "6. wasm-gallery namespace claimed"
-grep -q "wasm-gallery" "$ROOT/README.md" \
-  && ok || bad "wasm-gallery namespace not claimed"
-
-step "7. ADR-070 cross-reference present (rvagent-wasm + ruvllm-wasm integration)"
-F="$ROOT/README.md"
-miss=""
-grep -q "ADR-070" "$F" || miss="$miss adr-ref"
-grep -q "rvagent-wasm" "$F" || miss="$miss rvagent-wasm"
-grep -q "ruvllm-wasm" "$F" || miss="$miss ruvllm-wasm"
-grep -qE "optionalDependencies|graceful-degradation" "$F" || miss="$miss integration-detail"
-[[ -z "$miss" ]] && ok || bad "$miss"
-
-step "8. sandbox isolation documented"
-F="$ROOT/README.md"
-grep -q "Sandbox isolation\|sandbox isolation" "$F" \
-  && grep -qE "no host filesystem|virtual filesystem" "$F" \
-  && ok || bad "sandbox isolation guarantee not documented"
-
-step "9. AIDefence 3-gate cross-reference (sandbox → host LLM defense)"
-F="$ROOT/README.md"
-grep -q "ruflo-aidefence" "$F" \
-  && grep -qE "3-gate|3 gates" "$F" \
-  && ok || bad "AIDefence 3-gate cross-reference missing"
-
-step "10. ADR-0001 exists with status Accepted"
-ADR="$ROOT/docs/adrs/0001-wasm-contract.md"
-[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Accepted" "$ADR" \
-  && ok || bad "ADR missing or status != Accepted"
-
-step "11. no wildcard tool grants in skills"
-bad_skills=""
-for f in "$ROOT"/skills/*/SKILL.md; do
-  grep -q '^allowed-tools:[[:space:]]*\*' "$f" && bad_skills="$bad_skills $(basename $(dirname "$f"))"
-done
-[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
-
-step "12. managed-agent (cloud runtime) skill + command + all 6 managed_agent_* tools referenced (ADR-115)"
-miss=""
-[[ -f "$ROOT/skills/managed-agent/SKILL.md" ]] || miss="$miss missing-skill"
-[[ -f "$ROOT/commands/managed-agent.md" ]] || miss="$miss missing-command"
-for t in managed_agent_create managed_agent_prompt managed_agent_status managed_agent_events managed_agent_list managed_agent_terminate; do
-  grep -rq "$t" "$ROOT/skills" "$ROOT/commands" || miss="$miss no-ref-$t"
-done
-# the cloud-runtime skill must keep an explicit allowed-tools list (no wildcard) and offer the wasm fallback
-grep -q '^allowed-tools:[[:space:]]*\*' "$ROOT/skills/managed-agent/SKILL.md" 2>/dev/null && miss="$miss wildcard"
-grep -q 'wasm_agent_create' "$ROOT/skills/managed-agent/SKILL.md" 2>/dev/null || miss="$miss no-wasm-fallback-ref"
-[[ -z "$miss" ]] && ok || bad "$miss"
-
-printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
-[[ $FAIL -eq 0 ]] || exit 1

package/.claude/worktrees/adr-120-impl/plugins/ruflo-agentdb/.claude-plugin/plugin.json

@@ -1,24 +0,0 @@
-{
-  "name": "ruflo-agentdb",
-  "description": "Substrate plugin for Ruflo memory: AgentDB controller bridge (15 agentdb_* MCP tools), RuVector ONNX embeddings (10 embeddings_* tools incl. RaBitQ 32x quantization), and WASM HNSW pattern router (3 ruvllm_hnsw_* tools)",
-  "version": "0.3.0",
-  "author": {
-    "name": "ruvnet",
-    "url": "https://github.com/ruvnet"
-  },
-  "homepage": "https://github.com/ruvnet/ruflo",
-  "license": "MIT",
-  "keywords": [
-    "ruflo",
-    "agentdb",
-    "ruvector",
-    "hnsw",
-    "embeddings",
-    "vector-search",
-    "rabitq",
-    "quantization",
-    "namespace-convention",
-    "controller-bridge",
-    "mcp"
-  ]
-}

package/.claude/worktrees/adr-120-impl/plugins/ruflo-agentdb/README.md

@@ -1,221 +0,0 @@
-# ruflo-agentdb
-
-The substrate plugin for Ruflo memory. Wraps three CLI MCP families — `agentdb_*` (controller bridge, 15 tools), `embeddings_*` (RuVector ONNX engine, 10 tools), and `ruvllm_hnsw_*` (WASM-backed pattern router, 3 tools) — into discoverable skills and commands. Other plugins (`ruflo-browser`, `ruflo-rag-memory`, `ruflo-intelligence`) compose this substrate; this plugin owns the namespace convention and the smoke contract for the substrate as a whole.
-
-> **Status:** ADR-0001 implemented. Plugin v0.3.0 targets `@claude-flow/cli` v3.6.x with bundled `agentdb@^3.0.0-alpha.11`. The smoke contract (10 checks) is the verification mechanism — see [docs/adrs/0001-agentdb-optimization.md](./docs/adrs/0001-agentdb-optimization.md).
-
-## Install
-
-```
-/plugin marketplace add ruvnet/ruflo
-/plugin install ruflo-agentdb@ruflo
-```
-
-## Compatibility
-
-- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor. Patch bumps within v3.6 are expected to be no-op.
-- **AgentDB:** the CLI bundles `agentdb@^3.0.0-alpha.11`. The plugin does **not** pin the npm package — internals (alpha.11 → alpha.12 etc.) are not the plugin's contract.
-- **Verification:** the bundled smoke script is the source of truth (`bash plugins/ruflo-agentdb/scripts/smoke.sh`). If smoke passes against your CLI version, the plugin's contract holds.
-
-## Features
-
-- **Controller bridge**: 15 `agentdb_*` MCP tools (hierarchical store/recall, semantic routing, pattern store/search, causal edges, context synthesis, batch ops, consolidation, feedback, sessions).
-- **RuVector embeddings**: 10 `embeddings_*` MCP tools — 384-dim ONNX (all-MiniLM-L6-v2), HNSW search, hyperbolic (Poincare), neural substrate, and **RaBitQ 1-bit quantization (32× memory reduction)**.
-- **HNSW pattern router**: 3 `ruvllm_hnsw_*` tools (WASM-backed, ≤11 high-priority patterns — distinct from the large-scale embeddings HNSW path).
-- **Causal knowledge graphs**: `agentdb_causal-edge` (graph-node backend with bridge fallback per ADR-087).
-
-## Controllers (real registry, grouped by INIT_LEVELS)
-
-The "controller count" reported anywhere in this plugin is **whatever the runtime tool reports**. The canonical list of names is the `ControllerName` union at `v3/@claude-flow/memory/src/controller-registry.ts:34-73` (29 names across 6 init levels). Inspect at runtime:
-
-```bash
-mcp tool call agentdb_controllers --json
-```
-
-Initialization order per ADR-053 (`controller-registry.ts:160-174`):
-
-| Level | Controllers | Role |
-|------:|-------------|------|
-| 0 | _(foundation, pre-existing)_ | Bootstrap |
-| 1 | `reasoningBank`, `hierarchicalMemory`, `learningBridge`, `hybridSearch`, `tieredCache` | Core intelligence |
-| 2 | `memoryGraph`, `agentMemoryScope`, `vectorBackend`, `mutationGuard`, `gnnService` | Graph + security |
-| 3 | `skills`, `explainableRecall`, `reflexion`, `attestationLog`, `batchOperations`, `memoryConsolidation` | Specialization |
-| 4 | `causalGraph`, `nightlyLearner`, `learningSystem`, `semanticRouter` | Causal + routing |
-| 5 | `graphTransformer`, `sonaTrajectory`, `contextSynthesizer`, `rvfOptimizer`, `mmrDiversityRanker`, `guardedVectorBackend` | Advanced services |
-| 6 | `federatedSession`, `graphAdapter` | Session management |
-
-`graphAdapter` is currently disabled pending an external graph-DB connection (tracked in ADR-095). Other Level-2/3 security controllers (`mutationGuard`, `attestationLog`, `gnnService`, `rvfOptimizer`, `guardedVectorBackend`) were activated by ADR-095 G7 in ruflo 3.6.23+.
-
-## G7 controllers (activated by ADR-095)
-
-[ADR-095](../../v3/docs/adr/ADR-095-architectural-gaps-from-april-audit.md) closed five previously-disabled AgentDB controllers:
-
-| Controller | Role | Source |
-|---|---|---|
-| `gnnService` | Graph Neural Network embeddings + relational scoring over the AgentDB causal graph. No-arg construction. | `agentdb/dist/src/services/GNNService.js` |
-| `rvfOptimizer` | RuVector format compaction — quantizes + dedupes vector blocks before persistence. | `agentdb/dist/src/optimizations/RVFOptimizer.js` |
-| `mutationGuard` | WASM-backed proof generation for state mutations (ADR-060). | `agentdb/dist/src/security/MutationGuard.js` |
-| `attestationLog` | Hash-chained audit log of mutations. Backed by a dedicated `.swarm/attestation.db`. | `agentdb/dist/src/security/AttestationLog.js` |
-| `GuardedVectorBackend` | Wraps the existing vectorBackend with `mutationGuard` + `attestationLog`. | `agentdb/dist/src/backends/ruvector/GuardedVectorBackend.js` |
-
-## Commands
-
-- `/agentdb` — AgentDB health, controller status, session management
-- `/embeddings` — RuVector embedding engine status and operations
-
-## Skills
-
-- `agentdb-query` — Query AgentDB with semantic routing and hierarchical recall
-- `vector-search` — HNSW vector search + RaBitQ quantization + 3 tuning profiles
-
-## Namespace convention
-
-This plugin owns the namespace convention that downstream plugins consume. Following it keeps cross-plugin search discoverable and avoids accidental key collisions in the bridge.
-
-### Naming
-
-`<plugin-stem>-<intent>` in kebab-case. Examples already in the wild:
-
-| Plugin | Namespaces |
-|---|---|
-| `ruflo-browser` | `browser-sessions`, `browser-selectors`, `browser-templates`, `browser-cookies` |
-| `ruflo-rag-memory` | (uses bridge target `claude-memories`) |
-| `ruflo-intelligence` | (uses fallback target `pattern`) |
-
-### Reserved namespaces (do NOT shadow)
-
-| Namespace | Owned by | Source |
-|---|---|---|
-| `pattern` | ReasoningBank fallback writes here | `agentdb-tools.ts:144` |
-| `claude-memories` | Claude Code auto-memory bridge target | bridge |
-| `default` | `memory_store` default | `memory-tools.ts` |
-
-### Where namespace strings actually apply
-
-Namespace is **not** a universal parameter. Read the routing carefully:
-
-- `memory_*` and `embeddings_search` route by namespace — pass it.
-- `agentdb_hierarchical-*` routes by `tier` (`working|episodic|semantic`) — namespace argument is ignored.
-- `agentdb_pattern-*` routes through the ReasoningBank controller — namespace argument is ignored.
-- `agentdb_causal-edge` routes through the causal graph — namespace argument is ignored.
-
-Don't pass `namespace: 'browser-cookies'` to `agentdb_pattern-store` and expect filtering. It will be silently dropped.
-
-### GC posture
-
-This plugin **does not** GC namespaces. Consumer plugins that want lifecycle (e.g., `browser-sessions` after a `purge`) own their own deletion via `memory_delete` + `agentdb_consolidate`. If you need cleanup, schedule it.
-
-### Naming guardrails
-
-A namespace SHOULD NOT contain `:` (collides with key-internal delimiters used in the bridge), MUST be ≤200 chars, and MUST pass `validateIdentifier` (the same validator already used in `agentdb-tools.ts:122`).
-
-## How Claude Code populates AgentDB
-
-The `claude-memories` reserved namespace is filled by Claude Code's own auto-memory bridge, not by direct user calls. Two mechanisms:
-
-| Mechanism | Trigger | What it writes |
-|---|---|---|
-| `memory_import_claude` MCP tool | Manual or hook-driven | Reads `~/.claude/projects/*/memory/*.md`, parses YAML frontmatter, splits sections, stores with 384-dim embeddings. `allProjects: true` imports from ALL Claude projects. |
-| `.claude/helpers/auto-memory-hook.mjs` | `SessionStart` (import) and `SessionEnd` (sync) — wired in `.claude/settings.json` | `import` → calls into the bridge for the current project; `sync` → flows AgentDB insights back to `~/.claude/projects/*/memory/MEMORY.md` |
-
-To inspect or refresh:
-
-```bash
-# What's in the bridge right now?
-mcp tool call memory_bridge_status --json
-
-# Force a re-import from Claude Code's project memory
-mcp tool call memory_import_claude --json -- '{"allProjects": true}'
-
-# Cross-namespace search across claude-memories + auto-memory + patterns + tasks + feedback
-mcp tool call memory_search_unified --json -- '{"query": "your query"}'
-```
-
-`memory_search_unified` defaults to searching `['default', 'claude-memories', 'auto-memory', 'patterns', 'tasks', 'feedback']` — these are the namespaces the bridge actually populates. The `default` namespace is the catch-all; `auto-memory` is distinct from `claude-memories` (auto-memory holds bridge-internal cache, claude-memories holds parsed `*.md` sections).
-
-> **Pluralization gotcha:** the ReasoningBank fallback writes to `pattern` (singular). Other hooks (`hooks pretrain`, neural training paths) write to `patterns` (plural). They are different namespaces. When in doubt, `memory_list --namespace pattern` and `memory_list --namespace patterns` will tell you which one your data is in. Don't refactor your downstream code to "fix" the pluralization until you've confirmed which namespace was actually written.
-
-## Hook integration convention
-
-Several Claude Code hooks fire writes into AgentDB. Consumer plugins should know which namespaces accumulate state automatically vs. by explicit call, so they don't rebuild what the hook system already provides.
-
-| Hook | Tool invoked | Target namespace | Notes |
-|------|--------------|------------------|-------|
-| `SessionStart` | `memory_import_claude` (via auto-memory-hook.mjs) | `claude-memories` | Imports `~/.claude/projects/*/memory/*.md` into AgentDB on every session start |
-| `SessionEnd` | `auto-memory-hook.mjs sync` | bridge → `MEMORY.md` | Flows AgentDB insights back to Claude Code's MEMORY.md |
-| `post-task --train-neural` | `agentdb_pattern-store` (ReasoningBank) | `pattern` (with `memory-store-fallback` if registry unavailable) | Stores task-completion patterns for SONA distillation |
-| `pretrain` (one-shot) | `memory_store` | `patterns` (plural) | Bootstrap learning corpus |
-| `trajectory-begin/step/end` (ruvector hooks) | ruvector substrate (separate plugin) | sona/agentdb namespaces handled by `ruflo-ruvector` | See `plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md` |
-
-Implication for consumer plugins:
-
-- **Don't double-write.** If you're already calling `hooks post-task --train-neural`, you don't also need to manually `memory_store --namespace pattern`. Pick one path.
-- **Don't refresh `claude-memories` yourself.** It auto-imports on every SessionStart. Manual `memory_import_claude` is for force-refresh, not steady-state.
-- **Surface fallback responses.** When `controller: 'memory-store-fallback'` comes back from `agentdb_pattern-store`, the data still landed — see "Pattern-store fallback" below.
-
-## Operational fallbacks
-
-Three fallbacks exist in the bridge code; consumers should branch on them rather than treat them as soft failures.
-
-### Pattern-store fallback (ADR-093 F4)
-
-When the ReasoningBank controller registry returns null, `agentdb_pattern-store` writes through to `memory_store` and returns:
-
-```json
-{
-  "success": true,
-  "patternId": "pattern-...",
-  "controller": "memory-store-fallback",
-  "note": "ReasoningBank controller registry unavailable. Pattern persisted via memory_store."
-}
-```
-
-A `controller: 'memory-store-fallback'` response is a pattern that **was persisted** — not an error. Source: `agentdb-tools.ts:138-161`.
-
-### Causal-edge graph-node backend (ADR-087)
-
-`agentdb_causal-edge` tries the native `@ruvector/graph-node` backend first; on failure, falls back to the bridge. The response includes `_graphNodeBackend: true` when the native backend handled the call. Source: `agentdb-tools.ts:267-290`.
-
-### Bridge unavailable
-
-When `bridgeHealthCheck()` returns null (the `@claude-flow/memory` package is not installed or `controller-registry.ts` is missing), every `agentdb_*` handler returns:
-
-```json
-{
-  "success": false,
-  "error": "AgentDB bridge not available — @claude-flow/memory not installed... Use memory_store/memory_search tools instead."
-}
-```
-
-Replacement table for bridge-unavailable mode:
-
-| Unavailable `agentdb_*` | Use instead |
-|---|---|
-| `agentdb_hierarchical-store` / `_recall` | `memory_store` / `memory_search` |
-| `agentdb_pattern-store` / `_search` | `memory_store --namespace pattern` / `memory_search --namespace pattern` |
-| `agentdb_semantic-route` | `embeddings_search` |
-| `agentdb_context-synthesize` | `memory_search_unified` |
-
-## Verification
-
-```bash
-bash plugins/ruflo-agentdb/scripts/smoke.sh
-# Expected: "10 passed, 0 failed"
-```
-
-The smoke script is the contract. It calls each documented MCP tool, exercises the RaBitQ workflow, and source-inspects the fallback path (no env-var gate exists to force the fallback live).
-
-## Architecture Decisions
-
-- [`ADR-0001` — Optimize ruflo-agentdb (accurate surface, RaBitQ, namespacing, smoke contract)](./docs/adrs/0001-agentdb-optimization.md)
-
-## Related Plugins
-
-- `ruflo-rag-memory` — simple store/search/recall interface; consumes the `claude-memories` reserved namespace
-- `ruflo-intelligence` — SONA neural patterns; consumes the `pattern` reserved namespace via ReasoningBank
-- `ruflo-browser` — composes the namespace convention for `browser-sessions/-selectors/-templates/-cookies` (ADR-0001 §3 there)
-- `ruflo-ruvector` — pinned ruvector CLI; sibling substrate plugin
-
-## License
-
-MIT

package/.claude/worktrees/adr-120-impl/plugins/ruflo-agentdb/scripts/smoke.sh

@@ -1,204 +0,0 @@
-#!/usr/bin/env bash
-# Structural smoke test for ruflo-agentdb plugin v0.3.0.
-# Per ADR-0001 §6 Verification: 10 numbered checks against the documented
-# CLI MCP surface plus three documentation invariants.
-#
-# This script verifies plugin structural soundness and source-level
-# contracts. Live MCP-tool exercise (against a running daemon with the
-# bridge wired) is layered on top via the optional --live flag, but the
-# default invocation is offline-safe and CI-friendly.
-set -u
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-REPO_ROOT="$(cd "$ROOT/../.." && pwd)"
-LIVE=0
-for arg in "$@"; do
-  case "$arg" in --live) LIVE=1 ;; esac
-done
-
-PASS=0
-FAIL=0
-
-step() { printf "→ %s ... " "$1"; }
-ok()   { printf "PASS\n"; PASS=$((PASS+1)); }
-bad()  { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-
-# Documentation invariants (ADR-0001 §Verification)
-step "INV1: no '19 controllers' string in plugin docs (excluding ADRs which document history)"
-# ADR files inside docs/adrs/ are allowed to reference "19 controllers" because
-# they document the change. The invariant is on user-facing docs only.
-hits=$(grep -rE '19 (AgentDB )?[Cc]ontrollers|all 19 controllers' "$ROOT" \
-   --include='*.md' --include='*.json' \
-   --exclude-dir='adrs' 2>/dev/null || true)
-if [[ -n "$hits" ]]; then
-  bad "stale '19 controllers' phrasing still present in user-facing docs:"
-  echo "$hits" | sed 's/^/    /'
-else
-  ok
-fi
-
-step "INV2: RaBitQ workflow documented in vector-search SKILL"
-grep -q "embeddings_rabitq_build" "$ROOT/skills/vector-search/SKILL.md" \
-  && grep -q "embeddings_rabitq_search" "$ROOT/skills/vector-search/SKILL.md" \
-  && grep -q "embeddings_rabitq_status" "$ROOT/skills/vector-search/SKILL.md" \
-  && ok || bad "RaBitQ trio not all documented"
-
-step "INV3: README has the Namespace convention section"
-grep -q "## Namespace convention" "$ROOT/README.md" \
-  && grep -q "Reserved namespaces" "$ROOT/README.md" \
-  && ok || bad "Namespace convention section missing"
-
-# 1. Plugin version + new keywords
-step "1. plugin.json declares version 0.3.0 with rabitq + namespace-convention keywords"
-v=$(grep -E '"version"[[:space:]]*:' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.3.0" ]]; then
-  bad "expected 0.3.0, got '$v'"
-else
-  miss=""
-  for k in rabitq quantization namespace-convention controller-bridge; do
-    grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
-  done
-  [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
-fi
-
-# 2. Controller-count claims defer to runtime
-step "2. README/agent/command/skill defer controller count to runtime tool"
-miss=""
-for f in "$ROOT/README.md" "$ROOT/agents/agentdb-specialist.md" "$ROOT/commands/agentdb.md" "$ROOT/skills/agentdb-query/SKILL.md"; do
-  grep -q "agentdb_controllers" "$f" || miss="$miss $(basename $f)"
-done
-[[ -z "$miss" ]] && ok || bad "missing agentdb_controllers reference:$miss"
-
-# 3. All 15 agentdb_* tool names are documented somewhere in the plugin
-step "3. all 15 agentdb_* tool names referenced in plugin docs"
-miss=""
-for t in agentdb_health agentdb_controllers agentdb_pattern-store agentdb_pattern-search agentdb_feedback agentdb_causal-edge agentdb_route agentdb_session-start agentdb_session-end agentdb_hierarchical-store agentdb_hierarchical-recall agentdb_consolidate agentdb_batch agentdb_context-synthesize agentdb_semantic-route; do
-  grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
-done
-[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
-
-# 4. All 10 embeddings_* tools documented
-step "4. all 10 embeddings_* tool names referenced in plugin docs"
-miss=""
-for t in embeddings_init embeddings_generate embeddings_compare embeddings_search embeddings_neural embeddings_hyperbolic embeddings_status embeddings_rabitq_build embeddings_rabitq_search embeddings_rabitq_status; do
-  grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
-done
-[[ -z "$miss" ]] && ok || bad "undocumented:$miss"
-
-# 5. The 3 ruvllm_hnsw_* tools documented + the ~11 cap is acknowledged
-step "5. ruvllm_hnsw_* tools documented and ~11 cap acknowledged"
-miss=""
-for t in ruvllm_hnsw_create ruvllm_hnsw_add ruvllm_hnsw_route; do
-  grep -rq "$t" "$ROOT" --include='*.md' || miss="$miss $t"
-done
-if [[ -n "$miss" ]]; then
-  bad "undocumented:$miss"
-elif ! grep -rq "11 patterns\|≤11" "$ROOT/skills/vector-search/SKILL.md" "$ROOT/README.md" "$ROOT/agents/agentdb-specialist.md"; then
-  bad "WASM cap (~11 patterns) not acknowledged"
-else
-  ok
-fi
-
-# 6. RaBitQ workflow has a 5-step recipe + the rerank caveat
-step "6. RaBitQ section has the 5-step recipe + rerank caveat"
-F="$ROOT/skills/vector-search/SKILL.md"
-if grep -q "Quantized search" "$F" \
-   && grep -q "rerank" "$F" \
-   && grep -qE "embeddings_rabitq_build" "$F" \
-   && grep -qE "embeddings_rabitq_search" "$F" \
-   && grep -qE "embeddings_rabitq_status" "$F"; then
-  ok
-else
-  bad "RaBitQ section incomplete (missing recipe or rerank caveat)"
-fi
-
-# 7. Pattern-store fallback is source-inspectable (no env var gates this — see ADR §6 caveat)
-step "7. memory-store-fallback path is source-inspectable in agentdb-tools.ts"
-TOOLS="$REPO_ROOT/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts"
-if [[ -f "$TOOLS" ]] \
-   && grep -q "memory-store-fallback" "$TOOLS" \
-   && grep -q "ReasoningBank controller registry unavailable" "$TOOLS"; then
-  ok
-else
-  bad "fallback string not present in agentdb-tools.ts (or file moved)"
-fi
-
-# 8. agentdb_hierarchical-store rejects an unknown tier
-step "8. tier validator rejects unknown tier values"
-TOOLS="$REPO_ROOT/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts"
-if grep -qE "(working|episodic|semantic).*tier|tier.*(working|episodic|semantic)" "$TOOLS"; then
-  ok
-else
-  bad "tier validator pattern not found in agentdb-tools.ts"
-fi
-
-# 9. Batch size is bounded
-step "9. agentdb_batch enforces MAX_BATCH_SIZE = 500"
-TOOLS="$REPO_ROOT/v3/@claude-flow/cli/src/mcp-tools/agentdb-tools.ts"
-if grep -qE "MAX_BATCH_SIZE\s*=\s*500" "$TOOLS"; then
-  ok
-else
-  bad "MAX_BATCH_SIZE = 500 not present (or moved)"
-fi
-
-# 10. Namespace convention guardrails: reserved list + colon rule + length cap
-step "10. namespace guardrails documented (reserved list + colon rule + length cap)"
-F="$ROOT/README.md"
-miss=""
-grep -q "claude-memories" "$F" || miss="$miss reserved-list"
-grep -qE "SHOULD NOT contain.+:.+colon|colon.+delimiter" "$F" || \
-  grep -qE 'NOT contain `:`' "$F" || miss="$miss colon-rule"
-grep -qE "200 chars|≤200" "$F" || miss="$miss length-cap"
-[[ -z "$miss" ]] && ok || bad "guardrail set incomplete:$miss"
-
-# 11. Auto-memory bridge mechanics documented (Claude Code populates claude-memories)
-step "11. auto-memory bridge mechanics documented (memory_import_claude + auto-memory-hook.mjs)"
-F="$ROOT/README.md"
-if grep -q "How Claude Code populates AgentDB" "$F" \
-   && grep -q "memory_import_claude" "$F" \
-   && grep -q "auto-memory-hook.mjs" "$F" \
-   && grep -q "memory_bridge_status" "$F" \
-   && grep -q "memory_search_unified" "$F"; then
-  ok
-else
-  bad "auto-memory bridge section missing pieces (header, import tool, hook script, bridge status, unified search)"
-fi
-
-# 12. Hook → namespace integration table
-step "12. hook integration table maps hook → namespace it writes to"
-F="$ROOT/README.md"
-if grep -q "Hook integration convention" "$F" \
-   && grep -q "SessionStart" "$F" \
-   && grep -q "post-task --train-neural" "$F" \
-   && grep -qE "ReasoningBank.*pattern|pattern.*ReasoningBank" "$F"; then
-  ok
-else
-  bad "hook integration table missing (SessionStart, post-task --train-neural, ReasoningBank → pattern)"
-fi
-
-# 13. Pluralization gotcha (pattern vs patterns)
-step "13. pluralization gotcha documented (pattern vs patterns)"
-F="$ROOT/README.md"
-if grep -qiE "pluraliz.*gotcha|pattern.*plural|plural.*pattern" "$F" \
-   && grep -q '`pattern`' "$F" \
-   && grep -q '`patterns`' "$F"; then
-  ok
-else
-  bad "pluralization callout missing (must contrast pattern vs patterns)"
-fi
-
-# Live mode (optional, requires daemon)
-if [[ "$LIVE" == "1" ]]; then
-  step "L1 (live): agentdb_health responds (requires running daemon)"
-  if command -v claude-flow >/dev/null 2>&1; then
-    if claude-flow mcp call agentdb_health 2>/dev/null | grep -q '"available"'; then
-      ok
-    else
-      bad "agentdb_health did not return an 'available' field"
-    fi
-  else
-    bad "claude-flow CLI not on PATH (skipping --live checks)"
-  fi
-fi
-
-printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
-[[ $FAIL -eq 0 ]] || exit 1