@gonrocca/nodd 0.1.0

package/src/prompt.test.ts

@@ -0,0 +1,193 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { emptyCommitted, type Committed } from "./state.ts";
+import { emptyPolicy, type Policy } from "./gates/policy.ts";
+import { CANONICAL_STEPS } from "./manifest.ts";
+import { ODD_PROSE, type ProseEntry } from "./odd-prose.ts";
+import { BLOCK_A_BUDGET, BLOCK_B_BUDGET, renderBlockA, renderBlockB, renderPrompt } from "./prompt.ts";
+
+function committed(overrides: Partial<Committed> = {}): Committed {
+  return { ...emptyCommitted(), ...overrides };
+}
+
+const undeclared = committed();
+
+const tracked = committed({
+  declaration: { intent: "change", route: "tracked", slug: "cache-warmup" },
+  filesRead: new Set(["/repo/a.ts", "/repo/b.ts"]),
+  filesWritten: new Set(["/repo/a.ts"]),
+  toolCalls: 12,
+});
+
+const allOff: Policy = { ...emptyPolicy(), flags: { all: false } };
+
+// ---------------------------------------------------------------------------
+// Block A — the state
+// ---------------------------------------------------------------------------
+test("an undeclared session is told what is missing and how to declare it", () => {
+  const { blockA } = renderPrompt(undeclared, emptyPolicy());
+  assert.match(blockA, /nodd_declare/, "the unblocking action is named");
+  assert.match(blockA, /authorize/, "the current step is named");
+});
+
+test("a tracked session names its slug, its route and the enabled gates", () => {
+  const { blockA } = renderPrompt(tracked, emptyPolicy());
+  assert.ok(blockA.includes("cache-warmup"));
+  assert.ok(blockA.includes("tracked"));
+  assert.ok(blockA.includes("evidence"), "the evidence gate is listed as enabled");
+});
+
+test("the escape-hatch syntax is always available in block A", () => {
+  assert.match(renderPrompt(tracked, emptyPolicy()).blockA, /\/nodd-allow/);
+});
+
+test("a used hatch is reported, so a one-shot override is not silently spent", () => {
+  const policy: Policy = { ...emptyPolicy(), hatches: { track: { reason: "hand-edit" } } };
+  const { blockA } = renderPrompt(tracked, policy);
+  assert.match(blockA, /track/);
+  assert.match(blockA, /hatch|habilitad|override/i);
+});
+
+// ---------------------------------------------------------------------------
+// Disabled gates
+// ---------------------------------------------------------------------------
+test("with every gate off block A is a single line", () => {
+  const { blockA } = renderPrompt(tracked, allOff);
+  assert.equal(blockA.trim().split("\n").length, 1, `expected one line, got:\n${blockA}`);
+});
+
+test("the disabled notice never suggests re-enabling anything", () => {
+  const policies: Policy[] = [allOff, { ...emptyPolicy(), config: { track: { enabled: false } } }];
+  for (const policy of policies) {
+    const { blockA } = renderPrompt(tracked, policy);
+    for (const forbidden of ["re-enable", "reenable", "volvé a activar", "turn it back on", "reactivar", "nodd-gates on"]) {
+      assert.ok(!blockA.toLowerCase().includes(forbidden.toLowerCase()), `block A must not say "${forbidden}"`);
+    }
+  }
+});
+
+test("a gate turned off is not listed as enabled", () => {
+  const policy: Policy = { ...emptyPolicy(), config: { track: { enabled: false } } };
+  const { blockA } = renderPrompt(tracked, policy);
+  const enabledLine = blockA.split("\n").find((line) => /activ|enabled/i.test(line)) ?? "";
+  assert.ok(!enabledLine.includes("track"), `track must not appear as enabled: ${enabledLine}`);
+});
+
+// ---------------------------------------------------------------------------
+// Block B — forwarded prose, scoped to the step
+// ---------------------------------------------------------------------------
+test("block B still forwards step prose even with every gate off", () => {
+  const { blockB } = renderPrompt(tracked, allOff);
+  assert.ok(blockB.length > 0, "guidance survives the kill switch; only enforcement stops");
+});
+
+test("block B for implement carries the line advisory and no explore-only clause", () => {
+  const state = committed({ declaration: { intent: "change", route: "tracked", slug: "s" }, filesWritten: new Set(["/a.ts"]) });
+  const { blockB } = renderPrompt(state, emptyPolicy(), { step: "implement" });
+  assert.match(blockB, /400/, "the implement step carries the advisory");
+  assert.ok(!blockB.includes("Proportionality"), "an explore-only reason must not leak in");
+  assert.ok(!blockB.includes("proportionate to the request"), "an explore-only clause must not leak in");
+});
+
+test("block B for explore carries the preparation trigger and not the line advisory", () => {
+  const { blockB } = renderPrompt(tracked, emptyPolicy(), { step: "explore" });
+  assert.match(blockB, /prepar/i);
+  assert.ok(!blockB.includes("400"), "the line figure belongs to implement");
+});
+
+// ---------------------------------------------------------------------------
+// The budgets — this is the anti-ratchet mechanism
+// ---------------------------------------------------------------------------
+test("the budgets are the documented numbers", () => {
+  assert.equal(BLOCK_A_BUDGET, 1500);
+  assert.equal(BLOCK_B_BUDGET, 2500);
+});
+
+// This is the anti-ratchet assertion, and it is deliberately made on the text
+// *before* `renderPrompt` cuts it. Asserting on the emitted block would be
+// `min(len, budget) <= budget` — an assertion no corpus on earth can fail,
+// which is exactly the shape the round-1 verdict caught. Here, one clause too
+// many turns this red.
+test("every step, every policy, stays inside both budgets BEFORE any truncation", () => {
+  const states = [undeclared, tracked];
+  const policies = [emptyPolicy(), allOff, { ...emptyPolicy(), hatches: { track: { reason: "x" } } }];
+
+  for (const step of CANONICAL_STEPS) {
+    const blockB = renderBlockB(step);
+    assert.ok(blockB.length <= BLOCK_B_BUDGET, `block B at ${step} is ${blockB.length} > ${BLOCK_B_BUDGET} before truncation`);
+    for (const state of states) {
+      for (const policy of policies) {
+        const blockA = renderBlockA(state, policy, step);
+        assert.ok(blockA.length <= BLOCK_A_BUDGET, `block A at ${step} is ${blockA.length} > ${BLOCK_A_BUDGET} before truncation`);
+      }
+    }
+  }
+});
+
+// The test above is only a defence if it can fail. This one proves it can, by
+// doing to the corpus exactly what the verdict did: growing it. If this ever
+// stops throwing, the assertion above has gone tautological again.
+test("growing the corpus past the budget makes the anti-ratchet assertion fail", () => {
+  const padding: ProseEntry[] = Array.from({ length: 40 }, (_, i) => ({
+    row: 1000 + i,
+    line: ":999",
+    step: "implement" as const,
+    clause: `Filler clause ${i}: individually defensible, collectively a wall of prose.`,
+    reason: "a padding entry, here only to prove the budget assertion is reachable",
+  }));
+  const grown = [...ODD_PROSE.filter((entry) => entry.step === "implement"), ...padding];
+
+  const rendered = renderBlockB("implement", grown);
+  assert.ok(
+    rendered.length > BLOCK_B_BUDGET,
+    "40 extra clauses must overflow the budget; if they do not, the budget is not measuring the corpus",
+  );
+  assert.throws(
+    () => assert.ok(rendered.length <= BLOCK_B_BUDGET),
+    "the anti-ratchet assertion must reject a grown corpus",
+  );
+});
+
+test("a real ODD clause is never silently dropped to make room", () => {
+  // The verdict's worst finding: with padding injected first, all four real
+  // `implement` clauses fell out of the emitted block and nothing said so.
+  const real = ODD_PROSE.filter((entry) => entry.step === "implement");
+  const blockB = renderBlockB("implement");
+  for (const entry of real) {
+    assert.ok(blockB.includes(entry.clause), `row ${entry.row} must survive into block B whole`);
+  }
+});
+
+test("a mid-implementation prompt stays under 4000 characters combined", () => {
+  const { blockA, blockB } = renderPrompt(tracked, emptyPolicy(), { step: "implement" });
+  assert.ok(blockA.length + blockB.length <= 4000, `combined ${blockA.length + blockB.length}`);
+});
+
+test("an over-budget block is cut, and the cut is announced in the block itself", () => {
+  // Production must not lose characters quietly. The cut stays — the budget is
+  // the point — but the block says it happened and by how much, so the next
+  // author meets the decision instead of the loss.
+  const { blockB, overBudget } = renderPrompt(tracked, emptyPolicy(), { step: "implement", blockBBudget: 200 });
+  assert.ok(blockB.length <= 200, `truncated block is ${blockB.length}`);
+  assert.match(blockB, /NODD/, "the notice names who cut it");
+  assert.match(blockB, /over budget|cut/i, "a truncated block says it was truncated");
+  assert.match(blockB, new RegExp(String(renderBlockB("implement").length)), "and reports the real pre-cut size");
+  assert.deepEqual(
+    overBudget.length,
+    1,
+    "an overflow is reported to the caller, not only buried in the text",
+  );
+  assert.match(overBudget[0], /block B/, overBudget[0]);
+});
+
+test("a block inside its budget reports no overflow and carries no notice", () => {
+  const { blockA, blockB, overBudget } = renderPrompt(tracked, emptyPolicy(), { step: "implement" });
+  assert.deepEqual(overBudget, [], "the shipped corpus fits, so nothing is announced");
+  assert.ok(!blockA.includes("over budget") && !blockB.includes("over budget"));
+});
+
+test("the renderer is pure: same inputs, same bytes, no file access", () => {
+  const first = renderPrompt(tracked, emptyPolicy(), { step: "implement" });
+  const second = renderPrompt(tracked, emptyPolicy(), { step: "implement" });
+  assert.deepEqual(first, second);
+});

