jackherd 1.18.2 → 1.20.0

package/src/brief/command.ts

@@ -0,0 +1,45 @@
+import { boardFor, foundLanesOf } from '../plans/board-pick'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { readSettings } from '../plans/settings'
+import { CLI_NAME } from '../version/release'
+import { briefLines } from './lane-brief'
+import { laneFactsOf } from './lane-facts'
+
+const USAGE = `usage: ${CLI_NAME} brief [--board <board.md>]`
+
+const BOARD_FLAG = '--board'
+
+/** The board a command line names (`--board <path>`), null for none; undefined for a command line that is wrong. */
+const boardOf = (args: readonly string[]): string | null | undefined => {
+  if (args.length === 0) return null
+  return args.length === 2 && args[0] === BOARD_FLAG ? args[1] : undefined
+}
+
+/**
+ * `jh brief` prints three lines for each open lane of the board: its goal, its status and what it needs from the
+ * user, from the head of its plan and from the user's open questions and sent files. Exit 0, 1 on a wrong command line
+ * or a board that cannot be read.
+ */
+export const run = async (args: string[]): Promise<number> => {
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(USAGE)
+    return 0
+  }
+  const boardPath = boardOf(args)
+  if (boardPath === undefined) {
+    console.error(USAGE)
+    return 1
+  }
+  try {
+    const root = mainCheckout(process.cwd())
+    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))
+      console.log(line)
+    return 0
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/brief/lane-brief.ts

@@ -0,0 +1,51 @@
+import { HEAD_LINE, type PlanLanguage, parsePlanHead } from '../plan-format'
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+
+/** What the brief needs of one lane: its name, the text of its plan (null without one) and what waits on the user in it. */
+export type LaneFacts = { name: string; plan: string | null; openQuestions: number; sentFiles: number }
+
+/** The most of a head line the brief shows; a longer one is cut with an ellipsis. */
+const LINE_WIDTH = 110
+
+const NO_OPEN_LANES = 'no open lanes'
+const HEAD_MISSING = 'head missing'
+const NO_PLAN_LINKED = 'no plan linked'
+const UNKNOWN = 'unknown'
+
+const counted = (count: number, noun: string): string => `${count} ${noun}${count === 1 ? '' : 's'}`
+
+const shown = (text: string): string => ellipsize(terminalSafe(text), LINE_WIDTH)
+
+/** What a lane needs from the user: its open decisions in the head, the open questions and the sent files, in numbers. */
+const needsOf = (decisions: string | undefined, { openQuestions, sentFiles }: LaneFacts): string => {
+  const parts = [
+    ...(decisions ? [shown(decisions)] : []),
+    ...(openQuestions > 0 ? [counted(openQuestions, 'open question')] : []),
+    ...(sentFiles > 0 ? [counted(sentFiles, 'sent file')] : []),
+  ]
+  return parts.length > 0 ? parts.join(' · ') : 'nothing'
+}
+
+/**
+ * The three lines of one lane: its goal (what changes for the user), its status and what it needs from the user. A
+ * lane whose plan has no head, or no plan at all, says so instead of guessing; the counts still show.
+ */
+export const laneBrief = (facts: LaneFacts, language: PlanLanguage): string[] => {
+  const head = facts.plan === null ? null : parsePlanHead(facts.plan, language)
+  const changes = head?.texts[HEAD_LINE.changes]
+  if (!head || !changes)
+    return [
+      `${facts.name} · ${facts.plan === null ? NO_PLAN_LINKED : HEAD_MISSING}`,
+      `  Status: ${UNKNOWN}`,
+      `  Needs you: ${needsOf(undefined, facts)}`,
+    ]
+  return [
+    `${facts.name} · Goal: ${shown(changes)}`,
+    `  Status: ${shown(head.texts[HEAD_LINE.status] ?? UNKNOWN)}`,
+    `  Needs you: ${needsOf(head.texts[HEAD_LINE.decisions], facts)}`,
+  ]
+}
+
+/** The brief of all lanes, three lines each; a note when none is open. */
+export const briefLines = (lanes: readonly LaneFacts[], language: PlanLanguage): string[] =>
+  lanes.length === 0 ? [NO_OPEN_LANES] : lanes.flatMap((lane) => laneBrief(lane, language))

