harness-recover-clean-state

name	harness-recover-clean-state
description	根据不清洁状态类型，执行自动修复或回滚，恢复到清洁状态
trigger_words	["harness-recover-clean-state","恢复清洁状态","clean state recovery"]
priority	HIGH
dependencies	["harness-check-clean-state"]
version	v1.0.0

harness-recover-clean-state

Core Capabilities

根据清洁状态检查结果，执行自动修复或回滚，恢复到清洁状态。

核心职责：

1. 读取 GLOBAL_STATE.md（获取当前功能）
2. 根据问题类型执行修复（MINOR/MODERATE/CRITICAL）
3. 自动修复 Linter 警告、Git 未提交更改
4. 自动修复测试失败（尝试 1-2 次）
5. 自动回滚到上一个清洁提交（CRITICAL_ISSUES）
6. 重新运行清洁状态检查
7. 处理修复失败（失败次数 ≥ 3 → 判定真实阻塞后再人工升级）

Execution Steps

Step 1: Read GLOBAL_STATE.md（获取当前功能）

工具: Read
文件: .EnjoyHarness/GLOBAL_STATE.md
Token 消耗: ~200 tokens
目的: 获取 current_feature 字段（当前功能ID）

Step 2: 根据问题类型执行修复

2.1 MINOR_ISSUES（轻微问题）

问题类型:
  - Linter 警告
  - Git 未提交更改
  - 文档未更新
  - TODO/FIXME 遗留

修复流程:
  1. 自动修复 Linter 警告
     工具: Bash
     命令: make lint --fix（或项目特定修复命令）
     Token 消耗: ~1000 tokens

  2. 自动提交 Git 更改
     工具: Bash
     命令: git add . && git commit -m "fix: auto-fix linter warnings"
     Token 消耗: ~200 tokens

  3. 更新文档
     工具: Edit
     文件: .EnjoyHarness/EVENT_LOG.md
     追加: SESSION_END 事件
     Token 消耗: ~100 tokens

  4. 标记 TODO/FIXME（可选）
     工具: Edit
     处理: 将 TODO/FIXME 添加到临时清单，下次会话处理
     Token 消耗: ~100 tokens

总 Token 消耗: ~1400 tokens

2.2 MODERATE_ISSUES（中等问题）

问题类型:
  - 测试失败
  - 架构违规
  - 功能未标记完成
  - 端到端验证失败

修复流程:
  1. 尝试自动修复测试失败
     工具: Bash + AI 分析
     方法:
       - 分析测试失败日志
       - 定位失败原因
       - 修改代码修复问题
     Token 消耗: ~3000 tokens

  2. 重新运行测试
     工具: Bash
     命令: make test
     Token 消耗: ~1000 tokens

  3. 如果测试仍然失败:
     - 失败次数 +1
     - 如果失败次数 < 3 → 重试修复（返回步骤 1）
     - 如果失败次数 ≥ 3 → 触发回滚（步骤 3）

  4. 如果测试通过:
     - 更新 feature_list.json（passes: true）
     - 更新 EVENT_LOG.md
     - 继续下一步

总 Token 消耗: ~6000 tokens（含重试）

2.3 CRITICAL_ISSUES（严重问题）

问题类型:
  - 无法编译
  - 文件损坏
  - 依赖缺失

修复流程:
  1. 立即回滚到上一个清洁提交
     工具: Bash
     命令:
       - 查找上一个清洁提交：git log --grep="clean-state: true" --oneline -1
       - 如果没有清洁提交，使用最近一次成功构建的提交：git log --grep="BUILD_SUCCESS" --oneline -1
       - 如果都没有，使用最近一次提交：git log --oneline -1

  2. 执行回滚
     工具: Bash
     命令: git reset --hard {last-clean-commit}
     Token 消耗: ~500 tokens

  3. 记录回滚事件
     工具: Edit
     文件: .EnjoyHarness/EVENT_LOG.md
     追加内容:
       - 时间戳：2026-03-28T12:35:00
       - 事件类型：ROLLBACK
       - 回滚原因：CRITICAL_ISSUES
       - 回滚提交：{commit-hash}
     Token 消耗: ~100 tokens

  4. 验证回滚结果
     工具: Bash
     命令: make build
     Token 消耗: ~500 tokens

  5. 如果回滚失败:
     - 触发 harness-handle-failure 或标记真实阻塞
     - 仅在无法继续自动恢复时升级 harness-escalate-to-human
     - 记录到 EVENT_LOG.md（ESCALATION | ROLLBACK_FAILED）

