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

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

Open
agentson wants to merge 1 commits from feature/issue-350-doc-ssot into feature/v3-session-policy-stream
pull from: feature/issue-350-doc-ssot
merge into: jihoson:feature/v3-session-policy-stream
Conversation 1 Commits 1 Files Changed 10 +196 -89
agentson commented 2026-03-01 17:08:36 +09:00
Collaborator
Copy Link

개요

문서 중복·드리프트 방지를 위해 SSOT 원칙을 문서 체계에 적용한다.
validate_docs_sync.py로 CI에서 자동 검증한다.

의존성

PR #351 머지 후 병합 권장 (공유 파일 충돌 방지)

REQ/TASK 매핑

REQ TASK 변경
REQ-OPS-002 - CI validate_docs_sync 단계 추가
REQ-OPS-003 - PR 템플릿 Docs Sync 체크리스트 추가

변경 파일 (10개)

신규:

  • docs/README.md — 문서 라우팅/역할/SSOT 정의 (상대경로 링크)
  • scripts/validate_docs_sync.py — 가변 수치 하드코딩 + 누락 엔드포인트 검사

수정:

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

수용 기준

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

Docs Sync (SSOT)

  • docs/README.md가 새 SSOT 라우팅 문서
  • 요약 문서에 가변 수치 하드코딩 추가 없음
  • SSOT 반영 위치: docs/README.md (신규)

Closes #350

