capability_ontology.yaml

# Grounded Agency Capability Ontology
# Version: 2.0.0
# 36 atomic capabilities derived from first principles
# See: docs/methodology/FIRST_PRINCIPLES_REASSESSMENT.md
---
meta:
  name: Grounded Agency Capability Ontology
  version: 2.0.0
  generated_at: '2026-01-26T00:00:00.000Z'
  description: 36 atomic capabilities derived from first principles
  principles:
  - Capabilities are atomic and composable into workflows
  - Every capability returns evidence anchors and confidence
  - High-risk capabilities require checkpoint + verification
  - Capabilities are organized into 9 cognitive layers
  derivation:
    method: First-principles analysis
    sources:
    - BDI cognitive architecture
    - ReAct agent pattern
    - Claude Skills architecture
    - MCP tool patterns
    documentation: docs/methodology/FIRST_PRINCIPLES_REASSESSMENT.md
layers:
  PERCEIVE:
    description: Information acquisition from the world
    cognitive_mapping: 'BDI: Belief acquisition'
    capabilities:
    - retrieve
    - search
    - observe
    - receive
  UNDERSTAND:
    description: Making sense of information
    cognitive_mapping: 'BDI: Belief formation'
    capabilities:
    - detect
    - classify
    - measure
    - predict
    - compare
    - discover
  REASON:
    description: Planning and analysis
    cognitive_mapping: 'BDI: Deliberation'
    capabilities:
    - plan
    - decompose
    - critique
    - explain
  MODEL:
    description: World representation
    cognitive_mapping: 'BDI: World model'
    capabilities:
    - state
    - transition
    - attribute
    - ground
    - simulate
  SYNTHESIZE:
    description: Content creation
    cognitive_mapping: Action planning
    capabilities:
    - generate
    - transform
    - integrate
  EXECUTE:
    description: Changing the world
    cognitive_mapping: 'BDI: Intention execution'
    capabilities:
    - execute
    - mutate
    - send
  VERIFY:
    description: Correctness assurance
    cognitive_mapping: Control theory
    capabilities:
    - verify
    - checkpoint
    - rollback
    - constrain
    - audit
  REMEMBER:
    description: State persistence
    cognitive_mapping: 'Cognitive: Long-term memory'
    capabilities:
    - persist
    - recall
  COORDINATE:
    description: Multi-agent and user interaction
    cognitive_mapping: Multi-agent systems
    capabilities:
    - delegate
    - synchronize
    - invoke
    - inquire
nodes:
- id: retrieve
  layer: PERCEIVE
  description: Get specific data by reference (ID, path, URI)
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - target
    properties:
      target:
        type: string
        description: Reference to data (ID, path, URI)
      format:
        type: string
        description: Expected format of retrieved data
  output_schema:
    type: object
    required:
    - data
    - evidence_anchors
    - confidence
    properties:
      data:
        type: any
        description: Retrieved data
      evidence_anchors:
        type: array
        description: Source references
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: search
  layer: PERCEIVE
  description: Query for data matching criteria
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - query
    properties:
      query:
        type: string|object
        description: Search criteria
      scope:
        type: string
        description: Search scope/domain
      limit:
        type: integer
        description: Maximum results
  output_schema:
    type: object
    required:
    - results
    - evidence_anchors
    - confidence
    properties:
      results:
        type: array
        description: Matching items
      total_count:
        type: integer
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: observe
  layer: PERCEIVE
  description: Watch and report current state
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - target
    properties:
      target:
        type: string
        description: What to observe
      aspects:
        type: array
        description: Specific aspects to observe
  output_schema:
    type: object
    required:
    - observation
    - evidence_anchors
    - confidence
    properties:
      observation:
        type: object
        description: Current state
      timestamp:
        type: string
        format: date-time
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: receive
  layer: PERCEIVE
  description: Accept pushed data or events
  risk: low
  mutation: false
  input_schema:
    type: object
    properties:
      channel:
        type: string
        description: Source channel
      filter:
        type: object
        description: Event filter criteria
      timeout:
        type: string
        description: Wait timeout
  output_schema:
    type: object
    required:
    - data
    - evidence_anchors
    properties:
      data:
        type: array
        items:
          type: object
        description: Received data/events
      source:
        type: string
        description: Event source
      timestamp:
        type: string
        format: date-time
      evidence_anchors:
        type: array
