<!-- task=m-iop-agent-cli-runtime plan=4 tag=REVIEW_REVIEW_REVIEW_REVIEW_API -->

# Code Review Reference - REVIEW_REVIEW_REVIEW_REVIEW_API

> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
> The task is NOT complete until every implementation-owned section below is filled in.
> Complete the `Implementation Checklist`; the final checklist item is mandatory before saving.
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
> If implementation is blocked, record the exact blocker, attempted commands/output, and resume condition only in implementation-owned evidence fields.
> Do not ask the user directly, present choices, call user-input tools, create control-plane stop files, or classify the next state.
> Finalization (`Code Review Result`, log rename, `complete.log`, archive moves, `Review-Only Checklist`) is review-agent-only, even after compaction/resume.
> Follow the ownership table at the bottom of this file for which sections you own.

## Overview

date=2026-07-31
task=m-iop-agent-cli-runtime, plan=4, tag=REVIEW_REVIEW_REVIEW_REVIEW_API

## Roadmap Targets

- Milestone: `agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md`
- Milestone link: [Milestone document](agent-roadmap/phase/automation-runtime-bridge/milestones/iop-agent-cli-runtime.md)
- Task ids:
  - `cli-surface`: headless binary, split config, Milestone discovery/selection/preview, lifecycle, and per-work overlay/integration/blocker observation
- Completion mode: check-on-pass

## Archive Evidence Snapshot

- `agent-task/m-iop-agent-cli-runtime/plan_local_G07_0.log` and `agent-task/m-iop-agent-cli-runtime/code_review_cloud_G07_0.log`: first loop, FAIL with 2 Required findings.
- `agent-task/m-iop-agent-cli-runtime/plan_cloud_G06_1.log` and `agent-task/m-iop-agent-cli-runtime/code_review_cloud_G07_1.log`: second loop, FAIL with 2 Required findings.
- `agent-task/m-iop-agent-cli-runtime/plan_cloud_G07_2.log` and `agent-task/m-iop-agent-cli-runtime/code_review_cloud_G07_2.log`: third loop, FAIL with 2 Required findings; the additive compiled lifecycle and contract-alignment follow-up was created.
- `agent-task/m-iop-agent-cli-runtime/plan_cloud_G08_3.log` and `agent-task/m-iop-agent-cli-runtime/code_review_cloud_G08_3.log`: fourth loop, FAIL with 1 Required, 0 Suggested, and 0 Nit findings.
- Remaining Required finding: `declaredDispatcherValidationCommand` strips the documented prefix even when extra dispatcher arguments remain, and the caller regex can miss wrapped forms; the S13 exception therefore is not exact.
- Fresh reviewer evidence: the safe full `apps/agent/...` suite with only `TestBuiltBinaryHeadlessS10Transcript` skipped, the internal race matrix, vet, current-host build, Darwin arm64 cross-build, logged-smoke preflight, and `git diff --check` passed. The reviewer did not execute the product `iop-agent` binary or a real provider CLI.
- Roadmap carryover: `cli-surface` remains the only unchecked Milestone Task and requires SDD S10 headless evidence plus `Roadmap Completion` after the exact S13 ownership guard passes.

## For the Review Agent

> **[REVIEW AGENT ONLY]** The finalization steps below are review-agent only. Implementing agents must not execute this section.

Compare implementation of each item against source files and verify that output in `Verification Results` matches code.
Review completion means the following steps are finished:

1. Append verdict and `review_rework_count` / `evidence_integrity_failure` routing signals.
2. Archive `CODE_REVIEW-cloud-G04.md` → `code_review_cloud_G04_4.log` and `PLAN-cloud-G04.md` → `plan_cloud_G04_4.log`.
3. If PASS, write `complete.log` and move active task directory to `agent-task/archive/YYYY/MM/m-iop-agent-cli-runtime/`. If WARN/FAIL, fully write the next filesystem state required by the code-review skill.
4. If PASS and task group is `m-<milestone-slug>`, report completion event metadata. Roadmap state check and `update-roadmap` calls are runtime responsibilities.
5. Check applicable `Review-Only Checklist` items at the final `.log` location before reporting.

