jackherd 1.7.1 → 1.8.1

package/kit/hooks/hooks/shared/shell.ts

@@ -27,6 +27,22 @@ type Handler = (cursor: Cursor, state: ListState) => boolean
 
 export class ShellParseError extends Error {}
 
+/** What a guard tells the agent when it refuses or asks for a script `parseShell` cannot read. */
+export const UNREADABLE_ADVICE =
+  'Avoid quotes, substitutions and operators inside `${…}` and `$((…))`, close every quote and here-document, or put the script in a file and run that.'
+
+/** `<<EOF` or `<<-EOF` with an unquoted delimiter, not a here-string. */
+const EXPANDING_HERE_DOCUMENT = /(^|[^<])<<-?[ \t]*[A-Za-z_]/
+
+/**
+ * What a guard adds when the script holds a here-document with an unquoted delimiter: the shell runs `$(…)` and
+ * backticks in its body, which plain text such as Markdown rarely means. Empty for any other script.
+ */
+export const expandingHereDocumentAdvice = (script: string): string =>
+  EXPANDING_HERE_DOCUMENT.test(script)
+    ? "The shell runs `$(…)` and backticks in a here-document with an unquoted delimiter; for plain text, quote it (`<<'EOF'`)."
+    : ''
+
 const BLANKS = ' \t'
 const OPERATORS = '&;|'
 const REDIRECTION_CHARS = '<>&|'
@@ -35,6 +51,9 @@ const DELIMITER_END = ' \t\n;&|<>()'
 /** Marks where an expansion stood in a word (`$z` keeps its name after it): the value is unknown before the shell runs. */
 const EXPANSION = '$'
 
+/** Whether an expansion stood in the word's value, so the shell decides the text only when it runs. */
+export const isExpanded = (value: string): boolean => value.includes(EXPANSION)
+
 const peek = (cursor: Cursor, offset = 0): string => cursor.source[cursor.index + offset] ?? ''
 
 /** Whether the character is one of `chars`; the empty string past the end of input never is. */
@@ -68,10 +87,13 @@ const appendShaped = (state: ListState, text: string): void => {
 /** `{a,b}` and `{a..b}` expand into other words before the program sees them. */
 const BRACE_EXPANSION = /\{[^}]*(,|\.\.)[^}]*\}/
 
