docs(S15P11A705-158): 필수 상태 검사 둘을 정본에 반영하고 하위 문서를 맞춘다

[colosair]

요약

ai#42 병합 후 main·dev 양쪽 required status checks에
ai-ci / embedding profile parity가 추가됐는데 정본(CONTRIBUTING.md)이 갱신되지
않았다. 그래서 낡은 값이 정본에서 하위 문서로 퍼졌다. 이번에는 정본을 먼저 고치고
하위를 거기에 맞춘다. ai#45에 이은 dev 전환의 마지막 조각이며 코드·CI·GitHub 설정
변경은 없다.

실제 설정을 대조하는 과정에서 두 번째 오류를 하나 더 찾았다 — 아래 「배경」 2번.

Jira (필수)

• 키 또는 URL: S15P11A705-158 — https://ssafy.atlassian.net/browse/S15P11A705-158
• 완료 조건: 정본의 병합 조건 절이 실제 branch protection과 일치하고, 하위 문서가 그
  정본과 일치한다

base는 dev(0d739cb, ai#45 병합 직후)다.

변경 사항

파일	무엇을·왜
CONTRIBUTING.md	정본. 병합 조건 절을 실제 protection에 맞춤 — 검사 둘 명시, dev·main 조건이 동일함을 명시, 검사 이름 문자열 일치 + 정본 우선 개정 순서 규칙 추가
docs/development/workflow.md	15행 흐름도와 54행 병합 전 조건을 검사 둘로
docs/proposals/P44-ai-repository-governance.md	53행 완화 강화(문서를 고치는 주체를 정함) + 이 리스크가 실제로 발생했다는 각주
docs/WORKLOG.md	이 작업 한 줄

배경

1. 왜 낡은 값이 세 문서로 퍼졌나

순서가 뒤집혔다. GitHub 설정이 먼저 바뀌고 정본이 그대로 남았고, 직전 작업(ai#45)은
*"정본 재개정은 범위 밖"*이라는 제약 아래 하위 문서를 낡은 정본에 맞췄다. 그 판단
자체는 당시 제약에서 맞았지만(그렇게 하지 않으면 하위가 정본과 어긋나는 새 드리프트가
생긴다), 결과적으로 같은 낡은 값이 문서 셋에 남았다.

그래서 이번 정본 수정에 순서 규칙을 본문으로 박아 두었다 — 검사를 추가·개편할 때는
이 절을 먼저 고치고 하위 문서와 GitHub 설정을 거기에 맞춘다.

2. 검사 목록 말고 하나가 더 틀려 있었다

지시받은 것은 검사 둘 반영이었으나, 실제 설정을 API로 대조하니 main과 dev가
모든 항목에서 동일했다.

$ gh api repos/Team-PinLog/ai/branches/{main,dev}/protection
main·dev 공통
  strict                             true
  contexts                           ["ai-ci / check", "ai-ci / embedding profile parity"]
  required_conversation_resolution   true
  enforce_admins                     true
  required_approving_review_count    0

그런데 기존 정본은 관리자 포함 보호 적용을 main bullet에만 적고 있었다. 실제로는
dev도 enforce_admins: true다 — 검사 목록과 별개인 두 번째 오류다. 지시 범위를 좁게
읽으면 이건 그대로 남았을 것이고, 정본을 실제 설정에 맞추는 이번 목적에 어긋난다.
그래서 함께 고쳤다.

구조적 원인도 같이 없앴다. 원래 형태는 같은 조건을 두 bullet에 중복 기재해서 한쪽만
낡을 수 있었다. 조건은 공통으로 한 번만 적고, bullet에는 실제로 다른 것 — 무엇을
병합하는가 — 만 남겼다. image publish가 main 병합에서 일어난다는 서술은 그 bullet에
유지했다.

3. P44의 완화가 실패한 사례다

P44 리스크 표에 *"문서와 실제 GitHub 설정 불일치 → branch protection 변경 직후 API로
설정을 재조회한다"*가 있었다. 이 리스크가 그대로 발생했다. 완화가 부족했던 지점이
분명하다 — "재조회"는 설정을 읽는 것까지만 다루고 문서를 고치는 주체를 정하지
않았다. 그래서 완화를 *"설정을 바꾼 사람이 같은 작업에서 정본을 갱신하고, 변경 직후 API로
재조회해 문서와 대조한다"*로 바꾸고, 발생 사실을 각주로 남겼다.

리뷰 포인트

1. 관리자 포함 보호 정정이 범위 확장인지. 지시는 검사 둘이었고 이건 추가 발견이다.
   정본을 실제 설정에 맞추는 것이 이 작업의 목적이므로 포함이 맞다고 판단했다. 분리를
   원하면 그 문장만 되돌릴 수 있다.
2. 조건을 공통으로 합친 서술 구조. 중복 기재가 이번 드리프트를 가능하게 한 구조라
   합쳤다. bullet별 조건 표기를 유지하는 편이 읽기 좋다고 보면 되돌릴 수 있으나, 그러면
   같은 값을 두 곳에 유지해야 한다.
3. P44 완화 강화가 결정문 개정인지. 리스크 표 한 칸과 각주다. 발생한 리스크의
   완화를 그대로 두면 다음에도 같은 구멍이 남는다고 판단했다. ai#45에서 세운 방식대로
   표를 고치고 이력을 각주로 남겼다.
4. WORKLOG 직전 줄을 고치지 않았다. 그 줄은 *"정본은 아직 하나만 적고 있다"*고
   적혀 있고 이 PR이 그걸 해소한다. 그래도 그 시점의 사실 기록이므로 고치지 않고 새
   줄을 더했다 — ai#45에서 도입한 merge=union은 기존 줄 수정 시 중복 위험이 있고,
   그 주의의 첫 적용 사례다.

테스트 / 검증

문서 전용이라 RED/GREEN이 적용되지 않는다. 대신 문서가 실제 설정과 일치하는지 기계로
대조했다 — 이 PR이 정본에 새로 박은 규칙("문자열까지 일치")을 그 자리에서 검증한 것이다.

$ python  # CONTRIBUTING.md 의 검사 목록 블록을 파싱해 protection 과 대조
documented: ['ai-ci / check', 'ai-ci / embedding profile parity']
main  actual : ['ai-ci / check', 'ai-ci / embedding profile parity'] -> MATCH
dev   actual : ['ai-ci / check', 'ai-ci / embedding profile parity'] -> MATCH

순서·공백까지 리스트 동등 비교이며 불일치면 assert가 깨진다.

잔존 확인

$ grep -rn 'ai-ci / check' --include=*.md . | grep -v WORKLOG
CONTRIBUTING.md:109            (검사 둘 목록 블록 안)
docs/development/workflow.md:54 (검사 둘 나열 안)

단독으로 ai-ci / check만 필수라고 적는 서술은 남지 않았다.

개행

.gitattributes(ai#45)가 적용돼 커밋 시 경고가 CRLF → LF 방향으로 바뀌었고,
git ls-files --eol로 네 파일 모두 인덱스가 i/lf임을 확인했다.

Regression

• ruff check . — All checks passed! (exit 0)
• python -m compileall app tools — exit 0
• pytest — 146 passed, exit 0 (Docker 기동, pgvector Testcontainers 생략 없음)
• python tools/check_embedding_profile_parity.py — exit 0
• app/·tests/ 무변경 — 문서 4개만 변경

검증 커밋: 9a9a32e · 분기 기준 dev 0d739cb

리스크

• 계약: 없음. 코드·CI·GitHub 설정 무변경이며 문서를 실제 설정에 맞추는 방향뿐이다.
  이 PR은 protection을 바꾸지 않는다.
• 데이터·개인정보: 없음.
• 운영·배포: image publish 경로·조건 무변경. main 병합에서 publish가 일어난다는
  서술을 main bullet에 유지했다.
• 남은 노출: 앞으로 또 설정이 먼저 바뀌면 같은 드리프트가 재발할 수 있다. 이 PR은
  순서 규칙을 문서로 박았을 뿐이고 기계적 강제는 아니다 — 아래 후속 참조.

범위 밖 / 후속

1. 정본↔protection 대조를 CI로 강제하지 않았다. 이 PR에서 쓴 대조 스크립트는
   일회성이다. embedding profile parity 잡처럼 상시 검사로 만들 수 있으나
   branches/*/protection 조회에 admin 권한 토큰이 필요해서, ai CI에 그 권한을
   상주시키는 것이 이 티켓에서 판단할 사안이 아니다(parity 잡을 무인증 경로로 짠
   것과 정면으로 상충한다). 후속 티켓으로 별도 판단이 필요하다.
2. default_branch가 아직 main — 레포 설정, 사용자 직접 수행.

후속 Jira: 1번(정본↔protection 대조 자동화 여부와 권한 경계 판단).

영구 문서

• CONTRIBUTING.md — 병합 조건 절(정본)
• docs/development/workflow.md — 흐름도·병합 전 조건
• docs/proposals/P44-ai-repository-governance.md — 리스크 완화 강화 + 발생 각주
• docs/WORKLOG.md — 이 작업 한 줄

관련 GitHub Issue (선택)

• 선행: docs(S15P11A705-158): main 참조 문서를 dev 2단 구성에 정합시킨다 #45 (문서 6곳 정합 + .gitattributes)
• 원인: ci(S15P11A705-156): profile 리터럴 대조를 CI 로 옮기고 WORKLOG 를 메운다 #42 (embedding profile parity 잡 도입)