89088414/16gagent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
16gagent/GOVERNANCE.md
T
大海 a188ee1426 🎉 init: 小龙的工作空间
2026-06-06 10:40:48 +08:00

12 KiB
Raw Permalink 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，必须同时：

  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

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.

Reference in New Issue View Git Blame Copy Permalink