---
name: sync-agent-ui
description: 정합화된 agent-ui 변경분을 코드에 직접 반영하거나 plan/roadmap으로 라우팅하고 plan·Milestone 작업 매핑과 완료 후 상태 정합화를 소유한다. agent-ui와 코드 동기화, 화면정의서대로 코드 반영, agent-ui 코드 작업 준비·완료 정합화 요청에 사용한다.
---

# sync-agent-ui

## 목적

정합화된 `agent-ui/` 변경분을 실제 UI 코드에 반영한다.
기본 동작은 `.sync-state.json`의 `last_synced_head` 이후 agent-ui 변경분만 반영하며, 사용자가 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다.
코드 반영 전에 코드 작업 규모를 판정해 작은 작업은 직접 반영하고, 중간 작업은 `plan` 루프로, Milestone이 필요한 큰 코드 작업은 `update-roadmap`의 Milestone/Epic/Task 갱신으로 넘긴다.
`plan-required` 작업은 일반 plan/code-review 문서에 agent-ui 전용 section을 넣지 않는다. 대신 plan pair 생성 직후 `prepare-code-work`로 task와 agent-ui 문서를 매핑하고, 일반 code-review PASS와 `complete.log` 생성 뒤 `reconcile-completion`으로 status/code evidence를 정합화한다.
`milestone-required` 작업도 일반 Milestone 문서에 agent-ui 전용 완료 필드를 넣지 않는다. `update-roadmap`이 확정한 활성 Milestone을 `prepare-milestone-work`로 매핑하고, 종료 직전 `complete-milestone check-only` 근거를 받은 `reconcile-milestone-completion`이 status/code evidence를 정합화한다.

## 언제 호출할지

- 사용자가 "agent-ui와 코드 동기화", "화면정의서대로 코드 반영", "wireframe 변경사항 구현"을 요청할 때
- `update-agent-ui` 또는 `validate-agent-ui`가 code sync 필요성을 판단했고 현재 범위에 미해결 USER_REVIEW가 없을 때
- 사용자가 "agent-ui와 코드 전체 동기화"처럼 full sync를 명시할 때
- `plan-required`로 생성된 task와 agent-ui 문서의 연결을 기록할 때
- 일반 code-review PASS 뒤 생성된 `complete.log`를 agent-ui status/code evidence에 반영할 때
- `milestone-required`로 확정된 활성 Milestone과 agent-ui 문서를 연결할 때
- Milestone 종료 감사 통과 후보의 agent-ui 상태를 실제 종료 전에 정합화할 때

## 입력

- `mode`: `incremental`, `full`, `prepare-code-work`, `reconcile-completion`, `prepare-milestone-work`, `reconcile-milestone-completion` 중 하나. 기본값은 `incremental` (선택)
- `scope`: `all`, `view:<view-id>`, `component:<component-id>` 중 하나. 기본값은 `all` (선택)
- `validated`: `true` 또는 `false`. 기본값은 `false` (선택)
- `sync-intent-source`: `manual`, `update-agent-ui`, `validate-agent-ui` 중 하나 (선택)
- `execution-route`: `auto`, `direct-sync`, `plan-required`, `milestone-required` 중 하나. 기본값은 `auto` (선택)
- `task-path`: `agent-task/` 기준 원래 active task 경로. `prepare-code-work`와 `reconcile-completion`에서 필수
- `previous-task-path`: plan refinement/reindex 전에 pending entry가 가리키던 active task 경로. `prepare-code-work` rebind에서만 선택
- `milestone-path`: `agent-roadmap/phase/*/milestones/*.md`의 정확한 활성 Milestone 경로. Milestone prepare/reconcile에서 필수
- `agent-ui-docs`: 완료 시 `구현됨`으로 전환할 활성 view/component 문서 목록. `prepare-code-work`에서 필수
- `frame-docs`: 함께 검증할 활성 frame-view 문서 목록. `prepare-code-work`에서 선택
- `code-paths`: 구현 후보 또는 완료 evidence 코드 경로 목록. `prepare-code-work`에서 필수
- `verification-requirements`: 완료 정합화 전에 확인할 명령/기대 결과 목록. `prepare-code-work`에서 선택
- `completion-log`: 일반 code-review가 만든 정확한 `complete.log` 경로. `reconcile-completion`에서 필수
- `closure-evidence`: 같은 Milestone에 대해 `complete-milestone mode=check-only`가 반환한 종료 가능 근거와 검증 요약. `reconcile-milestone-completion`에서 필수
- `validation-evidence`: `update-agent-ui` 후 실행한 `validate-agent-ui` PASS 근거. `reconcile-completion`에서 필수
- `sync-result-head`: agent-ui와 코드 결과를 모두 포함한다고 검증된 commit hash. `reconcile-completion`에서 선택
- `push`: `true` 또는 `false`. `incremental|full`에서만 사용하며 기본값은 `true` (선택)

