docs + V4 catalog + samples + Phase Q legacy 보존

전체 26 files (20 추가 + 6 수정), 10507 insertions.

Phase Z 문서 :
- docs/architecture/PHASE-Z-CHANGE-LOG.md (신설) — axis-by-axis 의사결정 history
  (newest-on-top). Step 7-A 부터 6 entry 박힘 + 2026-05-08 / 2026-05-08 #2
  (compat 매트릭스 폐기 / 6-B 폐기 / F14 표현 정정 / label gate policy 분리).
- docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md (수정) — Step 5/6/9 Gap note
  append (구조 무변, append-only). 6-B 폐기 사실 + Refinement F.
- docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md (수정) — snapshot date
  2026-05-08 갱신. §3 핵심 missing item 5 (Step 5/6/9 boundary axis breakdown
  + 폐기 기록). §6 한 줄 갱신 — 다음 axis 후보 A~F.

Project root docs :
- PLAN.md / PROGRESS.md / README.md (수정) — 토큰 체계 / 폴더 구조 / 설계 문서 /
  역할 분리 반영.
- IMPROVEMENT-REDESIGN.md (신설) — Phase Z 설계 핵심 문서.
- PROCESS_OVERVIEW.html (신설) — 파이프라인 개요 시각.
- docs/tasks/* (신설) — Phase Z task 문서.

V4 catalog (Phase Z runtime 필수 의존성) :
- tests/matching/v4_full32_result.yaml (신설, 4888 줄) — V4 매칭 결과 32 frame
  × 10 MDX section. lookup_v4_match() / lookup_v4_candidates() 가 본 파일 read.
  Phase Z runtime 이 *없으면 즉시 abort* — clone 후 즉시 동작 가능 보장.

Samples :
- samples/mdx_batch/04.mdx (신설) — MDX04 기본 sample.
- samples/mdx/04. DX 지연 요인.mdx (신설) — MDX04 원본.

Phase Q legacy 보존 (별 axis "Phase Q audit & salvage" 영역) :
- src/block_matcher_tfidf.py / catalog_blocks.py / frame_extractor.py /
  pipeline_v2.py — Phase Q (옛 파이프라인) src 신규 untracked 파일들.
  Phase Z runtime 와 의존성 0. Phase Q audit axis 에서 검토 예정.
- scripts/eval_block_matcher.py / fetch_all_frame_screenshots.py /
  match_17_units_my_matcher.py / match_mdx_strict.py / match_mdx_to_frames_tfidf.py /
  ocr_augment_texts.py / run_pipeline_v2.py / previews/ — Phase Q 작업 시
  사용한 옛 script. 같이 보존.
- run_mdx03_pipeline.py (수정) — Phase Q 진입점 (no flag) + Phase Z 진입점
  (--phase-z2 flag) 동시 wrapper. Phase Z 만 사용 시 `python -m
  src.phase_z2_pipeline samples/mdx_batch/03.mdx <run_id>` 직접 호출.

비-scope :
- tests/matching/ (v4_full32_result.yaml 외 ~63MB) — V4 진화 history /
  reports / DECK / ATTACH. Phase Q audit axis 에서 검토.
- tests/pipeline/ (~15MB) — pipeline data. Phase Q audit 영역.
- templates/catalog/blocks.yaml — 옛 block catalog. Phase Q audit.
- templates/phase_z2/frames/ — 옛 frame partial 위치. Phase Q audit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

run_mdx03_pipeline.py

@@ -1,32 +1,36 @@
-"""MDX 03을 기존 파이프라인으로 Stage 1.7까지 돌린 뒤, 산출물을 저장.
+"""MDX 03을 기존 파이프라인 (Phase Q) 또는 Phase Z-2 MVP-1 로 실행.
 
-파이프라인 코드 그대로 사용:
-- Stage 0: mdx_normalizer
-- Stage 1A: kei_client.classify_content (Kei API)
-- Stage 1B: kei_client.refine_concepts + generate_structured_text
-- Stage 1.5a: space_allocator (컨테이너 계산 + font_hierarchy)
-- Stage 1.7: block_reference (블록 선택)
+기본 (no flag) : 기존 Phase Q 파이프라인 — async, Kei API 사용
+  - Stage 0: mdx_normalizer
+  - Stage 1A/1B: kei_client (분류 + 정제)
+  - Stage 1.5a: space_allocator
+  - Stage 1.7: block_reference
+  - 출력 : data/runs/{run_id}/final.html
 
-Stage 2(조립)는 여기서 하지 않음 — 산출물만 저장.
+`--phase-z2` flag : Phase Z-2 MVP-1 — sync, AI 미사용, 결정론적
+  - matched_zone only (V4 use_as_is) — 그 외 abort + error.json
+  - 출력 : data/runs/{run_id}/phase_z2/final.html
+  - 상세 : src/phase_z2_pipeline.py + docs/architecture/PHASE-Z-CATALOG-RUNTIME-DESIGN.md § 16
 """
+import argparse
 import asyncio
-import json
 import sys
 import time
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).parent))
 
-from src.pipeline import generate_slide
+
+DEFAULT_MDX = Path("samples/mdx/03. DX 시행을 위한 필수 요건 및 혁신 방안.mdx")
 
 
-async def main():
-    mdx_path = Path("samples/mdx/03. DX 시행을 위한 필수 요건 및 혁신 방안.mdx")
+async def run_phase_q(mdx_path: Path):
+    """기존 Phase Q 파이프라인 실행."""
+    from src.pipeline import generate_slide
+
     content = mdx_path.read_text(encoding="utf-8")
-
-    print(f"MDX 03: {mdx_path.name}")
-    print(f"내용 길이: {len(content)}자")
-    print()
+    print(f"[Phase Q] MDX: {mdx_path.name}")
+    print(f"  내용 길이: {len(content)}자\n")
 
     start = time.time()
     async for event in generate_slide(content, base_path=str(mdx_path.parent)):
@@ -39,10 +43,33 @@ async def main():
             print(f"\n완료! ({elapsed:.1f}초)")
             if isinstance(data, dict):
                 run_id = data.get("run_id", "")
-                print(f"run_id: {run_id}")
-                print(f"결과: data/runs/{run_id}/")
+                print(f"  run_id: {run_id}")
+                print(f"  결과: data/runs/{run_id}/")
         elif ev_type == "error":
-            print(f"  에러: {data}")
+            print(f"  에러: {data}", file=sys.stderr)
 
 
-asyncio.run(main())
+def run_phase_z2(mdx_path: Path, run_id: str = None):
+    """Phase Z-2 MVP-1 파이프라인 실행 (sync, AI 미사용)."""
+    from src.phase_z2_pipeline import run_phase_z2_mvp1
+    run_phase_z2_mvp1(mdx_path, run_id)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="MDX 03 pipeline runner.")
+    parser.add_argument("--phase-z2", action="store_true",
+                        help="Phase Z-2 MVP-1 (sync, AI 미사용, matched_zone only).")
+    parser.add_argument("--mdx", type=Path, default=DEFAULT_MDX,
+                        help=f"MDX 파일 경로 (default: {DEFAULT_MDX}).")
+    parser.add_argument("--run-id", type=str, default=None,
+                        help="run_id 오버라이드 (default: timestamp).")
+    args = parser.parse_args()
+
+    if args.phase_z2:
+        run_phase_z2(args.mdx, args.run_id)
+    else:
+        asyncio.run(run_phase_q(args.mdx))
+
+
+if __name__ == "__main__":
+    main()