zclaw_openfang/docs/wiki-restructure/implementation-plan.md

# Wiki Restructure Implementation Plan

> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Restructure ZCLAW wiki from inconsistent module pages to a unified 5-section template with symptom navigation, integration contracts, and size budgets.

**Architecture:** 6-phase migration following dependency order: archive/cap → middleware (single source) → dependents → remaining modules → index → feature-map. One module per commit for safe rollback.

**Spec:** `docs/wiki-restructure/design-spec.md`

---

## Chunk 1: Phase A — Archive & Cap (no dependencies)

### Task 1: Archive log.md old entries

**Files:**
- Create: `wiki/archive/log-2026-04-pre.md`
- Modify: `wiki/log.md`

- [ ] **Step 1: Count entries and identify cutoff**

Run: `grep -c '^\[' wiki/log.md`
Expected: ~100+ entries

- [ ] **Step 2: Create archive file with entries beyond the most recent 50**

Open `wiki/log.md`, identify the first 50 entries (newest first), move everything after line ~250 (the 50th entry boundary) to `wiki/archive/log-2026-04-pre.md`. Keep the frontmatter and header in both files.

- [ ] **Step 3: Verify log.md has ≤ 50 entries**

Run: `grep -c '^\[' wiki/log.md`
Expected: ≤ 50

- [ ] **Step 4: Commit**

```bash
git add wiki/log.md wiki/archive/log-2026-04-pre.md
git commit -m "docs(wiki): 归档 log.md 旧条目 — 保留最近50条"
```

### Task 2: Archive hermes-analysis.md

**Files:**
- Move: `wiki/hermes-analysis.md` → `wiki/archive/hermes-analysis.md`

- [ ] **Step 1: Move file to archive**

```bash
mv wiki/hermes-analysis.md wiki/archive/hermes-analysis.md
```

- [ ] **Step 2: Commit**

```bash
git add wiki/hermes-analysis.md wiki/archive/hermes-analysis.md
git commit -m "docs(wiki): 归档 hermes-analysis.md — 洞察已在 memory.md"
```

### Task 3: Convert known-issues.md to pointer

**Files:**
- Create: `wiki/archive/known-issues-full-2026-04-22.md`
- Modify: `wiki/known-issues.md`

- [ ] **Step 1: Archive full content**

```bash
cp wiki/known-issues.md wiki/archive/known-issues-full-2026-04-22.md
```

- [ ] **Step 2: Extract active issues per module for later use**

Read `wiki/known-issues.md`, note all currently OPEN issues and which module they belong to. Use these when writing Task 5-13 module pages.

- [ ] **Step 3: Rewrite known-issues.md as pointer index**

Replace with:
```markdown
---
title: 已知问题索引
updated: 2026-04-22
status: active
---

# 已知问题索引

> 活跃问题已迁移至各模块页面的"活跃问题+陷阱"章节。本文件仅作索引。

## 活跃问题

| 模块 | 问题数 | 详见 |
|------|--------|------|
| chat | 1 | [[chat#Active Issues]] |
| memory | 1 | [[memory#Active Issues]] |
| hands-skills | 2 | [[hands-skills#Active Issues]] |
| middleware | 2 | [[middleware#Active Issues]] |

## 已归档

- 全量问题记录: `wiki/archive/known-issues-full-2026-04-22.md`
```

- [ ] **Step 4: Commit**

```bash
git add wiki/known-issues.md wiki/archive/known-issues-full-2026-04-22.md
git commit -m "docs(wiki): known-issues.md 转为索引 — 活跃问题迁入各模块"
```

---

## Chunk 2: Phase B — middleware.md (single source of truth)

### Task 4: Restructure middleware.md

**Files:**
- Modify: `wiki/middleware.md` (7KB → target 150-200 lines)

- [ ] **Step 1: Write new middleware.md**

Rewrite with 5-section template. Content mapping:

| New Section | Source |
|-------------|--------|
| Design Decisions | Current "设计思想" + index Q&A "为什么14层中间件" |
| Key Files + Data Flow | 14-layer table → Core Files, execution flow → Data Flow |
| Integration Contracts | NEW (see below) |
| Code Logic | Priority ordering, decision types |
| Active Issues + Gotchas | "11/14 no tests" warning, TrajectoryRecorder fix |
| Change Log | Last 5 from log.md |

