<!-- task=m-iop-agent-cli-runtime/12+10,11_change_set_integration plan=0 tag=API -->

# Code Review Reference - API

> **[IMPLEMENTING AGENT — READ FIRST]** Both predecessors must have `complete.log`. Fill implementation evidence and leave finalization to review.

## Overview

date=2026-07-28
task=m-iop-agent-cli-runtime/12+10,11_change_set_integration, 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:
  - `change-set-integration`: immutable change set and serial integration
- Completion mode: check-on-pass

## Implementation Item Completion

| Item | Status |
|---|---|
| API-1 immutable change set backend을 구현한다 | [x] |

## Implementation Checklist

- [x] Freeze a review-PASS overlay as content-addressed ChangeSet with base fingerprint, operations, write set and validation evidence.
- [x] Apply eligible change sets only by first dispatch ordinal under workspace integration lease.
- [x] Implement atomic three-way apply, post-apply validation and exact rollback on conflict/drift/validation failure.
- [x] Retain blocker overlay/record while allowing later independent ordinals to advance.
- [x] Add clean/disjoint, conflict, unmanaged drift, validation rollback, restart and revised retry matrices.
- [x] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

## Review-Only Checklist

> **[REVIEW AGENT ONLY]**

- [x] Append PASS/WARN/FAIL and verified routing signals.
- [x] Archive as `code_review_cloud_G10_0.log` and `plan_cloud_G10_0.log`.
- [ ] On PASS create `complete.log`, report `change-set-integration`, then archive this subtask.

## Deviations from Plan

None. The implementation uses the existing device-local state envelope for opaque, checksum-covered integration journals and adds no dependency or out-of-scope runtime surface.

## Key Design Decisions

- `Backend.Freeze` compares the retained task view with its pinned immutable snapshot, normalizes additions/modifications/deletions/mode/symlink operations, copies regular content into a read-only record, and derives the change-set identity from the complete record.
- `SerialIntegrator` keeps one CAS journal per physical workspace. The journal atomically owns the managed head fingerprint and exact idempotency-key attempt records, while manager state CAS preserves every journal.
- An `applying` record and exact rollback manifest are durable before canonical mutation. Conflict and unmanaged drift do not mutate the base; apply or validation failures restore every affected entry and require the restored full fingerprint to match the observed pre-apply fingerprint.
- Managed predecessor changes use `git merge-file` for clean regular-file three-way merges. Same-file conflict becomes retained terminal-deferred without changing the managed head, so later independent change sets can continue.
- The manager queue admits a candidate only after every lower workspace dispatch ordinal is completed or terminal-deferred. A revised immutable change-set identity advances the integration attempt, while exact restart replay retains the prior attempt and result.

## Reviewer Checkpoints

- Rejected integration has exact rollback/retained blocker and does not halt later independent ordinal integration.

## Verification Results

### `command -v git`

```text
/bin/git
```

### `go test -count=1 -race ./packages/go/agentworkspace ./packages/go/agentstate ./packages/go/agenttask`

```text
ok  	iop/packages/go/agentworkspace	17.611s
ok  	iop/packages/go/agentstate	1.082s
ok  	iop/packages/go/agenttask	2.681s
```

### `git diff --check`

```text
(no stdout/stderr; exit 0)
```

### Additional verification

`go test -count=3 -run '^(TestFreezeChangeSet|TestSerialIntegrator|TestIntegrationTerminalDeferred|TestIntegrationCandidate|TestRevisedChangeSet)' ./packages/go/agentworkspace ./packages/go/agenttask`

```text
ok  	iop/packages/go/agentworkspace	25.429s
ok  	iop/packages/go/agenttask	0.211s
```

`go test -count=1 ./packages/go/...`

```text
ok  	iop/packages/go/agentconfig	0.080s
ok  	iop/packages/go/agentguard	0.034s
ok  	iop/packages/go/agentpolicy	0.033s
ok  	iop/packages/go/agentprovider/catalog	0.076s
ok  	iop/packages/go/agentprovider/cli	34.858s
?   	iop/packages/go/agentprovider/cli/internal/testutil	[no test files]
ok  	iop/packages/go/agentprovider/cli/status	41.191s
ok  	iop/packages/go/agentruntime	0.718s
ok  	iop/packages/go/agentstate	0.111s
ok  	iop/packages/go/agenttask	2.040s
ok  	iop/packages/go/agentworkspace	15.251s
ok  	iop/packages/go/audit	0.007s
?   	iop/packages/go/auth	[no test files]
ok  	iop/packages/go/config	0.130s
?   	iop/packages/go/events	[no test files]
ok  	iop/packages/go/hostsetup	0.024s
?   	iop/packages/go/jobs	[no test files]
?   	iop/packages/go/metadata	[no test files]
ok  	iop/packages/go/observability	0.030s
?   	iop/packages/go/policy	[no test files]
ok  	iop/packages/go/streamgate	0.893s
?   	iop/packages/go/version	[no test files]
```

`go vet ./packages/go/...` and `gofmt -d` over all six implementation files produced no stdout/stderr and exited 0.

Repository E2E smoke and full-cycle execution are not applicable: this change is confined to host-neutral workspace/state/task packages and does not change a binary entrypoint, transport, provider invocation, configuration, or protobuf contract.

## Section Ownership

| Section | Owner |
|---|---|
| Implementation checklist/results/deviations/decisions | Implementing agent |
| Review checklist, verdict, archive and completion log | Review agent |

## Code Review Result

- Overall Verdict: FAIL
- Dimension Assessment:
  - Correctness: Fail
  - Completeness: Fail
  - Test coverage: Fail
  - API contract: Fail
  - Code quality: Pass
  - Implementation deviation: Fail
  - Verification trust: Pass
  - Spec conformance: Fail
- Findings:
  - Required — `packages/go/agentworkspace/integrator.go:611`: path-local comparison treats a parent directory as unchanged even when an already integrated predecessor added a descendant, and `applyPreparedChanges` then removes that parent recursively at line 877. A focused reviewer reproducer integrated `tree/new.txt` at ordinal 1, integrated an ordinal-2 change set that deleted the pinned-base `tree`, and observed `tree/new.txt` disappear. Detect descendant changes before directory deletion/type replacement and either preserve clean independent descendants or return a retained conflict; add the exact managed-predecessor regression.
  - Required — `packages/go/agentworkspace/integrator.go:811`: rollback captures only `ChangeSet.WriteSet`, while the validator receives the writable canonical root at line 334. If validation creates or modifies any path outside the write set and then fails, `restoreRollback` cannot restore the pre-apply workspace; the later fingerprint check reports an error but leaves the mutation behind, violating the Integrator guarantee that a Go error has no partial canonical mutation. Run validation in a non-mutating view or capture/restore every possible validator mutation, and add a regression where validation mutates an unrelated path before failing.
  - Required — `packages/go/agenttask/integration_queue.go:218`: `integrationCandidateReady` treats a lower-ordinal `blocked` or `stopped` work with no current change set as if it were completed or terminal-deferred. Those states can transition back to `ready`, retain their original dispatch ordinal, and later produce a change set after a higher ordinal has already integrated. Require every lower ordinal to reach `completed` or `terminal_deferred` before admitting the candidate, and cover blocked/stopped resume ordering.
- Routing Signals:
  - `review_rework_count=1`
  - `evidence_integrity_failure=false`
- Next Step: Invoke the plan skill with these raw findings and create the smallest freshly routed follow-up pair.
