jackherd 1.1.0 → 1.3.0

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

@@ -277,7 +277,7 @@ not fire), when a lane's PR merges, its checks turn red or green, the same for o
 PRs on a branch no lane has (`=== checks failed #<n> (branch <name>)`, found by `--author @me`: a
 documentation or `chore` PR you opened yourself; act on it like on a lane's, a merge makes every
 lane rebase), a deploy run ends (after such a merge `(push, #<n>)`), the
-heartbeat falls due, `gh` becomes unreachable, the installed kit changes version (`=== kit updated <old> → <new>`, then the watcher ends), or your own fill rises to `warn` or `alert`
+heartbeat falls due, `gh` becomes unreachable, the installed kit changes version (`=== kit updated <old> → <new>`, then the watcher ends), npm names a newer release (`=== update available <old> → <new>`, once a day at most and once per version), or your own fill rises to `warn` or `alert`
 (`=== coordinator <level> <share>`). Every report prints the event blocks, then `status:` with one
 line per lane: its status, its branch, its PR with checks, and its open phase with the starts-after
 entry (or that the plan is finished, or that there is no plan). One more line holds your own fill,
@@ -370,6 +370,7 @@ On wake-up:
 | `lane added: <name>` | Nothing: the lane is watched. Check that it has its row (§ 2 step 5) |
 | `lane removed: <name>` | Nothing after you closed it (§ 7). Otherwise its agent exited or its worktree is gone: read why, then tell the user |
 | `kit updated <old> → <new>` | The kit was updated under the running watcher, which ended. After the `jh update` call has finished, read the change of this skill the next line names (`orchestrate skill: § … changed · diff <path>`; the diff shows the kit's placeholders, not your values), so the new text is the one you follow; read this skill file again (`Read` on the file you were given, no session restart) only when the line says `diff unavailable`; `orchestrate skill unchanged` needs no reading. Then start the stream again |
+| `update available <old> → <new>` | A newer jackherd is on npm. Ask the user with `AskUserQuestion` (update now / not now) and run `jh update` only after a yes; the watcher then ends with `kit updated`, handle it as that row and start the stream again. After a no, nothing: the watcher does not mention this version again |
 | monitor expired | Start the stream again |
 | `superseded by <pid>` / `stopped by SIGTERM` | Nothing for `superseded`: it is no event, the newer watcher runs. After `stopped by SIGTERM` from outside, start it again |
 | `watcher stopped: <reason>` | Tell the user, fix the cause (an unreadable state file, say), then start it again |
@@ -418,6 +419,25 @@ Every question leaves room for a note: the free answer `AskUserQuestion` offers
 the options cannot express an obvious limit, the question says a note is welcome.
 A note in the answer is read first: it can change or stop the next step.
 
+**Short questions.** A dialog is read at a glance, so it holds the decision and nothing else:
+
+- The question is one sentence, 15 words at most, and asks only the decision. No file path, number or
+  flag in it unless that is the decision itself. The one exception is the PR question, which names
+  ``Branch `<name>` `` because the merge guard reads it back (§ 5).
+- The context comes before it, in the chat: three short lines at most, and only what the decision needs.
+  Details come on request, in the free field of the dialog.
+- An option label has five words at most. Its description has about twelve and says only what the
+  choice leads to. The recommendation stays the first option. The self-merge label of § 5 stays as
+  written.
+- Two or three options, mostly. Several questions in one call only when they are independent; when one
+  depends on another, ask them one after the other.
+
+```text
+Question: Retry the failed check, or leave it?
+- Retry it (recommended): runs the check again
+- Leave it: the pull request waits
+```
+
 **A draft for review.** A lane's draft that the user reviews (a README, a page, a plan) goes in
 rounds. Show it where the user can read it: rendered, when this session can publish a page,
 otherwise the file path. Ask through `AskUserQuestion` with `multiSelect`, one option per remark,
@@ -430,7 +450,7 @@ The push waits for the approval of the last round.
 once: what changed, checks with numbers, open points, the commit message(s). That approval covers
 the commits, the push and opening the PR. The user merges every PR, unless the project supplement
 names PRs the coordinator may merge itself (approval tiers, standing approvals) and under which
-conditions.
+conditions, or the user picked the self-merge option of the PR question (step 2).
 
 A permission dialog inside a lane you confirm yourself only for a step on this list:
 
@@ -453,8 +473,29 @@ included, goes to the user.
    reports "Nothing changed": have the lane run `{{kit.command.typecheck}}` and `{{kit.command.test}}`
    from each package root and the linter on `git diff --name-only origin/{{kit.baseBranch}}...HEAD`
    instead. Never `git reset --soft` to make the runner see the diff.
-2. Summarise for the user and ask with `AskUserQuestion`, once for the PR: what changed, checks,
-   open points, the message(s) as Conventional Commits in English, no AI attribution.
+2. Summarise for the user and ask with `AskUserQuestion`, once for the PR. In the chat before the
+   question: what changed, the checks with numbers and the open points, as three to five bullets;
+   the message(s) as Conventional Commits in English, no AI attribution, go to the lane. The question
+   is one short sentence (§ 4, **Short questions**) that names the lane's branch once, written
+   ``Branch `<name>` ``, and carries three fixed options in this order, labelled in the language the
+   project replies in:
+   - the plain approval: the lane commits, pushes and opens the PR, and the user merges;
+   - `"{{kit.guard.selfMergeLabel}}"`, word for word: the same approval, and the coordinator merges
+     once the checks are green (**Self-merge**, below);
+   - the change: the user names what to alter first.
+
+   ```text
+   Question: Commit, push and open the PR? Branch `fix-login`
+   - Approve, I merge: the lane commits, pushes, opens the PR
+   - "{{kit.guard.selfMergeLabel}}": the same, and the checks decide the merge
+   - Change first: you say what to alter
+   ```
+
+   The self-merge option is **{{kit.guard.selfMerge}}** (`guard.selfMerge.offer` in the config). When
+   it reads `not offered`, or the project supplement blocks self-merge for the PR's tier, leave that
+   option out and ask with the other two. The label is the user's answer and the merge guard reads it
+   back from the session: never reword it, and never write the branch into a question that does not
+   offer the option.
 3. **Acceptance in the browser, before the PR question**, for every lane with a visible change. 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
@@ -470,9 +511,31 @@ included, goes to the user.
    then `cd` back. Not with `-C`: an option between `git` and the verb hides the push from the
    permission rules, and the kit's git guard refuses it.
 
+### Self-merge
+
+When the user picked `"{{kit.guard.selfMergeLabel}}"` for a PR:
+
+1. Commit, push and open the PR as in step 4. Enter in the board's `{{kit.heading.history}}` that the
+   user approved this PR with self-merge (time, lane, PR number), so the approval has a record outside
+   the chat.
+2. Wait for the checks in the background, never in the foreground (§ 4): a Bash call
+   `gh pr checks <n> --watch` with `run_in_background: true`, then work on until it reports.
+3. Green: `gh pr merge <n> --squash --delete-branch`, with the plain PR number and without `-R`,
+   `--repo` or `--admin`. The merge guard lets exactly this command through for the approved branch,
+   for `guard.selfMerge.approvalMinutes` after the answer. Red, or checks that never finish: do not
+   merge, report to the user with the failing check and the lane's next step.
+4. When the guard asks anyway (the approval lapsed, the branch differs, the command carries an
+   option it does not cover), the dialog is the user's. Do not confirm it for them and do not look
+   for a way around it: tell them what the PR waits for.
+5. After the merge, one line to the user (PR, merge commit, checks), then § 6 as for any merge.
+
+Self-merge never covers `gh workflow run` (a release, a deploy) or another PR: each of those asks
+the user every time.
+
 ## 6. Merge and rebase
 
-- **Who merges** is the user unless the project supplement says otherwise (§ 5). Track it with
+- **Who merges** is the user unless the project supplement says otherwise or the user picked
+  self-merge for the PR (§ 5). Track it with
   `gh pr view <n> --json state`.
 - After each merge, tell the remaining lanes to run `git fetch` and then
   `git rebase origin/{{kit.baseBranch}}`, as two commands, and to re-run their checks before they push,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "keywords": [
     "claude-code",
     "coding-agents",

package/schemas/jackherd.schema.json

@@ -451,6 +451,41 @@
       },
       "additionalProperties": false
     },
