# 업데이트 카탈로그 문서 메모리 (요약)

이 문서는 docs/design 및 docs/implementation 내용의 요점을 요약 저장한다.
변경 시 이 파일을 업데이트한다.

## design 요약

### 00-architecture-overview
- **목적**: Helm chart 신규 버전을 카탈로그(신규 배포용)에 추가하고, 업그레이드 주의사항을 CUSTOM-README.md에 자동 문서화.
- **카탈로그 역할**: 운영 클러스터 직접 변경 아님. 신규 배포를 위한 차트 보관소.
- **파이프라인**: chart_version_detector → helm_diff → breaking_change_check → generate_upgrade_doc(항상) → update_docs_file(CUSTOM-README.md) → create_pr.
- **검토 정책**: breaking=true → needs-review 레이블(담당자 판단), breaking=false → auto-update 레이블. deploy_validate는 Phase 2.
- 구성요소 책임 분리 및 스택(helm3, Python diff/rule, LLM, Git PR, OpenClaw/Nanobot).

### 01-helm-diff-engine
- 차트 버전 감지 방식: repo 디렉토리 스캔, git diff, index.yaml, ArtifactHub API, GitHub Release, cron.
- dip-catalog 흐름: 최신 chart pull/untar → manifests/helm/<chart>/<version>/ 디렉토리 생성(기존 유지).
- 이전 버전 파일 복사: custom-values.yaml(그대로), CUSTOM-README.md(그대로), BUILD-README.md(버전 번호 치환).
- generate_upgrade_doc → CUSTOM-README.md에 업그레이드 주의사항 섹션 추가 (항상 실행).
- helm_diff 처리: values, template, CRD, dependencies 비교 → Structured Diff JSON.
- values diff: flat key 비교(added/removed/changed/type_changed), rename은 removed+added.
- template diff: 리소스 단위(kind+name) 비교, generateName 처리.
- CRD diff: schema/required/version/webhook 변화 감지.
- errors 포함하여 부분 실패 기록.

### 02-breaking-change-rules
- **Breaking 정의**: custom-values.yaml을 수정해야 하는 상황.
- values_key_removed: custom-values.yaml에 해당 key가 있을 때만 breaking. 없으면 warning.
- values_type_changed: 동일 기준.
- service_port_changed, resource_removed: 카탈로그 맥락에서 warning (custom-values.yaml 수정 불필요).
- dependency_major_changed: custom-values.yaml에 해당 subchart prefix key 있으면 breaking, 없으면 warning.
- CRD 변경(field 삭제, required 추가, storage version 변경): breaking.
- deprecated API는 warning.
- severity: critical/high/medium/warning, 우선순위 규칙.

### 03-llm-summarizer
- **실행 조건**: generate_upgrade_doc 항상 실행. breaking=true → LLM 상세 가이드, breaking=false → 템플릿 요약.
- LLM 입력: diff + breaking 결과 + docs_context(CUSTOM-README.md).
- 규칙: 입력 JSON 외 내용 금지, 정해진 Markdown 포맷.
- 토큰 관리: 필터링/요약/청크.
- 출력 검증(포맷/허위 서술 금지).
- **대상 파일**: CUSTOM-README.md (배포 관련 문서). BUILD-README.md는 차트 메타 정보 유지.

### 04-skill-interface
- Skill 계약: helm_diff, breaking_change_check, generate_upgrade_doc, update_docs_file, create_pr.
- deploy_validate: Phase 2 예정 (현재 인터페이스만 정의, 구현 안 됨).
- update_docs_file: CUSTOM-README.md에 업그레이드 주의사항 추가. docs_file 경로에 to_version 포함.
- 워크플로: helm_diff → breaking_check → generate_doc(항상) → update_docs(CUSTOM-README.md, to_version 경로) → create_pr.
- 공통 에러 스키마, idempotency, secret 전달 방식.
- 인터페이스 버전 관리(1.0).

### 05-on-cluster-agent
- OpenClaw/Nanobot로 K8s 상시 에이전트 오케스트레이션.
- 보안 고려: RBAC 최소권한, NetworkPolicy, skill allowlist, prompt injection 방지.
- 운영 정책: breaking=true → needs-review 레이블(담당자 판단). breaking=false → auto-update.
- skills allowlist: helm_diff, breaking_change_check, generate_upgrade_doc, update_docs_file, create_pr (deploy_validate는 Phase 2).

## implementation 요약

### 01-skills
- Step 1 Skills 구현 태스크(T1~T10) + dip-catalog 최신 차트 pull/untar 반영.
- 핵심: helm_diff, breaking_check, generate_upgrade_doc(항상 실행), 인터페이스 노출.
- 문서 갱신은 CUSTOM-README.md 대상.
- 안정성: 에러 처리, version detector, docs updater, PR bot.
- 우선순위 로드맵 및 완료 기준.

### 02-agent
- Step 2~4: 프레임워크 POC(OpenClaw vs Nanobot), 워크플로 정의, 보안 정책 후 운영.
- 워크플로: generate_upgrade_doc 항상 실행, deploy_validate는 Phase 2.
- 결정사항은 decisions/에 기록.