@namewta/speculo 1.0.2 → 1.0.3

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 (77) hide show
  1. package/README.md +6 -2
  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/git-repository-audit.md +3 -602
  10. package/template/commands/references/git-repository-audit-procedure.md +608 -0
  11. package/template/skills/writing-great-skills/SKILL.md +2 -0
  12. package/template/skills/writing-great-skills/references/document-contract.md +23 -0
  13. package/template/workflows/learning/common/rules/activation-and-memory.md +7 -3
  14. package/template/workflows/ops/common/rules/activation-and-memory.md +7 -3
  15. package/template/workflows/person/common/rules/activation-and-memory.md +7 -3
  16. package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md +13 -136
  17. package/template/workflows/specdev/G-grill-with-docs/references/interview-procedure.md +134 -0
  18. package/template/workflows/specdev/I-implement/I-implement.md +15 -189
  19. package/template/workflows/specdev/I-implement/evidence-template.md +12 -0
  20. package/template/workflows/specdev/I-implement/execution-preflight.md +1 -1
  21. package/template/workflows/specdev/I-implement/references/implementation-procedure.md +192 -0
  22. package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +28 -143
  23. package/template/workflows/specdev/P-goal-plan/completion-control.md +1 -1
  24. package/template/workflows/specdev/P-goal-plan/references/goal-lifecycle.md +35 -0
  25. package/template/workflows/specdev/P-goal-plan/references/goal-tickets-map-template.md +15 -0
  26. package/template/workflows/specdev/P-goal-plan/references/map-control.md +28 -0
  27. package/template/workflows/specdev/{O-orchestrate-implementation/O-orchestrate-implementation.md → P-goal-plan/references/multi-change-plan.md} +21 -33
  28. package/template/workflows/specdev/P-goal-plan/references/replan-and-recovery.md +21 -0
  29. package/template/workflows/specdev/P-goal-plan/references/single-change-plan.md +149 -0
  30. package/template/workflows/specdev/R-review-architecture/R-review-architecture.md +48 -53
  31. package/template/workflows/specdev/R-review-architecture/architecture-review-template.md +19 -10
  32. package/template/workflows/specdev/R-review-architecture/proposal-to-ticket.md +3 -1
  33. package/template/workflows/specdev/R-review-architecture/review-rubric.md +52 -0
  34. package/template/workflows/specdev/README.md +36 -216
  35. package/template/workflows/specdev/T-tickets/T-tickets.md +19 -230
  36. package/template/workflows/specdev/T-tickets/references/planning-procedure.md +233 -0
  37. package/template/workflows/specdev/T-tickets/ticket-template.md +16 -0
  38. package/template/workflows/specdev/T-tickets/tickets-map-template.md +14 -0
  39. package/template/workflows/specdev/T-triage/T-triage.md +3 -1
  40. package/template/workflows/specdev/W-wayfinder/W-wayfinder.md +24 -118
  41. package/template/workflows/specdev/W-wayfinder/references/initiative-discovery.md +29 -0
  42. package/template/workflows/specdev/W-wayfinder/references/initiative-template.json +8 -0
  43. package/template/workflows/specdev/W-wayfinder/references/map-traversal.md +120 -0
  44. package/template/workflows/specdev/W-wayfinder/wayfinder-map-template.md +4 -0
  45. package/template/workflows/specdev/common/README.md +1 -1
  46. package/template/workflows/specdev/common/rules/activation-and-memory.md +7 -3
  47. package/template/workflows/specdev/common/rules/artifact-contract.md +10 -2
  48. package/template/workflows/specdev/common/rules/operating-governance.md +38 -0
  49. package/template/workflows/specdev/common/rules/parent-implementation-orchestration.md +6 -2
  50. package/template/workflows/specdev/common/rules/skill-invocation.md +27 -0
  51. package/template/workflows/specdev/common/rules/workflow-routing.md +24 -0
  52. package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md +93 -0
  53. package/template/workflows/specdev/common/schemas/goal-tickets-map.schema.json +33 -0
  54. package/template/workflows/specdev/common/schemas/initiative.schema.json +94 -0
  55. package/template/workflows/specdev/common/schemas/ticket.schema.json +168 -1
  56. package/template/workflows/specdev/common/schemas/tickets-map.schema.json +74 -6
  57. package/template/workflows/specdev/common/skills/code-review/SKILL.md +3 -2
  58. package/template/workflows/specdev/common/skills/code-review/references/risk-review.md +25 -0
  59. package/template/workflows/specdev/common/skills/plan-quality-review/SKILL.md +10 -0
  60. package/template/workflows/specdev/common/skills/plan-quality-review/references/checklist.md +13 -0
  61. package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +5 -83
  62. package/template/workflows/specdev/common/skills/subagent-delivery/references/dispatch-and-accept.md +87 -0
  63. package/template/workflows/specdev/common/tools/README.md +14 -2
  64. package/template/workflows/specdev/common/tools/plan-contract.mjs +256 -0
  65. package/template/workflows/specdev/common/tools/ticket-control.mjs +251 -0
  66. package/template/workflows/specdev/common/tools/validate-specdev.mjs +58 -40
  67. package/template/workflows/specdev/manifest.json +97 -1
  68. package/template/canonical/canonical-specdev-orchestrate-implementation.md +0 -2839
  69. package/template/workflows/specdev/O-orchestrate-implementation/implementation-evidence-template.md +0 -39
  70. package/template/workflows/specdev/O-orchestrate-implementation/implementation-map-template.md +0 -50
  71. package/template/workflows/specdev/O-orchestrate-implementation/implementation-plan-template.md +0 -61
  72. package/template/workflows/specdev/R-review-architecture/architecture-report-contract.md +0 -123
  73. package/template/workflows/specdev/R-review-architecture/architecture-review-report-template.html +0 -106
  74. /package/template/workflows/specdev/{O-orchestrate-implementation/conflict-and-drift.md → P-goal-plan/references/multi-conflict-and-drift.md} +0 -0
  75. /package/template/workflows/specdev/{O-orchestrate-implementation/execution-loop.md → P-goal-plan/references/multi-execution-loop.md} +0 -0
  76. /package/template/workflows/specdev/{O-orchestrate-implementation/input-readiness.md → P-goal-plan/references/multi-input-readiness.md} +0 -0
  77. /package/template/workflows/specdev/{O-orchestrate-implementation/super-dag.md → P-goal-plan/references/multi-super-dag.md} +0 -0
