docs(S15P11A705-158): main 참조 문서를 dev 2단 구성에 정합시킨다

[colosair]

요약

ai#40이 CONTRIBUTING.md를 main·dev 2단 구성으로 개정한 뒤, 다른 문서가 main을
가리킨 채 남아 있었다. 정본(CONTRIBUTING.md)에 문서 6곳을 맞춘다. dev 전환의
마지막 조각이며 앱 코드·CI·GitHub 설정 변경은 없다.

범위 추가(중앙 지시) — .gitattributes를 신설해 docs/WORKLOG.md에 merge=union을
걸고 개행을 LF로 고정한다. ai 레포에는 이 파일이 아예 없어서 동시 작업이면 WORKLOG가
항상 충돌한다. 오늘 실제로 ai#44↔ai#45가 충돌했다.

Jira (필수)

• 키 또는 URL: S15P11A705-158 — https://ssafy.atlassian.net/browse/S15P11A705-158
• 완료 조건: 여섯 곳의 브랜치 서술이 CONTRIBUTING.md와 일치하고, image publish의
  main 기준 서술은 유지된다

이 PR의 base는 dev다. 개정된 CONTRIBUTING.md가 요구하는 대로 dev에서
분기했다 — 앞선 ai#40·ai#42는 main을 대상으로 열렸고 그 불일치가 이 티켓을 만든
원인 중 하나다. 현재 base는 ai#44 병합 후의 dev(b45aa93)다(아래 rebase 이력).

변경 사항

정본은 CONTRIBUTING.md:46-50(브랜치)과 :107-111(병합 조건)이다.

파일	행	무엇을·왜
docs/development/workflow.md	4	"main에 병합하는 실행 순서" → dev. 2단 구성 한 줄(dev 통합 / main 배포)을 함께 명시
	8	흐름도 "최신 main에서 독립 브랜치 생성" → dev
	30	"최신 origin/main에서 브랜치를 만든다" → origin/dev
	33	"운영체계가 main에 병합되면 최신 main을 반영" → dev (한 행에 2곳)
	53	병합 전 조건 "최신 main 기준 ai-ci / check 성공" → dev
	§5	추가 — 릴리스 병합(dev→main)과 publish가 거기서 일어난다는 서술 한 줄
docs/proposals/P44-ai-repository-governance.md	52	리스크 완화 "운영체계 병합 후 최신 main을 반영한다" → dev. 전환 시점 각주 추가
docs/WORKLOG.md	—	이 작업 두 줄 + 머리말에 merge=union 주의
.gitattributes	—	신규. docs/WORKLOG.md merge=union + 개행 LF 고정

배경 — 판단이 필요했던 두 곳

1. workflow.md §5에 한 줄을 추가한 이유

지시받은 6곳만 고치면 이 문서는 "dev에 병합하는 실행 순서"로 끝나고, main이 언제
무엇을 받는지 어디에도 없다. workflow.md만 읽는 사람에게 main은 존재하지 않는
브랜치가 된다. 그래서 §5에 릴리스 병합과 publish 위치를 한 줄 넣었다. 조건 자체는
정본을 링크로 가리켜 P44가 정한 *"규칙은 CONTRIBUTING.md 한 곳에만 두고 나머지는
링크와 실행 순서만 둔다"*를 지켰다.

이 줄이 image publish의 main 기준을 서술로 못박는 역할도 한다 — 금지 항목이
요구하는 방향과 같다.

2. P44를 조용히 고치지 않은 이유

P44는 상태: Accepted, 날짜 2026-07-28인 결정 문서다. 표 한 칸을 main→dev로
바꾸면 2026-07-28에 dev 기준으로 결정했던 것처럼 읽힌다. 그래서 표 아래에 각주를
남겼다 — 작성 시점에는 main 단일 구성이었고 2단 전환은 S15P11A705-154·-158에서
이뤄졌다는 것.

docs/implements/README.md의 삭제 금지 원칙은 implements/ 전용이고 proposals/에는
같은 규정이 없다(확인함). 다만 proposals/는 *"Accepted인 것은 확정된 결정이며 구현이
따라야 한다"*이므로, 낡은 값을 그대로 두면 구현이 따라야 할 규칙이 틀린 상태가 된다
— 그래서 고치는 것이 맞고, 이력만 남긴다. ai#39가 implements/ 문서를 이력 없이
덮어써 ai#40에서 복원해야 했던 것과 같은 종류의 실수를 반복하지 않으려는 것이다.

3. .gitattributes — 왜 union 이고, 어디까지만 이득인가

