Skip to content

Commit 3db8a95

Browse files
committed
fix: add artifact lifecycle decision matrix
1 parent 781dde4 commit 3db8a95

16 files changed

Lines changed: 86 additions & 35 deletions

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,7 @@ AGENTS.md ← 与 instructions.md / copilot-instructions.md / CL
174174
- **Context Rehydration Contract**:压缩恢复、resume 或用户要求按文件真相重建时,会按“当前用户消息 → 已确认产物 → sessions → tasks → SUMMARY → 摘要 → AI 推断”的优先级恢复上下文,摘要不能覆盖文件真相源。
175175
- **ContextHandoffCard**:跨会话、跨 Agent、多批次、summary/compact 前或用户要求传递上下文时,会把 source-of-truth、confirmed decisions、open risks、next action、must-not-overwrite、validation state 与 ArtifactLinkSet 写入报告或 daily tasks;恢复时仍按 Context Rehydration Contract 重新核对文件真相源。
176176
- **SimpleTaskFastPath**:非常明确、预计 ≤2 文件、无公共契约/配置/发布/控制面/台账来源/高风险、无需多轮跟踪的简单 dev/fix 任务,可免建 `01-需求概述.md` / `04-实施计划.md`,改用内联 CP 摘要 + 报告/记忆 `N/A + skipReason`;范围扩大时立即升级回完整产物链。若已有需求/bug 真相源,命中 `ExistingRequirementArtifactOverride`,调整内容必须先回写文件,回复只做摘要。
177+
- **ArtifactDecisionMatrix**:CP1/CP2/CP3/ECR 会按任务规模列出关键产物的 `create` / `update` / `skip` / `N/A` 状态,覆盖需求、技术方案、实施计划、实施进度、目标文档、报告和记忆;判定优先级为已有真相源回写 > 任务触发条件 > SimpleTaskFastPath > 子类型豁免,避免模板“必填”口径压过轻路径或条件触发。
177178
- **Hook closure 三态**:Stop/PreCompact 可见回复验证区分 `verified-present`、`verified-missing`、`unverified`;无法解析最终 assistant 内容时只提示无法验证,并给出 payload capture 指引,不再断言“未输出”。
178179
- **长流程执行契约**:Auto、控制面、多批次、预计修改 ≥10 文件或发布前置任务会触发 ExecutionContract;测试路线不明显时触发 TestRoute;正式发版前触发 ReleaseAudit 与 ReleaseVerification;控制面消费链联动时建立 Concept Sync Map;宿主契约变化时触发 `host-contract-verification`。
179180
- **执行期 CP3 回退**:若执行过程中实际修改范围扩展到 CP3 门槛(≥5 文件、高风险、控制面联动),必须暂停执行并先补做 CP3,再继续改动。

‎changelogs/unreleased.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,12 @@
66
77
---
88

9+
## 2026-06-05
10+
11+
- 修复产物生命周期口径:新增 `ArtifactDecisionMatrix / ArtifactLifecycleState`,统一 `01-需求概述.md`、`02-技术方案.md`、`04-实施计划.md`、`05-实施进度.md`、目标文档、报告和记忆的 `create / update / skip / N/A` 判定,优先级为“已有真相源回写 > 任务触发条件 > SimpleTaskFastPath > 子类型豁免”。
12+
- 修正模板漂移:`technical-design.prompt.md` 仅在 `02-技术方案.md` 被判定需要创建/更新时使用;`implementation-plan.prompt.md` 不再要求 `04-实施计划.md` 始终创建;`implementation-progress.prompt.md` 支持 docs/init 等 CP3 豁免场景使用等价任务切片或 `ContextHandoffCard` 作为进度锚点。
13+
- 补充验证守门:`V41` 与 `test-spec-governance` 增加 `ArtifactDecisionMatrix` 正向探针和旧口径负向探针,防止“始终创建实施计划 / 技术方案禁止跳过”类表述回流。
14+
915
## 记录提示
1016

1117
- 控制面 / 长流程 / 多批次变更写入本文件时,优先标明 `execution-contract`、`test-router`、`release-verification`、`host-contract-verification`、`source-consumer-sync` 等支撑型能力是否同步更新。

‎instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -310,6 +310,7 @@ CP1(需求确认)→ CP2(方案确认)→ [plan-review] → CP3(实施
310310
- **CP3**:条件触发。default/refactor/database/optimization/scenario-test 必须执行;docs/init/plan-review 按子类型规则豁免,并记录 `CP3: N/A(<子类型> 子类型豁免)`。
311311
- **SimpleTaskFastPath**:非常明确、预计 ≤2 个源码/文档文件、无公共 API/Schema/依赖/配置/发布/控制面/台账来源/高风险、无需多轮跟踪的 dev/fix 任务,可不创建需求/bug 目录、`01-需求概述.md` 或 `04-实施计划.md`,改用内联 CP 摘要 + 报告/记忆记录 `N/A + skipReason`;PC0~PC7、Profile、报告、记忆、安全底线、必要验证和 ECR 不可省略,执行中任一条件失效立即升级回完整产物链。
312312
- **ExistingRequirementArtifactOverride**:当用户表达“调整/修改/补充/变更需求或问题”且已存在 `01-需求概述.md`、bug CP 产物、Profile 声明的正式需求文件或 website requirement 时,SimpleTaskFastPath 只能跳过**新建**完整产物,不能跳过**更新已有真相源**;必须先增量编辑对应文件,用户回复只作为摘要。若无法定位既有产物,先按项目 Profile/当前任务线索定位,仍无法确认时再最小澄清,禁止静默只在回复中变更口径。
313+
- **ArtifactDecisionMatrix / ArtifactLifecycleState**:CP1/CP2/CP3/ECR 必须按需列出关键产物状态:`create` / `update` / `skip` / `N/A`,并写明 `reason`、`trigger`、`upgradeTrigger`、`targetArtifact`。判定优先级固定为:已有真相源回写 > 任务触发条件 > SimpleTaskFastPath 轻路径豁免 > 子类型豁免。该矩阵覆盖 `01-需求概述.md`、`02-技术方案.md`、`04-实施计划.md`、`05-实施进度.md`、目标文档、报告和记忆;禁止用模板中的“必填/必选”口径压过条件触发或豁免规则。
313314
- 若执行过程中新增范围触发 CP3 条件(例如最初判断 <5 文件但实际扩展到 ≥5 文件,或新增高风险操作/控制面联动),必须暂停执行,回补或重开 CP3 后再继续。
314315
- **ECR**:执行完成后、宣告完成前必须执行 ECR 执行闭环复审,覆盖 CP1/CP2/CP3、报告、daily tasks、SUMMARY、diff/commit、测试/探针、AI 自启动服务清理证据与 dirty 边界。
315316

‎instructions/02-output-paths.instructions.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -74,12 +74,13 @@ version: 1.11.14
7474
| **scripts/ 触发条件** | 任务目录(requirements/<任务>/ 或 bugs/<任务>/)下有共享辅助脚本(数据迁移/数据填充/自动化验证等)时创建对应 `scripts/` 子目录;默认禁止放入业务逻辑或网络请求。`*-接口验证.cjs` 属规范强制产物,存放任务根目录(非 scripts/)|
7575
| **本地临时脚本豁免** | 仅本地执行、不会提交发布链路的临时脚本/配置可放入任务目录 `.tmp/local-scripts/` 或保持未提交;允许直接使用局部常量、敏感信息和网络请求,但不得伪装成共享正式产物 |
7676
| **services/ 触发条件(跨服务)** | 需求涉及 ≥2 个服务时在 CP2 后创建;每个 `实施方案.md` 头部**必须**包含反向引用 `> 📎 上级需求:[需求名](../../01-需求概述.md)(入口服务:<服务名>)`;**禁止**各服务各自单独建 `requirements/<需求名>/` 目录(碎片化) |
77-
| **04-实施计划 计划层级** | 默认创建 `04-实施计划.md`;小到中型任务可使用“轻计划摘要”,高风险 / 多模块 / 接口或 Schema 变更 / 跨轮次任务使用“完整实施计划” |
78-
| **05-实施进度 触发条件** | 小任务不默认创建;当任务跨 2 轮以上会话、存在明确阻塞、用户要求持续跟踪、CP3 计划拆成多批次、预计修改 ≥10 文件,或命中控制面/模板/validate/部署副本联动时必须创建并持续更新,且前提是已存在 `04-实施计划.md` |
77+
| **04-实施计划 计划层级** | 默认在 CP3 触发时创建 `04-实施计划.md`;小到中型任务可使用“轻计划摘要”,高风险 / 多模块 / 接口或 Schema 变更 / 跨轮次任务使用“完整实施计划”;SimpleTaskFastPath 或 docs/init/plan-review 子类型豁免时可记 `N/A + skipReason` |
78+
| **05-实施进度 触发条件** | 小任务不默认创建;当任务跨 2 轮以上会话、存在明确阻塞、用户要求持续跟踪、CP3 计划拆成多批次、预计修改 ≥10 文件,或命中控制面/模板/validate/部署副本联动时必须创建并持续更新;前提是已存在 `04-实施计划.md`,或 docs/init 等 CP3 豁免场景已有等价任务切片 / ContextHandoffCard |
7979
| **SimpleTaskFastPath** | 目标明确、预计 ≤2 个源码/文档文件、无公共 API/Schema/依赖/配置/发布/控制面/台账来源/高风险操作、无需多轮跟踪时,可不创建需求目录与 `01-需求概述.md`/`04-实施计划.md`,改用回复内联 CP 摘要 + 报告/记忆记录 `N/A + skipReason`;执行中任一条件失效必须升级回完整产物链 |
8080
| **ExistingRequirementArtifactOverride** | 用户调整/修改/补充既有需求或问题,且已有 `01-需求概述.md`、bug CP 产物、Profile 声明的正式需求文件或 website requirement 时,必须更新已有真相源;SimpleTaskFastPath 只豁免新建完整产物,不能把回复内联摘要当成文件回写 |
81+
| **ArtifactDecisionMatrix** | CP1/CP2/CP3/ECR 需要按任务规模列出关键产物的 `create` / `update` / `skip` / `N/A` 状态、原因、触发条件和升级回退;判定优先级为“已有真相源回写 > 任务触发条件 > SimpleTaskFastPath > 子类型豁免”,覆盖 01/02/04/05、目标文档、报告和记忆 |
8182
| **禁止写入源码目录** | 脚本/测试/辅助文件严禁放入项目源码目录 |
82-
| **强制产物首轮完成** | 默认 01/04 在首轮会话结束前必须创建;其中 `04-实施计划.md` 可按轻计划摘要 / 完整实施计划两档落地;SimpleTaskFastPath 命中时 01/04 允许 `N/A + skipReason`,但 PC0~PC7、Profile、报告、记忆、安全底线和必要验证仍不可省略;02-技术方案.md 和 实施方案/ 按条件触发;services/ 在 CP2 后按需创建;强触发条件命中时 `05-实施进度.md` 必须在执行前初始化 |
83+
| **强制产物首轮完成** | 默认 01/04 在首轮会话结束前按 ArtifactDecisionMatrix 处理:需要则创建/更新,命中 SimpleTaskFastPath 或子类型豁免则记录 `N/A + skipReason`;PC0~PC7、Profile、报告、记忆、安全底线和必要验证不可省略;02-技术方案.md 和 实施方案/ 按条件触发;services/ 在 CP2 后按需创建;强触发条件命中时 `05-实施进度.md` 必须在执行前初始化 |
8384
| **需求归档(v1.9.3+)** | 已完成且不再活跃的需求目录下创建空文件 `.archived`;CP gate 扫描跳过含此标记的需求,避免历史需求全局阻断 dev 工作流 |
8485

8586
## 报告路径

‎instructions/10-dev.instructions.md‎

Lines changed: 12 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -68,17 +68,18 @@ CP1(需求确认)→ PR-1 内部自检 → CP2(方案确认)→ plan-rev
6868
3. **每个 CP 独立确认**:输出后必须等待用户明确响应
6969
4. **CP3 内容边界**:CP3 只确认实施计划,不重复技术方案中的架构决策、接口论证和兼容性主说明;必须显式覆盖任务拆分、顺序、依赖、验证方式与回滚策略
7070
5. **产物文件前置创建**:默认 CP1 → `01-需求概述.md` + `<需求>/.memory/sessions.md`(需求级记忆);CP2 → `02-技术方案.md`(有架构/接口/设计决策时,否则跳过);CP3 → `04-实施计划.md`。若命中 `SimpleTaskFastPath`,可用回复内联 CP1 摘要 + 报告/记忆替代需求目录,并将 `01-需求概述.md` / `04-实施计划.md` 记为 `N/A + skipReason`;但命中 ExistingRequirementArtifactOverride 时必须先更新已有需求真相源。
71-
6. **进度文档触发**:`05-实施进度.md` 不是小任务默认必产物;但当任务跨 2 轮以上会话、存在明确阻塞、用户要求持续跟踪、CP3 计划拆分为多批次、预计修改 ≥10 文件或命中控制面/模板/validate/部署副本联动时,必须在执行前创建并在每批完成后更新,且前提是已存在 `04-实施计划.md`
72-
7. **无 Hooks 宿主软门禁**(v1.9.6+):当运行宿主为 `jetbrains-copilot`、`cursor` 或其他 `instruction-fallback` 客户端时,`lifecycle.cjs` CP gate 不可执行。AI 必须在每个 CP 输出末尾显式追加 `⏸ 等待用户确认(CP{N})— 收到"好/继续/ok"前不得进入下一阶段或写源码`,并在用户未明确回复前禁止 source mutation 工具调用。
73-
8. **CP3 豁免记录**:docs/init/plan-review 子类型被规则明确豁免 CP3 时,须在需求级记忆或报告中记录 `CP3: N/A(<子类型> 子类型豁免)`,供 hook/fallback 区分合法豁免与漏确认。
74-
9. **确认后前置轻量复审**(C19):每次用户明确确认 CP1 / CP2 / CP3 后、进入下一阶段前,必须先对当前已确认产物做 1 轮轻量前置复审并显式输出结果;控制面 / 多文件联动 / 真相源同步 / 模板-示例-校验链场景必须追加交叉验证;发现阻断性问题则先修正当前产物、告知用户并重新确认,无阻断问题方可推进。
75-
10. **Intent Expansion 可见性**:dev 模式下,CP1 / 需求确认前默认向用户展示完整 Intent Expansion Card;这会覆盖旧的“意图扩展摘要”默认行为,但当命中控制面或宿主能力差异、跨会话 resume、prod、instruction-fallback 宿主或低风险轻任务时,仍允许退化为 3~5 行意图扩展摘要。
76-
11. **执行期 CP3 回退**:若 N5 执行过程中实际变更范围扩展到 CP3 门槛(如文件数从 <5 增至 ≥5、临时引入高风险操作、命中控制面/模板/validate/部署副本联动),必须暂停执行,回到 N4 / CP3 补做实施计划确认后再继续。
77-
12. **backlog 来源前置真相复核**:若本轮需求、批次或范围直接来源于 `data/*.md` 的 open/partial 项,CP1 前必须先把候选项分类为 `pure-open` / `residual-tail` / `already-fixed` / `misclassified`;非 `pure-open` 项须先回写状态并修正范围口径,禁止直接按旧 open 计数开做。
78-
13. **OfficialDocsEvidence**:新增/升级依赖、框架、SDK、平台 API 或外部模块时,CP2 前必须读取官方使用文档/官方参考资料;CP2 记录文档来源、版本/日期、关键用法、限制和兼容性,缺失证据不得进入 PR-2 通过态。
79-
14. **ProfileImpactCheck**:项目技术栈、目录边界、脚本、测试/发布路线、分发面、配置项、长期连接或本地 overlay schema 变化时,CP2/CP3 必须判定并同步 Profile;不需要同步时写明 `skipReason`。
80-
15. **连接配置来源按用户 / 项目策略**:凡 CP2/CP3 涉及脚本、测试、数据库 / SSH / MongoDB / 数据操作连接信息,默认可直写或沿用项目既有模式;只有用户或项目明确指定 `config.local.json`、env、`secretRef` 或 secret manager 时,方案才按该入口读取并在缺失时提醒补齐。
81-
16. **AI 自启动服务清理**:若开发验证需要由 AI 启动 dev server、文档站、本地 API/mock、数据库代理、SSH 隧道、Playwright/Cypress server 或压测 target,CP3/TestRoute 必须记录启动命令、cwd、PID/job、端口/URL;验证完成、失败或最终回复前必须停止仅由 AI 本轮启动的服务并核验端口释放。用户明确要求保留服务时,报告保留原因、PID/端口和关闭方式;不得杀用户既有进程。
71+
6. **ArtifactDecisionMatrix / ArtifactLifecycleState**:CP1/CP2/CP3/ECR 必须按任务规模列出关键产物 `create` / `update` / `skip` / `N/A` 状态,至少覆盖 `01-需求概述.md`、`02-技术方案.md`、`04-实施计划.md`、`05-实施进度.md`、目标文档、报告、记忆;每项写明 `reason`、`trigger`、`upgradeTrigger`、`targetArtifact`。判定优先级:已有真相源回写 > 任务触发条件 > SimpleTaskFastPath > 子类型豁免。
72+
7. **进度文档触发**:`05-实施进度.md` 不是小任务默认必产物;但当任务跨 2 轮以上会话、存在明确阻塞、用户要求持续跟踪、CP3 计划拆分为多批次、预计修改 ≥10 文件或命中控制面/模板/validate/部署副本联动时,必须在执行前创建并在每批完成后更新。默认前提是已存在 `04-实施计划.md`;docs/init 等 CP3 豁免场景可使用已确认文档大纲、任务切片或 ContextHandoffCard 作为等价计划锚点。
73+
8. **无 Hooks 宿主软门禁**(v1.9.6+):当运行宿主为 `jetbrains-copilot`、`cursor` 或其他 `instruction-fallback` 客户端时,`lifecycle.cjs` CP gate 不可执行。AI 必须在每个 CP 输出末尾显式追加 `⏸ 等待用户确认(CP{N})— 收到"好/继续/ok"前不得进入下一阶段或写源码`,并在用户未明确回复前禁止 source mutation 工具调用。
74+
9. **CP3 豁免记录**:docs/init/plan-review 子类型被规则明确豁免 CP3 时,须在需求级记忆或报告中记录 `CP3: N/A(<子类型> 子类型豁免)`,供 hook/fallback 区分合法豁免与漏确认。
75+
10. **确认后前置轻量复审**(C19):每次用户明确确认 CP1 / CP2 / CP3 后、进入下一阶段前,必须先对当前已确认产物做 1 轮轻量前置复审并显式输出结果;控制面 / 多文件联动 / 真相源同步 / 模板-示例-校验链场景必须追加交叉验证;发现阻断性问题则先修正当前产物、告知用户并重新确认,无阻断问题方可推进。
76+
11. **Intent Expansion 可见性**:dev 模式下,CP1 / 需求确认前默认向用户展示完整 Intent Expansion Card;这会覆盖旧的“意图扩展摘要”默认行为,但当命中控制面或宿主能力差异、跨会话 resume、prod、instruction-fallback 宿主或低风险轻任务时,仍允许退化为 3~5 行意图扩展摘要。
77+
12. **执行期 CP3 回退**:若 N5 执行过程中实际变更范围扩展到 CP3 门槛(如文件数从 <5 增至 ≥5、临时引入高风险操作、命中控制面/模板/validate/部署副本联动),必须暂停执行,回到 N4 / CP3 补做实施计划确认后再继续。
78+
13. **backlog 来源前置真相复核**:若本轮需求、批次或范围直接来源于 `data/*.md` 的 open/partial 项,CP1 前必须先把候选项分类为 `pure-open` / `residual-tail` / `already-fixed` / `misclassified`;非 `pure-open` 项须先回写状态并修正范围口径,禁止直接按旧 open 计数开做。
79+
14. **OfficialDocsEvidence**:新增/升级依赖、框架、SDK、平台 API 或外部模块时,CP2 前必须读取官方使用文档/官方参考资料;CP2 记录文档来源、版本/日期、关键用法、限制和兼容性,缺失证据不得进入 PR-2 通过态。
80+
15. **ProfileImpactCheck**:项目技术栈、目录边界、脚本、测试/发布路线、分发面、配置项、长期连接或本地 overlay schema 变化时,CP2/CP3 必须判定并同步 Profile;不需要同步时写明 `skipReason`。
81+
16. **连接配置来源按用户 / 项目策略**:凡 CP2/CP3 涉及脚本、测试、数据库 / SSH / MongoDB / 数据操作连接信息,默认可直写或沿用项目既有模式;只有用户或项目明确指定 `config.local.json`、env、`secretRef` 或 secret manager 时,方案才按该入口读取并在缺失时提醒补齐。
82+
17. **AI 自启动服务清理**:若开发验证需要由 AI 启动 dev server、文档站、本地 API/mock、数据库代理、SSH 隧道、Playwright/Cypress server 或压测 target,CP3/TestRoute 必须记录启动命令、cwd、PID/job、端口/URL;验证完成、失败或最终回复前必须停止仅由 AI 本轮启动的服务并核验端口释放。用户明确要求保留服务时,报告保留原因、PID/端口和关闭方式;不得杀用户既有进程。
8283

8384
### SimpleTaskFastPath(简单任务轻路径)
8485

0 commit comments

Comments
 (0)