claude-flow 3.7.0-alpha.4 → 3.7.0-alpha.40

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

@@ -0,0 +1,232 @@
+# ruflo-neural-trader
+
+Neural trading strategies powered by [`neural-trader`](https://www.npmjs.com/package/neural-trader) (v2.7+) — self-learning LSTM/Transformer/N-BEATS models, Rust/NAPI backtesting (8-19x faster), 112+ MCP tools, swarm coordination, and portfolio optimization.
+
+## Overview
+
+Wraps the `neural-trader` npm package as a Ruflo plugin with 4 specialized agents, 7 skills, and comprehensive CLI commands. Adds AgentDB memory persistence, SONA trajectory learning, and swarm-coordinated execution on top of neural-trader's Rust/NAPI engine.
+
+Heavy jobs — multi-year walk-forward backtests, large Monte-Carlo runs, parameter sweeps, LSTM/Transformer/N-BEATS training — can be dispatched to an Anthropic Managed Agent **cloud container** instead of running locally: see the `trader-cloud-backtest` skill, the `/trader cloud <backtest|train|sweep>` command, and [ADR-117](../../v3/docs/adr/ADR-117-neural-trader-managed-agent-backtests.md) (built on the `managed_agent_*` runtime from the `ruflo-agent` plugin / [ADR-115](../../v3/docs/adr/ADR-115-managed-agents-rvagent-backend.md); needs `ANTHROPIC_API_KEY` + Managed Agents beta — degrades to the local `trader-backtest` skill without it).
+
+## Prerequisites
+
+> ✅ **`neural-trader@^2.8.11`** (shipped 2026-05-14; see [post-mortem gist](https://gist.github.com/ruvnet/a1aca90a5c299d89fa92e905dab11041) and [announcement #1981](https://github.com/ruvnet/ruflo/issues/1981)).
+> Resolves four compounding bugs that made the package unusable since v2.5.0:
+> 1. Install-hook fork-bomb (#1974 — 120 GB RAM on Apple Silicon) — fixed in 2.7.2 ([neural-trader#109](https://github.com/ruvnet/neural-trader/pull/109)).
+> 2. `require('neural-trader')` always threw `Cannot find module './src/cli/lib/napi-loader-shared'` — missing files restored in 2.7.5 ([neural-trader#111](https://github.com/ruvnet/neural-trader/pull/111)).
+> 3. `cargo build` aborted on `aarch64-apple-darwin` (`fasthash-sys` x86-only SIMD) — placeholder hash replaced with stdlib `DefaultHasher` in 2.7.5.
+> 4. npm tarball claimed 5 platform binaries, shipped 1 — `darwin-arm64` + `darwin-x64` added in 2.7.6.
+>
+> The 2.8.x line additionally adds a flag-style CLI dispatcher (`--backtest`, `--signal scan`, `--risk assess`, `--portfolio optimize`, `--regime`, `--train`, `--predict`, `--strategy-create`) running real math (SMA crossover / RSI mean-reversion / pairs z-score / adaptive regime-switching / multi-indicator RSI+MACD+Bollinger) against real Yahoo Finance data via `--live`. Supports `--walk-forward`, `--monte-carlo`, `--symbols A,B,C`, `--benchmark SPY`, `--optimize --param "name:min:max:step"`. The runtime smoke ([scripts/runtime-smoke.sh](scripts/runtime-smoke.sh)) covers 20 documented entry points end-to-end (basic commands + Kelly + walk-forward + Monte Carlo + optimize + multi-symbol + pairs + adaptive + multi-indicator).
+
+```bash
+# Recommended — keeps --ignore-scripts as defense in depth. The install
+# hook is safe in 2.7.2+, but --ignore-scripts protects against any
+# future install-script regression on this or transitive packages.
+npm install --ignore-scripts neural-trader@^2.8.11
+```
+
+| Platform | Native binding in 2.8.11 |
+|----------|--------------------------|
+| `linux-x64-gnu` | ✅ |
+| `darwin-arm64` (Apple Silicon) | ✅ first shipped in 2.7.5 |
+| `darwin-x64` (Intel Macs) | ✅ first shipped in 2.7.6 |
+| `linux-arm64-gnu` | ⏳ JS surface works, native calls throw at runtime |
+| `win32-x64-msvc` | ⏳ JS surface works, native calls throw at runtime |
+
+> 🚨 **If you must use an older version** (`neural-trader@2.7.1` or below — same fork-bomb risk on every non-linux-x64 host) always pass `--ignore-scripts` to skip the malicious install hook. The `linux-x64` binary is hardcoded inline in the tarball, so on `linux-x64` the package still works after `--ignore-scripts`. On other platforms `--ignore-scripts` at least won't fork-bomb your machine.
+>
+> ```bash
+> # Only needed for neural-trader <= 2.7.1 — DO NOT run plain `npm install
+> # neural-trader@<=2.7.1` on macOS / Windows / linux-arm64.
+> npm install --ignore-scripts neural-trader@<=2.7.1
+> ```
+
+The `audit-neural-trader-safety.mjs` CI guard in this repo still enforces `--ignore-scripts` on every documented invocation — defense in depth in case anyone pins to an older version in a lockfile.
+
+## Installation
+
+```bash
+claude --plugin-dir plugins/ruflo-neural-trader
+```
+
+## MCP Integration (112+ Tools)
+
+neural-trader exposes 112+ MCP tools for direct Claude Desktop access:
+
+```bash
+claude mcp add neural-trader -- npx neural-trader mcp start
+```
+
+## Agents
+
+| Agent | Model | Role |
+|-------|-------|------|
+| `trading-strategist` | opus | Strategy design, LSTM/Transformer training, Z-score anomaly detection, backtest orchestration |
+| `risk-analyst` | sonnet | VaR/CVaR assessment, Kelly criterion sizing, circuit breakers, correlation monitoring |
+| `market-analyst` | sonnet | Regime detection, technical indicators (RSI/MACD/Bollinger), sector analysis, correlation |
+| `backtest-engineer` | sonnet | Walk-forward validation, Monte Carlo simulation, parameter optimization, benchmark comparison |
+
+## Skills
+
+| Skill | Usage | Description |
+|-------|-------|-------------|
+| `trader-backtest` | `/trader-backtest <strategy> --symbol SPY` | Rust/NAPI backtest with walk-forward validation |
+| `trader-signal` | `/trader-signal [--strategy NAME]` | Z-score anomaly detection signal generation |
+| `trader-portfolio` | `/trader-portfolio [--risk-target 0.15]` | Mean-variance portfolio optimization |
+| `trader-regime` | `/trader-regime [--symbol SPY]` | Market regime detection and classification |
+| `trader-train` | `/trader-train lstm --symbol TSLA` | Train neural prediction models |
+| `trader-risk` | `/trader-risk [--symbol AAPL]` | VaR, position sizing, circuit breaker status |
+| `trader-cloud-backtest` | `/trader cloud backtest <strategy> --symbol SPY` | Dispatch a heavy backtest / training / sweep to an Anthropic Managed Agent cloud container ([ADR-117](../../v3/docs/adr/ADR-117-neural-trader-managed-agent-backtests.md)) |
+
+## Commands
+
+```bash
+# Strategy management
+trader strategy create <name> --type <momentum|mean-reversion|pairs|adaptive>
+trader backtest <strategy> --symbol <TICKER> --period <range>
+
+# Neural model training
+trader train <lstm|transformer|nbeats> --symbol <TICKER>
+
+# Signal generation
+trader signal scan [--strategy <name>] [--symbols <TICKERS>]
+
+# Market analysis
+trader regime --symbol <TICKER>
+trader indicators --symbol <TICKER> --indicators rsi,macd,bollinger
+trader correlation --symbols <TICKERS> --window 30d
+
+# Risk & portfolio
+trader risk assess [--symbol <TICKER>]
+trader portfolio optimize [--risk-target <number>]
+
+# Live trading
+trader live --broker <name> [--swarm enabled]
+
+# History
+trader history
+```
+
+## Neural Models (via neural-trader)
+
+| Model | Type | Use Case |
+|-------|------|----------|
+| LSTM | Recurrent | Sequence prediction, price forecasting |
+| Transformer | Attention | Multi-variate pattern recognition |
+| N-BEATS | Decomposition | Trend/seasonality decomposition |
+
+```bash
+npx neural-trader --model lstm --symbol TSLA --confidence 0.95
+npx neural-trader --model transformer --symbol BTC-USD --predict
+npx neural-trader --model nbeats --symbol SPY --decompose
+```
+
+## Strategy Types
+
+| Strategy | CLI Flag | Entry Logic |
+|----------|----------|-------------|
+| Momentum | `--strategy momentum` | RSI + MACD confirmation |
+| Mean-reversion | `--strategy mean-reversion` | Z-score > 2.0, Bollinger extremes |
+| Pairs trading | `--strategy pairs` | Cointegration spread divergence |
+| Multi-indicator | `--strategy multi-indicator` | RSI + MACD + Bollinger combined |
+| Adaptive | `--strategy adaptive` | Auto-switches by regime |
+
+## Market Regime Detection
+
+| Regime | Indicators | Recommended Strategy |
+|--------|-----------|---------------------|
+| Bull trending | ADX > 25, price > 200 SMA | Momentum, trend-following |
+| Bear trending | ADX > 25, price < 200 SMA | Short momentum, hedging |
+| Ranging | ADX < 20, Bollinger squeeze | Mean-reversion |
+| High volatility | VIX > 25, ATR expanding | Reduce size, widen stops |
+| Transitioning | Divergences forming | Wait for confirmation |
+
+## Anomaly Detection
+
+neural-trader Z-score composite scoring on OHLCV: `anomalyScore = min(1, meanZ / 3)`
+
+| Type | Detection | Market Interpretation |
+|------|-----------|----------------------|
+| spike | maxZ > 5 | Breakout / gap |
+| drift | 1-2 dims sustained | Sustained trend |
+| flatline | all near zero | Consolidation |
+| oscillation | alternating | Range-bound |
+| pattern-break | moderate Z, multi-dim | Regime change |
+| cluster-outlier | >50% dims high | Multi-factor dislocation |
+
+## Circuit Breakers
+
+| Breaker | Trigger | Action |
+|---------|---------|--------|
+| Daily loss | Drawdown > 3%/day | Halt new entries |
+| Weekly loss | Drawdown > 5%/week | Reduce sizes 50% |
+| Correlation spike | Portfolio corr > 0.85 | Reduce correlated positions |
+| Volatility regime | VIX > 2x historical | Minimum position sizes |
+| Max positions | Open > limit | Block new entries |
+| Concentration | Any position > 10% | Force trim |
+
+## Backtesting Features
+
+| Feature | Command |
+|---------|---------|
+| Walk-forward | `--walk-forward --train-window 6M --test-window 1M` |
+| Monte Carlo | `--monte-carlo --simulations 1000` |
+| Parameter optimization | `--optimize --param "entry_z:1.5:3.0:0.25"` |
+| Multi-symbol | `--symbols "AAPL,MSFT,GOOGL"` |
+| Benchmark comparison | `--benchmark SPY` |
+
+## Performance
+
+neural-trader uses Rust/NAPI bindings for zero-overhead performance:
+- **8-19x faster** than Python equivalents
+- **Sub-200ms** order execution and risk checks
+- **WASM/SIMD** acceleration available
+- **52,000+ inserts/sec** for market data
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Runtime:** `npx neural-trader` (Rust/NAPI bindings — 112+ MCP tools).
+- **Verification:** `bash plugins/ruflo-neural-trader/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns four AgentDB namespaces (kebab-case, follows the convention from [ruflo-agentdb ADR-0001 §"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)):
+
+| Namespace | Purpose |
+|-----------|---------|
+| `trading-strategies` | Strategy definitions (loaded by `trader-backtest`, `trader-signal`) |
+| `trading-backtests` | Backtest results indexed by strategy + timestamp |
+| `trading-risk` | Risk metrics per portfolio |
+| `trading-analysis` | Regime detection + market analysis history |
+
+Note: the namespace prefix is `trading-` (the actual intent) rather than `neural-trader-` (the plugin stem). This is a deliberate ergonomic choice — `trading` is the load-bearing concern downstream consumers reason about. Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+All access via `memory_*` (namespace-routed). No `agentdb_hierarchical-*` or `agentdb_pattern-store` with namespace arguments — the plugin uses the correct routing throughout.
+
+## Verification
+
+```bash
+bash plugins/ruflo-neural-trader/scripts/smoke.sh
+# Expected: "11 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` — ruflo-neural-trader plugin contract (already-compliant namespaces, 4-namespace claim, smoke as contract)](./docs/adrs/0001-neural-trader-contract.md)
+- [`ADR-117`](../../v3/docs/adr/ADR-117-neural-trader-managed-agent-backtests.md) — run heavy jobs (walk-forward / Monte-Carlo / sweep / training) on the Managed Agent cloud runtime (the `trader-cloud-backtest` skill + `/trader cloud` command), with cost-optimization rules
+- [`ADR-115`](../../v3/docs/adr/ADR-115-managed-agents-rvagent-backend.md) — the `managed_agent_*` cloud runtime that ADR-117 builds on (lives in the `ruflo-agent` plugin)
+
+## Related Plugins
+
+- `ruflo-agent` — the `managed_agent_*` cloud agent runtime used by the `trader-cloud-backtest` skill (ADR-115 / ADR-117)
+- `ruflo-agentdb` — namespace convention owner; backing store
+- `ruflo-market-data` — OHLCV data ingestion and candlestick pattern detection (feeds `trading-strategies`)
+- `ruflo-ruvector` — HNSW indexing for strategy pattern similarity search
+- `ruflo-cost-tracker` — PnL tracking and cost attribution
+- `ruflo-observability` — Strategy performance dashboards
+
+## License
+
+MIT

package/.claude/worktrees/adr-120-impl/plugins/ruflo-neural-trader/scripts/runtime-smoke.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+#
+# Runtime smoke test for ruflo-neural-trader: actually invoke each
+# `npx neural-trader` command the plugin's skills document and confirm
+# it returns parseable JSON with the expected shape.
+#
+# Distinct from `smoke.sh` (which only checks file presence / README
+# pins). This one runs against a real install and is gated on the
+# `neural-trader` npm package working end-to-end.
+#
+# Run:
+#   bash plugins/ruflo-neural-trader/scripts/runtime-smoke.sh
+#
+# Exit codes:
+#   0  every command emits valid JSON with the expected `command` key
+#   1  at least one command failed
+
+set -u
+PASS=0
+FAIL=0
+FAILURES=()
+
+# Lock to the version this plugin is pinned against so a global
+# npx cache doesn't shadow a stale local install.
+NT_PIN="${NT_PIN:-2.8.11}"
+
+WORKDIR="$(mktemp -d)"
+trap 'rm -rf "$WORKDIR"' EXIT
+cd "$WORKDIR"
+
+step() { printf "→ %s ... " "$1"; }
+ok()   { printf "PASS\n"; PASS=$((PASS+1)); }
+bad()  { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); FAILURES+=("$1"); }
+
+step "0. install neural-trader@${NT_PIN}"
+npm init -y >/dev/null 2>&1
+if npm install --ignore-scripts --no-audit --no-fund "neural-trader@${NT_PIN}" >/dev/null 2>&1; then
+  ok
+else
+  bad "npm install failed"
+  echo "$FAIL failures — aborting"
+  exit 1
+fi
+
+# Helper: run a command, parse JSON, assert it has .command == expected
+run_and_check() {
+  local label="$1" expected_cmd="$2"
+  shift 2
+  step "$label"
+  local out
+  if ! out=$(npx neural-trader "$@" 2>&1); then
+    bad "command exited non-zero: $out"
+    return
+  fi
+  local cmd
+  # Pull the .command field out of the JSON output. Use the standard
+  # `jq` filter — much safer than an inline node script through zsh,
+  # which mangles closing parens.
+  cmd=$(echo "$out" | jq -r 'if type == "object" then (.command // "") else "" end' 2>/dev/null)
+  if [[ "$cmd" == "$expected_cmd" ]]; then
+    ok
+  else
+    bad "expected command=\"$expected_cmd\", got \"$cmd\" — head: $(echo "$out" | head -3 | tr '\n' '|')"
+  fi
+}
+
+run_and_check "1. --backtest"        "backtest"        --backtest --strategy momentum --symbol AAPL --period 2024-01-01..2024-12-31
+run_and_check "2. --signal scan"     "signal"          --signal scan --symbols AAPL,MSFT
+run_and_check "3. --risk assess"     "risk"            --risk assess --returns 0.01,0.02,-0.005,0.015,-0.01
+run_and_check "4. --portfolio"       "portfolio"       --portfolio optimize --symbols AAPL,MSFT,GOOGL
+run_and_check "5. --regime"          "regime"          --regime --symbol SPY
+run_and_check "6. --train"           "train"           --train --symbol AAPL --model lstm --epochs 10
+run_and_check "7. --predict"         "predict"         --predict --symbol AAPL --model lstm
+run_and_check "8. --strategy-create" "strategy-create" --strategy-create momentum-spy --type momentum --symbols SPY
+
+step "9. require('neural-trader') exposes 194 exports"
+exports=$(node -e "console.log(Object.keys(require('neural-trader')).length)")
+if [[ "$exports" -ge 100 ]]; then
+  ok
+else
+  bad "expected >=100 exports, got $exports"
+fi
+
+step "10. --version"
+if npx neural-trader --version 2>&1 | grep -qE "^${NT_PIN%.*}\."; then
+  ok
+else
+  bad "version mismatch"
+fi
+
+# Helper: run a command and assert a jq path is non-null.
+assert_field() {
+  local label="$1" field="$2"
+  shift 2
+  step "$label"
+  local out value
+  out=$(npx neural-trader "$@" 2>&1)
+  value=$(echo "$out" | jq -r "$field" 2>/dev/null)
+  if [[ -n "$value" && "$value" != "null" && "$value" != "false" ]]; then
+    ok
+  else
+    bad "field $field missing/null/false — head: $(echo "$out" | head -3 | tr '\n' '|')"
+  fi
+}
+
+assert_field "11. backtest exposes Kelly fraction"   '.metrics.kellyFraction'    --backtest --symbol AAPL
+assert_field "12. --walk-forward returns windows"    '.walkForward.windowsRun'   --backtest --symbol AAPL --walk-forward --period 2023-01-01..2024-12-31
+assert_field "13. --monte-carlo returns distribution" '.monteCarlo.distribution.median' --backtest --symbol AAPL --monte-carlo --mc-runs 100
+assert_field "14. --optimize returns best Sharpe"    '.optimization.best.sharpeRatio' --backtest --symbol AAPL --optimize --param fast_ma:10:20:5
+assert_field "15. --signal scan returns ≥1 signal"   '.signalsCount'             --signal scan --symbols AAPL,MSFT
+assert_field "16. multi-symbol aggregate"            '.aggregate.bestSymbol'     --backtest --symbols AAPL,MSFT,GOOGL
+assert_field "17. pairs strategy returns metrics"    '.metrics.totalTrades'      --backtest --strategy pairs --symbols AAPL,MSFT
+assert_field "18. adaptive strategy picks regime"    '.regimePicked'             --backtest --strategy adaptive --symbol AAPL
+assert_field "19. multi-indicator strategy runs"     '.command'                  --backtest --strategy multi-indicator --symbol AMZN
+
+echo ""
+echo "$PASS passed, $FAIL failed"
+[[ $FAIL -eq 0 ]] || { printf 'failed steps: %s\n' "${FAILURES[@]}"; exit 1; }

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

@@ -0,0 +1,86 @@
+#!/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 declares 0.2.0 with new keywords"
+v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if [[ "$v" != "0.2.0" ]]; then bad "expected 0.2.0, got '$v'"; else
+  miss=""
+  for k in neural-trader-runtime walk-forward monte-carlo; do
+    grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+  done
+  [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. all 7 skills present with valid frontmatter (6 base + trader-cloud-backtest, ADR-117)"
+miss=""
+for s in trader-backtest trader-portfolio trader-regime trader-risk trader-signal trader-train trader-cloud-backtest; do
+  f="$ROOT/skills/$s/SKILL.md"
+  [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+  for k in 'name:' 'description:' 'allowed-tools:'; do
+    grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+  done
+done
+# the cloud-backtest skill must reference the managed_agent_* tools + offer the local fallback
+grep -q 'managed_agent_create' "$ROOT/skills/trader-cloud-backtest/SKILL.md" 2>/dev/null || miss="$miss cloud-no-managed-tool-ref"
+grep -q 'trader-backtest' "$ROOT/skills/trader-cloud-backtest/SKILL.md" 2>/dev/null || miss="$miss cloud-no-local-fallback-ref"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. all 4 agents present"
+miss=""
+for a in backtest-engineer market-analyst risk-analyst trading-strategist; do
+  [[ -f "$ROOT/agents/$a.md" ]] || miss="$miss missing-$a"
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. command present"
+[[ -f "$ROOT/commands/trader.md" ]] && ok || bad "trader command missing"
+
+step "5. 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 "6. README pins neural-trader runtime"
+grep -qE "npx neural-trader|Rust/NAPI" "$ROOT/README.md" \
+  && ok || bad "neural-trader runtime pin missing"
+
+step "7. 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 "8. all 4 namespaces claimed (trading-strategies/-backtests/-risk/-analysis)"
+F="$ROOT/README.md"
+miss=""
+for ns in trading-strategies trading-backtests trading-risk trading-analysis; do
+  grep -q "$ns" "$F" || miss="$miss $ns"
+done
+[[ -z "$miss" ]] && ok || bad "missing namespace claims:$miss"
+
+step "9. backtesting features documented (walk-forward, Monte Carlo, parameter optimization)"
+F="$ROOT/README.md"
+miss=""
+grep -q "Walk-forward\|walk-forward" "$F" || miss="$miss walk-forward"
+grep -q "Monte Carlo\|monte-carlo" "$F" || miss="$miss monte-carlo"
+grep -q "Parameter optimization\|parameter optimization\|param-optimize" "$F" || miss="$miss param-opt"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "10. ADR-0001 exists with status Accepted"
+ADR="$ROOT/docs/adrs/0001-neural-trader-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"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1

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

@@ -0,0 +1,22 @@
+{
+  "name": "ruflo-observability",
+  "description": "Structured logging, distributed tracing, and metrics — correlate agent swarm activity with application telemetry",
+  "version": "0.2.0",
+  "author": {
+    "name": "ruvnet",
+    "url": "https://github.com/ruvnet"
+  },
+  "homepage": "https://github.com/ruvnet/ruflo",
+  "license": "MIT",
+  "keywords": [
+    "ruflo",
+    "observability",
+    "logging",
+    "tracing",
+    "metrics",
+    "telemetry",
+    "mcp",
+    "distributed-tracing",
+    "anomaly-detection"
+  ]
+}

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

@@ -0,0 +1,98 @@
+# ruflo-observability
+
+Structured logging, distributed tracing, and metrics -- correlate agent swarm activity with application telemetry.
+
+## Overview
+
+Implements OpenTelemetry-compatible structured logging with correlation IDs, distributed tracing with parent-child span hierarchies, and metrics collection (counters, gauges, histograms). Correlates swarm agent activity with application-level telemetry and detects anomalies in latency, error rates, and resource usage.
+
+## Installation
+
+```bash
+claude --plugin-dir plugins/ruflo-observability
+```
+
+## Agents
+
+| Agent | Model | Role |
+|-------|-------|------|
+| `observability-engineer` | sonnet | Structured logging, distributed tracing, metrics collection, agent-application telemetry correlation |
+
+## Skills
+
+| Skill | Usage | Description |
+|-------|-------|-------------|
+| `observe-trace` | `/observe-trace <task-id>` | Trace agent execution by collecting spans and building a trace tree |
+| `observe-metrics` | `/observe-metrics [--period 1h]` | Aggregate and display system metrics with anomaly detection |
+
+## Commands (5 subcommands)
+
+```bash
+observe trace <task-id>              # Trace agent execution with span tree
+observe metrics [--period 1h]        # View aggregated metrics (p50, p95, p99)
+observe logs [--level error]         # Filter structured logs by level
+observe dashboard                    # Combined health dashboard
+observe correlate <agent-id>         # Correlate all telemetry for an agent
+```
+
+## Key Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `agent_task_duration_seconds` | Histogram | Time to complete agent tasks |
+| `agent_token_usage` | Counter | Tokens consumed per agent/model |
+| `agent_active_count` | Gauge | Currently active agents |
+| `agent_error_rate` | Counter | Errors per agent |
+| `swarm_span_duration_ms` | Histogram | Span durations for tracing |
+| `memory_operations_total` | Counter | AgentDB read/write counts |
+
+## Trace Hierarchy
+
+```
+[root] swarm-task
+  [child] agent-spawn (agent=architect)
+  [child] agent-spawn (agent=coder)
+    [child] file-read (path=src/auth.ts)
+    [child] file-write (path=src/auth.ts)
+  [child] agent-spawn (agent=tester)
+    [child] test-run (suite=auth)
+```
+
+## Log Format
+
+JSON structured logs with `timestamp`, `level`, `message`, `correlationId`, `agentId`, `taskId`, `spanId`, `traceId`, `duration_ms`, and `metadata`.
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-observability/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns the `observability` AgentDB namespace (base-name exception per [ruflo-agentdb ADR-0001 §"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md), same precedent as `federation` and `migrations`). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+`observability` is accessed via `memory_*` tools (namespace-routed). Stores spans, metric snapshots, and log entries.
+
+> **Routing note:** Earlier versions of these skills used `agentdb_hierarchical-recall` with namespace argument — that tool family routes by tier and ignores namespace strings. ADR-0001 fixed the skills to use `memory_*` for namespaced reads and documented the dual pattern-store path for metric snapshots.
+
+## Verification
+
+```bash
+bash plugins/ruflo-observability/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` — ruflo-observability plugin contract (namespace-routing fix, smoke as contract)](./docs/adrs/0001-observability-contract.md)
+
+## Related Plugins
+
+- `ruflo-agentdb` — namespace convention owner; defines the routing rules ADR-0001 fixes a violation of
+- `ruflo-cost-tracker` -- Token usage metrics feed into cost attribution
+- `ruflo-iot-cognitum` -- Reuses Z-score anomaly detection for telemetry patterns
+- `ruflo-market-data` -- Data feed health and ingestion latency monitoring
+
+## License
+
+MIT

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

@@ -0,0 +1,86 @@
+#!/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 declares 0.2.0 with new keywords"
+v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if [[ "$v" != "0.2.0" ]]; then bad "expected 0.2.0, got '$v'"; else
+  miss=""
+  for k in mcp distributed-tracing anomaly-detection; do
+    grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || 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 observe-trace observe-metrics; do
+  f="$ROOT/skills/$s/SKILL.md"
+  [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+  for k in 'name:' 'description:' 'allowed-tools:'; do
+    grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+  done
+done
+[[ -f "$ROOT/agents/observability-engineer.md" ]] || miss="$miss missing-agent"
+[[ -f "$ROOT/commands/observe.md" ]] || miss="$miss missing-command"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. observe-trace uses memory_* for namespaced reads"
+F="$ROOT/skills/observe-trace/SKILL.md"
+miss=""
+grep -q "memory_search\|memory_list" "$F" || miss="$miss no-memory-load"
+grep -qE 'agentdb_hierarchical-recall.+observability|observability.+agentdb_hierarchical-recall' "$F" && miss="$miss still-uses-hierarchical-recall"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. observe-metrics uses memory_* for namespaced reads"
+F="$ROOT/skills/observe-metrics/SKILL.md"
+miss=""
+grep -q "memory_search\|memory_list" "$F" || miss="$miss no-memory-load"
+grep -qE 'agentdb_hierarchical-recall.+observability|observability.+agentdb_hierarchical-recall' "$F" && miss="$miss still-uses-hierarchical-recall"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "5. observe-metrics documents dual pattern-store path"
+F="$ROOT/skills/observe-metrics/SKILL.md"
+if grep -q "ReasoningBank" "$F" \
+   && grep -q "memory_store --namespace observability" "$F"; then
+  ok
+else
+  bad "missing dual-path documentation"
+fi
+
+step "6. /observe command covers 5 subcommands"
+F="$ROOT/commands/observe.md"
+miss=""
+for sub in trace metrics logs dashboard correlate; do
+  grep -q "$sub" "$F" || miss="$miss $sub"
+done
+[[ -z "$miss" ]] && ok || bad "missing subcommands:$miss"
+
+step "7. 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 "8. 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 "9. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-observability-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+  && ok || bad "ADR missing or status != Proposed"
+
+step "10. 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"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1

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

@@ -0,0 +1,21 @@
+{
+  "name": "ruflo-plugin-creator",
+  "description": "Scaffold, validate, and publish new Claude Code plugins with the canonical plugin contract — ADR + smoke + Compatibility + namespace coordination + MCP-tool drift warnings",
+  "version": "0.2.0",
+  "author": {
+    "name": "ruvnet",
+    "url": "https://github.com/ruvnet"
+  },
+  "homepage": "https://github.com/ruvnet/ruflo",
+  "license": "MIT",
+  "keywords": [
+    "ruflo",
+    "plugin",
+    "scaffold",
+    "generator",
+    "developer-tools",
+    "mcp",
+    "scaffolding",
+    "contract-bootstrap"
+  ]
+}