HAL9000/temp
0
0
Fork 0
forked from HAL9000/cleveragents-core
Code Pull Requests Activity
Files
bugfix/checkpoint-wiring
temp/docs/reference/project_context_cli.md
T
Luis Mendes ff42d59d6d feat(cli): wire project context CLI stubs to ACMS pipeline 
Wire all four project context CLI commands (inspect, simulate, set, show)
to live ACMS pipeline services via ContextTierService and CRP models.

- context inspect: queries ContextTierService for tier metrics and
  per-project fragments with filtering by strategy/focus/breadth/depth
- context simulate: dry-run context assembly using CRP models with
  configurable token budget and assembly strategies
- context set: 12 new ACMS pipeline options (hot_max_tokens,
  warm_max_decisions, cold_max_decisions, summary_max_tokens,
  temporal_scope, auto_refresh, focus_area, breadth, depth,
  assembly_strategy, retrieval_strategy, summary_strategy)
- context show: displays ACMS pipeline configuration alongside policy

- `context inspect` displayed global tier fragment counts (hot/warm/cold)
across all projects instead of counts for the target project only.

Add `ContextTierService.get_scoped_metrics(project_names)` which uses
`ScopedBackendView` to filter fragment counts to the specified projects
while keeping hit/miss counters as global service-level cache metrics.
Update `context_inspect()` to call `get_scoped_metrics([project])`
instead of `get_metrics()`.

- `context simulate --focus` accepted focus URIs and passed them to the
`ContextRequest` model but never used them to filter the fragment list,
making the `--focus` flag a no-op.

Add focus URI filtering in `_simulate_context_assembly()` after
`get_scoped_view()` — filters `project_fragments` by matching each
fragment's `resource_id` against the supplied focus URIs.

Also fixes redaction false positives for hot_max_tokens and
summary_max_tokens keys, and Rich Console line-wrapping in test
output that caused JSON parse failures.

Includes 28 new Behave BDD scenarios for wiring coverage, updated
Robot Framework integration tests, and reference documentation.

ISSUES CLOSED: #499
2026-03-03 23:36:15 +00:00

274 lines
9.2 KiB
Markdown
Raw Permalink Blame History