- id: detect
  layer: UNDERSTAND
  description: Find patterns or occurrences in data
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - data
    - pattern
    properties:
      data:
        type: any
        description: Data to analyze
      pattern:
        type: string|object
        description: Pattern to find
      threshold:
        type: number
        description: Detection threshold
  output_schema:
    type: object
    required:
    - detected
    - evidence_anchors
    - confidence
    properties:
      detected:
        type: boolean
      matches:
        type: array
        description: Found occurrences
      locations:
        type: array
        description: Where patterns found
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: classify
  layer: UNDERSTAND
  description: Assign labels or categories to items
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - item
    properties:
      item:
        type: any
        description: Item to classify
      taxonomy:
        type: string|array
        description: Classification scheme
      multi_label:
        type: boolean
        description: Allow multiple labels
  output_schema:
    type: object
    required:
    - labels
    - evidence_anchors
    - confidence
    properties:
      labels:
        type: array
        description: Assigned labels
      probabilities:
        type: object
        description: Label probabilities
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: measure
  layer: UNDERSTAND
  description: Quantify values with uncertainty
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - target
    - metric
    properties:
      target:
        type: any
        description: What to measure
      metric:
        type: string
        description: Measurement type
      unit:
        type: string
        description: Unit of measurement
  output_schema:
    type: object
    required:
    - value
    - uncertainty
    - evidence_anchors
    - confidence
    properties:
      value:
        type: number
      uncertainty:
        type: object
        properties:
          lower:
            type: number
          upper:
            type: number
      unit:
        type: string
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: predict
  layer: UNDERSTAND
  description: Forecast future states or outcomes
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - target
    properties:
      target:
        type: string
        description: What to predict
      horizon:
        type: string
        description: Prediction timeframe
      conditions:
        type: object
        description: Assumed conditions
  output_schema:
    type: object
    required:
    - prediction
    - probability
    - evidence_anchors
    - confidence
    properties:
      prediction:
        type: any
        description: Predicted outcome
      probability:
        type: number
        minimum: 0
        maximum: 1
      alternatives:
        type: array
        description: Alternative outcomes
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: compare
  layer: UNDERSTAND
  description: Evaluate alternatives against criteria
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - options
    properties:
      options:
        type: array
        description: Items to compare
      criteria:
        type: array
        description: Evaluation criteria
      weights:
        type: object
        description: Criteria weights
  output_schema:
    type: object
    required:
    - ranking
    - evidence_anchors
    - confidence
    properties:
      ranking:
        type: array
        description: Ordered options
      scores:
        type: object
        description: Scores per option
      recommendation:
        type: string
        description: Top choice
      tradeoffs:
        type: array
        description: Key tradeoffs
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: discover
  layer: UNDERSTAND
  description: Find previously unknown patterns
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - data
    properties:
      data:
        type: any
        description: Data to explore
      constraints:
        type: object
        description: Discovery constraints
      method:
        type: string
        description: Discovery approach
  output_schema:
    type: object
    required:
    - patterns
    - evidence_anchors
    - confidence
    properties:
      patterns:
        type: array
        description: Discovered patterns
      relationships:
        type: array
        description: Found relationships
      anomalies:
        type: array
        description: Unusual findings
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: plan
  layer: REASON
  description: Create action sequence to achieve goal
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - goal
    properties:
      goal:
        type: string
        description: Desired outcome
      constraints:
        type: object
        description: Planning constraints
      resources:
        type: array
        description: Available resources
  output_schema:
    type: object
    required:
    - steps
    - evidence_anchors
    - confidence
    properties:
      steps:
        type: array
        description: Ordered action steps
      dependencies:
        type: object
        description: Step dependencies
      risks:
        type: array
        description: Identified risks
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: decompose
  layer: REASON
  description: Break problem into subproblems
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - problem
    properties:
      problem:
        type: string
        description: Problem to decompose
      max_depth:
        type: integer
        description: Maximum decomposition depth
      strategy:
        type: string
        description: Decomposition strategy
  output_schema:
    type: object
    required:
    - subproblems
    - evidence_anchors
    - confidence
    properties:
      subproblems:
        type: array
        description: Component problems
      structure:
        type: object
        description: Problem hierarchy
      dependencies:
        type: array
        description: Subproblem dependencies
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: critique
  layer: REASON
  description: Identify weaknesses and issues
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - target
    properties:
      target:
        type: any
        description: What to critique
      criteria:
        type: array
        description: Evaluation criteria
      severity_threshold:
        type: string
        description: Minimum severity to report
  output_schema:
    type: object
    required:
    - issues
    - evidence_anchors
    - confidence
    properties:
      issues:
        type: array
        description: Found weaknesses
      severity:
        type: object
        description: Issue severities
      suggestions:
        type: array
        description: Improvement suggestions
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: explain
  layer: REASON
  description: Justify conclusions with reasoning
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - conclusion
    properties:
      conclusion:
        type: any
        description: What to explain
      audience:
        type: string
        description: Target audience
      depth:
        type: string
        enum:
        - brief
        - detailed
        - comprehensive
  output_schema:
    type: object
    required:
    - explanation
    - evidence_anchors
    - confidence
    properties:
      explanation:
        type: string
        description: Reasoning explanation
      premises:
        type: array
        description: Supporting premises
      chain:
        type: array
        description: Reasoning chain
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: state
  layer: MODEL
  description: Create representation of current world state
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - scope
    properties:
      scope:
        type: string
        description: What to model
      schema:
        type: object
        description: State schema
      timestamp:
        type: string
        format: date-time
  output_schema:
    type: object
    required:
    - state
    - evidence_anchors
    - confidence
    properties:
      state:
        type: object
        description: World state representation
      entities:
        type: array
        description: Identified entities
      relationships:
        type: array
        description: Entity relationships
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: transition
  layer: MODEL
  description: Define how state changes over time
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - from_state
    properties:
      from_state:
        type: object
        description: Initial state
      to_state:
        type: object
        description: Target state (optional)
      triggers:
        type: array
        description: What causes transition
  output_schema:
    type: object
    required:
    - rules
    - evidence_anchors
    - confidence
    properties:
      rules:
        type: array
        description: Transition rules
      preconditions:
        type: array
        description: Required conditions
      effects:
        type: array
        description: State changes
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: attribute
  layer: MODEL
  description: Establish cause-effect relationships
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - effect
    properties:
      effect:
        type: any
        description: Observed effect
      candidates:
        type: array
        description: Potential causes
      context:
        type: object
        description: Situational context
  output_schema:
    type: object
    required:
    - causes
    - evidence_anchors
    - confidence
    properties:
      causes:
        type: array
        description: Identified causes
      strengths:
        type: object
        description: Causal strengths
      mechanism:
        type: string
        description: Causal mechanism
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: ground
  layer: MODEL
  description: Anchor claims to evidence
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - claim
    properties:
      claim:
        type: string
        description: Claim to ground
      sources:
        type: array
        description: Evidence sources
      required_strength:
        type: string
        enum:
        - weak
        - moderate
        - strong
  output_schema:
    type: object
    required:
    - grounded
    - evidence_anchors
    - confidence
    properties:
      grounded:
        type: boolean
        description: Whether claim is grounded
      evidence:
        type: array
        description: Supporting evidence
      gaps:
        type: array
        description: Evidence gaps
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: simulate
  layer: MODEL
  description: Run what-if scenarios
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - scenario
    properties:
      scenario:
        type: object
        description: Scenario to simulate
      initial_state:
        type: object
        description: Starting state
      steps:
        type: integer
        description: Simulation steps
  output_schema:
    type: object
    required:
    - outcomes
    - evidence_anchors
    - confidence
    properties:
      outcomes:
        type: array
        description: Simulation results
      trajectory:
        type: array
        description: State trajectory
      final_state:
        type: object
        description: End state
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: generate
  layer: SYNTHESIZE
  description: Produce new content
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - specification
    properties:
      specification:
        type: string|object
        description: What to generate
      format:
        type: string
        description: Output format
      constraints:
        type: object
        description: Generation constraints
  output_schema:
    type: object
    required:
    - content
    - evidence_anchors
    - confidence
    properties:
      content:
        type: any
        description: Generated content
      metadata:
        type: object
        description: Generation metadata
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: transform
  layer: SYNTHESIZE
  description: Convert between formats
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - input
    - target_format
    properties:
      input:
        type: any
        description: Data to transform
      source_format:
        type: string
        description: Input format
      target_format:
        type: string
        description: Output format
      options:
        type: object
        description: Transformation options
  output_schema:
    type: object
    required:
    - output
    - evidence_anchors
    - confidence
    properties:
      output:
        type: object
        description: Transformed data
      changes:
        type: array
        description: Applied transformations
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: integrate
  layer: SYNTHESIZE
  description: Merge data from multiple sources
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - sources
    properties:
      sources:
        type: array
        description: Data sources to merge
      strategy:
        type: string
        description: Merge strategy
      conflict_resolution:
        type: string
        description: How to handle conflicts
  output_schema:
    type: object
    required:
    - merged
    - evidence_anchors
    - confidence
    properties:
      merged:
        type: object
        description: Integrated data
        properties:
          observations:
            type: array
            description: Merged observations
          meta:
            type: object
            properties:
              world_id:
                type: string
                description: World model identifier
      conflicts:
        type: array
        description: Resolved conflicts
      provenance:
        type: object
        description: Source provenance
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: execute
  layer: EXECUTE
  description: Run code or script deterministically
  risk: medium
  mutation: false
  requires_approval: true
  input_schema:
    type: object
    required:
    - code
    properties:
      code:
        type: string
        description: Code to execute
      language:
        type: string
        description: Programming language
      timeout:
        type: string
        description: Execution timeout
      environment:
        type: object
        description: Execution environment
  output_schema:
    type: object
    required:
    - result
    - evidence_anchors
    properties:
      result:
        type: any
        description: Execution result
      stdout:
        type: string
        description: Standard output
      stderr:
        type: string
        description: Standard error
      exit_code:
        type: integer
      evidence_anchors:
        type: array
