Fix the SonarQube findings

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

README.md

@@ -1,6 +1,6 @@
 # 流行音樂中「女性力量」語彙的挪用與污染——以 Billboard Year-End Hot 100（2016-2025）為例的內容分析
 
-這是研究論文《流行音樂中「女性力量」語彙的挪用與污染——以 Billboard Year-End Hot 100（2016-2025）為例的內容分析》的專案資料，包括論文本身、文件、紀錄、資料、工具程式、LLM提示詞，等等。
+這是研究論文《流行音樂中「女性力量」語彙的挪用與污染——以 Billboard Year-End Hot 100（2016-2025）為例的內容分析》的專案資料，包括論文本身、文件、紀錄、資料、工具程式、AI提示詞，等等。
 
 ## 論文和摘要
 
@@ -10,17 +10,9 @@
 
 研究方法、記錄等文件，請參閱 docs/ 資料夾。
 
-## LLM提示
-
-LLM提示請參閱 prompts/ 資料夾。
-
 ## 輔助工具程式
 
-輔助工具程式請參閱 tools/ 資料夾。
-
-## 研究資料
-
-研究資料請參閱 data/ 資料夾。
+輔助工具程式，請參閱 tools/ 資料夾。
 
 ## 授權
 

docs/conventions.md

@@ -1,69 +1,78 @@
-# 常設工作規範
+# Project Conventions
 
-本專案的常設工作規範。原專案 `CLAUDE.md`；移置於此，
-使 Claude Code subagent 不將其繼承入 context（盲判型
-agent 不得見之）。凡於本專案工作的主會話，動手管線、
-資料或文件之前，先讀本檔。
+The standing working rules of this project.  Formerly the
+project `CLAUDE.md`; moved here so that Claude Code subagents
+do not inherit it into their context (blind-reading agents
+must not see it).  A main session working on this project
+reads this file before touching the pipeline, the data, or
+the documents.
 
-## 分析管線
+## Analysis pipeline
 
-管線已跑畢；本規範適用於任何重跑或擴充。
+The pipeline has run to completion; these conventions govern
+any rerun or extension.
 
-- LLM 分析以 Python 腳本呼叫 Anthropic Messages API
-  執行，能用 Batch API 處即用之。步驟 1 與步驟 3 以
-  `claude-sonnet-4-6` 執行，`temperature=0`、thinking
-  停用；步驟 4 與步驟 5 以 `claude-fable-5` 執行，該
-  模型兩個參數皆不受理——步驟 4 的取樣變異由多數決
-  吸收，步驟 5 由整合三份閱讀吸收。
-- 定義檔置於 `prompts/<步><次步>-<task>.md`（如
-  1-tag.md、5a-read.md；次步以字母標示，與論文正文的
-  步驟編號一致；不帶版本號——版本即 git 歷史），逐字
-  作為 system prompt。
-- 逐項的 LLM 判斷（步驟 3 的逐首編碼、步驟 4 的逐碼
-  入群判斷）以同一份定義檔、同一份輸入獨立執行三次；
-  再由確定性計票將三次執行中至少兩次指派的項目（一個
-  （歌，關鍵字）或（群，關鍵字）配對）收入定案
-  （「三次執行＋多數決」）。自由生成步驟執行兩次，
-  兩份輸出進池。步驟 5 的質性閱讀兩者皆非：逐首三次
-  獨立閱讀，由各自的定義檔逐首整合、跨首統整——質性
-  協定，不是投票（見 docs/methodology.md）。詞彙表由
-  確定性子命令建構（嵌入＋分群），不經 LLM。驗證結果
-  不符預期時，修訂定義檔並重複該循環；絕不手改結果。
-- 一步的每次執行皆自我完備歸檔於 `run-llm` 命令列上
-  明示指定的目的目錄下（慣例為
-  `data/runs/<步驟>/run<N>/`）：定義檔快照、原始輸出與
-  `meta.json`（model ID、參數、時間戳、batch ID）。
-  一步的 N 次執行即 N 次各自的 `run-llm` 呼叫。覆蓋
-  既有執行歸檔須明示旗標；被取代的執行留在 git 歷史。
-  確定性步驟歸檔於 `data/runs/<步驟>/`，不分 `run<N>` 層。
-- 每次 `run-llm` 執行的 token 用量與費用記入
-  `docs/run-costs.md`，與執行歸檔同一 commit。
-- 腳本自環境變數 `ANTHROPIC_API_KEY` 讀取 API key
-  （`.env`，gitignored）。
+- LLM analysis runs via Python scripts calling the Anthropic
+  Messages API, Batch API where possible.  Steps 1 and 3 run
+  on `claude-sonnet-4-6` with `temperature=0` and thinking
+  disabled; steps 4 and 5 run on `claude-fable-5`, which
+  accepts neither parameter -- step 4 absorbs its sampling
+  variance by the majority vote, step 5 by consolidating the
+  three readings.
+- Prompt definition files live in
+  `prompts/<step><substep>-<task>.md` (e.g. 1-tag.md,
+  5a-read.md; substeps are lettered, matching the step
+  numbering of the paper; no version suffix -- versions live
+  in git history) and are passed verbatim as the system
+  prompt.  The number names a step of the research
+  procedure, not the file: the deterministic vocabulary step
+  (step 2) has no definition file yet holds its own number.
+- Itemwise LLM judgments (per-song coding in step 3,
+  per-keyword group selection in step 4) run the same
+  definition file three times, independently, over the same
+  input; a deterministic tally then assigns an item (a
+  (song, keyword) or (group, keyword) pair) when at least
+  two of the three runs assign it ("3 runs + majority
+  vote").  Free-generation steps run
+  twice and both outputs are pooled.  The step-5 qualitative
+  readings are neither: three independent readings per song,
+  consolidated per song and synthesized across songs by
+  their own definition files -- a qualitative protocol, not
+  a vote (see docs/methodology.md).  The vocabulary is
+  built by a deterministic subcommand (embedding +
+  clustering), not by an LLM.  If a validation outcome is
+  unexpected, revise the definition file and repeat that
+  cycle; never patch results by hand.
+- Each run of a step is archived self-contained under the
+  destination directory given explicitly on the `run-llm`
+  command line (by convention `runs/<step>/run<N>/`):
+  prompt snapshot, raw output, and `meta.json` (model ID,
+  parameters, timestamps, batch ID).  The runs of a step are
+  that many separate invocations of `run-llm`.  Replacing
+  an existing run archive requires an explicit flag;
+  superseded runs live in git history.  Deterministic steps
+  archive under `runs/<step>/` with no `run<N>` level.
+- Token usage and cost of every `run-llm` execution are
+  recorded in `docs/run-costs.md` in the same commit as the
+  run archive.
+- Scripts read the API key from the `ANTHROPIC_API_KEY`
+  environment variable (`.env`, gitignored).
 
-## 資料規則
+## Data rules
 
-- `data/source/` 存手放後不動的原始檔；
-  `data/captures/` 只由 fetch 命令與私人匯入腳本
-  寫入；`data/manual/` 只由研究者親手寫入；
-  `data/derived/` 只由 `build-db` 子命令寫入；
-  `data/runs/` 存 LLM 執行的原始歸檔，只由執行程序
-  寫入；`data/results/` 存論文引用的定案表，只由
-  計票程序寫入。
-- 歌詞全文有版權：一律置於 `data/captures/lyrics/`
-  （gitignored），絕不 commit，亦絕不於 repo 任何處
-  全文重現。
+- `data/source/` holds the immutable hand-placed raw files;
+  `data/captures/` is written only by the fetch commands and the
+  private import script; `data/manual/` is written only by the
+  user's own hand; `data/derived/` is written only by the
+  `build-db` subcommand.
+- Full lyrics are copyrighted: they stay in `data/captures/lyrics/`
+  (gitignored) and must never be committed or reproduced in
+  full anywhere in the repo.
 
-## 文件
+## Documents
 
-- `data/results/` 存計票後的定案表（論文所引）；
-  `data/runs/` 存原始稽核紀錄。論文只引 `data/results/`。
-- **Commit 判準**：凡能由「committed 的輸入＋committed
-  的程式」決定性再生者不 commit；凡不能者一律以文字
-  格式 commit，格式跟著上文「資料規則」一節所定的
-  層次走。例外：`data/results/` 定案表與
-  `data/derived/` 人讀報表雖可再生仍 commit——理由是
-  引用穩定性、審稿人零門檻、撰稿期數字變動可 diff；
-  兩者皆與工作儲存同一動作產出，稽核鏈無中間空缺。
-- 凡定義檔或研究規劃之更動，皆記入
-  `docs/decision-log.md`，註明日期與原因。
+- `results/` holds the final tallied tables (what the paper
+  cites); `runs/` holds raw audit records.  The paper cites
+  `results/` only.
+- Any change to a definition file or the plan is recorded in
+  `docs/decision-log.md` with date and reason.

docs/decision-log.md

@@ -99,8 +99,8 @@
 
 ## 2026-08-02
 
-- **`import-lyrics` 不設為子命令，pilot 歌詞改以私人腳本
-  匯入**。理由：pilot 捕捉檔不隨論文發布，子命令
+- **`import-lyrics` 不設為子命令，pilot 歌詞改以 `excludes/`
+  私人腳本匯入**。理由：pilot 捕捉檔不隨論文發布，子命令
   形式會在發布的 CLI 裡留下讀者無法執行的死命令——要交待的
   是「沿用 pilot 捕捉」的事實（記於 lyrics-provenance.csv 與
   論文方法節），不是工具本身；工具移出專案，發布管線即
@@ -178,8 +178,8 @@
   來源公開可稽核，快照乾淨、overrides 縮小；論文方法節揭露
   「捕捉前經研究者查證補完」。性別以公開自我認同為準，
   推測不確定且無佐證者列疑慮清單；查證屬資料策展而非
-  分析，以 Claude Code 輔助、不走分析 API；QS 批次以
-  私人工作檔留存，不隨論文發布。
+  分析，以 Claude Code 輔助、不走分析 API；QS 批次存
+  `excludes/`（私人工作檔，不隨論文發布）。
 
 ## 2026-08-04
 
@@ -227,7 +227,7 @@
 - **Markdown 檔名一律以 dash 連接**（decision-log.md、
   research-plan.md、project-structure.md 等；與 data/ 層
   CSV 檔名慣例一致），定義檔命名慣例同步改為
-  `prompts/<task>-v<N>.md`（如 screen-v1.md），版本庫外的
+  `prompts/<task>-v<N>.md`（如 screen-v1.md），`excludes/`
   私人工作檔一併改名；`conference_abstract.md` 改名並搬入
   `paper/`——它是本次年會實際送出的摘要，與全文同屬投稿
   血脈，不是 `docs/` 的內部工作文件。全 repo 指涉同步更新。
@@ -583,8 +583,8 @@
   Billboard 署名 Pinkfong 為品牌（Wikidata Q55735607，型態
   brand），非演唱者；其唯一上榜曲 Baby Shark（2019#75）
   的實際演唱者為 Hope Segoine（KTVB 2019-03-06 報導、
-  Songfacts、經紀簡介，出處詳私人留存的
-  QuickStatements 草稿）。藉既有的
+  Songfacts、經紀簡介，出處詳
+  `excludes/quickstatements/hope-segoine.md`）。藉既有的
   署名正規化機制（`ArtistImporter.CANONICAL_ARTIST_NAMES`）
   指認：歌曲的署名字串維持榜單所印的 "Pinkfong"，解析出
   的演出者實體為 Hope Segoine。品牌無性別可言，人有；
@@ -637,9 +637,10 @@
   （sentence-transformers/all-mpnet-base-v2, revision
   e8c3b32e）對 `runs/02-cluster/source-keywords.txt` 的
   5,999 個關鍵字重新計算。組內一致性定義為組內成員兩兩
-  餘弦相似度之平均。k=50 直接取自私人留存的分群結果；
-  k=30 以同參數重跑（確定性演算法），重算所得最大組恰為
-  491 詞，與當時粗算紀錄吻合，佐證重算與原實驗一致。數表：
+  餘弦相似度之平均。k=50 直接取自留存的分群結果
+  （`excludes/k50/02-cluster/groups.csv`）；k=30 以同參數
+  重跑（確定性演算法），重算所得最大組恰為 491 詞，與
+  當時粗算紀錄吻合，佐證重算與原實驗一致。數表：
 
   | | k=30 | k=50 | k=100 |
   |---|---|---|---|
@@ -702,8 +703,8 @@
   力量語意即入選,women-power 群 11 碼,並產詞彙表外
   幻覺碼一筆),claude-fable-5 讀為詞彙化概念(要求女性
   標記,women-power 群 2 碼),與草稿盲選及深度閱讀輔助
