jackherd 1.13.0 → 1.15.0

package/docs/skills-dark.svg

@@ -1,5 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="960" height="530" viewBox="0 0 960 530" role="img" aria-labelledby="t d"><title id="t">The skills and what they hand on</title><desc id="d">/jh-grill hands decision rows to /jh-plan. /jh-plan feeds /jh-orchestrate with phases, Writes sets and a model per phase, or a single phase to /jh-implement; under /jh-orchestrate each lane runs /jh-implement. /jh-implement ends in /jh-pre-commit, which runs jh check, /jh-review, the jh-spec-review agent against the plan, and the reviewers routed by path: /jh-uncle-bob, /jh-security-audit, /jh-devops. /jh-diagnose hands a red command to /jh-implement.</desc><defs><style>.s{font-family:ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif}.m{font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace}</style></defs>
-<rect x="1" y="1" width="958" height="528" rx="18" fill="#151D22" stroke="#34434B" stroke-width="1.5"/>
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="600" viewBox="0 0 960 600" role="img" aria-labelledby="t d"><title id="t">The skills and what they hand on</title><desc id="d">A plan of your own or an issue is adopted: Jack adds what is missing, shows you the diff and hands it to /jh-orchestrate. /jh-grill hands decision rows to /jh-plan. /jh-plan feeds /jh-orchestrate with phases, Writes sets and a model per phase, or a single phase to /jh-implement, which your own skill can replace; under /jh-orchestrate each lane runs /jh-implement or your own skill. /jh-implement ends in /jh-pre-commit, which runs jh check, /jh-review, the jh-spec-review agent against the plan, and the reviewers routed by path: /jh-uncle-bob, /jh-security-audit, /jh-devops. /jh-diagnose hands a red command to /jh-implement.</desc><defs><style>.s{font-family:ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif}.m{font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace}</style></defs>
+<rect x="1" y="1" width="958" height="598" rx="18" fill="#151D22" stroke="#34434B" stroke-width="1.5"/>
+<g transform="translate(0 70)">
 <path d="M120 103.5 125.3 103.4 130.4 103.3 135.4 103.3 140.3 103.2 145.1 103.1 149.8 103 154.5 103 159 102.9 163.5 102.8 168 102.7 172.5 102.6 176.9 102.6 181.3 102.5 185.8 102.4 190.2 102.3 194.7 102.2 199.2 102.2 203.9 102.1 208.5 102 213.3 101.9 218.2 101.8 223.1 101.8 228.2 101.7 233.5 101.6 238.8 101.5 244.4 101.5 250.1 101.4 256 101.3 A1.3 1.3 0 0 1 256 98.7 L256 98.7 250.1 98.6 244.4 98.5 238.8 98.5 233.5 98.4 228.2 98.3 223.1 98.2 218.2 98.2 213.3 98.1 208.5 98 203.9 97.9 199.2 97.8 194.7 97.8 190.2 97.7 185.8 97.6 181.3 97.5 176.9 97.4 172.5 97.4 168 97.3 163.5 97.2 159 97.1 154.5 97 149.8 97 145.1 96.9 140.3 96.8 135.4 96.7 130.4 96.7 125.3 96.6 120 96.5 A3.5 3.5 0 0 1 120 103.5Z" fill="#21BEC5"/>
 <path d="M249.2 106L257.2 100L249.2 94" fill="none" stroke="#21BEC5" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
 <path d="M320 103.5 325.3 103.4 330.6 103.3 335.8 103.3 340.9 103.2 346 103.1 351 103 356 103 361 102.9 366 102.8 370.9 102.7 375.9 102.6 380.8 102.6 385.8 102.5 390.8 102.4 395.7 102.3 400.8 102.2 405.8 102.2 410.9 102.1 416.1 102 421.3 101.9 426.6 101.8 431.9 101.8 437.4 101.7 442.9 101.6 448.5 101.5 454.2 101.5 460.1 101.4 466 101.3 A1.3 1.3 0 0 1 466 98.7 L466 98.7 460.1 98.6 454.2 98.5 448.5 98.5 442.9 98.4 437.4 98.3 431.9 98.2 426.6 98.2 421.3 98.1 416.1 98 410.9 97.9 405.8 97.8 400.8 97.8 395.7 97.7 390.8 97.6 385.8 97.5 380.8 97.4 375.9 97.4 370.9 97.3 366 97.2 361 97.1 356 97 351 97 346 96.9 340.9 96.8 335.8 96.7 330.6 96.7 325.3 96.6 320 96.5 A3.5 3.5 0 0 1 320 103.5Z" fill="#21BEC5"/>
@@ -44,6 +45,7 @@
 <text x="532" y="114" class="s" font-size="12.5" fill="#9B9D9E" text-anchor="start">lanes in herdr</text>
 <text x="500" y="340" class="m" font-size="14" fill="#E6EDF3" font-weight="700" text-anchor="middle">/jh-implement</text>
 <text x="500" y="358" class="s" font-size="12.5" fill="#9B9D9E" text-anchor="middle">builds, ticks</text>
+<text x="500" y="382" class="s" font-size="12.5" fill="#9B9D9E" text-anchor="middle" font-style="italic">or your own skill</text>
 <text x="700" y="340" class="m" font-size="14" fill="#E6EDF3" font-weight="700" text-anchor="middle">/jh-pre-commit</text>
 <text x="700" y="358" class="s" font-size="12.5" fill="#9B9D9E" text-anchor="middle">jh check</text>
 <text x="880" y="200" class="m" font-size="14" fill="#E6EDF3" font-weight="700" text-anchor="middle">/jh-review</text>
@@ -62,4 +64,15 @@
 <text x="788" y="392" class="s" font-size="12.5" fill="#9B9D9E" text-anchor="end" font-style="italic">routed</text>
 <text x="788" y="408" class="s" font-size="12.5" fill="#9B9D9E" text-anchor="end" font-style="italic">by path</text>
 <text x="420" y="420" class="s" font-size="12.5" fill="#9B9D9E" text-anchor="start" font-style="italic">red command</text>
