jackherd 1.24.0 → 1.25.0

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,

package/docs/plan-contract.md

@@ -11,6 +11,7 @@ jackherd reads a plan from its Markdown. This is what a plan has to hold for the
 | Model | a table under `### Model recommendations per phase`: the phase in the first cell (`1 — Title`, `P1`, `10c`), the model in the second (`claude-opus-5-5`, `Opus 5.5`); a dash marks a phase that needs no model | yes | lane start (the model a lane runs on), `/implement` |
 | Dependencies | a table under `### Dependencies and parallelization` with the columns `Depends on`, `Writes`, `Serial marker` and one row per phase | from two phases on, optional | `jh check --parallel`, `/implement` |
 | Head | a section `## For you` (de: `## Für dich`) right after the header lines (`**Date:**`, `**Status:**`, `**Scope:**`), before the first other `##` section, with five lines `- **<label>:** <text>` | no, a note | `jh plan check`, the reader who is not an agent |
+| Purpose | directly under every `### Phase` heading, one line `**What it is about:** <sentence>` (de: `**Worum es geht:** <Satz>`): what is different afterwards, for whom | no, a note | `jh plan check`, `jh check` (new phases), the herd |
 
 Details that decide a verdict:
 
@@ -21,7 +22,47 @@ Details that decide a verdict:
 - The head's five labels are fixed per language. English: `What changes for you`, `Status`, `Your open decisions`, `Try it now`, `Next step`; German: `Was sich für dich ändert`, `Stand`, `Deine offenen Entscheidungen`, `Schon ausprobieren`, `Nächster Schritt`. The colon may stand outside the bold (`**Status**:`) and the list mark may be left out.
 - The `Status` line carries `Phase x/y`: x the id of the first phase with an open checkbox, as its heading spells it (`3`, `3a`), y the number of phases, each id counted once. When every phase is done, x is the id of the last one.
 - The head is `missing` without the section. It is `stale` when it stands behind another section, lacks a line, has no `Phase x/y`, or names another phase or phase count than the checkboxes show. Both are notes: the contract stays met and the exit code does not change, so plans written before the head keep passing.
-- The headings come from the plan language in `.jackherd/config.json` (`planLanguage`, `de` or `en`); the English ones are shown here.
+- The purpose line counts when it is the first non-empty line under a `### Phase` heading and has text after the colon; the colon may stand outside the bold or be left out. A line behind the origin line does not count. Only `### Phase` headings are read; phases headed `## 1 — …` or `## P1 — …` and the closing `## N — …` section are not. `purpose` is `missing` (`no purpose line in P2, P3`) when a phase with checkboxes of its own lacks the line (a phase that only points at a section needs none); it is a note and the exit code does not change, so older plans keep passing. `jh check` goes further for a phase the change adds: it fails without the line; phases the plan already had are not read.
+- The headings are shown in English here; a plan or board is read in German as well, and in any other language by markers (see below).
+
+## Language and markers
+
+jackherd reads boards and plans in every language it has words for (English and German), whatever `.jackherd/config.json` says: a German board next to an English plan works, and so does the other way round. The configuration decides only what jh **writes**:
+
+| Key | Decides | Default |
+| --- | ------- | ------- |
+| `planLanguage` | the language of new plans and of the plan templates | `en` |
+| `boardLanguage` | the language jh writes the board in: history lines, lane rows, waiting rows | the value of `planLanguage` |
+
+A config without `boardLanguage` runs as before. A heading, column name or status word is looked up in this order: the marker, the word of the configured language, the word of the other language.
+
+A document in a language jackherd has no words for carries a **marker**, `<!-- jh: <key> -->`, which Markdown does not show. The key comes from a closed set; an unknown key is ignored.
+
+| Where the marker stands | Keys |
+| ----------------------- | ---- |
+| on the line directly under a `##` (or `###`) heading | `waiting`, `appointments`, `lanes`, `goal`, `history`, `plans`, `decisions`, `implementation`, `model`, `dependencies`, `documentation`, `for-you`, `next` |
+| in a header cell of a table | `since`, `item`, `origin`, `unblocks`, `status`, `when`, `action`, `depends-on`, `writes`, `serial-marker` |
+| on a line of the head | `head-changes`, `head-status`, `head-decisions`, `head-try-now`, `head-next` |
+| in a status cell | `status-open` (a board row that still waits), `status-done`, `status-abandoned`, `status-in-progress`, `status-draft` |
+| on a line that opens with bold words | `no-review-gate`, `purpose` |
+| in a lane's name cell or phases cell | `lane-closed`, `partial-phase` |
+
+```markdown
+## Pistes
+<!-- jh: lanes -->
+
+| Piste | Port | Plan |
+| ----- | ---- | ---- |
+| `checkout` nettoyé <!-- jh: lane-closed --> | 3200 | [Plan](checkout.md) |
+
+### Phase 1: Surface
+
+**Le but** <!-- jh: purpose --> Les clients voient leurs filtres en haut de la liste.
+```
+
+When no section of a changed plan or board is recognised, three places say so: `jh plan check` names the forms it looked for (`no model table (looked for "### Model recommendations per phase", "### Model-Empfehlungen pro Phase" or <!-- jh: model -->)`), `jh check` warns on a changed file that has `##` headings of which jh reads none, and the herd shows `board: no section recognised` instead of "nothing waits for you". A section that is absent but allowed (no waiting item) stays silent.
+
+The plan templates are written in the language of their file name: `template-English.md` always in English, `template-German.md` always in German, whatever `planLanguage` says.
 
 ## Minimal valid plan
 
