jackherd 1.9.0 → 1.11.0

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

@@ -35,7 +35,9 @@ Skip this when the request already carries its decisions (a plan for a bug fix w
 
 The closing documentation section reads `## N — …` with rows `N.1` to `N.5`: replace `N` with the number of that phase (`## 10 — …`, `10.1`). A literal `N` is no phase to the herd, which shows it as "not in the plan".
 
-A checkbox moved on purpose to a later phase stays where it is, unticked, and ends in the target: `- [ ] Update the documentation → P9`. The herd counts it neither as open nor as done in its own phase and lists it as open in phase 9, so a phase whose only open box was moved on reads as finished. The arrow counts only at the end of the line; `jh check` refuses an open box in a changed plan that carries it anywhere else (`- [ ] → P9 Update …`). Once a phase's tasks are ticked on the base branch and the change does not tick it further, every box still open in it, gate boxes included, is ticked or moved on this way: `jh check` warns on a changed plan that leaves one.
+A checkbox moved on purpose to a later phase stays where it is, unticked, and ends in the target: `- [ ] Update the documentation → P9`. The herd counts it neither as open nor as done in its own phase and lists it as open in phase 9. The arrow stands only at the end of the line. Once a phase's tasks are ticked on the base branch, every box still open in it, gate boxes included, is ticked or moved on this way; `jh check` checks both.
+
+A task starts with its short name: `- [ ] **Name**: …` (a review-gate item keeps its own form). The name has 40 characters at most and names the subject and the result, what is different afterwards (`Heartbeat shows progress without ticks`, `` `ask-hint` finds questions anywhere ``); the how, the conditions, the origin and the evidence follow the colon. A phase's title is its name, its context goes into the origin line. A task the user adds later: `- [ ] **Name**: … (User <DD.MM.> <HH:MM>)`.
 
 What the template's tables mean:
 
@@ -67,7 +69,7 @@ Every phase gets the review gate block from the template at its end. Add the rev
 - **Shared code checked:** For every planned component it is documented why it is built new instead of reused or extended.
 - **Tests defined:** The tests section is filled in or carries an explicit rationale why none are needed (decision tree in `.claude/rules/kit/testing.md`).
 - **Model recommendations defined:** `## {{kit.heading.implementation}}` starts with the model table, one row per phase, justified by error cost × complexity.
-- **Parallelism defined (3+ phases):** the dependencies table follows it. Check it against the phase bodies: every migration, schema bump and new event in a phase appears as a serial marker; every shared file appears under {{kit.heading.writes}}. A dependency that exists only in your head lets `/implement` start two phases that collide. Every phase gets a row, a phase added later too: `jh check` warns about a phase without one.
+- **Parallelism defined (3+ phases):** the dependencies table follows it, a row for every phase, one added later too. Every migration, schema bump and new event of a phase is a serial marker, every shared file stands under {{kit.heading.writes}}; otherwise `/implement` starts two phases that collide.
 - **arc42 check (after the plan exists):** apply the filter in `.claude/rules/kit/arc42.md` to the finished plan and **ask the user concretely** which sections should be extended. On "yes", add a concrete task to `## {{kit.heading.documentation}}`.
 - **Architecture check (after the plan exists):** apply the filter in `.claude/rules/kit/architecture-files.md` — new ownership, a new invariant or an accepted risk each trigger a concrete question about the unit's `ARCHITECTURE.md`.
 - **arc42 closing phase (3+ phases or a new service/package):** end the plan with the architecture documentation phase from the template. Add arc42 sections beyond it only when they deliver real value.
@@ -94,9 +96,8 @@ Derive the rows from the dependencies table and the model table, nothing else:
 - **Plan:** a Markdown link to the plan, its path relative to the board's directory (`../<file>.md` for a plan
   directly under `{{kit.planDirectory}}`).
   Plans stay where they are; the row only links them.
