@namewta/speculo 0.3.4 → 0.5.0

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 (125) hide show
  1. package/README.md +4 -5
  2. package/package.json +1 -1
  3. package/template/canonical/canonical-specdev-engineering-cognitive-mentor.md +5 -0
  4. package/template/canonical/canonical-specdev-goal-plan.md +366 -59
  5. package/template/canonical/canonical-specdev-grill-with-docs.md +153 -104
  6. package/template/canonical/canonical-specdev-spec.md +5 -0
  7. package/template/canonical/canonical-specdev-tickets.md +5 -0
  8. package/template/canonical/canonical-specdev-wayfinder.md +171 -249
  9. package/template/commands/docs-sync.md +3 -3
  10. package/template/skills/docs-sync/SKILL.md +4 -3
  11. package/template/skills/docs-sync/assets/report-template.md +1 -0
  12. package/template/skills/docs-sync/references/agents/agent-writing.md +75 -0
  13. package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/claude-redirect.md +1 -1
  14. package/template/skills/docs-sync/references/agents-contract.md +23 -1
  15. package/template/skills/typescript-standards-builder/README.md +53 -0
  16. package/template/skills/typescript-standards-builder/SKILL.md +245 -0
  17. package/template/skills/typescript-standards-builder/examples/sample-generated-tree.md +30 -0
  18. package/template/skills/typescript-standards-builder/examples/sample-interview-decisions.md +26 -0
  19. package/template/skills/typescript-standards-builder/manifest.txt +29 -0
  20. package/template/skills/typescript-standards-builder/references/00-governance-and-fixed-defaults.md +77 -0
  21. package/template/skills/typescript-standards-builder/references/01-project-discovery.md +100 -0
  22. package/template/skills/typescript-standards-builder/references/02-interview-workflow.md +129 -0
  23. package/template/skills/typescript-standards-builder/references/03-project-architecture-and-directory-layout.md +84 -0
  24. package/template/skills/typescript-standards-builder/references/04-file-directory-and-symbol-naming.md +92 -0
  25. package/template/skills/typescript-standards-builder/references/05-modules-imports-exports-and-dependencies.md +63 -0
  26. package/template/skills/typescript-standards-builder/references/06-typescript-type-system.md +64 -0
  27. package/template/skills/typescript-standards-builder/references/07-functions-async-errors-and-resources.md +42 -0
  28. package/template/skills/typescript-standards-builder/references/08-comments-jsdoc-and-documentation.md +51 -0
  29. package/template/skills/typescript-standards-builder/references/09-testing-strategy.md +58 -0
  30. package/template/skills/typescript-standards-builder/references/10-react-and-frontend.md +39 -0
  31. package/template/skills/typescript-standards-builder/references/11-node-cli-and-cross-platform.md +31 -0
  32. package/template/skills/typescript-standards-builder/references/12-formatting-lint-and-complexity.md +58 -0
  33. package/template/skills/typescript-standards-builder/references/13-configuration-dependencies-and-ci.md +71 -0
  34. package/template/skills/typescript-standards-builder/references/14-security-performance-and-i18n.md +32 -0
  35. package/template/skills/typescript-standards-builder/references/15-git-review-and-delivery.md +28 -0
  36. package/template/skills/typescript-standards-builder/references/16-adoption-exceptions-and-migration.md +61 -0
  37. package/template/skills/typescript-standards-builder/references/17-generation-contract.md +104 -0
  38. package/template/skills/typescript-standards-builder/references/README.md +37 -0
  39. package/template/skills/typescript-standards-builder/templates/agents-compat-skill/SKILL.md +1 -0
  40. package/template/skills/typescript-standards-builder/templates/claude-skill/SKILL.md +1 -0
  41. package/template/skills/typescript-standards-builder/templates/project-skill/SKILL.md.template +34 -0
  42. package/template/skills/typescript-standards-builder/templates/project-skill/references/00-project-profile.md.template +17 -0
  43. package/template/skills/typescript-standards-builder/templates/project-skill/references/10-review-checklist.md +23 -0
  44. package/template/skills/typescript-standards-builder/templates/project-skill/references/11-decisions-and-exceptions.md.template +19 -0
  45. package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md +78 -73
  46. package/template/workflows/specdev/G-grill-with-docs/design-tree-template.json +9 -0
  47. package/template/workflows/specdev/G-grill-with-docs/grilling-protocol.md +16 -35
  48. package/template/workflows/specdev/G-grill-with-docs/log-format.md +2 -0
  49. package/template/workflows/specdev/I-implement/I-implement.md +12 -10
  50. package/template/workflows/specdev/I-implement/design-it-twice.md +45 -6
  51. package/template/workflows/specdev/I-implement/evidence-template.md +7 -0
  52. package/template/workflows/specdev/I-implement/execution-preflight.md +6 -0
  53. package/template/workflows/specdev/INDEX.md +11 -4
  54. package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +23 -10
  55. package/template/workflows/specdev/P-goal-plan/completion-control.md +20 -7
  56. package/template/workflows/specdev/P-goal-plan/goal-plan-template.md +55 -3
  57. package/template/workflows/specdev/P-goal-plan/orchestration-protocol.md +42 -38
  58. package/template/workflows/specdev/P-goal-plan/planning-modes.md +36 -2
  59. package/template/workflows/specdev/R-review-architecture/R-review-architecture.md +67 -80
  60. package/template/workflows/specdev/R-review-architecture/architecture-report-contract.md +123 -0
  61. package/template/workflows/specdev/R-review-architecture/architecture-review-report-template.html +103 -55
  62. package/template/workflows/specdev/R-review-architecture/architecture-review-template.md +20 -29
  63. package/template/workflows/specdev/W-wayfinder/W-wayfinder.md +76 -147
  64. package/template/workflows/specdev/W-wayfinder/investigation-ticket-template.md +8 -53
  65. package/template/workflows/specdev/W-wayfinder/local-tracker-contract.md +36 -0
  66. package/template/workflows/specdev/W-wayfinder/solution-comment-template.md +17 -0
  67. package/template/workflows/specdev/W-wayfinder/wayfinder-map-template.md +12 -65
  68. package/template/workflows/specdev/common/README.md +4 -0
  69. package/template/workflows/specdev/common/rules/artifact-contract.md +5 -0
  70. package/template/workflows/specdev/common/rules/codebase-design.md +148 -0
  71. package/template/workflows/specdev/common/schemas/design-tree.schema.json +35 -0
  72. package/template/workflows/specdev/common/schemas/wayfinder-ticket.schema.json +19 -0
  73. package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +61 -0
  74. package/template/workflows/specdev/common/skills/subagent-delivery/references/external-web-subagent.md +32 -0
  75. package/template/workflows/specdev/common/skills/subagent-delivery/references/github-checkpoints.md +24 -0
  76. package/template/workflows/specdev/common/skills/subagent-delivery/references/native-subagent.md +35 -0
  77. package/template/workflows/specdev/common/skills/subagent-delivery/references/source-package.md +17 -0
  78. package/template/workflows/specdev/common/tools/validate-specdev.mjs +226 -5
  79. package/template/skills/agents-md-builder/SKILL.md +0 -30
  80. package/template/skills/typescript-engineering-standards/README.md +0 -36
  81. package/template/skills/typescript-engineering-standards/SKILL.md +0 -158
  82. package/template/skills/typescript-engineering-standards/examples/comment-patterns.md +0 -47
  83. package/template/skills/typescript-engineering-standards/examples/naming-patterns.md +0 -42
  84. package/template/skills/typescript-engineering-standards/examples/project-layouts.md +0 -75
  85. package/template/skills/typescript-engineering-standards/examples/review-output-example.md +0 -25
  86. package/template/skills/typescript-engineering-standards/examples/type-modeling-patterns.md +0 -66
  87. package/template/skills/typescript-engineering-standards/manifest.txt +0 -33
  88. package/template/skills/typescript-engineering-standards/references/00-standard-levels-and-precedence.md +0 -51
  89. package/template/skills/typescript-engineering-standards/references/01-project-architecture-and-directory-layout.md +0 -105
  90. package/template/skills/typescript-engineering-standards/references/02-file-directory-and-symbol-naming.md +0 -117
  91. package/template/skills/typescript-engineering-standards/references/03-modules-imports-exports-and-dependencies.md +0 -111
  92. package/template/skills/typescript-engineering-standards/references/04-typescript-type-system.md +0 -150
  93. package/template/skills/typescript-engineering-standards/references/05-functions-async-errors-and-resources.md +0 -142
  94. package/template/skills/typescript-engineering-standards/references/06-comments-jsdoc-and-documentation.md +0 -104
  95. package/template/skills/typescript-engineering-standards/references/07-testing-strategy.md +0 -84
  96. package/template/skills/typescript-engineering-standards/references/08-react-and-frontend.md +0 -91
  97. package/template/skills/typescript-engineering-standards/references/09-node-cli-and-cross-platform.md +0 -92
  98. package/template/skills/typescript-engineering-standards/references/10-formatting-lint-and-complexity.md +0 -107
  99. package/template/skills/typescript-engineering-standards/references/11-configuration-dependencies-and-ci.md +0 -86
  100. package/template/skills/typescript-engineering-standards/references/12-security-performance-and-i18n.md +0 -65
  101. package/template/skills/typescript-engineering-standards/references/13-git-review-and-delivery.md +0 -79
  102. package/template/skills/typescript-engineering-standards/references/14-adoption-exceptions-and-migration.md +0 -84
  103. package/template/skills/typescript-engineering-standards/references/15-orca-derived-observations.md +0 -54
  104. package/template/skills/typescript-engineering-standards/references/README.md +0 -45
  105. package/template/skills/typescript-engineering-standards/templates/.editorconfig +0 -12
  106. package/template/skills/typescript-engineering-standards/templates/AGENTS.typescript.md +0 -21
  107. package/template/skills/typescript-engineering-standards/templates/code-review-checklist.md +0 -37
  108. package/template/skills/typescript-engineering-standards/templates/package-scripts.json +0 -11
  109. package/template/skills/typescript-engineering-standards/templates/prettier.json +0 -6
  110. package/template/skills/typescript-engineering-standards/templates/pull-request-template.md +0 -37
  111. package/template/skills/typescript-engineering-standards/templates/tsconfig.base.json +0 -17
  112. package/template/skills/typescript-engineering-standards/templates/tsconfig.project-references.json +0 -8
  113. package/template/workflows/specdev/I-implement/codebase-design-glossary.md +0 -12
  114. package/template/workflows/specdev/I-implement/deepening.md +0 -17
  115. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/content-contract.md +0 -0
  116. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/evidence-collection.md +0 -0
  117. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/manifest-discovery.md +0 -0
  118. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/role-classification.md +0 -0
  119. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/templates/aggregator-AGENTS.md +0 -0
  120. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/templates/capability-module-AGENTS.md +0 -0
  121. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/templates/contract-module-AGENTS.md +0 -0
  122. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/templates/repo-root-AGENTS.md +0 -0
  123. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/templates/runnable-app-AGENTS.md +0 -0
  124. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/templates/scripts-docs-AGENTS.md +0 -0
  125. /package/template/skills/{agents-md-builder/references → docs-sync/references/agents}/writing-style.md +0 -0
