jackherd 1.6.0 → 1.7.0

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

@@ -2,15 +2,21 @@ import { existsSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import {
   boardRowsWithoutPhase,
+  boardRowsWithProse,
   hasLanesTable,
   type MergedPhaseWithOpenBoxes,
   mergedPhasesWithOpenBoxes,
   newPhasesWithoutReviewGate,
+  PHASE_CELL_LIMIT,
   type PhaseWithoutGate,
+  type PhaseWithoutRow,
   PLAN_VOCABULARY,
   type PlanLanguage,
+  PROSE_REASON,
   phaseIdsOfPlan,
+  phasesWithoutDependencyRow,
   type RowWithoutPhase,
+  type RowWithProse,
 } from '../plan-format'
 import { changedPlansOf } from './deferral-arrows'
 import { CHECK_STATUS, type CheckResult } from './result'
@@ -31,60 +37,97 @@ export type PlanCheckInput = {
   baseOf: ContentAt
 }
 
-type Changed = { path: string; current: string; previous: string | null; base: string | null; board: boolean }
+type Changed = {
+  path: string
+  current: string
+  previous: string | null
+  previousLines: ReadonlySet<string>
+  base: string | null
+  board: boolean
+}
 
 type Found<T> = T & { path: string }
 
-const gateResult = (
-  findings: readonly Found<PhaseWithoutGate>[],
-  plans: number,
-  language: PlanLanguage,
+type Report<T> = {
+  name: string
+  noun: 'plan' | 'board'
+  /** What the check asks of each changed file, as the command column reads after the count. */
+  rule: string
+  /** The status of a check with findings. */
+  unmet: typeof CHECK_STATUS.fail | typeof CHECK_STATUS.warn
+  text: (found: Found<T>) => string
+  clean: string
+}
+
+const changedCount = (count: number, noun: string): string => `${count} changed ${count === 1 ? noun : `${noun}s`}`
+
+const findingsResult = <T>(
+  { name, noun, rule, unmet, text, clean }: Report<T>,
+  findings: readonly Found<T>[],
+  files: number,
   durationMs: number,
 ): CheckResult => ({
-  name: 'Plan review gates',
-  command: `${plans} changed ${plans === 1 ? 'plan' : 'plans'}, new phases need a review gate`,
-  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.fail,
-  detail:
-    findings
-      .map(
-        ({ path, line, id, title }) =>
-          `${path}:${line} Phase ${id} ${title} has tasks but no review gate; add one, or a **${PLAN_VOCABULARY[language].noReviewGate}:** line with the reason`,
-      )
-      .join('\n') || 'every new phase has a review gate',
+  name,
+  command: `${changedCount(files, noun)}, ${rule}`,
+  status: findings.length === 0 ? CHECK_STATUS.pass : unmet,
+  detail: findings.map(text).join('\n') || clean,
   durationMs,
 })
 
-const rowResult = (findings: readonly Found<RowWithoutPhase>[], boards: number, durationMs: number): CheckResult => ({
-  name: 'Board rows without a phase',
-  command: `${boards} changed ${boards === 1 ? 'board' : 'boards'}, changed lane rows name a phase`,
-  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.warn,
-  detail:
-    findings
-      .map(
-        ({ path, line, lane, phases }) =>
-          `${path}:${line} lane ${lane}: "${phases}" names no phase (P<n>), so the view cannot tie the step to one`,
-      )
-      .join('\n') || 'every changed lane row names a phase',
-  durationMs,
+const gateReport = (language: PlanLanguage): Report<PhaseWithoutGate> => ({
+  name: 'Plan review gates',
+  noun: 'plan',
+  rule: 'new phases need a review gate',
+  unmet: CHECK_STATUS.fail,
+  text: ({ path, line, id, title }) =>
+    `${path}:${line} Phase ${id} ${title} has tasks but no review gate; add one, or a **${PLAN_VOCABULARY[language].noReviewGate}:** line with the reason`,
+  clean: 'every new phase has a review gate',
 })
 
-const mergedResult = (
-  findings: readonly Found<MergedPhaseWithOpenBoxes>[],
-  plans: number,
-  durationMs: number,
-): CheckResult => ({
+const rowReport: Report<RowWithoutPhase> = {
+  name: 'Board rows without a phase',
+  noun: 'board',
+  rule: 'changed lane rows name a phase',
+  unmet: CHECK_STATUS.warn,
+  text: ({ path, line, lane, phases }) =>
+    `${path}:${line} lane ${lane}: "${phases}" names no phase (P<n>), so the herd cannot tie the step to one`,
+  clean: 'every changed lane row names a phase',
+}
+
+const proseText = ({ reason, length }: RowWithProse): string =>
+  reason === PROSE_REASON.sideOrder
+    ? 'the phase cell records a side order of the user'
+    : `the phase cell has ${length} characters (limit ${PHASE_CELL_LIMIT})`
+
+const proseReport: Report<RowWithProse> = {
+  name: 'Board rows with prose',
+  noun: 'board',
+  rule: 'changed lane rows name the phase only',
+  unmet: CHECK_STATUS.warn,
+  text: (found) =>
+    `${found.path}:${found.line} lane ${found.lane}: ${proseText(found)}; it belongs as a task in the plan`,
+  clean: 'every changed lane row names the phase only',
+}
+
+const mergedReport: Report<MergedPhaseWithOpenBoxes> = {
   name: 'Merged phases with open boxes',
-  command: `${plans} changed ${plans === 1 ? 'plan' : 'plans'}, a merged phase ticks or moves on its open boxes`,
-  status: findings.length === 0 ? CHECK_STATUS.pass : CHECK_STATUS.warn,
-  detail:
-    findings
-      .map(
-        ({ path, line, id, title, openLines }) =>
-          `${path}:${line} Phase ${id} ${title} is merged but has open boxes at ${openLines.join(', ')}; tick them or end them with → P<n>`,
-      )
-      .join('\n') || 'no merged phase has an open box left',
-  durationMs,
-})
+  noun: 'plan',
+  rule: 'a merged phase ticks or moves on its open boxes',
+  unmet: CHECK_STATUS.warn,
+  text: ({ path, line, id, title, openLines }) =>
+    `${path}:${line} Phase ${id} ${title} is merged but has open boxes at ${openLines.join(', ')}; tick them or end them with → P<n>`,
+  clean: 'no merged phase has an open box left',
+}
+
+const unlistedReport: Report<PhaseWithoutRow> = {
+  name: 'Phases without a dependency row',
+  noun: 'plan',
+  rule: 'every phase has a row in the dependency table',
+  unmet: CHECK_STATUS.warn,
+  text: ({ path, line, id, title }) =>
+    `${path}:${line} Phase ${id} ${title} has no row in the dependency table; add one with its dependencies, writes and serial marker`,
+  clean: 'every phase has a row in the dependency table',
+}
 
 const withPath =
   <T>(path: string) =>
@@ -95,25 +138,38 @@ const gatesOf = ({ path, current, previous }: Changed, language: PlanLanguage):
     withPath(path),
   )
 
-const rowsOf = ({ path, current, previous }: Changed, language: PlanLanguage): Found<RowWithoutPhase>[] =>
-  boardRowsWithoutPhase(current, language, new Set(previous?.split('\n') ?? [])).map(withPath(path))
+const rowsOf = ({ path, current, previousLines }: Changed, language: PlanLanguage): Found<RowWithoutPhase>[] =>
+  boardRowsWithoutPhase(current, language, previousLines).map(withPath(path))
+
+const proseOf = ({ path, current, previousLines }: Changed, language: PlanLanguage): Found<RowWithProse>[] =>
+  boardRowsWithProse(current, language, previousLines).map(withPath(path))
 
 const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Found<MergedPhaseWithOpenBoxes>[] =>
   base ? mergedPhasesWithOpenBoxes(current, base, language).map(withPath(path)) : []
 
+const unlistedOf = ({ path, current }: Changed, language: PlanLanguage): Found<PhaseWithoutRow>[] | null =>
+  phasesWithoutDependencyRow(current, language)?.map(withPath(path)) ?? null
+
 const changedContents = ({ root, previousOf, baseOf, language }: PlanCheckInput, plans: readonly string[]): Changed[] =>
   plans
     .filter((path) => existsSync(join(root, path)))
     .map((path) => {
       const current = readFileSync(join(root, path), 'utf8')
-      return { path, current, previous: previousOf(path), base: baseOf(path), board: hasLanesTable(current, language) }
+      const previous = previousOf(path)
+      const previousLines = new Set(previous?.split('\n') ?? [])
+      return { path, current, previous, previousLines, base: baseOf(path), board: hasLanesTable(current, language) }
     })
 
 /**
- * The structure of the changed plans and boards: a phase the change added (against `HEAD`) with tasks and without
- * a review gate fails; a lane row the change added or edited that names no phase warns; a phase whose tasks are
- * all ticked on the base branch and that still has open boxes without `→ P<n>` warns. Empty when no plan changed;
- * the row result is left out when no changed file has a lanes table, the merged result when every one has.
+ * The structure of the changed plans and boards:
+ * - a phase the change added (against `HEAD`) with tasks and without a review gate fails;
+ * - a lane row the change added or edited that names no phase warns, and so does one whose phases cell is longer
+ *   than `PHASE_CELL_LIMIT` or records a side order of the user;
+ * - a phase whose tasks are all ticked on the base branch and that still has open boxes without `→ P<n>` warns;
+ * - a phase of a plan with a dependency table that has no row in it warns.
+ *
+ * Empty when no plan changed. The row and prose results are left out when no changed file has a lanes table, the
+ * merged result when every one has, the dependency result when no changed plan has the table.
  */
 export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
   const files = changedPlansOf(input.paths, input.planDirectory)
@@ -123,13 +179,24 @@ export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
   const changed = changedContents(input, files)
   const boards = changed.filter(({ board }) => board)
   const plans = changed.filter(({ board }) => !board)
+  const unlistedPerPlan = plans.map((file) => unlistedOf(file, language)).filter((found) => found !== null)
   const gates = changed.flatMap((file) => gatesOf(file, language))
   const rows = boards.flatMap((file) => rowsOf(file, language))
+  const prose = boards.flatMap((file) => proseOf(file, language))
   const merged = plans.flatMap((file) => mergedOf(file, language))
+  const unlisted = unlistedPerPlan.flat()
   const durationMs = Date.now() - started
   return [
-    gateResult(gates, files.length, language, durationMs),
-    ...(boards.length > 0 ? [rowResult(rows, boards.length, durationMs)] : []),
-    ...(plans.length > 0 ? [mergedResult(merged, plans.length, durationMs)] : []),
+    findingsResult(gateReport(language), gates, files.length, durationMs),
+    ...(boards.length > 0
+      ? [
+          findingsResult(rowReport, rows, boards.length, durationMs),
+          findingsResult(proseReport, prose, boards.length, durationMs),
+        ]
+      : []),
+    ...(plans.length > 0 ? [findingsResult(mergedReport, merged, plans.length, durationMs)] : []),
+    ...(unlistedPerPlan.length > 0
+      ? [findingsResult(unlistedReport, unlisted, unlistedPerPlan.length, durationMs)]
+      : []),
   ]
 }

package/src/cli.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { pathToFileURL } from 'node:url'
+import { HERD_COMMAND } from './plans/herd-command'
 import { locateKit } from './sync/kit-source'
 import { CLI_NAME } from './version/release'
 
@@ -12,13 +13,17 @@ export type Resolution =
   | { kind: 'version' }
   | { kind: 'usage'; exitCode: number; message: string }
 
+/** Commands that stay callable but are not advertised in the usage line. */
+const ALIASES = new Set<string>([HERD_COMMAND.alias])
+
 /** One line per command; each entry lazily imports the module that exports its `run`. */
 export const COMMANDS: CommandTable = {
   check: () => import('./check/command'),
   config: () => import('./config/command'),
   context: () => import('./context/command'),
+  [HERD_COMMAND.name]: () => import('./plans/command'),
   init: () => import('./sync/init-command'),
-  plans: () => import('./plans/command'),
+  [HERD_COMMAND.alias]: () => import('./plans/command'),
   sync: () => import('./sync/command'),
   update: () => import('./update/command'),
   watch: () => import('./watch/command'),
@@ -27,7 +32,8 @@ export const COMMANDS: CommandTable = {
 export const resolveCommand = (argv: string[], table: CommandTable): Resolution => {
   const [name, ...args] = argv
   const names = Object.keys(table)
-  const usage = `Usage: ${CLI_NAME} <command> [args]\n       ${CLI_NAME} --version\nCommands: ${names.length > 0 ? names.join(', ') : '(none yet)'}`
+  const advertised = names.filter((entry) => !ALIASES.has(entry))
+  const usage = `Usage: ${CLI_NAME} <command> [args]\n       ${CLI_NAME} --version\nCommands: ${advertised.length > 0 ? advertised.join(', ') : '(none yet)'}`
   if (name === '--version' || name === '-v') return { kind: 'version' }
   if (!name || name === '--help' || name === '-h') return { kind: 'usage', exitCode: name ? 0 : 1, message: usage }
   if (!names.includes(name)) return { kind: 'usage', exitCode: 1, message: `Unknown command: ${name}\n${usage}` }

package/src/config/nested-quantifier.ts

@@ -0,0 +1,73 @@
+type Group = { repeats: boolean; branches: string[] }
+
+const GROUP_PREFIX = /^\?(?::|=|!|<=|<!|<[^>]+>)/
+const BRACES = /^\{(\d+)(?:(,)(\d*))?\}/
+
+/** Length of an unbounded or repeating quantifier (`*`, `+`, `{n,}`, `{n,m}` with m above 1) at `index`, else 0. */
+const repeatingLengthAt = (pattern: string, index: number): number => {
+  if (pattern[index] === '*' || pattern[index] === '+') return 1
+  const braces = pattern.slice(index).match(BRACES)
+  const [text, , comma, max] = braces ?? []
+  return text !== undefined && comma && (max === '' || Number(max) > 1) ? text.length : 0
+}
+
+const classEnd = (pattern: string, start: number): number => {
+  let index = start + 1
+  while (index < pattern.length && pattern[index] !== ']') index += pattern[index] === '\\' ? 2 : 1
+  return index
+}
+
+const overlapsAnother = (branches: readonly string[]): boolean =>
+  branches.some((branch, index) =>
+    branches.some((other, otherIndex) => index !== otherIndex && other.startsWith(branch)),
+  )
+
+const NESTED = -1
+
+const appendTo = (group: Group, text: string): void => {
+  group.branches[group.branches.length - 1] += text
+}
+
+const prefixLengthAt = (pattern: string, index: number): number =>
+  pattern.slice(index + 1).match(GROUP_PREFIX)?.[0].length ?? 0
+
+/** Closes the group at `index`; NESTED when it repeats and holds a repeat or branches that begin alike. */
+const closeGroup = (pattern: string, index: number, groups: Group[]): number => {
+  const closed = groups.pop() as Group
+  const repeated = repeatingLengthAt(pattern, index + 1) > 0
+  if (repeated && (closed.repeats || overlapsAnother(closed.branches))) return NESTED
+  groups[groups.length - 1].repeats ||= closed.repeats
+  return index + 1
+}
+
+/** Reads the token at `index` into the open groups and returns the index after it, or NESTED. */
+const stepAt = (pattern: string, index: number, groups: Group[]): number => {
+  const top = groups[groups.length - 1]
+  const char = pattern[index]
+  const literalEnd = char === '\\' ? index + 2 : classEnd(pattern, index) + 1
+  const quantifierLength = repeatingLengthAt(pattern, index)
+  if (char === '\\' || char === '[') appendTo(top, pattern.slice(index, literalEnd))
+  else if (char === '(') groups.push({ repeats: false, branches: [''] })
+  else if (char === ')' && groups.length > 1) return closeGroup(pattern, index, groups)
+  else if (char === '|') top.branches.push('')
+  else if (quantifierLength > 0) top.repeats = true
+  else appendTo(top, char)
+  if (char === '\\' || char === '[') return literalEnd
+  if (char === '(') return index + 1 + prefixLengthAt(pattern, index)
+  return index + Math.max(quantifierLength, 1)
+}
+
+/**
+ * Whether a regular expression repeats a group that repeats inside itself, the shape of catastrophic backtracking:
+ * `(a+)+`, `(\w*)*`, `(x+y)+z`, and with alternation whose branches begin alike, `(a|aa)+`. A best-effort scan of the
+ * source, not a proof: it misses overlaps it cannot see in the text (`(a|a?)+`), and it flags a few harmless ones.
+ */
+export const hasNestedQuantifier = (pattern: string): boolean => {
+  const groups: Group[] = [{ repeats: false, branches: [''] }]
+  let index = 0
+  while (index < pattern.length) {
+    index = stepAt(pattern, index, groups)
+    if (index === NESTED) return true
+  }
+  return false
+}

package/src/config/repository-directory.ts

@@ -0,0 +1,11 @@
+import { isAbsolute } from 'node:path'
+
+const segmentsOf = (path: string): string[] =>
+  path.split(/[\\/]/).filter((segment) => segment !== '' && segment !== '.')
+
+/**
+ * A directory below the repository root: relative, not the root itself and without a `..` segment. The approval gate
+ * hook applies the same rule (`kit/hooks/hooks/approval-gate/settings.ts`), which this package does not import.
+ */
+export const isRepositoryDirectory = (value: string): boolean =>
+  !isAbsolute(value) && segmentsOf(value).length > 0 && !segmentsOf(value).includes('..')

package/src/config/schema.ts

@@ -2,10 +2,13 @@ import { z } from 'zod'
 import { checkConfigSchema } from '../check/schema'
 import { claudePath, WORKTREES_DIRECTORY } from '../claude/paths'
 import { PLAN_LANGUAGE, RESPONSE_ADDRESS } from '../vocabulary'
-import { SOURCE_FIELD } from '../watch/source-fields'
+import { CONTENT_FIELDS, SOURCE_FIELD } from '../watch/source-fields'
 import { isSourcePath } from '../watch/source-path'
+import { BUN_FAILED_TEST_PATTERN, CLEAN_REVIEW_TEXT } from '../watch/watch-defaults'
 import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
+import { hasNestedQuantifier } from './nested-quantifier'
+import { isRepositoryDirectory } from './repository-directory'
 
 export const TERMINAL_ADAPTER = { none: 'none', herdr: 'herdr' } as const
 
@@ -89,7 +92,7 @@ const boardSchema = z.strictObject({
   pattern: boardPattern.default('board-*'),
   /** The board document inside each of those directories. */
   file: boardFile.default('board.md'),
-  /** What the project calls a board: the plans view, its page and the watcher print it as written. */
+  /** What the project calls a board: the herd, its page and the watcher print it as written. */
   term: z.string().min(1).default('board'),
 })
 
@@ -103,6 +106,28 @@ const deploySchema = z.strictObject({
 const feedbackSchema = z.strictObject({
   /** GitHub logins whose feedback does not wake the coordinator, such as a status bot; case is ignored. */
   ignore: z.array(z.string().min(1)).default([]),
+  /**
+   * Texts of a bot's pull request comment that report no finding: such a comment (login ending `[bot]`, no inline
+   * comment by the same author within five minutes of it) is no feedback. Compared with whitespace collapsed; the
+   * default is the CI code review's comment for a clean run. An empty list counts every bot comment.
+   */
+  noFindingTemplates: z.array(z.string().min(1)).default([CLEAN_REVIEW_TEXT]),
+})
+
+const checksSchema = z.strictObject({
+  /**
+   * Finds a failed test in a line of a red run's log (`gh run view --log-failed`) after its job, step and timestamp
+   * prefix: the first group is the name, else the match. The default is Bun's `(fail) <name> [<duration>]`. The
+   * watcher runs it on every line of a log it does not control, so a pattern that repeats a group which repeats inside
+   * itself (`(a+)+`, `(\w*)*`, and with alternation `(a|aa)+`) is refused: a best-effort scan of the source against
+   * catastrophic backtracking, not a proof.
+   */
+  failedTestPattern: z
+    .string()
+    .min(1)
+    .refine(isRegularExpression, 'not a valid regular expression')
+    .refine((pattern) => !hasNestedQuantifier(pattern), 'a quantified group that holds a quantifier backtracks badly')
+    .default(BUN_FAILED_TEST_PATTERN),
 })
 
 const previewsSchema = z.strictObject({
@@ -121,24 +146,33 @@ const sourcePath = z.string().refine(isSourcePath, 'not a source path: `.`, or `
 
 const SOURCE_FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/
 
-/** The six known fields, and any further field (`status`, `priority`, …) whose name is a plain name, for `reportOn`. */
+/** The seven known fields, and any further field (`priority`, `assignee`, …) whose name is a plain name, for `reportOn`. */
 const sourceMapSchema = z
   .object({
     [SOURCE_FIELD.id]: sourcePath,
-    /** Changes whenever the entry changes; compared as text, so any stable form of a time or version works. */
-    [SOURCE_FIELD.updatedAt]: sourcePath,
+    /**
+     * Changes whenever the entry changes; compared as text, so any stable form of a time or version works. Needed
+     * only where no content field and no `reportOn` can tell a change.
+     */
+    [SOURCE_FIELD.updatedAt]: sourcePath.optional(),
     [SOURCE_FIELD.title]: sourcePath.optional(),
     /** Shown only as an `https:` URL without user name or password. */
     [SOURCE_FIELD.url]: sourcePath.optional(),
     /** The first line with text is shown. */
     [SOURCE_FIELD.body]: sourcePath.optional(),
     [SOURCE_FIELD.author]: sourcePath.optional(),
+    /** A ticket source's status, shown on its badge in the herd; also a field `reportOn` can name. */
+    [SOURCE_FIELD.status]: sourcePath.optional(),
   })
   .catchall(sourcePath)
   .refine((map) => Object.keys(map).every((field) => SOURCE_FIELD_NAME.test(field)), {
     message: 'a map field is a letter, then letters, digits and `_`',
   })
 
+/** Whether an entry of the source can change at all: by `updatedAt`, a content field or a `reportOn` field. */
+const canChange = ({ map, reportOn }: { map: Record<string, string | undefined>; reportOn?: string[] }): boolean =>
+  map.updatedAt !== undefined || CONTENT_FIELDS.some((field) => map[field] !== undefined) || reportOn !== undefined
+
 const sourceSchema = z
   .strictObject({
     /** Printed in every report of the source and the key of its saved state. */
@@ -156,12 +190,21 @@ const sourceSchema = z
     reportLimit: z.number().int().min(1).default(5),
     /** The lane the source's reports name. */
     lane: z.string().min(1).optional(),
+    /**
+     * Marks the entries as tickets: the herd shows each as a badge beside the plan of the lane it belongs to,
+     * the lane above or the lane whose board row or plan names its id.
+     */
+    ticket: z.boolean().optional(),
     /**
      * The mapped fields whose change reports, with the old and the new value, in place of the content of `title`,
      * `author`, `body` and `url`; without it a change of that content reports.
      */
     reportOn: z.array(z.string().min(1)).min(1).max(10).optional(),
   })
+  .refine(canChange, {
+    message: 'map needs updatedAt, a content field (title, author, body, url) or reportOn',
+    path: ['map'],
+  })
   .refine((source) => source.ignoreAuthors.length === 0 || source.map.author !== undefined, {
     message: 'ignoreAuthors needs map.author',
     path: ['ignoreAuthors'],
@@ -232,6 +275,12 @@ const guardSchema = z.strictObject({
       approvalMinutes: z.number().int().min(1).max(1440).default(180),
     })
     .prefault({}),
+  approvals: z
+    .strictObject({
+      /** How long the approval gate hook holds a lane's call for the coordinator's dialog before it denies it; below the hook's 10 minutes. */
+      waitMinutes: z.number().int().min(1).max(9).default(8),
+    })
+    .prefault({}),
 })
 
 const hintsSchema = z.strictObject({
@@ -267,7 +316,11 @@ export const jackherdConfigSchema = z.strictObject({
   sprintPattern: z
     .never({ error: 'sprintPattern was replaced by board.pattern (with board.file and board.term)' })
     .optional(),
-  worktreeDirectory: z.string().min(1).default(claudePath(WORKTREES_DIRECTORY)),
+  worktreeDirectory: z
+    .string()
+    .min(1)
+    .refine(isRepositoryDirectory, 'must lie below the repository root: relative, not `.`, without `..`')
+    .default(claudePath(WORKTREES_DIRECTORY)),
   baseBranch: branchName.default(DEFAULT_BASE_BRANCH),
   /**
    * Put before every skill and agent name. `jh sync --global` refuses to run without one: a personal skill
@@ -304,7 +357,7 @@ export const jackherdConfigSchema = z.strictObject({
     .prefault({}),
   plans: z
     .strictObject({
-      /** Minutes between background fetches of the base branch while `jh plans` runs; 0 turns them off. */
+      /** Minutes between background fetches of the base branch while `jh herd` runs; 0 turns them off. */
       fetchIntervalMinutes: z.number().min(0).default(5),
       /** Links in a plan that the sprint page shows as chips; the list replaces the built-in kinds. */
       linkKinds: z
@@ -322,13 +375,15 @@ export const jackherdConfigSchema = z.strictObject({
   /**
    * Read by `jh watch`; without `deploy` it reports no deploy runs. `feedback` is on unless set to `false`:
    * it reports new feedback on the lanes' pull requests except from the account the watcher runs as and `ignore`.
+   * `checks` reads the failed tests of a red lane pull request (`failedTestPattern`), also with `feedback` off.
    * Without `previews` it reads no deploy preview; with it, one `preview` per new head commit. Each of `sources` is a
    * command whose JSON output reports `source` for a new or changed entry.
    */
   watch: z
     .strictObject({
       deploy: deploySchema.optional(),
-      feedback: z.union([z.literal(false), feedbackSchema]).default({ ignore: [] }),
+      feedback: z.union([z.literal(false), feedbackSchema]).prefault({}),
+      checks: checksSchema.prefault({}),
       previews: previewsSchema.optional(),
       sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
     })

package/src/plan-format/board-prose.ts

@@ -0,0 +1,36 @@
+import { PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { changedOpenLaneRows } from './lanes'
+
+/**
+ * The longest phases cell, in characters, that still reads as a phase and its state. Longer cells in the open
+ * lanes of the real boards carry prose, which belongs in the plan.
+ */
+export const PHASE_CELL_LIMIT = 250
+
+export const PROSE_REASON = { long: 'long', sideOrder: 'side-order' } as const
+export type ProseReason = (typeof PROSE_REASON)[keyof typeof PROSE_REASON]
+
+/** A changed row of an open lane (1-based line) whose phases cell is `length` characters and carries prose. */
+export type RowWithProse = { line: number; lane: string; reason: ProseReason; length: number }
+
+const reasonOf = (phases: string, marker: string): ProseReason | null => {
+  if (phases.includes(marker)) return PROSE_REASON.sideOrder
+  return phases.length > PHASE_CELL_LIMIT ? PROSE_REASON.long : null
+}
+
+/**
+ * The changed rows of open lanes whose phases cell is longer than `PHASE_CELL_LIMIT` or records a side order of the
+ * user in prose (`dazu (User …`): the board row names the phase, the side order is a task in the plan's phase.
+ * A cell that is both counts once, as a side order.
+ */
+export const boardRowsWithProse = (
+  markdown: string,
+  language: PlanLanguage,
+  previousLines: ReadonlySet<string>,
+): RowWithProse[] => {
+  const { sideOrderMarker } = PLAN_VOCABULARY[language]
+  return changedOpenLaneRows(markdown, language, previousLines).flatMap(({ line, lane, phases }) => {
+    const reason = reasonOf(phases, sideOrderMarker)
+    return reason === null ? [] : [{ line, lane, reason, length: phases.length }]
+  })
+}