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

package/src/hillclimb.ts

@@ -0,0 +1,407 @@
+import {
+  agentWork,
+  agentWorkOnce,
+  artifact,
+  ask,
+  call,
+  changeRequest,
+  ChangeRequestResult,
+  createTasks,
+  defineLoop,
+  isBlocking,
+  measure,
+  MeasurePlan,
+  syncBase,
+  verify,
+  writeBack,
+  type Measurement
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+import { scopeFindings } from './change-request-body'
+import review from './review'
+
+const Input = Schema.Struct({
+  /** What to make faster, in words; the journeys that matter most when left out. */
+  focus: 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),
+  /** Changes tried at most; 5 when left out. */
+  cycles: Schema.optional(Schema.Int),
+  /** The smallest gain that counts, as a fraction of the base; 0.05 when left out. */
+  threshold: Schema.optional(Schema.Finite),
+  /** How much worse a guardrail may get, as a fraction of the base; 0.02 when left out. */
+  tolerance: Schema.optional(Schema.Finite)
+})
+
+const Opportunity = Schema.Struct({
+  title: Schema.String,
+  detail: Schema.String,
+  /** measured: a number shows it; telemetry: production data shows it; hypothesis: reading the code suggests it. */
+  evidence: Schema.Literals(['measured', 'telemetry', 'hypothesis']),
+  /** Only another repository can make it; offered as a Task at the end, never made here. */
+  external: Schema.optional(Schema.Boolean)
+})
+
+const Discovery = Schema.Struct({
+  stack: Schema.String,
+  journeys: Schema.Array(Schema.Struct({ name: Schema.String, objective: Schema.String })),
+  telemetry: Schema.Array(
+    Schema.Struct({ source: Schema.String, status: Schema.Literals(['used', 'unavailable']), why: Schema.String })
+  ),
+  /** Ranked, most promising first. */
+  opportunities: Schema.Array(Opportunity)
+})
+
+const Harness = Schema.Struct({
+  /** What the benchmark exercises and why it stands for the journeys. */
+  summary: Schema.String,
+  plan: MeasurePlan
+})
+
+const Change = Schema.Struct({
+  /** changed: one change is committed; exhausted: nothing left worth trying; unsafe: the gain would cost correctness. */
+  status: Schema.Literals(['changed', 'exhausted', 'unsafe']),
+  summary: Schema.String
+})
+
+const Kept = Schema.Struct({ summary: Schema.String, verdict: Schema.String, reason: Schema.String })
+
+const Output = Schema.Struct({
+  /** improved: a ChangeRequest holds a gain the final measurement proved; otherwise a findings report only. */
+  status: Schema.Literals(['improved', 'no_gain', 'gain_gone', 'checks_failed', 'too_noisy']),
+  reason: Schema.String,
+  kept: Schema.Array(Kept),
+  cycles: Schema.Int,
+  reportArtifactId: Schema.String,
+  changeRequest: Schema.optional(ChangeRequestResult),
+  /** Improvements only another repository can make. */
+  external: Schema.Array(Schema.String),
+  /** What the ChangeRequest leaves open. */
+  unsettled: Schema.optional(Schema.Array(Schema.String))
+})
+
+const discoverPrompt = (focus: string | undefined) =>
+  [
+    `Find where this repository is slow${focus === undefined ? ', for the journeys that matter most' : `: ${focus}`}. Change nothing.`,
+    'Read the stack, the user journeys and the objective each has, the docs and earlier performance work. Read whatever telemetry you can reach, read-only and with bounded queries; list each source as used or unavailable, with why.',
+    'Rank the opportunities, most promising first, each marked measured, telemetry or hypothesis. Mark one that only another repository can make as external.'
+  ].join('\n\n')
+
+const harnessPrompt = (discovery: typeof Discovery.Type) =>
+  [
+    'Commit a local benchmark for these journeys, and change no product code:',
+    ...discovery.journeys.map(journey => `- ${journey.name}: ${journey.objective}`),
+    'It runs on this Runner alone: never call a service, database or URL outside it. Each run prints one JSON line of numbers by metric name as its last line; wall time is measured for you as wall_ms. Keep it under a minute a run.',
+    'Give the measurement plan: the command, any prepare command, and the metrics with one primary and the rest guardrails. Add a low-variance counter (instructions, allocations, queries) where you can, marked lowVariance.'
+  ].join('\n\n')
+
+const changePrompt = (discovery: typeof Discovery.Type, plan: MeasurePlan, tried: readonly string[], cycle: number) =>
+  [
+    `Cycle ${cycle}: make one bounded change that should improve ${plan.metrics.find(metric => metric.role === 'primary')?.name ?? 'the primary metric'} without making a guardrail worse, and commit it. Kitman measures it; do not report numbers of your own.`,
+    'Opportunities, most promising first:',
+    ...discovery.opportunities.flatMap(entry =>
+      entry.external === true ? [] : [`- ${entry.title} (${entry.evidence}): ${entry.detail}`]
+    ),
+    ...(tried.length === 0 ? [] : ['Already tried:', ...tried.map(entry => `- ${entry}`)]),
+    'Keep behaviour exactly as it is and run the tests you touch. Answer exhausted when nothing is left worth trying, or unsafe when the gain would cost correctness; either way change nothing.'
+  ].join('\n\n')
+
+const revertPrompt = (start: string, cycle: number) =>
+  `Cycle ${cycle}'s change did not prove faster. Revert its commits, and only those: run \`git revert --no-edit ${start}..HEAD\`. Touch no commit at or before ${start}, never reset or force-push, and change nothing else.`
+
+const fixPrompt = (findings: readonly { readonly id: string; readonly detail: string }[]) =>
+  [
+    'The review of the climb found these. Fix each, keep behaviour exactly as it is and keep the gain, and commit. Kitman verifies and measures again; a fix that costs the gain ends the climb.',
+    ...findings.map(finding => `- ${finding.id}: ${finding.detail}`)
+  ].join('\n\n')
+
+const percent = (fraction: number) => `${(fraction * 100).toFixed(1)}%`
+
+const numbers = (measured: Measurement) =>
+  [
+    '| Metric | Role | Base median | Head median | Change | Noise |',
+    '|---|---|---|---|---|---|',
+    ...measured.metrics.map(
+      metric =>
+        `| ${metric.name} | ${metric.role} | ${metric.base.median} | ${metric.head.median} | ${percent(metric.change)} | ${percent(metric.noise)} |`
+    )
+  ].join('\n')
+
+const report = (input: {
+  readonly discovery: typeof Discovery.Type
+  readonly harness: typeof Harness.Type
+  readonly reason: string
+  readonly kept: readonly (typeof Kept.Type)[]
+  readonly tried: readonly string[]
+  readonly final: Measurement | undefined
+}) =>
+  [
+    `# Hillclimb findings\n\n${input.reason}`,
+    `## Stack\n\n${input.discovery.stack}`,
+    `## Telemetry\n\n${input.discovery.telemetry.map(entry => `- ${entry.source}: ${entry.status}, ${entry.why}`).join('\n') || '- None reached'}`,
+    `## Benchmark\n\n${input.harness.summary}`,
+    `## Tried\n\n${input.tried.map(entry => `- ${entry}`).join('\n') || '- Nothing'}`,
+    ...(input.kept.length === 0
+      ? []
+      : [`## Kept\n\n${input.kept.map(entry => `- ${entry.summary}: ${entry.reason}`).join('\n')}`]),
+    ...(input.final === undefined ? [] : [`## Final measurement\n\n${input.final.reason}\n\n${numbers(input.final)}`]),
+    `## Opportunities\n\n${input.discovery.opportunities.map(entry => `- ${entry.title} (${entry.evidence}${entry.external === true ? ', external' : ''}): ${entry.detail}`).join('\n')}`
+  ].join('\n\n')
+
+/** Makes the plan's low-variance counter its primary metric, the old primary a guardrail. */
+const steadier = (plan: MeasurePlan): MeasurePlan | undefined => {
+  const counter = plan.metrics.find(metric => metric.lowVariance === true && metric.role !== 'primary')
+
+  return counter === undefined
+    ? undefined
+    : {
+        ...plan,
+        metrics: plan.metrics.map(metric => ({
+          ...metric,
+          role: metric.name === counter.name ? ('primary' as const) : ('guardrail' as const)
+        }))
+      }
+}
+
+/**
+ * Climbs one measured step at a time and keeps only the steps Kitman's own measurement proves uphill. It reads the
+ * repository and what telemetry it can reach, commits a benchmark, measures the noise floor, then tries one change a
+ * cycle: kept on a gain with no guardrail worse, else reverted to the cycle's start. Two unkept cycles in a row end
+ * the climb. A ChangeRequest opens only when the final tree still proves the gain over the harness on the base; with
+ * no gain the Run ends with a findings report.
+ */
+export default defineLoop({
+  id: 'hillclimb',
+  version: '1.3.0',
+  title: 'Hillclimb',
+  outcome: 'performance',
+  input: Input,
+  output: Output,
+  agents: { investigator: 'climber', implementer: 'implementer' },
+  checkout: 'write',
+  capabilities: ['agent_work', 'verify', 'measure', 'change_request', 'write_back', 'ask', 'create_tasks'],
+  calls: () => [review],
+  offers: [{ id: 'retry', title: 'Climb again', loop: 'hillclimb' }],
+  run: input =>
+    Effect.gen(function* () {
+      const limits = {
+        ...(input.threshold === undefined ? undefined : { threshold: input.threshold }),
+        ...(input.tolerance === undefined ? undefined : { tolerance: input.tolerance })
+      }
+
+      const discovery = yield* agentWork('discover', {
+        agent: 'investigator',
+        prompt: discoverPrompt(input.focus),
+        output: Discovery
+      })
+
+      const external = discovery.opportunities.flatMap(entry => (entry.external === true ? [entry.title] : []))
+
+      // The harness sits on the base as the climb found it, so every baseline holds the benchmark.
+      yield* syncBase('sync:start', {
+        agent: 'implementer',
+        ...(input.branch === undefined ? undefined : { target: input.branch })
+      })
+
+      const harness = yield* agentWorkOnce('harness', {
+        agent: 'implementer',
+        prompt: harnessPrompt(discovery),
+        output: Harness
+      })
+
+      const baseline = (yield* verify('verify:harness', {})).revision
+      let plan = harness.plan
+      const calibrated = yield* measure('calibrate', { plan, base: baseline, head: baseline, ...limits })
+      const kept: (typeof Kept.Type)[] = []
+      const tried: string[] = []
+      let cycles = 0
+
+      const ending = (status: typeof Output.Type.status, reason: string, final?: Measurement) =>
+        Effect.gen(function* () {
+          const stored = yield* artifact('report', {
+            kind: 'hillclimb-report',
+            title: 'Hillclimb findings',
+            text: report({ discovery, harness, reason, kept, tried, final })
+          })
+
+          return { status, reason, kept, cycles, reportArtifactId: stored.artifactId, external }
+        })
+
+      if (calibrated.verdict === 'too_noisy') {
+        const switched = steadier(plan)
+
+        if (switched === undefined)
+          return yield* ending('too_noisy', `${calibrated.reason}. ${calibrated.suggestion ?? ''}`.trim())
+
+        plan = switched
+      }
+
+      let start = baseline
+      let unkept = 0
+
+      for (let cycle = 1; cycle <= (input.cycles ?? 5) && unkept < 2; cycle++) {
+        const change = yield* agentWorkOnce(`change:${cycle}`, {
+          agent: 'implementer',
+          prompt: changePrompt(discovery, plan, tried, cycle),
+          output: Change
+        })
+
+        if (change.status !== 'changed') {
+          tried.push(`Cycle ${cycle}: ${change.status}, ${change.summary}`)
+          break
+        }
+
+        cycles = cycle
+
+        const head = yield* verify(`verify:${cycle}`, {})
+
+        const measured = head.passed
+          ? yield* measure(`measure:${cycle}`, { plan, base: start, head: head.revision, ...limits })
+          : undefined
+
+        if (measured?.verdict === 'gain') {
+          kept.push({ summary: change.summary, verdict: measured.verdict, reason: measured.reason })
+          tried.push(`Cycle ${cycle}, kept: ${change.summary} (${measured.reason})`)
+          start = head.revision
+          unkept = 0
+          continue
+        }
+
+        tried.push(
+          `Cycle ${cycle}, reverted: ${change.summary} (${measured === undefined ? 'its checks failed' : measured.reason})`
+        )
+        yield* agentWork(`revert:${cycle}`, {
+          agent: 'implementer',
+          prompt: revertPrompt(start, cycle),
+          output: Schema.Struct({ reverted: Schema.Boolean })
+        })
+        unkept++
+      }
+
+      if (external.length > 0) {
+        const file = yield* ask('external', {
+          prompt: `Only other repositories can make these improvements: ${external.join('; ')}. File them as Tasks?`,
+          options: ['File as Tasks', 'Leave them'],
+          recommended: 'File as Tasks',
+          recommendationReason:
+            'Filed as Tasks, the improvements wait in the repositories that can make them instead of being lost.',
+          default: 'Leave them',
+          timeout: '1 hour'
+        })
+
+        if (file === 'File as Tasks')
+          yield* createTasks('external-tasks', {
+            tickets: discovery.opportunities.flatMap((entry, index) =>
+              entry.external === true
+                ? [
+                    {
+                      key: `external-${index + 1}`,
+                      title: entry.title,
+                      body: entry.detail,
+                      acceptanceCriteria: [],
+                      blockedBy: [],
+                      outcome: 'performance' as const
+                    }
+                  ]
+                : []
+            )
+          })
+      }
+
+      if (kept.length === 0) return yield* ending('no_gain', 'No change proved faster than the noise allows')
+
+      const synced = yield* syncBase('sync:final', {
+        agent: 'implementer',
+        ...(input.branch === undefined ? undefined : { target: input.branch })
+      })
+
+      const checked = yield* verify('verify:final', {})
+
+      if (!checked.passed) {
+        const failing = checked.checks.filter(check => check.status === 'failed').map(check => check.name)
+
+        return yield* ending('checks_failed', `The final tree fails ${failing.join(', ') || 'its checks'}`)
+      }
+
+      let final = yield* measure('measure:final', { plan, base: baseline, head: checked.revision, ...limits })
+
+      if (final.verdict !== 'gain')
+        return yield* ending('gain_gone', `The final tree no longer proves the gain: ${final.reason}`, final)
+
+      const claims = [
+        'Behaviour is preserved: every kept change leaves what the code does exactly as it was.',
+        `The measurement is valid: ${harness.summary}`,
+        ...kept.map(entry => entry.summary)
+      ]
+
+      let reviewed = yield* call('review', review, {
+        base: baseline,
+        head: checked.revision,
+        outcome: 'performance',
+        claims
+      })
+
+      for (let round = 1; round <= 2 && reviewed.findings.some(isBlocking); round++) {
+        const blocking = reviewed.findings.filter(isBlocking)
+
+        yield* agentWork(`fix:${round}`, {
+          agent: 'implementer',
+          prompt: fixPrompt(blocking),
+          output: Schema.Struct({ summary: Schema.String })
+        })
+
+        const fixed = yield* verify(`verify:fix:${round}`, {})
+
+        if (!fixed.passed) {
+          const failing = fixed.checks.filter(check => check.status === 'failed').map(check => check.name)
+
+          return yield* ending('checks_failed', `The review's fixes fail ${failing.join(', ') || 'the checks'}`)
+        }
+
+        final = yield* measure(`measure:fix:${round}`, { plan, base: baseline, head: fixed.revision, ...limits })
+
+        if (final.verdict !== 'gain')
+          return yield* ending('gain_gone', `The review's fixes cost the gain: ${final.reason}`, final)
+
+        reviewed = yield* call(`review:${round + 1}`, review, {
+          base: baseline,
+          head: fixed.revision,
+          outcome: 'performance',
+          claims,
+          earlier: blocking
+        })
+      }
+
+      const unsettled = [
+        ...[...reviewed.findings, ...scopeFindings(reviewed.scope)].flatMap(finding =>
+          isBlocking(finding) ? [`${finding.id}: ${finding.detail}`] : []
+        ),
+        ...(synced.status === 'conflict' ? [`Merging the base in conflicts on ${synced.files.join(', ')}`] : [])
+      ]
+
+      const caveats =
+        synced.status === 'merged'
+          ? ['The base moved during the climb; the final measurement includes its changes too.']
+          : []
+
+      const opened = yield* changeRequest('change-request', {
+        title: `Faster: ${kept.map(entry => entry.summary).join('; ')}`.slice(0, 240),
+        body: [
+          `${final.reason}, measured by Kitman against the benchmark on the base.`,
+          numbers(final),
+          `## Kept\n\n${kept.map(entry => `- ${entry.summary}: ${entry.reason}`).join('\n')}`,
+          `## Benchmark\n\n${harness.summary}\n\n\`${plan.command}\``,
+          ...(unsettled.length + caveats.length === 0
+            ? []
+            : [`## Unsettled\n\n${[...unsettled, ...caveats].map(entry => `- ${entry}`).join('\n')}`])
+        ].join('\n\n')
+      })
+
+      yield* writeBack('write-back', { milestone: 'change_request_opened', changeRequestUrl: opened.url })
+
+      return { ...(yield* ending('improved', final.reason, final)), changeRequest: opened, unsettled }
+    })
+})

