@qwen-code/qwen-code 0.23.2 → 0.23.3-nightly.20260911.aaa6a32aae

package/bundled/review/references/persistence.md

@@ -72,6 +72,8 @@ The JSON helper is fail-closed because it carries the authoritative review resul
 
 ### Incremental review cache
 
+The automatic `reviewProfile: "docs-nav"` pass never updates or promotes this cache. Its focused-coverage disclosure withholds the posted ledger's SHA/model anchor; preserve any earlier full-review cache unchanged.
+
 If reviewing a PR **at high effort**, update the review cache for incremental review support. Low and medium reviews must NOT write it, and neither must a `--topology minimal` run at any effort — a cache hit would make a later high-effort review of the same SHA report "No new changes since last review", silently converting a cheaper pass into a full-review verdict.
 
 **A local or file-path review at high effort writes its cache the same way, from the capture's candidate.** **Before promoting, CHECK the candidate is this round's own:** read the file at the plan's `cacheCandidatePath` and compare its `stateId` to the plan's `cacheCandidateStateId` — the path is stable per target and local/file reviews take no lease, so a concurrent same-target run overwrites the file mid-round, and promoting the foreign candidate would anchor the next round's "no changes" to a tree this round never reviewed. A mismatch (or an absent `cacheCandidateStateId` field on a plan that published a path) is treated exactly like a withheld candidate: skip the cache write and say so. `capture-local` wrote this round's content anchor to the plan's `cacheCandidatePath` (`.qwen/tmp/qwen-review-<target>-cache-candidate.json`): the hashed per-file state and HEAD of exactly what was captured, deterministic, not yours to recompute. Read that file, add the ledger fields — `lastReviewDate`, `round`, `findingsCount`, `verdict`, and `findings[]` under the same id-carrying rules as the PR cache below — and write the merged object to the path the capture named in its plan, `cachePath` — **read that field, do not compute the name**, for the reason the incremental bullet in Step 1 gives: `target` is derived inside the command and `safeTarget` is not hand-reproducible. **The fail-closed conditions here are keyed to the PR cache's marker rule below — one definition, read twice.** Do NOT apply that rule's literal CHECK here: it keys on a `sha` inside the posted review's `qwen-review-ledger` marker, and a local round posts nothing and has no marker to read — a literal check would skip this write on every round and the feature would never persist. What this write takes from that rule is its WITHHOLDING CONDITIONS, applied as conditions on this round's own caps. For a local or file-path round the rule is a POSITIVE one, deliberately — and its fail-closed half is deliberately NOT a list: the list that lived here was "completed" three times, and each time a fourth shape walked through it (the last one an Uncoverable chunk and a whiffed lens, which withheld the PR marker's `sha` but never this write). **Write the cache only when every Critical this round raised carries a confirmed disposition: fixed, or confirmed-standing and recorded in `findings[]` under an id — and skip this write under any condition that would withhold the PR marker's `sha` in the rule below, plus the one local-only condition the marker cannot see: a non-empty `skippedFiles` in the capture (skipped content is in no diff and no hash).** At the time of writing those conditions are: `cannotTellCriticals` (a verifier that returned CANNOT-TELL, or a deadline stop or timed-out batch that never returned one), an Uncoverable chunk, the context-unavailable state, `scopeUnproven` (a chunk nobody read, an idle or blind agent), a finding still marked `— [unverified]`, the deterministic gates, and any `unreviewedDimensions` entry other than a depth-only build-and-test one (a whiffed lens withholds the marker's `sha`, so it withholds this write). The examples are the set as written, not the gate: the gate is the marker paragraph's withholding set — if it changes, this write changes with it, because a second hand-copied list here is how they drifted once already. Anything else withholds the candidate and says so. The reason is one reason, and it is why the rule is stated as a rule: the anchor's whole claim is "the next round may skip this", and a claim nobody ruled on is exactly what the next round must not skip — the round after it stops decided over a Critical that was never verified: skipped content is in no diff and no hash, so a candidate promoted over it would anchor the next round's "no changes" past work this round could not read. A run that ended with unreviewed or undecided scope skips this write and says so, because the candidate would anchor the next round's skip past scope nobody reviewed. (A capture that detected a mid-capture tree change — or a tracked path carrying a visibility bit, or an enumeration of them that failed — withholds the candidate itself and says so; then there is nothing to promote.) Low and medium local reviews must NOT write it, for the PR cache's exact reason.

package/bundled/review/references/posting.md

