jackherd 1.2.0 → 1.3.0

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

@@ -419,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,
@@ -431,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:
 
@@ -454,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
@@ -471,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.2.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/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/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)