@namewta/speculo 1.0.1 → 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 (128) hide show
  1. package/README.md +8 -3
  2. package/package.json +2 -2
  3. package/template/AGENTS.md +14 -1
  4. package/template/canonical/canonical-specdev-goal-plan.md +758 -217
  5. package/template/canonical/canonical-specdev-grill-with-docs.md +222 -127
  6. package/template/canonical/canonical-specdev-spec.md +79 -2
  7. package/template/canonical/canonical-specdev-tickets.md +691 -255
  8. package/template/canonical/canonical-specdev-wayfinder.md +331 -107
  9. package/template/commands/archive-and-consolidate.md +1 -2
  10. package/template/commands/docs-sync.md +1 -1
  11. package/template/commands/git-repository-audit.md +4 -603
  12. package/template/commands/handoff.md +1 -1
  13. package/template/commands/references/git-repository-audit-procedure.md +608 -0
  14. package/template/commands/retro.md +1 -1
  15. package/template/commands/status.md +1 -1
  16. package/template/skills/archive-and-consolidate/SKILL.md +9 -168
  17. package/template/skills/archive-and-consolidate/references/entry-procedure.md +170 -0
  18. package/template/skills/docs-sync/SKILL.md +9 -11
  19. package/template/skills/docs-sync/references/entry-procedure.md +18 -0
  20. package/template/skills/engineering-standards-builder/SKILL.md +9 -148
  21. package/template/skills/engineering-standards-builder/references/entry-procedure.md +154 -0
  22. package/template/skills/git-history-squash/SKILL.md +9 -88
  23. package/template/skills/git-history-squash/references/entry-procedure.md +94 -0
  24. package/template/skills/github-npm-ops/SKILL.md +9 -18
  25. package/template/skills/github-npm-ops/references/entry-procedure.md +25 -0
  26. package/template/skills/optimize-codex-config/SKILL.md +12 -72
  27. package/template/skills/optimize-codex-config/references/entry-procedure.md +78 -0
  28. package/template/skills/source-code-zip/SKILL.md +10 -559
  29. package/template/skills/source-code-zip/references/entry-procedure.md +565 -0
  30. package/template/skills/speculo-retro/SKILL.md +9 -16
  31. package/template/skills/speculo-retro/references/entry-procedure.md +23 -0
  32. package/template/skills/upstream-fork-sync/SKILL.md +10 -72
  33. package/template/skills/upstream-fork-sync/references/entry-procedure.md +78 -0
  34. package/template/skills/writing-great-skills/SKILL.md +10 -72
  35. package/template/skills/writing-great-skills/references/document-contract.md +23 -0
  36. package/template/skills/writing-great-skills/references/entry-procedure.md +79 -0
  37. package/template/workflows/learning/A-archive/A-archive.md +7 -0
  38. package/template/workflows/learning/A-assess-and-plan/A-assess-and-plan.md +7 -0
  39. package/template/workflows/learning/C-consolidate/C-consolidate.md +7 -0
  40. package/template/workflows/learning/H-homework/H-homework.md +8 -1
  41. package/template/workflows/learning/I-init-setup/I-init-setup.md +7 -0
  42. package/template/workflows/learning/INDEX.md +2 -0
  43. package/template/workflows/learning/L-lesson/L-lesson.md +7 -0
  44. package/template/workflows/learning/R-review/R-review.md +8 -1
  45. package/template/workflows/learning/README.md +3 -1
  46. package/template/workflows/learning/common/rules/activation-and-memory.md +24 -0
  47. package/template/workflows/ops/A-archive-and-learn/A-archive-and-learn.md +7 -0
  48. package/template/workflows/ops/E-execute-and-stabilize/E-execute-and-stabilize.md +8 -1
  49. package/template/workflows/ops/I-intake-and-assess/I-intake-and-assess.md +7 -0
  50. package/template/workflows/ops/INDEX.md +2 -0
  51. package/template/workflows/ops/P-plan-and-approve/P-plan-and-approve.md +8 -1
  52. package/template/workflows/ops/README.md +3 -0
  53. package/template/workflows/ops/common/rules/activation-and-memory.md +24 -0
  54. package/template/workflows/person/INDEX.md +2 -0
  55. package/template/workflows/person/M-mao-zedong-cognitive-os/M-mao-zedong-cognitive-os.md +9 -0
  56. package/template/workflows/person/M-mao-zedong-cognitive-os/books/README.md +1 -1
  57. package/template/workflows/person/S-steelman-deliberation/S-steelman-deliberation.md +7 -0
  58. package/template/workflows/person/common/rules/activation-and-memory.md +24 -0
  59. package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md +7 -0
  60. package/template/workflows/specdev/C-code-review/C-code-review.md +7 -0
  61. package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md +7 -0
  62. package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md +14 -130
  63. package/template/workflows/specdev/G-grill-with-docs/references/interview-procedure.md +134 -0
  64. package/template/workflows/specdev/I-implement/I-implement.md +16 -183
  65. package/template/workflows/specdev/I-implement/evidence-template.md +12 -0
  66. package/template/workflows/specdev/I-implement/execution-preflight.md +2 -2
  67. package/template/workflows/specdev/I-implement/references/implementation-procedure.md +192 -0
  68. package/template/workflows/specdev/I-init-setup/I-init-setup.md +7 -0
  69. package/template/workflows/specdev/INDEX.md +2 -0
  70. package/template/workflows/specdev/L-learn-change/L-learn-change.md +7 -0
  71. package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +29 -135
  72. package/template/workflows/specdev/P-goal-plan/completion-control.md +1 -1
  73. package/template/workflows/specdev/P-goal-plan/references/goal-lifecycle.md +35 -0
  74. package/template/workflows/specdev/P-goal-plan/references/goal-tickets-map-template.md +15 -0
  75. package/template/workflows/specdev/P-goal-plan/references/map-control.md +28 -0
  76. package/template/workflows/specdev/{O-orchestrate-implementation/O-orchestrate-implementation.md → P-goal-plan/references/multi-change-plan.md} +25 -28
  77. package/template/workflows/specdev/P-goal-plan/references/replan-and-recovery.md +21 -0
  78. package/template/workflows/specdev/P-goal-plan/references/single-change-plan.md +149 -0
  79. package/template/workflows/specdev/P-prototype/P-prototype.md +7 -0
  80. package/template/workflows/specdev/R-review-architecture/R-review-architecture.md +52 -50
  81. package/template/workflows/specdev/R-review-architecture/architecture-review-template.md +19 -10
  82. package/template/workflows/specdev/R-review-architecture/proposal-to-ticket.md +3 -1
  83. package/template/workflows/specdev/R-review-architecture/review-rubric.md +52 -0
  84. package/template/workflows/specdev/README.md +37 -214
  85. package/template/workflows/specdev/S-spec/S-spec.md +7 -0
  86. package/template/workflows/specdev/T-tickets/T-tickets.md +20 -224
  87. package/template/workflows/specdev/T-tickets/references/planning-procedure.md +233 -0
  88. package/template/workflows/specdev/T-tickets/ticket-template.md +18 -2
  89. package/template/workflows/specdev/T-tickets/tickets-map-template.md +15 -1
  90. package/template/workflows/specdev/T-triage/T-triage.md +10 -1
  91. package/template/workflows/specdev/W-wayfinder/W-wayfinder.md +25 -112
  92. package/template/workflows/specdev/W-wayfinder/references/initiative-discovery.md +29 -0
  93. package/template/workflows/specdev/W-wayfinder/references/initiative-template.json +8 -0
  94. package/template/workflows/specdev/W-wayfinder/references/map-traversal.md +120 -0
  95. package/template/workflows/specdev/W-wayfinder/wayfinder-map-template.md +4 -0
  96. package/template/workflows/specdev/common/README.md +2 -1
  97. package/template/workflows/specdev/common/rules/activation-and-memory.md +24 -0
  98. package/template/workflows/specdev/common/rules/artifact-contract.md +10 -2
  99. package/template/workflows/specdev/common/rules/operating-governance.md +38 -0
  100. package/template/workflows/specdev/common/rules/parent-implementation-orchestration.md +6 -2
  101. package/template/workflows/specdev/common/rules/skill-invocation.md +27 -0
  102. package/template/workflows/specdev/common/rules/workflow-routing.md +24 -0
  103. package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md +93 -0
  104. package/template/workflows/specdev/common/schemas/goal-tickets-map.schema.json +33 -0
  105. package/template/workflows/specdev/common/schemas/initiative.schema.json +94 -0
  106. package/template/workflows/specdev/common/schemas/ticket.schema.json +168 -1
  107. package/template/workflows/specdev/common/schemas/tickets-map.schema.json +74 -6
  108. package/template/workflows/specdev/common/skills/code-review/SKILL.md +3 -2
  109. package/template/workflows/specdev/common/skills/code-review/references/risk-review.md +25 -0
  110. package/template/workflows/specdev/common/skills/plan-quality-review/SKILL.md +10 -0
  111. package/template/workflows/specdev/common/skills/plan-quality-review/references/checklist.md +13 -0
  112. package/template/workflows/specdev/common/skills/subagent-delivery/SKILL.md +5 -83
  113. package/template/workflows/specdev/common/skills/subagent-delivery/references/dispatch-and-accept.md +87 -0
  114. package/template/workflows/specdev/common/tools/README.md +14 -2
  115. package/template/workflows/specdev/common/tools/plan-contract.mjs +256 -0
  116. package/template/workflows/specdev/common/tools/ticket-control.mjs +251 -0
  117. package/template/workflows/specdev/common/tools/validate-specdev.mjs +58 -40
  118. package/template/workflows/specdev/manifest.json +97 -1
  119. package/template/canonical/canonical-specdev-orchestrate-implementation.md +0 -2823
  120. package/template/workflows/specdev/O-orchestrate-implementation/implementation-evidence-template.md +0 -39
  121. package/template/workflows/specdev/O-orchestrate-implementation/implementation-map-template.md +0 -50
  122. package/template/workflows/specdev/O-orchestrate-implementation/implementation-plan-template.md +0 -61
  123. package/template/workflows/specdev/R-review-architecture/architecture-report-contract.md +0 -123
  124. package/template/workflows/specdev/R-review-architecture/architecture-review-report-template.html +0 -106
  125. /package/template/workflows/specdev/{O-orchestrate-implementation/conflict-and-drift.md → P-goal-plan/references/multi-conflict-and-drift.md} +0 -0
  126. /package/template/workflows/specdev/{O-orchestrate-implementation/execution-loop.md → P-goal-plan/references/multi-execution-loop.md} +0 -0
  127. /package/template/workflows/specdev/{O-orchestrate-implementation/input-readiness.md → P-goal-plan/references/multi-input-readiness.md} +0 -0
  128. /package/template/workflows/specdev/{O-orchestrate-implementation/super-dag.md → P-goal-plan/references/multi-super-dag.md} +0 -0
