[DONE] 정리 2단계 PR 10 — BOM·묶음만 고친 PR 에서도 어긋남 검사와 직접 쓴 글 잠금이 돈다

[patternflow-bot]

ops / https://claude.ai/code/session_01DyQnQUJ2K2X8ya4UcujAYC

정리 2단계 계획서 표의 PR 10 이다. 지금까지 어긋남 검사(check:drift)는 웹 CI 안에서만 돌아서 BOM·빌드 가이드·펌웨어 묶음만 고친 PR 에서는 돌지 않았고, 직접 쓴 글 잠금(check:human-lock)은 어느 PR 에서도 돌지 않았다. 새 워크플로 하나가 모든 PR 에서 둘을 엄격하게 돌린다. 머지하면 PR 마다 "Drift checks" 줄이 하나 생기고, 어긋나거나 잠긴 글의 낱말이 바뀌면 그 줄이 빨개진다.

좋아지는 것: 무엇을 고친 PR 이든 어긋남과 직접 쓴 글 고침이 머지 전에 빨개진다 — 틀어진 채 안 들어간다

할 일

• 계획서(docs/investigations/2026-10-cleanup-step2-plan.md) 표의 PR 10 줄, 소견 1·2·4, D2·D5·D6, k10 과 docs/rfc-cleanup.md §2.1·§2.4·§2.9·§2.11 을 읽는다
• 먼저 머지된 형제 PR 이 k10 에 남긴 말을 모은다: [DONE] 정리 2단계 PR 2 — GitHub 절대 주소 링크 118개가 닿는지 보는 검사를 단다 #26(태그엔 fetch-depth: 0, strict), [DONE] 정리 2단계 PR 3 — BOM 이 빌드 가이드 부품표나 회로도와 어긋나면 CI 가 빨개지는 검사 둘을 단다 #28(pdftotext 없으면 poppler 설치), [DONE] 정리 2단계 PR 8 — 일지·릴리스 노트·README 이야기처럼 직접 쓴 글의 낱말을 바꾼 PR 은 잠금 검사에 걸린다 #27(PF_LOCK_BASE 에 base SHA)
• 표가 PR 10 에 적은 파일 하나만 만든다: .github/workflows/drift.yml (+70)
• actionlint 로 문법을 본다
• CI 와 같은 조건(전체 이력·태그·pdftotext·strict)에서 로컬로 돌려 통과를 보고, 일부러 빠뜨리거나 고친 판 넷이 빨개지는 것을 본 뒤 되돌린다
• typecheck, lint, doc-map 을 돌린다(CSV 는 되돌린다)
• 이 PR 에서 새 워크플로가 GitHub 에서 실제로 돈다: b5f24c5 에서 success
• dev 를 merge 한다(be1c06f 그대로라 이미 최신)

한 일

.github/workflows/drift.yml, 이름은 "Drift checks", 작업 하나(check):

