harness-check-clean-state

Core Capabilities

执行清洁状态检查清单，验证系统是否达到"清洁状态"（会话结束时，代码应达到可合并到主分支的状态）。

核心职责：

1. 检查代码质量（编译、测试、Linter）
2. 检查 Git 状态（未提交更改、提交信息格式）
3. 检查功能完成度（feature_list.json 标记）
4. 检查文档更新（EVENT_LOG.md、GLOBAL_STATE.md）
5. 检查可合并性（无冲突、无 TODO/FIXME）
6. 返回检查结果（CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES）

Execution Steps

Step 1: 读取清洁状态检查清单

工具: Read
文件: .EnjoyHarness/CLEAN_STATE_CHECKLIST.md
Token 消耗: ~1000 tokens

Step 2: 检查代码质量

2.1 检查编译

工具: Bash
命令: make build（或项目特定编译命令）
Token 消耗: ~500 tokens
失败处理:
  - 返回 CRITICAL_ISSUES
  - 记录错误到 EVENT_LOG.md（CRITICAL_ISSUES | BUILD_FAILED）
  - 退出检查（不继续后续步骤）

2.2 检查测试

工具: Bash
命令: make test（或项目特定测试命令）
Token 消耗: ~1000 tokens
失败处理:
  - 返回 MODERATE_ISSUES
  - 记录错误到 EVENT_LOG.md（MODERATE_ISSUES | TEST_FAILED）
  - 继续检查其他项（收集完整问题列表）

2.3 检查 Linter

工具: Bash
命令: make lint（或项目特定 Linter 命令）
Token 消耗: ~500 tokens
失败处理:
  - 记录 MINOR_ISSUES
  - 记录警告到 EVENT_LOG.md（MINOR_ISSUES | LINTER_WARNING）
  - 继续检查其他项

Step 3: 检查 Git 状态

工具: Bash
命令: git status --porcelain
验证: 输出为空（无未提交更改）
Token 消耗: ~100 tokens
失败处理:
  - 如果输出非空 → 记录 MINOR_ISSUES
  - 检查未跟踪文件（git status --short | grep "^??"）

Step 4: 检查功能完成度

工具: Read
文件: .EnjoyHarness/feature_list.json
Token 消耗: ~800 tokens

验证逻辑:
  1. 读取当前功能ID（从 GLOBAL_STATE.md）
  2. 在 feature_list.json 中查找该功能
  3. 验证 passes 字段是否为 true

失败处理:
  - 如果 passes: false → 记录 MODERATE_ISSUES
  - 记录到 EVENT_LOG.md（MODERATE_ISSUES | FEATURE_NOT_COMPLETED）

Step 5: 检查文档更新

5.1 检查 EVENT_LOG.md

工具: Bash
命令: grep "SESSION_END" .EnjoyHarness/EVENT_LOG.md
Token 消耗: ~200 tokens
失败处理:
  - 如果未找到 → 记录 MINOR_ISSUES

5.2 检查 GLOBAL_STATE.md

工具: Read
文件: .EnjoyHarness/GLOBAL_STATE.md
Token 消耗: ~200 tokens
验证: 任务状态是否为 completed
失败处理:
  - 如果不是 → 记录 MINOR_ISSUES

Step 6: 检查可合并性

6.1 检查 Git 合并状态

工具: Bash
命令: git merge-base --is-ancestor HEAD main
Token 消耗: ~100 tokens
失败处理:
  - 如果失败 → 记录 MODERATE_ISSUES

6.2 检查 TODO/FIXME

工具: Bash
命令: grep -r "TODO\|FIXME" --include="*.py" --include="*.go" --include="*.js" || true
Token 消耗: ~200 tokens
验证: 输出为空（无未处理的 TODO/FIXME）
失败处理:
  - 如果找到 → 记录 MINOR_ISSUES

Step 7: 输出检查结果

结果类型:
  CLEAN: 所有检查通过
  MINOR_ISSUES: 轻微问题（Linter 警告、Git 未提交、文档未更新）
  MODERATE_ISSUES: 中等问题（测试失败、架构违规、功能未完成）
  CRITICAL_ISSUES: 严重问题（编译失败、文件损坏）

输出格式:
  检查结果: CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES
  检查项总数: 15
  通过项数: X
  失败项数: Y
  失败项列表:
    - [ ] 代码编译
    - [ ] 测试通过
    - [x] Linter 无警告
    ...

Token 消耗: ~200 tokens

Step 8: 记录到 EVENT_LOG.md

工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
  - 时间戳：2026-03-28T12:30:00
  - 事件类型：CLEAN_STATE_CHECK
  - 检查结果：CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES
  - 检查项详情
Token 消耗: ~100 tokens

Prerequisites

必须满足：

• ✅ 已执行 harness-validate-output（架构验证通过）
• ✅ 功能开发完成（工作流最后一个节点执行完成）

如果前置条件不满足：

• 提示用户先完成功能开发和验证
• 拒绝继续执行

Success Criteria

成功标准：

1. ✅ 成功执行所有检查项（15 项）
2. ✅ 正确识别问题级别（CLEAN/MINOR/MODERATE/CRITICAL）
3. ✅ 输出详细的检查结果（通过项、失败项列表）
4. ✅ 记录检查事件到 EVENT_LOG.md

失败情况：

• ❌ 检查脚本执行失败 → 记录错误，返回 CRITICAL_ISSUES
• ❌ 文件读取失败 → 记录错误，返回 MODERATE_ISSUES

Failure Recovery

错误场景 1: 编译失败（CRITICAL_ISSUES）

处理:
  1. 返回 CRITICAL_ISSUES
  2. 记录到 EVENT_LOG.md（CRITICAL_ISSUES | BUILD_FAILED）
  3. 触发 harness-recover-clean-state（自动回滚）
  4. 退出检查

错误场景 2: 测试失败（MODERATE_ISSUES）

处理:
  1. 记录 MODERATE_ISSUES
  2. 继续检查其他项（收集完整问题列表）
  3. 检查完成后触发 harness-recover-clean-state

错误场景 3: Linter 警告（MINOR_ISSUES）

处理:
  1. 记录 MINOR_ISSUES
  2. 继续检查其他项
  3. 检查完成后触发 harness-recover-clean-state

错误场景 4: Git 状态不清洁（MINOR_ISSUES）

处理:
  1. 记录 MINOR_ISSUES
  2. 继续检查其他项
  3. 检查完成后触发 harness-recover-clean-state

Relationships

Triggers (触发下游)

如果检查结果 == CLEAN:
  - 触发 harness-track-feature-progress（标记功能完成）

如果检查结果 != CLEAN:
  - 触发 harness-recover-clean-state（自动修复或回滚）

Triggered By (被谁触发)

触发时机:
  - harness-validate-output 验证通过后
  - 子代理开发完成后
  - 用户显式调用："清洁状态检查"

Dependencies (前置依赖)

必须依赖:
  - harness-validate-output（架构验证）

Token 消耗分析

完整检查流程:
  - 读取检查清单: ~1000 tokens
  - 代码质量检查: ~2000 tokens
  - Git 状态检查: ~100 tokens
  - 功能完成度检查: ~800 tokens
  - 文档更新检查: ~400 tokens
  - 可合并性检查: ~300 tokens
  - 输出检查结果: ~200 tokens
  - 记录 EVENT_LOG: ~100 tokens
  总计: ~4900 tokens

优化方案:
  - 仅检查必要项（跳过手动检查项）
  - Token 消耗降低至 ~3400 tokens

Examples

示例 1: 所有检查通过（CLEAN）

输入:
  - make build: 成功
  - make test: 成功
  - make lint: 成功
  - git status: 空输出
  - feature_list.json: passes: true
  - EVENT_LOG.md: 包含 SESSION_END

处理:
  1. 执行所有检查项（15 项）
  2. 所有检查通过
  3. 返回 CLEAN

输出:
  ✅ 检查结果: CLEAN
  检查项总数: 15
  通过项数: 15
  失败项数: 0

  所有检查项:
  - [x] 代码编译通过
  - [x] 测试通过
  - [x] Linter 无警告
  - [x] Git 状态清洁
  - [x] 功能标记完成
  - [x] 文档已更新

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

示例 2: 测试失败（MODERATE_ISSUES）

输入:
  - make build: 成功
  - make test: 失败（2 个测试用例失败）
  - make lint: 成功
  - git status: 空输出

处理:
  1. 执行所有检查项
  2. 发现测试失败
  3. 记录 MODERATE_ISSUES
  4. 继续检查其他项（收集完整问题列表）

输出:
  ⚠️ 检查结果: MODERATE_ISSUES
  检查项总数: 15
  通过项数: 14
  失败项数: 1

  失败项列表:
  - [ ] 测试通过（2 个测试用例失败）

  下一步：触发 harness-recover-clean-state（自动修复）

示例 3: 编译失败（CRITICAL_ISSUES）

输入:
  - make build: 失败（语法错误）

处理:
  1. 执行编译检查
  2. 发现编译失败
  3. 返回 CRITICAL_ISSUES
  4. 退出检查（不继续后续步骤）

输出:
  🔴 检查结果: CRITICAL_ISSUES
  检查项总数: 15
  通过项数: 0
  失败项数: 1

  失败项列表:
  - [ ] 代码编译（语法错误）

  下一步：触发 harness-recover-clean-state（立即回滚）

示例 4: Git 状态不清洁（MINOR_ISSUES）

输入:
  - make build: 成功
  - make test: 成功
  - git status: 有未提交更改（2 个文件）

处理:
  1. 执行所有检查项
  2. 发现 Git 状态不清洁
  3. 记录 MINOR_ISSUES
  4. 继续检查其他项

输出:
  ⚠️ 检查结果: MINOR_ISSUES
  检查项总数: 15
  通过项数: 14
  失败项数: 1

  失败项列表:
  - [ ] Git 状态清洁（2 个文件未提交）

  下一步：触发 harness-recover-clean-state（自动提交）

Implementation Notes

关键设计决策

1. 分级错误处理
   • CLEAN: 无问题，可继续
   • MINOR_ISSUES: 轻微问题，自动修复
   • MODERATE_ISSUES: 中等问题，尝试修复，失败则回滚
   • CRITICAL_ISSUES: 严重问题，立即回滚
2. 检查顺序
   • 编译优先（CRITICAL_ISSUES 立即退出）
   • 测试其次（MODERATE_ISSUES 继续收集问题）
   • Linter 和 Git 最后（MINOR_ISSUES 继续检查）
3. 问题收集
   • 编译失败立即退出（不继续检查）
   • 其他问题继续检查（收集完整问题列表）
   • 便于一次性修复所有问题

性能优化

并行检查:
  - 代码质量检查（编译、测试、Linter）可并行
  - Git 状态检查和文档更新检查可并行
  - 预计检查时长：2-5 分钟

跳过手动检查:
  - 端到端验证（手动）
  - 下一位开发者可直接开始工作（手动）
  - Token 消耗降低 ~20%