docs: update change log and project initialization prompt for clarity and structure

.github/prompts/project.init.prompt.md

@@ -1,43 +1,44 @@
 # /project.init — 初始化規格（Project Init）
 
-目的
+## 目的
 - 快速產生或盤點 `spec/spec.md`，作為契約與不變條件的單一來源。
-- 自動判斷是 greenfield 專案（無既有程式）還是 brownfield 專案（有既有程式），輸出相應的內容。
-
-輸入（由提問者提供）
-- 專案摘要（目前用途、使用者、主要流程）
-- 已知的 I/O 與外部依賴（若未知可空白）
-- 任何現有文件或 README 的連結（若有）
-- 工作區根目錄的程式碼結構概述（若提供，LLM 將判定為 brownfield）
-
-自動判定邏輯
-1. **Greenfield（無既有程式碼）**：LLM 產生初版規格骨架
-2. **Brownfield（有既有程式碼）**：LLM 盤點現有程式，提出規格建議
-
-請輸出
-
-### 若判定為 Greenfield
-- 以 `.github/spec-template.md` 為藍本，產出初版章節骨架與示範內容
-- 填入已知資訊，未知處留 TODO
-- 顯示「後續補齊清單」，列出缺漏與建議的尋找路徑
-
-### 若判定為 Brownfield
-- 根據既有程式和文件，提出 `spec/spec.md` 應包含的主要章節與內容建議，包含：
-  - 系統架構與核心組件
-  - I/O 契約（輸入/輸出 shape、格式、限制）
-  - 依賴與外部資源
-  - 失敗降級與可觀測性
-  - 性能限制與資源上限
-  - UI/UX 規範（若適用）
-- 缺漏清單：哪些重要規格缺失或不清楚
-- 建議的驗證步驟（在哪些檔案/程式入口可以找到相關證據）
-- 風險與優先序（高/中/低）
-
-完成後
-- 提示使用者確認並根據建議建立或更新 `spec/spec.md`
-- 建議使用者在 spec 確認後，**手動執行** `/project.plan` 以進入迭代規劃階段
-
-守則
-- 不做檔案修改或實際編寫 spec.md（僅提供建議）。
-- 盡量將領域數值與限制導向 `spec/spec.md`，避免散落在其它文件。
-- 僅輸出文字；如需代辦清單，標記 TODO。
+- 判斷 greenfield（無程式）還是 brownfield（有程式），輸出精簡的規格建議。
+
+## 輸入
+使用者提供：
+- 專案摘要（用途、主要流程、使用者）
+- I/O 與外部依賴（已知則填，未知可空）
+- 現有文件/README（若有）
+- 程式碼結構（若提供 → brownfield）
+
+## 判定邏輯
+- **Greenfield**：無程式碼，LLM 產生初版骨架
+- **Brownfield**：有程式碼，LLM 盤點代碼、提出建議
+
+## 輸出
+
+### Greenfield 模式
+以 `.github/spec-template.md` 為範本，產出：
+1. 簡潔骨架：7 個章節（見 template）各列 1–2 行
+2. 填入已知資訊，未知處留 TODO
+3. 「後續補齊清單」：需要調查或決策的項目
+
+### Brownfield 模式
+掃描既有程式，產出簡潔建議：
+1. **系統概觀**：架構 & 核心組件（3–5 句）
+2. **I/O 契約**：輸入/輸出形狀、必填欄位、格式
+3. **不變條件 & 邊界**：核心規則、失敗時降級方式
+4. **外部依賴**：主要服務/檔案、失敗降級
+5. **缺漏清單**：規格缺失或不清楚的項
+6. **驗證位置**：程式入口、設定檔位置（供查證）
+
+## 完成後
+- 提示使用者確認內容
+- 建議根據建議手動建立或更新 `spec/spec.md`
+- 提示下一步：在 spec 確認後執行 `/project.plan` 進入迭代規劃
+
+## 守則
+- **不修改檔案**：僅提供建議文字（不實際寫 spec）
+- **簡潔優先**：決策層級，不列完整資料結構或假資料
+- **領域知識集中**：數值、規則盡量導向 spec，避免散落
+- **實務優先**：只記錄「必須知道的」

.github/spec-template.md

@@ -1,89 +1,48 @@
 # 規格（Spec）模板 — 單人專案簡化版
 
-> 用途：作為專案的契約與不變條件單一來源（Single Source of Truth）。  
-> 注意：本模板為單人小型專案優化版，著重於核心契約與邊界情境；評估必要時補充完整版章節。
+> **用途**：作為專案的契約與不變條件單一來源（Single Source of Truth）。  
+> **原則**：簡潔、可執行、易維護。只記錄「必須知道的」，不列完整執行結果或逐行詳解。
 
 ## 1. 概述（Overview）
-- **背景與目標**：專案要解決的問題、可量化/驗證的目標。
-- **非目標**：此次不處理的事項（避免範圍擴張）。
-- **主要輸入/輸出**：一句話定義資料流的起點與終點。
-
-## 2. 架構與入口（Compact）
-- **主要入口**：CLI/Web/腳本/服務端點（僅列責任，不綁定檔名）。
-- **核心流程**：3–5 步的高層流程圖或敘述。
-- **關鍵相依**：外部服務/檔案/第三方庫。
-
-## 3. I/O 與資料契約（Data Contracts）
-- **輸入形狀與欄位**：資料形狀、必填欄位、預設值、驗證規則。
-- **輸出形狀與欄位**：預期格式、誤差/置信指標（如適用）。
-- **版本與相容性**：如何識別破壞性變更、遷移策略（若有）。
-
-## 4. 不變條件與限制（Invariants & Limits）
-- **核心規則**：業務邏輯中不可破壞的假設（如資料採樣率、處理窗口大小、並行數量上限等）。
-- **邊界情境與降級**：資料不足/缺漏/格式錯誤時的行為（退回/佔位/跳過/重試）。
-- **資源上限**：記憶體/時間/API 配額（語義層級，具體值置於設定檔）。
-
-## 5. 外部依賴與設定（Dependencies）
-- **外部服務/檔案/模型**：用途、介面、失敗時的降級方案。
-- **設定來源**：環境變數/設定檔欄位與預設值。
-- **快取與重試**：命中/失敗/TTL 策略。
-
-## 6. 失敗降級與可觀測性（Resilience & Observability）
-- **降級矩陣**：各失敗點 → 替代行為（繼續/佔位/使用預設值）+ Log 等級。
-- **Logging**：關鍵節點需有 INFO/WARNING/ERROR，記錄現象、原因、替代方案。
-- **測試邊界情境**：Happy path + 1–2 個代表邊界案例（如資料缺漏、逾時、格式錯誤）。
-
-## 7. UI/交互行為（若適用）
-- **主要流程**：使用者操作序列與預期結果。
-- **警告/錯誤顯示**：何時顯示、文案風格（應面向終端使用者）。
-- **無障礙/國際化**：如有特殊需求則列出。
-
-## 8. 擴充點（Extensibility）
-- **新增資料來源/目標**：如何添加新資源而不修改核心邏輯。
-- **新增輸入源/功能模組**：預留的設定/表格/介面位置。
-- **版本遷移**：破壞性變更時的因應步驟。
-
-## 9. 最小測試（Testing Checklist）
-- ✅ Happy path：完整流程 1 次（包含所有必填欄位）。
-- ✅ 邊界 1：資料不足/缺漏時能降級並顯示警告。
-- ✅ 邊界 2：外部服務失敗時能使用預設值/佔位。
-- ✅ 邊界 3：異常格式/超限時能記錄並繼續。
-
-## 10. 變更紀錄（Decision Log）
-- YYYY-MM-DD: 條目、影響、相容性、連結（PR/Issue）。
-
----
-
-## 附錄 A：常數與參考設定（可選）
-
-| 項目 | 預設值 | 來源 |
-|------|--------|------|
-| 常數 1 | 值 A | 硬編/約束/降級 |
-| 常數 2 | 值 B | 硬編/約束/降級 |
-| 常數 N | 值 N | 硬編/約束/降級 |
-
----
-
-## 附錄 B：資料欄位（可選）
-
-### 輸入欄位範例
-- `[源 1 路徑]`: `[欄位 A, 欄位 B, 欄位 C, ...]`
-- `[源 2 路徑]`: `[欄位 D, 欄位 E, 欄位 F, ...]`
-
-### 輸出欄位範例
-- `[輸出格式]`: `[欄位 1, 欄位 2, 欄位 3, ...]`
+**三句話說清楚**：
+- 問題 & 目標：一句話
+- 非目標：避免什麼
+- 主要輸入/輸出：資料流向
+
+## 2. 核心流程
+- 主要入口：CLI/Web/腳本/API
+- 3–5 步簡述
+- 關鍵外部依賴：服務/檔案/第三方庫名稱
+
+## 3. I/O 契約
+- **輸入**：資料形狀、必填欄位、預設值
+- **輸出**：預期格式、主要欄位
+- **相容性**：破壞性變更如何識別
+
+## 4. 不變條件 & 邊界
+- **核心規則**：不可破壞的假設（採樣率、處理單位上限、並行限制等）
+- **邊界行為**：缺漏/格式錯誤 → 降級策略（跳過/預設值/日誌警告）
+- **資源限制**：記憶體/時間/配額（語義級，具體值在設定檔）
+
+## 5. 外部依賴 & 降級
+- **主要依賴**：用途、介面、失敗時的替代行為
+- **日誌原則**：各失敗點應記 WARNING/ERROR（描述現象+替代方案）
+- **重試/快取**：簡述策略（無則不列）
+
+## 6. 擴充與相容（可選）
+- 新增資料源/模組的預留方式
+- 版本遷移計畫（若有破壞性變更）
+
+## 7. 驗收清單
+- ✅ Happy path：完整流程
+- ✅ 邊界情境：最常見的 1–2 個失敗案例
 
 ---
 
 ## 使用建議
 
-### 單人專案快速檢查清單
-1. **初期**：先填 1–4 節（明確 I/O 與邊界），不必逐章完整。
-2. **開發中**：發現新的邊界情境或外部依賴時，補充到第 4、5、6 節。
-3. **測試前**：確認第 6、9 節的降級與測試覆蓋。
-4. **新增功能**：先更新本文件（尤其 I/O 與邊界），再寫程式。
-
-### 何時升級為完整版
-- 多人協作開始、需求快速變化、或涉及多層級服務時，補充第 7–8 節與完整圖表。
-- 仍需參考原始 spec-template.md 作為參考。
+1. **初期**：填 1–4 節，建立基本契約
+2. **開發中**：發現新邊界時更新第 4–5 節
+3. **功能擴展**：先更新本文，再寫程式
+4. **記住**：不需列完整的執行結果、逐行說明或假資料，只記「決策」與「規則」
 

change-log.md

@@ -1,58 +1,35 @@
-# Change Log
-
-用途
-- 用於在任務完成後，將改動簡化整理為高層摘要，方便回顧與版本對齊。
-- 無需與 `docs/task.md` 一對一對應；可依里程碑/批次/日期合併紀錄。
-
-使用方式
-- 每次完成一批有意義的變更（合併 PR、完成里程碑、或結束一輪對話）時，新增一個條目。
-- 條目內容建議包含下列要點；若無則可省略，但公共行為與 I/O shape 變更必寫：
-  - Highlights（做了什麼、為何做）
-  - Spec/契約影響（是否更新 `docs/spec.md`、不變條件有無變動）
-  - 行為或 I/O 變更（UI、張量 shape、欄位變化與相容性）
-  - 資料/站台檔影響（`station/*.csv` 欄位或資料需求變更）
-  - 降級與 Logging（新增/調整的降級策略、關鍵 log 片語）
-  - 測試與驗收（新增/更新的測試、手動冒煙結果要點）
-  - 風險與回滾（若適用）
-  - 連結（PR、Commits、相關 Task IDs 可選）
+# 變更記錄 (Change Log)
+
+**專案**：TTSAM（Taiwan Transformer-based Shake Alert Model）  
+**格式**：高層變更摘要，按日期倒序排列
 
 ---
 
-## 2025-10-25 — 文件與工作流強化：task.md 與 change-log.md
-- Highlights
-  - 新增 `docs/task.md` 工作流與 `docs/task-template.md`，支援跨對話任務拆解與驗收。
-  - 新增 `change-log.md`，集中紀錄高層摘要，完成批次後可重置 `docs/task.md`。
-  - 擴充 `.github/copilot-instructions.md` 與 `README.md`，說明任務→摘要→重置之流程。
-- Spec/契約影響
-  - 無功能性調整；僅文件與流程。沿用既有不變條件（100 Hz/30s、<=25 站、Z 代 NE、Vs30 降級、地圖 800px）。
-- 行為或 I/O 變更
-  - 無；僅文件與維運工作流。
-- 資料/站台檔影響
-  - 無。
-- 降級與 Logging
-  - 無變更；維持現行策略。
-- 測試與驗收
-  - 手動檢查：新增/編輯的文檔檔案可正確顯示；連結指向正確位置。
-- 風險與回滾
-  - 低；如需回滾，移除新增文檔即可。
-- 連結
-  - Task: T-20251025-docs-workflow（規劃）
-
-## 2025-10-25 — UI 對齊不變條件：時間長度滑桿改為 0–30 秒
-- Highlights
-  - 將 `app.py` 之「時間長度 (秒)」滑桿範圍由 1–60 調整為 0–30（預設 30）。
-  - 新增說明文字：模型最多 30 秒；不足 30 秒以 0 填充至 30 秒（100 Hz，共 3000 點）。
-- Spec/契約影響
-  - 與 `docs/spec.md` 不變條件一致；無公共行為或 I/O 破壞性變更。
-- 行為或 I/O 變更
-  - UI 限制使用者輸入於 0–30 秒；後端行為不變（既有 30 秒窗口與補齊）。
-- 資料/站台檔影響
-  - 無。
-- 降級與 Logging
-  - 維持原有：duration < 30 秒時記錄 INFO 並 0 填充；其他降級策略不變。
-- 測試與驗收
-  - 手動冒煙：duration=0/5/30 均可載入與預測；看到不足 30 秒之補齊 log 與正常輸出。
-- 風險與回滾
-  - 低；若需回復，可將滑桿改回 1–60（單行改動）。
-- 連結
-  - Task: T-20251025-duration-slider-0-30
+## 2025-10-26 — Brownfield Spec Init
+
+### 新增
+- **`spec/spec.md`**（v1.0）：完整規格書
+  - 系統架構、I/O 契約、不變條件、限制
+  - 錯誤處理與日誌原則（spec #1–#7）
+  - 資源依賴、擴充指南、版本管理
+  - 審核檢查清單
+- **`spec/plan.md`**：迭代計畫模板（待填）
+- **`spec/task-template.md`**：任務拆解模板（待填）
+
+### 說明
+- 基於現有 `app.py` 與 README.md 進行 Brownfield 盤點
+- 正式化 I/O 契約、不變條件、降級策略
+- 確立長期設計參考點（`spec/spec.md`）與短期迭代計畫（`spec/plan.md`、`spec/task.md`）
+
+### 後續工作清單
+- [ ] 驗證 spec 對應現有程式碼（app.py、ttsam_realtime.py）
+- [ ] 若發現差異或缺漏，更新 spec 或程式碼
+- [ ] 根據開發需求，在 `spec/plan.md` 定義下一迭代目標
+- [ ] 進行程式碼審核，確保滿足 spec 第 10 節檢查清單
+
+---
+
+**End of Change Log**
+
+*此檔案記錄每個迭代/變更的高層摘要。詳細內容應參考 `spec/spec.md` 與 git commit 訊息。*
+