# Phase 03 — 문서 링크 무결성 CI 게이트

> 이 문서는 Claude 와의 설계 대화에서 정리된 phase 구현 문서다.
> 대상 PRD 항목: F-10, F-11, F-12, F-13 / 제약: NF-5, NF-6
> 선행 phase: Phase 01(문서 작성), Phase 02(HTML 렌더링) 완료 가정

## 배경

문서 사이트를 한 번 만들어 두는 것만으로는 오래 못 간다. 스킬이 하나 추가되면
`docs/skill-guides/` 와 `docs/skill-output/` 에 문서 두 개가 따라와야 하고
README 에도 링크가 붙어야 하는데, 사람이 잊어버리기 딱 좋은 지점이다. 실제로
직전 감사에서 R1/R2/R5 가 한꺼번에 WARN 으로 잡힌 것도 결국 "문서가 스킬을
따라가지 못한" 드리프트였다.

그래서 이번 phase 에서는 그 드리프트를 사람 눈이 아니라 CI 가 잡도록 만드는
것을 목표로 한다. 검증 자체는 이미 손으로 한 번 해봤으니, 그걸 재현 가능한
스크립트로 굳히고 워크플로에 물리면 될 것 같다.

## 하려는 것

크게 보면 검증 스크립트 하나와 워크플로 연결 한 군데다.

스크립트는 `scripts/check-docs-links.sh` 정도의 이름이 무난해 보인다. 하는 일은
대략 이렇다. 먼저 스킬 목록을 알아내야 하는데, 이건 절대 하드코딩하면 안 되고
`skills/*/` 를 스캔해서 얻어야 한다. repo-agnostic 해야 한다는 NF-6 이 있기
때문이다. 그 다음 각 스킬에 대해 guide md/html 과 usage md/html 네 개가 실재하는지
본다. 하나라도 없으면 실패다.

README 쪽도 봐야 한다. README 가 링크한 Pages URL 들을 뽑아서, 그 URL 의 경로
부분이 실제 파일과 대응되는지 확인한다. 그리고 링크 개수가 스킬 수의 정확히 두 배인지
센다. 이게 F-11 이다. 덤으로 URL 의 owner 부분이 소문자인지도 확인해두면 좋겠다.
대문자가 섞이면 Pages 에서 404 가 나는데 로컬에서는 파일이 있으니 안 잡힌다.

워크플로는 기존 `.github/workflows/validate.yml` 에 스텝을 하나 더 붙이는
방향이 맞을 것 같다. 별도 워크플로 파일을 새로 만드는 건 과해 보인다.

## 고려사항

출력 형식은 기존 스킬들이 쓰는 `[OK]` / `[FAIL]` 관례를 따르는 게 일관적이다.
실패했을 때 무엇이 왜 실패했는지 한 줄로 알 수 있어야 CI 로그에서 쓸모가 있다.

exit code 는 성공 0, 실패 1이면 충분하다고 본다. 세분화된 코드가 필요할 것
같지는 않다.

스크립트는 `set -euo pipefail` 로 시작하고, repo 루트에서 실행되는 것을 전제로
한다. 어디서 실행해도 되게 만들 수도 있지만 지금 단계에서는 과한 것 같다.

`docs/examples/` 아래 파일들은 검증 대상이 아니다. 거기는 worked example 산출물
보관소라서 스킬 목록과 1:1 대응이 아니다.

## 검증

스크립트를 만든 뒤에는 당연히 현재 repo 상태에서 통과하는지 돌려봐야 한다.
그리고 일부러 깨뜨려 보는 것도 해두면 좋겠다. 예를 들어 guide html 하나를 잠깐
다른 이름으로 옮겨두고 실패하는지, README 링크 한 줄을 지우고 개수 검사가
걸리는지 정도. 확인 후에는 원복한다.

CI 쪽은 푸시해봐야 확실하지만, 최소한 워크플로 YAML 이 문법적으로 유효한지는
확인해두자.

## 범위 밖

HTML 내부의 링크(문서 안에서 다른 문서로 거는 링크)까지 따라가서 검사하는 건
이번 phase 범위가 아니다. 필요해지면 나중에 별도로 다룬다.

Pages 배포 자체가 성공했는지 원격에서 확인하는 것도 여기서는 하지 않는다.
네트워크 의존이 생기고 NF-2 와 충돌한다.