jackherd 1.23.3 → 1.25.0

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.23.3"
+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.23.3}"
+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)
 }

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/workflow/skills/orchestrate/SKILL.md

@@ -86,7 +86,8 @@ through steps 0 to 8. One line to the user afterwards.
 ## 3. Dev server
 
 A lane whose phase changes something a user sees gets its dev server **when the lane starts**:
-[`references/start-lane.md`](references/start-lane.md).
+[`references/start-lane.md`](references/start-lane.md); with `lanes.backend`, the services of the shared backend:
+[`references/backend.md`](references/backend.md).
 
 ## 4. Watch
 

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

@@ -0,0 +1,30 @@
+# § 3: the shared backend of `lanes.backend`
+
+Read on a `backend:` watcher line, or at a lane's start (`start-lane.md` § 3) when `lanes.backend`
+is set. The services every lane's app talks to run in one pane of a tab in the main checkout; the watcher starts and
+keeps it. Without `lanes.backend` nothing here applies.
+
+## At a lane's start
+
+When the phase's Writes column names a path of one of those services, hand that service to the lane first, from the
+main checkout: `jh backend release <service> --lane <lane>` restarts the backend pane without it and prints the freed
+port; then `jh lane dev <lane> --filter <service> --port <port>`. Only you call `jh backend release`, from the main
+checkout; a lane that finds out later asks in its report. Before `jh lane close`, stop the lane's dev server, then
+`jh backend return <service>`; done when it prints that the service returned. Skipped, the watcher returns it once the
+worktree is gone.
+
+## Watcher lines
+
+Each line is said once while it stands, without the `backend: ` prefix. A `kit updated` leaves the pane running.
+
+| Line | What to do |
+| --- | --- |
+| `started in <pane>` | Nothing. |
+| `port <n> in use, not started` | Find the holder as in `start-lane.md` § 3; a lane's server for a handed-over service (`jh backend` lists them) is the lane's, any other goes to the user. The pane starts once the port is free. |
+| `running command differs from lanes.backend` | The config changed after the start. Tell the user once; `jh backend restart` after they agree, since it stops the services. |
+| `gave up after 3 starts in 10 minutes` | The command ends right after it starts. Read the pane, tell the user the cause; `jh backend restart` once fixed. |
+| `<service> returned from <lane> (worktree gone)` | Nothing. |
+| `backend check failed, still watching: <reason>` | Fix the cause (herdr answering, one workspace of the main checkout, `lanes.backend` readable); done when `jh backend` shows the pane. |
+| `… left alone` (several panes with the label, an agent in the pane, a pane outside the main checkout) | Tell the user; the pane is theirs. |
+
+`jh backend` only ever stops the process in the backend pane; a pane it cannot read goes to the user.

package/kit/workflow/skills/orchestrate/references/close-lane.md

@@ -9,6 +9,7 @@ or when the user names a lane to close. Run both commands from the main checkout
    nothing: resolve each reason it prints (a named file goes to the user first, a working agent is waited for, a lock
    is lifted once its session ended, an unmerged branch is not closed) and repeat until it exits 0.
    A worktree on no branch closes when its head is on the base branch and only staged plan changes the base holds are left.
+   Handed-over service: [`backend.md`](backend.md).
 2. `jh lane close <lane>` Run it without asking the user; its checks are the safeguard. It repeats the step 1 checks (resolve a refusal as in step 1) and runs the listed steps, one line each. After a failure,
    run it again: with the worktree gone and the branch left, `jh lane close <lane> --branch <branch>` finishes the
    branch and the board; a lane closed in full says so and changes nothing.

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/start-lane.md