@@ -4,12 +4,12 @@ type: workflow-entry
4
4
  workflow: specdev
5
5
  name: 目标规划
6
6
  description: 在协调复杂度需要时,将 Ready Spec、Tickets、架构决策与外部约束综合为决策完备的跨 Ticket 编排计划。
7
- keywords: [目标规划, 编排, DAG, Gate, Wave, Lead, Subagent, 迁移, 证据]
7
+ keywords: [目标规划, 编排, DAG, Gate, Wave, Lead, Subagent, checkpoint, 派单, 迁移, 证据]
8
8
  ---
9
9
 
10
10
  # 目标规划
11
11
 
12
- Goal Plan 只解决单个 Ticket 无法独立决定的事情:跨 Ticket 顺序、并发、共享所有权、里程碑 Gate、集成验证、迁移与发布顺序、偏差升级和恢复。它不是 Ticket 的放大版,也不按固定章节数量衡量质量。
12
+ Goal Plan 只解决单个 Ticket 无法独立决定的事情:跨 Ticket 顺序、并发、共享所有权、里程碑 Gate、Agent 交付、集成验证、迁移与发布顺序、偏差升级和恢复。它不是 Ticket 的放大版,也不按固定章节数量衡量质量;每个 Ticket 的独立 Dispatch Packet 是 Goal Plan 的执行入口,不是第二份 Ticket。
13
13
 
14
14
  产物写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`。
15
15
 
@@ -54,9 +54,10 @@ Spec 或 Tickets Map 不存在时,返回 `<Path>{roots.workflows}/specdev/S-sp
54
54
 
55
55
  1. 验证 Spec Ready、Ticket Ready、合同覆盖、DAG、路径所有权和 Deep Ticket 完整性;
56
56
  2. 只读探索会影响调度的代码事实和项目约束;
57
- 3. 识别 coordination、migration、high-assurance、reference-conformance 等可组合模式;
58
- 4. 只对无法发现且会改变 Gate、Wave、owner、迁移或批准点的问题向用户提问;
59
- 5. 不熟悉的外部标准或依赖使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
57
+ 3. 识别 coordination、migration、high-assurance、reference-conformance 等可组合规划模式;
58
+ 4. `direct`、`native-subagent`、`external-web-subagent` 中选择唯一 execution model,并固定 Lead、源码 checkpoint、上下文交付和逐动作授权;
59
+ 5. 只对无法发现且会改变 Gate、Wave、owner、执行模型、迁移或批准点的问题向用户提问;
60
+ 6. 不熟悉的外部标准或依赖使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
60
61
 
61
62
  任何硬停止问题都必须退回拥有该决策的上游工件,不得用 Goal Plan 覆盖。
62
63
 
@@ -69,7 +70,10 @@ Spec 或 Tickets Map 不存在时,返回 `<Path>{roots.workflows}/specdev/S-sp
69
70
  3. 为 shared path、共享合同和集中变更指定唯一 owner;
70
71
  4. 为行为闭环、合同稳定、迁移完成、发布就绪等关键状态定义 Gate;
71
72
  5. 明确 expand → migrate → contract、Evidence 返回和集成规则;并行写代码时使用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`;
72
- 6. 将每个 Ticket 需要的执行上下文压缩成派单载荷,不复制整个历史对话。
73
+ 6. `operation=plan` 调用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`,生成里程碑 Delivery Contract 和每个 Ticket 可独立投递的 Dispatch Packet;
74
+ 7. 派单块只携带实现所需的权威引用、边界、基线、验证、恢复和返回字段,不复制完整历史对话或 Ticket 全文。
75
+
76
+ **完成标准**:DAG、Wave、Gate 与 Tickets Map 一致;每个计划 Ticket 都有唯一 owner、基线和可恢复派单块。
73
77
 
74
78
  ### 3. 定义整体完成、证据与恢复
75
79
 
@@ -78,8 +82,11 @@ Spec 或 Tickets Map 不存在时,返回 `<Path>{roots.workflows}/specdev/S-sp
78
82
  1. 将整体目标、非目标和权威来源压缩为一个可审查摘要;
79
83
  2. 定义整体 Definition of Done 和每个 Gate 的关闭证据;
80
84
  3. 固化跨 Ticket 不可协商约束;
81
- 4. 定义偏差等级、暂停范围、批准人和恢复动作;
82
- 5. 定义进度回报、Evidence 汇总、残余风险和回滚要求。
85
+ 4. 区分不可违反约束与可由实现者调整的建议;
86
+ 5. 定义实测基线、反向验证、防伪完成、偏差等级、修正上限、暂停范围、批准人和恢复动作;
87
+ 6. 定义进度回报、Evidence 汇总、残余风险和回滚要求。
88
+
89
+ **完成标准**:所有完成声明能映射到实际命令、代码状态、Evidence 或人工批准;没有 provider 自报即通过的门禁。
83
90
 
84
91
  ### 4. 写入自适应 Goal Plan
85
92
 
@@ -96,6 +103,8 @@ Spec 或 Tickets Map 不存在时,返回 `<Path>{roots.workflows}/specdev/S-sp
96
103
 
97
104
  Ticket 较多时在 Execution Graph 内增加速查表;不创建独立的第二套状态来源。
98
105
 
106
+ Goal Plan 不受单次 `/goal` 字符上限约束。需要粘贴到外部 Agent 时,只投递对应 Ticket 的 Dispatch Packet 及其指向的权威材料。
107
+
99
108
  ### 5. 同步与验证
100
109
 
101
110
  1. 将 Wave、Gate 和 owner 投影同步到 `<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>`;
@@ -108,8 +117,9 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
108
117
  ```
109
118
 
110
119
  4. 更新 `<Path>{roots.state}/specdev/status.json</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`;
111
- 5. 向用户汇报模式、关键路径、WaveGate、shared owner、迁移策略、主要风险和 Ready 状态;
112
- 6. 未经用户要求,不自动进入实现。
120
+ 5. 原子写入 Goal Plan 和同步投影后重新读取,确认 execution model、Lead、checkpoint、授权、Wave/Gate 与派单块一致;
121
+ 6. 向用户汇报规划模式、execution model、关键路径、Wave、Gate、shared owner、checkpoint、迁移策略、主要风险和 Ready 状态;
122
+ 7. 未经用户要求,不自动进入实现。
113
123
 
114
124
  ## 决策完备标准
115
125
 
@@ -120,6 +130,7 @@ Goal Plan 必须让执行 Lead 或实现者无需重新决定:
120
130
  - Gate 开启、关闭和证据;
121
131
  - 迁移、兼容、收缩、发布和回滚顺序;
122
132
  - Agent 派单上下文、Evidence 返回和集成规则;
133
+ - execution model、Lead、checkpoint、上下文交付、修正上限和逐动作授权;
123
134
  - 偏差等级、暂停范围和批准路径。
124
135
 
125
136
  Goal Plan 不应重复:
@@ -134,6 +145,7 @@ Goal Plan 不应重复:
134
145
  - `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 已写入且只包含适用内容;
135
146
  - 所有计划内 Ticket Ready,DAG 无环,合同覆盖明确;
136
147
  - Wave、Gate、owner、集成、偏差和恢复可执行;
148
+ - 每个计划 Ticket 的 Dispatch Packet 可独立定位权威输入、路径合同、验证和恢复点;
137
149
  - Tickets Map 投影已同步;
138
150
  - 无未批准高影响假设或硬停止问题;
139
151
  - `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 无 error;
@@ -146,3 +158,4 @@ Goal Plan 不应重复:
146
158
  - 完成、证据、偏差与恢复:`<Path>{roots.workflows}/specdev/P-goal-plan/completion-control.md</Path>`
147
159
  - Goal Plan 模板:`<Path>{roots.workflows}/specdev/P-goal-plan/goal-plan-template.md</Path>`
148
160
  - 并行 Ticket worktree:`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`
161
+ - Agent 交付合同:`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
@@ -9,7 +9,8 @@ Goal Plan 用紧凑摘要表达:
9
9
  - 所有计划 Ticket 完成后的可观察终态;
10
10
  - 关键约束;
11
11
  - 明确非目标;
12
- - 权威来源和冲突规则。
12
+ - 权威来源和冲突规则;
13
+ - 看似有主路径但违反边界、数据、兼容或证据要求的伪完成判据。
13
14
 
14
15
  不复制 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 的完整用户故事。
15
16
 
@@ -19,10 +20,12 @@ Goal Plan 用紧凑摘要表达:
19
20
 
20
21
  - 所有计划内 Ticket 完成,cancelled 或 deferred 项有批准;
21
22
  - 所有 Spec 验收合同和外部符合性要求有 Evidence;
22
- - 项目类型检查、静态检查、测试、lint、构建和适用 CI 完成;仅 UI 交互受影响时由 Lead 完成 E2E;
23
+ - 项目类型检查、静态检查、测试、lint、构建和适用 CI 完成,测试数量、skip/todo、覆盖率或等价基线没有未经批准的退化;仅 UI 交互受影响时由 Lead 完成 E2E;
24
+ - 可静默失效的关键门禁完成受控反向验证并恢复绿色;普通门禁有明确不适用结论,不为形式破坏环境;
23
25
  - 迁移、兼容、调用点清零、监控、回滚和不可逆批准完成;
24
26
  - 无未批准偏差和未处置高风险残余问题;
25
- - Ticket、Map、Goal Plan、Evidence 和状态一致。
27
+ - Ticket、Map、Goal Plan、Evidence、源码 checkpoint 和状态一致;
28
+ - provider 或 Worker 自报结果均已由 Lead 核对,未核对项保持 `unverified`。
26
29
 
27
30
  ## 3. Gate 关闭仪式
28
31
 
@@ -32,14 +35,17 @@ Goal Plan 用紧凑摘要表达:
32
35
  2. 检查对应合同和参考符合性;
33
36
  3. 检查共享接口、数据、兼容、迁移和调用点;
34
37
  4. 运行里程碑级验证;仅 UI 交互受影响时由 Lead 运行最小 E2E;
35
- 5. 审查失败分类、偏差、残余风险和恢复能力;
36
- 6. 获取适用人工批准;
37
- 7. 同步 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 和状态工件。
38
+ 5. 对会出现“坏了但仍绿色”的关键门禁运行受控反向验证,记录失败信号和恢复后的通过证据;
39
+ 6. 审查基线退化、失败分类、偏差、残余风险和恢复能力;
40
+ 7. 获取适用人工批准;
41
+ 8. 同步 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/tickets-map.md</Path>` 和状态工件。
38
42
 
