---
name: garden
description: 【SDD 工作流】文档园丁：扫描 docs/ 索引-子文件结构的健康度，检查 overview 索引条目与子文件一致性、frontmatter 合法性、status 生命周期、source_iteration 溯源有效性。对照实际代码检测过时条目，修复方式限于打 deprecated/superseded 标或补删除线，不改正文（正文由 /sdd:distill 或人工维护）。消费 plans/*/7-review.md 的「反哺过期登记」表落地 status 变更。触发条件：用户说 /sdd:garden、SDD 文档维护、整理 docs、对齐 docs 与代码、或 /sdd:commit 收尾提示处理反哺过期标记时使用。
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, TodoWrite
---

# /sdd:garden — 文档园丁

维护 `docs/` 索引-子文件体系的健康度。**只做元数据修复**（status / frontmatter / 索引条目一致性），不改正文。

## 核心原则

- **只修元数据，不改正文**：正文变更由 `/sdd:distill` 或人工维护（比如 overview 正文里发现错别字不归 garden）
- **索引与子文件必须一致**：overview 索引条目 ↔ 子文件存在 ↔ frontmatter 合法，三者必须闭环
- **生命周期驱动**：status 字段（active / deprecated / superseded）是核心操作对象
- **过期不删除**：过期条目打 deprecated 标而不是删除（保留历史，避免反哺丢失）
- **用户把关**：每个修复动作询问用户确认
- **反哺过期处理**：消费 `/sdd:verify` Phase 8 迭代复盘在 `plans/*/7-review.md` 的「反哺过期登记」表登记的过期项，落地为对应 tech-memory / tech-rule / tech-design 的 status 变更

> 开源版不扫 `bugs/` 目录（无此概念），也不扫 `docs/insights/` 的 deprecate 类草稿（旧版入口，开源版统一走 `7-review.md` 两张表）。

## 维护对象

| 层 | 对象 | 检查内容 |
|---|---|---|
| 索引层 | `docs/*-overview.md` | 索引条目格式（tech-arch 四段式 / tech-memory·rule·design 三段式）、链接指向的子文件是否存在、分类维度合理性 |
| 子文件层 | `docs/<subdir>/*.md` | frontmatter 必填字段、status 生命周期、source_iteration 指向的 plans 目录存在性、冗余版本号、冗余时间字段 |
| 模板层 | `docs/insights/_template.md` | 占位符完整、与插件 assets 的 _template.md 一致（漂移检测） |
| 关联层 | 索引 ↔ 子文件 ↔ 代码的三边一致性 | 索引条目指向的子文件存在；子文件描述的代码/模块仍存在 |

## 执行流程

---

### Phase 0：读配置

Read `.claude/dev-workflow.local.md`，确认项目上下文。

检测 `docs/` 是否存在：
- 不存在 → 提示执行 `/sdd:init`，终止

---

### Phase 1：overview 与子文件一致性检查

#### 1.1 收集 overview 索引文件

```bash
Glob docs/*-overview.md
```

记录 `{overviews}` 列表。

#### 1.2 收集子目录子文件

```bash
Glob docs/requirements/*.md
Glob docs/tech-arch/*.md
Glob docs/tech-design/*.md
Glob docs/tech-memory/*.md
Glob docs/tech-rule/*.md
Glob docs/insights/*.md
```

记录每个 `{subdir}` 的子文件清单。

#### 1.3 输出清单

```
文档清单：

overview：
  - docs/requirements-overview.md        · 上次修改 2026-05-03
  - docs/tech-memory-overview.md         · 上次修改 2026-04-18
  - ...

子文件：
  docs/tech-memory/      · 12 条
  docs/tech-rule/        · 3 条
  docs/tech-design/      · 5 条
  docs/requirements/     · 8 条（对应 8 个 Epic）
  docs/tech-arch/        · 5 条（tech-stack / layering / dependency-graph / deploy / project-type）
  docs/insights/         · 6 条（未蒸馏 3 条）
```

#### 1.4 索引 ↔ 子文件一致性检查

对每个 overview 和其同名子目录：

```
a. overview 每条索引条目的链接 → 子文件是否存在
   ├─ 链接指向的文件不存在 → 记为「悬挂索引」
   └─ 链接指向 _template.md 等模板 → 记为「索引污染」

b. 子目录每个子文件 → overview 是否有对应索引条目
   └─ 子文件存在但 overview 无索引 → 记为「孤儿子文件」

c. 索引条目格式：
   - tech-arch-overview.md → 四段式 `链接 · tags · 日期 · 摘要`
   - tech-memory-overview.md / tech-design-overview.md / tech-rule-overview.md → 三段式 `链接 · tags · 摘要`
   - requirements-overview.md → 业务模块地图（不检查格式，由用户手动维护）
   - 任一必填段缺失 → 记为「格式残缺」

d. 索引条目字段与子文件 frontmatter 一致性：
   - overview 条目的 title 是否等于子文件 frontmatter.title
   - overview 条目的 tags 是否等于子文件 frontmatter.tags
   - overview 条目的 摘要 是否等于子文件 frontmatter.summary
   - 不一致 → 记为「索引与子文件不一致」（以子文件 frontmatter 为准）
```

> `requirements-overview.md` 不做索引 ↔ 子文件一致性检查。该 overview 是静态业务模块地图，与 `docs/requirements/` 下的 Epic 文件没有强映射关系。

---

### Phase 2：frontmatter 合法性检查

对每个子文件（`docs/requirements/` / `docs/tech-arch/` / `docs/tech-design/` / `docs/tech-memory/` / `docs/tech-rule/`）：

```
必填字段清单（按子目录类型分）：
  - 所有：title / tags / summary / status
  - tech-arch / requirements：+ created / updated（这两类记录时间）
  - tech-memory / tech-rule / tech-design：不需要 created / updated（长期知识不记录时间）
  - source_iteration（tech-memory 强要求，其他可选）
  - source_insights（可选）
  - superseded_by（当 status=superseded 时必填）

检查项：
a. 缺字段 → 记为「frontmatter 残缺」
b. status 值非法（必须是 active / deprecated / superseded）→ 「非法 status」
c. status=superseded 但无 superseded_by → 「溯源断裂」
d. superseded_by 字段指向的文件不存在 → 「溯源目标失效」
e. created / updated 格式非 YYYY-MM-DD（仅 tech-arch / requirements 检查）→ 「日期格式错」
f. tech-memory / tech-rule / tech-design 子文件若出现 `created` / `updated` 字段 → 「冗余时间字段」（建议移除）
g. tags 为空数组 → 「缺 tags」
h. 冗余版本号检测：
   - tech-arch 以外的子文件，正文禁止出现具体版本号（形如 `@^1.2.3` / `v18.3` / `0.74.1`）
   - 发现版本号 → 「冗余版本号」（建议移除，版本以 package.json 为准）
   - tech-arch/tech-stack.md 同样建议移除版本号（保留名称与说明，版本号以 package.json 为准）
```

#### 2.1 正文中的代码引用检查（抽样，仅 tech-arch）

对 `docs/tech-arch/` 下的子文件（最容易与代码漂移）：

```
a. 模块引用检查：
   用 Grep 检查子文件中提到的文件路径/目录是否仍存在
   └─ 不存在 → 「代码引用失效」

b. API 签名检查（仅采样）：
   若子文件有 TypeScript 签名摘要，Grep 实际源码确认
   └─ 不匹配 → 「API 签名漂移」（仅提示，不自动修）
```

此项采样即可（太细会冗长）。主要目标是发现**严重**漂移。

---

### Phase 3：消费 7-review 反哺过期登记

```bash
# 扫描所有 7-review.md 的「反哺过期登记」表
Glob plans/*/7-review.md
```

对每个 7-review.md 文件：
1. Read「反哺过期登记」章节的表格
2. 按行解析出：`tech-memory / tech-rule / tech-design 路径 / 过期原因 / 建议动作 / superseded_by`
3. 筛出未落地的行（行尾无 `✅ 已落地` 标记）

> 反哺过期的识别在 `/sdd:verify` Phase 8 迭代复盘中产出，落地由 garden 消费。
> 开源版不再扫 `docs/insights/` 的 deprecate 类草稿——该入口已在 verify Phase 8 统一切换到「反哺过期登记」表。

> 若 7-review.md 中不存在「反哺过期登记」章节（老版本迭代复盘），跳过该文件。

对每条未落地候选，用 `AskUserQuestion` 逐条确认：

```
/sdd:verify Phase 8 标记以下条目已过期：

