test(tool): add robot tool model smoke tests

docs/reference/tool_model.md

@@ -0,0 +1,91 @@
+# Tool & Validation Domain Models
+
+The `Tool` and `Validation` domain models are defined in
+`src/cleveragents/domain/models/core/tool.py`.
+
+## Overview
+
+| Model        | Purpose                                    |
+|--------------|--------------------------------------------|
+| `Tool`       | Atomic unit of execution — namespaced, independently registered callable operation |
+| `Validation` | Extends `Tool` with pass/fail semantics — always read-only, never writes, never checkpointable |
+
+### Key classes
+
+- **`ToolSource`** — enum: `mcp`, `agent_skill`, `builtin`, `custom`, `wrapped`
+- **`ToolType`** — enum: `tool`, `validation`
+- **`ValidationMode`** — enum: `required`, `informational`
+- **`ToolCapability`** — capability metadata (read_only, writes, checkpointable, side_effects, etc.)
+- **`ResourceSlot`** — typed resource binding declaration
+- **`ToolLifecycle`** — optional lifecycle hooks (discover, activate, deactivate)
+
+### Factory methods
+
+- `Tool.from_config(config)` — create a Tool from a YAML configuration dict
+- `Validation.from_config(config)` — create a Validation from a YAML configuration dict
+
+### Serialization
+
+- `tool.as_cli_dict()` — stable-ordered dictionary for CLI rendering
+
+## Testing
+
+### Behave BDD tests (unit tests)
+
+The primary test suite lives in `features/tool_model.feature` with step
+definitions in `features/steps/tool_model_steps.py`.
+
+Run with nox:
+
+```bash
+nox -s unit_tests -- features/tool_model.feature
+```
+
+The Behave suite covers:
+
+- Tool/Validation model creation and field validation
+- Source-conditional field requirements
+- Capability constraint enforcement
+- ResourceSlot binding validation
+- `from_config()` loading (including YAML example files)
+- `as_cli_dict()` output stability
+- Enum value completeness
+
+### Robot Framework smoke tests
+
+The Robot smoke suite in `robot/tool_model.robot` provides integration-level
+smoke tests that verify the same model creation and YAML loader outputs
+through a subprocess helper (`robot/helper_tool_model.py`).
+
+Run with nox:
+
+```bash
+nox -s integration_tests -- robot/tool_model.robot
+```
+
+Or directly with Robot Framework:
+
+```bash
+robot --outputdir build/reports/robot robot/tool_model.robot
+```
+
+The Robot suite covers:
+
+| Test Case | What it verifies |
+|-----------|-----------------|
+| Create Minimal Tool Model | Builtin tool creation, identity fields |
+| Create Validation Model With Forced Constraints | Validation read_only/writes/checkpointable forcing |
+| Load Custom Tool From YAML Config | `Tool.from_config()` with `examples/tools/custom-tool.yaml` |
+| Load MCP Tool From YAML Config | `Tool.from_config()` with `examples/tools/mcp-tool.yaml` |
+| Load Wrapped Validation From YAML Config | `Validation.from_config()` with `examples/validations/wrapped-validation.yaml` |
+| Load Required Validation From YAML Config | `Validation.from_config()` with `examples/validations/required-validation.yaml` |
+| Validate Forced Constraints On Writable Capability | Validation forces read_only even with writable capability |
+| Reject Invalid Tool Configurations | Invalid name, missing code, conflicting capabilities rejected |
+
+### ASV benchmarks
+
+Performance benchmarks live in `benchmarks/tool_model_bench.py`:
+
+```bash
+nox -s benchmark
+```

features/steps/tool_model_steps.py

@@ -1,7 +1,9 @@
 """Step definitions for Tool and Validation domain model tests."""
 
+from pathlib import Path
 from typing import Any
 
+import yaml
 from behave import then, when
 from behave.runner import Context
 from pydantic import ValidationError
@@ -925,3 +927,30 @@ def step_create_validation_with_writes(context: Context) -> None:
         ),
     )
     context.tool_model_error = None
