@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/specdev/specdev-t-tickets/assets/ticket-template.md

@@ -0,0 +1,157 @@
+---
+schema_version: 3
+plan_contract_version: 1
+skill_scan: unreviewed
+skill_bindings: []
+resource_claims: []
+artifact: ticket
+ui_change: false
+design_ref: null
+change: <YYYY-MM-DD-topic>
+id: T-01
+title: <标题>
+status: draft
+kind: bug
+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>`
+
+实现本 Ticket 时，Lead 与 实现执行者 必须按顺序完整读取总体 Map，读取项目 Skill 的 frontmatter 与入口并只展开适用于 `ALL`/`T-01` 的匹配项，再读取本 Ticket 与相关上游工件。Map 中的 Skill 是最低必读集合；新的匹配项先由 Lead 同步到 Map 并重新校验。
+
+## 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>` |
+
+不适用的关键风险类别必须写“不适用：原因”。
+
+- **Workspace checks：** 按 Goal Plan 在 current workspace 或 source worktree 运行单元、组件、静态、类型、lint/build 等适用非 E2E 检查。
+- **E2E disposition：** required / not-required：原因。
+- **E2E owner/environment：** Lead / current-workspace 或 parent-candidate；required 时写明场景、接缝与预期。
+- **Integration evidence：** implementation/source commit、parent before、适用 candidate/result SHA 和父分支包含关系。
+
+E2E 由实际跨边界行为与风险决定，不限于 UI；required 模式不得在 Ticket source worktree 运行或声明通过。
+
+## 9. 发布、迁移与恢复
+
+<!-- Deep 必填；其他深度仅在适用时保留。 -->
+
+- **迁移顺序：** 不适用：原因 / ...
+- **兼容窗口：** 不适用：原因 / ...
+- **监控信号：** 不适用：原因 / ...
+- **回滚或前向恢复：**
+- **不可逆操作与批准点：** 无 / ...
+- **收缩条件：** 不适用：原因 / 旧调用点、旧数据或旧协议使用量为零并有 Evidence。
+
+## 10. 验收标准
+
+- [ ] `AC-001`：<可判定结果>。
+- [ ] 实现开始前已完整读取 Tickets Map，已读取项目 Skill 入口并完整展开其中适用于 `ALL`/`T-01` 的匹配项；新发现的匹配 Skill 已由 Lead 同步回 Map。
+- [ ] 验证矩阵全部执行并记录到 `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>`。
+- [ ] 实际项目修改未超出 `writable_paths`，shared path 由指定 owner 修改。
+- [ ] Ticket 已按 Goal Plan 策略形成非空 implementation/source commit，direct-parent 或 candidate 验证通过且父分支 result 已记录。
+- [ ] E2E disposition 已执行；required 模式 E2E 在 parent-candidate、current 模式在 current workspace 由 Lead 完成。
+- [ ] 未发生未批准的范围、契约或发布偏差。
+- [ ] Ticket 状态有本票 Evidence 支撑；Tickets Map 的导航、依赖和合同覆盖仍有效，不复制本票进度。
+
+## 11. SKILL 调用计划
+
+依据 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 填写 frontmatter 绑定；正文解释每项调用为什么属于本票、具体何时调用、输入定位、输出如何用于下一步。不是仅给出技能名称或阅读列表。没有适用项目 Skill 时写明真实扫描证据；不要保留 unreviewed。
+
+## 12. 停止、检查点与交付
+
+- **用户交付要求与数量：** 与 Map 的 requested_deliverables 对齐；不为压缩而减少。
+- **必需 Skill/引用/测试不可用：** 阻塞本票，报告缺口，不静默替换默认工具。
+- **归属与资源冲突：** 暂停本票和受影响下游，不接管他人状态；独立票由 map 继续。
+- **检查点：** 记录源版本、绑定摘要、已完成步骤、Evidence 和未闭合动作；恢复前回读。
+- **完成出口：** 全部适用验收及实际 Skill 证据通过，再将结果交回 Goal；未完成项明确列出。
+
+## 工程验收补充（适用时）
+
+列明真实消费者/入口、文档和升级说明、错误后的状态保证、恢复责任、旧测试的风险承接，以及代码/输入/配置/Skill 变化时需重验的证据。性能票引用用户操作与基线；documentation 票区分纯说明与模型/用户可见变化。无关项写不适用及理由，不逐项另造 Ticket。