@@ -103,28 +103,45 @@ Read `.qwen/tmp/qwen-review-{target}-presubmit.json`. Schema:
   existingComments: {
     total: number;
     byBucket: { stale, resolved, overlap, repost, noConflict: number };
-                                 // repost entries are a SUBSET of overlap and
-                                 // are counted in both: every re-post target
-                                 // is also an overlap
+                                 // a top-level re-post target is ALSO an
+                                 // overlap and is counted in both; the
+                                 // pipeline's own carry-REPLY inside a
+                                 // replied-to thread appears in repost ONLY
+                                 // (an exemption carrier, never an overlap)
                                  // Comment = { id, path, line, commit_id,
                                  //   body — an 80-char excerpt,
                                  //   user? — the author login when known }
     overlap: Comment[];          // BLOCK on submit — except a finding whose
-                                 // id matches a repost entry at the same
-                                 // location (see repost below)
+                                 // id appears in matchedIds of ANY repost
+                                 // entry, wherever that entry sits (see
+                                 // repost below)
     repost: (Comment & { matchedIds: string[] })[];
-                                 // overlap comments matched as re-post
-                                 // targets — by a carried-id prefix in the
-                                 // claim line, or (when unambiguous) a truly
-                                 // id-less own-account original — exempt
-                                 // those findings from the drop (see below)
+                                 // a ROOT leg's matchedIds are the ids of
+                                 // findings at that entry's own location; a
+                                 // carry-reply leg's are id-joined, and its
+                                 // path/line are the reply's own anchor
+                                 // (`original_line` when GitHub unmapped it,
+                                 // else 0) — never null
+                                 // re-post targets: overlap comments matched
+                                 // by a carried-id prefix in the claim line,
+                                 // or (when unambiguous) a truly id-less
+                                 // own-account original, at the finding's
+                                 // location; PLUS the pipeline's own carry-
+                                 // reply carrying a wanted id, at ANY
+                                 // location (in repost only) — exempt those
+                                 // findings from the drop (see below)
     stale: Comment[];            // log "Skipped N stale ..."
     resolved: Comment[];         // log "Skipped N replied-to ..."
     noConflict: Comment[];       // log "Found N prior with no overlap ..."
   };
   downgradeApprove: boolean;        // submit COMMENT instead of APPROVE
   downgradeRequestChanges: boolean; // submit COMMENT instead of REQUEST_CHANGES (self-PR only)
-  downgradeReasons: string[];       // human-readable; join with '; ' for body
+  downgradeReasons: string[];       // human-readable; copy them into the
+                                    // compose state — `compose-review` caps
+                                    // each at 400 code points (a longer one
+                                    // is cut and ends in `…`), drops the
+                                    // ones past a 2000-point total, and
+                                    // joins and escapes what is left
   blockOnExistingComments: boolean; // one or more overlaps — drop those findings
                                     // (except carried-id re-posts, see below)
   findingsFileInvalid: boolean;     // the --new-findings file was unreadable:
@@ -150,9 +167,9 @@ Read `.qwen/tmp/qwen-review-{target}-presubmit.json`. Schema:
 
 **Apply the report:**
 
-- `blockOnExistingComments=true` → **an overlap is a duplicate; the disposal is deterministic — do not ask the user.** Drop each finding whose `(path, line)` appears in `existingComments.overlap` from your `comments` array — **except a finding whose `id` appears in `matchedIds` of an `existingComments.repost` entry at the same location**: that is a Step 6 ledger re-post, and re-posting under the original id is exactly how the id survives into the next round's marker — GitHub stacks it in the original thread, which is where it belongs. The inline counts follow automatically, because `submit` counts the comments you actually attach, so a dropped Critical is simply no longer there to count (and a dropped Critical that was already on the PR does not belong in `state.bodyCriticals` either). List each dropped finding in the terminal summary as "already reported at <path>:<line> — comment <id> (by <user>): <excerpt>", taking `<id>`, `<user>` (omit the `(by <user>)` slot when the entry carries no `user`), and the 80-char `<excerpt>` from the overlapping comment (`existingComments.overlap` entries carry all three), and submit the remainder without pausing. Naming the author is what makes an authorship-refused re-post exemption self-explanatory: the drop line then shows a DIFFERENT author next to the matching id. Name the comment on EVERY drop — that is what makes a same-line false positive visible to the operator instead of a bare location. This decision point has been improvised as an interactive question, which stalls a headless run forever (measured; DESIGN.md — The interactive overlap question); the Exclusion Criteria already forbid re-reporting discussed issues, so there is nothing to ask. (If dropping overlaps leaves zero findings, that is still not a question: submit with an empty `comments` array like any other run — `submit` composes the body from `state`, and a run with nothing to add posts whatever that computes. A recap like "all already reported, N resolved by `<sha>`, two still standing" goes in the **terminal summary**, not the PR: `compose-review` has no free-text body field to carry it (see Step 7 — you do not author PR-facing prose), and it is never a `gh pr comment` — a hand-posted issue comment bypasses the authorisation gate, the downgrade semantics, and the `posted` contract all at once.)
+- `blockOnExistingComments=true` → **an overlap is a duplicate; the disposal is deterministic — do not ask the user.** Drop each finding whose `(path, line)` appears in `existingComments.overlap` from your `comments` array — **except a finding whose `id` appears in `matchedIds` of ANY `existingComments.repost` entry** — a root leg matches at the finding's `(path, line)`, while a carry-reply leg (the pipeline's own reply inside a replied-to thread) matches on the id alone and its own `path`/`line` are the REPLY's — `original_line` when GitHub unmapped the anchor, else `0`, never null — which is routinely not where the finding sits, so never re-check the location: that is a Step 6 ledger re-post, and re-posting under the original id is exactly how the id survives into the next round's marker. Keep it in the array — on GitHub, `submit` posts it as a **reply in that original thread** rather than a new inline comment (the Create Review API opens a new thread per comment; only the replies endpoint joins one), so the finding keeps one thread across rounds instead of accumulating one per round (GitHub only: an Aone target has no review-thread graph, and the re-post stays inline there). Whenever the posting pass cannot reach an unresolved thread this account opened under the id — a resolved or gone original, a foreign or id-less root, a `(fix-induced)` re-report, or a draft that finds every live thread under the id already answered this round — the re-post goes inline and opens a fresh thread; the exemption is what lets it through to do either. The inline counts follow automatically, because `submit` counts the comments you actually attach, so a dropped Critical is simply no longer there to count (and a dropped Critical that was already on the PR does not belong in `state.bodyCriticals` either). List each dropped finding in the terminal summary as "already reported at <path>:<line> — comment <id> (by <user>): <excerpt>", taking `<id>`, `<user>` (omit the `(by <user>)` slot when the entry carries no `user`), and the 80-char `<excerpt>` from the overlapping comment (`existingComments.overlap` entries carry all three), and submit the remainder without pausing. Naming the author is what makes an authorship-refused re-post exemption self-explanatory: the drop line then shows a DIFFERENT author next to the matching id. Name the comment on EVERY drop — that is what makes a same-line false positive visible to the operator instead of a bare location. This decision point has been improvised as an interactive question, which stalls a headless run forever (measured; DESIGN.md — The interactive overlap question); the Exclusion Criteria already forbid re-reporting discussed issues, so there is nothing to ask. (If dropping overlaps leaves zero findings, that is still not a question: submit with an empty `comments` array like any other run — `submit` composes the body from `state`, and a run with nothing to add posts whatever that computes. A recap like "all already reported, N resolved by `<sha>`, two still standing" goes in the **terminal summary**, not the PR: `compose-review` has no free-text body field to carry it (see Step 7 — you do not author PR-facing prose), and it is never a `gh pr comment` — a hand-posted issue comment bypasses the authorisation gate, the downgrade semantics, and the `posted` contract all at once.)
 - `downgradeApprove` / `downgradeRequestChanges` / `downgradeReasons` → **do not apply these by hand.** Copy them into the `presubmit` field of the `compose-review` input (listed with the state fields in Step 6's Verdict section); the subcommand owns the semantics its tests pin — a downgrade fires only when the verdict it names is the one on the table (a Suggestion-only review is already Comment, so nothing is downgraded and no "Downgraded" sentence is emitted), the downgrade sentence carries the reasons, and a downgraded Request changes keeps its body Criticals after the sentence so the self-PR downgrade never erases the only copy of a blocker.
-- `headDrift.drifted=true` → **commits nobody reviewed are on the PR; the verdict can no longer certify the pull request as it stands.** The Approve cap has already fired through the downgrade machinery (the reason names both SHAs — it rides into the body with the other reasons; never hand-apply). What happens to the _submission_ is decided by **`headDrift.anchorsAtRisk`, which presubmit computes — do not re-derive it by hand**: pass `--new-findings` so it has your anchors, and it rules fail-safe on every hole a hand intersection falls into (a truncated `filesTouched` list (measured; DESIGN.md — The 283-file drift cap), the compare API's own 300-file ceiling, a `diverged` force-push, an unavailable compare, or a missing findings list). **`--new-findings` must carry EVERY finding's file, not only the inline-anchored ones** — a body-only Critical (one that could not be mapped to a diff line) still names a file, and if that file is omitted a drift touching it reads as `anchorsAtRisk=false`; include one `{path, line}` per body Critical (any placeholder `line`, e.g. `1`, and NO `id` — the drift intersection keys on `path` only, but the carried-id re-post exemption intersects on `(path, line)` plus id, so a placeholder line carrying an id could alias an inline finding's location and corrupt its exemption; a body-only Critical is never posted inline and can never be a re-post target). **`anchorsAtRisk=true`**: the anchors themselves are at risk and the findings may already be fixed — apply the 422-recovery rule _proactively_: abandon this submission, say so, and restart at the new SHA from Step 1's `fetch-pr`. **One exception — the CI salvage contract:** when the environment carries `QWEN_REVIEW_SALVAGE_POST=1` **and** the file named by `QWEN_CI_REVIEW_SALVAGE_OK_FILE` exists with content equal to `headDrift.reviewedSha`, the workflow's supersede watcher has already ruled this run salvage-eligible and a queued replacement run owns the new head — do **not** restart: submit as planned exactly as in the `anchorsAtRisk=false` branch (the review is of `fetchedSha`, the downgrade sentence names the drift, and the workflow's gh guard admits the post against that pinned head), and this consumes no restart. Either half missing — an explicit run exports no signal, and a marker alone is forgeable — and the rule above stands. **`anchorsAtRisk=false`**: submit as planned — the review is of `fetchedSha` (`submit` posts that very SHA as `commit_id`), the body's downgrade sentence says so, and if GitHub still answers 422 the recovery path below takes over. Name the drift in the terminal summary either way.
+- `headDrift.drifted=true` → **commits nobody reviewed are on the PR; the verdict can no longer certify the pull request as it stands.** The Approve cap has already fired through the downgrade machinery (the reason names both SHAs — it rides into the body with the other reasons; never hand-apply). What happens to the _submission_ is decided by **`headDrift.anchorsAtRisk`, which presubmit computes — do not re-derive it by hand**: pass `--new-findings` so it has your anchors, and it rules fail-safe on every hole a hand intersection falls into (a truncated `filesTouched` list (measured; DESIGN.md — The 283-file drift cap), the compare API's own 300-file ceiling, a `diverged` force-push, an unavailable compare, or a missing findings list). **`--new-findings` must carry EVERY finding's file, not only the inline-anchored ones** — a body-only Critical (one that could not be mapped to a diff line) still names a file, and if that file is omitted a drift touching it reads as `anchorsAtRisk=false`; include one `{path, line}` per body Critical (any placeholder `line`, e.g. `1`, and NO `id` — the drift intersection keys on `path` only, but the carried-id re-post exemption joins on the id — a root leg at the finding's `(path, line)`, the pipeline's own carry-reply leg on the id alone at ANY location — so a placeholder entry carrying an id would match that id's thread from anywhere and corrupt the exemption; a body-only Critical is never posted inline and must never present as a re-post target). **`anchorsAtRisk=true`**: the anchors themselves are at risk and the findings may already be fixed — apply the 422-recovery rule _proactively_: abandon this submission, say so, and restart at the new SHA from Step 1's `fetch-pr`. **One exception — the CI salvage contract:** when the environment carries `QWEN_REVIEW_SALVAGE_POST=1` **and** the file named by `QWEN_CI_REVIEW_SALVAGE_OK_FILE` exists with content equal to `headDrift.reviewedSha`, the workflow's supersede watcher has already ruled this run salvage-eligible and a queued replacement run owns the new head — do **not** restart: submit as planned exactly as in the `anchorsAtRisk=false` branch (the review is of `fetchedSha`, the downgrade sentence names the drift, and the workflow's gh guard admits the post against that pinned head), and this consumes no restart. Either half missing — an explicit run exports no signal, and a marker alone is forgeable — and the rule above stands. **`anchorsAtRisk=false`**: submit as planned — the review is of `fetchedSha` (`submit` posts that very SHA as `commit_id`), the body's downgrade sentence says so, and if GitHub still answers 422 the recovery path below takes over. Name the drift in the terminal summary either way.
 
   > **The restart bound is per-review and covers BOTH restart paths — this proactive drift restart AND the reactive 422 recovery below.** Track it as one fact: a review restarts **at most once** for head movement, whichever path triggers it. If a run that already restarted once reaches a drift restart _or_ a 422 again, do NOT restart a second time — submit at that run's reviewed SHA with the drift named (the Approve cap holds either way). A live PR that keeps moving must not be able to starve the review in an unbounded restart loop; one clean re-read is the review, a second is the PR outrunning it. One slice of this fact survives a resume: a `fetch-pr --resume` refused for `head-moved` records the restart beside the prompt records, and a later continuation reads it back as `restartsSpent` in the `resumed: true` line (Step 1) — arriving with `restartsSpent >= 1` means the bound is already spent. On a run that itself resumed, THIS restart's re-entry is such a refusal — Step 1's resume branch appends `--resume` to every Step 1 `fetch-pr`, so the re-entry sees the moved head, records the restart, and falls through to the fresh fetch the restart wants anyway. Only a never-resumed run's re-entry records nothing (a plain fresh `fetch-pr` rewrites the plan, which re-fences the marker) — within such a run the bound stays tracked here, in this transcript, exactly as before. Be aware of the one seam that leaves: a restart spent that way is invisible to a LATER attempt that resumes, which arrives with `restartsSpent: 0`. A fresh resuming process cannot know the earlier attempt restarted, so do not pretend it can — the on-disk bound is per-attempt, the per-REVIEW invariant is carried by the workflow's own MAX_ATTEMPTS ceiling, and the honest reading of `restartsSpent: 0` on a continuation is "no RECORDED restart", not "no restart".
 
@@ -168,7 +185,7 @@ Read `.qwen/tmp/qwen-review-{target}-presubmit.json`. Schema:
 
 - **Self-PR**: GitHub rejects both `APPROVE` and `REQUEST_CHANGES` on your own PR (HTTP 422); `COMMENT` is the only accepted event. Critical and Suggestion findings still appear as inline `comments` regardless, so substantive feedback is preserved.
 - **CI failure / pending**: the LLM review reads code statically and cannot see runtime test failures. Approving on red CI is misleading; pending CI means the verdict is premature.
-- **Overlap with existing comments**: posting on the same `(path, line)` as an existing Qwen comment produces visual duplicates, so overlapping findings are dropped rather than re-posted — with one exception by construction: a carried-id re-post belongs in the original thread (GitHub stacks same-line comments there), so a finding whose ledger id matches the existing comment at its location is exempted via `existingComments.repost`, and every drop names the overlapping comment so a same-line false positive stays visible. The match reads the id as the claim-line PREFIX (mirroring how the ledger marker reads it back), and a truly id-less OWN-account original is still matched when the target is unambiguous — exactly one own-account comment at the location and exactly one carried finding there (round-1 originals carry no id token; without this fallback their re-post would read as a plain overlap and be dropped). **Known limitation — the residue is the AMBIGUOUS case only**: an id-less original at a location with several own-account comments, or several carried ids at the location, or an id-less original whose body still mentions ANY ledger-id-shaped token (even a cross-reference — any token marks the comment as belonging to a specific finding's thread, so the fallback stays off), cannot be matched as a re-post target; the re-post of such a finding reads as a plain location overlap and is dropped — visibly, the drop log names the comment. A same-SHA re-run after an already-posted re-post can match that earlier re-post as the target and post a second copy (the two are structurally indistinguishable); the lineage self-heals next round through the new comment's prefix. A replied-to original still counts toward the ambiguity decision but is itself bucketed `resolved`, never a target. Stale-commit and replied-to comments are skipped silently — they're false-positive overlap from line-based matching.
+- **Overlap with existing comments**: posting on the same `(path, line)` as an existing Qwen comment produces visual duplicates, so overlapping findings are dropped rather than re-posted — with one exception by construction: a carried-id re-post belongs in the original thread, and `submit` puts it there (replying into the thread its ledger id names rather than opening a new one — same-line re-posts do NOT stack on their own, which is how one finding used to accumulate a thread per round), so a finding whose ledger id matches an own existing comment — a root at the finding's location, or the pipeline's own carry-reply in that id's thread, wherever its anchor now sits — is exempted via `existingComments.repost`, and every drop names the overlapping comment so a same-line false positive stays visible. The match reads the id as the claim-line PREFIX (mirroring how the ledger marker reads it back), and a truly id-less OWN-account original is still matched when the target is unambiguous — exactly one own-account comment at the location and exactly one carried finding there (round-1 originals carry no id token; without this fallback their re-post would read as a plain overlap and be dropped). **Known limitation — the residue is the AMBIGUOUS case only**: an id-less original at a location with several own-account comments, or several carried ids at the location, or an id-less original whose body still mentions ANY ledger-id-shaped token (even a cross-reference — any token marks the comment as belonging to a specific finding's thread, so the fallback stays off), cannot be matched as a re-post target; the re-post of such a finding reads as a plain location overlap and is dropped — visibly, the drop log names the comment. A same-SHA re-run after an already-posted re-post posts a second copy — under the reply mechanism, as a second reply in the same thread (the replied-to original is bucketed `resolved` and skipped by the overlap check, and the pipeline's own carry-reply inside that thread still carries the id as a `repost` exemption — so the re-post is not dropped even when another own comment overlaps the location); the thread stays one thread either way. A replied-to original still counts toward the ambiguity decision but is itself bucketed `resolved`, never a target. Stale-commit and replied-to comments are skipped silently — they're false-positive overlap from line-based matching.
 
 ⚠️ **Severity routing — high-confidence Critical AND Suggestion findings both go inline, pinned to the exact code line.** They are distinguished by the `**[Critical]**` / `**[Suggestion]**` prefix in the comment body, not by where they are posted.
 

package/bundled/workflow-authoring/SKILL.md

@@ -0,0 +1,410 @@
+---
+name: workflow-authoring
+description: Reference for writing a Workflow tool script (script API and gotchas, agent() options, pipeline() vs parallel(), verification and convergence patterns, resume, worked example). Load before authoring a script for a workflow the user already opted into; it does not itself authorize running one.
+---
+
+# Workflow authoring reference
+
+Everything below is about _writing_ the script. Whether a workflow may run at
+all is decided by the Workflow tool's own opt-in rule — this reference does
+not authorize a run.
+
+Reach for one to be comprehensive (decompose the work and cover every part in
+parallel), to be confident (independent perspectives and adversarial checks
+before an answer is committed to), or to take on scale a single context cannot
+hold — migrations, audits, broad sweeps. The script is where that structure is
+encoded: what fans out, what verifies, what synthesizes. Parallelism on its own
+is not a reason; work that is already one short sequence of edits belongs in
+the main loop.
+
+## Scout first, then orchestrate
+
+The strongest pattern is hybrid: discover the work list in the main loop (list
+the files, scope the diff, read the failing test), then hand that list to a
+workflow. You do not need to know the shape of the work before the task — only
+before the orchestration step. When the work has distinct phases, run several
+small workflows across turns and read each result before choosing the next,
+rather than authoring one large script that runs unattended.
+
+Common single-phase shapes: understand (parallel readers over subsystems,
+merged into one map), design (independent approaches, judged, then
+synthesized), review (dimensions, find, verify each finding), research (broad
+sweep, deep read, synthesis), migrate (discover sites, transform each under
+`isolation: 'worktree'`, verify).
+
+## Script contract
+
+The source is wrapped as an async IIFE, so top-level `await` and a top-level
+`return` are both legal — and a trailing expression is _not_ a return value.
+End every successful path with an explicit `return`.
+
+It is plain JavaScript, not TypeScript, and it cannot `import` anything.
+
+The script may start with a literal `export const meta = {...}` declaration
+with `name`, `description`, and optionally `whenToUse` and
+`phases: [{ title, detail? }]`. It must be a pure literal — no variables,
+calls, or interpolation — and it is stripped before execution, so nothing in
+the script body can read it. Fields outside that list are dropped. The
+approval dialog prints the name, the description, and each phase title with
+its `detail` as a one-line explanation beside it: give every phase a `detail`,
+because for a run that may dispatch hundreds of agents it is what the user
+reads before approving.
+
+Injected globals, and nothing else:
+
+- `phase(title)` — open a phase. Everything dispatched afterwards is attributed
+  to it in the live phase tree, until the next phase opens.
+- `log(msg)` — one line into the run log the user watches.
+- `agent(prompt, opts?)` — dispatch one subagent. See **agent() options**.
+- `parallel(thunks)` — run thunks through the shared concurrency window,
+  resolving to a position-aligned array. `parallel()` itself rejects on
+  invalid arguments.
+- `pipeline(items, ...stages)` — run each item through the stages
+  independently. See **Default to `pipeline()`**.
+- `workflow(nameOrRef, args?)` — run a saved workflow inline. See **Saved
+  workflows and workflow()**.
+- `args` — the structured value the caller passed, or `undefined`.
+- `budget` — `budget.total` (`null` = uncapped) and `budget.spent()`.
+
+Pass THUNKS to `parallel()`, not eager calls: `parallel([() => agent(...)])`,
+not `parallel([agent(...)])`. The eager form is refused outright: a
+non-function element rejects the whole batch, and by then every `agent()` in it
+has already been admitted, counted against the caps, and spent — with its
+result discarded.
+
+A script must be deterministic so a resume replays the same call sequence.
+`Math.random()` throws, and so does all of `Date` — `new Date()`,
+`Date.now()`, `Date.parse()` and `Date.UTC()` alike. Pass timestamps in via
+`args`, or stamp the result after the workflow returns.
+
+Scripts run in a `node:vm` sandbox with no filesystem, shell, network, or
+environment access. All I/O happens through the prompts you give the agents, so
+say explicitly what each one should read and whether it may edit files.
+
+## agent() options
+
+`agent(prompt, { label?, phase?, schema?, model?, agentType?, isolation?, workingDir?, stallMs? })`
+
+- `label` (string) — the name shown in the run views and the failures list.
+  Make it unique per dispatch: a failure line carries only the label and the
+  error, so two failed dispatches that share a label cannot be told apart.
+- `phase` (string) — opens a named phase at this call, exactly as `phase(title)`
+  would: this dispatch and every dispatch issued after it are attributed to that
+  phase. It is not scoped to the one call, so in a fan-out open phases with
+  `phase()` between groups rather than per dispatch.
+- `schema` (JSON Schema object) — the subagent must deliver its result by
+  calling `structured_output` with arguments matching the schema; agent()
+  resolves to the validated object. After two in-conversation nudges without a
+  valid result, it resolves to null and the failure is recorded as "subagent
+  completed without calling StructuredOutput (after 2 in-conversation nudges)";
+  check for null.
+- `agentType` (string) — resolves against the declarative-agents registry
+  (`.qwen/agents/<name>.md`, project then user then built-in). Unresolved names
+  make the admitted agent() resolve to null and record "agent({agentType}):
+  agent type 'X' not found"; check for null.
+- `model` (string) — per-call model override; routes provider correctly via the
+  subagent runtime view.
+- `isolation` — `'worktree'` provisions a fresh git worktree under
+  `<projectRoot>/.qwen/worktrees/agent-<7hex>`; the worktree is auto-removed if
+  no changes, otherwise the path and branch are returned alongside the result.
+  `'remote'` makes the admitted agent() resolve to null and records
+  "agent({isolation:'remote'}) is not available in this build". A `'worktree'`
+  dispatch is also refused — it resolves to null with the reason recorded —
+  when the session is already inside a worktree (nested isolation worktrees are
+  not supported; to run agents in that worktree, pass it as `workingDir`), when
+  git is not available or the directory is not a git repository, when the
+  parent working tree has uncommitted changes (the subagent would see a stale
+  HEAD), or when the worktree cannot be created. The nested case refuses every
+  dispatch, so rule it out before a large `isolation: 'worktree'` fan-out.
+- `workingDir` (string) — pin the subagent to an EXISTING git worktree of this
+  repository that the caller owns; nothing is created and nothing is removed.
+  Use it when the directory the agent must work in already exists and its
+  uncommitted state is the point (a review worktree, a checkout a previous step
+  provisioned) — exactly the case isolation cannot serve. Mutually exclusive
+  with `isolation`. The path must be a linked worktree of this repository
+  registered via `git worktree add` (it may live anywhere on disk) — the main
+  checkout is not eligible.
+- `stallMs` (number, ms) — a no-progress stall watchdog, not a wall-clock cap.
+  The dispatch is aborted and retried (up to 3 attempts total) after this many
+  milliseconds with no observable subagent progress — including before the
+  first response arrives; the timer is suspended while a tool is in flight, so
+  a legitimately slow tool is not a stall. Default 180000 (override via
+  `QWEN_CODE_WORKFLOW_STALL_SECONDS`, whole seconds); `0` disables the
+  watchdog. Wall time per attempt is bounded separately.
+
+Workflow subagents can never use AskUserQuestion, SendMessage, Monitor,
+EnterPlanMode, ExitPlanMode, or the Agent tool, whatever their `agentType`. A
+subagent therefore cannot fan out further and cannot ask anyone anything: the
+script owns all fan-out, and every ambiguity has to be resolved in the prompt
+it is given. Never ask a subagent to spawn its own verifiers — dispatch them
+from the script.
+
+## What agent() returns
+
+A subagent's final text, or the validated object under `schema`.
+
+`agent()` resolves to `null` when that admitted agent fails on its own —
+including turn/time caps, model or setup errors, missing structured output, and
+exhausted stall retries — and it does so for a bare `await agent()` exactly as
+it does inside `parallel()`/`pipeline()`, so check for `null` wherever you read
+a result. Call-shape validation failures — such as an empty prompt, an
+unsupported option combination, or an invalid option value — reject a bare
+call; inside `parallel()`/`pipeline()`, the surrounding ordinary thunk or stage
+rejection becomes a position-aligned `null`. Run-level rejections no later call
+could survive — the token budget, the 1000-agent cap, and cancellation — throw
+and end a `parallel()`/`pipeline()` batch. An admitted agent that fails and
+settles to `null` still counts as dispatched and is named, with its error, in
+the run's failures list; a `null` returned by an ordinary thunk or stage is not
+an agent dispatch.
+
+A `pipeline()` stage that returns `null` — or throws — drops that item: its
+remaining stages are skipped and its slot in the result is `null`. So a `null`
+check belongs in the stage that dispatched the agent, never in a later stage,
+which will not run for that item.
+
+A result must be JSON-serializable to survive the sandbox boundary and the
+resume journal. A thunk that resolves to something that is not becomes `null`
+at its index.
+
+## Limits
+
+- Concurrency: `max(2, min(16, availableParallelism()-2))` agents in flight per
+  run — `availableParallelism()` follows CPU affinity and container CPU limits,
+  not the host's core count — override via `QWEN_CODE_MAX_WORKFLOW_CONCURRENCY`
+  (clamped to 64).
+- 1000 `agent()` calls per run, override via `QWEN_CODE_MAX_WORKFLOW_AGENTS`
+  (clamped to 10000). The call past the cap throws.
+- 30-minute wall-clock cap per run, override via
+  `QWEN_CODE_MAX_WORKFLOW_SECONDS` (applied as given). A fan-out near the agent
+  cap will not fit inside the default cap.
+- 30 seconds for the script's synchronous code before its first `await`, with
+  no override. A synchronous loop that runs longer is aborted.
+- Per subagent attempt: 50 turns (`QWEN_CODE_WORKFLOW_AGENT_MAX_TURNS`, clamped
+  to 500) and 10 minutes (`QWEN_CODE_WORKFLOW_AGENT_MAX_MINUTES`, clamped
+  to 100). Raise them for legitimately long work rather than letting agents
+  come back `null` — but a value above the clamp is silently cut down to it.
+- Stall retries: 3 attempts per `agent()` call; the stall timeout itself
+  (`QWEN_CODE_WORKFLOW_STALL_SECONDS`) is applied as given.
+- Tokens: a per-run output-token cap may be in effect — read `budget.total`
+  (`null` = uncapped) before committing to a large fan-out, because once the
+  cap is reached every further `agent()` call is refused.
+
+## Default to `pipeline()`
+
+`pipeline()` runs each item through every stage independently — item A can be
+in stage 3 while item B is still in stage 1 — so wall-clock is the slowest
+single chain. `parallel()` is a barrier: it waits for every thunk before
+anything moves on, so it costs the slowest item of every stage.
+
+A barrier is right only when a stage genuinely needs cross-item context:
+deduplicating or merging across the full result set before expensive downstream
+work, exiting early when the total count is zero, or a prompt that compares one
+finding against all the others. It is not justified by needing to flatten, map,
+or filter between stages (do that inside a pipeline stage), by two stages being
+conceptually separate, or by the code reading more tidily. Smell test:
+`parallel()` → a pure transform → `parallel()` is a pipeline someone wrote with
+an unnecessary barrier. When in doubt, `pipeline()`.
+
+## Verify before believing
+
+A subagent's answer is a claim, not a result. For findings that matter, spawn
+independent verifiers prompted to _refute_, and drop what a majority refutes.
+When a claim can be wrong in several different ways, give each verifier a
+distinct lens (correctness, security, performance, does it actually reproduce)
+— diversity catches what repetition cannot. For a wide solution space, generate
+several independent attempts, judge them in parallel, and synthesize from the
+winner while grafting the best ideas from the rest.
+
+## Converge deliberately
+
+For discovery of unknown size, keep running finders until some number of
+consecutive rounds turn up nothing new; a fixed round count stops partway into
+the tail. Deduplicate each round against everything already seen, never against
+only what survived judging — otherwise rejected findings reappear every round
+and the loop never terminates. A closing pass that asks what is still missing
+(a search angle never run, a claim never verified, a file never read) usually
+produces the next round of real work.
+
+## Report honestly
+
+Scale the fleet to what was actually asked: a quick check gets a few agents and
+one verification pass; an explicit request to be thorough or exhaustive earns a
+larger pool and a multi-vote adversarial round. Whenever a run bounds its own
+coverage — top-N, sampling, no retry — `log()` what was dropped. Silent
+truncation reads as full coverage, which is worse than a smaller honest result.
+
+## Saved workflows and workflow()
+
+`workflow(nameOrRef, args?)` runs a saved workflow inline under this run's caps
+and nests one level only — a workflow reached through `workflow()` cannot call
+`workflow()` itself, and doing so throws.
+
+It takes one of two forms. `workflow('<name>')` resolves a name against
+`<projectRoot>/.qwen/workflows` (project scope, also surfaced as `/<name>`
+slash commands) and `~/.qwen/workflows` (user scope, lower precedence when both
+define the same name). `workflow({ scriptPath: '<absolute path>' })` loads a
+script file directly from either of those directories or from the
+generated-scripts root (`$QWEN_CODE_PROJECT_DIR/workflows/generated` — the
+per-project runtime dir, not the project tree); a path outside those roots is
+refused. A bare string is always a name: a path passed as a string is rejected
+as an invalid workflow name. At the top level that rejection ends the run;
+inside `parallel()`/`pipeline()` it becomes a position-aligned `null` like any
+other thunk rejection — with no agent dispatched and nothing in the failures
+list — so null-check a `workflow()` result too.
+
+To create or edit a saved workflow, use the `workflow-creator` skill — it owns
+the file layout, naming rules, and the save round-trip.
+
+## Resume and diagnostics
+
+Every run hands back its runId, the script's path on disk, and its journal
+path. An inline script is persisted under the generated-scripts root, so a
+resume edits that file and passes the path back instead of re-sending the whole
+source.
+
+`resumeFromRunId` replays a prior run: each `agent()` call's journal key hashes
+its prompt and opts chained in call order, so calls whose rolling prefix-hash
+still matches are served from cache for the longest unchanged prefix, and the
+first changed or missing call onward runs live. Post-processing after the last
+agent can therefore change freely without losing the cache. Pass the same
+`args` — they seed the chain, so different args re-run everything.
+
+The journal is one JSON line per event: a `started` line when an agent is
+dispatched, then a `result` line when it returns a value or a `failed` line
+when it settles without one. Only `result` lines feed the resume cache. A
+`started` line with neither after it means the run was interrupted with that
+agent in flight — not that the agent is broken. Read the journal before
+diagnosing an empty or surprising result: a cached result can itself be empty,
+and a `null` slot in the output means an agent failed, not that the work found
+nothing.
+
+Runs appear in the background-tasks view and the `/workflows` dialog (live
+phase tree, token usage, cooperative pause/resume, cancel);
+`run_in_background: true` returns a run handle immediately in the interactive
+TUI and delivers completion through the conversation.
+
+## Worked example
+
+Review a change set across several dimensions, verifying each finding as soon
+as its dimension is done — a pipeline, so a slow dimension never holds up
+verification of a fast one.
+
+```js
+export const meta = {
+  name: 'Review changes',
+  description: 'Review the diff across dimensions and verify every finding',
+  phases: [
+    { title: 'Review', detail: 'One reviewer per dimension reads the diff' },
+    {
+      title: 'Verify',
+      detail: 'An independent verifier tries to refute each finding',
+    },
+  ],
+};
+
+const DIMENSIONS = [
+  {
+    key: 'correctness',
+    lens: 'logic errors, wrong edge cases, broken invariants',
+  },
+  {
+    key: 'security',
+    lens: 'injection, path traversal, secrets, unsafe defaults',
+  },
+  {
+    key: 'performance',
+    lens: 'accidental O(n^2), unbounded memory, chatty I/O',
+  },
+];
+
+const FINDINGS = {
+  type: 'object',
+  properties: {
+    findings: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          file: { type: 'string' },
+          claim: { type: 'string' },
+        },
+        required: ['file', 'claim'],
+      },
+    },
+  },
+  required: ['findings'],
+};
+
+const VERDICT = {
+  type: 'object',
+  properties: { isReal: { type: 'boolean' }, why: { type: 'string' } },
+  required: ['isReal', 'why'],
+};
+
+const target = args?.target;
+if (!target) {
+  throw new Error('args.target is required, e.g. { target: "HEAD~1..HEAD" }');
+}
+
+phase('Review');
+const reviewed = await pipeline(
+  DIMENSIONS,
+  // The stage that dispatches an agent is the stage that handles its null:
+  // returning null here would drop the dimension and skip the verify stage.
+  async (dimension) => {
+    const review = await agent(
+      `Review the changes in ${target} for ${dimension.lens}. ` +
+        `Read the files; do not edit anything.`,
+      { label: `review:${dimension.key}`, schema: FINDINGS },
+    );
+    if (review === null) {
+      log(`review:${dimension.key} came back empty — its findings are missing`);
+      return [];
+    }
+    return review.findings;
+  },
+  (findings, dimension) => {
+    phase('Verify');
+    return parallel(
+      findings.map((finding, index) => async () => {
+        const label = `verify:${dimension.key}:${index + 1}`;
+        const verdict = await agent(
+          `Adversarially verify this claim about ${finding.file}: ` +
+            `"${finding.claim}". Try to REFUTE it. Read the code first.`,
+          { label, schema: VERDICT },
+        );
+        if (verdict === null) {
+          log(`${label} came back empty — "${finding.claim}" is unverified`);
+          return null;
+        }
+        return { ...finding, verdict };
+      }),
+    );
+  },
+);
+
+// A stage that throws drops its dimension to a null slot. Say which ones
+// before flattening, or the drop reads as a dimension that found nothing.
+reviewed.forEach((entries, index) => {
+  if (entries === null) {
+    log(
+      `${DIMENSIONS[index].key} was dropped before its findings were verified`,
+    );
+  }
+});
+const verdicts = reviewed.filter((entries) => entries !== null).flat();
+const confirmed = verdicts.filter(
+  (entry) => entry !== null && entry.verdict.isReal,
+);
+const refuted = verdicts.filter(
+  (entry) => entry !== null && !entry.verdict.isReal,
+);
+log(`confirmed ${confirmed.length} finding(s), refuted ${refuted.length}`);
+return { confirmed, refuted };
+```
+
+Note what the example does with failure: it refuses to run without the input
+it needs, handles each `null` in the stage that dispatched the agent, gives
+every verify dispatch its own label, `log()`s every dimension and agent it
+loses, and returns what the verifiers refuted next to what they confirmed — a
+verifier can be wrong too, and nothing is silently omitted.

package/bundled/workflow-creator/SKILL.md

@@ -32,7 +32,7 @@ export const meta = {
 };
 ```
 
-- Use the sandbox globals documented by the `workflow` tool: `phase(title)`, `log(message)`, `agent(prompt, options?)`, `parallel(thunks)`, `pipeline(items, ...stages)`, `workflow(nameOrRef, args?)`, `args`, and `budget`.
+- Use the sandbox globals `phase(title)`, `log(message)`, `agent(prompt, options?)`, `parallel(thunks)`, `pipeline(items, ...stages)`, `workflow(nameOrRef, args?)`, `args`, and `budget`. The `workflow-authoring` skill is the full reference for them — load it before writing anything beyond a trivial script.
 - Scripts cannot import modules or access the filesystem, shell, environment, or network directly. Put required reads and actions in explicit agent prompts.
 - Give every agent a complete, scoped prompt and a concise `label`. State whether it may edit files.
 - Express real concurrency as `parallel([() => agent(...), () => agent(...)])`. Do not pass already-started promises to `parallel`.