ci(S15P11A705-154): infra action pin·보존 문서·dev 준비를 정합화한다

[colosair]

요약

S15P11A705-154 후속 정합 3건이다. 서로 파일이 겹치지 않아 한 PR로 묶었다.
① infra#82 병합으로 확정된 canonical action SHA 로 pin 갱신, ② ai#39 가 덮어쓴
보존 문서 복원, ③ main·dev 2단 브랜치 준비(브랜치 생성·protection 은 중앙 몫).
도메인 코드·DB·앱 동작 변경 없음 — CI 설정·규약·문서만 바뀐다.

Jira (필수)

• 키 또는 URL: S15P11A705-154 — https://ssafy.atlassian.net/browse/S15P11A705-154
• 완료 조건: action pin 이 infra main 과 일치하고, 보존 원칙 위반이 복원되며,
  dev 도입 시 CI·규약이 즉시 성립하는 상태

변경 사항

① Infra action pin (84458bf3 → 16bfae0d)

파일	무엇을·왜
.github/workflows/seal-runtime-secrets.yml	공용 action pin 을 infra#82 병합 commit 으로. 기존 84458bf3 은 병합 전 브랜치 commit 이라 infra main 과 diverged 였고 action.yml 내용도 달랐다
tests/test_runtime_secret_contract.py	ACTION 상수를 동일 SHA 로. 이 상수는 workflow 의 uses 문자열과 정확히 일치해야 step 을 찾으므로 한쪽만 바꾸면 테스트가 깨진다(아래 RED)

대상 SHA 의 입력 계약을 직접 확인했다. policy·revision 두 입력의 이름·필수
여부·설명과 branch·pull_request_url 두 출력이 byte 단위로 동일하다. 유일한
차이는 back OAuth CLIENT_ID 3종의 unset 방어 추가와 알파벳 정렬로, ai-dev
policy 와 무관하다. 따라서 Need Decision 아님.

$ diff <(sed -n '/^inputs:/,/^runs:/p' action-84458bf.yml) \
       <(sed -n '/^inputs:/,/^runs:/p' action-16bfae0.yml)   # exit 0, 출력 없음
$ gh api repos/Team-PinLog/infra/compare/16bfae0d...main --jq .status
identical
$ gh api repos/Team-PinLog/infra/compare/84458bf3...main --jq .status
diverged                                    # ahead 6 · behind 6

② 보존 규칙 위반 복원

ai#39 가 docs/implements/2026-07-29-sealed-secret-handoff.md 를 86줄에서 42줄로
덮어썼다. docs/implements/README.md 가 "완료된 항목도 삭제하지 않고 상태 표시만
갱신합니다" 를 규정하므로 위반이다.

복원 방식은 ai#39 코멘트에서 인프라와
합의한 그대로다 — 현재 내용을 지우지 않고 상태 노트를 얹는다.

파일	무엇을·왜
docs/implements/2026-07-29-sealed-secret-handoff.md	상단에 상태: 대체(구현 주체 이관) — 설계 근거는 보존 노트. 하단에 「대체된 구현의 설계 근거(S15P11A705-96 · 보존)」 절로 인프라가 지목한 4건(--raw 선택·중간 평문 YAML 회피·strict scope·기동 검증 근거) 복원. 7키→3키 축소 경위와 이전 판 미결 3건의 현재 상태도 표로 남김
docs/implements/README.md	개별 리포트 표에 이 문서가 애초에 누락돼 있어 행 추가. I24 인벤토리 행을 이관 사실 반영해 갱신. 그 과정에서 I24·I25 를 헤더 없는 별도 표로 끊고 있던 빈 줄도 제거

diff 는 +101/−1 이고 유일한 삭제 줄은 갱신된 action SHA 다. 42줄 전부 보존되며
문서는 142줄이 됐다.

③ dev 브랜치 도입 준비

