Governance Inheritance#

This skill provides a hierarchical policy inheritance system that allows policies to be defined at multiple levels and automatically inherited by child contexts.

Policy Hierarchy Levels#

Policies cascade from broad to specific:

text

Organization (broadest)
    ↓
Team
    ↓
Project
    ↓
Session (most specific)

Inheritance Rules#

1. Child overrides parent: More specific policies override broader ones
2. Additive by default: Policies merge unless explicitly overridden
3. Explicit deny wins: A deny at any level blocks the action
4. Require explicit allow: Actions without an explicit allow are blocked in strict mode

Policy Structure#

Each level contains a policies.yaml file:

yaml

# policies.yaml
version: "1.0"
level: organization  # organization | team | project | session
parent: null         # path to parent policy (null for root)

# Policy blocks
policies:
  http:
    - pattern: "*.internal.company.com"
      action: allow
      scope: ["GET", "POST"]
    - pattern: "*"
      action: deny
      reason: "External HTTP requires approval"

  shell:
    - command: "git *"
      action: allow
    - command: "rm -rf /*"
      action: deny
      reason: "Destructive command blocked"
    - command: "*"
      action: require_approval

  file:
    read:
      - path: "~/workspace/*"
        action: allow
      - path: "/etc/*"
        action: deny
    write:
      - path: "~/workspace/*"
        action: allow
      - path: "*"
        action: require_approval

# Inheritance configuration
inheritance:
  mode: merge          # merge | override | isolate
  exceptions:          # Policies that don't inherit
    - shell.sudo
  extensions:          # Child can extend these
    - http.allowlist

Quick Start#

1. Initialize Organization Policies#

bash

python scripts/init_governance.py --level organization --path ~/.openclaw/governance

2. Create Team-Level Override#

bash

python scripts/init_governance.py --level team --name engineering --parent ~/.openclaw/governance/organization

3. Evaluate Policy for Action#

typescript

const result = await context.tools.governanceInheritance.evaluate({
  action: "http",
  details: { method: "GET", url: "https://api.example.com/data" },
  context: {
    sessionId: "sess_123",
    project: "my-project",
    team: "engineering"
  }
});

// result: { allowed: true } | { allowed: false, reason: "...", level: "organization" }

Policy Resolution#

When evaluating an action, the system:

1. Collects all applicable policies from root to leaf
2. Merges according to inheritance rules
3. Evaluates against the most specific matching rule
4. Returns decision with provenance (which level decided)

Conflict Resolution#

ParentChildResultallowallowallowallowdenydeny (child wins)allowrequire_approvalrequire_approvaldenyallowdeny (deny always wins)denydenydeny

Session Context Integration#

Policies automatically load based on session context:

yaml

# Session inherits from project → team → organization
session_context:
  organization: "acme-corp"
  team: "engineering"
  project: "api-gateway"
  session: "sess_abc123"

# Policy resolution path:
# ~/.openclaw/governance/organizations/acme-corp/policies.yaml
# ~/.openclaw/governance/teams/engineering/policies.yaml
# ~/.openclaw/governance/projects/api-gateway/policies.yaml
# ~/.openclaw/governance/sessions/sess_abc123/policies.yaml

Available Tools#

evaluate#

Evaluates an action against the inherited policy chain.

Parameters:

• action (string): Action type (http, shell, file, browser)
• details (object): Action-specific details
• context (object): Session context for policy resolution

Returns:

typescript

{
  allowed: boolean,
  reason?: string,
  level: string,        // Which policy level made the decision
  policy?: string,      // Specific policy that matched
  requiresApproval?: boolean
}

initPolicyLevel#

Initializes a new policy level.

Parameters:

• level (string): organization, team, project, or session
• name (string): Identifier for this level
• parent (string, optional): Path to parent policy
• path (string): Where to create the policy

validatePolicyChain#

Validates a policy chain for conflicts or errors.

Parameters:

• context (object): Session context to validate

Returns:

typescript

{
  valid: boolean,
  errors: string[],
  warnings: string[]
}

Configuration#

Set the governance root in your environment:

bash

export GOVERNANCE_ROOT="~/.openclaw/governance"

Or in openclaw.json:

json

{
  "skills": {
    "governance-inheritance": {
      "env": {
        "GOVERNANCE_ROOT": "~/.openclaw/governance"
      }
    }
  }
}

Policy Examples#

Organization Level (Restrictive Base)#

yaml

level: organization
policies:
  http:
    - pattern: "*.company.internal"
      action: allow
    - pattern: "*"
      action: require_approval
  shell:
    - command: "*"
      action: require_approval

Team Level (Engineering - More Permissive)#

yaml

level: team
parent: ../organization
inheritance:
  mode: merge
policies:
  http:
    - pattern: "*.github.com"
      action: allow
    - pattern: "*.npmjs.com"
      action: allow
  shell:
    - command: "git *"
      action: allow
    - command: "npm *"
      action: allow
    - command: "docker *"
      action: allow

Project Level (Specific Overrides)#

yaml

level: project
parent: ../engineering
inheritance:
  mode: merge
policies:
  http:
    - pattern: "api.stripe.com"
      action: allow  # This project uses Stripe
  file:
    write:
      - path: "./dist/*"
        action: allow

Integration with GovernClaw#

This skill works alongside governclaw-middleware:

typescript

// governclaw-middleware calls governance-inheritance for policy resolution
const policyResult = await context.tools.governanceInheritance.evaluate({
  action: "http",
  details: { method, url, headers },
  context: sessionContext
});

if (!policyResult.allowed) {
  return { blocked: true, reason: policyResult.reason };
}

Best Practices#

1. Start restrictive at organization level - Require approval for everything
2. Grant specific permissions at lower levels - Teams/projects opt into what they need
3. Document exceptions - Use reason field to explain why policies exist
4. Regular audits - Run validatePolicyChain to catch conflicts
5. Version your policies - Use the version field to track changes

Error Handling#

Always check for policy evaluation errors:

typescript

const result = await context.tools.governanceInheritance.evaluate({...});

if (result.error) {
  // Policy chain misconfiguration
  console.error("Policy error:", result.error);
  return { error: "Governance misconfigured" };
}

if (!result.allowed) {
  // Policy blocked the action
  console.log("Blocked by", result.level, "policy:", result.reason);
}

See Also#

• references/policy-schema.md - Complete policy YAML schema
• references/inheritance-algorithm.md - Detailed inheritance logic
• scripts/init_governance.py - Initialize policy levels
• scripts/validate_chain.py - Validate policy chains