+    "guard": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "commands": {
+          "default": [
+            "gh pr merge",
+            "gh workflow run"
+          ],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*){1,3}$"
+          }
+        },
+        "selfMerge": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "offer": {
+              "default": true,
+              "type": "boolean"
+            },
+            "approvalMinutes": {
+              "default": 180,
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1440
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "check": {
       "type": "object",
       "properties": {

package/src/config/schema.ts

@@ -187,6 +187,27 @@ const coordinatorSchema = z
   })
   .refine(warnBelowAlert, WARN_BELOW_ALERT)
 
+/** A guarded command as words: a program and one to three plain words after it, never an option, a quote or a shell character. */
+const guardedCommand = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*){1,3}$/, 'a program and one to three plain words, such as gh pr merge')
+
+const guardSchema = z.strictObject({
+  /**
+   * The commands the merge guard hook asks the user about before they run, also behind options before the verb, a chain,
+   * a wrapper or `sh -c`. An empty list switches the guard off.
+   */
+  commands: z.array(guardedCommand).default(['gh pr merge', 'gh workflow run']),
+  selfMerge: z
+    .strictObject({
+      /** Whether `/orchestrate` offers "merge it yourself after green checks" in the pull request question; off also stops the hook honouring such an answer. */
+      offer: z.boolean().default(true),
+      /** How long an answer to that question lets `gh pr merge <number>` pass without asking, counted from the answer. */
+      approvalMinutes: z.number().int().min(1).max(1440).default(180),
+    })
+    .prefault({}),
+})
+
 const contextSchema = z
   .strictObject({
     /** Share of the context window from which a lane's fill shows yellow and `/implement` offers a new chat. */
@@ -279,6 +300,8 @@ export const jackherdConfigSchema = z.strictObject({
       sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
     })
     .prefault({}),
+  /** Read by the merge guard hook, which asks before the listed commands run, and by `/orchestrate`. */
+  guard: guardSchema.prefault({}),
   /** Read by `jh check`; validated here too, so a typo fails every command alike. */
   check: checkConfigSchema.optional(),
 })

