cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

EPIC: CLI Output Format Compliance — Global Flags, JSON Envelope & Error Responses #5203

New Issue
Open
opened 2026-04-09 03:12:30 +00:00 by HAL9000 · 2 comments
HAL9000 commented 2026-04-09 03:12:30 +00:00
Owner
Copy Link
Copy Source

Background

Part of the Decision Intelligence Legendary (#4942). This Epic fixes critical CLI output format compliance issues: global flags (--format, --data-dir, --config-path, -v) not working, JSON/YAML envelope fields missing or incorrect, and error responses not structured per spec.

Demonstrable Capability

When this Epic is complete, all CLI commands respect global flags, produce correctly structured JSON/YAML envelopes with all required fields, and return structured error responses instead of plain text.

Child Issues

  • #5191 — UAT: Global --format flag ignored by subcommands
  • #5192 — UAT: Global --data-dir and --config-path flags not implemented
  • #5193 — UAT: Global -v verbosity flag not implemented
  • #5194 — UAT: JSON/YAML envelope command field is always empty string
  • #5195 — UAT: JSON/YAML envelope missing metadata field
  • #5196 — UAT: JSON/YAML messages[0].text is always "ok"
  • #5197 — UAT: JSON/YAML error responses not structured per spec
  • #5198 — UAT: JSON/YAML envelope timing.duration_ms is always 0

Definition of Done

  • All child issues are closed and merged
  • Global --format flag propagates to all subcommands
  • Global --data-dir and --config-path flags functional
  • Global -v verbosity flag works (repeatable)
  • JSON/YAML envelope has all required fields (command, metadata, timing, messages)
  • Error responses are structured JSON envelopes
  • All nox stages pass
  • Coverage >= 97%

Metadata

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

## Background Part of the Decision Intelligence Legendary (#4942). This Epic fixes critical CLI output format compliance issues: global flags (`--format`, `--data-dir`, `--config-path`, `-v`) not working, JSON/YAML envelope fields missing or incorrect, and error responses not structured per spec. ## Demonstrable Capability When this Epic is complete, all CLI commands respect global flags, produce correctly structured JSON/YAML envelopes with all required fields, and return structured error responses instead of plain text. ## Child Issues <!-- Updated by automation after child issues are created --> - [ ] #5191 — UAT: Global `--format` flag ignored by subcommands - [ ] #5192 — UAT: Global `--data-dir` and `--config-path` flags not implemented - [ ] #5193 — UAT: Global `-v` verbosity flag not implemented - [ ] #5194 — UAT: JSON/YAML envelope `command` field is always empty string - [ ] #5195 — UAT: JSON/YAML envelope missing `metadata` field - [ ] #5196 — UAT: JSON/YAML `messages[0].text` is always `"ok"` - [ ] #5197 — UAT: JSON/YAML error responses not structured per spec - [ ] #5198 — UAT: JSON/YAML envelope `timing.duration_ms` is always 0 ## Definition of Done - [ ] All child issues are closed and merged - [ ] Global `--format` flag propagates to all subcommands - [ ] Global `--data-dir` and `--config-path` flags functional - [ ] Global `-v` verbosity flag works (repeatable) - [ ] JSON/YAML envelope has all required fields (command, metadata, timing, messages) - [ ] Error responses are structured JSON envelopes - [ ] All nox stages pass - [ ] Coverage >= 97% ## Metadata - **Branch Naming Convention**: `fix/v3.2.0/cli-output-format-compliance` - **Milestone**: v3.2.0 - **Parent Legendary**: #4942 --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner
HAL9000 added this to the v3.2.0 milestone 2026-04-09 03:12:36 +00:00
HAL9000 added the
Priority
Critical
State
Unverified
Type
Epic
 labels 2026-04-09 03:12:37 +00:00
HAL9000 commented 2026-04-09 03:13:06 +00:00
Author
Owner
Copy Link
Copy Source

Issue triaged by project owner:

  • State: Verified
  • Priority: Critical — CLI output format compliance is foundational; JSON envelope, global flags, and error responses affect all commands
  • Milestone: v3.2.0 (already assigned — this is a base requirement)
  • Story Points: 21 (XXL) — comprehensive output format compliance across all CLI commands
  • MoSCoW: Must Have — correct CLI output format is required for all tooling and automation that consumes the CLI
  • Parent Epic: LEGENDARY #4942 (Decision Intelligence) or core CLI

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Critical — CLI output format compliance is foundational; JSON envelope, global flags, and error responses affect all commands - **Milestone**: v3.2.0 (already assigned — this is a base requirement) - **Story Points**: 21 (XXL) — comprehensive output format compliance across all CLI commands - **MoSCoW**: Must Have — correct CLI output format is required for all tooling and automation that consumes the CLI - **Parent Epic**: LEGENDARY #4942 (Decision Intelligence) or core CLI --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner
HAL9000 added
State
Verified
MoSCoW
Must have
 and removed
State
Unverified
 labels 2026-04-09 03:13:08 +00:00
HAL9000 commented 2026-04-09 03:13:10 +00:00
Author
Owner
Copy Link
Copy Source

Epic Planning: This Epic was created to group 8 orphaned UAT issues related to global CLI flag compliance and JSON/YAML envelope format issues.

Child Issues Linked

  • #5191 — Global --format flag ignored by subcommands (Priority/Critical)
  • #5192 — Global --data-dir and --config-path flags not implemented (Priority/Critical)
  • #5193 — Global -v verbosity flag not implemented (Priority/High)
  • #5194 — JSON/YAML envelope command field is always empty string (Priority/High)
  • #5195 — JSON/YAML envelope missing metadata field (Priority/Medium)
  • #5196 — JSON/YAML messages[0].text is always "ok" (Priority/Medium)
  • #5197 — JSON/YAML error responses not structured per spec (Priority/High)
  • #5198 — JSON/YAML envelope timing.duration_ms is always 0 (Priority/Backlog)

Dependency Chain

#5191-#5198 (UAT bugs) → EPIC #5203 → LEGENDARY #4942

Note: Issues #5191 and #5192 are Priority/Critical — global flags are fundamental to CLI usability.

Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planner

**Epic Planning**: This Epic was created to group 8 orphaned UAT issues related to global CLI flag compliance and JSON/YAML envelope format issues. ## Child Issues Linked - [ ] #5191 — Global `--format` flag ignored by subcommands (Priority/Critical) - [ ] #5192 — Global `--data-dir` and `--config-path` flags not implemented (Priority/Critical) - [ ] #5193 — Global `-v` verbosity flag not implemented (Priority/High) - [ ] #5194 — JSON/YAML envelope `command` field is always empty string (Priority/High) - [ ] #5195 — JSON/YAML envelope missing `metadata` field (Priority/Medium) - [ ] #5196 — JSON/YAML `messages[0].text` is always `"ok"` (Priority/Medium) - [ ] #5197 — JSON/YAML error responses not structured per spec (Priority/High) - [ ] #5198 — JSON/YAML envelope `timing.duration_ms` is always 0 (Priority/Backlog) ## Dependency Chain ``` #5191-#5198 (UAT bugs) → EPIC #5203 → LEGENDARY #4942 ``` **Note**: Issues #5191 and #5192 are Priority/Critical — global flags are fundamental to CLI usability. --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planner
HAL9000 added a new dependency 2026-04-12 08:25:56 +00:00
#7945 UAT: Plan CLI JSON outputs diverge from specification
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
auto/needs-reevaluation
Controller deferred this PR; awaiting Phase 6+ scope-evaluator or operator re-enablement.
 controller-managed
Auto-agents controller manages this PR/issue (see tools/controller/deploy/RUNBOOK.md). Remove this label to abandon controller management.
 overdue
auto/blocked-by-deps
PR blocked by an open issue dependency. Operator must close the dep (or remove the dependency link) before the merge driver can act. Auto-cleared by merge_drive when no open deps remain.
 auto/ci-timeout
Most recent merge cycle hit CI timeout. Driver excludes this PR while last merge_cycle row is < 30 min old; label persists thereafter as visible history.
 auto/claimed-implementer
Currently being processed by an implementer worker.
 auto/claimed-merge
Currently being processed by the merge driver.
 auto/claimed-reviewer
Currently being processed by a reviewer worker.
 auto/driver-down
Merge driver heartbeat stale; pipeline halted. Closed automatically on next clean tick.
 auto/invariant-violation
Detected master commit violating the strict merge invariant. Tracked as an issue (not a PR label); kept here for label completeness.
 auto/last-attempt-tier-0
In-cycle escalation: most recent attempt ran at the Tier 0 slot (`tier-0`). Slot's model defined in .opencode/models/tiers.yaml.
 auto/last-attempt-tier-1
In-cycle escalation: most recent attempt ran at the Tier 1 slot (`tier-1`). Slot's model defined in .opencode/models/tiers.yaml.
 auto/last-attempt-tier-2
In-cycle escalation: most recent attempt ran at the Tier 2 slot (`tier-2`). Slot's model defined in .opencode/models/tiers.yaml. Gated behind IMPLEMENTER_ESCALATION_TIER2_ENABLED.
 auto/last-attempt-tier-min
In-cycle escalation: most recent attempt ran at the Tier -1 slot (`tier-min`). Slot's model defined in .opencode/models/tiers.yaml. Suffix is ``-min`` (not ``--1``) so the Forgejo UI reads naturally.
 Automation Tracking
Tracking issues used by the AI Automation system for agents to communicate and report.
 auto/needs-conflict-resolution
Rebase conflict needs LLM conflict-resolver.
 auto/needs-implementer
Failing CI needs implementer attention.
 auto/postmortem
Documenting a driver incident or rollback.
 auto/ready-to-merge
Reviewer has APPROVED this PR and no later REQUEST_CHANGES is outstanding. The merge driver requires this label to even consider a PR for merging. Set by the reviewer worker on APPROVE; cleared on REQUEST_CHANGES.
 auto/restart-throttled
Train repeatedly lost master-tempo races. Driver excludes via merge_cycle until cooldown elapses; label persists as visible history.
 auto/revert
Revert PR backing out an invariant violation. Fast-tracked through the merge driver.
 auto/sentinel
Sentinel PR duplicated from upstream into a personal fork by tools/duplicate_prs_to_fork.py for pipeline testing. Lives only in the fork; the canonical pipeline never sees it.
 auto/stale-inactivity
No implementer activity for N days. Flagged for human review. Auto-cleared on next push to head branch.
 auto/unstable
Repeatedly fails on current master (>= 3 ci-fail-on-rebased-sha releases in 12 h). Excluded from driver until human triage.
 Blocked
A ticket in a blocked state and unable to complete until some other task is completed first.
Bounty
$100
A bounty of $100 for any open-source contributor who provides a MR that solves this issue
Bounty
$1000
A bounty of $1000 for any open-source contributor who provides a MR that solves this issue
Bounty
$10000
A bounty of $10000 for any open-source contributor who provides a MR that solves this issue
Bounty
$20
A bounty of $20 for any open-source contributor who provides a MR that solves this issue
Bounty
$2000
A bounty of $2000 for any open-source contributor who provides a MR that solves this issue
Bounty
$250
A bounty of $250 for any open-source contributor who provides a MR that solves this issue
Bounty
$50
A bounty of $50 for any open-source contributor who provides a MR that solves this issue
Bounty
$500
A bounty of $500 for any open-source contributor who provides a MR that solves this issue
Bounty
$5000
A bounty of $5000 for any open-source contributor who provides a MR that solves this issue
Bounty
$750
A bounty of $750 for any open-source contributor who provides a MR that solves this issue
MoSCoW
Could have
Could have feature in order to satisfy the epic/legendary.
MoSCoW
Must have
Must have feature in order to satisfy the epic/legendary.
MoSCoW
Should have
Should have feature in order to satisfy the epic/legendary.
Needs Feedback
There are questions in the ticket that can not be completed until the project owner provides clarity.
Points
1
1 man-hours worth of work for an expert with no learning curve.
Points
13
13 man-hours worth of work for an expert with no learning curve.
Points
2
2 man-hours worth of work for an expert with no learning curve.
Points
21
21 man-hours worth of work for an expert with no learning curve.
Points
3
3 man-hours worth of work for an expert with no learning curve.
Points
34
34 man-hours worth of work for an expert with no learning curve.
Points
5
5 man-hours worth of work for an expert with no learning curve.
Points
55
55 man-hours worth of work for an expert with no learning curve.
Points
8
8 man-hours worth of work for an expert with no learning curve.
Points
88
88 man-hours worth of work for an expert with no learning curve.
Priority
Backlog
This ticket has backlogged priority and is not to be worked on yet
Priority
CI Blocker
Critical priority issue that blocks CI/CD pipeline and prevents PR merges
Priority
Critical
The priority is critical
Priority
High
The priority is high
Priority
Low
The priority is low
Priority
Medium
The priority is medium
Signed-off: Owner
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
 Signed-off: Scrum Master
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
 Signed-off: Tech Lead
When an epic or legendary is in review it must be signed off by owner, tech lead, and scrum master before being marked as completed.
 Spike
A ticket for learning a tool or technology that is needed to be able to do future planning and design.
State
Completed
The ticket has been fully implemented, completed, and merged with the source code. This label should only be applied once a ticket is closed.
State
Duplicate
A ticket that represents the same content as an existing ticket.
State
In Progress
A ticket that is actively being developed.
State
In Review
A ticket that has had some code completed to implement but is waiting to pass peer review and is not yet merged in.
State
Paused
This ticket's work started but wasn't finished. It's on hold (likely in a feature branch) and will be resumed later, either due to a blocker or a delay.
State
Unverified
All new tickets start in this state. A developer may set it to show the ticket is unverified. This means we haven't agreed to work on it. It will either move to a verified state or be closed as wontdo.
State
Verified
The issue has been verified by a developer as legitimate. It will be worked on and verified tickets are now considered part of the backlog.
State
Wont Do
This ticket has been decided it wont be done. This may mean the bug has been determined to not be real (cant verify) or the feature is one we have decided we dont want to adopt.
Type
Automation
Any edits or discussion about the AI automated coding system.
Type
Bug
Something that doesnt work as intended.
Type
Discussion
Anytime a ticket represents a discussion about a subject and doesnt fall into one of the other categories.
Type
Documentation
An error or improvement needed in the documentation.
Type
Epic
Any first tier epic. That is, an epic which contains only issues as children and will not have sub-epics.
Type
Feature
Some new functionality not present.
Type
Legendary
A type of Epic which will contain other Epics.
Type
Refactor
A code change that restructures existing code without changing its external behavior.
Type
Support
Someone needs help using the project.
Type
Task
A generic task that doesnt fit into the other type categories.
Type
Testing
Work exclusively focusing on fixing or expanding testing.
No Label
MoSCoW
Must have
Priority
Critical
State
Verified
Type
Epic
Milestone
No items
No Milestone v3.2.0
Projects
Clear projects
No project
Assignees
Clear assignees
aditya (Aditya Chhabra) aleenaumair (Aleena Umair) brent.edwards (Brent Edwards) CoreRasurae (Luis Mendes) drew (Drew Morris) eugen.thaci (Eugen Thaci) freemo (Jeffrey Phillips Freeman) HAL9000 (HAL 9000) HAL9001 (HAL9001) hamza.khyari (Hamza Khyari) hurui200320 (Rui Hu) justin.morris khird (Kyle Hird) org.cleveragents
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Blocks
#4942 LEGENDARY: Decision Intelligence — Plan Decisions, Corrections, Subplans & Checkpoints
cleveragents/cleveragents-core
Depends on
#4794 UAT: `agents plan execute --format json` hardcodes `sandbox.strategy: "git_worktree"` regardless of actual resource sandbox strategy
cleveragents/cleveragents-core
#5011 UAT: `agents actor remove` missing `--format` option — inconsistent with all other actor subcommands
cleveragents/cleveragents-core
#5024 UAT: `--format` help text inconsistency — `color` format omitted from per-command `_FORMAT_HELP` strings but present in `constants.py`
cleveragents/cleveragents-core
#5030 UAT: `agents skill refresh` command exists in implementation but is not defined in the spec
cleveragents/cleveragents-core
#5033 UAT: `agents skill tools` has undocumented `--refresh` flag not in spec
cleveragents/cleveragents-core
#5043 UAT: `agents tool add` duplicate-tool error output format deviates from spec (plain format uses `[ERROR]` instead of `Error:`)
cleveragents/cleveragents-core
#5077 UAT: `agents actor run` has undocumented `--config` option not in spec — bypasses actor registry
cleveragents/cleveragents-core
#5191 UAT: Global `--format` flag ignored by subcommands — `agents --format json session list` outputs rich table instead of JSON
cleveragents/cleveragents-core
#5192 UAT: Global `--data-dir` and `--config-path` flags not implemented — spec-required global flags raise NoSuchOption error
cleveragents/cleveragents-core
#5193 UAT: Global `-v` verbosity flag not implemented — spec-required repeatable verbosity flag raises NoSuchOption error
cleveragents/cleveragents-core
#5194 UAT: JSON/YAML envelope `command` field is always empty string — spec requires actual command name
cleveragents/cleveragents-core
#5195 UAT: JSON/YAML envelope missing `metadata` field — spec requires top-level `metadata` object in envelope
cleveragents/cleveragents-core
#5196 UAT: JSON/YAML `messages[0].text` is always `"ok"` — spec requires meaningful command-specific message text
cleveragents/cleveragents-core
#5197 UAT: JSON/YAML error responses not structured per spec — errors output plain text to stderr instead of structured JSON envelope
cleveragents/cleveragents-core
#5198 UAT: JSON/YAML envelope `timing.duration_ms` is always 0 — command execution time not measured
cleveragents/cleveragents-core
#5528 UAT: `agents project link-resource` output missing structured Resource Linked panel with Type and Access fields
cleveragents/cleveragents-core
#5534 UAT: `agents project unlink-resource` fails if resource has been deleted — cannot clean up dangling links
cleveragents/cleveragents-core
#5588 UAT: `agents project context set` rich output does not match spec — missing Limits, Summarization, and Other Views panels
cleveragents/cleveragents-core
#5591 UAT: `agents project context inspect` does not return assembled context fragments with UKO URIs — uses stub simulation instead of live ACMS pipeline
cleveragents/cleveragents-core
#5594 UAT: `agents project context simulate` uses stub simulation instead of live ACMS pipeline — does not show token budget breakdown per strategy
cleveragents/cleveragents-core
#5625 UAT: `agents resource type add` output missing "New subcommand available" info message and multi-panel layout
cleveragents/cleveragents-core
#5628 UAT: `agents resource type remove` output missing "Resources Using" count and "Subcommand Removed" panel
cleveragents/cleveragents-core
#5631 UAT: `agents resource type show` output missing "Source" field and "Checkpointable" in sandbox section
cleveragents/cleveragents-core
#5632 UAT: `agents resource type list` missing "✓ OK N resource types listed" success count message
cleveragents/cleveragents-core
#5634 UAT: `agents resource type` JSON/YAML output uses `resource_kind` instead of `physical_virtual` as specified
cleveragents/cleveragents-core
#5730 UAT: Global `-v/--verbose` repeatable flag missing from `main_callback` — spec requires count-based verbosity (ERROR→WARN→INFO→DEBUG→TRACE)
cleveragents/cleveragents-core
#5741 UAT: `CLEVERAGENTS_FORMAT` env var not checked in CLI format resolution — spec-required tier in resolution chain is missing
cleveragents/cleveragents-core
#5743 UAT: `_print_basic_help()` fast-path bypasses Typer and omits global flags (`--format`, `-v`, `--data-dir`, `--config-path`) from help output
cleveragents/cleveragents-core
#5752 UAT: Global `--format/-f` short flag conflicts with `init --force/-f` — ambiguous argument parsing when using `-f` with `init` command
cleveragents/cleveragents-core
#5764 UAT: `agents audit export` command is missing — spec requires JSON/CSV export of audit logs
cleveragents/cleveragents-core
#5891 UAT: `agents session list` missing `--actor` filter option — cannot filter sessions by actor
cleveragents/cleveragents-core
#5902 UAT: `agents session list` truncates session ID to 8 chars — cannot use displayed ID with other commands
cleveragents/cleveragents-core
#5967 UAT: `agents project link-resource` JSON output does not match spec — missing `resource_linked`, `access`, and `indexing` fields
cleveragents/cleveragents-core
#5977 UAT: `agents project link-resource` exposes raw SQLAlchemy `IntegrityError` when resource is already linked
cleveragents/cleveragents-core
#6083 UAT: `agents plan apply` rich output uses generic single panel instead of spec-required multi-panel layout
cleveragents/cleveragents-core
#6095 UAT: `agents plan use`, `plan status`, `plan apply`, and `plan list` JSON/YAML output missing spec-required envelope structure
cleveragents/cleveragents-core
#6100 UAT: `agents plan list` Summary panel missing `Cancelled` count and Filters panel hidden when no filters active
cleveragents/cleveragents-core
#6111 UAT: `agents project create` JSON/YAML output missing spec-required sections — `paths`, `defaults`, `resources` panels absent
cleveragents/cleveragents-core
#6126 UAT: `agents plan execute` rich output uses generic single panel instead of spec-required multi-panel layout
cleveragents/cleveragents-core
#6160 UAT: `agents project show` JSON/YAML output missing spec-required sections — `validations`, `context`, `indexing_status`, `active_plans` absent
cleveragents/cleveragents-core
#7039 BUG-HUNT: [error-handling] Overly broad `except Exception:` patterns in CLI command modules mask critical errors
cleveragents/cleveragents-core
#7118 BUG-HUNT: [Security] SQLite URL parsing vulnerability allows path traversal in database checking
cleveragents/cleveragents-core
#7945 UAT: Plan CLI JSON outputs diverge from specification
cleveragents/cleveragents-core
Reference: cleveragents/cleveragents-core#5203
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?