//DOCS Governance Examples

Governance Examples

These examples use the policy fields Punk accepts today:

• name, version, optional description
• appliesTo.trustTiers, appliesTo.agentIds, or appliesTo.tags
• ordered rules with effect, actions, and optional requiresApproval
• defaultEffect

Policies live in PUNK_POLICIES_DIR. Rules match actions shaped as <verb>:<resource> such as model:chat, read:crm, write:crm, write:web, and destroy:*.

Observe vs Optimize

Punk API keys have observe or optimize mode. There is no separate policy YAML field for enforcement mode.

For stateful web actions, observe-mode reads can run, but web writes are refused because form submits and submit-button clicks are real remote writes.

Tool Actions and Side Effects

SDK and model-declared tools should declare sideEffectLevel:

For SDK-style names, Punk uses the prefix before the last dot as the namespace. For example, crm.lookup at level 1 maps to read:crm, while crm.updateAccount at level 3 maps to write:crm. Undeclared or unknown tools default to level 3, so they are treated conservatively.

Managed connectors publish their own domain policy actions in docs/CONNECTORS.md such as read:ticket, write:ticket, write:crm, and write:payment. Use those connector action names when governing managed connector tools.

Read-Only Support Agent

Use this when a support assistant may classify, summarize, and retrieve context, but must not change tickets, accounts, files, or execute commands.

name: support-readonly
version: "1.0"
description: Support agent can chat and read context, but cannot write.

appliesTo:
  tags: [support-readonly]

rules:
  - effect: allow
    actions: ["model:chat", "read:*"]

  - effect: deny
    actions: ["write:*", "destroy:*", "execute:*"]

defaultEffect: deny

Expected outcomes:

In observe mode, the model request still completes live. The blocked write policy verdict is recorded for review instead of being enforced at the request-routing layer.

Approval-Required CRM Write

Use this when CRM reads are safe, but account changes need a human exception before execution.

name: crm-write-approval
version: "1.0"
description: CRM writes need operator approval.

appliesTo:
  trustTiers: [verified, trusted]

rules:
  - effect: allow
    actions: ["model:chat", "read:*"]

  - effect: allow
    actions: ["write:crm"]
    requiresApproval: true

  - effect: deny
    actions: ["destroy:*", "execute:*"]

defaultEffect: deny

Expected outcomes:

In observe mode, the same approval verdict is recorded as a ghost blocked/held route, but the live model response is returned and no approval work item is created.

Blocked Private Web Fetch

This example allows public web context reads while blocking web writes. Private-network blocking is not a YAML policy field; it is the always-on URL guard used by SOM fetches, web sessions, workflow web fetches, and redirects.

name: public-web-context
version: "1.0"
description: Allow public web reads, block web writes.

appliesTo:
  trustTiers: [unverified, verified, trusted, privileged]

rules:
  - effect: allow
    actions: ["model:chat", "read:web"]

  - effect: deny
    actions: ["write:web"]

defaultEffect: deny

Expected outcomes:

Open dev mode is the exception for local demos: when there is no bootstrap API key, no login requirement, no authenticated caller, and no users, private/loopback fetches can be allowed. Authenticated deployments can only opt into private fetches with PUNK_ALLOW_PRIVATE_WEB_FETCH=true.

Level 3 and Level 4 Side-Effect Policy

Use this when user-visible writes should pause for approval and high-impact or destructive actions should be blocked outright.

name: side-effect-boundary
version: "1.0"
description: Human approval for level-3 writes; hard block level-4 destroy actions.

appliesTo:
  trustTiers: [unverified, verified, trusted]

rules:
  - effect: allow
    actions: ["model:chat", "read:*"]

  - effect: allow
    actions: ["write:*"]
    requiresApproval: true

  - effect: deny
    actions: ["destroy:*", "execute:*"]

defaultEffect: deny

Expected outcomes:

The side-effect gate is conservative even without a matching YAML approval rule: level 4 live actions require approval unless the agent is privileged, and level 3 live actions require approval for unverified agents.

Observe-Mode Skipped Enforcement

This fixture-style policy denies chat for unverified agents. It is useful for proving observe mode before moving a tenant to optimize mode.

name: deny-unverified-chat
version: "1.0"
description: Block chat for unverified agents.

appliesTo:
  trustTiers: [unverified]

rules:
  - effect: deny
    actions: ["model:chat"]

defaultEffect: allow

Expected outcomes:

Observe mode also skips serving optimized routes: cache and artifact hits are recorded as ghost savings rather than used for the user response.