Approval Workflows

[!WARNING] Status: Planned. Approval workflows are part of the governance layer currently under development. The design below describes the planned behavior.

Approval Workflows will allow you to define who must sign off on a change based on what is being changed. These policies will be defined in .choochoo/approval-policies.yaml within your project structure. For an overview of how approvals fit into the platform, see the Architecture.

Policy Schema

policies:
  - name: pii-change-policy
    description: "Requires Security Team approval for PII changes"
    trigger:
      tags: ["pii", "gdpr"]
      env: ["production"]
    approvers:
      - role: "security-engineer"
        team: "sec-ops"
        minApprovals: 1
    slaHours: 24

The trigger.tags field references compliance tags that are applied to fields in your Contracts. When a tagged field is modified, the policy is activated. The tags also feed into the Risk Scoring algorithm, which determines the severity level of the approval gate.

How It Works

1. Triggering: When an artifact is submitted (choochoo governance submit), the Engine evaluates the change against the triggers in approval-policies.yaml.
2. Matching: If a policy matches (e.g., a PII field was modified in Prod), the submission enters a pending_approval state. This is part of the artifact lifecycle.
3. Notification: The designated team is notified (via configured integrations). In The Station, pending approvals appear in the dashboard.
4. Action: An approver runs choochoo governance approve <id>. The approval is recorded in the Audit Trail.
5. Execution: Once all required approvals are met, the change is applied. The Decision Trace captures the full approval chain.

In CI/CD pipelines, a pending approval causes the CLI to return exit code 10 (APPROVAL_REQUIRED), blocking the pipeline until the approval is obtained.

Risk-Based Approval Levels

The number and type of approvers required depends on the risk score of the change:

The risk score is calculated based on compliance sensitivity, impact radius from the Lineage Graph, agent confidence, and environment. See Risk Scoring for the full algorithm.

Agent Interactions

When an AI agent triggers an approval workflow:

• The agent's action is paused and a Decision Trace is recorded with the pending state.
• The agent's System Card is referenced to determine if the action falls within its documented capabilities.
• If the agent has a requires-approval boundary, all its actions trigger approval regardless of risk score.
• Boundary violations (attempting actions outside permitted scope) produce error E007 and are logged in the Audit Trail.

Emergency Overrides

In "break glass" scenarios, an admin can force an approval. This event is logged with the highest severity in the Audit Trail and will appear prominently in Compliance Reports. Emergency overrides are subject to post-hoc review and may trigger additional notifications.

Configuration

Approval policies are configured in two places:

1. .choochoorc — The governance.requireApproval field lists compliance tags that always require approval.
2. .choochoo/approval-policies.yaml — Granular policies with team-specific approvers, SLAs, and environment scoping.

See the Configuration guide for the full schema and available options.

Related