jackherd 1.16.0 → 1.18.0

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,52 +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 the origin line. 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`).
-- **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.
+- **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 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:
 
@@ -92,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).
-- **Port:** `–`; the coordinator sets it when the lane starts, unless the project supplement assigns ports here.
+  (`/orchestrate` § 2), else the herd lists the lane as a worktree without an agent.
+- **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.16.0",
+  "version": "1.18.0",
   "keywords": [
     "claude-code",
     "coding-agents",
@@ -78,6 +78,7 @@
     "zod": "^4.0.0"
   },
   "devDependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.3.310",
     "@types/bun": "^1.4.3",
     "tsup": "^8.5.1",
     "typescript": "^5.8.3"

package/recipes/README.md

@@ -18,6 +18,7 @@ Each recipe is one `watch.sources` entry for the jackherd watcher: put in your k
 - **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. The token reaches the script through the entry's `secrets` (the keychain, for a personal source only; see [sources.md](sources.md)) or through the watcher's environment; either way the script reads `process.env`.
 - **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 reason of a failure comes only through one stdout line.** Before it exits, a script may print `jackherd-reason: <reason>` on stdout (`HTTP 401`, `LINEAR_API_KEY not set`); the watcher shows the last such line as `exit 1: <reason>`, cut to 160 characters; a line over 1024 characters gives no reason. stderr stays unread. The line names a status or a missing variable, never a token and never a URL with access in it: the watcher masks the values of the entry's `secrets`, credentials and query values of URLs, but a token the script took from elsewhere it cannot recognise.
 - **The scripts are files of their own** under [`sources/`](sources/). Copy one to `scripts/sources/<name>.ts` in your repository (a personal source: `~/.jackherd/sources/<name>.ts`), 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/jira-cli.md

@@ -4,7 +4,7 @@
 
 `acli jira workitem search` cannot return `updated` or `comment`, so a script searches for the keys and reads each one with `view`, a few at a time to stay well under the 30 seconds a source may run. `plainText` joins the text and mention nodes of the comment's document tree into plain text; it is a pure function, so you can test it on its own.
 
-**Script:** copy [sources/jira.ts](sources/jira.ts) to `scripts/sources/jira.ts` in your repository, put your project into `jql`, and set `host` to your `<site>.atlassian.net`. A failed `acli` call ends the script with exit code 1, which the watcher reports as a failing source; nothing is printed that it could take for an empty list.
+**Script:** copy [sources/jira.ts](sources/jira.ts) to `scripts/sources/jira.ts` in your repository, put your project into `jql`, and set `host` to your `<site>.atlassian.net`. A failed `acli` call ends the script with exit code 1, which the watcher reports as a failing source; nothing is printed that it could take for an empty list. Before it exits, the script prints one stdout line `jackherd-reason: <reason>`, so the report reads `exit 1: <reason>`.
 
 **Entry:**
 

package/recipes/sources/google-calendar-today.ts

@@ -7,8 +7,14 @@ import { addressesOf, civilOf, occurrencesOn, parseIcs, toItems } from './google
 
 const zone = Intl.DateTimeFormat().resolvedOptions().timeZone
 
+// The watcher shows this line with the exit code; it never names an address, the address is the credential.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
 const addresses = addressesOf(process.env)
-if (addresses.length === 0) process.exit(1)
+if (addresses.length === 0) fail('GOOGLE_CALENDAR_ICS_URL not set')
 
 // The address is the credential: nothing from a failed request (error text, URL) may reach stderr.
 const readCalendar = async (address: string): Promise<string | undefined> => {
@@ -23,7 +29,7 @@ const readCalendar = async (address: string): Promise<string | undefined> => {
 
 const answers = await Promise.all(addresses.map(readCalendar))
 const texts = answers.filter((text) => text !== undefined)
-if (texts.length < answers.length) process.exit(1)
+if (texts.length < answers.length) fail(`${answers.length - texts.length} of ${answers.length} calendars unreadable`)
 
 const today = civilOf(Date.now(), zone)
 const events = texts.flatMap((text) => parseIcs(text, zone))

package/recipes/sources/jira.ts

@@ -12,14 +12,22 @@ const plainText = (node: DocumentNode): string =>
     ? (node.text ?? node.attrs?.text ?? '')
     : (node.content ?? []).map(plainText).join('')
 
+// The watcher shows this line with the exit code; it never carries acli's output.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
 const acli = async (args: string[]): Promise<unknown> => {
   const child = Bun.spawn(['acli', ...args], { stdout: 'pipe', stderr: 'ignore', signal: AbortSignal.timeout(20_000) })
   const output = await new Response(child.stdout).text()
-  if ((await child.exited) !== 0) process.exit(1)
+  const code = await child.exited
+  const call = `acli ${args.slice(0, 2).join(' ')}`
+  if (code !== 0) fail(`${call} exited ${code}`)
   try {
     return JSON.parse(output)
   } catch {
-    return process.exit(1)
+    return fail(`${call} answered no JSON`)
   }
 }
 

package/recipes/sources/linear.ts

@@ -1,6 +1,12 @@
 // Copy to scripts/sources/linear.ts in your repository; the recipe recipes/linear.md says what to fill in.
+// The watcher shows this line with the exit code; it never carries the token or a URL.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
 const token = process.env.LINEAR_API_KEY
-if (!token) process.exit(1)
+if (!token) fail('LINEAR_API_KEY not set')
 
 const query = `{ issues(filter: { team: { key: { eq: "ENG" } }, number: { eq: 123 } }) {
   nodes { identifier title url updatedAt comments { nodes { body user { name } } } } } }`
@@ -11,9 +17,9 @@ const response = await fetch('https://<host>/graphql', {
   body: JSON.stringify({ query }),
   signal: AbortSignal.timeout(20_000),
 })
-if (!response.ok) process.exit(1)
+if (!response.ok) fail(`HTTP ${response.status}`)
 const answer = (await response.json()) as { errors?: unknown }
-if (answer.errors) process.exit(1)
+if (answer.errors) fail('GraphQL errors in the answer')
 console.log(JSON.stringify(answer))
 
 export {}

package/recipes/sources/sentry.ts

@@ -1,12 +1,18 @@
 // Copy to scripts/sources/sentry.ts in your repository; the recipe recipes/sentry.md says what to fill in.
+// The watcher shows this line with the exit code; it never carries the token or a URL.
+const fail: (reason: string) => never = (reason) => {
+  console.log(`jackherd-reason: ${reason}`)
+  return process.exit(1)
+}
+
 const token = process.env.SENTRY_AUTH_TOKEN
-if (!token) process.exit(1)
+if (!token) fail('SENTRY_AUTH_TOKEN not set')
 
 const response = await fetch(
   'https://<host>/api/0/projects/<org>/<project>/issues/?query=is:unresolved&statsPeriod=24h',
   { headers: { Authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(20_000) },
 )
-if (!response.ok) process.exit(1)
+if (!response.ok) fail(`HTTP ${response.status}`)
 console.log(JSON.stringify(await response.json()))
 
 export {}

package/recipes/sources.md

@@ -79,7 +79,7 @@ first run of this source: baseline, nothing reported; later a new or changed ent
 watcher state not read or changed; a running watcher takes a new source over at its next cycle
 ```
 