-  判讀同讀法;sonnet 對照執行歸檔另行私人備份,不入
-  版本庫,支出留帳。claude-fable-5 不
+  判讀同讀法;sonnet 對照執行歸檔備份於
+  `excludes/experiments/`,支出留帳。claude-fable-5 不
   受理 temperature 與 thinking 參數(均不送出),無法釘
   temperature=0;執行間變異實測存在(run1/run2 於陽剛、
   脆弱邊緣碼分歧),由三票多數決吸收;詞彙表外輸出項
@@ -750,9 +751,9 @@
   編碼、票數),納入重建摘要與清空範圍,供群層次查詢;
   重建命令自此帶 `--groups results/groups.csv`。
 
-- **Fable 5 輔助判讀實驗總錄(非正式編碼;結果檔私人
-  留存、不入版本庫,本條為其版本庫內的程序錨點)**:
-  2026-08-08 起以 Claude Code subagent(模型
+- **Fable 5 輔助判讀實驗總錄(非正式編碼;結果檔於
+  gitignored 之 `excludes/`,本條為其版本庫內的程序
+  錨點)**:2026-08-08 起以 Claude Code subagent(模型
   Fable 5)進行七項深度閱讀實驗。共同程序:每首歌一個
   獨立會話、提示最少化且逐字統一、判讀者互不知情、不經
   三票制;定位為研究者的輔助判讀(初篩),不改動任何
@@ -782,7 +783,7 @@
   `male-mixed-wp-fe-feminist-reading.md` 與同名 .ods)。
   此系列即論文方法節「最後編碼的結果,再由研究者與 LLM
   (Claude Code)輔助判讀」之所指;結果檔含大量歌詞引文,
-  依著作權紀律私人留置,不入版本庫。
+  依著作權紀律留置 `excludes/`,不入版本庫。
 
 - **步驟 5:女性主義問題之質性深讀(設計定案)**:論文
   題目「挪用與污染」需要框架層的系統性證據;47 首
@@ -898,7 +899,7 @@
   performer_gender 手工修正)、四份 results 定案表、時程
   展延一至二日與剩餘撰寫工作。仍然有效的原則(先導不
   比較、提示只定格式、歌手背景防火牆、commit 判準、
-  版權規則)保留。
+  版權規則、positionality)保留。
 
 ## 2026-08-17
 

docs/methodology.md

@@ -1,12 +1,12 @@
 # 方法細節
 
 （全文方法節底稿。演算法在執行前寫定；任何修訂記入
-`decision-log.md`。）
+`decision-log.md`。定義檔全文見 `prompts/`，執行紀錄見
+`runs/`。）
 
 ## 自然編碼管線總覽
 
-五個步驟：步驟 1 自由標註（`claude-sonnet-4-6`，
-temperature=0、thinking 關閉，兩次執行進池）→ 步驟 2 詞彙表
+五個步驟：步驟 1 自由標註（兩次執行進池）→ 步驟 2 詞彙表
 建構（詞向量分群，確定性）→ 步驟 3 全量編碼（三次執行＋
 多數決）→ 步驟 4 語意編碼群（三次執行＋多數決）→ 步驟 5
 女性主義問題之質性深讀（三次閱讀＋逐首整合＋樣態統整）。
@@ -14,6 +14,13 @@ temperature=0、thinking 關閉，兩次執行進池）→ 步驟 2 詞彙表
 不接觸歌詞，步驟 2 亦不呼叫 LLM。設計原則見
 `research-plan.md`；本檔記載可重現的演算法細節。
 
+編號的所指為**研究程序的工序**，不是定義檔：步驟 1、
+步驟 3、步驟 4 與步驟 5 有定義檔（`prompts/`；步驟 5 依
+子工序有三份），步驟 2 沒有——它是單一確定性計算，由
+`cluster-keywords` 一個子命令完成。有無定義檔的區別即
+「該步是否為 LLM 判斷」，由 `prompts/` 是否存在同號檔案
+直接可見。
+
 ## 步驟 2 詞彙表建構——詞向量分群
 
 詞彙表由確定性程序產生，不經 LLM。完整分割（每個關鍵字
@@ -23,7 +30,8 @@ temperature=0、thinking 關閉，兩次執行進池）→ 步驟 2 詞彙表
 ### 進池
 
 兩次標註執行的全部關鍵字取聯集、逐字串精確去重、字典序
-排列。失敗與拒答的記錄跳過（其歌曲不貢獻關鍵字）。
+排列。失敗與拒答的記錄跳過（其歌曲不貢獻關鍵字）；解析
+時偵測重複鍵，違規即失敗。
 
 ### 分群
 
@@ -31,10 +39,14 @@ temperature=0、thinking 關閉，兩次執行進池）→ 步驟 2 詞彙表
   （釘定 revision），關鍵字的連字號先還原為空格再編碼，
   輸出 768 維向量並 L2 正規化。
 - **分群**：階層式聚合分群（Ward linkage），k=100。
-  向量既已正規化，歐氏距離與餘弦相似度單調對應。
+  向量既已正規化，歐氏距離與餘弦相似度單調對應；三種
+  linkage 實測比較，Ward 於各個 k 的組內一致性均最高
+  （average 與 complete 皆產生吞噬半數語料的巨大異質
+  組）。
 - **組數的取捨**：k 太小則壓縮比過高，樹上層被迫併入
-  不相干的詞，組雖大而無主題；k 太大則人工難以通覽。
-  定於 100，理由是實測顯示雜物櫃
+  不相干的詞，組雖大而無主題（k=30 最大組 491 詞、
+  組內一致性 0.41，成員橫跨籃球、海灘、外星人綁架）；
+  k 太大則人工難以通覽。定於 100，理由是實測顯示雜物櫃
   組於此始裂解為有主題的組，且編碼實測未見碼數過多的
   副作用——全量三次執行下 101 個碼全數用到；模型另行
   造出的碼共 13 筆，佔 44,149 筆標籤指派的 0.03%。
@@ -43,23 +55,39 @@ temperature=0、thinking 關閉，兩次執行進池）→ 步驟 2 詞彙表
   自己產出過的關鍵字，非任何人事後撰寫。已知限制：
   組越大越異質時，medoid 只是折衷詞，可能代表不了組內
   內容（實測 `mutual-individuality` 組內一致 0.70 而
-  編碼從未使用）；此類碼於結果中呈現為零使用。
-- **取捨紀錄**：詞彙表分群曾比較的替代法與棄用理由，見
-  `decision-log.md` 2026-08-05 條。
-- **產物**：分群輸出中，只有實際交給模型的碼表——組名
-  加上先驗主題詞——含研究者的介入；其餘皆為分群過程本身
-  的機械紀錄。
+  編碼從未使用）；此類碼於結果中呈現為零使用，據實
+  報告，不事後改名。
+- **取捨紀錄**：曾以 LLM 單發收斂（merge／cap 兩步）
+  實作本步，四種模型六次執行全部無法維持完整分割，
+  已棄用（詳見 `decision-log.md` 2026-08-05；棄用的
+  定義檔止於 git 歷史，見 `git log -- prompts/`）。
+- **產物**：五份，前綴分別標示來源與結果。
+  `source-keywords.txt`（進池後的關鍵字，一行一個）
+  記錄進來的是什麼；`result-keywords.txt`（組名，一行
+  一個）與 `groups.csv`（欄位 Group、Keyword，一列一個
+  成員）記錄算出來的分割；`keywords-to-merge.json`
+  （`{"keywords": [...]}`）是實際交給模型的碼，即組名
+  加上先驗主題詞——五份中只有這一份含研究者的介入。
+  `meta.json` 記錄執行本身：進池的兩份執行歸檔與其有效
+  筆數、嵌入模型與釘定 revision、分群參數與組數、外加
+  的先驗詞、關鍵字總數，以及產生數字的套件版本。凡命令
+  列上的選擇與環境事實皆在此，不記時間戳與輸入雜湊
+  ——前者使同環境重跑逐位元組可再生，後者只會重述 git
+  已保證的事。
 - **可重現性**：同一輸入、同一釘定模型、同一參數逐次
   重現。不同 CPU／BLAS 實作的浮點尾數差異可能使邊界