@@ -5,16 +5,20 @@
5
5
  ## Locate before read
6
6
 
7
7
  1. 先解析当前 workflow 的 roots、状态索引和稳定 ID;不存在时静默跳过,不能凭旧路径猜测。
8
- 2. 根据当前请求、Work 分支、关键词、状态和 provenance 定位最小相关 entry
8
+ 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance,先搜索相关索引行或目录项,再定位最小相关 entry;不把索引全文默认装入上下文。
9
9
  3. 只回读命中的 entry 和直接 provenance;需要恢复、冲突裁决、归档、迁移或执行安全证明时,才读取该阶段声明的完整证据集合。
10
10
  4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支,不补造事实。
11
11
 
12
12
  ## Memory writes
13
13
 
14
- 正式知识、永久 context、synthesis 或 archive 写入前,先解析唯一 owner 与 gateway,检查 pending transaction、lock、未完成 promotion 和 recovery evidence。gateway 不明或事务未闭合时,只阻塞记忆写入,继续独立的只读审计、定位和验证。
14
+ 正式知识、永久 context、synthesis 或 archive 写入前,先解析唯一 owner 与 gateway,检查 pending transaction、lock、未完成 promotion 和 recovery evidence。gateway 不明或事务未闭合时,只阻塞记忆写入,继续独立且已授权的审计、定位、验证和其他工作。
15
15
 
16
- 每次写入必须记录 source IDs、证据定位、验证时间或 digest;写入后重新读取索引和目标 entry,确认 owner、locator、内容和状态投影一致。原始证据不可被派生视图覆盖。
16
+ 每次写入必须记录 source IDs、证据定位、验证时间或 digest;写入后定位受影响索引项并重新读取目标 entry,确认 owner、locator、内容和状态投影一致。原始证据不可被派生视图覆盖。
17
17
 
18
18
  ## Read budget
19
19
 
20
20
  当前 Work 的权威状态、schema、Map/Plan、当前输入和直接所有权合同可以完整读取;非当前分支的知识树、历史 change、研究库、项目 Skill 和示例只按索引与关键词读取。执行、冲突、恢复和归档 Work 需要完整证据时,以该 Work 的显式合同为准。
21
+
22
+ ## 事务与归属隔离
23
+
24
+ 启动正式写入前检查原网关未闭合事务与写集。属于本任务的事务按原恢复协议处理;属于其他任务的事务不得接管、解锁、清空或覆盖。只暂停资源重叠的写入与依赖分支,继续独立、已授权工作;事务年龄不构成接管授权。写后按变更 ID 定位受影响的索引项并回读目标原文,不为核验默认整读整库。
@@ -2,149 +2,26 @@
2
2
  id: specdev/grill-with-docs
3
3
  type: workflow-entry
4
4
  workflow: specdev
5
- name: 设计访谈(带文档)
6
- description: 以完整 frontier 逐轮推进设计树,直到每个决策分支都已关闭并获得用户共识,同时持续维护当前 change 的设计树、日志、领域上下文和架构决策。
7
- keywords: [设计访谈, grilling, design-tree, frontier, ADR, LOG, CONTEXT, 决策, 领域建模]
5
+ name: Change 决策访谈
6
+ description: 一个已界定 change 仍有产品、领域或架构决定待确认时进行可恢复访谈;跨 change 边界未清晰时先用 W。
7
+ keywords: [grill, 设计树, 领域, 决策, 共识]
8
8
  ---
9
9
 
10
- # 设计访谈(带文档)
10
+ # Change 决策访谈
11
11
 
