jackherd 1.23.3 → 1.25.0

package/src/backend/step.ts

@@ -0,0 +1,93 @@
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { BACKEND_PANE, type BackendPane, type BackendState } from './state'
+
+/** At most this many automatic starts within `BACKEND_START_WINDOW_MS`. */
+export const BACKEND_START_LIMIT = 3
+export const BACKEND_START_WINDOW_MS = 10 * MS_PER_MINUTE
+
+export const BACKEND_STEP_ACTION = { none: 'none', start: 'start', split: 'split' } as const
+
+export type BackendStepAction = (typeof BACKEND_STEP_ACTION)[keyof typeof BACKEND_STEP_ACTION]
+
+export const BACKEND_GIVE_UP_LINE = `backend: gave up after ${BACKEND_START_LIMIT} starts in ${BACKEND_START_WINDOW_MS / MS_PER_MINUTE} minutes; jh backend restart`
+export const BACKEND_DIFFERS_LINE = 'backend: running command differs from lanes.backend; jh backend restart'
+
+/** What the watcher found: the pane, where it sits, the busy service ports of the current list, the wanted command. */
+export type BackendObservation = {
+  pane: BackendPane
+  /** The pane's id, or the tab label when the pane is still to be created; named in the start line. */
+  place: string
+  busyPorts: readonly number[]
+  /** The command line `backendCommandOf` gives; null when every service is released. */
+  desired: string | null
+}
+
+export type BackendStep = { action: BackendStepAction; state: BackendState; line: string | null }
+
+const stay = (state: BackendState): BackendStep => ({ action: BACKEND_STEP_ACTION.none, state, line: null })
+
+/** Reports `line` only when it differs from the one already standing. */
+export const noticed = (state: BackendState, line: string): BackendStep => ({
+  action: BACKEND_STEP_ACTION.none,
+  state: { ...state, notice: line },
+  line: state.notice === line ? null : line,
+})
+
+const settled = (state: BackendState): BackendState => (state.notice === null ? state : { ...state, notice: null })
+
+const runningStep = (state: BackendState, desired: string | null): BackendStep =>
+  desired === null || state.command === desired ? stay(settled(state)) : noticed(state, BACKEND_DIFFERS_LINE)
+
+const portLine = (port: number): string => `backend: port ${port} in use, not started`
+
+const started = (
+  state: BackendState,
+  observation: BackendObservation,
+  desired: string,
+  starts: number[],
+): BackendStep => ({
+  action: observation.pane === BACKEND_PANE.missing ? BACKEND_STEP_ACTION.split : BACKEND_STEP_ACTION.start,
+  state: { ...state, command: desired, starts, notice: null },
+  line: `backend: started in ${observation.place}`,
+})
+
+const startStep = (state: BackendState, observation: BackendObservation, desired: string, now: number): BackendStep => {
+  const recent = state.starts.filter((start) => now - start < BACKEND_START_WINDOW_MS)
+  if (recent.length >= BACKEND_START_LIMIT)
+    return noticed({ ...state, starts: recent, gaveUp: true }, BACKEND_GIVE_UP_LINE)
+  return started(state, observation, desired, [...recent, now])
+}
+
+const refusedByHand = (state: BackendState, line: string): BackendStep => ({
+  action: BACKEND_STEP_ACTION.none,
+  state,
+  line,
+})
+
+/**
+ * The start `jh backend` makes after it stopped the pane (`restart`, `release`, `return`): no start limit, no start
+ * counted, every refusal said each time, since a person asked for it. A busy port prevents it as at every check.
+ */
+export const startedByHand = (state: BackendState, observation: BackendObservation): BackendStep => {
+  const { pane, desired, busyPorts, place } = observation
+  if (pane === BACKEND_PANE.running) return refusedByHand(state, `backend: still running in ${place}, not started`)
+  if (desired === null)
+    return refusedByHand({ ...state, command: null }, 'backend: every service is handed to a lane, nothing started')
+  const [busy] = busyPorts
+  if (busy !== undefined) return refusedByHand(state, portLine(busy))
+  return started(state, observation, desired, state.starts)
+}
+
+/**
+ * The decision of one check: what to do with the pane, the state to keep and the line to report, if any. A standing
+ * condition (a busy port, a differing command, the given-up state) is reported once, not at every check. Nothing here
+ * stops a process or frees a port: a busy port only prevents the start.
+ */
+export const backendStep = (state: BackendState, observation: BackendObservation, now: number): BackendStep => {
+  const { pane, desired, busyPorts } = observation
+  if (pane === BACKEND_PANE.running) return runningStep(state, desired)
+  if (desired === null || state.gaveUp) return stay(state)
+  const [busy] = busyPorts
+  if (busy !== undefined) return noticed(state, portLine(busy))
+  return startStep(state, observation, desired, now)
+}

