@namewta/speculo 1.0.2 → 1.0.4

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 (83) hide show
  1. package/README.md +8 -3
  2. package/package.json +2 -2
  3. package/template/AGENTS.md +3 -1
  4. package/template/canonical/canonical-specdev-goal-plan.md +757 -225
  5. package/template/canonical/canonical-specdev-grill-with-docs.md +221 -133
  6. package/template/canonical/canonical-specdev-spec.md +73 -3
  7. package/template/canonical/canonical-specdev-tickets.md +681 -252
  8. package/template/canonical/canonical-specdev-wayfinder.md +330 -113
  9. package/template/commands/archive-and-consolidate.md +39 -3
  10. package/template/commands/git-history-squash.md +76 -0
  11. package/template/commands/git-repository-audit.md +3 -602
  12. package/template/commands/references/git-repository-audit-procedure.md +608 -0
  13. package/template/skills/archive-and-consolidate/SKILL.md +1 -1
  14. package/template/skills/archive-and-consolidate/references/entry-procedure.md +11 -3
  15. package/template/skills/git-history-squash/SKILL.md +2 -0
  16. package/template/skills/git-history-squash/references/entry-procedure.md +1 -1
  17. package/template/skills/writing-great-skills/SKILL.md +2 -0
  18. package/template/skills/writing-great-skills/references/document-contract.md +23 -0
  19. package/template/workflows/learning/common/rules/activation-and-memory.md +7 -3
  20. package/template/workflows/ops/common/rules/activation-and-memory.md +7 -3
  21. package/template/workflows/person/common/rules/activation-and-memory.md +7 -3
  22. package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md +13 -136
  23. package/template/workflows/specdev/G-grill-with-docs/references/interview-procedure.md +134 -0
  24. package/template/workflows/specdev/I-implement/I-implement.md +15 -189
  25. package/template/workflows/specdev/I-implement/evidence-template.md +12 -0
  26. package/template/workflows/specdev/I-implement/execution-preflight.md +1 -1
  27. package/template/workflows/specdev/I-implement/references/implementation-procedure.md +192 -0
  28. package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +28 -143
  29. package/template/workflows/specdev/P-goal-plan/completion-control.md +1 -1
  30. package/template/workflows/specdev/P-goal-plan/references/goal-lifecycle.md +35 -0
  31. package/template/workflows/specdev/P-goal-plan/references/goal-tickets-map-template.md +15 -0
  32. package/template/workflows/specdev/P-goal-plan/references/map-control.md +28 -0
  33. package/template/workflows/specdev/{O-orchestrate-implementation/O-orchestrate-implementation.md → P-goal-plan/references/multi-change-plan.md} +21 -33
  34. package/template/workflows/specdev/P-goal-plan/references/replan-and-recovery.md +21 -0
  35. package/template/workflows/specdev/P-goal-plan/references/single-change-plan.md +149 -0
  36. package/template/workflows/specdev/R-review-architecture/R-review-architecture.md +48 -53
  37. package/template/workflows/specdev/R-review-architecture/architecture-review-template.md +19 -10
  38. package/template/workflows/specdev/R-review-architecture/proposal-to-ticket.md +3 -1
  39. package/template/workflows/specdev/R-review-architecture/review-rubric.md +52 -0
  40. package/template/workflows/specdev/README.md +36 -216
  41. package/template/workflows/specdev/T-tickets/T-tickets.md +19 -230
  42. package/template/workflows/specdev/T-tickets/references/planning-procedure.md +233 -0
  43. package/template/workflows/specdev/T-tickets/ticket-template.md +16 -0
  44. package/template/workflows/specdev/T-tickets/tickets-map-template.md +14 -0
  45. package/template/workflows/specdev/T-triage/T-triage.md +3 -1
  46. package/template/workflows/specdev/W-wayfinder/W-wayfinder.md +24 -118
  47. package/template/workflows/specdev/W-wayfinder/references/initiative-discovery.md +29 -0
  48. package/template/workflows/specdev/W-wayfinder/references/initiative-template.json +8 -0
  49. package/template/workflows/specdev/W-wayfinder/references/map-traversal.md +120 -0
  50. package/template/workflows/specdev/W-wayfinder/wayfinder-map-template.md +4 -0
  51. package/template/workflows/specdev/common/README.md +1 -1
  52. package/template/workflows/specdev/common/rules/activation-and-memory.md +7 -3
  53. package/template/workflows/specdev/common/rules/artifact-contract.md +10 -2
  54. package/template/workflows/specdev/common/rules/operating-governance.md +38 -0
  55. package/template/workflows/specdev/common/rules/parent-implementation-orchestration.md +6 -2
  56. package/template/workflows/specdev/common/rules/skill-invocation.md +27 -0
  57. package/template/workflows/specdev/common/rules/workflow-routing.md +24 -0
  58. package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md +93 -0
  59. package/template/workflows/specdev/common/schemas/goal-tickets-map.schema.json +33 -0
  60. package/template/workflows/specdev/common/schemas/initiative.schema.json +94 -0
  61. package/template/workflows/specdev/common/schemas/ticket.schema.json +168 -1
  62. package/template/workflows/specdev/common/schemas/tickets-map.schema.json +74 -6
  63. package/template/workflows/specdev/common/skills/code-review/SKILL.md +3 -2
  64. package/template/workflows/specdev/common/skills/code-review/references/risk-review.md +25 -0
  65. package/template/workflows/specdev/common/skills/plan-quality-review/SKILL.md +10 -0
  66. package/template/workflows/specdev/common/skills/plan-quality-review/references/checklist.md +13 -0
  67. package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +5 -83
  68. package/template/workflows/specdev/common/skills/subagent-delivery/references/dispatch-and-accept.md +87 -0
  69. package/template/workflows/specdev/common/tools/README.md +14 -2
  70. package/template/workflows/specdev/common/tools/plan-contract.mjs +256 -0
  71. package/template/workflows/specdev/common/tools/ticket-control.mjs +251 -0
  72. package/template/workflows/specdev/common/tools/validate-specdev.mjs +58 -40
  73. package/template/workflows/specdev/manifest.json +97 -1
  74. package/template/canonical/canonical-specdev-orchestrate-implementation.md +0 -2839
  75. package/template/workflows/specdev/O-orchestrate-implementation/implementation-evidence-template.md +0 -39
  76. package/template/workflows/specdev/O-orchestrate-implementation/implementation-map-template.md +0 -50
  77. package/template/workflows/specdev/O-orchestrate-implementation/implementation-plan-template.md +0 -61
  78. package/template/workflows/specdev/R-review-architecture/architecture-report-contract.md +0 -123
  79. package/template/workflows/specdev/R-review-architecture/architecture-review-report-template.html +0 -106
  80. /package/template/workflows/specdev/{O-orchestrate-implementation/conflict-and-drift.md → P-goal-plan/references/multi-conflict-and-drift.md} +0 -0
  81. /package/template/workflows/specdev/{O-orchestrate-implementation/execution-loop.md → P-goal-plan/references/multi-execution-loop.md} +0 -0
  82. /package/template/workflows/specdev/{O-orchestrate-implementation/input-readiness.md → P-goal-plan/references/multi-input-readiness.md} +0 -0
  83. /package/template/workflows/specdev/{O-orchestrate-implementation/super-dag.md → P-goal-plan/references/multi-super-dag.md} +0 -0
