cleveragents/cleveragents-core

Fork 3

Proposal: update specification — fix docs/reference/invariants.md to show 4-tier precedence chain (plan > action > project > global) #5861

New issue

Open

opened 2026-04-09 11:03:14 +00:00 by HAL9000 · 1 comment

HAL9000 commented

2026-04-09 11:03:14 +00:00

Owner

Proposal: Fix Invariant Precedence Chain in Reference Doc

What Changed in the Implementation

PR #5614 merged docs/modules/invariant-reconciliation.md which correctly documents the 4-tier precedence chain: plan > action > project > global. The implementation in src/cleveragents/actor/reconciliation.py also confirms this 4-tier chain (see _SCOPE_PRECEDENCE dict at line 42).

What Spec Section Needs Updating

File: docs/reference/invariants.md
Section: "Merge Precedence"

Current text:

When computing the effective set of invariants for a plan, the precedence chain is:

plan > project > global

- **Plan-level** invariants take highest precedence.
- **Project-level** invariants apply next.
- **Global-level** invariants are lowest precedence.
- **Action-level** invariants are promoted to plan scope when `plan use` is called.

Proposed text:

When computing the effective set of invariants for a plan, the precedence chain is:

plan > action > project > global

- **Plan-level** invariants take highest precedence.
- **Action-level** invariants apply next (action invariants are also promoted to plan scope when `plan use` is called, but they remain resolvable at action scope during reconciliation).
- **Project-level** invariants apply next.
- **Global-level** invariants are lowest precedence.

Rationale

The main specification (docs/specification.md line 92) clearly states: "The runtime precedence chain is four-tier: plan > action > project > global". The reference doc was inconsistent, showing only 3 tiers. The new module guide (PR #5614) correctly shows 4 tiers. This proposal aligns the reference doc with the spec and implementation.

Scope

File affected: docs/reference/invariants.md (Merge Precedence section only)
Change type: Minor documentation correction
Risk: Very low — documentation only, no behavioral change
Breaking changes: None

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

## Proposal: Fix Invariant Precedence Chain in Reference Doc ## What Changed in the Implementation PR #5614 merged `docs/modules/invariant-reconciliation.md` which correctly documents the 4-tier precedence chain: `plan > action > project > global`. The implementation in `src/cleveragents/actor/reconciliation.py` also confirms this 4-tier chain (see `_SCOPE_PRECEDENCE` dict at line 42). ## What Spec Section Needs Updating **File**: `docs/reference/invariants.md` **Section**: "Merge Precedence" **Current text:** ``` When computing the effective set of invariants for a plan, the precedence chain is: plan > project > global - **Plan-level** invariants take highest precedence. - **Project-level** invariants apply next. - **Global-level** invariants are lowest precedence. - **Action-level** invariants are promoted to plan scope when `plan use` is called. ``` **Proposed text:** ``` When computing the effective set of invariants for a plan, the precedence chain is: plan > action > project > global - **Plan-level** invariants take highest precedence. - **Action-level** invariants apply next (action invariants are also promoted to plan scope when `plan use` is called, but they remain resolvable at action scope during reconciliation). - **Project-level** invariants apply next. - **Global-level** invariants are lowest precedence. ``` ## Rationale The main specification (`docs/specification.md` line 92) clearly states: "The runtime precedence chain is four-tier: plan > action > project > global". The reference doc was inconsistent, showing only 3 tiers. The new module guide (PR #5614) correctly shows 4 tiers. This proposal aligns the reference doc with the spec and implementation. ## Scope - **File affected**: `docs/reference/invariants.md` (Merge Precedence section only) - **Change type**: Minor documentation correction - **Risk**: Very low — documentation only, no behavioral change - **Breaking changes**: None --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-updater

HAL9000 added this to the v3.8.0 milestone

2026-04-09 11:03:14 +00:00

HAL9000 added the

labels

2026-04-09 11:06:40 +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 referenced this issue from a commit

2026-04-09 11:37:09 +00:00

docs(reference): fix invariant precedence chain to show 4-tier (plan > action > project > global)

HAL9000 referenced this issue from a pull request that will close it,

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

docs(reference): fix invariant precedence chain to show 4-tier (plan > action > project > global) #5905

HAL9000 added

and removed

labels

2026-04-09 11:43:11 +00:00

HAL9000 commented

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

Author

Owner

Architecture Action Taken

PR #5905 has been created to fix the invariant precedence chain in docs/reference/invariants.md:

Changed plan > project > global to plan > action > project > global
Updated all 4 bullet points to correctly describe each tier
Aligned with docs/specification.md line 92 and the implementation

PR #5905 is awaiting human approval (Needs Feedback label applied).

Automated by CleverAgents Bot
Supervisor: Architecture | Agent: architect | Instance: architect-1

## Architecture Action Taken PR #5905 has been created to fix the invariant precedence chain in `docs/reference/invariants.md`: - Changed `plan > project > global` to `plan > action > project > global` - Updated all 4 bullet points to correctly describe each tier - Aligned with `docs/specification.md` line 92 and the implementation PR #5905 is awaiting human approval (`Needs Feedback` label applied). --- **Automated by CleverAgents Bot** Supervisor: Architecture | Agent: architect | Instance: architect-1

HAL9000 referenced this issue

2026-04-09 11:49:39 +00:00

[AUTO-ARCH] Architecture Review (Cycle 2) #5484

HAL9000 referenced this issue

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

[AUTO-GROOMER] Backlog Grooming Report (Cycle 60) #5850

HAL9000 referenced this issue

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

[AUTO-EVLV] Agent Evolution Report (Cycle 23) #6170

HAL9000 referenced this issue

2026-04-09 17:30:59 +00:00

[AUTO-EVLV] Agent Evolution Report (Cycle 24) #6191