+
+
+# ---------------------------------------------------------------------------
+# YAML file loading (mirrors Robot smoke suite)
+# ---------------------------------------------------------------------------
+
+_PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
+@when('I load a tool from YAML file "{rel_path}"')
+def step_load_tool_from_yaml_file(context: Context, rel_path: str) -> None:
+    """Load a Tool from an example YAML config file."""
+    yaml_path = _PROJECT_ROOT / rel_path
+    with yaml_path.open() as f:
+        config: dict[str, Any] = yaml.safe_load(f)
+    context.tool_model = Tool.from_config(config)
+    context.tool_model_error = None
+
+
+@when('I load a validation from YAML file "{rel_path}"')
+def step_load_validation_from_yaml_file(context: Context, rel_path: str) -> None:
+    """Load a Validation from an example YAML config file."""
+    yaml_path = _PROJECT_ROOT / rel_path
+    with yaml_path.open() as f:
+        config: dict[str, Any] = yaml.safe_load(f)
+    context.tool_model = Validation.from_config(config)
+    context.tool_model_error = None

features/tool_model.feature

@@ -325,3 +325,39 @@ Feature: Tool and Validation Domain Models
     Then the tool validation capability should be read only
     And the tool validation capability should not have writes
     And the tool validation capability should not be checkpointable
+
+  # ---- YAML loader output alignment (mirrors Robot smoke suite) ----
+
+  Scenario: Load custom tool from example YAML config
+    When I load a tool from YAML file "examples/tools/custom-tool.yaml"
+    Then the tool model should be created
+    And the tool model name should be "local/line-counter"
+    And the tool model source should be "custom"
+    And the tool model should have 1 resource slot
+    And the tool model timeout should be 60
+
+  Scenario: Load MCP tool from example YAML config
+    When I load a tool from YAML file "examples/tools/mcp-tool.yaml"
+    Then the tool model should be created
+    And the tool model name should be "devops/docker-build"
+    And the tool model source should be "mcp"
+    And the tool model timeout should be 600
+
+  Scenario: Load wrapped validation from example YAML config
+    When I load a validation from YAML file "examples/validations/wrapped-validation.yaml"
+    Then the tool model should be created
+    And the tool model type should be "validation"
+    And the tool model source should be "wrapped"
+    And the tool validation wraps should be "devops/run-linter"
+    And the tool validation mode should be "required"
+    And the tool validation capability should be read only
+    And the tool validation capability should not have writes
+
+  Scenario: Load required validation from example YAML config
+    When I load a validation from YAML file "examples/validations/required-validation.yaml"
+    Then the tool model should be created
+    And the tool model type should be "validation"
+    And the tool model source should be "custom"
+    And the tool validation mode should be "required"
+    And the tool validation capability should be read only
+    And the tool validation capability should not have writes

implementation_plan.md

@@ -2585,24 +2585,24 @@ No standalone Q0-Advanced commits planned. Advanced QA enhancements are bundled
   - [X] Forgejo PR [Jeff]: Open PR from `feature/m3-tool-domain` to `master` with description "Add tool + validation domain models, schema loaders, and tests.".
   - [X] Quality [Jeff]: Verify coverage >=97% via `nox -s coverage_report`. Coverage is 97% overall (tool.py 99% coverage).
 
