claude-flow 3.7.0-alpha.3 → 3.7.0-alpha.30

package/.claude/skills/verification-quality/SKILL.md

@@ -17,26 +17,70 @@ This skill provides a comprehensive verification and quality assurance system th
 - **CI/CD Integration**: Export capabilities for continuous integration pipelines
 - **Real-time Monitoring**: Live dashboards and watch modes for ongoing verification
 
+> **Shipped vs. aspirational.** The *concrete, in-CI* verification stack — the 6 regression-guard jobs + the witness manifest + the tool-discoverability audit — is real and runs on every push. The truth-scoring / auto-rollback / WebSocket-dashboard surface described later in this doc is partly shipped (`ruflo verify` runs the witness checks) and partly design — treat the "CI Guards" section below as the authoritative current state.
+
+## CI Guards — what's actually shipped (current state)
+
+Ruflo's regression protection is three layers, all gated before publish. Authoritative reference: [`verification/README.md`](../../../verification/README.md).
+
+| Layer | What | CI job(s) in `.github/workflows/v3-ci.yml` | ADR |
+|---|---|---|---|
+| **1 — install/behavioral smoke** | Exercise user-visible failure modes against a real build | `smoke-install-no-bsqlite` (npm install on platforms w/o prebuilds), `plugin-hooks-smoke` (#1859/#1862 — hook flag parsing), `mcp-protocol-smoke` (#1874 — HTTP MCP wire format), `memory-import-smoke` (#1883/#1884 — WSL path + key sanitization), `mcp-roundtrip-smoke` (#1889 paired-tool round-trip + #1863 cli-no-crash + ADR-095 G2 consensus-transport) | ADR-102 |
+| **1 — discoverability gate** | Every MCP tool description must answer "use this over native when?" | `tool-descriptions-audit` — `scripts/audit-tool-descriptions.mjs`, baseline at `verification/mcp-tool-baseline.json` (monotone-decreasing: noGuidance / tooShort / duplicates) | ADR-112 |
+| **2 — cryptographic witness** | Every documented fix's load-bearing marker must still be present in dist; Ed25519-signed, per-OS bundles | `witness-verify` (ubuntu/macos/windows) — `plugins/ruflo-core/scripts/witness/verify.mjs` against `verification/<os>/manifest.md.json` | ADR-103 |
+| **3 — temporal history** | When was a regression introduced | `verification/<os>/history.jsonl` + `history.mjs` (`summary` / `regressions` / `timeline`) | ADR-103 |
+
+### Run the guards locally
+
+```bash
+# Tool-description discoverability audit (ADR-112)
+node scripts/audit-tool-descriptions.mjs                       # fails if any baseline count rises
+node scripts/audit-tool-descriptions.mjs --update-baseline     # lock the new floor after a fix lands
+
+# Behavioral smokes (each builds what it needs; safe to run individually)
+node plugins/ruflo-core/scripts/test-hooks.mjs "node $PWD/v3/@claude-flow/cli/bin/cli.js"
+node plugins/ruflo-core/scripts/test-mcp-protocol.mjs
+node plugins/ruflo-core/scripts/test-memory-import.mjs
+node plugins/ruflo-core/scripts/test-mcp-roundtrips.mjs        # #1889 paired-tool round-trip
+node plugins/ruflo-core/scripts/test-cli-no-crash.mjs          # #1863 unhandled-exception class
+node plugins/ruflo-core/scripts/test-consensus-transport.mjs   # ADR-095 G2 consensus transport
+
+# Witness manifest — regenerate + verify
+node scripts/regen-witness.mjs
+node plugins/ruflo-core/scripts/witness/verify.mjs --manifest verification/macos/manifest.md.json
+
+# Temporal history
+node plugins/ruflo-core/scripts/witness/history.mjs --history verification/macos/history.jsonl summary
+node plugins/ruflo-core/scripts/witness/history.mjs --history verification/macos/history.jsonl regressions
+```
+
+### Adding a new guard
+
+1. **Behavioral smoke** → write `plugins/ruflo-core/scripts/test-<name>.mjs`. Pattern: static dist-scan first (fast, always completes), behavioral probe second with an internal timeout + a process-level watchdog so CI never hangs. Add a step to the relevant job in `v3-ci.yml`.
+2. **Static gate with a baseline** → write `scripts/audit-<name>.mjs` that scans, counts violations, and fails if the count exceeds a monotone-decreasing baseline in `verification/<name>-baseline.json`. Support `--update-baseline`. Add a CI job; wire it into `witness-verify` `needs[]` if it should gate `publish`.
+3. **Documented-fix marker** → append `{ id, desc, file, marker }` to `verification/witness-fixes.json`, run `node scripts/regen-witness.mjs`. The marker must be a substring the fix specifically creates (not a generic pattern like `'function'`).
+
 ## Prerequisites
 
-- Claude Flow installed (`npx claude-flow@alpha`)
+- Ruflo installed (`npx ruflo@alpha`)
 - Git repository (for rollback features)
 - Node.js 18+ (for dashboard features)
+- `@noble/ed25519` (for the witness verifier — a single runtime dep, `npm i @noble/ed25519`)
 
 ## Quick Start
 
 ```bash
 # View current truth scores
-npx claude-flow@alpha truth
+npx ruflo@alpha truth
 
 # Run verification check
-npx claude-flow@alpha verify check
+npx ruflo@alpha verify check
 
 # Verify specific file with custom threshold
-npx claude-flow@alpha verify check --file src/app.js --threshold 0.98
+npx ruflo@alpha verify check --file src/app.js --threshold 0.98
 
 # Rollback last failed verification
-npx claude-flow@alpha verify rollback --last-good
+npx ruflo@alpha verify rollback --last-good
 ```
 
 ---
@@ -52,40 +96,40 @@ Display comprehensive quality and reliability metrics for your codebase and agen
 **Basic Usage:**
 ```bash
 # View current truth scores (default: table format)
-npx claude-flow@alpha truth
+npx ruflo@alpha truth
 
 # View scores for specific time period
-npx claude-flow@alpha truth --period 7d
+npx ruflo@alpha truth --period 7d
 
 # View scores for specific agent
-npx claude-flow@alpha truth --agent coder --period 24h
+npx ruflo@alpha truth --agent coder --period 24h
 
 # Find files/tasks below threshold
-npx claude-flow@alpha truth --threshold 0.8
+npx ruflo@alpha truth --threshold 0.8
 ```
 
 **Output Formats:**
 ```bash
 # Table format (default)
-npx claude-flow@alpha truth --format table
+npx ruflo@alpha truth --format table
 
 # JSON for programmatic access
-npx claude-flow@alpha truth --format json
+npx ruflo@alpha truth --format json
 
 # CSV for spreadsheet analysis
-npx claude-flow@alpha truth --format csv
+npx ruflo@alpha truth --format csv
 
 # HTML report with visualizations
-npx claude-flow@alpha truth --format html --export report.html
+npx ruflo@alpha truth --format html --export report.html
 ```
 
 **Real-time Monitoring:**
 ```bash
 # Watch mode with live updates
-npx claude-flow@alpha truth --watch
+npx ruflo@alpha truth --watch
 
 # Export metrics automatically
-npx claude-flow@alpha truth --export .claude-flow/metrics/truth-$(date +%Y%m%d).json
+npx ruflo@alpha truth --export .claude-flow/metrics/truth-$(date +%Y%m%d).json
 ```
 
 #### Truth Score Dashboard
@@ -141,40 +185,40 @@ Execute comprehensive verification checks on code, tasks, or agent outputs.
 **File Verification:**
 ```bash
 # Verify single file
-npx claude-flow@alpha verify check --file src/app.js
+npx ruflo@alpha verify check --file src/app.js
 
 # Verify directory recursively
-npx claude-flow@alpha verify check --directory src/
+npx ruflo@alpha verify check --directory src/
 
 # Verify with auto-fix enabled
-npx claude-flow@alpha verify check --file src/utils.js --auto-fix
+npx ruflo@alpha verify check --file src/utils.js --auto-fix
 
 # Verify current working directory
-npx claude-flow@alpha verify check
+npx ruflo@alpha verify check
 ```
 
 **Task Verification:**
 ```bash
 # Verify specific task output
-npx claude-flow@alpha verify check --task task-123
+npx ruflo@alpha verify check --task task-123
 
 # Verify with custom threshold
-npx claude-flow@alpha verify check --task task-456 --threshold 0.99
+npx ruflo@alpha verify check --task task-456 --threshold 0.99
 
 # Verbose output for debugging
-npx claude-flow@alpha verify check --task task-789 --verbose
+npx ruflo@alpha verify check --task task-789 --verbose
 ```
 
 **Batch Verification:**
 ```bash
 # Verify multiple files in parallel
-npx claude-flow@alpha verify batch --files "*.js" --parallel
+npx ruflo@alpha verify batch --files "*.js" --parallel
 
 # Verify with pattern matching
-npx claude-flow@alpha verify batch --pattern "src/**/*.ts"
+npx ruflo@alpha verify batch --pattern "src/**/*.ts"
 
 # Integration test suite
-npx claude-flow@alpha verify integration --test-suite full
+npx ruflo@alpha verify integration --test-suite full
 ```
 
 #### Verification Criteria
@@ -215,7 +259,7 @@ The verification system evaluates:
 
 ```bash
 # Get structured JSON output
-npx claude-flow@alpha verify check --json > verification.json
+npx ruflo@alpha verify check --json > verification.json
 
 # Example JSON structure:
 {
@@ -247,25 +291,25 @@ Automatically revert changes that fail verification checks.
 **Basic Rollback:**
 ```bash
 # Rollback to last known good state
-npx claude-flow@alpha verify rollback --last-good
+npx ruflo@alpha verify rollback --last-good
 
 # Rollback to specific commit
-npx claude-flow@alpha verify rollback --to-commit abc123
+npx ruflo@alpha verify rollback --to-commit abc123
 
 # Interactive rollback with preview
-npx claude-flow@alpha verify rollback --interactive
+npx ruflo@alpha verify rollback --interactive
 ```
 
 **Smart Rollback:**
 ```bash
 # Rollback only failed files (preserve good changes)
-npx claude-flow@alpha verify rollback --selective
+npx ruflo@alpha verify rollback --selective
 
 # Rollback with automatic backup
-npx claude-flow@alpha verify rollback --backup-first
+npx ruflo@alpha verify rollback --backup-first
 
 # Dry-run mode (preview without executing)
-npx claude-flow@alpha verify rollback --dry-run
+npx ruflo@alpha verify rollback --dry-run
 ```
 
 **Rollback Performance:**
@@ -282,31 +326,31 @@ Create detailed verification reports with metrics and visualizations.
 **Report Formats:**
 ```bash
 # JSON report
-npx claude-flow@alpha verify report --format json
+npx ruflo@alpha verify report --format json
 
 # HTML report with charts
-npx claude-flow@alpha verify report --export metrics.html --format html
+npx ruflo@alpha verify report --export metrics.html --format html
 
 # CSV for data analysis
-npx claude-flow@alpha verify report --format csv --export metrics.csv
+npx ruflo@alpha verify report --format csv --export metrics.csv
 
 # Markdown summary
-npx claude-flow@alpha verify report --format markdown
+npx ruflo@alpha verify report --format markdown
 ```
 
 **Time-based Reports:**
 ```bash
 # Last 24 hours
-npx claude-flow@alpha verify report --period 24h
+npx ruflo@alpha verify report --period 24h
 
 # Last 7 days
-npx claude-flow@alpha verify report --period 7d
+npx ruflo@alpha verify report --period 7d
 
 # Last 30 days with trends
-npx claude-flow@alpha verify report --period 30d --include-trends
+npx ruflo@alpha verify report --period 30d --include-trends
 
 # Custom date range
-npx claude-flow@alpha verify report --from 2025-01-01 --to 2025-01-31
+npx ruflo@alpha verify report --from 2025-01-01 --to 2025-01-31
 ```
 
 **Report Content:**
@@ -326,16 +370,16 @@ Run interactive web-based verification dashboard with real-time updates.
 
 ```bash
 # Launch dashboard on default port (3000)
-npx claude-flow@alpha verify dashboard
+npx ruflo@alpha verify dashboard
 
 # Custom port
-npx claude-flow@alpha verify dashboard --port 8080
+npx ruflo@alpha verify dashboard --port 8080
 
 # Export dashboard data
-npx claude-flow@alpha verify dashboard --export
+npx ruflo@alpha verify dashboard --export
 
 # Dashboard with auto-refresh
-npx claude-flow@alpha verify dashboard --refresh 5s
+npx ruflo@alpha verify dashboard --refresh 5s
 ```
 
 **Dashboard Features:**
@@ -390,13 +434,13 @@ Set verification preferences in `.claude-flow/config.json`:
 **Adjust verification strictness:**
 ```bash
 # Strict mode (99% accuracy required)
-npx claude-flow@alpha verify check --threshold 0.99
+npx ruflo@alpha verify check --threshold 0.99
 
 # Lenient mode (90% acceptable)
-npx claude-flow@alpha verify check --threshold 0.90
+npx ruflo@alpha verify check --threshold 0.90
 
 # Set default threshold
-npx claude-flow@alpha config set verification.threshold 0.98
+npx ruflo@alpha config set verification.threshold 0.98
 ```
 
 **Per-environment thresholds:**
@@ -433,7 +477,7 @@ jobs:
 
       - name: Run Verification
         run: |
-          npx claude-flow@alpha verify check --json > verification.json
+          npx ruflo@alpha verify check --json > verification.json
 
       - name: Check Truth Score
         run: |
@@ -455,7 +499,7 @@ jobs:
 verify:
   stage: test
   script:
-    - npx claude-flow@alpha verify check --threshold 0.95 --json > verification.json
+    - npx ruflo@alpha verify check --threshold 0.95 --json > verification.json
     - |
       score=$(jq '.overallScore' verification.json)
       if [ $(echo "$score < 0.95" | bc) -eq 1 ]; then
@@ -475,13 +519,13 @@ Run verification automatically during swarm operations:
 
 ```bash
 # Swarm with verification enabled
-npx claude-flow@alpha swarm --verify --threshold 0.98
+npx ruflo@alpha swarm --verify --threshold 0.98
 
 # Hive Mind with auto-rollback
-npx claude-flow@alpha hive-mind --verify --rollback-on-fail
+npx ruflo@alpha hive-mind --verify --rollback-on-fail
 
 # Training pipeline with verification
-npx claude-flow@alpha train --verify --threshold 0.99
+npx ruflo@alpha train --verify --threshold 0.99
 ```
 
 #### Pair Programming Integration
@@ -490,10 +534,10 @@ Enable real-time verification during collaborative development:
 
 ```bash
 # Pair with verification
-npx claude-flow@alpha pair --verify --real-time
+npx ruflo@alpha pair --verify --real-time
 
 # Pair with custom threshold
-npx claude-flow@alpha pair --verify --threshold 0.97 --auto-fix
+npx ruflo@alpha pair --verify --threshold 0.97 --auto-fix
 ```
 
 ### Advanced Workflows
@@ -504,13 +548,13 @@ Monitor codebase continuously during development:
 
 ```bash
 # Watch directory for changes
-npx claude-flow@alpha verify watch --directory src/
+npx ruflo@alpha verify watch --directory src/
 
 # Watch with auto-fix
-npx claude-flow@alpha verify watch --directory src/ --auto-fix
+npx ruflo@alpha verify watch --directory src/ --auto-fix
 
 # Watch with notifications
-npx claude-flow@alpha verify watch --notify --threshold 0.95
+npx ruflo@alpha verify watch --notify --threshold 0.95
 ```
 
 #### Monitoring Integration
@@ -519,18 +563,18 @@ Send metrics to external monitoring systems:
 
 ```bash
 # Export to Prometheus
-npx claude-flow@alpha truth --format json | \
+npx ruflo@alpha truth --format json | \
   curl -X POST https://pushgateway.example.com/metrics/job/claude-flow \
   -d @-
 
 # Send to DataDog
-npx claude-flow@alpha verify report --format json | \
+npx ruflo@alpha verify report --format json | \
   curl -X POST "https://api.datadoghq.com/api/v1/series?api_key=${DD_API_KEY}" \
   -H "Content-Type: application/json" \
   -d @-
 
 # Custom webhook
-npx claude-flow@alpha truth --format json | \
+npx ruflo@alpha truth --format json | \
   curl -X POST https://metrics.example.com/api/truth \
   -H "Content-Type: application/json" \
   -d @-
@@ -542,16 +586,16 @@ Automatically verify before commits:
 
 ```bash
 # Install pre-commit hook
-npx claude-flow@alpha verify install-hook --pre-commit
+npx ruflo@alpha verify install-hook --pre-commit
 
 # .git/hooks/pre-commit example:
 #!/bin/bash
-npx claude-flow@alpha verify check --threshold 0.95 --json > /tmp/verify.json
+npx ruflo@alpha verify check --threshold 0.95 --json > /tmp/verify.json
 
 score=$(jq '.overallScore' /tmp/verify.json)
 if (( $(echo "$score < 0.95" | bc -l) )); then
   echo "❌ Verification failed with score: $score"
-  echo "Run 'npx claude-flow@alpha verify check --verbose' for details"
+  echo "Run 'npx ruflo@alpha verify check --verbose' for details"
   exit 1
 fi
 
@@ -583,13 +627,13 @@ echo "✅ Verification passed with score: $score"
 **Low Truth Scores:**
 ```bash
 # Get detailed breakdown
-npx claude-flow@alpha truth --verbose --threshold 0.0
+npx ruflo@alpha truth --verbose --threshold 0.0
 
 # Check specific criteria
-npx claude-flow@alpha verify check --verbose
+npx ruflo@alpha verify check --verbose
 
 # View agent-specific issues
-npx claude-flow@alpha truth --agent <agent-name> --format json
+npx ruflo@alpha truth --agent <agent-name> --format json
 ```
 
 **Rollback Failures:**
@@ -598,7 +642,7 @@ npx claude-flow@alpha truth --agent <agent-name> --format json
 git status
 
 # View rollback history
-npx claude-flow@alpha verify rollback --history
+npx ruflo@alpha verify rollback --history
 
 # Manual rollback
 git reset --hard HEAD~1
@@ -607,10 +651,10 @@ git reset --hard HEAD~1
 **Verification Timeouts:**
 ```bash
 # Increase timeout
-npx claude-flow@alpha verify check --timeout 60s
+npx ruflo@alpha verify check --timeout 60s
 
 # Verify in batches
-npx claude-flow@alpha verify batch --batch-size 10
+npx ruflo@alpha verify batch --batch-size 10
 ```
 
 ### Exit Codes
@@ -623,10 +667,10 @@ Verification commands return standard exit codes:
 
 ### Related Commands
 
-- `npx claude-flow@alpha pair` - Collaborative development with verification
-- `npx claude-flow@alpha train` - Training with verification feedback
-- `npx claude-flow@alpha swarm` - Multi-agent coordination with quality checks
-- `npx claude-flow@alpha report` - Generate comprehensive project reports
+- `npx ruflo@alpha pair` - Collaborative development with verification
+- `npx ruflo@alpha train` - Training with verification feedback
+- `npx ruflo@alpha swarm` - Multi-agent coordination with quality checks
+- `npx ruflo@alpha report` - Generate comprehensive project reports
 
 ### Best Practices
 

package/.claude-plugin/hooks/hooks.json

@@ -1,4 +1,5 @@
 {
+  "_note": "#1921 — hook commands invoke scripts/ruflo-hook.sh (resilient shim): prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and always exits 0 so a CLI/install failure (e.g. arborist `Invalid Version` on npm 10.8.x) never surfaces an error in Claude Code or blocks a turn. The trailing `|| true` guards the case where $CLAUDE_PLUGIN_ROOT is unset (older Claude Code) — the hook then no-ops silently. DO NOT revert to a bare `npx <pkg>@alpha hooks …` per fire.",
   "hooks": {
     "PreToolUse": [
       {
@@ -6,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cat | npx claude-flow@alpha hooks modify-bash"
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" modify-bash || true"
           }
         ]
       },
@@ -15,7 +16,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cat | npx claude-flow@alpha hooks modify-file"
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" modify-file || true"
           }
         ]
       }
@@ -26,7 +27,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cat | jq -r '.tool_input.command // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks post-command --command '{}' --track-metrics true --store-results true"
+            "command": "cat | jq -r '.tool_input.command // empty' | tr '\\n' '\\0' | xargs -0 -I {} \"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" post-command --command '{}' --track-metrics true --store-results true || true"
           }
         ]
       },
@@ -35,7 +36,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "cat | jq -r '.tool_input.file_path // .tool_input.path // empty' | tr '\\n' '\\0' | xargs -0 -I {} npx claude-flow@alpha hooks post-edit --file '{}' --format true --update-memory true"
+            "command": "cat | jq -r '.tool_input.file_path // .tool_input.path // empty' | tr '\\n' '\\0' | xargs -0 -I {} \"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" post-edit --file '{}' --format true --update-memory true || true"
           }
         ]
       }
@@ -65,7 +66,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "npx claude-flow@alpha hooks session-end --generate-summary true --persist-state true --export-metrics true"
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/scripts/ruflo-hook.sh\" session-end --generate-summary true --persist-state true --export-metrics true || true"
           }
         ]
       }

package/.claude-plugin/marketplace.json

@@ -72,9 +72,9 @@
       "description": "Advanced git workflows with diff analysis, risk scoring, and reviewer recommendations"
     },
     {
-      "name": "ruflo-wasm",
-      "source": "./plugins/ruflo-wasm",
-      "description": "Sandboxed WASM agent creation, execution, and gallery sharing"
+      "name": "ruflo-agent",
+      "source": "./plugins/ruflo-agent",
+      "description": "Agent runtimes — local WASM-sandboxed agents (rvagent) + Anthropic Claude Managed Agents (cloud); one interface, local-vs-cloud backends"
     },
     {
       "name": "ruflo-workflows",

package/.claude-plugin/scripts/ruflo-hook.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# ruflo-hook.sh — resilient invoker for ruflo CLI hook subcommands (#1921).
+#
+# Hooks fire on EVERY PreToolUse / PostToolUse / Stop. A bare
+# `npx <pkg>@alpha hooks …` re-resolves the @alpha dist-tag and re-installs
+# from cold cache on every fire, and when the install crashes (e.g. an
+# arborist `Invalid Version` on npm 10.8.x) the user sees a hook error in
+# Claude Code after every turn. This shim:
+#   1. prefers an already-installed `ruflo` / `claude-flow` binary (no npx,
+#      no install) — the common case for plugin users;
+#   2. falls back to `npx --prefer-offline` so a populated npx cache is
+#      reused instead of a fresh registry resolve;
+#   3. ALWAYS exits 0 — hook subcommands are best-effort telemetry/learning;
+#      a failure must never surface an error or block a turn.
+#
+# stdin (the hook event JSON) is passed through to the CLI unchanged.
+# Usage: ruflo-hook.sh <hook-subcommand> [args…]   (the literal `hooks`
+# word is prepended here, so callers pass e.g. `post-edit -f "$FILE" -s true`).
+
+# Swallow all diagnostics — nothing this script prints should reach Claude Code.
+exec 2>/dev/null
+
+run() { "$@" || true; }
+
+if command -v ruflo >/dev/null 2>&1; then
+  run ruflo hooks "$@"
+elif command -v claude-flow >/dev/null 2>&1; then
+  run claude-flow hooks "$@"
+else
+  run npx --prefer-offline --yes ruflo@alpha hooks "$@"
+fi
+
+exit 0