jackherd 1.7.0 → 1.8.0

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

@@ -69,6 +69,12 @@ What gets documented after completion?
 
 - [ ] ...
 
+## 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)
+
 ## Rejected Alternatives
 
 | Idea | Reason |

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

@@ -69,6 +69,12 @@ Was wird nach Abschluss dokumentiert?
 
 - [ ] ...
 
+## 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)
+
 ## Verworfene Alternativen
 
 | Idee | Grund |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jackherd",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "keywords": [
     "claude-code",
     "coding-agents",
@@ -48,11 +48,12 @@
     "!docs/gen",
     "assets",
     "!assets/icons/build.ts",
+    "recipes",
     "README.md",
     "INSTALL.md",
     "CHANGELOG.md",
     "LICENSE",
-    "NOTICE",
+    "NOTICE.txt",
     "install.sh"
   ],
   "publishConfig": {

package/recipes/README.md

@@ -0,0 +1,21 @@
+# Source recipes
+
+Each recipe is one `watch.sources` entry for the jackherd watcher: put in your key, project or query, then try it with `jh watch source <name> --dry-run` (and `--raw` where the shape differs from what is shown). `/jh-follow` picks a recipe and fills it for you. Where a recipe leaves a field open, [Rules every recipe follows](#rules-every-recipe-follows) decides; every field and limit of a source is in [sources.md](sources.md).
+
+| Service | Recipe | Login | Script |
+| --- | --- | --- | --- |
+| Jira, with the Atlassian CLI | [jira-cli.md](jira-cli.md) | `acli jira auth login` | [sources/jira.ts](sources/jira.ts) |
+| Jira, over REST with `curl` | [jira-rest.md](jira-rest.md) | API token in `~/.netrc` | none |
+| Linear, over GraphQL | [linear.md](linear.md) | `LINEAR_API_KEY` | [sources/linear.ts](sources/linear.ts) |
+| GitHub issues | [github-issues.md](github-issues.md) | `gh auth login` | none |
+| GitHub Projects, as tickets | [github-projects.md](github-projects.md) | `gh auth refresh -s project` | none |
+| Sentry | [sentry.md](sentry.md) | `SENTRY_AUTH_TOKEN` | [sources/sentry.ts](sources/sentry.ts) |
+| A status page | [status-page.md](status-page.md) | none, public API | none |
+
+## 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.
+- **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/github-issues.md

@@ -0,0 +1,23 @@
+# GitHub issues
+
+**Login:** `gh auth login`, kept by `gh`. No script.
+
+**Entry:**
+
+```json
+{
+  "name": "decisions",
+  "command": ["gh", "issue", "list", "--repo", "<owner>/<repo>", "--label", "decision", "--json", "number,title,url,updatedAt,comments"],
+  "map": {
+    "id": ".number",
+    "updatedAt": ".updatedAt",
+    "title": ".title",
+    "url": ".url",
+    "body": ".comments[-1].body",
+    "author": ".comments[-1].author.login"
+  },
+  "ignoreAuthors": ["<your-login>"]
+}
+```
+
+**Limits:** without `--limit`, `gh issue list` returns 30 issues. `ignoreAuthors` keeps your own comments from waking anybody.

package/recipes/github-projects.md

@@ -0,0 +1,22 @@
+# GitHub Projects
+
+Reads the cards of a project board as tickets, without a script, so the herd shows each card as a badge beside its lane's plan.
+
+**Login:** `gh` needs the `project` scope, `gh auth refresh -s project`.
+
+`<n>` is the project's number, `<owner>` its organization or `@me`; without `--limit` `gh` returns only 30 cards. Each card is `items[]` with its `id`, `title`, `content` (the issue or pull request, `content.url`; a draft card has none, so its badge has no link) and one key per project field, the name with a lower-case first letter, so the `Status` field is `.status` and holds the option's name. A card carries no time of its own, so the entry maps no `updatedAt` and a change of the title or URL is the change. The cards belong to a lane through `lane`, since their ids (`PVTI_…`) are not what a plan names.
+
+**Entry:**
+
+```json
+{
+  "name": "board",
+  "command": ["gh", "project", "item-list", "<n>", "--owner", "<owner>", "--format", "json", "--limit", "200"],
+  "items": ".items",
+  "ticket": true,
+  "lane": "<lane>",
+  "map": { "id": ".id", "title": ".title", "url": ".content.url", "status": ".status" }
+}
+```
+
+**Limits:** jackherd only reads the board. The status moves by the project's own workflows (Settings → Workflows: "Item closed" and "Pull request merged" set Done, "Auto-add" brings new issues in), and a pull request moves its issue's card only when its description links it with `Closes #<n>`; otherwise the status stays where it was. Add `"reportOn": ["status"]` to be told of each move as well.

package/recipes/jira-cli.md

@@ -0,0 +1,26 @@
+# Jira with the Atlassian CLI
+
+**Login:** `acli jira auth login`, kept by `acli`. No token passes through the source.
+
+`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.
+
+**Entry:**
+
+```json
+{
+  "name": "tickets-decisions",
+  "command": ["bun", "scripts/sources/jira.ts"],
+  "map": {
+    "id": ".key",
+    "updatedAt": ".updated",
+    "title": ".summary",
+    "url": ".url",
+    "body": ".body",
+    "author": ".author"
+  }
+}
+```
+
+**Limits:** one `view` call per item, six at a time; a query that returns many items takes longer. The search stops at 100 items (`--limit`). Before filling, read `acli jira workitem search --help` and `workitem view --help` of your installed version: the fields and options it names decide, not this recipe.

package/recipes/jira-rest.md

@@ -0,0 +1,24 @@
+# Jira over REST with `curl`
+
+One call returns everything, where the CLI needs one call per item, but it needs an API token.
+
+**Token:** an API token of your Atlassian account in `~/.netrc` (`machine <site>.atlassian.net login <email> password <api-token>`, mode 600), which `curl --netrc` reads without a shell; `<host>` is the same `<site>.atlassian.net`.
+
+**Entry:** version 3 of the API returns a comment body as a document tree, so the path reaches into its first paragraph:
+
+```json
+{
+  "name": "tickets-decisions",
+  "command": ["curl", "-fsS", "--max-time", "20", "--netrc", "-G", "https://<host>/rest/api/3/search/jql", "--data-urlencode", "jql=key in (PROJ-123)", "--data-urlencode", "fields=summary,updated,comment"],
+  "items": ".issues",
+  "map": {
+    "id": ".key",
+    "updatedAt": ".fields.updated",
+    "title": ".fields.summary",
+    "body": ".fields.comment.comments[-1].body.content[0].content[0].text",
+    "author": ".fields.comment.comments[-1].author.displayName"
+  }
+}
+```
+
+**Limits:** the body shows only the first text node of the comment's first paragraph; a comment that starts with a mention or a list shows less. For the whole text, use the [CLI recipe](jira-cli.md), whose script joins the nodes.

package/recipes/linear.md

@@ -0,0 +1,25 @@
+# Linear over GraphQL
+
+**Token:** a personal API key in `LINEAR_API_KEY`, sent as `Authorization: <key>` without `Bearer`.
+
+**Script:** copy [sources/linear.ts](sources/linear.ts) to `scripts/sources/linear.ts` in your repository, put your team key and issue number into `query`, and set `<host>` to the API host `api.linear.app`. Linear answers a bad key or query with HTTP 200 and an `errors` list, so the script checks for it as well.
+
+**Entry:**
+
+```json
+{
+  "name": "linear-eng-123",
+  "command": ["bun", "scripts/sources/linear.ts"],
+  "items": ".data.issues.nodes",
+  "map": {
+    "id": ".identifier",
+    "updatedAt": ".updatedAt",
+    "title": ".title",
+    "url": ".url",
+    "body": ".comments.nodes[-1].body",
+    "author": ".comments.nodes[-1].user.name"
+  }
+}
+```
+
+**Limits:** check with `--raw` which end of `comments.nodes` holds the newest comment; `[0]` instead of `[-1]` if it is the first.

package/recipes/sentry.md

@@ -0,0 +1,18 @@
+# Sentry
+
+**Token:** an auth token with `event:read` in `SENTRY_AUTH_TOKEN`; `<host>` is `sentry.io` or your own.
+
+**Script:** copy [sources/sentry.ts](sources/sentry.ts) to `scripts/sources/sentry.ts` in your repository and put your organization and project into the URL.
+
+**Entry:**
+
+```json
+{
+  "name": "errors",
+  "every": 10,
+  "command": ["bun", "scripts/sources/sentry.ts"],
+  "map": { "id": ".id", "updatedAt": ".lastSeen", "title": ".title", "url": ".permalink", "body": ".culprit" }
+}
+```
+
+**Limits:** `lastSeen` moves with every event, but title, culprit and link do not, so only a new issue wakes the coordinator, not each occurrence.

package/recipes/sources/jira.ts

@@ -0,0 +1,51 @@
+// Copy to scripts/sources/jira.ts in your repository; the recipe recipes/jira-cli.md says what to fill in.
+const jql = 'project = PROJ AND assignee = currentUser() AND statusCategory != Done'
+const host = '<host>'
+const parallel = 6
+
+type DocumentNode = { type?: string; text?: string; attrs?: { text?: string }; content?: DocumentNode[] }
+type IssueComment = { author?: { displayName?: string }; body?: DocumentNode }
+type Issue = { key: string; fields: { updated: string; summary: string; comment?: { comments: IssueComment[] } } }
+
+const plainText = (node: DocumentNode): string =>
+  node.type === 'text' || node.type === 'mention'
+    ? (node.text ?? node.attrs?.text ?? '')
+    : (node.content ?? []).map(plainText).join('')
+
+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)
+  try {
+    return JSON.parse(output)
+  } catch {
+    return process.exit(1)
+  }
+}
+
+const entryOf = ({ key, fields }: Issue) => {
+  const latest = fields.comment?.comments.at(-1)
+  return {
+    key,
+    url: `https://${host}/browse/${key}`,
+    updated: fields.updated,
+    summary: fields.summary,
+    author: latest?.author?.displayName ?? null,
+    body: latest?.body ? plainText(latest.body) : null,
+  }
+}
+
+const keys = ((await acli(['jira', 'workitem', 'search', '--jql', jql, '--limit', '100', '--json'])) as { key: string }[]).map(
+  ({ key }) => key,
+)
+const entries = []
+for (let start = 0; start < keys.length; start += parallel) {
+  const batch = keys.slice(start, start + parallel)
+  const issues = await Promise.all(
+    batch.map((key) => acli(['jira', 'workitem', 'view', key, '--fields', 'summary,updated,comment', '--json'])),
+  )
+  entries.push(...(issues as Issue[]).map(entryOf))
+}
+console.log(JSON.stringify(entries))
+
+export {}

