jackherd 1.18.2 → 1.20.0

package/src/plans/texts.ts

@@ -42,19 +42,31 @@ export type PlanTexts = {
   waitingHeading: string
   backlogHeading: string
   /** The balance of the lanes head: how many lanes wait on you, how many idle otherwise. */
-  lanesWaitOnYou: (lanes: number) => string
+  lanesNeedYou: (lanes: number) => string
   lanesIdle: (lanes: number) => string
   /** On a resting lane's line: the labels before a question to you, a row of "Your turn" and its starts-after cell, and the line for a lane without any reason. */
   restWaitsOnYou: string
-  /** After `restWaitsOnYou`: how many questions of its report wait, their text being rows of "Your turn". */
+  /** After `restWaitsOnYou`: how many questions of its report wait, for a note that holds none of their words. */
   restQuestions: (count: number) => string
+  /** After `restWaitsOnYou`: the first open question in its words and `+n questions` for the others. */
+  restAsks: (question: string, more: number) => string
+  /** `+2 phases`: the other phases that run beside the one the folded lane line names. */
+  morePhases: (count: number) => string
   restWaitsOn: string
   restAfter: string
   restNoReason: string
   /** On an open lane's session line: how long its agent has rested. */
   idleFor: (minutes: number) => string
-  /** The row under the tasks a phase shows of its open ones: how many more are open and how many are done. */
-  moreTasks: (open: number, done: number) => string
+  /** The status a folded lane line opens with: it needs the user, it is blocked on something, it runs. */
+  laneNeedsYou: string
+  laneBlocked: string
+  laneRunning: string
+  /** The age of the lane's last activity behind its status word: `3 min`, `2 h`, `<1 min`. */
+  laneAge: (minutes: number) => string
+  /** The row above and the row below a window over a long checklist: how many tasks it leaves out, `… 9 more`. */
+  tasksMore: (count: number) => string
+  /** The row that folds a long checklist listed whole back to its window. */
+  tasksListed: (count: number) => string
   /** The row under an opened task's brief: how many lines its rest takes. */
   moreLines: (count: number) => string
   /** The footer while a row has the focus: what a click or a key does on it. */
@@ -145,16 +157,25 @@ export const TEXTS: PlanTexts = {
   lanesHeading: 'Lanes',
   waitingHeading: 'Waiting',
   backlogHeading: 'Backlog',
-  lanesWaitOnYou: (lanes) => `${lanes} ${lanes === 1 ? 'waits' : 'wait'} on you`,
+  lanesNeedYou: (lanes) => `${lanes} ${lanes === 1 ? 'needs' : 'need'} you`,
   lanesIdle: (lanes) => `${lanes} idle`,
   restWaitsOnYou: 'waits on you',
+  restAsks: (question, more) => `· ${question}${more > 0 ? ` +${more} ${more === 1 ? 'question' : 'questions'}` : ''}`,
+  morePhases: (count) => `+${count} ${count === 1 ? 'phase' : 'phases'}`,
   restQuestions: (count) => `· ${count} ${count === 1 ? 'question' : 'questions'}`,
   restWaitsOn: 'waits on',
   restAfter: 'after',
   restNoReason: 'idle · no reason',
   idleFor: (minutes) => `idle ${minutes < 60 ? `${minutes} min` : `${Math.floor(minutes / 60)} h`}`,
-  moreTasks: (open, done) =>
-    [...(open > 0 ? [`${open} more open`] : []), ...(done > 0 ? [`${done} done`] : [])].join(' · '),
+  laneNeedsYou: 'needs you',
+  laneBlocked: 'blocked',
+  laneRunning: 'running',
+  laneAge: (minutes) => {
+    if (minutes < 1) return '<1 min'
+    return minutes < 60 ? `${minutes} min` : `${Math.floor(minutes / 60)} h`
+  },
+  tasksMore: (count) => `… ${count} more`,
+  tasksListed: (count) => `${count} tasks`,
   moreLines: (count) => `${count} more ${count === 1 ? 'line' : 'lines'}`,
   clickHint: (action) => `${action} · ? help`,
   hintOpens: (name) => `click or → opens ${name}`,
@@ -217,7 +238,10 @@ export const TEXTS: PlanTexts = {
         { mark: STATUS_SYMBOL[AGENT_STATUS.idle], meaning: 'idle' },
         { mark: `(${NO_AGENT_SYMBOL}) ${NO_AGENT_WORD}`, meaning: 'a worktree nobody works in' },
         { mark: UNKNOWN_SYMBOL, meaning: 'state unknown' },
-        { mark: 'waits on you', meaning: '· n questions: open questions of its report' },
+        { mark: 'needs you 3 min', meaning: 'the question to you, age of its last activity' },
+        { mark: 'blocked 3 min', meaning: 'waits on a merge, checks or a go' },
+        { mark: 'running 3 min', meaning: 'the step it is on' },
+        { mark: ':3100 ↗', meaning: "opens the lane's dev server, while it listens" },
         { mark: '🥣 36 %', meaning: 'context used' },
         { mark: '⎇ ↑ ±', meaning: 'branch, commits ahead, uncommitted' },
         { mark: 'n/m ph', meaning: 'phases finished' },
@@ -228,7 +252,8 @@ export const TEXTS: PlanTexts = {
       title: 'Tasks',
       entries: [
         { mark: '● teal', meaning: 'running (reported), its text shimmers' },
-        { mark: '◌ dim', meaning: 'running (guessed)' },
+        { mark: '◌', meaning: 'running (guessed; the first open task of a running phase shimmers)' },
+        { mark: '… n more', meaning: 'tasks the list leaves out; a click lists them all' },
         { mark: `${CHEVRON.closed} ${CHEVRON.open}`, meaning: 'opens / folds' },
         { mark: '☐ ☑', meaning: 'open, done' },
         { mark: '→ P9', meaning: 'moved to another phase' },

package/src/resume/command.ts

@@ -197,17 +197,51 @@ export const resumeAll = async (ports: ResumePorts): Promise<number> => {
   return 0
 }
 
+export const RESUME_USAGE = `Usage: jh resume   (run by the herdr plugin when herdr starts; takes no arguments)
+       jh resume --coordinator [--board <board.md>]   what a coordinator takes up after /clear, from files and herdr
+       jh resume --clear-line [--board <board.md>]    the first input of the chat after a clear, for the script's --send`
+
+/** What the command line asks for; `usage` with whether that was a request for help or a wrong line. */
+export type ResumeRequest =
+  | { kind: 'crash' }
+  | { kind: 'coordinator' | 'clearLine'; board: string | null }
+  | { kind: 'usage'; asked: boolean }
+
+const MODES = { '--coordinator': 'coordinator', '--clear-line': 'clearLine' } as const
+
+const isMode = (arg: string | undefined): arg is keyof typeof MODES => arg !== undefined && Object.hasOwn(MODES, arg)
+
+/** Reads the command line. No arguments is the crash path, which herdr's hook calls and nothing here may change. */
+export const parseResumeArgs = (args: readonly string[]): ResumeRequest => {
+  if (args.length === 0) return { kind: 'crash' }
+  if (args.includes('--help') || args.includes('-h')) return { kind: 'usage', asked: true }
+  const [mode, option, board, ...rest] = args
+  if (!isMode(mode) || rest.length > 0) return { kind: 'usage', asked: false }
+  if (option === undefined) return { kind: MODES[mode], board: null }
+  return option === '--board' && board !== undefined && !board.startsWith('--')
+    ? { kind: MODES[mode], board }
+    : { kind: 'usage', asked: false }
+}
+
 /**
  * `jh resume`: herdr's second `[[startup]]` hook. After a crash of the watcher (its record still marked running, no
  * watcher holding the lock now) sends the coordinator one fixed `/orchestrate … ` line and each lane that worked one
  * fixed text, at most once per record. Every step goes to `~/.jackherd/logs/resume.log`; the exit code is always 0,
- * a hook leaves nothing behind but its log.
+ * a hook leaves nothing behind but its log. With `--coordinator` or `--clear-line` it reads and prints instead, for a
+ * coordinator that clears its context; exit 0, 1 on a wrong command line.
  */
 export const run = async (args: string[]): Promise<number> => {
-  if (args.length > 0) {
-    console.log('Usage: jh resume   (run by the herdr plugin when herdr starts; takes no arguments)')
-    return args.includes('--help') || args.includes('-h') ? 0 : 1
+  const request = parseResumeArgs(args)
+  if (request.kind === 'usage') {
+    console.log(RESUME_USAGE)
+    return request.asked ? 0 : 1
   }
-  const { systemResumePorts } = await import('./ports')
-  return resumeAll(systemResumePorts())
+  if (request.kind === 'crash') {
+    const { systemResumePorts } = await import('./ports')
+    return resumeAll(systemResumePorts())
+  }
+  const { printClearLine, printCoordinatorState } = await import('./coordinator-read')
+  if (request.kind === 'clearLine') printClearLine(request.board)
+  else await printCoordinatorState(request.board)
+  return 0
 }

package/src/resume/coordinator-read.ts

@@ -0,0 +1,136 @@
+import { readFileSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import { installedReferenceHint } from '../lane/skill-hint'
+import { defaultPromptFile } from '../lane-prompt/command'
+import { parseSprintLanes } from '../plan-format'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { boardFor, foundLanesOf } from '../plans/board-pick'
+import { errorText } from '../plans/error-text'
+import { mainCheckout, worktreeNames } from '../plans/git'
+import { discoverLanes } from '../plans/lane-discovery'
+import { type PlansSettings, readSettings, worktreeOf } from '../plans/settings'
+import { recordWaitingItems } from '../plans/waiting-records'
+import { readApprovalRequests } from '../watch/approvals'
+import { readGithub } from '../watch/github-read'
+import { listAgents } from '../watch/herdr'
+import { laneReportPath, readLaneReport, reportMtime } from '../watch/lane-report-file'
+import { branchOf } from '../watch/lane-sources'
+import type { HerdrAgent } from '../watch/lane-watch'
+import { REFERENCE, referenceLine } from '../watch/reference-paths'
+import {
+  type CoordinatorStateInput,
+  coordinatorStateLines,
+  type LaneFacts,
+  laneStatusOf,
+  openPullRequestsOf,
+} from './state'
+import { resumeTexts } from './texts'
+
+type Place = { root: string; settings: PlansSettings; boardFile: string }
+
+/** The agents herdr lists; null when it does not answer. */
+const readAgents = (): HerdrAgent[] | null => {
+  try {
+    return listAgents()
+  } catch {
+    return null
+  }
+}
+
+const placeOf = (boardPath: string | null): Place => {
+  const root = mainCheckout(process.cwd())
+  const settings = readSettings([root])
+  const { file, notice } = boardFor(boardPath, [root], settings, () =>
+    foundLanesOf(root, settings, () => (readAgents() ?? []).flatMap((agent) => agent.name ?? [])),
+  )
+  if (notice) console.error(terminalSafe(notice))
+  return { root, settings, boardFile: file }
+}
+
+const readBoard = (file: string): string | null => {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const laneFactsOf = ({ root, settings }: Place, agents: readonly HerdrAgent[] | null, lane: string): LaneFacts => {
+  const reportPath = laneReportPath(worktreeOf(root, settings, lane), lane)
+  const promptPath = defaultPromptFile(root, lane)
+  return {
+    name: lane,
+    status: laneStatusOf(agents, lane),
+    reportText: readLaneReport(reportPath)?.text ?? null,
+    reportPath,
+    reportMtime: reportMtime(reportPath),
+    promptPath,
+    promptMtime: reportMtime(promptPath),
+  }
+}
+
+/** The open pull request of each lane's branch, as `gh` lists them now; the watcher's own list is gone with its stream. */
+const readPullRequests = async (
+  { root, settings }: Place,
+  lanes: readonly string[],
+): Promise<CoordinatorStateInput['pullRequests']> => {
+  const branches = lanes.flatMap((lane) => {
+    const branch = branchOf(worktreeOf(root, settings, lane))
+    return branch ? [{ lane, branch }] : []
+  })
+  const github = await readGithub(
+    root,
+    undefined,
+    settings.baseBranch,
+    branches.map(({ branch }) => branch),
+  )
+  return github.ok ? openPullRequestsOf(branches, github.pullRequests) : { error: github.error }
+}
+
+/** A failing `gh` read is a line of the list, never the end of it: what the other files hold still has to appear. */
+const readPullRequestsSafely = async (
+  place: Place,
+  lanes: readonly string[],
+): Promise<CoordinatorStateInput['pullRequests']> => {
+  try {
+    return await readPullRequests(place, lanes)
+  } catch (error) {
+    return { error: errorText(error) }
+  }
+}
+
+const lanesOf = ({ root, settings }: Place, board: string | null, agents: readonly HerdrAgent[] | null): string[] =>
+  discoverLanes({
+    worktrees: worktreeNames(join(root, settings.worktreeDirectory)),
+    agentNames: (agents ?? []).flatMap((agent) => agent.name ?? []),
+    sprintLanes: board === null ? [] : parseSprintLanes(board, settings.planLanguage).map((lane) => lane.name),
+  })
+
+/** `jh resume --coordinator`: prints what a cleared coordinator takes up, then the reference on it. Reads only. */
+export const printCoordinatorState = async (boardPath: string | null): Promise<void> => {
+  const place = placeOf(boardPath)
+  const { root, settings, boardFile } = place
+  const now = Date.now()
+  const board = readBoard(boardFile)
+  const agents = readAgents()
+  const lanes = lanesOf(place, board, agents)
+  const lines = coordinatorStateLines({
+    boardPath: relative(root, boardFile),
+    board,
+    language: settings.planLanguage,
+    lanes: lanes.map((lane) => laneFactsOf(place, agents, lane)),
+    herdrAnswered: agents !== null,
+    pullRequests: await readPullRequestsSafely(place, lanes),
+    approvals: readApprovalRequests(root),
+    records: recordWaitingItems(root, now),
+    now,
+  })
+  const hint = installedReferenceHint(root, REFERENCE.coordinatorClear)
+  for (const line of [...lines, ...referenceLine(hint)]) console.log(line)
+}
+
+/** `jh resume --clear-line`: prints the first input of the chat after a clear, for the script's `--send`. */
+export const printClearLine = (boardPath: string | null): void => {
+  const { root, settings, boardFile } = placeOf(boardPath)
+  console.log(resumeTexts(settings.responseLanguage).clearLine(relative(root, boardFile)))
+}

package/src/resume/state.ts

@@ -0,0 +1,163 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { openWaitingItems, type WaitingItem } from '../plan-format/waiting'
+import type { PlanLanguage } from '../vocabulary'
+import { parseAppointmentTime, readAppointmentTable } from '../watch/appointments'
+import { type ApprovalRequestFile, approvalEvents } from '../watch/approvals'
+import { questionsFingerprint } from '../watch/asking-lanes'
+import { questionCountOf } from '../watch/clear-moment'
+import { type HerdrAgent, NO_AGENT } from '../watch/lane-watch'
+import { latestPullRequestOf, PULL_REQUEST_STATE, type WatchedPullRequest } from '../watch/pull-requests'
+
+export type LaneFacts = {
+  name: string
+  status: string
+  reportText: string | null
+  reportPath: string | null
+  reportMtime: number | null
+  promptPath: string
+  promptMtime: number | null
+}
+
+export type LanePullRequest = { lane: string; number: number; checks: string }
+
+/** What a coordinator's chat lost with `/clear` and the files and herdr still hold. */
+export type CoordinatorStateInput = {
+  boardPath: string
+  /** Null when the board cannot be read. */
+  board: string | null
+  language: PlanLanguage
+  lanes: readonly LaneFacts[]
+  /** False when herdr did not answer: only the board's lanes are known then. */
+  herdrAnswered: boolean
+  /** The lanes' open pull requests, or why they could not be read. */
+  pullRequests: readonly LanePullRequest[] | { error: string }
+  approvals: readonly ApprovalRequestFile[]
+  /** The sends and questions of `jh waiting`. */
+  records: readonly WaitingItem[]
+  now: number
+}
+
+const INDENT = '  '
+const STANDING_APPROVAL = /standing approval `?([^\s`]+)`? until (\d{2}\.\d{2}\. \d{2}:\d{2})/g
+/** The status of a lane while herdr does not answer: not knowing is no `no agent`. */
+const STATUS_UNKNOWN = 'unknown'
+
+const entry = (...parts: readonly string[]): string => `${INDENT}${terminalSafe(parts.join(' · '))}`
+
+/** The status herdr reports for a lane; `agents` is null when herdr did not answer. */
+export const laneStatusOf = (agents: readonly HerdrAgent[] | null, lane: string): string => {
+  if (agents === null) return STATUS_UNKNOWN
+  return agents.find((agent) => agent.name === lane)?.agent_status ?? NO_AGENT
+}
+
+/** The open pull request of each lane's branch, from what `gh` listed. */
+export const openPullRequestsOf = (
+  branches: readonly { lane: string; branch: string }[],
+  pullRequests: readonly WatchedPullRequest[],
+): LanePullRequest[] =>
+  branches.flatMap(({ lane, branch }) => {
+    const pullRequest = latestPullRequestOf(pullRequests, branch)
+    return pullRequest?.state === PULL_REQUEST_STATE.open
+      ? [{ lane, number: pullRequest.number, checks: pullRequest.checks }]
+      : []
+  })
+
+/**
+ * `<board>:<line>` of the row whose cell is `text`, else of the first line that holds it; the board alone when no line
+ * does (a cell written with markup).
+ */
+const placeOf = (boardPath: string, board: string, text: string): string => {
+  const lines = board.split('\n')
+  const cell = lines.findIndex((line) => line.includes(`| ${text} |`))
+  const index = cell === -1 ? lines.findIndex((line) => line.includes(text)) : cell
+  return index === -1 ? boardPath : `${boardPath}:${index + 1}`
+}
+
+/** Whether the order in a lane's prompt file has had no report since: the prompt is younger, or there is no report. */
+export const ordersWithoutReport = (promptMtime: number | null, reportMtime: number | null): boolean =>
+  promptMtime !== null && (reportMtime === null || promptMtime > reportMtime)
+
+const laneTail = ({ reportMtime, reportPath, promptMtime, promptPath }: LaneFacts): string => {
+  if (ordersWithoutReport(promptMtime, reportMtime)) return `order without a report: ${promptPath}`
+  return reportPath !== null && reportMtime !== null ? reportPath : 'no report'
+}
+
+const laneHeading = (count: number, herdrAnswered: boolean): string => {
+  if (herdrAnswered) return `lanes ${count}`
+  return count === 0
+    ? 'lanes unknown: herdr did not answer'
+    : `lanes ${count} · herdr did not answer, only the board's lanes`
+}
+
+const laneLines = ({ lanes, herdrAnswered }: CoordinatorStateInput): string[] => [
+  laneHeading(lanes.length, herdrAnswered),
+  ...lanes.map((lane) => {
+    const questions = questionCountOf(questionsFingerprint(lane.reportText))
+    return entry(`${lane.name} ${lane.status}`, `${questions} questions`, laneTail(lane))
+  }),
+]
+
+const pullRequestLines = (pullRequests: CoordinatorStateInput['pullRequests']): string[] =>
+  'error' in pullRequests
+    ? [terminalSafe(`pull requests unknown: ${pullRequests.error}`)]
+    : [
+        `pull requests ${pullRequests.length}`,
+        ...pullRequests.map(({ lane, number, checks }) => entry(`#${number} ${checks}`, lane)),
+      ]
+
+const approvalLines = (approvals: readonly ApprovalRequestFile[], now: number): string[] => {
+  const open = approvalEvents([], approvals, now)
+  return [
+    `approvals ${open.length}`,
+    ...open.map(({ id, lane, tool, summary }) => entry(`${id} ${lane} ${tool}`, summary)),
+  ]
+}
+
+const waitingLines = ({ board, boardPath, language, records }: CoordinatorStateInput): string[] => {
+  const rows = board === null ? [] : openWaitingItems(board, language)
+  return [
+    `waiting on the user ${rows.length + records.length}`,
+    ...rows.map(({ since, item }) => entry(placeOf(boardPath, board ?? '', item), since, item)),
+    ...records.map(({ id, since, item }) => entry(id ?? '-', since, item)),
+  ]
+}
+
+const appointmentLines = ({ board, boardPath, language, now }: CoordinatorStateInput): string[] => {
+  const table =
+    board === null ? { appointments: [], unreadable: [] } : readAppointmentTable(board, language, new Date(now))
+  const open = [...table.appointments.filter((appointment) => appointment.open), ...table.unreadable]
+  if (open.length === 0) return ['appointments 0']
+  return [
+    `appointments ${open.length} · timers survive /clear: compare CronList, create a missing one, delete one without a row`,
+    ...open.map(({ whenText, action }) => entry(placeOf(boardPath, board ?? '', action), whenText, action)),
+  ]
+}
+
+const standingLines = ({ board, boardPath, now }: CoordinatorStateInput): string[] => {
+  const holding = (board ?? '').split('\n').flatMap((line, index) =>
+    [...line.matchAll(STANDING_APPROVAL)].flatMap(([, path = '', end = '']) => {
+      const endsAt = parseAppointmentTime(end, new Date(now))
+      return endsAt !== null && endsAt.getTime() > now ? [entry(`${boardPath}:${index + 1}`, `until ${end}`, path)] : []
+    }),
+  )
+  if (holding.length === 0) return ['standing approvals 0']
+  return [
+    `standing approvals ${holding.length} · a hint only: a cleared chat holds none, ask again before the next merge`,
+    ...holding,
+  ]
+}
+
+/**
+ * What a coordinator takes up after `/clear`, from files and herdr alone: one line per post with its count, one
+ * indented line per entry with its place. A post the board, herdr or `gh` could not answer says so; everywhere else
+ * zero means none, an unreadable approvals or records directory included.
+ */
+export const coordinatorStateLines = (input: CoordinatorStateInput): string[] => [
+  terminalSafe(`board ${input.boardPath}${input.board === null ? ' not readable' : ''}`),
+  ...laneLines(input),
+  ...pullRequestLines(input.pullRequests),
+  ...approvalLines(input.approvals, input.now),
+  ...waitingLines(input),
+  ...appointmentLines(input),
+  ...standingLines(input),
+]

package/src/resume/texts.ts

@@ -4,6 +4,8 @@ import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
 export type ResumeTexts = {
   /** One line, no break: herdr would send a break as an enter and split the command. */
   coordinatorLine: (board: string, interrupted: readonly string[], blocked: readonly string[]) => string
+  /** One line, no break: the hand-over script refuses one. The first input of the chat after a clear. */
+  clearLine: (board: string) => string
   laneText: string
 }
 
@@ -13,12 +15,16 @@ const TEXTS: Record<PlanLanguage, ResumeTexts> = {
   [PLAN_LANGUAGE.de]: {
     coordinatorLine: (board, interrupted, blocked) =>
       `/orchestrate ${board} Neustart nach Absturz: Watcher starten (§ 4), Wecker mit den Terminen abgleichen; fortgesetzt: ${listed(interrupted, 'keine')}; vor dem Absturz blockiert: ${listed(blocked, 'keine')}.`,
+    clearLine: (board) =>
+      `/orchestrate ${board} Aufgeräumt: zuerst jh resume --coordinator --board ${board}, dann Watcher starten (§ 4).`,
     laneText:
       'Der Rechner ist abgestürzt und herdr wurde neu gestartet. Dein letzter Befehl wurde unterbrochen: prüfe, wie weit er kam, und setze ihn fort.',
   },
   [PLAN_LANGUAGE.en]: {
     coordinatorLine: (board, interrupted, blocked) =>
       `/orchestrate ${board} Restart after a crash: start the watcher (§ 4), match the timers against the appointments; resumed: ${listed(interrupted, 'none')}; blocked before the crash: ${listed(blocked, 'none')}.`,
+    clearLine: (board) =>
+      `/orchestrate ${board} Cleared: first jh resume --coordinator --board ${board}, then start the watcher (§ 4).`,
     laneText:
       'The computer crashed and herdr was restarted. Your last command was interrupted: check how far it got, and carry on with it.',
   },

package/src/sync/render.ts

@@ -3,9 +3,11 @@ import { repositoryPlaceholderValues } from '../config/repository-values'
 import {
   ADDRESS_FORM,
   APPROVAL_TEXTS,
+  CARD_FIELDS,
   LANGUAGE_NAME,
   PLAN_VOCABULARY,
   RECOMMENDED_MARK,
+  REPORT_FIELDS,
   SELF_MERGE_LABEL,
   STANDING_APPROVAL_TEXTS,
 } from '../vocabulary'
@@ -53,6 +55,8 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ...prefixed('guard.standingApproval', STANDING_APPROVAL_TEXTS[config.responseLanguage]),
     ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
     ['kit.question.recommended', RECOMMENDED_MARK[config.responseLanguage]],
+    ...prefixed('card', CARD_FIELDS[config.responseLanguage]),
+    ...prefixed('report', REPORT_FIELDS[config.responseLanguage]),
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
     ['kit.merge.openAsDraft', config.merge.openAsDraft ? 'on' : 'off'],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
@@ -66,7 +70,7 @@ export const listPlaceholders = (template: string): string[] =>
 /**
  * Fills the kit placeholders from the project config: `{{kit.model.<role>}}`,
  * `{{kit.command.<test|typecheck|lint|format|install|dev>}}`, `{{kit.lanes.<copyCommand|lockFile|verifyInstall>}}`, `{{kit.word.<laneClosed|openSubagents>}}`,
- * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.question.recommended}}`, `{{kit.merge.<withoutChecks|openAsDraft>}}`, `{{kit.heading.<key>}}` from the plan
+ * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.question.recommended}}`, `{{kit.card.<topic|consequences|ifUndecided|readMore>}}`, `{{kit.report.<goal|phase|result|needsYou|next>}}`,`{{kit.merge.<withoutChecks|openAsDraft>}}`, `{{kit.heading.<key>}}` from the plan
  * vocabulary, the two languages, `{{kit.responseAddress}}`, the plan and worktree directory and the base branch. A
  * command or lock file the config leaves unset renders as `unsetValueText`, never as a guessed default. Other
  * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project

package/src/vocabulary/index.ts

@@ -58,6 +58,30 @@ export const RECOMMENDED_MARK: Record<PlanLanguage, string> = {
   [PLAN_LANGUAGE.de]: '(Empfohlen)',
 }
 
+/**
+ * The four fields of the decision card that stands in every dialog, in the question and the option previews: what it
+ * is about, what each option leads to, what happens without a decision, and where to read on. The plain question
+ * hook sends a dialog back that lacks one at the start of a line, so they are fixed per language and not a config
+ * value.
+ */
+export const CARD_FIELDS: Record<
+  PlanLanguage,
+  { topic: string; consequences: string; ifUndecided: string; readMore: string }
+> = {
+  [PLAN_LANGUAGE.en]: {
+    topic: 'What this is about',
+    consequences: 'What each option leads to',
+    ifUndecided: 'If you do nothing',
+    readMore: 'Details',
+  },
+  [PLAN_LANGUAGE.de]: {
+    topic: 'Worum es geht',
+    consequences: 'Folgen je Option',
+    ifUndecided: 'Wenn du nichts entscheidest',
+    readMore: 'Nachlesen',
+  },
+}
+
 /**
  * The words a lane prompt opens with, followed by the lane's name. The ask hint hook and the project's lane exception
  * recognise a lane by them, so they are fixed per language and not a config value.
@@ -173,6 +197,37 @@ export type StatusWord = {
   anywhere: readonly string[]
 }
 
+/**
+ * The five fields of a lane's report, in this order, each opening a line of the report: the goal, the phase (written
+ * `<phase> x/y`), the result with its numbers, what the lane needs from the user, the next step. They are fixed per
+ * language, like the card, so the report template reads them as `{{kit.report.<key>}}` and the watcher recognises them
+ * in either language; the `## Questions` heading stays English in both.
+ */
+export const REPORT_FIELDS: Record<
+  PlanLanguage,
+  { goal: string; phase: string; result: string; needsYou: string; next: string }
+> = {
+  [PLAN_LANGUAGE.en]: { goal: 'Goal', phase: 'Phase', result: 'Result', needsYou: 'Needs you', next: 'Next' },
+  [PLAN_LANGUAGE.de]: {
+    goal: 'Ziel',
+    phase: 'Phase',
+    result: 'Ergebnis',
+    needsYou: 'Braucht dich',
+    next: 'Nächster Schritt',
+  },
+}
+
+/** The five lines of a plan's head, in the order a plan writes them. */
+export const HEAD_LINE = {
+  changes: 'changes',
+  status: 'status',
+  decisions: 'decisions',
+  tryNow: 'tryNow',
+  next: 'next',
+} as const
+
+export type HeadLine = (typeof HEAD_LINE)[keyof typeof HEAD_LINE]
+
 export type PlanVocabulary = {
   header: { date: string; status: string; scope: string }
   sections: {
@@ -185,7 +240,10 @@ export type PlanVocabulary = {
     goal: string
     history: string
     plans: string
+    forYou: string
   }
+  /** The five labels of the `forYou` section, fixed per language: `- **<label>:** <text>`. */
+  head: Record<HeadLine, string>
   columns: { dependsOn: string; writes: string; serialMarker: string }
   phase: string
   /** Opens the line by which a phase says it has no review gate on purpose: `**Kein Review-Gate:** <reason>`. */
@@ -226,6 +284,14 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
       goal: 'Sprintziel',
       history: 'Verlauf',
       plans: 'Pläne',
+      forYou: 'Für dich',
+    },
+    head: {
+      changes: 'Was sich für dich ändert',
+      status: 'Stand',
+      decisions: 'Deine offenen Entscheidungen',
+      tryNow: 'Schon ausprobieren',
+      next: 'Nächster Schritt',
     },
     columns: { dependsOn: 'Hängt ab von', writes: 'Schreibt', serialMarker: 'Seriell-Marker' },
     phase: 'Phase',
@@ -261,6 +327,14 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
       goal: 'Sprint goal',
       history: 'History',
       plans: 'Plans',
+      forYou: 'For you',
+    },
+    head: {
+      changes: 'What changes for you',
+      status: 'Status',
+      decisions: 'Your open decisions',
+      tryNow: 'Try it now',
+      next: 'Next step',
     },
     columns: { dependsOn: 'Depends on', writes: 'Writes', serialMarker: 'Serial marker' },
     phase: 'Phase',