cleveragents/cleveragents-core

Fork 3

BUG-HUNT: [spec-alignment] Missing required schema fields in example YAML files violates configuration specification #7289

New issue

Open

opened 2026-04-10 15:13:59 +00:00 by HAL9000 · 4 comments

HAL9000 commented

2026-04-10 15:13:59 +00:00

Owner

Metadata

Branch: bugfix/example-yaml-missing-required-schema-fields
Commit Message: fix(examples): add required schema fields to example YAML configuration files
Milestone: (none — see backlog note below)
Parent Epic: #5502

Backlog note: This issue was discovered during autonomous operation
on milestone v3.8.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

Background and Context

Several YAML configuration files in examples/ are missing required schema fields (name, version, schema_version) as mandated by the project's configuration specification. The configuration schema requires all actor/configuration YAML files to include proper schema identifiers so that the configuration loader can validate, version, and correctly parse them. Without these fields, configuration validation will fail and runtime loading may produce errors or silently produce incorrect behaviour.

Current Behavior

examples/some-example.yaml contains only a single line: example: 1 — it is missing all required schema fields and appears to be a placeholder file that was never completed.
examples/basic_chat_actor.yaml defines an agents configuration block but has no top-level name, version, or schema_version fields.
Neither file can be validated against the configuration schema, and neither can be used as a working example by end users.

Expected Behavior

All YAML configuration files in examples/ must include the required schema fields (name, version, schema_version) as specified in the project configuration specification. Example files should be fully valid, loadable configurations that users can copy and adapt.

Evidence

examples/some-example.yaml — entire file content is example: 1; no schema fields present.
examples/basic_chat_actor.yaml — contains agents: block with actor definitions but is missing top-level name, version, and schema_version fields required by the configuration schema.
The project specification defines required top-level fields for all configuration files; their absence means these files violate the schema contract.

Impact

Configuration validation will fail when these files are loaded.
Runtime loading may produce errors or silently produce incorrect behaviour.
Example files cannot be validated against the schema, undermining their purpose as reference configurations.
Users following the examples will encounter failures or produce invalid configurations.

Acceptance Criteria

examples/basic_chat_actor.yaml includes all required top-level schema fields (name, version, schema_version) and passes schema validation.
examples/some-example.yaml is either removed (if it is a stale placeholder) or replaced with a complete, valid example configuration including all required schema fields.
All remaining files in examples/ are audited for missing required schema fields; any violations are fixed in the same commit.
All modified example files pass schema validation (e.g., via agents validation or equivalent).

Supporting Information

Files affected: examples/basic_chat_actor.yaml, examples/some-example.yaml
Category: spec-alignment
Severity: Medium — violates configuration schema requirements; could cause runtime failures for users following examples

Subtasks

Audit all files in examples/ for missing required schema fields (name, version, schema_version)
Fix examples/basic_chat_actor.yaml: add required top-level name, version, and schema_version fields
Fix or remove examples/some-example.yaml: either replace with a complete valid example or delete the placeholder
Validate all modified example files against the configuration schema
Tests (Behave): Add or update scenarios verifying that example YAML files pass schema validation
Tests (Robot): Add integration test confirming example configurations load without errors
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 (fix(examples): add required schema fields to example YAML configuration files), 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 (bugfix/example-yaml-missing-required-schema-fields).
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
All nox stages pass.
Coverage ≥ 97%.

Automated by CleverAgents Bot
Supervisor: Acting on behalf of: UAT Testing | Agent: new-issue-creator

