jackherd 1.23.3 → 1.25.0

package/dist/plan-format.d.ts

@@ -3,6 +3,8 @@ declare const PLAN_LANGUAGE: {
     readonly en: "en";
 };
 type PlanLanguage = (typeof PLAN_LANGUAGE)[keyof typeof PLAN_LANGUAGE];
+/** The languages to try when reading: `language` first, then every other known one. */
+declare const languagesFrom: (language: PlanLanguage) => PlanLanguage[];
 /** The language's name as a reply or a question says it. */
 declare const LANGUAGE_NAME: Record<PlanLanguage, string>;
 declare const RESPONSE_ADDRESS: {
@@ -106,6 +108,73 @@ declare const WAITING_VOCABULARY: Record<PlanLanguage, {
     statusAlso: readonly string[];
     open: readonly string[];
 }>;
+/**
+ * The closed set of keys a section carries in a marker, `<!-- jh: <key> -->` on the line directly under its heading.
+ * The marker names the section whatever language the heading is written in.
+ */
+declare const SECTION_KEY: {
+    readonly waiting: "waiting";
+    readonly appointments: "appointments";
+    readonly lanes: "lanes";
+    readonly goal: "goal";
+    readonly history: "history";
+    readonly plans: "plans";
+    readonly decisions: "decisions";
+    readonly implementation: "implementation";
+    readonly model: "model";
+    readonly dependencies: "dependencies";
+    readonly documentation: "documentation";
+    readonly forYou: "for-you";
+    readonly next: "next";
+};
+type SectionKey = (typeof SECTION_KEY)[keyof typeof SECTION_KEY];
+declare const isSectionKey: (value: string) => value is SectionKey;
+/**
+ * The marker key of each line of the head section (`- **Stand:** <!-- jh: head-status --> …`). The marker names the
+ * line whatever language its label is written in.
+ */
+declare const HEAD_KEY: Record<HeadLine, string>;
+/**
+ * The closed set of keys a line that opens with bold words carries in a marker
+ * (`**Kein Review-Gate** <!-- jh: no-review-gate --> reason`). The marker names the line whatever language it is in.
+ */
+declare const LINE_KEY: {
+    readonly noReviewGate: "no-review-gate";
+    readonly purpose: "purpose";
+};
+/**
+ * The closed set of keys a table column carries in a marker in its header cell (`Hängt ab von <!-- jh: depends-on -->`).
+ * The marker names the column whatever language the header is written in.
+ */
+declare const COLUMN_KEY: {
+    readonly since: "since";
+    readonly item: "item";
+    readonly origin: "origin";
+    readonly unblocks: "unblocks";
+    readonly status: "status";
+    readonly when: "when";
+    readonly action: "action";
+    readonly dependsOn: "depends-on";
+    readonly writes: "writes";
+    readonly serialMarker: "serial-marker";
+};
+type ColumnKey = (typeof COLUMN_KEY)[keyof typeof COLUMN_KEY];
+/** The header names the column `key` goes by in `language`: its name first, then the names that count as the same column. */
+declare const columnWords: (key: ColumnKey, language: PlanLanguage) => readonly string[];
+/**
+ * The closed set of keys a status carries in a marker in its cell (`erledigt <!-- jh: status-done -->`): `open` for a
+ * board row that still waits, the others for the status of a plan. The marker names the status whatever language the
+ * cell is written in.
+ */
+declare const STATUS_KEY: {
+    readonly open: "status-open";
+    readonly done: "status-done";
+    readonly abandoned: "status-abandoned";
+    readonly inProgress: "status-in-progress";
+    readonly draft: "status-draft";
+};
+type StatusKey = (typeof STATUS_KEY)[keyof typeof STATUS_KEY];
+declare const isStatusKey: (value: string) => value is StatusKey;
 declare const isPlanLanguage: (value: string) => value is PlanLanguage;
 declare const PLAN_STATUS: {
     readonly done: "done";
@@ -173,6 +242,8 @@ type PlanVocabulary = {
     phase: string;
     /** Opens the line by which a phase says it has no review gate on purpose: `**Kein Review-Gate:** <reason>`. */
     noReviewGate: string;
+    /** Opens the line directly under a phase heading that says in one sentence what is different afterwards, for whom: `**Worum es geht:** <sentence>`. */
+    phasePurpose: string;
     /** Marks a lane as closed when its name cell contains it. */
     laneClosed: string;
     /** Stands in a board row's phases cell when that pull request builds only part of the phase. */
@@ -196,10 +267,35 @@ type PlanVocabulary = {
     statusWords: Record<PlanStatus, StatusWord>;
 };
 declare const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary>;
-/** Classifies a free-text `Status:` line; the first matching status in precedence order wins. */
+/** A `<!-- jh: <key> -->` marker anywhere in a text; the key is group 1. */
+declare const MARKER_IN_TEXT: RegExp;
+/**
+ * Classifies a free-text `Status:` line. A status marker (`<!-- jh: status-done -->`) decides, any language; else the
+ * first matching status in precedence order of the words of `language`, then of any other known language.
+ */
 declare const classifyStatus: (language: PlanLanguage, statusText: string) => PlanStatus;
 /** `### Phase 3: Title` as the plan spells it in `language`. */
 declare const phaseHeading: (language: PlanLanguage, id: string, title: string) => string;
+/** The heading text of the section `key` names, as `language` writes it. */
+declare const headingOfSection: (key: SectionKey, language: PlanLanguage) => string;
+/** The key and language of the section a heading text names, read the way a caller spells it; `null` when no language does. */
+declare const sectionOfHeading: (headingText: string) => {
+    key: SectionKey;
+    language: PlanLanguage;
+} | null;
+/**
+ * The closed set of keys a lanes-table cell carries in a marker: `lane-closed` in the name cell of a lane that was
+ * cleaned up, `partial-phase` in the phases cell of a row that builds only part of a phase.
+ */
+declare const CELL_KEY: {
+    readonly laneClosed: "lane-closed";
+    readonly partialPhase: "partial-phase";
+};
+type CellKey = (typeof CELL_KEY)[keyof typeof CELL_KEY];
+/** The words of every known language that mark a lane as cleaned up. */
+declare const LANE_CLOSED_WORDS: readonly string[];
+/** The words of every known language that mark a row as building only part of a phase. */
+declare const PARTIAL_PHASE_WORDS: readonly string[];
 declare const sectionHeading: (language: PlanLanguage, section: keyof PlanVocabulary["sections"]) => string;
 
 /**
@@ -260,11 +356,13 @@ 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.
  */
 type PlanPhase = {
     id: string;
     title: string;
+    purpose?: string;
     items: ChecklistItem[];
     deferred?: DeferredItem[];
 } & Partial<PhaseWorkFields>;
@@ -283,6 +381,15 @@ declare const endsPhase: (line: string) => boolean;
 declare const isCheckboxLine: (line: string) => boolean;
 declare const isOpenCheckboxLine: (line: string) => boolean;
 declare const phaseHeadingPattern: (language: PlanLanguage) => RegExp;
+/** The bold opening of a line (`**Label:**` or `**Label**:`): the label and the text after it. */
+declare const BOLD_OPENING: RegExp;
+/**
+ * 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.
+ */
+declare const phasePurposeOf: (line: string, language: PlanLanguage) => string | null;
+/** The first non-empty line under a heading decides whether a phase has its purpose line; once `decided`, later lines never do. */
+declare const decidesPurpose: (decided: boolean, line: string) => boolean;
 /**
  * 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.
@@ -556,6 +663,8 @@ type PhaseWithOpenBoxes = PhaseWithoutGate & {
 };
 /** A `PhaseWithOpenBoxes` whose tasks are all ticked on the base branch. */
 type MergedPhaseWithOpenBoxes = PhaseWithOpenBoxes;
+/** A `### Phase` heading (1-based line) whose section has tasks and no purpose line directly under the heading. */
+type PhaseWithoutPurpose = PhaseHeading;
 /** The ids of the `### Phase` headings of a plan. */
 declare const phaseIdsOfPlan: (markdown: string, language: PlanLanguage) => Set<string>;
 /**
@@ -565,6 +674,13 @@ declare const phaseIdsOfPlan: (markdown: string, language: PlanLanguage) => Set<
  * plan does not turn red when it is touched.
  */
 declare const newPhasesWithoutReviewGate: (markdown: string, language: PlanLanguage, previousIds: ReadonlySet<string>) => PhaseWithoutGate[];
+/**
+ * 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`.
+ */
+declare const newPhasesWithoutPurpose: (markdown: string, language: PlanLanguage, previousIds: ReadonlySet<string>) => PhaseWithoutPurpose[];
+/** 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. */
+declare const phasesWithoutPurpose: (markdown: string, language: PlanLanguage) => PhaseWithoutPurpose[];
 /** Whether the document has a lanes table (`## Spuren`): a board, not a plan. */
 declare const hasLanesTable: (markdown: string, language: PlanLanguage) => boolean;
 /**
@@ -593,6 +709,8 @@ declare const boardRowsWithoutPhase: (markdown: string, language: PlanLanguage,
 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[];
@@ -709,4 +827,4 @@ declare const readSprintDocument: (markdown: string, language: PlanLanguage) =>
  */
 declare const readPhaseDependencies: (planMarkdown: string, language: PlanLanguage) => Record<string, string>;
 
-export { ADDRESS_FORM, APPOINTMENT_VOCABULARY, APPROVAL_TEXTS, CARD_FIELDS, type ChecklistItem, type ColumnModel, type DeferredItem, type DriftFinding, HEAD_LINE, HEAD_STATUS, type HeadLine, type HeadPhase, type HeadStatus, type HeadVerdict, LANE_PROMPT_OPENING, LANGUAGE_NAME, type LaneProgress, type LongPhaseTitle, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, type ModelRow, NEXT_VOCABULARY, NO_DEPENDENCY_TABLE, PHASE_CELL_LIMIT, PHASE_ID_PREFIX, PHASE_TITLE_LIMIT, PHASE_WORK, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, PROSE_REASON, type PhaseDependency, type PhaseHeading, type PhaseProgress, type PhaseSchedule, type PhaseTally, type PhaseWithOpenBoxes, type PhaseWithoutGate, type PhaseWithoutRow, type PhaseWork, type PhaseWorkFields, type PlanHead, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type ProseReason, RECOMMENDED_MARK, REPORT_FIELDS, RESPONSE_ADDRESS, type ResponseAddress, type RowWithProse, type RowWithoutPhase, SELF_MERGE_LABEL, SHORT_NAME_LIMIT, SHORT_NAME_PROBLEM, STANDING_APPROVAL_TEXTS, type ShortNameFinding, type ShortNameProblem, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusWord, type StepProgress, WAITING_VOCABULARY, activeItem, boardRowsWithProse, boardRowsWithoutPhase, checkPlanHead, classifyStatus, columnModels, countDecisions, criticalPath, currentPhase, currentPhaseOf, deferralTarget, differsFromColumn, endsPhase, findDrift, hasLanesTable, isCheckboxLine, isDocumentationGateItem, isOpenCheckboxLine, isPhaseFinished, isPhaseOpen, isPlanLanguage, isReviewGateLine, isTickedUnmerged, laneNameOf, laneProgress, longPhaseTitles, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutReviewGate, onlyDocumentationOpen, openBoxesOfPhase, parallelGroups, parallelGroupsOfPlan, parseDependencyTable, parseModelTable, parsePlanHead, parsePlanPhases, parseSprintLanes, phaseCount, phaseHeading, phaseHeadingPattern, phaseHeadings, phaseIdOf, phaseIdsOfCell, phaseIdsOfPlan, phaseLabel, phaseLabels, phaseProgress, phaseWaves, phaseWorkFields, phasesText, phasesWithoutDependencyRow, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, shortNameFindings, shortTitle, sprintTitleOf, sumPhases, tallyPhases, wavesOfPlan, withoutRepeats };
+export { ADDRESS_FORM, APPOINTMENT_VOCABULARY, APPROVAL_TEXTS, BOLD_OPENING, CARD_FIELDS, CELL_KEY, COLUMN_KEY, type CellKey, type ChecklistItem, type ColumnKey, type ColumnModel, type DeferredItem, type DriftFinding, HEAD_KEY, HEAD_LINE, HEAD_STATUS, type HeadLine, type HeadPhase, type HeadStatus, type HeadVerdict, LANE_CLOSED_WORDS, LANE_PROMPT_OPENING, LANGUAGE_NAME, LINE_KEY, type LaneProgress, type LongPhaseTitle, MARKER_IN_TEXT, type MergedPhaseWithOpenBoxes, type MisplacedDeferral, type ModelRow, NEXT_VOCABULARY, NO_DEPENDENCY_TABLE, PARTIAL_PHASE_WORDS, PHASE_CELL_LIMIT, PHASE_ID_PREFIX, PHASE_TITLE_LIMIT, PHASE_WORK, PLAN_LANGUAGE, PLAN_STATUS, PLAN_VOCABULARY, PROSE_REASON, type PhaseDependency, type PhaseHeading, type PhaseProgress, type PhaseSchedule, type PhaseTally, type PhaseWithOpenBoxes, type PhaseWithoutGate, type PhaseWithoutPurpose, type PhaseWithoutRow, type PhaseWork, type PhaseWorkFields, type PlanHead, type PlanHeader, type PlanLanguage, type PlanPhase, type PlanStatus, type PlanStep, type PlanVocabulary, type PlansByHref, type ProseReason, RECOMMENDED_MARK, REPORT_FIELDS, RESPONSE_ADDRESS, type ResponseAddress, type RowWithProse, type RowWithoutPhase, SECTION_KEY, SELF_MERGE_LABEL, SHORT_NAME_LIMIT, SHORT_NAME_PROBLEM, STANDING_APPROVAL_TEXTS, STATUS_KEY, type SectionKey, type ShortNameFinding, type ShortNameProblem, type SprintDocument, type SprintLane, type SprintPlanRow, type SprintPlanTable, type StatusKey, type StatusWord, type StepProgress, WAITING_VOCABULARY, activeItem, boardRowsWithProse, boardRowsWithoutPhase, checkPlanHead, classifyStatus, columnModels, columnWords, countDecisions, criticalPath, currentPhase, currentPhaseOf, decidesPurpose, deferralTarget, differsFromColumn, endsPhase, findDrift, hasLanesTable, headingOfSection, isCheckboxLine, isDocumentationGateItem, isOpenCheckboxLine, isPhaseFinished, isPhaseOpen, isPlanLanguage, isReviewGateLine, isSectionKey, isStatusKey, isTickedUnmerged, laneNameOf, laneProgress, languagesFrom, longPhaseTitles, mergedPhasesWithOpenBoxes, misplacedDeferrals, newPhasesWithoutPurpose, newPhasesWithoutReviewGate, onlyDocumentationOpen, openBoxesOfPhase, parallelGroups, parallelGroupsOfPlan, parseDependencyTable, parseModelTable, parsePlanHead, parsePlanPhases, parseSprintLanes, phaseCount, phaseHeading, phaseHeadingPattern, phaseHeadings, phaseIdOf, phaseIdsOfCell, phaseIdsOfPlan, phaseLabel, phaseLabels, phaseProgress, phasePurposeOf, phaseWaves, phaseWorkFields, phasesText, phasesWithoutDependencyRow, phasesWithoutPurpose, readPhaseDependencies, readPlanHeader, readSprintDocument, resolvePlanPath, sectionHeading, sectionOfHeading, shortNameFindings, shortTitle, sprintTitleOf, sumPhases, tallyPhases, wavesOfPlan, withoutRepeats };

package/dist/plan-format.js

@@ -3,25 +3,40 @@ import {
   APPOINTMENT_VOCABULARY,
   APPROVAL_TEXTS,
   CARD_FIELDS,
+  CELL_KEY,
+  COLUMN_KEY,
+  HEAD_KEY,
   HEAD_LINE,
+  LANE_CLOSED_WORDS,
   LANE_PROMPT_OPENING,
   LANGUAGE_NAME,
+  LINE_KEY,
+  MARKER_IN_TEXT,
   NEXT_VOCABULARY,
+  PARTIAL_PHASE_WORDS,
   PLAN_LANGUAGE,
   PLAN_STATUS,
   PLAN_VOCABULARY,
   RECOMMENDED_MARK,
   REPORT_FIELDS,
   RESPONSE_ADDRESS,
+  SECTION_KEY,
   SELF_MERGE_LABEL,
   STANDING_APPROVAL_TEXTS,
+  STATUS_KEY,
   WAITING_VOCABULARY,
   classifyStatus,
+  columnWords,
+  headingOfSection,
   isPlanLanguage,
+  isSectionKey,
+  isStatusKey,
+  languagesFrom,
   phaseHeading,
   sectionHeading,
+  sectionOfHeading,
   terminalSafe
-} from "./chunk-JDO6O3UO.js";
+} from "./chunk-O365KHHP.js";
 
 // src/plan-format/lanes.ts
 import { posix } from "path";
@@ -30,18 +45,74 @@ import { posix } from "path";
 var SECTION_END = /^##\s/;
 var TABLE_SEPARATOR = /^\|[\s|:-]+\|$/;
 var escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-var sectionStart = (markdown, headingText) => {
-  const heading = new RegExp(`^##\\s+${escapeRegExp(headingText)}\\s*$`);
-  const start = markdown.split("\n").findIndex((line) => heading.test(line));
-  return start === -1 ? -1 : start + 1;
+var MARKER = /^<!--\s*jh:\s*([a-z-]+)\s*-->\s*$/;
+var markedKeyOf = (text) => MARKER_IN_TEXT.exec(text)?.[1] ?? null;
+var withoutMarker = (text) => text.replace(MARKER_IN_TEXT, "").trim();
+var lookedForSection = (key, level, language) => {
+  const headings = languagesFrom(language).map((candidate) => `"${level} ${headingOfSection(key, candidate)}"`);
+  return `(looked for ${headings.join(", ")} or <!-- jh: ${key} -->)`;
+};
+var namesState = (text, key, words) => markedKeyOf(text) === key || words.some((word) => text.includes(word));
+var SECTION_HEADING = /^##\s+(.*?)\s*$/;
+var markerKey = (line) => {
+  const key = line === void 0 ? void 0 : MARKER.exec(line)?.[1];
+  return key !== void 0 && isSectionKey(key) ? key : null;
+};
+var SECTION_MATCH = { pattern: SECTION_HEADING, matches: (text, heading) => text === heading };
+var SUBSECTION_MATCH = {
+  pattern: /^(#{2,4})\s+(.*?)\s*$/,
+  matches: (text, heading) => text.startsWith(heading)
+};
+var headingText = (line, { pattern }) => pattern.exec(line)?.at(-1);
+var headingIndexOf = (lines, key, language, match) => {
+  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 !== void 0 && match.matches(text, heading);
+    });
+    if (found !== -1) return found;
+  }
+  return -1;
 };
-var sectionLines = (markdown, headingText) => {
-  const start = sectionStart(markdown, headingText);
-  if (start === -1) return [];
-  const rest = markdown.split("\n").slice(start);
+var findSectionStart = (markdown, key, language) => {
+  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);
+};
+var findSectionHeading = (markdown, key, language) => headingIndexOf(markdown.split("\n"), key, language, SECTION_MATCH);
+var untilNextSection = (rest) => {
   const end = rest.findIndex((line) => SECTION_END.test(line));
   return end === -1 ? rest : rest.slice(0, end);
 };
+var columnIndex = (header, key, language) => {
+  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;
+};
+var exactSectionStart = (markdown, headingTextValue) => {
+  const heading = new RegExp(`^##\\s+${escapeRegExp(headingTextValue)}\\s*$`);
+  const start = markdown.split("\n").findIndex((line) => heading.test(line));
+  return start === -1 ? -1 : start + 1;
+};
+var sectionStart = (markdown, headingText2) => {
+  const section = sectionOfHeading(headingText2);
+  return section === null ? exactSectionStart(markdown, headingText2) : findSectionStart(markdown, section.key, section.language);
+};
+var sectionLines = (markdown, headingText2) => {
+  const start = sectionStart(markdown, headingText2);
+  return start === -1 ? [] : untilNextSection(markdown.split("\n").slice(start));
+};
 var tableCells = (line) => line.slice(1, line.endsWith("|") ? -1 : void 0).split("|").map((cell) => terminalSafe(cell).trim());
 var firstTableRows = (lines) => {
   const start = lines.findIndex((line) => line.startsWith("|"));
@@ -57,10 +128,14 @@ var headerField = (markdown, name) => {
 };
 var firstHeading = (markdown, fallback) => terminalSafe(markdown.match(/^#\s+(.+)$/m)?.[1] ?? fallback).trim();
 var HEADING = /^(#{2,4})\s+(.*?)\s*$/;
-var subsectionStart = (markdown, headingText) => markdown.split("\n").findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText));
-var subsectionLines = (markdown, headingText) => {
+var subsectionStart = (markdown, headingText2) => {
+  const section = sectionOfHeading(headingText2);
+  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(headingText2));
+};
+var subsectionLines = (markdown, headingText2) => {
   const lines = markdown.split("\n");
-  const start = subsectionStart(markdown, headingText);
+  const start = subsectionStart(markdown, headingText2);
   if (start === -1) return [];
   const level = HEADING.exec(lines[start])?.[1].length ?? 2;
   const rest = lines.slice(start + 1);
@@ -166,14 +241,13 @@ var withoutRepeats = (lane, step) => {
 var parseSprintLanes = (markdown, language) => {
   const lanes = /* @__PURE__ */ new Map();
   const phaseId = phaseIdPatterns(language);
-  const { laneClosed } = PLAN_VOCABULARY[language];
   let previous = 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 = [];
@@ -227,7 +301,7 @@ var phaseWorkFields = (work) => work === PHASE_WORK.merged ? { work, touched: tr
 var REVIEW_GATE = /^\s*\*\*review[- ]gate\b/i;
 var PHASE_END = /^#{1,3}\s/;
 var CHECKBOX = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/;
-var SECTION_HEADING = /^##\s+(.+?)\s*$/;
+var SECTION_HEADING2 = /^##\s+(.+?)\s*$/;
 var TOP_HEADING = /^#\s/;
 var TABLE_STATUS = { done: "\u2705", open: "\u2B1C" };
 var ROW_NUMBER = /^\d+(\.\d+)*[a-z]?$/;
@@ -240,6 +314,19 @@ var endsPhase = (line) => PHASE_END.test(line);
 var isCheckboxLine = (line) => CHECKBOX.test(line);
 var isOpenCheckboxLine = (line) => line.match(CHECKBOX)?.[1] === " ";
 var phaseHeadingPattern = (language) => new RegExp(`^###\\s+${escapeRegExp(PLAN_VOCABULARY[language].phase)}\\s+(\\d+[a-z]?)\\b\\s*[:\u2014\u2013-]?\\s*(.*)$`, "i");
+var BOLD_OPENING = /^\s*\*\*([^*]+?)\s*:?\*\*\s*:?\s*(.*)$/;
+var namesPurpose = (line, label, language) => {
+  if (markedKeyOf(line) === LINE_KEY.purpose) return true;
+  const written = label.trim().toLowerCase();
+  return languagesFrom(language).some((candidate) => PLAN_VOCABULARY[candidate].phasePurpose.toLowerCase() === written);
+};
+var phasePurposeOf = (line, language) => {
+  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;
+};
+var decidesPurpose = (decided, line) => !decided && line.trim() !== "";
 var tableCells2 = (line) => {
   const trimmed = line.trim();
   if (!trimmed.startsWith("|")) return null;
@@ -266,7 +353,7 @@ var sectionItems = (markdown) => {
   const sections = /* @__PURE__ */ new Map();
   let open = null;
   for (const line of markdown.split("\n")) {
-    const heading = line.match(SECTION_HEADING);
+    const heading = line.match(SECTION_HEADING2);
     if (heading?.[1]) {
       open = [];
       sections.set(heading[1], open);
@@ -341,6 +428,12 @@ var notePointer = (pointers, phase, line) => {
   const pointer = phase && !pointers.has(phase) ? line.match(SECTION_POINTER)?.[1] : void 0;
   if (phase && pointer) pointers.set(phase, pointer);
 };
+var notePurpose = (read, phase, line, language) => {
+  if (!phase || !decidesPurpose(read.has(phase), line)) return;
+  read.add(phase);
+  const purpose = phasePurposeOf(line, language);
+  if (purpose !== null) phase.purpose = purpose;
+};
 var headingOf = (line, phaseHeading2) => line.match(phaseHeading2) ?? line.match(NUMBERED_SECTION);
 var phaseHeadings = (markdown, language) => {
   const phaseHeading2 = phaseHeadingPattern(language);
@@ -352,15 +445,22 @@ var phaseHeadings = (markdown, language) => {
 var parsePlanPhases = (markdown, language) => {
   const phaseHeading2 = phaseHeadingPattern(language);
   const pointers = /* @__PURE__ */ new Map();
+  const purposeRead = /* @__PURE__ */ new Set();
   const { phases } = markdown.split("\n").reduce(
     ({ phases: phases2, open, gate }, line) => {
       const heading = headingOf(line, phaseHeading2);
       if (heading) {
-        const phase = { id: (heading[1] ?? "").toLowerCase(), title: terminalSafe(heading[2] ?? "").trim(), items: [] };
+        const phase = {
+          id: (heading[1] ?? "").toLowerCase(),
+          title: terminalSafe(heading[2] ?? "").trim(),
+          items: []
+        };
+        if (!phaseHeading2.test(line)) purposeRead.add(phase);
         return { phases: [...phases2, phase], open: phase, gate: false };
       }
       if (PHASE_END.test(line)) return { phases: phases2, 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: phases2, open, gate: inGate };
@@ -385,6 +485,7 @@ var phaseProgress = (phases, id) => {
     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) : {}
   };
@@ -546,10 +647,10 @@ var releasedByFiles = (writes) => writes.flatMap((path) => {
   return [packageKey(directory.at(-1) ?? ".")];
 });
 var parseDependencyTable = (markdown, language) => {
-  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) => {
@@ -790,16 +891,21 @@ var tallyPhases = (markdown, language) => {
 
 // src/plan-format/plan-head.ts
 var HEAD_STATUS = { present: "present", missing: "missing", stale: "stale" };
-var SECTION_HEADING2 = /^##\s/;
+var SECTION_HEADING3 = /^##\s/;
 var HEAD_ENTRY = /^\s*(?:[-*]\s+)?\*\*([^*]+?)\s*:?\*\*\s*:?\s*(.*)$/;
 var HEAD_LINES = Object.values(HEAD_LINE);
 var labelOf = (language, line) => PLAN_VOCABULARY[language].head[line].toLowerCase();
+var labelNamed = (text, written, language) => {
+  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 !== void 0);
+};
 var entryOf = (text, language) => {
   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;
 };
 var phaseOf = (statusText, language) => {
   const match = statusText?.match(
@@ -809,11 +915,10 @@ var phaseOf = (statusText, language) => {
 };
 var parsePlanHead = (markdown, language) => {
   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_HEADING2.test(text));
+  const end = rest.findIndex((text) => SECTION_HEADING3.test(text));
   const texts = {};
   const lineNumbers = {};
   for (const [offset, text] of (end === -1 ? rest : rest.slice(0, end)).entries()) {
@@ -829,7 +934,7 @@ var parsePlanHead = (markdown, language) => {
     lineNumbers,
     missing: HEAD_LINES.filter((each) => texts[each] === void 0),
     phase: phaseOf(texts[HEAD_LINE.status], language),
-    misplaced: lines.slice(0, start).some((text) => SECTION_HEADING2.test(text))
+    misplaced: lines.slice(0, start).some((text) => SECTION_HEADING3.test(text))
   };
 };
 var verdict = (status, line, message) => ({ status, line, message });
@@ -843,8 +948,14 @@ var phaseMismatch = ({ current, total }, states) => {
 };
 var checkPlanHead = (markdown, language) => {
   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,
@@ -864,15 +975,21 @@ var checkPlanHead = (markdown, language) => {
 };
 
 // src/plan-format/plan-structure.ts
-var noGatePattern = (language) => new RegExp(`^\\s*\\*\\*${escapeRegExp(PLAN_VOCABULARY[language].noReviewGate)}\\b`, "i");
+var NO_GATE_WORDS = new RegExp(
+  `^\\s*\\*\\*(?:${Object.values(PLAN_VOCABULARY).map(({ noReviewGate }) => escapeRegExp(noReviewGate)).join("|")})\\b`,
+  "i"
+);
+var isNoGateLine = (line) => NO_GATE_WORDS.test(line) || BOLD_OPENING.test(line) && markedKeyOf(line) === LINE_KEY.noReviewGate;
 var tickCount = (phase) => phase.items.filter((item) => item.done).length;
 var tasksDone = (phase) => {
   const tasks = phase.items.filter((item) => !item.gate);
   return tasks.length > 0 && tasks.every((item) => item.done);
 };
+var settlePurpose = (section, line, language) => {
+  if (decidesPurpose(section.purpose !== null, line)) section.purpose = phasePurposeOf(line, language) !== null;
+};
 var phaseSections = (markdown, language) => {
   const heading = phaseHeadingPattern(language);
-  const noGate = noGatePattern(language);
   const sections = [];
   let open = null;
   for (const [index, line] of markdown.split("\n").entries()) {
@@ -884,14 +1001,16 @@ var phaseSections = (markdown, language) => {
         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);
     }
   }
@@ -899,6 +1018,8 @@ var phaseSections = (markdown, language) => {
 };
 var phaseIdsOfPlan = (markdown, language) => new Set(phaseSections(markdown, language).map(({ id }) => id));
 var newPhasesWithoutReviewGate = (markdown, language, previousIds) => phaseSections(markdown, language).filter(({ id, tasks, gate }) => tasks && !gate && !previousIds.has(id)).map(({ line, id, title }) => ({ line, id, title }));
+var newPhasesWithoutPurpose = (markdown, language, previousIds) => phaseSections(markdown, language).filter(({ id, tasks, purpose }) => tasks && !purpose && !previousIds.has(id)).map(({ line, id, title }) => ({ line, id, title }));
+var phasesWithoutPurpose = (markdown, language) => newPhasesWithoutPurpose(markdown, language, /* @__PURE__ */ new Set());
 var hasLanesTable = (markdown, language) => sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes).some((line) => line.startsWith("|"));
 var mergedPhasesWithOpenBoxes = (markdown, base, language) => {
   const baseById = new Map(parsePlanPhases(base, language).map((phase) => [phase.id, phase]));
@@ -977,9 +1098,9 @@ var readSprintDocument = (markdown, language) => {
   };
 };
 var readPhaseDependencies = (planMarkdown, language) => {
-  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];
@@ -991,13 +1112,21 @@ export {
   ADDRESS_FORM,
   APPOINTMENT_VOCABULARY,
   APPROVAL_TEXTS,
+  BOLD_OPENING,
   CARD_FIELDS,
+  CELL_KEY,
+  COLUMN_KEY,
+  HEAD_KEY,
   HEAD_LINE,
   HEAD_STATUS,
+  LANE_CLOSED_WORDS,
   LANE_PROMPT_OPENING,
   LANGUAGE_NAME,
+  LINE_KEY,
+  MARKER_IN_TEXT,
   NEXT_VOCABULARY,
   NO_DEPENDENCY_TABLE,
+  PARTIAL_PHASE_WORDS,
   PHASE_CELL_LIMIT,
   PHASE_ID_PREFIX,
   PHASE_TITLE_LIMIT,
@@ -1009,10 +1138,12 @@ export {
   RECOMMENDED_MARK,
   REPORT_FIELDS,
   RESPONSE_ADDRESS,
+  SECTION_KEY,
   SELF_MERGE_LABEL,
   SHORT_NAME_LIMIT,
   SHORT_NAME_PROBLEM,
   STANDING_APPROVAL_TEXTS,
+  STATUS_KEY,
   WAITING_VOCABULARY,
   activeItem,
   boardRowsWithProse,
@@ -1020,15 +1151,18 @@ export {
   checkPlanHead,
   classifyStatus,
   columnModels,
+  columnWords,
   countDecisions,
   criticalPath,
   currentPhase,
   currentPhaseOf,
+  decidesPurpose,
   deferralTarget,
   differsFromColumn,
   endsPhase,
   findDrift,
   hasLanesTable,
+  headingOfSection,
   isCheckboxLine,
   isDocumentationGateItem,
   isOpenCheckboxLine,
@@ -1036,12 +1170,16 @@ export {
   isPhaseOpen,
   isPlanLanguage,
   isReviewGateLine,
+  isSectionKey,
+  isStatusKey,
   isTickedUnmerged,
   laneNameOf,
   laneProgress,
+  languagesFrom,
   longPhaseTitles,
   mergedPhasesWithOpenBoxes,
   misplacedDeferrals,
+  newPhasesWithoutPurpose,
   newPhasesWithoutReviewGate,
   onlyDocumentationOpen,
   openBoxesOfPhase,
@@ -1062,15 +1200,18 @@ export {
   phaseLabel,
   phaseLabels,
   phaseProgress,
+  phasePurposeOf,
   phaseWaves,
   phaseWorkFields,
   phasesText,
   phasesWithoutDependencyRow,
+  phasesWithoutPurpose,
   readPhaseDependencies,
   readPlanHeader,
   readSprintDocument,
   resolvePlanPath,
   sectionHeading,
+  sectionOfHeading,
   shortNameFindings,
   shortTitle,
   sprintTitleOf,