@@ -1,266 +1,86 @@
1
1
  # SpecDev Activation Contract
2
2
 
3
- 本合同只在用户明确激活 SpecDev Work 后读取。它定义所有 Works 共享的启动、恢复、状态、所有权、路由和验证规则;具体 Work 仍只加载当前步骤需要的分支文件与共享规则。
4
-
5
- SpecDev 将“理解、决定、规划、执行、验证、沉淀”拆成职责清晰的工件链。目标不是让文档尽可能长,而是让每一层拥有明确权威,并让后续模型无需重新决定前一层已经锁定的事项。
3
+ 只在用户明确激活 SpecDev Work 后读取。先选择当前模式,再按条件读取参考;不默认展开所有 Work、历史 change、示例或永久知识。
6
4
 
7
5
  ## 运行时根
8
6
 
9
- - 工作流根:`<Path>{roots.workflows}/specdev/</Path>`
10
- - 状态根:`<Path>{roots.state}/specdev/</Path>`
11
-
12
- 任何具体文件或目录引用必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`。禁止内部相对链接、裸文件名和机器绝对路径。
13
-
14
- ## 工件链
15
-
16
- ```text
17
- 远程 Issue、指定内容或对话
18
-
19
- Triage 冻结为本地 Source
20
-
21
- Diagnose / Grill / Wayfinder / Prototype / Code Review / Architecture Review
22
-
23
- Spec 外部行为、范围、验收合同与关键约束
24
-
25
- Ticket 单一垂直切片的决策完备微计划
26
-
27
- Tickets Map 总体背景、项目 Skill 路由、DAG、合同覆盖、Ready 与并行投影
28
-
29
- Goal Plan 仅在需要时编排跨 Ticket Gate、Wave、owner 与恢复
30
-
31
- Implement 在既定契约内设计、TDD、审查、验证和交接
32
-
33
- Evidence 实际修改、命令、结果、偏差和残余风险
34
-
35
- Learn Change 围绕已完成实现提问并追加零基础 Markdown / ASCII 图解(按需)
36
-
37
- Triage 本地完成后按确认回写/关闭支持的远程 Issue
38
-
39
- Archive 归档历史并将经验证知识提升为当前长期知识
40
- ```
7
+ 工作流:`<Path>{roots.workflows}/specdev/</Path>`;状态:`<Path>{roots.state}/specdev/</Path>`。具体路径遵守 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`,不使用内部相对链接、裸文件名或机器绝对路径。
41
8
 
