Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.json
index 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.md
index 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.md
new file mode 100644
index 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 reference
diff --git a/plugins/ruflo-federation/scripts/smoke.sh b/plugins/ruflo-federation/scripts/smoke.sh
new file mode 100755
index 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