C.E.L_Slide_test2/docs/architecture/PROJECT-INTENT-AND-GOVERNANCE.md

프로젝트의 목적과 거버넌스

이 문서는 왜 이 프로젝트를 하는지, 무엇을 위해 이슈와 audit 을 도는지, 그리고 그 구조가 어떻게 짜여있는지 기록한다. 매번 처음부터 설명하지 않기 위함.

작성: 2026-05-20.

---

1. Destination (도착점)

Phase Z 가 다음 두 가지까지 작동하면 프로젝트 목표 달성:

1. 22-step pipeline end-to-end 작동
   • 참조: PHASE-Z-PIPELINE-OVERVIEW.md
   • 현재 status: PHASE-Z-PIPELINE-STATUS-BOARD.md
2. AI 가 zone fit 평가 → 안 맞는 frame reject → zone 에 맞는 frame 생성
   • frame 이 zone 안에 들어가지 않으면 AI 가 reject
   • reject 후 zone 에 맞춰 frame 을 생성하는 것까지가 destination

이 두 가지가 작동하면 끝. 그 이상은 별도 결정.

---

2. Q~Y 검토 = 이미 끝났음 (과거형)

Phase Z 구현 갭을 메우기 위해 Phase Q~Y 의 코드/기능을 이미 다 검토했고, 참고할 만한 것들을 22-step 에 매칭해서 이슈로 다 정리해놓은 상태.

