jackherd 1.23.3 → 1.25.0

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/dev.ts

@@ -1,4 +1,5 @@
 import { isRecord } from '../shared/is-record'
+import { SHELL_WORD } from '../shared/shell-word'
 import { CLI_NAME } from '../version/release'
 import { MAX_PORT } from './port'
 
@@ -36,7 +37,6 @@ board, the command is lanes.devCommand of the config ({port} and {filter} stand
 PORT=<port> <command> in a pane labelled "<lane> dev :<port>". A port something listens on is refused; a pane with
 that label in the lane's tab is reported and left alone.`
 
-const FILTER_VALUE = /^[\w@./:-]+$/
 const PORT_PLACEHOLDER = '{port}'
 const FILTER_PLACEHOLDER = '{filter}'
 
@@ -83,7 +83,7 @@ export const devLabelOf = (lane: string, port: number): string => `${lane} dev :
  */
 export const devCommandOf = (template: string | null | undefined, port: number, filter: string | null): string => {
   if (!template) throw new Error('no dev command: set lanes.devCommand in .jackherd/config.json')
-  if (filter !== null && !FILTER_VALUE.test(filter)) throw new Error(`${FILTER} ${filter} is no package name`)
+  if (filter !== null && !SHELL_WORD.test(filter)) throw new Error(`${FILTER} ${filter} is no package name`)
   if (filter === null && template.includes(FILTER_PLACEHOLDER))
     throw new Error(`lanes.devCommand names {filter}: pass ${FILTER} <package>`)
   const command = template.replaceAll(PORT_PLACEHOLDER, String(port)).replaceAll(FILTER_PLACEHOLDER, filter ?? '')

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.`

package/src/plan-contract/contract.ts

@@ -10,16 +10,19 @@ import {
   phaseCount,
   phaseHeadings,
   phaseLabels,
+  phasesWithoutPurpose,
 } from '../plan-format'
-import type { PlanLanguage } from '../vocabulary'
+import { lookedForSection } from '../plan-format/markdown'
+import { type PlanLanguage, SECTION_KEY } from '../vocabulary'
 
-/** The five parts of the plan contract; the head is a note, never a gap. */
+/** The six parts of the plan contract; the head and the purpose lines are notes, never a gap. */
 export const CONTRACT_PART = {
   phases: 'phases',
   tasks: 'tasks',
   model: 'model',
   dependencies: 'dependencies',
   head: 'head',
+  purpose: 'purpose',
 } as const
 
 export type ContractPart = (typeof CONTRACT_PART)[keyof typeof CONTRACT_PART]
@@ -37,7 +40,7 @@ export type PartStatus = (typeof PART_STATUS)[keyof typeof PART_STATUS]
 /** `line` is the 1-based line of the first problem, or of the part's first sign; null when the plan shows none. */
 export type PartFinding = { part: ContractPart; status: PartStatus; line: number | null; message: string }
 
-/** `met` is false when a part is malformed, or phases, tasks or the model table are missing; a missing dependency table or a missing or stale head is a note. */
+/** `met` is false when a part is malformed, or phases, tasks or the model table are missing; a missing dependency table, a missing or stale head or a missing purpose line is a note. */
 export type PlanContract = { parts: PartFinding[]; met: boolean }
 
 /** Fewer phases than this need no dependency table: there is nothing to put side by side. */
@@ -64,18 +67,19 @@ const phasesPart = (headings: readonly PhaseHeading[]): PartFinding =>
     ? finding(CONTRACT_PART.phases, PART_STATUS.missing, null, 'no phase heading')
     : finding(CONTRACT_PART.phases, PART_STATUS.present, headings[0].line, phaseCount(headings.length))
 
-/** Present when no phase lacks the part (`ok`), else malformed at the first phase that does, naming them all. */
+/** Present when no phase lacks the part (`ok`), else `unmet` (malformed by default) at the first phase that does, naming them all. */
 const coverage = (
   part: ContractPart,
   without: readonly PhaseHeading[],
   ok: { line: number | null; message: string },
   problem: string,
+  unmet: PartStatus = PART_STATUS.malformed,
 ): PartFinding =>
   without.length === 0
     ? finding(part, PART_STATUS.present, ok.line, ok.message)
     : finding(
         part,
-        PART_STATUS.malformed,
+        unmet,
         without[0].line,
         `${problem} ${phaseLabels(
           without.map(({ id }) => id),
@@ -108,7 +112,10 @@ const lacks = (headings: readonly PhaseHeading[], listed: ReadonlySet<string>):
 
 const modelPart = (markdown: string, language: PlanLanguage, headings: readonly PhaseHeading[]): PartFinding => {
   const rows = parseModelTable(markdown, language)
-  if (rows === null) return finding(CONTRACT_PART.model, PART_STATUS.missing, null, 'no model table')
+  if (rows === null) {
+    const looked = lookedForSection(SECTION_KEY.model, '###', language)
+    return finding(CONTRACT_PART.model, PART_STATUS.missing, null, `no model table ${looked}`)
+  }
   const modelled = new Set(rows.filter(isDecided).map(({ id }) => id))
   return coverage(
     CONTRACT_PART.model,
@@ -122,7 +129,10 @@ const dependenciesPart = (markdown: string, language: PlanLanguage, headings: re
   if (headings.length < PHASES_NEEDING_DEPENDENCIES)
     return finding(CONTRACT_PART.dependencies, PART_STATUS.present, null, 'not needed with fewer than two phases')
   const table = parseDependencyTable(markdown, language)
-  if (table === null) return finding(CONTRACT_PART.dependencies, PART_STATUS.missing, null, NO_DEPENDENCY_TABLE)
+  if (table === null) {
+    const looked = lookedForSection(SECTION_KEY.dependencies, '###', language)
+    return finding(CONTRACT_PART.dependencies, PART_STATUS.missing, null, `${NO_DEPENDENCY_TABLE} ${looked}`)
+  }
   return coverage(
     CONTRACT_PART.dependencies,
     lacks(headings, new Set(table.map(({ id }) => id))),
@@ -131,8 +141,18 @@ const dependenciesPart = (markdown: string, language: PlanLanguage, headings: re
   )
 }
 
-/** Notes, not gaps: a missing dependency table (the phases then run one after another) and the head, which old plans lack. */
-const NOTE_PARTS: readonly ContractPart[] = [CONTRACT_PART.dependencies, CONTRACT_PART.head]
+/** A note: present when every `### Phase` with tasks opens with its purpose line, else missing at the first phase without, naming them all. */
+const purposePart = (markdown: string, language: PlanLanguage): PartFinding =>
+  coverage(
+    CONTRACT_PART.purpose,
+    phasesWithoutPurpose(markdown, language),
+    { line: null, message: 'every phase says what it is about' },
+    'no purpose line in',
+    PART_STATUS.missing,
+  )
+
+/** Notes, not gaps: a missing dependency table (the phases then run one after another), and the head and the purpose lines, which old plans lack. */
+const NOTE_PARTS: readonly ContractPart[] = [CONTRACT_PART.dependencies, CONTRACT_PART.head, CONTRACT_PART.purpose]
 
 export const isGap = ({ part, status }: PartFinding): boolean =>
   status === PART_STATUS.malformed || (status === PART_STATUS.missing && !NOTE_PARTS.includes(part))
@@ -162,6 +182,7 @@ export const contractOf = (markdown: string, language: PlanLanguage): PlanContra
     modelPart(markdown, language, headings),
     dependenciesPart(markdown, language, headings),
     headPart(markdown, language),
+    purposePart(markdown, language),
   ]
   return { parts, met: !parts.some(isGap) }
 }

