bain-riper-cli 0.1.1

package/templates/openspec/project-profile.md

@@ -0,0 +1,107 @@
+# bain-riper 项目 Profile
+
+> **定位**：本文件是「换了项目必改」信息的**唯一存放处**。
+> `.qoder/rules/` 下的规则文件与 `openspec/config.yaml` 通过硬路径引用本文件，
+> 实现两层架构：**核心套件跨项目复用 / 只换 Profile**。
+>
+> **移植到新项目时**：只需修改本文件，`.qoder/rules/` 下除宪法 §3/§7/§8 少量条款外均无需改动。
+>
+> **当前项目**：bain-riper
+
+---
+
+## §1 技术栈
+
+| 项 | 值 |
+|---|---|
+| 语言版本 | JDK 21 |
+| 框架 | Spring Boot 3.5.9 |
+| ORM | MyBatis-Plus |
+| 数据库 | MySQL |
+| Web 容器 | Undertow |
+| 构建工具 | Maven（多模块，根 POM `/pom.xml` 聚合 `admin/`） |
+| 核心依赖 | MapStruct Plus 1.5.0 / Lombok 1.18.42 / Redisson / Jasypt 3.0.5 / EasyExcel |
+| 测试框架 | JUnit 5 (spring-boot-starter-test) |
+
+## §2 项目骨架
+
+| 项 | 值 |
+|---|---|
+| Maven groupId | `com.reference` |
+| 业务模块（唯一） | `admin/` |
+| 基础包路径 | `admin/src/main/java/com/reference/` |
+| Mapper XML 路径 | `admin/src/main/resources/mapper/` |
+| 建表 SQL 路径 | `script/SQL/` |
+| 参考代码路径 | `docs/reference-code/` |
+| 知识库路径 | `.qoder/repowiki/zh/content/` |
+| 构建命令 | `cd admin && mvn clean package -DskipTests` |
+| 测试命令 | `cd admin && mvn test` |
+| 本地运行 | IDEA 启动 `com.reference.Application#main` 或 `cd admin && mvn spring-boot:run` |
+
+## §3 标准分层目录
+
+```
+<base-package>/               ← 基础包路径见 §2
+├── controller/               # REST API 端点
+├── service/                  # 业务接口
+│   └── impl/                 # 业务实现
+├── mapper/                   # MyBatis Mapper 接口
+├── domain/                   # 实体（Entity）
+│   ├── bo/                   # 业务对象（BO，承载查询/新增/修改参数）
+│   └── vo/                   # 返回视图对象
+├── constant/                 # 枚举与常量
+└── config/                   # Spring 配置与工具类
+```
+
+- 新增实体 / Mapper / Service / Controller **必须**落在上述目录
+- 常量/枚举统一 `constant/`
+- 工具类与 Spring 配置统一 `config/`
+
+## §4 领域约定
+
+| 项 | 值 |
+|---|---|
+| 多租户字段 | `tenant_id`（所有业务表、DTO、Mapper 查询必含） |
+| 实体基类 | `TenantModel` |
+| Mapper 基类 | `BaseMapperPlus<T>`（RuoYi-Vue-Plus 框架提供） |
+| 表名注解 | `@TableName("table_name")`（snake_case） |
+| API 文档注解 | `@ApiModelProperty` |
+| 响应风格 | RESTful |
+| 异常规范 | 统一用 `BusinessException`，禁止直接抛 `RuntimeException` |
+| Commit 风格 | Conventional Commits |
+
+## §5 参考模板（八层标杆，基于 RuoYi-Vue-Plus）
+
+新增 CRUD / 导入导出 / 权限 / 分页等常规功能时，必须以
+`docs/reference-code/` 下 `EmployeeTraining` 示例的继承结构、注解写法、分页约定、多租户处理方式为准。
+参考代码对齐 [RuoYi-Vue-Plus](https://gitee.com/dromara/RuoYi-Vue-Plus) 5.X 代码生成模板风格：
+
+| 层次 | 参考文件 |
+|---|---|
+| Controller | `controller/EmployeeTrainingController.java` |
+| Service 接口 | `service/IEmployeeTrainingService.java` |
+| Service 实现 | `service/impl/EmployeeTrainingServiceImpl.java` |
+| Mapper 接口 | `mapper/EmployeeTrainingMapper.java` |
+| Mapper XML | `resources/mapper/EmployeeTrainingMapper.xml` |
+| Entity 实体 | `domain/EmployeeTraining.java` |
+| 业务对象 BO | `domain/bo/EmployeeTrainingBo.java` |
+| 返回 VO | `domain/vo/EmployeeTrainingVo.java` |
+
+## §6 repowiki 章节目录
+
+基于 `.qoder/repowiki/zh/content/` 的中文章节结构，变更类型 → 主章节映射：
+
+| 变更类型 | 候选章节（按命中率排序，选最相关的 1-2 个） |
+|---|---|
+| 新增业务功能 | `核心功能模块/`、`API接口文档/` |
+| 数据模型变更 | `数据模型设计/` |
+| 架构/组件调整 | `系统架构设计/` |
+| 配置/环境变更 | `配置管理/`、`部署与运维/` |
+| 权限/安全相关 | `安全与权限/` |
+| 开发规范相关 | `开发指南/` |
+
+> 移植到新项目时，本节是整个 Profile 中**唯一需要根据 repowiki 目录树重新填写**的章节。
+
+---
+
+_本文件版本：v1.0；修改时同步检查 `.qoder/rules/` 与 `openspec/config.yaml` 中的引用是否仍有效。_

package/templates/qoder/mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "codegraph": {
+      "command": "codegraph",
+      "args": ["serve", "--mcp", "-p", "/path/to/your-java-project"],
+      "enabled": true
+    }
+  }
+}

