# GOVERNANCE.md — Execution Governance Protocol 🔒

> **Canonical Reference.** This file defines the Execution Governance layer.
> AGENTS.md §4 mandates compliance; this file is the full specification.
> Every Agent Package MUST follow this protocol. No exceptions.

<!-- openclaw:governance:doctag -->

---

## §0 Purpose

Execution Protocol（AGENTS.md）解决了 **做什么、谁来做、先做什么**。

Execution Governance 解决：

| 问题 | 回答 |
|------|------|
| 是否真的在做？ | 心跳 + 状态机 |
| 是否按计划做？ | Execution Audit |
| 是否偏离目标？ | Scope Explosion Detector |
| 是否应该停止？ | Auto-Stop Rule |
| 是否应该重规划？ | Replanning Trigger |

**核心理念：计划是廉价的，治理是不可协商的。**

---

## §1 State Machine

每个 Agent Package 必须遵循统一状态机。禁止自定义状态。

### §1.1 Allowed States (7)

```
NOT_STARTED
IN_PROGRESS
BLOCKED
WAITING_DEPENDENCY
READY_FOR_REVIEW
VERIFIED
FAILED
ARCHIVED
```

### §1.2 State Transition Diagram

```mermaid
stateDiagram-v2
    [*] --> NOT_STARTED
    NOT_STARTED --> IN_PROGRESS

    IN_PROGRESS --> BLOCKED
    IN_PROGRESS --> WAITING_DEPENDENCY
    IN_PROGRESS --> READY_FOR_REVIEW

    BLOCKED --> IN_PROGRESS
    WAITING_DEPENDENCY --> IN_PROGRESS

    READY_FOR_REVIEW --> VERIFIED
    READY_FOR_REVIEW --> FAILED

    FAILED --> IN_PROGRESS

    VERIFIED --> ARCHIVED

    ARCHIVED --> [*]
```

### §1.3 Transition Table

| From | To | Condition |
|------|----|-----------|
| NOT_STARTED | IN_PROGRESS | Agent Package 开始执行 |
| IN_PROGRESS | BLOCKED | 遇到阻塞，无法继续（见 §6 Blocker） |
| IN_PROGRESS | WAITING_DEPENDENCY | 依赖的其他 Agent Package 尚未完成 |
| IN_PROGRESS | READY_FOR_REVIEW | 工作完成，提审 |
| BLOCKED | IN_PROGRESS | 阻塞已解除 |
| WAITING_DEPENDENCY | IN_PROGRESS | 依赖已完成 |
| READY_FOR_REVIEW | VERIFIED | 审核通过 |
| READY_FOR_REVIEW | FAILED | 审核不通过 |
| FAILED | IN_PROGRESS | 修改后重新执行 |
| VERIFIED | ARCHIVED | 项目归档 |

### §1.4 Prohibited Transitions

以下直接跳跃 **违规**：

```
NOT_STARTED → VERIFIED        ❌
NOT_STARTED → FAILED          ❌
NOT_STARTED → ARCHIVED        ❌
IN_PROGRESS  → VERIFIED       ❌（必须经过 READY_FOR_REVIEW）
IN_PROGRESS  → FAILED         ❌（必须经过 READY_FOR_REVIEW）
BLOCKED      → READY_FOR_REVIEW ❌
BLOCKED      → VERIFIED       ❌
BLOCKED      → ARCHIVED       ❌
WAITING_DEPENDENCY → READY_FOR_REVIEW ❌
VERIFIED     → IN_PROGRESS    ❌（如需修改，回退到 FAILED）
```

---

## §2 Heartbeat Rule

### §2.1 Mandatory Write

每个 Agent Package 必须定期写入 `progress.log`。

**格式（JSON Lines，每行一条记录）:**

```json
{"ts":"2026-06-06T05:00:00+08:00","status":"IN_PROGRESS","completed":["T1","T2"],"remaining":["T3","T4"],"risk":"dependency T4 not started","next_action":"kickoff T3"}
```

**字段说明:**

| 字段 | 必填 | 说明 |
|------|------|------|
| `ts` | ✅ | ISO-8601 时间戳，含时区 |
| `status` | ✅ | 当前状态机的合法状态 |
| `completed` | ✅ | 已完成的任务 ID 列表 |
| `remaining` | ✅ | 剩余任务 ID 列表 |
| `risk` | 条件 | 存在风险时必填 |
| `next_action` | ✅ | 下一步具体操作 |

**文件位置:** `<agent-package-root>/progress.log`

### §2.2 Heartbeat Frequency

| Package Size | Max Interval Before Stale |
|-------------|--------------------------|
| Small | 30 分钟 |
| Medium | 2 小时 |
| Large | 8 小时 |

### §2.3 Stale Task Detection