package/src/hindsight.ts

@@ -0,0 +1,242 @@
+import {
+  agentWork,
+  call,
+  defineLoop,
+  propose,
+  TranscriptPoint,
+  transcripts,
+  type ProposeRequest,
+  type TranscriptsResult
+} from '@kitman-sh/sdk/loop'
+import * as Effect from 'effect/Effect'
+import * as Schema from 'effect/Schema'
+import build from './build'
+import errand from './errand'
+
+const Input = Schema.Struct({
+  /** How many days back to read; a week when left out. */
+  days: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(31))),
+  /** Reads one Team's Runs; every Team's the Run may read when left out. */
+  teamId: Schema.optional(Schema.String),
+  /** How many findings to start fixing as Errands or Builds; none when left out. */
+  improvements: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(5)))
+})
+
+const categories = [
+  'navigation',
+  'checks',
+  'standards',
+  'instructions',
+  'tool_economy',
+  'no_ops',
+  'information_access',
+  'kitman'
+] as const
+
+const Category = Schema.Literals(categories)
+
+const Finding = Schema.Struct({
+  /** A stable kebab-case name for what goes wrong; the same problem gets the same key every week. */
+  key: Schema.String.check(Schema.isPattern(/^[a-z0-9]+(?:-[a-z0-9]+)*$/), Schema.isMaxLength(80)),
+  category: Category,
+  /** Memory teaches agents to avoid it; a Task changes what causes it. */
+  kind: Schema.Literals(['memory', 'task']),
+  /** The Memory's words, or the Task's title. */
+  lesson: Schema.String,
+  /** The Task's description. */
+  detail: Schema.optional(Schema.String),
+  /** How to fix the cause when a Run may start on it: an errand for a small change, a build for a feature. */
+  fix: Schema.optional(Schema.Struct({ size: Schema.Literals(['errand', 'build']), words: Schema.String })),
+  citations: Schema.Array(TranscriptPoint)
+})
+
+type Finding = typeof Finding.Type
+
+const Findings = Schema.Struct({ findings: Schema.Array(Finding) })
+
+const Proposal = Schema.Struct({
+  key: Schema.String,
+  category: Category,
+  kind: Schema.Literals(['memory', 'task']),
+  id: Schema.String,
+  /** It matched an earlier proposal or open Task, which it added to instead. */
+  matched: Schema.Boolean,
+  runIds: Schema.Array(Schema.String)
+})
+
+const Output = Schema.Struct({
+  /** One line on what the Run found. */
+  summary: Schema.String,
+  proposals: Schema.Array(Proposal),
+  /** Findings left out, and why. */
+  leftOut: Schema.Array(Schema.Struct({ key: Schema.String, reason: Schema.String })),
+  improvements: Schema.Array(
+    Schema.Struct({ key: Schema.String, loop: Schema.Literals(['errand', 'build']), outcome: Schema.String })
+  )
+})
+
+type ReadRun = TranscriptsResult['runs'][number]
+
+const prompt = (runs: readonly ReadRun[], days: number) =>
+  [
+    `These Runs settled in the last ${days} days, each with its status: a failed one with its failure, one with a retried Step marked retried. Find what keeps going wrong in more than one Run: a failure, or in Runs that completed, a wasted step, a wrong turn, a check run again and again, or work redone. Fix the cause, not the symptom.`,
+    '```json',
+    JSON.stringify(runs, null, 2),
+    '```',
+    `Give each finding a category: ${categories.join(', ')}. Use kitman when Kitman itself misbehaved: a Run that stalled, parked or needed rescue for a reason in Kitman, not in the work.`,
+    'Give each a stable kebab-case key naming the problem, not the week: the same problem must get the same key next time.',
+    "Propose Memory when agents can avoid it by knowing something, or a Task when something has to change; when the change is clear, say how to fix it as an errand (small) or a build (a feature). Cite every Transcript point (runId, stepAttemptId, sequence) it shows in. Cite what happened: tool calls and results, files and answers. An agent's own messages are not evidence. Leave out anything seen in one Run only.",
+    "Never quote a person's words into a lesson."
+  ].join('\n\n')
+
+const point = (cited: TranscriptPoint) => `${cited.runId}/${cited.stepAttemptId}/${cited.sequence}`
+
+/** The one value every cited Run has, if they share it. */
+const shared = (cited: readonly ReadRun[], field: 'teamId') => {
+  const values = new Set(cited.map(run => run[field]))
+  const [only] = values
+
+  return values.size === 1 ? only : undefined
+}
+
+/**
+ * What a finding proposes, citing only evidence that was read (not an agent's own messages), or why it is left out
+ * when that evidence falls in fewer than two Runs.
+ */
+const proposal = (
+  finding: Finding,
+  runs: readonly ReadRun[]
+): { readonly request: ProposeRequest } | { readonly request?: undefined; readonly reason: string } => {
+  const evidence = new Set(
+    runs.flatMap(run =>
+      run.entries.flatMap(entry =>
+        entry.kind === 'message'
+          ? []
+          : [point({ runId: run.runId, stepAttemptId: entry.stepAttemptId, sequence: entry.sequence })]
+      )
+    )
+  )
+
+  const citations = [
+    ...new Map(
+      finding.citations.filter(cited => evidence.has(point(cited))).map(cited => [point(cited), cited])
+    ).values()
+  ]
+
+  const runIds = new Set(citations.map(cited => cited.runId))
+  const [first, ...rest] = citations
+
+  if (first === undefined)
+    return { reason: 'It cites no evidence that was read: an agent’s own words or a summary are not evidence' }
+
+  if (runIds.size < 2) return { reason: 'It was seen in one Run only' }
+
+  const teamId = shared(
+    runs.filter(run => runIds.has(run.runId)),
+    'teamId'
+  )
+
+  if (finding.kind === 'memory' && teamId !== undefined)
+    return { request: { kind: 'memory', teamId, content: finding.lesson, citations: [first, ...rest] } }
+
+  return {
+    request: {
+      kind: 'task',
+      title: finding.lesson,
+      description: finding.detail ?? finding.lesson,
+      ...(teamId === undefined ? undefined : { teamId }),
+      key: finding.key,
+      citations: [first, ...rest]
+    }
+  }
+}
+
+/**
+ * Reads every Run that settled in the last week (or `days`), of one Team or every Team the person it acts for may read,
+ * completed ones too, and proposes Memory and Tasks for what went wrong in at least two, each with a category and a stable key. A key that
+ * matches an open Task or a waiting proposal adds the new Runs there instead of a duplicate. With `improvements`, that
+ * many findings are started as Errands or Builds. Memory belongs to one Team, so a lesson from Runs in several
+ * becomes a Task.
+ */
+export default defineLoop({
+  id: 'hindsight',
+  version: '1.0.0',
+  title: 'Hindsight',
+  input: Input,
+  output: Output,
+  outcome: 'investigation',
+  agents: { investigator: 'investigator' },
+  checkout: 'none',
+  schedule: { rule: { frequency: 'weekly', daysOfWeek: [1], hour: 9, minute: 0 }, timezone: 'UTC' },
+  capabilities: ['read_transcripts', 'agent_work', 'propose'],
+  calls: () => [errand, build],
+  run: input =>
+    Effect.gen(function* () {
+      const days = input.days ?? 7
+      const read = yield* transcripts('read', { days })
+      const runs = read.runs.filter(run => input.teamId === undefined || run.teamId === input.teamId)
+
+      if (runs.length < 2)
+        return {
+          summary: `Nothing recurred: ${runs.length === 0 ? 'no Run' : 'one Run'} settled in the last ${days} days.`,
+          proposals: [],
+          leftOut: [],
+          improvements: []
+        }
+
+      const { findings } = yield* agentWork('find', {
+        agent: 'investigator',
+        prompt: prompt(runs, days),
+        output: Findings
+      })
+
+      const judged = findings.map(finding => ({ finding, judged: proposal(finding, runs) }))
+
+      const leftOut = judged.flatMap(({ finding, judged }) =>
+        judged.request === undefined ? [{ key: finding.key, reason: judged.reason }] : []
+      )
+
+      const kept = judged.flatMap(({ finding, judged }) =>
+        judged.request === undefined ? [] : [{ finding, request: judged.request }]
+      )
+
+      const proposals = yield* Effect.forEach(kept, ({ finding, request }) =>
+        Effect.map(propose(`propose:${finding.key}`, request), made => ({
+          key: finding.key,
+          category: finding.category,
+          kind: made.kind,
+          id: made.id,
+          matched: made.matched === true,
+          runIds: [...new Set(request.citations.map(cited => cited.runId))]
+        }))
+      )
+
+      const fixable = kept.flatMap(({ finding }) =>
+        finding.fix === undefined ? [] : [{ ...finding, fix: finding.fix }]
+      )
+
+      const improvements = yield* Effect.forEach(fixable.slice(0, input.improvements ?? 0), finding => {
+        const started =
+          finding.fix.size === 'errand'
+            ? Effect.map(call(`improve:${finding.key}`, errand, { words: finding.fix.words }), done => done.status)
+            : Effect.map(call(`improve:${finding.key}`, build, { words: finding.fix.words }), built => built.stopped)
+
+        return started.pipe(
+          Effect.catchTag('ChildFailed', failed => Effect.succeed(`failed: ${failed.reason}`)),
+          Effect.map(outcome => ({ key: finding.key, loop: finding.fix.size, outcome }))
+        )
+      })
+
+      const fresh = proposals.filter(made => !made.matched).length
+
+      return {
+        summary:
+          proposals.length === 0
+            ? `Nothing recurred with evidence in ${runs.length} Runs.`
+            : `${proposals.length} recurring ${proposals.length === 1 ? 'problem' : 'problems'}: ${fresh} proposed, ${proposals.length - fresh} added to earlier work.`,
+        proposals,
+        leftOut,
+        improvements
+      }
+    })
+})