package/src/prompt.ts

@@ -0,0 +1,136 @@
+// The dynamic prompt: two blocks, both budgeted.
+//
+// Block A is the session's *state* — current step, enabled gates, what is
+// missing, how to unblock. Block B is the forwarded prose for that step and
+// nothing else (`src/odd-prose.ts`).
+//
+// ## Why there are hard budgets
+//
+// gentle's guidance surface reached **105,993 bytes** one defensible clause at a
+// time. No single addition was wrong; the sum was. A budget is the only defence
+// that does not depend on the next author's restraint, so these two numbers are
+// enforced by truncation and pinned by a test that fails if a block grows past
+// them. Adding a clause that does not fit is therefore a decision to remove or
+// shorten another — which is exactly the conversation that never happened in
+// gentle.
+//
+// For that to be a defence rather than a story, two things have to hold, and
+// round 1 of this build had neither:
+//
+//   - **the test measures the corpus, not the cut.** `renderBlockA`/`renderBlockB`
+//     are exported *unbudgeted* so `prompt.test.ts` can assert on what the
+//     corpus renders to. Asserting on `renderPrompt`'s output instead compares
+//     the truncator's output to the truncator's own limit, which no corpus can
+//     fail.
+//   - **overflow is loud.** A cut still happens — the budget is the mechanism —
+//     but the emitted block says it was cut and by how much, and `renderPrompt`
+//     returns the overflows so the caller can surface them. A silently dropped
+//     clause is the exact failure this budget exists to prevent, so it must not
+//     be how the budget is enforced.
+//
+// ## Guidance survives the kill switch
+//
+// With every gate disabled, block A collapses to one line and block B still
+// forwards the step's prose: turning enforcement off is not a request to stop
+// being useful. And the disabled notice contains **no suggestion to re-enable**
+// (`routing.go:116`) — "do not start it, do not retry, do not reactivate".
+
+import { GATE_IDS, type GateId } from "./gates/registry.ts";
+import { resolveFlag, type Policy } from "./gates/policy.ts";
+import { proseForStep, type ProseEntry } from "./odd-prose.ts";
+import type { CanonicalStep } from "./manifest.ts";
+import type { Committed } from "./state.ts";
+
+/** Hard ceilings. See the ratchet note above before raising either. */
+export const BLOCK_A_BUDGET = 1500;
+export const BLOCK_B_BUDGET = 2500;
+
+export type Prompt = {
+  blockA: string;
+  blockB: string;
+  /** One line per block that did not fit. Empty when everything fitted. */
+  overBudget: string[];
+};
+
+export type RenderOptions = {
+  step?: CanonicalStep;
+  blockABudget?: number;
+  blockBBudget?: number;
+};
+
+/** Where the session is, derived from what it has actually done. */
+function currentStep(committed: Committed): CanonicalStep {
+  if (committed.declaration === null) return committed.toolCalls === 0 ? "authorize" : "classify";
+  if (committed.declaration.intent === "read-only") return "explore";
+  if (committed.filesWritten.size > 0) return "implement";
+  return committed.declaration.route === "inline" ? "implement" : "track";
+}
+
+function enabledGates(policy: Policy): GateId[] {
+  return GATE_IDS.filter((gate) => resolveFlag(gate, policy).enabled);
+}
+
+/**
+ * Cut to budget and say so, in the block and to the caller. The notice is part
+ * of the budget: it is rendered inside the remaining room, so an over-budget
+ * block is still an under-budget block, just a visibly damaged one.
+ */
+function fit(text: string, budget: number, label: string): { text: string; problem: string | null } {
+  if (text.length <= budget) return { text, problem: null };
+
+  const problem = `${label} is ${text.length} characters, over its ${budget}-character budget: ${text.length - budget} were cut. Shorten or remove a clause instead of raising the budget.`;
+  const notice = `\n[NODD: ${label} over budget — ${text.length}/${budget} characters, cut]`;
+  const room = Math.max(0, budget - notice.length);
+  return { text: `${text.slice(0, room).trimEnd()}${notice}`, problem };
+}
+
+/** Block A at full length, unbudgeted. The budget is applied by `renderPrompt`. */
+export function renderBlockA(committed: Committed, policy: Policy, step: CanonicalStep): string {
+  const enabled = enabledGates(policy);
+
+  if (enabled.length === 0) {
+    // One line, and not a word about turning anything back on.
+    return "NODD: gates disabled. Working normally; no enforcement is applied.";
+  }
+
+  const lines = [`NODD · step: ${step} · gates activos: ${enabled.join(", ")}`];
+
+  if (committed.declaration === null) {
+    lines.push("Sin declaración: el primer write está bloqueado hasta que llames `nodd_declare` con intent y route.");
+  } else {
+    const { intent, route, slug } = committed.declaration;
+    lines.push(`Declarado: intent ${intent} · route ${route} · slug ${slug}.`);
+  }
+
+  const disabled = GATE_IDS.filter((gate) => !resolveFlag(gate, policy).enabled);
+  if (disabled.length > 0) lines.push(`Apagados por el usuario: ${disabled.join(", ")}.`);
+
+  const hatches = Object.keys(policy.hatches);
+  if (hatches.length > 0) lines.push(`Hatch de un uso pendiente: ${hatches.join(", ")}.`);
+
+  lines.push("Para saltear un gate una vez: `/nodd-allow <gate>`.");
+  return lines.join("\n");
+}
+
+/**
+ * Block B at full length, unbudgeted. `entries` is injectable so the anti-ratchet
+ * test can render a grown corpus and prove the budget assertion is reachable.
+ */
+export function renderBlockB(step: CanonicalStep, entries: readonly ProseEntry[] = proseForStep(step)): string {
+  if (entries.length === 0) return "";
+  // Only the clause text: the row number and the not-mechanizable reason are
+  // there for the reader of the corpus, and spending budget on them would push
+  // the useful half out.
+  return [`ODD · guía para ${step} (orientativa, no verificada):`, ...entries.map((entry) => `- ${entry.clause}`)].join("\n");
+}
+
+export function renderPrompt(committed: Committed, policy: Policy, options: RenderOptions = {}): Prompt {
+  const step = options.step ?? currentStep(committed);
+  const a = fit(renderBlockA(committed, policy, step), options.blockABudget ?? BLOCK_A_BUDGET, "block A");
+  const b = fit(renderBlockB(step), options.blockBBudget ?? BLOCK_B_BUDGET, "block B");
+  return {
+    blockA: a.text,
+    blockB: b.text,
+    overBudget: [a.problem, b.problem].filter((problem): problem is string => problem !== null),
+  };
+}

