Ticket System v1.0 Skill

Ticket System v1.0

統一 Ticket 系統 - 整合 create/track/handoff/resume/migrate/generate 六大功能。

系統模型（設計自我描述）

本系統的參照模型是 issue tracker + CI runner（batch job queue 為輔助類比），不是 OS process：

| 對應 | 參照 | 含義 | |------|------|------| | ticket = issue | issue tracker（Jira/Linear/GitHub 類） | 狀態機轉移經 CLI 驗證、stale 需 triage 儀式、ID 為全域引用錨點 | | agent = CI runner | ephemeral runner | 身份在派發/認領時綁定（claim --as）、工作區以隔離 checkout 為優先、逾時由 watchdog 回收 | | wave = batch cohort | job queue 批次 | blockedBy DAG 之外的隱式排序層 |

兩個與 OS process 直覺相反的預設（設計回顧確認：誤用 process 直覺是共享樹競態與身份回填缺口兩類歷史事故的共同根因）：

身份晚綁定：ticket 建立時不知道執行者（submit 與 assign 分離）；身份在 claim 時以 --as 綁定，不是 fork 即繼承。
共享工作區：agent 預設共享 working tree（thread 語意）而非 process 隔離；檔案變更型派發應優先採 feat branch / worktree 隔離。

scheduler 層類比（runqueue/dashboard 對應 Linux schedule()/top）仍然準確，保留使用。

named agent 生命週期三態（v2.9.0 擴展，W1-008 ANA 落地）：agent = CI runner 類比原僅二態（running → stopped），named agent（Agent tool 帶 name 參數 spawn）完工後不自動終止，實際存在第三態：

| 狀態 | 含義 | 觸發 | 對應 CI runner 語意 | |------|------|------|---------------------| | running | agent 正在執行 ticket 工作 | Agent tool spawn / SendMessage 派發新任務 | job 執行中 | | idle | agent 完工無新任務，process 保持存活且可定址 | agent 完成回報後 CC runtime 發送 idle_notification | warm runner（跑完不銷，省下次冷啟動成本） | | stopped | agent process 終止 | SubagentStop（自然結束）/ shutdown_request approve / session 結束 | job 完成後 runner 回收 |

idle 態不改變 agent = runner 的核心類比（身份仍在 claim 綁定、工作區仍隔離），只是擴展 runner 生命週期從「單 job 即銷」到「可選續用多 job」。PM 對 idle agent 的續用/放生判準與回收 SOP 見 .claude/pm-rules/parallel-dispatch.md「idle agent 回收 SOP」章節。

執行方式

禁止直接執行 Python 檔案！ ticket_system 是 Python 套件，必須透過 pyproject.toml 定義的入口點執行。

全局安裝（推薦）

ticket CLI 透過 cwd-resolving shim 安裝（非 uv tool install，ARCH-APP-002 / framework issue #12）。shim 依當前 cwd 所在專案的 git toplevel 解析 .claude/skills/ticket 源碼並 uv run，故源碼即時生效、不需 reinstall、多專案共用同名 skill 不碰撞。

# 首次安裝（一次安裝 ticket / doc / worktree 三個 shim）
python3 .claude/scripts/install-skill-clis.py

# 之後在任何目錄執行
ticket track summary
ticket track claim 1.0.0-W4-001

修改原始碼後無需重新安裝：shim 每次執行都 uv run 當前專案源碼，改動即時生效。（檢查是否已 shim 化：python3 .claude/scripts/install-skill-clis.py --check）

本地執行

(cd .claude/skills/ticket && uv run ticket track summary)

常用範例

ticket track summary                                    # 摘要
ticket track query 1.0.0-W4-001                       # 查詢
ticket track claim 1.0.0-W4-001                       # 認領
ticket track complete 1.0.0-W4-001                    # 完成（auto-stage：自動 git add ticket md + worklog md + cascade children，stdout 提示 commit 指令）
ticket track complete 1.0.0-W4-001 --no-stage         # 完成但跳過 auto-stage（保留用戶手動掌控 stage 範圍，W11-035）
ticket track complete 1.0.0-W4-001 --force            # 強制完成（旁路未完成 children 阻擋，W11-003.2）
ticket create --version 0.31.0 --wave 4 --action "實作" --target "XXX"  # 建立

subagent 派發時 claim 推薦用法

