[DONE] 정리 3단계 PR 7 — 펌웨어와 사이트가 같이 쓰는 값이 한 파일에 모이고, 낡으면 CI 가 빨개진다

[patternflow-bot]

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

정리 3단계 계획서 표의 PR 7 이다. 펌웨어와 사이트가 손으로 따로 적어 두던 패널·노브·버스 값을 shared/constants.json 한 곳에 모으고, 거기서 두 쪽 파일을 만드는 gen:shared 와 그 파일이 낡으면 CI 가 빨개지는 check:shared 를 넣었다. 아직 아무 코드도 두 파일을 읽지 않아 기기와 사이트는 그대로고, PR 8·9 가 두 쪽을 이 파일로 옮기면 20 대 24 디텐트 같은 어긋남이 한 곳에서 막힌다.

좋아지는 것: 없음

할 일

• 계획서 표의 PR 7 행(k7)과 D6·D7·발견 9·10, docs/rfc-cleanup.md §2.1·§2.5·§2.11, docs/voice.md 를 읽는다
• 표가 PR 7 에 적은 파일 여섯만 고친다 (+269, 300줄 안)
• gen:shared 를 두 번 돌려 같은 파일이 나오는지, check:shared 가 출력 둘의 손 고침·abi/pf_params.h 리터럴·build_module.py 에서 실패하는지 본다
• typecheck, lint, check:ci, 펌웨어 검사(check_boundaries.py·check_sources.py·check_abi_freeze.py), 잠금, 글투, doc-map 을 돌린다(CSV 는 되돌린다)
• 이 PR 의 CI 가 6196f86 에서 모두 success: Firmware builds(default·audio·performance·clock·midi), Core knows no features, Web CI, Drift checks
• dev 를 merge 한다(그새 PR 10 이 들어온 c836203 을 60f4231 로 merge. 겹치는 파일은 없고 typecheck·lint·check:drift·check:panels·check_boundaries.py 를 다시 돌려 통과)

한 일

• shared/constants.json: 계획서 D7 의 값. 패널 geometry 셋(128x64_SINGLE 1, 64x64_SINGLE 2, 64x64_CHAIN2 3, 각자 물리 크기와 체인)과 기본값, 노브 4·한 바퀴 24 디텐트·전 범위 2 바퀴, 디텐트당 엣지 4·롱프레스 1000 ms·버튼 디바운스 50 ms, 버스 최대 1000·클릭당 10. 키가 곧 두 쪽의 이름이고, 그룹마다 둔 "//" 메모가 두 출력의 주석이 된다.
• web/scripts/gen-shared.ts (npm run gen:shared): JSON 을 읽어 두 파일을 GENERATED 줄 아래 쓴다. 헤더는 PF_SHARED_<이름> 매크로, 모듈은 <이름> export 다. 캔버스 크기(RES_W·RES_H)는 물리 너비×체인, 물리 높이로 만든다. 값이 양의 정수가 아니거나 기본 geometry 가 목록에 없거나 id·이름이 겹치면 쓰지 않고 멈춘다. render() 를 내보내 검사가 같은 코드로 다시 만든다.
• web/scripts/drift/shared.ts (npm run check:shared): 두 출력을 메모리에서 다시 만든 것과 바이트로 비교하고, 다르면 다른 줄을 열 줄까지 찍는다. 만들 수 없는 사본 둘은 읽어서 JSON 과 비교한다. 얼어 있는 abi/pf_params.h 의 unit1000() 리터럴과 BUS_MAX, firmware/toolchain/build_module.py 의 PANEL_W·PANEL_H 와 기본 geometry 의 캔버스다. check:drift 가 scripts/drift/ 의 파일을 찾아 돌므로 check:ci 와 drift.yml 에 따로 적지 않아도 들어간다.
• firmware/patternflow/src/core_shared.h, web/src/lib/shared/constants.ts: gen:shared 가 쓴 그대로. 아직 아무 데서도 include·import 하지 않는다(k8·k9 몫).
• web/package.json: gen:shared, check:shared 두 줄.

증거

GitHub, 이 PR 의 6196f86: 「Firmware builds」 다섯 job(default 116268482231, audio, performance, clock, midi)이 build.sh 로 다섯 composition 을 빌드해 success, 「Core knows no features」 success, 「Web CI / build」(116268546050)의 Lint·Typecheck·Build·Smoke suites success. 「Drift checks / check」(116268481534)는 PF_DRIFT_STRICT=1 로 passed shared 를 포함해 아홉 검사 모두 passed, check:human-lock 도 통과했다.

