feat(docs-version-drift-check): docs:check가 현행 문서의 버전 표지를 package.json과 대조한다

[hsleedevelop]

요약

docs의 HTML 문서 중 "현행"을 표방하는 문서의 버전 표지가 package.json과 어긋나도 가드가 없었다 —
docs:check는 overview 생성본 바이트 대조뿐이라 green이어도 표지가 낡았다(overview 배지 두 세대 지연,
시뮬레이션 footer v0.23.0 17릴리스 방치, 시뮬레이션 현재 v0.40.0). 이제 npm run docs:check가 대조한다.

변경:

• scripts/docs-version-drift.mjs 신설, generate-harness-overview.mjs --check에서 호출(새 의존성·새 npm script 없음).
• 대조 대상(등록): overview 템플릿·생성본의 hero 배지·최신 🆕 배너(묶음이면 상한)·footer,
  what-changes-latest-version.html footer(title·dd는 기존 테스트 몫), index.html what-changes 목록 첫 항목.
  표지를 못 찾아도 실패한다(가드가 조용히 꺼지지 않게).
• 결정론적 분류 규칙(docs/ 최상위 *.html, 첫 일치 — 코드 머리 주석이 정본):
  1. snapshot — 파일명 -<버전>.html → 제외
  2. baseline — 버전 담은 hero 태그/footer 중 하나라도 "기준" 라벨 → 제외 (fleet/task/rubric guide, workflow-diagrams, schematics)
  3. current — 버전 담은 hero 태그/footer, "기준" 없음 → 등록 또는 사유 있는 명시 제외 필수, 없으면 실패
  4. unversioned — 그 밖(<title> 버전은 분류에 안 씀)
     명시 제외 항목이 current가 아니게 되면 "낡은 제외"로 실패한다.
• MAINTAINING 릴리스 5단계·결합 강도 서열, docs/ao-worker-rules.md §3 한 줄, CHANGELOG [Unreleased] Added.

⚠️ 명시 제외: docs/harness-workflow-simulation.html

오케스트레이터 결정 A. 표지 셋이 v0.40.0이지만 본문 시나리오가 0.40.0 기준이라(적어도 0.42.1 handoff 단독 커밋 중단·
0.44.0 머지 후 종결 커밋 하나가 워크스루에 걸림) 표지만 고치면 틀린 문서에 현행 도장을 찍는다.
excludedCurrentDocuments에 사유와 함께 올렸고 후속 task는 docs/followups.md 10번(본문 현행화 → currentVersionDocuments로 이동).
이 PR 이후에도 이 문서는 v0.40.0 그대로다.

검증

• 새 테스트 8건(tests/docs-version-drift.test.mjs) — 모듈 부재로 red 확인 후 구현. 일치·낡은 표지·표지 제거·묶음 배너·주석 가림·분류 4종·미등록 현행 문서·낡은 제외·실제 레포 무드리프트
• npm test tests 1059 · pass 1058 · fail 0 (+ perf 1/1), npm run docs:check 통과
• 음성 확인: index.html 최신 항목을 지우면 docs:check가 newest what-changes entry이(가) 0.44.1 — package.json은 0.44.2로 실패
• 리뷰: codex(scope=diff) P2 3건 — 속성 붙은 태그 미인식·주석 가림은 수정, footer 속 타 제품 버전 오분류는 fail-loud 방향이라 의도로 유지(artifact Reviews)

알려진 한계

• 표지 번호만 본다 — 🆕 배너 산문이 이번 릴리스를 제대로 설명하는지는 사람 몫.
• 릴리스 bump 직후 표지를 고치기 전까지 npm test·docs:check가 빨갛다(what-changes 테스트와 같은 성질, 절차 5단계 순서와 일치).

🤖 Generated with Claude Code