+</g>
+<text x="290" y="48" class="s" font-size="13" fill="#E6EDF3" font-weight="600" text-anchor="middle">your own plan</text>
+<text x="290" y="66" class="s" font-size="13" fill="#E6EDF3" font-weight="600" text-anchor="middle">or an issue</text>
+<path d="M350 52C400 52 440 52 466 52" fill="none" stroke="#7E8A90" stroke-width="2.6" stroke-linecap="round" stroke-dasharray="0.1 7"/>
+<path d="M459.2 58L467.2 52L459.2 46" fill="none" stroke="#7E8A90" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M496.5 82 496.6 84.9 496.7 87.7 496.7 90.4 496.8 93 496.9 95.4 497 97.8 497.1 100 497.1 102.2 497.2 104.2 497.3 106.2 497.4 108.1 497.4 110 497.5 111.8 497.6 113.5 497.7 115.2 497.8 116.8 497.8 118.5 497.9 120.1 498 121.6 498.1 123.2 498.1 124.8 498.2 126.3 498.3 127.9 498.4 129.4 498.5 131 498.5 132.7 498.6 134.3 498.7 136 A1.3 1.3 0 0 1 501.3 136 L501.3 136 501.4 134.3 501.5 132.7 501.5 131 501.6 129.4 501.7 127.9 501.8 126.3 501.9 124.8 501.9 123.2 502 121.6 502.1 120.1 502.2 118.5 502.2 116.8 502.3 115.2 502.4 113.5 502.5 111.8 502.6 110 502.6 108.1 502.7 106.2 502.8 104.2 502.9 102.2 502.9 100 503 97.8 503.1 95.4 503.2 93 503.3 90.4 503.3 87.7 503.4 84.9 503.5 82 A3.5 3.5 0 0 1 496.5 82Z" fill="#21BEC5"/>
+<path d="M494 129.2L500 137.2L506 129.2" fill="none" stroke="#21BEC5" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+<ellipse cx="500" cy="82.0" rx="28.0" ry="3.5" fill="#BCC5CA" opacity="0.12"/>
+<rect x="476" y="28" width="48" height="48" rx="9.6" fill="#212E34" stroke="#5B6B73" stroke-width="1.9"/><circle cx="500" cy="52" r="9.1" fill="#21BEC5"/>
+<text x="532" y="48" class="m" font-size="14" fill="#E6EDF3" font-weight="700" text-anchor="start">adopt</text>
+<text x="532" y="66" class="s" font-size="12.5" fill="#9B9D9E" text-anchor="start">adds what is missing, shows you the diff</text>
 </svg>

package/docs/skills.svg

@@ -1,5 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="960" height="530" viewBox="0 0 960 530" role="img" aria-labelledby="t d"><title id="t">The skills and what they hand on</title><desc id="d">/jh-grill hands decision rows to /jh-plan. /jh-plan feeds /jh-orchestrate with phases, Writes sets and a model per phase, or a single phase to /jh-implement; under /jh-orchestrate each lane runs /jh-implement. /jh-implement ends in /jh-pre-commit, which runs jh check, /jh-review, the jh-spec-review agent against the plan, and the reviewers routed by path: /jh-uncle-bob, /jh-security-audit, /jh-devops. /jh-diagnose hands a red command to /jh-implement.</desc><defs><style>.s{font-family:ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif}.m{font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace}</style></defs>
-<rect x="1" y="1" width="958" height="528" rx="18" fill="#FAF9F8" stroke="#C4CBCE" stroke-width="1.5"/>
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="600" viewBox="0 0 960 600" role="img" aria-labelledby="t d"><title id="t">The skills and what they hand on</title><desc id="d">A plan of your own or an issue is adopted: Jack adds what is missing, shows you the diff and hands it to /jh-orchestrate. /jh-grill hands decision rows to /jh-plan. /jh-plan feeds /jh-orchestrate with phases, Writes sets and a model per phase, or a single phase to /jh-implement, which your own skill can replace; under /jh-orchestrate each lane runs /jh-implement or your own skill. /jh-implement ends in /jh-pre-commit, which runs jh check, /jh-review, the jh-spec-review agent against the plan, and the reviewers routed by path: /jh-uncle-bob, /jh-security-audit, /jh-devops. /jh-diagnose hands a red command to /jh-implement.</desc><defs><style>.s{font-family:ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif}.m{font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace}</style></defs>
+<rect x="1" y="1" width="958" height="598" rx="18" fill="#FAF9F8" stroke="#C4CBCE" stroke-width="1.5"/>
+<g transform="translate(0 70)">
 <path d="M120 103.5 125.3 103.4 130.4 103.3 135.4 103.3 140.3 103.2 145.1 103.1 149.8 103 154.5 103 159 102.9 163.5 102.8 168 102.7 172.5 102.6 176.9 102.6 181.3 102.5 185.8 102.4 190.2 102.3 194.7 102.2 199.2 102.2 203.9 102.1 208.5 102 213.3 101.9 218.2 101.8 223.1 101.8 228.2 101.7 233.5 101.6 238.8 101.5 244.4 101.5 250.1 101.4 256 101.3 A1.3 1.3 0 0 1 256 98.7 L256 98.7 250.1 98.6 244.4 98.5 238.8 98.5 233.5 98.4 228.2 98.3 223.1 98.2 218.2 98.2 213.3 98.1 208.5 98 203.9 97.9 199.2 97.8 194.7 97.8 190.2 97.7 185.8 97.6 181.3 97.5 176.9 97.4 172.5 97.4 168 97.3 163.5 97.2 159 97.1 154.5 97 149.8 97 145.1 96.9 140.3 96.8 135.4 96.7 130.4 96.7 125.3 96.6 120 96.5 A3.5 3.5 0 0 1 120 103.5Z" fill="#03B5BD"/>
 <path d="M249.2 106L257.2 100L249.2 94" fill="none" stroke="#03B5BD" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
 <path d="M320 103.5 325.3 103.4 330.6 103.3 335.8 103.3 340.9 103.2 346 103.1 351 103 356 103 361 102.9 366 102.8 370.9 102.7 375.9 102.6 380.8 102.6 385.8 102.5 390.8 102.4 395.7 102.3 400.8 102.2 405.8 102.2 410.9 102.1 416.1 102 421.3 101.9 426.6 101.8 431.9 101.8 437.4 101.7 442.9 101.6 448.5 101.5 454.2 101.5 460.1 101.4 466 101.3 A1.3 1.3 0 0 1 466 98.7 L466 98.7 460.1 98.6 454.2 98.5 448.5 98.5 442.9 98.4 437.4 98.3 431.9 98.2 426.6 98.2 421.3 98.1 416.1 98 410.9 97.9 405.8 97.8 400.8 97.8 395.7 97.7 390.8 97.6 385.8 97.5 380.8 97.4 375.9 97.4 370.9 97.3 366 97.2 361 97.1 356 97 351 97 346 96.9 340.9 96.8 335.8 96.7 330.6 96.7 325.3 96.6 320 96.5 A3.5 3.5 0 0 1 320 103.5Z" fill="#03B5BD"/>
