fix(docs): 문서 검사가 짝 백엔드 참조를 pin 커밋의 트리에서 찾는다

문제
verify:documentation(FE-GATE-017)은 짝 백엔드 경로·링크를 옆 checkout의
작업 트리에서 찾았다. 그래서 같은 커밋이 놓인 곳마다 결과가 달랐다. desktop은
옆 checkout이 ef947e5(9월)에 미커밋 변경까지 있어 문서와 무관하게 rc=1,
짝이 없는 worktree는 PASS(17개 미확인)였다. 옆 checkout이 pin보다 새로우면
pin에 없는 파일을 적어도 통과하고, 저장소 이름을 틀린 `../` 링크는
"확인 못 함"으로 통과했다. config/contracts/backend-contract-pin.json은 읽지
않았다.

고른 방법
- 짝 저장소 목록과 기준 커밋을 pin 파일에서 읽는다. pin은 문서와 같이
  작업 디렉터리에서 읽는다(문서가 어느 커밋을 설명하는지 적은 파일이라서).
- 옆 checkout에 pin 커밋이 있으면 `git ls-tree -r -t <pin>`으로 그 커밋의
  트리(파일과 폴더)를 한 번 읽어 찾는다. 작업 트리와 HEAD는 보지 않는다.
  hook이 넘긴 GIT_DIR 같은 GIT_* 변수는 지우고 git을 부른다.
- checkout이 없거나, pin 커밋이 없거나, git이 읽지 못하면 실패 대신
  unverifiedLinks로 남기고, 출력에 이유(짝 HEAD, pin 앞 12자)를 적는다.
- `../`로 나가는 링크의 첫 폴더가 pin에 없는 저장소면 missingPaths로 실패한다.
  실패하면 "pin 커밋에서 찾았다"는 줄을 stderr에 하나 더 적는다.
- 버린 대안: 짝 HEAD가 pin과 다르면 전부 unverified(리뷰 (c)). 더 단순하지만
  pin 뒤로 앞서 있는 흔한 checkout에서 아무것도 확인하지 못한다. 경로마다
  `git cat-file -e`: 같은 결과지만 참조 수만큼 프로세스를 띄운다.

위험·한계
- pin 커밋을 fetch하지 않은 checkout(desktop 지금 상태)에서는 짝 참조가 전부
  "not verified"다. 실패하지 않는 대신 확인도 하지 않는다.
- 짝 저장소는 여전히 하나(pin 파일의 backend)다. 둘째 짝이 생기면 pin 모양부터
  바꿔야 한다.
- pin 파일이 없으면 짝 저장소가 없는 것으로 보고 `../` 링크를 전부 실패로 센다.
- 보고서 schema는 그대로다(unverifiedLinks 주석만 고침).

검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
  tests/unit/documentation-readiness.test.ts, 그리고 corepack pnpm
  verify:documentation(옆 짝이 ef947e5인 desktop에서 PASS_SCOPED +
  not verified 기대).
- RED 기대: "looks a reference up in the pinned commit, not in a later HEAD or
  the working tree", "reports the references as not verified when the
  checkout does not have the pinned commit", "fails a link out of the
  repository into a repository that is not paired".

Refs: 1105/12-02
This commit is contained in:
DongHyeonka
2026-11-05 22:29:19 +09:00
parent a793b83e82
commit fc95672ad5
5 changed files with 225 additions and 41 deletions
+5 -2
View File
@@ -43,8 +43,11 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와
셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의
경로와 링크는 그 checkout이 이 checkout 옆에 있을 때만 확인하고, 없으면 실패 대신 확인하지
못한 것으로 출력과 `artifacts/quality/documentation-review.json`에 남긴다. `CHANGELOG.md`는
경로와 링크는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다.
이 checkout 옆에 있는 짝 checkout의 git 기록을 읽고, 그 작업 트리와 HEAD는 보지 않는다. 짝
checkout이 없거나 그 커밋이 없으면 실패 대신 확인하지 못한 것으로 출력과
`artifacts/quality/documentation-review.json`에 남긴다. repo 밖으로 나가는 링크가 짝 저장소를
가리키지 않으면(저장소 이름 오타 포함) 실패한다. `CHANGELOG.md`는
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
`scripts/verify-documentation-readiness.ts`다.
+3 -1
View File
@@ -132,7 +132,9 @@ DOCUMENTATION_READY (off-chain)
- 입구 문서가 실제 `src` 최상위 폴더와 `.dependency-cruiser.json` 규칙 이름을
적는지
- `docs/README.md` 1절의 현재 계약 문서에 적힌 repo 경로·링크·package script·
FE-GATE ID가 실제로 있는지
FE-GATE ID가 실제로 있는지. 짝 백엔드 경로는 옆 checkout의 작업 트리가 아니라
`config/contracts/backend-contract-pin.json`이 고정한 커밋에서 찾고, 그 커밋을
읽을 수 없으면 확인하지 못한 것으로 남긴다
- 2026-07-18 diagram 리뷰 기록의 두 사본(`docs/architecture/review-ledger.json`,
`review-evidence.md`)이 같은 해시·점수를 담는지. 원본 diagram은 repo 밖에
있으므로 이 항목은 구조가 바뀌어도 통과한다