npm - @namewta/speculo - Versions diffs - 0.3.0 → 0.3.2 - Mend

@namewta/speculo 0.3.0 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (149) hide show

package/template/workflows/specdev/T-tickets/T-tickets.md CHANGED Viewed

@@ -3,206 +3,219 @@ id: specdev/tickets
 type: workflow-entry
 workflow: specdev
 name: 拆分 Tickets
-description: 将 spec 或计划拆分为一组曳光弹式垂直切片 tickets，每个声明阻塞边，持久化到变更目录。支持宽重构的扩展-收缩排序。
-keywords: [tickets, 拆分, 任务, 垂直切片, 阻塞, 曳光弹]
+description: 将 Spec、计划或已确认对话拆成曳光弹式垂直切片；每个 Ticket 决策完备、可独立验证、适配单一上下文，并建立阻塞 DAG、路径所有权和执行就绪门禁。
+keywords: [tickets, 拆分, 垂直切片, 阻塞, 曳光弹, decision-complete, readiness]
 ---
 # 拆分 Tickets
-将 plan、spec 或对话拆分为一组 **tickets** —— 曳光弹式垂直切片，每个 ticket 声明**阻塞**它的那些 tickets。
+Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、范围、公共契约、关键顺序和验收上的关键决策，但不展开逐行代码、局部变量或可从现有惯例自然推导的实现细节。
-## 流程
-### 1. 收集上下文
-基于对话上下文中已有的内容进行工作。如果用户将某个引用（spec 路径或其他标识）作为参数传入，拉取它并读取其完整内容。
-主要输入来源：
-- 如果已有 spec，读取 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` —— 这是 ticket 拆分的首要依据。
-- 读取 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 了解本 change 的架构决策——ticket 不应与已做出的决策冲突。
-- 读取 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 了解本 change 的领域词汇表。
-- 读取 `<Path>{roots.state}/specdev/adr/</Path>` —— 已确认并提升到永久的架构决策，始终反映项目当前架构现状。
-- 读取 `<Path>{roots.state}/specdev/context/</Path>` —— 已确认并提升到永久的领域词汇表，始终反映项目当前领域术语现状。
-如果尚未有 spec，可以基于对话中的计划或待办列表进行拆分，但优先建议用户先运行 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>` 产出 spec 以获得更精确的拆分。
-**完成标准**：上下文（spec、对话、代码库）已收集，所有必要输入源已读取。
+本 work 保留原有能力：代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。
-### 2. 探索代码库
+## 输入
-如果尚未探索代码库，进行探索以了解代码的当前状态。Ticket 标题和描述应使用项目的领域词汇表，并尊重所涉及区域的 ADR。
+优先读取：
-寻找预重构（prefactor）的机会，使实现更简单。"让变更变容易，然后做容易的变更。"
+- 当前 Spec：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前设计日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- Bug 诊断：`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- 永久架构决策：`<Path>{roots.state}/specdev/adr/</Path>`
+- 永久领域上下文：`<Path>{roots.state}/specdev/context/</Path>`
+- 项目当前代码、测试、配置、schema 和 CI 事实。
-具体做法：
-- 识别即将被修改的模块——它们的接口是否清晰？依赖是否合理？
-- 如果某个模块的当前结构会使后续实现变得复杂，先提出一个重构 ticket，放在功能 tickets 之前。
-- 预重构必须独立有价值——不是为了"更干净"而重构，而是为了"让后续变更更安全/更简单"。
+若尚无 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`，只有在用户提供的计划或对话已经等价覆盖目标、范围、关键决定和可判定验收时才可继续；否则建议先运行 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`。
-若探索中遇到不熟悉的模块、外部依赖或第三方库——其接口设计意图和行为特征尚不明确——调用 `<Path>{roots.workflows}/specdev/common/research/SKILL.md</Path>` 完成探查后再继续识别预重构机会。
-**完成标准**：代码库已探索，预重构机会已识别，领域词汇表和 ADR 已纳入考量。
+## 流程
-### 3. 草拟垂直切片
+### 1. 输入预检
-将工作拆分为**曳光弹** tickets。每个切片横向切穿每一层（schema、API、UI、测试），是一条窄但**完整**的路径——是垂直切片，不是某一层的水平切片。
+1. 读取所有存在的上游工件；
+2. 检查 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 的 `ready_for_tickets`；
+3. 按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 处理 Spec、ADR、用户决定与代码事实的冲突；
+4. 将未知项分类为可发现事实、高影响用户决定和低影响实现细节；
+5. 高影响未决问题没有关闭时停止，不通过更详细的 Ticket 文字伪装决策完备。
-垂直切片规则：
-- 一个完成的切片可以独立演示或验证——用户可以感知到它交付的行为
-- 每个切片的大小适配单个全新上下文窗口——一个 agent 会话可以在不间断的情况下完成它
-- 任何预重构应最先完成——它们解除后续 tickets 的阻塞
+**完成标准**：拆分依据、权威顺序、合同范围与未决问题已明确。
-为每个 ticket 标注其**阻塞边** —— 即必须在它开始之前完成的其他 tickets。没有阻塞边的 ticket 可以立即开始。
+### 2. 探索代码库与实现地形
-**宽重构是垂直切片的例外。** **宽重构**是指一个机械性变更 —— 重命名字段、修改共享符号的类型 —— 其**影响范围**辐射整个代码库，因此单次编辑会破坏数千个调用点，任何垂直切片都无法以绿色状态落地。不要强行将其塞入曳光弹；应将其排序为**扩展-收缩**序列：
+如果尚未探索，进行只读探索：
-1. **扩展**：在旧形式旁边添加新形式，使一切不中断。旧代码仍然工作，新代码可用但尚未被调用。
-2. **分批迁移调用点**：按影响范围分批（按包、按目录），每批是一个由扩展阶段阻塞的独立 ticket。保持 CI 逐批绿色，因为旧形式仍然存在。
-3. **收缩**：当没有调用方残留时删除旧形式，由一个由所有迁移批次阻塞的 ticket 负责。
+- 找到行为入口、稳定接口、测试接缝、数据流和错误路径；
+- 查找相邻或类似实现，优先复用项目现有模式；
+- 识别可能修改的模块、公共路径、共享文件、迁移索引和全局注册点；
+- 查找现有测试命令、夹具、类型检查、构建和 CI 门禁；
+- 对照 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 使用项目领域词汇；
+- 对照 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>` 避免重新争论已接受决策。
-当连批次本身都无法独立保持绿色时，保持排序不变，但让它们共享一个集成分支，所有批次共同阻塞一个最终的集成验证 ticket —— 绿色仅在该处得到承诺。
+遇到不熟悉的模块、外部依赖或第三方库时，使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`，再继续拆分。
-**完成标准**：曳光弹式垂直切片已草拟，每个 ticket 的阻塞边已标注。
+#### Prefactor
-### 4. 与用户核对
+遵循“让变更变容易，然后做容易的变更”：
-以编号列表形式呈现提议的拆分方案。对于每个 ticket，展示：
+- 如果当前接口、依赖或接缝会使后续实现明显不安全或重复，提出前置 prefactor Ticket；
+- prefactor 必须说明它解除的具体阻碍；
+- prefactor 必须独立有价值且可验证；
+- 不为了“更干净”而创建与目标无关的重构 Ticket。
-- **标题**：简短的描述性名称
-- **被阻塞于**：必须首先完成的其他 tickets（如有），或"无 —— 可立即开始"
-- **它交付什么**：此 ticket 使哪些端到端行为可用，从用户视角描述
+**完成标准**：实现地形、稳定接缝、共享路径与必要 prefactor 已识别。
-询问用户：
+### 3. 草拟曳光弹式垂直切片
-- 粒度是否合适？（太粗 —— 一个 ticket 内塞了太多决策，难以在一个会话内完成；太细 —— ticket 之间没有实质性行为差异）
-- 阻塞边是否正确 —— 每个 ticket 是否只依赖于真正阻碍它的 tickets？是否有不必要的阻塞关系？
-- 是否有 tickets 应合并或进一步拆分？
+加载 `<Path>{roots.workflows}/specdev/T-tickets/decomposition-rules.md</Path>`。每个切片应横向穿过交付该行为所需的最小层次组合，而不是把数据库、后端、前端和测试拆成互相无价值的水平 Ticket。
-迭代直到用户批准拆分方案。每次修改后重新展示完整列表。
+每个 Ticket 必须：
-**完成标准**：用户已确认粒度、阻塞边与合并/拆分方案。批准后，tickets 将写入 `ticket/` 目录（一个 ticket 一个独立文件，命名为 `NN-<name>.md`），并生成 `tickets-map.md` 作为总体地图和执行清单。
+- 交付一个可观察行为，或一个能独立解除后续阻塞的安全准备能力；
+- 完成后可以独立演示、测试或验证；
+- 适合一个全新 Agent 上下文在不中断的情况下完成；
+- 与其他 Ticket 有实质行为差异；
+- 只依赖真正阻止它开始的前置产物；
+- 自带至少一种完成证据。
-### 5. 发布
+#### 宽重构例外
-将已批准的 tickets 写入变更目录，**每个 ticket 一个独立文件**，并生成总体地图文件。按以下三步执行：
+字段重命名、共享符号类型变化、协议升级等宽机械变更无法安全塞入单个垂直切片时，按以下顺序：
-**5a. 创建 ticket 目录**
+1. **Expand**：在旧形式旁增加新形式，保持旧调用方可工作；
+2. **Migrate batches**：按包、目录、消费者或风险分批迁移，每批独立成 Ticket；
+3. **Contract**：确认旧调用点为零后删除旧形式；
+4. 若迁移批次无法各自保持绿色，使用隔离集成分支和最终集成验证 Gate，但仍保留明确的批次与责任边界。
-创建 `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>` 目录。
+**完成标准**：每个 Ticket 的可观察产出、真实阻塞边和验证方式已草拟。
-**5b. 写入单个 ticket 文件**
+### 4. 判定规划深度与风险
-按依赖顺序（无阻塞者在前，被阻塞者在后），为每个 ticket 创建独立文件 `<Path>{roots.state}/specdev/changes/{change}/ticket/NN-<ticket-name>.md</Path>`。`NN` 为 ticket 编号（两位零填充阿拉伯数字：`01`, `02`, ..., `10`, ...），代表执行顺序。文件名与编号均不含 `#` 字符，避免 Markdown 链接被编码为 `%23`。
+按 `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>` 为每个 Ticket 标注：
-每个 ticket 文件按以下模板填写：
+- `lite`：局部、可逆、沿用既有模式、无公共契约或迁移影响；
+- `standard`：大多数多文件或跨层垂直切片；
+- `deep`：公共 API/schema、数据迁移、安全/隐私/资金、不可逆操作、expand-contract、共享核心路径、多 Agent 或高事故半径。
-```markdown
-# Ticket NN: <标题>
+规划深度不是优先级，也不是 Gate。每个 Ticket 必须记录触发该深度的原因。
-- **被阻塞于：** `./ticket/NN-<name>.md`, `./ticket/NN-<name>.md`（相对路径，或多个用逗号分隔。无阻塞则写"无 —— 可立即开始"。查看被引用 ticket 文件中的状态字段自行判断是否已就绪）
-- **状态：** 未开始
+### 5. 写成决策完备 Ticket
-<!-- 如需了解整体上下文、所有 ticket 的依赖关系全景或横切关注点，请查看 `../tickets-map.md`。 -->
+使用 `<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>` 填写：
-## 战略与背景
+- 战略目标、可观察产出与来源追踪；
+- 当前代码事实和需求差距；
+- 已锁定决策、低影响假设和未决问题；
+- IN / REUSE / OUT；
+- 用户或调用者视角的端到端行为；
+- Standard/Deep 的接口、输入输出、不变量、数据流、失败与兼容契约；
+- 有序执行路线和安全落点；
+- expected、writable、read-only、shared 路径；
+- 正常、失败和回归验证矩阵；
+- 用户界面交互受影响时的 Lead E2E Gate；
+- Deep 的迁移、兼容窗口、监控、回滚和不可逆批准点；
+- 可判定验收标准。
-<!-- [必填] 本 ticket 的战略上下文。 -->
+路径所有权必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`，证据设计必须遵守 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
-- **本 ticket 战略**：一句话——本 ticket 做什么 + 为什么 + 以什么为基础（新建/复用现有模块）
-- **与该 ticket 相关的已确认决策**：逐条列出与本 ticket 范围相关的已拍板决策（从 ADR、spec 或对话中提取），防止实现时重新扯皮
-- **与该 ticket 相关的当前现状**：逐条列出与本 ticket 相关的、与需求不符的现有代码/行为。格式：文件路径 + 当前行为 + 为何不满足需求。可附近似行号作定位提示，不作承诺——实施时以现场代码为准
-- **该 ticket 的预期产出**：完成后可观察到的行为变化
+### 6. 构建依赖 DAG、合同覆盖与并发检查
-## 范围边界
+1. 使用 Ticket ID 建立 `blocked_by`；
+2. 检测循环和不存在的引用；
+3. 识别根 Ticket、汇合点、扇出与收缩点；
+4. 为每个 Spec 验收合同映射至少一个 Ticket；
+5. 检查并行候选的 `writable_paths` 是否相交；
+6. 共享路径必须指定唯一 owner，通常由 Lead 或专门 Ticket 修改；
+7. 不得用依赖边表达“可能更方便”或纯粹的人员交接。
-| IN（本 ticket 构建） | REUSE（复用现有，不改动） | OUT（本 ticket 明确不做） |
-|---------------------|-------------------------|-------------------------|
-| ...                 | ...                     | ...                     |
+使用 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` 草拟总体 Map。
-## 要构建什么
+### 7. Definition of Ready
-<从用户视角描述此 ticket 交付的端到端行为。用户能做什么、看到什么变化。不是逐层实现清单。一到三段。>
+加载 `<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>` 逐个检查。
-## 交付物
+存在以下任一情况时 `ready: false`：
-<!-- 本 ticket 产出的文件/模块/功能。新增文件标 **新增**，重度重构标 **重构**。 -->
+- 会改变行为、接口、数据、兼容、安全、范围或验收的未决问题；
+- 依赖缺失或 DAG 有环；
+- 可写路径不明确或并行所有权冲突；
+- 验证方法不能执行且没有批准的替代证据；
+- 单个新上下文无法完成；
+- Standard/Deep 缺少有序执行路线；
+- Deep 缺少迁移、兼容、监控、回滚或批准点。
-- **新增** path/to/new.ts —— 描述
-- 修改 path/to/existing.ts —— 改动内容
+### 8. 与用户核对
-## 需阅读的文件
+以完整编号列表展示所有 Ticket，至少包含：
-<!-- 可选：仅当 ticket 涉及非显而易见的代码区域时填写。简单 ticket 可省略整个小节。 -->
+- 标题；
+- 可观察交付；
+- 被阻塞于；
+- Planning Depth 与触发原因；
+- 风险；
+- Ready 状态；
+- 关键未决问题；
+- 预计并行组和共享路径 owner。
-| 文件 | 目的 |
-|------|------|
-| path | 为何需要阅读 |
+核对：
-## 保留/不动
+- 粒度是否适合单一上下文；
+- 是否出现水平切片；
+- 阻塞边是否真实；
+- 是否应合并、进一步拆分或增加 prefactor；
+- 合同是否全部覆盖；
+- 路径所有权和验证是否可信。
-<!-- 本 ticket 绝对不能碰的代码、契约或数据。无则写"无"。 -->
+每次修改后重新展示完整列表，直到用户批准。用户明确要求一次性自主规划且不存在高影响未知项时，可使用推荐默认值并把假设写入 Ticket，不为形式重复询问。
-## 实现要点
+### 9. 发布
-<!-- 可选：3-7 条关键技术决策。简单 ticket 可省略整个小节。 -->
+创建：
-1. 关键技术点
-2. 关键技术点
+- Ticket 目录：`<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- Tickets Map：`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- Evidence 目录：`<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
-## 验收标准
+按拓扑顺序写入 Ticket：
-- [ ] 可验证的验收条件
-- [ ] 可验证的验收条件
+```text
+<Path>{roots.state}/specdev/changes/{change}/ticket/NN-<ticket-name>.md</Path>
 ```
