jackherd 1.6.0 → 1.7.0

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 `####`

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

@@ -1,12 +1,13 @@
 import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { laneNameOf, parseSprintLanes, phaseIdsOfCell } from './lanes'
-import { escapeRegExp, firstTableRows, sectionLines, sectionStart } from './markdown'
+import { changedOpenLaneRows, type OpenLaneRow, phaseIdsOfCell } from './lanes'
+import { escapeRegExp, sectionLines } from './markdown'
 import {
   deferralTarget,
   endsPhase,
   isCheckboxLine,
   isOpenCheckboxLine,
   isReviewGateLine,
+  type PhaseHeading,
   type PlanPhase,
   parsePlanPhases,
   phaseHeadingPattern,
@@ -14,10 +15,10 @@ import {
 import { terminalSafe } from './terminal-text'
 
 /** A `### Phase` heading (1-based line) whose section has tasks and neither a review gate nor the line saying why not. */
-export type PhaseWithoutGate = { line: number; id: string; title: string }
+export type PhaseWithoutGate = PhaseHeading
 
 /** A row of the lanes table (1-based line) whose phases cell names no phase id. */
-export type RowWithoutPhase = { line: number; lane: string; phases: string }
+export type RowWithoutPhase = OpenLaneRow
 
 /**
  * A `### Phase` heading (1-based line) whose tasks are all ticked on the base branch while its own section still
@@ -118,33 +119,14 @@ export const mergedPhasesWithOpenBoxes = (
 }
 
 /**
- * The rows of the lanes table (`## Spuren`) that are not in `previousLines` word for word and whose phases cell
- * names no phase id (`P10c`), so neither the view nor the watcher can tie that step to a phase. 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.
+ * The changed rows of open lanes whose phases cell names no phase id (`P10c`), so neither the view nor the watcher
+ * can tie that step to a phase.
  */
 export const boardRowsWithoutPhase = (
   markdown: string,
   language: PlanLanguage,
   previousLines: ReadonlySet<string>,
-): RowWithoutPhase[] => {
-  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),
+): RowWithoutPhase[] =>
+  changedOpenLaneRows(markdown, language, previousLines).filter(
+    ({ phases }) => phaseIdsOfCell(phases, language).length === 0,
   )
-  const rows: RowWithoutPhase[] = []
-  let previous: string | null = null
-  for (const { index, line, cells } of firstTableRows(
-    sectionLines(markdown, PLAN_VOCABULARY[language].sections.lanes),
-  )) {
-    const [name = '', , , phases = ''] = cells
-    const lane = laneNameOf(name, previous)
-    previous = lane ?? previous
-    const counts = lane !== null && !closed.has(lane) && !previousLines.has(line)
-    if (counts && phaseIdsOfCell(phases, language).length === 0) rows.push({ line: start + index + 1, lane, phases })
-  }
-  return rows
-}

package/src/plan-format/progress.ts

@@ -33,30 +33,12 @@ export const sumPhases = (phases: readonly PhaseProgress[]): { done: number; tot
   total: phases.reduce((sum, phase) => sum + phase.total, 0),
 })
 