-- [ ] **COMMIT (Owner: Brent | Group: C1.tool.domain.tests | Branch: feature/m3-tool-domain-robot | Planned: Day 10 | Expected: Day 14) - Commit message: "test(tool): add robot tool model smoke tests"**
-  - [ ] Meta [Brent]: Only mark this commit complete after every subtask is done and `git commit -m "test(tool): add robot tool model smoke tests"` has executed.
-  - [ ] Git [Brent]: `git checkout master`
-  - [ ] Git [Brent]: `git pull origin master`
-  - [ ] Git [Brent]: `git checkout -b feature/m3-tool-domain-robot`
-  - [ ] Git [Brent]: `git fetch origin && git merge origin/master` (run before final tests and before commit)
-  - [ ] Code [Brent]: Add `robot/tool_model.robot` smoke tests for Tool/Validation model creation and YAML loader outputs.
-  - [ ] Docs [Brent]: Update `docs/reference/tool_model.md` to mention the Robot smoke suite and how to run it.
-  - [ ] Tests (Behave) [Brent]: Add a scenario in `features/tool_model.feature` that mirrors the Robot smoke expectations for YAML loader outputs.
-  - [ ] Tests (Robot) [Brent]: Add Robot suite that validates tool model creation and validation constraints.
-  - [ ] Tests (ASV) [Brent]: Confirm `benchmarks/tool_model_bench.py` still passes after the new Robot suite is added.
-  - [ ] Quality [Brent]: Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes.
-  - [ ] Git [Brent]: `git add .`
-  - [ ] Git [Brent]: `git commit -m "test(tool): add robot tool model smoke tests"`
+- [X] **COMMIT (Owner: Brent | Group: C1.tool.domain.tests | Branch: feature/m3-tool-domain-robot | Planned: Day 10 | Expected: Day 14) - Commit message: "test(tool): add robot tool model smoke tests"**
+  - [X] Meta [Brent]: Only mark this commit complete after every subtask is done and `git commit -m "test(tool): add robot tool model smoke tests"` has executed.
+  - [X] Git [Brent]: `git checkout master`
+  - [X] Git [Brent]: `git pull origin master`
+  - [X] Git [Brent]: `git checkout -b feature/m3-tool-domain-robot`
+  - [X] Git [Brent]: `git fetch origin && git merge origin/master` (run before final tests and before commit)
+  - [X] Code [Brent]: Add `robot/tool_model.robot` smoke tests for Tool/Validation model creation and YAML loader outputs.
+  - [X] Docs [Brent]: Update `docs/reference/tool_model.md` to mention the Robot smoke suite and how to run it.
+  - [X] Tests (Behave) [Brent]: Add a scenario in `features/tool_model.feature` that mirrors the Robot smoke expectations for YAML loader outputs.
+  - [X] Tests (Robot) [Brent]: Add Robot suite that validates tool model creation and validation constraints.
+  - [X] Tests (ASV) [Brent]: Confirm `benchmarks/tool_model_bench.py` still passes after the new Robot suite is added.
+  - [X] Quality [Brent]: Run `nox` (all default sessions, including benchmark), fix any errors if needed ensuring nox passes.
+  - [X] Git [Brent]: `git add .`
+  - [X] Git [Brent]: `git commit -m "test(tool): add robot tool model smoke tests"`
   - [ ] Forgejo PR [Brent]: Open PR from `feature/m3-tool-domain-robot` to `master` with description "Add Robot smoke tests for tool/validation domain models with docs and Behave alignment.".
   - [ ] Git [Brent]: `git checkout master`
   - [ ] Git [Brent]: `git branch -d feature/m3-tool-domain-robot`
-  - [ ] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
+  - [X] Quality [Brent]: Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.
 
 - [ ] **COMMIT (Owner: Jeff | Group: C1.tool.registry | Branch: feature/m3-tool-registry | Planned: Day 14 | Expected: Day 20) - Commit message: "feat(tool): add tool registry persistence"**
   - [ ] Git [Jeff]: `git checkout master`

robot/helper_tool_model.py

