deps-runner

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Purpose

用途

Dependency-PR verification and merge pipeline, partitioned into 6 sequential ICM stages: scan/context → preflight baseline → risk-eval (single cohesive stage, ALL groups) → build-test → merge-decision → report. Each stage runs in isolated context; the critical judgement (risk evaluation) gets a clean-context stage of its own. Behaviorally equivalent to the monolithic

deps-runner

skill, just stage-partitioned.

This skill runs in the OPERATOR session and owns its worker lifecycle. Stages that require a repo environment (preflight, build-test) spawn and drive a repo devbox worker via the gateway worker API (see

pylot-workers

skill). Stages that only need

gh

CLI (scan-context, risk-eval, merge-decision, report) run inline in the operator session.

This procedure is SEQUENTIAL. There is NO fan-out and NO parallel Task launches. Risk evaluation runs as ONE stage over every dependency group — never one subagent per group. The ICM win here is clean-context isolation of the judgement step plus resume-from-stage, not parallelism.

依赖PR验证与合并流水线，分为6个连续的ICM阶段：扫描/上下文 → 预检基准 → 风险评估（单一连贯阶段，覆盖所有分组）→ 构建测试 → 合并决策 → 报告。每个阶段在独立上下文中运行；关键的判断环节（风险评估）拥有独立的纯净上下文阶段。功能上与单体式

deps-runner

skill等效，只是按阶段拆分。

此skill运行在OPERATOR会话中，并管理其工作进程生命周期。需要代码库环境的阶段（预检、构建测试）会通过网关工作进程API（参见

pylot-workers

skill）生成并驱动代码库开发盒工作进程。仅需要

gh

CLI的阶段（扫描上下文、风险评估、合并决策、报告）则直接在operator会话中运行。

**此流程为顺序执行。无分支展开，无并行任务启动。**风险评估作为一个阶段针对所有依赖分组运行——绝不会为每个分组单独生成一个子代理。这里的ICM优势在于判断步骤的纯净上下文隔离以及支持从指定阶段恢复，而非并行性。

Worker Setup

工作进程设置

Stages 02-preflight-baseline and 04-build-test require a repo devbox. Spawn a worker at the start of the procedure and stop it after stage 05:

bash

REPO="${0:-$PYLOT_REPO}"
SPAWN_RESP=$(curl -s --max-time 90 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"repo\": \"$REPO\"}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers")
WID=$(echo "$SPAWN_RESP" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("worker_id",""))' 2>/dev/null)

Use the

pylot-workers

drive loop pattern to send each repo-access stage as a prompt and poll to idle before proceeding to the next stage. Stop the worker before stage 06-report:

bash

curl -s --max-time 30 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}/stop" >/dev/null 2>&1 || true

02-预检基准和04-构建测试阶段需要代码库开发盒。在流程开始时生成一个工作进程，并在05阶段后停止：

bash

