mnote/.codex/reasonix-tasks/results/design-governance-worker-a-01-03.md

# Design Governance Report — Worker A

审查范围：`design/01-tree-first-graph-kernel/process/`、`design/02-convex-rust-long-term-architecture/process/`、`design/03-rust-web/process/`

审查时间：2026-06-17

上位依据：`design/01-05-current-priority-overview.md`（2026-05-21 口径）

---

## 总览

| 域 | 文件 | 建议状态 | 高风险项 |
|----|------|---------|---------|
| 01 | 1-tree-first-graph-kernel-v1.md | **keep-process** | 无 |
| 01 | 1-1-tree-first-graph-kernel-checklist-v2.md | **keep-process** | 无 |
| 01 | 1-2-tree-first-graph-product-vision-progress-v1.md | **keep-process** | 无 |
| 01 | 1-3-current-priority-execution-checklist-v1.md | **keep-process** | 无 |
| 01 | 1-4-next-phase-execution-roadmap-v1.md | **keep-process** | 无 |
| 01 | 1-5-next-phase-sequential-execution-checklist-v1.md | **keep-process** | ⚠ 多数 items 未勾选 |
| 01 | 1-6-next-phase-gap-closure-checklist-v1.md | **keep-process** | ⚠ browser smokes 未复跑 |
| 01 | 1-7-local-workspace-root-page-bundle-checklist-v1.md | **archive-done** | 无 |
| 02 | 2-3-local-workspace-access-control-productization-v1.md | **archive-done** | 无 |
| 03 | 3-rust-web-long-term-architecture-v1.md | **keep-process** | 无 |
| 03 | 3-1-rust-web-long-term-checklist-v2.md | **keep-process** | 无 |
| 03 | 3-3-rust-web-tree-realtime-event-stream-v1.md | **keep-process** | 无 |
| 03 | 3-13-rust-web-local-markdown-gfm-ast-parser-migration-v1.md | **keep-process** | ⚠ 3 unsub items |
| 03 | 3-15-local-markdown-asset-upload-relative-path-v1.md | **keep-process** | ⚠ browser smoke 待补 |
| 03 | 3-17-convex-export-web-entry-v1.md | **needs-human-confirmation** | ⚡ 设计稿但未落码 |

---

## 逐文件审查

---

### 1. `01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md`

**建议状态：keep-process**

**证据：** `01-05-current-priority-overview.md` §1 明确列为当前仍然有效的 3 份上位主线之一。文档更新于 2026-04-22，全文固定 "tree-first graph kernel" 长期方向，不使用旧 Convex 默认存储 / Next 主入口 / BlockNote 默认编辑器口径。

**归档/保留原因：** 仍是 tree-first kernel 方向的权威定义文档，所有后续设计以此为基础。

---

### 2. `01-tree-first-graph-kernel/process/1-1-tree-first-graph-kernel-checklist-v2.md`

**建议状态：keep-process**

**证据：** `01-05-current-priority-overview.md` §3 明确列为"仍然有效但不在第一线"的 process 文档。文档头部已标注优先级转移说明，使用 `DONE / PARTIAL / NOT_STARTED` 状态体系，反映真实代码状态而非乐观口径。

**归档/保留原因：** 仍是 Kernel Phase 全景参考，Phase 0-3 已 DONE，Phase 4-9 进度清晰。

---

### 3. `01-tree-first-graph-kernel/process/1-2-tree-first-graph-product-vision-progress-v1.md`

**建议状态：keep-process**

**证据：** 更新于 2026-05-19，引用 `01-05-current-priority-overview.md` 作为上位依据。使用 local-first MVP 后阶段口径。包含对照 Wolai 帮助中心的详细块类型覆盖率、AI 操作能力缺口分析，以及三条架构收口主线的进度百分比。

**归档/保留原因：** 唯一一份产品愿景 vs 实现进展的对照文档，提供 gap analysis（AI 操作思维导图 / Office 文件），对产品规划仍有参考价值。

---