-**模板填写说明：**
-- **被阻塞于**使用指向 `./ticket/` 目录的相对路径（如 `./ticket/01-auth.md`），多个用逗号分隔。执行者应自行打开被引用的 ticket 文件查看其状态字段，判断阻塞是否已解除
-- **状态**初始固定为"未开始"；实现者开始工作时改为"进行中"，完成后改为"已完成"
-- **战略与背景**是必填段——为执行者提供该 ticket 的决策锚点和当前现状。从 spec、ADR、对话中提取，不确定的标记 `[待确认]`
-- **范围边界**是必填段——明确本 ticket 的 IN/REUSE/OUT 三列，防止范围蔓延。OUT 列吸收"明确不做"的内容
-- **交付物**列出本 ticket 产出的具体文件——新增标 **新增**，修改不标，重构标 **重构**。让执行者明确知道要动哪些文件
-- **需阅读的文件**仅在涉及非显而易见的代码区域时填写——告诉执行者上下文边界
-- **保留/不动**是本 ticket 的安全边界——显式列出不能碰的代码/契约/数据。无则写"无"
-- **实现要点**仅在 ticket 涉及有意义的架构决策时填写（3-7 条）。简单 ticket 省略
-- **验收标准**使用 `- [ ]` checklist 格式，每条具体、可独立验证。优先写可执行命令，其次写手动检查步骤
-- 描述统一使用深层模块设计词汇：模块/接口/接缝/适配器，而非组件/服务/边界
+`NN` 使用两位或更多位零填充数字；Ticket frontmatter ID 使用 `T-NN`。Ticket 的 `blocked_by` 使用 Ticket ID，而不是相对文件路径。
-避免在 ticket 文件中写入绝对路径；行号仅作近似定位提示，不作承诺。例外：如果原型产生了一个代码片段，它比文字更精确地编码了一个决策（状态机、reducer、schema、类型结构），将其内联并简要注明来自原型。精简到富含决策的部分 —— 不是可运行的演示，只是关键部分。
+使用 `<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>` 和 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` 生成工件，并对照：
-**5c. 写入 tickets-map.md**
+- `<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
+- `<Path>{roots.workflows}/specdev/common/schemas/tickets-map.schema.json</Path>`
-创建 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`，作为所有 ticket 的总体地图和执行看板。格式遵循权威模板 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`——加载该模板获取完整的节结构、表格列定义和填写约定。
+运行：
-T-tickets 阶段填写的列：**编号**、**Ticket**、**被阻塞于**、**状态**（初始"未开始"）。**Gate** 和 **Contract ID** 列暂留空或标注 `[待标注]`——由后续 P-goal-plan 在标注门禁层级时填充。**依赖关系**节写入基础 ASCII 树形图（阻塞链），后续 P-goal-plan 在此基础上叠加门禁边界（`--- P0 gate ---`）、就绪标记 `[READY]` 和扇出标记 `[FAN-OUT: N路并行]`。**并行规则**节按模板保留——T-tickets 阶段写入规则文本，P-goal-plan 阶段可调整并发数。
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
-**tickets-map.md 填写说明：**
+更新 `<Path>{roots.state}/specdev/status.json</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`。
-- **执行清单**的 Ticket 列使用指向 `./ticket/` 目录的相对链接（纯数字编号前缀，如 `./ticket/01-auth.md`）
-- **编号**列使用 `01`、`02`、`10` 格式（两位零填充阿拉伯数字，不含 `#`），代表依赖顺序
-- **被阻塞于**列填写阻塞者的编号（如 `01`、`02, 05`）
-- **状态**列由 T-tickets 初始化为"未开始"，后续由实现者手动更新——始终以对应 ticket 文件中的状态字段为权威来源
-- **Gate** 列（P0/P1/P2）和 **Contract ID** 列由 P-goal-plan 填充；T-tickets 阶段留空或标 `[待标注]`
-- **依赖关系**用 ASCII 树形图展示阻塞链——T-tickets 写入基础结构，P-goal-plan 叠加门禁标注
-- **横切关注点**只放跨 ticket 的规则——单 ticket 的规则留在该 ticket 文件内
-- **阻塞关系说明**在依赖图非平凡时补充文字解释
+## 完成标准
-**完成标准**：`ticket/` 目录与全部 `NN-<ticket-name>.md` 已按依赖顺序写入；`tickets-map.md` 已按模板落盘（Gate / Contract ID 为 `[待标注]`）；每个 ticket 含阻塞边、战略与背景、范围边界、交付物、保留/不动与验收标准。
+- Ticket 目录和 Map 已写入完整 Path 标签 所指位置；
+- Spec 合同全部 covered 或有明确批准的 deferred；
+- DAG 无环、阻塞引用存在；
+- Ready Ticket 无高影响未知项；
+- 并行 Ticket 无未解决的可写冲突；
+- 每个 Ticket 可独立验证且适配单一上下文；
+- Prefactor 与 expand-contract 使用条件正确；
+- 用户已批准拆分或明确授权自主发布；
+- 校验器无 error。
 ## 子文件引用
