end-to-end-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

End-to-End Development

端到端开发

Use the bundled LangGraph workflow as the sole orchestration engine. The current Pi/Codex agent performs only request/repository discovery, dedicated-worktree creation, bootstrap-spec construction, presentation of a high-risk plan-review interrupt when requested by policy, and concise presentation of terminal status. Do not manually choose phases, construct assignments, supervise workers, manage retries, mutate

run.json

, or bypass graph routing.

Resolve

SKILL_DIR

to this directory. Before a new run or resume, read:

ORCHESTRATION.md completely;
ARTIFACTS.md completely;
SIMPLICITY-CHALLENGE.md only when explaining or diagnosing a challenged plan.

Workers read their assigned

schemas/<kind>.md

and its linked blocker contract, never the coordinator documents.

使用内置的LangGraph工作流作为唯一编排引擎。当前的Pi/Codex Agent仅执行请求/仓库发现、专属工作树创建、引导规范构建、按策略要求触发高风险计划审查中断，以及简洁呈现终端状态。请勿手动选择阶段、构建任务分配、监督工作器、管理重试、修改

run.json

，或绕过图路由。

将

SKILL_DIR

解析为当前目录。在新运行或恢复运行前，请完整阅读：

ORCHESTRATION.md；
ARTIFACTS.md；
仅在解释或诊断受质询的计划时阅读SIMPLICITY-CHALLENGE.md。

工作器仅读取分配给它们的

schemas/<kind>.md

及其链接的阻塞器契约，绝不读取协调器文档。

Non-negotiable invariants

不可协商的不变规则

One executable state machine. LangGraph owns phase selection, conditional routing, retries, interrupts, fan-out/fan-in, writer leases, and completion. Never reimplement those decisions in the coordinator conversation.
Evidence is hash-pinned. A result, validation, finding, blocker, approval, delivery, or next action is known only after it exists in validated durable state or an immutable artifact.
Reconcile before action. Every graph path starts by reconciling run artifacts with output files and external state. Resume from artifacts, never conversation memory.
Follow the selected policy. Ordinary single- and multi-repository work may use the standard no-pause path. High-risk discovery escalates to full before project-file work.
One active project-file writer per repository. The lease protects a role, not an agent identity. Work packets and fix batches preserve it.
Workers do not mutate coordinator state. They write only their exact output, allowed project files, and log directory. The graph updates run, agent, event, lease, and checkpoint state.
Every loop is bounded. New runs get one review, one review-fix batch, one validation-fix cycle, and one pipeline-fix cycle. Worker replacement and planning revision limits are also enforced by the graph. Never “continue until green.”
Preserve evidence, not transcripts. Full output stays in logs. Artifacts contain commands, hashes, exit codes, concise conclusions, and evidence paths.
No silent degradation. Missing, invalid, oversized, stale-tree, or contradictory evidence leaves the gate incomplete.
Migration safety is mandatory. The graph must have isolated local/test database-target evidence before migration-capable validation. Never use production, staging, shared, or ambiguous databases; never copy
```
.env
```
into a new worktree.
No undeclared high-cost mechanism. Stop rather than invent a trigger, database function/procedure, backfill, background/event flow, cache, seam/adapter, storage system, or comparable mechanism absent from the approved plan.
Independent review remains mandatory. Every profile gets at least one fresh baseline-to-worktree review before delivery.
High-risk plan approval is a hard gate. Full-profile implementation cannot begin until a later user message explicitly approves every plan in the exact current hash-pinned review bundle. Fast/standard policy records an automatic hash-pinned decision without pausing; discovery of a high-risk surface invalidates it and escalates before implementation.
External side effects are idempotently reconciled. LangGraph checkpointing does not make workers, commits, pushes, or PR creation exactly-once. Valid existing evidence is recovered instead of repeated.
Completed worker handles are short-lived. The supervisor records an opaque backend handle, cleans it as soon as its worker settles and its output is captured, and records the result. Crash recovery uses the pinned backend to apply the same cleanup even when the output artifact already exists. Never report completion while a settled workflow worker remains open.