-**Keep a personal source.** A source can live in `~/.jackherd/sources.json` instead of the repository: `{ "$schema": "…/schemas/sources.schema.json", "sources": [ … ] }`, entries as above. It runs in every repository where the watcher starts, after the repository's `watch.sources`. On a name clash the repository's source wins and the personal one is skipped with a note. A personal source runs with `~/.jackherd/` as its working directory, so its script is `~/.jackherd/sources/<name>.ts` and its command `["bun", "sources/<name>.ts"]`. `jh watch source <name> --dry-run` finds it too and prints `origin: personal, <path>`; a draft file runs as a repository source, in the main checkout and without the keychain.
+**Keep a personal source.** A source can live in `~/.jackherd/sources.json` instead of the repository: `{ "$schema": "…/schemas/sources.schema.json", "sources": [ … ] }`, entries as above. It runs in every repository where the watcher starts, after the repository's `watch.sources`, unless it carries `"repos": ["owner/name"]` (one to twenty, unique without regard to case): then it runs only where the main checkout's `origin` names one of them, and elsewhere the watcher notes `<name>: not for this repo` (`<name>: no origin` when the checkout has none). `repos` belongs in the personal file only; the repository's config refuses it. `jh watch source <name> --dry-run` of a left-out source prints the note and exits 2 without running anything. On a name clash the repository's source wins and the personal one is skipped with a note. A personal source runs with `~/.jackherd/` as its working directory, so its script is `~/.jackherd/sources/<name>.ts` and its command `["bun", "sources/<name>.ts"]`. `jh watch source <name> --dry-run` finds it too and prints `origin: personal, <path>`; a draft file runs as a repository source, in the main checkout and without the keychain.
 
 **Keep a secret for a source.** `"secrets": ["NAME"]` (up to 10 names, `A-Z`, digits and `_`, starting with a letter) puts those variables into the environment of the source's command, and nowhere else. For a personal source each value comes from the keychain (service `jackherd`), else from the watcher's own environment; a repository source gets them from the watcher's environment only, never from the keychain. A value that is found nowhere fails the run with `secret missing: NAME`, an unreachable keychain with `secret store unavailable`; other sources go on. The script reads the value from `process.env` and never prints it.
 
