agent-devkit 0.0.1

package/runtime/vendor/plugins/ruflo/ruflo-cost-tracker/README.md

@@ -0,0 +1,180 @@
+# ruflo-cost-tracker
+
+Token usage tracking, model cost attribution per agent, budget alerts, and optimization recommendations.
+
+## Overview
+
+Tracks token usage per agent, task, and model, then computes USD cost attribution using current model pricing. Monitors configurable budgets with tiered alerts (info at 50%, warning at 75%, critical at 90%, hard stop at 100%). Analyzes usage patterns and recommends optimizations such as model downgrades, prompt caching, and batch operations.
+
+## Installation
+
+```bash
+claude --plugin-dir plugins/ruflo-cost-tracker
+```
+
+## Agents
+
+| Agent | Model | Role |
+|-------|-------|------|
+| `cost-analyst` | haiku | Token usage tracking, USD cost attribution, budget monitoring, optimization recommendations |
+
+## Skills
+
+| Skill | Usage | Description |
+|-------|-------|-------------|
+| `cost-report` | `/cost-report [--period today]` | Generate a cost report with token usage and USD costs by tier, model, and agent |
+| `cost-optimize` | `/cost-optimize` | Analyze usage patterns, recommend cost optimizations, and emit `hooks_model-outcome` events |
+| `cost-track` | `/cost-track` | **Auto-capture** per-session token usage from the Claude Code jsonl into `cost-tracking` namespace (producer side). Also auto-fires on session-end via the Stop hook in `hooks/hooks.json` — no manual invocation needed. |
+| `cost-budget-check` | `/cost-budget-check [--period today\|week\|month\|all]` | Read totals + budget config, emit 50/75/90/100% alert ladder; exit 1 on HARD_STOP |
+| `cost-booster-route` | `/cost-booster-route <task>` | Route tasks via `hooks_route` and report Agent Booster (Tier 1) bypass utilization |
+| `cost-booster-edit` | `/cost-booster-edit <intent> <file>` | **Apply** a Tier 1 transform via `agent-booster.apply()` (sub-millisecond, $0, deterministic) |
+| `cost-benchmark` | `/cost-benchmark [--llm] [--anthropic]` | Run the corpus benchmark and persist measured-vs-claimed table to `docs/benchmarks/runs/` |
+| `cost-trend` | `/cost-trend` | Read all bench runs and surface drift (win rate, latency, speedup) — flags regressions the smoke gate misses |
+| `cost-projection` | `/cost-projection [--window 7d]` | **Forward** spend extrapolation: USD/day rate × 7d/30d/90d/365d horizons + days-until-budget-exhausted (predictive counterpart to `cost-budget-check`) |
+| `cost-counterfactual` | `/cost-counterfactual [--since 7d] [--baseline all]` | **Comparative** cost analysis: actual spend vs always-haiku / always-sonnet / always-opus baselines. Negative savings flag over-escalation; positive savings quantify routing's win. |
+| `cost-burn` | `/cost-burn [--bucket 1d] [--lookback 14d] [--alert-on-acceleration-pct N]` | **Trend** burn-rate analysis: window-over-window delta + optional drift-alert exit code. Catches "hot loop burning 10× normal" before budget alarm fires. |
+| `cost-anomaly` | `/cost-anomaly [--since 7d] [--threshold 3.5] [--alert-on-outliers N]` | **Point-anomaly** MAD-based outlier detection: flags individual sessions with `\|modified z\| > threshold` (Iglewicz-Hoaglin 3.5 default). Robust to outliers themselves; works on n=10. |
+| `cost-diff` | `/cost-diff --baseline <path> --current <path> [--alert-on-pct N] [--alert-on-usd N]` | **PR regression detection** — diffs two cost-summary JSON snapshots. Per-tier + per-model breakdowns sorted by `\|delta\|`. Optional pct/USD alert thresholds for CI gating. |
+| `cost-session` | `/cost-session [--session-id <id>] [--top 20] [--since <iso-ts>]` | **Drill-down** — per-message cost breakdown within ONE session. Surfaces top-N expensive messages with cache_write column so $16 messages stop looking like 569-token outputs. Pair with cost-anomaly. |
+| `cost-health` | `/cost-health [--alert-acceleration 100] [--alert-outliers 1] [--skip burn,anomaly]` | **Composite CI gate** — runs budget+burn+anomaly+projection in parallel, returns `max(exit)`. One shell-out covers all four alert ladders. |
+| `cost-conversation` | `/cost-conversation` | Per-conversation cost view (different lens from cost-report's per-agent / per-model) |
+| `cost-export` | `/cost-export [--prometheus <path>] [--webhook <url>]` | Emit cost data as Prometheus textfile or POST to a webhook |
+| `cost-federation` | `/cost-federation` | ADR-097 Phase 3 consumer — per-peer 1h/24h/7d federation_spend rolling windows |
+| `cost-summary` | `/cost-summary [--format json\|markdown]` | Single-shot programmatic dump of all cost data (stable JSON contract for inter-plugin consumption) |
+| `cost-compact-context` | `/cost-compact-context <query>` | Wrap `getTokenOptimizer().getCompactContext()` for retrieval-compacted analysis (graceful fallback when agentic-flow not installed) |
+
+## Commands (20 subcommands)
+
+```bash
+cost track                                # Auto-capture this session's token usage (producer)
+cost report [--period today|week|month]   # Cost report (with By-tier block, reads measured booster data)
+cost breakdown [--by agent|model|task]    # Detailed breakdown by dimension
+cost optimize                             # Analyze usage and suggest savings (+ auto-emits hooks_model-outcome via outcome.mjs)
+cost outcome <task> <model> <outcome>     # Emit hooks_model-outcome (success|escalated|failure) so the router learns
+cost budget set <amount>                  # Set USD budget (real impl, persists to cost-tracking)
+cost budget get                           # Show current budget config
+cost budget check [--period ...]          # Compute utilization + alert; exit 1 on HARD_STOP
+cost benchmark [--llm] [--anthropic]      # Run measured benchmark — booster + optional Gemini/Sonnet/Opus baselines
+cost trend                                # Drift across bench runs (win rate, latency, regressions)
+cost projection [--window 7d]             # Forward USD/day extrapolation + days-until-budget-exhausted
+cost counterfactual [--since 7d]          # Multi-baseline (haiku/sonnet/opus) — is routing earning its keep?
+cost burn [--bucket 1d] [--alert ...]     # Burn-rate trend + acceleration alert (exit 1 on drift)
+cost anomaly [--since 7d] [--alert ...]   # MAD-based per-session outlier detection (exit 1 on outliers)
+cost diff --baseline <p> --current <p> ... # Snapshot delta — PR-level regression detection (exit 1 on >N% growth)
+cost session [--session-id <id>] [--top N] # Per-message drill-down within one session (cache_write column!)
+cost health [--alert-acceleration N] ...  # Composite CI gate: budget+burn+anomaly+projection in parallel (max exit)
+cost conversation                         # Per-conversation cost view
+cost summary [--format json|markdown]     # Programmatic JSON contract for inter-plugin consumption
+cost export [--prometheus] [--webhook]    # External observability — Prometheus textfile + webhook POST
+cost federation                           # ADR-097 Phase 3 federation_spend consumer
+cost workers                              # Inspect optimize + benchmark loop-workers consumed
+cost history                              # Show cost tracking over time
+```
+
+## Optimization integration (ADR-0002)
+
+Four upstream capabilities are now wired to the cost-tracker surface — every optimization recommendation maps to a real tool, not a heuristic:
+
+| Capability | Where | Surfaced by |
+|---|---|---|
+| **Agent Booster bypass** (Tier 1, $0, WASM) | `hooks_route` emits `[AGENT_BOOSTER_AVAILABLE]` (CLI: `npx @claude-flow/cli@latest hooks route --task ...`) | `cost-booster-route` skill |
+| **Token optimizer / compact context** | `getTokenOptimizer().getCompactContext()` from `@claude-flow/integration` (uses `agentic-flow` when present) | `cost-compact-context` skill |
+| **Model-outcome feedback loop** | `hooks_model-outcome` (typed equivalent of legacy `routing-outcomes`) | `cost-optimize` skill step 8 |
+| **Optimize + benchmark loop workers** | `hooks_worker-status --worker optimize / --worker benchmark` (declared by ruflo-loop-workers) | `cost workers` command + `cost-analyst` agent |
+
+CLAUDE.md root percentage claims (`-32%` retrieval, `-15%` booster edits, `352x` speedup, `95%` cache hit) are **claimed upstream, not yet verified** in this repo. The skills above tag every figure with that disclaimer; only the structural `$0` cost of Tier 1 bypasses is reported as a measured saving.
+
+See [ADR-0002](./docs/adrs/0002-agentic-flow-and-agent-booster-integration.md) for the full rationale, including the riskiest assumption (no MCP wrapper for `getTokenOptimizer` — `cost-compact-context` shells a Node one-liner).
+
+## Model Pricing (per 1M tokens)
+
+| Model | Input | Output | Cache Write | Cache Read |
+|-------|-------|--------|-------------|------------|
+| Haiku | $0.25 | $1.25 | $0.30 | $0.03 |
+| Sonnet | $3.00 | $15.00 | $3.75 | $0.30 |
+| Opus | $15.00 | $75.00 | $18.75 | $1.50 |
+
+## Budget Alert Thresholds
+
+| Level | Threshold | Action |
+|-------|-----------|--------|
+| Info | 50% consumed | Log notification |
+| Warning | 75% consumed | Display warning, suggest optimizations |
+| Critical | 90% consumed | Urgent alert, recommend model downgrades |
+| Hard Stop | 100% consumed | Halt non-essential agent spawns |
+
+## Optimization Strategies
+
+| Strategy | Savings | Impact |
+|----------|---------|--------|
+| Downgrade simple tasks to Haiku | 80-92% | Minimal for low-complexity work |
+| Enable prompt caching | 90% on reads | None (same quality) |
+| Batch similar operations | 15-25% | Slight latency increase |
+| Use Agent Booster (Tier 1) | 100% | Only for simple transforms |
+| Shorten system prompts | 10-20% | Requires careful pruning |
+
+## Federation budget circuit breaker pairing (ruflo 3.6.25+)
+
+This plugin pairs naturally with the federation budget envelope shipped in [ADR-097](../../v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md). The `federation_send` MCP tool now accepts caller-supplied caps that this plugin's tracking should respect:
+
+| Field | Default | Effect |
+|---|---|---|
+| `maxHops` | `8` | Hard ceiling on recursive delegation across federated peers — defangs cost cascades from runaway sub-swarms. |
+| `maxTokens` | unbounded | Σ tokens across the whole hop chain. Returns `BUDGET_EXCEEDED` (constant string, no oracle leak) on overshoot. |
+| `maxUsd` | unbounded | Σ USD across hops. Same enforcement. |
+| `hopCount` | `0` | Pass-through for re-forwarded messages. |
+| `spent.{tokens,usd}` | `0` | Caller-reported usage from previous legs. Negatives clamped to 0. |
+
+Phase 1 of ADR-097 enforces at the **send** side. Two follow-up phases will tighten the integration:
+
+- **Phase 2 (deferred)** — peer state machine `ACTIVE` / `SUSPENDED` / `EVICTED` driven by trailing 24h cost (default suspension threshold $5) + 1h failure ratio (>50% over ≥10 sends). Auto-recovery after 30 min cooldown.
+- **Phase 3 (deferred)** — `federation_spend` event bus. Each `federation_send` completion publishes `{peerId, taskId, tokensUsed, usdSpent, ts}`. This plugin's cost-tracker should aggregate per-peer rolling windows (1h / 24h / 7d) and expose them via the existing `cost-report` skill. Breaker queries the aggregate to evaluate suspension thresholds.
+
+Until Phase 3 ships, federated spend is **not** counted in the host's cost-tracker — only local agent spend. Treat `cost-report` numbers as a lower bound when federation is in use.
+
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-cost-tracker/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns two AgentDB namespaces:
+
+- `cost-tracking` — usage records (consumed by `cost-report`)
+- `cost-patterns` — optimization recommendations (consumed by `cost-optimize`)
+
+Both follow the kebab-case `<plugin-stem>-<intent>` convention from [ruflo-agentdb ADR-0001 §"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md). Both are accessed via the `memory_*` tool family which routes by namespace.
+
+> **Routing note:** The `agentdb_hierarchical-*` and `agentdb_pattern-*` tools route by tier / ReasoningBank, not by namespace string. Earlier versions of `cost-report` and `cost-optimize` passed namespace arguments to those tools and got silently-ignored behavior. ADR-0001 fixes this by switching the load path to `memory_*` and documenting the dual write path for optimization patterns.
+
+Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+## Verification
+
+```bash
+bash plugins/ruflo-cost-tracker/scripts/smoke.sh
+# Expected: "44 passed, 0 failed"
+
+CI: see [`.github/workflows/cost-tracker-smoke.yml`](../../.github/workflows/cost-tracker-smoke.yml).
+On every PR touching this plugin, GitHub Actions runs smoke + booster-only bench
++ regression gate (Tier 1 winRate ≥ 0.80). LLM/Anthropic baselines are NOT run in CI
+— they cost real money per invocation and belong in a manual / scheduled workflow.
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` — ruflo-cost-tracker plugin contract (namespace-routing fix, federation budget pairing, smoke as contract)](./docs/adrs/0001-cost-tracker-contract.md)
+- [`ADR-0002` — agentic-flow + Agent Booster integration, model-outcome feedback loop, optimize-worker consumption, tier-aware reporting](./docs/adrs/0002-agentic-flow-and-agent-booster-integration.md)
+- [`ADR-0003` — Implementation arc v0.5 → v0.15 (auto-capture, budget enforcement, model-outcome feedback, observability, federation consumer)](./docs/adrs/0003-implementation-arc-v0.5-to-v0.15.md)
+
+## Related Plugins
+
+- `ruflo-agentdb` — namespace convention owner; defines the routing rules ADR-0001 fixes a violation of
+- `ruflo-observability` -- Token usage metrics collected via observability instrumentation
+- `ruflo-neural-trader` -- PnL tracking and cost-adjusted return calculation
+- `ruflo-federation` -- Budget circuit breaker on outbound federation_send (ADR-097)
+
+## License
+
+MIT

package/runtime/vendor/plugins/ruflo/ruflo-cost-tracker/REFERENCE.md

@@ -0,0 +1,92 @@
+# ruflo-cost-tracker — Reference
+
+Companion reference for `cost-analyst`. The agent prompt deliberately stays lean per [ADR-098 Part 2](../../v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md); this file collects the pricing table, formulas, alert ladder, optimization catalog, and report shape the agent reads on-demand.
+
+## Model pricing (USD per 1M tokens)
+
+| Model | Input | Output | Cache write | Cache read |
+|---|---|---|---|---|
+| Haiku | $0.25 | $1.25 | $0.30 | $0.03 |
+| Sonnet | $3.00 | $15.00 | $3.75 | $0.30 |
+| Opus | $15.00 | $75.00 | $18.75 | $1.50 |
+
+Prices are public-list and may need a refresh — verify against the Anthropic pricing page when running quarterly cost reports.
+
+## Cost attribution formula
+
+```
+task_cost = (input_tokens       / 1_000_000 * input_price)
+          + (output_tokens      / 1_000_000 * output_price)
+          + (cache_write_tokens / 1_000_000 * cache_write_price)
+          + (cache_read_tokens  / 1_000_000 * cache_read_price)
+```
+
+Cache-read tokens are 90% cheaper than fresh input — that's where prompt caching pays off.
+
+## Budget alert thresholds
+
+| Level | Threshold | Action |
+|---|---|---|
+| Info | 50% consumed | Log notification, no UX disruption |
+| Warning | 75% consumed | Display warning, suggest optimizations |
+| Critical | 90% consumed | Urgent alert, recommend model downgrades |
+| Hard stop | 100% consumed | Halt non-essential agent spawns |
+
+Budgets are configured per project + per session via the cost-tracker plugin commands.
+
+## Optimization strategies
+
+| Strategy | Savings | Quality / latency impact |
+|---|---|---|
+| Downgrade simple tasks to Haiku | 80–92% | Minimal for low-complexity work |
+| Enable prompt caching | 90% on cache reads | None (same quality) |
+| Batch similar operations | 15–25% | Slight latency increase |
+| Reduce agent count | Linear | May slow parallel work |
+| Use Agent Booster (Tier 1) | 100% (no LLM) | Only for simple transforms (var-to-const, add-types, etc.) |
+| Shorten system prompts | 10–20% | Requires careful pruning |
+
+Strategy ordering: Agent Booster first when the task fits, prompt caching always (it's free wins), then model downgrade and batching for stable workloads.
+
+## Cost report shape
+
+```
+=== Cost Report (YYYY-MM-DD) ===
+
+Total: $12.45 / $50.00 budget (24.9%)
+
+By tier:
+  Tier 1 (booster):     $0.00 (0.0%)   — 18 bypasses, $0 cost (no LLM call)
+  Tier 2 (haiku):       $0.45 (3.6%)   — 1,200K input, 400K output
+  Tier 3 (sonnet+opus): $12.00 (96.4%) — 1,980K input, 348K output
+
+By model:
+  Haiku:  $0.45 (3.6%)  — 1,200K input, 400K output
+  Sonnet: $8.20 (65.9%) — 1,800K input, 320K output
+  Opus:   $3.80 (30.5%) — 180K input, 28K output
+
+By agent:
+  coder:      $5.20 (41.8%) — sonnet
+  architect:  $3.80 (30.5%) — opus
+  researcher: $2.00 (16.1%) — sonnet
+  tester:     $1.00 (8.0%)  — sonnet
+  reviewer:   $0.45 (3.6%)  — haiku
+
+Optimization opportunities:
+  - reviewer already on haiku — no change needed
+  - researcher tasks avg complexity 22% — consider haiku (-$1.60 savings)
+  - architect cache hit rate 40% — enable caching (-$1.14 savings)
+  - Tier 3 spend is 96.4% of total — see cost-booster-route skill to audit Tier 1 eligibility
+```
+
+### Tier classification rules
+
+Tier classification at report-time uses two signals, in priority order:
+
+1. **`[AGENT_BOOSTER_AVAILABLE]` flag** stored by the `cost-booster-route` skill in the `cost-tracking` namespace — authoritative when present.
+2. **Model name fallback** — `haiku` → Tier 2; `sonnet`/`opus` → Tier 3; missing/unknown → Tier 3 (conservative).
+
+The tier breakdown is the report's most actionable line: it tells the user *what fraction of Sonnet/Opus spend was Tier 1-eligible*. Without it, the report can't surface "you spent $X on Sonnet for tasks that should have routed to Tier 1" — see [ADR-0002 §"Decision 5"](docs/adrs/0002-agentic-flow-and-agent-booster-integration.md) for the rationale.
+
+## Federation cost integration (ADR-097 pairing)
+
+When `ruflo-federation` is loaded, `federation_send` calls carry optional `maxTokens` / `maxUsd` budget envelopes. Phase 1 enforces at the send side; Phase 3 (deferred) wires `federation_spend` events into this plugin's per-peer rolling aggregate so the cost report includes federated spend grouped by peer. Until Phase 3 ships, treat `cost-report` numbers as a **lower bound** when federation is in use.

package/runtime/vendor/plugins/ruflo/ruflo-cost-tracker/agents/cost-analyst.md

@@ -0,0 +1,98 @@
+---
+name: cost-analyst
+description: Tracks token usage per agent and model, computes cost attribution in USD, monitors budgets, and recommends optimizations
+model: haiku
+---
+You are a cost analyst agent. Your responsibilities:
+
+1. **Track token usage** per agent, per task, and per model.
+2. **Compute cost attribution** by mapping token counts to USD using model pricing.
+3. **Monitor budgets** with configurable thresholds and alerts.
+4. **Recommend optimizations** to reduce costs without degrading quality.
+5. **Generate reports** with breakdowns by agent, model, task, and time period.
+
+## Reference
+
+Model pricing per 1M tokens (Haiku/Sonnet/Opus × Input/Output/Cache-Write/Cache-Read), the cost attribution formula, the four-tier budget alert ladder (50% / 75% / 90% / 100%), the optimization strategy catalog with savings ranges, and the standard cost-report markdown layout all live in [`REFERENCE.md`](../REFERENCE.md). Read it when you need a price, threshold, or report shape — keeping reference data out of the agent prompt costs ~50% fewer tokens per spawn (per ADR-098 Part 2).
+
+## Skills (20 — what each does, when to invoke)
+
+| Skill | Role | Invoke when |
+|---|---|---|
+| `cost-track` | **Producer** — reads session jsonl, persists per-session usage to `cost-tracking`. Auto-fires on session Stop via `hooks/hooks.json` (iter 78); manual invocation rarely needed | After significant work; cron-friendly. Also runs automatically at every session end. |
+| `cost-report` | Per-agent / per-model narrative report (with By-tier block) | User asks for a cost report |
+| `cost-optimize` | Recommend downgrades + auto-emit `hooks_model-outcome` | Cost is higher than expected |
+| `cost-budget-check` | 50/75/90/100% alert ladder; exit 1 on HARD_STOP | Before spawning swarms; cron-friendly |
+| `cost-conversation` | Per-conversation cost view (different lens from cost-report) | "Which conversations cost the most?" |
+| `cost-summary` | Stable JSON contract for inter-plugin consumption | Another plugin/dashboard needs a snapshot |
+| `cost-trend` | Drift across `runs/*.json` — flags regressions the binary smoke gate misses | Pre-release audit |
+| `cost-projection` | Forward USD/day extrapolation + days-until-budget-exhausted | Quarterly/annual budget planning; CI gate "is exhaustion imminent?" |
+| `cost-counterfactual` | Multi-baseline (haiku/sonnet/opus) — actual spend vs hypothetical routing | Quarterly proof: "we saved $X vs always-sonnet"; over-escalation detection |
+| `cost-burn` | Burn-rate trend over time + acceleration alert; exit 1 on drift | CI gate: "did spend just spike?"; pre-release sanity check; complements budget-check (reactive) and projection (predictive) |
+| `cost-anomaly` | MAD-based outlier detection on session spend; exit 1 on outliers | "Which specific session is the outlier?"; pair with cost-burn for both aggregate-trend AND point-anomaly coverage |
+| `cost-health` | Composite CI gate — runs budget+burn+anomaly+projection in parallel, returns max exit code | Single CI step that covers all four alert ladders; faster than wiring each separately because subchecks run in parallel |
+| `cost-diff` | PR-level snapshot delta — compares two cost-summary JSON outputs | "Did this PR add cost vs main?"; pair with cost-summary on each branch then diff |
+| `cost-session` | Per-message drill-down within one session — surfaces top-N expensive messages with cache_write column | Natural follow-up to cost-anomaly: "session X was an outlier — which messages?". Distinguishes cache-write costs from output-token costs (the silent killer) |
+| `cost-export` | Prometheus textfile + webhook POST | External observability dashboards |
+| `cost-federation` | ADR-097 Phase 3 consumer — per-peer 1h/24h/7d windows | After Phase 3 emits federation_spend events |
+| `cost-benchmark` | Run the corpus harness — booster + optional Gemini/Sonnet/Opus | Verifying speedup claims, regression check |
+| `cost-booster-route` | Wrap `hooks_route`, partition by `[AGENT_BOOSTER_AVAILABLE]` | Audit how many tasks would route to Tier 1 |
+| `cost-booster-edit` | Apply a Tier 1 transform via `agent-booster.apply()` | When a transform is already classified as Tier 1 |
+| `cost-compact-context` | Wrap `getTokenOptimizer().getCompactContext()` | Retrieval-augmented prompt compression |
+
+`cost track` populates the namespace; everything else consumes it. Run `cost-track` first or other skills will operate on empty data.
+
+## Tools (MCP-routed primary path)
+
+- `mcp__claude-flow__memory_store` — store usage records, budget config, optimization patterns (the `memory_*` family is namespace-routed; prefer this over `agentdb_hierarchical-*`)
+- `mcp__claude-flow__memory_search` / `memory_list` / `memory_retrieve` — read cost-tracking + cost-patterns namespaces
+- `mcp__claude-flow__memory_delete` — clean up stale config (used by budget upsert-via-timestamp pattern)
+- `mcp__claude-flow__hooks_route` — invoked by `cost-booster-route`
+- `mcp__claude-flow__hooks_model-outcome` — invoked by `cost-optimize` step 8 (auto-emits via `outcome.mjs`)
+- `mcp__claude-flow__hooks_worker-status` — `cost workers` subcommand (consumes `optimize` + `benchmark` worker outputs)
+- `mcp__claude-flow__agentdb_pattern-store` / `_pattern-search` — ReasoningBank-routed (no namespace arg) for typed cost-optimization patterns
+
+## Agent Booster (direct invocation, $0/edit, ~1 ms measured)
+
+When a recommendation is to *apply* a Tier 1 transform (not just classify it), prefer the `cost-booster-edit` skill which wraps `agent-booster.apply()` from `npm agent-booster` (exposed via `agentic-flow/agent-booster`). Per the measured benchmark in `docs/benchmarks/0002-baseline.md`, mean latency was 1.2 ms and the strategy was `exact_replace` for the higher-confidence cases (`add-error-handling`, `async-await`) and `fuzzy_replace` for fuzzier edits (`var-to-const`, `add-types`, `remove-console`). All five measured cases produced `success: true`.
+
+Invocation contract (from `node_modules/agent-booster/dist/index.d.ts`):
+```ts
+booster.apply({ code, edit, language }) → { output, success, latency, confidence, strategy, tokens }
+```
+
+`cost-booster-route` decides whether to route to Tier 1; `cost-booster-edit` performs the transform when so directed. Always check `confidence >= 0.5` before writing; below that, escalate to Tier 2/3 and record via `hooks_model-outcome`.
+
+## Memory
+
+Store cost patterns and optimization results for cross-session learning:
+```bash
+npx @claude-flow/cli@latest memory store --namespace cost-tracking --key "report-DATE" --value "REPORT_JSON"
+npx @claude-flow/cli@latest memory store --namespace cost-patterns --key "optimization-OPT_NAME" --value "OPTIMIZATION_RESULT_JSON"
+npx @claude-flow/cli@latest memory search --query "cost savings from model downgrades" --namespace cost-patterns
+```
+
+## Background workers
+
+This plugin is the declared consumer of two `ruflo-loop-workers` background workers (see [ruflo-loop-workers ADR-0001 §"12-worker trigger map"](../../ruflo-loop-workers/docs/adrs/0001-loop-workers-contract.md)):
+
+- **`optimize`** — periodically scans recent cost data and produces optimization recommendations. Consumed by the `cost-optimize` skill and surfaced via `cost workers` (see `commands/ruflo-cost.md`).
+- **`benchmark`** — runs cost-per-benchmark across spawned agents; results inform Tier 1/2/3 routing decisions reported in `cost-report`.
+
+Use `mcp__claude-flow__hooks_worker-status --worker optimize` and `--worker benchmark` to inspect last-run timestamps and outcomes. The worker scheduling itself is owned by `ruflo-loop-workers`; this plugin only consumes outputs.
+
+## Neural learning
+
+After generating cost reports or applying optimizations, feed the cost-optimization learning loop so future strategies compound:
+```bash
+npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true
+npx @claude-flow/cli@latest neural train --pattern-type cost-optimization --epochs 5
+```
+
+## Related plugins
+
+- **ruflo-intelligence**: Model routing optimization data feeds cost analysis (3-tier routing reduces cost 75%).
+- **ruflo-autopilot**: Budget-aware autopilot mode uses cost data to throttle agent spawns.
+- **ruflo-observability**: Token usage metrics collected via observability instrumentation.
+- **ruflo-swarm**: Agent spawn/stop decisions informed by budget remaining.
+- **ruflo-federation**: Federation budget circuit breaker (ADR-097) — federation_send `maxTokens` / `maxUsd` enforcement complements local cost tracking.

package/runtime/vendor/plugins/ruflo/ruflo-cost-tracker/bench/booster-corpus.json

@@ -0,0 +1,244 @@
+{
+  "version": 3,
+  "description": "Golden corpus for cost-tracker's Agent Booster verification. Two case classes — `expectedTier1: true` cases SHOULD apply via booster; `expectedTier1: false` cases SHOULD escalate (low confidence or output != expected) so the router/skill can route them to Tier 2/3.",
+  "normalize": "trim, collapse whitespace runs to single space",
+  "metrics": {
+    "winRateTier1": "correct / count(expectedTier1==true)",
+    "escalationRate": "(low-confidence OR incorrect) / count(expectedTier1==false)  -- a high escalation rate is the desired signal on adversarial cases",
+    "overallCorrect": "correct / total  -- diagnostic; not the gate"
+  },
+  "cases": [
+    {
+      "id": "var-to-const-1",
+      "intent": "var-to-const",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "var x = 1; var y = 2;",
+      "edit": "const x = 1; const y = 2;",
+      "expected": "const x = 1; const y = 2;"
+    },
+    {
+      "id": "var-to-const-2",
+      "intent": "var-to-const",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function go() { var n = compute(); return n + 1; }",
+      "edit": "function go() { const n = compute(); return n + 1; }",
+      "expected": "function go() { const n = compute(); return n + 1; }"
+    },
+    {
+      "id": "add-types-1",
+      "intent": "add-types",
+      "language": "typescript",
+      "expectedTier1": true,
+      "code": "function add(a, b) { return a + b; }",
+      "edit": "function add(a: number, b: number): number { return a + b; }",
+      "expected": "function add(a: number, b: number): number { return a + b; }"
+    },
+    {
+      "id": "add-types-2",
+      "intent": "add-types",
+      "language": "typescript",
+      "expectedTier1": true,
+      "code": "function name(p) { return p.first + ' ' + p.last; }",
+      "edit": "function name(p: { first: string; last: string }): string { return p.first + ' ' + p.last; }",
+      "expected": "function name(p: { first: string; last: string }): string { return p.first + ' ' + p.last; }"
+    },
+    {
+      "id": "remove-console-1",
+      "intent": "remove-console",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function go() { console.log(\"x\"); doWork(); }",
+      "edit": "function go() { doWork(); }",
+      "expected": "function go() { doWork(); }"
+    },
+    {
+      "id": "remove-console-2",
+      "intent": "remove-console",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function init() { console.log('start'); console.error('e'); run(); }",
+      "edit": "function init() { run(); }",
+      "expected": "function init() { run(); }"
+    },
+    {
+      "id": "add-error-handling-1",
+      "intent": "add-error-handling",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function fetch() { return api.get(); }",
+      "edit": "function fetch() { try { return api.get(); } catch (e) { return null; } }",
+      "expected": "function fetch() { try { return api.get(); } catch (e) { return null; } }"
+    },
+    {
+      "id": "add-error-handling-2",
+      "intent": "add-error-handling",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function load(p) { return parse(read(p)); }",
+      "edit": "function load(p) { try { return parse(read(p)); } catch (e) { return null; } }",
+      "expected": "function load(p) { try { return parse(read(p)); } catch (e) { return null; } }"
+    },
+    {
+      "id": "async-await-1",
+      "intent": "async-await",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function fetch() { return api.get().then(r => r.data); }",
+      "edit": "async function fetch() { const r = await api.get(); return r.data; }",
+      "expected": "async function fetch() { const r = await api.get(); return r.data; }"
+    },
+    {
+      "id": "async-await-2",
+      "intent": "async-await",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function load() { return read().then(parse); }",
+      "edit": "async function load() { const r = await read(); return parse(r); }",
+      "expected": "async function load() { const r = await read(); return parse(r); }"
+    },
+    {
+      "id": "add-logging-1",
+      "intent": "add-logging",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function go() { return work(); }",
+      "edit": "function go() { console.log('go'); return work(); }",
+      "expected": "function go() { console.log('go'); return work(); }"
+    },
+    {
+      "id": "add-logging-2",
+      "intent": "add-logging",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function save(x) { db.put(x); }",
+      "edit": "function save(x) { console.log('save', x); db.put(x); }",
+      "expected": "function save(x) { console.log('save', x); db.put(x); }"
+    },
+    {
+      "id": "adversarial-extract-function",
+      "intent": "extract-function",
+      "language": "javascript",
+      "expectedTier1": false,
+      "comment": "Multi-statement extraction — booster's pattern-replace can't reason about control-flow boundaries. LLM should escalate.",
+      "code": "function process(items) { let total = 0; for (const i of items) { if (i.active) { total += i.value; } } if (total > 100) { console.log('big'); } else { console.log('small'); } return total; }",
+      "edit": "Extract the per-item summation into a helper called `sum_active(items)`, and the threshold-log into `log_threshold(total)`. Update process() to call them.",
+      "expected": "function sum_active(items) { let total = 0; for (const i of items) { if (i.active) { total += i.value; } } return total; } function log_threshold(total) { if (total > 100) { console.log('big'); } else { console.log('small'); } } function process(items) { const total = sum_active(items); log_threshold(total); return total; }"
+    },
+    {
+      "id": "adversarial-type-narrowing",
+      "intent": "type-narrowing",
+      "language": "typescript",
+      "expectedTier1": false,
+      "comment": "Requires understanding union types + control flow. Booster pattern-replace will likely fail or produce a low-confidence merge.",
+      "code": "type Result = { kind: 'ok'; value: number } | { kind: 'err'; message: string }; function describe(r: Result) { return r.value; }",
+      "edit": "Narrow `r` before accessing `value` — only return `r.value` when `r.kind === 'ok'`, otherwise return -1.",
+      "expected": "type Result = { kind: 'ok'; value: number } | { kind: 'err'; message: string }; function describe(r: Result) { if (r.kind === 'ok') { return r.value; } return -1; }"
+    },
+    {
+      "id": "adversarial-cross-method-rename",
+      "intent": "rename-symbol",
+      "language": "typescript",
+      "expectedTier1": false,
+      "comment": "Renaming requires reasoning about ALL call sites; booster sees only the snippet boundary.",
+      "code": "class Cache { get(k: string) { return this.store[k]; } set(k: string, v: any) { this.store[k] = v; } private store: Record<string, any> = {}; } const c = new Cache(); c.set('a', 1); console.log(c.get('a'));",
+      "edit": "Rename Cache.get to Cache.lookup and update all call sites.",
+      "expected": "class Cache { lookup(k: string) { return this.store[k]; } set(k: string, v: any) { this.store[k] = v; } private store: Record<string, any> = {}; } const c = new Cache(); c.set('a', 1); console.log(c.lookup('a'));"
+    },
+    {
+      "id": "adversarial-recursive-rewrite",
+      "intent": "recursive-to-iterative",
+      "language": "javascript",
+      "expectedTier1": false,
+      "comment": "Algorithmic transformation — requires reasoning, not pattern replacement.",
+      "code": "function factorial(n) { return n <= 1 ? 1 : n * factorial(n - 1); }",
+      "edit": "Rewrite as an iterative loop with no recursion.",
+      "expected": "function factorial(n) { let result = 1; for (let i = 2; i <= n; i++) { result *= i; } return result; }"
+    },
+    {
+      "id": "var-to-let-1",
+      "intent": "var-to-let",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "var i = 0; for (i = 0; i < 10; i++) { sink(i); }",
+      "edit": "let i = 0; for (i = 0; i < 10; i++) { sink(i); }",
+      "expected": "let i = 0; for (i = 0; i < 10; i++) { sink(i); }"
+    },
+    {
+      "id": "double-quote-to-single",
+      "intent": "string-quote-style",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function greet(name) { return \"hello \" + name; }",
+      "edit": "function greet(name) { return 'hello ' + name; }",
+      "expected": "function greet(name) { return 'hello ' + name; }"
+    },
+    {
+      "id": "add-readonly-prop",
+      "intent": "add-readonly",
+      "language": "typescript",
+      "expectedTier1": true,
+      "code": "class Box { value: number = 0; }",
+      "edit": "class Box { readonly value: number = 0; }",
+      "expected": "class Box { readonly value: number = 0; }"
+    },
+    {
+      "id": "remove-debugger",
+      "intent": "remove-debug",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "function go() { debugger; doWork(); }",
+      "edit": "function go() { doWork(); }",
+      "expected": "function go() { doWork(); }"
+    },
+    {
+      "id": "import-add-named",
+      "intent": "import-add",
+      "language": "typescript",
+      "expectedTier1": true,
+      "code": "import { foo } from './x'; foo();",
+      "edit": "import { foo, bar } from './x'; foo();",
+      "expected": "import { foo, bar } from './x'; foo();"
+    },
+    {
+      "id": "remove-trailing-semis",
+      "intent": "format-tweak",
+      "language": "javascript",
+      "expectedTier1": true,
+      "code": "const a = 1;; const b = 2;;",
+      "edit": "const a = 1; const b = 2;",
+      "expected": "const a = 1; const b = 2;"
+    },
+    {
+      "id": "adversarial-extract-class",
+      "intent": "extract-class",
+      "language": "typescript",
+      "expectedTier1": false,
+      "comment": "Splitting one class into two with delegation requires reasoning about responsibility boundaries.",
+      "code": "class UserService { saveUser(u: any) { db.put(u); audit.log('save', u.id); } private db = realDb; private audit = { log: (k: string, v: any) => console.log(k, v) }; }",
+      "edit": "Extract the `audit` concern into its own AuditService class and have UserService delegate to it.",
+      "expected": "class AuditService { log(k: string, v: any) { console.log(k, v); } } class UserService { saveUser(u: any) { db.put(u); this.audit.log('save', u.id); } private db = realDb; private audit = new AuditService(); }"
+    },
+    {
+      "id": "adversarial-callback-to-promise",
+      "intent": "callback-to-promise",
+      "language": "javascript",
+      "expectedTier1": false,
+      "comment": "Restructuring control flow from callbacks to async/await requires understanding execution semantics, not pattern matching.",
+      "code": "function loadConfig(cb) { fs.readFile('./c.json', (err, data) => { if (err) cb(err); else cb(null, JSON.parse(data)); }); }",
+      "edit": "Rewrite as an async function that returns a Promise<Config> using fs.promises and try/catch.",
+      "expected": "async function loadConfig() { try { const data = await fs.promises.readFile('./c.json'); return JSON.parse(data); } catch (err) { throw err; } }"
+    },
+    {
+      "id": "adversarial-deeply-nested-conditional",
+      "intent": "early-return-flatten",
+      "language": "javascript",
+      "expectedTier1": false,
+      "comment": "Flattening nested conditionals into guard clauses requires reasoning about boolean logic + control flow.",
+      "code": "function process(x) { if (x) { if (x.valid) { if (x.size > 0) { return doWork(x); } else { return null; } } else { return null; } } else { return null; } }",
+      "edit": "Flatten using early returns / guard clauses — return null at each failed precondition.",
+      "expected": "function process(x) { if (!x) return null; if (!x.valid) return null; if (x.size <= 0) return null; return doWork(x); }"
+    }
+  ]
+}