ultra11y 2.22.0

package/src/name.ts

@@ -0,0 +1,174 @@
+// Accessible-name computation — a pragmatic subset of the ARIA accname algorithm,
+// enough for the link/button/image/control naming rules. Not a full implementation
+// (no rendered CSS), so it stays conservative: it only claims a name it can see.
+import type { Doc, El, HNode } from "./parse/html.js";
+import { attr, hasAttr, boundAttr, hasBoundAttr, descendants, ancestors } from "./parse/html.js";
+import { isIntrinsic } from "./parse/jsx-bridge.js";
+
+const collapse = (s: string): string => s.replace(/\s+/g, " ").trim();
+
+/** JSX/SFC: the element's content/name may be injected at runtime in a way the static
+ *  parse can't see — a `<slot>` projection or a child component (which can render
+ *  anything). Rules that assert "this element is empty / unnamed" must bail on these. */
+export function mayInjectContent(el: El): boolean {
+  return descendants(el).some((d) => d.tag === "slot" || (d.tag !== "#fragment" && !isIntrinsic(d.tag)));
+}
+
+// Inline style declarations that take an element (and its subtree) out of the
+// accessibility tree entirely. Only INLINE styles are visible to a static parse — a
+// class-driven `display:none` is invisible here, which is why this stays a narrow,
+// high-confidence suppression rather than a general visibility model.
+const HIDDEN_STYLE = /(^|;)\s*(display\s*:\s*none|visibility\s*:\s*(hidden|collapse))\s*(;|$)/i;
+
+/** Is the element not rendered at all — `[hidden]`, or an inline `display:none` /
+ *  `visibility:hidden` on itself or an ancestor? Such an element is in no focus order and
+ *  exposes nothing, whatever its ARIA says. */
+export function isDisplayHidden(el: El): boolean {
+  for (const node of [el, ...ancestors(el)]) {
+    if (hasAttr(node, "hidden")) return true;
+    if (HIDDEN_STYLE.test(attr(node, "style") ?? "")) return true;
+  }
+  return false;
+}
+
+/** Is this element removed from the accessibility tree by something the source shows —
+ *  `hidden`, an inline `display:none`/`visibility:hidden`, or an `aria-hidden="true"`
+ *  ancestor? Such an element exposes no name to anyone, so a rule demanding one would be
+ *  reporting a defect nobody can experience. (`aria-hidden` on the element ITSELF is
+ *  included; a rule whose subject IS aria-hidden must use `isDisplayHidden` instead.) */
+export function isHiddenFromAT(el: El): boolean {
+  if (isDisplayHidden(el)) return true;
+  return [el, ...ancestors(el)].some((node) => attr(node, "aria-hidden") === "true");
+}
+
+/** `role="presentation"`/`role="none"` — the author has explicitly removed the element's
+ *  semantics, so it exposes no name to remove. */
+export function isPresentational(el: El): boolean {
+  return ["presentation", "none"].includes((attr(el, "role") ?? "").trim().toLowerCase());
+}
+
+/** Should a rule that demands an accessible name stay silent on this element? True when
+ *  the element is not in the accessibility tree at all, or is explicitly presentational.
+ *  Reporting either would be a defect no user can experience — the precision failure the
+ *  W3C ACT corpus catches most often. */
+export function isNameExempt(el: El): boolean {
+  return isHiddenFromAT(el) || isPresentational(el);
+}
+
+/** The name an embedded image contributes to its container's accessible name. Per the
+ *  accname computation an `<img>` is named by aria-labelledby > aria-label > alt > title,
+ *  so a link wrapping `<img aria-label="…">` or `<img title="…">` is NOT unnamed.
+ *  `doc` resolves an aria-labelledby to the text it points at; without one, the mere
+ *  presence of the attribute still counts as "named" (the reference may resolve at
+ *  runtime, and aria-ref-missing-id owns the dangling-idref case). */
+function embeddedImageName(n: El, doc?: Doc): string {
+  const labelled = (attr(n, "aria-labelledby") ?? "").trim();
+  if (labelled) return doc ? ariaLabelledbyText(n, doc) || labelled : labelled;
+  return (boundAttr(n, "aria-label") ?? attr(n, "alt") ?? attr(n, "title") ?? "").trim();
+}
+
+/** Text content of a subtree, with <img> names and <svg><title> folded in. */
+function nameFromContent(el: El, doc?: Doc): string {
+  let out = "";
+  const walk = (n: HNode): void => {
+    if (n.type === "text") {
+      out += n.data;
+      return;
+    }
+    if (n.tag === "img") {
+      const a = embeddedImageName(n, doc);
+      if (a) out += " " + a;
+      return;
+    }
+    if (n.tag === "svg") {
+      const title = descendants(n).find((d) => d.tag === "title");
+      if (title) out += " " + nameFromContent(title, doc);
+      return;
+    }
+    // aria-hidden subtrees contribute nothing
+    if (attr(n, "aria-hidden") === "true") return;
+    for (const c of n.children) walk(c);
+  };
+  for (const c of el.children) walk(c);
+  return collapse(out);
+}
+
+function ariaLabelledbyText(el: El, doc: Doc): string {
+  const ids = attr(el, "aria-labelledby");
+  if (!ids) return "";
+  const parts: string[] = [];
+  for (const id of ids.split(/\s+/).filter(Boolean)) {
+    const ref = doc.byId.get(id);
+    if (ref) parts.push(nameFromContent(ref) || (attr(ref, "aria-label") ?? "").trim());
+  }
+  return collapse(parts.join(" "));
+}
+
+const BUTTON_INPUT = new Set(["button", "submit", "reset"]);
+const NAMELESS_BY_DEFAULT = new Set(["submit", "reset"]); // UA supplies a default label
+
+/** Compute the accessible name of an element (links, buttons, images, generic). */
+export function accessibleName(el: El, doc: Doc): string {
+  // 1. aria-labelledby (a dynamically-bound :aria-labelledby can't be resolved, but it
+  //    names the element — treat as present so we don't hallucinate a missing name)
+  const labelledby = ariaLabelledbyText(el, doc);
+  if (labelledby) return labelledby;
+  if (hasBoundAttr(el, "aria-labelledby") && !attr(el, "aria-labelledby")) return " ";
+  // 2. aria-label (incl. dynamic `:aria-label`/`v-bind:` binding → value unknown but present)
+  const ariaLabel = (boundAttr(el, "aria-label") ?? "").trim();
+  if (ariaLabel) return ariaLabel;
+  // 3. element-specific
+  if (el.tag === "img" || el.tag === "area") {
+    return (boundAttr(el, "alt") ?? "").trim(); // alt="" → intentional empty name; :alt="x" → present
+  }
+  if (el.tag === "input") {
+    const type = (attr(el, "type") ?? "text").toLowerCase();
+    if (BUTTON_INPUT.has(type)) {
+      const value = (attr(el, "value") ?? "").trim();
+      if (value) return value;
+      if (NAMELESS_BY_DEFAULT.has(type)) return type === "submit" ? "Submit" : "Reset";
+      return (attr(el, "title") ?? "").trim();
+    }
+  }
+  // 4. content + title fallback
+  const content = nameFromContent(el, doc);
+  if (content) return content;
+  return (attr(el, "title") ?? "").trim();
+}
+
+const FIELD_TAGS = new Set(["input", "select", "textarea"]);
+const NON_LABELABLE_INPUT = new Set(["hidden", "submit", "reset", "button", "image"]);
+
+/** Is this a labelable form field (excludes buttons/hidden)? */
+export function isFormField(el: El): boolean {
+  if (!FIELD_TAGS.has(el.tag)) return false;
+  if (hasAttr(el, "hidden")) return false; // a [hidden] field is not an exposed UI control
+  if (el.tag === "input") {
+    const type = (attr(el, "type") ?? "text").toLowerCase();
+    return !NON_LABELABLE_INPUT.has(type);
+  }
+  return true;
+}
+
+export interface LabelInfo {
+  hasLabel: boolean;
+  via: "for" | "wrapping" | "aria-labelledby" | "aria-label" | "title" | null;
+}
+
+/** Does a form field have a programmatic label/name? (placeholder does NOT count.) */
+export function controlLabel(el: El, doc: Doc): LabelInfo {
+  // Mirror accessibleName's guard: a labelledby is a real label only when it resolves to
+  // text, OR is a DYNAMIC binding (present but value unknown). A literal aria-labelledby
+  // whose target is missing/empty names nothing — the field is effectively unlabeled.
+  if ((attr(el, "aria-labelledby") && ariaLabelledbyText(el, doc)) || (hasBoundAttr(el, "aria-labelledby") && !attr(el, "aria-labelledby")))
+    return { hasLabel: true, via: "aria-labelledby" };
+  if ((boundAttr(el, "aria-label") ?? "").trim()) return { hasLabel: true, via: "aria-label" };
+  const id = attr(el, "id");
+  if (id) {
+    const lbl = doc.elements.find((e) => e.tag === "label" && attr(e, "for") === id);
+    if (lbl) return { hasLabel: true, via: "for" };
+  }
+  if (ancestors(el).some((a) => a.tag === "label")) return { hasLabel: true, via: "wrapping" };
+  if ((attr(el, "title") ?? "").trim()) return { hasLabel: true, via: "title" };
+  return { hasLabel: false, via: null };
+}