- id: mutate
  layer: EXECUTE
  description: Change persistent state
  risk: high
  mutation: true
  requires_checkpoint: true
  requires_approval: true
  input_schema:
    type: object
    required:
    - target
    - operation
    properties:
      target:
        type: string
        description: What to modify
      operation:
        type: object
        description: Modification to apply
      checkpoint_id:
        type: string
        description: Recovery checkpoint
  output_schema:
    type: object
    required:
    - success
    - evidence_anchors
    properties:
      success:
        type: boolean
      previous_state:
        type: any
        description: State before mutation
      new_state:
        type: any
        description: State after mutation
      evidence_anchors:
        type: array
- id: send
  layer: EXECUTE
  description: Transmit data to external system
  risk: high
  mutation: true
  requires_checkpoint: true
  requires_approval: true
  input_schema:
    type: object
    required:
    - destination
    - payload
    properties:
      destination:
        type: string
        description: Target system/endpoint
      payload:
        type: any
        description: Data to send
      protocol:
        type: string
        description: Communication protocol
  output_schema:
    type: object
    required:
    - sent
    - evidence_anchors
    properties:
      sent:
        type: boolean
      response:
        type: any
        description: Response if any
      timestamp:
        type: string
        format: date-time
      evidence_anchors:
        type: array
