update agent-ui templates and skills

agent-ops/rules/common/rules-agent-ui.md

@@ -55,6 +55,24 @@ agent-ui/
 - 구현 코드에서 확인된 항목은 `implemented`, 문서 계획에서 온 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 표시한다.
 - `planned`, `assumed`, `unknown` 항목을 구현 완료처럼 설명하지 않는다.
 
+## Frontmatter Schema
+
+- 활성 Markdown 문서는 YAML frontmatter를 둔다.
+- `ui_doc_type`은 `readme`, `definition-index`, `views-index`, `view`, `components-index`, `component`, `frame-index`, `frame-view`, `user-review`, `archive-log` 중 하나다.
+- definition-index 문서는 `surface_type`, `source_evidence`를 둘 수 있다.
+- view 문서는 `view_id`, `status`, `frame`, `source_evidence`를 둔다.
+- component 문서는 `component_id`, `status`, `source_evidence`를 둔다.
+- frame-view 문서는 `view_id`, `definition`, `visual_source`, `regions`를 둔다.
+- `status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나다.
+- `source_evidence`는 list이며 각 항목은 `type`, `path`, `notes`를 둔다.
+- `source_evidence.type`은 `code`, `docs`, `user` 중 하나다.
+- 실제 파일 근거가 없으면 `path: null`을 사용한다. placeholder 문자열을 현재 근거처럼 남기지 않는다.
+- `visual_source`가 아직 없으면 `null`을 사용한다. 없는 `wire.excalidraw`를 기본 근거처럼 쓰지 않는다.
+- `implemented`는 존재하는 `code` evidence path가 있을 때만 사용한다.
+- `planned`는 문서 근거만 있을 때, `assumed`는 사용자 명시 입력만 있을 때, `unknown`은 근거나 판단이 부족할 때 사용한다.
+- frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`는 같은 기준을 말해야 한다.
+- frontmatter는 기계적 검증을 위한 최소 schema이고, 본문 Markdown은 사람과 agent가 읽는 설명을 유지한다.
+
 ## 명명 규칙
 
 - view id, component id, 파일명, 디렉터리명은 kebab-case를 사용한다.
@@ -70,6 +88,7 @@ agent-ui/
 - component id는 `definition/components/` 아래 경로에서 `index.md`를 제외한 path id로 본다. 예: `data-table`, `data-table/job-list`.
 - view 정의서의 region id와 frame 정의서의 region id는 동일해야 한다.
 - view에서 참조한 component id는 대응되는 component 정의 문서가 있어야 한다.
+- frame-view frontmatter의 `regions`와 view 본문의 region id는 같은 집합이어야 한다. 단, 차이가 제품 판단을 요구하면 USER_REVIEW로 남긴다.
 
 ## Archive 접근
 
@@ -90,6 +109,10 @@ agent-ui/
 - VS Code Excalidraw extension은 초기 편집 워크플로우로 사용할 수 있다.
 - excalidraw.com import/export 워크플로우는 기본 표준으로 삼지 않는다.
 - Excalidraw self-host는 R&D 후보이며, 기본 agent-ui scaffold의 필수 조건이 아니다.
+- `.excalidraw`는 JSON으로 다룬다. 검증 시 가능하면 JSON parser로 `elements`의 text label 또는 `customData.region_id`를 확인한다.
+- visual source에 region label이 있으면 `frame-view.regions`와 `definition` region id의 집합과 비교한다.
+- visual source가 있는데 region label이 없으면 frame과 definition의 연결 근거가 부족한 상태로 본다.
+- visual source에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동으로 UI 의도를 확정하지 않고 USER_REVIEW로 남긴다.
 
 ## 스킬
 

agent-ops/skills/common/_templates/agent-ui/archive-log-template.md

@@ -1,3 +1,8 @@
+---
+ui_doc_type: archive-log
+target: <target>
+---
+
 # <target> log
 
 ## <YYYY-MM-DD>

agent-ops/skills/common/_templates/agent-ui/component-index-template.md

@@ -1,3 +1,19 @@
+---
+ui_doc_type: component
+component_id: <component-id>
+status: <implemented|planned|assumed|unknown>
+source_evidence:
+  - type: code
+    path: null
+    notes: <구현 근거. 없으면 없음>
+  - type: docs
+    path: null
+    notes: <컨셉/계획 근거. 없으면 없음>
+  - type: user
+    path: null
+    notes: <사용자 명시 입력. 없으면 없음>
+---
+
 # <Component Name>
 
 Component ID: `<component-id>`
