skills/doc-issues-analyze/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: doc-issues-analyze
-description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list，依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
+description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題；處理議題時必須連同所有留言與附件一起讀取，附件內容一併納入需求分析），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日；形成子母議題時母議題必須所有子議題關閉後才可關閉，優先以 issue dependency 阻擋），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list；分析完成後若議題屬於專案看板且欄位可對應進度語意（例如分析中/待處理/進行中/待測試/已完成），把議題移到「待處理」欄位（不往回移、介面不支援時改列建議清單請人工調整）；再依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
 ---
 
 # 分析多來源需求並保存為議題
 
-你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源並彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 `develop` 或 `master`；**實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR**。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
+你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源並彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 `develop` 或 `master`；**實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR**。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
 
 ## 絕對準則（不可違反）
 
-- **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、實作進度、交付摘要）一律留在**對話內容**與 **subagent 的回傳值**，並透過 `tea` 或 Gitea API **保存到議題描述或留言**。唯一例外是使用者確認實作某議題後、在該議題範圍內對**目標 repository 原始碼**進行的正常程式修改與 git commit；除此之外不產生任何本機檔案。
+- **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、實作進度、交付摘要）一律留在**對話內容**與 **subagent 的回傳值**，並透過 `tea` 或 Gitea API **保存到議題描述或留言**。例外只有兩個：（1）使用者確認實作某議題後、在該議題範圍內對**目標 repository 原始碼**進行的正常程式修改與 git commit；（2）為了讀取議題附件（圖片等二進位檔）而**唯讀暫存下載到系統暫存目錄**，讀取完畢後立即刪除，不得下載到工作目錄或任何 repo 內、不得用暫存檔傳遞其他中間成果。除此之外不產生任何本機檔案。
 
 ## 前置：輸入與工具
 
@@ -21,6 +21,11 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
 - **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，實作參考以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
 - **工具選擇**：在解析與讀取 Gitea 來源前，先檢查本機是否可用 `tea`、`tea login list` 是否有對應 login、以及環境變數 `GITEA_TOKEN` 是否已設定；接著詢問使用者要使用 `tea` 或 Gitea REST API + `curl` + token。使用者已明確指定工具時才可跳過詢問。
 - **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
+- **議題必須連同留言與附件一起讀取**：處理任何議題（含專案底下展開的議題）時，除了 `title`／`body` 等欄位，必須一併讀取**所有留言（comments）**與**所有附件（attachments/assets，含議題本身與各留言的附件）**，其內容都是需求分析的依據：
+  - 附件清單：`tea` 目前沒有附件指令，一律走 API — 議題附件 `GET {base}/repos/{owner}/{repo}/issues/{index}/assets`、留言附件 `GET {base}/repos/{owner}/{repo}/issues/comments/{id}/assets`，取得每個附件的檔名、類型與下載 URL。
+  - 文字類附件（Markdown、純文字、CSV、JSON 等）：以 `curl` 直接取得內容到對話中分析，不落地。
+  - 圖片或其他二進位附件：依絕對準則的例外**唯讀暫存下載到系統暫存目錄**讀取（例如圖片以視覺方式讀取內容），讀取完畢後立即刪除暫存檔。
+  - 無法讀取的格式（或僅有 `tea` 而無 token 可下載附件）：在保存議題內容中列出附件檔名與 URL 並標註「附件無法讀取，需人工確認」，不得忽略附件的存在，也不得臆測其內容。
 - **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。
 - **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。
 - **議題描述流程圖**：產生保存議題或小功能議題的描述時，若有助於理解，盡量在描述中加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染），把需求流程、狀態轉移或議題間的相依／阻擋關係視覺化；流程圖必須忠實反映需求與拆分結果，不得杜撰未提及的流程。
@@ -78,16 +83,16 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
    - target repositories 來源：使用者指定的 repositories 位置，或「以來源議題所在 repo／保存目標 repo 為準」。
 4. 若使用者指定了 repositories 位置，先確認該路徑存在並列出其中的專案；若未指定，記錄「以來源議題所在 repo／保存目標 repo 為準」，並確認本機是否已 clone 對應 repo（沒有就在保存議題留言中標註需人工提供或 clone）。
 5. 依選定來源讀取內容：
