jackherd 1.7.0 → 1.8.0

package/kit/hooks/statusline.sh

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Status line for Claude Code: model, context use and session cost. Shipped by jackherd.
 # Enable it in .claude/settings.json: "statusLine": { "type": "command", "command": ".claude/statusline.sh" }
-# Colours follow plans.context of the jackherd config: the lane thresholds inside a worktree, the
-# coordinator's elsewhere; without a config, yellow from 60 % and red from 85 %.
+# Colours follow plans.context of the jackherd config, in tokens in the context: the lane thresholds inside a
+# worktree, the coordinator's elsewhere; without thresholds in the config, jackherd's default thresholds in tokens.
+# Either stops at 60 % and 85 % of the window.
 input=$(cat)
 
 model=$(jq -r '.model.display_name // .model.id // "?"' <<<"$input")
@@ -11,6 +12,9 @@ cost=$(jq -r '.cost.total_cost_usd // 0' <<<"$input")
 cwd=$(jq -r '.workspace.current_dir // .cwd // empty' <<<"$input")
 pct_int=${pct%.*}
 [ -z "$pct_int" ] && pct_int=0
+# Tokens in the context: the count Claude Code reports, else share times window.
+tokens=$(jq -r '(.context_window.total_input_tokens // ((.context_window.used_percentage // 0) * (.context_window.context_window_size // 0) / 100)) | floor' <<<"$input" 2>/dev/null)
+[[ "$tokens" =~ ^[0-9]+$ ]] || tokens=0
 
 case '{{kit.responseLanguage}}' in
   German) label='Kontext'; compact_hint='/compact oder /clear' ;;
@@ -41,27 +45,36 @@ config_file() {
   config_in "$HOME"
 }
 
-warn_pct=60
-alert_pct=85
+# The tokens decide, at the thresholds of the config or, where it leaves one out, at jackherd's defaults
+# (the schema's, as `jh context` reads them).
 config=$(config_file "${cwd:-$PWD}")