• Q~Y 새로 다시 보지 않음 — 작업은 끝남
• 결과물 = INSIGHT-MAP 문서 + 28 개 초기 IMP 이슈 (#1~#28)
• 회귀 금지선 4 항목 (Q/R'/T 의 폐기된 path 로 돌아가지 않음) 도 PHASE-Q-INSIGHT-TO-22STEP-MAP.md §0 에 같이 박혀있음

이제 남은 일 = 정리된 이슈를 orchestrator 로 처리해서 Phase Z 에 반영하는 것.

---

3. 그 검토 결과 = INSIGHT-MAP 문서

문서: PHASE-Q-INSIGHT-TO-22STEP-MAP.md

Q~Y 검토 결과를 22-step 의 어느 step 에 어떤 부품을 가져올지 매핑해서 정리한 catalog. 섹션 구성:

• §0: 목적 + 회귀 금지 4 항목 + Archive marker inventory (9 개)
• §1: SoT read result + 22 Step status snapshot
• §2: Salvage chained + new-make backend axes
• §3: Reference / carve-out
• §4: audit §1 lens column 정정
• §5: Module duplication cleanup

각 § cell 이 IMP 이슈로 1-to-1 분해됨.

---

4. IMP 이슈 = INSIGHT-MAP § cell 의 execution unit

초기 28 개 (2026-05-12 한 번에 생성, #1~#28):

INSIGHT-MAP §	이슈
§2 (Salvage chained + new-make backend)	#1~#11 (IMP-0111: A-1A-6, B-1~B-4, D-1, D-2)
§3 (Reference / carve-out)	#12~#20 (IMP-12~20: A-3/A-4, B-2, AI fallback, frame contract 등)
§4 (audit §1 lens column 정정)	#21~#25 (IMP-21~25: G2, I6, J5, K6, L5)
§5 (Module duplication cleanup)	#26~#28 (IMP-26~28: J3, K5, L4)

모든 IMP 이슈 본문에 표준 anchor:

**관련 step**: Phase Z 22-step 좌표
**source**: INSIGHT-MAP §X (Q~Y 부품 출처)
**priority**: ↑ high / medium / ↓ low
**scope**: 구체 작업
**guardrails**: 깨면 안 되는 contract

이후 추가된 이슈 (모두 source 명시):

이슈	source	의미
#38~#41 (IMP-29~32)	IMP-05 §5 defer + Codex 분석	V4 fallback 후 frontend bridge / AI adaptation 등
#42 (IMP-04b)	IMP-04 milestone close 후 잔여	Catalog 32 frames 확장
#43, #44	MDX 03/04/05 작업 중 발견	프론트 작업에서 발견된 새 axis
#45~#49	#15 (Step 14 visual_check) decomposition	parent → 5 execution children
#50	governance audit	초반 28 다수 close 후 INTEGRATION-AUDIT-01
#51~#54	#50 audit 의 발견 (F-1~F-5)	follow-up 분리 처리
#55	#20 closed 후 runtime defer	doc-axis closed, runtime 별도

→ 추가 이슈도 모두 (관련 step, source, priority) 좌표로 anchor.

---

5. orchestrator 의 역할

이슈 처리의 disciplined executor.

파일: orchestrator.py (현재 line 수: ~1500) 테스트: tests/orchestrator_unit/ (현재 94 케이스)

6 stage workflow:

1. problem-review — 문제 검토
2. simulation-plan — 시뮬 기반 계획 수립 (IMPLEMENTATION_UNITS YAML 강제)
3. code-edit — 코드 수정 / 이슈 분기
4. test-verify — 테스트 및 검증
5. commit-push — 커밋 및 푸쉬
6. final-close — 최종 확인 / close

원칙:

• Claude (executor) + Codex (verifier) 양쪽 합의 + evidence required
• 단일 LLM 의견 X
• 매 stage 마다 dual-write (local draft + Gitea comment)
• exit report = stage 완료의 binding contract

audit-only mode (P4/P4a):

• 제목에 [INTEGRATION-AUDIT-*]/[AUDIT-ONLY] 또는 --audit-only CLI flag
• Stage 3 에서 src/, templates/, tests/ 변경 자동 reject (deterministic git diff guard)
• Stage 5 commit 범위 = docs/architecture/INTEGRATION-AUDIT-*.md + BACKLOG.md 만 허용
• audit 이슈는 fix 안 함 → follow-up 이슈로 분리

---

6. Audit cycle (meta-governance)

이슈 진행으로 인한 누적 drift / 충돌 / 하드코딩 / 매핑 누락을 주기적으로 검증.

audit 자체는 코드 안 만짐. 발견 사항은 별도 이슈로 분리해서 일반 workflow 로 처리.

현재까지:

• #50 INTEGRATION-AUDIT-01 (closed 2026-05-19)
  • 산출: INTEGRATION-AUDIT-01-REPORT.md + INTEGRATION-AUDIT-01-MATRIX.md
  • 발견 F-1F-5 → #51#54 로 분리 (모두 closed)

다음 audit 시점 trigger:

• 닫힌 IMP 이슈가 일정 수 누적될 때 (5+ 연속)
• debug.json schema / layout / frame contract / router / visual_check_passed 의미가 바뀔 때
• 새 parent axis 진입 직전 (예: #19 → #20 → ...)
• 큰 feature 축 (#42 catalog 확장 / #38~#41 frontend bridge) 완료 후

---

7. 도착점 도달 기준

다음이 모두 작동해야 destination 도달:

• 22-step pipeline end-to-end (Step 0~22 모두 contract 준수, 회귀 0)
• AI 가 frame 을 zone fit 기준으로 평가 → 안 맞으면 reject
• reject 후 AI 가 zone 에 맞춰 frame 생성
• 하드코딩 0 (sample-specific 코드 없음 — anti-hardcoding mechanical check 통과)
• 모든 IMP 이슈 backlog 의 closed / documented (deferred) / pending 분류가 PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md 와 code reality 일치

---

8. 자주 헷갈리는 것들 (anti-patterns — 하지 말 것)

잘못된 framing	옳은 framing
"Phase Q~Y heritage 를 보존한다"	Q~Y 는 부품 창고. 갭에 필요한 것만 선택적 참조
"MDX 03 잘 만들면 끝"	재사용 가능한 pipeline contract 가 목표. 특정 샘플 최적화 X
"audit 가 발견하면 그 자리에서 고친다"	follow-up 이슈로 분리. audit 자체는 코드 안 만짐
"Claude 가 좋다고 하면 OK"	Claude + Codex 합의 + evidence 필수
"이슈 본문은 참고일뿐"	본문의 (관련 step, source, scope, guardrails) 가 binding anchor
"Phase R / R' / Q 의 path 로 돌아가도 됨"	회귀 금지선 4 항목 (INSIGHT-MAP §0) 절대 위반 X
"destination 외 추가 기능도 욕심내자"	22-step + AI frame generation 까지가 목표. 그 이상은 별도 결정

---

9. 핵심 참조 문서 한 곳에

문서	역할
PROJECT-INTENT-AND-GOVERNANCE.md	이 문서 — 왜/무엇을
PHASE-Q-INSIGHT-TO-22STEP-MAP.md	INSIGHT-MAP — Q~Y → Z 매핑 catalog
PHASE-Z-PIPELINE-OVERVIEW.md	22-step pipeline 정의
PHASE-Z-PIPELINE-STATUS-BOARD.md	22-step 현재 status
PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md	IMP 이슈 backlog (closed/documented/pending)
PHASE-Z-ROADMAP.md	진행 로드맵
INTEGRATION-AUDIT-01-REPORT.md	첫 audit 사이클 결과
../../orchestrator.py	disciplined executor (Claude + Codex 합의 workflow)
../../CLAUDE.md	AI 가 코드 작업할 때 따를 규칙

---

10. 한 줄 요약

Phase Z 가 "22-step pipeline + AI zone-fit frame generation" 까지 작동하는 것이 destination. Z 구현의 갭은 Phase Q~Y 를 부품 창고로 보고 선택적으로 참조해서 메움. INSIGHT-MAP 이 그 catalog, IMP 이슈가 execution unit. orchestrator 가 Claude + Codex 합의 + evidence 로 disciplined 하게 처리. INTEGRATION-AUDIT 가 주기적으로 누적 정합성 검증, 발견은 follow-up 이슈로 분리. 도착점은 22-step + AI frame generation 까지이고 그 이상은 별도 결정.