jackherd 1.18.2 → 1.20.0

package/dist/plan-format.js

@@ -2,6 +2,8 @@ import {
   ADDRESS_FORM,
   APPOINTMENT_VOCABULARY,
   APPROVAL_TEXTS,
+  CARD_FIELDS,
+  HEAD_LINE,
   LANE_PROMPT_OPENING,
   LANGUAGE_NAME,
   NEXT_VOCABULARY,
@@ -9,6 +11,7 @@ import {
   PLAN_STATUS,
   PLAN_VOCABULARY,
   RECOMMENDED_MARK,
+  REPORT_FIELDS,
   RESPONSE_ADDRESS,
   SELF_MERGE_LABEL,
   STANDING_APPROVAL_TEXTS,
@@ -18,7 +21,7 @@ import {
   phaseHeading,
   sectionHeading,
   terminalSafe
-} from "./chunk-N5FAOQZL.js";
+} from "./chunk-JDO6O3UO.js";
 
 // src/plan-format/lanes.ts
 import { posix } from "path";
@@ -785,6 +788,81 @@ var tallyPhases = (markdown, language) => {
   });
 };
 
+// src/plan-format/plan-head.ts
+var HEAD_STATUS = { present: "present", missing: "missing", stale: "stale" };
+var SECTION_HEADING2 = /^##\s/;
+var HEAD_ENTRY = /^\s*(?:[-*]\s+)?\*\*([^*]+?)\s*:?\*\*\s*:?\s*(.*)$/;
+var HEAD_LINES = Object.values(HEAD_LINE);
+var labelOf = (language, line) => PLAN_VOCABULARY[language].head[line].toLowerCase();
+var entryOf = (text, language) => {
+  const match = text.match(HEAD_ENTRY);
+  if (!match) return null;
+  const written = match[1].trim().toLowerCase();
+  const label = HEAD_LINES.find((each) => labelOf(language, each) === written);
+  return label ? { label, text: match[2].trim() } : null;
+};
+var phaseOf = (statusText, language) => {
+  const match = statusText?.match(
+    new RegExp(`${escapeRegExp(PLAN_VOCABULARY[language].phase)}\\s+(\\d+[a-z]?)\\s*/\\s*(\\d+)`, "i")
+  );
+  return match ? { current: match[1].toLowerCase(), total: Number(match[2]) } : null;
+};
+var parsePlanHead = (markdown, language) => {
+  const lines = markdown.split("\n");
+  const heading = new RegExp(`^##\\s+${escapeRegExp(PLAN_VOCABULARY[language].sections.forYou)}\\s*$`);
+  const start = lines.findIndex((text) => heading.test(text));
+  if (start === -1) return null;
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((text) => SECTION_HEADING2.test(text));
+  const texts = {};
+  const lineNumbers = {};
+  for (const [offset, text] of (end === -1 ? rest : rest.slice(0, end)).entries()) {
+    const entry = entryOf(text, language);
+    if (entry && texts[entry.label] === void 0) {
+      texts[entry.label] = entry.text;
+      lineNumbers[entry.label] = start + offset + 2;
+    }
+  }
+  return {
+    line: start + 1,
+    texts,
+    lineNumbers,
+    missing: HEAD_LINES.filter((each) => texts[each] === void 0),
+    phase: phaseOf(texts[HEAD_LINE.status], language),
+    misplaced: lines.slice(0, start).some((text) => SECTION_HEADING2.test(text))
+  };
+};
+var verdict = (status, line, message) => ({ status, line, message });
+var phaseStates = (markdown, language) => parsePlanPhases(markdown, language).filter(({ id }, index, all) => all.findIndex((other) => other.id === id) === index).map(({ id, items }) => ({ id: id.toLowerCase(), open: items.some(({ done }) => !done) }));
+var phaseMismatch = ({ current, total }, states) => {
+  if (total !== states.length) return `names ${total} phases, the plan has ${states.length}`;
+  const running = states.find(({ open }) => open);
+  if (running === void 0)
+    return current === states.at(-1)?.id ? null : `all phases are done, the head names phase ${current}`;
+  return current === running.id ? null : `names phase ${current}, the running phase is ${running.id}`;
+};
+var checkPlanHead = (markdown, language) => {
+  const head = parsePlanHead(markdown, language);
+  const { sections } = PLAN_VOCABULARY[language];
+  if (head === null) return verdict(HEAD_STATUS.missing, null, `no \`## ${sections.forYou}\` section`);
+  if (head.misplaced)
+    return verdict(
+      HEAD_STATUS.stale,
+      head.line,
+      `the head must stand right after the header lines, before the other sections`
+    );
+  if (head.missing.length > 0)
+    return verdict(
+      HEAD_STATUS.stale,
+      head.line,
+      `no line ${head.missing.map((each) => `"${PLAN_VOCABULARY[language].head[each]}"`).join(", ")}`
+    );
+  const statusLine2 = head.lineNumbers[HEAD_LINE.status] ?? head.line;
+  if (head.phase === null) return verdict(HEAD_STATUS.stale, statusLine2, 'the status line has no "Phase x/y"');
+  const mismatch = phaseMismatch(head.phase, phaseStates(markdown, language));
+  return mismatch === null ? verdict(HEAD_STATUS.present, head.line, `Phase ${head.phase.current}/${head.phase.total}`) : verdict(HEAD_STATUS.stale, statusLine2, mismatch);
+};
+
 // src/plan-format/plan-structure.ts
 var noGatePattern = (language) => new RegExp(`^\\s*\\*\\*${escapeRegExp(PLAN_VOCABULARY[language].noReviewGate)}\\b`, "i");
 var tickCount = (phase) => phase.items.filter((item) => item.done).length;
