jackherd 1.15.2 → 1.17.0

package/src/plan-contract/command.ts

@@ -3,22 +3,29 @@ import { homedir } from 'node:os'
 import { resolve } from 'node:path'
 import { findProjectRoot } from '../config/location'
 import { readConfig } from '../config/read-config'
+import { installedReferenceHint } from '../lane/skill-hint'
 import { asksForHelp } from '../preview/options'
 import { CLI_NAME } from '../version/release'
 import type { PlanLanguage } from '../vocabulary'
+import { REFERENCE, type Reference, referenceLine } from '../watch/reference-paths'
+import { baseGapLinesFor } from './base-check-git'
 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
+/**
+ * Exit codes of `jh plan check`: the contract is met, a part has a gap, the command line or the file is wrong, the
+ * contract is met but the plan or a board that links it is not on the base branch.
+ */
+export const PLAN_CHECK_EXIT = { met: 0, gaps: 1, error: 2, notOnBase: 3 } 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.
+Where git has the base branch, a plan, or a board that links it, that the base branch lacks gets a \`base:\` line with its path.
 The plan language comes from .jackherd/config.json.
-Exit 0 met, 1 with gaps, 2 for a wrong command line or an unreadable file.`
+Exit 0 met, 1 with gaps, 2 for a wrong command line or an unreadable file, 3 met but not on the base branch.`
 
 const where = (file: string, line: number | null): string => (line === null ? '' : ` ${file}:${line}`)
 
@@ -45,6 +52,12 @@ const readPlan = (file: string): string | null => {
   }
 }
 
+/** The line after the findings that names the reference to read for the gap, for exit 1 and exit 3; none without the skill. */
+const printReference = (reference: Reference, home: string): void => {
+  const root = findProjectRoot(process.cwd(), home, existsSync) ?? process.cwd()
+  for (const line of referenceLine(installedReferenceHint(root, reference, home))) console.log(line)
+}
+
 const fail = (message: string): number => {
   console.error(message)
   return PLAN_CHECK_EXIT.error
@@ -65,5 +78,13 @@ export const run = (args: string[], home: string = homedir()): number => {
   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
+  if (!contract.met) {
+    printReference(REFERENCE.adoptPlan, home)
+    return PLAN_CHECK_EXIT.gaps
+  }
+  const gapLines = baseGapLinesFor(file, process.cwd())
+  for (const line of gapLines) console.log(line)
+  if (gapLines.length === 0) return PLAN_CHECK_EXIT.met
+  printReference(REFERENCE.planCommit, home)
+  return PLAN_CHECK_EXIT.notOnBase
 }

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

@@ -20,11 +20,11 @@ export type PhaseWithoutGate = PhaseHeading
 /** A row of the lanes table (1-based line) whose phases cell names no phase id. */
 export type RowWithoutPhase = OpenLaneRow
 
-/**
- * A `### Phase` heading (1-based line) whose tasks are all ticked on the base branch while its own section still
- * has open checkboxes not moved on with `→ P<n>` (`openLines`, 1-based).
- */
-export type MergedPhaseWithOpenBoxes = PhaseWithoutGate & { openLines: number[] }
+/** A `### Phase` heading (1-based line) whose own section has open checkboxes not moved on with `→ P<n>` (`openLines`, 1-based). */
+export type PhaseWithOpenBoxes = PhaseWithoutGate & { openLines: number[] }
+
+/** A `PhaseWithOpenBoxes` whose tasks are all ticked on the base branch. */
+export type MergedPhaseWithOpenBoxes = PhaseWithOpenBoxes
 
 type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; openLines: number[] }
 
@@ -118,6 +118,18 @@ export const mergedPhasesWithOpenBoxes = (
     .map(({ line, id, title, openLines }) => ({ line, id, title, openLines }))
 }
 
