Proposal [AUTO-SPEC-2]: Update spec to reflect invariant reconciliation at every phase boundary (not just Strategize) #9899

Closed
opened 2026-04-15 23:59:30 +00:00 by HAL9000 · 2 comments
Owner

Metadata

  • Commit message: docs(spec): update invariant reconciliation to reflect multi-phase boundary enforcement
  • Branch name: docs/auto-spec-2-invariant-reconciliation-phase-boundary

Background and Context

The specification currently describes the Invariant Reconciliation Actor as operating only at the start of the Strategize phase. However, the implementation enforces invariant reconciliation at every phase boundary — a deliberate safety hardening decision that provides stronger guarantees than single-phase enforcement. The spec needs to be updated to accurately reflect this behavior.

Discrepancy Report

Type: Implementation found a better/more complete approach → spec update needed

Area: Invariants — Plan Lifecycle Phase Enforcement

Current Spec State

The specification describes the Invariant Reconciliation Actor as operating at the start of the Strategize phase:

Strategize: Second phase of the plan lifecycle (following the Action phase). The first phase where active processing occurs. Read-only: the strategy actor produces the initial decision tree — strategy choices, invariant enforcement records, resource selections, child plan blueprints — without modifying any resources.

Invariant: A natural-language constraint on plan execution scoped to global, project, action, or plan level. The runtime precedence chain is four-tier: plan > action > project > global. Exception: global invariants marked non_overridable always win regardless of scope. Reconciled by the Invariant Reconciliation Actor at the start of Strategize; recorded as invariant_enforced decisions that propagate to child plans.

The spec implies invariant reconciliation happens once, at the start of Strategize.

Implementation State

The implementation enforces invariant reconciliation at every phase boundary, not just Strategize:

  • Before Strategize (plan_lifecycle_service.py:399) — Initial reconciliation
  • Before Execute (plan_lifecycle_service.py:1391) — Re-reconciliation before execution begins
  • Before Apply (plan_lifecycle_service.py:1563) — Re-reconciliation before applying changes
  • After Apply (plan_lifecycle_service.py:1770) — Final reconciliation check

This is a deliberate hardening decision: invariants are re-checked at each phase transition to catch any invariants that may have been added or modified between phases, and to ensure that the plan remains compliant throughout its entire lifecycle.

Source: src/cleveragents/application/services/plan_lifecycle_service.py:399,1391,1563,1770

Proposed Spec Change

Update the §Invariant glossary entry and the §Plan Lifecycle section to reflect that invariant reconciliation occurs at every phase boundary:

  1. Update the Invariant glossary entry:

    Reconciled by the Invariant Reconciliation Actor at each phase boundary (before Strategize, Execute, and Apply); recorded as invariant_enforced decisions that propagate to child plans.

  2. Add a note in the plan lifecycle section explaining that invariants are re-evaluated at each phase transition to ensure continuous compliance throughout the plan lifecycle.

  3. Document that this multi-phase enforcement catches invariants added or modified between phases.

Classification

Implementation found a better approach — Multi-phase invariant enforcement is a deliberate safety hardening that provides stronger guarantees than single-phase enforcement. The spec should be updated to accurately describe this behavior.

Expected Behavior

The specification accurately documents that invariant reconciliation occurs at every phase boundary (before Strategize, Execute, and Apply), not just at the start of Strategize. Readers of the spec understand the full enforcement model and the rationale for multi-phase checking.

Acceptance Criteria

  • docs/specification.md Invariant glossary entry updated to reflect enforcement at every phase boundary
  • Plan lifecycle section updated to document multi-phase invariant reconciliation
  • The enforcement points (before Strategize, Execute, Apply) are documented
  • The rationale for multi-phase enforcement (catching invariants added/modified between phases) is documented

Subtasks

  • Review current docs/specification.md Invariant glossary entry
  • Update Invariant glossary entry to reflect multi-phase boundary enforcement
  • Update Plan Lifecycle section to document re-evaluation at each phase transition
  • Add rationale note explaining why multi-phase enforcement is used
  • Verify updated spec accurately matches implementation in plan_lifecycle_service.py

Definition of Done

This issue should be closed when:

  • The docs/specification.md Invariant glossary entry accurately describes enforcement at every phase boundary
  • The Plan Lifecycle section documents multi-phase invariant reconciliation with the specific enforcement points
  • The spec change has been reviewed and merged

