loop-graph

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

loop-graph — a graph of agent nodes, not a drifting loop

loop-graph — 由Agent节点构成的图，而非漂移的循环

Module boundary

模块边界

This is the shared compiler, not a goal-specific workflow. It owns the graph shape, the five runtime artifact schemas, generic interview mechanics, and host handoff. A focused preset owns only its North Star, proof, interview questions, recommended work shape, method guards, knobs, and slug; it never forks templates or adds a runtime node.

Use

../loop-converge/SKILL.md

for code cleanup,

../loop-deliver/SKILL.md

for requirement delivery, and

../loop-research/SKILL.md

for evidence-led solution selection. Use this skill directly only when a custom pack is genuinely needed. The exact contract is in

docs/preset-contract.md

这是共享编译器，而非针对特定目标的工作流。它负责图结构、五种运行时构件模式、通用访谈机制和主机交接。专用预设仅负责其北极星目标、验证标准、访谈问题、推荐工作形态、方法防护规则、调节参数和slug；它绝不会分叉模板或添加运行时节点。

代码清理请使用

../loop-converge/SKILL.md

，需求交付请使用

../loop-deliver/SKILL.md

，循证方案选型请使用

../loop-research/SKILL.md

。仅当确实需要自定义包时，才直接使用本技能。确切的契约定义在

docs/preset-contract.md

中。

What it does & why

核心功能与设计初衷

Turns a vague long-horizon request ("make it production-ready", "accuracy above baseline", "finish the migration") into a small graph of agent nodes that stays on-spec across many rounds:

an executor node — drives the work round by round against a single scoreboard;
a supervisor node — audits the work from outside the executor's context (re-verifying claimed-done against the shared standards) and corrects course before drift compounds.

Why a graph, not a loop: an agent grinding a long task is inside the context that drifted, so it rationalizes scope creep and calls half-done work "done". The nodes talk only through durable, inspectable state (ledger, git tree, directives file) — never a shared, polluted context.

Each node runs on its own timer, and no node ever wakes another. The executor fires, closes several verified rounds on warm context, and ends. The supervisor fires on a slower cadence, audits, appends corrections, and ends. A correction is picked up on the executor's next fire. Two independent clocks and one file edge — no dispatch, no resume prompt, no liveness protocol, and therefore nothing that can leave the run waiting for a wake that never comes.

将模糊的长期需求（例如“使其达到生产就绪状态”、“准确率超过基线”、“完成迁移”）转化为一个小型的Agent节点图，可在多轮运行中始终符合规范：

executor节点（执行节点） — 基于单一计分板逐轮推动工作；
supervisor节点（监督节点） — 从executor上下文的外部审计工作（对照共享标准重新验证声称已完成的内容），并在漂移累积之前纠正方向。

为什么是图而非循环：处理长期任务的Agent处于已经发生漂移的上下文之中，因此会将范围蔓延合理化，把完成一半的工作称作“已完成”。节点之间仅通过持久化、可审计的状态（ledger、git树、directives文件）通信 — 绝不使用共享的、被污染的上下文。

每个节点按自己的计时器运行，没有节点会唤醒其他节点。 executor触发后，在热上下文中完成若干轮已验证的工作，然后结束。supervisor以更慢的节奏触发，执行审计、追加纠正意见后结束。纠正意见会在executor下一次触发时被拾取。两个独立的时钟和一条文件边 — 没有调度、没有恢复提示词、没有活性协议，因此不会出现运行过程一直等待永远不会到来的唤醒信号的情况。

The graph it builds

它构建的图结构

        ┌─────────────┐   reads / rewrites   ┌──────────────┐
        │  EXECUTOR    │ ───────────────────▶ │              │
        │  node        │ ◀─────────────────── │  ledger.md   │  ← single scoreboard
        │ (own timer)  │                      │ (shared state)│
        └─────────────┘                      └──────────────┘
              ▲                                      ▲
              │ reads each round                     │ reads only (never writes it)
              │                                      │
        ┌───────────────┐   appends corrections ┌──────────────────┐
        │ directives.md │ ◀──────────────────── │   SUPERVISOR     │  ← separate context,
        └───────────────┘                       │ node (own timer) │     slower cadence
                                                 └──────────────────┘
                                                     │ checkpoint-commits clean work
                                                     │ escalates human-only calls
                                                     ▼
                                                   git / you

Five live artifacts from a short interview:

executor.md
— executor prompt: one task book, one cadence, anti-bloat rules, stop conditions, red lines.
ledger.md
— the single scoreboard both nodes read; the executor rewrites it every round.
directives.md
— the bounded one-way corrections queue: current STANDING locks + not-yet-folded numbered corrections; folded ones rotate into a cold archive.
ops.md
— the exact context index and gates every cold node follows, plus current environment/data/host lifecycle facts when applicable; update facts in place, never as a timeline.
supervisor.md
(optional) — supervisor prompt, scheduled; independently re-verifies claimed-done work, checkpoint-commits what passes, decides pending items, and corrects drift / steers the plan via the directives file.