Integration contracts:
- Called by ← kernel: `kernel/mod.rs:create_middleware_chain()` (kernel boot, once per session)
- Calls → runtime: `MiddlewareChain::run_before_completion()` (every chat request before LLM call)
- Called by ← saas: HTTP relay handler (10 HTTP middleware layers)
- Provides → all: `AgentMiddleware` trait (14 implementations registered)

Invariants:
- ⚡ Priority is ascending: 0-999, lower = earlier execution
- ⚡ Registration order ≠ execution order; chain sorts by priority at runtime
- ⚡ Stop/Block/AbortLoop halts the chain immediately (no further middleware runs)

- [ ] **Step 2: Verify line count**

Run: `wc -l wiki/middleware.md`
Expected: 150-200

- [ ] **Step 3: Verify all 5 sections**

Run: `grep '^## ' wiki/middleware.md`
Expected: ≥ 5 sections

- [ ] **Step 4: Commit**

```bash
git add wiki/middleware.md
git commit -m "docs(wiki): 重构 middleware.md — 5节模板+集成契约+不变量"
```

---

## Chunk 3: Phase C — Dependent pages

### Task 5: Restructure saas.md

**Files:**
- Modify: `wiki/saas.md` (231 lines → target 150-200)

- [ ] **Step 1: Remove security duplicates**

Delete: 认证流 (L46-61), 密码安全 (L78-89), Token刷新 (L91-98). Replace with: "认证安全详见 [[security]]"

- [ ] **Step 2: Write 5-section structure**

- Design Decisions: WHY SaaS relay architecture, WHY Token Pool
- Key Files: 16 SaaS dirs, 3-7 core files
- Integration Contracts: Called by ← desktop (Tauri invoke), Calls → relay, Token Pool
- Code Logic: Token Pool RPM/TPM algorithm, Workers (7), billing flow
- Active Issues + Gotchas: Active items from known-issues + Embedding deferred
- Change Log: Last 5

- [ ] **Step 3: Verify line count and commit**

```bash
git add wiki/saas.md
git commit -m "docs(wiki): 重构 saas.md — 移除安全重复+5节模板+契约"
```

### Task 6: Restructure security.md

**Files:**
- Modify: `wiki/security.md` (158 lines → target 150-200)

- [ ] **Step 1: Absorb auth content from saas.md**

Import the authentication flow, JWT pwv, password security content removed from saas.md.

- [ ] **Step 2: Write 5-section structure**

- Design Decisions: WHY each security mechanism
- Key Files: security files, auth flow diagram
- Integration Contracts: Provides → saas (auth middleware), Provides → desktop (crypto utils)
- Code Logic: JWT pwv mechanism, Argon2id, AES-256-GCM, rate limiting
- Active Issues + Gotchas: Security audit findings
- Change Log: Last 5

- [ ] **Step 3: Verify and commit**

```bash
git add wiki/security.md
git commit -m "docs(wiki): 重构 security.md — 吸收saas安全内容+5节模板"
```

### Task 7: Restructure memory.md

**Files:**
- Create: `wiki/archive/memory-extraction-details.md`
- Modify: `wiki/memory.md` (363 lines → target 200)

- [ ] **Step 1: Archive detailed extraction prose**

Move detailed extraction logic to `wiki/archive/memory-extraction-details.md`. Keep only flows + invariants in memory.md.

- [ ] **Step 2: Write 5-section structure**

- Design Decisions: WHY memory pipeline + index Q&A "进化引擎做什么" + Hermes insights (3-5 lessons in one paragraph)
- Key Files: 闭环数据流 diagram, 3-7 core files
- Integration Contracts: Called by ← middleware (Memory@150), Calls → FTS5/TF-IDF, Provides → loop_runner
- Code Logic: Pipeline flow, cross-session injection, FTS5+TF-IDF
- Active Issues + Gotchas: Cross-session fix history, profile store fix, Embedding deferred
- Change Log: Last 5

Invariants:
- ⚡ memories.db and data.db are separate SQLite databases; cross-DB queries need correct connection
- ⚡ Memory injection at middleware@150, AFTER ButlerRouter@80, BEFORE SkillIndex@200