未在 Max Interval 内写入心跳 → **判定为 `STALE`**。

STALE 检测器自动标记该 Agent Package 为 `BLOCKED`，并写入警报。

### §2.4 Heartbeat Format Template

见 `scripts/templates/progress.log.template`。

---

## §3 Blocker Management

### §3.1 Blocker Declaration

状态变为 `BLOCKED` 时，必须立即创建 `blocker.md`。

**文件位置:** `<agent-package-root>/blocker.md`

### §3.2 Blocker Schema

See `protocol-reference/templates.md` §blocker for the full schema.

### §3.3 Blocker Escalation

如果 `escalated: YES`，必须同时：

1. 写入 `blocker.md`
2. 通知用户（如可送达）
3. 停止当前 Agent Package 的后续执行

### §3.4 Blocker Resolution

在 blocker 解除时：

1. 填充 `resolved_at` 字段
2. 状态迁移 `BLOCKED → IN_PROGRESS`
3. 在心跳中记录解除信息

---

## §4 Replanning Trigger

### §4.1 Trigger Conditions

满足任意条件，必须触发 **REPLAN REQUIRED**：

| # | Condition | Source |
|---|-----------|--------|
| R1 | 某个 Agent Package 变为 `FAILED` | State Machine |
| R2 | `BLOCKED` 持续时间超过 2 倍 Stale 阈值 | Heartbeat |
| R3 | Dependency 失败（依赖的 Agent Package 进入 `FAILED`） | State Machine |
| R4 | Quality Gate 失败（AGENTS.md §5 Pre-flight Compliance） | Execution Protocol |
| R5 | Test 失败超过阈值 | Test Runner |
| R6 | Scope Explosion 被触发（§7） | Scope Detector |
| R7 | Project Health Score < 60（§9） | Health Score |
| R8 | 连续失败 > 3 | Auto-Stop |

### §4.2 Replanning Protocol

1. **暂停**所有相关的 Agent Package（状态 → `BLOCKED`）
2. **分析**失败原因 — 是否系统性？是否需要调整 Task Tree？
3. **输出**修订后的 Task Tree 和 PLAN
4. **记录** replan evidence 到 `execution-audit.md`
5. **恢复**执行（状态 → `IN_PROGRESS`）

### §4.3 Replan Log Entry

每次 replan 必须在 `execution-audit.md` 中记录（格式见 `protocol-reference/templates.md` §replan）。

---

## §5 Scope Explosion Detector

### §5.1 Detection Rules

如果以下任意条件成立，判定为 **SCOPE EXPLOSION**：

| # | Condition | Measurement |
|---|-----------|-------------|
| S1 | 预计代码量增长 > 2x | 初始估算 vs 当前估算 |
| S2 | 预计文件数增长 > 2x | 初始文件清单 vs 当前文件清单 |
| S3 | 出现新的业务域 | 最初未包含的概念/模块 |
| S4 | 依赖深度增加 > 1 | 初始依赖链 vs 当前依赖链 |

### §5.2 Required Actions

检测到 Scope Explosion 后必须：

1. **拆分**当前 Agent Package 成多个子包
2. **重新规划** Task Tree
3. **记录** scope change 证据到 `execution-audit.md`
4. **通知**用户

### §5.3 Prevention

- 每个 Agent Package 声明 `Context Budget`（AGENTS.md §Agent Package Context Budget）
- 如果 `Utilization > 90%`，在启动前就拆分，不要等爆发

---

## §6 Execution Audit

### §6.1 Daily Audit

每天生成 `execution-audit.md`。

**文件位置:** `<project-root>/execution-audit.md`

### §6.2 Audit Schema

See `protocol-reference/templates.md` §execution-audit for full schema.

## §7 Project Health Score

### §7.1 Dimension Definitions

#### D1 — Delivery Score (0–100)

度量：实际完成速度 vs 计划速度。

```
Delivery Score = min(100, (completed_tasks / planned_tasks) × 100 × schedule_adjustment)
```

其中 `schedule_adjustment` = 如果超出计划时间则衰减 0.9/天。

#### D2 — Quality Score (0–100)

度量：Failures / Reviews 比率。

```
Quality Score = max(0, 100 - (failed_reviews / total_reviews) × 100)
```

不通过率越高分越低。

#### D3 — Parallelism Score (0–100)

度量：实际并发 Agent Package 数 vs 最大可能并发。

```
Parallelism Score = min(100, (avg_active_packages / max_possible_packages) × 100)
```

一个都没并行起来 → 0。全在跑 → 100。

#### D4 — Dependency Score (0–100)

度量：依赖等待时间占总时间的比例。

```
Dependency Score = max(0, 100 - (waiting_time / total_time) × 100)
```

等依赖的时间越长，分越低。

