jackherd 0.0.0-stage → 1.0.0

package/src/plan-format/plan-structure.ts

@@ -0,0 +1,150 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { laneNameOf, parseSprintLanes, phaseIdsOfCell } from './lanes'
+import { escapeRegExp, firstTableRows, sectionLines, sectionStart } from './markdown'
+import {
+  deferralTarget,
+  endsPhase,
+  isCheckboxLine,
+  isOpenCheckboxLine,
+  isReviewGateLine,
+  type PlanPhase,
+  parsePlanPhases,
+  phaseHeadingPattern,
+} from './phases'
+import { terminalSafe } from './terminal-text'
+
+/** A `### Phase` heading (1-based line) whose section has tasks and neither a review gate nor the line saying why not. */
+export type PhaseWithoutGate = { line: number; id: string; title: string }
+
+/** A row of the lanes table (1-based line) whose phases cell names no phase id. */
+export type RowWithoutPhase = { line: number; lane: string; phases: string }
+
+/**
+ * A `### Phase` heading (1-based line) whose tasks are all ticked on the base branch while its own section still
+ * has open checkboxes not moved on with `→ P<n>` (`openLines`, 1-based).
+ */
+export type MergedPhaseWithOpenBoxes = PhaseWithoutGate & { openLines: number[] }
+
+type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; openLines: number[] }
+
+const noGatePattern = (language: PlanLanguage): RegExp =>
+  new RegExp(`^\\s*\\*\\*${escapeRegExp(PLAN_VOCABULARY[language].noReviewGate)}\\b`, 'i')
+
+const tickCount = (phase: PlanPhase): number => phase.items.filter((item) => item.done).length
+
+/** The phase's tasks before its review gate are all ticked: its work is on the branch the plan was read from. */
+const tasksDone = (phase: PlanPhase): boolean => {
+  const tasks = phase.items.filter((item) => !item.gate)
+  return tasks.length > 0 && tasks.every((item) => item.done)
+}
+
+/** Every `### Phase` section with whether it has tasks and whether it has a gate or says why it has none. */
+const phaseSections = (markdown: string, language: PlanLanguage): PhaseSection[] => {
+  const heading = phaseHeadingPattern(language)
+  const noGate = noGatePattern(language)
+  const sections: PhaseSection[] = []
+  let open: PhaseSection | null = null
+  for (const [index, line] of markdown.split('\n').entries()) {
+    const match = line.match(heading)
+    if (match) {
+      open = {
+        line: index + 1,
+        id: match[1].toLowerCase(),
+        title: terminalSafe(match[2]).trim(),
+        tasks: false,
+        gate: false,
+        openLines: [],
+      }
+      sections.push(open)
+    } else if (endsPhase(line)) {
+      open = null
+    } else if (open) {
+      open.tasks ||= isCheckboxLine(line)
+      open.gate ||= isReviewGateLine(line) || noGate.test(line)
+      if (isOpenCheckboxLine(line) && deferralTarget(line, open.id) === null) open.openLines.push(index + 1)
+    }
+  }
+  return sections
+}
+
+/** The ids of the `### Phase` headings of a plan. */
+export const phaseIdsOfPlan = (markdown: string, language: PlanLanguage): Set<string> =>
+  new Set(phaseSections(markdown, language).map(({ id }) => id))
+
+/**
+ * The phases a plan gained against `previousIds` (its phase ids before the change) that have checkboxes but
+ * neither a review gate nor a `**Kein Review-Gate:** <reason>` line. A phase without checkboxes of its own (one
+ * that points at `## Dokumentation`) has nothing to gate; phases the plan already had are not read, so an old
+ * plan does not turn red when it is touched.
+ */
+export const newPhasesWithoutReviewGate = (
+  markdown: string,
+  language: PlanLanguage,
+  previousIds: ReadonlySet<string>,
+): PhaseWithoutGate[] =>
+  phaseSections(markdown, language)
+    .filter(({ id, tasks, gate }) => tasks && !gate && !previousIds.has(id))
+    .map(({ line, id, title }) => ({ line, id, title }))
+
+/** Whether the document has a lanes table (`## Spuren`): a board, not a plan. */
+export const hasLanesTable = (markdown: string, language: PlanLanguage): boolean =>
+  sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes).some((line) => line.startsWith('|'))
+
+/**
+ * The phases of `markdown` that are merged but not closed: on the base branch (`base`, the plan there) every task
+ * before the review gate is ticked, the change does not tick the phase further, and its own section still has open
+ * checkboxes, gate boxes included, that no `→ P<n>` at their end moves on. A phase the base branch lacks, or one
+ * with an open task there, is still being worked on.
+ */
+export const mergedPhasesWithOpenBoxes = (
+  markdown: string,
+  base: string,
+  language: PlanLanguage,
+): MergedPhaseWithOpenBoxes[] => {
+  const baseById = new Map(parsePlanPhases(base, language).map((phase) => [phase.id, phase]))
+  const currentById = new Map(parsePlanPhases(markdown, language).map((phase) => [phase.id, phase]))
+  const isMerged = (id: string): boolean => {
+    const [basePhase, currentPhase] = [baseById.get(id), currentById.get(id)]
+    return (
+      basePhase !== undefined &&
+      currentPhase !== undefined &&
+      tasksDone(basePhase) &&
+      tickCount(currentPhase) <= tickCount(basePhase)
+    )
+  }
+  return phaseSections(markdown, language)
+    .filter(({ id, openLines }) => openLines.length > 0 && isMerged(id))
+    .map(({ line, id, title, openLines }) => ({ line, id, title, openLines }))
+}
+
+/**
+ * The rows of the lanes table (`## Spuren`) that are not in `previousLines` word for word and whose phases cell
+ * names no phase id (`P10c`), so neither the view nor the watcher can tie that step to a phase. The table is read
+ * as `parseSprintLanes` reads it (its first table, a lane closed when any of its rows says so); rows of a closed
+ * lane are history and stay out.
+ */
+export const boardRowsWithoutPhase = (
+  markdown: string,
+  language: PlanLanguage,
+  previousLines: ReadonlySet<string>,
+): RowWithoutPhase[] => {
+  const start = sectionStart(markdown, PLAN_VOCABULARY[language].sections.lanes)
+  if (start === -1) return []
+  const closed = new Set(
+    parseSprintLanes(markdown, language)
+      .filter((lane) => lane.closed)
+      .map((lane) => lane.name),
+  )
+  const rows: RowWithoutPhase[] = []
+  let previous: string | null = null
+  for (const { index, line, cells } of firstTableRows(
+    sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes),
+  )) {
+    const [name = '', , , phases = ''] = cells
+    const lane = laneNameOf(name, previous)
+    previous = lane ?? previous
+    const counts = lane !== null && !closed.has(lane) && !previousLines.has(line)
+    if (counts && phaseIdsOfCell(phases, language).length === 0) rows.push({ line: start + index + 1, lane, phases })
+  }
+  return rows
+}

