From 2eed4e492c67464e85d616d7e9393afea0f1df22 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Fri, 31 Jul 2026 01:51:31 +0000
Subject: [PATCH] =?UTF-8?q?docs:=20add=20deploy/residual=20checklist=20(N1?=
 =?UTF-8?q?=E2=80=93N5)=20after=20Phase=201=20A=E2=80=93C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Consolidate Claude + Cursor DONE state and the next execution track
(smoke → Docker msn.iykyka.com → stabilize → FCM/Android QA → human PoC).
Sync stale PLANNING Q1–Q7/stack status and point AGENTS/README/CLAUDE/roadmap
at docs/deploy-checklist.md.

Co-authored-by: okuma <o0kuma@users.noreply.github.com>
---
 AGENTS.md                |  21 +++++
 CLAUDE.md                |   9 +-
 README.md                |   6 +-
 docs/PLANNING.md         |  31 ++++---
 docs/deploy-checklist.md | 183 +++++++++++++++++++++++++++++++++++++++
 docs/roadmap.md          |   9 ++
 scripts/push-both.sh     |   4 +-
 7 files changed, 245 insertions(+), 18 deletions(-)
 create mode 100644 docs/deploy-checklist.md

diff --git a/AGENTS.md b/AGENTS.md
index 943885d..31f938b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -90,6 +90,9 @@ changes it.
 
 - Before starting any Phase 1 app-build task, check `docs/roadmap.md`'s
   "Phase 1 상세 작업 분해" checklist for what's already done and what's next.
+- After Phase 1 A~C, use [`docs/deploy-checklist.md`](docs/deploy-checklist.md)
+  (N1→N5) for smoke, Docker deploy, stabilize, FCM/Android QA, then human PoC.
+  Keep that file and `roadmap.md` in sync when status changes.
 - Follow the "권장 착수 순서" there — don't skip ahead in the numbered order
   without a reason, and note the reason in the checklist if you do.
 - When a task is finished, check it off in that same checklist. When you
@@ -113,6 +116,24 @@ Do not invent frameworks, folder layouts, or CI conventions beyond what
   in sync.
 - Prefer updating existing docs over creating parallel overlapping docs.
 
+## Git remotes & branch policy (Master)
+
+Master policy for this repo — follow even when a cloud agent default suggests
+feature branches or a non-`main` base:
+
+1. **Work on `main`.** Commit and land changes on `main` (fast-forward or merge
+   into `main`). Do not leave finished work only on long-lived side branches
+   unless Master explicitly asks for a temporary branch.
+2. **Dual remote sync after every `main` update.**
+   - `origin` = GitHub `o0kuma/hikikomori`
+   - `gitea` = Gitea `gitea.iykyka.com/oh/iykyka` (iykyka)
+   - Push both: `./scripts/push-both.sh main` (or `git push origin main` then
+     `git push gitea main`).
+3. Never commit secrets (tokens, API keys). Gitea/GitHub credentials stay in
+   local/env only.
+4. If a PR was opened for tooling reasons, merge it into `main` and dual-push;
+   then close the PR. Keep `gitea/main` even with `origin/main`.
+
 ## Communication with agents
 
 - Read the relevant docs before proposing product/tech changes.
diff --git a/CLAUDE.md b/CLAUDE.md
index 87b74ca..24010e8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,13 +4,18 @@ Follow the project instructions in [@AGENTS.md](./AGENTS.md).
 
 Quick context:
 
-- Phase 1 A~C are in place (`core-backend/`, `ai-service/`, `mobile/`). Next is
-  **D — human PoC** (`docs/roadmap.md`). Do not start PoC early or invent §3 defaults.
+- Phase 1 A~C are in place (`core-backend/`, `ai-service/`, `mobile/`).
+  **Next execution track:** N1 smoke → N2 Docker (`msn.iykyka.com`) → N3 stabilize →
+  N4 FCM/Android QA → **N5 / D human PoC last** — see
+  [`docs/deploy-checklist.md`](./docs/deploy-checklist.md). Do not start human PoC
+  early or invent Phase 1 §3 defaults.
 - Working product name: **와카뷰** (가칭 확정).
 - Source of decisions: `docs/decision-log.md` (Q1~Q7 **확정**; PoC sub-questions open).
 - v1 scope: self-app closed beta, L0~L2, 읽씹 종결 + 단톡 따라잡기, Android first.
 - Hard bans for v1: L3/L4, OS-layer over third-party messengers, B2B.
 - Never weaken escalation, twin badge, peer veto, or undo.