@@ -8,9 +24,9 @@ Status: `<implemented|planned|assumed|unknown>`
 
 | Type | Path | Notes |
 |------|------|-------|
-| code | `<path>` | <구현 근거. 없으면 `없음`> |
-| docs | `<path>` | <컨셉/계획 근거. 없으면 `없음`> |
-| user | `<request>` | <사용자 명시 입력. 없으면 `없음`> |
+| code | 없음 | <구현 근거. 없으면 `없음`> |
+| docs | 없음 | <컨셉/계획 근거. 없으면 `없음`> |
+| user | 없음 | <사용자 명시 입력. 없으면 `없음`> |
 
 ## Purpose
 

agent-ops/skills/common/_templates/agent-ui/components-index-template.md

@@ -1,10 +1,15 @@
+---
+ui_doc_type: components-index
+components: []
+---
+
 # Component Definitions
 
 ## Component List
 
 | Component ID | Status | Evidence | Description |
 |--------------|--------|----------|-------------|
-| `<component-id>` | `<implemented|planned|assumed|unknown>` | `<path>` | <반복 UI 구성요소 설명> |
+| 없음 | - | - | - |
 
 ## Rules
 

agent-ops/skills/common/_templates/agent-ui/definition-index-template.md

@@ -1,3 +1,18 @@
+---
+ui_doc_type: definition-index
+surface_type: ops-dev
+source_evidence:
+  - type: code
+    path: null
+    notes: <UI 구현 근거 요약>
+  - type: docs
+    path: null
+    notes: <컨셉/계획 근거 요약>
+  - type: user
+    path: null
+    notes: <사용자 명시 입력 요약>
+---
+
 # UI Definition
 
 ## Purpose
@@ -11,11 +26,11 @@
 
 ## Source Evidence
 
-| Type | Path | Usage |
+| Type | Path | Notes |
 |------|------|-------|
-| code | `<path>` | <UI 구현 근거 요약> |
-| docs | `<path>` | <컨셉/계획 근거 요약> |
-| user | `<request>` | <사용자 명시 입력 요약> |
+| code | 없음 | <UI 구현 근거 요약> |
+| docs | 없음 | <컨셉/계획 근거 요약> |
+| user | 없음 | <사용자 명시 입력 요약> |
 
 ## Structure
 

agent-ops/skills/common/_templates/agent-ui/frame-index-template.md

@@ -1,3 +1,8 @@
+---
+ui_doc_type: frame-index
+frames: []
+---
+
 # UI Frames
 
 ## Purpose

agent-ops/skills/common/_templates/agent-ui/frame-view-index-template.md

@@ -1,10 +1,19 @@
+---
+ui_doc_type: frame-view
+view_id: <view-id>
+definition: ../../../definition/views/<view-id>/index.md
+visual_source: null
+regions:
+  - <view-id>.<region>
+---
+
 # <View Name> Frame
 
 Definition:
 - `../../../definition/views/<view-id>/index.md`
 
 Visual Source:
-- `wire.excalidraw`
+- 없음
 
 ## Frame Intent
 
@@ -22,6 +31,6 @@ Visual Source:
 
 ## Sync Rules
 
-- visual source의 박스 라벨은 가능한 한 region id를 포함한다.
+- visual source의 주요 박스 text label 또는 `customData.region_id`는 가능한 한 region id를 포함한다.
 - definition에 없는 region을 frame에 추가하지 않는다. 필요한 경우 `agent-ui/USER_REVIEW.md`에 남긴다.
 - frame에서 제거한 region은 definition에서도 제거 대상인지 확인한다.

agent-ops/skills/common/_templates/agent-ui/readme-template.md

@@ -1,3 +1,8 @@
+---
+ui_doc_type: readme
+surface_type: ops-dev
+---
+
 # agent-ui
 
 이 디렉터리는 AI agent와 사람이 UI 의도, 화면 구조, 와이어프레임, 반복 구성요소를 동기화하기 위한 작업 문맥 저장소다.

agent-ops/skills/common/_templates/agent-ui/user-review-template.md

