Rebuild the vocabulary step on embeddings and drop the screen track

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

docs/methodology.md

@@ -6,116 +6,142 @@
 
 ## 自然編碼管線總覽
 
-四步驟：自由標註（tag，兩次進池）→ 自然收斂（merge，
-單次）→ 強制收斂（cap，單次）→ 全量編碼（code，2+1），
-另設「女性力量」單目標篩選（screen，2+1）作黃金標準取樣
-的補漏網。歌詞只出現在 tag、code、screen 與其仲裁步驟；
-merge、cap 不接觸歌詞。設計原則見 `research-plan.md`；
-本檔記載可重現的演算法細節。
+三個步驟：步驟 1 自由標註（兩次執行進池）→ 步驟 2 詞彙表
+建構（詞向量分群，確定性）→ 步驟 3 全量編碼（2+1）。歌詞
+只出現在步驟 1 與步驟 3；步驟 2 完全不接觸歌詞，也不呼叫
+LLM。設計原則見 `research-plan.md`；本檔記載可重現的
+演算法細節。
 
-## 詞彙表建構（merge、cap）——單次記錄性程序
+編號的所指為**研究程序的工序**，不是定義檔：步驟 1 與
+步驟 3 有定義檔（`prompts/`），步驟 2 沒有——它是確定性
+計算。有無定義檔的區別即「該步是否為 LLM 判斷」，由
+`prompts/` 是否存在同號檔案直接可見。
 
-merge 與 cap 各以單次執行完成，執行內自行為各組命名，
-輸出具名分組（組名 → 成員詞）。不做重複執行與仲裁。
+## 步驟 2 詞彙表建構——詞向量分群
 
-- **定位**：詞彙表是研究的儀器，不是量測。詞彙表凍結
-  入庫後，下游全部量測（編碼 vs 黃金標準）以同一把尺
-  進行，內部一致；建構過程的抽樣變異屬「揭露的儀器
-  選擇」，不污染量測。此與質性研究慣行一致——codebook
-  建構本為單次的詮釋程序，信度檢驗施於編碼應用層。
-- **取捨紀錄**：曾設計逐對仲裁鏈（共識塊、分歧塊對三票
-  多數、命名 2+1；完整版本保存於分支 `tag-algo-13`）。
-  棄用理由：逐對多數決雖降低單對變異，但遞移閉包會放大
-  結構層變異，淨縮減未經證實；其複雜度成本卻是確定的；
-  且縮減的是儀器變異——對論文主張無關緊要的量。
-- **確定性驗證**（違規即依協定修訂定義檔重跑）：輸出須
-  為輸入詞集的完整分割（缺詞、多詞、重複即失敗）；組名
-  唯一且符合格式；cap 組數 ≤ 50。
-- **收斂軌跡**：原始關鍵字 → merge 組名 → cap 組名，
-  兩份執行輸出本身即完整記錄。
+詞彙表由確定性程序產生，不經 LLM。完整分割（每個關鍵字
+恰屬一組、不遺漏、不新增）由演算法結構保證，無須事後
+驗證。
 
-## 編碼步驟（code、screen）的 2+1 比對與仲裁
+### 步驟 2-1 進池
 
