@nicknisi/pi-workflows 0.2.1 → 0.3.0

package/engine.ts

@@ -2,7 +2,7 @@
  * The workflow script engine — pi-free and testable.
  *
  * A workflow script is a JavaScript statement body with injected globals
- * (args, agent, parallel, pipeline, phase, log, budget, cwd) and a leading
+ * (args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask) and a leading
  * `export const meta = { name, description }` declaration. It returns a value
  * by evaluating a trailing expression or a top-level `return` (the body is
  * wrapped in an async function so a bare `return` compiles).
@@ -71,6 +71,58 @@ export interface EngineBudget {
   remaining: number;
 }
 
+// ── Run gate (pause/resume) ────────────────────────────────────────────────
+// A per-run hold. agent() awaits gate.wait() before every spawn, so pausing
+// lets the in-flight step finish and holds the run before the next one — the
+// script contract's equivalent of osolmaz/pi-workflows' `/workflow pause`.
+// abort() rejects current AND future waiters so a stopped run never hangs
+// parked at a gate.
+
+export interface RunGate {
+  readonly paused: boolean;
+  pause(): void;
+  resume(): void;
+  /** Reject all current and future waiters (run stopped/timed out). */
+  abort(): void;
+  wait(): Promise<void>;
+}
+
+export function createRunGate(): RunGate {
+  let paused = false;
+  let aborted = false;
+  let waiters: Array<{ resolve: () => void; reject: (e: Error) => void }> = [];
+  return {
+    get paused() {
+      return paused;
+    },
+    pause() {
+      paused = true;
+    },
+    resume() {
+      paused = false;
+      const w = waiters;
+      waiters = [];
+      for (const { resolve } of w) resolve();
+    },
+    abort() {
+      aborted = true;
+      const w = waiters;
+      waiters = [];
+      for (const { reject } of w) reject(new Error('run aborted while paused'));
+    },
+    wait() {
+      if (aborted) return Promise.reject(new Error('run aborted while paused'));
+      if (!paused) return Promise.resolve();
+      return new Promise<void>((resolve, reject) => {
+        waiters.push({ resolve, reject });
+      });
+    },
+  };
+}
+
+/** Script-global human question: select when options given, confirm otherwise. undefined = dismissed. */
+export type EngineAskFn = (question: string, options?: string[]) => Promise<string | boolean | undefined>;
+
 export interface ScriptMeta {
   name?: string;
   description?: string;
@@ -84,6 +136,19 @@ export interface RunScriptOptions {
   cwd: string;
   budgetTotal?: number;
   onLog?: (line: string) => void;
+  /** Pause gate; agent() awaits it before every spawn. */
+  gate?: RunGate;
+  /**
+   * Host-side human gate for the `checkpoint(label?)` global. When omitted,
+   * checkpoint is a no-op that logs a skip note (pi-free hosts, tests).
+   */
+  checkpoint?: (label?: string) => Promise<void>;
+  /**
+   * Host-side human question for the `ask(question, options?)` global. When
+   * omitted, ask throws — a script that needs an answer should fail loudly
+   * rather than invent one.
+   */
+  ask?: EngineAskFn;
 }
 
 export interface RunScriptResult {
@@ -168,6 +233,8 @@ export async function runScript(opts: RunScriptOptions): Promise<RunScriptResult
     if (typeof agentOpts.agentType === 'string') {
       log(`(agentType '${agentOpts.agentType}' accepted but ignored — no agent-type registry)`);
     }
+    // Pause gate: hold here (between steps) until resumed. Rejects on abort.
+    await opts.gate?.wait();
     const spawnOpts: EngineSpawnOptions = {
       prompt,
       ...(typeof agentOpts.label === 'string' ? { agent: agentOpts.label } : {}),
@@ -191,6 +258,25 @@ export async function runScript(opts: RunScriptOptions): Promise<RunScriptResult
     return res.data ?? res.text ?? null;
   };
 
+  // checkpoint(label?): script-internal human gate. The host decides what
+  // "continue?" means (a confirm dialog in pi); default is a logged no-op.
+  const checkpoint = async (label?: string): Promise<void> => {
+    if (!opts.checkpoint) {
+      log(`(checkpoint${label ? ` '${label}'` : ''} skipped — no host gate)`);
+      return;
+    }
+    log(`⏸ checkpoint${label ? `: ${label}` : ''}`);
+    await opts.checkpoint(label);
+  };
+
+  // ask(question, options?) — human answer inside a run. select with options,
+  // confirm without. Default throws: never invent an answer.
+  const ask: EngineAskFn = async (question, options) => {
+    if (!opts.ask) throw new Error('ask() unavailable in this host');
+    log(`? ${question}`);
+    return opts.ask(question, options);
+  };
+
   const parallel = <T>(thunks: Array<() => Promise<T>>): Promise<T[]> => Promise.all(thunks.map((t) => t()));
 
   // pipeline(items, ...stages): each stage maps over the previous stage's
@@ -206,7 +292,7 @@ export async function runScript(opts: RunScriptOptions): Promise<RunScriptResult
   // Compile + run. compileScript is extracted so callers (tests, future
   // tooling) can compile + read `meta` without a real spawn.
   const compiled = compileScript(script);
-  const value = await compiled.fn(args, agent, parallel, pipeline, phase, log, budget, cwd);
+  const value = await compiled.fn(args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask);
   return { value, meta: compiled.meta, logs, usage, durationMs: Date.now() - startedAt };
 }
 
@@ -222,6 +308,8 @@ export type CompiledFn = (
   log: unknown,
   budget: unknown,
   cwd: string,
+  checkpoint: unknown,
+  ask: unknown,
 ) => Promise<unknown>;
 
 export interface CompiledScript {
@@ -245,7 +333,7 @@ export interface CompiledScript {
 export function compileScript(script: string): CompiledScript {
   const metaHolder: { value: ScriptMeta | undefined } = { value: undefined };
   const stripped = script.replace(STRIP_META, 'const meta = metaHolder.value =');
-  const wrapped = `(async function(args, agent, parallel, pipeline, phase, log, budget, cwd, metaHolder){\n${stripped}\n})`;
+  const wrapped = `(async function(args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask, metaHolder){\n${stripped}\n})`;
   const raw = new vm.Script(wrapped, { filename: 'workflow.js' }).runInThisContext() as (
     args: unknown,
     agent: unknown,
@@ -255,12 +343,14 @@ export function compileScript(script: string): CompiledScript {
     log: unknown,
     budget: unknown,
     cwd: string,
+    checkpoint: unknown,
+    ask: unknown,
     metaHolder: { value: ScriptMeta | undefined },
   ) => Promise<unknown>;
-  // Bind metaHolder so callers invoke an 8-arg fn; the holder rides the call
+  // Bind metaHolder so callers invoke a 10-arg fn; the holder rides the call
   // (runInThisContext cannot see a closure variable, so it must be a parameter).
-  const fn: CompiledFn = (args, agent, parallel, pipeline, phase, log, budget, cwd) =>
-    raw(args, agent, parallel, pipeline, phase, log, budget, cwd, metaHolder);
+  const fn: CompiledFn = (args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask) =>
+    raw(args, agent, parallel, pipeline, phase, log, budget, cwd, checkpoint, ask, metaHolder);
 
   // Stub dry-run to read `meta`. Well-formed scripts declare `meta` first, so
   // it is assigned synchronously before the first `await`; we await the whole
@@ -274,6 +364,8 @@ export function compileScript(script: string): CompiledScript {
     return values as U[];
   };
   const stubBudget = { total: Infinity, spent: 0, remaining: Infinity };
+  const stubCheckpoint = async (): Promise<void> => {};
+  const stubAsk = async (): Promise<undefined> => undefined;
   void fn(
     undefined,
     stubAgent,
@@ -283,6 +375,8 @@ export function compileScript(script: string): CompiledScript {
     () => {},
     stubBudget,
     '/tmp',
+    stubCheckpoint,
+    stubAsk,
   ).catch(() => {});
 
   // `meta` is a getter so a caller that re-runs `fn` with real globals sees

package/examples/autoimplement.js

@@ -0,0 +1,80 @@
+// autoimplement.js — implement a plan end-to-end with a bounded review/fix loop.
+//
+// Ported from osolmaz/pi-workflows' autoimplement, cut to the loop that
+// matters: gate the plan with a human (their approval modes become one ask),
+// build, verify, review, fix, repeat until a reviewer finds no P0/P1 or the
+// round cap trips. Theirs adds PR/CI watching and pi-reviewer integration —
+// add that back as a stage when you need it (YAGNI until then).
+//
+// THE REASONING SHAPE (the part worth stealing):
+//   1. NEVER devise a new plan — the plan is input. If evidence invalidates
+//      it mid-run, stop and say so (re-plan is autoplan's job).
+//   2. ask() gates the plan BEFORE tokens burn: approve / edit / abort.
+//   3. Review loop is BOUNDED (MAX_ROUNDS) — an unbounded fix loop is a
+//      wallet drain with extra steps. P0/P1 block; P2 noted but non-blocking.
+//   4. Verification runs after EVERY fix round, not just the first build.
+//
+// HOW TO ADAPT: pass { task, plan, verify } via args —
+//   /wf run autoimplement {"task":"add timeout fallback","plan":"...","verify":"pnpm typecheck"}
+
+export const meta = {
+  name: 'autoimplement',
+  description: 'Human-gated plan → build → verify → review/fix loop, bounded rounds, P0/P1 block',
+};
+
+const TASK = (args && args.task) || 'Implement the plan.';
+const PLAN = (args && args.plan) || '(no plan supplied — stop and ask for one)';
+const VERIFY = (args && args.verify) || 'npx tsgo --noEmit';
+const MAX_ROUNDS = 3;
+const BUILDER_TOOLS = ['read', 'edit', 'write', 'bash', 'grep', 'find'];
+
+if (!args || !args.plan) throw new Error('autoimplement requires args.plan — never devise a new plan here.');
+
+const decision = await ask(`Implement this plan?\n\nTask: ${TASK}\n\nPlan:\n${PLAN.slice(0, 2000)}`, [
+  'implement',
+  'abort',
+]);
+if (decision !== 'implement') throw new Error(`aborted at plan gate (${decision ?? 'dismissed'})`);
+
+phase('build');
+let build = await agent(
+  `Implement this plan end-to-end, minimal and correct. Run \`${VERIFY}\` and make it pass before ` +
+    `finishing. Report: files changed, one line per change, verify output tail.\n\nTASK: ${TASK}\n\nPLAN:\n${PLAN}`,
+  { label: 'builder', tools: BUILDER_TOOLS },
+);
+
+for (let round = 1; round <= MAX_ROUNDS; round++) {
+  phase(`review round ${round}`);
+  const review = await agent(
+    `Review the implementation against the plan. Classify every finding P0 (wrong/unsafe), P1 (should ` +
+      `fix before merge), P2 (proportionate improvements). Verify claims against the actual files — no ` +
+      `evidence, no finding. Ignore legacy-compatibility asks unless the plan requires them.\n\n` +
+      `PLAN:\n${PLAN}\n\nBUILDER REPORT:\n${build}`,
+    {
+      label: 'reviewer',
+      schema: {
+        type: 'object',
+        properties: {
+          p0: { type: 'array', items: { type: 'string' } },
+          p1: { type: 'array', items: { type: 'string' } },
+          p2: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['p0', 'p1', 'p2'],
+      },
+    },
+  );
+
+  if (review.p0.length === 0 && review.p1.length === 0) {
+    return { status: 'clean', rounds: round, p2: review.p2, build };
+  }
+  if (round === MAX_ROUNDS) {
+    return { status: 'round-cap', blocking: [...review.p0, ...review.p1], build };
+  }
+
+  phase(`fix round ${round}`);
+  build = await agent(
+    `Fix these review findings, then re-run \`${VERIFY}\` and make it pass. Report files changed.\n\n` +
+      `P0/P1 FINDINGS:\n${[...review.p0, ...review.p1].map((f) => `- ${f}`).join('\n')}`,
+    { label: 'fixer', tools: BUILDER_TOOLS },
+  );
+}

package/examples/autoplan.js

@@ -0,0 +1,123 @@
+// autoplan.js — pick the best practical solution and write its implementation plan.
+//
+// Ported from osolmaz/pi-workflows' autoplan. Theirs is a durable graph with
+// human decision gates; this is the same reasoning shape as a flat script:
+// candidates fan out in parallel, a judge picks one WITHOUT asking the user
+// to choose, and a checkpoint gates the expensive plan write.
+//
+// THE REASONING SHAPE (the part worth stealing):
+//   1. 2-4 distinct practical candidates IN PARALLEL, each answering: gist,
+//      full solution, rationale, parts, trade-offs, and "is this the
+//      long-term-elegant production-ready answer?"
+//   2. The Holy Grail described SEPARATELY — the unconstrained ideal — with
+//      every dependency outside our authority named.
+//   3. An advisor ranks the options with a recommendation, curbing Grail
+//      ideas that need upstream changes we don't control.
+//   4. THE DECISION GATE IS THE HUMAN: ask() lists the options with the
+//      recommendation on top. The whole point of the workflow is that you
+//      only decide AFTER it finishes mining — including rejecting everything.
+//   5. Plan writer elaborates the CHOSEN option: per step, what changes,
+//      where, and how to verify.
+//
+// HOW TO ADAPT: pass { problem, scope, constraints } via args —
+//   /wf run autoplan {"problem":"choose a timeout fallback","scope":"packages/workflows only","constraints":["keep cancellation terminal"]}
+// Or just say "autoplan this" — the bundled skill derives the args from the
+// conversation.
+
+export const meta = {
+  name: 'autoplan',
+  description: 'Parallel candidates, judge picks without punting to the user, checkpoint-gated plan write',
+};
+
+const PROBLEM = (args && args.problem) || 'State the decision or planning problem and its observable end state.';
+const SCOPE = (args && args.scope) || 'This repository. Name important exclusions.';
+const CONSTRAINTS = (args && args.constraints) || [];
+
+const CONTEXT = `PROBLEM: ${PROBLEM}\nSCOPE: ${SCOPE}\nCONSTRAINTS: ${JSON.stringify(CONSTRAINTS)}`;
+
+phase('candidates');
+const CANDIDATE_IDS = ['A', 'B', 'C'];
+const candidates = await parallel(
+  CANDIDATE_IDS.map((id) => async () => {
+    return agent(
+      `${CONTEXT}\n\nYou are candidate advocate ${id}. Propose a DISTINCT practical solution ` +
+        `(different from what other advocates would pick). Give: short title, plain gist, full ` +
+        `solution, rationale, parts, trade-offs, and a yes/no on "is this the long-term-elegant ` +
+        `production-ready answer". Ground every claim in the actual codebase.`,
+      { label: `candidate-${id}` },
+    );
+  }),
+);
+
+phase('holy grail');
+const grail = await agent(
+  `${CONTEXT}\n\nDescribe the Holy Grail: the ideal solution with no practical constraints. ` +
+    `Name every dependency outside our authority (upstream changes, other teams, new services).`,
+  { label: 'grail' },
+);
+
+phase('advisor');
+// The advisor RECOMMENDS but does not decide — the human is the gate. It
+// curbs Holy Grail ideas that need changes outside our authority.
+const advice = await agent(
+  `${CONTEXT}\n\nCANDIDATES:\n${candidates.map((c, i) => `--- Candidate ${CANDIDATE_IDS[i]} ---\n${c}`).join('\n\n')}\n\n` +
+    `HOLY GRAIL:\n${grail}\n\nRank the options for practicality and simplicity, preferring interfaces we ` +
+    `control; reject any Grail that needs an upstream change as UNIMPLEMENTABLE NOW (note it, don't pick it). ` +
+    `Return a short title + one-line gist per option (candidates AND the grail if it qualifies), the ` +
+    `recommended id, why, and one rejection reason per loser.`,
+  {
+    label: 'advisor',
+    schema: {
+      type: 'object',
+      properties: {
+        options: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: { id: { type: 'string' }, title: { type: 'string' }, gist: { type: 'string' } },
+            required: ['id', 'title', 'gist'],
+          },
+        },
+        recommended: { type: 'string' },
+        why: { type: 'string' },
+        rejections: {
+          type: 'array',
+          items: { type: 'object', properties: { id: { type: 'string' }, reason: { type: 'string' } } },
+        },
+      },
+      required: ['options', 'recommended', 'why', 'rejections'],
+    },
+  },
+);
+
+phase('decision gate');
+// The human decides — after the mining, not during. Recommendation first.
+const ordered = [...advice.options].sort((a, b) =>
+  a.id === advice.recommended ? -1 : b.id === advice.recommended ? 1 : 0,
+);
+const REJECT = 'none — reject all / re-mine';
+const choice = await ask(`Recommended: ${advice.recommended} — ${advice.why}\n\nPick a direction:`, [
+  ...ordered.map((o) => `${o.id}: ${o.title} — ${o.gist}`),
+  REJECT,
+]);
+if (!choice || choice === REJECT) {
+  return {
+    decided: false,
+    options: advice.options,
+    recommended: advice.recommended,
+    why: advice.why,
+    rejections: advice.rejections,
+  };
+}
+const picked = ordered.find((o) => choice.startsWith(`${o.id}:`)) ?? ordered[0];
+log(`human picked: ${picked.id} ${picked.title}`);
+
+phase('plan');
+const plan = await agent(
+  `${CONTEXT}\n\nWrite the implementation plan for the SELECTED option (${picked.id}): ${picked.title} — ${picked.gist}\n\n` +
+    `For each step state WHAT changes, WHERE (exact files), and HOW TO VERIFY it. ` +
+    `End with a "rejected alternatives" section: ${JSON.stringify(advice.rejections)}`,
+  { label: 'planner' },
+);
+
+return { decided: true, choice: picked, why: advice.why, rejections: advice.rejections, plan };

package/examples/bake-off.js

@@ -0,0 +1,107 @@
+// bake-off.js — Bake-Off mode: race N models on one task, an advisory judge picks.
+//
+// WHEN BAKE-OFF BEATS A SINGLE BUILDER: empirically, a single GLM-5.2-class
+// builder produces decent-but-flawed code — right shape, subtle bugs. Racing
+// two models on the SAME task in ISOLATED worktrees and letting an advisory
+// judge pick the winner is a quality lever: the judge sees two independent
+// attempts AND their patches, and the better one wins. It costs ~2x the
+// tokens of a single build for a measurably better hit rate on hard tasks.
+// Don't run it for trivial edits — the judge overhead isn't worth it there.
+//
+// HOW IT WORKS:
+//   1. Each contender runs as a builder agent with `worktree: true` — it
+//      writes into its own detached worktree, so contenders never stomp each
+//      other. On settle the subagent runtime captures the full change set
+//      (including untracked files) to a `.patch`.
+//   2. agent() returns `{ value, patchPath, runId }` for a worktree run that
+//      changed files — the wrapper is opt-in: non-worktree agent() calls keep
+//      returning the bare value, so existing scripts are unaffected.
+//   3. A single judge agent receives all contender summaries + their patch
+//      paths and returns `{ winner, why, confidence }`.
+//   4. The workflow returns the winner's patchPath — apply it via the
+//      subagents fleet apply flow (the `/patches` staging area: pre-flights
+//      each patch without applying, then `Enter` to `git apply --3way`).
+//
+// Adapt: set CONTENDERS to the models you want to race, pass `task` in args
+// (or edit DEFAULT_TASK). The judge can be a stronger/different model than the
+// builders — set JUDGE_MODEL.
+
+export const meta = {
+  name: 'bake_off',
+  description: 'Race N models on one task in isolated worktrees; an advisory judge picks the winner',
+};
+
+// Models to race, in 'provider/id' form. Add or remove contenders freely.
+const CONTENDERS = ['z-ai/glm-5.2', 'anthropic/claude-sonnet-4-5'];
+const JUDGE_MODEL = 'anthropic/claude-opus-4-1';
+
+const DEFAULT_TASK = 'Implement X in packages/foo/bar.ts such that Y holds. Keep the change minimal and correct.';
+const TASK = (args && args.task) || DEFAULT_TASK;
+
+const BUILDER_TOOLS = ['read', 'edit', 'write', 'bash', 'grep', 'find'];
+const BUILDER_PROMPT =
+  'You are a builder. Implement the following task in this repo. Make the change minimal ' +
+  'and correct; run the repo typecheck before finishing. Report a one-paragraph summary of ' +
+  'what you changed and why.\n\nTASK:\n' +
+  TASK;
+
+// A throw inside parallel() collapses the wave — wrap each contender so a
+// failure reports which model died instead of nuking the whole race.
+const safeRun = (model, i) => async () => {
+  try {
+    const r = await agent(BUILDER_PROMPT, {
+      label: 'contender-' + (i + 1),
+      model,
+      tools: BUILDER_TOOLS,
+      worktree: true,
+    });
+    if (r && typeof r === 'object' && 'patchPath' in r) {
+      return { model, ok: true, summary: r.value, patchPath: r.patchPath, runId: r.runId };
+    }
+    return { model, ok: true, summary: r, patchPath: null, runId: null };
+  } catch (e) {
+    return { model, ok: false, summary: 'contender crashed: ' + (e && e.message), patchPath: null, runId: null };
+  }
+};
+
+phase('race');
+const entries = await parallel(CONTENDERS.map(safeRun));
+
+phase('judge');
+const verdict = await agent(
+  'You are an advisory judge for a model bake-off. Two builders each attempted the SAME ' +
+    'task below, independently, in isolated worktrees. You are given each contender model, ' +
+    'its self-reported summary, and the path to its patch. Read each patch (use bash: ' +
+    '`cat <patchPath>`) and compare them on correctness, minimalism, and style. Pick the ' +
+    'winner. Do not just trust the summaries — read the actual diffs (the read tool takes a path; no bash needed).\n\n' +
+    'TASK:\n' +
+    TASK +
+    '\n\nCONTENDERS JSON:\n' +
+    JSON.stringify(entries, null, 2) +
+    '\n\nReturn JSON { winner: <model id>, why: <one paragraph>, confidence: "low"|"medium"|"high" }.',
+  {
+    label: 'judge',
+    model: JUDGE_MODEL,
+    tools: ['read'], // patches are files — read-only judging, no bash
+    schema: {
+      type: 'object',
+      properties: {
+        winner: { type: 'string' },
+        why: { type: 'string' },
+        confidence: { type: 'string', enum: ['low', 'medium', 'high'] },
+      },
+      required: ['winner', 'why', 'confidence'],
+    },
+  },
+);
+
+const winner = entries.find((e) => e.model === verdict.winner) ?? entries[0];
+
+return {
+  winner: verdict.winner,
+  why: verdict.why,
+  confidence: verdict.confidence,
+  // Apply this via the subagents /patches staging area (git apply --3way).
+  patchPath: (winner && winner.patchPath) || null,
+  contenders: entries.map((e) => ({ model: e.model, ok: e.ok, patchPath: e.patchPath })),
+};

package/examples/gates.js

@@ -0,0 +1,106 @@
+// gates.js — judge/verify PROMPT builders.
+//
+// WHAT IT'S FOR: the prompt engineering that turns a flaky judge into a
+// reliable gate. Each builder is a function returning a prompt STRING; copy
+// the one that matches your gate into your own workflow and hand it to an
+// agent() with a JSON schema. These are PATTERNS, not an API — read them,
+// adapt the framing to your task, do not import this file.
+//
+// The valuable knowledge here is WHAT failure mode each framing prevents:
+//   adversarialReview      → confirmation bias / sycophancy
+//   deepResearchCoverage   → silent source omission / single-source skew
+//   codeReviewVerdict      → verdict collapse + severity ordering
+//
+// Prompt patterns distilled from @quintinshaw/pi-dynamic-workflows (MIT).
+// Substantial portions of the prompt text below are adapted from that
+// package, whose LICENSE requires this notice:
+//
+//   Copyright (c) 2026 QuintinShaw
+//   Copyright (c) Michael Livs (original pi-dynamic-workflows)
+//
+//   Permission is hereby granted, free of charge, to any person obtaining a
+//   copy of this software and associated documentation files (the
+//   "Software"), to deal in the Software without restriction, including
+//   without limitation the rights to use, copy, modify, merge, publish,
+//   distribute, sublicense, and/or sell copies of the Software, and to
+//   permit persons to whom the Software is furnished to do so, subject to
+//   the following conditions: the above copyright notice and this
+//   permission notice shall be included in all copies or substantial
+//   portions of the Software.
+
+export const meta = {
+  name: 'gates',
+  description: 'Judge/verify prompt builders: adversarial refutation, research coverage, code-review verdict',
+};
+
+// ── Adversarial refutation ─────────────────────────────────────────────────
+// Prevents: confirmation bias. A reviewer asked "is this finding real?" tends
+// to agree (sycophancy), and a wrong finding survives. Reframing the job as
+// "try to REFUTE this; default to real=false when uncertain" flips the prior:
+// a finding survives only when enough independent skeptics FAIL to refute it.
+// `reviewers` skeptics vote in parallel; the finding survives when the
+// real-vote share meets `threshold`. The "state the strongest reason it could
+// be WRONG first" line forces the skeptic to actually attack, not rubber-stamp.
+const adversarialReview = (task, finding, reviewers, threshold) =>
+  'You are a skeptical reviewer. Try to REFUTE this finding for the task below. ' +
+  'Default to real=false when uncertain; investigate with the available tools if needed. ' +
+  'State the strongest reason the finding could be WRONG before you decide.\n\n' +
+  'TASK: ' +
+  task +
+  '\nFINDING: ' +
+  finding +
+  '\n\nReturn JSON { real: boolean, reason: string }. This finding is counted real only ' +
+  'if it survives ' +
+  reviewers +
+  ' independent refuters at threshold ' +
+  threshold +
+  '.';
+
+// ── Deep-research coverage check ──────────────────────────────────────────
+// Prevents: silent source omission. A research fan-out gathers N sources and
+// lists claims; without a coverage check, a claim from a single weak source
+// (or one a model half-remembered and attributed to a plausible URL) survives
+// alongside well-sourced ones. This gate groups claims asserting the SAME
+// fact across DISTINCT source URLs and keeps a claim only when it has
+// `minSupport` distinct sources OR one clearly authoritative source. Conflicts
+// and single-source claims are discarded — the report says so explicitly.
+const deepResearchCoverage = (sources, minSupport) =>
+  'Cross-check these research sources. Group claims that assert the same fact across ' +
+  'different source URLs. Keep a claim only if it is supported by at least ' +
+  minSupport +
+  ' distinct source URLs OR by one clearly authoritative source. Discard claims found in ' +
+  'a single weak source or that conflict with others. Do not invent sources.\n\n' +
+  'SOURCES JSON:\n' +
+  JSON.stringify(sources) +
+  '\n\nReturn JSON { supported: [{ claim, sources: [url] }], discarded: [claim] }.';
+
+// ── Code-review verdict + severity ─────────────────────────────────────────
+// Prevents: verdict collapse. A boolean "is this issue real?" collapses
+// CONFIRMED (will break) and PLAUSIBLE (worth a look) into one bucket, losing
+// the hedge the report needs. A 3-way verdict — CONFIRMED / PLAUSIBLE /
+// REFUTED — with a per-finding failure scenario keeps the signal; only REFUTED
+// is filtered out. Severity framing: name the concrete failure scenario, not a
+// vague "this might be bad" — a finding with no traceable failure is PLAUSIBLE
+// at best, never CONFIRMED.
+const codeReviewVerdict = (finding, diffBlock) =>
+  'You are a verifier. Determine whether this code review finding is CONFIRMED, PLAUSIBLE, ' +
+  'or REFUTED.\n' +
+  'CONFIRMED = you can trace the exact failure in the diff.\n' +
+  'PLAUSIBLE = the concern is valid but not certain.\n' +
+  'REFUTED = the finding is wrong or already handled.\n\n' +
+  'FINDING:\n' +
+  finding +
+  diffBlock +
+  '\n\nReturn JSON { verdict: "CONFIRMED"|"PLAUSIBLE"|"REFUTED", reason: string }. ' +
+  'If you cannot trace a concrete failure scenario, return at most PLAUSIBLE.';
+
+// Demonstrate the shapes — copy whichever builder fits your gate.
+phase('gates');
+log('adversarialReview  →', adversarialReview('ship the release', 'auth refresh leaks', 3, 0.66).slice(0, 60) + '…');
+log('deepResearchCoverage →', deepResearchCoverage([{ url: 'https://example', claims: ['x'] }], 2).slice(0, 60) + '…');
+log('codeReviewVerdict  →', codeReviewVerdict('file.ts:42 null deref', '\n<diff>…</diff>').slice(0, 60) + '…');
+
+return {
+  builders: ['adversarialReview', 'deepResearchCoverage', 'codeReviewVerdict'],
+  note: 'Copy the builder that matches your gate; call it from agent() with a JSON schema.',
+};

package/examples/lanes.js

@@ -0,0 +1,70 @@
+// lanes.js — N parallel agents editing FILE-DISJOINT lanes of one repo.
+//
+// WHAT IT'S FOR: when a task splits into independent, file-disjoint edits
+// across a single repo, lanes runs them concurrently under hard rules that
+// make the parallelism safe: each lane owns a fixed file set, no lane touches
+// git or installs, and the parent integrates centrally. This is the pattern
+// behind "hardening lanes" — a blocker list split by subsystem, each lane
+// owned by one agent.
+//
+// HOW TO ADAPT:
+//   1. Set VERIFY to the repo's typecheck/lint command (repo-wide is fine —
+//      errors in files a lane does NOT own are other lanes mid-edit; each
+//      lane ignores them; only its own files must be clean).
+//   2. Fill LANES with one entry per parallel edit: a `name`, the exact
+//      `files` that lane may touch (no others), and a one-paragraph `brief`.
+//   3. Run it: /wf run lanes
+//   4. You (the parent) integrate the lanes' edits centrally — review and
+//      stage them here.
+//
+// The hard-rules preamble is the pattern's soul — keep it. The fan-out is a
+// single parallel() over the lanes. Cap lanes at the subagent runtime's child
+// budget (4 by default); split into a second wave if you need more.
+
+export const meta = {
+  name: 'lanes',
+  description: 'Parallel file-disjoint editing lanes under a hard-rules preamble',
+};
+
+// Repo-wide verification command. Replace with your project's typecheck
+// (`npx tsgo --noEmit`, `tsc --noEmit`, `cargo check`, …).
+const VERIFY = 'npx tsgo --noEmit';
+
+const COMMON = `You are one of N parallel agents editing the same repo (cwd is the repo root).
+HARD RULES — read before anything else:
+1. Edit ONLY the files listed for your lane. Other agents own the rest concurrently; touching their files corrupts their work.
+2. NO git commands, NO installs, NO format/test runners. The parent integrates centrally.
+3. Verify ONLY with \`${VERIFY}\` run from the repo root. It is repo-wide, so errors in files you do NOT own are other lanes mid-edit — ignore those. YOUR files must be clean.
+4. Match the existing code style.
+5. No behavior changes beyond your lane's brief.
+Report: files changed + one line per change.`;
+
+// One entry per parallel edit. `files` is the lane's exclusive write set.
+const LANES = [
+  {
+    name: 'engine',
+    files: ['packages/shared/subagents.ts', 'packages/shared/workflow.ts'],
+    brief: 'Make the budget counter event handling typecheck-visible…',
+  },
+  {
+    name: 'dispatch',
+    files: ['packages/subagents/index.ts'],
+    brief: 'Add allowTreeMutation + serialize tree-mutating tasks…',
+  },
+  // Add lanes here (≤ ~4 per wave).
+];
+
+const lanes = LANES.map((l) => ({
+  label: l.name,
+  prompt: COMMON + '\n\nLANE ' + l.name + ' — ' + l.files.join(', ') + ' (no other files):\n\n' + l.brief,
+}));
+
+phase('lanes');
+const results = await parallel(
+  lanes.map((l) => () => agent(l.prompt, { label: l.label, tools: ['read', 'edit', 'write', 'bash', 'grep'] })),
+);
+
+return LANES.reduce((acc, l, i) => {
+  acc[l.name] = results[i] ?? 'LANE RETURNED NULL (missing coverage)';
+  return acc;
+}, {});