jackherd 1.9.0 → 1.11.0

package/src/sync/kit-source.ts

@@ -9,10 +9,15 @@ import { parseKitPath } from './kit-path'
 
 export type KitLocation = { kitDirectory: string; version: string; packageRoot: string }
 
-/** What one kit module ships: its files and the text of its `hooks.json`, if any. */
-type KitModule = { name: string; files: KitFile[]; hooksText: string | undefined }
+/** What one kit module ships: its files and the texts of its `hooks.json` and `ask-rules.json`, if any. */
+type KitModule = { name: string; files: KitFile[]; hooksText: string | undefined; askRulesText: string | undefined }
 
 const MODULE_HOOKS_FILE = 'hooks.json'
+const MODULE_ASK_RULES_FILE = 'ask-rules.json'
+/** Files a module ships to sync itself, never into `.claude/`. */
+export const MODULE_DATA_FILES: readonly string[] = [MODULE_HOOKS_FILE, MODULE_ASK_RULES_FILE]
+
+const askRulesSchema = z.array(z.string().min(1))
 
 /** A test beside a kit script runs in this package and never ships into a project. */
 const TEST_FILE = /\.test\.ts$/
@@ -68,6 +73,21 @@ const mergeModuleHooks = (modules: KitModule[]): string | undefined => {
   return Object.keys(merged).length > 0 ? JSON.stringify(merged, null, 2) : undefined
 }
 
