C.E.L._slide_test/README.md

# C.E.L._slide_test

이 저장소는 `mdx` 문서를 읽고 슬라이드 HTML 결과물로 변환하는 **일반 파이프라인**을 관리하기 위한 작업 저장소다.

핵심 목표는 특정 샘플 3개를 예쁘게 만드는 것이 아니라, **어떤 MDX가 와도 내용 기반으로 적절한 슬라이드 구조를 고르고 결과를 검증하는 파이프라인**을 만드는 것이다.

## 핵심 원칙
- 원문 텍스트는 가능한 한 많이 유지한다. 큰 표, 큰 이미지, 긴 사례를 제외하면 텍스트의 약 85% 이상 보존을 목표로 한다.
- Step 1 ~ Step 3에서 임의 요약, 임의 제목 변경, 임의 순서 변경을 최소화한다.
- 넘치는 내용은 삭제보다 `popup`으로 이동한다.
- 모든 문서를 같은 골격에 넣지 않고, 콘텐츠 성격에 따라 `content family`를 먼저 분류한다.
- `content family`에 따라 zone, container, layout family, popup 전략을 다르게 잡는다.
- 목표는 특정 3개 run의 예외처리가 아니라, 임의의 MDX를 처리할 수 있는 일반 파이프라인이다.

## 저장소 역할
이 저장소는 네 가지 역할을 함께 가진다.

1. 입력과 산출물 저장소
- 원본 MDX 입력
- 중간 구조화 결과
- stage snapshot
- 최종 HTML 결과물
- 검증 기록

2. 실행 운영 저장소
- Step 1 ~ Step 6 이슈 정의
- stage 기반 실행 스크립트
- 자동 루프 스크립트
- Gitea 이슈 코멘트 자동 등록 스크립트

3. 반복 개선 저장소
- 실패 분류
- 수정 액션
- `retry-plan.json`
- rollback 이력
- 다음 반복에 반영할 개선 방향

4. 협업 저장소
- 위키에는 기준과 절차를 둔다.
- 이슈에는 단계별 실행 지시와 코멘트를 둔다.
- `docs/run-xxx`에는 실제 작업 기록과 결과를 둔다.

## 구조
- `docs/`
  - run별 입력, 중간 산출물, stage snapshot, 최종 결과물, 검증 결과
- `scripts/`
  - 실제 실행, 자동 루프, Gitea 이슈 코멘트 등록 스크립트
- `issues/`
  - Gitea 이슈 탭에 등록할 Step 1 ~ Step 6 본문 초안
- `results/`
  - run별 결과물을 빠르게 비교하기 위한 복사본
- `templates/`
  - 로컬에서 직접 참조하는 템플릿 자산과 catalog

## 위키, 이슈, docs의 역할 분리
### 위키
위키는 기준서다.
- 판단 기준
- 작업 절차
- 상세 파이프라인
- 실행 프롬프트
- content family와 layout family 원칙

### 이슈
이슈는 실행 단위다.
- Step 1 입력 확인
- Step 2 기준 해석
- Step 3 콘텐츠 구조화
- Step 4 실행 계획
- Step 5 실제 수행
- Step 6 검증 및 기록

### docs/run-xxx
`docs/run-xxx`는 실제 작업 기록과 산출물 저장소다.
- 원본 입력 MDX
- 중간 해석 파일
- 계획 파일
- stage context snapshot
- 생성 HTML
- measurement 결과
- validation 결과
- 이슈 코멘트 원문

## content family와 layout family
현재 파이프라인은 먼저 콘텐츠를 family로 분류한 뒤, family에 맞는 layout family를 고르는 방향으로 정리한다.

예시:
- `Type A`: 비교/정의/관계형
  - `run-001` 계열
  - 비교, 정의, 관계 설명이 동시에 필요한 경우
- `Type B`: 본문 중심형
  - 목표/효과형
  - 요건/프로세스/결과형
  - 오른쪽 독립 sidebar보다 body 중심 재배치를 우선하는 경우

중요한 점은, layout은 내용을 다시 쓰는 수단이 아니라 **원문 block을 더 잘 보이게 재배치하는 수단**이어야 한다는 점이다.

## popup 전략
popup은 본문 부족을 가리는 수단이 아니라, **상세를 숨기면서 본문 가시성을 유지하는 수단**이다.

원칙:
- 큰 표 전체
- 긴 사례 설명
- 긴 참고 근거
- 이미지 원문 설명 전체
같은 것은 popup으로 이동 가능하다.

대신 본문에는 반드시 남아야 한다.
- 섹션 제목
- 핵심 bullet 또는 핵심 문장
- popup을 여는 요약 진입점

## 기본 실행 흐름
1. 위키의 `Prompt`를 읽는다.
2. Step 이슈를 읽는다.
3. `docs/run-xxx/01-input`의 원본 MDX를 입력으로 사용한다.
4. Step 1 ~ Step 3에서 원문 block을 추출하고, content family와 popup 후보를 정리한다.
5. Step 4에서 family에 맞는 zone/container/layout을 고른다.
6. `scripts/run_from_artifacts.py`로 실제 stage 실행을 수행한다.
7. `scripts/auto_loop_runner.py`로 검증, retry-plan 생성, rollback, 반복 실행을 수행한다.
8. 결과를 `docs/run-xxx/05-execution`, `06-validation`에 저장한다.
9. Step 5, Step 6 결과를 Gitea 이슈 코멘트로 남긴다.

## Step 정의
### Step 1. 입력 확인
- 원문 block, 제목, 순서, 표/이미지/사례 위치를 식별한다.
- 이 단계의 최우선은 요약이 아니라 원문 구조 보존이다.

### Step 2. 기준 해석
- 핵심 목적, 의미 보존 기준, 실패 패턴, popup 후보를 정리한다.
- 이 단계의 목적은 재서술이 아니라 보존 기준과 grouping 기준을 세우는 것이다.

### Step 3. 콘텐츠 구조화
- 원문 block을 `가시 본문 / popup / 결론`으로 나눈다.
- content family를 확정한다.
- 원문 순서를 함부로 바꾸지 않는다.

### Step 4. 실행 계획
- family에 맞는 zone/container/layout family를 결정한다.
- stage별 입력, 출력, 검증 지점을 남긴다.

### Step 5. 실제 수행
- 실제 HTML 생성, 렌더링, 측정을 수행한다.
- stage snapshot과 산출물을 저장한다.

### Step 6. 검증 및 기록
- overflow, 핵심 메시지 가시성, 원문 보존율, popup 이동 적절성, 빈 block 여부를 검증한다.
- 실패 시 retry-plan과 rollback 기준을 만든다.

## stage snapshot
`run_from_artifacts.py`는 stage별 중간 상태를 저장한다.

예시:
- `stage_0_context.json`
- `stage_1a_context.json`
- `stage_1b_context.json`
- `stage_1_5a_context.json`
- `stage_1_7_context.json`
- `stage_1_5b_context.json`
- `stage_2_context.json`
- `stage_2_verification.json`
- `stage_3_context.json`
- `stage_4_context.json`
- `final_context.json`

이 구조가 중요한 이유는, 실패가 나면 최종 HTML만 다시 고치는 것이 아니라 어느 stage로 돌아가야 하는지 추적할 수 있기 때문이다.

## 자동 루프
핵심 루프는 `실행 -> 검증 -> retry-plan -> rollback -> 재실행 -> 재검증`이다.

주요 스크립트:
- `scripts/raw_bootstrap.py`
  - raw MDX 기준 Step 1 ~ Step 3와 stage 1a/1b 초기 산출물 정리
- `scripts/run_from_artifacts.py`
  - stage 실행, 템플릿 참조, 결과물 생성
- `scripts/auto_loop_runner.py`
  - 검증, retry-plan 생성, rollback, 재실행
- `scripts/gitea_issue_sync.py`
  - Gitea 이슈/코멘트 API 연동

## strict 검증 기준
합격 기준은 단순히 HTML 생성 여부가 아니다.
- slide/body/sidebar/footer overflow 없음
- 핵심 메시지 가시 텍스트 존재
- family에 필요한 핵심 block 존재
- popup 이동 후에도 본문 summary가 남아 있음
- 빈 block, placeholder, 잘린 row 없음
- 원문 보존율과 시선 흐름이 기준을 넘음

## 새 run을 시작하는 방법
1. `docs/run-template/`를 복사해 새 run 폴더를 만든다.
2. 원본 MDX를 `01-input/`에 넣는다.
3. 위키의 `Prompt`를 기준으로 실행한다.
4. `scripts/raw_bootstrap.py`와 `scripts/auto_loop_runner.py`를 실행한다.
5. 결과와 retry-plan, history를 확인한다.
6. Gitea 이슈 코멘트와 results 폴더를 확인한다.

## 현재 저장소의 의미
현재 저장소는 run-001, run-002, run-003을 통해 family 분기와 raw 보존, popup 전략, stage 기반 retry를 테스트하고 있다.

하지만 이 샘플들은 목표가 아니라 검증용 데이터다.
목표는 **임의의 MDX를 넣었을 때도 같은 절차로 content family를 고르고, 원문 85% 보존과 popup 전략을 통해 슬라이드로 만드는 일반 파이프라인**이다.