jackherd 1.24.0 → 1.26.0

package/kit/hooks/hooks/open-question/record.ts

@@ -13,8 +13,20 @@ export type QuestionRecord = {
   cwd: string
   session: string
   closedAt: number | null
+  /** Who closed the record and why; absent or null on a record that predates the field or is open. */
+  closedReason?: string | null
+  /** A later dialog's question that probably answered this one in other words; null or absent when none did. */
+  supersededBy?: SupersededBy | null
+  /** When the session that asked this question ended with it still open (the `SessionEnd` hook); null or absent while it runs. */
+  sessionEndedAt?: number | null
 }
 
+/** A later dialog's question that answered a record's question, and when. */
+export type SupersededBy = AnsweredQuestion
+
+const isSupersededBy = (value: unknown): value is SupersededBy =>
+  isRecord(value) && typeof value.question === 'string' && typeof value.answeredAt === 'number'
+
 export type QuestionContext = {
   cwd: string
   session: string
@@ -76,6 +88,26 @@ const resultsOf = (entries: readonly JsonObject[]): Map<string, JsonObject | nul
   return results
 }
 
+/** How the client words the result of a dialog that a `PreToolUse` hook sent back: the user never saw it. */
+const HOOK_REFUSAL = new RegExp(`^PreToolUse:${ASK_USER_QUESTION_TOOL} hook error`)
+
+const resultTextOf = (block: JsonObject): string => {
+  if (typeof block.content === 'string') return block.content
+  if (!Array.isArray(block.content)) return ''
+  return block.content.map((part) => (isRecord(part) && typeof part.text === 'string' ? part.text : '')).join('\n')
+}
+
+/** The ids of the dialog calls a hook refused: the user was never asked, so they leave nothing open. */
+const refusedByHookOf = (entries: readonly JsonObject[]): Set<string> =>
+  new Set(
+    entries.flatMap((entry) =>
+      contentOf(entry)
+        .filter((block) => block.type === CONTENT_BLOCK_TYPE.toolResult && block.is_error === true)
+        .filter((block) => HOOK_REFUSAL.test(resultTextOf(block)))
+        .flatMap((block) => (typeof block.tool_use_id === 'string' ? [block.tool_use_id] : [])),
+    ),
+  )
+
 /** Whether the transcript went on after the call, other than with the rest of the message that made it. */
 const wentOnAfter = (ask: Ask, entries: readonly JsonObject[]): boolean =>
   entries
@@ -102,6 +134,49 @@ export const answeredSince = (
   at: number,
 ): AnsweredQuestion | undefined => answered.find((done) => done.question === question && done.answeredAt > at)
 