package/src/plan-format/bare-codes.ts

@@ -1,6 +1,6 @@
 import { bareCodesOf } from '../../kit/hooks/hooks/shared/plan-codes'
-import { type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
-import { firstTableRows, firstTableWithHeader, sectionLines, sectionStart } from './markdown'
+import { COLUMN_KEY, type PlanLanguage, WAITING_VOCABULARY } from '../vocabulary'
+import { columnIndex, firstTableRows, firstTableWithHeader, sectionLines, sectionStart } from './markdown'
 
 /** A changed row of the waiting section (1-based line) whose item cell names `code` bare, outside brackets. */
 export type RowWithBareCode = { line: number; code: string }
@@ -16,10 +16,10 @@ export const boardRowsWithBareCodes = (
   previousLines: ReadonlySet<string>,
   codes: ReadonlySet<string> | null,
 ): RowWithBareCode[] => {
-  const { heading, columns } = WAITING_VOCABULARY[language]
+  const { heading } = WAITING_VOCABULARY[language]
   const start = sectionStart(markdown, heading)
   const lines = sectionLines(markdown, heading)
-  const item = firstTableWithHeader(lines).header.indexOf(columns.item)
+  const item = columnIndex(firstTableWithHeader(lines).header, COLUMN_KEY.item, language)
   if (item === -1) return []
   return firstTableRows(lines).flatMap(({ index, line, cells }) => {
     const code = previousLines.has(line) ? undefined : bareCodesOf(cells[item] ?? '', codes)[0]

package/src/plan-format/dependencies.ts

@@ -1,6 +1,6 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { COLUMN_KEY, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
 import { PHASE_ID_PREFIX, phaseIdOf, phaseLabels, spannedPhaseIds } from './lanes'
-import { escapeRegExp, firstTableWithHeader, subsectionLines } from './markdown'
+import { columnIndex, escapeRegExp, firstTableWithHeader, subsectionLines } from './markdown'
 import { type PhaseHeading, parsePlanPhases, phaseHeadings } from './phases'
 import { isPhaseFinished } from './progress'
 
@@ -163,10 +163,10 @@ const releasedByFiles = (writes: readonly string[]): string[] =>
  * such table or the table lacks one of its three columns, so a plan that never had one is not asked for rows.
  */
 export const parseDependencyTable = (markdown: string, language: PlanLanguage): PhaseDependency[] | null => {
-  const { sections, columns } = PLAN_VOCABULARY[language]
+  const { sections } = PLAN_VOCABULARY[language]
   const { header, rows } = firstTableWithHeader(subsectionLines(markdown, sections.dependencies))
-  const [after, writes, marker] = [columns.dependsOn, columns.writes, columns.serialMarker].map((name) =>
-    header.indexOf(name),
+  const [after, writes, marker] = [COLUMN_KEY.dependsOn, COLUMN_KEY.writes, COLUMN_KEY.serialMarker].map((key) =>
+    columnIndex(header, key, language),
   )
   if (after === -1 || writes === -1 || marker === -1) return null
   return rows.flatMap((cells) => {

package/src/plan-format/lanes.ts

@@ -1,6 +1,6 @@
 import { posix } from 'node:path'
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { firstHeading, firstTable, firstTableRows, sectionLines, sectionStart } from './markdown'
+import { CELL_KEY, LANE_CLOSED_WORDS, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { firstHeading, firstTable, firstTableRows, namesState, sectionLines, sectionStart } from './markdown'
 
 /**
  * `namedPhaseIds` holds every id the row names when `withoutRepeats` dropped some because an earlier row of the lane
@@ -156,14 +156,13 @@ export const withoutRepeats = (lane: SprintLane, step: PlanStep): PlanStep => {
 export const parseSprintLanes = (markdown: string, language: PlanLanguage): SprintLane[] => {
   const lanes = new Map<string, SprintLane>()
   const phaseId = phaseIdPatterns(language)
-  const { laneClosed } = PLAN_VOCABULARY[language]
   let previous: string | null = null
   for (const cells of firstTable(sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes))) {
     const name = laneNameOf(cells[0] ?? '', previous)
     if (!name) continue
     const port = Number.parseInt(cells[1] ?? '', 10)
     const lane = lanes.get(name) ?? { name, port: Number.isNaN(port) ? null : port, steps: [], closed: false }
-    const marked = (cells[0] ?? '').includes(laneClosed)
+    const marked = namesState(cells[0] ?? '', CELL_KEY.laneClosed, LANE_CLOSED_WORDS)
     if (lane.closed && !marked && !(cells[0] ?? '').startsWith(CONTINUATION)) {
       lane.closed = false
       lane.steps = []

package/src/plan-format/markdown.ts

@@ -1,3 +1,15 @@
+import {
+  type CellKey,
+  type ColumnKey,
+  columnWords,
+  headingOfSection,
+  isSectionKey,
+  languagesFrom,
+  MARKER_IN_TEXT,
+  type PlanLanguage,
+  type SectionKey,
+  sectionOfHeading,
+} from '../vocabulary'
 import { terminalSafe } from './terminal-text'
 
 const SECTION_END = /^##\s/
@@ -5,20 +17,120 @@ const TABLE_SEPARATOR = /^\|[\s|:-]+\|$/
 
 export const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
-/** The index of the line after a level-2 heading with exactly this text; -1 when there is none. */
-export const sectionStart = (markdown: string, headingText: string): number => {
-  const heading = new RegExp(`^##\\s+${escapeRegExp(headingText)}\\s*$`)
+const MARKER = /^<!--\s*jh:\s*([a-z-]+)\s*-->\s*$/
+
+/** The key of the `<!-- jh: <key> -->` marker in `text`, wherever it stands; null when there is none. The key is not checked against any vocabulary. */
+export const markedKeyOf = (text: string): string | null => MARKER_IN_TEXT.exec(text)?.[1] ?? null
+
+/** `text` without its marker, trimmed: what a cell or a line says in words. */
+export const withoutMarker = (text: string): string => text.replace(MARKER_IN_TEXT, '').trim()
+
+/**
+ * What a reader looked for when it found no section `key`: `(looked for "### A", "### B" or <!-- jh: key -->)`, the
+ * heading of `language` first. `level` is the heading marks the reader accepts (`##` or `###`).
+ */
+export const lookedForSection = (key: SectionKey, level: '##' | '###', language: PlanLanguage): string => {
+  const headings = languagesFrom(language).map((candidate) => `"${level} ${headingOfSection(key, candidate)}"`)
+  return `(looked for ${headings.join(', ')} or <!-- jh: ${key} -->)`
+}
+
+/** Whether `text` carries the marker `key` or contains one of `words`: a state a cell names in any language. */
+export const namesState = (text: string, key: CellKey, words: readonly string[]): boolean =>
+  markedKeyOf(text) === key || words.some((word) => text.includes(word))
+
+export const SECTION_HEADING = /^##\s+(.*?)\s*$/
+
+const markerKey = (line: string | undefined): SectionKey | null => {
+  const key = line === undefined ? undefined : MARKER.exec(line)?.[1]
+  return key !== undefined && isSectionKey(key) ? key : null
+}
+
+type HeadingMatch = { pattern: RegExp; matches: (text: string, heading: string) => boolean }
+
+const SECTION_MATCH: HeadingMatch = { pattern: SECTION_HEADING, matches: (text, heading) => text === heading }
+const SUBSECTION_MATCH: HeadingMatch = {
+  pattern: /^(#{2,4})\s+(.*?)\s*$/,
+  matches: (text, heading) => text.startsWith(heading),
+}
+
+const headingText = (line: string, { pattern }: HeadingMatch): string | undefined => pattern.exec(line)?.at(-1)
+
+const headingIndexOf = (lines: string[], key: SectionKey, language: PlanLanguage, match: HeadingMatch): number => {
+  const marked = lines.findIndex((line, index) => match.pattern.test(line) && markerKey(lines[index + 1]) === key)
+  if (marked !== -1) return marked
+  for (const candidate of languagesFrom(language)) {
+    const heading = headingOfSection(key, candidate)
+    const found = lines.findIndex((line) => {
+      const text = headingText(line, match)
+      return text !== undefined && match.matches(text, heading)
+    })
+    if (found !== -1) return found
+  }
+  return -1
+}
+
+/**
+ * The index of the line after the level-2 heading that names the section `key`; -1 when none does. A heading names it by the
+ * marker `<!-- jh: <key> -->` on the line directly under it (any language), else by the text of `language`, else by the
+ * text of any other known language. The marker line itself is not part of the section.
+ */
+export const findSectionStart = (markdown: string, key: SectionKey, language: PlanLanguage): number => {
+  const lines = markdown.split('\n')
+  const heading = headingIndexOf(lines, key, language, SECTION_MATCH)
+  if (heading === -1) return -1
+  return heading + (markerKey(lines[heading + 1]) === key ? 2 : 1)
+}
+
+/** The 0-based index of the level-2 heading that names the section `key`, found as `findSectionStart` finds it; -1 when none does. */
+export const findSectionHeading = (markdown: string, key: SectionKey, language: PlanLanguage): number =>
+  headingIndexOf(markdown.split('\n'), key, language, SECTION_MATCH)
+
+const untilNextSection = (rest: string[]): string[] => {
+  const end = rest.findIndex((line) => SECTION_END.test(line))
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+/** The lines of the section `key` names (see `findSectionStart`), up to the next level-2 heading; empty when none does. */
+export const findSection = (markdown: string, key: SectionKey, language: PlanLanguage): string[] => {
+  const start = findSectionStart(markdown, key, language)
+  return start === -1 ? [] : untilNextSection(markdown.split('\n').slice(start))
+}
+
+/**
+ * The position of the column `key` names among the header cells; -1 when none does. A cell names it by the marker
+ * `<!-- jh: <key> -->` (any language), else by a header name of `language`, else by one of any other known language.
+ */
+export const columnIndex = (header: string[], key: ColumnKey, language: PlanLanguage): number => {
+  const marked = header.findIndex((cell) => markedKeyOf(cell) === key)
+  if (marked !== -1) return marked
+  const names = header.map(withoutMarker)
+  for (const candidate of languagesFrom(language)) {
+    for (const word of columnWords(key, candidate)) {
+      const found = names.indexOf(word)
+      if (found !== -1) return found
+    }
+  }
+  return -1
+}
+
+const exactSectionStart = (markdown: string, headingTextValue: string): number => {
+  const heading = new RegExp(`^##\\s+${escapeRegExp(headingTextValue)}\\s*$`)
   const start = markdown.split('\n').findIndex((line) => heading.test(line))
   return start === -1 ? -1 : start + 1
 }
 
-/** The lines under a level-2 heading with exactly this text, up to the next level-2 heading. */
+/** The index of the line after a level-2 heading with exactly this text, or after the one that names the same section in another language or by marker; -1 when there is none. */
+export const sectionStart = (markdown: string, headingText: string): number => {
+  const section = sectionOfHeading(headingText)
+  return section === null
+    ? exactSectionStart(markdown, headingText)
+    : findSectionStart(markdown, section.key, section.language)
+}
+
+/** The lines under that heading (see `sectionStart`), up to the next level-2 heading. */
 export const sectionLines = (markdown: string, headingText: string): string[] => {
   const start = sectionStart(markdown, headingText)
-  if (start === -1) return []
-  const rest = markdown.split('\n').slice(start)
-  const end = rest.findIndex((line) => SECTION_END.test(line))
-  return end === -1 ? rest : rest.slice(0, end)
+  return start === -1 ? [] : untilNextSection(markdown.split('\n').slice(start))
 }
 
 const tableCells = (line: string): string[] =>
@@ -57,8 +169,11 @@ export const firstHeading = (markdown: string, fallback: string): string =>
 const HEADING = /^(#{2,4})\s+(.*?)\s*$/
 
 /** The 0-based line index of the first level 2 to 4 heading whose text starts with `headingText` (a suffix such as `(PFLICHT ab 3 Phasen)` is allowed); -1 when there is none. */
-export const subsectionStart = (markdown: string, headingText: string): number =>
-  markdown.split('\n').findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+export const subsectionStart = (markdown: string, headingText: string): number => {
+  const section = sectionOfHeading(headingText)
+  if (section !== null) return headingIndexOf(markdown.split('\n'), section.key, section.language, SUBSECTION_MATCH)
+  return markdown.split('\n').findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+}
 
 /** The lines under that heading (see `subsectionStart`), up to the next heading of the same or a higher level. */
 export const subsectionLines = (markdown: string, headingText: string): string[] => {

package/src/plan-format/open-status.ts

@@ -0,0 +1,15 @@
+import { isStatusKey, STATUS_KEY } from '../vocabulary'
+import { markedKeyOf, withoutMarker } from './markdown'
+
+/**
+ * Whether a status cell of a board row says the row is still open. A status marker decides (`<!-- jh: status-open -->`
+ * is open, any other status marker is not); else an empty cell is open (a row nobody closed is not dropped in
+ * silence), and so is a cell that starts with one of the lower-case `openWords`. The words come from every known
+ * language, so a board need not match the configured one.
+ */
+export const isOpenStatus = (status: string, openWords: readonly string[]): boolean => {
+  const marked = markedKeyOf(status)
+  if (marked !== null && isStatusKey(marked)) return marked === STATUS_KEY.open
+  const lower = withoutMarker(status).toLowerCase()
+  return lower === '' || openWords.some((word) => lower.startsWith(word))
+}

package/src/plan-format/phases.ts

@@ -1,6 +1,6 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { LINE_KEY, languagesFrom, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
 import { PHASE_ID_PREFIX } from './lanes'
-import { escapeRegExp } from './markdown'
+import { escapeRegExp, markedKeyOf, withoutMarker } from './markdown'
 import { terminalSafe } from './terminal-text'
 
 /** A checkbox of a plan. `gate` is set on the ones listed under the phase's review gate, and only on those. */
@@ -29,11 +29,13 @@ export type PhaseWorkFields = {
 /**
  * `work` is set by the phase source and says nothing for a phase the worktree left as the base has it; a merged phase
  * is touched as well. `deferred` holds the checkboxes moved to another phase; they are not among `items`, so they
- * count neither as open nor as done.
+ * count neither as open nor as done. `purpose` is the sentence of the purpose line directly under a `### Phase`
+ * heading (`phasePurposeOf`); absent when the phase has none.
  */
 export type PlanPhase = {
   id: string
   title: string
+  purpose?: string
   items: ChecklistItem[]
   deferred?: DeferredItem[]
 } & Partial<PhaseWorkFields>
@@ -72,6 +74,30 @@ export const isOpenCheckboxLine = (line: string): boolean => line.match(CHECKBOX
 export const phaseHeadingPattern = (language: PlanLanguage): RegExp =>
   new RegExp(`^###\\s+${escapeRegExp(PLAN_VOCABULARY[language].phase)}\\s+(\\d+[a-z]?)\\b\\s*[:—–-]?\\s*(.*)$`, 'i')
 
+/** The bold opening of a line (`**Label:**` or `**Label**:`): the label and the text after it. */
+export const BOLD_OPENING = /^\s*\*\*([^*]+?)\s*:?\*\*\s*:?\s*(.*)$/
+
+/** Whether the bold `label` of `line` names the purpose line: by the marker on the line, else by the word of `language`, else by that of any other known language. */
+const namesPurpose = (line: string, label: string, language: PlanLanguage): boolean => {
+  if (markedKeyOf(line) === LINE_KEY.purpose) return true
+  const written = label.trim().toLowerCase()
+  return languagesFrom(language).some((candidate) => PLAN_VOCABULARY[candidate].phasePurpose.toLowerCase() === written)
+}
+
+/**
+ * The sentence of a purpose line, `**Worum es geht:** <sentence>`, the colon inside or outside the bold; null for any
+ * other line and for a purpose line without text after the colon.
+ */
+export const phasePurposeOf = (line: string, language: PlanLanguage): string | null => {
+  const opening = BOLD_OPENING.exec(line)
+  if (!opening || !namesPurpose(line, opening[1], language)) return null
+  const text = terminalSafe(withoutMarker(opening[2])).trim()
+  return text === '' ? null : text
+}
+
+/** The first non-empty line under a heading decides whether a phase has its purpose line; once `decided`, later lines never do. */
+export const decidesPurpose = (decided: boolean, line: string): boolean => !decided && line.trim() !== ''
+
 const tableCells = (line: string): string[] | null => {
   const trimmed = line.trim()
   if (!trimmed.startsWith('|')) return null
@@ -220,6 +246,14 @@ const notePointer = (pointers: Map<PlanPhase, string>, phase: PlanPhase | null,
   if (phase && pointer) pointers.set(phase, pointer)
 }
 
+/** Reads the first non-empty line under a `### Phase` heading as the phase's purpose; later lines and `## N —` sections never are. */
+const notePurpose = (read: Set<PlanPhase>, phase: PlanPhase | null, line: string, language: PlanLanguage): void => {
+  if (!phase || !decidesPurpose(read.has(phase), line)) return
+  read.add(phase)
+  const purpose = phasePurposeOf(line, language)
+  if (purpose !== null) phase.purpose = purpose
+}
+
 const headingOf = (line: string, phaseHeading: RegExp): RegExpMatchArray | null =>
   line.match(phaseHeading) ?? line.match(NUMBERED_SECTION)
 
@@ -244,15 +278,22 @@ export const phaseHeadings = (markdown: string, language: PlanLanguage): PhaseHe
 export const parsePlanPhases = (markdown: string, language: PlanLanguage): PlanPhase[] => {
   const phaseHeading = phaseHeadingPattern(language)
   const pointers = new Map<PlanPhase, string>()
+  const purposeRead = new Set<PlanPhase>()
   const { phases } = markdown.split('\n').reduce<{ phases: PlanPhase[]; open: PlanPhase | null; gate: boolean }>(
     ({ phases, open, gate }, line) => {
       const heading = headingOf(line, phaseHeading)
       if (heading) {
-        const phase = { id: (heading[1] ?? '').toLowerCase(), title: terminalSafe(heading[2] ?? '').trim(), items: [] }
+        const phase: PlanPhase = {
+          id: (heading[1] ?? '').toLowerCase(),
+          title: terminalSafe(heading[2] ?? '').trim(),
+          items: [],
+        }
+        if (!phaseHeading.test(line)) purposeRead.add(phase)
         return { phases: [...phases, phase], open: phase, gate: false }
       }
       if (PHASE_END.test(line)) return { phases, open: null, gate: false }
       const inGate = gate || REVIEW_GATE.test(line)
+      notePurpose(purposeRead, open, line, language)
       if (open) fileLine(open, line, inGate)
       notePointer(pointers, open, line)
       return { phases, open, gate: inGate }

package/src/plan-format/plan-head.ts

@@ -1,5 +1,13 @@
-import { HEAD_LINE, type HeadLine, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { escapeRegExp } from './markdown'
+import {
+  HEAD_KEY,
+  HEAD_LINE,
+  type HeadLine,
+  languagesFrom,
+  PLAN_VOCABULARY,
+  type PlanLanguage,
+  SECTION_KEY,
+} from '../vocabulary'
+import { escapeRegExp, findSectionHeading, lookedForSection, markedKeyOf, withoutMarker } from './markdown'
 import { parsePlanPhases } from './phases'
 
 /** What a plan holds of its head: all of it and current, none of it, or something that no longer matches the plan. */
@@ -38,12 +46,21 @@ const HEAD_LINES = Object.values(HEAD_LINE)
 
 const labelOf = (language: PlanLanguage, line: HeadLine): string => PLAN_VOCABULARY[language].head[line].toLowerCase()
 
+/** The head line a label names: by the marker on the line, else by the label of `language`, else by that of any other known language. */
+const labelNamed = (text: string, written: string, language: PlanLanguage): HeadLine | undefined => {
+  const marked = markedKeyOf(text)
+  const byMarker = HEAD_LINES.find((each) => HEAD_KEY[each] === marked)
+  if (byMarker) return byMarker
+  return languagesFrom(language)
+    .map((candidate) => HEAD_LINES.find((each) => labelOf(candidate, each) === written))
+    .find((each) => each !== undefined)
+}
+
 const entryOf = (text: string, language: PlanLanguage): { label: HeadLine; text: string } | null => {
   const match = text.match(HEAD_ENTRY)
   if (!match) return null
-  const written = match[1].trim().toLowerCase()
-  const label = HEAD_LINES.find((each) => labelOf(language, each) === written)
-  return label ? { label, text: match[2].trim() } : null
+  const label = labelNamed(text, match[1].trim().toLowerCase(), language)
+  return label ? { label, text: withoutMarker(match[2]) } : null
 }
 
 const phaseOf = (statusText: string | undefined, language: PlanLanguage): HeadPhase | null => {
@@ -59,8 +76,7 @@ const phaseOf = (statusText: string | undefined, language: PlanLanguage): HeadPh
  */
 export const parsePlanHead = (markdown: string, language: PlanLanguage): PlanHead | null => {
   const lines = markdown.split('\n')
-  const heading = new RegExp(`^##\\s+${escapeRegExp(PLAN_VOCABULARY[language].sections.forYou)}\\s*$`)
-  const start = lines.findIndex((text) => heading.test(text))
+  const start = findSectionHeading(markdown, SECTION_KEY.forYou, language)
   if (start === -1) return null
   const rest = lines.slice(start + 1)
   const end = rest.findIndex((text) => SECTION_HEADING.test(text))
@@ -107,8 +123,14 @@ const phaseMismatch = ({ current, total }: HeadPhase, states: readonly PhaseStat
  */
 export const checkPlanHead = (markdown: string, language: PlanLanguage): HeadVerdict => {
   const head = parsePlanHead(markdown, language)
-  const { sections } = PLAN_VOCABULARY[language]
-  if (head === null) return verdict(HEAD_STATUS.missing, null, `no \`## ${sections.forYou}\` section`)
+  if (head === null) {
+    const looked = lookedForSection(SECTION_KEY.forYou, '##', language)
+    return verdict(
+      HEAD_STATUS.missing,
+      null,
+      `no \`## ${PLAN_VOCABULARY[language].sections.forYou}\` section ${looked}`,
+    )
+  }
   if (head.misplaced)
     return verdict(
       HEAD_STATUS.stale,