@@ -91,6 +91,8 @@ jh secret delete NAME
 
 **Show entries as content.** `"show": "entries"` opens the source's entries in a herd block of their own under "Your turn", headed by its `label`, instead of the folded row in `Sources`. For a source whose entries are the day's content, such as a calendar; not together with `ticket`.
 
-The watcher and the herd read the repository's config and the personal file again each cycle (about a minute): a new, changed or removed source counts without a restart, a new one runs at once. A changed file that is invalid keeps the previous sources and prints `sources not reloaded: <file>: <reason>`. The rest of the config is read when the watcher starts.
+The watcher and the herd read the repository's config and the personal file again each cycle (about a minute): a new, changed or removed source counts without a restart, a new one runs at once. A changed file that is invalid keeps the previous sources and prints `sources not reloaded: <file>: <reason>`. `deploy`, `feedback`, `previews` and `checks` follow the same way; a change that applies prints `config reloaded: <parts>`, an invalid one keeps every value and prints `config not reloaded: <file>: <reason>`. The board and the language are read when the watcher starts.
+
+**Say why a source failed.** A failing command may print one stdout line `jackherd-reason: <reason>` (a status, a missing variable); the watcher shows the last such line as `exit 1: <reason>`, with the values of the source's `secrets` and URL credentials masked, cut to 160 characters. stderr is never read. Name no token in it.
 
 Three limits stand: the watcher cannot make a command read only, so name only commands that read. A source in `.jackherd/config.json` runs for everyone who starts the watcher in the repository, at the same level of trust as `check.checks` and hooks. The watcher reads the config of the main checkout, never the one of a lane's worktree; a dry run started inside a worktree reads that worktree's config first. And `jh watch source … --dry-run` runs whatever command its draft names, so it never belongs in a permission allowlist.

package/schemas/jackherd.schema.json

@@ -143,6 +143,10 @@
         "lockFile": {
           "type": "string",
           "pattern": "^(?![/-])(?!(?:.*\\/)?\\.\\.(?:\\/|$))[A-Za-z0-9._/-]+$"
+        },
+        "minFreeGb": {
+          "type": "number",
+          "exclusiveMinimum": 0
         }
       },
       "additionalProperties": false
@@ -645,6 +649,15 @@
               "show": {
                 "type": "string",
                 "const": "entries"
+              },
+              "repos": {
+                "minItems": 1,
+                "maxItems": 20,
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "pattern": "^[\\w.-]+\\/[\\w.-]+$"
+                }
               }
             },
             "required": [
@@ -699,6 +712,28 @@
               "type": "integer",
               "minimum": 1,
               "maximum": 9
+            },
+            "standing": {
+              "type": "object",
+              "properties": {
+                "tools": {
+                  "type": "object",
+                  "propertyNames": {
+                    "type": "string",
+                    "pattern": "^mcp__[A-Za-z0-9_-]+__execute_sql$"
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "enum": [
+                      "stage"
+                    ]
+                  }
+                }
+              },
+              "required": [
+                "tools"
+              ],
+              "additionalProperties": false
             }
           },
           "additionalProperties": false
@@ -929,6 +964,38 @@
             "maximum": 9007199254740991
           }
         },
