Workflow Policy & Governance
Central policy-as-code layer governing retry ceilings, mutating workflow controls, verification requirements, and context cascade thresholds.
Context
Schema validation guaranteed workflow structure, but semantic governance was distributed across workflow authors and review habits. Retry policies differed without a global safety ceiling, mutating and non-mutating workflows were not always treated differently, verification expectations were inconsistent, and exemptions were hard to audit.
Core Decisions
1. Policy File Owns Global Guardrails
The policy file defines organization-level constraints:
- Workflow class inventory (mutating vs non-mutating)
- Retry ceilings and allowed retry strategies
- Actions requiring retry metadata
- Verification requirements by workflow or agent
- Compaction and context cascade thresholds
2. Schema and Policy Have Explicit Separation
Schema defines valid structure and field types. Policy defines allowed behavior and governance intent. This preserves a stable authoring experience while allowing governance evolution without schema churn.
3. Mutating Flows Receive Stricter Controls
Mutating workflows must include review/verification gates and cannot bypass configured guardrails unless explicitly exempted.
4. Exemptions Are Explicit and Reviewable
Policy supports scoped exemptions by step or agent, but each exemption must be declarative, minimal, and visible to tests.
5. CI Is the Enforcement Point
Policy violations fail the agent test suite. Workflow changes are incomplete until both schema and policy checks pass.
Validation Flow
Workflow YAML
Author submits or edits a workflow definition.
Schema Validation
Structural rules are checked against the JSON schema.
Policy Validation
Semantic governance rules are evaluated against the policy file.
Graph & Routing Tests
Graph safety, routing regressions, and overlap risk are tested.
CI Gate
All checks must pass before the change is merge-ready.