jackherd 1.14.0 → 1.15.1

package/src/config/schema.ts

@@ -46,6 +46,15 @@ export const isModelRole = (value: string): value is ModelRole =>
 /** Lower-case letters and digits ending in a dash, so a prefixed name stays one plain path segment. */
 export const SKILL_PREFIX = /^[a-z0-9]+-$/
 
+/** What a global install, and a project that already has skills of kit names, puts before every kit name. */
+export const DEFAULT_SKILL_PREFIX = 'jh-'
+
+/** The skills every lane and the coordinator run on; `kit.exclude` cannot take them away. */
+export const KIT_CORE: readonly string[] = ['orchestrate', 'start']
+
+/** A kit skill or agent as the kit names it, before `skillPrefix`. */
+const KIT_ENTRY_NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/
+
 const FULL_MODEL_ID = /^claude-[a-z0-9][a-z0-9.-]*$/
 
 const language = z.enum(Object.values(PLAN_LANGUAGE))
@@ -56,6 +65,13 @@ const modelId = z
 
 const command = z.string().min(1)
 
+const excludedKitEntry = z
+  .string()
+  .regex(KIT_ENTRY_NAME, 'a kit skill or agent name as the kit names it, e.g. devops')
+  .refine((name) => !KIT_CORE.includes(name), {
+    error: (issue) => `${issue.input} is the kit's core and cannot be excluded`,
+  })
+
 const tokenCount = z.number().int().positive()
 
 /**
@@ -360,6 +376,12 @@ const mergeSchema = z.strictObject({
    * `--match-head-commit`. Empty means every merge waits for checks.
    */
   withoutChecks: z.array(checkFreePattern).default([]),
+  /**
+   * Whether a lane opens every pull request as a draft (`gh pr create --draft`), so pushes while it is worked on start
+   * no workflow that skips drafts. `/orchestrate` runs `gh pr ready` before the merge and waits for the checks that
+   * start then; the merge guard never lets a draft through. Off opens pull requests ready, as before.
+   */
+  openAsDraft: z.boolean().default(false),
 })
 
 const guardFields = z.strictObject({
@@ -480,6 +502,11 @@ export const jackherdConfigSchema = z.strictObject({
     .union([z.literal(''), z.string().regex(SKILL_PREFIX, 'lower-case letters and digits ending in a dash, e.g. kit-')])
     .default(''),
   commands: commandsSchema.prefault({}),
+  /**
+   * Kit skills and agents `jh sync` leaves out, by the kit's name without `skillPrefix`; a name takes its skill and
+   * its agent alike. An unchanged copy already installed is removed, a changed one stays untracked.
+   */
+  kit: z.strictObject({ exclude: z.array(excludedKitEntry).default([]) }).prefault({}),
   /** How `/orchestrate` sets up a lane's worktree. */
   lanes: z
     .strictObject({

package/src/context/fill.ts

@@ -1,3 +1,4 @@
+import { LOG_ENTRY_TYPE } from './log-vocabulary'
 import { keptLogEntry } from './session-log'
 
 /** How the context window of a model is assumed: by model ID, with a default for the models not listed. */
@@ -26,7 +27,7 @@ const count = (value: unknown): number => (typeof value === 'number' && Number.i
 /** The answer of a main-chain `assistant` line; null for every other line, a sub-agent's answer and a synthetic one. */
 const answerOf = (line: string): Answer | null => {
   const entry = keptLogEntry(line)
-  if (!entry || entry.type !== 'assistant' || entry.isSidechain === true) return null
+  if (!entry || entry.type !== LOG_ENTRY_TYPE.assistant || entry.isSidechain === true) return null
   const { message } = entry
   if (!isRecord(message) || typeof message.model !== 'string' || message.model === SYNTHETIC_MODEL) return null
   const { usage } = message

package/src/context/log-vocabulary.ts

@@ -0,0 +1,22 @@
+/** The entry types of a Claude Code session log line that a reader tells apart; the log delivers them as strings. */
+export const LOG_ENTRY_TYPE = { assistant: 'assistant' } as const
+
+/** The block types inside an entry's `message.content`. */
+export const CONTENT_BLOCK_TYPE = { text: 'text', toolUse: 'tool_use', toolResult: 'tool_result' } as const
+
+/** The names of Claude Code's tools a reader looks for in a `tool_use` block. */
+export const CLAUDE_TOOL = {
+  taskCreate: 'TaskCreate',
+  taskUpdate: 'TaskUpdate',
+  todoWrite: 'TodoWrite',
+  edit: 'Edit',
+  write: 'Write',
+  multiEdit: 'MultiEdit',
+  notebookEdit: 'NotebookEdit',
+} as const
+
+/**
+ * What every assistant entry's raw line holds, as the log writes it without spaces: a text search for it finds the
+ * answers of a log without parsing every line.
+ */
+export const ASSISTANT_ENTRY_MARK = `"type":"${LOG_ENTRY_TYPE.assistant}"`

package/src/context/session-log.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path'
 import { CLAUDE_DIRECTORY, SESSION_LOGS_DIRECTORY } from '../claude/paths'
 import { boundedMemo } from '../shared/bounded-memo'
 import { isRecord } from '../shared/is-record'
+import { ASSISTANT_ENTRY_MARK } from './log-vocabulary'
 
 /** A tail read before: the file as it was (inode, size, modification time), its lines and the byte offset each starts at. */
 type FollowedTail = { inode: number; size: number; modifiedAt: number; lines: string[]; starts: number[] }
@@ -159,7 +160,7 @@ export const sessionLog = (
 
 export type AgentSession = { session: string | null; cwd: string | null }
 
-const hasAnswer = (lines: readonly string[]): boolean => lines.some((line) => line.includes('"type":"assistant"'))
+const hasAnswer = (lines: readonly string[]): boolean => lines.some((line) => line.includes(ASSISTANT_ENTRY_MARK))
 
 /** Claude Code names a project directory after the working directory, `/` and `.` turned into `-`. */
 export const projectDirectoryOf = (cwd: string): string => cwd.replace(/[/.]/g, '-')

package/src/lane-prompt/build.ts

@@ -19,6 +19,8 @@ export type LanePromptInput = {
   plans: LanePlan[]
   port: number | null
   handover: string | null
+  /** The project's `skillPrefix` (`''` for none), put before the name of the kit's skill the start names. */
+  skillPrefix: string
 }
 
 const writesText = (language: PlanLanguage, texts: LanePromptTexts, writes: string[] | null): string => {
@@ -35,11 +37,12 @@ const planLines = (language: PlanLanguage, texts: LanePromptTexts, plan: LanePla
   ...plan.phases.map((phase) => `  - ${phaseText(language, texts, phase)}`),
 ]
 
-const ruleLines = (input: LanePromptInput, texts: LanePromptTexts): string[] => [
-  input.port === null ? texts.noPort : texts.port(input.port),
+const ruleLines = (input: LanePromptInput, texts: LanePromptTexts, implementSkill: string): string[] => [
+  input.port === null ? texts.noPort : texts.port(input.port, implementSkill),
   texts.blocking,
   texts.mustNot,
   texts.commit,
+  texts.taskSignals,
   texts.report(laneReportFile(input.lane)),
   texts.textBlock,
   texts.secret,
@@ -51,11 +54,13 @@ const ruleLines = (input: LanePromptInput, texts: LanePromptTexts): string[] =>
 /**
  * The prompt that starts a lane, in the plan language: a first line that names the lane (the words the ask hint hook
  * and the project's lane exception recognise), the plans with their phases as `Phase P<n>` and each phase's write
- * set, the rules of `/orchestrate` § 1 that `/implement` does not carry already, and the start: `/implement`, or the
+ * set, the rules of `/orchestrate` § 1 and the lane contract (report each task, the report file, questions as text blocks,
+ * git through the coordinator), and the start: the phases built with `/implement` or another skill, or the
  * hand-over file after a restart.
  */
 export const buildLanePrompt = (input: LanePromptInput): string => {
   const texts = LANE_PROMPT_TEXTS[input.language]
+  const implementSkill = `/${input.skillPrefix}implement`
   return [
     `${LANE_PROMPT_OPENING[input.language]} ${input.lane}. ${texts.answersTo}`,
     '',
@@ -66,9 +71,9 @@ export const buildLanePrompt = (input: LanePromptInput): string => {
     texts.editInside,
     texts.writeTools,
     '',
-    ...ruleLines(input, texts).map((line) => `- ${line}`),
+    ...ruleLines(input, texts, implementSkill).map((line) => `- ${line}`),
     '',
-    input.handover === null ? texts.start : texts.restart(input.handover),
+    input.handover === null ? texts.start(implementSkill) : texts.restart(input.handover),
     '',
   ].join('\n')
 }

package/src/lane-prompt/command.ts

@@ -46,7 +46,12 @@ const promptSourcesOf = (options: LanePromptOptions, cwd: string): PromptSources
   if (board.notice) console.error(board.notice)
   const directory = dirname(boardRepoPathOf(root, settings, board.file))
   return {
-    request: { lane: options.lane, handover: options.handover, language: settings.planLanguage },
+    request: {
+      lane: options.lane,
+      handover: options.handover,
+      language: settings.planLanguage,
+      skillPrefix: settings.skillPrefix,
+    },
     board: { text: readFileSync(board.file, 'utf8'), directory, path: relative(cwd, board.file) },
     readPlan: readFirstIn([root, checkout]),
     readLanePlan: readFirstIn([worktreeOf(root, settings, options.lane)]),

package/src/lane-prompt/input.ts

@@ -5,8 +5,8 @@ import { isPhaseFinished } from '../plan-format/progress'
 import type { PlanLanguage } from '../vocabulary'
 import type { LanePhase, LanePlan, LanePromptInput } from './build'
 
-/** The lane to prompt, the hand-over file of a restart (null for a fresh start) and the plan language. */
-export type LanePromptRequest = { lane: string; handover: string | null; language: PlanLanguage }
+/** The lane to prompt, the hand-over file of a restart (null for a fresh start), the plan language and the project's `skillPrefix`. */
+export type LanePromptRequest = { lane: string; handover: string | null; language: PlanLanguage; skillPrefix: string }
 
 /**
  * The board's text, its directory from the repository root, which its plan links are relative to, and the path a
@@ -146,12 +146,12 @@ export const lanePromptInputOf = (
   const found = plansOf(steps, { main: readPlan, lane: readLanePlan }, request.language)
   if ('reason' in found) return refused(found.reason)
   if (found.plans.length === 0) return refused(`every phase of lane ${request.lane} is finished`)
-  const { lane, handover, language } = request
+  const { lane, handover, language, skillPrefix } = request
   const others = lanes.filter((candidate) => candidate.name !== lane && !candidate.closed)
   const { plans, notices } = withoutContested(found.plans, lane, others, board.directory)
   if (plans.length === 0) {
     return refused(`every open phase of lane ${lane} is also named by another lane: ${notices.join('; ')}`)
   }
-  const input = { language, lane, plans, port: sprintLane.port, handover }
+  const input = { language, lane, plans, port: sprintLane.port, handover, skillPrefix }
   return notices.length === 0 ? { kind: 'prompt', input } : { kind: 'prompt', input, notices }
 }

package/src/lane-prompt/texts.ts

@@ -1,3 +1,4 @@
+import { CLI_NAME } from '../version/release'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
 
 /**
@@ -12,11 +13,12 @@ export type LanePromptTexts = {
   wholeRepository: string
   editInside: string
   writeTools: string
-  port: (port: number) => string
+  port: (port: number, implementSkill: string) => string
   noPort: string
   blocking: string
   mustNot: string
   commit: string
+  taskSignals: string
   report: (reportPath: string) => string
   textBlock: string
   secret: string
@@ -24,7 +26,7 @@ export type LanePromptTexts = {
   approvalGate: string
   helper: (helperName: string) => string
   helperPurpose: string
-  start: string
+  start: (implementSkill: string) => string
   restart: (handoverPath: string) => string
 }
 
@@ -38,15 +40,17 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
       'Nothing outside the Writes set of your phases is edited, except the task lines of your phases in the plan: tick a finished one right away, by an Edit of exactly that line.',
     writeTools:
       'Write code and tests with Write and Edit, never through a here-document or a script in Bash: such a call shows the reviewer no diff, and an unquoted or unreadable one can stop at a guard.',
-    port: (port) =>
-      `Port ${port}: the coordinator runs your dev server in its own pane; look at your visible changes there (\`/implement\` Step 4b) and never start a server in your own shell.`,
+    port: (port, implementSkill) =>
+      `Port ${port}: the coordinator runs your dev server in its own pane; look at your visible changes there (\`${implementSkill}\` Step 4b) and never start a server in your own shell.`,
     noPort:
       'No port: this lane has no dev server of its own. Never start a server in your own shell; ask the coordinator when you need one.',
     blocking:
       'Mark every question of yours `blocking` or `not blocking`. A blocking one stops the step it decides; for a not blocking one leave a `TODO` at its spot and work on, building neither your recommendation nor another option as decided.',
     mustNot:
       'Without the user’s approval you push no database migration and write nothing against a shared environment (stage, production); you never run `git reset` or `git stash` on shared refs.',
-    commit: 'Ask before every commit (`/pre-commit`); no push, PR or merge without approval.',
+    commit:
+      '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.`,
     textBlock:
@@ -60,7 +64,8 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
     helper: (helperName) =>
       `A helper agent in a pane of your own (a measurement, a probe session) is announced to the coordinator before it starts, as a question at the end of your turn: what it does, how long, and which temporary settings it uses. Once approved, name it \`${helperName}\` (\`herdr agent rename\`), so the watcher watches it with your lane, and close it yourself when it is done: \`/exit\`, then \`herdr pane close\`, and remove every temporary file it needed.`,
     helperPurpose: '<purpose>',
-    start: 'Start: run `/implement` for your phases, in the order above.',
+    start: (implementSkill) =>
+      `Start: build your phases in the order above, with \`${implementSkill}\` or a skill of your choice; the rules above hold for every one.`,
     restart: (handoverPath) => `Start: read \`${handoverPath}\` first and continue with the next step it names.`,
   },
   [PLAN_LANGUAGE.de]: {
@@ -72,15 +77,17 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
       'Außerhalb der Schreibt-Menge deiner Phasen änderst du nichts, außer den Aufgabenzeilen deiner Phasen im Plan: eine erledigte hakst du sofort ab, per Edit auf genau diese Zeile.',
     writeTools:
       'Code und Tests schreibst du mit Write und Edit, nie per Heredoc oder Skript in Bash: ein solcher Aufruf zeigt dem Prüfer keinen Diff, und ein ungequoteter oder unlesbarer kann an einem Wächter hängen bleiben.',
-    port: (port) =>
-      `Port ${port}: Der Koordinator betreibt deinen Dev-Server in seinem eigenen Pane; deine sichtbaren Änderungen siehst du dort an (\`/implement\` Step 4b) und startest nie einen Server in deiner eigenen Shell.`,
+    port: (port, implementSkill) =>
+      `Port ${port}: Der Koordinator betreibt deinen Dev-Server in seinem eigenen Pane; deine sichtbaren Änderungen siehst du dort an (\`${implementSkill}\` Step 4b) und startest nie einen Server in deiner eigenen Shell.`,
     noPort:
       'Kein Port: Diese Spur hat keinen eigenen Dev-Server. Starte nie einen Server in deiner eigenen Shell; brauchst du einen, frag den Koordinator.',
     blocking:
       'Markiere jede deiner Fragen mit `blocking` oder `not blocking`. Eine blockierende hält den Schritt an, den sie entscheidet; bei einer nicht blockierenden lässt du an ihrer Stelle ein `TODO` und arbeitest weiter, ohne deine Empfehlung oder eine andere Option als entschieden zu bauen.',
     mustNot:
       'Ohne Freigabe des Users pushst du keine Datenbank-Migration und schreibst nichts gegen eine geteilte Umgebung (Stage, Produktion); `git reset` und `git stash` auf geteilten Refs führst du nie aus.',
-    commit: 'Vor jedem Commit fragst du (`/pre-commit`); kein Push, kein PR und kein Merge ohne Freigabe.',
+    commit:
+      '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.`,
     textBlock:
@@ -94,7 +101,8 @@ export const LANE_PROMPT_TEXTS: Record<PlanLanguage, LanePromptTexts> = {
     helper: (helperName) =>
       `Einen Helfer-Agenten in einem eigenen Pane (eine Messung, eine Probesitzung) meldest du dem Koordinator an, bevor er startet, als Frage am Ende deines Turns: was er tut, wie lange, und welche temporären Einstellungen er nutzt. Nach der Freigabe benennst du ihn \`${helperName}\` (\`herdr agent rename\`), damit der Watcher ihn mit deiner Spur beobachtet, und schließt ihn selbst, wenn er fertig ist: \`/exit\`, dann \`herdr pane close\`, und entferne jede temporäre Datei, die er brauchte.`,
     helperPurpose: '<zweck>',
-    start: 'Start: Führe `/implement` für deine Phasen aus, in der Reihenfolge oben.',
+    start: (implementSkill) =>
+      `Start: Baue deine Phasen in der Reihenfolge oben, mit \`${implementSkill}\` oder einem Skill deiner Wahl; die Regeln oben gelten für jeden.`,
     restart: (handoverPath) =>
       `Start: Lies zuerst \`${handoverPath}\` und mach mit dem nächsten Schritt weiter, den sie nennt.`,
   },

package/src/plan-contract/command.ts

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+import { findProjectRoot } from '../config/location'
+import { readConfig } from '../config/read-config'
+import { asksForHelp } from '../preview/options'
+import { CLI_NAME } from '../version/release'
+import type { PlanLanguage } from '../vocabulary'
+import { contractOf, type PartFinding, type PlanContract } from './contract'
+
+const CHECK_SUBCOMMAND = 'check'
+
+/** Exit codes of `jh plan check`: the contract is met, a part has a gap, the command line or the file is wrong. */
+export const PLAN_CHECK_EXIT = { met: 0, gaps: 1, error: 2 } as const
+
+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.
+The plan language comes from .jackherd/config.json.
+Exit 0 met, 1 with gaps, 2 for a wrong command line or an unreadable file.`
+
+const where = (file: string, line: number | null): string => (line === null ? '' : ` ${file}:${line}`)
+
+/** One line per part: `model: malformed plan.md:12 no model for P2`. */
+export const contractLines = (file: string, { parts }: PlanContract): string[] =>
+  parts.map(({ part, status, line, message }: PartFinding) => `${part}: ${status}${where(file, line)} ${message}`)
+
+type LanguageResult = { language: PlanLanguage } | { error: string }
+
+const languageOf = (home: string): LanguageResult => {
+  try {
+    const root = findProjectRoot(process.cwd(), home, existsSync) ?? process.cwd()
+    return { language: readConfig([root], home).planLanguage }
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+const readPlan = (file: string): string | null => {
+  try {
+    return readFileSync(resolve(process.cwd(), file), 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const fail = (message: string): number => {
+  console.error(message)
+  return PLAN_CHECK_EXIT.error
+}
+
+export const run = (args: string[], home: string = homedir()): number => {
+  if (asksForHelp(args)) {
+    console.log(USAGE)
+    return PLAN_CHECK_EXIT.met
+  }
+  const [subcommand, file, ...rest] = args
+  if (subcommand !== CHECK_SUBCOMMAND)
+    return fail(subcommand === undefined ? USAGE : `unknown subcommand ${subcommand}\n${USAGE}`)
+  if (file === undefined || rest.length > 0) return fail(USAGE)
+  const markdown = readPlan(file)
+  if (markdown === null) return fail(`cannot read ${file}\n${USAGE}`)
+  const result = languageOf(home)
+  if ('error' in result) return fail(result.error)
+  const contract = contractOf(markdown, result.language)
+  for (const line of contractLines(file, contract)) console.log(line)
+  return contract.met ? PLAN_CHECK_EXIT.met : PLAN_CHECK_EXIT.gaps
+}

package/src/plan-contract/contract.ts

@@ -0,0 +1,144 @@
+import {
+  type ModelRow,
+  NO_DEPENDENCY_TABLE,
+  type PhaseHeading,
+  parseDependencyTable,
+  parseModelTable,
+  parsePlanPhases,
+  phaseCount,
+  phaseHeadings,
+  phaseLabels,
+} from '../plan-format'
+import type { PlanLanguage } from '../vocabulary'
+
+/** The four parts of the plan contract. */
+export const CONTRACT_PART = {
+  phases: 'phases',
+  tasks: 'tasks',
+  model: 'model',
+  dependencies: 'dependencies',
+} 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 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. */
+export type PlanContract = { parts: PartFinding[]; met: boolean }
+
+/** Fewer phases than this need no dependency table: there is nothing to put side by side. */
+const PHASES_NEEDING_DEPENDENCIES = 2
+
+const SUB_PHASE_SUFFIX = /[a-z]$/
+const NO_MODEL_MARK = /^[—–-]/
+
+/** The phase a sub-phase belongs to (`3b` is `3`); a phase without a letter is its own base. */
+const baseOf = (id: string): string => id.replace(SUB_PHASE_SUFFIX, '')
+
+const finding = (part: ContractPart, status: PartStatus, line: number | null, message: string): PartFinding => ({
+  part,
+  status,
+  line,
+  message,
+})
+
+const uniqueHeadings = (headings: readonly PhaseHeading[]): PhaseHeading[] =>
+  headings.filter(({ id }, index) => headings.findIndex((other) => other.id === id) === index)
+
+const phasesPart = (headings: readonly PhaseHeading[]): PartFinding =>
+  headings.length === 0
+    ? finding(CONTRACT_PART.phases, PART_STATUS.missing, null, 'no phase heading')
+    : finding(CONTRACT_PART.phases, PART_STATUS.present, headings[0].line, phaseCount(headings.length))
+
+/** Present when no phase lacks the part (`ok`), else malformed at the first phase that does, naming them all. */
+const coverage = (
+  part: ContractPart,
+  without: readonly PhaseHeading[],
+  ok: { line: number | null; message: string },
+  problem: string,
+): PartFinding =>
+  without.length === 0
+    ? finding(part, PART_STATUS.present, ok.line, ok.message)
+    : finding(
+        part,
+        PART_STATUS.malformed,
+        without[0].line,
+        `${problem} ${phaseLabels(
+          without.map(({ id }) => id),
+          ', ',
+        )}`,
+      )
+
+const tasksPart = (markdown: string, language: PlanLanguage, headings: readonly PhaseHeading[]): PartFinding => {
+  if (headings.length === 0) return finding(CONTRACT_PART.tasks, PART_STATUS.missing, null, 'no phase to hold tasks')
+  const empty = new Set(
+    parsePlanPhases(markdown, language)
+      .filter(({ items }) => items.length === 0)
+      .map(({ id }) => id),
+  )
+  const without = headings.filter(({ id }) => empty.has(id))
+  return coverage(
+    CONTRACT_PART.tasks,
+    without,
+    { line: headings[0].line, message: 'every phase has tasks' },
+    'no checkbox in',
+  )
+}
+
+/** A row names a model, or marks the phase as one that needs none (`—`, a phase only a person does). */
+const isDecided = ({ models, cell }: ModelRow): boolean => models.length > 0 || NO_MODEL_MARK.test(cell)
+
+/** A phase is covered by a listed id of its own or of its base phase. */
+const lacks = (headings: readonly PhaseHeading[], listed: ReadonlySet<string>): PhaseHeading[] =>
+  headings.filter(({ id }) => !listed.has(id) && !listed.has(baseOf(id)))
+
+const modelPart = (markdown: string, language: PlanLanguage, headings: readonly PhaseHeading[]): PartFinding => {
+  const rows = parseModelTable(markdown, language)
+  if (rows === null) return finding(CONTRACT_PART.model, PART_STATUS.missing, null, 'no model table')
+  const modelled = new Set(rows.filter(isDecided).map(({ id }) => id))
+  return coverage(
+    CONTRACT_PART.model,
+    lacks(headings, modelled),
+    { line: rows[0]?.line ?? null, message: 'every phase has a model' },
+    'no model for',
+  )
+}
+
+const dependenciesPart = (markdown: string, language: PlanLanguage, headings: readonly PhaseHeading[]): PartFinding => {
+  if (headings.length < PHASES_NEEDING_DEPENDENCIES)
+    return finding(CONTRACT_PART.dependencies, PART_STATUS.present, null, 'not needed with fewer than two phases')
+  const table = parseDependencyTable(markdown, language)
+  if (table === null) return finding(CONTRACT_PART.dependencies, PART_STATUS.missing, null, NO_DEPENDENCY_TABLE)
+  return coverage(
+    CONTRACT_PART.dependencies,
+    lacks(headings, new Set(table.map(({ id }) => id))),
+    { line: null, message: 'every phase has a row' },
+    'no row for',
+  )
+}
+
+/** A missing dependency table is a note, not a gap: the phases then run one after another. */
+export const isGap = ({ part, status }: PartFinding): boolean =>
+  status === PART_STATUS.malformed || (status === PART_STATUS.missing && part !== CONTRACT_PART.dependencies)
+
+/**
+ * What a plan holds of the contract the herd, the watcher, `jh check` and a lane start read: phase headings,
+ * checkboxes in every phase, a recognised model for every phase, and (from two phases on) a dependency row for every
+ * phase. Built on the parsers those readers use, so a part is present exactly when they find it.
+ */
+export const contractOf = (markdown: string, language: PlanLanguage): PlanContract => {
+  const headings = uniqueHeadings(phaseHeadings(markdown, language))
+  const parts = [
+    phasesPart(headings),
+    tasksPart(markdown, language, headings),
+    modelPart(markdown, language, headings),
+    dependenciesPart(markdown, language, headings),
+  ]
+  return { parts, met: !parts.some(isGap) }
+}

package/src/plan-format/dependencies.ts

@@ -1,5 +1,5 @@
 import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { PHASE_ID_PREFIX, phaseLabels, spannedPhaseIds } from './lanes'
+import { PHASE_ID_PREFIX, phaseIdOf, phaseLabels, spannedPhaseIds } from './lanes'
 import { escapeRegExp, firstTableWithHeader, subsectionLines } from './markdown'
 import { type PhaseHeading, parsePlanPhases, phaseHeadings } from './phases'
 import { isPhaseFinished } from './progress'
@@ -30,7 +30,6 @@ export type PhaseWithoutRow = PhaseHeading
 type Candidate = { id: string; writes: string[]; serialMarkers: string[]; releases: string[] }
 
 const ID = '(\\d+[a-z]?)'
-const PHASE_ID = new RegExp(`^\\s*${PHASE_ID_PREFIX}?${ID}\\b`, 'i')
 const PHASE_RANGE = new RegExp(`^${PHASE_ID_PREFIX}?(\\d+)\\s*[–-]\\s*${PHASE_ID_PREFIX}?(\\d+)$`, 'i')
 const BACKTICKED = /`([^`]+)`/g
 const NO_VALUE = /^[—–-]?$/
@@ -41,8 +40,6 @@ const PACKAGE_SCOPE = /^@[^/]+\//
 /** The files a release of the package in their directory changes: the changelog and the version in the manifest. */
 const RELEASE_FILE = /(?:^|\/)(?:CHANGELOG\.md|package\.json)$/
 
-const phaseIdOf = (cell: string): string | null => PHASE_ID.exec(cell)?.[1]?.toLowerCase() ?? null
-
 const splitOutsideParentheses = (cell: string, separator: string): string[] => {
   const entries: string[] = []
   let depth = 0

package/src/plan-format/index.ts

@@ -18,9 +18,12 @@ export * from './drift'
 export * from './header'
 export {
   laneNameOf,
+  NO_DEPENDENCY_TABLE,
   PHASE_ID_PREFIX,
   type PlanStep,
   parseSprintLanes,
+  phaseCount,
+  phaseIdOf,
   phaseIdsOfCell,
   phaseLabel,
   phaseLabels,
@@ -30,6 +33,7 @@ export {
   withoutRepeats,
 } from './lanes'
 export * from './model-column'
+export * from './model-table'
 export * from './phase-tally'
 export * from './phases'
 export * from './plan-structure'

package/src/plan-format/lanes.ts

@@ -29,6 +29,17 @@ const PLAN_LINK = /\[([^\]]+)\]\(([^)]+)\)/
 /** Sprint tables name a phase `P4`; the sidebar title prints it the same way. */
 export const PHASE_ID_PREFIX = 'P'
 
+const LEADING_PHASE_ID = new RegExp(`^\\s*${PHASE_ID_PREFIX}?(\\d+[a-z]?)\\b`, 'i')
+
+/** The phase a table's first cell names (`1 — Title`, `P1`, `10c`), lower-cased; null when it names none. */
+export const phaseIdOf = (cell: string): string | null => LEADING_PHASE_ID.exec(cell)?.[1]?.toLowerCase() ?? null
+
+/** What a report says when the plan has no dependency table. */
+export const NO_DEPENDENCY_TABLE = 'no dependency table: phases run one after another'
+
+/** `1 phase`, `3 phases`. */
+export const phaseCount = (count: number): string => `${count} ${count === 1 ? 'phase' : 'phases'}`
+
 /** A phase as plans and reports name it: `P4`. */
 export const phaseLabel = (id: string): string => `${PHASE_ID_PREFIX}${id}`
 

package/src/plan-format/markdown.ts

@@ -56,13 +56,14 @@ export const firstHeading = (markdown: string, fallback: string): string =>
 
 const HEADING = /^(#{2,4})\s+(.*?)\s*$/
 
-/**
- * The lines under the first level 2 to 4 heading whose text starts with `headingText` (a suffix such as
- * `(PFLICHT ab 3 Phasen)` is allowed), up to the next heading of the same or a higher level.
- */
+/** The 0-based line index of the first level 2 to 4 heading whose text starts with `headingText` (a suffix such as `(PFLICHT ab 3 Phasen)` is allowed); -1 when there is none. */
+export const subsectionStart = (markdown: string, headingText: string): number =>
+  markdown.split('\n').findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+
+/** The lines under that heading (see `subsectionStart`), up to the next heading of the same or a higher level. */
 export const subsectionLines = (markdown: string, headingText: string): string[] => {
   const lines = markdown.split('\n')
-  const start = lines.findIndex((line) => HEADING.exec(line)?.[2].startsWith(headingText))
+  const start = subsectionStart(markdown, headingText)
   if (start === -1) return []
   const level = HEADING.exec(lines[start])?.[1].length ?? 2
   const rest = lines.slice(start + 1)

package/src/plan-format/model-table.ts

@@ -0,0 +1,27 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { phaseIdOf } from './lanes'
+import { firstTableRows, subsectionLines, subsectionStart } from './markdown'
+import { type ColumnModel, columnModels } from './model-column'
+
+/**
+ * A row of the model table: the phase it names, the models its model cell names (none for a dash), the model cell as
+ * written, and the row's 1-based line.
+ */
+export type ModelRow = { id: string; models: ColumnModel[]; cell: string; line: number }
+
+/**
+ * The rows of the plan's model table (`### Model-Empfehlungen pro Phase`): the phase from the first cell (`1 — Title`,
+ * `P1`, `10c`), the models from the second, read like a board's model column. A row whose first cell names no phase is
+ * skipped; null when the plan has no such section or the section holds no table.
+ */
+export const parseModelTable = (markdown: string, language: PlanLanguage): ModelRow[] | null => {
+  const heading = PLAN_VOCABULARY[language].sections.modelRecommendations
+  const rows = firstTableRows(subsectionLines(markdown, heading))
+  if (rows.length === 0) return null
+  const firstBodyLine = subsectionStart(markdown, heading) + 2
+  return rows.flatMap(({ index, cells }) => {
+    const id = phaseIdOf(cells[0] ?? '')
+    const cell = cells[1] ?? ''
+    return id === null ? [] : [{ id, models: columnModels(cell), cell, line: firstBodyLine + index }]
+  })
+}