jackherd 1.15.2 → 1.17.0

package/src/approval/checked.ts

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { isRecord } from '../shared/is-record'
+import type { ApprovalRequestFile } from '../watch/approvals'
+
+/** What `jh approval show|checked` prints and how it ends: 0 shown, 1 wrong arguments, 2 no such open request. */
+export type ApprovalReport = { exitCode: number; stdout: string[]; stderr: string[] }
+
+type RequestCall = Pick<ApprovalRequestFile, 'lane' | 'cwd' | 'tool' | 'input'>
+
+const VERBS = new Set(['show', 'checked'])
+const USAGE = 'Usage: jh approval show|checked <id> <hash>'
+const ID = /^[0-9a-f]{12}$/
+const HASH = /^[0-9a-f]{16}$/
+
+/** JSON with the keys of every object sorted, as the approval gate hook hashes a call. */
+const canonicalJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (isRecord(value))
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(',')}}`
+  return JSON.stringify(value) ?? 'null'
+}
+
+/** The hash of a call as the approval gate hook writes it (`callHash`, which this package does not import; contract test). */
+export const requestHash = ({ lane, cwd, tool, input }: RequestCall): string =>
+  createHash('sha256').update(canonicalJson({ lane, cwd, tool, input })).digest('hex').slice(0, 16)
+
+const refused = (exitCode: number, line: string): ApprovalReport => ({ exitCode, stdout: [], stderr: [line] })
+
+/** The request as the coordinator reads it before it marks it: every field the lane wrote, made safe to print. */
+const shown = ({ id, hash, lane, tool, cwd, input }: ApprovalRequestFile): string[] => [
+  `approval ${id} ${hash}`,
+  `lane: ${terminalSafe(lane)}`,
+  `tool: ${terminalSafe(tool)}`,
+  `cwd: ${terminalSafe(cwd)}`,
+  'input:',
+  ...(JSON.stringify(input, null, 2) ?? 'null').split('\n').map(terminalSafe),
+]
+
+/**
+ * `jh approval show <id> <hash>` and `jh approval checked <id> <hash>`: print the open request whose id and hash these
+ * are, and whose content its hash covers, and end with 0; otherwise say why and end with 2. Neither writes anything.
+ * `show` is for reading; a successful `checked` in the coordinator's transcript is the mark the approval gate hook
+ * reads as "the coordinator checked exactly this call", so it comes after the check, never before.
+ */
+export const approvalReport = (args: readonly string[], requests: readonly ApprovalRequestFile[]): ApprovalReport => {
+  const [verb, id, hash, ...rest] = args
+  if (!VERBS.has(verb ?? '') || !ID.test(id ?? '') || !HASH.test(hash ?? '') || rest.length > 0)
+    return refused(1, USAGE)
+  const request = requests.find((candidate) => candidate.id === id && candidate.usedAt === null)
+  if (request === undefined) return refused(2, `no open request ${id}`)
+  if (request.hash !== hash)
+    return refused(2, `request ${id} has hash ${request.hash}, not ${hash}: it changed, look at it again`)
+  if (requestHash(request) !== hash)
+    return refused(2, `request ${id} does not match its hash: it was changed by hand, ask the user`)
+  return { exitCode: 0, stdout: shown(request), stderr: [] }
+}

package/src/approval/command.ts

@@ -0,0 +1,16 @@
+import { mainCheckout } from '../plans/git'
+import { readApprovalRequests } from '../watch/approvals'
+import { approvalReport } from './checked'
+
+/** `jh approval show|checked <id> <hash>`: read a held call, and the coordinator's mark that it checked it (`approvalReport`). */
+export const run = (args: string[]): number => {
+  try {
+    const report = approvalReport(args, readApprovalRequests(mainCheckout(process.cwd())))
+    for (const line of report.stdout) console.log(line)
+    for (const line of report.stderr) console.error(line)
+    return report.exitCode
+  } catch (error) {
+    console.error(`jh approval: ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}

package/src/check/command.ts

@@ -3,17 +3,21 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { planRootsIn } from '../../kit/hooks/hooks/shared/boards'
+import { laneOf } from '../../kit/hooks/hooks/shared/lane'
 import { findProjectRoot, globalConfigPath, locateConfigFile, MANIFEST_FILE, TOOL_DIRECTORY } from '../config/location'
 import { readRepositoryFacts } from '../config/repository-facts'