@@ -1,3 +1,8 @@
+---
+ui_doc_type: user-review
+status: open
+---
+
 # agent-ui 사용자 리뷰
 
 이 문서는 agent가 확정할 수 없는 UI 결정을 사용자에게 넘기기 위한 활성 리뷰 문서다.

agent-ops/skills/common/_templates/agent-ui/view-index-template.md

@@ -1,3 +1,22 @@
+---
+ui_doc_type: view
+view_id: <view-id>
+status: <implemented|planned|assumed|unknown>
+frame: ../../../frame/views/<view-id>/index.md
+source_evidence:
+  - type: code
+    path: null
+    notes: <구현 근거. 없으면 없음>
+  - type: docs
+    path: null
+    notes: <컨셉/계획 근거. 없으면 없음>
+  - type: user
+    path: null
+    notes: <사용자 명시 입력. 없으면 없음>
+regions:
+  - <view-id>.<region>
+---
+
 # <View Name>
 
 View ID: `<view-id>`
@@ -11,9 +30,9 @@ Status: `<implemented|planned|assumed|unknown>`
 
 | Type | Path | Notes |
 |------|------|-------|
-| code | `<path>` | <구현 근거. 없으면 `없음`> |
-| docs | `<path>` | <컨셉/계획 근거. 없으면 `없음`> |
-| user | `<request>` | <사용자 명시 입력. 없으면 `없음`> |
+| code | 없음 | <구현 근거. 없으면 `없음`> |
+| docs | 없음 | <컨셉/계획 근거. 없으면 `없음`> |
+| user | 없음 | <사용자 명시 입력. 없으면 `없음`> |
 
 ## Purpose
 

agent-ops/skills/common/_templates/agent-ui/views-index-template.md

@@ -1,10 +1,15 @@
+---
+ui_doc_type: views-index
+views: []
+---
+
 # View Definitions
 
 ## View Tree
 
 | View ID | Status | Evidence | Description |
 |---------|--------|----------|-------------|
-| `<view-id>` | `<implemented|planned|assumed|unknown>` | `<path>` | <화면 또는 업무 단위 설명> |
+| 없음 | - | - | - |
 
 ## Navigation
 

agent-ops/skills/common/create-agent-ui/SKILL.md

@@ -65,6 +65,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분
      - `agent-ui/definition/views/index.md`
      - `agent-ui/definition/components/index.md`
      - `agent-ui/frame/index.md`
+   - 생성하는 활성 Markdown 문서에는 `rules-agent-ui.md`의 Frontmatter Schema를 적용한다.
    - 다음 archive/user-review 디렉터리가 빈 상태로 필요하면 `.gitkeep`을 둘 수 있다.
      - `agent-ui/definition/archive/views/`
      - `agent-ui/definition/archive/components/`
@@ -83,7 +84,10 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분
      - 문서 근거만 있으면 `status: planned`
      - 명시 입력만 있고 근거가 부족하면 `status: assumed`
      - 판단 불가하면 `status: unknown`과 USER_REVIEW 항목을 남긴다.
+   - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다.
+   - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 같은 기준을 말하게 작성한다.
    - `.excalidraw` 파일은 사용자가 요청했을 때만 빈 visual source로 만들거나 생성 후보로 보고한다.
+   - `.excalidraw`를 만들거나 연결하면 주요 박스 text label 또는 `customData.region_id`에 region id를 넣는다.
    - view id는 kebab-case가 아니면 정규화 후보를 보고하고 사용자 확인이 필요하면 생성하지 않는다.
 
 6. **초기 component 생성**
@@ -92,6 +96,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분
    - `blank`에서는 명시 `components`가 있을 때만 component 후보를 만든다.
    - 각 component 후보마다 `agent-ui/definition/components/<component-id>/index.md`를 만든다.
    - component 문서에는 `Source Evidence`와 `Status`를 반드시 남긴다.
+   - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다.
    - component id가 path id이면 하위 디렉터리 구조로 만든다.
    - view에서 참조하지 않는 component도 사용자가 명시했으면 생성할 수 있다.
 
@@ -104,6 +109,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분
    - 선택된 `source-mode`
    - 읽은 근거 파일과 생성에 사용한 evidence
    - 생성한 파일
+   - 적용한 frontmatter schema
    - 생성한 view/component의 status
    - USER_REVIEW 생성 여부
    - product UI 확장 후보
