rrrrrredy/beforedone

BeforeDone

让编码智能体证明它们已经完成。

BeforeDone 是一个面向编码智能体的开源证据门禁与事故回放工具包。它将配置的检查转化为与其声明的相关文件范围绑定的回执，通过单一机器可读门禁评估完成情况，并从可观测事件和产物重建失败的运行。Codex 钩子可以阻止第一次 Stop 尝试；DeepSeek Harness Bundle 评估原生回合停止边界；项目本地的 Pi 扩展评估已结束的运行，并可启动一次纠正性续跑。

网站与指南

证据与技术报告

实证技术报告冻结了协议、144 个符合条件的验证性结果、分析以及可复现性产物。一次未产生任何结果的被取代尝试被保留以供审计，并从所有有效性分母中排除。在可支持主张的子集中，每种条件都观察到 0/60 次无依据完成，因此报告不作出优越性主张；它记录了机制、可审计性以及测得的验证器成本。

单独的 beforedone-paper 仓库包含完整协议、运行记录、分析代码和报告来源。这使产品检出专注于 CLI，并保护该研究与其所评估的确切实现相对应。

阅读报告与产物

一个产品，五种交付形式

- CLI：检查、回执、事故、回放和适配器验证的事实来源。
- Codex Git Marketplace 插件：自动化体验。它捆绑 Stop Hook 和两个 BeforeDone 技能，同时将所有证据决策委托给 CLI。
- 独立技能包：相同的两个工作流，但没有生命周期钩子或 Stop 强制执行。
- DeepSeek Harness 社区 Bundle：原生会话事件捕获，加上完成前门禁和一次有界纠正性续跑。
- 项目本地 Pi 扩展：有界 Pi 生命周期捕获，加上结算后证据决策和一次纠正性续跑。

每种设置都需要 CLI。对于 Codex，请恰好选择一种集成路径：

1. 插件，用于钩子加两个捆绑技能；
2. 独立技能包，用于手动工作流；或
3. 来自 beforedone setup codex 的项目本地钩子，用于自动门禁而无需安装插件。

不要在一个 Codex 环境中组合这些路径。插件加独立技能会重复工作流；插件加项目本地钩子会运行两次生命周期集成。

对于 Pi，请使用 beforedone setup pi。不要在同一 Pi 运行时中加载生成扩展的另一份副本。

对于 DeepSeek Harness，请将 dsh-beforedone 安装到所选配置文件中。不要将其与同一会话的另一个 BeforeDone 生命周期适配器组合使用。

要求
- 一个 Git 仓库。BeforeDone 通过 Git 解析其本地运行时。
- 一个为 Git 目录支持同目录硬链接的文件系统；
在 Windows 上，请将仓库放在 NTFS 上，而不是 FAT/exFAT 可移动介质上。
- .beforedone.yaml 中指定的验证器程序，例如 go、npm 或
pytest。
- 仅当你使用 Plugin、独立 Skills 或项目本地 hooks 时才需要 Codex。
- 仅当你使用 dsh-beforedone 社区 Bundle 时才需要 DeepSeek Harness 0.1.0-rc.6 以及 Node.js 22.19+ 或 24+。
- 仅当你使用 Pi 集成时才需要一个当前版本的 Pi 发行版，且暴露 agent_settled、pi.exec、pi.appendEntry
和 pi.sendUserMessage。

1. 安装 CLI

在已安装 Go 的情况下：

go install github.com/rrrrrredy/beforedone/cmd/beforedone@latest
beforedone version

或者，从
GitHub Releases
下载适用于 Windows、macOS 或 Linux 的归档文件，
对照 checksums.txt 进行校验，并将 beforedone 可执行文件放入
PATH。

若要使用 Go 安装可复现的版本，请将 @latest 替换为发布标签，
例如 @v1.1.1。

2. 初始化仓库

从目标 Git 仓库内的任意目录运行以下命令：

beforedone init
beforedone doctor

init 会在 .beforedone.yaml 缺失时创建它，并在 .git/beforedone 下初始化本地
运行时数据。可以安全地重复运行：现有的有效
配置会被保留。

在运行检查之前，请审查生成的配置。命令是 argv
数组，而不是 shell 命令字符串：

schema_version: 1
checks:
test:
argv: ["go", "test", "./..."]
relevant_files: ["*/.go", "go.mod", "go.sum"]
working_directory: "."
timeout_seconds: 600
required: true
capture:
max_output_bytes: 1048576
redact_patterns:
- '(?i)(api[_-]?key|token|password|secret)\s[:=]\s[^\s]+'
reports:
retain: 20

选择可信的检查

一份新的 Receipt 只能证明所配置的验证器针对其
声明的文件通过了检查。它不能证明该验证器覆盖了所有验收
标准。用户不需要诊断确切的 bug，但任务仍然
需要可观察的验收标准以及一条测试这些标准的可信命令。

beforedone init 只是一个起点，而不是自动测试设计器。它
能识别 Go 模块并提出 go test ./...；对于其他仓库，其
git status --short 默认值只是脚手架，并不是正确性证明。
请审查现有的测试、构建、lint、类型检查、包脚本和 CI 命令，
然后保留能够可信地覆盖该任务的最小集合。如果覆盖
缺失，请在该变更范围内添加一个有针对性的回归测试，或者将
未覆盖的标准报告为未验证。

建议的 Codex 提示

为仓库配置一次：

Help me configure BeforeDone for this repository. Inspect the existing test,
build, lint, type-check, package-script, and CI configuration. Use
beforedone init 仅作为起点。配置最小可信的现有命令集合，纳入所有可能影响每项检查的文件类别，并报告假设与覆盖缺口。不要添加依赖，不要用 git status --short 作为正确性证明，也不要仅仅为了获得 PASS 而虚构一项检查。

验证一项任务：

对此任务使用 BeforeDone。将我的请求转化为可观察的验收标准，将其映射到现有测试或检查，并在覆盖缺失且该变更在范围内时添加最小的回归测试。在宣布完成之前，运行每一项必需的 BeforeDone 检查，并确认当前文件有新的 PASS 凭据。如果任何标准缺乏可信证据，请将其报告为未验证，而不是称其为 PASS。不要仅仅为了获得 PASS 而削弱检查。

这些提示帮助 Codex 提出并应用验证契约；它们不会将自然语言的信心转化为 Receipt。在依赖 .beforedone.yaml 之前，请先审查它。

不要将凭据放入验证器命令行参数中，也不要在验证器路径中使用敏感名称。证据凭据有意保留实际的 argv 和工作目录元数据，以便审查者能看到运行了什么；这些结构字段不会被输出脱敏重写。请使用基于环境或原生的凭据机制，并在分享凭据/报告元数据之前进行审查。

通过 BeforeDone 运行一项已配置的检查，然后检查其有效结果：

beforedone check test
beforedone receipt test

在不运行验证器的情况下评估每一项必需的凭据：

beforedone gate
beforedone gate --json

门禁同时返回 decision 和证据 verdict。缺失、失败、无效或过期的必需证据会阻止完成。验证器凭据本身为 INCONCLUSIVE 时，保留现有的非阻塞警告行为：decision 为 allow，verdict 和进程退出仍为 INCONCLUSIVE，并且 system_message 解释该不确定性。适配器必须读取 decision；它们不得仅从退出代码推断该值。

成功的进程会为当前相关文件指纹创建 PASS 凭据。更改相关文件会使该凭据过期；更改检查已配置模式之外的文件则不会。普通命令输出中的 PASS 之类的词永远不会覆盖非零进程退出。

相关 glob 也包括匹配的 Git 忽略文件，例如生成的 Go 源代码，并且指纹包含可执行模式变更。Git 在 BeforeDone 流式输出结果之前应用忽略文件路径规范，并带有硬性文件数、列表大小和内容大小限制；超过限制会失败关闭，而不是静默省略证据。v1 中不对手模块内容进行指纹计算：如果某个 relevant_files 模式可能覆盖 Git 子模块或其下的路径，该检查会失败关闭，而不是签发可复用的证据。

前瞻性研究计划和演进账本属于研究、记忆、
或创建它们的运行时演化系统。它们不会创建或刷新 Completion Receipt。BeforeDone 仅负责最终配置的检查以及当前相关文件指纹；参见演化研究边界。

3. 选择一种 agent 集成方式

路线 A：Codex Git Marketplace 插件

Git Marketplace 插件包含 Stop Hook 和两个 skills。先安装 CLI，然后添加公共 Git marketplace：

codex plugin marketplace add rrrrrredy/beforedone

重启 ChatGPT 桌面应用，在 Codex 中打开 Plugins Directory，选择 beforedone marketplace 源，打开 BeforeDone，然后选择 Install。接着打开 /hooks，审查并信任 BeforeDone hooks，并启动一个新任务，以便捆绑的 skills 可用。该插件不会静默下载或更新 CLI；缺少可执行文件时会产生可操作的错误。

更新此路线：

