sync: agent-ops from agentic-framework v1.1.159

2026-06-30 14:59:53 +09:00 · 2026-06-30 14:59:53 +09:00 · f5c359a3da
commit f5c359a3da
parent 39dfab2030
10 changed files with 176 additions and 25 deletions
--- a/agent-ops/.version
+++ b/agent-ops/.version
@ -1 +1 @@
-1.1.158
+1.1.159
--- a/agent-ops/rules/common/rules-agent-ui.md
+++ b/agent-ops/rules/common/rules-agent-ui.md
@ -83,14 +83,18 @@ agent-ui/
 - 초기 생성 이후 기본 방향은 `agent-ui -> code` 단방향이다. 코드에서 agent-ui를 만드는 흐름은 `create-agent-ui` 최초 생성에만 사용한다.
 - 화면정의서, view, component, frame, wireframe을 agent로 수정하는 요청은 `update-agent-ui`로 처리한다.
 - 사용자 리뷰 결정 반영, `UIR-NNN` 해결, "화면정의서와 코드가 안 맞아" 같은 회귀 요청도 `update-agent-ui` 또는 `validate-agent-ui`로 들어와 같은 루프를 재개한다.
- `update-agent-ui` 후에는 변경 범위에 따라 `validate-agent-ui` 필요 여부를 판단한다. 실행한다면 `validate-agent-ui`가 항상 `sync-agent-ui`보다 먼저 실행된다.
+- `update-agent-ui`는 agent-ui 문서 갱신을 맡는다. 코드 구현 규모 판정, plan 라우팅, roadmap/milestone 라우팅은 하지 않는다.
+- `update-agent-ui` 후에는 변경 범위에 따라 `validate-agent-ui` 필요 여부와 code sync intent 전달 여부만 판단한다. 실행한다면 `validate-agent-ui`가 항상 `sync-agent-ui`보다 먼저 실행된다.
 - `validate-agent-ui`는 agent-ui 내부 문서 그래프를 정합화한다. definition, frame, visual source, component, archive, USER_REVIEW 사이의 누락과 충돌을 같은 수준으로 맞춘다.
 - 운영 단계의 `validate-agent-ui`는 코드 후보만 보고 새 view/component를 자동 생성하지 않는다. 코드와 agent-ui가 어긋나면 agent-ui 기준 sync 대상, status 회귀, 또는 USER_REVIEW로 분리한다.
- `sync-agent-ui`는 정합화된 agent-ui 변경분을 코드에 반영한다.
+- `sync-agent-ui`는 정합화된 agent-ui 변경분을 코드에 반영하기 전에 코드 작업 규모를 판정한다. 작은 코드 작업은 직접 반영하고, 중간 코드 작업은 `plan` 루프로, Milestone이 필요한 큰 코드 작업은 `update-roadmap`의 Milestone/Epic/Task 갱신으로 넘긴다.
 - `sync-agent-ui`의 기본 모드는 `.sync-state.json` 기준 이후 변경분만 동기화한다.
 - 사용자가 "agent-ui와 코드 전체 동기화"처럼 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다.
- `update-agent-ui` 또는 수동 `validate-agent-ui`가 코드 반영 필요성을 판단했으면 그 판단을 다음 단계로 전달한다. 전달된 판단이 있으면 뒤 단계는 같은 내용을 재판단하지 않는다.
- 코드 동기화가 완료되면 반영된 view/component의 `status`를 `구현됨`으로 바꾼다. 사용자 확인 또는 후속 검증에서 불일치가 발견되면 해당 항목은 `계획`으로 되돌릴 수 있다.
+- `update-agent-ui` 또는 수동 `validate-agent-ui`가 코드 반영 필요성을 판단했으면 그 판단을 다음 단계로 전달한다. 전달된 판단이 있으면 뒤 단계는 문서 정합성과 sync intent 자체를 재판단하지 않지만, `sync-agent-ui`는 실제 코드 반영 방식 판정을 수행한다.
+- 직접 sync가 검증되면 반영된 view/component의 `status`를 `구현됨`으로 바꾼다.
+- `sync-agent-ui`가 코드 작업을 `plan-required`로 라우팅한 경우에는 plan이 `Agent UI Completion`을 남기고, code-review PASS 시점에 해당 view/component/frame만 `구현됨`으로 반영한다. 이 경로에서는 `sync-agent-ui`가 status를 직접 변경하지 않는다.
+- `sync-agent-ui`가 코드 작업을 `milestone-required`로 라우팅해 `agent-ui 상태 반영: 대기`를 남긴 Milestone만 종료 검토 통과 시 `구현됨` 반영 gate가 된다. 최종 검증과 code evidence가 확인된 view/component/frame만 반영하며, Milestone 완료만으로 agent-ui 전체 status를 일괄 변경하지 않는다.
+- 사용자 확인 또는 후속 검증에서 불일치가 발견되면 해당 항목은 `계획`으로 되돌릴 수 있다.
 - `sync-agent-ui`가 검증 실패, 환경 차단, 구현 방향 충돌, 반복 실패를 스스로 해결하지 못하면 commit/push하지 않고 `agent-ui/USER_REVIEW.md`에 게이트를 남긴다.
 - 실패한 `sync-agent-ui`가 남긴 작업트리 변경은 사용자 결정과 충돌하지 않으면 보존하고, USER_REVIEW 해결 후 같은 변경을 이어서 재검증할 수 있다.

--- a/agent-ops/skills/common/_templates/roadmap-milestone-template.md
+++ b/agent-ops/skills/common/_templates/roadmap-milestone-template.md
@ -76,8 +76,15 @@ Task 체크리스트는 Epic 바로 아래의 flat list로 유지하고, 구현
 - 요청일: <YYYY-MM-DD | 없음>
 - 완료 근거: <모든 기능 Task와 Task 안에 명시된 검증 충족 및 구현 잠금 해제 여부를 1~3줄로 요약>
 - 검토 항목: <없음 | 에이전트/런타임이 확인할 완료 근거 또는 archive 조건>
+- agent-ui 상태 반영: <해당 없음 | 대기 | 완료 | 차단: 사유>
 - 리뷰 코멘트: <없음 | 보완/보류/폐기 방향성>

+<!--
+기본값은 `해당 없음`이다.
+`sync-agent-ui`가 코드 작업을 `milestone-required`로 라우팅했거나 사용자가 Milestone 종료 검토에서 agent-ui 구현 상태 반영을 명시한 경우에만 `대기`로 둔다.
+`대기`인 경우 Milestone 종료 검토에서 최종 검증과 code evidence가 확인된 agent-ui view/component/frame만 `구현됨`으로 반영한다.
+-->
+
 ## 범위 제외

 - <이 Milestone에서 의도적으로 하지 않는 일>