被派發的 subagent 認領自身 ticket 時，推薦使用 ticket track claim <id> --as <self-agent-name>（申報自身身份；不加 --verify）。

Why：claim --as <agent> 在認領時把 who.current 寫成執行者身份，使後續 complete --as <self> 與 identity-guard 對稱通過，無需 set-who 繞過（W2-018）。--as 在 file_lock 內與 status 寫入同一原子操作（load → modify → save），不執行 AC 驗證、不讀 stdin、不偵測 TTY，subagent 無 TTY 的互動環境受限完全無影響。--as 與 --verify 正交：--as 只設身份，不觸發任何驗證副作用。

為何需要 --as：建立 ticket 未指定 --who 時 who.current 預設為字面 "pending"。裸 claim（不帶 --as）不寫 who.current，後續 complete --as <agent> 因 "pending" != <agent> 被 identity-guard deny（情境 4），agent 須先 set-who 繞過。--as 從源頭消除此縫隙。裸 claim（不帶 --as）維持向後相容，仍可用，但收尾時須自行 set-who。

Consequence：若 subagent 改用 --verify（明示啟用 AC 自動驗證，僅供除錯場景），在無 TTY 環境下會觸發 fail-closed：未加 --yes 時直接 return 1 並印出「非互動環境且未指定 --yes，已取消」，subagent 可能誤判 ticket 未 claim 而重試或放棄。--verify 還會在 claim 時跑 AC 對應的驗證指令（如 npm test 全套件），造成同 wave 並行 claim 衝突（PC-078）。

Action：

| 場景 | 推薦命令 | 說明 | |------|---------|------| | subagent 認領被派發的 ticket（常態） | ticket track claim <id> --as <self-agent-name> | 設 who.current，後續 complete --as 對稱通過 identity-guard，免 set-who（W2-018） | | 不申報身份的裸認領（向後相容） | ticket track claim <id> | 不碰 who.current；收尾若需 complete --as 須自行 set-who | | 除錯時想 claim 並同時跑 AC 驗證 | ticket track claim <id> --verify --yes | --yes 在非互動環境短路驗證 prompt 為 y，避免 fail-closed | | 只想看 AC 驗證結果不 claim | ticket track verify <id> | 與 claim 解耦（W4-019 後 --skip-verify 已移除，改用此子命令） |

半成功歷史背景：早期 claim --yes 在 subagent 無 TTY 環境曾因互動受限出現 metadata 部分寫入、需 --skip-verify 二次嘗試確認的半成功狀態（W1-048.4.1 觀察）。此 root cause 已由 W3-046（claim 預設不驗證）+ W4-019（移除 --skip-verify）兩階段修正消除；現行裸 claim 路徑無此問題。

無子命令時的預設行為（dashboard-first，v2.7.0 起）

當用戶輸入 /ticket（無子命令或參數）時，依序執行以下流程：

取得接手聚合視圖 — 執行 ticket track dashboard --top 5

dashboard 一次回傳 [In Progress] + [Ready Top N] + [Stale Warning] 三章節，Ready 章節含可直接 claim 的編號 [1] [2] [N] 與 priority 標籤。設計目的：將 PM 接手流程從 W10-113 baseline 7 tool call 降至 2-3 tool call（W3-013 ANA 結論方向 a）。
- dashboard 有 in_progress 或 ready 任務 → 使用 AskUserQuestion 依 dashboard 順序列出選項：
  - in_progress 任務優先列出（label: [ip] {ticket_id} - {title}，description: 進行中（resume 接手））
  - Ready 任務依 dashboard [1] [2] [N] 編號順序列出（label: [{N}] {ticket_id} - {title}, description: [{priority}]）
  - 額外選項：「建立新 Ticket」（description: 執行 /ticket create）
  - 用戶選擇：
    - in_progress 任務 → ticket resume <selected_id>
    - Ready 任務 → ticket track claim <selected_id>
    - 建立新 Ticket → 引導進入 /ticket create 流程
  - 流程結束