go install github.com/rrrrrredy/beforedone/cmd/beforedone@latest
codex plugin marketplace upgrade beforedone

然后在 Codex Plugins Directory 中打开 BeforeDone，并应用所提供的更新。如果该界面不提供就地更新，请从刷新后的 marketplace 卸载并重新安装该插件。

移除此路线时，请在 Codex Plugins Directory 中打开 BeforeDone，然后选择 Uninstall plugin。如果你也不再需要该仓库 marketplace，请单独移除该源：

codex plugin marketplace remove beforedone

移除 marketplace 源不能替代在 Plugins Directory 中卸载插件。

路线 B：独立 Skills Pack

选择此路线而非插件。它安装相同的工作流，但无法观察生命周期事件或强制执行 Stop Gate。

请让 Codex 针对每个确切路径运行一次内置 skill 安装器：

$skill-installer install https://github.com/rrrrrredy/beforedone/tree/main/skills/verify-before-done

$skill-installer install https://github.com/rrrrrredy/beforedone/tree/main/skills/investigate-agent-incident

这些 skills 将在下一个 Codex 回合可用。要将它们固定到 v1.1.1，请将两个 URL 中的 /tree/main/ 替换为 /tree/v1.1.1/。

你也可以通过第三方 skills.sh CLI 安装两者。BeforeDone 本身没有遥测，但 skills.sh 是独立工具，可能会收集其自身的使用数据。如有需要，请显式禁用该安装器的遥测：

DISABLE_TELEMETRY=1 npx skills add rrrrrredy/beforedone --skill verify-before-done --skill investigate-agent-incident --agent codex --global --yes

PowerShell：

$env:DISABLE_TELEMETRY = '1'
npx skills add rrrrrredy/beforedone --skill verify-before-done --skill investigate-agent-incident --agent codex --global --yes
Remove-Item Env:DISABLE_TELEMETRY

要更新由 $skill-installer 安装的 skills，请仅移除或备份
来自 $CODEX_HOME/skills 的 verify-before-done 和 investigate-agent-incident
（默认是 ~/.codex/skills），重新运行两个安装提示，并开始一个新的
回合。要卸载此路线，只需移除这两个相同的目录。

如果你使用了 skills.sh，请继续使用该安装器进行生命周期管理：

DISABLE_TELEMETRY=1 npx skills update --global verify-before-done investigate-agent-incident
DISABLE_TELEMETRY=1 npx skills remove --global verify-before-done investigate-agent-incident

路线 C：项目本地 Codex hooks

请选择此路线，而不是 Plugin 和独立 Skills。它会将
BeforeDone 生命周期处理器写入当前仓库的 .codex/hooks.json，
并将它们固定到设置期间找到的绝对 CLI 可执行文件：

beforedone setup codex

打开 /hooks，审查并信任项目 hooks，然后开始一个新任务。如果
CLI 路径在升级期间发生变化，请重新运行 beforedone setup codex。仅使用以下命令移除
BeforeDone 项目 hooks：

beforedone setup codex --remove

DeepSeek Harness：社区 Bundle

安装 BeforeDone CLI v1.1.1 或更新版本，初始化目标仓库，
然后将 Bundle 添加到你使用的 Harness 配置文件中：

dsh plugin --profile headless add dsh-beforedone@0.1.0
dsh --profile headless --dump-config

该 Bundle 订阅原生仅追加会话日志，通过 Adapter Kit 刷新规范化
元数据，并在
agent/turn-stopping 处运行 beforedone gate --json。阻塞或不安全的结果会成为一条持久的引导
消息。下一次停止会被重新评估，但同一回合绝不会被强制超过
一次。

提示文本、推理、工具参数和工具输出不会被复制到
.git/beforedone；规范化账本包含本地会话工作
目录、生命周期标识符、消息来源/插件名称、工具名称和
结果状态。缺少 CLI 支持、超时、输出截断、部分
摄取和损坏的 JSON 会大声失败，而不是变成隐式成功。

完整的兼容性、配置、测试、隐私和移除说明见
integrations/deepseek-harness/README.md。
这是社区插件，不是官方 DeepSeek 插件。

Pi：项目本地扩展

当仓库通过 Pi 使用时，改为运行以下命令：

beforedone setup pi

该命令会写入 .pi/extensions/beforedone.ts，并将其固定到设置期间找到的绝对
BeforeDone 可执行文件。审查该文件，批准 Pi 的
项目信任提示，然后开始一个新的 Pi 会话。如果 CLI 路径
发生变化，请重新运行 setup；仅使用以下命令移除此生成的扩展：

