[DONE] 정리 4단계를 닫는다 — 「done when」 둘이 맞고, 링크 1138개가 다 닿는 지도를 커밋한다

[patternflow-bot]

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

4단계 PR 1~23 이 모두 dev 에 머지돼서, 계획서 k24 대로 문서 지도를 다시 만들고(새 링크 43개, 모두 닿음) §2.6 의 「done when」 둘과 §2.12 셋째 항목이 맞는 것을 확인했다. 머지하면 링크 1138개가 다 닿는 지도가 커밋되고, §2.12 여섯 조건이 이 head 에서 다 맞아 any-resolution 초안을 proposed 로 올릴지는 창작자가 정할 차례다.

좋아지는 것: 없음

할 일

• 계획서 표의 PR 24 확인: 2026-10-doc-map.csv·2026-10-doc-parity.csv (docs/rfc-cleanup-progress.md 는 작업 글대로 안 고침)
• 조건 확인: k1k23 이 dev 에 머지됨([DONE] 정리 4단계 PR 1 — 가이드의 보드 시뮬레이터가 손이 아닌 입력도 받고, 상태를 /api/status 처럼 내준다 #69[DONE] 정리 4단계 PR 23 — REST 와 MIDI 스펙에서 두 말을 하던 줄 열 곳이 한 말을 하고, 그 줄을 옮긴 벡터 둘이 따라간다 #91, 열린 것 없음)
• 두 CSV 다시 만들기 (git fetch --tags 뒤 npm run doc-map 두 번, 바이트 같음)
• §2.6 「done when」 둘과 §2.12 셋째 항목 확인
• 앞 PR 들이 k24 에 넘긴 것 찾기: [DONE] 정리 4단계 PR 8 — 프리셋 34개가 가상 패널에서 다 도는지 검사가 매번 본다 #75 의 「프리셋 목록 전체」, [DONE] 정리 4단계를 PR 스물넷으로 나눈 계획서 — 같이 열릴 수 있는 PR 끼리는 파일이 안 겹친다 #21 의 「Where it stands 줄은 닫는 PR 몫」. 둘 다 아래에 있다
• 진행 기록에 넣을 글 (아래 「진행 기록, 머지하는 사람에게」, check:voice 통과)
• [DONE] 직전 dev fetch: e960629 그대로라 merge 할 것 없음(Already up to date.)

한 일

dev 에 마지막으로 커밋된 지도(#68, 1095행)에 4단계가 더한 링크 43행을 싣는다. 다 닿고, no 는 0행이다. 출처는 다섯 벡터 폴더의 README, docs/contract-vectors.md, tools/virtual-panel/README.md, 그리고 이것들과 스펙을 가리키는 지도 문서 docs/README.md·docs/REPOSITORY.md·CONTRIBUTING.md·tools/README.md 다. AGENTS.md(#89)는 경로를 백틱으로만 적어 행이 없다.

짝 목록은 다시 만들어도 한 바이트도 안 바뀐다(1366쌍).

증거

$ git fetch --tags                        # 28 tags
$ cd web && npm ci && npm run doc-map
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 doc-map; cmp (앞 결과)           # second run byte-identical
$ git diff --stat origin/dev
 docs/investigations/2026-10-doc-map.csv | 43 +++++++++++++++++++++++++++++++++

$ PF_DRIFT_STRICT=1 npm run check:rest-vectors    # 53 vectors, passed
$ PF_DRIFT_STRICT=1 npm run check:mqtt-vectors    # 15, passed
$ PF_DRIFT_STRICT=1 npm run check:osc-vectors     # 11, passed
$ PF_DRIFT_STRICT=1 npm run check:midi-vectors    # 20, passed
$ PF_DRIFT_STRICT=1 npm run check:audio-vectors   # 12, passed
$ PF_DRIFT_STRICT=1 npm run check:virtual-panel
  on the panel's list (34): 0510, 0511, … a_big_hit, origin, wave_saw
  2000 ms, 128×64, no error (34): 0510, 0511, … a_big_hit, origin, wave_saw
passed   virtual-panel

$ npm run typecheck                       # exit 0
$ npm run lint -- --max-warnings=0        # exit 0
$ npm run check:ci                        # exit 0, 26개
 Test Files  35 passed (35)
      Tests  487 passed (487)
skipped  roadmap                          # 이 세션은 engmung/Patternflow 를 못 읽는다. CI 는 아래
$ npm run check:human-lock                # this diff touches 0 locked files
$ npm run check:voice                     # nothing found
$ npm run check:voice -- (아래 진행 기록 글) # read: 49 lines in 1 file / nothing found
$ python3 .github/scripts/check_links.py  # all 754 relative links resolve
$ python3 firmware/toolchain/check_boundaries.py   # 74 core files know none of 42 feature namespaces across 9 features
$ python3 firmware/toolchain/check_presets.py      # 34 twins, 14 web-only on purpose, 1 firmware-only on purpose
$ python3 firmware/toolchain/check_versions.py     # core v3.11.0, audio v0.7.0, performance v0.4.0
$ python3 firmware/toolchain/console_pages.py check

head cee5494 의 CI: Drift checks success (run 38814004535, PF_DRIFT_STRICT: 1), Docs point at files that exist success. Drift 로그 끝:

passed   audio-vectors
passed   bom
passed   bom-schematic
passed   changelog
passed   editions
passed   features
passed   links-absolute
passed   markers
passed   midi-vectors
passed   mqtt-vectors
passed   osc-vectors
passed   presets
passed   rest-vectors
passed   roadmap
passed   shared
passed   virtual-panel
base: e960629 (PF_LOCK_BASE)
check:human-lock: no locked words changed

§2.6 「done when」.

1. 다섯 벡터 스위트가 CI 에서 가상 패널을 상대로 돌고 통과한다. 다섯 다 web/scripts/drift/ 의 파일이라 drift.yml(PR 마다, strict)과 check:ci 끝의 check:drift 에서 돈다. 위 CI 로그에 다섯 다 passed, 벡터 111개(REST 53 · MQTT 15 · OSC 11 · MIDI 20 · audio 12). 가상 패널은 다섯 계약을 다 말한다(transports 여덟). 맞다.
2. 가상 패널이 firmware/patternflow/presets/ 의 프리셋 목록 전체를 던진 오류 없이 돌린다. 헤더 35개 중 JS 쌍이 있는 34개가 2초씩 돌고 128×64 를 낸다. 남은 calib 는 check_presets.py 의 FIRMWARE_ONLY 로 펌웨어 전용이고 계획서 발견 8 이 그렇게 셌다. 맞다.

§2.6 의 「web harness 로 패턴을 돌려 둘이 안 갈라진다」도 맞다: panel.ts 가 @/lib/guide/deviceSim 을, 그것이 @/lib/pattern/harness 의 PatternRuntime 을 쓴다.

§2.12 셋째 항목. 가상 패널이 REST(rest-state.ts·rest-patterns.ts)와 MQTT(mqtt.ts·mqtt-http.ts)를 말하고, 위 2 대로 프리셋 목록을 다 그린다. 맞다.

§2.12 나머지(any-resolution 문턱). 이 PR 몫은 셋째뿐이지만 진행 기록의 문턱 줄을 쓰려고 다 봤다.

1. §2.1(1) 명령: check:ci·check:panels(487)·typecheck·lint 는 위에서 0. build.sh all 은 이 컨테이너가 PlatformIO 레지스트리에 못 닿아 돌리지 않았다. firmware/ 는 [DONE] 정리 3단계 PR 26 — 레포 지도 문서 셋이 shared/·패널 드라이버 패치·랩 저장 키를 지금 모습대로 가리킨다 #59(3단계 PR 26) 뒤로 한 줄도 안 바뀌었고, [DONE] 정리 3단계 PR 26 — 레포 지도 문서 셋이 shared/·패널 드라이버 패치·랩 저장 키를 지금 모습대로 가리킨다 #59 의 Firmware builds 가 default·audio·performance·clock·midi 다섯을 다 통과했다.
2. §2.4 일곱·check:shared·§2.6 여섯·check:human-lock: 위 CI 로그에 다 있다.
3. 위.
4. 지도 no 0행.
5. 루트: 파일 12개(AGENTS.md BUILD_GUIDE.md CHANGELOG.md CITATION.cff CLAUDE.md CONTRIBUTING.md FEATURE_GUIDE.md LICENSE LICENSE-CC-BY-SA LICENSE-MIT PATTERN_GUIDE.md README.md)와 점 파일. §2.13 답 1 의 목록과 같다.
6. docs/rfc-any-resolution.md·docs/rfc-linux-player.md 가 있다([DONE] 정리 5단계 PR 4 — 두 설계 초안이 서로 이어지고 docs 목록에 올라 5단계를 닫는다 #55).

실행법

git fetch --tags && (cd web && npm ci && npm run doc-map) && git diff --stat
cd web && PF_DRIFT_STRICT=1 GH_TOKEN=… npm run check:drift

가정

• 작업 글대로 표의 PR 24 파일 중 docs/rfc-cleanup-progress.md 는 고치지 않았다. 계획서 k24 는 거기에 4단계를 적으라고 하지만, 3단계를 닫은 [DONE] 정리 3단계를 닫는다 — 「done when」 넷이 다 맞고, 링크 1095개가 다 닿는 지도를 커밋한다 #68 과 같이 넣을 글을 아래에 붙였다. 진행 기록엔 1·2·3·5단계 글도 아직 없어서, 머리 줄은 그 넷이 먼저 들어간 뒤의 꼴로 썼다.
• 문턱 줄을 「met」으로 썼다. 위 여섯이 이 head 에서 맞기 때문이다. 다만 1 의 build.sh all 은 이 head 에서 다시 돌린 것이 아니라 바뀌지 않은 펌웨어 트리의 CI 결과다. any-resolution 초안의 Status 줄은 이 PR 이 고치지 않는다(§2.12 의 「may move」는 창작자가 정한다).
• 3단계 k12 의 원래 라이브러리 커밋 여덟([DONE] 정리 3단계를 닫는다 — 「done when」 넷이 다 맞고, 링크 1095개가 다 닿는 지도를 커밋한다 #68 의 「가정」)은 아직 남아 있다. §2.12 의 여섯 조건은 그것을 묻지 않는다.
• 계획서에 행이 없어 4단계 안에서 아무도 줍지 않은 것들은 진행 기록 글에 다 싣지 않고 아래 「남은 것」에 적었다.
• 이 PR 은 docs/ 만 고쳐 web-ci.yml·firmware-build.yml 이 돌지 않는다. check:ci·typecheck·lint 는 이 브랜치에서 손으로 돌렸다.
• 300줄(§2.1): CSV 43줄, 생성물이다.
• 라벨 cleanup·step-4 는 포크에 없어 달지 않았다(앞 PR 들과 같다).

남은 것

4단계 PR 들이 「창작자가 정한다」나 「다른 k」로 넘겼는데 계획서에 행이 없어 남은 것이다. 어느 것도 「done when」을 막지 않는다.

• 질문 26~29 에 답이 없다. 모든 PR 이 기본값을 썼다. 펌웨어가 스펙과 다른 곳 18개(벡터에 든 것 11, 벡터 없이 적은 것 5, k6 이 비켜 간 것 2)는 각 PR 의 「for an issue」에 있고, 열린 이슈는 없다(질문 26 의 기본값은 창작자가 연다).
• web-ci.yml 은 web/** 에만 돌아 tools/virtual-panel/ 만 고친 PR 은 CI 에서 typecheck 를 안 받는다([DONE] 정리 4단계 PR 2 — 보드 없이 도는 가상 패널이 생긴다: 화면은 /frame.png, 손과 시계는 /vp/ #70·[DONE] 정리 4단계 PR 22 — 레포 지도 문서 일곱 개가 가상 패널과 벡터 폴더를 가리킨다 #90).
• panel.ts 의 close() 가 finally 밖이다([DONE] 정리 4단계 PR 3 — 계약 벡터를 적는 꼴이 정해지고, 다섯 벡터 묶음이 같이 쓸 재생기가 생긴다 #71). mqtt.ts 에 setNoDelay(true) 가 없다([DONE] 정리 4단계 PR 11 — MQTT 벡터가 시험 브로커를 거쳐 토픽과 역할을 가상 패널에 돌려 보고 check:mqtt-vectors 가 생긴다 #79). mqtt-http.ts 가 prefix 보다 role 을 먼저 놓는다([DONE] 정리 4단계 PR 12 — MQTT 벡터가 채널과 스냅숏을, REST 벡터가 /api/mqtt 를 가상 패널에 돌려 본다 #82).
• 얼어 있는 _vectors.ts 에 앞부분 맞춤이 없다([DONE] 정리 4단계 PR 7 — REST 벡터가 display, knobs, crash, 파비콘, 패턴 경로와 기본 빌드에 없는 경로를 가상 패널에 돌려 본다 #81). contract-vectors.md 의 ws 칸에 { "close": code } 가 빠졌다([DONE] 정리 4단계 PR 20 — 오디오 WebSocket 벡터가 가상 패널에서 돌고, check:audio-vectors 가 PR 마다 본다 #85). rest-api-vectors/README.md 첫 문장이 rest-api.md 만 말하는데 midi-* 는 midi-spec.md 를 인용한다([DONE] 정리 4단계 PR 18 — MIDI 로 나가는 메시지 벡터 열한 개와 /api/midi 벡터 아홉 개가 가상 패널에서 돈다 #88).
• midi-spec.md 133행의 **1.3** (unreleased) 가 ## Version history 위에 있고 머리는 아직 1.2 다([DONE] 정리 4단계 PR 23 — REST 와 MIDI 스펙에서 두 말을 하던 줄 열 곳이 한 말을 하고, 그 줄을 옮긴 벡터 둘이 따라간다 #91). osc-spec.md 18 대 50, mqtt-spec.md 71 대 38·39·45 가 서로 다르다([DONE] 정리 4단계 PR 23 — REST 와 MIDI 스펙에서 두 말을 하던 줄 열 곳이 한 말을 하고, 그 줄을 옮긴 벡터 둘이 따라간다 #91, k23 파일 밖).

Changelog

Docs

• The doc map is regenerated at the close of step 4 of the cleanup. All 1138 of its links resolve. The 43 new rows are links step 4 added: the five vector folders' READMEs, docs/contract-vectors.md, tools/virtual-panel/README.md, and the maps of the tree that point at them.

Upstream

• What: regenerate docs/investigations/2026-10-doc-map.csv at the close of cleanup step 4. The parity CSV comes out byte-identical, and no other file changes.
• Checks: npm run check:ci (26 suites), npm run typecheck, npm run lint -- --max-warnings=0, npm run check:human-lock, python3 .github/scripts/check_links.py; in drift.yml, npm run check:drift passes all sixteen checks strict, the five vector suites, virtual-panel and roadmap included.
• Docs map: 43 rows added, all resolving, from the vector folders' READMEs, docs/contract-vectors.md, tools/virtual-panel/README.md, docs/README.md, docs/REPOSITORY.md, CONTRIBUTING.md and tools/README.md.

진행 기록, 머지하는 사람에게

docs/rfc-cleanup-progress.md 에 1·2·3·5단계 글(#23·#37 「for another …」, #68, #55)이 먼저 들어간 뒤에 0단계와 같은 꼴로. 머리 줄, 표 4행 state, 문턱 줄, 그리고 절이다.

**Where it stands: steps 0 to 5 done.** Baseline SHA `8226f7e`.

| 4 | Test spine: contract vectors ×5, virtual panel | done ([#69](https://github.com/Patternflow-lab/Patternflow/pull/69)–[#92](https://github.com/Patternflow-lab/Patternflow/pull/92)) |

Gate for any-resolution (§2.12): met at [#92](https://github.com/Patternflow-lab/Patternflow/pull/92).

## Step 4 — the test spine

Twenty-four PRs, 15 and 16 October 2026:
[#69](https://github.com/Patternflow-lab/Patternflow/pull/69) to
[#91](https://github.com/Patternflow-lab/Patternflow/pull/91) as cut by
[investigations/2026-10-cleanup-step4-plan.md](investigations/2026-10-cleanup-step4-plan.md),
and [#92](https://github.com/Patternflow-lab/Patternflow/pull/92) to close it.

`tools/virtual-panel/` is a Patternflow with no board. It is the guide's
`DeviceSim` behind the ports the firmware listens on, and patterns run on the
lab's `PatternRuntime`, the one the site runs them on. Eight files in
`transports/` speak the five wire contracts, each the subset its spec names,
on Node's own sockets. The lockfile did not move. `GET /frame.png` is the
frame as the LEDs would show it, and `/vp/` is a hand and the clock. The
firmware has neither.

The five vector folders hold 111 vectors: 53 for REST, 15 for MQTT, 11 for
OSC, 20 for MIDI and 12 for the audio socket. Each is a JSON file that quotes
one sentence of its spec, in the format
[contract-vectors.md](contract-vectors.md) gives. A suite starts a fresh panel
for each vector on a clock that stands still between steps, so a 500 ms
release costs no real time. `check:virtual-panel` runs the 34 presets that
have a JS twin for two seconds of panel time each. `calib` is firmware-only
and is left out. The six suites are files in `web/scripts/drift/`, so
`check:ci` and `drift.yml` run them on every pull request.

The vectors follow the spec. Where the spec said two things, #91 made it say
one, in ten lines of `rest-api.md` and `midi-spec.md`, by question 27's
default. Where the firmware disagrees with its spec, the vector keeps the
spec, and a real panel would fail it. Eleven such disagreements are in
vectors, and seven more are written up with no vector. Each PR names the
spec line and the firmware line, and no issue is open for any of them yet
(question 26). Nothing under `firmware/` changed in this step.

Questions 26 to 29 have no answer, and every PR took the default. Web CI
starts only on `web/`, so a PR that edits only `tools/virtual-panel/` is
typechecked at a desk and nowhere else.

At [#92](https://github.com/Patternflow-lab/Patternflow/pull/92) `check:ci`
passes its 26 suites, `check:panels` its 487 tests, and lint and typecheck
are clean. `drift.yml` passes its 16 checks strict. The doc map has 1138
links out of 224 files, every one resolving. The parity list is unchanged at
1366 pairs.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T4wTrjor7M86XLMCgJLNNS