39
43
  ## 4. 不可协商约束
40
44
 
41
45
  只记录跨多个 Ticket 且不可由实现者改变的规则,例如数据完整性、wire format 兼容、旧协议收缩条件、shared owner、安全要求、发布窗口、回滚演练和批准点。
42
46
 
47
+ 每条约束同时说明违反后果。可由实现者沿现有惯例选择、且不改变行为或风险的事项写入 Guidance,不伪装成硬约束。
48
+
43
49
  来源必须指向:
44
50
 
45
51
  - `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`;
@@ -60,10 +66,14 @@ Goal Plan 用紧凑摘要表达:
60
66
  - 哪些 Evidence 失效;
61
67
  - 重新开始的条件。
62
68
 
63
- ## 6. 风险与恢复
69
+ ## 6. 风险、修正与恢复
64
70
 
65
71
  每个高风险项写明:触发信号、事故半径、预防措施、检测方式、恢复动作、owner 和批准点。迁移或发布计划必须给出回滚不可行时的前向恢复方案。
66
72
 
73
+ 每个 Dispatch Packet 记录 checkpoint、workspace/session locator、最近已验证 Evidence 和 `max_correction_rounds`。默认同一验收项最多修正 3 轮;达到上限后暂停当前 Ticket 和受影响 Wave,保留已通过行为,形成包含失败命令、最小错误、责任方和恢复条件的 blocker。
74
+
75
+ 恢复时依次读取 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>`、当前 Ticket、最新 Evidence 和 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`。从最后已验证 checkpoint 继续,不重复询问已确认事实,也不创建额外进度或阻塞文件。
76
+
67
77
  ## 7. 进度与决策回报
68
78
 
69
79
  使用可核验状态,不使用主观百分比:
@@ -72,8 +82,11 @@ Goal Plan 用紧凑摘要表达:
72
82
  WAVE_STATUS wave=<n> ready=<ids> active=<ids> done=<ids> blocked=<ids>
73
83
  GATE_STATUS gate=<name> state=open|closed evidence=<paths> risks=<summary>
74
84
  TICKET_STATUS id=<id> state=<state> evidence=<path> deviation=<none|id>
85
+ DELIVERY_STATUS id=<id> model=<model> checkpoint=<sha> locator=<ref> corrections=<n> unverified=<items|none>
75
86
  BLOCKER id=<id> owner=<owner> needed=<decision-or-input> impact=<scope>
76
87
  DECISION id=<id> owner=<owner> status=pending|approved|rejected impact=<scope>