package/src/brief/lane-facts.ts

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from 'node:fs'
+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 { laneDirectoryOf } from '../plans/unlisted-lanes'
+import { readWaitingRecords } from '../plans/waiting-records'
+import { isStillWaiting } from '../plans/waiting-window'
+import type { LaneFacts } from './lane-brief'
+
+/** The plan a lane works on: the link of its newest step that has one. */
+const planHrefOf = ({ steps }: SprintLane): string | null =>
+  steps.filter((step) => step.planHref !== null).at(-1)?.planHref ?? null
+
+/** The plan file as the lane's worktree has it (it ticks and writes the head there), else the main checkout's copy. */
+const planTextOf = (root: string, worktrees: string, lane: string, planPath: string): string | null => {
+  const candidates = [join(worktrees, lane, planPath), join(root, planPath)]
+  const found = candidates.find((path) => existsSync(path))
+  return found === undefined ? null : readFileSync(found, 'utf8')
+}
+
+const openQuestionsOf = (
+  records: readonly QuestionRecord[],
+  lane: string,
+  worktreeDirectory: string,
+  now: number,
+): number =>
+  records.filter(
+    ({ closedAt, askedAt, cwd }) =>
+      isStillWaiting(closedAt, askedAt, now) && laneDirectoryOf(cwd, worktreeDirectory) === lane,
+  ).length
+
+const openSendsOf = (
+  records: readonly SentFileRecord[],
+  lane: string,
+  worktreeDirectory: string,
+  now: number,
+): number =>
+  records.filter(
+    (record) => isStillWaiting(record.closedAt, record.sentAt, now) && sentLaneOf(record, worktreeDirectory) === lane,
+  ).length
+
+/**
+ * The facts of each open lane of the board `boardFile` names, read from the checkout `root` (the plan from the lane's
+ * worktree first) and from the open questions and sent files of the user's records.
+ */
+export const laneFactsOf = (root: string, settings: PlansSettings, boardFile: string, now: number): LaneFacts[] => {
+  const sprintDirectory = dirname(relative(root, boardFile))
+  const worktreeDirectory = join(root, settings.worktreeDirectory)
+  const records = readWaitingRecords(root)
+  return parseSprintLanes(readFileSync(boardFile, 'utf8'), settings.planLanguage)
+    .filter(({ closed }) => !closed)
+    .map((lane) => {
+      const href = planHrefOf(lane)
+      return {
+        name: lane.name,
+        plan:
+          href === null ? null : planTextOf(root, worktreeDirectory, lane.name, resolvePlanPath(sprintDirectory, href)),
+        openQuestions: openQuestionsOf(records.questions, lane.name, worktreeDirectory, now),
+        sentFiles: openSendsOf(records.sent, lane.name, worktreeDirectory, now),
+      }
+    })
+}

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

@@ -31,13 +31,18 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   // plan; the proof became a word diff, since a short name goes into an existing line (+74); skill-review: the
   // done check names `jh check`, the gate and short-name rules as the code reads them (+24).
   '.claude/skills/orchestrate/references/adopt-plan.md': 680,
-  '.claude/skills/orchestrate/references/acceptance.md': 200,
+  // Browser helper: the look goes to `browser-check`, and a session without `SendUserFile` names the paths (+50).
+  '.claude/skills/orchestrate/references/acceptance.md': 250,
   // Core cut: the `due` row of the wake-up table moved here (+33).
   '.claude/skills/orchestrate/references/appointments.md': 290,
   // Resume: `--branch` finishes a lane whose worktree is gone, a detached worktree on the base closes, a closed lane
   // is reported (+41).
   '.claude/skills/orchestrate/references/close-lane.md': 307,
-  '.claude/skills/orchestrate/references/coordinator-handover.md': 567,
+  // Clearing is the normal way: the hand-over names it and what the note leaves to `jh resume --coordinator`, and what
+  // a refused approval means (+63).
+  '.claude/skills/orchestrate/references/coordinator-handover.md': 630,
+  // New: runs on every clear and replaces the longer hand-over there.
+  '.claude/skills/orchestrate/references/coordinator-clear.md': 580,
   '.claude/skills/orchestrate/references/draft-review.md': 300,
   // P33: a source entry the user must read or decide becomes a row of what waits on them, and when it closes.
   // Core cut: the `deploy`, `stalled` and lane `warn` rows of the wake-up table moved here (+101), and the checks
