From 3174b1ffefc47e7c4eb05a7b1d73a344168c7337 Mon Sep 17 00:00:00 2001
From: JK <jk@chequer.io>
Date: Sat, 25 Apr 2026 23:22:21 +0900
Subject: [PATCH] =?UTF-8?q?confluence-mdx:=20reverse-sync=20=ED=98=84?=
 =?UTF-8?q?=EC=9E=AC=20=EA=B5=AC=ED=98=84=20=EC=83=81=ED=83=9C=EB=A5=BC=20?=
 =?UTF-8?q?=EB=AC=B8=EC=84=9C=EC=97=90=20=EB=B0=98=EC=98=81=ED=95=A9?=
 =?UTF-8?q?=EB=8B=88=EB=8B=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- architecture 문서의 reverse-sync/sidecar 설명을 현재 코드 기준으로 갱신합니다.
- stale한 리팩토링 분석 문서를 현재 구현 상태 분석 문서로 전면 교체합니다.
- mapping.yaml, roundtrip sidecar v3, patch_builder 중심 구조와 현재 한계를 문서화합니다.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../docs/analysis-reverse-sync-refactoring.md | 436 +++++++-----------
 confluence-mdx/docs/architecture.md           | 317 +++++++------
 2 files changed, 333 insertions(+), 420 deletions(-)

diff --git a/confluence-mdx/docs/analysis-reverse-sync-refactoring.md b/confluence-mdx/docs/analysis-reverse-sync-refactoring.md
index 24e24574d..b9abc0b70 100644
--- a/confluence-mdx/docs/analysis-reverse-sync-refactoring.md
+++ b/confluence-mdx/docs/analysis-reverse-sync-refactoring.md
@@ -1,352 +1,246 @@
-# Reverse Sync 리팩토링 분석
+# Reverse Sync 현재 구현 상태 분석
 
-> 작성일: 2026-02-26
-> 대상: `confluence-mdx/bin/reverse_sync/` + `reverse_sync_cli.py`
+이 문서는 2026-04-13 기준 reverse-sync의 실제 구현 상태를 코드베이스, 테스트케이스, 최근 커밋 로그를 바탕으로 다시 정리한 문서입니다.
 
-## 1. 분석 목적
+기존 버전은 2026-02~03 시점의 리팩토링 제안과 phase 계획을 중심으로 작성되어 있었고, `text_transfer.py`, `list_patcher.py`, `table_patcher.py` 같은 과거 설계를 전제로 설명하는 부분이 남아 있었습니다. 현재 구현은 그 이후 다수의 refactor/fix를 거치며 구조가 크게 바뀌었으므로, 이 문서는 "무엇을 해야 하는가"보다 "지금 무엇이 구현되어 있고 어디가 여전히 취약한가"를 설명합니다.
 
-최근 reverse-sync 관련 커밋 12건 중 **10건이 버그 수정**이다. 이 빈도는 단순한 구현 실수가 아니라 **설계 수준의 구조적 문제**에서 비롯되었을 가능성이 높다. 이 문서는 반복 버그의 근본 원인을 디자인 결함 관점에서 분석하고, 리팩토링 대상을 도출한다.
+## 1. 한 문장 요약
 
----
+현재 reverse-sync는 "MDX diff를 XHTML에 보수적으로 반영하고, sidecar 기반 identity preservation과 fragment reconstruction을 활용해 원본 fragment를 최대한 유지하며, 마지막에 forward roundtrip으로 검증하는 시스템"입니다.
 
-## 2. 최근 버그 패턴 분류
+즉, 단순 역변환기나 text patcher가 아닙니다.
 
-최근 커밋에서 수정된 버그를 원인별로 분류한다.
+## 2. 최근 변경 흐름 요약
 
-### 2.1 텍스트 위치 매핑 오류 (4건)
+2026-03-17 이후 reverse-sync 관련 커밋은 대체로 다음 흐름을 보입니다.
 
-| 커밋 | 증상 | 근본 원인 |
-|------|------|-----------|
-| `2e9de1a` | `find_insert_pos(char_map, 0)`이 `char_map[0]` 존재 시에도 0 반환 | `text_transfer.py`의 문자 단위 정렬에서 경계 조건 누락 |
-| `fb7efeec` | 인접 text node 경계에서 insert opcode 양쪽 적용 | `xhtml_patcher.py`의 `_map_text_range`에서 half-open range 미적용 |
-| `60c5390` | `<strong>` 뒤 조사 앞 공백 미제거 | `_apply_text_changes`에서 인라인 태그 경계 gap 처리 누락 |
-| `1e4dd43` | 재실행 시 "네이티브로 네이티브로" 중복 | `transfer_text_changes`가 이미 적용된 텍스트를 재매핑 |
+1. Phase 5 초기 구현
+   - sidecar 타입 기반 매핑
+   - heading lookahead 제거
+   - reconstruction 경로 도입
 
-### 2.2 인라인 포맷 변경 감지 실패 (3건)
+2. 구조 재편
+   - `text_transfer.py` 제거
+   - legacy `list_patcher.py`, `table_patcher.py` 제거
+   - `build_patches()` 내부로 매핑/라우팅 책임 집중
 
-| 커밋 | 증상 | 근본 원인 |
-|------|------|-----------|
-| `6438a16` | 연속 인라인 마커 사이 텍스트 변경(쉼표 등) 미감지 | `has_inline_format_change`가 마커 간 텍스트를 검사하지 않음 |
-| `ea28d65` | flat list에서 backtick 변경 누락 | `_resolve_child_mapping` 실패 시 inline 변경 추적 경로 없음 |
-| `7ebaf87` | inline format 변경이 text-only 패치로 처리됨 | inline 변경 감지 로직 자체가 부재 (이 커밋에서 신규 구현) |
+3. 회귀 수정 집중
+   - preserved anchor list 처리
+   - callout 내부 list marker 공백
+   - code span 뒤 공백
+   - heading 내 badge roundtrip
+   - inline boundary whitespace
+   - `--no-normalize` 옵션 추가
+   - visible segment 모델 도입
 
-### 2.3 리스트 처리 실패 (2건)
+이 흐름은 현재 시스템이 아직도 활발히 안정화 중이며, 특히 리스트·인라인 경계·정규화·preserved anchor가 핵심 리스크 영역임을 보여줍니다.
 
-| 커밋 | 증상 | 근본 원인 |
-|------|------|-----------|
-| `f5f307f` | 리스트 항목 수 변경 시 빈 패치 반환 | `build_list_item_patches`에 항목 수 불일치 분기 없음 |
-| `acf4e3c` | 중첩 리스트 텍스트 붕괴 | `SequenceMatcher`의 `autojunk` 기본값이 CJK에 부적합 |
+## 3. 현재 아키텍처의 중심축
 
-### 2.4 정규화/검증 불일치 (2건)
+### 3.1 공개 진입점은 `reverse_sync_cli.py`
 
-| 커밋 | 증상 | 근본 원인 |
-|------|------|-----------|
-| `29cdc9f` | 날짜 locale 불일치로 verify 실패 | forward converter의 locale이 reverse-sync 파이프라인과 불일치 |
-| `18679d0` | callout 매핑 불완전으로 verify 실패 | `roundtrip_verifier`의 정규화 함수 부족 |
+CLI 계층은 다음 책임을 맡습니다.
 
----
+- 단일 파일 verify
+- branch 기준 batch verify
+- 선택적 push
+- 결과 YAML 기록
+- failures-only 출력 제어
+- `--lenient`, `--no-normalize` 같은 검증 옵션 전달
+- push 전 안전장치 및 충돌 처리
 
-## 3. 디자인 결함 분석
+하지만 이 파일이 reverse-sync의 "정책 엔진"은 아닙니다.
 