-- **Lane name:** short kebab case, unique on the board. `/orchestrate` names the worktree directory and the herdr
-  agent after it, so the worktree directory and the herdr agent carry the same name; a name that differs leaves the
-  watcher reporting the lane as `no agent`.
+- **Lane name:** short kebab case, unique on the board; the worktree directory and the herdr agent carry the same name
+  (`/orchestrate` § 2).
 - **Port:** `–`; the coordinator sets it when the lane starts, unless the project supplement assigns ports here.
 
 Show the rows as the table they become: `## {{kit.heading.lanes}}` with the columns lane, port, plan, phases, starts

package/kit/workflow/skills/plan/references/template-English.md

@@ -42,8 +42,8 @@ What changes concretely? Files, modules, flows.
 
 ### {{kit.heading.phase}} 1: ...
 
-- [ ] Step 1
-- [ ] Step 2
+- [ ] **Name of step 1**: how, conditions, origin, evidence
+- [ ] **Name of step 2**: how, conditions, origin, evidence
 
 **Review gate {{kit.heading.phase}} 1:**
 
@@ -67,13 +67,13 @@ Which tests are needed? Decide with the decision tree in `.claude/rules/kit/test
 
 What gets documented after completion?
 
-- [ ] ...
+- [ ] **Name**: ...
 
 ## Follow-ups
 
 > Ideas that come up during the work: noted here, not built in this plan, presented together once the release PR is merged.
 
-- [ ] The idea in one sentence (User <DD.MM.> <HH:MM>, where it came up)
+- [ ] **Name**: the idea in one sentence (User <DD.MM.> <HH:MM>, where it came up)
 
 ## Rejected Alternatives
 

package/kit/workflow/skills/plan/references/template-German.md

@@ -42,8 +42,8 @@ Was ändert sich konkret? Dateien, Module, Flows.
 
 ### {{kit.heading.phase}} 1: ...
 
-- [ ] Schritt 1
-- [ ] Schritt 2
+- [ ] **Name von Schritt 1**: Wie, Bedingungen, Herkunft, Beleg
+- [ ] **Name von Schritt 2**: Wie, Bedingungen, Herkunft, Beleg
 
 **Review-Gate {{kit.heading.phase}} 1:**
 
@@ -67,13 +67,13 @@ Welche Tests sind nötig? Entscheidung nach dem Entscheidungsbaum in `.claude/ru
 
 Was wird nach Abschluss dokumentiert?
 
-- [ ] ...
+- [ ] **Name**: ...
 
 ## Follow-ups
 
 > Ideen, die während der Umsetzung aufkommen: hier vorgemerkt, nicht in diesem Plan gebaut, gesammelt vorgelegt, sobald der Release-PR gemergt ist.
 