+import { installedReferenceHint } from '../lane/skill-hint'
 import { mainCheckout } from '../plans/git'
 import { baseRefOf } from '../plans/settings'
+import { REFERENCE } from '../watch/reference-paths'
 import { type ChangedFile, parsePorcelain, STATUS_COMMAND } from './changes'
 import { deferralArrowCheck } from './deferral-arrows'
 import { runCheck, runProcess } from './execute'
 import { matchesAnyGlob } from './glob'
+import { lintPointerCheck } from './lint-pointers'
 import { parallelArgument, parallelReportLines } from './parallel-report'
 import { type CheckPlan, type CheckStack, checkStackOf, type Filesystem, isSlow, planChecks } from './plan'
-import { planStructureChecks } from './plan-structure-check'
+import { laneOpenBoxesCheck, planStructureChecks } from './plan-structure-check'
 import { publicContentCheck } from './public-content-check'
 import {
   artifactResult,
@@ -29,6 +33,7 @@ import {
 } from './report'
 import { type CheckResult, RUN_MODE, type RunMode, runModeOf } from './result'
 import { isWorkspaceManifest, kitCopyPaths, WORKSPACE_LIST_FILE, WORKSPACE_MANIFEST } from './roots'
+import { DEFAULT_LINT_POINTERS } from './schema'
 import { type CheckSettings, CONFIG_PATH, noStackFallbackOf, parseCheckSettings, stackOf } from './settings'
 import { skillBudgetCheck } from './skill-budgets'
 
@@ -199,11 +204,50 @@ const planRootsOf = (root: string, worktreeDirectory: string): string[] => {
   }
 }
 