## 개요 문서 중복·드리프트 방지를 위해 SSOT 원칙을 문서 체계에 적용한다. validate_docs_sync.py로 CI에서 자동 검증한다. ## 의존성 PR #351 머지 후 병합 권장 (공유 파일 충돌 방지) ## REQ/TASK 매핑 | REQ | TASK | 변경 | |-----|------|------| | REQ-OPS-002 | - | CI validate_docs_sync 단계 추가 | | REQ-OPS-003 | - | PR 템플릿 Docs Sync 체크리스트 추가 | ## 변경 파일 (10개) 신규: - `docs/README.md` — 문서 라우팅/역할/SSOT 정의 (상대경로 링크) - `scripts/validate_docs_sync.py` — 가변 수치 하드코딩 + 누락 엔드포인트 검사 수정: - `CLAUDE.md` — 문서 진입점, SmartScanner → architecture.md 링크 - `README.md` — 문서 네비게이션 섹션, 고정 수치 제거 - `docs/commands.md` — validate_docs_sync 명령 추가 - `docs/testing.md` — 테스트 총량 동적 확인 전환 - `docs/ouroboros/82_doc_restructure_plan.md` — draft → active - `.gitea/PULL_REQUEST_TEMPLATE.md` — Docs Sync 체크리스트 - `.gitea/workflows/ci.yml` / `.github/workflows/ci.yml` — validate_docs_sync 단계 ## 수용 기준 - [x] python3 scripts/validate_docs_sync.py: PASS - [x] docs/README.md 링크 상대경로 - [x] commands.md 중복 엔드포인트 없음 ## Docs Sync (SSOT) - [x] docs/README.md가 새 SSOT 라우팅 문서 - [x] 요약 문서에 가변 수치 하드코딩 추가 없음 - SSOT 반영 위치: docs/README.md (신규) Closes #350
agentson added 2 commits 2026-03-01 17:08:36 +09:00
docs: v2/v3 구현 감사 문서 피드백 전체 반영 (#349)
Some checks failed
Gitea CI / test (push) Failing after 3s
Details
Gitea CI / test (pull_request) Failing after 3s
Details
6b34367656 
11회 리뷰 사이클에서 남긴 [코멘트]를 모두 본문에 반영하고 블록을 제거한다.

변경 문서:
- docs/architecture.md: SmartScanner 동작 모드(both), 대시보드 10 API,
  DB 스키마(session_id/fx_pnl/mode), config 변수 갱신
- docs/commands.md: /api/pnl/history, /api/positions 엔드포인트 추가
- docs/testing.md: 테스트 수 고정값 제거, SmartScanner fallback 최신화,
  Dashboard 10 API routes 반영
- README.md: 고정 수치 제거, Gitea CI 명시, 파일별 수치 'CI 기준 변동' 표기
- CLAUDE.md: SmartScanner 섹션명 변경, 고정 수치 제거
- docs/requirements-log.md: #318~#331 구현 항목 추가
- docs/ouroboros/80_implementation_audit.md: ROOT-5/6/7 분리,
  REQ-V3-008 함수명 병기, v3 ~85% / 거버넌스 ~60%로 갱신
- docs/ouroboros/85_loss_recovery_action_plan.md: ACT-07 함수명 병기,
  테스트 수 갱신, 6.1/6.2 정확도 개선
- docs/ouroboros/60_repo_enforcement_checklist.md: CI job/step 구분 표 추가
- docs/ouroboros/README.md: 50_* 문서 (A)/(B) 보조 표기

Closes #349
docs: SSOT 문서 허브 도입 및 동기화 자동 검증 게이트 (#350)
Some checks failed
Gitea CI / test (push) Failing after 3s
Details
Gitea CI / test (pull_request) Failing after 3s
Details
4ca582b418 
문서 중복·드리프트를 구조적으로 방지하기 위해 SSOT 원칙을 문서 체계에 적용한다.

신규:
- docs/README.md: 문서 라우팅/역할/읽기 순서/SSOT 정의 (상대경로 링크)
- scripts/validate_docs_sync.py: 가변 수치 하드코딩 금지 + 누락 엔드포인트 검사

수정:
- CLAUDE.md: 문서 진입점 추가, SmartScanner 세부 동작 → architecture.md 링크
- README.md: 문서 네비게이션 섹션 추가, 고정 수치/파일별 케이스 수 제거
- docs/commands.md: validate_docs_sync.py 명령 추가; 중복 엔드포인트 2행 제거
- docs/testing.md: 테스트 총량 고정값 → pytest --collect-only -q 동적 확인으로 전환
- docs/ouroboros/82_doc_restructure_plan.md: draft → active, 실행 현황으로 전환
- .gitea/PULL_REQUEST_TEMPLATE.md: Docs Sync 체크리스트 추가
- .gitea/workflows/ci.yml + .github/workflows/ci.yml: validate_docs_sync 단계 추가

검증:
- python3 scripts/validate_docs_sync.py: PASS

Closes #350
agentson commented 2026-03-01 17:15:57 +09:00
Author
Collaborator
Copy Link

코드 리뷰 — PR #352

개요

문서 드리프트 방지를 위한 SSOT 구조 도입. 핵심 변경:

  • docs/README.md 신규 — 문서 라우팅/역할 단일 진실 원장
  • scripts/validate_docs_sync.py 신규 — 가변 수치 하드코딩 + 누락 엔드포인트 CI 검사
  • 요약 문서(README.md, CLAUDE.md) → 링크 기반 참조로 축약
  • .gitea CI + PR 템플릿에 게이트 추가

🟡 확인 필요

1. architecture.md 설정 주석 잔재

본문 텍스트는 "Both modes"로 업데이트됐지만, 설정 예시 섹션의 주석이 여전히 # Optional — Smart Scanner (realtime mode only)입니다. 동일 문서 내 불일치입니다.

2. validate_docs_sync.py — ROOT = Path(".")

CWD 기준 상대경로를 사용합니다. scripts/ 디렉터리 안에서 직접 실행하면 오동작합니다. CI에서는 레포 루트에서 실행하므로 무해하지만, 스크립트 헤더 또는 docs/commands.md에 "레포 루트에서 실행" 조건을 명시하면 좋습니다.

3. diff 범위 — PR #351 변경이 함께 보임

현재 base가 feature/v3-session-policy-stream이고 이 브랜치가 PR #351 위에 스택되어 있어, diff에 architecture.md·80_implementation_audit.md 등 PR #351 변경이 중복으로 포함됩니다. PR #351이 base에 머지된 뒤 이 PR을 머지하면 실제 추가되는 내용은 SSOT 관련 파일들만 됩니다. 머지 전 base 업데이트(git rebase feature/v3-session-policy-stream) 여부를 확인하세요.

✅ 좋은 점

  • validate_docs_sync.py 패턴 설계 — 금지 패턴을 (파일명, 정규식) 튜플로 관리해 향후 추가가 쉽고, 엔드포인트 누락 검사도 명확합니다.
  • docs/README.md 링크 모두 상대경로 — 환경 독립적이고 GitHub/Gitea 모두에서 정상 렌더링됩니다.
  • PR 템플릿 Docs Sync 체크리스트 — "SSOT 반영 위치(링크)" 항목이 있어 리뷰어가 직접 확인 가능합니다.
  • 요약 문서 축약 — README.md, CLAUDE.md에서 고정 수치(551 tests, 8 API) 완전 제거, 드리프트 가능성 차단됩니다.

수정 권장 사항 요약

우선순위 위치 내용
🟡 docs/architecture.md 설정 주석 realtime mode only → both modes
🟡 docs/commands.md 또는 스크립트 헤더 validate_docs_sync.py는 레포 루트에서 실행해야 함을 명시
ℹ️ 브랜치 PR #351 머지 확인 후 base rebase 권장
## 코드 리뷰 — PR #352 ### 개요 문서 드리프트 방지를 위한 SSOT 구조 도입. 핵심 변경: - `docs/README.md` 신규 — 문서 라우팅/역할 단일 진실 원장 - `scripts/validate_docs_sync.py` 신규 — 가변 수치 하드코딩 + 누락 엔드포인트 CI 검사 - 요약 문서(`README.md`, `CLAUDE.md`) → 링크 기반 참조로 축약 - `.gitea` CI + PR 템플릿에 게이트 추가 --- ### 🟡 확인 필요 #### 1. `architecture.md` 설정 주석 잔재 본문 텍스트는 "Both modes"로 업데이트됐지만, 설정 예시 섹션의 주석이 여전히 `# Optional — Smart Scanner (realtime mode only)`입니다. 동일 문서 내 불일치입니다. #### 2. `validate_docs_sync.py` — `ROOT = Path(".")` CWD 기준 상대경로를 사용합니다. `scripts/` 디렉터리 안에서 직접 실행하면 오동작합니다. CI에서는 레포 루트에서 실행하므로 무해하지만, 스크립트 헤더 또는 `docs/commands.md`에 **"레포 루트에서 실행"** 조건을 명시하면 좋습니다. #### 3. diff 범위 — PR #351 변경이 함께 보임 현재 base가 `feature/v3-session-policy-stream`이고 이 브랜치가 PR #351 위에 스택되어 있어, diff에 `architecture.md`·`80_implementation_audit.md` 등 PR #351 변경이 중복으로 포함됩니다. PR #351이 base에 머지된 뒤 이 PR을 머지하면 실제 추가되는 내용은 SSOT 관련 파일들만 됩니다. 머지 전 base 업데이트(`git rebase feature/v3-session-policy-stream`) 여부를 확인하세요. --- ### ✅ 좋은 점 - **`validate_docs_sync.py` 패턴 설계** — 금지 패턴을 `(파일명, 정규식)` 튜플로 관리해 향후 추가가 쉽고, 엔드포인트 누락 검사도 명확합니다. - **`docs/README.md` 링크 모두 상대경로** — 환경 독립적이고 GitHub/Gitea 모두에서 정상 렌더링됩니다. - **PR 템플릿 Docs Sync 체크리스트** — "SSOT 반영 위치(링크)" 항목이 있어 리뷰어가 직접 확인 가능합니다. - **요약 문서 축약** — `README.md`, `CLAUDE.md`에서 고정 수치(`551 tests`, `8 API`) 완전 제거, 드리프트 가능성 차단됩니다. --- ### 수정 권장 사항 요약 | 우선순위 | 위치 | 내용 | |----------|------|------| | 🟡 | `docs/architecture.md` | 설정 주석 `realtime mode only` → `both modes` | | 🟡 | `docs/commands.md` 또는 스크립트 헤더 | `validate_docs_sync.py`는 레포 루트에서 실행해야 함을 명시 | | ℹ️ | 브랜치 | PR #351 머지 확인 후 base rebase 권장 |
Some checks failed
Gitea CI / test (push) Failing after 3s
Details
Gitea CI / test (pull_request) Failing after 3s
Details
This pull request can be merged automatically.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feature/issue-350-doc-ssot:feature/issue-350-doc-ssot
git checkout feature/issue-350-doc-ssot
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#352
Delete Branch "feature/issue-350-doc-ssot"

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?