feat(acms): context assembly CLI functional (context list/add/show/clear) #848

Closed
opened 2026-03-13 21:59:06 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit Message: feat(acms): context assembly CLI functional (context list/add/show/clear)
  • Branch: feature/m5-context-cli

Background

M5 (v3.4.0) acceptance criterion: the context assembly CLI must be fully functional, supporting context list, context add, context show, and context clear commands. These commands allow users to manage context resources attached to plans, view assembled context, and clear context state.

Per the E2E suite (m5_e2e_verification.robot lines 78, 89), the tests verify scoped context output per phase with narrowing size limits and clearing phase views with inheritance fallback, both with persistence round-trip verification.

Expected Behavior

  1. agents context list shows all context resources for the current plan/project
  2. agents context add attaches a new context resource to the current plan
  3. agents context show displays the assembled context for a given phase
  4. agents context clear removes context state, causing fallback to inherited views
  5. All operations persist correctly through round-trips

Acceptance Criteria

  • agents context list CLI command returns context resources
  • agents context add CLI command attaches resources
  • agents context show CLI command displays assembled context
  • agents context clear CLI command clears state with inheritance fallback
  • Persistence round-trip works for all operations
  • Robot E2E tests ACMS Scoped Context Output Per Phase and Context Policy Clear And Inheritance Fallback pass
  • Unit tests cover: empty state, multiple resources, clear + re-add

Supporting Information

  • E2E tests: robot/m5_e2e_verification.robot lines 78, 89
  • Related: context policy configuration (sibling issue)

Subtasks

  • Implement agents context list CLI command
  • Implement agents context add CLI command
  • Implement agents context show CLI command
  • Implement agents context clear CLI command
  • Ensure persistence round-trip for all operations
  • Tests (Behave): Add scenarios for CLI context operations
  • 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.
## Metadata - **Commit Message**: `feat(acms): context assembly CLI functional (context list/add/show/clear)` - **Branch**: `feature/m5-context-cli` ## Background M5 (v3.4.0) acceptance criterion: the context assembly CLI must be fully functional, supporting `context list`, `context add`, `context show`, and `context clear` commands. These commands allow users to manage context resources attached to plans, view assembled context, and clear context state. Per the E2E suite (`m5_e2e_verification.robot` lines 78, 89), the tests verify scoped context output per phase with narrowing size limits and clearing phase views with inheritance fallback, both with persistence round-trip verification. ## Expected Behavior 1. `agents context list` shows all context resources for the current plan/project 2. `agents context add` attaches a new context resource to the current plan 3. `agents context show` displays the assembled context for a given phase 4. `agents context clear` removes context state, causing fallback to inherited views 5. All operations persist correctly through round-trips ## Acceptance Criteria - [x] `agents context list` CLI command returns context resources - [x] `agents context add` CLI command attaches resources - [x] `agents context show` CLI command displays assembled context - [x] `agents context clear` CLI command clears state with inheritance fallback - [x] Persistence round-trip works for all operations - [x] Robot E2E tests `ACMS Scoped Context Output Per Phase` and `Context Policy Clear And Inheritance Fallback` pass - [x] Unit tests cover: empty state, multiple resources, clear + re-add ## Supporting Information - E2E tests: `robot/m5_e2e_verification.robot` lines 78, 89 - Related: context policy configuration (sibling issue) ## Subtasks - [x] Implement `agents context list` CLI command - [x] Implement `agents context add` CLI command - [x] Implement `agents context show` CLI command - [x] Implement `agents context clear` CLI command - [x] Ensure persistence round-trip for all operations - [x] Tests (Behave): Add scenarios for CLI context operations - [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.
freemo added this to the v3.4.0 milestone 2026-03-13 21:59:48 +00:00
Member

Implementation Notes

