jackherd 1.24.0 → 1.26.0

package/src/plans/closable-records.ts

@@ -1,16 +1,16 @@
 import { join } from 'node:path'
 import { readRecords, writeRecordAtomically } from '../shared/private-records'
 
-/** A record that waits on the user until something sets `closedAt`. */
-export type ClosableRecord = { id: string; closedAt: number | null }
+/** A record that waits on the user until something sets `closedAt`; `closedReason` says who closed it and why. */
+export type ClosableRecord = { id: string; closedAt: number | null; closedReason?: string | null }
 
 export type ClosableRecordLog<T extends ClosableRecord> = {
   /** Every record of the log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
   read: (root: string) => T[]
-  /** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
-  close: (root: string, ids: readonly string[], now: number) => number
-  /** Marks every open record `closedAt` and returns how many it closed. */
-  closeAll: (root: string, now: number) => number
+  /** Marks the named records `closedAt` with `reason` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+  close: (root: string, ids: readonly string[], now: number, reason: string) => number
+  /** Marks every open record `closedAt` with `reason` and returns how many it closed. */
+  closeAll: (root: string, now: number, reason: string) => number
 }
 
 /** The log of `.jackherd/<directoryName>/`: records the `guard` accepts, ordered by `timeOf`. */
@@ -21,14 +21,15 @@ export const closableRecordLog = <T extends ClosableRecord>(
 ): ClosableRecordLog<T> => {
   const directoryOf = (root: string): string => join(root, '.jackherd', directoryName)
   const read = (root: string): T[] => readRecords(directoryOf(root), guard, timeOf)
-  const closeWhere = (root: string, isChosen: (record: T) => boolean, now: number): number => {
+  const closeWhere = (root: string, isChosen: (record: T) => boolean, now: number, reason: string): number => {
     const open = read(root).filter((record) => record.closedAt === null && isChosen(record))
-    for (const record of open) writeRecordAtomically(directoryOf(root), { ...record, closedAt: now })
+    for (const record of open)
+      writeRecordAtomically(directoryOf(root), { ...record, closedAt: now, closedReason: reason })
     return open.length
   }
   return {
     read,
-    close: (root, ids, now) => closeWhere(root, (record) => ids.includes(record.id), now),
-    closeAll: (root, now) => closeWhere(root, () => true, now),
+    close: (root, ids, now, reason) => closeWhere(root, (record) => ids.includes(record.id), now, reason),
+    closeAll: (root, now, reason) => closeWhere(root, () => true, now, reason),
   }
 }

package/src/plans/close-reason.ts

@@ -0,0 +1,19 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+
+/** Who or what closes a record: the user (a click), the coordinator, a newer send of the same file, a removed lane. */
+export const CLOSE_REASON = {
+  user: 'user',
+  coordinator: 'coordinator',
+  newerVersion: 'newer version',
+  laneRemoved: 'lane removed',
+} as const
+
+export type CloseReasonKind = (typeof CLOSE_REASON)[keyof typeof CLOSE_REASON]
+
+const MAX_DETAIL = 200
+
+/** The reason a record carries: the kind, then a free detail on one line without control characters (`coordinator: decided …`). */
+export const closeReasonOf = (kind: CloseReasonKind, detail = ''): string => {
+  const text = ellipsize(terminalSafe(detail.replace(/\s+/g, ' ')).trim(), MAX_DETAIL)
+  return text === '' ? kind : `${kind}: ${text}`
+}

package/src/plans/ensure-panes.ts

@@ -21,7 +21,7 @@ import {
   withAgentPanes,
   withForeground,
 } from './plan-panes'
-import type { PlansSettings } from './settings'
+import { type PlansSettings } from './settings'
 
 const panesWithForeground = (agentPanes: readonly string[]): { panes: PaneState[]; notes: string[] } =>
   withForeground(withAgentPanes(paneListOf(runHerdr(['pane', 'list'])), agentPanes), (pane) =>
@@ -30,7 +30,7 @@ const panesWithForeground = (agentPanes: readonly string[]): { panes: PaneState[
 
 /** The board's lanes that have a worktree, closed ones left out. */
 const lanesOf = (root: string, settings: PlansSettings, boardFile: string) =>
-  parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.planLanguage)
+  parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.boardLanguage)
     .filter((lane) => !lane.closed)
     .map((lane) => ({ name: lane.name, cwd: join(root, settings.worktreeDirectory, lane.name) }))
     .filter((lane) => existsSync(lane.cwd))

package/src/plans/layout-summary.ts

@@ -170,6 +170,10 @@ const checklistFrames = (
   return [...folder, ...frames, ...(open ? deferredFrames(active.phase, context.width) : [])]
 }
 
+/** The phase's purpose sentence, dim, on one row cut at `width`; no row for a phase without one. */
+const purposeFrame = (purpose: string | undefined, width: number): Frame =>
+  purpose ? textFrame([fit(paint.dim(plain(purpose)), width)]) : textFrame([])
+
 /**
  * A phase the lane works on: its head with the bar, no row of its own; under it the checklist of its tasks in the
  * plan's order, the running one marked (`checklistFrames`). `laneRuns` is false for a phase that only waits.
@@ -184,7 +188,10 @@ const activeFrame = (context: SummaryContext, active: ActivePhase, laneRuns = tr
   const running = runningTasks(active, laneRuns)
   return joinFrames([
     textFrame([phaseHead(active, current, context, model)]),
-    indented(joinFrames(checklistFrames(inner, key, active, running)), TASK_INDENT),
+    indented(
+      joinFrames([purposeFrame(active.phase.purpose, inner.width), ...checklistFrames(inner, key, active, running)]),
+      TASK_INDENT,
+    ),
   ])
 }
 

package/src/plans/layout.ts

@@ -182,6 +182,8 @@ export type OverviewView = {
   awaiting?: WaitingItem[]
   /** What is the user's turn, in a block under the title; absent for a herd without a board. */
   yourTurn?: YourTurnBlock
+  /** True when the board has `##` headings and jh reads none of them: an empty "Your turn" then says so instead of that nothing waits. */
+  boardUnread?: true
   /** The sources the watcher runs that are not tickets, in a block of their own under "Your turn". */
   sourceBlock?: SourceBlock
   /** Whole days since the board was groomed (`groomedDaysAgo`), beside the clock; null or absent when unknown. */
@@ -1403,9 +1405,9 @@ const turnMarkPaint = (mark: string): string => {
 }
 
 /** "Your turn" without a point: one line that cannot be opened, its name in the column of the other block names. */
-const emptyTurnLines = (): BlockLines => ({
+const emptyTurnLines = (emptyText: string): BlockLines => ({
   open: false,
-  lines: [`${blockBar()} ${TEXTS.yourTurnHeading} ${paint.dim(`${ITEM_SEPARATOR} ${TEXTS.yourTurnEmpty}`)}`],
+  lines: [`${blockBar()} ${TEXTS.yourTurnHeading} ${paint.dim(`${ITEM_SEPARATOR} ${emptyText}`)}`],
   hit: { rows: [], moreKey: null },
 })
 
@@ -1413,9 +1415,14 @@ const emptyTurnLines = (): BlockLines => ({
  * What is the user's turn, on top of the herd: the head `Your turn · <n>` with its balance, folded until the user opens
  * it; open, the now rows and the planned rows (`turnRows`), told apart by their mark alone.
  */
-const yourTurnLines = ({ turn, now }: YourTurnBlock, state: Selection, width: number): BlockLines => {
+const yourTurnLines = (
+  { turn, now }: YourTurnBlock,
+  state: Selection,
+  width: number,
+  emptyText: string,
+): BlockLines => {
   const count = turn.now.length + turn.planned.length
-  if (count === 0) return emptyTurnLines()
+  if (count === 0) return emptyTurnLines(emptyText)
   const opened = { allNow: state.expanded.has(YOUR_TURN_MORE_KEY), allPlanned: state.expanded.has(YOUR_TURN_LATER_KEY) }
   const clock = new Date(now)
   const block: TopBlock = {
@@ -1702,6 +1709,7 @@ export const renderScreen = (
     watchesTickets,
     awaiting = [],
     yourTurn,
+    boardUnread,
     sourceBlock,
     groomedDays,
     unplaced = [],
@@ -1719,7 +1727,8 @@ export const renderScreen = (
   const notice = watchNotice({ lanes: active, watch, watchesTickets }, badgeTexts)
   const status = [notice ? paint.yellow(notice) : '', groomedCell(groomedDays)].filter(Boolean).join(COLUMN_SEPARATOR)
   const titleLine = spread(`${HEADER_MARK} ${paint.bold(title)}`, status, width)
-  const turn = yourTurn ? yourTurnLines(yourTurn, state, width) : null
+  const emptyTurnText = boardUnread ? TEXTS.boardUnread : TEXTS.yourTurnEmpty
+  const turn = yourTurn ? yourTurnLines(yourTurn, state, width, emptyTurnText) : null
   const nowLines = unplaced.map((task) => nowLine(task, width, taskStyle))
   const above = nowLines.length > 0 ? [titleLine, rule(width), ...nowLines] : [titleLine]
   const listed = sourceLinesOf(sourceBlock, awaiting, state, width)

package/src/plans/live.ts

@@ -10,6 +10,7 @@ import { closeWaiting } from '../waiting/command'
 import { isWatcherRunning } from '../watch/watcher-lock'
 import { ASKING_NOTICE, type AskDependencies, askCoordinator } from './ask-coordinator'
 import type { AskTarget } from './ask-target'
+import { CLOSE_REASON, closeReasonOf } from './close-reason'
 import { errorText } from './error-text'
 import { focusedScreen } from './focus-overlay'
 import { noPullRequests } from './github'
@@ -511,9 +512,9 @@ const applyBlockClick = (live: Live, outcome: BlockClick): void => {
   if ('done' in outcome) {
     const { closed, notice } = closeRow(outcome.done, {
       sprintFile: live.source.sprintFile,
-      language: live.source.settings.planLanguage,
+      language: live.source.settings.boardLanguage,
       now: new Date(),
-      closeRecords: (ids) => closeWaiting(live.source.root, ids, Date.now()),
+      closeRecords: (ids) => closeWaiting(live.source.root, ids, Date.now(), closeReasonOf(CLOSE_REASON.user)),
     })
     if (closed) live.closing = [...live.closing, outcome.done]
     live.notice = notice

package/src/plans/question-records.ts

@@ -12,8 +12,23 @@ export type QuestionRecord = {
   cwd: string
   session: string
   closedAt: number | null
+  /** Who closed the record and why (`closeReasonOf`); absent or null on a record that predates the field or is open. */
+  closedReason?: string | null
+  /** The later dialog that probably answered this question in other words; null or absent when none did. */
+  supersededBy?: SupersededBy | null
+  /** When the session that asked this question ended with it still open (the `SessionEnd` hook); null or absent while it runs. */
+  sessionEndedAt?: number | null
 }
 
+/** A later dialog's question that answered this one, and when. */
+export type SupersededBy = { question: string; answeredAt: number }
+
+const isSupersededBy = (value: unknown): value is SupersededBy =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as SupersededBy).question === 'string' &&
+  typeof (value as SupersededBy).answeredAt === 'number'
+
 /** Whether `value` has the shape of a question record's id: twelve lower-case hex digits. */
 export const isQuestionId = isRecordId
 
@@ -28,13 +43,19 @@ export const isQuestionRecord = (value: unknown): value is QuestionRecord => {
     typeof record.askedAt === 'number' &&
     typeof record.cwd === 'string' &&
     typeof record.session === 'string' &&
-    (record.closedAt === null || typeof record.closedAt === 'number')
+    (record.closedAt === null || typeof record.closedAt === 'number') &&
+    (record.closedReason == null || typeof record.closedReason === 'string') &&
+    (record.supersededBy == null || isSupersededBy(record.supersededBy)) &&
+    (record.sessionEndedAt == null || typeof record.sessionEndedAt === 'number')
   )
 }
 
+/** What a row of "Your turn" shows of a question, safe for the terminal. */
+export const questionTextOf = ({ question }: QuestionRecord): string => terminalSafe(question)
+
 const itemOf = (record: QuestionRecord): WaitingItem => ({
   since: clockText(record.askedAt),
-  item: terminalSafe(record.question),
+  item: questionTextOf(record),
   kind: WAITING_KIND.question,
   id: record.id,
   open: true,

package/src/plans/questions-read.ts

@@ -6,8 +6,8 @@ const log = closableRecordLog('questions', isQuestionRecord, ({ askedAt }) => as
 /** Every record of the question log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
 export const readQuestionRecords = log.read
 
-/** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+/** Marks the named records `closedAt` with a reason and returns how many it closed; one closed already, or unknown, counts for nothing. */
 export const closeQuestionRecords = log.close
 
-/** Marks every open record `closedAt` and returns how many it closed. */
+/** Marks every open record `closedAt` with a reason and returns how many it closed. */
 export const closeAllQuestionRecords = log.closeAll

package/src/plans/sent-files-read.ts

@@ -6,8 +6,8 @@ const log = closableRecordLog('sent', isSentFileRecord, ({ sentAt }) => sentAt)
 /** Every record of the sent-file log in the main checkout, oldest first; nothing when the directory is missing or unreadable. */
 export const readSentRecords = log.read
 
-/** Marks the named records `closedAt` and returns how many it closed; one closed already, or unknown, counts for nothing. */
+/** Marks the named records `closedAt` with a reason and returns how many it closed; one closed already, or unknown, counts for nothing. */
 export const closeSentRecords = log.close
 
-/** Marks every open record `closedAt` and returns how many it closed. */
+/** Marks every open record `closedAt` with a reason and returns how many it closed. */
 export const closeAllSentRecords = log.closeAll

package/src/plans/sent-files.ts

@@ -16,6 +16,8 @@ export type SentFileRecord = {
   session: string
   agentId: string | null
   closedAt: number | null
+  /** Who closed the record and why (`closeReasonOf`); absent or null on a record that predates the field or is open. */
+  closedReason?: string | null
 }
 
 /** A badge for a sent file: a `file:` address and the file's name. */
@@ -55,7 +57,8 @@ export const isSentFileRecord = (value: unknown): value is SentFileRecord => {
     typeof record.cwd === 'string' &&
     typeof record.session === 'string' &&
     (record.agentId === null || typeof record.agentId === 'string') &&
-    (record.closedAt === null || typeof record.closedAt === 'number')
+    (record.closedAt === null || typeof record.closedAt === 'number') &&
+    (record.closedReason == null || typeof record.closedReason === 'string')
   )
 }
 
@@ -69,7 +72,7 @@ export const sentLaneOf = ({ files, cwd }: SentFileRecord, worktreeDirectory: st
     .find((lane) => lane !== null) ?? laneDirectoryOf(cwd, worktreeDirectory)
 
 /** The records without an earlier send of the same first file: an artifact updated each round is one send, the newest. */
-const latestPerFile = (records: readonly SentFileRecord[]): SentFileRecord[] =>
+export const latestPerFile = (records: readonly SentFileRecord[]): SentFileRecord[] =>
   records.filter((record, index) => !records.slice(index + 1).some((later) => later.files[0] === record.files[0]))
 
 /**
@@ -94,12 +97,17 @@ export const sentChipsByLane = (
   return lanes
 }
 
+/** What a row of "Your turn" shows of a send: the first file's label and how many more follow. */
+export const sentTextOf = (record: SentFileRecord): string => {
+  const more = record.files.length > 1 ? ` +${record.files.length - 1}` : ''
+  return `${labelOf(record.files[0], record.caption)}${more}`
+}
+
 const itemOf = (record: SentFileRecord): WaitingItem => {
   const [first] = record.files
-  const more = record.files.length > 1 ? ` +${record.files.length - 1}` : ''
   return {
     since: clockText(record.sentAt),
-    item: `${labelOf(first, record.caption)}${more}`,
+    item: sentTextOf(record),
     kind: WAITING_KIND.file,
     id: record.id,
     open: true,

package/src/plans/settings.ts

@@ -16,6 +16,8 @@ export type PlansSettings = Pick<
   JackherdConfig,
   'planDirectory' | 'board' | 'worktreeDirectory' | 'baseBranch' | 'planLanguage' | 'responseLanguage' | 'skillPrefix'
 > & {
+  /** The language jh writes the board in: the config's `boardLanguage`, or its `planLanguage` when it sets none. */
+  boardLanguage: JackherdConfig['planLanguage']
   adapter: JackherdConfig['terminal']['adapter']
   /** Free gigabytes a new lane needs on the disk (`lanes.minFreeGb`). */
   minFreeGb: number
@@ -65,6 +67,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   worktreeDirectory: config.worktreeDirectory,
   baseBranch: config.baseBranch,
   planLanguage: config.planLanguage,
+  boardLanguage: config.boardLanguage ?? config.planLanguage,
   responseLanguage: config.responseLanguage,
   skillPrefix: config.skillPrefix,
   adapter: config.terminal.adapter,

package/src/plans/snapshot.ts

@@ -15,6 +15,7 @@ import {
   shortTitle,
   sprintTitleOf,
 } from '../plan-format'
+import { firstUnrecognizedSectionLine } from '../plan-format/unrecognized-sections'
 import type { WaitingItem } from '../plan-format/waiting'
 import { dropUnused } from '../shared/stat-cache'
 import type { TaskSignal } from '../task-signals/types'
@@ -140,6 +141,8 @@ export type Snapshot = {
   groomedDays?: number | null
   /** What is the user's turn: `waiting`, the board's open appointments and its next section, one row per topic. */
   yourTurn?: YourTurnBlock
+  /** True when the board has `##` headings and jh reads none of them (`firstUnrecognizedSectionLine`). */
+  boardUnread?: true
   /** The sources of `watch.sources` not marked `ticket`, from the watcher's state, for the block under "Your turn". */
   sourceBlock?: SourceBlock
   /** The tone of each role, from the config, which `renderSnapshot` sets before it draws. */
@@ -535,7 +538,7 @@ const readBoardLanes = async (
   const atBase = textAtBase(base, boardPath)
   const markdown = atBase ?? (await readFallback(boardPath, sprintFile, fallbacks)) ?? ''
   const liveMarkdown = atBase !== null && existsSync(sprintFile) ? await Bun.file(sprintFile).text() : markdown
-  return { markdown, liveMarkdown, lanes: rowsOf(markdown, liveMarkdown, settings.planLanguage).lanes }
+  return { markdown, liveMarkdown, lanes: rowsOf(markdown, liveMarkdown, settings.boardLanguage).lanes }
 }
 
 /** The plans the sprint's plans tables name, read at the base ref, by link; lanes read theirs themselves. */
@@ -547,7 +550,7 @@ const readListedPlans = async (
   fallbacks: Fallbacks,
 ): Promise<Record<string, string>> => {
   const hrefs = new Set(
-    readSprintDocument(markdown, source.settings.planLanguage).planTables.flatMap(({ rows }) =>
+    readSprintDocument(markdown, source.settings.boardLanguage).planTables.flatMap(({ rows }) =>
       rows.flatMap((row) => (row.href ? [row.href] : [])),
     ),
   )
@@ -757,7 +760,7 @@ export const loadSnapshot = async (
   await gate.pass()
   const waitingRecords = readWaitingRecords(root)
   const waiting = withSourcePrefix(
-    waitingItemsOf(liveBoard, settings.planLanguage, waitingRecords, now),
+    waitingItemsOf(liveBoard, settings.boardLanguage, waitingRecords, now),
     sourceSettings.sourceLabels,
   )
   const sentChips = sentChipsByLane(waitingRecords.sent, worktrees, now)
@@ -810,8 +813,9 @@ export const loadSnapshot = async (
     errors: [...laneSet.errors, ...pullRequests.errors, ...(notice ? [notice] : [])],
     watch: reading?.health,
     waiting,
-    groomedDays: groomedDaysAgo(liveBoard, settings.planLanguage, new Date(now)),
-    yourTurn: yourTurnOfBoard(liveBoard, settings.planLanguage, waiting, now),
+    groomedDays: groomedDaysAgo(liveBoard, settings.boardLanguage, new Date(now)),
+    yourTurn: yourTurnOfBoard(liveBoard, settings.boardLanguage, waiting, now),
+    ...(firstUnrecognizedSectionLine(liveBoard) === null ? {} : { boardUnread: true as const }),
     ...(reading?.sources ? { sourceBlock: { sources: withSourceStyle(reading.sources, sourceSettings), now } } : {}),
     tones: settings.tones,
     ...(coordinator ? { coordinator: coordinator.view } : {}),

package/src/plans/sprint-export.ts

@@ -37,7 +37,7 @@ const pageOf = ({ root, sprintFile, settings }: Source, snapshot: Snapshot, envi
     baseRef: baseRefInfo(root, baseRefOf(settings)),
     repoBlobBase: remoteBlobBase(root, settings.baseBranch),
     sprintDirectory: dirname(boardRepoPathOf(root, settings, sprintFile)),
-    language: settings.planLanguage,
+    language: settings.boardLanguage,
     linkKinds: settings.linkKinds,
   })
 

package/src/plans/texts.ts

@@ -84,6 +84,8 @@ export type PlanTexts = {
   hintDonePhases: string
   /** After the head of "Your turn" when nothing waits for the user and nothing is planned. */
   yourTurnEmpty: string
+  /** After the head of "Your turn" when the board has `##` headings and jh reads none of them, so nothing can be said to wait. */
+  boardUnread: string
   notInPlan: string
   /** Before a task an agent reports that no task of the plan names. */
   now: string
@@ -189,6 +191,7 @@ export const TEXTS: PlanTexts = {
   hintNextPhases: 'the next phases',
   hintDonePhases: 'the done phases',
   yourTurnEmpty: 'nothing waits for you',
+  boardUnread: 'board: no section recognised',
   notInPlan: 'not in the plan',
   now: 'now:',
   subagent: 'Subagent:',

package/src/plans/view.ts

@@ -47,6 +47,7 @@ const overviewOf = (snapshot: Snapshot, shimmer: boolean): OverviewView => {
     awaiting: snapshot.waiting,
     groomedDays: snapshot.groomedDays,
     yourTurn: snapshot.yourTurn,
+    boardUnread: snapshot.boardUnread,
     sourceBlock: snapshot.sourceBlock,
     unplaced: snapshot.unplaced,
     coordinator: snapshot.coordinator,

package/src/resume/coordinator-read.ts

@@ -103,7 +103,7 @@ const lanesOf = ({ root, settings }: Place, board: string | null, agents: readon
   discoverLanes({
     worktrees: worktreeNames(join(root, settings.worktreeDirectory)),
     agentNames: (agents ?? []).flatMap((agent) => agent.name ?? []),
-    sprintLanes: board === null ? [] : parseSprintLanes(board, settings.planLanguage).map((lane) => lane.name),
+    sprintLanes: board === null ? [] : parseSprintLanes(board, settings.boardLanguage).map((lane) => lane.name),
   })
 
 /** `jh resume --coordinator`: prints what a cleared coordinator takes up, then the reference on it. Reads only. */
@@ -117,7 +117,7 @@ export const printCoordinatorState = async (boardPath: string | null): Promise<v
   const lines = coordinatorStateLines({
     boardPath: relative(root, boardFile),
     board,
-    language: settings.planLanguage,
+    language: settings.boardLanguage,
     lanes: lanes.map((lane) => laneFactsOf(place, agents, lane)),
     herdrAnswered: agents !== null,
     pullRequests: await readPullRequestsSafely(place, lanes),

package/src/settled/command.ts

@@ -54,7 +54,7 @@ export const run = async (args: string[]): Promise<number> => {
       foundLanesOf(root, settings, () => terminal.listAgents().map((agent) => agent.name)),
     )
     if (board.notice) console.error(board.notice)
-    const context = { now: new Date(), planLanguage: settings.planLanguage }
+    const context = { now: new Date(), boardLanguage: settings.boardLanguage }
     const outcome = settle(request, context, portsFor(checkout, board.file, settings.adapter))
     printOutcome(outcome)
     return outcome.exitCode

package/src/settled/settle.ts

@@ -15,7 +15,7 @@ export type SettlePorts = {
 }
 
 /** When it runs and in which language the board is written; the lane is told in English. */
-export type SettleContext = { now: Date; planLanguage: PlanLanguage }
+export type SettleContext = { now: Date; boardLanguage: PlanLanguage }
 
 export const SETTLE_EXIT = { settled: 0, refused: 1, notSent: 2 } as const
 
@@ -48,10 +48,10 @@ const chatLine = (request: CheckedRequest): string =>
  * not be written, or null; the send has failed either way, so a board error must not turn exit 2 into exit 1.
  */
 const noteFailure = (entry: SettledEntry, error: string, context: SettleContext, ports: SettlePorts): string | null => {
-  const row = settledRow(entry, context.planLanguage)
-  const noted = settledRow(withSendFailure(entry, error, context.planLanguage), context.planLanguage)
+  const row = settledRow(entry, context.boardLanguage)
+  const noted = settledRow(withSendFailure(entry, error, context.boardLanguage), context.boardLanguage)
   try {
-    ports.writeBoard(withReplacedRow(ports.readBoard(), row, noted, context.planLanguage))
+    ports.writeBoard(withReplacedRow(ports.readBoard(), row, noted, context.boardLanguage))
     return null
   } catch (noteError) {
     return errorText(noteError)
@@ -80,7 +80,7 @@ export const settle = (request: SettledRequest, context: SettleContext, ports: S
   }
   const { checked } = result
   const entry = entryOf(checked, context.now, ports.evidenceVersion(checked.evidence.path))
-  ports.writeBoard(withSettledRow(ports.readBoard(), settledRow(entry, context.planLanguage), context.planLanguage))
+  ports.writeBoard(withSettledRow(ports.readBoard(), settledRow(entry, context.boardLanguage), context.boardLanguage))
   const error = ports.send(checked.lane, laneMessageOf(checked))
   if (error === null) return { exitCode: SETTLE_EXIT.settled, stdout: [chatLine(checked)], stderr: [] }
   return notSent(checked, error, noteFailure(entry, error, context, ports))

package/src/sync/render.ts

@@ -5,7 +5,9 @@ import {
   APPROVAL_TEXTS,
   CARD_FIELDS,
   LANGUAGE_NAME,
+  PLAN_LANGUAGE,
   PLAN_VOCABULARY,
+  type PlanLanguage,
   RECOMMENDED_MARK,
   REPORT_FIELDS,
   SELF_MERGE_LABEL,
@@ -35,9 +37,20 @@ const checkFreeList = (patterns: readonly string[]): string =>
 const prefixed = (prefix: string, values: Record<string, string>): [string, string][] =>
   Object.entries(values).map(([key, value]) => [`kit.${prefix}.${key}`, value])
 
-/** Every placeholder a kit file may use, with its value for this project. */
-const placeholderValues = (config: JackherdConfig): Map<string, string> => {
-  const { header, sections, columns, phase, laneClosed, openSubagents } = PLAN_VOCABULARY[config.planLanguage]
+const TEMPLATE_FILE = /(?:^|\/)template-([A-Za-z]+)\.md$/
+
+/**
+ * The language a plan template file is written in, from its name (`template-English.md` is English); undefined for any
+ * other path. Such a file renders with the vocabulary of that language, never with the project's plan language.
+ */
+export const templateLanguageOf = (path: string): PlanLanguage | undefined => {
+  const name = TEMPLATE_FILE.exec(path)?.[1]
+  return Object.values(PLAN_LANGUAGE).find((language) => LANGUAGE_NAME[language] === name)
+}
+
+/** Every placeholder a kit file may use, with its value for this project; the plan words follow `vocabularyLanguage`. */
+const placeholderValues = (config: JackherdConfig, vocabularyLanguage: PlanLanguage): Map<string, string> => {
+  const { header, sections, columns, phase, laneClosed, openSubagents } = PLAN_VOCABULARY[vocabularyLanguage]
   return new Map([
     ['kit.responseLanguage', LANGUAGE_NAME[config.responseLanguage]],
     ['kit.responseAddress', ADDRESS_FORM[config.responseLanguage][config.responseAddress]],
@@ -74,15 +87,17 @@ export const listPlaceholders = (template: string): string[] =>
  * 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
- * file unrendered. `overrides` win over the config: a global kit renders what each repository decides as
+ * file unrendered. `templateLanguage` (`templateLanguageOf` of the file) fills the plan words from that language's
+ * vocabulary instead of the project's plan language. `overrides` win over the config: a global kit renders what each repository decides as
  * `<name>` (`REPOSITORY_TOKENS`).
  */
 export const renderTemplate = (
   template: string,
   config: JackherdConfig,
   overrides: ReadonlyMap<string, string> = new Map(),
+  templateLanguage?: PlanLanguage,
 ): string => {
-  const values = placeholderValues(config)
+  const values = placeholderValues(config, templateLanguage ?? config.planLanguage)
   return template.replace(PLACEHOLDER, (_match, name: string) => {
     const value = overrides.get(name) ?? values.get(name)
     if (value === undefined) throw new Error(`Unknown kit placeholder {{${name}}}`)

package/src/sync/sync-plan.ts

@@ -77,13 +77,17 @@ export const assertOutsideWorktrees = (paths: Iterable<string>, config: Jackherd
   }
 }
 
-export const renderKitFiles = (kit: KitSource, render: (template: string) => string): Map<string, RenderedFile> => {
+/** `render` gets the kit path too, so a `template-<Language>.md` can be filled in its own language. */
+export const renderKitFiles = (
+  kit: KitSource,
+  render: (template: string, path: string) => string,
+): Map<string, RenderedFile> => {
   const rendered = new Map<string, RenderedFile>()
   for (const file of kit.files) {
     const parsed = parseKitPath(file.path)
     if (!parsed.ok) throw new Error(`Kit file ${file.path} ${parsed.reason}`)
     if (rendered.has(parsed.path)) throw new Error(`Kit file ${parsed.path} appears twice`)
-    const content = render(file.template)
+    const content = render(file.template, parsed.path)
     const mode = file.executable ? FILE_MODE.executable : FILE_MODE.regular
     rendered.set(parsed.path, { content, checksum: checksum(content), mode })
   }

package/src/sync/sync.ts

@@ -29,7 +29,7 @@ import {
   removeFileSafely,
   writeFileSafely,
 } from './project-fs'
-import { renderTemplate } from './render'
+import { renderTemplate, templateLanguageOf } from './render'
 import { parseSettings, type Settings } from './settings-hooks'
 import {
   type AcceptRequest,
@@ -184,7 +184,8 @@ const buildPlan = async ({
 }: PlanInput): Promise<SyncPlan> => {
   const { manifest, text: manifestText } = await readManifest(toolDirectory)
   const accept = parseAcceptPaths(acceptPaths)
-  const render = (template: string) => renderTemplate(template, config, overrides)
+  const render = (template: string, path: string) =>
+    renderTemplate(template, config, overrides, templateLanguageOf(path))
   const rendered = renderKitFiles(kit, render)
   assertOutsideWorktrees([...rendered.keys(), ...Object.keys(manifest.files), ...accept.files], config)
   const files = await planFiles(locate, rendered, manifest, accept)