A formal specification and reference implementation for deterministic AI agent governance.
The Governed State Machine is a formal extension of the classical finite state machine that adds two things every governance system requires: an authority function that determines who is permitted to do what, and a defined response to indeterminacy that routes unresolvable situations to human authority rather than failing silently.
The result is an architecture where every proposed agent action is intercepted, evaluated against a signed entitlement registry, and given one of three deterministic verdicts — Fire (authorised, execute), Reject (not permitted, halt with reason), or Escalate (indeterminate, route to human authority with named trigger and full audit record). There is no fourth option.
A conformant GSM implementation requires four layers, each necessary for the governance guarantee to hold:
Registry — Entitlements extracted from policy documents, normalised into formal structure, cryptographically signed, and stored with full provenance. Queryable by (role, activity, context). Physically separate from agent configuration.
Vocabulary — Activity vocabularies defined for each governance touchpoint. A classifier (the map() function) translates agent proposals into formal activity types, with confidence thresholds and mandatory audit logging.
Kernel — The evaluation loop. Intercepts every proposed action, evaluates entitlements, terms, and conditions against current context, and returns a deterministic verdict. Total — every input produces a defined output.
Confinement — Mandatory gateway architecture ensuring the kernel cannot be bypassed. Implemented at infrastructure level, not application level. An agent that calls the kernel voluntarily can be manipulated into not calling it.
Remove any one layer and the governance guarantee does not hold.
capsicum-gsm/
├── spec/ # The formal specification
│ ├── gsm-specification.md # Full prose specification
│ ├── formal/ # Mathematical definitions
│ │ └── definitions.md # The 9-tuple and evaluation algebra
│ ├── entitlement-schema.json # JSON Schema for entitlement entries
│ ├── verdict-schema.json # JSON Schema for kernel verdicts
│ ├── escalation-routing.md # Escalation triggers and routing
│ └── conformance.md # What "GSM-conformant" means
├── reference-implementation/ # Executable reference in Python
│ ├── kernel.py # The evaluation loop
│ ├── registry.py # Entitlement registry with query interface
│ ├── vocabulary.py # Activity vocabulary and map() stub
│ └── examples/
│ └── loan_approval/ # Mortgage scenario from the series
│ ├── entitlements.json # Registry entries
│ └── run_scenarios.py # Five demo scenarios
├── docs/
│ ├── translation-integrity-pipeline.md
│ ├── confinement-architecture.md
│ └── commercial-implementations.md
├── LICENSE.md
├── CONTRIBUTING.md
└── CHANGELOG.md
cd reference-implementation
python examples/loan_approval/run_scenarios.pyThe reference implementation requires Python 3.10+ with no external dependencies. It demonstrates five scenarios: a clean Fire, a Term breach rejection, a missing entitlement escalation, a deontic conflict escalation, and a missing context variable escalation.
The map() function in the reference implementation uses exact string matching. This is intentional — it demonstrates the formal evaluation semantics without introducing classifier complexity. Production implementations would use an ML-based classifier with confidence thresholds as described in the specification.
The GSM is formalised in the paper "A Logical Model of Endeavour: Toward a Formal Framework for AI Reasoning and Governance" (Roach, 2026), which presents it as a typed nine-tuple extending classical finite state machine theory with first-class authority and indeterminacy constructs.
The conceptual foundations, formal specification, and implementation guide are developed across the Discovered Not Invented series:
- Post 8 — The Architecture — Seven components, three verdicts, the mortgage worked example
- Post 9 — The Formal Object — The GSM as a mathematical specification
- Post 10 — Building the Machine That Can't Lie — Full implementation guide
A browser-based prototype demonstrating the kernel against five live scenarios is available at capsicum-kernel.
The Governed State Machine originates in the CAPSICUM Framework for Strategically Aligned Business Architecture (Roach, 2011), a formal ontology of purposeful action. In CAPSICUM, governance is not a layer applied to a process — it is constitutive of the process. The Interaction-Activity-Outcome-Responsibility quartet, the deontic entitlement structure, and the separation of Terms (granting-time) from Conditions (runtime) are all ontological commitments, not implementation choices.
The governance semantics of the GSM are derived from the ontology: an activity is a governance touchpoint not because it is flagged as one, but because an Entitlement is mapped to the Interaction associated with that Activity. The relationship carries the semantics. The ontology, not application-layer metadata, determines what is governed.
PlausibleBA and the Value Cognition Canvas (VCC) are the primary commercial implementations of the CAPSICUM framework, providing value stream mapping, friction analysis, entitlement management, and governance visualisation on top of the formal GSM specification defined in this repository.
The specification is open. The reference implementation is open source. Commercial implementations add the tooling that makes the specification practical across an enterprise.
See CONTRIBUTING.md for guidelines. The specification is the source of truth; code must conform to the spec.
- Specification (
spec/): Creative Commons CC-BY 4.0 - Code (
reference-implementation/): Apache License 2.0
See LICENSE.md for full texts.
Terry Roach is a UTS Research Fellow and Chair of the IIBA. He completed his PhD at UNSW in 2011 developing the CAPSICUM Framework, a formal ontology of purposeful action.