77
88
  ```
78
89
 
79
90
  具体路径必须以完整 Path 标签 形式填写。
91
+
92
+ **完成标准**:进度可由权威工件恢复;所有通过、阻塞和未验证声明均能定位到具体 Evidence 与源码 checkpoint。
@@ -19,6 +19,8 @@ ready_for_execution: false
19
19
 
20
20
  ### Outcome
21
21
 
22
+ ### Success and False Completion
23
+
22
24
  ### Non-goals
23
25
 
24
26
  ### Authoritative Inputs
@@ -68,9 +70,45 @@ ready_for_execution: false
68
70
 
69
71
  ## 4. Execution and Integration Protocol
70
72
 
71
- ### Dispatch Payload
72
-
73
- 并行写代码时记录统一 `base_sha`,并为每个 Ticket 指定分支、`workspace_ref` 和 worktree owner。
73
+ ### Delivery Contract
74
+
75
+ | 字段 | |
76
+ |---|---|
77
+ | Execution model | direct / native-subagent / external-web-subagent |
78
+ | Lead / Provider | `<owner>` / `<provider-or-none>` |
79
+ | Repository / Branch | `<repository-or-local>` / `<branch-or-n/a>` |
80
+ | Checkpoint policy | immutable SHA / local baseline |
81
+ | Source delivery | none / repository-url / source-package / combination |
82
+ | Max concurrency / corrections | `<n>` / `3` |
83
+ | Review | standards + spec + Lead verification + conditional E2E |
84
+
85
+ ### Authorization Matrix
86
+
87
+ | 动作 | 状态 | 目标与条件 |
88
+ |---|---|---|
89
+ | Local changes | allowed / not-authorized | ... |
90
+ | Commit | allowed / not-authorized | ... |
91
+ | Push / PR / Merge | allowed / not-authorized | ... |
92
+ | Deploy / Migration | allowed / not-authorized | ... |
93
+ | Production configuration / feature / real user data | allowed / not-authorized | ... |
94
+
95
+ ### Per-Ticket Dispatch Packets
96
+
97
+ #### Dispatch: T-01
98
+
99
+ - **Goal / observable result:**
100
+ - **Priority on conflict:** correctness > contract completeness > speed,或当前项目裁决
101
+ - **Implement / Ticket:** `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`;`<Path>{roots.state}/specdev/changes/{change}/ticket/01-<name>.md</Path>`
102
+ - **Authority / dependencies:** 相关合同、ADR/CONTEXT、已完成依赖 Evidence
103
+ - **Wave / Gate / hard constraints:**
104
+ - **Writable / read-only / shared owner:**
105
+ - **Baseline / branch / workspace or session locator / package hash:**
106
+ - **Preflight receipt:** 在 `<Path>{roots.state}/specdev/changes/{change}/evidence/T-01.md</Path>` 记录目标、顺序、最大风险和基线差异,不超过 10 行
107
+ - **Verification / baseline / reverse check:**
108
+ - **Authorization / deviation / correction limit:**
109
+ - **Return:** 状态、Evidence、locator、最终 checkpoint、commit/PR、未验证项、待 Lead E2E
110
+
111
+ 并行写代码时记录统一 `base_sha`,并为每个 Ticket 指定分支、`workspace_ref` 和 worktree owner。每个派单块可以独立投递,但不复制完整 Ticket 或历史对话。
74
112
 
75
113
  ### Ticket Execution
76
114
 
@@ -84,6 +122,12 @@ Worker 将 Ticket 推进到 `review`,返回 Ticket ID 与状态、Evidence 路
84
122
 
85
123
  ### Non-negotiable Constraints
86
124
 
125
+ 每条包含来源和违反后果;局部实现自由进入 Guidance。
126
+
127
+ ### Verification Integrity
128
+
129
+ 记录不可修改的判卷接缝、基线非退化条件、禁止的伪绿色方式,以及仅对静默失败风险执行的受控反向验证。
130
+
87
131
  ### Migration or Release Sequence
88
132
 
89
133
  ### Risks, Monitoring and Recovery
@@ -96,8 +140,16 @@ Worker 将 Ticket 推进到 `review`,返回 Ticket ID 与状态、Evidence 路
96
140
 
97
141
  ### Current Status
98
142
 
143
+ 记录 Wave/Gate、Ticket、checkpoint、workspace/session locator、修正轮次和未验证项;不使用主观百分比。
144
+
99
145
  ### Pending Decisions and Blockers
100
146
 
147
+ 达到修正上限时记录最后可信 checkpoint、失败命令、已通过行为、owner 和恢复条件。
148
+
149
+ ### Resume Protocol
150
+
151
+ 恢复时读取本 Goal Plan、当前 Ticket、最新 Evidence 和 change 状态,从最后已验证 checkpoint 继续。
152
+
101
153
  ### Reporting Format
102
154
 
103
155
  ## Assumptions
@@ -1,6 +1,6 @@
1
1
  # Goal Plan 编排协议
2
2
 
3
- 本文件定义 DAG、Wave、Gate、路径所有权、Lead/Subagentworktree、Evidence 返回和集成规则。
3
+ 本文件定义 DAG、Wave、Gate、路径所有权、Delivery ContractDispatch Packet、Evidence 返回和集成规则。
4
4
 
5
5
  ## 1. DAG 与关键路径
6
6
 
@@ -58,58 +58,62 @@ Gate 由可验证状态定义,不用“完成若干 Ticket”作为唯一条
58
58
 
59
59
  收缩不得仅以“所有迁移 Ticket 已完成”为依据。
60
60
 
61
- ## 6. Lead/Subagent
61
+ ## 6. Lead 与 Delivery Contract
62
62
 
63
- Lead 负责基线、DAG、Wave、shared owner、GateEvidence 汇总和集成;不抢做已派发 Ticket 的实现。
63
+ Lead 负责源码基线、DAG、Wave、shared owner、Gate、权限、Evidence 汇总和集成;已派发 Ticket 的实现由对应执行者负责,Lead 不制造双重 owner。
64
64
 
65
- 并行写代码且配置允许时,Lead 为每个 Ticket 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`:
65
+ Goal Plan 选择唯一 execution model:`direct`、`native-subagent` 或 `external-web-subagent`。Lead `operation=plan` 调用 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`,生成里程碑级 Delivery Contract;Implement 阶段以 `operation=execute` 调用同一 Skill 做恢复和验收。
66
66
 
67
- - 所有并行 Ticket 固定同一 `base_sha`,每个 Ticket 使用独立分支和 `workspace_ref`;
68
- - Lead 创建、恢复、集成和清理;Worker 只把状态推进到 `review`;
69
- - 只读调查和顺序执行不为形式创建 worktree。
67
+ Delivery Contract 必须固定:
70
68
 
71
- 每个 Agent 的最小读取顺序:
69
+ - execution model、Lead、provider 和可恢复 workspace/session locator;
70
+ - repository、branch、不可变 checkpoint 与源码交付方式;
71
+ - 最大并发和默认 3 轮的 `max_correction_rounds`;
72
+ - 标准轴、规范轴、Lead 独立验证和条件性 E2E;
73
+ - local changes、commit、push、PR、merge、deploy、migration 和生产动作的逐项授权;
74
+ - 完成、阻塞、偏差、恢复和返回协议。
72
75
 
73
- 1. `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`;
74
- 2. `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`;
75
- 3. `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 中适用的 Wave、Gate 和硬约束;
76
- 4. `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 中相关合同;
77
- 5. `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 中相关条目;
78
- 6. 项目级 Agent 指令和当前代码事实。
76
+ 并行写代码且配置允许时,Lead 为每个 Ticket 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`。所有并行 Ticket 固定同一 `base_sha`,每个 Ticket 使用独立分支和 `workspace_ref`;Lead 创建、恢复、集成和清理,Worker 只推进到 `review`。只读调查和顺序执行不为形式创建 worktree。
79
77
 
80
- 不把完整历史对话、全部 Ticket 或无关研究塞入 Agent 上下文。
78
+ **完成标准**:整个 Goal Plan 只有一个 execution model 和 Lead;每个高影响动作都有明确授权状态。
81
79
 
82
- ## 7. 派单载荷
80
+ ## 7. Dispatch Packet
83
81
 
84
- 派单必须包含:
82
+ 每个计划 Ticket 都生成一个可独立投递的 Dispatch Packet。它不是 Ticket 副本,而是进入权威工件和当前基线的紧凑入口,至少包含:
85
83
 
86
- - Ticket ID 与 `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`;
87
- - 基线 SHA、分支和 `workspace_ref`;
88
- - 项目写、只读和 shared 路径;
89
- - 已完成依赖及其 Evidence;
90
- - 合同 ID
91
- - 适用 WaveGate 和跨 Ticket 约束;
92
- - 必须执行的验证矩阵;
93
- - 偏差升级方式和禁止修改事项。
84
+ 1. Ticket ID、目标、可观察完成结果和优先级冲突裁决;
85
+ 2. `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` `<Path>{roots.state}/specdev/changes/{change}/ticket/{ticket-file}.md</Path>`;
86
+ 3. 相关 Spec 合同、ADR/CONTEXT 条目、Wave、Gate 和不可协商约束;
87
+ 4. 已完成依赖及其 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`;
88
+ 5. 项目 `writable_paths`、`read_only_paths`、`shared_paths` 与唯一 shared owner
89
+ 6. `base_sha`、branchworkspace/session locator source package hash;
90
+ 7. 必跑验证、基线指标、可静默失效门禁的反向验证,以及明确不适用项;
91
+ 8. 当前授权、偏差升级、修正上限、Evidence 路径和返回字段。
92
+
93
+ 派单块将不可违反项写为 Hard Constraints,将低影响实现自由写为 Guidance。执行者必须先核对 checkpoint、项目指令、路径和验证命令,再在 Ticket Evidence 记录不超过 10 行的开工回执:目标、执行顺序、最大风险和发现的基线差异。事实不一致时停止受影响路径并升级,不用更详细文字掩盖失效前提。
94
+
95
+ Agent 的最小读取顺序为 Implement work、当前 Ticket、Goal Plan 中适用的 Delivery Contract/Dispatch Packet、相关 Spec/ADR/CONTEXT、项目 Agent 指令和当前代码事实。不投递完整历史对话、全部 Ticket 或无关研究。
96
+
97
+ **完成标准**:每个 Dispatch Packet 可在新上下文中定位全部权威输入、边界、基线、验证、恢复点和返回目标。
94
98
 
