feat: 文档同步流程与任务目录重构

.gitignore

@@ -2,3 +2,4 @@ node_modules/
 dist/
 .worktree/
 .vitepress-dist/
+.opencode

assets/skills/flow-code/SKILL.md

@@ -19,24 +19,46 @@ description: 分支 → 编码 + 单测 → PR 提交
 ### 2. 检查 ADR 约束
 阅读相关 ADR，确保实现方案不违反已有架构决策。
 
-### 3. 分支 → 编码 → 单测 → PR
+### 3. 分支 → 编码 → 单测
 ```bash
 git checkout -b feat/<task-slug>
 # 实现代码 + 单元测试
 npm test
+```
+
+### 4. 文档同步检查
+完成编码后，逐项检查以下文档是否需要同步更新：
+
+```
+## 文档同步检查清单
+□ guides/quickstart.md — 安装方式或前置条件有变化吗？
+□ guides/configuration.md — 新增/修改了配置项吗？
+□ guides/usage.md — 命令或行为有变化吗？
+□ guides/architecture.md — 架构或流程有变化吗？
+□ docs/dev/guides/contributing.md — 开发流程有变化吗？
+```
+
+- 逐项评估，无需修改的跳过
+- 需要修改的文档随代码一起提交到同一个 PR
+- PR body 中列出已同步的文档
+
+### 5. 提交 PR
+```bash
 git commit -m "feat(<scope>): <title>"
 mkdir -p docs/dev/handoff
 echo "Closes #<issue-num>" > docs/dev/handoff/pr-body.md
 gh pr create --title "<title>" --body-file docs/dev/handoff/pr-body.md
 ```
 
-### 4. 更新开发文档
+### 6. 更新开发文档
 如涉及 API 变更 → 更新 `docs/dev/api/`
 如涉及数据模型变更 → 更新 `docs/dev/db/`
 
 ## Output
 - 代码已推送
 - PR 已创建并关联 Sub Issue（PR body 含 `Closes #<issue-num>`）
+- 文档同步 checklist 已完成
+- 已同步的文档随 PR 提交
 - dev docs 已更新
 
 ## 上下文管理

assets/skills/flow-review/SKILL.md

@@ -23,16 +23,29 @@ gh pr view <pr-number> --json title,body,files
 - 检查相关 ADR（`docs/adr/`）— 确认代码是否遵循架构决策
 - 确认规格来源：commit 消息中的 Issue 引用或 `docs/prd/` / `docs/dev/specs/`
 
-### 3. 双轴审查
+### 3. 文档同步确认
+确认 PR 中是否包含文档同步：
+- 检查 PR body 是否列出已同步的文档
+- 检查 `docs/guides/` 和 `docs/dev/guides/` 是否有相应变更
+- 如涉及配置/API 变更但文档未同步 → 标记为阻断性问题
+
+### 4. 双轴审查
 并行检查两个维度：
 
 **规范轴（Normative）** — 代码是否符合文档化的编码标准？
 参考 `references/smell-baseline.md` 中的代码气味基线。
 
 **规格轴（Specification）** — 代码是否忠实实现了需求？
 对照 PRD（`docs/prd/`）和设计方案（`docs/dev/specs/`）验证。
+- 如发现实现与设计偏差 → 追加到 `docs/dev/changelog/<YYYY-MM-DD-NNN-slug>.md`
+
+### 5. 合并前检查
+在合并前确认以下项：
+- 文档同步已完成（`docs/guides/` 已更新或无需更新）
+- changelog 已记录偏差（如有）
+- CI 已通过
 
-### 4. 发表审查意见
+### 6. 发表审查意见
 发现阻断性问题：
 ```bash
 gh pr review <pr-number> --request-changes --body "..."
@@ -42,13 +55,13 @@ gh pr review <pr-number> --request-changes --body "..."
 gh pr review <pr-number> --approve --body "..."
 ```
 
-### 5. 等待 CI + 自动合并
+### 7. 等待 CI + 自动合并
 ```bash
 gh pr checks <pr-number> --watch
 gh pr merge <pr-number> --squash --delete-branch
 ```
 
