6aspec 2.0.0-dev.27 → 2.0.0-dev.29

package/.6aspec/rules/brown/brown_implement_sop.md

@@ -2,9 +2,15 @@
 
 执行任务实现。
 
+> **阶段定位**：Implement 的目标是按 Tasks 阶段拆解的 `TASK-*.md` 逐个交付实现结果，并保持“变更最小化、可验证、可追溯”。
+> - 默认执行策略：**里程碑优先 + 依赖优先**（优先完成更早里程碑中依赖已满足的任务）。
+> - 关键承接：Tasks 中定义的「契约/数据库变更/迁移兼容回滚」等交付物，必须在 Implement 阶段逐项落地并验收。
+
 **输入**：`/6aspec:brown:implement` 后可选需求名称。
 
-**步骤**
+---
+
+## 步骤
 
 1. **选择需求并检查状态**
 
@@ -14,47 +20,67 @@
 
 2. **读取上下文文件**
 
-   读取以下文档：
+   根据 `flowDepth` 读取以下文档：
+
+   **轻量级流程**：
+   - `6aspecdoc/brown/<name>/artifacts/proposal.md`
+   - `6aspecdoc/brown/<name>/artifacts/specs.md`
+   - `6aspecdoc/brown/<name>/artifacts/design.md`
+   - `6aspecdoc/brown/<name>/artifacts/tasks-overview.md`
+   - `6aspecdoc/brown/<name>/tasks/TASK-*.md`
+   - `6aspecdoc/brown/<name>/explore-summary.md`（如果存在）
+
+   **标准级/完整级流程**：
+   - `6aspecdoc/brown/<name>/artifacts/proposal.md`
+   - `6aspecdoc/brown/<name>/artifacts/understanding.md`
+   - `6aspecdoc/brown/<name>/artifacts/impact-analysis.md`
+   - `6aspecdoc/brown/<name>/artifacts/specs.md`
    - `6aspecdoc/brown/<name>/artifacts/design.md`
    - `6aspecdoc/brown/<name>/artifacts/tasks-overview.md`
    - `6aspecdoc/brown/<name>/tasks/TASK-*.md`
 
-3. **显示当前进度**
+3. **显示当前进度（含里程碑）**
 
    显示：
-   - 总任务数
-   - 已完成任务数
-   - 待完成任务数
-   - 下一个待执行的任务
+   - 总任务数 / 已完成任务数 / 待完成任务数
+   - 各里程碑完成度（M0~Mn：已完成/总数）
+   - 下一个可执行任务（里程碑最早且依赖满足）
 
 4. **执行任务（循环直到完成或阻塞）**
 
    对每个待完成的任务：
 
-   a. **显示正在执行的任务**
+   a. **选择下一个任务（里程碑优先 + 依赖优先）**
+   - 优先选择最早里程碑中仍未完成的任务
+   - 若任务在 `TASK-*.md` 的“前置依赖”中列出依赖任务，则必须依赖全部完成后才能开始
+   - 若最早里程碑任务均被阻塞（依赖未满足/信息不清晰/环境问题），则暂停并报告阻塞原因
+
+   b. **显示正在执行的任务**
    ```
-   ## 执行任务 3/8: TASK-003-domain-service-logic
+   ## 执行任务 <i>/<N>: TASK-<序号>-<slug>
 
-   **任务描述**: 实现领域服务业务逻辑
-   **预估工时**: 2人日
+   **所属里程碑**: <M0/M1/...>
+   **任务描述**: <任务描述>
+   **预估工时**: <X人日>
    ```
 
-   b. **读取任务详情**
+   c. **读取任务详情**
    - 读取 `6aspecdoc/brown/<name>/tasks/TASK-<序号>.md`
-   - 理解任务目标、输入、输出、详细步骤
+   - 理解任务目标、输入、输出、详细步骤、验收标准
 
-   c. **执行代码变更**
-   - 根据任务步骤进行代码修改
+   d. **执行代码/脚本变更**
+   - 根据任务步骤进行实现与修改
    - 保持变更最小化和聚焦
-   - 遵循技术方案设计
+   - 遵循 `design.md` 的技术决策与边界（不要在 Implement 阶段临时发明新方案）
+
+   e. **质量控制检查**
 
