docs(spec): wiki重构设计v2 — 修复review问题(执行顺序+内容映射+契约示例)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/superpowers/specs/2026-04-22-wiki-restructure-design.md

@@ -133,10 +133,19 @@ tags: [{module-specific tags}]
 
 ### Integration Contracts
 
-| Direction | Module | Interface | Notes |
-|-----------|--------|-----------|-------|
-| Calls → | {module} | {function/API} | {when/why} |
-| Called by ← | {module} | {function/API} | {when/why} |
+> Format: Direction | Module | Interface (Rust trait / Tauri invoke / TS function) | Trigger
+
+| Direction | Module | Interface | Trigger |
+|-----------|--------|-----------|---------|
+| Calls → | {module} | `{rust_fn / tauri_invoke / ts_fn}` | {when/why} |
+| Called by ← | {module} | `{rust_fn / tauri_invoke / ts_fn}` | {when/why} |
+
+<!-- Example (middleware.md):
+| Calls → | runtime | `MiddlewareChain::run_before_completion()` | Every chat request before LLM call |
+| Called by ← | kernel | `kernel/mod.rs:create_middleware_chain()` | Kernel boot, once per session |
+| Called by ← | saas | HTTP relay handler | SaaS relay routes (10 HTTP middleware) |
+| Provides → | all modules | `AgentMiddleware` trait | 14 implementations registered |
+-->
 
 ## Code Logic
 
@@ -179,22 +188,109 @@ tags: [{module-specific tags}]
 
 ## 4. Migration Plan
 
-### 4.1 Pages to Create/Update
+### 4.0 Execution Order
 
-| Page | Action | Notes |
-|------|--------|-------|
-| `index.md` | Restructure | Add symptom table, remove architectural Q&A (move to modules), target ≤ 120 lines |
-| `routing.md` | Restructure | Move Store list to respective modules, add integration contracts |
-| `chat.md` | Restructure | Add invariants, integration contracts |
-| `saas.md` | Restructure | Remove security details (reference security.md), add contracts |
-| `butler.md` | Restructure | Add integration contracts with middleware |
-| `middleware.md` | Restructure | Become single source of truth for middleware, add contracts |
-| `memory.md` | Restructure | Absorb hermes insights, add invariants |
-| `hands-skills.md` | Restructure | Add integration contracts |
-| `pipeline.md` | Restructure | Add integration contracts |
-| `security.md` | Restructure | Own all security design, add contracts |
-| `data-model.md` | Restructure | Add integration contracts |
-| `feature-map.md` | Convert to index | Distribute chain traces to modules, keep as index |
+Migration must follow this sequence due to cross-page dependencies:
+
+1. **Phase A — Archive/cap** (no dependencies): Cap `log.md` at 50 entries, archive old to `wiki/archive/`. Convert `known-issues.md` to pointer. Archive `hermes-analysis.md`.
+2. **Phase B — Single source of truth**: Restructure `middleware.md` first (other pages reference it).
+3. **Phase C — Dependent pages**: `saas.md`, `security.md`, `memory.md` (remove middleware/evolution duplicates, add contracts).
+4. **Phase D — Remaining modules**: `routing.md`, `chat.md`, `butler.md`, `hands-skills.md`, `pipeline.md`, `data-model.md`.
+5. **Phase E — Index last**: `index.md` restructure (depends on all modules being complete).
+6. **Phase F — feature-map.md**: Distribute chain traces to module "Code Logic" sections, convert to index page.
+
+**Rollback strategy**: Migrate one module per commit. Any partial state is internally consistent per-page. `git revert` on a single commit restores that module's old version.
+
+### 4.1 Per-Page Source-to-Target Mapping
+
+#### `index.md` (8KB → target ≤ 120 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Key numbers table | Keep | Stay (cross-validated with TRUTH.md) |
+| System data flow diagram | Keep | Stay |
+| Module navigation tree | Keep | Stay |
+| Architecture Q&A "Why 14 middleware" | Move | → `middleware.md` Design Decisions |
+| Architecture Q&A "Why 管家 default" | Move | → `butler.md` Design Decisions |
+| Architecture Q&A "Why 3 ChatStream" | Move | → `chat.md` Design Decisions |
+| Architecture Q&A "Why SaaS relay" | Move | → `routing.md` Design Decisions |
+| Architecture Q&A "Evolution engine" | Move | → `memory.md` Design Decisions |
+| Symptom navigation table | NEW | Add after navigation tree |
+
+#### `middleware.md` (7KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Design thought | Keep as "Design Decisions" | Expand with WHY from index Q&A |
+| 14-layer table | Keep | Core Files + Data Flow |
+| Execution flow diagram | Keep | Code Logic |
+| SaaS HTTP middleware (10 layers) | Keep | Integration Contracts |
+| "11/14 no tests" warning | Keep | Active Issues |
+| API interface (trait) | Trim to key data flow | Code Logic (flows only) |
+
+#### `routing.md` (13KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| 5-branch decision tree | Keep | Code Logic → Key Data Flows |
+| Store layer listing (25 stores) | Remove | Split: chat stores → `chat.md`, saas stores → `saas.md`, connection stores stay |
+| lib/ file listing (75 files) | Remove | → `development.md` reference appendix |
+| Model routing full chain | Keep (simplified) | Code Logic → Key Data Flows |
+| Tauri commands table | Keep | Integration Contracts |
+
+#### `chat.md` (6KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| 3 ChatStream implementations | Keep as Design Decision | Add WHY from index Q&A |
+| Store 拆分 (5 Store) | Move | → Key Files table |
+| Send message flow | Keep | Code Logic → Key Data Flows |
+| Add invariants | NEW | e.g., ⚡ sessionKey must be consistent within a conversation |
+| Add integration contracts | NEW | Calls → routing (getClient), middleware (chain), saas (relay) |
+
+#### `memory.md` (19KB → target 200 lines, largest compression needed)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Memory pipeline design | Keep as Design Decisions | + Absorb WHY from index Q&A |
+| FTS5/TF-IDF/embedding details | Keep invariants and flows | Code Logic |
+| Hermes insights (from hermes-analysis.md) | Distill 3-5 key lessons | Design Decisions (one paragraph) + Gotchas |
+| Detailed extraction logic | Trim to flows + invariants | Archive detailed prose to `wiki/archive/` |
+| Cross-session injection fix | Keep as historical pitfall | Gotchas |
+| Profile store connection fix | Keep as historical pitfall | Gotchas |
+
+#### `saas.md` (10KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Auth flow (JWT/Cookie/TOTP) | Remove details | → `security.md` owns design, saas.md keeps reference |
+| Billing/subscription | Keep | Code Logic → Key Data Flows |
+| Admin V2 | Keep summary | Key Files |
+| Token Pool RPM/TPM | Keep | Code Logic → Non-obvious Algorithms |
+| Add integration contracts | NEW | Calls → relay, Called by ← desktop client |
+
+#### `security.md` (6KB → target 150-200 lines)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| Auth flow details | OWN this content | Absorb from saas.md, become single source |
+| JWT/Cookie/TOTP details | Keep | Code Logic |
+| Rate limiting | Keep | Code Logic |
+| Add integration contracts | NEW | Provides auth middleware to SaaS, crypto utils to client |
+
+#### Other modules (`butler`, `hands-skills`, `pipeline`, `data-model`)
+
+All follow same pattern: keep existing design/code sections, add integration contracts, add invariants, trim to size budget.
+
+#### `feature-map.md` (15KB → Convert to index)
+
+| Current Content | Action | Destination |
+|----------------|--------|-------------|
+| F-01~F-05 chat chains | Distribute | → `chat.md` Code Logic as chain trace reference |
+| F-06~F-10 memory chains | Distribute | → `memory.md` Code Logic |
+| F-11~F-15 hand chains | Distribute | → `hands-skills.md` Code Logic |
+| Remaining chains | Distribute | → Corresponding module pages |
+| File itself | Keep as index | Module → feature chain mapping only |
 
 ### 4.2 Pages to Merge/Archive
 
@@ -202,7 +298,7 @@ tags: [{module-specific tags}]
 |------|--------|-------------|
 | `known-issues.md` | Convert to pointer | Active issues → per-module, global file = links only |
 | `log.md` | Cap at 50 entries | Archive old entries to `wiki/archive/log-{YYYY-MM}.md` |
-| `hermes-analysis.md` | Archive | Key insights → `memory.md`, file → `wiki/archive/` |
+| `hermes-analysis.md` | Archive | Key insights → `memory.md` Gotchas, file → `wiki/archive/` |
 | `development.md` | Keep as-is | Global dev standards, not per-module |
 
 ### 4.3 Duplicate Content Resolution
@@ -236,6 +332,4 @@ tags: [{module-specific tags}]
 
 ## 7. Open Questions
 
-- Should feature-map.md be fully absorbed into modules or kept as a standalone index?
-- What format for integration contracts — prose table or structured schema?
 - Should we add a `wiki/templates/module-template.md` for consistency?