UAT: Spec documentation for conditional edge condition format doesn't match implementation #4058

New issue

Open

opened 2026-04-06 09:44:38 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 09:44:38 +00:00

Owner

Metadata

Branch: fix/reactive-graph-executor-conditional-edge-field-names
Commit Message: fix(docs): align spec conditional edge condition field names with graph_executor implementation
Milestone: (none — backlog)
Parent Epic: #392

Background and Context

The specification at docs/specification.md (lines 20985–20997) documents the conditional edge condition format using different field names than what src/cleveragents/reactive/graph_executor.py actually parses.

Spec documents (lines 20985–20997):

edges:
  # Conditional edge — routes based on context value
  - source: router
    target: brainstorming
    condition:
      context_value: next_node
      equals: brainstorming

  # Conditional edge — routes based on boolean flag
  - source: passthrough
    target: auto_driver
    condition:
      context_value: auto_finish_active
      equals: true

Actual implementation uses (src/cleveragents/reactive/graph_executor.py lines 60–64):

if isinstance(condition, dict) and condition.get("type") == "context_value":
    key = condition.get("key")
    if not key:
        return False
    return ctx.get(key) == condition.get("value")

Real-world example (examples/scientific_paper_writer.yaml lines 2357–2360):

condition:
  type: context_value
  key: next_node
  value: workflow_controller

Discrepancies:

Spec uses context_value: <key_name> (as a key-value pair) → Code uses type: context_value + key: <key_name>
Spec uses equals: <comparison_value> → Code uses value: <comparison_value>

Impact: Users following the spec to write conditional edges will find their configurations silently fail. The spec says to use context_value: next_node and equals: brainstorming, but the actual parser reads type: context_value, key: next_node, and value: brainstorming.

Evidence:

src/cleveragents/reactive/graph_executor.py lines 60–64 — uses type: context_value, key, value
examples/scientific_paper_writer.yaml lines 2357–2360 — uses type: context_value, key, value
docs/specification.md lines 20985–20997 — specifies context_value: <key>, equals: <value>

Resolution: Update docs/specification.md to use the correct field names (type: context_value, key, value) that match the implementation and the working examples. Per the project convention, the implementation is the source of truth when the spec and code diverge in a way that the code is already in use and validated by working examples.

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

Subtasks

Locate all occurrences in docs/specification.md that use the incorrect context_value: <key> / equals: <value> conditional edge format
Update spec documentation at lines 20985–20997 to use type: context_value, key: <key_name>, value: <comparison_value> format
Scan the full spec for any other conditional edge examples using the old field names and correct them
Write a Behave scenario in features/ verifying the documented conditional edge format matches the parser in graph_executor.py
Verify all nox stages pass (nox -e lint, nox -e typecheck, nox -e unit_tests, nox -e coverage_report)

Definition of Done

All occurrences of the incorrect conditional edge format in docs/specification.md are corrected to match the implementation
A Behave scenario exists that validates the conditional edge condition field names (type, key, value) against the graph_executor.py parser
No other spec examples use the deprecated context_value: <key> / equals: <value> format
All nox stages pass
Coverage >= 97%
PR is merged and this issue is closed

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

## Metadata - **Branch**: `fix/reactive-graph-executor-conditional-edge-field-names` - **Commit Message**: `fix(docs): align spec conditional edge condition field names with graph_executor implementation` - **Milestone**: *(none — backlog)* - **Parent Epic**: #392 ## Background and Context The specification at `docs/specification.md` (lines 20985–20997) documents the conditional edge condition format using different field names than what `src/cleveragents/reactive/graph_executor.py` actually parses. **Spec documents (lines 20985–20997):** ```yaml edges: # Conditional edge — routes based on context value - source: router target: brainstorming condition: context_value: next_node equals: brainstorming # Conditional edge — routes based on boolean flag - source: passthrough target: auto_driver condition: context_value: auto_finish_active equals: true ``` **Actual implementation uses (`src/cleveragents/reactive/graph_executor.py` lines 60–64):** ```python if isinstance(condition, dict) and condition.get("type") == "context_value": key = condition.get("key") if not key: return False return ctx.get(key) == condition.get("value") ``` **Real-world example (`examples/scientific_paper_writer.yaml` lines 2357–2360):** ```yaml condition: type: context_value key: next_node value: workflow_controller ``` **Discrepancies:** 1. Spec uses `context_value: <key_name>` (as a key-value pair) → Code uses `type: context_value` + `key: <key_name>` 2. Spec uses `equals: <comparison_value>` → Code uses `value: <comparison_value>` **Impact:** Users following the spec to write conditional edges will find their configurations silently fail. The spec says to use `context_value: next_node` and `equals: brainstorming`, but the actual parser reads `type: context_value`, `key: next_node`, and `value: brainstorming`. **Evidence:** - `src/cleveragents/reactive/graph_executor.py` lines 60–64 — uses `type: context_value`, `key`, `value` - `examples/scientific_paper_writer.yaml` lines 2357–2360 — uses `type: context_value`, `key`, `value` - `docs/specification.md` lines 20985–20997 — specifies `context_value: <key>`, `equals: <value>` **Resolution:** Update `docs/specification.md` to use the correct field names (`type: context_value`, `key`, `value`) that match the implementation and the working examples. Per the project convention, the implementation is the source of truth when the spec and code diverge in a way that the code is already in use and validated by working examples. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Subtasks - [ ] Locate all occurrences in `docs/specification.md` that use the incorrect `context_value: <key>` / `equals: <value>` conditional edge format - [ ] Update spec documentation at lines 20985–20997 to use `type: context_value`, `key: <key_name>`, `value: <comparison_value>` format - [ ] Scan the full spec for any other conditional edge examples using the old field names and correct them - [ ] Write a Behave scenario in `features/` verifying the documented conditional edge format matches the parser in `graph_executor.py` - [ ] Verify all nox stages pass (`nox -e lint`, `nox -e typecheck`, `nox -e unit_tests`, `nox -e coverage_report`) ## Definition of Done - [ ] All occurrences of the incorrect conditional edge format in `docs/specification.md` are corrected to match the implementation - [ ] A Behave scenario exists that validates the conditional edge condition field names (`type`, `key`, `value`) against the `graph_executor.py` parser - [ ] No other spec examples use the deprecated `context_value: <key>` / `equals: <value>` format - [ ] All nox stages pass - [ ] Coverage >= 97% - [ ] PR is merged and this issue is closed --- **Automated by CleverAgents Bot** Supervisor: Acting on behalf of: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 09:44:51 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-06 09:46:41 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo referenced this issue

2026-04-06 09:47:14 +00:00

[Automated] CleverAgents Build Session - 2026-04-06 #3775

freemo added the

Points

label