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 relationshipsKnowledge Wiki
Not all institutional knowledge fits in a schema'd database. Meeting synthesis from vendor calls, research paper summaries, design rationale notes, competitive intelligence, and commissioning lessons are inherently narrative. The Knowledge Wiki — a file-backed markdown vault exposed to agents through the wiki-graph MCP server, with wikilink graph traversal and an append-only operations log — is where this unstructured context lives.
The wiki is agent-written and agent-read. A two-flow discipline keeps it coherent: any agent can drop raw captures into dated channel folders, but only a dedicated knowledgebase agent writes to the compiled articles, running reconciliation nightly. Humans query the wiki by asking an agent — they do not open the vault directly. The maintenance burden stays with the agents; the knowledge surfaces through every agent conversation that needs it.
Drop raw sources
Any agent writes inbound captures — meeting transcripts, email threads, Teams chats, WhatsApp alerts, vendor calls, web clips — to raw/<channel>/<date>-<slug>.md with typed frontmatter (title, source, date, actor, refs, tags). Raw drops are immutable; corrections come as new dated files.
Reconcile into linked articles
The knowledgebase agent runs a nightly reconcile: it reads uncompiled raw sources, uses search_traverse to find related compiled articles, and either updates an existing page or creates a new one under concepts/, people/, projects/, decisions/, or glossary/, with [[wikilinks]] to related pages and sources: frontmatter pointing back to the raw drops. Phonetic-variant entity resolution keeps ASR-mangled proper nouns from splitting the graph.
File outputs back
Agent work products — design decision rationale, sizing justifications, commissioning lessons, comparison tables, research reports — are filed under output/ and summarized as new or updated compiled pages. Today's one-off exploration becomes tomorrow's reusable knowledge. The wiki grows as a byproduct of work, not as a separate documentation effort.
Query alongside structured data
When an agent needs context beyond what the schema'd databases hold, it runs search_traverse from compiled/_index.md to graph-walk from curated knowledge, then uses fragment to read the relevant section without loading the whole page. A weekly lint pass (broken links, orphans, stale pages, hub detection) keeps retrieval quality high. The result is narrative context — the "why" behind the "what" stored in structured records.
The schema'd substrate tells you the equipment spec. The wiki tells you why that spec was chosen over the alternative the vendor initially proposed.
Read the full governance documentation
Persona boundaries, delegation semantics, and the hybrid state model in detail.