### 4. `01-tree-first-graph-kernel/process/1-3-current-priority-execution-checklist-v1.md`

**建议状态：keep-process**

**证据：** `01-05-current-priority-overview.md` §6 明确引用为"持续推进 checklist"。文档 P0-P6 全部勾选且有验证证据（单测命令 + smoke 脚本），P7 已完成阶段性瘦身。迁移到 done/ 的标准清晰列出并已满足。

**归档/保留原因：** 当前最活跃的执行清单，`1-3` 本身作为持续执行清单保留在 process/，已完成的上位设计各自在 done/。

---

### 5. `01-tree-first-graph-kernel/process/1-4-next-phase-execution-roadmap-v1.md`

**建议状态：keep-process**

**证据：** 更新于 2026-05-19，引用 `01-05` 和 `1-3`。全文核心论点是"架构收口为主，产品化闭环为辅"，与当前 local-first MVP 后阶段口径完全一致。

**归档/保留原因：** 定义了下一阶段路线图（WorkspacePath → BufferStore → Page Aggregate kernel-native → command context → live cache），仍有效。

---

### 6. `01-tree-first-graph-kernel/process/1-5-next-phase-sequential-execution-checklist-v1.md`

**建议状态：keep-process**

**证据：** 更新于 2026-05-19，引用 `1-4` 和 `1-3`。所有执行原则和 Phase A0-A7 定义仍符合当前架构方向。

**归档/保留原因：** 提供了顺序执行的详细清单，且多数 items 尚未勾选，说明它是未来的工作计划而非已完成的文档。

**⚠ 风险：** 全场 687 行，大多数 checkbox 未勾选。如果团队当前执行顺序已不按此 checklist 推进（例如优先做 BufferStore 而非 smokes），应降级为 `mark-process-reference` 或更新本文件。当前保留但需关注执行偏差。

---

### 7. `01-tree-first-graph-kernel/process/1-6-next-phase-gap-closure-checklist-v1.md`

**建议状态：keep-process**

**证据：** 创建于 2026-05-19，状态 `PARTIALLY_DONE`。引用 `1-5` 和 `1-4`。基于 Reasonix 执行汇总的缺口补齐文档。

**归档/保留原因：** 记录了哪些缺口已由 Reasonix 执行填补（BufferStore、CommandContext、export/rollback），哪些仍未完成（browser smokes、conflict UI）。仍有跟踪价值。

**⚠ 风险：** §6.2 列出 6 个未复跑的 browser smokes。这些 smokes 如果长期不跑，本文件的剩余项跟踪价值下降。

---

### 8. `01-tree-first-graph-kernel/process/1-7-local-workspace-root-page-bundle-checklist-v1.md`

**建议状态：archive-done**

**证据：**
- 所有 checklist items 全部勾选并附验证命令
- 8 个 Rust 单测通过（`create_default_local_workspace_uses_managed_data_root`、`local_tree_command_create_page_creates_timestamped_markdown_and_sibling_folder` 等）
- HTTP smoke 通过：`node scripts/task443-local-markdown-asset-upload-smoke.js`
- 浏览器验收完成（截图保存到 `tmp/page-bundle-*`）
- 磁盘结构验证通过：无默认 `pages/`、`assets/`、`mindmaps/` 顶层目录，新建页面带 `HHMMSS` 时间戳

**代码证据：**
- `create_default_local_workspace_for_actor_at_base` — `local_folder_source.rs:1494`
- 同名目录作为页面子容器 — 单测 `local_page_tree_uses_sibling_directory_as_page_children_container`
- 文件树不合并 `.md` 和同名目录 — 单测 `local_file_tree_keeps_markdown_and_sibling_folder_as_separate_rows`

**归档/保留原因：** 所有目标已实现且有验收证据。设计稿的收口方向是"默认工作区只保留用户内容根目录和 `.mnote/` 系统目录"——已落地。

---

### 9. `02-convex-rust-long-term-architecture/process/2-3-local-workspace-access-control-productization-v1.md`

**建议状态：archive-done**

