---
name: doc-organizer
description: "创始人手动触发「整理/清理文档」时使用:增量窗口体检 → fan-out 三轴分类(过期历史档/核心设计档措辞/总账)→ 编清理计划 → 对抗评审 → 创始人批准后才归档/压缩/回填;阶段一只读、批准前零文件改动。"
---

# 文档整理助手（doc-organizer）

> **触发**：创始人**手动**（`/doc-organizer` 或"整理文档/清理文档"）。
> **性质**：**增量 + 审批门**式文档治理——只分析"上次清理→现在"窗口，**先发起 workflow 分析 → 编清理计划 → 评审计划 → 创始人批准后才动手清理**。把 2026-06-16 首轮目录治理固化为可重复、可控流程。
> **铁律**：**阶段一只读不写**；任何归档/压缩/改写/总账回填**必须等创始人批准**后才在阶段二执行。
> **分工**：机械检测/可逆搬运/记时 → `.agents/tools/doc-organizer.sh`；分析 fan-out → Workflow；分类判断/措辞修订/总账回填 → opus 子代理，主代理验证（见 [[opus-subagents-critical-tasks]]）。
> **依据**：`.agents/rules/engineering-conventions.md §10`、活地图 `docs/agent-specs/_index.md`、收口 `wave-close-checklist.md`。

---

## 何时触发

创始人手动，典型时机：一波收口后、感觉文档堆积时、或核心设计被新决策推翻后。**默认不自动跑**。

---

## 阶段一 · 分析 → 出计划 → 评审（零文件改动）

### 1. 读窗口 + 体检
```bash
bash .agents/tools/doc-organizer.sh since   # 上次清理 commit/时间（增量窗口起点；首次已 seed 7f24a344@2026-06-16）
bash .agents/tools/doc-organizer.sh scan    # 一次拿 delta + health + stale + ledger 全部信号
```
`scan` 四块：窗口内改动/新增文档 / 热目录体检（计数·体积·未归档横幅·未压缩巨档·混入非md）/ 核心设计档残留废弃选型词（含"疑似当现行"数，**疑似=优先看非必过期**，决策史/甘特表会假阳） / 总账新鲜度。

### 2. 发起分析 workflow（用 Workflow 工具 fan-out）
> 本 skill 指示即构成 Workflow 授权。把 scan 暴露的候选清单整理成 args，运行分析相脚本：
```
Workflow({ scriptPath: ".agents/tools/doc-organizer-analyze.mjs",
           args: { window, candidates:[{file,lines,type}], staleDocs:[{file,suspect}], ledgerGap } })
```
三轴并行分类、结构化返回（只读、不改文件）：
- **轴① 过期历史档**：每候选 → `{type, status(ACTIVE/SHIPPED/SUPERSEDED/SPIKE-DONE/DUP), action(KEEP/ARCHIVE/COMPRESS/EVICT/DELETE), pointer, rationale}`（判据=§10/_index：review 含"为什么"→KEEP/ARCHIVE；execution/edit-plan→COMPRESS；代码/证据→EVICT；噪声→DELETE；**KEEP=管当前/未来 或 某线唯一 SoT**）。
- **轴② 核心设计档措辞**：每 stale 档 → `{revise, bigRewrite, findings:[逐处:当现行?改/已降级?放过 + 现行口径]}`（基准=`tech-decisions.md`+AGENTS §3；事实核查据 `contracts/`+Flyway 勿臆造，规划项标 future-state 勿删）。
- **轴③ 总账**：`{窗口内已收口波次, 总账是否已回填, 待补段}`。

### 3. 编译清理计划（写计划档，仍不动目标文件）
主代理综合子代理结果 → 写 `docs/agent-specs/<今日>-文档整理-plan.md`：结论先行 + **逐档处置表** + **措辞修订清单** + **总账回填项** + 量化收益（归档N/压缩N/对齐N）+ 风险/约束/红线。

### 4. 评审计划（对抗一轮）
派 1 个 opus 评审子代理审计划：**误归档活档? 过度压缩? 措辞改错/事实臆造? 漏总账? 越红线动在飞档?** → 回填评审意见，主代理据以修订计划。

### 5. 呈创始人审批 —— 停在此
结论先行报告计划摘要 + 评审结论，**`AskUserQuestion` 请批**（执行 / 调整范围 / 不执行）。**未获批准前零文件改动。**

---

## 阶段二 · 执行（仅在创始人批准后）

### 6. 按批准的计划执行
- **压缩** = 改写为桩（状态横幅 `SHIPPED`/`SUPERSEDED→替代` + 目标 + 结论 + 权威指针；命名漂移等坑标"勿照抄"）。
- **归档** = `bash .agents/tools/doc-organizer.sh archive <文件名...>`（自动 git mv→`_archive/` + 全仓修引用 `agent-specs/X`→`agent-specs/_archive/X`，幂等）。
- **措辞对齐** = 外科 Edit（删除线 + 现行标注），不重排、不动无关内容；Mermaid 含废弃节点整图重画且语法合法；**大档重写先单独出计划过创始人**。
- **总账回填** = 按 [`wave-close-checklist.md`](wave-close-checklist.md) 第 1 步（§0/§6 + 表头日期 + 对账 commit）。
- 重活仍派 opus 子代理、主代理验证。

### 7. 报告 + 提交 + 记时
- 结论先行报告本轮成果（遵 [[founder-wants-compact-replies]]）。
- **守卫式** `git add` 本轮相关路径（**禁 `git add -A`**，见 [[multi-session-shared-tree-push-conflict]]）+ 提交。
- `bash .agents/tools/doc-organizer.sh record <new-commit> "<一句话摘要>"` → 写回 state，本次触发时间成为**下轮窗口起点**。

---

## 安全红线（不可破）

1. **阶段一绝不改文件**；阶段二只动**已批准**清单内、文件名 ≤ 当前未完成波次的历史档；**最新日期在飞档不碰**（脚本动态取目录内最新日期档作在飞保护锚，旧硬编码日期已废，2026-06-17 改）。
2. 破坏性操作（归档/压缩/git rm）**全程 git 跟踪可回滚**；提交前守卫核验：无外来文件、无在飞档、无 `orchestrator/*` 等未跟踪误纳。
3. **检测自动、判断留人**：脚本只报"疑似/超标"，KEEP/ARCHIVE/改不改由 agent 据 _index+MEMORY 裁决、再由创始人批准。
4. 白名单按现行路径维护：`orchestrator/` 已删（git 可查）、`channel-spike/` 已迁 `spikes/channel-spike/`、`generation-spike/` 已不存在。
5. 多 session 共享树：push 前 fetch 核对、撞车的别人 untracked 文档先避让（见 [[multi-session-shared-tree-push-conflict]]）。

## 配套文件

| 文件 | 作用 |
|---|---|
| `.agents/tools/doc-organizer.sh` | 检测(scan/since/delta/health/stale/ledger) + 可逆归档(archive) + 记时(record) |
| `.agents/tools/doc-organizer-analyze.mjs` | 阶段一分析相 Workflow 脚本（三轴 fan-out 分类，只读） |
| `.agents/tools/doc-organizer-state.json` | 上次清理时间/commit（增量窗口锚点，勿手改） |
| `.agents/rules/engineering-conventions.md §10` / `docs/agent-specs/_index.md` | 判据来源 / 活地图 |
| `git show bb7c2baf^:docs/agent-specs/2026-06-16-agent-specs目录治理-review.md`（已随域化重构删除、git 定位） | 首轮治理留痕（判据与全量分类范例） |