cleveragents/cleveragents-core

Fork 3

feat(acms): context policies configurable with view-specific settings #846

New issue

Closed

opened 2026-03-13 21:58:45 +00:00 by freemo · 1 comment

freemo commented

2026-03-13 21:58:45 +00:00

Owner

Metadata

Commit Message: feat(acms): context policies configurable with view-specific settings
Branch: feature/m5-context-policies

Background

M5 (v3.4.0) acceptance criterion: ACMS context policies must be configurable with view-specific settings per phase. Each plan phase (Strategize, Execute, Apply) can have its own context view with different size limits, included/excluded patterns, and scoping rules. Views inherit from parent phases when not explicitly set.

Per the E2E suite (m5_e2e_verification.robot lines 57, 67), the tests verify setting context policies with default and phase-specific views, reading them back, and confirming the view inheritance chain (default -> strategize -> execute -> apply).

Expected Behavior

Context policies can be set with view-specific settings for each plan phase
context policy set CLI command accepts per-phase view configuration
context policy show CLI command displays the resolved policy with all views
Phase views inherit from the nearest ancestor when not explicitly configured
Clearing a phase view causes fallback to the parent phase view

Acceptance Criteria

ContextPolicy model supports per-phase view configuration
context policy set CLI command works with default and phase-specific views
context policy show CLI command displays resolved policies
View inheritance chain (default -> strategize -> execute -> apply) works correctly
Robot E2E tests ACMS Context Policy Set And Show and ACMS Phase View Inheritance Chain pass
Unit tests cover: set/show round-trip, inheritance fallback, clear + fallback

Supporting Information

E2E tests: robot/m5_e2e_verification.robot lines 57, 67
Related: ACMS architecture in docs/specification.md

Subtasks

Implement ContextPolicy model with per-phase view support
Implement context policy set CLI command
Implement context policy show CLI command
Implement view inheritance chain resolution
Implement view clearing with fallback behavior
Tests (Behave): Add scenarios for policy configuration edge cases
Tests (Robot): Verify E2E acceptance tests pass
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.

Note: All functionality was delivered incrementally through prior feature branches already merged to master. See implementation journal comment for full audit trail.

## Metadata - **Commit Message**: `feat(acms): context policies configurable with view-specific settings` - **Branch**: `feature/m5-context-policies` ## Background M5 (v3.4.0) acceptance criterion: ACMS context policies must be configurable with view-specific settings per phase. Each plan phase (Strategize, Execute, Apply) can have its own context view with different size limits, included/excluded patterns, and scoping rules. Views inherit from parent phases when not explicitly set. Per the E2E suite (`m5_e2e_verification.robot` lines 57, 67), the tests verify setting context policies with default and phase-specific views, reading them back, and confirming the view inheritance chain (default -> strategize -> execute -> apply). ## Expected Behavior 1. Context policies can be set with view-specific settings for each plan phase 2. `context policy set` CLI command accepts per-phase view configuration 3. `context policy show` CLI command displays the resolved policy with all views 4. Phase views inherit from the nearest ancestor when not explicitly configured 5. Clearing a phase view causes fallback to the parent phase view ## Acceptance Criteria - [x] `ContextPolicy` model supports per-phase view configuration - [x] `context policy set` CLI command works with default and phase-specific views - [x] `context policy show` CLI command displays resolved policies - [x] View inheritance chain (default -> strategize -> execute -> apply) works correctly - [x] Robot E2E tests `ACMS Context Policy Set And Show` and `ACMS Phase View Inheritance Chain` pass - [x] Unit tests cover: set/show round-trip, inheritance fallback, clear + fallback ## Supporting Information - E2E tests: `robot/m5_e2e_verification.robot` lines 57, 67 - Related: ACMS architecture in `docs/specification.md` ## Subtasks - [x] Implement `ContextPolicy` model with per-phase view support - [x] Implement `context policy set` CLI command - [x] Implement `context policy show` CLI command - [x] Implement view inheritance chain resolution - [x] Implement view clearing with fallback behavior - [x] Tests (Behave): Add scenarios for policy configuration edge cases - [x] Tests (Robot): Verify E2E acceptance tests pass - [x] Verify coverage >=97% via `nox -s coverage_report` - [x] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. **Note**: All functionality was delivered incrementally through prior feature branches already merged to master. See implementation journal comment for full audit trail.