-  詞的歸屬翻動，屬已揭露的限制。
+  詞的歸屬翻動，屬已揭露的限制；論文所用碼表逐字
+  commit，引用單位為該份定案檔案。
 
 ### women-power 的注入
 
 定案詞彙表為 100 個分群組名再加上 `women-power` 一詞，
 共 101 個碼。`women-power` 是研究者任意決定的先驗主題（即本
 論文的主題本身），不由資料產生，屬揭露的儀器介入。該詞
-的加入於每次執行皆為明示、可稽核的介入，而非無聲內建於
-判斷邏輯；分群結果本身不含它，只有交給模型的碼表含它。
+於執行時以 `--extra-keyword` 明示加入，不寫死在程式裏
+——研究者的介入因此每次都出現在重現命令上，而非無聲
+發生；分群結果的兩份產物不含它，只有交給模型的碼表含
+它。
 
 注入而非另設篩選軌的理由：讓研究者的主題詞與模型自己
 收斂出的類別（分群已自行長出 `female-empowerment` 等組）
@@ -69,17 +97,24 @@ temperature=0、thinking 關閉，兩次執行進池）→ 步驟 2 詞彙表
 
 ## 步驟 3 編碼的三次執行與多數決
 
-- **模型**：`claude-sonnet-4-6`，temperature=0、thinking 關閉。
 - **三次執行**：同一份定義檔、同一份輸入檔，獨立執行
-  三次，三份歸檔並列，彼此無先後主從之別。
+  三次，三份歸檔並列（`runs/3a-code/run1`、`run2`、
+  `run3`），彼此無先後主從之別。
 - **多數決**：一首歌的一個標籤，三次執行中至少兩次標出
   即收入定案編碼。三票不平手，裁決規則因此無例外條款，
-  計票由確定性程序完成（見交接契約）。
-- **第三票取全量**：第三次執行同為全量——全部歌曲、
-  全部關鍵字——使三票在同一條件下取得。
+  計票由確定性子命令完成（見交接契約）。
+- **第三票取全量**：只對前兩次分歧的標籤補問第三票，
+  計票結果相同；仍採全量執行——全部歌曲、全部關鍵字
+  ——使三票在同一條件下取得。
 - **對邊緣標籤的作用**：兩次執行只分得出「兩次皆標」與
   「僅一次標」；三次執行還分得出 3-0 與 2-1，故「定案
   編碼中有多少比例僅以一票之差成立」成為可報告的量。
+  至於判定本身，兩次執行相左的標籤在何種協定下都由第三
+  個判斷定奪，票數不使不確定性消失：某標籤於單次執行被
+  標出的傾向若恰為一半，任何票數皆為擲幣。三票之效在
+  傾向偏離一半處——多數決將判定推向該傾向本身（單次
+  0.7 者為 0.78，0.9 者為 0.97），程序重跑的一致性因而
+  高於單次執行，唯獨恰半處無從改善。
 
 ## 步驟 4 語意編碼群
 
@@ -90,79 +125,103 @@ temperature=0、thinking 關閉，兩次執行進池）→ 步驟 2 詞彙表
   由 LLM 依編碼名的字面語意判斷。
 - **任務**：每筆輸入為一個群名加 101 個編碼的字母序
   清單，輸出為入選編碼的單層 JSON 陣列；定義檔
-  只定格式，不含任何群的語意定義。
-- **模型**：`claude-fable-5`；取樣變異由多數決吸收；
+  `prompts/4-group.md` 只定格式，不含任何群的語意定義。
+- **模型**：`claude-fable-5`（步驟 1、3 為
+  `claude-sonnet-4-6`）。該模型不受理 `temperature` 與
+  `thinking` 參數，兩者均不送出；取樣變異由多數決吸收。
   模型裁定的理由與對照實驗見決策日誌。
 - **三次執行**：同一份定義檔、同一份輸入檔，獨立執行
-  三次，歸檔並列。
+  三次，歸檔並列（`runs/4-group/run1`、`run2`、`run3`）。
 - **多數決**：一個（群，編碼）配對，三次執行中至少兩次
-  入選即屬該群；不在 101 碼詞彙表內的輸出項無效，逐筆
-  記錄後丟棄。計票由確定性計票程序完成，合法碼
-  清單之產法同步驟 3，結果為定案分群表。
+  入選即屬該群；不在 101 碼詞彙表內的輸出項無效，每筆
+  丟棄印於標準錯誤。計票由確定性子命令 `tally-groups`
+  完成：`tally-groups <執行歸檔 1> <執行歸檔 2> <執行歸檔
+  3> <合法碼清單> <輸出 CSV>`，合法碼清單之產法同步驟 3。
+  定案分群寫入 `results/groups.csv`，欄位 `Group`、
+  `Keyword`、`Votes`，列序先依群名、再依編碼，一律以
+  Unicode 碼位比較，換行為 CRLF。
+- **工作儲存**：`build-db --groups <定案分群 CSV>` 將定案
+  分群逐欄照存入 `groups` 資料表（群、編碼、票數），供
+  群層次查詢。
 
 ## 步驟 5 女性主義問題之質性深讀
 
-本步驟之 5a 至 5c 為**質性閱讀，非編碼**：輸出為自由
-文字的問題閱讀報告，無可逐項機械比對的單位，故不適用
-三票多數決與仲裁；
-三次獨立閱讀為分析者三角檢核，逐首整合為整合而非裁決，
-跨首統整之產出為草稿，終審與詮釋由研究者為之。論文引用
+本步驟之 5a 至 5c 為**質性閱讀,非編碼**:輸出為自由
+文字的問題閱讀報告,無可逐項機械比對的單位,故不適用
+三票多數決與仲裁;
+三次獨立閱讀為分析者三角檢核,逐首整合為整合而非裁決,
+跨首統整之產出為草稿,終審與詮釋由研究者為之。論文引用
 本步驟時不作次數宣稱。
 
-- **對象**：定案編碼含 `women-power` 或
+- **對象**:定案編碼含 `women-power` 或
   `female-empowerment` 的 145 首歌。
-- **5a 逐首閱讀**：每筆輸入為一首歌的完整歌詞逐字全文，
-  不含歌名與演唱者（盲讀）。同一份定義檔、同一份輸入檔，
-  獨立執行三次，歸檔並列。
-- **5b 逐首整合**：每筆輸入為該首歌的三份閱讀報告
-  （不含歌詞）；以問題機制為單位保守合併，標收斂註記
-  （（3/3）、（2/3）），主清單僅列兩讀以上提出者，單讀發現
-  以一行存目；定義檔，執行一次。
-- **5c 樣態統整**：單筆輸入為一批整合報告；歸納問題
-  **樣態**——問題呈現與運作的重複形態，非問題分類，
-  代表引句僅取自主清單。四種輸入範圍各執行
-  一次：全 145 首之基底統整，及依演唱聲音之性別切分
-  之三個發話脈絡統整——男聲（male）、女聲（female）、
-  混合（mixed）；基底看橫貫各
-  脈絡之樣態，分組看各權力脈絡下之樣態。genderfluid
-  與 non-binary 共 3 首不設群——樣本數不支持歸納——
-  僅入基底統整。同一輸入不重複
-  執行：自由歸納之產出無機械合併可言，其變異由 5a
-  三讀、5b 整合與草稿地位承接，四份草稿互為對照，由
-  研究者終審裁決。
-- **5d 樣態標註**：以（歌，樣態）對為可逐項機械比對之
-  單位，回歸「三次執行＋多數決」協定。對象為「有問題」
-  的歌——三讀中至多一個「無」（多數決精神；恰兩「無」
-  者其整合報告主清單必為空，與 5b 主清單規則自洽），
-  計 111 首（男聲 12、女聲 69、混合 29、genderfluid 1）。
-  樣態表為三份分組統整草稿原文：男聲 13 條（M1–M13）、
-  女聲 14 條（F1–F14）、混合 16 條（X1–X16）；基底 15 條
+- **5a 逐首閱讀**:每筆輸入為一首歌的完整歌詞逐字全文,
+  不含歌名與演唱者(盲讀);定義檔
+  `prompts/5a-read.md`。同一份定義檔、同一份輸入檔,
+  獨立執行三次,歸檔並列(`runs/5a-read/run1`、
+  `run2`、`run3`)。
+- **5b 逐首整合**:每筆輸入為該首歌的三份閱讀報告
+  (不含歌詞);以問題機制為單位保守合併,標收斂註記
+  ((3/3)、(2/3)),主清單僅列兩讀以上提出者,單讀發現
+  以一行存目;定義檔 `prompts/5b-consolidate.md`,
+  執行一次,歸檔 `runs/5b-consolidate/run1`。
+- **5c 樣態統整**:單筆輸入為一批整合報告;歸納問題
+  **樣態**——問題呈現與運作的重複形態,非問題分類,
+  代表引句僅取自主清單;定義檔
+  `prompts/5c-synthesize.md`。四種輸入範圍各執行
+  一次:全 145 首之基底統整(歸檔
+  `runs/5c-synthesize/run1`),及依 `performer_gender`
+  (演唱聲音之性別)切分之三個發話脈絡統整——男聲
+  (male,歸檔 `run2`)、女聲(female,歸檔 `run3`)、
+  混合(mixed,歸檔 `run4`);基底看橫貫各脈絡之樣態,
+  分組看各權力脈絡下之樣態。genderfluid 與 non-binary
+  共 3 首不設群——樣本數不支持歸納——僅入基底統整,
+  由研究者以個案閱讀。同一輸入不重複執行:自由歸納之
+  產出無機械合併可言,其變異由 5a 三讀、5b 整合與
+  草稿地位承接,四份草稿互為對照,由研究者終審裁決。
+- **5d 樣態標註**:以 (歌, 樣態) 對為可逐項機械比對之
+  單位,回歸「三次執行＋多數決」協定。對象為「有問題」
+  的歌——三讀中至多一個「無」(多數決精神;恰兩「無」
+  者其整合報告主清單必為空,與 5b 主清單規則自洽),
+  計 111 首(男聲 12、女聲 69、混合 29、genderfluid 1)。
+  樣態表為三份分組統整草稿原文:男聲 13 條(M1–M13)、
+  女聲 14 條(F1–F14)、混合 16 條(X1–X16);基底 15 條
   不入矩陣——全體歸納之一條樣態可能疊合不同方向的
-  權力關係（男對女、女對男），實為多個樣態共用一名。
-  檢驗範圍：男聲樣態不檢驗純女聲歌、女聲樣態不檢驗
-  純男聲歌（發話位置範疇錯置，檢查無意義）；混合樣態
-  檢驗全部（其男女聲部無系統化切分方式，無意義之標註
-  容忍之）；genderfluid 歌三套全查（無自身透鏡，發話
-  位置無法先驗決定），其歸屬引用維持個案地位。每筆
-  輸入為一首歌之整合報告（「僅單獨提及」行於組裝時
-  剝除，標註僅依主清單）與該首適用之樣態表；定義檔
-  獨立執行三次，（歌，樣態）對
+  權力關係(男對女、女對男),實為多個樣態共用一名。
+  檢驗範圍:男聲樣態不檢驗純女聲歌、女聲樣態不檢驗
+  純男聲歌(發話位置範疇錯置,檢查無意義);混合樣態
+  檢驗全部(其男女聲部無系統化切分方式,無意義之標註
+  容忍之);genderfluid 歌三套全查(無自身透鏡,發話
+  位置無法先驗決定),其歸屬引用維持個案地位。每筆
+  輸入為一首歌之整合報告(「僅單獨提及」行於組裝時
+  剝除,標註僅依主清單)與該首適用之樣態表;定義檔
+  `prompts/5d-annotate.md`,獨立執行三次
+  (`runs/5d-annotate/run1`~`run3`),(歌, 樣態) 對
   得兩票以上者定案。
-- **模型**：`claude-fable-5`。
-- **輸入組裝**：各步輸入檔由確定性程序自上游產物組裝。
-  5d 之樣態條目自分組統整草稿機械切出，代表引句不
-  隨附——引句出自特定歌曲，判該曲時形同預答。
+- **模型**:`claude-fable-5`(與先導深讀同儀器;
+  `temperature` 與 `thinking` 參數不適用,均不送出)。
+- **輸入組裝**:確定性行內腳本。5a:145 首依歌曲 ID
+  升序,`content` 為歌詞逐字全文;5b:每筆
+  `{"reports": [run1 輸出, run2 輸出, run3 輸出]}`;
+  5c:單筆以 `song-<ID>` 為鍵、整合報告為值之 JSON
+  物件,鍵集合為該次統整之範圍(基底為全 145 首,
+  分組依工作庫 `performer_gender` 切分);5d:每筆
+  `{"report": 主清單, "patterns": [{"id", "name",
+  "description"}]}`,樣態條目自分組統整草稿機械切出,
+  代表引句不隨附——引句出自特定歌曲,判該曲時形同
+  預答。各輸入檔之 SHA-256 記入該步 meta。
 
 ## 女性力量候選集
 
-候選集為定案編碼含 `women-power` 或 `female-empowerment`
-（步驟 4 女性力量群的兩個編碼）之歌曲聯集：wp 66 首、
-fe 144 首，聯集 145 首。
+候選集為兩類歌曲的合集：定案編碼含 `women-power` 者，
+以及定案編碼含研究者指認之女性力量概念域分群組者。
+指認於詞彙表定案後、黃金標準編碼開始前完成，指認清單
+與理由記入決策日誌。
 
 ## 軌跡對映（診斷用）
 
 沿收斂軌跡的機械對映：原始關鍵字 →（兩份標註執行歸檔的
-原始輸出）歌曲、原始關鍵字 →（分群）組，純機械查表，
+`output.jsonl`）歌曲、原始關鍵字 →（分群）組，純程式查表，
 決定性。以其結果與步驟 3 直接編碼的差異率作為「收斂軌跡
 扭曲」的診斷量，不作主結果。
 
@@ -171,36 +230,78 @@ fe 144 首，聯集 145 首。
 每一步的輸出如何變成下一步的輸入，皆為確定性程序，規則
 明定如下：
 
-- **歌詞輸入檔（步驟 1）**：由確定性的匯出程序自工作
-  儲存產出，一筆一首歌，依歌曲 ID 升序。步驟 3 的輸入
-  由同一匯出程序、同一工作儲存產出（見下），兩步的語料
-  同一性由此成立。
-- **步驟 1 → 2**：確定性的分群程序讀兩份執行歸檔的
-  執行紀錄，進池後直接分群，產出詞彙表與交給
-  模型的碼表。
-- **步驟 2 → 3 輸入檔**：同一匯出程序自工作儲存產出
-  步驟 3 的輸入，一筆一首歌，兼含歌詞與定案碼表，依
-  歌曲 ID 升序。碼表以參數傳入而非填進定義檔——定義
+- **歌詞輸入檔（步驟 1）**：`export-llm-input` 自工作
+  儲存產出，每筆 `{"id": "song-<ID>", "content": <歌詞>}`，
+  依歌曲 ID 升序。步驟 3 的輸入由同一子命令、同一工作
+  儲存產出（見下），兩步的語料同一性由此成立；各步
+  輸入檔的 SHA-256 記入該步 meta。
+- **步驟 1 → 2**：`cluster-keywords` 讀兩份執行歸檔的
+  `output.jsonl`（一律以換行字元 `\n` 切行——歌詞含
+  U+0085 等控制字元時，`str.splitlines()` 類的通用切行
+  會截斷 JSON 字串，實測踩中），進池後直接分群，一次
+  產出上列五份檔案。
+- **步驟 2 → 3 輸入檔**：`export-llm-input --extras
+  <定案碼表>` 自工作儲存產出步驟 3 的輸入，每筆
+  `{"id": "song-<ID>", "content": <字串>}`，`content` 為
+  固定鍵序序列化的 `{"lyrics": …, "keywords": [...]}`，
+  依歌曲 ID 升序。碼表以參數傳入而非填進定義檔——定義
   檔只規定任務形狀，換詞彙表、換演算法都不必改它。
-- **步驟 3 定案**：確定性的計票程序讀三份執行歸檔的
-  執行紀錄，依序套用更正表、驗證所有標籤皆在合法碼
+- **步驟 3 定案**：`tally-codings <執行歸檔 1> <執行歸檔
+  2> <執行歸檔 3> <輸出 CSV> --corrections <更正表>
+  --valid-keywords <合法碼清單>` 讀三份執行歸檔的
+  `output.jsonl`，依序套用更正表、驗證所有標籤皆在合法碼
   清單之內、計票。
-- **更正表**：研究者逐列校定的人工著作，逐筆更正標籤
-  或引述——以替代字串取代，或刪去該筆標籤指派或該句
-  引述。一筆引述更正套用於該首歌該次執行的所有出現處。
-  表中任一列若在資料中找不到對應者，即中止；校定的
-  判準記於 `decision-log.md`。
-- **合法碼清單**：自詞彙表產出：分群組名加上
-  `women-power`。
-- **定案編碼表**：歌名與演出者名銜逐首查工作儲存取得。
-  每個定案標籤隨附其在計票中各份執行所引的
-  歌詞行，供逐碼查核（三份執行彼此無先後主從之別）。
+- **更正表**：`data/manual/coding-corrections.csv`，研究者
+  逐列校定的人工著作，欄位 `Song ID`、`Run`、`Type`、
+  `To Be Replaced`、`Correct Term`。`Type` 為 `keyword`
+  或 `evidence`，分別更正標籤與引述；`Correct Term` 為
+  替代字串，或 `**REMOVE**` 表示刪去該筆標籤指派（`keyword`）
+  或該句引述（`evidence`）。一筆 `evidence` 更正套用於該
+  首歌該次執行的所有出現處。兩個文字欄以歌詞慣例「 / 」
+  表示換行（與載入後的執行紀錄同一表示法，逐字比對、不再
+  轉換），故一列一行，純文字工具可逐列處理。表中任一列若
+  在資料中找不到對應者，即中止；校定的判準記於
+  `decision-log.md`。
+- **合法碼清單**：純文字、一行一個碼，自詞彙表產出：
+  `{ cat runs/2-cluster/result-keywords.txt; echo
+  women-power; } | sort`。
+- **定案表**：`results/codings.csv`，欄位 `Song`、
+  `Artist Credit`、`Keyword`、`Quote`，一列一個標籤。歌名
+  與演出者名銜逐首查工作儲存取得，故本子命令須在
+  `build-db` 之後執行。`Quote` 為該標籤在計票中各份執行
+  所引的歌詞行：各份的引述串接後逐字去重，按 Unicode
+  碼位排序，以單一 `|` 相接（三份執行彼此無先後主從之
+  別，引述之序取決於引述本身）；引述內的換行於執行紀錄
+  載入時一次換成歌詞慣例「 / 」，此後更正表、定案表與
+  工作儲存全鏈路同一表示法，不再還原。「 / 」的無歧義性
+  是語料事實而非結構保證：全 883 首歌詞經窮舉查核不含
+  「 / 」；換語料須重查。列序依印出的前三欄依序排：
+  歌名、演出者名銜、
+  標籤，一律以 Unicode 碼位比較，換行為 CRLF（同專案
+  其他 CSV）。
+- **序列化通則**：所有中間檔為 UTF-8，欄序、鍵序與元素
+  序皆依上列規則明定，無時間戳、無隨機成分；JSON 解析
+  一律偵測重複鍵，違規即失敗。人讀為主的產物採純文字或
+  CSV（CSV 依 RFC 4180，標題列字首大寫），機器交接檔採
+  JSON。給定相同的 LLM 執行輸出，全部交接產物逐位元組
+  可再生。
 
 ## 執行與稽核
 
