jackherd 1.17.0 → 1.18.0

package/kit/workflow/skills/orchestrate/references/approvals.md

@@ -0,0 +1,23 @@
+# § 4: an approval request, the question to the user
+
+Read on `approval <lane> <id> <tool> · <call>`, before you ask (`/orchestrate` § 4, **Approvals**).
+
+In a lane, a call that would open a permission dialog (an ask rule) is held by the approval gate hook (a global
+install has none, and the dialog stays in the lane: § 5). The hook waits up to `guard.approvals.waitMinutes`
+(default 8) for the user's answer. A subagent of your own session is held the same way, as
+`subagent-<type>-<id>`. A stage tool (`guard.approvals.standing.tools`): read
+[`stage-approval.md`](stage-approval.md) first.
+
+Ask at once, one question per request, through `AskUserQuestion`:
+
+- First read the request, `.jackherd/approvals/<id>.json` in the main checkout, and show its `tool`,
+  `cwd` and whole `input` in the chat above the dialog, in a code block whose fence is longer than any
+  run of backticks in it. The reported line is shortened; the user approves the call.
+- The question names the lane and the call, and contains the mark `` `approval <id> <hash>` `` exactly
+  as the duty line prints it. If the `hash` of the file you showed differs, the request changed: do not
+  ask, tell the user.
+- The options are exactly `{{kit.approval.allow}}` and `{{kit.approval.deny}}`, no multi-select.
+
+An approval holds once, for exactly that call, for 30 minutes. When the wait ran out first, the lane was told
+"pending"; tell it once the user allowed the call. Leave the client's own dialog in the lane's pane alone; the
+hook's answer closes it.

package/kit/workflow/skills/orchestrate/references/plan-commit.md

@@ -5,7 +5,8 @@ for the plan commit, and again when its documentation PR has merged (§ 6).
 
 ## The question
 
-After an adoption, the diff round of [`adopt-plan.md`](adopt-plan.md) is this question; ask nothing more. The
+Ask through `AskUserQuestion` whether to commit the missing files on a documentation branch and open a
+documentation PR the lanes start from. After an adoption, the diff round of [`adopt-plan.md`](adopt-plan.md) is this question; ask nothing more. The
 answer is the approval of that commit, its push and the PR (§ 5). `<topic>` is the plan's file name without date
 and extension, or the board's directory name when several files are missing. Answered no: no lane of these plans
 starts; say why, and do not ask again in this run unless the user raises it.

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

@@ -16,16 +16,13 @@ You create a structured concept/plan document in `{{kit.planDirectory}}/`.
 
 ### 0. Are the decisions actually made?
 
-A plan records decisions; it is not where they get taken. If the `## {{kit.heading.decisions}}` table would end up holding your guesses rather than the user's answers, **stop and recommend `/grill`** — name the open questions you would otherwise have to invent answers for, and let the user decide whether to run it. Entering clarification mode is the user's call, so you recommend it and leave the invocation to them. It works the questions in rounds and hands back rows in this table's format.
-
-Skip this when the request already carries its decisions (a plan for a bug fix with one obvious approach, a change the user has already specified).
+A plan records decisions; it is not where they get taken. If the `## {{kit.heading.decisions}}` table would hold your guesses rather than the user's answers, **stop and recommend `/grill`**: name the open questions and leave the invocation to the user. It hands back rows in this table's format. Skip this when the request already carries its decisions.
 
 ### 1. Pre-Scan (before a single word of the plan is written)
 
 - [ ] Read the relevant files in their **current** state, from disk
 - [ ] Search the project's shared components and utilities for what covers 80%+ of the need. 80%+ match → the plan specifies reuse or an override; 60–80% → the plan extends the shared piece; below 60% → new code, with the rationale under the rejected alternatives