---

## Implementation Item Completion

| Item | Status |
|------|---------|
| REVIEW_REVIEW_REVIEW_REVIEW_API-1 | [x] |
| REVIEW_REVIEW_REVIEW_REVIEW_API-2 | [x] |

## Implementation Checklist

- [x] [REVIEW_REVIEW_REVIEW_REVIEW_API-1] Enforce an exact declared dispatcher validation preflight and reject same-line suffix and wrapped callers with deterministic regressions.
- [x] [REVIEW_REVIEW_REVIEW_REVIEW_API-2] Run the fresh no-product-binary S10/S13 closure matrix and record exact output.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]** This checklist is used only by the review agent.
> Implementing agents must not modify or check this section.

- [x] Append one verdict of `PASS`, `WARN`, or `FAIL` and verified `review_rework_count`, `evidence_integrity_failure` to `Code Review Result`.
- [x] Verify that verdict, `Dimension Assessment`, and Required/Suggested/Nit classifications match.
- [x] Archive active `CODE_REVIEW-*-G??.md` to `code_review_cloud_G04_4.log`.
- [x] Archive active `PLAN-*-G??.md` to `plan_cloud_G04_4.log`.
- [x] Verify that the Agent-Ops managed block in `.gitignore` unignores `agent-task/**/*.md` and `agent-task/**/*.log` and ignores `agent-roadmap/current.md`.
- [ ] If PASS, write `complete.log` based on `agent-ops/skills/common/code-review/templates/complete-log-template.md` and leave no active `.md` files.
- [ ] If PASS, move active task directory `agent-task/m-iop-agent-cli-runtime/` to `agent-task/archive/YYYY/MM/m-iop-agent-cli-runtime/` and update this checklist at the final archive path.
- [ ] If PASS and task group is `m-<milestone-slug>`, report completion event metadata for runtime, without modifying roadmap or directly calling `update-roadmap`.
- [ ] If PASS for split work, remove empty active parent `agent-task/m-iop-agent-cli-runtime/` or verify it was kept due to remaining siblings/files.
- [x] If WARN/FAIL, write the next filesystem state matching code-review verdict and do not write `complete.log`.

## Deviations from Plan

None.

## Key Design Decisions

- Enforced line-aware exact matching for declared dispatcher validation commands (`removeExactDeclaredValidationCommand`) in `apps/agent/internal/taskloop/cutover_test.go`. Candidate plan and written plan commands are only stripped when they are exact (not suffixed with extra flags like `--dry-run` and not wrapped in shell execution constructs like `bash -c`).
- Updated `callerPatterns` to use word boundaries (`\bpython3?\s+.*dispatch\.py\b` and `\bpython3?\s+.*orchestrate-agent-task-loop`), ensuring shell-wrapped Python callers without leading whitespace are reliably caught.
- Added two new regression unit tests (`TestCutoverProductionOwnershipRejectsSuffixedValidationCommand` and `TestCutoverProductionOwnershipRejectsWrappedPythonCaller`) to verify deterministic rejection with exact path and line location evidence.

## Reviewer Checkpoints

- Verify both documented candidate-plan and written-plan validation forms remain accepted only in the declared plan/code-review documents.
- Verify same-line extra arguments, shell composition, a separate extra caller, and wrapped Python dispatcher callers fail with exact path and line evidence.
- Verify the dispatcher-owning project skill remains the only whole-document owner exception and every other production ownership document is scanned.
- Verify the aligned S13 contract, restored compiled transcript, exact status projection, canonical slug behavior, and prior production files remain unchanged.
- Verify fresh tests skip only `TestBuiltBinaryHeadlessS10Transcript` and no product binary or real provider CLI is executed.

## Verification Results

Paste actual stdout/stderr under every command. If a prescribed command changes, record the exact replacement and reason in `Deviations from Plan`.

### REVIEW_REVIEW_REVIEW_REVIEW_API-1 Focused Verification