95
99
  ## 8. Evidence 返回与集成
96
100
 
97
101
  Agent 完成或阻塞时:
98
102
 
99
- 1. 写入 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`;
103
+ 1. 写入 `<Path>{roots.state}/specdev/changes/{change}/evidence/{ticket-id}.md</Path>`,包含实际修改、命令与退出状态、验收映射、反向验证、修正轮次、checkpoint 和未验证项;
100
104
  2. 同步 Ticket、Tickets Map、Goal Plan 和 change 状态;
101
- 3. 向 Lead 返回 Ticket ID 与状态、Evidence 完整路径、`workspace_ref`、commit PR 引用,以及仅在用户界面交互受影响时由 Lead 执行的待办 E2E。
105
+ 3. 向 Lead 返回 Ticket ID 与状态、Evidence 完整路径、workspace/session locator、最终 checkpoint、commit/PR 引用和条件性 Lead E2E。
106
+
107
+ Lead 接收原生或外部候选交付时:
102
108
 
103
- Lead 集成时:
109
+ 1. 读取 Dispatch Packet、Ticket、Evidence、Goal Plan 和对应代码引用;
110
+ 2. 检查 checkpoint、附件 hash、路径授权、依赖和敏感信息边界;
111
+ 3. 在隔离基线上应用交付,复跑定向验证和受影响回归;
112
+ 4. 仅当用户界面交互受影响时,由 Lead 运行最小 E2E;
113
+ 5. 将 provider 声明、模拟结果和静态推断保持为 `unverified`,直到有独立证据;
114
+ 6. 验证通过后集成,并按 dev-worktree Skill 更新或清理 worktree;
115
+ 7. 同步 Ticket、Map、Evidence 和 Goal Plan,检查 Gate 是否可关闭。
104
116
 
105
- 1. 读取 Ticket、Evidence、Goal Plan 和对应代码引用;
106
- 2. 检查路径授权;
107
- 3. 复跑定向验证;
108
- 4. 合并或应用变更;
109
- 5. 运行受影响回归;
110
- 6. 仅当用户界面交互受影响时,由 Lead 运行最小 E2E;
111
- 7. 按 dev-worktree Skill 更新或清理 worktree;
112
- 8. 同步 Ticket、Map、Evidence 和 Goal Plan;
113
- 9. 检查 Gate 是否可关闭。
117
+ 同一验收项达到修正上限时标记 blocker,记录最后 checkpoint、错误、已通过行为、责任方和恢复条件。逻辑冲突返回契约 owner 解决,不机械选择某一侧版本。
114
118
 
115
- 逻辑冲突返回契约和 owner 解决,不机械选择某一侧版本。
119
+ **完成标准**:每个完成声明可追溯到 Lead 核对的代码状态和 Evidence;失败也具有可恢复的最后可信 checkpoint。
@@ -13,6 +13,8 @@
13
13
  - [ ] 可能并行的 Ticket 项目写路径不相交,或已有 shared owner 与排序方案。
14
14
  - [ ] Deep Ticket 具备迁移、兼容、监控、回滚、收缩条件和批准点。
15
15
  - [ ] Ticket 与 Spec、ADR、代码事实不存在未处理冲突。
16
+ - [ ] 项目声明的验证命令真实存在且能观察目标行为;不可运行项有替代证据或明确 blocker。
17
+ - [ ] 当前源码基线、工作区状态和外部合同版本已实测,而非使用浮动的“最新”描述。
16
18
 
17
19
  ## 2. 硬停止
18
20
 
@@ -26,7 +28,9 @@
26
28
  - Ticket 与 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 的已接受决策冲突;
27
29
  - Deep Ticket 缺少关键迁移或恢复信息;
28
30
  - 当前代码事实使 Ticket 的核心行为、接口或验证不可执行;
29
- - 必需外部合同或参考权威不可获得。
31
+ - 必需外部合同或参考权威不可获得;
32
+ - 选择 delegated execution,但 Lead、checkpoint、可恢复 locator 或交付通道无法建立;
33
+ - 用户要求的远程或生产动作没有逐动作授权。
30
34
 
31
35
  按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/deviation-control.md</Path>` 返回真正拥有该决策的工件。
