Proposal: Folder-Level Governance Policy Scoping¶

repo/
  governance.yaml              ← Level 0 (root baseline)
  services/
    governance.yaml            ← Level 1
    billing/
      governance.yaml          ← Level 2 (most specific)
      agent.py                 ← Action occurs here

def discover_policies(action_path: Path, root: Path) -> list[Path]:
    """Walk up from action_path to root, collecting governance.yaml files.

    Returns policies in root-first order (root at index 0, most specific last).
    Stops early if a policy declares 'inherit: false'.
    """
    policies = []
    current = action_path.parent if action_path.is_file() else action_path

    while True:
        for name in ("governance.yaml", "governance.yml"):
            candidate = current / name
            if candidate.exists():
                policies.append(candidate)
                break

        if current == root or current == current.parent:
            break
        current = current.parent

    # Reverse: root first, most specific last
    policies.reverse()

    # Check for 'inherit: false' — stop loading at that boundary
    final = []
    for p in reversed(policies):  # Walk from most specific to root
        final.insert(0, p)
        doc = load_policy_header(p)
        if doc.get("inherit") is False:
            break  # Don't include anything above this level

    return final

# governance.yaml
name: billing-service-policy
version: "1.0"
inherit: true          # NEW: default true. Set to false to stop parent loading.
scope: "services/billing/**"  # NEW: optional glob — only applies to matching paths

rules:
  - name: block-pii-tools
    condition:
      field: tool_name
      operator: in
      value: [export_pii, bulk_download]
    action: deny
    message: "PII export tools blocked in billing service"
    priority: 200
    override: false     # NEW: default false. Set to true to override a parent rule with same name.

def merge_policies(policy_chain: list[PolicyDocument]) -> list[PolicyRule]:
    """Merge a chain of policies into a flat, priority-sorted rule list.

    Rules:
    1. All rules from all levels are collected
    2. If a child rule has override=true and shares a name with a parent rule,
       the parent rule is removed
    3. Deny rules CANNOT be overridden (security invariant)
    4. Rules are sorted by priority descending (highest first)
    5. First matching rule wins (existing AGT behavior)
    """
    # Collect all rules with their source level
    rules_by_name: dict[str, tuple[PolicyRule, int]] = {}  # name → (rule, level)
    all_rules: list[PolicyRule] = []

    for level, doc in enumerate(policy_chain):
        for rule in doc.rules:
            existing = rules_by_name.get(rule.name)

            if existing and rule.override:
                parent_rule, parent_level = existing
                # Security invariant: deny cannot be overridden
                if parent_rule.action == PolicyAction.DENY:
                    # Keep parent deny, also add child rule (both evaluated)
                    all_rules.append(rule)
                else:
                    # Replace parent rule with child override
                    all_rules = [r for r in all_rules if r.name != rule.name]
                    all_rules.append(rule)
                    rules_by_name[rule.name] = (rule, level)
            else:
                all_rules.append(rule)
                if rule.name not in rules_by_name:
                    rules_by_name[rule.name] = (rule, level)

    # Sort by priority descending
    all_rules.sort(key=lambda r: r.priority, reverse=True)
    return all_rules

class PolicyEvaluator:
    def __init__(self, policies=None, root_dir=None):
        self.policies = policies or []
        self.root_dir = Path(root_dir) if root_dir else None
        self._backends = []

    def evaluate(self, context: dict[str, Any]) -> PolicyDecision:
        """Evaluate policies. If root_dir is set and context contains 'path',
        use folder-scoped policy discovery. Otherwise, use flat evaluation."""

        if self.root_dir and "path" in context:
            action_path = Path(context["path"])
            chain = discover_policies(action_path, self.root_dir)
            docs = [PolicyDocument.from_yaml(p) for p in chain]
            merged_rules = merge_policies(docs)
            return self._evaluate_rules(merged_rules, context)

        # Existing flat evaluation (no breaking change)
        return self._evaluate_flat(context)

acme-corp/
│
├── governance.yaml                    # Org baseline
│   name: acme-baseline
│   rules:
│     - name: block-shell-exec
│       condition: { field: tool_name, operator: eq, value: shell_exec }
│       action: deny
│       priority: 1000
│     - name: require-audit
│       condition: { field: action_type, operator: eq, value: tool_call }
│       action: audit
│       priority: 50
│
├── services/
│   ├── billing/
│   │   └── governance.yaml            # Billing overrides
│   │       name: billing-policy
│   │       rules:
│   │         - name: block-pii-export
│   │           condition: { field: tool_name, operator: in, value: [export_pii, bulk_download] }
│   │           action: deny
│   │           priority: 900
│   │         - name: require-audit      # Override parent audit → deny
│   │           condition: { field: action_type, operator: eq, value: tool_call }
│   │           action: deny
│   │           override: true
│   │           priority: 50
│   │           message: "All tool calls require explicit approval in billing"
│   │
│   ├── docs/
│   │   └── governance.yaml            # Docs: permissive
│   │       name: docs-policy
│   │       rules:
│   │         - name: allow-web-search
│   │           condition: { field: tool_name, operator: eq, value: web_search }
│   │           action: allow
│   │           priority: 100
│   │
│   └── sandbox/
│       └── governance.yaml            # Sandbox: isolated
│           name: sandbox-policy
│           inherit: false              # Don't inherit org baseline
│           rules:
│             - name: allow-all
│               condition: { field: action_type, operator: eq, value: tool_call }
│               action: allow
│               priority: 1