+- **Git:** work and land on `main`; after each push to GitHub `origin`, also push
+  `main` to Gitea `gitea` (`scripts/push-both.sh`). See `AGENTS.md`.
 
 Before changing product or technical direction, read `AGENTS.md` and the
 relevant files under `docs/`.
diff --git a/README.md b/README.md
index 6e86333..8c33bac 100644
--- a/README.md
+++ b/README.md
@@ -18,17 +18,21 @@
 - 기획: [`docs/PLANNING.md`](./docs/PLANNING.md) · 결정: [`docs/decision-log.md`](./docs/decision-log.md) (Q1~Q7 **확정**)
 - Vision / PRD / 기술설계: [`docs/vision.md`](./docs/vision.md) · [`docs/PRD.md`](./docs/PRD.md) · [`docs/tech-design.md`](./docs/tech-design.md)
 - 로드맵 (작업 체크리스트): [`docs/roadmap.md`](./docs/roadmap.md)
+- **배포·잔여 실행 트랙:** [`docs/deploy-checklist.md`](./docs/deploy-checklist.md) (N1 스모크 → N2 Docker → … → N5 사람 PoC)
 - 베타 직전(C): [`docs/invite-ops.md`](./docs/invite-ops.md) · [`docs/android-release.md`](./docs/android-release.md) · [`docs/prototype.md`](./docs/prototype.md)
 - PoC 계획/준비물: [`docs/poc-plan.md`](./docs/poc-plan.md) · [`docs/poc-materials.md`](./docs/poc-materials.md)
 
 ## AI 에이전트 규칙
 
 - [`AGENTS.md`](./AGENTS.md) · [`CLAUDE.md`](./CLAUDE.md)
+- **브랜치:** 작업·머지는 항상 `main`
+- **리모트:** GitHub `origin` + Gitea `gitea`(iykyka) — `main` 갱신 후 `./scripts/push-both.sh`
 
 ## 현재 단계
 
 - Phase 1 **A~C**까지 반영됨 (서버·Flutter·베타 직전 문서/배포 경로)
-- 다음: **D — 사람 PoC #1/#3·Q3 인터뷰** (`docs/roadmap.md` §3, 맨 마지막)
+- **다음:** [`docs/deploy-checklist.md`](./docs/deploy-checklist.md) — N1 스모크 → N2 `msn.iykyka.com` Docker → N3 안정화 → N4 FCM/Android QA
+- **맨 마지막:** N5 / D — 사람 PoC #1/#3·Q3 인터뷰 (`docs/roadmap.md` §3). §3 기본값 추측 금지
 - 프로토타입 공유 URL은 [`docs/prototype.md`](./docs/prototype.md)의 `SHARE_URL`에 Master가 기입
 
 ## 로컬 실행 (요약)
diff --git a/docs/PLANNING.md b/docs/PLANNING.md
index f368ba0..e359cf1 100644
--- a/docs/PLANNING.md
+++ b/docs/PLANNING.md
@@ -29,18 +29,18 @@
 ## 2. 먼저 확정해야 할 결정 (회의 Q1~Q7)
 
 기능 명세를 쓰기 전에 아래 표를 채운다. 답이 안 나온 항목은 "보류 사유"를 적어두고 다음 회의 안건으로 남긴다.
-현재 작업용 답은 [`decision-log.md`](./decision-log.md)에 있으며, 상태는 모두 **제안(잠정)** 이다.
-회의에서 정식 확정되기 전까지는 decision-log를 단일 기준으로 따른다.
+현재 답은 [`decision-log.md`](./decision-log.md)에 있으며, **Q1~Q7은 Phase 1 C에서 확정**(2026-07-30).
+PoC 의존 하위 질문(자율성 기본값 등)만 열려 있다 — decision-log를 단일 기준으로 따른다.
 
-| # | 질문 | 잠정 결정 | 상태 |
+| # | 질문 | 결정 | 상태 |
 |---|------|------|------|
