jackherd 0.0.1 → 1.0.1

package/src/plan-format/drift.ts

@@ -0,0 +1,69 @@
+import type { PlanLanguage } from '../vocabulary'
+import { PLAN_VOCABULARY } from '../vocabulary'
+import { escapeRegExp } from './markdown'
+
+export type DriftFinding = { file: string; reason: string }
+
+type DriftWords = {
+  /** `Status:` lines starting with one of these describe a plan in flight, where open items are expected. */
+  inFlight: RegExp
+  completion: RegExp
+  open: RegExp
+  architecture: RegExp
+  /** Level 2-4 heading words that mark the architecture documentation closing phase. */
+  architectureHeading: string
+  selfReported: (statusText: string) => string
+  silent: string
+}
+
+const OPEN_TABLE_CELL = /⬜/
+
+const DRIFT_WORDS: Record<PlanLanguage, DriftWords> = {
+  de: {
+    inFlight: /^(Draft|In Progress|Proposed|Open|Planned|Review-Ready|Aktiv)\b/i,
+    completion: /\b(done|abgeschlossen|umgesetzt|implementiert|implemented|fertig)\b/i,
+    open: /\b(offen|ausstehend|deferred|zurückgestellt)\b/i,
+    architecture: /\b(arc42|ADR|Architekturdokumentation|Dokumentation)\b/i,
+    architectureHeading: 'Architekturdokumentation',
+    selfReported: (statusText) => `Status nennt offene Doku-Arbeit: "${statusText.trim()}"`,
+    silent: 'arc42-Abschlussphase hat offene ⬜-Zeilen trotz abgeschlossenem Status',
+  },
+  en: {
+    inFlight: /^(Draft|In Progress|Proposed|Open|Planned|Review-Ready|Active)\b/i,
+    completion: /\b(done|completed|implemented|finished)\b/i,
+    open: /\b(open|outstanding|pending|deferred)\b/i,
+    architecture: /\b(arc42|ADR|architecture documentation|documentation)\b/i,
+    architectureHeading: 'Architecture documentation',
+    selfReported: (statusText) => `Status names open documentation work: "${statusText.trim()}"`,
+    silent: 'The arc42 closing phase has open ⬜ rows despite a completed status',
+  },
+}
+
+// Single line on purpose: the drift check always read only the first line of the field, and the
+// 270-plan parity run depends on it. `headerField` follows soft wraps and would classify some plans differently.
+const statusLine = (content: string, name: string): string | undefined =>
+  content.match(new RegExp(`^\\*\\*${escapeRegExp(name)}:\\*\\*\\s*(.+)$`, 'm'))?.[1]
+
+const architectureSection = (content: string, heading: string): string | undefined =>
+  content.match(new RegExp(`#{2,4}[^\\n]*${escapeRegExp(heading)}[^\\n]*\\n([\\s\\S]*?)(?=\\n#{1,4} |$)`))?.[1]
+
+/**
+ * Plans whose own status text or closing documentation phase admits unfinished architecture work.
+ * Plans in flight are skipped: open items there are expected, not drift.
+ */
+export const findDrift = (file: string, content: string, language: PlanLanguage): DriftFinding[] => {
+  const statusText = statusLine(content, PLAN_VOCABULARY[language].header.status)
+  const words = DRIFT_WORDS[language]
+  if (!statusText || words.inFlight.test(statusText.trim())) return []
+
+  const completed = words.completion.test(statusText)
+  const caveat = words.open.test(statusText)
+  const selfReported =
+    completed && caveat && words.architecture.test(statusText) ? words.selfReported(statusText) : null
+  const section = completed && !caveat ? architectureSection(content, words.architectureHeading) : undefined
+  const silent = section && OPEN_TABLE_CELL.test(section) ? words.silent : null
+
+  return [selfReported, silent]
+    .filter((reason): reason is string => reason !== null)
+    .map((reason) => ({ file, reason }))
+}

package/src/plan-format/header.ts

