jackherd 1.16.0 → 1.18.0

package/kit/hooks/hooks/merge-guard/pane-process-info.ts

@@ -0,0 +1,38 @@
+/** The adapter that asks herdr what runs in a pane; `pane-input.ts` reads its answer. */
+import { paneAgentOf } from '../shared/pane-agent'
+import { foregroundOf } from './pane-input'
+
+const PROCESS_INFO_TIMEOUT_MS = 2000
+
+/**
+ * The directory the agent `target` runs in, which herdr reads from the process itself (`shared/own-pane.ts`); undefined
+ * when herdr does not answer in time, knows no such agent or answers otherwise.
+ */
+export const herdrAgentDirectory = (target: string, directory: string): string | undefined => {
+  try {
+    const result = Bun.spawnSync(['herdr', 'agent', 'get', target], {
+      cwd: directory,
+      timeout: PROCESS_INFO_TIMEOUT_MS,
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    return result.exitCode === 0 ? (paneAgentOf(JSON.parse(result.stdout.toString()))?.cwd ?? undefined) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** The foreground of `pane` as herdr names it now; undefined when herdr does not answer in time or answers otherwise. */
+export const herdrForeground = (pane: string, directory: string): string[][] | undefined => {
+  try {
+    const result = Bun.spawnSync(['herdr', 'pane', 'process-info', '--pane', pane], {
+      cwd: directory,
+      timeout: PROCESS_INFO_TIMEOUT_MS,
+      stdout: 'pipe',
+      stderr: 'ignore',
+    })
+    return result.exitCode === 0 ? foregroundOf(result.stdout.toString()) : undefined
+  } catch {
+    return undefined
+  }
+}

package/kit/hooks/hooks/merge-guard/run.ts

@@ -1,15 +1,20 @@
 import { readFileSync } from 'node:fs'
+import { isAbsolute } from 'node:path'
 import { mainCheckoutOf } from '../shared/checkout'
+import { commandOutput } from '../shared/command'
 import { dialogAnswers, parseTranscript } from '../shared/dialog-answers'
 import { isWithinDirectory } from '../shared/files'
 import { once } from '../shared/once'
 import { readShellDefinitions } from '../shared/shell-snapshots'
-import { ALWAYS_ASK_PATHS } from './always-ask'
-import { approvedBranches } from './approval'
+import { ALWAYS_ASK_PATHS, alwaysAskingFiles, STANDING_ALWAYS_ASK } from './always-ask'
+import { type ApprovedChange, approvedChanges } from './approval'
 import { boardSettingsOf } from './board-settings'
+import { changeIdOf, isSameChange } from './change-id'
 import { changedFilesOf, isCheckFree } from './check-free'
 import { decideBashCommand, type GuardPolicy, type MergeGuardDecision, type MergeNote, type PlainMerge } from './decision'
 import { planOfBranch } from './lane-plan'
+import { cannotBeHerd } from './pane-input'
+import { herdrAgentDirectory, herdrForeground } from './pane-process-info'
 import {
   checksPassed,
   parseBaseBranch,
@@ -26,7 +31,7 @@ type HookInput = { tool_input?: { command?: unknown }; transcript_path?: unknown
 /** The exact option labels that approve a merge: the one of the pull request question and those of the standing approval. */
 export type ApprovalLabels = { selfMerge: string; standing: StandingLabels }
 
-/** What GitHub says about the pull request a merge names; `files` is asked only when a rule needs it. */
+/** What GitHub says about the pull request a merge names; `files` and `change` are asked only when a rule needs them. */
 type MergeFacts = {
   branch: string
   baseBranch: string | undefined
@@ -34,13 +39,15 @@ type MergeFacts = {
   /** The `gh pr view` answer, which carries the checks and whether GitHub can merge. */
   view: string
   files: () => readonly string[] | undefined
+  /** The patch id of the pull request's diff at the head commit. */
+  change: () => string | undefined
 }
 
 type StandingApproval = (facts: MergeFacts) => boolean | MergeNote
 
 /** The ways a merge may pass without a question. */
 type MergeApprovals = {
-  branches: ReadonlySet<string>
+  changes: readonly ApprovedChange[]
   /** The checks a self-merge of an approved branch waits for a successful run of. */
   requiredChecks: readonly string[] | undefined
   withoutChecks: readonly string[]
@@ -51,47 +58,101 @@ type MergeApprovals = {
 
 const PASS: MergeGuardDecision = { kind: 'pass' }
 
-/** The transcript of the session that merges, one parsed entry per line; none without one. */
-const transcriptEntries = (transcriptPath: unknown): unknown[] =>
-  typeof transcriptPath === 'string' ? parseTranscript(readFileSync(transcriptPath, 'utf8')) : []
+const approvedChangesFrom = (entries: unknown[], settings: GuardSettings, label: string): ApprovedChange[] => {
+  if (!settings.selfMerge.offer) return []
+  return approvedChanges({ entries, label, now: Date.now(), windowMinutes: settings.selfMerge.approvalMinutes })
+}
+
+const changedSinceApproval = (branch: string, change: string): MergeNote => ({
+  note: `The user approved branch \`${branch}\` with change @${change}; the change id of the pull request differs (a push after the approval, or GitHub's diff reads otherwise), so the user confirms the merge.`,
+})
+
+const unboundMerge: MergeNote = {
+  note: 'The user approved this branch, but the merge names no head commit: bind the merge with `--match-head-commit <headRefOid>` (from `gh pr view`), so a push after the check is not merged unchecked.',
+}
+
+/** The note for a merge of an approved branch that names no head commit; false for any other head that differs. */
+const unboundMergeOf = (
+  merge: PlainMerge,
+  changes: readonly ApprovedChange[],
+  branch: string,
+): MergeNote | false =>
+  merge.headCommit === undefined && changes.some((change) => change.branch === branch) ? unboundMerge : false
+
+const carriesGuardFiles = (files: readonly string[] | undefined): MergeNote => ({
+  note:
+    files === undefined
+      ? 'GitHub did not list the files of the pull request, so a guard file may be among them and the user confirms the merge.'
+      : `The pull request carries a guard file (${files.map((file) => `\`${file}\``).join(', ')}), which can loosen the guard that merges it, so the user confirms the merge.`,
+})
 
-const approvedBranchesFrom = (entries: unknown[], settings: GuardSettings, label: string): Set<string> => {
-  if (!settings.selfMerge.offer) return new Set()
-  return approvedBranches({ entries, label, now: Date.now(), windowMinutes: settings.selfMerge.approvalMinutes })
+/**
+ * The guard files a self-merge never covers (`STANDING_ALWAYS_ASK`): a pull request could loosen the guard that merges
+ * it. The project's own `guard.alwaysAsk` stays covered, since the user's pick is the approval for that pull request.
+ */
+const guardFilesOf = (files: readonly string[] | undefined): readonly string[] | undefined =>
+  files === undefined ? undefined : alwaysAskingFiles(files, STANDING_ALWAYS_ASK)
+
+/**
+ * The user approved the branch with the change the pull request carries, its checks passed, and it carries no guard
+ * file; a change that differs, or a guard file, answers with a note for the question.
+ */
+const approvesChange = (
+  changes: readonly ApprovedChange[],
+  requiredChecks: readonly string[] | undefined,
+  facts: MergeFacts,
+): boolean | MergeNote => {
+  const named = changes.filter(({ branch }) => branch === facts.branch)
+  if (named.length === 0 || !checksPassed(facts.view, requiredChecks)) return false
+  const id = facts.change()
+  if (!named.some(({ change }) => isSameChange(change, id))) return changedSinceApproval(facts.branch, named[0].change)
+  const guarded = guardFilesOf(facts.files())
+  return guarded?.length === 0 || carriesGuardFiles(guarded)
 }
 
 /**
- * The user approved the branch and its checks passed, every file needs no checks, or a standing approval covers the
- * plan of the branch's lane; each only for a merge bound to the head commit GitHub reports, so a push after the check
- * is not merged unchecked. A standing approval that does not cover a file answers with a note for the question.
+ * The user approved the branch with this change and its checks passed, every file needs no checks, or a standing
+ * approval covers the plan of the branch's lane; each only for a merge bound to the head commit GitHub reports, so a
+ * push after the check is not merged unchecked. An approval that does not cover the merge answers with a note.
  */
 const approvesMerge = (
-  { branches, requiredChecks, withoutChecks, alwaysAsk, standing }: MergeApprovals,
+  { changes, requiredChecks, withoutChecks, alwaysAsk, standing }: MergeApprovals,
   merge: PlainMerge,
   facts: MergeFacts,
 ): boolean | MergeNote => {
   const { headCommit } = facts
-  if (headCommit === undefined || merge.headCommit !== headCommit) return false
-  if (branches.has(facts.branch) && checksPassed(facts.view, requiredChecks)) return true
+  if (headCommit === undefined) return false
+  if (merge.headCommit !== headCommit) return unboundMergeOf(merge, changes, facts.branch)
+  const selfMerge = approvesChange(changes, requiredChecks, facts)
+  if (selfMerge === true) return true
   if (withoutChecks.length > 0 && isCheckFree(facts.files() ?? [], withoutChecks, alwaysAsk)) return true
-  return standing === undefined ? false : standing(facts)
+  const verdict = standing === undefined ? false : standing(facts)
+  return verdict === false ? selfMerge : verdict
 }
 
+/** The transcript of the session that merges, one parsed entry per line; none without one. */
+const transcriptEntries = (transcriptPath: unknown): unknown[] =>
+  typeof transcriptPath === 'string' ? parseTranscript(readFileSync(transcriptPath, 'utf8')) : []
+
 /**
- * The files of the pull request, while its head is still the commit `gh pr view` named: a push between the two
- * calls would list the files of a commit the merge does not name.
+ * A lookup about the pull request, kept only while its head is still the commit `gh pr view` named: a push between
+ * the calls would answer for a commit the merge does not name.
  */
-const filesAtHead = (pullRequest: number, view: string, directory: string): (() => readonly string[] | undefined) => {
-  const facts = parseRepositoryFacts(view)
+const atHead = <T>(pullRequest: number, view: string, directory: string, lookup: () => T | undefined): (() => T | undefined) => {
   const headCommit = parseHeadCommit(view)
   return once(() => {
-    if (facts === undefined || headCommit === undefined) return undefined
-    const files = changedFilesOf(pullRequest, directory, facts)
-    const again = files === undefined ? undefined : parseHeadCommit(viewPullRequest(pullRequest, directory) ?? '')
-    return again === headCommit ? files : undefined
+    if (headCommit === undefined) return undefined
+    const value = lookup()
+    const again = value === undefined ? undefined : parseHeadCommit(viewPullRequest(pullRequest, directory) ?? '')
+    return again === headCommit ? value : undefined
   })
 }
 
+const filesAtHead = (pullRequest: number, view: string, directory: string): (() => readonly string[] | undefined) => {
+  const facts = parseRepositoryFacts(view)
+  return atHead(pullRequest, view, directory, () => (facts === undefined ? undefined : changedFilesOf(pullRequest, directory, facts)))
+}
+
 /** The facts of the pull request from its `gh pr view`; undefined unless it is open and from this repository. */
 const mergeFactsOf = (pullRequest: number, view: string, directory: string): MergeFacts | undefined => {
   const branch = parseHeadBranch(view)
@@ -102,6 +163,7 @@ const mergeFactsOf = (pullRequest: number, view: string, directory: string): Mer
     headCommit: parseHeadCommit(view),
     view,
     files: filesAtHead(pullRequest, view, directory),
+    change: atHead(pullRequest, view, directory, () => changeIdOf(pullRequest, directory)),
   }
 }
 
@@ -131,26 +193,46 @@ const standingApprovalFor = (entries: unknown[], labels: StandingLabels, project
   }
 }
 
+/**
+ * Whether an agent in this directory runs in a linked worktree, a lane's place: its own git directory is not the
+ * repository's common one. A main checkout, where the coordinator runs, a directory outside a repository and any
+ * doubt answer no, a git that answers no single absolute path too (before 2.31 it echoes `--path-format`).
+ */
+const runsInWorktree = (agentDirectory: string | undefined): boolean => {
+  if (agentDirectory === undefined) return false
+  try {
+    const gitDirectory = (option: string): string =>
+      commandOutput(['git', 'rev-parse', '--path-format=absolute', option], agentDirectory)
+    const own = gitDirectory('--absolute-git-dir')
+    const common = gitDirectory('--git-common-dir')
+    return [own, common].every((path) => isAbsolute(path) && !path.includes('\n')) && own !== common
+  } catch {
+    return false
+  }
+}
+
 const policyFor = (input: HookInput, labels: ApprovalLabels, projectDirectory: string): GuardPolicy => {
   const settings = readGuardSettings(projectDirectory)
   const directory = typeof input.cwd === 'string' && input.cwd !== '' ? input.cwd : projectDirectory
   const entries = once(() => transcriptEntries(input.transcript_path))
-  const branches = once(() => approvedBranchesFrom(entries(), settings, labels.selfMerge))
+  const changes = once(() => approvedChangesFrom(entries(), settings, labels.selfMerge))
   const standing = once(() => standingApprovalFor(entries(), labels.standing, projectDirectory))
   return {
     commands: settings.commands,
     shellDefinitions: once(() => readShellDefinitions()),
+    isPaneSafe: (pane) => cannotBeHerd(herdrForeground(pane, directory)),
+    isAgentSafe: (target) => runsInWorktree(herdrAgentDirectory(target, directory)),
     isMergeApproved: (merge) => {
       // the same branch name in another checkout is another pull request
       if (!isWithinDirectory(directory, projectDirectory)) return false
       const approvals = {
-        branches: branches(),
+        changes: changes(),
         requiredChecks: settings.requiredChecks,
         withoutChecks: settings.withoutChecks,
         alwaysAsk: [...ALWAYS_ASK_PATHS, ...settings.alwaysAsk],
         standing: standing(),
       }
-      if (approvals.branches.size === 0 && approvals.withoutChecks.length === 0 && approvals.standing === undefined) return false
+      if (approvals.changes.length === 0 && approvals.withoutChecks.length === 0 && approvals.standing === undefined) return false
       // The branch lookup also proves the pull request is open, no draft and from this repository; every path needs that.
       const facts = mergeFactsOf(merge.pullRequest, viewPullRequest(merge.pullRequest, directory) ?? '', directory)
       return facts !== undefined && approvesMerge(approvals, merge, facts)

package/kit/hooks/hooks/merge-guard/standing-approval.ts

@@ -8,14 +8,18 @@
  * that plan, and never with a file of `STANDING_ALWAYS_ASK`. Every doubt answers "no", so the guard asks as before.
  */
 import type { DialogAnswer } from '../shared/dialog-answer'
-import { MS_PER_MINUTE } from '../shared/fresh'
-import { newestVerdict } from '../shared/newest-verdict'
+import {
+  type StandingKind,
+  type StandingLabels,
+  type StandingMark,
+  standingGrants as grantsOfKind,
+  standingMarkOf as markOfKind,
+} from '../shared/standing-mark'
 import { alwaysAskingFiles, STANDING_ALWAYS_ASK } from './always-ask'
 import type { MergeNote } from './decision'
 import { isPlainPath } from './plain-path'
 
-/** The exact option label that approves, and the word before the end in the question, both per response language. */
-export type StandingLabels = { approve: string; until: string }
+export type { StandingLabels } from '../shared/standing-mark'
 
 /** A plan whose lanes merge without a question until `until`, in milliseconds. */
 export type StandingGrant = { plan: string; until: number }
@@ -39,92 +43,25 @@ export type StandingApprovalQuery = {
   settingsBaseBranch: string
 }
 
-export const MAX_STANDING_MINUTES = 24 * 60
-
 const PLAN_PATH = /^[A-Za-z0-9_./-]+\.md$/
 
-const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-
 /** A plan path as a board links it: a relative markdown file, no empty, `.` or `..` segment. */
 const isPlanPath = (path: string): boolean =>
   PLAN_PATH.test(path) && path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
 
-/** A local moment from its parts; undefined for one the calendar or the clock does not have (Feb 30, 24:00, a DST gap). */
-const localMoment = ([year, month, day, hour, minute]: number[]): number | undefined => {
-  const date = new Date(year, month - 1, day, hour, minute)
-  const exact =
-    date.getFullYear() === year &&
-    date.getMonth() === month - 1 &&
-    date.getDate() === day &&
-    date.getHours() === hour &&
-    date.getMinutes() === minute
-  return exact ? date.getTime() : undefined
-}
+const PLAN_KIND: StandingKind = { key: 'Plan', isSubject: isPlanPath }
+
+const grantOfMark = ({ subject, until }: StandingMark): StandingGrant => ({ plan: subject, until })
 
 /** The plan and the end a question names as ``Plan `<path>` <until> YYYY-MM-DD HH:MM``; none for none or several marks. */
 export const standingMarkOf = (question: string, until: string): StandingGrant | undefined => {
-  if (until === '') return undefined
-  const mark = new RegExp(`\\bPlan \`([^\`]*)\` ${escapeRegExp(until)} (\\d{4})-(\\d{2})-(\\d{2}) (\\d{2}):(\\d{2})(?!\\d)`, 'g')
-  const marks = [...question.matchAll(mark)]
-  if (marks.length !== 1) return undefined
-  const [, plan, ...parts] = marks[0]
-  const end = localMoment(parts.map(Number))
-  return end !== undefined && isPlanPath(plan) ? { plan, until: end } : undefined
-}
-
-const PLAN_MENTION = /\bPlan `([^`]*)`/g
-
-/** The one plan a question names as ``Plan `<path>` ``, with or without an end; none for none or several. */
-const namedPlanOf = (question: string): string | undefined => {
-  const plans = new Set([...question.matchAll(PLAN_MENTION)].map(([, plan]) => plan))
-  const [only] = plans
-  return plans.size === 1 && isPlanPath(only) ? only : undefined
-}
-
-/**
- * The plan an answer speaks about, and the end its question names; `NaN` for a question that names the plan without
- * an end, which never approves but, answered with anything else, ends the approval: in doubt it ends.
- */
-const markOf = (question: string, until: string): StandingGrant | undefined => {
-  const mark = standingMarkOf(question, until)
-  if (mark !== undefined) return mark
-  const plan = namedPlanOf(question)
-  return plan === undefined ? undefined : { plan, until: Number.NaN }
-}
-
-type MarkedAnswer = DialogAnswer & { mark: StandingGrant }
-
-const approves = ({ answer, offered, answeredAt, mark }: MarkedAnswer, label: string): boolean =>
-  label !== '' &&
-  answer === label &&
-  offered.includes(label) &&
-  mark.until > answeredAt &&
-  mark.until - answeredAt <= MAX_STANDING_MINUTES * MS_PER_MINUTE
-
-/** The approval the newest answers about one plan give: all of them approve, and the earliest end is still ahead. */
-const grantOf = (plan: string, answers: readonly MarkedAnswer[], label: string, now: number): StandingGrant[] => {
-  const verdict = newestVerdict(answers, now)
-  if (verdict.length === 0 || !verdict.every((answer) => approves(answer, label))) return []
-  const until = Math.min(...verdict.map(({ mark }) => mark.until))
-  return until > now ? [{ plan, until }] : []
+  const mark = markOfKind(question, PLAN_KIND, until)
+  return mark === undefined ? undefined : grantOfMark(mark)
 }
 
 /** The plans the user approved standing in these dialog answers, and until when; only those still holding at `now`. */
-export const standingGrants = (answers: readonly DialogAnswer[], labels: StandingLabels, now: number): StandingGrant[] => {
-  const marked = answers.flatMap((answer): MarkedAnswer[] => {
-    const mark = markOf(answer.question, labels.until)
-    return mark === undefined ? [] : [{ ...answer, mark }]
-  })
-  const plans = [...new Set(marked.map(({ mark }) => mark.plan))]
-  return plans.flatMap((plan) =>
-    grantOf(
-      plan,
-      marked.filter(({ mark }) => mark.plan === plan),
-      labels.approve,
-      now,
-    ),
-  )
-}
+export const standingGrants = (answers: readonly DialogAnswer[], labels: StandingLabels, now: number): StandingGrant[] =>
+  grantsOfKind(answers, PLAN_KIND, labels, now).map(grantOfMark)
 
 const exceptedNote = (plan: string, files: readonly string[]): MergeNote => ({
   note: `The standing approval of plan \`${plan}\` does not cover ${files.map((file) => `\`${file}\``).join(', ')}: workflows, migrations, env files and the guards' own files always ask.`,

package/kit/hooks/hooks/plain-question/form.ts

@@ -0,0 +1,89 @@
+import { questionsOf, recordsOf } from './run'
+
+/** The coordinator's mark on the header chip of every question it asks the user. */
+const PAW = '🐾'
+const EXAMPLE_HEADER = 'Merge'
+const QUESTION_LENGTH = 80
+
+export const MAX_QUESTION_WORDS = 15
+export const MAX_LABEL_WORDS = 5
+/** The words of an option's description: one sentence of about 12, with room for a clause. */
+export const MAX_DESCRIPTION_WORDS = 15
+const DESCRIPTION_SENTENCE_WORDS = 12
+/** The most the dialog tool takes in a header chip. */
+const MAX_HEADER_LENGTH = 12
+
+/** Code in backticks, a flag, a path with an extension or with two slashes; a slash between two words is none. */
+const PATH_OR_FLAG = /`|(?:^|\s)--[a-z]|\S+\/\S+\.\w+|\S+\/\S+\/\S+/
+/** A link stays in the question: the user decides in the dialog, the link of a draft under review included. */
+const LINK = /https?:\/\/\S+/g
+
+const wordsIn = (text: string): number => text.split(/\s+/).filter(Boolean).length
+
+const shorten = (text: string): string =>
+  text.length > QUESTION_LENGTH ? `${text.slice(0, QUESTION_LENGTH - 1)}…` : text
+
+const labelsOf = (options: unknown): string[] =>
+  recordsOf(options).flatMap((option) => (typeof option.label === 'string' ? [option.label] : []))
+
+const textOf = (value: unknown): string => (typeof value === 'string' ? value : '')
+
+const headerReason = (header: string, name: string): string | null =>
+  header.trimStart().startsWith(PAW)
+    ? null
+    : `${name}: start the header chip with ${PAW}, as in "${PAW} ${header.trim() || EXAMPLE_HEADER}" (${MAX_HEADER_LENGTH} characters at most).`
+
+const questionLengthReason = (text: string, name: string): string | null =>
+  wordsIn(text) <= MAX_QUESTION_WORDS
+    ? null
+    : `${name}: ask it in ${MAX_QUESTION_WORDS} words at most; the context goes in the chat before the dialog (§ 4, Short questions).`
+
+const pathReason = (text: string, name: string): string | null =>
+  PATH_OR_FLAG.test(text.replace(LINK, ''))
+    ? `${name}: no path, flag or code in the question, say it in everyday words and put the detail in the chat before the dialog.`
+    : null
+
+const descriptionReason = (options: unknown, name: string): string | null => {
+  const long = recordsOf(options).find((option) => wordsIn(textOf(option.description)) > MAX_DESCRIPTION_WORDS)
+  return long === undefined
+    ? null
+    : `${name}: option "${textOf(long.label)}": describe it in one sentence of about ${DESCRIPTION_SENTENCE_WORDS} words.`
+}
+
+const labelLengthReason = (labels: readonly string[], name: string): string | null => {
+  const long = labels.find((label) => wordsIn(label) > MAX_LABEL_WORDS)
+  return long === undefined
+    ? null
+    : `${name}: option "${long}": ${MAX_LABEL_WORDS} words at most; the rest goes in its description.`
+}
+
+/**
+ * A question that offers a label a guard reads word for word keeps the branch and plan marks and the self-merge label
+ * as written, so only the paw is required of it.
+ */
+const questionReasons = (question: Record<string, unknown>, guardedLabels: readonly string[]): string[] => {
+  const text = textOf(question.question)
+  const name = `Question "${shorten(text)}"`
+  const labels = labelsOf(question.options)
+  const header = headerReason(textOf(question.header), name)
+  const lengths = labels.some((label) => guardedLabels.includes(label))
+    ? []
+    : [
+        questionLengthReason(text, name),
+        pathReason(text, name),
+        labelLengthReason(labels, name),
+        descriptionReason(question.options, name),
+      ]
+  return [header, ...lengths].filter((reason): reason is string => reason !== null)
+}
+
+/**
+ * The reason to send a coordinator's dialog back because a question does not keep the form: the paw at the start of
+ * the header chip, at most `MAX_QUESTION_WORDS` words in the question and no path, flag or code in it, at most
+ * `MAX_LABEL_WORDS` in a label and `MAX_DESCRIPTION_WORDS` in a description. Every miss of every question is named, so
+ * one send-back is enough. Null when every question keeps the form.
+ */
+export const formReasonOf = (toolInput: unknown, guardedLabels: readonly string[]): string | null => {
+  const reasons = questionsOf(toolInput).flatMap((question) => questionReasons(question, guardedLabels))
+  return reasons.length === 0 ? null : reasons.join(' ')
+}

package/kit/hooks/hooks/plain-question/index.ts

@@ -2,18 +2,24 @@
 // guard. A dialog that shows a plan code bare (`F9` instead of "the release check (F9)") is denied with one line of
 // reason, so the question is asked again in the user's words. The codes are the ones the plans linked from the boards
 // of the main checkout define, in the main checkout and in the worktrees of the lanes the boards name, else a fallback
-// pattern; a cache keyed by each file's time and size spares reading the unchanged ones. Anything else, and any
-// failure, answers nothing, so the dialog opens.
-import { statSync } from 'node:fs'
+// pattern; a cache keyed by each file's time and size spares reading the unchanged ones. A dialog whose question
+// lacks its recommendation as the first option, marked with argv[2], is denied as well, and so is a coordinator's
+// question that breaks the form of `form.ts` (🐾 header, short question and labels); argv[3…] are the labels a
+// guard reads word for word, which carry no mark. Anything else, and any failure, answers nothing, so the dialog opens.
+import { existsSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { boardLocationOf, boardsIn } from '../shared/boards'
 import { mainCheckoutOf } from '../shared/checkout'
 import { readConfig } from '../shared/config'
 import { readTextOrNull } from '../shared/files'
 import { isRecord } from '../shared/json'
+import { isCoordinatorAgent } from '../shared/lane'
+import { ownPaneAgent } from '../shared/own-pane'
 import { planCodesOf } from '../shared/plan-codes'
 import { ensurePrivateDirectory, writePrivateFile } from '../shared/private-directory'
 import { type CodeCache, lookUpCodes, type PlanFileStat, parseCodeCache, serializeCodeCache } from './code-cache'
+import { formReasonOf } from './form'
+import { type RecommendationWords, recommendationReasonOf } from './recommendation'
 import { denyReasonOf, dialogTextsOf, planPathsOfBoards, planRootsOfBoards } from './run'
 
 const HOOK_EVENT = 'PreToolUse'
@@ -27,6 +33,12 @@ const statOf = (path: string): PlanFileStat | null => {
   return stat?.isFile() ? { path, mtimeMs: stat.mtimeMs, size: stat.size } : null
 }
 
+/** argv[2] is the recommended mark, argv[3…] the labels a guard reads word for word; an older install passes none. */
+const recommendationWordsOf = (argv: readonly string[]): RecommendationWords => ({
+  mark: argv[2] ?? '',
+  guardedLabels: argv.slice(3),
+})
+
 /** Keeps the cache for the next dialog; a cache that cannot be written only costs that dialog a full read. */
 const saveCache = (main: string, cache: CodeCache): void => {
   try {
@@ -59,12 +71,40 @@ const planCodesFor = (cwd: string): Set<string> | null => {
   }
 }
 
+/** Whether the dialog is the coordinator's: the form (paw, short question and labels) binds nobody else. */
+const isCoordinatorCall = (cwd: string, session: unknown): boolean => {
+  try {
+    const main = mainCheckoutOf(cwd)
+    const location = boardLocationOf(readConfig([main]))
+    if (location === null) return false
+    const { worktreeDirectory } = location
+    return isCoordinatorAgent({
+      agent: ownPaneAgent(),
+      session,
+      main,
+      isLane: (name) => existsSync(join(main, worktreeDirectory, name)),
+    })
+  } catch {
+    return false
+  }
+}
+
+const formReasonFor = (cwd: string, session: unknown, toolInput: unknown, guardedLabels: readonly string[]): string | null =>
+  isCoordinatorCall(cwd, session) ? formReasonOf(toolInput, guardedLabels) : null
+
 const decide = async (): Promise<string | null> => {
   try {
     const input: unknown = JSON.parse(await Bun.stdin.text())
     if (!isRecord(input) || typeof input.cwd !== 'string') return null
     const texts = dialogTextsOf(input.tool_input)
-    return texts.length === 0 ? null : denyReasonOf(texts, planCodesFor(input.cwd))
+    if (texts.length === 0) return null
+    const words = recommendationWordsOf(process.argv)
+    const reasons = [
+      denyReasonOf(texts, planCodesFor(input.cwd)),
+      recommendationReasonOf(input.tool_input, words),
+      formReasonFor(input.cwd, input.session_id, input.tool_input, words.guardedLabels),
+    ].filter((reason): reason is string => reason !== null)
+    return reasons.length === 0 ? null : reasons.join(' ')
   } catch {
     return null
   }

package/kit/hooks/hooks/plain-question/recommendation.ts

@@ -0,0 +1,73 @@
+import { questionsOf, recordsOf } from './run'
+
+/**
+ * The words the check needs, per response language: the mark a recommended option's label ends with, and the option
+ * labels a guard reads word for word (approvals of a lane call, the self-merge and the standing approval). An empty
+ * mark, from an install that does not pass one, checks nothing.
+ */
+export type RecommendationWords = { mark: string; guardedLabels: readonly string[] }
+
+const QUESTION_LENGTH = 80
+
+const shorten = (text: string): string =>
+  text.length > QUESTION_LENGTH ? `${text.slice(0, QUESTION_LENGTH - 1)}…` : text
+
+const labelsOf = (options: unknown): string[] =>
+  recordsOf(options).flatMap((option) => (typeof option.label === 'string' ? [option.label] : []))
+
+const isMarked = (label: string, mark: string): boolean => label.trimEnd().toLowerCase().endsWith(mark.toLowerCase())
+
+const withoutMark = (label: string, mark: string): string =>
+  isMarked(label, mark) ? label.trimEnd().slice(0, -mark.length).trimEnd() : label
+
+/** A guarded label that carries the mark: the guard would not know the answer, so the dialog goes back. */
+const markedGuardReason = (labels: readonly string[], { mark, guardedLabels }: RecommendationWords): string | null => {
+  const label = labels.find(
+    (candidate) => isMarked(candidate, mark) && guardedLabels.includes(withoutMark(candidate, mark)),
+  )
+  return label === undefined
+    ? null
+    : `Option "${label}": a guard reads "${withoutMark(label, mark)}" word for word; drop "${mark}" from it.`
+}
+
+/** The first option carries the mark; else the reason names a later marked option to move up, or asks for one. */
+const firstMarkReason = (question: string, labels: readonly string[], mark: string): string | null => {
+  const [first, ...rest] = labels
+  if (first !== undefined && isMarked(first, mark)) return null
+  const later = rest.find((label) => isMarked(label, mark))
+  return later === undefined
+    ? `Question "${shorten(question)}": put your recommendation first and end its label with "${mark}".`
+    : `Question "${shorten(question)}": the recommendation goes first; move "${later}" to the top.`
+}
+
+/** A single choice has one recommendation: the first option carries the mark and no other does. */
+const singleChoiceReason = (question: string, labels: readonly string[], mark: string): string | null => {
+  const firstReason = firstMarkReason(question, labels, mark)
+  const second = labels.slice(1).find((label) => isMarked(label, mark))
+  return firstReason ?? (second === undefined
+    ? null
+    : `Question "${shorten(question)}": one recommendation only; drop "${mark}" from "${second}".`)
+}
+
+const questionReason = (question: Record<string, unknown>, words: RecommendationWords): string | null => {
+  const labels = labelsOf(question.options)
+  if (labels.length === 0) return null
+  const guarded = markedGuardReason(labels, words)
+  if (guarded !== null) return guarded
+  if (labels.some((label) => words.guardedLabels.includes(label))) return null
+  const text = typeof question.question === 'string' ? question.question : ''
+  // A multiSelect question may recommend several options, the first among them.
+  const reasonOf = question.multiSelect === true ? firstMarkReason : singleChoiceReason
+  return reasonOf(text, labels, words.mark)
+}
+
+/**
+ * The reason to send a dialog back because a question does not carry its recommendation as the first option, marked
+ * at the end of its label; null when every question does. A question that offers a label a guard reads word for word
+ * needs no mark, and such a label must not carry one.
+ */
+export const recommendationReasonOf = (toolInput: unknown, words: RecommendationWords): string | null => {
+  if (words.mark === '') return null
+  const [reason] = questionsOf(toolInput).flatMap((question) => questionReason(question, words) ?? [])
+  return reason ?? null
+}