feat(invariant): enforce invariants during Strategize phase with violation blocking #9323

Open
opened 2026-04-14 14:49:38 +00:00 by HAL9000 · 1 comment
Owner

Metadata

  • Branch: feat/invariant-enforcement-strategize
  • Commit message: feat(invariant): enforce invariants during Strategize phase with violation blocking
  • Milestone: v3.2.0

Background and Context

The v3.2.0 milestone (M3: Decisions + Validations + Invariants) requires that invariants be enforced during the Strategize phase. Invariants are user-defined constraints that govern how the agent may approach a plan — they act as guardrails that prevent the LLM from taking approaches that violate project, plan, or global policies.

Currently, the Strategize phase has no mechanism to evaluate active invariants before or during LLM calls. This means the agent can propose approaches that directly contradict user-defined constraints, leading to wasted compute, incorrect plans, and user frustration.

Invariants must be scoped at three levels with a clear precedence hierarchy:

  • Plan-level invariants apply only to a specific plan
  • Project-level invariants apply to all plans within a project
  • Global-level invariants apply across all projects

The enforcement system must intercept LLM calls during Strategize, evaluate all active invariants in precedence order (plan > project > global), and block any approach that violates them — surfacing a clear, actionable error to the user.


Expected Behavior

  1. Invariant storage: Invariants are persisted to the database with scope (plan|project|global), source_id (plan ID or project ID, nullable for global), and text fields.
  2. CLI management:
    • agents invariant add --scope plan|project|global "text" — creates a new invariant
    • agents invariant list [--plan <ID>] [--project <ID>] — lists effective invariants with their precedence level
    • agents invariant remove <ID> — removes an invariant by ID
  3. Enforcement during Strategize: Before each LLM call in the Strategize phase, all active invariants are evaluated against the proposed approach. If any invariant is violated, the LLM call is blocked and the violation is surfaced to the user.
  4. User override: The user may bypass invariant enforcement with --force flag, which prompts for explicit confirmation before proceeding.
  5. Precedence display: agents invariant list shows invariants grouped by scope with clear precedence indicators (plan > project > global).

Acceptance Criteria

  • agents invariant add --scope global "Never use deprecated APIs" persists a global invariant to the database
  • agents invariant add --scope project "Always use async/await" persists a project-scoped invariant
  • agents invariant add --scope plan "Do not modify the auth module" persists a plan-scoped invariant
  • agents invariant list displays all effective invariants for the current context with scope labels
  • agents invariant list --plan <ID> shows invariants effective for a specific plan (plan + project + global)
  • agents invariant remove <ID> removes the specified invariant and confirms deletion
  • Invariants are stored in the database with id, scope, source_id, text, created_at fields
  • Before each LLM call during Strategize, all active invariants are evaluated in precedence order (plan > project > global)
  • A violated invariant blocks the LLM call and surfaces a clear error message identifying which invariant was violated and why
  • Running agents strategize with --force when an invariant is violated prompts for confirmation and proceeds if confirmed
  • Invariant evaluation is logged at DEBUG level for observability
  • Unit tests cover invariant CRUD operations with ≥ 97% coverage
  • Integration tests cover enforcement blocking and --force override flow
  • All existing Strategize tests continue to pass

Subtasks

  • DB schema: Add invariants table migration with id, scope (enum: plan|project|global), source_id (nullable FK), text, created_at
  • Model: Implement Invariant domain model and repository (InvariantRepository) with add, list, remove, list_effective methods
  • CLI — invariant add: Implement agents invariant add --scope <scope> <text> command with validation
  • CLI — invariant list: Implement agents invariant list [--plan <ID>] [--project <ID>] with precedence grouping display
  • CLI — invariant remove: Implement agents invariant remove <ID> with confirmation prompt
  • Invariant evaluator: Implement InvariantEvaluator service that takes a proposed approach and a list of active invariants and returns violations
  • Strategize hook: Integrate InvariantEvaluator into the Strategize phase pre-LLM-call hook; block on violation
  • Violation error: Implement InvariantViolationError with structured violation details (invariant ID, scope, text, reason)
  • --force flag: Add --force flag to agents strategize that bypasses invariant enforcement after user confirmation
  • Precedence resolution: Implement list_effective(plan_id) that merges plan + project + global invariants in correct precedence order
  • Unit tests: Write unit tests for InvariantRepository, InvariantEvaluator, and CLI commands
  • Integration tests: Write integration tests for end-to-end enforcement flow (add invariant → strategize → violation blocked → force override)
  • Documentation: Update CLI help text and any relevant spec/ADR references

Definition of Done

  • All acceptance criteria checkboxes are checked
  • agents invariant add, agents invariant list, and agents invariant remove commands are functional and tested
  • Invariant enforcement is active during Strategize and blocks violating LLM calls
  • --force override works with user confirmation
  • Database migration is included and reversible
  • Test coverage for new code is ≥ 97%
  • nox passes with no regressions
  • PR is reviewed and merged to main

Automated by CleverAgents Bot
Agent: new-issue-creator

## Metadata - **Branch:** `feat/invariant-enforcement-strategize` - **Commit message:** `feat(invariant): enforce invariants during Strategize phase with violation blocking` - **Milestone:** v3.2.0 --- ## Background and Context The v3.2.0 milestone (M3: Decisions + Validations + Invariants) requires that invariants be enforced during the Strategize phase. Invariants are user-defined constraints that govern how the agent may approach a plan — they act as guardrails that prevent the LLM from taking approaches that violate project, plan, or global policies. Currently, the Strategize phase has no mechanism to evaluate active invariants before or during LLM calls. This means the agent can propose approaches that directly contradict user-defined constraints, leading to wasted compute, incorrect plans, and user frustration. Invariants must be scoped at three levels with a clear precedence hierarchy: - **Plan-level** invariants apply only to a specific plan - **Project-level** invariants apply to all plans within a project - **Global-level** invariants apply across all projects The enforcement system must intercept LLM calls during Strategize, evaluate all active invariants in precedence order (plan > project > global), and block any approach that violates them — surfacing a clear, actionable error to the user. --- ## Expected Behavior 1. **Invariant storage**: Invariants are persisted to the database with `scope` (plan|project|global), `source_id` (plan ID or project ID, nullable for global), and `text` fields. 2. **CLI management**: - `agents invariant add --scope plan|project|global "text"` — creates a new invariant - `agents invariant list [--plan <ID>] [--project <ID>]` — lists effective invariants with their precedence level - `agents invariant remove <ID>` — removes an invariant by ID 3. **Enforcement during Strategize**: Before each LLM call in the Strategize phase, all active invariants are evaluated against the proposed approach. If any invariant is violated, the LLM call is blocked and the violation is surfaced to the user. 4. **User override**: The user may bypass invariant enforcement with `--force` flag, which prompts for explicit confirmation before proceeding. 5. **Precedence display**: `agents invariant list` shows invariants grouped by scope with clear precedence indicators (plan > project > global). --- ## Acceptance Criteria - [ ] `agents invariant add --scope global "Never use deprecated APIs"` persists a global invariant to the database - [ ] `agents invariant add --scope project "Always use async/await"` persists a project-scoped invariant - [ ] `agents invariant add --scope plan "Do not modify the auth module"` persists a plan-scoped invariant - [ ] `agents invariant list` displays all effective invariants for the current context with scope labels - [ ] `agents invariant list --plan <ID>` shows invariants effective for a specific plan (plan + project + global) - [ ] `agents invariant remove <ID>` removes the specified invariant and confirms deletion - [ ] Invariants are stored in the database with `id`, `scope`, `source_id`, `text`, `created_at` fields - [ ] Before each LLM call during Strategize, all active invariants are evaluated in precedence order (plan > project > global) - [ ] A violated invariant blocks the LLM call and surfaces a clear error message identifying which invariant was violated and why - [ ] Running `agents strategize` with `--force` when an invariant is violated prompts for confirmation and proceeds if confirmed - [ ] Invariant evaluation is logged at DEBUG level for observability - [ ] Unit tests cover invariant CRUD operations with ≥ 97% coverage - [ ] Integration tests cover enforcement blocking and `--force` override flow - [ ] All existing Strategize tests continue to pass --- ## Subtasks - [ ] **DB schema**: Add `invariants` table migration with `id`, `scope` (enum: plan|project|global), `source_id` (nullable FK), `text`, `created_at` - [ ] **Model**: Implement `Invariant` domain model and repository (`InvariantRepository`) with `add`, `list`, `remove`, `list_effective` methods - [ ] **CLI — `invariant add`**: Implement `agents invariant add --scope <scope> <text>` command with validation - [ ] **CLI — `invariant list`**: Implement `agents invariant list [--plan <ID>] [--project <ID>]` with precedence grouping display - [ ] **CLI — `invariant remove`**: Implement `agents invariant remove <ID>` with confirmation prompt - [ ] **Invariant evaluator**: Implement `InvariantEvaluator` service that takes a proposed approach and a list of active invariants and returns violations - [ ] **Strategize hook**: Integrate `InvariantEvaluator` into the Strategize phase pre-LLM-call hook; block on violation - [ ] **Violation error**: Implement `InvariantViolationError` with structured violation details (invariant ID, scope, text, reason) - [ ] **`--force` flag**: Add `--force` flag to `agents strategize` that bypasses invariant enforcement after user confirmation - [ ] **Precedence resolution**: Implement `list_effective(plan_id)` that merges plan + project + global invariants in correct precedence order - [ ] **Unit tests**: Write unit tests for `InvariantRepository`, `InvariantEvaluator`, and CLI commands - [ ] **Integration tests**: Write integration tests for end-to-end enforcement flow (add invariant → strategize → violation blocked → force override) - [ ] **Documentation**: Update CLI help text and any relevant spec/ADR references --- ## Definition of Done - All acceptance criteria checkboxes are checked - `agents invariant add`, `agents invariant list`, and `agents invariant remove` commands are functional and tested - Invariant enforcement is active during Strategize and blocks violating LLM calls - `--force` override works with user confirmation - Database migration is included and reversible - Test coverage for new code is ≥ 97% - `nox` passes with no regressions - PR is reviewed and merged to `main` --- **Automated by CleverAgents Bot** Agent: new-issue-creator
HAL9000 added this to the v3.2.0 milestone 2026-04-14 14:51:19 +00:00
Author
Owner