파일	무엇을·왜
.github/workflows/ai-ci.yml	pull_request·push 트리거를 [main, dev] 로. image-publish 의 if 는 refs/heads/main 그대로 유지하고, 왜 비대칭인지 주석으로 못박음
CONTRIBUTING.md 45행	분기·push 기준을 dev 로. 2단 구성(dev 통합 / main 배포)과 publish 가 main 전용인 이유를 명시
CONTRIBUTING.md 98행	병합 조건 절을 두 브랜치로 분리 — dev 는 일상 병합 대상, main 은 dev 릴리스 병합 전용이며 관리자 포함 보호 적용
CONTRIBUTING.md 116행	진행 중 브랜치가 반영할 기준을 dev 로

publish 를 dev 로 옮기지 않았다. infra 의 ai-image-update.yaml 이
test "$SOURCE_BRANCH" = main 으로 어서션하므로 넓히면 GitOps 반영이 거부된다. 이
근거를 workflow 주석과 CONTRIBUTING.md 양쪽에 남겼다.

테스트 / 검증

Docker 가 기동 상태였으므로 pgvector Testcontainers 를 포함한 전체 suite 를 실행했다.
생략한 검증 없음.

RED

pin 을 한쪽만 바꾸면 깨진다는 것을 실측했다. workflow 를 옛 SHA 로 되돌리고 테스트는
새 SHA 를 기대하게 둔 상태:

$ python -m pytest tests/test_runtime_secret_contract.py -q      # exit 1
FAILED test_checkout_and_shared_action_are_immutable_and_revision_bound  - StopIteration
FAILED test_shared_action_receives_only_the_exact_environment_secret_keys - StopIteration

next(step for step in job["steps"] if step.get("uses") == ACTION) 가 매칭에 실패해
StopIteration 이다. 두 파일을 함께 바꿔야 하는 이유가 이것이다.

GREEN

$ python -m pytest tests/test_runtime_secret_contract.py tests/test_ci_image_publish_contract.py -q
11 passed                                                        # exit 0

test_ci_image_publish_contract.py 는 트리거가 아니라 image-publish 의 if 를
어서션한다(github.ref == 'refs/heads/main' 포함 여부). 조건을 유지했으므로 ③ 에
따른 테스트 수정이 필요 없고, 되레 publish 를 dev 로 넓히려는 시도를 이 테스트가
막아 준다.

Regression

• ruff check . — All checks passed! (exit 0)
• python -m compileall app tools — exit 0
• pytest --cov=app --cov-branch --cov-report=term-missing — 74 passed, exit 0,
  TOTAL 77% (693 stmt / 150 miss / 102 branch). app/ 변경이 없어 커버리지는 main 과 동일
• DB 계약 변경 시 pgvector(PostgreSQL) Testcontainers 검증 — 스키마·DB 계약 변경은
  없으나 Docker 29.6.1 로 전체 suite 를 돌려 DB 테스트를 건너뛰지 않았다

검증 커밋: 2822816 · 분기 기준 main b171f8f

리뷰 포인트

1. 16bfae0d 가 맞는 pin 인가. infra#82 의 merge commit 이자 infra main 과
   identical 임을 확인했다. 태그가 아니라 merge commit 을 pin 하는 현재 방식을
   유지했다 — 태그 이동 위험을 피하려는 기존 판단으로 이해했다.
2. 입력 계약 확인 범위. action.yml 의 inputs/outputs 블록 동일성까지 봤다.
   ai-dev 의 키 집합은 action.yml 이 아니라 infra 의 guardrails 스크립트가
   들고 있어 이 PR 에서 판정하지 않았다 — 아래 「범위 밖」의 3키/7키 미결과 같은
   사안이다.
3. 보존 문서에 어디까지 복원하는가. 인프라가 지목한 4건 + 독자가 현재 계약(이름 4개)
   과 과거 7키 사이에서 혼란하지 않도록 축소 경위를 넣었다. 과하다고 보면 축소 경위
   절만 빼도 합의는 충족된다.
