v3.2.3: Phase 4 partial -- observability commands, governance vocabulary, competitive comparison

- Add --active-grants command (TTL countdown, agent filter, JSON output)
- Add --audit-summary command (per-agent/resource breakdowns, grant rate, recent activity)
- Add competitive comparison table (Network-AI vs LangChain vs AutoGen vs CrewAI vs Claude SDK)
- Add fan-out/fan-in example to README
- Reframe README around behavioral control plane, compliance enforcement, governance layer
- Add MCP Blackboard Tool Bindings to Phase 4 roadmap
- Fix Pylance type annotations in check_permission.py
- Update SECURITY.md scanner version to v3.2.3
- Add test-priority.ts to project structure listing

Author: jovanSAPFIONEER

CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to Network-AI will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.3] - 2026-02-18
+
+### Added -- Phase 4 (Partial): Observability & Governance Vocabulary
+- **`--active-grants` command** -- `check_permission.py --active-grants` shows which agents currently hold access to which APIs, with TTL countdown, scope, restrictions; supports `--agent` filter and `--json` output
+- **`--audit-summary` command** -- `check_permission.py --audit-summary` summarizes permission activity: per-agent and per-resource breakdowns of requests/grants/denials, grant rate, recent activity log; supports `--last N` and `--json`
+- **Competitive comparison table** -- README now includes side-by-side feature comparison (Network-AI vs LangChain vs AutoGen vs CrewAI vs Claude SDK) across 14 capabilities
+- **Fan-out/fan-in example** -- README documents the parallel evaluation pattern using LockedBlackboard for coordinating independent agent subtasks
+- **Governance vocabulary** -- README reframed around "behavioral control plane," "compliance enforcement," "governance layer," "fan-out/fan-in orchestration"
+- **Observability section in Features** -- `--active-grants`, `--audit-summary`, and justification hardening listed under Operational Safety & Governance
+- **MCP Blackboard Tool Bindings** -- Added to Phase 4 roadmap (expose blackboard as MCP tool definitions)
+- **SEO keywords** -- Added behavioral-control-plane, governance-layer, compliance-enforcement, fan-out-fan-in, agent-observability, permission-gating, audit-trail
+
+### Changed
+- **`check_permission.py` restructured** -- `--agent`, `--resource`, `--justification` now optional at argparse level; validated manually only for permission check mode; action flags `--active-grants` and `--audit-summary` bypass check requirements
+- **README "Why Network-AI?" section** -- Updated to lead with governance, shared state, and security (previously led with swarm intelligence)
+- **Related Concepts section** -- Added Behavioral Control Plane and Agent Governance entries
+
+### Stats
+- 315 tests passing (79 + 33 + 139 + 64)
+- 0 compile errors
+- `check_permission.py`: 596 lines (was 436)
+
 ## [3.2.2] - 2026-02-17
 
 ### Changed
@@ -56,6 +78,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`--active-grants` Command** -- Show which agents currently hold access to which APIs with expiry times
 - **`--audit-summary` Command** -- Summarize recent requests, grants, and denials by agent
 - **Behavioral Vocabulary in README** -- Reframe marketing around "behavioral control plane," "compliance enforcement," "governance layer"
+- **MCP Blackboard Tool Bindings** -- Expose `blackboard_read`, `blackboard_write`, `blackboard_list`, `blackboard_delete` as MCP-compatible tool definitions so any LLM agent can interact with shared state via tool calls
 
 ## [Future] -- Phase 5: Distributed Blackboard
 

README.md

@@ -2,7 +2,7 @@
 
 **The plug-and-play AI agent orchestrator for TypeScript/Node.js -- connect 12 agent frameworks with zero glue code**
 
