jackherd 1.18.1 → 1.19.0

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),
       ),

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

@@ -30,17 +30,17 @@ const markedGuardReason = (labels: readonly string[], { mark, guardedLabels }: R
     : `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. */
+/** A mark on a later option while the first carries none: the recommendation goes first. */
 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}".`
+    ? null
     : `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. */
+/** A single choice has at most one recommendation: marked, it is the first option and no other carries the mark. */
 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))
@@ -62,9 +62,9 @@ const questionReason = (question: Record<string, unknown>, words: Recommendation
 }
 
 /**
- * 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.
+ * The reason to send a dialog back because a question marks a recommendation badly: the mark stands at the end of the
+ * label of the first option, on no other, and at most once; null when every question does. A recommendation is
+ * voluntary, so a question without a mark passes. A label a guard reads word for word must not carry a mark.
  */
 export const recommendationReasonOf = (toolInput: unknown, words: RecommendationWords): string | null => {
   if (words.mark === '') return null

package/kit/hooks/hooks/return-brief/decision.ts

@@ -0,0 +1,29 @@
+const MINUTE_MS = 60_000
+
+/** A prompt written this close to `now` is the one being submitted, which the transcript may already hold. */
+const CURRENT_PROMPT_MS = 10_000
+
+export const DEFAULT_BRIEF_AFTER_MINUTES = 60
+
+export type ReturnInput = {
+  /** When each prompt of the session was written, in milliseconds since the epoch. */
+  promptTimes: readonly number[]
+  now: number
+  /** Minutes of silence after which the user counts as returned; 0 turns the hook off. */
+  afterMinutes: number
+}
+
+/** The minutes since the user's last earlier prompt; null when there is none (a first prompt is no return). */
+export const minutesAway = (promptTimes: readonly number[], now: number): number | null => {
+  const earlier = promptTimes.filter((time) => time < now - CURRENT_PROMPT_MS)
+  return earlier.length === 0 ? null : Math.floor((now - Math.max(...earlier)) / MINUTE_MS)
+}
+
+/** The context for the coordinator when the user comes back after `afterMinutes` or more; null otherwise. */
+export const returnContext = ({ promptTimes, now, afterMinutes }: ReturnInput): string | null => {
+  if (afterMinutes <= 0) return null
+  const away = minutesAway(promptTimes, now)
+  return away === null || away < afterMinutes
+    ? null
+    : `The user was away for ${away} minutes. Before you answer, run \`jh brief\` and put its lines to the user in the language you reply in. Report only: the open questions it counts wait for their own dialog.`
+}

package/kit/hooks/hooks/return-brief/index.ts

@@ -0,0 +1,37 @@
+// UserPromptSubmit hook of Claude Code, shipped by jackherd. When the user comes back to the coordinator after
+// `plans.briefAfterMinutes` (default 60) without a prompt, it adds the context to show the situation with `jh brief`
+// first. It only adds context: every failure, a lane, an absent transcript or a first prompt ends in exit 0 without
+// output, and a prompt is never blocked.
+import { readFileSync } from 'node:fs'
+import { isCoordinatorCall } from '../shared/coordinator-call'
+import { isRecord } from '../shared/json'
+import { promptTimesOf } from '../shared/transcript'
+import { returnContext } from './decision'
+import { briefAfterMinutes } from './settings'
+
+const HOOK_EVENT = 'UserPromptSubmit'
+
+const contextFor = (input: unknown): string | null => {
+  if (!isRecord(input) || typeof input.cwd !== 'string' || typeof input.transcript_path !== 'string') return null
+  const afterMinutes = briefAfterMinutes(process.env.CLAUDE_PROJECT_DIR ?? input.cwd)
+  if (afterMinutes <= 0) return null
+  const context = returnContext({
+    promptTimes: promptTimesOf(readFileSync(input.transcript_path, 'utf8')),
+    now: Date.now(),
+    afterMinutes,
+  })
+  return context !== null && isCoordinatorCall(input.cwd, input.session_id) ? context : null
+}
+
+const decide = async (): Promise<string | null> => {
+  try {
+    return contextFor(JSON.parse(await Bun.stdin.text()))
+  } catch {
+    return null
+  }
+}
+
+const context = await decide()
+if (context !== null)
+  console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: HOOK_EVENT, additionalContext: context } }))
+process.exit(0)