@@ -79,6 +84,7 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   '.claude/skills/start/SKILL.md': 630,
   '.claude/skills/uncle-bob/SKILL.md': 466,
   '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 5100,
+  '.claude/agents/browser-check.md': 380,
   '.claude/agents/devops.md': 104,
   '.claude/agents/explore.md': 132,
   '.claude/agents/implement.md': 303,
@@ -102,6 +108,11 @@ export const KIT_SKILL_CEILINGS: Readonly<Record<string, number>> = {
   // Orchestrate core plan P1: the reviewer also judges the whole length of a file against its target (+12).
   // Lint before prose: lens 7 for lint-shaped prose and the sentence on the `Lint pointers` result (+33).
   '.claude/agents/skill-review.md': 513,
+  // Plan head: every plan opens with a `For you` head of five short lines a person reads first, which
+  // `jh plan check` reports; cut to its labels; skill-review: the status line says what `N` counts. Measured size (+42).
+  '.claude/skills/plan/references/template-English.md': 578,
+  // Plan head: the same `Für dich` head as the English template, with what `N` counts; measured size (+41).
+  '.claude/skills/plan/references/template-German.md': 542,
   // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
   // Plain words: no plan code without its words in a short question.
   // Any language: a pointer in § 0 and a section in events.md for `plan missing`.

package/src/cli.ts

@@ -19,6 +19,7 @@ const ALIASES = new Set<string>([HERD_COMMAND.alias])
 /** One line per command; each entry lazily imports the module that exports its `run`. */
 export const COMMANDS: CommandTable = {
   approval: () => import('./approval/command'),
+  brief: () => import('./brief/command'),
   check: () => import('./check/command'),
   config: () => import('./config/command'),
   context: () => import('./context/command'),

package/src/config/schema.ts

@@ -357,14 +357,34 @@ const repositorySources = z
     })
   })
 
+const DEFAULT_CLEAR_TOKENS = 250_000
+
 const coordinatorSchema = z
   .strictObject({
     /** Tokens in the coordinator's context from which the watcher reports `coordinator warn`. */
     warnTokens: tokenCount.default(350_000),
     /** Tokens in the coordinator's context from which the watcher reports `coordinator alert`. */
     alertTokens: tokenCount.default(500_000),
+    /**
+     * Tokens in the coordinator's context from which the watcher reports `coordinator clear` at a quiet moment; below
+     * `warnTokens`. Unset, 250 000, or just below `warnTokens` where a project set those lower.
+     */
+    clearTokens: tokenCount.optional(),
+    /**
+     * Tokens in the coordinator's context from which a merge with the board written afterwards is a moment to clear too.
+     * At or above `clearTokens`, a merge adds no moment of its own.
+     */
+    clearAfterMergeTokens: tokenCount.default(150_000),
   })
   .refine(warnBelowAlert, WARN_BELOW_ALERT)
+  .refine(({ clearTokens, warnTokens }) => clearTokens === undefined || clearTokens < warnTokens, {
+    message: 'clearTokens must be below warnTokens',
+    path: ['clearTokens'],
+  })
+  .transform(({ clearTokens, ...thresholds }) => ({
+    ...thresholds,
+    clearTokens: clearTokens ?? Math.min(DEFAULT_CLEAR_TOKENS, thresholds.warnTokens - 1),
+  }))
 
 /**
  * An SQL tool of an MCP server by its full name (`mcp__<server>__execute_sql`), never one whose name says `prod`. The
@@ -583,6 +603,8 @@ export const jackherdConfigSchema = z.strictObject({
       lockFile: lockFilePath.optional(),
       /** Free gigabytes the disk must hold before `jh lane space` lets a new lane install its dependencies; 5 when left out. */
       minFreeGb: z.number().positive().optional(),
+      /** The port `jh lane port` starts counting from when it picks a lane's dev-server port; 3100 when left out. */
+      basePort: z.number().int().min(1).max(65535).optional(),
     })
     .prefault({}),
   models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId).default(DEFAULT_MODELS),
