docs: update Copilot instructions for clarity and specification alignment

.github/copilot-instructions.md

@@ -1,81 +1,80 @@
 # GitHub Copilot 指南（專案層級）
 
-請在本倉庫撰寫或修改程式碼時，務必遵循 `spec/spec.md` 的契約與不變條件。以下是重點守則與常見情境處理方式：
-
-關鍵文件
-- 必讀：`spec/spec.md`（軟體生命週期規格與設計；所有決策的長期約束與全局不變條件）
-- 本次 Sprint：`spec/plan.md`（此次 sprint 的範圍、目標與驗收標準；由 `/project.plan` 產生，可修改）
-- 主要程式與入口：請參考 `spec/spec.md` 中「主要程式/入口」章節（本文件不列舉檔名）
-- 範例/樣板流程：請參考 `spec/spec.md` 中的相關章節（本文件不列舉檔名）
-- 任務追蹤：`spec/task.md`（跨對話追蹤的任務拆解與驗收）
-- 變更摘要：`change-log.md`（完成後的高層摘要，非逐 Task 對應）
-
-核心守則（務必遵守）
-- 合約優先：一切行為以 `spec/spec.md` 為準，不在本文件重複或硬編領域常數。若發現不一致，先以 spec 為準並提出修正建議。
-- I/O 與資料契約：嚴格遵循 spec 定義的輸入/輸出形狀與資料欄位；任何變更需先更新 spec，並標註相容性與回滾策略。
-- 失敗降級與可觀測性：對所有可能失敗點提供明確降級方案與可追溯的 log；避免單一站點/檔案/服務錯誤導致整體中斷。
-- 邏輯集中與封裝：將跨處共用的關鍵規則與資源（例如資料載入、批次策略、對外服務查詢）集中封裝，避免分散於多處。
-- UI 行為：UI 顯示警告與提示的判準來自 spec；UI 不做字串解析以偷渡參數，不將關鍵參數藏於顯示名稱中。
-- 外部資源與預設：對外部依賴（檔案、API、模型、地圖資源）提供預設值、快取與退回路徑，並記錄使用情況與原因。
-- 相容性優先：新增或變更功能時，優先保持向後相容；若必須變更公共行為或 I/O，先在 spec 說明，並準備遷移與回滾。
-- 原則性限制（抽象）：批次處理、長度/頻率/資源上限等僅在 spec 定義；本文件僅要求「遵循 spec 的限制」，不重複具體數值。
-
-程式碼風格與作法
-- 加入或變更功能時，請以註解說明與 spec 的對齊；無需使用編號標籤。
-- 優先保持向後相容，不破壞現有行為；若需變更公共行為，先更新 `spec/spec.md`。
-- 對所有可能失敗點提供降級方案與 log；不要讓單站/單檔錯誤導致整體中斷。
-- 避免將模型結構分散於多處；若需重構，提供明確入口（工廠或封裝函式）。
-
-常見任務提示
-- 注意：本節僅提供流程範例；所有領域細節、檔名/欄位/限制一律以 `spec/spec.md` 為準。
-- 新增資料來源：
-  - 依 `spec/spec.md` 放置必要輸入，並更新程式的資料清單或索引。
-- 新增目標對象：
-  - 依 `spec/spec.md` 更新目標清單，不修改核心流程與模型行為。
-- 新增輸入來源：
-  - 依 `spec/spec.md` 更新來源清單，避免重複與格式不符。
-
-提交前檢查（最低需求）
-- 是否符合 `spec/spec.md` 的輸入/輸出 shape 與不變條件？
-- 針對 spec 中定義的邊界情境（如輸入不足、資料缺失、逾時、格式錯誤等）是否提供冒煙測試或最小驗證步驟？
-
-任務工作流：spec/task.md（跨對話沿用）
-- 在規劃或討論變更時，請於 `spec/task.md` 維護任務（提供模板）。
-- 每個任務請填寫：背景與目標、不變條件對齊、任務拆解（可勾選）、測試與驗收、降級策略、進度紀錄。
-- 子任務應小而可驗收（理想 1 小時內完成），並附明確驗收標準與冒煙測試方式。
-- 每個任務請填寫：背景與目標、不變條件對齊、任務拆解（可勾選）、降級策略、進度紀錄。
-- 子任務應小而可驗收（理想 1 小時內完成），並附明確驗收標準。
-- 本工作流僅為協助追蹤，不取代 `spec/spec.md` 的契約約束。
-
-完成後的變更摘要與 task 重置
-- 當某個任務或一批變更完成時，請在 `change-log.md` 新增一個條目，摘要說明本次改變了什麼（可跨多個 Task 合併記錄，非一對一）。
-- 條目建議包含：Highlights、Spec/契約影響、行為或 I/O 變更、資料檔影響、降級與 Logging、測試與驗收、風險與回滾、連結（PR/Commits/Task IDs）。
-- 條目完成後，可刪除或重置 `spec/task.md`；下次任務開始時請以 `spec/task-template.md` 重新建立。
-- 條目建議包含：Highlights、Spec/契約影響、行為或 I/O 變更、資料檔影響、降級與 Logging、風險與回滾、連結（PR/Commits/Task IDs）。
----
-
-Copilot Slash Commands（審核檢查點工作流）
-- 本專案提供以下指令（位於 `.github/prompts/*.prompt.md`），協助「先審核、後實作」：
-  - `/project.init`：初始化 `spec/spec.md`。自動判斷是否有既有程式碼，若有（brownfield）則盤點現有規格，若無（greenfield）則產生初版骨架。
-  - `/project.plan`：產生 `spec/plan.md`（本次 sprint 的範圍、目標與驗收標準），讓使用者討論、修改、確認。
-  - 確認後：根據討論結果更新 `spec/spec.md`（若有規格變更）並產生 `spec/task.md`（任務拆解）。
-  - `/project.task`：列出編號的 task 清單與驗收標準，讓使用者檢查、調整、增減。
-  - `/project.apply`：根據使用者選擇的 task 編號，更新 `spec/task.md` 的 checklist 標記，確定本次執行的任務範圍。
-  - `/project.report`：收斂交付、品質門檻與覆蓋度，建議後續。
-
-- 使用建議：
-  - **任意專案的標準工作流**：
-    1. 先執行 `/project.init` → LLM 自動判斷並產生對應的規格建議或骨架
-    2. 根據建議建立或更新 `spec/spec.md`
-    3. 執行 `/project.plan` 產生 `spec/plan.md`
-    4. 討論、修改、確認本 sprint 的計畫
-    5. 根據討論結果更新 `spec/spec.md`（若需要）並產生 `spec/task.md`
-    6. 執行 `/project.task` 列出編號的 task 清單
-    7. 檢查、調整、增減 task 內容（若需要修改 `spec/task.md`）
-    8. 執行 `/project.apply` 選擇要執行的 task，更新 checklist
-    9. 核准後自行實作變更並提交
-    10. 執行 `/project.report` 收斂交付
-
-核准口令
-- 前進：核准、套用、執行、下一步、繼續
-- 調整：退回上一步、只套用 <檔名>、暫停工具呼叫、僅 Dry-run
+本文件為單人專案的 Copilot 開發指南。撰寫或修改程式碼時，務必遵循 `spec/spec.md` 的規格與不變條件。
+
+## 關鍵文件
+
+- **`spec/spec.md`**（長期）：軟體規格、資料契約、不變條件、限制與降級策略。宏觀設計藍圖，所有決策的參考點。累積性維護。
+- **`spec/plan.md`**（短期）：本次迭代的範圍、目標、驗收標準。臨時討論檔，每個 sprint 更新後可拋棄。
+- **`change-log.md`**：記錄完成的變更摘要（高層描述，非逐行對應）。用於交付追蹤。
+
+## 核心守則（3 點）
+
+### 1. **規格優先** — 合約 + 不變條件
+- 新增或變更功能時，先檢查 `spec/spec.md` 中相關的不變條件與限制。
+- 若需變更 CSV 結構、模型契約、或 API 形狀，**必須先更新 spec**，並說明相容性影響。
+- 當 Copilot 指南與 spec 有衝突時，以 spec 為準。
+
+### 2. **失敗不中斷** — 降級 + 日誌
+- 單點錯誤（缺站欄位、Vs30 查詢失敗、檔案遺失等）**不應中止全流程**。
+- 改用預設值、跳過該點、或降級處理，並記錄 WARNING/ERROR log（使用 loguru）。
+- 參考 `spec/spec.md` 第 6 節「錯誤處理與 Log 原則」的具體策略。
+
+### 3. **資料清晰** — I/O 契約
+- 模型輸入/輸出形狀、CSV 必備欄位、檔案格式必須與 spec 保持一致。
+- 若要改動資料結構（如新增 CSV 欄位），先同步更新 spec 的對應小節。
+
+## 程式碼實踐
+
+- 在涉及 spec 約定的邏輯處加入註解，簡述與 spec 的對齊（如 "spec #4：25 站上限"），無需編號標籤。
+- 優先保持向後相容；新增資料來源（事件、目標測站、輸入站點）時參考 spec 第 8 節的擴充說明。
+- 避免將關鍵邏輯（如批次策略、資源查詢）分散於多處；若需重構，提供明確的入口函式或工廠。
+
+## 提交前檢查
+
+commit 前確認以下兩點：
+
+1. 是否符合 `spec/spec.md` 的輸入/輸出 shape 與不變條件？
+2. 若變更了 CSV 結構或模型契約，spec 已同步更新？
+
+## 迭代與任務追蹤
+
+- 每次開始新迭代時，在 `spec/plan.md` 討論本次目標、範圍、驗收標準。
+- 根據 plan.md 的內容，可在 `spec/task.md` 維護任務拆解（子任務應小而可驗收）。
+- 迭代完成後，更新 `change-log.md` 記錄變更摘要。
+- 舊的 `plan.md` 和 `task.md` 可拋棄，下次迭代時重新建立。
+- 長期的規格變更和決策應同步回 `spec/spec.md`，形成累積的設計參考。
+
+## Copilot Slash Commands（審核檢查點）
+
+本專案提供以下指令協助「規格審核」與「迭代開發」的清晰分工：
+
+### `/project.spec`（需求改變時用）
+- **目的**：調整 `spec/spec.md` 的大方向、契約或不變條件。與現有程式碼做比較，列出後續工作清單。
+- **流程**：
+  1. 討論新增或調整的規格項（需求、契約、不變條件）。
+  2. LLM 掃描現有程式碼，列出符合、缺漏、或違反的地方。
+  3. 產出「需要做的工作清單」。
+  4. 確認後更新 `spec/spec.md`，根據清單建立 `spec/plan.md` 作為後續執行的輸入。
+
+### `/project.plan`（迭代開發時用）
+- **目的**：根據 `spec/plan.md` 拆解本次迭代的任務，指導程式碼實作。
+- **流程**：
+  1. 基於 plan.md 的目標，產出編號任務清單與驗收標準。
+  2. 逐個實作任務，完成後更新 `change-log.md`。
+  3. 下次迭代時，舊 plan.md 可拋棄，根據新需求重新開始。
+
+### 標準工作流
+
+**當需求改變時：**
+1. 執行 `/project.spec` 討論規格調整 + 程式碼比較。
+2. 確認工作清單後更新 `spec/spec.md`。
+3. 根據清單建立 `spec/plan.md`（定義本次迭代範圍）。
+
+**執行迭代時：**
+4. 執行 `/project.plan` 根據 plan.md 拆解任務。
+5. 根據任務清單實作，完成後更新 `change-log.md`。
+6. 迭代結束，舊的 plan.md 與 task.md 可拋棄。
+
+**下次需求改變時：** 回到步驟 1。
+

.github/prompts/project.spec.prompt.md

@@ -0,0 +1,69 @@
+# /project.spec — 規格審核與更新
+
+目的
+- 調整 `spec/spec.md` 的大方向：新增、修改或移除規格項（需求、契約、不變條件、限制）。
+- 與現有程式碼做差異比較，檢查哪些地方符合、缺漏、或違反規格。
+- 產出「需要做的工作清單」，作為 `/project.plan` 的輸入。
+
+應用場景
+- 需求改變、使用者故事新增
+- 發現程式碼與規格不對齊
+- 業務邊界或資料模型調整
+- 性能、相容性或安全性要求變更
+
+角色區分
+- **`spec/spec.md`**：軟體生命週期全局規格（長期、累積性維護）
+- **`spec/plan.md`**：本 sprint 的執行計畫（臨時、可拋棄）
+- **現有程式碼**：當前實作狀態（檢查對齊度）
+
+輸入（由提問者提供）
+- 規格調整的內容描述（新增、修改或移除什麼規格項）
+- 背景與動機
+- 相關的邊界情況或假設（若有）
+
+請輸出
+
+### 第一部分：規格建議
+- 新增或修改的規格項清單，包含：
+  - 項目名稱與章節位置（對應 `spec/spec.md` 現有章節）
+  - 具體描述（契約、限制、不變條件）
+  - 影響範圍（涉及哪些模組/功能）
+  - 相容性說明（是否破壞現有行為）
+
+### 第二部分：程式碼比較分析
+- 掃描 spec 內所提到的關鍵檔案，針對調整項分析：
+  - ✅ **符合規格**：現有程式已正確實作的部分
+  - ❌ **缺漏**：規格定義但程式未實作的部分
+  - ⚠️ **違反**：程式行為與規格不一致的部分
+  - ❓ **不確定**：需要手動驗證的部分
+- 列出具體的程式碼位置（檔案名、函式名、行號範圍）
+
+### 第三部分：工作清單
+- 「需要做的工作項」：根據差異分析產出，包含：
+  - 優先序（High/Medium/Low）
+  - 工作描述與預期結果
+  - 受影響的檔案
+  - 估計工作量（Small/Medium/Large）
+  - 與 spec 各章節的對應關係
+- 格式化為可直接貼入 `spec/plan.md` Checklist 的形式
+
+### 第四部分：驗收與風險
+- 現有不變條件檢查清單（有無違反的？）
+- 主要風險與回滾建議
+- 冒煙測試建議（2–3 個步驟驗證調整是否生效）
+
+完成後
+- 產生上述四部分內容，展示給使用者
+- 使用者確認後的後續流程：
+  1. 根據確認結果更新 `spec/spec.md`（新增/修改規格項）
+  2. 根據「工作清單」建立 `spec/plan.md`（定義本次 sprint 範圍）
+  3. 執行 `/project.plan` 進行任務拆解與驗收標準
+  4. 開始迭代開發
+
+守則
+- 規格建議基於使用者輸入與現有 `spec/spec.md`；未經確認不做檔案修改。
+- 程式碼分析需精準定位（檔案、函式、行號），便於快速定位與修改。
+- 工作清單應與現有的 `spec/spec.md` 章節結構對應，避免遺漏或重複。
+- 若發現規格與程式碼有深層衝突，需明確標註為「需要討論」的項目。
+- 優先保持向後相容；若必須破壞相容性，需在規格變更中明確說明與遷移策略。
+