package/kit/hooks/hooks/return-brief/settings.ts

@@ -0,0 +1,11 @@
+import { homedir } from 'node:os'
+import { readConfig, sectionOf } from '../shared/config'
+import { DEFAULT_BRIEF_AFTER_MINUTES } from './decision'
+
+const isMinutes = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value) && value >= 0
+
+/** `plans.briefAfterMinutes` of the first config that sets it to a number (project before home), else the default. */
+export const briefAfterMinutes = (projectDirectory: string, home: string = homedir()): number =>
+  [readConfig([projectDirectory]), readConfig([home])]
+    .map((config) => sectionOf(config, 'plans').briefAfterMinutes)
+    .find(isMinutes) ?? DEFAULT_BRIEF_AFTER_MINUTES

package/kit/hooks/hooks/shared/coordinator-call.ts

@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { boardLocationOf } from './boards'
+import { mainCheckoutOf } from './checkout'
+import { readConfig } from './config'
+import { isCoordinatorAgent } from './lane'
+import { ownPaneAgent } from './own-pane'
+
+/** Whether the hook was called for the coordinator's session; any failure or a project without a board answers no. */
+export 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
+  }
+}

package/kit/hooks/hooks/shared/transcript.ts

@@ -13,6 +13,7 @@ type Entry = {
   type?: unknown
   isMeta?: unknown
   promptId?: unknown
+  timestamp?: unknown
   message?: { content?: unknown }
 }
 
@@ -87,3 +88,11 @@ export const readTurn = (jsonl: string, promptId: string | undefined): Turn => {
       .map(({ name }) => name),
   }
 }
+
+/** When each prompt the user typed was written, in milliseconds since the epoch, in order; a prompt without a readable time is skipped. */
+export const promptTimesOf = (jsonl: string): number[] =>
+  parseEntries(jsonl).flatMap((entry) => {
+    if (promptText(entry) === undefined || typeof entry.timestamp !== 'string') return []
+    const time = Date.parse(entry.timestamp)
+    return Number.isNaN(time) ? [] : [time]
+  })

package/kit/hooks/hooks.json

@@ -15,6 +15,15 @@
       "timeout": 10
     }
   },
+  "browser-guard": {
+    "event": "PreToolUse",
+    "matcher": "mcp__claude-in-chrome__.*",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/browser-guard/index.ts",
+      "timeout": 10
+    }
+  },
   "format-on-edit": {
     "event": "PostToolUse",
     "matcher": "Edit|Write",
@@ -83,7 +92,15 @@
     "matcher": "AskUserQuestion",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/plain-question/index.ts '{{kit.question.recommended}}' '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.guard.selfMergeLabel}}' '{{kit.guard.standingApproval.approve}}'",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/plain-question/index.ts '{{kit.question.recommended}}' '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.guard.selfMergeLabel}}' '{{kit.guard.standingApproval.approve}}' '{{kit.card.topic}}' '{{kit.card.consequences}}' '{{kit.card.ifUndecided}}' '{{kit.card.readMore}}'",
+      "timeout": 10
+    }
+  },
+  "return-brief": {
+    "event": "UserPromptSubmit",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/return-brief/index.ts",
       "timeout": 10
     }
   },

package/kit/review/agents/security-audit.md

@@ -1,7 +1,7 @@
 ---
 name: security-audit
 description: 'Use when a change touches auth, tenant isolation, access policies, API keys, secrets, user input, database queries, message payloads or infrastructure: OWASP Top 10, secrets exposure, authz, input validation, injection, path traversal.'
-model: {{kit.model.review}}
+model: {{kit.model.plan}}
 tools: Read, Grep, Glob
 user-invocable: false
 ---

package/kit/workflow/agents/browser-check.md

