jackherd 1.9.0 → 1.11.0

package/src/lane/close.ts

@@ -0,0 +1,141 @@
+import { twoDigits } from '../plan-format/clock'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { errorText } from '../plans/error-text'
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import { closedMark, historyDate, withHistoryRow, withLaneClosed } from './close-board'
+import { BOARD_LANE, type ClosableLane, type CloseFacts, closeVerdict } from './close-check'
+import { LANE_CLOSE_COMMAND } from './close-command-line'
+
+/** The facts the check reads, and the herdr workspace the worktree is open in, null when none is. */
+export type CloseSurvey = { facts: CloseFacts; workspace: string | null }
+
+/** What `jh lane close` was asked for; `worktree` comes from the settings and the lane's name, never from a reply. */
+export type CloseRequest = {
+  lane: string
+  worktree: string
+  /** The board as the output names it, relative to the main checkout. */
+  boardPath: string
+  dryRun: boolean
+  now: Date
+  language: PlanLanguage
+}
+
+/** The I/O `closeLane` drives; every port but `survey` and the printers throws when it fails. */
+export type ClosePorts = {
+  survey: () => Promise<CloseSurvey>
+  /** Ends the agent in this pane and returns once the terminal no longer lists its session. */
+  exitAgent: (pane: string) => Promise<void>
+  /** Removes the worktree without force, then closes the terminal workspace `workspace` names, if any. */
+  removeWorktree: (worktree: string, workspace: string | null) => void
+  /** Deletes the branch only while it still points to `head`, the commit the check compared. */
+  deleteBranch: (branch: string, head: string) => void
+  readBoard: () => string
+  writeBoard: (text: string) => void
+  print: (line: string) => void
+  printError: (line: string) => void
+}
+
+type ClosedLane = { lane: string } & ClosableLane
+
+type Step = { label: string; run: () => Promise<void> | void }
+
+/** A merge commit as the history row cites it. */
+const SHORT_COMMIT_LENGTH = 7
+
+const HISTORY_TEXT: Record<PlanLanguage, (closed: ClosedLane, mergeCommit: string) => string> = {
+  [PLAN_LANGUAGE.de]: ({ lane, branch, pullRequest }, mergeCommit) =>
+    `Spur \`${lane}\` abgeräumt mit \`${LANE_CLOSE_COMMAND}\`: PR #${pullRequest.number} gemergt (\`${mergeCommit}\`), Baum gleich Merge, Worktree entfernt, lokaler Branch \`${branch}\` gelöscht`,
+  [PLAN_LANGUAGE.en]: ({ lane, branch, pullRequest }, mergeCommit) =>
+    `Lane \`${lane}\` cleaned up with \`${LANE_CLOSE_COMMAND}\`: PR #${pullRequest.number} merged (\`${mergeCommit}\`), tree equal to the merge, worktree removed, local branch \`${branch}\` deleted`,
+}
+
+const clockOf = (time: Date): string => `${twoDigits(time.getHours())}:${twoDigits(time.getMinutes())}`
+
+/** The history row's text: the time, then what was closed and proven, in the board's language. */
+export const historyText = (closed: ClosedLane, request: Pick<CloseRequest, 'now' | 'language'>): string =>
+  `${clockOf(request.now)}: ${HISTORY_TEXT[request.language](closed, closed.pullRequest.mergeCommit.slice(0, SHORT_COMMIT_LENGTH))}`
+
+/** The board with the lane's rows marked and the history row on top. */
+const closedBoard = (board: string, closed: ClosedLane, request: CloseRequest): string =>
+  withHistoryRow(
+    withLaneClosed(board, closed.lane, closedMark(request.now, request.language), request.language),
+    historyDate(request.now),
+    historyText(closed, request),
+    request.language,
+  )
+
+const boardLabel = (facts: CloseFacts, request: CloseRequest): string =>
+  facts.boardLane === BOARD_LANE.closed
+    ? `add a history row in ${request.boardPath}, whose rows mark ${request.lane} already`
+    : `mark the rows of ${request.lane} "${closedMark(request.now, request.language)}" and add a history row in ${request.boardPath}`
+
+/** The removal steps after the agent is gone, in the order that never leaves the board claiming more than was done. */
+const removalSteps = (closed: ClosedLane, survey: CloseSurvey, request: CloseRequest, ports: ClosePorts): Step[] => {
+  const { workspace, facts } = survey
+  const place = workspace === null ? '' : ` and close workspace ${workspace}`
+  return [
+    {
+      label: `remove worktree ${request.worktree}${place}`,
+      run: () => ports.removeWorktree(request.worktree, workspace),
+    },
+    { label: `delete branch ${closed.branch}`, run: () => ports.deleteBranch(closed.branch, closed.head) },
+    { label: boardLabel(facts, request), run: () => ports.writeBoard(closedBoard(ports.readBoard(), closed, request)) },
+  ]
+}
+
+const exitSteps = ({ facts }: CloseSurvey, request: CloseRequest, ports: ClosePorts): Step[] => {
+  const { agent } = facts
+  if (agent === null) return []
+  return [
+    { label: `exit the agent of ${request.lane} and wait until it is gone`, run: () => ports.exitAgent(agent.pane) },
+  ]
+}
+
+/** The lane closable from `survey`, or null after printing every reason against it under `heading`. */
+const checked = (survey: CloseSurvey, heading: string, request: CloseRequest, ports: ClosePorts): ClosedLane | null => {
+  const verdict = closeVerdict(survey.facts)
+  if (verdict.kind === 'closable') return { lane: request.lane, ...verdict }
+  ports.printError(heading)
+  for (const refusal of verdict.refusals) ports.printError(`  ${terminalSafe(refusal)}`)
+  return null
+}
+
+/** Runs the steps in order, one line each; at the first failure, names it and every step left undone. */
+const runSteps = async (steps: readonly Step[], ports: ClosePorts): Promise<boolean> => {
+  for (const [index, step] of steps.entries()) {
+    try {
+      await step.run()
+      ports.print(`done: ${step.label}`)
+    } catch (error) {
+      ports.printError(`failed: ${step.label}: ${terminalSafe(errorText(error))}`)
+      for (const left of steps.slice(index + 1)) ports.printError(`not done: ${left.label}`)
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Closes a lane in one run, or refuses with every reason and changes nothing. Checks first (`closeVerdict`); a dry run
+ * stops there and prints the steps. Otherwise it ends the lane's agent, checks again, since the agent may have written
+ * until it exited, then removes the worktree and its workspace, deletes the local branch, and marks the board last, so
+ * the board never records a removal that failed. Exit 0 closed or dry run, 1 refused or failed.
+ */
+export const closeLane = async (request: CloseRequest, ports: ClosePorts): Promise<number> => {
+  const first = await ports.survey()
+  const closed = checked(first, `not closing ${request.lane}:`, request, ports)
+  if (closed === null) return 1
+  const exit = exitSteps(first, request, ports)
+  if (request.dryRun) {
+    ports.print(`dry run, nothing changed; closing ${request.lane} would:`)
+    for (const step of [...exit, ...removalSteps(closed, first, request, ports)]) ports.print(`  ${step.label}`)
+    return 0
+  }
+  if (!(await runSteps(exit, ports))) return 1
+  const settled = exit.length === 0 ? first : await ports.survey()
+  const late = checked(settled, `not closing ${request.lane} after its agent exited:`, request, ports)
+  if (late === null) return 1
+  if (!(await runSteps(removalSteps(late, settled, request, ports), ports))) return 1
+  ports.print(`closed ${request.lane}`)
+  return 0
+}

package/src/lane/command.ts

@@ -0,0 +1,13 @@
+import { run as runPrompt } from '../lane-prompt/command'
+
+const CLOSE = 'close'
+
+/**
+ * `jh lane close …` closes a lane, everything else is `jh lane prompt …`. `close` must come first, so the ask rule
+ * `jh lane close` always sees it; `jh lane --board b.md close x` reaches the prompt parser and is refused there.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (args[0] !== CLOSE) return runPrompt(args, cwd)
+  const { run: runClose } = await import('./close-command')
+  return runClose(args.slice(1), cwd)
+}

package/src/lane-prompt/additions.ts

@@ -0,0 +1,14 @@
+/** The line that ends a written lane prompt; what the coordinator adds below it survives every new writing. */
+export const ADDITIONS_MARKER = '<!-- jackherd: additions below this line stay when the prompt is written again -->'
+
+/** What follows the marker line of a written prompt; empty for no file, no marker line or nothing below it. */
+export const additionsOf = (existing: string | null): string => {
+  if (existing === null) return ''
+  const lines = existing.split('\n')
+  const marker = lines.indexOf(ADDITIONS_MARKER)
+  return marker === -1 ? '' : lines.slice(marker + 1).join('\n')
+}
+
+/** `prompt` closed by the marker and by the additions of the file it replaces, so writing twice changes nothing. */
+export const withAdditions = (prompt: string, existing: string | null): string =>
+  `${prompt}\n${ADDITIONS_MARKER}\n${additionsOf(existing)}`

package/src/lane-prompt/build.ts

@@ -0,0 +1,74 @@
+import { phaseLabel } from '../plan-format/lanes'
+import { LANE_PROMPT_OPENING, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { laneReportFile } from '../watch/lane-report-file'
+import { LANE_PROMPT_TEXTS, type LanePromptTexts } from './texts'
+
+/** A phase of the lane with the paths its row of the dependency table writes (`''` is the whole repository); null without a row. */
+export type LanePhase = { id: string; writes: string[] | null }
+
+/** A plan the lane works on, by its path from the repository root, with the lane's phases in it. */
+export type LanePlan = { path: string; phases: LanePhase[] }
+
+/**
+ * Everything a lane prompt is made of. `port` is null when the board gives the lane none; `handover` names the
+ * hand-over file a restarted lane reads first (`/orchestrate` § 8), null for a fresh start.
+ */
+export type LanePromptInput = {
+  language: PlanLanguage
+  lane: string
+  plans: LanePlan[]
+  port: number | null
+  handover: string | null
+}
+
+const writesText = (language: PlanLanguage, texts: LanePromptTexts, writes: string[] | null): string => {
+  if (writes === null) return texts.noWrites
+  const paths = writes.map((path) => (path === '' ? texts.wholeRepository : `\`${path}\``)).join(', ')
+  return `${PLAN_VOCABULARY[language].columns.writes}: ${paths}`
+}
+
+const phaseText = (language: PlanLanguage, texts: LanePromptTexts, phase: LanePhase): string =>
+  `\`${PLAN_VOCABULARY[language].phase} ${phaseLabel(phase.id)}\` (${writesText(language, texts, phase.writes)})`
+
+const planLines = (language: PlanLanguage, texts: LanePromptTexts, plan: LanePlan): string[] => [
+  `- \`${plan.path}\``,
+  ...plan.phases.map((phase) => `  - ${phaseText(language, texts, phase)}`),
+]
+
+const ruleLines = (input: LanePromptInput, texts: LanePromptTexts): string[] => [
+  input.port === null ? texts.noPort : texts.port(input.port),
+  texts.blocking,
+  texts.mustNot,
+  texts.commit,
+  texts.report(laneReportFile(input.lane)),
+  texts.textBlock,
+  texts.secret,
+  texts.askRule,
+  texts.approvalGate,
+  texts.helper(`${input.lane}-${texts.helperPurpose}`),
+]
+
+/**
+ * The prompt that starts a lane, in the plan language: a first line that names the lane (the words the ask hint hook
+ * and the project's lane exception recognise), the plans with their phases as `Phase P<n>` and each phase's write
+ * set, the rules of `/orchestrate` § 1 that `/implement` does not carry already, and the start: `/implement`, or the
+ * hand-over file after a restart.
+ */
+export const buildLanePrompt = (input: LanePromptInput): string => {
+  const texts = LANE_PROMPT_TEXTS[input.language]
+  return [
+    `${LANE_PROMPT_OPENING[input.language]} ${input.lane}. ${texts.answersTo}`,
+    '',
+    texts.phasesIntro,
+    '',
+    ...input.plans.flatMap((plan) => planLines(input.language, texts, plan)),
+    '',
+    texts.editInside,
+    texts.writeTools,
+    '',
+    ...ruleLines(input, texts).map((line) => `- ${line}`),
+    '',
+    input.handover === null ? texts.start : texts.restart(input.handover),
+    '',
+  ].join('\n')
+}

package/src/lane-prompt/command.ts

@@ -0,0 +1,93 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
+import { boardFor } from '../plans/board-pick'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { boardRepoPathOf, readSettings, worktreeOf } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { withAdditions } from './additions'
+import { buildLanePrompt } from './build'
+import { type BoardSource, type LanePromptRequest, lanePromptInputOf, type ReadPlan } from './input'
+import { LANE_PROMPT_USAGE, type LanePromptOptions, parseLanePromptOptions } from './options'
+
+/**
+ * What `lanePromptInputOf` reads, located from the command line, and the main checkout the default file goes to;
+ * `readLanePlan` reads from the lane's worktree, null for every plan while it has none.
+ */
+type PromptSources = {
+  request: LanePromptRequest
+  board: BoardSource
+  readPlan: ReadPlan
+  readLanePlan: ReadPlan
+  root: string
+}
+
+/** Where the prompt goes without `--out`: the hand-over directory of the main checkout, which git ignores. */
+export const defaultPromptFile = (root: string, lane: string): string =>
+  join(root, claudePath(HANDOVER_DIRECTORY), `${lane}-prompt.md`)
+
+/** The first of `roots` that holds `path` as a regular file, read; null when none does. */
+const readFirstIn =
+  (roots: readonly string[]) =>
+  (path: string): string | null => {
+    const file = roots
+      .map((root) => join(root, path))
+      .find((candidate) => existsSync(candidate) && statSync(candidate).isFile())
+    return file === undefined ? null : readFileSync(file, 'utf8')
+  }
+
+/** The lane's request, its board and the plan reader, from the checkouts of `cwd`; prints the board pick's notice. */
+const promptSourcesOf = (options: LanePromptOptions, cwd: string): PromptSources => {
+  const checkout = worktreeRoot(cwd)
+  const root = mainCheckout(cwd)
+  const settings = readSettings([checkout, root])
+  const boardPath = options.boardPath === null ? null : resolve(cwd, options.boardPath)
+  const board = boardFor(boardPath, [root, checkout], settings, () => [options.lane])
+  if (board.notice) console.error(board.notice)
+  const directory = dirname(boardRepoPathOf(root, settings, board.file))
+  return {
+    request: { lane: options.lane, handover: options.handover, language: settings.planLanguage },
+    board: { text: readFileSync(board.file, 'utf8'), directory, path: relative(cwd, board.file) },
+    readPlan: readFirstIn([root, checkout]),
+    readLanePlan: readFirstIn([worktreeOf(root, settings, options.lane)]),
+    root,
+  }
+}
+
+/** Writes `prompt` to `out`, closed by the marker and by the additions the file there already carries below it. */
+const writePrompt = (out: string, prompt: string): void => {
+  const existing = existsSync(out) ? readFileSync(out, 'utf8') : null
+  mkdirSync(dirname(out), { recursive: true })
+  writeFileSync(out, withAdditions(prompt, existing))
+}
+
+/**
+ * `jh lane prompt <lane> [--board <board.md>] [--out <file>] [--handover <file>]`: writes the lane's prompt, built
+ * from its board row and its plan in the plan language, and prints the file's path, so the coordinator sends it with
+ * `herdr agent prompt <lane> "$(cat <file>)"`. Below the marker line at the file's end the coordinator adds what the
+ * plan does not say; it stays through every new writing. A phase two open rows name is in no prompt and is reported on
+ * stderr. `--help` prints the usage. Exit 0 written, 1 refused or failed.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(LANE_PROMPT_USAGE)
+    return 0
+  }
+  try {
+    const options = parseLanePromptOptions(args)
+    const { request, board, readPlan, readLanePlan, root } = promptSourcesOf(options, cwd)
+    const result = lanePromptInputOf(request, board, readPlan, readLanePlan)
+    if (result.kind === 'refused') {
+      console.error(result.reason)
+      return 1
+    }
+    for (const notice of result.notices ?? []) console.error(notice)
+    const out = options.out === null ? defaultPromptFile(root, options.lane) : resolve(cwd, options.out)
+    writePrompt(out, buildLanePrompt(result.input))
+    console.log(out)
+    return 0
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/lane-prompt/input.ts

@@ -0,0 +1,157 @@
+import { type PhaseDependency, parseDependencyTable, writeSetOf } from '../plan-format/dependencies'
+import { parseSprintLanes, phaseLabel, resolvePlanPath, type SprintLane } from '../plan-format/lanes'
+import { parsePlanPhases } from '../plan-format/phases'
+import { isPhaseFinished } from '../plan-format/progress'
+import type { PlanLanguage } from '../vocabulary'
+import type { LanePhase, LanePlan, LanePromptInput } from './build'
+
+/** The lane to prompt, the hand-over file of a restart (null for a fresh start) and the plan language. */
+export type LanePromptRequest = { lane: string; handover: string | null; language: PlanLanguage }
+
+/**
+ * The board's text, its directory from the repository root, which its plan links are relative to, and the path a
+ * refusal names it by.
+ */
+export type BoardSource = { text: string; directory: string; path: string }
+
+/** A plan's text by its path from the repository root; null when it cannot be read. */
+export type ReadPlan = (path: string) => string | null
+
+/** `notices` is absent unless the board needs fixing: a phase two open rows name is in neither prompt. */
+export type LanePromptResult =
+  | { kind: 'prompt'; input: LanePromptInput; notices?: string[] }
+  | { kind: 'refused'; reason: string }
+
+type PlanSteps = { path: string; ids: string[] }
+
+type Refusal = { reason: string }
+
+type PlanOutcome = { plan: LanePlan } | Refusal
+
+type PlansOutcome = { plans: LanePlan[] } | Refusal
+
+const refused = (reason: string): LanePromptResult => ({ kind: 'refused', reason })
+
+/** The lane's plans by path in board order, each with the phase ids its rows name, rows of one plan merged. */
+const planStepsOf = (lane: SprintLane, directory: string): PlanSteps[] => {
+  const byPath = new Map<string, string[]>()
+  for (const step of lane.steps) {
+    if (step.planHref === null || step.phaseIds.length === 0) continue
+    const path = resolvePlanPath(directory, step.planHref)
+    byPath.set(path, [...new Set([...(byPath.get(path) ?? []), ...step.phaseIds])])
+  }
+  return [...byPath].map(([path, ids]) => ({ path, ids }))
+}
+
+/** The write set of the phase `id`; null without a row, for an unknown target or a cycle. */
+const phaseWriteSet = (rows: readonly PhaseDependency[], id: string): string[] | null => {
+  const row = rows.find((candidate) => candidate.id === id)
+  return row ? writeSetOf(row, new Map(rows.map((candidate) => [candidate.id, candidate]))) : null
+}
+
+/** A plan's text on the lane branch (null without a worktree or a copy there) and in the main checkout. */
+type PlanTexts = { lane: string | null; main: string | null }
+
+const finishedIdsOf = (text: string | null, language: PlanLanguage): Set<string> =>
+  new Set(
+    text === null ? [] : parsePlanPhases(text, language).flatMap((phase) => (isPhaseFinished(phase) ? [phase.id] : [])),
+  )
+
+/**
+ * The plan's open named phases, read from the lane branch when it has a copy, which holds the phases the lane wrote
+ * and the ticks it set; a phase finished in either copy is left out, so a lane branch behind the main checkout does not
+ * bring back what another lane finished.
+ */
+const lanePlanOf = (steps: PlanSteps, texts: PlanTexts, text: string, language: PlanLanguage): PlanOutcome => {
+  const phases = parsePlanPhases(text, language)
+  const named = steps.ids.map((id) => ({ id, phase: phases.find((phase) => phase.id === id) }))
+  const missing = named.find(({ phase }) => phase === undefined)
+  if (missing) return { reason: `${steps.path} has no phase ${phaseLabel(missing.id)}` }
+  const rows = parseDependencyTable(text, language) ?? []
+  const finishedInMain = finishedIdsOf(texts.main, language)
+  const open = named.filter(
+    ({ id, phase }) => phase !== undefined && !isPhaseFinished(phase) && !finishedInMain.has(id),
+  )
+  const lanePhases: LanePhase[] = open.map(({ id }) => ({ id, writes: phaseWriteSet(rows, id) }))
+  return { plan: { path: steps.path, phases: lanePhases } }
+}
+
+const plansOf = (
+  steps: readonly PlanSteps[],
+  readers: { main: ReadPlan; lane: ReadPlan },
+  language: PlanLanguage,
+): PlansOutcome => {
+  const plans: LanePlan[] = []
+  for (const step of steps) {
+    const texts = { lane: readers.lane(step.path), main: readers.main(step.path) }
+    const text = texts.lane ?? texts.main
+    if (text === null) return { reason: `cannot read the plan ${step.path}` }
+    const outcome = lanePlanOf(step, texts, text, language)
+    if ('reason' in outcome) return outcome
+    if (outcome.plan.phases.length > 0) plans.push(outcome.plan)
+  }
+  return { plans }
+}
+
+/** The other open lanes whose rows name the phase `id` of the plan at `path`, by name. */
+const otherNamersOf = (others: readonly SprintLane[], directory: string, path: string, id: string): string[] =>
+  others
+    .filter((lane) => planStepsOf(lane, directory).some((steps) => steps.path === path && steps.ids.includes(id)))
+    .map((lane) => lane.name)
+
+const withoutContested = (
+  plans: readonly LanePlan[],
+  lane: string,
+  others: readonly SprintLane[],
+  directory: string,
+): { plans: LanePlan[]; notices: string[] } => {
+  const judged = plans.map((plan) => ({
+    plan,
+    phases: plan.phases.map((phase) => ({ phase, namers: otherNamersOf(others, directory, plan.path, phase.id) })),
+  }))
+  const kept = judged.map(({ plan, phases }) => ({
+    ...plan,
+    phases: phases.filter(({ namers }) => namers.length === 0).map(({ phase }) => phase),
+  }))
+  const notices = judged.flatMap(({ plan, phases }) =>
+    phases
+      .filter(({ namers }) => namers.length > 0)
+      .map(
+        ({ phase, namers }) =>
+          `${plan.path} ${phaseLabel(phase.id)} is named by ${[lane, ...namers].sort().join(' and ')}, so it is in neither prompt; fix the board`,
+      ),
+  )
+  return { plans: kept.filter((plan) => plan.phases.length > 0), notices }
+}
+
+/**
+ * What the lane's prompt is built from: its open row of the board's lanes table (port, plans, phases), each named
+ * phase that is not finished, and the write set of each from its plan's dependency table. A plan is read from the lane
+ * branch (`readLanePlan`) when it has a copy, else from the main checkout (`readPlan`). Refused, with the reason,
+ * for a lane without a row, a closed lane, rows that name no phase, a plan that cannot be read or lacks a phase the
+ * row names, and a lane whose phases are all finished.
+ */
+export const lanePromptInputOf = (
+  request: LanePromptRequest,
+  board: BoardSource,
+  readPlan: ReadPlan,
+  readLanePlan: ReadPlan = () => null,
+): LanePromptResult => {
+  const lanes = parseSprintLanes(board.text, request.language)
+  const sprintLane = lanes.find((candidate) => candidate.name === request.lane)
+  if (!sprintLane) return refused(`no row for lane ${request.lane} in ${board.path}`)
+  if (sprintLane.closed) return refused(`lane ${request.lane} is closed in ${board.path}`)
+  const steps = planStepsOf(sprintLane, board.directory)
+  if (steps.length === 0) return refused(`the row of lane ${request.lane} in ${board.path} links no plan with a phase`)
+  const found = plansOf(steps, { main: readPlan, lane: readLanePlan }, request.language)
+  if ('reason' in found) return refused(found.reason)
+  if (found.plans.length === 0) return refused(`every phase of lane ${request.lane} is finished`)
+  const { lane, handover, language } = request
+  const others = lanes.filter((candidate) => candidate.name !== lane && !candidate.closed)
+  const { plans, notices } = withoutContested(found.plans, lane, others, board.directory)
+  if (plans.length === 0) {
+    return refused(`every open phase of lane ${lane} is also named by another lane: ${notices.join('; ')}`)
+  }
+  const input = { language, lane, plans, port: sprintLane.port, handover }
+  return notices.length === 0 ? { kind: 'prompt', input } : { kind: 'prompt', input, notices }
+}

package/src/lane-prompt/options.ts

@@ -0,0 +1,70 @@
+import { CLI_NAME } from '../version/release'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+
+/** What `jh lane prompt` was asked for; null where an option was left out. */
+export type LanePromptOptions = { lane: string; boardPath: string | null; out: string | null; handover: string | null }
+
+const VALUE_OPTIONS = ['--board', '--out', '--handover'] as const
+
+type ValueOption = (typeof VALUE_OPTIONS)[number]
+
+const SUBCOMMAND = 'prompt'
+
+export const LANE_PROMPT_USAGE = `usage: ${CLI_NAME} lane prompt <lane> [--board <board.md>] [--out <file>] [--handover <file>]
+
+Writes the prompt that starts the lane, from its row in the board and its plan, and prints the file's path.
+What you add below the marker line at the end of the file stays when the prompt is written again.
+A phase that two open rows of the board name is in neither prompt; the command reports it.
+  --board <board.md>   the board to read; without it the board is picked as for ${CLI_NAME} herd
+  --out <file>         where to write the prompt; default .claude/handover/<lane>-prompt.md in the main checkout
+  --handover <file>    a restart after a hand-over: the lane reads this file first and continues with its next step`
+
+const usageError = (message: string): Error => new Error(`${message}\n${LANE_PROMPT_USAGE}`)
+
+const isValueOption = (arg: string): arg is ValueOption => (VALUE_OPTIONS as readonly string[]).includes(arg)
+
+const splitArguments = (args: readonly string[]): { values: Map<ValueOption, string>; words: string[] } => {
+  const values = new Map<ValueOption, string>()
+  const words: string[] = []
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (!arg.startsWith('--')) {
+      words.push(arg)
+      continue
+    }
+    if (!isValueOption(arg)) throw usageError(`unknown option ${arg}`)
+    const value = args[i + 1]
+    if (value === undefined || value.startsWith('--')) throw usageError(`${arg} needs a value`)
+    values.set(arg, value)
+    i += 1
+  }
+  return { values, words }
+}
+
+const laneOf = (words: readonly string[]): string => {
+  const [subcommand, ...lanes] = words
+  if (subcommand !== SUBCOMMAND)
+    throw usageError(subcommand ? `unknown subcommand ${subcommand}` : 'the subcommand is required')
+  if (lanes.length === 0) throw usageError('the lane is required')
+  if (lanes.length > 1) throw usageError(`one lane at most, got ${lanes.join(' ')}`)
+  if (!SAFE_LANE_NAME.test(lanes[0])) throw usageError(`${lanes[0]} is no lane name (letters, digits, . _ -)`)
+  return lanes[0]
+}
+
+/** The hand-over path as the prompt quotes it in backticks: one line without a backtick. */
+const handoverOf = (value: string | undefined): string | null => {
+  if (value === undefined) return null
+  if (/[`\r\n]/.test(value)) throw usageError('--handover needs a path without backticks or line breaks')
+  return value
+}
+
+/** Reads `prompt <lane> [--board …] [--out …] [--handover …]` in any order; throws on a wrong command line. */
+export const parseLanePromptOptions = (args: readonly string[]): LanePromptOptions => {
+  const { values, words } = splitArguments(args)
+  return {
+    lane: laneOf(words),
+    boardPath: values.get('--board') ?? null,
+    out: values.get('--out') ?? null,
+    handover: handoverOf(values.get('--handover')),
+  }
+}