4. CONTRIBUTING.md 가 dev 를 전제하는데 브랜치가 아직 없다. 이 PR 자체가
   main 대상인 이유다(지시된 준비 PR). 병합~dev 생성 사이 짧은 구간에는 문서가
   존재하지 않는 브랜치를 가리킨다. 순서를 뒤집으려면 dev 를 먼저 만들어야 하는데
   그건 중앙 소관이라 이 PR 에서 하지 않았다.
5. ai-ci 를 dev push 에서도 돌리는 비용. dev 병합마다 check 가 한 번 더 돈다.
   cancel-in-progress 는 pull_request 에서만 참이라 dev push 는 순차 완료된다 —
   의도한 동작인지 확인 바란다.

리스크

• 계약: action pin 이동은 infra 소유 계약을 따라가는 방향이며 입력 계약 동일성을
  확인했다. 봉인 workflow 는 실행하지 않았다 — 실제 sealing 결과는 여전히 미검증이고,
  그 판정은 Environment·토큰 준비 완료 후 수동 workflow_dispatch 시점이다.
• 데이터·개인정보: 없음. Secret 값·placeholder·base64 표현을 레포에 넣지 않았고
  contract test 가 이를 계속 어서션한다.
• 운영·배포: image publish 경로 무변경(main push 전용 유지). dev 트리거
  추가는 check 실행 범위만 넓힌다. 다만 main 의 branch protection 이 strict
  ai-ci / check 를 요구하므로, dev 생성 후 dev 에도 동일 보호를 걸기 전까지는
  dev 가 무보호 상태다 — 중앙 후속 작업에 포함돼야 한다.

범위 밖 / 후속

이번 PR에서 다루지 않는 항목:

1. dev 브랜치 생성·기본 브랜치 변경·branch protection — 지시대로 중앙이 이 PR
   병합 후 수행한다. dev 에도 strict ai-ci / check 를 걸어야 한다.
2. docs/development/workflow.md 의 main 참조 4곳(4·8·33·53행) — 이 PR 이 지정한
   5개 파일 밖이라 손대지 않았다. 병합 직후 CONTRIBUTING.md 와 불일치한다
   ("최신 main에서 독립 브랜치 생성"). docs/proposals/P44 52행도 동일. 후속 티켓
   필요 — 규약 정본은 CONTRIBUTING.md 이므로 문서 마찰이지 동작 결함은 아니다.
3. 3키 vs 7키 미결 — ai#39 에서 질의한 infra 의
   tools/validate_ai_dev_prerequisites.py REQUIRED_RUNTIME_KEYS(7키)와
   docs/ai-dev-prerequisites.md 의 8-key schema 가 3키 기준으로 갱신될지 아직
   회신 없음. 갱신 전에는 봉인 workload gate 가 열리지 않는다. infra 소관.
4. Flyway 파일 집합 불일치 — infra 문서가 6파일을 전제하나 back dev 에 8개
   (V4·V5 추가). 백엔드 소관으로 관측만 전달된 상태.
5. Environment 설정·봉인 workflow 실행·ai#32 — 금지 범위라 건드리지 않았다.

후속 Jira: 위 2번(문서 정합)은 AI 파트 신규 티켓 필요. 3·4번은 infra·back 소관.

영구 문서

• docs/implements/2026-07-29-sealed-secret-handoff.md — 상태 노트 + 대체된 구현의
  설계 근거 보존(본 PR 항목 ②)
• docs/implements/README.md — 개별 리포트 표에 누락 행 추가, I24 인벤토리 갱신
• CONTRIBUTING.md — 브랜치 전략·병합 조건 2단화(본 PR 항목 ③)

관련 GitHub Issue (선택)

• 선행: ci(S15P11A705-154): runtime Secret 봉인 계약을 정렬한다 #39 (복원 방식 합의 코멘트)
• 선행: [S15P11A705-154] Backend OAuth CLIENT_ID Infra 계약 확장 infra#82 (canonical action SHA 16bfae0d)