- dashboard 無 in_progress 也無 ready → 進入步驟 2 fallback
Fallback：完整 pending/in_progress 清單（僅當步驟 1 dashboard 無結果時觸發） — 執行 ticket track list --status pending in_progress
- 有待辦任務 → 使用 AskUserQuestion 列出選項：
  - 各待辦任務作為選項（label: {ticket_id} - {title}, description: 狀態: {status}）
  - 額外選項：「建立新 Ticket」（description: 執行 /ticket create）
  - 用戶選擇既有任務 → 依狀態處理（pending → claim，in_progress → resume）
  - 用戶選擇「建立新 Ticket」→ 引導進入 /ticket create 流程
  - 流程結束
無任何待辦 → 顯示子命令總覽（下方表格）

完整待恢復清單檢視/除錯：可改用 ticket resume --list（子命令保留，獨立於 dashboard-first 流程）。 scheduler 接手建議單獨查詢：可改用 ticket track runqueue --context=resume --top 3（保留作除錯/腳本用途，但 PM 接手流程不再呼叫）。

統一命令格式

/ticket <subcommand> [options]

命令層級慣例：create / batch-create / show / handoff / resume / migrate / generate 是頂層命令（ticket create ...）；claim / complete / append-log / query / list / set-acceptance 等狀態操作在 track 之下（ticket track <op> ...）。常見誤打：ticket track create（錯，create 非 track 子命令）、ticket claim（錯，claim 在 track 下）。本標註僅說明既有慣例，零 CLI 行為變更（Never break userspace）。

子命令總覽

| 子命令 | 用途 | 範例 | | ------------------- | -------------------------- | -------------------------------------------------------------------------- | | create | 建立新 Ticket | /ticket create --version 0.31.0 --wave 1 --action "實作" --target "XXX" | | batch-create | 批次建立 Tickets | /ticket batch-create --template impl-parsley --targets "a,b,c" --wave 28 | | track | 追蹤 Ticket 狀態 | /ticket track summary | | track dashboard | PM 接手聚合視圖（W10-114） | ticket track dashboard --top 5 | | track list | 預設 top 10 priority 排序（W10-115） | ticket track list --status pending --top 20 | | track td-status | TD 清單校準（PC-094） | ticket track td-status 0.18.0-W10-017 | | track depth | 查詢嵌套深度與 can_descend（W1-056.8，沿 parent_id 鏈） | ticket track depth 1.0.0-W1-056.5 | | track parallel-check | 偵測子任務/兄弟 ticket 檔案衝突（W17-203.1，對齊 askuserquestion-rules 規則 7） | ticket track parallel-check 0.18.0-W17-203 | | track dispatch-validate | Context Bundle 自動填料合理性檢查（W17-003，C 方案安全網；exit 0=pass / 1=軟警告 / 2=硬失敗或 IO 錯誤；與 dispatch-check 的 exit code 語意不共享，需以命令名稱判別） | ticket track dispatch-validate 0.18.0-W17-003 | | track dispatch-readiness | 派發前認知負擔閾值檢查（W17-053；三項閾值：功能職責數 / 修改檔案數 / Context Bundle tokens；exit 0=pass / 1=軟警告 / 2=強制拆分或 IO 錯誤；與 dispatch-check / dispatch-validate 的 exit code 語意不共享；閾值 1 以 acceptance 條目近似，含驗證類條目時可能高估，PM 於 WARN/FAIL 應手動覆核——詳見 references/track-command.md） | ticket track dispatch-readiness 0.18.0-W17-053 | | show | 顯示 Ticket（含渲染） | ticket show W17-015 / ticket show W17-015 -r | | handoff | 任務交接 | /ticket handoff 1.0.0-W1-002 --to-sibling 1.0.0-W2-003 | | resume | 恢復任務 | /ticket resume <id> | | migrate | Ticket ID 遷移 | /ticket migrate 1.0.0-W4-001 1.0.0-W5-001 | | generate | Plan 轉換為 Tickets | /ticket generate plan.md --version 0.31.0 --wave 5 |

子命令詳細說明

各子命令的完整用法和參數說明，請參閱對應的 reference 檔案：

create - 建立新 Ticket

建立 Atomic Ticket，支援 5W1H 引導式建立、子 Ticket 建立、版本目錄初始化（init）。

版本歸屬引導（0.3.3-W1-001）：create 時根據 --type 和 --action 自動建議目標版本。新功能（IMP + 實作/新增/建立/開發）→ 大版本（0.x+1.0）；修復/改善/分析/文件 → 小版本（最新已完成版本 +1 patch）。未指定 --version 時自動套用建議；指定但與建議不符時輸出 WARNING（不阻擋）。