-### 6. 关闭关联 Sub Issue
+### 8. 关闭关联 Sub Issue
 如果 PR body 未包含 `Closes #<num>`（或 PR 合并后 GitHub 未自动关闭），手动关闭：
 ```bash
 gh issue close <issue-num> --comment "已完成，已合并至 main"
@@ -58,6 +71,7 @@ gh issue close <issue-num> --comment "已完成，已合并至 main"
 - PR 已审查
 - PR 已合并（条件满足时）
 - 关联 Sub Issue 已关闭
+- changelog 已记录偏差（如有）
 
 ## 后续
 - **/release** — 发布（如所有 PR 已合并）

docs/.vitepress/config.ts

@@ -28,6 +28,33 @@ function getSidebar(): DefaultTheme.Sidebar {
           link: `/${dir}/${name}`,
         })
       } else if (statSync(fullPath).isDirectory()) {
+        // Special handling for dev/tasks/ — feature subdirectories with date prefix
+        if (dir === 'dev' && entry === 'tasks') {
+          const featureDirs = readdirSync(fullPath).sort().filter(e => {
+            if (e.startsWith('.')) return false
+            return statSync(join(fullPath, e)).isDirectory()
+          })
+          if (featureDirs.length > 0) {
+            const taskItems: DefaultTheme.SidebarItem[] = featureDirs.map(fd => {
+              const fdPath = join(fullPath, fd)
+              const fdFiles = readdirSync(fdPath).sort().filter(e => e.endsWith('.md'))
+              const displayName = fd
+                .replace(/^\d{4}-\d{2}-\d{2}-\d{3}-/, '')
+                .replace(/-/g, ' ')
+                .replace(/\b\w/g, c => c.toUpperCase())
+              return {
+                text: displayName,
+                collapsed: true,
+                items: fdFiles.map(f => ({
+                  text: f.replace('.md', '').replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase()),
+                  link: `/${dir}/${entry}/${fd}/${f.replace('.md', '')}`,
+                })),
+              }
+            })
+            items.push({ text: 'Tasks', collapsed: false, items: taskItems })
+          }
+          continue
+        }
         const subEntries = readdirSync(fullPath).sort().filter(e => e.endsWith('.md'))
         if (subEntries.length > 0) {
           items.push({

docs/adr/2026-07-10-doc-sync-and-task-org.md

@@ -0,0 +1,103 @@
+# ADR 0004: 文档同步流程与任务目录组织
+
+**状态:** Proposed
+**日期:** 2026-07-10
+**上级:** [ADR 0003](/adr/2026-07-10-jekyll-to-vitepress)
+
+## 背景
+
+项目当前存在两个组织性问题：
+
+1. **任务目录混乱**：`docs/dev/tasks/` 下 14 个 `.md` 文件平铺，分别属于 "docs-and-pages" 和 "vitepress-migration" 两个 feature，无法区分归属、依赖关系和创建顺序
+2. **文档同步缺失**：代码变更后 `docs/guides/` 用户文档没有同步机制，可能导致文档与代码脱节
+
+## 决策
+
+### 1. 任务目录采用 `YYYY-MM-DD-NNN-slug/` 命名格式
+
+**格式**：`YYYY-MM-DD-NNN-slug/`，如 `2026-07-09-001-docs-and-pages/`
+
+**选择理由**：
+
+| 方案 | 排序 | 可读性 | 扩展性 | 结论 |
+|------|------|--------|--------|------|
+| `NNN-slug/`（仅编号） | 按编号无序（编号可能跨天） | 简洁 | 同一天多个 feature 时编号冲突 | ❌ |
+| `YYYY-MM-DD-slug/`（日期+slug） | 按时间排序 | 清晰 | 同一天多个 feature 无法区分 | ❌ |
+| `YYYY-MM-DD-NNN-slug/`（日期+编号+slug） | 字典序=时间序 | 清晰 | 每天独立编号，无限扩展 | ✅ |
+
+**关键点**：
+- `YYYY-MM-DD` 放在最前面，利用字符串字典序等于时间序的特性，无需额外排序逻辑
+- `NNN` 从 `001` 开始，每天独立递增，解决同一天多个 feature 的命名冲突
+- `slug` 提供人类可读的描述，方便 `git mv` 后快速定位
+
+**备选方案**：
+- 纯编号（`001-docs-and-pages/`）：简洁但跨天时编号不连续，排序无意义
+- UUID 前缀：完全放弃可读性，不适合人工浏览的目录结构
+
+### 2. 设计态（tasks/）与实现态（changelog/）分离
+
+**决策**：新增 `docs/dev/changelog/` 目录，与 `docs/dev/tasks/` 分离。
+
+**设计态（tasks/）**：
+- 记录原始设计意图和任务拆解
+- 在 `/design` 和 `/tasks` 阶段创建
+- 一旦创建，**不再修改**（保留设计原貌）
+
+**实现态（changelog/）**：
+- 记录实际实现与设计的偏差
+- 在 `/review` 阶段由 reviewer 追加
+- 每个 feature 一个 changelog 文件，生命周期与 feature 绑定
+
+**分离理由**：
+- 保留原始设计意图，便于复盘和审计
+- 避免在同文件中混入"设计"和"实际"导致信息混乱
+- 变更追溯清晰：tasks 看设计，changelog 看偏差
+
+**备选方案**：
+- 在 task 文件中直接追加偏差记录：会污染原始设计，不利于对比
+- 不记录偏差：失去可追溯性，不符合工程实践
+
+### 3. 文档同步嵌入 flow-code 而非独立 command
+
+**决策**：将文档同步检查作为 flow-code 技能内的固定步骤，而非独立的 `/doc-sync` 命令。
+
+**理由**：
+- 文档同步是编码流程的有机组成部分，不是独立活动
+- 独立 command 增加认知负担（8 个变 9 个 command），且容易遗漏
+- 嵌入 flow-code 确保每次编码后自动触发检查，无需开发者记忆
+- 符合"一个 slash command 完成一件事"的设计原则
+
+**备选方案**：
+- 独立 `/doc-sync` 命令：增加命令数量，且可能被跳过
+- 嵌入 flow-review：发现太晚，应在编码阶段就完成同步
+
+### 4. 人工 checklist 而非自动检测
+
+**决策**：文档同步使用人工 checklist 评估，不做自动检测。
+
+**理由**：
+- 代码变更与文档影响的映射本质上是语义判断，无法机械推导
+- 自动检测需要维护代码→文档的映射规则，投入产出比低
+- 人工 checklist 简单可靠，开发者最了解自己的变更影响范围
+- 对于 4 个 guides 文档的规模，人工评估成本极低
+
+**未来扩展**：当文档规模增长到 20+ 个文件时，可考虑 AI 辅助分析 diff 并推荐受影响的文档，但最终仍由人工确认。
+
+## 后果
+
+### 正向
+
+- 任务目录按 feature 组织，按时间排序，一目了然
+- 设计意图与实现偏差分离记录，可追溯
+- 文档同步嵌入编码流程，不会遗漏
+- 所有变更仅影响内部文件组织，对最终用户透明
+
+### 风险
+
+- 旧 task 文件路径的外部引用（如有）会 404 — 影响极小，文档站尚未广泛传播
+- `getSidebar()` 新增嵌套目录处理逻辑，增加维护成本 — 但仅限 `dev/tasks` 一个特殊路径
+- Changelog 依赖 reviewer 自觉追加 — 通过 flow-review 技能强制检查
+
+## 技术方案
+
+详见 [文档同步流程与任务目录重构 — 技术方案](/dev/specs/doc-sync-workflow)

docs/dev/changelog/2026-07-09-001-docs-and-pages.md

@@ -0,0 +1,15 @@
+# Changelog: Docs and Pages
+
+> 对应 tasks: `docs/dev/tasks/2026-07-09-001-docs-and-pages/`
+
+## 实现偏差
+
+（PR 合并前由 reviewer 追加）
+
+## 未实现项
+
+（如适用）
+
+## 额外实现项
+
+（如适用）

docs/dev/changelog/2026-07-10-001-vitepress-migration.md

@@ -0,0 +1,15 @@
+# Changelog: Vitepress Migration
+
+> 对应 tasks: `docs/dev/tasks/2026-07-10-001-vitepress-migration/`
+
+## 实现偏差
+
+（PR 合并前由 reviewer 追加）
+
+## 未实现项
+
+（如适用）
+
+## 额外实现项
+
+（如适用）

docs/dev/out-of-scope.md

@@ -17,3 +17,12 @@
 - 自定义域名配置
 - 多语言支持
 - 文档内容重写/重组 — 仅迁移，不修改内容
+
+## 文档同步流程与任务目录重构
+
+以下需求在访谈中明确排除，记录于此供后续参考：
+
+- 自动检测代码变更影响哪些文档（AI 辅助但最终人工判断）
+- specs/ 技术方案自动更新 — 设计阶段产物，代码阶段不改
+- adr/ 架构决策记录自动更新 — 设计偏离时单独更新
+- task 文件修改 — 保留原始设计意图，变更记入 changelog