WORKLOG는 모든 작업이 표 끝에 한 줄씩 붙이는 append 전용 파일이다. 브랜치가 둘
이상이면 항상 같은 지점에서 충돌한다. 오늘 ai#42·ai#44·ai#45가 모두 이 파일을
건드렸고, 순차 병합이라 앞의 둘은 넘어갔을 뿐이다 — ai#44가 dev에 들어간 순간
ai#45가 DIRTY가 됐다. dev 2단 구성을 도입한 이유가 담당자 합류이므로 이 충돌은
앞으로 반복된다.

이득의 한계를 정확히 적어 둔다. GitHub 서버측 병합 판정은 merge=union을 반영하지
않으므로 PR 화면은 여전히 CONFLICTING으로 보인다. dev를 브랜치에 반영해 다시
올리는 절차 자체는 그대로 필요하고, 달라지는 것은 그 반영에서 손으로 충돌을 풀 일이
없어진다는 것까지다. 이 주의를 .gitattributes 주석과 WORKLOG 머리말 양쪽에 남겼다 —
파일을 여는 사람이 보는 곳이 후자다.

개행 고정은 back/.gitattributes와 같은 형태이나 실제로 존재하는 확장자에 맞췄다
(Java·Gradle 항목을 그대로 옮기지 않았다). deploy/sealed-secrets/*.pem은 Infra가 제공한
인증서 원본이라 대상에서 뺐다.

리뷰 포인트

1. §5 추가 한 줄이 범위 확장인지. 지시는 6곳이었고 이것은 7번째 변경이다. 문서
   일관성상 필요하다고 판단했으나 불필요하다고 보면 삭제해도 6곳 정합은 성립한다.
2. P44 각주의 위치와 분량. 리스크 표 바로 아래 4줄이다. 결정문 본문을 건드리지
   않으려고 표 밖에 뒀다.
3. workflow.md 15·53행은 ai-ci / check만 적는다 — 의도적으로 유지했다.
   아래 「범위 밖」 1번이 이유다. 정본이 그렇게 적고 있어 문서를 정본에 맞췄다.
4. merge=union 을 설정만 하지 않고 동작을 실측했다. 임시 브랜치 둘이 각자 WORKLOG에
   한 줄을 붙인 뒤 병합해 충돌 0·양쪽 줄 보존을 확인했다(아래 검증). 결과 순서가
   B → A로 나와 순서 미보장 주의가 실제로 맞다는 것도 같은 실험에서 드러났다.
   임시 브랜치는 삭제했다.
5. 개행 선언이 재정규화를 일으키지 않는 근거. git ls-files --eol로 인덱스가 이미
   전부 LF임을 확인했다(126 파일 i/lf, 나머지 11개는 빈 __init__.py). 그래서 이
   선언은 앞으로 들어오는 파일만 고정하고 기존 파일의 인덱스 내용을 바꾸지 않는다 —
   .gitattributes 커밋의 staged 파일이 둘뿐인 것이 그 증거다.
6. 기본 브랜치 전환은 언급하지 않았다. 금지 항목대로 "전환 예정"을 적지 않고 결과
   상태만 썼다. 조회 결과 default_branch는 아직 main이지만, 이 문서들은 분기·병합
   대상만 규정하므로 기본 브랜치 설정과 무관하게 정확하다.

테스트 / 검증

문서 전용 변경이라 RED/GREEN이 적용되지 않는다. 대신 정합성을 기계로 확인했다.

정합 확인

$ grep -n 'main' docs/development/workflow.md
5:  브랜치이고 `main`은 배포 브랜치다 — 일상 작업의 병합 대상은 `dev`다.
67:  `main`으로는 기능 브랜치를 직접 병합하지 않는다. 릴리스 시점에 `dev`를 `main`으로
68:  병합하며, 컨테이너 이미지 publish는 그 `main` push에서만 일어난다. 조건은

남은 main은 셋 다 배포 브랜치·릴리스 병합·publish 서술로 의도된 것이다. 분기
기준·반영 대상·CI 기준을 가리키는 main은 하나도 남지 않았다.

P44의 잔존 main 2곳도 전환 시점을 설명하는 각주뿐이다.

레포 전체에서 최신 main·origin/main 류를 재검색해 남은 것은
docs/implements/2026-07-28-s1-implementation-recovery.md의 출처 표기
(직접확인(origin/main 코드)) 하나이며, 그 시점에 무엇을 대조했는지의 사실 기록이라
바꾸지 않았다(implements/ 보존 원칙 대상이기도 하다).

merge=union 실측

설정을 넣었다는 것과 그것이 동작한다는 것은 다르므로 직접 병합해 봤다.

$ git checkout -b tmp/union-a <HEAD>   # WORKLOG 에 UNION-TEST-A 한 줄
$ git checkout -b tmp/union-b <HEAD>   # WORKLOG 에 UNION-TEST-B 한 줄
$ git merge tmp/union-a
Auto-merging docs/WORKLOG.md
Merge made by the 'ort' strategy.                      # exit 0 — 충돌 없음

$ grep -n 'UNION-TEST' docs/WORKLOG.md
54:| 2026-07-30 | UNION-TEST-B | y |
55:| 2026-07-30 | UNION-TEST-A | x |                    # 양쪽 줄 보존
$ grep -c '<<<<<<<\|>>>>>>>' docs/WORKLOG.md
0

git check-attr merge text eol -- docs/WORKLOG.md → merge: union · text: set ·
eol: lf. 순서가 B → A로 나온 것이 머리말에 적은 순서 미보장 주의의 실제 사례다.
임시 브랜치 둘은 삭제했고 UNION-TEST 문자열 잔존 0을 확인했다.

링크

workflow.md·P44·WORKLOG.md의 상대 링크를 전수 확인해 깨진 것 없음.

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/ 무변경 — git status로 확인. ai#44(S15P11A705-121)와 파일이 겹치지 않는다
• .gitattributes 추가가 대량 재정규화를 일으키지 않음 — 인덱스 전부 LF 확인 후
  staged 파일 2개만 발생

검증 커밋: fe7a60a · 분기 기준 dev b45aa93

rebase 이력: 최초 검증은 dev 19a5d21 기준 3f2a27f(88 passed)였다. 작업 중
ai#44(S15P11A705-121)가 dev에 병합되며 docs/WORKLOG.md의 같은 추가 위치에서
충돌했다. CONTRIBUTING.md의 *"운영체계 PR 병합 후 진행 중인 브랜치는 최신 dev를
반영한다"*에 따라 rebase하고 두 줄을 병합 순서(-121 → -158)로 모두 보존했다
(어느 쪽도 덮어쓰지 않았다). rebase 후 전체 검증을 다시 돌린 결과가 위 수치다 —
ai#44가 테스트를 늘려 88 → 146이 됐다. app/·tests/는 여전히 무변경이다.

리스크

• 계약: 없음. 코드·CI·GitHub 설정 무변경이며 정본(CONTRIBUTING.md)도 건드리지
  않았다. 문서를 정본에 맞추는 방향뿐이다.
• 데이터·개인정보: 없음.
• 운영·배포: image publish 경로·조건 무변경. infra의 ai-image-update.yaml
  어서션(SOURCE_BRANCH = main)과 어긋나는 서술을 만들지 않았고, 오히려 §5에서
  명시적으로 못박았다.

범위 밖 / 후속

1. CONTRIBUTING.md의 병합 조건 절이 required 체크를 하나만 적는다. 실제
   protection을 조회하면 main·dev 모두
   ["ai-ci / check", "ai-ci / embedding profile parity"] 둘 다 strict required다.
   그런데 정본 :107-111은 ai-ci / check만 적는다. 정본 재개정은 금지 항목이라
   손대지 않았고, 문서를 정본에 맞춰 두었다(리뷰 포인트 3). 정본을 실제 설정에 맞추는
   후속 티켓이 필요하다 — 이 PR이 고친 것과 같은 종류의 드리프트다.
2. default_branch가 아직 main이다. 레포 설정이며 사용자가 직접 수행한다고
   전달받았다. 문서에 예정으로 적지 않았다.
3. app/·tests/ — ai#44 진행 중이라 손대지 않았다.

후속 Jira: 1번은 AI 파트 신규 티켓(정본과 실제 protection 정합).

영구 문서

• docs/development/workflow.md — 브랜치·병합 절차를 2단 구성으로
• docs/proposals/P44-ai-repository-governance.md — 리스크 완화 서술 + 전환 시점 각주
• docs/WORKLOG.md — 이 작업 두 줄 + merge=union 주의 머리말
• .gitattributes — 신규. WORKLOG union + 개행 LF 고정

관련 GitHub Issue (선택)

• 선행: ci(S15P11A705-154): infra action pin·보존 문서·dev 준비를 정합화한다 #40 (CONTRIBUTING.md 2단 개정)
• 선행: ci(S15P11A705-156): profile 리터럴 대조를 CI 로 옮기고 WORKLOG 를 메운다 #42 (embedding profile parity 잡)