单一可执行状态机。LangGraph负责阶段选择、条件路由、重试、中断、扇出/扇入、写入者租约和完成操作。绝不在协调器对话中重新实现这些决策。
证据哈希固定。结果、验证、发现、阻塞器、审批、交付或下一步操作仅在存在于已验证的持久状态或不可变工件中时才被确认。
操作前先协调。每条图路径都从协调运行工件与输出文件及外部状态开始。从工件恢复，绝不依赖对话记忆。
遵循选定策略。普通单仓库和多仓库工作可使用标准无暂停路径。高风险发现会在项目文件工作前升级为完整流程。
每个仓库仅一个活跃项目文件写入者。租约保护的是角色，而非Agent身份。工作包和修复批次会保留该租约。
工作器不得修改协调器状态。它们仅能写入指定的输出内容、允许的项目文件和日志目录。图负责更新运行、Agent、事件、租约和检查点状态。
每个循环都有边界。新运行包含一次审查、一次审查修复批次、一次验证修复周期和一次流水线修复周期。工作器替换和计划修订限制也由图强制执行。绝不“持续运行直至成功”。
保留证据，而非记录。完整输出保存在日志中。工件包含命令、哈希、退出码、简洁结论和证据路径。
无静默降级。缺失、无效、过大、树过期或矛盾的证据会导致关卡无法完成。
迁移安全是强制要求。在具备迁移能力的验证前，图必须拥有隔离的本地/测试数据库目标证据。绝不得使用生产、 staging、共享或模糊的数据库；绝不得将
```
.env
```
复制到新工作树中。
无未声明的高成本机制。若批准计划中未包含触发器、数据库函数/存储过程、回填、后台/事件流、缓存、接缝/适配器、存储系统或类似机制，应停止操作而非自行创建。
独立审查仍是强制要求。每个配置文件在交付前至少要接受一次从基线到工作树的全新审查。
高风险计划审批是硬性关卡。完整配置文件的实现必须等到后续用户消息明确批准当前哈希固定审查包中的所有计划后才能开始。快速/标准策略会自动记录哈希固定的决策而无需暂停；若发现高风险场景，该决策会失效并在实施前升级流程。
外部副作用需幂等协调。LangGraph检查点无法保证工作器、提交、推送或PR创建的精确一次性执行。应恢复有效的现有证据而非重复执行。
已完成的工作器句柄生命周期短暂。监督者会记录一个不透明的后端句柄，在工作器稳定且输出被捕获后立即清理，并记录结果。崩溃恢复时，即使输出工件已存在，也会使用固定的后端执行相同的清理操作。绝不在稳定的工作流工作器仍处于打开状态时报告完成。

Coordinator command interface

协调器命令接口

The orchestrator resolves the required

codebase-design

skill beside this skill and in common Pi/Codex global skill directories. If it is installed elsewhere, set

E2E_CODEBASE_DESIGN_DIR

to the directory containing its

SKILL.md

and

DEEPENING.md

files.

Always invoke the locked project through the wrapper, which keeps the generated virtual environment in the user cache rather than the installed skill directory:

bash

ORCHESTRATOR="$SKILL_DIR/scripts/run-orchestrator"

Do not invoke

workflow_tools.py run-batch

directly during a graph-managed run. It is an internal graph primitive.

编排器会在当前Skill旁以及通用Pi/Codex全局Skill目录中查找所需的

codebase-design

Skill。若它安装在其他位置，请将

E2E_CODEBASE_DESIGN_DIR

设置为包含其

SKILL.md

和

DEEPENING.md

文件的目录。

始终通过包装器调用锁定的项目，这样生成的虚拟环境会保存在用户缓存中，而非安装的Skill目录：

bash

ORCHESTRATOR="$SKILL_DIR/scripts/run-orchestrator"

在图管理的运行期间，请勿直接调用

workflow_tools.py run-batch

。它是图的内部原语。

New run

新运行

Treat skill arguments plus relevant user conversation as the complete request.

Discover every affected repository and every material risk before creating run state.
Ask the user only when repository identity or a material product choice cannot be established from the request and repository evidence. A later plan-review interrupt is mandatory only if policy selects full.
Create one dedicated worktree per repository, preferring Worktrunk:
bash
```
wt switch --create <branch> --format json --no-cd
```
The dedicated worktree must be clean. Never copy
```
.env
```
or other database credentials into it.
Write a bootstrap specification using the exact shape in ORCHESTRATION.md. Preserve material user wording in requirement source text and acceptance criteria.

Choose durable run state under:

text

${HOME}/.local/state/pi/end-to-end-development/<UTC-timestamp>-<request-slug>/

Never use

/tmp

Initialize, then execute:

bash

"$ORCHESTRATOR" init --spec "$BOOTSTRAP_SPEC" --run-dir "$RUN_DIR"
"$ORCHESTRATOR" run "$RUN_DIR" --worker-runtime auto

The command runs until completion, a validated blocker, or a full-profile plan-review LangGraph interrupt.

将Skill参数加上相关用户对话视为完整请求。

在创建运行状态前，发现所有受影响的仓库和所有重大风险。
仅当无法从请求和仓库证据中确定仓库身份或重大产品选择时，才询问用户。仅当策略选择完整流程时，才必须触发后续的计划审查中断。
为每个仓库创建一个专属工作树，优先使用Worktrunk：
bash
```
wt switch --create <branch> --format json --no-cd
```
专属工作树必须保持干净。绝不得将
```
.env
```
或其他数据库凭据复制到其中。
使用ORCHESTRATION.md中的精确格式编写引导规范。在需求源文本和验收标准中保留用户的关键表述。

在以下路径下选择持久化运行状态：

text

${HOME}/.local/state/pi/end-to-end-development/<UTC时间戳>-<请求标识>/

绝不得使用

/tmp

。

初始化后执行：

bash

"$ORCHESTRATOR" init --spec "$BOOTSTRAP_SPEC" --run-dir "$RUN_DIR"
"$ORCHESTRATOR" run "$RUN_DIR" --worker-runtime auto

该命令会持续运行直至完成、遇到已验证的阻塞器，或触发完整配置文件计划审查的LangGraph中断。

Resume

恢复运行

For an explicit run directory:

bash

"$ORCHESTRATOR" resume <absolute-run-directory> --worker-runtime auto

If the user says only “continue,” search the durable root for incomplete runs whose repository roots contain the current directory. Resume only when exactly one matches; otherwise list candidates. If that full-profile run is awaiting plan review, do not call
resume
: re-present the current bundle and request explicit whole-bundle approval or changes.

Inspect without advancing:

bash

"$ORCHESTRATOR" status "$RUN_DIR"

Never edit

run.json

agents.json

events.jsonl

, assignments, or LangGraph SQLite state to repair a run. Diagnose the rejected evidence or use a supported CLI transition.

resume

retries blockers classified as environment, authentication, permission, or infrastructure after the external condition is fixed; it never clears code, dependency, or decision blockers. If an older engine created a validation assignment without the canonical plan IDs and then emitted the exact validation-coverage blocker, update the engine and use the narrowly guarded recovery command:

bash

"$ORCHESTRATOR" retry-validation-evidence "$RUN_DIR" --worker-runtime auto

This command rejects every other blocker and reruns validation with a new plan-hash-bound assignment; it does not weaken ordinary code-blocker handling.

If a dependent fix was started concurrently with an upstream contract fix and stopped on the exact hash-pinned bundle-drift blocker, update the engine and use:

bash

"$ORCHESTRATOR" retry-dependent-fixes "$RUN_DIR" --worker-runtime auto

The guarded transition rejects other dependency blockers, serializes remaining fixes in shared-contract dependency order, grants read-only access to upstream worktrees, and pins accepted upstream fix artifacts into each dependent assignment.

对于明确指定的运行目录：

bash

"$ORCHESTRATOR" resume <绝对运行目录> --worker-runtime auto

若用户仅说“继续”，请在持久化根目录中搜索仓库根目录包含当前目录的未完成运行。仅当恰好有一个匹配项时才恢复运行；否则列出候选项。若该完整配置文件运行正在等待计划审查，请勿调用
resume
：重新呈现当前包并请求明确的全包批准或更改。

不推进运行仅检查状态：

bash

"$ORCHESTRATOR" status "$RUN_DIR"

绝不得编辑

run.json

、

agents.json

、

events.jsonl

、任务分配或LangGraph SQLite状态来修复运行。诊断被拒绝的证据或使用支持的CLI过渡。

resume

会在外部条件修复后重试归类为环境、认证、权限或基础设施类的阻塞器；它绝不会清除代码、依赖或决策类阻塞器。若旧引擎创建了没有规范计划ID的验证任务，然后触发了完全匹配的验证覆盖阻塞器，请更新引擎并使用严格受限的恢复命令：

bash

"$ORCHESTRATOR" retry-validation-evidence "$RUN_DIR" --worker-runtime auto