- docs/tech-memory/android-slider.md
  过期原因：Android 14 以上系统已修复该问题
  来源：plans/gh-456/7-review.md
  建议动作（由复盘对话产出）：deprecated

确认操作：
  A. 按建议执行（deprecated / superseded）
  B. 手动调整（比如复盘建议 deprecated，此处改为 superseded 并指定 superseded_by）
  C. 保留原状（override 复盘的判断）
```

按选择执行：
- **A/B 选 deprecated** → Edit 子文件 frontmatter，`status: active → deprecated` + 更新对应 overview 索引条目**前加 ⚠️ 前缀**
- **A/B 选 superseded** → Edit 子文件 frontmatter，`status: superseded` + `superseded_by: <新路径>` + overview 索引条目**用 `~~...~~` 包裹整行（删除线）**
- **C** → 跳过，不落地

处理完毕，**回写对应 7-review.md 的「反哺过期登记」表该行**，在行尾追加 `✅ 已落地（YYYY-MM-DD）` 标记（避免下次重复处理）。

---

### Phase 4：source_iteration 溯源有效性

对所有带 `source_iteration` 字段的子文件（主要是 tech-memory，其他子目录也可能有）：

```
a. source_iteration 指向的 plans/<ISSUE-ID>/ 是否存在
   ├─ 存在 → OK
   └─ 不存在 → 记为「迭代目录已删除」（不一定是问题，可能用户清理了旧迭代；需询问）

