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

package/src/sweep.ts

@@ -0,0 +1,385 @@
+import {
+  agentWork,
+  artifact,
+  call,
+  changeRequest,
+  ChangeRequestResult,
+  closeChangeRequest,
+  defineLoop,
+  openChangeRequests,
+  ownChangeRequests,
+  verify,
+  type OpenChangeRequests,
+  type VerifyResult
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+import shepherd from './shepherd'
+
+const Input = Schema.Struct({
+  /** The dependency bots' logins; Renovate's and Dependabot's on GitHub when left out. */
+  authors: Schema.optional(Schema.NonEmptyArray(Schema.String)),
+  /** The branch the batch targets; the repository's default branch when left out. */
+  branch: Schema.optional(Schema.String),
+  repoBindingId: Schema.optional(Schema.String),
+  /** Rounds of fixing what the batch breaks before an update is dropped instead; 2 when left out. */
+  maxFixRounds: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(5)))
+})
+
+const Decision = Schema.Literals(['batch', 'alone', 'hold'])
+
+const Assessed = Schema.Struct({
+  updates: Schema.Array(
+    Schema.Struct({
+      number: Schema.String,
+      /** batch: safe to land with the others; alone: needs its own review; hold: should not land now. */
+      decision: Decision,
+      reason: Schema.String,
+      /** Whether it bumps a major version. */
+      major: Schema.Boolean
+    })
+  )
+})
+
+const Batched = Schema.Struct({
+  /** The updates now on the branch. */
+  applied: Schema.Array(Schema.String),
+  /** The updates taken out, each with why. */
+  dropped: Schema.Array(Schema.Struct({ number: Schema.String, reason: Schema.String })),
+  summary: Schema.String
+})
+
+type Batched = typeof Batched.Type
+
+const Placed = Schema.Struct({ number: Schema.String, title: Schema.String, url: Schema.String, reason: Schema.String })
+
+type Placed = typeof Placed.Type
+
+const Output = Schema.Struct({
+  /** nothing_to_sweep: the bots have nothing open; reported: nothing could be batched or it did not pass. */
+  status: Schema.Literals(['nothing_to_sweep', 'reported', 'opened', 'landed']),
+  summary: Schema.String,
+  landed: Schema.Array(Placed),
+  /** Left for a person: updates that go alone, are held, or dropped out of the batch. */
+  left: Schema.Array(Placed),
+  reportArtifactId: Schema.optional(Schema.String),
+  changeRequest: Schema.optional(ChangeRequestResult)
+})
+
+type Output = typeof Output.Type
+
+type Bot = OpenChangeRequests['changeRequests'][number]
+
+const defaultAuthors = ['renovate[bot]', 'dependabot[bot]'] as const
+
+const listing = (requests: readonly Bot[]) =>
+  requests
+    .map(request =>
+      [
+        `### !${request.number} ${request.title}`,
+        `Branch \`${request.sourceBranch}\` at ${request.head}, ${request.url}`,
+        request.body
+      ].join('\n\n')
+    )
+    .join('\n\n')
+
+const assessPrompt = (requests: readonly Bot[]) =>
+  [
+    'These dependency updates are open. Read each one’s changelog and breaking-change notes, and what in this repository uses it.',
+    listing(requests),
+    'Decide for each: batch when it is safe to land with the others; alone when it needs its own review, such as a breaking change that needs code changes; hold when it should not land now, saying why.',
+    'Say whether it bumps a major version. Change nothing.'
+  ].join('\n\n')
+
+const batchPrompt = (requests: readonly Bot[], target: string) =>
+  [
+    `Bring these dependency updates onto this branch, which starts from ${target}: for each, merge \`origin/<branch>\` at the head named; Kitman fetched origin just before this Step, so do not fetch. Where lockfiles conflict, regenerate them with the package manager instead of hand-merging.`,
+    listing(requests),
+    'An update that cannot be brought in cleanly is dropped: leave it out and say why. Commit nothing yourself; Kitman pushes what you leave.'
+  ].join('\n\n')
+
+const fixPrompt = (failed: VerifyResult, applied: readonly string[]) =>
+  [
+    `The batch of ${applied.map(number => `!${number}`).join(', ')} fails these checks:`,
+    ...failed.checks.filter(check => check.status === 'failed').map(check => `- ${check.name}: \`${check.command}\``),
+    'Fix what an update broke, the way its changelog says to. If an update cannot be fixed in a small change, take it back out and drop it with the reason. Commit nothing yourself.'
+  ].join('\n\n')
+
+const supersedes = 'Supersedes:'
+
+/** An update a batch brings in, at the head it was brought in at. */
+type Landing = Placed & { readonly head: string }
+
+const supersededLine = (update: Landing) => `- !${update.number} ${update.title} (${update.url}) at ${update.head}`
+
+/** The updates a batch's description says it supersedes, as `supersededLine` wrote them. */
+const supersededIn = (body: string): Landing[] => {
+  const after = body.split(supersedes)[1] ?? ''
+  const listed = after.split('Left for a person:')[0] ?? ''
+
+  return listed.split('\n').flatMap(line => {
+    const found = /^- !(\S+) (.+) \((\S+)\) at (\S+)$/u.exec(line.trim())
+
+    return found === null
+      ? []
+      : [
+          {
+            number: found[1] ?? '',
+            title: found[2] ?? '',
+            url: found[3] ?? '',
+            head: found[4] ?? '',
+            reason: 'Verified in the batch'
+          }
+        ]
+  })
+}
+
+/**
+ * Closes each update a merged batch landed, with a note pointing at the batch. One the bot pushed to after it was
+ * batched stays open: its new head landed nowhere. Returns those, for a person.
+ */
+const closeSuperseded = (landing: readonly Landing[], batchUrl: string) =>
+  Effect.map(
+    Effect.forEach(landing, ({ head, ...update }) =>
+      Effect.map(
+        closeChangeRequest(`close:${update.number}`, {
+          number: update.number,
+          head,
+          note: `Landed in ${batchUrl} with the other dependency updates Sweep verified together.`
+        }),
+        closed =>
+          closed.head === undefined
+            ? []
+            : [{ ...update, reason: `The bot pushed ${closed.head} after Sweep batched ${head}, so it stays open` }]
+      )
+    ),
+    moved => moved.flat()
+  )
+
+/** What landed and what is left once the updates that moved are left open. */
+const afterClosing = (landing: readonly Landing[], left: readonly Placed[], moved: readonly Placed[]) => ({
+  landed: landing.flatMap(({ head: _head, ...update }) =>
+    moved.some(open => open.number === update.number) ? [] : [update]
+  ),
+  left: [...left, ...moved]
+})
+
+const reportText = (landing: readonly Placed[], left: readonly Placed[], heading: string) =>
+  [
+    heading,
+    ...(landing.length === 0 ? [] : ['Landing:', ...landing.map(update => `- !${update.number} ${update.title}`)]),
+    ...(left.length === 0
+      ? []
+      : ['Left for a person:', ...left.map(update => `- !${update.number} ${update.title}: ${update.reason}`)])
+  ].join('\n')
+
+/**
+ * Gathers the dependency bot's open ChangeRequests, lands the safe ones together, and leaves the rest explained. Each
+ * update is classified batch, alone or hold with a reason; a major version bump is never batched silently. The batch
+ * is built from the bots' heads read again just before, verified, and fixed for a bounded number of rounds; an update
+ * that still breaks drops out with its reason. One ChangeRequest names each update it supersedes and is shepherded to
+ * merge once approved; then the superseded ChangeRequests are closed with a note.
+ */
+export default defineLoop({
+  id: 'sweep',
+  version: '1.0.0',
+  title: 'Sweep',
+  input: Input,
+  output: Output,
+  agents: { assessor: 'investigator', implementer: 'implementer' },
+  checkout: 'write',
+  schedule: { rule: { frequency: 'weekly', daysOfWeek: [1], hour: 6, minute: 0 }, timezone: 'UTC' },
+  capabilities: ['agent_work', 'verify', 'change_request', 'read_change_request', 'merge_change_request'],
+  calls: () => [shepherd],
+  run: input =>
+    Effect.gen(function* () {
+      const authors = input.authors ?? defaultAuthors
+
+      // A batch an earlier Sweep left open is landed, not batched again beside it.
+      const [earlier] = (yield* ownChangeRequests('earlier')).changeRequests
+
+      if (earlier !== undefined) {
+        const landed = yield* call('land', shepherd, {
+          changeRequestId: earlier.id,
+          merge: true,
+          ...(input.branch === undefined ? undefined : { branch: input.branch })
+        })
+
+        const summary = `${earlier.url}, from an earlier Sweep, is still open; Sweep took it on instead of batching again: ${landed.status}. ${landed.reason}`
+        // Its description names what it supersedes, so merging it closes those as a fresh batch would.
+        const landing = supersededIn(earlier.body)
+
+        const settled = afterClosing(
+          landing,
+          [],
+          landed.status === 'merged' ? yield* closeSuperseded(landing, earlier.url) : []
+        )
+
+        const stored = yield* artifact('report', {
+          kind: 'sweep_report',
+          title: 'Sweep',
+          text: reportText(settled.landed, settled.left, summary)
+        })
+
+        return {
+          status: landed.status === 'merged' ? 'landed' : 'opened',
+          summary,
+          ...settled,
+          reportArtifactId: stored.artifactId,
+          changeRequest: { id: earlier.id, number: earlier.number, url: earlier.url }
+        } satisfies Output
+      }
+
+      const open = (yield* openChangeRequests('bots', { authors })).changeRequests
+
+      if (open.length === 0)
+        return {
+          status: 'nothing_to_sweep',
+          summary: 'The bots have nothing open.',
+          landed: [],
+          left: []
+        } satisfies Output
+
+      const assessed = yield* agentWork('assess', { agent: 'assessor', prompt: assessPrompt(open), output: Assessed })
+
+      const decisions = open.map(request => {
+        const decided = assessed.updates.find(update => update.number === request.number)
+        const placed = { number: request.number, title: request.title, url: request.url }
+
+        if (decided === undefined) return { ...placed, decision: 'hold', reason: 'It was not assessed' } as const
+
+        if (decided.major && decided.decision === 'batch')
+          return { ...placed, decision: 'alone', reason: `A major version bump goes alone. ${decided.reason}` } as const
+
+        return { ...placed, decision: decided.decision, reason: decided.reason }
+      })
+
+      const notBatched: Placed[] = decisions.flatMap(({ decision, ...placed }) =>
+        decision === 'batch' ? [] : [placed]
+      )
+
+      const batch = decisions.filter(update => update.decision === 'batch')
+
+      const reported = (status: 'reported', summary: string, left: readonly Placed[]) =>
+        Effect.map(
+          artifact('report', { kind: 'sweep_report', title: 'Sweep', text: reportText([], left, summary) }),
+          stored => ({ status, summary, landed: [], left, reportArtifactId: stored.artifactId }) satisfies Output
+        )
+
+      if (batch.length === 0) return yield* reported('reported', 'Nothing is safe to batch.', notBatched)
+
+      // The bots rebase on their own schedule: build from their heads as they are now, not as assessed.
+      const now = (yield* openChangeRequests('bots:again', { authors })).changeRequests
+      const toBatch = now.filter(request => batch.some(update => update.number === request.number))
+
+      const gone: Placed[] = batch.flatMap(update =>
+        toBatch.some(request => request.number === update.number)
+          ? []
+          : [
+              {
+                number: update.number,
+                title: update.title,
+                url: update.url,
+                reason: 'It was closed or merged while Sweep ran'
+              }
+            ]
+      )
+
+      const target = input.branch ?? 'the default branch'
+
+      let batched: Batched = yield* agentWork('batch', {
+        agent: 'implementer',
+        prompt: batchPrompt(toBatch, target),
+        output: Batched
+      })
+
+      let checked = yield* verify('verify', {})
+      const maxFixRounds = input.maxFixRounds ?? 2
+      const dropped = new Map(batched.dropped.map(drop => [drop.number, drop.reason]))
+
+      for (let round = 1; !checked.passed && round <= maxFixRounds && batched.applied.length > 0; round++) {
+        batched = yield* agentWork(`fix:${round}`, {
+          agent: 'implementer',
+          prompt: fixPrompt(checked, batched.applied),
+          output: Batched
+        })
+
+        for (const drop of batched.dropped) dropped.set(drop.number, drop.reason)
+        checked = yield* verify(`verify:${round}`, {})
+      }
+
+      const titled = (number: string) => toBatch.find(request => request.number === number)
+
+      const droppedOut: Placed[] = toBatch.flatMap(request => {
+        const reason =
+          dropped.get(request.number) ??
+          (batched.applied.includes(request.number) ? undefined : 'It was not brought onto the branch')
+
+        return reason === undefined ? [] : [{ number: request.number, title: request.title, url: request.url, reason }]
+      })
+
+      const left = [...notBatched, ...gone, ...droppedOut]
+
+      const landing: Landing[] = batched.applied.flatMap(number => {
+        const request = titled(number)
+
+        return request === undefined
+          ? []
+          : [{ number, title: request.title, url: request.url, head: request.head, reason: 'Verified in the batch' }]
+      })
+
+      if (landing.length === 0) return yield* reported('reported', 'No update survived the batch.', left)
+
+      if (!checked.passed) {
+        const failing = checked.checks.filter(check => check.status === 'failed').map(check => check.name)
+
+        return yield* reported(
+          'reported',
+          `The batch still fails ${failing.join(', ')} after ${maxFixRounds} rounds of fixing.`,
+          [...left, ...landing.map(({ head: _head, ...update }) => ({ ...update, reason: 'The batch did not pass' }))]
+        )
+      }
+
+      const opened = yield* changeRequest('change-request', {
+        title: `Update ${landing.length} ${landing.length === 1 ? 'dependency' : 'dependencies'}`,
+        body: [
+          batched.summary,
+          supersedes,
+          ...landing.map(supersededLine),
+          ...(left.length === 0
+            ? []
+            : ['Left for a person:', ...left.map(update => `- !${update.number} ${update.title}: ${update.reason}`)])
+        ].join('\n\n')
+      })
+
+      const landed = yield* call('land', shepherd, {
+        changeRequestId: opened.id,
+        merge: true,
+        ...(input.branch === undefined ? undefined : { branch: input.branch })
+      })
+
+      const merged = landed.status === 'merged'
+      const closed = afterClosing(landing, left, merged ? yield* closeSuperseded(landing, opened.url) : [])
+
+      const stored = yield* artifact('report', {
+        kind: 'sweep_report',
+        title: 'Sweep',
+        text: reportText(closed.landed, closed.left, `${opened.url}: ${landed.status}. ${landed.reason}`)
+      })
+
+      const settled = { ...closed, reportArtifactId: stored.artifactId, changeRequest: opened }
+
+      if (!merged)
+        return {
+          status: 'opened',
+          summary: `${opened.url} is ${landed.status}: ${landed.reason}`,
+          ...settled
+        } satisfies Output
+
+      return {
+        status: 'landed',
+        summary: `Landed ${closed.landed.length} in ${opened.url}`,
+        ...settled
+      } satisfies Output
+    })
+})