Automated by CleverAgents Bot
Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor


Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Commit message**: `docs(spec): update invariant reconciliation to reflect multi-phase boundary enforcement` - **Branch name**: `docs/auto-spec-2-invariant-reconciliation-phase-boundary` ## Background and Context The specification currently describes the Invariant Reconciliation Actor as operating only at the start of the **Strategize** phase. However, the implementation enforces invariant reconciliation at **every phase boundary** — a deliberate safety hardening decision that provides stronger guarantees than single-phase enforcement. The spec needs to be updated to accurately reflect this behavior. ## Discrepancy Report **Type**: Implementation found a better/more complete approach → spec update needed **Area**: Invariants — Plan Lifecycle Phase Enforcement ### Current Spec State The specification describes the Invariant Reconciliation Actor as operating at the start of the **Strategize** phase: > **Strategize**: Second phase of the plan lifecycle (following the Action phase). The first phase where active processing occurs. Read-only: the strategy actor produces the initial decision tree — strategy choices, **invariant enforcement records**, resource selections, child plan blueprints — without modifying any resources. > **Invariant**: A natural-language constraint on plan execution scoped to global, project, action, or plan level. The runtime precedence chain is four-tier: plan > action > project > global. Exception: global invariants marked `non_overridable` always win regardless of scope. **Reconciled by the Invariant Reconciliation Actor at the start of Strategize**; recorded as `invariant_enforced` decisions that propagate to child plans. The spec implies invariant reconciliation happens once, at the start of Strategize. ### Implementation State The implementation enforces invariant reconciliation at **every phase boundary**, not just Strategize: - **Before Strategize** (`plan_lifecycle_service.py:399`) — Initial reconciliation - **Before Execute** (`plan_lifecycle_service.py:1391`) — Re-reconciliation before execution begins - **Before Apply** (`plan_lifecycle_service.py:1563`) — Re-reconciliation before applying changes - **After Apply** (`plan_lifecycle_service.py:1770`) — Final reconciliation check This is a deliberate hardening decision: invariants are re-checked at each phase transition to catch any invariants that may have been added or modified between phases, and to ensure that the plan remains compliant throughout its entire lifecycle. Source: `src/cleveragents/application/services/plan_lifecycle_service.py:399,1391,1563,1770` ### Proposed Spec Change Update the §Invariant glossary entry and the §Plan Lifecycle section to reflect that invariant reconciliation occurs at **every phase boundary**: 1. Update the Invariant glossary entry: > Reconciled by the Invariant Reconciliation Actor **at each phase boundary** (before Strategize, Execute, and Apply); recorded as `invariant_enforced` decisions that propagate to child plans. 2. Add a note in the plan lifecycle section explaining that invariants are re-evaluated at each phase transition to ensure continuous compliance throughout the plan lifecycle. 3. Document that this multi-phase enforcement catches invariants added or modified between phases. ### Classification **Implementation found a better approach** — Multi-phase invariant enforcement is a deliberate safety hardening that provides stronger guarantees than single-phase enforcement. The spec should be updated to accurately describe this behavior. ## Expected Behavior The specification accurately documents that invariant reconciliation occurs at every phase boundary (before Strategize, Execute, and Apply), not just at the start of Strategize. Readers of the spec understand the full enforcement model and the rationale for multi-phase checking. ## Acceptance Criteria - [ ] `docs/specification.md` Invariant glossary entry updated to reflect enforcement at every phase boundary - [ ] Plan lifecycle section updated to document multi-phase invariant reconciliation - [ ] The enforcement points (before Strategize, Execute, Apply) are documented - [ ] The rationale for multi-phase enforcement (catching invariants added/modified between phases) is documented ## Subtasks - [ ] Review current `docs/specification.md` Invariant glossary entry - [ ] Update Invariant glossary entry to reflect multi-phase boundary enforcement - [ ] Update Plan Lifecycle section to document re-evaluation at each phase transition - [ ] Add rationale note explaining why multi-phase enforcement is used - [ ] Verify updated spec accurately matches implementation in `plan_lifecycle_service.py` ## Definition of Done This issue should be closed when: - The `docs/specification.md` Invariant glossary entry accurately describes enforcement at every phase boundary - The Plan Lifecycle section documents multi-phase invariant reconciliation with the specific enforcement points - The spec change has been reviewed and merged --- **Automated by CleverAgents Bot** Supervisor: Spec Evolution | Agent: spec-update-pool-supervisor --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.9.0 milestone 2026-04-16 09:38:26 +00:00
Author
Owner

Grooming Analysis

Quality Issues Found

  1. Missing Labels (4 required):

    • State/Unverified — Issue is in open/unverified state
    • Type/Spec — This is a specification update issue
    • Priority/High — Spec update for safety-critical invariant reconciliation
    • MoSCoW/Should have — Important spec update but not blocking
  2. Missing Milestone:

    • Assigned to v3.9.0 — Appropriate for spec documentation updates

Exemption Check

This issue is titled "Proposal [AUTO-SPEC-2]:..." which starts with "Proposal", not "[AUTO-". Per CONTRIBUTING.md rules, it is NOT exempt from label requirements and requires full label compliance.

Fixes Applied

Applied all 4 required labels:

  • State/Unverified
  • Type/Spec
  • Priority/High
  • MoSCoW/Should have

Set milestone to v3.9.0


Automated by CleverAgents Bot
Supervisor: Grooming | Agent: grooming-pool-supervisor | Worker: [AUTO-GROOM-9899]

## Grooming Analysis ### Quality Issues Found 1. **Missing Labels** (4 required): - ✅ State/Unverified — Issue is in open/unverified state - ✅ Type/Spec — This is a specification update issue - ✅ Priority/High — Spec update for safety-critical invariant reconciliation - ✅ MoSCoW/Should have — Important spec update but not blocking 2. **Missing Milestone**: - ✅ Assigned to v3.9.0 — Appropriate for spec documentation updates ### Exemption Check This issue is titled "Proposal [AUTO-SPEC-2]:..." which starts with "Proposal", not "[AUTO-". Per CONTRIBUTING.md rules, it is **NOT exempt** from label requirements and requires full label compliance. ### Fixes Applied ✅ Applied all 4 required labels: - State/Unverified - Type/Spec - Priority/High - MoSCoW/Should have ✅ Set milestone to v3.9.0 --- **Automated by CleverAgents Bot** Supervisor: Grooming | Agent: grooming-pool-supervisor | Worker: [AUTO-GROOM-9899]
Author
Owner

[GROOMED]


Automated by CleverAgents Bot
Supervisor: Grooming | Agent: grooming-pool-supervisor | Worker: [AUTO-GROOM-9899]

[GROOMED] --- **Automated by CleverAgents Bot** Supervisor: Grooming | Agent: grooming-pool-supervisor | Worker: [AUTO-GROOM-9899]
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#9899
No description provided.