data-loss-gate

数据丢失关卡 — 执行破坏性操作前先确认

**约定：**参见 conventions/brain-first.md — 提议删除前，先检查实际目标：get_backlinks、 gbrain graph <slug>，以及底层文件的 git log。确认卡片的质量取决于 背后的检查是否充分。

**约定：**参见 _brain-filing-rules.md — 确认后生成的删除日志文件按日期命名，存放在 daily/ 下。

这是什么

一个会在任何破坏性操作执行前触发，并要求用户明确确认的关卡。Agent 会停止操作，展示可恢复性卡片，然后等待。

**范围说明：**这个关卡是一种路由约定——当破坏性意图匹配时，运行环境会将其解析到上下文中，行为良好的 Agent 会遵循该约定。它并非操作边界强制机制：如果技能从未加载，gbrain 运行时不会以任何机制阻止删除。（原生操作边界确认关卡已登记为待办事项；在实现之前，这项约定就是防线。）某些 CLI 操作界面有自己的标志关卡——例如，gbrain sources remove 要求使用 --confirm-destructive——但该标志确认的是 Agent 确定要执行操作。这项技能是为了确认用户是否确定。

何时触发

在执行以下任意操作之前：

Shell／文件系统层面：

• 对任何包含数据的目录执行 rm -rf
• 对超过 10 个文件执行 rm／unlink
• 执行会修改超过 10 个文件的 sed -i
• 对受 Git 跟踪的文件执行 git rm
• 批量截断或剥离文件内容
• 用更小的版本覆盖文件（剥离内容）
• 任何被描述为“清理”或“释放空间”且会触及数据文件的操作

Brain／数据库层面（gbrain 专属）：

• 批量遗忘——编写脚本或循环对许多事实执行 gbrain forget <fact-id>。单次遗忘是经过审慎考虑、可幂等执行的操作；批量遗忘则属于数据丢失。
• 批量删除页面——循环执行 gbrain delete <slug>，或使用任何脚本对一组 slug 批量执行 delete_page。删除是软删除（可通过 gbrain restore <slug> 恢复），直到被清除为止——请在卡片中说明这一点，但仍须经过关卡：批量误删后，要批量恢复并纠正代价很高。
• gbrain pages purge-deleted——从 Brain 的所有来源中永久删除软删除页面。这是软删除安全网的最后一道防线。首先向用户展示 gbrain pages purge-deleted --dry-run --json；该命令本身会询问确认（没有终端时退出码为 3），只有在用户同意后才使用 --yes 执行。
• 移除来源——gbrain sources remove <id> 会删除该来源及其中的所有页面。--confirm-destructive 标志不能替代确认卡片。
• 移除挂载——gbrain mounts remove <id> 只会移除本地注册信息（被挂载的 Brain 数据库仍然保留；重新添加即可恢复）。但如果工作流还计划删除挂载所对应的底层数据库或文件，也必须经过关卡——此时这些对象适用完整的确认卡片。
• 原始 SQL 截断——通过任何途径对 Brain 数据库执行任何 DROP TABLE、TRUNCATE，或不含精确 WHERE 条件的 DELETE（包括 psql、迁移脚本或引擎的 executeRaw 调用）。
• 批量删除数据库行；删除表、集合或索引。

要怎么做

步骤 1：执行前先停止

不要运行破坏性命令。先检查实际目标（反向链接、图边、Git 历史、文件内容——任何可用于佐证卡片内容的信息），然后向用户展示：

步骤 2：确认卡片

⚠️ DATA DELETION — Confirmation Required

What: [exactly what will be deleted/modified]
Count: [number of files/rows/pages/facts affected]
Size: [how much data will be removed]
Location: [exact paths, slugs, or source/mount ids]

Why: [the reason for the deletion]

Recoverable?
- [ ] Backed up to a remote (git remote, database backup, object storage)
- [ ] In git history (can git checkout)
- [ ] Soft-deleted in the brain (restorable via `gbrain restore` until purged)
- [ ] Re-fetchable from an upstream source (which one, how long)
- [ ] NOT recoverable — permanent data loss

What we'd lose:
- [specific data/capability that would be gone]
- [any downstream systems that depend on this data]

Alternative to deletion:
- [compress instead of delete?]
- [move to cold storage?]
- [archive to a remote backup?]
- [soft-delete and defer the purge?]

Proceed? (yes/no)

步骤 3：等待明确的“yes”

• 不要因为用户说“ok”“sure”或“go ahead”就继续——必须要求用户说“yes”或“do it”
• 如果用户说“wait”或提出问题，请先回答，然后重新展示确认卡片
• 如果用户说“no”，立即停止并提出替代方案

有关如何展示确认关卡并暂停本轮操作，请使用 ask-user 选择关卡模式——此技能提供卡片内容以及对明确肯定答复的严格要求；ask-user 提供停止并等待的规范。

步骤 4：执行并记录

确认后：

