# Architecture Freeze — OpenClaw Agent OS v2

> **Frozen:** 2026-06-06
> **Freeze Commit:** `96b816c` (Slimmed Three-Layer Architecture)
> **Authority:** PR-1 Freeze Architecture → V2 Protocol Stack
> **Audit Verdict:** 78/91 PASS, 0 FAIL (WARN: 13, all expected — no active projects)
>
> 本文档是 OpenClaw Agent OS v2 架构的权威冻结声明。
> 当前活跃架构版本见 `VERSION.md`，完整协议见 `AGENTS.md` / `GOVERNANCE.md` / `PORTFOLIO.md`。

---

## 1. Architecture Layers

```
┌─────────────────────────────────────────────┐
│   CORE (AGENTS.md)                          │
│   Execution Protocol                      │
│   §0 Complexity → §7 Auto-Capture          │
│   + Learning Loop + Context Budget          │
├─────────────────────────────────────────────┤
│   GOVERNANCE (GOVERNANCE.md)                │
│   Execution Governance                    │
│   §0 Purpose → §11 Integration Summary      │
│   7-state machine, heartbeat, blocker,      │
│   replan, scope detection, health score,    │
│   auto-stop, recovery, quality gate         │
├─────────────────────────────────────────────┤
│   PORTFOLIO (PORTFOLIO.md)                  │
│   Portfolio Management                    │
│   §0 Purpose → §14 Integration Summary      │
│   Registry, project states, priority,       │
│   resource allocation, health aggregation,  │
│   learning reuse detector, kill/pause/promo,│
│   executive dashboard, quality gate         │
├─────────────────────────────────────────────┤
│   ADAPTER                                   │
│   protocol-reference/ + Factory Layer      │
│   quality-gates.md / metrics.md / templates.md│
├─────────────────────────────────────────────┤
│   EXPERIMENTAL                              │
│   (Reserved for future capability)          │
├─────────────────────────────────────────────┤
│   LEGACY (memory-wiki)                      │
│   Deprecated, migration window to 2026-09-04│
│   — tools still available                   │
└─────────────────────────────────────────────┘
```

### Core Module

AGENTS.md + GOVERNANCE.md + PORTFOLIO.md 构成三层协议栈核心。
不可移除的最小模块集合。

### Adapter Module

protocol-reference/（共享规格）和 Factory Layer（全栈工厂）。
可选加载，不影响协议栈最小可用状态。

### Legacy Module

memory-wiki plugin。已标记废弃，90 天迁移窗口。

### Experimental Module

预留。未来新模块在此区域试点，API 可能变更。
不纳入 guard 强制检查。

---

## 2. Core Module Inventory

| # | Module | Contracts | Description |
|---|--------|-----------|-------------|
| 1 | AGENTS.md | Execution Protocol (§0–7, LL, CB) | 任务理解→拆解→规划→执行协议 |
| 2 | GOVERNANCE.md | Execution Governance (§0–11) | 状态机、心跳、blocker、replan、审计、健康评分 |
| 3 | PORTFOLIO.md | Portfolio Management (§1–14) | 项目注册表、状态、优先级、资源、健康聚合 |
| 4 | protocol-reference/ | quality-gates, metrics, templates | 三协议共享的规格定义 |
| 5 | audit-agents.mjs | AGENTS.md 合规检查 (32 项) | Execution Protocol 自动化审计 |
| 6 | audit-governance.mjs | GOVERNANCE.md 合规检查 (35 项) | Governance 自动化审计 |
| 7 | audit-portfolio.mjs | PORTFOLIO.md 合规检查 (24 项) | Portfolio 自动化审计 |
| 8 | upgrade-test.mjs | 升级兼容性 (62 项) | OpenClaw 升级兼容性测试 |

## 3. Adapter Module Inventory

Workspace 工厂层（非协议核心，可独立演进）：

| Layer | Module | Description |
|-------|--------|-------------|
| Factory | SF-01 → SF-06 | 全栈软件产品工厂（策略→需求→架构→代码→测试→交付） |
| Factory | model-contract.mjs | 字段定义层（3 builder agents 共享） |
| Factory | fullstack-composer-agent.mjs | 全栈组合器 |
| Factory | frontend-builder-agent.mjs | Next.js 前端生成 |
| Factory | backend-builder-agent.mjs | Fastify 后端生成 |

## 4. Legacy Module Inventory

| Module | Deprecation Date | Migration Window | Removal Target |
|--------|-----------------|-----------------|----------------|
| memory-wiki plugin | 2026-06-04 | 90 days | 2026-09-04 |

## 5. Migration Policy

- 90-day migration window from freeze date
- Day 0 (2026-06-06): Legacy warnings active
- Day 30 (2026-07-06): Standard warnings
- Day 60 (2026-08-06): Honcho/LanceDB read-only cutoff
- Day 90 (2026-09-06): All legacy modules removed

## 6. Freeze Rules

1. **Core module count**: 8 (must not exceed 8)
2. **No XL Agent Package** (>200K tokens) — forbidden by AGENTS.md Context Budget
3. **All protocol changes** require **Governance Quality Gate** (GOVERNANCE.md §9)
4. **All architecture changes** require **this document update** + **full audit pass**

## 7. Guard Verification

| Guard | Script | Status |
|-------|--------|--------|
| AGENTS.md Compliance | `node scripts/audit-agents.mjs` | ✅ 32 checks |
| GOVERNANCE.md Compliance | `node scripts/audit-governance.mjs` | ✅ 35 checks |
| PORTFOLIO.md Compliance | `node scripts/audit-portfolio.mjs` | ✅ 24 checks |
| Full Audit | `node scripts/audit-all.mjs` | ✅ 91 checks (78 PASS, 13 WARN, 0 FAIL) |
| Upgrade Compat | `node scripts/upgrade-test.mjs` | ✅ 62/62 PASS |