OpenClaw Workspace Governance

🚨【高危预警 / IMPORTANT WARNING】这不是工具Skill，而是系统级架构升级！部署前务必备份工作区！This is NOT a standard tool skill, but a system-level architecture upgrade! Backup workspace before deployment! 虾滑 OpenClaw 工作区治理：用于治理和升级复杂 OpenClaw 工作区，覆盖多 Agent 治理、权威事实分层、查询分类路由、语义搜索诊断、工作集保鲜与维护收口。

# 虾滑 OpenClaw 工作区治理（OpenClaw Workspace Governance）

> 🚨 **高危/重要提示 (IMPORTANT WARNING)** 🚨
> **这不是一个普通的工具型 Skill，而是针对 OpenClaw 工作区的系统级架构升级与治理方案。**
> **在让你的 Agent 实施本指南之前，请务必对你的 Workspace 进行完整备份，并确保你理解其对文件状态和检索优先级的改变。请勿在未做快照的生产环境中盲目运行全自动治理！**
> 
> ***This is NOT a standard tool-level skill. It is a system-level architecture upgrade and governance framework for your OpenClaw workspace.***
> ***Before allowing your Agent to implement these guidelines, you MUST take a full backup of your workspace. Do not run automated governance in a production environment without understanding how it alters document states and retrieval routing.***

这是一个面向**复杂 OpenClaw 工作区**的治理型 skill。它不是为了制造更多流程，而是为了在复杂度已经上来之后，帮你压住漂移、明确当前事实层、缩小 live docs 面积，并让语义检索变得更可控。

### 系统能力详解 (System Capabilities)

本 Skill 提供了一套完整的系统级框架，赋予你的 OpenClaw 以下核心能力：
- **多 Agent 协作架构 (Multi-Agent Architecture)**：建立以 Supervisor 为中心的调度机制，实现“写审分离”。明确区分代码编写、代码审查、规则审核、文档撰写等专职岗位，防止单一 Agent 越权闭环。
- **分层记忆系统 (Layered Memory System)**：告别无序的长文档堆砌。建立从“原始日志 (Daily Notes)”到“主题卡片 (Topic Cards)”，再到“长期记忆 (Long-Term Memory)”的逐层蒸馏与质量门控机制。
- **语义检索与路由 (Semantic Retrieval Routing)**：将系统查询分类（如：状态查询、规则边界、历史溯源等），并建立基于桥接文件 (Bridge Files)、结构化记忆与 qmd 语义搜索的精准召回优先级。
- **审批与安全治理 (Approval & Governance)**：强制核心文件（如 AGENTS.md）的修改必须经过独立评审与人工授权；内置针对特定岗位的“防偷懒协议（代码交付契约）”，保障自动化任务的执行完整性。


## 适用场景

当你的工作区已经出现真实复杂度时，再用这份 skill。典型信号包括：
- 多个 Agent 或多角色执行路径已经出现
- 文档、记忆、状态层越来越多
- 回答“现在到底什么是真的”开始变难
- semantic search（语义搜索）有用，但不再能无脑相信
- live docs 过多、working set 不清、维护开始失控

⚠️ 这是进阶 skill，不是新手入门包，也不是 v1 的全自动 orchestrator。

## 非目标

这份 skill **不会**替你自动拍板、自动改规则，也不会把所有旧文档都继续维持成“活文档”。它提供的是治理 playbook，不是无限自动化引擎。

它不试图做这些事：
- 发布私有角色 lore 或内部组织文化
- 打包个人记忆、日记或私有运行历史
- 自动决定审批结果
- 自动改政策或规则
- 在 v1 里做全自动多 Agent 编排
- 因为“怕以后要用”而让所有旧文档都保持 live

## 快速开始

先别急着改文件，先判清楚你遇到的是哪一种 drift。主线只有六步：
1. 分类问题
2. 选择治理路径
3. 找到应该回答问题的权威事实层
4. 收紧文档角色和 freshness 边界
5. 用代表性问题验证
6. 在主线足够完整时主动收口

如果工作区现在很乱，先减少歧义，不要先加流程。

## 核心工作流

### 1. 先分类问题

先判断你面对的是哪一类 drift，不要一上来就盲改文件。先分清类型，后面所有动作才不会跑偏。

