From 8e819e593915329298d337979f948fdbe6b3b9c4 Mon Sep 17 00:00:00 2001
From: agentson <agentson@localhost>
Date: Sun, 1 Mar 2026 23:13:51 +0900
Subject: [PATCH] docs: align template/commands with docs sync gate (#364)

---
 .gitea/PULL_REQUEST_TEMPLATE.md |  7 +++++++
 docs/commands.md                | 14 ++++++++++++++
 2 files changed, 21 insertions(+)

diff --git a/.gitea/PULL_REQUEST_TEMPLATE.md b/.gitea/PULL_REQUEST_TEMPLATE.md
index 1fb6990..995ebf7 100644
--- a/.gitea/PULL_REQUEST_TEMPLATE.md
+++ b/.gitea/PULL_REQUEST_TEMPLATE.md
@@ -41,6 +41,13 @@
 - [ ] `workflow/session-handover.md` 최신 엔트리가 현재 브랜치/당일(UTC) 기준으로 갱신됨
 - 최신 handover 엔트리 heading:
 
+## Docs Sync Gate
+
+- [ ] `python3 scripts/validate_docs_sync.py` 통과
+- [ ] `README.md`/`CLAUDE.md`에 `docs/workflow.md`, `docs/commands.md` 코어 링크가 유지됨
+- [ ] 문서 링크를 절대경로(`/<path>`)로 추가하지 않음
+- [ ] `docs/commands.md` API endpoint 표에 중복 row 없음
+
 ## Runtime Evidence
 
 - 시스템 실제 구동 커맨드:
diff --git a/docs/commands.md b/docs/commands.md
index a667230..2cc3c83 100644
--- a/docs/commands.md
+++ b/docs/commands.md
@@ -21,6 +21,20 @@ python3 scripts/session_handover_check.py --strict
 
 - 실패 시 `workflow/session-handover.md` 최신 엔트리를 보강한 뒤 재실행한다.
 
+## Docs Sync Validator (Mandatory for docs changes)
+
+- 문서 변경 PR에서는 아래 명령으로 동기화 검증을 먼저 실행한다.
+
+```bash
+python3 scripts/validate_docs_sync.py
+```
+
+- 검증 실패 시 메시지 기준으로 즉시 수정한다.
+  - `absolute link is forbidden`: 문서 링크에 절대경로(`/...`) 사용
+  - `broken link`: 상대경로 링크 대상 파일/앵커 누락
+  - `missing core doc link reference`: `README.md`/`CLAUDE.md` 핵심 링크 누락
+  - `duplicated API endpoint row`: `docs/commands.md` API endpoint 표 중복 행
+
 ### tea CLI (Gitea Command Line Tool)
 
 #### ❌ TTY Error - Interactive Confirmation Fails