output-contract-enforcer

name	output-contract-enforcer
description	Validates that a DAG node's output matches its declared JSON schema before passing to downstream nodes. The glue that makes multi-agent DAGs reliable. Use when checking output contract compliance, generating validation schemas from descriptions, or debugging contract mismatches between nodes. Activate on "validate output", "output contract", "schema validation", "contract mismatch", "output doesn't match". NOT for content quality assessment (use dag-quality), skill grading (use skill-grader), or general JSON schema work outside DAG context.
allowed-tools	Read,Write,Edit,Grep
argument-hint	[output-json] [schema]
metadata	{"tags":["output","contract","enforcer","validate-output","output-contract"],"pairs-with":[{"skill":"task-decomposer","reason":"Decomposed tasks define the output schemas that the enforcer validates between nodes"},{"skill":"human-gate-designer","reason":"Human gate inputs/outputs need the same schema validation as automated node outputs"},{"skill":"typescript-advanced-patterns","reason":"Branded types and Zod schemas implement runtime output contract validation in TypeScript"}]}

Output Contract Enforcer

Validates that a DAG node's output matches its declared JSON schema before passing to downstream nodes. The glue that makes multi-agent DAGs reliable. Without this, downstream nodes receive unpredictable input and the DAG breaks.

---

When to Use

✅ Use for:

• Validating a node's output against its declared schema
• Generating output schemas from natural-language output descriptions
• Debugging why a downstream node rejected its input
• Ensuring contract compatibility between connected nodes

❌ NOT for:

• Assessing content quality or correctness (use dag-quality)
• Grading skill quality (use skill-grader)
• General JSON schema work outside DAG context

---

Validation Process

flowchart TD
  O[Node output] --> P[Parse as JSON]
  P -->|Parse error| E1[FAIL: Not valid JSON]
  P -->|Valid JSON| S[Check against schema]
  S --> R{Required fields?}
  R -->|Missing| E2[FAIL: Missing required field X]
  R -->|Present| T{Type check?}
  T -->|Wrong type| E3[FAIL: Field X expected string, got number]
  T -->|Correct| C{Constraints?}
  C -->|Violated| E4[FAIL: Field X violates constraint Y]
  C -->|Met| V[PASS: Contract satisfied]

What Gets Checked

Check	Example	Failure Message
JSON parseable	{broken json	"Output is not valid JSON"
Required fields	status missing	"Missing required field: status"
Field types	status: 42 (expected string)	"Field 'status' expected string, got number"
Enum values	status: "maybe"	"Field 'status' must be one of: pass, warn, fail"
String constraints	summary: "" (minLength: 1)	"Field 'summary' must have minLength 1"
Number constraints	score: 1.5 (maximum: 1.0)	"Field 'score' must be ≤ 1.0"
Array constraints	items: [] (minItems: 1)	"Field 'items' must have at least 1 item"
Nested objects	Missing sub-field	"Field 'metadata.cost' is required"

The Standard Output Contract

Every DAG node should produce output matching this base schema (fields can be extended):

{
  "type": "object",
  "required": ["status", "summary"],
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pass", "warn", "fail"]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "description": "1-3 sentence description of what was produced"
    },
    "artifacts": {
      "type": "array",
      "items"    
       
    
     
       
       
    
     
       
          
       
    
  

Contract Compatibility Check

When connecting Node A's output to Node B's input, verify:

1. Every field B requires is present in A's output schema
2. Types match (A produces string, B expects string)
3. A's output constraints are compatible with B's input constraints
4. If A produces optional fields that B requires → incompatible

Node A output: { status: string, recommendations: string[] }
Node B input:  { status: string, recommendations: string[], priority: number }

Result: INCOMPATIBLE — Node B requires 'priority' but Node A doesn't produce it.
Fix: Add 'priority' to Node A's output, or add a transformer node between A and B.

---

Schema Generation

When a node description says "produces a list of recommendations with priorities," generate:

{
  "type": "object",
  "required": ["status", "summary", "data"],
  "properties": {
    "status": { "type": "string", "enum": ["pass", "warn", "fail"] },
    "summary": { "type": "string", "minLength": 1 },
    "data": {
      "type": "object",
      "required": ["recommendations"]
       
         
           
           
           
             
              
             
                  
                      
            
          
        
      
    
  

---

Anti-Patterns

No Contract at All

Wrong: Nodes produce free-form text with no schema. Why: Downstream nodes can't reliably parse the input. The DAG is fragile. Right: Every node declares its output schema. Every output is validated before passing downstream.

Overly Strict Contracts

Wrong: Requiring exact character counts, specific formatting, or field values that depend on runtime context. Right: Constrain structure (types, required fields), not content. Let dag-quality handle content assessment.

Ignoring Optional Fields

Wrong: Treating all fields as required. Right: Use required only for fields that downstream nodes absolutely need. Mark everything else as optional.