@@ -0,0 +1,201 @@
+"""Robot Framework helper for Tool/Validation domain model smoke tests.
+
+Provides a CLI-style interface for Robot to invoke model creation and
+YAML config loading.  Exit code 0 = success, 1 = failure.
+
+Usage:
+    python robot/helper_tool_model.py create-tool
+    python robot/helper_tool_model.py create-validation
+    python robot/helper_tool_model.py load-tool-yaml <yaml_file>
+    python robot/helper_tool_model.py load-validation-yaml <yaml_file>
+    python robot/helper_tool_model.py validate-constraints
+    python robot/helper_tool_model.py validate-invalid-tool
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+# Ensure the src directory is on the import path.
+_SRC = str(Path(__file__).resolve().parents[1] / "src")
+if _SRC not in sys.path:
+    sys.path.insert(0, _SRC)
+
+from cleveragents.domain.models.core.tool import (  # noqa: E402
+    Tool,
+    ToolCapability,
+    ToolSource,
+    ToolType,
+    Validation,
+    ValidationMode,
+)
+
+
+def _cmd_create_tool() -> int:
+    """Create a minimal Tool and verify fields."""
+    tool = Tool(
+        name="smoke/robot-tool",
+        description="Robot smoke test tool",
+        source=ToolSource.BUILTIN,
+    )
+    assert tool.name == "smoke/robot-tool"
+    assert tool.namespace == "smoke"
+    assert tool.short_name == "robot-tool"
+    assert tool.source == ToolSource.BUILTIN
+    assert tool.tool_type == ToolType.TOOL
+    assert tool.timeout == 300
+    print(f"tool-model-ok: {tool.name}")
+    return 0
+
+
+def _cmd_create_validation() -> int:
+    """Create a Validation and verify forced constraints."""
+    val = Validation(
+        name="smoke/robot-val",
+        description="Robot smoke validation",
+        source=ToolSource.BUILTIN,
+    )
+    assert val.tool_type == ToolType.VALIDATION
+    assert val.capability.read_only is True
+    assert val.capability.writes is False
+    assert val.capability.checkpointable is False
+    assert val.mode == ValidationMode.REQUIRED
+    print(f"validation-model-ok: {val.name}")
+    return 0
+
+
+def _cmd_load_tool_yaml(yaml_path: str) -> int:
+    """Load a Tool from a YAML config file and verify."""
+    path = Path(yaml_path)
+    if not path.exists():
+        print(f"tool-yaml-fail: file not found: {yaml_path}")
+        return 1
+    with path.open() as f:
+        config: dict[str, Any] = yaml.safe_load(f)
+    tool = Tool.from_config(config)
+    cli_dict = tool.as_cli_dict()
+    assert "name" in cli_dict
+    assert "source" in cli_dict
+    assert "capability" in cli_dict
+    print(f"tool-yaml-ok: {tool.name} source={tool.source.value}")
+    return 0
+
+
+def _cmd_load_validation_yaml(yaml_path: str) -> int:
+    """Load a Validation from a YAML config file and verify."""
+    path = Path(yaml_path)
+    if not path.exists():
+        print(f"validation-yaml-fail: file not found: {yaml_path}")
+        return 1
+    with path.open() as f:
+        config: dict[str, Any] = yaml.safe_load(f)
+    val = Validation.from_config(config)
+    assert val.tool_type == ToolType.VALIDATION
+    assert val.capability.read_only is True
+    assert val.capability.writes is False
+    cli_dict = val.as_cli_dict()
+    assert "mode" in cli_dict
+    print(f"validation-yaml-ok: {val.name} mode={val.mode.value}")
+    return 0
+
+
+def _cmd_validate_constraints() -> int:
+    """Verify that Validation forces read_only and blocks writes."""
+    val = Validation(
+        name="smoke/constraint-check",
+        description="Constraint test",
+        source=ToolSource.BUILTIN,
+        capability=ToolCapability(writes=True, checkpointable=True),
+    )
+    # Validation must force these even when given writable capability
+    assert val.capability.read_only is True, "Validation must force read_only=True"
+    assert val.capability.writes is False, "Validation must force writes=False"
+    assert val.capability.checkpointable is False, (
+        "Validation must force checkpointable=False"
+    )
+    print("validate-constraints-ok")
+    return 0
+
+
+def _cmd_validate_invalid_tool() -> int:
+    """Verify that invalid tool config is rejected."""
+    from pydantic import ValidationError
+
+    # Test: invalid name pattern
+    try:
+        Tool(
+            name="no-namespace",
+            description="Bad name",
+            source=ToolSource.BUILTIN,
+        )
+        print("validate-invalid-unexpected-success: bad name accepted")
+        return 1
+    except ValidationError:
+        pass
+
+    # Test: custom source without code
+    try:
+        Tool(
+            name="local/test",
+            description="Missing code",
+            source=ToolSource.CUSTOM,
+        )
+        print("validate-invalid-unexpected-success: missing code accepted")
+        return 1
+    except ValidationError:
+        pass
+
+    # Test: read_only with writes
+    try:
+        ToolCapability(read_only=True, writes=True)
+        print("validate-invalid-unexpected-success: read_only+writes accepted")
+        return 1
+    except ValidationError:
+        pass
+
+    print("validate-invalid-ok")
+    return 0
+
+
+def main() -> int:
+    """Entry point called by Robot Framework ``Run Process``."""
+    if len(sys.argv) < 2:
+        print(
+            "Usage: helper_tool_model.py "
+            "<create-tool|create-validation|load-tool-yaml|"
+            "load-validation-yaml|validate-constraints|validate-invalid-tool> "
+            "[args...]"
+        )
+        return 1
+
+    command = sys.argv[1]
+
+    if command == "create-tool":
+        return _cmd_create_tool()
+    if command == "create-validation":
+        return _cmd_create_validation()
+    if command == "load-tool-yaml":
+        if len(sys.argv) < 3:
+            print("Usage: helper_tool_model.py load-tool-yaml <file>")
+            return 1
+        return _cmd_load_tool_yaml(sys.argv[2])
+    if command == "load-validation-yaml":
+        if len(sys.argv) < 3:
+            print("Usage: helper_tool_model.py load-validation-yaml <file>")
+            return 1
+        return _cmd_load_validation_yaml(sys.argv[2])
+    if command == "validate-constraints":
+        return _cmd_validate_constraints()
+    if command == "validate-invalid-tool":
+        return _cmd_validate_invalid_tool()
+
+    print(f"Unknown command: {command}")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

robot/tool_model.robot

@@ -0,0 +1,78 @@
+*** Settings ***
+Documentation    Smoke tests for Tool and Validation domain model creation,
+...              YAML config loading, and validation constraint enforcement.
+Resource         ${CURDIR}/common.resource
+Suite Setup      Setup Test Environment
+Suite Teardown   Cleanup Test Environment
+
+*** Variables ***
+${HELPER}    ${CURDIR}/helper_tool_model.py
+
+*** Test Cases ***
+Create Minimal Tool Model
+    [Documentation]    Create a builtin Tool model and verify identity fields
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    create-tool    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    tool-model-ok
+
+Create Validation Model With Forced Constraints
+    [Documentation]    Create a Validation and verify read_only/writes/checkpointable are forced
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    create-validation    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    validation-model-ok
+
+Load Custom Tool From YAML Config
+    [Documentation]    Load the custom-tool example YAML and verify Tool.from_config output
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    load-tool-yaml    ${CURDIR}/../examples/tools/custom-tool.yaml    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    tool-yaml-ok
+    Should Contain    ${result.stdout}    source=custom
+
+Load MCP Tool From YAML Config
+    [Documentation]    Load the mcp-tool example YAML and verify Tool.from_config output
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    load-tool-yaml    ${CURDIR}/../examples/tools/mcp-tool.yaml    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    tool-yaml-ok
+    Should Contain    ${result.stdout}    source=mcp
+
+Load Wrapped Validation From YAML Config
+    [Documentation]    Load the wrapped-validation example YAML and verify Validation.from_config output
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    load-validation-yaml    ${CURDIR}/../examples/validations/wrapped-validation.yaml    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    validation-yaml-ok
+    Should Contain    ${result.stdout}    mode=required
+
+Load Required Validation From YAML Config
+    [Documentation]    Load the required-validation example YAML and verify Validation.from_config output
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    load-validation-yaml    ${CURDIR}/../examples/validations/required-validation.yaml    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    validation-yaml-ok
+    Should Contain    ${result.stdout}    mode=required
+
+Validate Forced Constraints On Writable Capability
+    [Documentation]    Verify Validation forces read_only=True even when given writable capability
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    validate-constraints    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    validate-constraints-ok
+
+Reject Invalid Tool Configurations
+    [Documentation]    Verify that invalid tool name, missing code, and conflicting capabilities are rejected
+    ${result}=    Run Process    ${PYTHON}    ${HELPER}    validate-invalid-tool    cwd=${WORKSPACE}
+    Log    ${result.stdout}
+    Log    ${result.stderr}
+    Should Be Equal As Integers    ${result.rc}    0
+    Should Contain    ${result.stdout}    validate-invalid-ok