asia-aidlc 1.14.5 → 1.14.7

package/.aidlc-engine/README.md

@@ -1,20 +1,21 @@
 # 可运行系统实现（System）
 
-> 本目录把"OpenSpec + AI-DLC 思想增强"的流程规范落地为**可运行的三层系统**：状态层、能力层、编排层。
+> 本目录把"OpenSpec + AI-DLC 思想增强"的流程规范落地为**可运行的四层系统**：编排层、执行层、能力层、状态层。
 > 完整流程规范见 `../README.md` 与 `.aidlc-engine/docs/`。
 
-## 四层架构 + 统一入口
+## 四层架构 + 统一入口（v2.0：执行层由"数字分身"改为"主 Agent 单会话 + 角色帽执行卡"）
 
 ```
-编排层   .aidlc-engine/agent/            → 研发流程编排 Agent（System Prompt，流程引擎）
-执行层   AiDO 分身组               → 11 个 Trae 智能体（各阶段产物执行者，见 agent/agent-roles.md）
-能力层   .aidlc-engine/skills/           → 11 个确定性 Skill（产物生成 + 门控校验 + 状态维护）
-状态层   .aidlc-engine/state/            → workflow-state.json（唯一真相）+ Schema + 目录规约
-统一入口 .aidlc-engine/cli/              → flow CLI / MCP Server（Trae 加载，查·验·记）
+编排层   .aidlc-engine/skills/aidlc-flow/   → 入口技能（流程引擎：九步编排 / 戴帽执行 / 触发 Gate / 回流）
+         + .trae/rules/flow-orchestration.md（瘦身编排规则，alwaysApply：触发识别 + 铁律）
+执行层   主 Agent + 角色帽执行卡           → skills/aidlc-flow/references/ 6 份执行卡（各阶段产物执行者，单会话戴帽执行）
+能力层   .aidlc-engine/skills/             → 12 个确定性 Skill（含 aidlc-flow 入口技能；产物生成 + 门控校验 + 状态维护）
+状态层   .aidlc-engine/state/              → workflow-state.json（唯一真相）+ Schema + 目录规约
+统一入口 .aidlc-engine/cli/                → flow CLI / MCP Server（Trae 加载，查·验·记）
 ```
 
-> 执行层分工与调度协议详见 [.aidlc-engine/docs/agent-integration.md](.aidlc-engine/docs/agent-integration.md)：
-> 编排 Agent 只调度不干活，分身只产出不裁决（不写状态、不触发 Gate），Skill 只判定不裁量。
+> 角色帽分工与执行卡协议详见 [.aidlc-engine/docs/agent-integration.md](.aidlc-engine/docs/agent-integration.md)：
+> 主 Agent 单会话编排、戴帽干活；角色帽只产出不裁决（不写状态、不触发 Gate、不渲染追溯矩阵），Skill 只判定不裁量。
 
 ## 目录速览
 
@@ -28,7 +29,8 @@
 │   ├── audit-events.json               # 25 事件封闭注册表 + emitter 归属 + 审计不变量（P0-2）
 │   ├── gate_freeze.py                  # 门控冻结 hash 唯一实现（P0-3，gate/validate 共用）
 │   └── directory-convention.md         # 目录规约 + ID 规则 + 环节 memory.md（P0-4）+ 追溯要求
-├── skills/                             # 能力层（14 个 Skill）
+├── skills/                             # 能力层（12 个 Skill）
+│   ├── aidlc-flow/                     #   【入口技能】九步编排 + 角色帽执行卡（references/*.md，P2 待补）
 │   ├── req-doc-generator/              #   生成 REQ 文档 + 登记状态
 │   ├── gate-verifier/                  #   确定性门控校验（含脚本）
 │   ├── traceability-updater/           #   渲染追溯矩阵（含脚本）
@@ -40,9 +42,9 @@
 │   ├── design-doc-generator/           #   全局系统设计（架构/接口/数据模型）
 │   ├── compliance-checker/             #   合规检查清单（含脚本）
 │   └── audit-logger/                   #   全链路审计日志（含脚本）
