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

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

@@ -2,146 +2,205 @@
 
 Phase 4: 任务拆解与排期
 
+> **阶段定位**：Tasks 的目标是把 `design.md` 的技术蓝图落成“可执行的原子任务”。
+> - **里程碑（Milestone）**：用于组织任务与依赖关系、前置暴露风险（集成/迁移/兼容等）。里程碑不是任务。
+> - **任务（TASK）**：原子可交付单元；可独立完成；输入/输出明确；验收标准清晰；建议工作量 0.5-3 人日。
+> - **边界承接**：
+>   - API/回调/事件的**具体出入参字段清单**在 Tasks 阶段落地（Design 只写契约语义要点）。
+>   - **修改存量表**的 ALTER/索引/脚本/校验 SQL 在 Tasks 阶段落地（Design 只写语义与迁移策略）。
+>   - **新增表**若 Design 已给 DDL，Tasks 负责把 DDL/脚本落实为可执行变更与回滚方案。
+
 **输入**：`/6aspec:brown:tasks` 后可选需求名称。
 
-**步骤**
+---
+
+## 步骤
 
 1. **选择需求并检查状态**
 
    - 读取 `6aspecdoc/brown/<name>/status.json`
    - 确认 `phases.design` 为 "done"
-   - 如果未完成 Phase 3，提示先运行 `/6aspec:brown:design`
+   - 若未完成 Design，提示先运行 `/6aspec:brown:design`
 
 2. **读取前置文档**
 
    根据 `flowDepth` 读取不同的前置文档：
 
    **轻量级流程**：
-   - `6aspecdoc/brown/<name>/artifacts/design.md`
+   - `6aspecdoc/brown/<name>/artifacts/proposal.md`
    - `6aspecdoc/brown/<name>/artifacts/specs.md`
+   - `6aspecdoc/brown/<name>/artifacts/design.md`
+   - `6aspecdoc/brown/<name>/explore-summary.md` - 探索摘要（如果存在）
 
    **标准级/完整级流程**：
-   - `6aspecdoc/brown/<name>/artifacts/design.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`
 
-3. **原子任务拆解**
+3. **原子任务拆解（以里程碑组织）**
 
-   按以下维度拆解任务：
+   先基于 `design.md` 梳理里程碑，再在每个里程碑下拆成原子任务。
 
    **拆解原则**：
-   - 可以独立完成
-   - 有明确的输入和输出
-   - 有清晰的验收标准
-   - 预估工作量在 0.5-3 人日
+   - 可以独立完成（必要依赖明确）
+   - 有明确的输入与输出
+   - 有清晰的验收标准（可对齐 Specs 的 AC / Scenarios）
+   - 预估工作量在 0.5-3 人日（超过则继续拆分）
 
-   **拆解维度**：
-   - 按技术层次：数据层 → 业务层 → 表现层 → 测试
+   **拆解维度**（可组合使用）：
+   - 按交付里程碑：契约与集成 → 数据变更 → 迁移/兼容/回滚 → 核心链路 → 集成联调与观测 → 测试与发布准备
    - 按功能模块：模块A → 模块B → 模块C
    - 按依赖关系：前置任务 → 核心任务 → 后置任务
+   - 按横切能力：Integration / Migration / Compatibility / Observability / Security
 
-4. **任务命名**
+4. **任务命名与元信息**
 
    使用规范：`TASK-<序号>-<简短描述>`
 
    示例：
-   - TASK-001-database-fields
-   - TASK-002-entity-classes
-   - TASK-003-domain-service-logic
+   - `TASK-001-contract-and-idempotency`
+   - `TASK-010-db-migration-scripts`
+   - `TASK-020-external-callback-handler`
+
+   每个任务必须标注：
+   - 所属里程碑
+   - 涉及能力标签（DB/BE/FE/QA/Integration/Migration/Observability）
 
-5. **创建任务文档**
+5. **创建任务文档（TASK-*.md）**
 
    为每个任务创建 `6aspecdoc/brown/<name>/tasks/TASK-<序号>.md`：