package/src/backend/system.ts

@@ -0,0 +1,150 @@
+import { realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import { worktreeNames } from '../plans/git'
+import { paneListOf } from '../plans/plan-panes'
+import { listeningPorts } from '../plans/port-listening'
+import { readPrivateText } from '../shared/private-location'
+import { type HerdrRunner, renameArguments, runHerdr } from '../terminal/herdr'
+import { ensureWatcherDirectory } from '../watch/watcher-lock'
+import type { BackendSystem } from './control'
+import {
+  type BackendSight,
+  backendSightOf,
+  createdPaneOf,
+  mainWorkspaceOf,
+  type PaneProcesses,
+  paneProcessesOf,
+  stopTargetOf,
+  tabIdsOf,
+} from './herdr'
+import { processCwdOf } from './process-cwd'
+import type { BackendConfig } from './schema'
+import { BACKEND_PANE, parseBackendState } from './state'
+
+/** The backend's files in the watcher's directory of the repository, beside `watch-state.json`. */
+export const BACKEND_FILES = { state: 'backend.json', lock: 'backend.lock' } as const
+
+export type BackendFiles = Record<keyof typeof BACKEND_FILES, string>
+
+type Context = { root: string; label: string; run: HerdrRunner }
+
+type StopResult = { ok: true } | { ok: false; line: string }
+
+/** How long `jh backend` waits for a stopped backend to free its pane and ports. */
+const STOP_WAIT_MS = 30_000
+const STOP_POLL_MS = 500
+
+/** The paths of the backend's state and lock for the main checkout `root`; creates the private directory. */
+export const backendFilesOf = (root: string): BackendFiles => {
+  const directory = ensureWatcherDirectory(root)
+  return { state: join(directory, BACKEND_FILES.state), lock: join(directory, BACKEND_FILES.lock) }
+}
+
+const workspaceOf = ({ root, run }: Context): string => mainWorkspaceOf(run(['workspace', 'list']), root)
+
+const processesOf = (context: Context, pane: string): PaneProcesses =>
+  paneProcessesOf(context.run(['pane', 'process-info', '--pane', pane]))
+
+const lookWith = (context: Context): BackendSight =>
+  backendSightOf({
+    panes: paneListOf(context.run(['pane', 'list'])),
+    tabs: tabIdsOf(context.run(['tab', 'list', '--workspace', workspaceOf(context)])),
+    label: context.label,
+    root: context.root,
+    foregroundOf: (pane) => processesOf(context, pane).processes.map(({ argv }) => argv),
+  })
+
+const busyPortsOf = async (ports: readonly number[]): Promise<number[]> => {
+  const listening = await listeningPorts(ports)
+  return ports.filter((port) => listening.has(port))
+}
+
+/** A new tab in the main checkout's workspace, without focus, working in `root`; its pane labelled and running `command`. */
+const createWith = (context: Context, command: string): string => {
+  const { root, label, run } = context
+  const created = run([
+    'tab',
+    'create',
+    '--workspace',
+    workspaceOf(context),
+    '--cwd',
+    root,
+    '--label',
+    label,
+    '--no-focus',
+  ])
+  const pane = createdPaneOf(created)
+  run(renameArguments(pane, label))
+  run(['pane', 'run', pane, command])
+  return pane
+}
+
+const isStopped = async (context: Context, ports: readonly number[]): Promise<boolean> => {
+  const sight = lookWith(context)
+  return sight.kind === 'found' && sight.pane !== BACKEND_PANE.running && (await busyPortsOf(ports)).length === 0
+}
+
+/** SIGTERM to `pid`; a process that ended since it was read is what the stop wanted, any other failure propagates. */
+const terminate = (pid: number) => {
+  try {
+    process.kill(pid, 'SIGTERM')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error
+  }
+}
+
+const waitUntilStopped = async (context: Context, pane: string, pid: number, ports: readonly number[]) => {
+  const deadline = Date.now() + STOP_WAIT_MS
+  while (Date.now() < deadline) {
+    if (await isStopped(context, ports)) return { ok: true } as const
+    await Bun.sleep(STOP_POLL_MS)
+  }
+  return {
+    ok: false,
+    line: `backend: still running ${STOP_WAIT_MS / 1000} s after SIGTERM to ${pid}; stop it in pane ${pane}`,
+  } as const
+}
+
+/**
+ * SIGTERM to the leader of the pane's foreground group once `stopTargetOf` accepted it (never the shell, only a
+ * process in the main checkout), then a wait until the pane is a shell again and the ports are free. The pane is read
+ * a second time after the directory check, and the signal goes out only when the same group still leads it, so a
+ * process id reused in between is not hit. Never a port kill.
+ */
+const stopWith = async (context: Context, pane: string, ports: readonly number[]): Promise<StopResult> => {
+  const target = stopTargetOf(processesOf(context, pane), context.root, (pid) => processCwdOf(pid), pane)
+  if (!target.ok) return target
+  if (processesOf(context, pane).groupId !== target.pid)
+    return { ok: false, line: `backend: the process in pane ${pane} changed while it was checked; try again` }
+  terminate(target.pid)
+  return waitUntilStopped(context, pane, target.pid, ports)
+}
+
+/**
+ * The backend's calls for the main checkout `root`: herdr through `run`, the state in `files`, the ports probed on
+ * this machine, the lanes' worktrees under `worktreeDirectory`.
+ */
+export const backendSystemOf = (input: {
+  root: string
+  worktreeDirectory: string
+  backend: BackendConfig
+  files: BackendFiles
+  run?: HerdrRunner
+}): BackendSystem => {
+  const root = realpathSync(input.root)
+  const context: Context = { root, label: input.backend.label, run: input.run ?? runHerdr }
+  return {
+    readState: () => parseBackendState(readPrivateText(input.files.state)),
+    writeState: (state) => writePrivateFile(input.files.state, `${JSON.stringify(state)}\n`),
+    look: () => lookWith(context),
+    busyPorts: busyPortsOf,
+    create: (command) => createWith(context, command),
+    run: (pane, command) => {
+      context.run(['pane', 'run', pane, command])
+    },
+    stop: (pane, ports) => stopWith(context, pane, ports),
+    worktrees: () => worktreeNames(join(root, input.worktreeDirectory)),
+    now: Date.now,
+  }
+}

package/src/backend/watch.ts

@@ -0,0 +1,75 @@
+import { readConfig } from '../config/read-config'
+import type { JackherdConfig } from '../config/schema'
+import { errorText } from '../plans/error-text'
+import { checkBackend } from './control'
+import { withBackendLock } from './lock'
+import type { BackendConfig } from './schema'
+import { backendFilesOf, backendSystemOf } from './system'
+
+/** The watcher's memory of the backend between polls: the last check and whether a failure was already said. */
+export type BackendWatch = { checkedAt: number | null; failureReported: boolean }
+
+export type BackendWatchEffects = {
+  /** One check; null when `jh backend` holds the lock, so the next check tries again. */
+  check: () => Promise<string[] | null>
+  log: (line: string) => void
+  /** Put behind every line: where the coordinator reads what to do. */
+  hint: string
+}
+
+/** The backend and the lanes' worktree directory, both from the main checkout's config. */
+export type MainCheckoutBackend = { backend: BackendConfig; worktreeDirectory: string }
+
+/** The watcher checks the backend pane at its start and then once a minute, not at every poll. */
+export const BACKEND_CHECK_MS = 60_000
+
+export const INITIAL_BACKEND_WATCH: BackendWatch = { checkedAt: null, failureReported: false }
+
+export const backendCheckDue = ({ checkedAt }: BackendWatch, now: number): boolean =>
+  checkedAt === null || now - checkedAt >= BACKEND_CHECK_MS
+
+/**
+ * Checks the backend when one is due and prints its lines. A failure never ends the watch; it is printed once until
+ * a check works again, as `keepPlanViews` does for the herd panes.
+ */
+export const keepBackend = async (
+  watch: BackendWatch,
+  now: number,
+  effects: BackendWatchEffects,
+): Promise<BackendWatch> => {
+  if (!backendCheckDue(watch, now)) return watch
+  try {
+    for (const line of (await effects.check()) ?? []) effects.log(`${line}${effects.hint}`)
+    return { checkedAt: now, failureReported: false }
+  } catch (error) {
+    if (!watch.failureReported) effects.log(`backend check failed, still watching: ${errorText(error)}${effects.hint}`)
+    return { checkedAt: now, failureReported: true }
+  }
+}
+
+/**
+ * `lanes.backend` and `worktreeDirectory` of the main checkout's config only: a lane's worktree must change neither
+ * what the watcher runs in the main checkout nor which lanes count as gone. `config` is reused when the watcher
+ * already read the main checkout; undefined without a backend or when that config cannot be read.
+ */
+export const mainCheckoutBackendOf = (
+  root: string,
+  checkoutRoot: string,
+  config: JackherdConfig,
+): MainCheckoutBackend | undefined => {
+  try {
+    const main = checkoutRoot === root ? config : readConfig([root])
+    return main.lanes.backend ? { backend: main.lanes.backend, worktreeDirectory: main.worktreeDirectory } : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** One check of the main checkout's backend under the lock, without waiting for it. */
+export const backendCheckOf =
+  (root: string, { backend, worktreeDirectory }: MainCheckoutBackend) =>
+  (): Promise<string[] | null> => {
+    const files = backendFilesOf(root)
+    const system = backendSystemOf({ root, worktreeDirectory, backend, files })
+    return withBackendLock(files.lock, 0, () => checkBackend(backend, system))
+  }

package/src/brief/command.ts

@@ -35,7 +35,7 @@ export const run = async (args: string[]): Promise<number> => {
     const here = worktreeRoot(process.cwd())
     const settings = readSettings([here, root])
     const picked = boardFor(boardPath, [root, here], settings, () => foundLanesOf(root, settings, () => []))
-    for (const line of briefLines(laneFactsOf(root, settings, picked.file, Date.now()), settings.planLanguage))
+    for (const line of briefLines(laneFactsOf(root, settings, picked.file, Date.now()), settings.boardLanguage))
       console.log(line)
     return 0
   } catch (error) {

package/src/brief/lane-facts.ts

@@ -3,7 +3,7 @@ import { dirname, join, relative } from 'node:path'
 import { parseSprintLanes, resolvePlanPath, type SprintLane } from '../plan-format'
 import { type QuestionRecord } from '../plans/question-records'
 import { type SentFileRecord, sentLaneOf } from '../plans/sent-files'
-import type { PlansSettings } from '../plans/settings'
+import { type PlansSettings } from '../plans/settings'
 import { laneDirectoryOf } from '../plans/unlisted-lanes'
 import { readWaitingRecords } from '../plans/waiting-records'
 import { isStillWaiting } from '../plans/waiting-window'
@@ -49,7 +49,7 @@ export const laneFactsOf = (root: string, settings: PlansSettings, boardFile: st
   const sprintDirectory = dirname(relative(root, boardFile))
   const worktreeDirectory = join(root, settings.worktreeDirectory)
   const records = readWaitingRecords(root)
-  return parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.planLanguage)
+  return parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.boardLanguage)
     .filter(({ closed }) => !closed)
     .map((lane) => {
       const href = planHrefOf(lane)

package/src/check/command.ts

@@ -223,7 +223,7 @@ const openBoxesCheckOf = (root: string, settings: CheckSettings): CheckResult |
         lane,
         planDirectory: settings.planDirectory,
         board: settings.board,
-        language: settings.planLanguage,
+        language: settings.boardLanguage,
         level: settings.check.openBoxes,
         baseOf: contentAt(root, baseRefOf(settings)),
       })
@@ -253,6 +253,7 @@ const ownChecksOf = (
     paths,
     planDirectory: settings.planDirectory,
     language: settings.planLanguage,
+    boardLanguage: settings.boardLanguage,
     previousOf: contentAt(root, 'HEAD'),
     baseOf: contentAt(root, baseRefOf(settings)),
     planRoots: planRootsOf(root, settings.worktreeDirectory),

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

@@ -13,12 +13,14 @@ import {
   laneProgress,
   longPhaseTitles,
   mergedPhasesWithOpenBoxes,
+  newPhasesWithoutPurpose,
   newPhasesWithoutReviewGate,
   openBoxesOfPhase,
   PHASE_CELL_LIMIT,
   PHASE_TITLE_LIMIT,
   type PhaseWithOpenBoxes,
   type PhaseWithoutGate,
+  type PhaseWithoutPurpose,
   type PhaseWithoutRow,
   PLAN_VOCABULARY,
   type PlanLanguage,
@@ -38,7 +40,10 @@ import {
   shortNameFindings,
 } from '../plan-format'
 import { boardRowsWithBareCodes, type RowWithBareCode } from '../plan-format/bare-codes'
+import { namesState } from '../plan-format/markdown'
+import { firstUnrecognizedSectionLine } from '../plan-format/unrecognized-sections'
 import { mergePlanPhases } from '../plans/phase-source'
+import { CELL_KEY, PARTIAL_PHASE_WORDS, SECTION_KEY } from '../vocabulary'
 import { changedPlansOf } from './deferral-arrows'
 import { CHECK_STATUS, type CheckResult } from './result'
 import { OPEN_BOXES_LEVEL, type OpenBoxesLevel } from './schema'
@@ -55,6 +60,8 @@ export type PlanCheckInput = {
   paths: readonly string[]
   planDirectory: string
   language: PlanLanguage
+  /** The language the boards are read in first; `language` when absent. */
+  boardLanguage?: PlanLanguage
   previousOf: ContentAt
   baseOf: ContentAt
   /** Where a board's plans are read, `root` when absent: the checkout, the main checkout and the lane worktrees. */
@@ -124,6 +131,16 @@ const gateReport = (language: PlanLanguage): Report<PhaseWithoutGate> => ({
   clean: 'every new phase has a review gate',
 })
 
+const purposeReport = (language: PlanLanguage): Report<PhaseWithoutPurpose> => ({
+  name: 'Plan phase purposes',
+  noun: 'plan',
+  rule: 'new phases say what they are about',
+  unmet: CHECK_STATUS.fail,
+  text: ({ path, line, id, title }) =>
+    `${path}:${line} Phase ${id} ${title} has tasks but no **${PLAN_VOCABULARY[language].phasePurpose}:** line; say in one sentence what is different afterwards, for whom, directly under the heading`,
+  clean: 'every new phase says what it is about',
+})
+
 const rowReport: Report<RowWithoutPhase> = {
   name: 'Board rows without a phase',
   noun: 'board',
@@ -179,6 +196,21 @@ const unlistedReport: Report<PhaseWithoutRow> = {
   clean: 'every phase has a row in the dependency table',
 }
 
+const sectionReport: Report<{ line: number }> = {
+  name: 'Plan sections',
+  noun: 'plan',
+  rule: 'jh reads at least one section',
+  unmet: CHECK_STATUS.warn,
+  text: ({ path, line }) =>
+    `${path}:${line} none of the ## headings is a section jh reads, so every reader finds the document empty; write one in a known language or put <!-- jh: <key> --> on the line directly under it (keys: ${Object.values(SECTION_KEY).join(', ')})`,
+  clean: 'jh reads a section of every changed plan and board',
+}
+
+const sectionsOf = ({ path, current }: Changed): Found<{ line: number }>[] => {
+  const line = firstUnrecognizedSectionLine(current)
+  return line === null ? [] : [{ path, line }]
+}
+
 const shortNameText = (found: Found<ShortNameFinding>): string =>
   found.problem === SHORT_NAME_PROBLEM.long
     ? `${found.path}:${found.line} Phase ${found.phase}: the short name has ${found.length} characters (limit ${SHORT_NAME_LIMIT})`
@@ -207,10 +239,15 @@ const withPath =
   <T>(path: string) =>
   (found: T): Found<T> => ({ ...found, path })
 
-const gatesOf = ({ path, current, previous }: Changed, language: PlanLanguage): Found<PhaseWithoutGate>[] =>
-  newPhasesWithoutReviewGate(current, language, previous ? phaseIdsOfPlan(previous, language) : new Set()).map(
-    withPath(path),
-  )
+/** The ids of the phases the plan had before the change; none for a plan the change creates. */
+const previousPhaseIds = ({ previous }: Changed, language: PlanLanguage): Set<string> =>
+  previous ? phaseIdsOfPlan(previous, language) : new Set()
+
+const gatesOf = (file: Changed, language: PlanLanguage): Found<PhaseWithoutGate>[] =>
+  newPhasesWithoutReviewGate(file.current, language, previousPhaseIds(file, language)).map(withPath(file.path))
+
+const purposesOf = (file: Changed, language: PlanLanguage): Found<PhaseWithoutPurpose>[] =>
+  newPhasesWithoutPurpose(file.current, language, previousPhaseIds(file, language)).map(withPath(file.path))
 
 const rowsOf = ({ path, current, previousLines }: Changed, language: PlanLanguage): Found<RowWithoutPhase>[] =>
   boardRowsWithoutPhase(current, language, previousLines).map(withPath(path))
@@ -219,17 +256,26 @@ const proseOf = ({ path, current, previousLines }: Changed, language: PlanLangua
   boardRowsWithProse(current, language, previousLines).map(withPath(path))
 
 /** Every readable copy of the plans the board links, in each plan root; a path that leaves the repository is skipped. */
-const planTextsOf = (roots: readonly string[], { path, current }: Changed, language: PlanLanguage): string[] =>
-  boardPlansOf(current, posix.normalize(dirname(path)), language)
+const planTextsOf = (
+  roots: readonly string[],
+  { path, current }: Changed,
+  languages: { board: PlanLanguage; plan: PlanLanguage },
+): string[] =>
+  boardPlansOf(current, posix.normalize(dirname(path)), languages.board)
     .filter(isInsideRepository)
     .flatMap((plan) => planCopiesIn(roots, plan))
 
-const bareCodesOfBoard = (roots: readonly string[], file: Changed, language: PlanLanguage): Found<RowWithBareCode>[] =>
+/** The board is read in the board language, the plans it links in the plan language. */
+const bareCodesOfBoard = (
+  roots: readonly string[],
+  file: Changed,
+  languages: { board: PlanLanguage; plan: PlanLanguage },
+): Found<RowWithBareCode>[] =>
   boardRowsWithBareCodes(
     file.current,
-    language,
+    languages.board,
     file.previousLines,
-    codesOfPlans(planTextsOf(roots, file, language), language),
+    codesOfPlans(planTextsOf(roots, file, languages), languages.plan),
   ).map(withPath(file.path))
 
 const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Found<PhaseWithOpenBoxes>[] =>
@@ -297,7 +343,7 @@ const phaseBuiltBy = (input: LaneBoxesInput): BuiltPhase | null => {
   if (!phase || !step?.planHref) return null
   // with the base known, a phase this checkout did not tick further waits in the row; it is not what the lane builds
   if (phase.work === undefined && input.baseOf(pathOf(step.planHref)) !== null) return null
-  const partial = step.label.includes(PLAN_VOCABULARY[input.language].partialPhase)
+  const partial = namesState(step.label, CELL_KEY.partialPhase, PARTIAL_PHASE_WORDS)
   return { planPath: pathOf(step.planHref), phaseId: phase.id, partial }
 }
 
@@ -341,7 +387,8 @@ export const laneOpenBoxesCheck = (input: LaneBoxesInput & { level: OpenBoxesLev
 
 /**
  * The structure of the changed plans and boards:
- * - a phase the change added (against `HEAD`) with tasks and without a review gate fails;
+ * - a phase the change added (against `HEAD`) with tasks and without a review gate fails, and so does one without a
+ *   purpose line directly under its heading;
  * - a lane row the change added or edited that names no phase warns, and so does one whose phases cell is longer
  *   than `PHASE_CELL_LIMIT` or records a side order of the user;
  * - a waiting row the change added or edited whose item cell names a plan code of the board's plans bare warns;
@@ -357,15 +404,20 @@ export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
   const files = changedPlansOf(input.paths, input.planDirectory)
   if (files.length === 0) return []
   const { language } = input
+  const boardLanguage = input.boardLanguage ?? language
   const started = Date.now()
   const changed = changedContents(input, files)
   const boards = changed.filter(({ board }) => board)
   const plans = changed.filter(({ board }) => !board)
   const unlistedPerPlan = plans.map((file) => unlistedOf(file, language)).filter((found) => found !== null)
   const gates = changed.flatMap((file) => gatesOf(file, language))
-  const rows = boards.flatMap((file) => rowsOf(file, language))
-  const prose = boards.flatMap((file) => proseOf(file, language))
-  const bareCodes = boards.flatMap((file) => bareCodesOfBoard(input.planRoots ?? [input.root], file, language))
+  const purposes = changed.flatMap((file) => purposesOf(file, language))
+  const sections = changed.flatMap(sectionsOf)
+  const rows = boards.flatMap((file) => rowsOf(file, boardLanguage))
+  const prose = boards.flatMap((file) => proseOf(file, boardLanguage))
+  const bareCodes = boards.flatMap((file) =>
+    bareCodesOfBoard(input.planRoots ?? [input.root], file, { board: boardLanguage, plan: language }),
+  )
   const merged = plans.flatMap((file) => mergedOf(file, language))
   const unlisted = unlistedPerPlan.flat()
   const shortNames = plans.flatMap((file) => shortNamesOf(file, language))
@@ -373,6 +425,7 @@ export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
   const durationMs = Date.now() - started
   return [
     findingsResult(gateReport(language), gates, files.length, durationMs),
+    findingsResult(purposeReport(language), purposes, files.length, durationMs),
     ...(boards.length > 0
       ? [
           findingsResult(rowReport, rows, boards.length, durationMs),
@@ -390,5 +443,6 @@ export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
           findingsResult(titleReport, titles, plans.length, durationMs),
         ]
       : []),
+    findingsResult(sectionReport, sections, files.length, durationMs),
   ]
 }

package/src/check/settings.ts

@@ -21,6 +21,8 @@ export type CheckSettings = {
   check: CheckConfig
   planDirectory: string
   planLanguage: PlanLanguage
+  /** The language the boards are written in: the config's `boardLanguage`, or `planLanguage` when it sets none. */
+  boardLanguage: PlanLanguage
   /** The branch on the remote whose plans count as merged. */
   baseBranch: string
   /** Where the lane worktrees live, below the main checkout: a board's plans are read there too. */
@@ -44,6 +46,7 @@ export const noStackFallbackOf = ({ stack, check, commands }: CheckSettings): No
 const commandsSchema = jackherdConfigSchema.shape.commands
 const planDirectorySchema = jackherdConfigSchema.shape.planDirectory
 const planLanguageSchema = jackherdConfigSchema.shape.planLanguage
+const boardLanguageSchema = jackherdConfigSchema.shape.boardLanguage
 const baseBranchSchema = jackherdConfigSchema.shape.baseBranch
 const worktreeDirectorySchema = jackherdConfigSchema.shape.worktreeDirectory
 const skillPrefixSchema = jackherdConfigSchema.shape.skillPrefix
@@ -58,11 +61,13 @@ export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckS
   const detected = withDetected(z.record(z.string(), z.unknown()).parse(raw), facts)
   const object = z.record(z.string(), z.unknown()).parse(detected.raw)
   const { test, typecheck, lint } = commandsSchema.parse(object.commands)
+  const planLanguage = planLanguageSchema.parse(object.planLanguage)
   return {
     commands: { test, typecheck, lint },
     check: checkConfigSchema.parse(object.check ?? {}),
     planDirectory: planDirectorySchema.parse(object.planDirectory),
-    planLanguage: planLanguageSchema.parse(object.planLanguage),
+    planLanguage,
+    boardLanguage: boardLanguageSchema.parse(object.boardLanguage) ?? planLanguage,
     baseBranch: baseBranchSchema.parse(object.baseBranch),
     worktreeDirectory: worktreeDirectorySchema.parse(object.worktreeDirectory),
     board: boardSchema.parse(object.board),

package/src/check/skill-budget-defaults.ts

@@ -74,7 +74,8 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   '.claude/skills/orchestrate/references/waiting.md': 216,
   '.claude/skills/orchestrate/references/watch-without-monitor.md': 154,
   // Prose cut, round 2: cut to its mandatory rules, measured size plus 5 %.
-  '.claude/skills/plan/SKILL.md': 1717,
+  // Language split: the note that a template renders in the language of its file name and that a heading in any other language carries a marker (+27).
+  '.claude/skills/plan/SKILL.md': 1744,
   '.claude/skills/plan/references/template-English.md': 536,
   '.claude/skills/plan/references/template-German.md': 501,
   // Prose cut, round 2: cut to its mandatory rules, measured size plus 5 %.
@@ -111,9 +112,11 @@ export const KIT_SKILL_CEILINGS: Readonly<Record<string, number>> = {
   '.claude/agents/skill-review.md': 513,
   // Plan head: every plan opens with a `For you` head of five short lines a person reads first, which
   // `jh plan check` reports; cut to its labels; skill-review: the status line says what `N` counts. Measured size (+42).
-  '.claude/skills/plan/references/template-English.md': 578,
+  // Phase purpose: the line under every phase heading a template shows, one sentence of what is different afterwards and for whom (+17).
+  '.claude/skills/plan/references/template-English.md': 595,
   // Plan head: the same `Für dich` head as the English template, with what `N` counts; measured size (+41).
-  '.claude/skills/plan/references/template-German.md': 542,
+  // Phase purpose: the same line under every phase heading as the English template (+15).
+  '.claude/skills/plan/references/template-German.md': 557,
   // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
   // Plain words: no plan code without its words in a short question.
   // Any language: a pointer in § 0 and a section in events.md for `plan missing`.

package/src/cli.ts

@@ -19,6 +19,7 @@ const ALIASES = new Set<string>([HERD_COMMAND.alias])
 /** One line per command; each entry lazily imports the module that exports its `run`. */
 export const COMMANDS: CommandTable = {
   approval: () => import('./approval/command'),
+  backend: () => import('./backend/command-line'),
   brief: () => import('./brief/command'),
   check: () => import('./check/command'),
   config: () => import('./config/command'),

package/src/config/schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { backendSchema } from '../backend/schema'
 import { checkConfigSchema } from '../check/schema'
 import { claudePath, WORKTREES_DIRECTORY } from '../claude/paths'
 import { SECRET_NAME } from '../secrets/options'
@@ -566,7 +567,10 @@ export const jackherdConfigSchema = z.strictObject({
   responseLanguage: language.default(PLAN_LANGUAGE.en),
   /** Whether replies address the user with the familiar or the polite form where the language has both (German: du or Sie). */
   responseAddress: z.enum(Object.values(RESPONSE_ADDRESS)).default(RESPONSE_ADDRESS.informal),
+  /** The language new plans and the plan templates are written in. Boards and plans are read in every known language whatever this says. */
   planLanguage: language.default(PLAN_LANGUAGE.en),
+  /** The language jh writes the board in (history lines, lane rows, waiting rows); `planLanguage` when left out. */
+  boardLanguage: language.optional(),
   planDirectory: z.string().min(1).default('docs/plans'),
   /** Where the boards live and what the project calls them. */
   board: boardSchema.prefault({}),
@@ -607,6 +611,8 @@ export const jackherdConfigSchema = z.strictObject({
       basePort: z.number().int().min(1).max(65535).optional(),
       /** The command `jh lane dev` runs as `PORT=<port> <command>` in a pane beside the lane's agent; `{port}` and `{filter}` (`--filter <package>`) are filled in. Without it `jh lane dev` refuses. */
       devCommand: z.string().min(1).optional(),
+      /** The services every lane's app talks to, run in one pane of the main checkout that the watcher starts and keeps; without it `jh backend` has nothing to run. */
+      backend: backendSchema.optional(),
     })
     .prefault({}),
   models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId).default(DEFAULT_MODELS),