--- a/agent-ops/skills/common/code-review/SKILL.md
+++ b/agent-ops/skills/common/code-review/SKILL.md
@ -145,6 +145,8 @@ Count `agent-task/{task_name}/code_review_*.log` in the selected active task dir

 The diff is the starting point, not the boundary. Follow behavior and API connections far enough to judge correctness.

+If the active plan or review file contains `Agent UI Completion`, also read `agent-ops/rules/common/rules-agent-ui.md` and the listed active agent-ui documents. Do not read `agent-ui/definition/archive/**` or `agent-ui/archive/user-review/**` unless the review explicitly cites those archive paths.
+
 ## Step 3 - Pre-Review Checklist

 Before writing the verdict:
@ -155,6 +157,7 @@ Before writing the verdict:
 - Directly repair obvious non-behavioral source nits when safe: typos, stale comments, docs, or formatting only, with no behavior/test/API contract change.
 - If a checklist item contains integrated verification for a feature, treat that feature item as incomplete until both implementation evidence and the matching verification output are present. Do not accept a separate unchecked completion-criteria item as a substitute.
 - Confirm the implementation marked the matching checklist items in the active review file, including the final mandatory `CODE_REVIEW-*-G??.md` completion item; repair clear artifact drift when evidence supports completion.
+- If the active plan or review file contains `Agent UI Completion`, verify the implementation-owned fields are filled before PASS: listed agent-ui docs exist, actual code evidence paths exist, requested status updates are explicit, and implementation verification evidence is present. Missing or untrusted evidence is a completeness or verification-trust issue.
 - Treat review artifact gaps as failures only when they prevent judging implementation correctness, tests, contracts, or verification trust.
 - Read the `사용자 리뷰 요청` section. If `상태` is not `없음`, validate the exact decision needed, `연결 대상`, blocker evidence, command output or not-run reason, why automatic follow-up cannot resolve it, and resume condition before deciding whether the user-review gate triggers. Reject the request unless it is tied to a selected Milestone `구현 잠금 > 결정 필요` item.
 - Grep renamed/removed symbols for stale references.
@ -166,6 +169,8 @@ Before writing the verdict:

 Append `코드리뷰 결과` to the active `CODE_REVIEW-*-G??.md`.

+Before appending `PASS`, if all other PASS conditions are met and the active review file contains `Agent UI Completion`, perform the review-pass status update first: update the listed agent-ui docs to `구현됨`, add actual code evidence, run `validate-agent-ui`, and mark the section's review-agent-owned finalization items. If this update or validation fails, do not append `PASS`; classify the failure as `WARN` or `FAIL` and write the normal follow-up.
+
 Required fields:

 - `종합 판정`: exactly `PASS`, `WARN`, or `FAIL`.
@ -217,6 +222,7 @@ Complete log template:
 - Do not leave placeholders in `complete.log`.
 - If the task did not close through `USER_REVIEW.md`, remove the optional user-review row from the `루프 이력` table.
 - If the archived plan or review log contains `Roadmap Targets`, copy it into `complete.log` as `Roadmap Completion`. Include the Milestone path, completed Task ids, archived plan/review log paths, and verification evidence. If there is no `Roadmap Targets` section, remove the optional `Roadmap Completion` template section entirely and do not invent roadmap targets.
+- If the archived review log contains `Agent UI Completion`, copy the completed evidence into `complete.log`. If there is no `Agent UI Completion` section, remove the optional complete-log section entirely.
 - Use `없음` for empty `잔여 Nit` or `후속 작업`.
 - A PASS `complete.log` must not contain unresolved Required or Suggested issues. Nit-only leftovers may be recorded under `잔여 Nit`.

@ -242,6 +248,7 @@ If the user-review gate does not trigger, write new routed plan/review files usi
 - If follow-up verification involves mobile/UI hangs, timeouts, or no progress for 2 minutes, stop blind retries; require focused rerun output plus screenshot/window/UI-tree evidence path, or the exact reason capture is impossible.
 - Write an `Archive Evidence Snapshot` section in every WARN/FAIL follow-up plan. Copy enough prior-loop evidence from the archived plan/review logs for the next implementer to act without rereading archive by default: current archived plan/review log paths, verdict, Required/Suggested/Nit summary, affected files, verification evidence, and any roadmap carryover. If exact prior context is still required, cite the specific archive file paths allowed to read; do not instruct the implementer to search `agent-task/archive/**` broadly.
 - Copy the follow-up plan's `Archive Evidence Snapshot` section exactly into the follow-up review stub.
+- If the archived plan or review had `Agent UI Completion` and the follow-up still works toward the same agent-ui status update, include an updated `Agent UI Completion` section in the follow-up plan and review stub. If the follow-up intentionally no longer claims agent-ui status completion, omit the section and explain why in the follow-up plan `범위 결정 근거`.
 - Before choosing the follow-up route, apply this gate:
  - Keep the follow-up on `local` when all local allowlist conditions are true for the current fix; otherwise use `cloud`.
  - If the follow-up work is terminal-agent work that cannot be reduced to deterministic commands and evidence, use `cloud-G07` or higher.