-/** The checks jackherd runs itself beside the configured ones: public content, deferral arrows, skill budgets, plan structure. */
-const ownChecksOf = (root: string, paths: readonly string[], settings: CheckSettings, home: string) => [
+/** The lane a checkout is for: the first directory below the main checkout's worktree directory; null outside one. */
+const laneOfCheckout = (root: string, worktreeDirectory: string): string | null => {
+  try {
+    return laneOf({ cwd: root, main: mainCheckout(root), worktreeDirectory })
+  } catch {
+    return null
+  }
+}
+
+/** The open boxes of the lane's phase, left out for a checkout that is no lane's. */
+const openBoxesCheckOf = (root: string, settings: CheckSettings): CheckResult | null => {
+  const lane = laneOfCheckout(root, settings.worktreeDirectory)
+  return lane === null
+    ? null
+    : laneOpenBoxesCheck({
+        root,
+        lane,
+        planDirectory: settings.planDirectory,
+        board: settings.board,
+        language: settings.planLanguage,
+        level: settings.check.openBoxes,
+        baseOf: contentAt(root, baseRefOf(settings)),
+      })
+}
+
+/** The checks jackherd runs itself beside the configured ones: public content, deferral arrows, skill budgets, lint pointers, plan structure. */
+const ownChecksOf = (
+  root: string,
+  paths: readonly string[],
+  settings: CheckSettings,
+  home: string,
+  kitCopies: readonly string[],
+) => [
+  openBoxesCheckOf(root, settings),
   publicContentCheck(root, paths, settings.check.publicContent, home),
   deferralArrowCheck(root, paths, settings.planDirectory),
   skillBudgetCheck(root, settings.check.skillBudgets, settings.skillPrefix),
+  lintPointerCheck(
+    root,
+    paths,
+    settings.check.lintPointers ?? DEFAULT_LINT_POINTERS,
+    kitCopies,
+    contentAt(root, 'HEAD'),
+  ),
   ...planStructureChecks({
     root,
     paths,
@@ -228,8 +272,9 @@ const checkChanges = async (
 ): Promise<CheckResult[] | string> => {
   const stack = checkStackOf(stackOf(settings.stack))
   let plan: CheckPlan
+  let kitCopies: string[]
   try {
-    const kitCopies = kitCopyPaths(readJsonIfPresent(join(root, TOOL_DIRECTORY, MANIFEST_FILE)))
+    kitCopies = kitCopyPaths(readJsonIfPresent(join(root, TOOL_DIRECTORY, MANIFEST_FILE)))
     plan = planChecks(
       files,
       {
@@ -253,7 +298,7 @@ const checkChanges = async (
     testCommandResult(settings.commands.test, settings.stack),
     missingTestCommandResult(settings.commands.test, settings.stack),
     namedTestResult(plan.sourcesWithoutNamedTest),
-    ...ownChecksOf(root, plan.paths, settings, home),
+    ...ownChecksOf(root, plan.paths, settings, home, kitCopies),
   ])
 }
 
@@ -282,7 +327,7 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
   }
   print(settings.notes)
   if (files.length === 0) {
-    console.log('Nothing changed.')
+    console.log(`Nothing changed.${installedReferenceHint(root, REFERENCE.events, home)}`)
     return 0
   }
   const results = await checkChanges(files, root, settings, runModeOf(args), home)

package/src/check/lint-pointers.ts

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { matchesAnyGlob } from './glob'
+import {
+  changedBlocksOf,
+  LINT_MARKER,
+  LINT_NONE,
+  LINT_POINTER_STATE,
+  LINT_POINTERS_NAME,
+  type LintFinding,
+  lintFindingsOf,
+} from './lint-shaped'
+import { CHECK_STATUS, type CheckResult } from './result'
+import { LINT_POINTERS_LEVEL, type LintPointersConfig, type LintPointersLevel } from './schema'
+
+/** The texts a project writes its rules in: rule files and the instruction files. Skills carry commands, the hooks' field. */
+const LINT_POINTER_GLOBS = ['**/rules/**/*.md', '**/CLAUDE.md', '**/AGENTS.md'] as const
+
+export const isLintPointerPath = (path: string): boolean => matchesAnyGlob(path, LINT_POINTER_GLOBS)
+
+type PathFinding = LintFinding & { path: string }
+
+const WAY_THROUGH = `Write the lint rule and name it with \`${LINT_MARKER}<rule id>\`, or write \`${LINT_MARKER}${LINT_NONE} <reason>\` where it stays prose.`
+
+const HINTS = {
+  [LINT_POINTER_STATE.missing]: '',
+  [LINT_POINTER_STATE.noId]: ` (\`${LINT_MARKER}\` names no rule id)`,
+  [LINT_POINTER_STATE.noReason]: ` (\`${LINT_MARKER}${LINT_NONE}\` needs a reason)`,
+  [LINT_POINTER_STATE.pointed]: '',
+} as const
+
+const lineOf = ({ path, line, shape, excerpt, state }: PathFinding): string =>
+  `${path}:${line} ${shape}: "${excerpt}"${HINTS[state]}`
+
+const detailOf = (findings: readonly PathFinding[]): string =>
+  findings.length === 0
+    ? 'every lint-shaped rule block points at its lint rule'
+    : [...findings.map(lineOf), WAY_THROUGH].join('\n')
+
+const statusOf = (findings: readonly PathFinding[], level: LintPointersLevel): CheckResult['status'] => {
+  if (findings.length === 0) return CHECK_STATUS.pass
+  return level === LINT_POINTERS_LEVEL.fail ? CHECK_STATUS.fail : CHECK_STATUS.warn
+}
+
+/**
+ * The new or changed blocks of the changed rule files that carry a rule a linter could check (an import path,
+ * a literal comparison, a comment form, a banned call) and name no lint rule. Kit copies and `exclude` are not
+ * read; `previousOf` answers a path with the file as `HEAD` holds it. Null when no such file changed or the level is off.
+ */
+export const lintPointerCheck = (
+  root: string,
+  paths: readonly string[],
+  settings: LintPointersConfig,
+  kitCopies: readonly string[],
+  previousOf: (path: string) => string | null,
+): CheckResult | null => {
+  const files = paths.filter(
+    (path) =>
+      isLintPointerPath(path) &&
+      !kitCopies.includes(path) &&
+      !matchesAnyGlob(path, settings.exclude) &&
+      existsSync(join(root, path)),
+  )
+  if (settings.level === LINT_POINTERS_LEVEL.off || files.length === 0) return null
+  const started = Date.now()
+  const findings = files.flatMap((path) =>
+    lintFindingsOf(changedBlocksOf(readFileSync(join(root, path), 'utf8'), previousOf(path))).map((found) => ({
+      ...found,
+      path,
+    })),
+  )
+  return {
+    name: LINT_POINTERS_NAME,
+    command: `${files.length} changed rule ${files.length === 1 ? 'file' : 'files'}, new or changed blocks`,
+    status: statusOf(findings, settings.level),
+    detail: detailOf(findings),
+    durationMs: Date.now() - started,
+  }
+}

package/src/check/lint-shaped.ts

@@ -0,0 +1,196 @@
+/** The `Lint pointers` result name; the kit texts that name the check are held against it. */
+export const LINT_POINTERS_NAME = 'Lint pointers'
+
+/** The inline-code prefix of a pointer: `` `lint:<rule id>` `` names the linter rule that checks the block's rule. */
+export const LINT_MARKER = 'lint:'
+
+/** `` `lint:none` `` plus a reason: the rule stays prose on purpose. */
+export const LINT_NONE = 'none'
+
+/** The kinds of rule a linter can check. */
+export const LINT_SHAPE = {
+  importPath: 'import path',
+  literalComparison: 'literal comparison',
+  commentForm: 'comment form',
+  bannedCall: 'banned call',
+} as const
+
+export type LintShape = (typeof LINT_SHAPE)[keyof typeof LINT_SHAPE]
+
+/** Whether and how a block points at its lint rule. */
+export const LINT_POINTER_STATE = {
+  pointed: 'pointed',
+  missing: 'missing',
+  noId: 'noId',
+  noReason: 'noReason',
+} as const
+
+export type LintPointerState = (typeof LINT_POINTER_STATE)[keyof typeof LINT_POINTER_STATE]
+
+export type Block = { line: number; text: string }
+
+export type LintFinding = { line: number; shape: LintShape; state: LintPointerState; excerpt: string }
+
+const EXCERPT_LENGTH = 100
+
+const GAP = 40
+const BEFORE_SIGNAL = new RegExp(
+  `\\b(?:never|no|not|don't|avoid|instead of|forbidden)\\b([\\p{L}\\p{N}\\s,'’/*()-]{0,${GAP}})\`([^\`\\n]+)\``,
+  'giu',
+)
+const AFTER_SIGNAL = /`([^`\n]+)`[^`\n]{0,25}\b(?:forbidden|banned|refused|never|not allowed|stay out)\b/gi
+const POINTER_SPAN = new RegExp(`\`${LINT_MARKER}([^\`\\n]*)\``, 'g')
+const EXAMPLE_MARK = '❌'
+const IMPORT_WORD = /\b(?:imports?|imported|importing|require)\b/i
+const SCOPED_MODULE = /^(?:@[\w.-]+\/[\w./-]+|~\/[\w./-]+|\.{1,2}\/[\w./-]+)$/
+const PLAIN_MODULE = /^[\w.-]+\/[\w./-]+$/
+const COMPARISON = /(?:===?|!==?)\s*['"`][^'"`]+['"`]/
+const COMMENT_SPAN = /^(?:\/\/|\/\*|<!--|#(?:\s|$)|--(?:\s|$))/
+const CALL_SPAN = /^(?:[\w$]+(?:\.[\w$]+)*|\.[\w$]+)\(/
+const INLINE_CODE = /`([^`\n]+)`/g
+const FENCE = /^\s*```/
+const HEADING = /^#{1,6}\s/
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s/
+const TABLE_ROW = /^\s*\|/
+const WORD = /[\p{L}\p{N}]{2,}/u
+
+const spansOf = (text: string): string[] => [...text.matchAll(INLINE_CODE)].map(([, span]) => span.trim())
+
+const frontmatterEnd = (lines: readonly string[]): number => {
+  if (lines[0]?.trim() !== '---') return 0
+  const close = lines.findIndex((line, index) => index > 0 && line.trim() === '---')
+  return close === -1 ? 0 : close + 1
+}
+
+const isSingleLine = (line: string): boolean => HEADING.test(line) || TABLE_ROW.test(line)
+
+const startsBlock = (line: string): boolean => isSingleLine(line) || LIST_ITEM.test(line)
+
+/**
+ * The blocks of a Markdown text: a paragraph, a list item with its continuation lines, a table row or a
+ * heading, outside code. A code block belongs to the block before it; the frontmatter falls away. `line` is 1-based.
+ */
+export const blocksOf = (markdown: string): Block[] => {
+  const lines = markdown.split('\n')
+  const blocks: { line: number; lines: string[] }[] = []
+  let continuing = false
+  let inFence = false
+  const open = (index: number, line: string) => {
+    blocks.push({ line: index + 1, lines: [line] })
+    continuing = !isSingleLine(line)
+  }
+  for (let index = frontmatterEnd(lines); index < lines.length; index++) {
+    const line = lines[index]
+    const last = blocks.at(-1)
+    if (inFence) {
+      last?.lines.push(line)
+      inFence = !FENCE.test(line)
+    } else if (FENCE.test(line)) {
+      if (last) last.lines.push(line)
+      else open(index, line)
+      inFence = true
+    } else if (line.trim() === '') continuing = false
+    else if (startsBlock(line) || !continuing) open(index, line)
+    else last?.lines.push(line)
+  }
+  return blocks.map(({ line, lines: blockLines }) => ({ line, text: blockLines.join('\n') }))
+}
+
+const splitByFence = (text: string): { prose: string[]; code: string[] } => {
+  const split = { prose: [] as string[], code: [] as string[] }
+  let inFence = false
+  for (const line of text.split('\n')) {
+    if (FENCE.test(line)) inFence = !inFence
+    else (inFence ? split.code : split.prose).push(line)
+  }
+  return split
+}
+
+const proseLinesOf = (text: string): string[] => splitByFence(text).prose
+
+const codeLinesOf = (text: string): string[] => splitByFence(text).code
+
+/** An inline-code span a rule forbids, the words between the signal and the span, and whether the signal followed it. */
+type ForbiddenSpan = { span: string; gap: string; trailing: boolean }
+
+/**
+ * The spans a block marks as forbidden: right after a signal word (`never`, `no`, `not`, `avoid` …, at most
+ * {@link GAP} characters of plain words in between), before `forbidden` or `banned`, or on a line with a `❌`.
+ * A span far from every signal belongs to a sentence that merely mentions it.
+ */
+const forbiddenSpansOf = (text: string): ForbiddenSpan[] => {
+  const prose = proseLinesOf(text)
+  const marked = prose.filter((line) => line.includes(EXAMPLE_MARK)).join('\n')
+  const proseText = prose.join('\n')
+  return [
+    ...[...proseText.matchAll(BEFORE_SIGNAL)].map(([, gap, span]) => ({ span: span.trim(), gap, trailing: false })),
+    ...[...proseText.matchAll(AFTER_SIGNAL)].map(([, span]) => ({ span: span.trim(), gap: '', trailing: true })),
+    ...spansOf(marked).map((span) => ({ span, gap: '', trailing: false })),
+  ]
+}
+
+const isModule = ({ span, gap, trailing }: ForbiddenSpan, text: string): boolean =>
+  (SCOPED_MODULE.test(span) && (trailing || IMPORT_WORD.test(text))) ||
+  (PLAIN_MODULE.test(span) && IMPORT_WORD.test(gap))
+
+const markedCodeComparison = (text: string): boolean =>
+  codeLinesOf(text).some((line) => line.includes(EXAMPLE_MARK) && COMPARISON.test(line))
+
+const hasShape = {
+  [LINT_SHAPE.importPath]: (text: string, forbidden: readonly ForbiddenSpan[]) =>
+    forbidden.some((entry) => isModule(entry, text)),
+  [LINT_SHAPE.literalComparison]: (text: string, forbidden: readonly ForbiddenSpan[]) =>
+    forbidden.some(({ span }) => COMPARISON.test(span)) || markedCodeComparison(text),
+  [LINT_SHAPE.commentForm]: (_text: string, forbidden: readonly ForbiddenSpan[]) =>
+    forbidden.some(({ span }) => COMMENT_SPAN.test(span)),
+  [LINT_SHAPE.bannedCall]: (_text: string, forbidden: readonly ForbiddenSpan[]) =>
+    forbidden.some(({ span }) => CALL_SPAN.test(span)),
+} as const
+
+/**
+ * The kinds of lint-checkable rule a block carries: an inline-code span of that kind that a signal word
+ * forbids, or, for a literal comparison, a code line marked `❌`.
+ */
+export const lintShapesOf = (text: string): LintShape[] => {
+  const forbidden = forbiddenSpansOf(text)
+  return Object.values(LINT_SHAPE).filter((shape) => hasShape[shape](text, forbidden))
+}
+
+const isNoneMarker = (id: string): boolean => id === LINT_NONE || id.startsWith(`${LINT_NONE} `)
+
+const pointerStateOfMatch = (match: RegExpMatchArray, text: string): LintPointerState => {
+  const id = match[1].trim()
+  if (id === '') return LINT_POINTER_STATE.noId
+  if (!isNoneMarker(id)) return LINT_POINTER_STATE.pointed
+  const reason = `${id.slice(LINT_NONE.length)} ${text.slice((match.index ?? 0) + match[0].length)}`
+  return WORD.test(reason) ? LINT_POINTER_STATE.pointed : LINT_POINTER_STATE.noReason
+}
+
+/** Whether a block names its lint rule: `` `lint:<id>` ``, or `` `lint:none` `` with a reason in the block. */
+export const lintPointerStateOf = (text: string): LintPointerState => {
+  const marked = [...text.matchAll(POINTER_SPAN)]
+  if (marked.length === 0) return LINT_POINTER_STATE.missing
+  const states = marked.map((match) => pointerStateOfMatch(match, text))
+  return states.includes(LINT_POINTER_STATE.pointed) ? LINT_POINTER_STATE.pointed : states[0]
+}
+
+const excerptOf = (text: string): string => {
+  const first = text.split('\n')[0].trim()
+  return first.length > EXCERPT_LENGTH ? `${first.slice(0, EXCERPT_LENGTH - 1)}…` : first
+}
+
+/** The blocks that carry a lint-checkable rule and do not point at its lint rule. */
+export const lintFindingsOf = (blocks: readonly Block[]): LintFinding[] =>
+  blocks.flatMap(({ line, text }) => {
+    const [shape] = lintShapesOf(text)
+    const state = lintPointerStateOf(text)
+    return shape && state !== LINT_POINTER_STATE.pointed ? [{ line, shape, state, excerpt: excerptOf(text) }] : []
+  })
+
+const normalized = (text: string): string => text.replace(/\s+/g, ' ').trim()
+
+/** The blocks of `current` whose text `previous` (the file as `HEAD` holds it; null for a new file) lacks. */
+export const changedBlocksOf = (current: string, previous: string | null): Block[] => {
+  const known = new Set(previous === null ? [] : blocksOf(previous).map(({ text }) => normalized(text)))
+  return blocksOf(current).filter(({ text }) => !known.has(normalized(text)))
+}

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

@@ -1,36 +1,47 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join, posix } from 'node:path'
 import { boardPlansOf, isInsideRepository } from '../../kit/hooks/hooks/shared/board-lanes'
-import { planCopiesIn } from '../../kit/hooks/hooks/shared/boards'
+import { boardsIn, planCopiesIn } from '../../kit/hooks/hooks/shared/boards'
+import { readTextOrNull } from '../../kit/hooks/hooks/shared/files'
 import { codesOfPlans } from '../../kit/hooks/hooks/shared/plan-codes'
 import {
   boardRowsWithoutPhase,
   boardRowsWithProse,
+  currentPhase,
   hasLanesTable,
   type LongPhaseTitle,
+  laneProgress,
   longPhaseTitles,
-  type MergedPhaseWithOpenBoxes,
   mergedPhasesWithOpenBoxes,
   newPhasesWithoutReviewGate,
+  openBoxesOfPhase,
   PHASE_CELL_LIMIT,
   PHASE_TITLE_LIMIT,
+  type PhaseWithOpenBoxes,
   type PhaseWithoutGate,
   type PhaseWithoutRow,
   PLAN_VOCABULARY,
   type PlanLanguage,
+  type PlanPhase,
   PROSE_REASON,
+  parsePlanPhases,
+  parseSprintLanes,
   phaseIdsOfPlan,
   phasesWithoutDependencyRow,
   type RowWithoutPhase,
   type RowWithProse,
+  resolvePlanPath,
   SHORT_NAME_LIMIT,
   SHORT_NAME_PROBLEM,
   type ShortNameFinding,
+  type SprintLane,
   shortNameFindings,
 } from '../plan-format'
 import { boardRowsWithBareCodes, type RowWithBareCode } from '../plan-format/bare-codes'
+import { mergePlanPhases } from '../plans/phase-source'
 import { changedPlansOf } from './deferral-arrows'
 import { CHECK_STATUS, type CheckResult } from './result'
+import { OPEN_BOXES_LEVEL, type OpenBoxesLevel } from './schema'
 
 /** The content of a file at a ref; null where the ref lacks the file. */
 export type ContentAt = (path: string) => string | null
@@ -72,6 +83,22 @@ type Report<T> = {
   clean: string
 }
 
+/** The lane a checkout is for and where its boards live, as the check reads them from the checkout. */
+export type LaneBoxesInput = {
+  root: string
+  lane: string
+  planDirectory: string
+  board: { pattern: string; file: string }
+  language: PlanLanguage
+  /** A plan as the base has it (the pull request's parent in the watcher); null where it lacks the file. */
+  baseOf: ContentAt
+}
+
+type BuiltPhase = { planPath: string; phaseId: string; partial: boolean }
+
+/** The phase a lane builds with the plan it is in and its open boxes; `open` is null for a phase without any. */
+export type LaneBuild = { path: string; open: PhaseWithOpenBoxes | null }
+
 const changedCount = (count: number, noun: string): string => `${count} changed ${count === 1 ? noun : `${noun}s`}`
 
 const findingsResult = <T>(
@@ -132,7 +159,7 @@ const bareCodeReport: Report<RowWithBareCode> = {
   clean: 'no changed waiting row names a plan code bare',
 }
 
-const mergedReport: Report<MergedPhaseWithOpenBoxes> = {
+const mergedReport: Report<PhaseWithOpenBoxes> = {
   name: 'Merged phases with open boxes',
   noun: 'plan',
   rule: 'a merged phase ticks or moves on its open boxes',
@@ -205,7 +232,7 @@ const bareCodesOfBoard = (roots: readonly string[], file: Changed, language: Pla
     codesOfPlans(planTextsOf(roots, file, language), language),
   ).map(withPath(file.path))
 
-const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Found<MergedPhaseWithOpenBoxes>[] =>
+const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Found<PhaseWithOpenBoxes>[] =>
   base ? mergedPhasesWithOpenBoxes(current, base, language).map(withPath(path)) : []
 
 const unlistedOf = ({ path, current }: Changed, language: PlanLanguage): Found<PhaseWithoutRow>[] | null =>
@@ -227,6 +254,91 @@ const changedContents = ({ root, previousOf, baseOf, language }: PlanCheckInput,
       return { path, current, previous, previousLines, base: baseOf(path), board: hasLanesTable(current, language) }
     })
 
+const openBoxesText = (lane: string, partialWord: string, path: string, found: PhaseWithOpenBoxes): string =>
+  `${path}:${found.line} Phase ${found.id} ${found.title} is built by lane ${lane} but has open boxes at ${found.openLines.join(', ')}; tick them, end them with → P<n> or mark the row ${partialWord}`
+
+/** The open lane `input.lane` of the newest board that lists it, with the directory its plan links are relative to. */
+const laneOnBoards = (input: LaneBoxesInput): { lane: SprintLane; directory: string } | null => {
+  const boards = boardsIn(input.root, input).sort((left, right) => right.directory.localeCompare(left.directory))
+  for (const { directory, text } of boards) {
+    const lane = parseSprintLanes(text, input.language).find(({ name, closed }) => name === input.lane && !closed)
+    if (lane) return { lane, directory }
+  }
+  return null
+}
+
+/** The lane has work of its own in the checkout, so a phase it ticked further than the base is marked touched, as the herd reads it. */
+const CHECKOUT_WORK = { ahead: 1, dirty: 0 }
+
+/**
+ * The phases of the plan at `path` in the checkout; with the plan on the base too, those the checkout ticked further
+ * are marked touched, which is how the herd tells the phase a lane builds from the first open phase of its row.
+ */
+const phasesInCheckout = (input: LaneBoxesInput, path: string): PlanPhase[] => {
+  const text = readTextOrNull(join(input.root, path))
+  const base = input.baseOf(path)
+  const own = text === null ? [] : parsePlanPhases(text, input.language)
+  return base === null ? own : mergePlanPhases(parsePlanPhases(base, input.language), own, [], CHECKOUT_WORK)
+}
+
+/** The phase the lane's newest board row names, the plan it is in and whether the row marks it as built in parts. */
+const phaseBuiltBy = (input: LaneBoxesInput): BuiltPhase | null => {
+  const found = laneOnBoards(input)
+  if (!found) return null
+  const pathOf = (href: string): string => resolvePlanPath(found.directory, href)
+  const phasesByHref = Object.fromEntries(
+    found.lane.steps.flatMap(({ planHref }) =>
+      planHref === null ? [] : [[planHref, phasesInCheckout(input, pathOf(planHref))] as const],
+    ),
+  )
+  const progress = laneProgress(found.lane, phasesByHref)
+  const phase = currentPhase(progress)
+  const step = progress.current === null ? null : progress.steps[progress.current.stepIndex].step
+  if (!phase || !step?.planHref) return null
+  // with the base known, a phase this checkout did not tick further waits in the row; it is not what the lane builds
+  if (phase.work === undefined && input.baseOf(pathOf(step.planHref)) !== null) return null
+  const partial = step.label.includes(PLAN_VOCABULARY[input.language].partialPhase)
+  return { planPath: pathOf(step.planHref), phaseId: phase.id, partial }
+}
+
+/**
+ * The phase the lane's board row names and its open boxes, read from the checkout whether or not a commit changes the
+ * plan. Null for a lane the checkout's board does not list, for a row marked with the `partialPhase` word (`(Teil)`),
+ * which builds part of the phase, and for a phase ticked to the end, which is no longer the lane's current one.
+ */
+export const laneBuild = (input: LaneBoxesInput): LaneBuild | null => {
+  const built = phaseBuiltBy(input)
+  const plan = built && !built.partial ? readTextOrNull(join(input.root, built.planPath)) : null
+  return built && plan !== null
+    ? { path: built.planPath, open: openBoxesOfPhase(plan, input.language, built.phaseId) }
+    : null
+}
+
+/** What the level makes of a finding: `fail` fails, `warn` warns; `off` never reaches here. */
+const statusOf = (level: OpenBoxesLevel): typeof CHECK_STATUS.fail | typeof CHECK_STATUS.warn =>
+  level === OPEN_BOXES_LEVEL.warn ? CHECK_STATUS.warn : CHECK_STATUS.fail
+
+/**
+ * The open boxes of the phase the lane builds (`laneBuild`) as a check: `level` decides whether they fail, warn or are
+ * not looked at (`off` returns null).
+ */
+export const laneOpenBoxesCheck = (input: LaneBoxesInput & { level: OpenBoxesLevel }): CheckResult | null => {
+  if (input.level === OPEN_BOXES_LEVEL.off) return null
+  const started = Date.now()
+  const build = laneBuild(input)
+  if (!build) return null
+  const { open } = build
+  return {
+    name: 'Open boxes of the lane phase',
+    command: `lane ${input.lane}, the phase its board row names has no open box`,
+    status: open === null ? CHECK_STATUS.pass : statusOf(input.level),
+    detail: open
+      ? openBoxesText(input.lane, PLAN_VOCABULARY[input.language].partialPhase, build.path, open)
+      : 'the phase the lane builds has no open box left',
+    durationMs: Date.now() - started,
+  }
+}
+
 /**
  * The structure of the changed plans and boards:
  * - a phase the change added (against `HEAD`) with tasks and without a review gate fails;

package/src/check/report.ts

@@ -143,12 +143,18 @@ export const formatPlanHeader = (
   '',
 ]
 
+const ADVISORY_LINE = /^(hint|note):/
+
+/** A passing check shows only its advisory lines (`hint:`, `note:`); any other status shows its whole detail. */
+const shownDetail = ({ status, detail }: CheckResult): string[] => {
+  const lines = detail ? detail.split('\n') : []
+  return status === CHECK_STATUS.pass ? lines.filter((line) => ADVISORY_LINE.test(line)) : lines
+}
+
 export const formatResults = (results: readonly CheckResult[]): string[] =>
   results.flatMap((result) => [
     `${STATUS_ICON[result.status]} ${result.name}  (${result.command}, ${result.durationMs}ms)`,
-    ...(result.status !== CHECK_STATUS.pass && result.detail
-      ? result.detail.split('\n').map((line) => `     ${line}`)
-      : []),
+    ...shownDetail(result).map((line) => `     ${line}`),
   ])
 
 const warnings = (count: number): string => (count > 0 ? `${count} ${count === 1 ? 'warning' : 'warnings'}, ` : '')