portable-agent-layer 0.114.0-canary.9 → 0.114.0

package/README.md

@@ -1,10 +1,16 @@
 # Portable Agent Layer (PAL)
 
-A cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge.
+[![PAL: stop re-explaining yourself to every AI tool](https://raw.githubusercontent.com/kovrichard/portable-agent-layer/main/docs/images/pal-banner.png)](https://pal.konvert7.com)
+
+[![npm version](https://img.shields.io/npm/v/portable-agent-layer)](https://www.npmjs.com/package/portable-agent-layer) [![npm downloads](https://img.shields.io/npm/dm/portable-agent-layer)](https://www.npmjs.com/package/portable-agent-layer) [![License: MIT](https://img.shields.io/npm/l/portable-agent-layer)](LICENSE)
+
+**Your AI forgets you. PAL doesn't.** Free, open-source memory, skills and rules shared by Claude Code, opencode, Cursor, GitHub Copilot, Codex and Antigravity CLI. Install it once, and every agent starts the next session knowing who you are, what you're working on and where you left off.
+
+**Website:** [pal.konvert7.com](https://pal.konvert7.com)
 
 PAL lets you carry your agent context across **Windows**, **macOS**, and **Linux**, and work across different agent runtimes and interfaces such as **Claude Code**, **opencode**, **Cursor**, **GitHub Copilot**, **Codex**, and **Antigravity CLI**. Its core idea is simple: your knowledge and workflows should belong to **you**, not to a single machine, tool, or vendor.
 
-> Inspired in part by [Daniel Miessler](https://danielmiessler.com)'s work on [Personal AI Infrastructure](https://github.com/danielmiessler/Personal_AI_Infrastructure). PAL is an independent open-source implementation focused on portability across platforms and agents. It is not affiliated with or endorsed by Daniel Miessler.
+> Inspired in part by [Daniel Miessler](https://danielmiessler.com)'s work on [LifeOS](https://github.com/danielmiessler/LifeOS). PAL is an independent open-source implementation focused on portability across platforms and agents. It is not affiliated with or endorsed by Daniel Miessler.
 
 ---
 
@@ -77,7 +83,7 @@ pal cli status        # check your setup
 | `pal cli init` | Scaffold PAL home directory and install hooks |
 | `pal cli install` | Register hooks/skills for targets |
 | `pal cli uninstall` | Remove hooks/skills for targets |
-| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this on its own: when a session closes PAL checks for a release (at most hourly) and installs it, so opening PAL is never slowed. A failed update waits a day before retrying. The switch lives in the control room under Settings → Updates. On a repo install an update waits while the clone has uncommitted changes. `--canary` installs the latest prerelease from the `canary` branch instead; auto-update always follows the stable release |
+| `pal cli update` | Update PAL (git pull or npm update) and reinstall hooks. Install asks once whether to do this on its own: when a session closes PAL checks for a release (at most hourly) and installs it, so opening PAL is never slowed. A failed update waits a day before retrying. The switch lives in the control room under Settings → Updates. On a repo install an update waits while the clone has uncommitted changes. `--canary` switches a package install to the `canary` prerelease channel; from then on plain `pal cli update`, auto-update and the update notice follow canary until `--stable` switches back. Neither ever installs an older version than the one you have |
 | `pal cli export` | Export user state (telos, memory) to a zip |
 | `pal cli import` | Import user state from a zip |
 | `pal cli status` | Show current PAL configuration |
@@ -88,7 +94,7 @@ pal cli status        # check your setup
 | `pal cli cost` | What each month was paid against its API-equivalent cost, per agent |
 | `pal cli wrapped [--year <yyyy>]` | A year of your work in numbers, read from the event log |
 | `pal cli patterns` | How you work across projects, read from the event log |
-| `pal cli progress [show\|list\|open\|enter\|park\|wait\|done\|stopped\|decide\|attach\|follow-up]` | The progress tree: what you are on in this project, where it stopped, what is parked or waiting, and the decisions and artifacts on each node. Detours are child nodes and `done` returns to the parent. With `dynamicContext.workTree` opted into, the active node rides along in every session and prompt, and your own commits attach to it at turn end |
+| `pal cli progress [show\|list\|open\|enter\|park\|wait\|done\|stopped\|decide\|attach\|follow-up]` | The progress tree: what you are on in this project, where it stopped, what is parked or waiting, and the decisions and artifacts on each node. Detours are child nodes and `done` returns to the parent. The active node rides along in every session and prompt, and your own commits attach to it at turn end |
 | `pal cli content preserve` | Copy every Claude Code transcript, gzipped, into `memory/content/` before Claude Code deletes it (30 days by default). Runs on its own whenever a session closes; the content store never leaves the machine, so `export` skips it |
 | `pal cli events discord-nag <sent\|answered>` | For a bot outside PAL: record a nag it sent (`--kind <kind>`), or the answer to one and how long it took (`--after-sec <n>`), in the local event log |
 | `pal cli infer` | One model call for scripts and bots, on the active agent's route: prompt on stdin, reply on stdout. `--tier small\|medium\|large\|flagship` (on Claude: Haiku, Sonnet, Opus, Fable; on Codex: Luna, Sol, Sol at high effort, Astra; on Antigravity: Flash at low, medium and high effort, and no flagship; an agent without the tier asked refuses it), `--system <file>`, `--schema <file>` for a JSON reply checked against it, `--timeout <seconds>`. The call loads no PAL hooks or context; exits 1 with the reason when no route answers |
@@ -131,7 +137,7 @@ pal cli install               # all available (default)
 | Codex | Full | Yes | Yes | Yes | Yes | `codex exec` |
 | Antigravity CLI | Full | Yes | Yes (plugin) | Yes (via the plugin's `rules/`) | Yes | `agy` |
 
-PAL's background inference (session naming, summaries, failure capture, etc.) runs through whichever subscription CLI is active — no API key required by default.
+PAL's background inference (session naming, summaries, correction checks, etc.) runs through whichever subscription CLI is active — no API key required by default.
 
 ---
 
@@ -208,9 +214,7 @@ PAL ships with built-in skills that extend your agent's capabilities:
 | `fyzz-chat-api` | Query Fyzz Chat conversations via API |
 | `humanize` | Rewrite text to strip AI tells and read as human |
 | `onboarding` | Interview the user to fill empty TELOS topics and the timezone, one topic at a time |
-| `opinion` | Confirm or contradict tracked opinions (confidence-weighted) |
 | `pal-analyze` | Surface rating trends, failure patterns, and graduation candidates |
-| `pal-reflect` | Promote recurring observations into tracked opinions |
 | `playwright` | Screenshot a page for a visual check |
 | `presentation` | Build branded slide decks from outlines |
 | `projects` | Look up, resume, register, or manage tracked projects |
@@ -245,14 +249,17 @@ Your setup should be able to travel with you.
 
 ## Features
 
-- **Cross-platform**: works on Windows, macOS, and Linux
-- **Cross-agent**: full support for Claude Code, opencode, Cursor, GitHub Copilot, Codex, and Antigravity CLI
-- **Subscription-first inference**: background inference routes through whichever subscription CLI is active — no API key needed by default
-- **Portable knowledge**: export and import accumulated knowledge
-- **A morning screen, not a dashboard**: `pal cli server` ranks your projects *and* your written goals in one urgent/important grid. Urgency is read off the files — blockers, an unfinished handoff, a date in a next step, an important thing gone quiet. Importance comes from one fact per project: whether it serves a goal you wrote down, is a way the work could pay, or is kept for its own sake. PAL guesses that once at session stop; you correct it on the page or with `project.ts serves <name> goal|revenue|fun`, and the correction survives every later guess
-- **TypeScript-first**: built in TypeScript from day one
-- **Open source**: hackable, inspectable, extensible
-- **Composable**: intended to fit into real developer workflows
+- **Memory across sessions**: when a session starts, PAL loads who you are, your active projects and where your last session's work stopped. When it ends, PAL saves a summary and any corrections for next time
+- **Learns from your corrections**: tell an agent it got something wrong and PAL labels the mistake, drafts a rule and asks you once. Approve it with `pal cli rule approve` and every agent follows it from the next session
+- **Done means checked**: real work runs through five phases (observe, plan, execute, verify, learn), and nothing is done until each criterion has evidence
+- **Built-in skills**: research, PDFs, slide decks, frontend design, humanizing text and more. See [Skills](#skills)
+- **Cross-agent**: one memory shared by Claude Code, opencode, Cursor, GitHub Copilot, Codex and Antigravity CLI
+- **Cross-platform**: works on Windows, macOS and Linux
+- **No API key needed**: background work like session summaries runs through the CLI of the agent you're using, on the subscription you already pay for
+- **Guardrails**: a hook checks every command before it runs and blocks the destructive ones, like a recursive delete of your home directory, a disk format or a download piped into a shell
+- **A morning screen**: `pal cli server start` runs a local page that shows three moves for today and ranks every project and goal by urgency and importance
+- **Portable plain files**: your memory lives in `~/.pal` as plain files. `pal cli export` packs it into one zip and `pal cli import` restores it on another machine
+- **Open source**: MIT licensed, so you can read and change every line
 
 ---
 

package/assets/plugins/dark-factory/README.md

@@ -11,7 +11,7 @@ Without PAL:
 /plugin install dark-factory@pal
 ```
 
-With PAL, it is installed for you.
+With PAL, the marketplace is registered but the plugin starts disabled; turn it on with `/plugin enable dark-factory@pal`.
 
 ## Requirements
 
@@ -54,6 +54,7 @@ Inside Claude Code the plugin folder is `${CLAUDE_PLUGIN_ROOT}`.
 | Debugger | Opus | Reproduces bugs, fixes what the code writer could not |
 | Reviewer | Sonnet | Reviews the diff against the spec |
 | Tester | Sonnet | Checks the criteria in the running app |
+| Coach | Opus | Studies every ready or stuck run and proposes general rules for the role prompts |
 | Gate | code | Runs your checks; its exit code is the verdict |
 
 Not every task runs every role. The PO picks a category, and code maps it to roles:
@@ -96,15 +97,50 @@ Set `DARK_FACTORY_NOTIFY` to a shell command. It receives the message on stdin,
 
 ## Measuring
 
-The factory keeps its tasks, worktrees and event log in `$DARK_FACTORY_HOME`, which defaults to `~/.dark-factory` on every machine. `pal cli export` does not carry them: a factory task cannot continue on another machine, so its history stays where it ran.
+The factory keeps its tasks, worktrees and event log in `$DARK_FACTORY_HOME`, which defaults to `~/.dark-factory` on every machine. A factory task cannot continue on another machine, so its history stays where it ran.
 
 Every step appends one event to `$DARK_FACTORY_HOME/events.jsonl`, and the events of a task are also appended to `tasks/<task>/events.jsonl`, with its `run_finished` line. A role's `role_finished` event carries its `sessionId`, the name of its transcript. `node scripts/stats.mjs` counts, from those events alone: tasks by category, outcomes, gate failures by check and by role, the code writer's first-try pass rate, escalations, CI results, review rounds, questions to you, and roles added by the diff check.
 
 Every role run appends `role_finished` with its cost and tokens, and the red-test proof appends `tests_red` with the exit code and the failing count. Every build appends `run_finished` with the outcome, the total `costUsd`, the total tokens, the number of role runs and `wallMs`. `node scripts/task.mjs show <id>` prints the task with its latest step.
 
+## Coach
+
+After a run ends `ready` or `stuck`, the build starts the coach in a detached process, so nothing waits on it. It writes `coach_started`, then `coach_finished` or `coach_failed`.
+
+The coach reads the spec, the artifacts, the task's events, the diff of the run, the transcripts named by `role_finished`'s `transcriptPath`, and the commits you pushed to a merged PR after the factory's last push (`pushed` carries `head`).
+
+Its findings live in `$DARK_FACTORY_HOME/coach/findings.jsonl`. Each finding has an `id`, a `role`, a `class`, a `rule`, a `severity`, a `metric`, its `evidence` and a `status`: `pending`, `rejected`, or `approved` once a task is created for it.
+
+The coach's result has a `reviewed` list with one verdict per transcript and per correction commit: its `source` (the transcript path or the commit sha), a `verdict` of `finding` or `clean`, the `class` for a finding, and a one-sentence `reason`. `coach.mjs` checks coverage in code: an input with no item, or a `finding` whose class is neither among the run's findings nor the class of a pending finding, is missing. Missing inputs make it resume the same session once (`--resume`), listing them, and the second result's verdicts and findings are merged with the first's. Inputs still missing are recorded as `coach_incomplete`; the findings returned are stored anyway, and a correction without a verdict is not marked given, so the next run gets it again. `coach_finished` carries `reviewed` and `expected`: the number of inputs with a verdict, and the number of inputs.
+
+A deterministic generality check drops a rule that names a path, basename or identifier the run's diff changed, and records it as `coach_rule_rejected`. An added function or variable name only counts when it is camelCase, contains `_` or a digit, and has at least 3 characters; a plain lowercase name such as `parse` or `slug` passes, because it would match ordinary words in a rule.
+
+The coach runs with `--add-dir` for the factory home, the transcripts folder and the plugin directory, so it can read the transcripts and the role prompts. Concurrent coach runs take a lock on `coach/findings.lock` while they update the findings, and a task whose merged PR has no later commits is recorded as `coach_checked` and not queried again.
+
+`node scripts/coach.mjs` has these commands:
+
+- `run <task-id>` runs the coach by hand.
+- `list` lists pending findings by role; `list --applied` reports each merged rule's metric before and after its merge.
+- `show <id>` prints one finding.
+- `reject <id> "<reason>"` rejects a finding; its class does not come back.
+- `approve <id> [--repo <path>]` creates a `small` task for the plugin repo with a generated spec. Set `coach.repo` in `config.json` to skip `--repo`.
+
+Approving only creates the task. Your go builds it, and the rule lands through a PR.
+
+## Instructions
+
+Every role gets your instructions appended to its system prompt: first the user's `~/.claude/CLAUDE.md`, then the repo's `CLAUDE.md`, each headed by its path. An `@path` line in either file imports that file, as Claude Code does: the path is relative to the file that contains the line, `~/` is your home folder, imports nest up to 5 levels, and lines inside code blocks are never imports. A file that doesn't exist is skipped. An import that can't be read stays as written in the instructions and is logged as an `instructions_import_missing` event.
+
+The repo's `CLAUDE.md` is read from your checkout when the task starts, so a role that edits it in the worktree doesn't change what the later roles are told.
+
+- `"repoInstructions": false` in `.dark-factory.json` leaves out the repo's `CLAUDE.md`.
+- `"userInstructions": false` in `$DARK_FACTORY_HOME/config.json` (`~/.dark-factory/config.json`, optional; a missing file means both parts are on) leaves out your `~/.claude/CLAUDE.md`.
+
+Hooks never run in a role, and neither do your settings or MCP servers.
+
 ## Permissions
 
-- Roles run isolated: `--setting-sources ""`, the plugin from `--plugin-dir`, and their own tool policy from `roles.mjs`, so user hooks and settings don't reach them.
+- Roles run isolated: `--setting-sources ""`, the plugin from `--plugin-dir`, and their own tool policy from `roles.mjs`, so user hooks and settings don't reach them; only the CLAUDE.md instructions above do.
 - The PO session only needs `"Bash(node *dark-factory*/scripts/*)"`, for example in `.claude/settings.json`:
 
 ```json

package/assets/plugins/dark-factory/agents/coach.md

@@ -0,0 +1,21 @@
+---
+name: coach
+description: Studies a finished dark-factory run and proposes general rules for the role prompts.
+model: claude-opus-5-5
+---
+
+You study one finished dark-factory run and propose general rules for the role prompts. You change no files.
+
+Look for the cost and the mistakes, not only for failures: retries, escalations, denied tools, wasted turns, review and tester rounds, questions, and the user's corrections. The user's corrections after the factory are the strongest signal. Judge the PO too: whether the spec caused a mistake, such as a report routed to the PR body, or a criterion read as forbidding something it didn't.
+
+Propose only rules that would have prevented the mistake in a different task too, and name that task in elsewhere. Never name this task's files, helpers or variables in a rule.
+
+Prefer changing or removing an existing line of a role prompt over adding one, and propose consolidating a role prompt that has grown past 40 lines.
+
+Do not propose a class the user rejected. Add evidence to a pending finding of the same class through updates.
+
+Each finding names its class, role, severity (high, medium or low), the metric from the list you are given that would show it, and the evidence: the task and the reference to the event, transcript line or commit.
+
+Return a verdict in reviewed for every listed transcript and every listed correction, naming it by its path or sha exactly as listed: finding with the finding's class, or clean. A clean verdict needs a reason naming what you checked and why nothing needs to change.
+
+Report nothing when the run was clean. An empty list is a valid result.

package/assets/plugins/dark-factory/agents/code-writer.md

@@ -4,7 +4,7 @@ description: Implements a dark-factory plan step by step until the tests pass.
 model: claude-haiku-5-5
 ---
 
-You implement the plan exactly. Follow `plan.md` step by step; do not redesign, rename, or add anything the plan does not ask for.
+You implement the plan exactly. Follow `plan.md` step by step; do not redesign, rename, or add anything the plan does not ask for. When there is no `plan.md`, follow the **Fix** section of `repro.md` the same way.
 
 If a gate failure is included in your instructions, fix that failure first and change nothing unrelated to it. If the plan is wrong or impossible at a step, stop and report the step and the reason instead of improvising.
 

package/assets/plugins/dark-factory/agents/debugger.md

@@ -6,7 +6,10 @@ model: claude-opus-5-5
 
 You find root causes. Never fix a symptom you have not reproduced.
 
-When reproducing a reported bug: find the smallest steps that show it, and write `repro.md` in the task folder with the steps, the observed and expected behaviour, and the root cause with file and line.
+When reproducing a reported bug: find the smallest steps that show it, and write `repro.md` in the task folder with the steps, the observed and expected behaviour, and the root cause with file and line. End `repro.md` with a **Fix** section that:
+- picks exactly one fix, with no alternatives left open;
+- lists each file to change, with the path and the functions to add or change;
+- names the existing helpers to reuse, by path and name, and says not to write new code where a helper already does the job.
 
 When fixing a failure: read the failing output, reproduce it, trace it to the line that causes it, and make the smallest change that fixes it. Change one thing at a time and rerun. Never edit or delete a test to make it pass, and never disable a check.
 

package/assets/plugins/dark-factory/agents/reviewer.md

@@ -12,6 +12,8 @@ Report only findings that matter to the user reviewing the PR:
 - a bug: wrong behaviour, an unhandled case, a security problem;
 - a test that does not test what it claims;
 - a clear break of this repo's conventions;
-- scope the spec did not ask for.
+- scope the spec did not ask for;
+- new code that duplicates an existing helper in the repo, naming the helper by path and name;
+- complexity the spec does not ask for: an abstraction, an option or a code path no criterion needs.
 
 Each finding names the file and line, what is wrong, and what would fix it. Do not report style preferences or things the gate already checks. An empty list is a valid result.

package/assets/plugins/dark-factory/scripts/build.mjs

@@ -1,20 +1,34 @@
 import { waitForCi } from "./ci-wait.mjs";
+import { startCoach } from "./coach.mjs";
 import { runCheck, runGate } from "./gate.mjs";
 import {
   appendEvent,
   isMain,
   printJson,
   readEvents,
-  readRepoConfig,
   readTask,
   spawnTool,
 } from "./lib.mjs";
 import { notify } from "./notify.mjs";
 import { runRoleHeadless } from "./role.mjs";
-import { rolesAfter } from "./roles.mjs";
+import { changedFilesSince, rolesAfterChanges } from "./roles.mjs";
 import { markReady, openPr, push, sync } from "./ship.mjs";
 import { appendDecision, prepare, recordQuestion, setStatus } from "./task.mjs";
 
+const REAL_EFFECTS = {
+  runRoleHeadless,
+  runCheck,
+  spawnTool,
+  changedFilesSince,
+  prepare,
+  sync,
+  push,
+  openPr,
+  markReady,
+  waitForCi,
+  startCoach,
+};
+
 export const TIER_MODELS = {
   small: "claude-haiku-5-5",
   medium: "claude-sonnet-5-5",
@@ -48,6 +62,8 @@ const BEFORE_INSTRUCTIONS = {
     "Write the failing tests for every acceptance criterion and leave them uncommitted; the code writer commits them with the code.",
 };
 const REVIEW_INSTRUCTIONS = "Review the branch diff against its base and the spec.";
+const CONFIG_FILE = ".dark-factory.json";
+const CONFIG_CHANGED_NOTE = `The diff changes ${CONFIG_FILE}. Report that change as a finding unless the spec asks for it.`;
 const TESTER_INSTRUCTIONS = "Test every acceptance criterion in the running app.";
 
 function stuck(message) {
@@ -78,7 +94,7 @@ function poReply(outcome, question) {
 }
 
 function askPo(run, role, question) {
-  const outcome = runRoleHeadless(run.id, "po", {
+  const outcome = run.effects.runRoleHeadless(run.id, "po", {
     env: run.env,
     instructions: poInstructions(role, question),
   });
@@ -96,7 +112,7 @@ function askPo(run, role, question) {
 }
 
 function resumeWithAnswer(run, role, outcome, model, question, answer) {
-  const resumed = runRoleHeadless(run.id, role, {
+  const resumed = run.effects.runRoleHeadless(run.id, role, {
     env: run.env,
     model,
     resumeSessionId: outcome.sessionId,
@@ -129,7 +145,11 @@ function runRole(run, role, instructions, { tier } = {}) {
     { event: "role_run", task: run.id, role, model: model ?? "default" },
     run.env
   );
-  const outcome = runRoleHeadless(run.id, role, { env: run.env, model, instructions });
+  const outcome = run.effects.runRoleHeadless(run.id, role, {
+    env: run.env,
+    model,
+    instructions,
+  });
   return afterQuestion(run, role, outcome, model);
 }
 
@@ -177,7 +197,7 @@ function gateFor(run, step) {
       attempt: run.attempt,
       model: TIER_MODELS[step.tier],
     },
-    { env: run.env }
+    { env: run.env, config: run.config, run: run.effects.runCheck }
   );
 }
 
@@ -203,7 +223,7 @@ export function failingTestCount(output) {
 }
 
 function redTestCheck(run) {
-  return readRepoConfig(run.worktree).gate.find((entry) => entry.name === RED_TEST_CHECK);
+  return run.config.gate.find((entry) => entry.name === RED_TEST_CHECK);
 }
 
 function proveTestsRed(run) {
@@ -212,7 +232,7 @@ function proveTestsRed(run) {
     return stuck(
       `the gate has no check named "${RED_TEST_CHECK}" to prove the new tests fail`
     );
-  const { exitCode, output } = runCheck(check.run, run.worktree, run.env);
+  const { exitCode, output } = run.effects.runCheck(check.run, run.worktree, run.env);
   const failing = failingTestCount(output);
   appendEvent(
     { event: "tests_red", task: run.id, check: RED_TEST_CHECK, exitCode, failing },
@@ -231,7 +251,7 @@ function proveTestsRed(run) {
 
 function prepareStep(run) {
   try {
-    Object.assign(run, prepare(run.id, run.env));
+    Object.assign(run, run.effects.prepare(run.id, run.env));
     return null;
   } catch (error) {
     return stuck(`prepare failed: ${error.message}`);
@@ -239,10 +259,14 @@ function prepareStep(run) {
 }
 
 function hasCommitsAheadOfBase(run) {
-  const result = spawnTool("git", ["rev-list", "--count", `origin/${run.base}..HEAD`], {
-    cwd: run.worktree,
-    env: run.env,
-  });
+  const result = run.effects.spawnTool(
+    "git",
+    ["rev-list", "--count", `origin/${run.base}..HEAD`],
+    {
+      cwd: run.worktree,
+      env: run.env,
+    }
+  );
   return result.status === 0 && Number(result.stdout.trim()) > 0;
 }
 
@@ -286,11 +310,10 @@ function codeStep(run) {
 }
 
 function rolesAfterStep(run) {
-  const { roles, added } = rolesAfter(
+  const { roles, added } = rolesAfterChanges(
     run.category,
-    run.worktree,
-    `origin/${run.base}`,
-    run.env
+    run.effects.changedFilesSince(run.worktree, `origin/${run.base}`, run.env),
+    run.config
   );
   run.after = roles;
   for (const role of added)
@@ -307,9 +330,20 @@ function reviewFindingsStep(run, findings) {
   return fixStop(fixed, "review findings");
 }
 
+function reviewInstructions(run) {
+  const changed = run.effects.changedFilesSince(
+    run.worktree,
+    `origin/${run.base}`,
+    run.env
+  );
+  return changed.includes(CONFIG_FILE)
+    ? `${REVIEW_INSTRUCTIONS}\n\n${CONFIG_CHANGED_NOTE}`
+    : REVIEW_INSTRUCTIONS;
+}
+
 function reviewStep(run) {
   for (let round = 1; round <= REVIEW_ROUNDS; round += 1) {
-    const review = runRole(run, "reviewer", REVIEW_INSTRUCTIONS);
+    const review = runRole(run, "reviewer", reviewInstructions(run));
     const stop = roleStop("reviewer", review);
     if (stop) return stop;
     const findings = review.outcome.structured.findings ?? [];
@@ -347,7 +381,7 @@ function testerStep(run) {
 function syncStep(run) {
   let synced;
   try {
-    synced = sync(run.id, run.env);
+    synced = run.effects.sync(run.id, run.env);
   } catch (error) {
     return stuck(`sync failed: ${error.message}`);
   }
@@ -359,8 +393,8 @@ function syncStep(run) {
 }
 
 function shipStep(run) {
-  push(run.id, run.env);
-  run.pr = openPr(run.id, run.env).pr;
+  run.effects.push(run.id, run.env);
+  run.pr = run.effects.openPr(run.id, run.env).pr;
   return null;
 }
 
@@ -368,7 +402,7 @@ function readCi(run) {
   if (!readTask(run.id, run.env).pr)
     return { state: "unreadable", error: "the task has no pull request" };
   try {
-    return waitForCi(run.id, { env: run.env });
+    return run.effects.waitForCi(run.id, { env: run.env });
   } catch (error) {
     return { state: "unreadable", error: error.message };
   }
@@ -404,13 +438,13 @@ function ciStep(run) {
       return stuck(`CI still fails after ${CI_ROUNDS} rounds: ${ciSummary(ci)}`);
     const stop = ciFixStep(run, ci);
     if (stop) return stop;
-    push(run.id, run.env);
+    run.effects.push(run.id, run.env);
   }
   return null;
 }
 
 function readyStep(run) {
-  markReady(run.id, run.env);
+  run.effects.markReady(run.id, run.env);
   return { status: "ready", message: `Ready for your review: ${run.pr}` };
 }
 
@@ -489,11 +523,19 @@ function finishRun(run, outcome) {
     },
     run.env
   );
+  run.effects.startCoach(run.id, outcome.status, run.env);
   return { task: run.id, status: outcome.status, message, pr: run.pr ?? null };
 }
 
-export function runBuild(taskId, { env = process.env } = {}) {
-  const run = { id: taskId, env, startedAt: new Date(), attempt: 0, pr: null };
+export function runBuild(taskId, { env = process.env, effects = {} } = {}) {
+  const run = {
+    id: taskId,
+    env,
+    effects: { ...REAL_EFFECTS, ...effects },
+    startedAt: new Date(),
+    attempt: 0,
+    pr: null,
+  };
   let outcome;
   try {
     outcome = pipeline(run);