42
- 多个已经完成 Ready Spec 与 Ready Tickets 的 change 需要在一个会话持续实现时,O-orchestrate-implementation 额外创建一个父实现 change;父 Implementation Map/Plan 位于上述单 change 链之外,只编排实现,不参与或替代任何子 change 的需求澄清、Spec 或 Ticket 生产。
43
-
44
- 核心状态工件:
45
-
46
- - `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
47
- - `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
48
- - `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
49
- - `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
50
- - `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
51
- - `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
52
- - `<Path>{roots.state}/specdev/changes/{change}/implementation-map.md</Path>`
53
- - `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>`
54
- - `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
55
- - `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
56
- - `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
57
- - `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
58
- - `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
59
- - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`
60
- - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>`
61
- - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>`
62
- - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
63
- - `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`
64
-
65
- `{design-id}` 由 P-prototype 在当前 change 内分配为最小未占用的 `UI-NNN`;设计系统文档是设计权威,comparison 与 final 是其可运行投影。`{number}` 与 `{topic}` 由 L-learn-change 根据已有学习索引和当前问题分配,不属于 Learning workflow 的知识编号。
66
-
67
- 工件职责和冲突裁决位于 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`。
9
+ ## 工件链与权威
68
10
 
69
- ## 持久化约定
11
+ 大需求 → W 的 Initiative 候选图 → 每个 change 自己的 G/Grill → S/Spec → T 的计划型 Ticket 与 tickets-map → P 的 Goal → I/实现与 Evidence → Goal 集成验收 → 按需学习/远程 reconcile/归档。
70
12
 
71
- `speculo init` 创建固定状态骨架:
72
-
73
- - 全局状态:`<Path>{roots.state}/specdev/status.json</Path>`
74
- - 活跃 change:`<Path>{roots.state}/specdev/changes/</Path>`
75
- - 历史归档:`<Path>{roots.state}/specdev/archive/</Path>`
76
-
77
- 刷新时 CLI 依据 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 处理持久化数据:配置使用 baseline 三方合并,登记的状态 schema 使用显式 migrator,其他 runtime 文件按字节保留。只有字段删除或结构迁移时才在 `<Path>{roots.state}/back/</Path>` 写入 targeted backup;冲突在替换 active 安装前阻塞。`<Path>{roots.state}/back/</Path>`、`<Path>{roots.state}/install.json</Path>`、`<Path>{roots.state}/managed.json</Path>` 与 `<Path>{roots.state}/baselines/</Path>` 均不属于 SpecDev 写入 namespace。
78
-
79
- 初始化设置 work 首次运行时生成配置并创建空的永久 namespace:
80
-
81
- - 全局配置:`<Path>{roots.state}/specdev/config.json</Path>`
82
- - 追踪规则:`<Path>{roots.state}/specdev/.config/tracking.md</Path>`
83
- - 领域布局:`<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
84
- - 永久 ADR:`<Path>{roots.state}/specdev/adr/</Path>`
85
- - 永久领域上下文:`<Path>{roots.state}/specdev/context/</Path>`
86
- - 永久研究:`<Path>{roots.state}/specdev/research/</Path>`
87
-
88
- 初始化只保证永久目录存在,不写知识内容。只有 A-archive-and-consolidate 在 change 完成、实现证据验证、毕业评估和用户确认后,才能创建、合并或改写这些永久 namespace 中的内容;其他 Works 只读。
89
-
90
- 单个 change 可以包含:
91
-
92
- - `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`
93
- - `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
94
- - `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
95
- - `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
96
- - `<Path>{roots.state}/specdev/changes/{change}/diagnostics/</Path>`
97
- - `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
98
- - `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
99
- - `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
100
- - `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
101
- - `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
102
- - `<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
103
- - `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
104
- - `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`
105
- - `<Path>{roots.state}/specdev/changes/{change}/implementation-map.md</Path>`
106
- - `<Path>{roots.state}/specdev/changes/{change}/implementation-plan.md</Path>`
107
- - `<Path>{roots.state}/specdev/changes/{change}/wayfinder-map.md</Path>`
108
- - `<Path>{roots.state}/specdev/changes/{change}/investigation/</Path>`
109
- - `<Path>{roots.state}/specdev/changes/{change}/investigation/comments/</Path>`
110
- - `<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
111
- - `<Path>{roots.state}/specdev/changes/{change}/architecture-review.html</Path>`
112
- - `<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
113
- - `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`
114
- - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`
115
- - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/</Path>`
116
- - `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/</Path>`
117
- - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`
118
- - `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`
119
-
120
- ## 全局治理原则
121
-
122
- 1. **先发现、后询问**:仓库、配置、schema、测试和文档能回答的事实先探索;只询问真正影响行为、架构、风险、范围、迁移或验收的偏好。
123
- 2. **规划深度随风险增长**:Lite、Standard、Deep 由复杂度和事故半径决定,不由文档长度决定。
124
- 3. **Ticket 是微型计划**:每个 Ready Ticket 决策完备,但不展开逐行代码。
125
- 4. **Goal Plan 按需出现**:只在跨 Ticket 编排复杂度需要时生成,不以固定章节数量作为质量标准。
126
- 5. **证据优先**:每个验收合同、Ticket 和 Gate 都必须有可重复验证与 Evidence。
127
- 6. **路径所有权**:并发实现者只能修改授权项目路径;shared path 有唯一 owner。
128
- 7. **偏差显式化**:计划与事实冲突时停止、记录、修订,不静默扩大范围或改写契约。
129
- 8. **状态单一来源**:Ticket frontmatter 是单 Ticket 状态权威;Map 和 Goal Plan 是投影与编排。
130
- 9. **知识以当前真相为目标**:归档保留历史,永久知识只保留仍真实且经实现验证的结论。
131
- 10. **恢复依赖权威工件**:跨 Work 或 Agent 边界时同步 active change 的 `current_work`,成功完成后去重更新 `works_run`,返回下一 Work 和权威工件的完整路径。
132
- 11. **本地执行权威**:远程 Issue/PR/URL 只作为来源或完成投影;Spec、Ticket、Map、Goal Plan、Evidence 和状态始终以本地工件为准。
133
- 12. **完成与归档分离**:本地完成按 change completion 合同决定;远程 close 失败不回滚完成,但必须 reconcile 或 waive 后才归档。
134
- 13. **Lead 与隔离正交**:Lead 固定拥有 SpecDev 状态、Evidence 与父分支;是否派遣 subagent 由 Lead 动态决定。Goal Plan 创建时询问 Ticket 是否开启 worktree,默认不开启;选择只作用于当前 Goal Plan。
135
- 14. **策略化验收**:current 模式使用当前 workspace 严格串行、direct-parent 验证;required 模式使用 source worktree 与 parent-candidate。只有 required 模式创建独立 Ticket worktree。
136
- 15. **父子权威隔离**:父实现 change 只拥有 Ready 子 change 的组合 Ticket DAG、serialization、全局 workspace/资源和实现进度投影;子 change 继续拥有全部行为与实现合同。一个未完成子 change 只能属于一个未完成父实现 change。
137
-
138
- 共享规则:
139
-
140
- - `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
141
- - `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
142
- - `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>`
143
- - `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`
144
- - `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
145
- - `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>`
146
- - `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
147
- - `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
148
- - `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`
149
- - `<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`
150
-
151
- ## 启动协议
13
+ 已明确的小请求直接进入适用阶段;无需为了路由而创建 Triage。跨 change 实现由 P 统一管理。
152
14
 
153
- 1. 解析 workflow state roots
154
- 2. 读取 `<Path>{roots.state}/specdev/config.json</Path>`;不存在时运行 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。
155
- 3. 读取 `<Path>{roots.state}/specdev/status.json</Path>`:用户指定 change 优先;唯一活跃 change 直接使用;无活跃时创建;多个候选时请求消歧。
156
- 4. 读取当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`。若当前 change 是未完成父 Implementation Map 的成员,同时读取父 Map/Plan;父 O Work 自身恢复时以父产物为入口,不逐个手工激活成员。
157
- 5. 若当前 change 已有非空 `current_work`,先恢复或显式结束该 Work;否则将 `current_work` 设置为本次 work id。
158
- 6. 只加载当前步骤需要的 work 子文件和共享规则。
159
- 7. 完成后写入产物、运行适用校验、更新 change 状态和 `works_run`;全局状态只更新 active/archived 索引。
15
+ Ticket frontmatter 拥有本票状态、依赖、写集与 Skill 调用绑定;普通 map 是背景/路由/图投影;Goal Plan 拥有 Gate、workspace 和恢复决策。多 change 父 tickets-map 只指向原 Implementation Map/Plan,不复制状态。一个未完成 child 仍只能归属于一个未完成父 Goal
160
16
 
161
- Change 从 active/blocked 转为 completed 时加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`:有 Goal Plan 时由其中唯一 Lead 拥有转换;无 Goal Plan 的 Ticket/Direct Spec 由当前 I owner 拥有;非实现型终点由最终验收工件 owner 拥有。Archive 不补造 completed。
17
+ 具体职责与冲突裁决读取 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`;新增调用合同读取 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>`。
162
18
 
