Claude-Code-Workflow/status-reference.md

Issue System Status Reference

CCW Issue Management 状态管理参考手册

概述

CCW Issue 系统包含三个核心实体，每个实体有独立的状态定义：

实体	描述	存储位置
Issue	问题/任务	.workflow/issues/issues.jsonl
Queue	执行队列	.workflow/issues/queues/*.json
QueueItem	队列项（解决方案级别）	Queue 内的 solutions[] 数组

---

Issue 状态

类型定义: 'registered' | 'planning' | 'planned' | 'queued' | 'executing' | 'completed' | 'failed' | 'paused'

状态	含义	触发命令/场景
registered	已注册，待规划	ccw issue create, ccw issue init, ccw issue pull
planning	规划中	手动设置 ccw issue update <id> --status planning
planned	已规划，solution 已绑定	ccw issue bind <issue-id> <solution-id>
queued	已加入执行队列	ccw issue queue add <issue-id>, ccw issue retry
executing	执行中	ccw issue next
completed	已完成	ccw issue done <item-id>
failed	执行失败	ccw issue done <item-id> --fail
paused	暂停	手动设置 ccw issue update <id> --status paused

Issue 状态流转图

                                    ┌─────────────────────────────────────┐
                                    │                                     ▼
registered ──→ planning ──→ planned ──→ queued ──→ executing ──→ completed
                                          ▲           │
                                          │           ▼
                                          └─────── failed
                                                      │
                                                      ▼
                                                   paused (手动)

---

Queue 状态

类型定义: 'active' | 'completed' | 'archived' | 'failed' | 'merged'

状态	含义	触发命令/场景
active	活跃队列，可执行	创建队列时默认, ccw issue retry 重置
completed	已完成（所有项完成）	所有 QueueItem 状态为 completed
archived	已归档	ccw issue queue archive
failed	有失败项	有 QueueItem 失败且所有项已终止
merged	已合并到其他队列	ccw issue queue merge <source> --queue <target>

Queue 状态流转图

              ┌────────────────────────────────────────┐
              │                                        ▼
active ───────┼──────────────────────────────────→ completed ──→ archived
              │
              │         ┌───────────┐
              └────────→│  failed   │
                        └─────┬─────┘
                              │ retry
                              ▼
                           active

active ──────────────────────────────────────────→ merged

---

QueueItem 状态

类型定义: 'pending' | 'ready' | 'executing' | 'completed' | 'failed' | 'blocked'

状态	含义	触发命令/场景
pending	等待执行	创建队列项时默认, ccw issue retry 重置
ready	依赖满足，可执行	计算得出（非持久化），用于 DAG
executing	执行中	ccw issue next
completed	已完成	ccw issue done <item-id>
failed	失败	ccw issue done <item-id> --fail
blocked	被依赖阻塞	计算得出（非持久化），用于 DAG

QueueItem 状态流转图

pending ──→ executing ──→ completed
   ▲            │
   │            ▼
   └───────── failed (retry 重置)

注意: ready 和 blocked 是在 ccw issue queue dag 命令中动态计算的，不会持久化存储。

---

状态验证

系统内置状态验证函数，防止无效状态赋值：

// 常量定义
const VALID_QUEUE_STATUSES = ['active', 'completed', 'archived', 'failed', 'merged'] as const;
const VALID_ITEM_STATUSES = ['pending', 'ready', 'executing', 'completed', 'failed', 'blocked'] as const;
const VALID_ISSUE_STATUSES = ['registered', 'planning', 'planned', 'queued', 'executing', 'completed', 'failed', 'paused'] as const;

// 验证函数
validateQueueStatus(status: string): status is QueueStatus
validateItemStatus(status: string): status is QueueItemStatus
validateIssueStatus(status: string): status is IssueStatus

---

常用命令速查

状态查询

# 查看所有 Issue
ccw issue list

# 按状态筛选 Issue
ccw issue list --status planned,queued

# 查看队列状态
ccw issue queue

# 查看队列 DAG（含 ready/blocked 计算状态）
ccw issue queue dag

状态更新

# 更新 Issue 状态
ccw issue update <issue-id> --status <status>

# 从队列同步 Issue 状态为 queued
ccw issue update --from-queue

# 重试失败项（QueueItem → pending, Issue → queued, Queue → active）
ccw issue retry [issue-id]

执行流程

# 添加到队列 (Issue → queued, 创建 QueueItem → pending)
ccw issue queue add <issue-id>

# 获取下一个执行项 (QueueItem → executing, Issue → executing)
ccw issue next

# 标记完成 (QueueItem → completed, Issue → completed)
ccw issue done <item-id>

# 标记失败 (QueueItem → failed, Issue → failed)
ccw issue done <item-id> --fail --reason "error message"

---

状态对照表

操作	Issue 状态	Queue 状态	QueueItem 状态
创建 Issue	registered	-	-
绑定 Solution	planned	-	-
加入队列	queued	active	pending
开始执行	executing	active	executing
执行完成	completed	completed*	completed
执行失败	failed	failed*	failed
重试	queued	active	pending
归档队列	-	archived	-
合并队列	-	merged	-

*Queue 状态在所有项完成/失败后才会更新

---

相关文档

• Queue 命令详解
• Execute 工作流
• Plan 规划流程