@@ -0,0 +1,29 @@
+---
+name: browser-check
+description: 'Looks at a running page in the Claude in Chrome extension and reports findings with saved screenshots. Use when: a change needs a look in the real browser (acceptance of a lane, a visual or console check). Reads and looks only.'
+model: {{kit.model.review}}
+tools: Read, mcp__claude-in-chrome__tabs_context_mcp, mcp__claude-in-chrome__tabs_create_mcp, mcp__claude-in-chrome__tabs_close_mcp, mcp__claude-in-chrome__navigate, mcp__claude-in-chrome__computer, mcp__claude-in-chrome__read_page, mcp__claude-in-chrome__get_page_text, mcp__claude-in-chrome__find, mcp__claude-in-chrome__read_console_messages, mcp__claude-in-chrome__read_network_requests
+user-invocable: false
+---
+
+You look at a page in the user's Chrome and report what you saw. The page stays exactly as it is.
+
+## Task
+
+The prompt names the port or address, the path to open and what to check. Open a new tab of your own, never an existing one, and close it when you are done.
+
+## Rules
+
+- The extension acts as the user, with their real login: read and look only. Navigate, scroll, hover, read the page, the console and the network; a click that only opens or shows is yours. A click or an entry that would write (submit, save, delete, send, confirm) is not: name the step in your report and stop there. Never run against a shared environment unless the prompt says so.
+- One Chrome serves all lanes. Work one check at a time and close your tab afterwards.
+- A tab in a background window renders the DOM and takes screenshots, but anything waiting on animation frames stays blank there. Report that as the reason, not as a finding about the page.
+- Take screenshots with `save_to_disk`, at least one per path and one per step the prompt asks to see, and keep the saved paths. A screenshot that times out gets one more try.
+- Wait for data before you judge: poll for real content instead of reading an empty page right after navigation, for up to 60 seconds unless the prompt says otherwise, then report a timeout.
+
+## Report
+
+Return plain text, no screenshot inline:
+
+- Per step: what you opened, what you saw, and the finding (matches the ask, or what differs).
+- The absolute path of every saved screenshot, one per line, with what it shows.
+- Steps you did not run because they would write, and why you could not look (blank page, login wall, timeout).

package/kit/workflow/skills/implement/SKILL.md

@@ -54,7 +54,7 @@ Write code and tests with Write and Edit, never through a here-document or a scr
 
 ## Step 3: Verify
 
-After each changed file: `{{kit.command.typecheck}}` in the package and `{{kit.command.lint}}` clean, no dead code.
+After each changed file: `{{kit.command.typecheck}}` and `{{kit.command.lint}}` clean, no dead code.
 
 ## Step 4: Write Tests
 
@@ -62,7 +62,7 @@ Follow the decision tree in `.claude/rules/kit/testing.md`; run the tests with `
 
 ## Step 4b: Look at It
 
-A change a user sees (a page, a route, a redirect, a printed document) is looked at in the running app before `/pre-commit`: unit tests prove the pieces, only the running app proves they meet. Use a temporary end-to-end spec or the browser, a screenshot per state, and report what each shows; delete the temporary spec before the commit unless the plan asks for one. No visible change → skip, and say so in the report.
+A change a user sees (a page, a route, a redirect, a printed document) is looked at in the running app before `/pre-commit`: unit tests prove the pieces, only the running app proves they meet. Use a temporary end-to-end spec or the browser, a screenshot per state, and report what each shows; delete the temporary spec before the commit unless the plan asks for one. No visible change → skip.
 
 ## Step 5: arc42 and Architecture
 
@@ -74,7 +74,7 @@ Once tests are green, types clean, the change looked at and Step 5 done: call `/
 
 Ask every question with a fixed set of answers through the `AskUserQuestion` tool, in {{kit.responseLanguage}}.
 