@@ -913,6 +991,9 @@ export {
   ADDRESS_FORM,
   APPOINTMENT_VOCABULARY,
   APPROVAL_TEXTS,
+  CARD_FIELDS,
+  HEAD_LINE,
+  HEAD_STATUS,
   LANE_PROMPT_OPENING,
   LANGUAGE_NAME,
   NEXT_VOCABULARY,
@@ -926,6 +1007,7 @@ export {
   PLAN_VOCABULARY,
   PROSE_REASON,
   RECOMMENDED_MARK,
+  REPORT_FIELDS,
   RESPONSE_ADDRESS,
   SELF_MERGE_LABEL,
   SHORT_NAME_LIMIT,
@@ -935,6 +1017,7 @@ export {
   activeItem,
   boardRowsWithProse,
   boardRowsWithoutPhase,
+  checkPlanHead,
   classifyStatus,
   columnModels,
   countDecisions,
@@ -966,6 +1049,7 @@ export {
   parallelGroupsOfPlan,
   parseDependencyTable,
   parseModelTable,
+  parsePlanHead,
   parsePlanPhases,
   parseSprintLanes,
   phaseCount,

package/docs/plan-contract.md

@@ -2,7 +2,7 @@
 
 jackherd reads a plan from its Markdown. This is what a plan has to hold for the readers to find it, and how to check that with one command.
 
-## The four parts
+## The parts
 
 | Part | Form | Required | Read by |
 | ---- | ---- | -------- | ------- |
@@ -10,6 +10,7 @@ jackherd reads a plan from its Markdown. This is what a plan has to hold for the
 | Tasks | at least one checkbox (`- [ ]`, `- [x]`) or a ✅/⬜ table row in every phase; a phase that points at a section (``See `## Documentation` ``) counts that section's checkboxes | yes | herd (progress), watcher, `jh check` |
 | Model | a table under `### Model recommendations per phase`: the phase in the first cell (`1 — Title`, `P1`, `10c`), the model in the second (`claude-opus-5-5`, `Opus 5.5`); a dash marks a phase that needs no model | yes | lane start (the model a lane runs on), `/implement` |
 | Dependencies | a table under `### Dependencies and parallelization` with the columns `Depends on`, `Writes`, `Serial marker` and one row per phase | from two phases on, optional | `jh check --parallel`, `/implement` |
+| Head | a section `## For you` (de: `## Für dich`) right after the header lines (`**Date:**`, `**Status:**`, `**Scope:**`), before the first other `##` section, with five lines `- **<label>:** <text>` | no, a note | `jh plan check`, the reader who is not an agent |
 
 Details that decide a verdict:
 
@@ -17,6 +18,9 @@ Details that decide a verdict:
 - A model cell that names no model and is no dash is a gap: the lane would start on a guess.
 - With fewer than two phases the dependency part is reported `present` ("not needed"), never missing.
 - With two or more phases and no dependency table the plan is still valid: the phases run one after another. A table that is there but lacks a row for a phase is a gap.
+- The head's five labels are fixed per language. English: `What changes for you`, `Status`, `Your open decisions`, `Try it now`, `Next step`; German: `Was sich für dich ändert`, `Stand`, `Deine offenen Entscheidungen`, `Schon ausprobieren`, `Nächster Schritt`. The colon may stand outside the bold (`**Status**:`) and the list mark may be left out.
+- The `Status` line carries `Phase x/y`: x the id of the first phase with an open checkbox, as its heading spells it (`3`, `3a`), y the number of phases, each id counted once. When every phase is done, x is the id of the last one.
+- The head is `missing` without the section. It is `stale` when it stands behind another section, lacks a line, has no `Phase x/y`, or names another phase or phase count than the checkboxes show. Both are notes: the contract stays met and the exit code does not change, so plans written before the head keep passing.
 - The headings come from the plan language in `.jackherd/config.json` (`planLanguage`, `de` or `en`); the English ones are shown here.
 
 ## Minimal valid plan
@@ -66,6 +70,7 @@ phases: present plan.md:22 2 phases
 tasks: present plan.md:22 every phase has tasks
 model: present plan.md:12 every phase has a model
 dependencies: present every phase has a row
+head: missing no `## For you` section
 ```
 
 If the model table lacked the row for phase 2, and the dependency table were left out, the lines would read:
@@ -75,11 +80,12 @@ phases: present plan.md:22 2 phases
 tasks: present plan.md:22 every phase has tasks
 model: malformed plan.md:22 no model for P2
 dependencies: missing no dependency table: phases run one after another
+head: stale plan.md:5 names phase 1, the running phase is 2
 ```
 
 | Exit | Meaning |
 | ---- | ------- |
-| 0 | the contract is met (a missing dependency table is a note, not a gap) |
+| 0 | the contract is met (a missing dependency table and a missing or stale head are notes, not gaps) |
 | 1 | at least one part is missing or malformed |
 | 2 | wrong command line: no subcommand, unknown subcommand, no file, unreadable file, unreadable config |
 | 3 | the contract is met, but the plan or a board that links it is not on the base branch (a `base:` line names each path); the coordinator commits it first (`/orchestrate` § 2 step 0), after which the check counts as done |

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.18.2"
+version = "1.20.0"
 min_herdr_version = "0.8.2"
 description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.18.2}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.20.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/approval-gate/decision.ts

@@ -20,16 +20,16 @@ export type GateQuery = {
 const PENDING: GateDecision = { kind: 'pending' }
 
 /**
- * The open request of this call an answer names by id and hash, if the answer is one of the offered labels and was
- * given after it. The hash in the question is the one the coordinator showed; a request rewritten meanwhile has another.
+ * The request of this call an answer names by id and hash, if the answer is one of the offered labels and was given
+ * after it. The hash in the question is the one the coordinator showed; a request rewritten meanwhile has another.
  */
 const answeredRequest = (
   answer: DialogAnswer,
-  open: ReadonlyMap<string, ApprovalRequest>,
+  ofCall: ReadonlyMap<string, ApprovalRequest>,
   labels: GateLabels,
 ): ApprovalRequest | undefined => {
   const named = namedRequest(answer.question)
-  const candidate = named === null ? undefined : open.get(named.id)
+  const candidate = named === null ? undefined : ofCall.get(named.id)
   const request = candidate?.hash === named?.hash ? candidate : undefined
   const isLabel = answer.answer === labels.allow || answer.answer === labels.deny
   return request && isLabel && answer.offered.includes(answer.answer) && answer.answeredAt >= request.createdAt
@@ -39,22 +39,21 @@ const answeredRequest = (
 
 /**
  * What the user decided about this call: the newest fresh answer, given in the dialog with one of the two labels, to a
- * request of the same call that no answer was spent on yet. An earlier request of the same call counts, so a retry
- * after the approval passes at once. Anything else leaves the call pending.
+ * request of the same call. An earlier request of the same call counts, so a retry after the approval passes at once.
+ * A spent request still counts as the newest word and leaves the call pending, so an older approval never outruns it,
+ * whatever order or crash the claims went through. Anything else leaves the call pending too.
  */
 export const gateDecision = ({ requests, hash, answers, labels, now, validMinutes }: GateQuery): GateDecision => {
-  const open = new Map(
-    requests.filter((request) => request.hash === hash && request.usedAt === null).map((request) => [request.id, request]),
-  )
+  const ofCall = new Map(requests.filter((request) => request.hash === hash).map((request) => [request.id, request]))
   const decided = answers
     .filter((answer) => isFresh(answer.answeredAt, now, validMinutes))
     .sort((first, second) => second.answeredAt - first.answeredAt)
     .flatMap((answer) => {
-      const request = answeredRequest(answer, open, labels)
+      const request = answeredRequest(answer, ofCall, labels)
       return request ? [{ answer, request }] : []
     })
   const [newest] = decided
-  if (!newest) return PENDING
+  if (!newest || newest.request.usedAt !== null) return PENDING
   return newest.answer.answer === labels.allow
     ? { kind: 'allow', id: newest.request.id }
     : { kind: 'deny', id: newest.request.id }

package/kit/hooks/hooks/approval-gate/run.ts

@@ -103,9 +103,25 @@ const passStanding = (
   return dependencies.writeHistory(main, entry) ? { kind: 'allow' } : { kind: 'pending' }
 }
 
+/**
+ * Spends the other open requests of the call before the answered one is claimed. One left open would stay answerable,
+ * and its older approval could pass a retry after the user denied the newer request. The answered request goes last:
+ * while it stays open, a hook reading meanwhile reaches the same decision, and a crash leaves that answer standing.
+ */
+const settleSiblings = (
+  main: string,
+  answered: { id: string; hash: string },
+  requests: readonly ApprovalRequest[],
+  now: number,
+  dependencies: GateDependencies,
+): void => {
+  const isSibling = ({ id, hash, usedAt }: ApprovalRequest) => hash === answered.hash && usedAt === null && id !== answered.id
+  for (const { id } of requests.filter(isSibling)) dependencies.claimRequest(main, id, now)
+}
+
 /**
  * Polls the coordinator's transcripts until the user decided, a standing approval with the coordinator's mark lets the
- * call pass, the answer was claimed elsewhere, or the wait is over.
+ * call pass, or the wait is over. An answer another hook claimed first decides nothing here: this hook polls on.
  */
 const awaitDecision = async (
   main: string,
@@ -121,8 +137,12 @@ const awaitDecision = async (
     const log = dependencies.coordinatorLog(main)
     const { hash } = opened
     const decision = gateDecision({ requests, hash, answers: log.answers, labels: texts, now, validMinutes: VALID_MINUTES })
-    if (decision.kind !== 'pending' && dependencies.claimRequest(main, decision.id, now))
-      return decision.kind === 'allow' ? { kind: 'allow' } : { kind: 'denied' }
+    if (decision.kind !== 'pending') {
+      settleSiblings(main, { id: decision.id, hash }, requests, now, dependencies)
+      if (dependencies.claimRequest(main, decision.id, now)) {
+        return decision.kind === 'allow' ? { kind: 'allow' } : { kind: 'denied' }
+      }
+    }
     const standing = standingPass(heldRequest(opened, requests), log, texts, settings, now)
     const passed = standing === null ? null : passStanding(main, standing, now, dependencies)
     if (passed !== null) return passed

package/kit/hooks/hooks/browser-guard/decision.ts

@@ -0,0 +1,7 @@
+import type { JsonObject } from '../shared/json'
+
+export const BROWSER_GUARD_REASON =
+  'The coordinator does not open Chrome itself: send the look to the `browser-check` agent, its prompt names the port or address, the path and what to check.'
+
+/** A subagent's call carries its `agent_id` in the hook input, a call from the main context carries none. */
+export const isSubagentCall = (input: JsonObject): boolean => typeof input.agent_id === 'string' && input.agent_id !== ''

package/kit/hooks/hooks/browser-guard/index.ts

@@ -0,0 +1,50 @@
+// PreToolUse hook for the tools of the Claude in Chrome extension, shipped by jackherd: refuses them in the main context
+// of the coordinator, whose screenshots would stay in its context until the next `/clear`, and names the helper agent.
+// A subagent's call, a lane's and any session outside the herd pass. Any failure lets the call through: the guard
+// repeats a rule of the skill and must not stop a look it cannot judge.
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { boardLocationOf } from '../shared/boards'
+import { mainCheckoutOf } from '../shared/checkout'
+import { readConfig } from '../shared/config'
+import { isRecord } from '../shared/json'
+import { isCoordinatorAgent } from '../shared/lane'
+import { ownPaneAgent } from '../shared/own-pane'
+import { BROWSER_GUARD_REASON, isSubagentCall } from './decision'
+
+const HOOK_EVENT = 'PreToolUse'
+
+const isCoordinatorCall = (cwd: string, session: unknown): boolean => {
+  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)),
+  })
+}
+
+const refuses = async (): Promise<boolean> => {
+  try {
+    const input: unknown = JSON.parse(await Bun.stdin.text())
+    if (!isRecord(input) || typeof input.cwd !== 'string' || isSubagentCall(input)) return false
+    return isCoordinatorCall(input.cwd, input.session_id)
+  } catch {
+    return false
+  }
+}
+
+if (await refuses())
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: HOOK_EVENT,
+        permissionDecision: 'deny',
+        permissionDecisionReason: BROWSER_GUARD_REASON,
+      },
+    }),
+  )
+process.exit(0)

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

@@ -2,7 +2,20 @@
  * The positions of the values `sync` renders into the hook entry's command (`kit/hooks/hooks.json`), after the script
  * path. `arguments.test.ts` checks the entry passes them in this order.
  */
-export const ARGUMENT = { recommended: 2, approvalAllow: 3, approvalDeny: 4, selfMergeLabel: 5, standingApprove: 6 } as const
+export const ARGUMENT = {
+  recommended: 2,
+  approvalAllow: 3,
+  approvalDeny: 4,
+  selfMergeLabel: 5,
+  standingApprove: 6,
+  cardTopic: 7,
+  cardConsequences: 8,
+  cardIfUndecided: 9,
+  cardReadMore: 10,
+} as const
 
 /** The first position of a label a guard reads word for word. */
 export const FIRST_GUARDED_LABEL = ARGUMENT.approvalAllow
+
+/** The position after the last guarded label: the card's field names follow them. */
+export const AFTER_GUARDED_LABELS = ARGUMENT.cardTopic

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

@@ -0,0 +1,102 @@
+import { labelsOf, shorten, textOf } from './form'
+import { questionsOf, recordsOf } from './run'
+
+/** The four field names of the decision card, in the response language; each opens a line of the dialog's own text. */
+export type CardFields = { topic: string; consequences: string; ifUndecided: string; readMore: string }
+
+/**
+ * The words the check needs: the card's field names, and the option labels a guard reads word for word, whose
+ * dialogs (approvals) keep a form of their own. An empty field name, from an install that does not pass the names,
+ * checks nothing.
+ */
+export type CardWords = { fields: CardFields; guardedLabels: readonly string[] }
+
+/** What may stand before a field name at the start of a line: a list mark, a quote, a heading, bold or underline. */
+const LINE_OPENING = String.raw`^[ \t]*(?:(?:[-*+>]|#{1,6})[ \t]+)*(?:\*\*|__)?[ \t]*`
+/** What follows the name: a colon, the end of the bold, or the end of the line (a heading). */
+const NAME_ENDING = String.raw`[ \t]*(?::|\*\*|__|$)`
+/** A web link, a Markdown link, a path with a slash or a file name with its extension. */
+const LINK_OR_PATH = /https?:\/\/\S+|\[[^\]]*\]\([^)]+\)|\S*\w\/[\w.-]|[\w-]{2,}\.[a-z]{2,4}\b/i
+
+const escaped = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const fieldPattern = (name: string): RegExp => new RegExp(`${LINE_OPENING}${escaped(name)}${NAME_ENDING}`, 'im')
+
+const fieldNamesOf = (fields: CardFields): string[] => [
+  fields.topic,
+  fields.consequences,
+  fields.ifUndecided,
+  fields.readMore,
+]
+
+/** The text after the "read more" field, up to the next field line or the end; null without that field. */
+const readMoreText = (text: string, fields: CardFields): string | null => {
+  const match = fieldPattern(fields.readMore).exec(text)
+  if (match === null) return null
+  const rest = text.slice(match.index + match[0].length)
+  const ends = fieldNamesOf(fields)
+    .map((name) => fieldPattern(name).exec(rest)?.index ?? rest.length)
+    .filter((index) => index > 0)
+  return rest.slice(0, Math.min(rest.length, ...ends))
+}
+
+const quoted = (names: readonly string[]): string => names.map((name) => `"${name}"`).join(', ')
+
+const optionsOf = (question: Record<string, unknown>): Record<string, unknown>[] => recordsOf(question.options)
+
+/** The text the card is read from: the question and the `preview` of every option. */
+const cardTextOf = (question: Record<string, unknown>): string =>
+  [textOf(question.question), ...optionsOf(question).map((option) => textOf(option.preview))].join('\n')
+
+const missingFieldsReason = (text: string, fields: CardFields, name: string): string | null => {
+  const missing = fieldNamesOf(fields).filter((field) => !fieldPattern(field).test(text))
+  return missing.length === 0
+    ? null
+    : `${name}: decision card missing in the dialog: ${quoted(missing)}. Open a line with each field name in the "preview" of the options (a multiple choice has none: in the question), in everyday words, with consequences that can be checked (lines, files, an amount, downtime), as in "${fields.topic}: …", "${fields.consequences}: …", "${fields.ifUndecided}: …", "${fields.readMore}: <link or path>".`
+}
+
+const readMoreReason = (text: string, fields: CardFields, name: string): string | null => {
+  const readMore = readMoreText(text, fields)
+  return readMore === null || LINK_OR_PATH.test(readMore)
+    ? null
+    : `${name}: "${fields.readMore}" without a link or a path: name where to read on, as in "${fields.readMore}: https://…".`
+}
+
+/** A single choice shows each option's own consequences in its `preview`; a multiple choice has no preview. */
+const consequencesReason = (question: Record<string, unknown>, fields: CardFields, name: string): string | null => {
+  if (question.multiSelect === true) return null
+  const missing = labelsOf(optionsOf(question).filter((option) => !fieldPattern(fields.consequences).test(textOf(option.preview))))
+  return missing.length === 0
+    ? null
+    : `${name}: give each option its own line "${fields.consequences}: …" in its "preview" (missing: ${quoted(missing)}).`
+}
+
+const questionReasons = (question: Record<string, unknown>, fields: CardFields): (string | null)[] => {
+  const text = cardTextOf(question)
+  const name = `Question "${shorten(textOf(question.question))}"`
+  return [
+    missingFieldsReason(text, fields, name),
+    readMoreReason(text, fields, name),
+    consequencesReason(question, fields, name),
+  ]
+}
+
+const offersGuardedLabel = (questions: readonly Record<string, unknown>[], guardedLabels: readonly string[]): boolean =>
+  questions.some((question) => labelsOf(question.options).some((label) => guardedLabels.includes(label)))
+
+/**
+ * The reason to send a dialog back because its decision card is missing. The card stands in the dialog itself, since
+ * a `PreToolUse` hook does not see the text before it: each of the four field names opens a line in the question or in
+ * the `preview` of an option, the "read more" field has a link or a path, and every option of a single choice carries
+ * its own consequences line. Every miss is named, so one send-back is enough. Null when the card holds, when a field
+ * name is empty, and for a dialog that offers a guarded label.
+ */
+export const cardReasonOf = (toolInput: unknown, { fields, guardedLabels }: CardWords): string | null => {
+  const questions = questionsOf(toolInput)
+  if (questions.length === 0 || fieldNamesOf(fields).some((name) => name.trim() === '')) return null
+  if (offersGuardedLabel(questions, guardedLabels)) return null
+  const found = questions
+    .flatMap((question) => questionReasons(question, fields))
+    .filter((reason): reason is string => reason !== null)
+  return found.length === 0 ? null : found.join(' ')
+}

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