REPO="${0:-$PYLOT_REPO}"
SPAWN_RESP=$(curl -s --max-time 90 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"repo\": \"$REPO\"}" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers")
WID=$(echo "$SPAWN_RESP" | python3 -c 'import sys,json; print(json.load(sys.stdin).get("worker_id",""))' 2>/dev/null)

使用

pylot-workers

驱动循环模式，将每个需要访问代码库的阶段作为提示发送，并在进入下一阶段前轮询至空闲状态。在06-报告阶段前停止工作进程：

bash

curl -s --max-time 30 -X POST \
  -H "Authorization: Bearer $PYLOT_DISPATCH_TOKEN" \
  "${PYLOT_API}/missions/${PYLOT_JOB_ID}/workers/${WID}/stop" >/dev/null 2>&1 || true

Arguments

参数

Param	Required	Default	Notes
`repo`	yes	—	Target `org/repo` (positional `$0` )
`container`	no	—	Ona/Gitpod container or environment name (positional `$1` )
`resume_from`	no	(start fresh)	Stage to resume at, e.g. `04-build-test` . Reuses on-disk handoffs from completed stages and skips them.

Parse from

$ARGUMENTS

. Forms accepted:

```
org/repo
```
→ fresh run
```
org/repo container-name
```
→ fresh run with explicit container

org/repo container-name resume_from=04-build-test

→ resume run

参数	是否必填	默认值	说明
`repo`	是	—	目标 `org/repo` （位置参数 `$0` ）
`container`	否	—	Ona/Gitpod容器或环境名称（位置参数 `$1` ）
`resume_from`	否	（从头开始）	恢复执行的阶段，例如 `04-build-test` 。复用已完成阶段的磁盘交接文件并跳过这些阶段。

从

$ARGUMENTS

解析。支持的格式：

```
org/repo
```
→ 从头运行
```
org/repo container-name
```
→ 使用指定容器从头运行

org/repo container-name resume_from=04-build-test

→ 恢复运行

What it does

功能说明

6-stage SEQUENTIAL ICM procedure:

Stage	Mode	Description
01-scan-context	inline	Fetch candidate dep PRs, read repo + team CLAUDE.md, resolve container, group PRs
02-preflight-baseline	subagent	Verify main compiles + tests pass; record baseline; booster remote sync
03-risk-eval	subagent	SINGLE stage: classify every dependency group (diff, dep type, direct usage, risk)
04-build-test	subagent	Per PR: checkout+merge main, install+build, restart if runtime, run tests vs baseline
05-merge-decision	subagent	Apply merge matrix per PR: auto-merge/label, write targeted tests, or flag for Max
06-report	inline	Write local report file(s); release the environment; emit outcome marker

No stage fans out. Stage 03 evaluates ALL dependency groups in one cohesive pass — do not spawn one subagent per group.

6阶段顺序ICM流程：

阶段	模式	描述
01-扫描上下文	内联	获取候选依赖PR，读取代码库+团队CLAUDE.md，解析容器，对PR进行分组
02-预检基准	子代理	验证主分支编译+测试通过；记录基准；同步远程增强器
03-风险评估	子代理	单一阶段：对所有依赖分组进行分类（差异、依赖类型、直接使用情况、风险）
04-构建测试	子代理	每个PR：检出并合并主分支，安装+构建，如需运行时则重启，对比基准运行测试
05-合并决策	子代理	为每个PR应用合并矩阵：自动合并/打标签，编写针对性测试，或标记给Max处理
06-报告	内联	写入本地报告文件；释放环境；输出结果标记

无阶段分支展开。03阶段一次性评估所有依赖分组——请勿为每个分组生成单独的子代理。

Handoff locations

交接文件位置

All handoffs live in the repo working directory:

.procedure-output/deps-runner/{stage}/handoff.md

Stage 01 writes the root context. Each subagent stage receives only the handoffs its CONTEXT.md lists as inputs — never the full orchestrator context.

所有交接文件都位于代码库工作目录中：

.procedure-output/deps-runner/{stage}/handoff.md

01阶段写入根上下文。每个子代理阶段仅接收其CONTEXT.md中列出的输入交接文件——绝不会接收完整的编排器上下文。

Execution

执行方式

Stage 01 (inline)

01阶段（内联）

Run stage 01 yourself (orchestrator context). Read CONTEXT.md:

.claude/skills/deps-runner/stages/01-scan-context/CONTEXT.md

Write handoff to

.procedure-output/deps-runner/01-scan-context/handoff.md

自行运行01阶段（编排器上下文）。读取CONTEXT.md：

.claude/skills/deps-runner/stages/01-scan-context/CONTEXT.md

将交接文件写入

.procedure-output/deps-runner/01-scan-context/handoff.md

。

Stages 02 → 05 (sequential subagents — ONE AT A TIME)

02 → 05阶段（顺序子代理——一次一个）

For each stage in order, spawn exactly ONE Task. Wait for it to finish before spawning the next. Never launch two stages in the same response. Never split a stage across multiple concurrent subagents.

Each Task prompt must be self-contained:

Include only the stage's input handoff paths (listed in that stage's CONTEXT.md)
Include the path to the stage's CONTEXT.md
Do NOT pass orchestrator history or prior reasoning

Task prompt template:

You are running stage {NN}-{name} of the deps-runner procedure.

Read your stage instructions:
  .claude/skills/deps-runner/stages/{NN}-{name}/CONTEXT.md