-| 文件 | 内容 | 触发条件 |
-|------|------|----------|
-| `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` | tickets-map.md 权威模板——执行清单六列表格、门禁标注 DAG、并行规则、横切关注点 | 进入步骤 5c「写入 tickets-map.md」时加载——T-tickets 按此模板输出基础结构，P-goal-plan 随后标注 Gate、Contract ID 和门禁 DAG |
-本入口为单文件 work，所有 ticket 拆分流程内容均已内联。以下引用供其他 work 读取产物：
-- `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` —— 总体地图与执行清单（编号 | Ticket | 被阻塞于 | Gate | Contract ID | 状态），格式遵循 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`
-- `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>` —— 独立 ticket 文件目录，每个文件命名为 `NN-<ticket-name>.md`（`NN` = `01`, `02`, ..., `10`, ...）
-- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` —— 上游 spec（拆分依据）
-- `<Path>{roots.state}/specdev/adr/</Path>` —— 永久架构决策目录（已确认并提升的 ADR）
-- `<Path>{roots.state}/specdev/context/</Path>` —— 永久领域词汇表目录（已确认并提升的 CONTEXT）
+- 拆分规则：`<Path>{roots.workflows}/specdev/T-tickets/decomposition-rules.md</Path>`
+- Ticket 就绪规则：`<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>`
+- Ticket 模板：`<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>`
+- Tickets Map 模板：`<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`
 ## 下一步