-The report at the end is short: one line of diff stat, one line per check with its numbers, open points, questions; everything else is in the plan, by reference. Each question carries the situation, the problem and what each option leads to, in everyday words, not only the options and `file:line`. Mark each question `blocking` or `not blocking`. A blocking one stops the step it decides; a not blocking one leaves a `TODO` at its spot and the work goes on, with neither your recommendation nor another option built as decided.
+The report at the end is five lines, each opening with its field: `{{kit.report.goal}}:`, `{{kit.report.phase}} x/y:`, `{{kit.report.result}}:` (diff stat, a figure per check), `{{kit.report.needsYou}}:` (else `nothing`), `{{kit.report.next}}:`; then the questions; the rest is in the plan. Each question carries the decision card, four lines opening with `{{kit.card.topic}}:`, `{{kit.card.consequences}}:`, `{{kit.card.ifUndecided}}:` and `{{kit.card.readMore}}:` (a link or path): the situation, the problem and what each option leads to, in everyday words. Mark each question `blocking` or `not blocking`. A blocking one stops the step it decides; a not blocking one leaves a `TODO` at its spot and the work goes on, with neither your recommendation nor another option built as decided.
 
 ### Git commands run one at a time
 
@@ -84,6 +84,8 @@ The report at the end is short: one line of diff stat, one line per check with i
 
 Runs once the phase's review gate is ticked off, committed or not (a lane under `/orchestrate` commits only when its pull request is ready), and only then — never in the middle of a task.
 
+Before the next phase or the hand-over, update the plan's `## {{kit.heading.forYou}}` head: `Phase x/y` names the next phase with an open box (the last one once all are done), then open decisions, what the user can try, next step; done when `jh plan check <plan>` prints `head: present`. A plan without a head gets one at its last phase boundary, not before.
+
 1. Read the fill of your own context from the log, not from memory:
 
    ```bash

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -140,7 +140,7 @@ On wake-up:
 | `gh unavailable` | Tell the user once; herdr watching continues |
 | `lane <name> alert` | Send the lane once the request for its hand-over at the end of its current phase: [`references/lane-handover.md`](references/lane-handover.md) |
 | `approval <name> <id> <tool> · <call>` | A call of the lane waits for the user's approval (**Approvals**, below) |
-| `coordinator warn` / `coordinator alert` | § 8, for yourself |
+| `coordinator clear` / `coordinator warn` / `coordinator alert` | § 8, for yourself |
 | `lane added: <name>` | Check that it has its row (§ 2 step 5); a name `<lane>-<purpose>` without a worktree is a helper agent of that lane and needs no row. One the lane did not announce goes to the user |
 | `kit updated <old> → <new>` | The watcher ended. After the `jh update` call has finished (with `(source changed)` there is no call to wait for), read the change of this skill and of each reference the next lines name, by the diff or file each names; read this skill file again (no session restart) only when the line says `diff unavailable`; `orchestrate skill unchanged` needs no reading. Then start the stream again |
 | an event line ending in `· read <path>` | A rare event (`feedback`, `preview`, `source`, `parallel`, `deploy`, `due`, `stalled`, a lane's `warn`, …): read the file it names and handle it as it says; the `parallel tasks` section of [`references/events.md`](references/events.md) also before you switch `watch.parallelTasks.auto` on |
@@ -148,6 +148,9 @@ On wake-up:
 | `superseded by <pid>` / `stopped by SIGTERM` | Nothing for `superseded`. After `stopped by SIGTERM` from outside, start it again |
 | `watcher stopped: <reason>` | Tell the user, fix the cause, then start it again |
 
+**A look in the browser goes to the `browser-check` agent:** screenshots in your own context stay until the next
+`/clear`. A look that needs page scripts goes to the lane.
+
 **A decision of the user goes into the file at once.** Whatever the user decides about a plan or the
 board (a phase dropped or postponed, the order changed, an approval with its scope, an answer) you write
 into the plan or the board in the same turn, with the date and "User". **A date or time in a record is read,
@@ -177,6 +180,9 @@ the turn the answer arrives (also a "no") or the thing is withdrawn; an empty st
 waiting on the answer, a source's report and what needs no row: [`references/waiting.md`](references/waiting.md).
 A line `Ask me the open … now (jh waiting).` from the herd: [`references/herd-ask.md`](references/herd-ask.md).
 
+**The user comes back after a long absence** (the `return-brief` hook adds the context "The user was away for n
+minutes"): show the `jh brief` lines, so they see each lane's goal, status and what it needs from them.
+
 **A new idea during a release** (while a plan's phases run toward one release) is a line in the plan's
 `## Follow-ups` section, with its origin, and one line to the user: no dialog, no new phase. It enters the
 release only when the release would otherwise be wrong (a bug, a false statement, a security hole) or the