总 Token 消耗: ~1100 tokens

Step 3: 重新运行清洁状态检查

工具: Skill
技能: harness-check-clean-state
Token 消耗: ~3400 tokens
目的: 验证修复或回滚是否成功

Step 4: 处理检查结果

如果检查结果 == CLEAN:
  - 输出"清洁状态已恢复"
  - 继续下一步（触发 harness-track-feature-progress）

如果检查结果 != CLEAN:
  - 失败次数 +1
  - 如果失败次数 < 3 → 返回 Step 2（重新修复）
  - 如果失败次数 ≥ 3 → 判定是否进入真实阻塞升级（Step 5）

Step 5: 真实阻塞升级（失败次数 ≥ 3 且自动恢复无效）

工具: Skill
技能: harness-escalate-to-human
参数:
  - 原因：修复失败 3 次
  - 问题类型：MINOR/MODERATE/CRITICAL
  - 当前功能：{current_feature}

记录到 EVENT_LOG.md:
  - 时间戳：2026-03-28T12:40:00
  - 事件类型：ESCALATION
  - 原因：修复失败 3 次
  - 需要真实阻塞升级

Token 消耗: ~200 tokens

Prerequisites

必须满足：

• ✅ 已执行 harness-check-clean-state（有检查结果）
• ✅ 检查结果 != CLEAN（确实存在问题）

如果前置条件不满足：

• 提示"当前状态已是清洁状态，无需恢复"
• 拒绝继续执行

Success Criteria

成功标准：

1. ✅ 成功识别问题类型（MINOR/MODERATE/CRITICAL）
2. ✅ 成功执行修复或回滚
3. ✅ 清洁状态检查通过（CLEAN）
4. ✅ 记录修复事件到 EVENT_LOG.md

失败情况：

• ❌ 修复失败 3 次且自动恢复无效 → 升级真实阻塞处理
• ❌ 回滚失败且自动恢复无效 → 升级真实阻塞处理
• ❌ 清洁状态检查失败 → 返回 Step 2 重试

Failure Recovery

错误场景 1: 修复失败 3 次

检测: 失败次数 ≥ 3
处理:
  1. 记录到 EVENT_LOG.md（ERROR | FIX_FAILED_3_TIMES）
  2. 判定为真实阻塞后触发 harness-escalate-to-human
  3. 退出自动恢复循环

错误场景 2: 回滚失败

检测: git reset 失败
处理:
  1. 记录到 EVENT_LOG.md（ERROR | ROLLBACK_FAILED）
  2. 判定为真实阻塞后触发 harness-escalate-to-human
  3. 退出自动恢复循环

错误场景 3: 无法找到清洁提交

检测: git log --grep="clean-state: true" 返回空
处理:
  1. 使用最近一次成功构建的提交
  2. 如果也没有，使用最近一次提交
  3. 记录警告到 EVENT_LOG.md（WARNING | NO_CLEAN_COMMIT_FOUND）

Relationships

Triggers (触发下游)

修复成功:
  - 触发 harness-check-clean-state（重新检查）
  - 如果通过 → 触发 harness-track-feature-progress（标记完成）

修复失败:
  - 默认返回 harness-handle-failure / 自动恢复
  - 仅真实阻塞时触发 harness-escalate-to-human

Triggered By (被谁触发)

触发时机:
  - harness-check-clean-state 检测到不清洁状态
  - 用户显式调用："恢复清洁状态"

Dependencies (前置依赖)

必须依赖:
  - harness-check-clean-state（检查结果）

Token 消耗分析

轻微问题修复（MINOR_ISSUES）:
  - Read GLOBAL_STATE.md: ~200 tokens
  - 自动修复 Linter: ~1000 tokens
  - 自动提交 Git: ~200 tokens
  - 更新文档: ~200 tokens
  - 重新检查: ~3400 tokens
  总计: ~5000 tokens

中等问题修复（MODERATE_ISSUES）:
  - 分析测试失败: ~3000 tokens
  - 修改代码: ~3000 tokens
  - 重新运行测试: ~1000 tokens
  - 重新检查: ~3400 tokens
  总计: ~10400 tokens（含重试）

严重问题回滚（CRITICAL_ISSUES）:
  - Read GLOBAL_STATE.md: ~200 tokens
  - 查找清洁提交: ~200 tokens
  - 执行回滚: ~500 tokens
  - 验证回滚: ~500 tokens
  - 重新检查: ~3400 tokens
  总计: ~4800 tokens