-- **code**：逐首比對兩次執行的標籤集合（引述不參與
-  比對）。兩次皆有的標籤為共識保留、兩次皆無為共識
-  不標；單邊標籤送仲裁（`01-04-02-code-arb.md`）——仲裁者
-  看歌詞全文與該標籤的引述（不含執行別），裁決保留者
-  附仲裁者自己的引述，剔除者不列。剔除集合＝送裁鍵減
-  輸出鍵，由程式推得。
-- **screen**：輸出即引述陣列，非空＝有、空＝無。僅
-  「一有一無」的歌送仲裁（`02-01-02-screen-arb.md`），
-  輸入為歌詞加主張「有」方的引述（不記名），輸出同為
-  引述陣列。
+兩次標註執行的全部關鍵字取聯集、逐字串精確去重、字典序
+排列。失敗與拒答的記錄跳過（其歌曲不貢獻關鍵字）；解析
+時偵測重複鍵，違規即失敗。同時寫出處記錄（關鍵字 →
+（執行別，歌曲 ID）清單），供收斂軌跡分析；出處記錄不
+進任何下游輸入。
+
+### 步驟 2-2 分群
+
+- **嵌入**：`sentence-transformers/all-mpnet-base-v2`
+  （釘定 revision），關鍵字的連字號先還原為空格再編碼，
+  輸出 768 維向量並 L2 正規化。
+- **分群**：階層式聚合分群（Ward linkage），k=50。
+  向量既已正規化，歐氏距離與餘弦相似度單調對應，Ward
+  在保持語意距離的同時給出大小平衡的分割。
+- **組名**：取 medoid——與該組中心（成員向量均值後
+  正規化）餘弦相似度最高的成員詞。組名因此必為模型
+  自己產出過的關鍵字，非任何人事後撰寫。
+- **取捨紀錄**：曾以 LLM 單發收斂（merge／cap 兩步）
+  實作本步，四種模型六次執行全部無法維持完整分割，
+  已棄用（詳見 `decision-log.md` 2026-08-05；棄用的
+  定義檔止於 git 歷史，見 `git log -- prompts/`）。
+- **可重現性**：同一輸入、同一釘定模型、同一參數逐次
+  重現。不同 CPU／BLAS 實作的浮點尾數差異可能使邊界
+  詞的歸屬翻動，屬已揭露的限制；論文所用詞彙表逐字
+  commit，引用單位為該份定案檔案。
+
+### women-power 的注入
+
+定案詞彙表為 50 個分群組名再加上 `women-power` 一詞，共
+51 個碼。`women-power` 是研究者任意決定的先驗主題（即本
+論文的主題本身），不由資料產生，屬揭露的儀器介入。
+
+注入而非另設篩選軌的理由：讓研究者的主題詞與模型自己
+收斂出的類別（分群已自行長出 `female-empowerment` 等組）
+在同一份提示詞、同一個判斷體制下受檢，避免單目標提問
+把該主題的顯著性人為抬高。兩者的落點差異本身即可報告
+的結果。
+
+## 步驟 3 編碼的 2+1 比對與仲裁
+
+- **步驟 3-1 code**：逐首比對兩次執行的標籤集合（引述不
+  參與比對）。兩次皆有的標籤為共識保留、兩次皆無為
+  共識不標；單邊標籤送仲裁。
+- **步驟 3-2 code-arb**：仲裁者看歌詞全文與該標籤的引述
+  （不含執行別），裁決保留者附仲裁者自己的引述，剔除
+  者不列。剔除集合＝送裁鍵減輸出鍵，由程式推得。
 - 仲裁者的引述可能與原引述不同：仲裁是對歌詞的重新
   判讀，其引述是該裁決自身的依據，非轉抄。
 - 送入仲裁的標籤即模型自身不穩定的邊界判斷，其裁決為
   單次記錄性決定，不宣稱可再生；可重現性依計畫定義為
   「程序透明＋可稽核」，裁決與其輸入全程歸檔。
 
+## 女性力量候選集
+
+候選集為兩類歌曲的合集：定案編碼含 `women-power` 者，
+以及定案編碼含研究者指認之女性力量概念域分群組者。
+指認於詞彙表定案後、黃金標準編碼開始前完成，指認清單
+與理由記入決策日誌。
+
 ## 軌跡對映（診斷用）
 
-沿收斂軌跡的機械對映：原始關鍵字 → merge 組 → cap 組，
-純程式查表，決定性。以其結果與 code 直接編碼的差異率
-作為「收斂軌跡扭曲」的診斷量，不作主結果。
+沿收斂軌跡的機械對映：原始關鍵字 →（出處記錄）歌曲、
+原始關鍵字 →（分群）組，純程式查表，決定性。以其結果
+與步驟 3 直接編碼的差異率作為「收斂軌跡扭曲」的診斷量，
+不作主結果。
 
 ## 全管線的交接契約
 
 每一步的輸出如何變成下一步的輸入，皆為確定性程序，規則
 明定如下：
 
-- **歌詞輸入檔（tag、code、screen 共用）**：
-  `export-llm-input` 自工作儲存產出，每筆
-  `{"id": "song-<ID>", "content": <歌詞>}`，依歌曲 ID
-  升序。三個讀歌詞的步驟共用同一檔，SHA-256 記入各步
+- **歌詞輸入檔（步驟 1、3 共用）**：`export-llm-input` 自
+  工作儲存產出，每筆 `{"id": "song-<ID>", "content":
+  <歌詞>}`，依歌曲 ID 升序。兩個讀歌詞的步驟共用同一
+  檔，SHA-256 記入各步 meta。
+- **步驟 1 → 2-1**：`pool-keywords` 讀兩份執行歸檔的
+  `output.jsonl`（一律以換行字元 `\n` 切行——歌詞含
+  U+0085 等控制字元時，`str.splitlines()` 類的通用切行
+  會截斷 JSON 字串，實測踩中），輸出關鍵字 JSON 陣列
+  與出處記錄。
+- **步驟 2-1 → 2-2**：`cluster-keywords` 讀關鍵字陣列，
+  輸出具名分組（組名 → 成員詞，組名與成員皆字典序）
+  與記錄嵌入模型、revision、演算法參數、輸入 SHA-256 的
   meta。