@@ -194,8 +200,8 @@ Jack has seen. Before `AskUserQuestion`, every option of the lane's question blo
    --topic <topic>`, the only way to answer a lane's question yourself. A refusal sends the question to
    the user.
 4. **Own words are evidence.** A sentence Jack adds is either the lane's evidence or checked by Jack.
-5. **Context the user can follow** (**Short questions**, below). Options with only `file:line` go back
-   to the lane.
+5. **Context the user can follow**: the decision card (**Short questions**, below). A question without
+   its four fields, or with options that carry only `file:line`, goes back to the lane.
 
 Done when each relayed premise carries its source and only open decisions remain.
 
@@ -216,22 +222,37 @@ Silence is no answer: a collected question stays open until the user answered it
 
 **Short questions.** A dialog holds the decision and nothing else. The
 `plain-question` hook sends back a question of more than 15 words or with a path, flag or code in it, a label
-of more than five words, a description past one sentence of about twelve, and a plan code without its words
-(`the architecture docs (P7)`); a dialog that offers a guard's label is checked only for the paw. Beyond
-the hook:
+of more than five words, a description past one sentence of about twelve, a plan code without its words
+(`the architecture docs (P7)`), and a dialog that lacks the **decision card**; a dialog that offers a
+guard's label is checked only for the paw. Beyond the hook:
 
 - No number in the question, unless it is the decision itself; two or three options, mostly.
-- The context comes before it, in the chat: three short lines at most, and only what the decision needs:
-  the situation, the problem and what each option leads to, in everyday words, with any term the
-  user may not know explained. Details come on request.
-- A lane's question you pass on names the lane in backticks in its first context line
-  (``Lane `<lane>` asks: …``, in the language of the replies), not in the question; **Approvals** keeps its own form.
+- A recommendation only where you would honestly give one, and then always: first option, ending its label with
+  `{{kit.question.recommended}}`, at most one in a single choice. With none, no option carries a mark.
+- The context comes with it, in the dialog, as the decision card: four lines, each opening with its field
+  (`{{kit.card.topic}}`, `{{kit.card.consequences}}`, `{{kit.card.ifUndecided}}`, `{{kit.card.readMore}}`),
+  only what the decision needs: the situation, the problem and what each option leads to, in everyday words,
+  with any term the user may not know explained. The hook does not see the chat before the dialog, so the card
+  stands in each option's `preview`: its own `{{kit.card.consequences}}` line in every option, the other three
+  lines once, in the first option's. A multiple choice has no `preview`: its question carries the four lines,
+  up to 60 words. Consequences name what can be checked (diff lines, files, an amount, downtime), not a summary.
+  The link is one you read, never an invented one. Details come on request.
+- A lane's question you pass on names the lane in backticks in its `{{kit.card.topic}}` line
+  (``{{kit.card.topic}}: lane `<lane>` asks …``, in the language of the replies), not in the question;
+  **Approvals** keeps its own form.
 - A plan item in the chat and in a waiting row is named by what it is, as in the dialog.
 
 ```text
 Question: Retry the failed check, or leave it?
 - Retry it (recommended): runs the check again
+  preview:
+  {{kit.card.topic}}: the type check failed once on an unchanged diff.
+  {{kit.card.consequences}}: a retry takes about 8 minutes and changes no file.
+  {{kit.card.ifUndecided}}: the pull request waits.
+  {{kit.card.readMore}}: <link to the failed run>
 - Leave it: the pull request waits
