ruflo/plugins/ruflo-federation/docs/adrs/0001-federation-contract.md at main

admin/ruflo

0 Fork 0

mirror of https://github.com/ruvnet/ruflo.git synced 2026-10-23 03:47:00 +09:00

Files

T

randRuFlo ac583cd342 fix(plugins): group B skills and agents use real CLI flags and MCP parameter names

Verified every CLI flag and MCP call example in ruflo-core, cost-tracker, daa,
ddd, deepseek-harness, docs, federation and goals against the published CLI
(3.56.5) and the tool schemas in source:

- hooks post-task has no --train-neural (8 agents/skills); neural train takes
  --pattern, not --pattern-type; hooks worker dispatch takes --context, not
  --scope (docs scoping was silently ignored).
- agentdb_* examples used non-existent parameters (semantic-route query ->
  input; causal-edge from/to/type -> sourceId/targetId/relation; hierarchical
  store/recall path/data/depth -> key/value/tier and query/topK; pattern-search
  limit -> topK; context-synthesize sources -> maxEntries); ddd skills used a
  CLI-style --parent/--child form that failed on required key/value. The
  researcher agent now follows edges with graph-query/graph-pathfinder.
- hooks_worker-status has no worker filter; cost docs now filter the result.
- dossier-collect/investigator fetch web content: add untrusted-content rules
  and AIDefence screening. deepseek skills state the data egress.
- Stale smoke/tool/command counts and four dead relative links fixed.

Patch-bumps each changed plugin with a CHANGELOG entry.

Co-Authored-By: RuFlo <ruv@ruv.net>

2026-10-11 11:26:09 -04:00

4.1 KiB

Raw Permalink Blame History

id, title, status, date, updated, authors, tags

title

status

date

updated

authors

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:

No plugin-level ADR.
No smoke test.
README's "PII Pipeline" feature claim doesn't cross-reference the canonical 3-gate pattern owned by ruflo-aidefence ADR-0001. 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.
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).
Compatibility section missing the v3.6 pin.

Decision

Add this ADR (Proposed).
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); 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.
Plugin metadata stays at 0.2.0 (already at the cadence). Keywords add mcp, pii-pipeline, audit-log.
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 plugins/ruflo-federation/scripts/smoke.sh
# Expected: "10 passed, 0 failed"

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

Implementation status

Plugin version v0.2.0 shipped and listed in marketplace.json. Source exists at plugins/ruflo-federation/. Contract elements implemented: ADR-097 budget circuit breaker Phase 1 (send-side enforcement) and Phase 2 (peer state machine) documented; Phase 3 (ruflo-cost-tracker integration) deferred; 3-gate pattern alignment via ruflo-aidefence ADR-0001; smoke-as-contract gate defined in scripts/smoke.sh.

4.1 KiB Raw Permalink Blame History