-### 3.1 근본 원인: "텍스트 패칭" 전략의 본질적 취약성
+### 3.2 실제 정책 엔진은 `patch_builder.py`
 
-현재 reverse-sync의 핵심 전략은 다음과 같다:
+현재 reverse-sync의 핵심 지능은 `patch_builder.py`에 집중되어 있습니다.
 
-```
-MDX diff → 텍스트 변경 추출 → XHTML 내 텍스트 위치 매핑 → 문자 단위 치환
-```
+이 모듈이 결정하는 것:
 
-이 전략은 **XHTML의 DOM 구조를 보존하면서 텍스트만 교체**하는 것이 목표이지만, 근본적인 한계가 있다:
+- 어떤 변경을 direct/containing/list/table/paired/skip으로 볼지
+- mapping.yaml만으로 처리할지 roundtrip sidecar fallback이 필요한지
+- delete/add 쌍을 fragment replacement로 승격할지
+- preserved anchor를 rewrite_on_stored_template로 다룰지
+- container를 outer wrapper template 기반으로 재구성할지
+- table 변경을 허용할지 skip할지
+- list 변경을 visible segment 기반으로 흡수할지
 
-**문제 1: 두 개의 독립된 좌표계 사이의 매핑**
+현재 설계의 장점은 정책이 한곳에 모여 있다는 점이고, 단점은 정책/예외/skip 분기가 과도하게 집중되어 있다는 점입니다.
 
-MDX의 텍스트 위치와 XHTML의 텍스트 위치는 서로 다른 좌표계이다. 이 둘을 문자 단위로 정렬(`align_chars`)하는 것은 본질적으로 불안정하다.
+### 3.3 sidecar는 lookup 보조가 아니라 identity 계층
 
-- MDX에서 `**bold**`는 8글자, XHTML에서 `<strong>bold</strong>`는 23글자
-- Markdown의 인라인 마커, HTML 엔티티, Confluence 전용 태그 등이 좌표를 왜곡
-- `text_transfer.py`의 `align_chars()`는 비공백 문자만 정렬하므로, 공백 위치의 미묘한 차이에서 오류 발생
+현재 구현은 두 종류의 sidecar를 사용합니다.
 
-**이것이 2.1의 4건의 버그가 모두 "위치 매핑"에서 발생한 이유이다.**
+1. `mapping.yaml`
+   - top-level block alignment
+   - child alignment
+   - `lost_info`
+   - 기본 lookup 역인덱스
 
-**문제 2: "텍스트 변경"과 "구조 변경"의 구분 불가능**
+2. `expected.roundtrip.json` schema v3
+   - `xhtml_fragment`
+   - `mdx_content_hash`
+   - `mdx_line_range`
+   - `reconstruction`
+   - document envelope / separator
 
-현재 파이프라인은 모든 변경을 "텍스트 변경"으로 시작하되, 특정 조건에서 "구조 변경"(inner XHTML 재생성)으로 전환한다. 이 전환 조건이 `has_inline_format_change()` 등의 휴리스틱에 의존하므로:
+실전에서는 두 번째가 더 중요합니다. 현재 reverse-sync의 안정성은 "이 블록이 어떤 XHTML 요소인가"보다 "이 블록이 원래 어떤 fragment였고 어떤 템플릿으로 재사용할 수 있는가"에 더 크게 의존합니다.
 
-- 감지하지 못하는 edge case가 계속 발견된다 (2.2의 3건)
-- 감지 로직 추가 → 새로운 edge case 발견 → 또 추가, 의 무한 루프
+## 4. 현재 구현된 실행 파이프라인
 
-**문제 3: 리스트의 이중 구조**
+표준 경로는 `run_verify()`로 이해하는 것이 가장 정확합니다.
 
-MDX 리스트는 단일 블록(`type: 'list'`)이지만, XHTML에서는 `<ul>` 안에 여러 `<li>` 요소로 분해된다. 이 1:N 매핑은 다음과 같은 복잡성을 초래한다:
+1. 원본/교정 MDX 로드
+2. `parse_mdx_blocks()` + `diff_blocks()`
+3. `record_mapping(page.xhtml)`
+4. `generate_sidecar_mapping()` 또는 기존 `mapping.yaml` 활용
+5. `build_sidecar()`로 roundtrip sidecar v3 생성/활용
+6. `build_patches()`로 patch 목록 생성
+7. `patch_xhtml()` 적용
+8. patched XHTML에서 mapping 재기록
+9. patched XHTML을 forward converter로 다시 MDX 변환
+10. `verify_roundtrip()`로 improved MDX와 비교
+11. pass일 때만 push 후보로 간주
 
-- `build_list_item_patches`: 항목별 매칭 시도 → 실패 시 containing block 폴백
-- `_resolve_child_mapping`: 4단계 폴백 (collapse_ws → 공백 제거 → 마커 제거 → 역방향)
-- 항목 수 변경 시 별도 분기 필요 (`f5f307f`)
-- flat list vs nested list 구분 필요 (`ea28d65`)
+중요한 점은, reverse-sync의 성공 정의가 "patch를 만들었다"가 아니라 "forward roundtrip 증명이 끝났다"는 것입니다.
 
-**이 복잡성은 "하나의 MDX 블록 = 하나의 XHTML 요소" 가정이 리스트에서 무너지기 때문이다.**
+## 5. 현재 강한 영역
 
-### 3.2 코드 냄새: patch_builder.py의 God Function
+최근 커밋과 테스트 구조를 볼 때 현재 구현이 상대적으로 강한 영역은 다음과 같습니다.
 
-`build_patches()` (719줄 파일)는 다음을 모두 담당한다:
+### 5.1 paragraph / heading 중심 교정
 
-1. 변경 유형 판별 (modified / added / deleted)
-2. 매핑 전략 결정 (direct / containing / list / table / skip)
-3. 인라인 포맷 변경 감지
-4. 텍스트 정규화 및 비교
-5. 패치 dict 생성
-6. 멱등성 보장 (이미 적용된 변경 스킵)
+- 일반 문단 수정
+- heading 텍스트 수정
+- badge가 섞인 heading의 roundtrip
+- code span / link 주변 공백 보정
 
-**최근 버그 수정 10건 중 7건이 이 파일을 수정했다.** 이는 단일 모듈에 과도한 책임이 집중되어 있음을 보여준다.
+### 5.2 sidecar reconstruction이 잘 작동하는 container
 
-분기 구조를 보면:
+- clean container
+- 일부 callout / ADF panel
+- parameter-bearing container 중 outer wrapper template으로 body만 바꾸는 경로
 
-```
-build_patches()
-  ├── deleted → _build_delete_patch()
-  ├── added → _build_insert_patch()
-  └── modified
-      ├── NON_CONTENT → skip
-      └── _resolve_mapping_for_change()
-          ├── skip → continue
-          ├── list → build_list_item_patches()
-          │     ├── 항목 수 동일
-          │     │   ├── child 매칭 성공
-          │     │   │   ├── inline 변경 → new_inner_xhtml
-          │     │   │   └── text 변경
-          │     │   │       ├── prefix 있음 → transfer + prefix 복원
-          │     │   │       └── prefix 없음 → transfer
-          │     │   └── child 매칭 실패
-          │     │       ├── inline marker 추가 → 전체 재생성
-          │     │       └── containing block 폴백
-          │     └── 항목 수 다름 → 전체 inner XHTML 재생성
-          ├── table → build_table_row_patches()
-          ├── containing → 그룹화 후 일괄 transfer
-          └── direct
-              ├── inline 변경 → new_inner_xhtml
-              └── text 변경
-                  ├── 이미 적용됨 → skip (멱등성)
-                  ├── old ≠ xhtml → transfer_text_changes
-                  └── old == xhtml → 직접 교체
-```
+### 5.3 list의 일부 고질 회귀
 