+  preview:
+  {{kit.card.consequences}}: the merge stays held until the check is green.
 ```
 
 **A draft for review** (a README, a page, a plan a lane wrote for the user to read, or a text you wrote for the
@@ -339,8 +360,9 @@ After its last PR is merged, follow
 - **A lane's hand-over:** its request on `lane <name> alert`, and a lane `done` or `idle` whose worktree holds
   `.claude/handover/<lane>.md` with the line `{{kit.word.openSubagents}}: 0`:
   [`references/lane-handover.md`](references/lane-handover.md).
-- **For yourself:** on `coordinator warn` or above, hand yourself over without asking, at a quiet moment,
-  through the hand-over script: [`references/coordinator-handover.md`](references/coordinator-handover.md).
-  After a restart or hand-over, compare `CronList` with the board's appointments as that file says. A status
+- **For yourself:** on `coordinator clear`, clear without asking; on `coordinator warn`, work on until that line
+  comes: [`references/coordinator-clear.md`](references/coordinator-clear.md). On
+  `coordinator alert`, hand yourself over: [`references/coordinator-handover.md`](references/coordinator-handover.md).
+  After a restart, a hand-over or a clear, compare `CronList` with the board's appointments as those files say. A status
   line without a value (the reason in brackets, such as `no agent named <name>`, or the error it hit) is
   no value: tell the user in one line and never read it as `ok`.

package/kit/workflow/skills/orchestrate/references/acceptance.md

@@ -3,13 +3,14 @@
 Read when a lane with a visible change reports ready, before you put its PR question to the user
 (`/orchestrate` § 5 step 2).
 
-Open the lane's port in the Claude in Chrome extension: it carries the user's real login, so it shows what the
-lane's Playwright spec cannot (the user's account, their role, their theme). Walk the path the phase changed,
-screenshot it for the user, and send a finding back to the lane instead of asking about the PR. Done when the
-user has the screenshots and every finding went to the lane.
+Send the look to the `browser-check` agent. Its prompt names the lane's port, the path the phase changed, what to
+check, above all what the lane's spec cannot show (the user's account, role, theme), and the surfaces the project supplement lists as blank in a background window. The agent returns findings as text and the paths of the
+screenshots it saved: forward the files to the user with `SendUserFile` without looking at them yourself, and send
+each finding back to the lane instead of asking about the PR. A session without that tool gives the user the files' absolute paths instead, unseen as well. Done when the user has the files or their paths and every finding
+went to the lane.
 
-- One Chrome serves all lanes: accept them one after the other.
-- A tab in a background window renders the DOM and screenshots fine, but anything waiting on animation frames
-  stays blank there; only for that, ask the user to bring the window up.
-- The extension acts as the user: read and look only. A step that writes goes to the user first, and never
-  runs against a shared environment without their approval.
+- One Chrome serves all lanes: run one `browser-check` at a time.
+- A report that it could not look (blank in a background window, login wall, timeout) is no finding for the lane:
+  ask the user to bring the window up or log in, then send the look again.
+- A step that writes comes back to you and goes to the user first: the user does it in their browser, or the lane
+  in its own spec. It never runs against a shared environment without their approval.

package/kit/workflow/skills/orchestrate/references/close-lane.md

@@ -9,7 +9,7 @@ or when the user names a lane to close. Run both commands from the main checkout
    nothing: resolve each reason it prints (a named file goes to the user first, a working agent is waited for, a lock
    is lifted once its session ended, an unmerged branch is not closed) and repeat until it exits 0.
    A worktree on no branch closes when its head is on the base branch and only staged plan changes the base holds are left.
-2. `jh lane close <lane>` asks the user through its ask rule, dry run included; that prompt is the user's agreement, so ask no dialog around it (under `bypassPermissions` no rule asks: ask first). It runs the listed steps, one line each. After a failure,
+2. `jh lane close <lane>` Run it without asking the user; its checks are the safeguard. It repeats the step 1 checks (resolve a refusal as in step 1) and runs the listed steps, one line each. After a failure,
    run it again: with the worktree gone and the branch left, `jh lane close <lane> --branch <branch>` finishes the
    branch and the board; a lane closed in full says so and changes nothing.
 3. The command leaves the rows marked `{{kit.word.laneClosed}} <date>` and the `{{kit.heading.history}}` row as a

package/kit/workflow/skills/orchestrate/references/coordinator-clear.md

@@ -0,0 +1,45 @@
+# § 8: clearing your context at a quiet moment
+
+Read on the watcher line `coordinator clear <n>k`, on `coordinator warn`, and when a chat starts as
+`/orchestrate <board> Cleared: …` in your reply language.
+
+**The watcher decides the moment, you do not.** It sends `coordinator clear` when nothing is open: once per rise of
+your fill above `plans.context.coordinator.clearTokens`, and once after a merge with the board written afterwards.
+`coordinator warn`: work on until that line comes. `coordinator alert`:
+[`coordinator-handover.md`](coordinator-handover.md); with both lines standing, `coordinator clear` wins, it needs
+no note.
+
+## On `coordinator clear`
+
+1. **Secure what only the chat holds.** A decision of the user not yet in a plan or the board goes there now (§ 4);
+   a trap, a suspicion or a next step only the chat holds goes as one dated line into the board's history, an
+   instruction that holds only for now with the condition it ends on.
+   Write no note: what the files hold, nobody copies. A clear is no bundling moment: board lines stay in the main
+   checkout's board. Wait for your own background tasks and subagents to finish, the watcher's stream aside. A dialog
+   or a new report since the line means this moment has passed: work on. The next line comes after the next merge;
+   without one, `coordinator alert` hands you over.
+2. **Read the list and get the line:** the `standing approvals` post of `jh resume --coordinator --board <board>`
+   names each line and end for step 3; `jh resume --clear-line --board <board>` prints the first input of the next
+   chat.
+3. **Start the hand-over script** with it, as a plain Bash call, without `&`, `run_in_background` or `setsid`:
+   `bun .claude/skills/orchestrate/handover/index.ts --send "<the line>"`. Per standing approval
+   still holding, add `--board <board> --approval "<line number> <its end>"`;
+   it goes in as a hint and the new chat asks again. The script returns `hand-over started: pid <n>, log <path>`.
+   **End your turn right after it**, with one line to the user that the chat is about to clear. Any other output
+   (`hand-over not started: <reason>`) means no clear runs.
+   [`coordinator-handover.md`](coordinator-handover.md) covers what the script does once started, aborts included.
+
+## In the new chat
+
+1. Run `jh resume --coordinator --board <board>`. Each post lists its count and one line per entry with its place;
+   zero means none, `unknown` means it could not be read, so read that one yourself. Only the board, herdr and `gh`
+   can be `unknown`: an unreadable approvals or records directory counts as empty. Then read the newest dated lines
+   of the board's history: what the old chat secured stands there.
+2. Start the watcher (§ 4). The old chat's stream outlives the clear, and starting yours ends it with `superseded by
+   <pid>`, nothing to do; background tasks of the old chat keep running too.
+3. Approvals the watcher reported before the clear are not reported again: take the open ones from
+   the list and handle them (**Approvals**, § 4). Work through the rest of the list: a lane's open questions from the report it names; an `order without a report` waits for
+   that lane, nothing to send again; PRs, what waits on the user and appointments as § 4 and § 5 say. Timers survive
+   `/clear`: compare `CronList` with the appointments listed, create a missing one, delete one without a row. Done
+   when every listed lane has a started next action or a named reason to wait (§ 4), and every other post is handled
+   or zero.

package/kit/workflow/skills/orchestrate/references/coordinator-handover.md

@@ -1,27 +1,30 @@
 # § 8: the coordinator hands itself over
 
-Read on the watcher event `coordinator warn` or `coordinator alert`, and when a chat starts as
-`/orchestrate <board> Hand-over: …` or after a restart of your session. `jh resume` starts a chat as
+Read on the watcher event `coordinator alert`, and when a chat starts as
+`/orchestrate <board> Hand-over: …` or after a restart of your session. Clearing is the normal way
+([`coordinator-clear.md`](coordinator-clear.md)); a hand-over with a note is for `coordinator alert`, when no quiet
+moment came. `jh resume` starts a chat as
 `/orchestrate <board> Restart after a crash: …` in your reply language: start the watcher (§ 4), compare the
 alarms below, handle each lane as on wake-up; the resumed lanes it names have their message.
 
-## The hand-over, at a quiet moment
+## The hand-over, at your next stop
 
-Hand yourself over to a fresh chat at a quiet moment (no merge or rebase half done, no dialog open, no answer of
-the user awaited):
+Hand yourself over to a fresh chat as soon as no merge or rebase is half done, no dialog is open and no answer of
+the user is awaited:
 
 1. **Prepare.** Record your hand-over where the project supplement says, by default in the board's
-   `{{kit.heading.history}}` (dated as § 4 reads it): the state of every lane, what waits on the user, the next
-   step, the traps. It holds the hand-over only: a decision of the user that is not yet in a plan or the board
-   belongs there first (§ 4), not into the note. Collected not blocking questions are named by the path of the
+   `{{kit.heading.history}}` (dated as § 4 reads it): the next step and the traps and suspicions no file holds. The note holds the hand-over only: a decision of the user that is not yet in a plan or the board
+   belongs there first (§ 4), not into the note; the state of the lanes and what waits on the user come from
+   `jh resume --coordinator`. Collected not blocking questions are named by the path of the
    lane report that holds them, never copied. Board lines of § 4 not on `{{kit.baseBranch}}` yet go into a documentation PR now (the bundling moment). Write the prompt for the new chat to
-   `.claude/handover/coordinator.md`: what to read first, then the steps in order. It is read, not typed, so it
-   may be long.
+   `.claude/handover/coordinator.md`: what to read first, then the steps in order, the first of them
+   `jh resume --coordinator --board <board>`, whose list holds the approvals the watcher will not report again. The
+   file is read, not typed, so it may be long.
 2. **Start the hand-over script** as a plain Bash call, without `&`, `run_in_background` or `setsid`:
    `bun .claude/skills/orchestrate/handover/index.ts --send "/orchestrate <board> Hand-over: read .claude/handover/coordinator.md first and continue with the next step it names."`
    Per standing approval still holding, add `--board <board> --approval "<line number> <its end>"`: its row
-   goes in as a hint; the new chat asks again ([`standing-approval.md`](standing-approval.md)); `claude --resume` keeps it. It detaches itself and returns `hand-over started: pid <n>, log <path>`. **End your turn right after it**,
-   with one line to the user that the chat is about to clear.
+   goes in as a hint; the new chat asks again ([`standing-approval.md`](standing-approval.md)); `claude --resume` keeps the approval. The script detaches itself and returns `hand-over started: pid <n>, log <path>`. **End your turn right after it**,
+   with one line to the user that the chat is about to clear. Any other output (`hand-over not started: <reason>`, for example a refused `--approval`) means no hand-over runs.
 
 ## What the script does
 

package/kit/workflow/skills/plan/SKILL.md

@@ -30,6 +30,8 @@ A plan records decisions; it is not where they get taken. If the `## {{kit.headi
 
 **Structure:** copy the template in [`references/template-{{kit.planLanguage}}.md`](references/template-{{kit.planLanguage}}.md) and fill it in. Every section stays, in its order, with its heading verbatim.
 
