검증 규칙¶

이 저장소의 기본 검증 진입점은 make verify입니다. 이 명령은 python3 scripts/run_ci_checks.py를 통해 python3 scripts/verify_wiki.py와 테스트 묶음을 같은 순서로 실행합니다. python3 scripts/verify_wiki.py는 그중 위키 구조 무결성만 빠르게 확인할 때 쓰는 하위 검증 명령입니다.

현재 검사 범위¶

log.md의 항목 헤더와 필수 줄 형식이 일관된지 확인
wiki/ 아래 모든 Markdown 문서에 YAML frontmatter가 있는지 확인
저장소 전체 Markdown 파일에서 상대 경로 링크가 실제 파일을 가리키는지 확인
type: source 문서의 raw_source가 실제 raw 파일을 가리키는지 확인
raw/imports/ 아래 보관본이 실제 type: source 문서에 대응되는지 확인
type: source 문서의 updated 날짜와 해당 문서를 언급한 log.md의 마지막 날짜가 일치하는지 확인
type: source 문서가 최소 하나 이상의 concept, entity, comparison 문서로 직접 연결돼 있는지 확인
wiki/ 문서가 index.md나 다른 Markdown 문서 어디에서도 참조되지 않는 고아 문서인지 확인
index.md의 관리 섹션이 wiki/ frontmatter와 동기화되어 있는지 확인

링크 검사 규칙¶

상대 경로 링크만 검사합니다.
raw/imports/ 아래 원문 보존본은 외부 저장소 기준 상대 링크를 그대로 가질 수 있으므로 링크 검사에서 제외합니다.
http://, https://, mailto:, #anchor 링크는 검사 대상에서 제외합니다.
예시 텍스트는 실제 링크로 쓰지 않는 편이 안전합니다. 존재하지 않는 샘플 문서를 보여주고 싶다면 링크 없는 코드 예시로 적습니다.

실패 기준¶

아래 경우 검증은 실패합니다.

log.md 항목이 ## [YYYY-MM-DD] scope | title 형식을 따르지 않음
log.md 항목에 범위, 파일, 비고 줄이 빠짐
wiki/ 문서에 frontmatter가 없음
Markdown 상대 링크가 존재하지 않는 파일을 가리킴
소스 문서에 raw_source가 없거나 대상 파일이 없음
raw/imports/에 새 보관본이 생겼지만 대응하는 type: source 문서가 없음
소스 문서의 updated 날짜와 log.md의 마지막 관련 항목 날짜가 다름
소스 문서가 concept, entity, comparison 중 하나라도 직접 연결하지 않아 도메인 묶음 최소 요건을 충족하지 못함
wiki/ 문서가 index.md나 다른 문서 어디에서도 참조되지 않음
index.md의 소스, 엔티티, 개념, 비교 및 분석, 템플릿 섹션이 frontmatter 기준 기대값과 다름

운영 원칙¶

로컬에서는 make verify를 기본 검증 진입점으로 사용합니다.
CI는 .github/workflows/verify.yml에서 같은 make verify를 호출합니다.
새 문서를 만들거나 파일명을 바꾸면 바로 verify_wiki.py를 실행합니다.
freshness 검사는 현재 type: source 문서에만 적용합니다. concept, entity, comparison 문서는 같은 변경에서 함께 갱신하되, 개별 로그 날짜 일치까지는 강제하지 않습니다.
index.md의 예시 항목은 검증을 깨지 않도록 링크 없는 예시를 기본으로 사용합니다.
검증 실패가 나면 문서를 우회하지 말고, 링크나 메타데이터를 실제 상태에 맞게 고칩니다.
make web-build에서 나오는 MkDocs의 not in nav 경고는 현재 허용 범위입니다. 이 경고만으로는 실패로 보지 않고, 실제 링크 오류나 원치 않는 웹 노출이 있을 때만 수정 대상으로 다룹니다.