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.
In a typical DBO project lifecycle, 60-70% of tasks are irreducibly human: permit meetings, construction inspections, commissioning walkthroughs, and procurement — negotiation on pricing, specs-vs-pricing tradeoffs, lead time tradeoffs, and third-party QA/QC inspections. The PM board is not agent coordination overhead — it is the record of decision for the entire project. The undocumented "quick question" during construction can cost hundreds of thousands of dollars in rework during installation or commissioning. Every decision needs to be traceable.
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.
Why These Gates Are Permanent
Physical reality
A model predicts effluent COD from an AnMBR; the actual effluent is higher due to irregular CIP sanitizer usage that slightly inhibits the methanogens, resulting in higher residual VFA concentrations. This kind of operational nuance is not possible to decipher from structured data alone. The approval gate is where someone with access to physical reality certifies the model's output.
Human ownership of deliverables
Human ownership of engineering deliverables is a regulatory requirement, not a workflow preference. The "swarm" paradigm of rapid agent-to-agent collaboration is fundamentally at odds with how work must get done in this field. Agents compute; humans own the result.
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.