Design Decisions

  1. CLI commands already functional: The agents context list/add/show/clear CLI commands in cleveragents.cli.commands.context were already implemented and wired through ContextService and the DI container. The primary work was verifying full functionality and adding missing test coverage.

  2. E2E tests already passing: Both Robot E2E tests (ACMS Scoped Context Output Per Phase and Context Policy Clear And Inheritance Fallback) were already passing. They test the ProjectContextPolicy model layer directly via helper_m5_e2e_verification.py helper scripts, validating:

    • Phase-specific view resolution with resolve_view()
    • Size limit narrowing from strategize → execute → apply
    • Clearing views triggers inheritance fallback
    • Persistence round-trip via _write_policy/_read_policy
  3. Added missing unit test coverage: The acceptance criteria required unit tests for "empty state, multiple resources, clear + re-add". Added 5 new Behave scenarios to features/m5_acms_smoke.feature:

    • M5 smoke context list with multiple resources — verifies list output with 3 context entries
    • M5 smoke context add multiple files to project — verifies adding multiple files in one invocation
    • M5 smoke context show with multiple resources shows summary — verifies summary display for multi-file context
    • M5 smoke context clear then re-add restores entries — verifies the clear + re-add pattern
    • M5 smoke context clear on empty project succeeds — verifies clear on already-empty context

Key Code Locations

  • CLI commands: cleveragents.cli.commands.context module — context_add(), context_list(), context_show(), context_clear()
  • Programmatic wrappers: cleveragents.cli.commands.contextadd_command(), list_command(), show_command(), clear_command()
  • Context service: cleveragents.application.services.context_service.ContextService
  • Context policy model: cleveragents.domain.models.core.context_policy.ProjectContextPolicy
  • E2E test helper: robot/helper_m5_e2e_verification.pyacms_scoped_context(), context_policy_clear()
  • Behave feature: features/m5_acms_smoke.feature
  • Behave steps: features/steps/m5_acms_smoke_steps.py

Test Results

  • Unit tests: 12,235 scenarios passed (31 in m5_acms_smoke.feature, up from 26)
  • Integration tests: 1,672 tests passed
  • Robot E2E: Both target tests passed
  • Coverage: 98.38% (threshold: >97%)
  • Lint: Clean
  • Typecheck: 0 errors
## Implementation Notes ### Design Decisions 1. **CLI commands already functional**: The `agents context list/add/show/clear` CLI commands in `cleveragents.cli.commands.context` were already implemented and wired through `ContextService` and the DI container. The primary work was verifying full functionality and adding missing test coverage. 2. **E2E tests already passing**: Both Robot E2E tests (`ACMS Scoped Context Output Per Phase` and `Context Policy Clear And Inheritance Fallback`) were already passing. They test the `ProjectContextPolicy` model layer directly via `helper_m5_e2e_verification.py` helper scripts, validating: - Phase-specific view resolution with `resolve_view()` - Size limit narrowing from strategize → execute → apply - Clearing views triggers inheritance fallback - Persistence round-trip via `_write_policy`/`_read_policy` 3. **Added missing unit test coverage**: The acceptance criteria required unit tests for "empty state, multiple resources, clear + re-add". Added 5 new Behave scenarios to `features/m5_acms_smoke.feature`: - `M5 smoke context list with multiple resources` — verifies list output with 3 context entries - `M5 smoke context add multiple files to project` — verifies adding multiple files in one invocation - `M5 smoke context show with multiple resources shows summary` — verifies summary display for multi-file context - `M5 smoke context clear then re-add restores entries` — verifies the clear + re-add pattern - `M5 smoke context clear on empty project succeeds` — verifies clear on already-empty context ### Key Code Locations - CLI commands: `cleveragents.cli.commands.context` module — `context_add()`, `context_list()`, `context_show()`, `context_clear()` - Programmatic wrappers: `cleveragents.cli.commands.context` — `add_command()`, `list_command()`, `show_command()`, `clear_command()` - Context service: `cleveragents.application.services.context_service.ContextService` - Context policy model: `cleveragents.domain.models.core.context_policy.ProjectContextPolicy` - E2E test helper: `robot/helper_m5_e2e_verification.py` — `acms_scoped_context()`, `context_policy_clear()` - Behave feature: `features/m5_acms_smoke.feature` - Behave steps: `features/steps/m5_acms_smoke_steps.py` ### Test Results - **Unit tests**: 12,235 scenarios passed (31 in `m5_acms_smoke.feature`, up from 26) - **Integration tests**: 1,672 tests passed - **Robot E2E**: Both target tests passed - **Coverage**: 98.38% (threshold: >97%) - **Lint**: Clean - **Typecheck**: 0 errors
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

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