+        "openBoxes": {
+          "default": "fail",
+          "type": "string",
+          "enum": [
+            "fail",
+            "warn",
+            "off"
+          ]
+        },
+        "lintPointers": {
+          "type": "object",
+          "properties": {
+            "level": {
+              "default": "warn",
+              "type": "string",
+              "enum": [
+                "warn",
+                "fail",
+                "off"
+              ]
+            },
+            "exclude": {
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        },
         "looseTests": {
           "default": false,
           "type": "boolean"

package/schemas/sources.schema.json

@@ -126,6 +126,15 @@
           "show": {
             "type": "string",
             "const": "entries"
+          },
+          "repos": {
+            "minItems": 1,
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[\\w.-]+\\/[\\w.-]+$"
+            }
           }
         },
         "required": [

package/src/approval/checked.ts

@@ -0,0 +1,60 @@
+import { createHash } from 'node:crypto'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { isRecord } from '../shared/is-record'
+import type { ApprovalRequestFile } from '../watch/approvals'
+
+/** What `jh approval show|checked` prints and how it ends: 0 shown, 1 wrong arguments, 2 no such open request. */
+export type ApprovalReport = { exitCode: number; stdout: string[]; stderr: string[] }
+
+type RequestCall = Pick<ApprovalRequestFile, 'lane' | 'cwd' | 'tool' | 'input'>
+
+const VERBS = new Set(['show', 'checked'])
+const USAGE = 'Usage: jh approval show|checked <id> <hash>'
+const ID = /^[0-9a-f]{12}$/
+const HASH = /^[0-9a-f]{16}$/
+
+/** JSON with the keys of every object sorted, as the approval gate hook hashes a call. */
+const canonicalJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (isRecord(value))
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(',')}}`
+  return JSON.stringify(value) ?? 'null'
+}
+
+/** The hash of a call as the approval gate hook writes it (`callHash`, which this package does not import; contract test). */
+export const requestHash = ({ lane, cwd, tool, input }: RequestCall): string =>
+  createHash('sha256').update(canonicalJson({ lane, cwd, tool, input })).digest('hex').slice(0, 16)
+
+const refused = (exitCode: number, line: string): ApprovalReport => ({ exitCode, stdout: [], stderr: [line] })
+
+/** The request as the coordinator reads it before it marks it: every field the lane wrote, made safe to print. */
+const shown = ({ id, hash, lane, tool, cwd, input }: ApprovalRequestFile): string[] => [
+  `approval ${id} ${hash}`,
+  `lane: ${terminalSafe(lane)}`,
+  `tool: ${terminalSafe(tool)}`,
+  `cwd: ${terminalSafe(cwd)}`,
+  'input:',
+  ...(JSON.stringify(input, null, 2) ?? 'null').split('\n').map(terminalSafe),
+]
+
+/**
+ * `jh approval show <id> <hash>` and `jh approval checked <id> <hash>`: print the open request whose id and hash these
+ * are, and whose content its hash covers, and end with 0; otherwise say why and end with 2. Neither writes anything.
+ * `show` is for reading; a successful `checked` in the coordinator's transcript is the mark the approval gate hook
+ * reads as "the coordinator checked exactly this call", so it comes after the check, never before.
+ */
+export const approvalReport = (args: readonly string[], requests: readonly ApprovalRequestFile[]): ApprovalReport => {
+  const [verb, id, hash, ...rest] = args
+  if (!VERBS.has(verb ?? '') || !ID.test(id ?? '') || !HASH.test(hash ?? '') || rest.length > 0)
+    return refused(1, USAGE)
+  const request = requests.find((candidate) => candidate.id === id && candidate.usedAt === null)
+  if (request === undefined) return refused(2, `no open request ${id}`)
+  if (request.hash !== hash)
+    return refused(2, `request ${id} has hash ${request.hash}, not ${hash}: it changed, look at it again`)
+  if (requestHash(request) !== hash)
+    return refused(2, `request ${id} does not match its hash: it was changed by hand, ask the user`)
+  return { exitCode: 0, stdout: shown(request), stderr: [] }
+}

package/src/approval/command.ts

@@ -0,0 +1,16 @@
+import { mainCheckout } from '../plans/git'
+import { readApprovalRequests } from '../watch/approvals'
+import { approvalReport } from './checked'
+
+/** `jh approval show|checked <id> <hash>`: read a held call, and the coordinator's mark that it checked it (`approvalReport`). */
+export const run = (args: string[]): number => {
+  try {
+    const report = approvalReport(args, readApprovalRequests(mainCheckout(process.cwd())))
+    for (const line of report.stdout) console.log(line)
+    for (const line of report.stderr) console.error(line)
+    return report.exitCode
+  } catch (error) {
+    console.error(`jh approval: ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}

package/src/check/command.ts

@@ -3,17 +3,21 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join, resolve } from 'node:path'
 import { planRootsIn } from '../../kit/hooks/hooks/shared/boards'
+import { laneOf } from '../../kit/hooks/hooks/shared/lane'
 import { findProjectRoot, globalConfigPath, locateConfigFile, MANIFEST_FILE, TOOL_DIRECTORY } from '../config/location'
 import { readRepositoryFacts } from '../config/repository-facts'
+import { installedReferenceHint } from '../lane/skill-hint'
 import { mainCheckout } from '../plans/git'
 import { baseRefOf } from '../plans/settings'
+import { REFERENCE } from '../watch/reference-paths'
 import { type ChangedFile, parsePorcelain, STATUS_COMMAND } from './changes'
 import { deferralArrowCheck } from './deferral-arrows'
 import { runCheck, runProcess } from './execute'
 import { matchesAnyGlob } from './glob'
