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

package/src/research.ts

@@ -0,0 +1,225 @@
+import { agentWork, artifact, defineLoop, LoopOutcome, note, PlanTickets } from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+
+export class ResearchQuestionMissing extends Schema.TaggedError<ResearchQuestionMissing>()('ResearchQuestionMissing', {
+  message: Schema.String
+}) {}
+
+const Input = Schema.Struct({
+  /** The Task whose question to research. */
+  taskId: Schema.optional(Schema.String),
+  /** The question, when there is no Task. */
+  words: Schema.optional(Schema.String),
+  /** The repository to read; the Team's default repository when left out. */
+  repoBindingId: Schema.optional(Schema.String)
+})
+
+const Sources = Schema.NonEmptyArray(Schema.String)
+
+const Fix = Schema.Struct({
+  /** What to build, in words a Build starts from. */
+  words: Schema.String,
+  outcome: LoopOutcome
+})
+
+const NextSteps = Schema.Struct({ tickets: PlanTickets })
+
+const Report = Schema.Struct({
+  /** The Task's title, or a short title for the question. */
+  title: Schema.String,
+  summary: Schema.String,
+  findings: Schema.Array(
+    Schema.Struct({
+      finding: Schema.String,
+      /** observed: you ran it and saw it; read: a source says so; inferred: you concluded it. */
+      basis: Schema.Literals(['observed', 'read', 'inferred']),
+      sources: Sources
+    })
+  ),
+  /** Every primary source the report cites. */
+  sources: Sources,
+  /** Each source it needed and could not reach, with what it tried. */
+  unreached: Schema.Array(Schema.Struct({ source: Schema.String, tried: Schema.String })),
+  openQuestions: Schema.Array(Schema.String),
+  nextSteps: Schema.Array(Schema.String),
+  /** The change the report proposes, when it proposes one; outcome bug when the question is a bug report. */
+  fix: Schema.optionalKey(Fix),
+  /** The next steps as tickets someone may file as Tasks. */
+  nextStepTasks: Schema.optionalKey(NextSteps)
+})
+
+type Report = typeof Report.Type
+
+const Verdict = Schema.Struct({
+  /** Whether the conclusion follows from the cited evidence. */
+  supported: Schema.Boolean,
+  /** What the conclusion claims that its evidence does not show. */
+  gaps: Schema.Array(Schema.String)
+})
+
+const Output = Schema.Struct({
+  reportArtifactId: Schema.String,
+  /** Gaps the reviewer still found after one more pass. */
+  gaps: Schema.Array(Schema.String),
+  /** The sources the report needed and could not reach. */
+  unreached: Schema.Array(Schema.String),
+  fix: Schema.optionalKey(Fix),
+  nextStepTasks: Schema.optionalKey(NextSteps)
+})
+
+const researchPrompt = (words: string | undefined) =>
+  [
+    words === undefined
+      ? "Research the question this Task asks, using the `research` skill. The Task's title, description, Acceptance Criteria and comments are in your context."
+      : `Research this, using the \`research\` skill: ${words}`,
+    'If your context has an earlier research report on this, extend it: keep what still holds, check what may have changed, and answer what it left open. Do not start over.',
+    'Cite primary sources for every finding: the code, official documentation, specifications and first-party APIs. You may run things to reproduce behaviour; change nothing in the repository. Mark each finding observed (you ran it and saw it), read (a source says so) or inferred (you concluded it).',
+    'List every source you needed and could not reach under `unreached`, with what you tried, and lower your conclusions to what the sources you did reach show.',
+    'If the question turns out to be a bug report, say so in the summary and give `fix` with outcome bug. If the report proposes any other change, give `fix` with its outcome. Give next steps worth doing as `nextStepTasks` tickets too.',
+    'Return the report as your Output. Do not write it into the repository.'
+  ].join('\n\n')
+
+const reviewPrompt = (report: Report) =>
+  [
+    'Judge whether this research report is supported: does each conclusion follow from the evidence it cites? Check the cited sources where you can.',
+    'Answer supported, and list every gap: a claim its evidence does not show, including one that rests on a source listed as unreached. Do not ask for more scope; judge what it claims.',
+    '```json',
+    JSON.stringify(report, null, 2),
+    '```'
+  ].join('\n')
+
+const againPrompt = (words: string | undefined, gaps: readonly string[]) =>
+  [
+    researchPrompt(words),
+    'A reviewer found these claims unsupported by their evidence. Support each with evidence, or drop or weaken the claim:',
+    ...gaps.map(gap => `- ${gap}`)
+  ].join('\n\n')
+
+const list = (items: readonly string[]) => (items.length === 0 ? ['None.'] : items.map(item => `- ${item}`))
+
+const reportMarkdown = (report: Report, gaps: readonly string[]) =>
+  [
+    `# ${report.title}`,
+    '',
+    report.summary,
+    '',
+    ...(gaps.length === 0 ? [] : ['## Gaps', '', 'A reviewer found these unsupported:', '', ...list(gaps), '']),
+    '## Findings',
+    '',
+    ...report.findings.flatMap(({ finding, basis, sources }) => [
+      `- ${finding} (${basis})`,
+      ...sources.map(source => `  - ${source}`)
+    ]),
+    '',
+    '## Sources',
+    '',
+    ...list(report.sources),
+    '',
+    ...(report.unreached.length === 0
+      ? []
+      : ['## Out of reach', '', ...report.unreached.map(({ source, tried }) => `- ${source}: ${tried}`), '']),
+    '## Open questions',
+    '',
+    ...list(report.openQuestions),
+    '',
+    '## Next steps',
+    '',
+    ...list(report.nextSteps),
+    ...(report.fix === undefined ? [] : ['', '## Proposed fix', '', `${report.fix.words} (${report.fix.outcome})`])
+  ].join('\n')
+
+const sample = {
+  title: 'Does the API cap request bodies?',
+  summary: 'It does, at 1 MB.',
+  findings: [
+    {
+      finding: 'The server sets maxRequestBodySize to 1 MB.',
+      basis: 'read' as const,
+      sources: ['apps/api/src/server.ts:20']
+    }
+  ],
+  sources: ['apps/api/src/server.ts:20'],
+  unreached: [],
+  openQuestions: [],
+  nextSteps: []
+}
+
+/**
+ * Researches a Task's question or words against primary sources, reproducing what it can. A reviewer checks the
+ * conclusion follows from the evidence; an unsupported one goes back once, then ships with its gaps stated. The
+ * settled Run offers filing the next steps as Tasks and building a proposed fix. A re-run extends the earlier report.
+ */
+export default defineLoop({
+  id: 'research',
+  version: '2.0.0',
+  title: 'Research',
+  input: Input,
+  output: Output,
+  outcome: 'investigation',
+  agents: { researcher: 'researcher', reviewer: 'reviewer' },
+  checkout: 'read',
+  capabilities: ['agent_work'],
+  offers: [
+    { id: 'file-next-steps', title: 'File next steps as Tasks', loop: 'file-tasks', from: 'nextStepTasks' },
+    { id: 'build-fix', title: 'Build the fix', loop: 'build', from: 'fix' }
+  ],
+  checks: [
+    {
+      name: 'reports',
+      script: { input: { taskId: 'task-1' }, outputs: { research: sample, review: { supported: true, gaps: [] } } }
+    }
+  ],
+  run: input =>
+    Effect.gen(function* () {
+      if (input.taskId === undefined && input.words === undefined)
+        return yield* new ResearchQuestionMissing({ message: 'Give the question to research, or a Task' })
+
+      const first = yield* agentWork('research', {
+        agent: 'researcher',
+        prompt: researchPrompt(input.words),
+        output: Report
+      })
+
+      const firstVerdict = yield* agentWork('review', {
+        agent: 'reviewer',
+        prompt: reviewPrompt(first),
+        output: Verdict
+      })
+
+      const report = firstVerdict.supported
+        ? first
+        : yield* agentWork('research:again', {
+            agent: 'researcher',
+            prompt: againPrompt(input.words, firstVerdict.gaps),
+            output: Report
+          })
+
+      const gaps = firstVerdict.supported
+        ? []
+        : yield* agentWork('review:again', { agent: 'reviewer', prompt: reviewPrompt(report), output: Verdict }).pipe(
+            Effect.map(verdict => (verdict.supported ? [] : verdict.gaps))
+          )
+
+      // The tickets are in the Output, where the offer to file them reads them.
+      const { nextStepTasks: _, ...data } = report
+
+      const { artifactId } = yield* artifact('report', {
+        kind: 'research_report',
+        title: report.title,
+        text: reportMarkdown(report, gaps),
+        data
+      })
+
+      // A Run from words alone has no Task thread to post to.
+      if (input.taskId !== undefined) yield* note('summary', { text: report.summary, artifactId })
+
+      return {
+        reportArtifactId: artifactId,
+        gaps,
+        unreached: report.unreached.map(({ source }) => source),
+        ...(report.fix === undefined ? undefined : { fix: report.fix }),
+        ...(report.nextStepTasks === undefined ? undefined : { nextStepTasks: report.nextStepTasks })
+      }
+    })
+})

