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

# Immutable Change-set Serial Integration

## For the Implementing Agent

`10+06_state_recovery/complete.log`와 `11+06_workspace_overlay/complete.log` 모두 필요하다. review stub의 implementation sections만 채운다.

## Background

manager has an `Integrator` port and deterministic queue, but no backend freezes overlay content or atomically applies/rolls back a three-way merge against a pinned base.

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

## Analysis

### Files Read

- `packages/go/agenttask/integration_queue.go`
- `packages/go/agenttask/integration_queue_test.go`
- `packages/go/agenttask/review.go`
- `packages/go/agenttask/types.go`
- `packages/go/agenttask/ports.go`
- `packages/go/agentguard/types.go`
- `agent-contract/inner/agent-runtime.md`
- `agent-roadmap/sdd/automation-runtime-bridge/iop-agent-cli-runtime/SDD.md`

### SDD Criteria

S19/Evidence Map S19: immutable additions/modifications/deletions/mode/symlink, dispatch ordinal, clean merge, conflict/unmanaged drift/post-apply validation rollback, terminal-deferred queue advance and restart idempotency.

### Test Environment Rules

local rules were read. Backend tests use temporary Git fixture repositories; tests must detect and skip only when `git` is absent after recording `command -v git`.

### Test Coverage Gaps

Current `integration_queue_test.go` verifies port ordering and fake outcomes only; it never mutates a canonical base or validates rollback.

### Split Judgment

overlay produces the immutable source, durable state stores IntegrationRecord. Apply/validate/rollback must be one atomic correctness boundary, hence one G10 packet.

### Scope Rationale

provider invocation, artifact review and workspace grants remain unchanged. This does not introduce branch/index fallback as default behavior.

### Final Routing

`first-pass`; cloud G10. temporal-state, concurrent-consistency, boundary-contract risk; official cloud G10 review.

## Implementation Checklist

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

### [API-1] immutable change set backend을 구현한다

**Problem:** `integration_queue.go` correctly orders opaque `ChangeSetIdentity`, but its fake integrator cannot prove atomic file application or retained failure state.

**Solution:** extend `agentworkspace` with freeze/apply/rollback implementation and connect it to `agenttask.Integrator`. Persist expected/observed fingerprints, validation and attempt identity through the durable state store; a failure returns retained terminal-deferred, never partial completion.

**Test Strategy:** temporary Git fixtures cover clean disjoint merge, same-file conflict, unmanaged base drift, failed post-apply validation rollback, queue progress, retained overlay and restart replay.

**Verification:** fresh race test passes; canonical base digest is unchanged after every rejected integration.

## Modified Files Summary

| File | Item |
|---|---|
| `packages/go/agentworkspace/change_set.go` | API-1 |
| `packages/go/agentworkspace/integrator.go` | API-1 |
| `packages/go/agentworkspace/integrator_test.go` | API-1 |
| `packages/go/agenttask/integration_queue.go` | API-1 |
| `packages/go/agenttask/integration_queue_test.go` | API-1 |
| `packages/go/agentstate/store.go` | API-1 |

## Dependencies and Execution Order

`10+06_state_recovery`와 `11+06_workspace_overlay` PASS 뒤에만 구현한다.

## Final Verification

```bash
command -v git
go test -count=1 -race ./packages/go/agentworkspace ./packages/go/agentstate ./packages/go/agenttask
git diff --check
```

After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
