jackherd 1.24.0 → 1.26.0

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

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

package/src/check/settings.ts

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

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

@@ -71,10 +71,13 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   // The dev server restart by PID and `herdr pane run`, the form the merge guard passes (+54).
   '.claude/skills/orchestrate/references/start-lane.md': 766,
   // Core cut: § 4 waiting rows beyond the basic one, moved out of the core.
-  '.claude/skills/orchestrate/references/waiting.md': 216,
+  // What the watcher closes by itself, how to work through a `waiting obsolete?` proposal, and the rule for a
+  // decision the hooks cannot see: the coordinator's only text for the closing flow.
+  '.claude/skills/orchestrate/references/waiting.md': 450,
   '.claude/skills/orchestrate/references/watch-without-monitor.md': 154,
   // Prose cut, round 2: cut to its mandatory rules, measured size plus 5 %.
-  '.claude/skills/plan/SKILL.md': 1717,
+  // Language split: the note that a template renders in the language of its file name and that a heading in any other language carries a marker (+27).
+  '.claude/skills/plan/SKILL.md': 1744,
   '.claude/skills/plan/references/template-English.md': 536,
   '.claude/skills/plan/references/template-German.md': 501,
   // Prose cut, round 2: cut to its mandatory rules, measured size plus 5 %.
@@ -111,9 +114,11 @@ export const KIT_SKILL_CEILINGS: Readonly<Record<string, number>> = {
   '.claude/agents/skill-review.md': 513,
   // Plan head: every plan opens with a `For you` head of five short lines a person reads first, which
   // `jh plan check` reports; cut to its labels; skill-review: the status line says what `N` counts. Measured size (+42).
-  '.claude/skills/plan/references/template-English.md': 578,
+  // Phase purpose: the line under every phase heading a template shows, one sentence of what is different afterwards and for whom (+17).
+  '.claude/skills/plan/references/template-English.md': 595,
   // Plan head: the same `Für dich` head as the English template, with what `N` counts; measured size (+41).
-  '.claude/skills/plan/references/template-German.md': 542,
+  // Phase purpose: the same line under every phase heading as the English template (+15).
+  '.claude/skills/plan/references/template-German.md': 557,
   // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
   // Plain words: no plan code without its words in a short question.
   // Any language: a pointer in § 0 and a section in events.md for `plan missing`.

package/src/config/schema.ts

@@ -567,7 +567,10 @@ export const jackherdConfigSchema = z.strictObject({
   responseLanguage: language.default(PLAN_LANGUAGE.en),
   /** Whether replies address the user with the familiar or the polite form where the language has both (German: du or Sie). */
   responseAddress: z.enum(Object.values(RESPONSE_ADDRESS)).default(RESPONSE_ADDRESS.informal),
+  /** The language new plans and the plan templates are written in. Boards and plans are read in every known language whatever this says. */
   planLanguage: language.default(PLAN_LANGUAGE.en),
+  /** The language jh writes the board in (history lines, lane rows, waiting rows); `planLanguage` when left out. */
+  boardLanguage: language.optional(),
   planDirectory: z.string().min(1).default('docs/plans'),
   /** Where the boards live and what the project calls them. */
   board: boardSchema.prefault({}),

package/src/lane/close-board.ts

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

package/src/lane/close-command.ts

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

package/src/lane/dev-command.ts

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

package/src/lane/port-command.ts

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

package/src/plan-contract/command.ts

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

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 = []