@ -307,6 +314,25 @@ task={task_name}, plan={N}, tag={TAG}

 {copy the follow-up plan's 구현 체크리스트 items exactly, preserving order and checkbox text}

+## Agent UI Completion
+
+> Include this section only when the follow-up plan has `Agent UI Completion`; otherwise omit it entirely.
+> **[IMPLEMENTING AGENT]** Fill actual code evidence and implementation verification output for the listed docs.
+> **[REVIEW AGENT ONLY]** On PASS, update only the listed agent-ui docs to `구현됨`, add the listed code evidence, run `validate-agent-ui`, and copy this section into `complete.log`.
+
+- Mode: review-pass-status-update
+- Agent UI docs:
+  - `agent-ui/definition/views/<view-id>/index.md`
+- Actual code evidence:
+  - [ ] `<code path>`: <implemented evidence>
+- Implementation verification evidence:
+  - [ ] `<test or analysis command>`: <actual result or output path>
+- Status updates requested on PASS:
+  - [ ] `agent-ui/definition/views/<view-id>/index.md`: `계획` -> `구현됨`
+- Review finalization:
+  - [ ] Review agent updated the listed agent-ui docs and code evidence.
+  - [ ] Review agent ran `validate-agent-ui scope=<scope>` after the status/evidence update.
+
 ## 코드리뷰 전용 체크리스트

 > **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
@ -387,6 +413,7 @@ Sections and their ownership:
 | 헤더 주석, 개요(date/task/plan/tag), 리뷰 에이전트 지시 | 스텁 생성 시 고정 | 구현 에이전트가 수정하거나 실행하지 않음 |
 | Roadmap Targets | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 수정하지 않음; PASS 시 code-review가 `complete.log`의 `Roadmap Completion`으로 복사 |
 | Archive Evidence Snapshot | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트의 기본 이전 루프 컨텍스트; 추가 확인이 필요할 때 여기에 명시된 archive 파일만 좁게 읽음 |
+| Agent UI Completion | Mixed | Present only for agent-ui code work that should become `구현됨` on code-review PASS; implementing agent fills actual evidence, review agent applies the status/evidence update and copies the section into `complete.log` |
 | 구현 항목별 완료 여부 (항목명) | 스텁 생성 시 고정 | `[ ]` → `[x]` 체크만 구현 에이전트가 수행 |
 | 구현 체크리스트 (항목 텍스트/순서) | follow-up plan에서 복사해 스텁 생성 시 고정 | 구현 에이전트가 `[ ]` → `[x]` 체크만 수행; 마지막 체크박스는 저장 전 필수 |
 | 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
@ -405,6 +432,7 @@ After Step 6:
 - After moving a split subtask, remove the active parent `agent-task/{task_group}/` only if it is empty. If sibling subtask directories or other files remain, leave the parent task group in place.
 - If verdict is `PASS` and `{task_group}` matches `m-<milestone-slug>`, do not resolve the roadmap target and do not call `update-roadmap`. Report completion event metadata after the task archive move: `origin-task=agent-task/{task_name}` from the original active task path, `task-group={task_group}`, `milestone-slug=<milestone-slug>`, final archive path, `complete.log` path, archived plan/review log paths, and `roadmap-completion=<Task ids from complete.log or none>`.
 - The runtime consumes that completion event, checks current state, and calls `update-roadmap` if needed. `update-roadmap` only checks Milestone Task ids when `complete.log` contains `Roadmap Completion`; if the section is absent, roadmap Task completion is a no-op even for `m-*` task groups.
+- If verdict is `PASS` and the archived review log contains `Agent UI Completion`, ensure the listed agent-ui status/evidence update and `validate-agent-ui` check are complete before writing or finalizing `complete.log`. Do not defer this to runtime or Milestone completion.
 - `WARN` and `FAIL` do not update the roadmap Milestone; the follow-up plan remains under the same `m-<milestone-slug>` task group when the original task was Milestone-linked.
 - `USER_REVIEW` does not update the roadmap Milestone and does not produce PASS completion metadata. Keep the active task directory in place with `USER_REVIEW.md` and archived plan/review logs until the linked Milestone lock decision is resolved.
 - If `USER_REVIEW.md` is later resolved as complete/PASS by linked Milestone decision and evidence, write `complete.log`, move the task directory to archive, and report `m-*` PASS completion metadata just like a normal `PASS`.
@ -450,6 +478,8 @@ Report Required/Suggested counts, archive names, the final task archive path for
 - PASS milestone task group: `m-<milestone-slug>` completion event metadata was reported for runtime; roadmap was not modified by code-review.
 - PASS with `Roadmap Targets`: `complete.log` contains `Roadmap Completion` with Milestone path, Task ids, archived plan/review evidence, and verification evidence.
 - PASS without `Roadmap Targets`: `complete.log` omits `Roadmap Completion` and reported metadata says `roadmap-completion=none`.
+- PASS with `Agent UI Completion`: listed agent-ui docs were updated to `구현됨` with code evidence, `validate-agent-ui` passed, and `complete.log` contains `Agent UI Completion`.
+- PASS without `Agent UI Completion`: complete.log omits `Agent UI Completion`.
 - PASS split: empty active parent `agent-task/{task_group}/` removed after the subtask move; non-empty parent left in place.
 - WARN/FAIL without user-review gate: new active `PLAN-{build_lane}-GNN.md` and `CODE_REVIEW-{review_lane}-GNN.md` created with matching headers and matching `구현 체크리스트`; no `complete.log`.
 - WARN/FAIL follow-up: new active plan and review stub contain identical `Archive Evidence Snapshot` sections with prior archived plan/review log paths, verdict, issue summary, affected files, verification evidence, and specific archive paths allowed for narrow reread when needed.
--- a/agent-ops/skills/common/code-review/templates/complete-log-template.md
+++ b/agent-ops/skills/common/code-review/templates/complete-log-template.md
@ -32,6 +32,15 @@
  - `{task-id}`: PASS; evidence=`{archived-plan-log}`, `{archived-review-log}`; verification=`{command or saved output path}`
 - Not completed task ids: 없음

+## Agent UI Completion
+
+{optional; include only when archived review had Agent UI Completion. Remove this entire section when there is no Agent UI Completion.}
+
+- Agent UI docs:
+  - `{agent-ui/definition/views/<view-id>/index.md}`: `구현됨`; code evidence=`{code path}`; implementation verification=`{command or output path}`; validation=`{validate-agent-ui result or output path}`
+- Status updates: 완료
+- Remaining agent-ui issues: 없음
+
 ## 잔여 Nit

 - 없음
--- a/agent-ops/skills/common/create-roadmap/SKILL.md
+++ b/agent-ops/skills/common/create-roadmap/SKILL.md
@ -1,7 +1,7 @@
 ---
 name: create-roadmap
-version: 1.16.1
-description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, 로컬 current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하는 공통 스킬
+version: 1.17.0
+description: AI-first 개인/소규모 프로젝트의 전체 목표, Phase scaffold, Phase 하위 Milestone 문서, 로컬 current.md 활성 Phase/Milestone 창, archive Phase scaffold를 처음 생성하고, agent-ui 코드 동기화 Milestone의 완료 리뷰 상태 반영 항목을 포함하는 공통 스킬
 ---

 # 로드맵 생성
@ -112,6 +112,9 @@ agent-roadmap/
 - epic-id와 item-id는 공백 없는 짧은 ASCII 토큰이며, 해당 Milestone 안에서만 유일하면 된다.
 - 검증이 필요한 Task에만 같은 항목 안에 `검증: <명령/확인 방법/기대 결과>`를 붙인다. 검증이 필요 없는 기능에는 억지 검증을 붙이지 않는다.
 - `완료 리뷰`는 새 Milestone에서는 `상태: 없음`, `요청일: 없음`으로 두고, 모든 기능 Task와 Task 안에 명시된 검증이 충족되고 `구현 잠금`이 해제된 뒤 에이전트/런타임 완료 근거를 기록할 때 갱신한다. 에이전트가 확정할 수 없는 결정 항목은 완료 리뷰가 아니라 `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md`로 분리한다.
+- `agent-ui 상태 반영` 항목은 모든 신규 Milestone의 `완료 리뷰`에 두고 기본값은 `해당 없음`으로 적는다.
+- `sync-agent-ui`의 `milestone-required` 코드 작업 라우팅으로 생성/갱신하는 Milestone, 또는 사용자가 Milestone 종료 검토에서 agent-ui 구현 상태 반영을 명시한 Milestone만 `agent-ui 상태 반영: 대기`로 둔다.
+- `대기` Milestone은 종료 검토에서 최종 검증과 code evidence가 확인된 agent-ui view/component/frame만 `구현됨`으로 반영한다.
 - `범위`, `범위 제외`, `작업 컨텍스트`는 설명 목록으로 작성하고, 실행해야 할 작업을 이 섹션에 숨기지 않는다.

 ## 먼저 확인할 것
@ -165,6 +168,7 @@ agent-roadmap/
   - `check-gate` 결과는 `SDD gate` 항목에 `pass`, `review-required`, `blocked`, `invalid` 중 하나로 분리해 남긴다. `review-ready`로 만든 `USER_REVIEW.md` 때문에 막힌 경우는 `review-required`로 보고하고 형식 보완 실패로 보지 않는다.
   - `[검토중]` Milestone이 있다면 `구현 잠금`이 해제되어 있고 미완료 `결정 필요` 항목이 없는지 확인한다.
   - Milestone 문서에 `완료 리뷰` 섹션이 있는지 확인한다.
+   - `sync-agent-ui`의 `milestone-required` 코드 작업 라우팅으로 생성/갱신한 Milestone이면 `완료 리뷰`에 `agent-ui 상태 반영: 대기`가 있고, 그 외 Milestone은 `agent-ui 상태 반영: 해당 없음`인지 확인한다.

 ## 출력 형식

--- a/agent-ops/skills/common/plan/SKILL.md
+++ b/agent-ops/skills/common/plan/SKILL.md
@ -237,6 +237,23 @@ Required sections:
  - `<task-id>`: <Task text or concise label>
 - Completion mode: check-on-pass
 ```
+- `Agent UI Completion`: include this section only when the plan implements agent-ui definition/frame/component changes in code and code-review PASS should move specific agent-ui documents to `status: 구현됨`. Omit it for non-agent-ui work, `direct-sync` work handled entirely by `sync-agent-ui`, and `milestone-required` work whose status update is intentionally deferred to Milestone 종료 검토. Format exactly:
+
+```markdown
+## Agent UI Completion
+
+- Mode: review-pass-status-update
+- Agent UI docs:
+  - `agent-ui/definition/views/<view-id>/index.md`
+- Required code evidence:
+  - `<code path>`: <what proves the UI definition is implemented>
+- Required implementation verification:
+  - `<test or analysis command>`: PASS expected before review
+- Review finalization validation:
+  - `validate-agent-ui scope=<scope>`: PASS expected after status/evidence update
+- Status updates on PASS:
+  - `agent-ui/definition/views/<view-id>/index.md`: `계획` -> `구현됨`
+```
 - `분석 결과`: record the findings from Step 2 and Step 3. This section is the written output of the analysis — not a summary, but the actual findings that justify the plan's scope and decisions. Must include all of the following subsections:
  - `읽은 파일`: list every source and test file read during analysis, with path. List agent-test rule/profile files only when they were actually present and read.
  - `SDD 기준`: for `SDD: 필요` Milestones, list the SDD path, status, targeted Acceptance Scenario ids, their Milestone Task ids, and the Evidence Map rows that drive the plan. State explicitly how those rows shaped the implementation checklist and final verification. If the selected Milestone has `SDD: 불필요`, state the recorded reason. If the work is not Milestone-linked, state "not applicable".
@ -349,6 +366,25 @@ task={task_name}, plan={N}, tag={TAG}

 {copy the plan's 구현 체크리스트 items exactly, preserving order and checkbox text}

+## Agent UI Completion
+
+> Include this section only when the plan has `Agent UI Completion`; otherwise omit it entirely.
+> **[IMPLEMENTING AGENT]** Fill actual code evidence and implementation verification output for the listed docs.
+> **[REVIEW AGENT ONLY]** On PASS, update only the listed agent-ui docs to `구현됨`, add the listed code evidence, run `validate-agent-ui`, and copy this section into `complete.log`.
+
+- Mode: review-pass-status-update
+- Agent UI docs:
+  - `agent-ui/definition/views/<view-id>/index.md`
+- Actual code evidence:
+  - [ ] `<code path>`: <implemented evidence>
+- Implementation verification evidence:
+  - [ ] `<test or analysis command>`: <actual result or output path>
+- Status updates requested on PASS:
+  - [ ] `agent-ui/definition/views/<view-id>/index.md`: `계획` -> `구현됨`
+- Review finalization:
+  - [ ] Review agent updated the listed agent-ui docs and code evidence.
+  - [ ] Review agent ran `validate-agent-ui scope=<scope>` after the status/evidence update.
+
 ## 코드리뷰 전용 체크리스트

 > **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
@ -429,6 +465,7 @@ Sections and their ownership:
 | Header comment, 개요, 리뷰 에이전트 지시 | 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 |
+| Agent UI Completion | Mixed | Present only for plan-required agent-ui code work; implementing agent fills actual evidence, review agent applies `구현됨` status/evidence update on PASS and copies the section into `complete.log` |
 | 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
 | 구현 체크리스트 (item text/order) | Fixed at stub creation from plan | Implementing agent checks `[ ]` → `[x]` only; final checkbox is mandatory before saving |
 | 코드리뷰 전용 체크리스트 | Review agent only | Implementing agent must not modify or check this section |
@ -459,6 +496,7 @@ Sections and their ownership:
 - If resuming from `USER_REVIEW.md`, it was archived to `user_review_N.log` and the resolved linked Milestone decision was recorded in the new plan.
 - `Roadmap Targets` exists only when PASS should check explicit Milestone Task ids, the task group is `m-<milestone-slug>` for the listed Milestone path, and every listed Task id exists in the selected active Milestone.
 - If `Roadmap Targets` exists in the plan, the review stub contains the identical section. If it does not exist in the plan, the review stub omits it too.
+- If `Agent UI Completion` exists in the plan, the review stub contains the matching section with implementation-owned evidence fields. If it does not exist in the plan, the review stub omits it too.
 - If the selected Milestone has `SDD: 필요`, the plan's `분석 결과 > SDD 기준` proves that the implementation checklist and final verification were derived from the approved SDD Acceptance Scenarios and Evidence Map. Missing SDD mapping blocks plan creation.
 - If the plan is a follow-up or resumes from prior archive evidence, it has `Archive Evidence Snapshot` and the review stub contains the identical section.
 - `분석 결과 > 테스트 환경 규칙` records the selected test env, env rules read/missing/structural-blank/intentionally-unused state, matched profiles read when any, and any fallback verification source.
--- a/agent-ops/skills/common/sync-agent-ui/SKILL.md
+++ b/agent-ops/skills/common/sync-agent-ui/SKILL.md
@ -1,7 +1,7 @@
 ---
 name: sync-agent-ui
-version: 1.0.0
-description: 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-state.json 기준점을 갱신한다. "agent-ui와 코드 동기화", "화면정의서대로 코드 반영" 요청 시 사용한다.
+version: 1.1.0
+description: 정합화된 agent-ui 변경분을 코드에 직접 반영하거나, 코드 작업 규모에 따라 plan 또는 roadmap/milestone 작업으로 라우팅한다. 직접 반영이 검증된 경우에만 .sync-state.json 기준점을 갱신한다. "agent-ui와 코드 동기화", "화면정의서대로 코드 반영" 요청 시 사용한다.
 ---

 # sync-agent-ui
@ -10,6 +10,8 @@ description: 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-sta

 정합화된 `agent-ui/` 변경분을 실제 UI 코드에 반영한다.
 기본 동작은 `.sync-state.json`의 `last_synced_head` 이후 agent-ui 변경분만 반영하며, 사용자가 전체 동기화를 명시한 경우에만 현재 agent-ui 전체를 코드와 대조한다.
+코드 반영 전에 코드 작업 규모를 판정해 작은 작업은 직접 반영하고, 중간 작업은 `plan` 루프로, Milestone이 필요한 큰 코드 작업은 `update-roadmap`의 Milestone/Epic/Task 갱신으로 넘긴다.
+`plan-required` 또는 `milestone-required`로 라우팅한 경우에는 이 스킬 실행 안에서 코드 구현, status 전환, sync state 갱신, commit/push를 하지 않는다.

 ## 언제 호출할지

@ -23,6 +25,7 @@ description: 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-sta
 - `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` (선택)
 - `push`: `true` 또는 `false`. 기본값은 `true` (선택)

 ## 먼저 확인할 것
@ -50,21 +53,42 @@ description: 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-sta
   - `가정` 또는 `불명확` 상태 항목은 코드 반영 대상에서 제외하고 USER_REVIEW로 남긴다.
   - 현재 범위에 미해결 USER_REVIEW가 있으면 중단한다.

-2. **코드 반영**
+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에는 반영 대상 agent-ui 문서, 코드 후보, 최종 `validate-agent-ui`, code evidence 기준을 포함한다.
+     - plan이 만드는 `CODE_REVIEW-*-G??.md`에는 `Agent UI Completion` 섹션을 넣어 code-review PASS 때 listed agent-ui 문서를 `구현됨`으로 전환하게 한다.
+   - `milestone-required`는 코드 구현이 제품 UI 구조나 장기 작업 단위까지 바꾸는 경우 사용한다.
+     - navigation/information architecture 재정렬, 외부 제품 UI 분석 기반 재설계, 여러 workflow/role/surface를 묶는 작업, 활성 Milestone 범위 밖 작업이 여기에 속한다.
+     - 이 경우 직접 코드 반영과 plan 생성을 시작하지 않고 `update-roadmap`으로 Milestone/Epic/Task 배치를 먼저 남긴다.
+     - 이 Milestone에는 `완료 리뷰`의 `agent-ui 상태 반영: 대기`를 남기고, `status: 구현됨` 전환은 plan 완료가 아니라 Milestone 종료 검토 항목으로 둔다.
+   - `plan-required` 또는 `milestone-required`로 판정하면 agent-ui 문서 status를 `구현됨`으로 바꾸지 않고, sync state와 commit/push도 갱신하지 않는다.
+
+3. **코드 반영**
+   - 이 단계는 `execution-route=direct-sync`일 때만 수행한다. `plan-required` 또는 `milestone-required` 판정이면 Step 2의 라우팅 결과를 보고하고 해당 스킬 흐름으로 전환한다.
   - `계획` 상태의 view/component/frame 요구사항을 UI 코드에 반영한다.
   - existing component, route, shell, widget 구조를 우선하고 새 구조를 임의로 만들지 않는다.
   - definition이 요구하는 정보 우선순위, region, action, state, component 참조를 코드 반영 기준으로 삼는다.
   - wireframe/frame은 layout, density, visual relationship 보조 근거로만 사용하고 definition을 대체하지 않는다.
-   - 코드 반영이 끝난 항목은 agent-ui 문서의 `status`를 `구현됨`으로 갱신하고 Source Evidence에 코드 경로를 남긴다.

-3. **검증**
+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에 코드 경로를 남긴다.

-4. **sync state와 commit/push**
+5. **sync state와 commit/push**
+   - 이 단계는 `execution-route=direct-sync`에서 코드 반영, 검증, agent-ui status/code evidence 갱신이 모두 통과한 경우에만 수행한다.
   - 검증이 통과하면 agent-ui/code 변경을 먼저 commit한다.
   - 방금 만든 sync 결과 commit hash를 `agent-ui/.sync-state.json`의 `last_synced_head`에 기록한다.
   - `.sync-state.json`이 없으면 `agent-ops/skills/common/_templates/agent-ui/sync-state-template.json` 기준으로 새로 만든다.
@ -73,8 +97,9 @@ description: 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-sta
   - commit message는 예를 들어 `sync: apply agent-ui to code`와 `sync: record agent-ui sync state`처럼 목적이 분리되게 쓴다.
   - `push=true`이면 두 commit을 push한다.

-5. **결과 보고**
+6. **결과 보고**
   - sync mode와 scope
+   - execution route와 판정 근거
   - 반영한 agent-ui 파일과 코드 파일
   - 변경한 status
   - 실행한 검증
@ -85,23 +110,28 @@ description: 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-sta

 - [ ] `validate-agent-ui`가 먼저 실행되었거나 `validated=true` 근거가 있는가
 - [ ] 현재 sync 범위에 미해결 USER_REVIEW가 없는가
+- [ ] 코드 반영 전에 `direct-sync`, `plan-required`, `milestone-required` 중 하나로 판정했는가
+- [ ] `plan-required` 또는 `milestone-required` 판정에서 직접 코드 변경, status 구현됨 전환, sync state 갱신, commit/push를 하지 않았는가
+- [ ] `direct-sync` 판정에서 코드 반영과 검증이 통과한 항목은 같은 실행 안에서 agent-ui 문서 status를 `구현됨`으로 바꾸고 code evidence를 남겼는가
+- [ ] `plan-required` 판정에서 생성될 `CODE_REVIEW-*-G??.md`에 `Agent UI Completion` 섹션으로 status 전환 규칙을 넘겼는가
 - [ ] `가정` 또는 `불명확` 항목을 코드로 반영하지 않았는가
- [ ] 코드 반영된 항목의 status가 `구현됨`이고 code evidence가 있는가
- [ ] 관련 검증이 통과했는가
+- [ ] `direct-sync`로 코드 반영된 항목의 status가 `구현됨`이고 code evidence가 있는가
+- [ ] `direct-sync` 관련 검증이 통과했는가
 - [ ] 실패 또는 차단 시 commit/push와 `.sync-state.json` 갱신을 하지 않았는가
 - [ ] 실패 또는 차단 시 재개 진입점과 남은 변경 파일이 USER_REVIEW에 기록되었는가
- [ ] 성공 시 sync 결과 commit과 `.sync-state.json` commit이 분리되었는가
- [ ] `.sync-state.json.last_synced_head`가 sync 결과 commit hash를 가리키는가
+- [ ] `direct-sync` 성공 시 sync 결과 commit과 `.sync-state.json` commit이 분리되었는가
+- [ ] `direct-sync` 성공 시 `.sync-state.json.last_synced_head`가 sync 결과 commit hash를 가리키는가
 - [ ] unrelated dirty file이 sync commit에 포함되지 않았는가
 - 검증 실패 시: 에이전트가 해결할 수 없으면 `agent-ui/USER_REVIEW.md`에 남기고 중단한다.

 ## 출력 형식

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

 - Mode: <incremental|full>
 - Scope: <scope>
+- Execution Route: <direct-sync|plan-required|milestone-required>
 - Agent UI Changes: <파일 목록 또는 없음>
 - Code Changes: <파일 목록 또는 없음>
 - Status Updates: <구현됨 전환 목록 또는 없음>
@ -117,6 +147,8 @@ description: 정합화된 agent-ui 변경분을 코드에 반영하고 .sync-sta
 - `validate-agent-ui`를 거치지 않고 코드 동기화를 시작하지 않는다.
 - 미해결 USER_REVIEW가 있는 범위를 코드에 반영하지 않는다.
 - `가정` 또는 `불명확` 상태 항목을 코드로 구현하지 않는다.
+- `plan-required` 또는 `milestone-required`로 판정된 작업을 같은 `sync-agent-ui` 실행에서 직접 구현하지 않는다.
+- `execution-route=milestone-required`로 라우팅된 agent-ui 코드 작업의 일반 plan 완료만으로 agent-ui status를 일괄 `구현됨`으로 바꾸지 않는다. 종료 검토 통과와 code evidence가 있는 항목만 반영한다.
 - 검증 실패나 사용자 판단 차단 상태에서 commit/push하지 않는다.
 - `.sync-state.json`을 agent-ui 변경분 판정 대상으로 삼지 않는다.
 - 정의서와 충돌하는 wireframe만을 근거로 코드 구현을 확정하지 않는다.
--- a/agent-ops/skills/common/update-agent-ui/SKILL.md
+++ b/agent-ops/skills/common/update-agent-ui/SKILL.md
@ -1,7 +1,7 @@
 ---
 name: update-agent-ui
-version: 1.1.0
-description: 화면정의서, view, component, frame, wireframe 내용을 agent로 수정하고 후속 validate/sync 필요성을 판단하는 스킬
+version: 1.1.1
+description: 화면정의서, view, component, frame, wireframe 내용을 agent로 수정하고 후속 validate 필요성과 sync intent 전달 여부를 판단하는 스킬
 ---

 # update-agent-ui
@ -10,7 +10,8 @@ description: 화면정의서, view, component, frame, wireframe 내용을 agent

 기존 `agent-ui/`의 화면정의서와 wireframe 관련 문서를 갱신한다.
 사용자가 "화면정의서에 X 추가", "wireframe에 사이드바 추가"처럼 agent-ui 명사를 쓰지 않아도 UI 정의 문서 수정 요청이면 이 스킬을 사용한다.
-오래된 결정이 현재 기준을 흐리면 archive log로 분리하고, 변경 후 `validate-agent-ui`와 `sync-agent-ui` 필요성을 판단한다.
+오래된 결정이 현재 기준을 흐리면 archive log로 분리하고, 변경 후 `validate-agent-ui` 필요성과 code sync intent 전달 여부를 판단한다.
+코드 구현 규모 판정, plan 라우팅, roadmap/milestone 라우팅은 `sync-agent-ui` 책임이며 이 스킬에서 수행하지 않는다.

 ## 언제 호출할지

@ -84,7 +85,7 @@ description: 화면정의서, view, component, frame, wireframe 내용을 agent
   - 해결된 항목은 `agent-ui/archive/user-review/user_review_N.log`로 이동하고, 활성 `USER_REVIEW.md`에는 미해결 항목만 남긴다. 남은 항목이 없으면 활성 `USER_REVIEW.md`를 제거할 수 있다.
   - sync 실패 후 남은 작업트리 변경이 있고 사용자 결정과 충돌하지 않으면 보존한 채 후속 validate/sync에서 이어간다.

-5. **후속 validate/sync 판단**
+5. **후속 validate와 sync intent 판단**
   - `post-validate=false`가 아니고 view/component/frame/wireframe/source evidence/status 중 하나라도 바뀌었으면 `validate-agent-ui`를 실행한다.
   - `post-validate=true`이면 변경 크기와 무관하게 `validate-agent-ui`를 실행한다.
   - `post-sync=true` 또는 코드 반영이 필요한 `계획` 상태 변경이 있으면 sync intent를 `validate-agent-ui`에 전달한다.
@ -92,6 +93,7 @@ description: 화면정의서, view, component, frame, wireframe 내용을 agent
   - 후속 단계가 실행되면 순서는 항상 `validate-agent-ui` 다음 `sync-agent-ui`다.
   - 현재 변경 범위에 미해결 USER_REVIEW가 있으면 `sync-agent-ui`를 실행하지 않고 차단 항목을 보고한다.
   - 사용자가 "화면정의서와 코드가 안 맞아"처럼 불일치를 보고하면 관련 항목을 `계획`으로 되돌릴지 확인하고 validate/sync intent를 만든다.
+   - sync intent를 만들더라도 코드 반영 방식이 direct-sync, plan-required, milestone-required 중 무엇인지는 판단하지 않는다.

 6. **결과 보고**
   - 수정한 활성 정의 문서
@ -149,5 +151,6 @@ description: 화면정의서, view, component, frame, wireframe 내용을 agent
 - `.excalidraw` 파일만 만들고 frame index를 생략하지 않는다.
 - visual source 없이 빈 frame-view 문서를 만들지 않는다.
 - agent-ui 갱신과 무관한 앱 구현 파일을 수정하지 않는다.
+- 코드 구현 규모에 따라 plan 또는 roadmap/milestone 라우팅을 확정하지 않는다.
 - `validate-agent-ui`를 거치지 않고 `sync-agent-ui`를 실행하지 않는다.
 - sync 실패 후 남은 코드 변경을 사용자 결정 없이 되돌리지 않는다.
--- a/agent-ops/skills/common/update-roadmap/SKILL.md
+++ b/agent-ops/skills/common/update-roadmap/SKILL.md
@ -1,7 +1,7 @@
 ---
 name: update-roadmap
-version: 1.21.0
-description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 로컬 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, 완료 근거 충족 archive 이동, workspace 외부 의존 잠금 양방향 동기화를 처리한다.
+version: 1.22.0
+description: 로드맵 업데이트, 로드맵에 추가, 마일스톤 추가/갱신, phase/페이즈 변경 요청에 사용한다. Roadmap-Phase-Milestone scaffold에서 target 없는 신규 작업의 규모를 판정하고 기존 Phase/Milestone/Epic/Task를 검색해 upsert한 뒤, 없을 때만 새 항목을 만들고 로컬 current.md 동기화, runtime m-task 완료 이벤트 반영, 완료 후보 검토중 전환, agent-ui 코드 동기화 Milestone의 종료 검토 시 구현됨 상태 반영, 완료 근거 충족 archive 이동, workspace 외부 의존 잠금 양방향 동기화를 처리한다.
 ---

 # 로드맵 업데이트
@ -195,6 +195,21 @@ agent-roadmap/
 - 보류 또는 폐기 근거가 있으면 `완료 리뷰`와 Milestone 상태를 각각 `보류`/`[보류]`, `폐기`/`[폐기]`로 맞춘다. `[폐기]`는 archive 대상이 될 수 있다.
 - Phase는 하위 Milestone이 모두 `[완료]` 또는 `[폐기]`로 정리되고 Phase 목표도 충족된 것으로 보일 때 `[완료]` 또는 `[폐기]`로 archive한다.

+### agent-ui 코드 동기화 Milestone 완료 리뷰
+
+- 이 절은 `sync-agent-ui`가 코드 작업을 `milestone-required`로 라우팅했거나 사용자가 명시해 Milestone `완료 리뷰`에 `agent-ui 상태 반영: 대기`가 있는 경우에만 적용한다.
+- agent-ui 문서만 갱신한 Milestone, 작은 `direct-sync` 작업, 일반 `plan-required` 작업, `agent-ui 상태 반영: 해당 없음`인 Milestone에는 적용하지 않는다.
+- 기존 Milestone에 `agent-ui 상태 반영` 항목이 없으면 `해당 없음`으로 취급한다. 문서 구조 보정 또는 해당 Milestone 갱신 범위에 포함될 때만 `agent-ui 상태 반영: 해당 없음`을 보강한다.
+- 사용자가 "이 Milestone을 종료해도 될지 검토", "마일스톤 완료 검토", "종료 검토"처럼 완료 리뷰를 요청했거나 `review-state=통과`로 갱신할 때 적용한다.
+- agent-ui 코드 동기화 Milestone이 완료 리뷰 `통과` 조건을 충족하면 `[완료]` 전환 또는 archive 전에 관련 agent-ui view/component/frame 문서의 `status`를 `구현됨`으로 반영할 수 있다.
+- 상태 반영은 완료 evidence가 직접 가리키는 agent-ui 활성 문서에만 적용한다. Milestone 전체 완료만을 근거로 `agent-ui/definition/**` 전체를 일괄 `구현됨`으로 바꾸지 않는다.
+- 각 대상 문서는 실제 존재하는 code evidence path와 최종 검증 근거가 있어야 `구현됨`으로 바꾼다. 근거가 없으면 `계획` 또는 기존 상태를 유지하고 완료 리뷰를 `보완 필요`로 둔다.
+- agent-ui 상태 반영은 `update-agent-ui`의 문서 갱신 규칙을 따르고, 반영 후 `validate-agent-ui`로 정합성을 확인한다. 이 단계는 이미 완료된 코드 반영의 문서 상태 갱신이므로 `sync-agent-ui`를 새로 실행하지 않는다.
+- status/code evidence 반영과 `validate-agent-ui`가 모두 통과하면 Milestone `완료 리뷰`의 `agent-ui 상태 반영`을 `완료`로 바꾼다.
+- 근거 부족, 미해결 USER_REVIEW, 또는 `validate-agent-ui` 실패로 반영하지 못하면 Milestone `완료 리뷰`의 `agent-ui 상태 반영`을 `차단: <사유>`로 바꾸고 `상태: 보완 필요`를 남긴다.
+- `validate-agent-ui`가 FAIL이거나 현재 범위에 미해결 `agent-ui/USER_REVIEW.md`가 있으면 Milestone을 `[완료]`로 전환하지 않고 완료 리뷰를 `보완 필요`로 둔다.
+- `agent-ui 상태 반영: 대기`가 아닌 Milestone에서는 완료 리뷰 중 agent-ui status를 변경하지 않는다.
+
 ## Milestone task group 연동

 - 런타임 완료 이벤트의 `origin-task`에서 `agent-task/` 다음 첫 path segment가 `m-<milestone-slug>`이면 Milestone 기반 plan/review 완료에서 온 요청으로 본다. `origin-task`는 archive 이동 전 active task 경로 또는 런타임이 그 형태로 정규화한 경로를 사용한다.
@ -303,6 +318,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
   - 런타임 완료 이벤트가 `complete-log`를 전달하면 파일을 읽고 `Roadmap Completion` 섹션 유무와 Completed task ids를 확인한다. 섹션이 없으면 Milestone 기능 Task 체크는 no-op이다. SDD 대상 Milestone이면 SDD `Evidence Map` 충족 여부도 확인한다.
   - 구조 전환, 템플릿 보정, current 동기화는 `sync`로 본다.
   - 완료/폐기 근거가 충족된 이동은 `archive`로 본다.
+   - 완료 리뷰 요청에서 대상 Milestone의 `완료 리뷰`가 `agent-ui 상태 반영: 대기`인지 확인한다. 항목이 없거나 `대기`가 아니면 agent-ui 상태 반영 단계를 적용하지 않는다.
   - 새 기능 배치, Epic/Task 추가는 `milestone` 또는 `phase`로 본다.
   - "로드맵에 추가"처럼 target이 없는 신규 작업 요청은 `placement=auto`, `placement-unit=auto`, `new-feature=<요청 내용>`으로 본다.
   - 외부 의존 잠금 요청이면 `workspace-lock` 갱신으로 본다.
@ -351,6 +367,8 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
   - 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`이어도 `구현 잠금`이 `해제`가 아니거나 미완료 `결정 필요` 항목이 있으면 Milestone 상태를 `[검토중]`으로 바꾸지 않는다. `완료 리뷰` 또는 `작업 컨텍스트`에 잠금 차단 항목을 남긴다.
   - 모든 기능 Task와 Task 안에 명시된 검증이 evidence와 함께 `[x]`이고 `구현 잠금`도 해제되어 있으면 Milestone 상태를 `[검토중]`으로 바꾸고 `완료 리뷰`에 완료 근거와 남은 차단 항목을 남긴다.
   - `[검토중]` 전환만으로 archive 이동, 로컬 `current.md` 제거, archive 링크 변경을 수행하지 않는다.
+   - `agent-ui 상태 반영: 대기`인 Milestone의 완료 리뷰가 `통과` 후보이면 `[완료]` 전환 전에 관련 agent-ui 문서의 `status`를 `구현됨`으로 갱신할 수 있는지 확인한다. 대상 문서, code evidence, 최종 검증 근거, `validate-agent-ui` 결과가 모두 충족될 때만 반영하고 `agent-ui 상태 반영: 완료`로 바꾼다.
+   - agent-ui 상태 반영이 필요한데 근거가 부족하거나 `validate-agent-ui`가 통과하지 않으면 Milestone 상태를 `[진행중]` 또는 `[검토중]`으로 유지하고 `완료 리뷰: 보완 필요`와 `agent-ui 상태 반영: 차단: <사유>`를 남긴다.
   - 기능 Task, 검증, 구현 잠금, 완료 근거가 모두 충족되면 `[검토중]`을 `[완료]`로 전환하고 archive 모드를 수행할 수 있다.
   - `locks.yaml`이 있으면 갱신 대상 Milestone identity로 `--find-milestone "<identity>" both "<locks-file>"`를 실행해 이 Milestone이 `locked`인지, `rely-on.target`인지, 관련 lock이 없는지 확인한다.
   - archive 모드이면 파일 이동 전 active Milestone identity를 보존하고, 그 identity로 `--find-milestone "<identity>" both "<locks-file>"`를 먼저 실행한다.
@ -378,6 +396,8 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
   - `[검토중]` Milestone이 archive 경로로 이동되지 않았는지 확인한다.
   - 모든 기능 Task와 Task 안에 명시된 검증이 `[x]`인 Milestone은 `구현 잠금`이 해제되어야 `[검토중]`이 될 수 있다. 잠금이 남아 있으면 `완료 리뷰` 또는 `작업 컨텍스트`에 잠금 차단 항목이 있는지 확인한다.
   - `[검토중]` Milestone에는 `완료 리뷰` 섹션과 완료 근거/남은 차단 항목이 있는지 확인한다.
+   - `agent-ui 상태 반영: 대기`인 Milestone을 `[완료]`로 전환하는 경우, 완료 evidence가 가리키는 agent-ui 문서의 status/code evidence 반영 여부와 `validate-agent-ui` 결과가 완료 리뷰에 남았는지 확인한다.
+   - `agent-ui 상태 반영: 대기`가 아닌 Milestone 완료 리뷰에서 agent-ui 문서 status를 변경하지 않았는지 확인한다.
   - 각 Milestone의 `구현 잠금`에 SDD 필요 여부와 사유가 있는지 확인한다.
   - `SDD: 필요` Milestone은 SDD 경로, SDD 파일 존재, 잠금 해제 조건, SDD 사용자 리뷰 상태가 일관되는지 확인한다. 사용자가 명시적으로 SDD 생성을 뒤로 미루지 않았는데 SDD 파일이 없으면 검증 실패로 본다.
   - Epic heading과 Task id 형식이 맞는지 확인한다.
@ -401,6 +421,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
   - 자동 배치한 경우 비교한 후보와 선택 근거
   - 로컬 current.md 활성 창 변경 사항
   - 완료 리뷰 상태와 남은 차단 항목
+   - `agent-ui 상태 반영: 대기`인 Milestone이면 agent-ui status 반영 여부와 validate-agent-ui 결과
   - SDD gate 상태와 사용자 리뷰 필요 여부
   - 런타임 완료 이벤트의 `origin-task`가 `m-<milestone-slug>`이면 원래 active task 경로와 매칭된 target Milestone, `Roadmap Completion` Task ids 또는 no-op 사유
   - archive 모드이면 이동 경로와 남긴 링크
@ -437,6 +458,7 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
 - SDD gate: <불필요 | 필요-작성 전 | 필요-잠금 | 필요-사용자 리뷰 | 필요-승인됨 | 변경 없음>
 - 승격 조건: <해당 없음 | 추가/수정/미충족 유지/충족 요약>
 - 완료 리뷰: <변경 없음 | 검토중 | 통과 | 보완 필요 | 보류 | 폐기>
+- agent-ui 상태 반영: <해당 없음 | 대기 | 완료 | 차단: 사유 | 변경 없음>
 - runtime m-task 라우팅: <해당 없음 | origin-task -> target Milestone | target 불명확>
 - Workspace 잠금: <변경 없음 | 관련 lock 없음 | entry 생성/갱신 | rely-on enable | rely-on disable | 미충족 | 런타임 해제 대기>
 - 활성 항목: <변경 없음 | Phase/Milestone 추가/제거 요약>
@ -464,6 +486,8 @@ target 없는 신규 추가 요청은 append가 아니라 upsert로 처리한다
 - Phase와 Milestone 이름 또는 파일명에 순번을 강제하지 않는다.
 - 에이전트가 확정할 수 없는 결정 항목이 남아 있는데 Milestone의 `구현 잠금`을 `해제`로 바꾸지 않는다.
 - `구현 잠금`이 남아 있는 Milestone을 `[검토중]`, `[완료]`, 또는 완료 archive 대상으로 전환하지 않는다. 명시적인 폐기 근거가 있는 `[폐기]` archive는 허용한다.
+- `agent-ui 상태 반영: 대기`가 아닌 Milestone 완료 리뷰에서 agent-ui 문서 status를 변경하지 않는다.
+- `agent-ui 상태 반영: 대기`인 Milestone이라도 최종 검증과 실제 code evidence 없이 agent-ui status를 `구현됨`으로 바꾸지 않는다.
 - 사용자가 지정한 Phase/Milestone/Epic/Task anchor를 무시하지 않는다.
 - 사용자가 명시하지 않은 기존 epic-id나 item-id를 바꾸지 않는다.
 - `rely-on.status=enable`만으로 다른 프로젝트 Milestone의 `구현 잠금`을 직접 해제하지 않는다.
 @ -1 +1 @@
 .1.158
 .1.159