beforedone setup pi --remove

该扩展通过规范化 Adapter 契约记录 session_start、输入元数据、工具启动/完成、
agent_settled 和 session_shutdown。
它有意不持久化提示文本、工具参数、工具输出或
原始记录。其分支感知的自定义条目最多允许一次自动
更正。交互式或 RPC 输入会重置该守卫；来自扩展的输入则共享现有守卫。

Pi 在其自动重试、压缩和排队延续路径耗尽后暴露 agent_settled。这使得该集成对于纠正性后续操作很有用，但它并不等同于 Codex 的完成前 Stop 钩子：在 BeforeDone 发送纠正性用户消息之前，第一条不受支持的最终消息可能已经可见。随后的一次重试守卫允许下一个已结算结果，而不会造成无限循环。

事件与重放

根据当前仓库证据创建自包含的 HTML 报告、机器可读 JSON 和 Replay Case：

beforedone incident
beforedone incident --correction "The parser still mishandles escaped delimiters."
beforedone incident --transcript path/to/codex-transcript.jsonl

报告包含时间线、Claim/Evidence Matrix、缺失或过期的证据，以及现有证据所支持的最早分歧点。其精度恰好为 exact_event、time_window 或 unlocated 之一。精确事件要求与已验证的失败 Receipt 显式匹配；时间窗口必须由该检查周围观察到的事件界定。通用的非零工具退出和后续用户更正不会制造位置。BeforeDone 不会恢复隐藏推理或思维链。

可选转录是不稳定的叙述性上下文，不是信任来源，也不是 First Observable Divergence 的输入。BeforeDone 最多接受 4 MiB，应用脱敏，并且仅存储有界的 16 KiB 叙述摘录及其 SHA-256 摘要和截断标志；它不会将原始转录复制到事件中。

重放分析从不运行外部命令：

beforedone replay analyze

验证默认也是试运行。它显示仅来源于当前仓库配置的计划；导入的 Replay Case 中找到的 argv 会被忽略：

beforedone replay verify
beforedone replay verify --check test

只有显式的 --execute 才会在临时分离的 Git worktree 中运行配置的检查：

beforedone replay verify --check test --execute

BeforeDone 在创建该内部 worktree 时会禁用仓库 Git 钩子。配置的验证器在检出后仍会正常运行。

BeforeDone 不提供网络隔离。配置的验证器可以使用该进程可用的网络、凭据和其他资源。Replay 在脱敏和报告截断之前，通过配置的 capture.max_output_bytes 限制捕获验证器输出，因此无界验证器无法创建无界的内存结果。

命令与退出码

beforedone init
beforedone doctor
beforedone setup codex [--remove]
beforedone setup pi [--remove]
beforedone check
beforedone receipt [check-id]
beforedone gate
beforedone incident [--correction ] [--transcript ]
beforedone replay analyze [replay-case.json]
beforedone replay verify [replay-case.json] [--check ] [--execute]
beforedone adapter ingest [file|-]
beforedone adapter test [path]
beforedone licenses

为任何公共命令添加 --json，以获得 schema_version: 1 的机器输出。

| 代码 | 含义 |
| ---: | --- |
| 0 | 命令成功或判定为 PASS |
| 1 | 判定为 FAIL |
| 2 | 判定为 INCONCLUSIVE |
| 64 | 调用或配置错误 |
| 70 | 内部错误 |

beforedone incident 可以成功写入其产物，但仍以 1 或 2 退出，因为退出代码代表该事件的证据判定。

本地数据、隐私与保留

.beforedone.yaml 是仓库配置，通常应纳入版本控制。运行时产物位于 .git/beforedone 下，因此不会污染工作树。它们包括：

- 本地收据密钥、收据、检查日志和最新别名；
- 规范化事件账本，其中包含有界摘要，而非必需的原始记录；
- 事件 JSON、自包含 HTML 报告、Replay Cases，以及（在提供时）带有记录元数据的已脱敏有界叙述摘录。

BeforeDone 在持久化捕获的检查输出、事件摘要、重放输出、用户更正以及可选的记录摘录之前，会应用内置的密钥模式以及 capture.redact_patterns 和大小限制。内置模式涵盖敏感赋值、常见的 OpenAI/GitHub/Slack/Google 令牌形式、AWS 访问密钥 ID、PEM 私钥块以及携带凭据的 URI。脱敏仍是尽力而为，并非保证，也无法覆盖所有提供商或编码。它不会重写收据 argv 或路径元数据；切勿将凭据放入命令行参数，并在分享前审查产物。