b. source_insights 数组中每个路径是否存在
   └─ 不存在 → 「insight 关联断裂」

c. distilled_to 字段（若有）指向的目标文件是否存在
   └─ 不存在 → 「蒸馏目标已删除」
```

对每条「迭代目录已删除」，后续 Phase 5 询问用户：
- 更新为新的 plans 路径（用户手动指定）
- 清空该字段
- 保留（仅做记录，知识本身仍然有效）

---

### Phase 5：汇总报告 + 逐条确认修复动作

#### 5.1 汇总报告（按严重性分级）

合并 Phase 1-4 的检查结果：

```
📊 文档健康报告

扫描文档：
- overview: {n1} 个
- 子文件: {n2} 个
- insights 草稿: {n3} 个

═══ 严重（必须修复） ═══

1. 悬挂索引：docs/tech-memory-overview.md 第 15 行
   链接指向 docs/tech-memory/xxx.md 不存在
   建议：删除该索引条目

2. 索引污染：docs/tech-memory-overview.md 第 20 行
   链接指向 _template.md（模板文件不应出现在索引中）
   建议：删除该索引条目

3. frontmatter 残缺：docs/tech-memory/sentry.md 缺 tags
   建议：补充 tags（garden 可根据文件内容推断）

4. 溯源断裂：docs/tech-rule/xxx.md status=superseded 但无 superseded_by
   建议：补 superseded_by 或改回 active

═══ 一般（建议修复） ═══

5. 孤儿子文件：docs/tech-design/order-precision.md 在 overview 中无索引
   建议：在 tech-design-overview.md 追加条目

6. 索引与子文件不一致：docs/tech-memory-overview.md 第 30 行的 tags 与子文件不符
   建议：以子文件 frontmatter 为准同步 overview

7. 代码引用失效：docs/tech-arch/layering.md 提到 src/screens/OldModule 已删除
   建议：删除该引用 / 更新到新路径 / 保留并备注

8. 迭代目录已删除：docs/tech-memory/legacy.md 的 source_iteration
   plans/gh-100/ 不存在（可能用户清理了旧迭代）
   建议：可选清理 source_iteration 字段或保留

═══ 轻微（可优化） ═══

9. 冗余版本号：docs/tech-arch/tech-stack.md 正文出现 `React 18.3` 等具体版本
   建议：移除版本号（版本以 package.json 为准）

10. 冗余时间字段：docs/tech-memory/xxx.md 含 `created` / `updated` 字段
    建议：移除（tech-memory / tech-rule / tech-design 不记录时间）

═══ 反哺过期处理（来自 /sdd:verify Phase 8 登记） ═══

11. 已处理：Phase 3 汇总（见上）

═══ 总结 ═══

- 严重问题：{n}（建议立即修复）
- 一般问题：{n}
- 轻微问题：{n}
- 已自动处理：{n}（反哺过期）
```

#### 5.2 逐项修复（交互式）

先询问用户整体策略：

```
发现 {total} 个问题。请选择修复方式：

  A. 逐条确认（每个问题单独询问，安全）
  B. 批量自动修复元数据类（仅处理：悬挂索引删除、frontmatter 补齐、冗余时间/版本号移除；其他仍然逐条询问）
  C. 跳过所有修复，仅输出报告
```

按选择进入对应流程。逐条模式对每个问题用 `AskUserQuestion`：

```
严重问题 1：悬挂索引

- 位置：docs/tech-memory-overview.md 第 15 行
- 详情：链接指向 docs/tech-memory/2026-04-10-xxx.md 不存在

选择：
  A. 删除索引条目（子文件已不存在，索引无意义）
  B. 保留（可能是用户临时移走了子文件，后续会恢复）
  C. 查找相似文件，询问是否为重命名后的文件
