Merge the keyword pooling into cluster-keywords

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/methodology.md

@@ -13,9 +13,10 @@ LLM。設計原則見 `research-plan.md`；本檔記載可重現的
 演算法細節。
 
 編號的所指為**研究程序的工序**，不是定義檔：步驟 1 與
-步驟 3 有定義檔（`prompts/`），步驟 2 沒有——它是確定性
-計算。有無定義檔的區別即「該步是否為 LLM 判斷」，由
-`prompts/` 是否存在同號檔案直接可見。
+步驟 3 有定義檔（`prompts/`），步驟 2 沒有——它是單一
+確定性計算，由 `cluster-keywords` 一個子命令完成。有無
+定義檔的區別即「該步是否為 LLM 判斷」，由 `prompts/` 是
+否存在同號檔案直接可見。
 
 ## 步驟 2 詞彙表建構——詞向量分群
 
@@ -23,16 +24,15 @@ LLM。設計原則見 `research-plan.md`；本檔記載可重現的
 恰屬一組、不遺漏、不新增）由演算法結構保證，無須事後
 驗證。
 
-### 步驟 2-1 進池
+### 進池
 
 兩次標註執行的全部關鍵字取聯集、逐字串精確去重、字典序
-排列，寫成純文字檔（一行一個關鍵字）。失敗與拒答的記錄
-跳過（其歌曲不貢獻關鍵字）；解析時偵測重複鍵，違規即
-失敗。同時寫出處 CSV（欄位 Keyword、Run、Song，一列一筆
-出現，依三欄排序），供收斂軌跡分析；出處記錄不進任何
-下游輸入。
+排列。失敗與拒答的記錄跳過（其歌曲不貢獻關鍵字）；解析
+時偵測重複鍵，違規即失敗。同時記出處（欄位 Keyword、
+Run、Song，一列一筆出現，依三欄排序），供收斂軌跡分析；
+出處記錄不進任何下游輸入。
 
-### 步驟 2-2 分群
+### 分群
 
 - **嵌入**：`sentence-transformers/all-mpnet-base-v2`
   （釘定 revision），關鍵字的連字號先還原為空格再編碼，
@@ -47,12 +47,14 @@ LLM。設計原則見 `research-plan.md`；本檔記載可重現的
   實作本步，四種模型六次執行全部無法維持完整分割，
   已棄用（詳見 `decision-log.md` 2026-08-05；棄用的
   定義檔止於 git 歷史，見 `git log -- prompts/`）。
-- **產物**：三份。分群明細 CSV（欄位 Group、Keyword，
-  一列一個成員，依兩欄排序）記錄機器算出的分割；組名
-  純文字檔（一行一個，字典序）是分群結果的可讀清單；
-  定案碼表 JSON（`{"keywords": [...]}`）記錄實際交給
-  模型的碼，即組名加上先驗主題詞。前兩份只含分群結果，
-  只有第三份含研究者的介入。
+- **產物**：五份，前綴分別標示來源與結果。
+  `source-keywords.txt`（進池後的關鍵字，一行一個）與
+  `source-provenance.csv`（出處）記錄進來的是什麼；
+  `result-keywords.txt`（組名，一行一個）與
+  `groups.csv`（欄位 Group、Keyword，一列一個成員）
+  記錄算出來的分割；`keywords-to-merge.json`
+  （`{"keywords": [...]}`）是實際交給模型的碼，即組名
+  加上先驗主題詞。只有最後一份含研究者的介入。
 - **可重現性**：同一輸入、同一釘定模型、同一參數逐次
   重現。不同 CPU／BLAS 實作的浮點尾數差異可能使邊界
   詞的歸屬翻動，屬已揭露的限制；論文所用碼表逐字
@@ -110,15 +112,12 @@ LLM。設計原則見 `research-plan.md`；本檔記載可重現的
   依歌曲 ID 升序。步驟 3 的輸入由同一子命令、同一工作
   儲存產出（見下），兩步的語料同一性由此成立；各步
   輸入檔的 SHA-256 記入該步 meta。
-- **步驟 1 → 2-1**：`pool-keywords` 讀兩份執行歸檔的
+- **步驟 1 → 2**：`cluster-keywords` 讀兩份執行歸檔的
   `output.jsonl`（一律以換行字元 `\n` 切行——歌詞含
   U+0085 等控制字元時，`str.splitlines()` 類的通用切行
-  會截斷 JSON 字串，實測踩中），輸出關鍵字純文字檔與
-  出處 CSV。
-- **步驟 2-1 → 2-2**：`cluster-keywords` 讀關鍵字池純
-  文字檔，輸出分群明細 CSV、組名純文字檔與定案碼表
-  JSON。
-- **步驟 2-2 → 3 輸入檔**：`export-llm-input --extras
+  會截斷 JSON 字串，實測踩中），進池後直接分群，一次
+  產出上列五份檔案。
+- **步驟 2 → 3 輸入檔**：`export-llm-input --extras
   <定案碼表>` 自工作儲存產出步驟 3 的輸入，每筆
   `{"id": "song-<ID>", "content": <字串>}`，`content` 為
   固定鍵序序列化的 `{"lyrics": …, "keywords": [...]}`，