-- [ ] Read related plans in `{{kit.planDirectory}}/` — check dependencies and open TODOs
-- [ ] Read the architecture documentation the change touches — understand what is already documented before you plan
+- [ ] Read related plans in `{{kit.planDirectory}}/` (dependencies, open TODOs) and the architecture documentation the change touches
 
 ### 2. Create the Document
 
@@ -37,53 +34,43 @@ The closing documentation section reads `## N — …` with rows `N.1` to `N.5`:
 
 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 its origin line, a quote under the heading (`> Origin: …`, in the plan's language). A task the user adds later: `- [ ] **Name**: … (User <DD.MM.> <HH:MM>)`.
+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 (`Heartbeat shows progress without ticks`); the how, the conditions, the origin and the evidence follow the colon. A phase's title is its name; its context goes into its origin line, a quote under the heading (`> Origin: …`, in the plan's language). A task the user adds later: `- [ ] **Name**: … (User <DD.MM.> <HH:MM>)`.
 
-An Artifact that belongs to the plan (a mockup, a draft for review, a findings page) stands as a Markdown link with its title in the phase it concerns, in the same move as its first publish: `**Mockup:** [Title](url)` or in the origin line. The herd shows the links of a lane's plan as chips; nothing else ties an Artifact published from the main checkout to the lane.
+An Artifact that belongs to the plan (a mockup, a draft for review, a findings page) stands as a Markdown link with its title in the phase it concerns, in the same move as its first publish: `**Mockup:** [Title](url)` or in the origin line. The herd shows them as chips; nothing else ties an Artifact published from the main checkout to the lane.
 
 What the template's tables mean:
 
-- **Model recommendations per phase** — one row per phase, judged by **error cost × complexity**. The project's default model for implementation (`{{kit.model.implement}}`) is the default of every row. A phase moves up to the planning model (`{{kit.model.plan}}`) when its rationale names a concrete error cost: a breakable invariant, possible data loss, security or tenant isolation, a migration without a way back, distributed state across systems. "Complex" or "many files" alone keeps the default. Review gates with `/security-audit` always get the strongest model.
-- **Dependencies and parallelization** (from three phases) — `/implement` reads it and starts every phase whose dependencies are done and that shares no written path with another, at the same time.
-  - **{{kit.heading.dependsOn}}:** phases of this plan (numbers) or external gates (`User: mockups`). A phase is ready when everything here is done.
-  - **{{kit.heading.writes}}:** the directories or files the phase creates or changes, as narrow as possible. Shared files many phases touch (barrels, translation files, `package.json`, generated types, architecture docs) are listed explicitly, so the overlap is visible. Write each path in full from the repository root: paths are compared as written, so `src/watch/` and `packages/app/src/watch/` do not overlap.
+- **Model recommendations per phase** — one row per phase, judged by **error cost × complexity**. `{{kit.model.implement}}` is the default of every row. A phase moves up to `{{kit.model.plan}}` when its rationale names a concrete error cost: a breakable invariant, possible data loss, security or tenant isolation, a migration without a way back, distributed state across systems. "Complex" or "many files" alone keeps the default. Review gates with `/security-audit` always get the strongest model.
+- **Dependencies and parallelization** (from three phases) — `/implement` starts every phase whose dependencies are done and that shares no written path with another, at the same time.
+  - **{{kit.heading.dependsOn}}:** phases of this plan (numbers) or external gates (`User: mockups`).
+  - **{{kit.heading.writes}}:** the directories or files the phase creates or changes, as narrow as possible, shared files (barrels, translation files, `package.json`, generated types, architecture docs) listed explicitly. Write each path in full from the repository root: paths are compared as written.
   - **{{kit.heading.serialMarker}}:** `Migration`, `<collection> schema bump`, `Event <type>`, a generator run. Two phases with a migration never run at the same time; neither do two that bump the same schema.
-  - **Cutting phases:** many small phases that ship in one release are bundled into a few phases now, not appended one by one later: every phase costs a hand-over. Shared text files (skills, README, changelog, architecture docs) go into a small phase of their own or into the closing tasks of a phase, so a phase's code never waits behind another phase only for them. You cut them here; `jh check --parallel` only orders the phases it is given.
+  - **Cutting phases:** many small phases that ship in one release are bundled into a few phases now, not appended one by one later: every phase costs a hand-over. Shared text files (skills, README, changelog, architecture docs) go into a small phase of their own or into the closing tasks of a phase, so no phase's code waits behind them.
 
 ### 3. Architecture Review
 
-Apply `/uncle-bob` to the created plan. Additionally check:
-
-- **Interfaces:** Are the boundaries between modules/services clear? Who consumes what?
-- **Blast radius:** Which existing consumers are affected? Are tests needed in all consuming packages?
+Apply `/uncle-bob` to the created plan, and check the **interfaces** (who consumes what) and the **blast radius** (which consumers are affected, which consuming packages need tests).
 
 ### 4. Anchor the Review Gate in the Plan
 
-Every phase gets the review gate block from the template at its end. Add the reviewers the project supplement names for its areas (a UI review for UI phases, for instance). A phase with tasks that genuinely needs no gate (documentation only, a draft) says so and why in a line of its own, in the plan's language: `**No review gate:** <reason>` (`en`), `**Kein Review-Gate:** <Grund>` (`de`). `jh check` refuses a phase the change adds with tasks and neither line.
+Every phase gets the review gate block from the template at its end, plus the reviewers the project supplement names for its areas. A phase with tasks that genuinely needs no gate (documentation only, a draft) says so in a line of its own, in the plan's language: `**No review gate:** <reason>` (`en`), `**Kein Review-Gate:** <Grund>` (`de`). `jh check` refuses a phase the change adds with tasks and neither line.
 
 ### 5. Quality Checks
 
-- **Focus:** Does the plan solve a concrete problem? No "would be nice to have".
-- **Scope:** Is the scope clearly bounded? No feature-creep risk?
-- **Feasibility:** Can the phases be split into individual PRs/commits?
-- **References:** Are related plans in `{{kit.planDirectory}}/` linked?
-- **Current state is fact-based:** Read code, count files, verify architecture; every claim has a source.
-- **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`).
+- **Focus and scope:** a concrete problem, clearly bounded, phases that split into individual PRs, related plans in `{{kit.planDirectory}}/` linked.
+- **Current state is fact-based:** every claim has a source (code read, files counted).
+- **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 says why none are needed (decision tree in `.claude/rules/kit/testing.md`).
 - **Lint before prose:** a rule the plan writes or changes in an agent text that the project's linter can check becomes a lint task (a case where it fires, one where it stays silent); the prose shrinks to the sentence naming it with `lint:<rule id>`.
-- **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, 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.
-- **Documentation planned:** `## {{kit.heading.documentation}}` names concretely what will be created or updated after completion.
+- **Model recommendations and parallelism:** `## {{kit.heading.implementation}}` starts with the model table; from three phases the dependencies table follows, a row for every phase, every migration, schema bump and new event a serial marker, every shared file under {{kit.heading.writes}}.
+- **arc42 and architecture (after the plan exists):** apply the filters in `.claude/rules/kit/arc42.md` and `.claude/rules/kit/architecture-files.md` to the finished plan and **ask the user concretely**; on "yes", add a concrete task to `## {{kit.heading.documentation}}`. From three phases or a new service/package, the plan ends with the template's architecture documentation phase.
+- **Documentation planned:** `## {{kit.heading.documentation}}` names concretely what will be created or updated.
 
 ### 6. Propose the board rows
 
 A **board** gathers the lanes one coordinator runs with `/orchestrate`: `{{kit.board.file}}` in a directory
-matching `{{kit.planDirectory}}/{{kit.board.pattern}}` (this project calls it a "{{kit.board.term}}"). The plan
-already holds what a lane row needs, so end by proposing the rows; `/orchestrate` then starts the lanes from them.
-Skip this step for a plan of one phase that nobody runs as a lane, and say so.
+matching `{{kit.planDirectory}}/{{kit.board.pattern}}` (this project calls it a "{{kit.board.term}}"). End by
+proposing its rows; skip this for a plan of one phase that nobody runs as a lane, and say so.
 
 Derive the rows from the dependencies table and the model table, nothing else:
 