-이 분기 트리는 14단계 깊이에 6가지 전략을 포함한다. 새로운 edge case가 발견될 때마다 분기가 추가되는 구조이다.
+최근 수정으로 다음 류의 문제는 이전보다 많이 완화되었습니다.
 
-### 3.3 코드 냄새: 다단계 폴백 체인
+- marker 뒤 공백 감지
+- 선행 공백 축소
+- continuation line merge
+- preserved anchor list의 item 제거
+- callout 내부 list marker 공백
 
-`_resolve_mapping_for_change()`는 매핑을 찾기 위해 다음 순서로 시도한다:
+이는 2026-04-13의 visible segment 모델 도입까지 이어진 흐름입니다.
 
-1. sidecar 직접 조회 (`find_mapping_by_sidecar`)
-2. parent mapping → child 해석 (`_resolve_child_mapping`)
-3. 텍스트 포함 검색 (`_find_containing_mapping`)
-4. 리스트/테이블 전략으로 전환
+## 6. 현재 취약한 영역
 
-`_resolve_child_mapping()`도 내부적으로 4단계 폴백:
+### 6.1 table
 
-1. `collapse_ws` 완전 일치
-2. 공백 제거 완전 일치
-3. XHTML 리스트 마커 제거 후 비교
-4. MDX 리스트 마커 제거 후 비교
+테이블은 여전히 가장 조심스럽게 다뤄지는 영역입니다.
 
-이 폴백 체인은 매핑의 정확성에 대한 **자신감 부족**을 코드로 표현한 것이다. sidecar mapping이 정확하다면 폴백이 불필요하다.
+현재 구현은 table을 공격적으로 patch하지 않습니다. 위험할 경우 명시적으로 skip합니다.
 
-### 3.4 코드 냄새: 정규화 함수의 폭발적 증가
+대표 skip reason:
 
-텍스트 비교를 위한 정규화 함수가 여러 모듈에 분산되어 있다:
+- `no_mapping`
+- `missing_roundtrip_sidecar`
+- `preserved_anchor_table`
+- `raw_html_table`
+- `not_markdown_table`
+- `unsafe_html_table_edit`
 
-| 모듈 | 함수 | 용도 |
-|------|------|------|
-| `text_utils.py` | `normalize_mdx_to_plain()` | MDX → plain text |
-| `text_utils.py` | `collapse_ws()` | 공백 축약 |
-| `text_utils.py` | `strip_for_compare()` | 불가시 문자 제거 |
-| `text_utils.py` | `strip_list_marker()` | 리스트 마커 제거 |
-| `patch_builder.py` | `normalize_table_row()` | 테이블 행 정규화 |
-| `patch_builder.py` | `_strip_block_markers()` | heading/list 마커 제거 |
-| `roundtrip_verifier.py` | 9개 `_normalize_*` 함수 | 검증 시 정규화 |
+즉, "table도 어느 정도 된다"가 아니라 "안전한 table만 제한적으로 처리한다"가 현재 상태에 더 가깝습니다.
 
-**총 15개 이상의 정규화 함수**가 존재하며, 각각 미묘하게 다른 규칙을 적용한다. 이는 "어느 수준의 동일성이면 같다고 볼 것인가"에 대한 일관된 정의가 없음을 의미한다.
+### 6.2 preserved anchor가 섞인 복합 구조
 
-### 3.5 코드 냄새: xhtml_patcher.py의 취약한 텍스트 위치 추적
+preserved anchor는 현재 reverse-sync가 원본 XHTML fragment의 정체성을 끝까지 보존하려는 이유를 가장 잘 보여주는 케이스입니다.
 
-`_apply_text_changes()`는 다음 알고리즘을 사용한다:
+- 일반 emitter 재생성으로는 anchor 관련 메타가 쉽게 깨집니다.
+- 그래서 rewrite_on_stored_template 또는 sidecar reconstruction으로 우회합니다.
+- 하지만 list/table/container가 중첩되면 여전히 리스크가 큽니다.
 
-1. `old_text.strip()`에서 각 DOM text node의 위치를 `str.find()`로 추적
-2. `SequenceMatcher`로 old→new 변경(opcode)을 계산
-3. 각 text node의 [start, end) 범위에 해당하는 opcode를 적용
+### 6.3 normalization에 민감한 roundtrip
 
-이 알고리즘의 문제점:
+최근 커밋을 보면 verifier와 converter 정규화가 계속 조정되고 있습니다.
 
-- **`str.find()`는 "첫 번째 일치"만 반환**: 동일한 텍스트가 반복되면 위치가 틀려진다
-- **text node의 경계가 opcode의 경계와 일치하지 않을 때**: `replace` opcode를 비율(`ratio`)로 분배하는데, 이는 근사치이며 CJK 문자에서 부정확
-- **인라인 태그 사이의 gap 처리**: `<strong>A</strong> B`에서 gap(" ")이 삭제될 때의 처리를 별도 로직으로 해결 (`60c5390`)
+이 말은 곧,
 
----
+- 실제 patch는 맞지만 verifier에서 mismatch가 날 수 있고
+- 반대로 verifier를 느슨하게 하면 실제 회귀를 놓칠 수 있으며
+- converter 동작 변화가 reverse-sync pass/fail에 직접 영향을 준다는 뜻입니다.
 
-## 4. 구조적 개선 제안
+따라서 reverse-sync는 독립 서브시스템이 아니라 forward converter의 특성에 강하게 결합되어 있습니다.
 
-### 4.1 전략 전환: "텍스트 패칭" → "선택적 재생성" 중심으로
+### 6.4 `patch_builder.py` 단일 집중
 
-현재는 **텍스트 패칭이 기본**, 실패 시 재생성으로 폴백하지만, 이를 역전시킨다:
+현재 구조에서 가장 큰 유지보수 리스크는 `patch_builder.py`에 전략 분기, 예외 처리, sidecar fallback, skip 분류가 과도하게 모여 있다는 점입니다.
 
-| 현재 | 개선 후 |
-|------|---------|
-| text transfer가 기본 | inner XHTML 재생성이 기본 |
-| `has_inline_format_change` → 재생성 | 단순 텍스트만 text transfer |
-| edge case마다 분기 추가 | 재생성이 기본이므로 분기 축소 |
+이 파일은 현재 기능적으로 중요하지만, 새로운 회귀가 생길 때마다 이곳에 if/elif가 더 쌓이기 쉬운 구조입니다.
 
-**기대 효과:**
-- `text_transfer.py`, `_apply_text_changes()`의 복잡한 위치 매핑 로직의 사용 빈도 감소
-- `has_inline_format_change()` 같은 감지 휴리스틱 불필요
-- patch_builder.py의 분기 트리 대폭 단순화
+## 7. 테스트/픽스처가 보여주는 현재 상태
 
-**trade-off:**
-- 재생성 시 Confluence 전용 태그(`<ac:emoticon>`, `<ac:link>` 등)가 손실될 수 있음
-- `lost_info_patcher.py`의 복원 범위를 확대해야 함
-- 일부 케이스에서 XHTML 포맷(공백, 속성 순서 등)이 변경될 수 있음
+저장소 기준 확인 가능한 수치는 다음과 같습니다.
 
-### 4.2 patch_builder.py 분해
+- `confluence-mdx/tests/testcases/` 디렉터리: 21개
+- 각 testcase에 `page.xhtml`, `expected.mdx`, `expected.roundtrip.json` 존재: 21개
+- `original.mdx`, `improved.mdx`, `expected.reverse-sync.patched.xhtml`를 갖춘 reverse-sync fixture: 16개
+- `confluence-mdx/tests/reverse-sync/pages.yaml` 항목 수: 67개
+- 그중 `failure_type` 메타데이터가 있는 항목: 41개
+- `expected_status: pass` 항목: 43개
 
