업스트림 수정 루프 — coui 를 고치고 앱 핀을 옮기기

앱에서 본 문제의 원인이 coui 에 있을 때의 흐름이다. 전달 원칙("coui PR 이 먼저 머지되고, 앱은 그다음 핀을 옮긴다")은 coui-composition-and-extension 스킬과 같다. 이 문서는 그 사이의 실제 단계와 함정을 다룬다.

• coui 를 고칠지, 앱에서 감쌀지(래퍼·전역 테마) 사용자에게 확인한다. "coui 로 해야 한다"는 "coui 컴포넌트를 써라"일 수도 있다.
• 고치기로 했으면 coui 저장소의 이슈를 먼저 만든다. 앱 저장소 문서에는 결함 내용을 길게 적지 않고 그 이슈 링크만 남긴다.

1. 재현 테스트부터 — coui 저장소 테스트로 결함을 재현한다. 배율처럼 조건이 있는 결함은 조건을 두 값으로 비교하는 테스트가 단단하다(예: 배율 1.0 과 1.5 에서 결과 비율이 1.5 인지).
2. 수정 후 coui 의 기존 테스트를 돌린다. Flutter·웹 양쪽을 고쳤다면 둘 다 돌린다. coui 가 요구하는 Flutter(packages/coui_flutter/pubspec.yaml 의 environment.flutter)를 만족하는 바이너리를 쓴다 — coui 체크아웃의 로컬 버전 고정 파일이 저장소에서 추적되지 않아 오래됐을 수 있다. CI 설정의 버전을 기준으로 삼는다.
3. PR 을 열고 CI 를 기다린다. 한 사례에서 20~25분이 걸렸다 — 그동안 앱 쪽 준비(재현 골든, 영향 목록)를 한다.

coui 는 release-please 가 "release PR"(모든 패키지의 버전 상향과 CHANGELOG 를 한 커밋에 묶은 PR)을 열어 두고, 그 PR 을 머지할 때 태그를 만든다.

1. 수정 PR 이 머지되면 release PR 이 갱신된다. 대상 패키지의 버전과 CHANGELOG 항목이 release PR 에 들어왔는지 확인한다.
2. 안 들어왔다면 release 워크플로 로그에서 다음을 찾는다.
   • unexpected token — 커밋 메시지 파싱 실패
   • No commits for path: packages/<pkg> — 그 패키지를 "변경 없음"으로 건너뜀
   • 관찰된 원인: 커밋 본문의 괄호가 줄바꿈을 넘으면 파서가 그 커밋을 못 읽는다. 워크플로는 성공으로 끝나서 태그가 안 생긴 것만 남는다.
   • 해결: 그 패키지 경로를 건드리는 후속 커밋을 파서가 읽을 수 있는 메시지(괄호를 한 줄 안에서 닫기)로 올린다.
3. release PR 을 머지한다(저장소의 머지 방식 규약을 따른다). 머지 후 git fetch --tags 로 태그를 확인한다.

1. coui_pin.py plan --target <새 주 패키지 태그> --pubspec <앱>/pubspec.yaml
2. 수정 커밋이 새 핀의 조상인지 확인한다: git -C <coui> merge-base --is-ancestor <수정 커밋> <새 핀 커밋>
3. 핀을 교체하고 golden-gate.md 3절대로 골든 보유 패키지 전부를 돌린다. coui 렌더 수정은 다른 화면의 골든도 바꾼다.
4. 앱에 있던 임시 우회(래퍼, 테마 덮어쓰기)를 걷어낸다. 걷어낸 뒤 골든이 수정 전과 같거나 의도대로 바뀌었는지 확인한다.

수정 PR 이 머지되기 전 앱에서 확인해야 하면, 앱의 기능 브랜치에서만 coui PR 커밋을 임시 핀으로 쓴다.

• 임시 핀 커밋은 태그가 없다(git tag --points-at 결과 없음). 이 상태로 기본 브랜치에 머지하지 않는다.
• 릴리스 태그가 생기면 그 커밋으로 교체한 뒤 머지한다.
• 상위 통합 브랜치(에픽 브랜치 등)에서 임시로 쓰는 것은 팀 규약에 따른다. 기본 브랜치로 가는 PR 전에 반드시 교체한다.

• 앱 PR 본문: coui 이슈·PR·릴리스 링크, 새 핀, 골든 재생성 목록.
• 핀 주석: = <주 패키지>-vX.Y.Z 태그 커밋(coui_core 자체 버전 A.B.C) 한 줄. 결함 설명은 주석에 길게 쓰지 않는다.