Files

T

2026-06-06 10:40:48 +08:00

12 KiB

Raw Blame History

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.

§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

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，每行一条记录）:

{"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，必须同时：

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

§3.4 Blocker Resolution

在 blocker 解除时：

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

§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

暂停所有相关的 Agent Package（状态 → BLOCKED）
分析失败原因 — 是否系统性？是否需要调整 Task Tree？
输出修订后的 Task Tree 和 PLAN
记录 replan evidence 到 execution-audit.md
恢复执行（状态 → 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 后必须：

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

§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 后：

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

每个新项目启动时：

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

§10.2 Agent Package Handoff

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

最后写入一条心跳（status: ARCHIVED）
更新 execution-audit.md 中的 Task Status Matrix
触发依赖等待的 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

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.

12 KiB Raw Blame History Unescape Escape