163
- ## 状态字段
164
-
165
- `<Path>{roots.state}/specdev/status.json</Path>` 使用全局 schema v5;Spec/Ticket/Tickets Map 继续使用各自 schema v3,config 使用 schema v5,Goal Plan 使用 schema v6,Implementation Map/Plan 使用 schema v1,`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 使用 schema v6:
19
+ ## 持久化约定
166
20
 
167
- - `schema_version`(数字):全局状态 schema 版本,固定为 `5`。
168
- - `workflow`(字符串):workflow 标识,固定为 `"specdev"`。
169
- - `active`(对象数组):当前活跃 change 的严格索引;每项只能包含 `change`,格式 `"YYYY-MM-DD-<kebab-topic>"`。
170
- - `archived`(去重字符串数组):已归档 change 名称。详细归档时间、路径和 promotion 摘要只存在于 `<Path>{roots.state}/specdev/archive/YYYY-MM/{change}/.status.json</Path>`。
21
+ CLI 初始化和刷新保持原 namespace、三方配置合并、schema migrator 与 opaque 文件按字节保留。Work 不写 CLI-owned backup、install 或 managed 元数据。创建、恢复、迁移、关闭或归档时必须读取 `<Path>{roots.workflows}/specdev/common/rules/workflow-state-and-lifecycle.md</Path>`。
171
22
 
172
- `active[].change` 必须唯一,且不得同时出现在 `archived`。`current_work`、`works_run` 和 `claimed_investigations` 只存在于 change 自有 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`:开始 Work 时设置 `current_work`;暂停或可恢复阻塞时保留;成功完成时加入 `works_run` 并清空;取消时清空但不加入。逐次时间、结果和审计证据由 change 自有状态、Work 主产物、Evidence 或 LOG 承载,不写入全局索引。
23
+ 永久 ADR/context/research A 在完成证据、毕业评估和用户确认后通过原网关提升;其他 Work 只读,初始化不写知识内容。
173
24
 
174
- `<Path>{roots.state}/specdev/config.json</Path>` 的 `execution.max_implementation_agents`、`max_integration_attempts` 和 planning UI 设计候选字段均为可配置正整数;候选默认值与上限必须落在 2-4 且默认值不大于上限。仅 implementation subagent 受前者约束且不含 Lead,current workspace 仍保持单 writer 串行安全不变量;只读 review/research/test-observation agent 不设 SpecDev 数字上限。
25
+ ## 启动协议
175
26
 
176
- `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` `worktrees` 保存 Ticket 级 `base_sha`、父分支、workspace/implementation/integration owner、workspace locator、implementation/source checkpoint、适用 candidate/result SHA、验证、E2E disposition 与生命周期状态。current 记录使用 `workspace_ref=current` 和 direct-parent;required 记录使用 source/parent-candidate。每个实现 Ticket 都有一条记录;父分支只有在对应策略的验证通过后推进。`removed` 是 required 集成后来源 branch/worktree 完成清理的终态,必须保留全部集成与 E2E 证据。
27
+ 1. 解析 roots,读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;定位相关 entry 后回读必要原文,不默认整读索引。
28
+ 2. 读取 `<Path>{roots.state}/specdev/config.json</Path>`;不存在时使用 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。保留已知配置,不重复询问。
29
+ 3. 从 `<Path>{roots.state}/specdev/status.json</Path>` 定位用户指定或唯一 active change;多个候选需要真实消歧,无候选按原规则创建。
30
+ 4. 读取 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`;恢复、创建或状态修改时加载上述状态细则。child 归属未完成父 Goal 时读取对应父 Map/Plan,不接管或覆盖其 owner。
31
+ 5. current_work 非空则恢复或显式 handoff;暂停保留恢复键,成功才去重更新 works_run 并清空。其他任务冲突只暂停受影响分支,继续独立、已授权工作。
32
+ 6. 按 Work/模式读取必要参考,完成产物、运行验证、回读真实源与状态后再推进。全局状态仅更新本任务 active/archived 索引。
177
33
 
178
- 领域状态枚举:
34
+ ## 状态字段
179
35
 
180
- - change:`active | blocked | completed | archived`
181
- - Ticket:`draft | ready | in_progress | blocked | review | done | deviated | cancelled`
182
- - Investigation status:`open | closed`
183
- - Investigation resolution:`answered | out-of-scope | superseded | cancelled | null`
184
- - Planning Depth:`lite | standard | deep`
185
- - Worktree:`planned | active | review | integrating | integrated | removed | blocked`
36
+ 全局 status/config 保留 v5;change status Goal Plan 保留 v6;Spec/Ticket/Map 保留 v3,新增 Plan 扩展版本 1;父 Map/Plan 保留 v1。详细字段、枚举、worktree Evidence 与旧工件兼容见状态细则,不为压缩文档另建状态库。
186
37
 
187
38
  ## 路径分配
188
39
 
189
- 1. workflow 运行状态写入 `<Path>{roots.state}/specdev/</Path>`。
190
- 2. change 产物写入 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。
191
- 3. 项目代码、测试和用户要求的项目文档写入项目路径;Evidence 仅保存项目相对指针。
192
- 4. 长期知识候选先在 change 内形成;只有 A 在完成证据、毕业评估和用户确认全部通过后,才提升到对应永久 namespace。
40
+ 状态写在当前 change 授权 namespace;实现写在项目授权路径。源文件优先于生成物,保留链接和必要元数据;不改系统或插件缓存。路径归属、共享资源或工作树未知时暂停对应写集。规划/执行/恢复/验收必须读取 `<Path>{roots.workflows}/specdev/common/rules/operating-governance.md</Path>` 和当前步骤声明的所有权规则。
193
41
 
194
42
  ## 副作用边界
195
43
 
196
- 未经用户明确授权不得提交、推送、合并、删除来源 branch/worktree、部署、发布、移动归档、写入/关闭远程 Issue 或执行不可逆迁移。Ready Goal Plan/Ticket 执行必须明确取得 implementation commit 与所选 direct-parent/candidate integration/父分支更新授权;required 模式该授权包含 transient candidate checkout/branch 生命周期,不扩展到来源 cleanup、远端或生产动作。只读探索、change 工件生成和已授权验证可以进行。远程开发投影仅由 Triage reconcile 执行;Retro command 的 Speculo 反馈 Issue 是独立 command 边界。敏感值不得写入 `<Path>{roots.state}/specdev/</Path>`。
44
+ 规划不授权实现。提交、推送、合并/父分支更新、来源 branch/worktree 清理、部署、发布、远程 Issue 写入、归档移动、永久知识修改和不可逆迁移仍须原入口取得明确授权;文档中的标记不能授予权限。正式记忆写入前检查 pending transaction、lock recovery evidence;不抢占他人事务。
45
+
46
+ 保留原 current 严格串行/direct-parent 默认;worktree 策略在 Goal 创建时按原规则确认,required 使用 source worktree/parent-candidate。Lead 拥有状态、父分支与 E2E;implementation subagent 数量服从 config,只读 review/research/test-observation 不新增数字上限。用户明确的工具与交付数量、UI 默认 3/上限 4、W 每会话最多完成一张调查票均不因精简而改变。
197
47
 
198
48
  ## 场景路由
199
49
 
200
- | 场景 | 入口 | 正常出口 |
201
- |---|---|---|
202
- | 远程 Issue、URL、文件或对话摄入 | T-triage intake | D / G / W / P / S / C / T |
203
- | 本地 change 完成且来源可关闭 | T-triage reconcile | A |
204
- | 疑难 bug 或性能回归 | D-diagnose-bugs | S / T / I / R / W |
205
- | 模糊但可通过决策访谈收敛 | G-grill-with-docs | P / S / T / W |
206
- | 路径超出单次上下文 | W-wayfinder | G / P / D / S / T |
207
- | 需要检测项目 UI、选择设计方向并生成可运行设计包 | P-prototype | G / S / T / I |
208
- | 固定点 diff、branch 或 PR review | C-code-review | completed / T / S / G |
209
- | 外部行为已清楚 | S-spec | T-tickets |
210
- | Ready Spec 需要垂直切片 | T-tickets | P-goal-plan / I |
211
- | 多 Ticket 协调 | P-goal-plan | I / Triage / A |
212
- | 多个 Ready change 的持续实现 | O-orchestrate-implementation | I-implement 循环 / completed / blocked |
213
- | Ready 执行 | I-implement | Triage / A / blocked / deviation |
214
- | 开发完成后需要理解当前 change 或追问实现 | L-learn-change | 返回用户 / 继续提问 / Triage / A |
215
- | 架构健康扫描 | R-review-architecture | G / T |
216
-
217
- 同 change 下一阶段需要当前一手推理且上下文健康时继续;切换 repo/person/harness 或旁路时使用 `<Path>{roots.commands}/handoff.md</Path>`;严格限定且可独立派单时使用 Dispatch Packet;其他长上下文以权威工件路径恢复。平台不支持 clear/compact 时不虚构操作。
50
+ 不清晰的大需求选 W,单 change 的高影响决定选 G,Ready Spec 拆票选 T-tickets,一个或多个 Ready change 的 Goal 选 P-goal-plan;来源冻结/远程回写才选 T-triage。精确条件与全部出口见 `<Path>{roots.workflows}/specdev/common/rules/workflow-routing.md</Path>`。
218
51
 
219
52
  ## Work 条目
220
53
 
54
+
221
55
  <!-- AUTO-INDEX-START -->
222
56
 
223
57
  - **A-archive-and-consolidate** — 归档与沉淀:校验本地完成与远程 reconcile 门,复用全局归档能力移动 completed change 并提升当前知识,或从代码访谈形成可归档知识 change。
224
58
  - **C-code-review** — 代码审查:将 commit、branch、tag、merge-base 或 PR 解析为本地不可变固定点,执行隔离的标准轴与规范轴审查并持久化可恢复报告。
225
59
  - **D-diagnose-bugs** — 诊断 Bug:先建立会在精确症状上变红的紧凑反馈回路,再通过最小化、排名假设和单变量探针确认根因,输出修复契约而不实施生产修复。
226
- - **G-grill-with-docs** — 设计访谈(带文档):以完整 frontier 逐轮推进设计树,直到每个决策分支都已关闭并获得用户共识,同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
227
- - **I-implement** — 实现:基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、按 Goal Plan 选择的 current workspace 或 Ticket worktree 提交、直接父分支或候选合并验证和 Lead Evidence 回写。
60
+ - **G-grill-with-docs** — Change 决策访谈:一个已界定 change 仍有产品、领域或架构决定待确认时进行可恢复访谈;跨 change 边界未清晰时先用 W。
61
+ - **I-implement** — 实现与验收:执行已授权的 Ready Ticket 或获批 Direct Spec,产生可回读实现和验收证据;不从模糊需求直接写代码。
228
62
  - **I-init-setup** — 初始化设置:初始化 SpecDev 的语言、配置、全局状态、本地 change 追踪、领域知识布局、验证命令和并发治理。
229
63
  - **L-learn-change** — Change 学习:在开发完成后围绕当前 SpecDev change 回答问题,并用面向零专业背景读者的 Markdown 与 ASCII 图解持续记录理解。
230
- - **O-orchestrate-implementation** — 编排实现:将两个或以上已完成 Ready Spec 与 Ready Tickets 的 change 编译为跨 change implementation super-DAG,并由单一 Lead 在一个会话中持续调度实现、验证和集成。
231
- - **P-goal-plan** — 目标规划:在跨 Ticket 协调复杂度需要时,以固定 Lead、动态派单、DAG/Gate 和候选合并门禁生成决策完备且可恢复的执行计划。
64
+ - **P-goal-plan** — Goal 规划与执行:为一个或多个 Ready change 规划、执行或恢复 Goal;只在用户要求交付编排或已有 map 需推进时使用,不代替需求探索和 Ticket 编写。
232
65
  - **P-prototype** — UI 设计原型:检测现有项目的 UI 事实,按产品任务推荐并逐步选择设计风格,生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
233
- - **R-review-architecture** — 架构审查:从用户指定范围或 Git 热点扫描代码库的深化机会,以持久化可视化 HTML 呈现候选,并对用户选择的一个方案运行设计树访谈。
66
+ - **R-review-architecture** — 架构审查:从用户指定范围或 Git 热点扫描代码库中的结构性坏味道、代码 judo 机会和维护性风险,以中文 Markdown 记录高置信候选,并对用户选择的一个方案运行设计树访谈。
234
67
  - **S-spec** — 编写 Spec:综合已知事实、设计决定、诊断与代码现状,产出以外部行为和验收合同为权威的 Ready Spec。
235
- - **T-tickets** — 拆分 Tickets:将 Spec、计划或已确认对话拆成曳光弹式垂直切片;每个 Ticket 决策完备、可独立验证、适配单一上下文,并建立阻塞 DAG、路径所有权和执行就绪门禁。
236
- - **T-triage** — 请求分诊:把远程 Issue、URL、文件或对话冻结为本地来源工件,完成风险分诊与路由,并在本地 change 完成后受控回写和关闭支持的远程 Issue
237
- - **W-wayfinder** — 寻路:为超出单次会话且路径尚不可见的工作建立本地共享地图,逐个解决 research、prototype、grilling task Ticket,直到目的地路线决策完备。
68
+ - **T-tickets** — 编写计划型 Tickets:将已澄清的 Spec 或等价获批计划拆为可验收的实施 Ticket,并绑定真实项目 Skill;不用于探索未知需求或执行代码。
69
+ - **T-triage** — 请求分诊:需要冻结外部来源、审计摄入或对 completed change 回写来源 Issue 时使用;已清晰的本地需求不必经本入口路由。
70
+ - **W-wayfinder** — 探索大需求与 Change 边界:大需求的 change 边界或实施路线尚不可见时建立探索地图,并分别澄清各 change;已有清晰 Spec 时不触发。
238
71
 
239
72
  <!-- AUTO-INDEX-END -->
240
73
 
74
+
241
75
  ## Common 目录
242
76
 
243
- - 总览:`<Path>{roots.workflows}/specdev/common/README.md</Path>`
244
- - Rules:`<Path>{roots.workflows}/specdev/common/rules/</Path>`
245
- - Schemas:`<Path>{roots.workflows}/specdev/common/schemas/</Path>`
246
- - Tools:`<Path>{roots.workflows}/specdev/common/tools/</Path>`
247
- - Skills:`<Path>{roots.workflows}/specdev/common/skills/</Path>`
248
- - 激活与记忆读取规则:`<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`
77
+ `<Path>{roots.workflows}/specdev/common/README.md</Path>` 只作定位;按当前 Work 指针选中 rule/schema/tool/skill,不默认展开整个目录。
249
78
 
250
79
  ## 自动校验
251
80
 
252
- 校验一个 change:
253
-
254
- ```bash
255
- node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
256
- --stage <triage|diagnosis|grill|spec|tickets|goal-plan|implement|learn-change|review|prototype|wayfinder|orchestrate-implementation|complete> \
257
- <Path>{roots.state}/specdev/changes/{change}</Path>
258
- ```
259
-
260
- 校验工作流包:
261
-
262
81
  ```bash