@@ -113,6 +119,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분
 
 - [ ] `agent-ui/README.md`가 생성되었는가
 - [ ] `definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md`가 생성되었는가
+- [ ] 활성 Markdown 문서가 `ui_doc_type` frontmatter를 포함하는가
 - [ ] view/component는 folder-first + `index.md` 구조를 사용하는가
 - [ ] 생성한 view/component에 `Source Evidence`와 `Status`가 있는가
 - [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가
@@ -130,6 +137,7 @@ ops/dev UI를 1차 대상으로 하며, 구현 근거와 문서 근거를 구분
 - source-mode: <code-first|concept-first|blank>
 - evidence: <주요 근거 파일 목록>
 - 생성 파일: <목록>
+- frontmatter schema: <적용/부분 적용/없음>
 - views: <view-id=status 목록 또는 없음>
 - components: <component-id=status 목록 또는 없음>
 - USER_REVIEW: <생성/없음>

agent-ops/skills/common/update-agent-ui/SKILL.md

@@ -49,17 +49,22 @@ view, component, frame index, Excalidraw visual source 연결, source evidence,
 
 2. **정의 갱신**
    - 현재 기준은 `definition/**` 활성 문서에 반영한다.
+   - 활성 Markdown 문서의 frontmatter를 유지하고, 새 문서는 `rules-agent-ui.md`의 Frontmatter Schema를 적용한다.
    - view 문서에는 status, source evidence, purpose, tasks, information priority, regions, actions, states, open questions, decision history를 유지한다.
    - component 문서에는 status, source evidence, purpose, used by, anatomy, variants, states, rules, decision history를 유지한다.
    - 구현 코드 근거가 확인된 항목은 `implemented`, 문서 근거만 있는 항목은 `planned`, 사용자 명시 입력만 있고 근거가 부족한 항목은 `assumed`, 판단 불가 항목은 `unknown`으로 둔다.
+   - 실제 근거 파일이 없으면 frontmatter `source_evidence[].path`는 `null`로 둔다.
+   - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 충돌하지 않게 함께 갱신한다.
    - `status`가 입력되었더라도 evidence와 맞지 않으면 임의로 확정하지 않고 USER_REVIEW로 남긴다.
    - 새 view/component를 만들 때는 `Source Evidence`와 `Status`를 반드시 채운다.
    - 오래된 결정이 현재 기준을 흐리면 대응되는 `definition/archive/**.log`로 이동하거나 추가한다.
 
 3. **frame 갱신**
    - 대응되는 `frame/views/<view-id>/index.md`가 없으면 템플릿으로 만든다.
-   - visual source가 있으면 `Visual Source`에 기록한다.
+   - visual source가 있으면 frontmatter `visual_source`와 본문 `Visual Source`에 함께 기록한다.
+   - visual source가 없으면 frontmatter `visual_source`는 `null`로 둔다.
    - Excalidraw visual source의 기본 후보 파일명은 `wire.excalidraw`다.
+   - `.excalidraw`를 만들거나 수정하면 주요 박스 text label 또는 `customData.region_id`에 region id를 넣는다.
    - frame의 required region id는 view definition의 region id와 맞춘다.
    - 정의에 없는 region이 frame에 필요하면 바로 확정하지 않고 open question 또는 USER_REVIEW로 분리한다.
 
@@ -71,6 +76,7 @@ view, component, frame index, Excalidraw visual source 연결, source evidence,
 5. **결과 보고**
    - 수정한 활성 정의 문서
    - 수정한 frame 문서와 visual source
+   - frontmatter schema 변경 여부
    - archive log 변경 여부
    - USER_REVIEW 생성/갱신 여부
    - 남은 정합성 확인 항목
@@ -78,6 +84,7 @@ view, component, frame index, Excalidraw visual source 연결, source evidence,
 ## 실행 결과 검증
 
 - [ ] view/component는 folder-first + `index.md` 구조를 유지하는가
+- [ ] 새로 만들거나 수정한 활성 Markdown 문서가 `ui_doc_type` frontmatter를 포함하는가
 - [ ] 새로 만들거나 수정한 view/component에 `Source Evidence`와 `Status`가 있는가
 - [ ] 구현 근거 없는 항목을 `implemented`로 표시하지 않았는가
 - [ ] view region id와 frame region id가 충돌하지 않는가
@@ -97,6 +104,7 @@ view, component, frame index, Excalidraw visual source 연결, source evidence,
 - component: <component-id 또는 없음>
 - frame source: <파일 또는 없음>
 - evidence/status: <요약 또는 없음>
+- frontmatter schema: <변경/유지/없음>
 - archive 변경: <내용 또는 없음>
 - USER_REVIEW: <생성/갱신/없음>
 - 확인 필요: <항목 또는 없음>

agent-ops/skills/common/validate-agent-ui/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: validate-agent-ui
 version: 1.1.0
-description: agent-ui scaffold, definition/frame/component/source evidence/status 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬
+description: agent-ui scaffold, definition/frame/component/source evidence/status와 구현 코드 정합성을 검사하고 자동 보정하며 필요한 USER_REVIEW를 생성하는 스킬
 ---
 
 # validate-agent-ui
 
 ## 목적
 
-`agent-ui/` 구조와 문서 간 정합성을 검사한다.
+`agent-ui/` 구조, 문서 간 정합성, 구현 코드와 agent-ui 정의 간 정합성을 검사한다.
 파일 규약처럼 결정적으로 고칠 수 있는 문제는 자동 보정하고, UI 의도 판단이 필요한 문제는 `agent-ui/USER_REVIEW.md`에 남긴다.
 
 ## 언제 호출할지
@@ -16,12 +16,13 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu
 - agent-ui 구조 검증, UI 정의 정합성 확인, wireframe 정합성 확인을 요청할 때
 - view/component/frame 문서가 서로 어긋났는지 확인할 때
 - view/component의 Source Evidence와 Status가 근거와 맞는지 확인할 때
+- 실제 UI 코드와 agent-ui view/component 정의가 동기화되어 있는지 확인할 때
 - Excalidraw visual source와 frame index 연결을 검사할 때
 - agent-ui 갱신 후 자동 보정과 사용자 리뷰 분리가 필요할 때
 
 ## 입력
 
-- `scope`: `all`, `view:<view-id>`, `component:<component-id>`, `frame:<view-id>` 중 하나. 기본값은 `all` (선택)
+- `scope`: `all`, `internal`, `implementation`, `view:<view-id>`, `component:<component-id>`, `frame:<view-id>` 중 하나. 기본값은 `all` (선택)
 - `repair`: `true` 또는 `false`. 기본값은 `true` (선택)
 
 ## 먼저 확인할 것
@@ -30,6 +31,8 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu
 - [ ] `agent-ui/` 존재 여부를 확인한다. 없으면 `create-agent-ui` 대상이라고 보고하고 중단한다.
 - [ ] `agent-ui/definition/index.md`, `definition/views/index.md`, `definition/components/index.md`, `frame/index.md` 존재 여부를 확인한다.
 - [ ] scope에 해당하는 활성 definition/frame 문서만 읽는다.
+- [ ] `scope=view:<view-id>` 또는 `scope=component:<component-id>`이면 해당 문서의 Source Evidence code path를 확인한다.
+- [ ] `scope=all` 또는 `scope=implementation`이면 Source Evidence의 code path와 UI 구현 후보 파일을 확인한다.
 - [ ] archive는 경로와 tree 대응만 확인하고, 사용자가 과거 내용 확인을 요청하지 않았으면 본문을 읽지 않는다.
 - [ ] 필요한 템플릿만 `agent-ops/skills/common/_templates/agent-ui/`에서 읽는다.
 
@@ -39,6 +42,7 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu
    - `definition/views/**/index.md`에서 view 목록을 만든다.
    - `definition/components/**/index.md`에서 component 목록을 만든다.
    - `frame/views/**/index.md`에서 frame 목록을 만든다.
+   - 활성 Markdown 문서의 frontmatter에서 `ui_doc_type`, id, status, source_evidence, regions를 수집한다.
    - 같은 레벨의 `<name>.md`와 `<name>/` 혼재 여부를 확인한다.
 
 2. **구조 검증과 자동 보정**
@@ -49,7 +53,14 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu
    - `<name>.md`와 `<name>/`가 모두 있고 둘 다 의미 있는 내용이면 자동 병합하지 않고 USER_REVIEW로 남긴다.
 
 3. **definition 정합성 검사**
+   - 활성 Markdown 문서에 `ui_doc_type` frontmatter가 있는지 확인한다.
+   - `ui_doc_type`이 경로와 맞는지 확인한다. 예: `definition/views/<view-id>/index.md`는 `view`다.
+   - view/component/frame id가 경로 id와 일치하는지 확인한다.
    - view/component 문서에 `Source Evidence`와 `Status`가 있는지 확인한다.
+   - frontmatter `source_evidence`는 list이고 각 항목은 `type`, `path`, `notes`를 가져야 한다.
+   - `source_evidence.type`은 `code`, `docs`, `user` 중 하나여야 한다.
+   - 근거 파일이 없으면 `path: null`이어야 하며, placeholder 문자열을 근거로 보지 않는다.
+   - frontmatter의 `status`, `source_evidence`, `regions`와 본문 `Status`, `Source Evidence`, `Regions`가 충돌하는지 확인한다.
    - `Status`는 `implemented`, `planned`, `assumed`, `unknown` 중 하나여야 한다.
    - `implemented` 항목은 실제 존재하는 코드 근거가 있어야 한다.
    - `implemented`의 code evidence 경로가 명시되어 있고 실제 존재하지 않으면 `repair=true`일 때 `unknown`으로 낮추고 USER_REVIEW를 남길 수 있다.
@@ -62,19 +73,40 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu
 
 4. **frame 정합성 검사**
    - view가 있는데 대응 frame index가 없으면 `repair=true`일 때 만든다.
-   - frame index가 가리키는 definition 경로와 visual source가 실제 존재하는지 확인한다.
+   - frame index가 가리키는 definition 경로가 실제 존재하는지 확인한다.
+   - `visual_source`가 `null`이면 visual source 없음으로 본다.
+   - `visual_source`가 값이면 해당 파일이 실제 존재하는지 확인한다.
+   - `visual_source`가 `.excalidraw`이면 JSON으로 읽고 `elements`의 text label 또는 `customData.region_id`에서 region id 후보를 수집한다.
+   - Excalidraw region id 후보가 있으면 frame required region, view definition region과 비교한다.
+   - Excalidraw region id 후보가 없고 frame required region이 있으면 USER_REVIEW로 남긴다.
+   - Excalidraw에 정의되지 않은 region label이 있거나 필수 region label이 없으면 자동 수정하지 않고 USER_REVIEW로 남긴다.
+   - Excalidraw가 JSON으로 파싱되지 않으면 visual source 손상 또는 형식 불일치로 보고한다.
    - frame required region과 view definition region을 비교한다.
    - definition에 있는 region이 frame index에만 빠진 경우 `repair=true`이면 frame index의 required region을 보완할 수 있다.
    - frame에만 있는 region은 definition에 자동 추가하지 않고 USER_REVIEW로 남긴다.
    - region 추가/삭제 의도 판단이 필요하면 USER_REVIEW로 남긴다.
 
-5. **USER_REVIEW 생성 또는 갱신**
+5. **구현 정합성 검사**
+   - `scope=view:<view-id>` 또는 `scope=component:<component-id>`이면 해당 문서의 `source_evidence` 중 `type: code` 경로만 확인하고 전체 코드 후보 스캔은 하지 않는다.
+   - `scope=all` 또는 `scope=implementation`이면 전체 view/component의 `source_evidence` 중 `type: code` 경로가 실제 존재하는지 확인한다.
+   - 실제 UI 구현 후보를 찾는다.
+     - 이 후보 스캔은 `scope=all` 또는 `scope=implementation`일 때만 수행한다.
+     - 예: `apps/**/lib/**`, `packages/**/lib/**`, `src/**`, `app/**`, `pages/**`, `screens/**`, `views/**`, `components/**`, `widgets/**`, route/navigation/shell 파일
+     - 프로젝트 규칙에 dedicated UI domain rule이 있으면 먼저 따른다.
+     - 코드가 많으면 route, shell, page/view, widget/component 이름 중심으로 후보를 좁힌다.
+   - 코드 후보가 명확한 route/page/view/shell이면 대응 view가 있는지 확인한다.
+   - 코드 후보가 명확한 반복 widget/component/table/filter/log/status/action이면 대응 component가 있는지 확인한다.
+   - 명확한 누락이고 `repair=true`이면 skeleton view/component를 만들 수 있다. 이때 status는 `implemented`, source evidence는 해당 code path로 둔다.
+   - 후보가 임시/dev/debug 용도인지, view인지 component인지, region인지 판단이 필요하면 USER_REVIEW로 남긴다.
+   - 코드에서 사라진 evidence는 자동 삭제하지 않고, 명시된 code evidence 경로가 깨진 경우에만 `implemented`를 `unknown`으로 낮출 수 있다.
+
+6. **USER_REVIEW 생성 또는 갱신**
    - active review 파일은 `agent-ui/USER_REVIEW.md`를 사용한다.
    - 새 항목 id는 기존 최대 `UIR-NNN` 다음 번호를 사용한다.
    - 같은 경로와 같은 질문의 중복 항목은 만들지 않는다.
    - 항목에는 Context, Options, Needed For를 포함한다.
 
-6. **결과 판정**
+7. **결과 판정**
    - `PASS`: 자동 수정도 USER_REVIEW도 필요 없는 상태
    - `WARN`: 자동 수정이 있었거나 USER_REVIEW가 생성/갱신된 상태
    - `FAIL`: 구조가 너무 모호해서 자동 보정과 리뷰 작성 모두 불완전한 상태
@@ -86,8 +118,9 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu
 - 명확한 단일 후보 상대 링크 보정
 - definition에 이미 있는 region의 frame index 누락 보완
 - 빈 archive/user-review 디렉터리 생성
-- 템플릿 필수 섹션 누락 보완. `Source Evidence`와 `Status` 누락 포함
+- 템플릿 필수 섹션과 frontmatter 누락 보완. `ui_doc_type`, `Source Evidence`, `Status` 누락 포함
 - 의도가 명확한 component skeleton 생성. 단, status/evidence를 함께 기록한다.
+- 명확한 구현 코드 후보에 대응되는 skeleton view/component 생성. 단, status/evidence를 함께 기록한다.
 - 명시된 code evidence 경로가 실제 존재하지 않는 `implemented`를 `unknown`으로 낮추고 USER_REVIEW를 남기는 보정
 
 ## USER_REVIEW 대상
@@ -95,15 +128,19 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu
 - 정의에는 없는 region이 frame에 있고 추가/삭제 의도 판단이 필요한 경우
 - frame에는 없는 region이 정의에 있고 layout 반영 여부 판단이 필요한 경우
 - component 참조가 없으며 새 component 생성 또는 기존 component 재사용 판단이 필요한 경우
+- 코드 후보가 view, component, region, 임시/dev/debug UI 중 무엇인지 판단이 필요한 경우
+- 코드와 agent-ui 정의가 충돌하지만 어느 쪽을 기준으로 삼을지 제품 판단이 필요한 경우
 - `<name>.md`와 `<name>/`가 모두 있고 둘 다 의미 있는 내용이 있는 경우
 - drawer/page/split, 테이블/리스트, modal/page 같은 UX 방향 결정이 필요한 경우
 
 ## 실행 결과 검증
 
 - [ ] 필수 루트 문서가 존재하거나 누락 사유가 보고되었는가
+- [ ] 활성 Markdown 문서가 유효한 `ui_doc_type` frontmatter를 갖는가
 - [ ] folder-first + `index.md` 구조가 유지되는가
 - [ ] view/component에 `Source Evidence`와 유효한 `Status`가 있는가
 - [ ] 명시된 code evidence 경로가 깨진 `implemented`가 남아 있지 않은가
+- [ ] `scope=implementation` 또는 `all`이면 명확한 UI 코드 후보가 agent-ui에 반영되었거나 USER_REVIEW에 남았는가
 - [ ] view/component/frame 참조가 끊기지 않는가
 - [ ] 자동 수정한 파일 목록이 보고되는가
 - [ ] 사용자 판단이 필요한 항목이 `agent-ui/USER_REVIEW.md`에 남는가
@@ -120,6 +157,7 @@ description: agent-ui scaffold, definition/frame/component/source evidence/statu
 - User Review: <agent-ui/USER_REVIEW.md 생성/갱신/없음>
 - Remaining Issues: <목록 또는 없음>
 - Checked Files: <활성 파일 목록>
+- Implementation Sync: <확인/스킵/USER_REVIEW>
 ```
 
 ## 금지 사항