12
- > 激活本 Work 后,先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`,再执行本入口。
13
-
14
- 不留情面地访谈用户,直到达成共识。把这件事映射为一棵**设计树(design tree)**:每个决策都会分出挂在它下面的后续决策。
15
-
16
- 按**轮次**推进这棵树。**前沿(frontier)** 是所有前置条件已经确定的决策——那些现在就能问、不必猜测尚未得到答案的问题。每轮询问完整 frontier;用户的答案会重塑设计树并解除下一层问题的阻塞。
17
-
18
- 本 work 只把访谈写成当前 change 的可恢复工件:设计树保存进度,LOG 保存讨论轨迹,CONTEXT 保存本 change 已确认的规范语言,ADR 保存已成为本 change 下游合同的架构决定。这些工件不等于项目永久知识,也不构成实现授权;永久 namespace 对 G 只读,只有 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 能在实现证据、毕业评估和用户确认通过后执行提升。
12
+ > 激活后读取 `<Path>{roots.workflows}/specdev/README.md</Path>`。
19
13
 
20
14
  ## 读取范围
21
15
 
22
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
23
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
24
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
25
-
26
-
27
- ## 输入与产物
28
-
29
- 按存在情况读取:
30
-
31
- - `<Path>{roots.state}/specdev/config.json</Path>`
32
- - `<Path>{roots.state}/specdev/adr/</Path>`(只读永久基线)
33
- - `<Path>{roots.state}/specdev/context/</Path>`(只读永久基线)
34
- - `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
35
- - `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
36
- - `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
37
- - `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
38
- - `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
39
- - `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
40
-
41
- 本 work 拥有:
42
-
43
- - `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
44
- - `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
45
- - `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
46
- - `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
47
- - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`,仅在第三方 stakeholder 持有阻塞答案时延迟创建。
48
-
49
- 不存在的可选输入静默跳过,不把缺失文件伪装成已知事实。
50
-
51
- ## 流程
52
-
53
- ### 1. 启动或恢复 change
54
-
55
- 创建或恢复 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。首次启动时创建 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`,并以 `<Path>{roots.workflows}/specdev/G-grill-with-docs/design-tree-template.json</Path>` 为模板创建 `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`。
56
-
57
- 分别使用:
58
-
59
- - `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
60
- - `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
61
- - `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
62
- - `<Path>{roots.workflows}/specdev/common/schemas/design-tree.schema.json</Path>`
63
-
64
- 恢复时先读取四份工件,按 design tree 的节点状态恢复,避免重复询问已关闭问题。
65
-
66
- **完成标准**:四份工件均可读取;节点依赖无环,所有 LOG 指针存在,当前 frontier 可确定。
67
-
68
- ### 2. 查找事实
69
-
70
- 查找*事实*是 Agent 的工作,永远不是用户的。先探索相关代码、配置、接口、schema、测试、历史 ADR 和相邻实现。
71
-
72
- 当前沿问题需要来自环境的事实时,派遣独立探索去查找。不要阻塞等待:一次进行中的探索是一个未解决的前置条件,所以只有它下游的问题等待结果;现在就继续处理 frontier 的其余部分。不熟悉的外部技术使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
73
-
74
- 将未知项分为:
75
-
76
- - 可发现事实:探索或研究,不询问用户;
77
- - 高影响决策:进入设计树;
78
- - 低影响实现细节:记录为实现者可自行决定,不制造决策节点。
79
-
80
- 阻塞答案既不可发现、当前用户也无法回答、但另一个明确 stakeholder 掌握时,加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`,生成问卷并保存恢复条件;不在本轮继续猜测该分支。
81
-
82
- **完成标准**:每个候选问题已分类;用户只接收无法从环境发现的真实决策。
83
-
84
- ### 3. 建立设计树
85
-
86
- 围绕目标、角色、范围、主要流程、状态与失败、数据与接口、兼容与迁移、安全与隐私、性能与可观测性、验证与验收建立适用节点。
87
-
88
- 每个节点包含稳定 `D-###`、标题、问题、依赖、推荐答案和状态。只有问题本身已经可以精确陈述时才创建节点;依赖尚未确定的节点可以存在,但不进入 frontier。
89
-
90
- **完成标准**:每个高影响已知决策有且只有一个节点;每条依赖指向真实上游节点;没有默默采用的高影响假设。
91
-
92
- ### 4. 逐轮推进完整 frontier
93
-
94
- 加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`。每轮原子增加 `round`,重读设计树并计算完整 frontier。按协议格式给每个问题编号并附推荐答案,然后等待用户回答。
95
-
96
- 用户回答后:
97
-
98
- 1. 为每个回答更新对应节点;
99
- 2. 每个节点各追加一条 LOG,不把多个决定压成一条;
100
- 3. 根据回答增加、删除或重新连接后续节点;
101
- 4. 重新计算 frontier,进入下一轮。
102
-
103
- 一个答案依赖本轮仍开放问题的提问属于后续轮次。用户延后且该决定会影响外部行为、公共接口、数据、安全、兼容、迁移或验收时,保持 blocked,不把它伪装成共识。
104
-
105
- **完成标准**:本轮开始时的完整 frontier 每个节点都有回答、明确延后或阻塞记录;所有状态已原子写入并重读。
106
-
107
- ### 5. 同步 change-local 领域模型
108
-
109
- 加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。每轮先写 LOG,再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT,最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
110
-
111
- 历史轨迹只留在 LOG;未确认选项不写成已接受 ADR;已有 change ADR 被替代时建立 supersedes 链。同步只更新本 change 工件,不创建、合并或改写永久 `context/`、`adr/`;它记录共识生长过程,不授权产品实现。
112
-
113
- **完成标准**:LOG、CONTEXT、ADR 和 design tree 无冲突;每个同步结论都有用户回答或事实来源;永久 namespace 未被修改。
114
-
115
- ### 6. 共识确认与路由
116
-
117
- frontier 为空时,向用户确认设计树的每个分支均已走过且已经达成共识。用户指出遗漏时新增节点并继续;只有明确确认后把 design tree 标为 `consensus`。
118
-
119
- 路由前使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage grill` 校验当前 change;失败时保持本 Work 可恢复状态,不发布共识。
120
-
121
- 随后按成熟度路由:
122
-
123
- - 通常进入 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`;
124
- - 外部行为已经完全明确时进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`;
125
- - 获批的极小局部工作可进入 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`;
126
- - 路径或关键事实仍未知时进入 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`。
127
-
128
- 同步 workflow/change 状态,返回四份权威工件和下一 work 的完整路径。不自动执行下一 work。
16
+ 读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;定位当前 change `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`、`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 和相关 initiative 决策。先找到相关条目再回读必要原文,不默认整读永久 ADR 或索引。
129
17
 
130
- ## 完成标准
18
+ ## 过程与边界
131
19
 
132
- - 设计树的每个适用分支都已走过,没有高影响事项被默默假定;
133
- - 每轮询问的是完整 frontier,依赖未关闭的问题没有提前出现;
134
- - 可发现事实由 Agent 查找,没有转交用户;
135
- - design tree 通过 schema,LOG 指针完整;
136
- - CONTEXT 只包含当前 change 已确认的规范语言,ADR 只包含满足条件且已成为本 change 合同的架构决定;
137
- - 永久 `context/`、`adr/` 保持只读,未在 G 中执行知识提升;
138
- - frontier 为空且用户明确确认共识;
139
- - 状态、权威工件和下一 work 路径已返回;
140
- - 未执行产品实现。
20
+ 进入访谈必须读取 `<Path>{roots.workflows}/specdev/G-grill-with-docs/references/interview-procedure.md</Path>`,再按触发分支读取 grilling、领域建模、日志格式或 stakeholder questionnaire。保留完整 frontier、推荐答案和逐轮共识检查,但不替用户回答高影响取舍。
141
21
 
142
- ## 子文件引用
22
+ - 先查仓库可发现事实,只询问会改变行为、架构、风险、范围、迁移或验收的决定。
23
+ - W 的每个 materialized change 在自己的目录拥有设计树和文档;共享答案以来源指针引用,不能共用一棵可写设计树。
24
+ - 当前 change 的 LOG/CONTEXT/ADR 可按 Work 授权写入;永久 namespace 对 G 只读,正式知识只能经 A 的原有写入网关提升。
25
+ - 没有未决的高影响决定且证据可定位才标记共识;无法回答时只暂停相关分支,返回明确问题和恢复入口。
143
26
 
144
- - 质询协议:`<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`
145
- - 设计树模板:`<Path>{roots.workflows}/specdev/G-grill-with-docs/design-tree-template.json</Path>`
146
- - 领域建模:`<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`
147
- - ADR 格式:`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
148
- - CONTEXT 格式:`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
149
- - LOG 格式:`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
150
- - Stakeholder 问卷:`<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`
27
+ 完成后使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage grill`,回读四个真实源工件,再交给 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`;若属于 W 调查票,只关闭本票并返回探索地图。
@@ -0,0 +1,134 @@
1
+ # 设计访谈(带文档)
2
+
3
+
4
+ 不留情面地访谈用户,直到达成共识。把这件事映射为一棵**设计树(design tree)**:每个决策都会分出挂在它下面的后续决策。
5
+
6
+ 按**轮次**推进这棵树。**前沿(frontier)** 是所有前置条件已经确定的决策——那些现在就能问、不必猜测尚未得到答案的问题。每轮询问完整 frontier;用户的答案会重塑设计树并解除下一层问题的阻塞。
7
+
8
+ 本 work 只把访谈写成当前 change 的可恢复工件:设计树保存进度,LOG 保存讨论轨迹,CONTEXT 保存本 change 已确认的规范语言,ADR 保存已成为本 change 下游合同的架构决定。这些工件不等于项目永久知识,也不构成实现授权;永久 namespace 对 G 只读,只有 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>` 能在实现证据、毕业评估和用户确认通过后执行提升。
9
+
10
+
11
+ ## 输入与产物
12
+
13
+ 按存在情况读取:
14
+
15
+ - `<Path>{roots.state}/specdev/config.json</Path>`
16
+ - `<Path>{roots.state}/specdev/adr/</Path>`(只读永久基线)
17
+ - `<Path>{roots.state}/specdev/context/</Path>`(只读永久基线)
18
+ - `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
19
+ - `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
20
+ - `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
21
+ - `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
22
+ - `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`
23
+ - `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>`
24
+
25
+ 本 work 拥有:
26
+
27
+ - `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`
28
+ - `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
29
+ - `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
30
+ - `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
31
+ - `<Path>{roots.state}/specdev/changes/{change}/questionnaires/</Path>`,仅在第三方 stakeholder 持有阻塞答案时延迟创建。
32
+
33
+ 不存在的可选输入静默跳过,不把缺失文件伪装成已知事实。
34
+
35
+ ## 流程
36
+
37
+ ### 1. 启动或恢复 change
38
+
39
+ 创建或恢复 `<Path>{roots.state}/specdev/changes/{change}/</Path>`。首次启动时创建 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`,并以 `<Path>{roots.workflows}/specdev/G-grill-with-docs/design-tree-template.json</Path>` 为模板创建 `<Path>{roots.state}/specdev/changes/{change}/design-tree.json</Path>`。
40
+
41
+ 分别使用:
42
+
43
+ - `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
44
+ - `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
45
+ - `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
46
+ - `<Path>{roots.workflows}/specdev/common/schemas/design-tree.schema.json</Path>`
47
+
48
+ 恢复时先读取四份工件,按 design tree 的节点状态恢复,避免重复询问已关闭问题。
49
+
50
+ **完成标准**:四份工件均可读取;节点依赖无环,所有 LOG 指针存在,当前 frontier 可确定。
51
+
52
+ ### 2. 查找事实
53
+
54
+ 查找*事实*是 Agent 的工作,永远不是用户的。先探索相关代码、配置、接口、schema、测试、历史 ADR 和相邻实现。
55
+
56
+ 当前沿问题需要来自环境的事实时,派遣独立探索去查找。不要阻塞等待:一次进行中的探索是一个未解决的前置条件,所以只有它下游的问题等待结果;现在就继续处理 frontier 的其余部分。不熟悉的外部技术使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
57
+
58
+ 将未知项分为:
59
+
60
+ - 可发现事实:探索或研究,不询问用户;
61
+ - 高影响决策:进入设计树;
62
+ - 低影响实现细节:记录为实现者可自行决定,不制造决策节点。
63
+
64
+ 阻塞答案既不可发现、当前用户也无法回答、但另一个明确 stakeholder 掌握时,加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`,生成问卷并保存恢复条件;不在本轮继续猜测该分支。
65
+
66
+ **完成标准**:每个候选问题已分类;用户只接收无法从环境发现的真实决策。
67
+
68
+ ### 3. 建立设计树
69
+
70
+ 围绕目标、角色、范围、主要流程、状态与失败、数据与接口、兼容与迁移、安全与隐私、性能与可观测性、验证与验收建立适用节点。
71
+
72
+ 每个节点包含稳定 `D-###`、标题、问题、依赖、推荐答案和状态。只有问题本身已经可以精确陈述时才创建节点;依赖尚未确定的节点可以存在,但不进入 frontier。
73
+
74
+ **完成标准**:每个高影响已知决策有且只有一个节点;每条依赖指向真实上游节点;没有默默采用的高影响假设。
75
+
76
+ ### 4. 逐轮推进完整 frontier
77
+
78
+ 加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`。每轮原子增加 `round`,重读设计树并计算完整 frontier。按协议格式给每个问题编号并附推荐答案,然后等待用户回答。
79
+
80
+ 用户回答后:
81
+
82
+ 1. 为每个回答更新对应节点;
83
+ 2. 每个节点各追加一条 LOG,不把多个决定压成一条;
84
+ 3. 根据回答增加、删除或重新连接后续节点;
85
+ 4. 重新计算 frontier,进入下一轮。
86
+
87
+ 一个答案依赖本轮仍开放问题的提问属于后续轮次。用户延后且该决定会影响外部行为、公共接口、数据、安全、兼容、迁移或验收时,保持 blocked,不把它伪装成共识。
88
+
89
+ **完成标准**:本轮开始时的完整 frontier 每个节点都有回答、明确延后或阻塞记录;所有状态已原子写入并重读。
90
+
91
+ ### 5. 同步 change-local 领域模型
92
+
93
+ 加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。每轮先写 LOG,再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT,最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
94
+
95
+ 历史轨迹只留在 LOG;未确认选项不写成已接受 ADR;已有 change ADR 被替代时建立 supersedes 链。同步只更新本 change 工件,不创建、合并或改写永久 `context/`、`adr/`;它记录共识生长过程,不授权产品实现。
96
+
97
+ **完成标准**:LOG、CONTEXT、ADR 和 design tree 无冲突;每个同步结论都有用户回答或事实来源;永久 namespace 未被修改。
98
+
99
+ ### 6. 共识确认与路由
100
+
101
+ frontier 为空时,向用户确认设计树的每个分支均已走过且已经达成共识。用户指出遗漏时新增节点并继续;只有明确确认后把 design tree 标为 `consensus`。
102
+
103
+ 路由前使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage grill` 校验当前 change;失败时保持本 Work 可恢复状态,不发布共识。
104
+
105
+ 随后按成熟度路由:
106
+
107
+ - 通常进入 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`;
108
+ - 外部行为已经完全明确时进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`;
109
+ - 获批的极小局部工作可进入 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`;
110
+ - 路径或关键事实仍未知时进入 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`。
111
+
112
+ 同步 workflow/change 状态,返回四份权威工件和下一 work 的完整路径。不自动执行下一 work。
113
+
114
+ ## 完成标准
115
+
116
+ - 设计树的每个适用分支都已走过,没有高影响事项被默默假定;
117
+ - 每轮询问的是完整 frontier,依赖未关闭的问题没有提前出现;
118
+ - 可发现事实由 Agent 查找,没有转交用户;
119
+ - design tree 通过 schema,LOG 指针完整;
120
+ - CONTEXT 只包含当前 change 已确认的规范语言,ADR 只包含满足条件且已成为本 change 合同的架构决定;
121
+ - 永久 `context/`、`adr/` 保持只读,未在 G 中执行知识提升;
122
+ - frontier 为空且用户明确确认共识;
123
+ - 状态、权威工件和下一 work 路径已返回;
124
+ - 未执行产品实现。
125
+
126
+ ## 子文件引用
127
+
128
+ - 质询协议:`<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`
129
+ - 设计树模板:`<Path>{roots.workflows}/specdev/G-grill-with-docs/design-tree-template.json</Path>`
130
+ - 领域建模:`<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`
131
+ - ADR 格式:`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
132
+ - CONTEXT 格式:`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`
133
+ - LOG 格式:`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
134
+ - Stakeholder 问卷:`<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`
@@ -2,203 +2,29 @@
2
2
  id: specdev/implement