-如果 ticket 数量超过 10 个，建议运行 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>` 产出目标规划文档，定义里程碑级约束、质量门禁和执行协议，为大规模协调执行做准备。
+满足任一情况时建议运行 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>`：Ticket 数量达到或超过 10、存在多 Agent 并行、Deep Ticket、迁移、共享契约、多个 Gate 或高风险发布。少量线性 Ready Ticket 可直接进入 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`。

package/template/workflows/specdev/T-tickets/decomposition-rules.md ADDED Viewed

@@ -0,0 +1,56 @@
+# Ticket 拆分规则
+本文件由 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 在草拟切片时加载，并受 `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>` 约束。
+## 好的垂直切片
+- 从稳定入口到可观察结果形成闭环；
+- 包含该行为所需的最小 schema、接口、交互与测试组合；
+- 完成后仓库处于可验证状态；
+- 与其他切片有实质行为差异；
+- 可以由一个全新上下文完成；
+- 不需要执行者重新决定外部行为或公共契约。
+## 拆分信号
+出现任一情况应拆分：
+- 包含两个可独立发布或验证的用户行为；
+- 需要多个不同领域或架构决策；
+- 预计超出单一上下文；
+- `writable_paths` 过宽且可通过接缝隔离；
+- 验证必须等到不相关工作完成；
+- 一个部分高风险、另一部分低风险；
+- 一个部分改变共享契约，其他部分只是消费者迁移。
+## 合并信号
+出现任一情况应合并：
+- 两个 Ticket 单独完成都没有可观察价值或安全准备价值；
+- 只是按技术层水平分割；
+- 验收、代码范围和证据高度重叠；
+- 依赖边只是人为交接，没有真实前置产物；
+- 拆分后每个 Ticket 都需要重复相同关键上下文和同一不可分割验证。
+## 特殊模式
+### Prefactor
+必须说明解除的具体阻碍、后续受益 Ticket 和独立验证。不能只写“清理代码”。
+### Expand-contract
+先扩展兼容层，再分批迁移，最后收缩。每批应保持绿色；不能保持绿色时必须有隔离集成分支与最终集成 Gate。
+### Research spike
+未知足以阻止决策时，进入 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`。调查 Ticket 只回答决策问题，不顺手实现产品代码。
+### Shared contract
+先由单一 owner Ticket 修改共享契约并形成稳定证据，再扇出消费者 Ticket。共享路径规则见 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`。
+### Bug fix
+已确认根因时，以 `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>` 的修复契约为依据；根因未知时先运行 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`。