- id: verify
  layer: VERIFY
  description: Check that conditions are met
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - conditions
    properties:
      target:
        type: any
        description: What to verify
      conditions:
        type: array
        description: Conditions to check
      strict:
        type: boolean
        description: Fail on first violation
  output_schema:
    type: object
    required:
    - passed
    - evidence_anchors
    - confidence
    properties:
      passed:
        type: boolean
      results:
        type: array
        description: Per-condition results
      violations:
        type: array
        description: Failed conditions
      evidence_anchors:
        type: array
      confidence:
        type: number
        minimum: 0
        maximum: 1
- id: checkpoint
  layer: VERIFY
  description: Save state for potential recovery
  risk: low
  mutation: true
  input_schema:
    type: object
    required:
    - scope
    properties:
      scope:
        type: string
        description: What to checkpoint
      label:
        type: string
        description: Checkpoint name
      metadata:
        type: object
        description: Additional metadata
  output_schema:
    type: object
    required:
    - checkpoint_id
    - evidence_anchors
    properties:
      checkpoint_id:
        type: string
        description: Checkpoint identifier
      timestamp:
        type: string
        format: date-time
      size:
        type: integer
        description: Checkpoint size
      evidence_anchors:
        type: array
- id: rollback
  layer: VERIFY
  description: Restore to previous checkpoint
  risk: medium
  mutation: true
  input_schema:
    type: object
    required:
    - checkpoint_id
    properties:
      checkpoint_id:
        type: string
        description: Checkpoint to restore
      scope:
        type: string
        description: What to rollback
  output_schema:
    type: object
    required:
    - restored
    - evidence_anchors
    properties:
      restored:
        type: boolean
      previous_state:
        type: any
        description: State before rollback
      restored_state:
        type: any
        description: State after rollback
      evidence_anchors:
        type: array