3
3
  type: workflow-entry
4
4
  workflow: specdev
5
- name: 实现
6
- description: 基于 Ready Ticket 或获批小型 Spec 执行设计检查、TDD、动态派单、双轴审查、按 Goal Plan 选择的 current workspace 或 Ticket worktree 提交、直接父分支或候选合并验证和 Lead Evidence 回写。
7
- keywords: [实现, TDD, Lead, subagent, worktree, current workspace, direct-parent, candidate-merge, 代码审查, 证据]
5
+ name: 实现与验收
6
+ description: 执行已授权的 Ready Ticket 或获批 Direct Spec,产生可回读实现和验收证据;不从模糊需求直接写代码。
7
+ keywords: [implement, Ticket, TDD, Evidence, integration]
8
8
  ---
9
9
 
10
- # 实现
10
+ # 实现与验收
11
11
 
12
- > 激活本 Work 后,先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`,再执行本入口。
13
-
14
- 本 work 保留模块设计检查、design-it-twice、TDD 红绿循环、双轴审查和证据治理。Ticket 模式按子 Goal Plan 或父 Implementation Plan 的 `ticket_workspace_policy` 选择 current workspace 串行直接父分支或独立 worktree candidate-merge;Lead 根据实际情况自行实现或动态派单。
15
-
16
- 若当前 change 是未完成父 Implementation Map 的成员,必须读取 `<Path>{roots.workflows}/specdev/common/rules/parent-implementation-orchestration.md</Path>`、父 Map 与父 Plan。父 Plan 提供跨 change dependency/serialization、全局 workspace 策略、组合派单标识、implementation agent cap 和 integration queue;子 Goal Plan 只能增加子内 Gate,不能放宽或冲突。
12
+ > 激活后读取 `<Path>{roots.workflows}/specdev/README.md</Path>`。
17
13
 
18
14
  ## 读取范围
19
15
 
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
- ### Ticket 模式(默认)
28
-
29
- 先读取 Tickets Map 的总体实施背景与项目 Skill 读取矩阵,再读取适用于 `ALL` 或当前 Ticket 的项目 Skill,随后读取 Ready Ticket、可选子 Goal Plan 和可选父 Implementation Plan。存在父 Plan 时使用其 Lead、workspace/integration 策略和全局门,即使子 Goal Plan 不存在也可以执行;两者都存在时必须策略一致。没有父 Plan 时沿用子 Goal Plan;两者都不存在时,当前主会话作为该 Ticket 的 Lead,并按 Direct Spec 规则执行,不推断 worktree 策略。`required` 模式每个 Ticket 建立独立 worktree;`current` 模式所有受同一计划约束的 Ticket 严格串行,使用当前分支和当前 workspace。
30
-
31
- ### Direct Spec 模式
32
-
33
- 只有极小、局部、单一行为、低风险、可逆且无需 Ticket DAG 的工作,才可在用户批准后直接基于 Spec/ADR/CONTEXT 在 current workspace 执行。先确认目标、IN/OUT、唯一写入 owner、可写范围、关键不变量、验证和验收。出现公共 API/schema、迁移、安全、高风险、多个行为或并行需求时返回 T-tickets。
34
-
35
- ## 输入
36
-
37
- 两种模式都必须读取:
38
-
39
- - 当前 Spec:`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
40
- - 项目配置:`<Path>{roots.state}/specdev/config.json</Path>`
41
-
42
- Ticket 模式必须按以下顺序读取:
43
-
44
- 1. `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 的总体实施背景和完整项目 Skill 读取矩阵;
45
- 2. 矩阵中适用于 `ALL` 或当前 Ticket ID 的全部项目 Skill;
46
- 3. 当前 Ticket `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`;
47
- 4. 存在的 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`,以及父 Implementation Map 声明当前 change 时的父 Map/Plan。
48
-
49
- 矩阵是发布时确认的最低必读集合,不是 allowlist。项目 Agent 指令或实际实现范围触发新的项目 Skill 时,先读取该 Skill、停止项目写入,由 Lead 更新 Tickets Map 并重新运行 tickets 校验后恢复。Direct Spec 模式必须读取用户对轻量执行合同和直接实现的明确批准。
50
-
51
- 按存在情况读取:
52
-
53
- - 当前 change 架构决策:`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
54
- - 当前 change 领域上下文:`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
55
- - 当前 change 设计日志:`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
56
- - 当前 change 诊断:`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
57
- - 永久架构决策:`<Path>{roots.state}/specdev/adr/</Path>`
58
- - 永久领域上下文:`<Path>{roots.state}/specdev/context/</Path>`
59
-
60
- 永久目录可以为空,静默继续。当前 ADR/CONTEXT 缺失且实施需要对应决定时,返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`;Spec、Ticket 或 Goal Plan 与代码事实冲突时按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 返回真正 owner,不在实现中覆盖。
61
-
62
- Git 已处于 merge/rebase 冲突时,先加载 `<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`;不把冲突伪装成普通 TDD。
63
-
64
- ## 流程
65
-
66
- ### 1. 执行前预检与 workspace
67
-
68
- 加载 `<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`。
69
-
70
- Ticket 模式:
71
-
72
- 1. 验证 Ready、依赖 Evidence、Spec/ADR/Goal Plan、一致性、路径 owner 和验证接缝;确认 Tickets Map 的总体实施背景、项目 Skill 矩阵、当前 Ticket 覆盖与实际文件均有效,并完成规定读取顺序;
73
- 2. 确认子 Goal Plan schema v6(若存在)与父 Implementation Plan schema v1(若存在)、唯一 Lead、workspace 策略、动态 implementation/integration 上限与授权;
74
- 3. `required` 模式以 `purpose=ticket, operation=create|restore` 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`;`current` 模式读取当前 branch、HEAD、dirty 状态并确认没有其他 Ticket implementation writer;
75
- 4. Lead 把 Ticket 设为 `in_progress`;`required` 模式将 change worktree 记录设为 `active`,`current` 模式建立 current workspace 执行记录;
76
- 5. 当前代码使合同失效时停止并返回对应上游 owner。
77
-
78
- Direct Spec 模式验证用户批准、轻量合同和 current workspace 唯一写入 owner;不创建虚假 Ticket/worktree 状态。
79
-
80
- **完成标准**:按策略完成 workspace、基线、owners、权限与实际 Git 一致;current 模式只有一个 implementation writer 且 Ticket 串行可恢复。
81
-
82
- ### 2. Lead 决定自行实现或动态派单
83
-
84
- Ticket 模式下,Lead 根据 Ticket 独立性、路径冲突、上下文、风险和平台能力决定。派单时以 `operation=dispatch` 调用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`。`current` 模式仍可派遣一个 implementation subagent 写当前 workspace,但必须等待其返回、Lead 验收并形成 commit 后才进入下一个 Ticket;`required` 模式 implementation subagent 绑定独立 Ticket worktree。Direct Spec 模式由 Lead 作为 current workspace 唯一写入 owner,不派遣 implementation subagent 写入。
85
-
86
- - implementation subagent 同时取适用子 Goal Plan、父 Implementation Plan、config 和平台能力的共同上限;current 模式保持单 writer 串行安全不变量;Lead 不计入;
87
- - 父实现编排存在时,派单与返回都使用 `<member-change>::<ticket-id>`,并占用父 Plan 的 task/serialization/integration slot;
88
- - review/research/test-observation agent 不设置 SpecDev 数字上限,但保持只读;
89
- - implementation Packet 按策略绑定唯一 Ticket workspace 或 current workspace、checkpoint、Tickets Map、当前 Ticket 的项目 Skill 最低必读集合、路径、非 E2E 检查与 commit 返回;
90
- - subagent 不写 SpecDev 工件、Evidence、父分支或 E2E 结果;
91
- - Lead 自行实现时仍遵循相同 worktree、commit 与返回事实合同。
92
-
93
- **完成标准**:current 模式只有一个 implementation owner 写当前 workspace;required 模式只有一个 owner 写当前 Ticket worktree;Direct Spec 只有 Lead 写 current workspace;所有 SpecDev 写入仍由 Lead 拥有。
94
-
95
- ### 3. 设计检查
96
-
97
- 加载 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`,检查模块、接口、类型、不变量、顺序/错误/性能语义、接缝、适配器、依赖分类、测试观察点和既有公共合同。
98
-
99
- 存在多个不改变上层契约的局部设计时,可运行 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。超出 Ticket 或改变产品/公共合同/数据/兼容/安全时,返回架构审查、Grill、Spec 或 Ticket owner。陌生外部依赖使用 research Skill。
100
-
101
- **完成标准**:局部设计与上层契约一致,稳定接缝和依赖策略明确。
102
-
103
- ### 4. TDD 红→绿垂直循环
104
-
105
- 加载 `<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`。对每个验收行为或关键风险:
106
-
107
- 1. 选择公共接口或稳定接缝;
108
- 2. 编写因目标行为缺失而失败的测试/验证并确认失败原因;
109
- 3. 只写足以通过当前测试的实现;
110
- 4. 运行定向非 E2E 验证;
111
- 5. 保存 red/green 事实并进入下一条窄切片。
112
-
113
- 不得删除测试、放宽断言、吞错、永久跳过或只验证 Mock 调用次数来制造绿色。
114
-
115
- 新增或修改代码注释时,先判断信息能否由命名、类型或结构表达,并同步维护受行为变化影响的既有注释。
116
-
117
- ### 5. 实现检查、commit 与 Lead 接收
118
-
119
- Ticket 模式的 implementation owner 按 Goal Plan 策略在当前 workspace 或来源 worktree:
120
-
121
- - 运行 Ticket 要求的单元、组件、静态、类型、lint/build 等非 E2E 检查;
122
- - 审计 writable/shared/read-only 路径和新/既有/环境失败;
123
- - 在已授权时创建引用 Ticket ID 的实现 commit;current 模式 commit 直接落在父分支,required 模式落在 Ticket branch;
124
- - 返回 commit、dirty 状态、实际路径、命令/结果、未运行项和恢复条件。
125
-
126
- Ticket 模式中,Lead 以 `operation=accept` 调用 subagent-delivery,重读 Git 状态、branch tip、commit、diff 和命令事实。无改动时将 Ticket 改为 `cancelled` 并记录原因;不得 empty commit 或 Evidence-only Done。required 模式来源 worktree 不运行 E2E;current 模式适用 E2E 留给 Lead 的 direct-parent 验证。
127
-
128
- Direct Spec 模式由 Lead 在 current workspace 运行轻量合同要求的定向非 E2E 检查,审计获批可写范围,并在获得 implementation commit 授权后创建引用 change 的非空 commit;无需改动时记录事实并取消直接实现,不创建 empty commit。记录实施前基线、最终 checkpoint、dirty 状态、实际路径、命令结果、未运行项和恢复条件。
129
-
130
- **完成标准**:required 模式 Ticket worktree clean 且 `source_checkpoint` 精确等于 branch tip;current 模式 workspace clean 且 Ticket `result_sha` 精确等于父分支上的 implementation commit;或 Direct Spec 的 current workspace checkpoint、路径和轻量合同一致。
131
-
132
- ### 6. 双轴审查
133
-
134
- 调用 `<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`。required Ticket 以 `base_sha` 与 `source_checkpoint` 为固定点;current Ticket 以 Ticket 实施前基线与 implementation commit 为固定点;Direct Spec 以实施前基线与 current workspace 最终 checkpoint 为固定点:
135
-
136
- - 标准轴:正确性、模块设计、错误、安全、性能、并发、资源、测试与可维护性;
137
- - 规范轴:Spec/Ticket IN/OUT、实现合同、路径所有权、验证矩阵与 Goal Gate。
138
-
139
- 标准轴同时复核 `<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`:公共 API 契约完整,内部注释只保留非显然的 Why、Invariant 和 Risk,且相关注释与当前行为一致。
140
-
141
- 两个轴隔离并按标准轴、规范轴顺序返回 Lead。局部 finding 在当前模式的实现 workspace 修正、创建新 checkpoint 并重跑;改变上层契约则登记 deviation。Ticket 进入 `review` 或 Direct Spec 进入最终验证前,两轴必须通过。
142
-
143
- ### 7. 最终集成与适用 E2E
144
-
145
- `required` Ticket 模式中,Lead 以 `purpose=ticket, operation=finalize` 调用 dev-worktree:
146
-
147
- 1. 在最新父分支的 Lead-owned candidate checkout 组合 source commit;
148
- 2. 运行受影响集成/回归、项目父状态检查和 Ticket 标记 required 的 E2E;
149
- 3. candidate 失败时父分支不动,Ticket 回 `in_progress`/`blocked`;
150
- 4. 父 HEAD 漂移时废弃本轮 candidate,基于最新父分支重建并重跑;
151
- 5. 全部通过后父分支 fast-forward 到 candidate/result SHA;
152
- 6. 重读父 HEAD/tree 和 ancestor 关系后,才允许 Ticket Done。
153
-
154
- E2E 是否需要由 Ticket/Goal Plan 的实际跨边界风险决定,不限于 UI;不适用必须记录原因。
155
-
156
- `current` Ticket 模式跳过 source worktree、candidate merge 和 candidate checkout。Lead 在当前 workspace 运行 Ticket 要求的适用集成/回归与 E2E,记录运行环境、命令、退出码和摘要;E2E 不得派给其他 agent。失败时不声明完成,保留 Ticket commit、父 HEAD 和恢复条件。全部通过后重读父 HEAD/tree 并记录 `result_sha`。Direct Spec 模式同样跳过 source worktree、candidate merge 和父分支推进。
157
-
158
- 无论失败发生在 implementation、review、direct-parent 还是 parent-candidate,同一 Ticket 反复返回相同 blocker、下一轮没有产生新证据,或 integration attempts 达到有效 Plan 上限时,都停止自动退回原 implementation owner。Lead 保留当前 workspace/worktree、implementation/source commit、旧 candidate 和失败命令,在 Ticket Evidence 记录失败历史,并将 Ticket/worktree 标为 `blocked`。当前 change 属于父实现时返回父 O Lead;否则返回 Goal Plan Lead,或无 Goal Plan 时的当前 I Lead。Lead 按 lead-orchestration 完成最小复盘并形成有实质变化的新 Dispatch Packet 后,才可重置 attempts 和重新派发;契约已失效则返回真正 owner。
159
-
160
- ### 8. Evidence、状态与完成
161
-
162
- Lead 使用 `<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>` 写入 Ticket Evidence;Direct Spec 按该模板的 Direct Spec 适配说明写 `<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`。Ticket Evidence 按策略记录 implementation/source、适用 candidate/result SHA、派单/返回、两层验证、双轴审查、E2E disposition、路径审计、失败历史与适用 Lead 复盘、偏差和残余风险;Direct Spec Evidence 使用实施前基线与 current workspace 最终 checkpoint,不伪造 Ticket/worktree/candidate 字段。
163
-
164
- Ticket 正常状态:`ready → in_progress → review → done`。`required` 的 `done` 要求 change worktree 已完成集成(`integrated` 或 `removed`)、父 HEAD=result SHA 且包含 source commit;`current` 的 `done` 要求 current workspace clean、direct-parent 验证通过且父 HEAD=result SHA。阻塞使用 `blocked`,契约偏差使用 `deviated`,无需改动使用 `cancelled`。Direct Spec 由当前 I-implement owner 按 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>` 关闭 change。
165
-
166
- 按存在和当前模式同步 Ticket、Tickets Map、Goal Plan、`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 和全局状态;Direct Spec 不创建缺失的 Ticket/Map/Goal Plan。最后一个计划内 Ticket 完成后,Goal Plan 的 Lead 按 change completion 关闭;无 Goal Plan 的当前 I owner 承担同一门禁。需要远程 reconcile 时返回 T-triage,否则进入 Archive。
167
-
168
- 当前 change 属于未完成父实现 change 时,单个组合 Ticket 完成、阻塞或触发 Lead 复盘,且子状态与 Evidence 已写入后,必须自动返回 `<Path>{roots.workflows}/specdev/O-orchestrate-implementation/O-orchestrate-implementation.md</Path>`,由父 Lead 重读全部成员并决定重新派发、返回上游或继续下一 frontier;不得要求用户逐个重新激活,不得直接归档子 change,也不得从本 Work 实现另一个成员。
169
-
170
- 运行:
171
-
172
- ```bash
173
- node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
174
- --stage implement \
175
- --repo <project-root> \
176
- <Path>{roots.state}/specdev/changes/{change}</Path>
177
- ```
178
-
179
- ### 9. 返回
16
+ 先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;从当前 tickets-map 或父 map 定位本票、上游约束、项目 Skill 与执行策略。仅展开当前 Ticket 的正文、直接依赖、适用 Skill 和必要恢复证据,不整读知识库。
180
17
 