決策樹：Read references/workflow-create.md 詳細用法：Read references/create-command.md 血緣 vs 衍生：--parent vs --source-ticket 對比表見 references/create-command.md「--parent vs --source-ticket 對比表」章節（PC-073）重複偵測：Tier 1 警告層（相似度 >= 0.3，不阻擋）+ Tier 2 阻擋層（同窗口高相似度 exit 1，--allow-duplicate 旁路）；見 references/create-command.md「重複偵測（兩層防護）」章節（W1-040.1 冪等防護）

常用範例：

# 建立根任務（必須提供 decision-tree 三參數）
ticket create --version 0.2.0 --wave 2 --action "實作" --target "HTTP Handler" --type IMP \
  --decision-tree-entry "第五層:TDD" \
  --decision-tree-decision "Phase 3b 完成後建立重構 Ticket" \
  --decision-tree-rationale "quality-baseline-rule-5"

# 建立子任務（--parent 自動產生子序號，可省略 decision-tree 參數）
ticket create --parent "1.0.0-W2-001" --action "實作" --target "事件融合層"

# DOC 類型（可省略 decision-tree 參數）
ticket create --version 0.2.0 --wave 2 --action "撰寫" --target "工作日誌" --type DOC

# 多值參數格式
#   --acceptance：多次指定或用分隔符（vertical bar）分隔
ticket create ... --acceptance "條件A" --acceptance "條件B"
ticket create ... --acceptance "條件A|條件B|條件C"
#   注意（W3-089）：分隔符是 --acceptance 的多條拆分字元。
#   若 acceptance 內文本身需含該字元（如描述 shell pipe「-q | tail」），
#   用反斜線跳脫保留字面，避免被靜默拆條：
ticket create ... --acceptance "重現實證 -q \| tail 導致 0 行"
#   未跳脫時，單一 --acceptance 值被拆成多條會印出 [WARNING] 供確認。

#   --where：逗號分隔
ticket create ... --where "file1.py,file2.py"

#   --blocked-by / --related-to：逗號分隔
ticket create ... --blocked-by "1.0.0-W2-001.1,1.0.0-W2-001.2"

batch-create - 批次建立 Tickets

從模板 + 目標清單快速建立多個 Tickets。適用於大量同質任務場景（如 30 個實作子任務）。

邊界：batch-create 只建立 tickets，不派發 agents。多任務派發前先寫 dispatch-plan，保留每張 ticket 的獨立 prompt、commit policy 與 Exit Status；禁止把 batch-create 誤用為 batch dispatch CLI。

使用情境：

W28 場景：快速建立 30 個相同類型的實作任務
需要多個同質 Ticket，避免逐一手工填寫

命令格式：

# 基本用法
ticket batch-create --template impl-parsley --targets "目標1,目標2,目標3" --wave 28

# 指定版本
ticket batch-create --template impl-parsley --targets "a,b,c" --version 0.31.0 --wave 28

# 預演模式（只顯示摘要，不建立檔案）
ticket batch-create --template impl-parsley --targets "a,b,c" --dry-run

# 建立子任務
ticket batch-create --template impl-parsley --targets "a,b" --parent 1.0.0-W28-001

參數說明：

--template (必填)：使用的模板名稱（如 impl-parsley）
--targets (必填)：目標清單，逗號分隔（如 "BookCard Widget,LibraryListPage"）
--version (可選)：目標版本，預設自動偵測
--wave (可選)：Wave 編號，預設為 1
--parent (可選)：父 Ticket ID，用於建立子任務
--dry-run：預演模式，只顯示摘要不建立檔案

預定義模板：

impl-parsley：parsley-flutter-developer 實作 Ticket 模板（type: IMP, who: parsley-flutter-developer）
更多模板可在 ticket_system/templates/ 目錄中定義

詳細設計：參考評估報告（CLI 設計、使用者體驗、批次操作流程）

track - 追蹤和更新 Ticket 狀態

包含 READ 操作（summary/query/version/tree/chain/deps/full/log/list/board/agent/5W1H/validate/runqueue/dashboard/stale-list/td-status）和 UPDATE 操作（claim/complete/release/set-who/set-what/set-when/set-where/set-why/set-how/phase/check-acceptance/set-acceptance/append-log/add-child/batch-claim/batch-complete/audit/accept-creation）。list 支援 --wave、--status、--format、--top、--all 篩選參數（W10-115 預設 --top 10，priority 排序）。

