@namewta/speculo 1.0.18 → 1.0.20

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 (195) hide show
  1. package/README.md +8 -7
  2. package/THIRD-PARTY-NOTICES.md +33 -0
  3. package/dist/src/agent-files.js +2 -2
  4. package/dist/src/agent-files.js.map +1 -1
  5. package/dist/src/agent-skills.d.ts +81 -0
  6. package/dist/src/agent-skills.js +530 -0
  7. package/dist/src/agent-skills.js.map +1 -0
  8. package/dist/src/cli.js +11 -3
  9. package/dist/src/cli.js.map +1 -1
  10. package/dist/src/config.js +5 -3
  11. package/dist/src/config.js.map +1 -1
  12. package/dist/src/doctor.js +7 -2
  13. package/dist/src/doctor.js.map +1 -1
  14. package/dist/src/index.d.ts +8 -0
  15. package/dist/src/index.js +23 -3
  16. package/dist/src/index.js.map +1 -1
  17. package/dist/src/manifest.d.ts +9 -0
  18. package/dist/src/manifest.js +45 -7
  19. package/dist/src/manifest.js.map +1 -1
  20. package/dist/src/refresh.js +40 -0
  21. package/dist/src/refresh.js.map +1 -1
  22. package/dist/src/structured.js +15 -4
  23. package/dist/src/structured.js.map +1 -1
  24. package/dist/src/transaction.d.ts +24 -3
  25. package/dist/src/transaction.js +191 -12
  26. package/dist/src/transaction.js.map +1 -1
  27. package/package.json +10 -4
  28. package/scripts/validate-skills.mjs +56 -0
  29. package/template/AGENTS.md +1 -1
  30. package/template/CLAUDE.md +1 -1
  31. package/template/canonical/canonical-specdev-goal-plan.md +158 -30
  32. package/template/canonical/canonical-specdev-grill-with-docs.md +155 -33
  33. package/template/canonical/canonical-specdev-spec.md +162 -161
  34. package/template/canonical/canonical-specdev-tickets.md +155 -29
  35. package/template/canonical/canonical-specdev-wayfinder.md +144 -29
  36. package/template/commands/handoff.md +16 -0
  37. package/template/commands/retro.md +12 -10
  38. package/template/skills/archive-and-consolidate/SKILL.md +163 -7
  39. package/template/skills/archive-and-consolidate/references/cleanup-rules.md +1 -1
  40. package/template/skills/docs-sync/references/agents/claude-redirect.md +8 -8
  41. package/template/skills/docs-sync/references/agents/content-contract.md +1 -1
  42. package/template/skills/docs-sync/references/agents/manifest-discovery.md +7 -7
  43. package/template/skills/docs-sync/references/agents/role-classification.md +4 -4
  44. package/template/skills/docs-sync/references/agents-contract.md +1 -1
  45. package/template/skills/engineering-standards-builder/SKILL.md +149 -9
  46. package/template/skills/engineering-standards-builder/agents/openai.yaml +2 -0
  47. package/template/skills/engineering-standards-builder/manifest.txt +2 -1
  48. package/template/skills/engineering-standards-builder/references/rules/09-mechanical-guardrails.md +9 -0
  49. package/template/skills/engineering-standards-builder/scripts/validate-builder.mjs +4 -7
  50. package/template/skills/git-history-squash/SKILL.md +87 -11
  51. package/template/skills/git-history-squash/agents/openai.yaml +2 -0
  52. package/template/skills/optimize-codex-config/SKILL.md +71 -11
  53. package/template/skills/retrospective/SKILL.md +43 -0
  54. package/template/skills/{speculo-retro → retrospective}/references/friction-taxonomy.md +22 -13
  55. package/template/skills/{speculo-retro → retrospective}/references/issue-drafting-sop.md +13 -21
  56. package/template/skills/source-code-zip/SKILL.md +44 -8
  57. package/template/skills/source-code-zip/references/{entry-procedure.md → cli-reference.md} +0 -43
  58. package/template/skills/upstream-fork-sync/SKILL.md +71 -8
  59. package/template/skills/{writing-great-skills → writing-for-agents}/GLOSSARY.md +1 -1
  60. package/template/skills/writing-for-agents/SKILL.md +22 -0
  61. package/template/skills/writing-for-agents/agents/openai.yaml +2 -0
  62. package/template/skills/{writing-great-skills/references/entry-procedure.md → writing-for-agents/references/authoring-principles.md} +2 -9
  63. package/template/workflows/learning/A-archive/A-archive.md +2 -5
  64. package/template/workflows/learning/A-assess-and-plan/A-assess-and-plan.md +2 -5
  65. package/template/workflows/learning/C-consolidate/C-consolidate.md +2 -5
  66. package/template/workflows/learning/G-goal/G-goal.md +5 -23
  67. package/template/workflows/learning/H-homework/H-homework.md +2 -5
  68. package/template/workflows/learning/I-init-setup/I-init-setup.md +4 -9
  69. package/template/workflows/learning/L-lesson/L-lesson.md +2 -5
  70. package/template/workflows/learning/Q-question/Q-question.md +16 -8
  71. package/template/workflows/learning/Q-question/inquiry-template.md +2 -0
  72. package/template/workflows/learning/Q-question/tools/validate-inquiry.mjs +112 -0
  73. package/template/workflows/learning/R-review/R-review.md +3 -6
  74. package/template/workflows/learning/README.md +2 -2
  75. package/template/workflows/learning/common/rules/knowledge-organization.md +1 -1
  76. package/template/workflows/learning/common/rules/mastery-policy.md +1 -1
  77. package/template/workflows/learning/common/skills/socratic-questioning/SKILL.md +1 -1
  78. package/template/workflows/ops/D-project-deploy/D-project-deploy.md +6 -2
  79. package/template/workflows/ops/H-host-manage/H-host-manage.md +10 -18
  80. package/template/workflows/ops/H-host-manage/references/host-profiles.md +21 -0
  81. package/template/workflows/ops/I-initialize/I-initialize.md +4 -4
  82. package/template/workflows/ops/README.md +22 -84
  83. package/template/workflows/ops/S-server-connect/S-server-connect.md +3 -3
  84. package/template/workflows/ops/V-inventory-view/V-inventory-view.md +2 -2
  85. package/template/workflows/ops/common/rules/deployment-layout.md +51 -0
  86. package/template/workflows/ops/common/rules/recovery.md +6 -0
  87. package/template/workflows/ops/common/rules/server-onboarding.md +6 -0
  88. package/template/workflows/ops/common/tests/test_ops.mjs +5 -8
  89. package/template/workflows/ops/common/tests/test_ops_bootstrap.mjs +71 -14
  90. package/template/workflows/ops/common/tests/test_ops_workspace.mjs +17 -8
  91. package/template/workflows/ops/common/tools/opslib/bootstrap.mjs +4 -4
  92. package/template/workflows/ops/common/tools/opslib/transport.mjs +3 -3
  93. package/template/workflows/person/M-mao-zedong-cognitive-os/M-mao-zedong-cognitive-os.md +13 -68
  94. package/template/workflows/person/S-steelman-deliberation/S-steelman-deliberation.md +11 -123
  95. package/template/workflows/person/S-steelman-deliberation/references/state-and-publication.md +86 -0
  96. package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md +2 -17
  97. package/template/workflows/specdev/A-archive-and-consolidate/consolidation-interview.md +13 -4
  98. package/template/workflows/specdev/C-code-review/C-code-review.md +4 -15
  99. package/template/workflows/specdev/C-code-review/code-review-template.md +4 -0
  100. package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md +4 -20
  101. package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md +2 -2
  102. package/template/workflows/specdev/G-grill-with-docs/references/interview-procedure.md +6 -6
  103. package/template/workflows/specdev/I-implement/I-implement.md +2 -2
  104. package/template/workflows/specdev/I-implement/evidence-template.md +8 -0
  105. package/template/workflows/specdev/I-implement/references/implementation-procedure.md +9 -43
  106. package/template/workflows/specdev/I-implement/tdd-rules.md +4 -0
  107. package/template/workflows/specdev/I-init-setup/I-init-setup.md +16 -117
  108. package/template/workflows/specdev/I-init-setup/config-template.json +5 -1
  109. package/template/workflows/specdev/I-init-setup/references/first-setup.md +46 -0
  110. package/template/workflows/specdev/INDEX.md +2 -2
  111. package/template/workflows/specdev/L-learn-change/L-learn-change.md +11 -89
  112. package/template/workflows/specdev/L-learn-change/references/lesson-format.md +47 -0
  113. package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +2 -2
  114. package/template/workflows/specdev/P-goal-plan/planning-modes.md +1 -1
  115. package/template/workflows/specdev/P-prototype/P-prototype.md +7 -17
  116. package/template/workflows/specdev/P-prototype/logic-protocol.md +11 -0
  117. package/template/workflows/specdev/P-prototype/logic-template.md +27 -0
  118. package/template/workflows/specdev/P-prototype/project-preview-protocol.md +9 -0
  119. package/template/workflows/specdev/R-retro/R-retro.md +26 -0
  120. package/template/workflows/specdev/R-retro/retro-template.md +27 -0
  121. package/template/workflows/specdev/R-review-architecture/R-review-architecture.md +19 -57
  122. package/template/workflows/specdev/R-review-architecture/architecture-review-template.md +2 -1
  123. package/template/workflows/specdev/R-review-architecture/references/selected-design.md +23 -0
  124. package/template/workflows/specdev/R-review-architecture/review-rubric.md +2 -2
  125. package/template/workflows/specdev/README.md +17 -6
  126. package/template/workflows/specdev/S-spec/S-spec.md +13 -136
  127. package/template/workflows/specdev/T-tickets/T-tickets.md +6 -2
  128. package/template/workflows/specdev/T-triage/T-triage.md +32 -141
  129. package/template/workflows/specdev/T-triage/capture-protocol.md +1 -1
  130. package/template/workflows/specdev/T-triage/ci-security-protocol.md +11 -0
  131. package/template/workflows/specdev/T-triage/intake-protocol.md +29 -4
  132. package/template/workflows/specdev/T-triage/pr-delivery-protocol.md +13 -0
  133. package/template/workflows/specdev/T-triage/pr-record-template.md +39 -0
  134. package/template/workflows/specdev/T-triage/publish-protocol.md +1 -1
  135. package/template/workflows/specdev/T-triage/queue-protocol.md +7 -0
  136. package/template/workflows/specdev/T-triage/reconcile-protocol.md +1 -1
  137. package/template/workflows/specdev/T-triage/references/issue-pr-policy.md +23 -0
  138. package/template/workflows/specdev/T-triage/references/release-authentication.md +9 -0
  139. package/template/workflows/specdev/T-triage/references/release-notes-injection.md +21 -0
  140. package/template/workflows/specdev/T-triage/references/workflow-yaml-reference.md +37 -0
  141. package/template/workflows/specdev/T-triage/release-preflight.md +13 -0
  142. package/template/workflows/specdev/T-triage/release-protocol.md +12 -0
  143. package/template/workflows/specdev/T-triage/release-recovery.md +18 -0
  144. package/template/workflows/specdev/T-triage/remote-operations.md +25 -0
  145. package/template/workflows/specdev/T-triage/scripts/github-transport.mjs +208 -0
  146. package/template/workflows/specdev/T-triage/source-template.md +7 -0
  147. package/template/workflows/specdev/T-triage/triage-run-template.md +34 -0
  148. package/template/workflows/specdev/T-triage/triage-template.md +4 -1
  149. package/template/workflows/specdev/W-wayfinder/W-wayfinder.md +2 -2
  150. package/template/workflows/specdev/common/rules/artifact-contract.md +7 -0
  151. package/template/workflows/specdev/common/rules/change-completion.md +6 -0
  152. package/template/workflows/specdev/common/rules/deployment-handoff.md +23 -0
  153. package/template/workflows/specdev/common/rules/workflow-routing.md +6 -0
  154. package/template/workflows/specdev/common/rules/workflow-state-and-lifecycle.md +1 -1
  155. package/template/workflows/specdev/common/schemas/config.schema.json +137 -26
  156. package/template/workflows/specdev/common/schemas/logic-prototype.schema.json +62 -0
  157. package/template/workflows/specdev/common/schemas/pull-request.schema.json +90 -0
  158. package/template/workflows/specdev/common/schemas/retrospective.schema.json +58 -0
  159. package/template/workflows/specdev/common/schemas/triage-run.schema.json +149 -0
  160. package/template/workflows/specdev/common/schemas/triage.schema.json +117 -15
  161. package/template/workflows/specdev/common/skills/code-review/SKILL.md +5 -4
  162. package/template/workflows/specdev/common/skills/code-review/references/result-reuse.md +15 -0
  163. package/template/workflows/specdev/common/tools/delivery-artifacts.mjs +95 -0
  164. package/template/workflows/specdev/common/tools/validate-specdev.mjs +60 -19
  165. package/template/workflows/specdev/runtime-contract.json +4 -2
  166. package/template/skills/archive-and-consolidate/references/entry-procedure.md +0 -178
  167. package/template/skills/docs-sync/references/entry-procedure.md +0 -3
  168. package/template/skills/engineering-standards-builder/references/entry-procedure.md +0 -154
  169. package/template/skills/git-history-squash/references/entry-procedure.md +0 -94
  170. package/template/skills/github-npm-ops/SKILL.md +0 -19
  171. package/template/skills/github-npm-ops/references/ci-and-security-ops.md +0 -178
  172. package/template/skills/github-npm-ops/references/entry-procedure.md +0 -25
  173. package/template/skills/github-npm-ops/references/failure-recovery.md +0 -123
  174. package/template/skills/github-npm-ops/references/issue-pr-triage.md +0 -219
  175. package/template/skills/github-npm-ops/references/issue-transport.md +0 -26
  176. package/template/skills/github-npm-ops/references/package-json-checklist.md +0 -171
  177. package/template/skills/github-npm-ops/references/preflight-checklist.md +0 -39
  178. package/template/skills/github-npm-ops/references/publish-detection.md +0 -68
  179. package/template/skills/github-npm-ops/references/release-notes-injection.md +0 -238
  180. package/template/skills/github-npm-ops/references/release-pipeline.md +0 -108
  181. package/template/skills/github-npm-ops/references/setup-npm-token.md +0 -63
  182. package/template/skills/github-npm-ops/references/troubleshooting-playbook.md +0 -293
  183. package/template/skills/github-npm-ops/references/version-bump-flow.md +0 -217
  184. package/template/skills/github-npm-ops/references/workflow-yaml-reference.md +0 -268
  185. package/template/skills/github-npm-ops/scripts/issue-transport.mjs +0 -227
  186. package/template/skills/optimize-codex-config/references/entry-procedure.md +0 -78
  187. package/template/skills/speculo-retro/SKILL.md +0 -19
  188. package/template/skills/speculo-retro/references/entry-procedure.md +0 -23
  189. package/template/skills/upstream-fork-sync/references/entry-procedure.md +0 -78
  190. package/template/skills/writing-great-skills/SKILL.md +0 -23
  191. /package/template/skills/{writing-great-skills → writing-for-agents}/references/document-contract.md +0 -0
  192. /package/template/workflows/specdev/{G-grill-with-docs → common/rules}/adr-format.md +0 -0
  193. /package/template/workflows/specdev/{G-grill-with-docs → common/rules}/context-format.md +0 -0
  194. /package/template/workflows/specdev/{I-implement → common/rules}/design-it-twice.md +0 -0
  195. /package/template/workflows/specdev/{G-grill-with-docs/domain-modeling-rules.md → common/rules/domain-modeling.md} +0 -0