@@ -93,33 +80,26 @@ Derive the rows from the dependencies table and the model table, nothing else:
   Otherwise it is a `↳` row under a fitting lane, or a subagent there (`/implement` Step 0b).
 - **Continuation:** a phase that shares a written path or a serial marker with an earlier phase, or depends on it,
   is a `↳` row under that phase's lane, in the same worktree.
-- **Starts after:** from the phase's {{kit.heading.dependsOn}} cell, as the board reads it (`P2 merged`, an external
-  gate such as `User: mockups`); a phase without one starts at once.
-- **Model:** the full model ID from the model table (`{{kit.model.implement}}`, `{{kit.model.plan}}`), never an alias.
-- **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.
+- **Starts after:** from the phase's {{kit.heading.dependsOn}} cell (`P2 merged`, `User: mockups`); without one, at once.
+- **Model:** the full model ID from the model table, never an alias.
+- **Plan:** a Markdown link relative to the board's directory (`../<file>.md`). Plans stay where they are; the row only links them.
 - **Lane name:** short kebab case, unique on the board; the worktree directory and the herdr agent carry the same name
   (`/orchestrate` § 2), else the herd lists the lane as a worktree without an agent.
-- **Port:** `–`; the coordinator sets it when the lane starts, unless the project supplement assigns ports here.
+- **Port:** `–`; the coordinator sets it, 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
 after, model, in this order and headed in {{kit.planLanguage}} (the herd reads them by position). Then ask
 where they go:
 
-- **The newest board**, by name: the newest `{{kit.planDirectory}}/{{kit.board.pattern}}/{{kit.board.file}}`. The
-  rows are appended to its `## {{kit.heading.lanes}}` table.
-- **A new board.** Ask for its name and propose one: the year and month or the topic, in the pattern's shape. Check
-  that the directory name matches `{{kit.board.pattern}}` before writing; if it does not, say why and ask again.
-  Create `{{kit.planDirectory}}/<name>/{{kit.board.file}}` with a `#` title and the `## {{kit.heading.lanes}}`
-  table holding the proposed rows.
+- **The newest board**, by name: the newest `{{kit.planDirectory}}/{{kit.board.pattern}}/{{kit.board.file}}`, appended to its `## {{kit.heading.lanes}}` table.
+- **A new board:** ask for its name, proposing one (the year and month or the topic). Check that the directory name matches `{{kit.board.pattern}}` before writing; if it does not, say why and ask again. Create `{{kit.planDirectory}}/<name>/{{kit.board.file}}` with a `#` title and the table.
 - **Not now:** the rows stay in your answer, for `/orchestrate` to write when it starts the lanes.
 
 Nothing is written without that answer. The board is a file like the plan: it goes into the same commit, under the
 same approval.
 
 After writing the rows, name the next step in one line: `/orchestrate <board path>`, from a Claude Code session