该命令会拒绝所有其他阻塞器，并使用新的计划哈希绑定任务重新运行验证；它不会弱化普通代码阻塞器的处理逻辑。

若依赖修复与上游契约修复同时启动，并因完全匹配的哈希固定包漂移阻塞器而停止，请更新引擎并使用：

bash

"$ORCHESTRATOR" retry-dependent-fixes "$RUN_DIR" --worker-runtime auto

该受限过渡会拒绝其他依赖阻塞器，按共享契约依赖顺序序列化剩余修复，授予上游工作树只读访问权限，并将已接受的上游修复工件固定到每个依赖任务中。

Full-profile plan-review interrupt

完整配置文件计划审查中断

Fast and standard runs still emit a complete hash-pinned review bundle, but policy accepts it atomically without a user pause. When a full-profile graph returns

status: awaiting-user

and

phase: plan-review

Read
```
plan_review.path
```
and verify the reported SHA-256 still matches.
Present the bundle path, hash, and concise per-repository task/packet/risk/validation summaries.
Ask exactly: “Approve all plans in this exact review bundle, or send the changes you want.”
End the turn. Do not create implementation work, edit project files, or invoke a generic resume.

On a later message, approval is valid only when the user's wording explicitly approves the whole current bundle. Preserve that wording exactly:

bash

"$ORCHESTRATOR" approve "$RUN_DIR" \
  --review-sha256 "$CURRENT_BUNDLE_SHA256" \
  --text "$EXACT_USER_APPROVAL" \
  --worker-runtime auto

The CLI independently rejects generic continuation and a stale hash.

For requested changes:

bash

"$ORCHESTRATOR" request-changes "$RUN_DIR" \
  --review-sha256 "$CURRENT_BUNDLE_SHA256" \
  --text "$EXACT_USER_FEEDBACK" \
  [--repository <repo-id>] \
  --worker-runtime auto

Omit

--repository

when feedback affects the whole bundle. The graph creates a hash-pinned revision basis, returns the affected plans through the bounded planning path, reruns required challenges, emits a new complete bundle, and interrupts again. Any canonical contract, plan, or challenge hash change invalidates prior approval.

快速和标准运行仍会生成完整的哈希固定审查包，但策略会自动原子性接受它而无需用户暂停。当完整配置文件图返回

status: awaiting-user

和

phase: plan-review

时：

读取
```
plan_review.path
```
并验证报告的SHA-256是否仍匹配。
呈现包路径、哈希以及每个仓库的任务/工作包/风险/验证的简洁摘要。
准确询问：“批准此精确审查包中的所有计划，还是发送您想要的更改？”
结束当前交互。请勿创建实现工作、编辑项目文件或调用通用恢复命令。

在后续消息中，仅当用户表述明确批准当前完整包时，批准才有效。请完全保留该表述：

bash

"$ORCHESTRATOR" approve "$RUN_DIR" \
  --review-sha256 "$CURRENT_BUNDLE_SHA256" \
  --text "$EXACT_USER_APPROVAL" \
  --worker-runtime auto

CLI会独立拒绝通用继续指令和过期哈希。

对于请求更改的情况：

bash

"$ORCHESTRATOR" request-changes "$RUN_DIR" \
  --review-sha256 "$CURRENT_BUNDLE_SHA256" \
  --text "$EXACT_USER_FEEDBACK" \
  [--repository <repo-id>] \
  --worker-runtime auto

当反馈影响整个包时，省略

--repository

。图会创建哈希固定的修订基础，通过有界规划路径返回受影响的计划，重新运行必要的质询，生成新的完整包，并再次触发中断。任何规范契约、计划或质询哈希的变更都会使之前的批准失效。

Database-target safety gate

数据库目标安全关卡

If the graph blocks because a plan contains a migration-capable validation, independently confirm that the target is disposable and isolated. Never print or record the database URL or credentials. Then record only safe classification evidence:

bash

"$ORCHESTRATOR" database-target "$RUN_DIR" \
  --repository <repo-id> \
  --classification isolated-test \
  --description "Ephemeral database dedicated to this worktree"

Allowed classifications are

isolated-local

and

isolated-test

. The command rejects production, staging, shared, and ambiguous targets. Resume through the graph afterward. This evidence does not authorize an unplanned destructive migration, reset, fresh migration, seed, or drop operation.

若图因计划包含可迁移的验证而阻塞，请独立确认目标是可丢弃且隔离的。绝不得打印或记录数据库URL或凭据。然后仅记录安全分类证据：

