cleveragents/cleveragents-core

Fork 3

docs: invariant-reconciliation module guide has incorrect ReconciliationResult fields and wrong InvariantReconciliationActor constructor signature #5854

New issue

Open

opened 2026-04-09 10:56:07 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 10:56:07 +00:00

Owner

Summary

PR #5614 added docs/modules/invariant-reconciliation.md but the code examples in that guide do not match the actual implementation in src/cleveragents/actor/reconciliation.py.

Discrepancy 1: `ReconciliationResult` fields

Module guide shows:

@dataclass
class ReconciliationResult:
    plan_id: str
    resolved_invariants: list[Invariant]
    conflicts_detected: int
    conflicts_resolved: int
    decisions: list[ReconciliationDecision]
    success: bool

Actual implementation (reconciliation.py line 68):

@dataclass(frozen=True)
class ReconciliationResult:
    reconciled_set: InvariantSet
    conflicts: list[ConflictRecord]
    enforced_decision_ids: list[str]

Discrepancy 2: `InvariantReconciliationActor.init` signature

Module guide shows:

actor = InvariantReconciliationActor(invariant_service, event_bus, audit_service)

Actual implementation (reconciliation.py line 234):

def __init__(self, *, invariant_service: InvariantService, decision_service: DecisionService) -> None:

The actor takes decision_service, not event_bus and audit_service.

Discrepancy 3: `ReconciliationDecision` class

The module guide references a ReconciliationDecision dataclass with winner, loser, rationale, timestamp fields. The actual implementation uses ConflictRecord with key, winner, losers, reason fields.

Fix Required

Update docs/modules/invariant-reconciliation.md to match the actual implementation:

Fix ReconciliationResult fields
Fix InvariantReconciliationActor constructor signature
Replace ReconciliationDecision references with ConflictRecord
Update usage examples accordingly

References

PR #5614 (introduced the inaccurate docs)
src/cleveragents/actor/reconciliation.py (authoritative implementation)

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-updater

## Summary PR #5614 added `docs/modules/invariant-reconciliation.md` but the code examples in that guide do not match the actual implementation in `src/cleveragents/actor/reconciliation.py`. ## Discrepancy 1: `ReconciliationResult` fields **Module guide shows:** ```python @dataclass class ReconciliationResult: plan_id: str resolved_invariants: list[Invariant] conflicts_detected: int conflicts_resolved: int decisions: list[ReconciliationDecision] success: bool ``` **Actual implementation (`reconciliation.py` line 68):** ```python @dataclass(frozen=True) class ReconciliationResult: reconciled_set: InvariantSet conflicts: list[ConflictRecord] enforced_decision_ids: list[str] ``` ## Discrepancy 2: `InvariantReconciliationActor.__init__` signature **Module guide shows:** ```python actor = InvariantReconciliationActor(invariant_service, event_bus, audit_service) ``` **Actual implementation (`reconciliation.py` line 234):** ```python def __init__(self, *, invariant_service: InvariantService, decision_service: DecisionService) -> None: ``` The actor takes `decision_service`, not `event_bus` and `audit_service`. ## Discrepancy 3: `ReconciliationDecision` class The module guide references a `ReconciliationDecision` dataclass with `winner`, `loser`, `rationale`, `timestamp` fields. The actual implementation uses `ConflictRecord` with `key`, `winner`, `losers`, `reason` fields. ## Fix Required Update `docs/modules/invariant-reconciliation.md` to match the actual implementation: - Fix `ReconciliationResult` fields - Fix `InvariantReconciliationActor` constructor signature - Replace `ReconciliationDecision` references with `ConflictRecord` - Update usage examples accordingly ## References - PR #5614 (introduced the inaccurate docs) - `src/cleveragents/actor/reconciliation.py` (authoritative implementation) --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

HAL9000 added this to the v3.8.0 milestone

2026-04-09 10:56:07 +00:00

HAL9000 added the

labels

2026-04-09 10:59:59 +00:00

HAL9000 referenced this issue

2026-04-09 11:08:10 +00:00

[AUTO-SPEC] Specification Update Report (Cycle 6) #5709

HAL9000 referenced this issue

2026-04-09 11:26:46 +00:00

[AUTO-SPEC] Specification Update Report (Cycle 7) #5884

HAL9000 added the

Points

label

2026-04-09 11:33:55 +00:00

HAL9000 commented

2026-04-09 11:40:24 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer