cleveragents-core/features/subplan_spawn_service.feature

@phase1 @subplan @spawn
Feature: Subplan Spawn Service
  As a system orchestrating hierarchical plans
  I want to spawn child plans from decision entries
  And validate spawn requests before execution
  So that parent plans can safely decompose work into coordinated child plans

  # --- Successful spawn ---

  @spawn_success
  Scenario: Successfully spawn child plan from decision entry
    Given a parent plan with a subplan spawn decision
    And a subplan config with sequential execution mode
    When the subplan service spawns child plans
    Then 1 child plan status should be created
    And the spawn metadata should contain the parent plan id
    And the spawn metadata should contain the root plan id
    And the spawn metadata should contain the execution mode

  # --- Multiple entries ---

  @spawn_multiple
  Scenario: Spawn from multiple decision entries
    Given a parent plan with 3 subplan spawn decisions
    And a subplan config with parallel execution mode and max_parallel 5
    When the subplan service spawns child plans
    Then 3 child plan statuses should be created
    And each status should have a unique subplan id
    And the spawn result total_spawned should be 3

  # --- Validation: resource scopes ---

  @validation @resource_scope
  Scenario: Validate spawn with missing resource scope
    Given a parent plan with a spawn entry targeting resource "res-missing"
    And available resources are "res-a" and "res-b"
    And a subplan config with sequential execution mode
    When the subplan service validates the spawn request
    Then the validation result should be invalid
    And the validation errors should mention unresolved resource

  # --- Validation: merge strategy ---

  @validation @merge_strategy
  Scenario: Validate spawn with undefined merge strategy
    Given a parent plan with a valid spawn entry
    And a subplan config with no merge strategy
    When the subplan service validates the spawn request
    Then the validation result should be invalid
    And the validation errors should mention merge strategy

  # --- Validation: max_parallel ---

  @validation @max_parallel
  Scenario: Validate spawn exceeding max_parallel bound
    Given a parent plan with 5 subplan spawn decisions
    And a subplan config with parallel execution mode and max_parallel 3
    When the subplan service validates the spawn request
    Then the validation result should be invalid
    And the validation errors should mention max_parallel

  # --- Metadata persistence ---

  @metadata
  Scenario: Spawn metadata persisted for status output
    Given a parent plan that is a subplan with root plan id "01HGZ6FE0AQDYTR4BXVQZ6RF00"
    And a subplan config with sequential execution mode
    And a valid spawn decision
    When the subplan service spawns child plans
    Then the spawn metadata root_plan_id should be "01HGZ6FE0AQDYTR4BXVQZ6RF00"
    And the spawn metadata execution_mode should be "sequential"

  # --- Decision type validation ---

  @validation @decision_type
  Scenario: Validate spawn with wrong decision type
    Given a parent plan with a non-spawn decision type
    And a subplan config with sequential execution mode
    When the subplan service validates the spawn request
    Then the validation result should be invalid
    And the validation errors should mention decision type

  # --- Get spawn decisions ---

  @spawn_decisions
  Scenario: Get spawn decisions from decision service
    Given a decision service with spawn decisions for plan "01HGZ6FE0AQDYTR4BXVQZ6PN00"
    When the subplan service retrieves spawn decisions
    Then the returned decisions should only contain spawn types

  # --- Build spawn entries ---

  @build_entries
  Scenario: Build spawn entries from decisions
    Given a list of spawn decisions with resource refs
    When the subplan service builds spawn entries
    Then each entry should have action_name and target_resources

  # --- Service construction ---

  @construction
  Scenario: SubplanService rejects None decision_service
    When the subplan service is constructed with None decision_service
    Then a ValueError should be raised for subplan service

  # --- Spawn rejects None inputs ---

  @validation @null_guard
  Scenario: Spawn rejects None parent_plan
    Given a valid subplan service
    When spawn is called with None parent_plan
    Then a spawn ValueError should be raised with message "parent_plan must not be None"

  @validation @null_guard
  Scenario: Spawn rejects empty spawn_entries
    Given a valid subplan service
    And a parent plan with identity
    When spawn is called with empty spawn_entries
    Then a spawn ValueError should be raised with message "spawn_entries must not be empty"

  # --- Parallel spawn decision ---

  @spawn_parallel
  Scenario: Spawn from parallel spawn decision type
    Given a parent plan with a subplan_parallel_spawn decision
    And a subplan config with parallel execution mode and max_parallel 5
    When the subplan service spawns child plans
    Then 1 child plan status should be created
    And the spawn metadata execution_mode should be "parallel"