@opsee/cli 0.11.9

package/src/foreman/core/work-contract.ts

@@ -0,0 +1,152 @@
+/**
+ * The work contract (see ../../../CONTEXT.md: Goal, Acceptance Criteria, Verification, Boundaries;
+ * spec story 23): the headings a Ready Task's description carries, validated at dispatch. Goal and
+ * Acceptance Criteria are what a Worker implements against and cannot be invented, so a Task missing
+ * either is blocked with a comment saying what is absent. Verification is what the Verifier follows
+ * and can be drafted from the other two, so a Task missing only that gets a Triage turn (triage.ts)
+ * whose draft is posted as a comment; the comment is the record the Verifier slice reads back with
+ * `draftedVerificationFrom`. Boundaries is optional. Nothing here edits a Task description.
+ *
+ * Everything in this module is pure; run.ts calls it before the dispatch event.
+ */
+import { DISPATCH_LABEL, type TrackerComment } from "../tracker-adapter.js";
+
+export const WORK_CONTRACT_SECTIONS = ["Goal", "Acceptance Criteria", "Verification", "Boundaries"] as const;
+export type WorkContractSection = (typeof WORK_CONTRACT_SECTIONS)[number];
+
+/** The sections a Task must carry to be dispatched; Boundaries is optional. */
+export const REQUIRED_SECTIONS: readonly WorkContractSection[] = ["Goal", "Acceptance Criteria", "Verification"];
+
+export interface WorkContract {
+  /** Each present section's body, trimmed, without its heading; a section with nothing under its
+   * heading is absent. */
+  sections: Partial<Record<WorkContractSection, string>>;
+}
+
+/** What the check at dispatch found (not a Verdict, which is the Verifier's word). */
+export type WorkContractCheck =
+  | { status: "ok" }
+  /** Goal and Acceptance Criteria are there; Verification is the only required section missing. */
+  | { status: "needs_triage"; missing: ["Verification"] }
+  /** Goal or Acceptance Criteria is missing: every absent required section, in canonical order. */
+  | { status: "blocked"; missing: WorkContractSection[] };
+
+const HEADING = /^ {0,3}(#{1,6})\s+(.+?)\s*$/;
+const FENCE = /^ {0,3}(```|~~~)/;
+
+/** `## Acceptance criteria:` and `### VERIFICATION ##` both name their section. */
+function sectionOf(headingText: string): WorkContractSection | undefined {
+  const name = headingText
+    .replace(/\s*#+\s*$/, "")
+    .replace(/\s*:+\s*$/, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+  return WORK_CONTRACT_SECTIONS.find((s) => s.toLowerCase() === name);
+}
+
+/** Which of the four sections the description (markdown; the Tracker Adapter converts its storage
+ * format) carries. A heading counts only with something under it: an empty section is a
+ * placeholder, not a contract. Headings inside fenced code are content. */
+export function parseWorkContract(description: string): WorkContract {
+  const bodies = new Map<WorkContractSection, string[]>();
+  let current: WorkContractSection | undefined;
+  let currentLevel = 0;
+  let inFence = false;
+  for (const line of description.split("\n")) {
+    if (FENCE.test(line)) {
+      inFence = !inFence;
+    } else if (!inFence) {
+      const heading = HEADING.exec(line);
+      if (heading) {
+        const level = heading[1].length;
+        const named = sectionOf(heading[2]);
+        // A section runs until a heading at its own level or above, or one naming another
+        // section: `### Commands` under `## Verification` is part of Verification, not its end.
+        if (named) {
+          current = named;
+          currentLevel = level;
+          if (!bodies.has(current)) bodies.set(current, []);
+          continue;
+        }
+        if (current && level > currentLevel) {
+          bodies.get(current)!.push(line);
+          continue;
+        }
+        current = undefined;
+        continue;
+      }
+    }
+    if (current) bodies.get(current)!.push(line);
+  }
+
+  const sections: Partial<Record<WorkContractSection, string>> = {};
+  for (const [section, lines] of bodies) {
+    const body = lines.join("\n").trim();
+    if (body) sections[section] = body;
+  }
+  return { sections };
+}
+
+export function validateWorkContract(contract: WorkContract): WorkContractCheck {
+  const missing = REQUIRED_SECTIONS.filter((s) => contract.sections[s] === undefined);
+  if (missing.length === 0) return { status: "ok" };
+  if (missing.length === 1 && missing[0] === "Verification") return { status: "needs_triage", missing: ["Verification"] };
+  return { status: "blocked", missing };
+}
+
+/** First line of the comment a Triage turn leaves; what `draftedVerificationFrom` looks for. */
+export const TRIAGE_COMMENT_MARKER = "Foreman: drafted Verification section (Triage turn)";
+
+const DRAFT_HEADING = "## Verification";
+
+/** The comment carrying a drafted Verification section: the marker, then the section as it would
+ * read in the description, so a human can paste it there. */
+export function triageComment(verification: string): string {
+  return `${TRIAGE_COMMENT_MARKER}\n\n${DRAFT_HEADING}\n\n${verification.trim()}`;
+}
+
+export interface DraftedVerification {
+  /** The comment the draft was read from. */
+  commentId: number;
+  verification: string;
+}
+
+/** The newest Verification section the Foreman drafted on a Task, from its comments; what a later
+ * dispatch reuses instead of running another Triage turn, and what the Verifier follows. */
+export function draftedVerificationFrom(comments: Pick<TrackerComment, "id" | "body">[]): DraftedVerification | undefined {
+  const drafts = comments
+    .filter((c) => c.body.startsWith(TRIAGE_COMMENT_MARKER))
+    .sort((a, b) => b.id - a.id);
+  for (const draft of drafts) {
+    const rest = draft.body.slice(TRIAGE_COMMENT_MARKER.length);
+    const at = rest.indexOf(DRAFT_HEADING);
+    const verification = (at === -1 ? rest : rest.slice(at + DRAFT_HEADING.length)).trim();
+    if (verification) return { commentId: draft.id, verification };
+  }
+  return undefined;
+}
+
+const RELABEL = `The "${DISPATCH_LABEL}" label has been removed; add the missing sections to the description and re-add the label.`;
+
+/** The comment on a Task the Foreman will not dispatch. The dispatch label comes off with it, or
+ * the Task would be picked again every tick; a human re-adds it after fixing the description. */
+export function blockedComment(missing: readonly WorkContractSection[]): string {
+  return `Foreman: cannot dispatch, the work contract is missing: ${missing.join(", ")}. ${RELABEL}`;
+}
+
+/** The comment when the Triage turn produced no draft: the section is still missing, and why. */
+export function triageFailedComment(reason: string): string {
+  return `Foreman: cannot dispatch, the work contract is missing: Verification, and the Triage turn drafted nothing (${reason}). ${RELABEL}`;
+}
+
+/** The comment when every Triage turn the retry cap allows ended in a machine-side failure — a
+ * stall, a rate limit — rather than in a draft. Names the cause that spent the attempts, the way a
+ * capped dispatch does, so a human reading the Task alone knows whether to retry it or to fix
+ * something first. */
+export function triageCappedComment(outcome: string, reason: string, attempts: number, retries: number): string {
+  return (
+    `Foreman: cannot dispatch, the work contract is missing: Verification, and every Triage turn allowed for drafting it ended ${outcome} (${reason}).` +
+    ` ${attempts} ${attempts === 1 ? "attempt" : "attempts"} ended that way, which is the retry cap (${retries}) reached; nothing about the Task itself is known to be wrong. ${RELABEL}`
+  );
+}

package/src/foreman/core/workspace.ts

@@ -0,0 +1,335 @@
+/**
+ * Workspaces (see ../../../CONTEXT.md, story 19, ADR-0003): one git worktree per Ready Task, on a
+ * branch named after the Task identifier, created from the default branch's remote head.
+ *
+ * Where they live: `~/.opsee/workspaces/<repo>-<hash>/<identifier>` (or under
+ * `OPSEE_FOREMAN_WORKSPACES_PATH`), never inside the repository. Inside it a Workspace would show
+ * up in the main checkout's `git status` (the Foreman must leave that checkout untouched, story 22)
+ * and would sit in a directory something cleans; a Workspace outlives its turn until the Hand-off
+ * is merged or closed (ADR-0003), so it belongs beside the Foreman's other durable state, the
+ * Accounts file. The hash is of the repository's resolved root, so two checkouts of the same repo
+ * (or two repos with the same name) never share a Workspace.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { execToString } from "./exec.js";
+
+export interface Workspace {
+  /** Absolute path of the worktree: the Worker's cwd and nothing else. */
+  path: string;
+  branch: string;
+  /** False when the Workspace already existed (an earlier attempt on the same Task). */
+  created: boolean;
+  /** What the branch was created from, when it was created here. */
+  base?: string;
+}
+
+/** Runs one git command in `cwd` and resolves with trimmed stdout; rejects on a non-zero exit with
+ * stderr in the message. The seam the tests replace to script git without a repository. */
+export type GitRunner = (args: string[], cwd: string) => Promise<string>;
+
+export const runGit: GitRunner = async (args, cwd) => (await execToString("git", args, cwd, `git ${args.join(" ")}`)).trim();
+
+/** The name of the default branch on `origin` (`development`, `main`...): what `origin/HEAD` points
+ * at, else the first of the usual names that exists on origin; undefined when none can be found.
+ * Workspaces start from it and the Hand-off targets it, so both read it from one place. */
+export async function defaultBranchOf(git: GitRunner, repoRoot: string): Promise<string | undefined> {
+  try {
+    const ref = await git(["symbolic-ref", "--short", "refs/remotes/origin/HEAD"], repoRoot);
+    return ref.replace(/^origin\//, "");
+  } catch {
+    /* origin/HEAD unset: a clone made before the remote had a HEAD, or a bare-remote setup */
+  }
+  for (const candidate of ["development", "main", "master"]) {
+    try {
+      await git(["rev-parse", "--verify", "--quiet", `origin/${candidate}`], repoRoot);
+      return candidate;
+    } catch {
+      /* not this one */
+    }
+  }
+  return undefined;
+}
+
+/** A git command the Foreman refuses to run: a push to the default branch, or a merge. */
+export class GitGuardError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "GitGuardError";
+  }
+}
+
+/** The global git options the Foreman itself uses. Any other option before the subcommand is
+ * refused rather than skipped: `--namespace x push ...` or `--config-env k=v push ...` would
+ * otherwise make the guard read `x` as the subcommand and never look at the push. */
+const GLOBAL_OPTIONS_WITH_VALUE = new Set(["-c", "-C"]);
+const GLOBAL_FLAGS = new Set(["--no-pager", "--no-optional-locks"]);
+
+/** The subcommands the Foreman runs. An alias (`-c alias.p=push p ...`) or anything else is
+ * refused: an allow-list cannot be talked around by a spelling the guard does not know. `show`
+ * reads a blob of the base (the Gates' recipe, gates.ts); `add` and `commit` write the learnings
+ * file on the Foreman's own branch, and `reset` aligns that Workspace with origin before adding to
+ * an open pull request (core/learnings.ts); none of them can push or merge. */
+const ALLOWED_SUBCOMMANDS = new Set(["fetch", "push", "worktree", "rev-parse", "rev-list", "status", "remote", "symbolic-ref", "branch", "log", "show", "show-ref", "ls-remote", "config", "add", "commit", "reset"]);
+
+/** The git subcommand in `args`, past the global options the Foreman uses. `undefined` when the
+ * command line is shaped in a way the guard does not understand; that is refused, not allowed. */
+function subcommandOf(args: string[]): { name: string | undefined; rest: string[] } {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (GLOBAL_OPTIONS_WITH_VALUE.has(arg)) {
+      if (arg === "-c" && /^alias\./i.test(args[i + 1] ?? "")) return { name: undefined, rest: [] };
+      i++;
+      continue;
+    }
+    if (GLOBAL_FLAGS.has(arg)) continue;
+    if (arg.startsWith("-")) return { name: undefined, rest: [] };
+    return { name: arg, rest: args.slice(i + 1) };
+  }
+  return { name: undefined, rest: [] };
+}
+
+/** A push option the Foreman never sends and a remote could act on: on GitLab `merge_request.*`
+ * options create, retarget, or schedule the merge of an MR from the push itself. */
+function pushOptionsOf(rest: string[]): string[] {
+  const options: string[] = [];
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "-o" || arg === "--push-option") options.push(rest[++i] ?? "");
+    else if (arg.startsWith("--push-option=")) options.push(arg.slice("--push-option=".length));
+    else if (arg.startsWith("-o") && arg.length > 2) options.push(arg.slice(2));
+  }
+  return options;
+}
+
+/** Push options that take their value as the next argument, so the value is not read as the remote
+ * or a refspec (`-o reviewer=x origin a:b` would otherwise shift the parse by one). */
+const PUSH_OPTIONS_WITH_VALUE = new Set(["-o", "--push-option", "--receive-pack", "--exec", "--repo", "--recurse-submodules", "--signed", "--force-if-includes"]);
+
+/** What a `git push` argument list would write on the remote: the destination of every refspec,
+ * or `undefined` for a push whose targets git alone would decide (no refspec, `--all`, `--mirror`).
+ * Destinations are bare branch names, `HEAD` for the remote's HEAD. */
+function pushDestinations(rest: string[]): string[] | undefined {
+  const positional: string[] = [];
+  let del = false;
+  let everything = false;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    if (arg === "--delete" || arg === "-d") del = true;
+    else if (arg === "--all" || arg === "--mirror" || arg === "--branches" || arg === "--tags") everything = true;
+    else if (PUSH_OPTIONS_WITH_VALUE.has(arg)) i++;
+    else if (!arg.startsWith("-")) positional.push(arg);
+  }
+  if (everything) return undefined;
+  const refspecs = positional.slice(1);
+  if (refspecs.length === 0) return undefined;
+  return refspecs.map((spec) => {
+    const dst = del ? spec : spec.includes(":") ? spec.slice(spec.indexOf(":") + 1) : spec;
+    return dst.replace(/^\+/, "").replace(/^refs\/heads\//, "");
+  });
+}
+
+/** Wraps a GitRunner so the two things the Foreman must never do cannot happen by accident
+ * (ADR-0003, story 26): a `push` that would update the default branch on origin (by name, by the
+ * remote's `HEAD`, by deletion, or by pushing everything) is refused, and so is every `merge` and
+ * `pull`. Only the remote's default branch name is origin's; a refspec is judged by its destination
+ * whatever remote it names, so `push upstream x:development` is refused as well. The
+ * default branch is read once per repository the way Workspaces read it. A push with no explicit
+ * refspec is refused too: where it lands depends on configuration the guard cannot see. */
+export function guardedGit(inner: GitRunner, repoRoot: string): GitRunner {
+  let defaultBranch: Promise<string | undefined> | undefined;
+  return async (args, cwd) => {
+    const { name, rest } = subcommandOf(args);
+    // `pull` is a fetch plus a merge (or a rebase) into the checked-out branch: a merge by another name.
+    if (name === "merge" || name === "pull") {
+      throw new GitGuardError(`refused: git ${args.join(" ")}. The Foreman never merges; work leaves a Workspace only as a draft pull request (ADR-0003).`);
+    }
+    if (name === undefined || !ALLOWED_SUBCOMMANDS.has(name)) {
+      throw new GitGuardError(`refused: git ${args.join(" ")}. The Foreman runs a fixed set of git subcommands with no aliases or unknown global options, so the guard can always see a push or a merge (ADR-0003).`);
+    }
+    if (name === "push") {
+      const options = pushOptionsOf(rest);
+      if (options.length > 0) {
+        throw new GitGuardError(`refused: git ${args.join(" ")}. A Hand-off sends no push options; ${options.map((o) => `"${o}"`).join(", ")} could make the remote create, retarget, or merge a pull request on its own (ADR-0003).`);
+      }
+      const destinations = pushDestinations(rest);
+      if (!destinations) {
+        throw new GitGuardError(`refused: git ${args.join(" ")}. A Hand-off pushes one named branch explicitly, never whatever git would choose, so it cannot reach the default branch (ADR-0003).`);
+      }
+      defaultBranch ??= defaultBranchOf(inner, repoRoot);
+      const def = await defaultBranch;
+      const hit = destinations.find((d) => d === "HEAD" || (def !== undefined && d === def));
+      if (hit) {
+        throw new GitGuardError(
+          `refused: git ${args.join(" ")}. It would write ${hit === "HEAD" ? "the remote's HEAD" : `the default branch "${def}"`} on origin; the Foreman never pushes to the default branch, the Hand-off is a draft pull request (ADR-0003).`,
+        );
+      }
+    }
+    return inner(args, cwd);
+  };
+}
+
+/** The branch for a Task: its identifier, lowercased, so `OPS-269` works on `ops-269`. A branch the
+ * Foreman names itself (`foreman/learnings-17-...`, core/learnings.ts) may carry `/`-separated
+ * segments; each segment is held to the same shape. */
+export function branchFor(identifier: string): string {
+  const branch = identifier.trim().toLowerCase();
+  if (!/^[a-z0-9][a-z0-9._-]*(\/[a-z0-9][a-z0-9._-]*)*$/.test(branch)) {
+    throw new Error(`Task identifier "${identifier}" does not make a valid branch name`);
+  }
+  return branch;
+}
+
+export function workspacesRoot(): string {
+  return process.env.OPSEE_FOREMAN_WORKSPACES_PATH || join(homedir(), ".opsee", "workspaces");
+}
+
+/** `<basename>-<12 hex of sha256(resolved root)>`: readable, and unique per checkout. */
+export function repoKey(repoRoot: string): string {
+  const real = existsSync(repoRoot) ? realpathSync(repoRoot) : resolve(repoRoot);
+  const hash = createHash("sha256").update(real).digest("hex").slice(0, 12);
+  return `${basename(real)}-${hash}`;
+}
+
+export function workspacePath(repoRoot: string, identifier: string, root: string = workspacesRoot()): string {
+  return join(root, repoKey(repoRoot), branchFor(identifier));
+}
+
+export interface WorkspaceManagerOptions {
+  /** Where Workspaces live; `workspacesRoot()` by default. */
+  root?: string;
+  git?: GitRunner;
+  log?: (line: string) => void;
+}
+
+/** Creates and removes Workspaces for one repository checkout. */
+export class WorkspaceManager {
+  /** Creations in flight, one at a time; see `create`. */
+  private queue: Promise<void> = Promise.resolve();
+  private readonly root: string;
+  private readonly git: GitRunner;
+  private readonly log: (line: string) => void;
+
+  constructor(
+    private readonly repoRoot: string,
+    options: WorkspaceManagerOptions = {},
+  ) {
+    this.root = options.root ?? workspacesRoot();
+    this.git = options.git ?? runGit;
+    this.log = options.log ?? (() => {});
+  }
+
+  pathFor(identifier: string): string {
+    return workspacePath(this.repoRoot, identifier, this.root);
+  }
+
+  /** The worktree for `identifier`, created from the default branch's remote head when it does not
+   * exist yet. A branch left by an earlier attempt is checked out again rather than recreated, so a
+   * Worker resumes where the last one stopped; a branch that exists on origin but not here (pushed
+   * from another machine, or the head of a pull request the Foreman is adding to) is checked out
+   * from the remote head, tracking it.
+   *
+   * Creations are taken one at a time. `git worktree add` and `git fetch` write the repository's
+   * own bookkeeping — the worktree list, `FETCH_HEAD`, the remote refs — so two of them at once in
+   * the same checkout race on the same lock files. Slots (core/scheduler.ts) made this concurrent;
+   * queueing here keeps that away from git, and costs nothing worth having, since a creation is
+   * seconds and the Worker turn that follows it is not serialised at all.
+   *
+   * The queue is this manager's, so it holds within one Foreman process and nowhere else: two
+   * Foremen on the same checkout still race each other on those same lock files, and what keeps
+   * them apart is that only one Foreman runs an Account (commands/foreman.ts) — not this. */
+  async create(identifier: string): Promise<Workspace> {
+    // A failed creation must not poison the queue for the Slots behind it.
+    const mine = this.queue.then(
+      () => this.createOne(identifier),
+      () => this.createOne(identifier),
+    );
+    this.queue = mine.then(
+      () => undefined,
+      () => undefined,
+    );
+    return mine;
+  }
+
+  private async createOne(identifier: string): Promise<Workspace> {
+    const branch = branchFor(identifier);
+    const path = this.pathFor(identifier);
+
+    if (existsSync(path) && (await this.isWorktree(path))) {
+      return { path, branch, created: false };
+    }
+    mkdirSync(resolve(path, ".."), { recursive: true });
+
+    if (await this.branchExists(branch)) {
+      this.log(`workspace: branch ${branch} exists; checking it out at ${path}`);
+      await this.git(["worktree", "add", path, branch], this.repoRoot);
+      return { path, branch, created: true };
+    }
+    const base = await this.defaultBase();
+    if (await this.refExists(`refs/remotes/origin/${branch}`)) {
+      this.log(`workspace: branch ${branch} exists on origin; checking it out at ${path}`);
+      await this.git(["worktree", "add", "-b", branch, path, `origin/${branch}`], this.repoRoot);
+      return { path, branch, created: true, base: `origin/${branch}` };
+    }
+    this.log(`workspace: creating ${branch} from ${base} at ${path}`);
+    await this.git(["worktree", "add", "-b", branch, path, base], this.repoRoot);
+    return { path, branch, created: true, base };
+  }
+
+  /** The remote head of the default branch (`origin/HEAD`, fetched first), so a Workspace starts
+   * from what is merged rather than from whatever the main checkout happens to have checked out.
+   * A repository with no remote starts from its own HEAD. */
+  private async defaultBase(): Promise<string> {
+    let hasOrigin = false;
+    try {
+      await this.git(["remote", "get-url", "origin"], this.repoRoot);
+      hasOrigin = true;
+    } catch {
+      /* no remote named origin */
+    }
+    if (!hasOrigin) return "HEAD";
+    try {
+      await this.git(["fetch", "--quiet", "origin"], this.repoRoot);
+    } catch (error) {
+      this.log(`workspace: fetch failed, using the last known remote head (${(error as Error).message})`);
+    }
+    const branch = await defaultBranchOf(this.git, this.repoRoot);
+    return branch ? `origin/${branch}` : "HEAD";
+  }
+
+  /** Whether `path` is itself the root of a worktree. `--is-inside-work-tree` alone would also say
+   * yes for a plain directory left under some enclosing repository (a home directory tracked as
+   * dotfiles, a root pointed inside the checkout), and a Worker would then commit into that. */
+  private async isWorktree(path: string): Promise<boolean> {
+    try {
+      const top = await this.git(["rev-parse", "--show-toplevel"], path);
+      return realpathSync(top) === realpathSync(path);
+    } catch {
+      return false;
+    }
+  }
+
+  private branchExists(branch: string): Promise<boolean> {
+    return this.refExists(`refs/heads/${branch}`);
+  }
+
+  private async refExists(ref: string): Promise<boolean> {
+    try {
+      await this.git(["rev-parse", "--verify", "--quiet", ref], this.repoRoot);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/** The root of the repository containing `dir`, or undefined when `dir` is not in one. */
+export async function repoRootOf(dir: string, git: GitRunner = runGit): Promise<string | undefined> {
+  try {
+    return await git(["rev-parse", "--show-toplevel"], dir);
+  } catch {
+    return undefined;
+  }
+}

package/src/foreman/fake-handoff.ts

@@ -0,0 +1,33 @@
+import type { HandOffFn, HandOffInput, HandOffResult } from "./core/handoff.js";
+
+/**
+ * A Hand-off for the Run loop's tests: records what it was asked and, unless told otherwise, hands
+ * back a numbered draft pull request on the fake Tracker's repository, the way core/handoff.ts
+ * would after a real push. No git, no code host.
+ */
+export function fakeHandOff(result?: (input: HandOffInput, n: number) => HandOffResult) {
+  const handOffs: HandOffInput[] = [];
+  const handOff: HandOffFn = async (input) => {
+    handOffs.push(input);
+    const n = handOffs.length;
+    if (result) return result(input, n);
+    return {
+      kind: "handed_off",
+      pullRequest: {
+        number: n,
+        url: `https://remote.example/opsee/monorepo/-/merge_requests/${n}`,
+        title: `${input.task.identifier}: ${input.task.title}`,
+        draft: true,
+        headBranch: input.workspace.branch,
+        baseBranch: "development",
+      },
+      headSha: `sha-${input.workspace.branch}`,
+      baseBranch: "development",
+      repositoryFullName: "opsee/monorepo",
+      reused: false,
+      adopted: false,
+      commits: 1,
+    };
+  };
+  return { handOff, handOffs };
+}

package/src/foreman/fake-learnings.ts

@@ -0,0 +1,26 @@
+import type { LearningsFn, LearningsInput, LearningsResult } from "./core/learnings.js";
+
+/**
+ * A learnings step for the Run loop's tests: records what it was asked and, unless told otherwise,
+ * answers the way core/learnings.ts would after a real push: `none` for an empty batch, else a
+ * draft pull request numbered after the batch. No git, no code host.
+ */
+export function fakeLearnings(result?: (input: LearningsInput, n: number) => LearningsResult) {
+  const batches: LearningsInput[] = [];
+  const learnings: LearningsFn = async (input) => {
+    batches.push(input);
+    const n = batches.length;
+    if (result) return result(input, n);
+    if (input.learnings.length === 0) return { kind: "none" };
+    const branch = `foreman/learnings-${input.initiativeId}-batch${n}`;
+    return {
+      kind: "opened",
+      pullRequest: { number: 100 + n, url: `https://remote.example/opsee/monorepo/-/merge_requests/${100 + n}`, title: `Foreman: Proposed Learnings for Initiative ${input.initiativeId}`, draft: true, headBranch: branch, baseBranch: "development" },
+      count: input.learnings.length,
+      file: "docs/learnings.md",
+      branch,
+      headSha: `sha-${branch}`,
+    };
+  };
+  return { learnings, batches };
+}

package/src/foreman/fake-remote-api.ts

@@ -0,0 +1,70 @@
+import { basename } from "node:path";
+import type { Attachment, NewPullRequest, PullRequestPatch, RemoteApi, RemotePullRequest } from "./remote-api.js";
+
+/**
+ * An in-memory code host for the Foreman's tests: keeps the draft pull requests it opened, finds
+ * them by branch, and records every call in order so a test can assert that a Hand-off reused a
+ * pull request rather than opening a second one, and keeps the comments left on each. Like the
+ * seam it implements, it cannot merge.
+ */
+export class FakeRemoteApi implements RemoteApi {
+  readonly pullRequests = new Map<number, RemotePullRequest & { body: string }>();
+  /** Comments by pull request number, in the order they were added. */
+  readonly comments = new Map<number, string[]>();
+  /** Files uploaded for a pull request, by number, in order: the local path and the URL given. */
+  readonly uploads = new Map<number, Array<{ path: string; url: string }>>();
+  readonly calls: string[] = [];
+  private nextNumber = 1;
+  private nextUpload = 1;
+
+  constructor(private readonly fullName = "opsee/monorepo") {}
+
+  async findPullRequest(headBranch: string): Promise<RemotePullRequest | undefined> {
+    this.calls.push(`find ${headBranch}`);
+    const hit = [...this.pullRequests.values()].find((pr) => pr.headBranch === headBranch);
+    return hit ? strip(hit) : undefined;
+  }
+
+  async findPullRequestByTitle(title: string): Promise<RemotePullRequest | undefined> {
+    this.calls.push(`find-title ${title}`);
+    const hit = [...this.pullRequests.values()].find((pr) => pr.title === title);
+    return hit ? strip(hit) : undefined;
+  }
+
+  async openDraftPullRequest(input: NewPullRequest): Promise<RemotePullRequest> {
+    this.calls.push(`open ${input.headBranch} -> ${input.baseBranch}`);
+    const number = this.nextNumber++;
+    const pr = { number, url: `https://remote.example/${this.fullName}/-/merge_requests/${number}`, title: input.title, draft: true, headBranch: input.headBranch, baseBranch: input.baseBranch, body: input.body };
+    this.pullRequests.set(number, pr);
+    return strip(pr);
+  }
+
+  async updatePullRequest(number: number, patch: PullRequestPatch): Promise<RemotePullRequest> {
+    this.calls.push(`update ${number}`);
+    const pr = this.pullRequests.get(number);
+    if (!pr) throw new Error(`No pull request ${number}`);
+    pr.title = patch.title;
+    pr.body = patch.body;
+    return strip(pr);
+  }
+
+  async addPullRequestComment(number: number, body: string): Promise<void> {
+    this.calls.push(`comment ${number}`);
+    if (!this.pullRequests.has(number)) throw new Error(`No pull request ${number}`);
+    this.comments.set(number, [...(this.comments.get(number) ?? []), body]);
+  }
+
+  /** Behaves like GitLab: every file gets a URL and the markdown that embeds it. */
+  async uploadAttachment(number: number, filePath: string): Promise<Attachment> {
+    this.calls.push(`upload ${number} ${basename(filePath)}`);
+    if (!this.pullRequests.has(number)) throw new Error(`No pull request ${number}`);
+    const name = basename(filePath);
+    const url = `https://remote.example/${this.fullName}/uploads/${this.nextUpload++}/${name}`;
+    this.uploads.set(number, [...(this.uploads.get(number) ?? []), { path: filePath, url }]);
+    return { url, markdown: `![${name}](${url})` };
+  }
+}
+
+function strip({ body: _body, ...pr }: RemotePullRequest & { body: string }): RemotePullRequest {
+  return pr;
+}