@boyingliu01/xp-gate 0.5.2 → 0.6.0

package/lib/ui-review.ts

@@ -15,9 +15,9 @@ interface UiReviewResult {
 }
 
 function main(): void {
-  // eslint-disable-next-line no-console
+   
   console.log('═══ xp-gate ui-review ═══');
-  // eslint-disable-next-line no-console
+   
   console.log('');
 
   // Get staged + modified files
@@ -25,7 +25,7 @@ function main(): void {
   try {
     files = execSync('git diff --cached --name-only && git diff --name-only', { encoding: 'utf8' }).trim();
   } catch {
-    // eslint-disable-next-line no-console
+     
     console.log('⚠️ No git repo or no changes. Running in current directory.');
   }
 
@@ -35,7 +35,7 @@ function main(): void {
     .filter(f => f.length > 0);
 
   if (fileList.length === 0) {
-    // eslint-disable-next-line no-console
+     
     console.log('No files staged or modified. Checking all tracked files.');
     try {
       files = execSync('git ls-files', { encoding: 'utf8' }).trim();
@@ -48,28 +48,28 @@ function main(): void {
   const result = collectUiMatches(fileList);
 
   if (!result.isUiSprint) {
-    // eslint-disable-next-line no-console
+     
     console.log('ℹ️ No UI changes detected in staged/modified files.');
-    // eslint-disable-next-line no-console
+     
     console.log('  Nothing to review. Exiting.');
     process.exit(0);
   }
 
-  // eslint-disable-next-line no-console
+   
   console.log(`🎨 UI changes detected (${result.matchedFiles.length} files):`);
   result.matchedFiles.forEach(f => console.log(`  - ${f}`));
-  // eslint-disable-next-line no-console
+   
   console.log('');
 
-  // eslint-disable-next-line no-console
+   
   console.log('Next steps required before push:');
-  // eslint-disable-next-line no-console
+   
   console.log('  1. Run /design-review in your AI agent session');
-  // eslint-disable-next-line no-console
+   
   console.log('  2. Run /qa or /qa-only in your AI agent session');
-  // eslint-disable-next-line no-console
+   
   console.log('  3. Ensure you have .delphi-config.json configured for Delphi review');
-  // eslint-disable-next-line no-console
+   
   console.log('');
 
   const commit = execSync('git rev-parse HEAD 2>/dev/null || echo "no-commit"', { encoding: 'utf8' }).trim();
@@ -86,23 +86,23 @@ function main(): void {
 
   writeFileSync(join(process.cwd(), RESULT_FILE), JSON.stringify(uiResult, null, 2) + '\n', 'utf8');
 
-  // eslint-disable-next-line no-console
+   
   console.log(`✅ Generated ${RESULT_FILE} with APPROVED verdict (template)`);
-  // eslint-disable-next-line no-console
+   
   console.log(`   Commit: ${commit}`);
-  // eslint-disable-next-line no-console
+   
   console.log(`   Expires: ${expires}`);
-  // eslint-disable-next-line no-console
+   
   console.log('');
-  // eslint-disable-next-line no-console
+   
   console.log('⚠️  REVIEW THIS FILE before push:');
-  // eslint-disable-next-line no-console
+   
   console.log('   - Ensure design_review and browser_qa are actually APPROVED');
-  // eslint-disable-next-line no-console
+   
   console.log('   - Edit verdict to REJECTED if issues found');
-  // eslint-disable-next-line no-console
+   
   console.log('');
-  // eslint-disable-next-line no-console
+   
   console.log('Then: git push (pre-push will validate this file)');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boyingliu01/xp-gate",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "AI-driven development workflow: 6 quality gates + Delphi review + Sprint Flow",
   "bin": {
     "xp-gate": "./bin/xp-gate.js"

package/plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "xp-gate",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "displayName": "XP-Gate",
   "description": "Extreme Programming quality gates + AI workflow skills for Claude Code. Includes 6 quality gates, Sprint Flow, and Delphi multi-expert review.",
   "author": {

package/skills/sprint-flow/SKILL.md

@@ -53,6 +53,10 @@ maturity: beta
 ```
 Phase -1: ISOLATE → ⚠️ 检测保护分支(main/master/develop/trunk/mainline) → 强制创建 git worktree
             → 已在 worktree 中 → 跳过 → 项目 setup → .gitignore 校验 → sprint-state isolation 记录
+Phase -0.5: AUTO-ESTIMATE → 自动评估需求规模 → ⚠️ 展示评估结果，用户确认
+            → 轻量：跳过 brainstorming + delphi-review，直接 Phase 2 BUILD
+            → 标准：正常流程 Phase 0-4
+            → 复杂：完整流程 Phase 0-8 + 风险警告
 Phase 0: THINK → brainstorming → ⚠️ HARD-GATE: 设计未批准 → 不可进入实现 → Design Document (AI编辑行为约束: 原则3 Surgical Changes, 验证循环要求: 原则4 Goal-Driven Execution - 见 AGENTS.md "## AI CODING DISCIPLINE (Karpathy Principles)")
 Phase 1: PLAN → autoplan → ⚠️ (如有taste_decisions，暂停等用户确认)
            → delphi-review → ⚠️ (等待 APPROVED)
@@ -82,6 +86,7 @@ Phase 8: CLEANUP → git worktree remove + sprint-state.json update → status:
 | 暂停点位置 | 触发条件 | 用户操作 | 自动恢复条件 |
 |-----------|---------|---------|-------------|
 | **Phase -1** | ⚠️ **保护分支强制隔离 / --no-isolate 跳过** | 输出 ⚠️ 警告或自动创建 worktree | 自动创建或用户确认后继续 |
+| **Phase -0.5** | **AUTO-ESTIMATE 结果展示** | 接受建议 / 修改流程 / 取消 | 用户确认后按路由继续 |
 | **Phase 0** | ⚠️ **设计未 APPROVED (HARD-GATE)** | 根据反馈修改设计 | 设计 APPROVED 后继续 |
 | Phase 1 | autoplan surfacing taste_decisions | 用户确认每个决策 | 确认后自动继续 |
 | Phase 1 | delphi-review 未 APPROVED | 修复并重新评审 | APPROVED 后自动继续 |
@@ -155,6 +160,68 @@ Phase 8: CLEANUP → git worktree remove + sprint-state.json update → status:
 
 > **清理提示**: Sprint 完成（Phase 6 SHIP）后，执行 `git worktree remove <worktree_path>` 清理 worktree 目录，同时保留 `.sprint-state/` 中的历史记录。
 
+### Phase -0.5: AUTO-ESTIMATE（自动化规模评估与流程路由）
+
+**执行时机**: Phase -1 ISOLATE 完成后、Phase 0 THINK 之前。**自动执行**。
+
+**目的**: 自动评估需求规模，匹配适度流程，避免小需求走重量级流程造成资源浪费。不依赖人/AI 主观判断，而是通过代码结构分析提供客观指标。
+
+**详细指令**: 参见 `references/phase-minus-0-5-auto-estimate.md`
+
+#### 快速参考
+
+**步骤**:
+1. **识别需求类型** — 删除/修改已存在代码 → 立即分析；新增功能 → brainstorming 后分析
+2. **收集指标** — 引用计数 (`grep -rn`)、跨模块依赖 (目录分布)、循环依赖、Public API 暴露、测试文件数
+3. **汇总评估** — 综合打分 → 轻量 / 标准 / 复杂
+4. **输出结果** — 使用 `templates/auto-estimate-output-template.md` 标准格式
+5. **用户确认** — 接受建议 / 修改流程 / 取消
+6. **路由执行** — 按最终级别进入对应 Phase
+
+**路由决策表**:
+
+| 评估结果 | 路由 | 说明 |
+|---------|------|------|
+| **轻量** (引用 ≤3, 同模块，无循环依赖) | 跳过 Phase 0 brainstorming + Phase 1 delphi-review → 直接进入 Phase 2 BUILD | 小改动不需要完整流程 |
+| **标准** (引用 4-10, 跨 1-2 模块) | 正常流程 Phase 0-4 | 标准 sprint |
+| **复杂** (引用 >10 或 循环依赖 或 跨 3+ 模块) | 完整 Phase 0-8 + 风险警告 | 高风险需求 |
+
+**输出模板**: `templates/auto-estimate-output-template.md`
+**学习日志**: `templates/auto-estimate-learning-log.md`（记录用户 override，用于阈值优化）
+
+**输出格式**:
+```
++-------------------------------------------------------------+
+| AUTO-ESTIMATE 评估结果                                        |
++-------------------------------------------------------------+
+| 需求：{task_description}                                      |
+| 类型：{change_type}                                          |
+|                                                             |
+| [{impact_level}] Impact: {impact_label}                      |
+|                                                             |
+| 引用：{ref_count} 处                                          |
+| 跨模块：{cross_module_count} 个 ({module_list})               |
+| 循环依赖：{circular_dep_status}                               |
+| Public API：{public_api_count} 个                             |
+|                                                             |
+| 建议流程：{recommended_flow}                                  |
+|                                                             |
+| {risk_warning}                                               |
+|                                                             |
+| [接受建议]  [修改流程]  [取消]                                 |
++-------------------------------------------------------------+
+```
+
+**纠偏机制**:
+- **接受建议**: 按推荐流程执行，记录 `user_decision: "accepted"`
+- **修改流程**: 用户选择其他级别，记录 `override_reason` 到 `.sprint-state/auto-estimate-learning.json`
+- **取消**: 停止本次 sprint
+
+**⚠️ 轻量路由的特殊处理**:
+- 轻量路由跳过 Phase 0 brainstorming 和 Phase 1 delphi-review
+- 但仍然执行 Phase 1→2 的 GITHOOKS-GATE 检查
+- Phase 2 BUILD 仍然执行完整 TDD + 盲评 + 验证
+
 ### Phase 0: THINK（需求探索与设计）
 - **Subagent dispatch**: orchestrator 通过 `task(category="deep", load_skills=["brainstorming"])` 启动独立 session
 - 输入: Phase -1 summary（worktree 路径）+ 用户原始需求
@@ -318,11 +385,36 @@ Phase 2 第一步必须执行 DELPHI-GATE 检查。没有 delphi-review APPROVED
 
 ## 编排层规则（Orchestration Rules）
 
+### Agent Dispatch Rules
+
+| Agent Type | 适用场景 | 不适用场景 | 超时处理 |
+|-----------|---------|-----------|---------|
+| `explore` (bare) | **窄搜索**：单个关键词/pattern，已知文件位置 | 多角度宽泛搜索，读取大文件，3+ search angles | >5min → cancel + 用 `deep` 重试 |
+| `librarian` (bare) | **外部参考**：API 文档、OSS 示例 | 内部代码库宽泛探索 | >5min → cancel + 用 `deep` 重试 |
+| `task(category="deep")` | **复杂研究**：多模块分析，架构决策 | 单文件 trivial fix | 无限制 |
+| `task(category="unspecified-high")` | **高 effort 实现**：新模块、重构 | 单行修改 | 无限制 |
+
+**关键规则**：
+
+1. Bare `explore` agent 本质是 contextual grep，**不是研究 agent**。如果任务涉及：
+   - 3+ 个独立搜索角度
+   - 读取多个大文件（>200 行）
+   - 需要跨层分析（如"查 ralph-loop + .sprint-state/ + token 阈值 + phase transition"）
+   
+   → **必须用 `task(category="deep", load_skills=[...])` 替代**
+
+2. 如果 `explore` agent >5 分钟未返回 → cancel 并立即用 `task(category="deep")` 重试。不要等待。
+
+3. **并行 explore 仍然是正确模式**。2-4 个窄搜索 explore agent 并行执行是高效且推荐的。问题在于给单一 explore agent 分配宽泛任务。
+
+**issue #83 根因**：`bg_1abf2ed9` 被分配了 4 个独立搜索角度的宽泛任务（ralph-loop context + .sprint-state/ + token threshold + phase transition），bare explore agent 超时丢失 session。同批的 `bg_5ecf590d`（窄搜索 OpenCode compaction API）3m35s 正常完成。
+
 ### Phase Subagent Dispatch Matrix
 
 | Phase | 名称 | Subagent? | Category | load_skills | 执行者 |
 |-------|------|:---------:|----------|-------------|--------|
 | -1 | ISOLATE | ❌ | Bash（直接执行） | 无 | orchestrator |
+| -0.5 | AUTO-ESTIMATE | ❌ | Bash（直接执行） | 无 | orchestrator |
 | 0 | THINK | ✅ | `deep` | `["brainstorming"]` | subagent |
 | 1 | PLAN | ✅ | `deep` | `["autoplan", "delphi-review", "to-issues"]` | subagent |
 | 2 | BUILD | ✅(已有) | ralph-loop | `["test-driven-development"]` | subagent |
@@ -446,6 +538,22 @@ Sprint state is persisted as JSON in `.sprint-state/sprint-state.json`:
     "created_from": "main",
     "created_from_commit": "abc123def..."
   },
+  "auto_estimate": {
+    "change_type": "删除已存在代码|修改已存在代码|新增功能|Bug修复",
+    "metrics": {
+      "ref_count": 12,
+      "cross_module_count": 3,
+      "modules": ["auth", "user", "admin"],
+      "circular_dep": true,
+      "public_api_count": 5,
+      "test_file_count": 4
+    },
+    "estimated_level": "轻量|标准|复杂",
+    "recommended_flow": "轻量流程 (Phase 2-3)|标准流程 (Phase 0-4)|完整 Sprint Flow (Phase 0-8)",
+    "risk_warnings": ["循环依赖: user ↔ plane"],
+    "user_decision": "accepted|overridden|cancelled",
+    "override_reason": null
+  },
   "outputs": {
     "pain_document": "docs/pain-document.md",
     "specification": "specification.yaml",

package/skills/sprint-flow/references/phase-minus-0-5-auto-estimate.md

@@ -0,0 +1,238 @@
+# Phase -0.5: AUTO-ESTIMATE（自动化规模评估与流程路由）
+
+**执行时机**: Phase -1 ISOLATE 完成后、Phase 0 THINK 之前。**自动执行**。
+
+**目的**: 自动评估需求规模，匹配适度流程，避免小需求走重量级流程造成资源浪费。
+
+**核心原则**: 
+- **客观指标 > 主观判断**：依赖代码结构分析，不依赖人/AI 的主观直觉
+- **显式告知**：用户看到客观指标，不是 AI 主观结论
+- **可纠偏**：用户可接受/修改/取消
+- **学习闭环**：记录用户 override，优化阈值
+
+---
+
+## 执行流程
+
+### 步骤 1: 识别需求类型
+
+分析用户输入的需求描述，判定变更类型：
+
+| 关键词模式 | 变更类型 | AUTO-ESTIMATE 时机 |
+|-----------|---------|-------------------|
+| 删除、移除、去掉、砍掉、清理 + 已有模块名 | 删除已存在代码 | 立即执行 |
+| 修改、改、调整、重构、优化 + 已有模块名 | 修改已存在代码 | 立即执行 |
+| 新增、添加、开发、实现、创建 + 新模块名 | 新增功能 | brainstorming 后执行 |
+| 修复、fix、bug | Bug 修复 | 立即执行 |
+| 无法判断 | 询问用户 | — |
+
+**IF 新增功能**: 跳过当前 AUTO-ESTIMATE，先执行 Phase 0 brainstorming，brainstorming 完成后以设计文档为输入重新执行 AUTO-ESTIMATE。
+
+**IF 删除/修改/Bug 修复**: 继续执行以下步骤。
+
+### 步骤 2: 收集指标
+
+#### 2.1 引用计数
+
+```bash
+# 从用户输入中提取目标关键词（模块名、函数名、类名）
+# 示例：删除平面维护界面 → target="plane", "平面"
+grep -rn "{target_pattern}" --include="*.{ext}" . | grep -v node_modules | grep -v .git | wc -l
+```
+
+**阈值**：
+- ≤3: 轻量
+- 4-10: 标准
+- >10: 复杂
+
+#### 2.2 跨模块依赖
+
+分析引用出现的目录分布：
+
+```bash
+# 提取引用所在的目录（取前两级目录）
+grep -rn "{target_pattern}" --include="*.{ext}" . | grep -v node_modules | grep -v .git | \
+  awk -F: '{print $1}' | sed 's|/[^/]*$||' | sort -u
+```
+
+**阈值**：
+- 1 个目录: 轻量
+- 2 个目录: 标准
+- 3+ 个目录: 复杂
+
+#### 2.3 循环依赖检测
+
+简单检查：如果 A 引用 B 且 B 引用 A，则存在循环依赖。
+
+```bash
+# 简化检测：检查目标是否导入其调用者
+# 这需要根据具体语言调整。对于 TS/JS:
+grep -rn "import.*{target}" --include="*.ts" --include="*.tsx" .
+grep -rn "import.*{caller}" --include="*.ts" --include="*.tsx" {target_dir}/
+```
+
+**阈值**：
+- 无: 正常
+- 存在: 高风险 → 无论如何输出风险警告
+
+#### 2.4 Public API 暴露
+
+```bash
+# 统计目标模块中 export 的数量
+grep -rn "^export " {target_dir}/ --include="*.ts" | wc -l
+```
+
+**阈值**：
+- ≤2: 低影响
+- 3-5: 中影响
+- >5: 高影响 → 输出风险警告
+
+#### 2.5 相关测试文件
+
+```bash
+# 统计与目标相关的测试文件数
+find . -name "*{target}*.test.*" -o -name "*{target}*.spec.*" | grep -v node_modules | wc -l
+```
+
+**阈值**：
+- 0: 无测试覆盖（风险提示）
+- 1-2: 正常
+- >3: 重构工作量大 → 提示
+
+### 步骤 3: 汇总评估
+
+根据各指标得分，汇总整体评估结果：
+
+```
+总分计算：
+- 引用计数：轻量=1, 标准=2, 复杂=3
+- 跨模块：轻量=1, 标准=2, 复杂=3
+- 循环依赖：无=0, 存在=5（强制复杂）
+- Public API：低=0, 中=1, 高=2
+- 测试文件：正常=0, 多=1
+
+总分：1-3 = 轻量 | 4-6 = 标准 | 7+ 或 循环依赖存在 = 复杂
+```
+
+### 步骤 4: 输出评估结果
+
+使用 `templates/auto-estimate-output-template.md` 的标准格式向用户展示评估结果。
+
+**MUST** 遵循模板格式，包含：
+- 需求描述 + 变更类型
+- 影响级别标识
+- 各项指标的具体数值
+- 建议流程
+- 风险警告（如有）
+- 用户操作选项
+
+### 步骤 5: 处理用户选择
+
+#### 用户选择「接受建议」
+
+> 按推荐流程执行。保存评估结果到 sprint-state.json。
+
+```json
+{
+  "auto_estimate": {
+    "change_type": "删除已存在代码",
+    "metrics": {
+      "ref_count": 12,
+      "cross_module_count": 3,
+      "modules": ["auth", "user", "admin"],
+      "circular_dep": true,
+      "public_api_count": 5,
+      "test_file_count": 4
+    },
+    "estimated_level": "复杂",
+    "recommended_flow": "完整 Sprint Flow (Phase 0-8)",
+    "risk_warnings": ["循环依赖: user ↔ plane"],
+    "user_decision": "accepted"
+  }
+}
+```
+
+#### 用户选择「修改流程」
+
+> 展示修改流程子菜单（3 个选项：轻量/标准/完整）。
+> 要求用户输入修改原因（必填）。
+
+记录到学习日志：
+```json
+{
+  "sprint_id": "{sprint_id}",
+  "task_description": "{需求描述}",
+  "estimated_level": "标准",
+  "user_override_level": "轻量",
+  "override_reason": "{用户输入原因}",
+  "timestamp": "{当前时间}"
+}
+```
+
+数据写入 `.sprint-state/auto-estimate-learning.json`（追加模式）。
+
+#### 用户选择「取消」
+
+> 停止本次 sprint。
+> 输出：`[CANCELLED] 用户取消 Sprint，AUTO-ESTIMATE 评估结果为 {estimated_level}`。
+
+### 步骤 6: 路由执行
+
+根据最终确定的流程级别，进入对应 Phase：
+
+| 流程级别 | 路由 |
+|---------|------|
+| **轻量** | → Phase 2 BUILD（跳过 Phase 0 brainstorming、Phase 1 delphi-review） |
+| **标准** | → Phase 0 THINK（正常流程） |
+| **复杂** | → Phase 0 THINK（完整流程 + 风险警告提示） |
+
+---
+
+## 特殊场景处理
+
+### 场景 1: 小改动（总计 < 20 行新增/删除代码）
+
+```bash
+# 检查预估改动量
+git diff --stat HEAD 2>/dev/null  # 如果有局部修改
+```
+
+**处理**: 如果预估改动 < 20 行且涉及 ≤ 2 个文件，自动判定为「轻量」并告知用户，不强制展示完整 AUTO-ESTIMATE 面板。
+
+### 场景 2: 无法提取目标关键词
+
+**处理**: 询问用户「无法自动识别目标模块，请指定要分析的关键词（函数名/类名/模块名）：」
+
+### 场景 3: 用户输入包含多个独立需求
+
+**处理**: 提示用户「检测到多个独立需求，建议分别执行 sprint。是否拆分？」→ 等待确认
+
+---
+
+## 与学习循环的集成
+
+### 数据收集
+
+每次 sprint 完成（Phase 8 CLEANUP）后，将以下数据记录到 `.sprint-state/auto-estimate-learning.json`：
+
+```json
+{
+  "entries": [
+    {
+      "sprint_id": "sprint-YYYY-MM-DD-NN",
+      "estimated_level": "标准",
+      "user_decision": "accepted",
+      "actual_effort_phase_count": 5,
+      "actual_duration_minutes": 45,
+      "was_accurate": true
+    }
+  ]
+}
+```
+
+### 阈值优化
+
+当积累 ≥ 20 条记录后，提示用户可以运行阈值分析：
+
+> 已积累 {n} 条 AUTO-ESTIMATE 记录。是否运行阈值优化分析？
+> 分析会检查：过度估计（建议标准但实际轻量）、低估（建议轻量但实际复杂），并推荐阈值调整。

package/skills/sprint-flow/templates/auto-estimate-learning-log.md

@@ -0,0 +1,136 @@
+# AUTO-ESTIMATE 学习日志
+
+本文件记录 AUTO-ESTIMATE 的用户纠偏历史和完成数据，用于阈值迭代优化。
+
+## 文件位置
+
+`.sprint-state/auto-estimate-learning.json`
+
+## JSON Schema
+
+```json
+{
+  "entries": [
+    {
+      "sprint_id": "sprint-2026-06-01-14",
+      "task_description": "实现issue92 auto-estimate",
+      "change_type": "新增功能",
+      "estimated_level": "标准",
+      "estimated_metrics": {
+        "ref_count": null,
+        "cross_module_count": 2,
+        "circular_dep": false,
+        "public_api_count": 0,
+        "test_file_count": 0
+      },
+      "user_decision": "accepted",
+      "override_reason": null,
+      "actual_outcome": {
+        "phase_count": 3,
+        "duration_estimate": "30-45min",
+        "was_accurate": true,
+        "notes": "纯文档修改，实际确实为标准级别"
+      },
+      "timestamp": "2026-06-01T23:35:00+08:00"
+    }
+  ],
+  "summary": {
+    "total_entries": 1,
+    "accepted_count": 1,
+    "overridden_count": 0,
+    "accurate_count": 1,
+    "over_estimate_count": 0,
+    "under_estimate_count": 0,
+    "last_updated": "2026-06-01T23:35:00+08:00"
+  }
+}
+```
+
+## 字段说明
+
+### Entry 级别
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `sprint_id` | string | ✅ | Sprint 标识符 |
+| `task_description` | string | ✅ | 需求描述 |
+| `change_type` | string | ✅ | 变更类型：`删除已存在代码` / `修改已存在代码` / `新增功能` / `Bug修复` |
+| `estimated_level` | string | ✅ | 评估级别：`轻量` / `标准` / `复杂` |
+| `estimated_metrics` | object | ✅ | 评估时的指标数据 |
+| `user_decision` | string | ✅ | 用户决定：`accepted` / `overridden` / `cancelled` |
+| `override_reason` | string | 条件 | 当 `user_decision` 为 `overridden` 时必填 |
+| `actual_outcome` | object | 条件 | Sprint 完成后回填 |
+| `timestamp` | string | ✅ | ISO 8601 时间戳 |
+
+### actual_outcome 级别
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `phase_count` | number | ✅ | 实际执行的 phase 数 |
+| `duration_estimate` | string | 推荐 | 实际耗时估算 |
+| `was_accurate` | boolean | ✅ | 评估是否准确 |
+| `notes` | string | 推荐 | 备注说明 |
+
+### summary 级别
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total_entries` | number | 总条目数 |
+| `accepted_count` | number | 接受建议数 |
+| `overridden_count` | number | 用户修改数 |
+| `accurate_count` | number | 评估准确数 |
+| `over_estimate_count` | number | 高估数（建议标准但实际轻量） |
+| `under_estimate_count` | number | 低估数（建议轻量但实际复杂） |
+
+## 初始化
+
+新 sprint 创建时，自动创建 `.sprint-state/auto-estimate-learning.json`：
+
+```json
+{
+  "entries": [],
+  "summary": {
+    "total_entries": 0,
+    "accepted_count": 0,
+    "overridden_count": 0,
+    "accurate_count": 0,
+    "over_estimate_count": 0,
+    "under_estimate_count": 0,
+    "last_updated": null
+  }
+}
+```
+
+## 阈值优化触发
+
+当 `total_entries >= 20` 时，在 Phase 8 CLEANUP 阶段提示用户：
+
+```
+已积累 20 条 AUTO-ESTIMATE 记录。是否运行阈值优化分析？
+
+当前准确率：{accurate_count / total_entries * 100}%
+高估率：{over_estimate_count / total_entries * 100}%
+低估率：{under_estimate_count / total_entries * 100}%
+
+[运行分析] [跳过]
+```
+
+## 阈值优化规则
+
+### 高估模式检测
+
+IF `over_estimate_count / total_entries > 30%`:
+→ 建议降低「标准」→「复杂」的引用计数阈值（当前 >10）
+→ 分析高估的共性：是否某个指标权重过高？
+
+### 低估模式检测
+
+IF `under_estimate_count / total_entries > 20%`:
+→ 建议增加额外检查项（如循环依赖、测试文件数）
+→ 分析低估的共性：是否遗漏了关键复杂度信号？
+
+### 纠偏频率检测
+
+IF `overridden_count / total_entries > 30%`:
+→ 用户频繁修改建议 → 阈值体系可能有问题
+→ 建议全面阈值校准