@namewta/speculo 1.0.18 → 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.
- package/package.json +5 -2
- package/template/canonical/canonical-specdev-goal-plan.md +2 -2
- package/template/canonical/canonical-specdev-grill-with-docs.md +2 -2
- package/template/canonical/canonical-specdev-spec.md +11 -136
- package/template/canonical/canonical-specdev-tickets.md +2 -2
- package/template/canonical/canonical-specdev-wayfinder.md +2 -2
- package/template/commands/handoff.md +16 -0
- package/template/commands/retro.md +1 -1
- package/template/skills/github-npm-ops/references/issue-pr-triage.md +8 -0
- package/template/skills/speculo-retro/references/entry-procedure.md +19 -3
- package/template/skills/speculo-retro/references/issue-drafting-sop.md +3 -1
- package/template/workflows/learning/A-archive/A-archive.md +2 -5
- package/template/workflows/learning/A-assess-and-plan/A-assess-and-plan.md +2 -5
- package/template/workflows/learning/C-consolidate/C-consolidate.md +2 -5
- package/template/workflows/learning/G-goal/G-goal.md +5 -23
- package/template/workflows/learning/H-homework/H-homework.md +2 -5
- package/template/workflows/learning/I-init-setup/I-init-setup.md +4 -9
- package/template/workflows/learning/L-lesson/L-lesson.md +2 -5
- package/template/workflows/learning/Q-question/Q-question.md +16 -8
- package/template/workflows/learning/Q-question/inquiry-template.md +2 -0
- package/template/workflows/learning/Q-question/tools/validate-inquiry.mjs +112 -0
- package/template/workflows/learning/R-review/R-review.md +3 -6
- package/template/workflows/learning/README.md +2 -2
- package/template/workflows/learning/common/rules/knowledge-organization.md +1 -1
- package/template/workflows/learning/common/rules/mastery-policy.md +1 -1
- package/template/workflows/learning/common/skills/socratic-questioning/SKILL.md +1 -1
- package/template/workflows/ops/D-project-deploy/D-project-deploy.md +6 -2
- package/template/workflows/ops/H-host-manage/H-host-manage.md +10 -18
- package/template/workflows/ops/H-host-manage/references/host-profiles.md +21 -0
- package/template/workflows/ops/I-initialize/I-initialize.md +4 -4
- package/template/workflows/ops/README.md +22 -84
- package/template/workflows/ops/S-server-connect/S-server-connect.md +3 -3
- package/template/workflows/ops/V-inventory-view/V-inventory-view.md +2 -2
- package/template/workflows/ops/common/rules/deployment-layout.md +51 -0
- package/template/workflows/ops/common/rules/recovery.md +6 -0
- package/template/workflows/ops/common/rules/server-onboarding.md +6 -0
- package/template/workflows/person/M-mao-zedong-cognitive-os/M-mao-zedong-cognitive-os.md +13 -68
- package/template/workflows/person/S-steelman-deliberation/S-steelman-deliberation.md +11 -123
- package/template/workflows/person/S-steelman-deliberation/references/state-and-publication.md +86 -0
- package/template/workflows/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md +2 -17
- package/template/workflows/specdev/A-archive-and-consolidate/consolidation-interview.md +10 -1
- package/template/workflows/specdev/C-code-review/C-code-review.md +3 -14
- package/template/workflows/specdev/C-code-review/code-review-template.md +4 -0
- package/template/workflows/specdev/D-diagnose-bugs/D-diagnose-bugs.md +1 -23
- package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md +2 -2
- package/template/workflows/specdev/I-implement/I-implement.md +2 -2
- package/template/workflows/specdev/I-implement/evidence-template.md +8 -0
- package/template/workflows/specdev/I-implement/references/implementation-procedure.md +8 -42
- package/template/workflows/specdev/I-init-setup/I-init-setup.md +16 -117
- package/template/workflows/specdev/I-init-setup/references/first-setup.md +46 -0
- package/template/workflows/specdev/L-learn-change/L-learn-change.md +11 -89
- package/template/workflows/specdev/L-learn-change/references/lesson-format.md +47 -0
- package/template/workflows/specdev/P-goal-plan/P-goal-plan.md +2 -2
- package/template/workflows/specdev/P-prototype/P-prototype.md +2 -16
- package/template/workflows/specdev/R-review-architecture/R-review-architecture.md +19 -57
- package/template/workflows/specdev/R-review-architecture/architecture-review-template.md +2 -1
- package/template/workflows/specdev/R-review-architecture/references/selected-design.md +23 -0
- package/template/workflows/specdev/R-review-architecture/review-rubric.md +2 -2
- package/template/workflows/specdev/README.md +4 -4
- package/template/workflows/specdev/S-spec/S-spec.md +11 -138
- package/template/workflows/specdev/T-tickets/T-tickets.md +2 -2
- package/template/workflows/specdev/T-triage/T-triage.md +21 -136
- package/template/workflows/specdev/T-triage/intake-protocol.md +19 -0
- package/template/workflows/specdev/W-wayfinder/W-wayfinder.md +2 -2
- package/template/workflows/specdev/common/rules/deployment-handoff.md +23 -0
- package/template/workflows/specdev/common/skills/code-review/SKILL.md +5 -4
- package/template/workflows/specdev/common/skills/code-review/references/result-reuse.md +15 -0
|
@@ -11,18 +11,13 @@ keywords: [架构审查, 维护性, 浅模块, 深模块, 局部性, 杠杆, 接
|
|
|
11
11
|
|
|
12
12
|
> 激活本 Work 后,先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`,再执行本入口。
|
|
13
13
|
|
|
14
|
-
本 work
|
|
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
|
|
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
|
-
-
|
|
57
|
-
-
|
|
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
|
-
报告以“最佳推荐”结束;若没有高置信候选,就明确写
|
|
81
|
+
报告以“最佳推荐”结束;若没有高置信候选,就明确写 `无高置信候选`。报告阶段**不提出 interface**;返回候选和证据即可,不强制追加选择问题。
|
|
90
82
|
|
|
91
83
|
**完成标准**:每个候选字段完整、最佳推荐唯一或明确为空,Markdown 已原子写入并重读。
|
|
92
84
|
|
|
93
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
>
|
|
12
|
+
激活后读取 `<Path>{roots.workflows}/specdev/README.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`。本 Work 综合已有事实,定义为什么、为谁、系统应表现为何,不另开宽泛访谈,也不写逐文件施工计划。
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## 形成行为合同
|
|
15
15
|
|
|
16
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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,报告修改、验证结果和未完成项。规划完成不自动进入实现。
|
|
@@ -9,152 +9,37 @@ keywords: [triage, 摄入, import, issue, reconcile, publish, capture, close,
|
|
|
9
9
|
|
|
10
10
|
# 请求分诊
|
|
11
11
|
|
|
12
|
-
>
|
|
12
|
+
激活后先读 `<Path>{roots.workflows}/specdev/README.md</Path>` 与 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`。Triage 只管理来源冻结和远程投影;已清晰的本地请求直接进入适用 Work,不为路由创建来源工件。
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
## 选择模式
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
只读取选中模式的完整协议;协议中的授权、脱敏、去重、模板和失败恢复均为该模式的必需步骤。
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
| 模式与触发条件 | 必读协议 | 唯一产物/结果 |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| **intake**:冻结外部来源或用户要求来源审计 | `<Path>{roots.workflows}/specdev/T-triage/intake-protocol.md</Path>` | change 内 source、triage;分类、风险与下一 Work |
|
|
21
|
+
| **reconcile**:已完成 change 要通知并关闭支持的来源 Issue | `<Path>{roots.workflows}/specdev/T-triage/reconcile-protocol.md</Path>` | `external_action` 与远程完成回执 |
|
|
22
|
+
| **publish**:已完成 change 的 Ticket 要记入 GitHub | `<Path>{roots.workflows}/specdev/T-triage/publish-protocol.md</Path>` | `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>` 账本;标签 `specdev:published` |
|
|
23
|
+
| **capture**:尚未成 Change,只先记录仍 open 的记事项 | `<Path>{roots.workflows}/specdev/T-triage/capture-protocol.md</Path>` | workspace capture 账本;标签 `specdev:captured`;不关闭 Issue |
|
|
21
24
|
|
|
22
|
-
|
|
25
|
+
开发唯一权威始终是本地 source、triage、Spec、Ticket、Map、Goal Plan、Evidence 与状态,GitHub 不是开发 tracker。`external_action` 只拥有来源 Issue,`publish_action` 只拥有票级投影,capture 行 state 只拥有 inbox 记录;三者不互写。
|
|
23
26
|
|
|
24
|
-
##
|
|
27
|
+
## 定位、执行与写入边界
|
|
25
28
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
29
|
+
1. 从已打开的 workspace 解析 roots。intake 可创建或恢复 change;reconcile 与 publish 只选择已存在且满足本地完成门的 change,并读取 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`。多个候选真实消歧,不覆盖已冻结来源。
|
|
30
|
+
2. capture **既不创建也不选择 change**,不写 `current_work`,不读取 change-completion;只使用可缺省的 `<Path>{roots.state}/specdev/capture.md</Path>`。`mode=capture` 不写入 change 的 triage。
|
|
31
|
+
3. 其余三模式读取 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>` 和状态。`current_work` 为空才登记本 Work;他项占用先恢复或显式 handoff。publish 的轻量来源补建仅按其协议进行,不虚构 locator。
|
|
32
|
+
4. 按选中协议执行。远程写入必须有该动作的真实授权,未授权时远程写入为零;通过 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>` 操作。失败保留原账本与检查点,不以远程失败改写本地完成事实。
|
|
30
33
|
|
|
31
|
-
##
|
|
34
|
+
## 验证与返回
|
|
32
35
|
|
|
33
|
-
|
|
34
|
-
2. Intake 可以创建 change;reconcile 与 publish 必须选择一个已存在的 change。publish 的对象必须已 completed。capture 既不创建也不选择 change,不写 `current_work`,不加载 `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`。
|
|
35
|
-
3. 仅 intake、reconcile 与 publish:若该 change 的 `current_work` 为 null,设置为 `specdev/triage`;指向其他 Work 时先恢复或完成显式 handoff。capture 跳过本步。
|
|
36
|
-
4. 重读已有 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>` 与 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`,不覆盖已冻结的来源。publish 在本地源缺失这些文件时可以按协议补建轻量快照,仍不得虚构 GitHub locator。capture 不读、不写这些文件。
|
|
37
|
-
|
|
38
|
-
`external_action` 只描述源 Issue。`publish_action` 只描述票级发布投影。capture 行 state 只描述 inbox 记录。三者互不覆盖。未授权时远程写入为零。
|
|
39
|
-
|
|
40
|
-
## Intake
|
|
41
|
-
|
|
42
|
-
输入为远程 Issue、URL、项目相对文件、用户粘贴内容或当前对话时,加载 `<Path>{roots.workflows}/specdev/T-triage/intake-protocol.md</Path>`:
|
|
43
|
-
|
|
44
|
-
1. 按协议解析来源、查重、脱敏、冻结并计算内容 hash;使用 `<Path>{roots.workflows}/specdev/T-triage/source-template.md</Path>` 原子写入 `<Path>{roots.state}/specdev/changes/{change}/source.md</Path>`。
|
|
45
|
-
2. 按需读取永久 ADR/CONTEXT、当前 change 工件和相关代码事实;缺失的可选输入静默跳过。相似的已归档拒绝或 ADR 只展示,不自动 wontfix,也不回写源 Issue 标签。
|
|
46
|
-
3. 分类为 bug、feature、refactor、investigation、operations、documentation、review 或 mixed。对照见 `<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>`。
|
|
47
|
-
4. 评估影响、紧急度、事故半径、安全、数据、迁移和人工批准;把未知项分为可发现事实、decision-needed 和低影响实现细节。
|
|
48
|
-
5. 使用 `<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`。
|
|
49
|
-
6. 运行阶段校验并返回最小正确路线:
|
|
50
|
-
- 根因未知的 bug → `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`;
|
|
51
|
-
- 产品或架构决定未锁定 → `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`;
|
|
52
|
-
- 路径超出单次上下文 → `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`;
|
|
53
|
-
- 需要检测项目 UI、比较风格候选并固化可运行设计包 → `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>`;
|
|
54
|
-
- 外部行为明确 → `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`;
|
|
55
|
-
- 固定点 diff 或 PR 审查 → `<Path>{roots.workflows}/specdev/C-code-review/C-code-review.md</Path>`;
|
|
56
|
-
- 小型明确变更 → `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>` 或获批 Direct Spec。
|
|
57
|
-
|
|
58
|
-
只有目标、范围、验证、路径和风险全部明确且用户批准 Direct Spec 时,`ready_for_implementation` 才能为 true。
|
|
59
|
-
|
|
60
|
-
## Reconcile
|
|
61
|
-
|
|
62
|
-
本地 change 完成并需要关闭来源 Issue 时,加载:
|
|
63
|
-
|
|
64
|
-
- `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`;
|
|
65
|
-
- `<Path>{roots.workflows}/specdev/T-triage/reconcile-protocol.md</Path>`;
|
|
66
|
-
- `<Path>{roots.workflows}/specdev/T-triage/references/public-projection.md</Path>`。
|
|
67
|
-
|
|
68
|
-
按协议重验本地完成、生成最小外部摘要、展示准确目标和动作、取得本次明确授权,再调用 `<Path>{roots.skills}/github-npm-ops/SKILL.md</Path>`。成功时把 `external_action` 更新为 `closed`;部分或完全失败为 `close-failed` 并保留可重试检查点;用户明确不关闭时为 `waived`。任何结果都不改写本地完成事实。
|
|
69
|
-
|
|
70
|
-
Reconcile 成功或 waived 后返回 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>`。不支持关闭的来源使用 `not-applicable`,无需虚构 provider。若用户同时要求 publish,源 Issue 仍不是票 Issue。
|
|
71
|
-
|
|
72
|
-
## Publish
|
|
73
|
-
|
|
74
|
-
本地 change 完成、用户指定该 change 并要求把 Ticket 记到 GitHub 时,加载:
|
|
75
|
-
|
|
76
|
-
- `<Path>{roots.workflows}/specdev/common/rules/change-completion.md</Path>`;
|
|
77
|
-
- `<Path>{roots.workflows}/specdev/T-triage/publish-protocol.md</Path>`;
|
|
78
|
-
- `<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>`;
|
|
79
|
-
- `<Path>{roots.workflows}/specdev/T-triage/references/public-projection.md</Path>`。
|
|
80
|
-
|
|
81
|
-
按协议走硬门、确认表、dry-run,再调用 github-npm-ops 的 `issue-search` / `issue-create` / `issue-comment-close`。账本写 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>`。Issue 正文用 `<Path>{roots.workflows}/specdev/T-triage/issue-body-template.md</Path>`,关闭评论用 `<Path>{roots.workflows}/specdev/T-triage/close-comment-template.md</Path>`。
|
|
82
|
-
|
|
83
|
-
成功 `published`、用户放弃 `waived`,或从未请求的 `not-requested` 才允许归档。`pending` 与 `publish-failed` 挡住 Archive。下一站由用户指定:reconcile、A,或停止。
|
|
84
|
-
|
|
85
|
-
workspace 计数:
|
|
86
|
-
|
|
87
|
-
```bash
|
|
88
|
-
node <Path>{roots.workflows}/specdev/T-triage/tools/publish-status.mjs</Path> \
|
|
89
|
-
--state-root <Path>{roots.state}/specdev</Path>
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
## Capture
|
|
93
|
-
|
|
94
|
-
尚未成 Change、用户要求先把记事项写到 GitHub 时,加载:
|
|
95
|
-
|
|
96
|
-
- `<Path>{roots.workflows}/specdev/T-triage/capture-protocol.md</Path>`;
|
|
97
|
-
- `<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>`;
|
|
98
|
-
- `<Path>{roots.workflows}/specdev/T-triage/references/public-projection.md</Path>`。
|
|
99
|
-
|
|
100
|
-
按协议走硬门、确认表、dry-run,再调用 github-npm-ops 的 `issue-search` / `issue-create`。不调用 `issue-comment-close`。账本写 `<Path>{roots.state}/specdev/capture.md</Path>`。Issue 正文用 `<Path>{roots.workflows}/specdev/T-triage/issue-record-template.md</Path>`。默认 1 条记录对应一次未来 intake / 一个未来 Change。攒多了再处理:批量 capture,然后逐条 intake 或先走 W;不把多条 locator 写入同一个 source。
|
|
101
|
-
|
|
102
|
-
成功留下仍 open 的 inbox Issue。intake 消费到同一 locator 时把对应行标为 `intaken`。用户放弃为 `waived`。capture 不挡 Archive,因为没有 change 可归档。
|
|
103
|
-
|
|
104
|
-
workspace inbox 计数:
|
|
36
|
+
intake、reconcile、publish 校验当前 change;capture 只在账本已经存在时校验账本,不为校验创建它:
|
|
105
37
|
|
|
106
38
|
```bash
|
|
107
|
-
node <Path>{roots.workflows}/specdev/
|
|
108
|
-
|
|
39
|
+
node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --stage triage <Path>{roots.state}/specdev/changes/{change}</Path>
|
|
40
|
+
node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> --capture <Path>{roots.state}/specdev/capture.md</Path>
|
|
109
41
|
```
|
|
110
42
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
intake、reconcile 或 publish 运行:
|
|
114
|
-
|
|
115
|
-
```bash
|
|
116
|
-
node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
|
|
117
|
-
--stage triage \
|
|
118
|
-
<Path>{roots.state}/specdev/changes/{change}</Path>
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
capture 在账本存在时运行:
|
|
122
|
-
|
|
123
|
-
```bash
|
|
124
|
-
node <Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path> \
|
|
125
|
-
--capture <Path>{roots.state}/specdev/capture.md</Path>
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
缺失 `<Path>{roots.state}/specdev/capture.md</Path>` 合法,不要为了校验去创建它。
|
|
129
|
-
|
|
130
|
-
验证通过后,intake / reconcile / publish 原子重读 source、triage、publish(若请求过)和 change 状态;成功时将 `specdev/triage` 去重加入 `works_run` 并清空 `current_work`;可恢复失败保留 `current_work` 和具体 blocker。capture 不改任何 change 状态。
|
|
131
|
-
|
|
132
|
-
## 完成标准
|
|
133
|
-
|
|
134
|
-
- 来源已冻结为本地工件,原意未被改写,敏感值未持久化;
|
|
135
|
-
- 相同 locator 不会静默创建重复 change或覆盖已有快照;
|
|
136
|
-
- 分类、影响、风险、未知项和下一 Work 有证据;
|
|
137
|
-
- 开发权威完全位于本地 state;
|
|
138
|
-
- 未授权时远程写入为零;
|
|
139
|
-
- Reconcile 可从失败检查点幂等恢复;
|
|
140
|
-
- Publish 可从 `<Path>{roots.state}/specdev/changes/{change}/publish.md</Path>` 失败行幂等恢复,cancelled 默认 skip,本地源计入发布数;
|
|
141
|
-
- Capture 可从 `<Path>{roots.state}/specdev/capture.md</Path>` 失败行幂等恢复,Issue 保持 open,不创建 Change;
|
|
142
|
-
- 状态、验证结果和下一 Work 完整路径已返回。
|
|
143
|
-
|
|
144
|
-
## 子文件引用
|
|
43
|
+
回读选中模式的真实源、对应账本、状态和远程回执,报告结果、未完成项、验证命令与完整恢复路径。change 三模式成功才去重更新 `works_run` 并清空 `current_work`;可恢复失败保留当前 Work。capture 不修改任何 change 状态。
|
|
145
44
|
|
|
146
|
-
-
|
|
147
|
-
- Reconcile:`<Path>{roots.workflows}/specdev/T-triage/reconcile-protocol.md</Path>`
|
|
148
|
-
- Publish:`<Path>{roots.workflows}/specdev/T-triage/publish-protocol.md</Path>`
|
|
149
|
-
- Capture:`<Path>{roots.workflows}/specdev/T-triage/capture-protocol.md</Path>`
|
|
150
|
-
- Source 模板:`<Path>{roots.workflows}/specdev/T-triage/source-template.md</Path>`
|
|
151
|
-
- Triage 模板:`<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>`
|
|
152
|
-
- Publish 模板:`<Path>{roots.workflows}/specdev/T-triage/publish-template.md</Path>`
|
|
153
|
-
- Capture 模板:`<Path>{roots.workflows}/specdev/T-triage/capture-template.md</Path>`
|
|
154
|
-
- 分类映射:`<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>`
|
|
155
|
-
- 公共投影:`<Path>{roots.workflows}/specdev/T-triage/references/public-projection.md</Path>`
|
|
156
|
-
- Issue 正文:`<Path>{roots.workflows}/specdev/T-triage/issue-body-template.md</Path>`
|
|
157
|
-
- 记事项正文:`<Path>{roots.workflows}/specdev/T-triage/issue-record-template.md</Path>`
|
|
158
|
-
- 关闭评论:`<Path>{roots.workflows}/specdev/T-triage/close-comment-template.md</Path>`
|
|
159
|
-
- 发布计数:`<Path>{roots.workflows}/specdev/T-triage/tools/publish-status.mjs</Path>`
|
|
160
|
-
- inbox 计数:`<Path>{roots.workflows}/specdev/T-triage/tools/capture-status.mjs</Path>`
|
|
45
|
+
intake 返回协议选出的 Work。reconcile 的 `closed | waived | not-applicable`、publish 的 `not-requested | published | waived` 才满足各自归档门;`pending-close | close-failed` 或 `pending | publish-failed` 分别恢复原模式。归档交 `<Path>{roots.workflows}/specdev/A-archive-and-consolidate/A-archive-and-consolidate.md</Path>`,不自动合并两类 Issue。capture 成功返回仍 open 的记录;以后逐条 intake,或由 W 探索,capture 本身不挡归档。
|
|
@@ -36,3 +36,22 @@ GitHub 来源保存 title、body、author、state、labels、created/updated 和
|
|
|
36
36
|
- 相似归档/ADR 项已展示或明确无匹配;
|
|
37
37
|
- 失败没有生成伪造或不完整的 Ready source;
|
|
38
38
|
- 源 Issue 标签未被本协议修改。
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
## 分诊与交接
|
|
42
|
+
|
|
43
|
+
来源冻结后,按命中条目读取永久 ADR/CONTEXT、当前 change 工件和代码事实;可选输入缺失不补造。使用 `<Path>{roots.workflows}/specdev/T-triage/references/classification-map.md</Path>` 分类为 bug、feature、refactor、investigation、operations、documentation、review 或 mixed。评估影响、紧急度、事故半径、安全、数据、迁移与人工批准,把未知项区分为可发现事实、待用户决定和低影响实现细节。
|
|
44
|
+
|
|
45
|
+
使用 `<Path>{roots.workflows}/specdev/T-triage/triage-template.md</Path>` 写入 `<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`。按以下条件选择下一 Work,而不是要求每个请求经过全链:
|
|
46
|
+
|
|
47
|
+
| 条件 | 下一 Work |
|
|
48
|
+
|---|---|
|
|
49
|
+
| 根因未知的 bug | `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>` |
|
|
50
|
+
| 产品或架构高影响决定未锁定 | `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>` |
|
|
51
|
+
| 大需求的 change 边界或路线尚不清晰 | `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>` |
|
|
52
|
+
| 检测 UI、比较风格并固化设计包 | `<Path>{roots.workflows}/specdev/P-prototype/P-prototype.md</Path>` |
|
|
53
|
+
| 外部行为明确,需要验收合同 | `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>` |
|
|
54
|
+
| 固定点 diff 或 PR 审查 | `<Path>{roots.workflows}/specdev/C-code-review/C-code-review.md</Path>` |
|
|
55
|
+
| 小型明确变更 | `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`,或获批 Direct Spec |
|
|
56
|
+
|
|
57
|
+
只有目标、范围、验证、路径和风险全部明确且用户批准 Direct Spec,`ready_for_implementation` 才能为 true。相似的归档拒绝或 ADR 只作为决策证据,不自动 wontfix 或回写远程标签。
|
|
@@ -15,9 +15,9 @@ W 位于 change 形成之前:Initiative → 候选 change → 各自 Grill →
|
|
|
15
15
|
|
|
16
16
|
## 读取范围
|
|
17
17
|
|
|
18
|
-
先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path
|
|
18
|
+
先读 `<Path>{roots.workflows}/specdev/common/rules/activation-and-memory.md</Path>`;先从共享地图定位当前调查 ID,再读当前问题、直接依赖及其 solution comment 原文;共享答案只引用 provenance。低分辨率地图不缓存所有开放票正文。
|
|
19
19
|
|
|
20
|
-
##
|
|
20
|
+
## 按当前调查选择参考
|
|
21
21
|
|
|
22
22
|
| 当前需要 | 按需读取 |
|
|
23
23
|
|---|---|
|