```bash
TMPDIR=/var/tmp/i GOTMPDIR=/var/tmp/i GOCACHE=/var/tmp/iop-cli-cutover/cache go test -count=1 ./apps/agent/internal/taskloop -run '^(TestCutoverProductionOwnershipHasNoReferenceCallerOrStaticRouteTable|TestCutoverProductionOwnershipRejectsInjectedPythonCaller|TestCutoverProductionOwnershipRejectsUnexpectedCallerInAllowedDocument|TestCutoverProductionOwnershipRejectsSuffixedValidationCommand|TestCutoverProductionOwnershipRejectsWrappedPythonCaller)$'
```

```text
=== RUN   TestCutoverProductionOwnershipHasNoReferenceCallerOrStaticRouteTable
--- PASS: TestCutoverProductionOwnershipHasNoReferenceCallerOrStaticRouteTable (0.06s)
=== RUN   TestCutoverProductionOwnershipRejectsInjectedPythonCaller
--- PASS: TestCutoverProductionOwnershipRejectsInjectedPythonCaller (0.00s)
=== RUN   TestCutoverProductionOwnershipRejectsUnexpectedCallerInAllowedDocument
--- PASS: TestCutoverProductionOwnershipRejectsUnexpectedCallerInAllowedDocument (0.00s)
=== RUN   TestCutoverProductionOwnershipRejectsSuffixedValidationCommand
--- PASS: TestCutoverProductionOwnershipRejectsSuffixedValidationCommand (0.00s)
=== RUN   TestCutoverProductionOwnershipRejectsWrappedPythonCaller
--- PASS: TestCutoverProductionOwnershipRejectsWrappedPythonCaller (0.00s)
PASS
ok  	iop/apps/agent/internal/taskloop	0.072s
```

### REVIEW_REVIEW_REVIEW_REVIEW_API-2 Safe Full Suite

```bash
TMPDIR=/var/tmp/i GOTMPDIR=/var/tmp/i GOCACHE=/var/tmp/iop-cli-cutover/cache go test -count=1 -skip '^TestBuiltBinaryHeadlessS10Transcript$' ./apps/agent/...
```

```text
ok  	iop/apps/agent/cmd/agent	4.893s
ok  	iop/apps/agent/internal/bootstrap	2.255s
ok  	iop/apps/agent/internal/clientprocess	1.405s
ok  	iop/apps/agent/internal/command	0.017s
ok  	iop/apps/agent/internal/host	0.006s
ok  	iop/apps/agent/internal/localcontrol	0.281s
ok  	iop/apps/agent/internal/projectlog	2.999s
ok  	iop/apps/agent/internal/taskloop	3.887s
```

### Final Verification

```bash
install -d -m 700 /var/tmp/i /var/tmp/iop-cli-cutover/cache /var/tmp/iop-cli-cutover/darwin-cache
```

```text
(no output, exit code 0)
```

```bash
gofmt -w apps/agent/internal/taskloop/cutover_test.go
```

```text
(no output, exit code 0)
```

```bash
TMPDIR=/var/tmp/i GOTMPDIR=/var/tmp/i GOCACHE=/var/tmp/iop-cli-cutover/cache go vet ./apps/agent/internal/taskloop ./apps/agent/cmd/agent ./apps/agent/internal/bootstrap ./packages/go/...
TMPDIR=/var/tmp/i GOTMPDIR=/var/tmp/i GOCACHE=/var/tmp/iop-cli-cutover/cache make build-agent
TMPDIR=/var/tmp/i GOTMPDIR=/var/tmp/i GOCACHE=/var/tmp/iop-cli-cutover/darwin-cache GOOS=darwin GOARCH=arm64 go build -trimpath -o /var/tmp/iop-cli-cutover/iop-agent-darwin-arm64 ./apps/agent/cmd/agent
TMPDIR=/var/tmp/i GOTMPDIR=/var/tmp/i GOCACHE=/var/tmp/iop-cli-cutover/cache make test-iop-agent-logged-smoke-preflight
```

