Policies

Policies are the foundation of the governance framework. Each policy defines a set of stages, validators, enforcement rules, and applicable resource types that together create a compliance workflow for platform resources.

Policy Structure

A policy definition includes:

Field	Type	Description
name	String	Descriptive name (e.g., "Production Deployment Approval")
description	String	Purpose and scope of the policy
version	String	Semantic version for change tracking (e.g., 1.0.0)
category	Enum	Security, Compliance, Quality, or Operational
severity	Enum	Critical, High, Medium, Low, or Info
applicableResourceTypes	String[]	Resource types this policy applies to
stages	Array	Ordered list of approval stages with fields and validators
enforcementRules	Array	Per-environment enforcement actions
isActive	Boolean	Whether the policy is currently enforced
isDraft	Boolean	Whether the policy is still in draft mode
tags	String[]	Organizational tags for categorization
complianceFrameworks	String[]	Associated frameworks (SOC 2, HIPAA, GDPR, etc.)
yamlSource	String	Original YAML content if imported
versionHistory	Array	Change log with version, author, timestamp, and reason

Creating a Policy

Step 1: Open the Policy Builder

1. Navigate to Governance in the sidebar
2. Click Create Policy (or navigate to /governance/policies/new)
3. The Policy Builder opens with a tabbed wizard interface

Step 2: Define Policy Basics (General Tab)

Configure the core policy metadata:

• Name — A descriptive name that clearly identifies the policy's purpose (e.g., "Production Deployment Approval", "AI Model Bias Review")
• Description — Detailed explanation of what the policy enforces and why it exists
• Version — Semantic version string (e.g., 1.0.0)
• Category — Choose the policy's domain:
  • Security — Access control, encryption, vulnerability management
  • Compliance — Regulatory requirements, data handling, privacy
  • Quality — Code review, testing, performance standards
  • Operational — Deployment procedures, monitoring, incident response
• Severity — Set the importance level: Critical, High, Medium, Low, or Info
• Applicable Resource Types — Select which resources this policy applies to: Applications, Add-ons, Workflows, Data Sources, ML Models, AI Gateway Models, Workspaces, Projects

Step 3: Configure Stages (Stages Tab)

Policies consist of ordered stages that resources must complete sequentially. Each stage collects information and requires validator approval before advancing.

Adding a Stage

Click Add Stage and configure:

Setting	Description
Name	Descriptive stage name (e.g., "Security Review", "Technical Approval")
Order	Sequential position in the workflow (auto-assigned)
Required	Whether this stage must be completed or can be skipped
SLA Hours	Expected completion time — notifications escalate when overdue
Dependencies	Other stage IDs that must complete first

Stage Fields

Build custom form fields for data collection at each stage. Users must complete all required fields before submitting the stage for approval.

Field Type	Description	Use Case
text	Single-line text input	Short answers, identifiers, names
textarea	Multi-line text input	Descriptions, justifications
richtext	Rich text editor with formatting	Documentation, analysis reports
radio	Single selection from options	Yes/no, severity level
checkbox	Multiple selection checkboxes	Compliance checklist items
dropdown	Single selection dropdown	Category selection, environment
multiselect	Multiple selection dropdown	Select tags or frameworks
file	File upload	Evidence documents, test reports, screenshots
number	Numeric input with min/max	Metrics, scores, counts
date	Date picker	Target dates, review dates
datetime	Date and time picker	Scheduled events, deadlines
url	URL input with validation	External documentation, dashboards
email	Email input with validation	Contact for responsible parties

Each field supports these properties:

• Label — Human-readable display label
• Required — Whether the field must be completed before submission
• Default Value — Pre-populated value
• Help Text — Guidance shown below the field to explain what is expected
• Placeholder — Placeholder text in empty fields
• Options — Available choices (for radio, checkbox, dropdown, multiselect)
• Validation — Regex patterns, min/max values, or custom rules
• Conditional Display — Show/hide based on another field's value

Stage Validators

Assign approvers who must sign off on each stage:

Validator Type	Description	Best For
User	Specific user by ID — only that user can approve	Designated reviewers, compliance officers
Role	Any user with the specified role can approve	Flexible team assignments
Group	Organization membership check	Cross-team approvals, committees

Approval logic for multiple validators:

• All — Every validator must approve (unanimous)
• Any — A single validator approval is sufficient
• Majority — More than 50% of validators must approve