package/template/workflows/specdev/specdev-t-tickets/assets/tickets-map-template.md

@@ -0,0 +1,102 @@
+---
+schema_version: 3
+plan_contract_version: 1
+plan_revision: 1
+requested_deliverables: []
+deliverable_policy: unreviewed
+artifact: tickets-map
+change: <YYYY-MM-DD-topic>
+status: draft
+---
+
+# Tickets Map: <工作名称>
+
+- **Map：** `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
+- **Spec：** `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- **Ticket 目录：** `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
+- **Evidence 目录：** `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
+- **可选 Goal Plan：** `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
+
+## 1. 目标与拆分策略
+
+引用主要用户故事、验收合同和架构决策，说明所有 Ticket 共同交付的目标、切片原则、prefactor 和 expand-contract 选择。不要复制整个 Spec。
+
+### 总体实施背景
+
+记录所有 Ticket 共同依赖、但不属于单个 Ticket 的模块边界、公共契约、关键不变量、集成顺序和不可重复决定。实现者用本节理解全局目标；单 Ticket 的完整实现契约仍由对应 Ticket 拥有。
+
+### 项目 Skill 读取矩阵
+
+每个 Ticket 的 Lead 或 实现执行者 都必须先完整读取本 Map，再读取候选项目 Skill 的 frontmatter 与入口；只有适用于 `ALL` 或当前 Ticket ID、且 scope/路径/技术域/验证条件命中的 Skill 才完整读取，最后进入当前 Ticket。下表是发布时已确认的**最低必读集合，不是 Skill allowlist**；项目 Agent 指令或实现范围触发其他项目 Skill 时，先定位并读取其入口，由 Lead 更新本 Map、重新校验后继续。
+
+项目 Skill 使用项目根相对 Path，例如 `<Path>.agents/skills/{skill-name}/SKILL.md</Path>`；不得写机器绝对路径。若没有适用项目 Skill，保留一行 `无（已扫描项目 Skill 入口，未发现适用项）`，并在 Trigger / Scope 中记录实际扫描范围。
+
+| Applies To | Project Skill | Trigger / Scope | Read Timing | Purpose |
+|---|---|---|---|---|
+| ALL | 无（已扫描项目 Skill 入口，未发现适用项） | `<Path>.agents/skills/**/SKILL.md</Path>` 与项目 Agent 指令声明的 Skill 根 | Map 后、Ticket 前 | 明确当前 change 没有额外项目 Skill 读取要求 |
+
+## 2. 执行清单
+
+| ID | Ticket | 跨票 Gate/依赖导航 |
+|---|---|---|
+| T-01 | `<Path>{roots.state}/specdev/changes/{change}/ticket/01-<ticket-name>.md</Path>` | 本 Map 第 3、6 节；正式 Goal 存在时指向原 Gate |
+
+本表只导航实际 Ticket 和跨票合同。状态、Ready、执行 owner、深度、风险及本票写集从 Ticket frontmatter 回读，实际 workspace/集成结果从本票 Evidence 回读；不在 Map 缓存或随进度更新。Map frontmatter 的 status 表示本 Map 的结构/合同就绪与验收，不汇总或代替单票进度。
+
+## 3. 依赖 DAG
+
+```text
+T-01
+  ├─→ T-02
+  └─→ T-03
+        └─→ T-04
+```
+
+每条边必须表示真实开始条件。标记关键汇合点、prefactor、expand、migrate、observe、contract 和集成验证点。
+
+## 4. 合同覆盖矩阵
+
+| Contract ID | 覆盖 Ticket | 验证接缝 | 状态 | 说明 |
+|---|---|---|---|---|
+| AC-001 | T-01 | ... | covered | ... |
+
+`uncovered` 必须修复；`deferred` 必须有用户批准、原因和后续归属。
+
+## 5. 并行与路径所有权
+
+- 并发与集成尝试策略来自原 Goal 的 `Execution Policy Source` 或实际项目约定；存在有效 `<Path>{roots.state}/specdev/config.json</Path>` 时核对其限制，不为确定上限创建 config。未采用完整并行计划时缺省 current/direct-parent、单 writer；required 模式取计划、现有 config 和宿主能力允许的上限，Lead 实际参与实现时计入。
+- review/research/test-observation agent 不设 SpecDev 数字上限，但保持只读。
+- shared owner 为专用 Ticket；Lead 是 SpecDev 状态与父分支 integration owner。
+- 项目路径契约以 Ticket frontmatter 为准。
+- 每个实现 Ticket 的 workspace 由 Goal Plan 选择；current 模式串行使用当前 workspace，required 模式使用独立 worktree；只读调查不进入 I-implement Ticket。
+
+| Ticket A | Ticket B | Writable 交集 | 真实依赖 | 处理 |
+|---|---|---|---|---|
+| T-02 | T-03 | 无 | 否 | 可并行 |
+
+## 6. Gate、Wave 与集成点
+
+T-tickets 可以标注候选 Wave 和行为里程碑；单票 E2E disposition 在原 Ticket。需要正式跨 Ticket 编排时，由 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>` 完成 Gate、Wave、Lead、动态派单边界、candidate 集成顺序、发布与恢复，本 Map 只导航相应 Goal 章节。
+
+## 7. 横切契约与风险
+
+只记录跨多个 Ticket 的数据、安全、兼容、共享接口、迁移、发布和恢复规则。单 Ticket 规则留在具体 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`。
+
+## 8. 维护规则
+
+- Ticket 进度改变时只更新原 Ticket/Evidence；查看进度或恢复时重新读取它们，Map 保持不变；
+- Ticket 新增、移除、ID/路径或依赖合同变化时，修复本 Map 的导航、DAG 与覆盖；不从旧 Map 恢复票级状态；
+- 项目 Skill 新增、移动、删除、触发范围变化或实现中发现新的适用 Skill 时，先同步读取矩阵并重新校验；
+- Goal Plan 存在时，Wave、Gate 和 owner 以 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 为编排权威；
+- 依赖、合同覆盖或路径所有权变化后运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>`；
+- 内部工件不得使用相对 Markdown 链接。
+
+## 9. 总控与恢复
+
+从本 Map 进入 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>` 的 plan/run/resume/replan/verify。先运行 `<Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path>` 的 `--map` 只读检查，再按 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/references/map-control.md</Path>` 调用 I 和真实 Skill、验收、更新状态直到完成或明确阻塞；此工具本身不执行代码。
+
+- frontmatter 中 requested_deliverables 用 JSON 对象数组记录用户明确要求的名称与正整数 count；没有额外数量要求时用空数组，并在 deliverable_policy 记录依据，不能保留 unreviewed。
+- requested_deliverables 属于用户交付合同；done 之前按实际产物核对，不从 Ticket 数量推断交付数量。
+- 变更范围或验收后递增 plan_revision 并重算受影响闭包；原完成证据保留，失效证据不得复用。
+- 共享语义资源在 Ticket resource_claims 声明（例如 API、表、迁移序列、正式记忆写集）；不把“不同文件”视为互不冲突。
+- 未闭合事务先查原网关，其他任务冲突只暂停相关部分；全部票 done 后仍需整体 Gate、数量和集成验收。