-- [ ] Idee in einem Satz (User <TT.MM.> <HH:MM>, wo sie aufkam)
+- [ ] **Name**: Idee in einem Satz (User <TT.MM.> <HH:MM>, wo sie aufkam)
 
 ## Verworfene Alternativen
 

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "jackherd",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "keywords": [
     "claude-code",
     "coding-agents",
     "ai-agents",
     "agent-skills",
     "subagents",
+    "multi-agent",
     "orchestration",
+    "plan-driven",
     "git-worktree",
     "herdr",
     "planning",

package/recipes/README.md

@@ -15,7 +15,8 @@ Each recipe is one `watch.sources` entry for the jackherd watcher: put in your k
 ## Rules every recipe follows
 
 - **A token never goes into an argument:** an argument shows in the process list. Where a tool keeps its own login, it is used; where a token sits in an environment variable, a small TypeScript script run by Bun (which runs wherever `jh` does) puts it from `process.env` straight into the request header.
-- **A script fails with an exit code**, never with an empty answer the watcher would take for a source with nothing new, and it prints neither the token nor the body of a failed answer. Every request and every tool call is bounded with `AbortSignal.timeout(20_000)`, well under the 30 seconds a source may run.
+- **A script prints one JSON value on stdout and nothing else.**
+- **A script fails with an exit code**, never with an empty answer the watcher would take for a source with nothing new, and it prints neither the token nor the body of a failed answer. A 200 that carries an `errors` list, as GraphQL answers, is a failure too. Every request and every tool call is bounded with `AbortSignal.timeout(20_000)`, well under the 30 seconds a source may run.
 - **The scripts are files of their own** under [`sources/`](sources/). Copy one to `scripts/sources/<name>.ts` in your repository, the path the entry's `command` names. The closing `export {}` makes the file a module, so the type check accepts top-level `await` and the names do not clash between scripts.
 - **A recipe that needs no script** (`gh …`, `curl` on a public page, `curl --netrc`) stays a direct command.
 - **`bun` as the first word, never a path to it.** The watcher starts a source without a shell and reads `bun` to mean the Bun that runs the watcher itself, so the entry needs no absolute path, which would differ from machine to machine, even when Bun is not on the `PATH` (installed in `~/.bun/bin` only, say).

package/recipes/sources.md

@@ -36,7 +36,7 @@ Source reports are off unless the config lists `watch.sources`. The watcher cann
 
 `items` is the path of the list in the output (without it the output is the list), `map` picks each entry's fields: `id` is required, `updatedAt` too unless a content field (`title`, `author`, `body`, `url`) or `reportOn` can tell a change, and `title`, `url`, `body`, `author` and `status` (a ticket's status, below) are optional; any further field you name (`priority`, `assignee`; a letter, then letters, digits and `_`) is read for `reportOn`. A path is `.` for the whole value or a chain of `.key`, `[n]` and `[-n]` (counted from the end), nothing more; for anything else, put a script in between.
 