1. 将删除内容记录到 daily/notes/YYYY-MM-DD.md 的 ## Data Deletions 下
2. 记录：时间戳、内容、数量、大小、恢复路径
3. 如果删除量较大（>1GB 或 >1000 个文件／页面），请分批执行并更新进度

不存在例外类别

没有任何类别的数据默认可以丢弃。旧日志、git stash 条目、构建产物、缓存——它们都曾在某个时候成为某些内容的真实来源。是否可丢弃取决于具体目标，必须通过检查（反向链接、git 状态、依赖关系，以及能否重新获取及其成本）来确认——绝不能仅凭类别判断。如果检查确实表明目标是临时且可重新生成的，那么填写确认卡片很快，取得用户的“yes”也很快。这就是确认关卡正常运作的代价。

存在的原因

有一次，下游 Agent 为了腾出磁盘空间，删除了其大脑数据目录中一个数 GB 的原始源文件缓存。这些文件看起来“只是缓存”——但它们其实是一个计划中功能的源数据。虽然这些数据恰好可以从上游来源重新获取，但这次删除仍然是错误的，因为：

1. 它销毁了已有计划用途的成果
2. 事先没有取得数据所有者的同意
3. “清理”的说法让删除显得安全，实际却并非如此

规则：如果是数据，且数量庞大，就必须先征求同意。务必如此。

失败时的处理

对于任何 gbrain 错误 code、退出码、[AGENT] 块或通知块，请遵循Agent 操作者协议。此技能的具体要求如下：

• 破坏性命令以 3（confirmation_required）退出，或要求使用 --confirm-destructive：该标志确认的是 Agent 确实确定要执行，并不代表用户已同意。展示可恢复性确认卡片，并等待用户明确答复“yes”。
• gbrain pages purge-deleted 会永久移除软删除的页面，此后 gbrain restore 无法将其恢复：请在确认卡片上说明这一点。绝不要承诺无法验证的物理擦除或恢复能力。
• 删除或遗忘操作返回 write_pending（退出码 10）：在写入删除日志条目前，先轮询回执。

反模式

• ❌ “这些只是缓存文件”——缓存文件也可能是事实来源
• ❌ “我们可以从 API 重新获取”——重新获取需要时间和金钱，而且得到的数据可能不完全相同
• ❌ “它被 gitignore 忽略了，所以不重要”——被 gitignore 忽略 ≠ 不重要
• ❌ “磁盘已满，我现在就得腾出空间”——即使情况紧急，也要先征求同意
• ❌ “我会先清理，之后再告诉用户”——必须先取得确认，然后才能删除
• ❌ “这只是软删除”——错误的批量清理仍然会造成高昂的恢复成本，而且清除操作会让删除变为永久
• ❌ “命令已经带有 --confirm-destructive”——该标志确认的是 Agent 的意图，不是用户的同意
• ❌ 把删除说成唯一选项，却不列出替代方案

去重（明确边界）

• conventions/test-before-bulk.md — 写入侧的姊妹规范。test-before-bulk 用于把控批量写入质量（先测试 3-5 项，再运行 170 项）；data-loss-gate 用于把控批量销毁操作（批量删除前先确认）。就地重写页面的流程两者都需要：test-before-bulk 用于检查新内容，data-loss-gate 用于确认重写会销毁的内容。
• ask-user — 确认机制（2-4 个 选项、退出路径、停止本轮、处理回复）。data-loss-gate 是专用调用方：它会提供破坏性操作卡片，并采用 严格的明确肯定规则（“ok”不算同意）。对于任何非破坏性决策关卡，请转交给 ask-user。
• maintain — 知识库健康检查和例行清理（孤立项、反向链接、过时内容检测）。maintain 用于找出 清理候选项；若处理这些候选项涉及批量删除，则必须在执行前触发 data-loss-gate。“检查知识库健康状况”应转交给 maintain，而不是本规范。

合约

此技能保证：

• 在确认卡片呈现、且用户明确回复“yes”/“do it”之前，范围内（“触发条件”列表所列）的任何破坏性操作都不会执行。
• 卡片始终包含可恢复性检查清单、将丢失的内容，以及至少一种删除之外的替代方案。
• 已确认的删除操作会记录到 daily/notes/YYYY-MM-DD.md 的 ## Data Deletions 下，并注明时间戳、范围和恢复路径。
• 路由与 frontmatter 中的规范触发条件一致。
• 输出写入 writes_to: 中列出的目录。
• 保留隐私合约：不包含真实姓名、特定分支的文件系统路径字面值或上游分支引用。

完整的行为合约已记录在上文各正文部分；本节用于一致性测试。

输出格式

两个产物：

1. 确认卡片（执行前）——Step 2 中的确切围栏代码块，通过 ask-user 的停止并等待模式呈现。本轮在卡片呈现后结束；用户回复前不得再调用工具。
2. 删除日志条目（执行后，仅在用户明确回复“yes”后）——追加到 daily/notes/YYYY-MM-DD.md：

## Data Deletions

- **[HH:MM]** [what was deleted] — [count], [size]. Reason: [why].
  Recovery: [backup/git/restore path, or "none — permanent"].