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

# iop-agent Binary and S10 Contract Closure

## 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

The configuration and command packets leave S10 without a runnable product entry point or concrete evidence map. This closure packet adds the binary/build surface, records actual contract paths, and runs the headless transcript.

## 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

## Analysis

### Files Read

- `apps/node/cmd/node/main.go`
- `apps/node/cmd/node/main_test.go`
- `Makefile`
- `agent-contract/inner/iop-agent-cli-runtime.md`
- `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 the built binary, split-config command integration test, full headless transcript, and proof that an unselected ready Milestone never starts. This child closes those requirements over the two predecessor children.

### Verification Context

Use fresh command/binary tests, race, vet, local build, Darwin arm64 cross-build, help transcript, and `git diff --check` from the original plan.

### Test Coverage Gaps

- No `iop-agent` process entry or Makefile target exists.
- The standalone contract has no actual S10 source/test paths or transcript evidence.

### Symbol References

None. The entry point wraps the existing command package.

### Split Judgment

API-3 and API-4 form the closure because the contract transcript needs the built binary. They follow configuration and command-tree predecessors and exclusively own `Roadmap Targets`.

### Scope Rationale

Do not expand the command matrix, implement local control, subprocesses, project logs, authenticated provider smoke, or embed checkout-specific paths.

### 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

- [x] Add the `iop-agent` entry point and Makefile build target with command-level tests and Darwin cross-build.
- [x] Update the standalone contract with actual S10 source/test paths and run a headless operation transcript.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-3] Add the Binary and Build Target

#### Problem

The Makefile builds only Edge and Node binaries; no `iop-agent` entry point exists.

#### Solution

Add `apps/agent/cmd/agent/main.go` with an injectable `run(args, stdout, stderr)` seam. Build to `build/bin/iop-agent`, include it in `build-local`, and keep default paths overrideable so the binary works outside a checkout.

#### Modified Files and Checklist

- [x] `apps/agent/cmd/agent/main.go` — add the process entry point.
- [x] `apps/agent/cmd/agent/main_test.go` — verify exit codes and output separation.
- [x] `Makefile` — add `build-agent` and include it in local build.

#### Test Strategy

Test success, usage error, config error, and context cancellation. Build locally and for Darwin arm64.

#### Verification

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

Expected: tests and both builds pass.

Verified:

```
ok   	iop/apps/agent/cmd/agent	0.010s
ok   	iop/apps/agent/internal/command	0.022s
ok   	iop/apps/agent/cmd/agent	1.031s
ok   	iop/apps/agent/internal/command	1.028s
(no output — vet clean)
mkdir -p build/bin
go build -trimpath -o build/bin/iop-agent ./apps/agent/cmd/agent
(no output — cross-build succeeded)
```

### [API-4] Record S10 Sources and Transcript

#### Problem

The standalone contract has no implemented S10 source paths.

#### Solution

Add actual CLI/config paths and S10 evidence without restating shared runtime semantics. Run a temp-fixture transcript covering the full command surface, stable errors, and the no-unselected-start invariant.

#### Modified Files and Checklist

- [x] `agent-contract/inner/iop-agent-cli-runtime.md` — record actual S10 sources/tests and evidence.

#### Test Strategy

API-2/API-3 tests are the contract evidence; no additional test file is added.

#### Verification

```bash
build/bin/iop-agent --help
build/bin/iop-agent validate --repo-config configs/iop-agent.runtime.yaml --local-config /tmp/iop-agent-cli/local.yaml --provider-catalog configs/iop-agent.providers.yaml
```

Expected: help lists the full surface and validate succeeds against the prepared temp fixture.

Verified:

```
iop-agent --help: lists validate, provider, project, milestone, preview, serve, start, stop, resume, status
validate: ok
  revision: sha256:ebbd6ff31d789f5e2f37a9940785da56a3b42dd3092272cc978ce11a2f278b8b
  projects: 1
  providers: 2
  profiles: 3
no-unselected-start: "start: start: project iop-s0 has no selected milestone" (exit 1)
unsupported output format: "unsupported output format: xml" (exit 1)
missing config: "read repo-global config: open /nonexistent/runtime.yaml: no such file or directory" (exit 1)
```

## Dependencies and Execution Order

Predecessors `14+13_cli_config_fixtures`, `16+13,15_bootstrap_composition`, and `18+14,15_cli_command_tree` must each produce a same-group active or archived `complete.log`.

## Modified Files Summary

| File | Item |
|------|------|
| `apps/agent/cmd/agent/main.go` | API-3 |
| `apps/agent/cmd/agent/main_test.go` | API-3 |
| `Makefile` | API-3 |
| `agent-contract/inner/iop-agent-cli-runtime.md` | API-4 |

## Final Verification

```bash
gofmt -w apps/agent/cmd/agent/*.go
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
go vet ./apps/agent/cmd/agent ./apps/agent/internal/command
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
git diff --check
```

Expected: fresh tests, race, vet, local/Darwin builds, help transcript, and diff check pass. After completing all changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
