핀 모델 — 태그·커밋·패키지 버전

coui 는 한 저장소(pub workspace)에서 여러 패키지를 낸다. release-please 가 패키지마다 따로 버전을 올리고 태그를 붙인다.

같은 번호 태그가 우연히 같은 커밋인 버전도 있다(예: v0.131.0). 그래서 한 번 통과했다고 방식이 안전한 것은 아니다. 매 교체마다 커밋으로 풀어 비교한다.

1. 목표를 주 패키지 태그로 고른다. 주 패키지는 앱이 직접 쓰는 플랫폼 패키지다 — Flutter 앱은 coui_flutter, Jaspr 웹 앱은 coui_web.
   • "최신"은 git tag -l '<주 패키지>-v*' 를 semver 로 정렬해 고른다.
   • gh api repos/<owner>/coui/releases 의 첫 항목을 쓰지 않는다 — 목록 순서가 발행 순서가 아니라서 더 늦게 나온 릴리스가 뒤에 있을 수 있다.
   • 두 패키지를 다 쓰는 앱(혼합)은 두 주 패키지의 최신 태그 가운데 다른 쪽 태그 커밋을 조상으로 가진 태그를 고른다(그 커밋에 다른 쪽의 최신 변경도 들어 있다). 그런 태그가 없으면 --target 으로 직접 지정하고, 태그 없는 커밋은 쓰지 않는다.
2. 그 태그를 커밋 C 로 푼다: git rev-parse <주 패키지>-vX.Y.Z^{commit}.
3. 앱이 쓰는 형제 패키지 전부를 C 로 고정한다. 형제 태그를 따로 찾지 않는다.
4. C 에서 주 패키지 pubspec 의 요구치를 읽어 앱 환경과 비교한다 — coui_flutter 는 environment.flutter, coui_web 은 environment.sdk 와 dependencies.jaspr(web-apps.md §2).
5. C 의 매니페스트에서 형제 버전을 읽어 핀 주석에 남긴다.

coui_pin.py plan 이 1~5 를 한 번에 한다(주 패키지는 앱 pubspec 에서 판별, --package 로 강제).

태그 방식을 쓰다가 같은 번호 태그가 다른 커밋인 릴리스를 만나 SHA 로 돌아간 실제 이관 사례가 있다. 태그 방식을 유지할 거라면 교체 때마다 check 로 형제 커밋이 같은지 확인하고, 같은 커밋에 형제 태그가 없으면 그 형제만이라도 SHA 로 쓴다.

자동으로 coui 핀을 올리는 워크플로가 있다면 다음을 확인한다.

• 최신 릴리스를 /releases[0] 로 고르지 않는가 — semver 로 고른다.
• 형제 태그가 없는 릴리스 커밋을 만나면 flutter 만 올리고 나머지를 그대로 두지 않는가 — 그러면 형제 커밋이 갈라진다. 형제 태그가 없으면 SHA 를 쓴다.
• 교체 후 형제 ref 가 전부 같은 커밋인지 검사하는가 — coui_pin.py check 를 그대로 쓸 수 있다.
• 실패가 조용히 쌓이지 않는가 — 토큰 만료 등으로 매일 실패하는 동안 아무도 모를 수 있다. 실패 알림을 둔다.
• 자동으로 열린 PR 은 BREAKING 을 흡수하지 않는다 — 큰 격차는 이 스킬의 홉 절차로 사람이 올린다.

핀 옆 주석에는 다음만 남긴다. 긴 이력은 PR·이슈로 보낸다(주석이 옛 핀을 계속 "지금 핀"으로 적는 드리프트가 흔하다).

dependency_overrides:
  coui_core:
    git:
      url: https://github.com/<owner>/coui.git
      ref: <SHA> # = coui_flutter-vX.Y.Z 태그 커밋(coui_core 자체 버전 A.B.C)
      path: packages/coui_core
  coui_flutter:
    git:
      url: https://github.com/<owner>/coui.git
      ref: <SHA> # = coui_flutter-vX.Y.Z 태그 커밋
      path: packages/coui_flutter

• 불변식 한 줄(형제는 같은 커밋)과 올리는 방법 링크(이 스킬, 프로젝트 프로필)를 섹션 머리 주석에 둔다.
• "지금 핀: …" 처럼 값 자체를 주석에 반복해 적지 않는다 — ref 줄이 곧 값이다.