Document end-to-end mdx to slide workflow

README.md

@@ -1,36 +1,276 @@
 # C.E.L._slide_test
 
-이 저장소는 슬라이드 생성 작업을 단계별로 해석, 계획, 실행, 검증하고 그 결과를 반복적으로 개선하기 위한 작업 공간이다.
+이 저장소는 `mdx` 문서를 읽고 슬라이드 HTML 결과물로 변환하는 전체 실행 프로세스를 관리하기 위한 작업 저장소다.
 
-## 구성
+핵심 목표는 다음과 같다.
-- `docs/`: 방향성 문서, Stage 1 문서, run 기록, 입력 원문, 실행 결과
+- 누구라도 같은 저장소 구조와 위키 기준만으로 `mdx -> 슬라이드` 변환을 수행할 수 있어야 한다.
-- `scripts/`: 후반부 실행과 실험, Gitea 이슈 등록을 위한 스크립트
+- 실행 과정은 `위키 -> 이슈 -> docs/run-xxx -> 결과물` 순서로 추적 가능해야 한다.
-- `issues/`: Gitea 이슈 탭에 등록할 step별 이슈 본문 초안
+- 결과는 한 번 만들고 끝나는 것이 아니라, `검증 -> revise -> 재실행` 루프로 개선 가능해야 한다.
+- Codex와 Gitea를 함께 사용해 작업 기준, 실행 기록, 산출물, 검증 결과를 모두 남긴다.
 
-## 현재 포함된 항목
+## 저장소 역할
-- 단계별 운영 문서
-- run-001 입력 원문, 해석/구조화/계획/검증 기록
-- 실행 결과와 측정 결과
-- 반복 실행을 위한 템플릿
 
-## 운영 원칙
+이 저장소는 단순 코드 저장소가 아니다. 아래 네 가지 역할을 함께 가진다.
-- 원본 입력 파일은 각 run의 `01-input/` 폴더 안에 함께 둔다.
-- 위키는 기준과 절차를 관리한다.
-- 이슈는 step별 실행 지시와 실행 결과 코멘트를 관리한다.
-- `docs/run-xxx/`는 실제 산출물과 중간 결과를 저장한다.
 
-## 현재 run 예시
+1. 입력과 산출물 저장소
-- 입력 원문: `docs/run-001/01-input/01. 건설산업 DX의 올바른 이해(0127).mdx`
+- `mdx` 원문 입력
-- 입력 검토: `docs/run-001/01-input/input-review.md`
+- 중간 구조화 결과
-- 실행 계획: `docs/run-001/04-plan/execution-plan.md`
+- 최종 HTML 결과물
-- 최종 결과: `docs/run-001/05-execution/final.html`
+- 검증 기록
-- 검증 결과: `docs/run-001/06-validation/validation-result.md`
 
