π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs: ADR-102 + bump packages to 3.7.0-alpha.18 (published)
Reuven8709c8dd5b79
diff --git a/package.json b/package.jsonindex 6c8668a945..a3c9dd7b0e 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "claude-flow",- "version": "3.7.0-alpha.17",+ "version": "3.7.0-alpha.18","description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration","main": "dist/index.js","type": "module",diff --git a/ruflo/package.json b/ruflo/package.jsonindex bf329705de..d6e500fd1a 100644--- a/ruflo/package.json+++ b/ruflo/package.json@@ -1,6 +1,6 @@{"name": "ruflo",- "version": "3.7.0-alpha.17",+ "version": "3.7.0-alpha.18","description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration","main": "bin/ruflo.js","type": "module",diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.jsonindex 0e37dbcfac..5019991bae 100644--- a/v3/@claude-flow/cli/package.json+++ b/v3/@claude-flow/cli/package.json@@ -1,6 +1,6 @@{"name": "@claude-flow/cli",- "version": "3.7.0-alpha.17",+ "version": "3.7.0-alpha.18","type": "module","description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code","main": "dist/src/index.js",diff --git a/v3/docs/adr/ADR-102-plugin-hook-cli-flag-regression-ci-guard.md b/v3/docs/adr/ADR-102-plugin-hook-cli-flag-regression-ci-guard.mdnew file mode 100644index 0000000000..65b5925374--- /dev/null+++ b/v3/docs/adr/ADR-102-plugin-hook-cli-flag-regression-ci-guard.md@@ -0,0 +1,182 @@+# ADR-102: CI Smoke Harness for Plugin Hook + CLI Flag Regressions++**Status**: Accepted+**Date**: 2026-05-08+**Version**: v3.7.0-alpha.17 β v3.7.0-alpha.18+**Related**: #1859, #1862, #1867, ADR-100 (cli-core split)++## Context++Two issues filed within ~30 minutes on 2026-05-08 (#1859, #1862) and one filed ~5 hours later (#1867) all had the same shape: a regression that affected every Claude Code session using ruflo, shipped to users via `latest` and `alpha` dist-tags, and was *not* reproducible by any test in the existing suite β because no test exercised the user-visible invocation path.++The existing `v3-ci.yml` ran `pnpm test` (vitest unit tests in workspace context) and `pnpm typecheck`. Both passed for the broken builds because:++- `@claude-flow/memory` had a static `import 'better-sqlite3'` whose evaluation succeeded under the test runner's Node 20 + `pnpm install` (prebuilds present). It would only fail when a user ran `npm install` on Node 26 (no prebuilds) β which CI never did.+- `@claude-flow/cli` had a `ctx.args[0] || ctx.flags.X` priority anti-pattern in 14 hook handlers. No test exercised these handlers as a subprocess with both `--flag` and a value-shaped boolean (e.g. `--success true`) on the command line, so the parser's stray-positional behaviour was invisible.+- `plugins/ruflo-core/hooks/hooks.json` called CLI flags that didn't exist (`--format true`, `--update-memory true`, `--track-metrics true`, `--store-results true`). Every Write/Edit/Bash tool use crashed with `[ERROR] Invalid value for --format: true` once Claude Code fired the hook β but no test in the repo *invoked* `hooks.json` against the CLI with realistic stdin.++The common thread is a CI gap, not a coding gap. Each fix was small (~20 LOC) once the root cause was found; the cost was entirely in the user-visible failure window.++## Bugs Covered++### Bug 1 β Plugin hooks called non-existent CLI flags (#1862)++**Symptom**: Every `PostToolUse:Write` (and `Edit`, `MultiEdit`) hook fired by Claude Code printed:++```+PostToolUse:Write hook error+[ERROR] Invalid value for --format: true. Must be one of: text, json, table+```++**Root cause**: `plugins/ruflo-core/hooks/hooks.json` line 38 invoked `npx claude-flow@alpha hooks post-edit --file <path> --format true --update-memory true`. The CLI has a *global* `--format` option restricted to `text|json|table` β the parser rejected `true` before any handler ran. `--update-memory` is also not a real flag.++The Bash hook (line 29) had the equivalent issue: `--track-metrics true --store-results true` are also not real flags.++**Fix**: `plugins/ruflo-core/hooks/hooks.json` rewritten to call only the documented flags (`-f`/`-s` for post-edit, `-c`/`-s`/`-e` for post-command). Required republishing `[email protected]`.++### Bug 2 β CLI parser preferred stray positionals over named flags (#1859 part A)++**Symptom**: `claude-flow hooks post-edit --file src/foo.ts --success true` recorded `"true"` as the file path:++```+[INFO] Recording outcome for: true+[OK] Outcome recorded for true+```++**Root cause**: `v3/@claude-flow/cli/src/commands/hooks.ts` resolved the primary value with the same anti-pattern across **14 handlers**:++```ts+const filePath = ctx.args[0] || ctx.flags.file as string || 'unknown';+```++Because `--success` is declared as `type: 'boolean'`, the parser doesn't consume the next token as its value. Writing `--success true` (the form documented in the CLI's *own* help examples) leaves the literal string `"true"` in `ctx.args[0]`, which then beats the named flag.++**Fix**: Bulk regex swap of all 14 sites:++```ts+const filePath = (ctx.flags.file as string) || ctx.args[0] || 'unknown';+```++Backward-compatible: legacy positional-only callers (`hooks post-edit src/foo.ts`) still work because the positional is the fallback. The flag now wins when both are set, which matches user expectation.++### Bug 3 β Bash hook mangled multi-line commands (#1859 part B)++**Symptom**: When Claude Code ran a heredoc Bash command, the hook errored with:++```+[ERROR] Required option missing: --command+```++**Root cause**: The hook used `cat | jq -r '.tool_input.command' | tr '\n' '\0' | xargs -0 -I {} npx ...`. The `tr '\n' '\0'` converted real newlines (jq -r's unescaped output) into null delimiters, and `xargs -0 -I {}` split the multi-line command into multiple null-delimited records β invoking the CLI multiple times, sometimes with empty `--command ''` arguments that the CLI rejected.++**Fix**: Replaced with a `bash -c` wrapper that reads stdin once, extracts via jq into env vars, and invokes the CLI exactly once with the multi-line command quoted:++```json+"command": "/bin/bash -c 'INPUT=$(cat); CMD=$(printf %s \"$INPUT\" | jq -r \".tool_input.command // empty\"); [ -z \"$CMD\" ] && exit 0; EXIT=$(printf %s \"$INPUT\" | jq -r \".tool_response.exit_code // 0\"); SUCCESS=$([ \"$EXIT\" = \"0\" ] && echo true || echo false); npx claude-flow@alpha hooks post-command -c \"$CMD\" -s \"$SUCCESS\" -e \"$EXIT\"'"+```++## Decision++### 1. Add an integration smoke harness for plugin hooks++`plugins/ruflo-core/scripts/test-hooks.mjs` drives **each** PostToolUse hook from `hooks/hooks.json` against a CLI binary (local build under test), with synthetic Claude-Code-style JSON on stdin. It asserts both:++- **Exit code** β catches "flag the CLI doesn't accept" (Bug 1).+- **Recorded value matches input** β catches "parser ambiguity records the wrong value" (Bug 2). E.g. when stdin says `file_path = /tmp/foo.ts`, output must contain `/tmp/foo.ts` and must *not* contain `Recording outcome for: true`.++Negative assertions (`absent: 'Recording β¦ : true'`) are critical. A naive `contains: 'true'` test would have spuriously passed against the broken CLI because the recorded value happened to be the string "true".++**Empirical validation**: Against the published broken `@claude-flow/[email protected]` the harness reports `2/7 passed` with the exact #1859/#1862 symptoms. Against the fixed `@3.7.0-alpha.18` it reports `7/7 passed`.++### 2. Wire it into `v3-ci.yml` as a blocking job++`plugin-hooks-smoke` runs after `build` succeeds and before `publish`, on Node 20 + 22:++```yaml+plugin-hooks-smoke:+ needs: [build]+ strategy:+ matrix:+ node: ['20', '22']+ steps:+ - install + build v3+ - node plugins/ruflo-core/scripts/test-hooks.mjs \+ "node $GITHUB_WORKSPACE/v3/@claude-flow/cli/bin/cli.js"+```++This *blocks* publishing on hook regression. A future PR that adds a non-existent flag to `hooks.json`, or re-introduces the `ctx.args[0] || ctx.flags.X` priority bug, fails this job before reaching users.++### 3. Codify the CLI flag-priority convention++`v3/@claude-flow/cli/src/commands/hooks.ts` sets the precedent for all `CommandContext` consumers: **named flags win over stray positionals**. The 14 changed sites are:++```+pre-edit line 302 --file+post-edit line 431 --file+pre-command line 530 --command+post-command line 659 --command+route line 745 --task+explain line 897 --task+transfer line 1525 --source+pre-task line 1764 --description+session-restore line 2106 --sessionId+coverage-route line 3067 --task+coverage-suggest line 3339 --path+coverage-gaps line 4730 --task+post-task line 5093 --taskId+notify line 5192 --message+```++Future handlers must follow `(ctx.flags.X as string) || ctx.args[0]`, not the reverse.++### 4. Smoke-harness pattern as a class++This is the second instance (after `smoke-install-no-bsqlite` from #1867) of the same template:++> Build the artifact under test in a fresh CI job. Drive it through the *user-visible* failure path (a real `npm install` on a clean dir; a real plugin hook against a real CLI). Assert on the user-visible signal (install succeeds; correct value recorded). Block publish on failure.++Future regression categories should follow the same shape rather than relying on in-process unit tests that miss subprocess/install/parser realities.++## Implementation++| Artifact | Path | Purpose |+|----------|------|---------|+| Plugin hook fix | `plugins/ruflo-core/hooks/hooks.json` | Real flags, multi-line-safe wrappers |+| Smoke harness | `plugins/ruflo-core/scripts/test-hooks.mjs` | 7 assertions; runs against any CLI invocation string |+| CI job | `.github/workflows/v3-ci.yml` (`plugin-hooks-smoke`) | Node 20 + 22 matrix; blocks `publish` |+| CLI parser fix | `v3/@claude-flow/cli/src/commands/hooks.ts` | 14-site flag/positional priority swap |++The smoke harness accepts an arbitrary CLI invocation string, so it can also run against the *published* CLI (`npx --yes @claude-flow/cli@latest`) as a post-release sanity check β the same script doubles as a pre-merge guard and a release canary.++## Consequences++### Protected against++- Re-adding a flag to `hooks.json` that the CLI doesn't accept.+- Re-introducing the `ctx.args[0] || flags.X` anti-pattern in any of the 14 handlers (or a 15th).+- Multi-line Bash commands silently dropping or producing `--command ''`.+- Plugin/CLI flag drift in either direction (CLI removes a flag the plugin uses; plugin starts using a flag the CLI doesn't have).++### Not protected against (residual risk)++- Plugins beyond `ruflo-core`. The harness is currently scoped to one plugin's `hooks.json`. Other plugins (`ruflo-swarm`, `ruflo-federation`, etc.) ship their own hook configs and could regress independently. Generalizing the harness to discover and exercise *all* plugin hook configs is a follow-up.+- Hooks that call commands other than the documented set. The harness only verifies that exit code is 0 and the recorded value matches input β it doesn't verify behavioural side effects (memory writes, neural training, etc.).+- Non-bash shells (Windows `cmd.exe`, PowerShell). The hook commands assume bash. Windows users running Claude Code outside WSL will see different failure modes that this harness doesn't cover. Tracked separately under #1857.++### User-visible impact++- `[email protected]` users still see the original errors until they update to `0.2.1` (plugin republish via IPFS β separate ship).+- `npx ruflo@latest` (3.7.0-alpha.18) users get the parser fix immediately. Even with the cached `[email protected]` plugin, the Bash hook's flag-priority symptom (recording "true" instead of the command) is fixed; only the Edit hook's `--format true` rejection remains until the plugin republish lands.++### Maintenance cost++- ~150 LOC of new code (test harness + CI job).+- ~7 second additional CI time per Node version (matrix doubles to 14s aggregate).+- The harness runs the actual CLI binary, so it surfaces issues like missing dependencies, broken postinstall scripts, and prebuild gaps that pure-vitest tests would miss.++## References++- #1859 β [email protected] ships broken PostToolUse hooks (Bash + Edit)+- #1862 β ruflo-core plugin v0.2.0: PostToolUse hook fails with --format true+- #1867 β Established the post-build install smoke pattern (`smoke-install-no-bsqlite`) that this ADR generalizes+- ADR-100 β cli-core split: relevant because the parser anti-pattern lives in the layer that ADR-100 isolates