-[![Release](https://img.shields.io/badge/release-v3.2.2-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
+[![Release](https://img.shields.io/badge/release-v3.2.3-blue.svg)](https://github.com/jovanSAPFIONEER/Network-AI/releases)
 [![ClawHub](https://img.shields.io/badge/ClawHub-network--ai-orange.svg)](https://clawhub.ai/skills/network-ai)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6.svg)](https://typescriptlang.org)
@@ -15,12 +15,13 @@
 
 > **Legacy Users:** This skill works with **Clawdbot** and **Moltbot** (now OpenClaw). If you're searching for *Moltbot Security*, *Clawdbot Swarm*, or *Moltbot multi-agent* -- you're in the right place!
 
-Network-AI is a framework-agnostic multi-agent orchestrator that connects LLM agents across **12 frameworks** -- LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, and custom adapters. It provides shared blackboard coordination, built-in security (AES-256, HMAC tokens, rate limiting), content quality gates with hallucination detection, and agentic workflow patterns (parallel execution, voting, chaining). Zero dependencies per adapter -- bring your own framework SDK and start building multi-agent systems in minutes.
+Network-AI is a framework-agnostic multi-agent orchestrator and **behavioral control plane** that connects LLM agents across **12 frameworks** -- LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw, and custom adapters. It provides shared blackboard coordination with atomic commits, built-in security (AES-256, HMAC tokens, rate limiting), content quality gates with hallucination detection, compliance enforcement, and agentic workflow patterns (parallel fan-out/fan-in, voting, chaining). Zero dependencies per adapter -- bring your own framework SDK and start building governed multi-agent systems in minutes.
 
 **Why Network-AI?**
 - **Framework-agnostic** -- Not locked to one LLM provider or agent SDK
-- **Production security** -- Encryption, audit trails, rate limiting built in
-- **Swarm intelligence** -- Parallel execution, voting, chain-of-agents patterns
+- **Governance layer** -- Permission gating, audit trails, budget ceilings, and compliance enforcement across all agents
+- **Shared state** -- Atomic blackboard with conflict resolution for safe parallel agent coordination (fan-out/fan-in)
+- **Production security** -- AES-256 encryption, HMAC audit logs, rate limiting, input sanitization
 - **Zero config** -- Works out of the box with `createSwarmOrchestrator()`
 
 ## Hello World -- Get Running in 60 Seconds
@@ -131,12 +132,15 @@ Network-AI wraps your agent swarm with **file-system mutexes**, **atomic commits
 - **Cryptographic Audit Logs** -- Tamper-evident signed audit trail with chain continuation
 - **Secure Gateway** -- Integrated security layer wrapping all operations
 
-### Operational Safety
+### Operational Safety & Governance
 - **Swarm Guard** -- Prevents "Handoff Tax" (wasted tokens) and detects silent agent failures
 - **Atomic Commits** -- File-system mutexes prevent split-brain in concurrent writes
 - **Priority-Based Preemption** -- Higher-priority agents preempt lower-priority writes on same-key conflicts (`priority-wins` strategy)
 - **Cost Awareness** -- Token budget tracking with automatic SafetyShutdown
 - **Budget-Aware Handoffs** -- `intercept-handoff` command wraps `sessions_send` with budget checks
+- **`--active-grants` Observability** -- Real-time view of which agents hold access to which APIs, with TTL countdown
+- **`--audit-summary` Observability** -- Per-agent and per-resource breakdown of permission requests, grants, and denials
+- **Justification Hardening** -- 16-pattern prompt-injection detector, keyword-stuffing defense, structural coherence scoring
 
 ## Project Structure
 
@@ -190,6 +194,7 @@ Network-AI/
 |-- test-standalone.ts        # Core orchestrator tests (79 tests)
 |-- test-security.ts          # Security module tests (33 tests)
 |-- test-adapters.ts          # Adapter system tests (139 tests)
+|-- test-priority.ts          # Priority & preemption tests (64 tests)
 |-- test-ai-quality.ts        # AI quality gate demo
 |-- test.ts                   # Full integration test suite
 ```
@@ -341,6 +346,65 @@ Expires: 2026-02-04T15:30:00Z
 Restrictions: read_only, max_records:100
 ```
 
+#### 3a. View Active Grants
+
+See which agents currently hold access to which APIs:
+
+```bash
+# Human-readable
+python scripts/check_permission.py --active-grants
+
+# Filter by agent
+python scripts/check_permission.py --active-grants --agent data_analyst
+
+# Machine-readable JSON
+python scripts/check_permission.py --active-grants --json
+```
+
+Output:
+```
+Active Grants:
+======================================================================
+  Agent:       data_analyst
+  Resource:    DATABASE
+  Scope:       read:orders
+  Token:       grant_c1ea828897...
+  Remaining:   4.4 min
+  Restrictions: read_only, max_records:100
+  ------------------------------------------------------------------
+
+Total: 1 active, 0 expired
+```
+
+#### 3b. Audit Summary
+
+Summarize permission activity across all agents:
+
+```bash
+# Human-readable
+python scripts/check_permission.py --audit-summary
+
+# Last 50 entries, JSON output
+python scripts/check_permission.py --audit-summary --last 50 --json
+```
+
+Output:
+```
+Audit Summary
+======================================================================
+  Requests:     12
+  Grants:        9
+  Denials:       3
+  Grant Rate:   75%
+
+  By Agent:
+  --------------------------------------------------
+  Agent                  Requests     Grants    Denials
+  data_analyst                  4          3          1
+  orchestrator                  5          4          1
+  strategy_advisor              3          2          1
+```
+
 #### 4. Use the Blackboard
 
 ```bash
@@ -359,7 +423,44 @@ python scripts/blackboard.py commit "chg_001"
 python scripts/blackboard.py list
 ```
 
-#### 5. Priority-Based Conflict Resolution (Phase 3)
+#### 5. Fan-Out / Fan-In with Shared Blackboard
+
+Coordinate multiple specialized agents working on independent subtasks, then merge results:
+
+```typescript
+import { LockedBlackboard } from 'network-ai';
+import { Logger } from 'network-ai';
+
+const logger = Logger.create('fan-out');
+const board = new LockedBlackboard('.', logger, { conflictResolution: 'first-commit-wins' });
+
+// Fan-out: each agent writes to its own section
+const agents = ['reliability', 'security', 'cost', 'operations', 'performance'];
+
+for (const pillar of agents) {
+  // Each agent evaluates independently, writes to its own key
+  const id = board.propose(`eval:${pillar}`, { score: Math.random(), findings: [] }, pillar);
+  board.validate(id, 'orchestrator');
+  board.commit(id);
+}
+
+// Fan-in: orchestrator reads all results and merges
+const results = agents.map(pillar => ({
+  pillar,
+  ...board.read(`eval:${pillar}`)
+}));
+
+const summary = board.propose('eval:summary', {
+  overall: results.reduce((sum, r) => sum + r.score, 0) / results.length,
+  pillars: results
+}, 'orchestrator');
+board.validate(summary, 'orchestrator');
+board.commit(summary);
+```
+
+This pattern works with any framework adapter -- LangChain agents, AutoGen agents, CrewAI crews, or any mix. The blackboard ensures no agent overwrites another's results.
+
+#### 6. Priority-Based Conflict Resolution (Phase 3)
 
 ```typescript
 import { LockedBlackboard } from 'network-ai';
@@ -384,7 +485,7 @@ board.commit(highId);                   // success
 board.read('shared:config'); // { mode: 'final' } -- supervisor wins
 ```
 
-#### 6. Check Budget Status
+#### 7. Check Budget Status
 
 ```bash
 python scripts/swarm_guard.py budget-check --task-id "task_001"
@@ -628,18 +729,43 @@ If you find Network-AI useful, **give it a star** -- it helps others discover th
 
 **Compatible with 12 agent frameworks: OpenClaw, LangChain, AutoGen, CrewAI, MCP, LlamaIndex, Semantic Kernel, OpenAI Assistants, Haystack, DSPy, Agno, and any custom adapter**
 
+## Competitive Comparison
+
+How Network-AI compares to other multi-agent frameworks:
+
+| Capability | Network-AI | LangChain/LangGraph | AutoGen/AG2 | CrewAI | Claude SDK |
+|---|---|---|---|---|---|
+| **Multi-framework support** | 12 adapters | LangChain only | AutoGen only | CrewAI only | Claude only |
+| **Shared state (blackboard)** | Atomic commits, TTL, priority | LangGraph state | Shared context | Shared memory | Project memory |
+| **Conflict resolution** | Priority preemption, last-write-wins | None | None | None | None |
+| **Fan-out / fan-in** | Native (parallel + merge) | LangGraph branches | Group chat | Parallel tasks | Subagents |
+| **Permission gating** | AuthGuardian (weighted scoring) | None | None | None | None |
+| **Budget tracking** | Token ceiling + per-task budgets | Callbacks only | None | None | None |
+| **Audit trail** | HMAC-signed, tamper-evident | None | None | None | None |
+| **Encryption at rest** | AES-256-GCM | None | None | None | None |
+| **Observability** | `--active-grants`, `--audit-summary` | LangSmith (SaaS) | None | None | None |
+| **Rate limiting** | Per-agent with lockout | None | None | None | None |
+| **Justification hardening** | 16-pattern injection defense | None | None | None | None |
+| **Language** | TypeScript/Node.js | Python | Python | Python | Python |
+| **Dependencies** | Zero (per adapter) | Heavy | Heavy | Heavy | Moderate |
+| **License** | MIT | MIT | CC-BY-4.0 | MIT | MIT |
+
+**Key differentiator:** Network-AI is the only framework that combines multi-framework orchestration with a governance layer (permissions, audit, encryption, budget enforcement). Other frameworks focus on one LLM provider; Network-AI wraps all of them.
+
 ## Related Concepts
 
 Network-AI fits into the broader AI agent ecosystem:
 
 - **Multi-Agent Systems** -- Coordinate multiple AI agents working together on complex tasks
 - **Agentic AI** -- Build autonomous agents that reason, plan, and execute using LLMs
-- **Swarm Intelligence** -- Parallel execution patterns with voting, merging, and chain strategies
+- **Behavioral Control Plane** -- Govern agent behavior with permission gating, compliance enforcement, and audit trails
+- **Swarm Intelligence** -- Parallel fan-out/fan-in patterns with voting, merging, and chain strategies
 - **Model Context Protocol (MCP)** -- Standard protocol support for LLM tool integration
 - **Agent-to-Agent (A2A)** -- Inter-agent communication via shared blackboard and handoff protocol
 - **Context Engineering** -- Manage and share context across agent boundaries
 - **Agentic Workflows** -- Task decomposition, parallel processing, and synthesis pipelines
 - **LLM Orchestration** -- Route tasks to the right agent framework automatically
+- **Agent Governance** -- Permission gating, budget enforcement, audit logging, and compliance monitoring
 
 If you're using LangGraph, Dify, Flowise, PraisonAI, AutoGen/AG2, CrewAI, or any other agent framework, Network-AI can integrate with it through the adapter system.
 
@@ -648,6 +774,6 @@ If you're using LangGraph, Dify, Flowise, PraisonAI, AutoGen/AG2, CrewAI, or any
 <details>
 <summary>Keywords (for search)</summary>
 
-ai-agents, agentic-ai, multi-agent, multi-agent-systems, multi-agent-system, agent-framework, ai-agent-framework, agentic-framework, agentic-workflow, llm, llm-agents, llm-agent, large-language-models, generative-ai, genai, orchestration, ai-orchestration, swarm, swarm-intelligence, autonomous-agents, agents, ai, typescript, nodejs, mcp, model-context-protocol, a2a, agent-to-agent, function-calling, tool-integration, context-engineering, rag, ai-safety, multi-agents-collaboration, multi-agents, aiagents, aiagentframework, plug-and-play, adapter-registry, blackboard-pattern, agent-coordination, agent-handoffs, token-permissions, budget-tracking, cost-awareness, atomic-commits, hallucination-detection, content-quality-gate, OpenClaw, Clawdbot, Moltbot, Clawdbot Swarm, Moltbot Security, Moltbot multi-agent, OpenClaw skills, AgentSkills, LangChain adapter, LangGraph, AutoGen adapter, AG2, CrewAI adapter, MCP adapter, LlamaIndex adapter, Semantic Kernel adapter, OpenAI Assistants adapter, Haystack adapter, DSPy adapter, Agno adapter, Phidata adapter, Dify, Flowise, PraisonAI, custom-adapter, AES-256 encryption, HMAC tokens, rate limiting, input sanitization, privilege escalation prevention, ClawHub, clawhub, agentic-rag, deep-research, workflow-orchestration, ai-assistant, ai-tools, developer-tools, open-source
+ai-agents, agentic-ai, multi-agent, multi-agent-systems, multi-agent-system, agent-framework, ai-agent-framework, agentic-framework, agentic-workflow, llm, llm-agents, llm-agent, large-language-models, generative-ai, genai, orchestration, ai-orchestration, swarm, swarm-intelligence, autonomous-agents, agents, ai, typescript, nodejs, mcp, model-context-protocol, a2a, agent-to-agent, function-calling, tool-integration, context-engineering, rag, ai-safety, multi-agents-collaboration, multi-agents, aiagents, aiagentframework, plug-and-play, adapter-registry, blackboard-pattern, agent-coordination, agent-handoffs, token-permissions, budget-tracking, cost-awareness, atomic-commits, hallucination-detection, content-quality-gate, behavioral-control-plane, governance-layer, compliance-enforcement, fan-out-fan-in, agent-observability, permission-gating, audit-trail, OpenClaw, Clawdbot, Moltbot, Clawdbot Swarm, Moltbot Security, Moltbot multi-agent, OpenClaw skills, AgentSkills, LangChain adapter, LangGraph, AutoGen adapter, AG2, CrewAI adapter, MCP adapter, LlamaIndex adapter, Semantic Kernel adapter, OpenAI Assistants adapter, Haystack adapter, DSPy adapter, Agno adapter, Phidata adapter, Dify, Flowise, PraisonAI, custom-adapter, AES-256 encryption, HMAC tokens, rate limiting, input sanitization, privilege escalation prevention, ClawHub, clawhub, agentic-rag, deep-research, workflow-orchestration, ai-assistant, ai-tools, developer-tools, open-source
 
 </details>

SECURITY.md

@@ -37,7 +37,7 @@ Network-AI includes built-in security features:
 
 - **VirusTotal**: Benign (0/64 engines)
 - **OpenClaw Scanner**: Benign, HIGH CONFIDENCE
-- **ClawHub Scanner**: v3.2.1 -- justification bypass vulnerability resolved
+- **ClawHub Scanner**: v3.2.3 -- justification bypass vulnerability resolved
 - **Snyk**: All High/Medium findings resolved in v3.0.3
 
 ## Disclosure Policy

package.json

@@ -1,6 +1,6 @@
 {
   "name": "network-ai",
-  "version": "3.2.2",
+  "version": "3.2.3",
   "description": "AI agent orchestration framework for TypeScript/Node.js - plug-and-play multi-agent coordination with 12 frameworks (LangChain, AutoGen, CrewAI, OpenAI Assistants, LlamaIndex, Semantic Kernel, Haystack, DSPy, Agno, MCP, OpenClaw). Built-in security, swarm intelligence, and agentic workflow patterns.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",