fix(docs): 문서 검사가 명령 안 경로와 짝 저장소 참조를 본다
문제 verify:documentation(FE-GATE-017)은 공백 없는 backtick 경로만 본다. 그래서 `corepack pnpm exec vitest run tests/…` 같은 명령 안의 경로, 셸 코드 블록의 명령, 저장소 밖(`../`) 링크는 확인하지 않았다. 실제로 원장 docs/operations/adapter-remediation-ledger.md의 N-06~N-08 행이 V2와 함께 지운 테스트 세 개를 실행하라고 적고 있었다. 짝 백엔드 정본 링크가 깨져도 알 수 없었다. config/ci/ungated-scripts.json의 check:remediation-ledger 사유는 "It passes at this commit"이라는 시점 문장을 담았다. 고른 방법 - 인라인 코드와 셸 코드 블록(```bash/sh/shell/console/zsh, 언어 없음)에서 명령(corepack, pnpm, npx, node, vitest, playwright, tsc, eslint, bash, sh)의 인자를 같은 경로 규칙으로 본다. 앞의 NAME=value는 건너뛰고, --flag=value는 값만 본다. 자리표시자(<id>, glob, $VAR)는 기존 규칙대로 경로로 보지 않는다. - 짝 백엔드 템플릿(clean-architecture-backend-template)을 가리키는 backtick 경로와 저장소 밖 링크는 문서를 읽는 checkout 옆에서 찾는다. 그 checkout이 있으면 없는 경로는 실패다. 없으면(CI, 중첩 worktree) 실패 대신 "not verified"로 출력하고 보고서 documentReferences[].unverifiedLinks에 남긴다. 보고서 schema에 그 칸을 더했다. - 원장 N-06~N-08 행의 명령을 LEG-01 행처럼 "V2와 함께 지움"으로 바꾸고, ungated 사유에서 시점 문장을 지웠다. docs/README.md 1절의 검사 범위 설명을 고쳤다. - 버린 대안: 지운 심볼 이름 검사. 지운 이름 목록을 따로 관리해야 하고 오탐이 많다(리뷰 5.2절). 1절 밖 문서로 대상 넓히기. 기록 문서가 일부러 옛 경로를 적어 예외가 늘어난다. 위험·한계 - 명령 머리 목록에 없는 명령(git, curl 등)의 인자는 여전히 보지 않는다. - 짝 저장소 참조는 CI에서 늘 "not verified"다. 실제 확인은 옆에 checkout이 있는 개발 환경에서만 된다. - 1절 밖 문서(testing strategy :765, VD-23)는 그대로 검사 밖이다. 검증 - RED: 새 테스트 4건(인라인 명령, 셸 블록, 짝 저장소 있음·깨짐, 짝 저장소 없음 보고) 실패. - 수정 뒤 documentation-readiness 19건 통과. 저장소에서 수정 전 원장 행 3개가 "names paths that do not exist"로 잡혔고, 행을 고친 뒤 verify:documentation PASS_SCOPED(worktree라 짝 저장소 참조 3건은 not verified). check:remediation-ledger PASS, check:ci PASS, check:types 통과, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-05
This commit is contained in:
+4
-1
@@ -40,7 +40,10 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
|
||||
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
|
||||
|
||||
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
|
||||
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. `CHANGELOG.md`는
|
||||
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. 명령(인라인 코드와
|
||||
셸 코드 블록) 안의 경로 인자도 본다. 짝 백엔드 템플릿(`clean-architecture-backend-template`)의
|
||||
경로와 링크는 그 checkout이 이 checkout 옆에 있을 때만 확인하고, 없으면 실패 대신 확인하지
|
||||
못한 것으로 출력과 `artifacts/quality/documentation-review.json`에 남긴다. `CHANGELOG.md`는
|
||||
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
|
||||
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
|
||||
`scripts/verify-documentation-readiness.ts`다.
|
||||
|
||||
Reference in New Issue
Block a user