#### D5 — Learning Score (0–100)

度量：Reflection 覆盖率和知识沉淀。

```
Learning Score = min(100, reflections_written × 10 + patterns_promoted × 5)
```

上限 100，鼓励写 Reflection 和 Promotion。

### §7.2 Final Score

```
Health Score = Delivery × 0.30 + Quality × 0.25 + Parallelism × 0.15 + Dependency × 0.15 + Learning × 0.15
```

### §7.3 Rating

See `protocol-reference/metrics.md` §Rating for the full rating table (EXCELLENT→CRITICAL).

---

## §8 Auto-Stop Rule

### §8.1 Stop Conditions

满足任意条件，**立即停止**执行：

| # | Condition | Threshold |
|---|-----------|-----------|
| A1 | 连续失败次数 | > 3 |
| A2 | Project Health Score | < 60 |
| A3 | Critical Dependency Failed | 依赖的 Agent Package 进入 FAILED，且该 Agent Package 是硬依赖 |

### §8.2 RECOVERY MODE

进入 RECOVERY MODE 后：

1. **禁止**创建新的 Agent Package
2. **禁止**修改代码
3. **必须**执行以下恢复步骤：
   - 生成 Recovery Report（包含所有 FAILED/BLOCKED/STALE 的状态快照）
   - 分析 root cause 链（为什么走到这一步？最早在哪个决策点出问题？）
   - 调整 Task Tree 和 PLAN
   - 提交 recovery plan 给用户审批
4. **只有**用户明确批准后，才可退出 RECOVERY MODE

### §8.3 Recovery Report Template

见 `scripts/templates/recovery-report.md.template`。

---

## §9 Governance Quality Gate

### §9.1 Pre-Output Checklist

See `protocol-reference/quality-gates.md` §GOVERNANCE for full checklist.

### §9.2 Gate Failure

若任意一项未通过：

```
❌ GOVERNANCE FAILED — 项目治理失败。禁止输出。
```

必须修复所有未通过项后才能输出。

### §9.3 Integration with AGENTS.md

Governance Quality Gate 在 AGENTS.md §5 Verification Protocol 的 `## VERIFICATION` 块 **之后、输出之前** 执行。

---

## §10 Governance State Initialization

### §10.1 Project Start

每个新项目启动时：

1. 创建 `<project-root>/GOVERNANCE.md`（符号链接或副本指向本文档）
2. 创建 `<project-root>/execution-audit.md`（空文件，等待 Audit 填充）
3. 为每个 Agent Package 创建 `progress.log`
4. 初始化所有 Agent Package 状态为 `NOT_STARTED`

### §10.2 Agent Package Handoff

当一个 Agent Package 完成（→ `VERIFIED` → `ARCHIVED`）：

1. 最后写入一条心跳（`status: ARCHIVED`）
2. 更新 `execution-audit.md` 中的 Task Status Matrix
3. 触发依赖等待的 Agent Package 检查（`WAITING_DEPENDENCY → IN_PROGRESS`）

### §10.3 Governance Override

Governance Protocol 可以通过以下方式被 override：

| Override | 权限 | 记录要求 |
|----------|------|----------|
| 跳过 State Transition Rules | 仅红尘 | 必须在 audit 中记录原因 |
| 跳过 Auto-Stop | 仅红尘 | 必须在 audit 中记录风险接受声明 |
| 修改 Stale 阈值 | 仅红尘 | 必须在 audit 中记录新阈值和理由 |
| 修改 Health Score 权重 | 仅红尘 | 必须在 audit 中记录新权重 |

**任何 override 不代表协议失效，只是用户明确同意的偏差。** 每次 override 必须在 `execution-audit.md` 的 Override Log 中记录。

---

## §11 Integration Summary

```text
AGENTS.md (Execution Protocol)          GOVERNANCE.md (Governance Protocol)
│                                       │
├─ §0 Classify                         │
├─ §1 Task Tree                        │
├─ §2 PLAN                             │
├─ §3 Pre-flight                       │
├─ §4 (reference → GOVERNANCE.md) ─────┤
│                                       ├─ §1 State Machine
│                                       ├─ §2 Heartbeat
│                                       ├─ §3 Blocker
│                                       ├─ §4 Replanning
│                                       ├─ §5 Scope Explosion
│                                       ├─ §6 Execution Audit
│                                       ├─ §7 Health Score
│                                       ├─ §8 Auto-Stop
│                                       └─ §9 Quality Gate
│                                       │
├─ §5 Verification                      │
│   └─ Quality Gate ────────────────────┘
├─ §6 Auto-Capture                     │
└─ Learning Loop                       │
```

---

> **Integrity Check:** This document is version-locked. Any amendment to the state machine or transition rules requires updating the mermaid diagram and transition table simultaneously.