@kitman-sh/software-engineering 0.0.0-stage → 0.10.55

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@kitman-sh/software-engineering",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.55",
+  "description": "Everything for building software: Loops, their Agents, the skills they use and the Ponytail plugin.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "exports": {
+    ".": "./kitman.config.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "INSTRUCTIONS.md",
+    "agents",
+    "kitman.config.ts",
+    "src",
+    "tsconfig.json"
+  ],
+  "dependencies": {
+    "@kitman-sh/sdk": "0.10.55",
+    "effect": "4.1.2"
+  },
+  "kitman": {
+    "bundle": "dist/bundle.js",
+    "digest": "e030f00d63c0dadfeb7b0961dca0d9aeb156a3e22d9a24a116eaf90792bf822b",
+    "protocolVersion": 5,
+    "declarations": "dist/declarations.json",
+    "setup": {
+      "2a237548a69b0cd53ec3be7f687cfa8c2128335b3a655d34e185f2abce6a3c37": "dist/setup/2a237548a69b0cd53ec3be7f687cfa8c2128335b3a655d34e185f2abce6a3c37.json"
+    }
+  }
+}

package/src/build.ts

@@ -0,0 +1,542 @@
+import {
+  agentWork,
+  agentWorkOnce,
+  approveChangeRequest,
+  ApproveChangeRequestResult,
+  call,
+  CheckName,
+  Continuing,
+  continuingBrief,
+  syncBase,
+  changeRequest,
+  ChangeRequestResult,
+  comment,
+  defineLoop,
+  type CalledLoop,
+  evidenceGate,
+  failsOn,
+  isBlocking,
+  LoopOutcome,
+  rallyStop,
+  Rebuttal,
+  settleRound,
+  verify,
+  writeBack,
+  type Disputed,
+  type MergedFinding,
+  type RallyDecision,
+  type ScopeJudgement,
+  type SettledRound,
+  type VerifyResult
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+import {
+  brokenChecks,
+  changeRequestBody,
+  checkFindings,
+  isCheckFinding,
+  scopeFindings,
+  unsettledItems
+} from './change-request-body'
+import review from './review'
+import shepherd from './shepherd'
+import { ShepherdOutput } from './shepherd-output'
+
+export const BuildInput = Schema.Struct({
+  /** What to build, when no Task says it. */
+  words: Schema.optional(Schema.String),
+  taskId: Schema.optional(Schema.String),
+  repoBindingId: Schema.optional(Schema.String),
+  /** The base branch; the repository's default branch when left out. */
+  branch: Schema.optional(Schema.String),
+  /** Where to start; the head of `branch` when left out. */
+  revision: Schema.optional(Schema.String),
+  outcome: Schema.optional(LoopOutcome),
+  /** Review rounds before the rally stops; 3 when left out. */
+  maxRounds: Schema.optional(Schema.Int),
+  /** The Task's open ChangeRequest an earlier Run left, which this Build fixes forward instead of rebuilding. */
+  continuing: Schema.optional(Continuing),
+  /** Sees the ChangeRequest through to merge with Shepherd once it opens. */
+  land: Schema.optional(Schema.Boolean),
+  /**
+   * An open ChangeRequest to fix forward on: the Run works its branch, never force-pushing, and reports in one comment
+   * on it, leaving the ChangeRequest's title and description to its author.
+   */
+  changeRequestId: Schema.optional(Schema.String)
+})
+
+/** The implementer's answer to one acceptance criterion of the Task. */
+const CriterionAnswer = Schema.Struct({
+  criterion: Schema.String,
+  status: Schema.Literals(['met', 'after_merge', 'not_met']),
+  /** The test or file that shows it met, or why it is after merge or not met. */
+  detail: Schema.String
+})
+
+type CriterionAnswer = typeof CriterionAnswer.Type
+
+const Criteria = Schema.Struct({ criteria: Schema.Array(CriterionAnswer) })
+
+export const SuggestedCheck = Schema.Struct({
+  name: CheckName,
+  command: Schema.String,
+  workingDirectory: Schema.optionalKey(Schema.String)
+})
+
+const Implemented = Schema.Struct({
+  /** The ChangeRequest's title. */
+  title: Schema.String,
+  summary: Schema.String,
+  claims: Schema.Array(Schema.String),
+  /** The approved checks that run the documented commands, for a docs Outcome. */
+  documented: Schema.optional(Schema.Array(Schema.String)),
+  /** The approved check that rolls a migration back. */
+  rollback: Schema.optional(Schema.String),
+  /** Each acceptance criterion of the Task, answered; empty when it has none, left out when building from words. */
+  criteria: Schema.optional(Schema.Array(CriterionAnswer)),
+  /** Checks to run when the repository has none approved, from its package scripts or CI config. */
+  checks: Schema.optional(Schema.Array(SuggestedCheck))
+})
+
+const Reproduced = Schema.Struct({
+  /** The approved check that reproduces the bug. */
+  check: Schema.String,
+  summary: Schema.String
+})
+
+/** A bug's proof; a continued Build recovers it from the branch an earlier Run left. */
+const ReproducedOnBranch = Schema.Struct({
+  ...Reproduced.fields,
+  /** The branch's commit where the reproducing test is in place and the fix is not yet; the head when none is. */
+  revision: Schema.optional(Schema.String)
+})
+
+const Fixed = Schema.Struct({
+  summary: Schema.String,
+  claims: Schema.Array(Schema.String),
+  rebuttals: Schema.Array(Rebuttal)
+})
+
+export const BuildOutput = Schema.Struct({
+  changeRequest: ChangeRequestResult,
+  revision: Schema.String,
+  tree: Schema.String,
+  settled: Schema.Boolean,
+  unsettled: Schema.Array(Schema.String),
+  rounds: Schema.Int,
+  stopped: Schema.Literals(['settled', 'dispute_stands', 'findings_returned', 'round_cap']),
+  criteria: Schema.Array(CriterionAnswer),
+  /** Whether the last Review's approval was recorded, or why not, when nothing was left unsettled. */
+  approval: Schema.optional(ApproveChangeRequestResult),
+  /** What Shepherd did with the ChangeRequest, when the Build was told to land it. */
+  landed: Schema.optional(ShepherdOutput),
+  /** The input its Shepherd and Review offers start from. */
+  next: Schema.Struct({ changeRequestId: Schema.String })
+})
+
+export class BuildTargetMissing extends Schema.TaggedError<BuildTargetMissing>()('BuildTargetMissing', {
+  message: Schema.String
+}) {}
+
+const outcomeGuidance = {
+  feature: 'Deliver the whole scope; review checks it was met.',
+  bug: 'Your failing test is already in place: make it pass.',
+  refactor: 'Keep behaviour exactly as it is; the approved verifications must pass before and after.',
+  investigation: 'Investigate and report what you found, with its sources.',
+  docs: 'Name, in `documented`, the approved checks that run the commands you documented.',
+  migration: 'Name, in `rollback`, the approved check that rolls the migration back.',
+  performance: 'Make it faster without changing behaviour.'
+} as const satisfies { readonly [outcome in LoopOutcome]: string }
+
+/** Build cannot prove a gain: Hillclimb commits a benchmark first and measures each change against it. */
+export class BuildOutcomeRefused extends Schema.TaggedError<BuildOutcomeRefused>()('BuildOutcomeRefused', {
+  message: Schema.String
+}) {}
+
+const criteriaGuidance =
+  'If your brief has a Task, answer each of its acceptance criteria in `criteria`: met, with the test or file that shows it; after_merge, with why it can only be seen once merged; or not_met, with why. Give an empty `criteria` when the Task has none.'
+
+const checksGuidance =
+  'If your brief lists no approved verifications for this repository, name in `checks` the commands from its package scripts or CI config that test, lint and typecheck it, each with a `name` of letters, digits, `.`, `_`, `:` and `-` only, such as `unit-tests`; Kitman runs them and labels them as suggested by you.'
+
+/** How Build and Errand adapt the implement skill to a Step. */
+export const implementAdaptation =
+  'You run the implement skill as a Kitman Step. The work is in this prompt and your brief, so fetch no ticket. Leave your changes uncommitted: the Run owns the branch. Skip its final code-review: a Review run or a person reviews the change.'
+
+const implementPrompt = (task: string, outcome: LoopOutcome | undefined, continuing: Continuing | undefined) =>
+  [
+    ...(continuing === undefined ? [] : [continuingBrief(continuing), 'Fix forward from there.']),
+    `Build ${task}`,
+    implementAdaptation,
+    ...(outcome === undefined ? [] : [outcomeGuidance[outcome]]),
+    'Commit nothing yourself: Kitman pushes what you leave in the workspace. Give the ChangeRequest a title and a summary, and list as claims what you believe but Kitman has not checked, such as "the tests pass".',
+    criteriaGuidance,
+    checksGuidance
+  ].join('\n\n')
+
+const criteriaPrompt = (unanswered: boolean, unmet: readonly CriterionAnswer[]) =>
+  [
+    unanswered
+      ? "You did not answer the Task's acceptance criteria. Answer each one before anyone reviews the change."
+      : 'These acceptance criteria are not met yet. Meet them, or say why they cannot be met here:',
+    ...unmet.map(answer => `- ${answer.criterion}: ${answer.detail}`),
+    criteriaGuidance
+  ].join('\n\n')
+
+const answerLine = (answer: CriterionAnswer) =>
+  `${answer.criterion}: ${answer.status.replaceAll('_', ' ')}, ${answer.detail}`
+
+const reproducePrompt = (task: string) =>
+  [
+    `Reproduce the bug in ${task} before anyone fixes it.`,
+    'Add a test that fails because of the bug, and change nothing else. Name the approved check that runs it; it must fail now and pass once the bug is fixed.'
+  ].join('\n\n')
+
+const reproducedOnBranchPrompt = (task: string) =>
+  [
+    `An earlier Run already worked on fixing the bug in ${task}, on this branch.`,
+    'Find the commit on this branch where the test reproducing the bug was in place and the fix was not yet, and give it as `revision`; name the approved check that runs that test. Change nothing.',
+    'If no commit on the branch has the reproducing test without the fix, add a test that fails on the branch head now, change nothing else, and give no `revision`.'
+  ].join('\n\n')
+
+const findingLine = (finding: MergedFinding) => `- **${finding.severity}** \`${finding.id}\` ${finding.detail}`
+
+const disputeLine = ({ finding, rebuttal }: Disputed) => `${findingLine(finding)}\n  You rebutted: ${rebuttal.reason}`
+
+const fixPrompt = (settled: SettledRound) => {
+  const checks = settled.open.filter(finding => isCheckFinding(finding.id))
+
+  const findings = settled.open.filter(finding => !isCheckFinding(finding.id))
+
+  return [
+    ...(checks.length === 0
+      ? []
+      : [
+          'These checks fail on your head and pass on the base. Only the check passing closes one. If you are sure the change did not cause it, such as a flaky test, rebut it with your reason: the ChangeRequest reports that as your claim and the check stays open. A check does not run again on an unchanged tree, so if you change nothing and only these are open, the rally ends.',
+          ...checks.map(findingLine)
+        ]),
+    ...(findings.length === 0
+      ? []
+      : [
+          'The review found these. Fix each, or rebut it with your reason if it is wrong; reviewers judge the rebuttals next round.',
+          ...findings.map(findingLine)
+        ]),
+    ...(settled.standing.length === 0
+      ? []
+      : [
+          'The reviewers rejected your rebuttal of these. Fix each, or rebut it again with a better reason; one you leave stays a dispute for a person to settle.',
+          ...settled.standing.map(disputeLine)
+        ])
+  ].join('\n')
+}
+
+const blockingIds = (settled: SettledRound) => settled.open.filter(isBlocking).map(finding => finding.id)
+
+const onlyChecksBlock = (settled: SettledRound) =>
+  blockingIds(settled).every(isCheckFinding) && !settled.standing.some(entry => isBlocking(entry.finding))
+
+type Round = {
+  readonly round: number
+  readonly head: VerifyResult
+  readonly settled: SettledRound
+  readonly decision: RallyDecision & { readonly stop: true }
+  readonly claims: readonly string[]
+  readonly scope: ScopeJudgement | undefined
+  readonly conflicts: readonly string[]
+}
+
+/**
+ * Verifies the head and has it reviewed, then has the implementer fix or rebut the findings, until the rally stops.
+ * The last Step that changes code comes before the last review, so the reviewed revision is the one that ships.
+ */
+const rally = (input: {
+  readonly maxRounds: number
+  readonly base: string
+  readonly target: string | undefined
+  readonly outcome: LoopOutcome | undefined
+  readonly claims: readonly string[]
+  readonly suggested: readonly (typeof SuggestedCheck.Type)[]
+}) =>
+  Effect.gen(function* () {
+    const claims = [...input.claims]
+    const conflicts: string[] = []
+    let rebuttals: readonly Rebuttal[] = []
+    let earlier: readonly MergedFinding[] = []
+    let previous: readonly string[] | undefined
+    let last: Pick<Round, 'head' | 'settled' | 'scope'> | undefined
+    const shown = new Set<string>()
+
+    for (let round = 1; ; round++) {
+      // Reviewers see what will merge; a conflict the implementer cannot settle is left unsettled, not hidden.
+      const synced = yield* syncBase(`sync:${round}`, {
+        agent: 'implementer',
+        ...(input.target === undefined ? undefined : { target: input.target })
+      })
+
+      if (synced.status === 'conflict')
+        conflicts.push(
+          `Could not merge the target branch in round ${round}: ${synced.files.join(', ')} (${synced.reason})`
+        )
+
+      const head = yield* verify(`verify:${round}`, { suggested: input.suggested })
+
+      // Evidence is held per tree, so the same checks would fail again and a review would judge the same change.
+      if (last !== undefined && last.head.tree === head.tree && rebuttals.length === 0 && onlyChecksBlock(last.settled))
+        return {
+          ...last,
+          round: round - 1,
+          head,
+          decision: { stop: true, reason: 'findings_returned', unsettled: blockingIds(last.settled) },
+          claims,
+          conflicts
+        } satisfies Round
+
+      const failing = brokenChecks(head).map(check => check.name)
+
+      const reviewed = yield* call(`review:${round}`, review, {
+        base: input.base,
+        head: head.revision,
+        ...(rebuttals.length === 0 ? undefined : { rebuttals }),
+        ...(earlier.length === 0 ? undefined : { earlier }),
+        ...(input.outcome === undefined ? undefined : { outcome: input.outcome }),
+        ...(failing.length === 0 ? undefined : { failing }),
+        claims: [...claims]
+      })
+
+      const checks = checkFindings(head)
+
+      const settled = settleRound({
+        findings: [...reviewed.findings, ...scopeFindings(reviewed.scope), ...checks],
+        rebuttals,
+        verdicts: reviewed.verdicts
+      })
+
+      // A dispute that stands stays in front of the reviewers when a broken check carries the rally on past it.
+      earlier = [...settled.open, ...settled.standing.map(entry => entry.finding)].filter(
+        finding => !finding.id.startsWith('scope: ') && !isCheckFinding(finding.id)
+      )
+
+      // A failure the implementer has not been shown has not returned, and a dispute does not keep it from them.
+      const unseen = checks.some(finding => !shown.has(finding.detail))
+
+      const decision = rallyStop({
+        round,
+        maxRounds: input.maxRounds,
+        settled,
+        ...(previous === undefined || unseen ? undefined : { previous })
+      })
+
+      if (decision.stop && (!unseen || round >= input.maxRounds))
+        return { round, head, settled, decision, claims, scope: reviewed.scope, conflicts } satisfies Round
+
+      for (const finding of checks) shown.add(finding.detail)
+
+      const fixed = yield* agentWork(`fix:${round}`, {
+        agent: 'implementer',
+        prompt: fixPrompt(settled),
+        output: Fixed
+      })
+
+      claims.push(
+        ...fixed.claims,
+        ...fixed.rebuttals.flatMap(rebuttal =>
+          isCheckFinding(rebuttal.findingId) ? [`Rebutted ${rebuttal.findingId}: ${rebuttal.reason}`] : []
+        )
+      )
+      // Evidence is not the reviewers' to withdraw.
+      const rebutted = fixed.rebuttals.filter(rebuttal => !isCheckFinding(rebuttal.findingId))
+
+      // A blocking dispute the implementer does not repeat is still one, unless the fix ends the finding.
+      rebuttals = [
+        ...rebutted,
+        ...settled.standing
+          .filter(entry => isBlocking(entry.finding))
+          .map(entry => entry.rebuttal)
+          .filter(rebuttal => !rebutted.some(entry => entry.findingId === rebuttal.findingId))
+      ]
+      previous = blockingIds(settled)
+      last = { head, settled, scope: reviewed.scope }
+    }
+  })
+
+/**
+ * Implements a Task or words, reviews and fixes until the rally stops, gates on the evidence for the head, and opens
+ * the Run's ChangeRequest with the evidence, the claims and whatever it could not settle (ADR-0051). It writes the
+ * Run's milestones to its Task: started, ChangeRequest opened, and failed.
+ */
+export default defineLoop({
+  id: 'build',
+  version: '2.2.0',
+  title: 'Build',
+  input: BuildInput,
+  output: BuildOutput,
+  agents: { implementer: 'implementer' },
+  checkout: 'write',
+  offers: [
+    { id: 'shepherd', title: 'Shepherd it to merge', loop: 'shepherd', from: 'next' },
+    { id: 'review', title: 'Review again', loop: 'review', from: 'next' },
+    { id: 'tidy', title: 'Tidy', loop: 'tidy' },
+    { id: 'retry', title: 'Retry with a steer', loop: 'build' }
+  ],
+  capabilities: ['agent_work', 'verify', 'change_request', 'write_back', 'post_comment', 'approve_change_request'],
+  calls: (): readonly CalledLoop[] => [review, shepherd],
+  run: input =>
+    Effect.gen(function* () {
+      if (input.words === undefined && input.taskId === undefined)
+        return yield* new BuildTargetMissing({ message: 'Give the words to build, or a Task' })
+
+      if (input.outcome === 'performance')
+        return yield* new BuildOutcomeRefused({
+          message:
+            'Build cannot prove a performance gain; start Hillclimb, which commits a benchmark and keeps only the changes Kitman measures faster'
+        })
+
+      yield* writeBack('write-back:started', { milestone: 'started' })
+
+      const task = input.words === undefined ? 'the Task your brief describes.' : `this: ${input.words}`
+      const outcome = input.outcome
+      const target = input.branch ?? input.continuing?.targetBranch
+
+      if (input.changeRequestId !== undefined && input.continuing?.changeRequestId !== input.changeRequestId)
+        return yield* new BuildTargetMissing({
+          message: `Kitman did not put this Run on ChangeRequest ${input.changeRequestId}'s branch`
+        })
+
+      // A continued bug recovers its proof from the branch: the commit where the test failed before the fix.
+      const reproduced =
+        outcome === 'bug'
+          ? yield* agentWork('reproduce', {
+              agent: 'implementer',
+              prompt: input.continuing === undefined ? reproducePrompt(task) : reproducedOnBranchPrompt(task),
+              output: ReproducedOnBranch
+            })
+          : undefined
+
+      const base =
+        reproduced !== undefined
+          ? yield* verify(
+              'verify:reproduction',
+              reproduced.revision === undefined ? {} : { revision: reproduced.revision }
+            )
+          : outcome === 'refactor'
+            ? yield* verify('verify:base', {})
+            : undefined
+
+      const implemented = yield* agentWorkOnce('implement', {
+        agent: 'implementer',
+        skill: 'implement',
+        prompt: implementPrompt(task, outcome, input.continuing),
+        output: Implemented
+      })
+
+      // Every criterion is answered before a reviewer reads the change; what is missing or unmet goes back once.
+      // An empty list says the Task has none; only a missing one goes back.
+      const unanswered = input.taskId !== undefined && implemented.criteria === undefined
+      const unmet = (implemented.criteria ?? []).filter(answer => answer.status === 'not_met')
+
+      const criteria =
+        unanswered || unmet.length > 0
+          ? (yield* agentWorkOnce('criteria', {
+              agent: 'implementer',
+              prompt: criteriaPrompt(unanswered, unmet),
+              output: Criteria
+            })).criteria
+          : (implemented.criteria ?? [])
+
+      const last = yield* rally({
+        maxRounds: input.maxRounds ?? 3,
+        // Against the target, not `revision`: a Build handed a revision, such as an Errand's head, reviews that change too.
+        base: `origin/${target ?? 'HEAD'}`,
+        target,
+        outcome,
+        claims: [...implemented.claims, ...criteria.map(answer => `Criterion ${answerLine(answer)}`)],
+        suggested: implemented.checks ?? []
+      })
+
+      const verdict = evidenceGate({
+        ...(outcome === undefined ? undefined : { outcome }),
+        head: last.head,
+        ...(base === undefined ? undefined : { base }),
+        ...(last.scope === undefined ? undefined : { review: last.scope }),
+        ...(reproduced === undefined ? undefined : { reproducing: reproduced.check }),
+        ...(implemented.documented === undefined ? undefined : { documented: implemented.documented }),
+        ...(implemented.rollback === undefined ? undefined : { rollback: implemented.rollback })
+      })
+
+      // An Outcome's gate may not read every check, so a failing one is reported here too, once.
+      const unsettled = [
+        ...new Set([
+          ...(verdict.settled ? [] : verdict.reasons),
+          ...brokenChecks(last.head).map(check => failsOn('head', check.name, last.head.tree)),
+          ...unsettledItems(last.settled, last.decision),
+          ...last.conflicts,
+          ...criteria.flatMap(answer =>
+            answer.status === 'not_met' ? [`Criterion not met: ${answer.criterion} (${answer.detail})`] : []
+          )
+        ])
+      ]
+
+      const body = changeRequestBody({
+        summary: implemented.summary,
+        head: last.head,
+        claims: last.claims,
+        unsettled,
+        criteria: criteria.map(answerLine),
+        later: last.settled.open
+          .filter(finding => !isBlocking(finding))
+          .map(finding => `${finding.id}: ${finding.detail}`),
+        rounds: last.round,
+        stopped: last.decision.reason
+      })
+
+      const named = input.changeRequestId === undefined ? undefined : input.continuing
+
+      const opened =
+        named === undefined
+          ? yield* changeRequest('change-request', { title: implemented.title, body })
+          : yield* comment('report', { changeRequestId: named.changeRequestId, body, summary: 'kitman-build' }).pipe(
+              Effect.as({ id: named.changeRequestId, number: named.number, url: named.url })
+            )
+
+      if (named === undefined)
+        yield* writeBack('write-back', { milestone: 'change_request_opened', changeRequestUrl: opened.url })
+
+      // The last round's Review passed on the head that ships, so it is the independent approval Shepherd waits for.
+      // Without one, Shepherd waits for a person's.
+      const approval =
+        unsettled.length === 0
+          ? yield* approveChangeRequest('approve', {
+              changeRequestId: opened.id,
+              head: last.head.revision,
+              summary: `Review round ${last.round} passed with nothing blocking.`,
+              review: `review:${last.round}`
+            }).pipe(
+              Effect.catchTag('StepFailed', error => Effect.succeed({ approved: false as const, reason: error.reason }))
+            )
+          : undefined
+
+      const landed =
+        input.land === true
+          ? yield* call('land', shepherd, {
+              changeRequestId: opened.id,
+              ...(input.taskId === undefined ? undefined : { taskId: input.taskId }),
+              ...(input.branch === undefined ? undefined : { branch: input.branch })
+            })
+          : undefined
+
+      return {
+        changeRequest: opened,
+        revision: last.head.revision,
+        tree: last.head.tree,
+        settled: unsettled.length === 0,
+        unsettled,
+        rounds: last.round,
+        stopped: last.decision.reason,
+        criteria,
+        ...(approval === undefined ? undefined : { approval }),
+        ...(landed === undefined ? undefined : { landed }),
+        next: { changeRequestId: opened.id }
+      }
+    }).pipe(Effect.tapError(() => Effect.ignore(writeBack('write-back:failed', { milestone: 'failed' }))))
+})

package/src/change-request-body.ts

@@ -0,0 +1,95 @@
+import type { MergedFinding, RallyDecision, ScopeJudgement, SettledRound, VerifyResult } from '@kitman-sh/sdk/loop'
+
+/** Each part of the Task the reviewer found not done, as a blocker the implementer fixes or rebuts like any other. */
+export const scopeFindings = (scope: ScopeJudgement | undefined): readonly MergedFinding[] =>
+  (scope?.unmet ?? []).map(item => ({
+    id: `scope: ${item}`,
+    severity: 'blocker',
+    file: '',
+    line: 0,
+    detail: 'The reviewer found this part of the Task not done.',
+    seats: ['code-review']
+  }))
+
+/** What fails on the head and not on the base, so the change broke it. */
+export const brokenChecks = (head: VerifyResult) =>
+  head.unchanged === true ? [] : head.checks.filter(check => check.status === 'failed' && !check.preExisting)
+
+export const isCheckFinding = (id: string) => id.startsWith('check: ')
+
+/** Each check the change broke, as a blocker with its output, which only the check passing closes. */
+export const checkFindings = (head: VerifyResult): readonly MergedFinding[] =>
+  brokenChecks(head).map(check => ({
+    id: `check: ${check.name}`,
+    severity: 'blocker',
+    file: '',
+    line: 0,
+    detail: [
+      `\`${check.command}\` fails on the head and passes on the base.`,
+      ...(check.outputTail === undefined ? [] : ['It printed:', '```', check.outputTail, '```'])
+    ].join('\n'),
+    seats: ['verify']
+  }))
+
+/** Why each item the rally could not settle is still open; a failing check is the evidence's to report. */
+export const unsettledItems = (settled: SettledRound, decision: RallyDecision & { readonly stop: true }) =>
+  decision.unsettled
+    .filter(id => !isCheckFinding(id))
+    .map(id => {
+      const standing = settled.standing.find(entry => entry.finding.id === id)
+
+      if (standing !== undefined)
+        return `Dispute stands on ${id}: ${standing.finding.detail} (rebutted: ${standing.rebuttal.reason})`
+
+      return `Unresolved ${settled.open.find(finding => finding.id === id)?.severity ?? 'blocker'} at ${id}: ${settled.open.find(finding => finding.id === id)?.detail ?? ''}`
+    })
+
+export const evidenceTable = (head: VerifyResult) =>
+  [
+    `Collected by a Runner for revision \`${head.revision}\`, tree \`${head.tree}\`; it holds for any revision with this tree.`,
+    '',
+    '| Check | Command | Result |',
+    '| --- | --- | --- |',
+    ...head.checks.map(
+      entry =>
+        `| ${entry.name}${entry.suggested === true ? ' (suggested by the agent)' : ''} | \`${entry.command}\` | ${entry.status}${entry.status === 'failed' && (entry.preExisting || head.unchanged === true) ? ' (also fails on the base branch)' : ''} |`
+    ),
+    ...(head.checks.some(entry => entry.suggested === true)
+      ? [
+          '',
+          "The repository has no approved verifications, so these are the agent's suggestions; check them, and approve the ones to keep with `kitman verify add`."
+        ]
+      : [])
+  ].join('\n')
+
+/** A ChangeRequest's description: the summary, the head's evidence, the claims and what was left unsettled. */
+export const changeRequestBody = (build: {
+  readonly summary: string
+  readonly head: VerifyResult
+  readonly claims: readonly string[]
+  readonly unsettled: readonly string[]
+  /** The implementer's answers to the Task's acceptance criteria. */
+  readonly criteria?: readonly string[]
+  /** Minor findings left for later; they never cost a round. */
+  readonly later?: readonly string[]
+  readonly rounds: number
+  readonly stopped: string
+}) =>
+  [
+    build.summary,
+    '## Evidence',
+    evidenceTable(build.head),
+    ...(build.criteria === undefined || build.criteria.length === 0
+      ? []
+      : ['## Acceptance criteria', ...build.criteria.map(answer => `- ${answer}`)]),
+    '## Claims',
+    'What the agent says and Kitman has not checked.',
+    ...(build.claims.length === 0 ? ['None.'] : build.claims.map(claim => `- ${claim}`)),
+    '## Unsettled',
+    ...(build.unsettled.length === 0 ? ['Nothing is unsettled.'] : build.unsettled.map(item => `- ${item}`)),
+    ...(build.later === undefined || build.later.length === 0
+      ? []
+      : ['## Left for later', ...build.later.map(item => `- ${item}`)]),
+    '## Review',
+    `${build.rounds} review round${build.rounds === 1 ? '' : 's'}; the rally stopped: ${build.stopped.replaceAll('_', ' ')}.`
+  ].join('\n\n')