@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/specdev/specdev-s-spec/assets/spec-template.md

@@ -0,0 +1,99 @@
+---
+schema_version: 3
+artifact: spec
+change: <YYYY-MM-DD-topic>
+status: draft
+ready_for_tickets: false
+sources:
+  - USER-DECISION:<summary>
+---
+
+# Spec: <标题>
+
+- **Spec：** `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- **当前 ADR：** `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- **当前领域上下文：** `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+
+## 1. 问题与目标
+
+### 问题陈述
+
+### 目标用户与场景
+
+### 成功标准
+
+### 非目标
+
+## 2. 解决方案与外部行为
+
+### 解决方案摘要
+
+### 主要流程
+
+### 边界、失败与稳定错误行为
+
+### 状态转换与不变量
+
+## 3. 用户故事
+
+- **US-001**：作为 <角色>，我希望 <能力>，以便 <收益>。
+
+## 4. 验收合同
+
+| ID | 前置条件 | 动作或事件 | 可观察结果 | 验证接缝 |
+|---|---|---|---|---|
+| AC-001 | ... | ... | ... | ... |
+
+## 5. 范围
+
+### IN
+
+### REUSE
+
+### OUT
+
+- **OOS-001**：<不做什么及原因>。
+
+## 6. 已锁定实现约束
+
+- **DEC-001**：<只写影响公共接口、数据、不变量、兼容、安全或验证的决策>。来源：`ADR-###`。
+
+## 7. 数据、接口与兼容
+
+- **公共接口变化：** 无 / ...
+- **数据模型与持久化：** 无 / ...
+- **兼容要求：** 无 / ...
+- **迁移要求：** 无 / ...
+- **发布或运维影响：** 无 / ...
+
+## 8. 非功能要求
+
+- **NFR-001 安全与隐私：**
+- **NFR-002 性能与容量：**
+- **NFR-003 可用性与可靠性：**
+- **NFR-004 可观测性与运营：**
+
+不适用的维度写“不适用：原因”。
+
+## 9. 验证策略
+
+| 接缝 | 层级 | 覆盖合同 | 现有先例或命令 | Evidence 类型 |
+|---|---|---|---|---|
+
+项目测试先例可引用项目相对路径，例如 `<Path>tests/example.test.ts</Path>`。
+
+## 10. 风险、假设与未决问题
+
+### 风险
+
+### 已采用的低影响假设
+
+### 未决问题
+
+无。
+
+存在高影响未决问题时，`ready_for_tickets` 必须为 `false`。
+
+## 失败与兼容补充（适用时）
+
+在原 AC/NFR 编号下记录取消/重复/乱序、未开始/部分提交/已提交/未知结果、可安全重试前提、状态 owner、可观察错误和旧数据迁移/恢复限制。这里只补充适用合同，不新增另一套验收编号或实现计划。

package/template/workflows/specdev/specdev-s-spec/references/spec-readiness.md

@@ -0,0 +1,17 @@
+# Spec Readiness
+
+本检查适用于独立 Spec 或合同允许的 README 等价范围/AC/验证；轻量不机械要求 Spec YAML，但行为、可观察 AC、风险与 Ready 判断不变。独立 Spec 存在则读取它，不能双权威。
+
+- [ ] 问题、目标用户和成功标准从用户或调用者视角可理解。
+- [ ] 主要、边界、错误、角色和状态场景足以生成垂直切片。
+- [ ] 每个用户故事至少被一个验收合同覆盖。
+- [ ] 每个验收合同可观察、可判定且有验证接缝。
+- [ ] IN、REUSE、OUT 无冲突。
+- [ ] 公共接口、数据、兼容、安全、迁移和发布影响已决定或明确不适用。
+- [ ] 已锁定实现约束有来源，没有把偏好伪装成事实。
+- [ ] UI 范围已实际读取并引用批准有效的 change DESIGN、基线 revision/digest 与 UI 原型，页面/状态对应 AC；没有 UI 影响时明确不适用。
+- [ ] 高影响未决问题为零。
+- [ ] 低影响假设可逆且有验证方式。
+- [ ] 项目路径引用使用项目相对 Path 标签，内部工件使用完整根变量 Path 标签。
+- [ ] Spec 不包含逐文件施工清单或容易过时的行号承诺。
+- [ ] 独立 Spec 的 `ready_for_tickets: true` 与实际内容一致；轻量在原 README 明确同等就绪/缺口，不为免拆票创造 Map。