package/recipes/sources/linear.ts

@@ -0,0 +1,19 @@
+// Copy to scripts/sources/linear.ts in your repository; the recipe recipes/linear.md says what to fill in.
+const token = process.env.LINEAR_API_KEY
+if (!token) process.exit(1)
+
+const query = `{ issues(filter: { team: { key: { eq: "ENG" } }, number: { eq: 123 } }) {
+  nodes { identifier title url updatedAt comments { nodes { body user { name } } } } } }`
+
+const response = await fetch('https://<host>/graphql', {
+  method: 'POST',
+  headers: { Authorization: token, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ query }),
+  signal: AbortSignal.timeout(20_000),
+})
+if (!response.ok) process.exit(1)
+const answer = (await response.json()) as { errors?: unknown }
+if (answer.errors) process.exit(1)
+console.log(JSON.stringify(answer))
+
+export {}

package/recipes/sources/sentry.ts

@@ -0,0 +1,12 @@
+// Copy to scripts/sources/sentry.ts in your repository; the recipe recipes/sentry.md says what to fill in.
+const token = process.env.SENTRY_AUTH_TOKEN
+if (!token) process.exit(1)
+
+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)
+console.log(JSON.stringify(await response.json()))
+
+export {}

package/recipes/sources.md

@@ -0,0 +1,80 @@
+# How a source works
+
+The fields and limits of a `watch.sources` entry, for a source no [recipe](README.md) covers or a field a recipe leaves open.
+
+Source reports are off unless the config lists `watch.sources`. The watcher cannot use the MCP servers of a Claude Code session: their connections and logins (often OAuth in a browser) belong to the session. A source is a command instead, which prints JSON on stdout. It runs without a shell, in the main checkout, with your environment, so its token stays where it is. `/jh-follow` fills one of the [recipes](README.md) for you.
+
+```json
+{
+  "watch": {
+    "sources": [
+      {
+        "name": "tickets",
+        "every": 5,
+        "command": ["tickets-cli", "search", "--query", "key in (T-123)", "--json"],
+        "items": ".issues",
+        "map": {
+          "id": ".key",
+          "updatedAt": ".fields.updated",
+          "title": ".fields.summary",
+          "body": ".fields.comment.comments[-1].body",
+          "author": ".fields.comment.comments[-1].author.name"
+        },
+        "ignoreAuthors": ["me"],
+        "lane": "search"
+      }
+    ]
+  }
+}
+```
+
+```text
+=== source tickets (search) T-123 Decide the layout · updated
+  Yes, take variant B.
+  https://<host>/browse/T-123
+```
+
+`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.
+
+**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`.
+
+```json
+"map": { "id": ".key", "updatedAt": ".fields.updated", "title": ".fields.summary", "status": ".fields.status.name", "assignee": ".fields.assignee.displayName" },
+"reportOn": ["status", "assignee"]
+```
+
+```text
+=== source tickets (search) T-123 Decide the layout · updated: status In progress → Ready for Dev, assignee (empty) → alex
+  https://<host>/browse/T-123
+```
+
+At most 10 fields. For this the saved state keeps the value of each `reportOn` field on one line, as the report shows it (up to 200 characters, a longer one as its first 180, `…` and a hash of the whole, so any change shows). A field added to `reportOn` later, or a source that gains `reportOn`, starts from what it reads then and reports nothing for that first read; a state from an earlier version is read as it is, and dropping `reportOn` reports nothing either.
+
+A run that ends with an exit code other than 0, runs past 30 seconds (then its whole process group is killed, a `curl` behind a script included), prints more than 1 MB, cannot be read, prints no JSON or not the configured shape reports once per streak, with the reason only and never stderr, which may carry a token. While it fails, the status block ends with `source tickets failing since 10:15:00`; the watcher and the other sources go on:
+
+```text
+=== source tickets failed: exit 1
+```
+
+**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.
+
+**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`:
+
+```text
+dry run source tickets: ["tickets-cli","search","--query","key in (T-123)","--json"]
+2 entries
+  T-123 · alex · Decide the layout
+  T-124 · me · Pick a colour (ignoreAuthors)
+first run of this source: baseline, nothing reported; later a new or changed entry reports like this:
+=== source tickets (search) T-123 Decide the layout · new
+  Yes, take variant B.
+watcher state not read or changed; the watcher takes a new source over at its next start
+```
+
+The watcher reads `watch.sources` when it starts: a new or changed source counts from its next start.
+
+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/recipes/status-page.md

@@ -0,0 +1,19 @@
+# A status page
+
+A page on the common status page service answers its public API without a token; `<host>` is the page's own.
+
+**Login:** none. No script.
+
+**Entry:**
+
+```json
+{
+  "name": "provider-status",
+  "every": 5,
+  "command": ["curl", "-fsS", "--max-time", "20", "https://<host>/api/v2/incidents/unresolved.json"],
+  "items": ".incidents",
+  "map": { "id": ".id", "updatedAt": ".updated_at", "title": ".name", "url": ".shortlink", "body": ".incident_updates[0].body" }
+}
+```
+
+**Limits:** the newest update stands first in `incident_updates`, so each new update of an open incident reports `updated` with its text. A resolved incident drops out of the list and reports nothing more.

package/schemas/jackherd.schema.json

@@ -67,7 +67,7 @@
     "baseBranch": {
       "default": "main",
       "type": "string",
-      "pattern": "^(?![-/.])(?!.*(?:\\.\\.|\\/\\/|@\\{|\\.lock(?:\\/|$)))[A-Za-z0-9._/-]+(?<![./])$"
+      "pattern": "^(?!HEAD$)(?![-/.])(?!.*(?:\\.\\.|\\/\\/|@\\{|\\.lock(?:\\/|$)))[A-Za-z0-9._/-]+(?<![./])$"
     },
     "skillPrefix": {
       "default": "",
@@ -234,17 +234,17 @@
           "default": {},
           "type": "object",
           "properties": {
-            "warnAt": {
-              "default": 0.6,
-              "type": "number",
+            "warnTokens": {
+              "default": 250000,
+              "type": "integer",
               "exclusiveMinimum": 0,
-              "exclusiveMaximum": 1
+              "maximum": 9007199254740991
             },
-            "alertAt": {
-              "default": 0.8,
-              "type": "number",
+            "alertTokens": {
+              "default": 350000,
+              "type": "integer",
               "exclusiveMinimum": 0,
-              "exclusiveMaximum": 1
+              "maximum": 9007199254740991
             },
             "windows": {
               "default": {},
@@ -269,17 +269,17 @@
               "default": {},
               "type": "object",
               "properties": {
-                "warnAt": {
-                  "default": 0.5,
-                  "type": "number",
+                "warnTokens": {
+                  "default": 200000,
+                  "type": "integer",
                   "exclusiveMinimum": 0,
-                  "exclusiveMaximum": 1
+                  "maximum": 9007199254740991
                 },
-                "alertAt": {
-                  "default": 0.7,
-                  "type": "number",
+                "alertTokens": {
+                  "default": 300000,
+                  "type": "integer",
                   "exclusiveMinimum": 0,
-                  "exclusiveMaximum": 1
+                  "maximum": 9007199254740991
                 }
               },
               "additionalProperties": false
@@ -491,7 +491,9 @@
         "commands": {
           "default": [
             "gh pr merge",
-            "gh workflow run"
+            "gh workflow run",
+            "gh run rerun",
+            "gh api"
           ],
           "type": "array",
           "items": {
@@ -528,6 +530,28 @@
             }
           },
           "additionalProperties": false
+        },
+        "planApproval": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "exceptPaths": {
+              "default": [],
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9_.*/-]+$"
+              }
+            },
+            "requiredChecks": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "maxLength": 200
+              }
+            }
+          },
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

package/src/check/command.ts

@@ -78,7 +78,7 @@ const readPlanFile = (file: string): string | null => {
   }
 }
 
-/** `jh check --parallel <plan>`: the groups of phases that can run side by side, read from the plan as it is on disk. */
+/** `jh check --parallel <plan>`: the waves of phases that can run side by side and the critical path, read from the plan as it is on disk. */
 const printParallel = (path: string, settings: CheckSettings): number => {
   const file = resolve(process.cwd(), path)
   const markdown = path === '' ? null : readPlanFile(file)
@@ -112,7 +112,7 @@ const executePlan = async (
 
 /**
  * Runs the configured checks over the files `git status` reports. Exit code 1 when any check fails
- * or the configuration cannot be read. With `--parallel <plan>` it runs no check and prints the plan's parallel groups.
+ * or the configuration cannot be read. With `--parallel <plan>` it runs no check and prints the plan's waves and critical path.
  */
 export const run = async (args: string[], home: string = homedir()): Promise<number> => {
   const target = resolveCheckTarget(process.cwd(), home, existsSync, gitTopLevelOf)

package/src/check/parallel-report.ts

@@ -1,7 +1,7 @@
-import { parallelGroupsOfPlan, phasesText } from '../plan-format'
+import { type PhaseSchedule, phaseLabels, phasesText, wavesOfPlan } from '../plan-format'
 import type { PlanLanguage } from '../vocabulary'
 
-/** The flag by which `jh check` prints the parallel groups of one plan instead of running the checks. */
+/** The flag by which `jh check` prints the waves of one plan instead of running the checks. */
 export const PARALLEL_FLAG = '--parallel'
 
 /** The plan path after `--parallel`: empty when it is missing, null when the flag is absent. */
@@ -10,14 +10,24 @@ export const parallelArgument = (args: readonly string[]): string | null => {
   return index === -1 ? null : (args[index + 1] ?? '')
 }
 
+/** `critical path: P1 → P3 → P6 (3 phases)` */
+const criticalPathLine = (path: readonly string[]): string =>
+  `critical path: ${phaseLabels(path, ' → ')} (${path.length} ${path.length === 1 ? 'phase' : 'phases'})`
+
+const scheduleLines = ({ waves, criticalPath, unplaced }: PhaseSchedule): string[] => [
+  ...(waves.length === 0
+    ? ['no phase is ready']
+    : waves.map((wave, index) => `wave ${index + 1}: ${phasesText(wave)}`)),
+  ...(criticalPath.length > 0 ? [criticalPathLine(criticalPath)] : []),
+  ...(unplaced.length > 0 ? [`in no wave: ${phaseLabels(unplaced, ' ')}`] : []),
+]
+
 /**
- * What `jh check --parallel <plan>` prints: one line per group of phases that can run side by side (the first group
- * can start now), or the reason there is none.
+ * What `jh check --parallel <plan>` prints: one line per wave of phases that can run side by side, in order (the
+ * first wave can start now, each later one once the waves before it are done), the critical path, and the open
+ * phases no wave holds; or the reason there is no wave.
  */
 export const parallelReportLines = (markdown: string, language: PlanLanguage): string[] => {
-  const groups = parallelGroupsOfPlan(markdown, language)
-  if (groups === null) return ['no dependency table']
-  return groups.length === 0
-    ? ['no phase is ready']
-    : groups.map((group, index) => `group ${index + 1}: ${phasesText(group)}`)
+  const schedule = wavesOfPlan(markdown, language)
+  return schedule === null ? ['no dependency table'] : scheduleLines(schedule)
 }

package/src/cli.ts

@@ -24,6 +24,7 @@ export const COMMANDS: CommandTable = {
   [HERD_COMMAND.name]: () => import('./plans/command'),
   init: () => import('./sync/init-command'),
   [HERD_COMMAND.alias]: () => import('./plans/command'),
+  settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),
   update: () => import('./update/command'),
   watch: () => import('./watch/command'),