6a-spec-install 1.0.7 → 1.0.8-dev.2

package/.6aspec/rules/green/6A_archive_sop.md

@@ -0,0 +1,301 @@
+# 绿地需求归档 SOP
+
+## 目标
+
+归档已完成的绿地需求，将需求目录移动到归档位置，并更新状态。
+
+## 前置条件
+
+- 需求的所有工件已完成
+- 需求的所有任务已完成
+- 需求状态为 `completed`
+
+## 执行步骤
+
+### Step 1: 检测当前需求
+
+**1.1 检查是否在需求目录下**
+
+检查当前工作目录是否在 `6aspec/green/<feature-name>/` 下：
+
+```bash
+pwd
+```
+
+如果在需求目录下，自动识别需求名称（从路径中提取）。
+
+**1.2 如果不在需求目录下，列出所有可归档的需求**
+
+```bash
+find 6aspec/green -maxdepth 2 -name ".green-status.json" -type f
+```
+
+读取每个状态文件，筛选出状态为 `completed` 的需求。
+
+如果找到多个可归档的需求，使用 **AskUserQuestion** 让用户选择要归档的需求。
+
+选项应该显示：
+- 需求名称
+- 完成时间
+- 任务完成情况（如：8/8 任务已完成）
+
+如果没有找到任何可归档的需求，输出：
+```
+未找到可归档的需求。
+
+只有状态为 "completed" 的需求才能归档。
+
+运行 /6aspec:green:status 查看当前需求状态。
+```
+
+### Step 2: 读取状态文件
+
+读取 `6aspec/green/<feature-name>/.green-status.json` 文件。
+
+如果文件不存在或格式错误，输出错误信息并退出。
+
+### Step 3: 检查归档条件
+
+**3.1 检查工件完成状态**
+
+检查状态文件中的 `artifacts` 字段，确认所有工件的状态都是 `done`：
+
+```json
+{
+  "artifacts": {
+    "requirement": { "status": "done" },
+    "models": { "status": "done" },
+    "design": { "status": "done" },
+    "tasks": { "status": "done" }
+  }
+}
+```
+
+如果有任何工件状态不是 `done`，**拒绝归档**，停止并提示：
+
+```
+❌ 未通过依赖检查，不允许归档
+
+存在未完成的工件：
+- <artifact-name>: <status>
+
+请先完成主流程中对应步骤（new → model → design → tasks），待所有工件状态为 done 后再运行 /6aspec:green:archive。
+```
+
+**3.2 检查任务完成状态**
+
+检查状态文件中的 `tasks` 字段：
+
+```json
+{
+  "tasks": {
+    "total": 8,
+    "completed": 8,
+    "remaining": 0
+  }
+}
+```
+
+如果 `completed` < `total`，**拒绝归档**，停止并提示：
+
+```
+❌ 未通过依赖检查，不允许归档
+
+任务进度：<completed>/<total> 已完成，剩余 <remaining> 个任务未完成。
+
+请先运行 /6aspec:green:execute-task 完成所有任务，待状态变为 completed 后再运行 /6aspec:green:archive。
+```
+
+**3.3 检查状态（硬性门禁）**
+
+如果状态不是 `completed`，**拒绝归档**，不得提供“仍要继续”选项，直接停止并提示：
+
+```
+❌ 未通过依赖检查，不允许归档
+
+当前状态：<current-status>
+要求状态：completed（所有任务已完成）
+
+归档前必须完成主流程至“所有任务已完成”。请先运行 /6aspec:green:execute-task 完成剩余任务，待状态变为 completed 后再运行 /6aspec:green:archive。
+```
+
+### Step 4: 执行归档
+
+**4.1 创建归档目录**
+
+如果归档目录不存在，创建它：
+
+```bash
+mkdir -p 6aspec/green/archive
+```
+
+**4.2 生成归档目标名称**
+
+使用当前日期和需求名称生成归档目标名称：
+
+格式：`YYYY-MM-DD-<feature-name>`
+
+例如：`2026-02-16-user-authentication`
+
+**4.3 检查目标是否已存在**
+
+检查归档目标目录是否已存在：
+
+```bash
+ls -d 6aspec/green/archive/YYYY-MM-DD-<feature-name> 2>/dev/null
+```
+
+如果已存在，输出错误并停止：
+
+```
+❌ 归档失败
+
+目标目录已存在：6aspec/green/archive/YYYY-MM-DD-<feature-name>
+
+可能的原因：
+1. 今天已经归档过同名需求
+2. 归档目录中存在重复
+
+建议：
+1. 重命名现有归档目录
+2. 删除现有归档（如果是重复的）
+3. 等到明天再归档
+```
+
+**4.4 移动需求目录**
+
+将需求目录移动到归档位置：
+
+```bash
+mv 6aspec/green/<feature-name> 6aspec/green/archive/YYYY-MM-DD-<feature-name>
+```
+
+**4.5 更新状态文件**
+
+读取归档后的状态文件，更新状态：
+
+```json
+{
+  "status": "archived",
+  "lastModified": "<current-timestamp>"
+}
+```
+
+写回状态文件：
+
+```bash
+# 更新 6aspec/green/archive/YYYY-MM-DD-<feature-name>/.green-status.json
+```
+
+### Step 5: 显示归档摘要
+
+输出归档完成的摘要信息：
+
+```
+✅ 归档完成
+
+需求：<feature-name>
+归档位置：6aspec/green/archive/YYYY-MM-DD-<feature-name>/
+归档时间：<current-timestamp>
+
+工件完成情况：
+✓ 需求澄清文档
+✓ 领域模型
+✓ 技术方案
+✓ 任务列表
+
+任务完成情况：
+✓ 所有任务已完成 (<total>/<total>)
+
+状态：已归档
+```
+
+如果有警告（如未完成的工件或任务），在摘要中显示：
+
+```
+✅ 归档完成（带警告）
+
+需求：<feature-name>
+归档位置：6aspec/green/archive/YYYY-MM-DD-<feature-name>/
+归档时间：<current-timestamp>
+
+⚠️  警告：
+- 归档时有 <N> 个工件未完成
+- 归档时有 <M> 个任务未完成
+
+请检查归档内容是否符合预期。
+```
+
+## 错误处理
+
+### 错误 1: 状态文件不存在
+
+```
+错误：未找到状态文件
+
+路径：6aspec/green/<feature-name>/.green-status.json
+
+无法归档没有状态文件的需求。
+
+建议：
+1. 检查需求目录是否正确
+2. 手动创建状态文件（参考 green_status_schema.md）
+```
+
+### 错误 2: 归档目录已存在
+
+```
+错误：归档目标已存在
+
+目标：6aspec/green/archive/YYYY-MM-DD-<feature-name>/
+
+建议：
+1. 重命名现有归档目录
+2. 删除现有归档（如果是重复的）
+3. 等到明天再归档
+```
+
+### 错误 3: 移动失败
+
+```
+错误：无法移动需求目录
+
+源：6aspec/green/<feature-name>
+目标：6aspec/green/archive/YYYY-MM-DD-<feature-name>
+
+错误信息：<error-message>
+
+请检查文件权限和磁盘空间。
+```
+
+## 注意事项
+
+1. **不可逆操作**：归档是移动操作，不是复制。归档后原位置的需求目录将不存在
+2. **状态检查**：归档前会检查工件和任务完成状态，但允许用户强制归档
+3. **日期命名**：使用日期前缀可以方便地按时间排序归档
+4. **状态更新**：归档后状态文件会被更新为 `archived`
+5. **保留结构**：归档时保留完整的需求目录结构，包括所有文件和子目录
+
+## 归档后的目录结构
+
+```
+6aspec/green/
+├── archive/
+│   ├── 2026-02-15-feature-a/
+│   │   ├── .green-status.json
+│   │   ├── requirement.md
+│   │   ├── domain-model.md
+│   │   ├── tech-design.md
+│   │   ├── api-definition.md
+│   │   ├── tasks/
+│   │   └── ...
+│   └── 2026-02-16-feature-b/
+│       └── ...
+└── active-feature/
+    └── ...
+```
+
+## 参考文档
+
+- 状态文件结构定义：`.6aspec/rules/green/green_status_schema.md`
+- 状态查询SOP：`.6aspec/rules/green/6A_status_sop.md`

package/.6aspec/rules/green/6A_clarify_sop.md

@@ -0,0 +1,229 @@
+# clarify: 需求深化澄清标准操作流程 (Requirement Clarification SOP)
+
+## 角色
+你现在的角色是【需求分析师 + 业务架构师】，负责对已有的需求澄清文档进行深化、补充和细化。你善于发现隐藏的业务复杂性，通过反向提问帮助团队在编码前消除认知盲区。
+
+## 目标
+- 基于已有的 `requirement.md`，进一步深化需求的细节和边界
+- 解决上一轮遗留的"待确认项"
+- 识别新的风险点和模糊地带
+- 补充用户提供的新信息或补充文档
+- 确保需求文档达到可支撑领域建模的质量
+
+## 规则
+1. **增量更新**：在现有 `requirement.md` 基础上增补，不重写已确认的内容
+2. **反向提问**：每轮必须主动提出 3-5 个新的或更深入的问题
+3. **深度递进**：比 `new` 阶段的提问更加深入和具体，聚焦在实现层面的细节
+4. **可迭代**：`clarify` 命令可以多次执行，逐步深化
+
+## 前置条件
+- 已通过 `/6aspec:green:new` 创建了需求目录和初始 `requirement.md`
+- 状态文件 `.green-status.json` 存在
+
+## 输入要求
+- **自动读取**：现有的 `requirement.md` 和 `.green-status.json`
+- **可选输入**：用户提供的补充文档、业务确认结果、新的需求变更等
+
+## 执行步骤
+
+### Step 1: 读取现有状态和文档
+
+**1.1 检测需求目录**
+
+检查当前活跃的需求：
+
+```bash
+find 6aspec/green -maxdepth 2 -name ".green-status.json" -type f
+```
+
+如果有多个需求，使用 **AskUserQuestion** 让用户选择要澄清的需求。
+
+**1.2 读取状态文件和需求文档**
+
+- 读取 `6aspec/green/<feature-name>/.green-status.json`
+- 读取 `6aspec/green/<feature-name>/requirement.md`
+
+**1.3 状态检查**
+
+允许的状态：`created` 或 `requirement_clarified`
+
+如果状态不符合，输出：
+```
+⚠️ 当前状态为 <status>，通常在 "created" 或 "requirement_clarified" 阶段执行 clarify。
+
+是否继续？（在后续阶段执行 clarify 会更新需求文档但不会回退状态）
+```
+
+### Step 2: 分析现有文档的薄弱环节
+
+阅读现有 `requirement.md`，按以下维度评估文档质量：
+
+| 评估维度 | 检查项 | 评级 |
+| :--- | :--- | :--- |
+| **完整性** | 功能清单是否覆盖 PRD 所有要求 | 🟢充分 / 🟡部分 / 🔴缺失 |
+| **精确性** | 业务规则是否足够具体可实现 | 🟢充分 / 🟡部分 / 🔴缺失 |
+| **一致性** | 各章节描述是否存在矛盾 | 🟢一致 / 🟡有疑问 / 🔴矛盾 |
+| **可建模性** | 是否具备领域建模所需的信息 | 🟢就绪 / 🟡接近 / 🔴不足 |
+| **待确认项** | 遗留的 TBD 项是否已解决 | 🟢全部解决 / 🟡部分解决 / 🔴未解决 |
+
+输出评估结果：
+
+```markdown
+## 📋 需求文档质量评估
+
+| 维度 | 评级 | 说明 |
+| :--- | :--- | :--- |
+| 完整性 | 🟢/🟡/🔴 | <说明> |
+| 精确性 | 🟢/🟡/🔴 | <说明> |
+| 一致性 | 🟢/🟡/🔴 | <说明> |
+| 可建模性 | 🟢/🟡/🔴 | <说明> |
+| 待确认项 | 🟢/🟡/🔴 | <N 个 TBD 项中已解决 M 个> |
+
+**总体评估**：<就绪 / 接近就绪 / 需要继续澄清>
+```
+
+### Step 3: 反向提问（深化版）
+
+基于 Step 2 的评估结果，AI 必须主动提出 **3-5 个更深入的问题**。
+
+#### 深化提问的聚焦方向
+
+| 方向 | 说明 | 示例 |
+| :--- | :--- | :--- |
+| **状态机细化** | 业务对象的状态流转细节 | "合同从'待审批'到'已生效'之间，是否有'审批中'的中间态？审批需要几级？" |
+| **边界值明确** | 业务规则的精确边界 | "优惠金额的计算精度是保留几位小数？四舍五入还是向下取整？" |
+| **异常流程补全** | 异常场景的处理方式 | "如果支付超时，订单状态如何处理？是否需要自动取消？取消后的退款策略是？" |
+| **数据生命周期** | 数据的创建、变更和归档 | "历史评价数据保留多久？是否需要定期归档？归档后是否可查询？" |
+| **权限粒度** | 操作权限的细节 | "管理员是否可以修改已提交的评价？修改后是否需要留痕？" |
+| **并发与冲突** | 多人操作的冲突处理 | "如果两人同时编辑同一条记录，以谁的为准？是否需要乐观锁？" |
+
+#### 提问格式
+
+```markdown
+---
+
+## 🔍 需求深化确认（第 N 轮）
+
+基于对现有需求文档的分析，以下问题需要进一步确认：
+
+### Q1: [问题标题]
+**聚焦方向**：状态机细化 / 边界值明确 / 异常流程补全 / 数据生命周期 / 权限粒度 / 并发与冲突
+**关联章节**：requirement.md 第X章
+**当前描述**：<现有文档中的相关描述>
+**深化问题**：<具体问题>
+**AI 建议**：<基于业界最佳实践的建议，供参考>
+
+### Q2: [问题标题]
+...
+
+---
+
+请确认以上问题。对于暂时无法确认的，可标记为"待确认"。
+```
+
+**重要**：必须等待用户回复后再继续。
+
+### Step 4: 更新需求澄清文档
+
+根据用户的回答，**增量更新** `requirement.md`：
+
+1. **补充已确认的内容**：将用户的确认结果更新到对应章节
+2. **更新待确认项**：
+   - 已确认的 TBD 项：状态改为"已确认"，并将结论写入对应章节
+   - 新增的 TBD 项：追加到待确认项列表
+3. **追加澄清记录**：在"9.2 需求澄清记录"中追加本轮的问答记录
+
+### Step 5: 更新状态文件
+
+根据当前文档质量，更新 `.green-status.json`：
+
+**情况 A：需求已充分澄清（无核心 TBD 项，可建模性评估为"就绪"）**
+
+```json
+{
+  "status": "requirement_clarified",
+  "lastModified": "<ISO8601-now>",
+  "artifacts": {
+    "requirement": {
+      "status": "done",
+      "completedAt": "<ISO8601-now>"
+    },
+    "models": {
+      "status": "ready"
+    }
+  },
+  "nextAction": {
+    "command": "model",
+    "description": "开始领域建模"
+  }
+}
+```
+
+**情况 B：仍需继续澄清（有核心 TBD 项未解决）**
+
+```json
+{
+  "status": "created",
+  "lastModified": "<ISO8601-now>",
+  "artifacts": {
+    "requirement": {
+      "status": "pending"
+    }
+  },
+  "nextAction": {
+    "command": "clarify",
+    "description": "继续需求澄清（有 N 个核心待确认项）"
+  }
+}
+```
+
+## 输出要求
+1. 格式：Markdown 源码格式
+2. 文档位置：`6aspec/green/<feature-name>/requirement.md`（原地更新）
+3. 必须保留已有内容，仅做增量更新
+4. 更新后检查文档格式是否符合 `new` SOP 中的模板规范
+
+## 注意
+- **不可覆盖**：绝不可覆盖用户之前已确认的结论，只能追加新信息
+- **递进深入**：每一轮 clarify 的问题应该比上一轮更深入、更具体
+- **适时收敛**：如果评估所有维度都是 🟢，应主动建议用户进入下一步（领域建模），而不是无限制地继续澄清
+- **溯源标注**：新增内容必须标注来源（"第N轮 clarify 确认"）
+
+## 流程完成提示 (Workflow Progress)
+
+**重要提示**：本节内容仅用于向用户输出流程进度提示，**不要写入任何文档文件**。
+
+### 情况 A：需求已充分澄清
+
+---
+
+✅ **已完成：需求深化澄清 (clarify)**
+
+📊 **进度：0/4 (主流程)**
+
+**需求文档已就绪，建议进入下一步：**
+- 【主流程】领域建模：命令 `model`
+  基于需求澄清文档进行领域模型和数据库设计
+
+**完整流程图：**
+```
+主流程：需求澄清 ✅ → 领域建模 → 技术方案 → 任务生成 → 执行任务 (0/4)
+```
+
+---
+
+### 情况 B：仍需继续澄清
+
+---
+
+⏳ **需求澄清进行中 (clarify)**
+
+📊 **进度：0/4 (主流程)**
+
+**待确认项：N 个**（其中核心项 M 个）
+
+**下一步建议：**
+- 与产品/业务方确认待确认项后，再次运行 `clarify`
+- 如果评估风险可控，也可以直接进入 `model`
+
+---

package/.6aspec/rules/green/6A_code_implementation_sop.md

@@ -0,0 +1,110 @@
+---
+description: 任务代码实现标准操作流程 (Code Implementation SOP)
+alwaysApply: false
+---
+
+# execute-task: 任务代码实现标准操作流程
+
+你现在是 **Senior Developer**，负责执行具体的开发任务。你的核心职责是将 `6aspec/green/<feature-name>/tasks/task_xxx.md` 转化为高质量、可运行的业务代码。
+
+## 前置条件（依赖门禁，必须首先执行）
+
+在执行任务代码实现前，**必须**先完成依赖检查，不通过则**立即停止**并提示，不得继续：
+
+1. **确定当前需求**：根据用户指定的任务文件路径（如 `6aspec/green/<feature-name>/tasks/task-xxx.md`）确定 feature-name；若用户未指定任务文件，则根据当前工作目录或让用户选择需求。
+2. **读取状态文件**：读取 `6aspec/green/<feature-name>/.green-status.json`。若文件不存在，停止并提示先运行 `/6aspec:green:new` 创建需求。
+3. **检查上一流程已完成**：
+   - 若 `status` 不是 `tasks_created` 且不是 `implementing`，停止并提示：
+     ```
+     ❌ 未通过依赖检查，无法执行开发任务
+
+     当前状态：<status>
+     要求状态：tasks_created 或 implementing（任务已拆解或实施中）
+
+     请先完成任务拆解：运行 /6aspec:green:tasks，并确保生成 tasks/ 下的任务文件及 README.md，且状态已更新为 tasks_created。
+     ```
+   - 若 `artifacts.tasks.status` 不是 `done`，停止并提示先运行 `/6aspec:green:tasks` 完成任务拆解。
+4. **检查任务目录存在**：若 `6aspec/green/<feature-name>/tasks/` 下无任务文件或无 `README.md`，停止并提示先完成 `/6aspec:green:tasks`。
+
+**只有以上检查全部通过后，才允许继续执行本 SOP 的编码步骤。**
+
+## 0. 执行协议 (Protocol) - 拒绝盲目编码
+
+在开始编写代码前，**必须**执行以下上下文加载步骤（Context Loading）：
+
+1.  **加载任务上下文**：读取用户指定的 `task-xxx.md` 文件。
+2.  **加载设计上下文**：
+    *   必须寻找并读取该任务所属功能的 **技术设计主文档** (`tech-design.md`)，位于同需求目录下 `artifacts/`：`6aspec/green/<feature-name>/artifacts/tech-design.md`。
+    *   必须读取 **API 定义文档** (`api-definition.md`)（如果是 API 任务），位于 `6aspec/green/<feature-name>/artifacts/api-definition.md`。
+    *   *Rationale*: 任务文件中只包含摘要，核心逻辑和 JSON 结构都在技术设计文档中，不读技术设计文档必写错。
+3.  **加载规范上下文**：
+    *   读取任务文件中指定的“规则文件”（如 `api_rule.md`）。
+    *   读取公共代码规约 `.6aspec/rules/biz/code.md` 和 `.6aspec/rules/biz/project-structure.md`。
+
+## 1. 实现策略 (Implementation Strategy)
+
+请严格按照 **自底向上 (Bottom-Up)** 的顺序进行编码，以减少依赖错误：
+
+### Step 1: 领域对象与数据传输对象 (DTO/VO/Enum)
+- 优先定义 Request/Response DTO、Enums、Events。
+- **约束**：字段名称和类型必须严格匹配 `api-definition.md` 和技术设计文档。
+
+### Step 2: 基础设施层 (Repository/Gateway)
+- 检查所需的 Repository 接口是否存在。
+- 如果需要调用外部服务，实现对应的 Facade/Gateway。
+
+### Step 3: 核心业务逻辑 (Service/Domain)
+- 实现 Service 方法。
+- **关键**：严格翻译技术设计文档中的"执行逻辑"和"核心技术决策"。
+    - 如果技术设计文档说要加锁，必须加锁。
+    - 如果技术设计文档说要抛特定异常，必须抛出。
+
+### Step 4: 接口层 (Controller/Listener/Job)
+- 组装 Service，暴露对外的入口。
+- 添加必要的注解（Swagger, Auth, Validation）。
+
+## 2. 质量控制 (Quality Control)
+
+在输出代码后，必须进行自我审查：
+1.  **Lint 检查**：运行 `read_lints` 检查新文件，修复所有 Import 错误和语法错误。
+2.  **不写测试**：严禁编写 `src/test` 下的单元测试代码（除非用户明确要求）。
+3.  **不修改无关文件**：严禁修改与本任务无关的现有代码（除非是必要的 Entity 关联更新）。
+
+## 3. 任务收尾 (Task Closure)
+
+代码实现完成后，**必须**更新文档状态：
+
+1.  **更新任务文件** (`task-xxx.md`)：
+    - 将状态改为 `[已完成]`。
+    - 更新 `最后更新时间`。
+2.  **更新总览文件** (`tasks/README.md`)：
+    - 寻找该任务在列表中的行，将状态图标改为 ✅。
+    - 更新进度条和已完成工时统计。
+
+## 异常处理
+- 如果发现技术设计文档在代码层面无法实现（如循环依赖、技术设计文档参数缺失），**停止编码**，向用户报告并建议修改技术设计文档。
+
+## 流程完成提示 (Workflow Progress)
+
+**重要提示**：本节内容仅用于向用户输出流程进度提示，**不要写入任何文档文件**。
+
+当完成本 SOP 流程后，必须向用户输出以下流程进度提示：
+
+---
+
+✅ **已完成：执行开发任务 (execute-task)**
+
+📊 **进度：4/4 (主流程) - 全部完成！🎉**
+
+**任务状态：**
+- 当前任务已完成，请检查 `tasks/README.md` 查看整体进度
+- 如还有未完成的任务，继续执行 `execute-task` 命令
+- 如所有任务已完成，恭喜！整个开发流程已完成
+
+**完整流程图：**
+```
+主流程：领域建模 ✅ → 技术方案 ✅ → 任务生成 ✅ → 执行任务 ✅ (4/4)
+```
+
+---
+