UAT: Spec documentation for message_router rule fields doesn't match implementation #4055

New issue

Open

opened 2026-04-06 09:39:30 +00:00 by freemo · 0 comments

freemo commented

2026-04-06 09:39:30 +00:00

Owner

Metadata

Branch: fix/reactive-message-router-field-names
Commit Message: fix(reactive): align graph_executor message_router rule field names with spec (match_type→type, pattern→match)
Milestone: (none — backlog)
Parent Epic: #392

Background and Context

The specification at docs/specification.md (lines 20929–20957) documents the message_router rule format using different field names than what src/cleveragents/reactive/graph_executor.py actually parses. Per project convention, the specification is the source of truth; the implementation must be updated to match it.

This was discovered during UAT testing of the reactive graph routing system.

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

Current Behavior

src/cleveragents/reactive/graph_executor.py (lines 235–250) reads rule fields using implementation-specific names that differ from the spec:

match_type = rule.get("match_type", "prefix")
pattern = rule.get("pattern", "")

The examples/scientific_paper_writer.yaml and features/steps/reactive_application_coverage_steps.py also use these non-spec field names:

- match_type: prefix
  pattern: "GOTO_BRAINSTORMING"
  target: brainstorming
  extract_message: true
  separator: ":"

Expected Behavior (per spec, lines 20929–20957)

The spec defines the following field names for message_router rules:

router:
  type: message_router
  rules:
    - type: prefix
      match: "GOTO_BRAINSTORMING"
      target: brainstorming
      strip_match: true
    - type: contains
      match: "SET_TOPIC:"
      target: discovery
    - type: suffix
      match: ""
      target: workflow_controller

Spec Field	Implementation Field	Description
`type`	`match_type`	Match strategy: `prefix`, `contains`, or `suffix`
`match`	`pattern`	Pattern to match against message content
`strip_match`	`extract_message` + `separator`	Whether/how to strip the matched pattern

The three discrepancies are:

Spec uses type for match type → code uses match_type
Spec uses match for the pattern → code uses pattern
Spec uses strip_match: true to strip the prefix → code uses extract_message: true + separator: ":" to extract the message after a separator

Impact

Users following the spec to write message_router rules will produce configurations that silently fail to route. Any YAML actor graph authored against the spec will not work with the current implementation. This also creates inconsistency with the related langgraph/nodes.py implementation tracked in #3658.

Evidence

src/cleveragents/reactive/graph_executor.py lines 235–250 — uses match_type and pattern
examples/scientific_paper_writer.yaml lines 1892+ — uses match_type, pattern, extract_message, separator
features/steps/reactive_application_coverage_steps.py lines 401+ — uses match_type, pattern, extract_message
docs/specification.md lines 20929–20957 — specifies type, match, strip_match

Resolution

Per project convention the spec is the source of truth. The implementation must be updated to accept the spec-defined field names (type, match, strip_match). All examples and feature steps must be updated to match.

Alternative (lower risk): Update the spec to document the current implementation field names (match_type, pattern, extract_message/separator) — only if a breaking change to the YAML schema is unacceptable.

Subtasks

Update src/cleveragents/reactive/graph_executor.py to read type (not match_type) and match (not pattern) from rule dicts
Update strip_match handling: replace extract_message + separator logic with strip_match: true semantics per spec
Update examples/scientific_paper_writer.yaml rule fields to use spec-compliant names
Update features/steps/reactive_application_coverage_steps.py rule fields to use spec-compliant names
Search for any other files using match_type or pattern in message_router rule context and update them
Write/update Behave unit tests covering all three rule types with spec-compliant field names
Verify all nox stages pass; coverage ≥ 97%

Definition of Done