Your inputs:
  {input handoff path(s) from that stage's CONTEXT.md}

Write your output to:
  .procedure-output/deps-runner/{NN}-{name}/handoff.md

Execute all steps in CONTEXT.md. Write handoff.md before exiting.

If a stage's handoff reports a hard blocker (preflight failure, merge conflict on a stale PR, build/test failure on every PR), continue per that stage's Failure rules — typically the blocker is recorded and flagged, but the run proceeds to 06-report so the report is always produced.

按顺序处理每个阶段，每次仅生成一个任务。等待任务完成后再生成下一个。绝不在同一响应中启动两个阶段。绝不能将一个阶段拆分为多个并发子代理。

每个任务提示必须是自包含的：

仅包含该阶段CONTEXT.md中列出的输入交接文件路径
包含该阶段CONTEXT.md的路径
不得传递编排器历史记录或先前的推理过程

任务提示模板：

你正在执行deps-runner流程的{NN}-{name}阶段。

读取你的阶段说明：
  .claude/skills/deps-runner/stages/{NN}-{name}/CONTEXT.md

你的输入：
  {该阶段CONTEXT.md中列出的输入交接文件路径}

将你的输出写入：
  .procedure-output/deps-runner/{NN}-{name}/handoff.md

执行CONTEXT.md中的所有步骤。退出前写入handoff.md。

如果某个阶段的交接文件报告了严重阻塞（预检失败、过时PR存在合并冲突、所有PR的构建/测试失败），则按照该阶段的失败规则继续——通常会记录并标记阻塞，但流程仍会推进到06-报告阶段，以确保始终生成报告。

Stage 06 (inline)

06阶段（内联）

Run stage 06 yourself (orchestrator context). Read CONTEXT.md:

.claude/skills/deps-runner/stages/06-report/CONTEXT.md

Write the local report file(s) and release the environment. Emit the

[pylot] outcome=...

marker from the orchestrator (not from a subagent). There is NO Quest POST — write the local report file only.

自行运行06阶段（编排器上下文）。读取CONTEXT.md：

.claude/skills/deps-runner/stages/06-report/CONTEXT.md

写入本地报告文件并释放环境。从编排器（而非子代理）输出

[pylot] outcome=...

标记。无需POST到Quest——仅写入本地报告文件即可。

Resume-from-stage

从指定阶段恢复

When

resume_from={NN-name}

is set:

Verify the handoffs for all stages BEFORE
```
resume_from
```
already exist on disk:
bash
```
ls .procedure-output/deps-runner/*/handoff.md
```
Do NOT re-run completed stages — their handoffs are reused as-is as inputs to later stages.
Begin execution at the named stage and continue sequentially to 06-report.
If a required upstream handoff is missing, STOP and report which one — the resume point is invalid; the run must start from an earlier stage.

Stage names for

resume_from

02-preflight-baseline

03-risk-eval

04-build-test

05-merge-decision

06-report

. (

01-scan-context

= a fresh run, no resume needed.)

当设置

resume_from={NN-name}

时：

验证
```
resume_from
```
之前所有阶段的交接文件已存在于磁盘上：
bash
```
ls .procedure-output/deps-runner/*/handoff.md
```
请勿重新运行已完成的阶段——其交接文件会直接被复用为后续阶段的输入。
从指定阶段开始执行，并顺序推进至06-报告阶段。
如果所需的上游交接文件缺失，则停止并报告缺失的文件——恢复点无效，必须从更早的阶段开始运行。

resume_from

支持的阶段名称：

02-preflight-baseline

、

03-risk-eval

、

04-build-test

、

05-merge-decision

、

06-report

。（

01-scan-context

= 从头运行，无需恢复。）

Stage handoff chain

阶段交接链

01-scan-context (inline)
      │
      ▼
02-preflight-baseline ──► 03-risk-eval ──► 04-build-test ──► 05-merge-decision ──► 06-report (inline)
   (subagent)              (subagent,         (subagent)        (subagent)            reads all
                          ALL groups,                                                 handoffs,
                          single pass)                                                writes report)

01-scan-context (内联)
      │
      ▼
02-preflight-baseline ──► 03-risk-eval ──► 04-build-test ──► 05-merge-decision ──► 06-report (内联)
   (子代理)              (子代理，         (子代理)        (子代理)            读取所有
                          所有分组，                                                 交接文件，
                          一次性处理)                                                写入报告)