Run directory — fixed, one per run. Everything above goes in

.longgraph/<YYYY-MM-DD-slug>/

at the repo root (workspace root for multi-repo runs), plus an

archive/

subdir for in-run rotations. A new run always creates
.longgraph/…
from the templates — never retarget or edit a previous run's files: patching stale prompts wastes tokens and leaves leftover text steering toward the old goal. The old directory stays untouched (it is the archive); distill what still holds into the new ledger's starting snapshot and copy still-in-force STANDING directives forward. Commit the run directory unless data policy forbids — it's the durable state the graph depends on.

Runtime contract ids are

longgraph.loop-graph.*

Invariants: ledger = the only scoreboard; one independently verifiable work item (which may be one coherent workset) per round → verify → update ledger; the supervisor steers only through
directives.md
(a one-way edge) — it never edits the ledger or shares the executor's context.

        ┌─────────────┐   reads / rewrites   ┌──────────────┐
        │  EXECUTOR    │ ───────────────────▶ │              │
        │  node        │ ◀─────────────────── │  ledger.md   │  ← single scoreboard
        │ (own timer)  │                      │ (shared state)│
        └─────────────┘                      └──────────────┘
              ▲                                      ▲
              │ reads each round                     │ reads only (never writes it)
              │                                      │
        ┌───────────────┐   appends corrections ┌──────────────────┐
        │ directives.md │ ◀──────────────────── │   SUPERVISOR     │  ← separate context,
        └───────────────┘                       │ node (own timer) │     slower cadence
                                                 └──────────────────┘
                                                     │ checkpoint-commits clean work
                                                     │ escalates human-only calls
                                                     ▼
                                                   git / you

通过简短访谈生成五个可运行构件：

executor.md
— executor提示词：包含任务手册、运行节奏、防膨胀规则、停止条件、红线。
ledger.md
— 两个节点都读取的唯一计分板；executor每轮都会重写它。
directives.md
— 有界的单向纠正队列：当前的STANDING（常设）锁定 + 尚未合并的编号纠正意见；已合并的意见会轮转至冷归档。
ops.md
— 每个冷节点都遵循的确切上下文索引和门控规则，以及适用时的当前环境/数据/主机生命周期事实；事实信息直接就地更新，绝不以时间线形式呈现。
supervisor.md
（可选）— 定时运行的supervisor提示词；独立重新验证声称已完成的工作，对通过检查的内容提交检查点，决定待处理项，并通过directives文件纠正漂移/调整计划方向。

运行目录 — 固定，每次运行对应一个目录。 上述所有文件都放在仓库根目录（多仓库运行时为工作区根目录）下的

.longgraph/<YYYY-MM-DD-slug>/

目录中，另外还有一个

archive/

子目录用于运行过程中的归档轮转。新的运行始终基于模板创建
.longgraph/…
目录 — 绝不要复用或编辑之前运行的文件：修补过时的提示词会浪费token，并且残留的文本会将流程导向旧目标。旧目录保持原样（它本身就是归档）；将仍然有效的内容提炼到新ledger的起始快照中，并将仍然生效的STANDING指令复制过来。除非数据政策禁止，否则请提交运行目录 — 它是图结构依赖的持久化状态。

运行时契约ID为

longgraph.loop-graph.*

。

不变量：ledger = 唯一计分板；每轮完成一个可独立验证的工作项（可以是一个连贯的工作集）→ 验证 → 更新ledger；supervisor仅通过
directives.md
（单向边）进行引导 — 它绝不编辑ledger，也不共享executor的上下文。

When to use it

适用场景

Task spans many rounds; the user won't babysit each one.
"Done" is verifiable (tests, gates, metrics) — the graph needs a definition of done it can check itself.
Real risk of scope creep, "looks done" work, or quietly changing contracts / lowering the bar.

Not for a one-shot edit, or when success needs a human to judge every time — say so, suggest a plain task.

任务跨越多个轮次，用户无需全程跟进每一轮。
“完成”是可验证的（测试、门控、指标）— 图结构需要一个可自行检查的完成定义。
存在范围蔓延、“看起来完成了”的工作、或者悄悄变更契约/降低标准的实际风险。

不适用于一次性编辑，或者每次成功都需要人工判断的场景 — 请明确说明，并建议使用普通任务。

Language

语言要求

Interview in the user's language and mirror it in the prose inside the artifacts (goals, notes, red lines). Keep structural keywords, headings, and field names as in the templates so files stay tool-friendly.

使用用户的语言进行访谈，并在构件内的文本（目标、说明、红线）中保持一致。结构关键词、标题和字段名保持模板中的原样，确保文件对工具友好。

When called from a preset skill

从预设技能调用时

A sibling authoring skill (for example

loop-converge

) may bind a preset pack and then hand off here. The pack follows the

preset contract

; treat it as already answered for:

North Star and proof — skip that interview question unless the pack is silent on a checkable outcome.
Supervisor — required when the pack says so; do not ask to omit it.
Method guards — append the pack's guards as
```
PROJECT_SPECIFIC_METHOD_GUARDS
```
.
Knob overrides — use the pack's numbers instead of the defaults.
Recommended shape — present the pack's decomposition (milestones, or a rotation for a sweeping run) as A unless inspection shows a materially different one.
Artifact emphasis — compile the pack's required facts into the shared
```
ledger.md
```
,
```
ops.md
```
,
```
directives.md
```
, executor, and supervisor sections; do not create a second runtime template or scoreboard.

Still discover the workspace. Still ask at most three owner questions; with a bound pack those are typically scope, authority, and launch mode. Still generate from this skill's

templates/

— never a second template set, never a third runtime node. The preset skill does not execute the generated nodes.

兄弟创作技能（例如

loop-converge

）可以绑定一个预设包，然后移交到这里。预设包遵循

预设契约

；请将以下内容视为已回答：

北极星目标与验证标准 — 跳过该访谈问题，除非预设包未提及可验证的成果。
Supervisor — 当预设包要求时必须包含；请勿询问是否省略。
方法防护规则 — 将预设包的防护规则追加为
```
PROJECT_SPECIFIC_METHOD_GUARDS
```
。
参数覆盖 — 使用预设包的数值而非默认值。
推荐形态 — 将预设包的拆解方案（里程碑，或者全面运行的轮转方案）作为选项A呈现，除非检查后发现存在实质性差异。
构件重点 — 将预设包要求的事实编入共享的
```
ledger.md
```
、
```
ops.md
```
、
```
directives.md
```
、executor和supervisor部分；不要创建第二个运行时模板或计分板。

仍然需要探查工作区。仍然最多提出三个所有者问题；在绑定预设包的情况下，通常是范围、权限和启动模式。仍然基于本技能的

templates/

生成 — 绝不使用第二套模板，绝不添加第三个运行时节点。预设技能不会执行生成的节点。

How to run it

运行方式

Step 1 — Discover, then interview. Before asking anything, inspect the workspace and current system/tool context. Infer the current authoring host, project root, repos, branches, dirty state, repo instructions, likely gates, and any explicit goal/constraints. Never ask the user which client or host this is when the system context already identifies it. Capture the dirty-state baseline before this session changes anything — whatever you go on to move, archive, generate, or delete becomes indistinguishable from the owner's uncommitted work unless your own paths are enumerated in the ledger's starting snapshot. Keep authoring probes side-effect-free: direct scratch output into the new run's evidence directory, suppress tool caches when possible, and remove a known artifact this session created before handing off. An authoring run must not leave a product-path cache masquerading as owner work.

Ask one short batch of at most three questions containing only unresolved owner decisions. Propose the answer; do not ask the owner to design it. If more than three details remain, prioritize goal/proof, safety authority, and launch mode; infer or defer the rest. Ask a follow-up only when the run would otherwise be unsafe or unverifiable:

North Star and proof, only when the request does not already imply a checkable outcome. Offer one concise recommended wording.
Authority, only where not already stated. Recommended default: local edits and verification allowed; no push, destructive git, production/remote mutation, secret or real-data exposure, unbounded spend, or lowering an acceptance bar. Ask whether commits are allowed only when the run needs them. When the run performs metered or expensive work, put the actual numbers in
```
ops.md
```
— "spend beyond budget" is an owner-only tripwire, and an undeclared budget makes it unenforceable. Say what each gate actually costs: money, wall-clock, or risk. A gate that costs only time is batched, not rationed — a cap that puts a whole area of the work out of reach is a scope decision wearing a budget's clothes, and it belongs in the scope answer instead.
Milestones, only when two materially different decompositions exist. Present the recommended phase split and exit checks as A; offer B only when it changes the outcome or risk. Single goal means no milestone question. Sequence so the smallest slice that unblocks the main line comes first: a large enabling refactor placed ahead of the delivery milestone concentrates risk and delays every proof behind it. Split such a milestone into the narrow unblocking part and a remainder that runs alongside the main line instead of in front of it.
Launch mode, unless the user already chose it: A (Recommended) — create both runtime nodes here on the detected Codex or Claude Code host; B — print copy-ready prompts only. Ask target hosts only for B or when the user explicitly requests a cross-host run.

Do not ask for repo paths, branches, host, test commands, red lines, or cadences when they are discoverable. If a gate is missing or ambiguous after inspection, propose the narrowest credible command and ask one A/B choice. Long-horizon loop-graph runs include the supervisor by default; ask whether to omit it only when its value is genuinely doubtful.

For each supervised milestone boundary, name its exact promotion audit surface and exit checks. Expect the run to block often — owner decisions, missing inputs, unmet dependencies, a milestone under audit: seed the Debt & gap register with enough real, independent work that the executor always has a legal next item instead of ending the fire early.