@@ -602,6 +624,8 @@ export const jackherdConfigSchema = z.strictObject({
       fetchIntervalMinutes: z.number().min(0).default(5),
       /** The running task of a folded lane shimmers in `jh herd`; `false` keeps it still. `NO_COLOR` keeps it still too. */
       shimmer: z.boolean().default(true),
+      /** Minutes without a prompt after which the `return-brief` hook asks the coordinator to show `jh brief` first; 0 turns it off. */
+      briefAfterMinutes: z.number().min(0).default(60),
       /** Links in a plan that the sprint page shows as chips; the list replaces the built-in kinds. */
       linkKinds: z
         .array(

package/src/lane/command.ts

@@ -4,6 +4,7 @@ import { startLaneHintFor } from './start-lane-hint'
 
 const CLOSE = 'close'
 const SPACE = 'space'
+const PORT = 'port'
 const SEND = 'send'
 const BASE = 'base'
 
@@ -15,12 +16,13 @@ const withStartLaneHint = (code: number, args: readonly string[], cwd: string):
 }
 
 /**
- * `jh lane close …` closes a lane, `jh lane space …` checks the disk for a new one, `jh lane send …` sends its prompt
+ * `jh lane close …` closes a lane, `jh lane space …` checks the disk for a new one, `jh lane port …` names its dev-server port, `jh lane send …` sends its prompt
  * file, `jh lane base …` names the ref its worktree starts from, everything else is `jh lane prompt …`. `close` must
  * come first; `jh lane --board b.md close x` reaches the prompt parser and is refused there.
  */
 export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
   if (args[0] === SPACE) return (await import('./space-command')).run(args.slice(1), cwd)
+  if (args[0] === PORT) return (await import('./port-command')).run(args.slice(1), cwd)
   if (args[0] === SEND) return (await import('./send-command')).run(args.slice(1), cwd)
   if (args[0] === BASE)
     return withStartLaneHint(await (await import('./base-command')).run(args.slice(1), cwd), args.slice(1), cwd)

package/src/lane/port-command.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { parseSprintLanes } from '../plan-format'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { boardFor } from '../plans/board-pick'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { isPortListening } from '../plans/port-listening'
+import { readSettings } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { freePortNotListening, LANE_PORT_USAGE, MAX_PORT, parsePortOptions, portsOfRunningLanes } from './port'
+
+/**
+ * `jh lane port [--board <board.md>]`: prints the dev-server port for a new lane, the lowest from `lanes.basePort` that
+ * nothing listens on and no running lane of the board holds. Exit 0 printed, 1 on a wrong line, an unreadable board or
+ * no free port.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(LANE_PORT_USAGE)
+    return 0
+  }
+  try {
+    const { boardPath } = parsePortOptions(args)
+    const root = mainCheckout(cwd)
+    const settings = readSettings([root, worktreeRoot(cwd)])
+    const board = boardFor(boardPath === null ? null : resolve(cwd, boardPath), [root], settings, () => [])
+    if (board.notice) console.error(terminalSafe(board.notice))
+    const reserved = portsOfRunningLanes(parseSprintLanes(readFileSync(board.file, 'utf8'), settings.planLanguage))
+    const port = await freePortNotListening(settings.basePort, reserved, MAX_PORT, isPortListening)
+    if (port === null) throw new Error(`no free port from ${settings.basePort} to ${MAX_PORT}`)
+    console.log(port)
+    return 0
+  } catch (error) {
+    console.error(terminalSafe(error instanceof Error ? error.message : String(error)))
+    return 1
+  }
+}

package/src/lane/port.ts

@@ -0,0 +1,56 @@
+import type { SprintLane } from '../plan-format'
+import { CLI_NAME } from '../version/release'
+
+/** The port the first lane's dev server gets when the config names none (`lanes.basePort`). */
+export const DEFAULT_BASE_PORT = 3100
+
+/** The highest port a machine has. */
+export const MAX_PORT = 65535
+
+/** `boardPath` is null where `--board` was left out: the board is then picked as for `jh herd`. */
+export type PortOptions = { boardPath: string | null }
+
+const BOARD = '--board'
+
+export const LANE_PORT_USAGE = `usage: ${CLI_NAME} lane port [${BOARD} <board.md>]
+
+Prints the dev-server port for a new lane: the lowest port from lanes.basePort of the config (default ${DEFAULT_BASE_PORT})
+that nothing listens on and no lane still running holds in the port column of the board. Rows of cleaned-up lanes
+reserve nothing. Exit 1 and one line when no port up to ${MAX_PORT} is free.`
+
+/** The lowest port from `base` up to `max` (both included) that is not in `taken`; null when there is none. */
+export const firstFreePort = (base: number, taken: ReadonlySet<number>, max: number): number | null => {
+  for (let port = base; port <= max; port += 1) if (!taken.has(port)) return port
+  return null
+}
+
+/**
+ * The lowest port from `base` that is neither in `reserved` nor accepts a connection according to `isListening`; the
+ * probe is asked only for ports the board does not already hold. Null when none is free up to `max`.
+ */
+export const freePortNotListening = async (
+  base: number,
+  reserved: ReadonlySet<number>,
+  max: number,
+  isListening: (port: number) => Promise<boolean>,
+): Promise<number | null> => {
+  const taken = new Set(reserved)
+  for (let port = firstFreePort(base, taken, max); port !== null; port = firstFreePort(port, taken, max)) {
+    if (!(await isListening(port))) return port
+    taken.add(port)
+  }
+  return null
+}
+
+/** The ports the board's lanes that are not cleaned up hold; a lane without a port in its row reserves none. */
+export const portsOfRunningLanes = (lanes: readonly SprintLane[]): Set<number> =>
+  new Set(lanes.flatMap(({ port, closed }) => (closed || port === null ? [] : [port])))
+
+/** Reads `[--board <file>]`; throws with the usage on anything else. */
+export const parsePortOptions = (args: readonly string[]): PortOptions => {
+  if (args.length === 0) return { boardPath: null }
+  const [option, value, ...rest] = args
+  if (option !== BOARD || value === undefined || value.startsWith('--') || rest.length > 0)
+    throw new Error(LANE_PORT_USAGE)
+  return { boardPath: value }
+}

package/src/lane-prompt/texts.ts

@@ -52,7 +52,7 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
       'Ask before every commit (`/pre-commit` is the way where it is installed); git (commit, push, PR, merge) goes only through the coordinator and only with approval.',
     taskSignals: `Whatever skill builds a task, report it: \`${CLI_NAME} task start "<task>"\` before and \`${CLI_NAME} task done\` after every task. The herd shows the running task from that signal, and the watcher sees a standstill by it.`,
     report: (reportPath) =>
-      `The report at the end of each step goes to \`${reportPath}\` in the worktree, in the short form: one line of diff stat, one line per check with its numbers, open points, questions as a text block under the heading \`## Questions\` (whatever the report’s language: the watcher finds the section by that word and shows it whole); everything else is in the plan, by reference.`,
+      `The report at the end of each step goes to \`${reportPath}\` in the worktree, in the short form of \`/implement\` Step 6: five lines, each opening with its field, then the questions as a text block under the heading \`## Questions\` (whatever the report’s language: the watcher finds the section by that word and shows it whole); everything else is in the plan, by reference.`,
     textBlock:
       'Every question to the coordinator is a text block at the end of your turn, never a dialog (`AskUserQuestion`), also where a skill or a project rule asks for one, the commit confirmation of `/pre-commit` included: the question with the situation, the problem and what each option leads to, in everyday words (the user may not know your terms; a plan code like `P7` appears only in brackets after the words), the options, your recommendation, the evidence at `file:line`.',
     secret:
@@ -89,7 +89,7 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
       'Vor jedem Commit fragst du (`/pre-commit` ist der Weg, wo es installiert ist); Git (Commit, Push, PR, Merge) läuft nur über den Koordinator und nur mit Freigabe.',
     taskSignals: `Gleich mit welchem Skill eine Aufgabe gebaut wird, meldest du sie: \`${CLI_NAME} task start "<aufgabe>"\` vor und \`${CLI_NAME} task done\` nach jeder Aufgabe. Die Herde zeigt die laufende Aufgabe an diesem Signal, und der Watcher erkennt daran einen Stillstand.`,
     report: (reportPath) =>
-      `Den Bericht am Ende jedes Schritts schreibst du nach \`${reportPath}\` im Worktree, in der Kurzform: eine Zeile Diff-Stat, eine Zeile je Check mit seinen Zahlen, offene Punkte, Fragen als Textblock unter der Überschrift \`## Questions\` (in jeder Berichtssprache: der Watcher findet den Abschnitt an diesem Wort und zeigt ihn ganz); alles andere steht im Plan, per Verweis.`,
+      `Den Bericht am Ende jedes Schritts schreibst du nach \`${reportPath}\` im Worktree, in der Kurzform von \`/implement\` Step 6: fünf Zeilen, jede mit ihrem Feld am Anfang, dann die Fragen als Textblock unter der Überschrift \`## Questions\` (in jeder Berichtssprache: der Watcher findet den Abschnitt an diesem Wort und zeigt ihn ganz); alles andere steht im Plan, per Verweis.`,
     textBlock:
       'Jede Frage an den Koordinator ist ein Textblock am Ende deines Turns, nie ein Dialog (`AskUserQuestion`), auch wo ein Skill oder eine Projektregel einen verlangt, die Commit-Bestätigung von `/pre-commit` eingeschlossen: die Frage mit der Lage, dem Problem und wohin jede Option führt, in Alltagsworten (der User kennt deine Begriffe vielleicht nicht; ein Plan-Kürzel wie `P7` nur in Klammern hinter den Worten), die Optionen, deine Empfehlung, der Beleg als `datei:zeile`.',
     secret:

package/src/plan-contract/command.ts

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

package/src/plan-contract/contract.ts

@@ -1,4 +1,6 @@
 import {
+  checkPlanHead,
+  type HeadStatus,
   type ModelRow,
   NO_DEPENDENCY_TABLE,
   type PhaseHeading,
@@ -11,25 +13,31 @@ import {
 } from '../plan-format'
 import type { PlanLanguage } from '../vocabulary'
 
-/** The four parts of the plan contract. */
+/** The five parts of the plan contract; the head is a note, never a gap. */
 export const CONTRACT_PART = {
   phases: 'phases',
   tasks: 'tasks',
   model: 'model',
   dependencies: 'dependencies',
+  head: 'head',
 } as const
 
 export type ContractPart = (typeof CONTRACT_PART)[keyof typeof CONTRACT_PART]
 
 /** What the plan holds of a part: all of it, none of it, or something the readers cannot use. */
-export const PART_STATUS = { present: 'present', missing: 'missing', malformed: 'malformed' } as const
+export const PART_STATUS = {
+  present: 'present',
+  missing: 'missing',
+  malformed: 'malformed',
+  stale: 'stale',
+} as const
 
 export type PartStatus = (typeof PART_STATUS)[keyof typeof PART_STATUS]
 
 /** `line` is the 1-based line of the first problem, or of the part's first sign; null when the plan shows none. */
 export type PartFinding = { part: ContractPart; status: PartStatus; line: number | null; message: string }
 
-/** `met` is false when a part is malformed, or phases, tasks or the model table are missing; a missing dependency table is a note. */
+/** `met` is false when a part is malformed, or phases, tasks or the model table are missing; a missing dependency table or a missing or stale head is a note. */
 export type PlanContract = { parts: PartFinding[]; met: boolean }
 
 /** Fewer phases than this need no dependency table: there is nothing to put side by side. */
@@ -123,9 +131,23 @@ const dependenciesPart = (markdown: string, language: PlanLanguage, headings: re
   )
 }
 
-/** A missing dependency table is a note, not a gap: the phases then run one after another. */
+/** Notes, not gaps: a missing dependency table (the phases then run one after another) and the head, which old plans lack. */
+const NOTE_PARTS: readonly ContractPart[] = [CONTRACT_PART.dependencies, CONTRACT_PART.head]
+
 export const isGap = ({ part, status }: PartFinding): boolean =>
-  status === PART_STATUS.malformed || (status === PART_STATUS.missing && part !== CONTRACT_PART.dependencies)
+  status === PART_STATUS.malformed || (status === PART_STATUS.missing && !NOTE_PARTS.includes(part))
+
+/** The head's verdict as a part status; `satisfies` fails the type check when the two vocabularies drift apart. */
+const HEAD_PART_STATUS = {
+  present: PART_STATUS.present,
+  missing: PART_STATUS.missing,
+  stale: PART_STATUS.stale,
+} as const satisfies Record<HeadStatus, PartStatus>
+
+const headPart = (markdown: string, language: PlanLanguage): PartFinding => {
+  const { status, line, message } = checkPlanHead(markdown, language)
+  return finding(CONTRACT_PART.head, HEAD_PART_STATUS[status], line, message)
+}
 
 /**
  * What a plan holds of the contract the herd, the watcher, `jh check` and a lane start read: phase headings,
@@ -139,6 +161,7 @@ export const contractOf = (markdown: string, language: PlanLanguage): PlanContra
     tasksPart(markdown, language, headings),
     modelPart(markdown, language, headings),
     dependenciesPart(markdown, language, headings),
+    headPart(markdown, language),
   ]
   return { parts, met: !parts.some(isGap) }
 }

package/src/plan-format/index.ts

@@ -36,6 +36,7 @@ export * from './model-column'
 export * from './model-table'
 export * from './phase-tally'
 export * from './phases'
+export * from './plan-head'
 export * from './plan-structure'
 export * from './progress'
 export * from './short-names'

package/src/plan-format/plan-head.ts

@@ -0,0 +1,131 @@
+import { HEAD_LINE, type HeadLine, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { escapeRegExp } from './markdown'
+import { parsePlanPhases } from './phases'
+
+/** What a plan holds of its head: all of it and current, none of it, or something that no longer matches the plan. */
+export const HEAD_STATUS = { present: 'present', missing: 'missing', stale: 'stale' } as const
+
+export type HeadStatus = (typeof HEAD_STATUS)[keyof typeof HEAD_STATUS]
+
+/** `line` is the 1-based line of the head's heading, or of its `Phase x/y` line; null when the plan has no head. */
+export type HeadVerdict = { status: HeadStatus; line: number | null; message: string }
+
+/**
+ * The `Phase x/y` of the status line: `current` is the id of the running phase as its heading spells it (`3`, `3a`),
+ * `total` the number of phases.
+ */
+export type HeadPhase = { current: string; total: number }
+
+export type PlanHead = {
+  /** 1-based line of the `## Für dich` heading. */
+  line: number
+  /** The text after each label found. */
+  texts: Partial<Record<HeadLine, string>>
+  /** 1-based line of each label found. */
+  lineNumbers: Partial<Record<HeadLine, number>>
+  /** The labels the head lacks, in head order. */
+  missing: HeadLine[]
+  phase: HeadPhase | null
+  /** True when another level-2 section stands between the header lines and the head. */
+  misplaced: boolean
+}
+
+type PhaseState = { id: string; open: boolean }
+
+const SECTION_HEADING = /^##\s/
+const HEAD_ENTRY = /^\s*(?:[-*]\s+)?\*\*([^*]+?)\s*:?\*\*\s*:?\s*(.*)$/
+const HEAD_LINES = Object.values(HEAD_LINE)
+
+const labelOf = (language: PlanLanguage, line: HeadLine): string => PLAN_VOCABULARY[language].head[line].toLowerCase()
+
+const entryOf = (text: string, language: PlanLanguage): { label: HeadLine; text: string } | null => {
+  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 phaseOf = (statusText: string | undefined, language: PlanLanguage): HeadPhase | null => {
+  const match = statusText?.match(
+    new RegExp(`${escapeRegExp(PLAN_VOCABULARY[language].phase)}\\s+(\\d+[a-z]?)\\s*/\\s*(\\d+)`, 'i'),
+  )
+  return match ? { current: match[1].toLowerCase(), total: Number(match[2]) } : null
+}
+
+/**
+ * Reads the head section (`## Für dich` / `## For you`) and its five lines: `- **<label>:** <text>`, also with the
+ * colon outside the bold or without the list mark. Null when the plan has no such section.
+ */
+export const parsePlanHead = (markdown: string, language: PlanLanguage): PlanHead | null => {
+  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))
+  if (start === -1) return null
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((text) => SECTION_HEADING.test(text))
+  const texts: Partial<Record<HeadLine, string>> = {}
+  const lineNumbers: Partial<Record<HeadLine, number>> = {}
+  for (const [offset, text] of (end === -1 ? rest : rest.slice(0, end)).entries()) {
+    const entry = entryOf(text, language)
+    if (entry && texts[entry.label] === undefined) {
+      texts[entry.label] = entry.text
+      lineNumbers[entry.label] = start + offset + 2
+    }
+  }
+  return {
+    line: start + 1,
+    texts,
+    lineNumbers,
+    missing: HEAD_LINES.filter((each) => texts[each] === undefined),
+    phase: phaseOf(texts[HEAD_LINE.status], language),
+    misplaced: lines.slice(0, start).some((text) => SECTION_HEADING.test(text)),
+  }
+}
+
+const verdict = (status: HeadStatus, line: number | null, message: string): HeadVerdict => ({ status, line, message })
+
+/** The phases a plan has, once each by id, with whether anything in them is still open. */
+const phaseStates = (markdown: string, language: PlanLanguage): PhaseState[] =>
+  parsePlanPhases(markdown, language)
+    .filter(({ id }, index, all) => all.findIndex((other) => other.id === id) === index)
+    .map(({ id, items }) => ({ id: id.toLowerCase(), open: items.some(({ done }) => !done) }))
+
+/** Compares the phase the head names with the plan's checkboxes; null when they agree. */
+const phaseMismatch = ({ current, total }: HeadPhase, states: readonly PhaseState[]): string | null => {
+  if (total !== states.length) return `names ${total} phases, the plan has ${states.length}`
+  const running = states.find(({ open }) => open)
+  if (running === undefined)
+    return current === states.at(-1)?.id ? null : `all phases are done, the head names phase ${current}`
+  return current === running.id ? null : `names phase ${current}, the running phase is ${running.id}`
+}
+
+/**
+ * The verdict on a plan's head. Stale when it stands behind another section, lacks a line, has no `Phase x/y` in the
+ * status line, or names a phase other than the first one with an open checkbox (the last one when all are done) or a
+ * wrong phase count. Pure: it reads only the Markdown.
+ */
+export const checkPlanHead = (markdown: string, language: PlanLanguage): HeadVerdict => {
+  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.misplaced)
+    return verdict(
+      HEAD_STATUS.stale,
+      head.line,
+      `the head must stand right after the header lines, before the other sections`,
+    )
+  if (head.missing.length > 0)
+    return verdict(
+      HEAD_STATUS.stale,
+      head.line,
+      `no line ${head.missing.map((each) => `"${PLAN_VOCABULARY[language].head[each]}"`).join(', ')}`,
+    )
+  // Narrows for the type checker: the status line exists once no label is missing.
+  const statusLine = head.lineNumbers[HEAD_LINE.status] ?? head.line
+  if (head.phase === null) return verdict(HEAD_STATUS.stale, statusLine, 'the status line has no "Phase x/y"')
+  const mismatch = phaseMismatch(head.phase, phaseStates(markdown, language))
+  return mismatch === null
+    ? verdict(HEAD_STATUS.present, head.line, `Phase ${head.phase.current}/${head.phase.total}`)
+    : verdict(HEAD_STATUS.stale, statusLine, mismatch)
+}

package/src/plans/active-tasks.ts

@@ -8,7 +8,14 @@ import type { TaskPhase } from './current-task'
  * A task an agent is working on: its index among the phase's checkboxes, who works on it (null while only one agent
  * is active in the lane), whether the herd only guesses it from words, and when the agent began it (null for a guess).
  */
-export type ActiveTask = { index: number; agent: string | null; guessed: boolean; startedAt: number | null }
+export type ActiveTask = {
+  index: number
+  agent: string | null
+  guessed: boolean
+  startedAt: number | null
+  /** The first open task of a running phase that no agent reported: drawn `◌`, but shimmering like a reported one. */
+  fromPlan?: true
+}
 
 /** A task an agent reports that no open task of the plan names. */
 export type UnplannedTask = { text: string; agent: string | null }