docs(migration): finalize phase docs, validation, and rollback pack

2026-03-10 17:39:16 +08:00
parent eaa8058eb5
commit 2567ce4eda
12 changed files with 196 additions and 3 deletions
--- a/tasks/openclawd-migration-2026-03/EXECUTION-PROMPT-SHORT.md
+++ b/tasks/openclawd-migration-2026-03/EXECUTION-PROMPT-SHORT.md
@@ -0,0 +1,17 @@
+# Execution Prompt (Short)
+
+执行目标：将 OpenClaw 记忆体系收敛为双层架构：`vaults` 仅 runtime，`collective-memory-repo` 仅 durable memory authority。
+
+硬性要求：
+- 不破坏 OpenClaw 启动流程。
+- 不迁移 `SOUL.md/USER.md/IDENTITY.md/AGENTS.md/TOOLS.md/HEARTBEAT.md` 到共享长期记忆。
+- 长期事实以 `collective-memory-repo/shared/long-term/*` 为准。
+- 群体检索以远程 `memory-gateway` 为准（`require_latest=true`）。
+
+执行步骤：
+1. 盘点并输出 `INVENTORY.md` 与 `GAP-ANALYSIS.md`。
+2. 固化架构边界与映射，更新 `TARGET-ARCHITECTURE.md`、`MIGRATION-MAP.md`。
+3. 迁移/去重/标注来源，按 lane 写入 `daily/ tasks/ agents/ shared/long-term/`。
+4. 将 `vaults/MEMORY.md` 降级为 bridge/index。
+5. 验证 `/health`、`/memory/status`、`/memory/search`，输出 `VALIDATION.md` 与 `RETRIEVAL-TESTS.md`。
+6. 输出 `FINAL-STATE.md`、`ROLLBACK.md`，并提交 git。
--- a/tasks/openclawd-migration-2026-03/FINAL-STATE.md
+++ b/tasks/openclawd-migration-2026-03/FINAL-STATE.md
@@ -0,0 +1,16 @@
+# FINAL STATE
+
+## What changed
+- Memory authority consolidated into collective-memory-repo lanes.
+- Remote memory-gateway validated for authoritative retrieval on `main`.
+- OpenClaw local config switched to search collective lanes.
+- `vaults/MEMORY.md` converted to runtime bridge/index.
+- `vaults/AGENTS.md` read/write rules updated to prioritize collective lanes.
+- `vaults/memory/README.md` converted to compatibility-zone policy.
+
+## What did not change
+- OpenClaw runtime home remains `/Users/lingyuzeng/openclawd/vaults`.
+- Runtime files (persona/identity/tools/heartbeat) stay local.
+
+## Remaining work
+- Add automated policy checks to reduce dual-write risk.
--- a/tasks/openclawd-migration-2026-03/GAP-ANALYSIS.md
+++ b/tasks/openclawd-migration-2026-03/GAP-ANALYSIS.md
@@ -0,0 +1,16 @@
+# GAP ANALYSIS
+
+## Resolved
+- Durable memory lanes are established in collective-memory-repo.
+- Remote memory-gateway is healthy and can return indexed-visible results on `main`.
+- OpenClaw QMD paths have been redirected from vault folders to collective lanes.
+- `vaults/MEMORY.md` has been downgraded to bridge/index role.
+- `vaults/memory/README.md` now marks `vaults/memory/*` as compatibility-only.
+
+## Remaining Gaps
+- `vaults/memory/*.md` still exists and can cause dual-source writing if process discipline is not applied.
+- Write policy enforcement is doc-level; no hard guardrails yet (hooks/checks not implemented).
+
+## Risk Level
+- Medium if users continue dual-write into both vaults and collective.
+- Low for retrieval correctness when queries go through remote memory-gateway with `require_latest=true`.
--- a/tasks/openclawd-migration-2026-03/INVENTORY.md
+++ b/tasks/openclawd-migration-2026-03/INVENTORY.md
@@ -0,0 +1,21 @@
+# INVENTORY
+
+## Runtime Layer (vaults)
+- Path: `/Users/lingyuzeng/openclawd/vaults`
+- Core runtime files: `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, `TOOLS.md`, `HEARTBEAT.md`
+- Compatibility memory files: `MEMORY.md`, `memory/*.md`
+
+## Durable Memory Layer (collective)
+- Path: `/Users/lingyuzeng/project/collective-memory-repo`
+- Lanes: `daily/`, `tasks/`, `agents/`, `shared/long-term/`, `policies/`
+- Imported artifacts already present:
+  - `shared/long-term/decisions/openclawd-infra-baseline.md`
+  - `shared/long-term/projects/openclawd-memory-index.md`
+  - `shared/long-term/projects/openclawd-project-status.md`
+  - `shared/long-term/lessons/openclawd-ops-lessons.md`
+
+## OpenClaw Config Snapshot
+- File: `/Users/lingyuzeng/.openclaw/openclaw.json`
+- `memory.backend = qmd`
+- `memory.qmd.command = /opt/homebrew/bin/qmd` (local binary)
+- `memory.qmd.paths` now point to collective-memory-repo lanes.
--- a/tasks/openclawd-migration-2026-03/MIGRATION-MAP.md
+++ b/tasks/openclawd-migration-2026-03/MIGRATION-MAP.md
@@ -0,0 +1,11 @@
+# MIGRATION MAP
+
+| Source (vaults) | Target (collective) | Status |
+|---|---|---|
+| `MEMORY.md` | `shared/long-term/projects/openclawd-memory-index.md` | done |
+| `memory/infra.md` | `shared/long-term/decisions/openclawd-infra-baseline.md` | done |
+| `memory/projects.md` | `shared/long-term/projects/openclawd-project-status.md` | done |
+| `memory/lessons.md` | `shared/long-term/lessons/openclawd-ops-lessons.md` | done |
+| `memory/YYYY-MM-DD*.md` | `daily/YYYY-MM-DD.md` | done (merged by date) |
+| `shared/10-Team/**` | `tasks/openclawd-team-archive/10-Team/**` | done |
+| `mac-5/00-Inbox/**` | `tasks/openclawd-legacy-inbox/mac-5-00-Inbox/**` | done |
--- a/tasks/openclawd-migration-2026-03/READ-RULES.md
+++ b/tasks/openclawd-migration-2026-03/READ-RULES.md
@@ -0,0 +1,13 @@
+# READ RULES
+
+## Session Boot Read
+- Read from vault runtime files:
+  - `SOUL.md`, `USER.md`, `AGENTS.md`, `HEARTBEAT.md`
+
+## Memory Fact Read
+- Prefer remote memory-gateway query (`require_latest=true`).
+- Use `branch=main` for long-term facts.
+- Use `branch=task/<task-id>` for active collaboration context.
+
+## Fallback Read
+- Local qmd search on collective lanes is allowed for draft/debug fallback.
--- a/tasks/openclawd-migration-2026-03/RETRIEVAL-TESTS.md
+++ b/tasks/openclawd-migration-2026-03/RETRIEVAL-TESTS.md
@@ -0,0 +1,18 @@
+# RETRIEVAL TESTS
+
+## Test 1
+- Query: `OpenClaw 集群架构`
+- Branch: `main`
+- Expect: hit `shared/long-term/projects/openclawd-memory-index.md`
+- Result: pass
+
+## Test 2
+- Query: `mac-8`
+- Branch: `main`
+- Expect: retired/offline context in long-term files
+- Result: pass
+
+## Test 3
+- Query mode: `require_latest=true`
+- Expect: authoritative result from indexed latest commit
+- Result: pass
--- a/tasks/openclawd-migration-2026-03/ROLLBACK.md
+++ b/tasks/openclawd-migration-2026-03/ROLLBACK.md
@@ -0,0 +1,12 @@
+# ROLLBACK
+
+## If OpenClaw memory retrieval regresses
+1. Restore config backup:
+   - `cp ~/.openclaw/openclaw.json.bak-20260310-1723 ~/.openclaw/openclaw.json`
+2. Restart OpenClaw process/session.
+3. Re-run smoke checks on local memory retrieval.
+
+## If gateway retrieval regresses
+1. Check remote compose path and service health (`qmd`, `memory-gateway`).
+2. Run `POST /memory/status` with `require_latest=true`.
+3. Ensure target commit is pushed and index state returns `indexed-visible`.
--- a/tasks/openclawd-migration-2026-03/TARGET-ARCHITECTURE.md
+++ b/tasks/openclawd-migration-2026-03/TARGET-ARCHITECTURE.md
@@ -0,0 +1,18 @@
+# TARGET ARCHITECTURE
+
+## Layer A: Runtime (OpenClaw local)
+- Root: `/Users/lingyuzeng/openclawd/vaults`
+- Responsibility: session boot, persona, local operational control.
+- Authoritative for runtime behavior only.
+
+## Layer B: Durable Memory Authority
+- Root: `/Users/lingyuzeng/project/collective-memory-repo`
+- Responsibility: long-term/shared/task/agent memory.
+- Authoritative for memory facts.
+
+## Retrieval Chain
+- Preferred: `Agent -> memory-gateway (RTX) -> qmd -> git-backed workspace`
+- Fallback: local qmd on collective repo paths.
+
+## Authority Rule
+- Shared truth requires pushed and indexed state on remote gateway.
--- a/tasks/openclawd-migration-2026-03/TASK.md
+++ b/tasks/openclawd-migration-2026-03/TASK.md
@@ -1,9 +1,29 @@
 # TASK: openclawd-migration-2026-03

 ## Goal
- Migrate openclawd memory into collective-memory-repo and switch group retrieval to memory-gateway.
+- Migrate OpenClaw memory into collective-memory-repo and switch group retrieval to memory-gateway authority.

 ## Scope
 - Import long-term, daily, and legacy team memory.
- Preserve openclawd runtime files in local vaults.
- Validate gateway consistency chain (/health, /sync, /query).
+- Preserve OpenClaw runtime files in local vaults.
+- Validate gateway consistency chain (`/health`, `/memory/status`, `/memory/search`).
+
+## Phases
+- Phase 0 Inventory: complete
+- Phase 1 Target Architecture: complete
+- Phase 2 Content Migration: complete
+- Phase 3 Compatibility Layer: complete
+- Phase 4 Validation: complete
+- Phase 5 Finalization: complete
+
+## Deliverables
+- `INVENTORY.md`
+- `GAP-ANALYSIS.md`
+- `TARGET-ARCHITECTURE.md`
+- `MIGRATION-MAP.md`
+- `WRITE-RULES.md`
+- `READ-RULES.md`
+- `VALIDATION.md`
+- `RETRIEVAL-TESTS.md`
+- `FINAL-STATE.md`
+- `ROLLBACK.md`
--- a/tasks/openclawd-migration-2026-03/VALIDATION.md
+++ b/tasks/openclawd-migration-2026-03/VALIDATION.md
@@ -0,0 +1,16 @@
+# VALIDATION
+
+## Structural
+- Verified collective repo has lanes: `daily/`, `tasks/`, `agents/`, `shared/long-term/`.
+- Verified agent folders exist for `openclaw-main`, `claude-code`, `codex`.
+
+## Config
+- Verified `/Users/lingyuzeng/.openclaw/openclaw.json` uses `memory.backend=qmd`.
+- Verified `memory.qmd.paths` target collective lanes, not `vaults/*` memory lanes.
+- Verified `vaults/MEMORY.md` is bridge/index only.
+- Verified `vaults/memory/README.md` marks `vaults/memory/*` as compatibility zone.
+
+## Gateway
+- `GET /health` => `ok:true`
+- `POST /memory/status` (`branch=main`, `require_latest=true`) => `indexed-visible`
+- `indexed_commit_hash == remote_head_commit_hash == eaa8058eb55dc1813cdaf4268ec061743a88d784`
--- a/tasks/openclawd-migration-2026-03/WRITE-RULES.md
+++ b/tasks/openclawd-migration-2026-03/WRITE-RULES.md
@@ -0,0 +1,15 @@
+# WRITE RULES
+
+## Write to vaults
+- Only runtime files and local control context:
+  - `SOUL.md`, `USER.md`, `IDENTITY.md`, `AGENTS.md`, `TOOLS.md`, `HEARTBEAT.md`
+- `MEMORY.md` in vaults should remain bridge/index only.
+
+## Write to collective-memory-repo
+- Daily observations: `daily/YYYY-MM-DD.md`
+- Agent private working memory: `agents/openclaw-main/current.md`, `agents/openclaw-main/inbox.md`
+- Task collaboration: `tasks/<task-id>/`
+- Stable facts: `shared/long-term/{decisions,projects,lessons}/`
+
+## Promote Rule
+- Promote from `daily/` or `tasks/` into `shared/long-term/` only after review.