@dipoleml/dcode-cli 1.0.0 → 1.2.0

package/dist/packages/bundled-skills/skills/dynamic-workflows/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dynamic-workflows
-description: "Use when writing, debugging, or resubmitting a dynamic-workflow script for the CreateWorkflow tool: choosing subagent topology, typing subagent results, fanning out over files or git, gating loops on world.run commands, testing pieces with EvalWorkflowSnippet, planner-reviewer loops, confirming findings before reporting them, report() salvage, the report shape a run returns, publishing artifacts the user opens, and handling a backgrounded run."
+description: "Use when writing, debugging, or resubmitting a dynamic-workflow script for the CreateWorkflow tool: choosing subagent topology, typing subagent results, fanning out over files or git, gating loops on world.run commands, testing pieces with EvalWorkflowSnippet, planner-reviewer loops, confirming findings before reporting them, report() salvage, the report shape a run returns, publishing artifacts the user opens, leaving typed holes to fill mid-run, and handling a backgrounded run."
 when_to_use: "Only for CreateWorkflow scripts. A single delegation or a few independent lookups belong to the Agent tool instead."
 ---
 
@@ -8,8 +8,8 @@ when_to_use: "Only for CreateWorkflow scripts. A single delegation or a few inde
 
 This skill is the whole authoring contract for `CreateWorkflow`. The tool descriptions are
 short on purpose; the facade the compiler checks against, the rules a script must satisfy and
-the fields each tool takes are in §16, and `CreateWorkflow`, `AmendWorkflow`, `SaveWorkflow`
-and `EvalWorkflowSnippet` refuse to run until this skill has been loaded in the session. The
+the fields each tool takes are in §16, and `CreateWorkflow`, `AmendWorkflow`, `FillWorkflowHole`,
+`SaveWorkflow` and `EvalWorkflowSnippet` refuse to run until this skill has been loaded. The
 rest is the judgment layer: how many subagents a request deserves, which of them should share
 a context, what each one should hand back, and how to keep the run's work from dying with the
 run.
@@ -28,11 +28,10 @@ on every plan and every draft (§3), an independent confirmation of every findin
 deterministic checks wherever a command can decide, and a report that says what was
 verified, what was not, and what it all means.
 Depth is measured by what is at stake, not by how many subagents re-read the same work:
-verification is spent where a wrong claim would cost the user something, and each piece of
-work gets the one check that decides it, not every check this skill knows.
-When a shortcut and the expert's way disagree, take the expert's way. Trim the work only when
-the task is genuinely small, never because thoroughness is inconvenient; trim the checking
-when a wrong claim costs little or a command has already decided it.
+verification goes where a wrong claim would cost the user something, and each piece of work
+gets the one check that decides it. When a shortcut and the expert's way disagree, take the
+expert's way; trim the work only when the task is small, and trim the checking when a wrong
+claim costs little or a command has already decided it.
 
 ## 1. Is this the right tool, and how big should it be?
 
@@ -40,39 +39,37 @@ when a wrong claim costs little or a command has already decided it.
 | --- | --- |
 | One thing delegated to one agent | `Agent` |
 | A few independent lookups, nobody reading anybody's answer | `Agent`, in parallel |
-| Anything else the user did not name a workflow for — however many steps or subagents it needs | `Agent`, or do it yourself |
+| Anything else the user did not name a workflow for, however many steps it needs | `Agent`, or do it yourself |
 | The user said "use a workflow" / "使用 workflow" / "用工作流" — any phrasing naming workflow as the means | `CreateWorkflow`, mandatory, even if `Agent` would have done or one reply could answer |
 
-**Only an explicit request starts a workflow.** The request is the whole routing rule: a
-workflow begins with `/workflow` or with the user naming workflow/工作流 as the means, never
-with your own judgement that a task looks orchestration-shaped. Results feeding later steps,
-a loop with a stopping condition, control flow branching on a typed result — none of these
-are a reason to start one. Delegate with `Agent` or do the work yourself.
+**Only an explicit request starts a workflow.** A workflow begins with `/workflow` or with
+the user naming workflow/工作流 as the means, never with your own judgement that a task
+looks orchestration-shaped. Results feeding later steps, a bounded loop, a branch on a typed
+result — those are shapes the script is good at once one has been requested, not reasons
+there should be one. Delegate with `Agent` or do the work yourself.
 
-**An explicit request is binding.** When the user names workflow/工作流 as the way to do the
-task, the routing question is closed: not `Agent`, not doing it inline, not "this is too small
-for a workflow". The user picked the tool; what remains for you is only how big the script
-should be, and the smallest task still gets a small workflow rather than something else.
-
-Once a workflow has been requested, these are the shapes it is good at, and what the script
-should reach for: results feeding later steps (pipelines, fan-out then fan-in), a loop with a
-stopping condition, and control flow branching on a typed result. They describe how to build
-the workflow the user asked for — they never decide that there should be one.
+**An explicit request is binding.** Once the user names workflow/工作流 as the means, the
+routing question is closed — not `Agent`, not inline, not "too small for a workflow"; what
+remains is only how big the script should be, and the smallest task gets a small workflow.
 
 An explicit workflow request is a request for depth, and the bar above is the measure.
 Default to the thorough shape — a fresh subagent per unit of work, a deterministic gate
 wherever a command can decide, an independent confirmation of every finding the user will
-act on as fact (§10) — and size the checking to the stakes: a bug the user will fix on your
-word gets a confirmer; a poem, a brainstorm or a survey gets a reader at most. Cost still
-counts: every task is a full model session with its own context, so put the sessions where
-they raise confidence, not where they repeat each other. "Review the changed files" wants
-one reviewer per changed file plus one confirmer per finding; a three-line question wants
-neither; "write me twenty poems" wants twenty poets and no confirmers.
+act on as fact (§10) — sized to the stakes: a bug the user will fix on your word gets a
+confirmer; a poem or a survey gets a reader at most. Every task is a full model session, so
+put sessions where they raise confidence, not where they repeat each other: "review the
+changed files" wants a reviewer per file plus a confirmer per finding; "write me twenty
+poems" wants twenty poets and no confirmers.
+
+**Write only as much of that shape as you know for sure.** Where a later stage depends on
+what an earlier one finds, write up to that point, end in a hole (§15), and let the findings
+write the rest. Guessing a topology is not depth.
 
 ## 2. Subagent topology
 
-This is the decision that separates a good script from a bad one, and there are four parts
-to it.
+This is the decision that separates a good script from a bad one. It is made twice: now,
+for what the request already tells you, and at a hole (§15), for what only the run can tell
+you. This section is about the first, in four parts.
 
 **Fresh subagent per item, or one shared subagent?** Every `agent()` call creates a new context.
 Sharing a context means sharing the *variable*:
@@ -87,36 +84,33 @@ const judge = agent("judge", "You rank consistently across a whole batch.");
 items.map((i) => judge.ask<Verdict>(`Judge ${i.id}`));
 ```
 
-Both are correct for different jobs. Independent is right when the items are unrelated and
-you want parallelism; shared is right when the answers must be consistent with each other,
-and you are paying serialization for that consistency. Choosing shared by accident — by
-hoisting the `agent()` call out of a loop for tidiness — turns a parallel fan-out into a
-queue. Nothing rejects that script; the run simply takes as long as every item in a row.
-
-**A name is an identity, and it has to be unique.** Naming is optional, but no two subagents
-in one run may share a non-empty name — a duplicate fails the whole run. Note what that
-means for the first snippet above: one fixed name inside a fan-out is a duplicate once per
-item, so it is written `` agent(`judge-${i.id}`) ``, per item. The compiler catches the
-literal form (`agent("judge")` inside a `.map`/`for...of`) before you submit; a name built
-at run time it cannot see, so that one costs you the run. Anonymous is always safe: drop
-the name when you have nothing per-item to build one from.
-
-Names are worth giving anyway, because they are how a **revised** re-run finds its cache
-(§13): resubmitting a fixed script with `AmendWorkflow` imports, per named subagent, every ask
-whose instructions did not change — at zero tokens, up to the first ask that has to run
-live. Stable, meaningful names are what makes that hit. Anonymous subagents are legal
-and simply always start with an empty context.
-
-**Persona, frozen at creation.** A persona stacks on top of the harness's own workflow
-subagent contract — citing `path:line`, never reporting a check it did not run, saying
-plainly what it could not do, escalating instead of faking — so write the role and the
-standard of judgement, and leave those rules out; they are already there. Every subagent
-has the same tools — reading, searching, editing, running commands — and runs on the
-session's model; there is no per-subagent tool profile or model choice. What a subagent may
-do with its tools is said in the ask: a reviewer that must not touch the code is told "do not
-edit any file", a judge of a string is handed the string and told to judge it as given. A
-subagent asked to run a check runs it; one told not to edit does not. None of this can
-change after `agent()` — there is no per-task override.
+Independent is right for unrelated items; shared is right when the answers must be
+consistent with each other, at the price of serialization. Hoisting the `agent()` call out
+of a loop for tidiness turns a fan-out into a queue, and nothing rejects that script.
+
+**A name is an identity, and it has to be unique.** No two subagents in one run may share a
+non-empty name — a duplicate fails the run. One fixed name inside a fan-out is a duplicate
+per item, so write `` agent(`judge-${i.id}`) ``; the compiler catches the literal form, a
+name built at run time costs you the run. Anonymous is always safe.
+
+Names are worth giving anyway: a **revised** re-run finds its cache by them (§13),
+importing every ask whose instructions did not change at zero tokens. Anonymous subagents
+start empty.
+
+**Persona, frozen at creation.** A persona stacks on the harness's own subagent contract —
+citing `path:line`, never reporting a check it did not run, saying what it could not do,
+escalating instead of faking — so write the role and the standard of judgement and leave
+those rules out. Every subagent has the same tools; what it may do with them is said in the
+ask: a reviewer that must not touch the code is told "do not edit any file".
+
+**Per-subagent model**, only when asked or a light tier is obvious (judges, routers):
+`agent("judge", { model: "Raven Flash" })`, ids from `ListModels`. A literal or a `model()`
+ModelRef; to route, map the router's typed key to a `model()` table (`patterns.md` #13).
+
+**Where each item goes next.** A run with more than one stage is a pipeline: an item leaves
+its stage as soon as it is done, and the next stage takes it while the rest are still being
+worked on. Decide this at every hand-off when you lay out the topology, and let a stage wait
+for all of its items only where the next step needs every one. §7 says how to write each case.
 
 **Loops.** Bound every loop with a round cap, and carry the feedback forward:
 
@@ -130,14 +124,12 @@ for (let round = 0; round < 5; round++) {
 }
 ```
 
-Reuse the same two subagents across rounds — that is the point. A subagent asked more than once
-keeps its accumulated context and gets long-lived caching, so round five is cheap. Creating
-a fresh planner each round throws away everything it learned in round four. The one thing
-reuse costs you is freshness: by round three the reviewer is anchored on its own earlier
-critique. Keep the persistent reviewer for continuity and add an independent one at the end (§3).
+Reuse the same two subagents across rounds: a subagent asked again keeps its context, so
+round five is cheap. Reuse costs freshness — by round three the reviewer is anchored on its
+own critique — so add an independent one at the end (§3).
 
-**No nesting.** Subagents cannot call `CreateWorkflow`. If a task is big enough to want its own
-workflow, model it as more subagents here.
+**No nesting.** Subagents cannot call `CreateWorkflow`; model a big sub-task as more subagents
+here.
 
 ## 3. Fresh eyes
 
@@ -156,29 +148,23 @@ Four rules make the eyes actually fresh:
 - **Ask for failures, not approval.** "Is this good?" gets a yes. "What would break this?
   What is missing? Restate the plan in your own words" gets findings. Write the ask so
   that approving takes evidence and objecting is the easy move.
-- **Give the eyes the same evidence.** A reviewer told to judge a plan about code from the
-  plan's text alone can only judge coherence. To judge correctness it must read the code:
-  tell plan reviewers to read the files the plan touches, and not to edit them.
+- **Give the eyes the same evidence.** A reviewer judging a plan about code from its text
+  alone can only judge coherence: tell plan reviewers to read the files the plan touches,
+  and not to edit them.
 - **Give a prose deliverable an independent read.** When the deliverable is text nothing else
-  checked — a guide, an analysis, a write-up — hand it, before the script returns, to a
-  reader-proxy subagent asked what is unclear, what the text itself fails to support, and
-  what the user will ask next — then fix those, not the prose. Say in the ask that it judges
-  the report as a reader would, from the text alone, so it does not wander off to verify it
-  against the repository. If you want claims checked, that is a confirmer that reads the
-  code, not an independent read. A report whose findings were each confirmed (§10) has
-  already had its eyes; do not add a reader on top of the confirmers.
-
-Three cautions. Correlated reviewers add little — same model, same prompt, same blind
-spots — so give each a distinct lens or a different task. Bound it: one deliverable gets one
-mechanism — a plan gets a reviewer who reads the code, findings get a confirmer, prose gets a
-reader. A draft that came out of a planner–reviewer loop and then passed a fresh final
-reviewer has had its fresh eyes; a reader-proxy pass over the same text is a third session
-re-reading work two have already read. Two mechanisms on one deliverable is the ceiling, and
-it needs a reason you can say. And the rules above are about the subagents *inside* the
-script, not a gate on submitting it: reading your own script once against the request is
-normally enough, and the run confirmation already puts the plan in front of the user. An
-independent read of the script by a fresh `Agent` is an option for a genuinely hard one — many
-phases, subtle gates — not a routine step.
+  checked — a guide, an analysis — hand it, before the script returns, to a reader-proxy
+  subagent asked what is unclear, what the text fails to support, and what the user will ask
+  next; then fix those. Say it judges from the text alone — checking claims is a confirmer's
+  job. A report whose
+  findings were each confirmed (§10) has had its eyes; add no reader on top.
+
+Three cautions. Correlated reviewers add little — same model, same prompt, same blind spots
+— so give each a distinct lens. Bound it: one deliverable gets one mechanism — a plan a
+reviewer who reads the code, findings a confirmer, prose a reader; two is the ceiling, with
+a reason you can say. And these rules are about the subagents *inside* the script, not a gate
+on submitting it: read your own script once against the request, and at every `Promise.all`
+ask whether the next step needs every item; where it does not, pipeline it (§7). The
+confirmation window then puts the plan in front of the user.
 
 ## 4. Typed results
 
