@namewta/speculo 1.0.17 → 1.0.19

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 (88) hide show
  1. package/package.json +5 -2
  2. package/template/canonical/canonical-specdev-goal-plan.md +2 -2
  3. package/template/canonical/canonical-specdev-grill-with-docs.md +2 -2
  4. package/template/canonical/canonical-specdev-spec.md +11 -136
  5. package/template/canonical/canonical-specdev-tickets.md +2 -2
  6. package/template/canonical/canonical-specdev-wayfinder.md +2 -2
  7. package/template/commands/handoff.md +16 -0
  8. package/template/commands/retro.md +1 -1
  9. package/template/skills/github-npm-ops/references/issue-pr-triage.md +8 -0
  10. package/template/skills/speculo-retro/references/entry-procedure.md +19 -3
  11. package/template/skills/speculo-retro/references/issue-drafting-sop.md +3 -1
  12. package/template/workflows/learning/A-archive/A-archive.md +2 -5
  13. package/template/workflows/learning/A-assess-and-plan/A-assess-and-plan.md +2 -5
  14. package/template/workflows/learning/C-consolidate/C-consolidate.md +2 -5
  15. package/template/workflows/learning/G-goal/G-goal.md +5 -23
  16. package/template/workflows/learning/H-homework/H-homework.md +2 -5
  17. package/template/workflows/learning/I-init-setup/I-init-setup.md +4 -9
  18. package/template/workflows/learning/L-lesson/L-lesson.md +2 -5
  19. package/template/workflows/learning/Q-question/Q-question.md +16 -8
  20. package/template/workflows/learning/Q-question/inquiry-template.md +2 -0
  21. package/template/workflows/learning/Q-question/tools/validate-inquiry.mjs +112 -0
  22. package/template/workflows/learning/R-review/R-review.md +3 -6
  23. package/template/workflows/learning/README.md +2 -2
  24. package/template/workflows/learning/common/rules/knowledge-organization.md +1 -1
  25. package/template/workflows/learning/common/rules/mastery-policy.md +1 -1
  26. package/template/workflows/learning/common/skills/socratic-questioning/SKILL.md +1 -1
  27. package/template/workflows/ops/D-project-deploy/D-project-deploy.md +15 -9
  28. package/template/workflows/ops/H-host-manage/H-host-manage.md +14 -21
  29. package/template/workflows/ops/H-host-manage/references/host-profiles.md +21 -0
  30. package/template/workflows/ops/I-initialize/I-initialize.md +7 -7
  31. package/template/workflows/ops/INDEX.md +20 -16
  32. package/template/workflows/ops/README.md +29 -73
  33. package/template/workflows/ops/S-server-connect/S-server-connect.md +28 -0
  34. package/template/workflows/ops/V-inventory-view/V-inventory-view.md +30 -0
  35. package/template/workflows/ops/common/CAPABILITIES.md +22 -15
  36. package/template/workflows/ops/common/WORKSPACE-USAGE.md +78 -0
  37. package/template/workflows/ops/common/examples/task-host.example.json +64 -0
  38. package/template/workflows/ops/common/rules/activation-and-memory.md +5 -3
  39. package/template/workflows/ops/common/rules/deployment-layout.md +51 -0
  40. package/template/workflows/ops/common/rules/inventory-and-records.md +55 -0
  41. package/template/workflows/ops/common/rules/recovery.md +6 -0
  42. package/template/workflows/ops/common/rules/research-and-decisions.md +18 -0
  43. package/template/workflows/ops/common/rules/server-onboarding.md +27 -0
  44. package/template/workflows/ops/common/rules/workspace-and-authorization.md +39 -0
  45. package/template/workflows/ops/common/schemas/fleet-view.schema.json +487 -0
  46. package/template/workflows/ops/common/schemas/server-check.schema.json +95 -0
  47. package/template/workflows/ops/common/schemas/task-request.schema.json +138 -0
  48. package/template/workflows/ops/common/templates/FLEET.html +61 -0
  49. package/template/workflows/ops/common/tests/test_ops_workspace.mjs +246 -0
  50. package/template/workflows/ops/common/tools/ops.mjs +5 -3
  51. package/template/workflows/ops/common/tools/opslib/fleet.mjs +155 -0
  52. package/template/workflows/ops/common/tools/opslib/server_checks.mjs +149 -0
  53. package/template/workflows/ops/common/tools/opslib/tasks.mjs +313 -0
  54. package/template/workflows/ops/common/tools/opslib/workspace.mjs +107 -0
  55. package/template/workflows/ops/common/tools/opslib/workspace_cli.mjs +80 -0
  56. package/template/workflows/ops/common/tools/validate-ops.mjs +11 -8
  57. package/template/workflows/ops/manifest.json +43 -7
  58. package/template/workflows/person/M-mao-zedong-cognitive-os/M-mao-zedong-cognitive-os.md +13 -68
  59. package/template/workflows/person/S-steelman-deliberation/S-steelman-deliberation.md +11 -123
  60. package/template/workflows/person/S-steelman-deliberation/references/state-and-publication.md +86 -0
  61. package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md +2 -17
  62. package/template/workflows/specdev/A-archive-and-consolidate/consolidation-interview.md +10 -1
  63. package/template/workflows/specdev/C-code-review/C-code-review.md +3 -14
  64. package/template/workflows/specdev/C-code-review/code-review-template.md +4 -0
  65. package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md +1 -23
  66. package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md +2 -2
  67. package/template/workflows/specdev/I-implement/I-implement.md +2 -2
  68. package/template/workflows/specdev/I-implement/evidence-template.md +8 -0
  69. package/template/workflows/specdev/I-implement/references/implementation-procedure.md +8 -42
  70. package/template/workflows/specdev/I-init-setup/I-init-setup.md +16 -117
  71. package/template/workflows/specdev/I-init-setup/references/first-setup.md +46 -0
  72. package/template/workflows/specdev/L-learn-change/L-learn-change.md +11 -89
  73. package/template/workflows/specdev/L-learn-change/references/lesson-format.md +47 -0
  74. package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +2 -2
  75. package/template/workflows/specdev/P-prototype/P-prototype.md +2 -16
  76. package/template/workflows/specdev/R-review-architecture/R-review-architecture.md +19 -57
  77. package/template/workflows/specdev/R-review-architecture/architecture-review-template.md +2 -1
  78. package/template/workflows/specdev/R-review-architecture/references/selected-design.md +23 -0
  79. package/template/workflows/specdev/R-review-architecture/review-rubric.md +2 -2
  80. package/template/workflows/specdev/README.md +4 -4
  81. package/template/workflows/specdev/S-spec/S-spec.md +11 -138
  82. package/template/workflows/specdev/T-tickets/T-tickets.md +2 -2
  83. package/template/workflows/specdev/T-triage/T-triage.md +21 -136
  84. package/template/workflows/specdev/T-triage/intake-protocol.md +19 -0
  85. package/template/workflows/specdev/W-wayfinder/W-wayfinder.md +2 -2
  86. package/template/workflows/specdev/common/rules/deployment-handoff.md +23 -0
  87. package/template/workflows/specdev/common/skills/code-review/SKILL.md +5 -4
  88. package/template/workflows/specdev/common/skills/code-review/references/result-reuse.md +15 -0
