jackherd 1.24.0 → 1.25.0

package/kit/hooks/hooks/shared/board-lanes.ts

@@ -27,16 +27,38 @@ const PLAN_COLUMN = 2
 
 const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
-const sectionLines = (markdown: string, heading: string): string[] => {
+const MARKER = /<!--\s*jh:\s*([a-z-]+)\s*-->/
+
+const markerOf = (text: string | undefined): string | undefined => (text === undefined ? undefined : MARKER.exec(text)?.[1])
+
+const languagesFrom = (language: BoardLanguage): BoardLanguage[] =>
+  [language, ...(Object.keys(BOARD_WORDS) as BoardLanguage[]).filter((other) => other !== language)]
+
+/** The index of the lanes section's heading: the marker `<!-- jh: lanes -->` under it, else the heading of `language`, else of the other language. */
+const lanesHeadingIndex = (lines: string[], language: BoardLanguage): number => {
+  const marked = lines.findIndex((line, index) => SECTION_END.test(line) && markerOf(lines[index + 1]) === 'lanes')
+  if (marked !== -1) return marked
+  for (const candidate of languagesFrom(language)) {
+    const pattern = new RegExp(`^##\\s+${escapeRegExp(BOARD_WORDS[candidate].lanes)}\\s*$`)
+    const found = lines.findIndex((line) => pattern.test(line))
+    if (found !== -1) return found
+  }
+  return -1
+}
+
+const lanesSectionLines = (markdown: string, language: BoardLanguage): string[] => {
   const lines = markdown.split('\n')
-  const pattern = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`)
-  const start = lines.findIndex((line) => pattern.test(line))
-  if (start === -1) return []
-  const rest = lines.slice(start + 1)
+  const heading = lanesHeadingIndex(lines, language)
+  if (heading === -1) return []
+  const rest = lines.slice(heading + 1)
   const end = rest.findIndex((line) => SECTION_END.test(line))
   return end === -1 ? rest : rest.slice(0, end)
 }
 
+/** Whether a lane's name cell says the lane was cleaned up: the marker `<!-- jh: lane-closed -->`, or the word of any language. */
+const isClosedCell = (cell: string): boolean =>
+  markerOf(cell) === 'lane-closed' || Object.values(BOARD_WORDS).some(({ laneClosed }) => cell.includes(laneClosed))
+
 const cellsOf = (line: string): string[] =>
   line
     .slice(1, line.endsWith('|') ? -1 : undefined)
@@ -55,7 +77,7 @@ const firstTableLines = (lines: string[]): string[] => {
 const laneRows = (markdown: string, language: BoardLanguage): Row[] => {
   const rows: Row[] = []
   let previous: string | null = null
-  for (const line of firstTableLines(sectionLines(markdown, BOARD_WORDS[language].lanes))) {
+  for (const line of firstTableLines(lanesSectionLines(markdown, language))) {
     const cells = cellsOf(line)
     const first = cells[0] ?? ''
     const lane: string | null = first.match(LANE_NAME)?.[1] ?? (first.startsWith(CONTINUATION) ? previous : null)
@@ -73,11 +95,11 @@ const planPathOf = (boardDirectory: string, cell: string): string[] => {
 }
 
 /** The rows of one lane since it was last cleaned up: a named row without the mark after a closed one starts it anew. */
-const currentRows = <Row extends { cells: string[] }>(rows: Row[], closedWord: string): Row[] =>
+const currentRows = <Row extends { cells: string[] }>(rows: Row[]): Row[] =>
   rows.reduce<{ closed: boolean; kept: Row[] }>(
     ({ closed, kept }, row) => {
       const first = row.cells[0] ?? ''
-      const marked = first.includes(closedWord)
+      const marked = isClosedCell(first)
       const startsAnew = closed && !marked && !first.startsWith(CONTINUATION)
       return { closed: marked || (closed && !startsAnew), kept: startsAnew ? [row] : [...kept, row] }
     },
@@ -100,11 +122,10 @@ export const boardPlansOf = (markdown: string, boardDirectory: string, language:
 
 /** Every lane the lanes table names whose current rows do not say it was cleaned up, in table order, read in one pass. */
 export const openLaneNamesOf = (markdown: string, language: BoardLanguage): string[] => {
-  const { laneClosed } = BOARD_WORDS[language]
   const rowsByLane = new Map<string, Row[]>()
   for (const row of laneRows(markdown, language)) rowsByLane.set(row.lane, [...(rowsByLane.get(row.lane) ?? []), row])
   return [...rowsByLane].flatMap(([lane, rows]) =>
-    currentRows(rows, laneClosed).some(({ cells }) => (cells[0] ?? '').includes(laneClosed)) ? [] : [lane],
+    currentRows(rows).some(({ cells }) => isClosedCell(cells[0] ?? '')) ? [] : [lane],
   )
 }
 
@@ -117,9 +138,9 @@ export const lanePlansOf = (
 ): LanePlans | undefined => {
   const all = laneRows(markdown, language).filter((row) => row.lane === lane)
   if (all.length === 0) return undefined
-  const rows = currentRows(all, BOARD_WORDS[language].laneClosed)
+  const rows = currentRows(all)
   return {
-    closed: rows.some(({ cells }) => (cells[0] ?? '').includes(BOARD_WORDS[language].laneClosed)),
+    closed: rows.some(({ cells }) => isClosedCell(cells[0] ?? '')),
     plans: [...new Set(rows.flatMap(({ cells }) => planPathOf(boardDirectory, cells[PLAN_COLUMN] ?? '')))],
   }
 }

package/kit/hooks/hooks/shared/boards.ts

@@ -12,9 +12,13 @@ import { isRepositoryDirectory } from './repository-directory'
 /** A board's directory relative to the repository, and its text. */
 export type Board = { directory: string; text: string }
 
-/** The plan language, the plan directory and the board pattern and file below it, and where the lane worktrees live. */
+/**
+ * The plan language, the language the board is written in (the plan language when the config sets none), the plan
+ * directory and the board pattern and file below it, and where the lane worktrees live.
+ */
 export type BoardLocation = {
   planLanguage: BoardLanguage
+  boardLanguage: BoardLanguage
   planDirectory: string
   board: { pattern: string; file: string }
   worktreeDirectory: string
@@ -42,8 +46,16 @@ const isPlanLanguage = (value: unknown): value is BoardLanguage => typeof value
  * The board location's values of a config, each with its default where absent and `undefined` where present but
  * invalid; `board` is the config's `board` section.
  */
-export const boardLocationValues = (config: Record<string, unknown>, board: Record<string, unknown>) => ({
-  planLanguage: valueOr(config, 'planLanguage', isPlanLanguage, 'en'),
+export const boardLocationValues = (config: Record<string, unknown>, board: Record<string, unknown>) => {
+  const planLanguage = valueOr(config, 'planLanguage', isPlanLanguage, 'en')
+  return {
+    planLanguage,
+    boardLanguage: valueOr(config, 'boardLanguage', isPlanLanguage, planLanguage ?? 'en'),
+    ...directoryValues(config, board),
+  }
+}
+
+const directoryValues = (config: Record<string, unknown>, board: Record<string, unknown>) => ({
   planDirectory: valueOr(config, 'planDirectory', isRepositoryDirectory, 'docs/plans'),
   pattern: valueOr(board, 'pattern', matches(BOARD_PATTERN), 'board-*'),
   file: valueOr(board, 'file', matches(BOARD_FILE), 'board.md'),
@@ -54,10 +66,14 @@ export const boardLocationValues = (config: Record<string, unknown>, board: Reco
 export const boardLocationOf = (config: Record<string, unknown>): BoardLocation | null => {
   const board = config.board ?? {}
   if (!isRecord(board)) return null
-  const { planLanguage, planDirectory, pattern, file, worktreeDirectory } = boardLocationValues(config, board)
-  if (planLanguage === undefined || planDirectory === undefined || worktreeDirectory === undefined) return null
+  const { planLanguage, boardLanguage, planDirectory, pattern, file, worktreeDirectory } = boardLocationValues(
+    config,
+    board,
+  )
+  if (planLanguage === undefined || boardLanguage === undefined) return null
+  if (planDirectory === undefined || worktreeDirectory === undefined) return null
   if (pattern === undefined || file === undefined) return null
-  return { planLanguage, planDirectory, board: { pattern, file }, worktreeDirectory }
+  return { planLanguage, boardLanguage, planDirectory, board: { pattern, file }, worktreeDirectory }
 }
 
 /** The boards under the plan directory of the main checkout whose directory name matches the board pattern. */

package/kit/workflow/skills/orchestrate/references/herd.md

@@ -8,13 +8,13 @@ is missing or comes twice.
 It reads the plans at `origin/{{kit.baseBranch}}`. From a lane's worktree, once the lane has work
 there, it takes the phases the lane's rows name and any phase that is new there or ticked further
 than on the base. It redraws when a plan file changes or a fetch of the base branch lands in the
-main checkout (the watcher fetches it as soon as the remote moved). While it runs, it also sets each
-lane's sidebar title (`P4 · 7/12`) and clears it on exit.
+main checkout (the watcher fetches it as soon as the remote moved). While it runs it sets each
+lane's sidebar title (`P4 · 7/12`), clearing it on exit. An opened lane adds each phase's purpose line.
 
 A phase the lane ticked to the end in its worktree stays its current phase until the base branch
 carries its ticks (the watcher marks it `abgehakt, nicht gemergt` / `ticked, not merged`; the herd
 shows the branch's `↑n` instead); an open phase the lane works on goes first. The lane's newest row decides
-which phases count: ticks in an older phase (tidying the plan) take over only when that row names no
+which phases count: ticks in an older phase take over only when that row names no
 phase or only merged ones, which is why each new row starts with its phase number (§ 2 step 5).
 
 ## Notices per lane

package/kit/workflow/skills/plan/SKILL.md

@@ -11,6 +11,8 @@ You create a structured concept/plan document in `{{kit.planDirectory}}/`.
 > written in {{kit.planLanguage}}. Keep the section headings of the template **verbatim** — the plan
 > parser, `/implement` and `spec-review` find `## {{kit.heading.decisions}}`,
 > `## {{kit.heading.implementation}}` and `## {{kit.heading.documentation}}` by those exact names.
+> Another language: each heading, table head and purpose line carries `<!-- jh: <key> -->` (keys:
+> `docs/plan-contract.md`, "Language and markers"); done when `jh plan check` shows no `missing`.
 
 ## Your Workflow
 
@@ -36,7 +38,7 @@ The closing documentation section reads `## N — …` with rows `N.1` to `N.5`:
 
 A checkbox moved on purpose to a later phase stays where it is, unticked, and ends in the target: `- [ ] Update the documentation → P9`. The herd counts it neither as open nor as done in its own phase and lists it as open in phase 9. The arrow stands only at the end of the line. Once a phase's tasks are ticked on the base branch, every box still open in it, gate boxes included, is ticked or moved on this way; `jh check` checks both.
 
-A task starts with its short name: `- [ ] **Name**: …` (a review-gate item keeps its own form). The name has 40 characters at most and names the subject and the result (`Heartbeat shows progress without ticks`); the how, the conditions, the origin and the evidence follow the colon. A phase's title is its name; its context goes into its origin line, a quote under the heading (`> Origin: …`, in the plan's language). A task the user adds later: `- [ ] **Name**: … (User <DD.MM.> <HH:MM>)`.
+A task starts with its short name: `- [ ] **Name**: …` (a review-gate item keeps its own form). The name has 40 characters at most and names the subject and the result (`Heartbeat shows progress without ticks`); the how, the conditions, the origin and the evidence follow the colon. A phase's title is its name; directly under it stands the purpose line of the template, one sentence saying what is different afterwards and for whom, so that a reader outside the project understands the phase from that line alone; `jh check` asks for it on every new phase. The phase's context goes into its origin line, a quote below the purpose line (`> Origin: …`, in the plan's language). A task the user adds later: `- [ ] **Name**: … (User <DD.MM.> <HH:MM>)`.
 
 An Artifact that belongs to the plan (a mockup, a draft for review, a findings page) stands as a Markdown link with its title in the phase it concerns, in the same move as its first publish: `**Mockup:** [Title](url)` or in the origin line. The herd shows them as chips; nothing else ties an Artifact published from the main checkout to the lane.
 

package/kit/workflow/skills/plan/references/template-English.md

@@ -50,6 +50,8 @@ What changes concretely? Files, modules, flows.
 
 ### {{kit.heading.phase}} 1: ...
 
+**What it is about:** what is different afterwards, for whom; "nothing visible" when that is the case
+
 - [ ] **Name of step 1**: how, conditions, origin, evidence
 - [ ] **Name of step 2**: how, conditions, origin, evidence
 

package/kit/workflow/skills/plan/references/template-German.md

@@ -50,6 +50,8 @@ Was ändert sich konkret? Dateien, Module, Flows.
 
 ### {{kit.heading.phase}} 1: ...
 
+**Worum es geht:** was danach anders ist, für wen; „nichts Sichtbares“, wenn das so ist
+
 - [ ] **Name von Schritt 1**: Wie, Bedingungen, Herkunft, Beleg
 - [ ] **Name von Schritt 2**: Wie, Bedingungen, Herkunft, Beleg
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/schemas/jackherd.schema.json

@@ -29,6 +29,13 @@
         "en"
       ]
     },