@@ -0,0 +1,27 @@
+import { classifyStatus, PLAN_VOCABULARY, type PlanLanguage, type PlanStatus } from '../vocabulary'
+import { firstHeading, headerField } from './markdown'
+
+export type PlanHeader = {
+  title: string
+  date: string
+  status: string
+  statusWord: PlanStatus
+  scope: string
+}
+
+const DECISION_ROW = /^\|\s*\*?\*?D\d+/gm
+
+export const readPlanHeader = (markdown: string, language: PlanLanguage, fallbackTitle: string): PlanHeader => {
+  const { header } = PLAN_VOCABULARY[language]
+  const status = headerField(markdown, header.status)
+  return {
+    title: firstHeading(markdown, fallbackTitle),
+    date: headerField(markdown, header.date),
+    status,
+    statusWord: classifyStatus(language, status),
+    scope: headerField(markdown, header.scope),
+  }
+}
+
+/** Rows of the decision table, counted by their `D<number>` first cell. */
+export const countDecisions = (markdown: string): number => (markdown.match(DECISION_ROW) ?? []).length

package/src/plan-format/index.ts

@@ -0,0 +1,9 @@
+export * from '../vocabulary'
+export * from './drift'
+export * from './header'
+export * from './lanes'
+export * from './phase-tally'
+export * from './phases'
+export * from './plan-structure'
+export * from './progress'
+export * from './sprint-document'

package/src/plan-format/lanes.ts

@@ -0,0 +1,128 @@
+import { posix } from 'node:path'
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { firstHeading, firstTable, sectionLines } from './markdown'
+
+/**
+ * `namedPhaseIds` holds every id the row names when `withoutRepeats` dropped some because an earlier row of the lane
+ * named them; `withoutRow` marks a step no board row wrote: the phases a lane worked on without a row of their own.
+ */
+export type PlanStep = {
+  planTitle: string
+  planHref: string | null
+  phaseIds: string[]
+  label: string
+  startsAfter: string
+  model: string
+  namedPhaseIds?: string[]
+  withoutRow?: true
+}
+
+/** A lane of the sprint table; `closed` when its name cell says the lane was cleaned up. */
+export type SprintLane = { name: string; port: number | null; steps: PlanStep[]; closed: boolean }
+
+const LANE_NAME = /`([^`]+)`/
+const CONTINUATION = '↳'
+const PLAN_LINK = /\[([^\]]+)\]\(([^)]+)\)/
+/** Sprint tables name a phase `P4`; the sidebar title prints it the same way. */
+export const PHASE_ID_PREFIX = 'P'
+
+const CLAUSE_SEPARATOR = /([;,]|\.(?=\s))\s*/
+const ENTRY_END = new Set([';', '.'])
+
+type PhaseIdPatterns = { leading: RegExp; afterConnector: RegExp; connector: RegExp }
+
+const phaseIdPatterns = (language: PlanLanguage): PhaseIdPatterns => {
+  const connectors = PLAN_VOCABULARY[language].phaseConnectors.join('|')
+  const id = `(?:\\*\\*)?${PHASE_ID_PREFIX}(\\d+[a-z]?)\\b`
+  return {
+    leading: new RegExp(`^\\s*(?:(?:${connectors})\\s+)*${id}`),
+    afterConnector: new RegExp(`^\\s*(?:${connectors})\\s`),
+    connector: new RegExp(`\\b(?:${connectors})\\s+${id}`, 'g'),
+  }
+}
+
+/**
+ * The phase ids of a phases cell. An id counts where an entry starts: at the start of the cell or of a
+ * sentence, after `;`, after a connector word (`P1 Index und P2 Suche`), or after `,` while a list that began
+ * with an id is running (`P1 (#<number>), P2 (#<number>)`). A `P6` inside a sentence (`geht in P6 auf`, `abgeräumt,
+ * P6 startet neu`) is prose.
+ */
+const phaseIdsOf = (cell: string, patterns: PhaseIdPatterns): string[] => {
+  const parts = cell.split(CLAUSE_SEPARATOR)
+  const ids: string[] = []
+  let listRunning = false
+  for (let index = 0; index < parts.length; index += 2) {
+    const separator = index > 0 ? parts[index - 1] : null
+    const clause = parts[index]
+    const entryStart = separator === null || ENTRY_END.has(separator)
+    if (entryStart) listRunning = false
+    const leading = clause.match(patterns.leading)
+    const startsEntry: boolean = entryStart || listRunning || patterns.afterConnector.test(clause)
+    const counts: boolean = leading !== null && startsEntry
+    if (leading && counts) ids.push(leading[1])
+    ids.push(...[...clause.matchAll(patterns.connector)].map((match) => match[1]))
+    listRunning ||= counts
+  }
+  return [...new Set(ids)]
+}
+
+/** The phase ids a phases cell of the lanes table names, read as `parseSprintLanes` reads them. */
+export const phaseIdsOfCell = (cell: string, language: PlanLanguage): string[] =>
+  phaseIdsOf(cell, phaseIdPatterns(language))
+
+export const laneNameOf = (cell: string, previous: string | null): string | null =>
+  cell.match(LANE_NAME)?.[1] ?? (cell.startsWith(CONTINUATION) ? previous : null)
+
+const toStep = (
+  [, , plan = '', phases = '', startsAfter = '', model = '']: string[],
+  phaseId: PhaseIdPatterns,
+): PlanStep => {
+  const link = plan.match(PLAN_LINK)
+  return {
+    planTitle: link ? link[1] : plan,
+    planHref: link ? link[2] : null,
+    phaseIds: phaseIdsOf(phases, phaseId),
+    label: phases,
+    startsAfter,
+    model,
+  }
+}
+
+/** The step without the phases an earlier step of the lane already named from the same plan, which `namedPhaseIds` keeps. */
+export const withoutRepeats = (lane: SprintLane, step: PlanStep): PlanStep => {
+  const named = new Set(
+    lane.steps.filter((earlier) => earlier.planHref === step.planHref).flatMap((earlier) => earlier.phaseIds),
+  )
+  const phaseIds = step.phaseIds.filter((id) => !named.has(id))
+  if (phaseIds.length === step.phaseIds.length) return step
+  return { ...step, phaseIds, namedPhaseIds: step.namedPhaseIds ?? step.phaseIds }
+}
+
+/**
+ * The lanes of the sprint document's lanes table (`## Spuren` in `de`) in table order. A row whose
+ * first cell names a lane in backticks belongs to that lane; a `↳` row without a name continues
+ * the lane above it.
+ */
+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 }
+    lane.closed ||= (cells[0] ?? '').includes(laneClosed)
+    lane.steps.push(withoutRepeats(lane, toStep(cells, phaseId)))
+    lanes.set(name, lane)
+    previous = name
+  }
+  return [...lanes.values()]
+}
+
+export const sprintTitleOf = (markdown: string, fallback: string): string => firstHeading(markdown, fallback)
+
+/** The repository path of a plan link, relative to the sprint document's directory. */
+export const resolvePlanPath = (sprintDirectory: string, href: string): string =>
+  posix.normalize(posix.join(sprintDirectory, href.split('#')[0]))