## 먼저 확인할 것

- [ ] `agent-ops/rules/common/rules-agent-ui.md`를 읽는다.
- [ ] `agent-ui/`와 `agent-ui/definition/index.md` 존재 여부를 확인한다.
- [ ] `mode=incremental|full|prepare-code-work|prepare-milestone-work`이고 `validated=true`가 아니면 먼저 `validate-agent-ui`를 실행한다.
- [ ] `agent-ui/USER_REVIEW.md`가 있으면 현재 sync 범위와 관련된 미해결 항목이 없는지 확인한다.
- [ ] `agent-ui/.sync-state.json`을 읽는다. 없고 `mode=incremental|prepare-code-work|reconcile-completion|prepare-milestone-work|reconcile-milestone-completion`이면 legacy baseline migration 필요로 보고 중단한다.
- [ ] `schema_version: 1|2|3`이면 bundled state helper가 기존 필드와 pending 매핑을 보존·정규화하고 `schema_version: 4`로 올리게 한다.
- [ ] `.sync-state.json`을 갱신하는 모든 모드에서 `agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py`를 사용한다. shared state를 수동 read-modify-write하지 않는다.
- [ ] `mode=incremental|full`이면 현재 sync 대상 agent-ui 경로 또는 그 상·하위 경로가 code/Milestone pending entry의 `status_paths` 또는 `frame_paths`와 겹치지 않는지 확인한다. 겹치면 direct sync를 시작하지 않고 기존 pending owner 흐름으로 돌린다.
- [ ] `mode=incremental|full`이면 수정할 UI 코드 경로에 해당하는 project/domain rule을 먼저 읽는다.
- [ ] `mode=incremental|full`이고 코드 변경 검증이 필요하면 작업 환경의 `agent-test/<env>/rules.md`를 읽는다. 환경 미지정은 `local`로 본다.
- [ ] `mode=prepare-code-work`이면 exact active `PLAN-*-G??.md`와 matching `CODE_REVIEW-*-G??.md`가 `task-path`에 존재하는지 확인한다.
- [ ] `mode=reconcile-completion`이면 원래 `task-path`, exact `completion-log`가 존재하고 matching pending entry가 정확히 하나인지 확인한다.
- [ ] `mode=prepare-milestone-work`이면 `update-roadmap`이 확정한 exact active `milestone-path`가 존재하는지 확인한다.
- [ ] `mode=reconcile-milestone-completion`이면 같은 `milestone-path`의 pending entry와 `complete-milestone check-only` closure evidence가 있는지 확인한다.
- [ ] `git status --short`와 현재 `HEAD`를 확인한다.
- [ ] unrelated dirty worktree가 있으면 sync commit 전에 범위를 보고하고, agent-ui와 관련 코드 파일만 stage한다.
- [ ] 이전 sync 실패로 남은 관련 작업트리 변경이 있으면 보존할지, 사용자 결정과 충돌하는지 확인한다.

## 실행 절차

### prepare-code-work 절차

1. **task 매핑 검증**
   - `task-path`의 active PLAN/review pair가 같은 task header를 갖고 아직 verdict가 없는지 확인한다.
   - `agent-ui-docs`는 현재 활성 view/component 문서이고 status가 `계획`인지 확인한다. `가정`, `불명확`, 이미 archive 된 문서는 매핑하지 않는다.
   - `frame-docs`는 visual source가 있는 활성 frame-view 문서인지 확인하고 대응 view가 `agent-ui-docs`에 포함됐는지 확인한다. frame-view 자체에는 status를 요구하거나 `구현됨` 전환을 적용하지 않는다.
   - `code-paths`는 실제 구현 후보로 좁혀진 경로만 기록한다. 존재하지 않는 새 파일 후보는 경로와 생성 의도가 plan에 명시된 경우에만 허용한다.
   - 기존 pending task가 `refine-plans`로 분할되거나 sibling reindex로 경로가 바뀌었으면 원래 매핑을 그대로 둘 수 없다. status 대상 전체를 닫는 child를 하나만 고르고 기존 경로를 `previous-task-path`, 그 child 경로를 `task-path`로 전달한다.

