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

Checkpoint: File edits

rUve4110bc4e065
diff --git a/README.md b/README.md
index 94e0e198b0..c207cd7ff4 100644
--- a/README.md
+++ b/README.md
@@ -1186,6 +1186,102 @@ echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env
---
+<details>
+<summary>πŸ›‘οΈ <strong>@claude-flow/guidance</strong> β€” Long-horizon governance control plane for Claude Code agents</summary>
+
+### Overview
+
+`@claude-flow/guidance` turns `CLAUDE.md` into a runtime governance system with enforcement gates, cryptographic proofs, and feedback loops. Agents that normally drift after 30 minutes can now operate for days β€” rules are enforced mechanically at every step, not remembered by the model.
+
+**7-phase pipeline:** Compile β†’ Retrieve β†’ Enforce β†’ Trust β†’ Prove β†’ Defend β†’ Evolve
+
+| Capability | Description |
+|-----------|-------------|
+| **Compile** | Parses `CLAUDE.md` into typed policy bundles (constitution + task-scoped shards) |
+| **Retrieve** | Intent-classified shard retrieval with semantic similarity and risk filters |
+| **Enforce** | 4 gates the model cannot bypass (destructive ops, tool allowlist, diff size, secrets) |
+| **Trust** | Per-agent trust accumulation with privilege tiers and coherence-driven throttling |
+| **Prove** | HMAC-SHA256 hash-chained proof envelopes for cryptographic run auditing |
+| **Defend** | Prompt injection, memory poisoning, and inter-agent collusion detection |
+| **Evolve** | Optimizer loop that ranks violations, simulates rule changes, and promotes winners |
+
+### Install
+
+```bash
+npm install @claude-flow/guidance@alpha
+```
+
+### Quick Usage
+
+```typescript
+import {
+ createCompiler,
+ createRetriever,
+ createGates,
+ createLedger,
+ createProofChain,
+} from '@claude-flow/guidance';
+
+// Compile CLAUDE.md into a policy bundle
+const compiler = createCompiler();
+const bundle = await compiler.compile(claudeMdText);
+
+// Retrieve task-relevant rules
+const retriever = createRetriever();
+await retriever.loadBundle(bundle);
+const { shards, policyText } = await retriever.retrieve({
+ taskDescription: 'Fix authentication bug in login flow',
+});
+
+// Enforce gates on tool calls
+const gates = createGates(bundle);
+const result = gates.evaluate({ tool: 'bash', args: { command: 'rm -rf /' } });
+// result.blocked === true
+
+// Audit with proof chain
+const chain = createProofChain({ signingKey: process.env.PROOF_KEY! });
+const envelope = chain.seal(runEvent);
+chain.verify(envelope); // true β€” tamper-evident
+```
+
+### Key Modules
+
+| Import Path | Purpose |
+|-------------|---------|
+| `@claude-flow/guidance` | Main entry β€” GuidanceControlPlane |
+| `@claude-flow/guidance/compiler` | CLAUDE.md β†’ PolicyBundle compiler |
+| `@claude-flow/guidance/retriever` | Intent classification + shard retrieval |
+| `@claude-flow/guidance/gates` | 4 enforcement gates |
+| `@claude-flow/guidance/ledger` | Run event logging + evaluators |
+| `@claude-flow/guidance/proof` | HMAC-SHA256 proof chain |
+| `@claude-flow/guidance/adversarial` | Threat, collusion, memory quorum |
+| `@claude-flow/guidance/trust` | Trust accumulation + privilege tiers |
+| `@claude-flow/guidance/authority` | Human authority + irreversibility classification |
+| `@claude-flow/guidance/wasm-kernel` | WASM-accelerated security-critical paths |
+| `@claude-flow/guidance/analyzer` | CLAUDE.md quality analysis + A/B benchmarking |
+| `@claude-flow/guidance/conformance-kit` | Headless conformance test runner |
+
+### Stats
+
+- **1,331 tests** across 26 test files
+- **27 subpath exports** for tree-shaking
+- **WASM kernel** for security-critical hot paths (gates, proof, scoring)
+- **25 ADRs** documenting every architectural decision
+
+### Documentation
+
+- [Architecture Overview](v3/@claude-flow/guidance/docs/guides/architecture-overview.md)
+- [Getting Started](v3/@claude-flow/guidance/docs/guides/getting-started.md)
+- [Enforcement Gates Tutorial](v3/@claude-flow/guidance/docs/tutorials/enforcement-gates.md)
+- [Proof Audit Trail](v3/@claude-flow/guidance/docs/tutorials/proof-audit-trail.md)
+- [Multi-Agent Security](v3/@claude-flow/guidance/docs/guides/multi-agent-security.md)
+- [API Quick Reference](v3/@claude-flow/guidance/docs/reference/api-quick-reference.md)
+- [Full README](v3/@claude-flow/guidance/README.md)
+
+</details>
+
+---
+
## πŸ“¦ Core Features
Comprehensive capabilities for enterprise-grade AI agent orchestration.