mirror of
https://github.com/ruvnet/ruflo.git
synced 2026-11-09 14:04:06 +09:00
ruv
21e52108d5
Three coupled fixes for ruvnet/ruflo#2049:
1. `kg-extract/SKILL.md` step 3 now declares a separate `type-depends-on`
relation (weight 0.1) for TypeScript `import type` and inline
`import { type Foo, value }` specifiers. Includes the regex carve-out
pattern so future agents implementing the skill correctly classify
the three import shapes. Previously the skill said "follow
import/require statements" with no carve-out, and a naive grep
produced phantom runtime cycles (a 51-service codebase reported a
non-existent `findings ⇄ finding-actions` cycle driven entirely by
a one-way `import type { Finding }` edge).
2. `kg-traverse/SKILL.md` step 3 now calls `agentdb_pattern-search`
(enabled in current AgentDB builds) instead of
`agentdb_semantic-route` (`enabled: false` — controller is
compiled out, returns "SemanticRouter not available in current
agentdb build"). Both skills' `allowed-tools` lines updated to
drop the disabled controller.
3. New CI smoke at `scripts/smoke-kg-extract-type-imports.mjs` +
new workflow job `kg-extract type-import classification smoke (#2049)`
in `.github/workflows/v3-ci.yml`. Two layers:
- Static contract check on both SKILL.md files — asserts
`type-depends-on` relation is declared, weight ≤ 0.1, regex
carve-out is present, and no skill lists the disabled
`agentdb_semantic-route` in allowed-tools.
- Behavioural fixture test: writes a tiny TS scenario with one
type-only cycle + one value-import edge to /tmp, runs the
documented regex classifier, and asserts the cycle is NOT counted
as a value edge. If a future PR softens any of these contracts,
the smoke catches it before merge.
Path filters in v3-ci.yml expanded to include
`plugins/ruflo-knowledge-graph/**` + the new smoke script so the job
fires on every relevant edit.
Plus `.github/supply-chain/follow-ups.md` documents:
- #2047 (witness drift HIGH) — upstream scheduled-runner fix needed +
the interim CI guards already in place.
- #2048 (agentic-flow Windows onnxruntime binding) — needs the same
shape of upstream patch as ADR-124 shipped for @xenova/transformers
in agentic-flow 2.0.12; documented workaround for users and the
CI guard to add post-patch.
Smoke verified locally: 9/9 checks pass.
Co-Authored-By: RuFlo <ruv@ruv.net>
ruflo-knowledge-graph
Knowledge graph construction -- entity extraction, relation mapping, and pathfinder graph traversal.
Overview
Extracts entities (classes, functions, modules, types, concepts) and relations (imports, extends, implements, depends-on, calls) from source code and documentation. Builds a navigable knowledge graph stored in AgentDB with hierarchical nodes and causal edges. Traverses the graph using a pathfinder algorithm that scores paths by edge weight and semantic similarity.
Installation
claude --plugin-dir plugins/ruflo-knowledge-graph
Agents
| Agent | Model | Role |
|---|---|---|
graph-navigator |
sonnet | Entity extraction, relation mapping, knowledge graph construction, pathfinder traversal |
Skills
| Skill | Usage | Description |
|---|---|---|
kg-extract |
/kg-extract <path> |
Extract entities and relations from source files to build a knowledge graph |
kg-traverse |
/kg-traverse <entity> [--depth N] |
Pathfinder traversal starting from a seed entity |
Commands (5 subcommands)
kg extract <path> # Extract entities and relations from source files
kg traverse <entity> # Pathfinder traversal from a seed entity
kg relations <entity> # List all direct relations for an entity
kg visualize # ASCII visualization of the knowledge graph
kg search <query> # Semantic search across the graph
Entity Types
| Type | Examples |
|---|---|
| class | UserService, AuthController |
| function | calculateDiscount, handleRequest |
| module | auth, payments, api |
| concept | authentication, caching |
| type | User, OrderStatus |
| config | database, redis, jwt |
Compatibility
- CLI: pinned to
@claude-flow/cliv3.6 major+minor. - Verification:
bash plugins/ruflo-knowledge-graph/scripts/smoke.shis the contract.
Namespace coordination
This plugin owns the kg-graph AgentDB namespace (kebab-case, follows the convention from ruflo-agentdb ADR-0001 §"Namespace convention"). Reserved namespaces (pattern, claude-memories, default) MUST NOT be shadowed.
Entity nodes are stored via agentdb_hierarchical-store; relation edges via agentdb_causal-edge; semantic indexing via embeddings_generate (NOT embeddings_embed — that tool name doesn't exist; ADR-0001 fixes prior references).
Pathfinder Algorithm
- Seed -- start from the target entity node
- Expand -- follow causal edges outward (configurable depth, default 3)
- Score --
relevance = edge_weight * semantic_similarity(query, node) - Prune -- remove paths below threshold (default 0.3)
- Rank -- return top-K paths by cumulative relevance
G7 controllers (activated in ruflo 3.6.23+ / 3.6.24)
ADR-095 closed five AgentDB controllers that this plugin's graph traversal can leverage:
gnnService— GNN embeddings + relational scoring over the AgentDB causal graph. Augments the pathfinder'ssemantic_similarity(query, node)term with structurally-aware scoring; nodes that are graph-neighbors of confirmed-relevant nodes get a boost.rvfOptimizer— Quantizes + dedupes vector blocks before persistence. Knowledge-graph indexes commonly have many near-duplicate entity vectors (same class re-exported from multiple modules); rvfOptimizer collapses them transparently.mutationGuard+attestationLog+GuardedVectorBackend— Proof-gated writes to the underlying vector store. Relevant when the graph spans trust boundaries (federated knowledge import) — the attestation chain at.swarm/attestation.dbrecords every mutation for after-the-fact audit.
The yet-pending graphAdapter controller will give this plugin a first-class graph-DB backend (instead of building the graph view on top of AgentDB's flat causal-edge table). Tracked in ADR-095.
Inspect runtime status via the agentdb_controllers or agentdb_health MCP tools.
Verification
bash plugins/ruflo-knowledge-graph/scripts/smoke.sh
# Expected: "10 passed, 0 failed"
Architecture Decisions
Related Plugins
ruflo-agentdb-- The G7 controllers above ship via this plugin's runtime; install both for full graph + traversal coverage; namespace convention ownerruflo-ruvector-- HNSW indexing for fast semantic search across graph nodesruflo-adr-- ADR dependency graphs share the same causal edge model
License
MIT