2. **pending entry 기록**
   - `agent-ui/.sync-state.json`의 SHA-256을 계산한 뒤 bundled helper의 `prepare` 명령에 `--expected-sha256`으로 넘긴다. helper는 agent-ui 디렉터리 잠금을 잡은 다음 digest를 다시 확인한다.
   - 같은 `task_path`와 같은 내용은 idempotent `already_prepared`로 허용한다.
   - 같은 `task_path`의 내용이 다르면 helper가 중단한다. follow-up plan으로 범위가 실제 바뀐 것을 확인한 경우에만 `--replace`를 사용한다.
   - `previous-task-path`를 전달하면 helper가 기존 pending entry를 새 `task-path`로 원자적으로 rebind한다. scope/status/frame/code/verification 매핑이 달라지면 전체 결과를 닫는 child인지 검증한 뒤에만 `--replace`를 함께 사용한다.
   - 하나의 `status_path` 또는 `frame_path`를 둘 이상의 pending task가 소유하려 하면 helper가 중단한다.

```json
{
  "task_path": "agent-task/<task-name>",
  "scope": "<scope>",
  "status_paths": ["agent-ui/definition/views/.../index.md"],
  "frame_paths": ["agent-ui/frame/views/.../index.md"],
  "code_paths": ["<code path>"],
  "verification_requirements": ["<command>: <expected result>"],
  "prepared_at": "<ISO-8601>",
  "state": "pending"
}
```

```bash
python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py prepare \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --task-path agent-task/<task-name> \
  --scope <scope> \
  --status-path agent-ui/definition/views/<view-id>/index.md \
  --frame-path agent-ui/frame/views/<view-id>/index.md \
  --code-path <code-path> \
  --verification-requirement '<command>: <expected result>' \
  --prepared-at <ISO-8601>
```

   - `--status-path`와 `--code-path`는 필요한 만큼 반복하고, frame이 없으면 `--frame-path`를 생략한다.
   - refinement/reindex rebind에서는 `--previous-task-path agent-task/<old-task-name>`을 추가한다.

3. **state 경계 유지**
   - helper가 `schema_version`을 `4`로 올리고 code/Milestone pending·reconciled 기록과 baseline 필드를 보존하게 한다.
   - 이 모드는 `last_synced_head`, agent-ui status, code evidence를 바꾸지 않고 commit/push하지 않는다.
   - 일반 plan/review 문서에는 agent-ui 전용 completion section이나 review 전용 status 전환 지시를 추가하지 않는다.

### reconcile-completion 절차

1. **완료 이벤트 매칭**
   - exact `completion-log`가 `agent-task/archive/**/complete.log`에 있고 header task가 원래 `task-path`와 일치하며 loop history에 terminal PASS/RESOLVED가 있는지 확인한다.
   - 입력된 원래 `task-path`를 `pending_code_work[].task_path`와 exact match한다. archive destination suffix나 `completion-log` 경로에서 원래 task path를 역추정하지 않는다.
   - zero/multiple match이면 agent-ui 문서를 추측해 갱신하지 않는다.

2. **완료 evidence 검증**
   - pending entry의 모든 `code_paths`가 실제 존재하고 agent-ui 정의를 구현한 근거인지 확인한다.
   - `completion-log`의 최종 검증과 `verification_requirements`가 충족됐는지 확인한다.
   - generic `complete.log`에 agent-ui 전용 section이 없어도 정상으로 본다. 필요한 매핑은 pending entry에서만 읽는다.
   - evidence가 부족하면 entry를 `pending`으로 유지하고 일반 plan/review artifact를 수정하지 않는다.