-   - 專案：讀取 project 描述、欄位／卡片、project metadata，並只讀取該專案下**開啟中的議題**（若 API 有分頁必須完整分頁讀取）。若 Gitea 版本不支援 project API 或無法由 project 取得開啟中的 issue 清單，標註「此 Gitea 版本不支援 project API，需人工處理」，並請使用者改提供議題編號或可匯出的 project 文件。
+   - 專案：讀取 project 描述、欄位／卡片、project metadata，並只讀取該專案下**開啟中的議題**（若 API 有分頁必須完整分頁讀取；每筆議題都依「議題必須連同留言與附件一起讀取」完整讀取）。若 Gitea 版本不支援 project API 或無法由 project 取得開啟中的 issue 清單，標註「此 Gitea 版本不支援 project API，需人工處理」，並請使用者改提供議題編號或可匯出的 project 文件。
-   - 議題：對每一筆 issue，讀取完整內容：`title`、`body`、`state`、`labels`、`milestone`、`assignees`、以及**所有 comments**；若 Gitea 版本支援，另讀該 issue 所屬 `project`。
+   - 議題：對每一筆 issue，讀取完整內容：`title`、`body`、`state`、`labels`、`milestone`、`assignees`、**所有 comments**、以及**議題與各留言的所有附件**（讀取方式見前置「議題必須連同留言與附件一起讀取」）；若 Gitea 版本支援，另讀該 issue 所屬 `project`。
    - 檔案文件：讀取文件全文；若格式無法直接讀取，標註需人工轉換或提供純文字／Markdown。
 6. 同時盤點該 repo 既有的分類資源，供後續階段沿用：
    - 標籤：`GET {base}/labels`（tea：`tea labels list`）
    - 里程碑：`GET {base}/milestones`（tea：`tea milestones list`）
    - 專案（若該 Gitea 版本有此 API）：`GET {base}/projects`；若不支援就記錄「此 Gitea 版本不支援 project API，需人工處理」。
 7. 把所有來源內容彙整成保存議題內容，使用 `tea` 或 Gitea API 建立或更新保存議題；不得寫入本機草稿檔。保存議題描述至少包含：
-   - 來源清單：每筆專案／議題／檔案的來源資訊、標題或名稱、狀態、現有 labels／milestone／project（若適用）。
+   - 來源清單：每筆專案／議題／檔案的來源資訊、標題或名稱、狀態、現有 labels／milestone／project（若適用），以及議題的留言數與附件清單（檔名；無法讀取的附件標註「需人工確認」）。
-   - 完整需求描述：整合專案、議題、檔案文件的內容，去除重複、補齊上下文，形成單一連貫的需求敘述。
+   - 完整需求描述：整合專案、議題（含留言與附件內容）、檔案文件的內容，去除重複、補齊上下文，形成單一連貫的需求敘述。
    - 驗收條件／預期結果：能從來源內容推得的，逐條列出；不能確定的標註「需人工確認」。
    - 保存議題分類：labels／milestone／project 掛載方式。
    - `## TODO`：根據保存議題描述內容產生 Markdown checklist，放在描述最後。
@@ -105,8 +110,21 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
 - 到期日：根據複雜度評估 due date，預設從建立日往後推算：`S` 3 個工作天、`M` 5 個工作天、`L` 10 個工作天、`XL` 15 個工作天；若遇週末順延到下一個工作天。若小功能有相依關係，必須先排定相依順序，後置功能的到期日不得早於其前置功能的到期日，且應從最後一個前置功能的到期日之後再依自身複雜度推算。若 Gitea API 不支援 due date，寫入 issue body 並回報需人工設定。
 - 相依關係：列出與保存議題、來源議題與其他小功能議題的關聯；若有前後依賴，必須標明前置功能、後置功能、阻擋方向與到期日排程依據。
 
+**子母議題關閉規則**：若本次拆分實際建立了子母關係（保存議題為**母議題**、拆出的小功能議題為**子議題**），母議題必須在**所有子議題都關閉後才可關閉**，建立子議題時就要把這個限制落實：
+
+- 優先用 Gitea issue dependency 實作：把母議題設為 blocked by **每一個**子議題（API `POST {base}/issues/{母議題 index}/dependencies`，body 帶子議題資訊；先以 GET 探測該實例是否啟用 dependency 功能，404／501 視為不支援），讓 Gitea 在子議題尚未全部關閉前直接阻止關閉母議題。
+- dependency 不支援或未啟用時：在母議題描述加入「子議題清單」markdown 任務清單（每項連結一個子議題，例如 `- [ ] #<index> <子議題標題>`）與「關閉前檢查：所有子議題皆已關閉」字樣，並在回報中標註此限制需人工遵守；不得對未確認存在的端點做寫入。
+- 後續新增或補拆子議題時，必須同步補上對應的 dependency 或母議題子議題清單項目，不得遺漏。
+
 決定要對照的 target repositories：使用者指定位置底下的所有專案、來源議題所在 repo，或使用者指定 repo。可研究相關專案程式碼以補充小功能議題描述，但所有分析結果必須直接保存到小功能議題描述或留言，不得建立本機草稿檔。
 
+**分析完成後：把議題移到看板「待處理」欄位**。保存議題與所有小功能議題都建立／更新完成後（即分析階段結束），對其中**確實屬於某個專案看板（project board）**的議題調整進度欄位：
+
+- 若看板欄位名稱可對應進度語意（例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，語意相近即可對應，不得假設看板一定有這五欄），把議題移動到「待處理」欄位，代表需求分析已完成、等待實作。
+- **不往回移**：議題已在「待處理」或更後面的欄位（進行中／待測試／已完成）時維持原欄位，只有在「分析中」或未指定欄位時才移動。
+- 移動前先探測可用介面：`tea` 目前沒有 project 看板指令；Gitea REST 的 project／column 端點依版本而異，先以 GET 探測端點是否存在（404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。
+- 看板沒有可對應「待處理」語意的欄位、或介面不支援時，不移動、不視為錯誤：改在回報與保存議題留言中列出「議題 → 待處理」建議清單，請使用者到看板手動拖曳；不得新建欄位。
+
 ## 第 4 步：依到期日排序並逐議題實作
 
 將第 3 步產生的小功能議題依到期日由早到晚排序；若到期日相同，依相依關係排序，前置議題必須排在後置議題前。排序結果必須使用 `tea` 或 Gitea API 留言到保存議題或相關小功能議題，不得寫入本機檔案。
@@ -121,5 +139,6 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
 - 執行適合專案的測試／建置／驗證；失敗時留言說明失敗原因與下一步。
 - 完成後提交變更並推送工作分支，向 `develop` 開 PR；若遠端沒有 `develop`，改向 `master` 開 PR。不得直接 push 到 `develop` 或 `master`。
 - PR 內容必須連結對應小功能議題，並摘要變更、測試結果、風險與需人工確認項目。
+- **關閉順序（子母議題）**：實作完成只關閉（或由 PR 合併帶關鍵字自動關閉）該小功能**子議題**，並同步勾選母議題子議題清單中的對應項目（若有）；**母議題必須等所有子議題都關閉後才可關閉** — 有 dependency 阻擋時由 Gitea 強制，否則依母議題的「關閉前檢查」人工確認。所有子議題關閉後，回報母議題已可關閉並詢問使用者是否關閉，不得擅自關閉母議題。
 
 若小功能議題尚未實際建立到 Gitea，本步只能產生排序與實作計畫，不得開始實作；必須先回到建立小功能議題的確認流程。

skills/doc-issues-sync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doc-issues-sync
-description: 讀取一個 Gitea 專案（project）或單一議題（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq）；若給的是專案，因 tea／Gitea API 目前無法直接查詢專案，就先取得該 repo 底下所有開啟中的議題、再過濾掉與此專案無關的議題；若給的是議題就只同步該議題。議題若有標籤就依標籤分組並以 AskUserQuestion 讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，基於工作目錄下的所有檔案：分析議題描述的需求並判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補上 TODO 追加到議題正文、依需求從既有標籤更新議題標籤、逐條判斷未完成 TODO（含新增）是否已完成、有異動就整理成一則留言。全程不落地任何檔案：所有中間成果一律留在對話／subagent 回傳內容，最終只透過 tea 或 Gitea API 寫回議題正文／標籤／留言，且寫入前先經使用者確認。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、tea issues、Gitea 專案議題時使用此 skill。
+description: 讀取一個 Gitea 專案（project）或單一議題（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq）；若給的是專案，因 tea／Gitea API 目前無法直接查詢專案，就先取得該 repo 底下所有開啟中的議題、再過濾掉與此專案無關的議題；若給的是議題就只同步該議題。議題若有標籤就依標籤分組並以 AskUserQuestion 讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，基於工作目錄下的所有檔案：分析議題描述的需求並判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補上 TODO 追加到議題正文、依需求從既有標籤更新議題標籤、逐條判斷未完成 TODO（含新增）是否已完成、有異動就整理成一則留言；若議題屬於專案看板且看板欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），依議題描述與勾稽結果建議並調整議題所在欄位，介面不支援時改列建議清單請使用者手動調整。全程不落地任何檔案：所有中間成果一律留在對話／subagent 回傳內容，最終只透過 tea 或 Gitea API 寫回議題正文／標籤／留言，且寫入前先經使用者確認。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、tea issues、Gitea 專案議題時使用此 skill。
 ---
 
 # 依工作目錄同步 Gitea 專案／議題的 TODO 進度與標籤