bash

"$ORCHESTRATOR" database-target "$RUN_DIR" \
  --repository <repo-id> \
  --classification isolated-test \
  --description "专用于此工作树的临时数据库"

允许的分类为

isolated-local

和

isolated-test

。该命令会拒绝生产、staging、共享和模糊的目标。之后通过图恢复运行。此证据并不授权执行计划外的破坏性迁移、重置、全新迁移、种子数据导入或删除操作。

Deterministic policy

确定性策略

The initializer applies:

bash

python3 "$SKILL_DIR/scripts/workflow_tools.py" policy \
  --repository-count <N> \
  [--risk authorization] [--risk database-migration] \
  [--profile auto|fast|standard|full] [--report]

fast

is opt-in.

standard

is the automatic ordinary-work default, including coordinated multi-repository changes. Authorization, security, concurrency, migration, backfill, background processing, new storage, public-interface changes, or another high-cost mechanism force

full

. Planning can escalate before implementation when it discovers risk. Repository count and the

cross-repository

flag alone do not force full.

Gate	Fast	Standard	Full
Shared contract	embedded in plan	multi-repository only	multi-repository only
Design challenge	none unless discovery escalates	risk-only	risk-only
Complete-plan user approval	policy-accepted	policy-accepted	explicit user approval
Implementation packet	≤4 tasks	≤3 tasks	≤3 tasks
Independent full review	one	one	one
Targeted second review	never	never	never
Cross-repository integration	no	multi-repository only	multi-repository only
Deterministic HTML report	requested only	requested only	requested only

New runs use these hard stage limits:

json

{
  "worker_replacements_per_stage": 1,
  "artifact_repairs_per_action": 1,
  "contract_revisions": 1,
  "plan_revision_cycles": 1,
  "validation_fix_cycles": 1,
  "review_rounds": 1,
  "pipeline_fix_cycles": 1
}

A review may produce one compatible

fix-1

batch, but that fix never starts another review. A validation or required-check failure may produce one compatible fix batch and one check afterward; another failure blocks with preserved evidence. Never modify limits during an active run. Existing durable runs retain their pinned limits when resumed.

The graph checks

coordinator_attempt_budget

after each atomic batch. When reached, it checkpoints at

reconcile

; when

auto_resume

is true the CLI starts a fresh bounded graph invocation from that checkpoint, otherwise it returns

outcome: budget-checkpoint

for a supported later resume. Neither path can cross a pending plan-review interrupt.

初始化器会应用：

bash

python3 "$SKILL_DIR/scripts/workflow_tools.py" policy \
  --repository-count <N> \
  [--risk authorization] [--risk database-migration] \
  [--profile auto|fast|standard|full] [--report]

fast

需主动选择。

standard

是普通工作的默认自动配置，包括协调多仓库变更。授权、安全、并发、迁移、回填、后台处理、新存储、公共接口变更或其他高成本机制会强制使用

full

。当计划发现风险时，可能会在实施前升级流程。仅仓库数量和

cross-repository

标志不会强制使用完整流程。

关卡	Fast	Standard	Full
共享契约	嵌入计划中	仅多仓库场景	仅多仓库场景
设计质询	除非发现风险升级，否则无	仅风险场景	仅风险场景
完整计划用户批准	策略自动接受	策略自动接受	用户明确批准
实现工作包	≤4个任务	≤3个任务	≤3个任务
独立完整审查	1次	1次	1次
针对性二次审查	从不	从不	从不
跨仓库集成	无	仅多仓库场景	仅多仓库场景
确定性HTML报告	仅按需生成	仅按需生成	仅按需生成

新运行使用以下严格的阶段限制：

json

{
  "worker_replacements_per_stage": 1,
  "artifact_repairs_per_action": 1,
  "contract_revisions": 1,
  "plan_revision_cycles": 1,
  "validation_fix_cycles": 1,
  "review_rounds": 1,
  "pipeline_fix_cycles": 1
}

一次审查可能生成一个兼容的

fix-1

批次，但该修复绝不会触发另一次审查。验证或必填检查失败可能生成一个兼容的修复批次和一次后续检查；再次失败会保留证据并阻塞。运行期间绝不得修改限制。已存在的持久化运行在恢复时会保留其固定的限制。

图会在每个原子批次后检查

coordinator_attempt_budget

