jackherd 1.7.0 → 1.8.0

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

@@ -2,14 +2,15 @@
 // decision on stdout when the command runs a guarded one, or with nothing to leave the call to the
 // permission rules. Any failure asks: a guard that crashes, or takes too long, must not wave the command through.
 // The decision runs in a worker that is ended after DEADLINE_MS, because Claude Code lets a call through when a hook
-// runs into its own timeout. argv[2] is the exact option label that approves a merge, rendered into the hook entry by `sync`.
+// runs into its own timeout. argv[2] and argv[3] are the exact option labels that approve a merge: the one of the pull request
+// question and the one of a plan question, rendered into the hook entry by `sync`.
 import type { MergeGuardDecision } from './decision'
-import { failureDecision } from './run'
+import { type ApprovalLabels, failureDecision } from './run'
 
 /** Below the 10 s the hook entry allows, with room for the start of Bun and for printing. */
 const DEADLINE_MS = 7000
 
-type Job = { text: string; label: string; projectDirectory: string }
+type Job = { text: string; labels: ApprovalLabels; projectDirectory: string }
 
 const timeoutDecision: MergeGuardDecision = {
   kind: 'ask',
@@ -34,7 +35,8 @@ const decide = async (): Promise<MergeGuardDecision> => {
   try {
     const text = await Bun.stdin.text()
     const projectDirectory = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-    return await decideWithin({ text, label: process.argv[2] ?? '', projectDirectory }, DEADLINE_MS)
+    const labels = { selfMerge: process.argv[2] ?? '', plan: process.argv[3] ?? '' }
+    return await decideWithin({ text, labels, projectDirectory }, DEADLINE_MS)
   } catch (error) {
     return failureDecision(error)
   }

package/kit/hooks/hooks/merge-guard/plain-path.ts

@@ -0,0 +1,15 @@
+/** Whether a path is one GitHub lists for a pull request, and the character test the config validators share. */
+
+/** A C0 control character or DEL. */
+export const isControlCharacter = (character: string): boolean => {
+  const code = character.charCodeAt(0)
+  return code < 0x20 || code === 0x7f
+}
+
+/** A repository path as GitHub lists it: relative, no empty, `.` or `..` segment, no backslash, no control character. */
+export const isPlainPath = (file: string): boolean =>
+  file !== '' &&
+  !file.startsWith('/') &&
+  !file.includes('\\') &&
+  ![...file].some(isControlCharacter) &&
+  !file.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')

package/kit/hooks/hooks/merge-guard/plan-approval-record.ts

@@ -0,0 +1,23 @@
+// PostToolUse hook for AskUserQuestion, shipped by jackherd. When the call asked about a plan (``Plan `<path>` ``) and
+// offered the label that approves it or the one that revokes it, it leaves a pointer to that dialog in the main
+// checkout's `.jackherd/approvals/plans/`, so the merge guard finds the answer again after the session ended. It writes
+// only the pointer; the merge guard reads the answer from the transcript itself. argv[2] and argv[3] are the two labels,
+// rendered into the hook entry by `sync`. It never blocks and prints nothing: a pointer it fails to write costs a question.
+// The other way round it costs a revocation: when no pointer is written for a "revoke" answer, the merge guard never
+// sees that answer, and an older approval keeps holding until the next plan question that is recorded.
+import { mainCheckoutOf } from '../shared/checkout'
+import { planPointersDirectory, pointerOf, writePointer } from './plan-pointers'
+
+const record = async (): Promise<void> => {
+  const pointer = pointerOf(JSON.parse(await Bun.stdin.text()), process.argv.slice(2, 4), Date.now())
+  if (pointer === undefined) return
+  const projectDirectory = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
+  writePointer(planPointersDirectory(mainCheckoutOf(projectDirectory)), pointer)
+}
+
+try {
+  await record()
+} catch {
+  // Nothing to do: without a pointer the merge asks.
+}
+process.exit(0)

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

@@ -0,0 +1,142 @@
+import { baseBranchOf } from '../shared/base-branch'
+import { BOARD_WORDS, type BoardLanguage } from '../shared/board-lanes'
+import { isRecord, parseJsonObject } from '../shared/json'
+import { isRepositoryDirectory } from '../shared/repository-directory'
+import { isControlCharacter } from './plain-path'
+
+/**
+ * What plan approval needs: the paths that always ask (the defaults plus the project's own) and where plans, boards
+ * and lanes live. `null` from `readPlanApprovalSettings` means plan approval is off and every merge asks.
+ */
+export type PlanApprovalSettings = {
+  exceptPaths: readonly string[]
+  planLanguage: BoardLanguage
+  planDirectory: string
+  board: { pattern: string; file: string }
+  worktreeDirectory: string
+  baseBranch: string
+  /** The checks that must be among the head commit's and green; undefined: at least one check, every one green. */
+  requiredChecks: readonly string[] | undefined
+}
+
+/**
+ * The paths that always ask, whatever the project adds: workflows, migrations, env files, the agent setup and its
+ * instructions, the jackherd config, `bunfig.toml`, whose `preload` runs before every hook (they start in the project
+ * root, so only the root one), git hooks, lockfiles, registry config and code owners.
+ */
+export const PLAN_APPROVAL_ALWAYS_ASK: readonly string[] = [
+  '.github/**',
+  '**/migrations/**',
+  '**/.env*',
+  '.claude/**',
+  '.jackherd/**',
+  'bunfig.toml',
+  '**/CLAUDE.md',
+  '**/AGENTS.md',
+  '.agents/**',
+  '.mcp.json',
+  '.husky/**',
+  'lefthook.yml',
+  '**/bun.lock',
+  '**/bun.lockb',
+  '**/package-lock.json',
+  '**/pnpm-lock.yaml',
+  '**/yarn.lock',
+  '**/.npmrc',
+  '**/CODEOWNERS',
+]
+
+/** Where a project keeps its jackherd config, as a path inside the repository. */
+export const PROJECT_CONFIG = '.jackherd/config.json'
+
+/**
+ * The same rules as `alwaysAskPattern` in the config schema: path words with wildcards, relative, no empty, `.` or
+ * `..` segment (GitHub lists no file with one, so such a pattern would never ask). Broad on purpose (`.github/**`,
+ * `**`): a pattern here only ever adds a question.
+ */
+const isAlwaysAskPattern = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  /^[A-Za-z0-9_.*/-]+$/.test(value) &&
+  value.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
+
+const MAX_CHECK_NAME = 200
+const BOARD_PATTERN = /^(?![-.])[A-Za-z0-9._*?-]+$/
+const BOARD_FILE = /^(?![-.])[A-Za-z0-9._-]+\.md$/
+
+/** The value at `key`, its default when absent, `undefined` when present but invalid. */
+const valueOr = <T>(section: Record<string, unknown>, key: string, isValid: (value: unknown) => value is T, fallback: T) =>
+  !(key in section) ? fallback : isValid(section[key]) ? section[key] : undefined
+
+/** An optional value: `{ value }` with `value` undefined when absent, `undefined` when present but invalid. */
+const optionalValue = <T>(section: Record<string, unknown>, key: string, isValid: (value: unknown) => value is T) =>
+  !(key in section) ? { value: undefined } : isValid(section[key]) ? { value: section[key] } : undefined
+
+const matches =
+  (pattern: RegExp) =>
+  (value: unknown): value is string =>
+    typeof value === 'string' && pattern.test(value)
+
+const isPlanLanguage = (value: unknown): value is BoardLanguage => typeof value === 'string' && Object.hasOwn(BOARD_WORDS, value)
+
+const isSectionOrAbsent = (config: Record<string, unknown>, key: string): boolean =>
+  !(key in config) || isRecord(config[key])
+
+const sectionAt = (config: Record<string, unknown>, key: string): Record<string, unknown> =>
+  isRecord(config[key]) ? config[key] : {}
+
+const isPathList = (value: unknown): value is string[] => Array.isArray(value) && value.every(isAlwaysAskPattern)
+
+/** The same rules as `checkName` in the config schema: a name with a visible character, no control character. */
+const isCheckName = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  value.trim() !== '' &&
+  value.length <= MAX_CHECK_NAME &&
+  ![...value].some(isControlCharacter)
+
+const isCheckList = (value: unknown): value is string[] => Array.isArray(value) && value.every(isCheckName)
+
+const sectionsAreObjects = (config: Record<string, unknown>): boolean =>
+  isSectionOrAbsent(config, 'guard') &&
+  isSectionOrAbsent(sectionAt(config, 'guard'), 'planApproval') &&
+  isSectionOrAbsent(config, 'board')
+
+/** Every value plan approval reads, with its default where absent; `undefined` stands for a present but invalid one. */
+const planApprovalValues = (config: Record<string, unknown>) => {
+  const board = sectionAt(config, 'board')
+  const planApproval = sectionAt(sectionAt(config, 'guard'), 'planApproval')
+  return {
+    exceptPaths: valueOr(planApproval, 'exceptPaths', isPathList, []),
+    requiredChecks: optionalValue(planApproval, 'requiredChecks', isCheckList),
+    planLanguage: valueOr(config, 'planLanguage', isPlanLanguage, 'en'),
+    planDirectory: valueOr(config, 'planDirectory', isRepositoryDirectory, 'docs/plans'),
+    pattern: valueOr(board, 'pattern', matches(BOARD_PATTERN), 'board-*'),
+    file: valueOr(board, 'file', matches(BOARD_FILE), 'board.md'),
+    worktreeDirectory: valueOr(config, 'worktreeDirectory', isRepositoryDirectory, '.claude/worktrees'),
+    baseBranch: baseBranchOf(config),
+  }
+}
+
+type Values = ReturnType<typeof planApprovalValues>
+type ValidValues = { [Key in keyof Values]: Exclude<Values[Key], undefined> }
+
+const allValid = (values: Values): values is ValidValues => Object.values(values).every((value) => value !== undefined)
+
+/**
+ * The plan approval settings of the project's `.jackherd/config.json` as the base commit holds it (`null`: it holds
+ * none). Unlike the other guard settings, a missing config, one that is no JSON object, or any invalid value they read
+ * turns plan approval off (`null`), so neither a mistyped project path nor a home config can shrink the list silently.
+ * The project's paths add to `PLAN_APPROVAL_ALWAYS_ASK`.
+ */
+export const planApprovalSettingsOf = (text: string | null): PlanApprovalSettings | null => {
+  const config = text === null ? null : (parseJsonObject(text) ?? null)
+  if (config === null || !sectionsAreObjects(config)) return null
+  const values = planApprovalValues(config)
+  if (!allValid(values)) return null
+  const { exceptPaths, requiredChecks, pattern, file, ...where } = values
+  return {
+    exceptPaths: [...PLAN_APPROVAL_ALWAYS_ASK, ...exceptPaths],
+    board: { pattern, file },
+    ...where,
+    requiredChecks: requiredChecks.value,
+  }
+}

package/kit/hooks/hooks/merge-guard/plan-approval-sources.ts

@@ -0,0 +1,196 @@
+/**
+ * Where plan approval reads its facts: git in the main checkout for the base branch, the worktrees and the boards, the
+ * pointer directory and the transcripts for the answers. Every git call runs without a shell and with a timeout; any
+ * failure answers nothing, so the guard asks.
+ */
+import { existsSync } from 'node:fs'
+import { join, posix, relative, resolve } from 'node:path'
+import { lanePlansOf } from '../shared/board-lanes'
+import { laneOf } from '../shared/lane'
+import type { PlanApprovalSources } from './plan-approval'
+import { FULL_COMMIT } from '../shared/commit'
+import { isPlainPath } from './plain-path'
+import { planAnswers, planPointersDirectory } from './plan-pointers'
+import { checksPassed } from './pull-request'
+import { baseBranchOf } from '../shared/base-branch'
+import { type PlanApprovalSettings, PROJECT_CONFIG, planApprovalSettingsOf } from './plan-approval-settings'
+import { readConfigOrNull } from './settings'
+
+/** The base commit plan approval reads, just fetched, and the settings its project config holds. */
+export type PlanBase = { commit: string; settings: PlanApprovalSettings }
+
+export type PlanSourceContext = {
+  /** The main checkout, where the worktrees, the base branch and the pointers are. */
+  main: string
+  base: PlanBase
+  /** The transcript of the session that merges. */
+  transcript: string | undefined
+  /** The label that approves a plan. */
+  label: string
+  files: () => readonly string[] | undefined
+  /** The `gh pr view` answer for the pull request, which carries its checks. */
+  view: string
+}
+
+const GIT_TIMEOUT_MS = 3000
+const BASE_REMOTE = 'origin'
+const HEADER = /^[0-9a-f]+ blob (\d+)$/
+
+/**
+ * The output of `git cat-file --batch`, one entry per requested path in order: the text of a blob, null for a path the
+ * commit lacks or that is no blob. Undefined when the output does not hold one entry per path.
+ */
+export const parseCatFileBatch = (output: Buffer, count: number): (string | null)[] | undefined => {
+  const texts: (string | null)[] = []
+  let at = 0
+  while (texts.length < count) {
+    const newline = output.indexOf('\n', at)
+    if (newline === -1) return undefined
+    const size = HEADER.exec(output.subarray(at, newline).toString('utf8'))?.[1]
+    if (size === undefined) {
+      texts.push(null)
+      at = newline + 1
+      continue
+    }
+    const end = newline + 1 + Number(size)
+    if (end > output.length) return undefined
+    texts.push(output.subarray(newline + 1, end).toString('utf8'))
+    at = end + 1
+  }
+  return texts
+}
+
+/** The lane whose worktree, directly below the worktree directory, has `branch` checked out. */
+export const laneInWorktreeList = (
+  worktreeList: string,
+  main: string,
+  worktreeDirectory: string,
+  branch: string,
+): string | undefined => {
+  const blocks = worktreeList.split('\n\n').map((block) => block.split('\n'))
+  const block = blocks.find((lines) => lines.includes(`branch refs/heads/${branch}`))
+  const path = block?.find((line) => line.startsWith('worktree '))?.slice('worktree '.length)
+  if (path === undefined) return undefined
+  const lane = laneOf({ cwd: path, main, worktreeDirectory })
+  return lane !== null && relative(resolve(main, worktreeDirectory), resolve(path)) === lane ? lane : undefined
+}
+
+/** Whether `name` is the directory of a lane's worktree below the worktree directory. */
+export const isLaneIn =
+  (main: string, worktreeDirectory: string) =>
+  (name: string): boolean => {
+    const worktree = join(resolve(main, worktreeDirectory), name)
+    return laneOf({ cwd: worktree, main, worktreeDirectory }) === name && existsSync(worktree)
+  }
+
+/** Only the base branch into its remote ref: no tags, no FETCH_HEAD written, no maintenance started. */
+export const baseFetchArguments = (baseBranch: string): string[] => [
+  'fetch',
+  '--quiet',
+  '--no-tags',
+  '--no-write-fetch-head',
+  '--no-auto-maintenance',
+  BASE_REMOTE,
+  `+refs/heads/${baseBranch}:refs/remotes/${BASE_REMOTE}/${baseBranch}`,
+]
+
+/** No prompt for a password or a host key: a fetch that would wait for one fails at once instead. */
+export const NON_INTERACTIVE = { GIT_TERMINAL_PROMPT: '0', GIT_SSH_COMMAND: 'ssh -o BatchMode=yes' }
+
+const git = (main: string, args: readonly string[], stdin?: string): Buffer | undefined => {
+  const result = Bun.spawnSync(['git', '-C', main, ...args], {
+    stdin: stdin === undefined ? 'ignore' : new TextEncoder().encode(stdin),
+    stdout: 'pipe',
+    stderr: 'ignore',
+    timeout: GIT_TIMEOUT_MS,
+    env: { ...process.env, ...NON_INTERACTIVE },
+  })
+  return result.exitCode === 0 ? result.stdout : undefined
+}
+
+const baseCommitOf = (main: string, baseBranch: string): string | undefined => {
+  const commit = git(main, ['rev-parse', '--verify', '--quiet', `${BASE_REMOTE}/${baseBranch}^{commit}`])
+    ?.toString()
+    .trim()
+  return commit !== undefined && FULL_COMMIT.test(commit) ? commit : undefined
+}
+
+/** The texts of the paths at the commit, in one `git cat-file --batch`; null for each one it lacks or cannot read. */
+const readAtCommit = (main: string, commit: string, paths: readonly string[]): Map<string, string | null> => {
+  const asked = paths.filter(isPlainPath)
+  const output =
+    asked.length === 0
+      ? undefined
+      : git(main, ['cat-file', '--batch'], asked.map((path) => `${commit}:${path}\n`).join(''))
+  const texts = output === undefined ? undefined : parseCatFileBatch(output, asked.length)
+  return new Map(paths.map((path) => [path, texts?.[asked.indexOf(path)] ?? null]))
+}
+
+/** The board directories under the plan directory at the commit whose name matches the board pattern. */
+const boardDirectories = (main: string, commit: string, settings: PlanApprovalSettings): string[] => {
+  const listing = git(main, ['ls-tree', '-d', '--name-only', commit, '--', `${settings.planDirectory}/`])
+  const pattern = new Bun.Glob(settings.board.pattern)
+  return (listing?.toString() ?? '')
+    .split('\n')
+    .filter((path) => path !== '' && pattern.match(posix.basename(path)))
+}
+
+/** Brings `origin/<baseBranch>` up to date, so a stale ref cannot hold an approval GitHub's base no longer does. */
+const fetchBase = (main: string, baseBranch: string): boolean => git(main, baseFetchArguments(baseBranch)) !== undefined
+
+/** The newest first-parent commit of the base from before the time; undefined when there is none. */
+const commitBefore = (main: string, commit: string, time: number): string | undefined => {
+  const found = git(main, ['rev-list', '-1', '--first-parent', `--before=@${Math.floor(time / 1000)}`, commit])
+    ?.toString()
+    .trim()
+  return found !== undefined && FULL_COMMIT.test(found) ? found : undefined
+}
+
+/**
+ * The plan as the base held it at the time of the answer; undefined when the base did not hold it then, or not
+ * readably. A plan that was only in a pull request when the user approved it could have grown before it landed, and
+ * the state the user saw is nowhere on the base, so the guard asks once more after it landed.
+ */
+const planAtApproval = (main: string, commit: string, plan: string, answeredAt: number): string | undefined => {
+  const before = commitBefore(main, commit, answeredAt)
+  return (before === undefined ? undefined : readAtCommit(main, before, [plan]).get(plan)) ?? undefined
+}
+
+/**
+ * The base plan approval reads: `origin/<baseBranch>` right after a fetch, and the settings of the project config at
+ * that commit, never of the checkout. The base branch comes from the checkout's config (the base cannot name itself)
+ * and must agree with the one the base's config names. Undefined, so the guard asks, when any step fails.
+ */
+export const planBaseOf = (main: string): PlanBase | undefined => {
+  const baseBranch = baseBranchOf(readConfigOrNull([main]))
+  if (baseBranch === undefined || !fetchBase(main, baseBranch)) return undefined
+  const commit = baseCommitOf(main, baseBranch)
+  if (commit === undefined) return undefined
+  const settings = planApprovalSettingsOf(readAtCommit(main, commit, [PROJECT_CONFIG]).get(PROJECT_CONFIG) ?? null)
+  return settings !== null && settings.baseBranch === baseBranch ? { commit, settings } : undefined
+}
+
+export const planApprovalSources = ({ main, base, transcript, label, files, view }: PlanSourceContext): PlanApprovalSources => {
+  const { commit, settings } = base
+  return {
+    checksPassed: (requiredChecks) => checksPassed(view, requiredChecks),
+    containsBase: (headCommit) =>
+      FULL_COMMIT.test(headCommit) && git(main, ['merge-base', '--is-ancestor', commit, headCommit]) !== undefined,
+    files,
+    readAtBase: (paths) => readAtCommit(main, commit, paths),
+    laneOfBranch: (branch) => {
+      const list = git(main, ['worktree', 'list', '--porcelain'])?.toString()
+      return list === undefined ? undefined : laneInWorktreeList(list, main, settings.worktreeDirectory, branch)
+    },
+    lanePlans: (lane) => {
+      const boards = boardDirectories(main, commit, settings)
+      const texts = readAtCommit(main, commit, boards.map((directory) => `${directory}/${settings.board.file}`))
+      return boards.flatMap((directory) => {
+        const text = texts.get(`${directory}/${settings.board.file}`)
+        return (text ? lanePlansOf(text, directory, lane, settings.planLanguage) : undefined) ?? []
+      })
+    },
+    answers: (plan) => planAnswers({ directory: planPointersDirectory(main), currentTranscript: transcript, plan, label }),
+    readAtCommitBefore: (plan, answeredAt) => (isPlainPath(plan) ? planAtApproval(main, commit, plan, answeredAt) : undefined),
+  }
+}

package/kit/hooks/hooks/merge-guard/plan-approval.ts

@@ -0,0 +1,168 @@
+/**
+ * Whether the user's approval of a plan lifts the question for the merge of a pull request: it merges into the base
+ * branch, its checks passed, its head contains the base, the pull request comes from a lane whose rows link exactly
+ * that plan, the plan still has an open phase, no file matches a path that always asks, none is a package.json and
+ * none the CHANGELOG.md of a published package, the newest answer to a plan question naming it approved it, and the
+ * plan gained no phase and no undecided task since that answer. Everything is read from the base branch and from
+ * GitHub, never from the pull request's own files, and every doubt answers "no", so the guard asks as before. Only a
+ * plain `gh pr merge <number>` gets this far.
+ */
+import type { LanePlans } from '../shared/board-lanes'
+import { hasOpenPhase } from '../shared/plan-open-phases'
+import { isRecord } from '../shared/json'
+import type { MergeNote } from './decision'
+import { isPlainPath } from './plain-path'
+import { type NewTask, newPhasesSince, newTasksSince } from './plan-growth'
+
+/** The label the user picked in a plan question and when; read from the transcript, not from the pointer. */
+export type PlanAnswer = { answer: string; answeredAt: number }
+
+/** Where the facts come from; each is asked only once the steps before it said yes. */
+export type PlanApprovalSources = {
+  /** Whether GitHub can merge the head commit and its checks passed, the required ones among them. */
+  checksPassed: (requiredChecks: readonly string[] | undefined) => boolean
+  /** Whether the head commit contains the base commit plan approval reads. */
+  containsBase: (headCommit: string) => boolean
+  /** The files of the pull request as GitHub lists them, renames with their old name; undefined when not complete. */
+  files: () => readonly string[] | undefined
+  /** The texts of these paths at the base branch; null for a path it does not have. */
+  readAtBase: (paths: readonly string[]) => ReadonlyMap<string, string | null>
+  /** The lane whose worktree has the branch checked out. */
+  laneOfBranch: (branch: string) => string | undefined
+  /** The lane's rows in each board at the base branch that has any. */
+  lanePlans: (lane: string) => LanePlans[]
+  /** The answers to the plan questions naming this plan, each backed by its dialog in a transcript. */
+  answers: (plan: string) => PlanAnswer[]
+  /** The plan as the base held it at the time of the answer; undefined when it held none then or it is unreadable. */
+  readAtCommitBefore: (plan: string, answeredAt: number) => string | undefined
+}
+
+export type PlanApprovalQuery = {
+  /** The pull request as GitHub names it: its head branch and commit, and the branch it merges into. */
+  pullRequest: { branch: string; headCommit: string; baseBranch: string }
+  /** The exact option label that approves a plan. */
+  label: string
+  /** The time of the check, in milliseconds. */
+  now: number
+  /** The paths that always ask, the base branch, and the checks that must have passed (undefined: every one listed). */
+  settings: { exceptPaths: readonly string[]; baseBranch: string; requiredChecks: readonly string[] | undefined }
+}
+
+/** `true` lifts the question; `false` asks as before; a note asks and says why, for a plan that grew since its approval. */
+export type PlanVerdict = boolean | MergeNote
+
+const MANIFEST = 'package.json'
+/** How many new tasks a note names before it only counts the rest. */
+const NAMED_TASKS = 5
+const TASK_LENGTH = 80
+const CHANGELOG = 'changelog.md'
+
+const directoryOf = (file: string): string => file.slice(0, Math.max(file.lastIndexOf('/'), 0))
+
+/** In lower case, as a case-insensitive file system would write it. */
+const fileName = (file: string): string => file.slice(file.lastIndexOf('/') + 1).toLowerCase()
+
+const manifestOf = (directory: string): string => (directory === '' ? MANIFEST : `${directory}/${MANIFEST}`)
+
+/**
+ * Compared in lower case: on a case-insensitive file system git writes `.Claude/x` into the existing `.claude/`, so a
+ * pattern must not miss it. Folding only ever adds a question.
+ */
+const matchesAny = (files: readonly string[], patterns: readonly string[]): boolean => {
+  const globs = patterns.map((pattern) => new Bun.Glob(pattern.toLowerCase()))
+  return files.some((file) => globs.some((glob) => glob.match(file.toLowerCase())))
+}
+
+/** The manifests of the packages whose CHANGELOG.md the pull request changes. */
+const changelogManifests = (files: readonly string[]): string[] => [
+  ...new Set(files.filter((file) => fileName(file) === CHANGELOG).map((file) => manifestOf(directoryOf(file)))),
+]
+
+/** A package is private only when its manifest at the base says `"private": true`; a missing or broken one is published. */
+const isPrivate = (manifest: string | null | undefined): boolean => {
+  try {
+    const parsed: unknown = JSON.parse(manifest ?? '')
+    return isRecord(parsed) && parsed.private === true
+  } catch {
+    return false
+  }
+}
+
+/** The one plan the lane's open rows link across the boards; none or several gives none. */
+const onlyPlanOf = (rows: readonly LanePlans[]): string | undefined => {
+  const plans = new Set(rows.filter(({ closed }) => !closed).flatMap(({ plans }) => plans))
+  const [only] = plans
+  return plans.size === 1 ? only : undefined
+}
+
+/**
+ * When the user approved the plan: the time of the newest answers not from the future, when every one of them is the
+ * label. Two answers at the same time (two questions in one dialog) approve only together.
+ */
+const approvedAt = (answers: readonly PlanAnswer[], label: string, now: number): number | undefined => {
+  const past = answers.filter(({ answeredAt }) => answeredAt <= now)
+  if (past.length === 0) return undefined
+  const newest = Math.max(...past.map(({ answeredAt }) => answeredAt))
+  const atNewest = past.filter(({ answeredAt }) => answeredAt === newest)
+  return atNewest.every(({ answer }) => answer === label) ? newest : undefined
+}
+
+const shortened = (task: string): string => (task.length > TASK_LENGTH ? `${task.slice(0, TASK_LENGTH - 1)}…` : task)
+
+const tasksNote = (tasks: readonly NewTask[]): string => {
+  const named = tasks.slice(0, NAMED_TASKS).map(({ phase, task }) => `P${phase} "${shortened(task)}"`)
+  const rest = tasks.length > NAMED_TASKS ? ` and ${tasks.length - NAMED_TASKS} more` : ''
+  return `${tasks.length} new tasks: ${named.join(', ')}${rest}`
+}
+
+/** Why the approval no longer covers the plan: the phases and the undecided tasks it gained; undefined when none. */
+const growthNote = (plan: string, approvedText: string, currentText: string): string | undefined => {
+  const phases = newPhasesSince(approvedText, currentText)
+  const tasks = newTasksSince(approvedText, currentText)
+  const parts = [
+    ...(phases.length > 0 ? [`new phases: ${phases.map((phase) => `"${phase}"`).join(', ')}`] : []),
+    ...(tasks.length > 0 ? [tasksNote(tasks)] : []),
+  ]
+  return parts.length === 0 ? undefined : `Plan \`${plan}\` gained since the user's approval ${parts.join('; ')}.`
+}
+
+/**
+ * No file of the pull request matches a path that always asks or is a package.json (private or not: it can drop
+ * `"private"` or add a dependency), and none is the changelog of a package the base does not call private.
+ */
+const changesOnlyOrdinaryFiles = (files: readonly string[], exceptPaths: readonly string[], sources: PlanApprovalSources) => {
+  if (files.length === 0 || !files.every(isPlainPath) || matchesAny(files, exceptPaths)) return false
+  if (files.some((file) => fileName(file) === MANIFEST)) return false
+  const manifests = changelogManifests(files)
+  if (manifests.length === 0) return true
+  const texts = sources.readAtBase(manifests)
+  return manifests.every((manifest) => isPrivate(texts.get(manifest)))
+}
+
+/** The plan of the branch's lane and its text at the base, while that plan has an open phase there. */
+const openPlanOf = (branch: string, sources: PlanApprovalSources): { plan: string; text: string } | undefined => {
+  const lane = sources.laneOfBranch(branch)
+  const plan = lane === undefined ? undefined : onlyPlanOf(sources.lanePlans(lane))
+  if (plan === undefined) return undefined
+  const text = sources.readAtBase([plan]).get(plan)
+  return typeof text === 'string' && hasOpenPhase(text) ? { plan, text } : undefined
+}
+
+/** The pull request merges into the base, the head contains it, and its checks passed. */
+const isTestedAgainstBase = ({ pullRequest, settings }: PlanApprovalQuery, sources: PlanApprovalSources): boolean =>
+  pullRequest.baseBranch === settings.baseBranch &&
+  sources.checksPassed(settings.requiredChecks) &&
+  sources.containsBase(pullRequest.headCommit)
+
+export const isPlanApproved = (query: PlanApprovalQuery, sources: PlanApprovalSources): PlanVerdict => {
+  if (!isTestedAgainstBase(query, sources)) return false
+  const files = sources.files()
+  if (files === undefined || !changesOnlyOrdinaryFiles(files, query.settings.exceptPaths, sources)) return false
+  const open = openPlanOf(query.pullRequest.branch, sources)
+  const answeredAt = open === undefined ? undefined : approvedAt(sources.answers(open.plan), query.label, query.now)
+  if (open === undefined || answeredAt === undefined) return false
+  const approvedText = sources.readAtCommitBefore(open.plan, answeredAt)
+  if (approvedText === undefined) return false
+  const note = growthNote(open.plan, approvedText, open.text)
+  return note === undefined ? true : { note }
+}

package/kit/hooks/hooks/merge-guard/plan-growth.ts

@@ -0,0 +1,40 @@
+/**
+ * What a plan gained since the user approved it: phases, and tasks in the phases they already saw. Both compare the
+ * text of the approved plan with the plan at the base, whatever the boxes say, so ticking a task is no growth.
+ */
+import { phaseBlocksOf, taskOf } from '../shared/plan-open-phases'
+
+/** A task of a phase that was there at the approval, which the approved plan did not hold. */
+export type NewTask = { phase: string; task: string }
+
+/** A task the user decided, marked `(User <date> …)` with `DD.MM.` or `YYYY-MM-DD`; the user already saw it. */
+const USER_DECIDED = /\(User (?:\d{1,2}\.\d{1,2}\.|\d{4}-\d{2}-\d{2})/
+
+const tasksOf = (lines: readonly string[]): string[] =>
+  lines.flatMap((line) => {
+    const task = taskOf(line)
+    return task === null ? [] : [task.text]
+  })
+
+/** The headings of the current plan's phases the approved plan does not have, by their text: a rename is new. */
+export const newPhasesSince = (approvedText: string, currentText: string): string[] => {
+  const approved = new Set(phaseBlocksOf(approvedText).map(({ heading }) => heading))
+  return phaseBlocksOf(currentText)
+    .map(({ heading }) => heading)
+    .filter((heading) => !approved.has(heading))
+}
+
+/**
+ * The tasks of the current plan that the same phase of the approved plan did not hold, by their text (a rewording is
+ * new), leaving out tasks the user decided and every task of a phase that is new itself.
+ */
+export const newTasksSince = (approvedText: string, currentText: string): NewTask[] => {
+  const approved = new Map(phaseBlocksOf(approvedText).map(({ id, lines }) => [id, new Set(tasksOf(lines))]))
+  return phaseBlocksOf(currentText).flatMap(({ id, lines }) => {
+    const known = approved.get(id)
+    if (known === undefined) return []
+    return tasksOf(lines)
+      .filter((task) => !known.has(task) && !USER_DECIDED.test(task))
+      .map((task) => ({ phase: id, task }))
+  })
+}