Policy & Governance
This document defines the policy model for Zakardo: how governance rules are authored, structured, evaluated, and enforced. Policies are the mechanism through which organizations control what plans can do, when execution must pause for human approval, and what constraints apply in different contexts.
Prerequisites: Glossary, System Architecture, Type System, Plan IR, Capability System
1. Design Goals
Section titled “1. Design Goals”The Policy System must:
- Be declarative. Policies are data, not code. They are JSON documents that describe rules, not scripts that execute logic.
- Be composable. Multiple policies can apply simultaneously. The system must resolve overlaps and conflicts predictably.
- Be evaluable at three points. Pre-generation (Planner, lightweight), pre-execution (Validator, full plan), and per-step (Execution Engine, runtime). All evaluation points use the same policy engine.
- Be auditable. Every policy evaluation — its inputs, the matched rules, and the outcome — is recorded in the Trace.
- Be tenant-aware. Different organizations, teams, or users may have different policy sets. The system must support scoped policy application.
- Be understandable. A non-technical stakeholder should be able to read a policy and understand what it controls.
- Not be an authorization system. Policies govern what execution can do, not who is allowed to do it. User authentication and role-based access control are external to the policy model.
- Complement capability-level constraints. System-level policies defined here are cross-cutting governance rules. Capabilities may also declare their own constraints (role requirements, rate limits, preconditions) in their capability definition. The Planner reads both during plan generation. See the Capability System Specification, Section 16A.
2. Policy Structure
Section titled “2. Policy Structure”A policy is a JSON document that declares a set of rules. Each rule specifies conditions under which a governance action is taken.
2.1 Top-Level Policy Document
Section titled “2.1 Top-Level Policy Document”{ "policy_id": "550e8400-e29b-41d4-a716-446655440100", "name": "production_safety", "version": "1.0.0", "description": "Safety policies for production execution environment", "scope": { "environment": "production", "tenant": "*", "user": "*" }, "rules": [ ... ], "metadata": { "author": "platform-team", "created_at": "2026-02-05T10:00:00Z", "enabled": true, "priority": 100 }}2.2 Top-Level Fields
Section titled “2.2 Top-Level Fields”| Field | Type | Required | Description |
|---|---|---|---|
policy_id | string (UUID) | Yes | Unique identifier for this policy. |
name | string | Yes | Machine-readable name. Must match ^[a-z][a-z0-9_-]*$. |
version | string (semver) | Yes | Policy version. |
description | string | Yes | Human-readable description of what this policy governs. |
scope | PolicyScope | Yes | When this policy applies. See Section 3. |
rules | array of Rule | Yes | The governance rules. See Section 4. |
metadata | object | Yes | See Section 2.3. |
2.3 Metadata Fields
Section titled “2.3 Metadata Fields”| Field | Type | Required | Description |
|---|---|---|---|
author | string | Yes | Who authored this policy. |
created_at | string (ISO 8601) | Yes | When this version was created. |
enabled | boolean | Yes | If false, this policy is registered but not evaluated. Allows disabling without deleting. |
priority | integer | Yes | Evaluation priority. Higher numbers are evaluated first. Used for conflict resolution (see Section 6). |
3. Policy Scope
Section titled “3. Policy Scope”A policy’s scope determines when it applies. Scopes are hierarchical and support wildcards.
3.1 Scope Fields
Section titled “3.1 Scope Fields”| Field | Type | Description |
|---|---|---|
environment | string | The deployment environment: "production", "staging", "development", "*" (all). |
tenant | string | Tenant identifier, or "*" for all tenants. For single-tenant deployments, this is always "*". |
user | string | User identifier, or "*" for all users. Allows per-user policy overrides. |
capability_tags | array of string | If present, this policy only applies to capabilities matching these tags. |
plan_tags | array of string | If present, this policy only applies to plans matching these tags. |
3.2 Scope Resolution
Section titled “3.2 Scope Resolution”When the Policy Engine evaluates a step, it collects all applicable policies by matching scopes:
- Collect all enabled policies.
- Filter by
environment(exact match or wildcard). - Filter by
tenant(exact match or wildcard). - Filter by
user(exact match or wildcard). - Filter by
capability_tags(if specified, capability must have at least one matching tag). - Filter by
plan_tags(if specified, plan must have at least one matching tag). - Sort remaining policies by
priority(descending).
All matching policies are evaluated. If they conflict, the conflict resolution rules in Section 6 apply.
3.3 Scope Examples
Section titled “3.3 Scope Examples”// Applies to all users in production{ "environment": "production", "tenant": "*", "user": "*" }
// Applies only to tenant "acme-corp" in any environment{ "environment": "*", "tenant": "acme-corp", "user": "*" }
// Applies only to email-related capabilities in production{ "environment": "production", "tenant": "*", "user": "*", "capability_tags": ["email"] }
// Applies only to a specific user (e.g., a high-risk user under review){ "environment": "*", "tenant": "acme-corp", "user": "user-789" }4. Policy Rules
Section titled “4. Policy Rules”Rules are the core of a policy. Each rule declares a condition and an action.
4.1 Rule Structure
Section titled “4.1 Rule Structure”{ "rule_id": "rule-001", "name": "require_approval_for_destructive", "description": "All DESTRUCTIVE capabilities require human approval before execution", "condition": { "operator": "equals", "field": "capability.effect_class", "value": "DESTRUCTIVE" }, "action": { "type": "GATE", "gate_type": "APPROVAL", "message": "This step will perform a destructive operation. Approval is required." }}4.2 Rule Fields
Section titled “4.2 Rule Fields”| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | Yes | Unique identifier within the policy. |
name | string | Yes | Human-readable rule name. |
description | string | Yes | Human-readable description of what this rule enforces. |
condition | Condition | Yes | When this rule triggers. See Section 5. |
action | Action | Yes | What happens when the condition is met. See Section 4.3. |
4.3 Rule Actions
Section titled “4.3 Rule Actions”When a rule’s condition evaluates to true, its action is applied.
| Action Type | Behavior | Blocks Execution? |
|---|---|---|
GATE | Triggers a gate — pauses execution and presents a view to the user. | Yes (until user responds). |
DENY | Blocks execution entirely. The step (or plan) cannot proceed. | Yes (permanently). |
WARN | Records a warning in the trace but allows execution to continue. | No. |
LOG | Records the policy match in the trace. No visible effect to the user. | No. |
REQUIRE_MODE | Forces a minimum execution mode (e.g., “this plan must run in DRY_RUN before LIVE”). | Depends on current mode. |
MODIFY_CONSTRAINT | Adjusts an execution constraint (e.g., lower the timeout, reduce max steps). | No (modifies parameters). |
4.4 Gate Action Details
Section titled “4.4 Gate Action Details”When the action type is GATE, additional fields are required:
{ "action": { "type": "GATE", "gate_type": "APPROVAL", "message": "This operation will send emails to external recipients. Approve to continue.", "approvers": ["role:admin", "role:manager"], "timeout_ms": 3600000, "on_timeout": "DENY", "view_hint": { "preferred_blocks": ["ConfirmationCard"], "show_context": ["capability.name", "capability.effect_class", "step.input_bindings"] } }}| Field | Type | Required | Description |
|---|---|---|---|
gate_type | GateType enum | Yes | The kind of gate. See Section 4.5. |
message | string | Yes | Message displayed to the user explaining why approval is needed. |
approvers | array of string | No | Who can approve. Format: "role:<role>" or "user:<user_id>". If omitted, the executing user can self-approve. |
timeout_ms | integer | No | How long to wait for approval. Default: 3,600,000 ms (1 hour). |
on_timeout | string | No | What happens if the gate times out: "DENY" (block) or "APPROVE" (auto-approve). Default: "DENY". |
view_hint | object | No | Hints to A2UI Composition for rendering the gate UI. |
4.5 Gate Types
Section titled “4.5 Gate Types”| Gate Type | Purpose | User Action |
|---|---|---|
APPROVAL | The user must explicitly approve the step or plan before it proceeds. | Approve or Deny. |
INPUT | The user must provide additional data before the step proceeds. | Fill in required fields. |
REVIEW | The user must review information before proceeding. May approve/reject or just acknowledge. | Acknowledge, Approve, or Reject. |
LOG_ONLY | The gate is recorded in the trace but does not pause execution. Useful for audit trails. | None (automatic). |
4.6 Deny Action Details
Section titled “4.6 Deny Action Details”{ "action": { "type": "DENY", "reason": "DESTRUCTIVE operations are not permitted in the staging environment", "error_code": "POLICY_DENIED_DESTRUCTIVE_IN_STAGING" }}| Field | Type | Required | Description |
|---|---|---|---|
reason | string | Yes | Human-readable explanation of why the step/plan is denied. |
error_code | string | No | Machine-readable error code for programmatic handling. |
4.7 Require Mode Action Details
Section titled “4.7 Require Mode Action Details”{ "action": { "type": "REQUIRE_MODE", "minimum_mode": "DRY_RUN", "message": "CANDIDATE plans must run in DRY_RUN mode before LIVE execution" }}| Field | Type | Required | Description |
|---|---|---|---|
minimum_mode | ExecutionMode enum | Yes | The minimum mode required. If the requested mode is lower severity, execution is denied. Mode severity: SIMULATED < DRY_RUN < LIVE. |
message | string | Yes | Explanation of the mode requirement. |
5. Conditions
Section titled “5. Conditions”Conditions are the predicate logic that determines when a rule triggers.
5.1 Condition Fields
Section titled “5.1 Condition Fields”Conditions evaluate against the evaluation context — a structured data object assembled from the current plan, step, capability, execution mode, and user context.
| Field | Type | Required | Description |
|---|---|---|---|
operator | string | Yes | The comparison or logical operator. See Section 5.3. |
field | string | Depends | Path into the evaluation context. Required for comparison operators. |
value | any | Depends | The value to compare against. Required for comparison operators. |
conditions | array of Condition | Depends | Sub-conditions for logical operators (and, or). |
condition | Condition | Depends | Sub-condition for not operator. |
5.2 Evaluation Context
Section titled “5.2 Evaluation Context”The evaluation context is the data available to conditions. It is NOT the Execution Context (which holds step outputs). The evaluation context is assembled from static plan and capability metadata.
evaluation_context = { capability: { name: string, version: string, effect_class: EffectClass, boundary: Boundary, tags: string[], has_interaction_spec: boolean }, plan: { name: string, version: string, lifecycle_state: LifecycleState, aggregate_effect_class: EffectClass, tags: string[], step_count: integer, author: string }, step: { step_index: integer, name: string, has_condition: boolean, input_binding_count: integer }, execution: { mode: ExecutionMode, environment: string }, user: { user_id: string, tenant_id: string, roles: string[] }}5.3 Condition Operators
Section titled “5.3 Condition Operators”| Operator | Type | Description | Required Fields |
|---|---|---|---|
equals | Comparison | Strict equality | field, value |
not_equals | Comparison | Strict inequality | field, value |
greater_than | Comparison | Numeric/string comparison | field, value |
less_than | Comparison | Numeric/string comparison | field, value |
in | Comparison | Value is in a list | field, value (array) |
not_in | Comparison | Value is not in a list | field, value (array) |
contains | Comparison | Array field contains value | field, value |
matches | Comparison | Regex match on string field | field, value (regex string) |
exists | Comparison | Field is present and non-null | field |
and | Logical | All sub-conditions must be true | conditions (array) |
or | Logical | At least one sub-condition is true | conditions (array) |
not | Logical | Sub-condition must be false | condition (single) |
5.4 Condition Examples
Section titled “5.4 Condition Examples”Simple: trigger on destructive capabilities
{ "operator": "equals", "field": "capability.effect_class", "value": "DESTRUCTIVE"}Compound: trigger on external writes to remote boundaries by candidate plans
{ "operator": "and", "conditions": [ { "operator": "equals", "field": "capability.effect_class", "value": "WRITE_EXTERNAL" }, { "operator": "equals", "field": "capability.boundary", "value": "REMOTE" }, { "operator": "equals", "field": "plan.lifecycle_state", "value": "CANDIDATE" } ]}Tag-based: trigger on capabilities tagged “financial”
{ "operator": "contains", "field": "capability.tags", "value": "financial"}Mode-based: trigger when running in LIVE mode
{ "operator": "equals", "field": "execution.mode", "value": "LIVE"}6. Policy Evaluation and Conflict Resolution
Section titled “6. Policy Evaluation and Conflict Resolution”6.1 Evaluation Points
Section titled “6.1 Evaluation Points”Policies are evaluated at three points in the lifecycle:
| Evaluation Point | When | Evaluator | What Is Checked | Purpose |
|---|---|---|---|---|
| Pre-generation | During backward chaining, before the Planner selects a capability | Planner (via Policy Engine) | Can this user execute this specific capability? (effect class, boundary, tags vs. user roles) | UX quality. Ensures the Planner only builds plans the user can execute. If blocked, the Planner searches for alternatives (request pattern). |
| Pre-execution | After Plan Enrichment, during validation | Validator (via Policy Engine) | Plan-level policies: aggregate effect class, execution mode compatibility, plan lifecycle constraints. Evaluated once for the whole plan. | Safety net. Catches edge cases the Planner missed (race conditions, registry changes). |
| Per-step | During plan execution, before each step | Execution Engine (via Policy Engine) | Step-level policies: individual capability effect class, boundary, tags. May trigger gates. | Runtime governance. Enforces gates and runtime constraints. |
Pre-generation is the most important evaluation point. It ensures that plans always succeed by preventing the Planner from selecting capabilities the user cannot access. The other two points are defense-in-depth — they should rarely trigger denials for Planner-generated plans.
6.2 Pre-Generation Evaluation
Section titled “6.2 Pre-Generation Evaluation”The Planner calls the Policy Engine during backward chaining, once for each candidate capability before committing to it:
Input: - Capability metadata (name, version, effect_class, boundary, tags) - User context (user_id, tenant_id, roles) - Environment
Output: - ALLOWED: Planner may use this capability in the plan - DENIED: Planner must find an alternative (with reason, so the Planner can explain if no alternative exists)This is a lightweight evaluation. It checks only the capability’s static metadata against user roles and policies. It does not evaluate plan-level or step-level policies (those happen later). The purpose is not full policy enforcement — it is guidance to help the Planner build executable plans.
When a capability is DENIED:
- The Planner queries the Capability Registry for alternatives (checking
alternativesfield first, then tag-based search). - For each alternative found, the Planner runs another pre-generation evaluation.
- If an alternative is ALLOWED, the Planner adjusts the goal and uses it.
- If no alternative is ALLOWED, the Planner switches to CONVERSE mode and explains why the intent cannot be fulfilled.
Example:
Intent: "Delete customer account ABC-123"
Pre-generation check: delete_customer_account (DESTRUCTIVE) → User role: "support_agent" → Policy: DENY (support agents cannot execute DESTRUCTIVE capabilities)
Alternative search: request_account_deletion (WRITE_INTERNAL) → Pre-generation check: ALLOWED → Planner adjusts goal: "submit deletion request" → Plan built with request_account_deletion → Plan always succeeds.6.3 Pre-Execution Evaluation
Section titled “6.3 Pre-Execution Evaluation”The Validator calls the Policy Engine with the full Plan IR and requests plan-level evaluation:
Input: - Full Plan IR (plan name, tags, aggregate effect class, lifecycle state, step count) - Requested execution mode - User context (user_id, tenant_id, roles) - Environment
Output: - ALLOW: plan may proceed to execution - DENY: plan is rejected (with reason) - GATE: plan requires approval before execution starts (plan-level gate) - REQUIRE_MODE: execution mode must changePre-execution evaluation checks:
- Is this execution mode permitted for this plan’s aggregate effect class?
- Are there plan-level policies that deny or gate this plan?
- Does the plan’s lifecycle state have constraints (e.g., “CANDIDATE plans must run in DRY_RUN first”)?
6.4 Per-Step Evaluation
Section titled “6.4 Per-Step Evaluation”The Execution Engine calls the Policy Engine before executing each step:
Input: - Step metadata (step_index, name, capability info) - Capability metadata (name, version, effect_class, boundary, tags) - Plan metadata (name, lifecycle_state, tags) - Execution context (mode, environment) - User context (user_id, tenant_id, roles)
Output: - ALLOW: step may proceed - DENY: step is blocked (plan aborts or handles per error policy) - GATE: gate triggered (execution pauses, user sees gate UI) - WARN: warning recorded, step proceeds - LOG: logged silently, step proceeds - MODIFY_CONSTRAINT: execution parameters adjusted (e.g., lower timeout)6.4 Evaluation Algorithm
Section titled “6.4 Evaluation Algorithm”For a given evaluation context:
1. Collect all enabled policies whose scope matches the context.2. Sort by priority (descending).3. For each policy, evaluate its rules in order: a. Evaluate the rule's condition against the evaluation context. b. If condition is true: record the rule match and its action. c. Continue evaluating remaining rules (a single policy may have multiple matching rules).4. Collect all matched actions across all policies.5. Apply conflict resolution (see Section 6.5).6. Return the final set of actions.6.5 Conflict Resolution
Section titled “6.5 Conflict Resolution”When multiple rules match and produce conflicting actions:
Priority rules (in order):
- DENY always wins. If any rule produces DENY, the result is DENY. No other action can override a denial.
- GATE trumps ALLOW. If any rule produces GATE and no rule produces DENY, the result includes the gate.
- REQUIRE_MODE is additive. If multiple rules require different modes, the highest mode wins (LIVE > DRY_RUN > SIMULATED).
- WARN and LOG are always additive. They never conflict with other actions. All warnings and logs are recorded regardless of other outcomes.
- MODIFY_CONSTRAINT is additive. Multiple modifications are merged. If they conflict (e.g., two different timeout values), the more restrictive value wins.
- Multiple GATE actions are combined. If rules from different policies both produce gates, the user sees all gates (in priority order). The user must resolve each one.
Same-priority conflict: If two policies have the same priority and produce conflicting GATE vs. ALLOW results, the GATE wins (default to more governance, not less).
6.6 Evaluation Result Structure
Section titled “6.6 Evaluation Result Structure”The Policy Engine returns a structured result for tracing and auditing:
{ "outcome": "GATE", "matched_rules": [ { "policy_id": "550e8400-...", "policy_name": "production_safety", "rule_id": "rule-001", "rule_name": "require_approval_for_destructive", "action": { "type": "GATE", "gate_type": "APPROVAL", "message": "This step will perform a destructive operation." } }, { "policy_id": "660e8400-...", "policy_name": "audit_logging", "rule_id": "rule-010", "rule_name": "log_all_remote_calls", "action": { "type": "LOG" } } ], "unmatched_policies": ["770e8400-..."], "evaluation_context_snapshot": { ... }}This entire result is recorded in the Trace for auditability.
7. Default Policies
Section titled “7. Default Policies”The Zakardo runtime ships with a set of default policies. These provide sensible governance out of the box. They can be overridden, extended, or disabled by the developer.
7.1 Default Policy: Execution Mode Constraints
Section titled “7.1 Default Policy: Execution Mode Constraints”{ "policy_id": "default-mode-constraints", "name": "default_execution_mode_constraints", "version": "1.0.0", "description": "Controls which effect classes are permitted in each execution mode", "scope": { "environment": "*", "tenant": "*", "user": "*" }, "rules": [ { "rule_id": "simulated-read-only", "name": "simulated_mode_read_only", "description": "SIMULATED mode only permits READ capabilities", "condition": { "operator": "and", "conditions": [ { "operator": "equals", "field": "execution.mode", "value": "SIMULATED" }, { "operator": "not_equals", "field": "capability.effect_class", "value": "READ" } ] }, "action": { "type": "DENY", "reason": "SIMULATED mode does not permit capabilities with side effects", "error_code": "POLICY_SIMULATED_MODE_NO_SIDE_EFFECTS" } }, { "rule_id": "dryrun-no-external", "name": "dryrun_no_external_writes", "description": "DRY_RUN mode does not permit WRITE_EXTERNAL or DESTRUCTIVE capabilities", "condition": { "operator": "and", "conditions": [ { "operator": "equals", "field": "execution.mode", "value": "DRY_RUN" }, { "operator": "in", "field": "capability.effect_class", "value": ["WRITE_EXTERNAL", "DESTRUCTIVE"] } ] }, "action": { "type": "DENY", "reason": "DRY_RUN mode does not permit external writes or destructive operations", "error_code": "POLICY_DRYRUN_NO_EXTERNAL_EFFECTS" } } ], "metadata": { "author": "zakardo-runtime", "created_at": "2026-01-01T00:00:00Z", "enabled": true, "priority": 1000 }}7.2 Default Policy: Destructive Operations
Section titled “7.2 Default Policy: Destructive Operations”{ "policy_id": "default-destructive-approval", "name": "default_destructive_approval", "version": "1.0.0", "description": "All DESTRUCTIVE capabilities require human approval in LIVE mode", "scope": { "environment": "*", "tenant": "*", "user": "*" }, "rules": [ { "rule_id": "approve-destructive-live", "name": "approve_destructive_in_live", "description": "Require approval for destructive operations in LIVE mode", "condition": { "operator": "and", "conditions": [ { "operator": "equals", "field": "capability.effect_class", "value": "DESTRUCTIVE" }, { "operator": "equals", "field": "execution.mode", "value": "LIVE" } ] }, "action": { "type": "GATE", "gate_type": "APPROVAL", "message": "This step will perform a destructive operation. Approval is required to continue.", "on_timeout": "DENY" } } ], "metadata": { "author": "zakardo-runtime", "created_at": "2026-01-01T00:00:00Z", "enabled": true, "priority": 900 }}7.3 Default Policy: Candidate Plan Safety
Section titled “7.3 Default Policy: Candidate Plan Safety”{ "policy_id": "default-candidate-safety", "name": "default_candidate_plan_safety", "version": "1.0.0", "description": "CANDIDATE plans with external side effects must be reviewed before LIVE execution", "scope": { "environment": "production", "tenant": "*", "user": "*" }, "rules": [ { "rule_id": "candidate-external-review", "name": "candidate_external_writes_require_review", "description": "CANDIDATE plans with WRITE_EXTERNAL or DESTRUCTIVE aggregate effect must be approved", "condition": { "operator": "and", "conditions": [ { "operator": "equals", "field": "plan.lifecycle_state", "value": "CANDIDATE" }, { "operator": "in", "field": "plan.aggregate_effect_class", "value": ["WRITE_EXTERNAL", "DESTRUCTIVE"] }, { "operator": "equals", "field": "execution.mode", "value": "LIVE" } ] }, "action": { "type": "GATE", "gate_type": "APPROVAL", "message": "This is a new (CANDIDATE) plan that has external side effects. Please review before approving.", "on_timeout": "DENY" } }, { "rule_id": "candidate-force-dryrun-first", "name": "candidate_suggest_dryrun", "description": "CANDIDATE plans should run in DRY_RUN first when they have write effects", "condition": { "operator": "and", "conditions": [ { "operator": "equals", "field": "plan.lifecycle_state", "value": "CANDIDATE" }, { "operator": "in", "field": "plan.aggregate_effect_class", "value": ["WRITE_INTERNAL", "WRITE_EXTERNAL", "DESTRUCTIVE"] } ] }, "action": { "type": "WARN", "reason": "This CANDIDATE plan has write effects. Consider running in DRY_RUN mode first." } } ], "metadata": { "author": "zakardo-runtime", "created_at": "2026-01-01T00:00:00Z", "enabled": true, "priority": 800 }}7.4 Default Policy: Audit Logging
Section titled “7.4 Default Policy: Audit Logging”{ "policy_id": "default-audit-logging", "name": "default_audit_logging", "version": "1.0.0", "description": "Log all REMOTE and DESTRUCTIVE operations for audit", "scope": { "environment": "*", "tenant": "*", "user": "*" }, "rules": [ { "rule_id": "log-remote", "name": "log_remote_operations", "description": "Log all operations with REMOTE boundary", "condition": { "operator": "equals", "field": "capability.boundary", "value": "REMOTE" }, "action": { "type": "LOG" } }, { "rule_id": "log-destructive", "name": "log_destructive_operations", "description": "Log all DESTRUCTIVE operations with warning level", "condition": { "operator": "equals", "field": "capability.effect_class", "value": "DESTRUCTIVE" }, "action": { "type": "LOG" } } ], "metadata": { "author": "zakardo-runtime", "created_at": "2026-01-01T00:00:00Z", "enabled": true, "priority": 500 }}7.5 Summary of Default Policies
Section titled “7.5 Summary of Default Policies”| Policy | Effect | Can Be Disabled? |
|---|---|---|
| Execution Mode Constraints | SIMULATED=READ only, DRY_RUN=no external, LIVE=all | Yes, but strongly discouraged. |
| Destructive Approval | DESTRUCTIVE + LIVE requires approval gate | Yes. |
| Candidate Plan Safety | CANDIDATE + external effects + production requires approval | Yes. |
| Audit Logging | REMOTE and DESTRUCTIVE operations are logged | Yes. |
8. Governance Matrix Implementation
Section titled “8. Governance Matrix Implementation”The governance matrix (defined conceptually in the Capability System Specification, Section 3.4) is implemented through default policies plus developer-authored policies.
8.1 Matrix Mapping to Default Rules
Section titled “8.1 Matrix Mapping to Default Rules”| Effect Class | Boundary | Default Governance |
|---|---|---|
| READ | LOCAL | LOG_ONLY (via audit logging) |
| READ | REMOTE | LOG (via audit logging: remote boundary) |
| READ | USER_ENV | LOG |
| WRITE_INTERNAL | LOCAL | LOG. WARN for candidate plans. |
| WRITE_INTERNAL | USER_ENV | LOG. |
| WRITE_EXTERNAL | REMOTE | LOG. GATE (APPROVAL) for candidate plans in production. Outbox enforced (by Execution Engine, not policy). |
| DESTRUCTIVE | LOCAL | GATE (APPROVAL) in LIVE mode. |
| DESTRUCTIVE | REMOTE | GATE (APPROVAL) in LIVE mode. Outbox enforced. |
| DESTRUCTIVE | USER_ENV | GATE (APPROVAL) in LIVE mode. |
8.2 Extending the Matrix
Section titled “8.2 Extending the Matrix”Developers add policies to tighten governance beyond defaults. Common patterns:
Require approval for all external writes (not just destructive):
{ "condition": { "operator": "and", "conditions": [ { "operator": "equals", "field": "capability.effect_class", "value": "WRITE_EXTERNAL" }, { "operator": "equals", "field": "capability.boundary", "value": "REMOTE" }, { "operator": "equals", "field": "execution.mode", "value": "LIVE" } ] }, "action": { "type": "GATE", "gate_type": "APPROVAL", "message": "External write operation requires approval." }}Deny all DESTRUCTIVE operations for non-admin users:
{ "condition": { "operator": "and", "conditions": [ { "operator": "equals", "field": "capability.effect_class", "value": "DESTRUCTIVE" }, { "operator": "not", "condition": { "operator": "contains", "field": "user.roles", "value": "admin" } } ] }, "action": { "type": "DENY", "reason": "Only administrators can execute destructive operations" }}Require review for plans with more than 10 steps:
{ "condition": { "operator": "greater_than", "field": "plan.step_count", "value": 10 }, "action": { "type": "GATE", "gate_type": "REVIEW", "message": "This plan has more than 10 steps. Please review before execution." }}9. Gates at Runtime
Section titled “9. Gates at Runtime”Gates are the user-facing enforcement mechanism. When a policy triggers a GATE action, the Execution Engine pauses and the frontend presents a gate UI.
9.1 Gate Lifecycle
Section titled “9.1 Gate Lifecycle”1. Policy Engine returns GATE action for a step (or plan).2. Execution Engine pauses execution.3. Execution Engine records gate trigger in Trace.4. A2UI Composition produces Gate A2UI messages: - Uses gate_type to select appropriate A2UI components (GatePrompt, etc.) - Includes the gate message and context data - Includes approval/rejection options5. Gate A2UI messages streamed to frontend via SSE.6. A2UI Renderer renders the gate surface.7. User responds: a. APPROVE: Execution resumes. Gate resolution recorded in Trace. b. DENY/REJECT: Execution aborts. Gate rejection recorded in Trace. c. TIMEOUT: on_timeout action applied (DENY or auto-APPROVE).8. If approved: step proceeds.9. If denied/rejected: Execution Engine handles per plan's error policy (abort, compensate, etc.)9.2 Gate vs. Interaction Point (Clarification)
Section titled “9.2 Gate vs. Interaction Point (Clarification)”Both Gates and Interaction Points pause execution and show UI. The distinction matters:
| Aspect | Gate | Interaction Point |
|---|---|---|
| Triggered by | Policy Engine (governance rules) | Capability (Interaction Spec) |
| Purpose | Protection — “should this happen?” | Enablement — “what should happen?” |
| When | Before the capability executes | After the capability executes (it has already produced data) |
| User action | Approve/Deny/Acknowledge | Select/Compare/Review/Input/Confirm |
| Skippable | Depends on policy (usually no) | Depends on Interaction Spec constraints |
| Recorded as | Gate resolution in Trace | Interaction response in Trace |
A single step can trigger both: first a gate (policy says “approve this external write”), then an interaction point (capability says “user must select which item to send”). They happen in sequence: gate first, then interaction.
9.3 v1 Gate Model: Synchronous, Same-Session
Section titled “9.3 v1 Gate Model: Synchronous, Same-Session”In v1, gates are synchronous and same-session only:
- The
approversfield on a gate means “the current user must have one of these roles to approve.” - If the current user matches an approver role: they see the gate UI and can approve/deny.
- If the current user does not match any approver role: the gate resolves as DENY automatically. The user sees a message explaining what role is required.
- There is no async gate suspension. No notification to external approvers.
- There is no execution state persistence across sessions for gate resolution.
This is acceptable because the Planner is policy-aware (see Section 6.2). If a plan step would require approval from a role the current user doesn’t have, the Planner should have already found an alternative capability path (e.g., the request pattern). Gate DENY due to role mismatch is a safety net, not the primary user experience.
Example of same-session gate:
User role: "admin"Step: delete_customer_account (DESTRUCTIVE)Policy triggers: APPROVAL gate, approvers: ["admin", "super_admin"]→ User is "admin" → gate UI shown → user approves → step executes.Example of auto-DENY gate:
User role: "support_agent"Step: delete_customer_account (DESTRUCTIVE)Policy triggers: APPROVAL gate, approvers: ["admin"]→ User is "support_agent" → no matching role → auto-DENY.→ But this should rarely happen because the Planner's policy pre-check would have redirected to request_account_deletion.9.4 v2 Gate Model (Future): Async, Cross-Role
Section titled “9.4 v2 Gate Model (Future): Async, Cross-Role”v2 will introduce async gate resolution for cross-role approvals:
- When a gate requires a role the current user doesn’t have, execution suspends instead of denying.
- A notification is sent to eligible approvers (via the host app’s notification system).
- The approver reviews the gate asynchronously and responds.
- The Execution Engine resumes (or aborts) based on the approver’s response.
- This requires persistent execution state and long-lived suspended plan contexts.
v2 is documented here for planning purposes but is not part of the v1 design.
9.5 Multiple Gates on One Step
Section titled “9.5 Multiple Gates on One Step”If multiple policies trigger gates for the same step, the user sees all of them in priority order. Each gate must be resolved before the next is presented. If any gate is denied, execution aborts.
10. Policy Versioning and Lifecycle
Section titled “10. Policy Versioning and Lifecycle”10.1 Policy Versioning
Section titled “10.1 Policy Versioning”Policies are versioned using semver:
| Change | Version Bump |
|---|---|
| Fix a description or message | PATCH |
| Change a rule’s message text | PATCH |
| Add a new rule | MINOR |
| Add a new policy scope field | MINOR |
| Remove a rule | MAJOR |
| Change a rule’s condition | MAJOR |
| Change a rule’s action type (e.g., GATE to DENY) | MAJOR |
| Change the scope to be more or less restrictive | MAJOR |
10.2 Policy Lifecycle
Section titled “10.2 Policy Lifecycle”| State | Meaning |
|---|---|
enabled: true | Policy is active and evaluated. |
enabled: false | Policy is registered but skipped during evaluation. |
| Deleted | Policy is removed from the registry. |
There is no “deprecated” state for policies. Policies are either enabled or disabled. If a policy is no longer needed, disable it first (to verify nothing breaks), then delete it.
10.3 Policy Authoring
Section titled “10.3 Policy Authoring”Policies can be authored through:
| Method | Description |
|---|---|
| JSON files | Policies defined as JSON in the project repository. Loaded at runtime startup. |
| Runtime API | Policies created/updated via the API. Allows dynamic policy management. |
| Zakardo Cloud | Policies managed centrally in the Zakardo Cloud dashboard and synced to runtimes. |
| CLI | zakardo policy create, zakardo policy list, zakardo policy enable/disable. |
11. Policy and Plan Enrichment
Section titled “11. Policy and Plan Enrichment”Plan Enrichment interacts with the Policy Engine in two ways:
11.1 Default Policy Application
Section titled “11.1 Default Policy Application”During enrichment, when building the Full Plan IR from a Plan Draft:
- Enrichment computes
execution_constraints.aggregate_effect_classfrom the capabilities. - Enrichment sets
execution_constraints.require_plan_approvalbased on whether any default policy would trigger a plan-level gate for this effect class. - Enrichment sets default
execution_constraints.allowed_modesbased on the aggregate effect class (e.g., if all capabilities are READ, all modes are allowed).
These are hints in the Plan IR. The actual policy evaluation happens at validation and execution time.
11.2 Policy-Aware Enrichment (Future)
Section titled “11.2 Policy-Aware Enrichment (Future)”In a future version, enrichment could query the Policy Engine to pre-compute which steps will trigger gates and annotate the Plan IR accordingly. This would allow the Plan Preview to show the user where gates will appear before execution starts.
12. Trace Integration
Section titled “12. Trace Integration”Every policy evaluation is recorded in the Trace.
12.1 What Is Recorded
Section titled “12.1 What Is Recorded”| Event | Recorded Data |
|---|---|
| Pre-execution evaluation | Matched rules, outcome (ALLOW/DENY/GATE), evaluation context snapshot |
| Per-step evaluation | Matched rules, outcome, evaluation context for that step |
| Gate trigger | Gate type, message, approvers, timeout |
| Gate resolution | User response (approved/denied), response timestamp, responder identity |
| Gate timeout | Timeout action applied (DENY/auto-APPROVE) |
| Policy WARN | Warning message, matched rule |
| Policy DENY | Denial reason, error code, matched rule |
12.2 Audit Trail
Section titled “12.2 Audit Trail”The combination of policy evaluation records and gate resolutions in the Trace provides a complete audit trail:
- Who approved what, when, and why.
- Which policies matched and which didn’t.
- How the evaluation context looked at decision time.
- Whether any gates timed out and what happened.
This audit trail is immutable (per the Trace system’s append-only design) and supports compliance requirements.
13. Complete Example: Financial Transaction Policies
Section titled “13. Complete Example: Financial Transaction Policies”A company building a financial application with Zakardo might define these policies:
13.1 High-Value Transaction Approval
Section titled “13.1 High-Value Transaction Approval”{ "policy_id": "fin-001", "name": "high_value_transaction_approval", "version": "1.0.0", "description": "Transactions above $10,000 require manager approval", "scope": { "environment": "production", "tenant": "*", "user": "*", "capability_tags": ["financial", "payment", "transfer"] }, "rules": [ { "rule_id": "high-value-gate", "name": "high_value_approval", "description": "Require manager approval for high-value financial operations", "condition": { "operator": "and", "conditions": [ { "operator": "in", "field": "capability.effect_class", "value": ["WRITE_EXTERNAL", "DESTRUCTIVE"] }, { "operator": "equals", "field": "execution.mode", "value": "LIVE" } ] }, "action": { "type": "GATE", "gate_type": "APPROVAL", "message": "This financial operation requires manager approval for amounts above $10,000.", "approvers": ["role:finance_manager", "role:admin"], "timeout_ms": 86400000, "on_timeout": "DENY" } } ], "metadata": { "author": "finance-team", "created_at": "2026-02-05T12:00:00Z", "enabled": true, "priority": 700 }}13.2 Compliance Logging
Section titled “13.2 Compliance Logging”{ "policy_id": "fin-002", "name": "financial_compliance_logging", "version": "1.0.0", "description": "All financial operations must be logged for compliance", "scope": { "environment": "*", "tenant": "*", "user": "*", "capability_tags": ["financial"] }, "rules": [ { "rule_id": "log-all-financial", "name": "log_financial_operations", "description": "Log all financial capability invocations", "condition": { "operator": "exists", "field": "capability.name" }, "action": { "type": "LOG" } } ], "metadata": { "author": "compliance-team", "created_at": "2026-02-05T12:00:00Z", "enabled": true, "priority": 600 }}13.3 No DESTRUCTIVE Operations in Staging
Section titled “13.3 No DESTRUCTIVE Operations in Staging”{ "policy_id": "fin-003", "name": "no_destructive_in_staging", "version": "1.0.0", "description": "DESTRUCTIVE operations are denied in the staging environment for financial capabilities", "scope": { "environment": "staging", "tenant": "*", "user": "*", "capability_tags": ["financial"] }, "rules": [ { "rule_id": "deny-destructive-staging", "name": "deny_destructive_staging", "description": "Block all destructive financial operations in staging", "condition": { "operator": "equals", "field": "capability.effect_class", "value": "DESTRUCTIVE" }, "action": { "type": "DENY", "reason": "DESTRUCTIVE financial operations are not permitted in staging", "error_code": "POLICY_FIN_NO_DESTRUCTIVE_STAGING" } } ], "metadata": { "author": "finance-team", "created_at": "2026-02-05T12:00:00Z", "enabled": true, "priority": 700 }}14. Summary of Decisions
Section titled “14. Summary of Decisions”| Decision | Resolution |
|---|---|
| Policy format | Declarative JSON documents. Not code. |
| Policy scoping | Hierarchical: environment > tenant > user, with optional tag filtering. Wildcards supported. |
| Rule conditions | Structured predicate logic over an evaluation context (capability, plan, step, execution, user metadata). Same operator set as Plan IR conditions. |
| Action types | GATE, DENY, WARN, LOG, REQUIRE_MODE, MODIFY_CONSTRAINT. Six types covering blocking, non-blocking, and informational actions. |
| Gate types | APPROVAL, INPUT, REVIEW, LOG_ONLY. Four types matching governance needs. |
| Evaluation points | Three: pre-generation (Planner, lightweight), pre-execution (Validator, full plan), per-step (Execution Engine). Same engine, same rules. Pre-generation is the most important for UX. |
| Plans always succeed | The Planner performs policy pre-checks during backward chaining. If a capability is blocked, the Planner finds alternatives (request pattern). Plans are built only from capabilities the user can execute. |
| v1 Gate model | Synchronous, same-session. If user lacks approver role, gate auto-DENYs. This is acceptable because the Planner should have already found an alternative. |
| v2 Gate model (future) | Async cross-role approvals. Execution suspends, notification sent to eligible approvers. Requires persistent execution state. |
| Authorization model | Four layers: Identity (external), API Access (external), Execution Governance (Zakardo Policy Engine), Data Authorization (capability implementation). |
| Conflict resolution | DENY > GATE > ALLOW. Higher priority wins. Same-priority defaults to more governance. Warnings and logs are always additive. |
| Default policies | Four shipped policies: execution mode constraints, destructive approval, candidate plan safety, audit logging. All overridable. |
| Gate lifecycle | Trigger -> pause -> send view to frontend -> wait for response -> resume or abort -> record in Trace. |
| Gate vs. Interaction Point | Gates are policy-driven (before execution). Interaction Points are capability-driven (after execution). Both pause and show UI. |
| Trace integration | Every evaluation, gate trigger, and resolution recorded in the Trace for audit. |
| Policy versioning | Semver. Enabled/disabled state. No “deprecated” — disable then delete. |
| Authoring methods | JSON files, Runtime API, Zakardo Cloud dashboard, CLI. |
15. Questions Deferred
Section titled “15. Questions Deferred”| Question | Deferred To |
|---|---|
| How are gate approvals routed to specific users or roles? | Runtime API and SDK Specification (notification/routing mechanism) |
| Can policies trigger asynchronous workflows (e.g., email an approver)? | Execution Engine Specification |
| How are policies synced between Zakardo Cloud and local runtimes? | PRD — Zakardo Cloud |
| Can policies reference runtime data (e.g., “deny if transaction amount > $10,000”)? | See Section 15.1 |
| How do policies interact with sub-plan execution? | Execution Engine Specification |
15.1 Runtime Data in Conditions (v1: Static Only)
Section titled “15.1 Runtime Data in Conditions (v1: Static Only)”v1 Decision: Policies evaluate static metadata only. Value-based governance (e.g., “require approval if amount > $10,000”) is the capability’s responsibility via Interaction Specs. The capability knows its data semantics and can trigger a CONFIRM interaction for high-value operations. The policy system does not inspect runtime values.
Rationale:
- Keeps the policy engine simple and fast (no dependency on execution state).
- Clean separation: policies govern structure (what kind of operation), capabilities govern value (what specific data).
- A capability that processes financial transactions should declare a CONFIRM interaction for high-value operations regardless of policy — it’s domain logic, not governance.
Future Evolution Options (post-v1):
These are documented for future consideration but are NOT part of the v1 design:
- Runtime context extension. Extend the evaluation context to include
step.input_valuesandstep.output_values. Policies could then reference actual runtime data. Trade-off: adds power but policies become dependent on execution state, harder to reason about statically, and harder to preview in Plan Preview. - Capability policy hooks. Capabilities declare specific output fields as “policy-observable.” The policy engine evaluates only those declared fields, not the full output. Trade-off: targeted power without full runtime context exposure, but adds coupling between capability definitions and policies.
- Post-execution policy evaluation. A third evaluation point (after step execution, before writing to Execution Context) that can inspect outputs and trigger gates retroactively. Trade-off: enables value-based governance without pre-execution complexity, but means the capability has already run (side effects may have occurred).