package/src/review-candidate.test.ts

@@ -0,0 +1,118 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { emptyCommitted, fold, type Committed } from "./state.ts";
+import { observation } from "./observations.ts";
+import {
+  candidateFor,
+  chainBoundary,
+  parseCommitSha,
+  renderCandidate,
+  sliceCandidate,
+  type Boundary,
+} from "./review-candidate.ts";
+
+function afterCommands(runs: Array<{ command: string; text: string; isError?: boolean }>): Committed {
+  let committed = emptyCommitted();
+  runs.forEach((run, i) => {
+    committed = fold(committed, observation({
+      toolCallId: `c${i}`,
+      toolName: "bash",
+      input: { command: run.command },
+      isError: run.isError === true,
+      resultText: run.text,
+      at: `2026-09-19T10:0${i}:00.000Z`,
+    }));
+  });
+  return committed;
+}
+
+test("checking off with an observed commit records that SHA as the candidate", () => {
+  const committed = afterCommands([
+    { command: "git commit -m 'feat: thing'", text: "[main 1a2b3c4] feat: thing\n 2 files changed" },
+  ]);
+  const candidate = candidateFor(committed);
+  assert.deepEqual(candidate, { kind: "commit", sha: "1a2b3c4" });
+  assert.equal(renderCandidate(candidate), "candidate: 1a2b3c4");
+});
+
+test("a full SHA from git rev-parse is recorded too", () => {
+  const sha = "0123456789abcdef0123456789abcdef01234567";
+  const committed = afterCommands([{ command: "git rev-parse HEAD", text: sha }]);
+  assert.deepEqual(candidateFor(committed), { kind: "commit", sha });
+});
+
+test("the latest observed commit wins", () => {
+  const committed = afterCommands([
+    { command: "git commit -m 'one'", text: "[main aaaaaaa] one" },
+    { command: "git commit -m 'two'", text: "[main bbbbbbb] two" },
+  ]);
+  assert.deepEqual(candidateFor(committed), { kind: "commit", sha: "bbbbbbb" });
+});
+
+test("checking off with no observed commit records pending-commit, never the checkbox", () => {
+  const candidate = candidateFor(afterCommands([{ command: "npm test", text: "42 passing" }]));
+  assert.deepEqual(candidate, { kind: "pending-commit" });
+  assert.equal(renderCandidate(candidate), "candidate: pending-commit");
+});
+
+test("a failed commit is not a candidate: the SHA must come from a success", () => {
+  const committed = afterCommands([
+    { command: "git commit -m 'x'", text: "nothing to commit\n\nCommand exited with code 1", isError: true },
+  ]);
+  assert.deepEqual(candidateFor(committed), { kind: "pending-commit" });
+});
+
+test("prose that merely looks like commit output is not a candidate", () => {
+  // The model may say anything; only a NODD-issued git command's observed
+  // output is a source of SHAs.
+  const claimed = fold(emptyCommitted(), observation({
+    toolCallId: "a1",
+    toolName: "assistant_message",
+    input: { text: "I committed it as [main deadbee] feat: thing" },
+    isError: false,
+    resultText: "",
+    at: "2026-09-19T10:00:00.000Z",
+  }));
+  assert.deepEqual(candidateFor(claimed), { kind: "pending-commit" });
+});
+
+test("boundary chaining: the first base is the branch point, each head becomes the next base", () => {
+  const recorded: Boundary[] = [];
+  const first = chainBoundary("origin/main", recorded, "slice1head");
+  assert.deepEqual(first, { base: "origin/main", head: "slice1head" });
+
+  recorded.push(first);
+  const second = chainBoundary("origin/main", recorded, "slice2head");
+  assert.deepEqual(second, { base: "slice1head", head: "slice2head" });
+
+  const candidate = sliceCandidate(second);
+  assert.deepEqual(candidate, { kind: "slice", base: "slice1head", head: "slice2head" });
+  assert.equal(renderCandidate(candidate), "candidate: slice slice1head..slice2head");
+});
+
+test("parseCommitSha reads only the formats NODD issues", () => {
+  assert.equal(parseCommitSha("git commit -m 'x'", "[feature/x 9f8e7d6] x"), "9f8e7d6");
+  assert.equal(parseCommitSha("git commit --amend", "[main 1234567] x"), "1234567");
+  assert.equal(parseCommitSha("git log --oneline", "1234567 some commit"), null, "log is not a commit event");
+  assert.equal(parseCommitSha("npm test", "[main 1234567] looks like a commit"), null, "not a git command");
+  assert.equal(parseCommitSha("git commit -m 'x'", "nothing to commit"), null);
+});
+
+// The rule is structural: no candidate identity may ever be a task id or a
+// checkbox state. `routing.go:51`,`:102`.
+test("no candidate identity is a task id or a checkbox state", () => {
+  const identities = [
+    renderCandidate({ kind: "commit", sha: "1a2b3c4" }),
+    renderCandidate({ kind: "pending-commit" }),
+    renderCandidate(sliceCandidate({ base: "a", head: "b" })),
+  ];
+  for (const rendered of identities) {
+    assert.doesNotMatch(rendered, /\bT\d+\b/, `${rendered} must not carry a task id`);
+    assert.doesNotMatch(rendered, /\b(true|false|\[x\]|\[ \])\b/, `${rendered} must not carry checkbox state`);
+  }
+
+  const source = readFileSync(new URL("./review-candidate.ts", import.meta.url), "utf8");
+  assert.ok(!/\bchecked\b/.test(source), "the candidate module must not read checkbox state");
+  assert.ok(!/\btaskId\b/.test(source), "the candidate module must not take a task id");
+});