32
36
 
@@ -54,17 +58,47 @@
54
58
 
55
59
  模式可以组合。仅有线性低风险 Ticket 时不应为了形式生成重型 Goal Plan。
56
60
 
57
- ## 4. 模式摘要
61
+ ## 4. 执行模型与交付事实
62
+
63
+ 规划模式描述“为什么需要治理”,execution model 描述“每个 Ticket 怎样被执行”,两者不得混为同一枚举。每份 Goal Plan 只选一个主 execution model:
64
+
65
+ - `direct`:Lead 或当前执行者直接运行 Ticket,不创建子代理交付通道;
66
+ - `native-subagent`:Lead 可直接管理隔离 Agent,写代码并行时配合 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`;
67
+ - `external-web-subagent`:通过网页 provider 交付,输出在 Lead 独立核对前保持候选状态。
68
+
69
+ 选择模型前先发现当前平台能力、项目配置和用户请求。只有用户明确指定 provider 或交付通道时才把偏好当作约束;否则优先使用能保留隔离、checkpoint 和 Evidence 的现有原生能力。
70
+
71
+ 必须固定:
72
+
73
+ - `lead` 与不可转移责任;
74
+ - provider 和稳定 workspace/session locator,direct 时为不适用;
75
+ - repository/branch 与不可变 `base_sha` 或等价本地基线;
76
+ - `source_delivery`:none、repository-url、source-package 或 combination;
77
+ - `max_correction_rounds`,默认 3;
78
+ - local changes、commit、push、PR、merge、deploy、migration、production configuration、production feature、real user data 的逐动作授权。
79
+
80
+ GitHub checkpoint、源码包和 provider 分支由 `<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>` 按需加载。认证秘密和机器绝对路径不得进入 Goal Plan。
81
+
82
+ ## 5. 模式摘要
58
83
 
59
84
  写入 `<Path>{roots.state}/specdev/changes/{change}/goal-plan.md</Path>` 前形成:
60
85
 
61
86
  ```text
62
87
  modes=<mode-list>
88
+ execution_model=<direct|native-subagent|external-web-subagent>
89
+ lead=<owner>
90
+ provider=<id|none>
63
91
  tickets=<count>
64
92
  critical_path=<ticket-list>
65
93
  parallel_capacity=<n>
94
+ checkpoint=<sha-or-local-baseline>
95
+ source_delivery=<mode>
96
+ max_correction_rounds=<n>
66
97
  shared_owners=<owner-map>
67
98
  gates=<gate-list>
99
+ authorization=<action-summary>
68
100
  hard_stops=<none-or-list>
69
101
  adopted_assumptions=<low-impact-only>
70
102
  ```
103
+
104
+ **完成标准**:可组合 modes 与唯一 execution model 分离;源码、交付、权限和恢复字段都有可验证值。