cleveragents/cleveragents-core

Fork 3

UAT: `InvariantScope` docstring omits ACTION from precedence chain — misleading documentation #4828

New issue

Open

opened 2026-04-08 19:54:48 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-08 19:54:48 +00:00

Owner

Bug Report

Feature Area: Invariants — four-tier precedence chain documentation

What Was Tested

Code-level analysis of src/cleveragents/domain/models/core/invariant.py docstrings against the specification.

Expected Behavior (from spec)

The specification (line 92) defines a four-tier precedence chain:

The runtime precedence chain is four-tier: plan > action > project > global.

All docstrings describing the precedence chain should reflect this four-tier order.

Actual Behavior

InvariantScope class docstring (lines 39–44) states:

class InvariantScope(StrEnum):
    """Scope at which an invariant applies.

    Precedence (highest to lowest): PLAN > PROJECT > GLOBAL.
    ACTION invariants are promoted to PLAN scope at ``plan use`` time.
    """

This is incorrect in two ways:

The precedence chain listed is only three tiers: PLAN > PROJECT > GLOBAL — ACTION is missing
The note "ACTION invariants are promoted to PLAN scope at plan use time" is misleading — while action invariants are promoted at plan use time, they can also be stored directly as ACTION-scoped invariants via agents invariant add --action and are handled as a distinct tier by the InvariantReconciliationActor

Module-level docstring (lines 1–28) also states:

The runtime precedence chain is:

    plan > project > global

Again, ACTION is missing from the stated precedence chain.

InvariantSet.merge docstring (lines 143–161) says:

Merge invariants respecting plan > project > global precedence.

This is also missing ACTION.

Code Locations

src/cleveragents/domain/models/core/invariant.py lines 1–28 (module docstring)
src/cleveragents/domain/models/core/invariant.py lines 39–44 (InvariantScope docstring)
src/cleveragents/domain/models/core/invariant.py lines 143–161 (InvariantSet.merge docstring)

Impact

Developers reading the invariant.py module will believe the precedence chain is three-tier (plan > project > global) and may incorrectly implement code that skips the action tier. This is a documentation bug that compounds the functional bug in merge_invariants (see issue #4825).

Suggested Fix

Update all three docstrings to reflect the correct four-tier chain:

Module docstring: plan > action > project > global
InvariantScope docstring: PLAN > ACTION > PROJECT > GLOBAL
InvariantSet.merge docstring: plan > action > project > global

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

## Bug Report **Feature Area:** Invariants — four-tier precedence chain documentation ### What Was Tested Code-level analysis of `src/cleveragents/domain/models/core/invariant.py` docstrings against the specification. ### Expected Behavior (from spec) The specification (line 92) defines a **four-tier** precedence chain: > The runtime precedence chain is four-tier: **plan > action > project > global**. All docstrings describing the precedence chain should reflect this four-tier order. ### Actual Behavior **`InvariantScope` class docstring (lines 39–44)** states: ```python class InvariantScope(StrEnum): """Scope at which an invariant applies. Precedence (highest to lowest): PLAN > PROJECT > GLOBAL. ACTION invariants are promoted to PLAN scope at ``plan use`` time. """ ``` This is incorrect in two ways: 1. The precedence chain listed is only three tiers: `PLAN > PROJECT > GLOBAL` — ACTION is missing 2. The note "ACTION invariants are promoted to PLAN scope at `plan use` time" is misleading — while action invariants *are* promoted at `plan use` time, they can also be stored directly as `ACTION`-scoped invariants via `agents invariant add --action` and are handled as a distinct tier by the `InvariantReconciliationActor` **Module-level docstring (lines 1–28)** also states: ``` The runtime precedence chain is: plan > project > global ``` Again, ACTION is missing from the stated precedence chain. **`InvariantSet.merge` docstring (lines 143–161)** says: ``` Merge invariants respecting plan > project > global precedence. ``` This is also missing ACTION. ### Code Locations - `src/cleveragents/domain/models/core/invariant.py` lines 1–28 (module docstring) - `src/cleveragents/domain/models/core/invariant.py` lines 39–44 (`InvariantScope` docstring) - `src/cleveragents/domain/models/core/invariant.py` lines 143–161 (`InvariantSet.merge` docstring) ### Impact Developers reading the `invariant.py` module will believe the precedence chain is three-tier (plan > project > global) and may incorrectly implement code that skips the action tier. This is a documentation bug that compounds the functional bug in `merge_invariants` (see issue #4825). ### Suggested Fix Update all three docstrings to reflect the correct four-tier chain: - Module docstring: `plan > action > project > global` - `InvariantScope` docstring: `PLAN > ACTION > PROJECT > GLOBAL` - `InvariantSet.merge` docstring: `plan > action > project > global` --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 referenced this issue

2026-04-08 19:56:15 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:12:39 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 referenced this issue

2026-04-08 20:22:25 +00:00

[Automated] CleverAgents Build Session - 2026-04-08 #4799

HAL9000 added the

labels

2026-04-08 22:59:49 +00:00

HAL9000 commented

2026-04-09 03:02:38 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — spec compliance bug identified by UAT testing
Story Points: 3 (M) — targeted fix to align implementation with spec
MoSCoW: Must Have — spec compliance is required for correct system behavior

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — spec compliance bug identified by UAT testing - **Story Points**: 3 (M) — targeted fix to align implementation with spec - **MoSCoW**: Must Have — spec compliance is required for correct system behavior --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 added

and removed

labels

2026-04-09 03:02:45 +00:00

HAL9000 added this to the v3.5.0 milestone