π 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
feat(ruflo-federation): adopt plugin contract β 3-gate alignment + ADR-097 budget integration + smoke (ADR-0001)
Reuvenb0168e4a55b4
diff --git a/plugins/ruflo-federation/.claude-plugin/plugin.json b/plugins/ruflo-federation/.claude-plugin/plugin.jsonindex 8b55091f01..0be731cbf5 100644--- a/plugins/ruflo-federation/.claude-plugin/plugin.json+++ b/plugins/ruflo-federation/.claude-plugin/plugin.json@@ -18,6 +18,9 @@"distributed","circuit-breaker","budget",- "token-quota"+ "token-quota",+ "mcp",+ "pii-pipeline",+ "audit-log"]}diff --git a/plugins/ruflo-federation/README.md b/plugins/ruflo-federation/README.mdindex 3c698f1c77..f9124396c0 100644--- a/plugins/ruflo-federation/README.md+++ b/plugins/ruflo-federation/README.md@@ -60,3 +60,38 @@ Phase 1 enforces at the **send** side. Phase 2 (peer state machine: ACTIVE / SUS- `ruflo-core` plugin (provides MCP server)- `@claude-flow/security` (cryptographic primitives)++## Compatibility++- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.+- **Federation runtime:** `@claude-flow/plugin-agent-federation` (resolved via `npx -y -p`).+- **Verification:** `bash plugins/ruflo-federation/scripts/smoke.sh` is the contract.++## Alignment with the canonical 3-gate pattern++Federation's "PII Pipeline" feature is a richer specialization of the canonical 3-gate pattern owned by [ruflo-aidefence ADR-0001](../ruflo-aidefence/docs/adrs/0001-aidefence-contract.md). The mapping:++| Canonical gate | Federation specialization |+|----------------|--------------------------|+| Pre-storage PII (`aidefence_has_pii`) | 14-type PII detection with per-trust-level policies (`BLOCK` / `REDACT` / `HASH` / `PASS`) |+| Sanitization (`aidefence_scan`) | Outbound HMAC-signed envelope + dual AI Defence gates |+| Prompt-injection (`aidefence_is_safe`) | Inbound message verification before delivery to local agents |++Federation extends the canonical gates with adaptive confidence calibration and trust-level-aware policies, but the gate ordering and intent are identical. New federated content paths should reference the canonical 3-gate pattern by name.++## Namespace coordination++This plugin owns the `federation` AgentDB namespace. This is the documented exception to the kebab-case `<plugin-stem>-<intent>` rule: when a plugin's name *is* the intent, the namespace can match the plugin stem. See [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.++`federation` is accessed via `memory_*` tools (namespace-routed). Used for: peer registry, trust score history, audit log indices, message envelope receipts.++## Verification++```bash+bash plugins/ruflo-federation/scripts/smoke.sh+# Expected: "10 passed, 0 failed"+```++## Architecture Decisions++- [`ADR-0001` β ruflo-federation plugin contract (3-gate alignment, ADR-097 budget integration, namespace coordination, smoke as contract)](./docs/adrs/0001-federation-contract.md)diff --git a/plugins/ruflo-federation/docs/adrs/0001-federation-contract.md b/plugins/ruflo-federation/docs/adrs/0001-federation-contract.mdnew file mode 100644index 0000000000..42fb547807--- /dev/null+++ b/plugins/ruflo-federation/docs/adrs/0001-federation-contract.md@@ -0,0 +1,55 @@+---+id: ADR-0001+title: ruflo-federation plugin contract β pinning, namespace coordination, 3-gate pattern alignment, ADR-097 budget integration, smoke as contract+status: Proposed+date: 2026-05-04+authors:+ - reviewer (Claude Code)+tags: [plugin, federation, zero-trust, peer-discovery, consensus, budget, namespace, smoke-test]+---++## Context++`ruflo-federation` (v0.2.0) β comms layer for cross-installation agent federation. Plugin-internal (drives `@claude-flow/plugin-agent-federation` via npx; no CLI MCP tools of its own β federation tooling is npm-package-driven). Surface:++- 1 agent (`federation-coordinator`)+- 3 skills (`federation-init`, `federation-status`, `federation-audit`)+- 1 command (`/federation`)+- README extensively documents the ADR-097 budget circuit breaker (Phase 1: send-side enforcement; Phase 2: peer state machine; Phase 3: ruflo-cost-tracker integration β both deferred)++Contract gaps relative to the established cadence:++1. No plugin-level ADR.+2. No smoke test.+3. README's "PII Pipeline" feature claim doesn't cross-reference the canonical [3-gate pattern owned by ruflo-aidefence ADR-0001](../../ruflo-aidefence/docs/adrs/0001-aidefence-contract.md). Federation's PII pipeline is a richer 14-type detection β but it's a specialization of the same 3-gate design and should defer to the canonical contract.+4. No namespace coordination cross-reference (uses `federation` namespace β should be `federation-patterns` per kebab-case `<plugin-stem>-<intent>` rule, OR documented as the singular case where the plugin name itself is the intent).+5. Compatibility section missing the v3.6 pin.++## Decision++1. Add this ADR (Proposed).+2. README augment: Compatibility (pin v3.6); Namespace coordination (claim `federation` as the namespace β this is the documented exception where the plugin owns its base name; the kebab-case rule still applies, just with an empty intent. Cross-reference [ruflo-agentdb ADR-0001](../../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md)); 3-gate alignment block (federation's PII pipeline is a richer specialization of the canonical 3 gates from ruflo-aidefence ADR-0001); Verification + Architecture Decisions sections.+3. Plugin metadata stays at `0.2.0` (already at the cadence). Keywords add `mcp`, `pii-pipeline`, `audit-log`.+4. `scripts/smoke.sh` β 10 structural checks: version + new keywords; all 3 skills + agent + command with valid frontmatter; ADR-097 budget block intact (`maxHops`, `maxTokens`, `maxUsd`, `BUDGET_EXCEEDED`, `HOP_LIMIT_EXCEEDED`); 5-tier trust model documented (UNTRUSTED β VERIFIED β ATTESTED β TRUSTED β PRIVILEGED); compliance modes documented (HIPAA, SOC2, GDPR); v3.6 pin; namespace coordination block; 3-gate alignment cross-reference; ADR Proposed; no wildcard tools.++## Consequences++**Positive:**+- Federation's PII pipeline is now contractually anchored to the canonical 3-gate pattern. Implementers reading both plugins won't have to reconcile two different "gate" stories.+- ADR-097 budget integration (the cross-reference between `federation_send` caps and `ruflo-cost-tracker` Phase 3 plans) becomes a smoke-checked invariant.++**Negative:** none. Plugin behavior unchanged.++## Verification++```bash+bash plugins/ruflo-federation/scripts/smoke.sh+# Expected: "10 passed, 0 failed"+```++## Related++- `plugins/ruflo-aidefence/docs/adrs/0001-aidefence-contract.md` β canonical 3-gate pattern this plugin specializes+- `plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md` β ADR-097 Phase 3 integration target+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β namespace convention+- `v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md` β host-side enforcement referencediff --git a/plugins/ruflo-federation/scripts/smoke.sh b/plugins/ruflo-federation/scripts/smoke.shnew file mode 100755index 0000000000..bb241346b2--- /dev/null+++ b/plugins/ruflo-federation/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 pii-pipeline audit-log; do+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"+ done+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"+fi++step "2. all 3 skills + agent + command present with valid frontmatter"+miss=""+for s in federation-init federation-status federation-audit; 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/federation-coordinator.md" ]] || miss="$miss missing-agent"+[[ -f "$ROOT/commands/federation.md" ]] || miss="$miss missing-command"+[[ -z "$miss" ]] && ok || bad "$miss"++step "3. ADR-097 budget block intact (maxHops, maxTokens, maxUsd, BUDGET_EXCEEDED, HOP_LIMIT_EXCEEDED)"+F="$ROOT/README.md"+miss=""+for token in maxHops maxTokens maxUsd BUDGET_EXCEEDED HOP_LIMIT_EXCEEDED; do+ grep -q "$token" "$F" || miss="$miss $token"+done+[[ -z "$miss" ]] && ok || bad "$miss"++step "4. 5-tier trust model documented"+F="$ROOT/README.md"+miss=""+for tier in UNTRUSTED VERIFIED ATTESTED TRUSTED PRIVILEGED; do+ grep -q "$tier" "$F" || miss="$miss $tier"+done+[[ -z "$miss" ]] && ok || bad "missing tiers:$miss"++step "5. Compliance modes documented (HIPAA, SOC2, GDPR)"+F="$ROOT/README.md"+miss=""+for mode in HIPAA SOC2 GDPR; do+ grep -q "$mode" "$F" || miss="$miss $mode"+done+[[ -z "$miss" ]] && ok || bad "missing modes:$miss"++step "6. 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 "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. README aligns with canonical 3-gate pattern (cross-reference)"+F="$ROOT/README.md"+miss=""+grep -qE "3-gate|3 gates|three gates" "$F" || miss="$miss header"+grep -q "ruflo-aidefence" "$F" || miss="$miss aidefence-ref"+[[ -z "$miss" ]] && ok || bad "3-gate alignment block missing:$miss"++step "9. ADR-0001 exists with status Proposed"+ADR="$ROOT/docs/adrs/0001-federation-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