@@ -200,24 +186,20 @@ interface Finding {
 }
 ```
 
-Without the comments you get whatever the subagent guessed `severity` meant. With them you get
-a calibrated field, for the price of three lines.
+Without the comments you get whatever the subagent guessed `severity` meant.
 
-Keep results narrow. A result crosses a schema boundary and gets interpolated into the
-next prompt, so a wide one costs tokens twice. **Pass paths, not file contents** — a subagent
-has its own file tools and can read what it needs; handing it a stringified 4000-line file
-spends tokens to tell it something it could have fetched itself.
+Keep results narrow: a result crosses a schema boundary and gets interpolated into the next
+prompt, so a wide one costs tokens twice. **Pass paths, not file contents** — a subagent has
+its own file tools; a stringified 4000-line file spends tokens on what it could have read.
 
 ## 5. Getting the world in
 
-`files.glob` and `git.changedFiles` are how a script learns what to fan out over. Both are
-executed by the harness, recorded, and replayed from the record on resume.
+`files.glob` and `git.changedFiles` are how a script learns what to fan out over; both are
+executed by the harness, recorded, and replayed on resume.
 
-Caps **reject rather than truncate**: an over-wide `files.grep` fails that call instead of
-handing you a silently partial view of the workspace to fan out over. Narrow the pattern or
-add a glob filter. Reads are catchable, so a script that wants a coarser fallback writes one
-— which is exactly what you need for `git`, since every `git` call rejects outside a
-repository:
+Caps **reject rather than truncate** (§16.2), so narrow the pattern instead of fanning out
+over a silently partial view. Reads are catchable, so a coarser fallback is a `catch` —
+which `git` needs, since every `git` call rejects outside a repository:
 
 ```ts
 let paths: string[];