- id: constrain
  layer: VERIFY
  description: Enforce limits and policies
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - target
    - constraints
    properties:
      target:
        type: any
        description: What to constrain
      constraints:
        type: array
        description: Constraints to enforce
      action_on_violation:
        type: string
        enum:
        - block
        - warn
        - log
  output_schema:
    type: object
    required:
    - compliant
    - evidence_anchors
    properties:
      compliant:
        type: boolean
      violations:
        type: array
        description: Constraint violations
      actions_taken:
        type: array
        description: Enforcement actions
      evidence_anchors:
        type: array
- id: audit
  layer: VERIFY
  description: Record what happened and why
  risk: low
  # mutation: true because audit writes to persistent storage, but workflows
  # may override to false because append-only writes are non-destructive
  mutation: true
  input_schema:
    type: object
    required:
    - event
    properties:
      event:
        type: object
        description: Event to record
      context:
        type: object
        description: Event context
      retention:
        type: string
        description: How long to retain
  output_schema:
    type: object
    required:
    - recorded
    - evidence_anchors
    properties:
      recorded:
        type: boolean
      audit_id:
        type: string
        description: Audit record ID
      timestamp:
        type: string
        format: date-time
      evidence_anchors:
        type: array
- id: persist
  layer: REMEMBER
  description: Store data durably
  risk: low
  mutation: true
  input_schema:
    type: object
    required:
    - data
    properties:
      data:
        type: any
        description: Data to store
      key:
        type: string
        description: Storage key
      ttl:
        type: string
        description: Time to live
  output_schema:
    type: object
    required:
    - stored
    - evidence_anchors
    properties:
      stored:
        type: boolean
      key:
        type: string
        description: Storage key
      timestamp:
        type: string
        format: date-time
      evidence_anchors:
        type: array
- id: recall
  layer: REMEMBER
  description: Retrieve previously stored data
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - key
    properties:
      key:
        type: string
        description: Storage key
      default:
        type: any
        description: Default if not found
  output_schema:
    type: object
    required:
    - data
    - evidence_anchors
    properties:
      data:
        type: any
        description: Retrieved data
      found:
        type: boolean
      stored_at:
        type: string
        format: date-time
      evidence_anchors:
        type: array