181
- Ticket 模式返回 Ticket/change 状态、Evidence 完整路径、workspace locator、implementation/source、适用 candidate/result SHA、父分支、E2E disposition、适用 Lead 复盘决定、未验证项和下一路由。Direct Spec 返回 change 状态、`<Path>{roots.state}/specdev/changes/{change}/evidence/direct-spec.md</Path>`、current workspace、实施前/最终 checkpoint、适用 E2E 和下一路由。push、PR、remote merge、deploy、migration、生产动作及来源 branch/worktree cleanup 只在独立授权时执行。
18
+ ## 执行入口
182
19
 
183
- ## 完成标准
20
+ 执行必须读取 `<Path>{roots.workflows}/specdev/I-implement/references/implementation-procedure.md</Path>` 和 `<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`;这两份合同持有原有 Direct Spec/Ticket、TDD、双轴审查、Git、workspace 与 Evidence 全流程,不得跳过。
184
21
 
185
- - Ticket 模式按策略完成 current workspace/direct-parent 或 worktree/implementation commit/candidate gate;Direct Spec 的轻量合同、current workspace checkpoint、双轴审查和最终验证完整;
186
- - current Ticket 的适用 E2E Lead 在 current workspace 运行;required Ticket 的适用 E2E 由 Lead 在 parent-candidate 运行;Direct Spec 适用 E2E 由 Lead current workspace 运行;
187
- - Lead 独立核对并写全部 SpecDev 工件;
188
- - Lead 与任何 implementation subagent 都已先读 Tickets Map、再读当前 Ticket 适用的项目 Skill;实现中发现的新匹配 Skill 已同步回 Map 并通过校验;
189
- - 重复失败或 integration attempt 上限只触发 Lead 复盘;没有 Evidence 中的原因、改变和 owner 决定,不得重置 attempts 或重复派发;
190
- - current Ticket 父分支只推进到通过的 direct-parent 验证 commit;required Ticket 父分支只推进到通过的 candidate;两者 Ticket Done 都必须与实际 Git 一致;Direct Spec 的完成状态与 current workspace 最终 checkpoint 一致;
191
- - 实际路径、验证、偏差和状态可由 Evidence 恢复;
192
- - validator 无 error。
22
+ 1. 核验 Ready、授权、owner、真实源与 map 基线;新增计划型票按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 实际调用绑定能力并记录证据。旧票缺调用契约时先由 Lead 补齐,不猜测。
23
+ 2. 保持 codebase-design、design-it-twice TDD 的适用门禁;进入对应实现步骤再读其 reference。派单时调用 subagent-delivery;Lead 是唯一 SpecDev 状态写入者。
24
+ 3. current 模式串行使用当前 workspace;required 模式使用独立 worktree,E2E 由 Lead parent-candidate 完成。实现 commit、父分支推进和集成均需真实授权。
25
+ 4. 安全、并发、公共接口、数据迁移或用户要求全面审查时展开 `<Path>{roots.workflows}/specdev/common/skills/code-review/references/risk-review.md</Path>`;不为省上下文删减必要检查或限制发现数量。
26
+ 5. Evidence、运行适用校验并回读后才推进状态;必需 Skill 失败、验收失败、越界或归属冲突暂停本票及依赖它的分支。无关工作仍由总控继续,不接管他人事务。
193
27
 
