todo（核心）
此儲存庫是一個閉環狀態機，完全由既有的檔案建構而成。除此之外不儲存任何其他狀態。
| 層級 | 檔案 | 角色 | 寫入策略 |
|---|---|---|---|
| 需求 | README.md, docs/*.md | 事實來源：合約、規格、設定、長期計畫 | 主要為讀取。在 todo-continue 的「文件偏離」階段編輯；計畫文件（docs/plans/）由 todo-init/todo-plan/todo-add/todo-update 編輯；README 中的 Tests: 行由 todo-init 在確認後編輯；可選的 RTM（reference/rtm.md）僅在已存在時由 todo-plan/todo-add/todo-continue 編輯；docs/status.html 由 todo-report 編輯 |
| 活躍佇列 | TODO.md | 單一任務樹。工作項目的追蹤器，非設計場所 | 僅由 todo-* 技能編輯 |
| 驗證 | 原始碼 + 測試套件 | 「完成」的事實來源 | 僅為當前任務變更 |
| 歸檔 | CHANGELOG.md | 永久，僅附加（遵循 Keep a Changelog + Conventional Commits） | 僅 ## [Unreleased]（釋出時：重新命名為版本號，在其上方建立新的空白區塊，並更新結尾的連結行）由根節點的排空與已確認的 /todo-release 觸及；todo-init 建立檔案或新增遺失的 [Unreleased] |
| 檢查（可選） | .todo/check.sh, .todo/todo-lint.sh, CI 任務 | Lint + 測試，由 CI、預先推送鉤子與 /todo-continue 執行 | check.sh 由 /todo-init --ci 在確認後寫入；todo-lint.sh 由使用者複製；由使用者提交 |
| 版本儲存 | git | 每個任務一個分支或工作目錄。未經驗證的內容絕不進入基礎分支 | 請參閱「Git 模式」 |
對於檔案編輯，優先使用原生的檔案工具（Read/Edit/Write）；無論使用何種編輯方式，僅變更預期的行數，並保留檔案結尾的換行符。Shell 僅用於 git、測試和「完成時：」指令、可選腳本，以及技能指定的檔案指令（cp, chmod, mkdir -p, date, grep, cmp, mv，以及技能自身臨時檔案的 rm）。
待辦事項檔案包括 TODO.md、CHANGELOG.md、docs/plans/PROJECT.md、以 Ref: 命名的 docs/plans/<ROOT-ID>-*.md，以及由 todo-* 技能寫入的 README Tests: 和 Base: 行。README.md 僅在待辦事項提交中暫存，當 git diff README.md 恰好新增這些行（可選在空白行之後）時；由節點在「文件偏離」下編輯的 README 內容屬於該節點的檔案，並隨其一起提交；任何其他 README 變更皆屬使用者所有：它會計入乾淨樹檢查，但永遠不會被待辦事項提交暫存。待辦事項編輯保持未提交狀態，直到技能在 todo/ 分支上進行下一次提交（通常是樹聲明），此時會透過明確路徑暫存它們。新的根節點，以及對未聲明樹中任何節點的任何變更，僅在基礎分支上進行；在 todo/ 分支上，技能會拒絕並指明基礎分支。乾淨樹檢查（reference/git-flow.md）會忽略它們。
直接使用
單獨的 /todo 為唯讀：列出指令，若 TODO.md 存在則對其執行不變條件檢查，然後回報。不會變更任何內容。
| 指令 | 用途 |
|---|---|
/todo-init | 引導檔案，偵測測試指令與 git，可選的預先規劃與 CI 設定，遷移舊格式 |
/todo-plan | 將工作規劃成車道與樹；隨時修訂計畫 |
/todo-add | 新增任務，或將請求分解成樹 |
/todo-continue | 執行下一個任務節點，驗證它，將其合併至父節點 |
/todo-update | 手動狀態與欄位變更 |
/todo-status | 唯讀的樹、車道、歷史紀錄與搜尋 |
/todo-report | 將互動式 HTML 狀態頁面寫入 docs/status.html |
/todo-release | 在使用者確認後，將 [Unreleased] 轉換為版本號 |
每個技能僅執行其自身的指令，絕不會未經提示而鏈結至另一個指令。
Git 模式
在每個指令開始時執行 git rev-parse --is-inside-work-tree。
- Git 儲存庫： 每個節點在其自己的分支或工作目錄上工作（
reference/git-flow.md）。基礎分支是使用者命名的分支，否則為 README 的Base:行，否則為main、master、trunk、develop中第一個存在的分支；若都沒有，則詢問一次。當使用者命名的基礎分支與此預設值不同時，提供將Base: <branch>新增至 README 的選項（在確認後寫入；一個類似Tests:行的待辦事項檔案）。每個簽出或合併至基礎分支的步驟（樹聲明、聲明釋放、基礎合併、發佈）都在主要簽出（git worktree list的第一個條目）中執行：若從連結的工作目錄開始，則先cd到那裡；若它在另一個有變更的分支上，則停止並列印指令。 - 非 git 儲存庫： 每個指令警告一次：「這不是一個 git 儲存庫。todo 技能仍然可以運作，但沒有分支、工作目錄、提交或合併，因此沒有隔離性也沒有歷史記錄。執行
git init以啟用它們。」然後使用無 git 模式：跳過所有 git 步驟，在State:中追蹤進度（包括files:），仍更新標記並排空至 CHANGELOG.md。驗證保持不變。
永遠不要標記標籤、強制推送、硬重置或清除。唯一允許的強制分支刪除，是針對一個僅包含技能自身未發布聲明提交的分支（reference/git-flow.md，樹聲明步驟 2 與 5）。技能自身的 git 指令絕不觸及網路： 不進行 fetch、pull 或 push。分享提交是 git 的工作，也是你的工作。測試指令可能下載依賴項；若因缺乏網路而失敗，則以此原因阻止，而非重試。
TODO.md 結構
# Active Backlog
## 🌳 Task Tree
必須有恰好此標題與一個章節。沒有 In Progress、Ready 或 Blocked 章節：每個任務上的標記即其狀態。空的樹由兩個標題且無任務構成。
一個任務為 2 到 4 行：要做什麼、如何驗證、可選的連結與狀態。
- [ ] **FEAT-002** · P1 · mid · XL · 新增權杖重新整理至認證服務
- Done when: 舊權杖在重新整理後被拒絕；`npx jest tests/auth`；回歸測試：`npm test`
- Links: Ref: docs/auth.md#refresh · Depends: TASK-001 · From: FIX-001
- State: branch todo/FEAT-002-add-token-refresh-auth from main; next: build children
- [ ] **FEAT-002.1** · mid · 重新整理端點
- Done when: 端點經整合測試覆蓋；`npx jest tests/auth/refresh.test.ts`
- [/] **FEAT-002.1.1** · high · 權杖儲存介面
- Done when: 儲存區能往返傳遞權杖；`npx jest tests/auth/store.test.ts`
- State: attempts 1/3; baseline 42 passing; branch todo/FEAT-002.1.1-token-store-interface from todo/FEAT-002.1-refresh-endpoint; next: build
| 部分 | 規則 |
|---|---|
| 標頭 | - [m] **ID** · [P0-P2，僅根節點 ·] COMPLEXITY [· SIZE] · 要做什麼，一句話：複雜度 low、mid 或 high（必填）；大小 S、M、L 或 XL（可選） |
Done when: | 必填。 條件，接著 ; 和至少一個以反引號包圍的確切指令。可選 ; regression: \cmd``；若無，則回歸測試為專案的完整測試套件 |
Links: | 可選。Ref: <path#anchor>、Depends: <IDs>、From: <ID>、Lane: <name>（僅根節點），以 · 分隔 |
State: | 可選，可在上下文重置後存活。項目以 ; 分隔，每個最多出現一次，順序如下：attempts n/3、baseline <n> passing（或 none，或 red: <failing test ids, comma-separated>）、`tier: <low |
Blocked: | 在 [!] 任務上，取代 State 並位於其位置（最後的欄位行）：` → <error, at most 5 lines joined with |