Stages & Promotion

Policy stages define the individual steps within a governance workflow. Each stage collects information, routes to validators for approval, and records signoff decisions. The promotion system uses policy compliance status to gate resource movement between environments.

Stage Structure

Each stage within a policy contains:

Field	Description
name	Descriptive name (e.g., "Security Review", "Technical Approval")
order	Sequential position in the workflow
isRequired	Whether this stage must be completed or can be skipped
fields	Array of custom form fields for data collection
validators	Array of validator assignments for approval
dependencies	Stage IDs that must complete first
slaHours	Expected completion time — escalations trigger when overdue

Custom Fields

Each stage can define custom form fields that users must complete before submitting for approval. Fields are rendered as a form in the Validation Workflow UI.

Field Types

Type	Use Case	Example
text	Short answers, identifiers	"Security scan ID"
textarea	Detailed responses, justifications	"Describe the changes"
richtext	Formatted documentation, reports	"Privacy Impact Assessment"
radio	Single selection from options	"Risk Level: Low / Medium / High"
checkbox	Multiple selection checklist	"Compliance items verified"
dropdown	Single selection dropdown	"Target environment"
multiselect	Multiple selection	"Applicable frameworks"
file	Evidence documents, reports	"Upload security scan report"
number	Metrics, scores, counts	"Model accuracy score (0-100)"
date	Target dates, deadlines	"Expected completion date"
datetime	Scheduled events	"Deployment window"
url	External evidence links	"Link to test dashboard"
email	Contact information	"Responsible engineer's email"

Field Properties

Property	Description
name	Machine-readable identifier (used in data storage)
label	Human-readable display label shown in the form
required	Whether the field must be completed before submission
defaultValue	Pre-populated value
helpText	Guidance text displayed below the field
placeholder	Placeholder text shown in empty fields
options	Array of choices for selection fields
validation	Regex pattern, min/max values, or custom rules
conditionalOn	Show field only when another field has a specific value

Conditional Display

Fields can be conditionally shown or hidden based on other field values. For example, a "Justification" textarea can be shown only when a "Risk Level" radio field is set to "High":

Field: risk_level (radio: Low, Medium, High)
Field: justification (textarea, conditionalOn: risk_level = "High")

This keeps forms focused by only showing relevant fields.

Validators

Validators are the users or groups authorized to approve or deny a stage. When a stage is submitted for approval, all active validators are notified.

User Validators

Assign a specific user by their user ID. Only that exact user can approve the stage.

{ type: "user", identifier: "<userId>", isActive: true }

Best for: Designated reviewers, specific subject-matter experts, compliance officers.

Role-Based Validators

Assign by role name. Any user who holds the specified role can approve.

{ type: "role", identifier: "admin", isActive: true }

Best for: Flexible team assignments where any team member with the right role can approve. Team changes don't require policy updates.

Group Validators

Assign by organization membership. The system checks active membership in the organization.

Organization + Role format:

{ type: "group", identifier: "org:<orgId>:role:<memberRole>", isActive: true }

Organization-only format:

{ type: "group", identifier: "<organizationId>", isActive: true }

Best for: Cross-team approvals, committee reviews, organization-wide compliance requirements.

Validator Activation

Each validator has an isActive flag. Set to false to temporarily disable a validator without removing them from the stage configuration. This is useful for:

• Handling temporary absences or vacations
• Role transitions during team changes
• Temporarily reducing required approvers

Admin Override

Administrators can always approve or deny any stage regardless of validator assignments. This serves as a safety valve for urgent situations and should be used sparingly.

Approval Decisions

When a validator reviews a submitted stage, they can make one of three decisions:

Approve

The stage is marked as completed. If remaining stages exist, the instance advances to the next stage. If this was the last required stage, the policy instance status becomes completed.

{
  "stageId": "stage-1",
  "validatorId": "user_123",
  "validatorName": "Jane Smith",
  "decision": "approved",
  "comments": "All security requirements met. Scan passed.",
  "timestamp": "2026-02-25T14:30:00Z"
}

Conditional Approval

The stage is approved with documented conditions. The policy instance advances, but conditions are recorded for tracking and follow-up.

{
  "decision": "conditional",
  "comments": "Approved pending resolution of items below",
  "conditions": [
    "Update security scan by end of week",
    "Add unit tests for edge cases identified in review"
  ]
}

Deny

The stage is rejected. The policy instance status changes to denied. The requestor must address the reviewer's feedback, update the stage fields, and resubmit for approval.

{
  "decision": "denied",
  "comments": "Missing required threat model document. Please add before resubmitting."
}

Comments

Any user with access to a policy instance can add comments at any time. Comments support ongoing discussion between requestors and reviewers throughout the approval process.

Comments can optionally be associated with a specific stage:

{
  "author": "user_456",
  "authorName": "John Doe",
  "content": "Updated the threat model document as requested. See attachment.",
  "stageId": "stage-1",
  "timestamp": "2026-02-25T15:45:00Z"
}

Notifications

The governance notification system keeps stakeholders informed at each step of the approval workflow.

Notification Triggers