82
+ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage <stage> --repo <project-root> <Path>{roots.state}/specdev/changes/{change}</Path>
263
83
  node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
264
84
  ```
265
85
 
266
- 激活后读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`:先定位相关 entry,再回读少量原文与 provenance;正式写入前检查 owner/gateway、pending transaction、lock 和 recovery evidence。
86
+ 支持 triage、diagnosis、grill、spec、tickets、goal-plan、implement、learn-change、review、prototype、wayfinder、complete。Goal 总控通过 P 的 map-control 参考使用只读控制器;它不授权或自动执行。完成转换必须读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`,票全 done 不替代整体验收。
@@ -2,246 +2,35 @@
2
2
  id: specdev/tickets
3
3
  type: workflow-entry
4
4
  workflow: specdev
5
- name: 拆分 Tickets
6
- description: Spec、计划或已确认对话拆成曳光弹式垂直切片;每个 Ticket 决策完备、可独立验证、适配单一上下文,并建立阻塞 DAG、路径所有权和执行就绪门禁。
7
- keywords: [tickets, 拆分, 垂直切片, 阻塞, 曳光弹, decision-complete, readiness]
5
+ name: 编写计划型 Tickets
6
+ description: 将已澄清的 Spec 或等价获批计划拆为可验收的实施 Ticket,并绑定真实项目 Skill;不用于探索未知需求或执行代码。
7
+ keywords: [ticket, Plan Mode, 垂直切片, Skill绑定, DAG]
8
8
  ---
9
9
 
10
- # 拆分 Tickets
10
+ # 编写计划型 Tickets
11
11
 
12
- > 激活本 Work 后,先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`,再执行本入口。
12
+ > 激活后读取 `<Path>{roots.workflows}/specdev/README.md</Path>`。
13
13
 
14
- Ticket 是**决策完备的微型执行计划**:它消除执行者在目标、范围、公共契约、关键顺序和验收上的关键决策,但不展开逐行代码、局部变量或可从现有惯例自然推导的实现细节。
15
-
16
- 本 work 保留原有能力:代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。
14
+ 每张票都是供新上下文执行的 Plan:说明背景、来源、目标、非目标、真实项目 SKILL 调用、修改顺序、验证和失败停止点。Tickets Map 是统一启动与恢复入口,不是静态清单;它不复制 Ticket 的状态权威。
17
15
 
18
16
  ## 读取范围
19
17
 