-What counts as news: an unknown `id` reports `new`; `updated` only when what you read changed, a short hash over `title`, `author`, `body` and `url`. A change of the time alone (a label, a sprint, a status) wakes nobody; where none of the four is mapped, `updatedAt` is the content, and then it is required. An entry whose `author` is in `ignoreAuthors` (case ignored) is recorded but wakes nobody, so your own comment does not. The first successful run of a source is a baseline, and the saved state holds per source only each id with its hash (with `reportOn` also the values of those fields, which may name people, such as an assignee), the 1000 seen most recently, so a restart repeats nothing and an entry that falls out of a time window and comes back is not new. Everything one GitHub read finds goes into one report, at most `reportLimit` entries per source (`5`), the rest as one line `=== source tickets +3 more`. The body shows its first line with text that is no Markdown heading (a bot's `## Code review` is skipped; a body of headings only shows the first), at most 160 characters, and the URL only as an `https:` URL without user name or password. `every` is in minutes, at least 1, `5` by default; the sources run with the GitHub read, so at most once a minute, and after a restart each runs at once.
+What counts as news: an unknown `id` reports `new`; `updated` only when what you read changed, a short hash over `title`, `author`, `body` and `url`. A change of the time alone (a label, a sprint, a status) wakes nobody; where none of the four is mapped, `updatedAt` is the content, and then it is required. An entry whose `author` is in `ignoreAuthors` (case ignored) is recorded but wakes nobody, so your own comment does not. The first successful run of a source is a baseline, and the saved state holds per source only each id with its hash (with `reportOn` also the values of those fields, which may name people, such as an assignee), the 1000 seen most recently, so a restart repeats nothing and an entry that falls out of a time window and comes back is not new. Everything one GitHub read finds goes into one report, at most `reportLimit` entries per source (`5`), the rest as one line `=== source tickets +3 more`. The body shows its first line with text that is no Markdown heading (a bot's `## Code review` is skipped; a body of headings only shows the first), at most 160 characters, and the URL only as an `https:` URL without user name or password. `every` is in minutes, at least 1, `5` by default; the sources run with the GitHub read, so at most once a minute. The saved state keeps when each source last ran, failed or not, so a restart runs a source only once its `every` has passed; a source the state does not know yet, a new one or one from a state written before that time was kept, runs at once.
 
 **Report a status change.** `reportOn` names the mapped fields whose change reports, in place of the content hash: with `"reportOn": ["status"]` a ticket that moves from one column to the next wakes the coordinator, and a new comment alone does not. The report names each changed field with its old and new value, cut to 60 characters, `(empty)` for none, in one line; the body follows only when `body` is one of the changed fields. An unknown `id` still reports `new`, and `ignoreAuthors`, `reportLimit` and the one report per read stay as they are. `status` is just a field name: any mapped field but `id` may be listed, including `title` or `body`.
 
@@ -60,6 +60,10 @@ A run that ends with an exit code other than 0, runs past 30 seconds (then its w
 
 **Show a ticket beside its plan.** `"ticket": true` marks a source's entries as tickets. The herd then shows each one as a badge in the 📎 line of its lane's plan, right after `📄 Plan`: `📡 T-123 · In Progress`, linked to the ticket. A ticket belongs to the source's `lane`, and also to any lane whose board row, name or plan names its id as a whole word (`T-12` is not found in `T-123`); so one source listing all your open tickets works without `lane`. `map.status` is the status the badge shows; without it the badge shows only the key. A ticket whose last reported change is less than a day old is amber, and a folded lane then shows `📡 <n>` in amber before its bar, linked to the first new ticket. A lane shows at most three tickets, new ones first, then `+<n>`; a link chip of the plan with the same URL gives way to the badge. For this the saved state keeps, of a marked source only, each entry of its last successful run with its URL, its status (stored like a `reportOn` value) and the time its last change was reported. The badges come from the watcher's state like the pull request badges: without a running watcher or with a state older than three minutes there are none, and the header says `watcher off` or `state 4 min old`, also without a pull request. The [GitHub Projects recipe](#user-content-recipes) is a ticket source with a status.
 
+**Show a source in the herd.** A source without `ticket` appears in the herd's `Sources` block, one row each: its name, when it last ran (`ran 12 min ago`), since when it fails (`failing since 3 h ago`, mark red) and its newest report (mark amber while that report is under a day old). A source with several entries is one folded row; a click opens its entries (up to five, then `+<n> more`), each with its title, `map.count` as `113×` and the time of its last change. A click on an entry opens its `url` (the watcher keeps it only as a checked `https:` URL of at most 200 characters, so map a short link), `[ask]` asks the coordinator to look at that entry. An entry that an open row of "Waiting for you" already asks about (the row's `Origin` names the source and its text the title) is dim and says `↑ asked`; the row is amber only for a new entry nobody asked about. The watcher keeps the last 20 entries of such a source. `tone` (amber, teal, grey, red, green, blue or magenta) sets the mark's colour while the report is new, instead of the tone of the role `new`; the roles `waiting`, `new`, `running` and `resting` take their tones from `plans.tones` in the config (defaults: amber, amber, teal, grey).
+
+**Name a source in "Waiting for you".** A row of the board's waiting section whose `Origin` cell is the name of a source (case ignored) shows `<label>: <row>` in the herd; `label` (one line, at most 40 characters) is optional, without it the source's name stands before the row. `/jh-follow` proposes a short label when it writes the entry.
+
 **How you hear about it.** The report goes to the coordinator, as a `=== source …` event of its watcher. It passes you one line with the entry, its gist and the link. A decision inside it, such as a product owner's answer, it takes over only after you confirmed it, since the text comes from outside. You hear of it only while the coordinator's session and its watcher run; what happened in between is reported at the next start. There is no desktop notification of its own: you get the one herdr shows for any lane that needs you. What a source reports is a change in the mapped content fields (`title`, `author`, `body`, `url`), or with `reportOn` a change of the fields it names, such as a status.
 
 **Try a source before the watcher runs it.** `jh watch source <name> --dry-run` runs a configured source once; a draft not yet in the config comes as a file (`jh watch source draft.json --dry-run`, one source object) or on stdin (`-`). It lists the entries (`<id> · <author> · <title>`), says that the watcher's first run of the source is a baseline and reports nothing, and shows one entry as a later report would print it; it neither reads nor changes the watcher's state. A field of `map` that is empty in every entry is named with its path (`map.updatedAt: in 23 of 23 entries empty (.fields.updated)`), read from the raw output, so a run that failed on a missing `id` or `updatedAt` names it too; the dry run then ends with exit code 1, as for a failed run, and `/jh-follow` does not write the source. Without entries it says `0 entries: map not checked`. `--raw` adds the command's output, for finding the paths of `items` and `map`:

package/schemas/jackherd.schema.json

@@ -297,6 +297,65 @@
             }
           },
           "additionalProperties": false
+        },
+        "tones": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "waiting": {
+              "default": "amber",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            },
+            "new": {
+              "default": "amber",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            },
+            "running": {
+              "default": "teal",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            },
+            "resting": {
+              "default": "grey",
+              "type": "string",
+              "enum": [
+                "amber",
+                "teal",
+                "grey",
+                "red",
+                "green",
+                "blue",
+                "magenta"
+              ]
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false
@@ -381,10 +440,36 @@
               "type": "integer",
               "exclusiveMinimum": 0,
               "maximum": 9007199254740991
+            },
+            "auto": {
+              "type": "object",
+              "properties": {
+                "since": {
+                  "type": "string",
+                  "format": "date",
+                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
+                },
+                "until": {
+                  "type": "string",
+                  "format": "date",
+                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
+                }
+              },
+              "required": [
+                "since",
+                "until"
+              ],
+              "additionalProperties": false
             }
           },
           "additionalProperties": false
         },
