jackherd 1.24.0 → 1.25.0

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,

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

@@ -1,7 +1,9 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { LINE_KEY, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
 import { changedOpenLaneRows, type OpenLaneRow, phaseIdsOfCell } from './lanes'
-import { escapeRegExp, sectionLines } from './markdown'
+import { escapeRegExp, markedKeyOf, sectionLines } from './markdown'
 import {
+  BOLD_OPENING,
+  decidesPurpose,
   deferralTarget,
   endsPhase,
   isCheckboxLine,
@@ -11,6 +13,7 @@ import {
   type PlanPhase,
   parsePlanPhases,
   phaseHeadingPattern,
+  phasePurposeOf,
 } from './phases'
 import { terminalSafe } from './terminal-text'
 
@@ -26,10 +29,21 @@ export type PhaseWithOpenBoxes = PhaseWithoutGate & { openLines: number[] }
 /** A `PhaseWithOpenBoxes` whose tasks are all ticked on the base branch. */
 export type MergedPhaseWithOpenBoxes = PhaseWithOpenBoxes
 
-type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; openLines: number[] }
+/** A `### Phase` heading (1-based line) whose section has tasks and no purpose line directly under the heading. */
+export type PhaseWithoutPurpose = PhaseHeading
 
-const noGatePattern = (language: PlanLanguage): RegExp =>
-  new RegExp(`^\\s*\\*\\*${escapeRegExp(PLAN_VOCABULARY[language].noReviewGate)}\\b`, 'i')
+type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; purpose: boolean | null; openLines: number[] }
+
+const NO_GATE_WORDS = new RegExp(
+  `^\\s*\\*\\*(?:${Object.values(PLAN_VOCABULARY)
+    .map(({ noReviewGate }) => escapeRegExp(noReviewGate))
+    .join('|')})\\b`,
+  'i',
+)
+
+/** The line by which a phase says it has no review gate on purpose: a bold opening with the words of any known language, or with the marker. */
+const isNoGateLine = (line: string): boolean =>
+  NO_GATE_WORDS.test(line) || (BOLD_OPENING.test(line) && markedKeyOf(line) === LINE_KEY.noReviewGate)
 
 const tickCount = (phase: PlanPhase): number => phase.items.filter((item) => item.done).length
 
@@ -39,10 +53,13 @@ const tasksDone = (phase: PlanPhase): boolean => {
   return tasks.length > 0 && tasks.every((item) => item.done)
 }
 
+const settlePurpose = (section: PhaseSection, line: string, language: PlanLanguage): void => {
+  if (decidesPurpose(section.purpose !== null, line)) section.purpose = phasePurposeOf(line, language) !== null
+}
+
 /** Every `### Phase` section with whether it has tasks and whether it has a gate or says why it has none. */
 const phaseSections = (markdown: string, language: PlanLanguage): PhaseSection[] => {
   const heading = phaseHeadingPattern(language)
-  const noGate = noGatePattern(language)
   const sections: PhaseSection[] = []
   let open: PhaseSection | null = null
   for (const [index, line] of markdown.split('\n').entries()) {
@@ -54,14 +71,16 @@ const phaseSections = (markdown: string, language: PlanLanguage): PhaseSection[]
         title: terminalSafe(match[2]).trim(),
         tasks: false,
         gate: false,
+        purpose: null,
         openLines: [],
       }
       sections.push(open)
     } else if (endsPhase(line)) {
       open = null
     } else if (open) {
+      settlePurpose(open, line, language)
       open.tasks ||= isCheckboxLine(line)
-      open.gate ||= isReviewGateLine(line) || noGate.test(line)
+      open.gate ||= isReviewGateLine(line) || isNoGateLine(line)
       if (isOpenCheckboxLine(line) && deferralTarget(line, open.id) === null) open.openLines.push(index + 1)
     }
   }
@@ -87,6 +106,23 @@ export const newPhasesWithoutReviewGate = (
     .filter(({ id, tasks, gate }) => tasks && !gate && !previousIds.has(id))
     .map(({ line, id, title }) => ({ line, id, title }))
 
+/**
+ * The phases a plan gained against `previousIds` that have checkboxes and no purpose line as the first non-empty line
+ * under the heading (`phasePurposeOf`). Phases the plan already had are not read, like in `newPhasesWithoutReviewGate`.
+ */
+export const newPhasesWithoutPurpose = (
+  markdown: string,
+  language: PlanLanguage,
+  previousIds: ReadonlySet<string>,
+): PhaseWithoutPurpose[] =>
+  phaseSections(markdown, language)
+    .filter(({ id, tasks, purpose }) => tasks && !purpose && !previousIds.has(id))
+    .map(({ line, id, title }) => ({ line, id, title }))
+
+/** Every phase of the plan with tasks and without a purpose line: for a plan read whole, where no phase is older than the change. */
+export const phasesWithoutPurpose = (markdown: string, language: PlanLanguage): PhaseWithoutPurpose[] =>
+  newPhasesWithoutPurpose(markdown, language, new Set())
+
 /** Whether the document has a lanes table (`## Spuren`): a board, not a plan. */
 export const hasLanesTable = (markdown: string, language: PlanLanguage): boolean =>
   sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes).some((line) => line.startsWith('|'))

package/src/plan-format/progress.ts

@@ -8,6 +8,8 @@ import { type ChecklistItem, type DeferredItem, type PhaseWorkFields, type PlanP
 export type PhaseProgress = {
   id: string
   title: string | null
+  /** The phase's purpose sentence; absent when the plan has none or lacks the phase. */
+  purpose?: string
   done: number
   total: number
   items: ChecklistItem[]
@@ -46,6 +48,7 @@ export const phaseProgress = (phases: readonly PlanPhase[], id: string): PhasePr
     done: items.filter((item) => item.done).length,
     total: items.length,
     items,
+    ...(phase?.purpose ? { purpose: phase.purpose } : {}),
     ...(phase?.deferred ? { deferred: phase.deferred } : {}),
     ...(phase?.work ? phaseWorkFields(phase.work) : {}),
   }

package/src/plan-format/sprint-document.ts

@@ -1,5 +1,5 @@
-import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { allTables, firstTableWithHeader, sectionLines, subsectionLines } from './markdown'
+import { COLUMN_KEY, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { allTables, columnIndex, firstTableWithHeader, sectionLines, subsectionLines } from './markdown'
 
 const PHASE_ID_IN_CELL = /^(\d+[a-z]?)\b/
 
@@ -57,9 +57,9 @@ export const readSprintDocument = (markdown: string, language: PlanLanguage): Sp
  * first cell of a row starts with the id (`3 — Sync-Engine`); a plan without the table gives an empty map.
  */
 export const readPhaseDependencies = (planMarkdown: string, language: PlanLanguage): Record<string, string> => {
-  const { sections, columns } = PLAN_VOCABULARY[language]
+  const { sections } = PLAN_VOCABULARY[language]
   const { header, rows } = firstTableWithHeader(subsectionLines(planMarkdown, sections.dependencies))
-  const column = header.indexOf(columns.dependsOn)
+  const column = columnIndex(header, COLUMN_KEY.dependsOn, language)
   if (column === -1) return {}
   const entries = rows.flatMap((cells) => {
     const id = PHASE_ID_IN_CELL.exec(cells[0] ?? '')?.[1]