51c6811e11
承接创始人需求:手动触发、增量(记上次清理时间→只分析该窗口)、两阶段审批门(发起分析 Workflow→编清理计划→评审→创始人批准后才动手清理)。把 2026-06-16 首轮目录治理固化为可重复可控流程。 三轴:①过期历史档→归档/压缩 ②核心设计档→措辞对齐现行真相 ③主任务总账→回填。组成:.agents/skills/doc-organizer.md(playbook两阶段) + .agents/tools/doc-organizer.sh(检测scan/可逆归档archive/记时record,实测exit0) + doc-organizer-analyze.mjs(分析相Workflow,三轴fan-out只读) + doc-organizer-state.json(seed 7f24a344@2026-06-16)。 手动触发=~/.claude/skills/doc-organizer/SKILL.md 薄入口(本机注册,照 _gstack-command 范式;执行逻辑随仓走)。红线:检测自动·判断留人·脚本不自删·阶段一只读·最新日在飞档不碰·白名单 orchestrator/channel-spike/generation-spike。索引同步 AGENTS §5 + .agents/README。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
6.2 KiB
文档整理助手（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 .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第 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，本次触发时间成为下轮窗口起点。
安全红线（不可破）
- 阶段一绝不改文件；阶段二只动已批准清单内、文件名 ≤ 当前未完成波次的历史档；最新日期在飞档不碰（脚本对
2026-06-16-*已硬拒归档）。 - 破坏性操作（归档/压缩/git rm）全程 git 跟踪可回滚；提交前守卫核验：无外来文件、无在飞档、无
orchestrator/*等未跟踪误纳。 - 检测自动、判断留人：脚本只报"疑似/超标"，KEEP/ARCHIVE/改不改由 agent 据 _index+MEMORY 裁决、再由创始人批准。
- 白名单永留：
orchestrator/（活工具箱）、channel-spike/（活 spike）、generation-spike/（可复现证据）。 - 多 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 |
判据来源 / 活地图 |
docs/agent-specs/2026-06-16-agent-specs目录治理-review.md |
首轮治理留痕（判据与全量分类范例） |