+/**
+ * The phase `id` of `markdown` when its own section still has open checkboxes, gate boxes included, that no `→ P<n>`
+ * at their end moves on; null when it has none or the plan lacks the phase. Unlike `mergedPhasesWithOpenBoxes` it
+ * does not ask whether the phase counts as merged: the caller knows which phase a branch builds.
+ */
+export const openBoxesOfPhase = (markdown: string, language: PlanLanguage, id: string): PhaseWithOpenBoxes | null => {
+  const section = phaseSections(markdown, language).find((candidate) => candidate.id === id)
+  return section && section.openLines.length > 0
+    ? { line: section.line, id: section.id, title: section.title, openLines: section.openLines }
+    : null
+}
+
 /**
  * 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.

package/src/plans/ask-coordinator.ts

@@ -1,8 +1,10 @@
 import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
 import { resolveCoordinatorName } from '../context/coordinator-name'
+import { installedReferenceHintFor } from '../lane/skill-hint'
 import { laneSenderForAsync } from '../settled/send'
 import { type HerdrAsyncRunner, parseAgentList } from '../terminal/herdr'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import { REFERENCE } from '../watch/reference-paths'
 import { ASK_KIND, type AskTarget, boardRowKey } from './ask-target'
 import { errorText } from './error-text'
 import { isQuestionId } from './question-records'
@@ -18,29 +20,32 @@ export type AskDependencies = {
   /** The repository's directory name, from which the coordinator's herdr name follows. */
   repository: string
   run: HerdrAsyncRunner
+  /** Where the repository is looked up for the skill's reference; the working directory when omitted. */
+  cwd?: string
 }
 
 /** A sentence takes the subject's key and, for an entry of a source, the source it belongs to (else `''`). */
-type AskSentences = Record<AskTarget['kind'], (subject: string, scope: string) => string>
+type AskSentences = Record<AskTarget['kind'], (subject: string, scope: string, hint: string) => string>
 
 const ASK_LINES: Record<PlanLanguage, AskSentences> = {
   [PLAN_LANGUAGE.de]: {
-    [ASK_KIND.question]: (id) => `Stell mir die offene Frage ${id} jetzt (jh waiting).`,
-    [ASK_KIND.boardRow]: (key) => `Stell mir die offene Board-Zeile \`${key}\` jetzt (jh waiting).`,
+    [ASK_KIND.question]: (id, _scope, hint) => `Stell mir die offene Frage ${id} jetzt (jh waiting).${hint}`,
+    [ASK_KIND.boardRow]: (key, _scope, hint) =>
+      `Stell mir die offene Board-Zeile \`${key}\` jetzt (jh waiting).${hint}`,
     [ASK_KIND.appointmentRun]: (key) => `Führe den Termin \`${key}\` jetzt aus, unter den Freigaben, die er braucht.`,
     [ASK_KIND.appointmentMove]: (key) =>
       `Frag den User per Dialog nach der neuen Zeit für den Termin \`${key}\` und trag sie ins Board ein (verschobene Zeile = neuer Termin).`,
-    [ASK_KIND.sourceEntry]: (title, source) =>
-      `Sieh dir die Meldung \`${title}\` der Quelle \`${source}\` an und stell mir, falls nötig, die Frage dazu (jh waiting).`,
+    [ASK_KIND.sourceEntry]: (title, source, hint) =>
+      `Sieh dir die Meldung \`${title}\` der Quelle \`${source}\` an und stell mir, falls nötig, die Frage dazu (jh waiting).${hint}`,
   },
   [PLAN_LANGUAGE.en]: {
-    [ASK_KIND.question]: (id) => `Ask me the open question ${id} now (jh waiting).`,
-    [ASK_KIND.boardRow]: (key) => `Ask me the open board row \`${key}\` now (jh waiting).`,
+    [ASK_KIND.question]: (id, _scope, hint) => `Ask me the open question ${id} now (jh waiting).${hint}`,
+    [ASK_KIND.boardRow]: (key, _scope, hint) => `Ask me the open board row \`${key}\` now (jh waiting).${hint}`,
     [ASK_KIND.appointmentRun]: (key) => `Run the appointment \`${key}\` now, under the approvals it needs.`,
     [ASK_KIND.appointmentMove]: (key) =>
       `Ask the user in a dialog for the new time of the appointment \`${key}\` and write it into the board (a moved row is a new appointment).`,
-    [ASK_KIND.sourceEntry]: (title, source) =>
-      `Look at the report \`${title}\` of the source \`${source}\` and, if it needs it, put the question about it to me (jh waiting).`,
+    [ASK_KIND.sourceEntry]: (title, source, hint) =>
+      `Look at the report \`${title}\` of the source \`${source}\` and, if it needs it, put the question about it to me (jh waiting).${hint}`,
   },
 }
 
@@ -60,10 +65,11 @@ const scopeOf = (target: AskTarget): string =>
 /**
  * The line sent to the coordinator: a fixed sentence that carries the id of a question, or the sanitised key of a
  * row (`boardRowKey`), and nothing else from the board or the question, so a prompt line cannot be steered by
- * the file it reads. The caller checks the id with `isQuestionId`.
+ * the file it reads. The caller checks the id with `isQuestionId`. The sentences that send the coordinator to `jh waiting` end
+ * with `hint`, the reference that says how to put the question (none without the orchestrate skill).
  */
-export const askLine = (target: AskTarget, language: PlanLanguage): string =>
-  ASK_LINES[language][target.kind](subjectKeyOf(target), scopeOf(target))
+export const askLine = (target: AskTarget, language: PlanLanguage, hint = ''): string =>
+  ASK_LINES[language][target.kind](subjectKeyOf(target), scopeOf(target), hint)
 
 const isAskable = (target: AskTarget): boolean =>
   target.kind === ASK_KIND.question
@@ -114,7 +120,11 @@ export const askCoordinator = async (target: AskTarget, dependencies: AskDepende
   if ('reason' in coordinator) return TEXTS.notAsked(coordinator.reason)
   const failure = await laneSenderForAsync(dependencies.adapter, dependencies.run)(
     coordinator.name,
-    askLine(target, dependencies.language),
+    askLine(
+      target,
+      dependencies.language,
+      installedReferenceHintFor(dependencies.cwd ?? process.cwd(), REFERENCE.herdAsk),
+    ),
   )
   return failure === null ? TEXTS.asked(coordinator.name, subjectOf(target)) : TEXTS.notAsked(failure)
 }

package/src/plans/board-rows.ts

@@ -26,18 +26,23 @@ const newPartOf = (lane: SprintLane, step: PlanStep): PlanStep | null => {
   return rest.phaseIds.length > 0 ? rest : null
 }
 
