@haaaiawd/anws 2.2.1 → 2.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +39 -226
  2. package/bin/cli.js +112 -112
  3. package/lib/changelog.js +258 -258
  4. package/lib/copy.js +116 -109
  5. package/lib/diff.js +11 -0
  6. package/lib/manifest.js +3 -1
  7. package/lib/update.js +319 -319
  8. package/package.json +2 -1
  9. package/templates/.agents/skills/anws-system/SKILL.md +108 -106
  10. package/templates/.agents/skills/code-reviewer/SKILL.md +63 -288
  11. package/templates/.agents/skills/concept-modeler/SKILL.md +179 -176
  12. package/templates/.agents/skills/craft-authoring/SKILL.md +123 -0
  13. package/templates/.agents/skills/design-reviewer/SKILL.md +190 -176
  14. package/templates/.agents/skills/e2e-testing-guide/SKILL.md +204 -0
  15. package/templates/.agents/skills/nexus-mapper/SKILL.md +321 -306
  16. package/templates/.agents/skills/report-template/SKILL.md +92 -85
  17. package/templates/.agents/skills/runtime-inspector/SKILL.md +12 -12
  18. package/templates/.agents/skills/sequential-thinking/SKILL.md +225 -216
  19. package/templates/.agents/skills/spec-writer/SKILL.md +9 -9
  20. package/templates/.agents/skills/spec-writer/references/prd_template.md +6 -6
  21. package/templates/.agents/skills/system-architect/SKILL.md +678 -620
  22. package/templates/.agents/skills/system-designer/SKILL.md +599 -532
  23. package/templates/.agents/skills/system-designer/references/system-design-detail-template.md +5 -5
  24. package/templates/.agents/skills/system-designer/references/system-design-template.md +45 -45
  25. package/templates/.agents/skills/task-planner/SKILL.md +601 -531
  26. package/templates/.agents/skills/task-planner/references/TASK_TEMPLATE.md +97 -97
  27. package/templates/.agents/skills/task-reviewer/SKILL.md +388 -363
  28. package/templates/.agents/skills/tech-evaluator/SKILL.md +144 -135
  29. package/templates/.agents/skills/tech-evaluator/references/ADR_TEMPLATE.md +80 -78
  30. package/templates/.agents/workflows/blueprint.md +130 -130
  31. package/templates/.agents/workflows/challenge.md +450 -491
  32. package/templates/.agents/workflows/change.md +215 -238
  33. package/templates/.agents/workflows/craft.md +243 -664
  34. package/templates/.agents/workflows/design-system.md +32 -32
  35. package/templates/.agents/workflows/explore.md +78 -49
  36. package/templates/.agents/workflows/forge.md +455 -422
  37. package/templates/.agents/workflows/genesis.md +127 -180
  38. package/templates/.agents/workflows/probe.md +243 -238
  39. package/templates/.agents/workflows/quickstart.md +23 -38
  40. package/templates/.agents/workflows/upgrade.md +10 -10
  41. package/templates/AGENTS.md +49 -34
@@ -1,151 +1,156 @@
1
1
  ---
2
- description: "处理当前版本内的受控变更与 task 调整,并在需要时升级到 /genesis。适用于已进入 /forge 编码阶段后的文档、契约、测试与任务回流。"
3
- ---
2
+
3
+ ## description: "处理当前版本内的受控变更与 task 调整,并在需要时升级到 /genesis。适用于已进入 /forge 编码阶段后的文档、契约、测试与任务回流。"
4
4
 
5
5
  # /change
6
6
 
7
- <phase_context>
8
7
  你是 **CHANGE MANAGER (变更管理师)**。
9
8
 
10
- **核心使命**:
11
- - 处理当前版本内的**受控变更、契约回流与 task 调整**。**仅在已进入 `/forge` 编码阶段后使用**;若尚未开始编码,直接修改相关文档即可,无需走本工作流。只有当变更已经改变当前版本的核心前提时,才升级到 `/genesis`。
9
+ **核心使命**:
10
+
11
+ - 处理当前版本内的**受控变更、契约回流与 task 调整**。**仅在已进入 `/forge` 编码阶段后使用**;若尚未开始编码,直接修改相关文档即可,无需走本工作流。只有当变更已经改变当前版本的核心前提时,才升级到 `/genesis`。
12
12
 
13
- **核心原则**:
14
- - **当前版本内统一入口** - 只要不改变当前版本的核心前提,文档、设计、任务、测试与契约修订默认都走 `/change`
15
- - **前提判断优先于文件类型** - 是否触发 `/genesis`,取决于是否改变需求/架构前提,而不是是否碰了 PRD、ADR 或 Architecture 文件
16
- - **任务与契约一起回流** - `/forge` 发现任务不足、契约漂移、验证责任缺失时,应优先回流 `/change`
17
- - **Git 分支连续性** - `/change` 属于当前版本内修正,继续使用当前 `feature/*` 分支;如需保护点,可在进入 `/change` 前先打 checkpoint commit
18
- - **只改不乱增** - 允许在当前版本内补足必要承接项,但禁止无明确请求的功能蔓延
19
- - **忠于 Blueprint** - 所有修改必须在 `01_PRD.md` 已定义的需求范围内
20
- - **签名机制** - 所有写操作必须先展示计划,经签名后才能执行;`/forge自动` 回流时使用 `AUTO` 签名
21
- - **可追溯** - 所有变更都记录在 CHANGELOG
22
- - **不维护完成状态** - `/change` 只修改任务定义,不负责回填 `05_TASKS.md` checkbox
13
+ **核心原则**:
14
+
15
+ - **当前版本内统一入口** - 只要不改变当前版本的核心前提,文档、设计、任务、测试与契约修订默认都走 `/change`
16
+ - **前提判断优先于文件类型** - 是否触发 `/genesis`,取决于是否改变需求/架构前提,而不是是否碰了 PRD、ADR 或 Architecture 文件
17
+ - **任务与契约一起回流** - `/forge` 发现任务不足、契约漂移、验证责任缺失时,应优先回流 `/change`
18
+ - **Git 分支连续性** - `/change` 属于当前版本内修正,继续使用当前 `feature/`* 分支;如需保护点,可在进入 `/change` 前先打 checkpoint commit
19
+ - **只改不乱增** - 允许在当前版本内补足必要承接项,但禁止无明确请求的功能蔓延
20
+ - **忠于 Blueprint** - 所有修改必须在 `01_PRD.md` 已定义的需求范围内
21
+ - **签名机制** - 所有写操作必须先展示计划,经签名后才能执行;`/forge自动` 回流时使用 `AUTO` 签名
22
+ - **可追溯** - 所有变更都记录在 CHANGELOG
23
+ - **不维护完成状态** - `/change` 只修改任务定义,不负责回填 `05_TASKS.md` checkbox
23
24
 
24
25
  **Output Goal**:
26
+
25
27
  - 更新 `.anws/v{N}/05_TASKS.md`
26
28
  - 更新 `.anws/v{N}/06_CHANGELOG.md`
27
29
 
28
30
  ---
29
31
 
30
- ## ⚠️ CRITICAL 权限边界
32
+ ## CRITICAL 权限边界
31
33
 
32
34
  > [!IMPORTANT]
33
- > **`/change` 的权限边界以“是否改变当前版本核心前提”为准,而不是以文件类型为准**:
34
- >
35
- > | 能力 | 允许 | 禁止 |
36
- > |------|:----:|:----:|
37
- > | 修改已有任务的描述 | | |
38
- > | 修改已有任务的验收标准 | | |
39
- > | 调整已有任务的估时 | | |
40
- > | 标记任务阻塞/重分优先级 | | |
41
- > | 微调 `04_SYSTEM_DESIGN/` 中已有文件的细节 | | |
42
- > | 修改当前版本中的普通文档/设计文件细节 | | |
43
- > | 修改 `01_PRD.md` 中**不改变需求前提**的表达/命名/澄清内容 | | |
44
- > | 修改 `02_ARCHITECTURE_OVERVIEW.md` 中**不改变架构前提**的表达/命名/澄清内容 | | |
45
- > | 修改 `03_ADR/` 中**不改变 ADR 核心决策前提**的接口、命名、契约补全或澄清内容 | | |
46
- > | 为承接当前版本内变更创建少量必要文档文件 | | |
47
- > | 为承接已明确请求的局部修订而补充少量必要任务 | | |
48
- > | 更新任务说明字段,但不改变完成状态 | | |
49
- > | 调整任务编排、Sprint/Wave 内排序(不改变 ADR 前提) | | |
50
- > | **回填 `05_TASKS.md` checkbox** | | |
51
- > | **添加 AI 自认为好的功能** | | |
52
- > | **修改 [REQ-XXX] 需求引用** | | |
53
- > | **改变需求目标、用户故事集合或需求边界** | | |
54
- > | **改变系统边界、跨系统架构基线或关键执行模型** | | |
55
- > | **推翻 ADR 的核心决策前提** | | |
56
- > | **让当前 `05_TASKS.md` 整体失效、必须整体重建任务树** | | |
57
- >
58
- > **一旦命中禁止项 → 当前版本无法继续承接,升级到 `/genesis`。**
35
+ > **`/change` 的权限边界以「是否改变当前版本核心前提」为准,而不是以文件类型为准**:
36
+ >
37
+ >
38
+ > | 能力 | 允许 | 禁止 |
39
+ > | -------------------------------------------------------- | --- | --- |
40
+ > | 修改已有任务的描述 | | |
41
+ > | 修改已有任务的验收标准 | | |
42
+ > | 调整已有任务的估时 | | |
43
+ > | 标记任务阻塞/重分优先级 | | |
44
+ > | 微调 `04_SYSTEM_DESIGN/` 中已有文件的细节 | | |
45
+ > | 修改当前版本中的普通文档/设计文件细节 | | |
46
+ > | 修改 `01_PRD.md` 中**不改变需求前提**的表达/命名/澄清内容 | | |
47
+ > | 修改 `02_ARCHITECTURE_OVERVIEW.md` 中**不改变架构前提**的表达/命名/澄清内容 | | |
48
+ > | 修改 `03_ADR/` 中**不改变 ADR 核心决策前提**的接口、命名、契约补全或澄清内容 | | |
49
+ > | 为承接当前版本内变更创建少量必要文档文件 | | |
50
+ > | 为承接已明确请求的局部修订而补充少量必要任务 | | |
51
+ > | 更新任务说明字段,但不改变完成状态 | | |
52
+ > | 调整任务编排、Sprint/Wave 内排序(不改变 ADR 前提) | | |
53
+ > | **回填 `05_TASKS.md` checkbox** | | |
54
+ > | **添加 AI 自认为好的功能** | | |
55
+ > | **修改 [REQ-XXX] 需求引用** | | |
56
+ > | **改变需求目标、用户故事集合或需求边界** | | |
57
+ > | **改变系统边界、跨系统架构基线或关键执行模型** | | |
58
+ > | **推翻 ADR 的核心决策前提** | | |
59
+ > | **让当前 `05_TASKS.md` 整体失效、必须整体重建任务树** | | 是 |
60
+ >
61
+ >
62
+ > **一旦命中禁止项 → 当前版本无法继续承接,升级到 `/genesis`。**
59
63
 