- [ ] **Step 3: Verify ≤ 200 lines and commit**

```bash
git add wiki/memory.md wiki/archive/memory-extraction-details.md
git commit -m "docs(wiki): 重构 memory.md — 压缩至200行+不变量+Hermes提炼"
```

---

## Chunk 4: Phase D — Remaining modules

### Task 8: Restructure routing.md

**Files:**
- Modify: `wiki/routing.md` (13KB → target 150-200)

- [ ] **Step 1: Remove Store/lib listings**

Move chat stores → chat.md, saas stores → saas.md. Move lib/ listing → development.md.

- [ ] **Step 2: Write 5-section structure**

- Design Decisions: WHY 5-branch + WHY SaaS relay + index Q&A
- Key Files: 5-branch decision tree, degradation flow
- Integration Contracts: Calls → saas, Calls → kernel, Called by ← stores (getClient)
- Code Logic: Decision tree flow, model routing, SaaS degradation
- Active Issues + Gotchas: Current known issues
- Change Log: Last 5

- [ ] **Step 3: Verify and commit**

```bash
git add wiki/routing.md
git commit -m "docs(wiki): 重构 routing.md — 移除Store/lib列表+5节模板"
```

### Task 9: Restructure chat.md

**Files:**
- Modify: `wiki/chat.md` (~180 lines → target 150-200)

- [ ] **Step 1: Write 5-section structure**

- Design Decisions: WHY 3 ChatStream + index Q&A
- Key Files: 5 Store split, key files, send flow
- Integration Contracts: Calls → routing (getClient), Called by ← UI, Emits → streamStore
- Code Logic: Send message flow, stream events, 5-min timeout
- Active Issues: B-CHAT-07 (P2)
- Change Log: Last 5

Invariants:
- ⚡ sessionKey consistent within conversation
- ⚡ cancelStream sets atomic flag, no race with onDelta

- [ ] **Step 2: Verify and commit**

```bash
git add wiki/chat.md
git commit -m "docs(wiki): 重构 chat.md — 3种ChatStream WHY+契约+不变量"
```

### Task 10: Restructure butler.md

**Files:**
- Modify: `wiki/butler.md` (215 lines → target 150-200)

- [ ] **Step 1: Remove duplicates**

MemorySection frontend path → reference [[memory]]. SemanticSkillRouter → reference [[hands-skills]].

- [ ] **Step 2: Write 5-section structure**

- Design Decisions: WHY 管家默认 + WHY 双模式
- Key Files: ButlerRouter flow, cold start hook
- Integration Contracts: Middleware@80, Calls → skill router, Calls → memory
- Code Logic: Keyword matching, XML fencing, cross-session continuity
- Active Issues + Gotchas: Current issues
- Change Log: Last 5

- [ ] **Step 3: Verify and commit**

```bash
git add wiki/butler.md
git commit -m "docs(wiki): 重构 butler.md — 移除重复+5节模板+契约"
```

### Task 11: Restructure hands-skills.md

**Files:**
- Modify: `wiki/hands-skills.md` (281 lines → target 150-200)

- [ ] **Step 1: Write 5-section structure**

- Design Decisions: WHY 7 hands + WHY 75 skills + semantic routing
- Key Files: Hand trigger flow, skill chain
- Integration Contracts: Called by ← loop_runner, Calls → browser/Twitter, Provides → SkillIndex middleware
- Code Logic: Hand trigger+approval, TF-IDF routing, MCP bridge
- Active Issues: Hands E2E, Clip needs FFmpeg
- Change Log: Last 5

- [ ] **Step 2: Verify and commit**

```bash
git add wiki/hands-skills.md
git commit -m "docs(wiki): 重构 hands-skills.md — 5节模板+契约"
```

### Task 12: Restructure pipeline.md

**Files:**
- Modify: `wiki/pipeline.md` (157 lines → target 150-200)

- [ ] **Step 1: Add contracts and reorganize**

Already near target. Add integration contracts, invariants, reorganize to 5-section.