- id: delegate
  layer: COORDINATE
  description: Assign task to another agent
  risk: medium
  mutation: false
  input_schema:
    type: object
    required:
    - task
    - agent
    properties:
      task:
        type: object
        description: Task to delegate
      agent:
        type: string
        description: Target agent
      constraints:
        type: object
        description: Delegation constraints
  output_schema:
    type: object
    required:
    - accepted
    - evidence_anchors
    properties:
      accepted:
        type: boolean
      task_id:
        type: string
        description: Delegated task ID
      agent:
        type: string
        description: Assigned agent
      evidence_anchors:
        type: array
- id: synchronize
  layer: COORDINATE
  description: Achieve state agreement across agents
  risk: medium
  mutation: false
  input_schema:
    type: object
    required:
    - agents
    - state
    properties:
      agents:
        type: array
        description: Agents to synchronize
      state:
        type: object
        description: State to agree on
      timeout:
        type: string
        description: Sync timeout
  output_schema:
    type: object
    required:
    - synchronized
    - evidence_anchors
    properties:
      synchronized:
        type: boolean
      agreed_state:
        type: object
        description: Agreed state
      participants:
        type: array
        description: Participating agents
      evidence_anchors:
        type: array
- id: invoke
  layer: COORDINATE
  description: Execute a composed workflow
  risk: medium
  mutation: false
  input_schema:
    type: object
    required:
    - workflow
    properties:
      workflow:
        type: string
        description: Workflow to invoke
      input:
        type: object
        description: Workflow input
      options:
        type: object
        description: Execution options
  output_schema:
    type: object
    required:
    - result
    - evidence_anchors
    properties:
      result:
        type: object
        description: Workflow result (contains nested workflow outputs)
      steps_executed:
        type: array
        description: Executed steps
      duration:
        type: string
        description: Execution time
      evidence_anchors:
        type: array
- id: inquire
  layer: COORDINATE
  description: Request clarification when input is ambiguous
  risk: low
  mutation: false
  input_schema:
    type: object
    required:
    - ambiguous_input
    properties:
      ambiguous_input:
        type: any
        description: The underspecified request or goal
      context:
        type: object
        description: Available context for question generation
      max_questions:
        type: integer
        default: 3
        description: Maximum clarifying questions to generate
  output_schema:
    type: object
    required:
    - questions
    - ambiguity_analysis
    - evidence_anchors
    - confidence
    properties:
      questions:
        type: array
        items:
          type: object
          properties:
            question:
              type: string
            parameter:
              type: string
              description: What parameter this resolves
            options:
              type: array
              description: Suggested answers if bounded
        description: Clarifying questions to resolve ambiguity
      ambiguity_analysis:
        type: object
        properties:
          missing_parameters:
            type: array
          conflicting_interpretations:
            type: array
          confidence_without_clarification:
            type: number
      evidence_anchors:
        type: array
        description: Evidence supporting the ambiguity assessment
      confidence:
        type: number
        minimum: 0
        maximum: 1
        description: Confidence that clarification is needed
edge_types:
  requires:
    description: 'Hard dependency: the ''from'' capability MUST be satisfied before ''to'' can execute'
    semantics: Validator MUST reject workflows that violate this ordering
    transitive: false
  soft_requires:
    description: 'Soft dependency: the ''from'' capability SHOULD be satisfied when available'
    semantics: Validator SHOULD warn if not satisfied, but workflow is still valid
    transitive: false
  enables:
    description: The 'from' capability unlocks or makes possible the 'to' capability
    semantics: Represents capability flow and composition patterns
    transitive: false
  precedes:
    description: 'Temporal ordering: ''from'' must complete before ''to'' begins in any workflow'
    semantics: Enforces execution order even when no data dependency exists
    transitive: true
  conflicts_with:
    description: 'Mutual exclusivity: ''from'' and ''to'' cannot both execute in the same workflow'
    semantics: Validator MUST reject workflows containing both capabilities
    transitive: false
    symmetric: true
  alternative_to:
    description: 'Substitutability: ''from'' can replace ''to'' with compatible semantics'
    semantics: Used for capability selection when multiple options exist
    transitive: false
    symmetric: true
  specializes:
    description: 'Inheritance: ''from'' is a more specific variant of ''to'''
    semantics: The specialized capability inherits contracts from the general capability
    transitive: true