-- **tag → merge**：兩次執行的全部關鍵字取聯集、逐字串
-  精確去重、字典序排列成 JSON 陣列，即 merge 的輸入。
-  進池同時寫出處記錄（關鍵字 →（執行別，歌曲 ID）
-  清單），供軌跡對映回到歌曲；出處記錄不進任何 LLM
-  輸入。
-- **merge → cap**：merge 輸出的組名以字典序排成 JSON
-  陣列，即 cap 的輸入；原始關鍵字不下傳。
-- **cap → code 定義檔**：cap 輸出的組名以字典序逐行填入
-  `01-04-01-code.md` 的詞彙表節（逐字），檔案隨 git
-  commit 後方可執行——code 的定義檔因此自我完備，
-  論文附錄可直接引用。
-- **code 兩次執行 → code-arb**：逐首比對標籤集合
-  （鍵集合，引述不參與比對）；僅有分歧的歌入仲裁輸入
+- **步驟 2-2 → 3 定義檔**：50 個組名與 `women-power` 合併
+  後以字典序逐行填入 `prompts/03-01-code.md` 的詞彙表節
+  （逐字），檔案隨 git commit 後方可執行——步驟 3 的
+  定義檔因此自我完備，論文附錄可直接引用。
+- **步驟 3-1 兩次執行 → 3-2**：逐首比對標籤集合（鍵
+  集合，引述不參與比對）；僅有分歧的歌入仲裁輸入
   JSONL，依歌曲 ID 升序，每筆 `id` 沿用 `song-<ID>`、
   `content` 為固定鍵序序列化的
   `{"lyrics": …, "disagreements": …}`，disagreements
   鍵按字典序。
-- **code 定案**：每首歌的最終標籤＝共識標籤 ∪ 仲裁保留
-  標籤，寫入逐首紀錄檔（歌依 ID 升序、標籤按字典序，
-  各標籤附其定案時的引述與來源層——共識或仲裁）。
-- **screen 兩次執行 → screen-arb**：僅「一有一無」的歌
-  入仲裁輸入 JSONL（依 ID 升序），`content` 為
-  `{"lyrics": …, "evidence": <肯定方引述>}`。
-- **screen 定案**：命中集合＝兩次皆有 ∪ 仲裁裁定有。
-- **女性力量候選集**：於 cap 詞彙表定案後、黃金標準
-  編碼開始前，由研究者指認詞彙表中屬「女性力量」概念
-  域的組（指認及理由記入決策日誌），候選集＝code 定案
-  標籤含該等組者 ∪ screen 命中者。
+- **步驟 3 定案**：每首歌的最終標籤為共識標籤加上仲裁
+  保留的標籤，寫入逐首紀錄檔（歌依 ID 升序、標籤按
+  字典序，各標籤附其定案時的引述與來源層——共識或
+  仲裁）。
 - **序列化通則**：所有中間檔為 UTF-8 JSON，鍵序與元素
   序皆依上列規則明定，無時間戳、無隨機成分；解析一律
-  偵測重複鍵，違規即失敗。JSONL 一律以換行字元（\n）
-  切行——歌詞含 U+0085 等控制字元時，
-  `str.splitlines()` 類的通用切行會截斷 JSON 字串
-  （實測踩中）。給定相同的 LLM 執行輸出，全部交接產物
-  逐位元組可再生。
+  偵測重複鍵，違規即失敗。給定相同的 LLM 執行輸出，
+  全部交接產物逐位元組可再生。
 
 ## 執行與稽核
 
-- 每一步驟以 `run-llm <定義檔> <輸入檔> <歸檔目錄>`
+- LLM 步驟以 `run-llm <定義檔> <輸入檔> <歸檔目錄>`
   執行；2+1 步驟的兩次執行＝重現命令清單上的兩行命令，
-  各自歸檔（`runs/<定義檔名>/run1`、`run2`），仲裁為
-  獨立步驟、獨立歸檔；單次步驟（merge、cap）一行命令、
-  一份歸檔。
-- 進池、比對、裁決套用、對映皆為確定性程式（子命令），
-  其輸入輸出檔隨 runs/ 歸檔。
+  各自歸檔（`runs/<步驟>/run1`、`run2`），仲裁為獨立
+  步驟、獨立歸檔。
+- 確定性步驟（進池、分群、比對、裁決套用、對映）為
+  子命令，其輸入輸出檔同隨 `runs/` 歸檔；因無執行變異，
+  歸檔目錄下不分 `run<N>` 層。
 - Batch API 的每筆請求自含全部脈絡且互不可見（平台
   契約），歌與歌之間的獨立性由此成立；兩次執行的獨立
   性由「兩次呼叫、兩個批次、兩份歸檔」的執行結構自明。
+- 每次 `run-llm` 執行的 token 用量與費用記入
+  `run-costs.md`，被取代的執行一併保留供總支出核算。
 
 ## 映射分析方法