3. **agent-ui 상태 반영**
   - pending entry의 `status_paths`에 있는 view/component 문서마다 `update-agent-ui`를 `status=구현됨`, 실제 code evidence, `post-validate=false`, `post-sync=false`로 실행한다.
   - `frame_paths`에는 status를 쓰지 않는다. 대응 definition과 visual source 연결을 검증 대상으로만 사용한다.
   - 모든 문서 갱신 뒤 `validate-agent-ui`를 matching scope, `sync-intent=skip`으로 실행하고 PASS 근거를 `validation-evidence`로 고정한다.
   - 갱신이나 검증이 실패하면 pending entry를 제거하지 않고 `agent-ui/USER_REVIEW.md`에 `Source Skill: sync-agent-ui`, `Stage: completion-reconcile`로 차단 근거를 남긴다.

4. **pending entry 종료**
   - 갱신과 검증이 모두 통과한 뒤 `.sync-state.json`의 최신 SHA-256을 다시 계산하고 bundled helper의 `reconcile` 명령을 실행한다.
   - helper가 matching pending entry를 제거하고 `reconciled_code_work`에 `task_path`, exact `completion_log`, scope, status/frame/code paths, validation evidence를 기록하게 한다.
   - helper가 `last_sync_mode`을 `plan-reconcile`, `last_synced_at`, `agent_ui_paths`, `code_paths`, `notes`를 완료 근거로 갱신하게 한다.
   - `sync-result-head`가 실제 commit이고 matching agent-ui/code 결과를 모두 포함하는지 검증된 경우에만 `last_synced_head`를 그 값으로 갱신한다. 그렇지 않으면 기존 `last_synced_head`를 보존하고 notes에 기준점 미갱신 사유를 남긴다.
   - 이미 같은 `task_path`와 `completion-log`가 `reconciled_code_work`에 있으면 helper의 idempotent `already_reconciled` 결과를 사용한다.
   - 이 모드는 일반 plan/review/complete.log를 수정하거나 commit/push하지 않는다.

```bash
python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py reconcile \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --task-path agent-task/<task-name> \
  --completion-log agent-task/archive/<YYYY>/<MM>/<task-path>/complete.log \
  --validation-evidence '<validate-agent-ui PASS evidence>' \
  --reconciled-at <ISO-8601>
```

   - 검증된 결과 commit이 있을 때만 `--sync-result-head <commit>`을 추가한다.

### Milestone 매핑과 완료 정합화 절차

1. **Milestone 작업 준비**
   - `execution-route=milestone-required`이면 코드 구현을 시작하지 않고 먼저 `update-roadmap`으로 활성 Milestone을 생성하거나 정확히 하나를 선택한다.
   - 일반 Milestone 문서에는 agent-ui 전용 완료 필드나 status 전환 지시를 쓰지 않는다.
   - `agent-ui-docs`, `frame-docs`, `code-paths`, `verification-requirements`를 `prepare-code-work`와 같은 기준으로 검증한다.
   - `.sync-state.json`의 최신 SHA-256과 exact active `milestone-path`를 bundled helper의 `prepare-milestone`에 전달한다.
   - 같은 Milestone과 같은 매핑은 `already_prepared`로 허용하고, 실제 scope/evidence 변경을 확인한 경우에만 `--replace`를 사용한다.

```bash
python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py prepare-milestone \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --milestone-path agent-roadmap/phase/<phase>/milestones/<milestone>.md \
  --scope <scope> \
  --status-path agent-ui/definition/views/<view-id>/index.md \
  --frame-path agent-ui/frame/views/<view-id>/index.md \
  --code-path <code-path> \
  --verification-requirement '<command>: <expected result>' \
  --prepared-at <ISO-8601>
```

2. **종료 직전 정합화**
   - caller/router는 Milestone 종료 요청에서 먼저 `complete-milestone mode=check-only`를 실행한다. 종료 가능 판정과 실제 검증 근거가 없으면 이 모드를 실행하지 않는다.
   - `closure-evidence`에는 exact `milestone-path`, check-only 판정, 코드레벨 감사, 실행한 검증 결과, spec check-only 결과를 식별 가능하게 요약한다. 재시도 idempotency를 위해 실행 시각처럼 의미 없는 가변 값은 넣지 않는다.
   - pending entry의 모든 `code_paths`와 `verification_requirements`가 check-only 근거와 현재 checkout에서 충족되는지 다시 확인한다.
   - `status_paths`의 view/component만 `update-agent-ui status=구현됨`과 실제 code evidence로 갱신하고, `frame_paths`는 연결 정합성만 검증한다.
   - 모든 문서 갱신 뒤 `validate-agent-ui sync-intent=skip`을 실행한다. 실패하면 pending entry를 유지하고 Milestone close를 호출하지 않는다.