• 언제: 모든 pull_request(경로 거르개 없음), 그리고 main 으로의 push. 웹 CI 는 web/**·hardware/case/** 에서만 시작한다(소견 1).
• 권한: contents: read, issues: read.
• actions/checkout@v4 에 fetch-depth: 0: 절대 링크가 가리키는 태그(v1.0.0 부터 v3.1.0)와 잠금 검사가 견줄 base 커밋을 가져온다.
• Node 20, web/ 에서 npm ci(web-ci 와 같은 캐시 설정).
• pdftotext 가 없으면 poppler-utils 를 깐다. check:bom-schematic 이 회로도 글자 층을 읽는 데 쓴다.
• npm run check:drift: 작업 전체에 PF_DRIFT_STRICT=1, 이 단계에 GH_TOKEN: ${{ github.token }}(k6 의 gh api 몫).
• PR 일 때만 npm run check:human-lock, PF_LOCK_BASE: ${{ github.event.pull_request.base.sha }}. web/scripts/human-lock.ts 가 있을 때만 돌고, 앞의 어긋남 단계가 빨개도 돈다(!cancelled() 이고 npm ci 가 성공했을 때). 한 번 push 로 둘 다 보이게 하려고.

바뀐 줄: 1 파일, +70 −0.

증거

GitHub 에서 이 PR 의 b5f24c5 로 돈 "Drift checks"(job 116190762131): 모든 단계 success. 단계 시간은 checkout 10초, npm ci 2분 7초(캐시가 비어 있던 첫 판. 끝에 캐시를 저장했다), pdftotext 설치 17초, 어긋남 4초, 잠금 2초. 로그에서:

env:
  PF_DRIFT_STRICT: 1
  GH_TOKEN: ***
── bom-schematic
designators: same
  hardware/bom/bom_v3.9.csv (9): C11, J1, J3, J4, SW1, SW2, SW3, SW4, U1
  hardware/pcb/schematic.pdf (9): C11, J1, J3, J4, SW1, SW2, SW3, SW4, U1
── links-absolute
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)
0 do not resolve
...
passed   bom
passed   bom-schematic
passed   editions
passed   features
passed   links-absolute
passed   presets
── Run npm run check:human-lock
  PF_LOCK_BASE: be1c06f569816487d00b9703ba7696b9a5a18a69
base: be1c06f (PF_LOCK_BASE)
locked: 74 journal files, 33 release files, docs/manifesto.md, 3 README sections, Part 1 of 2 RFCs, 166 roadmap strings, 0 paths in docs/.human-written
this diff touches 0 locked files
check:human-lock: no locked words changed

웹 CI 의 check:ci 에서는 회로도 비교가 skipped(pdftotext 없음)로 지나가던 것(#28 로그)이 여기서 처음 실제로 비교된다.

로컬(b5f24c5, web/, 전체 이력과 태그 28개, pdftotext 있음):

• actionlint 1.7.12 .github/workflows/drift.yml: 출력 없음, exit 0.
• PF_DRIFT_STRICT=1 npm run check:drift: 위와 같은 여섯 줄 passed, exit 0.
• PF_DRIFT_STRICT=1 PF_LOCK_BASE=$(git rev-parse origin/dev) npm run check:human-lock: no locked words changed, exit 0.
• npm run typecheck: exit 0. npm run lint: exit 0, ✖ 12 problems (0 errors, 12 warnings)(원래 있던 src/ 경고).
• git fetch --tags 뒤 npm run doc-map: 1071 links from 214 files, 0 do not resolve. 새 행 다섯은 dev 의 5단계 계획서와 editions.ts 것이라 이 PR 과 무관하고, 두 CSV 는 git checkout 으로 되돌렸다.

워크플로의 각 부분이 왜 있는지, 빼거나 어긋나게 고친 판(버리는 클론·worktree 에서 돌리고 지움):

#	판	결과
1	fetch-depth: 0 없이: git clone --depth 1 --no-tags, strict	links-absolute failed, exit 1
1′	같은 클론, strict 없이	passed links-absolute, exit 0 — strict 가 없으면 태그 없는 CI 가 조용히 지나간다
2	pdftotext 가 없는 PATH, strict	bom-schematic failed, exit 1
3	BOM 의 J4 수량 1→2 만 고침	웹 CI 경로(web/**·hardware/case/**)에 맞는 파일 없음 = 웹 CI 가 안 돈다. 이 워크플로의 check:drift 는 failed bom, exit 1
4	docs/manifesto.md 한 낱말(same→very)	check:human-lock changed, exit 1
5	PF_LOCK_BASE 가 클론에 없는 커밋	exit 1

1번:

24 not read: this clone lacks v1.0.0, v2.0.0, v2.1.0, v3.0.0, v3.1.0; run git fetch --tags
PF_DRIFT_STRICT=1, so a link not read fails
links-absolute: failed

2번:

designators: skipped, pdftotext is not installed (poppler-utils)
PF_DRIFT_STRICT=1, so a skip fails
failed   bom-schematic

3번:

on the board: drift
  only in hardware/bom/bom_v3.9.csv: J4: 2 × TB002-500-02BE
  only in BUILD_GUIDE.md: J4: 1 × TB002-500-02BE
failed   bom

4번:

changed  docs/manifesto.md
           base  docs/manifesto.md:5  …t it.* This document is public for the «same» reason the schematics are. If you bu…
           head  docs/manifesto.md:5  …t it.* This document is public for the «very» reason the schematics are. If you bu…
check:human-lock: 1 locked text changed

실행법

CI 와 같게 로컬에서:

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

GitHub 에서는 PR 의 Checks 탭 "Drift checks / check".

가정

• 기준 브랜치는 dev(머리말). 표가 PR 10 에 적은 .github/workflows/drift.yml 하나만 만들었다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV 는 안 고쳤다. 라벨 cleanup·step-2 는 포크에 없어서 달지 않았다(D7).
• push 는 계획서대로 main 에서만 돈다. 포크의 dev 는 PR 로만 들어오니 PR 에서 이미 돈다.
• 잠금 단계는 계획서가 「한 단계」라 해서 작업을 나누지 않았다. 다만 어긋남 단계가 빨개도 돌게 했다. 아니면 어긋남을 고쳐 다시 push 한 뒤에야 잠금 결과를 보게 된다.
• hashFiles('web/scripts/human-lock.ts') 조건은 계획서 그대로 두었다. 포크 dev 에는 k8 이 이미 있지만, 원래 레포에는 hub 가 PR 을 하나씩 지어 보내니 k10 이 k8 보다 먼저 들어갈 수 있다. 그때 잠금 단계는 건너뛰고 빨개지지 않는다.
• PF_DRIFT_STRICT=1 은 작업 전체에 두었다. 잠금 단계에서는 PF_LOCK_BASE 가 늘 있으니 결과가 달라지지 않지만, [DONE] 정리 2단계 PR 8 — 일지·릴리스 노트·README 이야기처럼 직접 쓴 글의 낱말을 바꾼 PR 은 잠금 검사에 걸린다 #27 이 그 단계에도 주라고 남겼다.
• Node 20 은 계획서와 web-ci 그대로다. 러너가 「checkout@v4·setup-node@v4 가 Node 20 을 쓴다」는 경고를 찍는데, web-ci 도 같고 이 PR 몫이 아니다.
• check:voice 는 넣지 않았다(D6, Q14 기본값).
• 시작 커밋 글에 「매주」라고 잘못 썼다(이 워크플로는 일정으로 돌지 않는다). 빈 커밋이고, force push 를 하지 않으려고 그대로 두었다. 처음 PR 제목의 「정해진 때마다」도 같은 잘못이라 고쳤다.

for another k

• k6: check:drift 단계에 GH_TOKEN 이 있고 issues: read 다. gh 는 ubuntu-latest 에 깔려 있다. engmung/Patternflow 는 공개 레포라 포크의 토큰으로도 읽힐 것이고, k6 이 머지되면 이 워크플로가 첫 실제 실행이다(계획서 k6).
• k11·k12: 워크플로 이름 "Drift checks", 작업 check. 모든 PR 과 main push 에서 check:drift 를 strict 로, PR 에서만 check:human-lock 을 base SHA 로 돌린다. 한 줄로: 「drift.yml runs check:drift strictly on every pull request, and check:human-lock against the pull request's base」.
• k13: §2.4 의 「run in CI」는 이 워크플로다. 지금 여섯 검사가 strict 로 통과한다(roadmap·changelog 는 아직 파일이 없어 러너가 돌리지 않는다).

Changelog

Web

• Every pull request runs the drift checks and the text lock, whatever it touches. .github/workflows/drift.yml (Drift checks) runs check:drift on every pull request and on push to main; Web CI starts only on web/ and hardware/case/, so a pull request that edits only the BOM or a bundle never ran it. It fetches the tags and installs pdftotext and runs with PF_DRIFT_STRICT=1, so a check that cannot read a side fails instead of skipping. On a pull request it also runs check:human-lock against the base commit.

Upstream

• What: Add .github/workflows/drift.yml (Drift checks): npm run check:drift with PF_DRIFT_STRICT=1 on every pull request and on push to main, with full history, tags and pdftotext; on a pull request, npm run check:human-lock against the base SHA.
• Checks: actionlint clean; npm run typecheck, npm run lint (0 errors), strict npm run check:drift (6 passed) and npm run check:human-lock pass; a shallow clone, no pdftotext, a BOM-only edit and a locked word edit each fail it. npm run doc-map: 0 unresolved, CSVs restored.
• Docs map: none

🤖 Generated with Claude Code

https://claude.ai/code/session_01DyQnQUJ2K2X8ya4UcujAYC