**证据：**
- A1-A5 (P0 管理员控制面 API)：全部完成，`GET/POST/DELETE /api/admin/access-policy/*` 已实现并有单测覆盖
- B1-B5 (P1 权限覆盖审计)：全部完成，覆盖 local folder open、page body write、tree command、Hermes/Reasonix、shared AI session
- `01-05-current-priority-overview.md` §5 已将"管理员目录授权 UI/API"列为"已有最小实现与验证证据，不再作为当前第一优先级"

**代码证据：**
- `rust/crates/mnote-web/src/routes/local_folder_source.rs` — `add_local_access_grant_for_context`、`create_local_access_grant`、`ensure_local_workspace_access_for_actor`
- `rust/crates/mnote-web/src/ssr/pages/admin.rs` — 管理员 UI
- `rust/crates/mnote-web/src/routes/mod.rs` — route registration

**归档/保留原因：** 所有 checklist items 已勾选并有单测/代码证据。文档中定义的产品化目标（管理员可管理、agent 可复用、全入口不绕过）已实现。后续 access control 扩展可在新文档中推进。

---

### 10. `03-rust-web/process/3-rust-web-long-term-architecture-v1.md`

**建议状态：keep-process**

**证据：** `01-05-current-priority-overview.md` §1 明确列为当前仍然有效的 3 份上位主线之一。更新于 2026-05-09，定义了 Rust Web 分层方案（axum + Leptos Islands + Hermes）。

**归档/保留原因：** 仍是 Rust Web 架构的权威定义文档。

---

### 11. `03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md`

**建议状态：keep-process**

**证据：** `01-05-current-priority-overview.md` §3 明确列为"仍然有效但不在第一线"。文档头部已标注优先级转移说明（2026-04-22 + 2026-04-29 复核补充）。Phase 0-8 状态清晰（DONE / PARTIAL / NOT_STARTED），反映真实代码状态。

**归档/保留原因：** 仍是 Rust Web 实施全景参考。Phase 1 接近 DONE、Phase 8 接近 DONE、Phase 3/4/5/7 为 PARTIAL。

---

### 12. `03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`

**建议状态：keep-process**

**证据：** `01-05-current-priority-overview.md` §2.3 引用为 Tree Realtime 当前状态文档。2026-05-18 补充 local-first 口径，明确 Convex realtime substrate 仅适用于 convex_workspace。有明确 §9.2 "仍未完成" 说明不能移到 done/。

**归档/保留原因：** 有明确 §9.2 未完成项（Sidebar/page subtree/filetree 未全部统一到同一条 live stream cache；WS 尚未成为主实时链路）。README 中明确了 done/ 迁移前必须完成的验收标准。无风险。

---

### 13. `03-rust-web/process/3-13-rust-web-local-markdown-gfm-ast-parser-migration-v1.md`

**建议状态：keep-process**

**证据：** 文档自身 §11.9 明确标注 "[ ] 迁移完成后把设计稿状态从 process 移到 done" 未勾选。剩余 3 项未完成：
1. "[ ] 新增 web shell 单测，验证 legacy <-> Tiptap 转换不丢 marks"
2. "[ ] 把手写 parser 标记为过渡实现"
3. "[ ] 移除 web_shell.rs 中只为补丁存在的临时适配分支"

**归档/保留原因：** 迁移工作未完成。当前读侧 AST 已就位，写侧回 Markdown 仍部分依赖手写规则。无口径冲突。

**⚠ 风险：** 3 个未完成项如果长期无人推进，应降级为 `mark-process-reference`。但当前准确。

---

### 14. `03-rust-web/process/3-15-local-markdown-asset-upload-relative-path-v1.md`

**建议状态：keep-process**

**证据：** 文档状态头明确标注"（代码、单测和 HTTP smoke 已完成；真实浏览器 smoke 待补）"。§9 checklist 中除浏览器 smoke 外所有项目已勾选。实现与缺陷闭环在 `bugs/03-rust-web/done/3-16`。