When the work has to be found, seed the method — not the list. For runs whose items are discovered (dead code, duplication, coverage holes, stale config), you see one context window of a tree the run will cross many times, so a hand-written candidate list becomes the run's ceiling: the executor works it, then reports done. Compile detectors, a refill quota (close N → discover at least N), and a rotation across the whole surface into

ops.md

and the ledger, and seed the register with the method plus measured baselines. Make termination a yield check — two consecutive full sweeps whose fresh detector pass yields under a threshold — never an empty queue. Pair it with an output floor per fire so productivity, not a round count, decides when a fire ends. Fix the owner-only decision list (typical: DDL/schema, credentials / remote env / real-data exposure, spend beyond budget, lowering a metric bar, frozen contracts, push) — everything off that list the supervisor decides itself.

Pre-adjudicate critical-path calls now. Research the project and draft the evidence bar yourself; do not ask the owner to design it. Present: A (Recommended) accept the drafted standing authorization, B keep the action owner-blocked, and only when real, C a clearly different safe alternative. Explain each outcome in plain language and accept a one-letter reply. Write accepted bars as STANDING directives. Only a decision that genuinely needs case-by-case human judgment stays blocking.
Owner decision UX is a runtime contract. Every later owner escalation must use the decision-card format below. The owner should not need to understand internal symbols, reconstruct history, or propose the solution.

text

Decision needed: <one plain-language sentence>
Why now: <what is blocked and what happens if we wait>
Recommendation: A — <choice> (<one-sentence reason>)
A (Recommended) — <outcome and main tradeoff>
B — <outcome and main tradeoff>
C — <only when genuinely distinct; otherwise omit>
Reply with: A / B / C

Use at most three mutually exclusive options. Put the safest reversible option first unless evidence clearly favors another. Translate technical evidence into consequences; place paths, commands, and jargon in an optional

Technical note

after the choices. Never end with "what do you think?" or make the owner invent option D. If no answer arrives, the run holds at the safe no-change state.

Host and cadence. Infer the current authoring host from system context and callable tools. Codex and Claude Code are the supported direct-launch planners. When A is chosen, place both runtime nodes on that detected host and read only its reference; do not ask about or print other-host syntax. When B or an explicit cross-host request is chosen, read one reference per selected node:

Claude Code
Codex
Grok Build
Cursor
shell / cron

Do not load unrelated host references. The selected reference owns capability checks, node creation, and how each node arms and stops its own timer. Other hosts may execute prepared prompts, but direct creation is supported only from Codex and Claude Code.

Set two cadences. The timer guarantees a node comes back; it does not pace it.

EXEC_INTERVAL

is how soon the executor returns after a fire ends — short, because the fire, not the interval, decides how much work happens.

SUP_INTERVAL

is 3–4× that, phase-offset, so the supervisor audits several times across a long fire.

Size the milestone to the fire, not the fire to a round count. A round stays one independently verifiable work item; that item may be the largest related workset that shares a behavior claim, write set, and gate. Every fire boundary pays a cold re-derivation, so one fire should carry a whole milestone and end at a seam — the milestone exit, or a closed convergence round. That makes milestone granularity the real context-cost lever: a milestone the executor cannot plausibly finish in one warm fire should be split, and

FIRE_ROUND_CAP

ends only that fire, never the run.

Compile context, do not narrate it. Host prompts are one-line pointers to the runtime Markdown. At authoring time, build an

ops.md

Context index with exact files, symbols/headings, evidence paths, and narrow gates. Every Current slice and correction points to those IDs. Runtime nodes read the hot state plus referenced rows only; they do not scan the workspace, reopen whole authority documents, or restate source text. The supervisor audits deltas since its durable watermark and runs full gates only at promotion/checkpoint or when a narrow gate is insufficient.

Decide from context what you reasonably can and state the assumption; anything genuinely the user's call (data policy, DB access, lowering a bar) becomes a red line, a standing authorization (offer your drafted recommendation as a choice), or an

owner-blocked