reports.retain 会在创建新事件后修剪较旧的事件目录。在 v1 中，它不会自动修剪收据、日志或事件账本。要清除所有本地 BeforeDone 证据，请先卸载所选的 agent 集成，然后在审查路径后手动删除 .git/beforedone。仅当仓库不应再定义 BeforeDone 检查时，才单独删除 .beforedone.yaml。

CLI、Plugins、Bundle 和 Skills 不包含任何 BeforeDone 遥测、托管 API 或云账户。有关独立的网站和第三方工具边界，请参阅隐私页面。

安全与信任边界

BeforeDone 旨在在协作型或可能出错的 Agent 的完成边界处捕获缺失或过期的验证器证据。Codex 可以阻止其首次 Stop 尝试；DeepSeek Harness 可以在回合关闭前请求一次更正；Pi 可以在结算后请求一次更正。它并不是针对具有相同操作系统身份和仓库写入权限的恶意进程的安全边界。

此类进程可以读取或替换 .git/beforedone/receipt.key，编辑
.beforedone.yaml、篡改运行时产物，或运行一个轻易就能通过的允许检查。因此，它可以制造一个自洽的 PASS。回执签名会在受支持的工作流中检测损坏和不一致的产物；它不是远程证明，也无法让一个不受信任的同用户 Agent 变得诚实。

将 BeforeDone 视为一个可检查的流程护栏。当 Agent 本身处于威胁模型中时，请使用操作系统隔离、最小权限凭据、受保护的配置或外部验证器。在敌对环境中依赖回执之前，请阅读 SECURITY.md。

适配器

v1 规范化事件契约涵盖 SessionStarted、PromptSubmitted、ToolStarted、ToolFinished、AgentStopping 和 SessionEnded。Codex 和 dsh-beforedone 社区 Bundle 是受支持的完成前适配器；beforedone setup pi 提供一个 Pi 适配器，其 stop_retry 能力意味着一次结算后继续，而非结算前阻断。公开的 schema、fixture 和 beforedone adapter test 命令构成了用于未来集成的 Adapter Kit；它们的存在并不构成对其他 agent 的兼容性承诺。一个规范化事件在 JSON 编码后限制为 256 个属性和 1 MiB；本地事件账本一旦超过 64 MiB 就会以故障关闭方式读取。如果长时间运行的仓库产生大量事件，请在该边界之前审查并轮换账本。v1 写入器在每次追加之前都会重新验证已提交的段和 ID 声明；这有利于完整性而非恒定时间写入，因此如果在非常大的账本上钩子延迟开始接近配置的超时时间，请更早轮换。事件 ID 在账本内必须唯一。BeforeDone 将写入器批次存储为 .git/beforedone/events/ 下的不可变、内容寻址段，根据已提交的段元数据检查哈希 ID 索引，并拒绝缺失或重复的声明，而不是允许出现含糊的 Incident Timeline 或 Replay Case。v1 之前的 events.jsonl 会被导入一次；如果较旧的 BeforeDone 进程在迁移后继续写入该文件，读取和写入将故障关闭，直到版本不匹配问题得到解决。

升级与完全移除

所有五种交付形式共享 BeforeDone 兼容性边界。先升级 CLI，然后使用上述说明刷新所选的集成。升级后，在每个已配置的仓库中运行 beforedone doctor。

要完全移除：

1. 在 Plugins Directory 中卸载 Plugin，移除两个独立 skill 目录，运行 beforedone setup codex --remove，或运行 beforedone setup pi --remove，或运行 dsh plugin --profile  remove dsh-beforedone——取决于你选择的集成；
2. 在 macOS/Linux 上使用 command -v beforedone 定位 CLI，或在 PowerShell 中使用 Get-Command beforedone，然后移除你安装的二进制文件；
3. 在审查将要删除的内容后，可选择从每个仓库中移除 .git/beforedone 和 .beforedone.yaml；
4. 如适用，运行 codex plugin marketplace remove beforedone 以移除
Git 市场源。

贡献与许可

BeforeDone 采用 Apache-2.0 许可。与 MIT 类似，它允许商业使用、
修改和再分发，但它还为贡献者和用户提供了明确的专利许可，
并定义了贡献、NOTICE 和商标的边界。贡献使用开发者原创证书而非
CLA；使用 git commit -s 对提交进行签名。参见
CONTRIBUTING.md、SECURITY.md、
TRADEMARKS.md 和 THIRD_PARTY_NOTICES。