+/** The `permissions.ask` rules of every module's `ask-rules.json` (a JSON list of rules), each once, in module order. */
+const mergeModuleAskRules = (modules: KitModule[]): string[] => {
+  const rules = modules.flatMap(({ name, askRulesText }) => {
+    if (askRulesText === undefined) return []
+    const invalid = new Error(`Kit ${name}/${MODULE_ASK_RULES_FILE} is not a JSON list of permission rules`)
+    const parsed = askRulesSchema.safeParse(parseJsonOr(askRulesText, invalid))
+    if (!parsed.success) throw invalid
+    return parsed.data
+  })
+  return [...new Set(rules)]
+}
+
+const readOptional = async (moduleDirectory: string, relatives: string[], file: string): Promise<string | undefined> =>
+  relatives.includes(file) ? readFile(join(moduleDirectory, file), 'utf8') : undefined
+
 const listFiles = async (directory: string, prefix = ''): Promise<string[]> => {
   const entries = await readdir(join(directory, prefix), { withFileTypes: true })
   const nested = await Promise.all(
@@ -94,12 +114,11 @@ const readKitFile = async (moduleDirectory: string, relative: string): Promise<K
 const readModule = async (kitDirectory: string, name: string): Promise<KitModule> => {
   const moduleDirectory = join(kitDirectory, name)
   const relatives = (await listFiles(moduleDirectory)).sort()
-  const filePaths = relatives.filter((relative) => relative !== MODULE_HOOKS_FILE && !TEST_FILE.test(relative))
+  const filePaths = relatives.filter((relative) => !MODULE_DATA_FILES.includes(relative) && !TEST_FILE.test(relative))
   const files = await Promise.all(filePaths.map((relative) => readKitFile(moduleDirectory, relative)))
-  const hooksText = relatives.includes(MODULE_HOOKS_FILE)
-    ? await readFile(join(moduleDirectory, MODULE_HOOKS_FILE), 'utf8')
-    : undefined
-  return { name, files, hooksText }
+  const hooksText = await readOptional(moduleDirectory, relatives, MODULE_HOOKS_FILE)
+  const askRulesText = await readOptional(moduleDirectory, relatives, MODULE_ASK_RULES_FILE)
+  return { name, files, hooksText, askRulesText }
 }
 
 const listModuleNames = async (kitDirectory: string): Promise<string[]> => {
@@ -119,8 +138,8 @@ const listModuleNames = async (kitDirectory: string): Promise<string[]> => {
 /**
  * Reads the kit shipped with the package. Every directory under `kit/` is a module that mirrors
  * `.claude/` (`kit/workflow/skills/plan/SKILL.md` → `.claude/skills/plan/SKILL.md`); a module's
- * `hooks.json` holds its hooks by name, `{ "<name>": { event, matcher?, handler } }`, and is not
- * copied, nor is a `*.test.ts`. Files at the kit root, such as a README, belong to no module.
+ * `hooks.json` holds its hooks by name, `{ "<name>": { event, matcher?, handler } }`, and its
+ * `ask-rules.json` the `permissions.ask` rules a project install adds; neither is copied, nor is a `*.test.ts`. Files at the kit root, such as a README, belong to no module.
  *
  * A missing kit directory, or one without modules, is an error, never an empty kit: an empty kit
  * would make sync remove every untouched kit file from the project.
@@ -134,7 +153,7 @@ export const readKitSource = async ({
   const modules = await Promise.all(names.map((name) => readModule(kitDirectory, name)))
   assertUniquePaths(modules)
   const files = modules.flatMap((module) => module.files).sort((left, right) => (left.path < right.path ? -1 : 1))
-  return { version, files, hooksTemplate: mergeModuleHooks(modules) }
+  return { version, files, hooksTemplate: mergeModuleHooks(modules), askRules: mergeModuleAskRules(modules) }
 }
 
 const readPackageJson = async (path: string) => packageJsonSchema.parse(JSON.parse(await readFile(path, 'utf8')))

package/src/sync/kit.ts

@@ -6,4 +6,6 @@ export type KitSource = {
   files: KitFile[]
   /** The unrendered text of `kit/hooks.json`, if the kit ships hooks. */
   hooksTemplate: string | undefined
+  /** The `permissions.ask` rules of the kit's `ask-rules.json` files; none for a global install. */
+  askRules?: readonly string[]
 }

package/src/sync/manifest.ts

@@ -21,6 +21,8 @@ const manifestSchema = z.strictObject({
     z.string().regex(HOOK_NAME),
     z.strictObject({ base: hookDefinitionSchema, pending: sha256.optional() }),
   ),
+  /** The `permissions.ask` rules sync put into `settings.json`, which it removes once the kit drops them. */
+  askRules: z.array(z.string().min(1)).optional(),
   /** Checksum of the `settings.json.kit-new` sync wrote last. */
   settingsKitNew: sha256.optional(),
 })

package/src/sync/plan-ask-rules.ts

@@ -0,0 +1,94 @@
+import { HOOK_OUTCOME, type HookOutcome } from './plan-hooks'
+import type { Settings } from './settings-hooks'
+
+export type AskRulesInput = {
+  /** The `permissions.ask` rules the kit ships. */
+  kit: readonly string[]
+  /** The rules sync put into the settings before, from the lock. */
+  recorded: readonly string[]
+  settings: Settings
+  /** `--accept .claude/settings.json`: put back a kit rule the user removed. */
+  accept: boolean
+}
+
+export type AskRulesPlan = {
+  settings: Settings
+  changed: boolean
+  /** What the lock records next: every kit rule, a removed one included, so it is not added again. */
+  recorded: string[]
+  outcomes: { name: string; outcome: HookOutcome }[]
+  accepted: boolean
+}
+
+/**
+ * Every rule a jackherd kit has ever shipped in an `ask-rules.json`. Only these are ever removed: a lock is a file in
+ * the project, and a rule it lists that no kit shipped (a tampered lock) stays where it is. Add, never remove.
+ */
+export const SHIPPED_ASK_RULES: readonly string[] = [
+  'Bash(gh run rerun *)',
+  'Bash(gh api *pulls/*/merge*)',
+  'Bash(gh api *merges*)',
+  'Bash(gh api *contents/*)',
+  'Bash(gh api *dispatches*)',
+  'Bash(gh api *rerun*)',
+  'Bash(gh api *git/refs*)',
+  'Bash(jh lane close*)',
+  'Bash(jackherd lane close*)',
+  'Bash(bunx jackherd* lane close*)',
+  'Bash(bun */cli.ts lane close*)',
+  'Bash(bunx jh lane close*)',
+  'Bash(bun x jackherd* lane close*)',
+]
+
+/** How a rule shows in the sync report, beside the hooks. */
+export const askRuleName = (rule: string): string => `permissions.ask ${rule}`
+
+const askOf = (settings: Settings): string[] => {
+  const permissions = settings.permissions
+  const ask =
+    typeof permissions === 'object' && permissions !== null ? (permissions as { ask?: unknown }).ask : undefined
+  return Array.isArray(ask) ? ask.filter((rule): rule is string => typeof rule === 'string') : []
+}
+
+/** The settings with this ask list; an emptied list, and permissions it empties, disappear. Returns a copy. */
+const withAsk = (settings: Settings, ask: string[]): Settings => {
+  const { permissions: _old, ...rest } = settings
+  const { ask: _list, ...otherPermissions } = (settings.permissions ?? {}) as Record<string, unknown>
+  const permissions = ask.length > 0 ? { ...otherPermissions, ask } : otherPermissions
+  return Object.keys(permissions).length > 0 ? { ...rest, permissions } : rest
+}
+
+const outcomeOf = (rule: string, input: AskRulesInput, present: ReadonlySet<string>): HookOutcome => {
+  const shipped = input.kit.includes(rule)
+  if (!shipped)
+    return present.has(rule) && SHIPPED_ASK_RULES.includes(rule) ? HOOK_OUTCOME.removed : HOOK_OUTCOME.dropped
+  if (present.has(rule)) return HOOK_OUTCOME.unchanged
+  if (!input.recorded.includes(rule)) return HOOK_OUTCOME.created
+  return input.accept ? HOOK_OUTCOME.accepted : HOOK_OUTCOME.deselected
+}
+
+const ADDING: readonly HookOutcome[] = [HOOK_OUTCOME.created, HOOK_OUTCOME.accepted]
+
+/**
+ * Merges the kit's ask rules into `permissions.ask`, the way `planHooks` merges hooks. Pure. Only a rule the lock
+ * records and some kit shipped (`SHIPPED_ASK_RULES`) is ever removed, and only once the kit stops shipping it; every other entry stays where it is. A kit rule
+ * the user removed is not put back unless `accept` is set.
+ */
+export const planAskRules = (input: AskRulesInput): AskRulesPlan => {
+  const before = askOf(input.settings)
+  const present = new Set(before)
+  const rules = [...new Set([...input.kit, ...input.recorded])]
+  const decided = rules.map((rule) => ({ rule, outcome: outcomeOf(rule, input, present) }))
+  const removed = new Set(decided.filter(({ outcome }) => outcome === HOOK_OUTCOME.removed).map(({ rule }) => rule))
+  const added = decided.filter(({ outcome }) => ADDING.includes(outcome)).map(({ rule }) => rule)
+  const changed = removed.size > 0 || added.length > 0
+  return {
+    settings: changed
+      ? withAsk(input.settings, [...before.filter((rule) => !removed.has(rule)), ...added])
+      : input.settings,
+    changed,
+    recorded: [...input.kit],
+    outcomes: decided.map(({ rule, outcome }) => ({ name: askRuleName(rule), outcome })),
+    accepted: decided.some(({ outcome }) => outcome === HOOK_OUTCOME.accepted),
+  }
+}

package/src/sync/plan-hooks.ts

@@ -47,6 +47,8 @@ export type HooksPlan = {
   kitNewRecorded: string | undefined
   /** `--accept` was given for the settings but no hook was in conflict or deselected. */
   notAcceptable: boolean
+  /** The kit's `permissions.ask` rules the lock records next (`planAskRules`); none outside a project install. */
+  askRules?: string[]
 }
 
 type HookDecision = {

package/src/sync/render.ts

@@ -4,9 +4,9 @@ import {
   ADDRESS_FORM,
   APPROVAL_TEXTS,
   LANGUAGE_NAME,
-  PLAN_APPROVAL_LABELS,
   PLAN_VOCABULARY,
   SELF_MERGE_LABEL,
+  STANDING_APPROVAL_TEXTS,
 } from '../vocabulary'
 
 const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
@@ -47,7 +47,7 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ...prefixed('board', config.board),
     ['kit.guard.selfMergeLabel', SELF_MERGE_LABEL[config.responseLanguage]],
     ['kit.guard.selfMerge', config.guard.selfMerge.offer ? 'offered' : 'not offered'],
-    ...prefixed('guard.planApproval', PLAN_APPROVAL_LABELS[config.responseLanguage]),
+    ...prefixed('guard.standingApproval', STANDING_APPROVAL_TEXTS[config.responseLanguage]),
     ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
@@ -61,7 +61,7 @@ export const listPlaceholders = (template: string): string[] =>
 /**
  * Fills the kit placeholders from the project config: `{{kit.model.<role>}}`,
  * `{{kit.command.<test|typecheck|lint|format|install|dev>}}`, `{{kit.lanes.<copyCommand|lockFile|verifyInstall>}}`, `{{kit.word.<laneClosed|openSubagents>}}`,
- * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.planApproval.<approve|revoke>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
+ * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
  * vocabulary, the two languages, `{{kit.responseAddress}}`, the plan and worktree directory and the base branch. Other
  * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project
  * file unrendered. `overrides` win over the config: a global kit renders what each repository decides as

package/src/sync/settings-hooks.ts

@@ -25,7 +25,10 @@ const hookGroupSchema = z.looseObject({
   hooks: z.array(z.record(z.string(), z.unknown())),
 })
 
-const settingsSchema = z.looseObject({ hooks: z.record(z.string(), z.array(hookGroupSchema)).optional() })
+const settingsSchema = z.looseObject({
+  hooks: z.record(z.string(), z.array(hookGroupSchema)).optional(),
+  permissions: z.looseObject({ ask: z.array(z.string()).optional() }).optional(),
+})
 
 export const parseSettings = (raw: unknown): SettingsResult => {
   const parsed = settingsSchema.safeParse(raw)

package/src/sync/sync-plan.ts

@@ -115,6 +115,7 @@ export const nextManifest = (kitVersion: string, files: FilePlan[], hooks: Hooks
     kitVersion,
     files: Object.fromEntries(files.flatMap(({ path, entry }) => (entry ? [[path, entry]] : []))),
     hooks: hooks.entries,
+    ...(hooks.askRules !== undefined && hooks.askRules.length > 0 ? { askRules: hooks.askRules } : {}),
   }
   return hooks.kitNewRecorded === undefined ? manifest : { ...manifest, settingsKitNew: hooks.kitNewRecorded }
 }

package/src/sync/sync.ts

@@ -15,6 +15,7 @@ import type { KitSource } from './kit'
 import { kitNewPath, toolRootPath } from './kit-path'
 import { moveGlobalLegacyFiles, moveProjectLegacyFiles, removeEmptyLegacyDirectories } from './legacy-files'
 import { EMPTY_MANIFEST, type Manifest, parseManifest, serializeManifest } from './manifest'
+import { planAskRules } from './plan-ask-rules'
 import { FILE_MODE, FILE_OUTCOME, type FileEffect, type FilePlan, planFile, type RenderedFile } from './plan-file'
 import { type HooksPlan, planHooks } from './plan-hooks'
 import {
@@ -191,11 +192,29 @@ const buildPlan = async ({
   return { files, hooks, manifest: nextManifest(kit.version, files, hooks), manifestText }
 }
 
-/** Merges the kit's hooks into the project's `settings.json`. */
+/** The hooks plan with the kit's ask rules merged into the settings it writes, and their outcomes beside the hooks'. */
+const withAskRules = (hooks: HooksPlan, kit: KitSource, manifest: Manifest, accept: AcceptRequest): HooksPlan => {
+  const rules = planAskRules({
+    kit: kit.askRules ?? [],
+    recorded: manifest.askRules ?? [],
+    settings: hooks.settings,
+    accept: accept.settings,
+  })
+  return {
+    ...hooks,
+    settings: rules.settings,
+    changed: hooks.changed || rules.changed,
+    outcomes: [...hooks.outcomes, ...rules.outcomes],
+    notAcceptable: hooks.notAcceptable && !rules.accepted,
+    askRules: rules.recorded,
+  }
+}
+
+/** Merges the kit's hooks and ask rules into the project's `settings.json`. */
 const projectHooks =
   (claudeDirectory: string, kit: KitSource, config: JackherdConfig) =>
-  async (manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> =>
-    planHooks({
+  async (manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> => {
+    const hooks = planHooks({
       kit: renderKitHooks(kit, (template) => renderTemplate(template, config)),
       entries: manifest.hooks,
       settings: await readSettings(claudeDirectory),
@@ -203,6 +222,8 @@ const projectHooks =
       kitNewRecorded: manifest.settingsKitNew,
       accept: accept.settings,
     })
+    return withAskRules(hooks, kit, manifest, accept)
+  }
 
 /** A global install ships no hooks and never reads the user's `settings.json`. */
 const noHooks = async (_manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> =>

package/src/task-signals/claude-read.ts

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { readTailLines } from '../context/session-log'
 import { isRecord } from '../shared/is-record'
+import { readCached, type StatRound } from '../shared/stat-cache'
 import { claudeSignalsOf } from './claude-signals'
 import { cleanAgentName } from './text'
 import type { TaskSignal } from './types'
@@ -11,7 +12,12 @@ const SUBAGENT_LOG = /^(agent-[A-Za-z0-9]+)\.jsonl$/
 /** How much of the end of a log is read by default: sessions grow to hundreds of megabytes. */
 const SIGNAL_TAIL_BYTES = 8 * 1024 * 1024
 
+/** The signals of each log by path, kept while its modification time and size stay; `used` collects the paths of one round. */
+export type SignalCache = StatRound<TaskSignal[]>
+
 export type ReadOptions = {
+  /** Kept between reads, so a log that did not change is not parsed again. */
+  cache?: SignalCache
   /** How many bytes from the end of each log are read; a task created before that is unknown, so it gives no signal. */
   tailBytes?: number
   /** Subagent logs last written before this (epoch milliseconds) are left out. */
@@ -46,27 +52,38 @@ const isRecent = (path: string, notOlderThan: number): boolean => {
   }
 }
 
-const subagentSignals = (directory: string, tailBytes: number, notOlderThan: number): TaskSignal[] => {
+const named = (signals: TaskSignal[], agent: string): TaskSignal[] => signals.map((signal) => ({ ...signal, agent }))
+
+const subagentSignals = (
+  directory: string,
+  signalsOf: (path: string) => TaskSignal[],
+  notOlderThan: number,
+): TaskSignal[] => {
   try {
     return readdirSync(directory)
       .sort()
       .flatMap((name) => {
         const stem = SUBAGENT_LOG.exec(name)?.[1]
         const path = join(directory, name)
-        return stem && isRecent(path, notOlderThan)
-          ? claudeSignalsOf(linesOf(path, tailBytes), agentNameOf(directory, stem))
-          : []
+        return stem && isRecent(path, notOlderThan) ? named(signalsOf(path), agentNameOf(directory, stem)) : []
       })
   } catch {
     return []
   }
 }
 
-/** The tasks in progress in a Claude Code session log and in every `<session>/subagents/agent-*.jsonl` beside it. */
+/**
+ * The tasks in progress in a Claude Code session log and in every `<session>/subagents/agent-*.jsonl` beside it.
+ * With a `cache`, a log whose modification time and size are as at the last read is not read and parsed again.
+ */
 export const readClaudeSignals = (
   sessionLogPath: string,
-  { tailBytes = SIGNAL_TAIL_BYTES, notOlderThan = 0 }: ReadOptions = {},
-): TaskSignal[] => [
-  ...claudeSignalsOf(linesOf(sessionLogPath, tailBytes), 'session'),
-  ...subagentSignals(join(sessionLogPath.replace(/\.jsonl$/, ''), 'subagents'), tailBytes, notOlderThan),
-]
+  { tailBytes = SIGNAL_TAIL_BYTES, notOlderThan = 0, cache }: ReadOptions = {},
+): TaskSignal[] => {
+  const parsed = (path: string): TaskSignal[] => claudeSignalsOf(linesOf(path, tailBytes), '')
+  const signalsOf = cache ? (path: string) => readCached(cache, path, parsed, `${path}\0${tailBytes}`) : parsed
+  return [
+    ...named(signalsOf(sessionLogPath), 'session'),
+    ...subagentSignals(join(sessionLogPath.replace(/\.jsonl$/, ''), 'subagents'), signalsOf, notOlderThan),
+  ]
+}

package/src/terminal/text.ts

@@ -47,6 +47,7 @@ export const paint = {
   red: style('31'),
   green: style('32'),
   yellow: style('33'),
+  blue: style('34'),
   magenta: style('35'),
   teal: style(tealCodeOf(process.env)),
   cyan: style('36'),
@@ -75,12 +76,24 @@ export const link = (url: string, text: string): string =>
 export const badge = (url: string, text: string, hint = '', tone: BadgeTone = BADGE_TONE.grey): string =>
   `${ESC}[${tone}m ${link(url, text)}${hint ? `${FAINT_ON} ${hint}${FAINT_OFF}` : ''} ${RESET}`
 
+/**
+ * `text` as a button in square brackets, like `[ask]`: the text linked to `url` in the normal brightness, with `hint`
+ * after it inside the brackets, faint. A square bracket means a click does something.
+ */
+export const bracket = (url: string, text: string, hint = ''): string =>
+  `[${link(url, text)}${hint ? `${FAINT_ON} ${hint}${FAINT_OFF}` : ''}]`
+
 /** `text` as a badge without a link, for what no click opens: the background of `tone`, a cell of padding either side. */
 export const box = (text: string, tone: BadgeTone = BADGE_TONE.grey): string => `${ESC}[${tone}m ${text} ${RESET}`
 
-/** A line for output that is not a terminal: styling dropped, each link written out as `text (url)`. */
-export const plainText = (text: string): string =>
-  stripAnsi(text.replace(LINK, (_, url, inner) => `${stripAnsi(inner)} (${url})`))
+/**
+ * A line for output that is not a terminal: styling dropped, each link written out as `text (url)`, except the
+ * ones `writesAddress` refuses, which keep the bare text.
+ */
+export const plainText = (text: string, writesAddress: (url: string) => boolean = () => true): string =>
+  stripAnsi(
+    text.replace(LINK, (_, url, inner) => (writesAddress(url) ? `${stripAnsi(inner)} (${url})` : stripAnsi(inner))),
+  )
 
 /** The terminal cells a styled line takes: emoji count two. */
 export const visibleLength = (text: string): number => textWidth(stripAnsi(text))

package/src/terminal/types.ts

@@ -6,6 +6,10 @@ export type AgentStatus = (typeof AGENT_STATUS)[keyof typeof AGENT_STATUS]
 export const isAgentStatus = (value: string): value is AgentStatus =>
   (Object.values(AGENT_STATUS) as string[]).includes(value)
 
+/** The states of an agent that rests: it has finished or waits for the next task, and is not working or asking. */
+export const isRestingAgent = (agent: string | null): boolean =>
+  agent === AGENT_STATUS.idle || agent === AGENT_STATUS.done
+
 /** A name to list the unnamed agent of one pane under. */
 export type AdoptedName = { pane: string; name: string }
 

package/src/version/skill-diff.ts

@@ -6,6 +6,19 @@ export type SkillChange =
   | { kind: typeof SKILL_CHANGE.unchanged }
   | { kind: typeof SKILL_CHANGE.unavailable; reason: string }
 
+/** How a reference file of the orchestrate skill differs between the kit at the start and the kit now. */
+export const REFERENCE_CHANGE = { changed: 'changed', added: 'added', deleted: 'deleted' } as const
+
+type ReferenceChangeKind = (typeof REFERENCE_CHANGE)[keyof typeof REFERENCE_CHANGE]
+
+/** A reference that differs, before the diff is written or the path known. */
+export type ReferenceDelta = { name: string; kind: ReferenceChangeKind }
+
+export type ReferenceChange =
+  | { name: string; kind: typeof REFERENCE_CHANGE.changed; diffPath: string | null }
+  | { name: string; kind: typeof REFERENCE_CHANGE.added; path: string }
+  | { name: string; kind: typeof REFERENCE_CHANGE.deleted }
+
 const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/
 const SECTION_HEADING = /^## (.+)$/
 const NUMBERED_SECTION = /^(\d+)\.\s/
@@ -61,3 +74,36 @@ export const skillChangeLine = (change: SkillChange): string => {
   if (change.kind === SKILL_CHANGE.unchanged) return 'orchestrate skill unchanged'
   return `orchestrate skill diff unavailable (${change.reason}): read the skill again`
 }
+
+const deltaOf = (name: string, before: string | undefined, after: string | undefined): ReferenceDelta[] => {
+  if (before === after) return []
+  if (before === undefined) return [{ name, kind: REFERENCE_CHANGE.added }]
+  return [{ name, kind: after === undefined ? REFERENCE_CHANGE.deleted : REFERENCE_CHANGE.changed }]
+}
+
+/** The references (file name → text) that changed, are new or are gone, by name; unchanged ones are left out. */
+export const referenceChanges = (
+  before: Readonly<Record<string, string>>,
+  after: Readonly<Record<string, string>>,
+): ReferenceDelta[] =>
+  [...new Set([...Object.keys(before), ...Object.keys(after)])]
+    .sort()
+    .flatMap((name) => deltaOf(name, before[name], after[name]))
+
+export const referenceChangeLine = (change: ReferenceChange): string => {
+  const head = `orchestrate reference ${change.name}`
+  if (change.kind === REFERENCE_CHANGE.deleted) return `${head} deleted`
+  if (change.kind === REFERENCE_CHANGE.added) return `${head} new · read ${change.path}`
+  return change.diffPath === null
+    ? `${head} changed · diff unavailable: read it again`
+    : `${head} changed · diff ${change.diffPath}`
+}
+
+/**
+ * The lines about the orchestrate skill after a kit update: the skill's own, then one per reference that changed. An
+ * unchanged skill is named only when no reference changed either, so a quiet update stays one line.
+ */
+export const orchestrateChangeLines = (skill: SkillChange, references: readonly ReferenceChange[]): string[] => {
+  if (skill.kind === SKILL_CHANGE.unchanged && references.length > 0) return references.map(referenceChangeLine)
+  return [skillChangeLine(skill), ...references.map(referenceChangeLine)]
+}

package/src/vocabulary/index.ts

@@ -39,13 +39,23 @@ export const SELF_MERGE_LABEL: Record<PlanLanguage, string> = {
 }
 
 /**
- * The options of the question that approves a plan for all its lanes (``Plan `<path>` ``) and of the one that revokes
- * that approval. The merge guard hook lifts its question for a plain merge of such a lane only when the newest answer
- * to a question naming the plan is exactly `approve`, so the labels are fixed per language and not a config value.
+ * The standing approval: the option that approves (`approve`) and the word between the plan and the end in its
+ * question (``Plan `<path>` <until> <YYYY-MM-DD HH:MM>``). The merge guard hook lifts its question for a plain merge of
+ * that plan's lanes only when the newest answer to such a question is exactly `approve`, so both are fixed per
+ * language and not a config value.
  */
-export const PLAN_APPROVAL_LABELS: Record<PlanLanguage, { approve: string; revoke: string }> = {
-  [PLAN_LANGUAGE.en]: { approve: 'Approve the plan', revoke: 'Revoke the plan approval' },
-  [PLAN_LANGUAGE.de]: { approve: 'Plan freigeben', revoke: 'Plan-Freigabe widerrufen' },
+export const STANDING_APPROVAL_TEXTS: Record<PlanLanguage, { approve: string; until: string }> = {
+  [PLAN_LANGUAGE.en]: { approve: 'Approve standing', until: 'until' },
+  [PLAN_LANGUAGE.de]: { approve: 'Stehend freigeben', until: 'bis' },
+}
+
+/**
+ * The words a lane prompt opens with, followed by the lane's name. The ask hint hook and the project's lane exception
+ * recognise a lane by them, so they are fixed per language and not a config value.
+ */
+export const LANE_PROMPT_OPENING: Record<PlanLanguage, string> = {
+  [PLAN_LANGUAGE.en]: 'You are the lane',
+  [PLAN_LANGUAGE.de]: 'Du bist die Spur',
 }
 
 /** What the approval gate hook tells the lane when it denies: jackherd's own words, English in every language. */
@@ -77,6 +87,8 @@ export const APPOINTMENT_VOCABULARY: Record<
     /** Further header names that count as the status column. */
     statusAlso: readonly string[]
     open: readonly string[]
+    /** The lower-case word an action starts with when it is the weekly board grooming, which the herd's header counts from. */
+    grooming: string
   }
 > = {
   [PLAN_LANGUAGE.de]: {
@@ -84,15 +96,23 @@ export const APPOINTMENT_VOCABULARY: Record<
     columns: { when: 'Wann', action: 'Aktion', origin: 'Herkunft', status: 'Stand' },
     statusAlso: ['Status'],
     open: ['offen'],
+    grooming: 'board-pflege',
   },
   [PLAN_LANGUAGE.en]: {
     heading: 'Appointments',
     columns: { when: 'When', action: 'Action', origin: 'Origin', status: 'Status' },
     statusAlso: [],
     open: ['open'],
+    grooming: 'board grooming',
   },
 }
 
+/** The heading of the board section of what the coordinator does next, a numbered list of at most three lines. */
+export const NEXT_VOCABULARY: Record<PlanLanguage, { heading: string }> = {
+  [PLAN_LANGUAGE.de]: { heading: 'Als Nächstes' },
+  [PLAN_LANGUAGE.en]: { heading: 'Next' },
+}
+
 /**
  * The board section of what waits on the user's answer (a sent preview, an open question, a report to accept): its
  * heading, the header names of its columns (since, item, origin, status, found by name in any order; the status

package/src/waiting/command.ts

@@ -1,8 +1,9 @@
 import { terminalSafe } from '../plan-format/terminal-text'
 import type { WaitingItem } from '../plan-format/waiting'
 import { mainCheckout } from '../plans/git'
-import { sentWaitingItems } from '../plans/sent-files'
-import { closeAllSentRecords, closeSentRecords, readSentRecords } from '../plans/sent-files-read'
+import { closeAllQuestionRecords, closeQuestionRecords } from '../plans/questions-read'
+import { closeAllSentRecords, closeSentRecords } from '../plans/sent-files-read'
+import { recordWaitingItems } from '../plans/waiting-records'
 import { CLI_NAME } from '../version/release'
 
 const USAGE = `usage: ${CLI_NAME} waiting [close <id> ... | close --all]`
@@ -13,14 +14,25 @@ export const waitingListing = (items: readonly WaitingItem[]): string[] =>
     ? ['nothing waits on you']
     : items.map(({ since, item, id }) => terminalSafe(`${id} · ${since} · ${item}`))
 
+const CLOSE_ALL = '--all'
+
+/** Closes the records the ids name, files and questions alike; how many it closed. */
+export const closeWaiting = (root: string, ids: readonly string[], now: number): number =>
+  closeSentRecords(root, ids, now) + closeQuestionRecords(root, ids, now)
+
+/** Closes every open record, files and questions alike; how many it closed. */
+export const closeAllWaiting = (root: string, now: number): number =>
+  closeAllSentRecords(root, now) + closeAllQuestionRecords(root, now)
+
 /**
- * `jh waiting` lists the files sent to the user that no one closed (their id, time and caption);
- * `jh waiting close <id> ...` or `close --all` closes them once the user has answered. Exit 0, 1 on a wrong command line.
+ * `jh waiting` lists the files sent to the user and the questions left unanswered that no one closed (their id, time
+ * and text); `jh waiting close <id> ...` or `close --all` closes them once the user has answered. Exit 0, 1 on a wrong
+ * command line.
  */
 export const run = async (args: string[]): Promise<number> => {
   const root = mainCheckout(process.cwd())
   if (args.length === 0) {
-    for (const line of waitingListing(sentWaitingItems(readSentRecords(root), Date.now()))) console.log(line)
+    for (const line of waitingListing(recordWaitingItems(root, Date.now()))) console.log(line)
     return 0
   }
   const [command, ...rest] = args
@@ -28,8 +40,11 @@ export const run = async (args: string[]): Promise<number> => {
     console.error(USAGE)
     return 1
   }
-  const now = Date.now()
-  const closed = rest.includes('--all') ? closeAllSentRecords(root, now) : closeSentRecords(root, rest, now)
+  if (rest.includes(CLOSE_ALL) && rest.length > 1) {
+    console.error(`${CLOSE_ALL} closes everything and takes no ids\n${USAGE}`)
+    return 1
+  }
+  const closed = rest[0] === CLOSE_ALL ? closeAllWaiting(root, Date.now()) : closeWaiting(root, rest, Date.now())
   console.log(`closed ${closed}`)
   return 0
 }

package/src/watch/appointments.ts

@@ -1,4 +1,4 @@
-import { twoDigits } from '../plan-format/clock'
+import { DAY_MS, twoDigits } from '../plan-format/clock'
 import { firstTableWithHeader, sectionLines } from '../plan-format/markdown'
 import { isRecord } from '../shared/is-record'
 import { APPOINTMENT_VOCABULARY, type PlanLanguage } from '../vocabulary'
@@ -31,7 +31,6 @@ type DateParts = { year: number | null; month: number; day: number; hours: numbe
 const DAY_FIRST = /^(?:\p{L}{2,3}\.?,?\s+)?(\d{1,2})\.(\d{1,2})\.(\d{4})?\s+(\d{1,2}):(\d{2})$/u
 const ISO = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{1,2}):(\d{2})$/
 const KEY_TIME_LENGTH = 'YYYY-MM-DDThh:mm'.length
-const DAY_MS = 86_400_000
 const KEEP_GONE_MS = 7 * DAY_MS
 
 const APPOINTMENT_KINDS: readonly string[] = Object.values(APPOINTMENT_EVENT)