jackherd 1.6.1 → 1.7.0

package/src/config/schema.ts

@@ -2,10 +2,13 @@ import { z } from 'zod'
 import { checkConfigSchema } from '../check/schema'
 import { claudePath, WORKTREES_DIRECTORY } from '../claude/paths'
 import { PLAN_LANGUAGE, RESPONSE_ADDRESS } from '../vocabulary'
-import { SOURCE_FIELD } from '../watch/source-fields'
+import { CONTENT_FIELDS, SOURCE_FIELD } from '../watch/source-fields'
 import { isSourcePath } from '../watch/source-path'
+import { BUN_FAILED_TEST_PATTERN, CLEAN_REVIEW_TEXT } from '../watch/watch-defaults'
 import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
+import { hasNestedQuantifier } from './nested-quantifier'
+import { isRepositoryDirectory } from './repository-directory'
 
 export const TERMINAL_ADAPTER = { none: 'none', herdr: 'herdr' } as const
 
@@ -89,7 +92,7 @@ const boardSchema = z.strictObject({
   pattern: boardPattern.default('board-*'),
   /** The board document inside each of those directories. */
   file: boardFile.default('board.md'),
-  /** What the project calls a board: the plans view, its page and the watcher print it as written. */
+  /** What the project calls a board: the herd, its page and the watcher print it as written. */
   term: z.string().min(1).default('board'),
 })
 