20
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
21
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
22
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
23
-
24
-
25
- ## 输入
26
-
27
- 优先读取:
28
-
29
- - 当前 Spec:`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
30
- - 当前架构决策:`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
31
- - 当前领域上下文:`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
32
- - 当前设计日志:`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
33
- - Bug 诊断:`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
34
- - 永久架构决策:`<Path>{roots.state}/specdev/adr/</Path>`
35
- - 永久领域上下文:`<Path>{roots.state}/specdev/context/</Path>`
36
- - 项目 Agent 指令及其声明的项目 Skill 根;
37
- - 项目当前代码、测试、配置、schema 和 CI 事实。
38
-
39
- 若尚无 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`,只有在用户提供的计划或对话已经等价覆盖目标、范围、关键决定和可判定验收时才可继续;否则建议先运行 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`。
40
-
41
- ## 流程
42
-
43
- ### 1. 输入预检
44
-
45
- 1. 先读取上游工件索引,按当前 Ticket 的依赖、缺口和冲突关键词定位,再回读相关工件;
46
- 2. 检查 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 的 `ready_for_tickets`;
47
- 3. 按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 处理 Spec、ADR、用户决定与代码事实的冲突;
48
- 4. 将未知项分类为可发现事实、高影响用户决定和低影响实现细节;
49
- 5. 高影响未决问题没有关闭时停止,不通过更详细的 Ticket 文字伪装决策完备。
50
-
51
- **完成标准**:拆分依据、权威顺序、合同范围与未决问题已明确。
52
-
53
- ### 2. 探索代码库与实现地形
54
-
55
- 如果尚未探索,进行只读探索:
56
-
57
- - 找到行为入口、稳定接口、测试接缝、数据流和错误路径;
58
- - 查找相邻或类似实现,优先复用项目现有模式;
59
- - 识别可能修改的模块、公共路径、共享文件、迁移索引和全局注册点;
60
- - 查找现有测试命令、夹具、类型检查、构建和 CI 门禁;
61
- - 对照 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 使用项目领域词汇;
62
- - 对照 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>` 避免重新争论已接受决策。
63
-
64
- 遇到不熟悉的模块、外部依赖或第三方库时,使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`,再继续拆分。
65
-
66
- #### 项目 Skill 路由
67
-
68
- 1. 读取项目 Agent 指令,确定项目声明的 Skill 根;至少枚举 `<Path>.agents/skills/**/SKILL.md</Path>`,存在其他项目级 Skill 根时一并枚举;
69
- 2. 先读取候选 Skill 的 frontmatter 与入口路由;只有命中当前 change 的 scope、路径、技术域或验证条件时才完整读取,并按其 Skill Map 路由到当前 change 需要的领域 Skill;
70
- 3. 根据 change 索引、每个 Ticket 的 frontmatter、路径、技术域、公共契约、迁移与验证范围,确定 `ALL` 或具体 Ticket 的最低必读集合;只把真实存在且触发条件匹配的项目 Skill 纳入;
71
- 4. 使用项目根相对 Path 记录每个 Skill 的入口文件,同时记录触发 scope、读取时机和用途;不得把 Speculo 自带 Skill 或机器绝对路径伪装成项目 Skill;
72
- 5. 未发现适用项目 Skill 时,记录已扫描的 Skill 根和“无适用项”,不生成虚假路径;项目 Skill 清单是最低集合而非 allowlist。
73
-
74
- #### Prefactor
75
-
76
- 遵循“让变更变容易,然后做容易的变更”:
77
-
78
- - 如果当前接口、依赖或接缝会使后续实现明显不安全或重复,提出前置 prefactor Ticket;
79
- - prefactor 必须说明它解除的具体阻碍;
80
- - prefactor 必须独立有价值且可验证;
81
- - 不为了“更干净”而创建与目标无关的重构 Ticket。
82
-
83
- **完成标准**:实现地形、稳定接缝、共享路径、必要 prefactor 与逐 Ticket 项目 Skill 路由已识别。
84
-
85
- ### 3. 草拟曳光弹式垂直切片
86
-
87
- 加载 `<Path>{roots.workflows}/specdev/T-tickets/decomposition-rules.md</Path>`。每个切片应横向穿过交付该行为所需的最小层次组合,而不是把数据库、后端、前端和测试拆成互相无价值的水平 Ticket。
88
-
89
- 每个 Ticket 必须:
90
-
91
- - 交付一个可观察行为,或一个能独立解除后续阻塞的安全准备能力;
92
- - 完成后可以独立演示、测试或验证;
93
- - 适合一个全新 Agent 上下文在不中断的情况下完成;
94
- - 与其他 Ticket 有实质行为差异;
95
- - 只依赖真正阻止它开始的前置产物;
96
- - 自带至少一种完成证据。
97
-
98
- #### 宽重构例外
99
-
100
- 字段重命名、共享符号类型变化、协议升级等宽机械变更无法安全塞入单个垂直切片时,按以下顺序:
101
-
102
- 1. **Expand**:在旧形式旁增加新形式,保持旧调用方可工作;
103
- 2. **Migrate batches**:按包、目录、消费者或风险分批迁移,每批独立成 Ticket;
104
- 3. **Contract**:确认旧调用点为零后删除旧形式;
105
- 4. 若迁移批次无法各自保持绿色,使用隔离集成分支和最终集成验证 Gate,但仍保留明确的批次与责任边界。
106
-
107
- **完成标准**:每个 Ticket 的可观察产出、真实阻塞边和验证方式已草拟。
108
-
109
- ### 4. 判定规划深度与风险
110
-
111
- 按 `<Path>{roots.workflows}/specdev/common/rules/readiness-and-depth.md</Path>` 为每个 Ticket 标注:
112
-
113
- - `lite`:局部、可逆、沿用既有模式、无公共契约或迁移影响;
114
- - `standard`:大多数多文件或跨层垂直切片;
115
- - `deep`:公共 API/schema、数据迁移、安全/隐私/资金、不可逆操作、expand-contract、共享核心路径、多个 implementation owner 的跨 Ticket 写入协调或高事故半径。
116
-
117
- 规划深度不是优先级,也不是 Gate。每个 Ticket 必须记录触发该深度的原因。
18
+ 先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;按相关条目定位上游 Spec/ADR/CONTEXT、代码与项目 Agent 指令,再回读当前拆分所需原文。只枚举 Skill 的元数据与触发路由,不默认展开全部技能。
118
19
 
119
- ### 5. 写成决策完备 Ticket
20
+ ## 主流程
120
21
 
121
- 使用 `<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>` 填写:
122
-
123
- - 战略目标、可观察产出与来源追踪;
124
- - 当前代码事实和需求差距;
125
- - 已锁定决策、低影响假设和未决问题;
126
- - IN / REUSE / OUT;
127
- - 用户或调用者视角的端到端行为;
128
- - Standard/Deep 的接口、输入输出、不变量、数据流、失败与兼容契约;
129
- - 有序执行路线和安全落点;
130
- - expected、writable、read-only、shared 路径;
131
- - 正常、失败和回归验证矩阵;
132
- - 每个 Ticket 按 Goal Plan 的 workspace 策略定义 current-workspace/direct-parent 或 source-worktree/parent-candidate 检查,以及按实际跨边界风险判定的 E2E disposition;
133
- - 每个实现 Ticket 的 implementation commit 与对应父分支完成条件;仅 required 模式创建独立 worktree;
134
- - Deep 的迁移、兼容窗口、监控、回滚和不可逆批准点;
135
- - 可判定验收标准。
136
-
137
- 路径所有权必须遵守 `<Path>{roots.workflows}/specdev/common/rules/path-ownership.md</Path>`,证据设计必须遵守 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
138
-
139
- ### 6. 构建依赖 DAG、合同覆盖与并发检查
140
-
141
- 1. 使用 Ticket ID 建立 `blocked_by`;
142
- 2. 检测循环和不存在的引用;
143
- 3. 识别根 Ticket、汇合点、扇出与收缩点;
144
- 4. 为每个 Spec 验收合同映射至少一个 Ticket;
145
- 5. 检查并行候选的 `writable_paths` 是否相交;
146
- 6. 共享路径必须指定唯一 owner,通常由专门 Ticket 或明确的集成 owner 修改;
147
- 7. 不得用依赖边表达“可能更方便”或纯粹的人员交接。
148
-
149
- 使用 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` 草拟总体 Map;写入所有 Ticket 共享的总体实施背景与项目 Skill 读取矩阵。矩阵中的每个 Ticket 必须由 `ALL` 或自己的 Ticket ID 覆盖。
150
-
151
- ### 7. Definition of Ready
152
-
153
- 加载 `<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>` 逐个检查。
154
-
155
- 存在以下任一情况时 `ready: false`:
156
-
157
- - 会改变行为、接口、数据、兼容、安全、范围或验收的未决问题;
158
- - 依赖缺失或 DAG 有环;
159
- - 可写路径不明确或并行所有权冲突;
160
- - 验证方法不能执行且没有批准的替代证据;
161
- - Ticket 未声明 E2E required/not-required 及理由,或在 required 模式把 E2E 安排到 source worktree;
162
- - Tickets Map 缺少总体实施背景或项目 Skill 读取矩阵,项目 Skill 路径不存在、不是项目根相对路径,或当前 Ticket 未被 `ALL`/自身 ID 覆盖;
163
- - 无法形成实现 commit 与 Goal Plan 所选 direct-parent/candidate-merge 父分支出口;
164
- - 单个新上下文无法完成;
165
- - Standard/Deep 缺少有序执行路线;
166
- - Deep 缺少迁移、兼容、监控、回滚或批准点。
167
-
168
- ### 8. 与用户核对
169
-
170
- 以完整编号列表展示所有 Ticket,至少包含:
171
-
172
- - 标题;
173
- - 可观察交付;
174
- - 被阻塞于;
175
- - Planning Depth 与触发原因;
176
- - 风险;
177
- - Ready 状态;
178
- - 关键未决问题;
179
- - 预计并行组和共享路径 owner;
180
- - `ALL` 与逐 Ticket 的项目 Skill 最低必读集合。
181
-
182
- 核对:
183
-
184
- - 粒度是否适合单一上下文;
185
- - 是否出现水平切片;
186
- - 阻塞边是否真实;
187
- - 是否应合并、进一步拆分或增加 prefactor;
188
- - 合同是否全部覆盖;
189
- - 路径所有权和验证是否可信。
190
-
191
- 每次修改后重新展示完整列表,直到用户批准。用户明确要求一次性自主规划且不存在高影响未知项时,可使用推荐默认值并把假设写入 Ticket,不为形式重复询问。
192
-
193
- ### 9. 发布
194
-
195
- 创建:
196
-
197
- - Ticket 目录:`<Path>{roots.state}/specdev/changes/{change}/ticket/</Path>`
198
- - Tickets Map:`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`
199
- - Evidence 目录:`<Path>{roots.state}/specdev/changes/{change}/evidence/</Path>`
200
-
201
- 按拓扑顺序写入 Ticket:
202
-
203
- ```text
204
- <Path>{roots.state}/specdev/changes/{change}/ticket/NN-<ticket-name>.md</Path>
205
- ```
206
-
207
- `NN` 使用两位或更多位零填充数字;Ticket frontmatter ID 使用 `T-NN`。Ticket 的 `blocked_by` 使用 Ticket ID,而不是相对文件路径。
208
-
209
- 使用 `<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>` 和 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>` 生成工件,并对照:
210
-
211
- - `<Path>{roots.workflows}/specdev/common/schemas/ticket.schema.json</Path>`
212
- - `<Path>{roots.workflows}/specdev/common/schemas/tickets-map.schema.json</Path>`
213
-
214
- 运行:
22
+ 1. **输入与范围**:确认目标、非目标、用户指定数量、验收合同和未知项。高影响未决问题回到 G;无 Ready Spec 时,只有用户材料已等价覆盖全部合同才可规划。
23
+ 2. **地形与绑定**:定位真实可维护源、调用方、测试接缝和 Skill 根。按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 为每票解析实际 Skill ID、入口摘要、调用阶段、输入、产出与失败动作;没有适用项目 Skill 时记录扫描证据,不造名称。
24
+ 3. **垂直切片**:需要具体拆分时读取 `<Path>{roots.workflows}/specdev/T-tickets/references/planning-procedure.md</Path>` 与 `<Path>{roots.workflows}/specdev/T-tickets/decomposition-rules.md</Path>`。保留 Prefactor、Expand → Migrate → Contract 和真实 DAG,不按技术层制造空价值任务。
25
+ 4. **写 Plan**:使用 `<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>`。Lite 仅减少不适用说明,不删用户数量、权限、验收或停止条件。所有新增票使用 `plan_contract_version: 1`,旧票按迁移协议补齐后再执行。
26
+ 5. **写总控**:使用 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`,记录共同背景、Skill 最低路由、合同覆盖、依赖和明确控制入口;状态仍从票投影。依赖、路径与语义共享资源都需检查。
27
+ 6. **Definition of Ready**:读取 `<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>`,并调用 `<Path>{roots.workflows}/specdev/common/skills/plan-quality-review/SKILL.md</Path>`。缺失引用、必需 Skill、可运行验收或权限边界,当前票不可 ready。
28
+ 7. **与用户核对**:展示全部票、可观察产物、依赖、深度、风险、Skill 和未决问题。保留用户要求的交付数量;已授权自主规划且无关键未知时不重复请求形式确认。
29
+ 8. **验证、回读和交付**:按下述命令检查,再回读真实 Ticket/Map,报告修改、验证结果和未完成项。规划完成不自动进入实现。
215
30
 
