@excitedjs/dreamux 0.22.0-beta.160 → 0.22.0-beta.161

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@excitedjs/dreamux",
-  "version": "0.22.0-beta.160",
+  "version": "0.22.0-beta.161",
   "description": "Dreamux core host for multi-dispatcher agent orchestration through provider interfaces.",
   "license": "MIT",
   "repository": {
@@ -26,11 +26,11 @@
     "CHANGELOG.json"
   ],
   "dependencies": {
-    "@excitedjs/agent-runtime-claude-code": "0.5.0-beta.160",
-    "@excitedjs/agent-runtime-codex": "0.3.5-beta.160",
-    "@excitedjs/dreamux-types": "0.8.0-beta.160",
-    "@excitedjs/dreamux-utils": "0.4.0-beta.160",
-    "@excitedjs/feishu-channel": "5.0.0-beta.160",
+    "@excitedjs/agent-runtime-claude-code": "0.5.0-beta.161",
+    "@excitedjs/agent-runtime-codex": "0.3.5-beta.161",
+    "@excitedjs/dreamux-types": "0.8.0-beta.161",
+    "@excitedjs/dreamux-utils": "0.4.0-beta.161",
+    "@excitedjs/feishu-channel": "5.0.0-beta.161",
     "acorn": "^8.16.0",
     "croner": "^10.0.1",
     "smol-toml": "^1.6.1",

package/skills/shared/workflow/SKILL.md

@@ -161,3 +161,4 @@ unavailable so orchestration stays deterministic.
 | --- | --- | --- |
 | Code review run | Carrying a change review (pull/merge request, git range, or working-tree diff) as one workflow run: eligibility gate, multi-lens finders, confidence-scored verification, one synthesized report. | [Code review](references/code-review.md) |
 | Orchestration and prompt patterns | Writing TeamMate prompts inside scripts, choosing `pipeline` versus `parallel`, and applying quality patterns: adversarial verify, judge panel, loop-until-dry, multi-modal sweep, completeness critic. | [Orchestration patterns](references/orchestration-patterns.md) |
+| Ultracode orchestration techniques | Shaping a whole task as workflows: the five archetypes (understand/design/review/research/migrate), scouting before fan-out, chaining runs with the TeamLeader in the loop, worked compositions, novel harness shapes. | [Ultracode techniques](references/ultracode.md) |

package/skills/shared/workflow/references/code-review.md

@@ -1,394 +1,157 @@
 # Code Review Workflow
 
-`../SKILL.md` owns the run tools and the script API. This reference owns one
-recipe: carrying a full code review as a single `workflow_run` — an eligibility
-gate, context collection, independent multi-lens finders, per-finding
-confidence scoring, and one synthesized report.
-
-## Contents
-
-- [Stage design](#stage-design) — the five stages and their failure accounting
-- [Prompt discipline](#prompt-discipline) — output contract, rejection
-  semantics, self-contained prompts
-- [TeamMate budget](#teammate-budget) — cost arithmetic against the run caps
-- [Script](#script) — the complete runnable module
-- [Invocation](#invocation) — call shape and result fields
+`../SKILL.md` owns the run tools and the script API. This reference teaches
+the method for carrying a code review as one `workflow_run`: the stages, the
+scoring rubric, and the false-positive discipline. Write the script for the
+task at hand — the sketch at the end shows the shape, it is not a template to
+paste.
 
 The review target is any change the Team workspace can read: a GitHub pull
 request, a GitLab merge request, a local branch or commit range, or an
-uncommitted working-tree diff. Use this recipe when the operator wants one
-terminal result for such a change. For interactive review — where the next
+uncommitted working-tree diff. For interactive review — where the next
 instruction depends on reading the previous finding — use `spawn` and `send`
 instead.
 
-## Stage design
-
-1. **Gate** — one TeamMate checks eligibility and the run exits early when
-   review is not needed: the change is closed or a draft, is automated or
-   trivially safe, or already carries a review from this Team.
-2. **Context** — two TeamMates in parallel: one lists the file paths (not
-   contents) of the repository's agent guidance files (`CLAUDE.md`,
-   `AGENTS.md`) at the root and in directories the change touches; one
-   summarizes the change (intent, scope, risk areas). Both results feed every
-   later prompt. When guidance discovery fails, the guidance lens is skipped
-   and recorded as missing coverage — it must not audit against a silently
-   empty list. A missing summary is tolerable: finders read the change
-   themselves, and the placeholder is visible in their prompts.
-3. **Find** — independent finder lenses run in parallel, each blind to the
-   others: guidance-file compliance, a shallow bug scan limited to the changed
-   hunks, git history and blame context, review comments on prior change
-   requests touching the same files, guidance stated in code comments of the
-   modified files, and concrete security issues introduced by the change. The
-   barrier is justified: deduplication needs every lens's output at once —
-   and it is where coverage is accounted: lens results are index-aligned with
-   the lens list, so a failed lens is recorded as missing coverage instead of
-   being silently dropped by `.filter(Boolean)`.
-4. **Verify** — each unique finding is scored by three TeamMates with distinct
-   focus questions (does it reproduce on the changed lines; is it pre-existing
-   rather than introduced; does the cited guidance actually say that), using a
-   fixed 0-100 rubric. Findings advance through `pipeline` independently of
-   one another: each finding's vote aggregation follows its own three votes
-   without waiting for the other findings. A finding that keeps fewer than two
-   settled votes is returned as `unverified` — verifier failure must not
-   silently launder a finding into a clean report.
-5. **Report** — findings that keep at least two settled votes and average 80 or
-   higher survive; one TeamMate formats the final review comment, noting
-   incomplete coverage and unverified findings when there are any.
-
-The run returns the report plus `coverage` and `unverified` records; the
-caller decides where the report goes. When a channel reply tool is available, post it there; or
-have a follow-up `send` to the reporter TeamMate publish it with the forge's
-own tooling (for example `gh` for GitHub or `glab` for GitLab) once the
-operator confirms.
-
-## Prompt discipline
-
-Every workflow TeamMate receives the workflow output contract: its final
-response is the value `agent()` returns, not a human-facing message. Prompts
-can therefore ask for data directly, without output-format boilerplate. With
-`schema`, the runtime's native structured-output mechanism enforces the shape.
-
-Failure semantics drive the script structure:
-
-- An ordinary failed turn settles the `agent()` call to `null`. `parallel`
-  and `pipeline` contain per-item failures as `null` entries and keep results
-  index-aligned with their inputs — account required coverage positionally
-  first (which lens failed, which finding lost its verifiers), then drop
-  nulls with `.filter(Boolean)` only where item identity no longer matters.
-- A schema call rejects — it does not return `null` — when the runtime cannot
-  provide structured output or reports success with an empty or invalid JSON
-  result. A directly awaited rejection fails the whole run; that is the right
-  outcome for load-bearing calls like the gate, and the reason the gate below
-  is awaited bare while per-finding work runs inside helpers.
-
-Keep prompts self-contained: a finder must not depend on another finder's
-output, and everything a verifier needs (the finding, the rubric, the
-false-positive list) is embedded in its prompt.
+## The flow
+
+1. **Gate.** One TeamMate checks eligibility; exit early when review is not
+   needed: the change is closed or a draft, is automated or trivially safe,
+   or already carries a review from this Team.
+2. **Context.** In parallel: list the file paths (not contents) of the
+   repository's agent guidance files (`CLAUDE.md`, `AGENTS.md`) at the root
+   and in directories the change touches; summarize the change (intent,
+   scope, risk areas). Feed both into every later prompt.
+3. **Find.** Independent finder lenses in parallel, each blind to the others:
+   - guidance-file compliance (read the discovered files; not every writing
+     instruction applies at review time);
+   - a shallow bug scan limited to the changed hunks;
+   - git blame and history of the modified code;
+   - review comments on prior change requests touching the same files;
+   - guidance stated in code comments of the modified files;
+   - concrete security issues introduced by the change.
+   Every finding must state a concrete failure scenario — the specific
+   inputs or state that produce the wrong outcome; a defect that cannot be
+   stated as a scenario is not reportable. Deduplicate across lenses by
+   file, line, and title. For an exhaustive audit, repeat find/verify rounds
+   until two consecutive rounds surface nothing new, carrying already-seen
+   findings in each round's prompts.
+4. **Verify.** Score each finding with parallel verifier TeamMates — three
+   normally, two for a quick pass — but give each verifier a *distinct focus
+   question* rather than re-asking the same one: does the defect reproduce on
+   the changed lines; is it pre-existing rather than introduced by this change;
+   does the cited guidance file or code comment actually say that. Diverse
+   focus catches failure modes that identical skeptics miss. Each verifier
+   receives the finding, the guidance paths, the false-positive list, its
+   focus question, and this rubric verbatim:
+   - 0: Not confident at all. False positive that does not stand up to light
+     scrutiny, or a pre-existing issue.
+   - 25: Somewhat confident. Might be real, might be a false positive; could
+     not verify. If stylistic, it is not explicitly called out in a relevant
+     guidance file.
+   - 50: Moderately confident. Verified real, but may be a nitpick or rare in
+     practice; not very important relative to the rest of the change.
+   - 75: Highly confident. Double checked; very likely real and will be hit
+     in practice; directly impacts functionality or is directly mentioned in
+     a guidance file.
+   - 100: Absolutely certain. Double checked and confirmed; will happen
+     frequently; evidence directly confirms it.
+   Verifiers also check that the stated failure scenario is concrete and
+   actually leads to the claimed outcome. Score toward the low end when you
+   cannot independently corroborate the finding — an uncorroborated finding is
+   a 0 or 25, not a hopeful 50. Keep a finding only when at least two verifiers
+   settled a vote and those votes average 80 or higher; fewer than two settled
+   votes is unverified coverage, not a pass. At
+   max effort, findings in the 50-79 band may be reported too — in their own
+   clearly labeled section, never as confirmed issues.
+5. **Report.** One TeamMate writes the review comment: a short verdict, then
+   numbered issues (grouped by severity when findings carry one), each with
+   the flag reason in parentheses and a file#line citation — file path alone
+   when no line is known; never invent a line number. Brief, no emojis. When a
+   channel reply tool is available, post the returned report through it;
+   otherwise return the report for the caller, or have a follow-up `send` to
+   the reporter publish it with the forge's tooling (`gh`, `glab`) once the
+   operator confirms.
+
+## False positives
 
 Instruct finders and verifiers to treat these as false positives: pre-existing
 issues; code that looks buggy but is not; pedantic nitpicks; anything a
 linter, typechecker, or CI would catch; general quality concerns not required
 by a guidance file; issues explicitly silenced in code; intentional behavior
-changes related to the broader change; and real issues on lines the change did
-not modify.
+changes related to the broader change; and real issues on lines the change
+did not modify. When reviewing a cumulative range, add: behavior an earlier
+change introduced and a later change in the same range deliberately replaced.
 
-## TeamMate budget
+## Scaling and range reviews
 
-One round costs `1 (gate) + 2 (context) + 6 (find) + 3 × findings (verify) +
-1 (report)` TeamMates. The 1000-TeamMate lifetime cap per run leaves ample
-headroom for a single round (hundreds of findings) and comfortably supports
-repeat-until-dry rounds for exhaustive coverage; still count
-`6 finders + 3 × fresh findings` per extra round before choosing round
-counts, and match fan-out to what the operator asked for.
+Match fan-out to the ask: a quick pass is one round with two votes; a normal
+review is one round with three; "thoroughly audit this" repeats rounds until
+dry. The confirmation bar stays the same throughout — effort widens coverage,
+never the evidence standard.
 
-## Script
+For a cumulative range ("everything since X"), resolve the fuzzy description
+into one exact `base..head` first — as the opening stage when it takes
+repository work — and add a cross-change lens: a later change silently
+invalidating an earlier one's assumption, dead code or docs left behind by a
+superseding change, contradictory contracts between commits.
 
-The script uses the top-level entry: the body follows `export const meta`
-directly, and `await` and early `return` work at top level. Constants and helper
-functions remain in the same private async execution scope, so normal function
-hoisting applies exactly as written.
+## Failure semantics worth remembering
+
+`agent()` settles to `null` on a failed turn, and helper results stay
+index-aligned with their inputs — note which lens or verifier failed before
+filtering nulls, and say so in the report instead of presenting partial
+coverage as clean. A directly awaited schema call rejects on a
+structured-output contract breach, which is the right outcome for
+load-bearing calls like the gate. The pattern language lives in
+[orchestration-patterns.md](orchestration-patterns.md).
+
+## Sketch
+
+The shape, compressed — adapt lenses, schemas, rounds, and report format to
+the actual task:
 
 ```js
 export const meta = {
   name: 'code-review',
-  description: 'Multi-lens code review with confidence-scored findings and one report',
-  whenToUse: 'One-shot review of a change request, git range, or working-tree diff.',
+  description: 'Multi-lens code review with confidence-scored findings',
   phases: [
-    { title: 'gate', detail: 'eligibility check with early exit' },
-    { title: 'context', detail: 'guidance discovery and change summary' },
-    { title: 'find', detail: 'six independent finder lenses' },
-    { title: 'verify', detail: 'three-vote confidence scoring per finding' },
-    { title: 'report', detail: 'synthesized review comment' },
+    { title: 'gate' }, { title: 'context' }, { title: 'find' },
+    { title: 'verify' }, { title: 'report' },
   ],
 };
 
-const FALSE_POSITIVES =
-  'Treat as false positives: pre-existing issues; code that looks buggy but is not; ' +
-  'pedantic nitpicks; anything a linter, typechecker, or CI would catch; general ' +
-  'quality concerns (coverage, docs) unless a guidance file (CLAUDE.md, AGENTS.md) ' +
-  'requires them; issues explicitly silenced in code; intentional behavior changes ' +
-  'related to the broader change; real issues on unmodified lines.';
-
-const RUBRIC =
-  '0: Not confident at all. False positive that does not stand up to light scrutiny, or a pre-existing issue.\n' +
-  '25: Somewhat confident. Might be real, might be a false positive; could not verify. If stylistic, it is not explicitly called out in a relevant guidance file (CLAUDE.md, AGENTS.md).\n' +
-  '50: Moderately confident. Verified real, but may be a nitpick or rare in practice; not very important relative to the rest of the change.\n' +
-  '75: Highly confident. Double checked; very likely real and will be hit in practice; directly impacts functionality or is directly mentioned in a guidance file.\n' +
-  '100: Absolutely certain. Double checked and confirmed; will happen frequently; evidence directly confirms it.';
-
-const FINDINGS_SCHEMA = {
-  type: 'object',
-  properties: {
-    findings: {
-      type: 'array',
-      items: {
-        type: 'object',
-        properties: {
-          file: { type: 'string' },
-          line: { type: 'integer' },
-          title: { type: 'string' },
-          detail: { type: 'string' },
-          reason: {
-            type: 'string',
-            description: 'guidance | bug | history | prior-review | comment | security',
-          },
-        },
-        required: ['file', 'title', 'detail', 'reason'],
-        additionalProperties: false,
-      },
-    },
-  },
-  required: ['findings'],
-  additionalProperties: false,
-};
-
-const SCORE_SCHEMA = {
-  type: 'object',
-  properties: {
-    score: { type: 'integer', minimum: 0, maximum: 100 },
-    reasoning: { type: 'string' },
-  },
-  required: ['score', 'reasoning'],
-  additionalProperties: false,
-};
-
-function findingKey(f) {
-  return `${f.file}:${f.line || 0}:${f.title.toLowerCase().replace(/\s+/g, ' ').trim()}`;
-}
-
-const target = args && args.target;
-if (!target) {
-  return { error: 'args.target is required: a PR/MR URL or number, a git range, or a working-tree description' };
-}
-
 phase('gate');
-const gate = await agent(
-  `Inspect this change: ${target}. Decide whether it should be code reviewed. ` +
-  `Ineligible if: closed; a draft; an automated or trivial change that is ` +
-  `obviously fine; or it already has a review comment from this Team.`,
-  {
-    label: 'gate',
-    phase: 'gate',
-    intent: 'Review eligibility gate',
-    schema: {
-      type: 'object',
-      properties: { eligible: { type: 'boolean' }, reason: { type: 'string' } },
-      required: ['eligible', 'reason'],
-      additionalProperties: false,
-    },
-  },
-);
-if (!gate || !gate.eligible) {
-  return { skipped: true, reason: gate ? gate.reason : 'gate TeamMate failed' };
-}
+const gate = await agent(`Should ${args.target} be reviewed? ...`, {
+  phase: 'gate', schema: GATE_SCHEMA,
+});
+if (!gate?.eligible) return { skipped: true, reason: gate?.reason };
 
 phase('context');
-const ctx = await parallel([
-  () => agent(
-    `For this change: ${target}. List the file paths (NOT contents) of the ` +
-    `repository's agent guidance files — CLAUDE.md and AGENTS.md — at the ` +
-    `repository root and in directories whose files the change modifies.`,
-    {
-      label: 'guidance',
-      phase: 'context',
-      intent: 'Guidance file discovery',
-      schema: {
-        type: 'object',
-        properties: { paths: { type: 'array', items: { type: 'string' } } },
-        required: ['paths'],
-        additionalProperties: false,
-      },
-    },
-  ),
-  () => agent(
-    `View this change: ${target}. Summarize it: intent, scope, key files, risk ` +
-    `areas. Concise prose only.`,
-    { label: 'summary', phase: 'context', intent: 'Change summarizer' },
-  ),
+const [guidance, summary] = await parallel([
+  () => agent(`List guidance files relevant to ${args.target}.`, { phase: 'context' }),
+  () => agent(`Summarize ${args.target}.`, { phase: 'context' }),
 ]);
-// a null discovery result is a coverage gap, distinct from a successful
-// empty list (a repo that simply has no guidance files)
-const guidanceFailed = !ctx[0];
-const guidancePaths = guidanceFailed ? [] : ctx[0].paths;
-const summary = ctx[1] || '(summary unavailable)';
-
-const lenses = [
-  { key: 'guidance', prompt: `Audit the change for compliance with these guidance files (read them): ${JSON.stringify(guidancePaths)}. Guidance files direct code writing, so not every instruction applies at review time.` },
-  { key: 'shallow-bugs', prompt: 'Read only the changed hunks and scan for obvious large bugs. Do not read extra context. Skip small issues and nitpicks.' },
-  { key: 'git-history', prompt: 'Read git blame and history of the modified code; flag bugs visible only in light of that historical context, such as reintroduced bugs or violated invariants.' },
-  { key: 'prior-reviews', prompt: 'Find previous change requests (pull/merge requests) touching these files; check review comments on them that also apply to this change.' },
-  { key: 'code-comments', prompt: 'Read code comments in the modified files; flag violations of guidance stated in those comments.' },
-  { key: 'security', prompt: 'Review the changed code for concrete, exploitable security issues introduced by this change (injection, authorization gaps, secret handling). No generic hardening advice.' },
-];
 
 phase('find');
-// without discovered guidance files the guidance lens has nothing real to
-// audit — skip it and record the gap instead of auditing an empty list
-const activeLenses = guidanceFailed
-  ? lenses.filter((lens) => lens.key !== 'guidance')
-  : lenses;
-// parallel() preserves order, so a null entry identifies the failed lens
-const lensResults = await parallel(activeLenses.map((lens) => () =>
-  agent(
-    `Code review this change through one lens: ${target}\n${lens.prompt}\n` +
-    `${FALSE_POSITIVES}\nChange summary:\n${summary}`,
-    {
-      label: `find-${lens.key}`,
-      phase: 'find',
-      intent: `Finder lens: ${lens.key}`,
-      schema: FINDINGS_SCHEMA,
-    },
-  ),
-));
-const failedLenses = [
-  ...(guidanceFailed ? ['guidance'] : []),
-  ...activeLenses.filter((lens, i) => !lensResults[i]).map((lens) => lens.key),
-];
-if (failedLenses.length === lenses.length) {
-  return { error: 'every finder lens failed; the change was not reviewed', failedLenses };
-}
-if (failedLenses.length) {
-  log(`coverage incomplete: failed lenses ${failedLenses.join(', ')}`);
-}
-const found = lensResults.filter(Boolean).flatMap((r) => r.findings);
-
-const seen = new Set();
-const unique = [];
-for (const f of found) {
-  const key = findingKey(f);
-  if (!seen.has(key)) { seen.add(key); unique.push(f); }
-}
-log(`${found.length} raw findings, ${unique.length} unique`);
-
-const checkedLenses = lenses
-  .filter((lens) => !failedLenses.includes(lens.key))
-  .map((lens) => lens.key);
-function coverageRecord(unverifiedCount) {
-  return {
-    complete: failedLenses.length === 0 && unverifiedCount === 0,
-    failedLenses,
-    unverifiedFindings: unverifiedCount,
-  };
-}
-const noIssuesReport = failedLenses.length === 0
-  ? 'No issues found. Checked for bugs, security, history, and guidance-file compliance.'
-  : `No issues found by the lenses that completed (${checkedLenses.join(', ')}). ` +
-    `Coverage is incomplete: ${failedLenses.join(', ')} failed.`;
-if (!unique.length) {
-  return { issues: [], unverified: [], coverage: coverageRecord(0), report: noIssuesReport };
-}
+const findings = dedupe((await parallel(LENSES.map((lens) => () =>
+  agent(finderPrompt(lens, args.target, guidance, summary), {
+    phase: 'find', schema: FINDINGS_SCHEMA,
+  }),
+))).filter(Boolean).flatMap((r) => r.findings));
 
 phase('verify');
-const focusQuestions = [
-  'does it reproduce on the changed lines',
-  'is it pre-existing rather than introduced by this change',
-  'does the cited guidance file or code comment actually say that',
-];
-const judged = await pipeline(
-  unique,
-  (finding) => parallel(focusQuestions.map((focus) => () =>
-    agent(
-      `Confidence-score this code review finding for the change: ${target}\n` +
-      `Finding: ${JSON.stringify(finding)}\n` +
-      `Guidance files: ${JSON.stringify(guidancePaths)}\n` +
-      `Focus question: ${focus}.\n${FALSE_POSITIVES}\n` +
-      `Score with this rubric verbatim:\n${RUBRIC}`,
-      { phase: 'verify', intent: 'Finding verifier', schema: SCORE_SCHEMA },
-    ),
-  )),
-  (votes, finding, index) => {
-    const settled = (votes || []).filter(Boolean);
-    const average = settled.length
-      ? settled.reduce((sum, vote) => sum + vote.score, 0) / settled.length
-      : 0;
-    return { ...finding, confidence: Math.round(average), votes: settled.length, index };
-  },
+const scored = await pipeline(
+  findings,
+  (f) => parallel(FOCUS_QUESTIONS.map((focus) => () =>
+    agent(rubricPrompt(f, focus), { phase: 'verify', schema: SCORE_SCHEMA }))),
+  (votes, f) => ({ ...f, votes: (votes || []).filter(Boolean) }),
 );
-// pipeline() results are index-aligned with `unique`: a null entry or a
-// finding with fewer than two settled votes is unverified, not clean
-const unverified = unique.filter((f, i) => {
-  const j = judged[i];
-  return !j || j.votes < 2;
-});
-const confirmed = judged
-  .filter(Boolean)
-  .filter((f) => f.votes >= 2 && f.confidence >= 80);
-const coverage = coverageRecord(unverified.length);
-log(`${confirmed.length} findings at >=80 confidence, ${unverified.length} unverified`);
+const confirmed = scored.filter(Boolean)
+  .filter((f) => f.votes.length >= 2 && average(f.votes) >= 80);
 
 phase('report');
-const unverifiedNote = unverified.length
-  ? ` ${unverified.length} finding(s) could not be verified (verifier failures) ` +
-    `and are returned in \`unverified\` for manual triage.`
-  : '';
-if (!confirmed.length) {
-  const reportText = unverified.length
-    ? `No issues confirmed.${unverifiedNote}`
-    : noIssuesReport;
-  return { issues: [], unverified, coverage, report: reportText };
-}
-const report = await agent(
-  `Write the final code review comment for the change: ${target}\n` +
-  `Confirmed issues (JSON): ${JSON.stringify(confirmed)}\n` +
-  `Unverified findings — verifiers failed, no confidence claim (JSON): ${JSON.stringify(unverified)}\n` +
-  `Coverage (JSON): ${JSON.stringify(coverage)}\n` +
-  `Format: a "### Code review" heading, "Found N issues:", then a numbered list; ` +
-  `each item is a brief description with the flag reason in parentheses and a ` +
-  `citation on the next line — file#line when the finding carries a line number, ` +
-  `the file path alone otherwise; never invent a line number. If there are ` +
-  `unverified findings, add a short "Unverified" section listing them without ` +
-  `confidence claims. If coverage is incomplete, end with one line naming the ` +
-  `failed lenses. Brief, no emojis. Return markdown only.`,
-  { label: 'report', phase: 'report', intent: 'Review report writer' },
-);
-return { issues: confirmed, unverified, coverage, report };
-```
-
-The verify stage shows the three-argument stage signature: stage one returns
-only the vote array, and stage two recovers the finding and its position from
-`(votes, finding, index)` instead of threading them through the return value.
-
-## Invocation
-
-```
-workflow_run({
-  script: <the script above>,
-  args: { target: 'https://github.com/owner/repo/pull/123' },
-})
+return {
+  issues: confirmed,
+  report: await agent(reportPrompt(args.target, confirmed), { phase: 'report' }),
+};
 ```
-
-`args.target` is forge-neutral — pass whatever identifies the change in the
-Team workspace:
-
-- a pull-request or merge-request URL or number
-  (`'https://gitlab.example.com/group/repo/-/merge_requests/45'`, `'#123'`);
-- a local git range (`'main...feature'`);
-- a working-tree description (`'the uncommitted diff in the workspace'`).
-
-`max_concurrency` defaults to 16; lower it only when the workspace or runtime
-provider needs gentler fan-out. After the terminal completion, read `issues`
-for the confirmed findings, `unverified` for findings whose verifiers failed,
-`coverage` for whether every finder lens ran and every finding was verified,
-and `report` for the formatted comment; use the reporter TeamMate's concrete
-name with `send` for follow-ups such as posting the comment through the
-forge's tooling or re-checking one finding interactively.

package/skills/shared/workflow/references/ultracode.md

@@ -0,0 +1,177 @@
+# Ultracode Orchestration Techniques
+
+`../SKILL.md` owns the run tools and the script API;
+[orchestration-patterns.md](orchestration-patterns.md) owns prompt discipline,
+the `pipeline`-versus-`parallel` rules, and the individual quality patterns.
+This reference owns the level above: how to shape a whole task as ultracode
+workflows — choosing an archetype, scouting before orchestrating, chaining
+runs, and composing the quality patterns into complete harnesses.
+
+## Contents
+
+- [Workflow archetypes](#workflow-archetypes) — five reusable single-run
+  shapes
+- [Scout before you orchestrate](#scout-before-you-orchestrate) — discover
+  the work-list first
+- [Chain runs, stay in the loop](#chain-runs-stay-in-the-loop) — multi-phase
+  work as a sequence of runs
+- [Worked compositions](#worked-compositions) — barrier-when-justified and
+  the exhaustive-discovery loop
+- [Loop-until-count](#loop-until-count) — accumulate to a target
+- [Novel harnesses](#novel-harnesses) — beyond the named patterns
+
+## Workflow archetypes
+
+Most tasks that deserve a workflow fit one of five single-run shapes. Name the
+shape first; the script structure follows from it.
+
+- **Understand** — parallel readers over relevant subsystems, one structured
+  map out. Fan out one `agent()` per subsystem with a shared schema, then one
+  synthesis agent merges the maps. Use when the question is "how does this
+  system work" and no single context can hold it all.
+- **Design** — a judge panel over N independent approaches. Generate attempts
+  from deliberately different angles (smallest-change-first, risk-first,
+  user-first), score them with parallel judges against explicit criteria,
+  synthesize from the winner while grafting the runners-up's best ideas. Use
+  when the solution space is wide and one-attempt-iterated would anchor early.
+- **Review** — dimensions → find → adversarially verify. The complete recipe
+  lives in [code-review.md](code-review.md); the shape generalizes to any
+  audit: independent finder lenses, confidence-gated verification, one
+  severity-ordered report.
+- **Research** — multi-modal sweep → deep-read → verify → synthesize: search
+  agents per angle, URL dedup at a justified barrier, per-source claim
+  extraction, adversarial claim verification, one cited report with honest
+  coverage caveats.
+- **Migrate** — discover sites → transform each → verify each. Scout the
+  work-list first (see below), then `pipeline` items through
+  transform-then-verify stages. Keep concurrent edits on clearly independent
+  paths, or serialize the write stage — workflow TeamMates share the Team
+  workspace.
+
+## Scout before you orchestrate
+
+The coordination graph must be known before the orchestration step — not
+before the task. When the work-list is unknown ("migrate every call site",
+"review whatever changed"), scout first and fan out second:
+
+- cheap scouting (one `git diff --stat`, one directory listing) belongs in
+  the TeamLeader's own turn before `workflow_run`, with the result passed in
+  as `args`;
+- scouting that itself needs an agent (resolving a fuzzy range, inventorying
+  a subsystem) belongs as the script's first stage, awaited bare so an
+  unresolvable work-list fails the run before any fan-out — the resolve stage
+  in [code-review.md](code-review.md)'s range mode is this technique.
+
+Never fan out against a guess: every downstream prompt should receive the
+resolved work-list, not the fuzzy description.
+
+## Chain runs, stay in the loop
+
+A workflow is one well-scoped fan-out with a deterministic graph. Larger work
+— understand, then design, then implement, then review — is a SEQUENCE of
+workflows with the TeamLeader reading each terminal result before shaping the
+next run. Resist packing multi-phase judgment into one mega-script: the
+decisions between phases (is the map good enough? which design won? is the
+implementation ready for review?) are exactly the parts that should stay with
+the TeamLeader, interactive and revisable.
+
+Three practical consequences:
+
+- `workflow_run` returns only `{ run_id }` immediately — a durable acceptance
+  receipt, not the result. Save the id, wait for the terminal completion that
+  Dreamux pushes, and build the next run's `args` from that completion's
+  `result`; feeding the receipt into the next run is the classic mistake.
+  `workflow_status({ run_id })` is for explicit recovery, not a polling loop.
+- return STRUCTURED results (not just prose) from each run so the next run's
+  `args` can be built from them mechanically;
+- after a run, follow up interactively with a recorded concrete TeamMate name
+  via `send` when one result needs a clarification — reshaping and re-running
+  the whole workflow is for when the graph itself was wrong.
+
+## Worked compositions
+
+**A barrier when it is genuinely justified** — dedup across the full result
+set before expensive downstream work:
+
+```js
+const all = await parallel(angles.map((a) => () =>
+  agent(searchPrompt(a), { phase: 'search', schema: SOURCES_SCHEMA })));
+const sources = dedupeByUrl(all.filter(Boolean).flatMap((r) => r.sources));
+// only now fan out the expensive per-source work
+const reports = await pipeline(sources, fetchStage, verifyStage);
+```
+
+The barrier earns its latency because the dedup needs every angle's output at
+once; the per-source work that follows goes back to `pipeline`.
+
+**The exhaustive-discovery loop** — finders → dedup vs SEEN → verification →
+repeat until dry, the composition behind every "audit everything" request:
+
+```js
+const seen = new Set();
+const accepted = [];
+let dry = 0;
+while (dry < 2) {
+  const found = (await parallel(finderThunks(seen))).filter(Boolean)
+    .flatMap((r) => r.findings)
+    .filter((f) => !seen.has(key(f)));
+  if (!found.length) { dry += 1; continue; }
+  dry = 0;
+  found.forEach((f) => seen.add(key(f)));
+  const judged = await pipeline(found, verifyStage, aggregateStage);
+  accepted.push(...judged.filter(Boolean).filter((f) => f.accepted));
+}
+```
+
+Dedupe against SEEN, not against `accepted` — otherwise judge-rejected
+findings reappear every round and the loop never converges. When adapting the
+sketch, remember the standing failure-plumbing rules from
+[orchestration-patterns.md](orchestration-patterns.md): note failed positions
+before filtering nulls, and bound loops when the finding population may not
+converge.
+
+## Loop-until-count
+
+For "give me N of X" requests, accumulate to the target instead of guessing
+the fan-out size:
+
+```js
+const bugs = [];
+while (bugs.length < 10) {
+  const result = await agent('Find bugs not in this list: ' +
+    JSON.stringify(bugs.map((b) => b.title)), { schema: BUGS_SCHEMA });
+  if (!result || !result.bugs.length) break; // a dry pass ends the hunt honestly
+  bugs.push(...result.bugs);
+  log(`${bugs.length}/10 found`);
+}
+if (bugs.length < 10) log(`stopped short: ${bugs.length}/10 — no more found`);
+```
+
+Always pair the target with a dry-pass exit and `log()` the shortfall — a
+loop that cannot reach N must say so, not spin against the agent cap.
+
+## Novel harnesses
+
+The named patterns are a vocabulary, not a ceiling. Compose new harness
+shapes when the task calls for it:
+
+- **tournament** — pair candidates, judge each pair, advance winners; better
+  than one big judge panel when candidates are too many to compare at once;
+- **self-repair loop** — generate → check → feed the checker's findings back
+  to a fixer → re-check, bounded by attempts, with every iteration logged;
+- **staged escalation** — a cheap pass filters the easy majority, and only
+  survivors reach the expensive treatment (the confidence-gated verify stage
+  in [code-review.md](code-review.md) is this shape);
+- **completeness critic** — after synthesis, one agent asks "what is missing —
+  an angle never searched, a claim left unverified, a source unread?" What it
+  surfaces becomes the next round's work or is reported as a known gap. Pair it
+  with loop-until-dry: the loop proves discovery is exhausted, the critic proves
+  verification and coverage are.
+
+Whatever the shape, the standing rules from
+[orchestration-patterns.md](orchestration-patterns.md) still bind: positional
+coverage accounting before `.filter(Boolean)`, no silent caps, self-contained
+prompts, and budget arithmetic against the run limits before choosing sizes.
+And because scripts run in the deterministic sandbox, `Date.now()`,
+`Math.random()`, and argless `new Date()` throw — derive variation from an
+item's index, and take any timestamp from `args` instead of reading the clock.