# Project Context CLI Reference
The `agents project context` commands manage per-project context policies
that control what resources and files are visible during each ACMS phase,
and provide tools to inspect and simulate the ACMS pipeline state.
## Overview
Context policies use **view inheritance**:
| Phase | Inherits from |
|------------|---------------|
| default | (none) |
| strategize | default |
| execute | strategize |
| apply | execute |
An empty policy defaults to including everything.
---
## `agents project context set`
Persist a context policy view and ACMS pipeline configuration for a project.
### Usage
```
agents project context set PROJECT [OPTIONS]
```
### Arguments
| Argument | Description |
|-----------|------------------------------|
| `PROJECT` | Project namespaced name |
### Options
#### View Options
| Option | Type | Description |
|----------------------|-----------|------------------------------------------|
| `--view`, `-v` | `str` | Phase view: default, strategize, execute, apply (default: default) |
| `--include-resource` | `str` | Resource pattern to include (repeatable) |
| `--exclude-resource` | `str` | Resource pattern to exclude (repeatable) |
| `--include-path` | `str` | File path glob to include (repeatable) |
| `--exclude-path` | `str` | File path glob to exclude (repeatable) |
| `--max-file-size` | `int` | Max file size in bytes (None = no limit) |
| `--max-total-size` | `int` | Max total context size in bytes |
| `--clear` | `flag` | Clear (reset) the view for the phase |
#### ACMS Pipeline Options
| Option | Type | Default | Description |
|-------------------------|---------|----------|------------------------------------------------|
| `--hot-max-tokens` | `int` | 8000 | Max tokens for the hot tier context window |
| `--warm-max-decisions` | `int` | 500 | Max decisions for the warm tier |
| `--cold-max-decisions` | `int` | 5000 | Max decisions for the cold tier |
| `--query-limit` | `int` | None | Max number of fragments per query |
| `--summarize/--no-summarize` | `bool` | True | Enable or disable context summarization |
| `--summary-max-tokens` | `int` | None | Max tokens for context summaries |
| `--strategy` | `str` | (none) | Preferred context strategy (repeatable) |
| `--default-breadth` | `int` | 2 | Default breadth for context retrieval |
| `--default-depth` | `str` | 3 | Default depth (integer or named level) |
| `--skeleton-ratio` | `float` | 0.2 | Skeleton compression ratio (0.0-1.0) |
| `--temporal-scope` | `str` | current | Temporal scope: current, recent, or all |
| `--auto-refresh/--no-auto-refresh` | `bool` | True | Auto-refresh context on resource changes |
#### Output Options
| Option | Type | Description |
|-----------------|-------|------------------------------------------|
| `--format`, `-f`| `str` | Output format (json, yaml, plain, table, rich) |
### Examples
```bash
# Set default view with resource filters
agents project context set local/my-app \
--view default \
--include-resource "db-*" \
--exclude-resource "db-test"
# Set strategize view with path filters
agents project context set local/my-app \
--view strategize \
--include-path "src/**/*.py" \
--exclude-path "*.pyc"
# Set size limits
agents project context set local/my-app \
--max-file-size 1048576 \
--max-total-size 10485760
# Clear execute view (inherit from strategize)
agents project context set local/my-app --view execute --clear
# Configure ACMS pipeline options
agents project context set local/my-app \
--hot-max-tokens 4000 \
--warm-max-decisions 200 \
--temporal-scope recent \
--no-auto-refresh
# Set preferred strategies
agents project context set local/my-app \
--strategy breadth_first \
--strategy depth_first
# Adjust skeleton compression
agents project context set local/my-app \
--skeleton-ratio 0.5 \
--default-breadth 5 \
--default-depth 7
```
---
## `agents project context show`
Display the context policy and ACMS pipeline configuration for a project.
### Usage
```
agents project context show PROJECT [OPTIONS]
```
### Arguments
| Argument | Description |
|-----------|-------------------------|
| `PROJECT` | Project namespaced name |
### Options
| Option | Type | Description |
|-----------------|-------|--------------------------------------------------|
| `--view`, `-v` | `str` | Show resolved view for a specific phase |
| `--format`, `-f`| `str` | Output format (json, yaml, plain, table, rich) |
### Output
The `show` command displays:
- **View configuration** for each phase (or the resolved view for a specific phase)
- **ACMS Pipeline Config** including hot/warm/cold tier budgets, summarization settings,
strategies, temporal scope, and auto-refresh status
### Examples
```bash
# Show all views and ACMS config
agents project context show local/my-app
# Show resolved view for execute phase
agents project context show local/my-app --view execute
# JSON output (includes acms_config key)
agents project context show local/my-app --format json
```
---
## `agents project context inspect`
Inspect the effective context state for a project by querying the ACMS
tier service. Displays current fragment distribution across tiers, tier
metrics, budget utilisation, and per-actor visibility.
### Usage
```
agents project context inspect PROJECT [OPTIONS]
```
### Arguments
| Argument | Description |
|-----------|-------------------------|
| `PROJECT` | Project namespaced name |
### Options
| Option | Type | Description |
|-------------------|-------|------------------------------------------------|
| `--view`, `-v` | `str` | Phase view to inspect |
| `--strategy` | `str` | Filter fragments by strategy name |
| `--focus` | `str` | UKO URIs to focus on (repeatable) |
| `--breadth` | `int` | Override breadth for context retrieval |
| `--depth` | `str` | Override depth (integer or named level) |
| `--format`, `-f` | `str` | Output format (json, yaml, plain, table, rich) |
### Output
The `inspect` command displays:
- **Tier Metrics** — project-scoped hot/warm/cold fragment counts, service-level hit/miss rates
- **Tier Budget** — configured max tokens (hot) and max decisions (warm, cold)
- **Project Fragments** — total count and breakdown by tier for the project
- **Actor Visibility** — how many fragments each actor role (strategist, executor, reviewer) can see
- **Fragment Details** — first 20 fragments with IDs, tiers, token counts, and access metadata
- **ACMS Config** — the project's pipeline configuration
### Examples
```bash
# Inspect all tiers for a project
agents project context inspect local/my-app
# Inspect with JSON output
agents project context inspect local/my-app --format json
# Inspect a specific phase view
agents project context inspect local/my-app --view strategize
```
---
## `agents project context simulate`
Run a dry-run context window assembly for a project. Creates a simulated
`AssembledContext` using the project's ACMS configuration and available
tier fragments.
### Usage
```
agents project context simulate PROJECT [OPTIONS]
```
### Arguments
| Argument | Description |
|-----------|-------------------------|
| `PROJECT` | Project namespaced name |
### Options
| Option | Type | Description |
|-------------------|-------|------------------------------------------------|
| `--view`, `-v` | `str` | Phase view for simulation |
| `--budget` | `int` | Token budget override |
| `--focus` | `str` | UKO URIs to focus on (repeatable) |
| `--strategy` | `str` | Preferred strategies (repeatable) |
| `--format`, `-f` | `str` | Output format (json, yaml, plain, table, rich) |
### Output
The `simulate` command displays:
- **Summary** — total tokens, budget usage percentage, strategies used, fragment count, context hash
- **Fragment Table** — each assembled fragment with UKO node, token count, relevance score, depth, and strategy. When `--focus` is provided, only fragments matching the focus URIs are included.
- **ACMS Config** — the project's pipeline configuration used for the simulation
### Examples
```bash
# Simulate with default settings
agents project context simulate local/my-app
# Simulate with custom budget
agents project context simulate local/my-app --budget 4000
# Simulate for a specific phase with strategy hints
agents project context simulate local/my-app \
--view strategize \
--strategy breadth_first
# JSON output for programmatic consumption
agents project context simulate local/my-app --format json
```
View Git Blame Copy Permalink