3. **Milestone pending 종료**
   - 갱신과 검증이 통과한 뒤 최신 state SHA-256과 closure/validation evidence를 helper의 `reconcile-milestone`에 전달한다.
   - helper가 matching entry를 `pending_milestone_work`에서 `reconciled_milestone_work`로 이동하고 완료 근거를 기록한다.
   - 성공 또는 같은 evidence의 `already_reconciled` 뒤에만 caller/router가 `complete-milestone mode=close`를 실행한다. close가 다시 감사를 통과하지 못하면 roadmap 상태를 추측해 바꾸지 않는다.
   - 이 모드는 일반 Milestone 문서와 complete-milestone 결과를 수정하지 않고 commit/push하지 않는다.

```bash
python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py reconcile-milestone \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --milestone-path agent-roadmap/phase/<phase>/milestones/<milestone>.md \
  --closure-evidence '<complete-milestone check-only closure evidence>' \
  --validation-evidence '<validate-agent-ui PASS evidence>' \
  --reconciled-at <ISO-8601>
```

   - 검증된 결과 commit이 있을 때만 `--sync-result-head <commit>`을 추가한다.

### incremental/full 절차

1. **동기화 범위 확정**
   - `.sync-state.json`이 없고 `mode=incremental`이면 현재 agent-ui를 legacy baseline 후보로 본다.
   - legacy baseline 후보는 `validate-agent-ui` 통과 후 agent-ui baseline commit과 `.sync-state.json` commit을 남기는 migration으로 처리하고, 같은 실행에서 코드 반영은 하지 않는다.
   - `mode=incremental`이면 `.sync-state.json.last_synced_head` 이후 현재 `HEAD`/worktree까지의 agent-ui 변경분을 확인한다.
   - 변경분 판정에서 `agent-ui/.sync-state.json` 자체는 제외한다.
   - `mode=full`이면 현재 활성 `agent-ui/definition/**`과 `agent-ui/frame/**` 전체를 코드와 대조한다.
   - `mode=full`에서 `.sync-state.json`이 없으면 code sync 성공 후 새 sync state를 만든다.
   - `가정` 또는 `불명확` 상태 항목은 코드 반영 대상에서 제외하고 USER_REVIEW로 남긴다.
   - 현재 범위에 미해결 USER_REVIEW가 있으면 중단한다.
   - 확정된 sync 대상 agent-ui 경로 트리가 `pending_code_work` 또는 `pending_milestone_work`의 `status_paths`/`frame_paths`와 하나라도 겹치면 direct sync 대상으로 가져오지 않는다. 해당 pending task/Milestone의 완료 정합화 흐름을 사용한다.

2. **코드 반영 방식 판정**
   - 이 판정은 agent-ui 문서 작업의 크기가 아니라, 정합화된 agent-ui 변경분을 코드에 반영하는 구현 작업의 크기와 위험만 대상으로 한다.
   - `execution-route=auto`이면 코드 반영 대상의 크기와 위험을 `direct-sync`, `plan-required`, `milestone-required` 중 하나로 판정한다.
   - `direct-sync`는 다음 조건을 모두 만족할 때만 사용한다.
     - 단일 view/component/frame 또는 한 화면 안의 국소 변경이다.
     - 기존 route, shell, navigation, shared state, design token, package boundary를 그대로 사용한다.
     - 새 정보구조, 새 주요 workflow, 새 공통 component 체계, 제품 방향 결정이 필요 없다.
     - 변경 후보 코드가 소수 파일로 좁혀지고 검증 명령이 명확하다.
   - `plan-required`는 목표와 범위는 명확하지만 독립 리뷰 가능한 구현 루프가 필요할 때 사용한다.
     - 여러 view/component에 걸친 반영, shared component 추출, route/shell 조정, 테스트/검증 보강, UI 상태와 코드 변경을 함께 다루는 작업이 여기에 속한다.
     - 이 경우 직접 코드 반영을 시작하지 않고 `plan` 스킬로 전환한다.
     - plan에는 일반 구현 범위, 코드 후보, 검증 기준만 넘긴다.
     - plan pair가 생성되면 이 스킬의 `prepare-code-work`를 실행해 반영 대상 agent-ui 문서, 코드 후보, verification requirement를 task에 매핑한다.
     - 일반 code-review PASS와 `complete.log` 생성 뒤 caller/router/runtime가 `reconcile-completion`을 실행해 mapped agent-ui 문서를 `구현됨`으로 전환한다.
   - `milestone-required`는 코드 구현이 제품 UI 구조나 장기 작업 단위까지 바꾸는 경우 사용한다.
     - navigation/information architecture 재정렬, 외부 제품 UI 분석 기반 재설계, 여러 workflow/role/surface를 묶는 작업, 활성 Milestone 범위 밖 작업이 여기에 속한다.
     - 이 경우 직접 코드 반영과 plan 생성을 시작하지 않고 `update-roadmap`으로 Milestone/Epic/Task 배치를 먼저 남긴다.
     - exact active Milestone이 확정되면 `prepare-milestone-work`로 UI 매핑을 `.sync-state.json`에 남긴다. Milestone 문서에는 agent-ui 전용 완료 필드를 추가하지 않는다.
   - `plan-required` 판정 시 `prepare-code-work` pending entry 외에는 agent-ui 문서 status, baseline sync state, commit/push를 갱신하지 않는다.
   - `milestone-required` 판정 시 agent-ui 문서 status와 baseline sync state, commit/push를 갱신하지 않고 `pending_milestone_work` 매핑만 기록한다.