@@ -20,6 +20,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
   2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定；未設定則停下請使用者提供）。
 - **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
 - **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。
+- **專案進度欄位（project column）**：若議題屬於某個專案看板（project board），且看板欄位名稱可對應進度語意（例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，不得假設看板一定有這五欄），本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整；對應規則見第 3.5 步。欄位語意對不上或介面不支援時不移動，只回報建議。
 - **議題描述流程圖**：若要補進議題正文或進度留言的內容有助於理解（例如需求流程、TODO 之間的先後／相依），盡量加入 **Mermaid 流程圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）以視覺化呈現；流程圖必須忠實反映議題需求與 TODO 現況，不得杜撰未提及的流程。
 
 ## 第 0 步：解析輸入、判斷專案或議題、準備工具
@@ -61,8 +62,15 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 3. **3.2 依需求更新可用標籤**：依議題需求性質，從該 repo **既有標籤**中挑選應掛上（或應移除）的標籤，回傳內容中列出「建議的標籤異動」（新增哪些、移除哪些、維持哪些）。**不自行新建標籤**，除非使用者要求；找不到合適標籤就維持原樣並標註。
 4. **3.3 逐條勾稽未完成 TODO 是否已完成**：對所有**未完成**的 TODO（含 3.1 新增的），逐條依工作目錄下的檔案內容判斷是否已完成。已完成者標記為 `- [x]` 並在回傳內容記下判斷依據（以 `path:line` 指出對應實作位置）；無法從檔案可靠判斷者維持未完成並標註「需人工確認」。
 5. **3.4 整理 TODO 異動留言**：若本議題有任何 TODO 異動（**新增**的 TODO，或**狀態變更**——由未完成改為完成），整理成一則留言內容，包含：本次新增了哪些 TODO、哪些 TODO 判定為完成（附對應實作位置）、哪些仍未完成（含原因／需人工確認）。若沒有任何 TODO 異動，回傳標明「無異動、不需留言」。
+6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則（欄位名稱以看板實際名稱為準，語意相近即可對應）：
+   - 需求仍不明確、TODO 明顯不足以追蹤需求而需大量補列 → 「分析中」。
+   - 需求與 TODO 齊全，但工作目錄中尚無任何對應實作 → 「待處理」。
+   - 部分 TODO 已勾稽為完成（已有部分實作）→ 「進行中」。
+   - 所有 TODO 勾稽為已完成，但仍有「需人工確認」項目或尚待驗證 → 「待測試」。
+   - 所有 TODO 已完成且無需人工確認 → 「已完成」。
+   回傳內容需含：目前欄位、建議欄位、判斷依據。建議欄位與目前欄位相同時標明「欄位無異動」；看板欄位語意對不上（或取不到欄位資訊）時標明「無法對應、維持原欄位」並列出實際欄位名稱，不得硬套。議題不屬於任何專案看板時跳過本項。
 
-每個 subagent **回傳**一份結構化同步計畫（**不落地成檔案**），至少包含：議題參照與標題、追加後的完整正文（標明新增與勾稽的變更）、建議的標籤異動、TODO 異動留言內容（或「無異動」）、以及所有「需人工確認」項目。
+每個 subagent **回傳**一份結構化同步計畫（**不落地成檔案**），至少包含：議題參照與標題、追加後的完整正文（標明新增與勾稽的變更）、建議的標籤異動、TODO 異動留言內容（或「無異動」）、專案進度欄位建議（目前欄位／建議欄位／判斷依據，或「不屬於專案看板」「無法對應」）、以及所有「需人工確認」項目。
 
 ## 第 4 步：同步計畫品質檢查
 
@@ -72,14 +80,15 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 - 每個要同步的議題都有對應的同步計畫；正文的 TODO 變更（新增／勾稽）與留言內容的敘述一致。
 - 標籤異動只用到該 repo 既有標籤（名稱／id 對得上第 3.1 盤點結果），未擅自新建標籤。
 - 「已完成」的勾稽都有工作目錄檔案的依據；無依據者標為未完成或「需人工確認」，未被誤判為完成。