216
31
  ```bash
217
- node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
218
- --stage tickets \
219
- --repo <project-root> \
220
- <Path>{roots.state}/specdev/changes/{change}</Path>
32
+ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage tickets --repo <project-root> <Path>{roots.state}/specdev/changes/{change}</Path>
33
+ 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>
221
34
  ```
222
35
 
223
- 更新 `<Path>{roots.state}/specdev/status.json</Path>` `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`。
224
-
225
- ## 完成标准
226
-
227
- - Ticket 目录和 Map 已写入完整 Path 标签 所指位置;
228
- - Spec 合同全部 covered 或有明确批准的 deferred;
229
- - DAG 无环、阻塞引用存在;
230
- - Ready Ticket 无高影响未知项;
231
- - 并行 Ticket 无未解决的可写冲突;
232
- - 每个 Ticket 可独立验证且适配单一上下文;
233
- - Tickets Map 已记录总体实施背景;每个 Ticket 被项目 Skill 读取矩阵覆盖,Skill 路径存在且为项目根相对路径;
234
- - Prefactor 与 expand-contract 使用条件正确;
235
- - 用户已批准拆分或明确授权自主发布;
236
- - 校验器无 error。
237
-
238
- ## 子文件引用
239
-
240
- - 拆分规则:`<Path>{roots.workflows}/specdev/T-tickets/decomposition-rules.md</Path>`
241
- - Ticket 就绪规则:`<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>`
242
- - Ticket 模板:`<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>`
243
- - Tickets Map 模板:`<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`
244
-
245
- ## 下一步
246
-
247
- 满足任一情况时建议运行 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>`:Ticket 数量达到或超过 10、存在多个 implementation owner 的并行写入协调、Deep Ticket、迁移、共享契约、多个 Gate 或高风险发布。只读 review/research 并行本身不触发 Goal Plan;少量线性 Ready Ticket 可直接进入 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`。
36
+ 需要正式 Goal、多 change、迁移或跨票 Gate 时交给 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>`;少量线性票可从 map 按已授权范围调用 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`。不得以“精简”为理由静默更换默认工具或少交付。