@@ -62,9 +62,9 @@ herdr pane run <new-pane> "PORT=<port> {{kit.command.dev}}"
 ```
 
 The new pane starts in the lane's worktree; check with `/proc/<pid>/cwd` (macOS: `lsof -p <pid>`) that the server runs
-there, and before stopping one by PID. Stop only a server you started; another's port
+there, also before stopping one by PID. Stop only a server you started; another's port
 goes to the user.
 
 To restart it after a rebase, stop it by PID (found through the port) once `/proc/<pid>/cwd` (macOS: `lsof -p <pid>`) shows
-the lane's worktree, then `herdr pane run <pane> "<the same command>"` in the same pane. Each step is a call of its own and
+the lane's worktree, then `herdr pane run <pane> "<the same command>"` in the same pane. Each step is its own call and
 passes the pane guard without a question; keys typed into the pane ask the user.

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.23.3",
+  "version": "1.25.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",
@@ -156,6 +163,48 @@
         "devCommand": {
           "type": "string",
           "minLength": 1
+        },
+        "backend": {
+          "type": "object",
+          "properties": {
+            "command": {
+              "type": "string",
+              "minLength": 1
+            },
+            "services": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "pattern": "^(?!-)[\\w@./:-]+$"
+                  },
+                  "port": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 65535
+                  }
+                },
+                "required": [
+                  "name",
+                  "port"
+                ],
+                "additionalProperties": false
+              }
+            },
+            "label": {
+              "default": "backend",
+              "type": "string",
+              "pattern": "^(?!-)[\\w.-]+$"
+            }
+          },
+          "required": [
+            "command",
+            "services"
+          ],
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/src/backend/command-line.ts

@@ -0,0 +1,116 @@
+import { readConfig } from '../config/read-config'
+import { TERMINAL_ADAPTER } from '../config/schema'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { mainCheckout } from '../plans/git'
+import { asksForHelp } from '../preview/options'
+import { CLI_NAME } from '../version/release'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+import {
+  type BackendOutcome,
+  type BackendSystem,
+  releaseService,
+  restartBackend,
+  returnService,
+  statusLines,
+} from './control'
+import { withBackendLock } from './lock'
+import type { BackendConfig } from './schema'
+import { backendFilesOf, backendSystemOf } from './system'
+
+/** The exit codes of `jh backend`: done, refused, and a call it does not understand. */
+export const BACKEND_EXIT = { done: 0, refused: 1, usage: 2 } as const
+
+export const BACKEND_REQUEST = { status: 'status', restart: 'restart', release: 'release', return: 'return' } as const
+
+/** What `jh backend` was asked for. */
+export type BackendRequest =
+  | { kind: typeof BACKEND_REQUEST.status }
+  | { kind: typeof BACKEND_REQUEST.restart }
+  | { kind: typeof BACKEND_REQUEST.release; service: string; lane: string }
+  | { kind: typeof BACKEND_REQUEST.return; service: string }
+
+const LANE = '--lane'
+
+/** How long a call waits for the watcher's check, which may itself wait for a stop. */
+const LOCK_WAIT_MS = 90_000
+
+export const BACKEND_USAGE = `usage: ${CLI_NAME} backend
+       ${CLI_NAME} backend restart
+       ${CLI_NAME} backend release <service> ${LANE} <lane>
+       ${CLI_NAME} backend return <service>
+
+The shared backend of the lanes (lanes.backend): one pane in a tab of the main checkout that the watcher starts and
+keeps. Without arguments it shows the pane, the command last started, the services handed to lanes and the recent
+starts. restart stops the pane, forgets "gave up" and starts it again. release takes a service out of the backend,
+so a lane runs it itself (${CLI_NAME} lane dev <lane> --filter <service> --port <port>); return puts it back. A busy
+service port prevents a start; nothing frees a port.`
+
+const usage = (): never => {
+  throw new Error(BACKEND_USAGE)
+}
+
+/** Reads the arguments of `jh backend`; throws with the usage on anything else. */
+export const parseBackendRequest = (args: readonly string[]): BackendRequest => {
+  const [kind, service, option, lane, ...rest] = args
+  if (kind === undefined) return { kind: BACKEND_REQUEST.status }
+  if (kind === BACKEND_REQUEST.restart && args.length === 1) return { kind }
+  if (kind === BACKEND_REQUEST.return && service !== undefined && args.length === 2) return { kind, service }
+  const isRelease = kind === BACKEND_REQUEST.release && service !== undefined && option === LANE
+  if (isRelease && lane !== undefined && rest.length === 0 && SAFE_LANE_NAME.test(lane)) return { kind, service, lane }
+  return usage()
+}
+
+/** Carries out `request` against the backend; the caller holds the lock. */
+export const carryOutRequest = async (
+  request: BackendRequest,
+  backend: BackendConfig,
+  system: BackendSystem,
+): Promise<BackendOutcome> => {
+  if (request.kind === BACKEND_REQUEST.restart) return restartBackend(backend, system)
+  if (request.kind === BACKEND_REQUEST.release) return releaseService(backend, system, request.service, request.lane)
+  if (request.kind === BACKEND_REQUEST.return) return returnService(backend, system, request.service)
+  return { ok: true, lines: statusLines(await system.look(), system.readState(), system.now()) }
+}
+
+/** The backend of the main checkout's own config: a lane's worktree must not change the command the main checkout runs. */
+const backendOfMainCheckout = (root: string) => {
+  const config = readConfig([root])
+  if (config.terminal.adapter !== TERMINAL_ADAPTER.herdr) throw new Error('backend: needs terminal.adapter herdr')
+  if (!config.lanes.backend) throw new Error('backend: no lanes.backend in the main checkout .jackherd/config.json')
+  return { backend: config.lanes.backend, worktreeDirectory: config.worktreeDirectory }
+}
+
+const print = (lines: readonly string[]) => {
+  for (const line of lines) console.log(terminalSafe(line))
+}
+
+/**
+ * `jh backend [restart | release <service> --lane <lane> | return <service>]`: works on the main checkout from any
+ * worktree. Exit 0 done, 1 refused, 2 usage.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(BACKEND_USAGE)
+    return BACKEND_EXIT.done
+  }
+  let request: BackendRequest
+  try {
+    request = parseBackendRequest(args)
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return BACKEND_EXIT.usage
+  }
+  try {
+    const root = mainCheckout(cwd)
+    const { backend, worktreeDirectory } = backendOfMainCheckout(root)
+    const files = backendFilesOf(root)
+    const system = backendSystemOf({ root, worktreeDirectory, backend, files })
+    const outcome = await withBackendLock(files.lock, LOCK_WAIT_MS, () => carryOutRequest(request, backend, system))
+    if (outcome === null) throw new Error('backend: the watcher holds the backend lock; try again in a minute')
+    print(outcome.lines)
+    return outcome.ok ? BACKEND_EXIT.done : BACKEND_EXIT.refused
+  } catch (error) {
+    console.error(terminalSafe(error instanceof Error ? error.message : String(error)))
+    return BACKEND_EXIT.refused
+  }
+}

package/src/backend/command.ts

@@ -0,0 +1,14 @@
+import { type BackendConfig, SERVICES_PLACEHOLDER } from './schema'
+
+/** Frees the lanes' `PORT` for the services: a service reading `PORT ?? <NAME>_PORT` must not bind a lane's port. */
+export const BACKEND_ENVIRONMENT_PREFIX = 'env -u PORT '
+
+/**
+ * The shell line of the backend pane: the configured command without `PORT`, with `{services}` filled by the services
+ * not handed to a lane, in configuration order. Null when none is left to run.
+ */
+export const backendCommandOf = (backend: BackendConfig, released: readonly string[]): string | null => {
+  const names = backend.services.map(({ name }) => name).filter((name) => !released.includes(name))
+  if (names.length === 0) return null
+  return `${BACKEND_ENVIRONMENT_PREFIX}${backend.command.replaceAll(SERVICES_PLACEHOLDER, names.join(' '))}`
+}