60 lines
5.6 KiB
Markdown
60 lines
5.6 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Handoff protocol data contracts
|
|
The system SHALL define `Observation`, `VerificationVerdict`, `ReflectionOutcome`, and `ReflectionAction` as plain dataclasses with `to_dict()`/`from_dict()` methods, forming the stable, spec'd contract passed between the Observer, Verifier, and Reflector roles, independent of any single role's internal implementation.
|
|
|
|
#### Scenario: Handoff dataclasses round-trip through serialization
|
|
- **WHEN** an `Observation`, `VerificationVerdict`, or `ReflectionOutcome` instance is serialized via `to_dict()` and then reconstructed via `from_dict()`
|
|
- **THEN** the reconstructed instance is equal to the original instance
|
|
|
|
### Requirement: Observer produces an Observation from available device state
|
|
The system SHALL provide an Observer role that produces an `Observation` summarizing current device state, using `SemanticScene` and `WorldState` when available and falling back to the raw `Scene`/`PlannedStep`/`StepResult` when either or both are absent.
|
|
|
|
#### Scenario: Observation succeeds with SemanticScene and WorldState present
|
|
- **WHEN** `Observer.observe(...)` is called and both `SemanticScene` and `WorldState` are available
|
|
- **THEN** it returns an `Observation` incorporating both as context
|
|
|
|
#### Scenario: Observation degrades gracefully when semantic state is absent
|
|
- **WHEN** `Observer.observe(...)` is called and `SemanticScene` and/or `WorldState` is `None`
|
|
- **THEN** it returns an `Observation` built from the raw `Scene`/`PlannedStep`/`StepResult` instead of raising an exception
|
|
|
|
### Requirement: Verifier checks whether an executed step achieved its intended effect
|
|
The system SHALL provide a Verifier role that, after a `PlannedStep` has already been executed by the existing `Executor`, compares a pre-step and post-step `Observation` against the step's stated intent and produces a `VerificationVerdict` indicating whether the intended effect was actually achieved, distinct from and running after the Executor's own low-level tool-call retry.
|
|
|
|
#### Scenario: Verifier confirms an achieved effect
|
|
- **WHEN** `Verifier.verify(...)` is called with a pre-step `Observation`, a post-step `Observation`, the executed `PlannedStep`, and its `StepResult`, and the post-step `Observation` reflects the step's stated intent
|
|
- **THEN** it returns a `VerificationVerdict` marking the step as achieved
|
|
|
|
#### Scenario: Verifier flags a mechanically-successful but semantically-failed step
|
|
- **WHEN** the `StepResult` reports mechanical success but the post-step `Observation` does not reflect the step's stated intent
|
|
- **THEN** `Verifier.verify(...)` returns a `VerificationVerdict` marking the step as not achieved
|
|
|
|
### Requirement: Reflector proposes bounded recovery, never a blind re-issue
|
|
The system SHALL invoke a Reflector role only when the Verifier produces a not-achieved `VerificationVerdict`, and the Reflector SHALL analyze the `Observation`/`PlannedStep`/`StepResult`/verdict to produce a `ReflectionOutcome` carrying either a bounded, distinct recovery `ReflectionAction` or a replan request back to the Planner, never an outcome that simply re-issues the identical failed step.
|
|
|
|
#### Scenario: Reflector proposes a distinct recovery action
|
|
- **WHEN** `Reflector.reflect(...)` is invoked following a not-achieved `VerificationVerdict` and a distinct corrective action is identifiable
|
|
- **THEN** it returns a `ReflectionOutcome` carrying a `ReflectionAction` that differs from the originally failed `PlannedStep`
|
|
|
|
#### Scenario: Reflector requests a replan when no bounded recovery action applies
|
|
- **WHEN** `Reflector.reflect(...)` is invoked and no bounded corrective action is identifiable from the available `Observation`/`PlannedStep`/`StepResult`/verdict
|
|
- **THEN** it returns a `ReflectionOutcome` carrying a replan request rather than re-issuing the failed step
|
|
|
|
### Requirement: Reflection-driven recovery is bounded by an explicit ceiling
|
|
The system SHALL enforce a configurable maximum number of Reflector-triggered recovery attempts per task, tracked independently of and in addition to the Executor's own `max_retries`, so that a persistently-failing step cannot loop indefinitely between the Verifier and Reflector.
|
|
|
|
#### Scenario: Reflection loop stops once the ceiling is reached
|
|
- **WHEN** a task's Verifier-Reflector loop reaches the configured maximum reflection-recovery attempts without a step being verified as achieved
|
|
- **THEN** the `CollaborativeTaskRunner` stops attempting further reflection-driven recovery for that task and surfaces the failure instead of continuing the loop
|
|
|
|
### Requirement: Multi-agent collaboration composes existing Planner/Executor without modifying them
|
|
The system SHALL provide a `CollaborativeTaskRunner` that composes the existing `Planner`, `Executor`, and `TaskRunner` (`agent-runtime`) by import, without modifying `runtime/planner.py`, `runtime/executor.py`, or `runtime/task.py`, and SHALL default to disabled so that applying this capability does not alter any existing task's behavior, latency, or cost unless explicitly enabled.
|
|
|
|
#### Scenario: Collaboration disabled by default leaves existing task behavior unchanged
|
|
- **WHEN** a task is run without explicitly enabling multi-agent collaboration
|
|
- **THEN** it executes exactly as `runtime/task.py`'s existing `TaskRunner.run()` today, with no Observer/Verifier/Reflector invoked
|
|
|
|
#### Scenario: Enabling collaboration does not require changes to Planner or Executor
|
|
- **WHEN** a task is run with multi-agent collaboration explicitly enabled via `CollaborativeTaskRunner`
|
|
- **THEN** the existing `Planner.plan()` and `Executor.execute()` are invoked unchanged, with the Observer/Verifier/Reflector roles composed around them
|