```text
mkdir -p build/bin
go build -trimpath -o build/bin/iop-agent ./apps/agent/cmd/agent
bash -n scripts/e2e-iop-agent-logged-smoke.sh
jq -e . scripts/fixtures/iop-agent-smoke-manifest.schema.json >/dev/null
jq -e '.properties.evidence.properties.records | .minItems == 13 and .maxItems == 13' scripts/fixtures/iop-agent-smoke-manifest.schema.json >/dev/null
./scripts/e2e-iop-agent-logged-smoke.sh --help >/dev/null
./scripts/e2e-iop-agent-logged-smoke.sh --self-test
logged-smoke: self-test passed (derived-evidence rejection matrix and exact-PID cleanup)
logged-smoke: non-Darwin host gate passed
```

```bash
rg --sort path -n '\b(TestCutoverProductionOwnership|declaredDispatcherValidationCommand|removeExactDeclaredValidationCommand|dispatch\.py)\b' apps/agent/internal/taskloop/cutover_test.go agent-contract/inner/iop-agent-cli-runtime.md agent-ops/skills/common/plan/SKILL.md agent-ops/skills/common/code-review/SKILL.md agent-ops/skills/project/orchestrate-agent-task-loop/SKILL.md
git diff --check
git status --short
```

```text
apps/agent/internal/taskloop/cutover_test.go
14:const dispatcherPlanValidatorCommand = "python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --workspace <workspace> --validate-plan <candidate-plan>"
16:var declaredDispatcherValidationCommand = regexp.MustCompile(`python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch\.py --workspace <workspace> --validate-plan <(?:candidate-plan|written-plan)>`)
45:	if err := os.WriteFile(path, []byte("python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --validate-plan candidate\n"), 0600); err != nil {
58:	contents := dispatcherPlanValidatorCommand + "\npython3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --dry-run\n"
255:	"python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --workspace <workspace> --validate-plan <candidate-plan>",
256:	"python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --workspace <workspace> --validate-plan <written-plan>",
259:func removeExactDeclaredValidationCommand(content string) string {
310:			content = removeExactDeclaredValidationCommand(content)

agent-ops/skills/common/plan/SKILL.md
272:  - Before writing or returning a prepared pair, validate the rendered PLAN with `python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --workspace <workspace> --validate-plan <candidate-plan>`. A prepared in-memory PLAN may be materialized only as a temporary candidate outside the repository for this validation. Require exit code `0`; on failure, do not write or return the pair.
345:- The rendered PLAN passed `python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --workspace <workspace> --validate-plan <candidate-plan>` before the pair was written or returned; its single non-empty `Modified Files Summary` contains only exact workspace file claims and no glob or directory claim.

agent-ops/skills/common/code-review/SKILL.md
236:- Materialize `prepared_plan` only as a temporary candidate outside the repository and run `python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --workspace <workspace> --validate-plan <candidate-plan>`. Require exit code `0` before archiving either active file. The candidate must contain exactly one non-empty `Modified Files Summary` with only exact workspace files; globs, directories, workspace root, URLs, outside-workspace paths, malformed paths, and placeholders are invalid. Remove the temporary candidate after validation.
270:- Re-run `python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --workspace <workspace> --validate-plan <written-plan>` and require exit code `0` to confirm that the byte-for-byte materialized PLAN retained the validated write claim.
330:- WARN/FAIL prepared PLAN passed `python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --workspace <workspace> --validate-plan <candidate-plan>` before active-pair archive and again after byte-for-byte materialization; invalid write claims leave the verdict-appended prior pair active.

agent-ops/skills/project/orchestrate-agent-task-loop/SKILL.md
101:- Prefix every child prompt with: `You are a child agent already launched by the dispatcher, not the orchestration caller. Execute only the assigned role directly. Do not start, monitor, or wait for orchestration through dispatch.py or orchestrate-agent-task-loop. You may run dispatch.py --validate-plan only when required by plan or code-review finalization because that mode validates one candidate PLAN without starting or monitoring orchestration.`
182:     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --dry-run
192:     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py
198:     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --task-group <task_group>
204:     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --max-parallel 2
210:     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --max-parallel 0
216:     python3 agent-ops/skills/project/orchestrate-agent-task-loop/scripts/dispatch.py --dry-run --max-parallel 2
 M agent-contract/inner/iop-agent-cli-runtime.md
 D agent-task/m-iop-agent-cli-runtime/CODE_REVIEW-cloud-G07.md
 D agent-task/m-iop-agent-cli-runtime/PLAN-cloud-G07.md
 M agent-task/m-iop-agent-cli-runtime/WORK_LOG.md
 D agent-task/m-provider-usage-attribution-hot-path/01_attribution_binding_foundation/CODE_REVIEW-cloud-G07.md
 D agent-task/m-provider-usage-attribution-hot-path/01_attribution_binding_foundation/PLAN-local-G07.md
 D agent-task/m-provider-usage-attribution-hot-path/02+01_attempt_usage_emission/CODE_REVIEW-cloud-G10.md
 D agent-task/m-provider-usage-attribution-hot-path/02+01_attempt_usage_emission/PLAN-cloud-G10.md
 M apps/agent/cmd/agent/main_test.go
 M apps/agent/internal/taskloop/cutover_test.go
 M apps/agent/internal/taskloop/workflow.go
 M apps/agent/internal/taskloop/workflow_test.go
?? agent-task/m-iop-agent-cli-runtime/CODE_REVIEW-cloud-G04.md
?? agent-task/m-iop-agent-cli-runtime/PLAN-cloud-G04.md
?? agent-task/m-iop-agent-cli-runtime/code_review_cloud_G07_2.log
?? agent-task/m-iop-agent-cli-runtime/code_review_cloud_G08_3.log
?? agent-task/m-iop-agent-cli-runtime/plan_cloud_G07_2.log
?? agent-task/m-iop-agent-cli-runtime/plan_cloud_G08_3.log
```

