Add the reliability measurement record to the docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/project-structure.md

@@ -1,7 +1,7 @@
 # 專案目錄結構
 
 （2026-07-30 討論定案；2026-07-31 更新為 tools/ 子專案與
-SQLite 工作儲存架構）
+SQLite 工作儲存架構；2026-08-17 依完成後的現況更新）
 
 ```
 pop-fem-audit/
@@ -19,12 +19,18 @@ pop-fem-audit/
 │   │   └── lyrics/                        # 歌詞 .txt 快取
 │   │                                      #   （gitignored，版權）
 │   ├── manual/                # 人工著作：只由研究者手寫
-│   │                          #   （黃金標準編碼等）
+│   │   ├── coding-corrections.csv         # 編碼與引述的校對表
+│   │   └── performer-gender-corrections.csv  # 演唱聲音性別的
+│   │                                      #   手工修正
 │   └── derived/               # 衍生：只由 build-db 寫入
 │       ├── songs.csv          # 歌曲報表（人讀；進 git）
 │       └── artists.csv        # 歌手報表（人讀；進 git）
 ├── prompts/                   # LLM 定義檔（逐字作為 system prompt）
-│   └── <步>-<次步>-<task>.md  # 01-tag.md、03-code.md
+│   └── <步>-<次步>-<task>.md  # 01-tag.md、03-code.md、
+│                              #   04-group.md、05-01-read.md、
+│                              #   05-02-consolidate.md、
+│                              #   05-03-synthesize.md、
+│                              #   05-04-annotate.md
 │                              #   （步內僅一個執行時省略次步）
 │                              #   不帶版本號，版本即 git 歷史
 │                              #   （編號的所指是工序：確定性
@@ -52,6 +58,9 @@ pop-fem-audit/
 │   │   │   ├── cluster_keywords.py # pool the tagging runs'
 │   │   │   │                       #   keywords and cluster them
 │   │   │   │                       #   into the codes (step 2)
+│   │   │   ├── tally_codings.py    # settle step 3 by majority
+│   │   │   ├── tally_groups.py     # settle step 4 by majority
+│   │   │   ├── tally_annotations.py # settle step 5-4 by majority
 │   │   │   └── run_llm.py     # API 執行器：一份定義檔＋一份輸入
 │   │   │                      #   →歸檔至指定目錄（Batch API）；
 │   │   │                      #   多次執行的計票由獨立子命令承擔
@@ -62,7 +71,10 @@ pop-fem-audit/
 │   └── tests/                 # 單元測試（unittest）
 ├── runs/                      # 現行執行的完整稽核紀錄（進 git；
 │   │                          #   重跑同一 run 須明示 --replace）
-│   ├── <步驟名>/              #   一步一個目錄（如 03-code）
+│   ├── <步驟名>/              #   一步一個目錄（01-tag、03-code、
+│   │                          #   04-group、05-01-read、
+│   │                          #   05-02-consolidate、
+│   │                          #   05-03-synthesize、05-04-annotate）
 │   │   └── run<N>/            #   LLM 步驟：每個 run 一份自我
 │   │       ├── prompt.md      #   完備歸檔（定義檔快照）
 │   │       ├── output.jsonl   #   該次執行原始輸出
@@ -70,19 +82,24 @@ pop-fem-audit/
 │   │                          #   batch ID、token 用量
 │   └── 02-cluster/           # 確定性步驟：無執行變異，
 │                              #   不分 run<N> 層
-├── results/                   # 論文引用的報表 CSV（export 產出；
-│                              #   「可再生仍 commit」的唯一例外）
+├── results/                   # 論文引用的定案表 CSV（計票子命令
+│   │                          #   產出；「可再生仍 commit」的例外）
+│   ├── codings.csv            # 步驟 3 定案編碼
+│   ├── groups.csv             # 步驟 4 定案編碼群
+│   ├── patterns.csv           # 步驟 5-3 定案樣態表
+│   ├── annotations.csv        # 步驟 5-4 定案歌×樣態
+│   └── pattern-matrix.csv     # 前四者的人讀寬表
 ├── docs/
 │   ├── research-plan.md       # 研究步驟規劃（本檔之姊妹篇）
 │   ├── project-structure.md   # 本檔
-│   ├── codebook.md            # 人工編碼手冊（版本由 git 管理）
+│   ├── output-validation.md   # LLM 輸出的契約查核紀錄
 │   ├── decision-log.md        # 決策日誌：每次改定義檔的原因
 │   ├── run-costs.md           # 每次執行的 token 用量與費用
 │   └── methodology.md         # 方法細節（全文方法節底稿；
 │                              #   映射分析方法須在看結果前寫定）
 └── paper/
-    ├── conference-abstract.md # pilot 摘要（投稿版）
-    └── full-paper.md          # 全文
+    ├── conference-abstract.md # 先導研究摘要（投稿版）
+    └── 流行音樂中「女性力量」….odt  # 全文
 ```
 
 ## 設計理由