```

按选择执行。每个修复完成后继续下一个。

#### 5.3 修复操作清单（garden 允许的动作）

| 问题 | 允许的修复 |
|---|---|
| 悬挂索引 | 删除 overview 索引条目 |
| 索引污染 | 删除 overview 索引条目 |
| 孤儿子文件 | 在 overview 追加索引条目（tech-arch 四段式 / 其他三段式） |
| 格式残缺 | 从子文件 frontmatter 取值补齐 overview 索引字段 |
| 索引与子文件不一致 | 以子文件 frontmatter 为准同步 overview 条目 |
| frontmatter 残缺 | 追加缺失字段（tags/summary 从正文推断，需用户确认） |
| 非法 status | 改为 active（或询问用户选择） |
| 溯源断裂 | 补 superseded_by 字段（用户指定）或 status 改回 active |
| 溯源目标失效 | 询问：更新为新路径 / 清空 superseded_by + 改 status |
| 日期格式错 | 规范化为 YYYY-MM-DD（仅 tech-arch / requirements 需要日期） |
| 冗余时间字段 | 询问：移除 tech-memory / tech-rule / tech-design 子文件的 `created` / `updated` 字段 |
| 冗余版本号 | 询问：移除子文件正文中的版本号（保留名称与说明） |
| 迭代目录已删除 | 询问：清空 source_iteration / 更新为新路径 / 保留 |
| 代码引用失效 | 询问：删除该引用 / 更新到新路径 / 保留并备注 |
| API 签名漂移 | 仅提示，不自动修（避免错改） |
| 反哺过期 | Phase 3 已处理 |

#### 5.4 garden **禁止**的动作

- ❌ 删除子文件（只能改 status，不能删）
- ❌ 改子文件正文内容（正文由 `/sdd:distill` 或人工）
- ❌ 合并子文件（跨文件合并归 `/sdd:distill`）
- ❌ 自动修复 API 签名漂移（太容易错改）
- ❌ 批量操作无确认（批量模式也仅限明确的元数据类修复）

---

### Phase 6：输出维护报告

```markdown
# 🌱 文档维护完成

**扫描时间**: {timestamp}
**扫描范围**: docs/ 下 {n1} overview + {n2} 子文件 + {n3} insights

## 处理结果

| 类型 | 检出 | 已修复 | 跳过 |
|---|---|---|---|
| 悬挂索引 | 2 | 2 | 0 |
| 索引污染 | 1 | 1 | 0 |
| 孤儿子文件 | 1 | 1 | 0 |
| frontmatter 残缺 | 3 | 3 | 0 |
| 索引与子文件不一致 | 2 | 2 | 0 |
| 溯源断裂 | 1 | 1 | 0 |
| 代码引用失效 | 1 | 0 | 1（用户选择保留） |
| 冗余版本号 | 1 | 1 | 0 |
| 冗余时间字段 | 2 | 2 | 0 |
| 迭代目录已删除 | 1 | 0 | 1（用户选择保留） |
| 反哺过期（/sdd:verify Phase 8 登记） | 2 | 2 | 0 |

## 索引更新

- docs/tech-memory-overview.md · 删除 2 条悬挂索引 + 追加 1 条孤儿 + ⚠️ 前缀 1 条
- docs/tech-rule-overview.md · 补齐 3 条格式 + ~~删除线~~ 1 条
- ...

## 7-review 回写

- plans/gh-456/7-review.md · 「反哺过期登记」表 2 行追加 ✅ 已落地（2026-05-12）

## 未处理

- docs/tech-arch/layering.md 有 1 条 API 签名漂移（需人工确认）

## 下一步建议

- 若有 `status=deprecated` 的条目长期未使用：考虑 `/sdd:distill` 合并到新条目或人工归档
- 定期运行 `/sdd:garden`（建议 sprint 末 或大规模重构后）
- 严重漂移请配合人工梳理对应业务代码
```

---

## 常见异常与处理

| 异常 | 处理 |
|---|---|
| `docs/` 不存在 | 提示执行 `/sdd:init` |
| overview 不存在但子文件存在 | 创建空 overview 后追加索引 |
| 子目录完全空 | 跳过该子目录的检查，不报错 |
| `plans/` 不存在 | Phase 3 跳过（无反哺过期登记可处理） |
| 检查过程中某个维度失败 | 跳过该维度，继续其他维度，在报告中标注 |
| 大量问题（> 50） | 建议用户按类型分批处理 |

---

## 禁止事项

- ❌ **禁止修改子文件正文内容**（garden 只改 frontmatter 与 overview 索引条目）
- ❌ **禁止删除 `docs/<subdir>/` 下的任何子文件**（即便是 deprecated；超过一年的 deprecated 可询问用户，但默认保留）
- ❌ 禁止未经用户确认就修复任何问题
- ❌ 禁止合并多个子文件（归 `/sdd:distill`）
- ❌ 禁止修改 `plans/` 下的任何文件的正文（仅允许回写「反哺过期登记」表的 ✅ 已落地标记）
- ❌ 禁止删除 insights 草稿（即便标了 `distilled: true` 也不删，历史溯源用）
- ❌ 禁止扫描 `docs/insights/` 中的 deprecate 类草稿（开源版已切换到 `7-review.md` 两张表）
- ❌ 禁止扫描 `bugs/` 目录（开源版无此概念）