v0.18.0 HQ 운영 정본 — 기준선·소유권·병합 큐·릴리스 게이트 (이슈 #1279, G01)
2026-09-10 선행 확인 타이머 중단: 오너가 작업에 들어간 세션은 선행작업 타이머를 끄도록 전파하라고 요청했다. 담당자는 선행 조건을 확인하고 실제 작업에 착수하는 즉시 자기 선행 확인 heartbeat를
PAUSED로 바꾼다. 아직[선행대기]라면 기존 확인을 유지하다 착수 시 중단하고, 이미 중단했다면 그대로 둔다. 구현·Precheck·Merge Check·release 반영 이후에는 선행 확인 타이머를 계속 실행하지 않는다. CI 결과 추적·배포 후 관찰과 캠페인 전체를 연결하는 HQ 조율 heartbeat는 각각의 기존 종료 조건을 따른다.
2026-09-10 HQ 인계: 오너가
리팩토링 HQ세션(01a089b3-34c7-7f10-b718-3fec16596fb1)에 현재 리팩터링의 HQ 조율을 맡겼다. HQ는 직접 선행/앞 실행 스텝의 완료 PR·merge SHA·필수 검증·목적 release 포함과 계약 인계를 확인해 후속 담당에게 연결한다. 선행 대기 세션은 선행대기 제목 규칙으로 통일한다. 선행 PR 확인은 기존 5분 간격을 유지하며 새 승인 게이트·HQ 재승인을 추가하지 않는다. 다른 담당자의 PR·브랜치·큐 요청/취소/push/병합은 대신 조작하지 않는다.
2026-09-10 Phase 4 배정: 사용자 요청으로 D14 D14 #1533를 DATA / Phase 4-1에 추가했다. 전체 63개·Phase 4 7개·191개 직접 의존이며 D14 선행은 D02/D04/S10/D11, 후속 직접 소비자는 R01이다. 채택 실행계획과 총괄의 최신 목록을 따른다. D11의 기존 차등 발행 인계, R01의 활성 경로 마감, R04의 전체 비용, R05의 populated 전환 검증을 보강했다. 구현·검증 완료 판정은 추가하지 않았다.
2026-09-10 #1491 승인 정책 (v0.17.8 대상): 일반 작업→release는 precheck 후 Merge Check만 수행하고, 최종 release→staging에서 full을 실행한다. staging→main은 동일 tree의 유효한 full 기록과 현재 staging 배포·smoke를 확인한다. 진단용 dry-run·부분 재현은 유지한다. 앱 main
6afe58ec설치를 확인했다. 정상 큐의 새 실행·운영 배포 결과는 적용 기록에서 확인하며 아래 과거 실행 이력과 구분한다.
#1463 저장소 분리 이후 적용: 아래 앱 release·DB·데이터 보호 규칙은 앱 저장소에 적용한다. 과거 docs/admin 결합 빌드·같은 SHA 배포·앱 main 문서 직행·문서 문자열 검사 설명은 이관 전 기록이다. 모든 문서와 작업 기록은 dekerd/Barbelic-docs에서 관리하며, 현행 저장소 경계와 문서·관리자 독립 운영이 그 부분을 대체한다. 세션 제목은 현재 Phase/전체 Phase 규칙을 따른다. 코드 준비·원격 활성화·실제 배포 성공은 독립 운영 문서의 기록으로 구분한다.
2026-09-09 개정 (이슈 #1456·#1457·#1458, 오너 결정) — 명령·워크플로 이름이 바뀌었다. 작업 PR 통합 요청
npm run merge:request(구 landing:request), PR 전 사전 검증npm run ci:precheck-local(최신 release 합치기 → verify → 서버 변경 시 DB 단계, 브라우저 없음), 전체 검증npm run ci:full-local(릴리스 큐 runner 안에서만; 세션은--only <단계>재현만). 워크플로 표시 이름:3-Release Merge Request(release-merge-request.yml) ·GitHub Full CI(policy-contract.yml) ·1-Production Deploy/2-Staging Deploy(production-deploy.yml·staging-deploy.yml, 단계 정의는 deploy-steps.yml) ·Production smoke (manual)·Social login daily check·Daily data backup.landing:lock·db:preflight스크립트는 폐기됐다(GitHub concurrency 가 잠금, DB 검사는 사전 검증과 큐가 한다). 아래 본문의 옛 이름은 그 개정 전 기록이다.
한 문장 — v0.18.0 리팩터링 63개 작업을 여러 세션·여러 PC에서 진행할 때, 누가 무엇을 고칠 수 있고, 어떤 순서로 목적 release 에 합치고, 언제 Production 에 나가는지를 정하는 문서다. 목표·Phase·63개 작업 지시서는 총괄 문서가 정본이고, 이 문서는 그 총괄 문서의 §6(운영)·§9(검증·릴리스)를 실제 저장소 상태에 맞춰 집행 규칙으로 고정한다. 보존 정책과 바꾸는 기술 계약은 v0.18.0 ADR에 있다.
- 이슈: #1279 (계획 ID G01, Phase 1 Step 1)
- 정본 관계: 총괄 문서의 목표·선행 관계와 ADR의 보존 계약을 유지한다. 브랜치·CI·승격·배포는 2026-09-08 릴리스 프로세스가 정본이다. 아래 §1은 당시 기준선 기록이며 현재 설정은 착수 시 다시 확인한다. 새 프로세스 결정과 실제 자동화 전환 완료를 구분한다.
- 갱신 책임: HQ 조정 역할. 기준선(§1)은 착수·인계 때마다 다시 잰다. HQ는 상주 승인자가 아니다. 담당자는 확정된 계약·선행·검증을 확인하고 목적 release로 작업을 통합한다.
merge:request의 일반 release 경로는 GitHub 대기열에서 최신 후보의 Merge Check·병합을 직렬 처리한다. 작업자는 요청 전 precheck를 수행하고 최종 full은 release→staging에서 실행한다. 실제 활성화 상태는 릴리스 랜딩 큐에서 확인한다.
1. 기준선 (2026-09-07 실측)
아래 표는 G01 시작 당시 기록이다. 신규 v0.18.0 작업의 분기·PR base는 release/v0.18.0이며, 배포는 전환 완료 후 release → staging → main 경로를 따른다. 현재 적용 상태는 릴리스 프로세스의 상태 표에서 별도로 확인한다.
1-1. 브랜치·배포 상태
| 항목 | 값 | 비고 |
|---|---|---|
| main | 343e217a | 총괄 문서 PR #1278 머지 직후. 총괄 문서의 감사 기준 aed0d39c 이후 커밋 4개 — 전부 문서·테스트 픽스처(#1276·#1291·#1278), 제품 코드 변경 0 |
| production | 478ddf12 | = 태그 v0.17.0 (릴리스 PR #1227 머지 커밋). 실제 배포 버전 v0.17.0 |
| main ↔ production 차이 | 문서·테스트만 | 제품 diff 없음 → 지금 릴리스를 만들면 빈 릴리스 |
| 열린 PR | 없음 | #1278 은 이 문서 작업 중 머지 |
| GitHub 저장소 | private, squash·merge·rebase 모두 허용, auto-merge 꺼짐 | GitHub merge queue 미제공(private 저장소 플랜) |
| main 보호 규칙 | 규칙셋 main-protection Active (2026-09-07 오너 적용, G01 랜딩 당시에는 없었다) | 기본 브랜치 대상, PR 필수(승인 0), 필수 검사 verify·landing-queue, 강제 push·삭제 금지, bypass = Repository admin |
| production 보호 규칙 | 규칙셋 production-protection | PR 필수(승인 수 0), 필수 검사 verify, 강제 push·삭제 금지 |
GitHub Environment production | required reviewer 없음 | 릴리스 PR 머지 → 오너 클릭 없이 Production 레인 즉시 실행 |
| CI | policy-contract.yml(GitHub Full CI: scope → verify → full 레인 3잡), deploy-steps.yml(1-Production Deploy·2-Staging Deploy 가 호출)(main=staging, production=Production, ref 별 동시 실행 그룹), prod-smoke.yml, daily-data-backup.yml(매일 데이터 사본), social-login-daily-check.yml |
1-2. 진행 중인 다른 트랙 (v0.18.0 계획 ID 와의 겹침)
| 이슈 | 상태 | 브랜치 · 세션 | 겹치는 계획 ID | 처리 |
|---|---|---|---|---|
| #1277 홈 즐겨찾기 조회가 로그인 확인 실패로 간헐 실패 | [조사중] | fix/1277-auth-ready-gate · 세션 d3e6f5f2 | A07(owner·auth lifecycle), B01(인증 API) | 수리 트랙이 먼저다. 랜딩되면 A07/B01 착수 기준선에 포함. A07 담당은 이 수리가 만든 "로그인 준비 판정" 을 재구현하지 않는다 |
| #1256 반복수 투영 정본화 | 착수 조건 충족 | feat/1256-stats-reps · 세션 dd9f7df4 | D01(통계 계약), D04/D05(증분 통계), A06(통계 조회) | 통계 읽기 함수를 바꾸는 트랙. D01 착수 전 랜딩을 목표로 하고, 랜딩 전이면 D01 은 #1256 브랜치의 함수 목록을 입력으로 받는다 |
그 밖의 워크트리(git worktree list 기준 40여 개)는 이미 머지된 트랙의 잔재이며 소유권을 갖지 않는다. 새 세션은 자기 워크트리를 scratchpad 에 새로 만든다(공유 체크아웃 충돌 규칙).
1-3. 착수 때 다시 재는 법
git fetch origin
git rev-parse origin/main origin/staging origin/release/v0.18.0
# 전환 전에는 origin/production과 마지막 성공 운영 배포도 확인한다.
git tag --sort=-v:refname | head -1 # 마지막 릴리스
gh pr list --state open # 열린 PR
gh issue list --state open --limit 60 # 열린 이슈
git worktree list # 이 PC 의 진행 워크트리기준선이 총괄 문서·이 문서와 다르면 착수 댓글에 "달라진 것" 한 줄을 적고, 총괄 문서 §12 상태 칸은 HQ 가 고친다.
2. 보고서 항목 ↔ 실행 이슈 ↔ 소유
2-1. 대응표의 정본
보고서 F01~F30·F07b 와 추가 범위 C01~C08 이 어느 계획 ID 에 연결되는지는 총괄 문서 §11 이 정본이다. 여기에는 중복해서 적지 않는다. 이 절은 총괄 문서가 "선택 이유를 기록하라" 고 한 양자택일 항목 과, 게시된 이슈 번호만 보탠다.
| 보고서 | 양자택일 제안 | 선택 | 근거 | 기록 위치 |
|---|---|---|---|---|
| F07 | 안전한 자동 field merge 대 사본 + 명시 복구 | 사본 + 명시 복구 | 같은 기록을 두 기기에서 고친 경우 어느 값이 맞는지 기계가 알 수 없다. "나중 서버 도착 우선" 정책은 그대로 두고, 진 쪽 요청을 사본으로 보존해 사용자가 복구 화면에서 고르게 한다. 자동 병합은 원본을 시스템이 고치는 셈이라 원본 불변 계약 R2 와도 어긋난다 | ADR §3-3 |
| F09 | TanStack Query 도입 대 기존 store/coordinator 를 작고 typed 하게 완성 | 기존 store/coordinator 완성 | 총괄 문서 §2 의 기본안. 새 라이브러리는 G03 이 필요성을 입증할 때 한 번만 결정한다(두 방식을 같이 두지 않는다) | ADR §3-5, G03 |
| F24 | SQL 원천을 migration 안에 두기 대 도메인별 원천 파일 + migration 생성 | 도메인별 원천 + 생성기 | 적용된 migration 은 불변, 원천은 읽고 고칠 수 있어야 한다. D03 이 registry·생성·drift 검사를 만든다 | D03 |
| F30 | 오래된 문서를 그대로 두고 새 문서로 덮기 대 충돌 문장을 그 자리에서 고치기 | 그 자리에서 고치기 | 정본이 둘이면 새 세션이 옛 규칙을 따른다. 이 문서와 ADR 이 정본을 하나로 묶고, 옛 문장은 역사 표기로만 남긴다 | 이 문서 §4, ADR §4 |
2-2. 62개 작업의 소유 역할과 통합 담당
소유는 사람 이름이 아니라 역할 이다. 세션은 착수 댓글(§21 형식)에 자기 세션 ID 를 적는 순간 그 역할의 담당이 되고, 총괄 문서 §12 상태 칸에 "담당 세션" 으로 기록된다. 담당이 확정되기 전에는 아무도 이름을 추정해 적지 않는다.
| 역할 | 뜻 | 통합 책임 |
|---|---|---|
| HQ | 목표·계약·의존성·공용 파일 충돌·예외·릴리스 상태를 조율한다. 결정 기록은 하나로 유지하되 특정 세션이 켜져 있어야 진행되는 승인권으로 사용하지 않는다. 이슈 #1279 담당 세션이 Phase 1의 초기 HQ다 | 구조·범위·소유권 충돌 해결과 장부 정합. 일상적인 랜딩 요청·승인은 담당자가 수행 |
| DATA | DB 모델·쿼리·통계·migration·worker·인입 job | SQL object·번호·schema snapshot은 해당 PR 담당이 검증하고, release 통합은 §4의 로컬 검증·직렬 병합 절차로 집행 |
| DURABLE | outbox·command·dispatcher·receipt·충돌·초안·백업·복원 | pending store 최종 wiring 은 queue 담당(S01→S02→S04→S07 순서의 현재 담당) |
| APP | repository·codec·owner lifecycle·resource cache·editor·feature binding·shell·타입 | 거대 Repository/controller 최초 추출·최종 삭제는 A01/A07/A15 담당 |
| UI | tokens·primitive·mobile/desktop·responsive·CSS·가상화·bundle·UX | CSS/token 파일과 shell 최종 wiring 은 U01 계약 → U07 정리 담당 |
| PLATFORM | 인증·계정·관리 API, 빌드·의존성, iOS/Android·SW, 인입 파일 경로 | 공용 설정(package/lock/Vite/workflow)은 배정된 소유자가 변경하고 §4의 release별 직렬 병합 절차로 통합 |
| ID | 작업 | 역할 | 게시 | 소유 경계 |
|---|---|---|---|---|
| G01 | 0.18.0 범위·정책·작업 및 배포 계약 확정 | HQ | #1279 | 지시서 |
| G02 | 재현 가능한 테스트 기준선과 행동 검증 기반 | HQ(검증) | #1280 | 지시서 |
| G03 | 도메인 타입·명령·조회·통계 계약 설계 | HQ(타입 경계) | #1282 | 지시서 |
| G04 | 성능·보존 관측 기준선과 릴리즈 예산 확정 | HQ(성능·운영) | #1284 | 지시서 |
| G05 | 전체 기능·공유 계층의 커버리지와 소유권 장부 | HQ(범위 통합) | #1281 | 지시서 |
| S01 | 버전별 저장 codec와 mutation protocol 구현 | DURABLE | #1285 | 지시서 |
| S02 | Outbox 교체·합치기의 IDB 트랜잭션 원자화 | DURABLE | 미게시 | 지시서 |
| S03 | 순수 command builder와 요청 identity 통일 | DURABLE | 미게시 | 지시서 |
| S04 | 전송 중 요청 보호·탭별 claim과 후속 명령 보존 | DURABLE | 미게시 | 지시서 |
| S05 | Outbox·Dispatcher·ReceiptReconciler 책임 분리 | DURABLE | 미게시 | 지시서 |
| S06 | 충돌 재전송 요청과 복구 근거의 원자적 영속화 | DURABLE | 미게시 | 지시서 |
| S07 | Owner index·bounded mirror·IDB timeout 구현 | DURABLE | 미게시 | 지시서 |
| S08 | Draft lifecycle·Clock·checkpoint 순서 정리 | DURABLE | 미게시 | 지시서 |
| S09 | Conflict 사본 조회와 명시적 복구 command | DURABLE | 미게시 | 지시서 |
| S10 | Update·삭제·자식 전체·인입의 범위 지정 복구 엔진 | DURABLE | 미게시 | 지시서 |
| S11 | 데이터 사본 completeness·checksum·복구 manifest | DURABLE | 미게시 | 지시서 |
| D01 | 통계 계산 DAG·단일 작성자·동치 검증 계약 | DATA | #1286 | 지시서 |
| D02 | 동시 저장 generation 경합 재현과 영수증 세대 원자화 | DATA | 미게시 | 지시서 |
| D03 | SQL 도메인 원천·migration 생성·drift gate | DATA | #1283 | 지시서 |
| D04 | Dirty event의 정확한 영향 범위·세대별 병합 | DATA | 미게시 | 지시서 |
| D05 | 변경 세션 observation·기본 rollup 증분화 | DATA | 미게시 | 지시서 |
| D06 | 기간·달력 projection의 단일 작성자와 bucket 갱신 | DATA | 미게시 | 지시서 |
| D07 | PR·e1RM·최대반복수 checkpoint와 suffix 재생 | DATA | 미게시 | 지시서 |
| D08 | 사용자별 stats worker·lease·실패 복구 | DATA | #1412 · release/v0.18.0 통합 a1d462a8(2026-09-10), staging·Production 미반영(기록) | 지시서 |
| D09 | Wodup durable 소비자·lease 회수·완료 정합 | DATA | 미게시 | 지시서 |
| D10 | Repair·rollover 탐색의 index·cursor·watermark화 | DATA | 미게시 | 지시서 |
| D11 | 통계 계산 통합·동치 검증·generation publication 전환 | DATA | 미게시 | 지시서 |
| D12 | 전체 DB 모델·제약·index·대표 쿼리 품질 개선 | DATA | 미게시 | 지시서 |
| D13 | 데이터가 있는 DB의 migration·잠금·backfill 안전성 | DATA | #1287 | 지시서 |
| A01 | 공용 RPC transport와 거대 Repository 분리 경계 생성 | APP | #1288 | 지시서 |
| A02 | Workout·Plan repository와 canonical codec 분리 | APP | 미게시 | 지시서 |
| A03 | Catalog·Profile repository와 codec 분리 | APP | 미게시 | 지시서 |
| A04 | Social·Group repository와 codec 분리 | APP | 미게시 | 지시서 |
| A05 | Import·Admin repository와 codec 분리 | APP | 게시·구현 완료(#1406, release/v0.18.0 통합 4f6d193b 2026-09-10) | 지시서 |
| A06 | Stats·화면 RPC query와 codec 분리 | APP | 미게시 | 지시서 |
| A07 | Owner·Auth·Connectivity lifecycle 분리 | APP | 미게시 | 지시서 |
| A08 | Owner-scoped resource cache·typed snapshot primitive | APP | 미게시 | 지시서 |
| A09 | Workout·Plan·Catalog resource 이전과 첫 수직 통합 | APP | 미게시 | 지시서 |
| A10 | Home·Calendar·PR·Volume resource와 generation UX 이전 | APP | 미게시 | 지시서 |
| A11 | Profile·Social·Group·Import resource 이전 | APP | 미게시 | 지시서 |
| A12 | 플랫폼 공통 Workout headless editor | APP | 미게시 | 지시서 |
| A13 | 플랫폼 공통 Plan headless editor | APP | 미게시 | 지시서 |
| A14 | Canonical ID 기반 종목 이력 조회와 indexed merge | APP | #1414 · release/v0.18.0 통합 완료 209bbffd, staging 승격 대기(기록) | 지시서 |
| A15 | Feature binding 통합과 얇은 app shell 완성 | APP | 미게시 | 지시서 |
| A16 | 잔여 any·dual shape·거대 mapper 제거 완료 | APP | 미게시 | 지시서 |
| U01 | 공통 시각 token·primitive·접근성 계약 | UI | #1289 | 지시서 |
| U02 | Mobile 화면을 공통 editor·typed view model에 연결 | UI | 미게시 | 지시서 |
| U03 | Desktop 공통 editor 연결과 intrinsic responsive 전환 | UI | 미게시 | 지시서 |
| U04 | 긴 목록의 실제 viewport 가상화와 identity 계약 | UI | 미게시 | 지시서 |
| U05 | Feature import graph와 초기 bundle 비용 최적화 | UI | 미게시 | 지시서 |
| U06 | 전체 feature UX·접근성·플랫폼 일관성 검증 | UI | 미게시 | 지시서 |
| U07 | CSS cascade·scope·override·중복 코드 정리 | UI | 미게시 | 지시서 |
| B01 | 서버 API·인증·계정 연결·삭제·관리자 경계 개선 | PLATFORM | 미게시 | 지시서 |
| B02 | 웹·Edge·관리자·Native의 환경·빌드·의존성 경계 | PLATFORM | 미게시 | 지시서 |
| N01 | iOS·Android bridge·생애주기·SW 업데이트 개선 | PLATFORM | 미게시 | 지시서 |
| I01 | 전체 인입·파일 parser·identity·부분 실패 경로 개선 | PLATFORM | 미게시 | 지시서 |
| R01 | 구현 이식 종료·퇴역 코드·테스트·문서 정리 | HQ | 미게시 | 지시서 |
| R02 | 구·신 앱/서버/IDB 호환과 저장 장애 통합 검증 | HQ | 미게시 | 지시서 |
| R03 | 실제 사본 기반 선택 복구·인입 복원 리허설 | HQ | 미게시 | 지시서 |
| R04 | 혼합 부하·장기 이력·UI/저장 성능 검증 | HQ | 미게시 | 지시서 |
| R05 | 0.18.0 스테이징 전체 릴리즈 리허설과 후보 확정 | HQ | 미게시 | 지시서 |
| R06 | v0.18.0 production 릴리즈와 검증 종료 | HQ | 미게시 | 지시서 |
미게시 51개는 계획 ID 로 추적하고, HQ 가 선행 merge·계약 고정·소유권 확보를 확인한 뒤 게시한다. 게시 = 착수 아님(§5 Ready 판정).
3. 공용 파일·DB object 의 단일 통합 담당
"통합 담당"은 그 자원의 계약과 최종 export/wiring/생성 결과를 책임지는 역할이다. GitHub 머지 버튼을 누르는 유일한 세션이라는 뜻이 아니다. 다른 담당은 새 목적지 모듈을 만들고, 공용 자원의 변경 순서를 합의해 자기 PR에 반영한다. 병합은 §4의 목적 release별 로컬 검증·직렬 통합 절차를 따른다. 같은 공용 파일의 변경이 겹치면 뒤 PR 담당자가 최신 목적 release를 반영하고 관련 검증을 다시 수행한다.
| 공용 자원 | 지금 파일 | 분리 경계를 먼저 만드는 담당 | 새 목적지 구현 | 통합 담당(최종 병합) |
|---|---|---|---|---|
| 앱 컨트롤러·원격 데이터 컨트롤러 | src/react/appController.tsx, src/react/controllers/remoteDataController*.ts | A01(분리 경계) → A07(lifecycle) | feature 담당(A09~A14) | A15(얇은 shell 완성) — 그 전까지는 A01/A07 담당 |
| 거대 Repository | src/react/services/barbelicRepository.ts | A01(transport·경계) | A02~A06(도메인별 repository) | A01 담당이 최종 export 정리, A16 이 잔여 제거 |
| pending store·IDB 대기열 | src/react/services/pendingWorkoutSaves.ts, pendingWorkoutMutationFlush.ts, src/react/controllers/pendingWorkoutSavesStore.ts | S01(codec·protocol) | S02→S04→S07 순서로 같은 담당 계열 | queue 담당(현재 S 순서의 담당). S05/S06 은 순서대로 합류 |
| 타입·DTO·계약 | src/react/contracts/**, src/react/types/** | G03 | feature 담당은 좁은 port 만 추가 | G03(HQ 타입 경계) |
| SQL object(함수·정책·트리거·뷰) | supabase/definitions/<domain>/**(D03 이 만듦) | D03(registry·생성기) | 각 도메인 담당(D02·D04~D12·S10) | 도메인 담당이 object·번호·schema.sql을 검증하고 자동 큐에 landing 요청 |
| migration 번호·schema snapshot·배포 manifest | supabase/migrations/**, supabase/schema.sql, src/react/services/deploymentManifest.ts | — | 해당 PR 담당이 생성·검증 | 랜딩 절차 + §4의 release별 직렬 통합. 목적 release의 번호 순서를 검증하고 승격 전 main/staging·실제 장부도 대조한다. 기존 renumber 도구의 main 기본값을 release 기준으로 오인하지 않는다 |
| migration 실행·검증 도구 | scripts/migrations/**, supabase/tests/** | D13 | — | D13 |
| CSS scope·token | src/react/ui/shared/** tokens, src/react/ui/{mobile,desktop}/** CSS | U01(계약) | U02/U03(표현) | U01 → U07(정리) → U04 변경은 U06 까지 검증 |
| package.json/lock·Vite 설정·app entry·workflow | package.json, package-lock.json, vite*.config.mjs, index.html, .github/workflows/** | B02(환경 경계) | 필요한 담당이 PR 본문에 sentinel 사유 기재(branch-workflow §sentinel) | 배정된 소유자가 검증하고 §4 자동 큐에서 통합. 기존 작업 승인 범위면 HQ 재승인 불필요 |
| 테스트 감사 manifest | tests/audit/manifest.json | — | 담당은 pending-changes.json 에 신고만 | 감사자(G02 담당) |
| 총괄 문서·이 문서·ADR | docs/updates/2026-09-07-…roadmap.md, docs/process/v0-18-0-hq-operations.md, docs/contracts/v0-18-0-adr.md | — | 담당은 갱신안을 이슈 댓글로 | HQ |
| 관리자 셸 | src/react/features/admin/**, controllers/admin*.ts, ui/desktop/screens/DesktopAdmin*.tsx, vite/admin/** | B01(관리자 API 경계) | A05(Admin repository) | B01 — 공개 시점은 §4-5 관리자 게이트 |
4. 병합 큐·스테이징 슬롯·릴리스 게이트
4-1. 원칙과 적용 범위
- v0.18.0 작업은
release/v0.18.0에서 분기하고 같은 브랜치로 PR을 연다. 다른 버전 작업도 자기 release를 사용한다. 작업 통합이 곧 staging 확인이나 운영 출시가 되는 것은 아니다. - 실행 동작을 바꾸지 않는 순수 문서는 릴리스 프로세스의 예외에 따라 최신 main에서 분기해 main으로 직접 PR을 병합할 수 있다. 오너 요청 시 CI를 생략하며, 제품 코드·DB·배포/빌드 설정은 이 예외에 포함하지 않는다.
- 담당자는 소유권·직접 선행·관련 테스트와 변경에 필요한 DB/관리자 호환 증거를 준비한다. 일반 작업의 최종 full CI·병합은 GitHub가 release별 한 건씩 배정하고 self-hosted runner가 수행한다. HQ는 범위·의존성·소유권 충돌을 조정하고 일상적인 통합의 재승인자가 되지 않는다.
merge:request는 PR base에 따라 release 큐와 기존 main 경로를 구분한다. main 대상의 기존 원격 검사·squash merge·staging 확인과 복구는 마이그레이션 랜딩을 따른다. release PR을 main으로 바꿔 호출하지 않는다.
4-2. 병합 큐 — GitHub가 release별 CI·병합을 직렬 처리
- 작업 담당자가 선행·소유권·관련 검증을 완료하고 PR의 목적 release와 head를 기록한다. migration은 번호·스냅샷·위험·원본 보존 검증도 필요하다.
- clean worktree와 로컬 HEAD = PR head를 확인하고
npm run merge:request -- --pr <N>으로 요청한다. GitHub가 목적 release별 슬롯을 배정한다. 구현은 병렬로 진행해도 되고 파일landing:lock·heartbeat는 필요 없다. - self-hosted runner가 슬롯 안에서 최신 release base와 고정 PR head의 두 부모 merge commit을 만든 뒤
ci:full-local --base <고정 SHA>·docs/admin 빌드를 실행한다. head/base·라벨·clean 상태·tree를 재확인하고 예상 base일 때만 검증 commit 그대로 fast-forward push한다. CI 중 다음 release 병합은 대기한다. - GitHub PR의 merged 상태와 job summary의 PR·base/head·candidate/tree·결과를 확인한다. 중복 요청·충돌·CI 실패·실행 중 head/base 변경은 병합하지 않는다. 수정 후 재요청하며 이 시점의 성공은 통합 완료이고 staging/운영 확인 완료가 아니다.
릴리스 랜딩 큐에 runner 설치, 원격 workflow와 보호 규칙의 실제 적용 상태를 기록한다. landing:active·landing:queued 라벨이나 한 PC의 준비 잠금을 여러 PC의 병합 잠금으로 취급하지 않는다. release 업데이트는 전용 deploy key로 제한하고 force push·삭제는 별도로 보호한다. 관리자의 임의 병합이나 미실행 검사 성공 제출로 이를 대신하지 않는다.
4-3. 스테이징 통합 슬롯
공용 staging은 다음에 출시할 한 후보만 사용한다. release → staging PR에서 GitHub full CI ①을 통과한 뒤 병합하고, 전환된 배포 파이프라인이 DB → Edge → frontend → smoke를 직렬 실행한다. 현재는 아직 main push가 staging을 배포하므로 새 연결이 적용됐는지 먼저 확인한다.
실제 배포 SHA·smoke·사용자 흐름 QA를 기록한다. 실패하면 다른 릴리스를 위에 합치지 않고 해당 release의 수정 PR부터 다시 검증한다. 후보 교체는 Git 코드와 이미 적용한 DB migration 상태를 함께 정리한다. QA한 코드와 운영에 합쳐질 코드가 달라지면 다시 staging에서 확인한다.
4-4. 최종 Production 릴리스 게이트 (v0.18.0 은 한 번)
- 새 경로는
release/v0.18.0 → staging → main이다. 두 승격은 merge commit으로 이력을 보존하고, 마지막 PR 제목은[Release v0.18.0] 요약으로 작성한다. 포함 커밋·migration을 확정하여 미래 작업의 조기 포함을 막는다. - 총괄 §9의 R05 리허설·R02~R04·U06 완료 조건, 원본 보존·관리자 호환·복구 준비를 그대로 확인한다. 이미 앞선 패치로 배포된 부분과 아직 미출시인 부분은 실제 배포 이력으로 구분한다.
- staging → main의 GitHub full CI ②, 동일 코드의 staging 배포·QA, 오너의 운영 반영 승인이 모두 필요하다. 최신 main에 다른 패치가 생기면 release에 반영하고 staging 승격·배포·QA부터 다시 진행한다.
- main 병합 후 운영 DB의 staging-applied·dry-run/release diff·remote-schema → Edge → frontend → smoke 순서를 유지한다. 성공한 태그·배포 SHA로 출시 완료를 기록한다.
- 실제 전환 전에 이미 승인된 기존
main → production경로의 진행 건은 이 문서로 자동 취소하거나 승인하지 않는다. 현재 workflow와 보호 규칙을 확인하고 기존 운영 승인 조건을 유지한다.
4-5. 관리자 셸 공개 게이트 (admin-hold / admin-compat-confirmed)
새 배포 경로: docs/admin도 앱과 같은 SHA·환경의 DB·Edge 이후 Actions로 배포한다. staging 관리자 셸은 staging Supabase, main의 운영 관리자 셸은 Production Supabase를 본다. 아래 관리자 호환 게이트는 유지하며, 일반 release 병합만으로 공개됐다고 기록하지 않는다. 실제 전환 상태는 릴리스 프로세스를 따른다.
도입 배경: 전환 전에는 관리자 화면(/admin/)을 barbelic-docs 프로젝트가 main 푸시마다 먼저 빌드·배포했다. 앱과 배포 시점이 달라 main의 공용 코드가 Production DB에 아직 없는 함수를 부르면 관리자 화면이 먼저 깨질 수 있었다. 새 배포 경로와 대상 전달은 배포 파이프라인 "관리자 셸"을 따른다.
관리자 셸 경로(감시 대상): src/react/features/admin/**, src/react/controllers/admin*.ts, src/react/ui/desktop/screens/DesktopAdmin*.tsx, src/react/vite/admin/**, src/react/services/adminExerciseCatalog*.ts, admin/**, vite.admin.config.mjs. 관리자 셸이 부르는 서버 함수(2026-09-07 실측 15개): admin_catalog_write·admin_confirm·admin_create·admin_create_catalog_exercise_with_mapping·admin_delete_exercise_synonym_v1·admin_delete_performance_detail·admin_health·admin_rename_performance_detail·admin_resolve_content_report_v1·admin_search_users_v1·admin_set_default_exercise_synonym_v1·admin_set_user_suspension_v1·admin_update·mark_wodup_import_batch_failed_v1·mark_wodup_import_batch_uploaded_v1 + 공용 barbelicApi/barbelicViewMappers 가 부르는 조회.
규칙:
| 상황 | 라벨 | 뜻 |
|---|---|---|
| PR 이 관리자 셸 경로와 새 마이그레이션을 함께 바꾼다 | admin-hold | 관리자 화면이 새 함수에 의존한다. 필요하면 서버 변경과 관리자 공개를 별도 PR로 나눈다. 릴리스가 나가 Production에 필요한 마이그레이션이 적용된 뒤 담당자가 근거를 남기고 라벨을 해제한다. 그 전에는 검사가 빨간불 |
| 같은 상황이지만 관리자 셸은 Production 에 이미 있는 함수만 쓴다(마이그레이션은 앱 전용) | admin-compat-confirmed | 담당자가 PR 본문에 근거(어느 함수를 쓰고 그것이 Production에 있는 이유)를 남기고 붙인다. HQ의 별도 승인이 아니라 호환 검증 결과다 |
| 관리자 셸만 바꾸고 마이그레이션이 없다 | 라벨 없음 | 일반 제품 변경과 같은 작업→release→staging→main 경로 및 환경별 DB·Edge 이후 배포 |
공용 서비스(src/react/services/**)를 바꾸고 관리자 셸이 그것을 import 한다 | 담당자가 호환 판정, 계약 충돌만 HQ 조율 | 관리자 번들에 실리는 공용 코드가 새 함수를 부르면 admin-hold. 담당은 PR 본문 "호환 영향"에 관리자 번들 영향을 적는다 |
순수 Markdown은 오너가 요청한 문서 예외로 main에 직접 합치고 CI·배포를 생략할 수 있다. 이 경우 공개 문서 사이트는 다음 해당 환경 배포에서 갱신된다. 관리자 코드 변경에는 순수 문서 예외를 적용하지 않는다.
4-6. 배포 경로 정본 (문서 간 충돌 해소 결과)
브랜치·CI·승격의 단일 정본은 릴리스 프로세스다. 아래처럼 정책과 현재 연결을 구분한다.
| 경로 | 전환 후 동작 | 현재 설정과의 차이 |
|---|---|---|
| 작업 → release | GitHub 큐 → self-hosted full 로컬 CI·docs/admin → 검증 commit 직렬 병합, 배포 없음 | 실제 큐 검증 완료. release별 CI·병합 슬롯을 유지하며 승격·배포 락을 추가하지 않음 |
| release → staging | 최신 base의 full CI ① → 병합 → staging 배포·QA | 전환 코드 준비; main 설치·활성화·실제 배포 검증은 상태 표 확인 |
| staging → main | 최신 base의 full CI ②·QA·운영 승인 → 운영 배포 | 전환 코드 준비; 별도 promotion 큐·전역 락 없음 |
| docs/admin | 같은 SHA·환경의 DB·Edge 이후 앱과 함께 Actions 배포 | 앱·docs main/staging Vercel 환경 설정 확인. 원격 활성화·실제 배포 검증은 미완료 |
과거 문서의 main=staging 표기는 전환 전 구현이나 당시 이력으로만 보존한다. 사용자 결정만으로 workflow·환경·ruleset이 바뀐 것으로 적지 않는다.
5. Ready 판정과 인계
5-1. 상태와 Ready 조건
총괄 문서 §7 의 상태(Planned → Contract-ready → Ready → In progress → Review → Merged → Staging verified → Release verified)를 쓴다. GitHub 의 open/closed 로 대신하지 않는다.
| 상태 | 조건 | 누가 판정 |
|---|---|---|
| Contract-ready | 이 작업이 소비하는 계약(§2·ADR·G03 타입 계약 등)이 목적 release에 포함돼 있고 계약 버전이 적혀 있다 | 담당자가 증거로 확인. 계약 충돌만 HQ 조율 |
| Ready | ① 직접 선행 전부의 merged SHA 를 확인했다(closed 표시가 아니라 git merge-base --is-ancestor <sha> origin/release/vX.Y.Z) ② 필요한 계약이 Contract-ready ③ §3 의 공용 자원 중 이 작업이 만질 것의 통합 담당이 정해져 있고, 같은 자원을 만지는 다른 In progress 작업이 없거나 순서가 합의됐다 ④ 소유 경계 밖 파일이 필요하면 HQ 배정을 받았다 ⑤ Phase 1은 앞 스텝 전체의 완료·검증·병합을 확인했다 | 담당자가 근거를 이슈에 남기고 착수. HQ는 장부 정합과 충돌을 관리하며 기록 반영을 기다리게 하지 않음 |
| In progress | 담당 세션이 §21 형식 "작업 이어받았습니다/착수" 댓글(세션 ID·트랜스크립트·시작 지점·실제 수정 파일·새 목적지·계약 버전)을 남기고 세션 제목을 #N [진행중 0/M] … 으로 바꿨다 | 담당 세션 |
| Review | PR 열림. 본문에 base/head SHA·실행 명령·환경·결과·미실행과 이유·호환 영향 | 담당 세션 |
| Merged | 목적 release에 §4-2 큐를 통해 검증 commit이 병합됐고 GitHub PR merged 상태를 확인했다 | Actions 결과 / 담당 확인 |
| Staging verified | 그 커밋의 deploy-steps.yml(1-Production Deploy·2-Staging Deploy 가 호출) staging 레인 초록 + 작업이 정한 staging 확인(프로브·e2e) | 담당 세션이 증거, HQ 가 기록 |
| Release verified | R06 뒤 Production 확인 | R06 |
착수 댓글은 코드를 만지기 전에 남긴다. 착수 댓글에 적은 "실제 수정 파일" 밖으로 나가야 하면 댓글을 갱신하고 공용 파일이면 HQ 배정을 받는다.
5-2. 이 문서가 넘기는 것 (G01 → 후속)
| 받는 작업 | 이 문서·ADR 에서 확정된 것(기다릴 필요 없음) | 그 작업이 스스로 만들어야 하는 것 |
|---|---|---|
| G02 (#1280) | 소유 경계 tests/**·pending-changes.json·.gitattributes·scripts/**(§2-2). 검증 층 표(총괄 §9). 이 문서가 남긴 앵커 테스트 5파일은 그대로 유효 | Clock/UUID/scheduler 주입, LF/CRLF 정책, fault/barrier/oracle 도구. PR #1278 이 이미 고친 workoutDraftArchive 픽스처는 재구현하지 않는다 |
| G05 (#1281) | 62개 소유 역할·공용 자원 통합 담당(§2-2·§3)이 초기 소유권 이다. G05 가 feature×layer 목록으로 정밀화하되 §3 의 통합 담당은 바꾸지 않는다(바꾸려면 HQ 합의) | route/feature/controller/repository/RPC/table/CSS/native/job/build 목록과 장부, 계약 변경 통지 절차 |
| G03 (#1282) | ADR §3-2·§3-5(typed 경계·기존 store 완성)·P1 명령별 capability. docs/contracts/** 는 G03 과 공유 — ADR 파일은 G03 이 갱신하지 않고 새 계약 파일을 만든다 | canonical ID·단위·입력 union, Command/Receipt/Conflict/Resource/Generation 계약, 명령별 온라인·durable 정책표, 계층 의존 허용표 |
| D03 (#1283) | SQL registry 계약은 D03이, 각 PR의 migration 번호·schema snapshot 검증은 해당 담당이 책임진다(§3). 랜딩 절차 = migration-landing.md + §4-2 자동 큐 | 원천 registry·생성기·drift 검사. 번호 배정 방식을 바꾸지 않는다 |
| S01·S02·S04·S06·S09 | ADR §3-1(claim·fence·successor)·§3-3(사본+복구)·활성 조건(S01 공존 실험 → R02) | 실제 codec·트랜잭션·claim 구현과 공존 실험 결과 |
| D01·D04~D11 | ADR §3-4(단일 작성자·generation·동치 검증), P2(수치 정책 불변) | DAG·작성자 표·fixture·전환 |
| 모든 마이그레이션 PR | §4-2 큐·§4-3 슬롯, 관리자 게이트 §4-5 | — |
5-3. 인계
HQ 조정 역할이 바뀌면 이 문서 §1 기준선을 다시 재고, 이슈 #1279 (또는 당시 HQ 이슈)에 §21 형식 댓글을 남긴다. 담당자는 진행·계약·검증 증거와 문서 갱신안을 자기 이슈/PR에 기록하고, HQ는 총괄 상태와 모순되는 결정을 정리한다. HQ가 오프라인이라는 이유로 이미 확정된 계약의 착수·자동 랜딩·실패 복구를 보류하지 않는다. 실제 소유권·계약 충돌이나 오너 승인 범주만 미해결로 남긴다.
6. 오너 손이 필요한 것
아래 표는 전환 전 설정과 2026-09-07 확인 기록이다. 새 프로세스에서는 릴리스 프로세스의 전환 목록에 따라 workflow와 required checks를 함께 바꾸고, staging/main에 최신 base와 승격 검증을 요구한다. 문서 작업으로 유료 설정이나 승인 단계를 추가하지 않는다.
| # | 설정 | 지금 | 켜면 달라지는 것 | 어디서 |
|---|---|---|---|---|
| O1 | main 브랜치 보호 규칙: PR 필수(승인 수 0), 필수 검사 verify + landing-queue, 강제 push 금지 | 적용됨 (2026-09-07, 규칙셋 main-protection) | verify와 관리자 호환 검사를 필수로 유지. 큐 대상 PR은 §4-2 Actions가 별도로 최신 head/main·배포 순서를 검사한다. 옛 랜딩 라벨은 승인 조건이 아님 | Settings → Rules → Rulesets → main-protection |
| O2 | GitHub Environment Production 에 required reviewer = 오너 | 없음 — 릴리스 PR 머지 즉시 Production 배포 시작. 설정 화면에 항목 자체가 없다: 배포 보호 규칙(Required reviewers·Wait timer)은 private 저장소에서 GitHub Pro/Team/Enterprise 플랜에만 제공된다(Free 플랜 private 저장소는 환경·시크릿·변수만). 이 저장소는 private·Free | 릴리스마다 Actions 화면에서 승인 클릭 1회. 머지와 배포 사이에 마지막 확인 단계가 생긴다 | 유료 전환 시: Settings → Environments → Production → Required reviewers. 전환하지 않는 동안은 §4-4 의 규칙(릴리스 PR 은 오너만 머지 = 머지가 승인)이 그 자리를 대신한다 — 비용 결정은 오너 몫 |
O2가 없는 동안의 규칙: 릴리스 PR은 오너만 머지한다(§4-4). O1은 적용됐으므로 landing-queue·verify 빨간불은 머지를 막는다. 관리자 권한이 있어도 실패한 검사를 우회해 큐 대상 PR을 머지하지 않는다. 라벨 승인 폐지는 검증·데이터 보존·Production 승인 조건의 완화가 아니다.