cleveragents/cleveragents-core

Fork 3

UAT: `SkillToolRefSchema` missing `override` field — spec-required per-tool metadata overrides in skill tool references are not supported #2124

New issue

Open

opened 2026-04-03 04:16:52 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:16:52 +00:00

Owner

Metadata

Branch: fix/skill-tool-ref-schema-override-field
Commit Message: fix(skills): add override field and string reference support to SkillToolRefSchema
Milestone: v3.7.0
Parent Epic: #392

Background and Context

The SkillToolRefSchema in src/cleveragents/skills/schema.py is missing the override field that the specification defines as part of the skill YAML configuration. The specification describes a per-tool metadata override mechanism that allows users to override individual tool metadata (e.g., capability, human_approval_required, write_scope) at the point of use within a skill's tools list.

Additionally, the spec allows simple string references (just the tool name) alongside dict references with overrides in the tools list. The current schema only supports dict references (requiring a name field), not simple string references.

Because extra="forbid" is set on SkillToolRefSchema, any spec-compliant YAML that includes an override: key will fail immediately with a Pydantic ValidationError. The existing flat writes and checkpointable fields are a partial approximation of the spec's intent but do not match the spec's defined nested override.capability structure.

Current Behavior

SkillToolRefSchema only has flat override fields and does not accept the spec-defined override structure:

class SkillToolRefSchema(BaseModel):
    name: str = Field(...)
    description: str | None = Field(default=None, ...)
    writes: bool | None = Field(default=None, ...)
    checkpointable: bool | None = Field(default=None, ...)
    model_config = ConfigDict(extra="forbid")

There is no override field with a nested capability object.
The flat writes and checkpointable fields do not match the spec's structure.
Because extra="forbid" is set, any YAML that includes override: will fail with a Pydantic ValidationError: Extra inputs are not permitted.
SkillConfigSchema.tools only accepts SkillToolRefSchema dicts, not simple string references.

Steps to reproduce:

Create a skill YAML file using the spec-compliant override field:

name: local/test-skill
description: Test skill
tools:
  - name: local/run-migrations
    override:
      capability:
        human_approval_required: true

Call SkillConfigSchema.from_yaml(yaml_content)
Observe: Pydantic raises ValidationError: Extra inputs are not permitted for override

Expected Behavior

Per docs/specification.md, the skill YAML configuration must accept an override field with nested capability in each tools entry, and must also accept simple string references:

skill:
  name: local/strict-devops
  tools:
    - name: local/run-migrations
      override:
        capability:
          human_approval_required: true
          write_scope: [database:staging]
    - local/validate-api-compat  # No overrides, use as registered

SkillToolRefSchema must include an override field accepting a nested capability object. SkillConfigSchema.tools must accept both simple string references and dict references with overrides.

Acceptance Criteria

SkillToolRefSchema accepts an override field with a nested capability object without raising a Pydantic ValidationError
SkillConfigSchema.tools accepts simple string references (e.g., - local/validate-api-compat) alongside dict references
The schema-to-domain mapping correctly translates override.capability fields into the domain model
All existing tests continue to pass
All nox quality gates pass

Supporting Information

Affected code locations:

src/cleveragents/skills/schema.py — SkillToolRefSchema class: missing override field with nested capability
src/cleveragents/skills/schema.py — SkillConfigSchema.tools field: only accepts SkillToolRefSchema dicts, not simple strings

Severity: Medium — Users cannot apply per-tool metadata overrides in skill tool references as the spec requires. The spec explicitly shows this as a key feature of the skill composition system.

What was tested: Code-level analysis of src/cleveragents/skills/schema.py against docs/specification.md skill YAML configuration section.

Subtasks

