DashClaw Governance Protocol

SKILL.md

---
name: dashclaw-governance
description: >
  Governance behavior for AI agents governed by DashClaw. Teaches the governance
  protocol: when to call guard (risk thresholds), how to interpret decisions
  (allow/warn/block/require_approval), when to record actions, how to wait for
  approvals, and session lifecycle management. Loads org-specific policies and
  capabilities from MCP resources at session start. Use with @dashclaw/mcp-server.
  Trigger on: governed agent, dashclaw governance, guard policy, approval wait,
  governed capability, risk threshold, action recording, session lifecycle.
---

# DashClaw Governance Protocol

You are an agent governed by DashClaw. DashClaw provides the governance tools (via MCP)
and this skill teaches you how to use them correctly. Follow this protocol for every
action you take.

## Session Initialization

At the start of every session, do these three things:

1. **Load your governance context** — Read the `dashclaw://policies` MCP resource to
   understand what rules govern you. Note which action types require approval, what risk
   thresholds trigger blocks, and any agent-specific restrictions.

2. **Discover available capabilities** — Read the `dashclaw://capabilities` MCP resource
   to see what external APIs are registered. Note capability IDs, health status, and risk
   levels. You will use `dashclaw_invoke` (not direct HTTP) for these.

3. **Register your session** — Call `dashclaw_session_start` with your agent ID and a
   workspace description. This groups all your actions for tracking in Mission Control.

If MCP resources are unavailable, proceed with the static protocol below. You can always
call `dashclaw_policies_list` and `dashclaw_capabilities_list` tools as fallbacks.

## Governance Decision Tree

For every action you consider, assess risk and follow this protocol:

### Risk Assessment

| Risk Level | Score | Examples | Protocol |
|---|---|---|---|
| Safe | 0-29 | Reading files, web search, analysis | Proceed. Record outcome after. |
| Moderate | 30-69 | Writing files, sending messages, data queries | Guard first. Proceed on allow/warn. |
| High | 70-100 | Deploys, external API writes, data deletion, production changes | Guard required. Expect approval or block. |

### Guard Decision Handling

When you call `dashclaw_guard`, you will receive one of four decisions:

**`allow`** — Proceed with the action. No restrictions.

**`warn`** — Proceed with caution. The action is permitted but flagged. Include the
warning context in your action record (`dashclaw_record`).

**`block`** — Stop immediately. Do NOT proceed with the action. Do NOT attempt the action
through another path or tool. Report the block reason to the user. The policy exists for
a reason.

**`require_approval`** — A human must approve this action in DashClaw Mission Control.
1. Record the pending action: `dashclaw_record` with `status: 'pending_approval'`
2. Inform the user: "This action requires human approval in Mission Control."
3. Wait: call `dashclaw_wait_for_approval` with the action ID
4. Inspect the response — `approved` is true only when the action reaches `status: 'completed'` AND has an `approved_by` operator. Anything else (denied, cancelled, failed, or `timed_out: true`) means do not proceed:
   - `approved: true` → proceed and PATCH the outcome.
   - `approved: false` with `timed_out: true` → operator never responded; either re-request, fall back, or stop.
   - `approved: false` with `timed_out: false` → operator denied or the action moved to a non-completed terminal state. Stop and report `error_message` from the action record.

### External API Calls

Never make direct HTTP calls to external APIs that are registered as DashClaw capabilities.
Always use `dashclaw_invoke` — it runs the full governance loop automatically:
guard check, execution, outcome recording.

Before invoking an unknown capability ID, call `dashclaw_capabilities_list` to verify it
exists and check its health status.

## Recording Rules

Record all significant actions with `dashclaw_record`. This powers the audit trail visible
in Mission Control and the Decisions ledger.

**Always record:**
- Long-running actions (status: `running`) when you record up front; PATCH later with the final outcome
- Completed actions (status: `completed`)
- Failed actions (status: `failed`) — include error details in `output_summary`
- Blocked actions (status: `failed`) — include the guard block reason (the server has no separate `blocked` status on records you create)

**Write meaningful fields:**
- `declared_goal` — Write as if explaining to an auditor. Bad: "Deploy the app".
  Good: "Deploy v2.3.1 to staging after all tests passed".
- `reasoning` — Why you chose this action over alternatives.
- `output_summary` — What was produced or what went wrong.
- `risk_score` — Your honest assessment. Don't lowball to avoid guards.

