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`](PHASE-Z-PIPELINE-OVERVIEW.md)
   - 현재 status: [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](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`](PHASE-Q-INSIGHT-TO-22STEP-MAP.md) 에 같이 박혀있음

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

---

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

**문서**: [`PHASE-Q-INSIGHT-TO-22STEP-MAP.md`](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-01~11: A-1~A-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`](../../orchestrator.py) (현재 line 수: ~1500)
**테스트**: [`tests/orchestrator_unit/`](../../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-REPORT.md) + [`INTEGRATION-AUDIT-01-MATRIX.md`](INTEGRATION-AUDIT-01-MATRIX.md)
  - 발견 F-1~F-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`](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 까지가 목표. 그 이상은 별도 결정 |
| "문서에 박힌 dormant 항목은 자동 실행 안 됨" | L3 registry [`DORMANT-TRIGGERS.yaml`](DORMANT-TRIGGERS.yaml) + `scripts/check_dormant_triggers.py` 가 orchestrator Stage 4→5 transition 에서 informational alert 로 발화 (closed 이슈 #16/#17/#18/#19/#20 의 trigger-on-X contract) |

---

## 9. 핵심 참조 문서 한 곳에

| 문서 | 역할 |
|---|---|
| [`PROJECT-INTENT-AND-GOVERNANCE.md`](PROJECT-INTENT-AND-GOVERNANCE.md) | **이 문서** — 왜/무엇을 |
| [`PHASE-Q-INSIGHT-TO-22STEP-MAP.md`](PHASE-Q-INSIGHT-TO-22STEP-MAP.md) | INSIGHT-MAP — Q~Y → Z 매핑 catalog |
| [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md) | 22-step pipeline 정의 |
| [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) | 22-step 현재 status |
| [`PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md`](PHASE-Z-IMPLEMENTATION-ISSUE-BACKLOG.md) | IMP 이슈 backlog (closed/documented/pending) |
| [`PHASE-Z-ROADMAP.md`](PHASE-Z-ROADMAP.md) | 진행 로드맵 |
| [`INTEGRATION-AUDIT-01-REPORT.md`](INTEGRATION-AUDIT-01-REPORT.md) | 첫 audit 사이클 결과 |
| [`../../orchestrator.py`](../../orchestrator.py) | disciplined executor (Claude + Codex 합의 workflow) |
| [`../../CLAUDE.md`](../../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 까지이고 그 이상은 별도 결정.**