[DONE] 정리 1단계를 닫는다 — docs 안내 두 장이 옮긴 자리와 맞고, 링크 1066개가 다 닿는 지도를 커밋한다

[patternflow-bot]

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

정리 1단계의 A·B 갈래가 모두 머지돼서, 계획서 C3 대로 문서 지도를 다시 만들고 다른 갈래가 넘긴 문장을 docs/README.md 와 docs/REPOSITORY.md 에 넣었다. 머지하면 두 안내 문서가 지금 레포와 맞는다. 루트엔 가이드 셋만 둔다는 규칙, 릴리스마다 한 장인 releases/, 글투 문서 voice.md 가 적히고, 링크 1066개가 모두 닿는 지도가 커밋된다.

좋아지는 것: 없음

할 일

• 계획서 표의 PR C3 확인: 2026-10-doc-map.csv·2026-10-doc-parity.csv·docs/README.md·docs/REPOSITORY.md (docs/rfc-cleanup-progress.md 는 작업 글대로 안 고침)
• 조건 확인: A1 [DONE] 옛 v2 조립 가이드를 docs/legacy/ 로 옮겨 루트에서 한 장 덜어낸다 #13 · A2 [DONE] 행동 강령·보안·지원 안내는 .github/ 로, 오디오 가이드는 docs/ 로 옮겨 루트가 한눈에 읽힌다 #16 · A3 [DONE] README 의 이야기 세 절은 창작자 답대로 그대로 둔다 — 옮길 것이 없다 #22 · B1 [DONE] 변경 기록을 릴리스마다 한 장으로 나눠 docs/releases/ 에 두고 루트엔 최근 셋만 남긴다 #14 · C1 [DONE] 한국어·영어 짝 문서가 서로 맞는지 표 하나로 본다 #15 · C2 [DONE] 문서 지도가 이슈 양식의 링크까지 본다 #17 모두 dev 에 머지됨
• 두 CSV 다시 만들기 (git fetch --tags 뒤 npm run doc-map 두 번, 바이트 같음)
• 넘겨받은 문장 넣기: B1([DONE] 변경 기록을 릴리스마다 한 장으로 나눠 docs/releases/ 에 두고 루트엔 최근 셋만 남긴다 #14) releases/ 줄 · A2([DONE] 행동 강령·보안·지원 안내는 .github/ 로, 오디오 가이드는 docs/ 로 옮겨 루트가 한눈에 읽힌다 #16) 루트 규칙 · C1([DONE] 한국어·영어 짝 문서가 서로 맞는지 표 하나로 본다 #15) 짝 목록 한 줄 · 글투 PR([DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다 #18) voice.md 한 줄
• §2.3 「done when」 넷 확인 (아래 증거)
• head 84a3a3f 의 docs-links.yml 초록
• [DONE] 직전 dev fetch: d4668ad 그대로, 뒤처진 커밋 0 이라 merge 할 것 없음

한 일

• 지도. 마지막으로 커밋된 맵(C2 때)에 1단계의 옮김이 쌓여 있어서 다시 만들었다. dev 대비 +117 −67행이고, no 는 한 줄도 없다. 옮긴 파일의 나가는 행은 출처가 새 경로로(AUDIO_GUIDE.md → docs/AUDIO_GUIDE.md 23행, .github/ 의 세 파일 14행, docs/releases/v3.0.0.md·v3.1.0.md → -notes.md), CHANGELOG.md 의 옛 절 행은 제 릴리스 파일로, 들어오는 행은 대상이 새 경로로. 새 출처: docs/voice.md, docs/rfc-cleanup-progress.md, 2·3·4단계 계획서. 이 PR 이 더한 행은 docs/README.md → docs/voice.md·docs/voice-banned.txt 둘이다. 짝 목록은 다시 만들어도 한 바이트도 안 바뀌었다(1366쌍).
• docs/README.md. 첫 문단 규칙: 「a guide somebody follows start to finish lives at the repository root」는 오디오 가이드가 docs/ 로 간 뒤 틀린 말이라 「the repository root keeps three guides and no others (…), so a first-time visitor reads it at a glance」로, 이 폴더 쪽엔 「a walk-through for one task (the audio guide is one)」. Records 의 releases/ 줄은 B1 이 쓴 문장 그대로. investigations/ 줄에 계획서와 두 CSV(무엇을 적는지, 어느 명령이 쓰는지). Contributing 에 voice.md·voice-banned.txt 한 줄.
• docs/REPOSITORY.md. 같은 규칙 문장을 같은 뜻으로. docs/ 줄에 「the writing voice (voice.md and voice-banned.txt)」와 「project records (releases/, one file per release)」.

증거

$ git ls-files | grep -v / | grep -v '^\.'        # §2.3 루트 = 답 1 의 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

$ python3 .github/scripts/check_links.py
all 678 relative links resolve

$ git fetch --tags        # 28 tags
$ cd web && npm ci && npm run doc-map
1066 links from 212 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/README.md                          |   7 +-
 docs/REPOSITORY.md                      |   4 +-
 docs/investigations/2026-10-doc-map.csv | 184 ++++++++++++++++++++------------
 3 files changed, 123 insertions(+), 72 deletions(-)
# 짝 CSV 는 다시 만들어도 diff 없음. CSV 의 바뀐 행 중 ',no' 로 끝나는 것 0

# 새로 쓴 줄에 voice-banned.txt 낱말: 없음

• §2.3 「done when」: 루트는 답 1 의 파일만(위), 옮긴 파일의 들어오는 링크는 각 PR 이 같이 고쳤고 지금 맵에 no 0행, docs-links.yml(「Docs point at files that exist」) head 84a3a3f 에서 success, 짝 CSV 있음. 넷 다 맞다.
• firmware/·web/src/ 는 안 건드려서 §2.1 의 build.sh all·web 네 명령은 해당 없다. 이 PR 에서 도는 CI 는 docs-links.yml 하나다.

실행법

python3 .github/scripts/check_links.py
git fetch --tags && (cd web && npm ci && npm run doc-map) && git diff --stat

가정

• 작업 글대로 표의 C3 파일 중 docs/rfc-cleanup-progress.md 는 고치지 않았다. 그 파일은 「Entries are added by whoever merges」라서, 넣을 글을 아래 「for another lane」에 그대로 붙여 쓸 수 있게 두었다.
• 루트 규칙 문장을 다시 쓴 것은 A2([DONE] 행동 강령·보안·지원 안내는 .github/ 로, 오디오 가이드는 docs/ 로 옮겨 루트가 한눈에 읽힌다 #16)가 넘긴 일이다. A2 는 답 6 때문에 voice.md 머지 뒤로 미뤘고, [DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다 #18 이 머지됐다. 「so a first-time visitor reads it at a glance」는 메인테이너 답 1의 말(「A first-time visitor should be able to read the root at a glance」)을 옮긴 것이다. 새 까닭을 지어 넣지 않았다.
• C1([DONE] 한국어·영어 짝 문서가 서로 맞는지 표 하나로 본다 #15)의 부탁은 「docs/README.md 가 doc map 을 소개하는 곳이 있으면」이었다. 소개하는 곳이 없어서 investigations/ 줄에 두 CSV 를 같이 적었다. 「dated post-mortems」만으로는 거기 있는 계획서와 1단계 결과물(짝 목록)을 찾을 수 없다.
• releases/ 줄은 B1 문장 그대로다. 「two July 2026 releases」는 v3.0.0-notes.md·v3.1.0-notes.md 배너가 둘 다 「Historical (2026-07)」인 것으로 확인했다(원래 줄의 「three」는 launch 체크리스트까지 센 것).
• REPOSITORY.md 에선 voice.md 를 새 표 줄 대신 docs/ 줄 안에 넣었다. 그 표는 폴더 지도이고, 줄 안의 파일은 링크 없이 백틱으로 쓰는 꼴이다.
• [DONE] 영어는 README·조립 가이드 글투로, 한국어는 번역체를 피하는 기준으로 한 쪽에 적고, 쓰지 않는 말은 따로 목록으로 둔다 #18 이 넘긴 AGENTS.md 의 §2.10 「Writing voice」 덧붙임은 C3 파일이 아니다. 2단계 계획서가 k11(AGENTS.md: the §2.10 rule)로 이미 맡았다.
• 300줄(§2.1, D3): 손으로 쓴 줄은 두 문서의 +7 −5 다. CSV 는 npm run doc-map 이 쓴 생성물이다.
• 라벨 cleanup·step-1(D4)은 포크에 없어 붙이지 않았다(앞 PR 들과 같음).

Changelog

Docs

• The docs index and the repository map catch up with step 1 of the cleanup. docs/README.md and docs/REPOSITORY.md say the root keeps three guides and no others, describe docs/releases/ as one file per release, and list voice.md. The doc map is regenerated, and all 1066 of its links resolve.

Upstream

• What: regenerate docs/investigations/2026-10-doc-map.csv after the step 1 moves, and bring docs/README.md and docs/REPOSITORY.md in line: the root rule names the three guides it keeps, releases/ is one file per release, voice.md is listed.
• Checks: python3 .github/scripts/check_links.py (678 relative links resolve) and npm run doc-map twice in web/ (1066 links, 0 unresolved, byte-identical); no file under firmware/ or web/src/ changed.
• Docs map: two rows added, from docs/README.md to docs/voice.md and docs/voice-banned.txt; the rest of the CSV diff records the step 1 moves already merged.

for another lane

• 진행 기록 (docs/rfc-cleanup-progress.md), 머지하는 사람에게. 0단계와 같은 꼴로 넣을 글:
  • 머리 줄: **Where it stands: steps 0 and 1 done, step 2 next.** Baseline SHA 8226f7e.
  • 표 1행 state: done ([#13](https://github.com/Patternflow-lab/Patternflow/pull/13)–[#17](https://github.com/Patternflow-lab/Patternflow/pull/17), [#22](https://github.com/Patternflow-lab/Patternflow/pull/22), [#23](https://github.com/Patternflow-lab/Patternflow/pull/23))
  • 절:

## Step 1 — document structure

Seven PRs, 14 and 15 October 2026, in the three lanes of
[investigations/2026-10-cleanup-step1-plan.md](investigations/2026-10-cleanup-step1-plan.md).

The root holds the twelve files of the maintainer's answer 1. `BUILD_GUIDE_v2.md`
is `docs/legacy/BUILD_GUIDE_v2.md` ([#13](https://github.com/Patternflow-lab/Patternflow/pull/13)).
`CODE_OF_CONDUCT.md`, `SECURITY.md` and `SUPPORT.md` are in `.github/`, and
`AUDIO_GUIDE.md` is `docs/AUDIO_GUIDE.md` ([#16](https://github.com/Patternflow-lab/Patternflow/pull/16)).
The README's narrative sections stay where they are (answer 2), so A3 moved
nothing ([#22](https://github.com/Patternflow-lab/Patternflow/pull/22)).

`CHANGELOG.md` keeps the three newest releases in full and links the rest.
Every release back to v1.0.0 has its own file in `docs/releases/`, and
`release.py cut` writes the next one ([#14](https://github.com/Patternflow-lab/Patternflow/pull/14)).

`npm run doc-map` also writes
[investigations/2026-10-doc-parity.csv](investigations/2026-10-doc-parity.csv)
([#15](https://github.com/Patternflow-lab/Patternflow/pull/15)) and reads the
issue chooser's YAML ([#17](https://github.com/Patternflow-lab/Patternflow/pull/17)).
At [#23](https://github.com/Patternflow-lab/Patternflow/pull/23) the map has
1066 links out of 212 files, every one resolving. The parity list has 1366
pairs: 1340 ok, 18 ko-short, 7 en-short, and one missing-ko. No translation
was done; the list is the deliverable.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S5utCYhZ1dCRVsV4UgD716

---

Generated by Claude Code