## Metadata - **Branch**: `bugfix/example-yaml-missing-required-schema-fields` - **Commit Message**: `fix(examples): add required schema fields to example YAML configuration files` - **Milestone**: *(none — see backlog note below)* - **Parent Epic**: #5502 > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.8.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. --- ## Background and Context Several YAML configuration files in `examples/` are missing required schema fields (`name`, `version`, `schema_version`) as mandated by the project's configuration specification. The configuration schema requires all actor/configuration YAML files to include proper schema identifiers so that the configuration loader can validate, version, and correctly parse them. Without these fields, configuration validation will fail and runtime loading may produce errors or silently produce incorrect behaviour. ## Current Behavior - `examples/some-example.yaml` contains only a single line: `example: 1` — it is missing all required schema fields and appears to be a placeholder file that was never completed. - `examples/basic_chat_actor.yaml` defines an `agents` configuration block but has no top-level `name`, `version`, or `schema_version` fields. - Neither file can be validated against the configuration schema, and neither can be used as a working example by end users. ## Expected Behavior All YAML configuration files in `examples/` must include the required schema fields (`name`, `version`, `schema_version`) as specified in the project configuration specification. Example files should be fully valid, loadable configurations that users can copy and adapt. ## Evidence 1. `examples/some-example.yaml` — entire file content is `example: 1`; no schema fields present. 2. `examples/basic_chat_actor.yaml` — contains `agents:` block with actor definitions but is missing top-level `name`, `version`, and `schema_version` fields required by the configuration schema. 3. The project specification defines required top-level fields for all configuration files; their absence means these files violate the schema contract. ## Impact - Configuration validation will fail when these files are loaded. - Runtime loading may produce errors or silently produce incorrect behaviour. - Example files cannot be validated against the schema, undermining their purpose as reference configurations. - Users following the examples will encounter failures or produce invalid configurations. ## Acceptance Criteria - [ ] `examples/basic_chat_actor.yaml` includes all required top-level schema fields (`name`, `version`, `schema_version`) and passes schema validation. - [ ] `examples/some-example.yaml` is either removed (if it is a stale placeholder) or replaced with a complete, valid example configuration including all required schema fields. - [ ] All remaining files in `examples/` are audited for missing required schema fields; any violations are fixed in the same commit. - [ ] All modified example files pass schema validation (e.g., via `agents validation` or equivalent). ## Supporting Information - **Files affected**: `examples/basic_chat_actor.yaml`, `examples/some-example.yaml` - **Category**: spec-alignment - **Severity**: Medium — violates configuration schema requirements; could cause runtime failures for users following examples ## Subtasks - [ ] Audit all files in `examples/` for missing required schema fields (`name`, `version`, `schema_version`) - [ ] Fix `examples/basic_chat_actor.yaml`: add required top-level `name`, `version`, and `schema_version` fields - [ ] Fix or remove `examples/some-example.yaml`: either replace with a complete valid example or delete the placeholder - [ ] Validate all modified example files against the configuration schema - [ ] Tests (Behave): Add or update scenarios verifying that example YAML files pass schema validation - [ ] Tests (Robot): Add integration test confirming example configurations load without errors - [ ] 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 (`fix(examples): add required schema fields to example YAML configuration files`), 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 (`bugfix/example-yaml-missing-required-schema-fields`). - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage ≥ 97%. --- **Automated by CleverAgents Bot** Supervisor: Acting on behalf of: UAT Testing | Agent: new-issue-creator

HAL9000 added a new dependency

2026-04-10 15:14:11 +00:00

#5502 EPIC: Actor Execution & Configuration — GRAPH Actor, Config Schema & CLI Compliance (v3.5.0)

HAL9000 commented

2026-04-10 15:21:05 +00:00

Author

Owner

⚠️ Automated Label Application — Action Required

This issue was created by the automated new-issue-creator agent. The following labels need to be applied manually because the Forgejo label MCP server is not connected to this instance:

Label	ID	Purpose
`State/Unverified`	846	Initial state for all new issues
`Type/Bug`	1406	This is a bug report
`Priority/Backlog`	1408	Non-critical issue routed to backlog per Milestone Scope Guard

Dependency link: This issue has been linked to block parent Epic #5502 (Actor Execution & Configuration) ✅

Automated by CleverAgents Bot
Supervisor: Acting on behalf of: UAT Testing | Agent: new-issue-creator

## ⚠️ Automated Label Application — Action Required This issue was created by the automated new-issue-creator agent. The following labels need to be applied manually because the Forgejo label MCP server is not connected to this instance: | Label | ID | Purpose | |---|---|---| | `State/Unverified` | 846 | Initial state for all new issues | | `Type/Bug` | 1406 | This is a bug report | | `Priority/Backlog` | 1408 | Non-critical issue routed to backlog per Milestone Scope Guard | **Dependency link**: This issue has been linked to block parent Epic #5502 (Actor Execution & Configuration) ✅ --- **Automated by CleverAgents Bot** Supervisor: Acting on behalf of: UAT Testing | Agent: new-issue-creator

HAL9000 added the

labels

2026-04-10 18:44:25 +00:00

HAL9000 added

and removed

labels

2026-04-14 06:24:20 +00:00

HAL9000 commented

2026-04-14 06:24:20 +00:00

Author

Owner

✅ Verified — Spec alignment bug: example YAML files missing required schema fields. MoSCoW: Should-have. Priority: Medium.

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

✅ **Verified** — Spec alignment bug: example YAML files missing required schema fields. MoSCoW: Should-have. Priority: Medium. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor

HAL9000 commented

2026-04-14 06:29:58 +00:00

Author

Owner

✅ Verified — Spec alignment bug: example YAML files missing required schema fields. MoSCoW: Should-have. Priority: Medium.

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