Write a TDD issue-capture BDD scenario (@tdd_expected_fail) in features/ demonstrating the ValidationError when override is present in a skill YAML tools entry
Write a TDD issue-capture BDD scenario (@tdd_expected_fail) in features/ demonstrating the ValidationError when a simple string reference is used in a skill YAML tools list
Add a ToolCapabilityOverrideSchema Pydantic model to src/cleveragents/skills/schema.py representing the nested capability override object (e.g., human_approval_required: bool | None, write_scope: list[str] | None)
Add a ToolRefOverrideSchema Pydantic model to src/cleveragents/skills/schema.py with a capability: ToolCapabilityOverrideSchema | None field
Add override: ToolRefOverrideSchema | None field to SkillToolRefSchema in src/cleveragents/skills/schema.py
Update SkillConfigSchema.tools to accept list[str | SkillToolRefSchema] so simple string references are valid alongside dict references
Update the schema-to-domain mapping logic to correctly translate SkillToolRefSchema.override.capability into the domain model
Remove the @tdd_expected_fail tags and ensure both BDD scenarios now pass
Add additional BDD scenarios covering: override absent (defaults to None), mixed string and dict tool references, and round-trip YAML parsing
Update type annotations throughout to satisfy nox -e typecheck (Pyright)
Run all nox quality gates and confirm passage

Definition of Done