Exit paths

退出路径

Success: stage 06 emits

[pylot] outcome="deps-runner complete: {merged}/{total} merged, {flagged} flagged" status=success

Failure: failing stage's blocker → orchestrator emits

[pylot] outcome="deps-runner failed at stage NN: {reason}" status=failed

Blocked: preflight failure (main does not compile) →

[pylot] outcome="deps-runner blocked: preflight failed" status=blocked

In all cases stage 06 still writes the local report file before the marker is emitted.

成功：06阶段输出

[pylot] outcome="deps-runner complete: {merged}/{total} merged, {flagged} flagged" status=success

失败：失败阶段的阻塞 → 编排器输出

[pylot] outcome="deps-runner failed at stage NN: {reason}" status=failed

阻塞：预检失败（主分支无法编译）→

[pylot] outcome="deps-runner blocked: preflight failed" status=blocked

在所有情况下，06阶段都会先写入本地报告文件，再输出标记。

Hard Rules

硬性规则

SEQUENTIAL ONLY — one Task per response, each stage finishes before the next starts. NO parallel Task launches anywhere.
NO fan-out — stage 03 evaluates ALL dependency groups in a single cohesive pass; do NOT spawn one subagent per group/PR/dimension. A PR is reasoned about as a whole.
Stage 01 runs inline — context (PR list, CLAUDE.md, container) is established here.
Stage 06 runs inline — the
```
[pylot] outcome=...
```
marker MUST come from the orchestrator.
NO QUEST — no Quest DB POST, no
```
127.0.0.1:4242
```
, no
```
quest.fellowship.dev
```
, no
```
QUEST_TOKEN
```
. Reporting is the local report file only.
Never pass full orchestrator context into subagent Task prompts — inputs only.
Each stage writes handoff.md before the next stage reads it.
Do not skip stages — every stage executes even if its action is "nothing to do" (e.g. zero candidate PRs still runs preflight and produces a report).
resume_from reuses on-disk handoffs — completed stages are not re-run; missing upstream handoff = invalid resume point, stop and report.
Never auto-merge high risk. Always flag for Max. [skip ci] on all merges.
Always release the environment in stage 06. Leaked Ona environments burn credits.

仅顺序执行——每个响应一个任务，前一阶段完成后再启动下一阶段。任何地方都不得并行启动任务。
无分支展开——03阶段一次性评估所有依赖分组；请勿为每个分组/PR/维度生成单独的子代理。PR需作为一个整体进行推理。
01阶段内联运行——上下文（PR列表、CLAUDE.md、容器）在此处建立。
06阶段内联运行——
```
[pylot] outcome=...
```
标记必须来自编排器。
无需Quest——无需POST到Quest DB，无需
```
127.0.0.1:4242
```
，无需
```
quest.fellowship.dev
```
，无需
```
QUEST_TOKEN
```
。仅需生成本地报告文件。
绝不要将完整的编排器上下文传递给子代理任务提示——仅传递输入。
每个阶段写入handoff.md后，下一阶段才能读取它。
请勿跳过阶段——即使某个阶段的操作是"无任务可执行"（例如，没有候选PR时仍需运行预检并生成报告），每个阶段都必须执行。
resume_from复用磁盘上的交接文件——已完成的阶段不会重新运行；缺失上游交接文件=无效恢复点，停止并报告。
**绝不要自动合并高风险依赖。**始终标记给Max处理。所有合并都需添加[skip ci]标记。
**务必在06阶段释放环境。**泄露的Ona环境会消耗额度。

Reference files

参考文件

```
CONTEXT.md
```
— architecture overview
```
stages/NN-name/CONTEXT.md
```
— per-stage inputs, task, output contract
```
shared/report-template.md
```
— the local report file template (stage 06)
```
shared/risk-matrix.md
```
— risk classification matrix + merge-decision matrix (stages 03/05)

```
CONTEXT.md
```
— 架构概述
```
stages/NN-name/CONTEXT.md
```
— 各阶段的输入、任务、输出约定
```
shared/report-template.md
```
— 本地报告文件模板（06阶段）
```
shared/risk-matrix.md
```
— 风险分类矩阵+合并决策矩阵（03/05阶段）