package/src/review-candidate.ts

@@ -0,0 +1,81 @@
+// What gets reviewed is a commit or a slice — never a checkbox.
+//
+// `routing.go:51`,`:102`: "the native review candidate is a work-unit commit or
+// a PR slice, never a TODO checkbox and never the accumulated branch". A
+// checkbox is a claim the model wrote down; a commit is a thing that exists.
+// This module only ever hands out the second kind.
+//
+// The SHA comes from the observed output of a NODD-issued `git` command, on the
+// same rule as command outcomes (T019): the model's prose is not an input. When
+// no commit has been observed the candidate is `pending-commit` — an honest
+// absence, not a substitute identity.
+//
+// Slices carry an explicit (base, head) pair. The accumulated branch is never a
+// candidate: "everything since we started" is not reviewable, which is the
+// failure mode the clause exists to prevent.
+
+import type { Committed } from "./state.ts";
+import { parseOutcome, isSuccess } from "./outcome.ts";
+
+export type Boundary = { base: string; head: string };
+
+export type Candidate =
+  | { kind: "commit"; sha: string }
+  | { kind: "slice"; base: string; head: string }
+  | { kind: "pending-commit" };
+
+/** `git commit` prints `[<branch> <sha>] <subject>`; `rev-parse` prints the sha alone. */
+export function parseCommitSha(command: string, resultText: string): string | null {
+  if (!/\bgit\s+(commit|rev-parse)\b/.test(command)) return null;
+
+  const committed = /^\[[^\]\s]+ ([0-9a-f]{7,40})\]/m.exec(resultText);
+  if (committed) return committed[1];
+
+  if (/\bgit\s+rev-parse\b/.test(command)) {
+    const bare = /^([0-9a-f]{40})$/m.exec(resultText.trim());
+    if (bare) return bare[1];
+  }
+
+  return null;
+}
+
+/**
+ * The candidate for a checkoff: the most recent SHA this session observed a
+ * successful `git` command produce, or `pending-commit`.
+ */
+export function candidateFor(committed: Committed): Candidate {
+  for (let i = committed.commandResults.length - 1; i >= 0; i--) {
+    const run = committed.commandResults[i];
+    if (!isSuccess(parseOutcome(run.isError, run.resultText))) continue;
+    const sha = parseCommitSha(run.command, run.resultText);
+    if (sha) return { kind: "commit", sha };
+  }
+  return { kind: "pending-commit" };
+}
+
+export function sliceCandidate(boundary: Boundary): Candidate {
+  return { kind: "slice", base: boundary.base, head: boundary.head };
+}
+
+/**
+ * The next boundary. The first base is the branch point; afterwards each
+ * recorded head becomes the next base, so slices tile the work instead of each
+ * one re-proposing the whole branch.
+ */
+export function chainBoundary(branchPoint: string, recorded: Boundary[], head: string): Boundary {
+  const previous = recorded[recorded.length - 1];
+  return { base: previous ? previous.head : branchPoint, head };
+}
+
+/** The identity alone, for the feature doc's `candidate:` field. */
+export function candidateIdentity(candidate: Candidate): string {
+  switch (candidate.kind) {
+    case "commit": return candidate.sha;
+    case "slice": return `slice ${candidate.base}..${candidate.head}`;
+    case "pending-commit": return "pending-commit";
+  }
+}
+
+export function renderCandidate(candidate: Candidate): string {
+  return `candidate: ${candidateIdentity(candidate)}`;
+}