edges:
- from: retrieve
  to: detect
  type: enables
- from: search
  to: detect
  type: enables
- from: observe
  to: state
  type: enables
- from: detect
  to: classify
  type: enables
- from: classify
  to: compare
  type: enables
- from: measure
  to: predict
  type: enables
- from: compare
  to: plan
  type: enables
- from: plan
  to: execute
  type: enables
- from: plan
  to: mutate
  type: enables
- from: checkpoint
  to: mutate
  type: requires
- from: checkpoint
  to: send
  type: requires
- from: checkpoint
  to: rollback
  type: requires
- from: verify
  to: rollback
  type: enables
- from: execute
  to: audit
  type: enables
- from: mutate
  to: audit
  type: enables
- from: state
  to: transition
  type: enables
- from: transition
  to: simulate
  type: enables
- from: ground
  to: verify
  type: enables
- from: decompose
  to: delegate
  type: enables
- from: delegate
  to: synchronize
  type: enables
- from: integrate
  to: state
  type: enables
- from: persist
  to: recall
  type: enables
- from: observe
  to: ground
  type: soft_requires
- from: detect
  to: ground
  type: soft_requires
- from: plan
  to: critique
  type: soft_requires
- from: execute
  to: audit
  type: soft_requires
- from: mutate
  to: persist
  type: soft_requires
- from: predict
  to: ground
  type: soft_requires
- from: attribute
  to: ground
  type: soft_requires
  rationale: Causal claims should be grounded in evidence
- from: constrain
  to: audit
  type: soft_requires
  rationale: Constraint violations should be audited
- from: explain
  to: ground
  type: soft_requires
  rationale: Explanations should be grounded in evidence
- from: generate
  to: verify
  type: soft_requires
  rationale: Generated artifacts should be verified
- from: critique
  to: inquire
  type: enables
- from: inquire
  to: receive
  type: soft_requires
- from: detect
  to: attribute
  type: enables
  rationale: Detection finds effects for causal attribution
- from: observe
  to: attribute
  type: enables
  rationale: Observations provide data for causal analysis
- from: attribute
  to: explain
  type: enables
  rationale: Causal attribution enables explanation
- from: attribute
  to: plan
  type: enables
  rationale: Understanding causes informs planning
- from: plan
  to: constrain
  type: enables
  rationale: Plans generate actions needing constraint check
- from: constrain
  to: checkpoint
  type: enables
  rationale: After constraint approval, create checkpoint
- from: search
  to: discover
  type: enables
  rationale: Search results provide data for discovery
- from: retrieve
  to: discover
  type: enables
  rationale: Retrieved data can be explored for patterns
- from: observe
  to: discover
  type: enables
  rationale: Observations provide input for pattern discovery
- from: discover
  to: classify
  type: enables
  rationale: Discovered patterns may need classification
- from: discover
  to: attribute
  type: enables
  rationale: Discovered relationships may need causal analysis
- from: discover
  to: plan
  type: enables
  rationale: Discoveries may trigger action planning
- from: critique
  to: explain
  type: enables
  rationale: Critique findings can be explained
- from: predict
  to: explain
  type: enables
  rationale: Predictions need explanation of reasoning
- from: compare
  to: explain
  type: enables
  rationale: Comparison results need explanation
- from: classify
  to: explain
  type: enables
  rationale: Classifications can be explained
- from: explain
  to: audit
  type: enables
  rationale: Explanations become part of audit trail
- from: plan
  to: generate
  type: enables
  rationale: Plans specify what to generate
- from: compare
  to: generate
  type: enables
  rationale: Comparison winner informs generation
- from: discover
  to: generate
  type: enables
  rationale: Discovered gaps may trigger generation
- from: generate
  to: mutate
  type: enables
  rationale: Generated content may be written/persisted
- from: checkpoint
  to: mutate
  type: precedes
  rationale: State must be saved before any mutation