**代码证据：**
- `local_markdown_asset_upload_copies_next_to_markdown_with_relative_path` 单测通过
- HTTP smoke 覆盖 `/api/local-folder/assets/upload` 真实 multipart 上传

**归档/保留原因：** 代码实现已完成，仅缺浏览器 smoke 这一最终验收。应该保持 process 直到 browser smoke 通过。

**⚠ 风险：** 缺少浏览器 smoke 意味着编辑器上传面板的实际用户体验未验证。低风险。

---

### 15. `03-rust-web/process/3-17-convex-export-web-entry-v1.md`

**建议状态：needs-human-confirmation → 候选人：mark-process-reference**

**证据：** 状态标记为 `process`，但文档是一份 Web 控制台 UI 的设计提案（"后续落码顺序"列出 5 步尚未实现的落码步骤）。CLI 工具已存在：
- `scripts/export-convex-workspace-to-local.js` 支持 `--dry-run`、`--manifest`、`--conflict-report`、`--rollback`
- `task444` 和 `task455` smoke 通过

`01-05-current-priority-overview.md` §5 已将 P6 (Convex 导出) 列为"已有最小实现与验证证据，不再作为当前第一优先级"。

**建议补充说明：** 文档作为 Web 入口设计稿保留在 process/ 会产生"这是当前待办"的误导。建议：

- **选项 A (推荐)：mark-process-reference** — 保持文档但标记为参考设计，不误认为待办。保留 CLI 设计供后续 Web 入口实现时参考。
- **选项 B：keep-process** — 如果团队明确要在短期内实现 Web 入口。
- **选项 C：archive-old-process** — 如果决定 CLI 能力已足够，不优先做 Web UI。

**⚠ 风险：** 如果标记为 process，用户可能误以为 Web 入口已进入实施状态。实际上 5 个落码步骤均未开始。

---

## 汇总统计

| 建议状态 | 数量 | 文件 |
|---------|------|------|
| keep-process | 11 | 1, 1-1, 1-2, 1-3, 1-4, 1-5, 1-6, 3, 3-1, 3-3, 3-13, 3-15 |
| archive-done | 2 | 1-7, 2-3 |
| needs-human-confirmation | 1 | 3-17 |

> 注：3-15 虽推荐 keep-process，但其代码实现已完成，仅缺浏览器 smoke；在 browser smoke 通过后应自动进入 archive-done。

---

## 最高风险项

1. **`3-17-convex-export-web-entry-v1.md` (needs-human-confirmation)** — 被标记为 process 但实质是未落码的设计稿，可能误导读者以为 Web 入口在实施中。需人工确认是降级为参考、归档、还是推进落地。

2. **`1-5-next-phase-sequential-execution-checklist-v1.md` (keep-process, ⚠)** — 全场 687 行，大多数 checkbox 未勾选。如果执行计划已偏离此 checklist，内容可能过时。

3. **`1-6-next-phase-gap-closure-checklist-v1.md` (keep-process, ⚠)** — 6 个 browser smokes 长期未复跑降低剩余项跟踪价值。

4. **`3-13-rust-web-local-markdown-gfm-ast-parser-migration-v1.md` (keep-process, ⚠)** — 3 个未完成项如果无人认领，迁移工作将停滞在 partial 状态。

---

## 验证命令

```bash
# 确认文件存在
find design/01-tree-first-graph-kernel/process design/02-convex-rust-long-term-architecture/process design/03-rust-web/process -maxdepth 1 -type f -name '*.md' | sort
# 确认归档建议的文件已落地代码
cargo test -p mnote-web create_default_local_workspace_uses_managed_data_root -- --nocapture
cargo test -p mnote-web local_tree_command_create_page_creates_timestamped_markdown_and_sibling_folder -- --nocapture
cargo test -p mnote-web local_workspace_access -- --nocapture
```

---

## 未完成项

- 本报告仅为只读审查，未移动任何 `design/` 文件。
- 如果审核通过，`1-7` 和 `2-3` 应移至各自域的 `done/`。
- `3-17` 需人工确认最终状态。