jackherd 1.16.0 → 1.18.0

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'}, ` : '')

package/src/check/schema.ts

@@ -68,6 +68,30 @@ const publicContent = z.strictObject({
 /** A budget in words per path or glob from the project root; a key joining two paths with ` + ` budgets them together. */
 const skillBudgets = z.record(glob, z.number().int().positive())
 
+/** What `jh check` does with open boxes in the phase a lane builds: fail, warn or leave the check out. */
+export const OPEN_BOXES_LEVEL = { fail: 'fail', warn: 'warn', off: 'off' } as const
+
+export type OpenBoxesLevel = (typeof OPEN_BOXES_LEVEL)[keyof typeof OPEN_BOXES_LEVEL]
+
+/** What `jh check` does with a lint-shaped rule block that names no lint rule: warn (the default), fail or leave the check out. */
+export const LINT_POINTERS_LEVEL = { warn: 'warn', fail: 'fail', off: 'off' } as const
+
+export type LintPointersLevel = (typeof LINT_POINTERS_LEVEL)[keyof typeof LINT_POINTERS_LEVEL]
+
+const lintPointers = z.strictObject({
+  /** `warn` reports a block and lets the commit through; `fail` stops it; `off` skips the check. */
+  level: z
+    .enum([LINT_POINTERS_LEVEL.warn, LINT_POINTERS_LEVEL.fail, LINT_POINTERS_LEVEL.off])
+    .default(LINT_POINTERS_LEVEL.warn),
+  /** Rule files left unread, as globs from the project root; the kit copies in the lock file are always left out. */
+  exclude: z.array(glob).default([]),
+})
+
+export type LintPointersConfig = z.infer<typeof lintPointers>
+
+/** The check without a `lintPointers` block: warn, nothing excluded. */
+export const DEFAULT_LINT_POINTERS: LintPointersConfig = { level: LINT_POINTERS_LEVEL.warn, exclude: [] }
+
 /**
  * The `check` block of `.jackherd/config.json`. Test and type commands come from the top-level
  * `commands` block; this block holds what only the check runner reads.
@@ -89,6 +113,19 @@ export const checkConfigSchema = z.strictObject({
    * path and sets one for the project's own skills; a file with none is measured against the kit's default.
    */
   skillBudgets: skillBudgets.optional(),
+  /**
+   * What a lane's check does when the phase its board row names still has open boxes without `→ P<n>`: `fail` (the
+   * default) stops the commit, `warn` reports, `off` skips. A row carrying the `partialPhase` word (`(Teil)` in German) builds part of the phase and is
+   * left alone; a branch whose directory is no lane's is not checked.
+   */
+  openBoxes: z
+    .enum([OPEN_BOXES_LEVEL.fail, OPEN_BOXES_LEVEL.warn, OPEN_BOXES_LEVEL.off])
+    .default(OPEN_BOXES_LEVEL.fail),
+  /**
+   * Whether a new or changed block of a rule file (or `CLAUDE.md`, `AGENTS.md`) that a linter could check, such
+   * as a forbidden import path or call, must name its lint rule with `` `lint:<rule id>` `` (or `` `lint:none` `` and a reason).
+   */
+  lintPointers: lintPointers.optional(),
   /** Also run tests in directories that hold test files but belong to no package. */
   looseTests: z.boolean().default(false),
   /**

package/src/check/settings.ts

@@ -25,6 +25,8 @@ export type CheckSettings = {
   baseBranch: string
   /** Where the lane worktrees live, below the main checkout: a board's plans are read there too. */
   worktreeDirectory: string
+  /** Where the boards live: the directories under `planDirectory` and the file in each. */
+  board: { pattern: string; file: string }
   /** Put before the kit's skill and agent names in this project; empty without one. */
   skillPrefix: string
   /** What the lock files (without one, the manifests) decide: one stack, none, or several (ambiguous); `stackOf` reads the stack from it. */
@@ -45,6 +47,7 @@ const planLanguageSchema = jackherdConfigSchema.shape.planLanguage
 const baseBranchSchema = jackherdConfigSchema.shape.baseBranch
 const worktreeDirectorySchema = jackherdConfigSchema.shape.worktreeDirectory
 const skillPrefixSchema = jackherdConfigSchema.shape.skillPrefix
+const boardSchema = jackherdConfigSchema.shape.board
 
 /**
  * The check runner's view of `.jackherd/config.json`: the shared `commands` block, `planDirectory`, `planLanguage` and `baseBranch` plus its own
@@ -62,6 +65,7 @@ export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckS
     planLanguage: planLanguageSchema.parse(object.planLanguage),
     baseBranch: baseBranchSchema.parse(object.baseBranch),
     worktreeDirectory: worktreeDirectorySchema.parse(object.worktreeDirectory),
+    board: boardSchema.parse(object.board),
     skillPrefix: skillPrefixSchema.parse(object.skillPrefix),
     stack: detectStack(facts.lockFiles, facts.manifests),
     notes: detected.notes,