mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-ops.js

@@ -1,361 +0,0 @@
-/**
- * lib/orchestration/epic-spec-reconciler-ops.js — operation types + plan shape
- * for the epic-spec reconciler diff engine.
- *
- * Story #3302: `createOp` must serialize object bodies via `story-body.js`
- * rather than blind-coercing them with `String()`. See `createOp` for the
- * serialize-or-throw contract.
- *
- * Coverage note: the pure factories and plan utilities in this module are
- * exercised by `tests/story-3302-body-shape.test.js`. The one genuinely
- * untestable branch is the `createOp` serialize catch-rethrow path — it
- * requires `serialize()` to throw on a plain object, which the library
- * contract does not support (serialize only throws on non-object inputs, and
- * those are excluded by the `typeof rawBody === 'object'` guard above); the
- * branch is annotated with a surgical `node:coverage ignore` below.
- *
- * Owns the typed shapes that flow through the structural reconciler (Epic
- * #1182 / Tech Spec #1483 / Story #1492). The diff engine produces these
- * shapes from `(spec, state, ghState)`; the apply engine consumes them.
- * Both are intentionally I/O-free — operation objects are inert plain
- * data so plans can be hashed, serialised, dry-run-rendered, and round-
- * tripped through fixtures without provider involvement.
- *
- * ## Operation kinds
- *
- *   - `create`  — spec carries a slug that is not yet mapped to a GH
- *                 issue. The apply engine will materialise it.
- *   - `update`  — spec slug ↔ GH issue is mapped, but the structural
- *                 content (title/body/labels) drifted. Carries `before`
- *                 + `after` for the changed fields only; unchanged
- *                 fields are omitted.
- *   - `close`   — state mapping points at a GH issue whose slug no
- *                 longer appears in the spec. Apply will close the
- *                 issue (subject to the close-discriminator at apply
- *                 time — orphan-vs-drift is decided there, not in diff).
- *   - `relink`  — parent or `dependsOn` edges changed for a slug whose
- *                 mapping is otherwise stable. Carries the old and new
- *                 edge sets so apply can rewrite `blocked by` references.
- *
- * ## Plan shape
- *
- * `Plan` groups operations by kind into four arrays. This is the canonical
- * shape returned by `diff()` and consumed by `formatPlan()` and the
- * apply pipeline. Arrays are always present (never undefined); an empty
- * plan has all four arrays at length 0.
- *
- * @typedef {'epic'|'story'} EntityKind
- *   The structural entity kind. Matches schema $defs — agent-execution
- *   labels (agent::*) are owned by the wave-runner and never appear in
- *   the structural surface.
- *
- * @typedef {object} CreateOp
- * @property {'create'} kind
- * @property {string}   slug      Stable kebab-case identifier from spec.
- * @property {EntityKind} entity  Which structural level the op acts on.
- * @property {string}   title     Spec-side title (becomes the GH title).
- * @property {string}  [body]     Spec-side body when present.
- * @property {string[]}[labels]   Structural labels (no agent::*).
- * @property {string}  [parentSlug] Slug of the parent feature/story (for
- *                                  features/stories/tasks). Omitted for
- *                                  the epic-level op (epic has no parent).
- * @property {string[]}[dependsOn]  Sibling-story slugs the new Story
- *                                  depends on (stories only).
- * @property {number}  [wave]      Wave number (stories only).
- *
- * @typedef {object} UpdateFieldChange
- * @property {unknown} before
- * @property {unknown} after
- *
- * @typedef {object} UpdateOp
- * @property {'update'} kind
- * @property {string}   slug
- * @property {EntityKind} entity
- * @property {number}   issueNumber  Mapped GH issue number (from state).
- * @property {Record<string, UpdateFieldChange>} changes
- *   Only the changed fields appear here. Keys are `'title'|'body'|'labels'`
- *   (and `'wave'` for stories). `before` / `after` carry the prior + new
- *   values; for `labels` they are sorted string arrays.
- *
- * @typedef {object} CloseOp
- * @property {'close'} kind
- * @property {string}  slug         Slug from state (no longer in spec).
- * @property {EntityKind} entity    Entity kind from state mapping.
- * @property {number}  issueNumber  Mapped GH issue number to close.
- * @property {string} [title]       Last-known title (for human output).
- *
- * @typedef {object} RelinkOp
- * @property {'relink'} kind
- * @property {string}   slug
- * @property {EntityKind} entity     'story' (dependsOn / parent).
- * @property {number}   issueNumber
- * @property {{ before: string|null, after: string|null }} [parent]
- *   Parent slug change. `null` on either side means "no parent" (epic
- *   root). Omitted when the parent edge is unchanged.
- * @property {{ before: string[], after: string[] }} [dependsOn]
- *   Sibling-story slug list change (stories only). Both arrays are sorted
- *   so equality is order-independent. Omitted when the edge set is
- *   unchanged.
- *
- * @typedef {object} Plan
- * @property {CreateOp[]} creates
- * @property {UpdateOp[]} updates
- * @property {CloseOp[]}  closes
- * @property {RelinkOp[]} relinks
- */
-
-import { StoryBodyParseError, serialize } from '../story-body/story-body.js';
-
-/** Operation kind discriminator values. Exported for use by tests + apply. */
-export const OP_KINDS = Object.freeze({
-  CREATE: 'create',
-  UPDATE: 'update',
-  CLOSE: 'close',
-  RELINK: 'relink',
-});
-
-/** Entity-kind discriminator values, matching the schema $defs. */
-export const ENTITY_KINDS = Object.freeze({
-  EPIC: 'epic',
-  STORY: 'story',
-});
-
-const VALID_OP_KINDS = new Set(Object.values(OP_KINDS));
-const VALID_ENTITY_KINDS = new Set(Object.values(ENTITY_KINDS));
-
-/**
- * Internal helper — assert non-empty slug. Throws so test failures point
- * at the constructor argument rather than surfacing later as a silent
- * "slug: undefined" in formatted output.
- *
- * @param {unknown} slug
- * @returns {string}
- */
-function requireSlug(slug) {
-  if (typeof slug !== 'string' || slug.length === 0) {
-    throw new TypeError(
-      `operation slug must be a non-empty string (got ${String(slug)})`,
-    );
-  }
-  return slug;
-}
-
-/**
- * Internal helper — assert entity kind belongs to the structural set.
- *
- * @param {unknown} entity
- * @returns {EntityKind}
- */
-function requireEntity(entity) {
-  if (!VALID_ENTITY_KINDS.has(/** @type {string} */ (entity))) {
-    throw new TypeError(`unknown entity kind: ${String(entity)}`);
-  }
-  return /** @type {EntityKind} */ (entity);
-}
-
-/**
- * Construct a `CreateOp`. Tests build plans declaratively via this
- * factory so the inert-data shape never drifts from the typedef.
- *
- * @param {{slug: string, entity: EntityKind, title: string, body?: string,
- *          labels?: string[], parentSlug?: string, dependsOn?: string[], wave?: number}} input
- * @returns {CreateOp}
- */
-export function createOp(input) {
-  const op = {
-    kind: OP_KINDS.CREATE,
-    slug: requireSlug(input?.slug),
-    entity: requireEntity(input?.entity),
-    title: String(input?.title ?? ''),
-  };
-  if (input.body !== undefined) {
-    // Story #3302: never blind-coerce body with String(). An object body
-    // must be serialized via story-body.js so the caller gets the canonical
-    // markdown string rather than "[object Object]". A non-string,
-    // non-object value is still coerced (e.g. null, undefined are already
-    // gated above by the `!== undefined` check at this branch's entrance).
-    const rawBody = input.body;
-    if (rawBody !== null && typeof rawBody === 'object') {
-      try {
-        op.body = serialize(rawBody);
-        /* node:coverage ignore next 7 -- serialize() only throws on non-object
-           inputs; the rawBody guard above (`typeof rawBody === 'object'`) already
-           excludes every value that could make serialize() throw, so this catch
-           branch is unreachable in practice. It is kept as a defensive wrapper
-           for hypothetical future serialize contract changes. */
-      } catch (err) {
-        // Re-throw with extra context so callers know which op triggered
-        // the serialization failure. StoryBodyParseError is already
-        // informative; any other error gets wrapped.
-        throw new StoryBodyParseError(
-          `createOp: body for slug "${input?.slug}" is an object but could not be serialized: ${err.message}`,
-          { field: 'body', raw: JSON.stringify(rawBody).slice(0, 200) },
-        );
-      }
-    } else {
-      op.body = String(rawBody);
-    }
-  }
-  if (input.labels !== undefined) op.labels = [...input.labels].sort();
-  if (input.parentSlug !== undefined) op.parentSlug = String(input.parentSlug);
-  if (input.dependsOn !== undefined) op.dependsOn = [...input.dependsOn].sort();
-  if (input.wave !== undefined) op.wave = Number(input.wave);
-  return op;
-}
-
-/**
- * Construct an `UpdateOp`. `changes` keys are normalised to the closed
- * field set the reconciler is allowed to touch (`title|body|labels|wave`).
- *
- * @param {{slug: string, entity: EntityKind, issueNumber: number,
- *          changes: Record<string, UpdateFieldChange>}} input
- * @returns {UpdateOp}
- */
-export function updateOp(input) {
-  const changes = {};
-  for (const [key, value] of Object.entries(input?.changes ?? {})) {
-    if (!value || !('before' in value) || !('after' in value)) {
-      throw new TypeError(
-        `updateOp change[${key}] must carry { before, after }`,
-      );
-    }
-    changes[key] = { before: value.before, after: value.after };
-  }
-  return {
-    kind: OP_KINDS.UPDATE,
-    slug: requireSlug(input?.slug),
-    entity: requireEntity(input?.entity),
-    issueNumber: Number(input?.issueNumber),
-    changes,
-  };
-}
-
-/**
- * Construct a `CloseOp`.
- *
- * @param {{slug: string, entity: EntityKind, issueNumber: number, title?: string}} input
- * @returns {CloseOp}
- */
-export function closeOp(input) {
-  const op = {
-    kind: OP_KINDS.CLOSE,
-    slug: requireSlug(input?.slug),
-    entity: requireEntity(input?.entity),
-    issueNumber: Number(input?.issueNumber),
-  };
-  if (input.title !== undefined) op.title = String(input.title);
-  return op;
-}
-
-/**
- * Construct a `RelinkOp`. At least one of `parent` / `dependsOn` must be
- * present — a relink with no edges changed is meaningless and almost
- * certainly a diff bug, so we reject it loudly.
- *
- * @param {{slug: string, entity: EntityKind, issueNumber: number,
- *          parent?: {before: string|null, after: string|null},
- *          dependsOn?: {before: string[], after: string[]}}} input
- * @returns {RelinkOp}
- */
-export function relinkOp(input) {
-  if (!input?.parent && !input?.dependsOn) {
-    throw new TypeError(
-      'relinkOp requires at least one of { parent, dependsOn } to be set',
-    );
-  }
-  const op = {
-    kind: OP_KINDS.RELINK,
-    slug: requireSlug(input?.slug),
-    entity: requireEntity(input?.entity),
-    issueNumber: Number(input?.issueNumber),
-  };
-  if (input.parent) {
-    op.parent = {
-      before: input.parent.before == null ? null : String(input.parent.before),
-      after: input.parent.after == null ? null : String(input.parent.after),
-    };
-  }
-  if (input.dependsOn) {
-    op.dependsOn = {
-      before: [...input.dependsOn.before].sort(),
-      after: [...input.dependsOn.after].sort(),
-    };
-  }
-  return op;
-}
-
-/**
- * Build an empty `Plan` — every array length 0. Exported because the
- * diff engine and tests both want the same canonical zero value.
- *
- * @returns {Plan}
- */
-export function emptyPlan() {
-  return { creates: [], updates: [], closes: [], relinks: [] };
-}
-
-/**
- * Type-guard / runtime narrowing — true when `value` looks like a valid
- * `Plan`. Used by `formatPlan` so the formatter can reject malformed
- * inputs with a structured error rather than crashing on `.map`.
- *
- * @param {unknown} value
- * @returns {value is Plan}
- */
-export function isPlan(value) {
-  if (!value || typeof value !== 'object') return false;
-  const p = /** @type {Record<string, unknown>} */ (value);
-  return (
-    Array.isArray(p.creates) &&
-    Array.isArray(p.updates) &&
-    Array.isArray(p.closes) &&
-    Array.isArray(p.relinks)
-  );
-}
-
-/**
- * Total operation count across all kinds in a plan. Handy for callers
- * that just want to know "is anything happening?" without inspecting
- * each bucket.
- *
- * @param {Plan} plan
- * @returns {number}
- */
-export function planSize(plan) {
-  if (!isPlan(plan)) return 0;
-  return (
-    plan.creates.length +
-    plan.updates.length +
-    plan.closes.length +
-    plan.relinks.length
-  );
-}
-
-/**
- * True when a plan carries no operations — used by callers (CLI,
- * dry-run output) to short-circuit on the idempotent no-op case.
- *
- * @param {Plan} plan
- * @returns {boolean}
- */
-export function isEmptyPlan(plan) {
-  return planSize(plan) === 0;
-}
-
-/**
- * True for any value that conforms to one of the four operation shapes.
- * Used by tests + formatter validation.
- *
- * @param {unknown} value
- * @returns {boolean}
- */
-export function isOperation(value) {
-  if (!value || typeof value !== 'object') return false;
-  const op = /** @type {Record<string, unknown>} */ (value);
-  return (
-    typeof op.kind === 'string' &&
-    VALID_OP_KINDS.has(op.kind) &&
-    typeof op.slug === 'string' &&
-    VALID_ENTITY_KINDS.has(/** @type {string} */ (op.entity))
-  );
-}