-- LLM 步驟以批次執行程序執行，一份定義檔配一份
-  輸入檔；一步的 N 次執行為 N 次各自獨立的呼叫，各自
-  歸檔自我完備。
+- LLM 步驟以 `run-llm <定義檔> <輸入檔> <歸檔目錄>`
+  執行；一步的 N 次執行＝重現命令清單上的 N 行命令，
+  各自歸檔（`runs/<步驟>/run1`、`run2`，三票制步驟另有
+  `run3`）。
+- 確定性步驟（進池、分群、計票、對映）為子命令，其
+  輸入輸出檔同隨 `runs/` 歸檔；因無執行變異，歸檔目錄
+  下不分 `run<N>` 層。
 - Batch API 的每筆請求自含全部脈絡且互不可見（平台
   契約），歌與歌之間的獨立性由此成立；各次執行的獨立
   性由「一次呼叫、一個批次、一份歸檔」的執行結構自明。
+- 每次 `run-llm` 執行的 token 用量與費用記入
+  `run-costs.md`，被取代的執行一併保留供總支出核算。
+
+## 映射分析方法
+
+（依 2026-07-30 決策，於看到結果前寫定；待黃金標準
+編碼展開前補入。）

docs/output-validation.md

@@ -1,7 +1,7 @@
 # LLM 輸出的契約查核
 
 （2026-08-06 量測。對象為步驟 3 的三份執行歸檔
-`data/runs/3a-code/run1`–`run3`，共 883 首歌、44,149 筆標籤
+`runs/3a-code/run1`–`run3`，共 883 首歌、44,149 筆標籤
 指派、44,146 句引述。歌詞以模型實際看到的那一份為準，即
 `tools/instance/llm-input-code.jsonl`。）
 