。当预算耗尽时，它会在

reconcile

阶段创建检查点；若

auto_resume

为true，CLI会从该检查点启动新的有界图调用，否则返回

outcome: budget-checkpoint

以支持后续恢复。两条路径都无法跨越待处理的计划审查中断。

Executable phase behavior

可执行阶段行为

The compiled graph contains these phase nodes, with

reconcile

between every transition:

```
bootstrap
```
, auto-detecting and pinning the worker backend/runtime, then verifying Git worktrees, forge remotes, and forge CLI authentication
```
contract
```
when policy requires it
```
plan
```
, including conditional challenge and one bounded revision
```
plan-review
```
, implemented with LangGraph
```
interrupt()
```
only for full; fast/standard records a policy decision and proceeds
```
implement
```
, scheduling topologically eligible work packets
```
validate
```
, with at most one validation-fix batch
```
review-1
```
```
fix-1
```
when must-fix findings exist, with no follow-up review cycle
```
integrate
```
when policy requires it
```
deliver
```
, with at most one pipeline-fix batch for change-related failures
post-delivery content-evidence confirmation
```
report
```
when required
```
complete
```
, with final audit and deterministic metrics

The graph retains

review-2

and

fix-2

nodes only so older durable runs with a pinned two-round limit can resume safely. New runs never schedule them.

Repository IDs and stable IDs sort lexicographically. Independent repositories launch together through one supervisor batch. Contract dependency evidence is the only reason to serialize repositories.

编译后的图包含以下阶段节点，每个过渡之间都有

reconcile

步骤：

```
bootstrap
```
：自动检测并固定工作器后端/运行时，然后验证Git工作树、Forge远程仓库和Forge CLI认证
```
contract
```
：当策略要求时触发
```
plan
```
：包含条件性质询和一次有界修订
```
plan-review
```
：仅针对完整流程通过LangGraph
```
interrupt()
```
实现；快速/标准流程会记录策略决策并继续
```
implement
```
：调度拓扑上符合条件的工作包
```
validate
```
：最多包含一次验证修复批次
```
review-1
```
```
fix-1
```
：当存在必须修复的发现时触发，无后续审查周期
```
integrate
```
：当策略要求时触发
```
deliver
```
：针对变更相关失败最多包含一次流水线修复批次
交付后内容证据确认
```
report
```
：按需触发
```
complete
```
：包含最终审计和确定性指标

图保留

review-2

和

fix-2

节点仅为了让固定了两轮限制的旧持久化运行能够安全恢复。新运行绝不会调度这些节点。

仓库ID和稳定ID按字典序排序。独立仓库通过一个监督者批次同时启动。契约依赖证据是序列化仓库的唯一原因。

Worker routing

工作器路由

The graph constructs immutable assignments and invokes the supervisor internally. Users do not configure a terminal manager. Bootstrap selects the first positively detected active environment in this order: a reachable Paseo parent from

PASEO_AGENT_ID

, a compatible Herdr server from

HERDR_ENV

, the active tmux session from

TMUX

, then the always-available direct headless backend.

PASEO_HOST

alone never selects remote workers because remote paths may not match the coordinator's hash-pinned paths. The selected backend and evidence are pinned in

run.json

for recovery.

--worker-runtime auto

inherits a Paseo parent's Pi/Codex provider when present, otherwise follows the coordinator: Codex when

CODEX_THREAD_ID

is present and Pi by default.

E2E_COORDINATOR_RUNTIME

remains an internal diagnostic override, not required user setup.

Workers keep

gpt-6-astra

. New runs pin

worker_reasoning_policy: stage-v1

xhigh

for full-profile contract/planning/challenge/review/integration;

high

for ordinary planning/review and all source-writing implementation/fixes;

medium

for artifact-only repair, validation-only work, and fallback delivery. Launchers honor the actual level across every backend. Legacy runs without a pinned stage policy retain xhigh, and surviving handles retain their recorded configuration. Unsupported configuration blocks; never silently substitute a model.

Workers never spawn nested agents. A Paseo coordinator creates Paseo subagents, Herdr creates non-focused workspaces, tmux creates detached windows, and direct mode runs non-interactively without a terminal manager. The supervisor archives or closes each settled handle immediately after capturing its artifact result, including rejected artifacts; working, blocked, and timed-out workers are retained for diagnosis.

