bound

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BOUND

Use BOUND after meaningful execution steps to decide whether the agent should continue, retry, replan, or roll back. BOUND evaluates completed work; it does not decide what code to write.

在完成有意义的执行步骤后使用BOUND，以此决定Agent应继续、重试、重新规划还是回滚。BOUND用于评估已完成的工作，不负责决定编写何种代码。

Agent integration types

Agent集成类型

All BOUND agent integrations are instruction-only — they are prompts that the agent reads and follows. There are no enforced integrations (no programmatic hooks into the agent's event system, MCP servers, rules, or lifecycle events). Every integration relies on the agent to voluntarily follow the instructions and act on BOUND's decisions.

Agent	File	Type	Mechanism
Cline	`integrations/cline/INSTALL_BOUND.md`	Instruction-only	Prompt-based; agent follows instructions
Codex	`integrations/codex/INSTALL_BOUND.md`	Instruction-only	Prompt-based; agent follows instructions
Claude Code	`integrations/claude-code/INSTALL_BOUND.md`	Instruction-only	Prompt-based; agent follows instructions
Hermes Agent	`integrations/hermes-agent/INSTALL_BOUND.md`	Instruction-only	Prompt-based; agent follows instructions
Kilo Code	`integrations/kilo-code/INSTALL_BOUND.md`	Instruction-only	Prompt-based; agent follows instructions
Generic	`integrations/generic/INSTALL_BOUND.md`	Instruction-only	Prompt-based; any agent follows instructions

Key distinction: Instruction-only integrations describe the BOUND control loop and instruct the agent to manually call BOUND's CLI or Python API at each boundary. The agent is responsible for acting on the decision — BOUND does not enforce the action. Enforced integrations (future) would hook into the agent's event system to intercept decisions before they reach the agent.

所有BOUND Agent集成均为仅指令型——即供Agent阅读并遵循的提示词。不存在强制集成（无针对Agent事件系统、MCP服务器、规则或生命周期事件的编程钩子）。所有集成均依赖Agent自愿遵循指令并根据BOUND的决策采取行动。

Agent	文件	类型	机制
Cline	`integrations/cline/INSTALL_BOUND.md`	仅指令型	基于提示词；Agent遵循指令
Codex	`integrations/codex/INSTALL_BOUND.md`	仅指令型	基于提示词；Agent遵循指令
Claude Code	`integrations/claude-code/INSTALL_BOUND.md`	仅指令型	基于提示词；Agent遵循指令
Hermes Agent	`integrations/hermes-agent/INSTALL_BOUND.md`	仅指令型	基于提示词；Agent遵循指令
Kilo Code	`integrations/kilo-code/INSTALL_BOUND.md`	仅指令型	基于提示词；Agent遵循指令
Generic	`integrations/generic/INSTALL_BOUND.md`	仅指令型	基于提示词；任意Agent均可遵循指令

核心区别：仅指令型集成描述BOUND控制循环，并指示Agent在每个边界手动调用BOUND的CLI或Python API。Agent负责执行决策——BOUND不会强制行动。未来的强制集成将接入Agent的事件系统，在决策传递给Agent之前进行拦截。

Inspect before integrating

集成前检查

Install the latest stable package into the project's environment:
bash
```
pip install bound-policy
```

Inspect the installed API instead of relying on remembered signatures:

bash

python -c "import bound; print(bound.__version__); print(bound.__all__)"
bound integration-spec

Confirm the project's real test, lint, type-check, and build commands.
Inspect the agent's actual hooks, modes, instructions, commands, task boundaries, telemetry, and checkpoint support. Do not invent a native BOUND integration or an undocumented framework mechanism.
Find existing
```
INTEGRATION.md
```
,
```
INTEGRATION_REPORT.md
```
,
```
PLAN.md
```
, and
```
bound_integration/
```
files. Treat recorded results as claims to reproduce, not authoritative evidence.

将最新稳定包安装到项目环境中：
bash
```
pip install bound-policy
```

检查已安装的API，而非依赖记忆中的签名：

bash

python -c "import bound; print(bound.__version__); print(bound.__all__)"
bound integration-spec

确认项目真实的测试、代码检查、类型检查和构建命令。
检查Agent实际的钩子、模式、指令、命令、任务边界、遥测和 checkpoint 支持。不要虚构原生BOUND集成或未文档化的框架机制。
查找现有的
```
INTEGRATION.md
```
、
```
INTEGRATION_REPORT.md
```
、
```
PLAN.md
```
和
```
bound_integration/
```
文件。将记录的结果视为需要复现的声明，而非权威证据。

Establish execution lineage

建立执行谱系

For multi-step work, maintain

PLAN.md

at the repository root. A small one-step task may use an inline plan. Give each meaningful phase a stable id and define its goal, observable acceptance checks, risk checks, verification commands, budget, expected artifacts, owner, and dependencies where relevant.

Maintain this lineage:

text

intent -> plan phase -> StepContract -> execution -> ExecutionEvidence
       -> BOUND evaluation -> control action -> integration report

Preserve a phase after execution. When the strategy changes materially, create a derived id such as

PHASE-002-R1

; do not rewrite history to hide a replan.

对于多步骤工作，在仓库根目录维护

PLAN.md

。小型单步骤任务可使用内联计划。为每个有意义的阶段分配稳定ID，并定义其目标、可观察的验收检查、风险检查、验证命令、预算、预期产物、负责人及相关依赖项（如有）。

维护以下谱系：

text

意图 -> 计划阶段 -> StepContract -> 执行 -> ExecutionEvidence
       -> BOUND评估 -> 控制行动 -> 集成报告

执行后保留阶段信息。当策略发生重大变化时，创建衍生ID（如

PHASE-002-R1

）；不要重写历史以隐藏重新规划的操作。

Choose meaningful boundaries

选择有意义的边界

Call BOUND after implementation plus verification, after a focused retry, and before deciding to keep refining the same objective. Do not call it after each token, file read, shell command, or low-level tool call.

Each boundary must have observable completion criteria. Combine or redefine a step when no meaningful success or risk signal can be observed.

在实现加验证后、聚焦重试后，以及决定是否继续优化同一目标前调用BOUND。不要在每个token、文件读取、shell命令或低级工具调用后调用它。

每个边界必须具备可观察的完成标准。当无法观察到有意义的成功或风险信号时，合并或重新定义步骤。

Report the proposal before modifying the project

修改项目前提交方案报告

Record these headings before implementation:

text

Integration point:
Step boundary:
Available evidence:
Missing evidence:
Control-flow mapping:
Files to modify:

List exact verification commands and the small, removable set of integration files. Represent unavailable metrics as unavailable rather than estimating them.

在实现前记录以下标题内容：

text

集成点:
步骤边界:
可用证据:
缺失证据:
控制流映射:
待修改文件:

列出确切的验证命令和少量可移除的集成文件。将不可用的指标标记为不可用，而非估算。

Build contracts and evidence

构建合约与证据

Map each phase to a

StepContract

with at least one

AcceptanceCheck

, optional

RiskCheck

s, expected artifacts, and a

StepBudget

. Collect

ExecutionEvidence

only from observations made during the run: command exit codes, check results, changed artifacts, retries, tool calls, tokens, runtime, and rollback availability when exposed.

Keep

check_id

values aligned between contract and evidence. Missing evidence for a required check is not a pass. Distinguish an unset budget (

None

), an unavailable measurement, and an observed zero.

Prefer the installed

evaluate_agent_step(...)

helper when its inspected API provides it. Otherwise call

BoundWorkflow.evaluate_step(...)

and use exactly:

text

ACCEPT   -> continue
RETRY    -> retry
REPLAN   -> replan
ROLLBACK -> rollback

Never add a fifth action or reproduce BOUND's scoring and decision formula.

将每个阶段映射到一个

StepContract

，其中至少包含一个

AcceptanceCheck

、可选的

RiskCheck

、预期产物和

StepBudget

。仅收集运行期间观察到的

ExecutionEvidence

：命令退出码、检查结果、变更的产物、重试记录、工具调用、token数、运行时，以及暴露的回滚可用性。

保持合约与证据中的

check_id

值一致。必填检查的缺失证据不算通过。区分未设置的预算（

None

）、不可用的测量值和观察到的零值。

如果已安装的

evaluate_agent_step(...)

辅助函数可用，则优先使用。否则调用

BoundWorkflow.evaluate_step(...)

并严格使用以下映射：

text

ACCEPT   -> 继续
RETRY    -> 重试
REPLAN   -> 重新规划
ROLLBACK -> 回滚

绝不要添加第五种操作，也不要复现BOUND的评分和决策公式。

Verified evidence & provenance (v0.7.0)

已验证证据与来源（v0.7.0）

BOUND v0.7.0 separates who reports evidence from who verifies it. The agent is a participant, not the judge.

Define the contract upfront, including provenance requirements. Each
```
AcceptanceCheck
```
/
```
RiskCheck
```
may declare
```
accepted_provenance
```
(which trust provenances it accepts),
```
on_missing
```
,
```
on_claimed
```
, and — for risk checks —
```
decision_critical
```
(missing/claimed evidence then forces
```
INSUFFICIENT
```
assurance and blocks a clean
```
ACCEPT
```
).
Configure allowed collectors; BOUND performs objective verification. Use the BOUND collectors (
```
PytestCollector
```
,
```
GitCollector
```
,
```
JUnitCollector
```
,
```
BudgetCollector
```
,
```
ProcessRuntimeCollector
```
,
```
CommandCollector
```
, plus native
```
RuffEvidence
```
,
```
MypyEvidence
```
,
```
CoverageEvidence
```
) to execute verification BOUND controls. They record
```
evidence.collected
```
audit events with
```
VERIFIED
```
/
```
OBSERVED
```
provenance, a collector name/version, artefact hash and a timezone-aware timestamp. A collector crash or stale artefact is recorded honestly (
```
evidence.collection_failed
```
/
```
INVALID
```
), never a verified pass.
The agent CANNOT assign
VERIFIED
provenance. Agent self-report is always
```
CLAIMED
```
, never
```
VERIFIED
```
/
```
OBSERVED
```
. The agent must not override or suppress a collector result.
```
MISSING
```
means "not collected" — never silently
```
0
```
;
```
None
```
on a telemetry metric is missing, not a measured zero.
Subjective criteria use a separate evaluator (
EVALUATED
). Criteria that cannot be independently re-run (e.g. UX quality) are
```
EVALUATED
```
— honest but never
```
VERIFIED
```
.
BOUND logs what the agent reports; the agent executes control actions. BOUND records
```
action.reported
```
(
```
reported_provenance=CLAIMED
```
); an independent hook may add
```
observed_action
```
to confirm it. The agent executes control actions. BOUND is a thin harness: it emits
```
ROLLBACK
```
and may independently verify the resulting state. It can roll back the workspace with explicit
```
bound rollback --execute
```
against a previously confirmed checkpoint, but never without explicit opt-in.

Assurance gates the candidate decision. BOUND computes a

DecisionAssurance

(

VERIFIED

MIXED

CLAIMED

INSUFFICIENT

) from the decision-critical checks' provenance. A candidate

ACCEPT

backed only by

CLAIMED

MISSING

critical evidence is downgraded to the contract's

on_missing

on_claimed

action. Inspect it:

bash

bound inspect <run_id>                  # per-check provenance + candidate vs final + assurance + coverage
bound inspect <run_id> --only-unverified # only unverified/claimed/missing/invalid evidence
bound inspect <run_id> --json           # machine-readable: provenance + assurance + coverage

BOUND v0.7.0区分了报告证据的主体和验证证据的主体。Agent是参与者，而非裁判。

**提前定义合约，包括来源要求。**每个
```
AcceptanceCheck
```
/
```
RiskCheck
```
可声明
```
accepted_provenance
```
（接受的信任来源）、
```
on_missing
```
、
```
on_claimed
```
，以及针对风险检查的
```
decision_critical
```
（缺失/声明的证据会导致
```
INSUFFICIENT
```
保证，并阻止干净的
```
ACCEPT
```
决策）。
**配置允许的收集器；BOUND执行客观验证。**使用BOUND收集器（
```
PytestCollector
```
、
```
GitCollector
```
、
```
JUnitCollector
```
、
```
BudgetCollector
```
、
```
ProcessRuntimeCollector
```
、
```
CommandCollector
```
，以及原生的
```
RuffEvidence
```
、
```
MypyEvidence
```
、
```
CoverageEvidence
```
）执行BOUND控制的验证。它们会记录带有
```
VERIFIED
```
/
```
OBSERVED
```
来源、收集器名称/版本、产物哈希和时区感知时间戳的
```
evidence.collected
```
审计事件。收集器崩溃或过期产物会被如实记录（
```
evidence.collection_failed
```
/
```
INVALID
```
），绝不会被标记为已验证通过。
**Agent无法分配
```
VERIFIED
```
来源。**Agent的自我报告始终为
```
CLAIMED
```
，而非
```
VERIFIED
```
/
```
OBSERVED
```
。Agent不得覆盖或抑制收集器的结果。
```
MISSING
```
表示“未收集”——绝不要默认为
```
0
```
；遥测指标中的
```
None
```
表示缺失，而非测量得到的零值。
**主观标准使用独立评估器（
```
EVALUATED
```
）。**无法独立重新运行的标准（如UX质量）标记为
```
EVALUATED
```
——诚实但绝非
```
VERIFIED
```
。
**BOUND记录Agent报告的内容；Agent执行控制行动。**BOUND记录
```
action.reported
```
（
```
reported_provenance=CLAIMED
```
）；独立钩子可添加
```
observed_action
```
以确认行动。**Agent负责执行控制行动。**BOUND是一个轻量框架：它发出
```
ROLLBACK
```
指令，并可独立验证最终状态。它可以通过显式的
```
bound rollback --execute
```
命令针对先前确认的checkpoint回滚工作区，但绝不会在无显式 opt-in 的情况下执行。

**保证机制约束候选决策。**BOUND从决策关键检查的来源计算

DecisionAssurance

（

VERIFIED

MIXED

CLAIMED

INSUFFICIENT

）。仅由

CLAIMED

MISSING

关键证据支持的候选

ACCEPT

决策会降级为合约中

on_missing

on_claimed

指定的行动。可通过以下命令检查：

bash

bound inspect <run_id>                  # 按检查项展示来源 + 候选vs最终决策 + 保证级别 + 覆盖范围
bound inspect <run_id> --only-unverified # 仅展示未验证/声明/缺失/无效的证据
bound inspect <run_id> --json           # 机器可读格式：来源 + 保证级别 + 覆盖范围

Persist the numeric evaluation

持久化数值评估结果

For every evaluation, read the numbers from the returned BOUND object and emit:

text

BOUND evaluation
Acceptance (A): <4 decimals>
Influence (I): <4 decimals>
Risk (R): <4 decimals>
Cost (C): <4 decimals>
Score (S): <4 decimals>
Threshold (T): <4 decimals>
Decision: <ACCEPT|RETRY|REPLAN|ROLLBACK>
Next action: <continue|retry|replan|rollback>

Also persist exposed weights, weighted components, retry margin, rollback-risk threshold, and score provenance. Read

references/integration-report.md

for the required report structure.

每次评估时，从返回的BOUND对象中读取数值并输出：

text

BOUND评估结果
验收值 (A): <保留4位小数>
影响值 (I): <保留4位小数>
风险值 (R): <保留4位小数>
成本值 (C): <保留4位小数>
评分 (S): <保留4位小数>
阈值 (T): <保留4位小数>
决策: <ACCEPT|RETRY|REPLAN|ROLLBACK>
下一步行动: <继续|重试|重新规划|回滚>

同时持久化暴露的权重、加权组件、重试余量、回滚风险阈值和评分来源。参考

references/integration-report.md

获取所需的报告结构。

Validate earlier scores

验证历史评分

When an earlier integration record exists, compare its contract, evidence, criteria, budgets, scores, decision, and action with the current run. When its inputs are complete, reconstruct them and call BOUND again. Compare returned A/I/R/C/S/T, decision, and action with the record.

Mark incomplete historical results
```
not reproducible
```
and list missing data.
Mark evaluations
```
stale
```
when evidence or configuration changed.
Append a new evaluation instead of silently overwriting history.
Treat a mismatch as a failed consistency check and investigate it before continuing.
Do not independently implement the formula as a second evaluator.

当存在早期集成记录时，将其合约、证据、标准、预算、评分、决策和行动与当前运行结果进行比较。当历史输入完整时，重构输入并再次调用BOUND。将返回的A/I/R/C/S/T、决策和行动与记录进行对比。

将不完整的历史结果标记为
```
不可复现
```
，并列出缺失的数据。
当证据或配置发生变化时，将评估结果标记为
```
过期
```
。
添加新的评估结果，而非静默覆盖历史记录。
将不匹配视为一致性检查失败，在继续前进行调查。
不要独立实现公式作为第二个评估器。

React to the result

响应评估结果

```
ACCEPT
```
: stop refining this phase and continue.
```
RETRY
```
: preserve the strategy, make one focused correction, collect fresh evidence, and re-evaluate within the budget.
```
REPLAN
```
: stop the current strategy, choose a materially different approach, and create a derived contract id.
```
ROLLBACK
```
: restore only a previously confirmed safe checkpoint without discarding unrelated or pre-existing changes, then replan. If no safe checkpoint exists, report that and avoid a destructive approximation.

```
ACCEPT
```
：停止优化当前阶段并继续。
```
RETRY
```
：保留当前策略，进行一次聚焦修正，收集新证据，并在预算内重新评估。
```
REPLAN
```
：停止当前策略，选择差异显著的方法，并创建衍生合约ID。
```
ROLLBACK
```
：仅恢复先前确认的安全checkpoint，不丢弃无关或预先存在的变更，然后重新规划。如果没有安全checkpoint，需如实报告，避免破坏性的近似操作。

Record decision lineage (v0.7.0)

记录决策谱系（v0.7.0）

BOUND v0.7.0 can record every evaluation as a reproducible, append-only local lineage —

contract → evidence → scores → decision → agent outcome

— under

.bound/runs/<run_id>/

. It is opt-in per run and backwards compatible: if you never start a run, nothing is recorded. Disable it with

BOUND_LINEAGE_DISABLED=1

For any non-trivial task you evaluate with BOUND, follow these rules:

Start ONE run per task.

bash

bound run start "<task>" --metadata phase=PHASE-001

(In Python:

with bound.start_run("<task>") as run:

Use STABLE step/contract ids. Carry the same id from
```
PLAN.md
```
→
```
StepContract(id=...)
```
→ lineage. A replan of the same step appends
```
-R<N>
```
(
```
PHASE-001
```
→
```
PHASE-001-R1
```
); never invent an unrelated id or rewrite history to hide a replan.

Evaluate only MEANINGFUL boundaries (after implementation + verification, not after every token/file/command), and record the evaluation into the run:

bash

bound evaluate --run <run_id> --step PHASE-001 --attempt 1 \
    --action "..." --goal "..." \
    --acceptance A --influence I --risk R --cost C \
    --threshold 0.7 --retry-margin 0.1

This writes

step_started

evaluation_recorded

and adds a

lineage

block to the JSON.

Record the REAL follow-up action you actually took — not what BOUND "should" have produced:

bash

bound outcome --run <run_id> --step PHASE-001 --attempt 1 \
    --decision REPLAN --note "switched strategy to validator + parametrized tests"

--next-action

and

--reason-code

are derived from

--decision

(

ACCEPT|RETRY|REPLAN|ROLLBACK

) when omitted.

Explicitly CLOSE the run when the task ends:
bash
```
bound run finish <run_id> --status completed|interrupted|failed --note "..."
```
A missing
```
run_finished
```
marks an incomplete/crashed run (the log stays readable). If you used
```
with bound.start_run(...)
```
the context manager auto-finishes an interrupted run on exit.
REPORT the local lineage path —
```
.bound/runs/<run_id>/
```
(
```
run.json
```
+ the append-only
```
events.jsonl
```
) — and show the decision tree:
bash
```
bound inspect <run_id>
```

The canonical flow is one run, two attempts:

text

Attempt 1  →  evidence 1/3 (A=0.3333)  →  REPLAN  → switch strategy
            (new step PHASE-001-R1, attempt 2)
Attempt 2  →  evidence 3/3 (A=1.0000)  →  ACCEPT  → continue to next step

The event log is append-only: a replan emits a new

step_started

with

attempt+1

and a

-R<N>

-suffixed contract id; earlier attempts are never rewritten. Prompts, tokens, and source code are never stored — only the contract id, scores, threshold, decision, reason code, and your follow-up action/note. See

docs/lineage.md

for the full data model and API.

BOUND v0.7.0可将每次评估记录为可复现、仅追加的本地谱系——

合约 → 证据 → 评分 → 决策 → Agent结果

——存储在

.bound/runs/<run_id>/

下。此功能按运行 opt-in且向后兼容：如果从未启动运行，则不会记录任何内容。可通过

BOUND_LINEAGE_DISABLED=1

禁用。

对于使用BOUND评估的任何非 trivial 任务，请遵循以下规则：

每个任务启动一次运行。

bash

bound run start "<任务>" --metadata phase=PHASE-001

Python中使用：

with bound.start_run("<任务>") as run:

。

**使用稳定的步骤/合约ID。**将同一ID从
```
PLAN.md
```
传递到
```
StepContract(id=...)
```
再到谱系。同一步骤的重新规划需追加
```
-R<N>
```
（如
```
PHASE-001
```
→
```
PHASE-001-R1
```
）；绝不要使用无关ID或重写历史以隐藏重新规划操作。

仅评估有意义的边界（在实现+验证后，而非每个token/文件/命令后），并将评估结果记录到运行中：

bash

bound evaluate --run <run_id> --step PHASE-001 --attempt 1 \
    --action "..." --goal "..." \
    --acceptance A --influence I --risk R --cost C \
    --threshold 0.7 --retry-margin 0.1

此命令会写入

step_started

evaluation_recorded

事件，并向JSON中添加

lineage

块。

记录实际执行的后续行动——而非BOUND“应该”生成的行动：

bash

bound outcome --run <run_id> --step PHASE-001 --attempt 1 \
    --decision REPLAN --note "切换策略为验证器+参数化测试"

当省略

--next-action

和

--reason-code

时，会从

--decision

（

ACCEPT|RETRY|REPLAN|ROLLBACK

）推导得出。

任务结束时显式关闭运行：
bash
```
bound run finish <run_id> --status completed|interrupted|failed --note "..."
```
缺失
```
run_finished
```
事件会标记运行为不完整/崩溃状态（日志仍可读）。如果使用
```
with bound.start_run(...)
```
，上下文管理器会在退出时自动完成中断的运行。
报告本地谱系路径——
```
.bound/runs/<run_id>/
```
（包含
```
run.json
```
和仅追加的
```
events.jsonl
```
），并展示决策树：
bash
```
bound inspect <run_id>
```

标准流程为一次运行、两次尝试：

text

尝试1  →  证据1/3（A=0.3333）  →  REPLAN  → 切换策略
            （新步骤PHASE-001-R1，尝试2）
尝试2  →  证据3/3（A=1.0000）  →  ACCEPT  → 继续到下一步

事件日志为仅追加模式：重新规划会发出一个带有

attempt+1

和

-R<N>

后缀合约ID的新

step_started

事件；早期尝试绝不会被重写。提示词、token和源代码绝不会被存储——仅存储合约ID、评分、阈值、决策、原因代码和后续行动/备注。完整数据模型和API请参考

docs/lineage.md

。

Verify the integration

验证集成

Add an end-to-end test that builds a real contract, collects real observed evidence, calls BOUND, asserts one of the four decisions, and asserts the exact control-flow mapping. Do not hardcode

ACCEPT

unless the evidence genuinely satisfies the contract.

Keep all wiring thin and outside

src/bound/

in consumer repositories. Never fabricate evidence, duplicate policy logic, or use an LLM as the final judge.

添加端到端测试，构建真实合约、收集真实观察证据、调用BOUND、断言四个决策之一，并断言精确的控制流映射。除非证据真正满足合约要求，否则不要硬编码

ACCEPT

。

在消费者仓库中，保持所有连接逻辑轻量且位于

src/bound/

外部。绝不要伪造证据、重复策略逻辑或使用LLM作为最终裁判。