# Ticket 生命週期 - 詳細參考

> 本文件包含 ticket-lifecycle.md 的格式規範、訊息模板、Hook 技術細節。
> 核心決策規則請見：@.claude/pm-rules/ticket-lifecycle.md

---

## 任務鏈後續步驟建議

當 Ticket 完成時，系統會自動分析任務鏈狀態並建議下一步。

### 分析優先級

| 優先級 | 情境 | 建議內容 |
|--------|------|---------|
| 1 | 有子 Ticket 可開始 | 「子 Ticket {id} 現在可以開始」 |
| 2 | 有被解除阻塞的 Ticket | 「{id} 的阻塞已解除」 |
| 3 | 有同層兄弟 Ticket | 「同層還有 {id} 待處理」 |
| 4 | 同 Wave 有其他 pending | 「同 Wave 還有 N 個待處理」 |
| 5 | 任務鏈全部完成 | 「任務鏈 {root} 全部完成」 |

### 輸出範例

```
============================================================
[任務鏈後續步驟建議]
============================================================

已完成: 1.0.0-W4-007.1
        [實作 track P0 功能]

任務鏈進度: 1/3 completed
   Root: 1.0.0-W4-007

建議下一步:
   1. 1.0.0-W4-007.2
      [實作 track P1 功能]
      原因: 阻塞已解除（blockedBy 1.0.0-W4-007.1 已完成）
      狀態: pending → 可認領
```

---

## 任務鏈 ID 格式

### 格式規範

| 類型 | 格式 | 範例 |
|------|------|------|
| 根任務 | `{版本}-W{波次}-{序號}` | `1.0.0-W3-002` |
| 子任務 | `{根ID}.{n}[.{n}...]` | `1.0.0-W3-002.1.1` |

### 正則表達式

```regex
# 完整匹配（支援無限深度）
^(\d+\.\d+\.\d+)-W(\d+)-(\d+(?:\.\d+)*)$
```

### 範例任務鏈

```
1.0.0-W3-002              # ticket-handoff 功能（根）
├── 1.0.0-W3-002.1        # chain_analyzer 模組
│   ├── 1.0.0-W3-002.1.1  # 問題修復
│   └── 1.0.0-W3-002.1.2  # 測試補充
├── 1.0.0-W3-002.2        # handoff_executor 模組
└── 1.0.0-W3-002.3        # 文件更新
```

### chain 欄位說明

| 欄位 | 類型 | 說明 |
|------|------|------|
| root | string | 任務鏈根 ID |
| parent | string/null | 直接父任務 ID |
| depth | number | 深度（根=0） |
| sequence | array | 序號路徑陣列 |

### 範例 chain 欄位

**根任務**（`1.0.0-W3-002`）：
```yaml
chain:
  root: "1.0.0-W3-002"
  parent: null
  depth: 0
  sequence: [2]
```

**子任務**（`1.0.0-W3-002.1.1`）：
```yaml
chain:
  root: "1.0.0-W3-002"
  parent: "1.0.0-W3-002.1"
  depth: 2
  sequence: [2, 1, 1]
```

---

## Ticket 建立格式範本

```markdown
---
id: {版本}-W{波次}-{序號}
title: {動詞} {目標}
type: IMP/RES/ANA/INV/DOC
status: pending
priority: P0/P1/P2
assignee: pending
created: {日期}
---

# {Ticket ID}: {標題}

## 目標
{目標描述}

## 驗收條件
- [ ] {條件1}
- [ ] {條件2}
```

---

## 驗收條件 4V 格式要求

驗收條件必須符合 4V 原則：**可驗證、可量化、可追溯、可記錄**。

| 要求 | 說明 | 範例 |
|------|------|------|
| 必須有編號 | 每個驗收項目都有編號 | `1.`, `2.`, ... |
| 必須有來源 | 引用設計文件或需求 | `SKILL.md L97` |
| 必須有確認方法 | 定義如何驗證完成 | `執行命令驗證輸出` |
| 禁止模糊詞彙 | 不可用「完成」「正常」「適當」 | 用具體描述取代 |

