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

package/src/index.ts

@@ -0,0 +1,49 @@
+import build from './build'
+import errand from './errand'
+import fileTasks from './file-tasks'
+import hillclimb from './hillclimb'
+import firewatch from './firewatch'
+import plan from './plan'
+import projectUpdate from './project-update'
+import release from './release'
+import research from './research'
+import hindsight from './hindsight'
+import review from './review'
+import shepherd from './shepherd'
+import sweep from './sweep'
+import tidy from './tidy'
+
+/** The Kit's Loops, by id; a fork spreads the one it replaces. */
+export const loops = {
+  build,
+  errand,
+  'file-tasks': fileTasks,
+  hillclimb,
+  firewatch,
+  plan,
+  'project-update': projectUpdate,
+  release,
+  research,
+  hindsight,
+  review,
+  shepherd,
+  sweep,
+  tidy
+} as const
+
+export {
+  build,
+  errand,
+  fileTasks,
+  hillclimb,
+  firewatch,
+  plan,
+  projectUpdate,
+  release,
+  research,
+  hindsight,
+  review,
+  shepherd,
+  sweep,
+  tidy
+}

package/src/plan.ts

@@ -0,0 +1,634 @@
+import {
+  agentWork,
+  agentWorkOnce,
+  artifact,
+  ask,
+  call,
+  changeRequest,
+  ChangeRequestResult,
+  ChildFailed,
+  createTasks,
+  CreateTasksResult,
+  defineLoop,
+  integrationBranch,
+  mergeChangeRequest,
+  PlanTickets,
+  planWaves,
+  type IntegrationBranch,
+  type PlanTicket
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+import build from './build'
+
+const Input = Schema.Struct({
+  /** What to plan. */
+  words: Schema.String,
+  /** The Team's default RepoBinding when left out. */
+  repoBindingId: Schema.optional(Schema.String),
+  /** The branch the plan is delivered to; each repository's default branch when left out. */
+  branch: Schema.optional(Schema.String),
+  /** The Project the plan's Tasks land in. */
+  projectId: Schema.optional(Schema.String),
+  /** Implements the plan when nobody answers the menu; files it as Tasks otherwise. */
+  implement: Schema.optional(Schema.Boolean)
+})
+
+const Plan = Schema.Struct({
+  title: Schema.String,
+  /** The spec, as Markdown. */
+  spec: Schema.String,
+  tickets: PlanTickets,
+  /** What the plan leaves out; each becomes a constraint on the Builds of its tickets. */
+  outOfScope: Schema.Array(Schema.String),
+  /** Outcomes only visible after merge (adoption, a metric moving); never a ticket's criterion. */
+  afterMerge: Schema.Array(Schema.String),
+  /** The ChangeRequest for the ADR and glossary changes the planner left in the checkout; none when it left none. */
+  docs: Schema.optional(Schema.Struct({ title: Schema.String, summary: Schema.String }))
+})
+
+type Plan = typeof Plan.Type
+
+/** The criteria a ticket names that the base branch already meets. */
+const CriteriaCheck = Schema.Struct({
+  alreadyMet: Schema.Array(Schema.Struct({ key: Schema.String, criterion: Schema.String }))
+})
+
+const Rejected = Schema.Struct({ key: Schema.String, reason: Schema.String })
+
+const Opinion = Schema.Struct({ summary: Schema.String, concerns: Schema.Array(Schema.String) })
+
+const TicketResult = Schema.Struct({
+  key: Schema.String,
+  title: Schema.String,
+  status: Schema.Literals(['merged', 'failed', 'skipped']),
+  repoBindingId: Schema.optional(Schema.String),
+  changeRequest: Schema.optional(ChangeRequestResult),
+  reason: Schema.optional(Schema.String)
+})
+
+type TicketResult = typeof TicketResult.Type
+
+const Output = Schema.Struct({
+  title: Schema.String,
+  outOfScope: Schema.Array(Schema.String),
+  afterMerge: Schema.Array(Schema.String),
+  /** Tickets the base already does all of, left out of the plan. */
+  rejected: Schema.Array(Rejected),
+  /** Why the Run stopped where it did, when it was not a person's choice. */
+  stopped: Schema.optional(Schema.String),
+  implemented: Schema.Boolean,
+  tickets: Schema.Array(TicketResult),
+  /** One ChangeRequest per repository with merged work, from its integration branch into its base branch. */
+  deliveries: Schema.Array(ChangeRequestResult),
+  /** The Task made for each ticket by File as Tasks. */
+  tasks: Schema.optional(CreateTasksResult.fields.tasks),
+  /** The ChangeRequest for the ADRs and glossary the grilling changed. */
+  docs: Schema.optional(ChangeRequestResult)
+})
+
+const menu = ['Implement now', 'File as Tasks', 'Second opinion', 'Refine', 'Finish'] as const
+
+type Choice = (typeof menu)[number]
+
+/** Menu rounds before the plan is filed as Tasks for a person to pick up. */
+const maxRounds = 6
+
+const maxOpinionsPerPlan = 2
+
+const menuDescriptions: Record<Choice, string> = {
+  'Implement now': 'Builds the tickets in dependency order and delivers them.',
+  'File as Tasks': 'Makes a Task of each ticket, to build later.',
+  'Second opinion': 'Another Agent reviews the plan.',
+  Refine: 'You say what to change and the planner rewrites it.',
+  Finish: 'Ends the Run with the plan as it is.'
+}
+
+const onConflict = ['Rebuild on the integration branch', 'Skip'] as const
+
+const onFailure = ['Retry with a steer', 'Skip it and its dependents', 'Stop here'] as const
+
+const ticketRules = [
+  'Each ticket is one Build: a vertical slice an agent can implement, review and deliver as one ChangeRequest. Give it a short unique key, and list in blockedBy the keys of the tickets whose code it needs; tickets never block each other in a cycle. Set repoBindingId only when it changes another repository than the plan, keep one repository per ticket, and no cycle across repositories. Set outcome to the kind of change: feature, bug, refactor, docs, migration, investigation or performance.',
+  "Each acceptance criterion is something a Build can show before its ChangeRequest: a behaviour a test or a check proves. A text search is never a criterion, nor is something the code already does. Outcomes only visible after merge go under afterMerge, not under a ticket's criteria."
+].join('\n\n')
+
+const planPrompt = (words: string) =>
+  [
+    `Plan this: ${words}`,
+    'You run the grill-with-docs skill as a Kitman Step. Interview the person with the Kitman MCP ask tool, one question at a time, and ask only what changes what gets built: a clear goal needs no interview. Write the ADR and glossary changes the grilling settles in the checkout, and no other files.',
+    'Then write the spec and the tickets from the goal, the code and the answers.',
+    ticketRules,
+    'List in outOfScope what the plan deliberately leaves out, one item each; each holds the Builds of its tickets.',
+    'If you left ADR or glossary changes, give docs a ChangeRequest title and a summary of the decisions; Kitman opens it. Your Output is the plan, and Kitman stores it.'
+  ].join('\n\n')
+
+const planText = (plan: Plan) =>
+  [
+    `# ${plan.title}`,
+    plan.spec,
+    ...(plan.outOfScope.length === 0 ? [] : ['## Out of scope', plan.outOfScope.map(item => `- ${item}`).join('\n')]),
+    ...(plan.afterMerge.length === 0 ? [] : ['## After merge', plan.afterMerge.map(item => `- ${item}`).join('\n')]),
+    '## Tickets',
+    ...plan.tickets.map(ticketText)
+  ].join('\n\n')
+
+const ticketText = (ticket: PlanTicket) =>
+  [
+    `### ${ticket.key}: ${ticket.title}`,
+    ticket.body,
+    ...ticket.acceptanceCriteria.map(criterion => `- [ ] ${criterion}`),
+    ...(ticket.blockedBy.length === 0 ? [] : [`Blocked by: ${ticket.blockedBy.join(', ')}`])
+  ].join('\n\n')
+
+const opinionPrompt = (plan: Plan) =>
+  [
+    'Review this plan as a second opinion. Look for missing scope, tickets too big to review, wrong blockers and risks. Change nothing.',
+    planText(plan)
+  ].join('\n\n')
+
+const refinePrompt = (plan: Plan, words: string) =>
+  [`Change the plan as the user asks: ${words}`, ticketRules, planText(plan)].join('\n\n')
+
+const criteriaPrompt = (plan: Plan) =>
+  [
+    "Check each ticket's acceptance criteria against the base branch as it is now. List under alreadyMet each criterion the code already meets, with its ticket's key and the criterion word for word. Change nothing.",
+    planText(plan)
+  ].join('\n\n')
+
+const guard = ' (guard: the base already does this)'
+
+/**
+ * Labels each criterion the base already meets as a guard, and leaves out a ticket whose every criterion it meets,
+ * with its blockers' references to it.
+ */
+const guarded = (plan: Plan, check: typeof CriteriaCheck.Type) => {
+  const met = (ticket: PlanTicket, criterion: string) =>
+    check.alreadyMet.some(entry => entry.key === ticket.key && entry.criterion === criterion)
+
+  const rejected = plan.tickets.flatMap(ticket =>
+    ticket.acceptanceCriteria.length > 0 && ticket.acceptanceCriteria.every(criterion => met(ticket, criterion))
+      ? [{ key: ticket.key, reason: 'The base branch already meets every one of its criteria' }]
+      : []
+  )
+
+  const gone = new Set(rejected.map(entry => entry.key))
+
+  const tickets = plan.tickets.flatMap(ticket =>
+    gone.has(ticket.key)
+      ? []
+      : [
+          {
+            ...ticket,
+            acceptanceCriteria: ticket.acceptanceCriteria.map(criterion =>
+              met(ticket, criterion) ? `${criterion}${guard}` : criterion
+            ),
+            blockedBy: ticket.blockedBy.filter(key => !gone.has(key))
+          }
+        ]
+  )
+
+  return { plan: { ...plan, tickets }, rejected }
+}
+
+/** A plan revision whose criteria were checked against the base: a ticket with nothing left to do is rejected. */
+const checked = (plan: Plan, revision: number) =>
+  Effect.map(
+    agentWork(`criteria-check:${revision}`, { agent: 'reviewer', prompt: criteriaPrompt(plan), output: CriteriaCheck }),
+    check => guarded(plan, check)
+  )
+
+/** A revision of the plan, as Run artifacts later Runs retrieve. */
+const storePlan = (plan: Plan, suffix: string) =>
+  Effect.gen(function* () {
+    yield* artifact(`spec${suffix}`, {
+      kind: 'plan_spec',
+      title: plan.title,
+      text: plan.spec,
+      data: { outOfScope: [...plan.outOfScope] }
+    })
+    yield* artifact(`tickets${suffix}`, {
+      kind: 'plan_tickets',
+      title: `Tickets for ${plan.title}`,
+      text: plan.tickets.map(ticketText).join('\n\n'),
+      data: plan.tickets.map(({ repoBindingId, outcome, ...ticket }) => ({
+        ...ticket,
+        acceptanceCriteria: [...ticket.acceptanceCriteria],
+        blockedBy: [...ticket.blockedBy],
+        ...(repoBindingId === undefined ? undefined : { repoBindingId }),
+        ...(outcome === undefined ? undefined : { outcome })
+      }))
+    })
+  })
+
+/** What a refine changed, ticket by ticket, so the user sees the new revision against the last. */
+const changelog = (before: Plan, after: Plan, words: string) => {
+  const was = new Map(before.tickets.map(ticket => [ticket.key, ticketText(ticket)]))
+  const now = new Map(after.tickets.map(ticket => [ticket.key, ticketText(ticket)]))
+
+  const lines = [
+    ...after.tickets.filter(ticket => !was.has(ticket.key)).map(ticket => `- Added ${ticket.key}: ${ticket.title}`),
+    ...before.tickets.filter(ticket => !now.has(ticket.key)).map(ticket => `- Removed ${ticket.key}: ${ticket.title}`),
+    ...after.tickets
+      .filter(ticket => was.has(ticket.key) && was.get(ticket.key) !== now.get(ticket.key))
+      .map(ticket => `- Changed ${ticket.key}: ${ticket.title}`),
+    ...(before.spec === after.spec ? [] : ['- Changed the spec']),
+    ...(before.title === after.title ? [] : [`- Renamed the plan from "${before.title}"`])
+  ]
+
+  return [`Asked: ${words}`, ...(lines.length === 0 ? ['Nothing changed.'] : lines)].join('\n')
+}
+
+/** The ticket as the Build's words, for a ticket that got no Task. */
+const buildWords = (ticket: PlanTicket) =>
+  [
+    ticket.title,
+    ticket.body,
+    ...(ticket.acceptanceCriteria.length === 0
+      ? []
+      : ['Acceptance criteria:', ...ticket.acceptanceCriteria.map(criterion => `- ${criterion}`)])
+  ].join('\n\n')
+
+const settled = (ticket: PlanTicket, result: Omit<TicketResult, 'key' | 'title'>): TicketResult => ({
+  key: ticket.key,
+  title: ticket.title,
+  ...result
+})
+
+/**
+ * Builds a ticket from the integration head, then merges its ChangeRequest into the integration branch. On a
+ * conflict the user chooses to rebuild from the head as it is now, or to give the ticket up. `steer` is a person's
+ * words for a retry; `label` names its Steps apart from the first try's.
+ */
+const buildTicket = (
+  ticket: PlanTicket,
+  start: IntegrationBranch,
+  taskId: string | undefined,
+  retry?: { readonly label: string; readonly steer: string }
+) =>
+  Effect.gen(function* () {
+    let head = start
+    const name = retry === undefined ? ticket.key : `${ticket.key}:${retry.label}`
+
+    for (let attempt = 1; ; attempt++) {
+      const suffix = attempt === 1 ? '' : `:${attempt}`
+
+      const words =
+        retry === undefined
+          ? taskId === undefined
+            ? { words: buildWords(ticket) }
+            : undefined
+          : { words: `${buildWords(ticket)}\n\nAn earlier Build of this failed. ${retry.steer}` }
+
+      const built = yield* call(`build:${name}${suffix}`, build, {
+        ...words,
+        ...(taskId === undefined ? undefined : { taskId }),
+        repoBindingId: head.repoBindingId,
+        branch: head.branch,
+        revision: head.revision
+      }).pipe(Effect.catchTag('ChildFailed', (failure: ChildFailed) => Effect.succeed(failure)))
+
+      if (built instanceof ChildFailed)
+        return settled(ticket, { status: 'failed', repoBindingId: head.repoBindingId, reason: built.reason })
+
+      // Only what the Build verified merges; a commit pushed to its branch since is rebuilt or skipped like a conflict.
+      const merged = yield* mergeChangeRequest(`merge:${name}${suffix}`, {
+        changeRequestId: built.changeRequest.id,
+        head: built.revision
+      })
+
+      const delivered = { repoBindingId: head.repoBindingId, changeRequest: built.changeRequest }
+
+      if (merged.status === 'merged') return settled(ticket, { status: 'merged', ...delivered })
+
+      const choice = yield* ask(`conflict:${name}${suffix}`, {
+        prompt: `The ChangeRequest for ${ticket.key} (${built.changeRequest.url}) ${merged.status === 'moved' ? 'changed after it was built' : `conflicts with ${head.branch}`}. Rebuild ${ticket.key} on the integration branch as it is now, or skip it and the tickets it blocks?`,
+        options: [
+          {
+            value: 'Rebuild on the integration branch',
+            description: 'Builds the ticket again from the branch as it is now.'
+          },
+          { value: 'Skip', description: 'Leaves it and the tickets it blocks undelivered.' }
+        ] satisfies { readonly value: (typeof onConflict)[number]; readonly description: string }[],
+        recommended: 'Rebuild on the integration branch',
+        recommendationReason:
+          'A rebuild on the current branch usually resolves a conflict, and skipping also drops every ticket it blocks.',
+        default: 'Skip',
+        timeout: '1 hour'
+      })
+
+      if (choice === 'Skip')
+        return settled(ticket, { status: 'failed', ...delivered, reason: `It conflicted with ${head.branch}` })
+
+      head = yield* integrationBranch(`rebuild-from:${name}:${attempt + 1}`, {
+        repoBindingId: head.repoBindingId
+      })
+    }
+  })
+
+const deliveryBody = (plan: Plan, results: readonly TicketResult[]) => {
+  const line = (result: TicketResult) =>
+    result.status === 'merged' && result.changeRequest !== undefined
+      ? `- **${result.key}** [${result.title}](${result.changeRequest.url}); its evidence is on that ChangeRequest`
+      : `- **${result.key}** ${result.title}: ${result.reason ?? result.status}`
+
+  const section = (title: string, status: TicketResult['status']) => {
+    const lines = results.flatMap(result => (result.status === status ? [line(result)] : []))
+
+    return lines.length === 0 ? [] : [`## ${title}`, lines.join('\n')]
+  }
+
+  return [
+    `Delivers the plan "${plan.title}".`,
+    ...section('Merged', 'merged'),
+    ...section('Failed', 'failed'),
+    ...section('Skipped', 'skipped')
+  ].join('\n\n')
+}
+
+type Filed = { readonly revision: number; readonly tasks: typeof CreateTasksResult.Type.tasks }
+
+/**
+ * Makes a Task per ticket (or takes those File as Tasks made of this revision), then builds the tickets in waves on an
+ * integration branch per repository: a wave starts from the integration heads once its blockers' ChangeRequests are
+ * merged, so each Build contains its blockers' code. A failed ticket asks: retry it with a person's steer, skip it and
+ * its dependents (the default), or stop. Finally one ChangeRequest per repository delivers the integration branch.
+ */
+const implement = (input: typeof Input.Type, plan: Plan, revision: number, filed: Filed | undefined) =>
+  Effect.gen(function* () {
+    const tasks =
+      filed?.revision === revision
+        ? filed.tasks
+        : (yield* createTasks('tasks', {
+            tickets: plan.tickets,
+            ...(input.projectId === undefined ? undefined : { projectId: input.projectId })
+          })).tasks
+
+    const taskOf = new Map(tasks.map(task => [task.key, task.taskId]))
+    const results = new Map<string, TicketResult>()
+    const waves = yield* planWaves(plan.tickets)
+    let stopped: string | undefined
+
+    for (const [index, wave] of waves.entries()) {
+      const ready: PlanTicket[] = []
+
+      for (const ticket of wave) {
+        const unmerged = ticket.blockedBy.find(key => results.get(key)?.status !== 'merged')
+
+        if (stopped !== undefined) results.set(ticket.key, settled(ticket, { status: 'skipped', reason: stopped }))
+        else if (unmerged === undefined) ready.push(ticket)
+        else
+          results.set(
+            ticket.key,
+            settled(ticket, { status: 'skipped', reason: `blocked by ${unmerged}, which was not merged` })
+          )
+      }
+
+      const repoOf = (ticket: PlanTicket) => ticket.repoBindingId ?? input.repoBindingId
+      const heads = new Map<string | undefined, IntegrationBranch>()
+
+      for (const repo of new Set(ready.map(repoOf)))
+        heads.set(
+          repo,
+          yield* integrationBranch(
+            `integration:wave-${index + 1}:${repo ?? 'default'}`,
+            repo === undefined ? {} : { repoBindingId: repo }
+          )
+        )
+
+      const built = yield* Effect.forEach(
+        ready.flatMap(ticket => {
+          const head = heads.get(repoOf(ticket))
+
+          return head === undefined ? [] : [buildTicket(ticket, head, taskOf.get(ticket.key))]
+        }),
+        building => building,
+        { concurrency: 'unbounded' }
+      )
+
+      for (const first of built) {
+        const ticket = ready.find(entry => entry.key === first.key)
+        let result = first
+
+        for (let retry = 1; ticket !== undefined && result.status === 'failed' && stopped === undefined; retry++) {
+          const choice = yield* ask(`failed:${ticket.key}:${retry}`, {
+            prompt: `The Build of ${ticket.key} failed: ${result.reason ?? 'no reason given'}. Retry it with a steer, skip it and the tickets it blocks, or stop here?`,
+            options: onFailure,
+            recommended: 'Retry with a steer',
+            recommendationReason:
+              'The reason it failed is above, so a steer can aim the retry at it; skipping also drops the tickets it blocks.',
+            default: 'Skip it and its dependents',
+            timeout: '1 hour'
+          })
+
+          if (choice === 'Skip it and its dependents') break
+
+          if (choice === 'Stop here') {
+            stopped = `Stopped after ${ticket.key} failed`
+            break
+          }
+
+          const steer = yield* ask(`steer:${ticket.key}:${retry}`, {
+            prompt: `What should the retry of ${ticket.key} do differently?`,
+            freeText: true,
+            recommended: `Address the failure: ${result.reason ?? 'find out why it failed first'}`,
+            recommendationReason: 'Pointing the retry at the reason it failed is the least a steer should do.',
+            default: null
+          })
+
+          const head = yield* integrationBranch(`integration:${ticket.key}:retry-${retry}`, {
+            ...(repoOf(ticket) === undefined ? undefined : { repoBindingId: repoOf(ticket) })
+          })
+
+          result = yield* buildTicket(ticket, head, taskOf.get(ticket.key), { label: `retry-${retry}`, steer })
+        }
+
+        results.set(result.key, result)
+      }
+    }
+
+    const ordered = plan.tickets.flatMap(ticket => results.get(ticket.key) ?? [])
+
+    const repos = [
+      ...new Set(ordered.flatMap(result => (result.status === 'merged' ? (result.repoBindingId ?? []) : [])))
+    ]
+
+    const deliveries = yield* Effect.forEach(repos, repo =>
+      changeRequest(`deliver:${repo}`, {
+        title: plan.title,
+        body: deliveryBody(
+          plan,
+          ordered.filter(result => result.repoBindingId === repo || result.repoBindingId === undefined)
+        ),
+        integration: repo
+      })
+    )
+
+    return { tickets: ordered, deliveries, tasks, ...(stopped === undefined ? undefined : { stopped }) }
+  })
+
+/**
+ * Plans from the goal and the code: the planner runs grill-with-docs, asking only the decisions that change the
+ * tickets, and Plan opens a docs ChangeRequest for the ADR and glossary changes it left. Plan checks each ticket's
+ * criteria against the base, stores the spec and tickets as Run artifacts, and then asks what next, at most six times:
+ * build the tickets, file them as Tasks, ask another Agent's opinion (twice at most), refine the plan from the user's
+ * words, or finish (ADR-0051). Nobody answering files it as Tasks, or implements it when started with `implement`.
+ */
+export default defineLoop({
+  id: 'plan',
+  version: '2.0.0',
+  title: 'Plan',
+  input: Input,
+  output: Output,
+  agents: { planner: 'planner', reviewer: 'reviewer' },
+  checkout: 'write',
+  // A Child Run gets no more than its parent was granted, so this covers what each ticket's Build needs too.
+  capabilities: [
+    'agent_work',
+    'ask',
+    'call',
+    'verify',
+    'change_request',
+    'write_back',
+    'create_tasks',
+    'merge_change_request',
+    'read_change_request',
+    'post_comment'
+  ],
+  calls: () => [build],
+  run: input =>
+    Effect.gen(function* () {
+      const drafted = yield* agentWorkOnce('plan', {
+        agent: 'planner',
+        skill: 'grill-with-docs',
+        prompt: planPrompt(input.words),
+        output: Plan
+      })
+
+      const docs =
+        drafted.docs === undefined
+          ? undefined
+          : yield* changeRequest('docs', { title: drafted.docs.title, body: drafted.docs.summary })
+
+      let revision = 1
+      let { plan, rejected } = yield* checked(drafted, revision)
+      let filed: Filed | undefined
+      let opinions = 0
+
+      yield* storePlan(plan, '')
+
+      const project = input.projectId === undefined ? undefined : { projectId: input.projectId }
+
+      const ended = (rest: { readonly implemented: boolean; readonly stopped?: string }) => ({
+        title: plan.title,
+        outOfScope: plan.outOfScope,
+        afterMerge: plan.afterMerge,
+        rejected,
+        tickets: [],
+        deliveries: [],
+        ...(filed === undefined ? undefined : { tasks: filed.tasks }),
+        ...(docs === undefined ? undefined : { docs }),
+        ...rest
+      })
+
+      for (let round = 1; round <= maxRounds; round++) {
+        const isFiled = filed?.revision === revision
+
+        const options = menu.filter(
+          option =>
+            !(option === 'File as Tasks' && isFiled) && !(option === 'Second opinion' && opinions >= maxOpinionsPerPlan)
+        )
+
+        const fallback: Choice = input.implement === true ? 'Implement now' : isFiled ? 'Finish' : 'File as Tasks'
+
+        const answer = yield* ask(`next:${round}`, {
+          prompt: `What next for the plan "${plan.title}"?`,
+          options: options.map(option => ({ value: option, description: menuDescriptions[option] })),
+          recommended: fallback,
+          recommendationReason:
+            fallback === 'Implement now'
+              ? 'You asked for the plan to be implemented.'
+              : fallback === 'Finish'
+                ? 'The plan is filed as Tasks, so nothing is lost by finishing.'
+                : 'Filing keeps the plan as Tasks a person or a Build can pick up later.',
+          default: fallback,
+          timeout: '1 hour'
+        })
+
+        const choice = menu.find(option => option === answer) ?? fallback
+
+        switch (choice) {
+          case 'Finish':
+            return ended({ implemented: false })
+          case 'Implement now': {
+            const delivered = yield* implement(input, plan, revision, filed)
+
+            return { ...ended({ implemented: true }), ...delivered }
+          }
+
+          case 'File as Tasks': {
+            const made = yield* createTasks(`file-tasks:${round}`, { tickets: plan.tickets, ...project })
+
+            filed = { revision, tasks: made.tasks }
+            break
+          }
+
+          case 'Second opinion': {
+            opinions++
+
+            const opinion = yield* agentWork(`second-opinion:${round}`, {
+              agent: 'reviewer',
+              prompt: opinionPrompt(plan),
+              output: Opinion
+            })
+
+            yield* artifact(`opinion:${round}`, {
+              kind: 'plan_review',
+              title: `Second opinion on ${plan.title}`,
+              text: [opinion.summary, ...opinion.concerns.map(concern => `- ${concern}`)].join('\n\n')
+            })
+
+            break
+          }
+
+          case 'Refine': {
+            const words = yield* ask(`refine:${round}`, {
+              prompt: 'What should change in the plan?',
+              freeText: true,
+              informationOnly: true,
+              recommendationReason: 'You chose to refine it, so only you know what should change.'
+            })
+
+            const refined = yield* agentWorkOnce(`refine-plan:${round}`, {
+              agent: 'planner',
+              prompt: refinePrompt(plan, words),
+              output: Plan
+            })
+
+            const before = plan
+
+            revision++
+            ;({ plan, rejected } = yield* checked(refined, revision))
+            yield* storePlan(plan, `:${round}`)
+            yield* artifact(`changes:${round}`, {
+              kind: 'plan_changes',
+              title: `Revision ${revision} of ${plan.title}`,
+              text: changelog(before, plan, words)
+            })
+            break
+          }
+        }
+      }
+
+      if (filed?.revision !== revision)
+        filed = {
+          revision,
+          tasks: (yield* createTasks('file-tasks:last', { tickets: plan.tickets, ...project })).tasks
+        }
+
+      return ended({
+        implemented: false,
+        stopped: `No decision after ${maxRounds} rounds, so the tickets are filed as Tasks for a person to pick up`
+      })
+    })
+})