你通常会遇到这些类型：
- governance drift：角色、审批、审查边界或规则正在漂
- current-state drift：现在到底什么是真的变得不清楚
- retrieval drift：semantic search、bridge files、topic cards、long-term memory 开始互相打架
- doc drift：旧文档还在假装自己代表当前事实
- maintenance drift：live docs 太多，没有 working set，也没人做 freshness checks
- phase drift：系统不停产出流程文档，却没有收口

不要先改文件，先判类型。

### 2. 让不同变更走对治理路径

实现改动、文档解释改动、治理/规则改动，不是一回事。复杂工作区里，最怕把所有改动都走同一条线。

把工作类型区分清楚：
- implementation change：普通实现或落地改动
- documentation/explanation change：文档措辞、状态标签、说明层改动
- governance/policy/process change：角色边界、审批规则、路由规则、维护规则改动

可使用这些通用角色：
- **Coordinator**：定义问题、选路径、负责收口
- **Implementer**：执行文件/脚本/操作改动
- **Reviewer**：检查实现质量，揪明显问题
- **Policy Auditor**：审治理、流程、规则变化
- **Consensus Peer**：高风险结构变更前的可选同级会审

常见部署形态：
- **2-agent**：Coordinator+Implementer / Reviewer
- **3-agent**：Coordinator / Implementer / Reviewer
- **4-5-agent**：额外加入 Policy Auditor 和可选 Consensus Peer

基本规则：
- 高风险工作里，不要让同一角色既实现又做最终审查
- 治理/政策/流程改动要过 Policy Auditor
- 高风险结构改动前，如果单一规划者判断不够，插入 consensus-peer 会审
- 如果工作区里只有 1 个 agent，要明确写出“本来这里该有第二审”，不要假装自审等价

按需阅读：
- `references/multi-agent-governance.md`

v1 边界：
- 这份 skill 提供可部署的治理指导
- 它**不是** v1 的全自动多 Agent 编排系统

### 3. 建立权威事实分层

不要把所有资料平均对待。真正的关键不是“资料多不多”，而是**冲突时谁说了算**。

把这些层分清楚：
- **canon**：规则、审批、硬边界
- **bridge/current-state**：回答“现在什么是真的”的短文件
- **health/consistency**：运行健康和一致性状态
- **runtime snapshot**：某一时点的运行事实
- **structured memory**：中等持久度的 topic/index 卡片
- **long-term memory**：只保留高持久事实
- **historical docs**：背景、旧阶段、旧计划、审计、报告

两层冲突时，不要平均；必须决定谁赢。

按需阅读：
- `references/source-of-truth-layering.md`
- `references/query-class-routing.md`

### 4. 先分 query class，再决定检索顺序

别抽象地问“语义搜索靠不靠谱”。真正该问的是：对哪一类问题靠谱？在什么 runtime / cache 对齐状态下靠谱？它是主裁决层还是辅助召回层？

建议的 query class：
- system-state
- governance / rule-boundary
- runtime-now
- weekly-review / approval-state
- user-preference / profile
- historical trace / evidence
- maintenance / upkeep

默认策略：
- governance → canon first
- system-state → bridge/health first
- runtime-now → snapshot first
- user-preference → curated profile/manual sources first
- historical trace → discovery + verification
- semantic search → 除非明确验证更强，否则只作为 supporting layer

按需阅读：
- `references/query-class-routing.md`
- `references/semantic-search-diagnostics.md`

### 5. 给文档打角色边界

旧文档最危险的不是存在，而是它还在假装自己代表 current truth。把 live docs 面积压小，系统才会稳。

常见标签与角色：
- `historical-reference`
- `needs-refresh`
- active/live maintenance docs
- special-case active safety restriction

尽量定义一个**最小 live subset**，其他默认降级成次级参考层。

按需阅读：
- `references/live-vs-historical-docs.md`

### 6. 建 working set 和 freshness checks

working set 不是“所有重要文件”，而是“必须持续保鲜的最小活跃集合”。不要用一个统一阈值去管所有文档。

典型 working set 包括：
- health / consistency 文件
- bridge/current-state 文件
- runtime snapshot
- entrypoint/index docs
- 只有最高价值的 topic cards