**標準格式（表格式）**：

```markdown
## Acceptance Criteria

| # | 項目 | 來源 | 確認方法 | 狀態 |
|---|------|------|---------|------|
| 1 | {項目描述} | {來源引用} | {確認方法} | [ ] |
| 2 | {項目描述} | {來源引用} | {確認方法} | [ ] |
```

> 完整規範：@.claude/methodologies/acceptance-criteria-methodology.md

---

## Ticket 有效性驗證

### 有效 Ticket 定義

有效的 Ticket 必須滿足以下條件：

| 條件 | 說明 | 驗證方式 |
|------|------|---------|
| 決策樹欄位 | 包含 `decision_tree_path` 欄位 | YAML frontmatter 檢查 |
| 或決策樹區段 | 包含「## 決策樹路徑」Markdown 區段 | 內容檢查 |

### 驗證時機

| 時機 | 驗證者 | 動作 |
|------|-------|------|
| 建立 Ticket | /ticket create | 自動要求填寫決策樹欄位 |
| 派發任務 | agent-ticket-validation-hook | 阻止使用無效 Ticket |
| 認領 Ticket | /ticket track claim | 確認 Ticket 有效性 |

### 無效 Ticket 處理

無效 Ticket（缺少決策樹欄位）：
- 無法用於 Task 派發（被 Hook 阻止）
- 需要補充決策樹欄位才能使用
- 建議使用 /ticket create 重新建立

### 補充決策樹欄位

如果 Ticket 缺少決策樹欄位，可手動補充：

1. **YAML 格式**（在 frontmatter 中）：

```yaml
decision_tree_path:
  entry_point: "第X層"
  decision_nodes:
    - layer: "X"
      question: "決策問題"
      answer: "答案"
      next_action: "下一步"
  final_decision: "最終決策"
  rationale: "決策理由"
```

2. **Markdown 格式**（在內容中）：

```markdown
## 決策樹路徑

### 進入點
- **層級**: 第X層
- **觸發條件**: ...
```

---

## 驗收前置條件檢查流程

> **重要**：在執行驗收前，系統會先驗證 Ticket 狀態是否適合驗收。

```
觸發驗收流程
    |
    v
Step 1: 載入 Ticket
    |
    +-- 找不到 --> [Error] 錯誤訊息，exit 1
    |
    v
Step 2: 驗證狀態
    |
    +-- pending --> [Error] 阻止「尚未被接手」，exit 1
    +-- blocked --> [Error] 阻止「被阻塊」，exit 1
    +-- completed --> [Info] 已驗收完成，exit 0
    +-- in_progress --> 繼續檢查
    |
    v
Step 3: 驗收條件預檢查
    |
    +-- 有未完成項 --> [Warning] 提示執行者補齊，不阻止派發
    |
    v
Step 4: 檢查執行日誌
    |
    +-- 有未填寫區段 --> [Warning] 列出未填寫區段，建議執行者補充
    |
    v
[OK] 可以開始驗收，派發驗收代理人
```

---

## acceptance-gate-hook 技術細節

**Hook 檔案**：`.claude/hooks/acceptance-gate-hook.py`

**Hook 類型**：PreToolUse

**觸發時機**：`/ticket track complete` 命令執行前

**檢查邏輯**：

| 情景 | 檢查項目 | 結果 | 行為 |
|------|---------|------|------|
| 根任務 | 所有子任務是否 completed/closed？ | 否 | 阻止（exit 2） |
| 根任務 | 所有子任務是否驗收？ | 否 → 有未驗收子任務 | 警告（exit 0） |
| 子任務 | 是否已通過驗收？ | 否 | 阻止（exit 2） |
| 根任務 | 是否已通過驗收？ | 否 | 阻止（exit 2） |

> 「父 complete 需子全部 completed/closed」原則見 `.claude/methodologies/atomic-ticket-methodology.md` 任務鏈核心哲學 + `.claude/methodologies/ticket-lifecycle-management-methodology.md` 父 complete 前置條件。

