jackherd 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 What changed for people who use jackherd, newest first.
 
+## 1.8.0
+
+- **Context thresholds are tokens.** `plans.context.warnTokens` and `alertTokens` (default 250000 and 350000) and the same keys in `plans.context.coordinator` (default 200000 and 300000) replace the shares `warnAt` and `alertAt`, so a 1M window no longer warns only at 600000. The window only bounds the share the herd shows. A config with shares is read as tokens of the largest window it names (rounded to thousands), and `jh sync` writes it that way once, with a line per block; `jh sync --check` only says so. The status line colours by tokens too, at these defaults when the config sets no threshold, as `jh context` does. Each threshold stops at 60 % (warn) and 85 % (alert) of the model's window, so a 200k window warns at 120000 and alerts at 170000. `jh context` adds a line on stderr when Claude Code's auto-compact window (`CLAUDE_CODE_AUTO_COMPACT_WINDOW` for its own session, `modelSettings.<model>.autoCompactWindow` or `autoCompactWindow` in the project's and the user's settings) is not above `alertTokens`, since Claude Code then compacts before the hand-over.
+- **The merge guard reads here-documents the way the shell does.** In a here-document with an unquoted delimiter, `\`` and `\$` are text, and `$(…)` and backticks are read as commands instead of making the whole call unparsable. The body ends at its delimiter line, as in the shell, so a substitution that does not close before it still makes the call unparsable, and the guard asks. A report written with `cat >> report.md <<E` that quoted `` \`gh api /markdown\` `` asked for approval of a merge; it now passes, while `` `gh pr merge 5` `` in such a body still asks. The git guard refuses a force push there for the push itself, no longer because the call could not be read.
+- **A `case` inside a command substitution makes the call unparsable.** The `)` of its patterns would close the substitution early, so the commands after it went unread; the guards now ask, also inside double quotes.
+- **`$((cmd) )` is no longer taken for arithmetic.** The shell runs it as a command substitution of a subshell; the guards now treat such a call as unparsable and ask, at the top level and in here-documents.
+- **Plan approval in the merge guard.** Approve a plan once with a dialog naming ``Plan `<path>` `` and the option "Approve the plan". From then on, `gh pr merge <n> --match-head-commit <sha>` for a lane of that plan passes without a question, when `<sha>` is the head commit GitHub reports, the pull request merges into the base branch, its head contains the base branch's tip, GitHub can merge it, it has at least one check and every check is green, the plan still has an open phase on the base branch, the lane's board row is open and no file matches a path that always asks. `guard.planApproval.requiredChecks` names checks that must also be among them, by their names on GitHub. A plan that gained a phase since the approval (a renamed one counts) asks again; one that gained tasks in the phases you saw asks too, naming them all in one question, unless a task is marked `(User <date> …)`. Ticked boxes are no growth. The approved state is read from git, the last commit of the base before your answer; a plan that was not on the base yet when you approved it asks once more after it landed. When two answers in one dialog name the same plan, only both together approve. Any newer answer to a plan question that is not "Approve the plan", free text included, ends the approval, even when its transcript is gone. The paths that always ask are `.github/**`, `**/migrations/**`, `**/.env*`, `.claude/**`, `.jackherd/**`, `bunfig.toml` (its `preload` runs before every hook), `**/CLAUDE.md`, `**/AGENTS.md`, `.agents/**`, `.mcp.json`, `.husky/**`, `lefthook.yml`, the lockfiles of bun, npm, pnpm and yarn, `**/.npmrc`, `**/CODEOWNERS`, every `package.json`, and the `CHANGELOG.md` of every package without `"private": true`, matched without regard to case. A project adds its own under `guard.planApproval.exceptPaths`. The guard fetches the base branch and reads these values from `.jackherd/config.json` there, never from the checkout or the home config; without a project config at the base, or with an invalid entry, plan approval is off. A new `PostToolUse` hook leaves a pointer to the dialog under `.jackherd/approvals/plans/`, so the approval survives `/clear`; the merge guard re-reads the answer from that transcript at every merge.
+- **Self-merge waits for green checks of the commit it merges.** A merge the user approved with "merge it yourself after green checks" now passes the merge guard only as `gh pr merge <n> --match-head-commit <sha>` with the head commit GitHub reports, when GitHub can merge the pull request, it has at least one check run and every check is green; before, the guard trusted the coordinator to wait. A commit status counts only when it is green: one set through the API right after a push cannot stand in for the checks, neither for this nor for `guard.planApproval.requiredChecks`. A skipped check counts as green, as on GitHub.
+- **Merging without checks needs the head commit.** A pull request whose files all match `merge.withoutChecks` passes only as `gh pr merge <n> --match-head-commit <sha>` with the head commit GitHub reports, and the file list counts only when the head did not move while it was read; a push after the check no longer slips through. `orchestrate` passes the `<sha>` on every merge.
+- **`baseBranch` cannot be `HEAD`.**
+- **Skills put the user on the loop.** `/orchestrate` asks for a plan approval in a dialog of its own before a plan's first lane (``Plan `<path>` ``, the approve label first, word for word), asks once more for phases the plan gained, and revokes it through the same dialog. A lane PR of an approved plan is rebased onto the base branch first, merged with `--match-head-commit <sha>` once green, and recorded as `merged without asking #<n> (plan approval <path>)` in the board's history, with one chat line and a push notice. Lanes mark every question `blocking` or `not blocking`; a not blocking one leaves a `TODO` and the lane works on, and the coordinator collects such questions for the next natural pause; silence is never an answer. The coordinator answers a lane's question itself only through `jh settled`. A side order is written `(User <DD.MM.> <HH:MM>)`, the one form the merge guard counts as seen by the user. New ideas during a release go to the plan's new `## Follow-ups` section (both plan templates) and are presented together once the release PR is merged. Lane and coordinator hand over to a fresh chat without asking, never with a dialog open, and say so afterwards; a lane checks its context once a phase's review gate is ticked off, committed or not, and runs one `/pre-commit` per pull request; a lane writes its hand-over only once every subagent of a wave is back, and it names every phase of the wave. The skills call the coordinator Jack. A phase gets a lane of its own only when it is clearly more work than setting up a lane and has its own pull request or release path; a small fix (one pull request, no plan, no migration) runs without a lane, built by an `implement` subagent, with one line in the board's history. `/plan` bundles small phases that share a release and puts shared text files (skills, README, changelog) in a small phase of their own.
+- **The coordinator's agent is `jack-<repository>`.** `jh watch`, `jh context --coordinator` and `jh herd --ensure` find it without a name and still find `orchestrator-<repository>`, the earlier default, so a running session keeps working; when both run, `jack-…` wins. `jh herd --ensure` labels the coordinator's herdr pane `🐾 Jack`.
+- **Recipes moved out of the README.** Each source recipe (Jira CLI and REST, Linear, GitHub Issues and Projects, Sentry, a status page) is a file under `recipes/` in the package, its script a real `recipes/sources/<name>.ts`; `recipes/README.md` is the index. The README is short: a sentence, the herdr picture, six points and a quickstart that shows `/jh-plan` and `/jh-implement` on their own before parallel lanes; the details fold into `<details>` blocks, and its package links carry no version pin.
+- **The approval gate knows a lane by its pane.** A lane is the herdr agent of the hook's pane (`herdr agent get $HERDR_PANE_ID`), named after the worktree it runs in, in the session the hook was called for. The directory of the call no longer counts, so a coordinator whose shell stands in a lane's worktree is not taken for that lane. `AskUserQuestion` is never held: a question is no permission.
+- **Plan approval lifts only the coordinator's merge:** the agent of the pane, in the merging session, started in the main checkout and not named after a lane's worktree. A lane session whose transcript lies beside the coordinator's no longer merges on the plan approval. Outside herdr, plan approval asks.
+- **Unreadable shell text fails closed.** A Bash command the shell parser cannot read (an unterminated quote or here-document, a quote or command inside `${…}`, a `case` inside a substitution, an escaped backtick inside backticks, a line of an unquoted here-document that ends in `\`, the evaluating expansions `${(e)…}` and `${…@P}`) now always asks in the merge guard and is always refused by the git guard, whatever words it holds. Before, both reacted only when `gh` or a git verb stood as a whole word, which a split word (`g''h`) slipped past. The reason names what the parser found and how to make the command readable. An empty `guard.commands` still guards nothing.
+- **Hooks no longer hang on a stuck program.** Every command a hook runs (`git`, `herdr pane list`) is killed after 3 s and counts as failed, so the hook decides as it does on any failure instead of holding the call until Claude Code's hook timeout.
+- **The git guard refuses a push to the base branch**, not only a force push: a refspec that targets `baseBranch` (`main`, `HEAD:main`, `refs/heads/main`, `:main`, `--delete`, wildcards), the matching refspec `:`, `--all`/`--branches`, and a push without a refspec, or with `HEAD`, from a branch that is the base branch or pushes to it as git's own push settings resolve it. When the guard cannot tell the target (an expanded refspec, a brace or glob pattern in it, a detached HEAD, a `cd` or branch switch earlier in the same command, an invalid `baseBranch` or an unreadable config), it refuses with a hint to name the branch. The base branch comes from the main checkout's `.jackherd/config.json` (default `main`, `refs/heads/<name>` counts as `<name>`), read by the same rule the merge guard uses. Config and git are read only for a command that pushes.
+- **`jh check --parallel` prints every wave.** `wave N: …` instead of `group N: …`, in order, then the critical path (the longest chain over dependencies and shared serial markers or releases) and the open phases no wave holds. Two phases that release the same package never share a parallel group; the package comes from a release marker that names it (`Release jackherd 1.8.0`) or from a write of its `CHANGELOG.md` or `package.json`.
+- **The herd says what a lane works on.** An open lane shows its current phase in the head line, then a session line with the agent's title from herdr, the branch and the context, then `NOW` (one `▶` row per phase being worked on, `· n min ago`, amber from 20 min, and `→` the task it is on), `NEXT` (the next wave), `LATER` (the other open phases) and `DONE` (finished phases on one line, `(not merged)` where it applies). This replaces the plan tree and "also open". A phase is done once its tasks and its review gate are ticked off, in the herd as in `jh check --parallel`; a phase with an open gate stays under `NOW` or `NEXT`. Progress counts over the lane's whole plans and adds `· n/m ph` for phases; the model shows only when it differs from the plan's recommendation.
+- **Appointments in the board.** `jh watch` reads the board's appointment section (`## Termine` / `## Appointments`, columns When, Action, Origin, Status) and reports each open appointment once when it falls due: `=== due <when> · <action>`. The reported keys (local minute + action) live in the watcher's state file, so a restart neither repeats nor drops one, an appointment that fell due while the watcher was down reports at the next run, and a moved one reports again. An open row whose time cannot be read reports once as `=== appointment unreadable <when> · <action>`. Columns are found by their header, in any order; a table without When, Action or Status reports once as unreadable with the missing columns.
+- **`jh settled`: the one way for the coordinator to answer a lane's question itself.** `jh settled <lane> --question <sentence> --answer <text> --evidence <file:line> --topic <topic> [--way-back <text>] [--board <board.md>]` checks that the evidence file and line exist and that the line records a dated decision of the `User` (any line of a rule or skill file counts; a line of the board's own settled section never does, it would cite itself), refuses topics the user always decides (new dependencies, merge, release, publish, migration, money, auth, RLS, secrets, writes against stage or production, deletion, push), appends the row to the board's settled section (created when missing; the evidence cell names the short commit that last changed the cited file, or `@uncommitted`), sends the answer through `herdr agent prompt` and prints the line for the user's chat. A failed send is reported (exit 2) and noted in the board row.
+- **The herd's tree in one alignment.** The trunk of an open lane hangs under its status symbol; `SESSION` (the agent's title, branch and context) and the 📎 chips are branches like NOW, NEXT, LATER and DONE, every label in one column and every content behind it; the `→` task of a closed running phase stands under the phase's title. The phase count reads `· 4/14 ph`, so a lone letter at the edge no longer looks cut off, and stands right-aligned in the width of the widest one on screen, so the bars, `◐` and 🥣 of all lanes start in one column.
+- **NOW shows the work, not the bookkeeping.** Only ticks and new task lines outside a phase's review gate count as movement, so ticking review gates across a plan no longer puts all those phases under NOW at once.
+- **The board choice stays out of the herd's picture.** When several boards were found, the line saying which one was chosen and why no longer stands in the herd's frame; `herd --once` prints it once on stderr, and the watcher's `armed:` report keeps it.
+- **The herd labels its own pane.** `jh herd --lane <name>` labels its herdr pane `herd · <name>`, a herd of all lanes `herd`, through `herdr pane rename` and apart from the sidebar titles; the label is cleared when the view quits. Outside herdr nothing changes.
+- **Interpreters are read like `sh -c`.** Program text given to `python3 -c`, `bun -e`, `node -e` or on an interpreter's input (`python3 -`, a here-document, a pipe) is searched for the guarded commands: the merge guard asks, the git guard refuses. Only options before the script file count, so `python3 script.py -e foo` is not taken for program text.
+- **Shell aliases and functions cannot hide a guarded command.** The guards read the names from Claude Code's shell snapshot; a word at a program position whose alias or function body names `git` or `gh` is refused by the git guard and asked by the merge guard, with the command to run written out instead. A program taken from a variable or a substitution (`f=shipit; $f main`) counts when a function of that kind is named in the script, also as the default of an expansion (`${x:-shipit}`, nested, of an array element or of an empty name), and any such function counts when the script lists the shell's functions (`functions`, `functions_source`, `compgen -A function` or `-c`, `declare -F`, `typeset +f`, `whence -m`, `type -m`, a bare `set`). The action of `trap` is read like `sh -c`, and `eval` and `trap` count quoted or escaped too, in a function body and after `coproc`, `repeat`, `nocorrect` or zsh's `-`, but only where they are the command, so `grep trap` and `timeout 30 rg eval` stay a search. An `alias` command or a `functions[…]`/`BASH_ALIASES[…]` entry is read like `sh -c`. The snapshot is read only from regular files.
+- **Programs that run command text are guarded.** `watch`, `script -c`, `parallel`, `npx -c`, `npm exec -c`, `pnpm dlx -c`, `osascript`, sed's `e` and awk's `system()` are read like `sh -c` in both guards. The git guard refuses `eval` and `sh -c` with a script taken from a variable or a substitution.
+- **Words are searched as the shell decodes them.** A guarded command split by quotes (`pu""sh`) or written in `$'…'` escapes is found, in the script and in a variable it is assigned to.
+- **`gh api` writes that merge or rerun ask.** The default `guard.commands` covers `gh api` with a method other than GET on a pull request merge, `merges`, a file under `contents/`, a workflow dispatch, a ref, and a run's `rerun` or `rerun-failed-jobs`; `X-HTTP-Method-Override` counts as the method, and the path is normalised (case, `%`-escapes, doubled slashes, a fragment). `gh run rerun` asks too. A comment through `gh api` still passes.
+- **A hand-over waits for every subagent.** A lane writes its hand-over file only once all its subagents are back, with the line `open subagents: 0` (in the plan's language); Jack hands a lane over only when the file carries that line and the lane is idle or done.
+- **jackherd speaks English on screen.** The herd, the CLI output (`jh check`, `jh context`, `jh settled`), the watcher's events and status lines and the hooks' reasons are English. What comes from your files (phase titles, tasks, board rows) stays in its language, and headings or lines jackherd writes into a plan, a board or a hand-over follow the plan's language; `responseLanguage` now covers only the replies.
+- **Less to read on every call.** `orchestrate` keeps the steps every run takes and reads the rest only when it needs it, from `references/` (the plan commit, sensitive input, how the herd reads plans, the hand-over script): about 950 tokens less per call. The kit rule `testing.md` no longer repeats `code-style.md`. Tests cap the size of every skill, every always-loaded rule and every agent, and the lines of the watcher's status block.
+- **Every field of a source is documented again.** `recipes/sources.md` describes a `watch.sources` entry, its fields and its limits, linked from the recipes index; `/jh-follow` reads it only when a recipe leaves a field open.
+- **Questions carry their context.** `orchestrate` and `implement` have a lane's question, and Jack's question to you, say the situation, the problem and what each option leads to, in everyday words, not only the options and `file:line`.
+- **The README is short.** A head that says what jackherd does, a quickstart from install to `/jh-start` and the first plan, the feature lines with their icons, and the details folded in `<details>`; the reference that stood below moved into those sections or into `INSTALL.md` and `recipes/`. The feature icons share one size, stroke and left edge. The license note of the adapted kit files ships as `NOTICE.txt`.
+
 ## 1.7.1
 
 - **`jh update` no longer installs the kit into a project.** It synced every project with a `.jackherd/config.json`, including one that holds only settings for the global install, and so wrote kit files, hooks in `.claude/settings.json`, a `.gitignore` line and `.jackherd/lock.json` there unasked. Now it syncs only a project with an install of its own (`.jackherd/lock.json`, or the lock from before the rename); for any other it prints one line that it was not synced and that `jh init` installs the kit there.

package/INSTALL.md

@@ -139,6 +139,8 @@ The global skills cannot carry one repository's values, so `sync --global` write
 
 `jh update` asks npm for the newest release and, when there is one, installs exactly that version, from your home directory and without install scripts, with the package manager that installed the kit globally (bun, npm, pnpm or yarn, read from where the package lies), then syncs `~/.claude` and, inside a project with its own install (`.jackherd/lock.json`), the project with the freshly installed code. A project that has only a `.jackherd/config.json` for the global install is not synced; one line says so, and `jh init` installs the kit there. It prints the old and the new version. A kit that is a project dependency or a source checkout is not a global install, and `update` says so and changes nothing; there, update the dependency and run `jh sync`.
 
+Context thresholds are tokens (`plans.context.warnTokens`, `alertTokens`, the same in `coordinator`). A config that still gives them as a share of the window (`warnAt`, `alertAt`) is read as tokens of the largest window it names, and the next `jh sync` writes them that way once and says so.
+
 A running herd restarts itself with the new code, and a running `watch` prints `=== kit updated <old> → <new>` and ends, so the coordinator reads its skill again and starts the stream again.
 
 ## Keeping the global kit current

package/{NOTICE → NOTICE.txt}

@@ -1,4 +1,4 @@
-@crossdelta/agent-kit
+jackherd
 Copyright (c) crossdelta
 
 This package includes material adapted from third-party sources.