Each validator has an isActive flag that can be toggled to temporarily disable them during absences.

Guardrail Requirements (AI Gateway Models)

For policies that apply to AI Gateway Models, stages can include guardrail requirements specifying which AI guardrails must be enabled:

• Required Guardrails — Must be active on the model (hard requirement)
• Recommended Guardrails — Should be active (soft requirement, generates warnings)
• Configuration Requirements — Specific guardrail settings (e.g., PII detection must mask SSN)

The enforcement engine verifies guardrail compliance during pre-deployment checks. See Guardrails for the complete list of available guardrails.

Step 4: Set Enforcement Rules (Enforcement Tab)

Enforcement rules define how policy violations are handled per environment:

Action	Behavior
hard_block	Resource cannot be deployed or promoted until the policy completes. No workaround without an admin override.
soft_block	Deployment is blocked but can be overridden by an admin with a written justification.
warning	A warning is logged but deployment proceeds normally.
post_review	Deployment is blocked until a manual post-deployment review is completed.

Configure different enforcement levels per environment:

Development:  warning        (track compliance, don't block)
Staging:      soft_block     (block but allow override)
Production:   hard_block     (strict enforcement)

Each rule can also specify:

• Override Roles — Roles allowed to override blocks (default: admin only)
• Require Justification — Whether overrides must include a written reason

Step 5: Review and Activate

1. Review all stages, fields, validators, and enforcement rules in the Advanced tab (shows YAML preview)
2. Save as Draft to test the policy with sample resources
3. When ready, set isActive: true and isDraft: false to begin enforcement
4. Share the policy with specific users or teams as needed

Importing Policies from YAML

Policies can be imported from YAML files for version-controlled governance-as-code:

1. Navigate to Governance > Policies and click Import Policy
2. Paste or upload YAML content
3. The system validates the required fields
4. The policy is created in draft mode (isActive: false, isDraft: true)
5. Review and activate when ready

Required YAML fields:

• name — Policy name
• category — Security, Compliance, Quality, or Operational
• targetResourceTypes — Array of resource type strings

Optional YAML fields: description, severity, stages, enforcementRules, resourceSpecificFields, guardrailRequirements, tags, complianceFrameworks

Example YAML:

name: Production AI Model Approval
description: Ensures all AI models pass safety and quality checks before production
category: Quality
severity: High
targetResourceTypes:
  - aiGatewayModel
  - mlModel
complianceFrameworks:
  - NIST AI RMF
  - EU AI Act
stages:
  - name: Performance Review
    order: 1
    isRequired: true
    fields:
      - name: accuracy_score
        label: Model Accuracy Score
        type: number
        required: true
        helpText: Enter the model's accuracy on the test dataset (0-100)
      - name: test_report_url
        label: Test Report URL
        type: url
        required: true
    validators:
      - type: role
        identifier: data-scientist
        isActive: true
  - name: Safety & Bias Review
    order: 2
    isRequired: true
    fields:
      - name: bias_assessment
        label: Bias Assessment
        type: richtext
        required: true
        helpText: Document the bias analysis across protected groups
      - name: guardrails_enabled
        label: Required Guardrails
        type: checkbox
        options:
          - Content Filter
          - PII Detection
          - Prompt Injection Prevention
        required: true
    validators:
      - type: role
        identifier: ai-safety-reviewer
        isActive: true
enforcementRules:
  - environment: development
    action: warning
    requireJustification: false
  - environment: staging
    action: soft_block
    requireJustification: true
  - environment: production
    action: hard_block
    requireJustification: true

Policy Catalog (Templates)

The Policy Catalog provides a shared repository of reusable policy templates that can be discovered, reviewed, and instantiated across the organization.

Browsing the Catalog

Navigate to Governance > Catalog (or /governance/catalog) to browse templates:

• Search — Full-text search on name, description, and tags
• Filter by Category — Security, Compliance, Quality, or Operational
• Filter by Resource Type — Show templates for specific resource types
• Filter by Framework — SOC 2, HIPAA, GDPR, ISO 27001, PCI DSS, etc.
• Filter by Tags — Custom organizational tags
• Verified Only — Show only administrator-verified templates
• Sort By — Rating, usage count, creation date, or name

Each template card displays: name, description, target resource types, compliance frameworks, average rating, and usage count. Verified templates show a badge indicating administrator review.

Using a Template

1. Find a template in the catalog
2. Click Use Template
3. Optionally customize the name, description, stages, or enforcement rules
4. A new policy is created in draft mode from the template
5. The template's usage count is incremented automatically

Publishing Templates

Create templates to share governance patterns across the organization:

1. Create a policy template from the Policy Builder
2. Set isPublic: true or call publish to make it visible to all users
3. Associate tags, compliance frameworks, and target resource types
4. Administrators can mark templates as Verified after review

Reviewing Templates

Users can rate templates from 1-5 stars and leave written reviews. Each user can review a template once. The template's average rating and review count update automatically. Reviews help teams identify the most effective governance patterns.

Policy Instance Lifecycle

When a policy is applied to a resource, a policy instance is created that tracks progress through the stages:

not_started → in_progress → pending_approval → approved → completed
                                             → denied (requires revision)

Instance States

Status	Description
not_started	Instance created, no stages begun
in_progress	At least one stage has been started
pending_approval	A stage has been submitted and is awaiting validator action
approved	Current stage was approved (may proceed to next stage)
denied	Current stage was denied by a validator — requestor must revise
completed	All required stages have been approved
expired	Instance has passed its expiration date

Instance Operations

Operation	Who Can Do It	Notes
Create instance	Any user with resource access	Applies a policy to a specific resource
Update metadata	Instance creator or admin	Modify stage field data
Submit for approval	Instance creator or admin	Sends to validators for review
Approve stage	Authorized validators or admin	Advances workflow to next stage
Deny stage	Authorized validators or admin	Sends back for revision
Add comment	Any user with instance access	Discussion during review
Delete instance	Creator or admin	Cannot delete completed instances
Share instance	Creator or admin	Grant view/comment access to users

Signoff Records

Each approval or denial creates an immutable signoff record:

Field	Description
stageId	Which stage was reviewed
validatorId / validatorName	Who made the decision
decision	approved, denied, or conditional
comments	Reviewer's comments and feedback
conditions	Array of conditions for conditional approvals
timestamp	When the decision was made

Sharing Policies and Instances

Both policies and instances support sharing with specific users:

• Share policy — Allows specified users to view and use the policy
• Unshare policy — Removes access for specified users
• Share instance — Allows specified users to view and comment on the instance
• Unshare instance — Removes access for specified users

Only the owner (creator) or administrators can share or unshare.

Policy Examples

Production Deployment Approval

Category: Operational | Severity: High | Resources: Applications, Workflows

Stage	Validator	Purpose
1. Security Review	Security team (role)	Validate security requirements and scans
2. Technical Approval	Lead engineer (user)	Approve technical implementation
3. Business Sign-off	Product owner (user)	Confirm business requirements met

Enforcement: hard_block in Production, soft_block in Staging, warning in Development

Data Privacy Compliance

Category: Compliance | Severity: Critical | Resources: Data Sources, Applications

Stage	Validator	Purpose
1. Data Classification	Data steward (role)	Classify data sensitivity level
2. Privacy Impact Assessment	Privacy officer (user)	Document privacy implications
3. Legal Review	Legal team (group)	Approve data handling procedures

Enforcement: hard_block in all environments

AI Model Safety Validation

Category: Quality | Severity: High | Resources: AI Gateway Models, ML Models

Stage	Validator	Purpose
1. Performance Metrics	Data scientist (role)	Document accuracy, precision, recall
2. Bias Analysis	AI ethics reviewer (user)	Assess model for bias across protected groups
3. Guardrail Verification	Security team (role)	Verify required guardrails are enabled
4. Model Approval	Data science lead (user)	Final deployment approval

Enforcement: hard_block in Production, soft_block in Staging, warning in Development

Infrastructure Security

Category: Security | Severity: Critical | Resources: Add-ons, Data Sources

Stage	Validator	Purpose
1. Encryption Verification	DevOps (role)	Verify encryption at rest and in transit
2. Access Control Review	Security (role)	Review access policies and IAM
3. Network Isolation	Infrastructure lead (user)	Confirm network segmentation

Enforcement: hard_block in Production and Staging

Important

Policies with hard_block enforcement prevent resource deployment until all required stages are completed. Use warning enforcement in development environments to avoid blocking developer workflows while still tracking compliance.