package/src/tidy.ts

@@ -0,0 +1,286 @@
+import {
+  agentWork,
+  artifact,
+  ask,
+  call,
+  changeRequest,
+  ChangeRequestResult,
+  defineLoop,
+  evidenceGate,
+  RunFile,
+  rallyStop,
+  settleRound,
+  syncBase,
+  verify
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+import { changeRequestBody, unsettledItems } from './change-request-body'
+import plan from './plan'
+import review from './review'
+
+const Input = Schema.Struct({
+  /**
+   * The head of a change to tidy, such as a Build's: Tidy then touches only that change's area and opens at most one
+   * ChangeRequest, unasked. Left out, Tidy surveys and asks what next.
+   */
+  revision: Schema.optional(Schema.String),
+  /** The branch the ChangeRequest targets; the repository's default branch when left out. */
+  branch: Schema.optional(Schema.String),
+  repoBindingId: Schema.optional(Schema.String),
+  /** Where to look, in a few words. */
+  words: Schema.optional(Schema.String)
+})
+
+const Hint = Schema.Literals(['architecture', 'simplification'])
+
+const Candidate = Schema.Struct({
+  title: Schema.String,
+  /** What to change, in words a tidy or a plan starts from. */
+  words: Schema.String,
+  hint: Hint,
+  /** Why it is worth a reviewer's time. */
+  worth: Schema.String
+})
+
+const Survey = Schema.Struct({
+  /** The report, as Markdown. */
+  report: Schema.String,
+  /** The skill's HTML report, attached to the Run. */
+  htmlReport: Schema.optional(RunFile),
+  /** The improvements worth making, most valuable first; none when nothing is worth it. */
+  candidates: Schema.Array(Candidate),
+  /** Only what the code cannot tell, such as intent or plans; at most three. */
+  questions: Schema.Array(
+    Schema.Struct({
+      question: Schema.String,
+      /** The answer the surveyor would assume. */
+      recommended: Schema.String,
+      /** Why, in one or two sentences. */
+      why: Schema.String
+    })
+  ).check(Schema.isMaxLength(3))
+})
+
+const Tidied = Schema.Struct({
+  /** Whether it changed anything; false is a good outcome when nothing is worth it. */
+  improved: Schema.Boolean,
+  hint: Schema.optional(Hint),
+  title: Schema.optional(Schema.String),
+  summary: Schema.String,
+  claims: Schema.Array(Schema.String)
+})
+
+const Output = Schema.Struct({
+  status: Schema.Literals(['nothing_worth_it', 'reported', 'planned', 'opened']),
+  summary: Schema.String,
+  reportArtifactId: Schema.optional(Schema.String),
+  changeRequest: Schema.optional(ChangeRequestResult),
+  settled: Schema.optional(Schema.Boolean),
+  unsettled: Schema.optional(Schema.Array(Schema.String))
+})
+
+type Output = typeof Output.Type
+
+const hints = [
+  'Hints, not a sequence; pick what is worth most:',
+  '- architecture: deepen a shallow module, close a seam that leaks, or move behaviour to the data it uses; apply the deletion test (would deleting it make things simpler?).',
+  '- simplification: duplication, dead code, needless indirection or abstraction.'
+].join('\n')
+
+const surveyPrompt = (words: string | undefined, answers: readonly string[]) =>
+  [
+    `Survey ${words === undefined ? 'the repository' : `this area: ${words}`} for the code-quality improvements worth a reviewer's time.`,
+    'You run the improve-codebase-architecture skill as a Kitman Step. Write its HTML report, then keep it on the Run with attach_file and cite it as htmlReport instead of opening it. Stop after the report: Kitman asks the person which candidate to take, so do not grill here.',
+    hints,
+    'List the candidates most valuable first, and none when nothing is worth it; a small or cosmetic change is not worth it.',
+    answers.length === 0
+      ? 'Ask only what the code cannot tell you, such as intent or plans, and at most three questions. Keep each to the context and the question, and give the answer you would assume and why in one or two sentences.'
+      : `Your questions were answered:\n${answers.join('\n')}\nAsk nothing more.`,
+    'Change nothing. Return a report in Markdown.'
+  ].join('\n\n')
+
+const tidyPrompt = (scope: string, words: string | undefined) =>
+  [
+    `Make the one code-quality improvement worth most ${scope}.`,
+    ...(words === undefined ? [] : [`Look at: ${words}`]),
+    hints,
+    'Keep behaviour exactly as it is, and keep the change small enough to review in one sitting. If nothing is worth changing, change nothing and set improved to false: that is a good 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.'
+  ].join('\n\n')
+
+/** A Build's area: what its change touched, and the files that change with them. */
+const areaOf = (revision: string, branch: string | undefined) =>
+  `in the area of the change at ${revision}: only the files that \`git diff $(git merge-base origin/${branch ?? 'HEAD'} ${revision}) ${revision}\` touches, and the files that change with them`
+
+const next = ['Plan it', 'Tidy the top one now', 'Done'] as const
+
+/**
+ * Finds the code-quality improvement worth most and makes it reviewable in one sitting, or says nothing is worth it.
+ * Given a change's head, such as from a Build's offer, it tidies that change's area once, verifies base and head,
+ * has it reviewed once for preserved behaviour, and opens one ChangeRequest. Otherwise it surveys, asking only what
+ * the code cannot tell, reports, and asks whether to plan it, tidy the top one now, or stop.
+ */
+export default defineLoop({
+  id: 'tidy',
+  version: '1.0.0',
+  title: 'Tidy',
+  input: Input,
+  output: Output,
+  agents: { implementer: 'implementer', surveyor: 'surveyor' },
+  checkout: 'write',
+  capabilities: ['agent_work', 'ask', 'verify', 'change_request'],
+  calls: () => [review, plan],
+  run: input =>
+    Effect.gen(function* () {
+      const start = input.revision ?? `origin/${input.branch ?? 'HEAD'}`
+
+      /** One improvement, verified on base and head and reviewed once, so the reviewed diff is the one that ships. */
+      const tidy = (scope: string, words: string | undefined) =>
+        Effect.gen(function* () {
+          const improvement = yield* agentWork('tidy', {
+            agent: 'implementer',
+            prompt: tidyPrompt(scope, words),
+            output: Tidied
+          })
+
+          if (!improvement.improved)
+            return { status: 'nothing_worth_it', summary: improvement.summary } satisfies Output
+
+          const base = yield* verify('verify:base', { revision: start })
+          const head = yield* verify('verify', {})
+
+          const reviewed = yield* call('review', review, {
+            base: start,
+            head: head.revision,
+            outcome: 'refactor',
+            claims: improvement.claims
+          })
+
+          const settled = settleRound({ findings: reviewed.findings, rebuttals: [], verdicts: reviewed.verdicts })
+          const decision = rallyStop({ round: 1, maxRounds: 1, settled })
+          const verdict = evidenceGate({ outcome: 'refactor', base, head })
+
+          const unsettled = [
+            ...(verdict.settled ? [] : verdict.reasons),
+            ...(decision.stop ? unsettledItems(settled, decision) : [])
+          ]
+
+          const opened = yield* changeRequest('change-request', {
+            title: improvement.title ?? 'Tidy',
+            body: changeRequestBody({
+              summary: improvement.summary,
+              head,
+              claims: improvement.claims,
+              unsettled,
+              rounds: 1,
+              stopped: decision.stop ? decision.reason : 'round_cap'
+            })
+          })
+
+          return {
+            status: 'opened',
+            summary: improvement.summary,
+            changeRequest: opened,
+            settled: unsettled.length === 0,
+            unsettled
+          } satisfies Output
+        })
+
+      if (input.revision !== undefined) return yield* tidy(areaOf(input.revision, input.branch), input.words)
+
+      let survey = yield* agentWork('survey', {
+        agent: 'surveyor',
+        skill: 'improve-codebase-architecture',
+        prompt: surveyPrompt(input.words, []),
+        output: Survey
+      })
+
+      if (survey.questions.length > 0) {
+        const answers = yield* Effect.forEach(survey.questions, (question, index) =>
+          Effect.map(
+            ask(`question:${index + 1}`, {
+              prompt: question.question,
+              freeText: true,
+              recommended: question.recommended,
+              recommendationReason: question.why,
+              default: 'No answer; go by the code.',
+              timeout: '1 day'
+            }),
+            answer => `- ${question.question} ${answer}`
+          )
+        )
+
+        survey = yield* agentWork('survey:answered', {
+          agent: 'surveyor',
+          skill: 'improve-codebase-architecture',
+          prompt: surveyPrompt(input.words, answers),
+          output: Survey
+        })
+      }
+
+      const stored = yield* artifact('report', {
+        kind: 'tidy_report',
+        title: 'Tidy report',
+        text: survey.report,
+        ...(survey.htmlReport === undefined ? undefined : { files: [survey.htmlReport] })
+      })
+
+      const [top] = survey.candidates
+
+      if (top === undefined)
+        return {
+          status: 'nothing_worth_it',
+          summary: 'Nothing here is worth a reviewer’s time.',
+          reportArtifactId: stored.artifactId
+        } satisfies Output
+
+      const answer = yield* ask('next', {
+        prompt: `Tidy found ${survey.candidates.length} worth doing, top: ${top.title}. ${top.worth}\n\nWhat next?`,
+        options: [
+          { value: 'Plan it', description: 'Plan files the candidates as Tasks.' },
+          { value: 'Tidy the top one now', description: 'An agent makes the top one and opens a ChangeRequest.' },
+          { value: 'Done', description: 'Keep the report and stop.' }
+        ] satisfies { readonly value: (typeof next)[number]; readonly description: string }[],
+        recommended: 'Tidy the top one now',
+        recommendationReason: `The top one is worth a reviewer's time on its own: ${top.worth}`,
+        default: 'Done',
+        timeout: '1 day'
+      })
+
+      const reported = { summary: `Top: ${top.title}`, reportArtifactId: stored.artifactId }
+
+      if (answer === 'Done') return { status: 'reported', ...reported } satisfies Output
+
+      if (answer === 'Plan it') {
+        yield* call('plan', plan, {
+          words: [
+            'Plan these code-quality improvements:',
+            ...survey.candidates.map(candidate => `- ${candidate.title}: ${candidate.words}`),
+            survey.report
+          ].join('\n\n'),
+          ...(input.repoBindingId === undefined ? undefined : { repoBindingId: input.repoBindingId }),
+          ...(input.branch === undefined ? undefined : { branch: input.branch })
+        })
+
+        return { status: 'planned', ...reported } satisfies Output
+      }
+
+      // The answer can come a day after the survey: tidy on the base as it is now.
+      const synced = yield* syncBase('sync', {
+        agent: 'implementer',
+        ...(input.branch === undefined ? undefined : { target: input.branch })
+      })
+
+      if (synced.status === 'conflict')
+        return {
+          status: 'reported',
+          ...reported,
+          summary: `Top: ${top.title}. Bringing the branch up to date conflicts on ${synced.files.join(', ')}`
+        } satisfies Output
+
+      const tidied = yield* tidy('', `${top.title}: ${top.words}`)
+
+      return { ...tidied, reportArtifactId: stored.artifactId } satisfies Output
+    })
+})

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {},
+  "include": ["src/**/*.ts", "kitman.config.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.