@@ -46,8 +46,9 @@ song-750 run3: -use=[]  -abuse=["I got a thing for the hard
                                  liquor on ice"]
 ```
 
-song-750 的 run1 與 run2 則整筆使用錯拼的鍵並附上引述，
-故該首的三票分裂於兩種拼寫之間。
+模型寫錯後綴、已輸出的 token 收不回，遂以空陣列收束該鍵，
+再於正確的鍵補上引述。song-750 的 run1 與 run2 則整筆使用
+錯拼的鍵並附上引述，故該首的三票分裂於兩種拼寫之間。
 
 ## 引述的存在
 

docs/pilot-study.md

@@ -2,14 +2,15 @@
 
 （2026-08-17 認清並記錄。本檔記述正式研究之前的先導研究:
 它做了什麼、研究者檢視到哪一層、哪些成果被沿用、哪些被
-棄用,以及它如何促成正式研究的設計。）
+棄用,以及它如何促成正式研究的設計。散見於
+`decision-log.md` 的相關條目在文中逐一指出。）
 
 ## 一、先導研究是什麼
 
 正式研究之前,研究者曾以 Claude Code 對 Billboard Year-End
 Hot 100(2018–2025、684 首)的歌詞做過一輪探索性分析,檢視
 「女性力量」語彙的使用狀況,並附帶分析 pussy 一詞作為女性
-代稱的修辭。2026 年 4 月投出的研討會摘要即根據該輪分析撰寫。
+代稱的修辭。2026 年 8 月投出的研討會摘要即根據該輪分析撰寫。
 
 ## 二、它實際的執行方式
 
@@ -34,24 +35,27 @@ frame-aware 提示修正實驗,均由當時協作的 Claude Code 設計並
 ## 三、被沿用的成果
 
 - **歌詞捕捉檔**:先導研究蒐集的 lyrics.json(684 首,
-  2018–2025)以私人腳本(不入版本庫)匯入歌詞快取,只取
+  2018–2025)以 `excludes/` 的私人腳本匯入歌詞快取,只取
   識別欄位與歌詞本文,先導的分析欄位一概不匯入;出處記於
-  `data/captures/lyrics-provenance.csv`
-  (見 `decision-log.md` 2026-07-31、08-02 條)。
+  `data/captures/lyrics-provenance.csv`,method 欄標
+  `pilot-import`(見 `decision-log.md` 2026-07-31、08-02 條)。
 - **假說方向**:女性力量語彙的挪用與污染,成為正式研究的
   研究問題。
 - **粒度選擇**:正式研究鎖定 thematic keywords 這一粒度,
   係繼承先導研究三種粒度的比較結果(keywords 過碎、themes
-  過早抽象)。
+  過早抽象),且於執行前鎖定以防事後擇優。
 - **`women-power` 一詞的來歷**:考據先導研究的 local agent
   存檔可知,其第一步指令含數十個範例 thematic keywords,
   其中即有 women-power——為當時協作的 Claude Code 依研究者
   長期表達的關注主動加入(研究者端播種,非明示指定);先導
   的標籤 `women-power-and-empowerment` 則是第三步強制合併
-  兩個關鍵字的管線人工產物(見 `decision-log.md` 2026-08-04
-  條)。
+  兩個關鍵字的管線人工產物。正式研究的探針因此指向被播種的
+  本詞 `women-power`,不用合併假影(見 `decision-log.md`
+  2026-08-04 條)。**附帶認清:先導第一步並非零語意提示,
+  此即正式研究「提示詞只定格式、不定語意」設計所矯正者。**
 - **簿記容量的教訓**:先導研究九百餘詞可以在單一回應內完成
-  分組;此法未沿用,詞彙表改由確定性程序產生(見
+  分組,正式研究的 5,999 個關鍵字則四種模型六次執行全部未
+  通過完整分割驗證,遂改用詞向量嵌入＋確定性分群(見
   `decision-log.md` 2026-08-06 條)。
 
 ## 四、被棄用的成果
@@ -59,20 +63,35 @@ frame-aware 提示修正實驗,均由當時協作的 Claude Code 設計並
 以下先導研究的產物未進入正式研究,論文亦未引用:
 
 - **genuine／peripheral／fake 三分類與「44% 假女性力量」**:
-  構念與分母均未經稽核回溯,未沿用。
-- **五種「假女性力量」類型(A–E)**:未沿用。
-- **pussy 一詞的修辭分類**:未沿用。
+  構念與分母皆與正式研究不同(正式研究為 145 首女性力量群
+  歌曲中 111 首有性別問題),兩者不可對讀。
+- **五種「假女性力量」類型(A–E)**:正式研究改由儀器分三個
+  發話脈絡各自歸納,得 43 條問題樣態(`results/patterns.csv`)。
+- **pussy 一詞的修辭分類**:正式研究範圍收斂至語彙的挪用與
+  污染,未納入。
 - **frame-aware(框架感知)提示修正法**:先導研究以框架判準
-  寫進提示以提高準確率;未沿用。
-- **三個獨立 LLM subagent＋人工仲裁的流程**:未沿用,原因見
-  `decision-log.md` 2026-07-30 條。
+  寫進提示以提高準確率;正式研究刻意不定義編碼,因為研究
+  對象正是 LLM 未受引導的自然編碼——把框架寫進提示,即無法
+  再以其輸出為批判對象。兩者的設計方向相反,故未沿用。
+- **三個獨立 LLM subagent＋人工仲裁的流程**:正式研究改以
+  Anthropic API 逐首獨立呼叫,原因是實測證實 subagent 會繼承
+  CLAUDE.md 與環境資訊,context 無法僅憑定義檔重現(見
+  `decision-log.md` 2026-07-30 條)。
 
-## 五、它促成了可稽核的設計
+## 五、它如何促成正式研究的設計
 
 先導研究的根本限制不在結論對錯,而在**不可稽核**:沒有定義檔
 快照、沒有原始輸出歸檔、沒有參數紀錄,因此任何一個數字都無法
-回溯到產生它的那一次執行。正式研究的可稽核設計,正是針對這一點
-而立。
+回溯到產生它的那一次執行。正式研究的幾項設計正是針對這一點:
+
+- 所有 LLM 步驟改以 API script 執行,每次執行自我完備歸檔於
+  `runs/`(定義檔快照、原始輸出、model ID 與參數、批次 ID、
+  token 用量);
+- 可逐項機械比對的判斷採三次執行＋多數決,並量測其穩定性
+  (見 `reliability.md`);
+- 定義檔只規定任務形狀,不給主題定義、判準或範例;
+- 每一筆編碼必附歌詞引述,供逐筆查核;
+- 輸出的契約遵從另行查核(見 `output-validation.md`)。
 
 換言之,正式研究對 LLM 輸出所採取的「不信任、須查核」立場,
 其第一個案例就是先導研究本身。
@@ -83,3 +102,6 @@ frame-aware 提示修正實驗,均由當時協作的 Claude Code 設計並
   的前身),樹中不另存副本——摘要只是產物,不足以記述過程,
   故另立本檔。
 - 先導研究的歌詞捕捉檔沿用事實:`data/captures/lyrics-provenance.csv`。
+- 相關決策條目:`decision-log.md` 2026-07-30(不與先導比較、
+  不用 subagent)、07-31 與 08-02(歌詞沿用與私人匯入腳本)、
+  08-04(women-power 來歷考據)、08-06(詞彙表改用詞向量分群)。

docs/project-structure.md

@@ -0,0 +1,139 @@
+# 專案目錄結構
+
+（2026-07-30 討論定案；2026-07-31 更新為 tools/ 子專案與
+SQLite 工作儲存架構；2026-08-17 依完成後的現況更新）
+
+```
+pop-fem-audit/
+├── README.md                  # 專案說明
+├── .gitignore                 # captures/lyrics/、.env、scratch
+├── data/                      # 依生命週期分層（文字格式）
+│   ├── source/                # 源頭：手放後不動
+│   │   └── yearend_hot100_2016_2025.csv   # 原始榜單
+│   ├── captures/              # 外部捕捉：只由 fetch 命令與
+│   │   │                      #   私人匯入腳本寫入
+│   │   ├── artists-wikidata.csv           # Wikidata 快照
+│   │   ├── lyrics-provenance.csv          # 歌詞出處
+│   │   └── 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   # 1-tag.md、3a-code.md、
+│                              #   4-group.md、5a-read.md、
+│                              #   5b-consolidate.md、
+│                              #   5c-synthesize.md、
+│                              #   5d-annotate.md
+│                              #   （次步以字母標示，與論文正文
+│                              #   的步驟編號一致；步內僅一個
+│                              #   執行時省略次步）
+│                              #   不帶版本號，版本即 git 歷史
+│                              #   （編號的所指是工序：確定性
+│                              #   的步驟 2 無定義檔仍佔一號）
+├── tools/                     # 輔助工具子專案（src-layout）
+│   ├── pyproject.toml         #   發行名 pop-fem-audit-tools；
+│   │                          #   pip install -e tools/ 安裝
+│   ├── README.rst  LICENSE  MANIFEST.in  .env.example  .gitignore
+│   ├── docs/                  # Sphinx API 文件
+│   ├── instance/              # SQLite 工作儲存（generated、
+│   │                          #   gitignored；含歌詞全文）
+│   ├── src/pop_fem_audit_tools/
+│   │   ├── __main__.py        # 套件 CLI 進入點（分派子命令）
+│   │   ├── commands/          # CLI 子命令模組（登記於 __init__）
+│   │   │   ├── build_db.py    # build the SQLite working store
+│   │   │   │                  #   from the inputs
+│   │   │   ├── export_llm_input.py # export the LLM input JSONL
+│   │   │   │                       #   (lyrics only) from the
+│   │   │   │                       #   working store
+│   │   │   ├── fetch_artists.py # fetch artist metadata from
+│   │   │   │                    #   Wikidata into the snapshot CSV
+│   │   │   ├── fetch_lyrics.py # fetch missing lyrics from the
+│   │   │   │                   #   public APIs into the lyrics dir
+│   │   │   ├── 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 5d by majority
+│   │   │   └── run_llm.py     # API 執行器：一份定義檔＋一份輸入
+│   │   │                      #   →歸檔至指定目錄（Batch API）；
+│   │   │                      #   多次執行的計票由獨立子命令承擔
+│   │   ├── config.py          # pydantic-settings 設定（.env）
+│   │   ├── database.py        # SQLAlchemy engine / session / Base
+│   │   ├── models.py          # SQLAlchemy ORM 資料模型
+│   │   └── utils.py           # 共用工具（format_duration）
+│   └── tests/                 # 單元測試（unittest）
+├── runs/                      # 現行執行的完整稽核紀錄（進 git；
+│   │                          #   重跑同一 run 須明示 --replace）
+│   ├── <步驟名>/              #   一步一個目錄（1-tag、3a-code、
+│   │                          #   4-group、5a-read、
+│   │                          #   5b-consolidate、
+│   │                          #   5c-synthesize、5d-annotate）
+│   │   └── run<N>/            #   LLM 步驟：每個 run 一份自我
+│   │       ├── prompt.md      #   完備歸檔（定義檔快照）
+│   │       ├── output.jsonl   #   該次執行原始輸出
+│   │       └── meta.json      #   model ID、temperature、時間戳、
+│   │                          #   batch ID、token 用量
+│   └── 2-cluster/            # 確定性步驟：無執行變異，
+│                              #   不分 run<N> 層
+├── results/                   # 論文引用的定案表 CSV（計票子命令
+│   │                          #   產出；「可再生仍 commit」的例外）
+│   ├── codings.csv            # 步驟 3 定案編碼
+│   ├── groups.csv             # 步驟 4 定案編碼群
+│   ├── patterns.csv           # 步驟 5c 定案樣態表
+│   ├── annotations.csv        # 步驟 5d 定案歌×樣態
+│   └── pattern-matrix.csv     # 前四者的人讀寬表
+├── docs/
+│   ├── conventions.md         # 常設工作規範（原 CLAUDE.md；
+│   │                          #   移入 docs/ 使 subagent 不繼承）
+│   ├── research-plan.md       # 研究步驟規劃（本檔之姊妹篇）
+│   ├── project-structure.md   # 本檔
+│   ├── output-validation.md   # LLM 輸出的契約查核紀錄
+│   ├── decision-log.md        # 決策日誌：每次改定義檔的原因
+│   ├── run-costs.md           # 每次執行的 token 用量與費用
+│   ├── reliability.md         # 信度：量測方式與結果
+│   ├── pilot-study.md         # 先導研究的來歷與地位
+│   └── methodology.md         # 方法細節（全文方法節底稿；
+│                              #   映射分析方法須在看結果前寫定）
+└── paper/
+    ├── abstract.md            # 摘要
+    └── 流行音樂中「女性力量」….odt  # 全文
+```
+
+## 設計理由
+
+- **`runs/` 自我完備**：每個執行目錄含定義檔快照 + 原始輸出 +
+  meta，讀者不需 git 考古即可稽核任一筆結果。
+- **`runs/`（原始稽核資料）與 `results/`（最終表）分離**：
+  論文只引 `results/`，其來源可回溯至 `runs/`。
+- **`prompts/` 檔名不帶版本號**：版本即 git 歷史，失敗的
+  版本不保留；論文引用的單位是 `runs/` 內隨執行保存的定義檔
+  快照（每個執行目錄自我完備），不需檔名可指的版本名。
+- **工作儲存的資料表**：`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」的例外有二：
+  `results/` 報表（引用穩定性、審稿人零門檻、撰稿期可 diff）
+  與 `data/derived/` 人讀報表（與工作儲存同一動作產出，稽核
+  鏈無中間空缺）。詳見 `research-plan.md`「資料儲存與模型」。
+- **設定**經 pydantic-settings 統一：`.env`（gitignored，範本
+  `tools/.env.example`）供應 `SQLALCHEMY_DATABASE_URL` 與
+  `ANTHROPIC_API_KEY`，絕不寫入 repo。
+- **不設 CLAUDE.md**：實測證實 Claude Code subagent 會繼承專案
+  CLAUDE.md 全文（原本因此只放極簡工作規則），2026-08-18 進一步
+  將其移為 `docs/conventions.md`——docs/ 不會自動注入 subagent
+  的 context，盲判型 agent 便不會看到工作規範；主會話動手前
+  自行閱讀之。

docs/reliability.md

@@ -1,7 +1,8 @@
 # 信度:量測方式與結果
 
-（2026-08-16 量測。對象為步驟 3a 與步驟 5d 各三次執行的
-原始輸出;數字由原始輸出直接計算。）
+（2026-08-16 量測。對象為步驟 3a 的三份執行歸檔
+`runs/3a-code/run1`–`run3`,與步驟 5d 的三份執行歸檔
+`runs/5d-annotate/run1`–`run3`;數字由原始輸出直接計算。）
 
 ## 一、本研究的信度是什麼
 
@@ -33,7 +34,11 @@ Krippendorff 依產生資料的設計,把信度分成三型
 **精密度(precision)**,而**準確度(accuracy)** 未經量測。
 若儀器是確定性的,重複性無須量測;但 LLM 不是——同樣的提示、
 同樣的輸入,三次會給出不同結果,因此重複性是必須報告的儀器
-規格。
+規格,而非慣例儀式。
+
+這一點與 LLM 標註的近期文獻一致:同一模型重複取樣量測的是
+自我一致性(self-consistency),而重複執行後取多數決可提升
+標註穩定度(如 Prompt Stability Scoring,arXiv:2407.02039)。
 
 ## 二、三個常用指標
 
@@ -101,7 +106,7 @@ Jaccard(只看「有標到」的格子,忽略雙方都沒標的)約 0.89–0.91,
 比百分比一致率低而更誠實——因為 82% 的格子是雙方都判「無」,
 那些一致並不費力。
 
-## 四、隨機性的規模
+## 四、隨機性的規模與三票制的作用
 
 信度數字回答的實際問題是:**這台儀器的隨機性,大到會不會
 改變結論?**
@@ -111,6 +116,12 @@ Jaccard(只看「有標到」的格子,忽略雙方都沒標的)約 0.89–0.91,
 一半會成為誤收、另一半會成為漏收。三票多數決把兩票以上者
 收入、一票者剔除,處理的正是這一批。
 
+三票制並非消除隨機性,而是**把隨機性往案例原本的傾向推**。
+設某個邊緣案例的符合程度為 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,同一組結論就不能採信——信度

docs/research-plan.md

@@ -11,33 +11,81 @@
   **不與先導研究做比較**；
   全文數字一律以正式研究結果為準。先導研究僅作為假說的
   內部來源，記於決策日誌，不進入論文敘事。
-- **執行原則**：主會話只做討論，分析一律由確定性程序
-  執行。可逐項機械比對的判斷（步驟 3 編碼、步驟 4 選群、
-  步驟 5d 樣態標註）採「三次獨立執行＋多數決」定案，
-  自由生成（步驟 1 自由標註）採兩次執行全數進池，步驟
-  5a 至 5c 定為質性閱讀協定；程序細節見 `methodology.md`，
-  工作規範見 `conventions.md`。
+- **執行原則**：主會話只做討論；所有分析由 deterministic
+  script 執行。LLM 步驟以 Python script 呼叫 Anthropic
+  Messages API（個人 Console 帳號、Batch API 五折），定義
+  檔逐字作為 system prompt。可逐項機械比對的判斷（步驟 3
+  編碼、步驟 4 選群、步驟 5d 樣態標註）採「同一定義檔
+  獨立執行三次＋多數決」，計票由確定性子命令完成。自由
+  生成（步驟 1 自由標註）兩次執行全數進池。步驟 5a 至
+  5c 為質性閱讀協定：三次獨立閱讀為分析者三角檢核、
+  逐首整合、樣態統整產出草稿，不適用投票與仲裁。詞彙表
+  不經 LLM，由詞向量嵌入＋確定性分群產生。驗證結果不符
+  預期則修訂定義檔重跑該循環，絕不手改結果。
 - **提示詞只定格式、不定語意**：研究對象是通用 LLM 以其
   網路語料知識背景所做的自然編碼與閱讀，其結果本身是
   批判對象。定義檔只規定任務形狀（輸入、數量範圍、輸出
   格式），不給任何主題的定義、判準或範例。LLM 判斷一律
   要求逐項引述歌詞原句，作為檢視偏差的依據。
-- **模型**：步驟 1、3 用 `claude-sonnet-4-6`；步驟 4、5
-  用 `claude-fable-5`——實測發現 sonnet 將「Women Power」
-  拆讀為 women＋power 的組合語意，fable-5 讀為詞彙化
-  概念，語意層任務因此換用 fable-5（經過見決策日誌）。
+- **模型**：步驟 1、3 用 `claude-sonnet-4-6`（temperature=0、
+  thinking 關閉）；步驟 4、5 用 `claude-fable-5`（兩參數
+  不適用，均不送出；取樣變異由多數決或整合吸收）——實測
+  發現 sonnet 將「Women Power」拆讀為 women＋power 的組合
+  語意，fable-5 讀為詞彙化概念，語意層任務因此換用
+  fable-5（經過見決策日誌）。
 - **信度與效度**：三次獨立執行量測穩定性（intra-rater
   reliability，可報告兩兩一致率）；封閉母體全量檢查取代
   抽樣防衛。可重現性定義為「程序透明＋可稽核」：公開定義
   檔、記錄 model ID 與執行時間、保存全部原始輸出。
 
-## 範圍性定案
+## 資料儲存與模型
 
+- **Commit 判準**：凡能由「committed 的輸入＋committed 的
+  程式」決定性再生者，不 commit；凡不能者——源頭資料、
+  外部世界的捕捉（Wikidata 快照、LLM 原始輸出）、人工
+  著作——一律以文字格式 commit。格式跟著層次走。
+- **分層**：
+  - 源頭：原始榜單 CSV（進 git）。
+  - 捕捉：Wikidata 快照 CSV、`runs/` JSONL（皆進 git）；
+    歌詞 `.txt` 快取（版權因素 gitignored，為已知的稽核
+    缺口）。
+  - 人工：`data/manual/`（僅研究者親手寫入：編碼修正、
+    演唱者性別修正）。
+  - 工作儲存：SQLite 單檔（`tools/instance/`，generated、
+    不進 git），SQLAlchemy 2.0 typed ORM 定義 schema，
+    設定經 pydantic-settings（`.env` 供應
+    `SQLALCHEMY_DATABASE_URL` 與 `ANTHROPIC_API_KEY`）。
+    歌詞全文入 DB（不進 git 故無版權疑慮）。
+  - 衍生：`build-db` 建置工作儲存的同一動作產出人讀報表
+    （`data/derived/`，進 git），與 SQLite 同交易語意。
+  - 報表：論文引用的定案表進 `results/`——
+    `codings.csv`（步驟 3 定案編碼）、`groups.csv`
+    （步驟 4 定案編碼群）、`patterns.csv`（步驟 5c 定案
+    樣態表）、`annotations.csv`（步驟 5d 定案歌×樣態
+    矩陣）。衍生與報表為「可再生仍 commit」的例外，理由：
+    引用穩定性、審稿人零門檻、撰稿期數字變動可 diff。
+- **資料模型**：`songs`（含 lyrics、`performer_gender`——
+  演唱聲音之性別，由署名藝人之 Wikidata 性別推導後套用
+  `data/manual/performer-gender-corrections.csv` 手工修正）、
+  `chart_entries`、`artists`、`song_artists`、`codings`、
+  `groups`（語意編碼群）、`patterns`（深讀樣態）、
+  `annotations`（歌×樣態定案矩陣）。領域不變量（恰 1000
+  筆榜單、每歌至少一 primary 歌手等）檢查內建於
+  `build-db`，違規即建置失敗。
 - **歌手背景防火牆**：歌手背景資料只進人工解讀階段，
   **絕不進 LLM 輸入**——LLM 任務的 user message 維持
   歌詞-only 或管線中間產物-only，避免光環偏誤。
-- **Pilot 歌詞沿用**：先導歌詞沿用之來歷與細節詳見該檔
-  （`pilot-study.md`）。
+- **Pilot 歌詞沿用（私人匯入，不進發布管線）**：先導研究
+  捕捉檔（lyrics.json，684 首，2018–2025）以 `excludes/`
+  的私人腳本匯入歌詞快取；讀者的重現路徑純粹是
+  `fetch-lyrics`；沿用之事實記於
+  `data/captures/lyrics-provenance.csv`（進 git）。
+- **子命令**（`pop-fem-audit-tools <cmd>`）：`build-db`
+  （`--codings`、`--groups`、`--gender-corrections`、
+  `--patterns`、`--annotations`）、`cluster-keywords`、
+  `export-llm-input`、`fetch-artists`、`fetch-lyrics`、
+  `run-llm`（`--model` 於模型登錄表中擇一）、
+  `tally-codings`、`tally-groups`、`tally-annotations`。
 
 ## 分析管線（五步驟，全部完成）
 
@@ -48,19 +96,27 @@
    階層式聚合分群 k=100，組名取 medoid；再併入研究者先驗
    主題詞 `women-power`（據實揭露的儀器介入），共 101 碼。
 3. **編碼（步驟 3）**：以定稿詞彙表對全 883 首編碼，逐
-   標籤附引述，×3＋多數決，產出定案編碼表。「女性力量」
-   候選集（wp 66 首、fe 144 首、wp∪fe 145 首）由此浮現。
+   標籤附引述，×3＋多數決（`tally-codings`），定案
+   `results/codings.csv`。「女性力量」候選集（wp 66 首、
+   fe 144 首、wp∪fe 145 首）由此浮現。
 4. **語意編碼群（步驟 4）**：LLM 依編碼字面語意將 101 碼
    選入研究者指定的四個主題群（women-power／misogyny／
-   masculine／vulnerable），×3＋多數決，產出定案分群表；
-   wp/fe 與各編碼、各編碼群之關聯統計（BH-FDR 校正）入
-   論文。
+   masculine／vulnerable），×3＋多數決（`tally-groups`），
+   定案 `results/groups.csv`；wp/fe 與各編碼、各編碼群之
+   關聯統計（BH-FDR 校正）入論文。
 5. **女性主義問題之質性深讀（步驟 5）**：對 wp∪fe 145 首
    ——5a 逐首盲讀（僅歌詞全文）×3；5b 逐首整合（收斂
    註記、主清單限兩讀以上）；5c 樣態統整（全體基底＋
    男聲／女聲／混合三個發話脈絡分組）；5d 樣態標註——
-   以分組樣態表逐首標註「有問題」的 111 首，×3＋多數決，
-   產出定案樣態表與歌×樣態定案矩陣。
+   以分組樣態表逐首標註「有問題」的 111 首，×3＋多數決
+   （`tally-annotations`），定案 `results/patterns.csv` 與
+   `results/annotations.csv`。
+
+定義檔命名 `prompts/<步><次步>-<task>.md`，次步以字母標示
+（與論文正文的步驟編號一致）；編號的所指是工序而非定義檔
+（確定性的第 2 步無定義檔仍佔編號）；檔名
+不帶版本號——版本即 git 歷史；每次執行的定義檔快照隨
+`runs/` 自我完備，token 費用逐筆記於 `docs/run-costs.md`。
 
 ## 時程與剩餘工作
 
@@ -69,3 +125,12 @@
   污染」結論（步驟 5 素材已備）、信度說明、fe 與新自由
   主義敘事之詮釋標註。
 
+## 其他已定案事項
+
+- 歌詞受版權保護：完整歌詞不進 git
+  （`data/captures/lyrics/` gitignored），論文與 repo 只留
+  分析所引摘錄。
+- 工程支援（寫 script、style check、審稿）用公司訂閱的
+  Claude Code；進論文的分析 token 由個人 API 帳號支付。
+- Positionality statement 寫入論文（53 歲、長年婦運者、
+  資深工程師、離開學術圈多年、因整理榜單而起）。

docs/run-costs.md

@@ -48,7 +48,7 @@ LLM 合併嘗試（`01-02-01-merge`，詞彙表改採詞向量分群時
 | 2026-08-06 | 已廢棄 | — | claude-sonnet-4-6 | msgbatch_01N7bDbXRSfAVUzzaj2thKeR | 4 分 20 秒 | 781,037 | 39,315 | $1.47 | 現行（644 首全數有效，零攔阻；保留 1,481／送裁 1,699） | 03-02-arbitration |
 | 2026-08-06 | 3a-code | run3 | claude-sonnet-4-6 | msgbatch_01KnkCaGETnFJrPddrxZTYHA | 6 分 26 秒 | 1,625,458 | 363,840 | $5.17 | 現行（101 碼；883 首全數有效，零攔阻） | 03-code |
 | 2026-08-14 | 4-group | run1 | claude-sonnet-4-6 | msgbatch_01UPNedog6feQzJ9WVfSAxBD | 1 分 1 秒 | 3,129 | 470 | $0.01 | 已取代（僅 3 群；改納 women-power 群後重跑） | 04-group |
-| 2026-08-14 | 4-group | run1 | claude-sonnet-4-6 | msgbatch_01KntJgxdicStaMjNL12P3zi | 1 分 25 秒 | 4,170 | 558 | $0.01 | 已取代（改以 claude-fable-5 執行；vulnerable 輸出含詞彙表外碼 1 筆；歸檔另行私人備份，不入版本庫） | 04-group |
+| 2026-08-14 | 4-group | run1 | claude-sonnet-4-6 | msgbatch_01KntJgxdicStaMjNL12P3zi | 1 分 25 秒 | 4,170 | 558 | $0.01 | 已取代（改以 claude-fable-5 執行；vulnerable 輸出含詞彙表外碼 1 筆；歸檔備份於 excludes/experiments/） | 04-group |
 | 2026-08-14 | 4-group | run1 | claude-fable-5 | msgbatch_01Mr6goBb2Efa4YrqCprbP4U | 55 秒 | 5,553 | 2,049 | $0.08 | 現行（4 群；零違規碼；temperature 與 thinking 參數不適用於本模型，未送出） | 04-group |
 | 2026-08-14 | 4-group | run2 | claude-fable-5 | msgbatch_01C17xW3YBefThTYZ83g7KkL | 1 分 21 秒 | 5,553 | 1,891 | $0.08 | 現行（4 群；零違規碼） | 04-group |
 | 2026-08-14 | 4-group | run3 | claude-fable-5 | msgbatch_01DveEMYyjCAYe6wxpcCD87V | 2 分 9 秒 | 5,553 | 1,975 | $0.08 | 現行（4 群；零違規碼） | 04-group |

tools/.env.example

@@ -3,7 +3,7 @@
 # Authors:
 #   imacat@mail.imacat.idv.tw (imacat), 2026/7/31
 
-# The SQLAlchemy database URI.
-SQLALCHEMY_DATABASE_URI="postgresql://user:password@host/db"
+# The SQLAlchemy database URL.
+SQLALCHEMY_DATABASE_URL="postgresql://user:password@host/db"
 # The Anthropic API key
 ANTHROPIC_API_KEY=sk-ant-...

tools/docs/source/changelog.rst

@@ -1,10 +0,0 @@
-Change Log
-==========
-
-
-version 1.0.0
--------------
-
-Released 2026/8/19
-
-Initial release.

tools/docs/source/index.rst

@@ -13,8 +13,6 @@ This is a collection of supporting tools for the conference paper "流行音樂
    :maxdepth: 2
    :caption: Contents:
 
-   changelog
-
 
 Indices and tables
 ==================

tools/src/pop_fem_audit_tools/__init__.py

@@ -6,5 +6,5 @@
 """Tools for A Feminist Audit of Pop Music."""
 
 
-VERSION: str = "1.0.0"
+VERSION: str = "0.0.0"
 """The package version."""

tools/src/pop_fem_audit_tools/config.py

@@ -14,12 +14,12 @@ class Settings(BaseSettings):
     """The application name."""
     admin_email: str = "imacat@mail.imacat.idv.tw"
     """The administrator email address."""
-    SQLALCHEMY_DATABASE_URI: str
+    SQLALCHEMY_DATABASE_URL: str
     """The SQLAlchemy database URL."""
     ANTHROPIC_API_KEY: str
     """The Anthropic API key."""
 
-    model_config = SettingsConfigDict(env_file=".env")
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
     """The model configuration."""
 
 

tools/src/pop_fem_audit_tools/database.py

@@ -7,11 +7,10 @@
 """
 from functools import cached_property
 from pathlib import Path
+from typing import Any
 
 import sqlalchemy as sa
-from sqlalchemy.engine.interfaces import DBAPICursor, DBAPIConnection
 from sqlalchemy.orm import DeclarativeBase, sessionmaker, Session
-from sqlalchemy.pool import ConnectionPoolEntry
 
 from .config import Settings, get_settings
 
@@ -30,7 +29,7 @@ class DataSource:
         :return: The database engine.
         """
         settings: Settings = get_settings()
-        return self.__create_engine(settings.SQLALCHEMY_DATABASE_URI)
+        return self.__create_engine(settings.SQLALCHEMY_DATABASE_URL)
 
     @cached_property
     def __session_local(self) -> sessionmaker:
@@ -52,6 +51,9 @@ class DataSource:
     def __create_engine(cls, url: str) -> sa.Engine:
         """Constructs and returns the database engine.
 
+        The foreign key enforcement is enabled on every connection
+        of a SQLite engine.
+
         :param url: The SQLAlchemy database URL.
         :return: The database engine.
         """
@@ -63,10 +65,24 @@ class DataSource:
                 poolclass=sa.StaticPool)
         else:
             engine = sa.create_engine(url)