로컬, web/, npm ci 뒤:

$ npm run gen:shared; sha256sum ...; npm run gen:shared; sha256sum -c
dc2ef0d93d28...  ../firmware/patternflow/src/core_shared.h
e2490f5d0d8d...  src/lib/shared/constants.ts
../firmware/patternflow/src/core_shared.h: OK
src/lib/shared/constants.ts: OK

$ npm run check:shared                        # HEAD
firmware/patternflow/src/core_shared.h: same as gen:shared writes
web/src/lib/shared/constants.ts: same as gen:shared writes
the bus maximum: same
  shared/constants.json BUS_MAX (1): 1000
  the literals in unit1000(), firmware/patternflow/abi/pf_params.h (1): 1000
the default panel's canvas: same
  shared/constants.json 128x64_SINGLE (2): PANEL_H 64, PANEL_W 128
  firmware/toolchain/build_module.py (2): PANEL_H 64, PANEL_W 128
passed   shared

# core_shared.h 의 DETENTS_PER_TURN 을 손으로 20 으로
firmware/patternflow/src/core_shared.h: stale, run npm run gen:shared in web/
  line 33, gen:shared writes: #define PF_SHARED_DETENTS_PER_TURN 24
  line 33, the file has:      #define PF_SHARED_DETENTS_PER_TURN 20
failed   shared                               # exit 1
# constants.ts 의 DETENTS_PER_TURN 을 손으로 20 으로
web/src/lib/shared/constants.ts: stale, run npm run gen:shared in web/
  line 17, gen:shared writes: export const DETENTS_PER_TURN = 24;
  line 17, the file has:      export const DETENTS_PER_TURN = 20;
failed   shared                               # exit 1
# abi/pf_params.h 의 if (v > 1000) v = 1000; 을 1024 로
the bus maximum: drift
  only in the literals in unit1000(), firmware/patternflow/abi/pf_params.h: 1024
failed   shared                               # exit 1
# build_module.py 의 PANEL_W = 128 을 64 로
the default panel's canvas: drift
  only in shared/constants.json 128x64_SINGLE: PANEL_W 128
  only in firmware/toolchain/build_module.py: PANEL_W 64
failed   shared                               # exit 1
# JSON 메모를 고치고 gen:shared 를 안 돌렸을 때도 두 출력 모두 stale, exit 1
# 넷 다 git checkout 으로 되돌렸다

$ npm run typecheck                           # 출력 없음, exit 0
$ npm run lint                                # 출력 없음, exit 0
$ npm run check:ci                            # exit 0
 Test Files  35 passed (35)                   # check:panels
      Tests  478 passed (478)
pattern-sandbox.html is up to date            # check:sandbox-sync
All module cache checks passed.               # check:modcache
passed   bom
passed   bom-schematic
passed   changelog
passed   editions
passed   features
passed   links-absolute
passed   presets
skipped  roadmap                              # 이 세션은 원래 레포를 못 읽는다. CI 는 strict 로 돈다
passed   shared

$ python3 firmware/toolchain/check_boundaries.py
boundary holds: 74 core files know none of 42 feature namespaces across 9 features
$ python3 firmware/toolchain/check_sources.py
all checks passed
$ python3 firmware/toolchain/check_abi_freeze.py
abi frozen: 4 header(s) match abi.sums

# core_shared.h 를 include 하고 #if 비교와 static_assert 셋을 둔 작은 파일
$ g++ -std=c++17 -Wall -Werror -I firmware/patternflow/src shared_try.cpp
core_shared.h compiles: g++ 13

$ git diff --name-only origin/dev...HEAD      # 모듈 캐시 키(builderRev.ts)가 해시하는 파일은 없다
firmware/patternflow/src/core_shared.h
shared/constants.json
web/package.json
web/scripts/drift/shared.ts
web/scripts/gen-shared.ts
web/src/lib/shared/constants.ts

$ npm run check:human-lock
this diff touches 0 locked files
check:human-lock: no locked words changed
$ npm run check:voice                         # 더해 ../shared/constants.json 도 통째로
read: 238 added lines in 4 files
check:voice: nothing found