@@ -103,6 +106,28 @@ const deploySchema = z.strictObject({
 const feedbackSchema = z.strictObject({
   /** GitHub logins whose feedback does not wake the coordinator, such as a status bot; case is ignored. */
   ignore: z.array(z.string().min(1)).default([]),
+  /**
+   * Texts of a bot's pull request comment that report no finding: such a comment (login ending `[bot]`, no inline
+   * comment by the same author within five minutes of it) is no feedback. Compared with whitespace collapsed; the
+   * default is the CI code review's comment for a clean run. An empty list counts every bot comment.
+   */
+  noFindingTemplates: z.array(z.string().min(1)).default([CLEAN_REVIEW_TEXT]),
+})
+
+const checksSchema = z.strictObject({
+  /**
+   * Finds a failed test in a line of a red run's log (`gh run view --log-failed`) after its job, step and timestamp
+   * prefix: the first group is the name, else the match. The default is Bun's `(fail) <name> [<duration>]`. The
+   * watcher runs it on every line of a log it does not control, so a pattern that repeats a group which repeats inside
+   * itself (`(a+)+`, `(\w*)*`, and with alternation `(a|aa)+`) is refused: a best-effort scan of the source against
+   * catastrophic backtracking, not a proof.
+   */
+  failedTestPattern: z
+    .string()
+    .min(1)
+    .refine(isRegularExpression, 'not a valid regular expression')
+    .refine((pattern) => !hasNestedQuantifier(pattern), 'a quantified group that holds a quantifier backtracks badly')
+    .default(BUN_FAILED_TEST_PATTERN),
 })
 
 const previewsSchema = z.strictObject({
@@ -121,24 +146,33 @@ const sourcePath = z.string().refine(isSourcePath, 'not a source path: `.`, or `
 
 const SOURCE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/
 
-/** The six known fields, and any further field (`status`, `priority`, …) whose name is a plain name, for `reportOn`. */
+/** The seven known fields, and any further field (`priority`, `assignee`, …) whose name is a plain name, for `reportOn`. */
 const sourceMapSchema = z
   .object({
     [SOURCE_FIELD.id]: sourcePath,
-    /** Changes whenever the entry changes; compared as text, so any stable form of a time or version works. */
-    [SOURCE_FIELD.updatedAt]: sourcePath,
+    /**
+     * Changes whenever the entry changes; compared as text, so any stable form of a time or version works. Needed
+     * only where no content field and no `reportOn` can tell a change.
+     */
+    [SOURCE_FIELD.updatedAt]: sourcePath.optional(),
     [SOURCE_FIELD.title]: sourcePath.optional(),
     /** Shown only as an `https:` URL without user name or password. */
     [SOURCE_FIELD.url]: sourcePath.optional(),
     /** The first line with text is shown. */
     [SOURCE_FIELD.body]: sourcePath.optional(),
     [SOURCE_FIELD.author]: sourcePath.optional(),
+    /** A ticket source's status, shown on its badge in the herd; also a field `reportOn` can name. */
+    [SOURCE_FIELD.status]: sourcePath.optional(),
   })
   .catchall(sourcePath)
   .refine((map) => Object.keys(map).every((field) => SOURCE_FIELD_NAME.test(field)), {
     message: 'a map field is a letter, then letters, digits and `_`',
   })
 
+/** Whether an entry of the source can change at all: by `updatedAt`, a content field or a `reportOn` field. */
+const canChange = ({ map, reportOn }: { map: Record<string, string | undefined>; reportOn?: string[] }): boolean =>
+  map.updatedAt !== undefined || CONTENT_FIELDS.some((field) => map[field] !== undefined) || reportOn !== undefined
+
 const sourceSchema = z
   .strictObject({
     /** Printed in every report of the source and the key of its saved state. */
@@ -156,12 +190,21 @@ const sourceSchema = z
     reportLimit: z.number().int().min(1).default(5),
     /** The lane the source's reports name. */
     lane: z.string().min(1).optional(),
+    /**
+     * Marks the entries as tickets: the herd shows each as a badge beside the plan of the lane it belongs to,
+     * the lane above or the lane whose board row or plan names its id.
+     */
+    ticket: z.boolean().optional(),
     /**
      * The mapped fields whose change reports, with the old and the new value, in place of the content of `title`,
      * `author`, `body` and `url`; without it a change of that content reports.
      */
     reportOn: z.array(z.string().min(1)).min(1).max(10).optional(),
   })
+  .refine(canChange, {
+    message: 'map needs updatedAt, a content field (title, author, body, url) or reportOn',
+    path: ['map'],
+  })
   .refine((source) => source.ignoreAuthors.length === 0 || source.map.author !== undefined, {
     message: 'ignoreAuthors needs map.author',
     path: ['ignoreAuthors'],
@@ -232,6 +275,12 @@ const guardSchema = z.strictObject({
       approvalMinutes: z.number().int().min(1).max(1440).default(180),
     })
     .prefault({}),
+  approvals: z
+    .strictObject({
+      /** How long the approval gate hook holds a lane's call for the coordinator's dialog before it denies it; below the hook's 10 minutes. */
+      waitMinutes: z.number().int().min(1).max(9).default(8),
+    })
+    .prefault({}),
 })
 
 const hintsSchema = z.strictObject({
@@ -267,7 +316,11 @@ export const jackherdConfigSchema = z.strictObject({
   sprintPattern: z
     .never({ error: 'sprintPattern was replaced by board.pattern (with board.file and board.term)' })
     .optional(),
-  worktreeDirectory: z.string().min(1).default(claudePath(WORKTREES_DIRECTORY)),
+  worktreeDirectory: z
+    .string()
+    .min(1)
+    .refine(isRepositoryDirectory, 'must lie below the repository root: relative, not `.`, without `..`')
+    .default(claudePath(WORKTREES_DIRECTORY)),
   baseBranch: branchName.default(DEFAULT_BASE_BRANCH),
   /**
    * Put before every skill and agent name. `jh sync --global` refuses to run without one: a personal skill
@@ -304,7 +357,7 @@ export const jackherdConfigSchema = z.strictObject({
     .prefault({}),
   plans: z
     .strictObject({
-      /** Minutes between background fetches of the base branch while `jh plans` runs; 0 turns them off. */
+      /** Minutes between background fetches of the base branch while `jh herd` runs; 0 turns them off. */
       fetchIntervalMinutes: z.number().min(0).default(5),
       /** Links in a plan that the sprint page shows as chips; the list replaces the built-in kinds. */
       linkKinds: z
@@ -322,13 +375,15 @@ export const jackherdConfigSchema = z.strictObject({
   /**
    * Read by `jh watch`; without `deploy` it reports no deploy runs. `feedback` is on unless set to `false`:
    * it reports new feedback on the lanes' pull requests except from the account the watcher runs as and `ignore`.
+   * `checks` reads the failed tests of a red lane pull request (`failedTestPattern`), also with `feedback` off.
    * Without `previews` it reads no deploy preview; with it, one `preview` per new head commit. Each of `sources` is a
    * command whose JSON output reports `source` for a new or changed entry.
    */
   watch: z
     .strictObject({
       deploy: deploySchema.optional(),
-      feedback: z.union([z.literal(false), feedbackSchema]).default({ ignore: [] }),
+      feedback: z.union([z.literal(false), feedbackSchema]).prefault({}),
+      checks: checksSchema.prefault({}),
       previews: previewsSchema.optional(),
       sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
     })

package/src/plan-format/board-prose.ts

@@ -0,0 +1,36 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { changedOpenLaneRows } from './lanes'
+
+/**
+ * The longest phases cell, in characters, that still reads as a phase and its state. Longer cells in the open
+ * lanes of the real boards carry prose, which belongs in the plan.
+ */
+export const PHASE_CELL_LIMIT = 250
+
+export const PROSE_REASON = { long: 'long', sideOrder: 'side-order' } as const
+export type ProseReason = (typeof PROSE_REASON)[keyof typeof PROSE_REASON]
+
+/** A changed row of an open lane (1-based line) whose phases cell is `length` characters and carries prose. */
+export type RowWithProse = { line: number; lane: string; reason: ProseReason; length: number }
+
+const reasonOf = (phases: string, marker: string): ProseReason | null => {
+  if (phases.includes(marker)) return PROSE_REASON.sideOrder
+  return phases.length > PHASE_CELL_LIMIT ? PROSE_REASON.long : null
+}
+
+/**
+ * The changed rows of open lanes whose phases cell is longer than `PHASE_CELL_LIMIT` or records a side order of the
+ * user in prose (`dazu (User …`): the board row names the phase, the side order is a task in the plan's phase.
+ * A cell that is both counts once, as a side order.
+ */
+export const boardRowsWithProse = (
+  markdown: string,
+  language: PlanLanguage,
+  previousLines: ReadonlySet<string>,
+): RowWithProse[] => {
+  const { sideOrderMarker } = PLAN_VOCABULARY[language]
+  return changedOpenLaneRows(markdown, language, previousLines).flatMap(({ line, lane, phases }) => {
+    const reason = reasonOf(phases, sideOrderMarker)
+    return reason === null ? [] : [{ line, lane, reason, length: phases.length }]
+  })
+}

package/src/plan-format/dependencies.ts

@@ -0,0 +1,227 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { PHASE_ID_PREFIX } from './lanes'
+import { escapeRegExp, firstTableWithHeader, subsectionLines } from './markdown'
+import { type PhaseHeading, parsePlanPhases, phaseHeadings } from './phases'
+
+/**
+ * A row of the dependency table. `after` holds the phases it waits for, `external` the entries that name no phase
+ * (`User: Zuruf`) or a range that cannot be expanded; `writes` are the paths of the writes cell (`''` is the whole
+ * repository), `writesLike` the phases whose sets the cell takes over (`wie 15 und 16`); `serialMarkers` are the
+ * entries of the marker cell that keep two phases apart.
+ */
+export type PhaseDependency = {
+  id: string
+  after: string[]
+  external: string[]
+  writes: string[]
+  writesLike: string[]
+  serialMarkers: string[]
+}
+
+/** A phase heading (1-based line) the dependency table has no row for. */
+export type PhaseWithoutRow = PhaseHeading
+
+type Candidate = { id: string; writes: string[]; serialMarkers: 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 = /^[—–-]?$/
+const TRAILING_NOTE = /\s*\([^)]*\)\s*$/
+const GLOB_CHARACTER = /[*?{[]/
+const MAX_RANGE = 50
+
+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
+  let start = 0
+  for (const [index, character] of [...cell].entries()) {
+    if (character === '(') depth += 1
+    else if (character === ')') depth = Math.max(depth - 1, 0)
+    else if (character === separator && depth === 0) {
+      entries.push(cell.slice(start, index))
+      start = index + 1
+    }
+  }
+  return [...entries, cell.slice(start)]
+}
+
+/** The ids a range entry (`P15–P20`) spans; null when the entry is no range, empty when it cannot be expanded. */
+const rangeOf = (entry: string): string[] | null => {
+  const match = PHASE_RANGE.exec(entry)
+  if (!match) return null
+  const [first, last] = [Number(match[1]), Number(match[2])]
+  if (first > last || last - first >= MAX_RANGE) return []
+  return Array.from({ length: last - first + 1 }, (_, offset) => String(first + offset))
+}
+
+const dependsOf = (cell: string, language: PlanLanguage): Pick<PhaseDependency, 'after' | 'external'> => {
+  const noDependency = PLAN_VOCABULARY[language].noDependency
+  const entries = splitOutsideParentheses(cell, ',')
+    .map((entry) => entry.trim())
+    .filter((entry) => !NO_VALUE.test(entry) && !noDependency.includes(entry.toLowerCase()))
+  const after = entries.flatMap((entry) => rangeOf(entry) ?? phaseIdOf(entry) ?? [])
+  const external = entries.filter((entry) => {
+    const spanned = rangeOf(entry)
+    return spanned === null ? phaseIdOf(entry) === null : spanned.length === 0
+  })
+  return { after, external }
+}
+
+/**
+ * A path as the cell writes it, cut to the directory a glob character starts in (`scripts/*.ts` is `scripts`,
+ * `.claude/**` is `.claude`, `*.md` is the root `''`) and without a trailing slash; null for a backticked entry with a
+ * space in it, which is a command.
+ */
+const pathOf = (entry: string): string | null => {
+  if (/\s/.test(entry)) return null
+  const glob = entry.search(GLOB_CHARACTER)
+  const literal = glob === -1 ? entry : entry.slice(0, Math.max(entry.lastIndexOf('/', glob), 0))
+  const path = literal.replace(/^\.\//, '').replace(/\/+$/, '')
+  return path === '.' ? '' : path
+}
+
+const likePattern = (language: PlanLanguage): { start: RegExp; id: RegExp } => {
+  const { writesLike, writesLikeJoiners } = PLAN_VOCABULARY[language]
+  const words = (list: readonly string[]) => list.map(escapeRegExp).join('|')
+  const target = `${PHASE_ID_PREFIX}?${ID}`
+  const joiner = `(?:\\s*,\\s*|\\s+(?:${words(writesLikeJoiners)})\\s+|\\s*,\\s*(?:${words(writesLikeJoiners)})\\s+)`
+  return {
+    start: new RegExp(`(?<![\\p{L}\\d])(?:${words(writesLike)})\\s+${target}\\b(?:${joiner}${target}\\b)*`, 'iu'),
+    id: new RegExp(`${PHASE_ID_PREFIX}?${ID}\\b`, 'gi'),
+  }
+}
+
+/** The phases a writes cell takes over (`wie 15`, `wie P15 und P16`, `like 15, 16`), found anywhere in the cell. */
+const writesLikeOf = (cell: string, language: PlanLanguage): string[] => {
+  const { start, id } = likePattern(language)
+  const found = start.exec(cell)?.[0]
+  if (found === undefined) return []
+  const afterWord = found.replace(/^\S+\s+/, '')
+  return [...afterWord.matchAll(id)].map((match) => (match[1] ?? '').toLowerCase())
+}
+
+const writesOf = (cell: string, language: PlanLanguage): Pick<PhaseDependency, 'writes' | 'writesLike'> => ({
+  writes: [...cell.matchAll(BACKTICKED)].flatMap((match) => pathOf(match[1] ?? '') ?? []),
+  writesLike: writesLikeOf(cell, language),
+})
+
+/**
+ * The marker cell's entries, split at `;`, without a trailing note in parentheses and without the release entry: the
+ * release word followed by a space or the end, in any case (`Release-Pipeline` is a marker of its own).
+ */
+const markersOf = (cell: string, language: PlanLanguage): string[] => {
+  const release = new RegExp(`^${escapeRegExp(PLAN_VOCABULARY[language].releaseMarker)}(?:\\s|$)`, 'i')
+  return cell
+    .split(';')
+    .map((entry) => entry.replace(TRAILING_NOTE, '').trim())
+    .filter((entry) => !NO_VALUE.test(entry) && !release.test(entry))
+}
+
+/**
+ * The rows of the plan's dependency table (`### Abhängigkeiten und Parallelisierung`); null when the plan has no
+ * such table or the table lacks one of its three columns, so a plan that never had one is not asked for rows.
+ */
+export const parseDependencyTable = (markdown: string, language: PlanLanguage): PhaseDependency[] | null => {
+  const { sections, columns } = PLAN_VOCABULARY[language]
+  const { header, rows } = firstTableWithHeader(subsectionLines(markdown, sections.dependencies))
+  const [after, writes, marker] = [columns.dependsOn, columns.writes, columns.serialMarker].map((name) =>
+    header.indexOf(name),
+  )
+  if (after === -1 || writes === -1 || marker === -1) return null
+  return rows.flatMap((cells) => {
+    const id = phaseIdOf(cells[0] ?? '')
+    if (id === null) return []
+    return [
+      {
+        id,
+        ...dependsOf(cells[after] ?? '', language),
+        ...writesOf(cells[writes] ?? '', language),
+        serialMarkers: markersOf(cells[marker] ?? '', language),
+      },
+    ]
+  })
+}
+
+/** The phase headings of a plan with a dependency table that the table has no row for; null for a plan without one. */
+export const phasesWithoutDependencyRow = (markdown: string, language: PlanLanguage): PhaseWithoutRow[] | null => {
+  const table = parseDependencyTable(markdown, language)
+  if (table === null) return null
+  const listed = new Set(table.map(({ id }) => id))
+  return phaseHeadings(markdown, language).filter(({ id }) => !listed.has(id))
+}
+
+const mergeSets = (sets: readonly (string[] | null)[]): string[] | null =>
+  sets.some((set) => set === null) ? null : sets.flatMap((set) => set ?? [])
+
+/** The paths a phase writes, those of every phase its `like` cell names included; null for an unknown target or a cycle. */
+const writeSetOf = (
+  row: PhaseDependency,
+  byId: ReadonlyMap<string, PhaseDependency>,
+  chain: readonly string[],
+): string[] | null => {
+  if (chain.includes(row.id)) return null
+  const targets = row.writesLike.map((id) => byId.get(id))
+  const like = mergeSets(targets.map((target) => (target ? writeSetOf(target, byId, [...chain, row.id]) : null)))
+  return like === null ? null : [...row.writes, ...like]
+}
+
+const overlaps = (left: string, right: string): boolean =>
+  left === '' || right === '' || left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)
+
+const sharesMarker = (first: Candidate, second: Candidate): boolean => {
+  const markers = new Set(second.serialMarkers.map((marker) => marker.trim().toLowerCase()))
+  return first.serialMarkers.some((marker) => markers.has(marker.trim().toLowerCase()))
+}
+
+const collides = (first: Candidate, second: Candidate): boolean =>
+  sharesMarker(first, second) || first.writes.some((path) => second.writes.some((other) => overlaps(path, other)))
+
+const candidateOf = (row: PhaseDependency, byId: ReadonlyMap<string, PhaseDependency>): Candidate[] => {
+  const writes = writeSetOf(row, byId, [])
+  return writes === null || writes.length === 0 ? [] : [{ id: row.id, writes, serialMarkers: row.serialMarkers }]
+}
+
+/**
+ * The phases that can run side by side, as groups in table order: the first group can start now, a later one holds
+ * the ready phases that collide with an earlier group's members. A phase is offered when it is not in `doneIds`,
+ * every phase in its `Depends on` cell is, and the cell names no external gate: nothing in the plan says such a gate
+ * holds, so the phase stays out and the caller asks. Two phases share a group only when no path of one lies at or
+ * below a path of the other (a root path lies below nothing and above everything) and they share no serial marker,
+ * compared without case (a release marker does not count). A `wie N` writes cell takes the set of phase N; a phase
+ * whose set is empty, whose `wie` target is unknown, or whose `wie` chain is a cycle, cannot be shown disjoint and
+ * stays out. Whether two phases collide in content, or in the release files, is not decided here.
+ */
+export const parallelGroups = (rows: readonly PhaseDependency[], doneIds: ReadonlySet<string>): string[][] => {
+  const byId = new Map(rows.map((row) => [row.id, row]))
+  const ready = rows
+    .filter((row) => !doneIds.has(row.id) && row.external.length === 0 && row.after.every((id) => doneIds.has(id)))
+    .flatMap((row) => candidateOf(row, byId))
+  const groups: Candidate[][] = []
+  for (const candidate of ready) {
+    const group = groups.find((members) => members.every((member) => !collides(member, candidate)))
+    if (group) group.push(candidate)
+    else groups.push([candidate])
+  }
+  return groups.map((group) => group.map(({ id }) => id))
+}
+
+/** The phases as a report names them, side by side: `P19 ∥ P20`. */
+export const phasesText = (phases: readonly string[]): string =>
+  phases.map((id) => `${PHASE_ID_PREFIX}${id}`).join(' ∥ ')
+
+const donePhaseIds = (markdown: string, language: PlanLanguage): Set<string> =>
+  new Set(
+    parsePlanPhases(markdown, language)
+      .filter(({ items }) => items.length > 0 && items.every((item) => item.done))
+      .map(({ id }) => id),
+  )
+
+/** `parallelGroups` of the plan's own dependency table and ticks (a phase is done when every box is ticked); null for a plan without a table. */
+export const parallelGroupsOfPlan = (markdown: string, language: PlanLanguage): string[][] | null => {
+  const table = parseDependencyTable(markdown, language)
+  return table === null ? null : parallelGroups(table, donePhaseIds(markdown, language))
+}

package/src/plan-format/documentation-gate.ts

@@ -0,0 +1,16 @@
+import { PLAN_VOCABULARY } from '../vocabulary'
+import type { ChecklistItem } from './phases'
+
+const DOCUMENTATION_WORDS = Object.values(PLAN_VOCABULARY).map((vocabulary) =>
+  vocabulary.sections.documentation.toLowerCase(),
+)
+
+/** The review-gate box `Dokumentation aktualisiert …` (`Documentation updated …`): a gate item starting with the documentation word. */
+export const isDocumentationGateItem = ({ gate, text }: ChecklistItem): boolean =>
+  gate === true && DOCUMENTATION_WORDS.some((word) => text.toLowerCase().startsWith(word))
+
+/** The documentation gate box is the only unticked box of the phase: everything else is done. */
+export const onlyDocumentationOpen = ({ items }: { items: readonly ChecklistItem[] }): boolean => {
+  const open = items.filter((item) => !item.done)
+  return open.length === 1 && isDocumentationGateItem(open[0])
+}

package/src/plan-format/index.ts

@@ -1,7 +1,29 @@
 export * from '../vocabulary'
+export * from './board-prose'
+export {
+  type PhaseDependency,
+  type PhaseWithoutRow,
+  parallelGroups,
+  parallelGroupsOfPlan,
+  parseDependencyTable,
+  phasesText,
+  phasesWithoutDependencyRow,
+} from './dependencies'
+export * from './documentation-gate'
 export * from './drift'
 export * from './header'
-export * from './lanes'
+export {
+  laneNameOf,
+  PHASE_ID_PREFIX,
+  type PlanStep,
+  parseSprintLanes,
+  phaseIdsOfCell,
+  resolvePlanPath,
+  type SprintLane,
+  sprintTitleOf,
+  withoutRepeats,
+} from './lanes'
+export * from './model-column'
 export * from './phase-tally'
 export * from './phases'
 export * from './plan-structure'

package/src/plan-format/lanes.ts

@@ -1,6 +1,6 @@
 import { posix } from 'node:path'
 import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { firstHeading, firstTable, sectionLines } from './markdown'
+import { firstHeading, firstTable, firstTableRows, sectionLines, sectionStart } from './markdown'
 
 /**
  * `namedPhaseIds` holds every id the row names when `withoutRepeats` dropped some because an earlier row of the lane
@@ -20,12 +20,16 @@ export type PlanStep = {
 /** A lane of the sprint table; `closed` when its name cell says the lane was cleaned up. */
 export type SprintLane = { name: string; port: number | null; steps: PlanStep[]; closed: boolean }
 
+/** A row of the lanes table (1-based line) of an open lane with the text of its phases cell. */
+export type OpenLaneRow = { line: number; lane: string; phases: string }
+
 const LANE_NAME = /`([^`]+)`/
 const CONTINUATION = '↳'
 const PLAN_LINK = /\[([^\]]+)\]\(([^)]+)\)/
 /** Sprint tables name a phase `P4`; the sidebar title prints it the same way. */
 export const PHASE_ID_PREFIX = 'P'
 
+const PHASES_COLUMN = 3
 const CLAUSE_SEPARATOR = /([;,]|\.(?=\s))\s*/
 const ENTRY_END = new Set([';', '.'])
 
@@ -126,3 +130,33 @@ export const sprintTitleOf = (markdown: string, fallback: string): string => fir
 /** The repository path of a plan link, relative to the sprint document's directory. */
 export const resolvePlanPath = (sprintDirectory: string, href: string): string =>
   posix.normalize(posix.join(sprintDirectory, href.split('#')[0]))
+
+/**
+ * The rows of the lanes table (`## Spuren`) that are not in `previousLines` word for word. The table is read as
+ * `parseSprintLanes` reads it (its first table, a lane closed when any of its rows says so); rows of a closed lane
+ * are history and stay out.
+ */
+export const changedOpenLaneRows = (
+  markdown: string,
+  language: PlanLanguage,
+  previousLines: ReadonlySet<string>,
+): OpenLaneRow[] => {
+  const start = sectionStart(markdown, PLAN_VOCABULARY[language].sections.lanes)
+  if (start === -1) return []
+  const closed = new Set(
+    parseSprintLanes(markdown, language)
+      .filter((lane) => lane.closed)
+      .map((lane) => lane.name),
+  )
+  const rows: OpenLaneRow[] = []
+  let previous: string | null = null
+  for (const { index, line, cells } of firstTableRows(
+    sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes),
+  )) {
+    const lane = laneNameOf(cells[0] ?? '', previous)
+    previous = lane ?? previous
+    if (lane !== null && !closed.has(lane) && !previousLines.has(line))
+      rows.push({ line: start + index + 1, lane, phases: cells[PHASES_COLUMN] ?? '' })
+  }
+  return rows
+}

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

@@ -0,0 +1,52 @@
+/**
+ * A model as a board's model column names it: its words (`Opus 5.5` names `opus`; `claude-sonnet-5-5` names
+ * `claude` and `sonnet`, one of which is the family) and its version (`['5', '5']`).
+ */
+export type ColumnModel = { names: string[]; version: string[] }
+
+const NOTE = /\([^)]*\)/g
+const ENTRY_SEPARATOR = /[/,+→]/
+const TOKEN_SEPARATOR = /[^a-z0-9]+/
+const NAME = /^[a-z]+$/
+const NUMBER = /^\d+$/
+
+const tokensOf = (text: string): string[] => text.toLowerCase().split(TOKEN_SEPARATOR)
+
+/** Words and numbers of an entry; a mixed token (`1m`, a window mark) is neither. */
+const modelOf = (entry: string): ColumnModel | null => {
+  const tokens = tokensOf(entry)
+  const names = tokens.filter((token) => NAME.test(token))
+  return names.length > 0 ? { names, version: tokens.filter((token) => NUMBER.test(token)) } : null
+}
+
+/** The models a model column names, in its order; a note in brackets (`(Plan)`) and a dash name none. */
+export const columnModels = (column: string): ColumnModel[] =>
+  column
+    .replace(NOTE, '')
+    .split(ENTRY_SEPARATOR)
+    .flatMap((entry) => modelOf(entry) ?? [])
+
+const startsWith = (tokens: readonly string[], prefix: readonly string[]): boolean =>
+  prefix.every((part, index) => tokens[index] === part)
+
+/** Whether the id has the name as a whole word with the version right after it or right before it. */
+const fitsName = (tokens: readonly string[], name: string, version: readonly string[]): boolean =>
+  tokens.some(
+    (token, index) =>
+      token === name &&
+      (startsWith(tokens.slice(index + 1), version) ||
+        startsWith(tokens.slice(index - version.length, index), version)),
+  )
+
+const fits = (tokens: readonly string[], { names, version }: ColumnModel): boolean =>
+  names.some((name) => fitsName(tokens, name, version))
+
+/**
+ * Whether a running model's id fits none of the models the column names, by family and version (`Opus 5.5` fits
+ * `claude-opus-5-5`, also with a date or window suffix). Knows no vendor. A column that names no model never differs.
+ */
+export const differsFromColumn = (column: string, modelId: string): boolean => {
+  const models = columnModels(column)
+  const tokens = tokensOf(modelId)
+  return models.length > 0 && !models.some((model) => fits(tokens, model))
+}

package/src/plan-format/phases.ts

@@ -18,6 +18,9 @@ export type MisplacedDeferral = { line: number; target: string; corrected: strin
  */
 export type PlanPhase = { id: string; title: string; items: ChecklistItem[]; deferred?: DeferredItem[]; touched?: true }
 
+/** A phase heading with its 1-based line, the lower-case id and the title. */
+export type PhaseHeading = { line: number; id: string; title: string }
+
 const REVIEW_GATE = /^\s*\*\*review[- ]gate\b/i
 const PHASE_END = /^#{1,3}\s/
 const CHECKBOX = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/
@@ -25,7 +28,8 @@ const SECTION_HEADING = /^##\s+(.+?)\s*$/
 const TOP_HEADING = /^#\s/
 const TABLE_STATUS = { done: '✅', open: '⬜' } as const
 const ROW_NUMBER = /^\d+(\.\d+)*[a-z]?$/
-const NUMBERED_SECTION = /^##\s+(\d+[a-z]?)\s*[—–:-]\s*(.*)$/
+/** `## 10 — title`, and `## P15 — title` as a board names the phase. */
+const NUMBERED_SECTION = new RegExp(`^##\\s+${PHASE_ID_PREFIX}?(\\d+[a-z]?)\\s*[—–:-]\\s*(.*)$`)
 const SECTION_POINTER = /`##\s+([^`]+?)\s*`/
 const DEFERRED_TO = new RegExp(`\\s→\\s*${PHASE_ID_PREFIX}(\\d+[a-z]?)\\s*$`, 'i')
 /** A phase arrow anywhere in a line, with the whitespace before it. */
@@ -195,6 +199,17 @@ const notePointer = (pointers: Map<PlanPhase, string>, phase: PlanPhase | null,
 const headingOf = (line: string, phaseHeading: RegExp): RegExpMatchArray | null =>
   line.match(phaseHeading) ?? line.match(NUMBERED_SECTION)
 
+/** Every phase heading of a plan, `### Phase <id>` and `## P<id> — title` alike, with its 1-based line. */
+export const phaseHeadings = (markdown: string, language: PlanLanguage): PhaseHeading[] => {
+  const phaseHeading = phaseHeadingPattern(language)
+  return markdown.split('\n').flatMap((text, index) => {
+    const heading = headingOf(text, phaseHeading)
+    return heading
+      ? [{ line: index + 1, id: (heading[1] ?? '').toLowerCase(), title: terminalSafe(heading[2] ?? '').trim() }]
+      : []
+  })
+}
+
 /**
  * Every `### Phase <id>` section, and every `## <id> — title` section, with its checkboxes. A
  * section runs to the next heading of level three or higher, so a review-gate list or a `####`