-## Gitea 이슈 자동 등록
+2. 실행 운영 저장소
-- `scripts/gitea_issue_sync.py`는 Gitea REST API로 이슈 생성, 이슈 본문 수정, 코멘트 등록을 수행한다.
+- Step 1 ~ Step 6 이슈 정의
-- 필요 환경변수:
+- 자동 실행 루프 스크립트
+- Gitea 이슈 코멘트 자동 등록 스크립트
+
+3. 반복 개선 저장소
+- 실패 분류
+- 수정 액션
+- 다음 반복에 반영할 개선 방향
+
+4. 협업 저장소
+- 위키에는 기준과 절차를 둔다.
+- 이슈에는 단계별 실행 지시와 코멘트를 둔다.
+- `docs/run-xxx`에는 실제 작업 기록과 결과를 둔다.
+
+## 전체 구조
+
+- `docs/`
+  - run별 입력, 중간 산출물, 최종 결과물, 검증 결과
+- `scripts/`
+  - 실제 실행, 자동 루프, Gitea 이슈 코멘트 등록 스크립트
+- `issues/`
+  - Gitea 이슈 탭에 등록할 Step 1 ~ Step 6 본문 초안
+
+주요 경로:
+- `docs/run-001/01-input/`
+- `docs/run-001/02-kei-interpretation/`
+- `docs/run-001/03-structure/`
+- `docs/run-001/04-plan/`
+- `docs/run-001/05-execution/`
+- `docs/run-001/06-validation/`
+
+## 위키, 이슈, docs의 역할 분리
+
+### 위키
+위키는 기준서다.
+
+위키에서 관리하는 내용:
+- 사고방식과 운영 원칙
+- 상위 작업 절차
+- 상세 파이프라인
+- 실행 프롬프트
+
+즉, 위키는 `어떻게 할 것인가`를 정의한다.
+
+### 이슈
+이슈는 실행 단위다.
+
+이슈에서 관리하는 내용:
+- Step 1 입력 확인
+- Step 2 기준 해석
+- Step 3 콘텐츠 구조화
+- Step 4 실행 계획
+- Step 5 실제 수행
+- Step 6 검증 및 기록
+
+즉, 이슈는 `이번 step에서 무엇을 할 것인가`와 `실행 후 무엇이 나왔는가`를 관리한다.
+
+### docs/run-xxx
+`docs/run-xxx`는 실제 작업 기록과 산출물 저장소다.
+
+여기에는 다음이 들어간다.
+- 원본 입력 `mdx`
+- 중간 해석 파일
+- 계획 파일
+- 생성 HTML
+- measurement 결과
+- validation 결과
+- 이슈 코멘트 원문
+
+즉, `docs/run-xxx`는 `실제로 무엇이 만들어졌는가`를 저장한다.
+
+## 실행 대상 입력
+
+각 run은 반드시 원본 입력 파일을 `01-input`에 함께 둔다.
+
+예시:
+- `docs/run-001/01-input/01. 건설산업 DX의 올바른 이해(0127).mdx`
+
+이 원칙이 중요한 이유:
+- run만 보면 입력부터 결과까지 모두 추적 가능해야 한다.
+- 외부 경로를 다시 찾지 않아도 재실행이 가능해야 한다.
+
+## 기본 실행 흐름
+
+전체 흐름은 다음과 같다.
+
+1. 위키의 `Prompt`를 읽는다.
+2. Step 이슈를 읽는다.
+3. `docs/run-xxx/01-input`의 원본 `mdx`를 입력으로 사용한다.
+4. Step 1 ~ Step 4 결과를 기준으로 실행 준비를 마친다.
+5. `scripts/run_from_artifacts.py`로 실제 후반부 실행을 수행한다.
+6. `scripts/auto_loop_runner.py`로 검증, 자동 보정, 반복 실행을 수행한다.
+7. 결과를 `docs/run-xxx/05-execution`, `06-validation`에 저장한다.
+8. Step 5, Step 6 결과를 Gitea 이슈 코멘트로 남긴다.
+
+## Step 정의
+
+### Step 1. 입력 확인
+- 입력 문서를 식별한다.
+- 문서 제목, 목적, 범위, 제약을 정리한다.
+- 결과는 `01-input/input-review.md`에 남긴다.
+
+### Step 2. 기준 해석
+- 입력을 슬라이드 목적에 맞게 해석한다.
+- 핵심 메시지, 보존 기준, 실패 패턴을 정리한다.
+- 결과는 `02-kei-interpretation/`에 남긴다.
+
+### Step 3. 콘텐츠 구조화
+- 중심 메시지와 보조 정보를 구분한다.
+- 본문, 사이드, 결론의 배치 가정을 세운다.
+- 결과는 `03-structure/`에 남긴다.
+
+### Step 4. 실행 계획
+- 실제 stage 실행 계획을 세운다.
+- Stage 1A/1B 산출물, 실행 입력, 검증 포인트를 정리한다.
+- 결과는 `04-plan/`에 남긴다.
+
+### Step 5. 실제 수행
+- 실제 HTML 생성과 렌더링, 측정을 수행한다.
+- 결과는 `05-execution/`에 남긴다.
+
+### Step 6. 검증 및 기록
+- 핵심 메시지 가시성, 비교 정보, 이미지 참조, overflow 여부를 검증한다.
+- 결과는 `06-validation/`에 남긴다.
+
+## 자동 루프
+
+이 저장소의 핵심은 한 번 생성하고 끝나는 것이 아니라, 실패 시 자동으로 보정하고 다시 실행하는 루프다.
+
+현재 자동 루프 스크립트:
+- `scripts/auto_loop_runner.py`
+
+이 스크립트가 하는 일:
+- `run_from_artifacts.py` 실행
+- 결과 HTML 및 measurement 로드
+- strict 검증 수행
+- 실패 시 자동 보정 시도
+- 필요하면 더 짧고 강한 컴팩트 레이아웃으로 재구성
+- validation 결과 기록
+- Step 5 / Step 6 코멘트 파일 작성
+- Gitea 이슈 코멘트 자동 등록
+
+즉, 이 스크립트는 `실행 -> 검증 -> revise -> 자동 보정 -> 재검증`의 핵심 루프를 담당한다.
+
+## strict 검증 기준
+
+현재 합격 기준은 단순히 `HTML이 만들어졌는가`가 아니다.
+
+아래가 모두 충족되어야 `pass`다.
+- `slide overflow = false`
+- `body overflow = false`
+- `sidebar overflow = false`
+- `footer overflow = false`
+- 핵심 메시지 가시 텍스트 존재
+- 이미지/도해 참조 문구 존재
+- 비교 핵심 4축(범위, 프로세스, 성과품, 확장성) 존재
+
+즉, `측정 통과 + 가시 정보 보존`이 둘 다 만족되어야 한다.
+
+## 주요 스크립트
+
+### `scripts/run_from_artifacts.py`
+역할:
+- Step 4에서 만들어진 입력 산출물을 사용해 실제 후반부 생성 실행
+- `generated_html.json`, `final.html`, `measurement.json`, `context.json` 저장
+
+### `scripts/auto_loop_runner.py`
+역할:
+- 실행 결과를 다시 읽음
+- strict 검증 수행
+- 필요 시 자동 보정
+- validation 기록 저장
+- Step 5 / Step 6 코멘트 자동 생성
+- Gitea 이슈 코멘트 자동 등록
+
+### `scripts/gitea_issue_sync.py`
+역할:
+- Gitea REST API를 통해 이슈 생성, 본문 수정, 코멘트 등록 수행
+
+## Gitea 이슈 운영 방식
+
+이슈는 Step 단위로 관리한다.
+
+예시:
+- `Step-1-Input-Review`
+- `Step-2-Interpretation`
+- `Step-3-Content-Structuring`
+- `Step-4-Execution-Planning`
+- `Step-5-Execution`
+- `Step-6-Validation-and-Recording`
+
+실행 결과는 각 step 이슈의 코멘트로 누적된다.
+
+즉:
+- 이슈 본문 = step 정의와 KPI
+- 이슈 코멘트 = 실제 실행 결과
+
+## Gitea 자동 코멘트 등록
+
+필요 환경변수:
 - `GITEA_URL`
 - `GITEA_TOKEN`
