From 47f072ee052b5aa9772c1a969338e3677fd9fd70 Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Wed, 20 May 2026 00:56:52 +0900 Subject: [PATCH] docs: PROJECT-INTENT-AND-GOVERNANCE master doc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 프로젝트의 왜 / 무엇을 위해 / 어떻게 라는 질문에 대한 master 답. 이 문서가 있으면 매번 처음부터 framing 설명할 필요 없음. 구조: 1. Destination — Phase Z 22-step + AI zone-fit frame generation 2. Q~Y 검토 = 이미 완료 (과거형). 결과 = INSIGHT-MAP + 28 초기 이슈. 3. INSIGHT-MAP catalog 구조 (§0~§5) 4. IMP 이슈 좌표 체계 (관련 step + source + priority + scope + guardrails) 5. orchestrator 의 disciplined executor 역할 (Claude + Codex 합의) 6. Audit cycle (meta-governance) — 발견은 follow-up 이슈로 분리 7. 도착점 도달 기준 5 항목 8. 자주 헷갈리는 anti-patterns (heritage 보존 X, MDX 최적화 X 등) 9. 핵심 참조 문서 인덱스 10. 한 줄 요약 Co-Authored-By: Claude Opus 4.7 (1M context) --- .../PROJECT-INTENT-AND-GOVERNANCE.md | 181 ++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/architecture/PROJECT-INTENT-AND-GOVERNANCE.md diff --git a/docs/architecture/PROJECT-INTENT-AND-GOVERNANCE.md b/docs/architecture/PROJECT-INTENT-AND-GOVERNANCE.md new file mode 100644 index 0000000..87bf584 --- /dev/null +++ b/docs/architecture/PROJECT-INTENT-AND-GOVERNANCE.md @@ -0,0 +1,181 @@ +# 프로젝트의 목적과 거버넌스 + +> 이 문서는 **왜** 이 프로젝트를 하는지, **무엇을 위해** 이슈와 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 까지가 목표. 그 이상은 별도 결정 | + +--- + +## 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 까지이고 그 이상은 별도 결정.**