Governance Architecture
Agents Draft. Engineers Decide.
A single unrestricted agent is ungovernable at enterprise scale. PuranOS enforces governance through tool boundaries, not prompts.
Why Scoped Agents
Each agent persona has four independent permission scopes, all enforced at the infrastructure level — not in system prompts:
Tool scope
.mcp.json controls which servers are available. pe-process gets simulation engines; it cannot touch procurement tools. If the tool isn't in the config, it doesn't exist.
Expertise scope
Which skills the agent can run. Defined per persona, not per session. A separation specialist runs membrane design skills, not financial modeling.
Authority scope
Side-effect policy per task: allowed_side_effects: ["mail.draft"] = draft only, no send. Enforced at the MCP server boundary.
Boundary scope
Delegation protocol for out-of-scope work. Can't act — must delegate via OpenProject child task. Every delegation is traceable.
Delegation Protocol
Agent-to-agent handoffs happen through OpenProject work packages, not hidden function calls. This is a design choice grounded in research: explicit, externalized state produces better coordination than implicit message passing.
pe-lead creates child task for pe-separation
→ Communication agent routes to the right persona
→ pe-separation executes with clean context (no stale history)
→ Results posted as structured OP comment
→ Parent resumes when all children complete
Every delegation creates a traceable child task. Humans can intercept, re-assign, or reject at any point. The project board IS the coordination layer.
Human Approval Gates
OpenProject status workflow
Tasks transition New → Open → Review → Closed. Agent moves to "Review"; human closes. No agent auto-approves its own work.
Predecessor blocking
Agent task only runnable when predecessors complete. No out-of-order execution. Dependencies enforced by OpenProject, not by the agent.
Structured approval state
Explicit typed approval_state field checked before any agent proceeds. Not a prompt suggestion — a hard gate.
Audit Trail
Every action is recorded in the shared PostgreSQL execution ledger. The system can answer "which agent modified this record, when, and in response to what task" from structured logs.
work_items Every unit of agent workstate_transitions Immutable status change history with reasonsside_effect_log Every mutation — emails, task creation, calendar eventsdelegation_log Parent-child work relationshipsRead the full governance documentation
Persona boundaries, delegation semantics, and the hybrid state model in detail.