-const baseId = (id: string): string => id.replace(/[a-z]$/, '')
-
-const findPhase = (phases: PlanPhase[], id: string): PlanPhase | undefined =>
-  phases.find((phase) => phase.id === id) ?? phases.find((phase) => phase.id === baseId(id))
-
-/**
- * The ids of a step that show a phase of their own. An id the plan lacks (`5b`) falls back to its
- * base phase (`5`); when the step already names that phase by its own id, or an earlier id fell
- * back to it, the fallback would list the same tasks twice, so it is dropped. A lone fallback
- * stays: the sprint line `P4a` finds phase 4 in the plans that have no `4a`.
- */
-export const keptPhaseIds = (phases: PlanPhase[], ids: readonly string[]): string[] => {
-  const shown = new Set(ids.flatMap((id) => phases.filter((phase) => phase.id === id)))
-  return ids.filter((id) => {
-    const phase = findPhase(phases, id)
-    if (!phase || phase.id === id) return true
-    if (shown.has(phase)) return false
-    shown.add(phase)
-    return true
-  })
-}
+/** The phase with exactly this id: a board row's `3c` never falls back to phase 3. */
+const phaseById = <T extends { id: string }>(phases: readonly T[], id: string): T | undefined =>
+  phases.find((phase) => phase.id === id)
 
 const phaseProgress = (phases: PlanPhase[], id: string): PhaseProgress => {
-  const phase = findPhase(phases, id)
+  const phase = phaseById(phases, id)
   const items = phase?.items ?? []
   return {
     id,
@@ -102,16 +84,12 @@ const newestStepWith = (
 
 type LocatedPhase = { phase: PhaseProgress; current: NonNullable<LaneProgress['current']> }
 
-/** The phase a step shows for `id`: by that id, else by its base id, as `keptPhaseIds` keeps a lone fallback. */
-const shownPhase = (phases: readonly PhaseProgress[], id: string): PhaseProgress | undefined =>
-  phases.find((phase) => phase.id === id) ?? phases.find((phase) => phase.id === baseId(id))
-
 /** The phase `id` as the newest step before `before` that shows it from the same plan has it. */
 const earlierPhase = (steps: readonly StepProgress[], before: number, id: string): LocatedPhase | null => {
   const planHref = steps[before].step.planHref
   for (let stepIndex = before - 1; stepIndex >= 0; stepIndex--) {
     if (steps[stepIndex].step.planHref !== planHref) continue
-    const phase = shownPhase(steps[stepIndex].phases, id)
+    const phase = phaseById(steps[stepIndex].phases, id)
     if (phase) return { phase, current: { stepIndex, phaseId: phase.id } }
   }
   return null
@@ -179,7 +157,7 @@ export const currentPhaseOf = (steps: readonly StepProgress[]): LaneProgress['cu
 export const laneProgress = (lane: SprintLane, plans: PlansByHref): LaneProgress => {
   const steps = lane.steps.map((step) => {
     const phases = step.planHref ? plans[step.planHref] : undefined
-    return { step, phases: phases ? keptPhaseIds(phases, step.phaseIds).map((id) => phaseProgress(phases, id)) : [] }
+    return { step, phases: phases ? step.phaseIds.map((id) => phaseProgress(phases, id)) : [] }
   })
   return { lane, steps, current: currentPhaseOf(steps), ...sumPhases(steps.flatMap((step) => step.phases)) }
 }
@@ -187,7 +165,7 @@ export const laneProgress = (lane: SprintLane, plans: PlansByHref): LaneProgress
 export const currentPhase = (progress: LaneProgress): PhaseProgress | null => {
   if (!progress.current) return null
   const { stepIndex, phaseId } = progress.current
-  return progress.steps[stepIndex].phases.find((phase) => phase.id === phaseId) ?? null
+  return phaseById(progress.steps[stepIndex].phases, phaseId) ?? null
 }
 
 /** The item being worked on: the first open checkbox of a phase in plan order, a review-gate item included; null when none is open. */

package/src/plans/command.ts

@@ -27,8 +27,8 @@ const printOnce = async (source: Source): Promise<void> => {
 }
 
 /**
- * `jh plans [<board.md>] [--lane <name>] [--once | --ensure]`: a live view of a board's lanes and their plan
- * progress; `--ensure` instead brings back the missing views beside the coordinator and each lane.
+ * `jh herd [<board.md>] [--lane <name>] [--once | --ensure]`: a live view of a board's lanes and their plan
+ * progress; `--ensure` instead brings back the missing herd panes beside the coordinator and each lane.
  * `home` is where the global config is looked up when the project has none.
  */
 export const run = async (args: string[], home: string = homedir()): Promise<number> => {
@@ -45,7 +45,7 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
         settings.adapter === TERMINAL_ADAPTER.herdr
           ? ensurePlanPanes(root, settings, picked.file)
           : ['the terminal adapter is not herdr: no panes to bring back']
-      for (const line of lines.length > 0 ? lines : ['every plans view is running']) console.log(line)
+      for (const line of lines.length > 0 ? lines : ['every herd pane is running']) console.log(line)
       return 0
     }
     const source = { root, sprintFile: picked.file, options, settings, terminal, boardNotice: picked.notice }

package/src/plans/current-phase.ts

@@ -0,0 +1,71 @@
+import { isTickedUnmerged, type LaneProgress, type PhaseProgress, type PlansByHref } from '../plan-format'
+
+/** A phase of a plan, as the sprint table spells the plan's link. */
+export type PhaseRef = { planHref: string; phaseId: string }
+
+/** Per plan link and phase id, the state of its checkboxes as `1` (ticked) and `0` (open) in plan order. */
+export type TickSnapshot = Record<string, Record<string, string>>
+
+/**
+ * What the herd remembers of a lane between two reads: the ticks it saw, the phase whose ticks moved last and the
+ * identity of the newest board row (`newestRowIdentity`), which a new row changes.
+ */
+export type LaneMemory = { ticks: TickSnapshot; moved: PhaseRef | null; row: string }
+
+export const tickSnapshotOf = (plans: PlansByHref): TickSnapshot =>
+  Object.fromEntries(
+    Object.entries(plans).map(([href, phases]) => [
+      href,
+      Object.fromEntries(
+        phases.map((phase) => [phase.id, phase.items.map((item) => (item.done ? '1' : '0')).join('')]),
+      ),
+    ]),
+  )
+
+/**
+ * The phases both reads have whose ticks differ, in plan order; a plan or phase new in `next` has no state to move
+ * from. A task added to or removed from a phase changes its tick string and counts as movement.
+ */
+export const movedPhases = (previous: TickSnapshot, next: TickSnapshot): PhaseRef[] =>
+  Object.entries(next).flatMap(([planHref, phases]) =>
+    Object.entries(phases).flatMap(([phaseId, ticks]) => {
+      const before = previous[planHref]?.[phaseId]
+      return before !== undefined && before !== ticks ? [{ planHref, phaseId }] : []
+    }),
+  )
+
+/** The newest board row of a lane as its step index and the phase ids it shows, a step `withWorkedPhases` added not counted. */
+export const newestRowIdentity = ({ steps }: LaneProgress): string => {
+  const index = steps.reduce((last, { step }, stepIndex) => (step.withoutRow ? last : stepIndex), -1)
+  return `${index}:${(steps[index]?.phases ?? []).map((phase) => phase.id).join(',')}`
+}
+
+/**
+ * The memory after a read of the lane's plans. The first read has no earlier ticks and no moved phase; exactly one
+ * moved phase becomes the remembered one; none keeps the one moved last; several at once decide nothing, so the
+ * newest board row rules again until a single phase moves. A changed newest board row (`row`) is an explicit
+ * signal and clears the memory.
+ */
+export const nextMemory = (previous: LaneMemory | undefined, plans: PlansByHref, row: string): LaneMemory => {
+  const ticks = tickSnapshotOf(plans)
+  if (!previous || previous.row !== row) return { ticks, moved: null, row }
+  const moved = movedPhases(previous.ticks, ticks)
+  if (moved.length === 0) return { ticks, moved: previous.moved, row }
+  return { ticks, moved: moved.length === 1 ? moved[0] : null, row }
+}
+
+/**
+ * The progress with `moved` as the current phase, in the newest step that shows it with checkboxes; unchanged
+ * when there is no moved phase, the lane does not show it or it is done and merged, so the newest board row decides
+ * as before.
+ */
+export const withMovedPhase = (progress: LaneProgress, moved: PhaseRef | null): LaneProgress => {
+  if (!moved) return progress
+  const isCurrentWork = (phase: PhaseProgress): boolean =>
+    phase.id === moved.phaseId && phase.total > 0 && (phase.done < phase.total || isTickedUnmerged(phase))
+  const showsIt = progress.steps.map(
+    ({ step, phases }) => step.planHref === moved.planHref && phases.some(isCurrentWork),
+  )
+  const stepIndex = showsIt.lastIndexOf(true)
+  return stepIndex < 0 ? progress : { ...progress, current: { stepIndex, phaseId: moved.phaseId } }
+}