Event	Recipients	Priority
Stage submitted for approval	All active validators for the stage	High
Stage approved	Instance creator	Medium
Stage denied	Instance creator	High
Conditional approval	Instance creator	Medium
SLA deadline approaching	Validators and creator	High
Escalation (SLA exceeded)	Validators, creator, and admins	Critical
Attestation expiring	Attestation author	High
Compliance drift detected	Solution owners	Medium

Configuring Notification Preferences

Users can configure their notification preferences from their profile settings:

Setting	Options
Channels	Email, in-app, or both
Digest Mode	Batch notifications: daily, weekly, or never
Digest Time	Preferred time for digest delivery
Type Filters	Enable/disable per notification type
Quiet Hours	Time window to suppress non-critical notifications

Available notification type filters:

• Approval required
• Approval decisions (granted/denied)
• Escalation alerts
• Deadline reminders
• Policy violations
• Compliance alerts

Promotion Control

The promotion system gates resource movement between environments (Development → Staging → Production) based on policy compliance status.

Requesting a Promotion

1. Navigate to Governance > Promotions (or /governance/promotions)
2. Fill out the promotion request form:
   • Resource Type — Select the resource type (app, workflow, model, etc.)
   • Resource — Select the specific resource
   • From Environment — Current environment (e.g., Development)
   • To Environment — Target environment (e.g., Staging, Production)
3. The system evaluates compliance:
   • Queries all policy instances for the resource
   • Identifies blocking issues (incomplete or denied instances)
   • Calculates compliance metrics

Promotion Outcomes

Outcome	Description
Auto-Approved	All policies are completed — promotion proceeds immediately
Pending	Blocking issues found — promotion requires resolution or override
Denied	Critical violations prevent promotion — must be resolved

Compliance Status

Each promotion request includes a compliance summary:

Metric	Description
isCompliant	Whether all policies are satisfied
completedPolicies	Count of completed policy instances
totalPolicies	Total applicable policy instances
criticalViolations	Count of critical blocking issues
warnings	Count of low-severity issues
blockingIssues	Detailed list of what blocks the promotion

Blocking Issues

Each blocking issue includes:

Field	Description
policyId	Which policy is not satisfied
severity	Issue severity level
issue	Description of what is incomplete
canOverride	Whether an admin can override this block

Admin Override

When a promotion is blocked, administrators can override with a justification:

1. Admin reviews the blocking issues and promotion request
2. Admin clicks Override and provides a written justification explaining the business need
3. The system creates an override record with the justification, approver, and timestamp
4. Promotion proceeds with status overridden
5. The override is logged permanently in the audit trail

Override records include: resource ID, blocked policies, justification, approver, timestamp, and expiration date. Overrides can be revoked at any time with a reason.

Stage Workflow Patterns

Sequential Workflow

Stages complete one after another in order. Each stage must be approved before the next begins.

Stage 1 (Security Review) → Stage 2 (Technical Approval) → Stage 3 (Business Sign-off)

Best for: Linear approval processes where each stage depends on the previous one.

Multi-Validator Stage

A single stage with multiple validators where all (or a majority) must approve.

Stage 1: [Security Lead + Compliance Officer + Privacy Officer] → Stage 2

Best for: Committee decisions, cross-functional reviews requiring multiple perspectives.

Progressive Escalation

Use enforcement rules with increasing severity across environments to create a progressive compliance ramp:

Development:  warning       → Track compliance without blocking
Staging:      soft_block    → Require compliance or override
Production:   hard_block    → Strict enforcement, no workarounds

This allows developers to work freely in development while enforcing strict compliance in production. Teams can measure compliance patterns in development before tightening enforcement.

Dependency Chains

Stages can declare dependencies on other stages, allowing parallel review paths that converge:

Stage 1 (Security Review)  ─┐
                             ├→ Stage 3 (Final Approval)
Stage 2 (Technical Review)  ─┘

Best for: Parallel review tracks that must both complete before final sign-off.

Best Practices

Design Focused Stages

• Each stage should have a single, clear purpose
• Avoid combining unrelated reviews in one stage
• Break complex reviews into smaller, focused stages
• Use descriptive stage names that indicate what is being reviewed
• Keep the number of stages manageable (2-4 stages covers most workflows)

Choose Appropriate Validators

• Use role-based validators for flexibility as team membership changes
• Use user-specific validators for specialized reviews requiring particular expertise
• Use group validators for organization-wide compliance requirements
• Keep the number of required approvers manageable — too many slows the process
• Use the isActive flag for temporary absences instead of removing validators

Provide Clear Instructions

• Add help text to every form field explaining what is expected
• Include examples of valid input where appropriate
• Link to relevant documentation or guidelines in URL fields
• Use rich text fields for structured data entry and formatted responses
• Set sensible default values to reduce friction

Set Realistic Enforcement

• Start with warning enforcement to understand compliance patterns and adoption
• Graduate to soft_block once teams are familiar with the process
• Reserve hard_block for production environments and critical policies
• Review override frequency — frequent overrides suggest the policy needs adjustment
• Set realistic SLA hours based on actual review times

tip

Start with simple 2-3 stage policies and add complexity as governance needs mature. Most compliance requirements can be addressed with well-designed sequential stages.