[DONE] 정리 4단계 PR 21 — 에이전트 안내서가 가상 패널과 계약 벡터 폴더, 새 검사 여섯을 안다

[patternflow-bot]

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

AGENTS.md 의 레포 지도와 명령 목록에 4단계가 더한 것을 적었다. 빠져 있던 mqtt-spec.md, 계약마다 옆에 있는 벡터 폴더, 보드 없이 도는 가상 패널, 새 검사 여섯과 npm run virtual-panel 이다. 머지하면 에이전트가 계약 문장을 고칠 때 그 문장을 인용한 벡터도 같이 고쳐야 하고, 펌웨어가 계약과 다르면 벡터가 아니라 이슈로 간다는 걸 처음부터 안다.

좋아지는 것: 없음

할 일

• 계획표 PR 21 줄과 세부(k21) 읽기
• 먼저 머지돼야 할 PR 120 이 dev 에 있는지 확인 ([DONE] 정리 4단계 PR 1 — 가이드의 보드 시뮬레이터가 손이 아닌 입력도 받고, 상태를 /api/status 처럼 내준다 #69[DONE] 정리 4단계 PR 18 — MIDI 로 나가는 메시지 벡터 열한 개와 /api/midi 벡터 아홉 개가 가상 패널에서 돈다 #88, 스물 다 있음)
• AGENTS.md 고치기 (그 파일만, +5 −3 줄)
• 검사 돌리기 (check_versions·typecheck·drift·human-lock·voice·doc-map)
• dev merge 뒤 [DONE]. [DONE] 뒤 dev 에 [DONE] 정리 4단계 PR 22 — 레포 지도 문서 일곱 개가 가상 패널과 벡터 폴더를 가리킨다 #90·[DONE] 정리 4단계 PR 23 — REST 와 MIDI 스펙에서 두 말을 하던 줄 열 곳이 한 말을 하고, 그 줄을 옮긴 벡터 둘이 따라간다 #91 이 들어와 한 번 더 merge 했다(충돌 없음). check_versions·drift·human-lock·typecheck 다시 통과.

한 일

• 레포 지도 docs/ 줄: 계약 목록에 빠져 있던 mqtt-spec.md 를 넣고, 계약마다 옆에 벡터 폴더가 있다고 적었다. 목록에 그 꼴을 정한 contract-vectors.md 도 넣었다. 줄 끝에 폴더 다섯 이름과, 벡터는 펌웨어가 아니라 계약을 따르고(펌웨어가 다르면 이슈), 인용한 문장을 계약에서 바꾸면 그 벡터가 실패한다는 두 문장을 더했다.
• 레포 지도 tools/ 줄: virtual-panel 을 넣었다. 도구 가운데 하나뿐인 클라이언트 아닌 것이고, 가이드의 DeviceSim 을 펌웨어 포트 뒤에 둔 것이며, 그래서 DeviceSim 을 고치면 검사가 보는 패널이 바뀐다는 것. 시험용이라 Wi-Fi 와 펌웨어 업데이트는 없다는 것.
• 「Common commands」: lint·typecheck 줄에 typecheck 가 tools/virtual-panel/ 도 읽고 lint 는 안 읽는다고 한 문장. 새 줄 둘. 하나는 check:rest-vectors 와 나머지 넷, check:virtual-panel 이 무엇을 하고 check:drift·drift.yml 로 CI 에서 돈다는 것. 하나는 npm run virtual-panel 을 손으로 띄우는 법(1024 아래 포트와 --port, --features, /frame.png 와 /vp/).

증거

• python3 firmware/toolchain/check_versions.py → versions agree: core v3.11.0, audio v0.7.0, performance v0.4.0 - in net_config.h, the overrides, AGENTS.md, the manifest and the /editions cards, images on the shelf; try-out images: clock-v0.1.5, midi-v0.1.0 (AGENTS.md 를 읽는 검사, 계획서가 이 PR 에 돌리라고 한 것)
• 일부러 깨 본 판: AGENTS.md 의 - Project: v3.11.0 을 v3.11.1 로 바꾸고 돌리면 1 version problem(s): / - core: net_config.h says v3.11.0, AGENTS.md says v3.11.1, 종료 코드 1. 커밋 전에 되돌렸다.
• npm run typecheck → 종료 코드 0 (웹과 tools/virtual-panel/ 둘 다)
• npm run check:drift → audio-vectors·bom·bom-schematic·changelog·editions·features·links-absolute·markers·midi-vectors·mqtt-vectors·osc-vectors·presets·rest-vectors·shared·virtual-panel 통과, roadmap 은 gh 로그인이 없어 건너뜀(CI 에선 돈다). 새로 적은 여섯 검사는 따로도 돌려 봤다: 각 1~6초, 다 통과, check:virtual-panel 은 2000 ms, 128×64, no error (34).
• npm run check:human-lock → this diff touches 0 locked files / check:human-lock: no locked words changed
• npm run check:voice → AGENTS.md:11 threes manifesto, investigations, and media 하나. 고친 docs/ 줄 전체가 더한 줄로 읽혀서 나온 것이고, 그 셋은 원래 있던 목록 끝이라 건드리지 않았다. 새로 쓴 글에선 나온 게 없다. 이 본문도 check:voice - 로 읽혀 nothing found.
• git fetch --tags 뒤 npm run doc-map → 1120 links from 224 files / 0 do not resolve, 1366 Korean/English pairs / 7 en-short, 18 ko-short, 1 missing-ko, 1340 ok. AGENTS.md 에서 나온 행은 바뀌지 않았다(새 25행은 앞 PR 들이 더한 벡터 README 와 contract-vectors.md 몫). 두 CSV 는 되돌렸다.
• firmware/·web/src/ 를 건드리지 않아 §2.1(1) 의 다섯 명령은 해당 없음.
• [DONE] 정리 4단계 PR 22 — 레포 지도 문서 일곱 개가 가상 패널과 벡터 폴더를 가리킨다 #90 이 고친 tools/virtual-panel/README.md 와 맞춰 봤다. 트랜스포트 여덟, 벡터마다 새 패널과 빈 포트, 수동 시계, 프리셋마다 2초가 AGENTS.md 의 말과 같다.

실행법

web/ 에서 npm ci 뒤 위 명령을 그대로. check_versions.py 는 레포 뿌리에서.

가정

• mqtt-spec.md 는 docs/ 줄의 계약 목록에만 넣었다. integrations/ 줄의 목록은 그 폴더의 연동이 쓰는 계약이라(Ableton 은 OSC, Home Assistant 는 레포를 떠났다) 그대로 뒀다.
• 여섯 검사는 드리프트 줄의 check:<name> 목록에 섞지 않고 「Contract vectors」 줄로 따로 뒀다. 드리프트 목록은 손으로 맞추는 두 파일을 견주는 검사들이고, 벡터는 계약과 가상 패널을 견준다. 대신 그 줄에 여섯이 web/scripts/drift/ 의 파일이라 check:drift 와 drift.yml 이 같이 돌린다고 적었다.
• 「계약을 따르고 펌웨어가 다르면 이슈」와 「인용한 문장을 바꾸면 벡터가 실패」는 rfc-cleanup.md §2.6 과 contract-vectors.md 에서 가져왔다. 계약을 고치는 에이전트가 가장 먼저 알아야 할 것이라 지도에 넣었다.
• 계획서 D12 대로 typecheck 가 가상 패널을 읽고 lint 는 안 읽는다는 것을 lint·typecheck 줄에 더했다.
• 경로는 AGENTS.md 의 다른 줄처럼 링크가 아니라 코드로 적었다. 그래서 doc-map 행이 늘지 않는다.
• PR 라벨(cleanup, step-4)은 MCP 도구로 PR 라벨을 읽거나 붙이지 못해 달지 않았다.
• CHANGELOG.md 는 고치지 않았다(머리말·계획서대로). 넣을 줄은 아래.

Changelog

Docs

• AGENTS.md names the virtual panel, the contract vectors and their commands. The repository map adds mqtt-spec.md, the vector folder beside each of the five wire contracts with contract-vectors.md as their format, and tools/virtual-panel/. Common commands gain the five check:*-vectors suites, check:virtual-panel and npm run virtual-panel.

Upstream

• What: AGENTS.md maps tools/virtual-panel and the vector folder beside each wire contract, adds the missing mqtt-spec.md, and lists the six suites and npm run virtual-panel.
• Checks: check_versions.py, npm run typecheck, npm run check:drift and npm run check:human-lock pass; nothing under firmware/ or web/src/ changes, so the five section 2.1 commands do not apply.
• Docs map: none

🤖 Generated with Claude Code

https://claude.ai/code/session_01WPrPMmXxEhJCiBLq9SLbrZ