//DOCS Governance

Governance

Punk governance answers: who is acting, what are they trying to do, is it allowed, what evidence was recorded, and can this action influence future optimized routes?

What Governance Covers

• Agent identity.
• Trust tiers and trust score.
• Policy evaluation.
• Side-effect classification.
• Approval-required rules.
• Policy exceptions.
• Audit events.
• Payload redaction.
• Optional MeshGuard-compatible governance bridge.

Agent Identity

Agents are resolved from request identity:

• Tenant from bearer token or open dev default.
• App from pinned API key or X-Punk-App.
• Agent from X-Punk-Agent or anonymous.
• Subject from X-Punk-Subject.

The trust engine creates agent records as needed.

Trust tiers:

• unverified
• verified
• trusted
• privileged

Trust score is behavioral and currently collapsed into a numeric score in [0,1].

Policy Format

Policies are YAML files in PUNK_POLICIES_DIR.

Minimal example:

name: default
version: "1.0"
description: Default policy

appliesTo:
  trustTiers:
    - unverified
    - verified
    - trusted
    - privileged

rules:
  - effect: allow
    actions:
      - "model:*"
      - "read:*"

  - effect: deny
    actions:
      - "write:payment"
      - "delete:*"

defaultEffect: deny

Approval example:

name: email-approval
version: "1.0"
appliesTo:
  trustTiers: ["verified"]
rules:
  - effect: allow
    actions: ["write:email"]
    requiresApproval: true
defaultEffect: allow

Policy Selection

Punk selects the most specific applicable policy:

1. agentIds
2. tags
3. trustTiers
4. selectorless policy applies to everyone

Within the selected policy, rules are evaluated in order. First matching action wins. If no rule matches, defaultEffect applies. If no policy applies at all, Punk allows traffic so unconfigured local development does not break.

Action Matching

Actions use <verb>:<resource>.

Examples:

• model:chat
• read:crm
• write:email
• delete:file
• execute:tool

Wildcards:

• *
• read:*
• *:email
• write:email

Side-Effect Classification

SDK tools should declare sideEffectLevel.

Undeclared tools default to level 3. This is intentional.

Approval Required

When a rule has requiresApproval: true:

1. The request fails closed in optimize mode.
2. Punk creates or reuses a pending approval.
3. Operators decide from dashboard, API, or PunkBar.
4. An approved policy exception allows matching future requests for the configured TTL.
5. Decisions are audited.

Observe mode records what would have happened but does not block.

Artifact Promotion Approvals

When a candidate artifact passes replay/shadow gates but human sign-off is required, Punk opens an artifact promotion approval.

Approval promotes the artifact. Rejection leaves it unpromoted. Rollback and quarantine remain available after promotion.

Redaction

Set tenant setting redaction=true to redact SDK tool and side-effect payloads before they are appended to the trace ledger.

Secrets are also protected in settings:

• webhook_secret is accepted by PUT.
• GET returns [set] rather than the real value.
• Audit metadata never stores the raw secret.

Audit Events

Audit records include:

• Tenant.
• Trace id or subject id.
• Actor.
• Action.
• Decision.
• Policy name where applicable.
• Reason.
• Metadata.

Use /api/v1/audit to inspect governance events.

Observe Mode

Observe mode is the safest rollout mode for new tenants:

• Live provider still serves responses.
• Policy denials do not block.
• Caches and artifacts are not used to serve users.
• Punk records ghost savings and what route it would have selected.

Use observe mode to build trust before moving to optimize mode.