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

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

design 요약

목적: 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).

차트 버전 감지 방식: repo 디렉토리 스캔, git diff, index.yaml, ArtifactHub API, GitHub Release, cron.
dip-catalog 흐름: 최신 chart pull/untar → manifests/helm/// 디렉토리 생성(기존 유지).
이전 버전 파일 복사: 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 포함하여 부분 실패 기록.

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, 우선순위 규칙.

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

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).

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).