package/template/workflows/specdev/T-tickets/ticket-readiness.md ADDED Viewed

@@ -0,0 +1,45 @@
+# Ticket Definition of Ready
+本检查由 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 使用，并细化 `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>`。
+## 通用门禁
+- [ ] frontmatter 字段完整，Ticket ID、文件名和 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 一致。
+- [ ] 可观察产出单一、明确且可验证。
+- [ ] 来源和验收合同映射存在。
+- [ ] IN、REUSE、OUT 无冲突。
+- [ ] 高影响未决问题为零。
+- [ ] `blocked_by` 指向存在的 Ticket，DAG 无环。
+- [ ] `expected_changes`、`writable_paths`、`read_only_paths` 和 `shared_paths` 中的项目路径都使用项目相对 Path 标签。
+- [ ] `writable_paths` 非空，或明确为仅文档、调查或无代码变更。
+- [ ] 每个 shared path 在 `shared_path_owners` 中有唯一 owner。
+- [ ] 正常、失败和回归至少各有一条验证，或有可信的不适用原因。
+- [ ] 仅当用户界面交互受影响时定义 E2E，且 owner 为 Lead 集成 Gate。
+- [ ] Evidence 位置明确为 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`。
+- [ ] 单个全新上下文能够完成；否则已拆分。
+- [ ] 所有内部文件与目录引用使用完整根变量 Path 标签。
+## Standard 门禁
+- [ ] 实现契约包含入口、输入输出、不变量、状态或数据流、失败行为和兼容。
+- [ ] 有 3–7 步有序执行路线。
+- [ ] 路径所有权足以支持并发判断。
+- [ ] 验证矩阵可以证明外部行为，而非只检查内部调用。
+## Deep 门禁
+- [ ] 迁移顺序、兼容窗口、监控、回滚或前向恢复、收缩条件和批准点完整。
+- [ ] 安全、隐私、资金或数据完整性风险有缓解与验证。
+- [ ] 跨 Agent 路径所有权和集成 Gate 明确。
+- [ ] expand-contract 的收缩条件可通过扫描、指标、查询或测试证明。
+## Ready 状态
+只有全部适用项通过时才能设置：
+```yaml
+ready: true
+status: ready
+```
+未通过时保持 `ready: false`，并在未决问题、阻塞原因或偏差记录中写明原因。

package/template/workflows/specdev/T-tickets/ticket-template.md ADDED Viewed

@@ -0,0 +1,124 @@
+---
+schema_version: 3
+artifact: ticket
+change: <YYYY-MM-DD-topic>
+id: T-01
+title: <标题>
+status: draft
+planning_depth: standard
+planning_depth_reason: <触发该深度的事实>
+ready: false
+risk: medium
+blocked_by: []
+contract_ids: [AC-001]
+owner: unassigned
+expected_changes: ["<Path>src/example.ts</Path>"]
+writable_paths: ["<Path>src/example/**</Path>"]
+read_only_paths: []
+shared_paths: []
+shared_path_owners: []
+---
+# Ticket T-01: <标题>
+- **Ticket 文件：** `<Path>{roots.state}/specdev/changes/{change}/ticket/01-<ticket-name>.md</Path>`
+- **总体 Map：** `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- **上游 Spec：** `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- **完成 Evidence：** `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>`
+## 1. 战略与来源
+- **目标：** 做什么、为什么、基于什么现有能力。
+- **可观察产出：** 完成后用户、调用者或系统外部可以观察到什么。
+- **来源：** `US-###`、`AC-###`、`ADR-###`、`USER-DECISION`、`CODE`、`RESEARCH` 或 `DIAG-###`。
+- **当前事实：** 相关现状与目标差距；项目文件使用项目相对 Path 标签，例如 `<Path>src/example.ts</Path>`。
+- **Planning Depth 原因：** 说明为什么是 Lite、Standard 或 Deep。
+## 2. 决策状态
+### 已锁定决策
+- ...
+### 已采用的低影响假设
+- 无。
+### 未决问题
+无。
+存在会改变行为、接口、数据、兼容、安全、范围、迁移或验收的问题时，frontmatter 中 `ready` 必须为 `false`。
+## 3. 范围边界
+| IN（本 Ticket 构建） | REUSE（复用且不改变契约） | OUT（明确不做） |
+|---|---|---|
+| ... | ... | ... |
+## 4. 要构建什么
+从用户或调用者视角描述一条完整行为路径：入口、动作、可观察结果、失败行为和边界。不要按数据库、后端、前端、测试等技术层分段罗列。
+## 5. 实现契约
+<!-- Lite 可压缩为适用条目；Standard 和 Deep 必填。 -->
+- **入口或接缝：**
+- **输入与输出：**
+- **公共接口变化：** 无 / ...
+- **不变量：**
+- **状态或数据流：**
+- **错误与失败行为：**
+- **兼容要求：**
+- **安全与隐私要求：** 不适用：原因 / ...
+## 6. 执行路线
+<!-- Lite 通常 1–3 步；Standard 和 Deep 通常 3–7 步。描述行为顺序、安全落点和验证时机，不写逐行代码。 -->
+1. 建立或确认验证接缝，使目标行为或关键风险按预期失败。
+2. ...
+3. 形成保持仓库可验证的安全落点。
+4. 运行定向验证和适用回归。
+## 7. 路径访问契约
+- **预计修改点：** 与 `expected_changes` 对齐，仅作导航。
+- **可写范围：** 与 `writable_paths` 对齐；越界前必须停止。
+- **只读上下文：** 与 `read_only_paths` 对齐。
+- **共享路径：** 与 `shared_paths` 对齐；每项在 `shared_path_owners` 指定唯一 owner。
+- **保留或不动：** 无 / ...
+项目路径必须写成项目相对 Path 标签。SpecDev 工件必须使用完整根变量 Path 标签。
+## 8. 验证矩阵
+| 行为或风险 | 验证接缝 | 命令或步骤 | 预期结果 | Evidence |
+|---|---|---|---|---|
+| 正常路径 | ... | ... | ... | `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>` |
+| 失败路径 | ... | ... | ... | `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>` |
+| 回归 | ... | ... | ... | `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>` |
+不适用的关键风险类别必须写“不适用：原因”。
+仅当用户界面交互受影响时增加 E2E 行；owner 固定为 Lead 集成 Gate，Worker 只提供场景与预期。
+## 9. 发布、迁移与恢复
+<!-- Deep 必填；其他深度仅在适用时保留。 -->
+- **迁移顺序：** 不适用：原因 / ...
+- **兼容窗口：** 不适用：原因 / ...
+- **监控信号：** 不适用：原因 / ...
+- **回滚或前向恢复：**
+- **不可逆操作与批准点：** 无 / ...
+- **收缩条件：** 不适用：原因 / 旧调用点、旧数据或旧协议使用量为零并有 Evidence。
+## 10. 验收标准
+- [ ] `AC-001`：<可判定结果>。
+- [ ] 验证矩阵全部执行并记录到 `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>`。
+- [ ] 实际项目修改未超出 `writable_paths`，shared path 由指定 owner 修改。
+- [ ] 未发生未批准的范围、契约或发布偏差。
+- [ ] Ticket、Tickets Map 和 Evidence 状态一致。