Scheduler — runqueue（W17-011.1）：回答「下一個該做哪個 ticket」。Linux schedule()/runqueue/top/ps 類比。合併原 next+schedule+resume-hint 為單一命令。
ticket track runqueue --wave 17                    # 可執行清單（blockedBy=[] pending，priority 排序）
ticket track runqueue --wave 17 --format=dag       # 完整 DAG + 關鍵路徑高亮
ticket track runqueue --context=resume --top 3     # 與 handoff/pending 交集（接手建議）
新 session 啟動時 session-start-scheduler-hint-hook 自動呼叫 runqueue --context=resume，結果以 hook additionalContext 顯示。PM 迷失方向時優先執行，免靠記憶判斷先後順序。詳見 references/track-command.md「track runqueue 子命令」章節。

Dashboard — dashboard（W10-114 / W10-113 M1+M4'）：PM 接手新 session 的聚合視圖。一次回傳 [In Progress] + [Ready Top N] + [Stale Warning] 三章節，Ready 章節含可直接 claim 的編號 [1] [2] [3] 與 priority 標籤，免拼 ID。
ticket track dashboard                      # 預設：top 5 ready，stale 60min，text 格式
ticket track dashboard --top 10             # 擴大 ready 列數
ticket track dashboard --wave 10            # 限定 wave 範圍
ticket track dashboard --no-stale           # 隱藏 stale 章節
ticket track dashboard --stale-threshold 30 # 調整 stale 判定門檻（分鐘）
ticket track dashboard --format=json        # JSON 輸出（自動化用）
設計目的：將 /ticket 裸命令流程從 7 個 tool call（list + runqueue + stale + ToolSearch + AUQ + claim + read）降至 3 個（dashboard + claim by number + 後續動作）。詳見 references/track-command.md「track dashboard 子命令」章節。

Parallel-check — parallel-check（W17-203.1）：偵測目標 ticket 的 children（或同 parent 兄弟）pending 集合中，依 where.files 路徑前綴判斷哪些可平行派發、哪些互相衝突。輸出三章節（可平行派發 / 衝突任務 / 單獨派發）並對「可平行集合中 >= 3 個觸及 .claude/ 的 ticket」發出 PC-137 警告，輔助 PM 套用 .claude/pm-rules/askuserquestion-rules.md 規則 7。
ticket track parallel-check 0.18.0-W17-203   # 分析 W17-203 的 children pending 集合
路徑比較使用 pathlib.PurePosixPath（禁 string startswith）。共同祖先深度 >= 3 段視為弱衝突（如 .claude/skills/ticket/ 級）。exit code：0=分析成功 / 1=ticket 不存在或無 pending children / 2=ID 格式或 IO 錯誤。

List 預設行為 — list --top / --all（W10-115 / W10-113 M3）：list 預設 --top 10 並依 priority(P0>P1>P2>P3) → created → id 排序，避免 dump 全量 67+ 筆造成 PM 認知負擔。
ticket track list                            # 預設 top 10 by priority
ticket track list --top 20                   # 擴大列數
ticket track list --all                      # 取全量（覆蓋 --top；共存時 --all 優先並 emit warning）
ticket track list --format ids               # 純 ID 輸出（適合 pipe 到 xargs）
ticket track list --status pending --top 5   # 篩選 pending 且只取 top 5
--format 可選值：table（預設）/ ids（每行一個 ID，適合 pipe）/ yaml。詳見 references/track-command.md「track list 子命令」章節。

Stale ticket 明細 — stale-list（W17-200）：列舉 pending 且建立日期超過閾值的 ticket，補 list 命令僅顯示彙總計數無法定位個別 ticket 的缺口。
ticket track stale-list                           # 預設 --threshold warning（warning + critical）
ticket track stale-list --threshold info          # 三級全收（info + warning + critical）
ticket track stale-list --threshold all           # 同 info
ticket track stale-list --threshold critical      # 僅 critical
ticket track stale-list --wave 17 --format ids    # 僅輸出 ID（適合 pipe）
閾值複用 lib/staleness.py：info ≥ 7 天 / warning ≥ 14 天 / critical ≥ 30 天。輸出依 days 降序。table 格式另附 stale in-progress 章節（>= 24h，依 frontmatter started_at 單平面判定，附 ticket track release <id> 釋放提示）；ids/yaml 維持 pending-only 向後相容（1.5.0-W5-005.7）。詳見 references/track-command.md「track stale-list 子命令」章節。