@@ -1,4 +1,4 @@
1
- # 拆分 Tickets
1
+ # 编写计划型 Tickets
2
2
 
3
3
  ## 网页平台运行约定
4
4
 
@@ -11,235 +11,34 @@
11
11
  - 项目代码与测试始终使用项目根相对路径;不写机器绝对路径。工件之间使用上述逻辑路径,不使用 Speculo 的运行时路径标签。
12
12
  - 如果网页平台不能直接写项目文件,则按目标文件名输出完整内容,并在答复中明确应保存的位置;不得把“无法写文件”伪装成已经持久化。
13
13
  - 若本地项目提供 Speculo Node 校验器,可运行它补充结构校验;纯网页环境按本文内联的 schema、Ready 清单和完成标准逐项核对,并明确记录未运行的自动校验。
14
+ - 本地只读 Goal 控制器和 Plan 合同校验库不随网页快照提供,不能把其名称当作可执行命令。网页执行者按内联 map-control/调用合同逐项计算依赖与门禁;缺少真实项目 Skill 源或执行能力时阻塞对应任务,不声称自动验证通过。
14
15
  - 提交、推送、合并、部署、发布、归档移动和不可逆迁移仍需用户明确授权。
15
16
 
16
- Ticket 是**决策完备的微型执行计划**:它消除执行者在目标、范围、公共契约、关键顺序和验收上的关键决策,但不展开逐行代码、局部变量或可从现有惯例自然推导的实现细节。
17
-
18
- 本 work 保留原有能力:代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。
19
-
20
- ## 输入
21
-
22
- 优先读取:
23
-
24
- - 当前 Spec:`specdev/changes/{change}/spec.md`
25
- - 当前架构决策:`specdev/changes/{change}/ADR.md`
26
- - 当前领域上下文:`specdev/changes/{change}/CONTEXT.md`
27
- - 当前设计日志:`specdev/changes/{change}/LOG.md`
28
- - Bug 诊断:`specdev/changes/{change}/diagnosis.md`
29
- - 永久架构决策:`specdev/adr/`
30
- - 永久领域上下文:`specdev/context/`
31
- - 项目 Agent 指令及其声明的项目 Skill 根;
32
- - 项目当前代码、测试、配置、schema 和 CI 事实。
33
-
34
- 若尚无 `specdev/changes/{change}/spec.md`,只有在用户提供的计划或对话已经等价覆盖目标、范围、关键决定和可判定验收时才可继续;否则建议先运行 “编写 Spec 阶段”。
35
-
36
- ## 流程
37
-
38
- ### 1. 输入预检
39
-
40
- 1. 读取所有存在的上游工件;
41
- 2. 检查 `specdev/changes/{change}/spec.md` 的 `ready_for_tickets`;
42
- 3. 按 下方 `<artifact-contract>` 标签 处理 Spec、ADR、用户决定与代码事实的冲突;
43
- 4. 将未知项分类为可发现事实、高影响用户决定和低影响实现细节;
44
- 5. 高影响未决问题没有关闭时停止,不通过更详细的 Ticket 文字伪装决策完备。
45
-
46
- **完成标准**:拆分依据、权威顺序、合同范围与未决问题已明确。
47
-
48
- ### 2. 探索代码库与实现地形
49
-
50
- 如果尚未探索,进行只读探索:
51
-
52
- - 找到行为入口、稳定接口、测试接缝、数据流和错误路径;
53
- - 查找相邻或类似实现,优先复用项目现有模式;
54
- - 识别可能修改的模块、公共路径、共享文件、迁移索引和全局注册点;
55
- - 查找现有测试命令、夹具、类型检查、构建和 CI 门禁;
56
- - 对照 `specdev/changes/{change}/CONTEXT.md` 使用项目领域词汇;
57
- - 对照 `specdev/changes/{change}/ADR.md` 与 `specdev/adr/` 避免重新争论已接受决策。
58
-
59
- 遇到不熟悉的模块、外部依赖或第三方库时,使用 下方 `<research>` 标签,再继续拆分。
60
-
61
- #### 项目 Skill 路由
62
-
63
- 1. 读取项目 Agent 指令,确定项目声明的 Skill 根;至少枚举 `.agents/skills/**/SKILL.md`,存在其他项目级 Skill 根时一并枚举;
64
- 2. 先读取候选 Skill 的 frontmatter 与入口路由;存在 `.agents/skills/engineering-standards/SKILL.md` 时完整读取,并按其 Skill Map 路由到当前 change 需要的领域 Skill;
65
- 3. 根据整个 change 和每个 Ticket 的路径、技术域、公共契约、迁移与验证范围,确定 `ALL` 或具体 Ticket 的最低必读集合;只把真实存在且触发条件匹配的项目 Skill 纳入;
66
- 4. 使用项目根相对 Path 记录每个 Skill 的入口文件,同时记录触发 scope、读取时机和用途;不得把 Speculo 自带 Skill 或机器绝对路径伪装成项目 Skill;
67
- 5. 未发现适用项目 Skill 时,记录已扫描的 Skill 根和“无适用项”,不生成虚假路径;项目 Skill 清单是最低集合而非 allowlist。
68
-
69
- #### Prefactor
70
-
71
- 遵循“让变更变容易,然后做容易的变更”:
72
-
73
- - 如果当前接口、依赖或接缝会使后续实现明显不安全或重复,提出前置 prefactor Ticket;
74
- - prefactor 必须说明它解除的具体阻碍;
75
- - prefactor 必须独立有价值且可验证;
76
- - 不为了“更干净”而创建与目标无关的重构 Ticket。
77
-
78
- **完成标准**:实现地形、稳定接缝、共享路径、必要 prefactor 与逐 Ticket 项目 Skill 路由已识别。
79
-
80
- ### 3. 草拟曳光弹式垂直切片
81
-
82
- 加载 下方 `<decomposition-rules>` 标签。每个切片应横向穿过交付该行为所需的最小层次组合,而不是把数据库、后端、前端和测试拆成互相无价值的水平 Ticket。
83
-
84
- 每个 Ticket 必须:
85
-
86
- - 交付一个可观察行为,或一个能独立解除后续阻塞的安全准备能力;
87
- - 完成后可以独立演示、测试或验证;
88
- - 适合一个全新 Agent 上下文在不中断的情况下完成;
89
- - 与其他 Ticket 有实质行为差异;
90
- - 只依赖真正阻止它开始的前置产物;
91
- - 自带至少一种完成证据。
92
-
93
- #### 宽重构例外
94
-
95
- 字段重命名、共享符号类型变化、协议升级等宽机械变更无法安全塞入单个垂直切片时,按以下顺序:
96
-
97
- 1. **Expand**:在旧形式旁增加新形式,保持旧调用方可工作;
98
- 2. **Migrate batches**:按包、目录、消费者或风险分批迁移,每批独立成 Ticket;
99
- 3. **Contract**:确认旧调用点为零后删除旧形式;
100
- 4. 若迁移批次无法各自保持绿色,使用隔离集成分支和最终集成验证 Gate,但仍保留明确的批次与责任边界。
101
-
102
- **完成标准**:每个 Ticket 的可观察产出、真实阻塞边和验证方式已草拟。
103
-
104
- ### 4. 判定规划深度与风险
105
-
106
- 按 下方 `<readiness-and-depth>` 标签 为每个 Ticket 标注:
107
-
108
- - `lite`:局部、可逆、沿用既有模式、无公共契约或迁移影响;
109
- - `standard`:大多数多文件或跨层垂直切片;
110
- - `deep`:公共 API/schema、数据迁移、安全/隐私/资金、不可逆操作、expand-contract、共享核心路径、多个 implementation owner 的跨 Ticket 写入协调或高事故半径。
111
-
112
- 规划深度不是优先级,也不是 Gate。每个 Ticket 必须记录触发该深度的原因。
113
-
114
- ### 5. 写成决策完备 Ticket
115
-
116
- 使用 下方 `<ticket-template>` 标签 填写:
117
-
118
- - 战略目标、可观察产出与来源追踪;
119
- - 当前代码事实和需求差距;
120
- - 已锁定决策、低影响假设和未决问题;
121
- - IN / REUSE / OUT;
122
- - 用户或调用者视角的端到端行为;
123
- - Standard/Deep 的接口、输入输出、不变量、数据流、失败与兼容契约;
124
- - 有序执行路线和安全落点;
125
- - expected、writable、read-only、shared 路径;
126
- - 正常、失败和回归验证矩阵;
127
- - 每个 Ticket 按 Goal Plan 的 workspace 策略定义 current-workspace/direct-parent 或 source-worktree/parent-candidate 检查,以及按实际跨边界风险判定的 E2E disposition;
128
- - 每个实现 Ticket 的 implementation commit 与对应父分支完成条件;仅 required 模式创建独立 worktree;
129
- - Deep 的迁移、兼容窗口、监控、回滚和不可逆批准点;
130
- - 可判定验收标准。
131
-
132
- 路径所有权必须遵守 下方 `<path-ownership>` 标签,证据设计必须遵守 下方 `<evidence-and-verification>` 标签。
133
-
134
- ### 6. 构建依赖 DAG、合同覆盖与并发检查
135
-
136
- 1. 使用 Ticket ID 建立 `blocked_by`;
137
- 2. 检测循环和不存在的引用;
138
- 3. 识别根 Ticket、汇合点、扇出与收缩点;
139
- 4. 为每个 Spec 验收合同映射至少一个 Ticket;
140
- 5. 检查并行候选的 `writable_paths` 是否相交;
141
- 6. 共享路径必须指定唯一 owner,通常由专门 Ticket 或明确的集成 owner 修改;
142
- 7. 不得用依赖边表达“可能更方便”或纯粹的人员交接。
143
-
144
- 使用 下方 `<tickets-map-template>` 标签 草拟总体 Map;写入所有 Ticket 共享的总体实施背景与项目 Skill 读取矩阵。矩阵中的每个 Ticket 必须由 `ALL` 或自己的 Ticket ID 覆盖。
145
-
146
- ### 7. Definition of Ready
147
-
148
- 加载 下方 `<ticket-readiness>` 标签 逐个检查。
149
-
150
- 存在以下任一情况时 `ready: false`:
151
-
152
- - 会改变行为、接口、数据、兼容、安全、范围或验收的未决问题;
153
- - 依赖缺失或 DAG 有环;
154
- - 可写路径不明确或并行所有权冲突;
155
- - 验证方法不能执行且没有批准的替代证据;
156
- - Ticket 未声明 E2E required/not-required 及理由,或在 required 模式把 E2E 安排到 source worktree;
157
- - Tickets Map 缺少总体实施背景或项目 Skill 读取矩阵,项目 Skill 路径不存在、不是项目根相对路径,或当前 Ticket 未被 `ALL`/自身 ID 覆盖;
158
- - 无法形成实现 commit 与 Goal Plan 所选 direct-parent/candidate-merge 父分支出口;
159
- - 单个新上下文无法完成;
160
- - Standard/Deep 缺少有序执行路线;
161
- - Deep 缺少迁移、兼容、监控、回滚或批准点。
162
-
163
- ### 8. 与用户核对
164
-
165
- 以完整编号列表展示所有 Ticket,至少包含:
166
-
167
- - 标题;
168
- - 可观察交付;
169
- - 被阻塞于;
170
- - Planning Depth 与触发原因;
171
- - 风险;
172
- - Ready 状态;
173
- - 关键未决问题;
174
- - 预计并行组和共享路径 owner;
175
- - `ALL` 与逐 Ticket 的项目 Skill 最低必读集合。
176
-
177
- 核对:
17
+ > 激活后读取 SpecDev 的激活合同。
178
18
 