package/src/plan-format/markdown.ts

@@ -0,0 +1,98 @@
+import { terminalSafe } from './terminal-text'
+
+const SECTION_END = /^##\s/
+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 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. */
+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)
+}
+
+const tableCells = (line: string): string[] =>
+  line
+    .slice(1, line.endsWith('|') ? -1 : undefined)
+    .split('|')
+    .map((cell) => terminalSafe(cell).trim())
+
+/** A body row of a table: its index among the lines it was read from, the line as written, and its cells. */
+export type TableRow = { index: number; line: string; cells: string[] }
+
+/** Body rows of the first table among `lines` with their index, header and separator dropped, cells trimmed and terminal-safe. */
+export const firstTableRows = (lines: string[]): TableRow[] => {
+  const start = lines.findIndex((line) => line.startsWith('|'))
+  if (start === -1) return []
+  const rest = lines.slice(start)
+  const end = rest.findIndex((line) => !line.startsWith('|'))
+  return (end === -1 ? rest : rest.slice(0, end))
+    .map((line, offset) => ({ index: start + offset, line, cells: tableCells(line) }))
+    .slice(1)
+    .filter(({ line }) => !TABLE_SEPARATOR.test(line))
+}
+
+/** Body rows of the first table among `lines`, header and separator dropped, cells trimmed and terminal-safe. */
+export const firstTable = (lines: string[]): string[][] => firstTableRows(lines).map(({ cells }) => cells)
+
+/** Value of a `**Name:** value` header line; continues over soft-wrapped lines until the next field or blank line. */
+export const headerField = (markdown: string, name: string): string => {
+  const match = new RegExp(`^\\*\\*${escapeRegExp(name)}:\\*\\*\\s*(.+?)(?=\\n\\*\\*|\\n\\n)`, 'ms').exec(markdown)
+  return match ? match[1].replace(/\s+/g, ' ').trim() : ''
+}
+
+export const firstHeading = (markdown: string, fallback: string): string =>
+  terminalSafe(markdown.match(/^#\s+(.+)$/m)?.[1] ?? fallback).trim()
+
+const HEADING = /^(#{2,4})\s+(.*?)\s*$/
+
+/**
+ * The lines under the first level 2 to 4 heading whose text starts with `headingText` (a suffix such as
+ * `(PFLICHT ab 3 Phasen)` is allowed), up to the next heading of the same or a higher level.
+ */
+export const subsectionLines = (markdown: string, headingText: string): string[] => {
+  const lines = markdown.split('\n')
+  const start = lines.findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+  if (start === -1) return []
+  const level = HEADING.exec(lines[start])?.[1].length ?? 2
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => {
+    const heading = HEADING.exec(line)
+    return heading !== null && heading[1].length <= level
+  })
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+/** The header cells and the body rows of the first table among `lines`. */
+export const firstTableWithHeader = (lines: string[]): { header: string[]; rows: string[][] } => {
+  const start = lines.findIndex((line) => line.startsWith('|'))
+  if (start === -1) return { header: [], rows: [] }
+  return { header: tableCells(lines[start]), rows: firstTable(lines) }
+}
+
+export type TableWithCaption = { caption: string | null; header: string[]; rows: string[][] }
+
+/** Every table among `lines` with its header cells and body rows, and the paragraph line right above it as its caption. */
+export const allTables = (lines: string[]): TableWithCaption[] => {
+  const tables: TableWithCaption[] = []
+  for (let index = 0; index < lines.length; index += 1) {
+    if (!lines[index].startsWith('|') || (index > 0 && lines[index - 1].startsWith('|'))) continue
+    const above = lines
+      .slice(0, index)
+      .reverse()
+      .find((line) => line.trim() !== '')
+    const caption = above && !above.startsWith('|') ? above.trim() : null
+    tables.push({ caption, ...firstTableWithHeader(lines.slice(index)) })
+  }
+  return tables
+}

package/src/plan-format/phase-tally.ts

@@ -0,0 +1,55 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { escapeRegExp } from './markdown'
+import { deferralTarget } from './phases'
+
+/** Per heading that carries checkboxes or table status cells: how many are done and open. */
+export type PhaseTally = { title: string; done: number; open: number; model: string | undefined }
+
+/** A tally with the id of its phase and the targets of the checkboxes it defers. */
+type Section = PhaseTally & { phaseId: string; targets: string[] }
+
+const DONE_MARK = /^\s*[-*]\s\[x\]|\|\s*✅\s*\|/gim
+const OPEN_MARK = /^\s*[-*]\s\[ \]|\|\s*⬜\s*\|/gm
+const TRAILING_SEPARATOR = /[:—–-]\s*$/
+
+const PHASE_ID = /^(\d+[a-z]?)/
+
+const modelFor = (markdown: string, phaseWord: string, phaseTitle: string): string | undefined => {
+  const prefix = new RegExp(`^${escapeRegExp(phaseWord)}\\s*`, 'i')
+  const number = /^(\d+)/.exec(phaseTitle.replace(prefix, ''))?.[1]
+  if (!number) return undefined
+  const row = new RegExp(`^\\|\\s*${number}\\s*[—–-][^|]*\\|\\s*([^|]+?)\\s*\\|`, 'm').exec(markdown)
+  return row?.[1].trim()
+}
+
+const sectionOf = (section: string, heading: RegExp, markdown: string, phaseWord: string): Section | null => {
+  const match = heading.exec(section)
+  if (!match) return null
+  const title = match[1].replace(TRAILING_SEPARATOR, '').trim()
+  const phaseId = PHASE_ID.exec(title)?.[1]?.toLowerCase() ?? ''
+  const targets = section.split('\n').flatMap((line) => deferralTarget(line, phaseId) ?? [])
+  const done = (section.match(DONE_MARK) ?? []).length
+  const open = (section.match(OPEN_MARK) ?? []).length - targets.length
+  return { title, done, open, model: modelFor(markdown, phaseWord, title), phaseId, targets }
+}
+
+/**
+ * Every level-2 or level-3 section whose heading starts with a number (optionally after the phase
+ * word) and that holds at least one checkbox or ✅/⬜ table cell, with the model its recommendation
+ * table names for that phase. An open checkbox moved on with `→ P<n>` counts as open in the section
+ * of phase `<n>` instead of its own; with no such section it stays open where it is, as in `parsePlanPhases`.
+ */
+export const tallyPhases = (markdown: string, language: PlanLanguage): PhaseTally[] => {
+  const phaseWord = PLAN_VOCABULARY[language].phase
+  const heading = new RegExp(`^###?\\s+(?:${escapeRegExp(phaseWord)}\\s*)?(\\d+[^\\n]*)`)
+  const sections = markdown
+    .split(/\n(?=###?\s)/)
+    .flatMap((section) => sectionOf(section, heading, markdown, phaseWord) ?? [])
+  const ids = new Set(sections.map(({ phaseId }) => phaseId))
+  return sections.flatMap(({ phaseId, targets, ...tally }) => {
+    const stranded = targets.filter((target) => !ids.has(target)).length
+    const arriving = sections.flatMap((each) => each.targets).filter((target) => target === phaseId).length
+    const open = tally.open + stranded + arriving
+    return tally.done + open === 0 ? [] : [{ ...tally, open }]
+  })
+}

package/src/plan-format/phases.ts

@@ -0,0 +1,224 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { PHASE_ID_PREFIX } from './lanes'
+import { escapeRegExp } 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. */
+export type ChecklistItem = { done: boolean; text: string; gate?: true }
+
+/** An open checkbox that ends in `→ P<n>`: moved on purpose to phase `target`, its text without the marker. */
+export type DeferredItem = { text: string; target: string }
+
+/** An open checkbox whose phase arrow is not at the end of its line (1-based), with the form the parser reads. */
+export type MisplacedDeferral = { line: number; target: string; corrected: string }
+
+/**
+ * `touched` is set by the phase source when the worktree's ticks differ from the base branch's. `deferred` holds
+ * the checkboxes moved to another phase; they are not among `items`, so they count neither as open nor as done.
+ */
+export type PlanPhase = { id: string; title: string; items: ChecklistItem[]; deferred?: DeferredItem[]; touched?: true }
+
+const REVIEW_GATE = /^\s*\*\*review[- ]gate\b/i
+const PHASE_END = /^#{1,3}\s/
+const CHECKBOX = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/
+const SECTION_HEADING = /^##\s+(.+?)\s*$/
+const TOP_HEADING = /^#\s/
+const TABLE_STATUS = { done: '✅', open: '⬜' } as const
+const ROW_NUMBER = /^\d+(\.\d+)*[a-z]?$/
+const NUMBERED_SECTION = /^##\s+(\d+[a-z]?)\s*[—–:-]\s*(.*)$/
+const SECTION_POINTER = /`##\s+([^`]+?)\s*`/
+const DEFERRED_TO = new RegExp(`\\s→\\s*${PHASE_ID_PREFIX}(\\d+[a-z]?)\\s*$`, 'i')
+/** A phase arrow anywhere in a line, with the whitespace before it. */
+const PHASE_ARROW = new RegExp(`\\s*→\\s*${PHASE_ID_PREFIX}(\\d+[a-z]?)\\b`, 'i')
+
+/** The line that opens a phase's review gate: `**Review-Gate:**`, `**Review gate** (…)`. */
+export const isReviewGateLine = (line: string): boolean => REVIEW_GATE.test(line)
+
+/** A heading of level three or higher, which ends the section of a phase. */
+export const endsPhase = (line: string): boolean => PHASE_END.test(line)
+
+export const isCheckboxLine = (line: string): boolean => CHECKBOX.test(line)
+
+export const isOpenCheckboxLine = (line: string): boolean => line.match(CHECKBOX)?.[1] === ' '
+
+export const phaseHeadingPattern = (language: PlanLanguage): RegExp =>
+  new RegExp(`^###\\s+${escapeRegExp(PLAN_VOCABULARY[language].phase)}\\s+(\\d+[a-z]?)\\b\\s*[:—–-]?\\s*(.*)$`, 'i')
+
+const tableCells = (line: string): string[] | null => {
+  const trimmed = line.trim()
+  if (!trimmed.startsWith('|')) return null
+  return trimmed
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split('|')
+    .map((cell) => cell.trim())
+}
+
+/** A table row with a cell that is exactly ✅ or ⬜: its other cells, minus a leading row number, are the text. */
+const tableItemOf = (line: string): ChecklistItem | null => {
+  const cells = tableCells(line)
+  const statusIndex = cells?.findIndex((cell) => cell === TABLE_STATUS.done || cell === TABLE_STATUS.open) ?? -1
+  if (!cells || statusIndex < 0) return null
+  const rest = cells.filter((_, index) => index !== statusIndex)
+  const text = (ROW_NUMBER.test(rest[0] ?? '') ? rest.slice(1) : rest).filter((cell) => cell !== '').join(' · ')
+  return { done: cells[statusIndex] === TABLE_STATUS.done, text: terminalSafe(text).trim() }
+}
+
+const checkboxItemOf = (line: string): ChecklistItem | null => {
+  const checkbox = line.match(CHECKBOX)
+  return checkbox ? { done: checkbox[1] !== ' ', text: terminalSafe(checkbox[2] ?? '').trim() } : null
+}
+
+const checklistItemOf = (line: string, gate = false): ChecklistItem | null => {
+  const item = checkboxItemOf(line) ?? tableItemOf(line)
+  if (!item) return null
+  return gate ? { ...item, gate: true } : item
+}
+
+/** The items (checkboxes and ✅/⬜ table rows) of every `## ` section by its heading, sub-headings included. */
+const sectionItems = (markdown: string): Map<string, ChecklistItem[]> => {
+  const sections = new Map<string, ChecklistItem[]>()
+  let open: ChecklistItem[] | null = null
+  for (const line of markdown.split('\n')) {
+    const heading = line.match(SECTION_HEADING)
+    if (heading?.[1]) {
+      open = []
+      sections.set(heading[1], open)
+    } else if (TOP_HEADING.test(line)) {
+      open = null
+    } else {
+      const item = checklistItemOf(line)
+      if (item) open?.push(item)
+    }
+  }
+  return sections
+}
+
+/**
+ * Gives a phase without checkboxes of its own the ones of the section it points at. Sections are
+ * cut like the orchestrate script does (to the next `# ` or `## ` heading, the last of equal headings
+ * wins), so the counts of both agree.
+ */
+const withPointedSections = (
+  phases: PlanPhase[],
+  pointers: ReadonlyMap<PlanPhase, string>,
+  markdown: string,
+): PlanPhase[] => {
+  if (pointers.size === 0) return phases
+  const sections = sectionItems(markdown)
+  return phases.map((phase) => {
+    const pointer = pointers.get(phase)
+    return phase.items.length === 0 && pointer ? { ...phase, items: sections.get(pointer) ?? [] } : phase
+  })
+}
+
+/**
+ * The phase an open checkbox line is moved to with `→ P<n>` at its end; null for any other line, a ticked box,
+ * a ✅/⬜ table row, and an arrow to the box's own phase `phaseId`. The one rule the parser and the tally share.
+ */
+export const deferralTarget = (line: string, phaseId: string): string | null => {
+  const checkbox = line.match(CHECKBOX)
+  if (checkbox?.[1] !== ' ') return null
+  const target = checkbox[2]?.match(DEFERRED_TO)?.[1]?.toLowerCase()
+  return target && target !== phaseId ? target : null
+}
+
+const misplacedDeferralOf = (line: string, index: number): MisplacedDeferral[] => {
+  const checkbox = line.match(CHECKBOX)
+  if (checkbox?.[1] !== ' ' || DEFERRED_TO.test(checkbox[2])) return []
+  const arrow = checkbox[2].match(PHASE_ARROW)
+  if (!arrow) return []
+  const rest = checkbox[2].replace(PHASE_ARROW, '').trim()
+  const marker = line.slice(0, line.length - checkbox[2].length)
+  return [{ line: index + 1, target: arrow[1], corrected: `${marker}${rest} → ${PHASE_ID_PREFIX}${arrow[1]}` }]
+}
+
+/**
+ * Open checkboxes that carry `→ P<n>` somewhere other than at the end of the line. `deferralTarget` reads the arrow
+ * only there, so such a box counts as open in its own phase without a word; `jh check` refuses it. In an
+ * open checkbox the phase arrow stands only at the end, also where it would be meant as prose (`→ P2 prüfen`).
+ */
+export const misplacedDeferrals = (markdown: string): MisplacedDeferral[] =>
+  markdown.split('\n').flatMap(misplacedDeferralOf)
+
+const deferredItemOf = (line: string, phaseId: string): DeferredItem | null => {
+  const target = deferralTarget(line, phaseId)
+  const text = line.match(CHECKBOX)?.[2] ?? ''
+  return target ? { text: terminalSafe(text.replace(DEFERRED_TO, '')).trim(), target } : null
+}
+
+/** A deferred checkbox as its target phase lists it: an open, plain task with its origin. */
+const arrivedItem = ({ text }: DeferredItem, origin: PlanPhase): ChecklistItem => ({
+  done: false,
+  text: `${text} ← ${PHASE_ID_PREFIX}${origin.id}`,
+})
+
+/**
+ * Appends every deferred checkbox to its target phase as an open task. One whose target the plan lacks goes back
+ * among its own phase's items, open and with its marker, so a mistyped target never drops a task from the count.
+ */
+const withArrivedItems = (phases: PlanPhase[]): PlanPhase[] => {
+  const ids = new Set(phases.map(({ id }) => id))
+  const moved = phases.flatMap((origin) => (origin.deferred ?? []).map((item) => ({ origin, item })))
+  if (moved.length === 0) return phases
+  return phases.map((phase) => {
+    const arriving = moved
+      .filter(({ item }) => item.target === phase.id)
+      .map(({ item, origin }) => arrivedItem(item, origin))
+    const stranded = (phase.deferred ?? []).filter(({ target }) => !ids.has(target))
+    const deferred = (phase.deferred ?? []).filter(({ target }) => ids.has(target))
+    const returned = stranded.map(({ text, target }) => ({
+      done: false,
+      text: `${text} → ${PHASE_ID_PREFIX}${target}`,
+    }))
+    const { deferred: _, ...rest } = phase
+    return { ...rest, items: [...phase.items, ...returned, ...arriving], ...(deferred.length > 0 ? { deferred } : {}) }
+  })
+}
+
+/** Files one line of an open phase: a deferred checkbox under `deferred`, any other checkbox or table row under `items`. */
+const fileLine = (phase: PlanPhase, line: string, gate: boolean): void => {
+  const deferred = deferredItemOf(line, phase.id)
+  if (deferred) {
+    phase.deferred = [...(phase.deferred ?? []), deferred]
+    return
+  }
+  const item = checklistItemOf(line, gate)
+  if (item) phase.items.push(item)
+}
+
+const notePointer = (pointers: Map<PlanPhase, string>, phase: PlanPhase | null, line: string): void => {
+  const pointer = phase && !pointers.has(phase) ? line.match(SECTION_POINTER)?.[1] : undefined
+  if (phase && pointer) pointers.set(phase, pointer)
+}
+
+const headingOf = (line: string, phaseHeading: RegExp): RegExpMatchArray | null =>
+  line.match(phaseHeading) ?? line.match(NUMBERED_SECTION)
+
+/**
+ * Every `### Phase <id>` section, and every `## <id> — title` section, with its checkboxes. A
+ * section runs to the next heading of level three or higher, so a review-gate list or a `####`
+ * sub-heading inside the phase still counts. A phase without checkboxes of its own that points at
+ * a section (``Siehe `## Dokumentation` ``) counts that section's items, so it is done when the
+ * section is. An open checkbox ending in `→ P<n>` is kept under `deferred` and listed in phase `<n>` as open.
+ */
+export const parsePlanPhases = (markdown: string, language: PlanLanguage): PlanPhase[] => {
+  const phaseHeading = phaseHeadingPattern(language)
+  const pointers = new Map<PlanPhase, string>()
+  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: [] }
+        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)
+      if (open) fileLine(open, line, inGate)
+      notePointer(pointers, open, line)
+      return { phases, open, gate: inGate }
+    },
+    { phases: [], open: null, gate: false },
+  )
+  return withArrivedItems(withPointedSections(phases, pointers, markdown))
+}