-   d. **质量控制检查**
-   **必须严格遵循代码规范**：`.6aspec/rules/biz/code.md`，并使用其中的"检查清单"章节进行自我验证。
+   **必须严格遵循代码规范**：`.6aspec/rules/biz/code.md`，并使用其中的“检查清单”章节进行自我验证。
 
    **重点关注以下红线规则（零容忍）：**
-   - [ ] 循环中的数据库查询、网络请求、文件I/O操作
-   - [ ] SQL字符串拼接、敏感信息硬编码、弱加密算法使用
-   - [ ] 循环依赖、跨层直接调用、空catch块
+   - [ ] 循环中的数据库查询、网络请求、文件 I/O 操作
+   - [ ] SQL 字符串拼接、敏感信息硬编码、弱加密算法使用
+   - [ ] 循环依赖、跨层直接调用、空 catch 块
 
    **棕地需求特别检查：**
    - [ ] 修改是否符合现有代码风格和架构模式
@@ -67,16 +93,33 @@
    - [ ] 检查代码编译和语法错误
    - [ ] 验证修改范围最小化
 
-   e. **标记任务完成**
+   f. **任务交付物核对（对齐新版 TASK 模板）**
+
+   根据任务文件中的栏目，逐项确认交付物已落地：
+   - 若包含“契约与接口出入参（如适用）”：
+     - [ ] 已明确字段清单与口径/必填性/兼容策略
+     - [ ] 已明确错误语义与幂等语义，并在实现/测试中覆盖
+   - 若包含“数据库变更（如适用）”：
+     - [ ] 已提供可执行的变更脚本与回滚要点（或回滚脚本）
+     - [ ] 已提供关键校验点（校验 SQL 或等价验证手段）
+   - 若包含“迁移 / 兼容 / 回滚（如适用）”：
+     - [ ] 已覆盖迁移/回填步骤与边界条件
+     - [ ] 已覆盖兼容策略（行为/数据/集成）与灰度/开关验证点
+     - [ ] 已明确回滚影响与限制，并准备验证方式
+   - 若任务标注 Observability：
+     - [ ] 处理记录可追踪（触发来源/处理结果/关键时间点可查）
+
+   g. **标记任务完成**
    - 在任务文件中更新状态：`📋 待开始` → `✅ 已完成`
-   - 在 `04-tasks-overview.md` 中更新任务状态：`- [ ]` → `- [x]`
+   - 在 `tasks-overview.md` 中更新任务状态：`- [ ]` → `- [x]`
+     - 注意：`tasks-overview.md` 中任务通常为链接形式（如 `[TASK-001...](../tasks/TASK-001.md)`），**只修改勾选，不要破坏链接结构**。
    - 更新 `status.json` 中的任务计数
 
-   e. **继续下一个任务**
+   h. **继续下一个任务**
 
    **暂停条件**：
-   - 任务不清晰 → 询问澄清
-   - 实现发现设计问题 → 建议更新 artifacts
+   - 任务不清晰 → 暂停并询问澄清
+   - 实现发现设计问题 → 暂停并建议更新 artifacts（design/specs/tasks）
    - 遇到错误或阻塞 → 报告并等待指导
    - 用户中断
 
@@ -86,18 +129,14 @@
    ```
    ## 实现完成：<name>
 
-   **进度**: 5/7 阶段完成
-   **任务完成**: 8/8 (100%)
+   **任务完成**: <N>/<N> (100%)
 
    ### 本次完成的任务
-   - [x] TASK-001: 数据库字段配置
-   - [x] TASK-002: 实体类字段添加
-   - [x] TASK-003: 领域服务逻辑实现
-   ...
+   - [x] TASK-001: ...
+   - [x] TASK-002: ...
+   - ...
 
    ### 下一步
-   所有任务已完成！
-
    - 轻量级/标准级流程:
      - 运行 `/6aspec:brown:verify` 进行质量检查（可选）
      - 运行 `/6aspec:brown:archive` 归档此需求
@@ -110,8 +149,7 @@
    ```
    ## 实现暂停：<name>
 
-   **进度**: 5/7 阶段完成
-   **任务完成**: 4/8 (50%)
+   **任务完成**: <完成数>/<总数> (<百分比>)
 
    ### 暂停原因
    <描述遇到的问题>
@@ -133,12 +171,11 @@
    {
      "status": "completed",
      "phases": {
-       ...
        "implement": "done"
      },
      "tasks": {
-       "total": 8,
-       "completed": 8,
+       "total": <N>,
+       "completed": <N>,
        "pending": 0
      }
    }
@@ -149,27 +186,32 @@
    {
      "status": "verify_pending",
      "phases": {
-       ...
        "implement": "done",
        "verify": "pending"
      },
      "tasks": {
-       "total": 8,
-       "completed": 8,
+       "total": <N>,
+       "completed": <N>,
        "pending": 0
      }
    }
    ```
 
-**输出**
+---
+
+## 输出
 
 根据执行情况显示相应的输出（见步骤 5）。
 
-**防护措施**
-- 必须先完成 Phase 4
+---
+
+## 防护措施
+
+- 必须先完成 Phase 4（Tasks）
 - 必须读取上下文文件再开始实现
+- 默认执行策略：里程碑优先 + 依赖优先；如发现阻塞必须暂停并报告
 - 如果任务模糊，暂停并询问
 - 如果实现发现设计问题，暂停并建议更新 artifacts
 - 保持代码变更最小化和聚焦
-- 立即更新任务状态
+- 立即更新任务状态（TASK 文件、tasks-overview、status.json）
 - 遇到错误时暂停并报告

package/.6aspec/rules/brown/brown_proposal_sop.md

@@ -63,21 +63,12 @@
 
    从需求描述中提取关键词（实体名、功能名、业务术语），然后执行快速搜索：
 
-   ```bash
-   # 搜索相关实体类
-   rg "class.*<关键词>.*Entity" --type java -g "*Entity.java"
+   - 搜索相关实体类：pattern = `class.*<关键词>.*Entity`，type = `java`，glob = `*Entity.java`
+   - 搜索相关服务类：pattern = `class.*<关键词>.*Service`，type = `java`，glob = `*Service.java`
+   - 搜索相关 Controller 类：pattern = `class.*<关键词>.*Controller`，type = `java`，glob = `*Controller.java`
+   - 搜索关键业务逻辑：pattern = `<关键方法名>`，type = `java`
 
-   # 搜索相关服务类
-   rg "class.*<关键词>.*Service" --type java -g "*Service.java"
-
-   # 搜索相关Controller类
-   rg "class.*<关键词>.*Controller" --type java -g "*Controller.java"
-
-   # 搜索关键业务逻辑
-   rg "<关键方法名>" --type java -C 3
-   ```
-
-   识别受影响的核心文件（3-5个），快速阅读关键代码片段。
+   识别受影响的核心文件（3-5 个），快速阅读关键代码片段。
 
    b. **识别待明确问题**
 
@@ -160,15 +151,17 @@
    <!-- If modifying existing behavior -->
    - `<capability-name>`: <brief description>
 
-   ## Impact
+   ## Impact（范围影响）
 
-   **轻量级流程**（基于需求描述或 explore 摘要）：
-   - `<file-path>`: <what changes>
-   - `<file-path>`: <what changes>
+   > 只描述「范围影响」而非实现细节：不写代码/类/数据库表层面的改动。
 
-   **标准级/完整级流程**（基于 understanding 和 impact 分析）：
-   - `<file-path>`: <what changes>（来自 impact-analysis.md）
-   - `<file-path>`: <what changes>（来自 impact-analysis.md）
+   - **业务影响**：<影响哪些业务流程/指标/体验>
+   - **用户与角色影响**：<影响哪些角色/人群/是否需要公告或培训>
+   - **系统模块影响**：<影响哪些系统/领域模块（模块级即可）>
+   - **兼容性影响**：<行为/接口是否向后兼容；对现有流程是否有行为变化>
+   - **数据影响（业务口径）**：<业务字段含义/口径变化；是否需要补数据/迁移（不写表结构）>
+   - **运营/流程影响**：<运营配置、审批链路、权限策略是否变化>
+   - **风险与回滚影响**：<主要风险点；是否可灰度；回滚对业务的影响>
 
    ## Next Steps
 
@@ -181,9 +174,8 @@
    - Why 部分：1-2 句话说明问题或机会
    - What Changes 部分：列出主要变更点
    - Capabilities 部分：列出新增或修改的系统能力（每个 capability 将对应一个 spec 文件）
-   - Impact 部分：列出受影响的文件和简要描述
-   - 轻量级流程的 Impact 基于需求描述、explore 摘要或轻量级探索结果（高层次评估）
-   - 标准级/完整级流程的 Impact 基于 impact-analysis.md（详细分析的摘要）
+   - Impact（范围影响）部分：只写业务/系统范围影响、兼容性、数据口径、风险与回滚等，不写代码/类/数据库表等实现细节
+   - Impact 内容基于：原始需求描述、（如有）explore 摘要、以及标准级/完整级流程中的 understanding / impact-analysis 结论进行归纳
    - 如果轻量级流程在步骤3中询问了用户问题，基于用户的回答生成proposal
 
 5. **更新状态**
@@ -362,7 +354,7 @@
 **防护措施**
 - 适用于所有流程（轻量级、标准级、完整级）
 - 如果需求信息不明确，必须询问用户
-- 提案必须包含Why、What、Impact三个核心部分
+- 提案必须包含 Why、What、Impact（范围影响） 三个核心部分
 - 提案应聚焦高层次的业务目标和核心能力，不包含详细的功能需求（FR）和验收标准（AC）
 - 详细的功能需求和验收标准应该在specs阶段定义
 - 风险评估不能省略

package/.6aspec/rules/brown/brown_specs_sop.md

@@ -21,6 +21,7 @@
 
    **轻量级流程**：
    - `6aspecdoc/brown/<name>/artifacts/proposal.md`
+   - `6aspecdoc/brown/<name>/explore-summary.md` - 探索摘要（如果存在）
 
    **标准级/完整级流程**：
    - `6aspecdoc/brown/<name>/artifacts/proposal.md`
@@ -47,17 +48,11 @@
 
    **探索方式**：
 
-   a. **简单搜索**（使用Grep/Glob工具）：
-   ```bash
-   # 搜索相关Entity类的字段定义
-   rg "private.*<字段名>" --type java -g "*Entity.java" -C 3
+   a. **简单搜索**（使用 Grep/Glob 工具）：
 
-   # 搜索相关验证注解
-   rg "@NotNull|@NotEmpty|@Valid" --type java -g "*Entity.java"
-
-   # 搜索现有的测试场景
-   rg "test.*<功能名>" --type java -g "*Test.java"
-   ```
+   - 搜索相关 Entity 类的字段定义：pattern = `private.*<字段名>`，type = `java`，glob = `*Entity.java`
+   - 搜索相关验证注解：pattern = `@NotNull|@NotEmpty|@Valid`，type = `java`，glob = `*Entity.java`
+   - 搜索现有的测试场景：pattern = `test.*<功能名>`，type = `java`，glob = `*Test.java`
 
    b. **复杂探索**（使用Task工具调用Explore agent）：
    - 当需要深入理解现有架构模式时
@@ -87,59 +82,37 @@
 
    <需求描述，使用 SHALL/MUST 关键字表示强制性要求>
 
-   ##### Scenario: <场景名称>
-
-   - **WHEN** <触发条件>
-   - **THEN** <预期结果>
-   - **AND** <额外的预期结果>（可选）
-
-   ##### Scenario: <另一个场景名称>
-
-   - **WHEN** <触发条件>
-   - **THEN** <预期结果>
-
-   #### Requirement: <另一个需求名称>
-
-   <需求描述>
+   ##### 验收标准
+   - AC1: <可观察、可验证的验收点>
+   - AC2: <可观察、可验证的验收点>
 
    ##### Scenario: <场景名称>
 
-   - **WHEN** <触发条件>
-   - **THEN** <预期结果>
-   ```
-
-5. **基于 Capabilities 定义功能需求**
-
-   从 proposal.md 中读取 Capabilities 列表，按 Capability 组织功能需求：
-
-   **功能需求格式**（按 Capability 组织）：
-   ```markdown
-   ### Capability: <capability-name> [ADD/MODIFY/REMOVE]
-
-   <Capability 描述，说明这个能力是做什么的>
-
-   #### Requirement: <需求名称>
-
-   <需求描述，使用 SHALL/MUST 关键字表示强制性要求>
-
-   ##### Scenario: <场景名称>
-
-   - **WHEN** <触发条件>
+   - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
+   - **GIVEN** <前置条件（业务对象状态/权限/已有数据/开关等）>
+   - **WHEN** <触发动作>
    - **THEN** <预期结果>
    - **AND** <额外的预期结果>（可选）
 
    ##### Scenario: <另一个场景名称>
 
-   - **WHEN** <触发条件>
+   - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
    - **THEN** <预期结果>
 
    #### Requirement: <另一个需求名称>
 
    <需求描述>
 
+   ##### 验收标准
+   - AC1: <...>
+
    ##### Scenario: <场景名称>
 
-   - **WHEN** <触发条件>
+   - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
    - **THEN** <预期结果>
    ```
 
@@ -148,7 +121,8 @@
    - 在 Capability 级别标识变更类型：[ADD]（新增）、[MODIFY]（修改）、[REMOVE]（移除）
    - 每个 Capability 下包含多个 Requirements
    - 每个 Requirement 应该是独立的、可验证的
-   - 每个 Scenario 使用 WHEN/THEN 格式，天然可测试
+   - 每个 Requirement SHOULD 显式列出验收标准（AC），用于快速评审覆盖面与边界
+   - 每个 Scenario MUST 包含：触发类型 + GIVEN/WHEN/THEN（AND 可选）；触发类型只能从「用户操作｜系统事件｜定时任务｜外部系统触发」中选择
    - 使用 SHALL/MUST 关键字表示强制性要求，SHOULD 表示推荐性要求
    - 功能需求应该从用户视角描述（做什么，而不是怎么做）
    - 避免技术实现细节（技术细节放在 design 阶段）
@@ -212,7 +186,7 @@
 
 8. **创建需求规格文档**
 
-   注意：使用 WHEN/THEN 格式定义的 Scenario 本身就是验证标准，无需单独定义验收标准。
+   注意：Scenario 用于将关键验收路径以结构化方式表达（GIVEN/WHEN/THEN），但验收标准仍应显式列出，便于评审快速检查覆盖面与边界。
 
    创建 `6aspecdoc/brown/<name>/artifacts/specs.md`：
    ```markdown
@@ -240,7 +214,24 @@
    - <业务约束：如必须满足某业务规则>
    - <时间约束：如必须在某时间前完成>
 
-   ## 2. 功能需求
+   ## 2. Key Entities（关键业务对象）
+
+   > 轻量业务模型：描述业务对象的含义、关键属性口径、状态与关系；避免写数据库表/类/字段类型。
+
+   - **实体**：<实体名称>
+     - **定义**：<一句话定义>
+     - **关键属性**：<属性1口径>；<属性2口径>...
+     - **状态**（可选）：<状态列表>
+     - **关系**（可选）：<与其他实体的业务关系>
+
+   ## 3. Business Rules（业务规则）
+
+   > 业务上必须成立的约束/推导规则（与实现无关）。
+
+   - BR-001：<规则描述（条件/结果）>
+   - BR-002：<规则描述>
+
+   ## 4. 功能需求
 
    ### Capability: <capability-name> [ADD]
 
@@ -250,24 +241,37 @@
 
    <需求描述，使用 SHALL/MUST 关键字表示强制性要求>
 
+   ##### 验收标准
+   - AC1: <可观察、可验证的验收点>
+   - AC2: <可观察、可验证的验收点>
+
    ##### Scenario: <场景名称>
 
-   - **WHEN** <触发条件>
+   - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
+   - **GIVEN** <前置条件（业务对象状态/权限/已有数据/开关等）>
+   - **WHEN** <触发动作>
    - **THEN** <预期结果>
    - **AND** <额外的预期结果>（可选）
 
    ##### Scenario: <另一个场景名称>
 
-   - **WHEN** <触发条件>
+   - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
    - **THEN** <预期结果>
 
    #### Requirement: <另一个需求名称>
 
    <需求描述>
 
+   ##### 验收标准
+   - AC1: <...>
+
    ##### Scenario: <场景名称>
 
-   - **WHEN** <触发条件>
+   - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
    - **THEN** <预期结果>
 
    ### Capability: <another-capability-name> [MODIFY]
@@ -278,12 +282,17 @@
 
    <需求描述>
 
+   ##### 验收标准
+   - AC1: <...>
+
    ##### Scenario: <场景名称>
 
-   - **WHEN** <触发条件>
+   - **触发类型** 用户操作｜系统事件｜定时任务｜外部系统触发
+   - **GIVEN** <前置条件>
+   - **WHEN** <触发动作>
    - **THEN** <预期结果>
 
-   ## 3. 非功能需求
+   ## 5. 非功能需求
 
    > **注意**：只写有明确要求的项，如果某个类别没有明确要求，可以省略该小节。
 
@@ -303,7 +312,7 @@
    - 浏览器：SHALL 支持 <具体版本>
    - 数据库：SHALL 兼容 <具体版本>
 
-   ## 4. 下一步
+   ## 6. 下一步
 
    运行 `/6aspec:brown:design` 进行技术方案设计
    ```