package/templates/qoder/rules/openspec_codegraph.md

@@ -0,0 +1,162 @@
+---
+trigger: model_decision
+description: CodeGraph 代码知识图谱使用规则。在代码探索、检索仓库现有实现、分析调用关系时，优先使用 CodeGraph MCP 工具替代 Grep/Glob 全库扫描，减少 token 消耗。适用于所有 OpenSpec skill 及日常 AI 编码交互。
+---
+
+# CodeGraph 使用规范
+
+> ⚖️ **上级规则**：本文件受 `.qoder/rules/project_constitution.md`（项目宪法，always_on）约束。
+> 当本文件与宪法冲突时，以宪法为准。本文件仅定义"优先用什么工具"，不修改任何宪法条款。
+
+**codegraph**（v0.9.4, TypeScript）是一个本地代码知识图谱，已在本项目完成初始化：
+- 索引范围：210 个文件，5,713 个 AST 节点，9,348 条关系边
+- 数据库：`.codegraph/codegraph.db`（SQLite，WAL 模式，约 11.4 MB）
+- 语言支持：Java（198 文件）+ YAML（12 文件）
+
+---
+
+## §1 工具分层与优先级
+
+代码探索分为两个阶段，不同阶段使用不同工具：
+
+```
+阶段 A「找在哪」→ CodeGraph MCP 优先（秒级、低 token）
+阶段 B「读内容」→ Read 确认（精确、必须）
+```
+
+| 阶段 | 任务 | 优先工具 | 降级工具（无 CodeGraph 或失败时） |
+|------|------|---------|--------------------------|
+| A | 搜索符号/类/方法 | `codegraph_query` | search_codebase + Grep |
+| A | 查看文件结构 | `codegraph_files` | Glob |
+| A | 分析调用者 | `codegraph_callers` | ❌ 无等价工具（只能手工 Grep） |
+| A | 分析被调用方 | `codegraph_callees` | ❌ 无等价工具（只能手工 Grep） |
+| A | 变更影响分析 | `codegraph_impact` | ❌ 无等价工具 |
+| A | 任务相关上下文 | `codegraph_context` | Read × N（高 token） |
+| B | 读取实现细节 | Read（必须） | Read（唯一方案） |
+| B | 读取参考模板 | Read（必须） | Read（唯一方案） |
+| B | 读取知识库 | Read（必须） | Read（唯一方案） |
+
+> **硬规则**：「阶段 A」任务禁止用 Grep/Glob 直接扫描全库，「阶段 B」任务禁止用 `codegraph_query` 代替 Read。
+
+---
+
+## §2 对各宪法条款的增强
+
+### §5（禁止重复造轮子）—— `codegraph_query`
+
+**效果**：将"搜索同名类/同语义方法"从手动多次 Grep 变为一条 query。
+
+**使用模式**：
+```text
+# 检查是否存在同名 Service
+codegraph_query("EmployeeExport")  → 返回所有匹配符号（类/方法/字段）+ 位置 + 相关度评分
+
+# 若结果 ≥ 1，再 Read 具体文件做精确判断
+Read(结果[0].文件路径)
+```
+
+**前置条件**：在 Restate 阶段声明"将通过 codegraph_query 检查仓库现有实现"。
+**禁止**：① query 出结果后跳过 Read 直接假设功能重复 ② query 无结果后跳过 pom.xml 依赖检查。
+
+### §6（禁止猜测第三方 API）—— `codegraph_callers` / `codegraph_callees`
+
+**效果**：通过调用链分析确认"API 是否已被使用"。
+
+**使用模式**：
+```text
+# 查询某方法的所有被调用方（确认依赖该 API 的代码范围）
+codegraph_callees("EmployeeInfoServ")
+
+# 查询某方法的所有调用者（确认该 API 是否被实际使用）
+codegraph_callers("TenantModel.getTenantId")
+```
+
+**前置条件**：需要精度跨越的领域（如引入新的二方库/三方库），在 proposal.md 的 Why 中注明"已通过 codegraph 调用链分析确认无同类实现"。
+
+### §1（Spec is Truth）—— `codegraph_impact`
+
+**效果**：在改代码前自动评估变更影响面，提前预判是否需要改 spec。
+
+**使用模式**：
+```text
+# 修改某方法前，评估影响面
+codegraph_impact("待修改的符号名") → 返回受影响的调用链
+→ 交叉验证 spec.md 中是否有对应 Scenario 覆盖
+→ 若无 → 先触发 Reverse Sync
+```
+
+### §3（多租户完整性）
+
+**效果**：`codegraph_query("tenant_id")` 可列出所有包含 `tenant_id` 的符号，辅助验证 Mapper 是否缺多租户过滤。
+
+---
+
+## §3 Preflight 前置阅读中的使用
+
+在 `openspec_preflight.md` §一 前置阅读阶段，CodeGraph 作为可选辅助工具使用：
+
+| Preflight 步骤 | CodeGraph 辅助方式 | 严格程度 |
+|---------------|-------------------|---------|
+| §一.1 读取 inputs | 不适用（纯文本输入） | — |
+| §一.2 repowiki 阅读 | 不适用（业务知识，非代码） | — |
+| §一.3 参考代码 | `codegraph_files` 快速了解模板文件结构；仍必须 Read 模板内容 | 辅助，不可替代 |
+| §一.4 项目规则 | 不适用（规则文本） | — |
+| §一.5 存储现有实现检索 | **`codegraph_query` 优先**，替代手工 Grep | 推荐，失败降级 Grep |
+| §一.6 调用链分析 | **`codegraph_callers/callees` 优先**，回答"谁在用这个 API" | 推荐 |
+
+> **硬约束**：CodeGraph 的输出是"快速索引摘要"，精度不如 Read 全文。
+> 关键决策（如"确定没有重复实现"）需要 Read 确认后做出，不可仅凭 CodeGraph 摘要拍板。
+
+---
+
+## §4 同步策略
+
+### 4.1 自动同步
+
+配置 `.qoder/mcp.json` 后，CodeGraph MCP 将以 `serve --mcp` 模式运行，内置文件监听器自动增量同步。无需手动执行 `codegraph sync`。
+
+### 4.2 手动同步（异常恢复）
+
+当索引落后或出现不一致时：
+
+```bash
+cd /path/to/your-java-project
+codegraph sync    # 增量同步
+codegraph status  # 确认状态
+```
+
+### 4.3 索引新鲜度验证
+
+每次 OpenSpec skill 启动时，CodeGraph MCP 自动提供的 `codegraph_status` 可查看当前索引状态。若发现文件数明显少于预期（< 200），应触发手动 sync。
+
+---
+
+## §5 Preflight 自检扩展项
+
+使用 CodeGraph 辅助时，preflight 自检清单追加两项（仅在使用阶段生效，不影响不使用时）：
+
+- [ ] （如启用 CodeGraph）`codegraph_status` 已确认索引新鲜（文件数 ≥ 200）
+- [ ] （如启用 CodeGraph）关键代码检索/调用链分析已通过 CodeGraph 完成，结果已写入 Restate 对齐纪要
+
+---
+
+## §6 禁止行为
+
+以下行为视为违反本规范：
+
+| 禁止行为 | 理由 |
+|---------|------|
+| 用 `codegraph_query` 结果代替 Read 做精确判断 | query 返回的是索引摘要，不包括完整方法体/注解/import |
+| 用 `codegraph_context` 代替 Read 阅读源代码 | context 用于了解任务周边，不用于精确实现 |
+| 发现 CodeGraph 失败后直接跳过检索步骤 | 应降级到 Grep/Glob 继续检索，宪法 §5 要求必须检索仓库 |
+| CodeGraph 不可用时以此为由拒绝执行任务 | CodeGraph 是可选增强，不是必需依赖 |
+| 使用 CodeGraph 工具时跳过宪法 §2（Restate First） | 任何工具均不豁免 Restate 义务 |
+
+---
+
+## §7 技术参考
+
+- CLI 入口：`codegraph`（v0.9.4, npm 全局安装，路径 `/usr/local/bin/codegraph`）
+- 索引存储：`.codegraph/codegraph.db`（已加入 `.codegraph/.gitignore`，不入库）
+- MCP 模式：`codegraph serve --mcp`（stdio 传输）
+- MCP 工具列表：`codegraph_query` / `codegraph_context` / `codegraph_callers` / `codegraph_callees` / `codegraph_impact` / `codegraph_affected` / `codegraph_files` / `codegraph_status` / `codegraph_sync`

package/templates/qoder/rules/openspec_output_specs.md

@@ -0,0 +1,112 @@
+---
+trigger: glob
+glob: openspec/**/*.md
+---
+# OpenSpec 输出规范（Output Specs）
+
+> ⚖️ **上级规则**：本文件受 `.qoder/rules/project_constitution.md`（项目宪法，always_on）约束。宪法 §4（SHALL/MUST 硬性）与 §9（禁止独立编译任务）直接落地于本文件 §四 / §五，冲突以宪法为准。
+
+**本文件是 OpenSpec artifact（proposal / design / spec / tasks）输出格式与内容
+要求的唯一真相源。** 在 `openspec/changes/**` 与 `openspec/specs/**` 下创建或
+修改任何 artifact 时必须遵守本文件，违反即视为 artifact 不合规。
+
+> 与本文件配套的另两份规则：
+> - 📋 `.qoder/rules/openspec_preflight.md`：写作前的 Preflight（Restate + 前置阅读）
+> - 📋 `.qoder/rules/openspec_specifications.md`：项目级目录与命名约束、规则索引
+
+---
+
+## §一、通用输出约定
+
+- 所有标题与正文使用中文，代码、路径、标识符保留英文
+- 引用 repowiki 章节统一格式：`见 .qoder/repowiki/zh/content/xxx.md#章节名`
+- 引用 reference-code 统一格式：`参考 docs/reference-code/xxx/Xxx.java`（路径前缀见 `openspec/project-profile.md` §2）
+- 行尾不留多余空格，文末保留单个换行
+- artifact 内禁止粘贴 `<context>` / `<rules>` / `<project_context>` 块
+
+---
+
+## §二、proposal.md
+
+| 章节 | 硬性要求 |
+|---|---|
+| **Why** | 必须显式引用 repowiki 相关章节，说明新增能力与现有能力的边界 |
+| **Why / What Changes** | 必须能在 `inputs/requirement.md`（若存在）中找到对应依据，不得夹带需求文档未提及的功能 |
+| **What Changes** | 对每一项新增能力须标注可参考的 reference-code 模板路径 |
+| **Impact** | 列出受影响的 repowiki 章节（将来知识库需要更新的条目） |
+
+附加约束（与 `openspec/config.yaml` `rules.proposal` 同源）：
+- 禁止凭空假设技术栈，须以实际依赖为准（pom 路径见 `openspec/project-profile.md` §2）
+- 避免重复造轮子：先检索仓库现有实现与已有依赖，禁止引入功能重复的依赖
+- 禁止猜测第三方包用法：未在 reference-code 与现有实现中找到同类型用法时，
+  必须先阅读包源码或 README 确认 API 存在后再引用
+
+---
+
+## §三、design.md
+
+| 章节 | 硬性要求 |
+|---|---|
+| **Context** | 引用 repowiki 的"数据模型设计"与"系统架构设计"对应章节 |
+| **Decisions** | Domain / Mapper / Controller 选型对齐参考模板的继承与注解写法（实体基类、Mapper 基类、表名注解等）。具体注解名与基类见 `openspec/project-profile.md` §4 / §5 |
+| **Non-Goals** | 显式声明不修改的 repowiki 现有模块 |
+
+---
+
+## §四、spec.md
+
+- **Requirement 条目必须以 `SHALL` 或 `MUST` 开头**（OpenSpec 归档校验硬性
+  要求，使用其他动词将导致 `openspec archive` 失败）
+- 场景以 `WHEN / THEN / AND` 结构描述，行为与 reference-code 中同类型功能
+  保持一致
+- 数据模型类 spec 必须包含：
+  - 建表 SQL 路径约定（路径见 `openspec/project-profile.md` §2）
+  - 表名使用 snake_case
+  - 主键、多租户字段完整声明（字段名见 `openspec/project-profile.md` §4）
+
+---
+
+## §五、tasks.md
+
+- 每个任务可独立验证，给出验证命令或可观察证据
+- 涉及新增类的任务，任务描述必须指明参考的 `docs/reference-code/` 文件路径
+- 建表 / SQL 脚本任务统一放到建表 SQL 路径（见 `openspec/project-profile.md` §2）
+- Mapper XML 统一放到 Mapper XML 路径（见 `openspec/project-profile.md` §2）
+- **禁止包含编译验证任务**：tasks.md 不得独立列出 `mvn clean compile` /
+  `mvn compile` 等整体编译验证步骤；单任务内的"编译无错误"作为验证证据
+  可保留，但不得单独用作任务条目
+- **Reverse Sync 硬规则（apply 阶段强制）**：实施任一任务时若发现 spec.md /
+  design.md / tasks.md 自身描述与代码/参考实现不一致，**必须先停止代码实现，
+  按 `.qoder/rules/openspec_reverse_sync.md` 的「Reverse Sync 五步法」
+  回写 artifact 并等待用户确认**，禁止反向修改代码适配错误文档
+
+---
+
+## §六、Artifact 输出自检清单（落盘前逐项核验）
+
+通用：
+- [ ] 全文中文叙述、英文路径与代码
+- [ ] 所有 repowiki / reference-code 引用使用统一格式
+- [ ] 未粘贴 context / rules 注入块
+
+proposal.md：
+- [ ] Why / What Changes 在 `inputs/requirement.md` 中均能找到依据
+- [ ] What Changes 每项新增能力都标注了 reference-code 模板
+- [ ] Impact 列出受影响 repowiki 章节
+
+design.md：
+- [ ] Context 引用了 repowiki 数据模型 / 系统架构章节
+- [ ] Decisions 与 reference-code 注解、继承一致
+- [ ] Non-Goals 明确
+
+spec.md：
+- [ ] 每条 Requirement 以 SHALL 或 MUST 开头
+- [ ] 场景使用 WHEN / THEN / AND
+- [ ] 数据模型类 spec 含建表 SQL 路径、snake_case 表名、多租户字段
+
+tasks.md：
+- [ ] 每个任务可独立验证
+- [ ] 新增类任务标注了 reference-code 路径
+- [ ] 不含独立的 `mvn compile` 任务
+
+**任一项未通过**：禁止落盘，先修订后再写入。

package/templates/qoder/rules/openspec_preflight.md

@@ -0,0 +1,230 @@
+---
+trigger: model_decision
+description: OpenSpec skills（openspec-propose / openspec-continue-change / openspec-explore / openspec-apply-change）与在 openspec/changes/** 或 openspec/specs/** 下生成任何 artifact（proposal/design/spec/tasks）前的统一 Preflight 流程（Restate First + Clarify 主动找歧义 + 前置阅读 + 物理化自检展示）。apply 阶段额外叠加 Reverse Sync 硬规则（发现 spec 偏差时先回写文档再改代码）。因 Qoder 在 skill 触发时同步加载 model_decision 规则，本文件无需在各 SKILL.md 中硬编码 Step 0 引用即可自动生效。
+---
+
+# OpenSpec Preflight（统一前置流程）
+
+> ⚖️ **上级规则**：本文件受 `.qoder/rules/project_constitution.md`（项目宪法，always_on）约束。宪法 §2 / §10 直接对应本文件的 §零 Restate First 与 §二 自检清单，冲突以宪法为准。
+
+**本文件是 OpenSpec 体系中所有提案/继续/探索前置流程的唯一真相源。**
+触发 `openspec-propose` / `openspec-continue-change` / `openspec-explore` 三个 skill，
+或在 `openspec/changes/**`、`openspec/specs/**` 下创建/修改
+`proposal.md` / `design.md` / `spec.md` / `tasks.md` 时，必须按本文件流程执行，
+不得跳过、简化或重新发明。
+
+其它文件（三个 SKILL.md、`openspec_specifications.md`、`openspec/config.yaml`）
+仅负责引用本文件，不再重复 Preflight 内容。
+
+---
+
+## §零、Restate First（最先执行，优先级高于一切）
+
+在**任何**前置阅读、CLI 调用、artifact 生成之前，必须先完成一次「Restate + Checkpoint」：
+
+1. **Restate（用自己的话复述）**：以 8 行以内，明确给出：
+   - 任务目标（一句话）
+   - 变更边界（包含 / 不包含什么）
+   - Done Contract（什么算完成、由什么证明）
+   - 已识别的关键风险或歧义
+   - **任务档位**：`zero` / `fast` / `standard` / `deep` 四选一 + 一句话理由
+     （判定规则见 📋 `.qoder/rules/openspec_task_tiers.md` §二 决策树）
+2. **等待用户确认**：若用户未明确同意（"OK / 继续 / 确认"等），
+   禁止进入前置阅读与任何 artifact 生成。若存在歧义，使用 AskUserQuestion 澄清。
+   用户有权在此时覆盖 AI 判定的档位。
+3. **确认通过后**，按档位裁剪后续流程（fast 档跳过 Clarify、跳过 design.md；
+   standard 走全套；deep 追加 codemap.md），才进入 §一 前置阅读与后续工作流。
+4. **再对齐时机（Core Goal as Loop Anchor）**：
+
+   以下三个时机**强制**重新回看 Restate 中的核心目标，不得仅靠记忆推进：
+
+   | 时机 | 动作 |
+   |------|------|
+   | **执行前 checkpoint** | 每一个实施步骤（如 tasks.md 的每个 task）执行前，输出 **≤4 行 Core Goal Re-Anchor**：<br>· 核心目标（来自 proposal.md / spec.md，≤1 句）<br>· 当前步骤对目标的贡献<br>· 1 行 sanity check：「基于当前进度，此步骤是否仍合理？」 |
+   | **偏差暴露后** | 发现 spec / design / tasks 与实现不一致时，启动 Reverse Sync 五步法（见 `.qoder/rules/openspec_reverse_sync.md`）；回写文档后**回到本节的 Re-Anchor 重新对齐** |
+   | **artifact 收尾时** | 全部任务完成后，回看 Restate 中的 Done Contract，逐条检查是否由证据证明完成 |
+
+   **Core Goal Re-Anchor 格式**（轻量，非完整 Restate）：
+   ```
+   ## Core Goal Re-Anchor
+   - **目标**：<1 句核心目标>
+   - **当前步骤**：<步骤编号 + 描述> → 贡献：<1 句>
+   - **Sanity Check**：<1 句路径检查>
+   ```
+
+   若 Re-Anchor 发现核心目标已偏移、当前步骤不再合理：
+   - 立即暂停
+   - 报告偏移内容
+   - 建议更新 spec / design / tasks 后再继续
+   - **禁止**绕过偏移继续推进
+
+   此机制是宪法 §2 Restate First 在实施阶段的轻量化延伸，
+   与 Preflight 自检（§二）互为补充：自检管"开始前"，Loop Anchor 管"进行中"。
+
+> 灵感来源：轻量 AI Agent Harness 实践（SDD-RIPER Light）。
+> 目的：避免"四件套写完才发现理解错了"的返工。
+
+---
+
+## §零点五、Clarify（Restate 通过后、前置阅读前执行）
+
+Restate 被用户确认后，**不得直接进入前置阅读**，必须先执行一次主动找歧义：
+
+1. **主动列出 3-5 个歧义点**，每条包含：
+   - 歧义编号（Q1 / Q2 ...）
+   - 一句话描述争议（例："字段 X 是否跟随租户隔离？"）
+   - **二选一或三选一**的候选答案（避免开放式问题）
+   - 推荐答案 + 简短理由（可选）
+2. **展示方式**：必须用 AskUserQuestion 工具提交（多选或单选），
+   禁止以"请回复数字 1/2/3"的自由文本形式草草带过。
+3. **无歧义的例外**：若任务确实简单（例如仅修正错别字、仅加一个枚举值），
+   允许显式声明「本任务无需 Clarify，理由：XXX」并等待用户"OK"后继续；
+   但涉及数据模型、接口、权限、租户隔离、编制计划等领域变更时不得省略。
+   **档位例外**：声明为 `zero` 档的任务不进入本节；声明为 `fast` 档的任务
+   **默认跳过** Clarify（需显式写"fast 档无需 Clarify"），`standard` / `deep`
+   档仍必须执行。
+4. **确认方式**：用户作答后，必须把答案回写到 Restate 末尾形成"对齐纪要"，
+   再进入 §一 前置阅读。
+
+> 灵感来源：GitHub Spec-Kit `/clarify` 阶段。
+> 目的：把 Restate First 从"复述理解"升级为"主动暴露并锁死边界"，
+> 避免"复述看似无误、落盘才知分歧"的隐性返工。
+
+---
+
+## §一、前置阅读（强制，Restate 确认后执行）
+
+在编写任何 OpenSpec artifact 前，必须按需读取以下资料，并在输出文档中
+显式引用来源（文件路径 + 章节名）。
+
+### 1. 本次 change 的原始需求输入（最高优先级）
+约定路径：`openspec/changes/<name>/inputs/`
+
+- 若该目录存在，必须**完整阅读**其中所有文件（PRD、会议纪要、接口草案、
+  原型图等），作为本次 change 的权威需求源。
+- 若目录缺失或为空，**禁止凭空编写 artifact**，必须先向用户确认需求来源
+  （对话 / 外部链接 / 其他），并把确认后的需求落盘到 `inputs/requirement.md`
+  再进入后续流程。
+- 图片资料统一放到 `inputs/mockups/`，在 `inputs/requirement.md` 中用
+  相对路径引用。
+- `inputs/` 目录随 change 一同归档到 `openspec/changes/archive/`，保证可回溯。
+
+建议结构：
+```
+openspec/changes/<name>/
+├── inputs/
+│   ├── requirement.md      # PRD / 业务方描述（必需）
+│   ├── api-draft.yaml      # 接口草案（可选）
+│   ├── mockups/            # 原型/截图（可选）
+│   └── data-samples.sql    # 样本数据（可选）
+├── proposal.md
+├── design.md
+├── specs/
+└── tasks.md
+```
+
+### 2. 知识库 `.qoder/repowiki/zh/content/`（按需阅读，禁止全量扫描）
+
+> ⚠️ **读取策略硬规则**：repowiki 体量大，**全量扫描昂贵且无必要**。本节
+> 既是阅读清单，也是**读取成本控制**的硬约束。
+
+#### 2.1 三步路由法（按顺序执行）
+
+1. **预判**：根据 Restate 中的变更类型，从下方映射表选出 **最多 2 个** 主章节；
+   无关章节禁止打开。
+2. **先列目录再读文件**：对每个目标章节，先用 `list_dir` 查看文件清单
+   （成本约为 `read_file` 的 1/20），再根据文件名判断只读 1-3 个最相关
+   `.md`，禁止把整个章节目录批量 `read_file`。
+3. **增量补读**：后续 Step 若发现证据不足，再按需补读新文件；
+   禁止"先把所有可能相关的都读一遍再开始"。
+
+#### 2.2 变更类型 → 主章节映射（最多选 2 个）
+
+> 完整映射表见 `openspec/project-profile.md` §6。该表根据当前项目 repowiki 目录树维护，
+> 移植项目时只需改 profile 一处。
+
+#### 2.3 不重复读取（本 session 内强约束）
+
+- **已在本 session 内读过的文件禁止再次 `read_file`**。若需回忆内容，
+  通过上下文引用（直接写出文件路径 + 章节名），而不是重新读。
+- 若对已读内容有新的需要（如只记得大意需要精确行号），允许二次读取，
+  但必须在回复中标注"二次读取原因：XXX"。
+- **Preflight 自检清单中必须列出本次已读章节清单**（见 §二），作为
+  "不重复读取"的取证基准。
+
+#### 2.4 跨轮对话的已读判定
+
+- 用户在上一轮已明确引用某文件，或上一轮已通过 `read_file` 输出其内容，
+  视为**已读**，本轮禁止重读，直接基于上下文工作。
+- 仅当用户显式要求"重新读一次最新版"时，才允许重读。
+
+> 目的：把 repowiki 从"每轮从零扫描"改为"按需最小读取 + 跨轮缓存"，
+> 显著降低 token 成本与响应延迟。
+
+### 3. 参考代码 `docs/reference-code/`
+以参考模板为标准，按层检索。完整七层文件清单见 `openspec/project-profile.md` §5。
+
+### 4. 项目规则
+- `.qoder/rules/openspec_specifications.md`：项目规则索引层（含目录与命名约束）。
+- `.qoder/rules/openspec_output_specs.md`：**artifact 输出规范的唯一真相源**
+  （proposal / design / spec / tasks 章节硬性要求 + 落盘前自检清单），写入
+  artifact 前必读且必须严格遵守。
+- `.qoder/rules/openspec_reverse_sync.md`：**apply 阶段偏差处理的唯一标准**（Reverse Sync 五步法），实施代码前必读。
+- `openspec/config.yaml`：`context` 与按 artifact 分类的 `rules` 字段，
+  由 openspec CLI 注入给 AI。
+
+### 5. 依赖版本确认
+涉及第三方库选型时，必须阅读：
+- `/pom.xml` 的 `dependencyManagement`（版本）
+- `/admin/pom.xml` 的 `dependencies`（实际依赖清单）
+> 模块名与依赖清单见 `openspec/project-profile.md` §2。
+
+禁止凭空假设依赖或版本。
+
+### 6. 依赖与实现复用原则
+- **避免重复造轮子**：新增功能前先检索仓库现有实现与 `pom.xml` 中已有的包，
+  禁止引入功能重复的依赖或重复实现已有的工具类。在 `proposal.md` 的 **Why** /
+  **What Changes** 中需明确说明与已有能力的边界。
+- **禁止猜测第三方包用法**：若 `docs/reference-code/` 与仓库现有实现中均未
+  找到同类型用法，必须先阅读该包的源码或官方 README，确认 API 存在、
+  版次兼容后，再在 `design.md` / `tasks.md` 中引用具体类名或方法名；
+  不允许以假定存在的 API 为前提编写 artifact。
+
+---
+
+## §二、Preflight 自检清单（进入 skill 后续 Step 前必须全部通过）
+
+**物理化展示硬规则（宪法 §10 落地）**：进入 Step 1 之前，必须在主回复开头
+用可见的 Markdown checkbox 形式（`- [x]` / `- [ ]`）打印下方清单的真实勾选
+状态，禁止仅用"已完成 Preflight"等文字描述代替。未展示勾选结果 = 视为
+未执行 Preflight，用户有权要求重做。
+
+- [ ] Restate 已产出且 ≤ 8 行（含目标 / 边界 / Done Contract / 风险）
+- [ ] **已在 Restate 末尾声明任务档位**（`zero` / `fast` / `standard` / `deep`）并给出一句话理由
+- [ ] 用户已明确确认（"OK / 继续 / 确认"等），或歧义已通过 AskUserQuestion 澄清
+- [ ] Clarify 阶段已完成：已列 3-5 个歧义点并获用户答复，或已显式声明"本任务无需 Clarify"且得到用户"OK"
+- [ ] `openspec/changes/<name>/inputs/` 已完整阅读，或已按缺失处理流程
+      落盘 `inputs/requirement.md`
+- [ ] 与当前变更主题相关的 repowiki 章节已识别并阅读（已读清单必须列出：`路径A#章节X`、`路径B#章节Y`；已读文件本 session 不重复 `read_file`）
+- [ ] 与当前变更同类型的 reference-code 模板已识别并阅读
+- [ ] 涉及依赖变更时，`/pom.xml` 与 `/admin/pom.xml` 已核对
+- [ ] 已加载 `.qoder/rules/openspec_output_specs.md`，准备在写入 artifact 时按其执行落盘前自检
+- [ ] 已加载 `.qoder/rules/project_constitution.md` 宪法 10 条并确认本次任务不违宪
+
+**任一项未完成**：禁止进入 skill 的后续 Step，禁止生成任何 artifact。
+
+---
+
+## §三、与其他文件的引用关系
+
+| 文件 | 引用方式 |
+|---|---|
+| `.qoder/skills/openspec-propose/SKILL.md` | 方案甲迁移后不再含 Step 0 硬引用；规则由 Qoder model_decision 自动加载本文件 |
+| `.qoder/skills/openspec-continue-change/SKILL.md` | 同上 |
+| `.qoder/skills/openspec-explore/SKILL.md` | 同上，探索场景通过本文件 §一.5 覆盖 |
+| `.qoder/skills/openspec-apply-change/SKILL.md` | 同上；Reverse Sync 五步法已搬迁至 `openspec_reverse_sync.md` |
+| `.qoder/rules/openspec_specifications.md` | §零 为引用指针，自身只保留输出规范 |
+| `.qoder/rules/openspec_output_specs.md` | §五 tasks.md 末尾记录 Reverse Sync 硬规则，指向 `openspec_reverse_sync.md` |
+| `.qoder/rules/openspec_task_tiers.md` | 在 §零 Restate 与 §零点五 Clarify 中被引用；四档裁剪规则由该文件承载 |
+| `.qoder/rules/openspec_reverse_sync.md` | apply 阶段偏差处理流程（五步法）；本文件 §零 完成后、进入实施时由该文件接管偏差处置 |
+| `openspec/config.yaml` | `context.Restate First` / `rules.proposal` 保留硬约束，作为 CLI 注入链路的双保险 |