**For LLM-driven actions, include token usage (cost is auto-derived):**
- `tokens_in` / `tokens_out` — Total input and output tokens for the LLM call(s) attributed to this action.
- `model` — Model identifier (e.g. `claude-opus-4-6`, `gpt-5-codex`). The server uses this to look up pricing.
- `cost_estimate` — Optional. **Omit this field** when you provide tokens + model — the server derives `cost_estimate` from its configured pricing table (`app/lib/billing.js`) so cost stays consistent across all agents. Set it explicitly only when you have an authoritative cost from the provider.

**Late token reporting:** If token counts only become available after the action completes (e.g. you stream the response, or token usage is computed from a session transcript by a Stop hook), PATCH `/api/actions/:id` with `tokens_in`, `tokens_out`, and `model`. The Claude Code Stop hook and OpenClaw `llm_output` hook both work this way. Cost is still derived server-side.

## Session Lifecycle

Every governed session has a clean lifecycle:

1. `dashclaw_session_start` — Register at the beginning
2. Governance loop — Guard, act, record for each action
3. `dashclaw_session_end` — Close when done (status: `completed`, `failed`, or `cancelled`)

Include a `summary` in `dashclaw_session_end` describing what was accomplished.

## Best Practices

1. **Guard before act** — When in doubt about risk, guard. False positives are cheap.
   Unauthorized actions are expensive.

2. **Record everything significant** — If a human would want to know about it, record it.
   Silent failures are governance gaps.

3. **Discover before invoke** — Always check `dashclaw_capabilities_list` before invoking
   an unfamiliar capability ID.

4. **Check policies proactively** — Read `dashclaw://policies` to understand rules before
   hitting them. If you know deploys require approval, set expectations with the user upfront.

5. **Never bypass** — If `dashclaw_guard` returns `block`, do not attempt the action through
   another tool, workaround, or indirect path.

6. **Fail loudly** — Record failures with `status: 'failed'` and a clear `output_summary`.
   Never silently retry without recording the failure first.

7. **Be honest about risk** — Use accurate `risk_score` values. Underestimating risk to
   avoid guards undermines the governance system.

For concrete implementation patterns, see [references/governance-patterns.md](references/governance-patterns.md).

## Session Continuity

### After concluding a session
Call `dashclaw_handoff_create` with a bundle containing your 1-2 sentence summary,
any open loops you opened (action-scoped, via `dashclaw_loop_add`), and decisions
you made (or references via `dashclaw_learning_log`). The next session of yours
will pick this up automatically via `dashclaw_handoff_latest` in pre_llm_call
context injection (when running under Hermes Agent — Claude Code and Codex pick
it up on first turn via the governance protocol).

### On session start (Claude Code / Codex only)
On your first turn, call `dashclaw_handoff_latest` with your agent_id. If a
bundle is returned, summarize it for the operator, then call
`dashclaw_handoff_consume` to mark it claimed so it isn't read twice.

## Skill Safety

### Before loading an unknown skill
Call `dashclaw_skill_scan` with the skill's file contents (map of filename →
content). If `passed=false`, do NOT load the skill — show the findings to the
operator with their severities and let them decide. Scans of identical content
are cached.

## Credential Hygiene

### Before acting on credentials
Call `dashclaw_secret_due` to surface any tracked credentials overdue for
rotation. If an action would use an overdue credential, record the action with
status='pending_approval' and flag it to the operator. Registering new
credentials for tracking is an operator task — agents don't add secrets
themselves (that would be an authorization-creep risk).

## Commitment Tracking

### When you say "I will X later"
Open loops are **action-scoped**, not standalone. After recording an action via
`dashclaw_record`, you can attach an open loop to it via
`dashclaw_loop_add({ action_id, loop_type, description })` — pass the parent
`action_id`, a `loop_type` (e.g. `followup`, `verification`, `pending_input`),
and a `description` of the commitment. On session start, call
`dashclaw_loop_list` to see what you owe. Call `dashclaw_loop_close({ id })`
when you complete one — close maps to "resolve" semantically (the route
accepts `status: 'resolved'`).

## Learning From Prior Sessions

### Before making a non-obvious decision
Call `dashclaw_learning_query` with a search string. If a prior session made a
similar decision, surface its outcome before making yours.

### After making a non-obvious decision
Call `dashclaw_learning_log` with the decision + context (+ outcome if known).
Future sessions querying for this pattern will see your reasoning.

## In-Session Retrospection

### When you want to know "what have I done recently?"
Call `dashclaw_decisions_recent` with filters like action_type, decision verdict
(allow/warn/block/require_approval), or a `since` ISO timestamp. Useful when an
operator asks "what did the agent do this week?" or before suggesting a follow-up
to a recent action.