-현재 719줄 단일 파일을 책임 단위로 분리한다:
+이 숫자가 의미하는 바는 다음과 같습니다.
 
-| 새 모듈 | 책임 | 현재 위치 |
-|---------|------|-----------|
-| `strategy_resolver.py` | 변경 유형별 전략 결정 | `_resolve_mapping_for_change` |
-| `list_patcher.py` | 리스트 블록 전용 패치 로직 | `build_list_item_patches`, `split_list_items` |
-| `table_patcher.py` | 테이블 전용 패치 로직 | `build_table_row_patches`, `split_table_rows` |
-| `inline_detector.py` | 인라인 포맷 변경 감지 | `has_inline_format_change`, `_extract_inline_markers` |
-| `patch_builder.py` | 오케스트레이션만 담당 | `build_patches` (축소) |
+1. reverse-sync는 순수 unit test만으로 관리되지 않고, 문서 페이지 fixture 중심의 회귀 방지 체계를 함께 사용합니다.
+2. 실패를 "아예 모르는 문제"로 두기보다 `failure_type`, severity, label로 분류하려는 운영 방식이 이미 존재합니다.
+3. pages.yaml은 단순 catalog가 아니라 테스트 메타데이터 저장소 역할도 동시에 합니다.
 
-### 4.3 매핑 정확성 개선
+## 8. 기존 문서가 왜 stale해졌는가
 
-현재 `generate_sidecar_mapping()`의 텍스트 기반 매칭을 개선하여 폴백 체인의 필요성을 줄인다:
+기존 문서의 핵심 문제는 "틀린 문제의식"이 아니라 "문제의식은 맞았지만 구현 상태가 바뀌었다"는 데 있습니다.
 
-- forward converter가 mapping.yaml을 생성할 때 **확정적인 MDX 블록 인덱스**를 기록
-- `_resolve_child_mapping()`의 4단계 폴백 → sidecar가 child 매핑도 포함하도록 확장
-- `_find_containing_mapping()`의 텍스트 포함 검색 → sidecar에서 parent-child 관계를 명시
+예를 들어 다음은 여전히 유효한 진단입니다.
 
-### 4.4 정규화 전략 통합
+- patch_builder가 너무 크다
+- 리스트/테이블/인라인 경계가 위험하다
+- normalization이 구조적 부담이다
+- reverse-sync는 단순 text patching으로 안정화되기 어렵다
 
-15개 이상의 정규화 함수를 **비교 수준(level)** 기반으로 체계화한다:
+반면 다음은 더 이상 현재 상태를 반영하지 않습니다.
 
-| Level | 적용 | 용도 |
-|-------|------|------|
-| L0: exact | 변환 없음 | 엄격 검증 |
-| L1: whitespace | `collapse_ws` + trailing ws 제거 | 매핑 조회 |
-| L2: markup | L1 + 인라인 마커 제거 + HTML unescape | 블록 매칭 |
-| L3: structural | L2 + 리스트 마커 + heading 마커 제거 | 폴백 매칭 |
+- `text_transfer.py` 중심 설명
+- `list_patcher.py`, `table_patcher.py`가 여전히 핵심이라는 전제
+- roundtrip sidecar를 backward verify 보조 정도로만 보는 설명
+- phase 문서의 예정 작업이 아직 미구현이라고 가정하는 표현
 
-현재는 각 호출부에서 임의로 정규화 수준을 선택하고 있어, 동일한 비교에서도 정규화 수준이 불일치하는 경우가 있다.
+즉, 기존 문서를 그대로 읽으면 "아직 해야 할 설계"와 "이미 구현된 설계"가 섞여 보입니다.
 
-### 4.5 xhtml_patcher.py의 알고리즘 개선
+## 9. 현재 상태를 문서화할 때의 원칙
 
-`_apply_text_changes()`의 `str.find()` 기반 위치 추적을 개선한다:
+현재 문서를 유지보수할 때는 다음 원칙이 필요합니다.
 
-- text node 순회 시 DOM 순서를 기반으로 위치를 누적 계산 (str.find 제거)
-- `replace` opcode의 비율 분배 대신, opcode 경계를 text node 경계에 맞춰 분할
-- 대안: `_apply_text_changes` 전체를 `_replace_inner_html`로 대체하는 것을 기본으로 고려
+1. 계획과 현황을 분리합니다.
+   - 구현 상태 문서는 현재 코드가 실제로 하는 일을 적어야 합니다.
+   - 계획 문서는 앞으로 바꿀 설계를 적어야 합니다.
 
----
+2. `mapping.yaml`과 roundtrip sidecar를 구분해서 설명합니다.
+   - 둘은 역할이 다릅니다.
 
-## 5. 리팩토링 대상 요약
+3. 성공 사례보다 보수적 경계를 명시합니다.
+   - 어떤 변경은 일부러 skip한다는 점을 숨기면 안 됩니다.
 
-### 5.1 높은 우선순위 (버그 재발 방지)
+4. reverse-sync를 forward converter와 분리해서 서술하지 않습니다.
+   - 최종 성공 판정은 roundtrip에 의존합니다.
 
-| # | 대상 | 유형 | 기대 효과 |
-|---|------|------|-----------|
-| R1 | `build_patches` direct 경로: text transfer → inner XHTML 재생성 기본 전환 | 전략 변경 | 2.1 위치 매핑 + 2.2 인라인 감지 버그 근본 해결 |
-| R2 | `build_list_item_patches` 단순화: child 매칭 실패 시 즉시 재생성 | 전략 변경 | 리스트 관련 버그 근본 해결, `_resolve_child_mapping` 4단계 폴백 제거 |
-| R3 | `_apply_text_changes`의 str.find() → DOM 순서 기반 위치 추적 | 알고리즘 | 위치 매핑 정확성 향상 |
+5. patch_builder를 "세부 구현"이 아니라 "정책 엔진"으로 설명합니다.
 
-### 5.2 중간 우선순위 (유지보수성 개선)
+## 10. 결론
 
-| # | 대상 | 유형 | 기대 효과 |
-|---|------|------|-----------|
-| R4 | `patch_builder.py` 분해 (719줄 → 5개 모듈) | 구조 | 변경 영향 범위 축소, 테스트 용이성 |
-| R5 | 정규화 함수 체계화 (Level 기반) | 설계 | 비교 일관성, 새 정규화 추가 시 혼란 방지 |
-| R6 | `generate_sidecar_mapping()`에 child 매핑 포함 | 데이터 | 폴백 체인 축소, 매핑 정확성 향상 |
+현재 reverse-sync는 실패한 실험 단계가 아니라, 이미 상당한 수준의 sidecar/reconstruction 기반 시스템으로 진화한 상태입니다. 다만 그 대가로 다음 특성이 분명해졌습니다.
 
-### 5.3 낮은 우선순위 (코드 품질)
+- 안정성은 올라갔지만 구조는 복잡해졌습니다.
+- fragment identity 보존이 핵심이 되었고, 단순 emitter 재생성 전략은 중심에서 밀려났습니다.
+- list/table/preserved anchor 같은 영역은 여전히 기능 경계가 뚜렷합니다.
+- 향후 개선은 "기능 추가"보다 "정책 분리, 경계 명시, 테스트 피라미드 정리"에 더 가깝게 접근해야 합니다.
 