-| Q1 | AI 와카뷰로 확정? | 예 | 제안 — 근거는 `decision-log.md` |
-| Q2 | 타깃: 대중 vs 회사? | 대중 우선 (B2B는 이후) | 제안 |
-| Q3 | 자율성 몇 단계까지 출시? | L0~L2만 | 제안 |
-| Q4 | 사칭 우려 대응 충분한가? | 1차 설계는 충분, 실사용 검증 필요 | 제안 |
-| Q5 | MVP 데모 시나리오 1개는? | 읽씹 종결 + 단톡 따라잡기 (묶음) | 제안 |
-| Q6 | 서비스 이름 | "와카뷰" (가칭) | 제안 (가칭) |
-| Q7 | 자체 앱 vs OS 레이어 시작점 | 자체 앱 클로즈드 베타 먼저 → OS 레이어는 이후 | 제안 |
+| Q1 | AI 와카뷰로 확정? | 예 | **확정** — `decision-log.md` |
+| Q2 | 타깃: 대중 vs 회사? | 대중 우선 (B2B는 이후) | **확정** |
+| Q3 | 자율성 몇 단계까지 출시? | L0~L2만 (시작 기본값은 PoC 후) | **확정** (하위 기본값은 열림) |
+| Q4 | 사칭 우려 대응 충분한가? | 1차 설계는 충분, 실사용 검증 필요 | **확정** (실사용은 PoC) |
+| Q5 | MVP 데모 시나리오 1개는? | 읽씹 종결 + 단톡 따라잡기 (묶음) | **확정** |
+| Q6 | 서비스 이름 | "와카뷰 (Ykavu)" | **확정** (2026-07-31 명칭 변경) |
+| Q7 | 자체 앱 vs OS 레이어 시작점 | 자체 앱 클로즈드 베타 먼저 → OS 레이어는 이후 | **확정** |
 
 ## 3. MVP 시나리오 좁히기
 