图会构建不可变的任务分配并内部调用监督者。用户无需配置终端管理器。引导阶段会按以下顺序选择第一个检测到的活跃环境：来自

PASEO_AGENT_ID

的可访问Paseo父节点、来自

HERDR_ENV

的兼容Herdr服务器、来自

TMUX

的活跃tmux会话，最后是始终可用的直接无头后端。仅

PASEO_HOST

不会选择远程工作器，因为远程路径可能与协调器的哈希固定路径不匹配。所选后端和证据会被固定在

run.json

中用于恢复。

--worker-runtime auto

会继承Paseo父节点的Pi/Codex提供商（若存在），否则遵循协调器的配置：当

CODEX_THREAD_ID

存在时使用Codex，默认使用Pi。

E2E_COORDINATOR_RUNTIME

仍是内部诊断覆盖选项，无需用户配置。

工作器使用

gpt-6-astra

。新运行会固定

worker_reasoning_policy: stage-v1

：完整配置文件的契约/计划/质询/审查/集成阶段使用

xhigh

；普通计划/审查以及所有源代码编写的实现/修复使用

high

；仅工件修复、仅验证工作和回退交付使用

medium

。启动器会在所有后端上遵循实际的推理级别。未固定阶段策略的旧运行会保留xhigh级别，现存的句柄会保留其记录的配置。不支持的配置会阻塞；绝不得静默替换模型。

工作器绝不会生成嵌套Agent。Paseo协调器会创建Paseo子Agent，Herdr会创建非聚焦工作区，tmux会创建分离窗口，直接模式会在无终端管理器的情况下以非交互方式运行。监督者会在捕获工件结果（包括被拒绝的工件）后立即归档或关闭每个稳定的句柄；工作中、阻塞或超时的工作器会被保留用于诊断。

Artifact-only recovery

仅工件恢复

Workers should use the typed

artifact_guard.py block

command and blocker schema. In new runs, a parseable blocked result missing only

blockers[*].kind

receives at most one five-minute, medium-reasoning artifact-only repair. It has a new immutable assignment/output, no project/Git/forge write permission, and pinned original semantics, logs, content, HEAD, branch, and index. It cannot manufacture a pass, rewrite evidence, or start another source writer. Ambiguous/invalid repair and stale evidence block with an actionable explanation. Missing files or process failures remain distinct from eligible schema repair. Resume never resets the allowance; legacy runs retain their existing policy.

工作器应使用类型化的

artifact_guard.py block

命令和阻塞器 schema。在新运行中，若可解析的阻塞结果仅缺少

blockers[*].kind

，最多会获得一次5分钟、中等推理级别的仅工件修复。它会有新的不可变任务分配/输出，无项目/Git/Forge写入权限，并固定原始语义、日志、内容、HEAD、分支和索引。它无法制造通过结果、重写证据或启动新的源代码写入器。模糊/无效的修复和过期证据会被阻塞并给出可操作的解释。缺失文件或流程故障与符合条件的schema修复是不同的情况。恢复运行绝不会重置修复配额；旧运行会保留其现有策略。

Work packets and bounded deviations

工作包和有界偏差

The plan defines the packet, not individual task, as the implementation unit. A worker may record a bounded deviation only when it preserves accepted requirements and contract, adds no risk or mechanism, follows repository precedent, remains within the packet concern, and records evidence. A new behavior, contract/interface change, migration, dependency edge, or high-cost mechanism is material and blocks rather than silently replans.

计划将工作包（而非单个任务）定义为实现单元。仅当工作器的操作能保留已接受的需求和契约、不增加风险或机制、遵循仓库先例、保持在工作包的关注范围内并记录证据时，才可记录有界偏差。新行为、契约/接口变更、迁移、依赖关系或高成本机制属于重大变更，应阻塞而非静默重新计划。

Validation and review

验证和审查

The graph computes a content fingerprint independent of commit identity. The final implementation/fix writer runs the complete planned suite, and the graph reuses that evidence only when validation ID, exact command hash, and content fingerprint match. A delivery-only commit therefore causes no duplicate validation; any source change invalidates the evidence. Compatible failures are fixed in one batch and checked once afterward.

One fresh worker independently reviews the complete baseline-to-worktree state. Critical/high actionable findings always block; medium correctness/spec findings normally block; low findings remain advisory. Compatible must-fix findings are resolved in one repository batch, affected checks run once, and the workflow proceeds without a second review. An incompatible or still-failing correction blocks instead of opening another remediation loop.