-- 예시:
+
-  - `python scripts/gitea_issue_sync.py create-issue --repo Kyeongmin/C.E.L._slide_test --title "Step 1 / 입력 확인" --body-file issues/Step-1-Input-Review.md`
+예시:
-  - `python scripts/gitea_issue_sync.py create-comment --repo Kyeongmin/C.E.L._slide_test --issue-number 2 --body-file docs/run-001/comments/step-1.md`
+```powershell
+$env:GITEA_URL="https://gitea.hmac.kr"
+$env:GITEA_TOKEN="발급받은_개인_액세스_토큰"
+```
+
+주의:
+- 토큰은 채팅이나 문서에 그대로 남기지 않는다.
+- 노출된 토큰은 즉시 폐기하고 새로 발급한다.
+
+## 새 run을 시작하는 방법
+
+1. `docs/run-template/`를 복사해 새 run 폴더를 만든다.
+2. 원본 `mdx`를 `01-input/`에 넣는다.
+3. 필요한 Step 1 ~ Step 4 산출물을 채운다.
+4. 위키의 `Prompt`를 기준으로 실행한다.
+5. `scripts/auto_loop_runner.py`를 실행한다.
+6. 결과를 확인한다.
+
+## 사람이 실제로 하는 최소 판단
+
+이 시스템이 자동화된 뒤에도 사람은 최소한 아래를 확인하는 것이 좋다.
+- 최종 `final.html`이 실제 사용 목적에 맞는가
+- 너무 과하게 압축되지는 않았는가
+- 표현 톤이나 정보 강조가 의도와 맞는가
+
+즉, 시스템의 `pass`는 운영 기준 합격이고, 최종 실사용 품질은 사람 검토로 한 번 더 확인하면 가장 좋다.
+
+## 결과물 확인 위치
+
+주요 결과물:
+- 최종 HTML: `docs/run-001/05-execution/final.html`
+- 생성 HTML JSON: `docs/run-001/05-execution/generated_html.json`
+- 측정 결과: `docs/run-001/05-execution/measurement.json`
+- 검증 결과: `docs/run-001/06-validation/validation-result.md`
+
+## 현재 상태
+
+현재 `run-001`은 strict 기준으로 `pass`를 달성했다.
+
+즉, 이 저장소는 이제 다음을 실제로 수행할 수 있다.
+- `mdx` 입력을 저장소 안에 둔다.
+- Codex가 위키와 이슈를 읽는다.
+- 단계별 실행을 수행한다.
+- 산출물을 저장한다.
+- strict 검증을 수행한다.
+- 실패 시 자동 보정 후 재실행한다.
+- Gitea 이슈 코멘트로 결과를 남긴다.
+
+## 한 줄 요약
+
+이 저장소는 `Codex + Gitea + docs/run-xxx 구조`를 이용해 누구라도 `mdx -> 슬라이드` 변환을 반복 실행하고 검증하고 개선할 수 있도록 만든 운영 저장소다.