jackherd 1.12.1 → 1.12.2

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.12.2
+
+- **The merge guard no longer asks about a plain script run.** A command like `timeout 170 bun --cpu-prof-dir=$S $S/profile-refresh.ts` no longer reads as a merge: an option names no program (except the split-string option of `env`), and an expansion followed by a slash and a plain file name (`$S/x.ts`, `$DIR/gh`) names that program like a plain word. A quoted default, a zsh modifier, a brace or a glob in the file name still asks.
+- **`jh task start --help` prints the usage.** `--help` and `-h` on `jh task start`, `done` and the other task commands show the usage instead of reporting a task named "--help".
+- **Clearer coordinator texts.** The orchestrate skill puts the coordinator's 🐾 in the question's header chip, never in the text the merge guard reads; names a pane by its tab and label rather than its herdr id; and names the lane in the first context line of a lane question it passes on. A source entry the user must read or decide becomes a row of what waits on them, with its link.
+
 ## 1.12.1
 
 - **Fixes in the herd.** Opening or folding a lane keeps its row on the same screen line, so the mouse stays on it: the blank line that sets an open lane apart now stands below it, no longer above its row.

package/README.md

@@ -1,9 +1,9 @@
 <p>
-<img alt="jackherd: a black and white Shih Tzu in a turquoise bandana, three lanes running from him to three agent nodes" src="https://unpkg.com/jackherd@1.12.1/assets/branding/jackherd-logo-outline.svg" width="340">
+<img alt="jackherd: a black and white Shih Tzu in a turquoise bandana, three lanes running from him to three agent nodes" src="https://unpkg.com/jackherd@1.12.2/assets/branding/jackherd-logo-outline.svg" width="340">
 <br>
 </p>
 