-/** The lane with the checkout's steps it does not have yet; the same object when nothing is new. */
+/** Whether the lane is closed: the base says so, or the checkout marks it cleaned up before the mark is merged. */
+const closedBy = (known: SprintLane, checkout: SprintLane | undefined): boolean =>
+  known.closed || checkout?.closed === true
+
+/** The lane with the checkout's steps it does not have yet and its closed mark; the same object when nothing is new. */
 const grownBy = (known: SprintLane, checkout: SprintLane | undefined): SprintLane => {
-  const grown: SprintLane = { ...known, steps: [...known.steps] }
+  const grown: SprintLane = { ...known, steps: [...known.steps], closed: closedBy(known, checkout) }
   for (const step of checkout?.steps ?? []) {
     const part = newPartOf(grown, step)
     if (part !== null) grown.steps.push(part)
   }
-  return grown.steps.length > known.steps.length ? grown : known
+  return grown.steps.length > known.steps.length || grown.closed !== known.closed ? grown : known
 }
 
 /**
- * The board at the base ref with the rows only the checkout has. Base lanes keep their order and their rows;
+ * The board at the base ref with the rows only the checkout has. Base lanes keep their order and their rows, and are
+ * closed when the checkout marks them cleaned up, so the herd drops a lane before the mark reaches the base;
  * a lane only the checkout names is appended; a step of a known lane is added when the base does not name its
  * phases for that plan yet (identity: plan link and phase id), a row without a plan link when its label is new.
  * Both sides come parsed, this function reads no text.

package/src/plans/click-hint.ts

@@ -3,8 +3,10 @@ import { pullRequestNumberOfKey } from './pull-requests'
 import { LINKS_KEY_PREFIX } from './row-focus'
 import {
   BACKLOG_KEY,
+  entryBlockOfKey,
   finishedKey,
   isBlockFolded,
+  isEntryBlockFolded,
   isLaneOpen,
   isLanesOpen,
   isTaskRestKey,
@@ -55,6 +57,8 @@ const foldingHint = (key: string, state: Selection, agentOf: AgentOf): string |
   const lane = laneOfKey(key)
   if (lane !== null) return foldHint(isLaneOpen(state, lane, agentOf(lane)), lane)
   if (key === LANES_KEY) return foldHint(isLanesOpen(state), TEXTS.lanesHeading)
+  const entrySource = entryBlockOfKey(key)
+  if (entrySource !== null) return foldHint(!isEntryBlockFolded(state, entrySource), entrySource)
   const top = topBlockOfKey(key)
   if (top !== null) return foldHint(!isBlockFolded(state, top), TOP_BLOCK_NAMES[top])
   const open = state.expanded.has(key)

package/src/plans/command.ts

@@ -4,7 +4,7 @@ import { laneStatusSourceFor } from '../terminal'
 import { listHerdrAgents } from '../terminal/herdr'
 import { startedKit } from '../version/started-kit'
 import { boardFor, foundLanesOf } from './board-pick'
-import { ensurePlanPanes } from './ensure-panes'
+import { ensurePlanPaneRun } from './ensure-panes'
 import { mainCheckout, worktreeRoot } from './git'
 import { fetchPullRequests } from './github'
 import { claimOwnTerminal, startExclusive } from './herd-claim'
@@ -12,6 +12,7 @@ import { recallLanes, rememberLanes } from './herd-memory'
 import { publishedKey } from './herd-state'
 import { runLive } from './live'
 import { parseOptions } from './options'
+import { ENSURE_EXIT } from './plan-panes'
 import { isSupervisedChild } from './restart-decision'
 import { type PlansSettings, readSettings } from './settings'
 import { loadSnapshot, type Source } from './snapshot'
@@ -55,12 +56,12 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
       foundLanesOf(root, settings, () => terminal.listAgents().map((agent) => agent.name)),
     )
     if (options.ensure) {
-      const lines =
+      const { lines, exitCode } =
         settings.adapter === TERMINAL_ADAPTER.herdr
-          ? ensurePlanPanes(root, settings, picked.file)
-          : ['the terminal adapter is not herdr: no panes to bring back']
+          ? ensurePlanPaneRun(root, settings, picked.file)
+          : { lines: ['the terminal adapter is not herdr: no panes to bring back'], exitCode: ENSURE_EXIT.done }
       for (const line of lines.length > 0 ? lines : ['every herd pane is running']) console.log(line)
-      return 0
+      return exitCode
     }
     const source: Source = { root, sprintFile: picked.file, options, settings, terminal, ...agentListOf(settings) }
     if (options.once || !process.stdout.isTTY) await printOnceWithNotice(source, picked.notice)

package/src/plans/ensure-panes.ts

@@ -8,6 +8,8 @@ import {
   agentPanesOf,
   coordinatorLabelOf,
   coordinatorPaneOf,
+  type EnsureExit,
+  ensureExitOf,
   foregroundOf,
   missingCoordinatorNote,
   type PaneAction,
@@ -60,9 +62,14 @@ const labelCoordinator = (label: { pane: string; label: string } | null) => {
 /**
  * `herd --ensure`: brings back every missing herd pane beside the coordinator and each lane of the board, and
  * leaves running ones alone, so it can run after every start. A lane gets its view once its agent runs. One line per
- * action or skipped target, none when every view runs. The coordinator's pane is labelled `🐾 Jack` on the way.
+ * action or skipped target, none when every view runs, and the exit code (`ENSURE_EXIT`) that says whether the
+ * coordinator's pane was found. The coordinator's pane is labelled `🐾 Jack` on the way.
  */
-export const ensurePlanPanes = (root: string, settings: PlansSettings, boardFile: string): string[] => {
+export const ensurePlanPaneRun = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+): { lines: string[]; exitCode: EnsureExit } => {
   const agents = runHerdr(['agent', 'list'])
   const listed = parseAgentList(agents)
   const panes = panesWithForeground(agentPanesOf(agents))
@@ -84,5 +91,9 @@ export const ensurePlanPanes = (root: string, settings: PlansSettings, boardFile
     command: (lane) => viewCommandOf(process.argv, lane),
     missingCoordinator: missingCoordinatorNote(panes, root, coordinatorName),
   })
-  return [...actions.map(apply), ...notes]
+  return { lines: [...actions.map(apply), ...notes], exitCode: ensureExitOf(panes, coordinator) }
 }
+
+/** The lines of `ensurePlanPaneRun`, for a caller that brings the panes back without an exit code (the watcher). */
+export const ensurePlanPanes = (root: string, settings: PlansSettings, boardFile: string): string[] =>
+  ensurePlanPaneRun(root, settings, boardFile).lines

package/src/plans/git.ts