@@ -0,0 +1,86 @@
1
+ # Steelman 状态与候选发布合同
2
+
3
+ 新建、恢复或写入状态前读取状态合同;发布 dossier 时只读取回答前分支,发布 decision 时只读取回答后分支。所有路径、schema 和字段沿用原版,禁止另建状态源。
4
+
5
+ ## 状态合同
6
+
7
+ ### Workflow 状态
8
+
9
+ `<Path>{roots.state}/person/status.json</Path>` 保持 `schema_version: 1`,本 work 只管理 `active` 数组中的如下条目:
10
+
11
+ ```json
12
+ {
13
+ "change": "2026-08-18-steelman-company-anniversary",
14
+ "work_id": "person/steelman-deliberation",
15
+ "phase": "awaiting-answer",
16
+ "updated_at": "2026-08-18T00:00:00.000Z"
17
+ }
18
+ ```
19
+
20
+ 读取—合并—写入时保留未知顶层字段、未知 entry 字段和其他 work 的全部条目。写临时文件、重读 JSON、再原子替换。
21
+
22
+ ### Change 状态
23
+
24
+ `<Path>{roots.state}/person/changes/{change}/.status.json</Path>` 至少包含:
25
+
26
+ ```json
27
+ {
28
+ "schema_version": 1,
29
+ "artifact": "person-work-status",
30
+ "workflow": "person",
31
+ "change": "2026-08-18-steelman-company-anniversary",
32
+ "work_id": "person/steelman-deliberation",
33
+ "status": "active",
34
+ "phase": "awaiting-answer",
35
+ "key_question": "[唯一关键问题]",
36
+ "key_question_asked": true,
37
+ "question_disposition": "asked",
38
+ "answer_received": false,
39
+ "user_answer": null,
40
+ "created_at": "2026-08-18T00:00:00.000Z",
41
+ "updated_at": "2026-08-18T00:00:00.000Z",
42
+ "completed_at": null,
43
+ "blockers": []
44
+ }
45
+ ```
46
+
47
+ 允许转换:
48
+
49
+ ```text
50
+ intake → deliberating → awaiting-answer → judging → completed
51
+ 任一活动阶段 → blocked
52
+ awaiting-answer → reframe-required
53
+ ```
54
+
55
+ `question_disposition` 只能是 `asked | already-answered`;前者要求 `key_question_asked: true`,后者要求 `key_question_asked: false`。工件先验证,change 状态后更新,workflow active 最后更新。状态只是工件的索引,不替代工件本身。
56
+
57
+
58
+ ## 回答前:发布 dossier
59
+
60
+ 使用 `<Path>{roots.workflows}/person/S-steelman-deliberation/_templates/steelman-dossier-template.md</Path>` 在 change 目录下的唯一临时子目录中写入候选 dossier 与候选 `.status.json`,重读后运行:
61
+
62
+ ```bash
63
+ node <Path>{roots.workflows}/person/S-steelman-deliberation/tools/validate-steelman-change.mjs</Path> \
64
+ --phase awaiting-answer \
65
+ --change-dir <Path>{roots.state}/person/changes/{change}</Path> \
66
+ --dossier-file <Path>{roots.state}/person/changes/{change}/.steelman-stage/steelman-dossier.md</Path> \
67
+ --status-file <Path>{roots.state}/person/changes/{change}/.steelman-stage/.status.json</Path>
68
+ ```
69
+
70
+ 临时目录名在并发时追加唯一后缀。校验通过后,先原子替换正式 dossier,再原子替换 change `.status.json`;workflow active 只在入口的等待回答阶段 确认需要等待用户时更新。校验失败时删除临时目录并保持正式工件和旧状态不变。
71
+
72
+
73
+ ## 回答后:发布 decision
74
+
75
+ 使用 `<Path>{roots.workflows}/person/S-steelman-deliberation/_templates/decision-template.md</Path>` 在唯一临时目录中写入候选 decision 与候选完成态 `.status.json`,随后运行:
76
+
77
+ ```bash
78
+ node <Path>{roots.workflows}/person/S-steelman-deliberation/tools/validate-steelman-change.mjs</Path> \
79
+ --phase completed \
80
+ --change-dir <Path>{roots.state}/person/changes/{change}</Path> \
81
+ --decision-file <Path>{roots.state}/person/changes/{change}/.steelman-stage/decision.md</Path> \
82
+ --status-file <Path>{roots.state}/person/changes/{change}/.steelman-stage/.status.json</Path>
83
+ ```
84
+
85
+ 校验通过后才原子替换正式 decision 和 change 状态,并只从 workflow `status.json.active` 删除匹配当前 `change` 且属于本 work 的条目。校验失败时删除临时目录、返回 `validation-failed`,保留可恢复的 `judging` 状态。
86
+
@@ -13,12 +13,7 @@ keywords: [归档, consolidation, ADR, context, research, knowledge, 代码库
13
13
 
14
14
  A 是 SpecDev 的归档 wrapper:它拥有模式选择、SpecDev 完成门和代码访谈;机械扫描、dry-run、知识毕业、合并、清理、移动与重读由 `<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>` 单一维护。
15
15
 
16
- ## 读取范围
17
-
18
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
19
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
20
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
21
-
16
+ 激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前步骤定位输入和证据。
22
17
 
23
18
  ## 模式
24
19
 
@@ -38,11 +33,7 @@ A 是 SpecDev 的归档 wrapper:它拥有模式选择、SpecDev 完成门和
38
33
 
39
34
  ## Consolidate-from-code 模式
40
35
 
41
- 1. 创建 `<Path>{roots.state}/specdev/changes/{change}/</Path>`、change 状态、LOG、CONTEXT 和 ADR,并登记 `current_work`。
42
- 2. 加载 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-interview.md</Path>`,每轮先探索代码/配置/测试并陈述证据,再一次只问一个真正影响长期理解的问题。
43
- 3. 按 LOG → CONTEXT → ADR 顺序写入:CONTEXT 只保存项目规范术语;ADR 只有同时满足难逆转、令人意外和真实权衡时才创建。
44
- 4. 用户结论必须由当前代码或实际行为验证;未验证内容留在 LOG,不提升。
45
- 5. 按 change completion 规则由本 Work 关闭该非实现型 change,再进入 Archive 模式的 dry-run/确认流程。
36
+ 读取 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-interview.md</Path>`,由本 Work 创建知识 change、按代码证据访谈并验证后关闭,再回到 Archive 模式。LOG/CONTEXT/ADR 先在该 change 内形成;未验证结论留在 LOG,不直接提升永久知识。
46
37
 
47
38
  ## 副作用
48
39
 
@@ -57,9 +48,3 @@ Dry-run 不修改文件。归档移动、知识 merge/rewrite/delete、Git 动
57
48
  - 源不存在、目标完整、active/archived 无重叠、归档状态正确;
58
49
  - 永久知识只包含当前、跨 change 有用且有实现证据的结论;
59
50
  - 无未批准移动、删除、改写或 Git 副作用。
60
-
61
- ## 子文件引用
62
-
63
- - 全局归档 Skill:`<Path>{roots.skills}/archive-and-consolidate/SKILL.md</Path>`
64
- - Change 完成:`<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`
65
- - 代码访谈:`<Path>{roots.workflows}/specdev/A-archive-and-consolidate/consolidation-interview.md</Path>`
@@ -38,9 +38,9 @@
38
38
  change 内三份文档复用 grill 的既有格式,避免重复发明:
39
39
 
40
40
  - 设计日志:`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`;
41
- - 领域上下文:`<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`;
42
- - 架构决策:`<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`;
43
- - 领域建模规则:`<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。
41
+ - 领域上下文:`<Path>{roots.workflows}/specdev/common/rules/context-format.md</Path>`;
42
+ - 架构决策:`<Path>{roots.workflows}/specdev/common/rules/adr-format.md</Path>`;
43
+ - 领域建模规则:`<Path>{roots.workflows}/specdev/common/rules/domain-modeling.md</Path>`。
44
44
 
45
45
  同步顺序固定:先 LOG,再 CONTEXT,最后 ADR。CONTEXT 只描述当前真相,历史轨迹留在 LOG;未确认的解读不得写成已接受 ADR;与现有永久 ADR 冲突时建立 supersedes 链,不重写历史。高影响条目带来源标识(`USER-DECISION`、`CODE:`、`RESEARCH:`、`ADR-###`)。
46
46
 
@@ -51,4 +51,13 @@ change 内三份文档复用 grill 的既有格式,避免重复发明:
51
51
  - 缺少必要外部信息或权限,change 标 blocked;或
52
52
  - 继续提问只会产生低影响或纯实现细节,交给对应实现阶段决定。
53
53
 
54
- 停止后交回入口 §3,进入知识提升评估。未获代码或实际行为验证的结论一律不提升,只留在 change 内。
54
+ 停止后返回 A 的 Archive 模式,进入知识提升评估。未获代码或实际行为验证的结论一律不提升,只留在 change 内。
55
+
56
+
57
+ ## Consolidate-from-code 模式
58
+
59
+ 1. 创建 `<Path>{roots.state}/specdev/changes/{change}/</Path>`、change 状态、LOG、CONTEXT 和 ADR,并登记 `current_work`。
60
+ 2. 按上述访谈过程,每轮先探索代码/配置/测试并陈述证据,再一次只问一个真正影响长期理解的问题。
61
+ 3. 按 LOG → CONTEXT → ADR 顺序写入:CONTEXT 只保存项目规范术语;ADR 只有同时满足难逆转、令人意外和真实权衡时才创建。
62
+ 4. 用户结论必须由当前代码或实际行为验证;未验证内容留在 LOG,不提升。
63
+ 5. 按 change completion 规则由本 Work 关闭该非实现型 change,再进入 Archive 模式的 dry-run/确认流程。
@@ -13,12 +13,7 @@ keywords: [code-review, review, diff, fixed-point, PR, 标准, 规范]
13
13
 
14
14
  C 是独立 review 入口,不实施修复。它拥有 `<Path>{roots.state}/specdev/changes/{change}/reviews/</Path>`;I 的最终审查由 I 写入 Evidence,不写本目录。
15
15
 
16
- ## 读取范围
17
-
18
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
19
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
20
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
21
-
16
+ 激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前步骤定位输入和证据。
22
17
 
23
18
  ## 输入
24
19
 
@@ -28,11 +23,11 @@ C 是独立 review 入口,不实施修复。它拥有 `<Path>{roots.state}/spe
28
23
 
29
24
  ## 流程
30
25
 
31
- 1. **解析固定点**:使用 `git rev-parse` 把固定点和 HEAD 固定为 SHA;PR 先通过 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>` 的 `pr-read` 获得 base/head SHA,并确保对应对象可在本地解析。
26
+ 1. **解析固定点**:使用 `git rev-parse` 把固定点和 HEAD 固定为 SHA;PR 先通过 `<Path>{roots.workflows}/specdev/T-triage/remote-operations.md</Path>` 的 `pr-read` 获得 base/head SHA,并确保对应对象可在本地解析。
32
27
  2. **冻结输入**:记录 `git diff <fixed>...<head>` 和 `git log <fixed>..<head> --oneline`。引用无效或 diff 为空时失败,不创建报告。
33
28
  3. **发现来源**:调用 `<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`;规范来源缺失时经确认跳过规范轴,标准轴继续。
34
- 4. **隔离审查**:平台支持时并行 reviewer,否则用两个独立完整输入包顺序执行。两轴不得读取对方 finding。
35
- 5. **持久化**:选择下一个未占用 `CR-###`,使用模板写入 `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>`,原子重读。
29
+ 4. **隔离审查**:仅按公共 Skill 的完整输入复用门接受既有结果;需要执行的轴在平台支持时并行 reviewer,否则用两个独立完整输入包顺序执行。两轴不得读取对方 finding。
30
+ 5. **持久化**:选择下一个未占用 `CR-###`,使用 `<Path>{roots.workflows}/specdev/C-code-review/code-review-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/reviews/CR-###.md</Path>`,原子重读。
36
31
  6. **验证与路由**:使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage review` 校验当前 change。无阻塞 finding 时返回完成或 I;局部修复生成/修订 Ticket;规范冲突返回 S/G;无法确定的 blocker 保持 C 可恢复状态。
37
32
 
38
33
  ## 完成标准
@@ -43,9 +38,3 @@ C 是独立 review 入口,不实施修复。它拥有 `<Path>{roots.state}/spe
43
38
  - 每个 finding 有路径、风险、依据和满足条件;
44
39
  - 报告、状态、验证结果和下一 Work 路径一致;
45
40
  - C 未修改项目代码或远程状态。
46
-
47
- ## 子文件引用
48
-
49
- - 公共审查 Skill:`<Path>{roots.workflows}/specdev/common/skills/code-review/SKILL.md</Path>`
50
- - 报告模板:`<Path>{roots.workflows}/specdev/C-code-review/code-review-template.md</Path>`
51
- - 报告 Schema:`<Path>{roots.workflows}/specdev/common/schemas/code-review.schema.json</Path>`
@@ -40,3 +40,7 @@ created_at: <ISO-8601>
40
40
  - **Most severe standards finding:** none / ...
41
41
  - **Most severe specification finding:** none / ...
42
42
  - **Next Work:** completed / `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` / `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`
43
+
44
+ ## 审查证据复用(仅实际发生时填写)
45
+
46
+ 记录原 CR/Evidence locator、fixed/head/diff、规范/标准/指令与 Skill/reference 摘要、工具/环境相关证据、两轴隔离核对、复用或重跑的轴与原因。未发生时写“不适用”;本节不是通过声明,也不改变原始审查结果。
@@ -13,12 +13,7 @@ keywords: [bug, 诊断, 红灯, tight-loop, 根因, 复现, 假设]
13
13
 
14
14
  D 的主导词是**红灯**:没有一条已执行且能在此 bug 上变红的紧凑命令,就没有可进入的假设阶段。D 默认只读项目代码,可以创建 change 诊断工件和经授权的临时可撤销探针;生产修复由 Implement 拥有。
15
15
 
16
- ## 读取范围
17
-
18
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
19
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
20
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
21
-
16
+ 激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前步骤定位输入和证据。
22
17
 
23
18
  ## 输入与所有权
24
19
 
@@ -75,19 +70,8 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
75
70
 
76
71
  根因确认后将本 Work 加入 `works_run` 并清空 `current_work`,返回 diagnosis 和下一 Work:局部修复进入 Tickets/I,公共行为或高风险进入 S/Tickets,缺 seam 进入 R,仍无根因则保持 blocked 或进入 W。
77
72
 
78
- ## 完成标准
79
-
80
- - 红灯回路硬门有已执行证据;
81
- - 最小复现的剩余元素都有负载作用;
82
- - 假设有排名、预测和反证;
83
- - 根因解释触发、机制、漏检和影响;
84
- - 修复契约决策完备但未夹带生产修复;
85
- - debug 插桩已清理或有明确 owner;
86
- - diagnosis、状态、验证证据和下一 Work 路径一致。
73
+ ## 脱敏与强制变异证据
87
74
 
88
- ## 子文件引用
75
+ 在日志、报告和重现材料中移除 token、Cookie、认证头、秘密配置、个人数据及机器绝对路径;保留项目相对定位和必要错误形态。原始敏感数据不进入长期工件。
89
76
 
90
- - 反馈回路:`<Path>{roots.workflows}/specdev/D-diagnose-bugs/feedback-loop.md</Path>`
91
- - 假设与插桩:`<Path>{roots.workflows}/specdev/D-diagnose-bugs/hypothesis-and-instrumentation.md</Path>`
92
- - 诊断模板:`<Path>{roots.workflows}/specdev/D-diagnose-bugs/diagnosis-template.md</Path>`
93
- - HITL 模板:`<Path>{roots.workflows}/specdev/D-diagnose-bugs/scripts/hitl-loop.template.sh</Path>`
77
+ 如果使用强制变异检验测试敏感性,先记录未变异文件的 hash/diff,实际修改目标后读取 git diff 与运行路径,证明变异已落到执行文件。只有测试因预期行为断言失败才算有效 red;编译错误、未选中测试、变异未落地均为无效证据。恢复原内容,复跑基线并核对 diff。D 输出诊断及修复不变量,正式修复仍交 I。
@@ -15,9 +15,9 @@ keywords: [grill, 设计树, 领域, 决策, 共识]
15
15
 
16
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 或索引。
17
17
 
18
- ## 过程与边界
18
+ ## 当前 change 的访谈与共识
19
19
 
20
- 进入访谈必须读取 `<Path>{roots.workflows}/specdev/G-grill-with-docs/references/interview-procedure.md</Path>`,再按触发分支读取 grilling、领域建模、日志格式或 stakeholder questionnaire。保留完整 frontier、推荐答案和逐轮共识检查,但不替用户回答高影响取舍。
20
+ 进入访谈必须读取 `<Path>{roots.workflows}/specdev/G-grill-with-docs/references/interview-procedure.md</Path>`,由该过程在出现设计取舍、术语变化、日志写入或外部 stakeholder 缺口时分别读取 grilling、领域建模、日志格式或 questionnaire;不默认加载所有参考。保留完整 frontier、推荐答案和逐轮共识检查,但不替用户回答高影响取舍。
21
21
 
22
22
  - 先查仓库可发现事实,只询问会改变行为、架构、风险、范围、迁移或验收的决定。
23
23
  - W 的每个 materialized change 在自己的目录拥有设计树和文档;共享答案以来源指针引用,不能共用一棵可写设计树。
@@ -40,9 +40,9 @@
40
40
 
41
41
  分别使用:
42
42
 
43
- - `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`
43
+ - `<Path>{roots.workflows}/specdev/common/rules/adr-format.md</Path>`
44
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>`
45
+ - `<Path>{roots.workflows}/specdev/common/rules/context-format.md</Path>`
46
46
  - `<Path>{roots.workflows}/specdev/common/schemas/design-tree.schema.json</Path>`
47
47
 
48
48
  恢复时先读取四份工件,按 design tree 的节点状态恢复,避免重复询问已关闭问题。
@@ -90,7 +90,7 @@
90
90
 
91
91
  ### 5. 同步 change-local 领域模型
92
92
 
93
- 加载 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。每轮先写 LOG,再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT,最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
93
+ 加载 `<Path>{roots.workflows}/specdev/common/rules/domain-modeling.md</Path>`。每轮先写 LOG,再把已确认且本 change 下游必须使用的项目规范术语同步到 change CONTEXT,最后把同时满足三个准入条件、已成为本 change 合同的架构决定写入 change ADR。
94
94
 
95
95
  历史轨迹只留在 LOG;未确认选项不写成已接受 ADR;已有 change ADR 被替代时建立 supersedes 链。同步只更新本 change 工件,不创建、合并或改写永久 `context/`、`adr/`;它记录共识生长过程,不授权产品实现。
96
96
 
@@ -127,8 +127,8 @@ frontier 为空时,向用户确认设计树的每个分支均已走过且已
127
127
 
128
128
  - 质询协议:`<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`
129
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>`
130
+ - 领域建模:`<Path>{roots.workflows}/specdev/common/rules/domain-modeling.md</Path>`
131
+ - ADR 格式:`<Path>{roots.workflows}/specdev/common/rules/adr-format.md</Path>`
132
+ - CONTEXT 格式:`<Path>{roots.workflows}/specdev/common/rules/context-format.md</Path>`
133
133
  - LOG 格式:`<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`
134
134
  - Stakeholder 问卷:`<Path>{roots.workflows}/specdev/G-grill-with-docs/stakeholder-questionnaire.md</Path>`
@@ -15,9 +15,9 @@ keywords: [implement, Ticket, TDD, Evidence, integration]
15
15
 
16
16
  先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;从当前 tickets-map 或父 map 定位本票、上游约束、项目 Skill 与执行策略。仅展开当前 Ticket 的正文、直接依赖、适用 Skill 和必要恢复证据,不整读知识库。
17
17
 
18
- ## 执行入口
18
+ ## 当前票的执行入口
19
19
 
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 全流程,不得跳过。
20
+ 执行必须读取 `<Path>{roots.workflows}/specdev/I-implement/references/implementation-procedure.md</Path>` 和 `<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`;执行过程按当前阶段路由设计、TDD、双轴审查和 Evidence;预检单独拥有 Git、workspace、Ready 与授权检查。两者必读,分支参考只在对应 workspace/风险/阶段进入时加载。
21
21
 
22
22
  1. 核验 Ready、授权、owner、真实源与 map 基线;新增计划型票按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 实际调用绑定能力并记录证据。旧票缺调用契约时先由 Lead 补齐,不猜测。
23
23
  2. 保持 codebase-design、design-it-twice 和 TDD 的适用门禁;进入对应实现步骤再读其 reference。派单时调用 subagent-delivery;Lead 是唯一 SpecDev 状态写入者。
@@ -131,3 +131,11 @@ subagent 不写本 Evidence;以上内容由 Lead 从实际 workspace、Git 和
131
131
  ## 用户交付与源回读
132
132
 
133
133
  记录用户要求的实际数量、交付位置、源/链接/必要元数据回读、行为差异、备份和未完成项。Goal 有显式数量时在 `<Path>{roots.state}/specdev/changes/{change}/evidence/goal-delivery.md</Path>` 写 Delivery Records,与 map 合同逐项核对。字符统计包含移动后的参考文件,不等同于 Token 或套餐用量。
134
+
135
+ ## 审查证据复用(仅实际发生时填写)
136
+
137
+ 记录原 CR/Evidence locator、fixed/head/diff、规范/标准/指令与 Skill/reference 摘要、工具/环境相关证据、两轴隔离核对、复用或重跑的轴与原因。未发生时写“不适用”;本节不是通过声明,也不改变原始审查结果。
138
+
139
+ ## OPS 交付(仅用户请求时)
140
+
141
+ 交付前读取 `<Path>{roots.workflows}/specdev/common/rules/deployment-handoff.md</Path>`,记录当前 change/Ticket、代码 revision、实际构件 digest、AC/Evidence、目标与部署约束;回传时只追加经核对的 Run/Release/receipt 指针。未请求写“不适用”,不为填表创建 OPS 任务。
@@ -10,7 +10,7 @@
10
10
 
11
11
  ### Ticket 模式(默认)
12
12
 
13
- 先读取 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。
13
+ 使用下节规定的输入顺序。父 Implementation Plan 存在时采用其 Lead、workspace/integration 与全局 Gate,即使子 Goal Plan 不存在;两者都有时必须一致。没有父计划沿用子计划;两者都没有时当前主会话作为 Lead,按 Direct Spec 的轻量边界执行,不猜测 worktree 策略。
14
14
 
15
15
  ### Direct Spec 模式
16
16
 
@@ -51,17 +51,11 @@ Git 已处于 merge/rebase 冲突时,先加载 `<Path>{roots.workflows}/specde
51
51
 
52
52
  加载 `<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`。
53
53
 
54
- Ticket 模式:
54
+ 预检参考拥有 Ready、依赖证据、真实 Skill、计划版本、owner、权限、Git 状态与 workspace 的完整检查,不在此复写。
55
55
 
56
- 1. 验证 Ready、依赖 Evidence、Spec/ADR/Goal Plan、一致性、路径 owner 和验证接缝;确认 Tickets Map 的总体实施背景、项目 Skill 矩阵、当前 Ticket 覆盖与实际文件均有效,并完成规定读取顺序;
57
- 2. 确认子 Goal Plan schema v6(若存在)与父 Implementation Plan schema v1(若存在)、唯一 Lead、workspace 策略、动态 implementation/integration 上限与授权;
58
- 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;
59
- 4. Lead 把 Ticket 设为 `in_progress`;`required` 模式将 change worktree 记录设为 `active`,`current` 模式建立 current workspace 执行记录;
60
- 5. 当前代码使合同失效时停止并返回对应上游 owner。
56
+ 通过预检后:`required` Ticket 以 `purpose=ticket, operation=create|restore` 调用 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`;`current` Ticket 确认当前 branch/HEAD/dirty 状态和单 writer。Lead 设置 Ticket 为 `in_progress` 并按策略登记 active worktree 或 current workspace 记录。Direct Spec 不创建虚假 Ticket/worktree 状态。
61
57
 
62
- Direct Spec 模式验证用户批准、轻量合同和 current workspace 唯一写入 owner;不创建虚假 Ticket/worktree 状态。
63
-
64
- **完成标准**:按策略完成 workspace、基线、owners、权限与实际 Git 一致;current 模式只有一个 implementation writer 且 Ticket 串行可恢复。
58
+ **完成标准**:真实 workspace、基线、唯一 owners 和授权与预检一致;代码使合同失效时停止并返回上游 owner,current Ticket 严格串行。
65
59
 
66
60
  ### 2. Lead 决定自行实现或动态派单
67
61
 
@@ -80,13 +74,13 @@ Ticket 模式下,Lead 根据 Ticket 独立性、路径冲突、上下文、风
80
74
 
81
75
  加载 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`,检查模块、接口、类型、不变量、顺序/错误/性能语义、接缝、适配器、依赖分类、测试观察点和既有公共合同。
82
76
 
83
- 存在多个不改变上层契约的局部设计时,可运行 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`。超出 Ticket 或改变产品/公共合同/数据/兼容/安全时,返回架构审查、Grill、Spec 或 Ticket owner。陌生外部依赖使用 research Skill。
77
+ 存在多个不改变上层契约的局部设计时,可运行 `<Path>{roots.workflows}/specdev/common/rules/design-it-twice.md</Path>`。超出 Ticket 或改变产品/公共合同/数据/兼容/安全时,返回架构审查、Grill、Spec 或 Ticket owner。陌生外部依赖使用 research Skill。
84
78
 
85
79
  **完成标准**:局部设计与上层契约一致,稳定接缝和依赖策略明确。
86
80
 
87
81
  ### 4. TDD 红→绿垂直循环
88
82
 
89
- 加载 `<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>`。对每个验收行为或关键风险:
83
+ 加载 `<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/common/rules/code-commenting-rule.md</Path>`。对每个验收行为或关键风险:
90
84
 
91
85
  1. 选择公共接口或稳定接缝;
92
86
  2. 编写因目标行为缺失而失败的测试/验证并确认失败原因;
@@ -94,6 +88,8 @@ Ticket 模式下,Lead 根据 Ticket 独立性、路径冲突、上下文、风
94
88
  4. 运行定向非 E2E 验证;
95
89
  5. 保存 red/green 事实并进入下一条窄切片。
96
90
 
91
+ 涉及外部依赖、隔离策略或已有 Mock 时,先读取 `<Path>{roots.workflows}/specdev/I-implement/tdd-mocking.md</Path>`,再决定是否复用真实接缝或替身。
92
+
97
93
  不得删除测试、放宽断言、吞错、永久跳过或只验证 Mock 调用次数来制造绿色。
98
94
 
99
95
  新增或修改代码注释时,先判断信息能否由命名、类型或结构表达,并同步维护受行为变化影响的既有注释。
@@ -126,14 +122,7 @@ Direct Spec 模式由 Lead 在 current workspace 运行轻量合同要求的定
126
122
 
127
123
  ### 7. 最终集成与适用 E2E
128
124
 
129
- `required` Ticket 模式中,Lead 以 `purpose=ticket, operation=finalize` 调用 dev-worktree:
130
-
131
- 1. 在最新父分支的 Lead-owned candidate checkout 组合 source commit;
132
- 2. 运行受影响集成/回归、项目父状态检查和 Ticket 标记 required 的 E2E;
133
- 3. candidate 失败时父分支不动,Ticket 回 `in_progress`/`blocked`;
134
- 4. 父 HEAD 漂移时废弃本轮 candidate,基于最新父分支重建并重跑;
135
- 5. 全部通过后父分支 fast-forward 到 candidate/result SHA;
136
- 6. 重读父 HEAD/tree 和 ancestor 关系后,才允许 Ticket Done。
125
+ `required` Ticket 模式中,Lead 以 `purpose=ticket, operation=finalize` 调用 dev-worktree,并读取 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/references/finalize.md</Path>`。该参考唯一维护最新父分支 candidate 的组合、检查、失败/漂移、重建、fast-forward、回读与尝试上限过程。验证失败或父 HEAD 漂移,父分支不推进;不能凭来源检查通过标记 Done。
137
126
 
138
127
  E2E 是否需要由 Ticket/Goal Plan 的实际跨边界风险决定,不限于 UI;不适用必须记录原因。
139
128
 
@@ -164,29 +153,6 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
164
153
 
165
154
  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 只在独立授权时执行。
166
155
 
167
- ## 完成标准
168
-
169
- - Ticket 模式按策略完成 current workspace/direct-parent 或 worktree/implementation commit/candidate gate;Direct Spec 的轻量合同、current workspace checkpoint、双轴审查和最终验证完整;
170
- - current Ticket 的适用 E2E 由 Lead 在 current workspace 运行;required Ticket 的适用 E2E 由 Lead 在 parent-candidate 运行;Direct Spec 适用 E2E 由 Lead 在 current workspace 运行;
171
- - Lead 独立核对并写全部 SpecDev 工件;
172
- - Lead 与任何 implementation subagent 都已先读 Tickets Map、再读当前 Ticket 适用的项目 Skill;实现中发现的新匹配 Skill 已同步回 Map 并通过校验;
173
- - 重复失败或 integration attempt 上限只触发 Lead 复盘;没有 Evidence 中的原因、改变和 owner 决定,不得重置 attempts 或重复派发;
174
- - current Ticket 父分支只推进到通过的 direct-parent 验证 commit;required Ticket 父分支只推进到通过的 candidate;两者 Ticket Done 都必须与实际 Git 一致;Direct Spec 的完成状态与 current workspace 最终 checkpoint 一致;
175
- - 实际路径、验证、偏差和状态可由 Evidence 恢复;
176
- - validator 无 error。
177
-
178
- ## 子文件引用
179
-
180
- - 执行前预检:`<Path>{roots.workflows}/specdev/I-implement/execution-preflight.md</Path>`
181
- - 代码库设计:`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
182
- - Design It Twice:`<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`
183
- - 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>`
184
- - 代码注释:`<Path>{roots.workflows}/specdev/common/rules/code-commenting-rule.md</Path>`
185
- - Evidence:`<Path>{roots.workflows}/specdev/I-implement/evidence-template.md</Path>`
186
- - Agent 交付:`<Path>{roots.workflows}/specdev/common/skills/subagent-delivery/SKILL.md</Path>`
187
- - Worktree:`<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>`
188
- - 冲突处理:`<Path>{roots.workflows}/specdev/I-implement/merge-conflict-protocol.md</Path>`
189
-
190
156
  ## 计划型票扩展
191
157
 
192
158
  实施前按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 执行绑定;恢复或上游变化按 `<Path>{roots.workflows}/specdev/P-goal-plan/references/replan-and-recovery.md</Path>` 核验。不以读取替代调用,不因他人任务冲突暂停独立已授权工作。
@@ -15,3 +15,7 @@
15
15
  - 一个循环只有一个 seam、一个测试和一个最小实现;
16
16
  - 测试没有通过删除、跳过、吞错或放宽断言制造绿色;
17
17
  - review 前没有以“顺手重构”扩大切片。
18
+
19
+ ## 强制变异验证
20
+
21
+ 使用强制变异时,先保存基线 hash/diff,修改后核对实际执行文件的 diff 与测试选择。只有预期行为断言 red 才有效;编译错误、错测或变异未落地均不计。恢复原内容、复跑基线并核对 diff,把全过程记入 Evidence。诊断协议见 <Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>。
@@ -9,134 +9,33 @@ keywords: [初始化, 配置, status, tracking, 验证命令]
9
9
 
10
10
  # 初始化设置
11
11
 
12
- > 激活本 Work 后,先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`,再执行本入口。
12
+ 激活后读取 `<Path>{roots.workflows}/specdev/README.md</Path>`、`<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`。本 Work 只配置 SpecDev,不修改业务代码或迁移旧状态。
13
13
 
14
- 首次使用 SpecDev、状态根不存在或治理契约发生变化后运行。此 work 只初始化 SpecDev 的状态与配置,不修改项目业务代码。
14
+ ## 定位与探测
15
15
 
16
- ## 读取范围
16
+ 创建任何目录前,从 cwd 向上定位并打开 `<Path>{roots.state}/workspace.json</Path>`,验证 `path_base` 与 roots。只写声明的 `<Path>{roots.state}/specdev/</Path>`;不得把状态根默认展开成项目根 `.speculo`,嵌套安装的项目根 `.speculo/specdev` 非法。根目录未解析或未获授权时停止写入;持久化引用使用根变量,不把机器绝对路径写回模板。
17
17
 
18
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
19
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
20
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
18
+ 只读探测包管理、多工作区、构建/测试/类型/lint/CI、默认父分支、worktree、项目 Agent 指令及分支/提交/发布先例;记录根依赖清单、锁文件、共享 schema、迁移索引、全局导出/路由等高冲突资源。能从仓库发现的事实不重复问用户。
21
19
 
20
+ 确认项目根 `.gitignore` 已含 `specdev-worktree/` 或 `/specdev-worktree/`;该条目由 `speculo init` 唯一维护,缺失时停止并提示重新运行当前版本 CLI,不由 Work 补写。
22
21
 
23
- ## 规范输入
22
+ ## 选择初始化分支
24
23
 
25
- - 工作流运行合同:`<Path>{roots.workflows}/specdev/README.md</Path>`
26
- - 路径引用契约:`<Path>{roots.workflows}/specdev/common/rules/path-reference-contract.md</Path>`
27
- - 配置模板:`<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
28
- - 配置 Schema:`<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`
29
- - 全局状态模板:`<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>`
30
- - 全局状态 Schema:`<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`
31
- - Change 状态模板:`<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`
32
- - Change 状态 Schema:`<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>`
24
+ | 当前事实 | 执行 |
25
+ |---|---|
26
+ | 配置或状态不存在 | 读取 `<Path>{roots.workflows}/specdev/I-init-setup/references/first-setup.md</Path>`,仅在首次创建对应文件时读取 `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`、`<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>`、`<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>`;只创建缺失骨架;语言、并发、UI 数量与人工批准偏好仅补问尚未知项 |
27
+ | 已有有效配置和状态 | 对照 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`、`<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>` 验证并复用;保留 active、历史、永久知识和用户配置 |
28
+ | 用户要求修改既有配置 | 先验证并展示差异,再按授权更新;不存全局自动提交/集成开关 |
29
+ | JSON 无效、版本未知或契约冲突 | 保留原文件并报告 blocker;迁移只由 `speculo init` 使用 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 中登记的显式 migrator 完成 |
33
30
 
34
- ## 流程
31
+ ## 验收与返回
35
32
 
36
- ### 1. 解析根目录
33
+ 配置/全局状态必须可解析且满足 schema;状态、changes、永久 ADR/context/research、archive 与配置目录齐全,tracking/domain-layout 两份配置文档有效。验证命令必须有仓库或用户来源,未知值保留 `null`,不保存秘密。
37
34
 
38
- 创建任何状态目录之前,先从 cwd 向上定位并打开 `<Path>{roots.state}/workspace.json</Path>`,校验 `path_base` 与 `roots.*`。只在解析后的状态根下创建 specdev 目录;禁止在声明的状态根之外新建 `.speculo`。
39
-
40
- 确认:
41
-
42
- - 工作流根可解析为 `<Path>{roots.workflows}/specdev/</Path>`;
43
- - 状态根可解析为 `<Path>{roots.state}/specdev/</Path>`,且必须来自已打开的 `<Path>{roots.state}/workspace.json</Path>`;
44
- - 当前用户允许在状态根创建目录和工件。
45
-
46
- 嵌套安装反例:不得把状态根默认展开成项目根 `.speculo`。项目根 `.speculo/specdev` 非法;init 与 Grill 只写入声明的 `<Path>{roots.state}/specdev/</Path>`。
47
-
48
- 不得把真实绝对路径写回模板或治理文档;持久化引用继续使用根变量。
49
-
50
- ### 2. 探测项目事实
51
-
52
- 只读检查仓库根、包管理方式、构建脚本、测试脚本、静态检查、CI、默认分支、项目级 Agent 指令与 worktree 约定。能从仓库发现的事实直接记录,不询问用户。
53
-
54
- 至少探测:
55
-
56
- - 项目测试、类型检查、lint 和构建命令;
57
- - 是否存在多包或多工作区结构;
58
- - 默认父分支、Git worktree 支持和项目已有分支/提交约定;
59
- - 共享高冲突路径的类型,例如根依赖清单、锁文件、全局导出、共享 schema、迁移索引和全局路由;
60
- - 项目中已有的提交、分支和发布约定。
61
-
62
- 同时确认项目根 `.gitignore` 存在且包含 `specdev-worktree/`(`/specdev-worktree/` 视为等价)。该条目由 `speculo init` 单一维护;缺失时停止并提示用户以当前 Speculo 版本重新运行 `speculo init`,本 Work 不作为第二写入者修改它。
63
-
64
- ### 3. 询问不可发现偏好
65
-
66
- 仅在上下文未提供时询问:
67
-
68
- - 交互语言与持久化工件语言;
69
- - implementation subagent、集成尝试次数和 UI 设计候选上限(初始化时写入 config,Lead 不计入);
70
- - Deep Ticket 的迁移、发布和不可逆操作是否必须人工批准;
71
-
72
- 不询问可由仓库事实回答的文件位置、脚本名或默认分支。
73
-
74
- ### 4. 写入配置
75
-
76
- 以 `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>` 为模板写入 `<Path>{roots.state}/specdev/config.json</Path>`。
77
-
78
- 要求:
79
-
80
- - 字段满足 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>`;
81
- - 验证命令来自仓库事实或显式用户决定;
82
- - 未确认命令写 `null`,不得虚构;
83
- - 不写入令牌、凭据、Cookie、个人隐私或敏感环境变量值;
84
- - Ticket 的实现 commit 与本地 candidate integration 仍由具体 Goal Plan/I-implement 取得授权,不存为全局自动副作用开关。
85
-
86
- ### 5. 初始化目录与状态
87
-
88
- 创建或确认以下目录和文件:
89
-
90
- - 以 `<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>` 生成 `<Path>{roots.state}/specdev/status.json</Path>`
91
- - `<Path>{roots.state}/specdev/.config/</Path>`
92
- - `<Path>{roots.state}/specdev/changes/</Path>`
93
- - `<Path>{roots.state}/specdev/adr/</Path>`
94
- - `<Path>{roots.state}/specdev/context/</Path>`
95
- - `<Path>{roots.state}/specdev/research/</Path>`
96
- - `<Path>{roots.state}/specdev/archive/</Path>`
97
-
98
- 若全局状态或 config 已存在,先检查各自 `schema_version`。版本未知、JSON 不可解析或状态与当前 workflow 契约不一致时,停止当前 Work;不得在 Work 内迁移、兼容或猜测旧状态。`speculo init` 只会对 `<Path>{roots.workflows}/specdev/runtime-contract.json</Path>` 已登记且存在显式 migrator 的旧版本升级,其他冲突会保留当前安装并报告具体 blocker。只有状态不存在时才从当前 schema 模板创建。
99
-
100
- 从模板生成:
101
-
102
- - `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>` → `<Path>{roots.state}/specdev/.config/tracking.md</Path>`
103
- - `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>` → `<Path>{roots.state}/specdev/.config/domain-layout.md</Path>`
104
-
105
- 已有永久知识不得被初始化过程清空。已有配置应先验证和展示差异,再按用户授权更新。
106
-
107
- ### 6. 验证初始化结果
108
-
109
- 1. 解析 `<Path>{roots.state}/specdev/config.json</Path>` 和 `<Path>{roots.state}/specdev/status.json</Path>`;
110
- 2. 对照 `<Path>{roots.workflows}/specdev/common/schemas/config.schema.json</Path>` 与 `<Path>{roots.workflows}/specdev/common/schemas/status.schema.json</Path>`;
111
- 3. 确认 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>` 的字段与 `<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>` 对齐;实际创建 change 时替换模板占位符后再执行 Schema 验证;
112
- 4. 确认所有必需目录存在;
113
- 5. 确认两个配置文档均已从对应模板生成;
114
- 6. 确认项目根 `.gitignore` 已忽略 `specdev-worktree/`;
115
- 7. 运行:
35
+ 创建 change 前,对照 `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>` 与 `<Path>{roots.workflows}/specdev/common/schemas/change-status.schema.json</Path>`,真实创建时替换占位符后校验;纯初始化不创建虚假的 change。
116
36
 
117
37
  ```bash
118
38
  node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
119
39
  ```
120
40
 
121
- ### 7. 更新状态并汇报
122
-
123
- 若本 Work 由某个 active change 调用,开始时把该 entry 的 `current_work` 设为 `specdev/init-setup`,完成时将该 id 去重加入 `works_run` 并清空;纯工作流初始化没有 active change 时不创建虚假的 change。时间和验证结果写入本次回复或 change 自有 Evidence/LOG,不写入全局索引。向用户汇报:状态根、语言、验证命令、并发策略、人工批准策略和任何仍为 `null` 的配置项。
124
-
125
- ## 完成标准
126
-
127
- - `<Path>{roots.state}/specdev/config.json</Path>` 与 `<Path>{roots.state}/specdev/status.json</Path>` 可解析且满足 Schema;
128
- - 状态目录、永久知识目录和归档目录齐全;
129
- - 两个配置文档已就位;
130
- - 验证命令与并发规则有来源;
131
- - 项目根 `.gitignore` 已包含 `specdev-worktree/`;
132
- - 无敏感值被写入;
133
- - 包级自检无 error;
134
- - 存在调用 change 时,其 `works_run` 已包含本 work且 `current_work` 已清空;纯初始化时全局 active 保持真实为空。
135
-
136
- ## 子文件引用
137
-
138
- - `<Path>{roots.workflows}/specdev/I-init-setup/config-template.json</Path>`
139
- - `<Path>{roots.workflows}/specdev/I-init-setup/status-template.json</Path>`
140
- - `<Path>{roots.workflows}/specdev/I-init-setup/change-status-template.json</Path>`
141
- - `<Path>{roots.workflows}/specdev/I-init-setup/tracking-template.md</Path>`
142
- - `<Path>{roots.workflows}/specdev/I-init-setup/domain-layout-template.md</Path>`
41
+ 回读实际配置、状态、目录和忽略项后返回状态根、语言、验证命令、并发/批准策略、未确认配置与检查结果。若由 active change 调用,按原启动/交接合同登记 `current_work`,成功后去重更新 `works_run` 并清空;纯初始化不改已有 active 索引。时间和验证证据留在回复或调用 change 的 Evidence/LOG,不写进全局索引。
@@ -1,5 +1,5 @@
1
1
  {
2
- "schema_version": 5,
2
+ "schema_version": 6,
3
3
  "interaction_language": "zh-CN",
4
4
  "artifact_language": "zh-CN",
5
5
  "git": {
@@ -23,5 +23,9 @@
23
23
  "require_evidence": true,
24
24
  "ui_design_default_candidates": 3,
25
25
  "ui_design_max_candidates": 4
26
+ },
27
+ "github": {
28
+ "include_external_prs": false,
29
+ "labels": {}
26
30
  }
27
31
  }