<!-- task=m-iop-agent-cli-runtime/18+14,15_cli_command_tree plan=0 tag=API -->

# Headless CLI Command Tree

## For the Implementing Agent

Filling implementation-owned sections in `CODE_REVIEW-cloud-G06.md` is mandatory. Run verification, paste actual output, leave active files in place, and report ready for review. Finalization is code-review-only. If blocked, record exact blocker evidence and resume conditions without asking the user, creating stop files, archiving, or writing `complete.log`.

## Background

With split configuration fixtures available, the standalone host needs deterministic Cobra commands over narrow ports. This packet owns command parsing, delegation, stable output, manual selection, and side-effect-free preview without owning process entry or build packaging.

## Analysis

### Files Read

- `packages/go/agentconfig/runtime_config.go`
- `packages/go/agenttask/ports.go`
- `packages/go/agenttask/types.go`
- `agent-task/m-iop-agent-cli-runtime/14+13_cli_config_fixtures/plan_local_G06_0.log`
- `agent-task/m-iop-agent-cli-runtime/14+13_cli_config_fixtures/code_review_cloud_G06_0.log`

### SDD Criteria

S10 requires validate, discovery, selection, preview, lifecycle, and status behavior. This strict subset supplies the command-level integration tests but does not claim the binary/transcript evidence or `cli-surface` completion.

### Verification Context

Use fresh command package tests, race, vet, formatting, and diff validation from the original plan. No binary build or external runner is needed.

### Test Coverage Gaps

- No Cobra root invokes standalone host ports.
- No test proves preview and an unselected start perform zero mutation.

### Symbol References

None. New command DTOs and ports are application-owned.

### Split Judgment

API-2 is independently implementable over fakes after the host and configuration fixtures exist. Binary construction and contract evidence remain in the closure child.

### Scope Rationale

Do not add `apps/agent/cmd/agent`, Makefile targets, local proto-socket transport, subprocesses, project logs, or contract evidence.

### Final Routing

- evaluation_mode: `first-pass`
- finalizer: `finalize-task-policy.sh pair`
- build: closure complete, `local-G06`, basis `local-fit`, filename `PLAN-local-G06.md`
- review: closure complete, `cloud-G06`, basis `official-review`, filename `CODE_REVIEW-cloud-G06.md`
- large_indivisible_context: `false`
- positive loop risks: `broad command matrix` (count `1`)
- recovery signals: rework `0`, evidence-integrity failure `false`
- capability-gap evidence: none

## Implementation Checklist

- [ ] Implement the complete Cobra command tree over narrow host ports, including manual selection and side-effect-free preview.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-2] Implement the Command Tree

#### Problem

The approved S10 surface has no standalone command package.

#### Solution

Create one Cobra root with explicit `--repo-config`, `--local-config`, and `--provider-catalog` flags. Implement `validate`, `provider list`, `project list`, `milestone list`, `milestone select`, `preview`, `serve`, `start`, `stop`, `resume`, and `status` over a narrow command service. Preview must not call mutation methods, and start must reject a project without an explicitly selected Milestone.

#### Modified Files and Checklist

- [ ] `apps/agent/internal/command/root.go` — construct root, flags, and subcommands.
- [ ] `apps/agent/internal/command/service.go` — define request/response DTOs and service port.
- [ ] `apps/agent/internal/command/root_test.go` — test the command matrix and stable text/JSON output.
- [ ] `apps/agent/internal/command/config_test.go` — cover config command behavior using predecessor fixtures.

#### Test Strategy

Write table tests `TestCommandMatrix`, `TestPreviewIsSideEffectFree`, `TestStartRequiresSelectedMilestone`, and `TestStatusIncludesOverlayIntegrationAndBlockers` using one recording fake.

#### Verification

```bash
go test -count=1 ./apps/agent/internal/command
```

Expected: all commands parse and delegate exactly once; preview and unselected start mutate nothing.

## Dependencies and Execution Order

Predecessors `14+13_cli_config_fixtures` and `15+13_host_lifecycle` must each produce a same-group active or archived `complete.log`.

## Modified Files Summary

| File | Item |
|------|------|
| `apps/agent/internal/command/config_test.go` | API-2 |
| `apps/agent/internal/command/root.go` | API-2 |
| `apps/agent/internal/command/service.go` | API-2 |
| `apps/agent/internal/command/root_test.go` | API-2 |

## Final Verification

```bash
gofmt -w apps/agent/internal/command/*.go
go test -count=1 ./apps/agent/internal/command
go test -count=1 -race ./apps/agent/internal/command
go vet ./apps/agent/internal/command
git diff --check
```

Expected: fresh, race, vet, formatting, and diff checks pass. After completing all changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