+
    ```markdown
    # TASK-<序号>: <任务名称>
 
    > **任务ID**: TASK-<序号>
+   > **所属里程碑**: <M0/M1/...>
+   > **涉及能力**: DB / BE / FE / QA / Integration / Migration / Observability
    > **状态**: 📋 待开始
    > **优先级**: 🔴 P0 / 🟡 P1
-   > **预估工作量**: X人日
+   > **预估工作量**: X 人日
    > **负责人**: 待分配
 
    ## 任务概述
-   ### 任务描述
-   ### 目标
-   ### 涉及文件
+   - **任务描述**：<一句话说明要交付什么>
+   - **目标**：<完成后可验证的目标>
 
    ## 依赖关系
-   ### 前置依赖
-   ### 后置任务
+   - **前置依赖**：<TASK-xxx>
+   - **后置任务**：<TASK-yyy>
 
    ## 输入
+   - specs.md：<引用相关 Capability/Requirement/AC/Scenario>
+   - design.md：<引用相关模块/边界/事件流/集成/迁移策略>
+
    ## 输出
+   - <代码/脚本/配置/文档/验证产物>
+
    ## 详细步骤
+   1. ...
+   2. ...
+
    ## 验收标准
+   - 与 Specs 对齐的 AC/Scenario 覆盖：<列出 ACx / Sx>
+   - 可观测性：<是否需要处理记录、trace、日志等可查证输出>
+
+   ## 契约与接口出入参（如适用）
+   > 用于落地 API/回调/事件的具体字段清单与口径（Design 不展开字段清单）。
+   - **接口/回调/事件名称**：<...>
+   - **请求字段**：<字段名/含义/必填/兼容策略>
+   - **响应字段**：<字段名/含义/必填/兼容策略>
+   - **错误语义**：<错误码/错误类型>
+   - **幂等语义**：<幂等键/重复请求处理规则>
+
+   ## 数据库变更（如适用）
+   - **新增表**：<若已有 DDL，注明复用；若需补充，写出最终 DDL 与回滚要点>
+   - **修改存量表**：<ALTER/索引/回滚脚本任务拆分点>
+   - **校验 SQL**：<关键校验点>
+
+   ## 迁移 / 兼容 / 回滚（如适用）
+   - **迁移/回填策略**：<步骤与边界>
+   - **兼容性策略**：<行为/数据/集成兼容>
+   - **灰度/开关验证**：<需要验证的开关点>
+   - **回滚策略**：<回滚影响与限制>
+
    ## 风险与注意事项
+   - <风险1>
+   - <风险2>
+
    ## 参考资料
+   - <链接或文件路径>
    ```
 
-6. **创建任务总览**
+6. **创建任务总览（按里程碑）**
 
    创建 `6aspecdoc/brown/<name>/artifacts/tasks-overview.md`：
+
    ```markdown
    # Phase 4: 任务拆解与排期
 
    > **需求**: <name>
-   > **阶段**: Phase 4 - 任务拆解
+   > **阶段**: Phase 4 - Tasks
    > **状态**: ✅ 已完成
    > **完成时间**: <timestamp>
 
-   ## 任务列表
+   ## 里程碑与任务列表
+
+   ### M0: 契约与集成准备（Integration/Contract）
+   - [ ] [TASK-001: 对齐回调/事件幂等语义与处理记录（含验收点）](../tasks/TASK-001.md)
+   - [ ] [TASK-002: 外部系统集成联调前置（认证/失败语义/对账点）](../tasks/TASK-002.md)
 
-   ### 阶段 1: 数据层
-   - [ ] TASK-001: 数据库字段配置
-   - [ ] TASK-002: 实体类字段添加
+   ### M1: 数据变更准备（DB Change）
+   - [ ] [TASK-010: 新增表 DDL 落地与回滚方案（如适用）](../tasks/TASK-010.md)
+   - [ ] [TASK-011: 存量表 ALTER/索引/脚本任务拆分（如适用）](../tasks/TASK-011.md)
 
-   ### 阶段 2: 业务层
-   - [ ] TASK-003: 领域服务逻辑实现
-   - [ ] TASK-004: 应用服务逻辑实现
+   ### M2: 迁移 / 兼容 / 回滚（Migration/Compatibility）
+   - [ ] [TASK-020: 数据回填/迁移脚本与校验 SQL](../tasks/TASK-020.md)
+   - [ ] [TASK-021: 兼容策略与灰度/开关验证清单](../tasks/TASK-021.md)
 
-   ### 阶段 3: 表现层
-   - [ ] TASK-005: API 接口更新
-   - [ ] TASK-006: 前端 UI 开发
+   ### M3: 核心链路实现（Core Flow）
+   - [ ] [TASK-030: 核心业务逻辑实现（对齐 AC/Scenario）](../tasks/TASK-030.md)
+   - [ ] [TASK-031: 定时任务/事件消费/回调处理实现（如适用）](../tasks/TASK-031.md)
 
-   ### 阶段 4: 测试
-   - [ ] TASK-007: 单元测试
-   - [ ] TASK-008: 集成测试
+   ### M4: 集成联调与可观测性（Integration & Observability）
+   - [ ] [TASK-040: 集成联调与异常路径验证（重试/乱序/重复）](../tasks/TASK-040.md)
+   - [ ] [TASK-041: 可观测性补齐（处理记录可查、日志/指标/追踪要点）](../tasks/TASK-041.md)
 
-   ## 依赖关系图
+   ### M5: 测试与发布准备（Validation & Release）
+   - [ ] [TASK-050: 回归与验证矩阵落地（覆盖关键 AC/Scenario）](../tasks/TASK-050.md)
+   - [ ] [TASK-051: 发布检查清单（灰度/回滚演练要点）](../tasks/TASK-051.md)
+
+   ## 依赖关系图（示例）
 
    ```mermaid
    graph TD
-       TASK-001 --> TASK-002
-       TASK-002 --> TASK-003
-       TASK-003 --> TASK-004
-       TASK-004 --> TASK-005
-       TASK-005 --> TASK-006
-       TASK-006 --> TASK-007
-       TASK-007 --> TASK-008
+       TASK001 --> TASK010
+       TASK010 --> TASK020
+       TASK020 --> TASK030
+       TASK030 --> TASK040
+       TASK040 --> TASK050
    ```
 
    ## 工作量统计
 
-   | 阶段 | 任务数 | 预估工时 |
+   | 里程碑 | 任务数 | 预估工时 |
    |------|--------|----------|
-   | 数据层 | 2 | 1.5人日 |
-   | 业务层 | 2 | 4人日 |
-   | 表现层 | 2 | 5人日 |
-   | 测试 | 2 | 4人日 |
-   | **总计** | **8** | **14.5人日** |
-
-   ## 关键里程碑
-
-   - 里程碑 1: 数据层完成（TASK-001, TASK-002）
-   - 里程碑 2: 业务层完成（TASK-003, TASK-004）
-   - 里程碑 3: 表现层完成（TASK-005, TASK-006）
-   - 里程碑 4: 测试完成（TASK-007, TASK-008）
+   | M0 | <n> | <x> 人日 |
+   | M1 | <n> | <x> 人日 |
+   | M2 | <n> | <x> 人日 |
+   | M3 | <n> | <x> 人日 |
+   | M4 | <n> | <x> 人日 |
+   | M5 | <n> | <x> 人日 |
+   | **总计** | **<n>** | **<x> 人日** |
 
    ## 风险清单
 
    | 风险 | 影响 | 应对措施 |
    |------|------|----------|
-   | 历史数据迁移失败 | 高 | 提前备份，准备回滚方案 |
-   | API 不兼容 | 中 | 版本控制，灰度发布 |
+   | 历史数据迁移/回填失败 | 高 | 提前准备校验 SQL 与回滚方案；灰度验证 |
+   | 外部回调乱序/重复投递 | 高 | 明确幂等键与业务语义；补齐处理记录与对账点 |
+   | 集成不兼容/调用方影响 | 中 | 明确兼容策略与灰度开关；联调用例覆盖 |
 
    ## 下一步
 
@@ -151,21 +210,72 @@ Phase 4: 任务拆解与排期
 7. **更新状态**
 
    更新 `6aspecdoc/brown/<name>/status.json`：
+
+   **轻量级流程**：
+   ```json
+   {
+     "status": "implement_pending",
+     "flowDepth": "lightweight",
+     "phases": {
+       "proposal": "done",
+       "specs": "done",
+       "design": "done",
+       "tasks": "done",
+       "implement": "pending"
+     },
+     "artifacts": ["proposal.md", "specs.md", "design.md", "tasks-overview.md"],
+     "tasks": {
+       "total": <N>,
+       "completed": 0,
+       "pending": <N>
+     }
+   }
+   ```
+
+   **标准级流程**：
+   ```json
+   {
+     "status": "implement_pending",
+     "flowDepth": "standard",
+     "phases": {
+       "understand": "done",
+       "impact": "done",
+       "proposal": "done",
+       "specs": "done",
+       "design": "done",
+       "tasks": "done",
+       "implement": "pending"
+     },
+     "artifacts": ["understanding.md", "impact-analysis.md", "proposal.md", "specs.md", "design.md", "tasks-overview.md"],
+     "tasks": {
+       "total": <N>,
+       "completed": 0,
+       "pending": <N>
+     }
+   }
+   ```
+
+   **完整级流程**：
    ```json
    {
      "status": "implement_pending",
+     "flowDepth": "complete",
      "phases": {
        "understand": "done",
        "impact": "done",
+       "proposal": "done",
+       "specs": "done",
        "design": "done",
        "tasks": "done",
        "implement": "pending",
-       ...
+       "verify": "blocked",
+       "review": "blocked"
      },
+     "artifacts": ["understanding.md", "impact-analysis.md", "proposal.md", "specs.md", "design.md", "tasks-overview.md"],
      "tasks": {
-       "total": 8,
+       "total": <N>,
        "completed": 0,
-       "pending": 8
+       "pending": <N>
      }
    }
    ```
@@ -177,26 +287,27 @@ Phase 4: 任务拆解与排期
    - 更新"下一步操作"为 `运行 /6aspec:brown:implement 开始执行任务`
    - 在"进度概览"中标记 Tasks 阶段为已完成 `[x]`
 
-**输出**
+---
+
+## 输出
 
 ```
 ## Phase 4 完成：任务拆解
 
 **需求**: <name>
-**进度**: 4/7 阶段完成
+**进度**: <已完成阶段>/<总阶段>
 
 ### 任务统计
 - 总任务数：<数量>
 - 预估总工时：<工时>
 
-### 任务分布
-- 数据层：<数量> 个任务
-- 业务层：<数量> 个任务
-- 表现层：<数量> 个任务
-- 测试：<数量> 个任务
-
-### 关键里程碑
-<列出关键里程碑>
+### 里程碑分布
+- M0 契约与集成准备：<数量> 个任务
+- M1 数据变更准备：<数量> 个任务
+- M2 迁移/兼容/回滚：<数量> 个任务
+- M3 核心链路实现：<数量> 个任务
+- M4 集成联调与可观测性：<数量> 个任务
+- M5 测试与发布准备：<数量> 个任务
 
 ### 文档位置
 - 6aspecdoc/brown/<name>/artifacts/tasks-overview.md
@@ -207,9 +318,14 @@ Phase 4: 任务拆解与排期
 - 或运行 `/6aspec:brown:continue` 自动进入下一阶段
 ```
 
-**防护措施**
-- 必须先完成 Phase 3
-- 任务必须是原子的、可独立完成的
-- 任务依赖关系必须明确
-- 验收标准必须具体
-- 工作量评估要合理
+---
+
+## 防护措施
+
+- 必须先完成 Design 阶段（`phases.design == done`）
+- 任务必须是原子的、可独立完成的；工作量超过 3 人日必须继续拆分
+- 每个任务必须有明确验收标准，并与 Specs 的 AC/Scenario 可追溯
+- 必须覆盖横切能力：Integration / Migration / Compatibility（如设计中涉及）
+- 需要对外/跨模块契约时：出入参字段清单、幂等语义、错误语义必须在对应任务中落地
+- 涉及数据库变更时：改表 DDL/脚本/回滚/校验 SQL 必须作为任务交付物
+- 用户补充信息时只更新文档，不得自动进入下一阶段

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "6aspec",
-  "version": "2.0.0-dev.28",
+  "version": "2.0.0-dev.29",
   "description": "6Aspec - 轻量级 spec 驱动开发框架，支持 Cursor 和 Claude Code",
   "main": "lib/installer.js",
   "bin": {