@@ -147,10 +147,13 @@
   PoC #3 역할극 자극재로 사용
 - [x] "AI 대리 응답 수용성"(Q3) 인터뷰 질문지 작성 — `user-interview-guide.md`
   (질문지만 완료. 5~10명 실제 인터뷰는 아직 미착수 — PoC#3과 이어서 진행 권장)
-- [ ] 위 인터뷰 실제 진행 (참가자 5~10명, 스크리닝 → 본 인터뷰 → 결과 반영)
+- [ ] 위 인터뷰 실제 진행 (참가자 5~10명, 스크리닝 → 본 인터뷰 → 결과 반영) — **맨 마지막(N5/D)**
 - [x] 회의 리뷰용 1페이지 요약 자료 작성 — `meeting-review-summary.md`
-- [ ] 실제 회의에서 위 요약 자료로 문서 세트 전체를 리뷰하고 Q1~Q7을 정식 확정
+- [x] Q1~Q7 정식 확정 — `decision-log.md` (Phase 1 C, 2026-07-30). PoC 의존 하위만 열림
 - [x] Phase 1(자체 앱 빌드) 상세 작업 분해 — `roadmap.md` "Phase 1 상세 작업 분해". PoC 결과
   무관 기반 작업(백엔드/클라이언트 뼈대)과 PoC 결과 필요 항목을 구분해둠
-- [ ] 기술 스택 결정 (클라이언트/백엔드/DB/메시지 릴레이/온디바이스 저장소) — `roadmap.md`
-  Phase 1 §1, 회의 필요
+- [x] 기술 스택 결정 — `tech-design.md` §8 / `roadmap.md` Phase 1 §1
+  (Flutter/Dart, Go core + Python AI, WebSocket, drift+SQLCipher; 배포 DB는
+  [`deploy-checklist.md`](./deploy-checklist.md) N2-A에서 SQLite 1차 등 운영 결정)
+- [ ] A~C 이후 실행 트랙 — [`deploy-checklist.md`](./deploy-checklist.md)
+  (N1 스모크 → N2 Docker → N3 안정화 → N4 FCM/Android QA → N5 사람 PoC)
diff --git a/docs/deploy-checklist.md b/docs/deploy-checklist.md
new file mode 100644
index 0000000..13b1b6f
--- /dev/null
+++ b/docs/deploy-checklist.md
@@ -0,0 +1,183 @@
+# 배포·잔여 작업 체크리스트 (와카뷰)
+
+Phase 1 **A~C** 이후 실행 트랙. 작업 단위를 하나씩 처리한다.
+권위 문서: [`roadmap.md`](./roadmap.md) · [`decision-log.md`](./decision-log.md) · [`AGENTS.md`](../AGENTS.md).
+
+**사람 PoC(D)와 Phase 1 §3 기본값은 맨 마지막.** 추측으로 채우지 않는다.
+
+---
+
+## 0. 통합 현황 (Claude + Cursor)
+
+### DONE — Claude (`claude/project-planning-approach-ukdz31` 계열)
+
+- [x] 기획 문서 세트 (`PLANNING`, vision/PRD/tech-design/risk/roadmap, decision-log 초안)
+- [x] PoC #1/#3 계획·모집/역할극 자료·Q3 인터뷰 가이드·프로토타입 앵커
+- [x] `poc/tone-corpus/` 파이프라인 (전처리·draft·escalation·retrieve·blind_eval)
+- [x] 스택 확정: Flutter + Go core + Python AI
+- [x] `core-backend/` · `ai-service/` · 하드게이트·거부권·초대·되돌리기·L0~L2 QA
+- [x] Flutter UI 테마 폴리시 (`app_theme` + 화면별 시각 개선)
+
+### DONE — Cursor 후속
+
+- [x] A1/A2 API · A3 Flutter 메신저 연결 · API E2E (`scripts/e2e_a3.py`)
+- [x] Phase 1 B (drift/SQLCipher, FCM 골격, sessions, metrics, data-flow, identity)
+- [x] Phase 1 C (Q1~Q7 **확정**, invite-ops, Android release 경로)
+- [x] Flutter Web SQLCipher stub · Twin Shadow UI · CORS · `DEMO-BUNSIN`
+- [x] GitHub + Gitea 듀얼 리모트 (`scripts/push-both.sh`)
+
+### NOW
+
+- 앱 코드는 클로즈드 베타 직전 수준
+- **프로덕션 Docker / `msn.iykyka.com` 배포는 미착수**
+- 실 FCM · Android UI 수동 QA · 사람 PoC 실행은 남음
+
+### NEXT 순서
+
+```
+N1 스모크 → N2 Docker(msn.iykyka.com) → N3 배포 안정화
+         → N4 FCM·Android QA 등 → N5 사람 PoC(D) → 실제 베타 오픈
+```
+
+### LOCKED
+
+- [ ] Phase 2+ (L3 / OS 레이어 / L4 / B2B) — Phase 1 게이트 전 구현 금지
+- [ ] PoC §3 기본값(자율성 시작 레벨, 화이트리스트 기본 주제, 신뢰 UX 최종 카피) 추측 금지
+
+---
+
+## 항목 템플릿
+
+각 ID를 처리할 때 아래로 상태를 갱신한다.
+
+```text
+Status: todo | doing | done | blocked
+Depends on:
+Acceptance: (체크리스트)
+Notes:
+```
+
+---
+
+## N1 — 배포 전 스모크
+
+| ID | 작업 | Status | 완료 조건 |
+|----|------|--------|-----------|
+| **N1-1** | 서비스 기동 | todo | `8080` core-backend, `8001` ai-service, (옵션) `5555` Flutter web 헬스 OK |
+| **N1-2** | API E2E | todo | `ADMIN_API_TOKEN` 설정 후 `python3 scripts/e2e_a3.py` 16/16 |
+| **N1-3** | Web 가입 스모크 | todo | `DEMO-BUNSIN` → 표시명 → 가입 → 세션/다음 화면 |
+| **N1-4** | 말투 온보딩 스모크 | todo | 샘플 저장 또는 스킵 후 대화 목록 진입 |
+| **N1-5** | 핵심 메신저 스모크 | todo | 연락처·대화·메시지 또는 초안/L1 중 최소 1경로 UI 왕복 |
+| **N1-6** | 프로덕션 CORS/API 메모 | todo | `msn.iykyka.com`용 origins / `CORE_API_BASE` 변경 목록 작성 |
+
+로컬 포트 참고: 앱 **5555**, 코어 **8080**, AI **8001**. Dart VM Service 고포트(예: 39369)는 디버그용 — 무시 가능.
+
+---
+
+## N2 — Docker 배포 (`https://msn.iykyka.com`) — Plan A
+
+### N2-A. 착수 전 결정 (Master 확인)
+
+| ID | 결정 | 제안 기본값 | Status |
+|----|------|-------------|--------|
+| **N2-A1** | 구 Node MSN 교체 | 교체(Plan A) | todo |
+| **N2-A2** | DB | 1차 SQLite 파일 볼륨 (PostgreSQL은 이후) | todo |
+| **N2-A3** | AI 서비스 노출 | 내부망만 (외부 포트 미공개) | todo |
+| **N2-A4** | 클라이언트 제공 | Web 컨테이너 ± 내부 APK (둘 다/웹만 결정) | todo |
+| **N2-A5** | 시크릿 관리 | Portainer/호스트 env — **git 금지** | todo |
+| **N2-A6** | 데모 초대 | 프로덕션 `ALLOW_DEMO_INVITE` on/off | todo |
+
+### N2-B. 이미지·compose
+
+| ID | 작업 | Status | 완료 조건 |
+|----|------|--------|-----------|
+| **N2-B1** | `core-backend` Dockerfile | todo | `docker build` 성공, migrate/기동 |
+| **N2-B2** | `ai-service` Dockerfile | todo | `docker build` 성공 |
+| **N2-B3** | Flutter web 빌드/서빙 | todo | `flutter build web` + nginx(또는 Caddy)로 `/` 로딩 |
+| **N2-B4** | `docker-compose.yml` | todo | `up` 후 서비스 healthy |
+| **N2-B5** | env 템플릿 | todo | `.env.example`에 키만: `GEMINI_API_KEY`, `ADMIN_API_TOKEN`, `AI_SERVICE_URL`, DB, `ALLOW_DEMO_INVITE`, CORS/origins, `FCM_*` |
+| **N2-B6** | 데이터 볼륨 | todo | 재시작 후 SQLite(및 필요 경로) 유지 |
+| **N2-B7** | 내부 DNS | todo | Go → `http://ai-service:…` draft/escalate 동작 |
+| **N2-B8** | CORS + API base | todo | `https://msn.iykyka.com`에서 브라우저 가입 성공 |
+| **N2-B9** | 리버스 프록시 | todo | HTTPS로 도메인 접속 |
+| **N2-B10** | Portainer 스택 | todo | 스택 Up, 절차를 Notes에 기록 |
+| **N2-B11** | 구 MSN 컷오버 | todo | 새 스택이 도메인 응답 + 롤백 메모 |
+| **N2-B12** | 배포 스모크 | todo | N1-3~N1-5를 프로덕션 URL로 재실행 |
+| **N2-B13** | 운영 runbook | todo | 로그·재시작·SQLite 백업·초대 발급 1페이지 (`docs/` 또는 본 파일 Notes) |
+
+관련: Portainer `https://portainer.iykyka.com/`, 호스트 SSH는 인프라 메모 참고(시크릿은 커밋 금지).
+
+---
+
+## N3 — 배포 직후 안정화
+
+| ID | 작업 | Status | 완료 조건 |
+|----|------|--------|-----------|
+| **N3-1** | 헬스/로그 | todo | OOM·CORS·502 없음 |
+| **N3-2** | 초대 발급 리허설 | todo | `docs/invite-ops.md` 절차 1회 |
+| **N3-3** | admin metrics | todo | `/admin/metrics`·`/admin/dashboard` 토큰 조회 |
+| **N3-4** | Gemini | todo | draft 1회 실호출 또는 mock 정책 명시 |
+| **N3-5** | 백업 리허설 | todo | SQLite 볼륨 복사/복구 1회 |
+| **N3-6** | 테스터 안내 | todo | URL + 초대(`DEMO-BUNSIN` 또는 개인 코드) + 주의사항 |
+
+---
+
+## N4 — 베타 품질 잔여
+
+### FCM
+
+| ID | 작업 | Status | 완료 조건 |
+|----|------|--------|-----------|
+| **N4-1** | Firebase + `google-services.json` | todo | Android 앱 연결 |
+| **N4-2** | 실 FCM registration token | todo | install-id 플레이스홀더 제거 |
+| **N4-3** | 서버 FCM 자격증명 | todo | env만 (`FCM_SERVER_KEY` 또는 HTTP v1) |
+| **N4-4** | 푸시 수신 | todo | `/admin/push-test` + 에스컬레이션 수신 |
+
+### Android UI 탭 (`mobile/README.md`)
+
+| ID | 작업 | Status |
+|----|------|--------|
+| **N4-5** | 가입 → 말투 저장 | todo |
+| **N4-6** | 연락처 → 대화 → 메시지·히스토리 | todo |
+| **N4-7** | L1 초안 수정/버리기/승인·뱃지 | todo |
+| **N4-8** | 에스컬레이션 → 사후알림 함 | todo |
+| **N4-9** | 되돌리기·거부권 | todo |
+| **N4-10** | 자율성 L0~L2 + 화이트리스트 | todo |
+
+### 후순위
+
+| ID | 작업 | Status | 비고 |
+|----|------|--------|------|
+| **N4-11** | 오프라인 메시지 큐 | todo | 멀티디바이스 고도화 |
+| **N4-12** | 자연스러움 피드백 UI | todo | vision 지표 |
+| **N4-13** | `prototype.md` `SHARE_URL` | todo | Master 기입 |
+| **N4-14** | 내부 release APK | todo | `docs/android-release.md` |
+| **N4-15** | roadmap/`[~]` 동기화 | todo | 완료 시 체크 |
+
+---
+
+## N5 — 사람 PoC (D) — **지금 열지 않음**
+
+N1~N4(배포·품질에 필요한 최소분) 이후에만 착수. `roadmap.md` Phase 1 §3과 동일.
+
+| ID | 작업 | Status |
+|----|------|--------|
+| **N5-1** | PoC #1/#3 참가자 모집·실행 | locked |
+| **N5-2** | Q3 인터뷰 → 자율성 기본값 | locked |
+| **N5-3** | 화이트리스트 기본 주제 | locked |
+| **N5-4** | 신뢰 UX 문구/위치 확정 | locked |
+| **N5-5** | vision 게이트 → 실제 클로즈드 베타 오픈 | locked |
+
+자료: [`poc-plan.md`](./poc-plan.md) · [`poc-materials.md`](./poc-materials.md) · [`user-interview-guide.md`](./user-interview-guide.md).
+
+---
+
+## 바로 다음 5개 (권장)
+
+1. **N2-A1~A6** 결정 체크  
+2. **N1-1~N1-5** 스모크  
+3. **N2-B1~B4** Dockerfile + compose  
+4. **N2-B8~B12** 도메인·Portainer·컷오버·스모크  
+5. **N3-6** 테스터 안내  
+
+완료 시 본 표의 Status를 `done`으로 바꾸고, [`roadmap.md`](./roadmap.md) §4/§5의 대응 `[~]`/`[ ]`도 같이 갱신한다.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 8d168ee..304ea72 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -212,10 +212,19 @@ Master 합의 착수 순서: **A → B → C → D(맨 마지막)**. E는 Phase
 
 ##### D. 맨 마지막 — 사람 PoC (지금 안 함)
 - §3 항목과 동일. A~C 완료 후에만 착수.
+  **단, 프로덕션 Docker 배포·스모크(N1~N3)는 D보다 앞** — [`deploy-checklist.md`](./deploy-checklist.md).
 
 ##### E. 베타 이후 (지금은 설계만, 구현 금지)
 - Phase 2 L3 / Phase 3 OS 레이어 / Phase 4 L4·B2B
 
+#### 6. 배포·잔여 작업 (A~C 이후 실행 트랙)
+
+단일 실행 체크리스트: **[`deploy-checklist.md`](./deploy-checklist.md)**.
+
+순서: **N1 스모크 → N2 Docker(`msn.iykyka.com`) → N3 안정화 → N4 FCM/Android QA → N5 사람 PoC(D)**.
+Claude/Cursor 통합 DONE 목록과 항목 ID(N1-1 … N5-5)는 해당 문서를 본다. 완료 시 그 문서와
+본 로드맵 §2/§5의 `[~]`/`[ ]`를 함께 갱신한다.
+
 
 ## Phase 2 — L3 확장 + 베타 확대
 
diff --git a/scripts/push-both.sh b/scripts/push-both.sh
index ef28999..7fb4fa7 100755
--- a/scripts/push-both.sh
+++ b/scripts/push-both.sh
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
-# Push main to GitHub (origin) and Gitea (gitea) remotes.
+# Push a branch to GitHub (origin) and Gitea iykyka (gitea) remotes.
+# Master policy: land work on main, then run: ./scripts/push-both.sh main
+# See AGENTS.md "Git remotes & branch policy".
 set -euo pipefail
 BRANCH="${1:-main}"
 cd "$(dirname "$0")/.."