@@ -49,11 +90,15 @@ Details that decide a verdict:
 
 ### Phase 1: Query parser
 
+**What it is about:** nothing visible yet; the search box can turn typed text into filters.
+
 - [ ] **Parse filters**: `parseQuery(text)` returns the filter list
 - [ ] **Test it**: every operator, one malformed input
 
 ### Phase 2: Filter bar
 
+**What it is about:** people who search see their filters as chips above the results and can remove each one.
+
 - [ ] **Render the bar**: one chip per filter
 ```
 
@@ -70,22 +115,24 @@ phases: present plan.md:22 2 phases
 tasks: present plan.md:22 every phase has tasks
 model: present plan.md:12 every phase has a model
 dependencies: present every phase has a row
-head: missing no `## For you` section
+head: missing no `## For you` section (looked for "## For you", "## Für dich" or <!-- jh: for-you -->)
+purpose: present every phase says what it is about
 ```
 
-If the model table lacked the row for phase 2, and the dependency table were left out, the lines would read:
+If the model table lacked the row for phase 2, the dependency table were left out and the phases had no purpose lines, the lines would read:
 
 ```
 phases: present plan.md:22 2 phases
 tasks: present plan.md:22 every phase has tasks
 model: malformed plan.md:22 no model for P2
-dependencies: missing no dependency table: phases run one after another
+dependencies: missing no dependency table: phases run one after another (looked for "### Dependencies and parallelization", "### Abhängigkeiten und Parallelisierung" or <!-- jh: dependencies -->)
 head: stale plan.md:5 names phase 1, the running phase is 2
+purpose: missing plan.md:22 no purpose line in P1, P2
 ```
 
 | Exit | Meaning |
 | ---- | ------- |
-| 0 | the contract is met (a missing dependency table and a missing or stale head are notes, not gaps) |
+| 0 | the contract is met (a missing dependency table, a missing or stale head and a missing purpose line are notes, not gaps) |
 | 1 | at least one part is missing or malformed |
 | 2 | wrong command line: no subcommand, unknown subcommand, no file, unreadable file, unreadable config |
 | 3 | the contract is met, but the plan or a board that links it is not on the base branch (a `base:` line names each path); the coordinator commits it first (`/orchestrate` § 2 step 0), after which the check counts as done |

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.24.0"
+version = "1.25.0"
 min_herdr_version = "0.8.2"
 description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.24.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.25.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/approval-gate/index.ts

@@ -59,11 +59,11 @@ const writeHistory = (main: string, entry: StandingHistoryEntry): boolean => {
   try {
     const location = boardLocationOf(readConfig([main]))
     if (location === null) return false
-    const board = boardForLane(boardsIn(main, location), entry.lane, location.planLanguage)
+    const board = boardForLane(boardsIn(main, location), entry.lane, location.boardLanguage)
     if (board === null) return false
     const path = join(main, board.directory, location.board.file)
     const text = readTextOrNull(path)
-    const next = text === null ? null : withHistoryRow(text, location.planLanguage, historyDate(entry.at), standingHistoryLine(entry))
+    const next = text === null ? null : withHistoryRow(text, location.boardLanguage, historyDate(entry.at), standingHistoryLine(entry))
     if (next === null) return false
     writeFileSync(path, next)
     return true

package/kit/hooks/hooks/merge-guard/lane-plan.ts

@@ -47,5 +47,5 @@ const worktreeListOf = (main: string): string | undefined => {
 export const planOfBranch = (main: string, settings: BoardSettings, branch: string): string | undefined => {
   const list = worktreeListOf(main)
   const lane = list === undefined ? undefined : laneInWorktreeList(list, main, settings.worktreeDirectory, branch)
-  return lane === undefined ? undefined : onlyPlanOf(boardsIn(main, settings), lane, settings.planLanguage)
+  return lane === undefined ? undefined : onlyPlanOf(boardsIn(main, settings), lane, settings.boardLanguage)
 }