docs(release): 긴급 수정(hotfix) 경로와 필수 백머지 문서화 (#480)

[parkjs101]

무엇

AGENTS.md 릴리스 절차에 긴급 수정(hotfix) 경로를 추가한다. 문서 변경만이고 코드/스크립트는 건드리지 않는다.

#480 의 마이그레이션 7단계 중 문서 항목만 떼어낸 것이다. ff 승격 전환(#480 본체)은 브랜치 보호 적용이 선행돼야 하므로 별도 PR로 간다.

왜

preview 에 미출시 커밋이 쌓여 있는 것은 정상이고 beta 채널의 존재 이유지만, 그 상태에서 정규 승격은 preview 전체를 함께 내보낸다. main 만 고쳐야 하는 상황의 경로가 어디에도 적혀 있지 않았다.

측정 시점 기준 격차:

main..preview 51    preview..main 0

긴급 수정 하나를 내보내려다 미검증 기능 51개가 딸려 나가는 상황이 실재한다.

핵심 — 백머지를 절차에 못박음

hotfix 커밋은 main 에만 남으므로, 백머지를 빠뜨리면 main 이 preview 의 조상에서 빠지고 다음 승격이 origin/main is not an ancestor of the certified preview SHA 로 막힌다.

막히는 것으로 끝나면 다행이다. 실제로는 그 상태를 손으로 복구하려다 #418 의 durable queue-notice store 가 통째로 사라졌고, 그대로 cli-jaw@2.17.13 이 npm 에 발행됐다. 그래서 백머지와 사후 검증(git merge-base --is-ancestor)을 선택이 아니라 필수 단계로 적었다.

#468 이 promote-to-main.sh 말미에 같은 검증을 이미 넣어 뒀으므로, 백머지를 빠뜨리면 다음 릴리스 로그에 WARN: origin/main is still not an ancestor of origin/preview 로 드러난다. 문서와 스크립트가 같은 불변식을 가리키게 맞췄다.

판단 분기를 앞에 둠

hotfix 경로를 기본값으로 제시하지 않았다. "preview 를 지금 다 내보내도 괜찮은가"를 먼저 묻고, 괜찮으면 정규 절차를 쓰라고 적었다. 분기를 만들지 않는 쪽이 항상 더 안전하다.

검증

• tests/unit/release-scripts-contract.test.ts — 11/11 pass
• structure/verify-counts.sh — 불일치 1건은 skills_ref/registry.json 으로, 이 PR 과 무관한 서브모듈 포인터 변경에서 온 것이라 손대지 않았다

Draft 인 이유

#480 의 방향(ff 승격 전환, dev 기본 브랜치)이 확정되기 전에 머지하면 문서가 두 번 바뀐다. 다만 이 PR 자체는 현재 squash 승격 구조에서도 그대로 옳으므로, #480 결정과 무관하게 머지해도 무방하다.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[parkjs101]

핫픽스 경로는 도입하지 않기로 정정. #480 의 핫픽스 항목도 '없음(3번)'으로 정리한다.

문서만 남기면 실제 운영과 어긋나므로 철회한다. 승격 구조 변경(ff 전환)은 별도 PR 로 간다.