\r \r

governance-guard\r

\r Governance guard enforces structural authority separation on all agent actions through a PROPOSE-DECIDE-PROMOTE pipeline.\r \r

When to activate\r

\r Before performing any write, execute, network, create, or delete action. The governance pipeline MUST be invoked before the action executes. Read actions may also be governed under standard or strict policies.\r \r

How to use\r

\r

1. Full pipeline (recommended)\r

\r Run the complete PROPOSE → DECIDE → PROMOTE pipeline in a single call:\r \r

npx tsx scripts/governance.ts pipeline '\x3Cintent-json>' --policy policies/standard.yaml\r
```\r
\r
The intent JSON must include:\r
- `skill`: skill identifier\r
- `tool`: tool/function being invoked\r
- `model`: LLM model name\r
- `actionType`: one of `read`, `write`, `execute`, `network`, `create`, `delete`\r
- `target`: resource being acted upon\r
- `parameters`: tool parameters (object)\r
- `dataScope`: data categories accessed (array, e.g. `["personal", "financial"]`)\r
- `conversationId`: current conversation ID\r
- `messageId`: current message ID\r
- `userInstruction`: the user message that triggered this action\r
\r
### 2. Handle the verdict\r
\r
The pipeline returns a JSON response:\r
\r
- If `"governance": "approved"` — proceed with the action\r
- If `"governance": "deny"` — do NOT proceed; inform the user with the `reason`\r
- If `"governance": "escalate"` — present the action to the user for approval:\r
\r
```\r
Action requires your approval:\r
  Skill: \x3Cskill>\r
  Action: \x3CactionType> on \x3Ctarget>\r
  Reason: \x3Creason>\r
Reply APPROVE or DENY\r
```\r
\r
Then resolve:\r
\r
```bash\r
npx tsx scripts/governance.ts resolve-escalation \x3Cintent-id> approve\r
# or\r
npx tsx scripts/governance.ts resolve-escalation \x3Cintent-id> deny\r
```\r
\r
### 3. Audit decisions\r
\r
```bash\r
npx tsx scripts/governance.ts audit --last 10\r
```\r
\r
## Policy presets\r
\r
| Preset | Default | Description |\r
|--------|---------|-------------|\r
| `minimal` | approve | Blocks only credentials and destructive commands. Lowest friction. |\r
| `standard` | deny | Allows common ops, escalates network and data access. Recommended. |\r
| `strict` | deny | Reads only. Everything else requires explicit approval. Maximum safety. |\r
\r
## Fail-closed guarantee\r
\r
If any error occurs during governance evaluation, the default verdict is **DENY**. Missing policy files result in DENY ALL. This is by design. The system fails safe, never open.\r
\r
## Configuration\r
\r
Governance data is stored in `~/.openclaw/governance/`:\r
- `policy.yaml` — active policy file\r
- `witness.jsonl` — append-only, hash-chained audit log\r
\r
## Verify witness chain\r
\r
```bash\r
npx tsx scripts/governance.ts verify\r
```\r
\r
Any tampering with historical records is detected by recomputing the hash chain from genesis.\r