179
- - 粒度是否适合单一上下文;
180
- - 是否出现水平切片;
181
- - 阻塞边是否真实;
182
- - 是否应合并、进一步拆分或增加 prefactor;
183
- - 合同是否全部覆盖;
184
- - 路径所有权和验证是否可信。
185
-
186
- 每次修改后重新展示完整列表,直到用户批准。用户明确要求一次性自主规划且不存在高影响未知项时,可使用推荐默认值并把假设写入 Ticket,不为形式重复询问。
187
-
188
- ### 9. 发布
189
-
190
- 创建:
191
-
192
- - Ticket 目录:`specdev/changes/{change}/ticket/`
193
- - Tickets Map:`specdev/changes/{change}/tickets-map.md`
194
- - Evidence 目录:`specdev/changes/{change}/evidence/`
19
+ 每张票都是供新上下文执行的 Plan:说明背景、来源、目标、非目标、真实项目 SKILL 调用、修改顺序、验证和失败停止点。Tickets Map 是统一启动与恢复入口,不是静态清单;它不复制 Ticket 的状态权威。
195
20
 
196
- 按拓扑顺序写入 Ticket:
197
-
198
- ```text
199
- specdev/changes/{change}/ticket/NN-<ticket-name>.md
200
- ```
201
-
202
- `NN` 使用两位或更多位零填充数字;Ticket frontmatter ID 使用 `T-NN`。Ticket 的 `blocked_by` 使用 Ticket ID,而不是相对文件路径。
21
+ ## 读取范围
203
22
 
204
- 使用 下方 `<ticket-template>` 标签 下方 `<tickets-map-template>` 标签 生成工件,并对照:
23
+ 先读 下方 `<activation-and-memory>` 标签;按相关条目定位上游 Spec/ADR/CONTEXT、代码与项目 Agent 指令,再回读当前拆分所需原文。只枚举 Skill 的元数据与触发路由,不默认展开全部技能。
205
24
 
206
- - 下方 `<ticket-schema>` 标签
207
- - 下方 `<tickets-map-schema>` 标签
25
+ ## 主流程
208
26
 
209
- 运行:
27
+ 1. **输入与范围**:确认目标、非目标、用户指定数量、验收合同和未知项。高影响未决问题回到 G;无 Ready Spec 时,只有用户材料已等价覆盖全部合同才可规划。
28
+ 2. **地形与绑定**:定位真实可维护源、调用方、测试接缝和 Skill 根。按 下方 `<ref-common-rules-skill-invocation>` 标签 为每票解析实际 Skill ID、入口摘要、调用阶段、输入、产出与失败动作;没有适用项目 Skill 时记录扫描证据,不造名称。
29
+ 3. **垂直切片**:需要具体拆分时读取 下方 `<ref-t-tickets-references-planning-procedure>` 标签 与 下方 `<decomposition-rules>` 标签。保留 Prefactor、Expand → Migrate → Contract 和真实 DAG,不按技术层制造空价值任务。
30
+ 4. **写 Plan**:使用 下方 `<ticket-template>` 标签。Lite 仅减少不适用说明,不删用户数量、权限、验收或停止条件。所有新增票使用 `plan_contract_version: 1`,旧票按迁移协议补齐后再执行。
31
+ 5. **写总控**:使用 下方 `<tickets-map-template>` 标签,记录共同背景、Skill 最低路由、合同覆盖、依赖和明确控制入口;状态仍从票投影。依赖、路径与语义共享资源都需检查。
32
+ 6. **Definition of Ready**:读取 下方 `<ticket-readiness>` 标签,并调用 下方 `<ref-common-skills-plan-quality-review-skill>` 标签。缺失引用、必需 Skill、可运行验收或权限边界,当前票不可 ready。
33
+ 7. **与用户核对**:展示全部票、可观察产物、依赖、深度、风险、Skill 和未决问题。保留用户要求的交付数量;已授权自主规划且无关键未知时不重复请求形式确认。
34
+ 8. **验证、回读和交付**:按下述命令检查,再回读真实 Ticket/Map,报告修改、验证结果和未完成项。规划完成不自动进入实现。
210
35
 
211
36
  ```bash
212
- node Speculo Node 校验器 \
213
- --stage tickets \
214
- --repo <project-root> \
215
- specdev/changes/{change}
37
+ node Speculo Node 校验器 --stage tickets --repo <project-root> specdev/changes/{change}
38
+ node 本地只读 Goal 控制器(不含于网页快照) --map specdev/changes/{change}/tickets-map.md --repo <project-root>
216
39
  ```
217
40
 
218
- 更新 `specdev/status.json` `specdev/changes/{change}/.status.json`。
219
-
220
- ## 完成标准
221
-
222
- - Ticket 目录和 Map 已写入本文约定的位置;
223
- - Spec 合同全部 covered 或有明确批准的 deferred;
224
- - DAG 无环、阻塞引用存在;
225
- - Ready Ticket 无高影响未知项;
226
- - 并行 Ticket 无未解决的可写冲突;
227
- - 每个 Ticket 可独立验证且适配单一上下文;
228
- - Tickets Map 已记录总体实施背景;每个 Ticket 被项目 Skill 读取矩阵覆盖,Skill 路径存在且为项目根相对路径;
229
- - Prefactor 与 expand-contract 使用条件正确;
230
- - 用户已批准拆分或明确授权自主发布;
231
- - 校验器无 error。
232
-
233
- ## 子文件引用
234
-
235
- - 拆分规则:下方 `<decomposition-rules>` 标签
236
- - Ticket 就绪规则:下方 `<ticket-readiness>` 标签
237
- - Ticket 模板:下方 `<ticket-template>` 标签
238
- - Tickets Map 模板:下方 `<tickets-map-template>` 标签
239
-
240
- ## 下一步
241
-
242
- 满足任一情况时建议运行 “目标规划阶段”:Ticket 数量达到或超过 10、存在多个 implementation owner 的并行写入协调、Deep Ticket、迁移、共享契约、多个 Gate 或高风险发布。只读 review/research 并行本身不触发 Goal Plan;少量线性 Ready Ticket 可直接进入 “实现阶段”。
41
+ 需要正式 Goal、多 change、迁移或跨票 Gate 时交给 “目标规划阶段”;少量线性票可从 map 按已授权范围调用 “实现阶段”。不得以“精简”为理由静默更换默认工具或少交付。
243
42
 
244
43
  ---
245
44
 
@@ -371,6 +170,10 @@ status: ready
371
170
 
