Ruflo v3.32.27 agentic policy engine — end-user quick start

ruflo-v3.32.27-quick-start.md

Ruflo v3.32.27: put enforceable boundaries around autonomous agents

Agents are most useful when they can act, delegate, and work in parallel. They are also easiest to trust when their authority is explicit.

Ruflo v3.32.27 adds an agentic policy engine between an agent's intent and a consequential action. You can roll it out without breaking an existing installation, observe what it would allow or deny, and then enforce rules, budgets, approvals, delegated capability envelopes, and concurrency limits. Every decision produces a hash-linked receipt for later audit.

This gives teams a practical control plane for:

• limiting model or tool spend by principal, action, resource, and time window;
• requiring approval for production deploys, destructive operations, or MetaHarness promotion;
• preventing a delegated worker from gaining more authority than its parent;
• bounding concurrent Codex workers and MetaHarness evaluations;
• restricting tools, MCP servers, namespaces, environments, network access, and destructive actions;
• auditing decisions and detecting receipt-ledger tampering;
• introducing controls gradually through legacy, observe, and enforce modes.

The core rule is simple: Ruflo coordinates and authorizes; Codex workers and other agents execute.

Install or upgrade

Install the verified v3.32.27 release artifacts:

npm install --global \
  https://github.com/ruvnet/ruflo/releases/download/v3.32.27/claude-flow-security-3.0.0-alpha.13.tgz \
  https://github.com/ruvnet/ruflo/releases/download/v3.32.27/claude-flow-cli-3.32.27.tgz \
  https://github.com/ruvnet/ruflo/releases/download/v3.32.27/ruflo-3.32.27.tgz
ruflo --version
ruflo policy status

The normal npm install --global ruflo@3.32.27 path will become available after npm trusted-publisher authorization is completed.

1. Inspect and migrate safely

Existing installations migrate automatically in legacy mode. That preserves previous behavior while creating the versioned policy state.

ruflo policy init
ruflo policy status
ruflo policy verify

Policy administration is deliberately restricted to an interactive local terminal. Run the following mode changes from a TTY.

Start with observation:

ruflo policy init --mode observe

In observe, Ruflo records the policy outcome but continues to allow actions. Capability-envelope violations are the exception: delegated authority is a hard boundary in every mode.

2. Add a production-deploy rule

The CLI accepts policy objects as JSON:

ruflo policy rule add '{
  "id": "production-deploy-approval",
  "description": "Require human approval for production deployments",
  "priority": 100,
  "effect": "require_approval",
  "actions": ["deploy"],
  "environments": ["production"],
  "approvalTtlMs": 1800000
}'

Add an ordinary development allow rule:

ruflo policy rule add '{
  "id": "allow-development",
  "priority": 10,
  "effect": "allow",
  "actions": ["*"],
  "environments": ["development"]
}'

Rules can match principals, identity types, roles, actions, resources, and environments. Constraints can set maximum cost, tokens, concurrency, network access, destructive access, allowed namespaces, signed evidence, and required provenance.

3. Add an atomic spend and token budget

This example caps model.call at USD 10 and 500,000 tokens per day:

ruflo policy budget set '{
  "id": "daily-model-budget",
  "action": "model.call",
  "maxCostUsd": 10,
  "maxTokens": 500000,
  "periodMs": 86400000
}'

When a matching budget exists, requests must report the corresponding costUsd or tokens value. Missing metering fails the policy decision instead of silently bypassing the ceiling.

4. Evaluate a request

ruflo policy evaluate '{
  "identity": {
    "id": "codex-worker-1",
    "type": "agent",
    "roles": ["developer"]
  },
  "action": {
    "type": "model.call",
    "resource": "openrouter",
    "environment": "development",
    "costUsd": 0.12,
    "tokens": 8000,
    "concurrency": 2,
    "network": true
  }
}'

The response distinguishes:

• outcome: what the configured policy decided;
• enforcedOutcome: what Ruflo actually enforced in the current mode;
• reason and matchedRules: why;
• receiptId: the append-only audit record.

Review and verify the ledger:

ruflo policy audit
ruflo policy verify

5. Use reduced capability envelopes for delegated workers

A child worker should receive only the authority required for its task. A request can carry a capability envelope:

{
  "context": {
    "envelope": {
      "actions": ["test.*", "memory.read"],
      "tools": ["shell", "memory_search"],
      "readNamespaces": ["patterns"],
      "writeNamespaces": [],
      "environments": ["development"],
      "maxCostUsd": 1,
      "maxTokens": 50000,
      "maxConcurrency": 2,
      "network": false,
      "destructive": false,
      "delegationDepth": 0,
      "expiresAt": 1785297600000
    }
  }
}

Envelope checks are monotonic: delegation may reduce authority but cannot expand tools, servers, namespaces, network, spend, destructive access, concurrency, expiry, or delegation depth.

6. Move to enforcement

After reviewing observation receipts and adding the required allow, deny, and approval rules:

ruflo policy init --mode enforce
ruflo policy status

observe and enforce are default-deny when no rule matches. Make sure the ordinary actions you depend on have explicit allow rules before switching.

Approval issuance is not exposed as a local convenience command. An approval must be issued through an authenticated human identity adapter; a local TTY alone is not identity proof. Existing approvals can be revoked interactively:

ruflo policy revoke <approval-id>

Policy-governed concurrent Codex development

Use one bounded hierarchical swarm, fan out only independent work, and give every writing worker its own git worktree. Read-only researchers may share a checkout. Assign one integration owner for shared manifests and lockfiles.

npx claude-flow memory search \
  --query "policy engine release workflow" \
  --namespace patterns

npx claude-flow swarm init \
  --topology hierarchical \
  --max-agents 4

Recommended workflow:

1. Search AgentDB before planning.
2. Define a reduced capability envelope for each worker.
3. Give each writer a unique worktree.
4. Run independent tasks concurrently within the hard fan-out limit.
5. Cancel dependent work on a policy denial or dependency failure.
6. Integrate committed handoffs in dependency order.
7. Run scoped tests, the full gate, and ledger verification.
8. Store the successful pattern and retain policy/MetaHarness receipts.

Govern MetaHarness evaluation and promotion

MetaHarness can evaluate bounded candidates concurrently. It cannot authorize its own promotion or expand its SafetyEnvelope.

ruflo metaharness flywheel run \
  --project-root . \
  --proposer local \
  --sample 40 \
  --max-concurrency 2 \
  --timeout-ms 120000 \
  --private-key /path/to/flywheel-private.pem \
  --public-key /path/to/flywheel-public.pem

ruflo metaharness flywheel receipts --project-root .
ruflo metaharness flywheel history --project-root .

Promotion is a separate policy-controlled operation:

ruflo metaharness flywheel promote <receipt-id> \
  --project-root . \
  --public-key /path/to/flywheel-public.pem \
  --approval-id <authenticated-approval-id> \
  --confirm

The candidate still must have an accepted, trusted receipt and pass the atomic compare-and-swap promotion transaction. Policy authorization is an additional boundary, not a replacement for the flywheel safety gate.

AgentDB compatibility

Previous installations and existing AgentDB data continue to work. The release adds typed provenance filters for user claims, agent output, system observations, tool results, and unknown legacy records. Missing provenance is treated as unknown; it is not silently upgraded to trusted evidence.

Use legacy first, inspect receipts in observe, and enable enforce only after your rules cover normal operation.

Troubleshooting

An action is allowed in observe even though outcome is denied

That is the observation contract. Check enforcedOutcome; switch to enforce after reviewing the receipts.

A delegated action is denied in legacy or observe

Capability envelopes are always hard boundaries. Reduce the requested action or issue an appropriate parent envelope; do not widen it in the child.

A budgeted request says metering is required

Include costUsd and/or tokens on every request matched by that budget.

policy rule add, budget set, or mode changes fail in automation

Local administration requires an interactive TTY. Automations should call a trusted policy administration or identity adapter instead of simulating a terminal.

MetaHarness packages are absent

They remain optional. Ruflo and the local policy engine continue to operate, and explicit MetaHarness commands degrade or fail closed according to the selected mode.

More information

• ADR-324: Agentic policy engine and Codex swarm
• ADR-323: typed AgentDB provenance
• ADR-322: governed MetaHarness flywheel
• Implementation PR #2822