item (only if it truly can't be pre-decided). Never hand the owner an unstructured problem.

Step 2 — Generate a fresh

.longgraph/<YYYY-MM-DD-slug>/

from

templates/

Always:

executor.md

ledger.md

directives.md

ops.md

, and

archive/

. Add

supervisor.md

only when chosen.

Replace every placeholder and delete guidance comments. Keep paths inside the run directory.
Keep host launch prompts to a pointer plus the host primitive. Put behavior in
```
executor.md
```
/
```
supervisor.md
```
, never duplicate it in the handoff prompt. Two things matter in every launch prompt: read-and-follow, never an authoring verb ("set up", "create", "author", "plan" read as permission to build something, and a fresh node answers by creating a second run) — and "do not load any skill", because a host that matches skills by name or path can inject the authoring skill before the node opens its own file.
Owner-facing paste is a
/loop
line on every host that has
/loop
. Shape:
```
/loop {{INTERVAL}} Execute the existing runtime node at {{PATH}}. Do not load any skill.
```
Cadence, timer-ID recording, self-stop, and freshness belong in
```
TIMER_STEP
```
or the node file — never as extra owner steps ("write this ID into
```
ops.md
```
", "then create a scheduled task"). Codex has no
```
/loop
```
: the owner paste is the thin read-and-follow line. Mention creating a scheduled task or automation only when the owner explicitly asked; the compiled
```
TIMER_STEP
```
is what arms Codex.
Compile the
```
ops.md
```
Context index before writing the first ledger slice. Each row names when to read it, exact source pointers, and exact verification. Make the ledger Current slice and every directive cite those rows.
Tune the knobs; otherwise use
```
FIRE_ROUND_CAP=8
```
,
```
CONVERGE_EVERY=5
```
,
```
NET_LINE_CAP=400
```
,
```
KEEP_ROUNDS=5
```
,
```
OPEN_DIRECTIVE_CAP=8
```
,
```
STANDING_CAP=12
```
,
```
GAP_CAP=12
```
, and
```
FILE_LINE_CAP=200
```
. Open-ended runs add
```
FIRE_OUTPUT_FLOOR
```
(the closed items or net lines a fire must land before it may end) and
```
YIELD_FLOOR
```
(the per-sweep discovery count under which the run may go terminal).
Every durable section is bounded and rotates on a rule that actually fires. Rotate by count against a cap — rounds past
```
KEEP_ROUNDS
```
and corrections at or below the folded watermark move to
```
archive/
```
; STANDING and the gap register are capped and rewritten in place; no live file exceeds
```
FILE_LINE_CAP
```
lines. A rule keyed to a boundary that may never be reached (a fixed shard size, a milestone that slips) is the same as no rule: the file grows until a node truncates its read and silently misses the newest entry. Anything re-read every round that can only grow is a defect, not a style choice.
Fill
```
TIMER_STEP
```
from the selected reference. Delete it only when the node has nothing to arm, record, or stop. A
```
/loop
```
interval on the launch line is not a reason to delete
```
TIMER_STEP
```
if the node must still write its own timer ID or delete its own task. Never ask the owner to type a task, session, or automation ID into
```
ops.md
```
. Host-specific facts belong in references, not in the generic templates.
Name the host's cheap model tier as
```
FANOUT_TIER
```
in
```
ops.md
```
when the executor may spawn read-only sub-tasks; delete the section when the host has no cheap concurrent tier. Read-only investigators run cheap; the executor itself does not.
Render
```
templates/handoff.md
```
only as the chat response. It is a presentation template, not a runtime artifact: never save
```
handoff.md
```
in the run directory. Delete its supervisor section and the
```
To steer
```
line when no supervisor was selected.
Keep hot files lean: current state, unresolved rows, recent rounds, and unconsumed directives only.

Step 3 — Deliver without making the owner discover the workflow. Offer only when the user has not already chosen:

A (Recommended) — create both nodes here when the detected host is Codex or Claude Code.
B — prompts only when the owner will launch elsewhere.

Never end at "files generated." End with the exact next action and copy-ready prompt(s).

Create both nodes here: treat the user's A choice as authorization to create the two in-scope runtime sessions. Follow the selected reference's ordered capability check and creation protocol. Use the current project/checkout; do not create a cross-host prompt or silently switch to worktrees. Verify both nodes started, and report their IDs, both cadences, and how to stop them. Do not ask for a second confirmation.
Prompts only: render the completed
```
templates/handoff.md
```
in chat without persisting it. It must say how many sessions/tasks/processes to open, where each prompt goes, what continues automatically, how it stops, and how to steer. Never ask the owner to write host IDs or create a timer the compiled node already owns.
Never leave
```
{{PLACEHOLDER}}
```
text or tell the owner merely to "start the loop." Keep executor and supervisor in separate contexts; use a cheap/fast executor and a strong supervisor when available.

步骤1 — 探查，然后访谈。 在提问之前，请检查工作区和当前系统/工具上下文。推断当前的创作主机、项目根目录、仓库、分支、未提交状态、仓库说明、可能的门控规则，以及任何明确的目标/约束。当系统上下文已经可以识别时，绝不要询问用户这是哪个客户端或主机。 在本次会话修改任何内容之前，记录未提交状态的基线 — 除非你自己的路径被列在ledger的起始快照中，否则你后续移动、归档、生成或删除的任何内容都将与所有者未提交的工作无法区分。请确保创作探查无副作用：将临时输出定向到新运行的证据目录，尽可能禁用工具缓存，并在交接前删除本次会话创建的已知构件。创作运行绝不能留下伪装成所有者工作的产品路径缓存。

一次性提出最多三个问题，仅包含未解决的所有者决策。请给出建议答案；不要让所有者来设计方案。如果剩余的细节超过三个，请优先处理目标/验证标准、安全权限和启动模式；其余内容可推断或延后。仅当运行会因此不安全或无法验证时，才提出后续问题：

北极星目标与验证标准，仅当请求未隐含可验证的成果时提出。提供一份简洁的推荐表述。
权限，仅当未明确说明时提出。推荐默认值：允许本地编辑和验证；不允许推送、破坏性git操作、生产/远程环境变更、密钥或真实数据暴露、无限制支出，或者降低验收标准。仅当运行需要时，才询问是否允许提交。当运行涉及计量或高成本工作时，将实际数值写入
```
ops.md
```
— “超出预算支出”是仅由所有者决策的警戒线，而未声明的预算会导致该规则无法执行。请说明每个门控的实际成本：金钱、实际时间或风险。仅消耗时间的门控应批量处理而非定量分配 — 如果一个上限将整个工作领域都排除在外，那这是一个伪装成预算的范围决策，应该放在范围答案中。
里程碑，仅当存在两种实质性不同的拆解方案时提出。将推荐的阶段划分和退出检查作为选项A呈现；仅当选项B会改变成果或风险时才提供。单一目标意味着不需要里程碑问题。排序时，让能打通主线的最小切片优先：将大型支撑性重构放在交付里程碑之前会集中风险，并延迟后续所有验证。请将此类里程碑拆分为狭窄的解阻塞部分和剩余部分，剩余部分与主线并行运行而非放在前面。
启动模式，除非用户已经选择：A（推荐）— 在检测到的Codex或Claude Code主机上创建两个运行时节点；B — 仅打印可直接复制的提示词。仅当选择B或用户明确要求跨主机运行时，才询问目标主机。

如果仓库路径、分支、主机、测试命令、红线或运行节奏是可探查的，就不要询问。如果检查后发现某个门控缺失或不明确，提出最窄范围的可信命令，并给出A/B选择。长期loop-graph运行默认包含supervisor；仅当其价值确实存疑时，才询问是否省略。

对于每个受监督的里程碑边界，请明确其确切的升级审计范围和退出检查项。要预料到运行会经常阻塞 — 所有者决策、缺失输入、未满足的依赖、正在审计的里程碑：请在债务与缺口登记册中预置足够多的真实、独立的工作，确保executor总有合法的下一个工作项，而不是提前结束本次触发。

当工作项需要被发现时，请预置方法而非列表。 对于工作项需要动态发现的运行（死代码、重复代码、覆盖率漏洞、过时配置），你只能看到运行将多次遍历的树的一个上下文窗口，因此手写的候选列表会成为运行的上限：executor处理完列表后，就会报告完成。请将检测器、补充配额（完成N项 → 至少发现N项）以及覆盖整个范围的轮转机制编入

ops.md

和ledger，并在登记册中预置方法和已测量的基线。将终止条件设为产出检查 — 连续两次全量扫描中，检测器新发现的项低于阈值 — 而不是队列为空。同时为每次触发设置产出下限，这样由生产率而非轮次数量决定触发何时结束。确定仅由所有者决策的列表（典型项：DDL/模式、凭证/远程环境/真实数据暴露、超出预算支出、降低指标标准、冻结的契约、推送）— 不在该列表中的所有事项都由supervisor自行决定。

现在就预先裁决关键路径上的决策。 研究项目并自行起草证据标准；不要让所有者来设计。呈现：A（推荐） 接受起草的常设授权，B 保持该操作由所有者阻塞，以及仅当确实存在时的C 一个明显不同的安全替代方案。用平实的语言解释每个结果，并接受单字母回复。将接受的标准写入STANDING指令。只有真正需要逐案人工判断的决策才保持阻塞状态。
所有者决策的用户体验是运行时契约。 后续每次所有者升级都必须使用下面的决策卡格式。所有者不需要理解内部符号、重建历史或提出解决方案。

text

Decision needed: <one plain-language sentence>
Why now: <what is blocked and what happens if we wait>
Recommendation: A — <choice> (<one-sentence reason>)
A (Recommended) — <outcome and main tradeoff>
B — <outcome and main tradeoff>
C — <only when genuinely distinct; otherwise omit>
Reply with: A / B / C

最多使用三个互斥选项。将最安全的可逆选项放在首位，除非证据明显支持另一个选项。将技术证据转化为后果；将路径、命令和术语放在选项后面可选的

Technical note

（技术说明）中。绝不要以“你怎么看？”结尾，也不要让所有者想出选项D。如果没有收到回复，运行将保持在安全的无变更状态。

主机与运行节奏。 从系统上下文和可调用工具推断当前的创作主机。Codex和Claude Code是支持直接启动的规划器。选择A时，将两个运行时节点都放在检测到的主机上，仅读取其参考文档；不要询问或打印其他主机的语法。选择B或明确要求跨主机运行时，为每个选定的节点读取一份参考文档：

Claude Code
Codex
Grok Build
Cursor
shell / cron

不要加载不相关的主机参考文档。选定的参考文档负责能力检查、节点创建，以及每个节点如何启动和停止自己的计时器。其他主机可以执行准备好的提示词，但仅支持从Codex和Claude Code直接创建。

设置两个运行节奏。计时器保证节点会返回，但不决定运行速度。

EXEC_INTERVAL

是executor在一次触发结束后多久返回 — 这个时间很短，因为工作量由触发而非间隔决定。

SUP_INTERVAL

是其3-4倍，且相位偏移，这样supervisor会在一次长触发过程中进行多次审计。

里程碑的规模要适配单次触发的工作量，而非让触发去适配轮次数量。 每轮仍然是一个可独立验证的工作项；该工作项可以是共享同一个行为声明、写入集和门控的最大相关工作集。每次触发边界都需要付出冷启动重推导的成本，因此一次触发应该完成整个里程碑，并在接缝处结束 — 即里程碑出口，或者一个已完成的收敛轮次。这使得里程碑粒度成为真正的上下文成本杠杆：如果executor在一次热触发中无法合理完成某个里程碑，就应该拆分它，而

FIRE_ROUND_CAP

只会结束本次触发，绝不会终止整个运行。

编译上下文，而非叙述上下文。 主机提示词是指向运行时Markdown文件的单行指针。在创作阶段，构建

ops.md

的上下文索引，包含确切的文件、符号/标题、证据路径和窄范围门控。每个当前切片和纠正意见都指向这些ID。运行时节点仅读取热状态和被引用的行；它们不会扫描工作区、重新打开完整的权限文档或重述源文本。supervisor审计自其持久化水印以来的增量，仅在升级/检查点或者窄范围门控不足时才运行完整门控。

从上下文中合理地决定你能决定的内容，并说明假设；任何真正需要用户决定的事项（数据政策、数据库访问、降低标准）要么成为红线，要么成为常设授权（将你起草的推荐方案作为选项提供），要么成为

owner-blocked

（所有者阻塞）项（仅当确实无法预先决定时）。绝不要把非结构化的问题丢给所有者。

步骤2 — 生成 从

templates/

生成全新的

.longgraph/<YYYY-MM-DD-slug>/

始终包含：
```
executor.md
```
、
```
ledger.md
```
、
```
directives.md
```
、
```
ops.md
```
和
```
archive/
```
。仅当选择了supervisor时才添加
```
supervisor.md
```
。
替换所有占位符并删除指导注释。路径保持在运行目录内。
主机启动提示词仅保留指针和主机原语。将行为逻辑放在
```
executor.md
```
/
```
supervisor.md
```
中，绝不要在交接提示词中重复。每个启动提示词中最重要的两点：读取并遵循，绝不要使用创作类动词（“设置”、“创建”、“编写”、“规划”这类词会被解读为允许构建内容，新节点会因此创建第二个运行）— 以及**“不要加载任何skill”**，因为按名称或路径匹配skill的主机会在节点打开自己的文件之前注入创作技能。
面向所有者的粘贴内容是每个支持
/loop
的主机上的一行
/loop
命令。格式：
```
/loop {{INTERVAL}} Execute the existing runtime node at {{PATH}}. Do not load any skill.
```
运行节奏、计时器ID记录、自停止和新鲜度检查都应该放在
```
TIMER_STEP
```
或节点文件中 — 绝不要作为额外的所有者步骤（“将此ID写入
```
ops.md
```
”、“然后创建定时任务”）。Codex没有
```
/loop
```
：所有者粘贴的内容是精简的读取并遵循行。仅当所有者明确要求时才提及创建定时任务或自动化；编译后的
```
TIMER_STEP
```
才是启动Codex的关键。
在写入第一个ledger切片之前，先编译
```
ops.md
```
的上下文索引。每一行都说明读取时机、确切的源指针和确切的验证方式。让ledger的当前切片和每个指令都引用这些行。
调整参数；否则使用默认值：
```
FIRE_ROUND_CAP=8
```
、
```
CONVERGE_EVERY=5
```
、
```
NET_LINE_CAP=400
```
、
```
KEEP_ROUNDS=5
```
、
```
OPEN_DIRECTIVE_CAP=8
```
、
```
STANDING_CAP=12
```
、
```
GAP_CAP=12
```
和
```
FILE_LINE_CAP=200
```
。开放式运行需要添加
```
FIRE_OUTPUT_FLOOR
```
（一次触发必须完成的关闭项或净行数，达到后才能结束）和
```
YIELD_FLOOR
```
（每次扫描的发现数量低于该值时，运行可进入终止状态）。
每个持久化部分都是有界的，并且按照实际会触发的规则进行轮转。 根据上限按数量轮转 — 超过
```
KEEP_ROUNDS
```
的轮次和已合并水印及以下的纠正意见会移动到
```
archive/
```
；STANDING和缺口登记册有上限，并就地重写；任何活动文件的行数都不得超过
```
FILE_LINE_CAP
```
。如果规则绑定的是可能永远不会到达的边界（固定的分片大小、延期的里程碑），那就等于没有规则：文件会不断增长，直到节点截断读取内容，从而静默错过最新条目。任何每轮都会重新读取且只会增长的内容都是缺陷，而非风格选择。
从选定的参考文档中填充
```
TIMER_STEP
```
。仅当节点没有需要启动、记录或停止的内容时才删除它。如果节点仍然需要写入自己的计时器ID或删除自己的任务，那么启动行上的
```
/loop
```
间隔不能成为删除
```
TIMER_STEP
```
的理由。绝不要要求所有者将任务、会话或自动化ID输入到
```
ops.md
```
中。主机特定的事实属于参考文档，而非通用模板。
当executor可能生成只读子任务时，在
```
ops.md
```
中将主机的廉价模型层命名为
```
FANOUT_TIER
```
；如果主机没有廉价并发层，则删除该部分。只读调查任务运行成本低；executor本身则不然。
仅将
```
templates/handoff.md
```
渲染为聊天响应。它是一个展示模板，而非运行时构件：绝不要将
```
handoff.md
```
保存在运行目录中。如果未选择supervisor，则删除其中的supervisor部分和
```
To steer
```
行。
保持热文件精简：仅包含当前状态、未解决的行、最近的轮次和未处理的指令。

步骤3 — 交付，不要让所有者去摸索工作流。 仅当用户尚未选择时提供选项：

A（推荐）— 在此创建两个节点，当检测到的主机是Codex或Claude Code时。
B — 仅提供提示词，当所有者将在其他地方启动时。

绝不要以“文件已生成”结尾。要以确切的下一步操作和可直接复制的提示词结束。

在此创建两个节点： 将用户的A选择视为创建两个范围内运行时会话的授权。遵循选定参考文档的有序能力检查和创建协议。使用当前项目/检出；不要创建跨主机提示词，也不要静默切换到工作树。验证两个节点都已启动，并报告它们的ID、两个运行节奏以及停止方法。不要要求二次确认。
仅提供提示词： 在聊天中渲染完成的
```
templates/handoff.md
```
，不要持久化保存。必须说明要打开多少个会话/任务/进程，每个提示词放在哪里，什么会自动继续，如何停止，以及如何引导。绝不要要求所有者写入主机ID或创建编译后的节点已经自带的计时器。
绝不要留下
```
{{PLACEHOLDER}}
```
文本，或者仅仅告诉所有者“启动循环”。将executor和supervisor保持在独立的上下文中；如果可用，使用廉价/快速的executor和强大的supervisor。

The rules that make it work (encoded in the templates)

使其正常运行的规则（已编码在模板中）

```
ledger.md
```
is the single, bounded scoreboard; executor writes it, supervisor never does.
One independently verifiable work item per round: implement, verify, record. A related workset shares one behavior claim, write set, and gate; unrelated work stays separate. Register side-gaps for later.
Each node owns one timer and wakes only itself; blocked work moves to the registered lane instead of ending the fire.
Force convergence off durable state the supervisor audits; pilot expensive batches; require a real consumer before new surface area.
Count only reproducible evidence on the declared real set.
Pre-authorize checkable owner calls; present genuine exceptions as recommended A/B/C choices.
Keep the supervisor's context separate; it re-verifies, steers only through directives, and stops its own timer at terminal state.

```
ledger.md
```
是唯一的、有界的计分板；executor写入它，supervisor绝不写入。
每轮完成一个可独立验证的工作项：实现、验证、记录。相关工作集共享同一个行为声明、写入集和门控；不相关的工作保持分离。将侧边缺口登记下来以便后续处理。
每个节点拥有自己的计时器，且仅唤醒自己；被阻塞的工作会移动到登记通道，而不是结束本次触发。
基于supervisor审计的持久化状态强制收敛；高成本批次先试点；新的功能面需要有真实的使用者才能添加。
仅统计声明的真实集合上可复现的证据。
预先授权可检查的所有者决策；将真正的例外情况作为推荐的A/B/C选项呈现。
保持supervisor的上下文独立；它仅进行重新验证，通过指令引导流程，并在终止状态时停止自己的计时器。

Files in this skill

本技能包含的文件

```
templates/
```
— host-neutral runtime artifacts plus a chat-only launch-prompt template.
```
references/
```
— one small, independently loaded file per host.
```
methodology.md
```
— the deep dive (why each rule exists, failure modes it prevents).
```
examples/add-tests-to-cli/
```
— a fully worked, generic example.
```
examples/migrate-blob-storage/
```
— a longer worked example: milestones, a cohort pilot, a supervisor directive in action, and the non-skippable milestone gate blocking until the supervisor audits and releases.

```
templates/
```
— 与主机无关的运行时构件，以及仅用于聊天的启动提示词模板。
```
references/
```
— 每个主机对应一个小型的独立加载文件。
```
methodology.md
```
— 深入探讨（每条规则存在的原因，它预防的故障模式）。
```
examples/add-tests-to-cli/
```
— 一个完整的通用示例。
```
examples/migrate-blob-storage/
```
— 一个更完整的长示例：包含里程碑、队列试点、实际运行的supervisor指令，以及在supervisor审计并放行之前会一直阻塞的不可跳过里程碑门控。