package/src/orchestrate-templates.ts

@@ -0,0 +1,231 @@
+import { join } from "node:path";
+import type { PhaseInfo } from "./orchestrate.js";
+
+// ---------------------------------------------------------------------------
+// Templates for `ultra11y orchestrate` — the generator that turns the run's
+// CURRENT worklists into a launchable multi-agent Workflow per phase, the
+// dispatch contracts it references, and a sequential RUNBOOK fallback.
+// Everything here is emitted by string concatenation with the run's constants
+// injected as JSON literals, so the workflow runs as-is under the Workflow
+// tool: `export const meta` stays a pure literal, and no emitted line ever
+// calls Date.now()/Math.random()/new Date() (they throw in that harness).
+// ---------------------------------------------------------------------------
+
+/** Family-standard footer: subagents return fragments; the orchestrator is the sole writer. */
+const ONE_WRITER_FOOTER = `
+## Return, don't write
+
+Return ONLY the structured output specified above. Do NOT write, edit, or delete any file; do NOT run any engine command that writes (\`verify --apply\`, \`fix --write\`, \`audit --out\`, \`init\`). The orchestrator is the sole writer — it folds your verdicts into the worklist itself and runs the apply gate. Exception: if a justification is prose too large to return, write ONLY to \`<RUN>/orchestration/out/<role>-<batch>.md\` (a file namespaced to you alone) and return its path.
+`;
+
+// Structured-output schemas the emitted workflows pass to agent(..., { schema }).
+// They mirror the fail-closed rules `verify --apply` enforces, so a fragment that
+// validates here still gets re-checked (grounding, required justifications) at fold time.
+const ADJUDICATE_SCHEMA = {
+  type: "object",
+  required: ["verdicts"],
+  properties: {
+    verdicts: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["criteriaId", "verdict"],
+        properties: {
+          criteriaId: { type: "string" },
+          verdict: { enum: ["C", "NC", "NA", "manual"] },
+          justification: { type: "string", description: "REQUIRED for C and NA" },
+          reason: { type: ["string", "null"], enum: ["needs-rendered-dom", "undecidable", null], description: "REQUIRED for a still-manual verdict" },
+          findings: {
+            type: "array",
+            description: "REQUIRED (>=1, groundable) for NC",
+            items: {
+              type: "object",
+              required: ["file", "line", "message"],
+              properties: {
+                file: { type: "string" },
+                line: { type: "integer" },
+                selector: { type: "string" },
+                message: { type: "string" },
+                snippet: { type: "string" },
+                severity: { enum: ["bloquant", "majeur", "mineur"] },
+              },
+            },
+          },
+        },
+      },
+    },
+  },
+};
+
+const VERIFY_SCHEMA = {
+  type: "object",
+  required: ["verdicts"],
+  properties: {
+    verdicts: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["n", "verdict", "note"],
+        properties: {
+          n: { type: "integer" },
+          verdict: { enum: ["supported", "partial", "refuted", "unsupported"] },
+          note: { type: "string", description: "one line grounded in the source you read" },
+        },
+      },
+    },
+  },
+};
+
+interface PhaseSpec {
+  role: string;
+  title: string;
+  schema: unknown;
+  description: (items: number) => string;
+  /** The orchestrator's fold step, shown as a comment in the workflow tail + in the runbook. */
+  applyHint: (engineAbs: string, worklist: string, runAbs: string) => string;
+}
+
+const PHASE_SPECS: Record<string, PhaseSpec> = {
+  adjudicate: {
+    role: "adjudicator",
+    title: "Adjudicate",
+    schema: ADJUDICATE_SCHEMA,
+    description: (n) => `Adjudicate the ${n} residual judgment criterion(ia) of an ultra11y audit (fan-out, fail-closed fold)`,
+    applyHint: (engine, worklist, run) => `node ${engine} verify --apply ${worklist} --in ${join(run, "audit-latest.json")} --out ${run}`,
+  },
+  "verify-report": {
+    role: "refuter",
+    title: "Verify",
+    schema: VERIFY_SCHEMA,
+    description: (n) => `Adversarially verify the ${n} non-conformity claim(s) of an ultra11y report (skeptic fan-out)`,
+    applyHint: (engine, worklist) => `node ${engine} verify --apply ${worklist} --report <report.md>`,
+  },
+};
+
+export function phaseSpec(name: string): PhaseSpec {
+  const spec = PHASE_SPECS[name];
+  if (!spec) throw new Error(`no phase spec for "${name}"`);
+  return spec;
+}
+
+/** Chunk worklist ids into batches, one subagent per batch (order-preserving, deterministic). */
+export function toBatches(ids: string[], batchSize: number): string[][] {
+  const out: string[][] = [];
+  for (let i = 0; i < ids.length; i += batchSize) out.push(ids.slice(i, i + batchSize));
+  return out;
+}
+
+export function phaseWorkflowScript(ph: PhaseInfo, runAbs: string, engineAbs: string, batchSize: number): string {
+  const spec = phaseSpec(ph.name);
+  const scriptPath = join(runAbs, "orchestration", `${ph.name}.workflow.mjs`);
+  const meta = { name: `ultra11y-${ph.name}`, description: spec.description(ph.items), phases: [{ title: spec.title }] };
+  return [
+    `export const meta = ${JSON.stringify(meta)}`,
+    ``,
+    `// NOT a plain Node script: launch via the Workflow tool — Workflow({ scriptPath: ${JSON.stringify(scriptPath)} }).`,
+    `// Emitted by \`ultra11y orchestrate\` from the CURRENT worklist. The worklist is the source`,
+    `// of truth: if it changes, re-run \`orchestrate --phase ${ph.name}\` before launching.`,
+    ``,
+    `// Constants for THIS run (injected at emit time; no Date.now/Math.random in this harness).`,
+    `const RUN = ${JSON.stringify(runAbs)}`,
+    `const ENGINE = ${JSON.stringify(engineAbs)}`,
+    `const WORKLIST = ${JSON.stringify(ph.worklist)}`,
+    `const AGENTS = RUN + '/orchestration/agents'`,
+    `const BATCHES = ${JSON.stringify(toBatches(ph.ids, batchSize))}`,
+    `const SCHEMA = ${JSON.stringify(spec.schema)}`,
+    ``,
+    `function contract(name, extra) {`,
+    `  return 'Read and follow the dispatch contract at ' + AGENTS + '/' + name + '.md VERBATIM.\\n'`,
+    `    + 'Constants: RUN=' + RUN + '  ENGINE=' + ENGINE + '  WORKLIST=' + WORKLIST + '.\\n'`,
+    `    + 'Invoke the engine only by its ABSOLUTE path: node ' + ENGINE + ' <cmd> — read-only commands only.'`,
+    `    + (extra ? '\\n' + extra : '')`,
+    `}`,
+    ``,
+    `log('ultra11y ${ph.name}: ' + ${JSON.stringify(String(ph.items))} + ' item(s) across ' + BATCHES.length + ' agent(s)')`,
+    ``,
+    `phase(${JSON.stringify(spec.title)})`,
+    `const results = await pipeline(BATCHES, (batch, _item, i) =>`,
+    `  agent(contract('${spec.role}', 'ITEMS=' + batch.join(',')), { label: '${ph.name}:' + (i + 1), phase: ${JSON.stringify(spec.title)}, agentType: 'general-purpose', schema: SCHEMA }))`,
+    ``,
+    `// One-writer rule: this workflow only COLLECTS verdict fragments. The main agent folds`,
+    `// them into WORKLIST (fill each item's fields from the matching fragment), then runs:`,
+    `//   ${spec.applyHint(engineAbs, ph.worklist, runAbs)}`,
+    `return { phase: ${JSON.stringify(ph.name)}, worklist: WORKLIST, results: results.filter(Boolean) }`,
+    ``,
+  ].join("\n");
+}
+
+export function agentContracts(runAbs: string, engineAbs: string): Record<string, string> {
+  const footer = ONE_WRITER_FOOTER.replaceAll("<RUN>", runAbs);
+  return {
+    adjudicator: `# Contract: adjudicator
+
+You adjudicate residual judgment criteria of an ultra11y WCAG audit — the success criteria the deterministic engine could not decide (alt-text relevance, link purpose in context, reading order…).
+
+Worklist: \`${join(runAbs, "ADJUDICATE.todo.json")}\` (an object with \`kind: "adjudication"\` and \`items[]\`). Handle ONLY the criteria whose \`criteriaId\` is named in your prompt (\`ITEMS=<id,…>\`).
+
+For EACH of your criteria:
+
+1. Read its worklist entry. \`evidence[]\` holds source-anchored excerpts (\`file\`, \`line\`, \`selector\`, \`snippet\`) harvested from the audited code — open the cited files at the cited lines whenever the snippet alone cannot decide.
+2. Rule it (the apply gate is FAIL-CLOSED — a verdict missing its required field does not fold):
+   - \`C\` (conforming) — REQUIRES \`justification\` explaining why the evidence satisfies the criterion.
+   - \`NC\` (non-conforming) — REQUIRES \`findings\`: at least one groundable \`{ file, line, selector?, message, snippet?, severity? }\` pointing at REAL source. The fold re-grounds every finding; an invented file:line is rejected.
+   - \`NA\` (not applicable) — REQUIRES \`justification\`.
+   - \`manual\` (still undecidable) — REQUIRES \`reason\`: \`needs-rendered-dom\` (only a rendered DOM can decide, e.g. computed contrast) or \`undecidable\` (the evidence cannot settle it either way).
+3. Never guess. A criterion you cannot decide from real evidence stays \`manual\` with a reason — that is a valid, honest verdict; the scan tier or a human picks it up.
+
+Return (structured output): \`{ "verdicts": [{ "criteriaId", "verdict", "justification", "reason", "findings" }] }\` — your ITEMS only, every field grounded in what you actually read.
+${footer}`,
+    refuter: `# Contract: refuter
+
+You are an adversarial skeptic verifying the non-conformities of an ultra11y report. Your job is to try to REFUTE each claim: assume it is wrong until the source proves it.
+
+Worklist: \`${join(runAbs, "VERIFY.todo.json")}\` (a JSON array; each entry has \`n\`, \`criteriaId\`, \`file\`, \`line\`, \`selector\`, \`claim\`). Handle ONLY the entries whose \`n\` is named in your prompt (\`ITEMS=<n,…>\`).
+
+For EACH of your entries:
+
+1. Open \`file\` at \`line\` and read the cited element (\`selector\`) in its real context.
+2. Judge the claim against the source:
+   - \`supported\` — the cited code violates the criterion exactly as claimed.
+   - \`partial\` — a real issue, but the claim overstates it (wrong element, wrong scope, exaggerated count).
+   - \`unsupported\` — the source does not establish the claim.
+   - \`refuted\` — the source contradicts the claim.
+   When unsure, choose the HARSHER verdict — a false pass is worse than a false fail.
+3. \`note\` is REQUIRED — one line grounded in what you read (quote or paraphrase the decisive code).
+
+Return (structured output): \`{ "verdicts": [{ "n", "verdict", "note" }] }\` — your ITEMS only.
+${footer}`,
+  };
+}
+
+export function runbookMd(phases: PhaseInfo[], runAbs: string, engineAbs: string): string {
+  const status = phases
+    .map((p) => `| ${p.name} | \`${p.worklist}\` | ${p.ready ? `ready (${p.items} item(s))` : "not ready"} | \`${p.prerequisite}\` |`)
+    .join("\n");
+  const engine = `node ${engineAbs}`;
+  return `# ultra11y — sequential RUNBOOK (eco / no-subagent fallback)
+
+Run: \`${runAbs}\` · Engine: \`${engine}\`
+
+Generated by \`ultra11y orchestrate\` from the CURRENT run state. This sequential path is
+correctness-identical to the multi-agent workflows — same worklists, same contracts, same
+fail-closed gates; only wall-clock differs. Fan-out is an optimization, not a requirement.
+
+## Phase status
+
+| Phase | Worklist | Status | Produce it with |
+|---|---|---|---|
+${status}
+
+## The loop (play every role yourself, one item at a time)
+
+1. **Audit** (if not done): \`${engine} audit "<globs>" --graph --out ${runAbs}\` → \`${join(runAbs, "audit-latest.json")}\`.
+2. **Adjudicate the residual criteria** — \`${engine} verify --manual --in ${join(runAbs, "audit-latest.json")} --out ${runAbs}\` writes \`${join(runAbs, "ADJUDICATE.todo.json")}\`. For EVERY item, apply \`${join(runAbs, "orchestration", "agents", "adjudicator.md")}\` yourself (read the evidence, rule C/NC/NA/manual, fill the required justification/findings/reason IN the todo file). Then fold, fail-closed: \`${engine} verify --apply ${join(runAbs, "ADJUDICATE.todo.json")} --in ${join(runAbs, "audit-latest.json")} --out ${runAbs}\`.
+3. **Report**: \`${engine} report --in ${join(runAbs, "audit-latest.json")} --out ${runAbs}\`.
+4. **Verify the report's claims** — \`${engine} verify --report <the report .md> --out ${runAbs}\` writes \`${join(runAbs, "VERIFY.todo.json")}\`. For EVERY entry, apply \`${join(runAbs, "orchestration", "agents", "refuter.md")}\` yourself (open file:line, verdict supported/partial/refuted/unsupported + note IN the todo file). Then: \`${engine} verify --apply ${join(runAbs, "VERIFY.todo.json")} --report <the report .md>\`.
+5. **Gate**: \`${engine} check --report <the report .md> --semantic\` must exit 0 before presenting anything.
+6. **Fix & re-audit**: \`${engine} fix <globs> --write --iterate\`, hand-apply the judgment fixes, then loop from step 1 until the gate stays green.
+
+With subagents available, prefer the emitted workflows instead: \`orchestrate --run ${runAbs} --phase <p>\` then \`Workflow({ scriptPath: "${join(runAbs, "orchestration", "<p>.workflow.mjs")}" })\` — you stay the sole writer either way.
+`;
+}