图会计算独立于提交标识的内容指纹。最终的实现/修复写入器会运行完整的计划套件，仅当验证ID、精确命令哈希和内容指纹匹配时，图才会复用该证据。因此仅交付的提交不会导致重复验证；任何源代码变更都会使证据失效。兼容的失败会在一个批次中修复并进行一次后续检查。

一名全新的工作器会独立审查从基线到工作树的完整状态。关键/高优先级的可操作发现始终会阻塞；中等正确性/规范发现通常会阻塞；低优先级发现仅作为建议。兼容的必须修复发现会在一个仓库批次中解决，运行一次受影响的检查，然后工作流无需二次审查即可继续。不兼容或仍失败的修正会被阻塞而非开启另一个修复循环。

Delivery and completion

交付和完成

New GitHub.com runs pin a deterministic command executor using scripts/delivery_tools.py, not a delivery agent. It audits the explicit task inventory, preserves unrelated work, commits/pushes without force, reconciles the existing PR, and checks CI against the local/pushed/PR head. Command intents are durable and recovered without worker handles; independent repositories can execute delivery concurrently. Other forges and legacy runs retain their pinned worker path.

Version-2 delivery evidence requires positive required-check policy discovery, the final checked head, and every required identity passing. An empty rollup is not a waiver: verified absence is

not-configured

, never "CI passed." Pending/missing/timed-out, skipped/cancelled, changed-head/policy, or unknown-policy results cannot complete. Authentication, permission, and infrastructure failures block rather than churn. Only compatible change-related failures get one pipeline-fix batch; pending checks do not spend it. Bootstrap can set a repository's

delivery_check_timeout_seconds

from 0 (observe once) to 1800 (default). This is a CI polling limit, not a whole-run deadline.

After delivery, the graph verifies that the committed content still matches passing evidence rather than invalidating it merely because

HEAD

changed. Completion then verifies the policy-selected plan decision, canonical hashes, current validation, required integration/report evidence, delivery artifacts, no unresolved must-fix finding, no unexplained writer lease, no open workflow worker handle, empty actions, and empty blockers. Metrics are generated deterministically, counting command attempts separately from agent launches. Do not infer elapsed-time improvements from mocked worker counts.

新的GitHub.com运行会使用scripts/delivery_tools.py固定确定性命令执行器，而非交付Agent。它会审核明确的任务清单、保留无关工作、无强制地提交/推送、协调现有PR，并针对本地/推送/PR头检查CI状态。命令意图是持久化的，无需工作器句柄即可恢复；独立仓库可并发执行交付。其他Forge和旧运行会保留其固定的工作器路径。

版本2的交付证据要求积极的必填检查策略发现、最终检查的HEAD，以及所有必填身份验证通过。空汇总并非豁免：已验证的缺失状态为

not-configured

，绝非“CI已通过”。待处理/缺失/超时、跳过/取消、HEAD/策略变更或未知策略的结果无法完成交付。认证、权限和基础设施失败会阻塞而非反复重试。仅兼容的变更相关失败会获得一次流水线修复批次；待处理的检查不会消耗该配额。引导阶段可将仓库的

delivery_check_timeout_seconds

设置为0（仅观察一次）到1800（默认值）之间。这是CI轮询限制，而非整个运行的截止时间。

交付后，图会验证提交的内容是否仍与通过的证据匹配，而非仅因

HEAD

变更而使证据失效。完成阶段会验证策略选定的计划决策、规范哈希、当前验证、所需的集成/报告证据、交付工件、无未解决的必须修复发现、无未解释的写入者租约、无打开的工作流工作器句柄、无未处理操作和无阻塞器。指标会确定性生成，将命令尝试次数与Agent启动次数分开统计。请勿从模拟的工作器数量推断耗时改进。

Final response

最终响应

Use the orchestrator JSON output. Keep the final response concise:

status;
absolute run directory;
PR URLs;
report path/URL when present.

For WSL local HTML, convert the absolute report path to a

file://wsl.localhost/Ubuntu-Shared...

URL on its own line.

使用编排器的JSON输出。保持最终响应简洁：

状态；
绝对运行目录；
PR链接；
报告路径/链接（若存在）。

对于WSL本地HTML，请将绝对报告路径转换为

file://wsl.localhost/Ubuntu-Shared...

格式的链接并单独成行。