package/src/plan-format/progress.ts

@@ -0,0 +1,202 @@
+import { PHASE_ID_PREFIX, type PlanStep, type SprintLane } from './lanes'
+import type { ChecklistItem, DeferredItem, PlanPhase } from './phases'
+
+/**
+ * `title` is null when the sprint names a phase the plan does not have; `touched` and `deferred` carry the plan
+ * phase's own, and the deferred checkboxes are in neither `done` nor `total`.
+ */
+export type PhaseProgress = {
+  id: string
+  title: string | null
+  done: number
+  total: number
+  items: ChecklistItem[]
+  deferred?: DeferredItem[]
+  touched?: true
+}
+
+export type StepProgress = { step: PlanStep; phases: PhaseProgress[] }
+
+export type LaneProgress = {
+  lane: SprintLane
+  steps: StepProgress[]
+  current: { stepIndex: number; phaseId: string } | null
+  done: number
+  total: number
+}
+
+/** Parsed phases per plan link, as the sprint table spells the link; a missing key is an unread plan. */
+export type PlansByHref = Record<string, PlanPhase[]>
+
+export const sumPhases = (phases: readonly PhaseProgress[]): { done: number; total: number } => ({
+  done: phases.reduce((sum, phase) => sum + phase.done, 0),
+  total: phases.reduce((sum, phase) => sum + phase.total, 0),
+})
+
+const baseId = (id: string): string => id.replace(/[a-z]$/, '')
+
+const findPhase = (phases: PlanPhase[], id: string): PlanPhase | undefined =>
+  phases.find((phase) => phase.id === id) ?? phases.find((phase) => phase.id === baseId(id))
+
+/**
+ * The ids of a step that show a phase of their own. An id the plan lacks (`5b`) falls back to its
+ * base phase (`5`); when the step already names that phase by its own id, or an earlier id fell
+ * back to it, the fallback would list the same tasks twice, so it is dropped. A lone fallback
+ * stays: the sprint line `P4a` finds phase 4 in the plans that have no `4a`.
+ */
+export const keptPhaseIds = (phases: PlanPhase[], ids: readonly string[]): string[] => {
+  const shown = new Set(ids.flatMap((id) => phases.filter((phase) => phase.id === id)))
+  return ids.filter((id) => {
+    const phase = findPhase(phases, id)
+    if (!phase || phase.id === id) return true
+    if (shown.has(phase)) return false
+    shown.add(phase)
+    return true
+  })
+}
+
+const phaseProgress = (phases: PlanPhase[], id: string): PhaseProgress => {
+  const phase = findPhase(phases, id)
+  const items = phase?.items ?? []
+  return {
+    id,
+    title: phase?.title ?? null,
+    done: items.filter((item) => item.done).length,
+    total: items.length,
+    items,
+    ...(phase?.deferred ? { deferred: phase.deferred } : {}),
+    ...(phase?.touched ? { touched: true as const } : {}),
+  }
+}
+
+const isOpen = ({ done, total }: PhaseProgress): boolean => done < total
+
+/** A phase the plan has written: one with at least one checkbox, not one missing from the plan or without any. */
+const isWritten = ({ total }: PhaseProgress): boolean => total > 0
+
+const newestWrittenStepIndex = (steps: readonly StepProgress[]): number =>
+  steps.reduce((last, { phases }, index) => (phases.some(isWritten) ? index : last), -1)
+
+const newestRowIndex = (steps: readonly StepProgress[]): number =>
+  steps.reduce((last, { step }, index) => (step.withoutRow ? last : index), -1)
+
+const isTouched = (phase: PhaseProgress): boolean => phase.touched === true && isWritten(phase)
+
+/**
+ * A phase the lane ticked to the end in its worktree while the base branch does not carry those ticks yet: still
+ * the lane's work until it is merged, not a finished phase.
+ */
+export const isTickedUnmerged = (phase: PhaseProgress): boolean => isTouched(phase) && !isOpen(phase)
+
+/** The first phase `pick` finds in a step, from the newest step back. */
+const newestStepWith = (
+  steps: readonly StepProgress[],
+  pick: (phases: readonly PhaseProgress[]) => PhaseProgress | undefined,
+): LaneProgress['current'] => {
+  for (let stepIndex = steps.length - 1; stepIndex >= 0; stepIndex--) {
+    const phase = pick(steps[stepIndex].phases)
+    if (phase) return { stepIndex, phaseId: phase.id }
+  }
+  return null
+}
+
+type LocatedPhase = { phase: PhaseProgress; current: NonNullable<LaneProgress['current']> }
+
+/** The phase a step shows for `id`: by that id, else by its base id, as `keptPhaseIds` keeps a lone fallback. */
+const shownPhase = (phases: readonly PhaseProgress[], id: string): PhaseProgress | undefined =>
+  phases.find((phase) => phase.id === id) ?? phases.find((phase) => phase.id === baseId(id))
+
+/** The phase `id` as the newest step before `before` that shows it from the same plan has it. */
+const earlierPhase = (steps: readonly StepProgress[], before: number, id: string): LocatedPhase | null => {
+  const planHref = steps[before].step.planHref
+  for (let stepIndex = before - 1; stepIndex >= 0; stepIndex--) {
+    if (steps[stepIndex].step.planHref !== planHref) continue
+    const phase = shownPhase(steps[stepIndex].phases, id)
+    if (phase) return { phase, current: { stepIndex, phaseId: phase.id } }
+  }
+  return null
+}
+
+/**
+ * The phases a board row names, in its order, each located in the step that shows it: its own for a phase it names
+ * first, an earlier step's for one it repeats (`namedPhaseIds`, every id the row names once some were repeats).
+ */
+const rowPhases = (steps: readonly StepProgress[], stepIndex: number): LocatedPhase[] => {
+  const row = steps[stepIndex]
+  if (!row) return []
+  const own = row.phases.map((phase) => ({ phase, current: { stepIndex, phaseId: phase.id } }))
+  const named = row.step.namedPhaseIds
+  if (!named) return own
+  return named.flatMap((id) => {
+    const located = own.find((entry) => entry.phase.id === id) ?? earlierPhase(steps, stepIndex, id)
+    return located ? [located] : []
+  })
+}
+
+const touchedOpenPhaseOf = (phases: readonly PhaseProgress[]): PhaseProgress | undefined =>
+  phases.find((phase) => isTouched(phase) && isOpen(phase))
+
+const lastTickedUnmergedOf = (phases: readonly PhaseProgress[]): PhaseProgress | undefined =>
+  phases.filter(isTickedUnmerged).at(-1)
+
+/**
+ * The phase the lane's newest board row names, a step `withWorkedPhases` added not counted: an open one the lane
+ * ticks in its worktree, else the last one it ticked to the end without a merge, else the first open one. Null when
+ * that row names no written phase or every phase it names is merged, i.e. done and carried by the base branch.
+ * A phase the row repeats from an earlier row counts too (`rowPhases`).
+ */
+const newestRowPhase = (steps: readonly StepProgress[]): LaneProgress['current'] => {
+  const located = rowPhases(steps, newestRowIndex(steps)).filter(({ phase }) => isWritten(phase))
+  const phases = located.map(({ phase }) => phase)
+  const phase = touchedOpenPhaseOf(phases) ?? lastTickedUnmergedOf(phases) ?? phases.find(isOpen)
+  return located.find((entry) => entry.phase === phase)?.current ?? null
+}
+
+/**
+ * The phase from the ticks alone, when the newest board row decides nothing: among the phases whose ticks differ in
+ * the worktree from the base branch, an open one from the newest step (the first within it), else one ticked to the
+ * end from the newest step (the last within it); without such a phase, the open phase of the lane's newest step with
+ * a written phase (`isWritten`); else none. Open items left in an earlier step, once the newest one is done, stay
+ * visible but are not what the lane works on (D81).
+ */
+const phaseFromTicks = (steps: readonly StepProgress[]): LaneProgress['current'] => {
+  const touched = newestStepWith(steps, touchedOpenPhaseOf) ?? newestStepWith(steps, lastTickedUnmergedOf)
+  if (touched) return touched
+  const lastIndex = newestWrittenStepIndex(steps)
+  const phase = steps[lastIndex]?.phases.find(isOpen)
+  return phase ? { stepIndex: lastIndex, phaseId: phase.id } : null
+}
+
+/**
+ * The phase a lane works on: the one its newest board row names (`newestRowPhase`), so ticks the lane set in older
+ * phases while tidying the plan do not take over; when that row decides nothing, the ticks do (`phaseFromTicks`).
+ * A phase ticked to the end stays current until the base branch carries its ticks.
+ */
+export const currentPhaseOf = (steps: readonly StepProgress[]): LaneProgress['current'] =>
+  newestRowPhase(steps) ?? phaseFromTicks(steps)
+
+/** Progress of a lane over the phases its steps name; `currentPhaseOf` picks the current phase. */
+export const laneProgress = (lane: SprintLane, plans: PlansByHref): LaneProgress => {
+  const steps = lane.steps.map((step) => {
+    const phases = step.planHref ? plans[step.planHref] : undefined
+    return { step, phases: phases ? keptPhaseIds(phases, step.phaseIds).map((id) => phaseProgress(phases, id)) : [] }
+  })
+  return { lane, steps, current: currentPhaseOf(steps), ...sumPhases(steps.flatMap((step) => step.phases)) }
+}
+
+export const currentPhase = (progress: LaneProgress): PhaseProgress | null => {
+  if (!progress.current) return null
+  const { stepIndex, phaseId } = progress.current
+  return progress.steps[stepIndex].phases.find((phase) => phase.id === phaseId) ?? null
+}
+
+/** The item being worked on: the first open checkbox of a phase in plan order, a review-gate item included; null when none is open. */
+export const activeItem = (phase: Pick<PhaseProgress, 'items'>): ChecklistItem | null =>
+  phase.items.find((item) => !item.done) ?? null
+
+/** The sidebar title of a lane, e.g. `P4 · 7/12` or `P4 · 12/12` while ticked and not merged; null when nothing of the lane could be counted. */
+export const shortTitle = (progress: LaneProgress): string | null => {
+  const phase = currentPhase(progress)
+  if (phase) return `${PHASE_ID_PREFIX}${phase.id} · ${phase.done}/${phase.total}`
+  return progress.total > 0 ? `✓ ${progress.done}/${progress.total}` : null
+}