package/template/workflows/specdev/specdev-t-tickets/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: specdev-t-tickets
+description: "将已澄清的 Spec 或等价获批计划拆为可验收的实施 Ticket，并绑定真实项目 Skill；不用于探索未知需求或执行代码。"
+metadata:
+  speculo-kind: work-skill
+  speculo-id: specdev/tickets
+  speculo-domain: specdev
+  speculo-contract-version: "2"
+---
+
+# 编写计划型 Tickets
+
+> 激活后读取 `<Path>{roots.workflows}/specdev/common/rules/domain-runtime.md</Path>`。
+
+每张票都是供新上下文执行的 Plan：说明背景、来源、目标、非目标、真实项目 SKILL 调用、修改顺序、验证和失败停止点。Tickets Map 是统一启动与恢复入口，不是静态清单；它不复制 Ticket 的状态权威。
+
+## 读取范围
+
+先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`；按相关条目定位上游 Spec/ADR/CONTEXT、代码与项目 Agent 指令，再回读当前拆分所需原文。只枚举 Skill 的元数据与触发路由，不默认展开全部技能。
+
+先判断是否确需拆票；单 change、明确范围/AC 且无需 DAG/独立票的任务保留 README 或无票 Goal 清单，不为工具制造 Map。用户明确要求 Ticket 则交付；复杂并行、Deep 或跨 change 使用完整合同。
+
+## 从合同到可执行票
+
+1. **输入与范围**：确认目标、非目标、用户指定数量、验收合同和未知项。高影响未决问题回到 G；无 Ready Spec 时，只有用户材料已等价覆盖全部合同才可规划。
+2. **地形与绑定**：定位真实可维护源、调用方、测试接缝和 Skill 根。按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 为每票解析实际 Skill ID、入口摘要、调用阶段、输入、产出与失败动作；没有适用项目 Skill 时记录扫描证据，不造名称。
+3. **垂直切片**：需要具体拆分时读取 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/planning-procedure.md</Path>` 与 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/decomposition-rules.md</Path>`。保留 Prefactor、Expand → Migrate → Contract 和真实 DAG，不按技术层制造空价值任务。
+4. **写 Plan**：使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/ticket-template.md</Path>`。Lite 仅减少不适用说明，不删用户数量、权限、验收或停止条件。所有票必须使用 `plan_contract_version: 1`；旧格式不进入执行。
+5. **写总控**：使用 `<Path>{roots.workflows}/specdev/specdev-t-tickets/assets/tickets-map-template.md</Path>`，记录共同背景、Skill 最低路由、合同覆盖、依赖和明确控制入口；进度、Ready 与执行 owner 每次从 Ticket/Evidence 回读，不写入 Map。按 AC 反查至少一个负责验证的 Ticket，暴露未覆盖和重复所有权；依赖环、路径重叠与语义共享资源分别检查，不能用“可并行”文字替代实际 DAG/写集。
+6. **Definition of Ready**：读取 `<Path>{roots.workflows}/specdev/specdev-t-tickets/references/ticket-readiness.md</Path>`，并调用 `<Path>{roots.workflows}/specdev/common/skills/plan-quality-review/SKILL.md</Path>`。缺失引用、必需 Skill、可运行验收或权限边界，当前票不可 ready。
+7. **与用户核对**：展示全部票、可观察产物、依赖、深度、风险、Skill 和未决问题。保留用户要求的交付数量；已授权自主规划且无关键未知时不重复请求形式确认。
+8. **验证、回读和交付**：按下述命令检查，再回读真实 Ticket/Map，报告修改、验证结果和未完成项。规划完成不自动进入实现。
+
+```bash
+node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage tickets --repo <project-root> <Path>{roots.state}/specdev/changes/{change}</Path>
+node <Path>{roots.workflows}/specdev/common/tools/ticket-control.mjs</Path> --map <Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path> --repo <project-root>
+```
+
+需要正式 Goal、多 change、迁移或跨票 Gate 时交给 `<Path>{roots.workflows}/specdev/specdev-p-goal-plan/SKILL.md</Path>`；少量线性票可从 map 按已授权范围调用 `<Path>{roots.workflows}/specdev/specdev-i-implement/SKILL.md</Path>`。不得以“精简”为理由静默更换默认工具或少交付。
+
+## 工程义务与证据失效
+
+每票按实际影响列明真实生产消费者、接口两端、文档/升级说明、回归与模型可见输出的责任；删除测试要给出原风险在新测试中的承接。风险及证据选择使用 <Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>，失败状态使用 <Path>{roots.workflows}/specdev/common/rules/error-handling.md</Path>。工具定义或上下文变更才加载 <Path>{roots.workflows}/specdev/common/rules/agent-experience.md</Path>。
+
+将有关检查合并进负责该行为的 Ticket，不为每个检查项创建一票。documentation 仍用现有 kind，性能实施引用 R 的测量基线，不增加分类 schema。每票说明 base/head、配置、输入或 Skill 改变后哪些证据需重新验证。
+
+## UI 设计绑定与逻辑证据
+
+UI 拆票必读 <Path>{roots.workflows}/specdev/common/rules/design-contract.md</Path> 与已批准 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>。UI Ticket 使用 `ui_change: true` 和 `design_ref: {revision, digest, pages, acceptance}` 固定本 change 设计版本、designDigest、页面 ID 与验收 ID；Map 给出共同基线与读取位置。expected_changes 明确命中 UI 文件时同样需要绑定，不能以缺字段绕过。纯非 UI 票可省略或设 ui_change=false、design_ref=null，不制造 UI 门禁。
+
+将组件复用、页面/状态、响应式与真实浏览器验收放入相应垂直切片；缺确认或摘要漂移返回 P，不让执行者重新选择。LOGIC 证据保留 locator/hash，模拟原型不能自动成为生产实现。

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。