TD 清單校準 — td-status（W10-083 / PC-094）：掃描指定 ticket 的 body 與 git commit 訊息，將 TD 編號分類為「已處理 / 無需處理 / 仍待處理」三狀態。用於 Phase 3a/3b/4 結束時即時校準 TD 清單，防止 Phase 4 評估時誤判已完成項（PC-094 根因）。
ticket track td-status 0.18.0-W10-017          # 校準指定 ticket 的 TD 清單
ticket track td-status 0.18.0-W10-017 --version 0.18.0  # 明確指定版本
輸出分三組：[已處理] / [無需處理] / [仍待處理]，pending TD 會附 PC-094 校準提示，建議於 body 標註或在 commit 訊息引用 TD 編號。呼叫時機：Phase 3a 策略文件完成後、Phase 3b commit 前、Phase 4 派發前。詳見 .claude/pm-rules/tech-debt.md「TD 清單即時校準（td-status）」章節。

注意：complete 在父 ticket 含未完成 children（非 terminal：pending / in_progress / blocked）時會以 exit 1 阻擋（W11-003.2）。提供 --force 旁路強制完成，會在 stderr 列出未完成 children 作為警告，cascade 解鎖機制仍會執行。建議優先完成 children 後再 complete 父 ticket。

注意：5W1H 欄位由 set-who ~ set-how 6 個命令更新。blockedBy 用 set-blocked-by、relatedTo 用 set-related-to（均支援 --add/--remove）、priority 用 set-priority。其餘 frontmatter 欄位無 CLI 命令，需手動編輯 frontmatter。完整對照表見 references/track-command.md。

注意：append-log 必須加上 --section 必填參數：ticket track append-log <id> --section "Problem Analysis" "內容"。有效區段值（SSOT：ticket_system/constants.py 的 CANONICAL_BODY_SECTIONS + Execution Log，共 10 章）：Task Summary、Problem Analysis、重現實驗結果、Solution、Test Results、Context Bundle、NeedsContext、Exit Status、Completion Info、Execution Log。body-schema 全必填章節（含 Completion Info）皆可經 append-log 寫入，不需 Edit 繞道。重現實驗結果 為 ANA type 必填章節（PC-063 / ticket-body-schema.md）。Context Bundle 用於派發前寫入 PCB（PC-040）；NeedsContext/Exit Status 用於代理人結束狀態協議（W17-010）。

Status precondition（W3-044 / W1-058）：append-log 要求 ticket status 為 in_progress（completed 亦放行，補 review 場景）。例外（W1-058）：派發前章節 Problem Analysis / Context Bundle 允許 pending 直寫——PM 依 PC-040 / PC-100 於 create 後立即寫入派發 context 屬合法 bookkeeping，不需 --force、不記 audit。其餘章節（Solution / Test Results / Execution Log 等執行產出）於 pending / blocked / closed 仍阻擋（status 失敗 exit 2）；--force 逃生閥行為與 hook-logs audit 紀錄不變。

副作用（W7-001）：append-log 寫入 body 後會 auto-commit 該 ticket md（精確路徑，commit message chore(<id>): append-log <section>）。Why：body 即時進 commit 歷史可使 git checkout -- <file> / git reset --hard / git stash 三種還原全失效，根除 W1-017「未 commit body 被 git 還原覆蓋回 placeholder」遺失問題。Consequence：每次 append-log 會新增一個 chore commit（碎 commit 為設計取捨，對 ticket md chore 類可接受）；body 無變更時 graceful skip 不產生空 commit。Action：非 git repo / index.lock 競爭 / commit 失敗時 append-log 仍 exit 0 + stderr 警告，body 保留 working tree 可手動 commit。不使用 --no-verify（維持 pre-commit hook 把關；ticket md 非 JS，lint-staged 無匹配）。

注意：check-acceptance 只接受單一 index（如 1）或 --all；不支援 1 2 3 多索引。一次勾選多項請改用 set-acceptance --check 1 2 3。先用 ticket track query <id> 查看驗收條件清單和編號。詳見 references/track-command.md「驗收條件操作詳解」（含決策樹 + 5 常見錯誤）。