@@ -229,7 +211,7 @@ try {
 ```
 
 Reach for `files.read` or `files.grep` only when the *script itself* must shard or branch on
-content. Deciding which files to hand out is script work; reading them is subagent work.
+content; reading files is subagent work.
 
 **`world.run` is the deterministic gate.** When a check is fixed and machine-checkable — the
 build passes, the proof checks, the tests are green — run it as code and branch on the exit
@@ -240,28 +222,23 @@ const check = await world.run("lake", ["build"], { timeoutMs: 1_800_000 });
 if (check.exitCode !== 0) feedback = check.stderr;
 ```
 
-A nonzero exit code is a **value**, not an exception: the gating loop's normal case reads
-`exitCode` and carries `stderr` forward as the next round's feedback, with no `catch` in
-sight. Rejections are reserved for the world failing to answer — spawn failure, timeout
-(default 300s, override per call, no cap), or output over the per-stream cap. The command
-name must be a compile-time string literal, because the user approves the script's command
-set at confirmation: interpolate paths, flags and round numbers into the **args array**,
-never into the command. And keep the division of labor: open-ended editing belongs to a
-subagent with tools; `world.run` is for checks whose outcome your control flow branches on.
+A nonzero exit code is a **value**, not an exception: read `exitCode` and carry `stderr`
+forward as the next round's feedback, with no `catch`; rejections are for the world failing
+to answer (spawn failure, timeout, output over the cap). The command name must be a
+compile-time string literal, because the user approves the script's command set at
+confirmation: interpolate paths, flags and round numbers into the **args array**, never into
+the command. Open-ended editing belongs to a subagent; `world.run` is for checks your
+control flow branches on.
 
 **Choose the gate before you write it.** A gate decides exactly as much as the check it
-runs, and the check the task needs is rarely the first one you would type from habit.
-Before the first `world.run`, find out what checks the repository actually has — the
-scripts in `package.json`, the targets in a `Makefile`, the CI config, the README's "run
-this to verify" line — and rank them by how much they decide: a unit suite over fixtures
-decides less than an integration or end-to-end suite, which decides less than the
-acceptance command the README names, and none of them decides a performance request the
-way the bench does. Then build the gate in two tiers. The fast tier may drive the rounds of
-a loop. The **strongest** tier the request implies decides the exit, and it runs for real at
-least once before the final `return` — even when the fast tier already said yes, because
-the fast tier cannot see what it does not test. When the strong tier is slow, give it the
-`timeoutMs` it needs; a faster substitute is a different check, not a cheaper version of
-the same one.
+runs. Before the first `world.run`, find out what checks the repository has — `package.json`
+scripts, `Makefile` targets, the CI config, the README's "run this to verify" line — and
+rank them by how much they decide: a unit suite decides less than an end-to-end suite, which decides less than
+the acceptance command the README names, and none decides a performance request the way
+the bench does. Then build the gate in two tiers: the fast tier may drive a loop's rounds;
+the **strongest** tier the request implies decides the exit and runs for real at least once
+before the final `return`, even when the fast tier said yes. Give a slow tier the
+`timeoutMs` it needs; a faster substitute is a different check.
 
 ```ts
 phase("Fix until the unit tests pass");
@@ -282,28 +259,26 @@ unverified work (§10).
 ## 6. Test the pieces before you commit
 
 A workflow script is final at submit. The fixed logic inside it does not have to be: run it
-through the `EvalWorkflowSnippet` tool first, which compiles and executes a snippet against
-the same compiler, sandbox and world-read path a real run uses, synchronously and without
-persisting anything. What passed there pastes into the workflow verbatim. Send the snippet
-as `code`, or as `path` to a file holding it when you have already written it out — the
-second try then costs an `Edit` rather than the whole snippet again.
-
-Snippet work is exactly the non-subagent part: what a glob really returns (workspace-relative,
-sorted), whether a grep pattern overruns its cap, how `world.run("lean", ...)`'s stderr
-parses, whether a gate predicate does what you meant. A snippet has `files.*`, `git.*`,
-`world.run` and `log`, but no `agent()` — orchestration cannot be rehearsed, only the pieces
-can. Testing a parse function by burning a full run is the expensive way to find a typo.
-Once you know which check decides the result (§5), run it once here as well: that tells you
-what its output looks like, whether it exits nonzero the way you assumed, and how long it
-takes — which is the `timeoutMs` you write, not a guess.
-
-## 7. Keep the script analyzable, and join only where the data needs everyone
-
-The harness recovers the dependency graph by reading your code before it runs, so write code
-whose data flow is visible. Node results flowing through plain variables, template
-interpolation, destructuring and small local helpers are all traced exactly. Stashing a
-result into a container and fishing it out later, or routing it through a clever indirection,
-earns an analyzability diagnostic instead.
+through the `EvalWorkflowSnippet` tool first (§16.6), synchronously and without persisting
+anything. What passed there pastes into the workflow verbatim. Send the snippet
+as `code`, or as `path` to a file holding it — the second try then costs an `Edit`.
+
+Snippet work is the non-subagent part: what a glob really returns, whether a grep pattern
+overruns its cap, how `world.run("lean", ...)`'s stderr parses, whether a gate predicate does
+what you meant. A snippet has `files.*`, `git.*`, `world.run` and `log`, but no `agent()`.
+Once you know which check decides the result (§5), run it once here too: that shows its
+output, whether it exits nonzero as you assumed, and how long it takes — the `timeoutMs` you
+write, not a guess.
+
+## 7. Pipeline by default; join only where the next step needs every item
+
+A workflow with more than one stage should run like a pipeline: every stage works at the
+same time, and each item moves on the moment it is ready. A reviewed file goes to its
+confirmer while the other files are still being reviewed; a fact goes to its checker while
+the researchers are still reading. Write it this way wherever the next step can take items
+one at a time, which is nearly every hand-off. Let a stage wait for all of its items only
+where the next step needs every one: a deduplication across files, a ranking on one scale, a
+synthesis. Those are the barriers, and a script has few of them.
 
 `Promise.all` is a join, and a join is a barrier: nothing after it starts until the slowest
 item before it has landed. Parallelism comes from *not awaiting yet*:
@@ -318,20 +293,21 @@ const all = await Promise.all(
 for (const p of paths) results.push(await agent(`reviewer-${p}`).ask<Review>(`Review ${p}`));
 ```
 
-**Join where the next step needs every item, and nowhere else.** When two stages map one to
-one — a reviewer per file and a confirmer per finding, a migrator per file and a checker per
-file — a barrier between them makes every confirmer wait for the slowest reviewer while the
-concurrency slots sit idle. Chain the stages per item inside the fan-out instead, and join
-once at the end:
+**Decide, at every hand-off, how an item leaves its stage:**
 
-```ts
-// ✗ Two barriers: no finding is confirmed until every file has been reviewed.
-const reviews = await Promise.all(paths.map((p) => agent(`reviewer-${p}`).ask<Review>(`Review ${p}`)));
-const confirmed = await Promise.all(
-  reviews.flatMap((r) => r.findings).map((f, i) => agent(`confirmer-${i}`).ask<Confirmation>(`Reproduce: ${JSON.stringify(f)}`)),
-);
+| The next step takes | The stages | Write |
+| --- | --- | --- |
+| one item at a time | one to one: a reviewer per file, a confirmer per finding, a migrator per file and a checker per file | the stages chained per item inside one fan-out, one join at the end |
+| one item at a time | a pool of shared workers serves a stage; items are still being found while the next stage works; a later stage sends work back; the stages read better as separate blocks | a `channel` between the stages, a `future` per stage |
+| every item at once | deduplication, a ranking on one scale, a synthesis, the final report | a join, with a comment saying what needs every item |
 
-// ✓ One join: each file's findings go to their confirmers the moment its review lands.
+**Chaining.** When two stages map one to one, a barrier between them makes every worker of
+the second stage wait for the slowest worker of the first while the run's concurrency slots
+sit idle. Chain the stages per item inside the fan-out instead, and join once at the end:
+
+```ts
+// One join: each file's findings go to their confirmers the moment its review lands
+// (two Promise.all — review every file, then confirm every finding — is the barrier).
 const confirmed = (
   await Promise.all(
     paths.map(async (p) => {
@@ -344,22 +320,88 @@ const confirmed = (
 ).flat();
 ```
 
-The stages that genuinely need everyone — a triage that ranks on one scale, a synthesis that
-deduplicates across findings — are the legitimate barriers, and they are few. A shared,
-calibrated subagent is not one of them: asks on it queue FIFO, so feeding it per item as
-results land keeps it consistent *and* keeps the pipeline moving (§11).
+A shared, calibrated subagent is not a barrier: asks on it queue first in, first out, so feed
+it each item as it lands and it stays consistent while the pipeline keeps moving (§11).
 
 One rejection inside `Promise.all` rejects the whole join and the sibling results with it.
 When one bad item should cost one item, catch inside the callback (examples #3) or use
 `Promise.allSettled` and read each outcome.
 
+**Channels.** Chaining covers stages that map one to one. It cannot write a stage served by a
+pool of shared workers, a producer still finding items while consumers work, stages laid out
+as separate blocks, or a feedback loop to an earlier stage. For those, a `channel<T>()`
+carries items between two stages and each stage is a `future(async () => { … })`. An item
+sent into the channel is taken by the next stage at once, by a worker that is waiting for it
+or by a new one started for it:
+
+```ts
+const facts = channel<Fact>("facts");
+const verified: Fact[] = [];
+
+const research = future(async () => {
+  phase("Research the topic from each angle");
+  try {
+    await Promise.all(
+      angles.map(async (angle) => {
+        const found = await agent(`researcher-${angle}`).ask<Research>(`Research ${angle}.`);
+        for (const fact of found.facts) facts.send(fact);
+      }),
+    );
+  } finally {
+    facts.close(); // the producer side owns the close; a failed researcher still ends the stream
+  }
+});
+
+const verify = future(async () => {
+  phase("Check each fact as it arrives");
+  await Promise.all(
+    [1, 2, 3].map(async (k) => {
+      const verifier = agent(`verifier-${k}`);
+      for await (const fact of facts) {
+        const verdict = await verifier.ask<Verdict>(`Does this hold? ${JSON.stringify(fact)}`);
+        if (verdict.holds) verified.push(fact);
+      }
+    }),
+  );
+});
+
+await Promise.all([research, verify]); // start every stage, then join once
+```
+
+The rules, in the order the code reads:
+
+- **A stage is a future.** Its marker first, then the workers (a `Promise.all` over K
+  `for await` loops on the input channel), then the output's `close()` in a `finally`. Start
+  every stage, then join all of them once with `Promise.all`, with no `await` between: while
+  you await one stage, a failure in another has no listener and surfaces as an unhandled
+  rejection instead of failing the run with its error.
+- **A channel where the next stage should start before the previous one ends; a join where it
+  needs every item.** Never a channel between two stages that need a barrier.
+- **A new subagent per item inside a consumer is a `future` inside the `for await`**, pushed
+  into an array and joined before the stage ends (examples #6); without that join the stage
+  ends when the channel closes with checks still running, and nothing reports it.
+- **A cycle is counted.** A feedback channel (a verifier sends a doubtful fact back for more
+  research) has no single producer who knows when it is done, so keep one count of open work
+  items: increment *before* finishing the item that produced the new work, close the feedback
+  channel when the count hits zero, bound the loop with a depth field on the item
+  (`patterns.md` #12).
+- **Pools trade cache reuse for consistency.** A pool of shared workers (`verifier-1…3`
+  above) judges on one scale, but which item lands on which worker depends on timing, so an
+  amendment that changes one upstream item misses the cache for the whole pool; a fresh
+  `verifier-${fact.id}` per item misses only itself. `send` never waits (the buffer is
+  unbounded); a channel nobody can send to any more fails the run as `ChannelDeadlock`.
+
+**Keep the data flow visible.** The harness recovers the dependency graph by reading your
+code before it runs: plain variables, template interpolation, destructuring and small local
+helpers are traced exactly; a result stashed in a container or behind an indirection earns a
+diagnostic.
+
 ## 8. Group the run into named phases
 
-Phases are required, not a nice-to-have. The user experiences a workflow through its
-phase graph: the confirmation dialog they approve is drawn one node per phase, and a
-dialog with thirty step cards in it is a dialog nobody reads. Cover the whole script —
-every stage gets a `phase("...")` marker at its head, and the arrows between the phases
-are inferred from the same analysis:
+Phases are required. The user experiences a workflow through its phase graph: the
+confirmation dialog is drawn one node per phase, and thirty step cards is a dialog nobody
+reads. Cover the whole script — every stage gets a `phase("...")` marker at its head; the
+arrows between phases are inferred:
 
 <!-- compile -->
 ```ts
@@ -403,57 +445,47 @@ const head = await world.run("git", ["rev-parse", "HEAD"]);
 return { approach: winner, commit: head.stdout.trim() };
 ```
 
-Five nodes — "Measure today's baseline" → "Make one improvement" → "Check that the tests
-still pass" → "Measure whether it is actually faster" (and back to "Make one improvement")
-→ "Collect the final numbers" — and they stay five when the real version of this script
-grows to thirty steps. That is the entire payoff: the user sees the story you had in your
-head instead of a wall of cards.
+Five nodes, with an arrow back from the bench to "Make one improvement" — and still five
+when the real script grows to thirty steps: the user sees the story instead of a wall of
+cards.
 
-Notice the two checks. The unit tests are the fast tier: they decide whether a round is
-worth measuring. The bench is the check the request was about, and it runs every time a
-round survives the tests — not once at the start to print a baseline and never again. A
-loop that gates on `cargo test` alone would crown the first round that compiles (§5).
+The unit tests are the fast tier that drives the rounds; the bench is the check the request
+was about, and it decides every round that survives them, not once at the start (§5).
 
 **Write the names for the user, not for the graph.** A phase name is a short natural
 phrase saying what this stage accomplishes for the user, written in the language the
 user is speaking in this session — "Research each changed file in parallel",
-"汇总并产出最终报告". Orchestration vocabulary the user never chose ("fan-out",
-"gate", "aggregate") names the machinery, not the work. Names must be compile-time
-string literals, so you cannot number rounds by interpolation — and you should not
-want to: two markers with the same name are one node, which is how a loop body stays
-one box across all its rounds.
-
-**Put the marker where the steps are.** A marker claims the rest of the block it sits
-in, nested blocks and inlined helper calls included, so a marker inside an `if` covers
-that branch and stops at its closing brace. Mark the block where the `ask` and
+"汇总并产出最终报告" (§9). Names are compile-time string literals, so you cannot number
+rounds by interpolation, and should not want to: two markers with the same name are one
+node, so a loop body stays one box across its rounds.
+
+**Put the marker where the steps are.** A marker claims the rest of the block it sits in,
+nested blocks and inlined helper calls included, so mark the block where the `ask` and
 `world.run` calls actually live.
 
-**Not inside a concurrent fan-out callback.** The run has one current phase, and every step
-is stamped with it at birth. Twenty `map(async …)` callbacks each re-entering
-`phase("Review")` and `phase("Confirm")` out of order would stamp each other's steps and
-count every re-entry as a round. A per-item pipeline (§7) is one phase, named for what it
-does to each item — "Review each changed file and confirm its findings as they land" — and
-the markers stay at the top level around it.
-
-**Every phase must contain at least one `ask` or one `world.run`.** A phase is a stage
-the user watches progress through. Plain script logic — reading `args`, shaping a
-prompt, sorting results, building the final `return` — runs in a flash and shows no
-progress, so it is not a stage; a phase made only of it sits on the timeline as a step
-that never does anything. Fold that logic into the phase before or after it. In
-particular, do not open a phase for the setup at the top of the script or for the
-`return` at the bottom; the first phase starts at the first ask, and the last phase is
-the last stage that asks or runs something. The same goes for a branch that only
-narrates: an `if` whose body is nothing but `report(...)` and `log(...)` does not get
-its own marker.
+**Not inside a concurrent fan-out callback.** Twenty `map(async …)` callbacks re-entering
+`phase("Review")` out of order would count every re-entry as a round. A per-item pipeline
+(§7) is one phase named for what it does to each item, with the markers at the top level
+around it.
+
+**One marker at the head of each stage's future.** Concurrent stages written as futures (§7)
+each open their body with their own `phase("...")`. Stamping is lexical — a step gets the
+phase the analyzer places it in, not the marker the engine passed last — so two stages
+running at once keep their own steps; still no marker in the per-item callback or the
+`for await` body.
+
+**Every phase must contain at least one `ask` or one `world.run`.** Plain script logic —
+reading `args`, shaping a prompt, building the `return` — shows no progress, so it is not a
+stage: fold it into the phase before or after it, and open none for the setup at the top,
+the `return` at the bottom, or a branch that only narrates with `report` and `log`.
 
 ## 9. Write for the user
 
 Six things you write are read by the user, not by the script: phase names, subagent names,
 `log` lines, artifact titles and the markdown you publish, the four report fields, and any
-question a subagent escalates. Write each one the way you would tell a colleague across the
-desk what is happening: say what the work is, in the words the user would use, in the
-language the user is speaking in this session. The machinery — fan-out, gate, node, stage,
-pipeline — is yours, not theirs, and so is the numbering.
+question a subagent escalates. Write each one as you would tell a colleague across the desk
+what is happening: what the work is, in the user's words and language. The machinery —
+fan-out, gate, node, stage, pipeline — is yours, not theirs, and so is the numbering.
 
 | Read by the user | Write | Not |
 | --- | --- | --- |
@@ -468,19 +500,15 @@ pipeline — is yours, not theirs, and so is the numbering.
 | Artifact title | Review report / 评审报告 | report-artifact-v1 / 产物输出 |
 | Escalation question | Should the threshold be 94 rather than 96? / 阈值应该是 94 而不是 96 吗？ | Requesting clarification regarding gate configuration parameters / 请求对门控配置参数进行澄清 |
 
-The method names in this skill — fresh eyes, independent read — are English idioms for you,
-not words for the user. Carry the idea across, not the words: in Chinese that is 独立复核 or
-换人复审, never a word-for-word rendering such as 冷读 or 冷眼, which are not Chinese.
-
-The language travels through your asks. Findings, summaries and anything else the user will
-read are written by subagents answering the ask you wrote, so write those asks in the user's
-language, or say in the ask which language to answer in. Otherwise a Chinese report arrives
-wrapping English findings.
+The method names in this skill — fresh eyes, independent read — are idioms for you, not
+words for the user: in Chinese that is 独立复核 or 换人复审, never 冷读 or 冷眼.
+The language travels through your asks: findings and summaries are written by subagents
+answering the ask you wrote, so write asks in the user's language, or say which language to
+answer in; otherwise a Chinese report arrives wrapping English findings.
 
 ## 10. Verify, report, deliver
 
-`log(...)` is narration for the human watching the run. Use it at the points where a reader
-would otherwise wonder whether anything is happening — after a fan-out is sized, at the top
+`log(...)` is narration for the human watching the run: after a fan-out is sized, at the top
 of each loop round.
 
 **Verify before you report, in proportion to what a wrong claim costs.** Verification
@@ -489,40 +517,32 @@ is real: a bug they will fix, a security claim, a number they will quote, a fact
 rests on. Each finding of that kind is confirmed independently before it reaches the user: a
 second subagent that reproduces the finding from its evidence alone — reading the code,
 running a check when one decides it, never editing — or a `world.run` command when one can
-decide. The reviewer that found the problem does not get to confirm it; self-confirmation is
-not confirmation. A finding that fails confirmation is **kept and labelled** `unconfirmed`,
-never silently dropped — a real issue the confirmer could not reproduce is still worth a
-human's eyes, and the label is what lets the user tell "seen" from "suspected".
+decide. The reviewer that found it does not confirm it. A finding that fails confirmation
+is **kept and labelled** `unconfirmed`, never silently dropped — a real issue the confirmer
+could not reproduce is still worth a human's eyes, and the label tells the user "seen" from
+"suspected".
 
 Three things that look like verification and are waste. A confirmer on a finding a
-`world.run` already decided: the exit code is the confirmation, so record the command in
-`verified` and move on. A confirmer on work nobody will act on as fact — poems, brainstormed
-options, a first-draft survey — which gets at most one independent read (§3). And a suite run
-three times because the hunter ran it, the confirmer ran it and then the script gated on it:
-a check the script runs as a gate is run once, by the script, and the asks say so ("the
-script runs the full suite after you; do not run it yourself") so the subagents spend their
-turns on what only they can do.
+`world.run` already decided: the exit code is the confirmation; record the command in
+`verified`. A confirmer on work nobody will act on as fact — poems, brainstormed options, a
+first-draft survey — which gets at most one independent read (§3). A suite run three times
+because the hunter, the confirmer and the gate each ran it: a gate runs once, by the script,
+and the asks say so ("the script runs the full suite after you; do not run it yourself").
 
 **Gate at the task's scale.** `verified` names the commands that actually decided the
-result, and the reader will hold them against what they asked for. A unit suite in
-`verified` and the end-to-end suite in `notCovered` is not a verified deliverable; it is an
-unverified one with a disclosure attached. `notCovered` is for what *could not* be checked —
-no test exists for it, the environment lacks the tool, the check needs something only the
-user has — never for a check that exists in the repository and was skipped because it is
-slow or because the fast tier already passed. If the strongest check the request implies
-exists and did not run, the run is not done: run it, or say in `conclusion` that the work
-is unverified and why (§5).
-
-**Salvage by report.** `report(...)` is different from `log` and more important: reported
-items are delivered with the completion notification **even when the run fails**. A
-forty-task run that dies on task twelve still did eleven tasks' worth of work, and `report`
-is the only thing that gets that work out. So report each finding at the moment it lands —
-after its confirmation, with its status — rather than accumulating an array and returning it
-at the end: the array is what you lose. Items are recorded, so a resumed run never shows the
-same one twice.
-
-Give open-ended work an explicit round cap in the script rather than an unbounded loop: the
-harness enforces no node limit, so a loop that never goes dry only ends when the user cancels.
+result, and the reader holds them against what they asked for. A unit suite in `verified`
+and the end-to-end suite in `notCovered` is an unverified deliverable with a disclosure
+attached. `notCovered` is for what *could not* be checked — no test exists, the environment
+lacks the tool, the check needs something only the user has — never for a check that exists
+and was skipped because it is slow. If the strongest check the request implies exists and
+did not run, the run is not done: run it, or say in `conclusion` that the work is unverified
+and why (§5).
+
+**Salvage by report.** `report(...)` is not `log`: reported items are delivered with the
+completion notification **even when the run fails**, which is how a run that dies on its
+twelfth task keeps eleven tasks' worth of work. Report each finding the moment it lands —
+after its confirmation, with its status — rather than accumulating an array to return at the
+end: the array is what you lose. Items are recorded, so a resumed run never shows one twice.
 
 **Deliver a report.** The script's final `return` is the handoff the main agent presents,
 in the order below; what the user themselves keep is the artifact of the next section.
@@ -561,9 +581,6 @@ const result: WorkflowReport = {
 return result;
 ```
 
-Before returning it, give it an independent read (§3): a reader-proxy subagent that has seen nothing else
-tells you what is unclear, unsupported, or missing, while there is still time to fix it.
-
 Each field has a reader. `conclusion` is the answer to what the user asked. `findings` carry
 their evidence and their status, so the user can tell what was seen from what was suspected.
 `verified` says what this run actually checked and how — the commands it ran, the files it
@@ -575,44 +592,31 @@ speaking in this session.
 is the other channel: things the *user* opens, shown as cards beside the run while it is
 still going and kept after it ends. Two habits:
 
-- **Every run publishes its deliverable.** The deliverable is whatever the user asked for.
-  When that is a thing — a webpage, a PDF, a spreadsheet, a generated site — a subagent writes
-  it into the workspace with its own tools and returns the path, and the script publishes that
-  path with `artifact.file`. Until it does, nothing the run left in the workspace exists as far
-  as the user is concerned, which is why "write it to `out/…` and return the path" belongs in
-  the ask that produces it. When the user asked for an answer — findings, a review, an
-  analysis — the deliverable is a report, and the `return` alone is not it: the return is a
-  compact handoff the main agent retells, while the user deserves the long form of the same
-  facts, the findings with their evidence, what was checked and what was not. Markdown
-  composed from the same values the return is built from is the usual shape; a subagent-written
-  document is fine when the user asked for one. Publish it once, at the end, when the facts are
-  settled. The one exception is a run whose whole answer is a line: a verdict, a number, a yes
-  or no. A page that restates one sentence is noise, so let the return carry it alone.
-  When the run publishes more than one artifact, mark the deliverable `{ primary: true }`: the
-  completion card and the run pane lead with it (its `description` is shown beside the title),
-  and the notification the main agent reads lists it first. One id per run; a run whose only
-  artifact is the deliverable needs no flag.
-- **A dashboard is for the person watching the run.** Its job is to answer "where is it, how
-  is it going" without opening anything. Declare one when the run has state worth watching
-  while it is still running: the key number after each round, which items are done and which
-  failed. Metrics or a chart when the watched thing is a number; a table or board when it is
-  a set of items with a status. Declare it once at the top, then tag the items you are
-  already reporting: `report(item, "perf")`. Nothing else is needed; the dashboard is a
-  projection of that stream, so it grows live and comes back identical after a resume. A run
-  that is over before anyone would look at it needs none.
-
-**Show what matters.** More artifacts is not more delivery: every card competes with the
-deliverable for the user's attention. Two tests decide what earns a card. Would the user open
-it on its own? If not, it is a section of the deliverable. Does it repeat another artifact? A
-CSV and a table of the same rows, a report and a copy of it, a chart and a metrics tile of the
-same number — one of each pair is noise. The common run publishes one deliverable, one
-dashboard when there is something to watch, and further files only when a subagent produced
-something else a person opens.
-
-Ids and the report tag are compile-time string literals. What a run can publish is therefore
-fixed at the moment the user approves the script, and an id assembled at runtime is a compile
-diagnostic rather than a surprise. Publishing an id a second time mints the next version and
-keeps the old one, so a file worth republishing each round costs you nothing to name once.
+- **Every run publishes its deliverable.** When the user asked for a thing — a webpage, a PDF
+  — a subagent writes it into the workspace and returns the path ("write it to `out/…` and
+  return the path" belongs in the ask), and the script publishes it with `artifact.file`;
+  until it does, nothing the run left in the workspace exists for the user. When the user
+  asked for an answer — findings, a review — the `return` is the compact handoff and the
+  deliverable is the long form of the same facts: markdown built from the values the return
+  is built from, published once, at the end. The exception is a run whose whole answer is a
+  line. With more than one artifact, mark the deliverable `{ primary: true }`: the completion
+  card, the run pane and the notification lead with it. One primary per run.
+- **A dashboard is for the person watching the run.** Declare one when the run has state worth
+  watching while it runs — the key number after each round, which items are done or failed:
+  metrics or a chart for a number, a table or board for items with a status. Declare it once
+  at the top, then tag the items you already report: `report(item, "perf")`. It is a
+  projection of that stream, so it grows live and survives a resume. A run that is over
+  before anyone would look needs none.
+
+**Show what matters.** Two tests decide what earns a card: would the user open it on its
+own (else it is a section of the deliverable), and does it repeat another artifact (a CSV and
+a table of its rows, a report and a copy of it — one of each pair is noise). The common run
+publishes one deliverable, one dashboard when there is something to watch, and further files
+only when a subagent produced something else a person opens.
+
+Ids and the report tag are compile-time string literals: what a run can publish is fixed
+when the user approves the script, and an id assembled at runtime is a compile diagnostic.
+Publishing an id a second time mints the next version and keeps the old one.
 
 **A rejected publish is a repair opportunity, not an error to swallow.** Content publishes
 reject catchably — the file is missing, the path escaped the workspace, the bytes are over the
@@ -685,77 +689,73 @@ return {
 ```
 
 One `report` call feeds both surfaces: the tagged item lands on the chart *and* in the run's
-progressive results, so tagging costs nothing and adds a picture. Three cards, none repeating
-another: the chart is what the user watched, the profile is what a person opens, the report
-is what they keep. The CSV the bench also wrote stays in the workspace — its rows are the
-chart's points, so a card for it would say nothing new.
+results. Three cards, none repeating another: the chart is what the user watched, the profile
+is what a person opens, the report is what they keep; the CSV the bench wrote stays in the
+workspace, since its rows are the chart's points.
 
 ## 11. A complete example
 
 The complete review workflow that used to sit here — a reviewer per changed file, triage
 through one shared subagent that is fed as reviews land, a confirmer per kept finding chained
 inside the same callback, one join for the cross-file deduplication — is
-`${DCODE_SKILL_DIR}/examples.md` §5. Read it when you want to see a whole script's arc; §7
-and §10 already carry its rules.
+`${DCODE_SKILL_DIR}/examples.md` §5; §7 and §10 carry its rules. The open-ended form — a
+seed that surveys and ends in a tail hole, grown fill by fill — is `examples.md` #7 (§15).
 
 ## 12. Anti-patterns
 
 | What you wrote | What it costs you |
 | --- | --- |
-| Hoisted one subagent out of a fan-out for tidiness | The fan-out silently became a FIFO queue |
-| Gave every subagent in a fan-out the same fixed name | Every name in a run must be unique: a literal one is rejected at compile time, a computed one kills the run at the second item. Name per item or stay anonymous |
-| A fresh subagent each loop round | Round five re-learns everything round four knew, at full price |
-| Accumulated findings in an array, returned at the end | A failure on the last task loses all of them; `report` as you go |
-| Interpolated a whole file into the prompt | Paid tokens to tell a subagent something its own tools would have read |
-| A wide `files.grep` with no glob | The call rejects; it does not quietly hand you a partial workspace |
-| An unbounded `while` | The run dies on a cap instead of finishing |
-| Asked a subagent to run the tests and report whether they passed | Paid a session for what `world.run` does as code — and trusted a pass/fail claim the subagent can fake |
-| Built the `world.run` command name from a variable or template hole | Compile fails: the user approves the script's command set, so the command must be a literal; runtime values belong in the args array |
-| Submitted a workflow to find out whether a parse function works | A full run spent on what `EvalWorkflowSnippet` answers synchronously |
-| Dereferenced a `.find()` / `.match()` result or an optional property without a guard | Compile fails: `strict` keeps those `T \| undefined` / `null`; plain `items[i]` needs no guard (`noUncheckedIndexedAccess` is off) |
-| `Date.now()` / `Math.random()` / `fetch` / `fs` | Rejected at compile time; a replayable run cannot contain them |
-| Awaited each call in a loop that had no ordering requirement | Serial wall-clock for concurrent work |
-| Interpolated a tunable constant (a threshold, a cap) into an ask message | Amending that one number rewrites every prompt that mentions it: an `AmendWorkflow` re-run misses cache at the first such ask and re-pays everything downstream |
-| Named a phase or a subagent after the machinery, in either language ("fan-out", "文件评审阶段", "节点3"), or shipped the script with no markers at all | The user approves a graph whose stages say nothing about their work — or thirty cards with no story (§9) |
-| Wrote a persona that says only "make the check pass" | Against a check it cannot pass, faking one is the obedient reading. Tell the subagent to escalate an impossible gate instead (§14) |
-| Asked the reviewer "is this good?" | A reviewer asked for approval approves; ask what would break it and what is missing (§3) |
-| Reported findings nobody confirmed | The user gets a list that cannot tell "seen" from "suspected"; confirm each finding independently and label the ones that failed (§10) |
-| Gated the loop on the unit tests and never ran the integration suite, the end-to-end suite, or the bench the request was about | The work passed the check that was cheap, not the one that decides; the strongest check runs at least once before `return` (§5) |
-| Wrote the gate from habit (`cargo test`, `node --test`) without reading the project's own scripts | The `package.json`, `Makefile` or README already named a stronger check, and the user knows it; survey the repository's checks before you gate (§5) |
-| Put a check that exists into `notCovered` because it was slow | An honest-looking report of unverified work; `notCovered` is for what could not be checked (§10) |
-| Returned a bare array as the run's result | The main agent has to improvise the deliverable, so the user gets a different shape every time; return the report shape (§10) |
-| Returned the report and published nothing | The user gets the main agent's retelling and nothing to keep; publish the deliverable — the file they asked for, or the findings in long form (§10) |
-| Published a CSV and a table of its rows, or a report and a copy of it | Two cards for one fact: the second is noise the user has to look past (§10) |
-| Declared a dashboard for a run nobody watches | Three points on a chart for a run that was over before anyone looked; a dashboard is for the person watching (§10) |
-| Stacked a reviewer loop, a fresh final reviewer, a per-finding confirmer and a reader-proxy read on one deliverable | Four sessions re-reading the same work; one deliverable gets one mechanism, two at most with a reason (§3) |
-| Sent a confirmer after a finding a `world.run` already decided, or let the hunter, the confirmer and the gate each run the suite | The same check paid three times; the exit code is the confirmation, and the gate runs the suite once (§10) |
-| `Promise.all` between two stages whose items map one to one (review every file, *then* confirm every finding) | The slowest reviewer gates every confirmer while the slots idle; chain the stages per item and join once (§7) |
-| Waited for a run you already knew was wrong to finish, or stopped it and left it | Everything after the fix point is re-paid either way; call `AmendWorkflow` on it now, while it runs (§13) |
-| Pasted a whole revised script inline after a diagnostic or an error, instead of editing the file the tool named | Twenty thousand tokens re-streamed to change one line, on a provider that may stall on the resubmit — and a script compaction has dropped is one you can no longer paste; the file is on disk, so the revision is an `Edit` and a `path` (§13) |
+| One subagent hoisted out of a fan-out for tidiness | The fan-out became a FIFO queue (§2) |
+| One fixed name for every subagent in a fan-out | A literal duplicate fails compile, a computed one kills the run; name per item or stay anonymous (§2) |
+| A fresh subagent each loop round | Round five re-learns what round four knew, at full price (§2) |
+| An unbounded `while` | The run dies on a cap instead of finishing (§2) |
+| Findings accumulated in an array, returned at the end | A failure on the last task loses them all; `report` as you go (§10) |
+| A whole file interpolated into a prompt | Tokens spent on what the subagent's own tools read; pass the path (§4) |
+| A wide `files.grep` with no glob | The call rejects; there is no partial result (§5) |
+| A subagent asked to run the tests and say if they passed | A session paid for what `world.run` decides as code, and a claim it can fake (§5) |
+| A `world.run` command name built at run time | Compile fails: the command is a literal; runtime values go in the args array (§5) |
+| The gate written from habit, or only the unit tests gated | The project named a stronger check; survey its checks, and run the strongest one before `return` (§5) |
+| A workflow submitted to see whether a parse function works | A full run for what `EvalWorkflowSnippet` answers now (§6) |
+| An unguarded `.find()` / `.match()` result or optional property | Compile fails under `strict`; plain `items[i]` needs no guard (§16.3) |
+| `Date.now()` / `Math.random()` / `fetch` / `fs` | Compile fails: a replayable run cannot contain them |
+| An `await` per item in a loop with no ordering need | Serial wall-clock for concurrent work (§7) |
+| A stage that waits for the whole previous stage though it handles items one at a time | Every worker of the second stage waits for the slowest of the first while slots idle; chain per item, or use a channel (§7) |
+| A join with no comment saying what needs every item | On the next revision nobody can tell the barrier from a habit; say why, or pipeline it (§7) |
+| A channel nobody closes | `ChannelDeadlock`; the producing stage closes it in a `finally` (§7) |
+| An `await` between starting the stage futures and joining them | A stage failing while you await another has no listener: an unhandled rejection, not a failed run; start all, then join once (§7) |
+| A shared pool where per-item names were wanted | One changed upstream item misses the cache for the whole pool (§7) |
+| Phases or subagents named after the machinery ("fan-out", "文件评审阶段", "节点3"), or no markers | A graph that says nothing about the work, or thirty cards (§8, §9) |
+| A reviewer asked "is this good?" | It approves; ask what would break it (§3) |
+| A reviewer loop, a final reviewer, a confirmer and a reader on one deliverable | Four sessions re-reading one piece of work; one mechanism, two with a reason (§3) |
+| Findings reported unconfirmed, or a slow existing check put in `notCovered` | The user cannot tell "seen" from "suspected", or verified from skipped (§10) |
+| A confirmer on a finding `world.run` already decided, or the suite run by hunter, confirmer and gate | One check paid three times; the exit code is the confirmation (§10) |
+| A bare array returned, or nothing published | The main agent improvises the handoff and the user keeps nothing; return the report shape and publish the deliverable (§10) |
+| A CSV and a table of its rows, or a dashboard nobody watches | Cards that are noise (§10) |
+| A persona that says only "make the check pass" | Faking is the obedient reading of an impossible gate; tell it to escalate (§14) |
+| A tunable constant interpolated into an ask | Amending it rewrites every such prompt and re-pays everything downstream (§13) |
+| A wrong run left to finish, or stopped and left | `AmendWorkflow` it now, while it runs (§13) |
+| A revised script pasted inline after a diagnostic | Twenty thousand tokens re-streamed to change one line; `Edit` the named file and pass `path` (§13) |
+| A hole for what an `if` or a subagent could decide, or one in a fan-out callback | A run parked on you for nothing; the fan-out case does not compile (§15) |
 
 ## 13. After you submit
 
-Compilation happens first. **Diagnostics mean nothing ran** — there is no partially-started
-run to clean up — and they name the file your script is in. Every script you submit has one:
-an inline `script` is written under `.dcode/workflow-drafts/` before it is even compiled and
-the response hands you the path; a script you submitted by `path` is that file already. Each
-diagnostic reads `{path}:L{line}:C{column} {message}`, counted in the file, so it addresses
-an `Edit` as it stands.
-**Edit that file and resubmit with `path`. Do not paste the script inline again**:
-re-streaming twenty thousand tokens to change one line is slow enough that some providers
-stall on it, while the `Edit` that fixes it costs a few lines. (If the response names no
-file — a checkout the tool could not write to — then fix the script and resubmit it inline,
-as before.)
+Compilation happens first. **Diagnostics mean nothing ran**, and they name the file your
+script is in: an inline `script` is written under `.dcode/workflow-drafts/` before it is
+compiled and the response hands you the path; a `path` submission is that file already. Each
+diagnostic reads `{path}:L{line}:C{column} {message}`, counted in the file.
+**Edit that file and resubmit with `path`. Do not paste the script inline again**: the
+`Edit` costs a few lines; the re-stream costs twenty thousand tokens and may stall the
+provider. (If the response names no file, resubmit inline.)
 
 On a clean compile the run starts in the background and you get a run ID. **Do not poll it.**
-The completion notification arrives on its own and carries the final return value plus every
-reported item. Go do other work, unless the user asked you to wait.
+The completion notification arrives on its own with the final return value and every
+reported item. Do other work, unless the user asked you to wait.
 
 When you genuinely need to look at a run:
 
-- `TaskOutput` blocks until a run *this session started* finishes. That is the waiting tool.
-- `GetWorkflowRun` is an instant snapshot and never waits. Use it when you must not block,
-  or for a run another session owns — `TaskOutput` cannot see those.
+- `TaskOutput` blocks until a run *this session started* finishes: the waiting tool.
+- `GetWorkflowRun` is an instant snapshot; use it when you must not block, or for a run
+  another session owns, which `TaskOutput` cannot see.
 - `ListWorkflowRuns` enumerates the project's runs, including other sessions'.
 
 Read the terminal state precisely. A run ends in exactly one of three states:
@@ -765,109 +765,77 @@ Read the terminal state precisely. A run ends in exactly one of three states:
   whose source file was missing). Replaying it would fail the same way, so
   `ResumeWorkflowRun` refuses it; edit the run's script file, which the notification names,
   and resubmit it with `AmendWorkflow` and `path`.
-- **stopped** — the run was stopped and can be resumed as-is with `ResumeWorkflowRun`. The
-  notification's `<stop-reason>` says why: `user` (the user stopped it — leave it alone
-  unless they ask), `model` (you stopped it with TaskStop), `interrupted` (the process that
-  owned it exited; resume it), or `provider` (a subagent hit a deterministic model-side
-  error — sign-in expired, model not in the plan, quota cap; the `<error>` block names the
-  cause and the fix — resolve it with the user, then resume). A fifth reason, `superseded`,
-  never arrives as a notification: it is the state of a run you amended away, and the
-  `AmendWorkflow` result already told you. Such a run is not resumable; its successor is
-  the live one.
-
-Reported items come back on errored and stopped runs too, so a dead run is still worth
-reading. Model errors never reach the script: rate limits, overload, network errors,
-timeouts and unknown provider errors are retried inside the run without limit while the
-fan-out adapts to what the provider accepts, so a run that looks stalled with a "waiting for
-provider" badge is waiting, not broken. If nothing succeeds for twenty minutes you get one
-informational stall notification; the run is still running and needs nothing from you.
+- **stopped** — resumable as-is with `ResumeWorkflowRun`. The `<stop-reason>` says why:
+  `user` (leave it alone unless they ask), `model` (you stopped it), `interrupted` (the
+  owning process exited; resume it), or `provider` (a deterministic model-side error —
+  sign-in expired, quota cap; the `<error>` block names the fix — resolve it with the user,
+  then resume). A fifth state, `superseded`, is a run you amended away: not resumable, no
+  notification.
+
+Reported items come back on errored and stopped runs too. A run with a "waiting for
+provider" badge is retrying a provider error (§16.3), not broken; after twenty minutes you
+get one stall notification, and it still needs nothing from you.
 
 **When the script itself was wrong, do not start over.** Any run — errored, stopped,
 completed, or still running — can be superseded: edit the run's script file and call
-`AmendWorkflow` with `run_id: "<runId>"` and that `path`. That starts a new run which
-imports the old one's finished work, matched per named subagent along its sequence of asks,
-so every step you did not touch settles from cache at no token cost and only the changed
-part actually runs — with one deliberate limit: the moment a live subagent writes to the
-workspace (or a live `world.run` executes), the workspace may no longer be the one the old
-results were computed against, so from that point every cached `world.run`, every cached
-world read and every cached ask whose subagent had read or run something runs live even if
-its text is unchanged; asks whose subagent only answered keep settling from the cache. A gate
-command therefore always tests the code the amended run actually produced; the price is
-that doing steps after the first live write are re-paid. The old run is left exactly as it
-was. This is the move after a `ScriptError`, after a bad prompt
-produced a useless result, and when a completed analysis needs one more stage — rewriting
-the workflow from scratch throws away work that was already paid for. Two things make the
-cache hit: names that stay the same across the revision, and asks whose instructions stay
-byte-identical (an upstream change cascades — a changed result changes what interpolates
-into everything downstream, which is what you want).
+`AmendWorkflow` with `run_id` and that `path`. The new run imports the old one's finished
+work, matched per named subagent along its sequence of asks, so every step you did not touch
+settles from cache and only the changed part runs (the boundary is in §16.4). This is the
+move after a `ScriptError`, a bad prompt, or a completed analysis that needs one more stage.
+Two things make the cache hit: names that stay the same, and asks whose instructions stay
+byte-identical (an upstream change cascades downstream).
 
 **Every run remembers its script file, so a revision is an `Edit`.** The terminal
-notification names that path, and `GetWorkflowRun` reports it as `scriptPath` — which is why
-you never have to keep the script in context: by the time a long run errors, compaction may
-well have dropped the text you sent, while the file on disk has not moved. Edit it in place
-and pass `path`; pass `script` only when what you are submitting is genuinely new. A `path`
-whose bytes still equal what the run already ran is refused as `script_unchanged`, with
-nothing stopped and nothing created — that refusal means your `Edit` did not land, not that
-the run cannot be amended (changing only `max_concurrency` or `subagent_model` is a real
-change and goes through).
+notification names that path and `GetWorkflowRun` reports it as `scriptPath`, so the script
+never has to live in your context: compaction may have dropped the text you sent, the file
+on disk has not moved. Edit it in place and pass `path`; pass `script` only for something
+genuinely new. A `path` whose bytes still equal what the run ran is refused as
+`script_unchanged` — your `Edit` did not land — with nothing stopped and nothing created.
 
 **Editing a draft asks nothing.** `.dcode/workflow-drafts/` is machine-owned and
-git-ignored, so an `Edit` or `Write` under it is pre-approved and opens no confirmation
-window. Editing a script is not running one: the window still stands between the file and
-the run, so fix the file freely and let the submission be the thing the user answers.
-
-**Repair a run while it is still going.** The same call works before the run ends, and it
-is cheaper the earlier you make it. When the user points at a run that is heading the wrong
-way, or a reported item shows the script is wrong, do not wait for the completion
-notification and do not stop the run first: call `AmendWorkflow` on it. The tool stops the
-running predecessor, waits for it to settle, imports everything that settled before the
-stop at zero cost, and starts the revision — one call, no `TaskStop`, no polling for the
-stop. Nothing after the stop was ever paid for, and nothing the predecessor finished is paid
-twice: the cache stays open until the revision's first write to the workspace, and asks whose
-subagent only answered, without reading or running anything, keep replaying even after that. The
-old run shows as "superseded" and sends no notification of its own; the result you get back
-names both runs. A run you amended is not left for the user to ask about: the amend result
-is the account of what happened to it.
-
-That cascade rule has a converse that decides whether your revisions are cheap or ruinous.
-Interpolating an upstream **result** into a prompt is safe: on resume the result replays
-byte-identical, so the prompt does too. Interpolating a script **constant** is the
-opposite bet — constants are exactly what an amendment tunes, and every ask whose text
-mentions one is an ask whose cache you forfeit by tuning it, plus everything downstream of
-it:
+git-ignored, so an `Edit` under it opens no confirmation window; the window still stands
+between the file and the run, so fix the file freely and let the submission be what the
+user answers.
+
+**Repair a run while it is still going.** The same call works before the run ends, and the
+earlier the cheaper. When a run is heading the wrong way, do not wait for it and do not stop
+it first: call `AmendWorkflow` on it. The tool stops the predecessor, waits for it to settle,
+imports everything that settled before the stop at zero cost, and starts the revision — one
+call, no `TaskStop`, no polling. The old run shows as "superseded" and sends no notification;
+the result you get back names both runs.
+
+The cascade rule has a converse that decides whether revisions are cheap or ruinous.
+Interpolating an upstream **result** into a prompt is safe: on resume it replays
+byte-identical, so the prompt does too. Interpolating a script **constant** is the opposite
+bet — constants are what an amendment tunes, and every ask whose text mentions one forfeits
+its cache when you tune it, plus everything downstream:
 
 ```ts
-// ✗ Couples every revision ask to a knob you will want to tune. Amending
-//   PASS_THRESHOLD (say 96 → 94) rewrites this text, so the resumed run misses
-//   cache at the first revision and re-pays every ask after it — to reproduce
-//   answers the old run already holds.
+// ✗ Amending PASS_THRESHOLD (say 96 → 94) rewrites this text, so the resumed run
+//   misses cache at the first revision and re-pays every ask after it.
 draft = await writer.ask<Draft>(
   `Scored ${review.score}; passing needs ${PASS_THRESHOLD}. Revise: ${JSON.stringify(review.comments)}`,
 );
 
-// ✓ The prompt carries only replayed upstream values and the fact that the
-//   branch was taken; the threshold comparison already happened in script code.
-//   Amending the threshold now moves only where the loop exits — every round
-//   before that point settles from cache.
+// ✓ Only replayed upstream values and the fact that the branch was taken; amending
+//   the threshold now moves only where the loop exits, and earlier rounds settle from cache.
 draft = await writer.ask<Draft>(
   `The review did not pass. Address each comment: ${JSON.stringify(review.comments)}`,
 );
 ```
 
-Keep the tunable knobs — thresholds, round caps — in the script's control flow,
-where amending them is free, and out of ask text, where amending them is a cache purge.
-A subagent almost never needs the number anyway; it needs the verdict and the feedback.
+Keep the tunable knobs — thresholds, round caps — in the script's control flow, where
+amending them is free, and out of ask text, where it is a cache purge. A subagent rarely
+needs the number; it needs the verdict and the feedback.
 
 ## 14. When a subagent escalates
 
-Every subagent can escalate a blocking question to you while the run is going. Nothing in the
-script switches this on and no persona field controls it — the tool is injected the way
-`submit_result` is. It exists for the one thing a script
-cannot design its way around: a subagent walled in by something that is not its fault. A gate
-it cannot pass (a check capped at 95 against a threshold of 96), two instructions no single
-output satisfies, or a fact only whoever started the run knows. With no way to ask,
-a walled-in subagent has two moves left and both are bad — grind until the round cap, or
-fake its way past.
+Every subagent can escalate a blocking question to you while the run is going; nothing in
+the script switches this on. It exists for the one thing a script cannot design around: a
+subagent walled in by something not its fault — a gate it cannot pass (capped at 95 against
+a threshold of 96), two instructions no single output satisfies, a fact only whoever started
+the run knows. With no way to ask, it has two moves left, both bad: grind until the round
+cap, or fake its way past.
 
 **What reaches you.** A notification arrives mid-run carrying the run, the subagent, the
 question with whatever evidence the subagent attached, and a globally unique question id shaped
@@ -890,34 +858,198 @@ you need not drop what you are doing, but you cannot leave it unanswered.
   past the cache boundary — everything before it imports from the old run at no token cost,
   and it re-runs against the fixed script.
 
-**If the notification never arrives**, the question is still discoverable. `GetWorkflowRun`
-lists what a run still owes an answer to under `pendingQuestions`, ids included. That
-snapshot is the fallback when a notification is dropped, and the way to check on a run you
-suspect is waiting on you.
+**If the notification never arrives**, `GetWorkflowRun` lists what a run still owes you:
+the questions under `pendingQuestions`, ids included, and the holes it is waiting at (§15).
+That snapshot is the way to check on a run you suspect is waiting on you.
+
+**Write personas that make honesty the cheap move.** A persona that says "make the check
+pass" and stops there leaves faking a pass as the obedient reading. One sentence closes that
+off: *"If a check is impossible to pass, or your instructions contradict each other, escalate
+and say so plainly rather than working around it."*
+
+One ask gets three escalations; the fourth comes back as an ordinary result telling the
+subagent to proceed on its own best judgement — a guard against chatter.
+
+## 15. Holes: growing the workflow as the run learns
+
+`hole<T>()` is the other mid-run request — §14 is the subagent's, this one is yours. A
+script is what you know for sure; a hole is where knowing stops. Any phase whose subagents,
+asks or gate you would have to guess is a hole: write the part before the guess, end it in
+`hole<T>()`, and the run's findings write the rest. A workflow whose shape the request fixes
+has no holes, and that is fine too.
+
+A subagent returns a **value**; a hole returns **code**. Ask a subagent when the script
+already knows what to do with the answer and only the data is missing. Leave a hole when
+what is missing is the rest of the workflow — which phases come next, which subagents exist,
+what each is told, what gate runs. *If you could write the code now and only the data is
+missing, it is not a hole.*
+
+| The unknown is… | Use |
+| --- | --- |
+| an answer the script knows how to consume | a subagent ask; fresh eyes if it is a judgment (§3) |
+| a branch among outcomes you can enumerate now | a typed result and an `if` or a loop, in the script |
+| what the remaining workflow should be, knowable only from findings | a hole |
+| a question a subagent hits mid-task that only the run's owner can answer | escalation (§14) |
+
+Subagents run without you, in parallel; a hole parks one branch until you take a turn. Spend
+holes on shape, never on answers.
+
+Three forms; `T` is always written out:
+
+```ts
+const plan = await hole<Plan>("决定分组", `最慢的模块是 ${survey.slowest}`); // decide, then continue
+return await hole<Guide>("第1步：决定导览结构", `盘点：${JSON.stringify(survey)}`); // tail: the rest is not written yet
+const plan = await hole<Plan>("决定分组", `…`, async () => { /* filled: the body stands in for the hole */ });
+```
+
+- **The name is a phase name.** A literal, unique among the script's holes and phase markers
+  (nested fills included), in the user's language: it labels the station, the notification and
+  the fill file. `T` is the contract the body is checked against.
+- **The prompt is the one channel for values.** Interpolate what the decision needs; the
+  fill reads values there and types from the code.
+- **The body sees every binding declared before the hole, none after**, and may leave holes
+  of its own.
+- **Filled once, run per reach.** A hole in a loop or a helper is filled once and its body
+  runs each iteration with that iteration's bindings. Never inside a fan-out callback (`.map`
+  or another array-method body): the fill would be owed while the items already run.
+
+### Grow by tail holes — the default for a task whose shape is not known upfront
+
+When the request does not tell you the workflow — a repository to understand before the
+work can be planned, a bug whose next step depends on what the last one found — do not
+guess the topology. Write the part you know and end the script with a tail hole. The script
+then grows by **nesting**: each fill is the statements of the innermost body, does one step,
+and ends in the next tail hole, until one returns instead.
+
+```ts
+// 0. The seed you submit: what is known, then a typed gap.
+phase("盘点仓库顶层目录");
+const survey = await agent("勘察员").ask<Survey>("列出顶层目录，各用一句话说明作用。");
+return await hole<Guide>("第1步：决定导览结构", `盘点：${JSON.stringify(survey.dirs)}`);
+```
+
+```ts
+// 1. After the first fill: the hole has a body — one step, then the next hole.
+return await hole<Guide>("第1步：决定导览结构", `盘点：…`, async () => {
+  phase("分章并行撰写初稿");
+  const drafts = await Promise.all(
+    survey.dirs.map((d) => agent(`写手·${d.path}`).ask<Chapter>(`写「${d.path}」一章：${d.purpose}`)),
+  );
+  return await hole<Guide>("第2步：审读与交付", `${drafts.length} 章初稿已就绪`);
+});
+```
+
+```ts
+// 2. After the second fill: the chain closes with a value, which is the run's result.
+return await hole<Guide>("第1步：决定导览结构", `盘点：…`, async () => {
+  /* step 1 as above; `survey` and `drafts` are in scope below */
+  return await hole<Guide>("第2步：审读与交付", `…`, async () => {
+    phase("独立审读并修订");
+    const critique = await agent("审读员").ask<string>(`只凭文本挑毛病：${JSON.stringify(drafts)}`);
+    const chapters = await agent("修订编辑").ask<Chapter[]>(`按意见修订：${critique}`);
+    return { title: "仓库导览", chapters, notCovered: [] };
+  });
+});
+```
+
+You send only the innermost statements; the tool splices them in and rewrites the draft
+with the effective script, so the draft you read before the next fill is the script that is
+running. The chain's rules: a fresh name per step (`第N步：<what it does>`; a repeated name
+is a 9012); the prompt is the progress ledger; results stay in bindings (`survey`, `drafts`),
+because every inner body sees the ones around it; a step may add phases, subagents and
+holes of its own. The timeline grows to the right, one head per step. This is the normal
+way to run a task whose shape only appears as the work proceeds, not a fallback.
+
+### A stage shaped by discovery
+
+The survey's *value* goes to the script as data; the fill writes the *topology* of the next
+stage, which the survey decided: three reviewers or one, fanned out or sequential, which
+check gates them.
+
+```ts
+const hot = await agent("剖析员").ask<Hotspots>("找出最慢的三个模块，说明各自的耦合。");
+const reviews = await hole<Review[]>("怎么审查这些热点", `热点：${JSON.stringify(hot.modules)}`);
+```
+
+A fill for two independent modules and one shared one: two reviewers in a `Promise.all`,
+a calibrated reviewer over the shared module, then a bounded fix-and-recheck loop — none of
+it writable before `hot` was known.
+
+### A procedure decided at first sight, run every round
+
+```ts
+for (const failure of failures) {
+  const triage = await hole<Triage>("每个失败怎么分诊", `第一个失败：${failure.name}\n${failure.output}`);
+  report(triage);
+}
+```
+
+Filled at the first failure, the body runs for every one after with that round's `failure`.
+The fill is a *procedure* — which subagent to send, what to ask, when to mark `unconfirmed`
+— not an answer about one failure; that would be a subagent ask inside the loop.
 
-**Write personas that make honesty the cheap move.** A subagent follows the instructions you
-wrote, so a persona that says "make the check pass" and stops there leaves faking a pass as
-the obedient reading. One sentence closes that off; adapt this one: *"If a check is
-impossible to pass, or your instructions contradict each other, escalate and say so plainly
-rather than working around it."*
+### A remedy the plan could not enumerate
 
-One ask gets three escalations. The fourth comes back as an ordinary result telling the
-subagent its escalation allowance is spent and to proceed on its own best judgement — a guard against
-chatter, not an allowance to spend.
+```ts
+const gate = await world.run("pnpm", ["test"]);
+if (gate.exitCode !== 0) {
+  await hole<void>("测试没过怎么办", `退出码 ${gate.exitCode}：\n${gate.stderr.slice(0, 2000)}`);
+}
+```
+
+If the remedies were known, the script would hold a `Remedy` value and an `if`. The hole is
+for when the fix may need phases and subagents nobody planned — a bisect, a second opinion,
+a rollback — decided with the failure in hand.
 
-## 15. Going deeper
+### Propose, judge, then build
 
-- `${DCODE_SKILL_DIR}/patterns.md` — the topology catalogue: fan-out/fan-in, review sweeps,
-  planner-reviewer loops, judge panels, staged pipelines, bounded discovery,
-  `world.run`-gated verifier loops. Read it
-  when you know the shape you want and want it written correctly.
+```ts
+const proposals = await Promise.all([1, 2, 3].map((k) => agent(`方案${k}`).ask<Proposal>("提一个方案。")));
+const pick = await agent("评委").ask<Pick>(`选最好的一个：${JSON.stringify(proposals)}`);
+return await hole<Outcome>("按选定方案施工", `选中：${JSON.stringify(proposals[pick.index])}`);
+```
+
+The judge is a subagent, because choosing is a value; the hole writes the stage that builds
+the winner, whose shape depends on what won.
+
+**Not a hole:** a verdict, a summary, a choice among options, an answer per item — those are
+subagent asks — and any branch an `if` over a typed result can express.
+
+**Filling one.** The notification carries the run, the hole's site id (`hole#21b40fca`), its name
+and type, the prompt with its values in, the draft's path and the hole's line, and the phases
+before and after. Then:
+
+1. Read the draft around the line: the body is compiled where the hole stands and sees what
+   is declared above it.
+2. Write only the statements — no `hole(...)` call, no arrow — returning a value of `T`, or
+   ending in a new tail hole when the next step is not known yet; rehearse fixed logic in
+   `EvalWorkflowSnippet` first (§6).
+3. Call `FillWorkflowHole` with `run_id`, `hole_id` and `script` (or `path`, §16.7). The run
+   grows by the body and goes on; the response names the phases added and the draft, now
+   holding the effective script, for any later `AmendWorkflow`.
+4. Diagnostics mean nothing was spliced and the hole still waits: edit the fill file the
+   response names and resubmit with `path`, never paste it again (§13). A line in the
+   draft's file is the run's recorded script: `AmendWorkflow`, not a draft edit.
+
+A fill that throws at run time rejects at the site and ends the run errored unless caught;
+amend the draft as usual. Full scripts: `patterns.md` #14–#16, `examples.md` #7.
+
+## Going deeper
+
+- `${DCODE_SKILL_DIR}/patterns.md` — the topology catalogue. Its index puts the pipeline
+  shapes first: per-item chaining, streaming through channels, a feedback loop with a counted
+  close. Then fan-out/fan-in, review sweeps, planner-reviewer loops, judge panels, staged
+  handoffs, bounded discovery, `world.run`-gated verifier loops, model routing, and the hole
+  shapes (growth by tail holes, a stage shaped by discovery, a remedy hole). Read it when you
+  know the shape you want and want it written correctly.
 - `${DCODE_SKILL_DIR}/examples.md` — complete worked scripts, including a two-subagent
-  adversarial prove/disprove loop. Read one when you want to see a whole script's arc.
+  adversarial prove/disprove loop and a repository guide grown step by step through tail
+  holes. Read one when you want to see a whole script's arc.
 
 ## 16. Tool reference
 
-The four authoring tools — `CreateWorkflow`, `AmendWorkflow`, `SaveWorkflow` and
-`EvalWorkflowSnippet` — carry one-paragraph descriptions on purpose, and each of them refuses
+The five authoring tools — `CreateWorkflow`, `AmendWorkflow`, `FillWorkflowHole`,
+`SaveWorkflow` and `EvalWorkflowSnippet` — carry short descriptions on purpose, and each refuses
 to run until this skill has been loaded in the session. This section is the part of their
 contract that the descriptions do not carry: the facade the compiler checks against, the
 rules a script must satisfy, and the fields each tool takes. Read it before writing or
@@ -932,14 +1064,12 @@ Compilation errors come back as diagnostics, counted in the script's file (§13)
 **Three sources; pass exactly one.**
 
 - `script`: a one-off workflow written inline. It is saved to a file under
-  `.dcode/workflow-drafts/` and the result names that file, whether the script compiled or
-  not; revise it by editing the file and resubmitting with `path`, never by pasting the
-  script again.
+  `.dcode/workflow-drafts/` and the result names that file, compiled or not; revise it by
+  editing the file and resubmitting with `path` (§13).
 - `saved`: a workflow saved in this project or globally, by name —
-  `saved: { name: "pr-review", args: { pr: "123" } }`. Its arguments are validated against
-  its declaration (unknown keys, missing required values and wrong types are rejected)
-  before anything runs. Before writing a workflow from scratch, check `ListSavedWorkflows`:
-  a saved workflow the user reviewed and kept beats a rebuilt one. Running a saved workflow
+  `saved: { name: "pr-review", args: { pr: "123" } }`; arguments are validated against its
+  declaration before anything runs. Check `ListSavedWorkflows` before writing one from
+  scratch: a saved workflow the user kept beats a rebuilt one. Running a saved workflow
   is the one call that does not need this skill loaded.
 - `path`: a script file on disk, relative to the working directory or absolute — normally
   the file a previous result named. Pass `args` alongside it when the file declares
@@ -953,14 +1083,12 @@ Either way the user confirms the run, and the confirmation shows the actual scri
   Always pass it for an inline script; it labels the run everywhere and names its draft
   file. It defaults to the saved workflow's name.
 - `max_concurrency`: an upper bound on how many subagents work at once. Set it only when
-  the user asks to limit parallelism — never on your own initiative and never as a
-  reaction to provider rate limits or errors, which the runtime already adapts to. A value
-  above the machine's ceiling is lowered to it. Otherwise how many subagents run at once is
-  the runtime's decision, not the script's.
-- `subagent_model`: the model the subagents run on, as `providerId/modelId` or a bare
-  model id (optionally `$reasoningLevel`). Set it only when the user asks for a specific
-  model; pass the name the user used, and if the tool cannot resolve it, pick from the ids
-  it lists or call `ListModels`. You stay on the session model either way.
+  the user asks to limit parallelism — never as a reaction to provider rate limits or
+  errors, which the runtime already adapts to.
+- `subagent_model`: the model the subagents run on, as `providerId/modelId` or a bare model
+  id (optionally `$reasoningLevel`). Set it only when the user asks for a specific model;
+  pass the name they used, and if the tool cannot resolve it, pick from the ids it lists or
+  `ListModels`. You stay on the session model either way.
 
 This tool starts a new run. To change a run that exists — errored, completed, stopped or
 still running — call `AmendWorkflow` (§13, §16.4), never `CreateWorkflow` again.
@@ -974,67 +1102,53 @@ plain interfaces and never uses `declare`.
 
 <!-- facade-dts:start -->
 ```ts
-/**
- * A node: one task assigned to an actor, producing a typed result.
- * Thenable — await it, or combine with Promise.all for joins.
- */
+/** The pending result of one ask. Await it, or pass it to Promise.all with others. */
 declare interface Node<T> extends PromiseLike<T> {}
 
+/** A model declared with model(). */
+declare class ModelRef { private constructor(); private readonly modelRef: never }
+
 /**
- * Persona of an actor: identity, fixed at creation (frozen for the actor's lifetime). Every
- * actor has the regular working tools (reading, searching, editing, running commands); what
- * it may do with them is said in the ask.
+ * Declare a model subagents may run on: "modelId" or "providerId/modelId", optional "$level".
+ * String literal only (checked at launch); choose among ModelRefs at run time.
  */
+declare function model(id: string): ModelRef;
+
+/** Persona of a subagent, fixed when agent() creates it. Every subagent has the same working tools. */
 declare interface AgentPersona {
   /** System prompt describing the actor's role. */
   system?: string;
+  /** Model id literal or ModelRef; omitted = the run's subagent model. */
+  model?: ModelRef | string;
 }
 
 /**
- * An actor: a persistent conversational context that executes tasks serially.
- * Context accumulates across asks; concurrent asks on one actor queue FIFO.
+ * A subagent: one conversation that keeps its context across asks. Asks issued while it is
+ * busy wait their turn, first in, first out.
  */
 declare interface Agent {
   /**
-   * Assign one task. T is the task's output value: an interface you define in
-   * this script with a plain "interface" declaration (no "declare" modifier; the
-   * harness synthesizes its runtime schema from the type), or the final response
-   * text when the type argument is omitted.
+   * Give the subagent one task. With a type argument, the answer is a value of type T,
+   * validated against a schema built from it: T is an interface you define in this script
+   * with a plain "interface" declaration (no "declare" modifier). Without one, the answer is
+   * the subagent's final reply text.
    */
   ask<T = string>(instructions: string): Node<T>;
 }
 
 /**
- * Create a fresh actor. Every call creates a new context; sharing context means
- * sharing this reference.
- *
- * The name is optional, but a non-empty one is an identity, not a label. It must be
- * unique within the run: two actors under the same name fail the whole run. It is
- * also the key a revised re-run matches its cache on (AmendWorkflow imports the
- * finished work of each named actor), so stable, meaningful
- * names carry work across script revisions. Anonymous actors are legal and never
- * reuse imported work.
- *
- * In a fan-out or a loop each iteration is a separate actor, so a single static name
- * there is the duplicate case: give each one its own name (agent("reviewer-" + file))
- * or leave them all anonymous. A literal name in a loop is reported when the script
- * is compiled; a computed one fails at run time.
+ * Create a subagent. Every call starts a new, empty conversation; to share one, share the
+ * returned value. A non-empty name is an identity: unique within the run (a literal duplicate
+ * is a compile error, a computed one fails the run) and the key AmendWorkflow matches cached
+ * work by. Unnamed subagents are allowed and never reuse cached work.
  */
 declare function agent(name?: string, persona?: string | AgentPersona): Agent;
 
 /**
- * The run's arguments: the values supplied when this workflow was started.
- *
- * A workflow saved into the project declares its arguments (name, type, whether they
- * are required, defaults); the host validates the caller's values against that
- * declaration and fills in defaults before the run starts, so what lands here is
- * always a complete, checked bag. For an inline script — and inside a snippet — it is
- * simply empty.
- *
- * Always defined, so reading args.target is a plain property read rather than a crash.
- * The values are typed unknown on purpose: the compiler surface must not change from
- * one workflow to the next, so narrow them in the script -- String(args.target), or a
- * typeof guard -- exactly as you would any other external input.
+ * The run's arguments. For a saved workflow they are validated against its declared
+ * arguments, with defaults filled in, before the run starts; an inline script or a snippet
+ * gets {}. Always defined; the values are unknown, so narrow them (String(args.target), a
+ * typeof guard).
  */
 declare const args: Readonly<Record<string, unknown>>;
 
@@ -1042,31 +1156,17 @@ declare const args: Readonly<Record<string, unknown>>;
 declare function log(message: string): void;
 
 /**
- * Publish one intermediate result while the run is still going. Like log() it
- * returns nothing and there is nothing to await — a finding has no reply.
- *
- * Unlike log() it is journaled: a resumed run never shows the same item twice, and
- * the items are delivered with the completion notification even when the run ends in
- * failure. That is the point of it — a run that dies on its twelfth of forty tasks
- * still did eleven tasks' worth of work, and reported items are how that work
- * survives.
+ * Publish one intermediate result while the run is going; returns nothing. Items are
+ * recorded: a resumed run never shows one twice, and they reach the completion notification
+ * even when the run fails. The item must be JSON-serializable (plain objects, arrays, strings,
+ * numbers, booleans, null); functions, class instances, Date and promises are compile
+ * errors. Caps fail the whole run, not the call: 65,536 items per run, 1 MiB per serialized
+ * item, 1 GiB per run.
  *
- * Two caps, and both fail the whole run rather than the call (there is no rejection
- * channel in a void return): at most 256 items per run, and at most 32KB per
- * serialized item. They are generous on purpose — report findings, not chatter.
- *
- * The item must be JSON-serializable: plain objects, arrays, strings, numbers,
- * booleans, null. Functions, class instances, Date and promises are rejected when
- * the script is compiled.
- *
- * The optional second argument routes the item to a dashboard artifact: pass the id
- * of a preset declared with artifact.chart / table / metrics / board, and this item
- * becomes one more point, row, tile value or card on it — the dashboard is nothing
- * but the items tagged with its id. The tag must be a compile-time string literal
- * naming a preset the script declares (anywhere in the text, but the declaration must
- * have executed by the time this call runs); a tag that names nothing, or names a
- * file/markdown artifact, fails the run. An untagged report is unchanged: it goes to
- * the run's Results, and a tagged one goes to both.
+ * artifactId routes the item to a dashboard: a compile-time literal naming a preset
+ * (artifact.chart / table / metrics / board) whose declaration has executed by then. The
+ * item becomes one point, row, tile value or card there and still lands in the run's
+ * Results. A tag naming nothing, or a file/markdown artifact, fails the run.
  */
 declare function report(item: unknown, artifactId?: string): void;
 
@@ -1076,7 +1176,7 @@ declare interface ArtifactRef { id: string; version: number }
 declare interface ArtifactOptions {
   /** Shown as the card title; defaults to the id. In the user's language. */
   title?: string;
-  /** A sentence or two, shown beside the title when this artifact leads the card. */
+  /** A sentence or two, shown beside the title when this artifact is the run's primary. */
   description?: string;
   /** The run's deliverable: the card and the run pane lead with it. At most one id per run; once set it stays set for later versions. */
   primary?: boolean;
@@ -1116,44 +1216,24 @@ declare interface BoardSpec extends ArtifactOptions {
   detail?: ArtifactField[];
 }
 /**
- * Publish what the user should see: the run's own deliverable surface, kept after it ends.
- * Two habits. (1) EVERY RUN PUBLISHES ITS DELIVERABLE, whatever the user asked for: a webpage
- * or PDF a subagent wrote goes out via file(); an answer (findings, a review) goes out as the
- * long form of the facts the return summarises, usually via markdown(). Once, at the end;
- * skip it only when the whole answer is one line. When the run publishes more than one
- * artifact, mark the deliverable { primary: true }. (2) A DASHBOARD IS FOR THE PERSON WATCHING
- * THE RUN: declare one when there is state worth watching mid-run (the key number per round,
- * which items are done) and none when the run is over before anyone looks. Two tests keep it
- * to what matters: would the user open it on its own? does it repeat another artifact? A CSV
- * and a table of its rows: one of them is noise.
- *
- * Every id is a compile-time string literal (non-empty, at most 64 characters of
- * [A-Za-z0-9_.-]); the set a run can publish is fixed at submit time, so the compiler
- * rejects a computed one. Within one run an id belongs to exactly one member.
- * The two families are deliberately asymmetric, and the asymmetry is the whole design:
- * - CONTENT (file, markdown) are EFFECTS: async, resolve to an ArtifactRef, and REJECT
- *   catchably — missing file, not a file, path outside the workspace, over the size cap, no
- *   store. try { await artifact.file("book", "out/book.pdf") } catch { …ask a subagent to
- *   write it… } is the intended idiom. Bytes are copied at publish time, so later workspace
- *   edits never rewrite a version; republishing an id mints the NEXT version and keeps the
- *   old ones (at most 16 per id).
- * - PRESET (chart, table, metrics, board) are DECLARATIONS: synchronous, return nothing,
- *   never touch a file; they say how items tagged with their id are drawn. Declare each ONCE,
- *   at the top, then feed it with report(item, "<id>"). The same id with an identical spec is
- *   a no-op; a DIFFERENT or malformed spec fails the whole run — a void return has no
- *   rejection channel, exactly as with report().
+ * Publish what the user keeps: cards beside the run, kept after it ends. Every id is a
+ * compile-time string literal (non-empty, at most 64 characters of [A-Za-z0-9_.-]) and is
+ * used with one member only.
+ * - CONTENT (file, markdown) are effects: async, resolve to an ArtifactRef, and reject
+ *   catchably (missing file, not a file, outside the workspace, over the cap, or no artifact
+ *   store in this host).
+ *   Bytes are copied at publish time; republishing an id mints the next version and keeps
+ *   the old ones.
+ * - PRESET (chart, table, metrics, board) are declarations: synchronous and void, drawn from
+ *   the items tagged report(item, "<id>"). Declare each once, at the top level; an identical
+ *   re-declaration is a no-op, a different or malformed spec fails the whole run.
  * Caps: 32 ids per run, 16 versions per id, 20 MiB per file, 256 KB per markdown, 120
  * characters of title and 500 of description.
  */
 declare const artifact: {
-  /**
-   * Publish a file from the workspace. path is workspace-relative, resolved by the same
-   * resolver files.read() uses; the bytes are copied at publish time. The content type is
-   * read off the extension unless opts.contentType overrides it. Rejects (catchably)
-   * rather than publishing something empty.
-   */
+  /** Publish a workspace file, path resolved as in files.read(). The type comes from the extension unless opts.contentType sets it. */
   file(id: string, path: string, opts?: ArtifactFileOptions): Promise<ArtifactRef>;
-  /** Publish markdown text the script composed: the usual shape of a report deliverable, the long form of what the return summarises. */
+  /** Publish markdown text the script composed. */
   markdown(id: string, content: string, opts?: ArtifactOptions): Promise<ArtifactRef>;
   /** Declare a chart fed by report(item, id): each tagged item is one point. */
   chart(id: string, spec: ChartSpec): void;
@@ -1166,44 +1246,26 @@ declare const artifact: {
 };
 
 /**
- * Mark the start of a phase: a short, human-readable name for the group of steps that
- * follow, shown as one node on the workflow graph the user reads and approves.
- * Presentation only — it starts nothing, waits for nothing, returns nothing.
- *
- * Required in every script you submit, not optional: the phase graph is how the user
- * experiences the workflow. Without markers they face one card per step and no story;
- * group the whole script, top to bottom.
- *
- * Name phases for the user, in the language the user is speaking in this session: a short
- * natural phrase saying what the stage accomplishes ("Research each changed file in parallel",
- * "汇总并产出最终报告"). Graph-building vocabulary the user never chose — "fan-out", "gate",
- * "aggregate" — is not a name; the user approves stages by what they do. Say it the way you
- * would tell a colleague what is happening: "确认测试仍然通过", not "执行测试验证任务".
- *
- * The scope is the rest of the enclosing block: the marker claims every step issued
- * from it to the end of the block it stands in — nested blocks and inlined helper
- * calls included — and the enclosing phase resumes once that block ends. A marker
- * inside an if-branch therefore groups that branch and does not leak past it. Two
- * markers with the same name are one phase: repeating a name continues that phase,
- * which is the opposite of an actor's name — that one has to be unique.
- *
- * Two rules the compiler enforces. The name must be a compile-time string literal
- * ("review the diff" or a no-substitution template) and non-empty, because the phase
- * names label the graph the user confirms before anything runs. And the call must
- * stand alone as its own statement: a marker in expression position has no
- * rest-of-block to claim.
- *
- * Every phase must contain at least one subagent ask or one world.run. A phase is a
- * stage the user watches progress through; plain script logic between two asks (reading
- * args, shaping a prompt, building the return) runs in a flash and shows no progress, so
- * it is not a stage. Fold it into the phase before or after it; never open a phase for
- * the setup at the top or the return at the bottom.
- *
- * Idiom: one marker at the head of each stage that does work — name the loop body and
- * its check where they start, name the close-out that asks or runs after the loop.
+ * Mark the start of a phase: a named group of the steps that follow, drawn as one node on
+ * the graph the user approves. Presentation only: it starts, waits for and returns nothing.
+ * Required. The name is a non-empty compile-time literal and the call a standalone
+ * statement. A marker covers every step from it to the end of the block it stands in
+ * (nested blocks and inlined helpers included); two markers with the same name are one
+ * phase. Every phase contains at least one ask or world.run.
  */
 declare function phase(name: string): void;
 
+/**
+ * A typed gap: code you write later, once an earlier step's findings are in. When the run
+ * reaches an unfilled hole, that branch waits while you write the body (FillWorkflowHole);
+ * the rest of the run keeps going. prompt is the message you will receive, so interpolate
+ * the values the decision needs. The body runs in the hole's place, sees the bindings
+ * declared before it, and returns the hole's value. The filled form passes the body last.
+ */
+declare function hole<T>(name: string, prompt?: string): Promise<T>;
+declare function hole<T>(name: string, body: () => Promise<T>): Promise<T>;
+declare function hole<T>(name: string, prompt: string, body: () => Promise<T>): Promise<T>;
+
 /** One matching line found by files.grep. */
 declare interface GrepMatch {
   /** Workspace-relative path of the file the match was found in. */
@@ -1215,30 +1277,18 @@ declare interface GrepMatch {
 }
 
 /**
- * Journaled read-only observations of the workspace, executed by the harness.
- * Replay returns the journal-recorded value. Prefer passing paths to agents and
- * letting them read files with their own tools; read() and grep() are for when the
- * script itself must shard or branch on content. There is no write — writing to the
- * world is an agent task.
+ * Read-only views of the workspace. Each result is recorded, so a resumed run gets the same
+ * answer back instead of reading again. There is no write: writing is a subagent's task.
  */
 declare const files: {
-  /**
-   * List workspace files matching a glob pattern, as workspace-relative paths sorted
-   * lexicographically. Capped at 2000 files: over the cap the call rejects instead of
-   * returning a partial view — narrow the pattern.
-   */
+  /** Workspace-relative paths matching a glob, sorted. Over 2000 files the call rejects. */
   glob(pattern: string): Promise<string[]>;
   /** Read one workspace file as UTF-8 text. Size-capped. */
   read(path: string): Promise<string>;
   /**
-   * Search file contents with a ripgrep-compatible regular expression, optionally
-   * narrowed to a glob over paths (the same syntax glob() takes: "*.ts", "src/**").
-   * Returns one entry per matching line, with workspace-relative paths and one-based
-   * line numbers.
-   *
-   * Capped at 2000 matches or 256KB of results, whichever comes first. Over the cap
-   * the call rejects instead of returning a partial view — a silently truncated search
-   * is the one result you cannot reason about — so narrow the pattern or add a glob.
+   * Search contents with a ripgrep-compatible regex, optionally narrowed by a glob over
+   * paths ("*.ts", "src/**"); one entry per matching line. Over 2000 matches or 256KB of
+   * results the call rejects.
    */
   grep(pattern: string, glob?: string): Promise<GrepMatch[]>;
 };
@@ -1270,30 +1320,17 @@ declare interface GitCommit {
 }
 
 /**
- * Journaled read-only git observations — the same bargain as files.*: executed by the
- * harness, recorded in the journal, and replayed from the record, so a resumed run
- * sees the repository as it was rather than as it is now.
- *
- * Read-only by construction rather than by permission: the harness builds a fixed
- * argument list for one allowlisted subcommand and never a shell string, so there is
- * no call this surface can express that writes. A base must name a single ref — no
- * ".." ranges in this version — and paths are workspace-relative.
- *
- * Observations are scoped to the workspace, which is the same world files.* observes:
- * every path you get back is relative to the workspace and safe to pass straight to
- * files.read(). If the workspace is a subdirectory of the repository, changes outside
- * it are not reported — the workspace is the world. git.log is the exception, because
- * commits are repository-wide objects rather than paths.
- *
- * Caps reject rather than truncate (diff at 512KB, log at 100 commits), for the same
- * reason grep does. Outside a git repository, or with no git available, every call
- * rejects with a catchable error, so the idiom is try/catch with a files.glob fallback.
+ * Read-only git views, recorded like files.* so a resumed run gets the same answer back; no
+ * call can write. A base names a single ref (no ".." ranges). Paths are workspace-relative, and
+ * changes outside the workspace are not reported; git.log alone is repository-wide. Caps
+ * reject rather than truncate: diff at 512KB, log at 100 commits. Outside a git repository,
+ * or without git, every call rejects catchably.
  */
 declare const git: {
   /**
-   * Workspace-relative paths that changed. With no base: files modified against HEAD
-   * plus untracked files, because a brand-new file is a change to anyone reading. With
-   * a base ref: files differing from that ref, tracked history only.
+   * Workspace-relative paths that changed. With no base: files modified against HEAD, plus
+   * untracked files. With a base ref: tracked files whose current state differs from that
+   * ref, uncommitted edits included, untracked files not.
    */
   changedFiles(base?: string): Promise<string[]>;
   /**
@@ -1303,10 +1340,7 @@ declare const git: {
   diff(base?: string, path?: string): Promise<string>;
   /** The current working-tree status, for the workspace. */
   status(): Promise<GitStatus>;
-  /**
-   * The most recent commits, newest first. Default 20, maximum 100. Unlike the other
-   * members this reads repository-wide history, not workspace paths.
-   */
+  /** The most recent commits, newest first. Default 20, maximum 100. */
   log(count?: number): Promise<GitCommit[]>;
 };
 
@@ -1321,28 +1355,44 @@ declare interface WorldRunResult {
 }
 
 /**
- * Journaled command execution — the effect primitive. Executed by the harness exactly
- * once per call site and iteration, recorded in the journal, and replayed from the
- * record on resume (resume is crash recovery, not re-verification).
- *
- * Deliberately unlike git.*: a completed process with a NONZERO exit code RESOLVES to
- * a WorldRunResult — a failing check is the gating loop's normal case and must not
- * travel exception control flow. The promise only rejects (catchably) when the
- * command could not run as an observation at all: spawn failure, or timeout (default
- * 300000ms, override per call via timeoutMs, no upper cap).
- *
- * cmd must be a compile-time string literal: the script's command set is shown to the
- * user when the run is confirmed, and only those commands are executable. Fixed argv,
- * never a shell — no pipes, no redirection, no variable expansion; compose with
- * multiple calls and plain code. cwd is the workspace. Idiom: model generates, code
- * gates — run the check here, parse its output with pure script logic, and hand
- * failures to an agent to fix. A helper that needs Node builtins can be inlined as
- * world.run("node", ["-e", code]) — the code string lives inside the script, so it is
- * pinned by the journal key like every other argument.
+ * Run a command. Each call runs once and its result is recorded: a resumed run reuses the
+ * recorded result instead of running the command again. A completed process RESOLVES,
+ * nonzero exit included; the promise rejects (catchably) only on spawn failure or timeout
+ * (default 300000ms, timeoutMs overrides, no upper cap). cmd is a compile-time string
+ * literal, shown to the user at confirmation. Fixed argv, never a shell: no pipes,
+ * redirection or expansion. cwd is the workspace. Node builtins are reachable as
+ * world.run("node", ["-e", code]).
  */
 declare const world: {
   run(cmd: string, args?: string[], opts?: { timeoutMs?: number }): Promise<WorldRunResult>;
 };
+
+/**
+ * A stream of typed items between two stages: one stage send()s, another drains it with
+ * for await. Unbounded, first-in-first-out, each item to exactly one receiver.
+ */
+declare interface Channel<T> extends AsyncIterable<T> {
+  /** Enqueue one item; synchronous, never waits. Throws ChannelClosed after close(). */
+  send(item: T): void;
+  /**
+   * End the stream: receivers get the remaining items, then their loops exit. Idempotent.
+   * A channel nobody closes fails the run as ChannelDeadlock, naming it, once nothing in
+   * flight could send to it again.
+   */
+  close(): void;
+}
+
+/**
+ * Create a channel. The name labels the deadlock message; it is not an identity. A receiver
+ * on an empty, open channel waits until a send or the close.
+ */
+declare function channel<T>(name?: string): Channel<T>;
+
+/**
+ * Run an async block as a concurrent stage. It starts immediately, not when awaited, and
+ * returns its promise.
+ */
+declare function future<T>(body: () => Promise<T>): Promise<T>;
 ```
 <!-- facade-dts:end -->
 
@@ -1362,10 +1412,11 @@ declare const world: {
 - `world.run` executes a real command. Its first argument must be a compile-time string
   literal — the script's command set is shown to the user at confirmation — so interpolate
   runtime values into the args array, never into the command name. A nonzero exit code
-  comes back as a value (`{ exitCode, stdout, stderr }`), not an exception: branch on
-  `exitCode` for gate checks. Default timeout 300s; override per call with `timeoutMs` (no
-  cap). Spawn failures and timeouts reject; stdout or stderr over 256KB rejects like any
-  other over-cap world read.
+  comes back as a value, not an exception (§5).
+- `hole<T>()` (§15): explicit type argument; a literal name of at most 128 characters,
+  unique among the script's holes and phase markers; the call awaited and written inline;
+  outside every array-method fan-out callback (a `for...of` body is fine); the body reads no
+  binding declared after the hole. All of these are diagnostic 9012.
 - Phases are required (§8): cover the whole script with `phase("...")` markers, one at the
   head of each stage. The name is a compile-time string literal and the call is a standalone
   statement; the marker claims the rest of its enclosing block, nested blocks and inlined
@@ -1377,20 +1428,24 @@ declare const world: {
 - Subagent names: the name you pass to `agent("...")` is the card the user sees, so write
   it for the user in the session's language (§9). It is also an identity: unique within the
   run, and the key an amended run matches its cached results by. Keep names stable across
-  revisions of the same script, and give duplicates in a loop their own computed names.
+  revisions, and give duplicates in a loop their own computed names.
 - Artifact ids and the `report` tag are compile-time literals; one id belongs to one
   artifact kind; at most one artifact carries `primary: true`; a preset artifact is declared
-  at the top level, not inside a loop, callback or branch (§10). Publishing rejects
-  catchably when the file is missing or too large.
-- Model-side errors never reach the script. Rate limits, concurrency limits, overload,
-  network errors, timeouts and unknown provider errors are retried by the runtime without
-  limit while it adapts the fan-out to what the provider accepts; a deterministic one
-  (expired sign-in, model not in the plan, quota cap, invalid request) stops the whole run as
-  `stopped` so the user can fix the cause and resume it. So do not write retry loops or
-  `try`/`catch` for provider errors. Reserve them for logic failures — a subagent result
-  that failed validation, a gate that did not pass, a world read over its cap, an artifact
-  publish whose source file is missing, or a `ContextLimit` (the ask was too large for the
-  model's context even after compaction: split the work or send less).
+  at the top level, not inside a loop, callback or branch (§10), and a fill's body is where
+  its hole stands. Publishing rejects catchably when the file is missing or too large.
+- Model-side errors never reach the script. Rate limits, overload, network errors and
+  timeouts are retried by the runtime without limit while it adapts the fan-out; a
+  deterministic one (expired sign-in, model not in the plan, quota cap) stops the run as
+  `stopped` for the user to fix and resume. Write no retry loops or `try`/`catch` for
+  provider errors; reserve them for logic failures — a result that failed validation, a gate
+  that did not pass, a world read over its cap, a missing artifact source, or a
+  `ContextLimit` (the ask outgrew the model's context even after compaction: split it).
+- `channel`, `future`, `Channel.send` and `Channel.close` are facade callables: call them
+  directly (9001 applies to a stored or aliased call); a channel value itself may be stored
+  or passed freely. `send` after `close()` throws
+  `ChannelClosed`, catchable. Stalls fail the run, never time out: `ChannelDeadlock` when
+  receivers wait on channels nothing can send to any more (naming each), `ScriptStalled` when
+  some other promise can never settle.
 - The final `return` is the model-facing result; artifacts are the user-facing deliverable.
   Never put the same content in both.
 - On diagnostics, edit the file the result names and call the tool again with `path`; never
@@ -1440,8 +1495,8 @@ would describe a workspace that no longer exists, so they run live too. Asks tha
 answered keep settling from the cache. Editing an ask's text is how you force it to run
 again; keep names stable and keep tunable constants out of ask text (§13).
 
-An inline `script` that does not compile comes back as diagnostics: fix the file the result
-names and call again with `path` — nothing was stopped and nothing was started.
+On diagnostics nothing was stopped and nothing was started; fix the file the result names
+and call again with `path`.
 
 **Confirmation.** A run this session started (through `CreateWorkflow`, a previous
 `AmendWorkflow` or the workflows hub) is amended without a confirmation window, even while
@@ -1454,9 +1509,8 @@ settles. Do not wait for it or poll it with `TaskOutput`.
 
 Saves a script with its metadata so it can be run again by name — through `CreateWorkflow`'s
 `saved` source, discovered with `ListSavedWorkflows`. Project definitions go in
-`.dcode/workflows/<name>.dwf.ts`, committed with the repository and visible only inside it;
-global definitions go in `~/.dcode/workflows/<name>.dwf.ts` and are available from every
-project on this machine.
+`.dcode/workflows/<name>.dwf.ts`, committed with the repository; global definitions go in
+`~/.dcode/workflows/<name>.dwf.ts` and are available from every project on this machine.
 
 **When to call it.**
 
@@ -1466,15 +1520,13 @@ project on this machine.
   different inputs — suggest saving it in prose, one sentence naming what you would save and
   why, then stop and wait. Call `SaveWorkflow` only after the user agrees, or when the user
   asks directly ("save this workflow", "保存这个工作流"). A one-off script tailored to a
-  single question is not worth suggesting; it wastes the user's attention and clutters the
-  project.
+  single question is not worth suggesting.
 
 **Fields.**
 
 - `name`: a file-safe identifier (letters, digits, dot, dash and underscore). Saving over an
-  existing name replaces that workflow; the confirmation tells the user whether this is a
-  new file or an overwrite, so reuse a name to update a workflow and pick a new one to add a
-  variant.
+  existing name replaces that workflow, and the confirmation says whether the file is new or
+  an overwrite: reuse a name to update, pick a new one for a variant.
 - `description` (required) and `whenToUse`: written for a reader who has not seen this
   conversation. `description` shows up wherever the workflow is listed.
 - `scope` (required, no default): `project` when the script references this repository's
@@ -1485,11 +1537,9 @@ project on this machine.
   file is dropped, because the metadata comes from this call's fields. `script` is the body
   only — no metadata block.
 - `args`: name exactly the values that would change between runs — a PR number, a
-  directory, a depth — and no more; every declared argument is one more thing a future
-  caller has to get right. Each declaration gives a `type` (`string`, `number`, `boolean`,
-  or `json` for anything else), and optionally a `description`, `required: true` and a
-  `default`. Declared arguments are the workflow's calling convention; every future call is
-  validated against them.
+  directory, a depth. Each declaration gives a `type` (`string`, `number`,
+  `boolean`, or `json` for anything else), and optionally a `description`, `required: true`
+  and a `default`; every future call is validated against them.
 
 The saved file is valid TypeScript: a `/* dcode-workflow` block of YAML metadata, then the
 script verbatim. The script is typechecked by the same compiler as `CreateWorkflow`, before
@@ -1501,20 +1551,43 @@ get.
 
 Compiles and runs a small snippet synchronously against the same compiler, sandbox and
 world-read execution path a real run uses, and returns the result in the tool call. Nothing
-persists: no journal rows, no background task, no run. It is the test bench for authoring
-(§6): before writing or revising a script, check a parser against real command output, see
-what a glob actually returns (workspace-relative sorted paths, cap rejections), or exercise a
-gate predicate on real repository state, instead of guessing. It is not for orchestration:
-there is no `agent()` here.
+persists: no journal rows, no background task, no run. It is the test bench of §6, for the
+fixed logic of a script or of a hole's body; it is not for orchestration.
 
 - `code` or `path`, never both: the snippet inline, or a file holding it, read whole with no
   metadata handling.
 - `timeoutMs`: the wall clock for the whole snippet in milliseconds; default 60000, at most
   600000.
-- The snippet facade is the `args`, `log`, `files`/`git` and `world.run` parts of the block
-  in §16.2; `agent()`, `report()`, `artifact.*` and the `phase` marker do not exist here and
+- The snippet facade is the `args`, `log`, `files`/`git`, `world.run`, `channel` and `future`
+  parts of the block in §16.2; `agent()`, `report()`, `artifact.*`, `hole()` and the `phase`
+  marker are the only absentees — they do not exist here and
   fail typechecking. The language rules are a script's: plain interfaces, top-level `await`, a
   final `return <value>`. The returned value is serialized into the result, so return a
   summary, not a dump; over 256KB fails the call. `log(...)` lines come back in order. A
   snippet that contains `world.run` asks the user for confirmation before running. On
   diagnostics nothing ran: fix the snippet and call again.
+
+### 16.7 `FillWorkflowHole`
+
+Writes the body of a hole a run is waiting at (§15). It starts nothing: the run keeps its id,
+journal and subagents, and the effective script — the run's script with the body spliced in —
+is what a resume replays, an amend revises and `SaveWorkflow` keeps.
+
+- `run_id` and `hole_id` (required): from the notification or `GetWorkflowRun`; the hole id
+  is the site id (`hole#21b40fca`), not the name.
+- `script` or `path`, never both: the body's statements only. An inline `script` is written to
+  a fill file under `.dcode/workflow-drafts/` before it is compiled and the result names it;
+  `path` is usually that file after an `Edit`, and bytes equal to the last rejected attempt
+  are refused as `fill_unchanged`.
+
+The body is compiled where the hole stands, against the whole script; a diagnostic is anchored
+to the file it falls in — the fill file inside the body, the run's draft outside it — and on
+diagnostics nothing is spliced. A body may name only the models the run was launched with; any
+other model is diagnostic 9011 — to add one, amend the run.
+`hole_not_waiting` means the run is not in flight or not
+waiting at that hole (filled, not yet reached, unknown id); resume a stopped run first and the
+hole asks again. A body may end in a new tail hole instead of returning (§15). On success the
+response names the phases added and the run's draft, rewritten in place with the effective
+script. Confirmation follows the amend rule (§16.4): this session's run fills without a
+window; otherwise the window shows the new stations and the `world.run` commands the body
+adds.