-| # | 대상 | 유형 | 기대 효과 |
-|---|------|------|-----------|
-| R7 | `_iter_block_children()` 중복 제거 (mapping_recorder ↔ xhtml_patcher) | 중복 제거 | 기존 분석(4.1)과 동일 |
-| R8 | `NON_CONTENT_TYPES` 상수 중복 (block_diff, patch_builder, sidecar, rehydrator) | 중복 제거 | 4곳에서 독립 정의 → 단일 정의 |
-| R9 | `reverse_sync_cli.py`의 sidecar 조립 인라인 코드 → 함수 추출 | 추출 | run_verify() 285~302행의 인라인 조립 → 전용 함수 |
-
----
-
-## 6. 주요 수치
-
-| 지표 | 값 |
-|------|-----|
-| reverse_sync/ 총 줄 수 | ~3,263 |
-| patch_builder.py 줄 수 | 719 (전체의 22%) |
-| 최근 12 커밋 중 버그 수정 | 10건 (83%) |
-| patch_builder.py 수정 커밋 | 7/10건 (70%) |
-| 정규화 함수 수 | 15+ |
-| `_resolve_child_mapping` 폴백 단계 | 4 |
-| `_resolve_mapping_for_change` 전략 수 | 5 (direct, containing, list, table, skip) |
-
----
-
-## 8. 구현 진행 상황
-
-### 8.1 R1: direct 경로 inner XHTML 재생성 — 완료
-
-- **PR**: #858 (merged)
-- `build_patches`의 direct 경로에서 text transfer 대신 `mdx_block_to_inner_xhtml` 재생성을 기본으로 전환
-- `lost_info_patcher.py`의 `apply_lost_info`로 `<ac:*>` 요소 보존
-
-### 8.2 R2: list_patcher 재생성 — 완료 (후속 과제 있음)
-
-- **PR**: #859
-- `build_list_item_patches`에서 child 매칭 실패 시 전체 리스트 inner XHTML 재생성
-- containing block 제거 폴백 완전 제거
-- `<ac:image>` 포함 리스트는 `transfer_text_changes`로 폴백하는 가드 추가
-
-#### R2 구현 후 발견된 후속 과제
-
-R2 구현 중 3개 테스트 케이스(544112828, 544379140, 544384417)에서 round-trip 검증이 `pass → fail`로 변경됨. 원인 분석 결과 2가지 후속 과제가 도출됨.
-
-**F1. `<span style>` 가드 추가 (우선순위: 높음)**
-
-| 항목 | 내용 |
-|------|------|
-| 위치 | `list_patcher.py` — `_regenerate_list_from_parent` 및 per-child 경로 |
-| 증상 | 리스트 항목 내 `<span style="color: ...">` 인라인 스타일이 재생성 시 소실 |
-| 예시 | 544379140: `<span style="color: rgb(76,154,255);">See Log Template...</span>` → 일반 텍스트 |
-| 해결 방향 | `<ac:image>` 가드와 동일한 패턴으로 `<span style=` 포함 시 `transfer_text_changes`로 폴백 |
-| 영향 | Confluence에서 색상이 적용된 텍스트가 일반 텍스트로 변경되는 **실제 시각적 변화** |
-
-**F2. `<ol start="1">` 보존 (우선순위: 낮음)**
-
-| 항목 | 내용 |
-|------|------|
-| 위치 | `mdx_to_xhtml_inline.py` — `_render_nested_list` |
-| 증상 | 재생성 시 `<ol start="1">` → `<ol>`로 변경 (HTML 기본값이므로 기능 동일) |
-| 예시 | 544379140: 4건, 544384417: 8건의 `start` 속성 제거 |
-| 해결 방향 | `_render_nested_list`에서 ordered list 생성 시 `start="1"` 속성 출력 |
-| 영향 | 기능적 영향 없음 (Confluence 렌더링 동일), 불필요한 XHTML 변경 최소화 |
-
-### 8.3 F1+F2: `<span style>` 가드 + `<ol start="1">` 보존 — 완료
-
-- **PR**: #862 (merged)
-- `list_patcher.py`에서 `<span style=` 포함 시 `transfer_text_changes`로 폴백하는 가드 추가
-- `mdx_to_xhtml_inline.py`에서 ordered list 생성 시 `start="1"` 속성 출력
-
-### 8.4 F3: direct 경로 `<ac:link>` 가드 — 완료
-
-- **PR**: #864 (예정)
-- `build_patches`의 direct 경로에서 매핑 XHTML에 `<ac:link>` 포함 시 inner XHTML 재생성 대신 `transfer_text_changes`로 폴백
-- HTML table 블록 내 `<ac:link>` 요소가 `<a href>`로 소실되는 문제 해결
-- 544178405 테스트케이스 `status: fail → pass` 전환 (16/16 전체 pass 달성)
-
----
-
-## 7. 결론
-
-reverse-sync의 반복적인 버그는 **"텍스트 패칭이 기본, 재생성이 폴백"이라는 설계 전략**에서 비롯된다. 텍스트 패칭은 두 좌표계(MDX ↔ XHTML) 사이의 문자 단위 정렬을 요구하며, 이는 인라인 마커, 공백 차이, DOM 구조 경계에서 본질적으로 불안정하다.
-
-이 전략을 **"재생성이 기본, 텍스트 패칭이 최적화"**로 역전시키면, 대부분의 edge case 분기가 불필요해지고, patch_builder.py의 복잡도를 대폭 줄일 수 있다.
-
-단, 재생성 전략으로의 전환에는 Confluence 전용 요소(`<ac:*>`) 보존이라는 별도의 과제가 있으므로, `lost_info_patcher.py`의 확장이 선행되어야 한다.
+이 문서는 현재 구현을 설명하는 기준선입니다. 후속 계획은 별도의 계획 문서에서 다시 정의해야 합니다.
diff --git a/confluence-mdx/docs/architecture.md b/confluence-mdx/docs/architecture.md
index 6c580a83d..d914b530c 100644
--- a/confluence-mdx/docs/architecture.md
+++ b/confluence-mdx/docs/architecture.md
@@ -252,227 +252,246 @@ MDX 상대 경로                     Confluence XHTML
 
 ## Reverse Sync: MDX 편집 → Confluence 반영 (`reverse_sync/`)
 
-MDX 파일의 교정 내용을 Confluence XHTML에 반영한다. 블록 단위 diff를 XHTML 패치로 변환하는 정밀한 파이프라인이다.
+현재 reverse-sync는 "텍스트만 덮어쓰는 간단한 패처"가 아니라, MDX diff를 XHTML DOM에 보수적으로 되돌려 넣고 다시 forward converter로 검증한 뒤에만 통과시키는 파이프라인입니다. 2026-03 이후 구현은 sidecar 기반 identity preservation과 fragment replacement를 중심으로 재편되었고, 기존 문서에 남아 있던 `text_transfer.py`, `list_patcher.py`, `table_patcher.py` 중심 설명은 더 이상 현재 상태를 반영하지 않습니다.
 
 ### 전체 흐름
 
 ```
-원본 MDX (main 브랜치)    교정된 MDX (작업 브랜치)
-        │                        │
-        ▼                        ▼
-  parse_mdx_blocks()       parse_mdx_blocks()
-        │                        │
-        ▼                        ▼
-   MdxBlock[]               MdxBlock[]
-        │                        │
-        └────────┬───────────────┘
-                 ▼
-          diff_blocks()          ← 블록 단위 diff
-                 │
-                 ▼
-          BlockChange[]          ← modified / added / deleted
-                 │
-        ┌────────┴────────┐
-        ▼                 ▼
-  record_mapping()   Sidecar 인덱스
-  (원본 XHTML)       (mapping.yaml)
-        │                 │
-        └────────┬────────┘
-                 ▼
-          build_patches()        ← MDX 변경 → XHTML 패치 변환
-                 │
-                 ▼
-          patch_xhtml()          ← BeautifulSoup으로 XHTML 수정
-                 │
-                 ▼
-          verify_roundtrip()     ← 라운드트립 검증 (XHTML→정순변환→MDX→비교)
-                 │
-                 ▼
-       Confluence API push       ← (선택) 실제 반영
-```
-
-### 모듈 구성
-
-| 모듈 | 줄 수 | 역할 |
-|------|-------|------|
-| `mdx_block_parser.py` | 129 | MDX → MdxBlock 시퀀스 파싱 (splice rehydrator 호환용 유지) |
-| `block_diff.py` | 90 | 두 MdxBlock 시퀀스 diff |
-| `mapping_recorder.py` | 210 | XHTML → BlockMapping 추출 |
-| `sidecar.py` | 524 | Roundtrip sidecar + 매핑 인덱스 |
-| `fragment_extractor.py` | 204 | XHTML byte-exact 프래그먼트 추출 |
-| `patch_builder.py` | 547 | BlockChange → XHTML 패치 변환 |
-| `text_transfer.py` | 79 | 텍스트 변경을 XHTML에 전사 |
-| `xhtml_patcher.py` | 333 | 패치를 XHTML에 적용 |
-| `roundtrip_verifier.py` | 174 | 패치 결과 라운드트립 검증 |
-| `mdx_to_xhtml_inline.py` | 240 | 삽입 패치용 MDX → XHTML 블록 변환 (`mdx_to_storage.inline` 활용) |
-| `rehydrator.py` | 149 | Sidecar 기반 무손실 XHTML 복원 (fast path + splice + fallback) |
-| `byte_verify.py` | 126 | Byte-equal 검증 (document-level + forced-splice) |
-| `confluence_client.py` | 65 | Confluence REST API 클라이언트 |
+원본 MDX (main / testcase original.mdx)     교정 MDX (작업 브랜치 / improved.mdx)
+                  │                                          │
+                  ├──────────── parse_mdx_blocks() ───────────┤
+                  ▼                                          ▼
+             original_blocks                           improved_blocks
+                         └──────── diff_blocks() ────────┘
+                                      │
+                                      ▼
+                             BlockChange[] + alignment
+                                      │
+             ┌────────────────────────┼────────────────────────┐
+             ▼                        ▼                        ▼
+   record_mapping(page.xhtml)   generate_sidecar_mapping()   build_sidecar()
+   (현재 XHTML 블록 구조)       (`mapping.yaml`)              (`expected.roundtrip.json` v3)
+             │                        │                        │
+             └────────────────────────┴──────────────┬─────────┘
+                                                     ▼
+                                             build_patches()
+                                                     │
+                                  delete / insert / modify / replace_fragment
+                                                     │
+                                                     ▼
+                                              patch_xhtml()
+                                                     │
+                                                     ▼
+                               record_mapping(patched_xhtml) + converter/cli.py
+                                                     │
+                                                     ▼
+                                            verify_roundtrip()
+                                                     │
+                                                     ▼
+                                   pass → (선택) push / fail → result.yaml 기록
+```
+
+핵심 포인트는 다음과 같습니다.
+
+- `run_verify()`가 사실상 reverse-sync의 표준 실행 경로입니다.
+- `mapping.yaml`만으로는 현재 구현을 설명할 수 없고, `expected.roundtrip.json` 기반 sidecar v3가 실제 identity fallback과 reconstruction에 깊게 관여합니다.
+- 모호한 변경은 억지로 반영하지 않고 `skipped_changes`로 보고합니다.
+- 성공 조건은 "패치 생성"이 아니라 "patched XHTML을 다시 forward 변환했을 때 improved MDX와 일치"입니다.
+
+### 현재 모듈 구성
+
+| 모듈 | 현재 역할 |
+|------|-----------|
+| `reverse_sync_cli.py` | verify / push 오케스트레이션, 결과 파일 생성, 배치 처리, Confluence push 안전장치 |
+| `mdx_block_parser.py` | MDX 블록 파싱 래퍼 |
+| `block_diff.py` | 블록 단위 diff + alignment 계산 |
+| `mapping_recorder.py` | XHTML에서 top-level / child block mapping 추출 |
+| `sidecar.py` | `mapping.yaml` v3 생성, roundtrip sidecar v3 생성/검증, identity 인덱스, lost_info 로딩 |
+| `fragment_extractor.py` | XHTML fragment를 byte-exact 수준으로 추출 |
+| `patch_builder.py` | reverse-sync의 정책 엔진. direct / containing / paired / list / table / skip 분기 결정 |
+| `visible_segments.py` | list 경로에서 visible segment 모델을 사용해 marker/공백/내용 변경을 더 정밀하게 판별 |
+| `reconstructors.py` | preserved anchor, container, list item 등에서 원본 fragment 템플릿을 유지한 채 부분 재구성 |
+| `mdx_to_xhtml_inline.py` | insert/replace용 MDX 블록을 XHTML fragment로 생성 |
+| `xhtml_patcher.py` | patch를 실제 XHTML DOM/fragment에 적용 |
+| `roundtrip_verifier.py` | normalize / lenient / no-normalize 옵션을 포함한 roundtrip 검증 |
+| `rehydrator.py` | sidecar fragment 재조립/검증 보조 유틸 |
+| `confluence_client.py` | Confluence REST API push |
 
 ### 단계별 상세
 
-#### Step 1: MDX 블록 파싱 (`mdx_to_storage/parser.py`)
+#### Step 1: MDX 블록 파싱과 diff
 
-MDX 텍스트를 줄 단위 상태머신으로 파싱하여 블록 시퀀스를 생성한다. (`mdx_block_parser.py`는 backward-compat re-export 래퍼)
+원본/교정 MDX를 `parse_mdx_blocks()`로 파싱한 뒤 `diff_blocks()`로 `BlockChange[]`와 alignment를 계산합니다.
 
-**⚠️ 알려진 파싱 버그:** list item 뒤 빈 줄 없이 이어지는 연속행(문장 단위 줄바꿈)을 별도 `paragraph` 블록으로 잘못 분리한다. Markdown 규칙상 paragraph 분리는 빈 줄이 필요하며, 빈 줄 없는 연속행은 동일 list item의 일부다. 이 버그가 sidecar alignment 오류의 근본 원인이다.
+- non-content 블록(frontmatter, import, empty 등)은 후속 단계에서 제외됩니다.
+- reverse-sync는 line range와 block hash를 이후 sidecar identity lookup에 재사용합니다.
+- 과거 문서에 있던 일부 파싱 버그 설명은 현재 구현과 완전히 일치하지 않습니다. 현재 기준에서 중요한 것은 "블록 경계가 sidecar line range / content hash와 함께 identity로 사용된다"는 점입니다.
 
-```python
-Block(type, content, level, language, children, attrs, line_start, line_end)
-# type: "frontmatter" | "import_statement" | "heading" | "paragraph" |
-#       "code_block" | "list" | "html_block" | "callout" | "figure" |
-#       "details" | "badge" | "table" | "blockquote" | "empty"
-```
+#### Step 2: XHTML 구조 기록
 
-#### Step 2: 블록 Diff (`block_diff.py`)
+`record_mapping(page.xhtml)`는 XHTML에서 블록 구조를 추출해 `BlockMapping` 목록을 만듭니다.
 
-SequenceMatcher 기반으로 원본/교정 블록 시퀀스를 정렬하고 변경 사항을 추출한다.
+- heading / paragraph / list / table / code / html_block / macro container 등을 추출합니다.
+- callout, ADF panel, expand 같은 compound block은 children 매핑을 함께 기록합니다.
+- reverse-sync는 patched XHTML에도 동일 recorder를 다시 적용해 `reverse-sync.mapping.patched.yaml`을 생성합니다.
 
-```python
-BlockChange(index, change_type, old_block, new_block)
-# change_type: "modified" | "added" | "deleted"
-```
+#### Step 3: 두 종류의 sidecar 구축
 
-#### Step 3: XHTML 매핑 추출 (`mapping_recorder.py`)
+현재 구현은 두 종류의 메타데이터를 함께 사용합니다.
 
-원본 XHTML을 BeautifulSoup으로 파싱하여 블록 레벨 요소를 추출하고 XPath를 부여한다.
+1. `mapping.yaml`
+   - `generate_sidecar_mapping()`이 생성합니다.
+   - 타입 호환성 기반 two-pointer 정렬로 XHTML top-level block과 MDX content block을 연결합니다.
+   - reverse-sync에서는 주로 `mdx_to_sidecar` 역인덱스와 page/block-level `lost_info` 로딩에 사용합니다.
 
-```python
-BlockMapping(block_id, type, xhtml_xpath, xhtml_text, xhtml_plain_text,
-             xhtml_element_index, children)
-# type: "heading" | "paragraph" | "list" | "code" | "table" | "html_block"
-# xhtml_xpath: "p[3]", "macro-info[1]" 등
-```
+2. `expected.roundtrip.json` (schema v3)
+   - `build_sidecar()`가 생성합니다.
+   - XHTML fragment, `mdx_content_hash`, `mdx_line_range`, `reconstruction` 메타데이터를 함께 저장합니다.
+   - 현재 reverse-sync에서 사실상 더 중요한 메타데이터입니다. list fallback, preserved anchor, container reconstruction, roundtrip integrity 검증에 사용됩니다.
 
-Callout 매크로, ADF 패널 내부의 자식 요소는 `children` 필드로 재귀 추출한다.
+#### Step 4: 패치 생성 (`patch_builder.py`)
 
-#### Step 4: Sidecar 인덱스 구축 (`sidecar.py`)
+`patch_builder.py`가 현재 reverse-sync의 실제 정책 엔진입니다. 이 모듈은 각 변경을 다음 중 하나로 분기합니다.
 
-`mapping.yaml`을 로드하여 O(1) 조회 인덱스를 구축한다.
+- `delete`: 기존 XHTML 요소 제거
+- `insert`: 새 MDX 블록을 XHTML로 생성해 삽입
+- `modify`: 안전한 텍스트 수준 변경
+- `replace_fragment`: fragment 전체를 교체하되 sidecar/reconstruction metadata를 활용해 원본 구조를 최대한 보존
+- `skip`: 위험하거나 identity가 불충분한 변경을 명시적으로 보고
 
-```python
-mdx_to_sidecar   = build_mdx_to_sidecar_index(mappings)    # MDX 블록 인덱스 → SidecarEntry
-xpath_to_mapping = build_xpath_to_mapping(block_mappings)   # XPath → BlockMapping
-```
+현재 구현의 특징:
+
+- delete+add가 같은 인덱스에서 만나면 `paired` 케이스로 보고 전체 fragment replacement를 우선 검토합니다.
+- clean block, container sidecar, preserved anchor, parameter-bearing container, markdown table 여부에 따라 다른 reconstruction 경로를 탑니다.
+- list 경로는 `visible_segments.py`를 사용해 marker 뒤 공백, 선행 공백 축소, continuation line merge 같은 회귀를 줄이도록 강화되었습니다.
+- table 경로는 whole-fragment replacement를 시도하되, 위험한 경우 `no_mapping`, `missing_roundtrip_sidecar`, `preserved_anchor_table`, `raw_html_table`, `not_markdown_table`, `unsafe_html_table_edit` 등 이유로 skip합니다.
+- legacy `mapping.yaml`이 list를 충분히 설명하지 못하는 경우, roundtrip sidecar v3의 `mdx_content_hash + mdx_line_range` identity fallback으로 매핑을 복원합니다.
 
-**조회 체인:** `MDX 블록 인덱스 → SidecarEntry → BlockMapping → XHTML XPath`
+즉, 현재 reverse-sync는 "가능하면 직접 수정"보다 "안전하면 fragment replacement, 아니면 skip"에 더 가깝습니다.
 
-#### Step 5: 패치 생성 (`patch_builder.py`)
+#### Step 5: XHTML 패치 적용
 
-각 `BlockChange`에 대해 sidecar 인덱스로 대응하는 XHTML 요소를 찾고, 텍스트 변경을 패치로 변환한다.
+`xhtml_patcher.py`는 patch 목록을 XHTML에 적용합니다.
 
-- **Modified**: `text_utils`로 MDX를 일반 텍스트로 정규화 → `text_transfer`로 XHTML 텍스트에 변경 전사
-- **Added**: `mdx_to_xhtml_inline`로 새 MDX 블록을 XHTML 요소로 변환 → insert 패치
-- **Deleted**: 대응 XPath 요소 삭제 패치
-- **리스트/테이블**: 항목별 세분화된 패치 (항목 매칭, 셀 매칭)
+- action은 대체로 `delete`, `insert_before`, `insert_after`, `modify`, `replace_fragment` 계열로 정리됩니다.
+- 단순 문자열 치환이 아니라 DOM 요소 탐색 + fragment 재파싱을 조합합니다.
+- replace_fragment는 reconstruction을 거쳐 생성된 XHTML 조각을 그대로 주입하는 경우가 많습니다.
 
-자식 매핑 해석 (`_resolve_child_mapping`): Callout 내부 단락 등은 정규화된 텍스트로 4단계 비교하여 매칭한다.
+#### Step 6: roundtrip proof
 
-#### Step 6: XHTML 패치 적용 (`xhtml_patcher.py`)
+패치가 끝나면 reverse-sync는 여기서 끝나지 않습니다.
 
-BeautifulSoup으로 패치를 적용한다. 실행 순서: **delete → insert → modify** (인덱스 시프트 방지를 위해 XPath를 사전 해석).
+1. `reverse-sync.patched.xhtml` 저장
+2. `record_mapping()` 재실행 → `reverse-sync.mapping.patched.yaml` 저장
+3. patched XHTML을 `converter/cli.py`로 다시 MDX로 변환 → `verify.mdx` 생성
+4. `verify_roundtrip(improved_mdx, verify_mdx, ...)`로 최종 비교
 
-#### Step 7: 라운드트립 검증 (`roundtrip_verifier.py`)
+`roundtrip_verifier.py`는 다음과 같은 성격을 가집니다.
 
-패치된 XHTML을 정순변환(Forward Conversion)하여 MDX로 되돌린 뒤, 교정된 MDX와 비교한다. 두 MDX가 동일하면 패치가 정확하게 적용된 것이다. 정규화 항목:
-- Trailing whitespace, 날짜 포맷 (한국어 ↔ 영어), 테이블 패딩, h1 헤딩 (페이지 제목), `<td>` 내 줄 합치기, 코드 블록 HTML 엔티티
+- 기본값은 비교적 엄격한 exact/normalized match입니다.
+- `--lenient`, `--no-normalize` 옵션이 존재합니다.
+- 최근 커밋에서 sentence break, table padding, inline whitespace, badge/heading roundtrip 같은 케이스에 맞춰 정규화가 계속 조정되었습니다.
 
-### Reverse Sync 생성 파일
+### 현재 생성/사용 파일
 
 | 파일 | 위치 | 설명 |
 |------|------|------|
-| `reverse-sync.diff.yaml` | `var/<page_id>/` | 블록 변경 사항 |
-| `reverse-sync.mapping.original.yaml` | `var/<page_id>/` | 원본 XHTML 매핑 |
-| `reverse-sync.mapping.patched.yaml` | `var/<page_id>/` | 패치 후 XHTML 매핑 |
-| `reverse-sync.patched.xhtml` | `var/<page_id>/` | 패치된 XHTML |
-| `reverse-sync.result.yaml` | `var/<page_id>/` | 검증 결과 (pass/fail, diff) |
-| `verify.mdx` | `var/<page_id>/` | 라운드트립 검증용: 패치된 XHTML을 정순변환한 MDX |
+| `mapping.yaml` | `var/<page_id>/` | XHTML↔MDX top-level mapping + lost_info |
+| `expected.roundtrip.json` | `tests/testcases/<case_id>/` 또는 fixture | roundtrip sidecar v3 |
+| `reverse-sync.diff.yaml` | `var/<page_id>/` | block diff 결과 |
+| `reverse-sync.mapping.original.yaml` | `var/<page_id>/` | 원본 XHTML mapping dump |
+| `reverse-sync.mapping.patched.yaml` | `var/<page_id>/` | patched XHTML mapping dump |
+| `reverse-sync.patched.xhtml` | `var/<page_id>/` | 패치 결과 XHTML |
+| `reverse-sync.result.yaml` | `var/<page_id>/` | verify 결과, skipped_changes, diff 요약 |
+| `verify.mdx` | `var/<page_id>/` | patched XHTML을 다시 forward 변환한 MDX |
 
 ---
 
 ## Sidecar 시스템
 
-Forward Converter와 Reverse Sync를 연결하는 메타데이터 시스템이다. 두 종류의 sidecar 파일이 있다.
+현재 구현에서 sidecar는 단순한 부가 메타데이터가 아니라 reverse-sync의 identity preservation 계층입니다.
 
-### 1. Mapping Sidecar (`mapping.yaml`)
+### 1. Mapping sidecar (`mapping.yaml`)
 
-`reverse_sync/sidecar.py`의 `generate_sidecar_mapping()`이 생성한다. XHTML 블록과 MDX 블록의 대응 관계를 기록한다. Forward Converter(`converter/cli.py`)와 Reverse Sync CLI(`reverse_sync_cli.py`) 모두 이 함수를 사용한다.
-
-**위치:** `var/<page_id>/mapping.yaml`
+`generate_sidecar_mapping()`이 생성하며, 현재 포맷은 사실상 v3 semantics를 가집니다.
 
 ```yaml