3. **코드 반영**
   - 이 단계는 `execution-route=direct-sync`일 때만 수행한다. `plan-required` 또는 `milestone-required` 판정이면 Step 2의 라우팅 결과를 보고하고 해당 스킬 흐름으로 전환한다.
   - `계획` 상태의 view/component 요구사항과 연결된 frame의 layout 근거를 UI 코드에 반영한다.
   - existing component, route, shell, widget 구조를 우선하고 새 구조를 임의로 만들지 않는다.
   - definition이 요구하는 정보 우선순위, region, action, state, component 참조를 코드 반영 기준으로 삼는다.
   - wireframe/frame은 layout, density, visual relationship 보조 근거로만 사용하고 definition을 대체하지 않는다.

4. **검증**
   - 관련 domain rule과 agent-test rule에 맞는 최소 검증을 실행한다.
   - 검증 실패가 명확하고 에이전트가 해결 가능하면 수정과 검증을 반복한다.
   - 구현 방향 충돌, 환경/권한 차단, 반복 실패, 사용자 판단이 필요한 시각 결과는 `agent-ui/USER_REVIEW.md`에 남기고 중단한다.
   - USER_REVIEW로 중단하면 commit/push하지 않고 `.sync-state.json`도 갱신하지 않는다.
   - USER_REVIEW로 중단할 때 관련 작업트리 변경은 사용자 결정과 충돌하지 않으면 보존하고, 재개 진입점과 변경 파일을 USER_REVIEW에 남긴다.
   - `execution-route=direct-sync`에서 코드 반영과 검증이 모두 통과한 항목은 이 스킬 실행 안에서 agent-ui 문서의 `status`를 `구현됨`으로 갱신하고 Source Evidence에 코드 경로를 남긴다.

5. **sync state와 commit/push**
   - 이 단계는 `execution-route=direct-sync`에서 코드 반영, 검증, agent-ui status/code evidence 갱신이 모두 통과한 경우에만 수행한다.
   - commit 전에 state를 다시 읽어 direct sync 대상이 새 pending entry의 소유 경로와 겹치지 않는지 재확인한다. 겹치면 commit하지 않고 충돌 경로와 pending owner를 보고한다.
   - 검증이 통과하면 agent-ui/code 변경을 먼저 commit한다.
   - `.sync-state.json`이 없으면 `agent-ops/skills/common/_templates/agent-ui/sync-state-template.json` 기준으로 새로 만든다.
   - 방금 만든 sync 결과 commit hash와 `.sync-state.json`의 최신 SHA-256을 bundled helper `record-sync`에 넘긴다.
   - helper가 lock 안에서 pending 소유 경로와의 겹침을 다시 거부한 뒤 `last_sync_mode`, `last_synced_head`, `last_synced_at`, `agent_ui_paths`, `code_paths`, `notes`를 갱신하고 기존 code/Milestone pending·reconciled 기록을 보존하게 한다.