用分组阈值，不要用一个笼统阈值：
- health/bridge/runtime/entry docs 用更短阈值
- structured topic/index docs 用更长阈值

用 freshness checker 把“谁应该记得更新一下”变成可重复执行的检查。

按需阅读：
- `references/freshness-discipline.md`

### 7. 认真诊断 semantic-search runtime

语义检索出问题时，最常见的坑不是模型不行，而是 path alignment、cache/index 混线，或者 split-brain（诊断一个索引、查询另一个索引）。

诊断时建议按这条线走：
1. 先记录 before-state baseline
2. 确认 runtime config 与 cache/index context 是否对齐
3. 检查是否存在 split-brain
4. 修掉明显的 indexing/embedding 缺口
5. 用少量代表性 query classes 回归验证
6. 不要给 blanket trust label，要按 query class 标可信度

按需阅读：
- `references/semantic-search-diagnostics.md`

### 8. 用代表性问题验证，而不是只看结构

结构看起来整齐，不等于系统真的能回答问题。至少拿 system-state、governance、maintenance、historical/preference 这几类真实问题测一轮。

最低验证集：
- 一个 system-state 问题
- 一个 governance 问题
- 一个 maintenance 问题
- 一个 historical 或 preference 问题

判定结果建议只用三种：
- PASS
- PASS WITH ESCALATION
- FAIL

只有当较小的 live subset 也确实能回答日常问题时，才算成立。

### 9. 主动收尾，不要无限扩相

如果一个 phase 已经主线落地，就该收口进 maintenance observation（维护观察期），而不是继续生产更多流程文档。

每个 phase 都要明确：
- 什么是 **landed**
- 什么是 **improving**
- 什么是 **deferred**
- 主线是否已经足够完整，可以关闭

一旦主线够完整：
- 转入 maintenance observation
- 保持 live subset 尽量小
- 做小修，不要再开一轮 sprawling phase

按需阅读：
- `references/completion-criteria.md`

## v1 推荐脚本

这些脚本覆盖 v1 最关键的三条治理检查线：freshness、semantic runtime、doc status。

- `scripts/freshness-check.py`
- `scripts/semantic-runtime-check.sh`
- `scripts/doc-status-scan.py`

## v1 推荐参考文档

这些 references 构成 v1 的主参考集；它们负责解释治理原则，不负责替你自动执行一切。

- `references/multi-agent-governance.md`
- `references/source-of-truth-layering.md`
- `references/query-class-routing.md`
- `references/live-vs-historical-docs.md`
- `references/freshness-discipline.md`
- `references/semantic-search-diagnostics.md`
- `references/completion-criteria.md`

## v1 推荐示例

先用这些示例建 working set、system-state index 和 health 示例，再按你的工作区实际情况收窄。

- `assets/examples/working-set.example.md`
- `assets/examples/working-set.example.json`
- `assets/examples/current-health.example.json`
- `assets/examples/system-state-index.example.md`

## v1 叙事要收紧

这是一份 workspace governance tool / governance playbook。它包含多 Agent 治理指导，但它不是 roleplay 包，也不是 v1 的全自动 multi-agent orchestrator。

它最核心的承诺只有五条：
- 减少 drift
- 让 current truth 更容易识别
- 把 live docs 面积压小
- 让 semantic retrieval 更可控
- 让维护更可持续

## 发布与草案边界

当前正式发布内容以本目录下的 package-local 文件为准。旧的 `docs/skill-draft-*` 文件属于设计历史，不应继续和当前发布包竞争解释权。

---

> This is a governance skill for **complex OpenClaw workspaces**. It is not here to add process for its own sake. It helps you reduce drift, clarify current truth, shrink the live-doc surface, and make semantic retrieval more controllable.
> 
> ### System Capabilities
> 
> This skill provides a complete system-level framework, empowering your OpenClaw with the following core capabilities:
> - **Multi-Agent Architecture**: Establishes a Supervisor-centric dispatch mechanism, ensuring "separation of writing and reviewing". It clearly separates roles like code generation, code review, policy auditing, and documentation, preventing any single agent from making unauthorized closed-loop decisions.
> - **Layered Memory System**: Moves away from chaotic long documents. It builds a progressive distillation and quality-gating mechanism from "Raw Daily Notes" to "Topic Cards" and finally to "Long-Term Memory".
> - **Semantic