package/.agents/scripts/lib/orchestration/finalize/open-or-locate-pr.js

@@ -1,306 +0,0 @@
-// .agents/scripts/lib/orchestration/finalize/open-or-locate-pr.js
-/**
- * open-or-locate-pr.js — finalize helper that opens the Epic→main pull
- * request, or locates the existing one when finalize is replaying after
- * a crash between `gh pr create` and the `pr.created` emit.
- *
- * Extracted from `/deliver` Phase 7.1 prose so the lifecycle
- * Finalizer listener has a single async helper that returns the
- * `{ prNumber, url, created }` envelope it needs to compose
- * downstream emits.
- *
- * Story #2894 / Task #2908 (Epic #2880).
- *
- * Implementation: two `gh` shells.
- *
- *   1. Probe — `gh pr list --head <head> --json number,url --jq '.[0]'`.
- *      Returns the first open PR on the head branch (idempotent locate).
- *      If one exists, the helper returns `{ created: false, … }` with
- *      the existing PR's number + URL.
- *   2. Create — `gh pr create --base <base> --head <head>
- *      --title <title> --body <body>`. The stdout of `gh pr create` is
- *      the raw html_url; we follow up with `gh pr view <url>
- *      --json number,url` to harvest the canonical numeric id + api url.
- *
- * The probe/create split is what makes the helper safe to call twice on
- * the same head branch: the second call short-circuits at the probe and
- * does not attempt to create a duplicate PR. This is the AC-10
- * idempotency contract the Finalizer relies on for cross-process
- * re-runs of `/deliver`.
- *
- * Early-PR draft mode — Story #4359 (Epic #4355).
- *
- *   When `delivery.ci.earlyPr` is on (the default), `/deliver` opens the
- *   Epic PR as a **draft** at wave 1 (`openOrLocatePr({ draft: true })`)
- *   so every subsequent per-wave push runs CI attributed to its own wave.
- *   The `draft` flag only appends `--draft` to the `gh pr create` shell —
- *   the probe/locate path is unchanged, so a re-run on the same head
- *   branch still short-circuits without opening a duplicate. Phase 7 then
- *   flips that existing draft to ready-for-review via `markPrReady` rather
- *   than creating the PR. When `earlyPr` is off, no draft is opened at
- *   wave 1 and Phase 7 opens the PR at close time exactly as before
- *   (`openOrLocatePr` with no `draft`). The title/body contract
- *   (`feat: Epic #<id>` / `Closes #<id>`) is identical in both modes.
- */
-
-import { spawnSync } from 'node:child_process';
-
-import { sanitizeSkipCiMarkers } from './sanitize-skip-ci.js';
-
-/**
- * Default `gh` invocation — matches the `shell: false` contract the
- * other listener helpers (`ghPrListHead`, `ghPrViewAutoMerge`) use so a
- * future Windows audit doesn't have to grep across modules.
- *
- * @param {{ args: string[], cwd?: string, input?: string, spawnFn?: typeof spawnSync }} opts
- */
-export function defaultGhSpawn({ args, cwd, input, spawnFn = spawnSync }) {
-  const result = spawnFn('gh', args, {
-    cwd,
-    encoding: 'utf-8',
-    shell: false,
-    input,
-  });
-  return {
-    status: result.status ?? 1,
-    stdout: result.stdout ?? '',
-    stderr: result.stderr ?? '',
-  };
-}
-
-/**
- * Parse `gh pr list --head <branch> --json number,url --jq '.[0]'` into
- * a `{ number, url }` envelope or `null`. Pure helper — exported for
- * tests so the parse regex is explicit and reviewable.
- *
- * Accepts:
- *   - empty / whitespace stdout (no PR on the head branch)
- *   - JSON object form `{"number":7,"url":"…"}`
- *   - JSON array form `[{"number":7,"url":"…"}]` (when `--jq` is absent)
- */
-export function parsePrListResult(stdout) {
-  const trimmed = String(stdout || '').trim();
-  if (trimmed.length === 0) return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch {
-    return null;
-  }
-  const candidate = Array.isArray(parsed) ? parsed[0] : parsed;
-  if (!candidate || typeof candidate !== 'object') return null;
-  const num = Number(candidate.number);
-  const url = typeof candidate.url === 'string' ? candidate.url : null;
-  if (!Number.isInteger(num) || num <= 0 || !url) return null;
-  return { number: num, url };
-}
-
-/**
- * Parse `gh pr view <url> --json number,url` into `{ number, url }`.
- * Used to canonicalise the `gh pr create` stdout (which is just the
- * html_url string) into the listener's `{ prNumber, url }` envelope.
- */
-export function parsePrViewResult(stdout) {
-  const trimmed = String(stdout || '').trim();
-  if (trimmed.length === 0) return null;
-  let parsed;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch {
-    return null;
-  }
-  if (!parsed || typeof parsed !== 'object') return null;
-  const num = Number(parsed.number);
-  const url = typeof parsed.url === 'string' ? parsed.url : null;
-  if (!Number.isInteger(num) || num <= 0 || !url) return null;
-  return { number: num, url };
-}
-
-/**
- * Open the Epic→base PR (or locate the existing one). Returns
- * `{ prNumber, url, created }`.
- *
- * @param {object} args
- * @param {number} args.epicId — Epic ticket id. Used to compose the
- *   default title and the `Closes #<epicId>` body trailer.
- * @param {string} args.headBranch — feature branch (typically
- *   `epic/<epicId>`).
- * @param {string} [args.baseBranch] — base branch. Default `main`.
- * @param {string} [args.title] — explicit PR title override; defaults
- *   to the Conventional Commit form `feat: Epic #<epicId>` so the
- *   squash-merge subject on `main` parses cleanly for release-please
- *   (a non-conventional subject is ignored, producing no version bump
- *   or changelog entry).
- * @param {string} [args.body] — explicit PR body override; defaults to
- *   `Closes #<epicId>`.
- * @param {boolean} [args.draft] — when `true`, open the new PR as a draft
- *   (`gh pr create --draft`). Story #4359: the early-PR path opens the
- *   Epic PR as a draft at wave 1 so per-wave pushes warm CI; Phase 7 later
- *   flips it ready via `markPrReady`. Only affects the create path — the
- *   locate short-circuit never inspects draft state, so a re-run stays
- *   idempotent. Default `false`.
- * @param {string} [args.cwd] — working directory for the gh shells.
- *   Default `process.cwd()`.
- * @param {Function} [args.ghSpawn] — override the gh invocation for
- *   tests. Same shape as `defaultGhSpawn`.
- * @returns {Promise<{ prNumber: number, url: string, created: boolean }>}
- */
-export async function openOrLocatePr({
-  epicId,
-  headBranch,
-  baseBranch = 'main',
-  title,
-  body,
-  draft = false,
-  cwd = process.cwd(),
-  ghSpawn = defaultGhSpawn,
-} = {}) {
-  if (!Number.isInteger(epicId) || epicId < 1) {
-    throw new TypeError('openOrLocatePr: epicId must be a positive integer');
-  }
-  if (typeof headBranch !== 'string' || headBranch.length === 0) {
-    throw new TypeError(
-      'openOrLocatePr: headBranch must be a non-empty string',
-    );
-  }
-  if (typeof baseBranch !== 'string' || baseBranch.length === 0) {
-    throw new TypeError(
-      'openOrLocatePr: baseBranch must be a non-empty string',
-    );
-  }
-
-  // 1. Probe — locate any existing open PR on the head branch.
-  const probe = ghSpawn({
-    args: [
-      'pr',
-      'list',
-      '--head',
-      headBranch,
-      '--state',
-      'open',
-      '--json',
-      'number,url',
-      '--jq',
-      '.[0]',
-    ],
-    cwd,
-  });
-  if (probe.status === 0) {
-    const existing = parsePrListResult(probe.stdout);
-    if (existing) {
-      return { prNumber: existing.number, url: existing.url, created: false };
-    }
-  } else {
-    throw new Error(
-      `openOrLocatePr: gh pr list failed (status=${probe.status}): ${probe.stderr.trim()}`,
-    );
-  }
-
-  // 2. Create — open the PR.
-  // Default to the Conventional Commit form so the squash-merge subject
-  // on `main` (PR title + `(#<pr>)`) parses for release-please. A bare
-  // `Epic #<id>` subject carries no conventional type, so release-please
-  // skips it — no version bump, no changelog entry.
-  const finalTitle =
-    typeof title === 'string' && title.length > 0
-      ? title
-      : `feat: Epic #${epicId}`;
-  // Story #3165: strip any `[skip ci]` / `[ci skip]` / `[no ci]` /
-  // `[skip actions]` / `[actions skip]` markers from the body before
-  // handing it to `gh pr create`. Default body (`Closes #<epicId>`)
-  // never contains them, but a caller-supplied body could carry the
-  // markers in from upstream tooling — and any text that survives
-  // into the squash commit body suppresses CI + release-please on
-  // `main`.
-  const rawBody =
-    typeof body === 'string' && body.length > 0 ? body : `Closes #${epicId}`;
-  const finalBody = sanitizeSkipCiMarkers(rawBody);
-  const create = ghSpawn({
-    args: [
-      'pr',
-      'create',
-      '--base',
-      baseBranch,
-      '--head',
-      headBranch,
-      '--title',
-      finalTitle,
-      '--body',
-      finalBody,
-      // Story #4359: open as a draft when the early-PR path requests it.
-      // The flag is elided entirely when `draft` is false so the
-      // close-time (earlyPr=false) create path is byte-identical to the
-      // pre-Story behaviour.
-      ...(draft ? ['--draft'] : []),
-    ],
-    cwd,
-  });
-  if (create.status !== 0) {
-    throw new Error(
-      `openOrLocatePr: gh pr create failed (status=${create.status}): ${create.stderr.trim()}`,
-    );
-  }
-  const htmlUrl = create.stdout.trim();
-  if (htmlUrl.length === 0) {
-    throw new Error(
-      'openOrLocatePr: gh pr create returned empty stdout — cannot resolve PR number',
-    );
-  }
-
-  // 3. View — canonicalise into `{ number, url }`.
-  const view = ghSpawn({
-    args: ['pr', 'view', htmlUrl, '--json', 'number,url'],
-    cwd,
-  });
-  if (view.status !== 0) {
-    throw new Error(
-      `openOrLocatePr: gh pr view failed (status=${view.status}): ${view.stderr.trim()}`,
-    );
-  }
-  const parsed = parsePrViewResult(view.stdout);
-  if (!parsed) {
-    throw new Error(
-      `openOrLocatePr: gh pr view returned unparseable JSON: ${view.stdout.trim()}`,
-    );
-  }
-  return { prNumber: parsed.number, url: parsed.url, created: true };
-}
-
-/**
- * Mark an existing draft PR as ready-for-review — Story #4359 (Epic
- * #4355). This is the Phase-7 counterpart to the wave-1 draft open: when
- * `delivery.ci.earlyPr` is on, the Epic PR already exists as a draft, so
- * finalize flips it ready rather than creating a PR.
- *
- * Idempotent: `gh pr ready` on an already-ready PR is a no-op that exits
- * 0, so re-running finalize (or replaying after a crash) is safe. When the
- * PR reference does not resolve, `gh` exits non-zero and this helper
- * throws with the stderr detail.
- *
- * @param {object} args
- * @param {string} args.pr — a PR reference `gh pr ready` accepts: the
- *   numeric id, the branch name, or the html URL. `openOrLocatePr`
- *   returns both `prNumber` and `url`; either is a valid input.
- * @param {string} [args.cwd] — working directory for the gh shell.
- *   Default `process.cwd()`.
- * @param {Function} [args.ghSpawn] — override the gh invocation for
- *   tests. Same shape as `defaultGhSpawn`.
- * @returns {Promise<{ pr: string, ready: true }>}
- */
-export async function markPrReady({
-  pr,
-  cwd = process.cwd(),
-  ghSpawn = defaultGhSpawn,
-} = {}) {
-  const ref = pr == null ? '' : String(pr).trim();
-  if (ref.length === 0) {
-    throw new TypeError('markPrReady: pr must be a non-empty reference');
-  }
-  const ready = ghSpawn({ args: ['pr', 'ready', ref], cwd });
-  if (ready.status !== 0) {
-    throw new Error(
-      `markPrReady: gh pr ready failed (status=${ready.status}): ${ready.stderr.trim()}`,
-    );
-  }
-  return { pr: ref, ready: true };
-}