beforedone

1. 安装并启动 DeepSeek Harness：npx @deepseek-ai/dsh web
2. 在终端执行上面的安装命令（CLI 会解析插件并核验来源）
3. 用 dsh plugins list 确认已安装，必要时重启 Harness 生效

插件以当前 dsh 进程的权限运行，安装时可能执行代码。请先通读仓库源码与许可证，确认无破坏性命令与越权访问；本站只做索引，不对第三方插件安全性作担保。

事实信息来自公开插件目录快照（2026-10-01），介绍文案由本站再加工。

以下为插件仓库 README 全文（原始内容，由公开目录抓取整理）。

# BeforeDone

**Make coding agents prove they're done.**

BeforeDone is an open-source evidence gate and incident replay toolkit for
coding agents. It turns configured checks into receipts bound to their declared
relevant-file scope, evaluates completion through one machine-readable gate,
and reconstructs failed runs from observable events and artifacts. Codex hooks
can block the first Stop attempt; the DeepSeek Harness Bundle evaluates the
native turn-stopping boundary; and the project-local Pi extension evaluates a
settled run and can start one corrective continuation.

[Website and guide](https://rrrrrredy.github.io/beforedone/)

## Evidence and technical report

The empirical technical report freezes the protocol, 144 eligible confirmatory
outcomes, analysis, and reproducibility artifact. One superseded attempt that
produced no outcome is retained for audit and excluded from all effectiveness
denominators. Every condition observed 0/60
unsupported completions in the claim-supportable subset, so the report makes
no superiority claim; it documents the mechanism, auditability, and measured
verifier cost.

[The separate `beforedone-paper` repository](https://github.com/rrrrrredy/beforedone-paper)
contains the full protocol, run records, analysis code, and report sources. This
keeps the product checkout focused on the CLI and preserves the study against
the exact implementation it evaluated.

[Read the report and artifact](https://doi.org/10.5281/zenodo.21766277)

## One product, five delivery forms

- **CLI:** the source of truth for checks, receipts, incidents, replay, and
  adapter validation.
- **Codex Git Marketplace Plugin:** the automatic experience. It bundles the
  Stop Hook and both BeforeDone skills, while delegating all evidence decisions
  to the CLI.
- **Standalone Skills Pack:** the same two workflows without lifecycle hooks or
  Stop enforcement.
- **DeepSeek Harness community Bundle:** native session-event capture plus a
  pre-completion gate and one bounded corrective continuation.
- **Project-local Pi extension:** bounded Pi lifecycle capture plus a
  post-settlement evidence decision and one corrective continuation.

The CLI is required in every setup. For Codex, choose exactly one integration
route:

1. the Plugin for hooks plus both bundled skills;
2. the standalone Skills Pack for a manual workflow; or
3. project-local hooks from `beforedone setup codex` for the automatic gate
   without installing the Plugin.

Do not combine these routes in one Codex environment. The Plugin plus
standalone Skills duplicates the workflows; the Plugin plus project-local
hooks runs the lifecycle integration twice.

For Pi, use `beforedone setup pi`. Do not load another copy of the generated
extension in the same Pi runtime.

For DeepSeek Harness, install `dsh-beforedone` into the selected profile. Do
not combine it with another BeforeDone lifecycle adapter for the same session.

## Requirements

- A Git repository. BeforeDone resolves its local runtime through Git.
- A filesystem that supports same-directory hard links for the Git directory;
  on Windows, keep the repository on NTFS rather than FAT/exFAT removable media.
- The verifier programs named in `.beforedone.yaml`, such as `go`, `npm`, or
  `pytest`.
- Codex only if you use the Plugin, standalone Skills, or project-local hooks.
- DeepSeek Harness `0.1.0-rc.6` and Node.js 22.19+ or 24+ only if you use the
  `dsh-beforedone` community Bundle.
- A current Pi release exposing `agent_settled`, `pi.exec`, `pi.appendEntry`,
  and `pi.sendUserMessage` only if you use the Pi integration.

## 1. Install the CLI

With Go installed:

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

Alternatively, download the archive for Windows, macOS, or Linux from
[GitHub Releases](https://github.com/rrrrrredy/beforedone/releases/latest),
verify it against `checksums.txt`, and put the `beforedone` executable on
`PATH`.

To install a reproducible version with Go, replace `@latest` with a release tag,
for example `@v1.1.1`.

## 2. Initialize a repository

Run these commands from any directory inside the target Git repository:

```sh
beforedone init
beforedone doctor
```

`init` creates `.beforedone.yaml` when it is missing and initializes local
runtime data under `.git/beforedone`. It is safe to run again: an existing valid
configuration is kept.

Review the generated configuration before running checks. Commands are argv
arrays, not shell command strings:

```yaml
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
```

### Choose credible checks

A fresh Receipt proves only that the configured verifier passed for its
declared files. It does not prove that the verifier covers every acceptance
criterion. The user does not need to diagnose the exact bug, but the task still
needs observable acceptance criteria and a credible command that tests them.

`beforedone init` is a starting point, not an automatic test designer. It
recognizes a Go module and proposes `go test ./...`; for other repositories its
`git status --short` default is only scaffolding and is not correctness proof.
Review existing test, build, lint, type-check, package-script, and CI commands,
then keep the smallest set that credibly covers the task. If coverage is
missing, add a focused regression test when that change is in scope, or report
the uncovered criterion as unverified.

### Suggested Codex prompts

Configure a repository once:

```text
Help me configure BeforeDone for this repository. Inspect the existing test,
build, lint, type-check, package-script, and CI configuration. Use
`beforedone init` only as a starting point. Configure the smallest credible set
of existing commands, include every file class that can affect each check, and
report assumptions and coverage gaps. Do not add dependencies, use
`git status --short` as proof of correctness, or invent a check merely to get
PASS.
```

Verify a task:

```text
Use BeforeDone for this task. Turn my request into observable acceptance
criteria, map them to existing tests or checks, and add the smallest regression
test when coverage is missing and that change is within scope. Before saying
done, run every required BeforeDone check and confirm fresh PASS receipts for
the current files. If any criterion lacks credible evidence, report it as
unverified instead of calling it PASS. Do not weaken checks merely to obtain
PASS.
```

These prompts help Codex propose and apply the verification contract; they do
not turn natural-language confidence into a Receipt. Review `.beforedone.yaml`
before relying on it.

Do not place credentials in verifier command-line arguments or sensitive names
in verifier paths. Evidence receipts intentionally preserve the actual argv and
working-directory metadata so a reviewer can see what ran; those structural
fields are not rewritten by output redaction. Use environment-based or native
credential mechanisms, and review receipt/report metadata before sharing it.

Run a configured check through BeforeDone, then inspect its effective result:

```sh
beforedone check test
beforedone receipt test
```

Evaluate every required receipt without running a verifier:

```sh
beforedone gate
beforedone gate --json
```

The gate returns both a `decision` and an evidence `verdict`. Missing, failed,
invalid, or stale required evidence blocks completion. A verifier receipt that
is itself `INCONCLUSIVE` preserves the existing non-blocking warning behavior:
the decision is `allow`, the verdict and process exit remain `INCONCLUSIVE`,
and `system_message` explains the uncertainty. Adapters must read `decision`;
they must not infer it from the exit code alone.

A successful process creates a `PASS` receipt for the current relevant-file
fingerprint. Changing a relevant file makes that receipt stale; changing a file
outside the check's configured patterns does not. A word such as `PASS` in
ordinary command output never overrides a non-zero process exit.

Relevant globs also include matching Git-ignored files such as generated Go
sources, and the fingerprint includes executable-mode changes. Git applies the
ignored-file pathspec before BeforeDone streams results, with hard file-count,
listing-size, and content-size limits; exceeding a limit fails closed instead
of silently omitting evidence. Submodule contents are not fingerprinted in v1:
if a `relevant_files` pattern may cover a Git submodule or a path below it, the
check fails closed instead of issuing reusable evidence.

## 3. Choose an agent integration

### Route A: Codex Git Marketplace Plugin

The Git Marketplace Plugin includes the Stop Hook and both skills. Install the
CLI first, then add the public Git marketplace:

```sh
codex plugin marketplace add rrrrrredy/beforedone
```

Restart the ChatGPT desktop app, open the Plugins Directory in Codex, select the
`beforedone` marketplace source, open BeforeDone, and choose **Install**. Then
open `/hooks`, review and trust the BeforeDone hooks, and start a new task so the
bundled skills are available. The Plugin does not download or update the CLI
silently; a missing executable produces an actionable error.

To update this route:

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

Then open BeforeDone in the Codex Plugins Directory and apply the offered
update. If that surface does not offer an in-place update, uninstall and
install the Plugin again from the refreshed marketplace.

To remove this route, open BeforeDone in the Codex Plugins Directory and select
**Uninstall plugin**. If you no longer want the repository marketplace either,
remove that source separately:

```sh
codex plugin marketplace remove beforedone
```

Removing the marketplace source is not a substitute for uninstalling the
Plugin in the Plugins Directory.

### Route B: standalone Skills Pack

Choose this route instead of the Plugin. It installs the same workflows but
cannot observe lifecycle events or enforce a Stop Gate.

Ask Codex to run the built-in skill installer once for each exact path:

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

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

The skills become available on the next Codex turn. To pin them to v1.1.1,
replace `/tree/main/` with `/tree/v1.1.1/` in both URLs.

You can also install both through the third-party `skills.sh` CLI. BeforeDone
itself has no telemetry, but `skills.sh` is a separate tool and may collect its
own usage data. Disable that installer telemetry explicitly if desired:

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

PowerShell:

```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
```

To update skills installed by `$skill-installer`, remove or back up only
`verify-before-done` and `investigate-agent-incident` from `$CODEX_HOME/skills`
(by default `~/.codex/skills`), rerun the two install prompts, and start a new
turn. To uninstall this route, remove only those same two directories.

If you used `skills.sh`, keep using that installer for lifecycle management:

```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
```

### Route C: project-local Codex hooks

Choose this route instead of the Plugin and standalone Skills. It writes the
BeforeDone lifecycle handlers to the current repository's `.codex/hooks.json`
and pins them to the absolute CLI executable found during setup:

```sh
beforedone setup codex
```

Open `/hooks`, review and trust the project hooks, then start a new task. If the
CLI path changes during an upgrade, rerun `beforedone setup codex`. Remove only
the BeforeDone project hooks with:

```sh
beforedone setup codex --remove
```

### DeepSeek Harness: community Bundle

Install BeforeDone CLI `v1.1.1` or newer, initialize the target repository,
then add the Bundle to the Harness profile you use:

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

The Bundle subscribes to the native append-only session log, flushes normalized
metadata through the Adapter Kit, and runs `beforedone gate --json` at
`agent/turn-stopping`. A blocking or unsafe result becomes one durable steering
message. The next stop is reevaluated, but the same turn is never forced more
than once.

Prompt text, reasoning, tool arguments, and tool output are not copied into
`.git/beforedone`; the normalized ledger contains the local session working
directory, lifecycle identifiers, message source/plugin names, tool names, and
result status. Missing CLI support, timeouts, truncated output, partial
ingestion, and damaged JSON fail loud instead of becoming an implicit success.

Full compatibility, configuration, test, privacy, and removal instructions are
in [`integrations/deepseek-harness/README.md`](integrations/deepseek-harness/README.md).
This is a community plugin, not an official DeepSeek plugin.

### Pi: project-local extension

Run this instead when the repository is used through Pi:

```sh
beforedone setup pi
```

The command writes `.pi/extensions/beforedone.ts` and pins it to the absolute
BeforeDone executable found during setup. Review the file, approve Pi's
project-trust prompt, and start a new Pi session. Rerun setup if the CLI path
changes; remove only this generated extension with:

```sh
beforedone setup pi --remove
```

The extension records `session_start`, input metadata, tool start/finish,
`agent_settled`, and `session_shutdown` through the normalized Adapter contract.
It deliberately does not persist prompt text, tool arguments, tool output, or a
raw transcript. Its branch-aware custom entry permits at most one automatic
correction. Interactive or RPC input resets the guard; extension-originated
input shares the existing guard.

Pi exposes `agent_settled` after its automatic retry, compaction, and queued
continuation paths are exhausted. That makes the integration useful for a
corrective follow-on, but it is not equivalent to Codex's pre-completion Stop
hook: the first unsupported final message may already be visible before
BeforeDone sends the corrective user message. The one-retry guard then allows
the next settled result without creating an infinite loop.

## Incidents and replay

Create a self-contained HTML report, machine-readable JSON, and Replay Case
from the current repository evidence:

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

The report contains a timeline, Claim/Evidence Matrix, missing or stale
evidence, and the earliest divergence supported by the available evidence. Its
precision is exactly one of `exact_event`, `time_window`, or `unlocated`.
An exact event requires an explicit match to a verified failing Receipt; a time
window must be bounded by observed events around that check. Generic non-zero
tool exits and later user corrections do not manufacture a location. BeforeDone
does not recover hidden reasoning or chain of thought.

An optional transcript is unstable narrative context, not a trust source and
not an input to First Observable Divergence. BeforeDone accepts at most 4 MiB,
applies redaction, and stores only a bounded 16 KiB narrative excerpt plus its
SHA-256 digest and a truncation flag; it does not copy the raw transcript into
the incident.

Replay analysis never runs an external command:

```sh
beforedone replay analyze
```

Verification is also a dry run by default. It displays a plan sourced only from
the current repository configuration; argv found in an imported Replay Case is
ignored:

```sh
beforedone replay verify
beforedone replay verify --check test
```

Only an explicit `--execute` runs configured checks in a temporary detached Git
worktree:

```sh
beforedone replay verify --check test --execute
```

BeforeDone disables repository Git hooks while it creates that internal
worktree. The configured verifier still runs normally after checkout.

BeforeDone does not provide network isolation. A configured verifier can use
the network, credentials, and other resources available to that process. Replay
captures verifier output through the configured `capture.max_output_bytes`
limit before redaction and report truncation, so an unbounded verifier cannot
create an unbounded in-memory result.

## Commands and exit codes

```text
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
```

Add `--json` to any public command for `schema_version: 1` machine output.

| Code | Meaning |
| ---: | --- |
| `0` | command succeeded or verdict is `PASS` |
| `1` | verdict is `FAIL` |
| `2` | verdict is `INCONCLUSIVE` |
| `64` | invocation or configuration error |
| `70` | internal error |

`beforedone incident` can successfully write its artifacts and still exit `1`
or `2`, because the exit code represents the incident's evidence verdict.

## Local data, privacy, and retention

`.beforedone.yaml` is repository configuration and normally belongs in version
control. Runtime artifacts live under `.git/beforedone` so they do not pollute
the working tree. They include:

- the local receipt key, receipts, check logs, and latest aliases;
- a normalized event ledger containing bounded summaries rather than a required
  raw transcript;
- incident JSON, self-contained HTML reports, Replay Cases, and—when supplied—a
  redacted bounded narrative excerpt with transcript metadata.

BeforeDone applies built-in secret patterns plus `capture.redact_patterns` and
size limits before persisting captured check output, event summaries, replay
output, user corrections, and the optional transcript excerpt. Built-ins cover
sensitive assignments, common OpenAI/GitHub/Slack/Google token forms, AWS access
key IDs, PEM private-key blocks, and credential-bearing URIs. Redaction remains
best effort, not a guarantee, and cannot cover every provider or encoding. It
does not rewrite receipt argv or path metadata; never put credentials in
command-line arguments, and review artifacts before sharing them.

`reports.retain` prunes older incident directories after a new incident is
created. In v1 it does not automatically prune receipts, logs, or the event
ledger. To erase all local BeforeDone evidence, first uninstall the selected
agent integration, then manually remove `.git/beforedone` after reviewing the
path. Remove `.beforedone.yaml` separately only if the repository should no
longer define BeforeDone checks.

The CLI, Plugins, Bundle, and Skills contain no BeforeDone telemetry, hosted
API, or cloud account. See the [privacy page](https://rrrrrredy.github.io/beforedone/privacy.html)
for the separate website and third-party-tool boundaries.

## Security and trust boundary

BeforeDone is designed to catch missing or stale verifier evidence at a
cooperative or fallible Agent's completion boundary. Codex can block its first
Stop attempt; DeepSeek Harness can request one correction before the turn
closes; Pi can request one correction after settlement. It is not a security
boundary against a malicious process with the same operating-system identity
and repository write access.

Such a process can read or replace `.git/beforedone/receipt.key`, edit
`.beforedone.yaml`, alter runtime artifacts, or run a trivially passing allowed
check. It can therefore manufacture a self-consistent `PASS`. Receipt signing
detects corruption and inconsistent artifacts within the supported workflow;
it is not remote attestation and does not make an untrusted same-user Agent
honest.

Treat BeforeDone as an inspectable process guardrail. Use OS isolation,
least-privilege credentials, protected configuration, or an external verifier
when the Agent itself is inside the threat model. Read [SECURITY.md](SECURITY.md)
before relying on receipts in a hostile environment.

## Adapters

The v1 normalized event contract covers `SessionStarted`, `PromptSubmitted`,
`ToolStarted`, `ToolFinished`, `AgentStopping`, and `SessionEnded`. Codex and
the `dsh-beforedone` community Bundle are supported pre-completion adapters;
`beforedone setup pi` supplies a Pi adapter whose `stop_retry` capability means
one post-settlement continuation, not a pre-settlement block. The public
schemas, fixtures, and `beforedone adapter test` command form an Adapter Kit
for future integrations; their presence is not a compatibility promise for
other agents. A normalized event is limited to
256 attributes and 1 MiB after JSON encoding; the local
event ledger is read fail-closed once it exceeds 64 MiB. Review and rotate the
ledger before that boundary if a long-running repository produces many events.
The v1 writer revalidates committed segments and ID claims before every append;
this favors integrity over constant-time writes, so rotate earlier if hook
latency starts approaching the configured timeout on a very large ledger.
Event IDs must be unique within the ledger. BeforeDone stores writer batches as
immutable, content-addressed segments under `.git/beforedone/events/`, checks
the hashed-ID index against committed segment metadata, and rejects missing or
duplicate claims instead of allowing an ambiguous Incident Timeline or Replay
Case. A pre-v1 `events.jsonl` is imported once; if an older BeforeDone process
continues writing that file after migration, reads and writes fail closed until
the version mismatch is resolved.

## Upgrade and complete removal

All five delivery forms share the BeforeDone compatibility boundary. Upgrade the CLI first, then
refresh the selected integration using the instructions above. Run `beforedone
doctor` in each configured repository after upgrading.

For a complete removal:

1. uninstall the Plugin in the Plugins Directory, remove the two standalone
   skill directories, run `beforedone setup codex --remove`, or run
   `beforedone setup pi --remove`, or run
   `dsh plugin --profile  remove dsh-beforedone`—whichever integration
   you selected;
2. locate the CLI with `command -v beforedone` on macOS/Linux or
   `Get-Command beforedone` in PowerShell, then remove the binary you installed;
3. optionally remove `.git/beforedone` and `.beforedone.yaml` from each
   repository after reviewing what will be deleted;
4. if applicable, run `codex plugin marketplace remove beforedone` to remove the
   Git marketplace source.

## Contributing and license

BeforeDone is licensed under Apache-2.0. Like MIT, it allows commercial use,
modification, and redistribution, but it also gives contributors and users an
explicit patent license and defines contribution, NOTICE, and trademark
boundaries. Contributions use the Developer Certificate of Origin rather than
a CLA; sign commits with `git commit -s`. See
[CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md),
[TRADEMARKS.md](TRADEMARKS.md), and [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES).