jackherd 1.16.0 → 1.17.0

package/src/check/plan-structure-check.ts

@@ -1,36 +1,47 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join, posix } from 'node:path'
 import { boardPlansOf, isInsideRepository } from '../../kit/hooks/hooks/shared/board-lanes'
-import { planCopiesIn } from '../../kit/hooks/hooks/shared/boards'
+import { boardsIn, planCopiesIn } from '../../kit/hooks/hooks/shared/boards'
+import { readTextOrNull } from '../../kit/hooks/hooks/shared/files'
 import { codesOfPlans } from '../../kit/hooks/hooks/shared/plan-codes'
 import {
   boardRowsWithoutPhase,
   boardRowsWithProse,
+  currentPhase,
   hasLanesTable,
   type LongPhaseTitle,
+  laneProgress,
   longPhaseTitles,
-  type MergedPhaseWithOpenBoxes,
   mergedPhasesWithOpenBoxes,
   newPhasesWithoutReviewGate,
+  openBoxesOfPhase,
   PHASE_CELL_LIMIT,
   PHASE_TITLE_LIMIT,
+  type PhaseWithOpenBoxes,
   type PhaseWithoutGate,
   type PhaseWithoutRow,
   PLAN_VOCABULARY,
   type PlanLanguage,
+  type PlanPhase,
   PROSE_REASON,
+  parsePlanPhases,
+  parseSprintLanes,
   phaseIdsOfPlan,
   phasesWithoutDependencyRow,
   type RowWithoutPhase,
   type RowWithProse,
+  resolvePlanPath,
   SHORT_NAME_LIMIT,
   SHORT_NAME_PROBLEM,
   type ShortNameFinding,
+  type SprintLane,
   shortNameFindings,
 } from '../plan-format'
 import { boardRowsWithBareCodes, type RowWithBareCode } from '../plan-format/bare-codes'
+import { mergePlanPhases } from '../plans/phase-source'
 import { changedPlansOf } from './deferral-arrows'
 import { CHECK_STATUS, type CheckResult } from './result'
+import { OPEN_BOXES_LEVEL, type OpenBoxesLevel } from './schema'
 
 /** The content of a file at a ref; null where the ref lacks the file. */
 export type ContentAt = (path: string) => string | null
@@ -72,6 +83,22 @@ type Report<T> = {
   clean: string
 }
 
+/** The lane a checkout is for and where its boards live, as the check reads them from the checkout. */
+export type LaneBoxesInput = {
+  root: string
+  lane: string
+  planDirectory: string
+  board: { pattern: string; file: string }
+  language: PlanLanguage
+  /** A plan as the base has it (the pull request's parent in the watcher); null where it lacks the file. */
+  baseOf: ContentAt
+}
+
+type BuiltPhase = { planPath: string; phaseId: string; partial: boolean }
+
+/** The phase a lane builds with the plan it is in and its open boxes; `open` is null for a phase without any. */
+export type LaneBuild = { path: string; open: PhaseWithOpenBoxes | null }
+
 const changedCount = (count: number, noun: string): string => `${count} changed ${count === 1 ? noun : `${noun}s`}`
 
 const findingsResult = <T>(
@@ -132,7 +159,7 @@ const bareCodeReport: Report<RowWithBareCode> = {
   clean: 'no changed waiting row names a plan code bare',
 }
 
-const mergedReport: Report<MergedPhaseWithOpenBoxes> = {
+const mergedReport: Report<PhaseWithOpenBoxes> = {
   name: 'Merged phases with open boxes',
   noun: 'plan',
   rule: 'a merged phase ticks or moves on its open boxes',
@@ -205,7 +232,7 @@ const bareCodesOfBoard = (roots: readonly string[], file: Changed, language: Pla
     codesOfPlans(planTextsOf(roots, file, language), language),
   ).map(withPath(file.path))
 
-const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Found<MergedPhaseWithOpenBoxes>[] =>
+const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Found<PhaseWithOpenBoxes>[] =>
   base ? mergedPhasesWithOpenBoxes(current, base, language).map(withPath(path)) : []
 
 const unlistedOf = ({ path, current }: Changed, language: PlanLanguage): Found<PhaseWithoutRow>[] | null =>
@@ -227,6 +254,91 @@ const changedContents = ({ root, previousOf, baseOf, language }: PlanCheckInput,
       return { path, current, previous, previousLines, base: baseOf(path), board: hasLanesTable(current, language) }
     })
 
+const openBoxesText = (lane: string, partialWord: string, path: string, found: PhaseWithOpenBoxes): string =>
+  `${path}:${found.line} Phase ${found.id} ${found.title} is built by lane ${lane} but has open boxes at ${found.openLines.join(', ')}; tick them, end them with → P<n> or mark the row ${partialWord}`
+
+/** The open lane `input.lane` of the newest board that lists it, with the directory its plan links are relative to. */
+const laneOnBoards = (input: LaneBoxesInput): { lane: SprintLane; directory: string } | null => {
+  const boards = boardsIn(input.root, input).sort((left, right) => right.directory.localeCompare(left.directory))
+  for (const { directory, text } of boards) {
+    const lane = parseSprintLanes(text, input.language).find(({ name, closed }) => name === input.lane && !closed)
+    if (lane) return { lane, directory }
+  }
+  return null
+}
+
+/** The lane has work of its own in the checkout, so a phase it ticked further than the base is marked touched, as the herd reads it. */
+const CHECKOUT_WORK = { ahead: 1, dirty: 0 }
+
+/**
+ * The phases of the plan at `path` in the checkout; with the plan on the base too, those the checkout ticked further
+ * are marked touched, which is how the herd tells the phase a lane builds from the first open phase of its row.
+ */
+const phasesInCheckout = (input: LaneBoxesInput, path: string): PlanPhase[] => {
+  const text = readTextOrNull(join(input.root, path))
+  const base = input.baseOf(path)
+  const own = text === null ? [] : parsePlanPhases(text, input.language)
+  return base === null ? own : mergePlanPhases(parsePlanPhases(base, input.language), own, [], CHECKOUT_WORK)
+}
+
+/** The phase the lane's newest board row names, the plan it is in and whether the row marks it as built in parts. */
+const phaseBuiltBy = (input: LaneBoxesInput): BuiltPhase | null => {
+  const found = laneOnBoards(input)
+  if (!found) return null
+  const pathOf = (href: string): string => resolvePlanPath(found.directory, href)
+  const phasesByHref = Object.fromEntries(
+    found.lane.steps.flatMap(({ planHref }) =>
+      planHref === null ? [] : [[planHref, phasesInCheckout(input, pathOf(planHref))] as const],
+    ),
+  )
+  const progress = laneProgress(found.lane, phasesByHref)
+  const phase = currentPhase(progress)
+  const step = progress.current === null ? null : progress.steps[progress.current.stepIndex].step
+  if (!phase || !step?.planHref) return null
+  // with the base known, a phase this checkout did not tick further waits in the row; it is not what the lane builds
+  if (phase.work === undefined && input.baseOf(pathOf(step.planHref)) !== null) return null
+  const partial = step.label.includes(PLAN_VOCABULARY[input.language].partialPhase)
+  return { planPath: pathOf(step.planHref), phaseId: phase.id, partial }
+}
+
+/**
+ * The phase the lane's board row names and its open boxes, read from the checkout whether or not a commit changes the
+ * plan. Null for a lane the checkout's board does not list, for a row marked with the `partialPhase` word (`(Teil)`),
+ * which builds part of the phase, and for a phase ticked to the end, which is no longer the lane's current one.
+ */
+export const laneBuild = (input: LaneBoxesInput): LaneBuild | null => {
+  const built = phaseBuiltBy(input)
+  const plan = built && !built.partial ? readTextOrNull(join(input.root, built.planPath)) : null
+  return built && plan !== null
+    ? { path: built.planPath, open: openBoxesOfPhase(plan, input.language, built.phaseId) }
+    : null
+}
+
+/** What the level makes of a finding: `fail` fails, `warn` warns; `off` never reaches here. */
+const statusOf = (level: OpenBoxesLevel): typeof CHECK_STATUS.fail | typeof CHECK_STATUS.warn =>
+  level === OPEN_BOXES_LEVEL.warn ? CHECK_STATUS.warn : CHECK_STATUS.fail
+
+/**
+ * The open boxes of the phase the lane builds (`laneBuild`) as a check: `level` decides whether they fail, warn or are
+ * not looked at (`off` returns null).
+ */
+export const laneOpenBoxesCheck = (input: LaneBoxesInput & { level: OpenBoxesLevel }): CheckResult | null => {
+  if (input.level === OPEN_BOXES_LEVEL.off) return null
+  const started = Date.now()
+  const build = laneBuild(input)
+  if (!build) return null
+  const { open } = build
+  return {
+    name: 'Open boxes of the lane phase',
+    command: `lane ${input.lane}, the phase its board row names has no open box`,
+    status: open === null ? CHECK_STATUS.pass : statusOf(input.level),
+    detail: open
+      ? openBoxesText(input.lane, PLAN_VOCABULARY[input.language].partialPhase, build.path, open)
+      : 'the phase the lane builds has no open box left',
+    durationMs: Date.now() - started,
+  }
+}
+
 /**
  * The structure of the changed plans and boards:
  * - a phase the change added (against `HEAD`) with tasks and without a review gate fails;

package/src/check/report.ts

@@ -143,12 +143,18 @@ export const formatPlanHeader = (
   '',
 ]
 
+const ADVISORY_LINE = /^(hint|note):/
+
+/** A passing check shows only its advisory lines (`hint:`, `note:`); any other status shows its whole detail. */
+const shownDetail = ({ status, detail }: CheckResult): string[] => {
+  const lines = detail ? detail.split('\n') : []
+  return status === CHECK_STATUS.pass ? lines.filter((line) => ADVISORY_LINE.test(line)) : lines
+}
+
 export const formatResults = (results: readonly CheckResult[]): string[] =>
   results.flatMap((result) => [
     `${STATUS_ICON[result.status]} ${result.name}  (${result.command}, ${result.durationMs}ms)`,
-    ...(result.status !== CHECK_STATUS.pass && result.detail
-      ? result.detail.split('\n').map((line) => `     ${line}`)
-      : []),
+    ...shownDetail(result).map((line) => `     ${line}`),
   ])
 
 const warnings = (count: number): string => (count > 0 ? `${count} ${count === 1 ? 'warning' : 'warnings'}, ` : '')

package/src/check/schema.ts

@@ -68,6 +68,30 @@ const publicContent = z.strictObject({
 /** A budget in words per path or glob from the project root; a key joining two paths with ` + ` budgets them together. */
 const skillBudgets = z.record(glob, z.number().int().positive())
 
+/** What `jh check` does with open boxes in the phase a lane builds: fail, warn or leave the check out. */
+export const OPEN_BOXES_LEVEL = { fail: 'fail', warn: 'warn', off: 'off' } as const
+
+export type OpenBoxesLevel = (typeof OPEN_BOXES_LEVEL)[keyof typeof OPEN_BOXES_LEVEL]
+
+/** What `jh check` does with a lint-shaped rule block that names no lint rule: warn (the default), fail or leave the check out. */
+export const LINT_POINTERS_LEVEL = { warn: 'warn', fail: 'fail', off: 'off' } as const
+
+export type LintPointersLevel = (typeof LINT_POINTERS_LEVEL)[keyof typeof LINT_POINTERS_LEVEL]
+
+const lintPointers = z.strictObject({
+  /** `warn` reports a block and lets the commit through; `fail` stops it; `off` skips the check. */
+  level: z
+    .enum([LINT_POINTERS_LEVEL.warn, LINT_POINTERS_LEVEL.fail, LINT_POINTERS_LEVEL.off])
+    .default(LINT_POINTERS_LEVEL.warn),
+  /** Rule files left unread, as globs from the project root; the kit copies in the lock file are always left out. */
+  exclude: z.array(glob).default([]),
+})
+
+export type LintPointersConfig = z.infer<typeof lintPointers>
+
+/** The check without a `lintPointers` block: warn, nothing excluded. */
+export const DEFAULT_LINT_POINTERS: LintPointersConfig = { level: LINT_POINTERS_LEVEL.warn, exclude: [] }
+
 /**
  * The `check` block of `.jackherd/config.json`. Test and type commands come from the top-level
  * `commands` block; this block holds what only the check runner reads.
@@ -89,6 +113,19 @@ export const checkConfigSchema = z.strictObject({
    * path and sets one for the project's own skills; a file with none is measured against the kit's default.
    */
   skillBudgets: skillBudgets.optional(),
+  /**
+   * What a lane's check does when the phase its board row names still has open boxes without `→ P<n>`: `fail` (the
+   * default) stops the commit, `warn` reports, `off` skips. A row carrying the `partialPhase` word (`(Teil)` in German) builds part of the phase and is
+   * left alone; a branch whose directory is no lane's is not checked.
+   */
+  openBoxes: z
+    .enum([OPEN_BOXES_LEVEL.fail, OPEN_BOXES_LEVEL.warn, OPEN_BOXES_LEVEL.off])
+    .default(OPEN_BOXES_LEVEL.fail),
+  /**
+   * Whether a new or changed block of a rule file (or `CLAUDE.md`, `AGENTS.md`) that a linter could check, such
+   * as a forbidden import path or call, must name its lint rule with `` `lint:<rule id>` `` (or `` `lint:none` `` and a reason).
+   */
+  lintPointers: lintPointers.optional(),
   /** Also run tests in directories that hold test files but belong to no package. */
   looseTests: z.boolean().default(false),
   /**

package/src/check/settings.ts

@@ -25,6 +25,8 @@ export type CheckSettings = {
   baseBranch: string
   /** Where the lane worktrees live, below the main checkout: a board's plans are read there too. */
   worktreeDirectory: string
+  /** Where the boards live: the directories under `planDirectory` and the file in each. */
+  board: { pattern: string; file: string }
   /** Put before the kit's skill and agent names in this project; empty without one. */
   skillPrefix: string
   /** What the lock files (without one, the manifests) decide: one stack, none, or several (ambiguous); `stackOf` reads the stack from it. */
@@ -45,6 +47,7 @@ const planLanguageSchema = jackherdConfigSchema.shape.planLanguage
 const baseBranchSchema = jackherdConfigSchema.shape.baseBranch
 const worktreeDirectorySchema = jackherdConfigSchema.shape.worktreeDirectory
 const skillPrefixSchema = jackherdConfigSchema.shape.skillPrefix
+const boardSchema = jackherdConfigSchema.shape.board
 
 /**
  * The check runner's view of `.jackherd/config.json`: the shared `commands` block, `planDirectory`, `planLanguage` and `baseBranch` plus its own
@@ -62,6 +65,7 @@ export const parseCheckSettings = (raw: unknown, facts: RepositoryFacts): CheckS
     planLanguage: planLanguageSchema.parse(object.planLanguage),
     baseBranch: baseBranchSchema.parse(object.baseBranch),
     worktreeDirectory: worktreeDirectorySchema.parse(object.worktreeDirectory),
+    board: boardSchema.parse(object.board),
     skillPrefix: skillPrefixSchema.parse(object.skillPrefix),
     stack: detectStack(facts.lockFiles, facts.manifests),
     notes: detected.notes,

package/src/check/skill-budget-defaults.ts

@@ -8,11 +8,11 @@ export const KIT_FILE_FALLBACK_BUDGET = 2000
 export const SUPPLEMENT_BUDGET = 800
 
 /**
- * The kit's word budgets, by path from the project root. A key joining two paths with ` + ` budgets what is
- * loaded together. A budget is the measured size plus at most 10 %, so a file has room for a sentence, not for a
- * section; a file that needs more justifies the growth where it raises the number.
+ * The kit's word targets, by path from the project root: the size a file should have, not the size it has. A key
+ * joining two paths with ` + ` targets what is loaded together. A file above its target carries a ceiling in
+ * `KIT_SKILL_CEILINGS`; growth never moves a target.
  */
-export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
+export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   '.claude/skills/devops/SKILL.md': 321,
   '.claude/skills/diagnose/SKILL.md': 1521,
   '.claude/skills/diagnose/references/feedback-loops.md': 636,
@@ -22,36 +22,47 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/follow/SKILL.md': 1498,
   '.claude/skills/grill/SKILL.md': 685,
   '.claude/skills/implement/SKILL.md': 2190,
-  // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
-  // Plain words: no plan code without its words in a short question.
-  // Any language: a pointer in § 0 and a section in events.md for `plan missing`.
-  // Open up: a pointer in § 0 to adopt-plan.md, and § 2 step 8 waits until the lane works on its prompt (+113);
-  // step 0 lets the adoption diff stand for its question, step 2 bases on origin only for an unchanged plan.
-  // Cross-check: measured in a repository whose stack nothing detects, every unset command renders as a note (+7).
-  // Ready phase: the `done` / `idle` row names the watcher's mandatory `ready:` line (+20).
-  // Drafts until the merge: § 5 step 5 opens a draft and readies it, Self-merge step 3 waits for the runs after it (+100).
-  // Ready round: a PR of the lane waiting for approval or merge holds only the commit; the self-merge command runs
-  // alone, so the guard can check it (+132, the longest rendering of the kit's renderings); skill-review: the commit
-  // of a PR awaiting approval stages only its files, a branch over a squash-merged PR moves with `--onto` (+51).
-  '.claude/skills/orchestrate/SKILL.md': 8413,
+  '.claude/skills/orchestrate/SKILL.md': 4500,
   // skill-review: the copy is taken after a mirror, and rejecting together with a remark is a remark (+36).
   // Cross-check: an adopted plan also gets short names and a no-review-gate line, which `jh check` asks of a new
   // plan; the proof became a word diff, since a short name goes into an existing line (+74); skill-review: the
   // done check names `jh check`, the gate and short-name rules as the code reads them (+24).
   '.claude/skills/orchestrate/references/adopt-plan.md': 680,
   '.claude/skills/orchestrate/references/acceptance.md': 200,
-  '.claude/skills/orchestrate/references/close-lane.md': 250,
-  '.claude/skills/orchestrate/references/coordinator-handover.md': 551,
+  // Core cut: the `due` row of the wake-up table moved here (+33).
+  '.claude/skills/orchestrate/references/appointments.md': 290,
+  // Resume: `--branch` finishes a lane whose worktree is gone, a detached worktree on the base closes, a closed lane
+  // is reported (+41). The ask rule is the one question: the coordinator asks no dialog before it (+15).
+  '.claude/skills/orchestrate/references/close-lane.md': 309,
+  '.claude/skills/orchestrate/references/coordinator-handover.md': 567,
   '.claude/skills/orchestrate/references/draft-review.md': 300,
   // P33: a source entry the user must read or decide becomes a row of what waits on them, and when it closes.
-  '.claude/skills/orchestrate/references/events.md': 1166,
+  // Core cut: the `deploy`, `stalled` and lane `warn` rows of the wake-up table moved here (+101), and the checks
+  // after `Nothing changed.` from `jh check` (+70 as rendered), and the board patch when `main checkout behind`
+  // cannot fast-forward (+60). skill-review: `lane removed`, `no longer listed`, `did not stop` and
+  // `herd --ensure failed`, whose lines the watcher already points here (+86).
+  '.claude/skills/orchestrate/references/events.md': 1491,
   '.claude/skills/orchestrate/references/herd.md': 299,
-  '.claude/skills/orchestrate/references/lane-handover.md': 280,
-  '.claude/skills/orchestrate/references/lane-session.md': 280,
+  '.claude/skills/orchestrate/references/herd-ask.md': 152,
+  // Core cut: the request on `lane alert` moved here (+56); ending a lane names `herdr agent prompt <lane> /exit`,
+  // the form the merge guard passes (+23).
+  '.claude/skills/orchestrate/references/lane-handover.md': 360,
+  // Ending the agent names `herdr agent prompt <lane> /exit`, the form the merge guard passes (+25).
+  '.claude/skills/orchestrate/references/lane-session.md': 285,
   '.claude/skills/orchestrate/references/lane-setup.md': 380,
   // Open up: an adopted plan is committed like a missing one, and a tracked copy is restored after the merge.
-  '.claude/skills/orchestrate/references/plan-commit.md': 350,
+  // Core cut: the question of § 2 step 0 (the adoption's diff round, the approval it is, `<topic>`, a no) (+60).
+  '.claude/skills/orchestrate/references/plan-commit.md': 412,
+  // Core cut: § 5 self-merge steps 1 to 6, moved out of the core.
+  '.claude/skills/orchestrate/references/self-merge.md': 379,
   '.claude/skills/orchestrate/references/sensitive-input.md': 269,
+  '.claude/skills/orchestrate/references/stage-approval.md': 634,
+  '.claude/skills/orchestrate/references/standing-approval.md': 458,
+  // Core cut: § 2 steps 0 to 8 and § 3 dev server, moved out of the core.
+  '.claude/skills/orchestrate/references/start-lane.md': 712,
+  // Core cut: § 4 waiting rows beyond the basic one, moved out of the core.
+  '.claude/skills/orchestrate/references/waiting.md': 216,
+  '.claude/skills/orchestrate/references/watch-without-monitor.md': 154,
   '.claude/skills/plan/SKILL.md': 1920,
   '.claude/skills/plan/references/template-English.md': 536,
   '.claude/skills/plan/references/template-German.md': 501,
@@ -61,9 +72,7 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   // Any language: step 3 points to proposing the missing commands from the CI; the proposal itself is a reference.
   '.claude/skills/start/SKILL.md': 630,
   '.claude/skills/uncle-bob/SKILL.md': 466,
-  // P33 and open up: grows with the skill above (+132 for the ready round and the lone merge call); measured with
-  // this repository's supplement after the skill-review fixes (+153).
-  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 9165,
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 5100,
   '.claude/agents/devops.md': 104,
   '.claude/agents/explore.md': 132,
   '.claude/agents/implement.md': 303,
@@ -73,8 +82,50 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/agents/skill-review.md': 468,
   '.claude/agents/spec-review.md': 1137,
   '.claude/agents/uncle-bob.md': 111,
-  '.claude/rules/kit/code-style.md': 1664,
+  // Lint before prose: the vocabulary section and two one-liners cut, a sentence on `lint:` pointers added (-79).
+  '.claude/rules/kit/code-style.md': 1585,
   // Drafts until the merge: a precondition opens a draft when `merge.openAsDraft` says so (+39).
   '.claude/rules/kit/pull-requests.md': 640,
   '.claude/rules/kit/testing.md': 741,
 }
+
+/**
+ * The most a file above its target may have, today's size. A ceiling only falls: the plan that cuts the file lowers
+ * or deletes it, and a rise needs a reason in the comment above the entry (a test holds every entry to one).
+ */
+export const KIT_SKILL_CEILINGS: Readonly<Record<string, number>> = {
+  // Orchestrate core plan P1: the reviewer also judges the whole length of a file against its target (+12).
+  // Lint before prose: lens 7 for lint-shaped prose and the sentence on the `Lint pointers` result (+33).
+  '.claude/agents/skill-review.md': 513,
+  // Lint before prose: the quality check that asks of every written rule whether the linter can check it (+44).
+  '.claude/skills/plan/SKILL.md': 1964,
+  // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
+  // Plain words: no plan code without its words in a short question.
+  // Any language: a pointer in § 0 and a section in events.md for `plan missing`.
+  // Open up: a pointer in § 0 to adopt-plan.md, and § 2 step 8 waits until the lane works on its prompt (+113);
+  // step 0 lets the adoption diff stand for its question, step 2 bases on origin only for an unchanged plan.
+  // Cross-check: measured in a repository whose stack nothing detects, every unset command renders as a note (+7).
+  // Ready phase: the `done` / `idle` row names the watcher's mandatory `ready:` line (+20).
+  // Drafts until the merge: § 5 step 5 opens a draft and readies it, Self-merge step 3 waits for the runs after it (+100).
+  // Ready round: a PR of the lane waiting for approval or merge holds only the commit; the self-merge command runs
+  // alone, so the guard can check it (+132, the longest rendering of the kit's renderings); skill-review: the commit
+  // of a PR awaiting approval stages only its files, a branch over a squash-merged PR moves with `--onto` (+51).
+  // Change id: the PR question names the staged change's patch id, which the merge guard compares; skill-review:
+  // staging first and the worktree named (+55, to cut again).
+  // Bundled board lines: written into the main checkout at once, carried to the base bundled, and the fast-forward
+  // that keeps them (+115).
+  // Audit P6: commands and hooks carry rules the prose repeated; monitorless watching, appointments, the standing
+  // approval and the herd's ask line moved to references. Cut to the measured size plus 5 %.
+  // Orchestrate core plan P1: the target is 4500. P5 cut the core to its longest rendering; the rest of the cut is
+  // a follow-up, decided by the user after the P6 runs.
+  '.claude/skills/orchestrate/SKILL.md': 5938,
+  // P33 and open up: grows with the skill above (+132 for the ready round and the lone merge call); measured with
+  // this repository's supplement after the skill-review fixes (+153); click merge grows with the skill (+30); change
+  // id grows with the skill, staging first and the worktree named after skill-review (+55). Audit P6: cut with the
+  // skill, the supplement down to its deviations; measured size plus 5 %.
+  // Orchestrate core plan P1: the target is 5100; P5 lowered the ceiling with the skill's to the rendered sum.
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 6635,
+}
+
+/** What `jh check` measures against: a file's ceiling where it has one, else its target. */
+export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = { ...KIT_SKILL_TARGETS, ...KIT_SKILL_CEILINGS }

package/src/check/skill-budgets.ts

@@ -11,6 +11,7 @@ import type { SkillBudgets } from './schema'
 import {
   KIT_FILE_FALLBACK_BUDGET,
   KIT_SKILL_BUDGETS,
+  KIT_SKILL_TARGETS,
   OWN_SKILL_BUDGET,
   SUPPLEMENT_BUDGET,
 } from './skill-budget-defaults'
@@ -21,8 +22,18 @@ export type BudgetTable = Readonly<SkillBudgets>
 /** A file with the budget it falls back on when neither the project nor the kit names one. */
 export type FileWords = { path: string; words: number; fallback: number; foreign?: boolean }
 
-/** A `foreign` measurement belongs to a skill `skills-lock.json` lists: it warns, it never fails. */
-export type Measurement = { label: string; words: number; budget: number; foreign?: boolean }
+/**
+ * A `foreign` measurement belongs to a skill `skills-lock.json` lists: it warns, it never fails. `target` is the
+ * kit's target for the path, `projectBudget` is the project's own entry for the path.
+ */
+export type Measurement = {
+  label: string
+  words: number
+  budget: number
+  foreign?: boolean
+  target?: number
+  projectBudget?: number
+}
 
 type Overrun = typeof CHECK_STATUS.warn | typeof CHECK_STATUS.fail
 
@@ -63,12 +74,16 @@ export const overrunOf = (words: number, budget: number): Overrun | null => {
   return words > budget ? CHECK_STATUS.warn : null
 }
 
-/** The project's entry for the exact path, else its first glob that matches, else the kit's default, else `fallback`. */
-export const budgetOf = (path: string, project: BudgetTable, defaults: BudgetTable, fallback: number): number => {
+/** The project's entry for the exact path, else its first glob that matches; undefined when it names neither. */
+const projectBudgetOf = (path: string, project: BudgetTable): number | undefined => {
   const glob = Object.keys(project).find((key) => isGlob(key) && matchesGlob(path, key))
-  return project[path] ?? (glob === undefined ? undefined : project[glob]) ?? defaults[path] ?? fallback
+  return project[path] ?? (glob === undefined ? undefined : project[glob])
 }
 
+/** The project's entry for the exact path, else its first glob that matches, else the kit's default, else `fallback`. */
+export const budgetOf = (path: string, project: BudgetTable, defaults: BudgetTable, fallback: number): number =>
+  projectBudgetOf(path, project) ?? defaults[path] ?? fallback
+
 /** Every budget path starts with `.claude/` (the kit-content test holds them to shipped files). */
 const prefixedPath = (path: string, prefix: string): string =>
   claudePath(prefixedKitPath(path.slice(CLAUDE_DIRECTORY.length + 1), prefix))
@@ -91,23 +106,39 @@ const sumEntry = (key: string, files: readonly FileWords[]): number | null => {
   return parts.every((part) => part !== undefined) ? parts.reduce((total, part) => total + part.words, 0) : null
 }
 
-/** Every file against its budget, then every sum entry of the project and the kit whose files all exist. */
+/**
+ * Every file against its budget, then every sum entry of the project and the kit whose files all exist. `targets`
+ * are the kit's targets by path; a measurement carries its own when the kit names one.
+ */
 export const measureFiles = (
   files: readonly FileWords[],
   project: BudgetTable,
   defaults: BudgetTable,
+  targets: BudgetTable = {},
 ): Measurement[] => {
   const single = files.map(({ path, words, fallback, foreign }) => ({
     label: foreign ? `${path} ${FOREIGN_LABEL}` : path,
     words,
     budget: budgetOf(path, project, defaults, fallback),
     foreign,
+    target: targets[path],
+    projectBudget: projectBudgetOf(path, project),
   }))
   const sums = [...new Set([...Object.keys(project), ...Object.keys(defaults)])]
     .filter((key) => key.includes(SUM_SEPARATOR))
     .flatMap((key) => {
       const words = sumEntry(key, files)
-      return words === null ? [] : [{ label: key, words, budget: budgetOf(key, project, defaults, 0) }]
+      return words === null
+        ? []
+        : [
+            {
+              label: key,
+              words,
+              budget: budgetOf(key, project, defaults, 0),
+              target: targets[key],
+              projectBudget: projectBudgetOf(key, project),
+            },
+          ]
     })
   return [...single, ...sums]
 }
@@ -128,17 +159,33 @@ const statusOf = (overruns: readonly MeasuredOverrun[]): CheckStatus => {
   return overruns.length > 0 ? CHECK_STATUS.warn : CHECK_STATUS.pass
 }
 
-/** One line per overrun; one line in total when none is over. Warns above a budget, fails above the budget plus 10 %. */
+/** A file within the kit's ceiling but above the kit's target for it: a hint, never a failure. A project budget has its note instead. */
+const targetHint = ({ label, words, budget, target, projectBudget }: Measurement): string[] =>
+  target !== undefined && projectBudget === undefined && words > target && budget > target
+    ? [`hint: ${label} is over target by ${words - target} words (target ${target}, ceiling ${budget})`]
+    : []
+
+/** A budget the project set above the kit's target for the path: shown, so the deviation stays visible. */
+const overrideNote = ({ label, target, projectBudget }: Measurement): string[] =>
+  target !== undefined && projectBudget !== undefined && projectBudget > target
+    ? [`note: ${label} budget ${projectBudget} comes from the project, above the kit target ${target}`]
+    : []
+
+/**
+ * One line per overrun; one line in total when none is over. Warns above a budget, fails above the budget plus 10 %.
+ * Lines for a file over its target and for a project budget above the kit target follow, and change no status.
+ */
 export const budgetResult = (measured: readonly Measurement[], durationMs: number): CheckResult => {
   const overruns = measured.flatMap((entry) => {
     const overrun = overrunOfMeasurement(entry)
     return overrun === null ? [] : [{ entry, overrun }]
   })
+  const lines = overruns.length > 0 ? overruns.map(overrunLine) : [withinLine(measured.length)]
   return {
     name: 'Skill budgets',
     command: `${measured.length} measured, words per budget`,
     status: statusOf(overruns),
-    detail: overruns.map(overrunLine).join('\n') || withinLine(measured.length),
+    detail: [...lines, ...measured.flatMap(targetHint), ...measured.flatMap(overrideNote)].join('\n'),
     durationMs,
   }
 }
@@ -211,5 +258,6 @@ export const skillBudgetCheck = (root: string, project: BudgetTable = {}, skillP
     ...ownSkillPaths(root, kit).flatMap((path) => fileWordsOf(root, path, OWN_SKILL_BUDGET)),
   ].map(markForeign(foreign))
   const defaults = prefixedBudgets(KIT_SKILL_BUDGETS, skillPrefix)
-  return files.length === 0 ? null : budgetResult(measureFiles(files, project, defaults), Date.now() - started)
+  const targets = prefixedBudgets(KIT_SKILL_TARGETS, skillPrefix)
+  return files.length === 0 ? null : budgetResult(measureFiles(files, project, defaults, targets), Date.now() - started)
 }

package/src/cli.ts

@@ -18,6 +18,7 @@ const ALIASES = new Set<string>([HERD_COMMAND.alias])
 
 /** One line per command; each entry lazily imports the module that exports its `run`. */
 export const COMMANDS: CommandTable = {
+  approval: () => import('./approval/command'),
   check: () => import('./check/command'),
   config: () => import('./config/command'),
   context: () => import('./context/command'),
@@ -28,6 +29,7 @@ export const COMMANDS: CommandTable = {
   mermaid: () => import('./mermaid/command'),
   plan: () => import('./plan-contract/command'),
   preview: () => import('./preview/command'),
+  resume: () => import('./resume/command'),
   secret: () => import('./secrets/command'),
   settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),