+import { lintPointerCheck } from './lint-pointers'
 import { parallelArgument, parallelReportLines } from './parallel-report'
 import { type CheckPlan, type CheckStack, checkStackOf, type Filesystem, isSlow, planChecks } from './plan'
-import { planStructureChecks } from './plan-structure-check'
+import { laneOpenBoxesCheck, planStructureChecks } from './plan-structure-check'
 import { publicContentCheck } from './public-content-check'
 import {
   artifactResult,
@@ -29,6 +33,7 @@ import {
 } from './report'
 import { type CheckResult, RUN_MODE, type RunMode, runModeOf } from './result'
 import { isWorkspaceManifest, kitCopyPaths, WORKSPACE_LIST_FILE, WORKSPACE_MANIFEST } from './roots'
+import { DEFAULT_LINT_POINTERS } from './schema'
 import { type CheckSettings, CONFIG_PATH, noStackFallbackOf, parseCheckSettings, stackOf } from './settings'
 import { skillBudgetCheck } from './skill-budgets'
 
@@ -199,11 +204,50 @@ const planRootsOf = (root: string, worktreeDirectory: string): string[] => {
   }
 }
 
-/** The checks jackherd runs itself beside the configured ones: public content, deferral arrows, skill budgets, plan structure. */
-const ownChecksOf = (root: string, paths: readonly string[], settings: CheckSettings, home: string) => [
+/** The lane a checkout is for: the first directory below the main checkout's worktree directory; null outside one. */
+const laneOfCheckout = (root: string, worktreeDirectory: string): string | null => {
+  try {
+    return laneOf({ cwd: root, main: mainCheckout(root), worktreeDirectory })
+  } catch {
+    return null
+  }
+}
+
+/** The open boxes of the lane's phase, left out for a checkout that is no lane's. */
+const openBoxesCheckOf = (root: string, settings: CheckSettings): CheckResult | null => {
+  const lane = laneOfCheckout(root, settings.worktreeDirectory)
+  return lane === null
+    ? null
+    : laneOpenBoxesCheck({
+        root,
+        lane,
+        planDirectory: settings.planDirectory,
+        board: settings.board,
+        language: settings.planLanguage,
+        level: settings.check.openBoxes,
+        baseOf: contentAt(root, baseRefOf(settings)),
+      })
+}
+
+/** The checks jackherd runs itself beside the configured ones: public content, deferral arrows, skill budgets, lint pointers, plan structure. */
+const ownChecksOf = (
+  root: string,
+  paths: readonly string[],
+  settings: CheckSettings,
+  home: string,
+  kitCopies: readonly string[],
+) => [
+  openBoxesCheckOf(root, settings),
   publicContentCheck(root, paths, settings.check.publicContent, home),
   deferralArrowCheck(root, paths, settings.planDirectory),
   skillBudgetCheck(root, settings.check.skillBudgets, settings.skillPrefix),
+  lintPointerCheck(
+    root,
+    paths,
+    settings.check.lintPointers ?? DEFAULT_LINT_POINTERS,
+    kitCopies,
+    contentAt(root, 'HEAD'),
+  ),
   ...planStructureChecks({
     root,
     paths,
@@ -228,8 +272,9 @@ const checkChanges = async (
 ): Promise<CheckResult[] | string> => {
   const stack = checkStackOf(stackOf(settings.stack))
   let plan: CheckPlan
+  let kitCopies: string[]
   try {
-    const kitCopies = kitCopyPaths(readJsonIfPresent(join(root, TOOL_DIRECTORY, MANIFEST_FILE)))
+    kitCopies = kitCopyPaths(readJsonIfPresent(join(root, TOOL_DIRECTORY, MANIFEST_FILE)))
     plan = planChecks(
       files,
       {
@@ -253,7 +298,7 @@ const checkChanges = async (
     testCommandResult(settings.commands.test, settings.stack),
     missingTestCommandResult(settings.commands.test, settings.stack),
     namedTestResult(plan.sourcesWithoutNamedTest),
-    ...ownChecksOf(root, plan.paths, settings, home),
+    ...ownChecksOf(root, plan.paths, settings, home, kitCopies),
   ])
 }
 
@@ -282,7 +327,7 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
   }
   print(settings.notes)
   if (files.length === 0) {
-    console.log('Nothing changed.')
+    console.log(`Nothing changed.${installedReferenceHint(root, REFERENCE.events, home)}`)
     return 0
   }
   const results = await checkChanges(files, root, settings, runModeOf(args), home)