In DSH plugin development and agent workflows, distinguishing between “intent” and “completion” is a core challenge. The butler-git plugin uses Git’s native mechanisms to decouple “what I want to change (a node)” from “what I have changed (a commit)”, and enforces consistency between the two through gates.

Plugin Positioning

Core value: A node is intent, and a commit is evidence. A commit is produced only when the expected changes (\(\Delta\)) and the verification program (\(P\)) all pass.

Basic information:
* Name: hercules-debug/butler-git
* Maintainer: Hercules-debug
* Category: Workflow
* License: MIT

Core Features

1. Separation of Nodes and Evidence

The plugin maintains an “intent tree”. Nodes are first declared as intents; a commit is generated as evidence only when the fulfillment conditions are met. The relationship between the two is not equality, but fulfillment.

2. Zero-Dependency Gate

The gate mechanism does not depend on external environments; it uses only node and git.
* Delta (\(\Delta\)): Expected changes, a precise set, including direction (M/A/D/R).
* Program (\(P\)): Verification program; it executes one command, and exit code 0 counts as passing.
* Commit rule: The commit command pins the working tree as a tree, compares it against \(\Delta\), and executes \(P\). History is written only if everything passes.

3. Permissions and Freeze

  • Credential system: Credentials are used to escalate permissions to the creator (downward, including all descendants). The credential plaintext appears only once during creation; afterward, only its hash is stored.
  • Freeze mechanism: Fulfilled nodes (those with a commit) are immutable; no credential can modify them, and history cannot be rewritten.

4. Visualization and Audit

  • DAG graph: Generates a Mermaid-layout DAG graph, displaying the parent-child relationships of intents and the parent-child relationships in Git.
  • Evidence chain: Commit trailers record evidence (such as bg-verified-tree) to prevent tampering. Even if the graph is lost, bg recheck can scan history to detect tampering.

Usage

The plugin provides CLI commands to manage these intents and gates.

Definition and Commit

In a Git repository, use node bin/bg.mjs as the entry point:

# 1. 定义意图（节点）
# --expect: 描述
# --base: 基准提交
# --verify: 验证命令
# --delta: 预期改动（M:修改, A:新增, D:删除）
node bin/bg.mjs plan \
  --id n7 \
  --expect "让导出支持非 ASCII" \
  --base <commit-hash> \
  --verify "pytest -q" \
  --delta "M:src/csv.py" \
  --delta "A:src/enc.py"

# 2. 查看状态（不跑 P，只对比改动）
node bin/bg.mjs status n7

# 3. 提交（触发门禁：Delta + P）
node bin/bg.mjs commit n7

Human-facing Interface and Diagnostics

# 查看意图树（包含灯、状态、弱 P 标记）
node bin/bg.mjs tree

# 生成 HTML 可视化（需要联网，从 CDN 获取 Mermaid）
node bin/bg.mjs html

# 启动实时查看器
node bin/bg.mjs serve

# 对当前 commit 复查历史节点（诊断工具）
node bin/bg.mjs recheck

Applicable Scenarios and Notes

  • Applicable scenarios: Scenarios that require strict verification of agent-produced work. Suitable for projects that are highly sensitive to “unexpected changes”.
  • Notes:
    • The bg html command depends on the network to load the Mermaid library. When offline, the page will report an error, but the information in the graph is listed as plain text, and the gate logic is not affected.
    • Running the plugin itself depends on the DeepSeek Harness environment (peerDependencies points to @deepseek-ai/cordis and @deepseek-ai/dsh-tools).
    • Any commit that includes a bg-node trailer is treated as having passed through the gate; commits without this trailer are treated as bypassing it and are marked in the tree view.

Conclusion

butler-git uses Git’s immutability and trailer mechanisms to solidify the verification of code changes into facts. It does not promise “overall usability”; instead, it pushes verification granularity down to every intent node, turning “I have finished changing it” into truly replayable and auditable evidence.