jackherd 1.6.0 → 1.7.0

package/kit/hooks/hooks/shared/model-family.ts

@@ -0,0 +1,48 @@
+/** The model families a subagent can be started on, by the word their aliases and full ids carry. */
+export const MODEL_FAMILY = { haiku: 'haiku', sonnet: 'sonnet', opus: 'opus', fable: 'fable' } as const
+
+export type ModelFamily = (typeof MODEL_FAMILY)[keyof typeof MODEL_FAMILY]
+
+/** The families from the weakest to the strongest. */
+const MODEL_RANK: readonly ModelFamily[] = [MODEL_FAMILY.haiku, MODEL_FAMILY.sonnet, MODEL_FAMILY.opus, MODEL_FAMILY.fable]
+
+export const MODEL_COMPARISON = { fits: 'fits', weaker: 'weaker', stronger: 'stronger', unknown: 'unknown' } as const
+
+/**
+ * How a model compares with a plan's recommendation, which may name a range (`Fable 5 / Opus 4.8`). `recommended` is
+ * the family to start on instead: the strongest of the range for a stronger model, else the weakest.
+ */
+export type ModelComparison =
+  | { kind: typeof MODEL_COMPARISON.fits | typeof MODEL_COMPARISON.weaker | typeof MODEL_COMPARISON.stronger; recommended: ModelFamily }
+  | { kind: typeof MODEL_COMPARISON.unknown }
+
+const TOKEN_SEPARATOR = /[^a-z0-9]+/
+
+const isModelFamily = (token: string): token is ModelFamily => (MODEL_RANK as readonly string[]).includes(token)
+
+const rankOf = (family: ModelFamily): number => MODEL_RANK.indexOf(family)
+
+/** Every family a text names as a whole word, once each, in its order: `claude-opus-5-5`, `Opus 5.5`, `opus`. */
+export const familiesIn = (text: string): ModelFamily[] => [
+  ...new Set(text.toLowerCase().split(TOKEN_SEPARATOR).filter(isModelFamily)),
+]
+
+/** The family of a model alias or id; null for `inherit`, an unknown vendor or an empty value. */
+export const familyOf = (model: string): ModelFamily | null => familiesIn(model)[0] ?? null
+
+const byRank = (first: ModelFamily, second: ModelFamily): number => rankOf(first) - rankOf(second)
+
+/** The families a text names, from the weakest to the strongest. */
+export const rankedFamiliesIn = (text: string): ModelFamily[] => familiesIn(text).sort(byRank)
+
+/** How `model` compares with the families the recommendation names, from its weakest to its strongest. */
+export const compareModels = (recommendation: string, model: string): ModelComparison => {
+  const named = rankedFamiliesIn(recommendation)
+  const family = familyOf(model)
+  const [weakest] = named
+  const strongest = named.at(-1)
+  if (!family || !weakest || !strongest) return { kind: MODEL_COMPARISON.unknown }
+  if (rankOf(family) < rankOf(weakest)) return { kind: MODEL_COMPARISON.weaker, recommended: weakest }
+  if (rankOf(family) > rankOf(strongest)) return { kind: MODEL_COMPARISON.stronger, recommended: strongest }
+  return { kind: MODEL_COMPARISON.fits, recommended: weakest }
+}

package/kit/hooks/hooks/shared/plan-model-table.ts

@@ -0,0 +1,41 @@
+const ROW_PHASE = /^(?:phase\s+)?p?(\d+[a-z]?)\b/i
+const SEPARATOR_ROW = /^[\s|:-]+$/
+/** The header of a plan's model column in the plan languages of the kit's templates. */
+const MODEL_COLUMN_HEADERS = ['model', 'modell']
+const PHASE_COLUMN_HEADER = 'phase'
+
+const cellsOf = (line: string): string[] =>
+  line
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split('|')
+    .map((cell) => cell.trim())
+
+/** The index of the model column when the row is the header of a phase table with one, else -1. */
+const modelColumnOf = (cells: readonly string[]): number =>
+  cells[0]?.toLowerCase() === PHASE_COLUMN_HEADER
+    ? cells.findIndex((cell) => MODEL_COLUMN_HEADERS.includes(cell.toLowerCase()))
+    : -1
+
+const rowPhase = (cell: string): string | null => ROW_PHASE.exec(cell.replaceAll('*', ''))?.[1]?.toLowerCase() ?? null
+
+/**
+ * The model cell of the phase's row in a table whose header starts with `Phase` and has a `Model`/`Modell` column;
+ * null when the plan has no such table or no row for the phase.
+ */
+export const recommendationOf = (plan: string, phase: string): string | null => {
+  let modelColumn = -1
+  for (const line of plan.split('\n')) {
+    if (!line.trim().startsWith('|')) {
+      modelColumn = -1
+      continue
+    }
+    const cells = cellsOf(line)
+    const header = modelColumnOf(cells)
+    if (header !== -1) modelColumn = header
+    else if (modelColumn !== -1 && !SEPARATOR_ROW.test(line) && rowPhase(cells[0] ?? '') === phase)
+      return cells[modelColumn] ?? null
+  }
+  return null
+}

package/kit/hooks/hooks/shared/private-directory.ts

@@ -0,0 +1,29 @@
+import { chmodSync, existsSync, lstatSync, mkdirSync, type Stats, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** The mode of a file in a private directory: readable by its owner only. */
+export const PRIVATE_FILE = 0o600
+const PRIVATE_DIRECTORY = 0o700
+
+/** What sits at the path, a dangling link too, without following a link; null for nothing. */
+const entryAt = (path: string): Stats | null => {
+  try {
+    return lstatSync(path)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A directory only its owner reads, ignored by git: created `0700` when missing; when present it must be a directory
+ * and not a link (else this throws, so nothing is written through it), is narrowed to `0700` and gets the `.gitignore`
+ * it lacks. An existing `.gitignore` is kept.
+ */
+export const ensurePrivateDirectory = (directory: string): void => {
+  const entry = entryAt(directory)
+  if (entry && (entry.isSymbolicLink() || !entry.isDirectory())) throw new Error(`${directory} is no directory`)
+  if (!entry) mkdirSync(directory, { recursive: true, mode: PRIVATE_DIRECTORY })
+  chmodSync(directory, PRIVATE_DIRECTORY)
+  const ignore = join(directory, '.gitignore')
+  if (!existsSync(ignore)) writeFileSync(ignore, '*\n')
+}

package/kit/hooks/hooks/shared/repository-directory.ts

@@ -0,0 +1,14 @@
+import { isAbsolute } from 'node:path'
+
+const segmentsOf = (path: string): string[] => path.split(/[\\/]/).filter((segment) => segment !== '' && segment !== '.')
+
+/**
+ * The same rule as `isRepositoryDirectory` in the package's config schema, which a hook cannot import.
+ * A directory below the repository root: relative, not the root itself and without a `..` segment, so a config cannot
+ * point a hook elsewhere or make the whole repository the directory.
+ */
+export const isRepositoryDirectory = (value: unknown): value is string =>
+  typeof value === 'string' &&
+  !isAbsolute(value) &&
+  segmentsOf(value).length > 0 &&
+  !segmentsOf(value).includes('..')

package/kit/hooks/hooks/shared/subagent-phase.ts

@@ -0,0 +1,99 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { recommendationOf } from './plan-model-table'
+import { isRepositoryDirectory } from './repository-directory'
+
+/** Where a subagent's phase is looked up, from the config of the project and of the home directory. */
+export type SubagentSettings = { planDirectory: string; agentNames: string[] }
+
+/** The phase a prompt names, the plan it found it in (relative to the root, `/`-separated) and the row's model cell. */
+export type PhaseRecommendation = { phase: string; plan: string; cell: string | null }
+
+/** `realPath` resolves every link and answers null for a path that does not exist. */
+export type PlanFiles = { realPath: (path: string) => string | null; readText: (path: string) => string | null }
+
+const IMPLEMENT_AGENT = 'implement'
+const DEFAULT_PLAN_DIRECTORY = 'docs/plans'
+/** A prompt is read up to here: the phase and the plan stand at its start, and a giant prompt costs no time. */
+const PROMPT_LIMIT = 64 * 1024
+/** The config schema's `skillPrefix`: lower-case letters and digits ending in a dash. */
+const SKILL_PREFIX = /^[a-z0-9]+-$/
+/** The convention of a dispatching prompt (`Phase P3`), preferred over the bare form (`phase 3`). */
+const PREFIXED_PHASE = /\bphase\s+p(\d+[a-z]?)\b/gi
+const BARE_PHASE = /\bphase\s+(\d+[a-z]?)\b/gi
+const PATH_SEPARATOR = /[\s`'"()<>[\]{}„“”«»,;]+/
+const SENTENCE_END = /[.:!?]+$/
+const MARKDOWN_FILE = /\.md$/
+
+/** The one phase a pattern names, lower-case; null for none or for several. */
+const singlePhase = (prompt: string, pattern: RegExp): string | null => {
+  const phases = new Set([...prompt.matchAll(pattern)].map(([, phase]) => phase.toLowerCase()))
+  return phases.size === 1 ? [...phases][0] : null
+}
+
+/** The phase a prompt is dispatched for: the one `Phase P<n>` it names, else the one `phase <n>`; null otherwise. */
+export const phaseOfPrompt = (prompt: string): string | null =>
+  singlePhase(prompt, PREFIXED_PHASE) ?? singlePhase(prompt, BARE_PHASE)
+
+/** Every Markdown path a prompt names, in its order; a split on separators, linear in the prompt's length. */
+export const planCandidatesOfPrompt = (prompt: string): string[] =>
+  prompt
+    .split(PATH_SEPARATOR)
+    .map((word) => word.replace(SENTENCE_END, ''))
+    .filter((word) => MARKDOWN_FILE.test(word))
+
+const isInside = (directory: string, path: string): boolean => {
+  const inner = relative(directory, path)
+  return inner !== '' && !inner.startsWith(`..${sep}`) && inner !== '..' && !isAbsolute(inner)
+}
+
+/**
+ * The first candidate that exists and lies in the plan directory below `root`, both compared where their links
+ * resolve, so a link under the plan directory to a file elsewhere never counts; null when none does.
+ */
+export const planFileOf = (
+  root: string,
+  planDirectory: string,
+  candidates: readonly string[],
+  realPath: (path: string) => string | null,
+): string | null => {
+  const directory = realPath(resolve(root, planDirectory))
+  if (directory === null) return null
+  const files = candidates.map((candidate) => realPath(resolve(root, candidate)))
+  return files.find((file): file is string => file !== null && isInside(directory, file)) ?? null
+}
+
+/** `implement` and its name under each usable prefix, once each. */
+export const implementAgentNames = (prefixes: readonly string[]): string[] => [
+  ...new Set([
+    IMPLEMENT_AGENT,
+    ...prefixes.filter((prefix) => SKILL_PREFIX.test(prefix)).map((prefix) => `${prefix}${IMPLEMENT_AGENT}`),
+  ]),
+]
+
+/** The settings from the configs, project first: its plan directory if usable, every prefix. */
+export const subagentSettingsOf = (configs: readonly Record<string, unknown>[]): SubagentSettings => ({
+  planDirectory: configs.map((config) => config.planDirectory).find(isRepositoryDirectory) ?? DEFAULT_PLAN_DIRECTORY,
+  agentNames: implementAgentNames(
+    configs.flatMap((config) => (typeof config.skillPrefix === 'string' ? [config.skillPrefix] : [])),
+  ),
+})
+
+/**
+ * The phase the first 64 KB of a prompt name, with the plan they name in the plan directory and that plan's model cell
+ * for the phase (null without a row). The plan's path is taken from the resolved root. Null without a phase or an
+ * existing plan.
+ */
+export const phaseRecommendation = (
+  root: string,
+  prompt: string,
+  planDirectory: string,
+  files: PlanFiles,
+): PhaseRecommendation | null => {
+  const head = prompt.slice(0, PROMPT_LIMIT)
+  const phase = phaseOfPrompt(head)
+  const file = phase ? planFileOf(root, planDirectory, planCandidatesOfPrompt(head), files.realPath) : null
+  const text = file ? files.readText(file) : null
+  if (!phase || !file || text === null) return null
+  const base = files.realPath(root) ?? root
+  return { phase, plan: relative(base, file).split(sep).join('/'), cell: recommendationOf(text, phase) }
+}

package/kit/hooks/hooks.json

@@ -1,4 +1,12 @@
 {
+  "approval-gate": {
+    "event": "PermissionRequest",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/approval-gate/index.ts '{{kit.approval.allow}}' '{{kit.approval.deny}}' '{{kit.approval.pending}}' '{{kit.approval.denied}}'",
+      "timeout": 600
+    }
+  },
   "ask-hint": {
     "event": "Stop",
     "handler": {
@@ -36,6 +44,23 @@
       "onFailure": "block"
     }
   },
+  "model-gate": {
+    "event": "PreToolUse",
+    "matcher": "Agent|Task",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/model-gate/index.ts",
+      "timeout": 10
+    }
+  },
+  "model-log": {
+    "event": "SubagentStop",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/model-log/index.ts",
+      "timeout": 10
+    }
+  },
   "watch-guard": {
     "event": "PreToolUse",
     "matcher": "Bash",

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

@@ -10,11 +10,12 @@ You add one entry to `watch.sources`, so that `jh watch` reports a new or change
 
 ## 1. Ask
 
-One `AskUserQuestion` round in {{kit.responseLanguage}}, only for what the argument and the conversation leave open, each with the recommended option first:
+`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, and "another command that prints JSON".
+- **Service:** the recipes the README lists (Jira, Linear, GitHub issues, GitHub Projects, Sentry, a status page), 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.
 - **What reports:** a change of what the user reads (title, body, the latest comment; recommended), or a change of named fields such as a status (`reportOn` with those fields, mapped in `map`).
 - **Own changes:** ignore the user's own account on that service (`ignoreAuthors`, needs an author in the map), or report everything.
 
@@ -29,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` and `ignoreAuthors` where chosen. 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 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/implement/SKILL.md

@@ -19,22 +19,22 @@ You are the **Implementer**. Your job is to carry tasks through completely: expl
 1. Read the model recommended for the phase from the table.
 2. Compare it with the model your current run is on:
    - **Same model** → continue with step 1.
-   - **Any other model, stronger or weaker** → delegate the phase to a subagent with the recommended model: `Agent(subagent_type: 'implement', model: <recommended>, prompt: …)`. Hand it what you already know (files located, decisions made, the phase's review gate) so it does not repeat the exploration. It ticks its phase's tasks itself as it finishes them (see Plan Hygiene). You stay the orchestrator: the review gate, gate verification, the arc42 and architecture checks and `/pre-commit` stay with you.
+   - **Any other model, stronger or weaker** → delegate the phase to a subagent with the recommended model: `Agent(subagent_type: 'implement', model: <recommended>, prompt: …)`. Hand it what you already know (files located, decisions made, the phase's review gate) so it does not repeat the exploration. The prompt names the phase as `Phase P<n>` and the plan by its path from the repository root, the one form the kit's hooks read: `model-gate` stops a start on a weaker model than the table's, `model-log` records the model the subagent ran on for the herd. It ticks its phase's tasks itself as it finishes them (see Plan Hygiene). You stay the orchestrator: the review gate, gate verification, the arc42 and architecture checks and `/pre-commit` stay with you.
 3. **The recommendation is a choice, not a floor.** The table records the tier the plan's author judged right for the error cost; a model cannot switch itself, so spawning the subagent is the way to apply it.
 
 ## Step 0b: Parallel Gate (plans with a `{{kit.heading.dependencies}}` table)
 
 When the user asks for more than one phase:
 
-1. **Ready set:** every requested phase whose `{{kit.heading.dependsOn}}` entries are all done — phases ticked off with their review gate, external gates confirmed. Unsure whether an external gate holds → ask.
-2. **Batch:** from the ready set, take phases pairwise without overlap — no shared path under `{{kit.heading.writes}}` (a directory overlaps every file below it), and no two sharing a `{{kit.heading.serialMarker}}`. Overlap → the lower-numbered phase goes now, the other waits.
-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 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.
+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.
 
 ## Plan Hygiene (when implementing from a plan in `{{kit.planDirectory}}/`)
 
-- **Tick off tasks as you go.** As soon as a task is done, set `- [ ]` → `- [x]` in the plan document, right then, so the plan reflects real progress and the plans view shows it while the phase runs.
+- **Tick off tasks as you go.** As soon as a task is done, set `- [ ]` → `- [x]` in the plan document, right then, so the plan reflects real progress and the herd shows it while the phase runs.
 - **A subagent ticks only its own phase,** and only with `Edit` on the exact task line (enough of it to be unique in the file). Never `Write` the plan or rewrite it with a script: parallel subagents share the file, and `Edit` applies its replacement to the file as it is on disk, so ticks in other phases survive, while a whole-file write from an older read erases them. A line that is not unique, and every review-gate item, stays with the caller.
 - **The review gate is binding.** A phase is finished once its review gate has been walked through completely and ticked off; only then comes the next phase or `/pre-commit`. Gate items that name a skill (`/uncle-bob`, `/security-audit`, …) are ticked after the skill has actually run.
 
@@ -42,7 +42,7 @@ When the user asks for more than one phase:
 
 Before you write a single line:
 
-0. A phase not yet in the plan gets its skeleton there first (heading, origin, tasks, review gate), before any research, so the plans view never shows it as missing.
+0. A phase not yet in the plan gets its skeleton there first (heading, origin, tasks, review gate), before any research, so the herd never shows it as missing.
 1. Search with `Grep` / `Glob` / `Read` for existing utilities, components and domain types that cover 80%+ of the need. For deeper research dispatch an `explore` subagent.
 2. Check `package.json` for `gen` / `generate` / `codegen` scripts and run the generator for a generated file instead of editing it.