@bluewombat/slots 0.9.0 → 0.10.0

package/builders/e2e.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import {
+  BUILDER_FLAGS,
+  emitFailure,
+  fillPrompt,
+  finishRun,
+  loadPrompt,
+  loadRules,
+  PROMPT_RULES,
+  parseRole,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+import { attemptOf } from "../lib/fill.mjs";
+
+// The Ticket that holds a Feature's e2e acceptance suite. One command for its first pass and for
+// a pass a Gate refused: the suite is written once from the scenarios of the task, and a refusal
+// is about its form, so there is no second command to tell apart. `{{report}}` and
+// `{{refused_by}}` are empty on a first pass; `{{refusal}}` is a ready-made paragraph about them.
+
+const NAME = "builder e2e";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+You write the acceptance suite of a feature. The task below lists its scenarios, agreed with the
+operator before development, each with an id (E1, E2, ...).
+
+Task:
+{{task}}
+
+- Write one test per scenario, in the end-to-end framework this project already uses, and
+  start the name of each test with its scenario id ("E1 …"). Follow the scenario's steps and
+  expected result as written; do not add, merge or drop one.
+- List the ids in the manifest \`e2e/scenarios.json\`, a JSON array: ["E1", "E2"].
+- Write only inside the suite folder (\`e2e/\`). Touch no file of the application, and add no
+  dependency it does not already have.
+- The feature is not finished here and the application is not started: do not run the suite. Check
+  only that it compiles, with the project's own typecheck or build command.
+
+{{refusal}}
+
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (a scenario is ambiguous, the framework is missing,
+the cause is outside this directory), do not invent a change. Change nothing and end your final
+message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
+Rules of this run:
+{{rules}}
+`;
+
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (intention.length === 0) {
+  emitFailure("fail-blocking", "The Builder received no --intention.");
+  process.exit(1);
+}
+
+const parsed = parseRole(process.argv, BUILDER_FLAGS, NAME);
+if (!parsed.ok) {
+  emitFailure("fail-blocking", parsed.reason);
+  process.exit(1);
+}
+
+const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
+if (!template.ok) {
+  emitFailure("fail-blocking", template.reason);
+  process.exit(1);
+}
+const rules = loadRules(parsed.options, PROMPT_RULES);
+if (!rules.ok) {
+  emitFailure("fail-blocking", rules.reason);
+  process.exit(1);
+}
+
+const report = (take(process.argv, "--report") ?? "").trim();
+const refusedBy = (take(process.argv, "--report-from") ?? "").trim();
+const refusal =
+  report.length === 0
+    ? ""
+    : [
+        "What is in this directory is what an earlier attempt left. It was refused",
+        `${refusedBy.length > 0 ? `by ${refusedBy}` : "by a check"}:`,
+        "",
+        "```raw",
+        report,
+        "```",
+        "",
+        "Resolve that, change what it takes and nothing more.",
+      ].join("\n");
+
+const rendered = fillPrompt(
+  template.value,
+  {
+    task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
+    refusal,
+    report,
+    refused_by: refusedBy,
+    rules: rules.value.trim(),
+    id: take(process.argv, "--id") ?? "",
+    attempt: String(attemptOf(process.argv)),
+  },
+  ["task", "rules"],
+  textOption(parsed.options, "promptFile") ?? "built-in template",
+);
+if (!rendered.ok) {
+  emitFailure("fail-blocking", rendered.reason);
+  process.exit(1);
+}
+
+const spawned = await spawnFilled(parsed.runner, rendered.prompt, transcriptArgs(process.argv));
+if (!spawned.ok) {
+  emitFailure("fail-blocking", spawned.reason);
+  process.exit(1);
+}
+finishRun({ run: spawned.run, bin: spawned.about.bin, name: spawned.about.name });

package/builders/producer.mjs

@@ -25,6 +25,10 @@ Task:
 This checkout is the project as it stands. Add or change only what this task
 names, and leave the project's own checks green on the whole tree.
 
+When the latest commit of this checkout is titled "Tests: …", the tests of this task were
+written before the code and committed. They are the specification: make them pass as they
+are. Do not edit, delete or rename them.
+
 {{history}}
 
 ## When you cannot act

package/builders/repair.mjs

@@ -38,6 +38,10 @@ This was asked in the first place, and still holds:
 
 {{task}}
 
+When the latest commit of this checkout is titled "Tests: …", the tests of this task were
+written before the code and committed. They are the specification: make them pass as they
+are. Do not edit, delete or rename them.
+
 {{history}}
 
 ## When you cannot act

package/builders/tests.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import {
+  BUILDER_FLAGS,
+  emitFailure,
+  fillPrompt,
+  finishRun,
+  loadPrompt,
+  loadRules,
+  PROMPT_RULES,
+  parseRole,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+import { attemptOf } from "../lib/fill.mjs";
+
+const NAME = "builder tests";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+Task:
+{{task}}
+
+YOUR WORK NOW IS TO WRITE THE TESTS OF THIS TASK, AND ONLY THE TESTS. Another agent
+writes the code afterwards and must make your tests pass without editing them. A test it
+cannot pass is not sent back to you: it stops the task and waits for a person. So a test
+you deliver must be one that a correct implementation of the task passes, and you prove
+it before you hand it over (see below).
+
+## The cases
+
+- The task has a "Tests" section: write one test per case of it, in the file and the
+  framework it names (or the ones this repository already uses), each named after the
+  case it covers. Test the behaviour at the seam the section names, not how it is built.
+- The task has no "Tests" section: do not look for one elsewhere. Derive the cases from
+  its acceptance criteria ("Done when" or the like), one case per criterion, and name each
+  test after the criterion and the identifiers it carries. A criterion that describes two
+  sets of data (sixty rows for a page, more than a cap for the cap) is two cases, never one
+  test with two batches of data.
+- Do not write the behaviour. If the interface under test does not exist yet, create the
+  minimal stub — the name and signature the task gives, a body that does nothing useful —
+  so that the tests compile and fail on what they check, not on a missing import.
+- Add or update no other test, and no production code beyond the stubs.
+
+## How a test stays passable
+
+- One data set per test, seeded at the top. Every expectation derives from that set: the
+  rows a filter keeps, the order they take, the page a limit and an offset cut out of it.
+  Write the expected count from the seeded data, not as a figure recounted by hand.
+- To observe a bound, seed past it: a cap of 200 is only visible with more than 200 rows
+  that the filters keep. "At most N" is asserted with \`<= N\`, or by seeding more than N;
+  never as exactly N when fewer exist.
+
+## Prove them: red, green, red
+
+A test you have only seen fail proves nothing about itself: a test no implementation
+could pass fails exactly the same way. The tests must FAIL now, because the behaviour is
+missing, and you prove every one of them passable before you finish:
+
+1. **Red.** Run the tests. Each fails on an assertion (not on an import, a type, a syntax
+   error).
+2. **Green.** In the stub bodies — the same files, no new file — write the shortest
+   implementation of the task that makes every test pass: naive, in memory, unoptimised;
+   it is thrown away. Run the tests. A test still red here is wrong, not the task: fix its
+   data or its expectation (never drop a case, never replace a value the task gives with a
+   looser one), and run again until all are green.
+3. **Red again.** Put every stub body back to no behaviour. Run the tests: each fails
+   again on an assertion. Leave the tree in this state.
+
+Leave no trace of the green step: no helper, no import, no comment. The only non-test
+lines you deliver are the stubs.
+
+{{history}}
+
+## When you cannot act
+
+If the cases are missing, or contradict the task or the code, do not invent them. Change
+nothing and end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
+Rules of this run:
+{{rules}}
+`;
+
+// A retry carries the refusal in --history; the flags themselves are consumed so the
+// role options see only their own.
+take(process.argv, "--report");
+take(process.argv, "--report-from");
+
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (intention.length === 0) {
+  emitFailure("fail-blocking", "The Builder received no --intention.");
+  process.exit(1);
+}
+
+const parsed = parseRole(process.argv, BUILDER_FLAGS, NAME);
+if (!parsed.ok) {
+  emitFailure("fail-blocking", parsed.reason);
+  process.exit(1);
+}
+
+const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
+if (!template.ok) {
+  emitFailure("fail-blocking", template.reason);
+  process.exit(1);
+}
+const rules = loadRules(parsed.options, PROMPT_RULES);
+if (!rules.ok) {
+  emitFailure("fail-blocking", rules.reason);
+  process.exit(1);
+}
+
+const rendered = fillPrompt(
+  template.value,
+  {
+    task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
+    rules: rules.value.trim(),
+    id: take(process.argv, "--id") ?? "",
+    attempt: String(attemptOf(process.argv)),
+  },
+  ["task", "rules"],
+  textOption(parsed.options, "promptFile") ?? "built-in template",
+);
+if (!rendered.ok) {
+  emitFailure("fail-blocking", rendered.reason);
+  process.exit(1);
+}
+
+const spawned = await spawnFilled(parsed.runner, rendered.prompt, transcriptArgs(process.argv));
+if (!spawned.ok) {
+  emitFailure("fail-blocking", spawned.reason);
+  process.exit(1);
+}
+finishRun({ run: spawned.run, bin: spawned.about.bin, name: spawned.about.name });

package/feature/fix.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import {
+  BUILDER_FLAGS,
+  emitFailure,
+  fillPrompt,
+  finishRun,
+  loadPrompt,
+  loadRules,
+  PROMPT_RULES,
+  parseRole,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+import { attemptOf } from "../lib/fill.mjs";
+
+const NAME = "feature fix";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+This directory is a whole feature: the work of all its tickets, already
+assembled and checked ticket by ticket. It was then brought up to date with the
+branch it will be merged into, and checked again as a whole. Something refused
+it after that: a merge conflict while bringing it up to date, a check that fails
+on the result, or the project's CI. Do not redo the feature, or any ticket of
+it. Fix what the refusal names.
+
+Refused by: {{refused_by}}
+
+What it said:
+
+\`\`\`raw
+{{report}}
+\`\`\`
+
+YOUR WORK NOW IS TO RESOLVE THAT. Change what it takes and nothing more; what is
+already here and passes is not to be redone.
+
+## According to who refused
+
+- **A merge conflict** (refused by \`align\`): the report names the branch the
+  feature is merged into. Look at what that branch changed since this feature
+  started (compare the two with git), then edit the files in conflict so that
+  both sets of changes hold: what the branch added stays, and the feature still
+  does what it asks. Do not drop the branch's changes to keep yours. Leave the
+  result uncommitted.
+- **A check** (a gate named by its id, such as the typecheck or the tests): run
+  the failing command here the way the gate ran it, see the error, fix the
+  cause. The error often comes from what the target branch brought in, or from
+  two tickets that were each fine alone: adapt the feature's code to it.
+- **The CI**: reproduce the failing job's command here, then fix it. Change the
+  work, not the CI definition.
+
+## Original request
+
+This was asked in the first place, and still holds:
+
+{{task}}
+
+{{history}}
+
+## When you cannot act
+
+If what you were given is not enough to act on (the refusal names nothing you
+can read or run here, the request contradicts the rules of this run, or the
+cause is outside this directory), do not invent a change. Change nothing and
+end your final message with exactly one line:
+
+MASON_BLOCKED: <what is missing, in one line>
+
+A person reads that line and decides. It is a correct answer, not a failure.
+
+## Rules of this run
+
+{{rules}}
+`;
+
+const report = (take(process.argv, "--report") ?? "").trim();
+if (report.length === 0) {
+  emitFailure("fail-blocking", "The feature fix command needs --report.");
+  process.exit(1);
+}
+
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (intention.length === 0) {
+  emitFailure("fail-blocking", "The Builder received no --intention.");
+  process.exit(1);
+}
+
+const parsed = parseRole(process.argv, BUILDER_FLAGS, NAME);
+if (!parsed.ok) {
+  emitFailure("fail-blocking", parsed.reason);
+  process.exit(1);
+}
+
+const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
+if (!template.ok) {
+  emitFailure("fail-blocking", template.reason);
+  process.exit(1);
+}
+const rules = loadRules(parsed.options, PROMPT_RULES);
+if (!rules.ok) {
+  emitFailure("fail-blocking", rules.reason);
+  process.exit(1);
+}
+
+const refusedBy = (take(process.argv, "--report-from") ?? "").trim();
+const rendered = fillPrompt(
+  template.value,
+  {
+    task: intention,
+    history: (take(process.argv, "--history") ?? "").trim(),
+    report,
+    refused_by:
+      refusedBy.length > 0 ? refusedBy : "the producer of the last attempt, which did not finish",
+    rules: rules.value.trim(),
+    id: take(process.argv, "--id") ?? "",
+    attempt: String(attemptOf(process.argv)),
+  },
+  ["task", "report", "rules"],
+  textOption(parsed.options, "promptFile") ?? "built-in template",
+);
+if (!rendered.ok) {
+  emitFailure("fail-blocking", rendered.reason);
+  process.exit(1);
+}
+
+const spawned = await spawnFilled(parsed.runner, rendered.prompt, transcriptArgs(process.argv));
+if (!spawned.ok) {
+  emitFailure("fail-blocking", spawned.reason);
+  process.exit(1);
+}
+finishRun({ run: spawned.run, bin: spawned.about.bin, name: spawned.about.name });

package/feature/validate.mjs

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import {
+  BUILDER_FLAGS,
+  emitFailure,
+  failureOf,
+  fillPrompt,
+  loadPrompt,
+  loadRules,
+  parseRole,
+  readResult,
+  spawnFilled,
+  take,
+  textOption,
+  transcriptArgs,
+} from "@bluewombat/slot-kit";
+import { attemptOf } from "../lib/fill.mjs";
+
+const NAME = "feature validate";
+
+const DEFAULT_TEMPLATE = `You are a coding agent working unattended in a checkout of the project.
+
+This directory is a whole feature: the work of all its tickets, already
+assembled, and brought up to date with the branch it will be merged into. Each
+ticket was checked and reviewed on its own. Your job now is different: read the
+diff it carries against that branch, and judge whether the WHOLE feature meets
+what was asked of the feature. Look for what no ticket covers, for what two
+tickets contradict or leave half-connected, and for what the merge with the
+branch broke. Do not re-judge each ticket. Do not redo the work. Do not change
+anything — this is a read-only review, not a repair.
+
+## What was asked of the feature
+
+{{task}}
+
+## Your answer
+
+End your final message with exactly one line in this form, and nothing after
+it:
+
+- \`MASON_VERDICT: VALIDATED\` — the feature meets what was asked.
+- \`MASON_VERDICT: REFUSED: <one paragraph>\` — it does not, and the paragraph
+  says what is missing or wrong, specifically enough for another agent to fix it
+  without redoing your review. Keep the whole paragraph on that one line.
+
+Nothing else may start a line with \`MASON_VERDICT:\`. You may explain your
+reasoning before it, but that line is what is read — write it last.
+
+## Rules of this run
+
+{{rules}}
+`;
+
+/**
+ * A reviewer's bounds: read-only, and answer in the one shape the caller
+ * parses. `PROMPT_RULES` tells a producer to leave work uncommitted and push
+ * nothing — obligations a Task that writes nothing does not have.
+ */
+const DEFAULT_RULES = [
+  "- Work only inside this directory. Do not read or edit anything outside it.",
+  "- This is a review, not a repair: do not change, stage, commit, or stash any file.",
+  "- Judge the diff against what was asked of the feature, not the style of the tickets that made it.",
+  "- Nobody is watching this run and nobody will answer a question. Where the intention is",
+  "  ambiguous, take the reading most consistent with the existing code, and say which one",
+  "  you took in your answer.",
+  "- End your final message with one line: MASON_VERDICT: VALIDATED, or",
+  "  MASON_VERDICT: REFUSED: <one paragraph, on that one line>.",
+].join("\n");
+
+const report = (take(process.argv, "--report") ?? "").trim();
+if (report.length > 0) {
+  emitFailure(
+    "fail-blocking",
+    "feature.validate is a read-only review; it does not take --report — that is feature.fix's job.",
+  );
+  process.exit(1);
+}
+
+const intention = (take(process.argv, "--intention") ?? "").trim();
+if (intention.length === 0) {
+  emitFailure("fail-blocking", "The Builder received no --intention.");
+  process.exit(1);
+}
+
+const parsed = parseRole(process.argv, BUILDER_FLAGS, NAME);
+if (!parsed.ok) {
+  emitFailure("fail-blocking", parsed.reason);
+  process.exit(1);
+}
+
+const template = loadPrompt(parsed.options, DEFAULT_TEMPLATE);
+if (!template.ok) {
+  emitFailure("fail-blocking", template.reason);
+  process.exit(1);
+}
+const rules = loadRules(parsed.options, DEFAULT_RULES);
+if (!rules.ok) {
+  emitFailure("fail-blocking", rules.reason);
+  process.exit(1);
+}
+
+const rendered = fillPrompt(
+  template.value,
+  {
+    task: intention,
+    rules: rules.value.trim(),
+    id: take(process.argv, "--id") ?? "",
+    attempt: String(attemptOf(process.argv)),
+  },
+  ["task", "rules"],
+  textOption(parsed.options, "promptFile") ?? "built-in template",
+);
+if (!rendered.ok) {
+  emitFailure("fail-blocking", rendered.reason);
+  process.exit(1);
+}
+
+const spawned = await spawnFilled(parsed.runner, rendered.prompt, transcriptArgs(process.argv));
+if (!spawned.ok) {
+  emitFailure("fail-blocking", spawned.reason);
+  process.exit(1);
+}
+
+answer(spawned.run, spawned.about.bin, spawned.about.name);
+
+/**
+ * Read the agent's own verdict and map it through `emitFailure` — never
+ * through exit 0 alone. A review that completes cleanly still has to answer
+ * whether the work is right; the CLI exiting 0 only says the review ran.
+ *
+ * @param {import("@bluewombat/slot-kit").AgentRun} run
+ * @param {string} bin
+ * @param {string} name
+ * @returns {never}
+ */
+function answer(run, bin, name) {
+  if (run.error !== undefined || run.code !== 0) {
+    const failure = failureOf(run, bin, name);
+    emitFailure(failure.outcome, failure.report);
+    process.exit(1);
+  }
+  const result = readResult(run.stdout);
+  if (result?.is_error === true) {
+    const failure = failureOf(run, bin, name);
+    emitFailure(failure.outcome, failure.report);
+    process.exit(1);
+  }
+  const said = typeof result?.result === "string" ? result.result.trim() : "";
+  const verdict = lastVerdictLine(said);
+  if (verdict === undefined) {
+    // No `MASON_VERDICT:` line at all is not a pass on the strength of exit 0.
+    // Treated as retryable, the same as any other malformed Attempt — the
+    // next round gets the same prompt again.
+    emitFailure(
+      "fail-retryable",
+      `feature.validate found no MASON_VERDICT: line in the answer: ${
+        said.length > 0 ? said.slice(0, 500) : "(no answer)"
+      }`,
+    );
+    process.exit(1);
+  }
+  const refused = /^REFUSED:?\s*/i.exec(verdict);
+  if (refused !== null) {
+    const why = verdict.slice(refused[0].length).trim();
+    emitFailure(
+      "fail-retryable",
+      why.length > 0 ? why : "feature.validate refused the feature, with no reason given.",
+    );
+    process.exit(1);
+  }
+  if (/^VALIDATED\b/i.test(verdict)) {
+    process.exit(0);
+  }
+  emitFailure(
+    "fail-retryable",
+    `feature.validate's MASON_VERDICT: line was neither VALIDATED nor REFUSED: ${verdict.slice(0, 500)}`,
+  );
+  process.exit(1);
+}
+
+/**
+ * The text after the last line that starts with `MASON_VERDICT:`, or
+ * `undefined` when no such line exists.
+ *
+ * A distinctive, unlikely-to-collide marker, anchored to the start of a line
+ * — not a bare search for "VALIDATED" or "REFUSED" anywhere in the answer,
+ * which a model's own reasoning can contain by accident ("the units were
+ * already validated on their own"). The *last* such line wins: a model that
+ * restates its conclusion, or that is shown an example in the prompt, still
+ * means its final one.
+ *
+ * @param {string} text
+ * @returns {string | undefined}
+ */
+function lastVerdictLine(text) {
+  const marker = /^MASON_VERDICT:\s*/i;
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const line = (lines[i] ?? "").trim();
+    const match = marker.exec(line);
+    if (match !== null) {
+      return line.slice(match[0].length).trim();
+    }
+  }
+  return undefined;
+}

package/gates/ci-green.mjs

@@ -88,7 +88,7 @@ for (;;) {
     // yet, and an empty list then says nothing. Ask again, until the wait
     // runs out: a commit no check ever picks up is not a refusal of the work.
     if (Date.now() >= stopAt) {
-      stopWaiting(pull, "no check has appeared");
+      stopWaiting(pull, "no check has appeared", true);
     }
     await sleep(Math.min(options.pollMs, Math.max(0, stopAt - Date.now())));
     continue;
@@ -128,16 +128,25 @@ function stopTime(from, raw) {
  * could change: blocking, so a person reads it instead of an agent being sent
  * to repair what was never judged.
  *
- * @param {{ number: number; sha: string }} pr
+ * When no check ever appeared, the cause is on the repository's side, and the
+ * message says the three it can be: no CI at all, a CI that does not run on pull
+ * requests into this branch, or a CI that is late.
+ *
+ * @param {{ number: number; sha: string; base?: string }} pr
  * @param {string} what
+ * @param {boolean} [never]
  * @returns {never}
  */
-function stopWaiting(pr, what) {
+function stopWaiting(pr, what, never = false) {
   const seconds = Math.round((Date.now() - startedAt) / 1000);
   const lasted = seconds >= 120 ? `${Math.round(seconds / 60)} min` : `${seconds} s`;
+  const into = pr.base === undefined ? "this branch" : `"${pr.base}"`;
+  const hint = never
+    ? ` Either this repository has no CI (then take ci-green out of the Gate list), or its workflows do not run on pull requests into ${into}, or the CI was removed or is late.`
+    : "";
   emitVerdict(
     "fail-blocking",
-    `ci-green stopped waiting after ${lasted}: ${what} on ${pr.sha.slice(0, 7)} (pull request #${pr.number}). The CI did not answer in time; this is not a refusal of the work, and no change to it can make the CI answer.`,
+    `ci-green stopped waiting after ${lasted}: ${what} on ${pr.sha.slice(0, 7)} (pull request #${pr.number}). The CI did not answer in time; this is not a refusal of the work, and no change to it can make the CI answer.${hint}`,
   );
   process.exit(0);
 }
@@ -221,7 +230,7 @@ function repoFrom(url) {
 
 /**
  * @param {string} head
- * @returns {Promise<{ number: number; sha: string } | undefined>}
+ * @returns {Promise<{ number: number; sha: string; base?: string } | undefined>}
  */
 async function openPullFor(head) {
   const listed = await api(
@@ -232,8 +241,10 @@ async function openPullFor(head) {
   if (first === undefined || headOf === undefined) {
     return undefined;
   }
+  const baseOf = record(first.base);
+  const base = typeof baseOf?.ref === "string" ? baseOf.ref : undefined;
   return typeof first.number === "number" && typeof headOf.sha === "string"
-    ? { number: first.number, sha: headOf.sha }
+    ? { number: first.number, sha: headOf.sha, ...(base === undefined ? {} : { base }) }
     : undefined;
 }