-version: 1
-source_page_id: "608501837"
-mdx_file: "page.mdx"
+page_id: "..."
 mappings:
   - xhtml_xpath: "p[1]"
     xhtml_type: "paragraph"
     mdx_blocks: [3]
-  - xhtml_xpath: "macro-info[1]"
-    xhtml_type: "callout"
-    mdx_blocks: [4, 5, 6]
+    mdx_line_start: 12
+    mdx_line_end: 12
+lost_info:
+  ...
 ```
 
-**생성 과정:**
-1. `record_mapping(xhtml)` → XHTML 블록 목록 (`BlockMapping`)
-2. `parse_mdx_blocks(mdx)` → MDX 블록 목록
-3. 텍스트 기반 lookahead 매칭 → 정규화 텍스트로 XHTML↔MDX 블록 대응
-
-**사용처:** Reverse Sync에서 `build_mdx_to_sidecar_index()`로 O(1) 조회 인덱스를 구축한다.
+현재 역할은 다음에 가깝습니다.
 
-### 2. Roundtrip Sidecar (`expected.roundtrip.json`)
+- top-level XHTML block ↔ MDX block의 기본 연결 제공
+- child alignment 정보 제공 (callout/details 등)
+- `lost_info`를 통해 forward converter에서 사라진 원본 정보 보존
+- reverse-sync의 기본 lookup용 역인덱스 제공
 
-Backward Converter의 검증 인프라에서 사용한다. XHTML 원본을 블록 단위 프래그먼트로 분해하여 저장하며, **프래그먼트 재조립이 원본과 byte-equal**함을 보장한다.
+다만 현재 구현을 이해할 때 `mapping.yaml`만 보면 부족합니다. list/complex container/preserved anchor는 roundtrip sidecar 없이는 설명되지 않는 경우가 많습니다.
 
-**위치:** `tests/testcases/<case_id>/expected.roundtrip.json`
+### 2. Roundtrip sidecar (`expected.roundtrip.json`, schema v3)
 
-**스키마 (v2):**
+현재 핵심 스키마는 다음 필드를 가집니다.
 
 ```json
 {
-  "schema_version": "2",
+  "schema_version": "3",
   "page_id": "544381877",
-  "mdx_sha256": "<MDX 전체 SHA256>",
-  "source_xhtml_sha256": "<XHTML 전체 SHA256>",
+  "mdx_sha256": "...",
+  "source_xhtml_sha256": "...",
   "blocks": [
     {
       "block_index": 0,
       "xhtml_xpath": "h2[1]",
       "xhtml_fragment": "<h2>Title</h2>",
-      "mdx_content_hash": "<블록 MDX SHA256>",
+      "mdx_content_hash": "...",
       "mdx_line_range": [3, 3],
-      "lost_info": null
+      "lost_info": {},
+      "reconstruction": {}
     }
   ],
   "separators": ["\n"],
-  "document_envelope": {
-    "prefix": "",
-    "suffix": "\n"
-  }
+  "document_envelope": {"prefix": "", "suffix": "\n"}
 }
 ```
 
-**핵심 불변조건:**
+이 sidecar의 핵심 역할은 다음과 같습니다.
 
-```
-envelope.prefix
-  + blocks[0].xhtml_fragment
-  + separators[0]
-  + blocks[1].xhtml_fragment
-  + separators[1]
-  + ...
-  + blocks[N].xhtml_fragment
-  + envelope.suffix
-== page.xhtml (byte-equal)
-```
+- fragment + separator + envelope 재조립이 원본 XHTML과 byte-equal이어야 합니다.
+- `mdx_content_hash`와 `mdx_line_range`를 통해 block identity fallback을 제공합니다.
+- `reconstruction` 메타데이터를 통해 preserved anchor / container / list item처럼 emitter 단독 재생성이 위험한 블록을 원본 템플릿 기반으로 재구성합니다.
+- reverse-sync는 이 sidecar를 이용해 "원래 XHTML fragment의 정체성"을 최대한 유지합니다.
+
+### 현재 이해해야 할 원칙
+
+- `mapping.yaml`은 구조적 lookup과 lost_info 전달 계층입니다.
+- `expected.roundtrip.json`은 fragment identity / reconstruction 계층입니다.
+- reverse-sync의 안정성은 결국 "patch를 잘 만들었는가"보다 "sidecar가 원본 fragment를 얼마나 안전하게 다시 사용할 수 있는가"에 더 크게 좌우됩니다.
+
+### 알려진 한계
+
+현재 구현이 강한 영역:
+
+- paragraph / heading 중심 텍스트 교정
+- badge, code span, inline whitespace 등 최근 커밋으로 회귀가 줄어든 인라인 변경
+- preserved anchor가 없거나 sidecar reconstruction metadata가 충분한 container/list 변경
 
-**프래그먼트 추출 (`fragment_extractor.py`):** BeautifulSoup으로 태그 시퀀스를 식별한 뒤, 원문을 직접 스캔하여 정확한 태그 경계를 추출한다. BS4의 속성 재정렬, 공백 정규화, self-closing 변환 문제를 회피한다.
+여전히 취약한 영역:
 
-**무손실 복원 (`rehydrator.py`):** 세 가지 경로로 XHTML을 복원한다:
+- markdown table과 raw HTML table의 경계 케이스
+- preserved anchor가 섞인 list/table
+- parameter-bearing container의 구조 변화
+- forward converter 정규화 특성에 민감한 roundtrip mismatch
+- `patch_builder.py`에 전략/예외/skip 분기가 과도하게 집중된 구조
 
-1. **Fast path** — MDX 전체 SHA256이 sidecar와 일치하면 `reassemble_xhtml()`으로 원본을 document-level byte-equal 복원
-2. **Splice path** — 블록 단위 해시 매칭. sidecar 블록을 순회하면서 MDX 대응 없는 블록(이미지 등)은 원본 fragment 보존, 해시 일치 블록은 원본 fragment 사용, 불일치 블록은 emitter 폴백
-3. **Fallback path** — 전체 emitter 재생성 (byte-equal 미보장)
+이 한계는 "아직 구현되지 않은 기능"이라기보다, 현재 구현이 안전성 우선으로 선택한 보수적 경계에 가깝습니다.
 
 ---