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

docs: SSOT 문서 허브 도입 및 동기화 자동 검증 게이트 #350

New Issue
Closed
opened 2026-03-01 17:06:09 +09:00 by agentson · 2 comments
agentson commented 2026-03-01 17:06:09 +09:00
Collaborator
Copy Link

개요

문서 중복·드리프트 문제를 구조적으로 방지하기 위해 SSOT(Single Source of Truth) 원칙을 문서 체계에 적용한다.

변경 내용

신규 파일

  • docs/README.md — 문서 라우팅/역할/읽기 순서/SSOT 정의
  • scripts/validate_docs_sync.py — 가변 수치 하드코딩 금지, 누락 엔드포인트 검사

수정 파일

  • CLAUDE.md — 문서 진입점 추가, 가변 수치/동작 설명 → SSOT 링크로 대체
  • README.md — 문서 네비게이션 섹션 추가, 고정 수치 제거
  • .gitea/PULL_REQUEST_TEMPLATE.md — Docs Sync 체크리스트 추가
  • .gitea/workflows/ci.yml / .github/workflows/ci.yml — validate_docs_sync 단계 추가
  • docs/commands.md — validate_docs_sync.py 명령 추가
  • docs/testing.md — 테스트 총량을 동적 확인 명령으로 전환
  • docs/ouroboros/82_doc_restructure_plan.md — draft → active, 실행 현황으로 전환

SSOT 규칙 (docs/README.md 기준)

  • 아키텍처/동작: docs/architecture.md
  • 실행 명령: docs/commands.md
  • 테스트 정책: docs/testing.md
  • 요약 문서(README.md, CLAUDE.md)는 개요/진입점 역할만 가짐
  • 가변 수치는 요약 문서에 하드코딩 금지

수용 기준

  • python3 scripts/validate_docs_sync.py PASS
  • python3 scripts/validate_ouroboros_docs.py PASS
  • docs/README.md 의 링크가 상대경로로 작동
  • commands.md 중복 엔드포인트 없음

의존성

Closes #349 이후 머지 권장 (파일 충돌 방지)

## 개요 문서 중복·드리프트 문제를 구조적으로 방지하기 위해 SSOT(Single Source of Truth) 원칙을 문서 체계에 적용한다. ## 변경 내용 ### 신규 파일 - `docs/README.md` — 문서 라우팅/역할/읽기 순서/SSOT 정의 - `scripts/validate_docs_sync.py` — 가변 수치 하드코딩 금지, 누락 엔드포인트 검사 ### 수정 파일 - `CLAUDE.md` — 문서 진입점 추가, 가변 수치/동작 설명 → SSOT 링크로 대체 - `README.md` — 문서 네비게이션 섹션 추가, 고정 수치 제거 - `.gitea/PULL_REQUEST_TEMPLATE.md` — Docs Sync 체크리스트 추가 - `.gitea/workflows/ci.yml` / `.github/workflows/ci.yml` — validate_docs_sync 단계 추가 - `docs/commands.md` — validate_docs_sync.py 명령 추가 - `docs/testing.md` — 테스트 총량을 동적 확인 명령으로 전환 - `docs/ouroboros/82_doc_restructure_plan.md` — draft → active, 실행 현황으로 전환 ## SSOT 규칙 (docs/README.md 기준) - 아키텍처/동작: `docs/architecture.md` - 실행 명령: `docs/commands.md` - 테스트 정책: `docs/testing.md` - 요약 문서(`README.md`, `CLAUDE.md`)는 개요/진입점 역할만 가짐 - 가변 수치는 요약 문서에 하드코딩 금지 ## 수용 기준 - `python3 scripts/validate_docs_sync.py` PASS - `python3 scripts/validate_ouroboros_docs.py` PASS - docs/README.md 의 링크가 상대경로로 작동 - commands.md 중복 엔드포인트 없음 ## 의존성 Closes #349 이후 머지 권장 (파일 충돌 방지)
agentson commented 2026-03-01 22:48:18 +09:00
Author
Collaborator
Copy Link

현행 기준으로 #350을 재평가한 결과, 이슈 본문에서 요구한 산출물(, )은 현재 저장소 표준 경로/검증 체계와 불일치합니다.

대신 아래로 기능이 실질 대체되었습니다.

따라서 #350은 최신 체계로 superseded 처리하는 것이 맞아 종결합니다.

현행 기준으로 #350을 재평가한 결과, 이슈 본문에서 요구한 산출물(, )은 현재 저장소 표준 경로/검증 체계와 불일치합니다. 대신 아래로 기능이 실질 대체되었습니다. - docs SSOT 허브: - 문서 무결성 검증: [OK] validated 14 docs in docs/ouroboros [OK] unique Doc-ID: 14 [OK] definitions: 100, references: 114 [OK] req->task mappings: 20 [OK] req->test mappings: 20 - 거버넌스/템플릿/추적성 검증: - 관련 후속 머지: #359, #360, #361 따라서 #350은 최신 체계로 superseded 처리하는 것이 맞아 종결합니다.
agentson commented 2026-03-01 22:48:30 +09:00
Author
Collaborator
Copy Link

정정 코멘트입니다.

현행 기준으로 #350을 재평가한 결과, 이슈 본문의 산출물(docs/README.md, scripts/validate_docs_sync.py)은 현재 저장소 표준 경로/검증 체계와 불일치합니다.

실질 대체 체계:

따라서 #350은 최신 체계로 superseded 처리되어 종결되었습니다.

정정 코멘트입니다. 현행 기준으로 #350을 재평가한 결과, 이슈 본문의 산출물(`docs/README.md`, `scripts/validate_docs_sync.py`)은 현재 저장소 표준 경로/검증 체계와 불일치합니다. 실질 대체 체계: - SSOT 문서 허브: `docs/ouroboros/*` - 문서 무결성 검증: `scripts/validate_ouroboros_docs.py` - 거버넌스/템플릿/추적성 검증: `scripts/validate_governance_assets.py` - 관련 후속 머지: #359, #360, #361 따라서 #350은 최신 체계로 superseded 처리되어 종결되었습니다.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
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#350
Delete Branch "%!s()"

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?