372
171
  ```yaml
373
172
  schema_version: 3
173
+ plan_contract_version: 1
174
+ skill_scan: unreviewed
175
+ skill_bindings: []
176
+ resource_claims: []
374
177
  artifact: ticket
375
178
  change: <YYYY-MM-DD-topic>
376
179
  id: T-01
@@ -397,7 +200,7 @@ shared_path_owners: []
397
200
  - **上游 Spec:** `specdev/changes/{change}/spec.md`
398
201
  - **完成 Evidence:** `specdev/changes/{change}/evidence/T-01.md`
399
202
 
400
- 实现本 Ticket 时,Lead 与 implementation subagent 必须按顺序完整读取总体 Map、其中适用于 `ALL`/`T-01` 的项目 Skill,再读取本 Ticket 与其他上游工件。Map 中的 Skill 是最低必读集合;新的匹配项先由 Lead 同步到 Map 并重新校验。
203
+ 实现本 Ticket 时,Lead 与 implementation subagent 必须按顺序完整读取总体 Map,读取项目 Skill 的 frontmatter 与入口并只展开适用于 `ALL`/`T-01` 的匹配项,再读取本 Ticket 与相关上游工件。Map 中的 Skill 是最低必读集合;新的匹配项先由 Lead 同步到 Map 并重新校验。
401
204
 
402
205
  ## 1. 战略与来源
403
206
 
@@ -496,7 +299,7 @@ E2E 由实际跨边界行为与风险决定,不限于 UI;required 模式不
496
299
  ## 10. 验收标准
497
300
 
498
301
  - [ ] `AC-001`:<可判定结果>。
499
- - [ ] 实现开始前已完整读取 Tickets Map 及其中适用于 `ALL`/`T-01` 的项目 Skill;新发现的匹配 Skill 已由 Lead 同步回 Map。
302
+ - [ ] 实现开始前已完整读取 Tickets Map,已读取项目 Skill 入口并完整展开其中适用于 `ALL`/`T-01` 的匹配项;新发现的匹配 Skill 已由 Lead 同步回 Map。
500
303
  - [ ] 验证矩阵全部执行并记录到 `specdev/changes/{change}/evidence/T-01.md`。
501
304
  - [ ] 实际项目修改未超出 `writable_paths`,shared path 由指定 owner 修改。
502
305
  - [ ] Ticket 已按 Goal Plan 策略形成非空 implementation/source commit,direct-parent 或 candidate 验证通过且父分支 result 已记录。
@@ -504,6 +307,18 @@ E2E 由实际跨边界行为与风险决定,不限于 UI;required 模式不
504
307
  - [ ] 未发生未批准的范围、契约或发布偏差。
505
308
  - [ ] Ticket、Tickets Map 和 Evidence 状态一致。
506
309
 
310
+ ## 11. SKILL 调用计划
311
+
312
+ 依据 下方 `<ref-common-rules-skill-invocation>` 标签 填写 frontmatter 绑定;正文解释每项调用为什么属于本票、具体何时调用、输入定位、输出如何用于下一步。不是仅给出技能名称或阅读列表。没有适用项目 Skill 时写明真实扫描证据;不要保留 unreviewed。
313
+
314
+ ## 12. 停止、检查点与交付
315
+
316
+ - **用户交付要求与数量:** 与 Map 的 requested_deliverables 对齐;不为压缩而减少。
317
+ - **必需 Skill/引用/测试不可用:** 阻塞本票,报告缺口,不静默替换默认工具。
318
+ - **归属与资源冲突:** 暂停本票和受影响下游,不接管他人状态;独立票由 map 继续。
319
+ - **检查点:** 记录源版本、绑定摘要、已完成步骤、Evidence 和未闭合动作;恢复前回读。
320
+ - **完成出口:** 全部适用验收及实际 Skill 证据通过,再将结果交回 Goal;未完成项明确列出。
321
+
507
322
  </ticket-template>
508
323
 
509
324
  <tickets-map-template>
@@ -514,6 +329,10 @@ E2E 由实际跨边界行为与风险决定,不限于 UI;required 模式不
514
329
 
515
330
  ```yaml
516
331
  schema_version: 3
332
+ plan_contract_version: 1
333
+ plan_revision: 1
334
+ requested_deliverables: []
335
+ deliverable_policy: unreviewed
517
336
  artifact: tickets-map
518
337
  change: <YYYY-MM-DD-topic>
519
338
  status: draft
@@ -537,7 +356,7 @@ status: draft
537
356
 
538
357
  ### 项目 Skill 读取矩阵
539
358
 
540
- 每个 Ticket 的 Lead 或 implementation subagent 都必须先完整读取本 Map,再读取下表中适用于 `ALL` 或当前 Ticket ID 的项目 Skill,最后进入当前 Ticket。下表是发布时已确认的**最低必读集合,不是 Skill allowlist**;项目 Agent 指令或实现范围触发其他项目 Skill 时,先读取该 Skill,并由 Lead 更新本 Map、重新校验后继续。
359
+ 每个 Ticket 的 Lead 或 implementation subagent 都必须先完整读取本 Map,再读取候选项目 Skill 的 frontmatter 与入口;只有适用于 `ALL` 或当前 Ticket ID、且 scope/路径/技术域/验证条件命中的 Skill 才完整读取,最后进入当前 Ticket。下表是发布时已确认的**最低必读集合,不是 Skill allowlist**;项目 Agent 指令或实现范围触发其他项目 Skill 时,先定位并读取其入口,由 Lead 更新本 Map、重新校验后继续。
541
360
 
542
361
  项目 Skill 使用项目根相对 Path,例如 `.agents/skills/{skill-name}/SKILL.md`;不得写机器绝对路径。若没有适用项目 Skill,保留一行 `无(已扫描项目 Skill 入口,未发现适用项)`,并在 Trigger / Scope 中记录实际扫描范围。
543
362
 
@@ -601,6 +420,16 @@ T-tickets 可以标注候选 Wave、E2E disposition 和行为里程碑。需要
601
420
  - 依赖、合同覆盖或路径所有权变化后运行 Speculo Node 校验器;
602
421
  - 内部工件使用本文约定的逻辑路径,不用 Markdown 链接充当状态引用。
603
422
 
423
+ ## 9. 总控与恢复
424
+
425
+ 从本 Map 进入 “目标规划阶段” 的 plan/run/resume/replan/verify。先运行 本地只读 Goal 控制器(不含于网页快照) 的 `--map` 只读检查,再按 下方 `<ref-p-goal-plan-references-map-control>` 标签 调用 I 和真实 Skill、验收、更新状态直到完成或明确阻塞;此工具本身不执行代码。
426
+
427
+ - frontmatter 中 requested_deliverables 用 JSON 对象数组记录用户明确要求的名称与正整数 count;没有额外数量要求时用空数组,并在 deliverable_policy 记录依据,不能保留 unreviewed。
428
+ - requested_deliverables 属于用户交付合同;done 之前按实际产物核对,不从 Ticket 数量推断交付数量。
429
+ - 变更范围或验收后递增 plan_revision 并重算受影响闭包;原完成证据保留,失效证据不得复用。
430
+ - 共享语义资源在 Ticket resource_claims 声明(例如 API、表、迁移序列、正式记忆写集);不把“不同文件”视为互不冲突。
431
+ - 未闭合事务先查原网关,其他任务冲突只暂停相关部分;全部票 done 后仍需整体 Gate、数量和集成验收。
432
+
604
433
  </tickets-map-template>
605
434
 
606
435
  <planning-principles>
@@ -684,7 +513,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
684
513
  | Change 架构决策 | `specdev/changes/{change}/ADR.md` | 已成为本 change 下游合同的架构决策、原因、后果和替代关系 | 永久项目 ADR 或尚未决定的方案集合 |
685
514
  | Spec | `specdev/changes/{change}/spec.md` | 用户问题、外部行为、范围、验收合同、非功能要求和已锁定实现约束 | 文件级施工步骤 |
686
515
  | Ticket | `specdev/changes/{change}/ticket/NN-<ticket-name>.md` | 单一垂直切片的行为、决策、范围、路径所有权、执行路线和验证证据 | 跨 Ticket 里程碑治理 |
687
- | Tickets Map | `specdev/changes/{change}/tickets-map.md` | 总体实施背景、项目 Skill 最低读取路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
516
+ | Tickets Map | `specdev/changes/{change}/tickets-map.md` | 总体实施背景、项目 Skill 最低调用路由、依赖 DAG、合同覆盖、Ready 投影、并行候选和路径冲突 | 单 Ticket 的完整实现契约 |
688
517
  | Goal Plan | `specdev/changes/{change}/goal-plan.md` | 跨 Ticket 调度、Gate、共享所有权、迁移顺序、集成和偏差治理 | 复制 Ticket 全文 |
689
518
  | Implementation Map | `specdev/changes/{change}/implementation-map.md` | Ready 成员、组合 Ticket inventory、跨 change dependency/serialization 与 revision | 创建或改写子 Spec、Ticket 或实现细节 |
690
519
  | Implementation Plan | `specdev/changes/{change}/implementation-plan.md` | 父 Lead、全局 workspace/实现上限、frontier/Wave/locks/integration queue 和可恢复进度投影 | 改写子 change 权威或伪造完成 |
@@ -697,7 +526,7 @@ SpecDev 通过分层工件避免同一决策被多个模型反复重做。每个
697
526
  | Wayfinder 地图 | `specdev/changes/{change}/wayfinder-map.md` | 目的地、说明、已关闭决策索引、战争迷雾和范围之外 | 开放 Ticket 正文或答案详情 |
698
527
  | Wayfinder Ticket | `specdev/changes/{change}/investigation/{investigation-id}.md` | 一个可精确陈述的问题、类型、阻塞和关闭状态 | 解决方案评论或交付目标 |
699
528
  | Wayfinder solution comment | `specdev/changes/{change}/investigation/comments/{investigation-id}/NN-solution.md` | Ticket 的答案、结果事实和资产指针 | 地图索引或产品实现 |
700
- | 架构审查 | `specdev/changes/{change}/architecture-review.md` `specdev/changes/{change}/architecture-review.html` | 深化候选、证据、可视化、选择和访谈状态 | 未经用户选择的执行契约 |
529
+ | 架构审查 | `specdev/changes/{change}/architecture-review.md` | 结构性候选、code-judo 机会、证据、选择和访谈状态 | 未经用户选择的执行契约 |
701
530
 
702
531
  UI 设计包中的 `{design-id}` 由 P-prototype 分配为当前 change 内最小未占用的 `UI-NNN`;设计系统文档是唯一设计权威,comparison 与 final 不建立第二套规则。