package/template/workflows/specdev/specdev-t-tickets/references/decomposition-rules.md

@@ -0,0 +1,60 @@
+# Ticket 拆分规则
+
+本文件由 `<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.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/specdev-w-wayfinder/SKILL.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/specdev-d-diagnose-bugs/SKILL.md</Path>`。
+
+## 工程证据随行为切片
+
+把文档、失败恢复、真实入口与回归检查放入拥有该行为的票，不逐检查项拆票制造交接。复杂迁移保留 Expand → Migrate → Contract 的真实顺序和旧数据核对；低风险文档继续使用现有 documentation kind。

package/template/workflows/specdev/specdev-t-tickets/references/planning-procedure.md

@@ -0,0 +1,235 @@
+# 拆分 Tickets
+
+
+Ticket 是**决策完备的微型执行计划**：它消除执行者在目标、范围、公共契约、关键顺序和验收上的关键决策，但不展开逐行代码、局部变量或可从现有惯例自然推导的实现细节。
+
+本 work 保留原有能力：代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。
+
+
+## 输入
+
+优先读取：
+
+- 当前 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>`
+- 项目 Agent 指令及其声明的项目 Skill 根；
+- 项目当前代码、测试、配置、schema 和 CI 事实。
+
+若尚无 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`，只有在用户提供的计划或对话已经等价覆盖目标、范围、关键决定和可判定验收时才可继续；否则建议先运行 `<Path>{roots.workflows}/specdev/specdev-s-spec/SKILL.md</Path>`。
+
+## 流程
+
+### 1. 输入预检
+
+1. 先读取上游工件索引，按当前 Ticket 的依赖、缺口和冲突关键词定位，再回读相关工件；
+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 文字伪装决策完备。
+
+**完成标准**：拆分依据、权威顺序、合同范围与未决问题已明确。
+
+UI 范围同时读取 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 与 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>，核对批准、revision/digest、基线、prototype 和页面/状态。每张 UI 票以 `design_ref` 绑定所负责的 pages/acceptance，不能复制一份可独立修改的视觉规则。设计缺失或漂移先返回 P。
+
+### 2. 探索代码库与实现地形
+
+如果尚未探索，进行只读探索：
+
+- 找到行为入口、稳定接口、测试接缝、数据流和错误路径；
+- 查找相邻或类似实现，优先复用项目现有模式；
+- 识别可能修改的模块、公共路径、共享文件、迁移索引和全局注册点；
+- 查找现有测试命令、夹具、类型检查、构建和 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>` 避免重新争论已接受决策。
+
+遇到不熟悉的模块、外部依赖或第三方库时，使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`，再继续拆分。
+
+#### 项目 Skill 路由
+
+1. 读取项目 Agent 指令，确定项目声明的 Skill 根；至少枚举 `<Path>.agents/skills/**/SKILL.md</Path>`，存在其他项目级 Skill 根时一并枚举；
+2. 先读取候选 Skill 的 frontmatter 与入口路由；只有命中当前 change 的 scope、路径、技术域或验证条件时才完整读取，并按其 Skill Map 路由到当前 change 需要的领域 Skill；
+3. 根据 change 索引、每个 Ticket 的 frontmatter、路径、技术域、公共契约、迁移与验证范围，确定 `ALL` 或具体 Ticket 的最低必读集合；只把真实存在且触发条件匹配的项目 Skill 纳入；
+4. 使用项目根相对 Path 记录每个 Skill 的入口文件，同时记录触发 scope、读取时机和用途；不得把 Speculo 自带 Skill 或机器绝对路径伪装成项目 Skill；
+5. 未发现适用项目 Skill 时，记录已扫描的 Skill 根和“无适用项”，不生成虚假路径；项目 Skill 清单是最低集合而非 allowlist。
+
+#### Prefactor
+
+遵循“让变更变容易，然后做容易的变更”：
+
+- 如果当前接口、依赖或接缝会使后续实现明显不安全或重复，提出前置 prefactor Ticket；
+- prefactor 必须说明它解除的具体阻碍；
+- prefactor 必须独立有价值且可验证；
+- 不为了“更干净”而创建与目标无关的重构 Ticket。
+
+**完成标准**：实现地形、稳定接缝、共享路径、必要 prefactor 与逐 Ticket 项目 Skill 路由已识别。
+
+### 3. 草拟曳光弹式垂直切片
+
+加载 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/decomposition-rules.md</Path>`。每个切片应横向穿过交付该行为所需的最小层次组合，而不是把数据库、后端、前端和测试拆成互相无价值的水平 Ticket。
+
+每个 Ticket 必须：
+
+- 交付一个可观察行为，或一个能独立解除后续阻塞的安全准备能力；
+- 完成后可以独立演示、测试或验证；
+- 适合一个全新 Agent 上下文在不中断的情况下完成；
+- 与其他 Ticket 有实质行为差异；
+- 只依赖真正阻止它开始的前置产物；
+- 自带至少一种完成证据。
+
+#### 宽重构例外
+
+字段重命名、共享符号类型变化、协议升级等宽机械变更无法安全塞入单个垂直切片时，按以下顺序：
+
+1. **Expand**：在旧形式旁增加新形式，保持旧调用方可工作；
+2. **Migrate batches**：按包、目录、消费者或风险分批迁移，每批独立成 Ticket；
+3. **Contract**：确认旧调用点为零后删除旧形式；
+4. 若迁移批次无法各自保持绿色，使用隔离集成分支和最终集成验证 Gate，但仍保留明确的批次与责任边界。
+
+**完成标准**：每个 Ticket 的可观察产出、真实阻塞边和验证方式已草拟。
+
+### 4. 判定规划深度与风险
+
+按 `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>` 为每个 Ticket 标注：
+
+- `lite`：局部、可逆、沿用既有模式、无公共契约或迁移影响；
+- `standard`：大多数多文件或跨层垂直切片；
+- `deep`：公共 API/schema、数据迁移、安全/隐私/资金、不可逆操作、expand-contract、共享核心路径、多个 implementation owner 的跨 Ticket 写入协调或高事故半径。
+
+规划深度不是优先级，也不是 Gate。每个 Ticket 必须记录触发该深度的原因。
+
+### 5. 写成决策完备 Ticket
+
+必须按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 填写本票真实调用绑定；Map 中的读取路由不能代替调用。
+
+使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/ticket-template.md</Path>` 填写：
+
+- 战略目标、可观察产出与来源追踪；
+- 当前代码事实和需求差距；
+- 已锁定决策、低影响假设和未决问题；
+- IN / REUSE / OUT；
+- 用户或调用者视角的端到端行为；
+- Standard/Deep 的接口、输入输出、不变量、数据流、失败与兼容契约；
+- 有序执行路线和安全落点；
+- expected、writable、read-only、shared 路径；
+- 正常、失败和回归验证矩阵；
+- 每个 Ticket 按 Goal Plan 的 workspace 策略定义 current-workspace/direct-parent 或 source-worktree/parent-candidate 检查，以及按实际跨边界风险判定的 E2E disposition；
+- 每个实现 Ticket 的 implementation commit 与对应父分支完成条件；仅 required 模式创建独立 worktree；
+- Deep 的迁移、兼容窗口、监控、回滚和不可逆批准点；
+- 可判定验收标准。
+
+路径所有权必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`，证据设计必须遵守 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
+
+### 6. 构建依赖 DAG、合同覆盖与并发检查
+
+1. 使用 Ticket ID 建立 `blocked_by`；
+2. 检测循环和不存在的引用；
+3. 识别根 Ticket、汇合点、扇出与收缩点；
+4. 为每个 Spec 验收合同映射至少一个 Ticket；
+5. 检查并行候选的 `writable_paths` 是否相交；
+6. 共享路径必须指定唯一 owner，通常由专门 Ticket 或明确的集成 owner 修改；
+7. 不得用依赖边表达“可能更方便”或纯粹的人员交接。
+
+使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/tickets-map-template.md</Path>` 草拟总体 Map；写入所有 Ticket 共享的总体实施背景与项目 Skill 读取矩阵。矩阵中的每个 Ticket 必须由 `ALL` 或自己的 Ticket ID 覆盖。
+
+### 7. Definition of Ready
+
+加载 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/ticket-readiness.md</Path>` 逐个检查。
+
+存在以下任一情况时 `ready: false`：
+
+- 会改变行为、接口、数据、兼容、安全、范围或验收的未决问题；
+- 依赖缺失或 DAG 有环；
+- 可写路径不明确或并行所有权冲突；
+- 验证方法不能执行且没有批准的替代证据；
+- Ticket 未声明 E2E required/not-required 及理由，或在 required 模式把 E2E 安排到 source worktree；
+- Tickets Map 缺少总体实施背景或项目 Skill 读取矩阵，项目 Skill 路径不存在、不是项目根相对路径，或当前 Ticket 未被 `ALL`/自身 ID 覆盖；
+- 无法形成实现 commit 与 Goal Plan 所选 direct-parent/candidate-merge 父分支出口；
+- 单个新上下文无法完成；
+- Standard/Deep 缺少有序执行路线；
+- Deep 缺少迁移、兼容、监控、回滚或批准点。
+
+### 8. 与用户核对
+
+以完整编号列表展示所有 Ticket，至少包含：
+
+- 标题；
+- 可观察交付；
+- 被阻塞于；
+- Planning Depth 与触发原因；
+- 风险；
+- Ready 状态；
+- 关键未决问题；
+- 预计并行组和共享路径 owner；
+- `ALL` 与逐 Ticket 的项目 Skill 最低必读集合。
+
+核对：
+
+- 粒度是否适合单一上下文；
+- 是否出现水平切片；
+- 阻塞边是否真实；
+- 是否应合并、进一步拆分或增加 prefactor；
+- 合同是否全部覆盖；
+- 路径所有权和验证是否可信。
+
+每次修改后重新展示完整列表，直到用户批准。用户明确要求一次性自主规划且不存在高影响未知项时，可使用推荐默认值并把假设写入 Ticket，不为形式重复询问。
+
+### 9. 发布
+
+创建：
+
+- 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>
+```
+
+`NN` 使用两位或更多位零填充数字；Ticket frontmatter ID 使用 `T-NN`。Ticket 的 `blocked_by` 使用 Ticket ID，而不是相对文件路径。
+
+使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/ticket-template.md</Path>` 和 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/tickets-map-template.md</Path>` 生成工件，并对照：
+
+- `<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
+- `<Path>{roots.workflows}/specdev/common/schemas/tickets-map.schema.json</Path>`
+
+运行：
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
+  --stage tickets \
+  --repo <project-root> \
+  <Path>{roots.state}/specdev/changes/{change}</Path>
+```
+
+回读 Ticket 的状态、Map 的依赖/导航以及 README 接续点，不另写状态镜像。
+
+## 完成标准
+
+- Ticket 目录和 Map 已写入完整 Path 标签 所指位置；
+- Spec 合同全部 covered 或有明确批准的 deferred；
+- DAG 无环、阻塞引用存在；
+- Ready Ticket 无高影响未知项；
+- 并行 Ticket 无未解决的可写冲突；
+- 每个 Ticket 可独立验证且适配单一上下文；
+- Tickets Map 已记录总体实施背景；每个 Ticket 被项目 Skill 读取矩阵覆盖，Skill 路径存在且为项目根相对路径；
+- Prefactor 与 expand-contract 使用条件正确；
+- 用户已批准拆分或明确授权自主发布；
+- 校验器无 error。
+
+## 子文件引用
+
+- 拆分规则：`<Path>{roots.workflows}/specdev/specdev-t-tickets/references/decomposition-rules.md</Path>`
+- Ticket 就绪规则：`<Path>{roots.workflows}/specdev/specdev-t-tickets/references/ticket-readiness.md</Path>`
+- Ticket 模板：`<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/ticket-template.md</Path>`
+- Tickets Map 模板：`<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/tickets-map-template.md</Path>`
+
+## 下一步
+
+满足任一情况时建议运行 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>`：Ticket 数量达到或超过 10、存在多个 implementation owner 的并行写入协调、Deep Ticket、迁移、共享契约、多个 Gate 或高风险发布。只读 review/research 并行本身不触发 Goal Plan；少量线性 Ready Ticket 可直接进入 `<Path>{roots.workflows}/specdev/specdev-i-implement/SKILL.md</Path>`。

package/template/workflows/specdev/specdev-t-tickets/references/ticket-readiness.md

@@ -0,0 +1,56 @@
+# Ticket Definition of Ready
+
+本检查由 `<Path>{roots.workflows}/specdev/specdev-t-tickets/SKILL.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>` 一致。
+- [ ] Tickets Map 包含总体实施背景与项目 Skill 读取矩阵；当前 Ticket 被 `ALL` 或自身 Ticket ID 覆盖。
+- [ ] 矩阵中的项目 Skill 均使用真实存在的项目根相对 `<Path>.../SKILL.md</Path>`，并声明 Trigger / Scope、读取时机和用途；没有适用项时记录实际扫描范围而不生成虚假路径。
+- [ ] Ticket 明确要求 Lead 与 实现执行者 按 Map -> 适用项目 Skill -> 当前 Ticket 的顺序读取；矩阵是最低必读集合而非 allowlist。
+- [ ] 可观察产出单一、明确且可验证。
+- [ ] 来源和验收合同映射存在。
+- [ ] UI Ticket 的 ui_change/design_ref 固定批准 DESIGN 的 revision、digest、pages 与 acceptance；实际 UI 文件范围不能靠省略标记绕过，非 UI 票无此门禁。
+- [ ] UI 实施的 Design Conformance 证据责任、页面/状态验收与真实浏览器路径明确；设计漂移返回 P。
+- [ ] IN、REUSE、OUT 无冲突。
+- [ ] 高影响未决问题为零。
+- [ ] `blocked_by` 指向存在的 Ticket，DAG 无环。
+- [ ] `expected_changes`、`writable_paths`、`read_only_paths` 和 `shared_paths` 中的项目路径都使用项目相对 Path 标签。
+- [ ] `writable_paths` 非空；纯 review/research 不伪装成 I-implement Ticket。
+- [ ] 每个 shared path 在 `shared_path_owners` 中有唯一 owner。
+- [ ] 正常、失败和回归至少各有一条验证，或有可信的不适用原因。
+- [ ] 明确 `E2E disposition: required | not-required: reason`；required 场景、预期和接缝可执行。
+- [ ] 按 Goal Plan 策略定义 current-workspace 或 source-worktree 的非 E2E 检查；E2E owner 固定为 Lead，运行环境分别为 current-workspace 或 parent-candidate。
+- [ ] Ticket 完成合同包含 implementation commit、direct-parent 或 candidate-merge、父分支 result SHA 和 Lead Evidence；仅 required 模式需要独立 worktree。
+- [ ] Evidence 位置明确为 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`。
+- [ ] 单个全新上下文能够完成；否则已拆分。
+- [ ] 所有内部文件与目录引用使用完整根变量 Path 标签。
+
+## Standard 门禁
+
+- [ ] 实现契约包含入口、输入输出、不变量、状态或数据流、失败行为和兼容。
+- [ ] 有 3–7 步有序执行路线。
+- [ ] 路径所有权足以支持并发判断。
+- [ ] 验证矩阵可以证明外部行为，而非只检查内部调用。
+
+## Deep 门禁
+
+- [ ] 迁移顺序、兼容窗口、监控、回滚或前向恢复、收缩条件和批准点完整。
+- [ ] 安全、隐私、资金或数据完整性风险有缓解与验证。
+- [ ] 跨 implementation owner 的路径所有权和所选 direct-parent/parent-candidate 集成 Gate 明确。
+- [ ] expand-contract 的收缩条件可通过扫描、指标、查询或测试证明。
+
+## Ready 状态
+
+只有全部适用项通过时才能设置：
+
+```yaml
+ready: true
+status: ready
+```
+
+未通过时保持 `ready: false`，并在未决问题、阻塞原因或偏差记录中写明原因。
+
+## 适用工程义务
+
+Ready 前确认真实调用方、文档/升级说明、正常与失败验证、恢复条件和证据失效条件。删除测试有风险承接；性能票有测量基线和真实用户操作；文档票分清纯说明与可见行为。缺少 required 验证不因工具暂不可用而标 ready。