194
- ## 子文件引用
28
+ ## 返回总控
195
29
 
196
- - 执行前预检:`<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`
197
- - 代码库设计:`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
198
- - Design It Twice:`<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`
199
- - TDD:`<Path>{roots.workflows}/specdev/I-implement/tdd-rules.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-test-design.md</Path>`、`<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`
200
- - 代码注释:`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
201
- - Evidence:`<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>`
202
- - Agent 交付:`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
203
- - Worktree:`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`
204
- - 冲突处理:`<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`
30
+ 完成、暂停或重规划后返回 `<Path>{roots.workflows}/specdev/P-goal-plan/P-goal-plan.md</Path>` 的当前 Goal;旧父 O 恢复键继续有效。恢复先核对 HEAD、Ticket/Skill 摘要、证据和未闭合动作,避免重复提交、迁移、发布或正式记忆写入。没有不可变实现证据时不得宣称完成。
@@ -119,3 +119,15 @@ subagent 不写本 Evidence;以上内容由 Lead 从实际 workspace、Git 和
119
119
  - **Parent result:** `<sha>`
120
120
  - **Source workspace:** `<workspace_ref>`
121
121
  - **Evidence:** `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`
122
+
123
+ ## Skill Execution Records
124
+
125
+ 按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 从真实执行轨迹填写以下 JSON 数组;每个 required 调用必须唯一匹配 Ticket 的 id、phase、operation 和 sha256,并有 passed 状态及可回读证据。没有绑定时保留空数组。仅阅读入口不能写 passed;失败/未执行保持 blocker,不伪造工具结果。
126
+
127
+ ```json
128
+ []
129
+ ```
130
+
131
+ ## 用户交付与源回读
132
+
133
+ 记录用户要求的实际数量、交付位置、源/链接/必要元数据回读、行为差异、备份和未完成项。Goal 有显式数量时在 `<Path>{roots.state}/specdev/changes/{change}/evidence/goal-delivery.md</Path>` 写 Delivery Records,与 map 合同逐项核对。字符统计包含移动后的参考文件,不等同于 Token 或套餐用量。
@@ -41,4 +41,4 @@
41
41
  - **delivery-unverified**:候选、provider 声明或附件不能独立核对;保持 unverified。
42
42
  - **e2e-owner-invalid**:required 模式 E2E 被安排在 source worktree,或任一模式不是 Lead owner;停止并修 Ticket/Goal Plan。
43
43
  - **direct-parent-invalid**:current 模式的 Ticket commit、父 HEAD、验证或 Evidence 不一致;保留最后可信 commit 并阻塞当前 Ticket。
44
- - **parent-plan-stale**:父 Implementation Map revision、成员 Ticket、serialization、workspace 策略、全局实现配额或 repository/ref 已变化;停止当前派单并返回 O-orchestrate-implementation 重算。
44
+ - **parent-plan-stale**:父 Implementation Map revision、成员 Ticket、serialization、workspace 策略、全局实现配额或 repository/ref 已变化;停止当前派单并返回 P-goal-plan 重算。