+The `## {{kit.heading.forYou}}` head is what a person reads first, in everyday words, with `Phase 1/<number of phases>` in the status line; done when `jh plan check <plan>` prints `head: present`.
+
 The closing documentation section reads `## N — …` with rows `N.1` to `N.5`: replace `N` with the number of that phase (`## 10 — …`, `10.1`). A literal `N` is no phase to the herd, which shows it as "not in the plan".
 
 A checkbox moved on purpose to a later phase stays where it is, unticked, and ends in the target: `- [ ] Update the documentation → P9`. The herd counts it neither as open nor as done in its own phase and lists it as open in phase 9. The arrow stands only at the end of the line. Once a phase's tasks are ticked on the base branch, every box still open in it, gate boxes included, is ticked or moved on this way; `jh check` checks both.

package/kit/workflow/skills/plan/references/template-English.md

@@ -4,6 +4,14 @@
 **{{kit.heading.status}}:** Draft / In Progress / Done / Abandoned
 **{{kit.heading.scope}}:** `affected/paths`
 
+## {{kit.heading.forYou}}
+
+- **What changes for you:** one sentence in everyday words
+- **Status:** Phase 1/N (N = number of phases): name of the running one
+- **Your open decisions:** which, or "none"
+- **Try it now:** what, or "nothing"
+- **Next step:** what, and who
+
 ## Problem / Context
 
 What is the trigger? Why now? One paragraph.