@@ -94,12 +111,15 @@ pop-fem-audit/
 - **`prompts/` 檔名不帶版本號**：版本即 git 歷史，失敗的
   版本不保留；論文引用的單位是 `runs/` 內隨執行保存的定義檔
   快照（每個執行目錄自我完備），不需檔名可指的版本名。
-- **工作儲存的資料表**：`songs`、`chart_entries`、`artists`、
-  `song_artists`、`codings`（定案編碼：一歌一標籤一列，`quotes`
-  存該標籤所據的歌詞引述，多句以 `|` 相接）。定案表
-  `results/codings.csv` 經 `build-db --codings` 匯入，與其餘資料
-  同一交易，儲存不會半建；詳見 `research-plan.md`「資料儲存與
-  模型」。
+- **工作儲存的資料表**：`songs`（含 `performer_gender`＝演唱
+  聲音的性別）、`chart_entries`、`artists`、`song_artists`、
+  `codings`（定案編碼：一歌一標籤一列，`quotes` 存該標籤所據的
+  歌詞引述，多句以 `|` 相接）、`groups`（語意編碼群）、
+  `patterns`（深讀樣態）、`annotations`（歌×樣態定案矩陣）。
+  各定案表經 `build-db` 的 `--codings`、`--groups`、
+  `--patterns`、`--annotations` 匯入，性別修正經
+  `--gender-corrections` 套用，與其餘資料同一交易，儲存不會
+  半建；詳見 `research-plan.md`「資料儲存與模型」。
 - **Commit 判準**：能由「committed 輸入＋程式」決定性再生者不
   commit（SQLite 工作儲存、LLM 輸入檔）；源頭、捕捉、人工著作
   一律以文字 commit。「可再生仍 commit」的例外有二：

docs/reliability.md

