jackherd 1.9.0 → 1.11.0

package/src/plans/link-chips.ts

@@ -1,4 +1,4 @@
-import type { LinkKind } from '../config/link-kinds'
+import { ARTIFACT_LINK_KIND, type LinkKind } from '../config/link-kinds'
 
 /** A link of a plan that matches a link kind, as the sprint page shows it. */
 export type LinkChip = { url: string; label: string; icon: string; private: boolean }
@@ -14,6 +14,7 @@ const MARKS = /\*\*|`/g
 const CONTROL = /\p{Cc}/gu
 
 const linksOf = (line: string): Found[] => {
+  if (!line.includes('http')) return []
   const found: Found[] = []
   const take = (url: string, text: string | null, index: number) =>
     found.push({ url, text, before: line.slice(0, index), line })
@@ -26,9 +27,27 @@ const linksOf = (line: string): Found[] => {
   return found.sort((left, right) => line.indexOf(left.url) - line.indexOf(right.url))
 }
 
-const labelOf = ({ text, before }: Found, kind: LinkKind): string => {
-  const written = text ?? LABEL_BEFORE.exec(before)?.[1]
-  return written ? written.replace(MARKS, '').replace(CONTROL, '').trim() || kind.label : kind.label
+const LIST_LEAD = /^\s*(?:[-*>]\s*)*(?:\[[ xX]\]\s*)?/
+const LEFTOVER_LINK = /\bhttps?:\/\/\S+/g
+const TITLE_END = /[\s:,;.\-–>]+$/
+
+/** What a line says besides its links, without list marks, checkbox and emphasis: the title of a bare artifact link. */
+const lineTitleOf = ({ line }: Found): string =>
+  line
+    .replace(MARKDOWN_LINK, '$1')
+    .replace(AUTOLINK, '')
+    .replace(LEFTOVER_LINK, '')
+    .replace(LIST_LEAD, '')
+    .replace(MARKS, '')
+    .replace(CONTROL, '')
+    .replace(TITLE_END, '')
+    .trim()
+
+const labelOf = (found: Found, kind: LinkKind): string => {
+  const written = found.text ?? LABEL_BEFORE.exec(found.before)?.[1]
+  const own = written?.replace(MARKS, '').replace(CONTROL, '').trim()
+  if (own) return own
+  return (kind.pattern === ARTIFACT_LINK_KIND.pattern && lineTitleOf(found)) || kind.label
 }
 
 /**

package/src/plans/live.ts

@@ -1,14 +1,20 @@
 import { existsSync, type FSWatcher, watch } from 'node:fs'
-import { dirname } from 'node:path'
+import { basename, dirname } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { terminalSafe } from '../plan-format/terminal-text'
+import { runHerdr } from '../terminal/herdr'
 import { openInBrowser } from '../terminal/open'
+import { stripAnsi } from '../terminal/text'
+import { closeWaiting } from '../waiting/command'
+import { appointmentKeys } from './appointment-rows'
+import { askCoordinator } from './ask-coordinator'
 import type { LaneMemory } from './current-phase'
 import { errorText } from './error-text'
 import {
   type FetchState,
   fetchBase,
   fetchNotice,
+  fetchPlanHeads,
   goneLanePullRequests,
   initialFetchState,
   shouldFetch,
@@ -17,18 +23,31 @@ import {
 import { fetchHeadPath } from './git'
 import { fetchPullRequests, noPullRequests, type PullRequestState } from './github'
 import { recallLanes, rememberLanes } from './herd-memory'
-import type { Screen } from './layout'
+import { type Screen, settledSelection } from './layout'
+import { nextKeys } from './next-rows'
 import { type KnownPage, pageAfterWrite, pageKey, pageNeedsWriting, planAnchorOn, withPlanChips } from './plan-chips'
+import { planPullRequests } from './plan-heads'
 import { herdLabel } from './plan-panes'
 import { pullRequestUrl } from './pull-requests'
+import { newReadCache, type ReadCache } from './read-cache'
+import { TAKEN_OVER_CODE, TAKEOVER_SIGNAL } from './restart-decision'
+import { closeRow } from './row-actions'
+import { blockRowByKey, bracketAt, hoveredKeyAt, lineIndexAt, withHovered } from './row-focus'
 import {
   inputOutcome,
+  isActivateKey,
+  isMotion,
   isSprintPageKey,
+  type MouseEvent,
   overviewSelection,
   parseMouse,
+  settledBlockFolds,
+  showDoneNotice,
   splitKeys,
   syncLaneFolds,
-  targetKeys,
+  TOP_BLOCK,
+  type TopBlockId,
+  toggledBlockFold,
   toggledExpansion,
   type View,
   windowTop,
@@ -36,10 +55,21 @@ import {
 import { BASE_REMOTE, baseRefOf, boardRepoPathOf, CLOCK_LOCALE } from './settings'
 import { singleFlight } from './single-flight'
 import { loadSnapshot, type Snapshot, type Source } from './snapshot'
+import { sourceKeys } from './source-rows'
 import { exportSprintPage, writeSprintPageInSteps } from './sprint-export'
 import { boardTexts } from './texts'
-import { bodyRows, clockOf, draw, paneWidth, renderSnapshot, startSelection, TERMINAL_OFF, TERMINAL_ON } from './view'
-import { waitingClick, waitingRows } from './waiting-click'
+import {
+  bodyRows,
+  clockOf,
+  frameOutput,
+  frameToWrite,
+  paneWidth,
+  renderSnapshot,
+  startSelection,
+  TERMINAL_OFF,
+  TERMINAL_ON,
+} from './view'
+import { type BlockClick, type BlockHit, blockClick, blockHeadClick, mainClickOf, waitingKeys } from './waiting-click'
 
 /** The state of the running view; only the functions below `runLive` change it. */
 type Live = {
@@ -58,6 +88,8 @@ type Live = {
   reported: Map<string, string | null>
   /** Per lane, the ticks seen at the last read, the phase that moved last and when each moved; kept across herds (`rememberLanes`). */
   memories: Map<string, LaneMemory>
+  /** Session logs and plans parsed at the last read, kept while they did not change. */
+  cache: ReadCache
   pending: Timer | null
   /** The snapshot as read, without the plan chips; `snapshot` is this plus the chips of `page`. */
   read: Snapshot | null
@@ -66,6 +98,8 @@ type Live = {
   pageWriting: boolean
   flight: (() => Promise<void>) | null
   pageError: string | null
+  /** The frame last written to the terminal; null while its content is unknown, such as after a resize. */
+  written: string | null
 }
 
 const REFRESH_MS = 5_000
@@ -143,7 +177,10 @@ const redraw = (live: Live) => {
   const top = windowTop(live.view, screen.body.cursorLine, screen.body.lines.length, bodyRows(screen))
   live.screen = screen
   live.view = { ...live.view, top }
-  draw(screen, top)
+  const output = frameToWrite(live.written, frameOutput(screen, top, paneWidth(), bodyRows(screen)))
+  if (output === null) return
+  live.written = output
+  process.stdout.write(output)
 }
 
 /** The whole sprint, also while the view shows one lane: the snapshot is read again without the lane filter. */
@@ -193,16 +230,29 @@ const refresh = (live: Live, onChange: () => void): Promise<void> => {
 
 const readOnce = async (live: Live, onChange: () => void) => {
   try {
-    const read = await loadSnapshot(live.source, live.pullRequests, live.memories)
+    const read = await loadSnapshot(live.source, live.pullRequests, live.memories, live.cache)
     rememberLanes(live.source.root, live.memories, read.documents.laneOrder)
     const next = withKnownPage(live, read)
     live.read = read
-    if (!live.snapshot) live.view = { ...live.view, selection: startSelection(next, live.source.options) }
+    if (!live.snapshot)
+      live.view = {
+        ...live.view,
+        selection: startSelection(next, live.source.options),
+      }
     const folded = syncLaneFolds(
       live.view.selection,
-      next.views.map(({ progress, status }) => ({ lane: progress.lane.name, status: status.agent })),
+      next.views.map(({ progress, status }) => ({
+        lane: progress.lane.name,
+        status: status.agent,
+      })),
     )
-    live.view = { ...live.view, selection: folded }
+    const settled = settledBlockFolds(folded, {
+      waiting: waitingKeys(next.waiting ?? []),
+      next: nextKeys(next.next?.rows ?? []),
+      appointments: appointmentKeys(next.appointments?.rows ?? []),
+      sources: sourceKeys(next.sourceBlock?.sources ?? []),
+    })
+    live.view = { ...live.view, selection: settled }
     live.snapshot = next
     const fetchLine = fetchNotice(live.fetch, baseRefOf(live.source.settings), CLOCK_LOCALE)
     live.errors = [
@@ -246,39 +296,133 @@ const openPlan = (live: Live, snapshot: Snapshot, address: string) => {
   live.notice = reason === null ? texts.pageOpened(live.page.path) : texts.pageNotOpenedReason(reason)
 }
 
-/** A plain click on the for-you block expands or folds a cut-off row, or opens its file or Artifact; the opener's failure shows in the footer. */
-const clickWaiting = (live: Live, snapshot: Snapshot, screen: Screen, input: string): boolean => {
-  const mouse = parseMouse(input)
-  const rows = waitingRows(snapshot.waiting ?? [], live.view.selection.expanded, paneWidth())
-  const outcome = mouse ? waitingClick(rows, screen.waitingLine, mouse) : null
-  if (!outcome) return false
+/**
+ * What a hit on a row of a block of the herd does: expands or folds it, asks the coordinator to put a question or a board row
+ * (the result shows in the footer) or opens its address (a failure shows there). An appointment row only ever expands.
+ */
+const applyBlockClick = (live: Live, outcome: BlockClick): void => {
   if ('toggle' in outcome) {
-    live.view = { ...live.view, selection: toggledExpansion(live.view.selection, outcome.toggle) }
-    return true
+    live.view = {
+      ...live.view,
+      selection: toggledExpansion(live.view.selection, outcome.toggle),
+    }
+    return
+  }
+  if ('ask' in outcome) {
+    const { root, settings } = live.source
+    live.notice = askCoordinator(outcome.ask, {
+      language: settings.responseLanguage,
+      adapter: settings.adapter,
+      repository: basename(root),
+      run: runHerdr,
+    })
+    return
+  }
+  if ('done' in outcome) {
+    live.notice = closeRow(outcome.done, {
+      sprintFile: live.source.sprintFile,
+      language: live.source.settings.planLanguage,
+      now: new Date(),
+      closeRecords: (ids) => closeWaiting(live.source.root, ids, Date.now()),
+    })
+    return
   }
   const reason = openInBrowser(outcome.open)
   if (reason) live.notice = boardTextsOf(live).notOpened(terminalSafe(reason))
+}
+
+/**
+ * A plain click on a block on top of the herd, matched against `hit` as it was drawn: the head folds or opens it, a
+ * cut-off row expands, a file or Artifact opens, a question or a board row asks the coordinator; the failure or the result
+ * shows in the footer. An appointment row has nothing to open or ask.
+ */
+const clickBlock = (live: Live, block: TopBlockId, hit: BlockHit | null, input: string): boolean => {
+  const mouse = parseMouse(input)
+  if (!mouse || !hit) return false
+  if (blockHeadClick(hit.firstLine - 1, mouse)) {
+    live.view = {
+      ...live.view,
+      selection: toggledBlockFold(live.view.selection, block, hit.keys),
+    }
+    return true
+  }
+  const outcome = blockClick(hit.rows, hit.firstLine, mouse, hit.moreKey)
+  if (!outcome) return false
+  applyBlockClick(live, outcome)
   return true
 }
 
+/** The mouse moved: the row under it is drawn like the selected one, and the screen is redrawn only when that row changes. */
+const hover = (live: Live, screen: Screen, mouse: MouseEvent): void => {
+  const frame = { headerRows: screen.header.length, bodyRows: bodyRows(screen), top: live.view.top }
+  const key = hoveredKeyAt(screen.focusHits, mouse, frame)
+  const line = lineIndexAt(mouse, frame)
+  const text = line === null ? '' : (screen.header[line] ?? screen.body.lines[line - frame.headerRows] ?? '')
+  const selection = withHovered(
+    live.view.selection,
+    key,
+    key === null ? null : bracketAt(stripAnsi(text), mouse.column - 1),
+  )
+  if (selection === live.view.selection) return
+  live.view = { ...live.view, selection }
+  redraw(live)
+}
+
+/**
+ * Enter or space on the selected row of a block on top does its main action (`mainClickOf`: ask, open, expand); true
+ * when the input was for such a row, whether or not it had anything to do.
+ */
+const activateBlockRow = (live: Live, screen: Screen, input: string): boolean => {
+  if (!isActivateKey(input)) return false
+  const key = live.view.selection.selected
+  const row = key === null ? null : blockRowByKey(blocksOf(screen), key)
+  if (!row) return false
+  const click = mainClickOf(row)
+  if (click) applyBlockClick(live, click)
+  return true
+}
+
+const blocksOf = ({ waitingBlock, nextBlock, appointmentBlock, sourceBlock }: Screen): (BlockHit | null)[] => [
+  waitingBlock,
+  nextBlock,
+  appointmentBlock,
+  sourceBlock,
+]
+
 const handleInput = (live: Live, input: string) => {
   const { snapshot, screen } = live
   if (!snapshot || !screen) return
+  const mouse = parseMouse(input)
+  if (mouse && isMotion(mouse)) {
+    hover(live, screen, mouse)
+    return
+  }
   live.notice = null
+  live.view = { ...live.view, selection: settledSelection(live.view.selection, screen) }
+  if (activateBlockRow(live, screen, input)) {
+    redraw(live)
+    return
+  }
   if (isSprintPageKey(input)) {
     void writeSprintPage(live, snapshot)
     return
   }
-  if (clickWaiting(live, snapshot, screen, input)) {
+  if (
+    clickBlock(live, TOP_BLOCK.waiting, screen.waitingBlock, input) ||
+    clickBlock(live, TOP_BLOCK.next, screen.nextBlock, input) ||
+    clickBlock(live, TOP_BLOCK.appointments, screen.appointmentBlock, input) ||
+    clickBlock(live, TOP_BLOCK.sources, screen.sourceBlock, input)
+  ) {
     redraw(live)
     return
   }
   const context = {
-    keys: targetKeys(screen.body.targets),
+    keys: screen.rowKeys,
     targets: screen.body.targets,
     headerRows: screen.header.length,
     bodyRows: bodyRows(screen),
   }
+  live.notice = showDoneNotice(live.view.selection, input, context.keys)
   const pullRequests = snapshot.views.flatMap((view) => view.pullRequests)
   const outcome = inputOutcome(live.view, input, context, (key) => pullRequestUrl(pullRequests, key))
   live.view = outcome.view
@@ -306,12 +450,14 @@ export const runLive = (source: Source): void => {
     fetchHead: fetchHeadPath(source.root),
     reported: new Map(),
     memories: recallLanes(source.root),
+    cache: newReadCache(),
     pending: null,
     read: null,
     page: null,
     pageWriting: false,
     flight: null,
     pageError: null,
+    written: null,
   }
   const schedule = () => {
     if (live.pending) clearTimeout(live.pending)
@@ -320,6 +466,8 @@ export const runLive = (source: Source): void => {
   const fetchBaseBranch = async () => {
     live.fetch = { ...live.fetch, lastAttempt: Date.now(), running: true }
     const failure = await fetchBase(source.root, BASE_REMOTE, source.settings.baseBranch)
+    const planHeads = planPullRequests([...live.pullRequests.byBranch.values()].flat(), source.settings.planDirectory)
+    if (failure === null) await fetchPlanHeads(source.root, BASE_REMOTE, planHeads)
     live.fetch = {
       ...live.fetch,
       running: false,
@@ -346,17 +494,24 @@ export const runLive = (source: Source): void => {
     fetchWhenDue(readable && gone.length > 0)
     schedule()
   }
-  const quit = () => {
+  const leave = (code: number) => {
     clearTitles(source, live.reported)
     source.terminal.labelOwnPane(null)
     for (const watcher of live.watchers.values()) watcher.close()
     process.stdout.write(TERMINAL_OFF)
-    process.exit(0)
+    process.exit(code)
   }
+  const quit = () => leave(0)
+  const takenOver = () => leave(TAKEN_OVER_CODE)
   const onInput = (input: string) => (QUIT_KEYS.has(input) ? quit() : handleInput(live, input))
 
   source.terminal.labelOwnPane(herdLabel(source.options.lane))
-  enterTerminal(onInput, quit, () => redraw(live))
+  process.removeAllListeners(TAKEOVER_SIGNAL)
+  process.on(TAKEOVER_SIGNAL, takenOver)
+  enterTerminal(onInput, quit, () => {
+    live.written = null
+    redraw(live)
+  })
   setInterval(() => {
     fetchWhenDue(false)
     void refresh(live, schedule)

package/src/plans/next-rows.ts

@@ -0,0 +1,44 @@
+import { sectionLines } from '../plan-format/markdown'
+import { NEXT_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { shortTitle } from './task-name'
+import type { BlockItem } from './waiting-click'
+
+/** A line of the board's next section as the herd shows it. */
+export type NextRow = { text: string }
+
+/** The next block: the section's lines without the ones the for-you block already shows. */
+export type NextBlock = { rows: NextRow[] }
+
+const MAX_NEXT_ROWS = 3
+
+const LIST_LINE = /^(?:\d+[.)]|[-*])\s+(.+)$/
+
+const sameText = (left: string, right: string): boolean => left.trim().toLowerCase() === right.trim().toLowerCase()
+
+/**
+ * The next section of the board, up to three list lines in the order written; the parser cuts after three, as the board
+ * says. A line equal to one of `shown` (the texts of the for-you block) is left out: it stands above already.
+ */
+export const nextBlock = (board: string, language: PlanLanguage, shown: readonly string[]): NextBlock => ({
+  rows: sectionLines(board, NEXT_VOCABULARY[language].heading)
+    .flatMap((line) => LIST_LINE.exec(line.trim())?.[1] ?? [])
+    .slice(0, MAX_NEXT_ROWS)
+    .filter((text) => !shown.some((known) => sameText(known, text)))
+    .map((text) => ({ text })),
+})
+
+const nextKey = ({ text }: NextRow): string => `next>${text}`
+
+/** The rows as the block draws them, numbered; a click on one only expands it. */
+export const nextItems = (rows: readonly NextRow[]): BlockItem[] =>
+  rows.map((row, index) => ({
+    key: nextKey(row),
+    mark: String(index + 1),
+    text: row.text,
+    title: shortTitle(row.text),
+    url: null,
+    ask: null,
+  }))
+
+/** The keys of all rows: what the fold of the block remembers. */
+export const nextKeys = (rows: readonly NextRow[]): string[] => rows.map(nextKey)

package/src/plans/phase-ids.ts

@@ -0,0 +1,8 @@
+const SUB_PHASE_LETTERS = /[a-z]+$/i
+
+/** The main phase a sub-phase belongs to: `10c` is part of `10`; a main phase is its own. */
+export const mainPhaseIdOf = (id: string): string => id.replace(SUB_PHASE_LETTERS, '')
+
+/** Whether `named` names the phase: by its own id, or by its main phase when it is a sub-phase (`21b` by `21`). */
+export const isNamedBy = (id: string, named: ReadonlySet<string>): boolean =>
+  named.has(id) || named.has(mainPhaseIdOf(id))

package/src/plans/phase-source.ts

@@ -35,6 +35,21 @@ const tickCount = (phase: PlanPhase): number => phase.items.filter((item) => ite
 const tickedFurther = (worktreePhase: PlanPhase, basePhase: PlanPhase): boolean =>
   tickCount(worktreePhase) > tickCount(basePhase)
 
+/**
+ * The phases of `base` with each phase replaced by the copy's where the copy ticked it further (`tickedFurther`), and
+ * the phases only the copy has after them. Nothing is marked touched: the copy is someone's branch, not the lane's own
+ * work, so it never makes a phase the lane's current one.
+ */
+export const newerPhases = (base: readonly PlanPhase[], copy: readonly PlanPhase[]): PlanPhase[] => {
+  const copyById = new Map(copy.map((phase) => [phase.id, phase]))
+  const baseIds = new Set(base.map((phase) => phase.id))
+  const inBaseOrder = base.map((basePhase) => {
+    const copied = copyById.get(basePhase.id)
+    return copied && tickedFurther(copied, basePhase) ? copied : basePhase
+  })
+  return [...inBaseOrder, ...copy.filter((phase) => !baseIds.has(phase.id))]
+}
+
 /** A phase read from the worktree is touched when its ticks differ from the base's, or the base lacks it. */
 const markTouched = (phase: PlanPhase, basePhase: PlanPhase | undefined): PlanPhase =>
   basePhase && sameTicks(phase, basePhase) ? phase : { ...phase, touched: true }

package/src/plans/plan-cache.ts

@@ -0,0 +1,28 @@
+import { type PlanLanguage, type PlanPhase, parsePlanPhases } from '../plan-format'
+import type { CacheRound } from '../shared/stat-cache'
+
+type ParsedPlan = { text: string; language: PlanLanguage; phases: PlanPhase[] }
+
+/** The phases of each plan by key, kept while the plan's text and language stay the same. */
+export type PlanCache = Map<string, ParsedPlan>
+
+export type PlanRound = CacheRound<ParsedPlan>
+
+/**
+ * `parsePlanPhases` of the text, asked again only when the text or the language under `key` changed since the cache
+ * saw it. The text decides, not a modification time: most plans come from the base ref, which has none.
+ */
+export const parsedPlanPhases = (
+  round: PlanRound | undefined,
+  key: string,
+  text: string,
+  language: PlanLanguage,
+): PlanPhase[] => {
+  if (!round) return parsePlanPhases(text, language)
+  round.used.add(key)
+  const kept = round.entries.get(key)
+  if (kept && kept.language === language && kept.text === text) return kept.phases
+  const phases = parsePlanPhases(text, language)
+  round.entries.set(key, { text, language, phases })
+  return phases
+}

package/src/plans/plan-heads.ts

@@ -0,0 +1,54 @@
+import type { BaseReader } from './git'
+import type { PullRequest } from './pull-requests'
+
+/** What choosing the heads needs of an open pull request: the herd's and the watcher's lists both carry it. */
+export type PlanPullRequest = Pick<PullRequest, 'number' | 'branch' | 'files'>
+
+/** An open pull request that changes a plan, with a reader of the files at its head. */
+export type PlanHead = { number: number; files: readonly string[]; read: BaseReader }
+
+/** Where the herd keeps the fetched heads of open pull requests: its own namespace, apart from branches and remotes. */
+const PULL_HEAD_NAMESPACE = 'refs/jackherd/pr'
+
+export const pullHeadRef = (number: number): string => `${PULL_HEAD_NAMESPACE}/${number}`
+
+/** The refspec that fetches a pull request's head from `refs/pull/<n>/head`, which GitHub keeps for forks too. */
+export const pullHeadRefspec = (number: number): string => `+refs/pull/${number}/head:${pullHeadRef(number)}`
+
+const changesPlan = (pullRequest: PlanPullRequest, planDirectory: string): boolean =>
+  (pullRequest.files ?? []).some((path) => path.startsWith(`${planDirectory}/`))
+
+/** The open pull requests that change a file under `planDirectory`, by number, so several heads merge in a fixed order. */
+export const planPullRequests = <Open extends PlanPullRequest>(
+  pullRequests: readonly Open[],
+  planDirectory: string,
+): Open[] =>
+  pullRequests
+    .filter((pullRequest) => changesPlan(pullRequest, planDirectory))
+    .sort((first, second) => first.number - second.number)
+
+/**
+ * `readerOf` asked once per ref, the reader kept for every later ask: build it once per read of all lanes, so a
+ * head costs one `git rev-parse` however many lanes read it.
+ */
+export const readerOncePerRef = (readerOf: (ref: string) => BaseReader): ((ref: string) => BaseReader) => {
+  const readers = new Map<string, BaseReader>()
+  return (ref) => {
+    const kept = readers.get(ref) ?? readerOf(ref)
+    readers.set(ref, kept)
+    return kept
+  }
+}
+
+/**
+ * The heads a lane's plans are read from besides the base: every plan pull request but the one of the lane's own
+ * branch, whose ticks the lane's worktree holds already.
+ */
+export const laneHeads = (
+  pullRequests: readonly PlanPullRequest[],
+  ownBranch: string | null,
+  readerOf: (ref: string) => BaseReader,
+): PlanHead[] =>
+  pullRequests
+    .filter(({ branch }) => branch !== ownBranch)
+    .map(({ number, files }) => ({ number, files: files ?? [], read: readerOf(pullHeadRef(number)) }))

package/src/plans/planned.ts

@@ -19,8 +19,15 @@ export type PlannedPlan = {
   phaseIds: string[]
   done: number
   total: number
+  /** Set when the plan file was last changed `STALE_PLAN_DAYS` or more days ago; absent otherwise or when git does not know. */
+  stale?: true
 }
 
+/** Days without a change to its plan file from which a planned phase reads `stale?`. */
+export const STALE_PLAN_DAYS = 14
+
+const DAY_MS = 86_400_000
+
 /** A lane of the sprint and what its agent reports, null when it has none. */
 export type PlannedLane = { lane: SprintLane; agent: string | null }
 
@@ -76,9 +83,24 @@ export const plannedPlans = (input: PlannedInput): PlannedPlan[] => {
   })
 }
 
+/** The plans with `stale` set on those whose file `touchedAt` says was last changed `STALE_PLAN_DAYS` or more days before `now`. */
+export const markStale = (
+  plans: readonly PlannedPlan[],
+  touchedAt: (path: string) => number | null,
+  now: number,
+): PlannedPlan[] =>
+  plans.map((plan) => {
+    const touched = touchedAt(plan.path)
+    return touched !== null && now - touched >= STALE_PLAN_DAYS * DAY_MS ? { ...plan, stale: true } : plan
+  })
+
 /** `P3 P4 P5` */
 export const phaseList = (plan: Pick<PlannedPlan, 'phaseIds'>): string => phaseLabels(plan.phaseIds, ' ')
 
+/** `P3`: the phase of the plan that comes next, the first open one in the order of the plan. */
+export const plannedNextLabel = (plan: Pick<PlannedPlan, 'phaseIds' | 'stale'>): string =>
+  `${phaseLabels(plan.phaseIds.slice(0, 1), ' ')}${plan.stale ? ' stale?' : ''}`
+
 /** How many phases the plans list together. */
 export const plannedPhaseCount = (planned: readonly Pick<PlannedPlan, 'phaseIds'>[]): number =>
   planned.reduce((count, plan) => count + plan.phaseIds.length, 0)

package/src/plans/pull-requests.ts

@@ -14,6 +14,8 @@ export type PullRequest = {
   checks: ChecksState
   /** The names of the checks that failed, each once, in the rollup's order; empty while none failed. */
   failedChecks: string[]
+  /** The paths the pull request changes, as `gh` lists them (at most 100); absent when the answer has none. */
+  files?: string[]
 }
 
 /**
@@ -40,10 +42,11 @@ export type GhPullRequest = {
   headRefName: string
   isDraft: boolean
   statusCheckRollup: RollupEntry[] | null
+  files?: { path: string }[]
 }
 
 /** The fields `parsePullRequests` reads; pass them to `gh pr list --json`. */
-export const PULL_REQUEST_FIELDS = 'number,title,url,headRefName,isDraft,statusCheckRollup'
+export const PULL_REQUEST_FIELDS = 'number,title,url,headRefName,isDraft,statusCheckRollup,files'
 
 const RUN_IN_PATH = /^\/([\w.-]+)\/([\w.-]+)\/actions\/runs\/(\d+)(?:\/|$)/
 
@@ -131,6 +134,16 @@ const isPullRequestPage = (url: string, number: number, host: string): boolean =
   }
 }
 
+const isFileList = (value: unknown): boolean =>
+  Array.isArray(value) &&
+  value.every(
+    (file) => typeof file === 'object' && file !== null && typeof (file as { path?: unknown }).path === 'string',
+  )
+
+/** The `files` of a `gh` answer as plain paths, to spread into a pull request; nothing when the answer has none. */
+export const filePathsOf = ({ files }: Pick<GhPullRequest, 'files'>): { files?: string[] } =>
+  files ? { files: files.map(({ path }) => path) } : {}
+
 /** One entry of `gh pr list --json <PULL_REQUEST_FIELDS>` whose link is the pull request's own page on `host`. */
 export const isGhPullRequest = (value: unknown, host: string): value is GhPullRequest => {
   if (typeof value !== 'object' || value === null) return false
@@ -142,7 +155,8 @@ export const isGhPullRequest = (value: unknown, host: string): value is GhPullRe
     isPullRequestPage(candidate.url, candidate.number, host) &&
     typeof candidate.headRefName === 'string' &&
     typeof candidate.isDraft === 'boolean' &&
-    (candidate.statusCheckRollup === null || Array.isArray(candidate.statusCheckRollup))
+    (candidate.statusCheckRollup === null || Array.isArray(candidate.statusCheckRollup)) &&
+    (candidate.files === undefined || isFileList(candidate.files))
   )
 }
 
@@ -163,6 +177,7 @@ export const parsePullRequests = (json: string, host = 'github.com'): PullReques
     draft: pullRequest.isDraft,
     checks: checksOf(pullRequest.statusCheckRollup ?? []),
     failedChecks: failedChecksOf(pullRequest.statusCheckRollup ?? [], pullRequest.url).map(({ name }) => name),
+    ...filePathsOf(pullRequest),
   }))
 }