@@ -44,6 +45,7 @@
 <text x="532" y="114" class="s" font-size="12.5" fill="#4A4E51" text-anchor="start">lanes in herdr</text>
 <text x="500" y="340" class="m" font-size="14" fill="#212E34" font-weight="700" text-anchor="middle">/jh-implement</text>
 <text x="500" y="358" class="s" font-size="12.5" fill="#4A4E51" text-anchor="middle">builds, ticks</text>
+<text x="500" y="382" class="s" font-size="12.5" fill="#4A4E51" text-anchor="middle" font-style="italic">or your own skill</text>
 <text x="700" y="340" class="m" font-size="14" fill="#212E34" font-weight="700" text-anchor="middle">/jh-pre-commit</text>
 <text x="700" y="358" class="s" font-size="12.5" fill="#4A4E51" text-anchor="middle">jh check</text>
 <text x="880" y="200" class="m" font-size="14" fill="#212E34" font-weight="700" text-anchor="middle">/jh-review</text>
@@ -62,4 +64,15 @@
 <text x="788" y="392" class="s" font-size="12.5" fill="#4A4E51" text-anchor="end" font-style="italic">routed</text>
 <text x="788" y="408" class="s" font-size="12.5" fill="#4A4E51" text-anchor="end" font-style="italic">by path</text>
 <text x="420" y="420" class="s" font-size="12.5" fill="#4A4E51" text-anchor="start" font-style="italic">red command</text>
+</g>
+<text x="290" y="48" class="s" font-size="13" fill="#212E34" font-weight="600" text-anchor="middle">your own plan</text>
+<text x="290" y="66" class="s" font-size="13" fill="#212E34" font-weight="600" text-anchor="middle">or an issue</text>
+<path d="M350 52C400 52 440 52 466 52" fill="none" stroke="#7E8487" stroke-width="2.6" stroke-linecap="round" stroke-dasharray="0.1 7"/>
+<path d="M459.2 58L467.2 52L459.2 46" fill="none" stroke="#7E8487" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M496.5 82 496.6 84.9 496.7 87.7 496.7 90.4 496.8 93 496.9 95.4 497 97.8 497.1 100 497.1 102.2 497.2 104.2 497.3 106.2 497.4 108.1 497.4 110 497.5 111.8 497.6 113.5 497.7 115.2 497.8 116.8 497.8 118.5 497.9 120.1 498 121.6 498.1 123.2 498.1 124.8 498.2 126.3 498.3 127.9 498.4 129.4 498.5 131 498.5 132.7 498.6 134.3 498.7 136 A1.3 1.3 0 0 1 501.3 136 L501.3 136 501.4 134.3 501.5 132.7 501.5 131 501.6 129.4 501.7 127.9 501.8 126.3 501.9 124.8 501.9 123.2 502 121.6 502.1 120.1 502.2 118.5 502.2 116.8 502.3 115.2 502.4 113.5 502.5 111.8 502.6 110 502.6 108.1 502.7 106.2 502.8 104.2 502.9 102.2 502.9 100 503 97.8 503.1 95.4 503.2 93 503.3 90.4 503.3 87.7 503.4 84.9 503.5 82 A3.5 3.5 0 0 1 496.5 82Z" fill="#03B5BD"/>
+<path d="M494 129.2L500 137.2L506 129.2" fill="none" stroke="#03B5BD" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"/>
+<ellipse cx="500" cy="82.0" rx="28.0" ry="3.5" fill="#BCC5CA" opacity="0.55"/>
+<rect x="476" y="28" width="48" height="48" rx="9.6" fill="#212E34"/><circle cx="500" cy="52" r="9.1" fill="#03B5BD"/>
+<text x="532" y="48" class="m" font-size="14" fill="#212E34" font-weight="700" text-anchor="start">adopt</text>
+<text x="532" y="66" class="s" font-size="12.5" fill="#4A4E51" text-anchor="start">adds what is missing, shows you the diff</text>
 </svg>

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.13.0"
+version = "1.15.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/herdr-plugin/restore-plans.ts

@@ -7,11 +7,13 @@ type Limits = { attempts: number; intervalMs: number }
  * Measured on herdr 0.9.0: the hook starts ~85 ms after the server, `pane process-info` answers
  * `pane_not_found` until the terminals spawn at ~0.9 s, and the agents are back at ~3 s. The panes get 10 s, ten
  * times what they took; `herd --ensure` gets four tries 2 s apart, past the ~3 s of the agents, for a pane that
- * goes away between the two reads.
+ * goes away between the two reads. The coordinator gets a minute: after a crash its session was still not back after
+ * ~8 s, and the herd beside it stayed missing.
  */
 export const RESTORE_LIMITS = {
   panes: { attempts: 20, intervalMs: 500 },
   ensure: { attempts: 4, intervalMs: 2_000 },
+  coordinator: { attempts: 30, intervalMs: 2_000 },
 } as const satisfies Record<string, Limits>
 
 /** Runs `attempt` until it works or the attempts are used up, waiting the interval between two of them. */
