[DONE] 정리 2단계 PR 12 — CI 가 무엇을 돌리는지 적은 문서가 지금 CI 와 맞는다

[patternflow-bot]

lsh / https://claude.ai/code/session_015BBxbLQw4YT47XGgbhCeqz

정리 2단계 계획서 표의 PR 12 다. CI 가 무엇을 돌리는지 적은 문서 넷(CONTRIBUTING, web/README, web/ARCHITECTURE, docs/REPOSITORY)은 웹 CI 와 상대 링크 검사만 말했고, REPOSITORY 는 절대 링크를 CI 가 안 본다고 했다. 모든 PR 에서 도는 어긋남 검사와 직접 쓴 글 잠금(drift.yml)을 더해 적고, 절대 링크는 check:links-absolute 가 본다고 고쳤다. 머지하면 BOM 이나 일지만 고친 PR 이 왜 빨개지는지 기여자가 문서에서 찾는다.

좋아지는 것: 없음

할 일

• 계획서 표의 PR 12 줄과 k12, docs/rfc-cleanup.md §2.1·§2.4·§2.9·§2.10·§2.11, docs/voice.md 를 읽는다
• 먼저 머지된 형제 PR 이 k12 에 남긴 말을 모은다: [DONE] 정리 2단계 PR 10 — BOM·묶음만 고친 PR 에서도 어긋남 검사와 직접 쓴 글 잠금이 돈다 #32(k10, drift.yml 한 줄 설명), [DONE] 정리 2단계 PR 8 — 일지·릴리스 노트·README 이야기처럼 직접 쓴 글의 낱말을 바꾼 PR 은 잠금 검사에 걸린다 #27(k8, check:human-lock 한 줄 설명)
• 지금 CI 를 목록으로 만든다: web-ci.yml(web/·hardware/case/ 에서 lint·typecheck·build·check:ci, check:ci 끝이 check:drift), drift.yml(모든 PR, strict check:drift 와 PR 에서 check:human-lock), docs-links.yml(상대 링크)
• 표가 PR 12 에 적은 파일 넷만 고친다 (+16 −12)
• §2.1 검사와 doc-map 을 돌린다(CSV 는 되돌린다)
• 새 문장 둘이 참인지 버리는 고침으로 본다: 제목을 바꾸면 check:links-absolute 가, BOM 만 고치면 check:bom 이 빨개진다
• k9([DONE] 정리 2단계 PR 9 — 새로 쓴 글에 금지 낱말이나 셋 나열, 「이 문서는」 첫머리, 맺음 요약이 있으면 check:voice 가 줄마다 짚는다 #33) 의 voice-lint 로 더한 줄을 읽는다
• dev 를 merge 한다(1c231e4 그대로라 이미 최신)
• 이 PR 의 CI(Drift checks, Web CI, docs-links)가 3b14d6f 에서 셋 다 success

한 일

• CONTRIBUTING.md: 표의 웹 줄 CI 칸을 「lint, typecheck, check:ci (the smoke suites and the drift checks), next build」로. 표 아래에 한 문단: 어느 줄이든 모든 PR 이 drift 도 돌리고, 손으로 두 벌 지키는 것(BOM 과 빌드 가이드 부품표)이 어긋나거나 직접 쓴 글의 낱말이 바뀌면 빨개진다(§2.9 링크).
• web/README.md: 명령 목록에 check:drift, check:human-lock 두 줄을 더하고 check:ci 설명에 drift 를 넣었다(주석 칸을 다시 맞춰서 기존 넷 줄도 공백만 바뀐다). Contributing 문단의 CI 문장에 「모든 PR 에서 drift 검사와 check:human-lock」을 더했다.
• web/ARCHITECTURE.md: 테스트 문단에 drift 검사가 scripts/drift/ 의 check:* 이고 check:ci 끝의 check:drift 가 다 돌린다는 두 문장. CI 줄에 drift.yml 이 모든 PR 에서 check:drift 와 PR 기준으로 check:human-lock 을 돌리고, PF_DRIFT_STRICT=1 이라 책상에선 건너뛰는 쪽이 CI 에선 실패한다는 두 문장.
• docs/REPOSITORY.md: check_links.py 줄 뒤에 check:links-absolute 가 절대 링크를 모든 PR 에서 본다는 한 문장. 그 위 「none of them is checked by CI」를 「a pull request that breaks one fails check:links-absolute」로. .github/ 줄의 워크플로 목록에 「the drift checks」.

바뀐 줄: 4 파일, +16 −12.

증거

GitHub, 이 PR 의 3b14d6f: 「Drift checks / check」(job 116197638700), 「Web CI / build」(job 116197643922, lint·typecheck·build·check:ci), 「Docs point at files that exist / check」(job 116197638549) 셋 다 success.

로컬, 3b14d6f, web/, 태그 28개, pdftotext 있음:

$ python3 .github/scripts/check_links.py
all 683 relative links resolve
$ npm run typecheck        → exit 0
$ npm run lint             → ✖ 12 problems (0 errors, 12 warnings), exit 0 (원래 있던 src/ 경고)
$ PF_DRIFT_STRICT=1 npm run check:drift
passed   bom
passed   bom-schematic
passed   changelog
passed   editions
passed   features
passed   links-absolute
passed   presets
$ PF_DRIFT_STRICT=1 PF_LOCK_BASE=$(git rev-parse origin/dev) npm run check:human-lock
base: 1c231e4 (PF_LOCK_BASE)
this diff touches 0 locked files
check:human-lock: no locked words changed
$ git fetch --tags && npm run doc-map
1072 links from 214 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve

doc-map 에서 이 PR 몫의 새 행은 CONTRIBUTING.md,docs/rfc-cleanup.md,relative,29-human-written-text-lock,yes 하나다. 다른 새 행 다섯은 dev 의 5단계 계획서와 editions.ts 것(#32 와 같다). 두 CSV 는 git checkout 으로 되돌렸다.

새 문장이 참인지(버리는 고침, 커밋 전에 되돌림):

1. REPOSITORY 의 「a pull request that breaks one fails check:links-absolute」. BUILD_GUIDE.md 의 ## 10. Known Issues & Design Notes 를 ## 10. Known Issues 로:

118 absolute links from 26 files, against main at HEAD (94), v1.0.0 (4), v2.0.0 (1), v2.1.0 (8), v3.0.0 (8), v3.1.0 (3)
2 do not resolve
  web/src/components/guide/build/build.test.ts → BUILD_GUIDE.md#10-known-issues--design-notes (absolute-blob)
  web/src/components/guide/copy/build.ts → BUILD_GUIDE.md#10-known-issues--design-notes (absolute-blob)
links-absolute: failed
failed   links-absolute
exit 1

2. CONTRIBUTING 의 「every pull request also runs drift … the BOM and the parts table」. bom_v3.9.csv 의 J4 수량만 1→2(웹 CI 경로 밖):

on the board: drift
  hardware/bom/bom_v3.9.csv (7): … J4: 2 × TB002-500-02BE …
  BUILD_GUIDE.md (7): … J4: 1 × TB002-500-02BE …
failed   bom
exit 1

글투: #33(k9) 브랜치의 web/scripts/voice-lint.ts 를 잠깐 복사해 인자 없이(dev 이후 더한 줄) 돌리고 지웠다. 첫 판에 web/README.md:49 threes lint, typecheck, and on 이 걸려서, web-ci 단계를 npm 스크립트 이름(lint, typecheck, check:ci, build)으로 적어 고쳤다. 다시 돌리니 남은 것은 복사해 둔 voice-lint.ts 자기 주석(fast, simple, and reliable, 금지 예시) 하나뿐이다. 새 글에 문장을 잇는 줄표(—)와 금지어는 없다.

실행법

git fetch --tags
cd web && npm ci
PF_DRIFT_STRICT=1 npm run check:drift
PF_LOCK_BASE=$(git merge-base HEAD origin/dev) npm run check:human-lock
python3 ../.github/scripts/check_links.py

GitHub 에서는 PR 의 Checks 탭 「Drift checks / check」, 「Web CI / build」, 「Docs point at files that exist / check」.

가정

• 기준 브랜치는 dev(머리말). 표가 PR 12 에 적은 파일 넷만 고쳤다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV 는 안 고쳤다. 라벨 cleanup·step-2 는 포크에 없어서 달지 않았다(D7).
• 계획서는 CONTRIBUTING 의 「웹 줄」을 짚었지만 drift.yml 은 표의 모든 줄에서 돈다. BOM 이나 가이드만 고치는 사람이 웹 줄을 읽지 않으니 표 아래에 한 문단을 더했다. 웹 줄 칸은 「the check:* suites」가 check:human-lock·check:module 까지 가리키는 것처럼 읽혀서 check:ci 로 좁혔다.
• 계획서는 REPOSITORY 의 「check_links.py 줄」을 짚었다. 그런데 같은 절 첫 문장 「none of them is checked by CI」가 k2·k10 뒤로 틀린 말이라 그 구절도 고쳤다. 「grep 하라」는 그대로 둔다. 같은 PR 안에서 링크를 고치라는 말이라 여전히 맞다. .github/ 줄 워크플로 목록에도 drift 를 넣었다.
• check:voice 는 web/README 명령 목록에 넣지 않았다. voice-lint.ts 가 아직 dev 에 없어([DONE] 정리 2단계 PR 9 — 새로 쓴 글에 금지 낱말이나 셋 나열, 「이 문서는」 첫머리, 맺음 요약이 있으면 check:voice 가 줄마다 짚는다 #33 열림) 지금 적으면 실패하는 명령이 된다.
• README 의 「check:bom, check:editions and the others run one each」에서 check:roadmap 은 k6([DONE] 정리 2단계 PR 6 — /roadmap 노드 상태가 그 이슈의 열림·닫힘과 어긋나면 CI 가 빨개지는 검사 #34)이 머지될 때까지 「not written yet」으로 실패한다. 그 한 줄 때문에 이름을 다 늘어놓지는 않았다.
• docs/rfc-cleanup.md#29-human-written-text-lock 앵커는 check_links.py 가 보지 않아서(파일만 본다) doc-map 으로 닿는 것을 봤다.

for another k

• k9·k13: check:voice 가 dev 에 들어오면 web/README.md 명령 목록에 「npm run check:voice # by hand, before a PR with new prose; CI does not run it」 한 줄을 더할 수 있다. web/README 는 이 행 파일이라 k13 이 싣거나 따로 고친다.
• k11: AGENTS.md 의 drift 설명은 이 PR 의 web/ARCHITECTURE 문장과 같은 말로 맞추면 좋다(check:drift 는 check:ci 끝, drift.yml 에서 strict, check:human-lock 은 PR 에서).

Changelog

Docs

• The contributor docs say what CI runs on every pull request. CONTRIBUTING.md, web/README.md, web/ARCHITECTURE.md and docs/REPOSITORY.md now name drift.yml, which runs the drift checks and check:human-lock on every pull request whatever it touches. docs/REPOSITORY.md no longer says the absolute blob/main links go unchecked: check:links-absolute fails a pull request that breaks one.

Upstream

• What: Update CONTRIBUTING.md, web/README.md, web/ARCHITECTURE.md and docs/REPOSITORY.md to say that drift.yml runs check:drift and check:human-lock on every pull request, and that check:links-absolute checks the absolute links REPOSITORY.md called unchecked.
• Checks: npm run typecheck, npm run lint (0 errors), strict npm run check:drift (7 passed), npm run check:human-lock and check_links.py pass; a renamed BUILD_GUIDE heading fails check:links-absolute and a BOM-only edit fails check:bom.
• Docs map: adds one row, CONTRIBUTING.md to docs/rfc-cleanup.md at anchor 29-human-written-text-lock, which resolves; CSVs not committed.

🤖 Generated with Claude Code

https://claude.ai/code/session_015BBxbLQw4YT47XGgbhCeqz

---

Generated by Claude Code