```bash
python3 agent-ops/skills/common/sync-agent-ui/scripts/sync_state.py record-sync \
  --state agent-ui/.sync-state.json \
  --expected-sha256 <sha256> \
  --sync-mode <incremental|full> \
  --sync-result-head <sync-result-commit> \
  --synced-at <ISO-8601> \
  --agent-ui-path <agent-ui-path> \
  --code-path <code-path> \
  --note '<sync evidence>'
```

   - agent-ui/code 경로와 note는 필요한 만큼 옵션을 반복한다.
   - legacy baseline migration은 `--sync-mode migration`을 사용하고 code 반영이 없으면 `--code-path`를 생략한다.
   - `.sync-state.json` 변경을 별도 commit한다.
   - commit message는 예를 들어 `sync: apply agent-ui to code`와 `sync: record agent-ui sync state`처럼 목적이 분리되게 쓴다.
   - `push=true`이면 두 commit을 push한다.

6. **결과 보고**
   - sync mode와 scope
   - execution route와 판정 근거
   - 반영한 agent-ui 파일과 코드 파일
   - 변경한 status
   - 실행한 검증
   - sync 결과 commit hash와 sync-state commit/push 결과
   - USER_REVIEW 생성/갱신 여부

## 실행 결과 검증

- [ ] `validate-agent-ui`가 먼저 실행되었거나 `validated=true` 근거가 있는가
- [ ] 현재 sync 범위에 미해결 USER_REVIEW가 없는가
- [ ] 코드 반영 전에 `direct-sync`, `plan-required`, `milestone-required` 중 하나로 판정했는가
- [ ] `plan-required` 판정에서 직접 코드 변경, status 구현됨 전환, baseline sync state 갱신, commit/push를 하지 않고 pending entry만 기록했는가
- [ ] `milestone-required` 판정에서 직접 코드 변경, status 구현됨 전환, baseline sync state 갱신, commit/push를 하지 않고 exact Milestone pending mapping만 기록했는가
- [ ] `direct-sync` 판정에서 코드 반영과 검증이 통과한 항목은 같은 실행 안에서 agent-ui 문서 status를 `구현됨`으로 바꾸고 code evidence를 남겼는가
- [ ] `direct-sync` 대상이 code/Milestone pending owner의 status/frame path와 겹치지 않는지 코드 변경 전과 commit 전 확인했는가
- [ ] `prepare-code-work`가 exact task path와 활성 agent-ui 문서를 unique pending entry로 기록했는가
- [ ] refinement/reindex된 pending task는 전체 결과를 닫는 child 하나로 rebind되어 이전 task path가 남지 않았는가
- [ ] view/component는 `status_paths`, frame-view는 validation-only `frame_paths`로 분리했는가
- [ ] 하나의 status/frame path가 둘 이상의 pending task에 배정되지 않았는가
- [ ] state helper에 inspection 시점 SHA-256을 전달해 directory lock 안에서 concurrent/stale write를 차단했는가
- [ ] `prepare-code-work`가 일반 plan/review 문서에 agent-ui 전용 completion section을 요구하지 않았는가
- [ ] `reconcile-completion`이 exact completion log, code path, verification requirement를 확인했는가
- [ ] `reconcile-completion`이 `update-agent-ui` 다음 `validate-agent-ui sync-intent=skip` 순서로 실행했는가
- [ ] reconcile 실패 시 pending entry를 유지하고 성공 시에만 제거했는가
- [ ] reconcile 성공과 idempotency를 `reconciled_code_work`로 판정했는가
- [ ] Milestone mapping은 roadmap 문서가 아니라 `pending_milestone_work`에만 기록했는가
- [ ] Milestone reconcile 전에 `complete-milestone check-only`의 closure-ready 근거를 확인했는가
- [ ] Milestone reconcile 성공 뒤에만 caller/router가 `complete-milestone close`로 진행하는가
- [ ] 검증되지 않은 `sync-result-head`로 `last_synced_head`를 바꾸지 않았는가
- [ ] `가정` 또는 `불명확` 항목을 코드로 반영하지 않았는가
- [ ] `direct-sync`로 코드 반영된 항목의 status가 `구현됨`이고 code evidence가 있는가
- [ ] `direct-sync` 관련 검증이 통과했는가
- [ ] 실패 또는 차단 시 commit/push와 `.sync-state.json` 갱신을 하지 않았는가
- [ ] 실패 또는 차단 시 재개 진입점과 남은 변경 파일이 USER_REVIEW에 기록되었는가
- [ ] `direct-sync` 성공 시 sync 결과 commit과 `.sync-state.json` commit이 분리되었는가
- [ ] `direct-sync` 성공 시 `.sync-state.json.last_synced_head`가 sync 결과 commit hash를 가리키는가
- [ ] direct-sync/baseline state 갱신도 helper를 사용해 code/Milestone pending·reconciled 기록을 보존했는가
- [ ] unrelated dirty file이 sync commit에 포함되지 않았는가
- 검증 실패 시: 에이전트가 해결할 수 없으면 `agent-ui/USER_REVIEW.md`에 남기고 중단한다.