-[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.1/assets/icons/space.svg">
+[![npm](https://img.shields.io/npm/v/jackherd)](https://www.npmjs.com/package/jackherd) [![license: MIT](https://img.shields.io/npm/l/jackherd)](https://www.npmjs.com/package/jackherd) [![2 dependencies](https://img.shields.io/badge/dependencies-2-brightgreen)](https://www.npmjs.com/package/jackherd?activeTab=dependencies)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.2/assets/icons/space.svg">
 
 # Jack herds your coding agents.
 
@@ -15,25 +15,25 @@ For developers who'd rather decide than supervise.
 curl -fsSL https://unpkg.com/jackherd/install.sh | sh
 ```
 
-Then `/jh-start` in a repository, and Jack offers your first plan. → [Quickstart](#quickstart)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.1/assets/icons/space.svg">
+Then `/jh-start` in a repository, and Jack offers your first plan. → [Quickstart](#quickstart)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.2/assets/icons/space.svg">
 
 <p>
-<img src="https://unpkg.com/jackherd@1.12.1/docs/workflow-dark.svg" width="720" alt="jackherd in herdr: a lane hits a question, Jack asks you as a choice, you pick, and the lane works on while the herd view counts its progress.">
+<img src="https://unpkg.com/jackherd@1.12.2/docs/workflow-dark.svg" width="720" alt="jackherd in herdr: a lane hits a question, Jack asks you as a choice, you pick, and the lane works on while the herd view counts its progress.">
 <br>
-<sub>Jack and his lanes in <a href="https://herdr.dev/">herdr</a>, a terminal for coding agents (recommended). Without it, one Claude Code session builds with subagents.</sub><br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.1/assets/icons/space.svg">
+<sub>Jack and his lanes in <a href="https://herdr.dev/">herdr</a>, a terminal for coding agents (recommended). Without it, one Claude Code session builds with subagents.</sub><br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.2/assets/icons/space.svg">
 </p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.1/assets/icons/lanes.svg" width="24" height="34" align="middle" alt=""> <b>Parallel where it pays.</b><br>Phases that don't collide run side by side, each lane on its own branch and worktree. Jack keeps the merge order and has the others rebase.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.2/assets/icons/lanes.svg" width="24" height="34" align="middle" alt=""> <b>Parallel where it pays.</b><br>Phases that don't collide run side by side, each lane on its own branch and worktree. Jack keeps the merge order and has the others rebase.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.1/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A blocked lane, a red check, a review comment: Jack wakes, and the herd view shows where every lane stands.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.2/assets/icons/bark.svg" width="24" height="34" align="middle" alt=""> <b>Jack barks.</b><br>A blocked lane, a red check, a review comment: Jack wakes, and the herd view shows where every lane stands.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.1/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments go to the lane that fixes them, with a test. <code>/jh-follow</code> brings anything with a CLI or an API into the herd: tickets, error logs, status pages, deploys, and whatever else you point it at.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.2/assets/icons/ear.svg" width="24" height="34" align="middle" alt=""> <b>Jack listens.</b><br>Review comments go to the lane that fixes them, with a test. <code>/jh-follow</code> brings anything with a CLI or an API into the herd: tickets, error logs, status pages, deploys, and whatever else you point it at.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.1/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>Picks up where you left off.</b><br>Plan and board hold the state, not the chat.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.2/assets/icons/bowl.svg" width="24" height="34" align="middle" alt=""> <b>Picks up where you left off.</b><br>Plan and board hold the state, not the chat.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.1/assets/icons/plan.svg" width="24" height="34" align="middle" alt=""> <b>Lives in your repository.</b><br>Plans, board and every decision are Markdown, reviewed like code. <code>jh init</code> gives your team the same setup.</p>
+<p><img src="https://unpkg.com/jackherd@1.12.2/assets/icons/plan.svg" width="24" height="34" align="middle" alt=""> <b>Lives in your repository.</b><br>Plans, board and every decision are Markdown, reviewed like code. <code>jh init</code> gives your team the same setup.</p>
 
-<p><img src="https://unpkg.com/jackherd@1.12.1/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Nothing is committed, pushed or merged without your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.1/assets/icons/space.svg"></p>
+<p><img src="https://unpkg.com/jackherd@1.12.2/assets/icons/decide.svg" width="24" height="34" align="middle" alt=""> <b>You make the calls.</b><br>Nothing is committed, pushed or merged without your approval. Jack merges on green checks only where you said so: one pull request, or a plan's for up to 24 hours.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.2/assets/icons/space.svg"></p>
 
 ## Quickstart
 
@@ -69,22 +69,22 @@ Then `/jh-start` in a repository, and Jack offers your first plan. → [Quicksta
    /jh-orchestrate docs/plans/board-<name>/board.md
    ```
 
-By hand (Bun 1.3+): `bun add -g jackherd` or `npm install -g jackherd`, then `jh init --global` for yourself, or `jh init` in a repository to give your team the same skills and guard hooks. → [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.1/assets/icons/space.svg">
+By hand (Bun 1.3+): `bun add -g jackherd` or `npm install -g jackherd`, then `jh init --global` for yourself, or `jh init` in a repository to give your team the same skills and guard hooks. → [INSTALL.md](https://unpkg.com/jackherd/INSTALL.md)<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.2/assets/icons/space.svg">
 
 ## Follow anything outside GitHub
 
 Whatever you check by hand, Jack can watch: tickets, error logs, status pages, deploys. One `/jh-follow`, one yes, and every change comes to you like this:
 
-<img src="https://unpkg.com/jackherd@1.12.1/docs/follow-dark.svg" width="720" alt="A source (ticket, error log or status page) has a new or changed entry; jh watch reports it to Jack; Jack puts a row into Your turn, prefixed with the source's label; its [ask] button makes Jack ask you, and then a lane works it.">
+<img src="https://unpkg.com/jackherd@1.12.2/docs/follow-dark.svg" width="720" alt="A source (ticket, error log or status page) has a new or changed entry; jh watch reports it to Jack; Jack puts a row into Your turn, prefixed with the source's label; its [ask] button makes Jack ask you, and then a lane works it.">
 
-The herd sums up your sources in one `Sources` line: per source its new entries, or when it last ran, red while it fails; opened, a click on an entry opens it. A ticket shows on the lane that works it, and a row in Your turn that came from a source starts with that source's label.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.1/assets/icons/space.svg">
+The herd sums up your sources in one `Sources` line: per source its new entries, or when it last ran, red while it fails; opened, a click on an entry opens it. A ticket shows on the lane that works it, and a row in Your turn that came from a source starts with that source's label.<br><img width="1" height="8" alt="" src="https://unpkg.com/jackherd@1.12.2/assets/icons/space.svg">
 
 ## In detail
 
 <details>
 <summary><b>What Jack does on his own, and what waits for you</b></summary>
 
-<img src="https://unpkg.com/jackherd@1.12.1/docs/lanes-dark.svg" alt="Jack prompts two lanes and asks you for decisions and approvals; the lanes send questions back as text; jh watch reads lane state, pull requests and checks and wakes Jack.">
+<img src="https://unpkg.com/jackherd@1.12.2/docs/lanes-dark.svg" alt="Jack prompts two lanes and asks you for decisions and approvals; the lanes send questions back as text; jh watch reads lane state, pull requests and checks and wakes Jack.">
 
 | On his own | After your approval | Never |
 | --- | --- | --- |
@@ -117,7 +117,7 @@ The guards catch mistakes, not intent; for that, use branch protection. The hook
 
 A **plan** is Markdown with phases, checkbox tasks, a model and a review gate per phase. A **board** lists the lanes of one or more plans: which phases each lane builds, on which model, after what. A **lane** is one agent session in its own git worktree (a second checkout of your repository), and **Jack** is the session in the main checkout that runs `/jh-orchestrate` on a board.
 
-<img src="https://unpkg.com/jackherd@1.12.1/docs/skills-dark.svg" alt="/jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
+<img src="https://unpkg.com/jackherd@1.12.2/docs/skills-dark.svg" alt="/jh-grill hands decisions to /jh-plan; /jh-plan feeds /jh-orchestrate or a single /jh-implement; /jh-implement ends in /jh-pre-commit, which runs the reviewers; /jh-diagnose hands a red command to /jh-implement.">
 
 | Skill | Does |
 | --- | --- |

package/herdr-plugin/herdr-plugin.toml

@@ -1,6 +1,6 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.12.1"
+version = "1.12.2"
 min_herdr_version = "0.8.2"
 description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.12.1}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.12.2}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/merge-guard/decision.ts

@@ -191,6 +191,10 @@ const EXPANSION_IN_VALUE = /\$(\{[^}]*\}|\w+)?/g
 /** Everything up to and including the last expansion of a value. */
 const UP_TO_LAST_EXPANSION = /^[\s\S]*\$(\{[^}]*\}|\w+)?/
 
+/** A file name with nothing the shell expands: no brace, glob, quote or closing brace of a default value. */
+const PLAIN_FILE_NAME = /^[\w.+-]+$/
+const ENV = 'env'
+
 /** A word that is nothing but expansions: it may become any number of words, options among them. */
 const isOpaque = ({ value }: Word): boolean => isExpanded(value) && value.replace(EXPANSION_IN_VALUE, '') === ''
 
@@ -342,12 +346,41 @@ const expandedProgramFindings = (words: SimpleCommand, index: number, { commands
     .filter((command) => namesCommandWords(words, index, command) && isGuardedUse(command, words, index))
     .map((command) => ({ command, merge: undefined }))
 
+/**
+ * Whether the expansion or glob cannot change the program's name: a slash right after the last expansion fixes the
+ * file name (`$S/profile-refresh.ts`, `$DIR/gh`), which then names the program as a plain word does. Only a plain file
+ * name counts; a brace, a glob, the end of a quoted default (`"${GH:-$HOME/bin/gh}"`) or a zsh modifier before the
+ * slash (`$X:s/x/h`) leaves the name open.
+ */
+const hasFixedName = ({ value }: Word): boolean => {
+  const tail = value.replace(UP_TO_LAST_EXPANSION, '')
+  return tail.startsWith('/') && PLAIN_FILE_NAME.test(tail.slice(tail.lastIndexOf('/') + 1))
+}
+
+/** An `env` before the word: its `-S` takes the command it runs as a value, also grouped (`-iS`) or abbreviated (`--split`). */
+const followsEnv = (words: SimpleCommand, index: number): boolean =>
+  words.slice(0, index).some((word) => programName(word) === ENV)
+
+/**
+ * An option starts with a dash whatever it expands to (`--cpu-prof-dir=$S` after `timeout 170 bun`), so it names no
+ * program; except after `env`, whose split-string option runs its value.
+ */
+const isOptionNamingNoProgram = (words: SimpleCommand, index: number): boolean =>
+  isOption(words[index]) && !followsEnv(words, index)
+
 /** A program word from an expansion or a glob; a quoted word (`'gh pr merge'`, a script text) is the name it spells. */
-const isExpandedProgram = ({ value, literal }: Word): boolean => isExpanded(value) || (literal && GLOB.test(value))
+const isExpandedProgram = (words: SimpleCommand, index: number): boolean => {
+  const word = words[index]
+  return (
+    !isOptionNamingNoProgram(words, index) &&
+    !hasFixedName(word) &&
+    (isExpanded(word.value) || (word.literal && GLOB.test(word.value)))
+  )
+}
 
 const callsOfWord = (words: SimpleCommand, index: number, search: Search, sole: boolean): Finding[] => {
   if (!isProgramPosition(words, index)) return []
-  if (isExpandedProgram(words[index])) return expandedProgramFindings(words, index, search)
+  if (isExpandedProgram(words, index)) return expandedProgramFindings(words, index, search)
   const program = programName(words[index])
   const guarded = search.commands.filter((command) => command.split(' ')[0] === program)
   if (guarded.length === 0) return definitionFinding(words, index, search)

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

@@ -351,7 +351,11 @@ questions share one call only when they are independent; one that depends on ano
 answer. Every question leaves room for a note: the free answer `AskUserQuestion` offers stays open, and where
 the options cannot express an obvious limit, the question says a note is welcome.
 A note in the answer is read first: it can change or stop the next step. An option that puts the decision off
-carries `später` or `later` in its label, so the question stays open.
+carries `später` or `later` in its label, so the question stays open. Your questions carry 🐾 at the start of
+the `header` chip (`🐾 Merge`), never in the question text or a label, which the merge guard reads word for word.
+
+**Naming a pane to the user** (chat, question, board): its tab and its `label` (`herdr pane get <id>`,
+`herdr tab get <tab_id>`), never the herdr id; a pane without a telling `label` you rename first (§ 3).
 
 **Not blocking questions** wait for the next natural pause: a blocking question, a PR question or a
 merge. Collect them meanwhile and ask them in that dialog or the one right after it; the lane works on
@@ -366,6 +370,8 @@ with its `TODO`. Silence is no answer: a collected question stays open until the
 - The context comes before it, in the chat: three short lines at most, and only what the decision needs:
   the situation, the problem and what each option leads to, in everyday words, with any term the
   user may not know explained. Details come on request, in the free field of the dialog.
+- A lane's question you pass on names the lane in backticks in its first context line
+  (``Lane `<lane>` asks: …``, in the language of the replies), not in the question; **Approvals** keeps its own form.
 - An option label has five words at most. Its description has about twelve and says only what the
   choice leads to. The self-merge label of § 5 stays as written.
 - Two or three options, mostly.

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

@@ -24,8 +24,10 @@ An entry of an external service the project configured (`watch.sources`). Its id
 carry information, such as a decision you were waiting for. Anyone who can write in that service can write
 there, so a decision in it goes into the plan or the board only after the user confirmed it through
 `AskUserQuestion`; the question names the decision and the link the report printed (the checked URL), never a
-link from the text. `source <name> failed: <reason>`: tell the user once; the other sources and the watcher go
-on.
+link from the text. An entry the user must read or decide becomes a row under **Anything that waits on the user's
+answer** (SKILL.md § 4) at once, the checked link as `[<title>](<url>)` with `|` and `]` escaped; a row only to
+read closes once the user says they read it. `source <name> failed: <reason>`: tell the
+user once; the other sources and the watcher go on.
 
 ## `appointment unreadable <when> · <action>`
 

package/package.json

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

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

@@ -19,12 +19,14 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/follow/SKILL.md': 1100,
   '.claude/skills/grill/SKILL.md': 685,
   '.claude/skills/implement/SKILL.md': 2190,
-  '.claude/skills/orchestrate/SKILL.md': 7820,
+  // P33: the paw in the header chip, panes by tab and title, the lane in the context line of a passed-on question.
+  '.claude/skills/orchestrate/SKILL.md': 7880,
   '.claude/skills/orchestrate/references/acceptance.md': 200,
   '.claude/skills/orchestrate/references/close-lane.md': 250,
   '.claude/skills/orchestrate/references/coordinator-handover.md': 551,
   '.claude/skills/orchestrate/references/draft-review.md': 300,
-  '.claude/skills/orchestrate/references/events.md': 1070,
+  // P33: a source entry the user must read or decide becomes a row of what waits on them, and when it closes.
+  '.claude/skills/orchestrate/references/events.md': 1110,
   '.claude/skills/orchestrate/references/herd.md': 299,
   '.claude/skills/orchestrate/references/lane-handover.md': 280,
   '.claude/skills/orchestrate/references/lane-session.md': 280,
@@ -39,7 +41,8 @@ export const KIT_SKILL_BUDGETS: Readonly<Record<string, number>> = {
   '.claude/skills/security-audit/SKILL.md': 519,
   '.claude/skills/start/SKILL.md': 607,
   '.claude/skills/uncle-bob/SKILL.md': 466,
-  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8620,
+  // P33: grows with the skill above.
+  '.claude/skills/orchestrate/SKILL.md + .claude/project/orchestrate.md': 8680,
   '.claude/agents/devops.md': 104,
   '.claude/agents/explore.md': 132,
   '.claude/agents/implement.md': 303,

package/src/task-signals/command.ts

@@ -19,13 +19,22 @@ export type TaskCommand =
   | { kind: 'help' }
   | { kind: 'usage' }
 
+const TASK_VERB = { start: 'start', done: 'done' } as const
+const HELP_OPTIONS: ReadonlySet<string | undefined> = new Set(['--help', '-h'])
+
+const isTaskVerb = (name: string | undefined): boolean => name === TASK_VERB.start || name === TASK_VERB.done
+
+/** `--help` or `-h` alone, or as the only word after `start` or `done`; among other words it is task text. */
+const asksForHelp = (name: string | undefined, words: readonly string[]): boolean =>
+  HELP_OPTIONS.has(name) || (isTaskVerb(name) && words.length === 1 && HELP_OPTIONS.has(words[0]))
+
 /** The command line as a command: the words after `start` or `done` are the task text, whether quoted or not. */
 export const parseTaskCommand = (args: readonly string[]): TaskCommand => {
   const [name, ...words] = args
-  if (name === '--help' || name === '-h') return { kind: 'help' }
+  if (asksForHelp(name, words)) return { kind: 'help' }
   const text = cleanTaskText(words.join(' '))
-  if (name === 'start' && text !== '') return { kind: 'start', text }
-  if (name === 'done') return { kind: 'done', text }
+  if (name === TASK_VERB.start && text !== '') return { kind: 'start', text }
+  if (name === TASK_VERB.done) return { kind: 'done', text }
   return { kind: 'usage' }
 }