package/src/review.ts

@@ -0,0 +1,397 @@
+import {
+  agentWork,
+  approveChangeRequest,
+  artifact,
+  ask,
+  call,
+  comment,
+  defineLoop,
+  type CalledLoop,
+  Finding,
+  isBlocking,
+  LoopOutcome,
+  MergedFinding,
+  mergeFindings,
+  Rebuttal,
+  RebuttalVerdict,
+  pipelineStatus,
+  ScopeJudgement
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+import build, { BuildInput, BuildOutput } from './build'
+
+/** Build, by its schemas: the module imports this one, so its definition is not ready when this one loads. */
+const buildLoop = () => ({ id: 'build', input: BuildInput, output: BuildOutput })
+
+/** The two reviewers: each follows one Kit's review skill, and what it looks for when that skill is not installed. */
+const seats = {
+  'code-review': {
+    skill: 'code-review',
+    focus:
+      "Review along two axes: Standards (does the change follow the repository's documented conventions?) and Spec (does it do what was asked?)."
+  },
+  quality: {
+    skill: 'code-review-and-quality',
+    focus: 'Review across correctness, readability, architecture, security and performance.'
+  }
+} as const
+
+const seatNames = ['code-review', 'quality'] as const
+
+/** The seat that judges the Task's scope: its skill reviews against the spec. */
+const scopeSeat = 'code-review'
+
+const choices = ['Post to the ChangeRequest', 'Fix here', 'Build from it', 'Done'] as const
+
+const Input = Schema.Struct({
+  /** Reviews this ChangeRequest, then asks what next: posting, fixing and building are each the user's call. */
+  changeRequestId: Schema.optional(Schema.String),
+  /** Or reviews `git diff base...head`, and only returns the findings. */
+  base: Schema.optional(Schema.String),
+  head: Schema.optional(Schema.String),
+  /**
+   * With `base` and `head`, reviews only these files of the change, such as the conflicts a catch-up merge settled; the
+   * rest was approved before. It judges no scope and approves nothing itself.
+   */
+  files: Schema.optional(Schema.Array(Schema.String)),
+  /** With `files`, also reviews everything in `git diff since..head`, such as a fix made after the files' review. */
+  since: Schema.optional(Schema.String),
+  /** The implementer's rebuttals of the last round's findings, for the panel to judge. */
+  rebuttals: Schema.optional(Schema.Array(Rebuttal)),
+  /** The Outcome the change must prove. */
+  outcome: Schema.optional(LoopOutcome),
+  /** What the implementer claims it built, for the scope seat to check. */
+  claims: Schema.optional(Schema.Array(Schema.String)),
+  /** An earlier review's open findings: each is checked as fixed, changed or still there, keeping its id. */
+  earlier: Schema.optional(Schema.Array(MergedFinding)),
+  /** The checks that fail on the head and pass on the base, which the implementer is already told. */
+  failing: Schema.optional(Schema.Array(Schema.String)),
+  /** What to do after a ChangeRequest's review without asking; Done when nobody answers. */
+  next: Schema.optional(Schema.Literals(choices))
+})
+
+const FollowUpStatus = Schema.Literals(['fixed', 'changed', 'still_there'])
+
+const FollowUp = Schema.Struct({ id: Schema.String, status: FollowUpStatus })
+
+const SeatOutput = Schema.Struct({
+  /** One sentence: can it merge, and what matters most. */
+  summary: Schema.String,
+  findings: Schema.Array(Finding),
+  verdicts: Schema.optional(Schema.Array(RebuttalVerdict)),
+  scope: Schema.optional(ScopeJudgement),
+  followUps: Schema.optional(Schema.Array(FollowUp))
+})
+
+const Output = Schema.Struct({
+  /** What the review leads with: each reviewer's one sentence. */
+  summary: Schema.String,
+  findings: Schema.Array(MergedFinding),
+  /** Each earlier finding, as fixed, changed but not fixed, or still there. */
+  followUps: Schema.Array(FollowUp),
+  verdicts: Schema.Array(RebuttalVerdict),
+  blocking: Schema.Boolean,
+  artifactId: Schema.String,
+  /** The scope seat's judgement of the Task's scope; absent when there was no Task to judge against. */
+  scope: Schema.optional(ScopeJudgement),
+  /** Kitman's approval of the ChangeRequest's head, recorded when nothing blocks it; or why it was refused. */
+  approval: Schema.optional(
+    Schema.Struct({ head: Schema.String, approved: Schema.Boolean, reason: Schema.optional(Schema.String) })
+  ),
+  /** What happened after a ChangeRequest's review. */
+  next: Schema.optional(Schema.Struct({ choice: Schema.Literals(choices), detail: Schema.optional(Schema.String) }))
+})
+
+export class ReviewTargetMissing extends Schema.TaggedError<ReviewTargetMissing>()('ReviewTargetMissing', {
+  message: Schema.String
+}) {}
+
+const targetOf = (input: typeof Input.Type, head?: string) => {
+  if (input.changeRequestId !== undefined)
+    return `ChangeRequest ${input.changeRequestId} at revision ${head}. Read it with \`kitman.changeRequests.get("${input.changeRequestId}")\` through Kitman's MCP, fetch its source branch, and review the diff of revision ${head} against its target branch, even if the branch has moved since. If the Runner cannot fetch that revision (a fork, say), report exactly that as your only finding, a blocker, and stop.`
+
+  if (input.base !== undefined && input.head !== undefined)
+    return input.files === undefined
+      ? `the change \`git diff ${input.base}...${input.head}\` in your checkout.`
+      : [
+          `only these files of the change \`git diff ${input.base}...${input.head}\` in your checkout; the rest of it was reviewed and approved before:`,
+          ...input.files.map(file => `- ${file}`),
+          ...(input.since === undefined
+            ? []
+            : [`Also review all of \`git diff ${input.since}..${input.head}\`, whichever files it touches.`])
+        ].join('\n')
+
+  return undefined
+}
+
+const scopePrompt = (input: typeof Input.Type) =>
+  [
+    "If your brief has a Task, judge its scope and give it as `scope`: does the change do what the Task's description and each of its Acceptance Criteria ask? Set `met` to true only if it does all of it, and list in `unmet` one line for each criterion or part of the description that is not done. If your brief has no Task, leave `scope` out.",
+    ...(input.outcome === undefined ? [] : [`The Outcome to prove is ${input.outcome}.`]),
+    ...(input.claims === undefined || input.claims.length === 0
+      ? []
+      : [
+          'The implementer claims it built these. Check them against the code rather than taking them on trust:',
+          ...input.claims.map(claim => `- ${claim}`)
+        ])
+  ].join('\n\n')
+
+const earlierPrompt = (earlier: readonly MergedFinding[]) =>
+  [
+    'An earlier review found these. Give each as a `followUps` entry with its id: fixed, changed (the code moved but the problem stands) or still_there. Do not report them again as findings; review only what changed since, for new problems.',
+    ...earlier.map(finding => `- ${finding.id} (${finding.severity}): ${finding.detail}`)
+  ].join('\n')
+
+const promptFor = (seat: keyof typeof seats, target: string, input: typeof Input.Type) =>
+  [
+    `You are one of two reviewers. Follow your \`${seats[seat].skill}\` skill; if you do not have it: ${seats[seat].focus}`,
+    `Review ${target}`,
+    'Give `summary`: one sentence on whether it can merge and what matters most.',
+    'Report each problem as a finding: severity blocker (must not ship), major (fix before merge) or minor (optional); the file path from the repository root; the line; and the detail. When it is one instance of a class of bug, name every other instance in the diff in its detail. Report nothing you have not checked in the code.',
+    'If the diff is too big to review in one go, review it directory by directory and say so in a finding on the first file you skipped.',
+    ...(seat === scopeSeat && input.files === undefined ? [scopePrompt(input)] : []),
+    ...(input.earlier === undefined || input.earlier.length === 0 ? [] : [earlierPrompt(input.earlier)]),
+    ...(input.failing === undefined || input.failing.length === 0
+      ? []
+      : [
+          `These checks fail on this head and pass on the base: ${input.failing.join(', ')}. The implementer has their output, so do not report them as findings, and do not say it can merge while they fail.`
+        ]),
+    ...(input.rebuttals === undefined || input.rebuttals.length === 0
+      ? []
+      : [
+          'The implementer disputes these findings. For each, give a verdict: accepted if the rebuttal is right and the finding should be dropped.',
+          ...input.rebuttals.map(rebuttal => `- ${rebuttal.findingId}: ${rebuttal.reason}`)
+        ])
+  ].join('\n\n')
+
+const rank = { still_there: 0, changed: 1, fixed: 2 } as const
+
+/** Each earlier finding's status: the worst any seat gave, and still there when no seat answered for it. */
+const followUpsOf = (earlier: readonly MergedFinding[], answers: readonly (typeof FollowUp.Type)[]) =>
+  earlier.map(finding => {
+    const statuses = answers.flatMap(answer => (answer.id === finding.id ? [answer.status] : []))
+
+    return {
+      id: finding.id,
+      status:
+        statuses.length === 0
+          ? ('still_there' as const)
+          : statuses.reduce((worst, status) => (rank[status] < rank[worst] ? status : worst))
+    }
+  })
+
+const reviewText = (
+  summary: string,
+  findings: readonly MergedFinding[],
+  followUps: readonly (typeof FollowUp.Type)[]
+) =>
+  [
+    `**Kitman review.** ${summary}`,
+    ...(findings.length === 0
+      ? []
+      : [
+          findings
+            .map(
+              finding => `- **${finding.severity}** \`${finding.id}\` ${finding.detail} _(${finding.seats.join(', ')})_`
+            )
+            .join('\n')
+        ]),
+    ...(followUps.length === 0
+      ? []
+      : [
+          `Earlier findings:\n${followUps.map(entry => `- \`${entry.id}\` ${entry.status.replace('_', ' ')}`).join('\n')}`
+        ])
+  ].join('\n\n')
+
+const fixBrief = (changeRequestId: string, findings: readonly MergedFinding[]) =>
+  [
+    `Fix what a review of ChangeRequest ${changeRequestId} found, on its branch:`,
+    ...findings.map(finding => `- ${finding.id} (${finding.severity}): ${finding.detail}`)
+  ].join('\n')
+
+/**
+ * Reviews a ChangeRequest or a revision range with two reviewer Agents, one following the `code-review` skill and one
+ * `code-review-and-quality`, and writes one review from their findings, each said once. Given an earlier review's
+ * findings it follows them up, keeping their ids. On a ChangeRequest it approves the head it reviewed when nothing
+ * blocks it, unless it wrote the change, then asks what next and posts only when told to, as one summary
+ * comment it edits on later reviews.
+ */
+export default defineLoop({
+  id: 'review',
+  version: '3.3.0',
+  title: 'Review',
+  input: Input,
+  output: Output,
+  agents: { 'code-review': 'code-reviewer', quality: 'quality-reviewer' },
+  checkout: 'read',
+  // Build's, for Fix here and Build from it.
+  capabilities: [
+    'agent_work',
+    'post_comment',
+    'ask',
+    'call',
+    'verify',
+    'change_request',
+    'write_back',
+    'read_change_request',
+    'merge_change_request',
+    'approve_change_request'
+  ],
+  calls: (): readonly CalledLoop[] => [build],
+  offers: [
+    { id: 'build', title: 'Build from it', loop: 'build' },
+    { id: 'review', title: 'Review again', loop: 'review' }
+  ],
+  run: input =>
+    Effect.gen(function* () {
+      // The head is read first, so an approval approves the commit the reviewers read.
+      const head =
+        input.changeRequestId === undefined
+          ? undefined
+          : (yield* pipelineStatus('head', { changeRequestId: input.changeRequestId })).head
+
+      const target = targetOf(input, head)
+
+      if (target === undefined)
+        return yield* new ReviewTargetMissing({ message: 'Name a ChangeRequest, or both base and head revisions' })
+
+      const outputs = yield* Effect.forEach(
+        seatNames,
+        seat =>
+          agentWork(`review:${seat}`, {
+            agent: seat,
+            prompt: promptFor(seat, target, input),
+            output: SeatOutput
+          }).pipe(Effect.map(output => [seat, output] as const)),
+        { concurrency: 'unbounded' }
+      )
+
+      const earlier = input.earlier ?? []
+      const earlierIds = new Set(earlier.map(finding => finding.id))
+
+      const followUps = followUpsOf(
+        earlier,
+        outputs.flatMap(([, output]) => output.followUps ?? [])
+      )
+
+      const standing = new Set(followUps.flatMap(entry => (entry.status === 'fixed' ? [] : [entry.id])))
+
+      const carried = earlier.filter(finding => standing.has(finding.id))
+
+      const fresh = mergeFindings(
+        Object.fromEntries(
+          outputs.map(([seat, output]) => [
+            seat,
+            output.findings.filter(finding => !earlierIds.has(`${finding.file}:${finding.line}`))
+          ])
+        )
+      )
+
+      const findings = [...carried, ...fresh]
+
+      const summary =
+        findings.length === 0
+          ? 'No findings: nothing stands in the way of merging.'
+          : outputs.map(([, output]) => output.summary).join(' ')
+
+      const freshIds = new Set(fresh.map(finding => finding.id))
+      const text = reviewText(summary, findings, followUps)
+      const scope = input.files === undefined ? outputs.find(([seat]) => seat === scopeSeat)?.[1].scope : undefined
+
+      const stored = yield* artifact('findings', {
+        kind: 'review-findings',
+        title: 'Review findings',
+        text,
+        data: { findings, followUps }
+      })
+
+      const reviewed = {
+        summary,
+        findings,
+        followUps,
+        verdicts: outputs.flatMap(([, output]) => output.verdicts ?? []),
+        blocking: findings.some(isBlocking),
+        artifactId: stored.artifactId,
+        ...(scope === undefined ? undefined : { scope })
+      }
+
+      const changeRequestId = input.changeRequestId
+
+      if (changeRequestId === undefined || head === undefined) return reviewed
+
+      const approval =
+        reviewed.blocking || scope?.met === false || (input.failing?.length ?? 0) > 0
+          ? undefined
+          : yield* approveChangeRequest('approve', { changeRequestId, head, summary }).pipe(
+              Effect.map(result =>
+                result.approved ? { head, approved: true } : { head, approved: false, reason: result.reason }
+              )
+            )
+
+      const answer =
+        input.next ??
+        (yield* ask('next', {
+          prompt: `${summary}\n\nWhat next?`,
+          options: [
+            { value: 'Post to the ChangeRequest', description: 'Comments the findings on the ChangeRequest.' },
+            { value: 'Fix here', description: 'A Build fixes them and pushes to this ChangeRequest.' },
+            { value: 'Build from it', description: 'A Build fixes them in a new ChangeRequest.' },
+            { value: 'Done', description: 'Keeps the review as an artifact and stops.' }
+          ] satisfies { readonly value: (typeof choices)[number]; readonly description: string }[],
+          recommended: reviewed.blocking ? 'Fix here' : 'Done',
+          recommendationReason: reviewed.blocking
+            ? 'A blocking finding stops the merge, and fixing it here is the shortest way through.'
+            : 'Nothing blocks the merge, so the findings can wait in the Run.',
+          default: 'Done',
+          timeout: '1 hour'
+        }))
+
+      const choice = choices.find(option => option === answer) ?? 'Done'
+
+      const next = yield* Effect.gen(function* () {
+        if (choice === 'Post to the ChangeRequest') {
+          yield* comment('post', { changeRequestId, body: text, summary: 'kitman-review' })
+
+          // Earlier findings were anchored by the Run that found them; the summary carries them all.
+          const anchors = findings.flatMap(finding =>
+            !freshIds.has(finding.id) || finding.line < 1
+              ? []
+              : [{ file: finding.file, line: finding.line, body: `**${finding.severity}:** ${finding.detail}` }]
+          )
+
+          if (anchors.length === 0) return { choice }
+
+          // A line outside the diff refuses the lot; the summary comment still carries every finding.
+          return yield* comment('anchors', { changeRequestId, body: '', anchors }).pipe(
+            Effect.as({ choice }),
+            Effect.catchTag('StepFailed', error =>
+              Effect.succeed({ choice, detail: `Posted the summary; the line comments failed: ${error.reason}` })
+            )
+          )
+        }
+
+        if (choice === 'Fix here') {
+          const fixed = yield* call('fix', buildLoop(), {
+            words: fixBrief(changeRequestId, findings),
+            changeRequestId,
+            maxRounds: 2
+          })
+
+          return { choice, detail: fixed.settled ? 'Fixed and pushed' : `Pushed; left: ${fixed.unsettled.join('; ')}` }
+        }
+
+        if (choice === 'Build from it') {
+          const built = yield* call('build', buildLoop(), { words: fixBrief(changeRequestId, findings) })
+
+          return { choice, detail: built.changeRequest.url }
+        }
+
+        return { choice, detail: 'The review is kept as an artifact' }
+      }).pipe(Effect.catchTag('ChildFailed', failed => Effect.succeed({ choice, detail: failed.reason })))
+
+      return { ...reviewed, ...(approval === undefined ? undefined : { approval }), next }
+    })
+})
+
+export { Input as ReviewInput, Output as ReviewOutput }

package/src/shepherd-output.ts

@@ -0,0 +1,10 @@
+import * as Schema from 'effect/Schema'
+
+/** Shepherd's Output, outside shepherd.ts so Build can import it without the review → build → shepherd cycle. */
+export const ShepherdOutput = Schema.Struct({
+  status: Schema.Literals(['merged', 'ready', 'needs_you']),
+  /** Why it stopped, in a line a person can act on. */
+  reason: Schema.String,
+  fixRounds: Schema.Int,
+  replies: Schema.Int
+})