freemo added the

labels

2026-03-13 21:59:42 +00:00

freemo added this to the v3.4.0 milestone

2026-03-13 21:59:47 +00:00

aditya was assigned by freemo

2026-03-14 04:27:00 +00:00

aditya added

and removed

labels

2026-03-23 12:27:45 +00:00

aditya commented

2026-03-24 09:50:36 +00:00

Member

Implementation Journal — Closing as Already Delivered

Summary

All functionality described in this issue was implemented incrementally through prior feature branches and is already merged to master. No new branch or commit is required. This comment documents the full audit trail.

1. Domain Model — `ProjectContextPolicy` + `ContextView`

Module: cleveragents.domain.models.core.context_policy
File: src/cleveragents/domain/models/core/context_policy.py (173 lines)
Delivered by: commit 5480cd36 (feat(project): add context policy model) — 2026-02-17

VALID_PHASES = frozenset({"default", "strategize", "execute", "apply"})
_INHERITANCE_CHAIN dict defining view resolution: default → strategize → execute → apply
ContextView (Pydantic BaseModel): include_resources, exclude_resources, include_paths, exclude_paths, max_file_size, max_total_size — all with field validators
ProjectContextPolicy (Pydantic BaseModel): default_view, strategize_view, execute_view, apply_view
resolve_view(phase) method implementing the full inheritance chain with fallback
Exported from domain.models.core.__init__ as ContextView and ProjectContextPolicy

Design decisions:

Inheritance chain is a dict lookup (_INHERITANCE_CHAIN), not a linked list, for O(1) resolution with known fixed phases
Views are Optional[ContextView] — None means "inherit from parent"
resolve_view() walks the chain until a non-None view is found, falling back to an empty ContextView() if the entire chain is None

2. CLI Commands — `context policy set` / `context policy show`

Module: cleveragents.cli.commands.project_context
File: src/cleveragents/cli/commands/project_context.py (1111 lines)
Delivered by: commit a8558f13 (feat(cli): add project context commands) — 2026-02-17, then extended by ff42d59d (feat(cli): wire project context CLI stubs to ACMS pipeline) — 2026-03-03

Four commands fully implemented:

agents project context set — persists per-phase view configuration with all options: --view, --include-resource, --exclude-resource, --include-path, --exclude-path, --max-file-size, --max-total-size, --clear, plus 12 ACMS pipeline options
agents project context show — displays active policy with optional --view for phase-specific resolution; supports rich/json/yaml/plain output
agents project context inspect — queries ACMS tier service for scoped metrics and fragments
agents project context simulate — dry-run context assembly with budget tracking

Persistence: SQL helpers (_read_policy, _write_policy, _save_policy_json, _load_policy_json) read/write context_policy_json column on ns_projects table.

Bug fixes applied:

session.flush() → session.commit() — policy changes were silently lost on session.close() (fixed in cbf8bcc9, issue #745)
contextlib.suppress rollback wrapper to prevent masking original commit exceptions (same commit)
--execution-env-priority flag added via commit d9c61e28 (issue #1079)

3. View Inheritance Chain Resolution

Method: ProjectContextPolicy.resolve_view(phase) in context_policy.py

The inheritance chain is: default → strategize → execute → apply

Calling resolve_view("apply") checks apply_view; if None, checks execute_view; if None, checks strategize_view; if None, checks default_view; if None, returns empty ContextView()
Clearing a phase view (setting it to None) correctly causes fallback to the nearest ancestor view
Invalid phase names raise ValueError — validated against VALID_PHASES

4. Tests — Behave BDD Unit Tests (20+ scenarios)

File: features/consolidated_context.feature (238 lines, lines 69–228 for context policy scenarios)
Steps: features/steps/project_context_policy_steps.py (347 lines)

Scenarios cover:

Empty policy defaults
View inheritance (6 scenarios): strategize from default, execute from strategize, apply from execute, and full chain
Override isolation — setting one phase doesn't affect others
Invalid phase names → ValueError
Include/exclude resource patterns
Include/exclude path patterns
Size limit validation (7 scenarios): zero, negative, valid, None allowed
JSON serialization round-trip
model_dump key verification

Additional ACMS smoke test scenarios:
File: features/m5_acms_smoke.feature (155 lines) — context policy resolution, budget enforcement, CLI commands

5. Tests — Robot Framework E2E (5 test cases)

File: robot/m5_e2e_verification.robot (lines 300–351)
Helper: robot/helper_m5_e2e_verification.py (725 lines)
Delivered by: commit fd1612c3 (test(e2e): verify M5 success criteria) — 2026-02-26

Test Case	What It Verifies
`ACMS Context Policy Set And Show`	Sets policy with default + strategize views, reads back, verifies round-trip
`ACMS Phase View Inheritance Chain`	`default → strategize → execute → apply` inheritance
`ACMS Scoped Context Output Per Phase`	Narrowing size limits across phases
`Context Policy Clear And Inheritance Fallback`	Clearing a phase view → fallback to parent
`Context View Validation Rules`	Zero/negative limits rejected, None allowed, invalid phases → ValueError

Additional E2E coverage added in robot/e2e/m5_acceptance.robot (21 test cases) via commit cbf8bcc9 (issue #745).

6. Budget Enforcement Extension

Delivered by: commit 3c0d8397 (feat(acms): budget enforcement with max_file_size and max_total_size constraints) — 2026-03-23

This commit (issue #847, the sibling issue) added enforcement logic on top of the ContextView fields defined here:

BudgetViolation and BudgetEnforcementResult frozen models
enforce_size_budget() function filtering fragments against max_file_size / max_total_size
Wired into both ACMSPipeline.assemble() and ContextAssemblyPipeline.assemble()
7 additional Behave scenarios

7. Quality Gates (as of latest master)

Per commit cbf8bcc9 quality gate results:

lint: PASS
typecheck: PASS (0 errors)
unit_tests: 393/393 features, 11,210+ scenarios
integration_tests: 1,576/1,576
coverage: 98% (threshold: 97%)

Per commit 3c0d8397 quality gate results:

unit_tests: 12,237 scenarios PASS
integration_tests: 1,672 tests PASS
coverage: 98%

8. Rationale for Closing Without New Branch

All acceptance criteria code exists on master. The work was delivered incrementally through the following commit chain:

5480cd36 — domain model (ProjectContextPolicy, ContextView, resolve_view)
a8558f13 — CLI commands (context set, context show)
ff42d59d — ACMS pipeline wiring for CLI commands
fd1612c3 — Robot E2E tests for context policies
cbf8bcc9 — additional E2E acceptance tests + production bug fixes
3c0d8397 — budget enforcement extending the context view fields
d9c61e28 — --execution-env-priority flag addition

Creating a new branch feature/m5-context-policies from current master would produce a zero-diff PR since all code is already merged. The issue is being closed as already delivered.

Acceptance Criteria Cross-Reference

Criterion	Status	Evidence
`ContextPolicy` model supports per-phase view configuration	✅	`context_policy.py` — `ProjectContextPolicy` with 4 phase views
`context policy set` CLI command works with default and phase-specific views	✅	`project_context.py` `context_set()` with `--view` option
`context policy show` CLI command displays resolved policies	✅	`project_context.py` `context_show()` with phase resolution
View inheritance chain works correctly	✅	`resolve_view()` method with `_INHERITANCE_CHAIN` lookup
Robot E2E tests pass	✅	5 dedicated tests in `m5_e2e_verification.robot` + 21 in `m5_acceptance.robot`
Unit tests cover set/show round-trip, inheritance fallback, clear + fallback	✅	20+ Behave scenarios in `consolidated_context.feature`

## Implementation Journal — Closing as Already Delivered ### Summary All functionality described in this issue was implemented incrementally through prior feature branches and is already merged to `master`. No new branch or commit is required. This comment documents the full audit trail. --- ### 1. Domain Model — `ProjectContextPolicy` + `ContextView` **Module**: `cleveragents.domain.models.core.context_policy` **File**: `src/cleveragents/domain/models/core/context_policy.py` (173 lines) **Delivered by**: commit `5480cd36` (`feat(project): add context policy model`) — 2026-02-17 - `VALID_PHASES = frozenset({"default", "strategize", "execute", "apply"})` - `_INHERITANCE_CHAIN` dict defining view resolution: `default → strategize → execute → apply` - `ContextView` (Pydantic `BaseModel`): `include_resources`, `exclude_resources`, `include_paths`, `exclude_paths`, `max_file_size`, `max_total_size` — all with field validators - `ProjectContextPolicy` (Pydantic `BaseModel`): `default_view`, `strategize_view`, `execute_view`, `apply_view` - `resolve_view(phase)` method implementing the full inheritance chain with fallback - Exported from `domain.models.core.__init__` as `ContextView` and `ProjectContextPolicy` **Design decisions**: - Inheritance chain is a dict lookup (`_INHERITANCE_CHAIN`), not a linked list, for O(1) resolution with known fixed phases - Views are `Optional[ContextView]` — `None` means "inherit from parent" - `resolve_view()` walks the chain until a non-None view is found, falling back to an empty `ContextView()` if the entire chain is None --- ### 2. CLI Commands — `context policy set` / `context policy show` **Module**: `cleveragents.cli.commands.project_context` **File**: `src/cleveragents/cli/commands/project_context.py` (1111 lines) **Delivered by**: commit `a8558f13` (`feat(cli): add project context commands`) — 2026-02-17, then extended by `ff42d59d` (`feat(cli): wire project context CLI stubs to ACMS pipeline`) — 2026-03-03 Four commands fully implemented: - `agents project context set` — persists per-phase view configuration with all options: `--view`, `--include-resource`, `--exclude-resource`, `--include-path`, `--exclude-path`, `--max-file-size`, `--max-total-size`, `--clear`, plus 12 ACMS pipeline options - `agents project context show` — displays active policy with optional `--view` for phase-specific resolution; supports rich/json/yaml/plain output - `agents project context inspect` — queries ACMS tier service for scoped metrics and fragments - `agents project context simulate` — dry-run context assembly with budget tracking **Persistence**: SQL helpers (`_read_policy`, `_write_policy`, `_save_policy_json`, `_load_policy_json`) read/write `context_policy_json` column on `ns_projects` table. **Bug fixes applied**: - `session.flush()` → `session.commit()` — policy changes were silently lost on `session.close()` (fixed in `cbf8bcc9`, issue #745) - `contextlib.suppress` rollback wrapper to prevent masking original commit exceptions (same commit) - `--execution-env-priority` flag added via commit `d9c61e28` (issue #1079) --- ### 3. View Inheritance Chain Resolution **Method**: `ProjectContextPolicy.resolve_view(phase)` in `context_policy.py` The inheritance chain is: `default → strategize → execute → apply` - Calling `resolve_view("apply")` checks `apply_view`; if `None`, checks `execute_view`; if `None`, checks `strategize_view`; if `None`, checks `default_view`; if `None`, returns empty `ContextView()` - Clearing a phase view (setting it to `None`) correctly causes fallback to the nearest ancestor view - Invalid phase names raise `ValueError` — validated against `VALID_PHASES` --- ### 4. Tests — Behave BDD Unit Tests (20+ scenarios) **File**: `features/consolidated_context.feature` (238 lines, lines 69–228 for context policy scenarios) **Steps**: `features/steps/project_context_policy_steps.py` (347 lines) Scenarios cover: - Empty policy defaults - View inheritance (6 scenarios): strategize from default, execute from strategize, apply from execute, and full chain - Override isolation — setting one phase doesn't affect others - Invalid phase names → `ValueError` - Include/exclude resource patterns - Include/exclude path patterns - Size limit validation (7 scenarios): zero, negative, valid, None allowed - JSON serialization round-trip - `model_dump` key verification Additional ACMS smoke test scenarios: **File**: `features/m5_acms_smoke.feature` (155 lines) — context policy resolution, budget enforcement, CLI commands --- ### 5. Tests — Robot Framework E2E (5 test cases) **File**: `robot/m5_e2e_verification.robot` (lines 300–351) **Helper**: `robot/helper_m5_e2e_verification.py` (725 lines) **Delivered by**: commit `fd1612c3` (`test(e2e): verify M5 success criteria`) — 2026-02-26 | Test Case | What It Verifies | |-----------|------------------| | `ACMS Context Policy Set And Show` | Sets policy with default + strategize views, reads back, verifies round-trip | | `ACMS Phase View Inheritance Chain` | `default → strategize → execute → apply` inheritance | | `ACMS Scoped Context Output Per Phase` | Narrowing size limits across phases | | `Context Policy Clear And Inheritance Fallback` | Clearing a phase view → fallback to parent | | `Context View Validation Rules` | Zero/negative limits rejected, None allowed, invalid phases → ValueError | Additional E2E coverage added in `robot/e2e/m5_acceptance.robot` (21 test cases) via commit `cbf8bcc9` (issue #745). --- ### 6. Budget Enforcement Extension **Delivered by**: commit `3c0d8397` (`feat(acms): budget enforcement with max_file_size and max_total_size constraints`) — 2026-03-23 This commit (issue #847, the sibling issue) added enforcement logic on top of the `ContextView` fields defined here: - `BudgetViolation` and `BudgetEnforcementResult` frozen models - `enforce_size_budget()` function filtering fragments against `max_file_size` / `max_total_size` - Wired into both `ACMSPipeline.assemble()` and `ContextAssemblyPipeline.assemble()` - 7 additional Behave scenarios --- ### 7. Quality Gates (as of latest master) Per commit `cbf8bcc9` quality gate results: - lint: PASS - typecheck: PASS (0 errors) - unit_tests: 393/393 features, 11,210+ scenarios - integration_tests: 1,576/1,576 - coverage: 98% (threshold: 97%) Per commit `3c0d8397` quality gate results: - unit_tests: 12,237 scenarios PASS - integration_tests: 1,672 tests PASS - coverage: 98% --- ### 8. Rationale for Closing Without New Branch All acceptance criteria code exists on `master`. The work was delivered incrementally through the following commit chain: 1. `5480cd36` — domain model (`ProjectContextPolicy`, `ContextView`, `resolve_view`) 2. `a8558f13` — CLI commands (`context set`, `context show`) 3. `ff42d59d` — ACMS pipeline wiring for CLI commands 4. `fd1612c3` — Robot E2E tests for context policies 5. `cbf8bcc9` — additional E2E acceptance tests + production bug fixes 6. `3c0d8397` — budget enforcement extending the context view fields 7. `d9c61e28` — `--execution-env-priority` flag addition Creating a new branch `feature/m5-context-policies` from current `master` would produce a zero-diff PR since all code is already merged. The issue is being closed as already delivered. --- ### Acceptance Criteria Cross-Reference | Criterion | Status | Evidence | |-----------|--------|----------| | `ContextPolicy` model supports per-phase view configuration | ✅ | `context_policy.py` — `ProjectContextPolicy` with 4 phase views | | `context policy set` CLI command works with default and phase-specific views | ✅ | `project_context.py` `context_set()` with `--view` option | | `context policy show` CLI command displays resolved policies | ✅ | `project_context.py` `context_show()` with phase resolution | | View inheritance chain works correctly | ✅ | `resolve_view()` method with `_INHERITANCE_CHAIN` lookup | | Robot E2E tests pass | ✅ | 5 dedicated tests in `m5_e2e_verification.robot` + 21 in `m5_acceptance.robot` | | Unit tests cover set/show round-trip, inheritance fallback, clear + fallback | ✅ | 20+ Behave scenarios in `consolidated_context.feature` |

aditya

2026-03-24 09:51:40 +00:00