-        if engine.dialect.name == "sqlite":
-            cls.__enable_sqlite_foreign_keys(engine)
+        if engine.url.get_backend_name() == "sqlite":
+            sa.event.listen(engine, "connect",
+                            cls.__enable_sqlite_foreign_keys)
         return engine
 
+    @staticmethod
+    def __enable_sqlite_foreign_keys(dbapi_connection: Any,
+                                     _: Any) -> None:
+        """Enables the foreign key enforcement on a new connection.
+
+        :param dbapi_connection: The DBAPI connection.
+        :param _: The connection record (unused).
+        :return: None.
+        """
+        cursor: Any = dbapi_connection.cursor()
+        cursor.execute("PRAGMA foreign_keys=ON")
+        cursor.close()
+
     @staticmethod
     def __resolve_sqlite_relative_url(url: str) -> str:
         """Resolves the SQLite relative URL to the instance folder.
@@ -85,31 +101,6 @@ class DataSource:
         path = base / "instance" / path
         return f"sqlite:///{path}"
 
-    @staticmethod
-    def __enable_sqlite_foreign_keys(engine: sa.Engine) -> None:
-        """Turns on the foreign key enforcement of SQLite.
-
-        The ``foreign_keys`` pragma is turned on for every
-        connection of the engine, so that the ``ON DELETE``
-        actions of the schema run.
-
-        :param engine: The SQLite database engine.
-        :return: None.
-        """
-        def on_connect(dbapi_connection: DBAPIConnection,
-                       _: ConnectionPoolEntry) -> None:
-            """Turns on the pragma on a new connection.
-
-            :param dbapi_connection: The DB-API connection.
-            :param _: The connection record (unused).
-            :return: None.
-            """
-            cursor: DBAPICursor = dbapi_connection.cursor()
-            cursor.execute("PRAGMA foreign_keys=ON")
-            cursor.close()
-
-        sa.event.listen(engine, "connect", on_connect)
-
 
 ds: DataSource = DataSource()
 """The data source."""

tools/tests/test_build_db.py

@@ -278,7 +278,7 @@ class TestBuildDB(unittest.TestCase):
         self.__annotations: Path = self.__dir / "annotations.csv"
         self.__write_chart(self.CHART_CSV)
         config.set_settings(config.Settings(
-            SQLALCHEMY_DATABASE_URI="sqlite://",
+            SQLALCHEMY_DATABASE_URL="sqlite://",
             ANTHROPIC_API_KEY="test-key"))
         self.__ds: DataSource = DataSource()
         self.addCleanup(self.__ds.engine.dispose)

tools/tests/test_export_llm_input.py

@@ -36,7 +36,7 @@ class TestExportLlmInput(unittest.TestCase):
         self.__dir: Path = Path(tmp.name)
         self.__output: Path = self.__dir / "llm-input.jsonl"
         config.set_settings(config.Settings(
-            SQLALCHEMY_DATABASE_URI="sqlite://",
+            SQLALCHEMY_DATABASE_URL="sqlite://",
             ANTHROPIC_API_KEY="test-key"))
         self.__ds: DataSource = DataSource()
         self.addCleanup(self.__ds.engine.dispose)

tools/tests/test_fetch_artists.py

@@ -45,7 +45,7 @@ class TestFetchArtists(unittest.TestCase):
         self.__snapshot: Path = \
             self.__dir / "artists_wikidata.csv"
         config.set_settings(config.Settings(
-            SQLALCHEMY_DATABASE_URI="sqlite://",
+            SQLALCHEMY_DATABASE_URL="sqlite://",
             ANTHROPIC_API_KEY="test-key"))
         self.__ds: DataSource = DataSource()
         self.addCleanup(self.__ds.engine.dispose)

tools/tests/test_fetch_lyrics.py

@@ -44,7 +44,7 @@ class TestFetchLyrics(unittest.TestCase):
         self.__provenance: Path = \
             self.__dir / "lyrics-provenance.csv"
         config.set_settings(config.Settings(
-            SQLALCHEMY_DATABASE_URI="sqlite://",
+            SQLALCHEMY_DATABASE_URL="sqlite://",
             ANTHROPIC_API_KEY="test-key"))
         self.__ds: DataSource = DataSource()
         self.addCleanup(self.__ds.engine.dispose)

tools/tests/test_models.py

@@ -27,7 +27,7 @@ class TestModels(unittest.TestCase):
     def setUp(self) -> None:
         """Create the schema on an in-memory SQLite database."""
         config.set_settings(config.Settings(
-            SQLALCHEMY_DATABASE_URI="sqlite://",
+            SQLALCHEMY_DATABASE_URL="sqlite://",
             ANTHROPIC_API_KEY="test-key"))
         self.__ds: DataSource = DataSource()
         self.addCleanup(self.__ds.engine.dispose)

tools/tests/test_run_llm.py

@@ -188,8 +188,7 @@ class TestRequestBuilding(RunLLMTestCase):
         :return: The parsed request.
         """
         stdout: io.StringIO = io.StringIO()