703
532
 
@@ -748,6 +577,14 @@ Change CONTEXT/ADR 是 active change 内的执行权威,不是 workflow 级永
748
577
 
749
578
  不得仅在下游工件中覆盖上游权威。
750
579
 
580
+ ## 5. Initiative 与计划调用扩展
581
+
582
+ W 的 `specdev/changes/{change}/initiative.json` 只拥有候选 change 的边界、未知、依赖和目标指针;每个物化 child 的 Grill、Spec、Ticket 和状态仍独立。候选图不是实施 DAG,也不是共享可写设计树。
583
+
584
+ 新 Ticket/普通 Map 保持原 schema_version,并使用 plan_contract_version: 1 扩展。Ticket 拥有经过核实的 Skill 调用绑定、语义资源和执行计划;Map 路由是其投影。规则为 下方 `<ref-common-rules-skill-invocation>` 标签。计划、产物数量与完成证据漂移必须由对应 owner 修订;不能仅改 map 状态。
585
+
586
+ 父 `specdev/changes/{change}/tickets-map.md` 是 goal-tickets-map 无状态入口,只引用现有 Implementation Map/Plan;它不能拥有第二份 status、owner 或任务清单。统一 P 拥有生命周期,旧 O 仅保留入口与恢复键。
587
+
751
588
  </artifact-contract>
752
589
 
753
590
  <readiness-and-depth>
@@ -958,7 +795,7 @@ Direct Spec Evidence 至少包含:用户批准与轻量合同、Lead、实施
958
795
 
959
796
  # Parent Implementation Orchestration
960
797
 
961
- 本规则只约束 Ready Spec/Tickets 之后的跨 change 实现,供 O-orchestrate-implementation、I-implement 与 A-archive-and-consolidate 读取。
798
+ 本规则只约束 Ready Spec/Tickets 之后的跨 change 实现,供统一 P-goal-plan、兼容 P-goal-plan、I-implement 与 A-archive-and-consolidate 读取。
962
799
 
963
800
  ## 输入边界
964
801
 
@@ -978,12 +815,16 @@ Direct Spec Evidence 至少包含:用户批准与轻量合同、Lead、实施
978
815
 
979
816
  ## I-implement 调用
980
817
 
981
- 父 Plan 可以替代缺失的子 Goal Plan 提供 workspace/integration 策略和全局执行边界。子 Goal Plan 存在时继续拥有子 change 内 Gate,但不得与父策略冲突。I-implement 完成或阻塞一个组合 Ticket 后返回父 O Work,不要求用户重新激活 change。
818
+ 父 Plan 可以替代缺失的子 Goal Plan 提供 workspace/integration 策略和全局执行边界。子 Goal Plan 存在时继续拥有子 change 内 Gate,但不得与父策略冲突。I-implement 完成或阻塞一个组合 Ticket 后返回父 P Goal(旧 O 入口保留恢复键),不要求用户重新激活 change。
982
819
 
983
820
  ## 归档与完成
984
821
 
985
822
  未完成父实现 change 的成员不得归档。成员满足普通 change completion 时可以先 completed,但不自动归档。父 change 只有全部成员 completed、Map/Plan completed、aggregate Evidence 完整且无 active dispatch/candidate/lock 后才能 completed;完成或归档均不自动级联。
986
823
 
824
+ ## 局部阻塞不升级为全局停机
825
+
826
+ 父创建前仍全部成员预检且 all-or-nothing。父开始运行后,单票 blocked/deviated、他人资源冲突或必需 Skill 失效只阻塞该票及其依赖闭包,父 Map/Plan 可保持 in_progress 与有效的全局执行门,继续独立已授权 frontier。只有共享的全局门禁失败、计划整体失效或没有合法 frontier 时,才将父运行暂停;不得为继续运行接管其他任务。
827
+
987
828
  </parent-implementation-orchestration>
988
829
 
989
830
  <research>
@@ -1744,41 +1585,636 @@ implementation owner 只在来源 worktree 修改授权项目路径,运行 Tic
1744
1585
  "pattern": "^(?!/)(?![A-Za-z]:).+\\s*=>\\s*[^=].+$"
1745
1586
  },
1746
1587
  "uniqueItems": true
1747
- }
1748
- },
1749
- "$defs": {
1750
- "pathArray": {
1588
+ },
1589
+ "plan_contract_version": {
1590
+ "const": 1
1591
+ },
1592
+ "skill_scan": {
1593
+ "type": "string",
1594
+ "minLength": 1
1595
+ },
1596
+ "skill_bindings": {
1751
1597
  "type": "array",
1752
1598
  "items": {
1753
- "type": "string",
1754
- "pattern": "^(?!/)(?![A-Za-z]:).+$"
1755
- },
1756
- "uniqueItems": true
1757
- }
1758
- },
1759
- "additionalProperties": true
1760
- }
1761
- ```
1762
-
1763
- </ticket-schema>
1764
-
1765
- <tickets-map-schema>
1766
-
1767
- ```json
1768
- {
1769
- "$schema": "https://json-schema.org/draft/2020-12/schema",
1770
- "$id": "urn:speculo:specdev:tickets-map:v3",
1771
- "title": "SpecDev Tickets Map Frontmatter",
1599
+ "type": "object",
1600
+ "required": [
1601
+ "id",
1602
+ "path",
1603
+ "sha256",
1604
+ "phase",
1605
+ "operation",
1606
+ "inputs",
1607
+ "outputs",
1608
+ "required",
1609
+ "on_failure"
1610
+ ],
1611
+ "properties": {
1612
+ "id": {
1613
+ "type": "string",
1614
+ "minLength": 1
1615
+ },
1616
+ "path": {
1617
+ "type": "string",
1618
+ "pattern": "^[^<]+/SKILL\\.md$"
1619
+ },
1620
+ "sha256": {
1621
+ "type": "string",
1622
+ "pattern": "^[a-f0-9]{64}$"
1623
+ },
1624
+ "phase": {
1625
+ "enum": [
1626
+ "plan",
1627
+ "implement",
1628
+ "verify"
1629
+ ]
1630
+ },
1631
+ "operation": {
1632
+ "type": "string",
1633
+ "minLength": 1
1634
+ },
1635
+ "inputs": {
1636
+ "type": "array",
1637
+ "minItems": 1,
1638
+ "items": {
1639
+ "type": "string",
1640
+ "minLength": 1
1641
+ }
1642
+ },
1643
+ "outputs": {
1644
+ "type": "array",
1645
+ "minItems": 1,
1646
+ "items": {
1647
+ "type": "string",
1648
+ "minLength": 1
1649
+ }
1650
+ },
1651
+ "required": {
1652
+ "type": "boolean"
1653
+ },
1654
+ "on_failure": {
1655
+ "enum": [
1656
+ "block-ticket",
1657
+ "report-and-continue"
1658
+ ]
1659
+ },
1660
+ "condition": {
1661
+ "type": "string",
1662
+ "minLength": 1
1663
+ },
1664
+ "references": {
1665
+ "type": "array",
1666
+ "items": {
1667
+ "type": "object",
1668
+ "required": [
1669
+ "path",
1670
+ "sha256",
1671
+ "when"
1672
+ ],
1673
+ "properties": {
1674
+ "path": {
1675
+ "type": "string",
1676
+ "pattern": "^(?!/)(?![A-Za-z]:).+$"
1677
+ },
1678
+ "sha256": {
1679
+ "type": "string",
1680
+ "pattern": "^[a-f0-9]{64}$"
1681
+ },
1682
+ "when": {
1683
+ "type": "string",
1684
+ "minLength": 1
1685
+ }
1686
+ },
1687
+ "additionalProperties": false
1688
+ }
1689
+ }
1690
+ },
1691
+ "allOf": [
1692
+ {
1693
+ "if": {
1694
+ "properties": {
1695
+ "required": {
1696
+ "const": true
1697
+ }
1698
+ },
1699
+ "required": [
1700
+ "required"
1701
+ ]
1702
+ },
1703
+ "then": {
1704
+ "properties": {
1705
+ "on_failure": {
1706
+ "const": "block-ticket"
1707
+ }
1708
+ }
1709
+ }
1710
+ },
1711
+ {
1712
+ "if": {
1713
+ "properties": {
1714
+ "required": {
1715
+ "const": false
1716
+ }
1717
+ },
1718
+ "required": [
1719
+ "required"
1720
+ ]
1721
+ },
1722
+ "then": {
1723
+ "required": [
1724
+ "condition"
1725
+ ]
1726
+ }
1727
+ }
1728
+ ],
1729
+ "additionalProperties": false
1730
+ }
1731
+ },
1732
+ "resource_claims": {
1733
+ "type": "array",
1734
+ "items": {
1735
+ "type": "string",
1736
+ "minLength": 1
1737
+ },
1738
+ "uniqueItems": true
1739
+ }
1740
+ },
1741
+ "$defs": {
1742
+ "pathArray": {
1743
+ "type": "array",
1744
+ "items": {
1745
+ "type": "string",
1746
+ "pattern": "^(?!/)(?![A-Za-z]:).+$"
1747
+ },
1748
+ "uniqueItems": true
1749
+ }
1750
+ },
1751
+ "additionalProperties": true,
1752
+ "allOf": [
1753
+ {
1754
+ "if": {
1755
+ "required": [
1756
+ "plan_contract_version"
1757
+ ]
1758
+ },
1759
+ "then": {
1760
+ "required": [
1761
+ "skill_scan",
1762
+ "skill_bindings",
1763
+ "resource_claims"
1764
+ ]
1765
+ }
1766
+ }
1767
+ ]
1768
+ }
1769
+ ```
1770
+
1771
+ </ticket-schema>
1772
+
1773
+ <tickets-map-schema>
1774
+
1775
+ ```json
1776
+ {
1777
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
1778
+ "$id": "urn:speculo:specdev:tickets-map:v3",
1779
+ "title": "SpecDev Tickets Map Frontmatter",
1772
1780
  "type": "object",
1773
- "required": ["schema_version", "artifact", "change", "status"],
1781
+ "required": [
1782
+ "schema_version",
1783
+ "artifact",
1784
+ "change",
1785
+ "status"
1786
+ ],
1774
1787
  "properties": {
1775
- "schema_version": {"const": 3},
1776
- "artifact": {"const": "tickets-map"},
1777
- "change": {"type": "string", "minLength": 1},
1778
- "status": {"enum": ["draft", "ready", "in_progress", "completed", "blocked"]}
1788
+ "schema_version": {
1789
+ "const": 3
1790
+ },
1791
+ "artifact": {
1792
+ "const": "tickets-map"
1793
+ },
1794
+ "change": {
1795
+ "type": "string",
1796
+ "minLength": 1
1797
+ },
1798
+ "status": {
1799
+ "enum": [
1800
+ "draft",
1801
+ "ready",
1802
+ "in_progress",
1803
+ "completed",
1804
+ "blocked"
1805
+ ]
1806
+ },
1807
+ "plan_contract_version": {
1808
+ "const": 1
1809
+ },
1810
+ "plan_revision": {
1811
+ "type": "integer",
1812
+ "minimum": 1
1813
+ },
1814
+ "requested_deliverables": {
1815
+ "type": "array",
1816
+ "items": {
1817
+ "type": "object",
1818
+ "required": [
1819
+ "name",
1820
+ "count"
1821
+ ],
1822
+ "properties": {
1823
+ "name": {
1824
+ "type": "string",
1825
+ "minLength": 1
1826
+ },
1827
+ "count": {
1828
+ "type": "integer",
1829
+ "minimum": 1
1830
+ }
1831
+ },
1832
+ "additionalProperties": false
1833
+ }
1834
+ },
1835
+ "deliverable_policy": {
1836
+ "type": "string",
1837
+ "minLength": 1
1838
+ }
1779
1839
  },
1780
- "additionalProperties": true
1840
+ "additionalProperties": true,
1841
+ "allOf": [
1842
+ {
1843
+ "if": {
1844
+ "required": [
1845
+ "plan_contract_version"
1846
+ ]
1847
+ },
1848
+ "then": {
1849
+ "required": [
1850
+ "plan_revision",
1851
+ "requested_deliverables",
1852
+ "deliverable_policy"
1853
+ ]
1854
+ }
1855
+ }
1856
+ ]
1781
1857
  }