+        "taskSignalMinutes": {
+          "default": 10,
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
         "previews": {
           "type": "object",
           "properties": {
@@ -457,6 +542,9 @@
                   },
                   "status": {
                     "type": "string"
+                  },
+                  "count": {
+                    "type": "string"
                   }
                 },
                 "required": [
@@ -480,6 +568,12 @@
                 "minimum": 1,
                 "maximum": 9007199254740991
               },
+              "label": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 40,
+                "pattern": "^[^\\r\\n]+$"
+              },
               "lane": {
                 "type": "string",
                 "minLength": 1
@@ -487,6 +581,18 @@
               "ticket": {
                 "type": "boolean"
               },
+              "tone": {
+                "type": "string",
+                "enum": [
+                  "amber",
+                  "teal",
+                  "grey",
+                  "red",
+                  "green",
+                  "blue",
+                  "magenta"
+                ]
+              },
               "reportOn": {
                 "minItems": 1,
                 "maxItems": 10,
@@ -515,9 +621,7 @@
         "commands": {
           "default": [
             "gh pr merge",
-            "gh workflow run",
-            "gh run rerun",
-            "gh api"
+            "gh workflow run"
           ],
           "type": "array",
           "items": {
@@ -555,12 +659,26 @@
           },
           "additionalProperties": false
         },
+        "alwaysAsk": {
+          "default": [],
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9_.*/-]+$"
+          }
+        },
+        "requiredChecks": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "maxLength": 200
+          }
+        },
         "planApproval": {
-          "default": {},
+          "deprecated": true,
           "type": "object",
           "properties": {
             "exceptPaths": {
-              "default": [],
               "type": "array",
               "items": {
                 "type": "string",
@@ -602,6 +720,10 @@
         "askUserQuestion": {
           "default": true,
           "type": "boolean"
+        },
+        "taskSignal": {
+          "default": true,
+          "type": "boolean"
         }
       },
       "additionalProperties": false
@@ -741,6 +863,18 @@
           ],
           "additionalProperties": false
         },
+        "skillBudgets": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "minLength": 1
+          },
+          "additionalProperties": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          }
+        },
         "looseTests": {
           "default": false,
           "type": "boolean"

package/src/check/agent-text-reviewers.ts

@@ -0,0 +1,23 @@
+import { matchesAnyGlob } from './glob'
+
+/** The kit agent that judges how a changed agent text steers its reader. */
+export const AGENT_TEXT_REVIEWER = 'skill-review'
+
+/**
+ * Texts an agent reads as instructions, wherever they sit: the project's `.claude/` and a kit source tree alike.
+ * Only Markdown counts, so a script beside a skill or a source directory named `agents` stays out.
+ */
+const AGENT_TEXT_GLOBS = [
+  '**/skills/**/*.md',
+  '**/agents/**/*.md',
+  '**/rules/**/*.md',
+  '.claude/project/**/*.md',
+  '**/CLAUDE.md',
+  '**/AGENTS.md',
+] as const
+
+export const isAgentTextPath = (path: string): boolean => matchesAnyGlob(path, AGENT_TEXT_GLOBS)
+
+/** The agent-text reviewer when a change touches an agent text. */
+export const agentTextReviewers = (paths: readonly string[]): string[] =>
+  paths.some(isAgentTextPath) ? [AGENT_TEXT_REVIEWER] : []

package/src/check/command.ts

@@ -15,6 +15,7 @@ import { publicContentCheck } from './public-content-check'
 import { artifactResult, formatPlanHeader, formatResults, skippedSlowResult, summarize } from './report'
 import { type CheckResult, SKIP_SLOW_FLAG } from './result'
 import { type CheckSettings, CONFIG_PATH, parseCheckSettings } from './settings'
+import { skillBudgetCheck } from './skill-budgets'
 
 type CheckTarget = { root: string; configPath: string }
 
@@ -154,6 +155,7 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
   const results = await executePlan(plan, root, args.includes(SKIP_SLOW_FLAG), [
     publicContent,
     deferralArrows,
+    skillBudgetCheck(root, settings.check.skillBudgets),
     ...planStructure,
   ])
   print(formatResults(results))

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

@@ -4,10 +4,13 @@ import {
   boardRowsWithoutPhase,
   boardRowsWithProse,
   hasLanesTable,
+  type LongPhaseTitle,
+  longPhaseTitles,
   type MergedPhaseWithOpenBoxes,
   mergedPhasesWithOpenBoxes,
   newPhasesWithoutReviewGate,
   PHASE_CELL_LIMIT,
+  PHASE_TITLE_LIMIT,
   type PhaseWithoutGate,
   type PhaseWithoutRow,
   PLAN_VOCABULARY,
@@ -17,6 +20,10 @@ import {
   phasesWithoutDependencyRow,
   type RowWithoutPhase,
   type RowWithProse,
+  SHORT_NAME_LIMIT,
+  SHORT_NAME_PROBLEM,
+  type ShortNameFinding,
+  shortNameFindings,
 } from '../plan-format'
 import { changedPlansOf } from './deferral-arrows'
 import { CHECK_STATUS, type CheckResult } from './result'
@@ -129,6 +136,30 @@ const unlistedReport: Report<PhaseWithoutRow> = {
   clean: 'every phase has a row in the dependency table',
 }
 
+const shortNameText = (found: Found<ShortNameFinding>): string =>
+  found.problem === SHORT_NAME_PROBLEM.long
+    ? `${found.path}:${found.line} Phase ${found.phase}: the short name has ${found.length} characters (limit ${SHORT_NAME_LIMIT})`
+    : `${found.path}:${found.line} Phase ${found.phase}: open task has no short name; start it with - [ ] **Name**: (${SHORT_NAME_LIMIT} characters at most)`
+
+const shortNameReport: Report<ShortNameFinding> = {
+  name: 'Task short names',
+  noun: 'plan',
+  rule: 'open tasks the change wrote start with a short name',
+  unmet: CHECK_STATUS.warn,
+  text: shortNameText,
+  clean: 'every open task the change wrote has a short name',
+}
+
+const titleReport: Report<LongPhaseTitle> = {
+  name: 'Phase title length',
+  noun: 'plan',
+  rule: `phase titles the change wrote have ${PHASE_TITLE_LIMIT} characters at most`,
+  unmet: CHECK_STATUS.warn,
+  text: ({ path, line, id, title, length }) =>
+    `${path}:${line} Phase ${id} ${title} has ${length} characters (limit ${PHASE_TITLE_LIMIT}); the title is the phase's name, its context goes into the origin line`,
+  clean: `every phase title the change wrote has ${PHASE_TITLE_LIMIT} characters at most`,
+}
+
 const withPath =
   <T>(path: string) =>
   (found: T): Found<T> => ({ ...found, path })
@@ -150,6 +181,12 @@ const mergedOf = ({ path, current, base }: Changed, language: PlanLanguage): Fou
 const unlistedOf = ({ path, current }: Changed, language: PlanLanguage): Found<PhaseWithoutRow>[] | null =>
   phasesWithoutDependencyRow(current, language)?.map(withPath(path)) ?? null
 
+const shortNamesOf = ({ path, current, previousLines }: Changed, language: PlanLanguage): Found<ShortNameFinding>[] =>
+  shortNameFindings(current, language, previousLines).map(withPath(path))
+
+const titlesOf = ({ path, current, previousLines }: Changed, language: PlanLanguage): Found<LongPhaseTitle>[] =>
+  longPhaseTitles(current, language, previousLines).map(withPath(path))
+
 const changedContents = ({ root, previousOf, baseOf, language }: PlanCheckInput, plans: readonly string[]): Changed[] =>
   plans
     .filter((path) => existsSync(join(root, path)))
@@ -166,10 +203,12 @@ const changedContents = ({ root, previousOf, baseOf, language }: PlanCheckInput,
  * - a lane row the change added or edited that names no phase warns, and so does one whose phases cell is longer
  *   than `PHASE_CELL_LIMIT` or records a side order of the user;
  * - a phase whose tasks are all ticked on the base branch and that still has open boxes without `→ P<n>` warns;
- * - a phase of a plan with a dependency table that has no row in it warns.
+ * - a phase of a plan with a dependency table that has no row in it warns;
+ * - an open task the change added or edited without a short name, or with one over `SHORT_NAME_LIMIT`, warns, and so
+ *   does a phase title it wrote over `PHASE_TITLE_LIMIT`.
  *
  * Empty when no plan changed. The row and prose results are left out when no changed file has a lanes table, the
- * merged result when every one has, the dependency result when no changed plan has the table.
+ * merged, short-name and phase-title results when every one has, the dependency result when no changed plan has the table.
  */
 export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
   const files = changedPlansOf(input.paths, input.planDirectory)
@@ -185,6 +224,8 @@ export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
   const prose = boards.flatMap((file) => proseOf(file, language))
   const merged = plans.flatMap((file) => mergedOf(file, language))
   const unlisted = unlistedPerPlan.flat()
+  const shortNames = plans.flatMap((file) => shortNamesOf(file, language))
+  const titles = plans.flatMap((file) => titlesOf(file, language))
   const durationMs = Date.now() - started
   return [
     findingsResult(gateReport(language), gates, files.length, durationMs),
@@ -198,5 +239,11 @@ export const planStructureChecks = (input: PlanCheckInput): CheckResult[] => {
     ...(unlistedPerPlan.length > 0
       ? [findingsResult(unlistedReport, unlisted, unlistedPerPlan.length, durationMs)]
       : []),
+    ...(plans.length > 0
+      ? [
+          findingsResult(shortNameReport, shortNames, plans.length, durationMs),
+          findingsResult(titleReport, titles, plans.length, durationMs),
+        ]
+      : []),
   ]
 }

package/src/check/plan.ts

@@ -1,4 +1,5 @@
 import type { JackherdConfig } from '../config'
+import { agentTextReviewers } from './agent-text-reviewers'
 import { type ChangedFile, generatorOwnedFiles, stagedBuildArtifacts } from './changes'
 import { tokenize } from './command-line'
 import { looseDirectories, packageRootsFor } from './roots'
@@ -90,7 +91,13 @@ export const planChecks = (
   return {
     paths,
     roots,
-    reviewers: [...reviewersFor(paths, config.reviewerRoutes), ...publicContentReviewers(paths, config.publicContent)],
+    reviewers: [
+      ...new Set([
+        ...reviewersFor(paths, config.reviewerRoutes),
+        ...publicContentReviewers(paths, config.publicContent),
+        ...agentTextReviewers(paths),
+      ]),
+    ],
     generated: generatorOwnedFiles(paths, config.generatorOwned),
     artifacts: stagedBuildArtifacts(files, config.buildArtifacts),
     checks:

package/src/check/schema.ts

@@ -57,6 +57,9 @@ const publicContent = z.strictObject({
   reviewer: nonEmpty.default('public-content'),
 })
 
+/** 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())
+
 /**
  * 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.
@@ -73,6 +76,11 @@ export const checkConfigSchema = z.strictObject({
   buildArtifacts: z.array(glob).default([...DEFAULT_BUILD_ARTIFACT_GLOBS]),
   reviewerRoutes: z.array(reviewerRoute).default([]),
   publicContent: publicContent.optional(),
+  /**
+   * Word budgets for the files an agent loads again and again. An entry replaces the kit's budget for the same
+   * path and sets one for the project's own skills; a file with none is measured against the kit's default.
+   */
+  skillBudgets: skillBudgets.optional(),
   /** Also run tests in directories that hold test files but belong to no package. */
   looseTests: z.boolean().default(false),
 })
@@ -81,3 +89,4 @@ export type CheckConfig = z.infer<typeof checkConfigSchema>
 export type ReviewerRoute = CheckConfig['reviewerRoutes'][number]
 export type ProjectCheck = CheckConfig['checks'][number]
 export type PublicContentConfig = NonNullable<CheckConfig['publicContent']>
+export type SkillBudgets = NonNullable<CheckConfig['skillBudgets']>

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

@@ -0,0 +1,55 @@
+/** Words allowed to a skill the kit did not install and the project gave no budget. */
+export const OWN_SKILL_BUDGET = 2000
+
+/** Words allowed to a file the kit installed when neither the project nor `KIT_SKILL_BUDGETS` names it. */
+export const KIT_FILE_FALLBACK_BUDGET = 2000
+
+/** Words allowed to a project supplement, `.claude/project/<skill>.md`. */
+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.
+ */
+export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
+  '.claude/skills/devops/SKILL.md': 321,
+  '.claude/skills/diagnose/SKILL.md': 1521,
+  '.claude/skills/diagnose/references/feedback-loops.md': 636,
+  '.claude/skills/follow/SKILL.md': 1100,
+  '.claude/skills/grill/SKILL.md': 685,
+  '.claude/skills/implement/SKILL.md': 2190,
+  '.claude/skills/orchestrate/SKILL.md': 7820,
+  '.claude/skills/orchestrate/references/acceptance.md': 200,
+  '.claude/skills/orchestrate/references/close-lane.md': 250,
+  '.claude/skills/orchestrate/references/coordinator-handover.md': 551,
+  '.claude/skills/orchestrate/references/draft-review.md': 300,
+  '.claude/skills/orchestrate/references/events.md': 1070,
+  '.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/lane-setup.md': 380,
+  '.claude/skills/orchestrate/references/plan-commit.md': 330,
+  '.claude/skills/orchestrate/references/sensitive-input.md': 269,
+  '.claude/skills/plan/SKILL.md': 1920,
+  '.claude/skills/plan/references/template-English.md': 536,
+  '.claude/skills/plan/references/template-German.md': 501,
+  '.claude/skills/pre-commit/SKILL.md': 1003,
+  '.claude/skills/review/SKILL.md': 319,
+  '.claude/skills/security-audit/SKILL.md': 519,
+  '.claude/skills/start/SKILL.md': 607,
+  '.claude/skills/uncle-bob/SKILL.md': 466,
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8620,
+  '.claude/agents/devops.md': 104,
+  '.claude/agents/explore.md': 132,
+  '.claude/agents/implement.md': 303,
+  '.claude/agents/plan.md': 209,
+  '.claude/agents/public-content.md': 449,
+  '.claude/agents/security-audit.md': 128,
+  '.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,
+  '.claude/rules/kit/pull-requests.md': 601,
+  '.claude/rules/kit/testing.md': 741,
+}