-        stderr: io.StringIO = io.StringIO()
-        with redirect_stdout(stdout), redirect_stderr(stderr):
+        with redirect_stdout(stdout):
             run_llm.main([
                 str(self.__prompt), str(self.__input),
                 str(self.__archive_dir), "--dry-run"] + extra_argv)
@@ -240,7 +239,7 @@ class TestMainFlow(RunLLMTestCase):
             str(self.__prompt), str(self.__input),
             str(self.__archive_dir)]
         self.__settings: config.Settings = config.Settings(
-            SQLALCHEMY_DATABASE_URI="sqlite://",
+            SQLALCHEMY_DATABASE_URL="sqlite://",
             ANTHROPIC_API_KEY="test-key")
         config.set_settings(self.__settings)
 

tools/tests/test_tally_annotations.py

@@ -50,7 +50,7 @@ class TestTallyAnnotations(unittest.TestCase):
             run_dir.mkdir()
             self.__runs.append(run_dir)
         config.set_settings(config.Settings(
-            SQLALCHEMY_DATABASE_URI="sqlite://",
+            SQLALCHEMY_DATABASE_URL="sqlite://",
             ANTHROPIC_API_KEY="test-key"))
         self.__ds: DataSource = DataSource()
         self.addCleanup(self.__ds.engine.dispose)

tools/tests/test_tally_codings.py

@@ -39,7 +39,7 @@ class TestTallyCodings(unittest.TestCase):
         self.__output_csv: Path \
             = self.__dir / "results" / "codings.csv"
         config.set_settings(config.Settings(
-            SQLALCHEMY_DATABASE_URI="sqlite://",
+            SQLALCHEMY_DATABASE_URL="sqlite://",
             ANTHROPIC_API_KEY="test-key"))
         self.__ds: DataSource = DataSource()
         self.addCleanup(self.__ds.engine.dispose)