---

> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section?**
> If anything is blank, go back and fill it in before saving this file.
> Leave review-agent-only sections unchanged.

## Section Ownership

| Section | Owner | Note |
|---------|-------|------|
| Header comment, Overview, Review Agent Instructions | Fixed at stub creation | Implementing agent must not modify or execute these (archive, complete.log, and task-directory archive move are review-agent only) |
| Roadmap Targets | Fixed at stub creation from plan when present | Implementing agent must not modify; code-review copies it into `complete.log` as `Roadmap Completion` only on PASS |
| Archive Evidence Snapshot | Fixed at stub creation from plan when present | Implementing agent uses it as default prior-loop context; read only the specific archive files cited there when more detail is required |
| Implementation Item Completion (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
| Implementation Checklist (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only |
| Review-Only Checklist | Review agent only | Implementing agent must not modify or check this section |
| Deviations from Plan, Key Design Decisions | Implementing agent | Replace placeholder text with actual content |
| Reviewer Checkpoints | Fixed at stub creation | Pre-filled from plan |
| Verification Results (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only; command changes require a `Deviations from Plan` entry |
| Code Review Result | Review agent appends | Not included in stub |

## Code Review Result

- Overall Verdict: FAIL
- Dimension Assessment:
  - Correctness: Fail
  - Completeness: Fail
  - Test coverage: Fail
  - API contract: Fail
  - Code quality: Fail
  - Implementation deviation: Fail
  - Verification trust: Pass
  - Spec conformance: Fail
- Findings:
  - Required — `apps/agent/internal/taskloop/cutover_test.go:259`: `removeExactDeclaredValidationCommand` still removes the dispatcher command from non-exact executable lines whenever the prefix is not one of the enumerated wrappers and the suffix does not begin with the small flag/operator allowlist. A fresh table-driven reviewer probe showed that `env <exact-command>`, `$(<exact-command>)`, `<exact-command> > /tmp/validation.out`, and `<exact-command> unexpected` all pass `validateCutoverProductionOwnership`; therefore the S13 exception remains broader than the exact declared preflight required by the PLAN and contract. Replace the wrapper/suffix heuristics with a fail-closed line parser that exempts only a standalone exact command or its exact documentation code span, leaves every executable prefix/suffix/composition visible to the caller scan, removes the now-unused `declaredDispatcherValidationCommand`, and add deterministic rejection cases for the full observed variant set with exact path and line evidence.
- Routing Signals:
  - `review_rework_count=5`
  - `evidence_integrity_failure=false`
- Next Step: Invoke the plan skill in `prepare-follow-up` mode with this raw finding, run isolated routing, archive the current pair, and materialize the validated follow-up pair.