package/src/plan-format/sprint-document.ts

@@ -0,0 +1,69 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { allTables, firstTableWithHeader, sectionLines, subsectionLines } from './markdown'
+
+const PHASE_ID_IN_CELL = /^(\d+[a-z]?)\b/
+
+/** What a sprint document says around its lanes table: its goal and its history. */
+export type SprintPlanRow = { cells: string[]; title: string | null; href: string | null }
+
+/** One table of the plans section: the line above it (`**Folgepläne …:**`), its header and its rows. */
+export type SprintPlanTable = { caption: string | null; header: string[]; rows: SprintPlanRow[] }
+
+export type SprintDocument = {
+  /** The tables of the plans section (core plans, follow-up plans), each row with the plan it names. */
+  planTables: SprintPlanTable[]
+  /** The paragraphs of the goal section, or of the text before the first section when there is none. */
+  goal: string[]
+  history: { header: string[]; rows: string[][] }
+}
+
+const paragraphs = (lines: string[]): string[] =>
+  lines
+    .join('\n')
+    .split(/\n\s*\n/)
+    .map((paragraph) => paragraph.trim())
+    .filter(Boolean)
+
+const PLAN_LINK = /\[([^\]]+)\]\(([^)\s]+)\)/
+
+const planRowOf = (cells: string[]): SprintPlanRow => {
+  const link = cells.map((cell) => PLAN_LINK.exec(cell)).find((match) => match !== null)
+  return { cells, title: link?.[1] ?? null, href: link?.[2] ?? null }
+}
+
+const textBeforeFirstSection = (markdown: string): string[] => {
+  const lines = markdown.split('\n')
+  const end = lines.findIndex((line) => /^##\s/.test(line))
+  const intro = (end === -1 ? lines : lines.slice(0, end)).filter((line) => !/^#\s/.test(line))
+  return paragraphs(intro).filter((paragraph) => !/^\*\*[^*]+:\*\*/.test(paragraph))
+}
+
+export const readSprintDocument = (markdown: string, language: PlanLanguage): SprintDocument => {
+  const { goal, history, plans } = PLAN_VOCABULARY[language].sections
+  const goalParagraphs = paragraphs(sectionLines(markdown, goal))
+  return {
+    planTables: allTables(sectionLines(markdown, plans)).map(({ caption, header, rows }) => ({
+      caption,
+      header,
+      rows: rows.map(planRowOf),
+    })),
+    goal: goalParagraphs.length > 0 ? goalParagraphs : textBeforeFirstSection(markdown),
+    history: firstTableWithHeader(sectionLines(markdown, history)),
+  }
+}
+
+/**
+ * The `Depends on` cell of each phase from the plan's dependency table, by phase id (`4`, `4b`). The
+ * first cell of a row starts with the id (`3 — Sync-Engine`); a plan without the table gives an empty map.
+ */
+export const readPhaseDependencies = (planMarkdown: string, language: PlanLanguage): Record<string, string> => {
+  const { sections, columns } = PLAN_VOCABULARY[language]
+  const { header, rows } = firstTableWithHeader(subsectionLines(planMarkdown, sections.dependencies))
+  const column = header.indexOf(columns.dependsOn)
+  if (column === -1) return {}
+  const entries = rows.flatMap((cells) => {
+    const id = PHASE_ID_IN_CELL.exec(cells[0] ?? '')?.[1]
+    return id ? [[id, cells[column] ?? ''] as const] : []
+  })
+  return Object.fromEntries(entries)
+}

package/src/plan-format/terminal-text.ts

@@ -0,0 +1,28 @@
+/**
+ * C0 and C1 control characters (ESC, BEL, CR, the 8-bit CSI U+009B …), the bidi marks that reorder text on screen
+ * and the Unicode line and paragraph separators, which a reader that splits on them would take as a new line. A
+ * terminal executes the first instead of printing them.
+ */
+const UNSAFE_RANGES: [number, number][] = [
+  [0x00, 0x1f],
+  [0x7f, 0x9f],
+  [0x061c, 0x061c],
+  [0x200e, 0x200f],
+  [0x2028, 0x2029],
+  [0x202a, 0x202e],
+  [0x2066, 0x2069],
+]
+
+const escapeCodePoint = (codePoint: number): string => `\\u${codePoint.toString(16).padStart(4, '0')}`
+
+const UNSAFE_TERMINAL_TEXT = new RegExp(
+  `[${UNSAFE_RANGES.map(([from, to]) => `${escapeCodePoint(from)}-${escapeCodePoint(to)}`).join('')}]`,
+  'g',
+)
+
+/**
+ * Text from outside the program (a plan file, a pull request title) made safe to print: every control
+ * character is dropped, so an embedded escape sequence shows as harmless leftovers instead of acting
+ * on the terminal. Apply it where such text enters, before any styling is added.
+ */
+export const terminalSafe = (text: string): string => text.replace(UNSAFE_TERMINAL_TEXT, '')

package/src/plans/board-choice.ts

@@ -0,0 +1,60 @@
+/** A board file that came into question: the lane names its table lists and when it last changed (epoch seconds). */
+export type BoardCandidate = { path: string; lanes: readonly string[]; changedAt: number }
+
+export type BoardReason =
+  | { kind: 'only' }
+  | { kind: 'lanes'; count: number }
+  | { kind: 'tie'; count: number }
+  | { kind: 'newest' }
+
+export type BoardChoice = { chosen: BoardCandidate; others: BoardCandidate[]; reason: BoardReason }
+
+const foundIn = (candidate: BoardCandidate, found: ReadonlySet<string>): number =>
+  candidate.lanes.filter((lane) => found.has(lane)).length
+
+const reasonOf = (hits: number, nextHits: number): BoardReason => {
+  if (hits === 0) return { kind: 'newest' }
+  return hits === nextHits ? { kind: 'tie', count: hits } : { kind: 'lanes', count: hits }
+}
+
+/**
+ * The board to read when none is named: the one whose table names the most of the lanes that were found (a
+ * worktree with a herdr agent), then the most recently changed, then the path that sorts last (the rule before
+ * boards were compared), so every run of the same state chooses the same board. A board that lists lanes nobody runs does not outrank one that
+ * lists the running ones.
+ */
+export const chooseBoard = (
+  candidates: readonly BoardCandidate[],
+  foundLanes: readonly string[],
+): BoardChoice | null => {
+  const found = new Set(foundLanes)
+  const ranked = candidates
+    .map((candidate) => ({ candidate, hits: foundIn(candidate, found) }))
+    .sort(
+      (left, right) =>
+        right.hits - left.hits ||
+        right.candidate.changedAt - left.candidate.changedAt ||
+        right.candidate.path.localeCompare(left.candidate.path),
+    )
+  const [first, ...rest] = ranked
+  if (!first) return null
+  const others = rest.map(({ candidate }) => candidate)
+  if (rest.length === 0) return { chosen: first.candidate, others, reason: { kind: 'only' } }
+  const reason: BoardReason = reasonOf(first.hits, rest[0].hits)
+  return { chosen: first.candidate, others, reason }
+}
+
+const reasonText = (reason: BoardReason, term: string): string => {
+  if (reason.kind === 'lanes') return `names ${reason.count} found ${reason.count === 1 ? 'lane' : 'lanes'}`
+  if (reason.kind === 'tie')
+    return `tied on ${reason.count} found ${reason.count === 1 ? 'lane' : 'lanes'}, newest taken`
+  if (reason.kind === 'newest') return `no found lane in any ${term}, newest taken`
+  return ''
+}
+
+/** Why this board and not another, with the way out; null when there was nothing to choose between. */
+export const boardNotice = (choice: BoardChoice, term: string): string | null => {
+  if (choice.others.length === 0) return null
+  const others = choice.others.map((other) => other.path).join(', ')
+  return `${choice.chosen.path} chosen of ${choice.others.length + 1}: ${reasonText(choice.reason, term)}; others: ${others}; override with --board <path>`
+}

package/src/plans/board-pick.ts

@@ -0,0 +1,72 @@
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { parseSprintLanes } from '../plan-format'
+import { type BoardCandidate, boardNotice, chooseBoard } from './board-choice'
+import { lastCommitTime, worktreeNames } from './git'
+import { discoverLanes } from './lane-discovery'
+import { baseRefOf, boardGlobOf, boardRepoPathOf, type PlansSettings } from './settings'
+import { boardTexts } from './texts'
+
+/** The board file that was chosen, and the line that says why when there was a choice. */
+export type PickedBoard = { file: string; notice: string | null }
+
+const boardFilesIn = (root: string, glob: string): string[] =>
+  existsSync(root) ? [...new Bun.Glob(glob).scanSync({ cwd: root })].sort().map((file) => join(root, file)) : []
+
+/** Seconds since the epoch of the last commit on the base ref that touched the board; the file's mtime when none did. */
+const changedAtOf = (root: string, settings: PlansSettings, file: string): number =>
+  lastCommitTime(root, baseRefOf(settings), boardRepoPathOf(root, settings, file)) ??
+  Math.floor(statSync(file).mtimeMs / 1000)
+
+const candidateOf = (root: string, settings: PlansSettings, file: string): BoardCandidate => ({
+  path: relative(root, file),
+  lanes: parseSprintLanes(readFileSync(file, 'utf8'), settings.planLanguage).map((lane) => lane.name),
+  changedAt: changedAtOf(root, settings, file),
+})
+
+/**
+ * The board under the plan directory, by `board.pattern` and `board.file`, in the first of `roots` that has
+ * one: the main checkout first, then the checkout the command runs in, whose board may not be on the base yet.
+ * Of several boards the one that names the `foundLanes` wins, see `chooseBoard`.
+ */
+export const pickBoard = (
+  roots: readonly string[],
+  settings: PlansSettings,
+  foundLanes: readonly string[],
+): PickedBoard => {
+  const glob = boardGlobOf(settings)
+  const found = roots.map((root) => ({ root, files: boardFilesIn(root, glob) })).find(({ files }) => files.length > 0)
+  const choice =
+    found &&
+    chooseBoard(
+      found.files.map((file) => candidateOf(found.root, settings, file)),
+      foundLanes,
+    )
+  if (!found || !choice) throw new Error(boardTexts(settings.board.term).missing(glob))
+  return { file: join(found.root, choice.chosen.path), notice: boardNotice(choice, settings.board.term) }
+}
+
+/**
+ * The worktrees under the project that carry an agent of their name: the lanes that exist before any board names
+ * them. None when anything on the way fails (the terminal cannot be asked, the directory cannot be read): the
+ * choice of a board must not fail over the search for lanes.
+ */
+export const foundLanesOf = (root: string, settings: PlansSettings, agentNames: () => string[]): string[] => {
+  try {
+    return discoverLanes({
+      worktrees: worktreeNames(join(root, settings.worktreeDirectory)),
+      agentNames: agentNames(),
+      sprintLanes: [],
+    })
+  } catch {
+    return []
+  }
+}
+
+/** The board `--board` names, else the one `pickBoard` chooses; the lanes are looked up only in that case. */
+export const boardFor = (
+  boardPath: string | null,
+  roots: readonly string[],
+  settings: PlansSettings,
+  foundLanes: () => string[],
+): PickedBoard => (boardPath ? { file: resolve(boardPath), notice: null } : pickBoard(roots, settings, foundLanes()))

package/src/plans/board-rows.ts

@@ -0,0 +1,62 @@
+import { type PlanStep, parseSprintLanes, type SprintLane, withoutRepeats } from '../plan-format'
+import type { PlanLanguage } from '../vocabulary'
+
+/**
+ * The board's lanes as the base ref has them, plus the rows only the checkout's board file has; `rowsFromCheckout`
+ * counts those rows.
+ */
+export type BoardRows = { lanes: SprintLane[]; rowsFromCheckout: number }
+
+const repeatsLabel = (lane: SprintLane, step: PlanStep): boolean =>
+  lane.steps.some((known) => known.planHref === step.planHref && known.label === step.label)
+
+/** A row without phase ids of its own still counts when it has no plan link or repeats phases an earlier row named. */
+const countsWithoutIds = (lane: SprintLane, step: PlanStep): boolean =>
+  (step.planHref === null || step.namedPhaseIds !== undefined) && !repeatsLabel(lane, step)
+
+/**
+ * The step as far as the lane does not have it yet; null when nothing of it is new. A step with a plan link that
+ * names no phase carries nothing to show; one the parser emptied as a repeat stays, since its phases tell which
+ * phase the lane's newest row names. A step that names only phases the base rows name is dropped: it is mostly a base
+ * row the checkout reworded (`PR offen` to `gemergt`), and appending it would make an old row the newest.
+ */
+const newPartOf = (lane: SprintLane, step: PlanStep): PlanStep | null => {
+  if (step.phaseIds.length === 0) return countsWithoutIds(lane, step) ? step : null
+  const rest = withoutRepeats(lane, step)
+  return rest.phaseIds.length > 0 ? rest : null
+}
+
+/** The lane with the checkout's steps it does not have yet; the same object when nothing is new. */
+const grownBy = (known: SprintLane, checkout: SprintLane | undefined): SprintLane => {
+  const grown: SprintLane = { ...known, steps: [...known.steps] }
+  for (const step of checkout?.steps ?? []) {
+    const part = newPartOf(grown, step)
+    if (part !== null) grown.steps.push(part)
+  }
+  return grown.steps.length > known.steps.length ? grown : known
+}
+
+/**
+ * The board at the base ref with the rows only the checkout has. Base lanes keep their order and their rows;
+ * a lane only the checkout names is appended; a step of a known lane is added when the base does not name its
+ * phases for that plan yet (identity: plan link and phase id), a row without a plan link when its label is new.
+ * Both sides come parsed, this function reads no text.
+ */
+export const withCheckoutRows = (base: readonly SprintLane[], checkout: readonly SprintLane[]): BoardRows => {
+  const checkoutByName = new Map(checkout.map((lane) => [lane.name, lane]))
+  const knownNames = new Set(base.map((lane) => lane.name))
+  const grown = base.map((lane) => grownBy(lane, checkoutByName.get(lane.name)))
+  const lanes = [...grown, ...checkout.filter((lane) => !knownNames.has(lane.name))]
+  const rowsFromCheckout = lanes.reduce(
+    (count, lane, index) => count + lane.steps.length - (base[index]?.steps.length ?? 0),
+    0,
+  )
+  return { lanes, rowsFromCheckout }
+}
+
+/** The board of `baseText` with the rows of `checkoutText` it lacks; a checkout with the same text adds nothing. */
+export const boardRowsOf = (baseText: string, checkoutText: string, language: PlanLanguage): BoardRows => {
+  const lanes = parseSprintLanes(baseText, language)
+  if (checkoutText === baseText) return { lanes, rowsFromCheckout: 0 }
+  return withCheckoutRows(lanes, parseSprintLanes(checkoutText, language))
+}