# CHANGELOG.md — Protocol Stack V2

> All notable changes to the three-layer agent protocol architecture.

---

## [2.0.0] — 2026-06-06

### Added

- **GOVERNANCE.md** — Full Execution Governance Protocol (§0–11)
  - 8-state state machine with transition rules and mermaid diagram
  - Heartbeat/stale detection rules with Small/Medium/Large thresholds
  - Blocker management with escalation mechanism
  - Replanning trigger (R1–R8 conditions)
  - Scope explosion detector (S1–S4)
  - Execution audit schema
  - Project Health Score (5 dimensions + weighted formula + rating)
  - Auto-Stop Rule with RECOVERY MODE
  - Governance Quality Gate (8-item checklist)
  - State initialization and override protocols

- **PORTFOLIO.md** — Full Portfolio Management Protocol (§1–14)
  - Portfolio registry schema (9 fields: ID/Name/Status/Priority/Health/Agents/Progress/Updated/ROI)
  - 7-state project lifecycle (PLANNING→ACTIVE→...→ARCHIVED)
  - Priority system (P0 Mission Critical → P3 Low Priority)
  - Resource allocation with Agent Utilization Score
  - Project Health Aggregation (5 dimensions + Execution/Risk)
  - Portfolio Health Score (weighted by Agent count)
  - Learning Reuse Detector with duplicate work criteria
  - Portfolio Audit with daily generation
  - Kill / Pause / Promotion rules
  - Executive Dashboard schema
  - Portfolio Quality Gate

- **protocol-reference/** — Extracted reference directory
  - `quality-gates.md` — 3 gates consolidated in one file
  - `metrics.md` — All score formulas and rating tables
  - `templates.md` — All example templates extracted from main docs

- **Scripts**
  - `scripts/audit-agents.mjs` — 24 checks for AGENTS.md
  - `scripts/audit-governance.mjs` — 34 checks for GOVERNANCE.md
  - `scripts/audit-portfolio.mjs` — 33 checks for PORTFOLIO.md
  - `scripts/audit-all.mjs` — 91-check orchestrator + audit-report.md generator
  - `scripts/upgrade-test.mjs` — 62-check OpenClaw upgrade compatibility suite
  - `npm run audit` / `npm run upgrade` package.json entries

- **Governance artifacts**
  - `COMPATIBILITY-STRATEGY.md` — OpenClaw integration surface audit + risk matrix
  - `version-contract.md` — Required/Forbidden interfaces contract
  - `upgrade-playbook.md` — Migration strategy (minor/major/deprecation)
  - `SYSTEM-AUDIT.md` — Protocol simplification audit with metrics
  - `PROJECT-COMPLETION-REPORT.md` — Project completion template

### Changed

- **AGENTS.md**
  - §6 Governance Compliance: ~50 lines → 3-line references to GOVERNANCE.md
  - Removed non-protocol sections: Memory, Red Lines, External vs Internal, Group Chats, Security Baseline, Heartbeats
  - §7 Auto-Capture: renumbered from §6 (after new §6 inserted)
  - Cross-refs added to PORTFOLIO.md in §6e

- **GOVERNANCE.md**
  - §12 Portfolio Integration: deleted (covered by PORTFOLIO.md)
  - §3.2 Blocker Schema: migrated to protocol-reference/templates.md
  - §4.3 Replan Log Entry: migrated to protocol-reference/templates.md
  - §6.2 Audit Schema: migrated to protocol-reference/templates.md
  - §7.3 Rating: migrated to protocol-reference/metrics.md
  - §9.1 Quality Gate checklist: migrated to protocol-reference/quality-gates.md

- **PORTFOLIO.md**
  - §8.2 Audit Schema: migrated to protocol-reference/templates.md
  - §12.2 Dashboard Schema: migrated to protocol-reference/templates.md
  - §13.1 Quality Gate checklist: migrated to protocol-reference/quality-gates.md
  - Self-ref comment tags cleaned

- **MEMORY.md** — Added Governance Protocol and Portfolio Protocol entries

- **Package.json** — Added `audit`, `audit:*`, `upgrade` npm scripts

### Removed

- AGENTS.md: 6 non-protocol sections removed
- GOVERNANCE.md: §12 Portfolio Integration removed
- Inline template code blocks replaced with references to protocol-reference/

### Fixed

- AGENTS.md section numbering collision (§6 Governance vs old §6 Auto-Capture → renumbered §7)
- upgrade-test.mjs: false-positive `DD.md` cross-ref detection

### Secured

- Zero OpenClaw internal API dependencies in audit scripts
- All audit scripts are pure Node.js (fs/path)
- Protocol files are pure Markdown (no runtime deps)
- 62/62 upgrade compatibility tests (verified on v2026.5.28 → v2026.6.1)
- Self-hosting readiness: 80/100

## Volume History

| Version | Date | Total Bytes | Audit PASS | Audit FAIL |
|---------|------|-------------|------------|------------|
| V0 (bootstrap) | 2026-06-05 | ~56KB | — | — |
| V1 (initial) | 2026-06-06 | 56,002 | 78 | 0 |
| **V2 (freeze)** | **2026-06-06** | **44,136 (−21%)** | **78** | **0** |