+worktrees='.claude/worktrees'
+[ -n "$config" ] && worktrees=$(jq -r '.worktreeDirectory // ".claude/worktrees"' "$config" 2>/dev/null)
+case "${cwd:-$PWD}/" in
+  */"$worktrees"/*) block='.plans.context'; warn_at=250000; alert_at=350000 ;;
+  *) block='.plans.context.coordinator'; warn_at=200000; alert_at=300000 ;;
+esac
 if [ -n "$config" ]; then
-  worktrees=$(jq -r '.worktreeDirectory // ".claude/worktrees"' "$config" 2>/dev/null)
-  case "${cwd:-$PWD}/" in
-    */"$worktrees"/*) block='.plans.context' ;;
-    *) block='.plans.context.coordinator' ;;
-  esac
-  # A share of the window (0.6) as a whole percent; empty when the config does not set it.
-  warn=$(jq -r "($block.warnAt // empty) * 100 | floor" "$config" 2>/dev/null)
-  alert=$(jq -r "($block.alertAt // empty) * 100 | floor" "$config" 2>/dev/null)
-  [[ "$warn" =~ ^[0-9]+$ ]] && warn_pct=$warn
-  [[ "$alert" =~ ^[0-9]+$ ]] && alert_pct=$alert
+  warn=$(jq -r "$block.warnTokens // empty | floor" "$config" 2>/dev/null)
+  alert=$(jq -r "$block.alertTokens // empty | floor" "$config" 2>/dev/null)
+  [[ "$warn" =~ ^[0-9]+$ ]] && warn_at=$warn
+  [[ "$alert" =~ ^[0-9]+$ ]] && alert_at=$alert
+fi
+# A threshold stops at a share of the window, so a small window still hands over before it is full.
+warn_cap=60
+alert_cap=85
+window=$(jq -r '.context_window.context_window_size // 0 | floor' <<<"$input" 2>/dev/null)
+if [[ "$window" =~ ^[0-9]+$ ]] && [ "$window" -gt 0 ]; then
+  [ "$warn_at" -gt $((window * warn_cap / 100)) ] && warn_at=$((window * warn_cap / 100))
+  [ "$alert_at" -gt $((window * alert_cap / 100)) ] && alert_at=$((window * alert_cap / 100))
 fi
+level=$tokens
 
 reset='\033[0m'
-if [ "$pct_int" -ge "$alert_pct" ]; then
+if [ "$level" -ge "$alert_at" ]; then
   color='\033[31m'
   hint=" ⚠ ${compact_hint}"
-elif [ "$pct_int" -ge "$warn_pct" ]; then
+elif [ "$level" -ge "$warn_at" ]; then
   color='\033[33m'
   hint=''
 else

package/kit/review/skills/diagnose/SKILL.md

@@ -5,7 +5,7 @@ description: 'Diagnosis loop for hard bugs, flaky failures and performance regre
 
 <!--
   Adapted from https://github.com/mattpocock/skills (skills/engineering/diagnosing-bugs),
-  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE in jackherd.
+  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE.txt in jackherd.
   Phase structure and the feedback-loop discipline are his; the loop recipes, redaction rules
   and hand-off targets are the kit's.
 -->

package/kit/review/skills/review/SKILL.md

@@ -22,6 +22,7 @@ Types, lint, unused imports, staged build artifacts and failing tests are decida
 3. **Function size**: anything past ~20 lines, or a description that needs an "and"
 4. **Duplication**: more than three lines of identical logic in two places
 5. **Design review**: the checklist in `.claude/rules/kit/code-style.md` → Design Review
+6. **Recurring context**: text and output that reach an agent's context again and again (skill and rule bodies, hook reasons, tool reports, event lines) justify their cost; count what the change adds there and weigh it against what it buys
 
 ## Output Format
 
@@ -38,6 +39,7 @@ Measured (jh check): PASS / FAIL
 3. Function size: ✅ / ❌
 4. Duplication:   ✅ / ❌
 5. Design review: ✅ / ❌
+6. Recurring context: ✅ / ❌
 
 Verdict: PASS / FIX FIRST
 ```

package/kit/rules/rules/kit/testing.md

@@ -84,8 +84,5 @@ mock.module('../adapters', () => ({
 
 `/pre-commit` runs `bunx jackherd check`, which measures types, lint, tests, staged build artifacts and the project's own checks. Beyond that, the judgement points:
 
-1. No unused imports left over from refactoring
-2. Version bumped if the change affects a published package (minor = feature, patch = fix)
-3. Code follows the order types → pure functions → higher-order functions, without section-label comments
-4. The design review in `code-style.md` passed
-5. No dead code: unused exports, unreachable branches, commented-out code removed from every changed file
+1. Version bumped if the change affects a published package (minor = feature, patch = fix)
+2. `code-style.md` holds in every changed file: its code order, and its design review passed, dead code (unused exports, unreachable branches, commented-out code) included

package/kit/rules/rules/kit/writing-for-agents.md

@@ -9,7 +9,7 @@ paths:
 
 <!--
   Adapted from https://github.com/mattpocock/skills (skills/productivity/writing-for-agents),
-  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE in jackherd.
+  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE.txt in jackherd.
   The levers are his; the kit mechanics and the worked examples are the kit's.
 -->
 
@@ -67,6 +67,8 @@ Every document spends one of two budgets:
 
 Material behind a pointer escapes context load at the price of the pointer's own line. Material with no pointer rides entirely on cognitive load.
 
+Context load also arrives later than the start of a session. Text and output that reach an agent's context again and again (a skill body, a hook's reason, a tool's report, an event line) justify their cost: each is paid on every arrival and read again on every turn after it. Count what a change adds there and weigh it against what it buys.
+
 ## Information hierarchy
 
 Documents are built from **steps** (ordered actions) and **reference** (facts consulted on demand), and they mix freely. The decision is where each piece sits:

package/kit/workflow/agents/spec-review.md

@@ -9,7 +9,7 @@ user-invocable: false
 <!--
   The two-axis idea (Standards vs. Spec) is adapted from
   https://github.com/mattpocock/skills (skills/engineering/code-review), commit 8b78b53,
-  MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE in jackherd. Only the Spec
+  MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE.txt in jackherd. Only the Spec
   axis is used here — the Standards axis is covered by /review and /uncle-bob.
 -->
 

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

@@ -6,13 +6,13 @@ argument-hint: 'What to follow, e.g. a ticket key, an issue or a query'
 
 If `.claude/project/follow.md` exists, read it first. It extends this skill for this project and wins where the two disagree.
 
-You add one entry to `watch.sources`, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the project's `.jackherd/config.json` in the main checkout, and only after the user approved the entry. How sources work, their fields and limits: the jackherd README, section **Source reports** and **Recipes**, in the installed package (`"$(dirname "$(readlink -f "$(command -v jh)")")/../README.md"`). Read those two sections; do not copy a recipe from memory.
+You add one entry to `watch.sources`, so that `jh watch` reports a new or changed entry of an external service as `=== source <name> …`. You run only reading commands; the one file you write is the project's `.jackherd/config.json` in the main checkout, and only after the user approved the entry. Read the recipe index `recipes/README.md` of the installed package first (`"$(dirname "$(readlink -f "$(command -v jh)")")/../recipes/README.md"`), then only the recipe file it names for the chosen service; do not copy a recipe from memory. Where the recipe leaves a field open, the index's section **Rules every recipe follows** decides, and `recipes/sources.md` beside it describes every field and limit of a source.
 
 ## 1. Ask
 
 `AskUserQuestion` in {{kit.responseLanguage}}, only for what the argument and the conversation leave open, each with the recommended option first; at most four questions per call, so more open points go into a second call:
 
-- **Service:** the recipes the README lists (Jira, Linear, GitHub issues, GitHub Projects, Sentry, a status page), and "another command that prints JSON".
+- **Service:** the services the recipe index lists, and "another command that prints JSON".
 - **What to follow:** the item the argument names (its comments, recommended) or a query over several items.
 - **Lane:** the lane the reports name, from the board's lanes table, or none.
 - **Ticket:** whether the entries are tickets (`ticket: true`, recommended for an issue tracker or a project board), which the herd shows as a badge beside the plan of their lane: the lane above, or the lane whose name, board row or plan names the ticket's id. A source of comments or messages is no ticket. The path of the status you find yourself in step 3.
@@ -30,7 +30,7 @@ Anything missing goes to the user as the command to run themselves (`! <command>
 
 Before filling, read the help of the installed CLI version for every command the recipe calls (`acli jira workitem search --help` and `workitem view --help`, `gh issue list --help`) and confirm that the fields and options the entry needs exist there. Read the provider's web documentation only when the help leaves it open or no recipe fits. A recipe is a starting point; the installed version decides.
 
-Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane`, `ignoreAuthors` and `ticket` where chosen. For a ticket source, find the path of the status in the output (from the CLI's help, or the dry run with `--raw`) and set it as `map.status`; the entry you show for approval in step 4 carries it, and without a status in the output the entry has none and the badge shows only the key. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]`. The script:
+Fill the recipe with the item or query and the answers from step 1: a `name` of letters, digits, `.`, `_` and `-` that says what is followed, `lane`, `ignoreAuthors` and `ticket` where chosen. For a ticket source, find the path of the status in the output (from the CLI's help, or the dry run with `--raw`) and set it as `map.status`; the entry you show for approval in step 4 carries it, and without a status in the output the entry has none and the badge shows only the key. A recipe that needs a script (a token from the environment, or one call per item) gets TypeScript run by Bun: write it, from the recipe's script under `recipes/sources/`, to the scratchpad first as `<name>.ts`, never into the repository before step 4, and let the entry's `command` be `["bun", "scripts/sources/<name>.ts"]`. The script:
 
 - bounds every request and every call of a tool with `AbortSignal.timeout(20_000)`, where a shell recipe would use `--max-time`;
 - reads a token only from `process.env`, and never prints it, passes it as an argument or writes it into an output;

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

@@ -7,7 +7,7 @@ argument-hint: 'Describe the idea, feature or change you want stress-tested'
 
 <!--
   Adapted from https://github.com/mattpocock/skills (skills/productivity/grilling),
-  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE in jackherd.
+  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE.txt in jackherd.
   The design-tree/frontier model is his; the question mechanics and the handover format to /plan
   are the kit's.
 -->

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

@@ -26,11 +26,11 @@ You are the **Implementer**. Your job is to carry tasks through completely: expl
 
 When the user asks for more than one phase:
 
-1. **Read the computed groups:** run `jh check --parallel <plan>`. It reads the plan's `{{kit.heading.dependencies}}` table and the plan's ticks and prints one line per group of phases that can run side by side, `group 1: P19 ∥ P20`; group 1 can start now, a later group waits for the phases before it. A phase is ready when every `{{kit.heading.dependsOn}}` entry is done (ticked off with its review gate); a phase with an external gate (`User: …`) is never ready, since the plan cannot say the gate holds. Two phases share a group only with no shared path under `{{kit.heading.writes}}` and no shared `{{kit.heading.serialMarker}}` (compared without case). Only backticked paths count, written from the repository root; a directory overlaps every file below it, a glob counts as the directory before its first wildcard, and a wildcard at the root (`*.md`) overlaps everything. A `like N` entry (`wie N`, the plan's own word) in the cell, with several phases (`like 15 and 16`) as their union, adds the sets of those phases. `no dependency table` means the plan has none: the phases run one after the other. `no phase is ready` means every open phase waits, is done, or is in no group.
-2. **Batch:** the requested phases in group 1. A requested phase in a later group waits, naming the phase it collides with. One in no group is not ready for one of these reasons: it is done, it has an external gate (ask whether the gate holds), its `like N` entry names an unknown phase or runs in a cycle, or its `{{kit.heading.writes}}` cell has no backticked path; say which. The command checks paths and markers only: two phases that collide in content, or both edit a shared release file (changelog, version bump), stay your judgement, so serialise them yourself.
-3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, prompt: …)` per phase, in the same checkout: the disjoint `{{kit.heading.writes}}` sets are the isolation. Each prompt names its phase (`Phase P<n>` and the plan's path, as in Step 0) and its `{{kit.heading.writes}}` set as the **only** paths it may edit, besides ticking its own phase's task lines in the plan, and states that it ticks the task checkboxes of its own phase as it finishes each one (Plan Hygiene), and leaves the review gate, commits and `/pre-commit` to you — it reports changed files, test results and the gate items it ran.
-4. **When the batch returns:** check each report against its set (`git diff --stat`; an edit outside the set is a finding; a ticked line outside its own phase is one too), tick what it left open, walk each review gate. Gate items that write outside a phase's set (documentation, plan synchronisation) are yours. Then recompute the ready set and dispatch the next batch.
-5. **Commits stay serial and with you:** one `/pre-commit` per finished phase, in phase order.
+1. **Read the computed waves:** run `jh check --parallel <plan>`. It reads the plan's `{{kit.heading.dependencies}}` table and the plan's ticks and prints one line per wave of phases that can run side by side, in order (`wave 1: P19 ∥ P20`), then `critical path: …` and `in no wave: …`; wave 1 can start now, each later wave once the waves before it are done. A phase is ready when every `{{kit.heading.dependsOn}}` entry is done (ticked off with its review gate); a phase with an external gate (`User: …`) is never ready, since the plan cannot say the gate holds. Two phases share a wave only with no shared path under `{{kit.heading.writes}}`, no shared `{{kit.heading.serialMarker}}` (compared without case), and no release of the same package: a marker `Release <package> <version>`, or the package's `CHANGELOG.md` or `package.json` under `{{kit.heading.writes}}`. Only backticked paths count, written from the repository root; a directory overlaps every file below it, a glob counts as the directory before its first wildcard, and a wildcard at the root (`*.md`) overlaps everything. A `like N` entry (`wie N`, the plan's own word) in the cell, with several phases (`like 15 and 16`) as their union, adds the sets of those phases. `no dependency table` means the plan has none: the phases run one after the other. `no phase is ready` means every open phase waits, is done, or is in no wave.
+2. **Batch:** the requested phases in wave 1. A requested phase in a later wave waits, naming the phase it collides with. One in no wave is not ready for one of these reasons: it has an external gate (ask whether the gate holds), its `like N` entry names an unknown phase or runs in a cycle, its `{{kit.heading.writes}}` cell has no backticked path, or it depends on such a phase; say which. The command checks paths, markers and releases only: two phases that collide in content stay your judgement, so serialise them yourself.
+3. **Dispatch the batch in one message**, one `Agent(subagent_type: 'implement', model: <from the model table>, prompt: …)` per phase, in the same checkout: the disjoint `{{kit.heading.writes}}` sets are the isolation. They may run in the background; a hand-over (Step 7) waits until all are back. Each prompt names its phase (`Phase P<n>` and the plan's path, as in Step 0) and its `{{kit.heading.writes}}` set as the **only** paths it may edit, besides ticking its own phase's task lines in the plan, and states that it ticks the task checkboxes of its own phase as it finishes each one (Plan Hygiene), and leaves the review gate, commits and `/pre-commit` to you — it reports changed files, test results and the gate items it ran.
+4. **When the batch returns:** check each report against its set (`git diff --stat`; an edit outside the set is a finding; a ticked line outside its own phase is one too), tick what it left open, walk each review gate. Gate items that write outside a phase's set (documentation, a changelog entry, plan synchronisation) are yours, at the wave's end. Then recompute the ready set and dispatch the next batch.
+5. **Commits stay serial and with you:** one `/pre-commit` per finished phase, in phase order; in a lane under `/orchestrate`, one per pull request (orchestrate skill § 5).
 
 ## Plan Hygiene (when implementing from a plan in `{{kit.planDirectory}}/`)
 
@@ -83,7 +83,7 @@ Once all tests are green, types are clean, the change has been looked at (Step 4
 
 Ask every question with a fixed set of answers through the `AskUserQuestion` tool, in {{kit.responseLanguage}}.
 
-The report at the end is short: one line of diff stat, one line per check with its numbers, open points, questions; everything else is in the plan, by reference.
+The report at the end is short: one line of diff stat, one line per check with its numbers, open points, questions; everything else is in the plan, by reference. Each question carries the situation, the problem and what each option leads to, in everyday words, not only the options and `file:line`. Mark each question `blocking` or `not blocking`. A blocking one stops the step it decides; a not blocking one leaves a `TODO` at its spot and the work goes on, with neither your recommendation nor another option built as decided.
 
 ### Git commands run one at a time
 
@@ -93,7 +93,7 @@ Why: Claude Code checks permissions per subcommand and splits a command at `&&`,
 
 ## Step 7: Phase Boundary
 
-Runs once a phase is committed or its pull request is merged, and only then — never in the middle of a task, and never before the phase's review gate is ticked.
+Runs once the phase's review gate is ticked off, committed or not (a lane under `/orchestrate` commits only when its pull request is ready), and only then — never in the middle of a task.
 
 1. Read the fill of your own context, from the log and not from memory:
 
@@ -101,7 +101,6 @@ Runs once a phase is committed or its pull request is merged, and only then —
    bunx jackherd context
    ```
 
-   It prints one line of JSON with `share` and `level` (`ok`, `warn` or `alert`), or `null` when there is no value (no terminal adapter, no log). `null` or `ok` → continue with the next phase in this chat, and say nothing about it.
-2. `warn` or `alert`, and a next phase exists → ask through `AskUserQuestion` whether the next phase runs in a new chat. Name the fill (`62 %`) in the question. The recommended option is the new chat. When the coordinator already asked this lane for its hand-over, do not ask: that request is the answer, go on with step 3.
-3. On yes, write the hand-over to `.claude/handover/<lane>.md` (`<lane>` is the name of the worktree directory; the directory is ignored by git and stays out of every commit) and end your turn with its path. The file holds, in this order: the state (branch, commits, what is merged), the open points, the next step, the traps you ran into, and links to the plan and the files that matter. The coordinator ends this agent and starts a fresh one in the same worktree with the hand-over as its first task.
-4. On no, continue.
+   It prints one line of JSON with `tokens`, `share` and `level` (`ok`, `warn` or `alert`, from the token thresholds `plans.context.warnTokens` and `alertTokens`), or `null` when there is no value (no terminal adapter, no log). `null` or `ok` → continue with the next phase in this chat, and say nothing about it. A line on stderr that the auto-compact window is not above `alertTokens` means Claude Code compacts before this hand-over: name it in one line of your report.
+2. `warn` or `alert`, and a next phase exists → the next phase runs in a new chat, without a question: go on with step 3, once every subagent you started is back, no dialog of yours is open and no question of yours waits for an answer. The same holds when Jack, the coordinator, asked this lane for its hand-over.
+3. Write the hand-over to `.claude/handover/<lane>.md` (`<lane>` is the name of the worktree directory; the directory is ignored by git and stays out of every commit) and end your turn with its path. The file holds, in this order: the line `{{kit.word.openSubagents}}: 0`, which the coordinator requires, the state (branch, commits or uncommitted changes, what is merged), the open points, the next step (after a wave, the state of each of its phases), the traps you ran into, and links to the plan and the files that matter. Jack ends this agent and starts a fresh one in the same worktree with the hand-over as its first task; without a coordinator, the last line names the fill and tells the user to start a new chat with that file.