Spec: conditional state machine transitions based on capability output values

[enricopiovesan]

Summary

Extend the app state machine spec (spec 047-app-state-machine) to support conditional transitions: the next state is determined by evaluating a predicate against the capability output, not just the event type.

This is required to implement branching workflows — e.g. auto-approve when confidence is high, route to human review when confidence is low.

New primitive: transition condition

In the manifest state_machine block, a transition may include a condition field:

{
  "id": "extracting",
  "invoke": { "capability_id": "doc-approval.extract", "input_from": "session.context" },
  "transitions": [
    {
      "on": "capability_succeeded",
      "condition": { "field": "output.confidence_score", "op": "gte", "value": 0.85 },
      "to": "auto_approved"
    },
    {
      "on": "capability_succeeded",
      "condition": { "field": "output.confidence_score", "op": "lt", "value": 0.85 },
      "to": "pending_review"
    },
    { "on": "capability_failed", "to": "extraction_error" }
  ]
}

Condition operators

Op	Meaning
eq	equal
neq	not equal
gt	greater than
gte	greater than or equal
lt	less than
lte	less than or equal
in	value is in array
exists	field is present and non-null

Field path

field is a dot-path into the capability output: output.confidence_score, output.recommendation, output.extracted_fields.date.

Evaluation semantics

• Conditions are evaluated in order. First match wins.
• If no condition matches on capability_succeeded, the runtime emits a no_matching_transition error event.
• A transition with no condition is an unconditional fallback — evaluated last.
• Type mismatch (comparing string to number) → condition_type_error event, state stays unchanged.

Definition of Done

• Spec 047 updated with condition field schema and evaluation semantics
• Runtime evaluates conditions on capability_succeeded in manifest order, first match wins
• traverse-cli app validate rejects manifests where no transition is reachable (dead-end detection)
• traverse-cli app validate warns when condition fields reference paths not in the capability output contract
• Integration test: confidence_score = 0.90 → auto_approved; confidence_score = 0.70 → pending_review
• Error events for no_matching_transition and condition_type_error documented in spec

Unblocks

• App-References: doc-approval branching state machine
• All future apps with conditional routing