cleveragents/cleveragents-core

Fork 3

UAT: `SkillIncludeSchema` missing `tool_overrides` field — spec-required per-tool metadata overrides for included skills are not supported #2119

New issue

Open

opened 2026-04-03 04:13:48 +00:00 by freemo · 1 comment

freemo commented

2026-04-03 04:13:48 +00:00

Owner

Metadata

Branch: fix/skill-include-schema-tool-overrides
Commit Message: fix(skills): add tool_overrides field to SkillIncludeSchema and update SkillInclude domain model
Milestone: v3.7.0
Parent Epic: #392

Background

The SkillIncludeSchema in src/cleveragents/skills/schema.py is missing the tool_overrides 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) when including a sub-skill. Without this field, the skill composition system is incomplete and any spec-compliant YAML that uses tool_overrides will be rejected by Pydantic validation.

Additionally, the SkillInclude domain model in src/cleveragents/domain/models/core/skill.py uses a flat overrides dict structure that does not match the spec's per-tool list format, meaning the domain model also needs to be updated.

Current Behavior

SkillIncludeSchema only has name and description fields:

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

Because extra="forbid" is set, any YAML that includes tool_overrides will fail with a Pydantic ValidationError: Extra inputs are not permitted.

The SkillInclude domain model uses a flat dict for overrides, which does not match the spec's per-tool list structure.

Expected Behavior

Per docs/specification.md, the skill YAML configuration must accept tool_overrides in each includes entry:

skill:
  name: local/production-ops
  includes:
    - name: local/devops-toolkit
      tool_overrides:
        - tool: local/run-migrations
          override:
            capability:
              human_approval_required: true
              write_scope: [database:production]
        - tool: local/create-github-issue
          override:
            capability:
              human_approval_required: true

SkillIncludeSchema must include a tool_overrides field accepting a list of per-tool override objects. The SkillInclude domain model must be updated to use the spec's per-tool list structure instead of a flat dict.

Steps to Reproduce

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

name: local/production-ops
description: Production operations
includes:
  - name: local/devops-toolkit
    tool_overrides:
      - tool: 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 tool_overrides

Affected Code

