[DONE] 정리 4단계를 PR 스물넷으로 나눈 계획서 — 같이 열릴 수 있는 PR 끼리는 파일이 안 겹친다

[patternflow-bot]

dev / https://claude.ai/code/session_01SG78HSjf3bAZr3jNp6Jr4L

정리 4단계(계약 벡터 다섯과 가상 패널)를 정찰해서 PR 스물넷으로 나눈 계획서를 썼다. 머지하면 k1(가이드의 DeviceSim 보강)과 k2(가상 패널 뼈대)를 바로 맡길 수 있고, 둘이 머지되면 REST 부터 전송마다 갈래가 열린다. 정찰해 보니 RFC 가 말한 web/src/lib/harness/ 는 없고 가이드의 DeviceSim 이 이미 펌웨어 규칙을 흉내 내고 있어서, 가상 패널은 그 위에 소켓을 붙이는 꼴로 잡았다.

좋아지는 것: 없음

체크리스트

• docs/rfc-cleanup.md §2.6 · §2.1 · §2.8–§2.13 과 §2.13 답 읽기
• 진행 기록 · 1·2·3단계 계획서 읽기. docs/voice.md 는 일하는 사이 dev 에 들어와([DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다 #18) merge 해서 그대로 따랐다
• 정찰: 계약 다섯(REST·OSC·MIDI·MQTT·오디오 WS)과 펌웨어 구현, 웹 하네스·DeviceSim, 포트, 의존성, 프리셋, CI
• docs/investigations/2026-10-cleanup-step4-plan.md: 맨 위 표에 k · 고칠 파일 · 먼저 머지될 k · §2.13 번호
• 표를 스크립트로 읽어, 같이 열릴 수 있는 두 줄에 같은 파일이 없는지 확인
• docs/rfc-cleanup-progress.md 표의 4단계 줄을 planned 와 계획서 링크로
• 링크 검사 · doc map 돌림(CSV 는 되돌림) · 글투 검사(금지어·대시·굵은 글씨)
• dev merge(e3b977f, [DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다 #18 이 들어옴. 마지막 fetch 에서 Already up to date)

한 일

• 계획서 docs/investigations/2026-10-cleanup-step4-plan.md (영어 295줄, 2·3단계 계획과 같은 꼴). 구현은 하지 않았다.
• PR 표 (파일까지는 계획서 맨 위 표)
  • 기반: k1 DeviceSim 에 소켓이 읽고 쓸 것(버스·레인 값, 손이 아닌 노브 움직임, 채널·레인 하나 풀기), k2 가상 패널 뼈대(start(), 수동 시계, /frame.png, /vp/* 고정 경로, 전송을 붙이는 이음매, npm 이름 전부), k3 벡터 형식과 재생 라이브러리
  • REST(답 3: 먼저): k4 장치 상태 경로, k5 패턴 경로, k6·k7 벡터와 check:rest-vectors
  • k8 check:virtual-panel: 펌웨어 프리셋 34개가 가상 패널에서 예외 없이 돈다(calib 은 FIRMWARE_ONLY)
  • MQTT k9–k12 · OSC k13–k14 · MIDI k15–k18 · 오디오 WS k19–k20: 전송마다 「가상 패널 쪽」 PR 과 「벡터 + 재생 스크립트」 PR 을 나눴다. 벡터는 스펙만 보고 전송과 나란히 쓸 수 있고, 전송 뒤에 머지한다
  • k21 AGENTS.md, k22 트리 지도 문서, k23 스펙이 스스로 어긋난 줄 고치기(창작자가 정한 줄만), k24 4단계 닫기
  • §2.13 번호: REST 줄(k4–k7)은 3, 나머지 —
  • 같이 고칠 자리: check:ci 와 .github/ 는 아무도 안 고친다. 2단계 k1 러너가 web/scripts/drift/ 의 파일을 저절로 돌리고, 2단계 k10 워크플로가 모든 PR 에서 엄격하게 돌린다. web/package.json 은 k2 가 이름을 한 번에 다 넣고 뒤 PR 은 안 건드린다
• 정찰에서 나온 것
  1. web/src/lib/harness/ 는 없다. 패턴은 web/src/lib/pattern/harness.ts 의 PatternRuntime 에서 돌고, 가이드의 DeviceSim 이 버스(클릭당 10, 250 ms 유예)·레인(500 ms 해제, 손 5초)·잠자기·선택을 이미 흉내 낸다. 다만 버스·레인 값을 밖에 안 보이고, 노브를 움직이는 길은 「손」(turn) 하나다
  2. /api/status 의 knobs 는 손으로 돌린 클릭만 센다(patternflow.ino:1214). OSC 델타, MIDI CC 24–27, MQTT knob/N, 오디오 d= 는 거기 안 보인다. 그래서 벡터가 「패턴이 받은 것」을 읽는 고정 경로(/vp/state)를 따로 둔다
  3. 포트 80·81 은 1024 아래라 Actions 러너(루트 아님)에서 못 연다. 가상 패널 기본값은 펌웨어 번호, 시험은 빈 포트(0)
  4. rest-api.md 가 스스로 어긋나는 곳이 여덟(HTTP 로 노브를 못 쓴다 vs POST /api/params, select 가 바뀌기 전 상태를 준다 vs 예시, 오류는 JSON vs 일반 텍스트 404 등). 벡터는 그 경로를 정의한 절을 따른다
  5. 펌웨어가 스펙과 다른 곳: OSC 실수 반올림, MIDI 상대 CC 가 binary offset(스펙 40줄은 two's complement), MQTT 빈 param 이 250 ms 안엔 안 풀림, 오디오 a=-0.5 가 다음 레인으로 밀림, 5초 손 붙잡기가 손 말고 모든 델타에 걸림 등. 벡터는 스펙대로, 차이는 PR 마다 「for an issue」 로
  6. 새 의존성 없이 된다: Node 내장 http·dgram·net·crypto·zlib 로 다섯 전송과 PNG 를 쓴다. lockfile 에 ws 는 다른 패키지가 끌고 온 것뿐이다
• 창작자에게 물을 것 (계획서 끝. 3단계 계획의 25 다음 번호, 모두 기본값 있음)
  26. 벡터 PR 이 찾은 펌웨어 차이를 누가 이슈로 여나(기본: 창작자가 PR 목록으로 원래 레포에) · 27. 스펙이 스스로 어긋나면 그 경로의 절이 이기나(기본: 예, k23 이 다른 줄을 고침) · 28. 5초 손 붙잡기: 스펙은 손, 펌웨어는 모든 델타(기본: 이슈, 스펙 유지) · 29. 같은 벡터를 실제 패널에도 돌릴까(기본: 이번 단계엔 안 함)

증거

$ python3 table_check.py docs/investigations/2026-10-cleanup-step4-plan.md .   # 표를 읽어 k 사이 순서를 따짐
24 rows; cycles: none
rows sharing a file without an order between them: none
files in more than one row: {'tools/virtual-panel/README.md': [2, 22]}   # k22 는 k2 뒤
wait on nothing: [1, 2]
named paths in the table that do not exist yet: 31   # 전부 백틱. 마크다운 링크는 ../rfc-cleanup.md, ../voice.md 둘(있는 파일)

$ python3 .github/scripts/check_links.py
all 676 relative links resolve
$ git fetch --tags && (cd web && npm ci && npm run doc-map)
1064 links from 212 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
$ git checkout docs/investigations/2026-10-doc-map.csv docs/investigations/2026-10-doc-parity.csv   # CSV 는 k24 만 커밋

# 글투: voice-banned.txt 의 21개 grep → 0, 표 칸 밖의 대시(—) → 0, 굵은 글씨 → 0

# 정찰 숫자 대조
$ grep -n "input.knobs\[i\] = getClicks" firmware/patternflow/patternflow.ino
1214:    input.knobs[i] = getClicks(LOGICAL_TO_PHYSICAL_KNOB[i]);
$ sed -n 287p firmware/patternflow/features/midi/core_midi.h
    pendingDelta[cc - PF_MIDI_CC_REL_BASE] += (int)value - 64;
$ grep -n "PF_OSC_REMOTE_PORT\|PF_OSC_LOCAL_PORT" firmware/patternflow/features/osc/osc_config.h
38:#define PF_OSC_REMOTE_PORT 9000
41:#define PF_OSC_LOCAL_PORT 9001
$ ls firmware/patternflow/presets/*.h | wc -l
35

$ git diff --stat origin/dev...HEAD
 docs/investigations/2026-10-cleanup-step4-plan.md | 295 +++
 docs/rfc-cleanup-progress.md                      |   2 +-
 2 files changed, 296 insertions(+), 1 deletion(-)      # 300줄 안

• 펌웨어 · web/src 무변경이라 §2.1 의 빌드 · 웹 명령은 해당 없다.

실행법

계획서만 있는 PR 이라 돌릴 것이 없다. 읽을 곳은 docs/investigations/2026-10-cleanup-step4-plan.md 맨 위 「The PRs」 표다. 3단계가 닫히면(§2.12) 총괄이 k1·k2 를 먼저 맡긴다. k2 가 머지되면 k3·k5, 둘 다 머지되면 k4·k9·k13·k15·k19 가 열린다. 그 뒤엔 「merges after」 가 다 머지된 줄을 다섯 개 안에서 맡기면 된다.

가정

• 「진행 기록의 앞 단계 줄」은 표의 4단계 줄로 읽었다([DONE] 정리 2단계를 PR 열넷으로 나눈 계획서 — 어느 셋을 같이 맡겨도 파일이 안 겹친다 #19·[DONE] 정리 3단계를 PR 스물일곱으로 나눈 계획서 — 같이 열릴 수 있는 PR 끼리는 파일이 안 겹친다 #20 이 자기 단계 줄만 고친 것처럼). 「Where it stands」 줄은 닫는 PR 몫이라 두었다.
• k 는 1·2·3 에서 그치지 않고 24까지다. 「PR 하나에 300줄, 관심사 하나」(§2.1(5))를 지키면서 전송 다섯과 벡터 다섯을 담으면 셋으로는 안 된다. 「셋이 같이 해도」는 「같이 열릴 수 있는 어느 줄끼리도 파일이 안 겹친다」로 읽었고, 표 검사 스크립트로 확인했다.
• RFC 가 이 단계에 정한 일을 표의 k 에 다 걸었다: 벡터 폴더 다섯(k6·k7, k11·k12, k14, k17·k18, k20), 재생 스크립트 다섯(같은 k), 가상 패널과 /frame.png(k2), 다섯 전송(k4·k5, k9·k10, k13, k15·k16, k19), 하네스를 쓴다(k1, D1), 프리셋 전부 돌기(k8), 다른 크기는 §2.7 에서 한 줄(D1), 펌웨어 차이는 이슈(D9, 질문 26), 「done when」과 §2.12 셋째 관문 확인(k24). §2.13 답 3(REST 먼저)은 순서와 k4–k7 의 번호로, 답 4(메이저 업데이트 안 함)는 이 단계가 의존성을 아예 안 더하는 것(D2)으로 지켰다.
• RFC 가 적은 web/src/lib/harness/ 는 없어서 실제 하네스(PatternRuntime)와 DeviceSim 을 쓰기로 했다. 그 폴더를 새로 만들거나 옮기지 않는다.
• 「없는 §2.9 잠금·§2.10 글투 검사」는 2단계 계획의 k8·k9 가 맡았다. 다시 넣지 않고, 4단계 PR 은 잠긴 글을 안 고치고 더한 글에 글투 검사를 돌린다고만 적었다(파일 이름은 백틱).
• CHANGELOG.md 는 고치는 PR 이 없다. 각 PR 의 변경 줄은 본문 ## Changelog 로 간다. AGENTS.md 는 k21 하나만. .github/ 는 고칠 일이 없어서 줄이 없다(2단계 drift.yml 이 모든 PR 에서 돈다).
• 스펙이 스스로 어긋나는 곳은 「그 경로를 정의한 절이 이긴다」를 기본으로 하고, 다른 줄 고치기(k23)는 창작자가 정한 줄만으로 묶었다(질문 27). 스펙이 말하지 않는 것(rN, 실수 반올림 규칙)엔 벡터를 안 만든다.
• 펌웨어와 스펙의 차이는 소스를 읽어서 찾았다(정찰용 하위 에이전트 둘 + 직접 대조). 이 환경엔 패널이 없어서 실제 장치로 돌려 보지는 않았다.
• 이슈는 이 세션이 원래 레포에 쓸 수 없어서, 벡터 PR 본문의 「for an issue」 목록으로 두고 질문 26 으로 물었다.
• docs/voice.md 가 일하는 사이 dev 에 들어와([DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다 #18) merge 하고 그 글투를 따랐다: 절 사이 대시 없음, 금지어 없음, 굵은 글씨 없음, 여는 말·맺는 말 없음. 창작자는 대명사 없이 「the maintainer」, 질문의 기본값에서만 「you」.
• 계획서는 영어로 썼다. docs/investigations/ 의 다른 기록이 영어다.

Changelog

Docs

• Cleanup step 4 is planned. docs/investigations/2026-10-cleanup-step4-plan.md cuts §2.6 into twenty-four PRs, no two of which edit a file while both can be open, and records what scouting found: the virtual panel can be the guide's DeviceSim behind sockets, /api/status shows no knob delta that arrives over OSC, MIDI, MQTT or the audio socket, and rest-api.md contradicts itself in eight places a vector has to choose between.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SG78HSjf3bAZr3jNp6Jr4L