-├── agent/                              # 编排层 + 执行层分工
-│   ├── orchestration-agent-system-prompt.md  # 主编排 Agent 提示词（核心，含分身调度）
-│   └── agent-roles.md                        # AiDO 分身执行层分工表
+├── agent/                              # v2.0 起废弃（仅作入口技能/角色帽内容源与历史口径参考）
+│   ├── orchestration-agent-system-prompt.md  # 原编排 Agent 提示词（降级为内容源）
+│   └── agent-roles.md                        # 原 AiDO 分身执行层分工表（已废弃）
 └── cli/                                # 统一入口（Trae 加载）
     ├── flow.py                         #   状态管理与巡检 CLI（req create/init/status/validate/transition/gate/code/commit/compliance/audit/matrix/e2e）
     ├── flow_mcp.py                     #   MCP stdio Server（把 flow 暴露为 10 个工具，供 Trae 调用）
@@ -54,19 +56,19 @@
 
 > 缺口补齐：相对 AI-DLC，新增了测试体系（Test Plan/Cases/Report）、全局系统设计、合规清单、全链路审计日志四类工件。E2E 已扩展为 9 步覆盖这些产出物。
 
-## Skill、编排 Agent 与 AiDO 分身的关系
+## 入口技能、主 Agent、角色帽与 Skill 的关系（v2.0）
 
-- **Agent 是流程引擎**：决定"何时推进、触发哪个 Gate、调哪个 Skill、派哪个分身"。System Prompt 见 `agent/orchestration-agent-system-prompt.md`。
-- **AiDO 分身是执行者**：各阶段产物（REQ/DSN/WU/TP/Change/代码/TR/OBS 分析）由对应分身生产（分工见 `agent/agent-roles.md`）。分身只写内容真相产物，不写状态、不触发 Gate。
-- **Skill 是能力单元**：每个 Skill 做一件确定的事（生成某产物 / 校验某门控 / 维护某状态）。7 个 Skill 全部具备独立 `SKILL.md`。
-- **状态文件是真相**：Agent 和 Skill 都读写 `workflow-state.json`，追溯矩阵只是它的渲染视图。
+- **aidlc-flow 是流程引擎**：主 Agent 加载入口技能，决定"何时推进、触发哪个 Gate、调哪个 Skill、戴哪顶角色帽"。见 `skills/aidlc-flow/SKILL.md`。
+- **角色帽是执行者**：主 Agent 单会话戴 `skills/aidlc-flow/references/` 执行卡（P2 待补）生产各阶段产物（REQ/DSN/WU/TP/Change/代码/TR）。角色帽只写其声明写边界内的内容真相产物，不写状态、不触发 Gate。
+- **Skill 是能力单元**：每个 Skill 做一件确定的事（生成某产物 / 校验某门控 / 维护某状态）。12 个 Skill 全部具备独立 `SKILL.md`。
+- **状态文件是真相**：主 Agent 和 Skill 都读写 `workflow-state.json`（写一律经 flow CLI / Skill 入口），追溯矩阵只是它的渲染视图。
 
 ## 三阶段实现对应关系
 
 | 阶段 | 对应产物 | 状态 |
 |---|---|---|
 | 阶段1 状态层 + 校验 | `state/` + `state-validator` + `traceability-updater` | ✅ 已实现，脚本可运行 |
-| 阶段2 编排 Agent | `agent/orchestration-agent-system-prompt.md` | ✅ 已生成提示词 |
+| 阶段2 编排 | v2.0：`skills/aidlc-flow/` 入口技能（原提示词 `agent/orchestration-agent-system-prompt.md` 降级为内容源） | ✅ 入口技能 + 6 角色帽执行卡 + 瘦身规则（源 `agent/flow-orchestration-rule.md`，init 装 `.trae/rules/`）已就位 |
 | 阶段3 OpenSpec 集成 | `skills/openspec-executor` | ✅ 已封装桥接 |
 | 缺口补齐（对照 AI-DLC） | `skills/{test-manager, design-doc-generator, compliance-checker, audit-logger}` + 对应模板 | ✅ 已实现并接入 9 步 E2E |
 
@@ -121,7 +123,7 @@ python .aidlc-engine/cli/flow.py code verify --chg CHG-102               # 代
 
 1. 在仓库根执行 `python .aidlc-engine/cli/flow.py init`——自动生成 `workflow-state.json`（按实际项目清空为初始状态）+ 目录脚手架 + Trae 接入件与技能（`.trae/`）。
 2. 非 Trae 环境手工把 Skill 安装到你环境的 `workspace/.user_skills`（符合 skill 规范）；Trae 环境由 init 自动装到 `.trae/skills/`。
-3. 编排 Agent 提示词：Trae 环境由 init 自动写入 `.trae/rules/flow-orchestration.md`（alwaysApply）；其他载体手工加载 `agent/orchestration-agent-system-prompt.md`。
+3. 流程规则：Trae 环境由 init 自动把 v2.0 瘦身编排规则写入 `.trae/rules/flow-orchestration.md`（alwaysApply；源文件 `agent/flow-orchestration-rule.md`：触发识别 + 8 铁律 + 流程任务必须先加载 `aidlc-flow` 入口技能；已存在 v1.8 旧全量提示词版时跳过并提示人工替换）；其他载体手工加载 `skills/aidlc-flow/SKILL.md`。
 4. 按 `README.md` 的"落地三步"接入第一个真实需求，跑通一条完整链路。
 
 ## 验证清单（用户后续验收用）
@@ -129,5 +131,5 @@ python .aidlc-engine/cli/flow.py code verify --chg CHG-102               # 代
 - [ ] `state-validator` 对 example.json 返回 EXIT=0
 - [ ] `gate-verifier` 对 gated WU 返回 PASS
 - [ ] `traceability-updater` 能生成正确矩阵
-- [ ] 编排 Agent 收到一条 L1 需求能走到 REQ→Epic→WU→Gate→Change→Release→Observation
-- [ ] 指标不达标时，Agent 能新建 REQ 回流
+- [ ] 主 Agent（aidlc-flow 入口技能）收到一条 L1 需求能走到 REQ→Epic→WU→Gate→Change→Release→Observation
+- [ ] 指标不达标时，主 Agent 能新建 REQ 回流

package/.aidlc-engine/agent/agent-roles.md

@@ -1,5 +1,9 @@
 # 执行层分工：AiDO 分身嵌入（原"角色 Agent 扩展"）
 
+> **已废弃（v2.0 起）**：本文件不再作为执行层依据。v2.0 起执行层改为"主 Agent 单会话 + 角色帽执行卡"：
+> 现行执行卡见 `.aidlc-engine/skills/aidlc-flow/references/`（6 卡），分身 → 角色帽迁移映射见 `.aidlc-engine/docs/agent-integration.md` §10。
+> 本文件仅作历史口径参考保留，禁止据其新建流程或变更。
+
 > 本文件定义**执行层**：各流程阶段由哪个 AiDO 分身实际执行产物生产。
 > 完整集成设计（调度协议 / 分级组合 / 并行隔离 / 异常处理）见 `.aidlc-engine/docs/agent-integration.md`。
 

package/.aidlc-engine/agent/flow-orchestration-rule.md

@@ -0,0 +1,29 @@
+# 研发流程编排规则（v2.0 瘦身版）
+
+> 本规则只是"触发开关 + 铁律地板"；完整流程协议（九步主流程 / 角色帽协议 / 门控两步确认 /
+> 执行分支规约 / 会话恢复）在 `aidlc-flow` 入口技能，设计依据见 `.aidlc-engine/docs/agent-integration.md`。
+
+## 触发条件：命中任一，必须先加载入口技能
+
+新需求 / 需求解析 / 需求评审 / 合规 / Epic / WorkUnit / 执行分支 / OpenSpec 变更 /
+apply 实施 / 代码评审 / 发布评审 / 上线 / 观测验收 / 流程状态查询或恢复。
+
+命中后必须先完整读取 `.trae/skills/aidlc-flow/SKILL.md`，再按其"九步主流程"执行；
+**禁止凭记忆或仅凭本规则启动流程步骤**。
+
+## 8 条铁律（地板，未加载技能时同样不放宽）
+
+1. **只编排不裁量门控**：所有 Gate 通过与否必须由 `gate-verifier` Skill 判定。
+2. **状态唯一真相** `aidlc-data/workflow-state.json`：只经 `flow` CLI / flow MCP 写，改后 `state-validator` 确认。
+3. **不直接改追溯矩阵**：由 `traceability-updater` 重渲。
+4. **分级豁免**：按 `.aidlc-engine/docs/task-grading.md` 判 L1/L2/L3，L3 跳过重流程。
+5. **追溯链不可断**：REQ↔EPIC↔WU↔CHG↔REL↔OBS 双向可溯。
+6. **角色帽写边界**：按步骤戴对应执行卡，只写卡内声明的"写边界"；不写状态、不触发 Gate、不渲染矩阵。
+7. **门控两步确认（HARD STOP）**：`flow gate --request` → 呈现用户并立即结束回合 → 用户真实回复后 `--record --confirm` 留痕。
+8. **执行分支前置硬规则**：CHG 实施前必须先 `flow branch create`（GUARD_BRANCH_REQUIRED）；CHG 状态变更一律 `flow transition`。
+
+## 禁止项
+
+- 禁止用文件工具直写 `workflow-state.json` / `traceability-matrix.md` / `openspec/specs/` 等硬约束路径（hooks 拦截）。
+- 禁止未戴帽（未加载对应执行卡）时执行状态写、触发 Gate、推进流程。
+- 禁止盲目重试：自检不过按执行卡返工规则处理，两次仍不过上报用户。

package/.aidlc-engine/agent/orchestration-agent-system-prompt.md

@@ -1,6 +1,11 @@
 # 系统提示词：研发流程编排 Agent（Orchestration Agent）
 
-> 用途：将本提示词作为编排 Agent 的 System Prompt 加载。它驱动 OpenSpec+AI-DLC 增强流程的全链路流转。
+> **已降级为内容源（v2.0 起）**：本文件不再是编排安装源，不应再作为 System Prompt 加载。当前生效的编排规则为
+> `agent/flow-orchestration-rule.md`（瘦身版，`flow init` 安装至 `.trae/rules/flow-orchestration.md`）+ `skills/aidlc-flow/SKILL.md` 入口技能；
+> 执行层"AiDO 分身"已由角色帽执行卡（`skills/aidlc-flow/references/`）取代，迁移映射见 `docs/agent-integration.md` §10。
+> 本文件仅作入口技能/角色帽的内容源保留（铁律、状态机、门控协议、执行分支链路等口径），按口径引用，不再整体加载。
+
+> 用途：驱动 OpenSpec+AI-DLC 增强流程的全链路流转（原"作为 System Prompt 加载"用途已失效，见上方降级声明）。
 > 配套能力：
 > - **Skill（确定性判定/登记）**：req-doc-generator、gate-verifier、traceability-updater、state-validator、openspec-executor、release-doc-generator、observation-doc-generator（见 `../skills/` 目录）。
 > - **AiDO 分身（执行层，产物生产者）**：需求数字分身（agent-requirement-designer）、技术设计分身（agent-technical-designer）、原型设计分身（agent-prototype-designer）、测试分身（agent-e2e-test）、SDD 开发分身（agent-sdd-development）、前端开发分身（agent-frontend-architect）、后端开发分身（agent-backend-architect）、数据库操作分身（database-ops-offline-agent）、架构分析分身（agent-project-analysis）、代码检索分身（code-search-agent）。分工详见 `agent-roles.md`，集成设计详见 `.aidlc-engine/docs/agent-integration.md`。

package/.aidlc-engine/cli/.trae/mcp.json

@@ -3,7 +3,10 @@
     "flow": {
       "command": "python",
       "args": ["${workspaceFolder}/.aidlc-engine/cli/flow_mcp.py"],
-      "env": {}
+      "env": {
+        "PYTHONUTF8": "1",
+        "PYTHONIOENCODING": "utf-8"
+      }
     }
   }
 }

package/.aidlc-engine/cli/TRAE-SETUP.md

@@ -75,7 +75,7 @@ python .aidlc-engine/cli/flow.py e2e
 - **路径分隔**：Windows 下 `args` 中的路径建议用正斜杠或双反斜杠，Trae 的 `${workspaceFolder}` 会自动展开为项目根。
 - **中文路径**：flow.py / flow_mcp.py 均用 UTF-8 读写，已验证中文路径正常（实测含中文路径的 `flow_status` 通过）。
 - **jsonschema 未安装**：`validate` 会降级为 WARN（跳过完整 schema 校验），建议 `pip install jsonschema`。
-- **流程推进仍归编排 Agent**：本 CLI 只负责"查、验、记"，不会替 Agent 做流程决策；编排 Agent 的 System Prompt 见 `.aidlc-engine/agent/orchestration-agent-system-prompt.md`。
+- **流程推进仍归编排 Agent**：本 CLI 只负责"查、验、记"，不会替 Agent 做流程决策；v2.0 编排 = 瘦身规则 `.trae/rules/flow-orchestration.md`（init 安装，源文件 `.aidlc-engine/agent/flow-orchestration-rule.md`）+ `aidlc-flow` 入口技能（流程任务必须先加载 `skills/aidlc-flow/SKILL.md`）；全量编排提示词（`agent/orchestration-agent-system-prompt.md`）仅保留为内容源。
 
 ## 五、MCP 工具清单