package/src/sync/command-context.ts

@@ -7,7 +7,7 @@ import { errorMessage } from './error-message'
 import { linkHerdrPluginFrom } from './herdr-plugin'
 import type { KitSource } from './kit'
 import { type KitLocation, locateKit, readKitSource } from './kit-source'
-import { exitCodeOf, formatReport, SYNC_EXIT } from './report'
+import { driftExitCodeOf, exitCodeOf, formatReport, SYNC_EXIT } from './report'
 import type { SyncResult } from './sync-result'
 import { detectTools, INSTALLERS, type InstallerName, spawnTool, type ToolPresence } from './tools'
 
@@ -86,19 +86,23 @@ export const usageError = (context: CommandContext, message: string): number =>
   return SYNC_EXIT.error
 }
 
-/** Reads the kit, runs the command, prints the report; any thrown error becomes exit code 2. */
+/**
+ * Reads the kit, runs the command, prints the report; any thrown error becomes exit code 2. A `dryRun` writes and links
+ * nothing, and exits 1 when the report lists anything a sync would change.
+ */
 export const runWithKit = async (
   context: CommandContext,
   commandName: string,
   action: (kit: KitSource) => Promise<CommandOutcome>,
+  dryRun = false,
 ): Promise<number> => {
   try {
     const location = await context.locate()
     const { notes, result } = await action(await readKitSource(location))
-    const herdrNote = context.linkHerdrPlugin(location.packageRoot)
+    const herdrNote = dryRun ? null : context.linkHerdrPlugin(location.packageRoot)
     for (const note of herdrNote ? [...notes, herdrNote] : notes) context.log(note)
     context.log(formatReport(result))
-    return exitCodeOf(result)
+    return dryRun ? driftExitCodeOf(result) : exitCodeOf(result)
   } catch (err) {
     context.log(`${CLI_NAME} ${commandName} failed: ${errorMessage(err)}`)
     return SYNC_EXIT.error

package/src/sync/command.ts

@@ -14,18 +14,26 @@ import { migrateGlobalSettings } from './settings-migration'
 import { runGlobalSync, runSync } from './sync'
 
 export type SyncArgs =
-  | { ok: true; accept: string[]; global: boolean; ifChanged: boolean }
+  | { ok: true; accept: string[]; global: boolean; ifChanged: boolean; check: boolean }
   | { ok: false; message: string }
 
 const ACCEPT_FLAG = '--accept'
 const IF_CHANGED_FLAG = '--if-changed'
+const CHECK_FLAG = '--check'
 
-const SYNC_USAGE = `Usage: ${CLI_NAME} sync [--global [${IF_CHANGED_FLAG}]] [--accept <path>]...`
+const SYNC_USAGE = `Usage: ${CLI_NAME} sync [--global [${IF_CHANGED_FLAG}]] [--accept <path>]... | ${CLI_NAME} sync ${CHECK_FLAG}`
+
+const flagConflict = ({ accept, global, ifChanged, check }: Omit<Extract<SyncArgs, { ok: true }>, 'ok'>) => {
+  if (ifChanged && !global) return `${IF_CHANGED_FLAG} goes with ${GLOBAL_FLAG}`
+  if (check && (global || ifChanged || accept.length > 0)) return `${CHECK_FLAG} stands alone: it writes nothing`
+  return undefined
+}
 
 export const parseSyncArgs = (args: string[]): SyncArgs => {
   const accept: string[] = []
   let global = false
   let ifChanged = false
+  let check = false
   for (let i = 0; i < args.length; i++) {
     const arg = args[i]
     if (arg === GLOBAL_FLAG) {
@@ -36,6 +44,10 @@ export const parseSyncArgs = (args: string[]): SyncArgs => {
       ifChanged = true
       continue
     }
+    if (arg === CHECK_FLAG) {
+      check = true
+      continue
+    }
     if (arg.startsWith(`${ACCEPT_FLAG}=`)) {
       accept.push(arg.slice(ACCEPT_FLAG.length + 1))
       continue
@@ -45,8 +57,9 @@ export const parseSyncArgs = (args: string[]): SyncArgs => {
     if (path === undefined) return { ok: false, message: `${ACCEPT_FLAG} needs a path\n${SYNC_USAGE}` }
     accept.push(path)
   }
-  if (ifChanged && !global) return { ok: false, message: `${IF_CHANGED_FLAG} goes with ${GLOBAL_FLAG}\n${SYNC_USAGE}` }
-  return { ok: true, accept, global, ifChanged }
+  const conflict = flagConflict({ accept, global, ifChanged, check })
+  if (conflict) return { ok: false, message: `${conflict}\n${SYNC_USAGE}` }
+  return { ok: true, accept, global, ifChanged, check }
 }
 
 const syncGlobal = (context: CommandContext, accept: string[]): Promise<number> =>
@@ -82,13 +95,18 @@ export const runSyncCommand = async (
 ): Promise<number> => {
   const parsed = parseSyncArgs(args)
   if (!parsed.ok) return usageError(context, parsed.message)
-  const { accept, global, ifChanged } = parsed
+  const { accept, global, ifChanged, check: dryRun } = parsed
   if (ifChanged) return syncGlobalIfChanged(context, accept, check)
   if (global) return syncGlobal(context, accept)
-  return runWithKit(context, 'sync', async (kit) => ({
-    notes: [],
-    result: await runSync({ projectRoot: context.projectRoot, home: context.home, kit, accept }),
-  }))
+  return runWithKit(
+    context,
+    'sync',
+    async (kit) => ({
+      notes: dryRun ? [`${CLI_NAME} sync ${CHECK_FLAG}: nothing is written`] : [],
+      result: await runSync({ projectRoot: context.projectRoot, home: context.home, kit, accept, check: dryRun }),
+    }),
+    dryRun,
+  )
 }
 
 export const run = (args: string[]): Promise<number> => runSyncCommand(args)

package/src/sync/if-changed.ts

@@ -15,6 +15,9 @@ export type UpdateCheck = { now: () => number; latestVersion: () => Promise<stri
 
 export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000
 
+/** How soon npm is asked again after it gave no answer: an hour, so an offline morning does not cost the day. */
+export const UPDATE_RETRY_INTERVAL_MS = 60 * 60 * 1000
+
 const REGISTRY_LATEST = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`
 const REGISTRY_TIMEOUT_MS = 3_000
 const UPDATE_STATE_FILE = 'update-check.json'
@@ -78,22 +81,29 @@ const stampUpdateCheck = async (home: string, now: number): Promise<boolean> =>
   }
 }
 
+/** The stamp that makes the check due again after `UPDATE_RETRY_INTERVAL_MS`, as if npm had been asked that long ago. */
+const retryStampFor = (now: number): number => now - UPDATE_CHECK_INTERVAL_MS + UPDATE_RETRY_INTERVAL_MS
+
 /**
- * The update line, when the daily check is due and npm has a newer release. The check is stamped before npm is
- * asked, so a registry that does not answer is asked again tomorrow, not in every session.
+ * The newest version npm names, when the daily check is due; null when it is not due or npm gave no answer. The
+ * check is stamped before npm is asked, so sessions starting together ask once. An unanswered question is
+ * restamped as if it had been asked `UPDATE_RETRY_INTERVAL_MS` before it is due again: the state file keeps its
+ * one field, and the hook and the watcher share it.
  */
-export const dailyUpdateNotice = async (
-  home: string,
-  installed: string,
-  check: UpdateCheck,
-): Promise<string | null> => {
+export const latestVersionIfDue = async (home: string, check: UpdateCheck): Promise<string | null> => {
   const path = join(home, TOOL_DIRECTORY, UPDATE_STATE_FILE)
   const now = check.now()
   if (!updateCheckDue(await readUpdateState(path), now)) return null
   if (!(await stampUpdateCheck(home, now))) return null
-  return updateNotice(await check.latestVersion(), installed)
+  const latest = await check.latestVersion()
+  if (latest === null) await stampUpdateCheck(home, retryStampFor(now))
+  return latest
 }
 
+/** The update line, when the daily check is due and npm has a newer release. */
+export const dailyUpdateNotice = async (home: string, installed: string, check: UpdateCheck): Promise<string | null> =>
+  updateNotice(await latestVersionIfDue(home, check), installed)
+
 /** Asks the npm registry for the `latest` tag; null on any failure, after a few seconds at most. */
 const registryLatestVersion = async (): Promise<string | null> => {
   try {

package/src/sync/render.ts

@@ -1,5 +1,5 @@
 import type { JackherdConfig } from '../config'
-import { LANGUAGE_NAME, PLAN_VOCABULARY } from '../vocabulary'
+import { LANGUAGE_NAME, PLAN_VOCABULARY, SELF_MERGE_LABEL } from '../vocabulary'
 
 const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
 
@@ -29,6 +29,8 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ['kit.lanes.copyCommand', laneCopyCommand(config.lanes.copy)],
     ['kit.lanes.lockFile', config.lanes.lockFile],
     ...prefixed('board', config.board),
+    ['kit.guard.selfMergeLabel', SELF_MERGE_LABEL[config.responseLanguage]],
+    ['kit.guard.selfMerge', config.guard.selfMerge.offer ? 'offered' : 'not offered'],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
   ])
 }
@@ -40,7 +42,7 @@ export const listPlaceholders = (template: string): string[] =>
 /**
  * Fills the kit placeholders from the project config: `{{kit.model.<role>}}`,
  * `{{kit.command.<test|typecheck|lint|format|install|dev>}}`, `{{kit.lanes.<copyCommand|lockFile>}}`,
- * `{{kit.board.<pattern|file|term>}}`, `{{kit.heading.<key>}}` from the plan
+ * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.heading.<key>}}` from the plan
  * vocabulary, the two languages, the plan and worktree directory and the base branch. Other
  * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project
  * file unrendered. `overrides` win over the config: a global kit renders what each repository decides as

package/src/sync/report.ts

@@ -15,6 +15,21 @@ const NEEDS_ATTENTION: readonly Outcome[] = [
   HOOK_OUTCOME.blocked,
 ]
 
+/** What a sync would write into the files or hooks, or could not: a project copy that no longer equals the kit. */
+const DRIFT: readonly Outcome[] = [
+  ...NEEDS_ATTENTION,
+  FILE_OUTCOME.created,
+  FILE_OUTCOME.updated,
+  FILE_OUTCOME.removed,
+  FILE_OUTCOME.accepted,
+  FILE_OUTCOME.resolved,
+  HOOK_OUTCOME.created,
+  HOOK_OUTCOME.updated,
+  HOOK_OUTCOME.removed,
+  HOOK_OUTCOME.accepted,
+  HOOK_OUTCOME.resolved,
+]
+
 const COUNTED: readonly Outcome[] = [
   FILE_OUTCOME.created,
   FILE_OUTCOME.updated,
@@ -68,6 +83,12 @@ export const exitCodeOf = (result: SyncResult): number => {
   return outcomes.some((outcome) => NEEDS_ATTENTION.includes(outcome)) ? SYNC_EXIT.conflicts : SYNC_EXIT.clean
 }
 
+/** The exit code of `sync --check`: 1 when a sync would change anything, so a check can fail on it. */
+export const driftExitCodeOf = (result: SyncResult): number => {
+  const outcomes = [...result.files, ...result.hooks].map(({ outcome }) => outcome)
+  return outcomes.some((outcome) => DRIFT.includes(outcome)) ? SYNC_EXIT.conflicts : SYNC_EXIT.clean
+}
+
 const summaryLine = (outcomes: Outcome[]): string => {
   const counts = COUNTED.map((outcome) => ({ outcome, count: outcomes.filter((each) => each === outcome).length }))
   const nonZero = counts.filter(({ count }) => count > 0)

package/src/sync/settings-migration.ts

@@ -7,6 +7,8 @@ import {
   isObject,
   readSettingsOffer,
   SESSION_HOOK_COMMAND,
+  SESSION_HOOK_MATCHER,
+  SESSION_START,
   type SettingsObject,
   type SettingsOffer,
 } from './settings-offer'
@@ -41,7 +43,7 @@ const migrateGroup = (group: unknown): unknown =>
 
 const sessionStartOf = (settings: SettingsObject): unknown[] | null => {
   const hooks = settings.hooks
-  return isObject(hooks) && Array.isArray(hooks.SessionStart) ? hooks.SessionStart : null
+  return isObject(hooks) && Array.isArray(hooks[SESSION_START]) ? hooks[SESSION_START] : null
 }
 
 /** Our `SessionStart` hook as the old CLI ran it becomes the `jh` command; every other event, group and handler stays. */
@@ -53,7 +55,42 @@ export const LEGACY_HOOK_MIGRATION: SettingsOffer = {
     if (JSON.stringify(migrated) === JSON.stringify(groups)) return { kind: 'present' }
     return {
       kind: 'add',
-      next: { ...settings, hooks: { ...(settings.hooks as SettingsObject), SessionStart: migrated } },
+      next: { ...settings, hooks: { ...(settings.hooks as SettingsObject), [SESSION_START]: migrated } },
+    }
+  },
+}
+
+/** The matcher older installs wrote: the hook ran at `startup` only, so a `/clear` handover never saw its line. */
+export const LEGACY_SESSION_HOOK_MATCHER = 'startup'
+
+const sameKeys = (value: SettingsObject, keys: readonly string[]): boolean =>
+  Object.keys(value).sort().join() === [...keys].sort().join()
+
+/** Exactly the group an older install wrote: the `startup` matcher and our one handler, nothing else on either. */
+const isLegacyMatcherGroup = (group: unknown): boolean => {
+  if (!isObject(group) || !sameKeys(group, ['matcher', 'hooks'])) return false
+  if (group.matcher !== LEGACY_SESSION_HOOK_MATCHER || !Array.isArray(group.hooks) || group.hooks.length !== 1)
+    return false
+  const [handler] = group.hooks
+  return (
+    isObject(handler) &&
+    sameKeys(handler, ['type', 'command']) &&
+    handler.type === 'command' &&
+    handler.command === SESSION_HOOK_COMMAND
+  )
+}
+
+/** Our `SessionStart` hook written for `startup` only also runs after `resume`, `clear` and `compact`; any other group stays. */
+export const SESSION_MATCHER_MIGRATION: SettingsOffer = {
+  find: (settings) => {
+    const groups = sessionStartOf(settings)
+    if (!groups?.some(isLegacyMatcherGroup)) return { kind: 'present' }
+    const widened = groups.map((group) =>
+      isLegacyMatcherGroup(group) ? { ...(group as SettingsObject), matcher: SESSION_HOOK_MATCHER } : group,
+    )
+    return {
+      kind: 'add',
+      next: { ...settings, hooks: { ...(settings.hooks as SettingsObject), [SESSION_START]: widened } },
     }
   },
 }
@@ -90,5 +127,10 @@ export const migrateGlobalSettings = async (home: string, cliOnPath: boolean): P
           `Changed the SessionStart hook in ${SHOWN_SETTINGS} to \`${SESSION_HOOK_COMMAND}\`.`,
         )
       : HOOK_WAITS
-  return [statusLine, hook].filter((line): line is string => line !== null)
+  const matcher = await migrate(
+    path,
+    SESSION_MATCHER_MIGRATION,
+    `Widened the SessionStart hook in ${SHOWN_SETTINGS} to startup, resume, clear and compact.`,
+  )
+  return [statusLine, hook, matcher].filter((line): line is string => line !== null)
 }

package/src/sync/settings-offer.ts

@@ -29,9 +29,15 @@ export type SettingsWrite = { kind: 'written' } | { kind: 'notWritten'; reason:
 /** What the `SessionStart` hook runs: a global sync only when the installed kit changed. */
 export const SESSION_HOOK_COMMAND = `${CLI_NAME} sync --global --if-changed`
 
-const SESSION_START = 'SessionStart'
+export const SESSION_START = 'SessionStart'
 
-const SESSION_HOOK_GROUP = { matcher: 'startup', hooks: [{ type: 'command', command: SESSION_HOOK_COMMAND }] }
+/** Every way a session starts; the daily timestamp makes the extra runs free. */
+export const SESSION_HOOK_MATCHER = 'startup|resume|clear|compact'
+
+const SESSION_HOOK_GROUP = {
+  matcher: SESSION_HOOK_MATCHER,
+  hooks: [{ type: 'command', command: SESSION_HOOK_COMMAND }],
+}
 
 /** Claude Code creates `settings.json` world-readable; an existing file keeps its own mode. */
 const NEW_FILE_MODE = 0o644

package/src/sync/sync.ts

@@ -50,6 +50,8 @@ export type SyncRequest = {
   accept: string[]
   /** What fills the values the config leaves out; read from the project root when absent. */
   facts?: RepositoryFacts
+  /** Plan and report, write nothing: the result says what a sync would do. */
+  check?: boolean
 }
 
 export type GlobalSyncRequest = {
@@ -253,7 +255,7 @@ export const syncProjectWithConfig = async (request: SyncRequest): Promise<Confi
   await assertOwnDirectoriesInProject(request.projectRoot)
   const claudeDirectory = join(request.projectRoot, CLAUDE_DIRECTORY)
   const toolDirectory = join(request.projectRoot, TOOL_DIRECTORY)
-  const moved = await moveProjectLegacyFiles(request.projectRoot)
+  const moved = request.check ? [] : await moveProjectLegacyFiles(request.projectRoot)
   const facts = request.facts ?? readRepositoryFacts(request.projectRoot)
   const { config, notes } = await readConfig(toolDirectory, TOOL_DIRECTORY, `${CLI_NAME} init`, facts)
   const directories = { claudeDirectory, toolDirectory, locate: inClaudeDirectory(claudeDirectory) }
@@ -264,8 +266,10 @@ export const syncProjectWithConfig = async (request: SyncRequest): Promise<Confi
     accept: request.accept,
     readHooks: projectHooks(claudeDirectory, request.kit, config),
   })
-  await applyPlan(directories, plan)
-  await ensureGitignoreLines(request.projectRoot)
+  if (!request.check) {
+    await applyPlan(directories, plan)
+    await ensureGitignoreLines(request.projectRoot)
+  }
   return { result: { ...syncResultOf(plan), notes: [...moved, ...notes] }, config }
 }
 

package/src/vocabulary/index.ts

@@ -8,6 +8,16 @@ export const LANGUAGE_NAME: Record<PlanLanguage, string> = {
   [PLAN_LANGUAGE.de]: 'German',
 }
 
+/**
+ * The option of the pull request question that approves the PR and a merge by the coordinator once the checks are
+ * green. The merge guard hook matches the user's answer against this exact text, so it is fixed per language and not
+ * a config value.
+ */
+export const SELF_MERGE_LABEL: Record<PlanLanguage, string> = {
+  [PLAN_LANGUAGE.en]: 'Approve, and merge it yourself after green checks',
+  [PLAN_LANGUAGE.de]: 'Freigeben, und nach grünen Checks selbst mergen',
+}
+
 export const isPlanLanguage = (value: string): value is PlanLanguage =>
   (Object.values(PLAN_LANGUAGE) as string[]).includes(value)
 

package/src/watch/command.ts

@@ -6,7 +6,8 @@
  * with `watch.sources`), a gh outage, a lane's or the coordinator's own context fill rising to warn or alert, or the
  * heartbeat. A blocked lane adds one duty line, a merge one per lane, a lane at alert one, and every report ends with one status line
  * per lane and one for the coordinator, in the words of `responseLanguage`. When the installed kit changes version
- * it prints `=== kit updated <old> → <new>` and ends. The coordinator is the agent in the
+ * it prints `=== kit updated <old> → <new>` and ends; once a day it asks npm and prints `=== update available <old> → <new>`
+ * for a newer release, once per version. The coordinator is the agent in the
  * watcher's own herdr pane unless `--coordinator` names it, else `orchestrator-<repository>`. A new start replaces a running watcher of the same
  * repository; one in another repository keeps running.
  *
@@ -26,6 +27,7 @@
  *   jh watch source <name|draft.json|-> --dry-run
  */
 import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
 import { basename, dirname, join, relative } from 'node:path'
 import { readResolvedConfig } from '../config/read-config'
 import type { JackherdConfig } from '../config/schema'
@@ -42,6 +44,7 @@ import { mainCheckout, worktreeNames, worktreeRoot } from '../plans/git'
 import { discoverLanes, isUnchanged, laneSetChange, laneSetLines } from '../plans/lane-discovery'
 import { clockLocaleOf, type PlansSettings, plansSettingsOf, worktreeOf } from '../plans/settings'
 import { boardTexts } from '../plans/texts'
+import { defaultUpdateCheck } from '../sync/if-changed'
 import { herdrLaneStatusSource } from '../terminal/herdr'
 import { startedKit } from '../version/started-kit'
 import {
@@ -135,6 +138,7 @@ import {
 } from './sources'
 import { streamHeartbeatLine } from './stream-output'
 import { WATCH_TEXTS, type WatchTexts } from './texts'
+import { updateAnnouncer } from './update-available'
 import {
   coordinatorWatchEvent,
   deployEvents,
@@ -846,9 +850,11 @@ const watchLanes = async (watch: Watch) => {
   const kit = await startedKit()
   const skillSnapshot = kit ? readOrchestrateSkill(kit.packageRoot) : null
   const skillLine = () => skillLineFor(kit, skillSnapshot, dirname(watch.files.state))
+  const announceUpdate = kit ? updateAnnouncer(homedir(), kit.version, defaultUpdateCheck(), console.log) : null
   while (await pollOnce(watch, watching)) {
     await Bun.sleep(POLL_MS)
     pollLanes(watch, watching)
+    await announceUpdate?.()
     if (endedByKitUpdate(kit, { saveState: () => saveState(watch, watching), log: console.log, skillLine })) return
   }
 }

package/src/watch/report-questions.ts

@@ -7,6 +7,9 @@ const ANY_HEADING = /^(#{1,6})\s/
 const CODE_FENCE = /^\s*(```|~~~)/
 const LIST_ITEM = /^(?:\d+[.)]|[-*])\s/
 const CONTINUATION_LINE = /^\s/
+const LIST_MARKER = /^(?:\d+[.)]|[-*])\s*/
+/** What a section writes when it has nothing to ask: "Keine.", "None.", "Keine offenen Fragen.", a dash. */
+const NO_QUESTIONS = /^(?:(?:keine|none|no|nein)(?:\s+(?:offenen\s+)?(?:fragen?|questions?))?\.?|n\/a|[—–])$/i
 
 /** What the questions part of a message may take: whole up to these limits, else cut question by question. */
 const QUESTION_LINES = 20
@@ -24,13 +27,24 @@ const headings = (lines: readonly string[]): { index: number; level: number; isQ
   })
 }
 
-/** The questions sections of a report, in order: from the heading to the next heading of the same or a higher level. */
+/** True when every line of the body, ignoring blank lines, a list marker and bold, says there is nothing to ask. */
+const asksNothing = (body: readonly string[]): boolean =>
+  body
+    .map((line) => line.trim().replace(LIST_MARKER, '').replaceAll('**', '').trim())
+    .filter((text) => text !== '')
+    .every((text) => NO_QUESTIONS.test(text))
+
+/**
+ * The questions sections of a report, in order: from the heading to the next heading of the same or a higher level.
+ * A section that is empty or only says "Keine." / "None." asks nothing and is left out.
+ */
 export const questionSections = (lines: readonly string[]): QuestionSection[] => {
   const all = headings(lines)
   return all.flatMap((heading, position) => {
     if (!heading.isQuestion) return []
     const next = all.slice(position + 1).find((other) => other.level <= heading.level)
-    return [{ start: heading.index, end: next?.index ?? lines.length }]
+    const end = next?.index ?? lines.length
+    return asksNothing(lines.slice(heading.index + 1, end)) ? [] : [{ start: heading.index, end }]
   })
 }