governance-guard

# governance-guard

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

## When to activate

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.

## How to use

### 1. Full pipeline (recommended)

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

```bash
npx tsx scripts/governance.ts pipeline '<intent-json>' --policy policies/standard.yaml
```

The intent JSON must include:
- `skill`: skill identifier
- `tool`: tool/function being invoked
- `model`: LLM model name
- `actionType`: one of `read`, `write`, `execute`, `network`, `create`, `delete`
- `target`: resource being acted upon
- `parameters`: tool parameters (object)
- `dataScope`: data categories accessed (array, e.g. `["personal", "financial"]`)
- `conversationId`: current conversation ID
- `messageId`: current message ID
- `userInstruction`: the user message that triggered this action

### 2. Handle the verdict

The pipeline returns a JSON response:

- If `"governance": "approved"` — proceed with the action
- If `"governance": "deny"` — do NOT proceed; inform the user with the `reason`
- If `"governance": "escalate"` — present the action to the user for approval:

```
Action requires your approval:
  Skill: <skill>
  Action: <actionType> on <target>
  Reason: <reason>
Reply APPROVE or DENY
```

Then resolve:

```bash
npx tsx scripts/governance.ts resolve-escalation <intent-id> approve
# or
npx tsx scripts/governance.ts resolve-escalation <intent-id> deny
```

### 3. Audit decisions

```bash
npx tsx scripts/governance.ts audit --last 10
```

## Policy presets

| Preset | Default | Description |
|--------|---------|-------------|
| `minimal` | approve | Blocks only credentials and d...

# governance-guard

Structural authority separation for autonomous agent actions. An [OpenClaw](https://openclaw.dev) skill that interposes a three-phase governance pipeline between agent intent and execution.

**Core principle**: PROPOSE ≠ DECIDE ≠ PROMOTE. The agent proposes actions. A separate, deterministic policy engine decides admissibility. Only approved actions are promoted to execution. Every transition is witnessed.

## Quick start

```bash
# Install
npm install

# Run the governance pipeline
npx tsx scripts/governance.ts pipeline \
  '{"skill":"browser","tool":"fetch","model":"claude","actionType":"network","target":"https://api.example.com","parameters":{},"dataScope":[],"conversationId":"c1","messageId":"m1","userInstruction":"fetch the API"}' \
  --policy policies/standard.yaml
```

## Architecture

```
Agent Intent  →  PROPOSE  →  DECIDE  →  PROMOTE  →  Execution
                   │            │           │
              Serialize    Evaluate     Gate on
              + hash       policy       approval
                           (no LLM)    + freshness
```

| Phase | Authority | Implementation |
|-------|-----------|---------------|
| PROPOSE | Agent (LLM) | Structured intent capture with SHA-256 hash binding |
| DECIDE | Policy Engine (deterministic) | Pure function: policy + intent → verdict. No LLM. |
| PROMOTE | Execution Gate | Approve verdict + hash match + freshness check |

## Policy presets

| Preset | Default | Use case |
|--------|---------|----------|
| `minimal` | approve | Low friction. Blocks only credentials and destructive commands. |
| `standard` | deny | Recommended. Allows common ops, escalates network/delete. |
| `strict` | deny | Maximum safety. Reads only, everything else escalates. |

See [references/policy-schema.md](references/policy-schema.md) for the full policy file specification.

## Witness chain

Every governance decision is recorded as a hash-chained witness record in `~/....