@@ -23,6 +25,31 @@ export const retried = (attempt: () => boolean, limits: Limits, sleep: (ms: numb
   }
 }
 
+/**
+ * Waits for every item in one shared window of `limits`, calls `onReady` for each as soon as `isReady` holds, and
+ * returns the items that never got ready.
+ */
+export const awaitEach = <T>(
+  items: readonly T[],
+  isReady: (item: T) => boolean,
+  onReady: (item: T) => void,
+  limits: Limits,
+  sleep: (ms: number) => void,
+): T[] => {
+  let pending = [...items]
+  retried(
+    () => {
+      const ready = pending.filter(isReady)
+      for (const item of ready) onReady(item)
+      pending = pending.filter((item) => !ready.includes(item))
+      return pending.length === 0
+    },
+    limits,
+    sleep,
+  )
+  return pending
+}
+
 /**
  * The directories of the panes an agent runs in, each once, from a `herdr pane list` answer; none when unreadable.
  * `agentPanes` are the panes of `herdr agent list`: right after a restart the pane list names no agent there for a
@@ -43,6 +70,10 @@ export const agentDirectoriesOf = (json: string, agentPanes: readonly string[]):
   }
 }
 
+/** Whether an agent runs in `root` itself, where the coordinator works, rather than only in its lanes' worktrees. */
+export const hasAgentIn = (root: string, paneList: string, agentPanes: readonly string[]): boolean =>
+  agentDirectoriesOf(paneList, agentPanes).includes(root)
+
 /** The arguments for `bun` that run `herd --ensure` with the CLI of the package this plugin ships in. */
 export const ensureArguments = (pluginRoot: string): string[] => [
   join(dirname(pluginRoot), 'src', 'cli.ts'),
@@ -80,13 +111,33 @@ const panesAnswer = (panes: readonly string[]): boolean =>
 const ensureIn = (root: string, pluginRoot: string): boolean =>
   spawnSync('bun', ensureArguments(pluginRoot), { cwd: root, stdio: 'inherit' }).status === 0
 
+const coordinatorBackIn = (root: string): boolean =>
+  hasAgentIn(root, herdrRun(['pane', 'list']).stdout ?? '', idsOf(herdrRun(['agent', 'list']).stdout ?? '', 'agents'))
+
+const ensureWithRetries = (root: string, sleep: (ms: number) => void) => {
+  if (!retried(() => ensureIn(root, import.meta.dir), RESTORE_LIMITS.ensure, sleep))
+    console.error(`restore-plans: herd --ensure failed in ${root}`)
+}
+
+/**
+ * The herd beside each coordinator once its session is back, which can take longer than the lanes'. A coordinator
+ * already back had its herd from the first `--ensure`; the others share one waiting window.
+ */
+const ensureCoordinators = (roots: readonly string[], sleep: (ms: number) => void) => {
+  const missing = roots.filter((root) => !coordinatorBackIn(root))
+  const ensure = (root: string) => ensureWithRetries(root, sleep)
+  for (const root of awaitEach(missing, coordinatorBackIn, ensure, RESTORE_LIMITS.coordinator, sleep))
+    console.error(`restore-plans: no coordinator came back in ${root}`)
+}
+
 /**
  * herdr's `[[startup]]` hook: after a server start or a live handoff, brings back the herd panes of every
  * repository an agent runs in. It parses herdr's answers itself and never throws, unlike the strict parsers of
  * `src/plans/plan-panes.ts`: a hook that fails leaves nothing behind but a log line, and `herd --ensure`, which it
  * calls, reads the panes again strictly. It reads the panes at once, while herdr still names their agents, then waits until
- * herdr answers for every pane and retries `herd --ensure` within `RESTORE_LIMITS`. A repository without a board
- * or config only prints why and is skipped.
+ * herdr answers for every pane and retries `herd --ensure` within `RESTORE_LIMITS`. A repository whose coordinator
+ * is not back yet gets one more `herd --ensure` once an agent runs in its main checkout. A repository without a
+ * board or config only prints why and is skipped.
  */
 const main = (): number => {
   const list = herdrRun(['pane', 'list'])
@@ -98,9 +149,8 @@ const main = (): number => {
   const sleep = (ms: number) => Bun.sleepSync(ms)
   if (!retried(() => panesAnswer(idsOf(listing, 'panes')), RESTORE_LIMITS.panes, sleep))
     console.error('restore-plans: herdr did not answer for every pane in time, trying anyway')
-  for (const root of roots)
-    if (!retried(() => ensureIn(root, import.meta.dir), RESTORE_LIMITS.ensure, sleep))
-      console.error(`restore-plans: herd --ensure failed in ${root}`)
+  for (const root of roots) ensureWithRetries(root, sleep)
+  ensureCoordinators([...roots], sleep)
   return 0
 }
 

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.13.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.15.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/merge-guard/board-settings.ts

@@ -39,8 +39,11 @@ const sectionsAreObjects = (config: Record<string, unknown>): boolean =>
   isSectionOrAbsent(sectionAt(config, 'guard'), 'planApproval') &&
   isSectionOrAbsent(config, 'board')
 
-/** `guard.requiredChecks`, else where configs before 1.10.0 kept it, `guard.planApproval.requiredChecks`. */
-const requiredChecksOf = (guard: Record<string, unknown>) =>
+/**
+ * `guard.requiredChecks`, else where configs before 1.10.0 kept it, `guard.planApproval.requiredChecks`: `{ value }`,
+ * with `value` undefined when neither is set, and `undefined` for a list that does not read.
+ */
+export const requiredChecksOf = (guard: Record<string, unknown>): { value: readonly string[] | undefined } | undefined =>
   'requiredChecks' in guard
     ? optionalValue(guard, 'requiredChecks', isCheckList)
     : optionalValue(sectionAt(guard, 'planApproval'), 'requiredChecks', isCheckList)

package/kit/hooks/hooks/merge-guard/pull-request.ts

@@ -13,6 +13,7 @@ type PullRequestView = {
   headRefOid?: unknown
   baseRefName?: unknown
   isCrossRepository?: unknown
+  isDraft?: unknown
   state?: unknown
   statusCheckRollup?: unknown
   mergeable?: unknown
@@ -20,10 +21,17 @@ type PullRequestView = {
   changedFiles?: unknown
 }
 
+/**
+ * A check of the rollup: `green` when it does not stand in a merge's way, `succeeded` only for a check run that
+ * concluded success; a status never succeeds here.
+ */
+type RollupCheck = { name: string; green: boolean; succeeded: boolean }
+
 /** Where a pull request lives and how many files it changes, as GitHub's `pr view` says. */
 export type RepositoryFacts = { repository: string; changedFiles: number }
 
-const VIEW_FIELDS = 'headRefName,headRefOid,baseRefName,isCrossRepository,state,url,changedFiles,statusCheckRollup,mergeable'
+const VIEW_FIELDS =
+  'headRefName,headRefOid,baseRefName,isCrossRepository,isDraft,state,url,changedFiles,statusCheckRollup,mergeable'
 const PULL_REQUEST_URL = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/pull\/[1-9]\d*$/
 /** The conclusions of a finished check run that do not stand in a merge's way. */
 const GREEN_CONCLUSIONS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED'])
@@ -31,24 +39,27 @@ const GREEN_CONCLUSIONS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED'])
 const viewOf = (json: string): PullRequestView | undefined => parseJsonObject(json)
 
 /**
- * A check of the rollup by its name, whether it is green, and whether it is a check run: a run comes from a workflow
- * or an app, while a status anyone with push access can set through the API.
+ * A check of the rollup by its name, whether it is green, and whether it succeeded as a check run: a run comes from a
+ * workflow or an app, while a status anyone with push access can set through the API.
  */
-const checkOf = (entry: unknown): { name: string; green: boolean; run: boolean } | undefined => {
+const checkOf = (entry: unknown): RollupCheck | undefined => {
   if (typeof entry !== 'object' || entry === null) return undefined
   const { __typename, name, status, conclusion, context, state } = entry as Record<string, unknown>
   if (__typename === 'CheckRun' && typeof name === 'string') {
-    const green = status === 'COMPLETED' && typeof conclusion === 'string' && GREEN_CONCLUSIONS.has(conclusion)
-    return { name, green, run: true }
+    const finished = status === 'COMPLETED' && typeof conclusion === 'string'
+    return { name, green: finished && GREEN_CONCLUSIONS.has(conclusion), succeeded: finished && conclusion === 'SUCCESS' }
   }
-  if (__typename === 'StatusContext' && typeof context === 'string') return { name: context, green: state === 'SUCCESS', run: false }
+  if (__typename === 'StatusContext' && typeof context === 'string') return { name: context, green: state === 'SUCCESS', succeeded: false }
   return undefined
 }
 
-/** The head branch of an open pull request from this repository; a fork's branch name proves nothing. */
+/**
+ * The head branch of an open, ready pull request from this repository; a fork's branch name proves nothing, and a
+ * draft is never merged, nor one whose draft flag GitHub did not answer.
+ */
 export const parseHeadBranch = (json: string): string | undefined => {
-  const { headRefName, isCrossRepository, state } = viewOf(json) ?? {}
-  const ours = state === 'OPEN' && isCrossRepository === false
+  const { headRefName, isCrossRepository, isDraft, state } = viewOf(json) ?? {}
+  const ours = state === 'OPEN' && isCrossRepository === false && isDraft === false
   return ours && typeof headRefName === 'string' ? headRefName : undefined
 }
 
@@ -60,9 +71,11 @@ export const parseBaseBranch = (json: string): string | undefined => {
 
 /**
  * Whether the head commit's checks let a merge pass without a question: GitHub can merge it, it has at least one check
- * run, every check is green (a run finished as success, neutral or skipped, a status succeeded), and every required
- * check is among the runs. An empty list is what a pull request shows right after a push, before any workflow started,
- * so it does not pass; neither does a list of statuses alone, which an agent could set itself in that moment.
+ * run that succeeded, every check is green (a run finished as success, neutral or skipped, a status succeeded), and
+ * every required check has a run that succeeded. An empty list is what a pull request shows right after a push, before
+ * any workflow started, so it does not pass; neither does a list of statuses alone, which an agent could set itself in
+ * that moment, nor skipped runs alone or a required check that was only skipped, as a draft's runs stand right after
+ * `gh pr ready`.
  */
 export const checksPassed = (json: string, requiredChecks: readonly string[] | undefined): boolean => {
   const view = viewOf(json)
@@ -70,8 +83,8 @@ export const checksPassed = (json: string, requiredChecks: readonly string[] | u
   if (view?.mergeable !== 'MERGEABLE' || !Array.isArray(rollup)) return false
   const checks = rollup.map(checkOf)
   if (!checks.every((check) => check?.green === true)) return false
-  const runs = new Set(checks.flatMap((check) => (check?.run ? [check.name] : [])))
-  return runs.size > 0 && (requiredChecks ?? []).every((name) => runs.has(name))
+  const succeeded = new Set(checks.flatMap((check) => (check?.succeeded ? [check.name] : [])))
+  return succeeded.size > 0 && (requiredChecks ?? []).every((name) => succeeded.has(name))
 }
 
 /** The commit the pull request's head points at, as GitHub says now; what a `--match-head-commit` must name. */

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

@@ -41,6 +41,8 @@ type StandingApproval = (facts: MergeFacts) => boolean | MergeNote
 /** The ways a merge may pass without a question. */
 type MergeApprovals = {
   branches: ReadonlySet<string>
+  /** The checks a self-merge of an approved branch waits for a successful run of. */
+  requiredChecks: readonly string[] | undefined
   withoutChecks: readonly string[]
   /** The paths that always ask, which a `withoutChecks` pattern never opens. */
   alwaysAsk: readonly string[]
@@ -64,13 +66,13 @@ const approvedBranchesFrom = (entries: unknown[], settings: GuardSettings, label
  * is not merged unchecked. A standing approval that does not cover a file answers with a note for the question.
  */
 const approvesMerge = (
-  { branches, withoutChecks, alwaysAsk, standing }: MergeApprovals,
+  { branches, requiredChecks, withoutChecks, alwaysAsk, standing }: MergeApprovals,
   merge: PlainMerge,
   facts: MergeFacts,
 ): boolean | MergeNote => {
   const { headCommit } = facts
   if (headCommit === undefined || merge.headCommit !== headCommit) return false
-  if (branches.has(facts.branch) && checksPassed(facts.view, undefined)) return true
+  if (branches.has(facts.branch) && checksPassed(facts.view, requiredChecks)) return true
   if (withoutChecks.length > 0 && isCheckFree(facts.files() ?? [], withoutChecks, alwaysAsk)) return true
   return standing === undefined ? false : standing(facts)
 }
@@ -143,12 +145,13 @@ const policyFor = (input: HookInput, labels: ApprovalLabels, projectDirectory: s
       if (!isWithinDirectory(directory, projectDirectory)) return false
       const approvals = {
         branches: branches(),
+        requiredChecks: settings.requiredChecks,
         withoutChecks: settings.withoutChecks,
         alwaysAsk: [...ALWAYS_ASK_PATHS, ...settings.alwaysAsk],
         standing: standing(),
       }
       if (approvals.branches.size === 0 && approvals.withoutChecks.length === 0 && approvals.standing === undefined) return false
-      // The branch lookup also proves the pull request is open and from this repository; every path needs that.
+      // The branch lookup also proves the pull request is open, no draft and from this repository; every path needs that.
       const facts = mergeFactsOf(merge.pullRequest, viewPullRequest(merge.pullRequest, directory) ?? '', directory)
       return facts !== undefined && approvesMerge(approvals, merge, facts)
     },

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

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { isRecord } from '../shared/json'
+import { requiredChecksOf } from './board-settings'
 
 export type GuardSettings = {
   commands: string[]
@@ -13,6 +14,11 @@ export type GuardSettings = {
    * before 1.10.0); they only ever add a question.
    */
   alwaysAsk: string[]
+  /**
+   * `guard.requiredChecks`: the checks a self-merge waits for a successful run of; undefined: none named, or a list
+   * that does not read, which turns `selfMerge.offer` off.
+   */
+  requiredChecks: readonly string[] | undefined
 }
 
 export const DEFAULT_SETTINGS: GuardSettings = {
@@ -20,6 +26,7 @@ export const DEFAULT_SETTINGS: GuardSettings = {
   selfMerge: { offer: true, approvalMinutes: 180 },
   withoutChecks: [],
   alwaysAsk: [],
+  requiredChecks: undefined,
 }
 
 const CONFIG_PATH = join('.jackherd', 'config.json')
@@ -63,6 +70,7 @@ const pathsOf = (value: unknown): string[] =>
 /**
  * The guard settings of the project's `.jackherd/config.json`, else of the home one. Whatever is missing or
  * malformed keeps its default, so a broken config guards more, never less; only an empty list switches the guard off.
+ * A `requiredChecks` list that does not read has no default that guards more, so it turns the self-merge answer off.
  */
 export const readGuardSettings = (projectDirectory: string, home: string = homedir()): GuardSettings => {
   const config = readConfig([projectDirectory, home])
@@ -70,15 +78,18 @@ export const readGuardSettings = (projectDirectory: string, home: string = homed
   const merge = isRecord(config.merge) ? config.merge : {}
   const selfMerge = isRecord(section.selfMerge) ? section.selfMerge : {}
   const legacy = isRecord(section.planApproval) ? section.planApproval : {}
+  const readableRequiredChecks = requiredChecksOf(section)
+  const offer = typeof selfMerge.offer === 'boolean' ? selfMerge.offer : DEFAULT_SETTINGS.selfMerge.offer
   return {
     commands: isCommandList(section.commands) ? section.commands : DEFAULT_SETTINGS.commands,
     selfMerge: {
-      offer: typeof selfMerge.offer === 'boolean' ? selfMerge.offer : DEFAULT_SETTINGS.selfMerge.offer,
+      offer: offer && readableRequiredChecks !== undefined,
       approvalMinutes: isMinutes(selfMerge.approvalMinutes)
         ? selfMerge.approvalMinutes
         : DEFAULT_SETTINGS.selfMerge.approvalMinutes,
     },
     withoutChecks: isPatternList(merge.withoutChecks) ? merge.withoutChecks : DEFAULT_SETTINGS.withoutChecks,
     alwaysAsk: [...pathsOf(section.alwaysAsk), ...pathsOf(legacy.exceptPaths)],
+    requiredChecks: readableRequiredChecks?.value,
   }
 }

package/kit/hooks/hooks/model-log/transcript.ts

@@ -1,11 +1,8 @@
 import { parseTranscript } from '../shared/dialog-answers'
 import { isRecord, type JsonObject } from '../shared/json'
+import { CONTENT_BLOCK_TYPE, LOG_ENTRY_TYPE } from '../shared/log-vocabulary'
 import { familyOf, type ModelFamily } from '../shared/model-family'
 
-const USER_ENTRY = 'user'
-const ASSISTANT_ENTRY = 'assistant'
-const TEXT_BLOCK = 'text'
-
 const messageOf = (entry: unknown): JsonObject | null =>
   isRecord(entry) && isRecord(entry.message) ? entry.message : null
 
@@ -13,14 +10,14 @@ const textOf = (content: unknown): string | null => {
   if (typeof content === 'string') return content
   if (!Array.isArray(content)) return null
   const texts = content.flatMap((block) =>
-    isRecord(block) && block.type === TEXT_BLOCK && typeof block.text === 'string' ? [block.text] : [],
+    isRecord(block) && block.type === CONTENT_BLOCK_TYPE.text && typeof block.text === 'string' ? [block.text] : [],
   )
   return texts.length > 0 ? texts.join('\n') : null
 }
 
 /** The subagent's prompt: the text of the first user entry of its transcript; null without one. */
 export const promptOf = (head: string): string | null => {
-  const first = parseTranscript(head).find((entry) => isRecord(entry) && entry.type === USER_ENTRY)
+  const first = parseTranscript(head).find((entry) => isRecord(entry) && entry.type === LOG_ENTRY_TYPE.user)
   return textOf(messageOf(first)?.content)
 }
 
@@ -28,7 +25,7 @@ export const promptOf = (head: string): string | null => {
 export type AnsweredModel = { model: string; family: ModelFamily }
 
 const answeredModel = (entry: unknown): AnsweredModel[] => {
-  const model = isRecord(entry) && entry.type === ASSISTANT_ENTRY ? messageOf(entry)?.model : undefined
+  const model = isRecord(entry) && entry.type === LOG_ENTRY_TYPE.assistant ? messageOf(entry)?.model : undefined
   const family = typeof model === 'string' ? familyOf(model) : null
   return typeof model === 'string' && family ? [{ model, family }] : []
 }

package/kit/hooks/hooks/open-question/record.ts

@@ -1,5 +1,6 @@
 import { ASK_USER_QUESTION_TOOL, contentOf, dialogAnswers, questionsOf } from '../shared/dialog-answers'
 import { isRecord, type JsonObject } from '../shared/json'
+import { CONTENT_BLOCK_TYPE, LOG_ENTRY_TYPE } from '../shared/log-vocabulary'
 
 /**
  * A question of a dialog that ended without an answer, as the hook records it: what was asked, when, from where and
@@ -50,7 +51,7 @@ const asksOf = (entries: readonly JsonObject[]): Ask[] =>
     const askedAt = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
     if (Number.isNaN(askedAt)) return []
     return contentOf(entry)
-      .filter((block) => block.type === 'tool_use' && block.name === ASK_USER_QUESTION_TOOL)
+      .filter((block) => block.type === CONTENT_BLOCK_TYPE.toolUse && block.name === ASK_USER_QUESTION_TOOL)
       .flatMap((block) =>
         typeof block.id === 'string'
           ? questionsOf(block.input).map(({ question }) => ({
@@ -70,7 +71,7 @@ const resultsOf = (entries: readonly JsonObject[]): Map<string, JsonObject | nul
   for (const entry of entries) {
     const answers = isRecord(entry.toolUseResult) && isRecord(entry.toolUseResult.answers) ? entry.toolUseResult.answers : null
     for (const block of contentOf(entry))
-      if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') results.set(block.tool_use_id, answers)
+      if (block.type === CONTENT_BLOCK_TYPE.toolResult &&typeof block.tool_use_id === 'string') results.set(block.tool_use_id, answers)
   }
   return results
 }
@@ -79,7 +80,7 @@ const resultsOf = (entries: readonly JsonObject[]): Map<string, JsonObject | nul
 const wentOnAfter = (ask: Ask, entries: readonly JsonObject[]): boolean =>
   entries
     .slice(ask.position + 1)
-    .some((entry) => (entry.type === 'user' || entry.type === 'assistant') && messageIdOf(entry) !== ask.messageId)
+    .some((entry) => (entry.type === LOG_ENTRY_TYPE.user || entry.type === LOG_ENTRY_TYPE.assistant) && messageIdOf(entry) !== ask.messageId)
 
 /** No answer came back, the answer is not a text for this question, or it only puts the question off. */
 const endedUnanswered = (ask: Ask, results: ReadonlyMap<string, JsonObject | null>, entries: readonly JsonObject[]) => {

package/kit/hooks/hooks/shared/dialog-answers.ts

@@ -5,11 +5,12 @@
  */
 import type { DialogAnswer } from './dialog-answer'
 import { isRecord, type JsonObject } from './json'
+import { CLAUDE_TOOL, CONTENT_BLOCK_TYPE } from './log-vocabulary'
 
 export type { DialogAnswer } from './dialog-answer'
 
 /** The tool name of the dialog, as hook inputs and transcripts carry it. */
-export const ASK_USER_QUESTION_TOOL = 'AskUserQuestion'
+export const ASK_USER_QUESTION_TOOL = CLAUDE_TOOL.askUserQuestion
 
 /** The content blocks of a transcript entry's message; none when it has no list of blocks. */
 export const contentOf = (entry: JsonObject): JsonObject[] => {
@@ -52,7 +53,10 @@ const askedQuestions = (entries: JsonObject[]): Map<string, AskedQuestion[]> =>
     entries
       .filter(isMainThread)
       .flatMap(contentOf)
-      .filter((block) => block.type === 'tool_use' && block.name === ASK_USER_QUESTION_TOOL && typeof block.id === 'string')
+      .filter(
+        (block) =>
+          block.type === CONTENT_BLOCK_TYPE.toolUse && block.name === ASK_USER_QUESTION_TOOL && typeof block.id === 'string',
+      )
       .map((block): [string, AskedQuestion[]] => [block.id as string, questionsOf(block.input)]),
   )
 
@@ -61,7 +65,7 @@ const answersIn = (entry: JsonObject, asked: Map<string, AskedQuestion[]>): Dial
   const answeredAt = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
   if (!isRecord(answers) || Number.isNaN(answeredAt)) return []
   return contentOf(entry)
-    .filter((block) => block.type === 'tool_result')
+    .filter((block) => block.type === CONTENT_BLOCK_TYPE.toolResult)
     .flatMap((block) => asked.get(String(block.tool_use_id)) ?? [])
     .flatMap(({ question, offered }) => {
       const answer = answers[question]

package/kit/hooks/hooks/shared/log-vocabulary.ts

@@ -0,0 +1,13 @@
+/** The entry types of a Claude Code transcript line that a hook tells apart; the transcript delivers them as strings. */
+export const LOG_ENTRY_TYPE = { user: 'user', assistant: 'assistant' } as const
+
+/** The block types inside an entry's `message.content`. */
+export const CONTENT_BLOCK_TYPE = { text: 'text', toolUse: 'tool_use', toolResult: 'tool_result' } as const
+
+/** The names of Claude Code's tools a hook looks for, in a `tool_use` block or a hook input's `tool_name`. */
+export const CLAUDE_TOOL = {
+  askUserQuestion: 'AskUserQuestion',
+  agent: 'Agent',
+  taskUpdate: 'TaskUpdate',
+  todoWrite: 'TodoWrite',
+} as const

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

@@ -1,4 +1,5 @@
 import { isRecord } from './json'
+import { CONTENT_BLOCK_TYPE, LOG_ENTRY_TYPE } from './log-vocabulary'
 
 export type Turn = { firstPrompt: string; tools: string[] }
 
@@ -37,17 +38,19 @@ const blocks = (entry: Entry): Block[] => {
 
 /** The text a person typed: a string, or text parts. A tool result and the harness's own skill text are no prompt. */
 const promptText = (entry: Entry): string | undefined => {
-  if (entry.type !== 'user' || entry.isMeta === true) return undefined
+  if (entry.type !== LOG_ENTRY_TYPE.user || entry.isMeta === true) return undefined
   const content = entry.message?.content
   if (typeof content === 'string') return content
-  const texts = blocks(entry).flatMap((block) => (block.type === 'text' && typeof block.text === 'string' ? [block.text] : []))
+  const texts = blocks(entry).flatMap((block) =>
+    block.type === CONTENT_BLOCK_TYPE.text && typeof block.text === 'string' ? [block.text] : [],
+  )
   return texts.length > 0 ? texts.join('\n') : undefined
 }
 
 const toolUses = (entry: Entry): ToolUse[] =>
-  entry.type === 'assistant'
+  entry.type === LOG_ENTRY_TYPE.assistant
     ? blocks(entry).flatMap((block) =>
-        block.type === 'tool_use' && typeof block.name === 'string'
+        block.type === CONTENT_BLOCK_TYPE.toolUse && typeof block.name === 'string'
           ? [{ name: block.name, input: isRecord(block.input) ? block.input : {} }]
           : [],
       )

package/kit/hooks/hooks/task-hint/decision.ts

@@ -1,4 +1,5 @@
 import { isRecord } from '../shared/json'
+import { CLAUDE_TOOL } from '../shared/log-vocabulary'
 import { toolUsesOf } from '../shared/transcript'
 
 /**
@@ -41,8 +42,8 @@ export const hasTaskInProgress = (lines: readonly string[]): boolean => {
   let todos = false
   const tasks = new Map<string, boolean>()
   for (const { name, input } of toolUsesOf(lines.join('\n'))) {
-    if (name === 'TodoWrite') todos = todosInProgress(input)
-    if (name === 'TaskUpdate' && input.taskId !== undefined && input.status !== undefined)
+    if (name === CLAUDE_TOOL.todoWrite) todos = todosInProgress(input)
+    if (name === CLAUDE_TOOL.taskUpdate &&input.taskId !== undefined && input.status !== undefined)
       tasks.set(String(input.taskId), input.status === IN_PROGRESS)
   }
   return todos || [...tasks.values()].some(Boolean)

package/kit/hooks/hooks/task-hint/run.ts

@@ -1,14 +1,12 @@
 import { isHintOn } from '../shared/config'
 import { isWithinDirectory } from '../shared/files'
+import { CLAUDE_TOOL } from '../shared/log-vocabulary'
 import { firstPromptOf, isLanePrompt } from '../shared/transcript'
 import { decideTaskHint, hasTaskInProgress, TASK_HINT_SUBAGENT_TEXT, TASK_HINT_TEXT } from './decision'
 
 /** An Edit, Write or Agent call as the hook receives it: the session, its directory, its transcript and the tool. */
 export type TaskHintCall = { session: string; cwd: string; transcriptPath: string; tool: string }
 
-/** The tool that starts a subagent. */
-const SUBAGENT_TOOL = 'Agent'
-
 /** Everything with a side effect, passed in so a test reaches the flow without git, files or a home directory. */
 export type TaskHintDependencies = {
   mainCheckoutOf: (cwd: string) => string
@@ -34,7 +32,7 @@ const hintFor = (call: TaskHintCall, dependencies: TaskHintDependencies): string
   const main = dependencies.mainCheckoutOf(call.cwd)
   const worktree = dependencies.repositoryRootOf(call.cwd)
   const hinted = dependencies.readMark(main, call.session)
-  const subagent = call.tool === SUBAGENT_TOOL
+  const subagent = call.tool === CLAUDE_TOOL.agent
   const decision = decideTaskHint({
     enabled: isHintOn(dependencies.configs(main), 'taskSignal'),
     lane: isLanePrompt(firstPromptOf(dependencies.readHead(call.transcriptPath).join('\n'))),

package/kit/rules/rules/kit/pull-requests.md

@@ -8,6 +8,7 @@ How an agent opens a pull request so every PR reads consistently and is review-
 - **Base = `{{kit.baseBranch}}`** unless the user names another.
 - **Work on a branch.** If the working branch is `{{kit.baseBranch}}`, branch first.
 - **Push before creating, with the user's go-ahead for the push.** The head branch must be on the remote so `gh pr create` has a target.
+- **Drafts:** Opening as a draft is **{{kit.merge.openAsDraft}}** (`merge.openAsDraft`); `on` opens every PR with `gh pr create --draft`; you turn it ready (`gh pr ready <n>`) once it goes to merge.
 - **Check for an existing PR first** (`gh pr view <branch>`). If a prior PR for the same branch is already **merged**, the new one is a continuation — mark it in the title.
 
 ## Title