@@ -39,6 +39,11 @@ export const showAtRef = (root: string, ref: string, path: string): string | nul
   return result.exitCode === 0 ? result.stdout.toString() : null
 }
 
+/** Whether `path` (from the repository root, without `..`) exists at `ref`. */
+export const existsOnRef = (root: string, ref: string, path: string): boolean =>
+  Bun.spawnSync(['git', '-C', root, 'cat-file', '-e', `${ref}:${path}`], { stdout: 'ignore', stderr: 'ignore' })
+    .exitCode === 0
+
 /** The commit `ref` points at, null when it does not exist. */
 export const commitOf = (root: string, ref: string): string | null =>
   git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
@@ -151,6 +156,15 @@ export const mainCheckout = (cwd: string): string => {
   return dirname(commonDirectory)
 }
 
+/** `mainCheckout`, null outside a git checkout instead of git's error. */
+export const mainCheckoutOrNull = (cwd: string): string | null => {
+  try {
+    return mainCheckout(cwd)
+  } catch {
+    return null
+  }
+}
+
 /** The top of the checkout `cwd` is in: the worktree itself, not the main checkout. */
 export const worktreeRoot = (cwd: string): string => {
   const top = git(cwd, ['rev-parse', '--show-toplevel'])

package/src/plans/github.ts

@@ -4,31 +4,40 @@ import { PULL_REQUEST_FIELDS, type PullRequest, parsePullRequests, pullRequestsB
 /** Open pull requests by head branch, or none with the reason when `gh` fails. */
 export type PullRequestState = { byBranch: Map<string, PullRequest[]>; errors: string[] }
 
+/** What `gh` answered: stdout on success, else the reason. */
+export type GhAnswer = { ok: true; stdout: string } | { ok: false; reason: string }
+
 export const noPullRequests = (): PullRequestState => ({ byBranch: new Map(), errors: [] })
 
 /** The GitHub host whose pull request links are trusted; `GH_HOST` names an Enterprise server. */
 export const GITHUB_HOST = process.env.GH_HOST ?? 'github.com'
 
-const runGh = async (root: string): Promise<{ stdout: string; stderr: string; exitCode: number }> => {
-  const child = Bun.spawn(['gh', 'pr', 'list', '--state', 'open', '--limit', '100', '--json', PULL_REQUEST_FIELDS], {
-    cwd: root,
-    stdout: 'pipe',
-    stderr: 'pipe',
-  })
+const runGh = async (args: readonly string[], root: string): Promise<GhAnswer> => {
+  const child = Bun.spawn(['gh', ...args], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
   const [stdout, stderr, exitCode] = await Promise.all([
     new Response(child.stdout).text(),
     new Response(child.stderr).text(),
     child.exited,
   ])
-  return { stdout, stderr, exitCode }
+  return exitCode === 0 ? { ok: true, stdout } : { ok: false, reason: stderr.trim() || `exit ${exitCode}` }
+}
+
+/** Runs `gh`; never rejects, also not when `gh` is not installed, and the reason is terminal-safe. */
+const askGh = async (args: readonly string[], root: string): Promise<GhAnswer> => {
+  try {
+    const answer = await runGh(args, root)
+    return answer.ok ? answer : { ok: false, reason: errorText(answer.reason) }
+  } catch (error) {
+    return { ok: false, reason: errorText(error) }
+  }
 }
 
 /** Open pull requests, or none with the reason; never rejects, also not when `gh` is not installed. */
 export const fetchPullRequests = async (root: string): Promise<PullRequestState> => {
+  const answer = await askGh(['pr', 'list', '--state', 'open', '--limit', '100', '--json', PULL_REQUEST_FIELDS], root)
+  if (!answer.ok) return { byBranch: new Map(), errors: [`gh pr list: ${answer.reason}`] }
   try {
-    const { stdout, stderr, exitCode } = await runGh(root)
-    if (exitCode !== 0) throw new Error(`gh pr list: ${stderr.trim() || `exit ${exitCode}`}`)
-    return { byBranch: pullRequestsByBranch(parsePullRequests(stdout, GITHUB_HOST)), errors: [] }
+    return { byBranch: pullRequestsByBranch(parsePullRequests(answer.stdout, GITHUB_HOST)), errors: [] }
   } catch (error) {
     return { byBranch: new Map(), errors: [errorText(error)] }
   }