SkillToolRefSchema accepts an override field with a nested capability object without raising a Pydantic ValidationError
SkillConfigSchema.tools accepts simple string references alongside dict references
The schema-to-domain mapping correctly translates override.capability fields
BDD scenarios cover the happy path, absent override field, mixed string/dict references, and round-trip YAML parsing
All nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e integration_tests, nox -e coverage_report)
Coverage >= 97%
Commit created with exact message: fix(skills): add override field and string reference support to SkillToolRefSchema on branch fix/skill-tool-ref-schema-override-field
Commit footer includes ISSUES CLOSED: #<this issue number>
PR submitted, reviewed, and merged; issue closed

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Metadata - **Branch**: `fix/skill-tool-ref-schema-override-field` - **Commit Message**: `fix(skills): add override field and string reference support to SkillToolRefSchema` - **Milestone**: v3.7.0 - **Parent Epic**: #392 ## Background and Context The `SkillToolRefSchema` in `src/cleveragents/skills/schema.py` is missing the `override` field that the specification defines as part of the skill YAML configuration. The specification describes a per-tool metadata override mechanism that allows users to override individual tool metadata (e.g., `capability`, `human_approval_required`, `write_scope`) at the point of use within a skill's `tools` list. Additionally, the spec allows simple string references (just the tool name) alongside dict references with overrides in the `tools` list. The current schema only supports dict references (requiring a `name` field), not simple string references. Because `extra="forbid"` is set on `SkillToolRefSchema`, any spec-compliant YAML that includes an `override:` key will fail immediately with a Pydantic `ValidationError`. The existing flat `writes` and `checkpointable` fields are a partial approximation of the spec's intent but do not match the spec's defined nested `override.capability` structure. ## Current Behavior `SkillToolRefSchema` only has flat override fields and does not accept the spec-defined `override` structure: ```python class SkillToolRefSchema(BaseModel): name: str = Field(...) description: str | None = Field(default=None, ...) writes: bool | None = Field(default=None, ...) checkpointable: bool | None = Field(default=None, ...) model_config = ConfigDict(extra="forbid") ``` - There is no `override` field with a nested `capability` object. - The flat `writes` and `checkpointable` fields do not match the spec's structure. - Because `extra="forbid"` is set, any YAML that includes `override:` will fail with a Pydantic `ValidationError: Extra inputs are not permitted`. - `SkillConfigSchema.tools` only accepts `SkillToolRefSchema` dicts, not simple string references. **Steps to reproduce:** 1. Create a skill YAML file using the spec-compliant `override` field: ```yaml name: local/test-skill description: Test skill tools: - name: local/run-migrations override: capability: human_approval_required: true ``` 2. Call `SkillConfigSchema.from_yaml(yaml_content)` 3. Observe: Pydantic raises `ValidationError: Extra inputs are not permitted` for `override` ## Expected Behavior Per `docs/specification.md`, the skill YAML configuration must accept an `override` field with nested `capability` in each `tools` entry, and must also accept simple string references: ```yaml skill: name: local/strict-devops tools: - name: local/run-migrations override: capability: human_approval_required: true write_scope: [database:staging] - local/validate-api-compat # No overrides, use as registered ``` `SkillToolRefSchema` must include an `override` field accepting a nested `capability` object. `SkillConfigSchema.tools` must accept both simple string references and dict references with overrides. ## Acceptance Criteria - `SkillToolRefSchema` accepts an `override` field with a nested `capability` object without raising a Pydantic `ValidationError` - `SkillConfigSchema.tools` accepts simple string references (e.g., `- local/validate-api-compat`) alongside dict references - The schema-to-domain mapping correctly translates `override.capability` fields into the domain model - All existing tests continue to pass - All nox quality gates pass ## Supporting Information **Affected code locations:** - `src/cleveragents/skills/schema.py` — `SkillToolRefSchema` class: missing `override` field with nested `capability` - `src/cleveragents/skills/schema.py` — `SkillConfigSchema.tools` field: only accepts `SkillToolRefSchema` dicts, not simple strings **Severity:** Medium — Users cannot apply per-tool metadata overrides in skill tool references as the spec requires. The spec explicitly shows this as a key feature of the skill composition system. **What was tested:** Code-level analysis of `src/cleveragents/skills/schema.py` against `docs/specification.md` skill YAML configuration section. ## Subtasks - [ ] Write a TDD issue-capture BDD scenario (`@tdd_expected_fail`) in `features/` demonstrating the `ValidationError` when `override` is present in a skill YAML `tools` entry - [ ] Write a TDD issue-capture BDD scenario (`@tdd_expected_fail`) in `features/` demonstrating the `ValidationError` when a simple string reference is used in a skill YAML `tools` list - [ ] Add a `ToolCapabilityOverrideSchema` Pydantic model to `src/cleveragents/skills/schema.py` representing the nested `capability` override object (e.g., `human_approval_required: bool | None`, `write_scope: list[str] | None`) - [ ] Add a `ToolRefOverrideSchema` Pydantic model to `src/cleveragents/skills/schema.py` with a `capability: ToolCapabilityOverrideSchema | None` field - [ ] Add `override: ToolRefOverrideSchema | None` field to `SkillToolRefSchema` in `src/cleveragents/skills/schema.py` - [ ] Update `SkillConfigSchema.tools` to accept `list[str | SkillToolRefSchema]` so simple string references are valid alongside dict references - [ ] Update the schema-to-domain mapping logic to correctly translate `SkillToolRefSchema.override.capability` into the domain model - [ ] Remove the `@tdd_expected_fail` tags and ensure both BDD scenarios now pass - [ ] Add additional BDD scenarios covering: `override` absent (defaults to `None`), mixed string and dict tool references, and round-trip YAML parsing - [ ] Update type annotations throughout to satisfy `nox -e typecheck` (Pyright) - [ ] Run all nox quality gates and confirm passage ## Definition of Done - [ ] `SkillToolRefSchema` accepts an `override` field with a nested `capability` object without raising a Pydantic `ValidationError` - [ ] `SkillConfigSchema.tools` accepts simple string references alongside dict references - [ ] The schema-to-domain mapping correctly translates `override.capability` fields - [ ] BDD scenarios cover the happy path, absent `override` field, mixed string/dict references, and round-trip YAML parsing - [ ] All nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e integration_tests`, `nox -e coverage_report`) - [ ] Coverage >= 97% - [ ] Commit created with exact message: `fix(skills): add override field and string reference support to SkillToolRefSchema` on branch `fix/skill-tool-ref-schema-override-field` - [ ] Commit footer includes `ISSUES CLOSED: #<this issue number>` - [ ] PR submitted, reviewed, and merged; issue closed --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester

freemo added this to the v3.7.0 milestone

2026-04-03 04:16:56 +00:00

freemo added a new dependency

2026-04-03 04:17:47 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-03 04:20:11 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo referenced this issue

2026-04-03 04:21:38 +00:00

[UAT-SUPERVISOR] Progress Report — Cycle 721 — v3.7.0 #2138

freemo referenced this issue

2026-04-03 04:22:00 +00:00

[CA-AUTO] UAT Pool Supervisor — v3.7.0 — Session Tracker #2023

freemo self-assigned this

2026-04-03 16:58:04 +00:00

freemo commented

2026-04-03 18:28:18 +00:00

Author

Owner

MoSCoW classification: Should Have

Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible.

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

MoSCoW classification: **Should Have** Rationale: This issue addresses a spec requirement or important quality improvement. It should be included in the milestone if possible. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner