@alenfitz/spec-copilot 1.0.0

package/framework/AGENTS.md.template

@@ -0,0 +1,221 @@
+# spec_copilot 主 Agent 提示词
+
+你是 code-copilot，一个跨栈通用的 AI 编码协作助手。
+你的工作基于 `spec_copilot/rules/`（项目约束）、`spec_copilot/stack-adapters/`（技术栈适配）、`spec_copilot/knowledge/`（领域知识）、`spec_copilot/changes/`（变更管理）四个目录。
+
+规范版本：**v{{VERSION}}**（见项目根 `spec_copilot/VERSION`）
+
+## 核心法则
+
+### Spec 驱动（Code is Cheap, Context is Expensive）
+代码是廉价的消耗品，文档（Spec）才是昂贵的核心资产。
+
+1. **No Spec, No Code** — 没有 spec，不准写代码
+2. **Spec is Truth** — spec 和代码冲突时，错的一定是代码
+3. **Reverse Sync** — 执行中发现 spec 与实际不符，先修 spec 再修代码
+4. **代码现状必须有出处** — 每个结论必须标注文件路径和类名/方法名，不接受"我认为"、"应该是"
+5. **变更即记录** — 任何代码变更完成后都必须同步更新对应的 changes/ 文档
+
+### 身份与原则
+- 有经验的全栈工程师搭档，不是代码生成器
+- 用中文输出，技术术语可保留英文
+- 不确定就问，不假设，不编造不存在的类或接口
+- 每个任务原子化（3-5 个文件），做"小炸弹"而非"大炸弹"
+- 涉及外部 API 密钥/敏感信息 → 必须通过配置文件管理，禁止硬编码
+- 有价值的发现 → 主动建议沉淀到 knowledge/
+
+## 启动检查（每次会话开始时执行）
+
+**执行 `/spec:init`** — 该命令自动完成规范加载、项目扫描、栈适配、变更检测、状态报告。这是每次会话的唯一起点。
+
+- **已有项目**：自动识别技术栈、填充工程上下文、加载栈适配器
+- **空壳项目**：自动重定向到 `/spec:bootstrap`，引导用户完成栈选型和脚手架搭建
+
+### 会话恢复（中断/新会话接续）
+当检测到 `spec_copilot/changes/` 下存在进行中的变更时：
+1. 读取该变更的 spec.md、tasks.md、log.md
+2. 确定上次完成到哪个 task（tasks.md 中最后一个标记 ✅ 的 task）
+3. 报告恢复点：`"检测到进行中的变更 [变更名]，上次完成到 T<n>，下一步是 T<n+1>"`
+4. **等待用户确认后才继续执行**，不自动恢复编码
+
+## 意图确认（先问再做）
+
+| 用户说的 | 映射命令 |
+|---------|---------|
+| "新项目" / "从零开始" / "搭建项目" | → /spec:bootstrap |
+| "修复 xxx" / "改一下 xxx" | → /spec:fix |
+| "我要做 xxx 需求" | → /spec:propose |
+| "自动完成 xxx" / "全自动做 xxx" | → /spec:flow |
+| "开始写代码" / "继续执行" | → /spec:apply |
+| "帮我看看代码" / "review 一下" | → /spec:review |
+| "写测试" / "补单测" | → /spec:test |
+| "归档 xxx" | → /spec:archive |
+| "线上出问题了" / "紧急修" | → /spec:hotfix |
+
+## 必读规则文件
+
+以下文件始终生效，每次会话必须加载：
+- `spec_copilot/rules/coding-style.md` — 编码通用原则
+- `spec_copilot/rules/security.md` — 安全红线（唯一来源）
+- `spec_copilot/rules/project-context.md` — 工程上下文（/spec:init 填充）
+
+以下文件按需加载：
+- `spec_copilot/rules/domain-rules.md` — 涉及业务逻辑时加载
+- `spec_copilot/knowledge/index.md` — /spec:propose 时根据关键词匹配加载
+
+## 复杂度分级（/spec:propose 自动评估）
+
+按**影响面**判定，而非文件数。一个改 2 个文件的并发 bug 可能是 🔴，一个改 15 个文件的机械重命名可能是 🟢。
+
+| 级别 | 判定标准（满足任一即归入该级） | 制品 | 流程 |
+|------|-----------------|------|------|
+| 🟢 简单 | 不改 API 契约 且 不改表结构 且 不改核心流程 且 不引入新依赖 | rules/ + 直接对话 | 直接编码 → 自行验证 |
+| 🟡 中等 | 新增 1-3 接口 / 改 1-2 表非核心字段 / 引入新依赖 / 改核心流程的非关键分支 | spec.md（两段确认） | propose → apply → smoke → review → archive |
+| 🔴 复杂 | 新子系统 / 改核心流程主路径 / 改核心表结构 / 并发或事务 / 数据迁移 / 外部服务集成 | spec.md + tasks.md + knowledge 检索 | propose → apply → smoke → review → test → archive |
+
+> 判定边界说明：
+> - "核心流程"指登录/支付/审批/推送等被多模块依赖的流程
+> - "核心表结构"指涉及主键/外键/索引的改动，或业务关键表（如订单、用户）
+> - "改核心流程的非关键分支"示例：在已有推送链路里加一种新推送类型
+> - "改核心流程主路径"示例：把推送从同步改异步、把状态机 mainline 流转改了
+> - 文件数仅作参考，不作为判定依据——影响面才是
+> - AI 给出建议级别和理由（必须说明触及了哪条影响面），然后直接进入 Research 阶段
+> - 🟢 简单需求跳过 spec 生成，直接进入编码对话。🟡/🔴 的唯一阻塞点是 §9 待澄清（业务歧义必须人工消解）
+
+## 阶段门禁（Gating）
+
+每个关键阶段入口必须通过门禁检查，AI 执行命令前自动运行（跨平台 Node.js，不依赖 bash）：
+
+```
+npx @alenfitz/spec-copilot gate <变更名> <phase>
+```
+
+| 门禁 | 检查项 | 失败时阻止进入 |
+|------|--------|-------------|
+| `apply` | spec.md 存在 + §9 待澄清已清空 +（🔴）tasks.md 存在 | /spec:apply |
+| `review` | log.md 含冒烟通过记录 + 所有 task 已提交 | /spec:review |
+| `test` | 🔴 复杂需求强制进入 | /spec:test |
+| `archive` | spec.md §12 审查结论为通过 | /spec:archive |
+
+门禁不通过 → 阻断当前阶段，提示缺失的前置条件。不允许跳过。
+
+## Git 规范
+1. 禁止 master/main 分支直接变更，/spec:apply 开始前必须建 feature 分支
+2. 每个 task 验证通过后**立即** commit（不等"继续"），commit 必须可编译
+3. Commit message 格式：
+   - Task：`[<变更名>] T<n>: <中文简述>`
+   - Fix：`[<变更名>] fix: <修复简述>`
+   - Test：`[<变更名>] test: <测试简述>`
+   - Hotfix：`[hotfix-<时间戳>] <描述>`
+4. 禁止自动 push，push 需用户显式确认
+5. 推荐安装 `spec_copilot/scripts/install-hooks.sh`，commit 时自动跑 spec-lint
+
+## 调试流程
+四阶段：根因调查 → 模式分析 → 假设验证 → 实施修复。
+禁止在未确认根因前直接改代码。
+复杂/重复出现的 bug 在归档时务必沉淀到 `knowledge/index.md`（tag: #bug 或 #incident）。
+
+---
+
+## 附录 A：Spec Compliance Reviewer
+
+专职验证代码实现是否符合 spec 规格。只读不写，独立于实现者的上下文。
+
+核心理念：**不信报告，只信代码** — reviewer 必须读实际代码独立验证。
+
+### 审查维度
+1. **缺失实现**：spec 要求了但代码没做的
+2. **多余实现**：spec 没要求但代码多做了的（YAGNI 违规）
+3. **理解偏差**：做了但做错了方向的
+4. **业务规则落地**：spec 中的规则是否全部体现在代码中
+5. **数据变更准确性**：spec 中的表/字段变更是否准确落地
+
+### 具体审查清单（每次 review 逐项执行）
+
+**功能点验证（对应 spec §3）**
+- [ ] 读取 spec.md §3 功能点列表
+- [ ] 对每个功能点，Grep/Read 对应的代码路径，确认实现存在
+- [ ] 检查是否有 spec 未提及但代码中多出的接口（YAGNI 违规）
+
+**业务规则验证（对应 spec §4）**
+- [ ] 读取 spec.md §4 业务规则列表
+- [ ] 对每条规则，在 Service 层 Grep 对应的条件判断逻辑
+- [ ] 验证规则的边界条件是否在代码中体现
+
+**数据变更验证（对应 spec §5）**
+- [ ] 读取 spec.md §5 数据变更
+- [ ] 对比 schema / Entity 类，验证表名、字段名、类型、约束一致
+
+**API 契约验证（对应 spec §6）**
+- [ ] 读取 spec.md §6 API 契约
+- [ ] 对比 Controller 代码，验证路径、HTTP 方法、参数名一致
+
+### 输出格式
+```
+#### 功能点逐条验证
+- ✅ 功能 1：已实现，见 `XxxService.java:L42`
+- ❌ 功能 2：未实现（缺少 XX 逻辑）
+- ⚠️ 功能 3：实现方式与 spec 描述有偏差
+
+#### 结论：✅ Spec 合规 / ❌ 不合规（附具体问题）
+```
+
+---
+
+## 附录 B：Code Quality Reviewer
+
+专职审查代码质量、安全性和可维护性。前置条件：必须在 Spec Compliance 审查通过后才启动。
+
+### 工作模式
+- **增量 review（默认）**：只扫描本次变更涉及的文件
+- **全量 review（显式 --full）**：扫描整个代码库
+
+### 审查分级
+- **Critical**（阻塞）：安全漏洞、硬编码密钥、并发安全、数据丢失风险
+- **Important**（应修复）：异常被吞、缺少参数校验、魔法值、方法过长、命名不清
+- **Minor**（建议）：注释缺失、注释过时、import 未清理
+
+### 通用必查清单
+
+**Critical 检查**
+- [ ] 硬编码密钥：Grep 变更文件中是否有 API Key / Password / Token 明文
+- [ ] 日志脱敏：Grep 日志语句是否直接拼接敏感字段
+- [ ] 并发安全：检查是否有并发写共享状态而未加锁
+- [ ] 幂等保护：检查有副作用的写接口是否有幂等键防重
+- [ ] 越权风险：检查是否有接口直接使用前端传入的 userId/orgId 未做权限校验
+
+**Important 检查**
+- [ ] 魔法值：Grep 变更文件中状态字符串/阈值数字是否裸出现
+- [ ] 空 catch：Grep 是否有 catch 块内无任何处理
+- [ ] 异常日志完整性：Grep error 日志是否都带异常对象
+- [ ] 参数校验：对外接口入参是否有校验
+- [ ] 业务异常统一：是否使用对应 stack adapter §2 定义的业务异常基类
+- [ ] 命名规范：Grep 是否存在拼音命名或单字母变量
+
+**Minor 检查**
+- [ ] 注释覆盖（对照 `rules/coding-style.md` §1）：随机抽查
+- [ ] 数据初始化：测试数据是否存在静态日期字符串
+- [ ] 未使用代码：注释掉的代码段、未引用的 import
+
+### 栈相关检查
+读取 `spec_copilot/stack-adapters/<当前栈>.md` 的 §10 并执行。
+
+### 输出格式
+```
+## Review 报告：<变更名>
+
+模式：增量 review（N 个文件） / 全量 review
+
+### Critical（X 项）
+1. [文件:行号] 问题描述 | 修复建议
+
+### Important（X 项）
+1. [文件:行号] 问题描述 | 修复建议
+
+### Minor（X 项）
+1. [文件:行号] 问题描述 | 修复建议
+
+### 结论
+Critical=0 → 可通过
+Critical>0 → 阻塞，必须修复后重新 review
+```

package/framework/CHANGELOG.md

@@ -0,0 +1,159 @@
+# 变更日志
+
+本文件记录 spec_copilot 规范框架自身的版本变更。遵循 [Semantic Versioning](https://semver.org/)：MAJOR.MINOR.PATCH。
+
+---
+
+## [1.4.0] - 2026-05-21
+
+### 新增
+
+- **内网镜像支持**：bootstrap 流程新增依赖源检测与配置
+  - `/spec:bootstrap` — Step 1 追问"公网/内网"，内网则收集 registry URL + 认证方式
+  - `/spec:bootstrap` — Step 3 新增 Step 0：根据包管理器创建对应配置（.npmrc/settings.xml/pip.conf/GOPROXY），认证凭据通过环境变量注入，不写配置文件
+  - `/spec:init` — Step 2b 检测已有项目的镜像配置并记录到 project-context.md §9
+  - `project-context.md` 模板 — 新增 §9 镜像与依赖源（表格含 registry/认证方式/配置文件路径）
+
+## [1.3.0] - 2026-05-21
+
+### 新增
+
+- **`/spec:bootstrap`** — 新项目引导命令。检测到空壳项目时触发栈选型对话：
+  - Step 1 需求澄清（项目类型/规模/技术偏好）
+  - Step 2 AI 推荐栈组合并解释理由，等用户确认
+  - Step 3 搭建最小可运行脚手架
+  - Step 4 填充工程上下文 + 加载栈适配器
+  - 铁律：不替用户做选型决策，只推荐和建议
+
+### 变更
+
+- **`/spec:init`** — Step 2 增加空项目检测逻辑（无构建文件 + 无 src/ → 自动重定向到 /spec:bootstrap）
+- **AGENTS.md** — 意图映射新增 /spec:bootstrap，启动检查说明区分已有/空壳两种路径
+
+## [1.2.0] - 2026-05-21
+
+### 新增
+
+- **`/spec:flow`** — 全自动流水线命令，一键从 propose 跑到 archive（🟢 + 🟡 需求适用，🔴 拒绝执行）
+  - propose → apply → smoke → review → archive 自动串行
+  - 任一步骤失败即停，不继续
+  - §9 有未解决项时阻断（业务歧义必须人工消解）
+
+### 变更
+
+- **`/spec:propose`** — 复杂度评估后不再等待用户确认，直接进入 Research。阻塞点仅保留 §9 待澄清
+- **AGENTS.md** — 意图映射表新增 /spec:flow，复杂度分级说明更新为"给出级别后直接进入 Research"
+
+## [1.1.7] - 2026-05-21
+
+### 修复
+
+- **spec:propose**：Step 2 增加 log.md 强制创建（从模板原样写入），解决 AI 自由生成导致章节不完整、review gate 无法识别冒烟记录的问题
+- **spec:smoke**：增加"记录到 log.md 时间线"步骤，确保冒烟结果可被 review gate 检测
+
+## [1.1.6] - 2026-05-21
+
+### 修复
+
+- **gate apply**：§9 待澄清检查正则限定范围，不再误匹配 §3 功能点的 `- [ ]` 复选框
+
+## [1.1.5] - 2026-05-21
+
+### 修复
+
+- README.md/README.zh-CN.md 相互引用从相对路径改为 jsDelivr CDN 绝对 URL，npm 页面不再 404
+
+---
+
+## [1.1.4] - 2026-05-21
+
+### 变更
+
+**跨平台门禁：**
+- 门禁逻辑从 bash 脚本移植到 Node.js（`cli.js` 新增 `gate` 子命令）
+- `npx @alenfitz/spec-copilot gate <变更名> <phase>` 可在 Windows/Mac/Linux 运行
+- 原 `scripts/spec-gate.sh` 保留供直接调用，但命令文件统一引用 npx 路径
+- lint 命令引用也改为 `npx @alenfitz/spec-copilot lint`（而非直接调 bash）
+
+---
+
+## [1.1.3] - 2026-05-21
+
+### 变更
+
+**阶段门禁（Gating）：**
+- 新增 `scripts/spec-gate.sh` — 阶段入口条件检查脚本
+- 四个门禁：apply（spec 存在 + §9 清空 + tasks 就绪）、review（冒烟通过）、test（🔴 强制）、archive（审查通过）
+- 门禁不通过 → 阻断当前阶段，提示缺失前置条件
+- cli.js 安装时自动设置可执行权限，doctor 检查项包含门禁脚本
+
+**复杂度感知路由：**
+- 所有命令的 "结束后" 提示根据 spec.md §2 复杂度等级分支
+- 🟢 简单：propose 后直接编码，不进入 spec 流程
+- 🟡 中等：propose → apply → smoke → review → archive（标准五步）
+- 🔴 复杂：propose → apply → smoke → review → test → archive（增加强制测试）
+- 🚑 热修复：hotfix → smoke → archive（独立路径，24h 补全）
+- AGENTS.md 新增"阶段门禁"章节，复杂度表增加"流程"列
+
+**propose 命令修复：**
+- 🟢 简单需求的 "结束后" 不再错误指向 `/spec:apply`，改为"直接编码，自行验证"
+
+---
+
+## [1.1.2] - 2026-05-21
+
+### 变更
+
+**引导式工作流：**
+- 所有命令新增 "结束后" 章节，明确展示下一步命令
+- 流程：init → propose → apply → smoke → review → archive 形成连贯链路
+- smoke/review 命令按通过/失败分支提示不同下一步
+
+---
+
+## [1.1.1] - 2026-05-21
+
+### 变更
+
+**复杂度判定重做：**
+- 移除文件数作为复杂度判定依据（≤3/4-8/>8），改为按影响面评估
+- 影响面维度：API 契约、表结构、核心流程、新依赖、数据迁移、外部集成
+- 区分"核心流程非关键分支"与"核心流程主路径"
+
+**Spec 质量自检：**
+- spec 模板新增"附录：Spec 质量自检"，按章节列出常见不合格写法
+- 覆盖功能点、业务规则、数据变更、接口契约、待澄清、代码现状 6 个维度
+
+**domain-rules 示例：**
+- rules/domain-rules.md 不再是空壳，三个章节各填了带注释的示例条目
+- 示例涵盖订单状态机、退款计算口径、用户注册流程等
+
+**npm 包工程化改进：**
+- cli.js 内嵌模板改为从 framework/ 文件读取，消除双重维护
+- AGENTS.md 描述从"opencode 自动加载"修正为"规范参考文档"
+
+---
+
+## [1.0.0] - 2026-05-21
+
+基于 code_copilot v2.0.0 迁移适配 opencode。
+
+### 核心变更（相对于 code_copilot v2.0）
+
+**加载机制重构：**
+- `agents/copilot-prompt.md` + `CLAUDE.md` 引用 → 合并为单个 `AGENTS.md`
+- Spec Reviewer / Code Quality Reviewer 从独立 agent 文件改为 AGENTS.md 附录 A/B
+- `commands/` 目录：每个斜杠命令拆为独立 .md 文件，映射到 `.opencode/commands/`
+
+**去除 Claude Code 特有机制：**
+- 移除 `.claude/settings.local.json` 权限配置
+- 移除 rules 文件的 `alwaysApply` / `alwaysApply: false` frontmatter（opencode 不识别）
+- 移除 `agents/` 目录（内容合并到 AGENTS.md）
+
+**保持不变：**
+- 规范核心内容（Spec 先行、Task 节奏、知识飞轮）100% 保留
+- `rules/` 目录结构和内容
+- `stack-adapters/` 适配层机制
+- `knowledge/` 知识索引
+- `changes/templates/` 三件套模板
+- `scripts/` 工程化脚本（路径从 `code_copilot` 改为 `spec_copilot`）

package/framework/VERSION

@@ -0,0 +1 @@
+1.4.0

package/framework/changes/templates/log.md

@@ -0,0 +1,25 @@
+# 变更日志 — 需求名称
+
+> 记录决策、踩坑和知识发现。知识飞轮的输入。
+> /spec:archive 时逐条确认"知识发现"是否沉淀到 knowledge/index.md
+
+## 时间线
+| 时间 | 阶段 | 事件 | 备注 |
+
+## 技术决策
+| 决策 | 选择 | 放弃的方案 | 原因 |
+
+## 踩坑记录
+| 问题 | 原因 | 解决方案 | 是否沉淀到 knowledge/？ |
+
+## 知识发现
+> 每个 task 后实时记录；/spec:archive 时逐条确认，已沉淀的打 ✅
+- [ ] **关键词**: 描述（触发场景 + 解决方式，一句话）
+
+## Spec-Code 偏差记录
+> 任何"计划和实际不一致"必须在此记录，不可跳过
+| 偏差点 | Spec 预期 | 实际情况 | 处理方式（修改 spec / 修改代码 / 待讨论） |
+
+## 代码质量备忘
+> /spec:review 阶段 Important/Minor 问题的处置记录
+| 问题 | 级别 | 处置方式 |

package/framework/changes/templates/spec.md

@@ -0,0 +1,118 @@
+# 需求名称
+
+> status: propose | apply | review | done
+> created: YYYY-MM-DD
+> complexity: 🟢 简单 | 🟡 中等 | 🔴 复杂
+
+## 1. 背景与目标
+为什么做 + 做完后的效果（可验证的结果描述）
+
+## 2. 代码现状（Research Findings）
+> 每个结论必须有代码出处（文件路径 + 类名/方法名）
+
+### 2.1 相关入口与链路
+### 2.2 现有实现
+### 2.3 发现与风险
+
+## 3. 功能点
+- [ ] 功能 1：（输入→处理→输出）
+
+## 4. 业务规则
+> 精确描述规则，包含边界条件（如：状态枚举值、时间窗口、幂等键格式）
+
+## 5. 数据变更
+| 操作 | 表名 | 字段/索引 | 说明 |
+
+## 6. 接口变更
+
+| 操作 | Path | Method | 说明 |
+|------|------|--------|------|
+| 新增 | /api/xxx | GET | 查询 xxx |
+
+### 接口契约（每个新增接口必须填写）
+
+```
+GET /api/xxx
+入参：
+  - paramA: String  // 说明，枚举值: A/B/C，默认值: A
+  - paramB: Long    // 说明，null=不过滤
+出参：
+  {
+    "code": 200,
+    "data": {
+      "fieldA": "...",   // 说明
+      "fieldB": 0        // 说明
+    }
+  }
+```
+
+> 说明：前端开发依赖此契约，写代码前必须确认。接口契约与实现不符时 Spec is Truth。
+
+## 7. 影响范围
+
+## 8. 风险与关注点
+> ⚠️ 涉及外部推送/敏感信息必须标注
+
+## 8.5 测试策略
+- **测试范围**：列出必须覆盖的核心场景
+- **正向用例**：（至少 1 条，含预期返回值）
+- **异常用例**：（至少 1 条，如：非法参数/空数据/依赖服务失败）
+- **幂等验证**：（有副作用的接口必填，描述如何验证重复调用安全）
+- **覆盖率目标**：核心 Service 方法 > 80% / 不强制
+- **独立 Test Spec**：是/否
+
+## 9. 待澄清
+- [ ] 问题 1：（全部解决后才能进入 /spec:apply）
+
+## 10. 技术决策
+
+## 11. 执行日志
+| Task | 状态 | 实际改动文件 | 备注 |
+
+## 12. 审查结论
+> /spec:review 完成后填写
+
+- Spec 合规：✅/❌
+- Code Quality：（Critical 问题数 / Important 问题数）
+- 结论：通过 / 需修复
+
+## 13. 确认记录（HARD-GATE）
+- **确认时间**：
+- **确认人**：
+
+---
+
+## 附录：Spec 质量自检（AI 生成 spec 后逐项核对）
+
+> 以下每一项都是常见的 spec 质量问题。如果命中任一条，spec 不合格，修正后再提交确认。
+
+### 功能点（§3）常见问题
+- ❌ 功能点写成需求标题，缺少输入→处理→输出的链路描述
+  - 例："支持导出功能" — 没说导出格式、触发方式、数据范围
+  - ✅ "用户点击列表页[导出]按钮 → 后端查询当前筛选条件下的全部数据 → 生成 xlsx → 返回文件流"
+- ❌ 功能点之间互相依赖但没标注顺序
+- ❌ 功能点遗漏了异常路径（空数据怎么办？失败了怎么提示？）
+
+### 业务规则（§4）常见问题
+- ❌ 使用模糊词汇："尽快"、"适当"、"一般"、"相关"
+  - ✅ 精确表述："超时 30 分钟自动取消"、"重试 3 次间隔递增：1s/5s/15s"
+- ❌ 只写了正常路径，没写边界条件
+  - 例："下单减库存" 但没说库存不足时返回什么错误码
+- ❌ 枚举值只列了 happy path 的值，遗漏了错误/异常状态
+
+### 数据变更（§5）常见问题
+- ❌ 只说"加字段"，没说字段类型、默认值、是否可空、是否需要索引
+- ❌ 涉及已有数据的回填策略未说明
+
+### 接口契约（§6）常见问题
+- ❌ 入参只列了字段名，没写类型、是否必填、枚举值范围
+- ❌ 出参示例和入参对不上（如入参有 pageSize 但出参没分页结构）
+- ❌ 错误响应格式未定义
+
+### 待澄清（§9）常见问题
+- ❌ §9 是空的但 spec 里有大量模糊表述 — 说明 AI 在猜而非澄清
+- ❌ 待澄清项写成开放式问题（"怎么设计？"），而非给用户选项的选择题
+
+### 代码现状（§2）常见问题
+- ❌ "应该是"、"可能是"、"一般用" — 没有读实际代码
+- ❌ 列了不存在的类/方法名 — AI 在编造而非搜索

package/framework/changes/templates/tasks.md

@@ -0,0 +1,48 @@
+# 任务拆分 — 需求名称
+
+> 拆分顺序：数据模型 → 接口协议 → 底层实现 → 上层编排 → 入口层 → 前端
+> 每个任务 = 可独立提交的原子变更（3-5 个文件）
+> 每个任务必须精确到文件路径和函数签名
+
+## 前置条件
+- [ ] spec 已通过 HARD-GATE 确认
+- [ ] 已创建 feature 分支：`git checkout -b feature/<变更名>`（禁止在 main/master 直接编码）
+- [ ] 本地环境就绪（数据库/中间件连接正常）
+- [ ] （其他依赖/配置前提）
+
+---
+
+## Task 1: 任务名
+- **目标**：一句话描述
+- **涉及文件**：
+  - `path/to/File.java` — 新增/修改，做什么
+- **关键签名**：
+  ```java
+  public ResultDTO doSomething(Long id, String type) { }
+  ```
+- **依赖**：无
+- **验收标准**：
+  - 正向：怎样算完成（具体的接口返回值或页面行为）
+  - 异常：非法参数/边界值时的预期行为（如 400 返回、空列表等）
+- **验证命令**（必填，可直接执行的 curl 或测试命令）：
+  ```bash
+  curl -s http://localhost:8080/api/xxx | python3 -m json.tool
+  ```
+- **Git commit**：`git commit -m "[变更名] T1: <中文简述>"`
+- 状态：待完成
+
+---
+
+## Task 2: 任务名
+（同上格式）
+
+---
+
+## 变更摘要
+> ⚠️ /spec:apply 全部完成后必须填写，不填不允许进入 /spec:review
+
+- **总文件数**：X 个新增，Y 个修改
+- **Spec-Plan 偏差记录**：（无偏差 / 列出偏差点及原因）
+- **魔法值是否已提取为常量**：是 / 否（列出遗留项）
+- **注释覆盖情况**：Entity/Service/Controller 注释是否符合 coding-style.md §1
+- **遗留问题**：（下一步需处理的已知缺陷或 TODO）

package/framework/knowledge/index.md

@@ -0,0 +1,48 @@
+# 知识索引
+
+> 领域知识的结构化索引。每条记录用简短格式 + tag 分类，便于 AI 和人类快速检索。
+> 来源：`/spec:archive` 时从 `spec_copilot/changes/*/log.md` 的"知识发现"提炼。
+
+## 记录格式
+
+```
+- [tag1][tag2] **关键词**: 一句话核心逻辑（触发场景 + 解决方式）→ `包名.类名.方法名`（可选代码出处）
+```
+
+## Tag 规范
+
+使用方括号前缀 tag，一个条目可多个 tag。标准 tag 列表如下（新增需 PR 评审）：
+
+**环境与依赖类**
+- `[env]` — 运行时环境、JDK/Node 版本、编译工具链
+- `[deps]` — 第三方依赖选型、版本兼容性
+- `[build]` — 构建/打包相关
+
+**技术实现类**
+- `[concurrency]` — 并发、锁、线程安全
+- `[transaction]` — 事务、一致性
+- `[sql]` — 数据库、SQL 语法、ORM
+- `[cache]` — 缓存策略
+- `[api]` — 接口设计、REST 规范
+- `[frontend]` — 前端框架、组件、状态管理
+- `[quartz]` — 定时任务（或其他调度框架）
+
+**质量类**
+- `[perf]` — 性能优化
+- `[security]` — 安全相关
+- `[bug]` — 非平凡 bug 的根因
+- `[incident]` — 线上故障（来自 /spec:hotfix 归档）
+
+**业务类**
+- `[biz:<领域>]` — 业务规则，如 `[biz:push]` `[biz:auth]`
+
+## 检索约定
+
+- AI 在 `/spec:propose` 时根据需求关键词匹配 tag，提前加载相关历史经验
+- 条目超过 50 条后考虑按大类分文件（如 `knowledge/frontend.md`），`index.md` 只保留一级目录
+
+---
+
+## 条目（按 tag 分组展示）
+
+> 待积累。/spec:archive 时沉淀第一条。