+/** Whether the shell would expand braces in the word's value into several words. */
+export const expandsBraces = (value: string): boolean => BRACE_EXPANSION.test(value)
+
 const endWord = (state: ListState): void => {
   const { word } = state
   if (!word) return
-  if (BRACE_EXPANSION.test(word.value)) word.literal = false
+  if (expandsBraces(word.value)) word.literal = false
   state.word = undefined
   if (state.dropNextWord) state.dropNextWord = false
   else state.words.push(word)
@@ -90,11 +112,21 @@ const endCommand = (state: ListState): void => {
  */
 const MAYBE_COMMAND = /\$\(|[<>]\(|[`'";&|\n\\]/
 
+/**
+ * `${(e)x}` (zsh flags) and `${x@P}` (bash prompt expansion) evaluate the variable's value as shell text, so a
+ * substitution stored in it runs.
+ */
+const EVALUATING_EXPANSION = /^\$\{\(|@P/
+
 /** Rather than parse a command inside an expansion, the whole text is refused as unparsable. */
 const assertNoHiddenCommand = (text: string): void => {
   if (MAYBE_COMMAND.test(text)) throw new ShellParseError('a command or quote inside an expansion')
 }
 
+const assertNotEvaluating = (text: string): void => {
+  if (EVALUATING_EXPANSION.test(text)) throw new ShellParseError('an expansion that evaluates its value')
+}
+
 const skipBalanced = (cursor: Cursor, open: string, close: string): void => {
   const start = cursor.index
   let depth = 0
@@ -107,19 +139,60 @@ const skipBalanced = (cursor: Cursor, open: string, close: string): void => {
   throw new ShellParseError(`missing ${close}`)
 }
 
-const SUBSTITUTION = /\$\(|`/
+/** Where the line at the cursor ends: at its newline, or at the end of input. */
+const lineEnd = (cursor: Cursor): number => {
+  const newline = cursor.source.indexOf('\n', cursor.index)
+  return newline === -1 ? cursor.source.length : newline
+}
+
+const isDelimiterLine = (cursor: Cursor, { delimiter, stripTabs }: Heredoc): boolean => {
+  const line = cursor.source.slice(cursor.index, lineEnd(cursor))
+  return (stripTabs ? line.replace(/^\t+/, '') : line) === delimiter
+}
 
-/** Skips the body. A substitution in an expanding body runs, so it is refused as unparsable. */
-const readHeredocBody = (cursor: Cursor, { delimiter, stripTabs, expands }: Heredoc): void => {
+/**
+ * Reads the commands of an expanding body. A backslash escapes the next character, so `\`` and `\$`
+ * stay text; `$(…)` and backticks run. The body ends at its delimiter line before the shell expands
+ * it, so a substitution that does not close inside the body is unparsable.
+ */
+const readExpandingBody = (body: string): SimpleCommand[] => {
+  const cursor: Cursor = { source: body, index: 0 }
+  const state = newListState()
   while (!atEnd(cursor)) {
-    const newline = cursor.source.indexOf('\n', cursor.index)
-    const lineEnd = newline === -1 ? cursor.source.length : newline
-    const line = cursor.source.slice(cursor.index, lineEnd)
-    cursor.index = lineEnd + 1
-    if ((stripTabs ? line.replace(/^\t+/, '') : line) === delimiter) return
-    if (expands && SUBSTITUTION.test(line)) throw new ShellParseError('a command inside a here-document')
+    if (!BODY_HANDLERS.some((handle) => handle(cursor, state))) cursor.index++
   }
-  throw new ShellParseError(`here-document without its ${delimiter} line`)
+  return state.commands
+}
+
+const skipLine = (cursor: Cursor): void => {
+  cursor.index = lineEnd(cursor) + 1
+}
+
+/** An odd number of backslashes at the end of the line: the last one joins the next line to it. */
+const CONTINUED_LINE = /(?:^|[^\\])(?:\\\\)*\\$/
+
+/**
+ * In an expanding body `\⏎` joins two lines before the shell looks for the delimiter, so `EO\⏎F` ends the body
+ * where the parse would not: such a body is refused as unparsable.
+ */
+const assertNotContinued = (cursor: Cursor): void => {
+  if (CONTINUED_LINE.test(cursor.source.slice(cursor.index, lineEnd(cursor)))) {
+    throw new ShellParseError('a line continuation in a here-document body')
+  }
+}
+
+/** Skips the body; in an expanding body the commands of its substitutions run, so they are kept. */
+const readHeredocBody = (cursor: Cursor, heredoc: Heredoc, commands: SimpleCommand[]): void => {
+  const start = cursor.index
+  while (!atEnd(cursor)) {
+    if (isDelimiterLine(cursor, heredoc)) {
+      if (heredoc.expands) commands.push(...readExpandingBody(cursor.source.slice(start, cursor.index)))
+      return skipLine(cursor)
+    }
+    if (heredoc.expands) assertNotContinued(cursor)
+    skipLine(cursor)
+  }
+  throw new ShellParseError(`here-document without its ${heredoc.delimiter} line`)
 }
 
 const readHeredocHeader = (cursor: Cursor, stripTabs: boolean): Heredoc => {
@@ -161,7 +234,7 @@ const newline: Handler = (cursor, state) => {
   if (peek(cursor) !== '\n') return false
   endCommand(state)
   cursor.index++
-  for (const heredoc of state.heredocs) readHeredocBody(cursor, heredoc)
+  for (const heredoc of state.heredocs) readHeredocBody(cursor, heredoc, state.commands)
   state.heredocs = []
   return true
 }
@@ -181,7 +254,16 @@ const singleQuoted: Handler = (cursor, state) => {
   return true
 }
 
-const ANSI_C_ESCAPES: Record<string, string> = { n: '\n', t: '\t', r: '\r', e: '\u001b', a: '\u0007', b: '\b', f: '\f', v: '\v' }
+const ANSI_C_ESCAPES: Record<string, string> = {
+  n: '\n',
+  t: '\t',
+  r: '\r',
+  e: '\u001b',
+  a: '\u0007',
+  b: '\b',
+  f: '\f',
+  v: '\v',
+}
 const MAX_CODE_POINT = 0x10ffff
 const ANSI_C_NUMERIC = /^(x[0-9a-fA-F]{1,2}|u[0-9a-fA-F]{1,4}|U[0-9a-fA-F]{1,8}|[0-7]{1,3})/
 
@@ -217,15 +299,41 @@ const ansiCQuoted: Handler = (cursor, state) => {
   return true
 }
 
+/**
+ * A backtick substitution ends at its first unescaped backtick, and inside it `` \` `` opens a nested one that the
+ * parse would read as text: such a substitution is refused as unparsable. The cursor stands after the opening one.
+ */
+const assertNoNestedBacktick = ({ source, index }: Cursor): void => {
+  for (let at = index; at < source.length && source[at] !== '`'; at++) {
+    if (source[at] !== '\\') continue
+    if (source[at + 1] === '`') throw new ShellParseError('an escaped backtick inside backticks')
+    at++
+  }
+}
+
+/**
+ * Parses a substitution's list up to its terminator. A `case` in it is refused as unparsable: the
+ * `)` of its patterns would close the substitution early and leave the rest of its commands unread.
+ */
+const parseSubstitution = (cursor: Cursor, terminator: Terminator): SimpleCommand[] => {
+  if (terminator === '`') assertNoNestedBacktick(cursor)
+  const commands = parseList(cursor, terminator)
+  if (commands.some(([program]) => program.value === 'case')) throw new ShellParseError('a case inside a substitution')
+  return commands
+}
+
 const substitute = (cursor: Cursor, state: ListState, skip: number, terminator: Terminator): void => {
   cursor.index += skip
-  state.commands.push(...parseList(cursor, terminator))
+  state.commands.push(...parseSubstitution(cursor, terminator))
   appendShaped(state, EXPANSION)
 }
 
 const startsCommandSubstitution = (cursor: Cursor): boolean =>
   peek(cursor) === '$' && peek(cursor, 1) === '(' && peek(cursor, 2) !== '('
 
+const startsArithmetic = (cursor: Cursor): boolean =>
+  peek(cursor) === '$' && peek(cursor, 1) === '(' && peek(cursor, 2) === '('
+
 const readDoubleQuotedEscape = (cursor: Cursor, state: ListState): void => {
   const next = peek(cursor, 1)
   if (next !== '\n') appendShaped(state, isOneOf('$`"\\', next) ? next : `\\${next}`)
@@ -238,10 +346,32 @@ const backtick: Handler = (cursor, state) => {
   return true
 }
 
-const arithmetic: Handler = (cursor, state) => {
-  if (peek(cursor) !== '$' || peek(cursor, 1) !== '(' || peek(cursor, 2) !== '(') return false
+/** Whether the inner parenthesis of `((…))` closes right before the outer one, as arithmetic does. */
+const innerClosesLast = (text: string): boolean => {
+  let depth = 0
+  for (let at = 1; at < text.length; at++) {
+    if (text[at] === '(') depth++
+    if (text[at] === ')' && --depth === 0) return at === text.length - 2
+  }
+  return false
+}
+
+/**
+ * Skips `$((…))` from the cursor on its `$`. Text that opens like it but closes differently, such
+ * as `$((cmd) )`, is a command substitution of a subshell and is refused as unparsable.
+ */
+const skipArithmetic = (cursor: Cursor): void => {
   cursor.index++
+  const start = cursor.index
   skipBalanced(cursor, '(', ')')
+  if (!innerClosesLast(cursor.source.slice(start, cursor.index))) {
+    throw new ShellParseError('a command substitution that opens with a subshell')
+  }
+}
+
+const arithmetic: Handler = (cursor, state) => {
+  if (!startsArithmetic(cursor)) return false
+  skipArithmetic(cursor)
   appendShaped(state, EXPANSION)
   return true
 }
@@ -252,8 +382,22 @@ const commandSubstitution: Handler = (cursor, state) => {
   return true
 }
 
-/** Inside double quotes only these two still open a command. */
-const QUOTED_HANDLERS: Handler[] = [backtick, commandSubstitution]
+/**
+ * Inside double quotes and here-document bodies a `${…}` stays text the parse does not follow, so this only refuses
+ * one that evaluates its value; it never consumes the text and leaves it to the next handler.
+ */
+const evaluatingExpansion: Handler = (cursor) => {
+  if (peek(cursor) !== '$' || peek(cursor, 1) !== '{') return false
+  const close = cursor.source.indexOf('}', cursor.index)
+  assertNotEvaluating(cursor.source.slice(cursor.index, close === -1 ? undefined : close + 1))
+  return false
+}
+
+/** Inside double quotes only substitutions still open a command. */
+const QUOTED_HANDLERS: Handler[] = [evaluatingExpansion, backtick, commandSubstitution]
+
+/** In an expanding here-document body an escape keeps the next character text; substitutions run. */
+const BODY_HANDLERS: Handler[] = [escapedChar, evaluatingExpansion, backtick, arithmetic, commandSubstitution]
 
 const doubleQuoted: Handler = (cursor, state) => {
   if (peek(cursor) !== '"') return false
@@ -284,8 +428,10 @@ const localeQuoted: Handler = (cursor, state) => {
 const parameterExpansion: Handler = (cursor, state) => {
   if (peek(cursor) !== '$') return false
   if (peek(cursor, 1) === '{') {
+    const start = cursor.index
     cursor.index++
     skipBalanced(cursor, '{', '}')
+    assertNotEvaluating(cursor.source.slice(start, cursor.index))
   } else cursor.index++
   appendShaped(state, EXPANSION)
   return true
@@ -317,7 +463,8 @@ const hereDocument: Handler = (cursor, state) => {
   return true
 }
 
-const isFileDescriptor = (word: Word | undefined): boolean => word !== undefined && word.literal && /^\d+$/.test(word.value)
+const isFileDescriptor = (word: Word | undefined): boolean =>
+  word !== undefined && word.literal && /^\d+$/.test(word.value)
 
 const redirection: Handler = (cursor, state) => {
   const char = peek(cursor)
@@ -402,6 +549,6 @@ const parseList = (cursor: Cursor, terminator: Terminator): SimpleCommand[] => {
  * Splits a shell script into its simple commands, the way a permission rule sees them: at `&&`,
  * `||`, `;`, `|`, `&` and newlines, and into subshells, command substitutions and process
  * substitutions. Here-document bodies, comments and redirection targets are not commands and are
- * dropped. Throws `ShellParseError` on an unterminated quote or substitution.
+ * dropped, except the substitutions in the body of a here-document with an unquoted delimiter, which run. Throws `ShellParseError` on an unterminated quote or substitution.
  */
 export const parseShell = (script: string): SimpleCommand[] => parseList({ source: script, index: 0 }, undefined)

package/kit/hooks/hooks.json

@@ -39,7 +39,7 @@
     "matcher": "Bash",
     "handler": {
       "type": "command",
-      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/index.ts '{{kit.guard.selfMergeLabel}}' || exit 2",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/index.ts '{{kit.guard.selfMergeLabel}}' '{{kit.guard.planApproval.approve}}' || exit 2",
       "timeout": 10,
       "onFailure": "block"
     }
@@ -61,12 +61,21 @@
       "timeout": 10
     }
   },
+  "plan-approval": {
+    "event": "PostToolUse",
+    "matcher": "AskUserQuestion",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/merge-guard/plan-approval-record.ts '{{kit.guard.planApproval.approve}}' '{{kit.guard.planApproval.revoke}}'",
+      "timeout": 10
+    }
+  },
   "watch-guard": {
     "event": "PreToolUse",
     "matcher": "Bash",
     "handler": {
       "type": "command",
-      "command": "input=$(cat); case \"$input\" in *watch*) printf '%s' \"$input\" | bun \"$CLAUDE_PROJECT_DIR/.claude/hooks/watch-guard/index.ts\";; esac",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && { input=$(cat); case \"$input\" in *watch*) printf '%s' \"$input\" | bun .claude/hooks/watch-guard/index.ts;; esac; }",
       "timeout": 10
     }
   }

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.