- from: checkpoint
  to: send
  type: precedes
  rationale: State must be saved before external communication
- from: plan
  to: execute
  type: precedes
  rationale: Planning must complete before execution
- from: plan
  to: mutate
  type: precedes
  rationale: Planning must complete before state mutation
- from: observe
  to: detect
  type: precedes
  rationale: Observation must precede pattern detection
- from: detect
  to: classify
  type: precedes
  rationale: Detection must precede classification
- from: retrieve
  to: transform
  type: precedes
  rationale: Data must be retrieved before transformation
- from: search
  to: compare
  type: precedes
  rationale: Search results needed before comparison
- from: state
  to: simulate
  type: precedes
  rationale: Current state needed before simulation
- from: verify
  to: audit
  type: precedes
  rationale: Verification results must be audited
- from: mutate
  to: verify
  type: precedes
  rationale: Mutation must complete before verification
- from: execute
  to: verify
  type: precedes
  rationale: Execution must complete before verification
- from: send
  to: verify
  type: precedes
  rationale: External communication must complete before verification
- from: detect
  to: attribute
  type: precedes
  rationale: Must detect effects before attributing causes
- from: constrain
  to: execute
  type: precedes
  rationale: Constraints must be checked before execution
- from: constrain
  to: mutate
  type: precedes
  rationale: Constraints must be checked before mutation
- from: constrain
  to: send
  type: precedes
  rationale: Constraints must be checked before external comms
- from: constrain
  to: generate
  type: precedes
  rationale: Constraints must be checked before generation
- from: rollback
  to: persist
  type: conflicts_with
  rationale: Cannot persist while rolling back state
- from: persist
  to: rollback
  type: conflicts_with
  rationale: Cannot persist while rolling back state
- from: mutate
  to: rollback
  type: conflicts_with
  rationale: Cannot mutate during rollback operation
- from: rollback
  to: mutate
  type: conflicts_with
  rationale: Cannot mutate during rollback operation
- from: search
  to: retrieve
  type: alternative_to
  rationale: Both acquire data, search by criteria vs retrieve by reference
- from: retrieve
  to: search
  type: alternative_to
  rationale: Both acquire data, search by criteria vs retrieve by reference
- from: measure
  to: predict
  type: alternative_to
  rationale: Both quantify, measure current vs predict future
- from: predict
  to: measure
  type: alternative_to
  rationale: Both quantify, measure current vs predict future
- from: persist
  to: checkpoint
  type: alternative_to
  rationale: Both store state, checkpoint for recovery vs persist for durability
- from: checkpoint
  to: persist
  type: alternative_to
  rationale: Both store state, checkpoint for recovery vs persist for durability
- from: verify
  to: constrain
  type: alternative_to
  rationale: Both check conditions; verify post-hoc, constrain pre-execution
- from: constrain
  to: verify
  type: alternative_to
  rationale: Both check conditions; verify post-hoc, constrain pre-execution
- from: detect
  to: discover
  type: alternative_to
  rationale: Both find patterns; detect for known patterns, discover for unknown
- from: discover
  to: detect
  type: alternative_to
  rationale: Both find patterns; detect for known patterns, discover for unknown
- from: transform
  to: generate
  type: alternative_to
  rationale: Both create output; transform converts existing, generate creates new
- from: generate
  to: transform
  type: alternative_to
  rationale: Both create output; transform converts existing, generate creates new
- from: detect
  to: observe
  type: specializes
  rationale: Detection is specialized observation for patterns
- from: classify
  to: detect
  type: specializes
  rationale: Classification is specialized detection with categories
- from: predict
  to: measure
  type: specializes
  rationale: Prediction is specialized measurement over time
- from: critique
  to: verify
  type: specializes
  rationale: Critique is specialized verification for quality
- from: rollback
  to: mutate
  type: specializes
  rationale: Rollback is specialized mutation to previous state
- from: delegate
  to: invoke
  type: specializes
  rationale: Delegation is specialized invocation to agents