jackherd 1.8.1 → 1.10.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/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,87 @@
+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 { 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,
+  }
+}
+
+const writePrompt = (out: string, prompt: string): void => {
+  mkdirSync(dirname(out), { recursive: true })
+  writeFileSync(out, prompt)
+}
+
+/**
+ * `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>)"`. `--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
+    }
+    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,116 @@
+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
+
+export type LanePromptResult = { kind: 'prompt'; input: LanePromptInput } | { 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 }
+}
+
+/**
+ * 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 sprintLane = parseSprintLanes(board.text, request.language).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
+  return { kind: 'prompt', input: { language, lane, plans: found.plans, port: sprintLane.port, handover } }
+}

package/src/lane-prompt/options.ts

@@ -0,0 +1,68 @@
+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.
+  --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')),
+  }
+}

package/src/lane-prompt/texts.ts

@@ -0,0 +1,101 @@
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+
+/**
+ * The sentences of a lane prompt in one language, after `/orchestrate` § 1. The opening words and the column name of
+ * a write set come from the vocabulary; the report file keeps its `## Questions` heading in every language, since the
+ * watcher finds the section by that word.
+ */
+export type LanePromptTexts = {
+  answersTo: string
+  phasesIntro: string
+  noWrites: string
+  wholeRepository: string
+  editInside: string
+  writeTools: string
+  port: (port: number) => string
+  noPort: string
+  blocking: string
+  mustNot: string
+  commit: string
+  report: (reportPath: string) => string
+  textBlock: string
+  secret: string
+  askRule: string
+  approvalGate: string
+  helper: (helperName: string) => string
+  helperPurpose: string
+  start: string
+  restart: (handoverPath: string) => string
+}
+
+export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
+  [PLAN_LANGUAGE.en]: {
+    answersTo: 'You answer to the coordinator, not to the user.',
+    phasesIntro: 'Your plan and phases:',
+    noWrites: 'no Writes set in the plan',
+    wholeRepository: 'the whole repository',
+    editInside:
+      'Nothing outside the Writes set of your phases is edited, except the task lines of your phases in the plan: tick a finished one right away, by an Edit of exactly that line.',
+    writeTools:
+      'Write code and tests with Write and Edit, never through a here-document or a script in Bash: such a call shows the reviewer no diff, and an unquoted or unreadable one can stop at a guard.',
+    port: (port) =>
+      `Port ${port}: the coordinator runs your dev server in its own pane; look at your visible changes there (\`/implement\` Step 4b) and never start a server in your own shell.`,
+    noPort:
+      'No port: this lane has no dev server of its own. Never start a server in your own shell; ask the coordinator when you need one.',
+    blocking:
+      'Mark every question of yours `blocking` or `not blocking`. A blocking one stops the step it decides; for a not blocking one leave a `TODO` at its spot and work on, building neither your recommendation nor another option as decided.',
+    mustNot:
+      'Without the user’s approval you push no database migration and write nothing against a shared environment (stage, production); you never run `git reset` or `git stash` on shared refs.',
+    commit: 'Ask before every commit (`/pre-commit`); no push, PR or merge without approval.',
+    report: (reportPath) =>
+      `The report at the end of each step goes to \`${reportPath}\` in the worktree, in the short form: one line of diff stat, one line per check with its numbers, open points, questions as a text block under the heading \`## Questions\` (whatever the report’s language: the watcher finds the section by that word and shows it whole); everything else is in the plan, by reference.`,
+    textBlock:
+      'Every question to the coordinator is a text block at the end of your turn, never a dialog (`AskUserQuestion`), also where a skill or a project rule asks for one, the commit confirmation of `/pre-commit` included: the question with the situation, the problem and what each option leads to, in everyday words (the user may not know your terms), the options, your recommendation, the evidence at `file:line`.',
+    secret:
+      'A value only the user knows (a secret, password, token or one-time code) never passes through you, your arguments, your output or a file you write: ask the coordinator for the step as a question.',
+    askRule:
+      'A tool that asks for approval on every call (an ask rule, such as a database query tool or a project CLI) gets as few calls as possible: bundle the steps into one call (one script, one query) instead of one call per step.',
+    approvalGate:
+      'A call that would open a permission dialog waits for the coordinator: the approval gate holds it and the coordinator asks the user. Denied with “approval pending”, retry the same call once the coordinator says it is approved; denied by the user, do not retry it.',
+    helper: (helperName) =>
+      `A helper agent in a pane of your own (a measurement, a probe session) is announced to the coordinator before it starts, as a question at the end of your turn: what it does, how long, and which temporary settings it uses. Once approved, name it \`${helperName}\` (\`herdr agent rename\`), so the watcher watches it with your lane, and close it yourself when it is done: \`/exit\`, then \`herdr pane close\`, and remove every temporary file it needed.`,
+    helperPurpose: '<purpose>',
+    start: 'Start: run `/implement` for your phases, in the order above.',
+    restart: (handoverPath) => `Start: read \`${handoverPath}\` first and continue with the next step it names.`,
+  },
+  [PLAN_LANGUAGE.de]: {
+    answersTo: 'Du antwortest dem Koordinator, nicht dem User.',
+    phasesIntro: 'Dein Plan und deine Phasen:',
+    noWrites: 'keine Schreibt-Menge im Plan',
+    wholeRepository: 'das ganze Repository',
+    editInside:
+      'Außerhalb der Schreibt-Menge deiner Phasen änderst du nichts, außer den Aufgabenzeilen deiner Phasen im Plan: eine erledigte hakst du sofort ab, per Edit auf genau diese Zeile.',
+    writeTools:
+      'Code und Tests schreibst du mit Write und Edit, nie per Heredoc oder Skript in Bash: ein solcher Aufruf zeigt dem Prüfer keinen Diff, und ein ungequoteter oder unlesbarer kann an einem Wächter hängen bleiben.',
+    port: (port) =>
+      `Port ${port}: Der Koordinator betreibt deinen Dev-Server in seinem eigenen Pane; deine sichtbaren Änderungen siehst du dort an (\`/implement\` Step 4b) und startest nie einen Server in deiner eigenen Shell.`,
+    noPort:
+      'Kein Port: Diese Spur hat keinen eigenen Dev-Server. Starte nie einen Server in deiner eigenen Shell; brauchst du einen, frag den Koordinator.',
+    blocking:
+      'Markiere jede deiner Fragen mit `blocking` oder `not blocking`. Eine blockierende hält den Schritt an, den sie entscheidet; bei einer nicht blockierenden lässt du an ihrer Stelle ein `TODO` und arbeitest weiter, ohne deine Empfehlung oder eine andere Option als entschieden zu bauen.',
+    mustNot:
+      'Ohne Freigabe des Users pushst du keine Datenbank-Migration und schreibst nichts gegen eine geteilte Umgebung (Stage, Produktion); `git reset` und `git stash` auf geteilten Refs führst du nie aus.',
+    commit: 'Vor jedem Commit fragst du (`/pre-commit`); kein Push, kein PR und kein Merge ohne Freigabe.',
+    report: (reportPath) =>
+      `Den Bericht am Ende jedes Schritts schreibst du nach \`${reportPath}\` im Worktree, in der Kurzform: eine Zeile Diff-Stat, eine Zeile je Check mit seinen Zahlen, offene Punkte, Fragen als Textblock unter der Überschrift \`## Questions\` (in jeder Berichtssprache: der Watcher findet den Abschnitt an diesem Wort und zeigt ihn ganz); alles andere steht im Plan, per Verweis.`,
+    textBlock:
+      'Jede Frage an den Koordinator ist ein Textblock am Ende deines Turns, nie ein Dialog (`AskUserQuestion`), auch wo ein Skill oder eine Projektregel einen verlangt, die Commit-Bestätigung von `/pre-commit` eingeschlossen: die Frage mit der Lage, dem Problem und wohin jede Option führt, in Alltagsworten (der User kennt deine Begriffe vielleicht nicht), die Optionen, deine Empfehlung, der Beleg als `datei:zeile`.',
+    secret:
+      'Ein Wert, den nur der User kennt (ein Geheimnis, Passwort, Token oder Einmalcode), läuft nie über dich, deine Argumente, deine Ausgabe oder eine Datei, die du schreibst: bitte den Koordinator mit einer Frage um diesen Schritt.',
+    askRule:
+      'Ein Werkzeug, das bei jedem Aufruf um Freigabe fragt (eine Ask-Regel, etwa ein Datenbank-Abfragewerkzeug oder eine Projekt-CLI), bekommt so wenige Aufrufe wie möglich: bündle die Schritte in einen Aufruf (ein Skript, eine Abfrage) statt eines Aufrufs je Schritt.',
+    approvalGate:
+      'Ein Aufruf, der einen Erlaubnis-Dialog öffnen würde, wartet auf den Koordinator: Das Approval-Gate hält ihn an, und der Koordinator fragt den User. Abgelehnt mit „approval pending“: denselben Aufruf wiederholen, sobald der Koordinator ihn als freigegeben meldet; vom User abgelehnt: nicht wiederholen.',
+    helper: (helperName) =>
+      `Einen Helfer-Agenten in einem eigenen Pane (eine Messung, eine Probesitzung) meldest du dem Koordinator an, bevor er startet, als Frage am Ende deines Turns: was er tut, wie lange, und welche temporären Einstellungen er nutzt. Nach der Freigabe benennst du ihn \`${helperName}\` (\`herdr agent rename\`), damit der Watcher ihn mit deiner Spur beobachtet, und schließt ihn selbst, wenn er fertig ist: \`/exit\`, dann \`herdr pane close\`, und entferne jede temporäre Datei, die er brauchte.`,
+    helperPurpose: '<zweck>',
+    start: 'Start: Führe `/implement` für deine Phasen aus, in der Reihenfolge oben.',
+    restart: (handoverPath) =>
+      `Start: Lies zuerst \`${handoverPath}\` und mach mit dem nächsten Schritt weiter, den sie nennt.`,
+  },
+}

package/src/plan-format/clock.ts

@@ -0,0 +1,12 @@
+export const MS_PER_MINUTE = 60_000
+
+export const DAY_MS = 86_400_000
+
+/** A day, month, hour or minute with a leading zero: `7` → `07`. */
+export const twoDigits = (value: number): string => String(value).padStart(2, '0')
+
+/** A time as the for-you rows show it: `DD.MM. HH:MM`. */
+export const clockText = (at: number): string => {
+  const date = new Date(at)
+  return `${twoDigits(date.getDate())}.${twoDigits(date.getMonth() + 1)}. ${twoDigits(date.getHours())}:${twoDigits(date.getMinutes())}`
+}