[DONE] 정리 4단계 PR 22 — 레포 지도 문서 일곱 개가 가상 패널과 벡터 폴더를 가리킨다

[patternflow-bot]

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

정리 4단계 계획서 표의 PR 22 다. PR 1~20 이 만든 가상 패널과 벡터 폴더 다섯 개를 레포를 그리는 문서 일곱 개가 가리키게 했다. 머지되면 docs 목록의 스펙마다 옆 벡터 폴더가 보이고, 가상 패널 README 에 transport 여덟 개와 그 포트가 적히고, web 문서가 벡터 묶음과 프리셋 검사를 이름으로 부른다.

좋아지는 것: 없음

할 일

• 계획서 PR 22 행(k22)과 「k21 and k22」 문단, PR 120([DONE] 정리 4단계 PR 1 — 가이드의 보드 시뮬레이터가 손이 아닌 입력도 받고, 상태를 /api/status 처럼 내준다 #69[DONE] 정리 4단계 PR 18 — MIDI 로 나가는 메시지 벡터 열한 개와 /api/midi 벡터 아홉 개가 가상 패널에서 돈다 #88) 본문의 「for another k」 중 k22 몫을 읽는다
• docs/README.md: 다섯 스펙 줄에 벡터 폴더를 pfst 줄처럼, 기능 경로의 REST 벡터 자리, contract-vectors.md 한 줄
• docs/REPOSITORY.md: tools/ 행에 가상 패널, docs/ 행에 벡터, 「Control the panel」 행에 가상 패널
• CONTRIBUTING.md: wire contract 행이 스펙을 고치면 벡터도 따라 고친다고 말하고, CI 칸에 drift
• tools/README.md: 가상 패널 행, 클라이언트가 아닌 하나
• tools/virtual-panel/README.md: transport 여덟 개 표(기능, 답하는 것, --port 이름과 펌웨어 번호), 어느 스위트가 start() 를 부르나
• web/ARCHITECTURE.md: 벡터 스위트 다섯과 check:virtual-panel, _ 라이브러리와 _broker.ts, typecheck 가 tools/virtual-panel/ 도 읽는다
• web/README.md: 명령 목록에 check:rest-vectors, check:virtual-panel, virtual-panel, scripts/drift/
• 300줄 안: +41 −21
• 링크, 잠금, 글투, markers, check:drift, doc-map
• 표의 포트 이름과 404 를 가상 패널을 띄워 확인
• 이 PR 의 CI: 2ff123a 에서 셋 다 success
• [DONE] 직전 dev 를 다시 받아 본다: c8e877f 그대로라 merge 할 것이 없다

한 일

docs/README.md 의 Contracts 목록에서 rest-api.md, osc-spec.md, midi-spec.md, mqtt-spec.md, audio-ws-spec.md 줄 끝에 「with test vectors in …」을 붙였다. pfst 줄이 쓰는 말 그대로다. /api/mqtt, /api/midi, /api/audio 의 벡터는 rest-api-vectors/ 에 있어서(mqtt-, midi-, audio-) 그 셋의 줄은 그것도 말한다. pfst 줄 아래에 contract-vectors.md 한 줄을 두고 가상 패널 README 로 잇는다.

가상 패널 README 의 마지막 문장(「Step 4's plan lists the transports to come」)을 표로 바꿨다. 행마다 앞 PR 이 k22 에 적어 둔 것을 넣었다. rest-patterns.ts 가 /api/status 의 볼륨 칸을 낸다는 것(#73), GET /vp/mqtt(#74), /api/mqtt/config 와 /forget, Director 경로가 404 라는 것(#77), OSC 의 두 포트(#78), MIDI 의 데이터 포트(#83), midi-out.ts 와 /api/midi(#86), ws(#84). 그 아래 두 문장은 CI 가 main.ts 가 아니라 start() 를 직접 부른다는 것과, 벡터 스위트와 check:virtual-panel 이 패널을 어떻게 쓰는지다.

web/ARCHITECTURE.md 121행은 drift 검사가 「손으로 맞추는 두 파일을 견준다」고만 했다. 다섯 벡터 스위트는 스펙을 돌아가는 패널에 대 본다는 것, check:virtual-panel 은 벡터 스위트가 아니라 프리셋 검사라는 것(#75), _broker.ts 는 시험 브로커라는 것(#79)을 이었다. web/README.md 의 명령 목록은 주석 열이 맞게 일곱 줄의 공백도 같이 밀었다.

증거

로컬, web/:

$ git diff --stat origin/dev...HEAD
 CONTRIBUTING.md               |  2 +-
 docs/README.md                | 11 ++++++-----
 docs/REPOSITORY.md            |  6 +++---
 tools/README.md               |  3 ++-
 tools/virtual-panel/README.md | 17 ++++++++++++++++-
 web/ARCHITECTURE.md           |  4 ++--
 web/README.md                 | 19 +++++++++++--------
 7 files changed, 41 insertions(+), 21 deletions(-)

$ python3 ../.github/scripts/check_links.py
all 754 relative links resolve
$ npm run check:human-lock
This diff touches 0 locked files
check:human-lock: no locked words changed
$ npm run check:voice
base: c8e877f (the merge-base with origin/dev)
read: 41 added lines in 7 files
check:voice: nothing found
$ npx tsx scripts/drift.ts markers
passed   markers
$ npm run check:drift
passed audio-vectors, bom, bom-schematic, changelog, editions, features, links-absolute, markers, midi-vectors, mqtt-vectors, osc-vectors, presets, rest-vectors, shared, virtual-panel · skipped roadmap(원래 레포를 못 읽는다, CI 는 strict)
$ git fetch --tags && npm run doc-map           # CSV 는 git checkout 으로 되돌렸다
1138 links from 224 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

본문은 npm run check:voice -- - 로 따로 돌렸다: check:voice: nothing found.

표에 적은 포트 이름은 패널을 네 기능 모두로 띄워 봤다. osc 의 답 포트 oscReply 는 묶는 포트가 아니라 이 목록에 없고, --port oscReply=… 로만 쓴다(osc.ts 65행).

$ npm run virtual-panel -- --features mqtt,osc,midi,audio --port '*=0'
http     37649
ws       39421
midi     46118
osc      34037
$ curl -s -o /dev/null -w "%{http_code} %{content_type}\n" localhost:37649/frame.png
200 image/png
$ curl -s localhost:37649/vp/mqtt
{"banner":null,"ms":0}
$ npm run virtual-panel -- --features mqtt --port '*=0'   # 그리고 POST 넷
director 404
flowlocal 404
mode 404
config 200

GitHub, 이 PR: 2ff123a 에서 「Web CI / build」(116557195013), 「Drift checks / check」(116557078576), 「Docs point at files that exist / check」(116557078449)가 success.

실행법

cd web && npm ci
npm run check:voice && npm run check:human-lock
python3 ../.github/scripts/check_links.py
npm run virtual-panel -- --port http=8080     # 가상 패널 README 의 표와 맞대 볼 때

가정

• 기준 브랜치는 dev(머리말). 표가 PR 22 에 적은 일곱 파일만 고쳤다. CHANGELOG.md, docs/rfc-cleanup-progress.md, doc-map CSV, AGENTS.md(k21), 벡터 폴더 README 와 docs/contract-vectors.md 는 안 고쳤다. 라벨은 앞 PR 들처럼 달지 않았다(레포에 cleanup, step-4 라벨이 없다).
• 계획서는 가상 패널을 「tools/ 에서 클라이언트가 아닌 하나」라 부르는데, case-models/ 도 클라이언트가 아니다. 그래서 tools/README.md 는 「계약의 패널 쪽에 선 하나」로 적었다.
• docs/REPOSITORY.md 의 「Control the panel from other software」 행에 가상 패널 한 문장을 더했다. 계획서는 tools/ 행만 말하지만, D3 이 기본 포트를 펌웨어 번호로 둔 까닭이 클라이언트가 가상 패널을 가리킬 수 있게 하려는 것이라 그 행이 맞는 자리다.
• web/README.md 의 npm run virtual-panel 줄은 -- --port http=8080 을 같이 적었다. 플래그 없이는 80 을 묶으려다 루트가 아닌 리눅스에서 EACCES 로 끝난다(main.ts 가 같은 말을 낸다).
• docs/README.md 의 새 줄은 Contracts 목록 안, pfst 줄 아래에 뒀다. 형식 문서는 스펙이 아니지만 그 목록을 읽는 사람이 찾는 자리다.
• firmware/ 와 web/src/ 를 건드리지 않아 build.sh all, check:ci, check:panels, typecheck, lint 는 §2.1(1) 대상이 아니다. 스크린샷은 없다. 화면이 바뀌지 않는다.

Changelog

Docs

• The maps of the tree name the virtual panel and the contract vectors. docs/README.md puts each contract's vector folder on its line, as it already did for pfst, and adds docs/contract-vectors.md. tools/virtual-panel/README.md lists its eight transports with the feature each needs and the port it answers on. CONTRIBUTING.md says a spec change brings its vectors along, and web/README.md and web/ARCHITECTURE.md name the five vector suites and check:virtual-panel.

for another k

• web-ci 는 web/** 에서만 돈다. npm run typecheck 가 tools/virtual-panel/ 을 읽어도, tools/virtual-panel/*.ts 만 고친 PR 은 typecheck 를 안 거친다. drift 는 tsx 로 돌려 타입을 보지 않는다. .github/ 는 4단계 표에 없어 적기만 한다.
• docs/contract-vectors.md 의 ws 칸에 { "close": code } 를 적을 자리([DONE] 정리 4단계 PR 20 — 오디오 WebSocket 벡터가 가상 패널에서 돌고, check:audio-vectors 가 PR 마다 본다 #85). 그 파일은 k3 의 것이고 다시 가진 행이 없다.
• docs/rest-api-vectors/README.md 첫 문장 「one sentence of rest-api.md」와 midi- 벡터([DONE] 정리 4단계 PR 18 — MIDI 로 나가는 메시지 벡터 열한 개와 /api/midi 벡터 아홉 개가 가상 패널에서 돈다 #88). 이 PR 의 docs/README.md 는 /api/midi 의 벡터가 rest-api-vectors/ 에 있다고만 말한다.

Upstream

• What: Point docs/README.md, docs/REPOSITORY.md, CONTRIBUTING.md, tools/README.md, tools/virtual-panel/README.md, web/ARCHITECTURE.md and web/README.md at the virtual panel, its eight transports and the five folders of contract vectors.
• Checks: docs only, firmware/ and web/src/ untouched; relative links, check:human-lock, check:voice, markers and npm run check:drift pass.
• Docs map: none.

🤖 Generated with Claude Code

https://claude.ai/code/session_0115cC8RgMiEKctiBiBbMasD