[DONE] 정리 2단계 PR 8 — 일지·릴리스 노트·README 이야기처럼 직접 쓴 글의 낱말을 바꾼 PR 은 잠금 검사에 걸린다

[patternflow-bot]

studio / https://claude.ai/code/session_01YDk7JRDmTHg8hV22rdfCih

정리 2단계 계획서 표의 PR 8 이다. 일지, 매니페스토, 릴리스 노트, README 의 이야기 세 절, RFC 의 Part 1, 로드맵 설명처럼 직접 쓴 글을 PR 이 한 낱말이라도 바꾸면 빨개지는 검사(check:human-lock)를 넣는다. 마크업이나 링크·그림 경로만 바꾸거나 글을 그대로 옮기면 통과한다. 머지하면 바로 돌릴 수 있고, 모든 PR 에서 돌게 하는 것은 같은 단계의 워크플로 PR(k10)이다.

좋아지는 것: 직접 쓴 글의 낱말을 바꾼 PR 은 검사에 걸린다 — 쓴 그대로 남는다

할 일

• 계획서(docs/investigations/2026-10-cleanup-step2-plan.md) 표의 PR 8 줄, 소견 10, D2·D5, k8 과 docs/rfc-cleanup.md §2.1·§2.9·§2.11 을 읽는다
• 표가 PR 8 에 적은 세 파일만 고친다: web/scripts/human-lock.ts, web/scripts/lib/pr-base.ts, docs/.human-written
• 잠긴 글은 한 글자도 안 고친다
• 일부러 고친 판 열다섯 가지로 빨개질 때와 통과할 때를 보이고 되돌린다
• typecheck, lint, check:drift, check:ci, doc-map 을 돌린다(CSV 는 되돌린다)
• §2.1(5) 의 300줄 안에 둔다: 3 파일 +293
• dev 를 merge 한다(898c46f, [DONE] 정리 2단계 첫 PR — 드리프트 검사를 한 번에 돌리는 틀과, /features 목록이 기능 폴더와 어긋나면 CI 가 빨개지는 첫 검사 #25·[DONE] 정리 2단계 PR 2 — GitHub 절대 주소 링크 118개가 닿는지 보는 검사를 단다 #26·[DONE] 정리 2단계 PR 3 — BOM 이 빌드 가이드 부품표나 회로도와 어긋나면 CI 가 빨개지는 검사 둘을 단다 #28·[DONE] 정리 2단계 PR 4 — /editions 진열대가 펌웨어 묶음·이미지 폴더·릴리스 스크립트와 어긋나면 CI 가 빨개지는 검사 #29 까지)
• GitHub CI 를 본다: c847a92 에서 check·build 모두 success. [DONE] 정리 2단계 PR 4 — /editions 진열대가 펌웨어 묶음·이미지 폴더·릴리스 스크립트와 어긋나면 CI 가 빨개지는 검사 #29 를 merge 한 fd0d23e 는 로컬 검사를 다시 돌렸다

한 일

• web/scripts/human-lock.ts (npm run check:human-lock, 이름은 [DONE] 정리 2단계 첫 PR — 드리프트 검사를 한 번에 돌리는 틀과, /features 목록이 기능 폴더와 어긋나면 CI 가 빨개지는 첫 검사 #25 가 package.json 에 넣어 두었다): 소견 10 의 자리를 잠근다. 일지 폴더의 모든 파일, docs/manifesto.md, docs/releases/*.md, README 의 세 절(## 제목에서 다음 ## 까지), docs/rfc-*.md 의 Part 1(다음 같은 단계 제목까지), 로드맵의 detail·detailKo(TypeScript 파서로 읽어 노드 id 로 짝짓는다), 그리고 docs/.human-written 의 경로. 기준 판과 작업 트리 판을 평문으로 견준다. 평문은 마크다운·MDX 문법(제목·인용·목록 표시, 강조·코드 표시, 펜스, 표 파이프, 가로줄, 주석, 엔티티, 태그, 링크 대상, 맨 URL, 프런트매터 키)과 공백을 모두 뺀 글자다. 문법을 지우지 않고 같은 길이의 빈칸으로 바꿔서 글자마다 원래 자리를 기억하고, 바뀐 곳을 파일:줄 과 함께 원문으로 보여 준다(«» 가 바뀐 부분).
• 사라진 잠긴 글은 이 diff 가 더하거나 고친 파일(추적 안 된 새 파일 포함) 어디에 평문 그대로 있으면 옮김으로 보고 통과하되 「창작자 승인이 필요하다」고 찍는다. 어디에도 없으면 removed 로 실패한다. 기준에 없던 잠긴 파일은 new 로 통과한다.
• web/scripts/lib/pr-base.ts: D5 의 기준 찾기(PF_LOCK_BASE → origin/dev 와의 merge-base → origin/main → 없으면 skip)와 그 뒤로 바뀐 파일 목록, 커밋 시점 파일 읽기. k9(voice-lint)도 같은 기준을 쓰게 따로 뺐다.
• docs/.human-written: 주석 한 줄, 경로 없음(답 5).

바뀐 줄: 3 파일, +293 −0.

증거

지금 브랜치(fd0d23e, web/):

• npm run check:human-lock: exit 0

  base: 898c46f (the merge-base with origin/dev)
  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
  

  잠긴 수가 계획서 소견 10 과 같다(일지 74, 릴리스 33, README 세 절, RFC 둘, 로드맵 노드 83 × 2).
• npm run typecheck: exit 0. npm run lint: exit 0, ✖ 12 problems (0 errors, 12 warnings) — 모두 원래 있던 src/ 의 경고이고 새 파일에는 없다.
• npm run check:drift: passed bom, passed bom-schematic, passed editions, passed features, passed links-absolute, exit 0.
• npm run check:ci([DONE] 정리 2단계 PR 3 — BOM 이 빌드 가이드 부품표나 회로도와 어긋나면 CI 가 빨개지는 검사 둘을 단다 #28·[DONE] 정리 2단계 PR 4 — /editions 진열대가 펌웨어 묶음·이미지 폴더·릴리스 스크립트와 어긋나면 CI 가 빨개지는 검사 #29 를 merge 하기 전 5b9e13d 에서. 그 뒤 들어온 것은 drift 검사 셋이고 위에서 돌렸다): exit 0, Test Files 35 passed (35), Tests 478 passed (478).
• GitHub CI: c847a92 에서 build·check 두 작업 모두 success.
• git fetch --tags 뒤 npm run doc-map: 1070 links from 213 files → docs/investigations/2026-10-doc-map.csv, 0 do not resolve. 새 행 넷은 dev 의 5단계 계획서 것이라 이 PR 과 무관하고, 두 CSV 는 git checkout 으로 되돌렸다.

일부러 고친 판(버리는 worktree 에서 고치고 돌린 뒤 되돌림, 기준은 dev 의 merge-base):

#	고친 것	결과
0	없음	exit 0
1	일지 한 구절(「되게 큰 뱀이랑」→「아주 큰 뱀과」)	changed, exit 1
2	README 링크 경로·그림 경로·굵게 표시, 일지 cover 경로·figure class·img src	same, exit 0
3	일지 글을 git mv 로 새 이름에, 그림 경로도 바꿈	moved + 승인 문구, exit 0
4	릴리스 노트 파일 삭제	removed, exit 1
5	로드맵 노드의 status·issues 변경과 detailKo 한 낱말	detailKo 만 changed, exit 1
6	RFC Part 1 한 문장과 Part 2 한 문장	Part 1 만 changed, exit 1
7	README Story so far 를 추적 안 한 새 docs/story.md 로 옮기고 안내 한 줄	moved + 승인 문구, exit 0
8	README 절 제목 하나를 바꿈	removed, exit 1
9	새 일지 글	new, exit 0
10	.human-written 에 디렉터리 하나를 더하고 그 아래 파일 한 낱말	changed, exit 1
11	기준 판 목록에 있던 경로를 빼고 그 파일을 고침(PF_LOCK_BASE)	unlisted + changed, exit 1
12	PF_LOCK_BASE 가 없는 커밋	exit 1
13	기준 없음(origin 없는 클론)	skipped, exit 0
14	13 + PF_DRIFT_STRICT=1	exit 1

300줄로 줄이기 전 판과 줄인 판으로 열다섯 가지를 다 돌려, 출력이 base SHA 말고는 한 줄도 다르지 않은 것을 diff 로 봤다.

1번:

changed  web/content/journal/a-strange-dream.mdx
           base  web/content/journal/a-strange-dream.mdx:11  …긴 한데 금방 잊어버려 그런갑다 하고 있었는데, 방금 그 꿈이 생각났다. «되게 큰 뱀이랑» 지네가 나온 특이한 꿈이다. 어쩌면 자기 전에 집에서 그리마를 본 것 때문…
           head  web/content/journal/a-strange-dream.mdx:11  …긴 한데 금방 잊어버려 그런갑다 하고 있었는데, 방금 그 꿈이 생각났다. «아주 큰 뱀과» 지네가 나온 특이한 꿈이다. 어쩌면 자기 전에 집에서 그리마를 본 것 때문…

check:human-lock: 1 locked text changed
Markup, layout and link and image paths may change in locked text; words may not. A typo is reported in the PR description, not fixed.
exit=1

5번:

changed  web/src/app/roadmap/roadmap-data.ts › pcb-proto-v0.detailKo
           base  web/src/app/roadmap/roadmap-data.ts:74  …조배터리를 들고 마포새빛문화숲에 나가 첫 영상을 찍었습니다. 반응이 «거의» 없었고, 그래서 케이스가 필요하다는 결론에 도달합니다.…
           head  web/src/app/roadmap/roadmap-data.ts:74  …조배터리를 들고 마포새빛문화숲에 나가 첫 영상을 찍었습니다. 반응이 «별로» 없었고, 그래서 케이스가 필요하다는 결론에 도달합니다.…
same     web/src/app/roadmap/roadmap-data.ts (165 of 166 locked strings)

7번:

moved    README.md › Story so far → docs/story.md, word for word
same     README.md (2 of 3 locked sections)

Moving locked text needs the maintainer's approval on the PR (docs/rfc-cleanup.md §2.9).
check:human-lock: no locked words changed
exit=0

11번:

unlisted docs/.human-written no longer names docs/EDITIONS.md; only the maintainer takes a path off it
changed  docs/EDITIONS.md
           base  docs/EDITIONS.md:1  …Features, compositions and edit«i»ons **How Patternflow is put together…
           head  docs/EDITIONS.md:1  …Features, compositions and edit«»ons **How Patternflow is put together…

check:human-lock: 1 locked text changed, 1 path taken off docs/.human-written

13·14번:

check:human-lock: skipped, no PF_LOCK_BASE, and no merge-base with origin/dev or origin/main
exit=0
check:human-lock: skipped, no PF_LOCK_BASE, and no merge-base with origin/dev or origin/main
PF_DRIFT_STRICT=1, so a skip fails
exit=1

실행법

cd web
npm ci
npm run check:human-lock                          # 기준: origin/dev 와의 merge-base
PF_LOCK_BASE=<base sha> npm run check:human-lock  # CI 처럼 기준을 정해서
PF_DRIFT_STRICT=1 npm run check:human-lock        # 기준을 못 찾으면 실패

가정

• 기준 브랜치는 dev(머리말). 표가 PR 8 에 적은 세 파일만 고쳤다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV 는 안 고쳤다. 라벨 cleanup·step-2 는 포크에 없어서 달지 않았다.
• check:ci 에는 넣지 않았다. 계획서대로 k10 의 워크플로가 PR 에서 PF_LOCK_BASE 를 넘겨 돌린다. 드리프트 러너 밖에서 npm run 으로 도니 skip 은 k1 의 75 가 아니라 0 으로 끝낸다(PF_DRIFT_STRICT=1 이면 1, D2 그대로). PF_LOCK_BASE 가 이 클론에 없는 커밋이면 skip 이 아니라 실패로 했다. 값이 틀린 것이라서.
• 300줄 상한(§2.1(5)): 처음 판이 395줄이라 동작은 그대로 두고 줄였다. 그 과정에서 HTML 엔티티는 풀어 읽던 것을 통째로 지우게 바꿨다(& ↔ & 를 바꾸면 걸린다. 드물고 안전한 쪽). 로드맵 문자열은 평범한 리터럴만 읽는다(지금 166개 모두 그렇다). 리터럴이 아니게 바뀌면 removed 로 걸린다.
• 평문: 태그의 alt·title·aria-label 값은 낱말이라 남긴다(마크다운 그림의 alt 와 맞춘다). 프런트매터 값은 글로 세고, 경로·URL 값만 뺀다. 그래서 draft·date 를 바꿔도 걸린다. 체크박스 [ ]/[x] 는 했는지 안 했는지의 기록이라 글로 남긴다. 밑줄은 낱말 가장자리에 붙은 것만 강조로 보고 지운다(preset_origin.h 같은 이름은 그대로).
• 옮김은 「이 diff 가 더하거나 고친 파일 어딘가에 평문이 그대로 있는가」로 본다. 옮긴 곳이 잠긴 자리가 아니면(예: docs/story.md) 다음 PR 부터는 잠기지 않는다. 그건 창작자가 docs/.human-written 에 더할 일로 남긴다.
• README 절 제목도 창작자의 글이라, 제목을 바꾸면 그 절은 removed 로 걸린다. Story so far 는 계획서대로 다음 ## 까지라 ### Sponsor 까지 잠긴다.
• RFC 는 docs/ 아래 rfc-*.md 중 「Part 1」 제목이 있는 것이다. 진행 기록(-progress.md)은 Part 1 이 없어 잠길 것이 없다. Part 1 의 끝은 다음 같은 단계 제목이다.
• 로드맵은 노드 id 로 짝짓는다. 노드 순서, status, issues 를 바꾸면 통과한다(k14 가 고칠 수 있는 것).
• docs/.human-written: 기준 판과 지금 판의 목록을 합쳐 잠근다. 목록에서 경로를 빼면 실패하게 했다. 계획서에 없는 동작이지만, 빼는 것만으로 잠금을 피해 갈 수 있어서다(Q13 기본값대로 창작자는 빨간 줄 위로 머지하면 된다). 디렉터리 경로는 그 아래를 다 잠근다.
• 잠긴 글의 오타는 찾아보지 않았다. 이 PR 은 잠긴 글을 건드리지 않는다.

for another k

• k9: import { findBase, changedSince, readAt, readNow, git, ROOT } from "./lib/pr-base". findBase() 는 { sha, from } 이나 { sha: null, why, fatal } 을 돌려준다(fatal 은 PF_LOCK_BASE 가 틀렸을 때). 더한 줄은 git(["diff", "-U0", sha]) 로 읽으면 된다.
• k10: 이 검사는 PF_LOCK_BASE: ${{ github.event.pull_request.base.sha }} 와 fetch-depth: 0 이 있어야 기준을 읽는다. 그 단계에도 PF_DRIFT_STRICT=1 을 주면 기준을 못 찾을 때 통과하지 않는다.
• k11·k12: 명령 이름은 npm run check:human-lock, 설명 한 줄은 「잠긴 글의 낱말이 바뀌면 실패, 마크업·경로·그대로 옮김은 통과」.

Changelog

Web

• check:human-lock fails a pull request that changes a word of the maintainer's own writing. The journal, the manifesto, the release notes, the README's three story sections, Part 1 of each RFC and the roadmap's detail and detailKo strings are compared with the pull request's base as plain text, with the Markdown, MDX and whitespace taken out. Markup, link paths and image paths can change; a typo fix cannot. A locked file moved word for word passes, and the run says the move needs the maintainer's approval. docs/.human-written takes more paths, one per line.

Upstream

• What: Add check:human-lock (web/scripts/human-lock.ts): a PR that changes a word of the text rfc-cleanup.md section 2.9 locks fails it; markup, link and image path edits and verbatim moves pass. web/scripts/lib/pr-base.ts finds the PR base; docs/.human-written starts empty.
• Checks: npm run typecheck, npm run lint (0 errors), npm run check:ci, npm run check:human-lock (passes; seven throwaway word edits and a deletion fail it, markup-only edits and moves pass), npm run doc-map (1070 links, 0 unresolved, CSVs restored).
• Docs map: none

🤖 Generated with Claude Code

https://claude.ai/code/session_01YDk7JRDmTHg8hV22rdfCih