Triage: Verified [AUTO-OWNR-1]

Valid feature: Invariant enforcement during Strategize is explicitly listed in the v3.2.0 milestone acceptance criteria: "Invariants are enforced during strategize." This issue provides a comprehensive specification for the Invariant domain model, InvariantRepository, CLI commands (add/list/remove), InvariantEvaluator service, Strategize phase integration, and --force override.

The invariant system is a core safety feature that prevents the LLM from taking approaches that violate user-defined constraints. Without it, the agent can propose plans that directly contradict project policies.

Assigning to v3.2.0 as invariant enforcement is explicitly required by the M3 acceptance criteria. Priority High — core M3 deliverable.

MoSCoW: Must Have — invariant enforcement is explicitly required by the v3.2.0 milestone acceptance criteria. The milestone cannot be considered complete without it.


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

✅ **Triage: Verified** [AUTO-OWNR-1] Valid feature: Invariant enforcement during Strategize is explicitly listed in the v3.2.0 milestone acceptance criteria: "Invariants are enforced during strategize." This issue provides a comprehensive specification for the `Invariant` domain model, `InvariantRepository`, CLI commands (add/list/remove), `InvariantEvaluator` service, Strategize phase integration, and `--force` override. The invariant system is a core safety feature that prevents the LLM from taking approaches that violate user-defined constraints. Without it, the agent can propose plans that directly contradict project policies. Assigning to **v3.2.0** as invariant enforcement is explicitly required by the M3 acceptance criteria. Priority **High** — core M3 deliverable. MoSCoW: **Must Have** — invariant enforcement is explicitly required by the v3.2.0 milestone acceptance criteria. The milestone cannot be considered complete without it. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner-pool-supervisor
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#9323
No description provided.