@@ -6,6 +6,10 @@ const EXAMPLE_HEADER = 'Merge'
 const QUESTION_LENGTH = 80
 
 export const MAX_QUESTION_WORDS = 15
+/** A multiple choice has no `preview`: its question carries the decision card, four short lines and the question. */
+export const MAX_MULTIPLE_CHOICE_QUESTION_WORDS = 60
+/** The words of an option's `preview`: the four card lines, each a sentence. */
+export const MAX_PREVIEW_WORDS = 70
 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
@@ -20,29 +24,39 @@ const LINK = /https?:\/\/\S+/g
 
 const wordsIn = (text: string): number => text.split(/\s+/).filter(Boolean).length
 
-const shorten = (text: string): string =>
+/** A question as a send-back names it: its first `QUESTION_LENGTH` characters. */
+export const shorten = (text: string): string =>
   text.length > QUESTION_LENGTH ? `${text.slice(0, QUESTION_LENGTH - 1)}…` : text
 
-const labelsOf = (options: unknown): string[] =>
+/** The labels of a question's options; an option without a text label is skipped. */
+export const labelsOf = (options: unknown): string[] =>
   recordsOf(options).flatMap((option) => (typeof option.label === 'string' ? [option.label] : []))
 
-const textOf = (value: unknown): string => (typeof value === 'string' ? value : '')
+/** The value when it is a string, else `''`. */
+export 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
+const questionLengthReason = (text: string, name: string, limit: number): string | null =>
+  wordsIn(text) <= limit
     ? null