src/cleveragents/skills/schema.py — SkillIncludeSchema class: missing tool_overrides field
src/cleveragents/domain/models/core/skill.py — SkillInclude class: overrides field uses wrong structure (flat dict vs spec's per-tool list)

Severity

High — The per-tool metadata override mechanism for included skills is completely unsupported. This is a key feature of the skill composition system described in the spec. Any spec-compliant YAML using tool_overrides will fail at parse time.

Subtasks

Write a TDD issue-capture BDD scenario (@tdd_expected_fail) in features/ demonstrating the ValidationError when tool_overrides is present in a skill YAML includes entry
Add a ToolOverrideSchema Pydantic model to src/cleveragents/skills/schema.py representing a single per-tool override entry (tool: str, override: dict[str, Any])
Add tool_overrides: list[ToolOverrideSchema] | None field to SkillIncludeSchema in src/cleveragents/skills/schema.py
Update SkillInclude domain model in src/cleveragents/domain/models/core/skill.py to replace the flat overrides dict with a tool_overrides: list[ToolOverride] | None field matching the spec's per-tool list structure
Add a ToolOverride domain model dataclass/class to src/cleveragents/domain/models/core/skill.py
Update the schema-to-domain mapping logic to correctly translate SkillIncludeSchema.tool_overrides → SkillInclude.tool_overrides
Remove the @tdd_expected_fail tag and ensure the BDD scenario now passes
Add additional BDD scenarios covering: tool_overrides absent (defaults to None), multiple overrides, 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

All subtasks above are completed
SkillIncludeSchema accepts tool_overrides without raising a Pydantic ValidationError
SkillInclude domain model uses the spec's per-tool list structure for tool_overrides
Schema-to-domain mapping correctly translates tool_overrides
BDD scenarios cover the happy path, absent field, and multiple overrides
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 message fix(skills): add tool_overrides field to SkillIncludeSchema and update SkillInclude domain model on branch fix/skill-include-schema-tool-overrides
PR submitted, reviewed (≥2 approvals), and merged; issue closed

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

## Metadata - **Branch**: `fix/skill-include-schema-tool-overrides` - **Commit Message**: `fix(skills): add tool_overrides field to SkillIncludeSchema and update SkillInclude domain model` - **Milestone**: v3.7.0 - **Parent Epic**: #392 ## Background The `SkillIncludeSchema` in `src/cleveragents/skills/schema.py` is missing the `tool_overrides` 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`) when including a sub-skill. Without this field, the skill composition system is incomplete and any spec-compliant YAML that uses `tool_overrides` will be rejected by Pydantic validation. Additionally, the `SkillInclude` domain model in `src/cleveragents/domain/models/core/skill.py` uses a flat `overrides` dict structure that does not match the spec's per-tool list format, meaning the domain model also needs to be updated. ## Current Behavior `SkillIncludeSchema` only has `name` and `description` fields: ```python class SkillIncludeSchema(BaseModel): name: str = Field(...) description: str | None = Field(default=None, ...) model_config = ConfigDict(extra="forbid") ``` Because `extra="forbid"` is set, any YAML that includes `tool_overrides` will fail with a Pydantic `ValidationError: Extra inputs are not permitted`. The `SkillInclude` domain model uses a flat dict for `overrides`, which does not match the spec's per-tool list structure. ## Expected Behavior Per `docs/specification.md`, the skill YAML configuration must accept `tool_overrides` in each `includes` entry: ```yaml skill: name: local/production-ops includes: - name: local/devops-toolkit tool_overrides: - tool: local/run-migrations override: capability: human_approval_required: true write_scope: [database:production] - tool: local/create-github-issue override: capability: human_approval_required: true ``` `SkillIncludeSchema` must include a `tool_overrides` field accepting a list of per-tool override objects. The `SkillInclude` domain model must be updated to use the spec's per-tool list structure instead of a flat dict. ## Steps to Reproduce 1. Create a skill YAML file using the spec-compliant `tool_overrides` field: ```yaml name: local/production-ops description: Production operations includes: - name: local/devops-toolkit tool_overrides: - tool: 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 `tool_overrides` ## Affected Code - `src/cleveragents/skills/schema.py` — `SkillIncludeSchema` class: missing `tool_overrides` field - `src/cleveragents/domain/models/core/skill.py` — `SkillInclude` class: `overrides` field uses wrong structure (flat dict vs spec's per-tool list) ## Severity **High** — The per-tool metadata override mechanism for included skills is completely unsupported. This is a key feature of the skill composition system described in the spec. Any spec-compliant YAML using `tool_overrides` will fail at parse time. ## Subtasks - [ ] Write a TDD issue-capture BDD scenario (`@tdd_expected_fail`) in `features/` demonstrating the `ValidationError` when `tool_overrides` is present in a skill YAML `includes` entry - [ ] Add a `ToolOverrideSchema` Pydantic model to `src/cleveragents/skills/schema.py` representing a single per-tool override entry (`tool: str`, `override: dict[str, Any]`) - [ ] Add `tool_overrides: list[ToolOverrideSchema] | None` field to `SkillIncludeSchema` in `src/cleveragents/skills/schema.py` - [ ] Update `SkillInclude` domain model in `src/cleveragents/domain/models/core/skill.py` to replace the flat `overrides` dict with a `tool_overrides: list[ToolOverride] | None` field matching the spec's per-tool list structure - [ ] Add a `ToolOverride` domain model dataclass/class to `src/cleveragents/domain/models/core/skill.py` - [ ] Update the schema-to-domain mapping logic to correctly translate `SkillIncludeSchema.tool_overrides` → `SkillInclude.tool_overrides` - [ ] Remove the `@tdd_expected_fail` tag and ensure the BDD scenario now passes - [ ] Add additional BDD scenarios covering: `tool_overrides` absent (defaults to `None`), multiple overrides, 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 - [ ] All subtasks above are completed - [ ] `SkillIncludeSchema` accepts `tool_overrides` without raising a Pydantic `ValidationError` - [ ] `SkillInclude` domain model uses the spec's per-tool list structure for `tool_overrides` - [ ] Schema-to-domain mapping correctly translates `tool_overrides` - [ ] BDD scenarios cover the happy path, absent field, and multiple overrides - [ ] 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 message `fix(skills): add tool_overrides field to SkillIncludeSchema and update SkillInclude domain model` on branch `fix/skill-include-schema-tool-overrides` - [ ] PR submitted, reviewed (≥2 approvals), 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:13:53 +00:00

freemo added a new dependency

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

#392 Epic: Actor YAML & Compiler

freemo commented

2026-04-03 04:15:57 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: High (confirmed) — The tool_overrides field is a key feature of the skill composition system. Any spec-compliant YAML using it will fail at parse time due to extra="forbid".
Milestone: v3.7.0 (confirmed — Skills Epic #392)
MoSCoW: Should Have — Per-tool metadata overrides are a spec-defined feature for skill composition. Without this, the skill system cannot support production-grade override patterns.
Parent Epic: #392 (confirmed correct)

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

Issue triaged by project owner: - **State**: Verified - **Priority**: High (confirmed) — The `tool_overrides` field is a key feature of the skill composition system. Any spec-compliant YAML using it will fail at parse time due to `extra="forbid"`. - **Milestone**: v3.7.0 (confirmed — Skills Epic #392) - **MoSCoW**: Should Have — Per-tool metadata overrides are a spec-defined feature for skill composition. Without this, the skill system cannot support production-grade override patterns. - **Parent Epic**: #392 (confirmed correct) --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner

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:05 +00:00