6aspec 2.0.0-dev.7 → 3.0.0-dev.1

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

@@ -1,6 +1,10 @@
 # 棕地需求 - Understand SOP
 
-Phase 1: 需求理解与现状分析
+需求理解与现状分析
+
+**适用流程**：标准级、完整级
+
+**流程定位**：标准级/完整级的第一阶段，基于需求描述分析现有系统
 
 **输入**：`/6aspec:brown:understand` 后可选需求名称。如果省略，从上下文推断或提示选择。
 
@@ -17,15 +21,19 @@ Phase 1: 需求理解与现状分析
 2. **检查状态**
 
    读取 `6aspecdoc/brown/<name>/status.json`：
-   - 如果 `phases.understand` 不是 "pending"，提示已完成或跳过
-   - 确认需求级别（P0/P1/P2）
-   - P2 需求提示使用 `/6aspec:brown:quick`
+   - 确认流程深度为 "standard" 或 "complete"
+   - 如果是 "lightweight"，提示轻量级流程不需要understand阶段，应该直接运行 `/6aspec:brown:proposal`
+   - 确认 `phases.understand` 为 "pending"
+   - 如果understand已完成，提示使用 `/6aspec:brown:continue` 进入下一阶段
+   - 如果是简单需求，提示考虑使用 `/6aspec:brown:quick` 快速通道
 
 3. **读取需求描述**
 
-   读取 `6aspecdoc/brown/<name>/status.json` 中的 `inputSource` 字段判断输入类型：
-   - `type = "text"`：读取 `requirement.md` 中的"原始需求"部分获取需求描述。
-   - `type = "file"`：读取 `requirement.md` 中记录的来源文件路径，然后读取该文件获取完整需求内容。
+   读取 `6aspecdoc/brown/<name>/artifacts/original-requirement.md` 获取原始需求内容：
+   - 如果 `inputSource.type = "text"`：文档中包含用户输入的原始需求描述
+   - 如果 `inputSource.type = "file"`：文档中包含来源文件路径的引用
+
+   **注意**：Understand 阶段不依赖 proposal，直接基于原始需求分析现有系统
 
 4. **分析现有系统**
 
@@ -64,23 +72,27 @@ Phase 1: 需求理解与现状分析
    - 识别状态机约束
    - 识别权限控制逻辑
 
-5. **记录发现的疑问点**
+5. **生成待明确问题清单**
 
-   基于现状分析，记录在分析过程中发现的疑问点（观察性备注）：
-   - 现有实现中不清楚的地方
-   - 可能影响需求实现的关键点
-   - 需要在 specs 阶段明确的技术或业务细节
+   基于现状分析和需求描述，生成需要用户明确的问题清单：
 
-   注意：这些疑问点是观察性的，不是正式的需求问题清单。正式的需求问题将在 specs 阶段提出。
+   **问题类型**：
+   - 字段设计问题（名称、类型、必填、默认值、值域）
+   - 业务规则问题（是否可修改、是否继承、是否同步）
+   - 权限和统计问题（权限控制、统计报表）
+   - 集成和兼容问题（与其他模块的集成、数据迁移）
+
+   这些问题将在本阶段提出，并引导用户回答，为 specs 阶段的需求定义提供依据。
 
 6. **创建分析文档**
 
