feat(estimation): add estimation actor YAML template and role-aware registration validation #650

New issue

Closed

opened 2026-03-09 20:15:39 +00:00 by freemo · 0 comments

freemo commented

2026-03-09 20:15:39 +00:00

Owner

Metadata

Commit Message: feat(estimation): add estimation actor YAML template and role-aware registration validation
Branch: feature/m6-estimation-actor-yaml

Background and Context

There are 7 actor YAML examples in examples/actors/ (simple_llm.yaml, graph_workflow.yaml, etc.) but none is an estimation actor. The action example at examples/actions/estimation-actor.yaml references local/estimator, yet that actor definition does not exist anywhere in the repository — it is a phantom reference. The specification (line 155) defines four specialized actor roles (strategy, execution, estimation, invariant reconciliation), and the actor definition schema includes context_view (line 20197) and config.response_format (line 20222) — both critical for an estimation actor that must produce structured JSON output.

Furthermore, actor registration (agents actor add) currently performs no validation that an actor's context_view, response_format, or capability profile is compatible with the role it will serve. The preflight guardrail (plan_preflight_guardrail.py) checks only name-existence, not role compatibility.

Expected Behavior

A complete, valid estimation actor YAML template exists in examples/actors/, and the actor registration pipeline warns when an actor assigned to an estimation role lacks required configuration (e.g., response_format).

Acceptance Criteria

examples/actors/estimator.yaml exists with: context_view: strategist, response_format wired to the EstimationReport JSON Schema, appropriate system_prompt for cost/risk/duration estimation, and skill references.
The YAML template loads, compiles, and passes schema validation via existing tooling.
A role_hint field (or convention-based validation) in the actor config schema allows the compiler to warn when an actor assigned as estimation_actor lacks response_format or has incompatible context_view.
The plan_preflight_guardrail.py emits a warning (not error) when an estimation actor is configured without response_format.
Unit tests validate the new YAML template loads and compiles.

Subtasks

Create examples/actors/estimator.yaml with full estimation actor configuration
Add role_hint field to actor config schema (or implement convention-based naming validation)
Add preflight warning for estimation actors missing response_format
Tests (Behave): Add scenario for estimation actor YAML loading and compilation
Tests (Robot): Add integration test for role-aware validation warning
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

## Metadata - **Commit Message**: `feat(estimation): add estimation actor YAML template and role-aware registration validation` - **Branch**: `feature/m6-estimation-actor-yaml` ## Background and Context There are 7 actor YAML examples in `examples/actors/` (`simple_llm.yaml`, `graph_workflow.yaml`, etc.) but none is an estimation actor. The action example at `examples/actions/estimation-actor.yaml` references `local/estimator`, yet that actor definition does not exist anywhere in the repository — it is a phantom reference. The specification (line 155) defines four specialized actor roles (strategy, execution, estimation, invariant reconciliation), and the actor definition schema includes `context_view` (line 20197) and `config.response_format` (line 20222) — both critical for an estimation actor that must produce structured JSON output. Furthermore, actor registration (`agents actor add`) currently performs no validation that an actor's `context_view`, `response_format`, or capability profile is compatible with the role it will serve. The preflight guardrail (`plan_preflight_guardrail.py`) checks only name-existence, not role compatibility. ## Expected Behavior A complete, valid estimation actor YAML template exists in `examples/actors/`, and the actor registration pipeline warns when an actor assigned to an estimation role lacks required configuration (e.g., `response_format`). ## Acceptance Criteria 1. `examples/actors/estimator.yaml` exists with: `context_view: strategist`, `response_format` wired to the EstimationReport JSON Schema, appropriate `system_prompt` for cost/risk/duration estimation, and skill references. 2. The YAML template loads, compiles, and passes schema validation via existing tooling. 3. A `role_hint` field (or convention-based validation) in the actor config schema allows the compiler to warn when an actor assigned as `estimation_actor` lacks `response_format` or has incompatible `context_view`. 4. The `plan_preflight_guardrail.py` emits a warning (not error) when an estimation actor is configured without `response_format`. 5. Unit tests validate the new YAML template loads and compiles. ## Subtasks - [ ] Create `examples/actors/estimator.yaml` with full estimation actor configuration - [ ] Add `role_hint` field to actor config schema (or implement convention-based naming validation) - [ ] Add preflight warning for estimation actors missing `response_format` - [ ] Tests (Behave): Add scenario for estimation actor YAML loading and compilation - [ ] Tests (Robot): Add integration test for role-aware validation warning - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.

Rows
Columns