Add reAM250 BOM research task pack

queue_tasks/research_mission/ream250_bom_research/README.md

@@ -0,0 +1,197 @@
+# reAM250 BOM Research Task Pack
+
+This folder contains one-off support files for the reAM250 BOM research run. It
+is not part of the generic research queue system.
+
+## Files
+
+- `research_instructions/agent.md` - Prompt/instructions for a Codex agent processing
+  reAM250 BOM research queue items.
+- `research_schemas/research_result.schema.yaml` - Expected structured result shape.
+- `research_scripts/generate_queue_tasks.py` - Build queue items from the gold
+  CSV/manifest package, optionally extracting STEP metadata with FreeCAD.
+- `research_scripts/validate_results.py` - Local validator for result Markdown/YAML/JSON
+  files.
+- `research_scripts/run_codex_batches.sh` - Optional batch runner that repeatedly starts
+  fresh `codex exec` sessions.
+
+## Queue Requirements
+
+The queue should contain research tasks with:
+
+- `kind: research`
+- `gap_type: research_task`
+- IDs starting with `research_task:ream250_bom_row_`
+- `context.output_path` under `research/ream250_bom/`
+- `context.output_validator` pointing to this task pack validator
+
+Generate or refresh the 401 queue items from the gold CSV/manifest:
+
+```bash
+.venv/bin/python queue_tasks/research_mission/ream250_bom_research/research_scripts/generate_queue_tasks.py \
+  --replace-queue-prefix
+```
+
+This replaces only existing queue entries whose IDs start with
+`research_task:ream250_bom_row_`.
+
+CAD geometry is intentionally read by the agent after it leases a specific row.
+Use `--extract-cad-metadata` only for offline diagnostics, not for the normal
+research queue run.
+
+Lease with hard filters:
+
+```bash
+.venv/bin/python -m src.cli queue lease \
+  --agent ream250-bom-agent-01 \
+  --ttl 7200 \
+  --kind research \
+  --gap-type research_task \
+  --id-prefix research_task:ream250_bom_row_
+```
+
+## Agent Usage
+
+Open Codex from the repo root:
+
+```bash
+cd /home/eastrolinux/seres
+codex --search -C /home/eastrolinux/seres -s workspace-write -a on-request
+```
+
+Then tell the agent:
+
+```text
+Read queue_tasks/research_mission/ream250_bom_research/research_instructions/agent.md and follow it as ream250-bom-agent-01.
+```
+
+Use a different agent name in each terminal, such as `ream250-bom-agent-02`.
+
+## Session Limit
+
+Each agent session should process at most 3 queue items. Restart or clear the
+session for the next batch. This keeps web research context bounded and makes
+failures easier to resume.
+
+## Automated Batch Runner
+
+For larger runs, use the task-local runner instead of manually clearing Codex or
+opening new terminals. The runner starts a fresh `codex exec` session for each
+small batch, so context does not accumulate across the whole BOM.
+
+Conservative default:
+
+```bash
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh
+```
+
+Two workers, three rows per fresh Codex session:
+
+```bash
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh \
+  --workers 2 \
+  --max-items 3
+```
+
+Smoke test one Codex session:
+
+```bash
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh \
+  --max-batches 1
+```
+
+Print the generated prompt without running Codex:
+
+```bash
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh --dry-run
+```
+
+Logs are written to `out/ream250_bom_runner_logs/` by default.
+
+### Targeted Reruns
+
+The runner has an optional `--id-prefix` filter. If it is omitted, the runner
+uses the normal broad prefix:
+
+```text
+research_task:ream250_bom_row_
+```
+
+That default means "any reAM250 BOM research row". Normal runs do not need to
+pass `--id-prefix`.
+
+The option is named `--id-prefix` because the queue lease API filters with
+`startswith(...)`, not exact-id matching. Passing a complete queue id still works
+as an exact single-row filter because the complete id is also a valid prefix of
+itself.
+
+To rerun a completed row, first release it back to `pending`, then run one
+single-item batch with the complete queue id as the prefix:
+
+```bash
+.venv/bin/python -m src.cli queue release \
+  --id research_task:ream250_bom_row_0195_6Q \
+  --agent rerun-targeted
+
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh \
+  --workers 1 \
+  --max-items 1 \
+  --max-batches 1 \
+  --id-prefix research_task:ream250_bom_row_0195_6Q
+```
+
+The runner prompt requires the agent to overwrite an existing output file after
+re-checking evidence. If you are testing that behavior, verify the file mtime or
+inspect the log for an actual file write.
+
+Rerun the first three completed smoke-test rows in one shell loop:
+
+```bash
+for id in research_task:ream250_bom_row_0308_174 research_task:ream250_bom_row_0195_6Q research_task:ream250_bom_row_0380_4122; do .venv/bin/python -m src.cli queue release --id "$id" --agent rerun-targeted && queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh --workers 1 --max-items 1 --max-batches 1 --id-prefix "$id"; done
+```
+
+### Runner Risks
+
+- If a Codex session crashes after leasing an item, that item remains leased
+  until its TTL expires. Run `.venv/bin/python -m src.cli queue gc` after the TTL
+  to return expired leases to pending.
+- Parallel workers increase web-search/API usage and can hit external rate
+  limits. Start with `--workers 1` or `--workers 2`.
+- Do not run `python -m src.cli index` while the runner is active. This workflow
+  relies on the research queue as the state source.
+- The runner does not guarantee research quality. It only bounds context and
+  automates fresh Codex sessions; use `research_scripts/validate_results.py` to check
+  required result structure and source fields.
+
+## Validate Results
+
+Validate one file:
+
+```bash
+.venv/bin/python queue_tasks/research_mission/ream250_bom_research/research_scripts/validate_results.py \
+  --file research/ream250_bom/ream250_bom_row_0001_11.md
+```
+
+Validate a directory:
+
+```bash
+.venv/bin/python queue_tasks/research_mission/ream250_bom_research/research_scripts/validate_results.py \
+  --dir research/ream250_bom
+```
+
+The validator checks that `function`, `mass`, `material`, and `how_to_make`
+each have their own source object containing:
+
+- `url_or_path`
+- `cited_fact_or_basis`
+- `confidence`
+
+## Completion
+
+Complete research tasks without `--verify`:
+
+```bash
+.venv/bin/python -m src.cli queue complete --id <leased-id> --agent <agent-name> --require-output --validate-output
+```
+
+Do not run `python -m src.cli index` during this one-off research workflow.

queue_tasks/research_mission/ream250_bom_research/README.zh.md

@@ -0,0 +1,187 @@
+# reAM250 BOM 研究任務包
+
+這個資料夾只服務 reAM250 BOM 這次單次研究任務，不是通用 research
+queue 系統的一部分。
+
+## 檔案
+
+- `research_instructions/agent.md` - 給 Codex agent 的 reAM250 BOM 研究指令。
+- `research_schemas/research_result.schema.yaml` - 結果檔應符合的結構。
+- `research_scripts/generate_queue_tasks.py` - 從 gold CSV/manifest 產生 queue
+  items，可選擇用 FreeCAD 抽 STEP metadata。
+- `research_scripts/validate_results.py` - 檢查 Markdown/YAML/JSON 結果檔的本地驗證器。
+- `research_scripts/run_codex_batches.sh` - 選用的 batch runner，會反覆啟動新的
+  `codex exec` session。
+
+## Queue 條件
+
+queue 裡的任務應該符合：
+
+- `kind: research`
+- `gap_type: research_task`
+- ID 以 `research_task:ream250_bom_row_` 開頭
+- `context.output_path` 位於 `research/ream250_bom/`
+- `context.output_validator` 指到這個任務包的 validator
+
+從 gold CSV/manifest 產生或刷新 401 筆 queue items：
+
+```bash
+.venv/bin/python queue_tasks/research_mission/ream250_bom_research/research_scripts/generate_queue_tasks.py \
+  --replace-queue-prefix
+```
+
+這只會替換 ID 以 `research_task:ream250_bom_row_` 開頭的既有 queue entries。
+
+CAD 幾何資料刻意由 agent 在 lease 到特定 row 後才讀取。`--extract-cad-metadata`
+只用於離線診斷，不作為正常 research queue run 的流程。
+
+租任務時使用 hard filters：
+
+```bash
+.venv/bin/python -m src.cli queue lease \
+  --agent ream250-bom-agent-01 \
+  --ttl 7200 \
+  --kind research \
+  --gap-type research_task \
+  --id-prefix research_task:ream250_bom_row_
+```
+
+## Agent 使用方式
+
+在 repo root 開 Codex：
+
+```bash
+cd /home/eastrolinux/seres
+codex --search -C /home/eastrolinux/seres -s workspace-write -a on-request
+```
+
+進入 Codex 後貼：
+
+```text
+Read queue_tasks/research_mission/ream250_bom_research/research_instructions/agent.md and follow it as ream250-bom-agent-01.
+```
+
+不同 terminal 使用不同 agent 名稱，例如 `ream250-bom-agent-02`。
+
+## 每個 Session 的工作上限
+
+每個 agent session 最多處理 3 筆 queue item。做完 3 筆就停，下一輪重新開
+或 `/clear`。這可以降低 web research 把 context 撐爆的機率，也比較容易恢復。
+
+## 自動 Batch Runner
+
+如果要跑大量 rows，不要手動一直 `/clear` 或開新 terminal。可以使用這個
+task-local runner；它每一小批都會啟動新的 `codex exec`，所以 context 不會
+在整份 BOM 期間持續累積。
+
+保守預設：
+
+```bash
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh
+```
+
+兩個 worker，每個新的 Codex session 最多處理 3 rows：
+
+```bash
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh \
+  --workers 2 \
+  --max-items 3
+```
+
+先測一個 Codex session：
+
+```bash
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh \
+  --max-batches 1
+```
+
+只印出產生的 prompt，不實際執行 Codex：
+
+```bash
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh --dry-run
+```
+
+log 預設會寫到 `out/ream250_bom_runner_logs/`。
+
+### 指定 Row 重跑
+
+runner 有選用的 `--id-prefix` filter。不加時會使用正常的寬 prefix：
+
+```text
+research_task:ream250_bom_row_
+```
+
+這個預設值代表「任何 reAM250 BOM research row」。正常批次執行不需要加
+`--id-prefix`。
+
+它叫 `--id-prefix` 是因為 queue lease API 用的是 `startswith(...)` 過濾，
+不是 exact-id matching。把完整 queue id 傳進去仍然等同於指定單一 row，
+因為完整 id 也是它自己的 prefix。
+
+如果要重跑已完成 row，先把該 queue item release 回 `pending`，再用完整
+queue id 當 prefix 跑一個單筆 batch：
+
+```bash
+.venv/bin/python -m src.cli queue release \
+  --id research_task:ream250_bom_row_0195_6Q \
+  --agent rerun-targeted
+
+queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh \
+  --workers 1 \
+  --max-items 1 \
+  --max-batches 1 \
+  --id-prefix research_task:ream250_bom_row_0195_6Q
+```
+
+runner prompt 會要求 agent 在重新檢查證據後覆寫既有 output file。若你是在測試
+是否真的重寫，請檢查檔案 mtime，或看 log 裡是否有實際寫檔動作。
+
+用一行 shell loop 重跑前三筆 smoke-test 結果：
+
+```bash
+for id in research_task:ream250_bom_row_0308_174 research_task:ream250_bom_row_0195_6Q research_task:ream250_bom_row_0380_4122; do .venv/bin/python -m src.cli queue release --id "$id" --agent rerun-targeted && queue_tasks/research_mission/ream250_bom_research/research_scripts/run_codex_batches.sh --workers 1 --max-items 1 --max-batches 1 --id-prefix "$id"; done
+```
+
+### Runner 風險
+
+- 如果 Codex session 在 lease 任務後中斷，該任務會維持 leased 到 TTL
+  過期。TTL 到期後可跑 `.venv/bin/python -m src.cli queue gc` 回收。
+- 平行 worker 會增加 web search/API 使用量，也更容易遇到外部 rate limit。
+  建議先從 `--workers 1` 或 `--workers 2` 開始。
+- runner 執行時不要跑 `python -m src.cli index`。這個流程把 research queue
+  當作狀態來源。
+- runner 不保證研究品質；它只負責限制 context 並自動啟動新的 Codex
+  session。結果格式與 source 欄位仍要用 `research_scripts/validate_results.py` 檢查。
+
+## 驗證結果
+
+驗證單一檔案：
+
+```bash
+.venv/bin/python queue_tasks/research_mission/ream250_bom_research/research_scripts/validate_results.py \
+  --file research/ream250_bom/ream250_bom_row_0001_11.md
+```
+
+驗證整個資料夾：
+
+```bash
+.venv/bin/python queue_tasks/research_mission/ream250_bom_research/research_scripts/validate_results.py \
+  --dir research/ream250_bom
+```
+
+驗證器會檢查 `function`、`mass`、`material`、`how_to_make` 是否各自有
+source object，且包含：
+
+- `url_or_path`
+- `cited_fact_or_basis`
+- `confidence`
+
+## 完成任務
+
+research task 完成時不要加 `--verify`：
+
+```bash
+.venv/bin/python -m src.cli queue complete --id <leased-id> --agent <agent-name> --require-output --validate-output
+```
+
+這個單次研究流程期間不要跑 `python -m src.cli index`。