-inside herdr. A plan or board that is not on `origin/{{kit.baseBranch}}` yet needs no merge first: `/orchestrate`
+inside herdr. A plan or board not yet on `origin/{{kit.baseBranch}}` needs no merge first: `/orchestrate`
 asks to commit it on a documentation branch and starts the lanes from there.
 
 Ask every question with a fixed set of answers through the `AskUserQuestion` tool, in {{kit.responseLanguage}}.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "keywords": [
     "claude-code",
     "coding-agents",

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

@@ -21,8 +21,11 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   // dry-run by name after the entry is written, since a draft runs without the keychain (+103).
   '.claude/skills/follow/SKILL.md': 1498,
   '.claude/skills/grill/SKILL.md': 685,
-  '.claude/skills/implement/SKILL.md': 2190,
+  // Prose cut, round 2: cut to its mandatory rules, measured size plus 5 %.
+  '.claude/skills/implement/SKILL.md': 1882,
   '.claude/skills/orchestrate/SKILL.md': 4500,
+  // Prose cut, round 2: § 4 Approvals moved here from the core.
+  '.claude/skills/orchestrate/references/approvals.md': 266,
   // 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
@@ -52,7 +55,8 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   '.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.
   // 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,
+  // Prose cut, round 2: the question itself moved here from § 2 step 0; measured size plus 5 %.
+  '.claude/skills/orchestrate/references/plan-commit.md': 475,
   // 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,
@@ -63,10 +67,12 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   // 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,
+  // Prose cut, round 2: cut to its mandatory rules, measured size plus 5 %.
+  '.claude/skills/plan/SKILL.md': 1717,
   '.claude/skills/plan/references/template-English.md': 536,
   '.claude/skills/plan/references/template-German.md': 501,
-  '.claude/skills/pre-commit/SKILL.md': 1003,
+  // Prose cut, round 2: cut to its mandatory rules, measured size plus 5 %.
+  '.claude/skills/pre-commit/SKILL.md': 825,
   '.claude/skills/review/SKILL.md': 319,
   '.claude/skills/security-audit/SKILL.md': 519,
   // Any language: step 3 points to proposing the missing commands from the CI; the proposal itself is a reference.
@@ -82,11 +88,10 @@ export const KIT_SKILL_TARGETS: Readonly<Record<string, number>> = {
   '.claude/agents/skill-review.md': 468,
   '.claude/agents/spec-review.md': 1137,
   '.claude/agents/uncle-bob.md': 111,
-  // 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,
+  // Prose cut, round 2: the three rules cut to their mandatory rules, measured size plus 5 %.
+  '.claude/rules/kit/code-style.md': 1290,
+  '.claude/rules/kit/pull-requests.md': 459,
+  '.claude/rules/kit/testing.md': 506,
 }
 
 /**
@@ -97,8 +102,6 @@ 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`.
@@ -118,13 +121,17 @@ export const KIT_SKILL_CEILINGS: Readonly<Record<string, number>> = {
   // 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,
+  // Prose cut, round 2: cut to the phrases the kit-content test holds word for word, § 4 Approvals moved to a
+  // reference; measured size plus 5 %. Then checked sentence by sentence (skill-review, uncle-bob): what a
+  // reference, a hook message or a watcher line already carries left the core; measured size plus 5 %.
+  '.claude/skills/orchestrate/SKILL.md': 5163,
   // 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,
+  // Prose cut, round 2: lowered with the skill's, this repository's sum plus 5 %; again after the sentence check.
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 5611,
 }
 
 /** What `jh check` measures against: a file's ceiling where it has one, else its target. */

package/src/check/skill-budgets.ts

@@ -154,9 +154,11 @@ const overrunLine = ({ entry: { label, words, budget }, overrun }: MeasuredOverr
 const withinLine = (count: number): string =>
   count === 1 ? '1 file within its word budget' : `${count} files within their word budget`
 
-const statusOf = (overruns: readonly MeasuredOverrun[]): CheckStatus => {
+const missingLine = (path: string): string => `warning: ${path} is named in check.skillBudgets but missing`
+
+const statusOf = (overruns: readonly MeasuredOverrun[], missing: readonly string[]): CheckStatus => {
   if (overruns.some(({ overrun }) => overrun === CHECK_STATUS.fail)) return CHECK_STATUS.fail
-  return overruns.length > 0 ? CHECK_STATUS.warn : CHECK_STATUS.pass
+  return overruns.length > 0 || missing.length > 0 ? CHECK_STATUS.warn : CHECK_STATUS.pass
 }
 
 /** 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. */
@@ -172,19 +174,25 @@ const overrideNote = ({ label, target, projectBudget }: Measurement): string[] =
     : []
 
 /**
- * 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.
+ * One line per overrun and per `missing` path the project budget names; one line in total when none is over. Warns
+ * above a budget and on a missing path, 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 => {
+export const budgetResult = (
+  measured: readonly Measurement[],
+  durationMs: number,
+  missing: readonly string[] = [],
+): 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)]
+  const problems = [...overruns.map(overrunLine), ...missing.map(missingLine)]
+  const lines = problems.length > 0 ? problems : [withinLine(measured.length)]
   return {
     name: 'Skill budgets',
     command: `${measured.length} measured, words per budget`,
-    status: statusOf(overruns),
+    status: statusOf(overruns, missing),
     detail: [...lines, ...measured.flatMap(targetHint), ...measured.flatMap(overrideNote)].join('\n'),
     durationMs,
   }
@@ -241,10 +249,28 @@ const supplementPaths = (root: string): string[] =>
     .filter((name) => name.endsWith('.md'))
     .map((name) => claudePath(SUPPLEMENTS_DIRECTORY, name))
 
+/** The entries of the project budget that name one file by its exact path: no glob, no sum. */
+const namedProjectFiles = (project: BudgetTable): [path: string, words: number][] =>
+  Object.entries(project).filter(([key]) => !isGlob(key) && !key.includes(SUM_SEPARATOR))
+
+/** The files the project budget names that `found` does not hold yet, and the named paths that cannot be read. */
+const namedFilesOf = (
+  root: string,
+  project: BudgetTable,
+  found: readonly FileWords[],
+): { files: FileWords[]; missing: string[] } => {
+  const measured = new Set(found.map(({ path }) => path))
+  const named = namedProjectFiles(project).filter(([path]) => !measured.has(path))
+  const files = named.flatMap(([path, words]) => fileWordsOf(root, path, words))
+  const missing = named.map(([path]) => path).filter((path) => !files.some((file) => file.path === path))
+  return { files, missing }
+}
+
 /**
  * The installed kit skills with their references, kit agents and kit rules that load every session (the lock file
- * says which files the kit installed), the project's supplements and its own skills, measured against the budgets.
- * `skillPrefix` is the project's: the kit's budgets follow its skills and agents to their prefixed paths.
+ * says which files the kit installed), the project's supplements and its own skills, and every other file the project
+ * budget names by its exact path, measured against the budgets; a named file that is missing warns. `skillPrefix` is
+ * the project's: the kit's budgets follow its skills and agents to their prefixed paths.
  * Null when there is nothing to measure.
  */
 export const skillBudgetCheck = (root: string, project: BudgetTable = {}, skillPrefix = ''): CheckResult | null => {
@@ -252,12 +278,16 @@ export const skillBudgetCheck = (root: string, project: BudgetTable = {}, skillP
   const kitPaths = kitPathsOf(root)
   const kit = new Set(kitPaths.map((key) => claudePath(key)))
   const foreign = readForeignSkills(root)
-  const files = [
+  const found = [
     ...kitPaths.flatMap((key) => kitFileWordsOf(root, key)),
     ...supplementPaths(root).flatMap((path) => fileWordsOf(root, path, SUPPLEMENT_BUDGET)),
     ...ownSkillPaths(root, kit).flatMap((path) => fileWordsOf(root, path, OWN_SKILL_BUDGET)),
-  ].map(markForeign(foreign))
+  ]
+  const named = namedFilesOf(root, project, found)
+  const files = [...found, ...named.files].map(markForeign(foreign))
   const defaults = prefixedBudgets(KIT_SKILL_BUDGETS, skillPrefix)
   const targets = prefixedBudgets(KIT_SKILL_TARGETS, skillPrefix)
-  return files.length === 0 ? null : budgetResult(measureFiles(files, project, defaults, targets), Date.now() - started)
+  return files.length === 0 && named.missing.length === 0
+    ? null
+    : budgetResult(measureFiles(files, project, defaults, targets), Date.now() - started, named.missing)
 }