**阻止場景**（exit 2）：

```
Ticket {id} 尚未通過驗收

檢查結果：
- 尚未派發 acceptance-auditor 驗收
- 驗收代理人尚未完成驗收

正確流程：
1. 派發 acceptance-auditor 執行驗收（完整或簡化）
2. 驗收通過後再執行 /ticket track complete

詳見：ticket-lifecycle.md 驗收代理人流程
```

**警告場景**（exit 0，允許繼續但提示）：

```
警告：Ticket {id} 有子任務尚未驗收

子任務狀態：
- {child-id-1}: pending 驗收
- {child-id-2}: 已驗收

建議：考慮等待所有子任務驗收後再完成根任務
（允許繼續，但可能影響整體品質）
```

**Hook 註冊**（`.claude/settings.json`）：

```json
{
  "hooks": {
    "acceptance-gate-hook": {
      "type": "PreToolUse",
      "tools": ["ticket_track_complete"],
      "enabled": true,
      "fail_mode": "block",
      "description": "驗收狀態檢查"
    }
  }
}
```

### 驗證結果對應表

| 情境 | 驗證結果 | 訊息類型 | Exit Code |
|------|---------|---------|-----------|
| Ticket 不存在 | 阻止 | Error | 1 |
| 狀態為 pending | 阻止 | Error（提示先 claim） | 1 |
| 狀態為 blocked | 阻止 | Error | 1 |
| 狀態為 completed | 允許（友好提示） | Info | 0 |
| 驗收條件未全部完成 | 阻止 | Error（列出未完成項） | 1 |
| 正常完成 | 允許 | OK | 0 |

---

## 驗收提示訊息模板

### IMP/ADJ/複雜/安全任務

```
============================================================
[驗收派發提示]
============================================================

Ticket {id} 類型為 {type}，需派發 acceptance-auditor 執行驗收。

依據 ticket-lifecycle 規則：
- 所有 Ticket 都必須驗收（契約原則）
- 驗收必須在 /ticket track complete 之前執行
- IMP/ADJ/複雜/安全任務由 acceptance-auditor 執行完整驗收
- DOC/簡單任務由 acceptance-auditor 執行簡化驗收
- PM 審核驗收報告並做最終決策

正確流程：
1. PM 派發 acceptance-auditor 執行驗收
2. 驗收通過後，才能執行 /ticket track complete
3. 如驗收失敗，由執行者修正後重新驗收

============================================================
```

### DOC/簡單任務

```
============================================================
[驗收派發提示]
============================================================

Ticket {id} 為 DOC/簡單任務，需派發 acceptance-auditor 執行簡化驗收。

簡化驗收檢查項目：
- [ ] Ticket 結構完整性（必填欄位齊全）
- [ ] 所有驗收條件已完成
- [ ] 執行日誌已填寫

正確流程：
1. PM 派發 acceptance-auditor 執行簡化驗收
2. acceptance-auditor 產出驗收報告
3. PM 審核報告並做最終決策
4. 驗收通過後執行 /ticket track complete 更新狀態

============================================================
```

### complete 前的驗收狀態檢查

```
============================================================
[驗收狀態檢查]
============================================================

執行 /ticket track complete 前的檢查：

[Error] Ticket {id} 尚未驗收
- 原因: 未通過驗收代理人檢查
- 建議: 先派發驗收代理人執行驗收
- 類型: {type}

[Warning] Ticket {id} 子任務尚未全部驗收
- 原因: 有 N 個子任務未驗收
- 建議: 先完成子任務驗收

詳見: ticket-lifecycle.md

============================================================
```

---

## P0 緊急任務處理

P0 緊急任務可「先完成後補驗收」，這不是豁免，而是時間順序調整：

```
P0 緊急任務
    |
    v
執行者完成工作（優先響應）
    |
    v
標記「待補驗收」
    |
    v
[後續] PM 派發驗收（24 小時內）
    |
    v
驗收完成 → 正式完成
```