## 출력 형식

```md
## agent-ui 코드 동기화 결과: <PASS|PLAN_REQUIRED|MILESTONE_REQUIRED|PREPARED|RECONCILED|ALREADY_RECONCILED|USER_REVIEW|FAIL>

- Mode: <incremental|full|prepare-code-work|reconcile-completion|prepare-milestone-work|reconcile-milestone-completion>
- Scope: <scope>
- Execution Route: <direct-sync|plan-required|milestone-required|not-applicable>
- Task Mapping: <task-path와 pending 상태 또는 없음>
- Milestone Mapping: <milestone-path와 pending 상태 또는 없음>
- Completion Log: <path 또는 없음>
- Closure Evidence: <Milestone check-only 근거 또는 없음>
- Agent UI Changes: <파일 목록 또는 없음>
- Code Changes: <파일 목록 또는 없음>
- Status Updates: <구현됨 전환 목록 또는 없음>
- Verification: <명령과 결과>
- Sync Commit: <hash 또는 없음>
- Sync State Commit/Push: <완료/생략/실패>
- State Transition: <prepared|already_prepared|replaced|rebound|reconciled|already_reconciled|없음>
- USER_REVIEW: <생성/갱신/없음>
- Remaining Issues: <목록 또는 없음>
```

## 금지 사항

- `validate-agent-ui`를 거치지 않고 코드 동기화를 시작하지 않는다.
- 미해결 USER_REVIEW가 있는 범위를 코드에 반영하지 않는다.
- `가정` 또는 `불명확` 상태 항목을 코드로 구현하지 않는다.
- `plan-required` 또는 `milestone-required`로 판정된 작업을 같은 `sync-agent-ui` 실행에서 직접 구현하지 않는다.
- 일반 plan/review/complete.log에 agent-ui 전용 completion schema나 status 전환 책임을 추가하지 않는다.
- 일반 Milestone 문서나 roadmap 스킬에 agent-ui 전용 완료 필드나 status 전환 책임을 추가하지 않는다.
- code/Milestone pending entry가 소유한 status/frame path를 direct sync로 반영하거나 `record-sync`하지 않는다.
- matching pending entry 없이 `complete.log`만 보고 agent-ui 문서를 추측해 갱신하지 않는다.
- frame-view 문서에 `status`를 추가하거나 `구현됨` 전환을 적용하지 않는다.
- `.sync-state.json`을 bundled helper 밖에서 수동 read-modify-write하지 않는다.
- refinement/reindex 뒤 이전 task path의 pending entry를 남기거나 같은 status/frame path를 여러 pending task에 중복 배정하지 않는다.
- reconcile 실패 시 pending entry를 제거하거나 `last_synced_head`를 추정하지 않는다.
- `complete-milestone check-only` 종료 가능 근거 없이 Milestone pending entry를 reconcile하거나 close를 계속하지 않는다.
- `execution-route=milestone-required`로 라우팅된 agent-ui 코드 작업의 일반 plan 완료만으로 agent-ui status를 일괄 `구현됨`으로 바꾸지 않는다. 종료 감사와 code evidence가 있는 항목만 반영한다.
- 검증 실패나 사용자 판단 차단 상태에서 commit/push하지 않는다.
- `.sync-state.json`을 agent-ui 변경분 판정 대상으로 삼지 않는다.
- 정의서와 충돌하는 wireframe만을 근거로 코드 구현을 확정하지 않는다.
- 실패한 sync의 작업트리 변경을 사용자 결정 없이 되돌리지 않는다.