-    : `${name}: ask it in ${MAX_QUESTION_WORDS} words at most; the context goes in the chat before the dialog (§ 4, Short questions).`
+    : `${name}: ask it in ${limit} words at most; the context goes in the decision card, in the "preview" of the options (§ 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.`
+    ? `${name}: no path, flag or code in the question, say it in everyday words and put the detail in the decision card, in the "preview" of the options.`
     : null
 
+const previewLengthReason = (options: unknown, name: string): string | null => {
+  const long = recordsOf(options).find((option) => wordsIn(textOf(option.preview)) > MAX_PREVIEW_WORDS)
+  return long === undefined
+    ? null
+    : `${name}: option "${textOf(long.label)}": its "preview" has ${MAX_PREVIEW_WORDS} words at most; one sentence per card line.`
+}
+
 const descriptionReason = (options: unknown, name: string): string | null => {
   const long = recordsOf(options).find((option) => wordsIn(textOf(option.description)) > MAX_DESCRIPTION_WORDS)
   return long === undefined
@@ -66,13 +80,15 @@ const questionReasons = (question: Record<string, unknown>, guardedLabels: reado
   const name = `Question "${shorten(text)}"`
   const labels = labelsOf(question.options)
   const header = headerReason(textOf(question.header), name)
+  const multiple = question.multiSelect === true
   const lengths = labels.some((label) => guardedLabels.includes(label))
     ? []
     : [
-        questionLengthReason(text, name),
-        pathReason(text, name),
+        questionLengthReason(text, name, multiple ? MAX_MULTIPLE_CHOICE_QUESTION_WORDS : MAX_QUESTION_WORDS),
+        multiple ? null : pathReason(text, name),
         labelLengthReason(labels, name),
         descriptionReason(question.options, name),
+        previewLengthReason(question.options, name),
       ]
   return [header, ...lengths].filter((reason): reason is string => reason !== null)
 }

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

@@ -7,19 +7,22 @@
 // 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. A PR question that offers the self-merge label (argv[5]) for a branch
 // whose staged change carries a guard file is denied too, since the merge guard never lets that approval cover it
-// (`self-merge-files.ts`; the positions are named in `arguments.ts`). Anything else, and any failure, answers nothing, so the dialog opens.
-import { existsSync, statSync } from 'node:fs'
+// (`self-merge-files.ts`; the positions are named in `arguments.ts`). Any dialog but an approval is denied when it
+// lacks the decision card (`card.ts`, field names argv[7…10]) in its own question and option previews: at `PreToolUse`
+// the text before the dialog is not in the transcript yet. Anything else, and any failure, answers nothing, so the
+// dialog opens.
+import { 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 { isCoordinatorCall } from '../shared/coordinator-call'
 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 { ARGUMENT, FIRST_GUARDED_LABEL } from './arguments'
+import { AFTER_GUARDED_LABELS, ARGUMENT, FIRST_GUARDED_LABEL } from './arguments'
+import { type CardFields, cardReasonOf } from './card'
 import { type CodeCache, lookUpCodes, type PlanFileStat, parseCodeCache, serializeCodeCache } from './code-cache'
 import { formReasonOf } from './form'
 import { type RecommendationWords, recommendationReasonOf } from './recommendation'
@@ -41,10 +44,18 @@ 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. */
+/** argv[2] is the recommended mark, argv[3…6] the labels a guard reads word for word; an older install passes none. */
 const recommendationWordsOf = (argv: readonly string[]): RecommendationWords => ({
   mark: argv[ARGUMENT.recommended] ?? '',
-  guardedLabels: argv.slice(FIRST_GUARDED_LABEL),
+  guardedLabels: argv.slice(FIRST_GUARDED_LABEL, AFTER_GUARDED_LABELS),
+})
+
+/** argv[7…10] are the card's field names; an older install passes none, and an empty name checks no card. */
+const cardFieldsOf = (argv: readonly string[]): CardFields => ({
+  topic: argv[ARGUMENT.cardTopic] ?? '',
+  consequences: argv[ARGUMENT.cardConsequences] ?? '',
+  ifUndecided: argv[ARGUMENT.cardIfUndecided] ?? '',
+  readMore: argv[ARGUMENT.cardReadMore] ?? '',
 })
 
 /** Keeps the cache for the next dialog; a cache that cannot be written only costs that dialog a full read. */
@@ -79,24 +90,7 @@ 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
-  }
-}
-
+/** The form (paw, short question and labels) binds the coordinator's dialog only. */
 const formReasonFor = (cwd: string, session: unknown, toolInput: unknown, guardedLabels: readonly string[]): string | null =>
   isCoordinatorCall(cwd, session) ? formReasonOf(toolInput, guardedLabels) : null
 
@@ -112,6 +106,7 @@ const decide = async (): Promise<string | null> => {
       denyReasonOf(texts, planCodesFor(cwd)),
       recommendationReasonOf(input.tool_input, words),
       formReasonFor(cwd, input.session_id, input.tool_input, words.guardedLabels),
+      cardReasonOf(input.tool_input, { fields: cardFieldsOf(process.argv), guardedLabels: words.guardedLabels }),
       selfMergeGuardFileReason(input.tool_input, selfMergeLabelOf(process.argv), (branch) =>
         stagedFilesOfBranch(cwd, branch),
       ),