60
64
  ---
61
65
 
62
- ## ⚠️ CRITICAL 反自由发挥护栏
66
+ ## CRITICAL 反自由发挥护栏
63
67
 
64
68
  > [!IMPORTANT]
65
69
  > **AI 禁止自行添加功能!**
66
70
  >
67
- > - "我认为加一个 XX 功能会更好" → **禁止**
68
- > - "顺便优化一下 YY" → **禁止**
69
- > - "为了完善体验,建议增加 ZZ" → **禁止**
70
- > - 只处理用户**明确提出的**变更请求
71
- > - 变更内容必须可追溯到用户的**原话**
71
+ > - "我认为加一个 XX 功能会更好" → **禁止**
72
+ > - "顺便优化一下 YY" → **禁止**
73
+ > - "为了完善体验,建议增加 ZZ" → **禁止**
74
+ > - 只处理用户**明确提出的**变更请求
75
+ > - 变更内容必须可追溯到用户的**原话**
72
76
  >
73
77
  > **你的职责是忠实执行用户要求的微调,而非自作主张改善系统。**
74
78
  > **如果你发现了值得改进的地方,请在报告中以"建议"形式告知用户,由用户决定是否通过 `/genesis` 处理。**
75
79
 
76
- </phase_context>
77
-
78
80
  ---
79
81
 
80
- ## ⚠️ CRITICAL 变更分类
82
+ ## CRITICAL 变更分类
81
83
 
82
- > [!IMPORTANT]
83
- > **变更分类决定处理方式**:
84
- > - **局部修订 (Local Refinement)** → 本工作流处理
85
- > - **受控扩展 (Controlled Expansion)** → 本工作流处理,但必须显式展示影响范围
86
- > - **前提演进 (Foundational Evolution)** → 升级到 `/genesis`
84
+ > [!IMPORTANT]
85
+ > **变更分类决定处理方式**:
86
+ >
87
+ > - **局部修订 (Local Refinement)** → 本工作流处理
88
+ > - **受控扩展 (Controlled Expansion)** → 本工作流处理,但必须显式展示影响范围
89
+ > - **前提演进 (Foundational Evolution)** → 升级到 `/genesis`
87
90
 
88
- > [!NOTE]
89
- > **默认判断原则**:
90
- > 只要变更不改变当前版本的需求前提、架构前提与任务树可承接性,即使需要调整 PRD、ADR、System Design、TASKS 与测试要求,也应优先留在 `/change`。
91
+ > [!NOTE]
92
+ > **默认判断原则**:
93
+ > 只要变更不改变当前版本的需求前提、架构前提与任务树可承接性,即使需要调整 PRD、ADR、System Design、TASKS 与测试要求,也应优先留在 `/change`。
91
94
 
92
95
  ---
93
96
 
94
- ## Step 0: 定位当前版本
97
+ ## Step 0: 定位当前版本
95
98
 
96
- 1. **扫描版本**:
97
- 扫描 `.anws/` 目录,找到最新版本号 `v{N}`
98
- 2. **确定当前版本**:
99
- - 找到数字最大的文件夹 `v{N}`。
99
+ 1. **扫描版本**:
100
+ 扫描 `.anws/` 目录,找到最新版本号 `v{N}`
101
+ 2. **确定当前版本**:
102
+ - 找到数字最大的文件夹 `v{N}`。
100
103
  - **TARGET_DIR** = `.anws/v{N}`。
101
-
102
- 3. **检查必需文件**:
103
- - [ ] `{TARGET_DIR}/01_PRD.md` 存在
104
- - [ ] `{TARGET_DIR}/05_TASKS.md` 存在
105
- - [ ] `{TARGET_DIR}/06_CHANGELOG.md` 存在
106
-
107
- 4. **如果缺失**: 提示先运行 `/genesis` 和 `/blueprint`。
108
-
109
- 5. **Git 分支说明**:
110
- - `/change` 不负责切换开发主题分支
111
- - 只要仍属于当前版本、当前交付主题,就继续使用当前 `feature/*`
112
- - `/change` 结束后回到同一条 `feature/*` 分支继续推进
104
+ 3. **检查必需文件**:
105
+ - `{TARGET_DIR}/01_PRD.md` 存在
106
+ - `{TARGET_DIR}/05_TASKS.md` 存在
107
+ - `{TARGET_DIR}/06_CHANGELOG.md` 存在
108
+ 4. **如果缺失**: 提示先运行 `/genesis` 和 `/blueprint`。
109
+ 5. **Git 分支说明**:
110
+ - `/change` 不负责切换开发主题分支
111
+ - 只要仍属于当前版本、当前交付主题,就继续使用当前 `feature/`*
112
+ - `/change` 结束后回到同一条 `feature/`* 分支继续推进
113
113
 
114
114
  ---
115
115
 
116
116
  ## Step 1: 变更影响评估 (分级判定)
117
117
 
118
- **目标**: 判断变更属于局部修订、受控扩展,还是已经改变当前版本前提,必须升级到 `/genesis`。
119
-
120
- > [!IMPORTANT]
121
- > **你必须逐一回答以下 10 个问题**,并据此给出分级。
122
-
123
- | # | 评估问题 | `/change` 条件 |
124
- |---|---------|---------|
125
- | 1 | 是否改变需求目标、用户故事集合或需求边界? | |
126
- | 2 | 是否改变系统边界、关键执行模型或架构基线? | 否 |
127
- | 3 | 是否推翻 ADR 的核心决策前提? | 否 |
128
- | 4 | 是否只是表达、命名、接口、契约、示例、测试要求或澄清层面的修订? | 是,或影响可控且不改前提 |
129
- | 5 | 是否影响多个系统的接口? | 允许,但必须仍不改变前提 |
130
- | 6 | 是否需要新增外部依赖 (npm包/API/服务)? | 否或仅限当前版本内小范围可控引入,且不改前提 |
131
- | 7 | 用户是否明确要求新版本? | |
132
- | 8 | **是否需要在 `05_TASKS.md` 中新增承接当前变更的少量任务?** | **允许,但必须与用户原话或 `/forge` 回流原因直接对应** |
133
- | 9 | **是否新增或修改公共契约,并需要补充验证承接?** | **允许,但必须显式展示影响范围** |
134
- | 10 | **当前 `05_TASKS.md` 是否仍可通过局部修订继续承接?** | **是** |
135
-
136
- > [!IMPORTANT]
137
- > **Q8/Q9/Q10 是本工作流的核心防线**:
138
- > - Q8 允许最小承接任务,但不允许借机注入无关新功能
139
- > - Q9 让契约补全与测试责任补全明确留在 `/change`
140
- > - Q10 决定是否还能在当前版本内收敛;若任务树整体失效,必须升级 `/genesis`
141
- > - **如果变更只是为了更好地兑现现有 PRD / ADR / 设计契约,应优先判为 `/change` 可处理**
142
-
143
- **判定逻辑**:
144
- - 不改变当前版本的需求前提 / 架构前提 / 任务树承接性,且影响半径局部 **局部修订 (Local Refinement)**
145
- - 不改变当前版本的核心前提,但需要补充契约、测试责任、少量任务或任务重排以兑现当前版本目标 → **受控扩展 (Controlled Expansion)**
146
- - 只要改变需求前提、架构前提、ADR 核心前提,或已经无法在当前任务树上继续收敛 → **前提演进 (Foundational Evolution)**,跳转 Step 4
118
+ **目标**: 判断变更属于局部修订、受控扩展,还是已经改变当前版本前提,必须升级到 `/genesis`。
119
+
120
+ > [!IMPORTANT]
121
+ > **你必须逐一回答以下 10 个问题**,并据此给出分级。
122
+
123
+
124
+ | # | 评估问题 | `/change` 条件 |
125
+ | --- | --------------------------------------- | ---------------------------------- |
126
+ | 1 | 是否改变需求目标、用户故事集合或需求边界? | 否 |
127
+ | 2 | 是否改变系统边界、关键执行模型或架构基线? | 否 |
128
+ | 3 | 是否推翻 ADR 的核心决策前提? | |
129
+ | 4 | 是否只是表达、命名、接口、契约、示例、测试要求或澄清层面的修订? | 是,或影响可控且不改前提 |
130
+ | 5 | 是否影响多个系统的接口? | 允许,但必须仍不改变前提 |
131
+ | 6 | 是否需要新增外部依赖 (npm包/API/服务)? | 否或仅限当前版本内小范围可控引入,且不改前提 |
132
+ | 7 | 用户是否明确要求新版本? | |
133
+ | 8 | **是否需要在 `05_TASKS.md` 中新增承接当前变更的少量任务?** | **允许,但必须与用户原话或 `/forge` 回流原因直接对应** |
134
+ | 9 | **是否新增或修改公共契约,并需要补充验证承接?** | **允许,但必须显式展示影响范围** |
135
+ | 10 | **当前 `05_TASKS.md` 是否仍可通过局部修订继续承接?** | **是** |
136
+
137
+
138
+ > [!IMPORTANT]
139
+ > **Q8/Q9/Q10 是本工作流的核心防线**:
140
+ >
141
+ > - Q8 允许最小承接任务,但不允许借机注入无关新功能
142
+ > - Q9 让契约补全与测试责任补全明确留在 `/change`
143
+ > - Q10 决定是否还能在当前版本内收敛;若任务树整体失效,必须升级 `/genesis`
144
+ > - **如果变更只是为了更好地兑现现有 PRD / ADR / 设计契约,应优先判为 `/change` 可处理**
145
+
146
+ **判定逻辑**:
147
+
148
+ - 不改变当前版本的需求前提 / 架构前提 / 任务树承接性,且影响半径局部 → **局部修订 (Local Refinement)**
149
+ - 不改变当前版本的核心前提,但需要补充契约、测试责任、少量任务或任务重排以兑现当前版本目标 → **受控扩展 (Controlled Expansion)**
150
+ - 只要改变需求前提、架构前提、ADR 核心前提,或已经无法在当前任务树上继续收敛 → **前提演进 (Foundational Evolution)**,跳转 Step 4
147
151
 
148
152
  **输出示例**:
153
+
149
154
  ```markdown
150
155
  ## 变更评估
151
156
 
@@ -162,85 +167,79 @@ description: "处理当前版本内的受控变更与 task 调整,并在需要
162
167
  | 需要新增承接任务? | 否 | 对应 T2.1.3 的验收标准修改 |
163
168
  | 超出 PRD 范围? | 否 | [REQ-005] 已定义登录功能 |
164
169
 
165
- **结论**:局部修订 — 修改 T2.1.3 的验收标准
170
+ **结论**: 局部修订 — 修改 T2.1.3 的验收标准
166
171
  ```
167
172
 
168
173
  ---
169
174
 
170
175
  ## Step 2: 定位受影响的已有任务
171
176
 
172
- **目标**: 找到受影响的现有任务、文档与契约,并判断是否需要补充最小承接项。
177
+ **目标**: 找到受影响的现有任务、文档与契约,并判断是否需要补充最小承接项。
173
178
 
174
179
  > [!IMPORTANT]
175
180
  > **优先复用已有任务。**
176
181
  > 只有当用户请求的局部修订无法被现有任务承接时,才允许补充少量直接相关的新任务;只要仍不偏离 ADR 与当前版本目标,就不应轻易跳转 `/genesis`。
177
182
 
178
- 1. **读取当前任务清单**:
179
- 读取 `{TARGET_DIR}/05_TASKS.md`
180
-
181
- 2. **读取 PRD (交叉验证)**:
182
- 读取 `{TARGET_DIR}/01_PRD.md`,确认变更在需求范围内
183
-
184
- 3. **定位任务**:
185
- - 找到与变更相关的已有任务 (如 `T2.1.3`)
183
+ 1. **读取当前任务清单**:
184
+ 读取 `{TARGET_DIR}/05_TASKS.md`
185
+ 2. **读取 PRD (交叉验证)**:
186
+ 读取 `{TARGET_DIR}/01_PRD.md`,确认变更在需求范围内
187
+ 3. **定位任务**:
188
+ - 找到与变更相关的已有任务 (如 `T2.1.3`)
186
189
  - 记录所有实际受影响的已有任务
187
190
  - 如现有任务无法承接,但变更仍属当前版本内局部修订,可补充少量新任务并在 Step 3 明确展示
188
191
  - 如仅需在当前 ADR 前提下重排任务、调整 Sprint/Wave 归属或补充少量承接项,仍由 `/change` 处理
189
192
  - 如需要重做任务结构的根因是 ADR 已不成立或系统边界已变化 → 跳转 Step 4
190
-
191
- 4. **定位相关设计文件** (如需要):
192
- - 检查 `{TARGET_DIR}/04_SYSTEM_DESIGN/` 中是否有对应的系统设计文件
193
- - 仅当任务的修改涉及设计细节时才需要同步修改
194
- - 如为了承接当前版本内的契约补全或测试约束,需要新增少量设计/附录文件,允许创建,但必须在 Step 3 显式展示
195
-
196
- 5. **ADR 引用检测** (CRITICAL):
197
- > [!IMPORTANT]
198
- > **ADR 与 SYSTEM_DESIGN 的单向引用链**:
199
- > - ADR 记录跨系统决策详情
200
- > - SYSTEM_DESIGN §8 Trade-offs **只引用 ADR,不复制决策内容**
201
- > - 修改时:ADR 是源头,SYSTEM_DESIGN 通过引用关联
202
-
203
- **检测规则**:
204
- - 如果修改 `04_SYSTEM_DESIGN/` 中的文件:
205
- - 扫描文件中是否有 `[ADR-XXX]` 或 `../03_ADR/` 引用
206
- - 如果有引用,**必须提醒用户**:该系统设计依赖 ADR 决策
207
- - 如果用户请求修改 ADR
208
- - 先判断是否只是命名同步、接口补全、表达澄清或测试约束补充
209
- - 如不改变 ADR 核心决策前提 → 允许通过 `/change` 修改
210
- - 如改变 ADR 核心决策前提 → 升级 `/genesis`
211
-
212
- 6. **契约与验证承接检查**:
213
- - 如变更涉及公共契约(接口、CLI 参数、配置结构、文件格式、错误语义、跨系统协议)
214
- - 明确这些契约是否已有任务承接
215
- - 如无验证承接,确定是否需要补充验证任务、验收标准或验证说明
216
-
217
- 7. **确定修改内容**:
218
- 对每个受影响的文件,明确要修改什么:
219
- - 05_TASKS.md: 描述调整? 验收标准修改? 估时调整? 优先级变更?
220
- - 04_SYSTEM_DESIGN: 接口细节? 参数调整? 样式微调?
221
- - 01_PRD / 02_ARCHITECTURE_OVERVIEW / 03_ADR: 命名同步? 契约补全? 表达澄清? 测试约束补充?
222
- - **验证承接**: 是否需要新增/调整验证类型、验证说明或补充测试任务
223
- - **ADR 引用**: 如果修改涉及决策,确认是否需要更新 ADR 引用
193
+ 4. **定位相关设计文件** (如需要):
194
+ - 检查 `{TARGET_DIR}/04_SYSTEM_DESIGN/` 中是否有对应的系统设计文件
195
+ - 仅当任务的修改涉及设计细节时才需要同步修改
196
+ - 如为了承接当前版本内的契约补全或测试约束,需要新增少量设计/附录文件,允许创建,但必须在 Step 3 显式展示
197
+ 5. **ADR 引用检测** (CRITICAL):
198
+ > [!IMPORTANT]
199
+ > **ADR SYSTEM_DESIGN 的单向引用链**:
200
+ >
201
+ > - ADR 记录跨系统决策详情
202
+ > - SYSTEM_DESIGN §8 Trade-offs **只引用 ADR,不复制决策内容**
203
+ > - 修改时:ADR 是源头,SYSTEM_DESIGN 通过引用关联
204
+ > **检测规则**:
205
+ - 如果修改 `04_SYSTEM_DESIGN/` 中的文件:
206
+ - 扫描文件中是否有 `[ADR-XXX]` 或 `../03_ADR/` 引用
207
+ - 如果有引用,**必须提醒用户**:该系统设计依赖 ADR 决策
208
+ - 如果用户请求修改 ADR
209
+ - 先判断是否只是命名同步、接口补全、表达澄清或测试约束补充
210
+ - 如不改变 ADR 核心决策前提 → 允许通过 `/change` 修改
211
+ - 如改变 ADR 核心决策前提 → 升级 `/genesis`
212
+ 6. **契约与验证承接检查**:
213
+ - 如变更涉及公共契约(接口、CLI 参数、配置结构、文件格式、错误语义、跨系统协议)
214
+ - 明确这些契约是否已有任务承接
215
+ - 如无验证承接,确定是否需要补充验证任务、验收标准或验证说明
216
+ 7. **确定修改内容**:
217
+ 对每个受影响的文件,明确要修改什么:
218
+ - 05_TASKS.md: 描述调整? 验收标准修改? 估时调整? 优先级变更?
219
+ - 04_SYSTEM_DESIGN: 接口细节? 参数调整? 样式微调?
220
+ - 01_PRD / 02_ARCHITECTURE_OVERVIEW / 03_ADR: 命名同步? 契约补全? 表达澄清? 测试约束补充?
221
+ - **验证承接**: 是否需要新增/调整验证类型、验证说明或补充测试任务
222
+ - **ADR 引用**: 如果修改涉及决策,确认是否需要更新 ADR 引用
224
223
 
225
224
  ---
226
225
 
227
- ## Step 3: 签名检查点 ⚠️
228
-
229
- **目标**: 展示变更计划,获得签名后才能执行。
230
-
231
- > [!IMPORTANT]
232
- > **这是强制检查点。未经签名,禁止修改任何文件。**
233
- > 普通模式下等待用户签名;如本次 `/change` 明确来自 `/forge自动` 的连续回流,则保留完整检查点展示,并以 `AUTO` 作为签名继续执行。
226
+ ## Step 3: 签名检查点
227
+
228
+ **目标**: 展示变更计划,获得签名后才能执行。
229
+
230
+ > [!IMPORTANT]
231
+ > **这是强制检查点。未经签名,禁止修改任何文件。**
232
+ > 普通模式下等待用户签名;如本次 `/change` 明确来自 `/forge自动` 的连续回流,则保留完整检查点展示,并以 `AUTO` 作为签名继续执行。
234
233
 
235
234
  **展示变更计划**:
236
235
 
237
236
  ```markdown
238
- ⚠️ 签名检查点 — 变更确认
239
-
240
- **变更级别**: 局部修订 / 受控扩展
241
- **用户原始请求**: "{用户原话}"
242
- **受影响任务**: {N} 个
243
- **签名**: 用户 / AUTO
237
+ 签名检查点 — 变更确认
238
+
239
+ **变更级别**: 局部修订 / 受控扩展
240
+ **用户原始请求**: "{用户原话}"
241
+ **受影响任务**: {N} 个
242
+ **签名**: 用户 / AUTO
244
243
 
245
244
  ### 修改预览
246
245
 
@@ -256,85 +255,64 @@ description: "处理当前版本内的受控变更与 task 调整,并在需要
256
255
 
257
256
  ---
258
257
 
259
- 请签名:批准 /拒绝 / ✏️ 调整 / AUTO
260
- ```
261
-
262
- - **批准** → 继续 Step 3.1 执行修改
263
- - **拒绝** → 终止,不做任何修改
264
- - **调整** → 根据反馈重新制定计划,重新进入 Step 3
265
- - **AUTO** → 仅当本次来自 `/forge自动` 且仍在 `/change` 权限范围内时有效;保留检查点仪式,自动继续执行
266
-
267
- ### Step 3.1: 执行修改 (仅在签名后)
268
-
269
- 1. **修改任务清单**:
270
- 使用 `replace_file_content` 修改 `{TARGET_DIR}/05_TASKS.md` 中的对应任务定义
271
- - 仅允许修改任务描述、验收标准、估时、优先级、阻塞说明等定义字段
272
- - 如 Step 1 判定为受控扩展,可补充少量与用户原话直接对应的新任务
273
- - **禁止**在 `/change` 中将 `- [ ]` 改为 `- [x]` 或反向修改 checkbox
274
-
275
- 2. **记录变更日志**:
276
- 读取并追加到 `{TARGET_DIR}/06_CHANGELOG.md`:
277
- ```markdown
278
- ## {YYYY-MM-DD} - 局部修订变更
279
- - [CHANGE] T{X}.{Y}.{Z}: {修改描述}
280
- - 用户原话: "{用户的原始请求}"
281
- - 修改内容: {具体修改了什么}
282
- - 影响范围: {受影响的文件/组件}
283
- - PRD 追溯: [REQ-XXX]
284
- ```
285
-
286
- 3. **更新 AGENTS.md**:
287
- - 更新 `最近一次更新` 日期。
288
- - (注意: 局部修订不改变待办任务数)
258
+ 请签名: 批准 / 拒绝 / 调整 / AUTO
259
+ ```
289
260
 
290
- 4. **报告**: 告知用户变更已完成。
291
-
292
- 5. **最小复核判定**:
293
- - 如果本次 `/change` 修改了以下任一内容:
294
- - `05_TASKS.md` 中的 `契约承接`
295
- - `05_TASKS.md` 中的 `验证类型` / `验证说明`
296
- - `04_SYSTEM_DESIGN/`
297
- - 公共接口、错误语义、配置结构、文件格式
298
- - 则必须追加一次**最小复核**:
299
- - 默认先运行 `task-reviewer`
300
- - 如触及设计契约,再追加 `/challenge` `design-reviewer`
301
- - 生成一段**复核摘要**,至少包含:执行的 reviewer、发现数量、最高严重度、是否允许返回 `/forge`
302
- - 如最小复核仍有未处理 Critical → **阻塞**,不得回到 `/forge`
303
- - 如仍有未处理 High → 仅允许用户显式签名接受风险后继续;AUTO 不得自动带过
304
- - 只有复核通过或用户明确签名接受风险后,才允许回到 `/forge`
261
+ - **批准** → 继续 Step 3.1 执行修改
262
+ - **拒绝** → 终止,不做任何修改
263
+ - **调整** → 根据反馈重新制定计划,重新进入 Step 3
264
+ - **AUTO** → 仅当本次来自 `/forge自动` 且仍在 `/change` 权限范围内时有效;保留检查点仪式,自动继续执行
265
+
266
+ ### Step 3.1: 执行修改 (仅在签名后)
267
+
268
+ 1. **修改任务清单**:
269
+ 使用 `replace_file_content` 修改 `{TARGET_DIR}/05_TASKS.md` 中的对应任务定义
270
+ - 仅允许修改任务描述、验收标准、估时、优先级、阻塞说明等定义字段
271
+ - Step 1 判定为受控扩展,可补充少量与用户原话直接对应的新任务
272
+ - **禁止**在 `/change` 中将 `- [ ]` 改为 `- [x]` 或反向修改 checkbox
273
+ 2. **记录变更日志**:
274
+ 读取并追加到 `{TARGET_DIR}/06_CHANGELOG.md`:
275
+ 3. **更新 AGENTS.md**:
276
+ - 更新 `最近一次更新` 日期。
277
+ - (注意: 局部修订不改变待办任务数)
278
+ 4. **报告**: 告知用户变更已完成。
279
+ 5. **回到 `/forge` 前的衔接说明(非静态代码审查)**:
280
+ - **`/change` 不运行、不替代 `code-reviewer`。** 静态忠实度审查只属于 **`/forge` 3.4.5** 与 **`/challenge`(CODE/FULL)**;不得在本次变更报告中声称「代码已完成静态审查」。
281
+ - 若本次变更触及 `契约承接`、`验证类型` / `验证说明`、`04_SYSTEM_DESIGN/` 或公共接口语义:在报告中 **列表说明触达项**,便于 `/forge` 规划门禁与任务执行。
282
+ - **可选(文档侧)**:若任务表或设计措辞需要可读性复核,可 **建议** 用户使用 `task-reviewer` 或 `design-reviewer`;**不得**将 `/change` 写成与 **`/forge` Step 0**(含 `07_CHALLENGE_REPORT.md`)同等效力的「Critical/High 阻塞回到编码」门禁。
305
283
 
306
284
  ---
307
285
 
308
- ## Step 4: 升级到 /genesis
309
-
310
- **目标**: 告知用户当前变更已经改变版本前提,必须升级到 `/genesis`。
311
-
312
- > [!IMPORTANT]
313
- > **只有当变更改变当前版本的需求前提、架构前提或任务树承接性时,才升级到 `/genesis`。**
314
- > 不要把普通命名同步、契约补全、测试责任补全过度升级为 `/genesis`,也不要把前提演进伪装成 `/change`。
315
-
316
- > [!IMPORTANT]
317
- > **Git 换轨动作**:
318
- > 如果本次是从现有 `feature/*` 分支中途升级到 `/genesis`,先冻结当前分支;必要时先创建一个 checkpoint / freeze commit,再从最新 `main` 开新的 `feature/*`` 承接新版本。不要继续在旧分支上混做新版本实现。
286
+ ## Step 4: 升级到 /genesis
287
+
288
+ **目标**: 告知用户当前变更已经改变版本前提,必须升级到 `/genesis`。
289
+
290
+ > [!IMPORTANT]
291
+ > **只有当变更改变当前版本的需求前提、架构前提或任务树承接性时,才升级到 `/genesis`。**
292
+ > 不要把普通命名同步、契约补全、测试责任补全过度升级为 `/genesis`,也不要把前提演进伪装成 `/change`。
293
+
294
+ > [!IMPORTANT]
295
+ > **Git 换轨动作**:
296
+ > 如果本次是从现有 `feature/`* 分支中途升级到 `/genesis`,先冻结当前分支;必要时先创建一个 checkpoint / freeze commit,再从最新 `main` 开新的 `feature/`*` 承接新版本。不要继续在旧分支上混做新版本实现。
319
297
 
320
298
  ```markdown
321
- 🚫 此变更**已超出当前版本可承接范围**。
299
+ 此变更**已超出当前版本可承接范围**。
322
300
 
323
301
  **评估结果**:
324
302
  - [问题 X]: 是 — {理由}
325
303
 
326
- **为什么 /change 不能处理?**
327
- /change 的职责是处理当前版本内的受控修订与回流,
328
- 但当前变更已经改变了本版本的需求/架构前提,继续原地修补会破坏版本真相。
304
+ **为什么 /change 不能处理?**
305
+ /change 的职责是处理当前版本内的受控修订与回流,
306
+ 但当前变更已经改变了本版本的需求/架构前提,继续原地修补会破坏版本真相。
329
307
 
330
308
  **这能防止什么?**
331
- - AI 自行添加"觉得好"的功能
332
- - 架构文档与实现不一致
333
- - 绕过 PRD → 架构 → 任务的完整链条
309
+ - AI 自行添加"觉得好"的功能
310
+ - 架构文档与实现不一致
311
+ - 绕过 PRD → 架构 → 任务的完整链条
334
312
 
335
- **建议**: 升级到 `/genesis` 创建新的架构版本 `v{N+1}`。
313
+ **建议**: 升级到 `/genesis` 创建新的架构版本 `v{N+1}`。
336
314
 
337
- 📋 下一步: `/genesis` (将自动创建 v{N+1})
315
+ 下一步: `/genesis` (将自动创建 v{N+1})
338
316
  ```
339
317
 
340
318
  ---
@@ -348,22 +326,21 @@ description: "处理当前版本内的受控变更与 task 调整,并在需要
348
326
  > 用户需要自行决定是否通过 `/genesis` 处理。
349
327
 
350
328
  ```markdown
351
- 💡 **AI 发现的改进建议** (仅供参考,不在本次变更范围内):
329
+ **AI 发现的改进建议** (仅供参考,不在本次变更范围内):
352
330
 
353
331
  1. [建议1]: {描述} — 如需实施,请运行 `/genesis`
354
332
  2. [建议2]: {描述} — 如需实施,请运行 `/genesis`
355
333
 
356
- ⚠️ 以上建议**不会被自动执行**,请自行决定是否采纳。
334
+ 以上建议**不会被自动执行**,请自行决定是否采纳。
357
335
  ```
358
336
 
359
337
  ---
360
338
 
361
- <completion_criteria>
362
- - 完成 10 问题评估(含契约补全、验证承接与任务树承接性检查)
363
- - 局部修订 / 受控扩展: 定位受影响内容 + 展示计划 + 人类确认 + 执行修改 + 记录 CHANGELOG
364
- - ✅ 超出范围: 明确告知用户 /change 无权处理,引导 /genesis
365
- - ✅ 所有写操作前通过了人类检查点
366
- - 如有新增任务,必须与用户原话直接对应且影响范围已显式展示
367
- - 如修改触及契约承接、验证责任或系统设计,已追加最小复核
368
- - ✅ 未添加任何 AI 自认为好的功能
369
- </completion_criteria>
339
+ - 完成 10 问题评估(含契约补全、验证承接与任务树承接性检查)
340
+ - 局部修订 / 受控扩展:定位受影响内容 + 展示计划 + 人类确认 + 执行修改 + 记录 CHANGELOG
341
+ - 超出范围:明确告知用户 `/change` 无权承接,引导 `/genesis`
342
+ - 所有写操作前通过了人类检查点
343
+ - 如有新增任务,必须与用户原话直接对应且影响范围已显式展示
344
+ - 若触及契约/验证/系统设计:报告中已列出触达项,且未将 `code-reviewer` 或「代码已静态审查」归入 `/change`
345
+ - 未添加任何 AI 自认为好的功能
346
+