package/src/orchestrate.ts

@@ -0,0 +1,186 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { AdjudicationFile } from "./adjudicate.js";
+import { agentContracts, phaseWorkflowScript, runbookMd } from "./orchestrate-templates.js";
+import type { VerifyItem } from "./verify.js";
+
+// ---------------------------------------------------------------------------
+// `ultra11y orchestrate` — emit the run's multi-agent orchestration from its
+// CURRENT worklists (per-phase workflow scripts + dispatch contracts + a
+// sequential RUNBOOK), so a subagent-capable harness fans the judgment work
+// out while the main agent stays the sole writer. Per-phase emission is
+// deliberate: each worklist only exists after its engine step (`verify
+// --manual`, `verify --report`), so a whole-pipeline script could only carry
+// placeholders — exactly what the check/verify gates exist to prevent.
+// ---------------------------------------------------------------------------
+
+export const PHASES = ["adjudicate", "verify-report"] as const;
+export type PhaseName = (typeof PHASES)[number];
+
+/** Small worklists don't amortize a fan-out — orchestrate says so and nudges --eco. */
+export const SMALL_WORKLIST = 3;
+/** One subagent per batch of at most this many worklist items. */
+export const BATCH_SIZE = 8;
+
+export interface PhaseInfo {
+  name: PhaseName;
+  ready: boolean;
+  /** Absolute path of the worklist this phase fans out over. */
+  worklist: string;
+  items: number;
+  /** The injected fan-out ids (criteriaId for adjudicate, `n` for verify-report). */
+  ids: string[];
+  /** The engine command that produces the worklist when it is missing. */
+  prerequisite: string;
+}
+
+export function listPhases(runDir: string, engineAbs: string): PhaseInfo[] {
+  const run = resolve(runDir);
+
+  const adjPath = join(run, "ADJUDICATE.todo.json");
+  let adjIds: string[] = [];
+  let adjReady = false;
+  if (existsSync(adjPath)) {
+    try {
+      const f = JSON.parse(readFileSync(adjPath, "utf8")) as AdjudicationFile;
+      if (f && f.kind === "adjudication" && Array.isArray(f.items)) {
+        adjReady = true;
+        adjIds = f.items.map((i) => i.criteriaId);
+      }
+    } catch {
+      /* unreadable worklist = not ready */
+    }
+  }
+
+  const verPath = join(run, "VERIFY.todo.json");
+  let verIds: string[] = [];
+  let verReady = false;
+  if (existsSync(verPath)) {
+    try {
+      const items = JSON.parse(readFileSync(verPath, "utf8")) as VerifyItem[];
+      if (Array.isArray(items)) {
+        verReady = true;
+        verIds = items.map((i) => String(i.n));
+      }
+    } catch {
+      /* unreadable worklist = not ready */
+    }
+  }
+
+  return [
+    {
+      name: "adjudicate",
+      ready: adjReady,
+      worklist: adjPath,
+      items: adjIds.length,
+      ids: adjIds,
+      prerequisite: `node ${engineAbs} verify --manual --in ${join(run, "audit-latest.json")} --out ${run}`,
+    },
+    {
+      name: "verify-report",
+      ready: verReady,
+      worklist: verPath,
+      items: verIds.length,
+      ids: verIds,
+      prerequisite: `node ${engineAbs} verify --report <report.md> --out ${run}`,
+    },
+  ];
+}
+
+export interface OrchestrateOptions {
+  /** Emit only this phase (exit 2 if its worklist does not exist yet). */
+  phase?: string;
+  /** Emit only the RUNBOOK + contracts (the explicit low-token sequential path). */
+  eco?: boolean;
+}
+
+export interface OrchestrateResult {
+  exitCode: number;
+  written: string[];
+  notices: string[];
+  errors: string[];
+  phases: PhaseInfo[];
+}
+
+export function orchestrateRun(runDir: string, engineAbs: string, opts: OrchestrateOptions = {}): OrchestrateResult {
+  const run = resolve(runDir);
+  if (!existsSync(run)) {
+    return { exitCode: 2, written: [], notices: [], errors: [`run dir not found: ${run}`], phases: [] };
+  }
+  const phases = listPhases(run, engineAbs);
+
+  let selected = phases.filter((p) => p.ready);
+  if (opts.phase !== undefined) {
+    const ph = phases.find((p) => p.name === opts.phase);
+    if (!ph) {
+      return {
+        exitCode: 2,
+        written: [],
+        notices: [],
+        errors: [`unknown phase "${opts.phase}" — expected one of: ${PHASES.join(", ")}.`],
+        phases,
+      };
+    }
+    if (!ph.ready) {
+      return {
+        exitCode: 2,
+        written: [],
+        notices: [],
+        errors: [`phase "${ph.name}" is not ready — its worklist ${ph.worklist} does not exist yet. Produce it first: ${ph.prerequisite}`],
+        phases,
+      };
+    }
+    selected = [ph];
+  }
+
+  const orchDir = join(run, "orchestration");
+  const agentsDir = join(orchDir, "agents");
+  mkdirSync(join(orchDir, "out"), { recursive: true });
+  mkdirSync(agentsDir, { recursive: true });
+
+  const written: string[] = [];
+  const notices: string[] = [];
+
+  // Contracts: every role, every call (idempotent overwrite) — they double as the
+  // RUNBOOK's self-pass checklists, so eco mode needs them too.
+  for (const [name, content] of Object.entries(agentContracts(run, engineAbs))) {
+    const p = join(agentsDir, `${name}.md`);
+    writeFileSync(p, content);
+    written.push(p);
+  }
+
+  // Reconcile before emitting: a workflow script left behind by an earlier
+  // emission whose worklist has since emptied or disappeared is a launchable
+  // fan-out over ids that no longer exist — "deterministic and idempotent"
+  // means the orchestration dir always mirrors the CURRENT run state.
+  const emitted = new Set(opts.eco ? [] : selected.filter((p) => p.items > 0).map((p) => p.name));
+  for (const ph of phases) {
+    if (emitted.has(ph.name)) continue;
+    const stale = join(orchDir, `${ph.name}.workflow.mjs`);
+    if (existsSync(stale)) {
+      rmSync(stale, { force: true });
+      notices.push(`phase "${ph.name}": stale workflow removed — its worklist ${ph.ready ? "is now empty" : "no longer exists"}.`);
+    }
+  }
+
+  if (!opts.eco) {
+    for (const ph of selected) {
+      if (ph.items === 0) {
+        notices.push(`phase "${ph.name}": worklist is empty — nothing to orchestrate.`);
+        continue;
+      }
+      if (ph.items <= SMALL_WORKLIST) {
+        notices.push(`phase "${ph.name}": only ${ph.items} item(s) — the sequential --eco path is equivalent and cheaper.`);
+      }
+      const p = join(orchDir, `${ph.name}.workflow.mjs`);
+      writeFileSync(p, phaseWorkflowScript(ph, run, engineAbs, BATCH_SIZE));
+      written.push(p);
+    }
+  }
+
+  const rb = join(orchDir, "RUNBOOK.md");
+  writeFileSync(rb, runbookMd(phases, run, engineAbs));
+  written.push(rb);
+
+  return { exitCode: 0, written, notices, errors: [], phases };
+}