1782
1858
  ```
1783
1859
 
1784
1860
  </tickets-map-schema>
1861
+
1862
+ <activation-and-memory>
1863
+
1864
+ # Activation and memory retrieval protocol
1865
+
1866
+ 本规则只在用户明确激活当前 workflow 或某个 Work 后读取。INDEX 只用于被动发现,不初始化状态、不读取 active change、不写入知识。
1867
+
1868
+ ## Locate before read
1869
+
1870
+ 1. 先解析当前 workflow 的 roots、状态索引和稳定 ID;不存在时静默跳过,不能凭旧路径猜测。
1871
+ 2. 根据当前请求、Work 分支、关键词、稳定 ID、状态和 provenance,先搜索相关索引行或目录项,再定位最小相关 entry;不把索引全文默认装入上下文。
1872
+ 3. 只回读命中的 entry 和直接 provenance;需要恢复、冲突裁决、归档、迁移或执行安全证明时,才读取该阶段声明的完整证据集合。
1873
+ 4. 没有匹配证据时返回缺失证据并停止依赖该结论的分支,不补造事实。
1874
+
1875
+ ## Memory writes
1876
+
1877
+ 正式知识、永久 context、synthesis 或 archive 写入前,先解析唯一 owner 与 gateway,检查 pending transaction、lock、未完成 promotion 和 recovery evidence。gateway 不明或事务未闭合时,只阻塞记忆写入,继续独立且已授权的审计、定位、验证和其他工作。
1878
+
1879
+ 每次写入必须记录 source IDs、证据定位、验证时间或 digest;写入后定位受影响索引项并重新读取目标 entry,确认 owner、locator、内容和状态投影一致。原始证据不可被派生视图覆盖。
1880
+
1881
+ ## Read budget
1882
+
1883
+ 当前 Work 的权威状态、schema、Map/Plan、当前输入和直接所有权合同可以完整读取;非当前分支的知识树、历史 change、研究库、项目 Skill 和示例只按索引与关键词读取。执行、冲突、恢复和归档 Work 需要完整证据时,以该 Work 的显式合同为准。
1884
+
1885
+ ## 事务与归属隔离
1886
+
1887
+ 启动正式写入前检查原网关未闭合事务与写集。属于本任务的事务按原恢复协议处理;属于其他任务的事务不得接管、解锁、清空或覆盖。只暂停资源重叠的写入与依赖分支,继续独立、已授权工作;事务年龄不构成接管授权。写后按变更 ID 定位受影响的索引项并回读目标原文,不为核验默认整读整库。
1888
+
1889
+ </activation-and-memory>
1890
+
1891
+ <ref-common-rules-skill-invocation>
1892
+
1893
+ # 可验证的 Skill 调用契约
1894
+
1895
+ 本规则用于 T 规划、P 调度和 I 执行。Map 维护最低读取路由;每票 `skill_bindings` 才定义本票调用,二者不得互相代替。
1896
+
1897
+ ## 定位与绑定
1898
+
1899
+ 1. 从项目 Agent 指令解析真实 Skill 根,先枚举元数据和触发条件,再读取命中入口及当前阶段要求的参考;不整读所有 Skills。
1900
+ 2. 保留逻辑路径、解析真实源,检查不存在的路径、越界软链接、缓存和入口 `name`。默认不使用插件缓存或 node_modules 充当项目可维护源;用户维护的项目内软链接保持原状。仓库外技能需要先取得明确源域授权并由项目网关处理,控制器不会自行扩大根目录。
1901
+ 3. 每个绑定必须包含真实 `id`(SKILL 的 name)、项目根相对路径 `path`、入口字节 `sha256`、`phase`(plan/implement/verify)、`operation`、非空 `inputs`、`outputs`、`required` 与 `on_failure`。引用较长参考时在 references 字段 中记录明确 Path、sha256 与 `when`;相关参考在调用前按条件回读。
1902
+ 4. 必需绑定失败固定为 `block-ticket`;可选绑定只有说明 `condition` 与不适用原因才允许 `report-and-continue`。可选标记不能覆盖用户要求或技能自身硬门禁。
1903
+ 5. 在模板 frontmatter 中,数组对象用单行 JSON;不使用自定义 YAML 对象语法。缺失 Skill、摘要漂移、占位符或入口 ID 不符,票不得进入 ready。没有适用项目 Skill 时 `skill_bindings: []`,`skill_scan` 必须写真实扫描范围与不适用理由,Map 同步无适用项。
1904
+
1905
+ ## 示例形状(生成真实票时全部替换)
1906
+
1907
+ ```json
1908
+ {"id":"project-test","path":".agents/skills/project-test/SKILL.md","sha256":"<真实64位摘要>","phase":"verify","operation":"run-regression","inputs":["当前Ticket与定向diff"],"outputs":["含命令、退出码和验收映射的Evidence"],"required":true,"on_failure":"block-ticket","references":[]}
1909
+ ```
1910
+
1911
+ 此示例不是项目已存在的 Skill,不得复制为可执行绑定。SpecDev 自带技能在 Work 中按明确 Path 调用,不能伪装为项目 Skill。
1912
+
1913
+ ## 执行证据
1914
+
1915
+ 到相应阶段后,实际调用宿主能力或执行该 Skill 明确的步骤。记录技能 ID、phase、operation、所用摘要、输入定位、执行轨迹、输出与结果。仅展示 `@skill`、复制入口、声明“已读”都不是完成证据。
1916
+
1917
+ 新版票 done 前,在本票 `specdev/changes/{change}/evidence/T-NN.md` 增加 `## Skill Execution Records`,紧接一个 JSON 数组代码块。每项有 `id`、`phase`、`operation`、`sha256`、`status`(passed/failed/skipped)、非空 `evidence` 字符串数组。required 项必须 passed;验证器只能检查记录结构与摘要一致,Lead 仍需回读真实工具/过程证据,不能把结构通过称为宿主调用已经被认证。
1918
+
1919
+ 摘要变更先由 Lead 检查影响、更新绑定和 map 后重验;不自动接受最新文件,不回写已完成旧证据。
1920
+
1921
+ </ref-common-rules-skill-invocation>
1922
+
1923
+ <ref-t-tickets-references-planning-procedure>
1924
+
1925
+ # 拆分 Tickets
1926
+
1927
+
1928
+ Ticket 是**决策完备的微型执行计划**:它消除执行者在目标、范围、公共契约、关键顺序和验收上的关键决策,但不展开逐行代码、局部变量或可从现有惯例自然推导的实现细节。
1929
+
1930
+ 本 work 保留原有能力:代码库探索、prefactor 识别、曳光弹垂直切片、真实阻塞边、用户粒度核对、宽重构的 expand-contract 排序、Ticket 独立文件和总体 Tickets Map。
1931
+
1932
+
1933
+ ## 输入
1934
+
1935
+ 优先读取:
1936
+
1937
+ - 当前 Spec:`specdev/changes/{change}/spec.md`
1938
+ - 当前架构决策:`specdev/changes/{change}/ADR.md`
1939
+ - 当前领域上下文:`specdev/changes/{change}/CONTEXT.md`
1940
+ - 当前设计日志:`specdev/changes/{change}/LOG.md`
1941
+ - Bug 诊断:`specdev/changes/{change}/diagnosis.md`
1942
+ - 永久架构决策:`specdev/adr/`
1943
+ - 永久领域上下文:`specdev/context/`
1944
+ - 项目 Agent 指令及其声明的项目 Skill 根;
1945
+ - 项目当前代码、测试、配置、schema 和 CI 事实。
1946
+
1947
+ 若尚无 `specdev/changes/{change}/spec.md`,只有在用户提供的计划或对话已经等价覆盖目标、范围、关键决定和可判定验收时才可继续;否则建议先运行 “编写 Spec 阶段”。
1948
+
1949
+ ## 流程
1950
+
1951
+ ### 1. 输入预检
1952
+
1953
+ 1. 先读取上游工件索引,按当前 Ticket 的依赖、缺口和冲突关键词定位,再回读相关工件;
1954
+ 2. 检查 `specdev/changes/{change}/spec.md` 的 `ready_for_tickets`;
1955
+ 3. 按 下方 `<artifact-contract>` 标签 处理 Spec、ADR、用户决定与代码事实的冲突;
1956
+ 4. 将未知项分类为可发现事实、高影响用户决定和低影响实现细节;
1957
+ 5. 高影响未决问题没有关闭时停止,不通过更详细的 Ticket 文字伪装决策完备。
1958
+
1959
+ **完成标准**:拆分依据、权威顺序、合同范围与未决问题已明确。
1960
+
1961
+ ### 2. 探索代码库与实现地形
1962
+
1963
+ 如果尚未探索,进行只读探索:
1964
+
1965
+ - 找到行为入口、稳定接口、测试接缝、数据流和错误路径;
1966
+ - 查找相邻或类似实现,优先复用项目现有模式;
1967
+ - 识别可能修改的模块、公共路径、共享文件、迁移索引和全局注册点;
1968
+ - 查找现有测试命令、夹具、类型检查、构建和 CI 门禁;
1969
+ - 对照 `specdev/changes/{change}/CONTEXT.md` 使用项目领域词汇;
1970
+ - 对照 `specdev/changes/{change}/ADR.md` 与 `specdev/adr/` 避免重新争论已接受决策。
1971
+
1972
+ 遇到不熟悉的模块、外部依赖或第三方库时,使用 下方 `<research>` 标签,再继续拆分。
1973
+
1974
+ #### 项目 Skill 路由
1975
+
1976
+ 1. 读取项目 Agent 指令,确定项目声明的 Skill 根;至少枚举 `.agents/skills/**/SKILL.md`,存在其他项目级 Skill 根时一并枚举;
1977
+ 2. 先读取候选 Skill 的 frontmatter 与入口路由;只有命中当前 change 的 scope、路径、技术域或验证条件时才完整读取,并按其 Skill Map 路由到当前 change 需要的领域 Skill;
1978
+ 3. 根据 change 索引、每个 Ticket 的 frontmatter、路径、技术域、公共契约、迁移与验证范围,确定 `ALL` 或具体 Ticket 的最低必读集合;只把真实存在且触发条件匹配的项目 Skill 纳入;
1979
+ 4. 使用项目根相对 Path 记录每个 Skill 的入口文件,同时记录触发 scope、读取时机和用途;不得把 Speculo 自带 Skill 或机器绝对路径伪装成项目 Skill;
1980
+ 5. 未发现适用项目 Skill 时,记录已扫描的 Skill 根和“无适用项”,不生成虚假路径;项目 Skill 清单是最低集合而非 allowlist。
1981
+
1982
+ #### Prefactor
1983
+
1984
+ 遵循“让变更变容易,然后做容易的变更”:
1985
+
1986
+ - 如果当前接口、依赖或接缝会使后续实现明显不安全或重复,提出前置 prefactor Ticket;
1987
+ - prefactor 必须说明它解除的具体阻碍;
1988
+ - prefactor 必须独立有价值且可验证;
1989
+ - 不为了“更干净”而创建与目标无关的重构 Ticket。
1990
+
1991
+ **完成标准**:实现地形、稳定接缝、共享路径、必要 prefactor 与逐 Ticket 项目 Skill 路由已识别。
1992
+
1993
+ ### 3. 草拟曳光弹式垂直切片
1994
+
1995
+ 加载 下方 `<decomposition-rules>` 标签。每个切片应横向穿过交付该行为所需的最小层次组合,而不是把数据库、后端、前端和测试拆成互相无价值的水平 Ticket。
1996
+
1997
+ 每个 Ticket 必须:
1998
+
1999
+ - 交付一个可观察行为,或一个能独立解除后续阻塞的安全准备能力;
2000
+ - 完成后可以独立演示、测试或验证;
2001
+ - 适合一个全新 Agent 上下文在不中断的情况下完成;
2002
+ - 与其他 Ticket 有实质行为差异;
2003
+ - 只依赖真正阻止它开始的前置产物;
2004
+ - 自带至少一种完成证据。
2005
+
2006
+ #### 宽重构例外
2007
+
2008
+ 字段重命名、共享符号类型变化、协议升级等宽机械变更无法安全塞入单个垂直切片时,按以下顺序:
2009
+
2010
+ 1. **Expand**:在旧形式旁增加新形式,保持旧调用方可工作;
2011
+ 2. **Migrate batches**:按包、目录、消费者或风险分批迁移,每批独立成 Ticket;
2012
+ 3. **Contract**:确认旧调用点为零后删除旧形式;
2013
+ 4. 若迁移批次无法各自保持绿色,使用隔离集成分支和最终集成验证 Gate,但仍保留明确的批次与责任边界。
2014
+
2015
+ **完成标准**:每个 Ticket 的可观察产出、真实阻塞边和验证方式已草拟。
2016
+
2017
+ ### 4. 判定规划深度与风险
2018
+
2019
+ 按 下方 `<readiness-and-depth>` 标签 为每个 Ticket 标注:
2020
+
2021
+ - `lite`:局部、可逆、沿用既有模式、无公共契约或迁移影响;
2022
+ - `standard`:大多数多文件或跨层垂直切片;
2023
+ - `deep`:公共 API/schema、数据迁移、安全/隐私/资金、不可逆操作、expand-contract、共享核心路径、多个 implementation owner 的跨 Ticket 写入协调或高事故半径。
2024
+
2025
+ 规划深度不是优先级,也不是 Gate。每个 Ticket 必须记录触发该深度的原因。
2026
+
2027
+ ### 5. 写成决策完备 Ticket
2028
+
2029
+ 必须按 下方 `<ref-common-rules-skill-invocation>` 标签 填写本票真实调用绑定;Map 中的读取路由不能代替调用。
2030
+
2031
+ 使用 下方 `<ticket-template>` 标签 填写:
2032
+
2033
+ - 战略目标、可观察产出与来源追踪;
2034
+ - 当前代码事实和需求差距;
2035
+ - 已锁定决策、低影响假设和未决问题;
2036
+ - IN / REUSE / OUT;
2037
+ - 用户或调用者视角的端到端行为;
2038
+ - Standard/Deep 的接口、输入输出、不变量、数据流、失败与兼容契约;
2039
+ - 有序执行路线和安全落点;
2040
+ - expected、writable、read-only、shared 路径;
2041
+ - 正常、失败和回归验证矩阵;
2042
+ - 每个 Ticket 按 Goal Plan 的 workspace 策略定义 current-workspace/direct-parent 或 source-worktree/parent-candidate 检查,以及按实际跨边界风险判定的 E2E disposition;
2043
+ - 每个实现 Ticket 的 implementation commit 与对应父分支完成条件;仅 required 模式创建独立 worktree;
2044
+ - Deep 的迁移、兼容窗口、监控、回滚和不可逆批准点;
2045
+ - 可判定验收标准。
2046
+
2047
+ 路径所有权必须遵守 下方 `<path-ownership>` 标签,证据设计必须遵守 下方 `<evidence-and-verification>` 标签。
2048
+
2049
+ ### 6. 构建依赖 DAG、合同覆盖与并发检查
2050
+
2051
+ 1. 使用 Ticket ID 建立 `blocked_by`;
2052
+ 2. 检测循环和不存在的引用;
2053
+ 3. 识别根 Ticket、汇合点、扇出与收缩点;
2054
+ 4. 为每个 Spec 验收合同映射至少一个 Ticket;
2055
+ 5. 检查并行候选的 `writable_paths` 是否相交;
2056
+ 6. 共享路径必须指定唯一 owner,通常由专门 Ticket 或明确的集成 owner 修改;
2057
+ 7. 不得用依赖边表达“可能更方便”或纯粹的人员交接。
2058
+
2059
+ 使用 下方 `<tickets-map-template>` 标签 草拟总体 Map;写入所有 Ticket 共享的总体实施背景与项目 Skill 读取矩阵。矩阵中的每个 Ticket 必须由 `ALL` 或自己的 Ticket ID 覆盖。
2060
+
2061
+ ### 7. Definition of Ready
2062
+
2063
+ 加载 下方 `<ticket-readiness>` 标签 逐个检查。
2064
+
2065
+ 存在以下任一情况时 `ready: false`:
2066
+
2067
+ - 会改变行为、接口、数据、兼容、安全、范围或验收的未决问题;
2068
+ - 依赖缺失或 DAG 有环;
2069
+ - 可写路径不明确或并行所有权冲突;
2070
+ - 验证方法不能执行且没有批准的替代证据;
2071
+ - Ticket 未声明 E2E required/not-required 及理由,或在 required 模式把 E2E 安排到 source worktree;
2072
+ - Tickets Map 缺少总体实施背景或项目 Skill 读取矩阵,项目 Skill 路径不存在、不是项目根相对路径,或当前 Ticket 未被 `ALL`/自身 ID 覆盖;
2073
+ - 无法形成实现 commit 与 Goal Plan 所选 direct-parent/candidate-merge 父分支出口;
2074
+ - 单个新上下文无法完成;
2075
+ - Standard/Deep 缺少有序执行路线;
2076
+ - Deep 缺少迁移、兼容、监控、回滚或批准点。
2077
+
2078
+ ### 8. 与用户核对
2079
+
2080
+ 以完整编号列表展示所有 Ticket,至少包含:
2081
+
2082
+ - 标题;
2083
+ - 可观察交付;
2084
+ - 被阻塞于;
2085
+ - Planning Depth 与触发原因;
2086
+ - 风险;
2087
+ - Ready 状态;
2088
+ - 关键未决问题;
2089
+ - 预计并行组和共享路径 owner;
2090
+ - `ALL` 与逐 Ticket 的项目 Skill 最低必读集合。
2091
+
2092
+ 核对:
2093
+
2094
+ - 粒度是否适合单一上下文;
2095
+ - 是否出现水平切片;
2096
+ - 阻塞边是否真实;
2097
+ - 是否应合并、进一步拆分或增加 prefactor;
2098
+ - 合同是否全部覆盖;
2099
+ - 路径所有权和验证是否可信。
2100
+
2101
+ 每次修改后重新展示完整列表,直到用户批准。用户明确要求一次性自主规划且不存在高影响未知项时,可使用推荐默认值并把假设写入 Ticket,不为形式重复询问。
2102
+
2103
+ ### 9. 发布
2104
+
2105
+ 创建:
2106
+
2107
+ - Ticket 目录:`specdev/changes/{change}/ticket/`
2108
+ - Tickets Map:`specdev/changes/{change}/tickets-map.md`
2109
+ - Evidence 目录:`specdev/changes/{change}/evidence/`
2110
+
2111
+ 按拓扑顺序写入 Ticket:
2112
+
2113
+ ```text
2114
+ specdev/changes/{change}/ticket/NN-<ticket-name>.md
2115
+ ```
2116
+
2117
+ `NN` 使用两位或更多位零填充数字;Ticket frontmatter ID 使用 `T-NN`。Ticket 的 `blocked_by` 使用 Ticket ID,而不是相对文件路径。
2118
+
2119
+ 使用 下方 `<ticket-template>` 标签 和 下方 `<tickets-map-template>` 标签 生成工件,并对照:
2120
+
2121
+ - 下方 `<ticket-schema>` 标签
2122
+ - 下方 `<tickets-map-schema>` 标签
2123
+
2124
+ 运行:
2125
+
2126
+ ```bash
2127
+ node Speculo Node 校验器 \
2128
+ --stage tickets \
2129
+ --repo <project-root> \
2130
+ specdev/changes/{change}
2131
+ ```
2132
+
2133
+ 更新 `specdev/status.json` 与 `specdev/changes/{change}/.status.json`。
2134
+
2135
+ ## 完成标准
2136
+
2137
+ - Ticket 目录和 Map 已写入本文约定的位置;
2138
+ - Spec 合同全部 covered 或有明确批准的 deferred;
2139
+ - DAG 无环、阻塞引用存在;
2140
+ - Ready Ticket 无高影响未知项;
2141
+ - 并行 Ticket 无未解决的可写冲突;
2142
+ - 每个 Ticket 可独立验证且适配单一上下文;
2143
+ - Tickets Map 已记录总体实施背景;每个 Ticket 被项目 Skill 读取矩阵覆盖,Skill 路径存在且为项目根相对路径;
2144
+ - Prefactor 与 expand-contract 使用条件正确;
2145
+ - 用户已批准拆分或明确授权自主发布;
2146
+ - 校验器无 error。
2147
+
2148
+ ## 子文件引用
2149
+
2150
+ - 拆分规则:下方 `<decomposition-rules>` 标签
2151
+ - Ticket 就绪规则:下方 `<ticket-readiness>` 标签
2152
+ - Ticket 模板:下方 `<ticket-template>` 标签
2153
+ - Tickets Map 模板:下方 `<tickets-map-template>` 标签
2154
+
2155
+ ## 下一步
2156
+
2157
+ 满足任一情况时建议运行 “目标规划阶段”:Ticket 数量达到或超过 10、存在多个 implementation owner 的并行写入协调、Deep Ticket、迁移、共享契约、多个 Gate 或高风险发布。只读 review/research 并行本身不触发 Goal Plan;少量线性 Ready Ticket 可直接进入 “实现阶段”。
2158
+
2159
+ </ref-t-tickets-references-planning-procedure>
2160
+
2161
+ <ref-common-skills-plan-quality-review-skill>
2162
+
2163
+ # Plan Quality Review
2164
+
2165
+ 读取 下方 `<ref-common-skills-plan-quality-review-references-checklist>` 标签,输入当前范围的 Spec、Ticket、map、授权引用和真实技能元数据。只读检查,结果交回 T/P 写入其原有 LOG/Evidence,不创建独立状态根。
2166
+
2167
+ 按背景与边界、调用可执行性、依赖/资源、验收与数量、权限与恢复逐项给出 pass/block/not-applicable 及证据。任一硬门禁缺失则阻塞受影响票;用户要求完整计划时不得用 Lite、少量样例或压缩输出代替全部交付。
2168
+
2169
+ </ref-common-skills-plan-quality-review-skill>
2170
+
2171
+ <ref-p-goal-plan-references-map-control>
2172
+
2173
+ # 从 tickets-map 控制整个 Goal
2174
+
2175
+ ## 只读控制器
2176
+
2177
+ 使用 本地只读 Goal 控制器(不含于网页快照),输入单 change tickets-map、父入口 tickets-map 或旧 Implementation Map。`--repo` 指项目根;可用 `--previous` 提供上轮 JSON 输出,比较输入漂移。输出仅建议 frontier、blocked、in-flight、完成票与受影响闭包,不写状态、不调用 Skill、不授予权限,也不代替既有阶段校验器。
2178
+
2179
+ ```bash
2180
+ node 本地只读 Goal 控制器(不含于网页快照) --map <map-path> --repo <project-root>
2181
+ ```
2182
+
2183
+ Lead 将输出保存到调用方自己的既有 Evidence 位置;不创建独立调度数据库。JSON 中 `input_digest`、`goal_contract_digest` 和逐票 `contract_digests` 是读集快照,不是授权凭据。
2184
+
2185
+ ## 每轮循环
2186
+
2187
+ 1. 重读当前 map、Ticket frontmatter、Gate 与 owner;机器检查依赖、Skill、语义资源和路径,Lead 核验真实授权及当前 Git 事实。
2188
+ 2. 只有依赖成功满足、ready、owner 可判定且无冲突的票才能进入 dispatch。cancelled 不是成功交付:下游必须重规划依赖,不能自动视为 satisfied。
2189
+ 3. current 策略串行;required 仅在 config/宿主允许且写集、语义资源、integration queue 无冲突时并行。不同文件可能共享 API、数据表、锁文件或公共契约,因此不能只比较文件名。
2190
+ 4. 按票的调用阶段读取并实际执行必需 Skill;按项目协议调用的“技能”可以是宿主技能调用,也可以是完整执行该 SKILL 的程序步骤,但必须记录对应步骤/工具轨迹与输出,不得仅记录阅读完成。
2191
+ 5. I 返回后核对实现、Skill 执行记录、验证矩阵、实际交付数量和集成证据。失败保留 blocker;不能用减少测试或替换工具来“修好”状态。
2192
+ 6. 同步 Ticket 权威状态,再生成 map 投影与检查点。已完成票不重跑副作用;持久化失败不推进 done。
2193
+ 7. 有他人资源/事务冲突只暂停该票与其依赖闭包,继续独立、已授权票。无法可靠分辨共享资源时,暂停相关资源而非抢占。
2194
+ 8. frontier 空且仍有未完成票时返回精确缺口;全部票完成后执行 Goal 集成验收,按原完成合同关闭。
2195
+
2196
+ ## 正式记忆
2197
+
2198
+ 开始任何正式写入前,先检查原网关的 pending transaction、lock、recovery evidence 与 owner。Goal 只请求拥有 namespace 的原工作流执行,不直接写永久记忆,也不创建“更轻量”的旁路网关。
2199
+
2200
+ 单票 blocked/deviated 不强制将父 Plan 的全局执行门关闭。只有全局合同失败或合法 frontier 为空时暂停父循环。检查点摘要覆盖 Spec、票合同、实际 Skill/参考版本、依赖、相关 serialization 与共享 Goal 门禁;普通 owner/status 和进度投影不是合同变更。摘要是漂移检测,不替代授权和实证验收。
2201
+
2202
+ </ref-p-goal-plan-references-map-control>
2203
+
2204
+ <ref-common-skills-plan-quality-review-references-checklist>
2205
+
2206
+ # 计划发布检查
2207
+
2208
+ | 检查轴 | 通过证据 | 阻塞条件 |
2209
+ |---|---|---|
2210
+ | 背景与边界 | 用户问题、源基线、IN/REUSE/OUT、可观察行为 | 需实现者重新猜目标或高影响决定 |
2211
+ | Skill 调用 | 实际入口 ID/摘要、阶段、输入输出、失败动作;无适用项有扫描依据 | 假路径、缓存伪装源、仅 @名称 或“阅读完成” |
2212
+ | 执行计划 | 接缝、有序步骤、公共契约、异常、迁移/兼容与回滚 | 只有任务标题或横向技术层清单 |
2213
+ | 控制图 | 全部票、真实依赖、路径与语义资源、owner、失败闭包 | 环、未解析依赖、并发写冲突、取消被当成功 |
2214
+ | 验收与数量 | 每项 AC 和用户数量都有可复核证据目标 | 以字符预算削减验收、数量或风险处理 |
2215
+ | 权限 | 真实授权引用、明确计划与实现分界、独立审批点 | 自授权、默认提交/发布/远程写入 |
2216
+ | 恢复 | 基线/版本、检查点、原事务网关、源回读、停止条件 | 抢占他人事务、重复副作用、只看 done |
2217
+
2218
+ 先利用代码、配置、测试和历史回答可发现事实;确有高影响取舍才回用户。不要为显得严格而制造与当前风险无关的关卡。用户要求全面审查时覆盖所有适用轴和所有票,不限制 finding 数量。
2219
+
2220
+ </ref-common-skills-plan-quality-review-references-checklist>