注意：set-acceptance 是 check-acceptance 的明確語意版（：--check <index> / --uncheck <index>（可多個）、--all-check / --all-uncheck。禁止 subagent 直接 Edit frontmatter 的 acceptance 欄位。

注意：validate <id> 驗證 Ticket frontmatter 4 關鍵欄位（status/completed_at/acceptance/who）合規性，違規時給出建議修復命令。

身份申報（--as，W1-048）：complete / check-acceptance / set-acceptance 三個寫入命令支援選用 --as <agent-name>，與 ticket who.current 精確對照。Why：防 generic agent 收 Ticket ID 即越權收尾（PC-V1-002 前提一，W1-044 探針實證）。判定邏輯——--as 值 ≠ who.current（含空值）→ deny（exit 1，純前置檢查不寫入狀態）；--as rosemary-project-manager 一律放行（PM bookkeeping 豁免，如代收尾 / stale cleanup）；未提供 --as 僅 stderr 警告不阻擋（過渡期向後相容）。Action：subagent 收尾時帶自身身份，例 ticket track complete <id> --as thyme-python-developer；轉強制（無 --as 即阻擋）的 trigger 待獨立監測 ticket 評估。

注意：deps <id> 顯示衍生關係（spawned_tickets + source_ticket），與 tree/chain 純血緣語意（parent_id/children/chain）分離，對齊 Jira/Linear/GitHub 業界慣例（W15-004）。支援遞迴展開與循環引用防護（標記 CYCLE DETECTED）。用法：ticket track deps <ticket-id>。

注意：depth <id> 沿 parent_id 鏈計算嵌套深度（非 ID 字串數點，避免完整版本前綴 1.0.0-W1-056.5 含 3 個點被誤算為 depth 4 的 linux F1 fatal bug）。輸出 depth / max_depth（= MAX_TICKET_DEPTH=3）/ can_descend（depth < MAX_TICKET_DEPTH）。深度定義：根任務（parent_id: null）= depth 1，每往下一層 +1。用途：agent 自檢層級自覺（協議 v2 D3），無需上層 prompt 傳遞層級資訊。用法：ticket track depth <ticket-id>。

注意：create --parent <id> 時，若新子任務深度 >= MAX_TICKET_DEPTH（3）會 emit warning（不硬擋，留旁路）。深度同樣沿 parent_id 鏈計算（W1-056.5 協議 v2 D3）。此為嵌套派發深度上限的 CLI 強制層，使協議深度上限不只是文件建議。

六欄位語意 SSOT：parent_id / children / source_ticket / spawned_tickets / blockedBy / relatedTo 的權威定義、阻擋語意、用戶情境對照表、決策樹見 references/field-semantics.md。其他規則 / 方法論 / error-pattern 涉及這些欄位時應引用該檔，不重複定義。

派發前提示：當 ticket 是 group、含 children、含 spawned_tickets，或同輪會派 2+ agents 時，先在 Ticket Problem Analysis / Solution 寫 dispatch-plan。欄位使用 .claude/references/agent-dispatch-template.md：ticket / agent / files / deps / context source / commit policy / run mode。dispatch-plan 是 orchestration description，不是 batch dispatch CLI。

決策樹：Read references/workflow-execute.md 和 references/workflow-query.md 詳細用法：Read references/track-command.md

show - 顯示 Ticket 內容（含 Markdown 渲染）

終端閱讀專用。TTY 下自動以 glow/mdcat/bat 渲染；pipe 時自動降純文字，避免污染下游消費者。

ticket show 0.18.0-W17-015     # 完整 ID
ticket show W17-015            # 短 ID（自動補當前版本）
ticket show W17-015 -r         # 純文字（同 track full）
ticket show W17-015 -R bat     # 指定渲染器
ticket show W17-015 -P         # 停用分頁

短 flag：-r raw / -R renderer / -p pager / -P no-pager。完整說明 ticket show --help。

與 ticket track full <id> 差異：track full 永遠純文字（腳本友善，向後相容）；show 預設渲染（閱讀友善）。

handoff - 任務鏈管理與 Context 交接

支援自動判斷方向、指定交接到父/子/兄弟任務。五種交接情境。