- Design Decisions: WHY DAG + WHY YAML
- Key Files: Architecture, templates
- Integration Contracts: Called by ← UI, Calls → runtime (DAG executor)
- Code Logic: DAG execution, template loading
- Active Issues: E2E pass rate
- Change Log: Last 5

- [ ] **Step 2: Verify and commit**

```bash
git add wiki/pipeline.md
git commit -m "docs(wiki): 重构 pipeline.md — 5节模板+契约"
```

### Task 13: Restructure data-model.md

**Files:**
- Modify: `wiki/data-model.md` (181 lines → target 150-200)

- [ ] **Step 1: Add contracts and reorganize**

Already near target. Add integration contracts, reorganize to 5-section.

- Design Decisions: WHY dual database (PG+SQLite)
- Key Files: DB schema overview
- Integration Contracts: Called by ← saas (PG), Called by ← memory (SQLite/FTS5)
- Code Logic: Dual-DB architecture, FTS5 structure
- Active Issues: pgvector deferred, CJK fallback
- Change Log: Last 5

- [ ] **Step 2: Verify and commit**

```bash
git add wiki/data-model.md
git commit -m "docs(wiki): 重构 data-model.md — 5节模板+契约"
```

---

## Chunk 5: Phase E — Index restructure

### Task 14: Restructure index.md

**Files:**
- Modify: `wiki/index.md` (144 lines → target ≤ 120)

- [ ] **Step 1: Remove architecture Q&A**

Delete "核心架构决策" section (5 Q&A pairs). Now in respective module pages.

- [ ] **Step 2: Add symptom navigation table**

8-row table from spec, after module navigation tree.

- [ ] **Step 3: Add module dependency map**

Simple ASCII: UI → routing → chat → middleware → memory → saas → security

- [ ] **Step 4: Verify ≤ 120 lines**

Run: `wc -l wiki/index.md`
Expected: ≤ 120

- [ ] **Step 5: Commit**

```bash
git add wiki/index.md
git commit -m "docs(wiki): 重构 index.md — 症状导航+依赖图+≤120行"
```

---

## Chunk 6: Phase F — feature-map.md conversion

### Task 15: Distribute feature-map chain traces

**Files:**
- Modify: `wiki/feature-map.md` (424 lines → ~80, index only)
- Modify: Module pages (add chain trace references)

- [ ] **Step 1: Add one-line chain traces to module Code Logic sections**

| Module | Features |
|--------|----------|
| chat | F-01~F-05, F-06~F-09 |
| hands-skills | F-10~F-13 |
| memory | F-14~F-16 |
| saas | F-17~F-22 |
| butler | F-23~F-25 |
| pipeline | F-26~F-28 |
| routing | F-29~F-31 |
| security | F-32~F-33 |

- [ ] **Step 2: Rewrite feature-map.md as lightweight index**

Module → feature mapping table only. No full chain details.

- [ ] **Step 3: Commit**

```bash
git add wiki/feature-map.md wiki/chat.md wiki/memory.md wiki/hands-skills.md wiki/saas.md wiki/butler.md wiki/pipeline.md wiki/routing.md wiki/security.md
git commit -m "docs(wiki): feature-map 分发链路到各模块 — 转为索引页"
```

---

## Final: Validation

### Task 16: Validate all criteria

- [ ] **Step 1: Line counts**

```bash
wc -l wiki/index.md wiki/routing.md wiki/chat.md wiki/saas.md wiki/security.md wiki/memory.md wiki/butler.md wiki/middleware.md wiki/hands-skills.md wiki/pipeline.md wiki/data-model.md
```

Expected: index ≤ 120, all others 100-200

- [ ] **Step 2: 5-section coverage**

```bash
for f in wiki/routing.md wiki/chat.md wiki/saas.md wiki/security.md wiki/memory.md wiki/butler.md wiki/middleware.md wiki/hands-skills.md wiki/pipeline.md wiki/data-model.md; do echo "=== $f ===" && grep '^## ' $f; done
```

Expected: each has Design Decisions, Key Files, Code Logic, Active Issues, Change Log

- [ ] **Step 3: Integration contracts**

```bash
grep -l 'Integration Contracts\|集成契约' wiki/*.md
```

Expected: all module pages

- [ ] **Step 4: Push**

```bash
git push
```