Examples

示例 1: Linter 警告自动修复（MINOR_ISSUES）

输入:
  问题类型: Linter 警告（格式问题）
  失败项: "Linter 无警告"

处理:
  1. Read GLOBAL_STATE.md（获取 current_feature）
  2. 执行 make lint --fix
  3. 提交修复：git add . && git commit -m "fix: auto-fix linter warnings"
  4. 更新 EVENT_LOG.md（追加 SESSION_END）
  5. 调用 harness-check-clean-state（重新检查）
  6. 检查通过（CLEAN）

输出:
  ✅ 清洁状态已恢复
  修复内容: Linter 警告自动修复
  提交哈希: abc1234

  下一步：触发 harness-track-feature-progress（标记完成）

示例 2: 测试失败自动修复（MODERATE_ISSUES）

输入:
  问题类型: 测试失败（2 个测试用例失败）
  失败项: "测试通过"

处理:
  1. Read GLOBAL_STATE.md
  2. 分析测试失败日志
  3. 定位失败原因（边界条件未处理）
  4. 修改代码修复问题
  5. 重新运行测试（成功）
  6. 调用 harness-check-clean-state（重新检查）
  7. 检查通过（CLEAN）

输出:
  ✅ 清洁状态已恢复
  修复内容: 测试失败自动修复
  失败次数: 1
  修复项: 边界条件处理

  下一步：触发 harness-track-feature-progress（标记完成）

示例 3: 编译失败自动回滚（CRITICAL_ISSUES）

输入:
  问题类型: 编译失败（语法错误）
  失败项: "代码编译"

处理:
  1. Read GLOBAL_STATE.md
  2. 查找上一个清洁提交（abc123）
  3. 执行回滚：git reset --hard abc123
  4. 验证回滚：make build（成功）
  5. 调用 harness-check-clean-state（重新检查）
  6. 检查通过（CLEAN）

输出:
  ✅ 清洁状态已恢复
  回滚提交: abc123
  回滚原因: 编译失败

  下一步：重新开始当前功能开发

示例 4: 修复失败 3 次触发真实阻塞升级

输入:
  问题类型: 测试失败
  失败次数: 3

处理:
  1. 尝试修复（第 1 次）→ 失败
  2. 尝试修复（第 2 次）→ 失败
  3. 尝试修复（第 3 次）→ 失败
  4. 失败次数 ≥ 3
  5. 触发 harness-escalate-to-human
  6. 记录到 EVENT_LOG.md（ESCALATION | FIX_FAILED_3_TIMES）

输出:
  ⚠️ 修复失败 3 次，自动恢复已穷尽
  问题类型: 测试失败
  当前功能: FEAT-001
  失败次数: 3

  下一步：进入真实阻塞升级流程

示例 5: 回滚失败触发真实阻塞升级

输入:
  问题类型: 编译失败
  回滚失败: git reset 失败

处理:
  1. 尝试回滚 → 失败
  2. 记录错误到 EVENT_LOG.md（ERROR | ROLLBACK_FAILED）
  3. 触发 harness-escalate-to-human

输出:
  🔴 回滚失败，自动恢复无法继续
  问题类型: 编译失败
  回滚命令: git reset --hard abc123
  错误信息: fatal: Could not parse object 'abc123'

  下一步：进入真实阻塞升级流程

Implementation Notes

关键设计决策

1. 三层兜底机制

   • 第一层：自动修复（MINOR/MODERATE）
   • 第二层：自动回滚（CRITICAL 或修复失败）
   • 第三层：真实阻塞升级（修复失败 3 次或回滚失败）

2. 修复优先级

   • MINOR_ISSUES: 自动修复（Linter、Git、文档）
   • MODERATE_ISSUES: 尝试修复 1-2 次，失败则回滚
   • CRITICAL_ISSUES: 立即回滚，不尝试修复

3. 失败计数

   • 每个功能独立计数（避免跨功能影响）
   • 失败次数存储在 GLOBAL_STATE.md
   • 达到 3 次 → 进入真实阻塞升级评估

性能优化

修复策略:
  - MINOR_ISSUES: 快速修复（1 分钟内）
  - MODERATE_ISSUES: 尝试修复（5-10 分钟）
  - CRITICAL_ISSUES: 立即回滚（1 分钟内）

Token 优化:
  - 避免重复读取文件
  - 使用增量式状态摘要
  - 并行执行多个检查项