Reorganize data/ into source, captures, and manual layers

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

.gitignore

@@ -1,5 +1,5 @@
 # Copyrighted lyrics cache — never commit full lyrics
-data/lyrics/
+data/captures/lyrics/
 
 # Secrets
 .env

CLAUDE.md

@@ -21,9 +21,11 @@
 
 ## Data rules
 
-- `data/yearend_hot100_2016_2025.csv` is the only hand-placed
+- `data/source/` holds the immutable hand-placed raw files;
-  raw file; everything else in `data/` is script-derived.
+  `data/captures/` is written only by the fetch commands and the
-- Full lyrics are copyrighted: they stay in `data/lyrics/`
+  private import script; `data/manual/` is written only by the
+  user's own hand.
+- Full lyrics are copyrighted: they stay in `data/captures/lyrics/`
   (gitignored) and must never be committed or reproduced in
   full anywhere in the repo.
 

README.md

@@ -21,17 +21,17 @@ Hot 100（2016–2025）為例的內容分析。
 3. 依 `docs/research_plan.md` 的階段順序，於 `tools/` 目錄下
    執行子命令，必要輸入以位置引數、選擇性輸入以選項給定（如
    `pop-fem-audit-tools build-db
-   ../data/yearend_hot100_2016_2025.csv
+   ../data/source/yearend_hot100_2016_2025.csv
-   --lyrics-dir ../data/lyrics
+   --lyrics-dir ../data/captures/lyrics
-   --wikidata-csv ../data/artists_wikidata.csv
+   --wikidata-csv ../data/captures/artists_wikidata.csv
-   --overrides-csv ../data/artists_overrides.csv`）。
+   --overrides-csv ../data/manual/artists_overrides.csv`）。
    LLM 步驟使用 `claude-sonnet-4-6`、temperature=0、
    thinking 關閉；每步驟獨立執行兩次後由仲裁步驟合併
    （「2+1」協定）。
 4. 每次執行的完整紀錄（定義檔快照、原始輸出、參數）存於
    `runs/`，可逐筆稽核。論文引用的最終資料表在 `results/`。
 
-注意：歌詞受版權保護，`data/lyrics/` 不隨 repo 發布，須自行
+注意：歌詞受版權保護，`data/captures/lyrics/` 不隨 repo 發布，須自行
 以 `tools/` 中的抓取程式重建。
 
 ## 授權

docs/decision_log.md

@@ -119,3 +119,8 @@
   settings 的 `.env` 依 pydantic 慣例讀自 CWD（約定
   `tools/`），資料路徑原以 repo 根為 CWD，兩者衝突；顯式引數
   消滅隱性 CWD 契約，亦拒絕以父目錄推導兄弟檔案的隱性慣例。
+- **`data/` 依生命週期分三層**：`source/`（源頭，手放後不動）、
+  `captures/`（外部捕捉，只由 fetch 命令與私人匯入腳本寫入）、
+  `manual/`（人工著作，只由研究者手寫；之後的黃金標準編碼
+  亦居此）。理由：三種生命週期混住一層，目錄無法傳達「誰可以
+  寫哪裡」；顯式引數化後搬遷零程式改動。

docs/project_structure.md

@@ -8,16 +8,20 @@ pop-fem-audit/
 ├── README.md                  # 專案說明、重現步驟
 ├── CLAUDE.md                  # 極簡工作規範（subagent 會讀到，
 │                              #   絕不放理論、codebook、預期結果）
-├── .gitignore                 # data/lyrics/、.env、scratch
+├── .gitignore                 # captures/lyrics/、.env、scratch
 ├── conference_abstract.md     # pilot 摘要（投稿版）
-├── data/                      # 源頭與捕捉層（文字格式，進 git）
+├── data/                      # 依生命週期分三層（文字格式）
-│   ├── yearend_hot100_2016_2025.csv   # 原始榜單（唯一手放原始檔）
+│   ├── source/                # 源頭：手放後不動
-│   ├── artists_wikidata.csv           # 捕捉：Wikidata 快照
+│   │   └── yearend_hot100_2016_2025.csv   # 原始榜單
-│   ├── artists_overrides.csv          # 人工核定 / 深度背景
+│   ├── captures/              # 外部捕捉：只由 fetch 命令與
-│   ├── lyrics_provenance.csv          # 歌詞出處（source + method）
+│   │   │                      #   私人匯入腳本寫入
-│   ├── lyrics_missing.csv             # 歌詞缺漏報表（人工補救用）
+│   │   ├── artists_wikidata.csv           # Wikidata 快照
-│   └── lyrics/                        # 歌詞 .txt 快取
+│   │   ├── lyrics_provenance.csv          # 歌詞出處
-│                                      #   （gitignored，版權）
+│   │   ├── lyrics_missing.csv             # 歌詞缺漏報表
+│   │   └── lyrics/                        # 歌詞 .txt 快取
+│   │                                      #   （gitignored，版權）
+│   └── manual/                # 人工著作：只由研究者手寫
+│       └── artists_overrides.csv          # 人工核定 / 深度背景
 ├── prompts/                   # LLM 定義檔（逐字作為 system prompt）
 │   └── <task>_v<N>.md         #   版本化：screen_v1.md、judge_v2.md…
 ├── tools/                     # 輔助工具子專案（src-layout）
@@ -36,7 +40,7 @@ pop-fem-audit/
 │   │   ├── fetch_artists.py   # fetch artist metadata from
 │   │   │                      #   Wikidata into the snapshot CSV
 │   │   ├── fetch_lyrics.py    # fetch missing lyrics from the
-│   │   │                      #   public APIs into data/lyrics/
+│   │   │                      #   public APIs into the lyrics dir
 │   │   ├── models.py          # SQLAlchemy ORM 資料模型
 │   │   └── run_llm.py         # API runner：2+1 協定、Batch API、
 │   │                          #   寫入引數指定的 runs 目錄；執行

docs/research_plan.md

@@ -61,7 +61,7 @@
   匯入歌詞快取——只取識別欄位與歌詞本文，以
   (year, rank) 精確匹配 song_id。匯入工具不屬於專案交付物
   （讀者拿不到其輸入），讀者的重現路徑純粹是 `fetch-lyrics`；
-  沿用之**事實**記於 `data/lyrics_provenance.csv`（進 git）：
+  沿用之**事實**記於 `data/captures/lyrics_provenance.csv`（進 git）：
   `source`（原始 API）與 `method`
   （pilot-import / api-fetch / manual）兩層，取得日期不可考者
   不假造，僅記可證上界。
@@ -103,7 +103,7 @@
 
 ## 其他已定案事項
 
-- 歌詞受版權保護：完整歌詞不進 git（`data/lyrics/` gitignored），
+- 歌詞受版權保護：完整歌詞不進 git（`data/captures/lyrics/` gitignored），
   論文與 repo 只留分類所引摘錄。
 - Fable 5 不用於 pipeline：成本高、thinking 無法關閉且不可稽核、
   無 temperature 控制，且會混淆「盲點是提示問題」的核心主張。