+    "boardLanguage": {
+      "type": "string",
+      "enum": [
+        "de",
+        "en"
+      ]
+    },
     "planDirectory": {
       "default": "docs/plans",
       "type": "string",

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/config/schema.ts

@@ -567,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({}),

package/src/lane/close-board.ts

@@ -1,8 +1,8 @@
 import { twoDigits } from '../plan-format/clock'
 import { laneNameOf, parseSprintLanes } from '../plan-format/lanes'
-import { firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
+import { firstTableRows, namesState, sectionLines, sectionStart } from '../plan-format/markdown'
 import { terminalSafe } from '../plan-format/terminal-text'
-import { PLAN_LANGUAGE, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { CELL_KEY, LANE_CLOSED_WORDS, PLAN_LANGUAGE, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
 import { BOARD_LANE, type BoardLane } from './close-check'
 
 const CONTINUATION = '↳'
@@ -38,7 +38,7 @@ export const boardLaneOf = (board: string, lane: string, language: PlanLanguage)
  * a row that names the lane again without the mark starting it anew. Empty when the lane is closed or missing.
  */
 const currentRowIndexes = (board: string, lane: string, language: PlanLanguage): number[] => {
-  const { sections, laneClosed } = PLAN_VOCABULARY[language]
+  const { sections } = PLAN_VOCABULARY[language]
   const start = sectionStart(board, sections.lanes)
   if (start === -1) return []
   let previous: string | null = null
@@ -49,7 +49,7 @@ const currentRowIndexes = (board: string, lane: string, language: PlanLanguage):
     const name = laneNameOf(first, previous)
     previous = name ?? previous
     if (name !== lane) continue
-    const marked = first.includes(laneClosed)
+    const marked = namesState(first, CELL_KEY.laneClosed, LANE_CLOSED_WORDS)
     if (closed && !marked && !first.startsWith(CONTINUATION)) {
       closed = false
       indexes = []

package/src/lane/close-command.ts

@@ -185,7 +185,7 @@ const surveyOf = async (lane: string, branch: string | null, context: CloseConte
   const present = entry !== null && existsSync(context.worktree)
   const facts: CloseFacts = {
     lane,
-    boardLane: boardLaneOf(readFileSync(context.boardFile, 'utf8'), lane, context.settings.planLanguage),
+    boardLane: boardLaneOf(readFileSync(context.boardFile, 'utf8'), lane, context.settings.boardLanguage),
     setupFiles: setupFilesOf(context.root),
     ...agentFactsOf(laneStatusSourceFor(context.settings.adapter).listAgents(), lane, context.worktree),
     runsInside: realPath(worktreeRoot(context.cwd)) === realPath(context.worktree),
@@ -267,7 +267,7 @@ export const run = async (args: string[], cwd: string = process.cwd()): Promise<
       boardPath: relative(context.root, context.boardFile),
       dryRun: options.dryRun,
       now: new Date(),
-      language: context.settings.planLanguage,
+      language: context.settings.boardLanguage,
     }
     return await closeLane(request, portsFor(options.lane, options.branch, context))
   } catch (error) {

package/src/lane/dev-command.ts

@@ -26,7 +26,7 @@ export const run = async (args: string[], cwd: string = process.cwd()): Promise<
     const settings = readSettings([root, worktreeRoot(cwd)])
     const board = boardFor(boardPath === null ? null : resolve(cwd, boardPath), [root], settings, () => [])
     if (board.notice) console.error(terminalSafe(board.notice))
-    const row = parseSprintLanes(readFileSync(board.file, 'utf8'), settings.planLanguage).find(
+    const row = parseSprintLanes(readFileSync(board.file, 'utf8'), settings.boardLanguage).find(
       ({ name, closed }) => name === lane && !closed,
     )
     const port = devPortOf(portOption, row?.port ?? null)

package/src/lane/port-command.ts

@@ -25,7 +25,7 @@ export const run = async (args: string[], cwd: string = process.cwd()): Promise<
     const settings = readSettings([root, worktreeRoot(cwd)])
     const board = boardFor(boardPath === null ? null : resolve(cwd, boardPath), [root], settings, () => [])
     if (board.notice) console.error(terminalSafe(board.notice))
-    const reserved = portsOfRunningLanes(parseSprintLanes(readFileSync(board.file, 'utf8'), settings.planLanguage))
+    const reserved = portsOfRunningLanes(parseSprintLanes(readFileSync(board.file, 'utf8'), settings.boardLanguage))
     const port = await freePortNotListening(settings.basePort, reserved, MAX_PORT, isPortListening)
     if (port === null) throw new Error(`no free port from ${settings.basePort} to ${MAX_PORT}`)
     console.log(port)

package/src/plan-contract/command.ts

@@ -23,7 +23,8 @@ export const USAGE = `usage: ${CLI_NAME} plan ${CHECK_SUBCOMMAND} <plan.md>
 
 Checks one plan against the plan contract: phases, tasks in every phase, a model for every phase, a dependency
 row for every phase (from two phases on). One line per part, \`file:line\` where a part is incomplete.
-A fifth line, \`head:\` present, missing or stale, reports the plan's "For you" head; it is a note and never changes the exit code.
+A fifth line, \`head:\` present, missing or stale, reports the plan's "For you" head; a sixth, \`purpose:\` present or missing,
+reports whether every phase opens with its one-sentence purpose line. Both are notes and never change the exit code.
 Where git has the base branch, a plan, or a board that links it, that the base branch lacks gets a \`base:\` line with its path.
 The plan language comes from .jackherd/config.json.
 Exit 0 met, 1 with gaps, 2 for a wrong command line or an unreadable file, 3 met but not on the base branch.`