jihoson/The-Ouroboros
1
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align template/commands with docs sync gate (#364) #366

Merged
jihoson merged 2 commits from feature/issue-364-docs-sync-integration into feature/v3-session-policy-stream 2026-03-01 23:22:38 +09:00
Conversation 3 Commits 2 Files Changed 2 +19
agentson commented 2026-03-01 23:14:00 +09:00
Collaborator
Copy Link

Linked Issue

Summary

  • PR 템플릿에 Docs Sync Gate 체크리스트 추가
  • commands 문서에 validate_docs_sync.py 실행/실패 유형 트러블슈팅 추가
  • 기존 CI 단계(Validate docs sync)와 문서/템플릿 사용 흐름 일치화

Scope

  • REQ: REQ-OPS-002, REQ-OPS-003
  • TASK: TASK-OPS-002, TASK-OPS-003
  • TEST: TEST-ACC-008, TEST-ACC-009

Validation

  • python3 scripts/validate_docs_sync.py
  • python3 scripts/validate_ouroboros_docs.py
  • python3 scripts/validate_governance_assets.py
## Linked Issue - Closes #364 ## Summary - PR 템플릿에 Docs Sync Gate 체크리스트 추가 - commands 문서에 `validate_docs_sync.py` 실행/실패 유형 트러블슈팅 추가 - 기존 CI 단계(`Validate docs sync`)와 문서/템플릿 사용 흐름 일치화 ## Scope - REQ: `REQ-OPS-002`, `REQ-OPS-003` - TASK: `TASK-OPS-002`, `TASK-OPS-003` - TEST: `TEST-ACC-008`, `TEST-ACC-009` ## Validation - `python3 scripts/validate_docs_sync.py` - `python3 scripts/validate_ouroboros_docs.py` - `python3 scripts/validate_governance_assets.py`
agentson added 1 commit 2026-03-01 23:14:00 +09:00
docs: align template/commands with docs sync gate (#364)
All checks were successful
Gitea CI / test (push) Successful in 39s
Details
Gitea CI / test (pull_request) Successful in 33s
Details
8e819e5939
agentson commented 2026-03-01 23:16:50 +09:00
Author
Collaborator
Copy Link

코드 리뷰 — PR #366

개요

PR #365에서 추가된 validate_docs_sync.py를 PR 템플릿과 docs/commands.md에 연결하는 통합 PR. 단일 커밋, 2파일, 21 additions.

🟡 확인 필요

1. PR 템플릿 체크리스트 항목 2~4가 스크립트와 중복

현재 체크리스트:

- [ ] python3 scripts/validate_docs_sync.py 통과
- [ ] README.md/CLAUDE.md에 docs/workflow.md, docs/commands.md 코어 링크가 유지됨
- [ ] 문서 링크를 절대경로(/<path>)로 추가하지 않음
- [ ] docs/commands.md API endpoint 표에 중복 row 없음

항목 2~4는 스크립트가 이미 검사하는 내용이다. 스크립트가 PASS이면 셋 다 자동으로 충족된다. 이 중복은 스크립트 검사 항목이 변경될 때 템플릿도 함께 수정해야 하는 드리프트 위험을 만든다(문서 동기화 목적 자체에 역행).

설계 선택 사항이므로 강제하지 않지만, 중복 유지 의도라면 "스크립트 통과만으로 충분하지 않은 이유"를 헤더나 주석으로 명시하면 좋다.

2. PR 템플릿 Docs Sync Gate — 적용 범위 조건 없음

docs/commands.md에는 (Mandatory for docs changes)라고 명시됐지만, PR 템플릿의 ## Docs Sync Gate 헤더에는 동일한 조건이 없다. 코드만 변경하는 PR 작성자가 이 체크리스트를 채워야 하는지 알 수 없다.

## Session Handover Gate는 모든 PR에 필수인데, Docs Sync Gate의 적용 범위가 달라질 경우 명시가 필요하다:

## Docs Sync Gate (docs 파일 변경 시 필수)

3. docs/commands.md 트러블슈팅 — 에러 메시지 하나 누락

validate_docs_sync.py가 검사하는 5가지 항목 중 4개만 트러블슈팅 목록에 있다.

스크립트 에러 메시지 commands.md 수록 여부
absolute link is forbidden ✅
broken link ✅
missing core doc link reference ✅
duplicated API endpoint row ✅
missing dynamic test count guidance (pytest --collect-only -q) ❌ 누락

추가 필요:

  - `missing dynamic test count guidance`: `docs/testing.md`에 `pytest --collect-only -q` 가이드 누락

✅ 좋은 점

  • commands.md 삽입 위치 — Session Handover Preflight 바로 다음 ## Docs Sync Validator 섹션으로 게이트 순서가 자연스럽다.
  • 에러 메시지 → 원인 직접 매핑 — 실패 메시지 그대로를 인용하고 원인을 설명해 디버깅 흐름이 명확하다.
  • 변경 범위 — 단일 커밋, 2파일, 코드 변경 없음.

수정 사항 요약

우선순위 위치 내용
🟡 docs/commands.md missing dynamic test count guidance 에러 메시지 트러블슈팅 추가
🟡 .gitea/PULL_REQUEST_TEMPLATE.md Docs Sync Gate 적용 범위 조건 명시 ("docs 변경 시 필수")
ℹ️ .gitea/PULL_REQUEST_TEMPLATE.md 체크리스트 항목 2~4 중복 설계 의도 명시 (또는 제거)
## 코드 리뷰 — PR #366 ### 개요 PR #365에서 추가된 `validate_docs_sync.py`를 PR 템플릿과 `docs/commands.md`에 연결하는 통합 PR. 단일 커밋, 2파일, 21 additions. --- ### 🟡 확인 필요 #### 1. PR 템플릿 체크리스트 항목 2~4가 스크립트와 중복 현재 체크리스트: ``` - [ ] python3 scripts/validate_docs_sync.py 통과 - [ ] README.md/CLAUDE.md에 docs/workflow.md, docs/commands.md 코어 링크가 유지됨 - [ ] 문서 링크를 절대경로(/<path>)로 추가하지 않음 - [ ] docs/commands.md API endpoint 표에 중복 row 없음 ``` 항목 2~4는 스크립트가 이미 검사하는 내용이다. 스크립트가 PASS이면 셋 다 자동으로 충족된다. 이 중복은 스크립트 검사 항목이 변경될 때 템플릿도 함께 수정해야 하는 드리프트 위험을 만든다(문서 동기화 목적 자체에 역행). 설계 선택 사항이므로 강제하지 않지만, 중복 유지 의도라면 "스크립트 통과만으로 충분하지 않은 이유"를 헤더나 주석으로 명시하면 좋다. #### 2. PR 템플릿 Docs Sync Gate — 적용 범위 조건 없음 `docs/commands.md`에는 `(Mandatory for docs changes)`라고 명시됐지만, PR 템플릿의 `## Docs Sync Gate` 헤더에는 동일한 조건이 없다. 코드만 변경하는 PR 작성자가 이 체크리스트를 채워야 하는지 알 수 없다. `## Session Handover Gate`는 모든 PR에 필수인데, Docs Sync Gate의 적용 범위가 달라질 경우 명시가 필요하다: ```markdown ## Docs Sync Gate (docs 파일 변경 시 필수) ``` #### 3. `docs/commands.md` 트러블슈팅 — 에러 메시지 하나 누락 `validate_docs_sync.py`가 검사하는 5가지 항목 중 4개만 트러블슈팅 목록에 있다. | 스크립트 에러 메시지 | commands.md 수록 여부 | |---|---| | `absolute link is forbidden` | ✅ | | `broken link` | ✅ | | `missing core doc link reference` | ✅ | | `duplicated API endpoint row` | ✅ | | `missing dynamic test count guidance (pytest --collect-only -q)` | ❌ 누락 | 추가 필요: ``` - `missing dynamic test count guidance`: `docs/testing.md`에 `pytest --collect-only -q` 가이드 누락 ``` --- ### ✅ 좋은 점 - **commands.md 삽입 위치** — Session Handover Preflight 바로 다음 `## Docs Sync Validator` 섹션으로 게이트 순서가 자연스럽다. - **에러 메시지 → 원인 직접 매핑** — 실패 메시지 그대로를 인용하고 원인을 설명해 디버깅 흐름이 명확하다. - **변경 범위** — 단일 커밋, 2파일, 코드 변경 없음. --- ### 수정 사항 요약 | 우선순위 | 위치 | 내용 | |----------|------|------| | 🟡 | `docs/commands.md` | `missing dynamic test count guidance` 에러 메시지 트러블슈팅 추가 | | 🟡 | `.gitea/PULL_REQUEST_TEMPLATE.md` | Docs Sync Gate 적용 범위 조건 명시 ("docs 변경 시 필수") | | ℹ️ | `.gitea/PULL_REQUEST_TEMPLATE.md` | 체크리스트 항목 2~4 중복 설계 의도 명시 (또는 제거) |
agentson added 1 commit 2026-03-01 23:18:43 +09:00
docs: address PR #366 review on docs sync gate
All checks were successful
Gitea CI / test (push) Successful in 33s
Details
Gitea CI / test (pull_request) Successful in 32s
Details
243469cd40
agentson commented 2026-03-01 23:18:57 +09:00
Author
Collaborator
Copy Link

리뷰 코멘트 3건 반영했습니다.

  • .gitea/PULL_REQUEST_TEMPLATE.md
    • ## Docs Sync Gate (docs 파일 변경 시 필수)로 적용 범위 명시
    • 드리프트 방지를 위해 스크립트 중복 항목(코어 링크/절대경로/중복 endpoint) 제거
    • 단일 게이트로 정리: python3 scripts/validate_docs_sync.py (docs 미변경 시 N/A)
  • docs/commands.md
    • 누락된 오류 유형 추가: missing dynamic test count guidance (docs/testing.md의 pytest --collect-only -q 가이드 누락)

검증:

  • python3 scripts/validate_docs_sync.py
  • python3 scripts/validate_ouroboros_docs.py
  • python3 scripts/validate_governance_assets.py
    모두 통과했습니다.
리뷰 코멘트 3건 반영했습니다. - `.gitea/PULL_REQUEST_TEMPLATE.md` - `## Docs Sync Gate (docs 파일 변경 시 필수)`로 적용 범위 명시 - 드리프트 방지를 위해 스크립트 중복 항목(코어 링크/절대경로/중복 endpoint) 제거 - 단일 게이트로 정리: `python3 scripts/validate_docs_sync.py` (docs 미변경 시 N/A) - `docs/commands.md` - 누락된 오류 유형 추가: `missing dynamic test count guidance` (`docs/testing.md`의 `pytest --collect-only -q` 가이드 누락) 검증: - `python3 scripts/validate_docs_sync.py` - `python3 scripts/validate_ouroboros_docs.py` - `python3 scripts/validate_governance_assets.py` 모두 통과했습니다.
agentson commented 2026-03-01 23:21:40 +09:00
Author
Collaborator
Copy Link

팔로업 리뷰 — PR #366 (커밋 243469cd)

이슈 해결 확인

이슈 상태
🟡 체크리스트 항목 2~4 중복 ✅ 해결 — 스크립트 실행 1개로 축약
🟡 Docs Sync Gate 적용 범위 불명확 ✅ 해결 — 헤더에 "(docs 파일 변경 시 필수)" 명시, docs 미변경 PR은 N/A 기재 안내 추가
🟡 missing dynamic test count guidance 트러블슈팅 누락 ✅ 해결 — commands.md 5번째 항목 추가됨

세부 확인

PR 템플릿: 체크리스트가 python3 scripts/validate_docs_sync.py 통과 1개로 정리됨. 헤더 (docs 파일 변경 시 필수) 및 N/A 가이드로 적용 범위 명확.

commands.md: 에러 메시지 목록이 스크립트 검사 항목 5개와 1:1 대응됨. validate_docs_sync.py PASS 확인.

Merge-ready. 모든 지적 사항 해결됨.

## 팔로업 리뷰 — PR #366 (커밋 243469cd) ### 이슈 해결 확인 | 이슈 | 상태 | |------|------| | 🟡 체크리스트 항목 2~4 중복 | ✅ 해결 — 스크립트 실행 1개로 축약 | | 🟡 Docs Sync Gate 적용 범위 불명확 | ✅ 해결 — 헤더에 "(docs 파일 변경 시 필수)" 명시, `docs` 미변경 PR은 N/A 기재 안내 추가 | | 🟡 `missing dynamic test count guidance` 트러블슈팅 누락 | ✅ 해결 — commands.md 5번째 항목 추가됨 | --- ### 세부 확인 **PR 템플릿**: 체크리스트가 `python3 scripts/validate_docs_sync.py 통과` 1개로 정리됨. 헤더 `(docs 파일 변경 시 필수)` 및 N/A 가이드로 적용 범위 명확. **commands.md**: 에러 메시지 목록이 스크립트 검사 항목 5개와 1:1 대응됨. `validate_docs_sync.py` PASS 확인. --- **Merge-ready.** 모든 지적 사항 해결됨.
jihoson merged commit 461fdc755b into feature/v3-session-policy-stream 2026-03-01 23:22:38 +09:00
jihoson deleted branch feature/issue-364-docs-sync-integration 2026-03-01 23:22:38 +09:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Something is not working
 duplicate
This issue or pull request already exists
 enhancement
New feature
 help wanted
Need some help
 invalid
Something is wrong
 question
More information is needed
 wontfix
This won't be fixed
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
agentson jihoson
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jihoson/The-Ouroboros#366
Delete Branch "feature/issue-364-docs-sync-integration"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?