claude-flow 3.32.26 → 3.32.30

package/v3/@claude-flow/cli/dist/src/commands/metaharness.js

@@ -40,6 +40,7 @@ import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { runFlywheelWorker } from '../services/harness-flywheel-runtime.js';
 import { listFlywheelReceipts, promoteFlywheelCandidate, readFlywheelTransactionState, verifyFlywheelLedger, } from '../services/flywheel-transaction.js';
+import { evaluatePolicyRequest } from '../services/policy-runtime.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Subcommand → plugin script filename
 const SUBCOMMANDS = {
@@ -99,6 +100,8 @@ async function dispatchFlywheel(operation, positional, flags) {
                 proposer: String(flywheelFlag(flags, 'proposer', 'auto')),
                 receiptPrivateKeyPem: privateKeyPath ? readFileSync(resolve(privateKeyPath), 'utf8') : undefined,
                 receiptPublicKeyPem: publicKeyPath ? readFileSync(resolve(publicKeyPath), 'utf8') : undefined,
+                maxConcurrency: Number(flywheelFlag(flags, 'maxConcurrency', 2)),
+                evaluationTimeoutMs: Number(flywheelFlag(flags, 'timeoutMs', 120_000)),
             });
         }
     }
@@ -124,11 +127,28 @@ async function dispatchFlywheel(operation, positional, flags) {
             data = { success: false, reason: 'promote requires <receipt-id> and --public-key <PEM path>' };
         }
         else {
-            const publicKey = readFileSync(resolve(publicKeyPath), 'utf8');
-            data = await promoteFlywheelCandidate(projectRoot, receiptId, {
-                confirm: flywheelFlag(flags, 'confirm', false) === true,
-                trustedPublicKeys: new Set([publicKey]),
-            });
+            const policy = await evaluatePolicyRequest({
+                identity: { id: process.env.CLAUDE_FLOW_PRINCIPAL_ID ?? 'metaharness-local', type: 'agent', roles: ['optimizer'] },
+                action: {
+                    type: 'metaharness.candidate.promote',
+                    resource: receiptId,
+                    environment: 'production',
+                    destructive: true,
+                },
+                context: {
+                    approvalIds: String(flywheelFlag(flags, 'approvalId', '')).split(',').filter(Boolean),
+                },
+            }, projectRoot);
+            if (policy.enforcedOutcome !== 'allowed') {
+                data = { success: false, reason: `policy-${policy.enforcedOutcome}:${policy.reason}`, policyReceiptId: policy.receiptId };
+            }
+            else {
+                const publicKey = readFileSync(resolve(publicKeyPath), 'utf8');
+                data = await promoteFlywheelCandidate(projectRoot, receiptId, {
+                    confirm: flywheelFlag(flags, 'confirm', false) === true,
+                    trustedPublicKeys: new Set([publicKey]),
+                });
+            }
         }
     }
     else {

package/v3/@claude-flow/cli/dist/src/commands/policy.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from '../types.js';
+export declare const policyCommand: Command;
+export default policyCommand;
+//# sourceMappingURL=policy.d.ts.map

package/v3/@claude-flow/cli/dist/src/commands/policy.js

@@ -0,0 +1,107 @@
+import { output } from '../output.js';
+import { autoMigratePolicyStateIfNeeded, evaluatePolicyRequest, loadPolicyState, revokePolicyApproval, setPolicyBudget, setPolicyMode, upsertPolicyRule, verifyPolicyLedger, } from '../services/policy-runtime.js';
+function argJson(value, label) {
+    if (!value)
+        throw new Error(`${label} requires a JSON argument`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`${label} must be valid JSON`);
+    }
+}
+function print(data) {
+    output.writeln(JSON.stringify(data, null, 2));
+    return { success: true, exitCode: 0, data };
+}
+function requireInteractiveAdministrator() {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error('policy administration requires an interactive local terminal');
+    }
+}
+export const policyCommand = {
+    name: 'policy',
+    description: 'Agentic policy engine — evaluate actions, manage rules/approvals, and verify the decision ledger (ADR-324)',
+    options: [
+        { name: 'mode', type: 'string', description: 'Policy mode: legacy | observe | enforce' },
+        { name: 'project-root', type: 'string', description: 'Project root containing .claude-flow/policy' },
+    ],
+    async action(context) {
+        const args = context.args ?? [];
+        const flags = context.flags ?? {};
+        const root = String(flags.projectRoot ?? process.cwd());
+        const operation = args[0] ?? 'status';
+        try {
+            if (operation === 'init' || operation === 'migrate') {
+                if (flags.mode || args[1])
+                    requireInteractiveAdministrator();
+                const migration = await autoMigratePolicyStateIfNeeded(root);
+                const mode = String(flags.mode ?? args[1] ?? '');
+                if (mode) {
+                    if (!['legacy', 'observe', 'enforce'].includes(mode))
+                        throw new Error('mode must be legacy, observe, or enforce');
+                    await setPolicyMode(mode, root);
+                }
+                return print({ ...migration, state: loadPolicyState(root) });
+            }
+            if (operation === 'status') {
+                const state = loadPolicyState(root);
+                return print({
+                    version: state.version,
+                    mode: state.mode,
+                    migratedFrom: state.migratedFrom,
+                    rules: state.rules.length,
+                    budgets: state.budgets.length,
+                    approvals: state.approvals.length,
+                    receipts: state.receipts.length,
+                    ledger: await verifyPolicyLedger(root),
+                });
+            }
+            if (operation === 'evaluate') {
+                return print(await evaluatePolicyRequest(argJson(args[1], 'evaluate'), root));
+            }
+            if (operation === 'rule' && args[1] === 'add') {
+                requireInteractiveAdministrator();
+                const rule = argJson(args[2], 'rule add');
+                await upsertPolicyRule(rule, root);
+                return print({ success: true, ruleId: rule.id });
+            }
+            if (operation === 'budget' && args[1] === 'set') {
+                requireInteractiveAdministrator();
+                const budget = argJson(args[2], 'budget set');
+                await setPolicyBudget(budget, root);
+                return print({ success: true, budgetId: budget.id });
+            }
+            if (operation === 'approve') {
+                throw new Error('approval issuance requires an authenticated human identity adapter; '
+                    + 'the local TTY is not an identity credential');
+            }
+            if (operation === 'revoke') {
+                requireInteractiveAdministrator();
+                if (!args[1])
+                    throw new Error('revoke requires an approval id');
+                return print({ success: await revokePolicyApproval(args[1], root), approvalId: args[1] });
+            }
+            if (operation === 'audit') {
+                const state = loadPolicyState(root);
+                return print({ receipts: state.receipts });
+            }
+            if (operation === 'verify')
+                return print(await verifyPolicyLedger(root));
+            throw new Error(`unknown policy operation: ${operation}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            output.printError(message);
+            return { success: false, exitCode: 1, data: { error: message } };
+        }
+    },
+    examples: [
+        { command: 'ruflo policy status', description: 'Show policy mode and ledger health' },
+        { command: 'ruflo policy init --mode observe', description: 'Migrate an existing install without blocking legacy actions' },
+        { command: 'ruflo policy budget set \'{"id":"daily-model","action":"model.call","maxCostUsd":10,"periodMs":86400000}\'', description: 'Set an atomic policy budget ceiling' },
+        { command: 'ruflo policy evaluate \'{"identity":{"id":"agent-1","type":"agent"},"action":{"type":"deploy","environment":"production"}}\'', description: 'Evaluate an action and write a decision receipt' },
+    ],
+};
+export default policyCommand;
+//# sourceMappingURL=policy.js.map

package/v3/@claude-flow/cli/dist/src/index.js

@@ -120,6 +120,24 @@ export class CLI {
             // stamp read + string compare (sub-ms), and the copy runs at most once per
             // version bump. Best-effort + silent — never blocks or fails a command.
             if (commandPath[0] !== 'init' && commandPath[0] !== 'update') {
+                // ADR-324: existing installations acquire a versioned policy state on
+                // first use. Migration is additive and starts in legacy mode, so older
+                // AgentDB, MCP, hooks, and swarm workflows keep their exact behavior.
+                try {
+                    const { autoMigratePolicyStateIfNeeded } = await import('./services/policy-runtime.js');
+                    const migration = await autoMigratePolicyStateIfNeeded(process.cwd());
+                    if (migration.migrated && this.output.isVerbose()) {
+                        this.output.printDebug(`Initialized agentic policy compatibility state (${migration.mode})`);
+                    }
+                }
+                catch (error) {
+                    // Legacy compatibility requires startup to remain available if the
+                    // policy state cannot be initialized. Enforce-mode actions still
+                    // fail at their authoritative dispatcher when state is unreadable.
+                    if (this.output.isVerbose()) {
+                        this.output.printDebug(`Policy compatibility migration skipped: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                }
                 try {
                     const { autoRefreshHelpersIfStale } = await import('./init/helper-refresh.js');
                     // alsoRefreshGlobal:true — refresh ~/.claude/helpers too, not just

package/v3/@claude-flow/cli/dist/src/init/claudemd-generator.js

@@ -19,6 +19,49 @@ function behavioralRules() {
 - Keep files under 500 lines
 - Validate input at system boundaries`;
 }
+function policyGovernedWorkflow() {
+    return `## Ruflo Capability Brain & Implementation Loop
+
+Ruflo is the coordination ledger and policy decision point. Claude Code is the
+executor: after a Ruflo coordination call, continue implementing the task.
+
+When it is registered, call
+\`guidance_brain({ mode: "recommend", task: "..." })\` before complex Ruflo
+work. Use its live registry instead of guessing tool names. Treat
+\`registered\`, \`configured\`, \`reachable\`, \`healthy\`, and \`authorized\`
+as separate facts. If the brain is unavailable, continue with the compatible
+\`guidance_recommend\` tool, CLI discovery, and repository instructions.
+
+Follow the returned loop:
+
+1. Recall memory and ADR constraints.
+2. Inspect source, runtime, dependencies, policy, and health.
+3. Route to the smallest capable topology, agents, skills, and tools.
+4. Plan acceptance criteria, safety envelope, ownership, and validation.
+5. Execute in isolated scopes; the coding agent performs the work.
+6. Test focused, regression, and failure paths.
+7. Validate types, security, policy, compatibility, and artifacts.
+8. Benchmark a source-bound candidate against a source-bound baseline.
+9. Optimize measured bottlenecks without weakening safety.
+10. Bind claims and evidence to exact source/build receipts.
+11. Reconcile concurrent handoffs and disclose limitations.
+12. Publish only through a separately authorized release gate.
+
+### Concurrency and authority
+
+- Never allow two writers in one worktree; give each writing agent an isolated
+  worktree and explicit file ownership.
+- Read-only research may run concurrently and report findings to the owner.
+- Only the integration owner edits shared manifests and lockfiles or reconciles
+  overlapping changes.
+- A child may drop capabilities but cannot add tools, network, secrets, spend,
+  concurrency, namespaces, or delegation depth.
+- A lease or claim coordinates ownership; it does not authorize a side effect.
+- Darwin, Flywheel, MetaHarness, memory, and neural systems may propose or
+  evaluate candidates but cannot self-promote or expand their SafetyEnvelope.
+- Bind tests, benchmarks, policy decisions, and release evidence to an exact
+  commit or immutable dirty-worktree snapshot.`;
+}
 function agentComms() {
     return `## Agent Comms (SendMessage-First Coordination)
 
@@ -61,8 +104,10 @@ SendMessage({ to: "researcher", summary: "Start", message: "[task context]" })
 - ALWAYS name agents — \`name: "role"\` makes them addressable
 - ALWAYS include comms instructions in prompts — who to message, what to send
 - Spawn ALL agents in ONE message with \`run_in_background: true\`
-- After spawning: STOP, tell user what's running, wait for results
-- NEVER poll status — agents message back or complete automatically`;
+- After spawning, continue independent local work; wait only when a dependency
+  genuinely blocks progress
+- Do not poll repeatedly — agents message back or complete automatically
+- Give every writing agent an isolated worktree and a non-overlapping file scope`;
 }
 function swarmConfig(options) {
     return `## Swarm & Routing
@@ -283,6 +328,7 @@ CLAUDE_FLOW_MEMORY_PATH=./data/memory
 const TEMPLATE_SECTIONS = {
     minimal: [
         behavioralRules,
+        (_opts) => policyGovernedWorkflow(),
         (_opts) => agentComms(),
         swarmConfig,
         (_opts) => buildAndTest(),
@@ -291,6 +337,7 @@ const TEMPLATE_SECTIONS = {
     ],
     standard: [
         behavioralRules,
+        (_opts) => policyGovernedWorkflow(),
         (_opts) => agentComms(),
         swarmConfig,
         (_opts) => memoryAndLearning(),
@@ -301,6 +348,7 @@ const TEMPLATE_SECTIONS = {
     ],
     full: [
         behavioralRules,
+        (_opts) => policyGovernedWorkflow(),
         (_opts) => agentComms(),
         swarmConfig,
         (_opts) => memoryAndLearning(),
@@ -315,6 +363,7 @@ const TEMPLATE_SECTIONS = {
     ],
     security: [
         behavioralRules,
+        (_opts) => policyGovernedWorkflow(),
         (_opts) => agentComms(),
         swarmConfig,
         (_opts) => securitySection(),
@@ -326,6 +375,7 @@ const TEMPLATE_SECTIONS = {
     ],
     performance: [
         behavioralRules,
+        (_opts) => policyGovernedWorkflow(),
         (_opts) => agentComms(),
         swarmConfig,
         (_opts) => performanceSection(),
@@ -338,6 +388,7 @@ const TEMPLATE_SECTIONS = {
     ],
     solo: [
         behavioralRules,
+        (_opts) => policyGovernedWorkflow(),
         (_opts) => agentComms(),
         (_opts) => memoryAndLearning(),
         (_opts) => buildAndTest(),

package/v3/@claude-flow/cli/dist/src/mcp-client.js

@@ -21,6 +21,8 @@ import { analyzeTools } from './mcp-tools/analyze-tools.js';
 import { progressTools } from './mcp-tools/progress-tools.js';
 import { embeddingsTools } from './mcp-tools/embeddings-tools.js';
 import { claimsTools } from './mcp-tools/claims-tools.js';
+import { policyTools } from './mcp-tools/policy-tools.js';
+import { authorizeMcpTool, classifyMcpTool } from './services/policy-runtime.js';
 import { securityTools } from './mcp-tools/security-tools.js';
 import { transferTools } from './mcp-tools/transfer-tools.js';
 // V2 Compatibility tools
@@ -47,7 +49,7 @@ import { wasmAgentTools } from './mcp-tools/wasm-agent-tools.js';
 // the local WASM-sandboxed `wasm_agent_*` (rvagent) tools. Lives in the
 // `ruflo-agent` plugin.
 import { managedAgentTools } from './mcp-tools/managed-agent-tools.js';
-import { guidanceTools } from './mcp-tools/guidance-tools.js';
+import { configureGuidanceToolProvider, guidanceTools, } from './mcp-tools/guidance-tools.js';
 import { autopilotTools } from './mcp-tools/autopilot-tools.js';
 // ADR-150 — MetaHarness MCP tools (score / genome / mcp-scan / threat-model / oia-audit)
 import { metaharnessTools } from './mcp-tools/metaharness-tools.js';
@@ -127,6 +129,10 @@ registerTools([
     ...progressTools,
     ...embeddingsTools,
     ...claimsTools,
+    // Remote MCP exposes evaluation/status only. Administrative mutation is a
+    // local CLI bootstrap/recovery operation until the server has authenticated
+    // human identity propagation.
+    ...policyTools.filter((tool) => ['policy_evaluate', 'policy_status'].includes(tool.name)),
     ...securityTools,
     ...transferTools,
     // V2 Compatibility tools
@@ -167,6 +173,15 @@ registerTools([
     // ADR-164 Phase 4 §5.1.8 — http_fetch (1 tool, secure-by-default HTTP probe)
     ...httpFetchTools,
 ]);
+// The capability brain consumes the completed live registry. This is injected
+// after registration to keep guidance honest and avoid a registry import cycle.
+configureGuidanceToolProvider(() => Array.from(TOOL_REGISTRY.values()).map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    category: tool.category,
+    tags: tool.tags,
+    version: tool.version,
+})));
 /**
  * MCP Client Error
  */
@@ -211,6 +226,15 @@ export async function callMCPTool(toolName, input = {}, context) {
         throw new MCPClientError(`MCP tool not found: ${toolName}`, toolName);
     }
     try {
+        // ADR-324: one policy chokepoint for every local CLI/MCP invocation.
+        // Policy administration is not exempt: authorization calls the engine
+        // directly, so there is no recursive MCP dispatch. In enforce mode an
+        // administrator must explicitly allow policy.* actions or use the local
+        // CLI bootstrap path.
+        const decision = await authorizeMcpTool(toolName, input, context, classifyMcpTool(toolName));
+        if (decision.enforcedOutcome !== 'allowed') {
+            throw new Error(`policy-${decision.enforcedOutcome}:${decision.reason}; receipt=${decision.receiptId}`);
+        }
         // Call the tool handler
         const result = await tool.handler(input, context);
         // ADR-146 P2: scan every tool result for indirect-injection before it

package/v3/@claude-flow/cli/dist/src/mcp-tools/capability-brain.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Ruflo capability brain.
+ *
+ * This module is deliberately data-only: it describes the complete MCP surface
+ * without importing the MCP registry. The registry injects its live tool list
+ * into guidance-tools after registration, which avoids a circular dependency
+ * and prevents documentation from being mistaken for runtime availability.
+ */
+export type CapabilityMaturity = 'stable' | 'experimental' | 'compatibility';
+export type CapabilityAuthority = 'advisory' | 'capability-plane' | 'control-plane';
+export type CapabilityRisk = 'read-only' | 'reversible' | 'privileged';
+export type AvailabilityState = boolean | 'unknown';
+export type CapabilityRiskFlag = 'read' | 'local-write' | 'memory-poisoning' | 'process-exec' | 'network' | 'credential-pii' | 'spend' | 'concurrency' | 'destructive' | 'approval' | 'promotion';
+export interface CapabilityToolMetadata {
+    name: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+    version?: string;
+}
+export interface CapabilityHealth {
+    /** Present in this running MCP server's registry. */
+    registered: boolean;
+    /** Requires an operator/provider configuration check. */
+    configured: AvailabilityState;
+    /** Requires a non-mutating dependency probe. */
+    reachable: AvailabilityState;
+    /** Requires a service-specific health check. */
+    healthy: AvailabilityState;
+    /** Requires a policy evaluation for the current subject and action. */
+    authorized: AvailabilityState;
+}
+export interface CapabilityDomainDefinition {
+    id: string;
+    name: string;
+    description: string;
+    prefixes: string[];
+    exactTools?: string[];
+    taskSignals: string[];
+    commands: string[];
+    skills: string[];
+    agents: string[];
+    maturity: CapabilityMaturity;
+    authority: CapabilityAuthority;
+    risk: CapabilityRisk;
+    optionalRuntime?: boolean;
+    packageOwners?: string[];
+    pluginOwners?: string[];
+    availabilityMode?: 'always-local' | 'conditional-registration' | 'registered-degraded' | 'configured-remote' | 'policy-filtered';
+    /**
+     * Conservative union of effects possible anywhere in this domain.
+     * Individual tool descriptors may narrow or expand this reviewed profile.
+     */
+    riskFlags?: CapabilityRiskFlag[];
+    loopPhases?: Array<'discover' | 'recall' | 'authorize-claim' | 'route-plan' | 'branch-propose' | 'execute' | 'validate-critique' | 'commit-validated' | 'observe' | 'publish'>;
+    useWhen: string;
+    verifyBeforeUse: string[];
+}
+export interface CapabilityDomain extends CapabilityDomainDefinition {
+    packageOwners: string[];
+    pluginOwners: string[];
+    availabilityMode: NonNullable<CapabilityDomainDefinition['availabilityMode']>;
+    riskFlags: NonNullable<CapabilityDomainDefinition['riskFlags']>;
+    loopPhases: NonNullable<CapabilityDomainDefinition['loopPhases']>;
+    tools: Array<CapabilityToolMetadata & {
+        domain: string;
+        packageOwner: string;
+        pluginOwner?: string;
+        availabilityMode: NonNullable<CapabilityDomainDefinition['availabilityMode']>;
+        authority: CapabilityAuthority;
+        risk: CapabilityRisk;
+        riskFlags: NonNullable<CapabilityDomainDefinition['riskFlags']>;
+        loopPhases: NonNullable<CapabilityDomainDefinition['loopPhases']>;
+    }>;
+    health: CapabilityHealth;
+}
+export interface CapabilityBrain {
+    schemaVersion: 'ruflo.capability-brain/v1';
+    generatedAt: string;
+    truthModel: {
+        catalogued: string;
+        registered: string;
+        configured: string;
+        reachable: string;
+        healthy: string;
+        authorized: string;
+    };
+    domains: CapabilityDomain[];
+    cliCommands: string[];
+    implementationLoop: ImplementationLoopStep[];
+    coverage: {
+        registeredToolCount: number;
+        classifiedToolCount: number;
+        coveragePercent: number;
+        fallbackClassifiedTools: string[];
+        duplicateToolNames: string[];
+    };
+}
+/** Top-level commands from the CLI command loader. Kept as a checked manifest. */
+export declare const RUFLO_CLI_COMMANDS: readonly ["init", "start", "status", "task", "session", "agent", "swarm", "memory", "mcp", "config", "migrate", "hooks", "workflow", "hive-mind", "process", "daemon", "version", "neural", "security", "performance", "providers", "plugins", "deployment", "claims", "policy", "embeddings", "completions", "doctor", "verify", "analyze", "route", "progress", "issues", "update", "ruvector", "benchmark", "guidance", "appliance", "appliance-advanced", "transfer-store", "cleanup", "autopilot", "gaia-bench", "metaharness", "eject", "funnel", "settings", "auth", "proxy", "advisor", "spinner", "announcements"];
+export interface ImplementationLoopStep {
+    id: string;
+    name: string;
+    purpose: string;
+    preferredTools: string[];
+    requiredEvidence: string;
+    mutation: 'none' | 'workspace' | 'external';
+}
+export declare const IMPLEMENTATION_LOOP: readonly ImplementationLoopStep[];
+/**
+ * Domain order is significant: narrow/specialized matches precede broad
+ * compatibility prefixes. Every registered tool is eventually classified by
+ * the final runtime-services domain, but fallback classifications are reported.
+ */
+export declare const CAPABILITY_DOMAINS: readonly CapabilityDomainDefinition[];
+export declare function classifyCapabilityTool(tool: CapabilityToolMetadata): CapabilityDomainDefinition;
+export declare function buildCapabilityBrain(registeredTools: readonly CapabilityToolMetadata[], now?: Date): CapabilityBrain;
+export interface CapabilityRecommendation {
+    task: string;
+    domains: Array<{
+        id: string;
+        name: string;
+        score: number;
+        registeredTools: string[];
+        health: CapabilityHealth;
+        authority: CapabilityAuthority;
+        risk: CapabilityRisk;
+        verifyBeforeUse: string[];
+    }>;
+    implementationLoop: ImplementationLoopStep[];
+    guardrails: string[];
+}
+export declare function recommendCapabilities(brain: CapabilityBrain, task: string): CapabilityRecommendation;
+//# sourceMappingURL=capability-brain.d.ts.map