@@ -9,98 +9,20 @@ keywords: [learn-change, change 学习, 开发后提问, 零基础, 大一新生
9
9
 
10
10
  # Change 学习:给零基础新生的图解
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>`。只解释当前 change 已验证的实现与测试事实,不作产品/架构决定或授予实现权限。
13
13
 
14
- ## 读取范围
15
-
16
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
17
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
18
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
19
-
20
-
21
- ## 读者与职责
22
-
23
- 读者是刚入大学、没有专业背景(零专业背景)的新生。读者能理解日常因果和简单流程,但不应被假定知道代码、网络、数学或行业背景。
24
-
25
- 本 Work 用于在 change 开发完成后回答与该 change 有关的问题。它只解释,不作产品决定、架构决定或实现授权;它把当前 change 中已验证的工件、实现和测试事实写成可恢复的 Markdown 图解。图比段落更先出现,文字只负责读懂图。
26
-
27
- ```text
28
- 已完成 change 的已验证事实
29
- |
30
- v
31
- 用户关于 change 的问题
32
- |
33
- v
34
- ASCII 全图 + 分步图 + 简短说明
35
- |
36
- v
37
- learning/01_<topic>.md、02_<topic>.md、...
38
- |
39
- v
40
- learning/index.md(图解目录)
41
- ```
42
-
43
- 主题:`$ARGUMENTS`
44
-
45
- ## 输出格式
46
-
47
- 在当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内原子写入一份新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`,并原子更新索引 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>`。这些产物属于 SpecDev change,不写入 `<Path>{roots.state}/learning/</Path>`。文档必须是纯 Markdown,不生成 HTML、CSS、SVG、图片链接或浏览器专属交互。
48
-
49
- `<number>` 是两位起始、持续递增的序号:先读取索引和同目录已有的图解文件,取最大序号加一,因此第一次为 `01`,下一次为 `02`;不为旧文件重编号。`<topic>` 是主题的简短、可作文件名的标签,可使用中文、字母、数字、`-` 或 `_`,但不能含空格、`/`、`\\` 或 `..`。同主题再次解释也创建新编号文件。
50
-
51
- 索引是唯一目录,使用下列 Markdown 表格;每新增一份图解就在表末追加一行,并保留既有行。文件列只写同目录的文件名:
52
-
53
- ```markdown
54
- # Change 学习图解索引
55
-
56
- | 编号 | 文件 | 主题 | 简介 |
57
- | --- | --- | --- | --- |
58
- | 01 | 01_<topic>.md | <主题> | <一句话说明它解释什么> |
59
- ```
60
-
61
- 按主题选择最贴切的图,但优先用多个短小 ASCII 图代替长文字:
62
-
63
- ```text
64
- 结构图:
65
- [系统]
66
- |
67
- +-- [部件 A]
68
- +-- [部件 B]
14
+ ## 执行
69
15
 
70
- 数据流图:
71
- [输入] -> [处理] -> [结果]
16
+ 1. **选择现有 change**:使用用户指定或唯一未归档 change;没有时返回缺失输入,不创建空 change。只读归档不追加学习材料。按原交接规则登记 `current_work=specdev/learn-change`,不把 `change_status=completed` 重新打开为开发中。
17
+ 2. **确定主题**:使用 `$ARGUMENTS` 调用参数或用户最新问题;缺少时只询问主题。读者是刚入大学、零专业背景的新生,先确定“它是什么、为什么需要、怎样流动或被调用”三个答案。
18
+ 3. **定位事实**:按主题读取 Source、Spec、Ticket、Evidence、review、实际代码/测试与可靠来源。区分已验证事实、类比与未知;旧计划和实现冲突时明确差异,以当前代码、测试、Evidence 为实现事实,不让类比代替证据。
19
+ 4. **生成与保存**:读取 `<Path>{roots.workflows}/specdev/L-learn-change/references/lesson-format.md</Path>` 的完整格式和命名合同。先画 ASCII 全图,再按实际关系画短小结构/数据/调用/状态图;用短句解释箭头,术语先日常解释再给专业名字。验证零背景读者能复述三个答案;不能时拆图或换词,不灌长文。
20
+ 5. **追加而非覆盖**:从 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 及同目录真实图解的最大编号取下一号;先原子创建 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` 新图解,再更新索引并回读。重讲同主题仍新增编号,保留旧文件、原顺序和全部历史行。产物仅为纯 Markdown/ASCII,不生成 HTML、CSS、SVG、图片或浏览器依赖,不写 `<Path>{roots.state}/learning/</Path>`、生产代码、永久知识或远程系统。
72
21
 
73
- 调用流图:
74
- [用户动作] -> [入口] -> [服务] -> [回应]
22
+ ## 验收与恢复
75
23
 
76
- 状态变化图:
77
- [等待] -> [进行中] -> [完成]
24
+ ```bash
25
+ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage learn-change <Path>{roots.state}/specdev/changes/{change}</Path>
78
26
  ```
79
27
 
80
- 每份图解至少包含以下四节:
81
-
82
- 1. `## 先看全图`:一个能说清“谁和谁有关”的 ASCII 图。
83
- 2. `## 一步一步看`:按箭头顺序解释。流程、数据或调用会移动时,再给对应的 ASCII 图。
84
- 3. `## 术语小词典`:只保留读图必需的词。每个词先用日常语言解释,再给它的专业名字。例如:`临时便签(缓存)`,意思是“把常用结果先放在手边,下一次不用重新找”。
85
- 4. `## 你现在能复述什么`:用短句归纳“它是什么、为什么需要它、它怎样流动或被调用”。
86
-
87
- 图中的方框名称使用普通名词和动词,不用缩写;箭头必须有方向。一个图只讲一个问题。确有边界、失败或例外时,单独画一张小图说明,不把它塞进主图。
88
-
89
- ## 执行
90
-
91
- 1. 按 `<Path>{roots.workflows}/specdev/README.md</Path>` 读取全局状态和当前 change 状态。只选择用户指定或唯一未归档的现有 change;没有可用 change 时说明必须先完成或指定一个 SpecDev change,不创建空 change。已归档 change 保持只读,不在归档目录追加学习产物。`current_work` 为空时设为 `specdev/learn-change`;若指向其他 Work,先完成显式交接。`change_status=completed` 不因本 Work 被重新打开为开发中。
92
- 2. 将调用中的 `$ARGUMENTS` 解析为主题;直接提出的问题以用户最新消息为主题。主题缺失时只询问问题或主题,不猜测。先写下读者要带走的三个答案:它是什么、为什么需要它、它怎样流动或被调用。
93
- 3. 按需读取当前 change 的 Source、Spec、Ticket、Evidence、review、项目实现、测试和可靠来源。区分已验证事实、便于理解的类比和未知处;实现事实与旧计划冲突时以当前代码、测试和 Evidence 为准,并显式指出差异。类比只能帮助理解,不能替代事实或掩盖边界。
94
- 4. 先画 `先看全图`,再按实际关系补充结构图、数据流图、调用流图或状态变化图。每张图旁只用短句解释箭头;避免长段落、术语堆叠、缩写和先备知识。
95
- 5. 首次使用术语时,先写日常解释,再在括号中给专业名字。读完后从读者角度检查:没有背景知识的人能否仅靠图和短句复述三个答案;若不能,拆图或替换术语,不增加大段说明。
96
- 6. 读取 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内已有图解文件。从两者的最大序号计算下一个编号,先原子创建新的图解文件,再原子更新索引;不覆盖、重命名或重排已有图解。重读确认新文件是 Markdown,包含四个必需章节、至少一个 ASCII 图且没有 HTML 标记或图片依赖;索引的文件名、主题和简介都与新文件对应。
97
- 7. 运行 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage learn-change`。成功后把 `specdev/learn-change` 去重加入 `works_run`,清空 `current_work`,并返回新 Markdown 与索引的完整路径;失败时保留 `current_work` 和阻塞原因,便于恢复,但不改变 change 的开发完成状态。
98
-
99
- ## 完成标准
100
-
101
- - `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>` 存在,按序列出每份图解的编号、文件、主题和简介;每个文件名都对应同目录真实文件。
102
- - 新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>` 存在,是纯 Markdown,并含有全部四个必需章节和至少一个 ASCII 图;编号比既有最大编号大一,旧文件未被重排或覆盖。
103
- - 文档面向刚上大一、没有专业背景的读者;用图和短句回答当前 change 的问题,而不是把专业长文换成更简单的字。
104
- - 图解覆盖主题需要的结构、数据流、调用流或状态变化;能画图的地方优先画图,且每张图的箭头方向与事实一致。
105
- - 术语首次出现前有日常解释;类比不把读者带向相反结论;计划与最终实现的差异没有被隐藏。
106
- - 状态已原子更新;所有学习产物只写入当前 SpecDev change 的 `learning/` namespace,没有修改项目代码、永久知识、Learning workflow state 或远程系统。
28
+ 图解符合格式参考的四节、至少一个 ASCII 图和连续编号;索引指向真实新文件且主题/简介一致,箭头方向与事实相符。验证通过才去重更新 `works_run`、清空 `current_work`,返回新图解和索引完整路径。失败保留恢复位置与原因,不改变 change 原有开发完成状态。
@@ -0,0 +1,47 @@
1
+ # Change 学习图解格式
2
+
3
+ 写图解与分配编号时读取;这是产物格式权威,不是另一套学习状态。
4
+
5
+ ## 输出格式
6
+
7
+ 在当前 change 的 `<Path>{roots.state}/specdev/changes/{change}/learning/</Path>` 内原子写入一份新的 `<Path>{roots.state}/specdev/changes/{change}/learning/{number}_{topic}.md</Path>`,并原子更新索引 `<Path>{roots.state}/specdev/changes/{change}/learning/index.md</Path>`。这些产物属于 SpecDev change,不写入 `<Path>{roots.state}/learning/</Path>`。文档必须是纯 Markdown,不生成 HTML、CSS、SVG、图片链接或浏览器专属交互。
8
+
9
+ `<number>` 是两位起始、持续递增的序号:先读取索引和同目录已有的图解文件,取最大序号加一,因此第一次为 `01`,下一次为 `02`;不为旧文件重编号。`<topic>` 是主题的简短、可作文件名的标签,可使用中文、字母、数字、`-` 或 `_`,但不能含空格、`/`、`\\` 或 `..`。同主题再次解释也创建新编号文件。
10
+
11
+ 索引是唯一目录,使用下列 Markdown 表格;每新增一份图解就在表末追加一行,并保留既有行。文件列只写同目录的文件名:
12
+
13
+ ```markdown
14
+ # Change 学习图解索引
15
+
16
+ | 编号 | 文件 | 主题 | 简介 |
17
+ | --- | --- | --- | --- |
18
+ | 01 | 01_<topic>.md | <主题> | <一句话说明它解释什么> |
19
+ ```
20
+
21
+ 按主题选择最贴切的图,但优先用多个短小 ASCII 图代替长文字:
22
+
23
+ ```text
24
+ 结构图:
25
+ [系统]
26
+ |
27
+ +-- [部件 A]
28
+ +-- [部件 B]
29
+
30
+ 数据流图:
31
+ [输入] -> [处理] -> [结果]
32
+
33
+ 调用流图:
34
+ [用户动作] -> [入口] -> [服务] -> [回应]
35
+
36
+ 状态变化图:
37
+ [等待] -> [进行中] -> [完成]
38
+ ```
39
+
40
+ 每份图解至少包含以下四节:
41
+
42
+ 1. `## 先看全图`:一个能说清“谁和谁有关”的 ASCII 图。
43
+ 2. `## 一步一步看`:按箭头顺序解释。流程、数据或调用会移动时,再给对应的 ASCII 图。
44
+ 3. `## 术语小词典`:只保留读图必需的词。每个词先用日常语言解释,再给它的专业名字。例如:`临时便签(缓存)`,意思是“把常用结果先放在手边,下一次不用重新找”。
45
+ 4. `## 你现在能复述什么`:用短句归纳“它是什么、为什么需要它、它怎样流动或被调用”。
46
+
47
+ 图中的方框名称使用普通名词和动词,不用缩写;箭头必须有方向。一个图只讲一个问题。确有边界、失败或例外时,单独画一张小图说明,不把它塞进主图。
@@ -13,9 +13,9 @@ keywords: [goal, 目标, plan, run, resume, replan, verify, Lead]
13
13
 
14
14
  ## 读取范围
15
15
 
16
- 先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,定位用户指定的 change 或 map,再读状态、当前 map 和所选模式。只有进入 frontier 的 Ticket、命中的项目 Skill、Gate 与恢复证据需要展开;不默认通读所有 Ticket 或永久索引。
16
+ 先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,定位用户指定的 change 或 map,再读状态、当前 map 和所选模式。每次只展开实际进入 frontier 的 Ticket、直接依赖 Evidence、命中的项目 Skill、当前 Gate 与恢复证据;不默认通读所有 Ticket 或永久索引。
17
17
 
18
- ## 模式与权威
18
+ ## 按意图选择模式与权威
19
19
 
20
20
  | 用户意图 | 模式 | 必须按需读取 |
21
21
  |---|---|---|
@@ -13,12 +13,7 @@ keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互,
13
13
 
14
14
  本 Work 的主导词是**设计定向**:先从项目事实识别现状,再让用户看到基于功能而非流行色推荐的候选,最后把选择固化为既可阅读又可运行的 UI 设计包。P 不修改生产 UI;后续 S、Tickets 和 I 以设计包为视觉与交互权威。
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
 
@@ -36,7 +31,7 @@ P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/</
36
31
  3. **建立功能候选**:读取 `<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`,依据产品任务、平台和信息密度从八种风格及六种布局中推荐 2-4 个候选。每个候选写明适合原因、需要保留/调整/替换的现有事实、参考项目和迁移成本。
37
32
  4. **逐项选择并持久化**:加载 `<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`。每轮只处理一个决策层;每个答案立即写回设计系统主文档并重读。高影响偏好未确认时保持 `status: selecting`,不得自行标记 Ready。
38
33
  5. **生成可视对照与最终原型**:加载 `<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`。为每个候选生成独立 comparison variant,再生成 comparison 索引。用户确认或明确组合后,把最终 HTML/CSS/JS 作为具名代码块写入设计系统主文档,再物化到 final 目录。
39
- 6. **验证并封板**:运行 `<Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> --check` 和 `<Path>{roots.workflows}/specdev/P-prototype/tools/validate-design-package.mjs</Path>`;随后运行 SpecDev `--stage prototype`。全部通过且选择闭合后设置 `status: ready`,更新 `works_run` 并清空 `current_work`。缺少项目事实或用户决定时设置 `blocked` 并保留恢复位置。
34
+ 6. **验证并封板**:运行 `<Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> --check` 和 `<Path>{roots.workflows}/specdev/P-prototype/tools/validate-design-package.mjs</Path>`;随后运行 SpecDev `--stage prototype`。对照 `<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`,全部通过且选择闭合后设置 `status: ready`,更新 `works_run` 并清空 `current_work`。缺少项目事实或用户决定时设置 `blocked` 并保留恢复位置。
40
35
  7. **返回路由**:返回设计包、comparison 和 final 的完整路径、验证命令与结果、未决问题和下一 Work。需要补足产品决定时返回 G;需要写外部行为合同返回 S;需要拆实施工作返回 Tickets;已有 Ready Ticket 才返回 I。Wayfinder 调用时只把设计包与 comparison locator 写入对应 solution comment。
41
36
 
42
37
  ## 完成标准
@@ -48,12 +43,3 @@ P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/</
48
43
  - 字体、间距、圆角、色彩、层级、控件状态、异步反馈、响应式、键盘、focus 和 reduced motion 均有明确合同。
49
44
  - Markdown 代码块与 `final/` 文件逐字一致,schema、局部校验和 SpecDev stage 校验全部通过。
50
45
  - 设计包不包含机器绝对路径、敏感值、生产数据写入、发布动作或未授权的生产实现。
51
-
52
- ## 子文件引用
53
-
54
- - 检测:`<Path>{roots.workflows}/specdev/P-prototype/detect-existing-style.md</Path>`,仅在步骤 2 加载。
55
- - 选择:`<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`,仅在步骤 4 加载。
56
- - 生成:`<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`,仅在步骤 5 加载。
57
- - 模板:`<Path>{roots.workflows}/specdev/P-prototype/design-system-template.md</Path>`,创建设计包时加载。
58
- - 设计库:`<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`,建立候选或查具体规则时渐进读取。
59
- - Schema:`<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`。
@@ -11,18 +11,13 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
11
11
 
12
12
  > 激活本 Work 后,先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`,再执行本入口。
13
13
 
14
- 本 work 以热核级维护性标准审查当前范围:先找会让 module 变浅的结构性坏味道,再找能删掉复杂性的 `code-judo` 机会,再找真正值得深化的 seam。行为正确不构成通过;如果存在更简单的路径,就优先把复杂性删掉,而不是搬家。
14
+ 本 work 根据可定位的代码压力审查当前范围:先找会让 module 变浅的结构性坏味道,再找能删掉复杂性的 `code-judo` 机会,再找真正值得深化的 seam。行为正确不构成通过;如果存在更简单的路径,就优先把复杂性删掉,而不是搬家。
15
15
 
16
16
  本 work 只审查、呈现和访谈,不直接修改产品代码。报告阶段只产出 Markdown 决策记录,不生成 HTML。
17
17
 
18
- 本 work 的候选筛选、排序和删除测试见 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`。审查语言必须使用 module、interface、depth、seam、adapter、leverage、locality。
18
+ 本 work 的候选筛选、排序和删除测试见 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`。沿用 CONTEXT 与共享设计词汇(module、interface、depth、seam、adapter、leverage、locality)准确表达含义,不为机械出现英文而牺牲理解。
19
19
 
20
- ## 读取范围
21
-
22
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
23
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`、`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 和 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
24
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
25
- 4. 用户指定范围优先于 Git 热点;若未指定,则从最近 churn、重复编辑和报错/回归轨迹中找出最值得审查的 module。
20
+ 激活时读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前步骤定位输入和证据。
26
21
 
27
22
  ## 输入与产物
28
23
 
@@ -43,7 +38,14 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
43
38
 
44
39
  每个候选都必须说明:files、structural problem、code-judo move、deleted complexity、dependency class、strength、ADR conflict、interview state 和 user conclusion。文件若因为本次变化接近或超过 1k lines,必须显式标注 decomposition pressure,不得默默吞掉。
45
40
 
46
- ## 流程
41
+ ## 选择交付分支
42
+
43
+ - `report`(默认):用户只请求 review/扫描时完成下方探索与报告,候选保持 `unselected`;没有候选是有效结果,不要求用户先选方案才完成报告。
44
+ - `selected-design`:只有用户已经选择一个候选并请求深入设计,才加载 `<Path>{roots.workflows}/specdev/R-review-architecture/references/selected-design.md</Path>`。输入是可回读报告和所选候选;来源漂移先核对影响,不用旧结论代替当前代码。
45
+
46
+ 两分支均不修改生产代码,报告不授权访谈、建票或实施。
47
+
48
+ ## Report 流程
47
49
 
48
50
  ### 1. 探索
49
51
 
@@ -53,18 +55,8 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
53
55
  - 否则翻阅足够长的 `git log --oneline`,找出反复出现的 files、call sites 和 test surfaces;
54
56
  - 变更散落、没有明确热点时才扩大搜索范围;
55
57
  - 只接受能通过删除测试的候选:删掉该 module 后,复杂性应集中或消失,而不是换一个地方继续蔓延;
56
- - 优先挑出结构性回归、重复 special cases、wrong-layer logic、thin wrappers、identity abstractions、type boundary drift、sequential orchestration 和 file-size/decomposition pressure;
57
- - 如果一个更 canonical 的 helper 已经存在,优先复用它;如果 proposal 只是 rearrange complexity,不算候选。
58
-
59
- 首先阅读项目领域词汇和接触区域的 ADR。然后有机探索 codebase,注意哪里会让 maintenance knowledge 分散:
60
-
61
- - 哪些 module 是 shallow,interface 几乎与 implementation 一样复杂;
62
- - 哪些 seam 正在 leak;
63
- - 哪些纯函数只是为了可测试性被拆出,但 bug 实际藏在缺少 locality 的调用方式中;
64
- - 哪些模块因为 ad-hoc conditionals、mode flags 或 one-off branches 变得更 spaghetti;
65
- - 哪些区域正在把 feature logic 泄漏进 shared path 或 canonical helper 之外;
66
- - 哪些结构已经逼近或超过 1k lines,应该先 decomposition 再 review;
67
- - 哪些 orchestration 本可以并行或更 atomic,却被无谓串行化。
58
+ - 逐项应用 `<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>` 的结构压力、删除测试与排序规则;
59
+ - 先读取项目领域词汇及当前区域 ADR;探索真实调用和测试表面,过滤仅 rearrange complexity 的提案。
68
60
 
69
61
  对每个怀疑对象应用删除测试。候选必须有真实路径、调用或测试证据,并说明不做的实际后果。与业务目标、近期变化压力、测试改善或风险降低无关的候选过滤掉。若没有任何候选通过这条线,明确写出“没有高置信候选”,不要为了填表而硬造一个。
70
62
 
@@ -86,46 +78,16 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
86
78
  - **依赖类别**——`in-process | local-substitutable | ports & adapters | mock`;
87
79
  - **ADR 冲突**——只在摩擦真实到值得重审时显示警告。
88
80
 
89
- 报告以“最佳推荐”结束;若没有高置信候选,就明确写 `无高置信候选`。此时**不提出 interface**,只询问用户想探索哪一个候选,或者为何没有候选。
81
+ 报告以“最佳推荐”结束;若没有高置信候选,就明确写 `无高置信候选`。报告阶段**不提出 interface**;返回候选和证据即可,不强制追加选择问题。
90
82
 
91
83
  **完成标准**:每个候选字段完整、最佳推荐唯一或明确为空,Markdown 已原子写入并重读。
92
84
 
93
- ### 3. 访谈用户选择的一个候选
94
-
95
- 用户选择候选后,调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`,用完整 frontier 遍历约束、依赖、deep module 形状、seam 后面的内容和保留测试。
96
-
97
- 决策结晶时保持领域模型同步:
98
-
99
- - 新概念加入 change CONTEXT;永久 CONTEXT 不存在时延迟到归档提升;
100
- - 模糊术语当场精炼;
101
- - 用户的选择同时难以逆转、没有上下文会令人惊讶且来自真实权衡时,询问是否记录 ADR;任一条件不满足就留在 LOG/Ticket,不制造 ADR;
102
- - 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`;
103
- - 如果候选最终只是把复杂性搬家,而不是删掉它,在访谈中直接回退,不把它升级成 Ticket。
104
-
105
- 将选择、访谈状态与结论同步到 Markdown;每次运行只访谈用户选择的候选,不批量迫使用户决定所有卡片。
106
-
107
- **完成标准**:被选候选的设计树达到共识或明确 blocked;领域词汇、LOG、ADR 和审查报告一致。
108
-
109
- ### 4. 转化为执行工作
110
-
111
- 只有被接受且有具体变更压力的提案进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。加载 `<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`,按 Prefactor、Standard 或 Deep/expand-contract 建立 Ready 治理;只有能删除复杂性的提案才继续,纯重排和 thin wrapper 不进入 Ticket。
85
+ ## 分支完成、状态与返回
112
86
 
113
- ## 完成标准
87
+ `report` 完成条件:范围有依据;高置信候选满足删除测试且每项有当前文件/调用/测试证据、前后对比、收益、强度和 ADR 冲突处理;最佳推荐唯一或明确为“无高置信候选”;Markdown 已原子写入并回读。未选择或拒绝的候选不变成 Ticket。
114
88
 
115
- - 范围来自用户方向或 Git 热点,未进行无边界扫描;
116
- - 每个候选通过删除测试并有真实代码压力;
117
- - 领域使用 CONTEXT 词汇,架构严格使用共享词汇;
118
- - Markdown 决策记录可重读;
119
- - 每个候选有前后对比、强度、收益和 ADR 冲突处理;
120
- - 报告阶段没有提前设计 interface;
121
- - 用户选择的一个候选完成完整 frontier 访谈;
122
- - 接受项进入 Ticket 治理,没有直接修改产品代码;
123
- - 没有把结构性弱候选包装成最佳推荐。
89
+ `selected-design` 完成条件:用户选定的一个候选完成参考中的完整 frontier 访谈,或明确 blocked/rejected;只有接受且达成共识的方案才按原 Ticket 治理交接。其他候选保持未选择,不批量要求决定。
124
90
 
125
- ## 子文件引用
91
+ 按本分支真实结果更新 Work 状态:成功才把本 Work 去重加入 `works_run` 并清空 `current_work`,blocked 保留恢复键和原因。报告完成不是产品交付;只有请求本来以非实现审查为终点且满足 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`,该终点 owner 才可关闭 change。
126
92
 
127
- - 共享设计规则:`<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>`
128
- - 证据与验证:`<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`
129
- - 审查准则:`<Path>{roots.workflows}/specdev/R-review-architecture/review-rubric.md</Path>`
130
- - Markdown 模板:`<Path>{roots.workflows}/specdev/R-review-architecture/architecture-review-template.md</Path>`
131
- - 提案转 Ticket:`<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`
93
+ 返回分支、报告完整路径、审查范围/排除范围、代码证据、候选结论、实际验证与未验证项;有选择时再返回相应设计树/下一 Work。结构检查不证明设计判断正确,不能把弱候选包装成最佳推荐。
@@ -64,5 +64,6 @@ status: draft
64
64
 
65
65
  ## 5. 下一步
66
66
 
67
- - 报告生成后询问用户选择一个候选,不批量访谈。
67
+ - 当前请求:report / selected-design。report 到此完成,访谈状态可为 unselected;无高置信候选也可交付。
68
+ - 用户选择原文与候选 ID:仅 selected-design 填写;未选择时不虚构结论、不自动转票。
68
69
  - 达成共识的接受项进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。
@@ -0,0 +1,23 @@
1
+ # 已选架构候选的设计与转票
2
+
3
+ 用户选定一个候选后读取;保持审查报告和 change 内决策同步,不修改生产代码。
4
+
5
+ ### 3. 访谈用户选择的一个候选
6
+
7
+ 用户选择候选后,调用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`,用完整 frontier 遍历约束、依赖、deep module 形状、seam 后面的内容和保留测试。
8
+
9
+ 决策结晶时保持领域模型同步:
10
+
11
+ - 新概念加入 change CONTEXT;永久 CONTEXT 不存在时延迟到归档提升;
12
+ - 模糊术语当场精炼;
13
+ - 用户的选择同时难以逆转、没有上下文会令人惊讶且来自真实权衡时,询问是否记录 ADR;任一条件不满足就留在 LOG/Ticket,不制造 ADR;
14
+ - 替代 interface 需要探索时使用 `<Path>{roots.workflows}/specdev/I-implement/design-it-twice.md</Path>`;
15
+ - 如果候选最终只是把复杂性搬家,而不是删掉它,在访谈中直接回退,不把它升级成 Ticket。
16
+
17
+ 将选择、访谈状态与结论同步到 Markdown;每次运行只访谈用户选择的候选,不批量迫使用户决定所有卡片。
18
+
19
+ **完成标准**:被选候选的设计树达到共识或明确 blocked;领域词汇、LOG、ADR 和审查报告一致。
20
+
21
+ ### 4. 转化为执行工作
22
+
23
+ 只有被接受且有具体变更压力的提案进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。加载 `<Path>{roots.workflows}/specdev/R-review-architecture/proposal-to-ticket.md</Path>`,按 Prefactor、Standard 或 Deep/expand-contract 建立 Ready 治理;只有能删除复杂性的提案才继续,纯重排和 thin wrapper 不进入 Ticket。
@@ -1,8 +1,8 @@
1
1
  # 架构审查准则
2
2
 
3
- 本准则只在 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 激活时生效。它把热核级维护性标准转成候选筛选和排序规则。
3
+ 本准则只在 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 激活时生效。它把实际维护压力转成候选筛选和排序规则;每个结论都要有路径、调用或测试证据。
4
4
 
5
- 使用 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的术语:module、interface、depth、seam、adapter、leverage、locality。描述架构时不要滑向更弱的替代词。
5
+ 使用 `<Path>{roots.workflows}/specdev/common/rules/codebase-design.md</Path>` 的术语:module、interface、depth、seam、adapter、leverage、locality。优先保持项目共享含义;中文解释可与专业词并列,不要求机械复述每个词。
6
6
 
7
7
  ## 重点观察
8
8
 
@@ -14,7 +14,7 @@
14
14
 
15
15
  Ticket frontmatter 拥有本票状态、依赖、写集与 Skill 调用绑定;普通 map 是背景/路由/图投影;Goal Plan 拥有 Gate、workspace 和恢复决策。多 change 父 tickets-map 只指向原 Implementation Map/Plan,不复制状态。一个未完成 child 仍只能归属于一个未完成父 Goal。
16
16
 
17
- 具体职责与冲突裁决读取 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`;新增调用合同读取 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>`。
17
+ 发生职责或事实冲突时读取 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>`;T 绑定、P 调度或 I 执行 Skill 时读取 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>`。
18
18
 
19
19
  ## 持久化约定
20
20
 
@@ -24,9 +24,9 @@ CLI 初始化和刷新保持原 namespace、三方配置合并、schema migrator
24
24
 
25
25
  ## 启动协议
26
26
 
27
- 1. 先打开 `<Path>{roots.state}/workspace.json</Path>` 解析 roots,再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;定位相关 entry 后回读必要原文,不默认整读索引。不得把状态根默认展开成项目根 `.speculo`;项目根 `.speculo/specdev` 非法。
27
+ 1. 先打开 `<Path>{roots.state}/workspace.json</Path>` 解析 roots,再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;定位相关 entry 后回读必要原文,不默认整读索引。
28
28
  2. 读取 `<Path>{roots.state}/specdev/config.json</Path>`;不存在时使用 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。保留已知配置,不重复询问。
29
- 3. 从 `<Path>{roots.state}/specdev/status.json</Path>` 定位用户指定或唯一 active change;多个候选需要真实消歧,无候选按原规则创建。
29
+ 3. 纯初始化和 T-triage capture 按各自无 change 分支执行;其他 Work 从 `<Path>{roots.state}/specdev/status.json</Path>` 定位用户指定或唯一 active change;多个候选需要真实消歧,无候选按原规则创建。
30
30
  4. 读取 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`;恢复、创建或状态修改时加载上述状态细则。child 归属未完成父 Goal 时读取对应父 Map/Plan,不接管或覆盖其 owner。
31
31
  5. current_work 非空则恢复或显式 handoff;暂停保留恢复键,成功才去重更新 works_run 并清空。其他任务冲突只暂停受影响分支,继续独立、已授权工作。
32
32
  6. 按 Work/模式读取必要参考,完成产物、运行验证、回读真实源与状态后再推进。全局状态仅更新本任务 active/archived 索引。
@@ -83,4 +83,4 @@ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --
83
83
  node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --self-check
84
84
  ```
85
85
 
86
- 支持 triage、diagnosis、grill、spec、tickets、goal-plan、implement、learn-change、review、prototype、wayfinder、complete。Goal 总控通过 P 的 map-control 参考使用只读控制器;它不授权或自动执行。完成转换必须读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`,票全 done 不替代整体验收。
86
+ 支持 triage、diagnosis、grill、spec、tickets、goal-plan、implement、learn-change、review、prototype、wayfinder、complete。Goal 总控通过 P 的 map-control 参考使用只读控制器;它不授权或自动执行。只有进行完成转换时必须读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`,票全 done 不替代整体验收。
@@ -9,149 +9,22 @@ keywords: [spec, PRD, 用户故事, 验收合同, 接缝, 范围, readiness]
9
9
 
10
10
  # 编写 Spec
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>`。本 Work 综合已有事实,定义为什么、为谁、系统应表现为何,不另开宽泛访谈,也不写逐文件施工计划。
13
13
 
14
- 本 work 以“综合已有上下文”为主,不启动宽泛访谈。它保留原有的代码库探索、领域词汇、ADR 约束、测试接缝设计和用户确认能力,但将确认限制为真正影响外部行为或验证的高价值问题。
14
+ ## 形成行为合同
15
15
 
16
- Spec 决定“为什么、为谁、系统应表现为何”。它可以锁定影响公共接口、数据、兼容、安全或验收的实现约束,但不写逐文件施工计划。
16
+ 1. **Grounding**:定位用户目标与当前代码、测试、接口、schema、配置和运行事实。按存在情况定位 change 的来源、分诊、诊断、LOG、CONTEXT、ADR 及相关永久领域词汇/决策;只回读命中原文,可选工件缺失静默跳过,不当作已确认事实。按 `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>` 区分可发现事实、高影响偏好和可逆实现细节;冲突按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 返回权威 owner。
17
+ 2. **关闭必要决定**:只确认会改变外部行为、接口、数据、兼容、安全、迁移、发布或验收的高价值问题。广泛取舍未定时返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`;陌生外部依赖或版本行为通过 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>` 查证。不虚构错误码、性能阈值、法规或迁移政策。
18
+ 3. **写入合同**:以 `<Path>{roots.workflows}/specdev/S-spec/spec-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`。模板拥有问题/用户/成功、正常/边界/失败/角色/状态行为、IN/REUSE/OUT、保持项、接口数据与 NFR 的完整结构及 `US-### / AC-### / NFR-### / DEC-### / OOS-###` 稳定编号。实现约束仅锁定会影响公共合同、兼容、安全或验收的决定。
19
+ 4. **绑定验证接缝**:优先复用稳定接缝,通常从用户端到端行为、公共 API/CLI、事件/集成、稳定单元接缝选择;按实际风险与项目先例决定,不机械追求最高测试层级。每个接缝注明入口类型/位置、触发方式、可观察结果、覆盖 AC 和实际测试先例/命令。选择显著改变可测试性、事故半径或范围时聚焦确认;可由已有代码推导时记录依据即可。证据遵守 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
20
+ 5. **Readiness**:对照 `<Path>{roots.workflows}/specdev/S-spec/spec-readiness.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/schemas/spec.schema.json</Path>`。高影响未决问题使 `ready_for_tickets: false`;低影响、可逆默认值可作为带验证方式的显式假设。每个 AC 必须可观察、可判定、绑定接缝;不适用影响写明理由。
17
21
 
18
- ## 读取范围
19
-
20
- 1. 先读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与当前 Work 的状态入口。
21
- 2. 再读取 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`,按当前分支、状态和关键词定位最小相关工件。
22
- 3. 只在本 Work 明确要求恢复、冲突、执行安全或归档证据时扩展为全量读取;缺少匹配证据或 owner/gateway 时停止受影响分支。
23
-
24
-
25
- ## 输入
26
-
27
- 按存在情况读取:
28
-
29
- - `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`
30
- - `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
31
- - `<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
32
- - `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
33
- - `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
34
- - `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
35
- - `<Path>{roots.state}/specdev/context/</Path>`
36
- - `<Path>{roots.state}/specdev/adr/</Path>`
37
- - 当前代码、测试、接口、schema、配置和运行事实。
38
-
39
- 不存在的可选工件静默跳过,不得把缺失内容当作已确认事实。
40
-
41
- ## 流程
42
-
43
- ### 1. Grounding 与事实探索
44
-
45
- 1. 汇总用户目标、受众、问题、限制和已有决定;
46
- 2. 只读探索相关代码、测试、配置、schema 和相邻实现;
47
- 3. 使用 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 与 `<Path>{roots.state}/specdev/context/</Path>` 的术语,不自创冲突名称;
48
- 4. 使用 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 与 `<Path>{roots.state}/specdev/adr/</Path>` 的已接受决策;
49
- 5. 按 `<Path>{roots.workflows}/specdev/common/rules/planning-principles.md</Path>` 区分可发现事实、高影响偏好和低影响实现细节;
50
- 6. 按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 处理冲突;
51
- 7. 外部依赖、标准或版本行为不清楚时使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。
52
-
53
- 广泛的产品或架构取舍仍未确定时,返回 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`;不要在 Spec 中用猜测补齐。
54
-
55
- ### 2. 定义问题、用户和成功
56
-
57
- 从用户或调用者视角写明:
58
-
59
- - 当前问题与影响;
60
- - 目标用户、调用者或运营角色;
61
- - 主要场景和现有痛点;
62
- - 成功状态与可观察结果;
63
- - 明确非目标。
64
-
65
- 目标不能只写“新增模块”“修改接口”或“完成 Ticket”。
66
-
67
- ### 3. 定义外部行为与范围
68
-
69
- 写明:
70
-
71
- - 解决方案摘要;
72
- - 正常路径;
73
- - 边界和失败路径;
74
- - 稳定错误行为;
75
- - 状态转换和不变量;
76
- - IN、REUSE、OUT;
77
- - 需要保持的既有行为;
78
- - 公共接口、数据、安全、迁移和运维影响。
79
-
80
- 局部文件组织、辅助函数和逐行实现不进入 Spec。
81
-
82
- ### 4. 设计验证接缝
83
-
84
- 优先复用现有稳定接缝。通常优先顺序是用户端到端行为、公共 API 或 CLI、事件或集成接缝、稳定单元接缝;实际层级由风险和项目先例决定,不机械追求最高层测试。
85
-
86
- 每个接缝写明:
87
-
88
- - 入口位置和类型;
89
- - 触发方式;
90
- - 可观察结果;
91
- - 覆盖哪些验收合同;
92
- - 现有测试先例或命令。
93
-
94
- 若接缝选择会显著改变可测试性、事故半径或实现范围,向用户做一次聚焦确认;接缝可由代码和已有测试明确推导时,直接采用并记录依据,不为形式提问。
95
-
96
- 证据规则见 `<Path>{roots.workflows}/specdev/common/rules/evidence-and-verification.md</Path>`。
97
-
98
- ### 5. 编写 Spec
99
-
100
- 使用 `<Path>{roots.workflows}/specdev/S-spec/spec-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`。
101
-
102
- 稳定编号:
103
-
104
- - `US-###`:用户故事;
105
- - `AC-###`:验收合同;
106
- - `NFR-###`:非功能要求;
107
- - `DEC-###`:已锁定实现约束;
108
- - `OOS-###`:明确超出范围。
109
-
110
- 不得虚构错误码、性能阈值、schema、迁移政策、法规或合规要求。项目代码证据使用项目相对 Path 标签。
111
-
112
- ### 6. Readiness Review
113
-
114
- 加载 `<Path>{roots.workflows}/specdev/S-spec/spec-readiness.md</Path>` 检查 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`。
115
-
116
- 任何会改变以下内容的未决问题都会使 `ready_for_tickets: false`:
117
-
118
- - 外部行为和范围;
119
- - 公共接口或数据;
120
- - 安全、隐私、资金或数据完整性;
121
- - 兼容、迁移和发布约束;
122
- - 验收合同或验证接缝。
123
-
124
- 低影响、可逆实现默认值可以作为显式假设,但必须有验证方式。
125
-
126
- ### 7. 发布与路由
127
-
128
- 1. 对照 `<Path>{roots.workflows}/specdev/common/schemas/spec.schema.json</Path>`;
129
- 2. 运行:
22
+ ## 验证、状态与交接
130
23
 
131
24
  ```bash
132
- node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
133
- --stage spec \
134
- <Path>{roots.state}/specdev/changes/{change}</Path>
25
+ node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage spec --repo <project-root> <Path>{roots.state}/specdev/changes/{change}</Path>
135
26
  ```
136
27
 
137
- 3. 更新 `<Path>{roots.state}/specdev/status.json</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`;
138
- 4. 汇报主要用户故事、验收合同、范围、验证接缝、风险和 Ready 状态;
139
- 5. 返回 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、Ready 状态及下一 Work 的完整路径;
140
- 6. 只有用户请求或工作流显式串联时,进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。
141
-
142
- ## 完成标准
143
-
144
- - `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>` 已按模板写入;
145
- - 问题、目标用户、外部行为、范围和非目标明确;
146
- - 用户故事覆盖主要、边界、错误、角色和状态场景;
147
- - 每个验收合同可观察、可判定并绑定验证接缝;
148
- - 公共接口、数据、兼容、安全和迁移已决定或明确不适用;
149
- - 高影响未决问题与 `ready_for_tickets` 一致;
150
- - 不包含逐文件施工计划;
151
- - Spec、Ready 状态和下一 Work 路径已返回;
152
- - 状态和用户摘要已更新。
153
-
154
- ## 子文件引用
28
+ 回读真实 Spec、Ready 结论与状态,按激活合同只更新本 change 与全局索引的所属项。返回 Spec 完整路径、主要行为/验收合同、范围、验证接缝、风险、高影响缺口和验证结果。成功完成本 Work 才更新 `works_run` 并清空 `current_work`;可恢复失败保留入口。
155
29
 
156
- - Spec 模板:`<Path>{roots.workflows}/specdev/S-spec/spec-template.md</Path>`
157
- - Ready 检查:`<Path>{roots.workflows}/specdev/S-spec/spec-readiness.md</Path>`
30
+ 只有用户请求或工作流已显式串联时才进入 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`;产出 Ready Spec 本身不授权实施。
@@ -17,13 +17,13 @@ keywords: [ticket, Plan Mode, 垂直切片, Skill绑定, DAG]
17
17
 
18
18
  先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;按相关条目定位上游 Spec/ADR/CONTEXT、代码与项目 Agent 指令,再回读当前拆分所需原文。只枚举 Skill 的元数据与触发路由,不默认展开全部技能。
19
19
 
20
- ## 主流程
20
+ ## 从合同到可执行票
21
21
 
22
22
  1. **输入与范围**:确认目标、非目标、用户指定数量、验收合同和未知项。高影响未决问题回到 G;无 Ready Spec 时,只有用户材料已等价覆盖全部合同才可规划。
23
23
  2. **地形与绑定**:定位真实可维护源、调用方、测试接缝和 Skill 根。按 `<Path>{roots.workflows}/specdev/common/rules/skill-invocation.md</Path>` 为每票解析实际 Skill ID、入口摘要、调用阶段、输入、产出与失败动作;没有适用项目 Skill 时记录扫描证据,不造名称。
24
24
  3. **垂直切片**:需要具体拆分时读取 `<Path>{roots.workflows}/specdev/T-tickets/references/planning-procedure.md</Path>` 与 `<Path>{roots.workflows}/specdev/T-tickets/decomposition-rules.md</Path>`。保留 Prefactor、Expand → Migrate → Contract 和真实 DAG,不按技术层制造空价值任务。
25
25
  4. **写 Plan**:使用 `<Path>{roots.workflows}/specdev/T-tickets/ticket-template.md</Path>`。Lite 仅减少不适用说明,不删用户数量、权限、验收或停止条件。所有新增票使用 `plan_contract_version: 1`,旧票按迁移协议补齐后再执行。
26
- 5. **写总控**:使用 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`,记录共同背景、Skill 最低路由、合同覆盖、依赖和明确控制入口;状态仍从票投影。依赖、路径与语义共享资源都需检查。
26
+ 5. **写总控**:使用 `<Path>{roots.workflows}/specdev/T-tickets/tickets-map-template.md</Path>`,记录共同背景、Skill 最低路由、合同覆盖、依赖和明确控制入口;状态仍从票投影。按 AC 反查至少一个负责验证的 Ticket,暴露未覆盖和重复所有权;依赖环、路径重叠与语义共享资源分别检查,不能用“可并行”文字替代实际 DAG/写集。
27
27
  6. **Definition of Ready**:读取 `<Path>{roots.workflows}/specdev/T-tickets/ticket-readiness.md</Path>`,并调用 `<Path>{roots.workflows}/specdev/common/skills/plan-quality-review/SKILL.md</Path>`。缺失引用、必需 Skill、可运行验收或权限边界,当前票不可 ready。
28
28
  7. **与用户核对**:展示全部票、可观察产物、依赖、深度、风险、Skill 和未决问题。保留用户要求的交付数量;已授权自主规划且无关键未知时不重复请求形式确认。
29
29
  8. **验证、回读和交付**:按下述命令检查,再回读真实 Ticket/Map,报告修改、验证结果和未完成项。规划完成不自动进入实现。