-   创建 `6aspecdoc/brown/<name>/artifacts/01-understanding.md`：
+   创建 `6aspecdoc/brown/<name>/artifacts/understanding.md`：
    ```markdown
-   # Phase 1: 需求理解与现状分析
+   # 需求理解与现状分析
 
    > **需求**: <name>
-   > **阶段**: Phase 1 - 现状分析
+   > **流程**: <flowDepth>
+   > **阶段**: Understand
    > **状态**: ✅ 已完成
    > **完成时间**: <timestamp>
 
@@ -118,83 +130,153 @@ Phase 1: 需求理解与现状分析
    ### 1.5 隐性假设和约束
    <列出识别的隐性假设和约束>
 
-   ## 2. 发现的疑问点
-
-   基于现状分析，记录以下疑问点（这些疑问点将在 specs 阶段转化为正式的需求问题）：
+   ## 2. 待明确问题清单
 
-   ### 技术实现相关
-   - <现有实现中不清楚的地方>
+   ### 字段设计
+   1. 字段名称：[待确认]
+   2. 字段类型：[待确认]
+   3. 是否必填：[待确认]
+   4. 默认值：[待确认]
+   5. 值域范围：[待确认]
 
-   ### 业务逻辑相关
-   - <可能影响需求实现的关键点>
+   ### 业务规则
+   6. 是否可以修改：[待确认]
+   7. 子项目是否继承：[待确认]
+   8. 是否需要同步到其他表：[待确认]
 
-   ### 数据和集成相关
-   - <需要在 specs 阶段明确的技术或业务细节>
+   ### 权限和统计
+   9. 是否需要权限控制：[待确认]
+   10. 是否需要统计报表：[待确认]
 
    ## 3. 下一步
 
-   运行 `/6aspec:brown:specs` 进入需求规格定义阶段，在该阶段将提出正式的需求问题并定义系统应该具备的能力。
+   请回答上述待明确问题，然后运行 `/6aspec:brown:specs` 定义需求规格。
    ```
 
 7. **更新状态**
 
    更新 `6aspecdoc/brown/<name>/status.json`：
+
+   **标准级流程**：
    ```json
    {
-     "status": "specs_pending",
+     "status": "impact_pending",
+     "flowDepth": "standard",
      "phases": {
+       "proposal": "done",
        "understand": "done",
-       "specs": "pending",
-       "impact": "blocked",
-       ...
+       "impact": "pending",
+       "specs": "blocked",
+       "design": "blocked",
+       "tasks": "blocked",
+       "implement": "blocked"
      },
-     "artifacts": ["01-understanding.md"]
+     "artifacts": ["proposal.md", "understanding.md"]
    }
    ```
 
+   **完整级流程**：
+   ```json
+   {
+     "status": "impact_pending",
+     "flowDepth": "complete",
+     "phases": {
+       "proposal": "done",
+       "understand": "done",
+       "impact": "pending",
+       "specs": "blocked",
+       "design": "blocked",
+       "tasks": "blocked",
+       "implement": "blocked",
+       "verify": "blocked",
+       "review": "blocked"
+     },
+     "artifacts": ["proposal.md", "understanding.md"]
+   }
+   ```
+
+   同时更新 `6aspecdoc/brown/<name>/requirement.md`：
+   - 更新"状态"字段为 `📋 Impact 待开始`
+   - 更新"最后修改"时间戳为 `<timestamp>`
+   - 更新"当前阶段"为 `Understand - 需求理解与现状分析（已完成）`
+   - 更新"下一步操作"为 `运行 /6aspec:brown:impact 继续下一阶段`
+   - 在"进度概览"中标记 Understand 阶段为已完成 `[x]`
+
 8. **停止并等待用户指令**
 
 **输出**
 
-完成后，显示：
+根据 `flowDepth` 显示不同的输出信息：
+
+**标准级流程**：
+```
+## Understand 完成：<name>
+
+**流程**: 标准级
+**进度**: 2/6 阶段完成
+
+### 分析结果
+- 相关实体类：<数量>
+- 相关服务类：<数量>
+- 数据库表：<数量>
+- 待明确问题：<数量>
+
+### 关键发现
+<列出 2-3 个关键发现>
+
+### 待明确问题（重要）
+<列出最重要的 3-5 个问题>
+
+### 文档位置
+6aspecdoc/brown/<name>/artifacts/understanding.md
+
+### 下一步
+- 直接回答上述待明确问题 → 我会更新本阶段文档（understanding.md）中的问题答案
+- 运行 `/6aspec:brown:impact` → 进入影响面分析阶段
+- 运行 `/6aspec:brown:continue` → 自动进入下一阶段
+```
+
+**完整级流程**：
 ```
-## Phase 1 完成：现状分析
+## Understand 完成：<name>
 
-**需求**: <name>
-**进度**: 1/7 阶段完成
+**流程**: 完整级
+**进度**: 2/8 阶段完成
 
 ### 分析结果
 - 相关实体类：<数量>
 - 相关服务类：<数量>
 - 数据库表：<数量>
-- 发现的疑问点：<数量>
+- 待明确问题：<数量>
 
 ### 关键发现
 <列出 2-3 个关键发现>
 
-### 发现的疑问点
-<列出主要的疑问点>
+### 待明确问题（重要）
+<列出最重要的 3-5 个问题>
 
 ### 文档位置
-6aspecdoc/brown/<name>/artifacts/01-understanding.md
+6aspecdoc/brown/<name>/artifacts/understanding.md
 
 ### 下一步
-- 直接补充现状分析信息 → 我会更新本阶段文档（01-understanding.md）
-- 运行 `/6aspec:brown:specs` → 进入需求规格定义阶段（将提出正式的需求问题）
+- 直接回答上述待明确问题 → 我会更新本阶段文档（understanding.md）中的问题答案
+- 运行 `/6aspec:brown:impact` → 进入影响面分析阶段
 - 运行 `/6aspec:brown:continue` → 自动进入下一阶段
 ```
 
 **用户补充信息时的处理**
 
-当用户补充现状分析信息时（未使用阶段命令）：
-1. 将用户的补充整合到 `01-understanding.md` 的相关章节
-2. 如果补充引发新的发现或疑问点，同步更新文档
-3. 展示变更摘要（更新了哪些内容、新增了哪些发现）
+当用户回答待明确问题或补充需求信息时（未使用阶段命令）：
+1. 将用户的回答整合到 `understanding.md` 中对应的问题项（将"[待确认]"替换为实际答案）
+2. 如果回答引发新的发现或问题，同步更新文档的相关章节
+3. 展示变更摘要（更新了哪些问题的答案、新增了哪些发现）
 4. 再次提示：可以继续补充，或通过命令进入下一阶段
 5. **禁止**：不得自动进入下一阶段
 
 **防护措施**
+- 只适用于标准级和完整级流程
+- 必须先完成proposal阶段
 - 必须先读取需求描述再开始分析
 - 如果找不到相关代码，询问用户提供更多关键词
 - 如果分析不充分，不要强行生成文档，而是询问用户
-- 发现的疑问点应该是观察性的，不是正式的需求问题
+- 待明确问题必须具体，避免模糊问题

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

@@ -0,0 +1,283 @@
+# 棕地需求 - Update SOP
+
+非破坏性地更新指定阶段的文档，支持简单模式和智能模式。
+
+**输入**：
+- `/6aspec:brown:update <requirement-name> <phase>` - 简单更新（默认）
+- `/6aspec:brown:update <requirement-name> <phase> --smart` - 智能更新
+- `/6aspec:brown:update <requirement-name> --history` - 查看更新历史
+
+**适用场景**：
+- ✅ 补充遗漏的信息
+- ✅ 修正错别字、格式问题
+- ✅ 澄清模糊的描述
+- ✅ 添加新的考虑因素（不推翻原有决策）
+- ✅ 调整优先级、时间估算等非核心内容
+- ✅ 修正小的技术细节
+
+**不适用场景（建议使用 rollback）**：
+- ❌ 推翻核心决策（如技术方案选型）
+- ❌ 发现前面阶段的分析有重大错误
+- ❌ 需求发生根本性变化
+- ❌ 影响范围太大，难以准确识别
+- ❌ 需要重新思考整个方案
+
+**支持的阶段**：
+- `analyze` - 需求分析（相对稳定，不常需要 update）
+- `proposal` - 需求提案（常见 update 场景）
+- `specs` - 需求规格（常见 update 场景）
+- `design` - 技术设计（常见 update 场景）
+- `tasks` - 任务拆解（常见 update 场景）
+
+**限制**：
+- 只能更新已完成的阶段（状态为 "done"）
+- 不能更新已归档的需求
+- 不能更新不存在的阶段文档
+- 在实施阶段（implement、verify、review）使用时需要特别小心
+
+**步骤**
+
+1. **选择需求**
+
+   如果提供了名称，使用它。否则：
+   - 从对话上下文推断
+   - 如果模糊，读取 `6aspecdoc/brown/` 目录，让用户选择
+
+2. **处理特殊选项**
+
+   **如果是 `--history` 选项**：
+   - 读取 `6aspecdoc/brown/<name>/artifacts/` 目录下的所有文档
+   - 提取每个文档末尾的"修改记录"部分
+   - 按时间顺序汇总显示所有更新历史
+   - 显示统计信息（总更新次数、最近更新时间等）
+   - 停止执行
+
+3. **检查当前状态**
+
+   读取 `6aspecdoc/brown/<name>/status.json`：
+   - 确认需求未归档
+   - 确认目标阶段存在且状态为 "done"
+   - 确认对应的文档文件存在
+
+4. **读取目标文档**
+
+   根据阶段名称读取对应文档：
+   - `analyze` → `artifacts/analysis.md`
+   - `proposal` → `artifacts/proposal.md`
+   - `specs` → `artifacts/specs.md`
+   - `design` → `artifacts/design.md`
+   - `tasks` → `artifacts/tasks-overview.md`
+
+5. **获取用户修改需求**
+
+   询问用户要修改的内容：
+   ```
+   问题："请描述您要对 <phase> 阶段文档进行的修改："
+
+   提示：
+   - 请具体描述要修改、补充或调整的内容
+   - 如果是补充信息，请说明要补充什么
+   - 如果是修正错误，请说明错误的地方和正确的内容
+   - 如果是调整描述，请说明要如何调整
+   ```
+
+6. **执行更新（根据模式）**
+
+   **简单模式（默认）**：
+
+   a. 根据用户描述修改目标文档
+
+   b. 在文档末尾添加或更新修改记录：
+   ```markdown
+   ## 修改记录
+   - 2026-02-27 10:30: <修改描述>（update）
+   ```
+
+   c. 分析可能受影响的后续文档，生成检查清单
+
+   d. 更新 status.json 中的 lastUpdate
+
+   e. 显示检查清单，提示用户手动检查后续文档
+
+   **智能模式（--smart）**：
+
+   a. 分析修改内容对后续文档的影响范围
+
+   b. 读取所有可能受影响的后续文档
+
+   c. 生成详细的更新计划：
+   ```markdown
+   ## 更新计划
+
+   ### 修改内容
+   - <phase>.md: <修改描述>
+
+   ### 影响分析
+   - <后续文档1>: 需要更新"<具体部分>"
+     - 位置：第 X.Y 节
+     - 修改：<具体修改内容>
+   - <后续文档2>: 不需要修改
+
+   ### 风险评估
+   - <风险级别>：<风险描述>
+   - 建议：<执行建议>
+   ```
+
+   d. **等待用户确认**：
+   ```
+   问题："是否执行上述更新计划？"
+   选项：
+   - 确认执行更新
+   - 取消
+   ```
+
+   e. 如果用户确认，批量执行所有更新：
+   - 修改目标文档
+   - 更新所有受影响的后续文档
+   - 在每个修改的文档末尾添加修改记录
+
+   f. 生成更新报告
+
+7. **更新状态记录**
+
+   更新 `6aspecdoc/brown/<name>/status.json`：
+
+   a. 更新 `lastModified` 时间戳
+
+   b. 更新 `lastUpdate` 记录：
+   ```json
+   "lastUpdate": {
+     "phase": "<phase>",
+     "timestamp": "<时间戳>",
+     "description": "<修改描述>",
+     "affectedPhases": ["<阶段1>", "<阶段2>"],
+     "mode": "simple|smart"
+   }
+   ```
+
+8. **显示更新结果**
+
+**输出**
+
+**简单模式输出**：
+```
+## 更新完成：<name>
+
+**更新阶段**: <phase>
+**更新时间**: <时间戳>
+**更新模式**: 简单模式
+
+### 修改内容
+<修改描述>
+
+### 影响分析和检查清单
+
+#### 可能受影响的文档
+- [ ] <文档1>: <检查要点>
+- [ ] <文档2>: <检查要点>
+
+#### 建议
+<具体检查建议>
+
+### 下一步
+请根据检查清单逐一检查可能受影响的文档，必要时手动调整。
+```
+
+**智能模式输出**：
+```
+## 更新完成：<name>
+
+**更新阶段**: <phase>
+**更新时间**: <时间戳>
+**更新模式**: 智能模式
+
+### 修改内容
+<修改描述>
+
+### 联动更新
+- <文档1>: <更新内容>
+- <文档2>: <更新内容>
+
+### 修改摘要
+- 共修改 N 个文件
+- 新增 X 字
+- 修改 Y 处
+
+### 建议
+请人工复查关键文档，确认修改内容符合预期。
+```
+
+**历史查看输出**：
+```
+## 更新历史：<name>
+
+### 更新记录
+1. **2026-02-27 10:30** - proposal
+   - 描述：补充业务背景说明
+
+2. **2026-02-26 15:20** - specs
+   - 描述：调整性能指标要求
+
+### 统计
+- 总更新次数：2
+- 最近更新：2026-02-27 10:30
+- 涉及阶段：proposal, specs
+```
+
+**依赖关系和影响分析规则**
+
+根据文档依赖关系确定影响范围：
+
+```
+analyze (需求分析)
+  ↓
+proposal (Why, What, Impact)
+  ↓
+specs (功能需求、验收标准)
+  ↓
+design (技术方案)
+  ↓
+tasks (任务拆解)
+  ↓
+implement (代码实现)
+```
+
+**影响分析矩阵**：
+
+| 修改位置 | 可能影响的文档 | 影响程度 | 检查重点 |
+|---------|--------------|---------|---------|
+| analyze.现状 | proposal | 中 | 需求背景、影响面 |
+| analyze.影响面 | proposal, design | 中 | 需求范围、非功能需求 |
+| proposal.Why | specs, design | 中 | 优先级、技术选型 |
+| proposal.What | specs, design, tasks | 高 | 功能需求、技术方案、任务拆解 |
+| proposal.Impact | design | 低 | 非功能需求 |
+| specs.功能需求 | design, tasks | 高 | 技术方案、任务拆解 |
+| specs.验收标准 | tasks | 中 | 任务定义、测试用例 |
+| design.技术方案 | tasks | 高 | 任务拆解、工作量估算 |
+| design.技术选型 | tasks | 中 | 技术栈、工作量估算 |
+
+**防护措施**
+- 必须确认需求未归档
+- 必须确认目标阶段已完成（状态为 "done"）
+- 必须确认对应文档文件存在
+- 智能模式必须等待用户确认后才执行更新
+- 在实施阶段使用时特别提示代码一致性问题
+- 记录所有更新历史，支持追溯
+- 生成的检查清单必须具体明确
+- 智能模式的影响分析必须准确，避免误判
+
+**错误处理**
+
+- 如果需求不存在，提示创建新需求
+- 如果需求已归档，提示先取消归档
+- 如果目标阶段不存在或未完成，提示阶段状态
+- 如果对应文档文件不存在，提示文件缺失
+- 如果在实施阶段使用，特别提示：
+  ```
+  ⚠️  警告：当前需求处于实施阶段，更新文档后请检查代码是否需要相应调整。
+  如果修改影响代码实现，建议使用 rollback 或创建新需求。
+  ```
+- 如果智能模式影响分析失败，降级为简单模式
+- 如果用户取消智能模式的更新计划，停止执行
+- 如果文档修改失败，回滚已修改的文件并报告错误
+- 如果--history选项找不到修改记录，显示"暂无更新历史"