@@ -0,0 +1,161 @@
+# 信度:量測方式與結果
+
+（2026-08-16 量測。對象為步驟 3 的三份執行歸檔
+`runs/03-code/run1`–`run3`,與步驟 5-4 的三份執行歸檔
+`runs/05-04-annotate/run1`–`run3`;數字由原始輸出直接計算。）
+
+## 一、本研究的信度是什麼
+
+**信度(reliability)** 問的是:同一個量測重複做,會不會得到
+同樣的結果。它管的是**一致性**,不管對錯。一把每次都少兩公斤
+的秤,信度很好、效度很差。**效度(validity)** 問的則是:量到
+的是不是想量的東西。
+
+Krippendorff 依產生資料的設計,把信度分成三型
+(Krippendorff, 2004;Hayes & Krippendorff, 2007):
+
+- **穩定性(stability)**:同一位觀察者、同樣的材料,重複
+  量測是否一致(test–retest,即 intra-observer)。
+- **可複製性(reproducibility)**:不同觀察者各自獨立量測
+  是否一致,即一般所稱的**編碼者間信度**
+  (inter-coder reliability)。Krippendorff 認為這是內容
+  分析中最強、也最可行的一型,因為它排除了「這些類目只是
+  某一個人特異的讀法」的疑慮。
+- **準確性(accuracy)**:與已知標準比對。
+
+**本研究三次獨立執行量到的是第一型。**同一個模型、同一份
+定義檔、同一批輸入,重複三次,量到的是這個編碼者自己前後
+一不一致。第二型在本設計中**結構上不存在**:編碼者只有一位,
+不同的模型版本(Sonnet 4.6、Fable 5)也不是「不同的編碼者」,
+而是不同的儀器。第三型**未量測**:沒有黃金標準可比。
+
+以工程的語言說更精確:這裏量的是**儀器的重複性
+(repeatability)**,亦即**隨機性有多大**;計量學上稱之為
+**精密度(precision)**,而**準確度(accuracy)** 未經量測。
+若儀器是確定性的,重複性無須量測;但 LLM 不是——同樣的提示、
+同樣的輸入,三次會給出不同結果,因此重複性是必須報告的儀器
+規格,而非慣例儀式。
+
+這一點與 LLM 標註的近期文獻一致:同一模型重複取樣量測的是
+自我一致性(self-consistency),而重複執行後取多數決可提升
+標註穩定度(如 Prompt Stability Scoring,arXiv:2407.02039)。
+
+## 二、三個常用指標
+
+以「這首歌有沒有這個碼」這種是非題為例:
+
+- **百分比一致率**:兩次判斷相同的格子佔全部格子的比例。
+  最直觀,但會被「碰巧同意」灌水——當九成五的格子都是
+  「無」,兩次隨便判也會有九成以上一致。
+- **Cohen's κ(kappa)**:把「碰巧同意」的部分扣掉之後的
+  一致度,兩位編碼者用。0 表示與隨機無異,1 表示完全一致。
+  慣例上 0.61–0.80 稱為 substantial、0.81 以上稱為
+  almost perfect(Landis & Koch 1977 的分級)。
+- **Krippendorff's α**:可處理兩位以上編碼者、缺漏值與
+  不同尺度,是內容分析文獻最常被要求的指標。慣例門檻為
+  α ≥ 0.800 可作結論、0.667–0.800 只能作暫定結論
+  (Krippendorff 的建議)。
+
+三者裏,**百分比一致率會高估、κ 與 α 才是可比較的數字**。
+
+補充一個常被誤解的方向:κ 的著名「悖論」
+(Feinstein & Cicchetti, 1990)是**類別分佈極不平衡時,
+高一致率反而算出很低的 κ**——偏斜會壓低 κ,不會抬高它。
+本研究的正例只佔 16.5%(89,183 格中約 14,700 格有碼),
+在這種偏斜下 κ 仍達 0.93,屬於保守估計,不是被大量「雙方
+都判無」灌出來的。
+
+## 三、實測結果
+
+### 步驟 3(編碼:883 首 × 101 個碼 = 89,183 格,執行三次)
+
+| 兩次執行 | 百分比一致率 | Cohen's κ | Jaccard |
+|---|---:|---:|---:|
+| run1 × run2 | 98.10% | 0.931 | 0.891 |
+| run1 × run3 | 98.09% | 0.931 | 0.891 |
+| run2 × run3 | 98.26% | 0.937 | 0.900 |
+
+**Krippendorff's α = 0.933**(三次執行合計)。
+
+三票計票的分佈:三票全同 13,500 格、兩票 1,163 格、
+僅一票 1,310 格(未達門檻而剔除)。**定案的 14,663 個編碼
+中,92.1% 是三次全數同意的**。
+
+(此處由原始輸出計算,未套用 936 筆人工校對表;論文引用的
+定案數 14,664 為校對後的結果,差 1 筆。)
+
+### 步驟 5-4(樣態標註:111 首 × 各自適用樣態 = 3,708 格,執行三次)
+
+| 兩次執行 | 百分比一致率 | Cohen's κ | Jaccard |
+|---|---:|---:|---:|
+| run1 × run2 | 97.87% | 0.933 | 0.898 |
+| run1 × run3 | 98.17% | 0.942 | 0.911 |
+| run2 × run3 | 97.87% | 0.933 | 0.898 |
+
+**Krippendorff's α = 0.936**。三票全同 675 格、兩票 62 格、
+僅一票 51 格;**定案的 737 筆歸屬中,91.6% 三次全同**。
+
+### 怎麼讀這些數字
+
+κ 與 α 都在 0.93 上下,以慣例分級屬於 almost perfect,
+也高於 α ≥ 0.800 的門檻。用白話說:**這個編碼者重複三次,
+判斷幾乎不變;會左右搖擺的,是那一成左右的邊緣案例,而
+三票多數決正是為它們設計的**。
+
+Jaccard(只看「有標到」的格子,忽略雙方都沒標的)約 0.89–0.91,
+比百分比一致率低而更誠實——因為 82% 的格子是雙方都判「無」,
+那些一致並不費力。
+
+## 四、隨機性的規模與三票制的作用
+
+信度數字回答的實際問題是:**這台儀器的隨機性,大到會不會
+改變結論?**
+
+步驟 3 的 89,183 格中,搖擺的格子共 2,473 格(兩票 1,163、
+一票 1,310),佔 2.8%。若只執行一次即定案,這批格子當中約
+一半會成為誤收、另一半會成為漏收。三票多數決把兩票以上者
+收入、一票者剔除,處理的正是這一批。
+
+三票制並非消除隨機性,而是**把隨機性往案例原本的傾向推**。
+設某個邊緣案例的符合程度為 p,單次執行以機率 p 標出,三次
+多數決則以 p³+3p²(1−p) 標出:p=0.9 者由 0.9 提高到 0.972,
+p=0.1 者由 0.1 壓低到 0.028,而 p=0.5 者仍是 0.5——真正
+模稜兩可的案例,任何票制都救不了。
+
+以此規模判斷,結論層的三條帶狀結構(女性力量與陽剛群共現、
+與脆弱群互斥、與厭女群獨立)不可能由這個量級的雜訊翻轉。
+反過來說,若一致率只有 0.6,同一組結論就不能採信——信度
+數字的用途在此,而不在滿足慣例。
+
+## 五、這些數字證明了什麼、不能證明什麼
+
+**能證明**:量測是穩定的,結果不是單次抽樣的偶然;
+三票多數決確實只在少數邊緣格子上發揮作用(約 3%)。
+
+**不能證明**:判斷是正確的。三次共用同一個模型與同一份
+先驗,能濾掉隨機噪音,濾不掉系統性偏誤。本研究已發現三個
+三次一致的錯誤可作實例:Sonnet 4.6 穩定地將 Women Power
+讀為 Women+Power;深讀階段將〈Cowgirls〉中握韁繩者判反、
+將〈Happen To Me〉分屬兩段的引文接成同一動機。一把每次都
+量出同樣偏差的尺,重複性滿分,準確度為零。
+
+**結構上沒有**:編碼者間信度。要有它,需要第二個獨立的
+觀察者——另一個模型,或研究者人工編一小批對照。本研究
+未做,列為限制。
+
+## 六、計算方式與依據
+
+- **分析單位**:每一個「(歌曲, 編碼)」格為一個單位,是非題
+  (有標／無標)。步驟 3 為 883 首 × 101 碼 = 89,183 格;
+  步驟 5-4 為各歌適用樣態數合計 3,708 格。
+- **Cohen's κ**:兩次執行的 2×2 表,κ=(p_o−p_e)/(1−p_e),
+  p_e 由兩次各自的邊際比例相乘求得。
+- **Krippendorff's α(名目、三位「編碼者」、無缺漏)**:
+  α=1−D_o/D_e;某單位若有 v 次標為「有」,其不一致配對數為
+  v(3−v),D_o 為其總和除以總配對數,D_e 由整體「有／無」的
+  邊際比例求得。
+- **門檻依據**:κ 的分級為 Landis & Koch (1977)
+  (0.61–0.80 substantial、0.81–1.00 almost perfect);
+  α 的門檻為 Krippendorff 的建議(≥0.800 可作結論、
+  0.667–0.800 僅能作暫定結論)。
+- 數字由原始執行輸出直接計算,未套用 936 筆人工校對表。