設計原則：handoff = 純指針，禁含任務描述 / acceptance / 5W1H（這些屬 ticket md 範圍）。完整原則見 .claude/methodologies/handoff-design-principle-methodology.md。

--next <target-ticket-id> 子旗標（W17-164 / L2-A）：以絕對指向語意建立 handoff，直接寫入 target_ticket_id 欄位，讓下 session 從「該做的 ticket」（target）讀取，而非從 source + direction 間接推導。

ticket handoff --next <target-ticket-id> --from-ticket-id <source-id>

--next 與 --auto 互斥；產生的 JSON direction="context-refresh"、auto_generated=False。讀取端（GC / SessionStart hint / Stop hook / resume）優先讀 target_ticket_id，缺則 fallback 至 direction 後綴解析（向後相容，舊 JSON 不破）。

新增 --from-worklog 子命令（W17-083.2）：解析 worklog 最新交接段，提取 ticket ID 並批次補建 .claude/handoff/pending/<id>.json，修復「worklog 寫了但未執行 CLI」雙軌不同步缺口。搭配 stop-worklog-handoff-sync-check-hook（Stop event 偵測）形成自動防護。

ticket handoff --from-worklog [--worklog-path PATH] [--dry-run]

決策樹：Read references/workflow-handoff.md 詳細用法：Read references/handoff-command.md

resume - 恢復任務

從 handoff 檔案載入 context。SessionStart hook 提醒 → 用戶 /ticket 或 /ticket resume <id> 觸發。

決策樹：Read references/workflow-handoff.md 詳細用法：Read references/resume-command.md

migrate - Ticket ID 遷移

支援單一和批量遷移，自動更新所有 ID 引用和 chain 資訊。

決策樹：Read references/workflow-migrate.md 詳細用法：Read references/migrate-command.md

generate - Plan 轉換為 Tickets

從 Plan 檔案自動生成 Atomic Tickets（Plan-to-Ticket 轉換）。

詳細用法：Read references/generate-command.md

參考資料

| 資料 | 說明 | | ---------------------------------------- | ---------------------------------------- | | references/architecture.md | 目錄結構、共用模組設計、自動化分析功能 | | references/workflow-create.md | 建立流程決策樹 | | references/workflow-execute.md | 執行+更新+批量+完成流程決策樹 | | references/workflow-query.md | 查詢流程決策樹 | | references/workflow-handoff.md | 交接+恢復流程決策樹 | | references/workflow-migrate.md | ID 遷移流程決策樹 | | references/completeness-check.md | 指令完整性驗證（39 個指令/選項覆蓋狀態） | | references/ticket-lifecycle-details.md | Ticket 生命週期詳細規則 | | references/track-command.md | track 子命令；含 format_error() 雙路徑（legacy str / ErrorEnvelope 結構化）、ArgparseFormatErrorParser 業務 vs 語法錯誤分流、版本標記 __error_envelope_v1__（W17-008.5 group） |

Ticket Body Schema（type-aware）

不同 type 的 body 章節填寫要求：

| Section | ANA | IMP | DOC | | ---------------- | -------------- | ---- | ------------------ | | Problem Analysis | 必填 | 選填 | 選填 | | 重現實驗結果 | 必填（PC-063） | 免填 | 免填 | | Solution | 必填 | 選填 | 免填 | | Test Results | 選填 | 必填 | 免填 | | Completion Info | 必填 | 必填 | 必填（附變更摘要） |

ticket create --type ANA/IMP/DOC 會在 body 各章節插入  標註，指引填寫者。完整規則見 .claude/pm-rules/ticket-body-schema.md。

修改 source 後無需重新安裝（shim 化）

重要：本 skill 已改用 cwd-resolving shim（ARCH-APP-002 / framework issue #12），不再走 uv tool install。shim 每次執行都 uv run --directory .claude/skills/ticket 當前專案源碼，修改 source 後改動即時生效，無 stale installed 問題（取代舊 uv-tool-staleness-check-hook / ticket-reinstall-hook 機制）。

檢查 / 安裝指令：

# 安裝 / 更新 shim（一次安裝 ticket / doc / worktree）
python3 .claude/scripts/install-skill-clis.py

# 檢查是否已 shim 化（exit 0/1）
python3 .claude/scripts/install-skill-clis.py --check

Agent Skills: Ticket System v1.0

Install this agent skill to your local

Skill Files