$ git fetch --tags && npm run doc-map
1074 links from 215 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
1366 Korean/English pairs → docs/investigations/2026-10-doc-parity.csv
7 en-short, 18 ko-short, 1 missing-ko, 1340 ok

doc-map 이 커밋된 CSV 와 다르게 쓴 줄은 둘이고 둘 다 dev 에 이미 있는 docs/investigations/2026-10-panel-geometry.md 에서 나가는 링크다. 이 PR 의 줄은 없다. 두 CSV 는 git checkout 으로 되돌렸다.

실행법

cd web && npm ci
npm run gen:shared        # shared/constants.json → core_shared.h, constants.ts
npm run check:shared      # 지금은 passed
sed -i 's/PER_TURN = 24/PER_TURN = 20/' src/lib/shared/constants.ts
npm run check:shared      # stale, exit 1
npm run gen:shared        # 되돌린다

가정

• 기준 브랜치는 dev(머리말). 표가 PR 7 에 적은 파일 여섯만 고쳤다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV 는 안 고쳤다. 라벨 cleanup·step-3 은 포크에 없어 달지 않았다.
• JSON 키를 두 쪽의 이름으로 그대로 썼다. DETENTS_PER_TURN 하나를 grep 하면 JSON·헤더·모듈 셋이 다 나온다. 펌웨어 쪽은 계획서 발견 10 대로 PF_SHARED_ 를 붙였다. config.h 가 이미 PANEL_GEOM_* 를 정의하고 있어 같은 이름이면 k8 에서 부딪히기도 한다.
• JSON 엔 주석이 없어서 키 "//" 를 메모로 썼다. 생성기는 그 키를 값으로 읽지 않고 그룹 주석으로 옮긴다.
• 「디바운스」는 버튼의 50 ms 다(계획서 발견 9). 인코더 엣지의 ENC_BOUNCE_US 500 µs 는 config.h 의 #ifndef 설정이고 사이트에 사본이 없어 넣지 않았다. 그 밖의 타이밍 스물은 질문 23 의 기본값대로 뺐다.
• 캔버스 크기는 JSON 에 두지 않고 물리 크기와 체인에서 만든다. config.h 의 #error 두 줄이 지키는 규칙과 같다.
• 출력의 낡음은 _lib.ts 의 compare() 대신 직접 찍고 done() 뒤 exit code 를 1 로 둔다. compare() 는 두 쪽 항목을 한 줄에 다 찍어 40줄 넘는 파일엔 읽기 어렵고, _lib.ts 는 표가 PR 7 에 적은 파일이 아니다. ABI 와 build_module.py 비교는 compare() 를 쓴다.
• 다른 독자를 위해 쓴 사본(docs/rest-api.md 382행의 24, Ableton 브리지의 48, 랩 AI 프롬프트)은 D6 대로 손으로 두고 읽지 않는다.
• build.sh all 은 컨테이너가 PlatformIO 에 닿지 못해(기준선) 이 PR 의 firmware-build.yml 다섯 job 에 맡겼고 모두 success 다. 아무 데서도 include 하지 않는 헤더라 이미지는 바뀌지 않는다.
• Changelog 절은 ### Web 하나로 했다. 도구가 web/ 에 있고, 펌웨어가 새 헤더를 읽는 건 k8 이라 그 PR 의 줄이 펌웨어 몫이다.

Changelog

Web

• One file holds the values the firmware and the site both carry. shared/constants.json has the three panel geometries, the knob count, 24 detents a turn, the encoder and button timings and the bus scale. npm run gen:shared in web/ writes it out as firmware/patternflow/src/core_shared.h and web/src/lib/shared/constants.ts, and check:shared, part of check:ci and the drift workflow, fails when either file is stale or when the frozen abi/pf_params.h or build_module.py disagrees with it. Nothing reads the two files yet.

Upstream

• What: Add shared/constants.json with the panel geometries and the knob, encoder and bus values the firmware and the site both carry, npm run gen:shared to write core_shared.h and constants.ts from it, and check:shared. Nothing includes the two outputs yet.
• Checks: npm run typecheck, npm run lint and npm run check:ci (with check:panels, check:sandbox-sync, check:modcache) pass; check:shared fails on a hand edit to either output and on a changed literal in abi/pf_params.h; CI ran build.sh all.
• Docs map: none

🤖 Generated with Claude Code

https://claude.ai/code/session_01DAcHkDDTJ6Go5j92QT5mpD