+/** The reason a record carries when a later dialog answered its question; the package's `closeReasonOf` spells it the same (contract test). */
+export const ANSWERED_REASON = 'user: answered in a dialog'
+
+/** Fewest words the shorter of two questions has to carry before one can be taken for a rewording of the other. */
+const MIN_REWORDED_WORDS = 3
+/** Share of the longer question's words the shorter one has to keep, with no word of its own besides. */
+const MIN_REWORDED_SHARE = 0.7
+
+/** Most words the longer question may add: one more word can be a restriction (`lane A`), two or more are another question. */
+const MAX_EXTRA_WORDS = 1
+/** A word that turns a question around: adding one is no rewording (`run it` against `do not run it`). */
+const NEGATIONS: ReadonlySet<string> = new Set(['nicht', 'kein', 'keine', 'keinen', 'nie', 'not', 'no', 'never'])
+
+const wordsOf = (question: string): Set<string> =>
+  new Set(question.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter((word) => word !== ''))
+
+/**
+ * Whether two different questions read as one asked twice: all the words of the shorter one are in the longer one,
+ * and they are most of it. A word that only one side has and the other lacks (`A` against `B`, `export` against
+ * `import`) makes them two questions.
+ */
+export const isRewording = (left: string, right: string): boolean => {
+  const [short, long] = [wordsOf(left), wordsOf(right)].sort((first, second) => first.size - second.size)
+  if (short.size < MIN_REWORDED_WORDS || short.size / long.size < MIN_REWORDED_SHARE) return false
+  if (![...short].every((word) => long.has(word))) return false
+  const extra = [...long].filter((word) => !short.has(word))
+  return extra.length <= MAX_EXTRA_WORDS && !extra.some((word) => NEGATIONS.has(word))
+}
+
+/**
+ * The record with `supersededBy` set to the first dialog after it that answered a different question that reads as the
+ * same one reworded; the record itself when none did or one is set already. Only a suspicion for the coordinator to
+ * weigh: it never closes the record.
+ */
+export const withSupersededBy = (record: QuestionRecord, answered: readonly AnsweredQuestion[]): QuestionRecord => {
+  if (record.closedAt !== null || record.supersededBy) return record
+  const later = answered.find(
+    ({ question, answeredAt }) =>
+      answeredAt > record.askedAt && question !== record.question && isRewording(question, record.question),
+  )
+  return later ? { ...record, supersededBy: { question: later.question, answeredAt: later.answeredAt } } : record
+}
+
 /**
  * The questions of the main thread that stand open: their dialog was rejected or interrupted, or answered with "later",
  * and no dialog answered the same text since. A call that carries its own answers asked nobody; a sidechain is no dialog
@@ -110,7 +185,9 @@ export const answeredSince = (
 export const openQuestionsOf = (entries: readonly unknown[], context: QuestionContext): QuestionRecord[] => {
   const thread = mainThread(entries)
   const results = resultsOf(thread)
+  const refused = refusedByHookOf(thread)
   return asksOf(thread)
+    .filter((ask) => !refused.has(ask.toolUseId))
     .filter((ask) => endedUnanswered(ask, results, thread))
     .map((ask) => ({ ask, question: questionTextOf(ask.question) }))
     .filter(({ ask, question }) => question !== '' && !answeredSince(context.answered, question, ask.askedAt))
@@ -133,4 +210,7 @@ export const isQuestionRecord = (value: unknown): value is QuestionRecord =>
   typeof value.askedAt === 'number' &&
   typeof value.cwd === 'string' &&
   typeof value.session === 'string' &&
-  (value.closedAt === null || typeof value.closedAt === 'number')
+  (value.closedAt === null || typeof value.closedAt === 'number') &&
+  (value.closedReason == null || typeof value.closedReason === 'string') &&
+  (value.supersededBy == null || isSupersededBy(value.supersededBy)) &&
+  (value.sessionEndedAt == null || typeof value.sessionEndedAt === 'number')

package/kit/hooks/hooks/open-question/run.ts

@@ -1,6 +1,13 @@
 import { ASK_USER_QUESTION_TOOL, parseTranscript } from '../shared/dialog-answers'
 import { isRecord } from '../shared/json'
-import { answeredQuestionsOf, answeredSince, openQuestionsOf, type QuestionRecord } from './record'
+import {
+  ANSWERED_REASON,
+  answeredQuestionsOf,
+  answeredSince,
+  openQuestionsOf,
+  type QuestionRecord,
+  withSupersededBy,
+} from './record'
 
 /** Everything with a side effect, passed in so a test reaches the flow without git, files or a clock. */
 export type OpenQuestionDependencies = {
@@ -42,14 +49,21 @@ export const runOpenQuestion = (input: unknown, dependencies: OpenQuestionDepend
     const answered = answeredQuestionsOf(entries)
     for (const record of stored.filter(({ closedAt }) => closedAt === null)) {
       const answer = answeredSince(answered, record.question, record.askedAt)
-      if (answer) dependencies.writeRecord(main, { ...record, closedAt: answer.answeredAt })
+      if (answer) {
+        dependencies.writeRecord(main, { ...record, closedAt: answer.answeredAt, closedReason: ANSWERED_REASON })
+        continue
+      }
+      if (record.session !== session) continue
+      const marked = withSupersededBy(record, answered)
+      if (marked !== record) dependencies.writeRecord(main, marked)
+      else if (record.sessionEndedAt != null) dependencies.writeRecord(main, { ...record, sessionEndedAt: null })
     }
     const known = new Set(stored.map(({ id }) => id))
     const openTexts = new Set(stored.filter(({ closedAt }) => closedAt === null).map(({ question }) => question))
     for (const record of openQuestionsOf(entries, { cwd, session, answered, idOf: dependencies.idOf })) {
       if (known.has(record.id) || openTexts.has(record.question)) continue
       openTexts.add(record.question)
-      dependencies.writeRecord(main, record)
+      dependencies.writeRecord(main, withSupersededBy(record, answered))
     }
   } catch {
     // A failed record is no record; the herd shows no question.

package/kit/hooks/hooks/question-session-end/index.ts

@@ -0,0 +1,18 @@
+// SessionEnd hook of Claude Code, shipped by jackherd: marks the still open question records that the ending session
+// asked (`sessionEndedAt` in `.jackherd/questions/` of the main checkout), also on `/clear`, so the watcher can propose
+// them as `session ended`. It marks only its own session's records, prints nothing, never blocks and always exits 0.
+import { mainCheckoutOf } from '../shared/checkout'
+import { readQuestionRecords, writeQuestionRecord } from '../open-question/store'
+import { runQuestionSessionEnd } from './run'
+
+try {
+  runQuestionSessionEnd(JSON.parse(await Bun.stdin.text()), {
+    mainCheckoutOf,
+    readRecords: readQuestionRecords,
+    writeRecord: writeQuestionRecord,
+    now: Date.now,
+  })
+} catch {
+  // Unreadable input marks nothing.
+}
+process.exit(0)

package/kit/hooks/hooks/question-session-end/run.ts

@@ -0,0 +1,37 @@
+import { isRecord } from '../shared/json'
+import type { QuestionRecord } from '../open-question/record'
+
+/** Everything with a side effect, passed in so a test reaches the flow without git, files or a clock. */
+export type SessionEndDependencies = {
+  mainCheckoutOf: (cwd: string) => string
+  readRecords: (main: string) => QuestionRecord[]
+  writeRecord: (main: string, record: QuestionRecord) => void
+  now: () => number
+}
+
+/**
+ * The open question records that `session` asked and that carry no end mark yet, marked `sessionEndedAt`. Only the
+ * records of the ending session: another session in the same directory is not touched.
+ */
+export const endedRecords = (records: readonly QuestionRecord[], session: string, now: number): QuestionRecord[] =>
+  records
+    .filter((record) => record.session === session && record.closedAt === null && record.sessionEndedAt == null)
+    .map((record) => ({ ...record, sessionEndedAt: now }))
+
+/**
+ * Marks the ending session's still open questions. Claude Code's `SessionEnd` hook input: `session_id`, `cwd`, `reason`
+ * (`clear`, `logout`, `prompt_input_exit`, `resume`, `other`); every reason ends the session's own questions, the mark
+ * is only a suspicion for the watcher to propose. Writes nothing on any failure.
+ */
+export const runQuestionSessionEnd = (input: unknown, dependencies: SessionEndDependencies): void => {
+  try {
+    if (!isRecord(input)) return
+    const { cwd, session_id: session } = input
+    if (typeof cwd !== 'string' || typeof session !== 'string') return
+    const main = dependencies.mainCheckoutOf(cwd)
+    for (const record of endedRecords(dependencies.readRecords(main), session, dependencies.now()))
+      dependencies.writeRecord(main, record)
+  } catch {
+    // A failed mark is no mark; the question stays open as before.
+  }
+}

package/kit/hooks/hooks/sent-file/record.ts

@@ -15,6 +15,8 @@ export type SentRecord = {
   session: string
   agentId: string | null
   closedAt: number | null
+  /** Who closed the record and why; absent or null on a record that predates the field or is open. */
+  closedReason?: string | null
 }
 
 export type SentCall = {
@@ -125,4 +127,5 @@ export const isSentRecord = (value: unknown): value is SentRecord =>
   typeof value.cwd === 'string' &&
   typeof value.session === 'string' &&
   (value.agentId === null || typeof value.agentId === 'string') &&
-  (value.closedAt === null || typeof value.closedAt === 'number')
+  (value.closedAt === null || typeof value.closedAt === 'number') &&
+  (value.closedReason == null || typeof value.closedReason === 'string')

package/kit/hooks/hooks/shared/board-lanes.ts

@@ -27,16 +27,38 @@ const PLAN_COLUMN = 2
 
 const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
-const sectionLines = (markdown: string, heading: string): string[] => {
+const MARKER = /<!--\s*jh:\s*([a-z-]+)\s*-->/
+
+const markerOf = (text: string | undefined): string | undefined => (text === undefined ? undefined : MARKER.exec(text)?.[1])
+
+const languagesFrom = (language: BoardLanguage): BoardLanguage[] =>
+  [language, ...(Object.keys(BOARD_WORDS) as BoardLanguage[]).filter((other) => other !== language)]
+
+/** The index of the lanes section's heading: the marker `<!-- jh: lanes -->` under it, else the heading of `language`, else of the other language. */
+const lanesHeadingIndex = (lines: string[], language: BoardLanguage): number => {
+  const marked = lines.findIndex((line, index) => SECTION_END.test(line) && markerOf(lines[index + 1]) === 'lanes')
+  if (marked !== -1) return marked
+  for (const candidate of languagesFrom(language)) {
+    const pattern = new RegExp(`^##\\s+${escapeRegExp(BOARD_WORDS[candidate].lanes)}\\s*$`)
+    const found = lines.findIndex((line) => pattern.test(line))
+    if (found !== -1) return found
+  }
+  return -1
+}
+
+const lanesSectionLines = (markdown: string, language: BoardLanguage): string[] => {
   const lines = markdown.split('\n')
-  const pattern = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`)
-  const start = lines.findIndex((line) => pattern.test(line))
-  if (start === -1) return []
-  const rest = lines.slice(start + 1)
+  const heading = lanesHeadingIndex(lines, language)
+  if (heading === -1) return []
+  const rest = lines.slice(heading + 1)
   const end = rest.findIndex((line) => SECTION_END.test(line))
   return end === -1 ? rest : rest.slice(0, end)
 }
 
+/** Whether a lane's name cell says the lane was cleaned up: the marker `<!-- jh: lane-closed -->`, or the word of any language. */
+const isClosedCell = (cell: string): boolean =>
+  markerOf(cell) === 'lane-closed' || Object.values(BOARD_WORDS).some(({ laneClosed }) => cell.includes(laneClosed))
+
 const cellsOf = (line: string): string[] =>
   line
     .slice(1, line.endsWith('|') ? -1 : undefined)
@@ -55,7 +77,7 @@ const firstTableLines = (lines: string[]): string[] => {
 const laneRows = (markdown: string, language: BoardLanguage): Row[] => {
   const rows: Row[] = []
   let previous: string | null = null
-  for (const line of firstTableLines(sectionLines(markdown, BOARD_WORDS[language].lanes))) {
+  for (const line of firstTableLines(lanesSectionLines(markdown, language))) {
     const cells = cellsOf(line)
     const first = cells[0] ?? ''
     const lane: string | null = first.match(LANE_NAME)?.[1] ?? (first.startsWith(CONTINUATION) ? previous : null)
@@ -73,11 +95,11 @@ const planPathOf = (boardDirectory: string, cell: string): string[] => {
 }
 
 /** The rows of one lane since it was last cleaned up: a named row without the mark after a closed one starts it anew. */
-const currentRows = <Row extends { cells: string[] }>(rows: Row[], closedWord: string): Row[] =>
+const currentRows = <Row extends { cells: string[] }>(rows: Row[]): Row[] =>
   rows.reduce<{ closed: boolean; kept: Row[] }>(
     ({ closed, kept }, row) => {
       const first = row.cells[0] ?? ''
-      const marked = first.includes(closedWord)
+      const marked = isClosedCell(first)
       const startsAnew = closed && !marked && !first.startsWith(CONTINUATION)
       return { closed: marked || (closed && !startsAnew), kept: startsAnew ? [row] : [...kept, row] }
     },
@@ -100,11 +122,10 @@ export const boardPlansOf = (markdown: string, boardDirectory: string, language:
 
 /** Every lane the lanes table names whose current rows do not say it was cleaned up, in table order, read in one pass. */
 export const openLaneNamesOf = (markdown: string, language: BoardLanguage): string[] => {
-  const { laneClosed } = BOARD_WORDS[language]
   const rowsByLane = new Map<string, Row[]>()
   for (const row of laneRows(markdown, language)) rowsByLane.set(row.lane, [...(rowsByLane.get(row.lane) ?? []), row])
   return [...rowsByLane].flatMap(([lane, rows]) =>
-    currentRows(rows, laneClosed).some(({ cells }) => (cells[0] ?? '').includes(laneClosed)) ? [] : [lane],
+    currentRows(rows).some(({ cells }) => isClosedCell(cells[0] ?? '')) ? [] : [lane],
   )
 }
 
@@ -117,9 +138,9 @@ export const lanePlansOf = (
 ): LanePlans | undefined => {
   const all = laneRows(markdown, language).filter((row) => row.lane === lane)
   if (all.length === 0) return undefined
-  const rows = currentRows(all, BOARD_WORDS[language].laneClosed)
+  const rows = currentRows(all)
   return {
-    closed: rows.some(({ cells }) => (cells[0] ?? '').includes(BOARD_WORDS[language].laneClosed)),
+    closed: rows.some(({ cells }) => isClosedCell(cells[0] ?? '')),
     plans: [...new Set(rows.flatMap(({ cells }) => planPathOf(boardDirectory, cells[PLAN_COLUMN] ?? '')))],
   }
 }

package/kit/hooks/hooks/shared/boards.ts

@@ -12,9 +12,13 @@ import { isRepositoryDirectory } from './repository-directory'
 /** A board's directory relative to the repository, and its text. */
 export type Board = { directory: string; text: string }
 
-/** The plan language, the plan directory and the board pattern and file below it, and where the lane worktrees live. */
+/**
+ * The plan language, the language the board is written in (the plan language when the config sets none), the plan
+ * directory and the board pattern and file below it, and where the lane worktrees live.
+ */
 export type BoardLocation = {
   planLanguage: BoardLanguage
+  boardLanguage: BoardLanguage
   planDirectory: string
   board: { pattern: string; file: string }
   worktreeDirectory: string
@@ -42,8 +46,16 @@ const isPlanLanguage = (value: unknown): value is BoardLanguage => typeof value
  * The board location's values of a config, each with its default where absent and `undefined` where present but
  * invalid; `board` is the config's `board` section.
  */
-export const boardLocationValues = (config: Record<string, unknown>, board: Record<string, unknown>) => ({
-  planLanguage: valueOr(config, 'planLanguage', isPlanLanguage, 'en'),
+export const boardLocationValues = (config: Record<string, unknown>, board: Record<string, unknown>) => {
+  const planLanguage = valueOr(config, 'planLanguage', isPlanLanguage, 'en')
+  return {
+    planLanguage,
+    boardLanguage: valueOr(config, 'boardLanguage', isPlanLanguage, planLanguage ?? 'en'),
+    ...directoryValues(config, board),
+  }
+}
+
+const directoryValues = (config: Record<string, unknown>, board: Record<string, unknown>) => ({
   planDirectory: valueOr(config, 'planDirectory', isRepositoryDirectory, 'docs/plans'),
   pattern: valueOr(board, 'pattern', matches(BOARD_PATTERN), 'board-*'),
   file: valueOr(board, 'file', matches(BOARD_FILE), 'board.md'),
@@ -54,10 +66,14 @@ export const boardLocationValues = (config: Record<string, unknown>, board: Reco
 export const boardLocationOf = (config: Record<string, unknown>): BoardLocation | null => {
   const board = config.board ?? {}
   if (!isRecord(board)) return null
-  const { planLanguage, planDirectory, pattern, file, worktreeDirectory } = boardLocationValues(config, board)
-  if (planLanguage === undefined || planDirectory === undefined || worktreeDirectory === undefined) return null
+  const { planLanguage, boardLanguage, planDirectory, pattern, file, worktreeDirectory } = boardLocationValues(
+    config,
+    board,
+  )
+  if (planLanguage === undefined || boardLanguage === undefined) return null
+  if (planDirectory === undefined || worktreeDirectory === undefined) return null
   if (pattern === undefined || file === undefined) return null
-  return { planLanguage, planDirectory, board: { pattern, file }, worktreeDirectory }
+  return { planLanguage, boardLanguage, planDirectory, board: { pattern, file }, worktreeDirectory }
 }
 
 /** The boards under the plan directory of the main checkout whose directory name matches the board pattern. */

package/kit/hooks/hooks.json

@@ -96,6 +96,14 @@
       "timeout": 10
     }
   },
+  "question-session-end": {
+    "event": "SessionEnd",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/question-session-end/index.ts",
+      "timeout": 5
+    }
+  },
   "return-brief": {
     "event": "UserPromptSubmit",
     "handler": {

package/kit/workflow/skills/orchestrate/references/herd.md

@@ -8,13 +8,13 @@ is missing or comes twice.
 It reads the plans at `origin/{{kit.baseBranch}}`. From a lane's worktree, once the lane has work
 there, it takes the phases the lane's rows name and any phase that is new there or ticked further
 than on the base. It redraws when a plan file changes or a fetch of the base branch lands in the
-main checkout (the watcher fetches it as soon as the remote moved). While it runs, it also sets each
-lane's sidebar title (`P4 · 7/12`) and clears it on exit.
+main checkout (the watcher fetches it as soon as the remote moved). While it runs it sets each
+lane's sidebar title (`P4 · 7/12`), clearing it on exit. An opened lane adds each phase's purpose line.
 
 A phase the lane ticked to the end in its worktree stays its current phase until the base branch
 carries its ticks (the watcher marks it `abgehakt, nicht gemergt` / `ticked, not merged`; the herd
 shows the branch's `↑n` instead); an open phase the lane works on goes first. The lane's newest row decides
-which phases count: ticks in an older phase (tidying the plan) take over only when that row names no
+which phases count: ticks in an older phase take over only when that row names no
 phase or only merged ones, which is why each new row starts with its phase number (§ 2 step 5).
 
 ## Notices per lane

package/kit/workflow/skills/orchestrate/references/waiting.md

@@ -1,6 +1,6 @@
 # § 4 Waiting for you: the rows beyond the basic one
 
-Read when `jh waiting` or the heartbeat's `for you (<n>)` names this file, a lane waits on the user's answer,
+Read when a watcher line `waiting closed` or `waiting obsolete?`, `jh waiting` or the heartbeat's `for you (<n>)` names this file, a lane waits on the user's answer,
 or something you sent the user needs no row of its own.
 
 - **A lane waits on the answer:** add its name as in the lanes table (a phase may follow) to the optional
@@ -14,3 +14,17 @@ or something you sent the user needs no row of its own.
   the user's. A dialog that ended without an answer (declined, cut off, or answered "later") needs none
   either: the kit hook `open-question` records it, and it closes once the same question is answered in a
   dialog.
+- **The watcher closes a send by itself** when a newer send has the same first entry (`newer version: <id>`,
+  whoever sent it) or its lane's worktree stayed gone for two heartbeats (`lane removed: <name>`), and reports
+  `waiting closed <n>: <id> <reason>; …`. `jh waiting --closed` lists the last 24 hours with reasons.
+- **A proposal `waiting obsolete? <key> <reason> "<text>"`** closes nothing and comes once per reason. Check
+  it against the thing itself. A key `row-…` is a board row (find it by the quoted text): set its status cell to
+  `done` (`erledigt` in a German board) with `(<you> <DD.MM.> <HH:MM>: <why>)`; the table is yours alone, no
+  code writes into it. Any other key is a record id: `jh waiting close <id> --reason "<why>"`. A thing still
+  wanted stays open. Reasons: `pr #<n> merged|closed`,
+  `lane removed: <name>`, `superseded: <question>` (a later dialog answered it in nearly the same words),
+  `session ended`.
+- **A decision the hooks cannot see** (made in the chat or in a lane's report, written into the board by you):
+  close the records it settles in the same turn, `jh waiting close <id> --reason "decided: <decision>"`.
+- **A board row's key is a hash of its item text:** a reworded row gets a new key and can raise its proposal
+  again, as can an unreadable `.jackherd/sent`; close it then.

package/kit/workflow/skills/plan/SKILL.md

@@ -11,6 +11,8 @@ You create a structured concept/plan document in `{{kit.planDirectory}}/`.
 > written in {{kit.planLanguage}}. Keep the section headings of the template **verbatim** — the plan
 > parser, `/implement` and `spec-review` find `## {{kit.heading.decisions}}`,
 > `## {{kit.heading.implementation}}` and `## {{kit.heading.documentation}}` by those exact names.
+> Another language: each heading, table head and purpose line carries `<!-- jh: <key> -->` (keys:
+> `docs/plan-contract.md`, "Language and markers"); done when `jh plan check` shows no `missing`.
 
 ## Your Workflow
 
@@ -36,7 +38,7 @@ The closing documentation section reads `## N — …` with rows `N.1` to `N.5`:
 
 A checkbox moved on purpose to a later phase stays where it is, unticked, and ends in the target: `- [ ] Update the documentation → P9`. The herd counts it neither as open nor as done in its own phase and lists it as open in phase 9. The arrow stands only at the end of the line. Once a phase's tasks are ticked on the base branch, every box still open in it, gate boxes included, is ticked or moved on this way; `jh check` checks both.
 
-A task starts with its short name: `- [ ] **Name**: …` (a review-gate item keeps its own form). The name has 40 characters at most and names the subject and the result (`Heartbeat shows progress without ticks`); the how, the conditions, the origin and the evidence follow the colon. A phase's title is its name; its context goes into its origin line, a quote under the heading (`> Origin: …`, in the plan's language). A task the user adds later: `- [ ] **Name**: … (User <DD.MM.> <HH:MM>)`.
+A task starts with its short name: `- [ ] **Name**: …` (a review-gate item keeps its own form). The name has 40 characters at most and names the subject and the result (`Heartbeat shows progress without ticks`); the how, the conditions, the origin and the evidence follow the colon. A phase's title is its name; directly under it stands the purpose line of the template, one sentence saying what is different afterwards and for whom, so that a reader outside the project understands the phase from that line alone; `jh check` asks for it on every new phase. The phase's context goes into its origin line, a quote below the purpose line (`> Origin: …`, in the plan's language). A task the user adds later: `- [ ] **Name**: … (User <DD.MM.> <HH:MM>)`.
 
 An Artifact that belongs to the plan (a mockup, a draft for review, a findings page) stands as a Markdown link with its title in the phase it concerns, in the same move as its first publish: `**Mockup:** [Title](url)` or in the origin line. The herd shows them as chips; nothing else ties an Artifact published from the main checkout to the lane.
 

package/kit/workflow/skills/plan/references/template-English.md

@@ -50,6 +50,8 @@ What changes concretely? Files, modules, flows.
 
 ### {{kit.heading.phase}} 1: ...
 
+**What it is about:** what is different afterwards, for whom; "nothing visible" when that is the case
+
 - [ ] **Name of step 1**: how, conditions, origin, evidence
 - [ ] **Name of step 2**: how, conditions, origin, evidence
 

package/kit/workflow/skills/plan/references/template-German.md

@@ -50,6 +50,8 @@ Was ändert sich konkret? Dateien, Module, Flows.
 
 ### {{kit.heading.phase}} 1: ...
 
+**Worum es geht:** was danach anders ist, für wen; „nichts Sichtbares“, wenn das so ist
+
 - [ ] **Name von Schritt 1**: Wie, Bedingungen, Herkunft, Beleg
 - [ ] **Name von Schritt 2**: Wie, Bedingungen, Herkunft, Beleg
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/schemas/jackherd.schema.json

@@ -29,6 +29,13 @@
         "en"
       ]
     },
+    "boardLanguage": {
+      "type": "string",
+      "enum": [
+        "de",
+        "en"
+      ]
+    },
     "planDirectory": {
       "default": "docs/plans",
       "type": "string",

package/src/brief/command.ts

@@ -35,7 +35,7 @@ export const run = async (args: string[]): Promise<number> => {
     const here = worktreeRoot(process.cwd())
     const settings = readSettings([here, root])
     const picked = boardFor(boardPath, [root, here], settings, () => foundLanesOf(root, settings, () => []))
-    for (const line of briefLines(laneFactsOf(root, settings, picked.file, Date.now()), settings.planLanguage))
+    for (const line of briefLines(laneFactsOf(root, settings, picked.file, Date.now()), settings.boardLanguage))
       console.log(line)
     return 0
   } catch (error) {

package/src/brief/lane-facts.ts

@@ -3,7 +3,7 @@ import { dirname, join, relative } from 'node:path'
 import { parseSprintLanes, resolvePlanPath, type SprintLane } from '../plan-format'
 import { type QuestionRecord } from '../plans/question-records'
 import { type SentFileRecord, sentLaneOf } from '../plans/sent-files'
-import type { PlansSettings } from '../plans/settings'
+import { type PlansSettings } from '../plans/settings'
 import { laneDirectoryOf } from '../plans/unlisted-lanes'
 import { readWaitingRecords } from '../plans/waiting-records'
 import { isStillWaiting } from '../plans/waiting-window'
@@ -49,7 +49,7 @@ export const laneFactsOf = (root: string, settings: PlansSettings, boardFile: st
   const sprintDirectory = dirname(relative(root, boardFile))
   const worktreeDirectory = join(root, settings.worktreeDirectory)
   const records = readWaitingRecords(root)
-  return parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.planLanguage)
+  return parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.boardLanguage)
     .filter(({ closed }) => !closed)
     .map((lane) => {
       const href = planHrefOf(lane)

package/src/check/command.ts

@@ -223,7 +223,7 @@ const openBoxesCheckOf = (root: string, settings: CheckSettings): CheckResult |
         lane,
         planDirectory: settings.planDirectory,
         board: settings.board,
-        language: settings.planLanguage,
+        language: settings.boardLanguage,
         level: settings.check.openBoxes,
         baseOf: contentAt(root, baseRefOf(settings)),
       })
@@ -253,6 +253,7 @@ const ownChecksOf = (
     paths,
     planDirectory: settings.planDirectory,
     language: settings.planLanguage,
+    boardLanguage: settings.boardLanguage,
     previousOf: contentAt(root, 'HEAD'),
     baseOf: contentAt(root, baseRefOf(settings)),
     planRoots: planRootsOf(root, settings.worktreeDirectory),