graph_executor.py reads type and match fields as specified in docs/specification.md
strip_match: true strips the matched prefix/suffix from the forwarded message
All examples and feature steps use spec-compliant field names
No remaining references to match_type or pattern in message_router rule parsing context
Behave unit tests pass for all three rule types with spec-compliant field names
All nox stages pass
Coverage ≥ 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/reactive-message-router-field-names` - **Commit Message**: `fix(reactive): align graph_executor message_router rule field names with spec (match_type→type, pattern→match)` - **Milestone**: *(none — backlog)* - **Parent Epic**: #392 ## Background and Context The specification at `docs/specification.md` (lines 20929–20957) documents the `message_router` rule format using different field names than what `src/cleveragents/reactive/graph_executor.py` actually parses. Per project convention, the specification is the source of truth; the implementation must be updated to match it. This was discovered during UAT testing of the reactive graph routing system. > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.6.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## Current Behavior `src/cleveragents/reactive/graph_executor.py` (lines 235–250) reads rule fields using implementation-specific names that differ from the spec: ```python match_type = rule.get("match_type", "prefix") pattern = rule.get("pattern", "") ``` The `examples/scientific_paper_writer.yaml` and `features/steps/reactive_application_coverage_steps.py` also use these non-spec field names: ```yaml - match_type: prefix pattern: "GOTO_BRAINSTORMING" target: brainstorming extract_message: true separator: ":" ``` ## Expected Behavior (per spec, lines 20929–20957) The spec defines the following field names for `message_router` rules: ```yaml router: type: message_router rules: - type: prefix match: "GOTO_BRAINSTORMING" target: brainstorming strip_match: true - type: contains match: "SET_TOPIC:" target: discovery - type: suffix match: "" target: workflow_controller ``` | Spec Field | Implementation Field | Description | |------------|----------------------|-------------| | `type` | `match_type` | Match strategy: `prefix`, `contains`, or `suffix` | | `match` | `pattern` | Pattern to match against message content | | `strip_match` | `extract_message` + `separator` | Whether/how to strip the matched pattern | The three discrepancies are: 1. Spec uses `type` for match type → code uses `match_type` 2. Spec uses `match` for the pattern → code uses `pattern` 3. Spec uses `strip_match: true` to strip the prefix → code uses `extract_message: true` + `separator: ":"` to extract the message after a separator ## Impact Users following the spec to write `message_router` rules will produce configurations that silently fail to route. Any YAML actor graph authored against the spec will not work with the current implementation. This also creates inconsistency with the related `langgraph/nodes.py` implementation tracked in #3658. ## Evidence - `src/cleveragents/reactive/graph_executor.py` lines 235–250 — uses `match_type` and `pattern` - `examples/scientific_paper_writer.yaml` lines 1892+ — uses `match_type`, `pattern`, `extract_message`, `separator` - `features/steps/reactive_application_coverage_steps.py` lines 401+ — uses `match_type`, `pattern`, `extract_message` - `docs/specification.md` lines 20929–20957 — specifies `type`, `match`, `strip_match` ## Resolution Per project convention the spec is the source of truth. The implementation must be updated to accept the spec-defined field names (`type`, `match`, `strip_match`). All examples and feature steps must be updated to match. Alternative (lower risk): Update the spec to document the current implementation field names (`match_type`, `pattern`, `extract_message`/`separator`) — only if a breaking change to the YAML schema is unacceptable. ## Subtasks - [ ] Update `src/cleveragents/reactive/graph_executor.py` to read `type` (not `match_type`) and `match` (not `pattern`) from rule dicts - [ ] Update `strip_match` handling: replace `extract_message` + `separator` logic with `strip_match: true` semantics per spec - [ ] Update `examples/scientific_paper_writer.yaml` rule fields to use spec-compliant names - [ ] Update `features/steps/reactive_application_coverage_steps.py` rule fields to use spec-compliant names - [ ] Search for any other files using `match_type` or `pattern` in `message_router` rule context and update them - [ ] Write/update Behave unit tests covering all three rule types with spec-compliant field names - [ ] Verify all nox stages pass; coverage ≥ 97% ## Definition of Done - [ ] `graph_executor.py` reads `type` and `match` fields as specified in `docs/specification.md` - [ ] `strip_match: true` strips the matched prefix/suffix from the forwarded message - [ ] All examples and feature steps use spec-compliant field names - [ ] No remaining references to `match_type` or `pattern` in `message_router` rule parsing context - [ ] Behave unit tests pass for all three rule types with spec-compliant field names - [ ] All nox stages pass - [ ] Coverage ≥ 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-06 09:39:42 +00:00

#392 Epic: Actor YAML & Compiler

freemo referenced this issue

2026-04-06 09:40:55 +00:00

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

freemo added the

Points

label

2026-04-06 09:43:08 +00:00

freemo referenced this issue

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