**P0 待補驗收記錄格式**：

```markdown
### P0 待補驗收
- **完成時間**: {時間}
- **補驗收期限**: {完成時間 + 24 小時}
- **狀態**: 待驗收 / 已驗收
```

---

## 簡化驗收檢查清單

acceptance-auditor 對 DOC 類型或簡單任務進行簡化驗收時，必須確認：

- [ ] Ticket 結構完整性（必填欄位齊全）
- [ ] 所有驗收條件已完成
- [ ] 執行日誌已填寫（非佔位符）
- [ ] 無遺漏項目

**簡化驗收記錄格式**：

```markdown
### 簡化驗收記錄
- **驗收者**: acceptance-auditor
- **驗收類型**: 簡化驗收
- **驗收時間**: {時間}
- **驗收結論**: 通過
```

---

## 與其他流程的整合

### 與 TDD 流程整合

Phase 0~4 Ticket 按順序執行：SA 審查 → 功能設計 → 測試設計 → 策略規劃 → 實作執行 → 重構優化

> 詳細流程：@.claude/pm-rules/tdd-flow.md

### 與事件回應流程整合

incident-responder 分析 → 建立錯誤修復 Ticket → 派發對應代理人

> 詳細流程：@.claude/pm-rules/incident-response.md

### 與技術債務流程整合

Phase 4 發現技術債務 → 記錄到工作日誌 → /tech-debt-capture → 建立技術債務 Ticket

> 詳細流程：@.claude/pm-rules/tech-debt.md

### 與建議追蹤流程整合

調查/分析報告產生建議 → 記錄到 Suggestion Tracking → 處理每個建議（採納/拒絕/延後） → 採納的建議轉為驗收條件

> 詳細規範：@.claude/methodologies/suggestion-tracking-methodology.md

#### 建議追蹤狀態

| 狀態 | 說明 | 要求 |
|------|------|------|
| pending | 待決定 | 必須在任務執行前處理 |
| adopted | 採納 | 必須轉為驗收條件 |
| rejected | 拒絕 | 必須記錄拒絕理由 |
| deferred | 延後 | 必須記錄目標版本 |

#### 建議追蹤格式

```markdown
## Suggestion Tracking

### 來源：{來源文件}

| # | 建議內容 | 狀態 | 決定理由 | 對應 AC | 決定者 | 決定時間 |
|---|---------|------|---------|--------|--------|---------|
| 1 | {內容} | adopted | {理由} | AC-001 | PM | 2026-01-30 |
```

---

## 變更日誌

- v4.0.0 (2026-02-06): 瘦身重構 - 移出至 details 參考文件
  - 從 ticket-lifecycle.md 移出格式規範、訊息模板、Hook 技術細節
  - 精簡版保留核心決策規則
  - 本文件作為詳細參考
- v3.1.0 (2026-02-03): 統一驗收派發規則，移除 PM 直接驗收
- v3.0.0 (2026-02-03): 將驗收流程從 complete 之後改為 complete 之前
- v2.9.0 (2026-02-03): 新增執行日誌驗證機制
- v2.8.0 (2026-02-01): 取消驗收豁免機制，改為契約式驗收
- v2.7.0 (2026-02-01): 強化驗收代理人派發要求
- v2.6.0 (2026-01-31): 新增任務層級判斷規則
- v2.5.0 (2026-01-30): 新增階段-標準流程對照表和任務鏈後續步驟建議
- v2.4.0 (2026-01-30): 新增建議追蹤流程整合章節
- v2.3.0 (2026-01-30): 新增驗收條件格式要求章節
- v2.2.0 (2026-01-29): 新增任務鏈 ID 格式章節
- v2.1.0 (2026-01-27): 新增 Ticket 有效性驗證章節
- v2.0.0 (2026-01-23): 重構為 TDD 含 SA 前置審查流程版本

---

**Last Updated**: 2026-02-06
**Version**: 4.0.0 (從 ticket-lifecycle.md 移出)
