---
description: 按 retention 批清过期已归档变更：默认 dry-run，确认后硬删目录并写 tombstone
argument-hint: "[说明]"
---

> Pi 包 `@suwenguang/pi-kb`：运行时包根为环境变量 `PI_KB_ROOT`（由 `extensions/kb-root.ts` 注入）。
> 工种子 Agent 通过 **pi-subagents** 派发（已 bundled）；agent 定义见本包 `agents/`。
> 脚本调用示例：`node "$PI_KB_ROOT/scripts/<name>.mjs"`。

## 用户输入

${@:-（未附带参数；结合当前对话上下文执行，缺信息时向用户澄清。）}

---
按 `kb.project.json` → `archivePurge.retentionDays`（默认 **90**）批清过期**已归档**变更目录：硬删目录，写入 tombstone 供查重与审计。

**用途**：仅**策略批清**（**无单 id 删除**）；不迁移、不修半迁移。细则唯一出处：[kb-archive-purge.md](../skills/kb-workflow/references/kb-archive-purge.md)。

**执行 Agent**：建议 **kb-release**（或 admin）；工种见 [kb-agent-roles.md](../skills/kb-workflow/references/kb-agent-roles.md)。脚本由子 Agent / shell 执行；**主 Agent 不直接写盘**。

**输入**：无变更名称。可选标志：`--dry-run`（默认）、`--confirm`、`--scan-wikilinks`。

## 安全门禁

1. **只处理** `changeDirs.archived`（默认 `knowledge/变更/归档/`）下符合 `^\d{14}-` 的一级子目录；**禁止**触碰 `changeDirs.active`（进行中）。
2. `00-manifest.json` 的 `stage` **仅**允许 `archived` / `archived_with_debt`；缺 manifest 或 stage 不符 → 跳过并列入报告。
3. 默认 **dry-run**（未传 `--confirm` 即只报告不删）；真正删除须显式 `--confirm`。
4. 硬删前写 `{archived}/.tombstones/<change_id>.json`，并追加 `{archived}/.tombstones/_audit.jsonl`。
5. 可选 `--scan-wikilinks`：扫描 `knowledge/` 下 Markdown 是否仍指向待删归档路径；命中则跳过不删（见 reference）。

## Bootstrap 门禁（硬阻断）

本命令要求业务仓已完成 KB 初始化（`/kb-init` / `kb-bootstrap`）。开始前**必须**先跑机器门禁；失败则**立即停止**，禁止继续（含禁止用 `mkdir -p knowledge/...` 绕过建目录）。执行：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap-check.mjs" --target "$(pwd)"`

未通过时按脚本输出指引执行 `/kb-init`，或：

`node "${PI_KB_ROOT}/scripts/kb-bootstrap.mjs" --target "$(pwd)"`

## 执行步骤

1. 确认业务仓根（含 `kb.project.json` 或 `knowledge/`）；读取 `archivePurge.retentionDays`（缺省 90）。
2. Dry-run：

```bash
node "${PI_KB_ROOT}/scripts/kb-archive-purge.mjs" --target "$(pwd)" --dry-run
```

3. 向用户展示：retention、候选列表、跳过原因、可选 wikilink 命中。
4. 用户确认后执行（建议带 wikilink 扫描）：

```bash
node "${PI_KB_ROOT}/scripts/kb-archive-purge.mjs" --target "$(pwd)" --confirm --scan-wikilinks
```

5. 汇报：已删 / 跳过 / tombstone 路径；提醒查重已占坑（见 [kb-change-directory-id.md](../skills/kb-workflow/references/kb-change-directory-id.md)）。

## 与相关命令的边界

| 命令 | 边界 |
|------|------|
| `/kb-archive` | 归档迁移（`mv` 进行中→归档）+ 知识合并 + commit；**不删除**归档目录。长期清理见本命令。 |
| `/kb-verify-issue` | 验收打回：归档→进行中。purge 后该目录已不存在，**无法**再 verify-issue 回退；审计靠 tombstone。 |
| `/kb-repair` | 修半迁移 / manifest 漂移；本命令**不**修半迁移，只对满足门禁的过期归档做批清。 |

## 输出报告格式

```markdown
## 归档批清报告

| 项目 | 内容 |
|------|------|
| 模式 | dry-run / confirm |
| retentionDays | <N> |
| 候选数 | <N> |
| 将删 / 已删 | 列表（dirname） |
| 跳过 | 列表（dirname + 原因） |
| wikilink 命中 | 无 / 列表（跳过不删） |
| tombstone | `knowledge/变更/归档/.tombstones/<change_id>.json` |
| 审计 | `knowledge/变更/归档/.tombstones/_audit.jsonl` |
```

## 注意事项

- 本命令**不**接受单条变更 id / 中文名作为删除目标。
- 同 `change_id` 的 tombstone 已存在时脚本跳过、不覆盖。
- propose / lite 创建前查重须读 tombstone（同名中文名命中则禁止静默新建），见 [kb-archive-purge.md](../skills/kb-workflow/references/kb-archive-purge.md)「查重」。