+- 進度欄位建議只使用看板實際存在的欄位，且與 TODO 勾稽結果一致（例如仍有未完成 TODO 的議題不得建議「已完成」、仍有「需人工確認」項目的議題不得越過「待測試」）。
 - 有問題先在對話中修正同步計畫並重新檢查，通過後才進入下一步。
 
 ## 第 5 步：詢問使用者要如何執行（AskUserQuestion）
 
 同步計畫通過檢查後，主 agent 用 AskUserQuestion 讓使用者確認要如何對 Gitea 執行寫入，至少提供：
 
-1. 全部執行：追加／勾稽 TODO 到議題正文、套用標籤異動、對有異動的議題留言。
+1. 全部執行：追加／勾稽 TODO 到議題正文、套用標籤異動、調整專案進度欄位、對有異動的議題留言。
-2. 只更新議題（正文＋標籤），先不留言。
+2. 只更新議題（正文＋標籤＋進度欄位），先不留言。
 3. 只呈現同步計畫、先不動 Gitea：僅在對話中列出計畫供檢視（不落地檔案、不寫入議題）。
 4. 逐議題確認：每處理完一個議題就回報，待使用者確認後再做下一個。
 5. 其他（由使用者輸入自訂方式）。
@@ -95,6 +104,11 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
   - 更新前先重新讀一次議題正文，若與 subagent 讀到的版本已不同（他人期間有改動），停下該議題並回報，避免覆蓋他人變更。
 - **標籤異動**：套用建議的新增／移除。
   - tea：`tea labels`／issue 編輯對應指令；API：`POST`/`DELETE {base}/repos/{owner}/{repo}/issues/{index}/labels`（用既有 label id）。
+- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，把議題移到建議欄位。
+  - 先探測可用介面：`tea` 目前沒有 project 看板指令；Gitea REST 的 project／column 端點依版本而異，先以 GET 探測對應端點是否存在（回 404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。
+  - 介面可用 → 呼叫對應端點把議題移至建議欄位，一次一個議題並確認回應成功。
+  - 介面不可用 → 不視為錯誤：跳過移動，改在第 7 步回報中列出「議題 → 建議欄位」清單，請使用者到看板手動拖曳。
+  - 只在建議欄位確實存在於看板且語意對應明確時移動；有疑慮就不動並回報。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。
 - **留言**：對有 TODO 異動的議題張貼留言。
   - tea：`tea comment --repo <owner>/<repo> --login <name> <index> "<留言內容>"`；API：`POST {base}/repos/{owner}/{repo}/issues/{index}/comments`，body `{"body":"<留言內容>"}`。
   - 無異動的議題不留言。
@@ -103,7 +117,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 
 ## 第 7 步：回報
 
-- 回報：輸入是專案或議題、（若為專案）該 repo open 議題數／過濾後屬於此專案的議題數與依標籤篩選後的最終清單、每個議題新增了哪些 TODO、勾稽為完成的 TODO（附實作位置）、標籤異動、是否留言，以及所有「需人工確認」或「無法判斷是否屬於此專案」項目。
+- 回報：輸入是專案或議題、（若為專案）該 repo open 議題數／過濾後屬於此專案的議題數與依標籤篩選後的最終清單、每個議題新增了哪些 TODO、勾稽為完成的 TODO（附實作位置）、標籤異動、進度欄位異動（目前欄位 → 新欄位；介面不支援時改列「議題 → 建議欄位」清單請使用者手動調整）、是否留言，以及所有「需人工確認」或「無法判斷是否屬於此專案」項目。
 - 因全程不落地檔案，**沒有本機草稿需要清理**；成果都在對話與已寫回的議題正文／標籤／留言中。
 
 ## 重要限制
@@ -113,6 +127,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
 - 「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」一律以**工作目錄下的檔案**為依據；無法可靠判斷就標「需人工確認」，不得臆測或編造需求未涵蓋的內容。
 - subagent 與各步驟只讀檔案與議題、只回傳結構化內容，**不得在磁碟寫任何檔案、不得修改任何工作目錄原始碼**。
 - 標籤只從既有標籤挑選，不自行新建（除非使用者要求）。
+- 進度欄位調整只在議題確實屬於專案看板、建議欄位存在於看板且語意對應明確、並經第 5 步使用者確認後執行；不得新建欄位、不得對未確認存在的 API 端點做寫入。介面不支援時只回報建議清單，不視為錯誤。
 - 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。
 - 留言與回傳內容不得洩漏個資（PII）；若議題內容含個資，於回傳內容與留言中僅保留必要資訊或去識別化。
 - 回傳內容與留言以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。