<!-- task=m-iop-agent-cli-runtime/14+13_cli_surface plan=0 tag=API -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> Complete the checklist and evidence, leave active files in place, and report ready for review. Blockers belong only in implementation evidence. Do not classify next state or perform review-agent finalization.

## Overview

date=2026-07-29
task=m-iop-agent-cli-runtime/14+13_cli_surface, plan=0, tag=API

## Roadmap Targets

- Milestone: `agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md)
- Task ids:
  - `cli-surface`: binary, split configuration, validation, discovery, selection, lifecycle, and status commands
- Completion mode: check-on-pass

## For the Review Agent

> **[REVIEW AGENT ONLY]** Implementing agents must not execute finalization.

Compare every item and actual output to source. Append verdict/signals; archive `CODE_REVIEW-cloud-G06.md` → `code_review_cloud_G06_0.log` and `PLAN-local-G06.md` → `plan_local_G06_0.log`; on PASS write `complete.log`, archive the task, and report completion metadata without editing the roadmap; on WARN/FAIL materialize the next code-review state.

## Implementation Item Completion

| Item | Status |
|------|--------|
| API-1 Split configs | [ ] |
| API-2 Command tree | [ ] |
| API-3 Binary/build | [ ] |
| API-4 Contract/transcript | [ ] |

## Implementation Checklist

- [ ] Add secret-free repo-global and user-local example configurations with strict validation tests.
- [ ] Implement the complete Cobra command tree over narrow host ports, including manual selection and side-effect-free preview.
- [ ] Add the `iop-agent` entry point and Makefile build target with command-level tests and Darwin cross-build.
- [ ] Update the standalone contract with actual S10 source/test paths and run a headless operation transcript.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** Implementing agents must not modify this checklist.

- [ ] Append one verdict and verified `review_rework_count` / `evidence_integrity_failure`.
- [ ] Verify verdict, dimensions, and finding classifications match.
- [ ] Archive `CODE_REVIEW-cloud-G06.md` as `code_review_cloud_G06_0.log`.
- [ ] Archive `PLAN-local-G06.md` as `plan_local_G06_0.log`.
- [ ] Verify the Agent-Ops managed `.gitignore` block.
- [ ] If PASS, write canonical `complete.log` and leave no active Markdown files.
- [ ] If PASS, move this task directory to the dated archive and update this checklist there.
- [ ] If PASS, report `cli-surface` completion metadata without editing the roadmap.
- [ ] If PASS, remove an empty split parent or prove remaining siblings/files require it.
- [ ] If WARN/FAIL, write the exact next state and do not write `complete.log`.

## Deviations from Plan

_Implementer: replace with actual deviations or `None`._

## Key Design Decisions

_Implementer: replace with actual decisions._

## Reviewer Checkpoints

- Every S10 command exists and delegates through the host.
- Preview and unselected start are mutation-free.
- Repo-global input is secret-free/read-only; local example owns device paths.
- Binary runs outside a checkout with explicit paths and cross-builds for macOS.

## Verification Results

### Focused tests

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

_Paste actual stdout/stderr._

### Build and transcript

```bash
make build-agent
GOOS=darwin GOARCH=arm64 go build -trimpath -o /tmp/iop-agent-darwin-arm64 ./apps/agent/cmd/agent
build/bin/iop-agent --help
```

_Paste actual stdout/stderr._

### Static checks

```bash
go vet ./apps/agent/cmd/agent ./apps/agent/internal/command
git diff --check
```

_Paste actual stdout/stderr._

---

> **[IMPLEMENTING AGENT — BEFORE SAVING]** Fill every implementation-owned section and leave review-only content unchanged.

## Section Ownership

| Section | Owner | Note |
|---------|-------|------|
| Header, Overview, Roadmap Targets, Review Instructions | Fixed | Implementer must not modify |
| Implementation Item Completion, Implementation Checklist | Implementing agent | Check status only |
| Review-Only Checklist | Review agent | Implementer must not modify |
| Deviations, Decisions, Verification Results | Implementing agent | Record actual evidence |
| Reviewer Checkpoints | Fixed | Reviewer verifies them |
| Code Review Result and finalization | Review agent | Append/execute only after review |