jackherd 0.0.1 → 1.0.0

package/kit/hooks/hooks/watch-guard/starts.ts

@@ -0,0 +1,154 @@
+import { basename } from 'node:path'
+import { parseShell } from '../git-guard/shell'
+import { hasBackgroundJob } from './background'
+import { SHELLS, shellHeredocBodies, shellHereStrings, withoutHeredocBodies } from './shell-input'
+
+/**
+ * One start of the watcher in a call: whether it streams, and whether the call (or the script around the
+ * start) sends any command off with `&`, which ends a background call before the watcher reports.
+ */
+export type WatcherStart = { stream: boolean; callHasBackgroundJob: boolean }
+
+/** Thrown past `MAX_DEPTH` nested scripts; the caller answers it like an unreadable call. */
+export class NestingTooDeep extends Error {}
+
+const WATCH = 'watch'
+/** `watch source <name> --dry-run` runs one source once and ends; it starts no watcher. */
+const SOURCE = 'source'
+const STREAM = '--stream'
+/** The program names of the CLI: `jh`, and `agent-kit` until 2.0.0 (an old install and the shell around it still say it). */
+const BINS = new Set(['jh', 'agent-kit'])
+const MAX_DEPTH = 8
+
+/** Words that may stand before the program of a simple command without being it. */
+const KEYWORDS = new Set(['!', '{', 'if', 'then', 'elif', 'else', 'while', 'until', 'do', 'function', 'coproc'])
+const WRAPPERS = new Set([
+  'exec',
+  'nohup',
+  'env',
+  'time',
+  'setsid',
+  'command',
+  'nice',
+  'stdbuf',
+  'sudo',
+  'timeout',
+  'busybox',
+])
+/** Programs besides the shells that run their `-c` argument: `su -c`, `script -c`, `flock <file> -c`. */
+const COMMAND_RUNNERS = new Set([...SHELLS, 'su', 'runuser', 'script', 'flock'])
+const PACKAGE_RUNNERS = new Set(['bunx', 'npx', 'pnpx'])
+/** Package managers that run a package after `dlx` or `exec`; `yarn` also runs one directly. */
+const PACKAGE_MANAGERS = new Set(['pnpm', 'yarn', 'npm'])
+const PACKAGE_SUBCOMMANDS = new Set(['dlx', 'exec'])
+
+const ASSIGNMENT = /^\w+=/
+const DURATION = /^\d+(?:\.\d+)?[smhd]?$/
+const PACKAGE = /^(?:(?:@crossdelta\/)?agent-kit|jackherd|jh)(?:@\S+)?$/
+const SCRIPT = /(?:^|\/)(?:cli\.ts|agent-kit|jh)$/
+const COMMAND_FLAG = /^-[a-zA-Z]*c[a-zA-Z]*$/
+
+const isOption = (word: string | undefined): boolean => word?.startsWith('-') === true
+
+/**
+ * A word before the program: a keyword, a wrapper (`nohup`, `timeout`, …), an assignment, an option, a
+ * duration, the word after an option, which may be its value (`timeout -s INT`, `nice -n 10`), or the
+ * name after `function`.
+ */
+const isPrefixWord = (words: readonly string[], index: number): boolean => {
+  const word = words[index] ?? ''
+  const previous = words[index - 1]
+  return (
+    KEYWORDS.has(word) ||
+    WRAPPERS.has(basename(word)) ||
+    ASSIGNMENT.test(word) ||
+    isOption(word) ||
+    DURATION.test(word) ||
+    isOption(previous) ||
+    previous === 'function'
+  )
+}
+
+const afterOptions = (words: readonly string[], from: number): number => {
+  let index = from
+  while (isOption(words[index])) index++
+  return index
+}
+
+const subcommandAt = (words: readonly string[], index: number): number =>
+  words[index] === WATCH && words[index + 1] !== SOURCE ? index : -1
+
+/** `<package> watch`, also `<package> <bin> watch` as `npx -p <package> <bin>` spells it. */
+const packageAt = (words: readonly string[], index: number): number => {
+  if (!PACKAGE.test(words[index] ?? '')) return -1
+  return subcommandAt(words, BINS.has(words[index + 1] ?? '') ? index + 2 : index + 1)
+}
+
+/** `bun x <package> watch`, or `bun [flags] [run] <…/cli.ts | …/jh | …/agent-kit> watch` with the script anywhere after `bun`. */
+const bunWatchIndex = (words: readonly string[], from: number): number => {
+  const first = afterOptions(words, from)
+  if (words[first] === 'x') return packageAt(words, afterOptions(words, first + 1))
+  for (let index = from; index < words.length; index++) {
+    if (SCRIPT.test(words[index] ?? '') && words[index + 1] === WATCH) return subcommandAt(words, index + 1)
+  }
+  return -1
+}
+
+const packageManagerWatchIndex = (words: readonly string[], from: number): number =>
+  PACKAGE_SUBCOMMANDS.has(words[from] ?? '') ? packageAt(words, afterOptions(words, from + 1)) : packageAt(words, from)
+
+/** The index of `watch` when the program at `index` runs the watcher, else -1. */
+const watchIndexOf = (words: readonly string[], index: number): number => {
+  const program = basename(words[index] ?? '')
+  if (BINS.has(program)) return subcommandAt(words, index + 1)
+  if (PACKAGE_RUNNERS.has(program)) return packageAt(words, afterOptions(words, index + 1))
+  if (PACKAGE_MANAGERS.has(program)) return packageManagerWatchIndex(words, index + 1)
+  if (program === 'bun') return bunWatchIndex(words, index + 1)
+  return -1
+}
+
+/** The script a program at `index` runs as a command line: `bash -c '<script>'`, `su -c …`, `eval <words>`, else null. */
+const nestedScriptOf = (words: readonly string[], index: number): string | null => {
+  const program = basename(words[index] ?? '')
+  if (program === 'eval') return words.slice(index + 1).join(' ')
+  if (!COMMAND_RUNNERS.has(program)) return null
+  const flag = words.findIndex((word, position) => position > index && COMMAND_FLAG.test(word))
+  return flag === -1 ? null : (words[afterOptions(words, flag + 1)] ?? null)
+}
+
+/**
+ * The starts in one simple command. The program is tried at every position the words before it allow
+ * (wrappers, assignments, options and their values), so `env -i bun …` finds `bun` behind the option.
+ */
+const startsOfCommand = (words: readonly string[], callHasBackgroundJob: boolean, depth: number): WatcherStart[] => {
+  for (let index = 0; index < words.length; index++) {
+    const watch = watchIndexOf(words, index)
+    if (watch !== -1) return [{ stream: words.slice(watch + 1).includes(STREAM), callHasBackgroundJob }]
+    const nested = nestedScriptOf(words, index)
+    if (nested !== null) return startsIn(nested, callHasBackgroundJob, depth + 1)
+    if (!isPrefixWord(words, index)) return []
+  }
+  return []
+}
+
+/**
+ * Every start of the watcher a shell would run from `script`, at any nesting the script spells out: its
+ * simple commands (substitutions included, which `parseShell` lists), `bash -c` and `eval` arguments, and
+ * here-documents or here-strings fed to a shell. Throws `ShellParseError` or `NestingTooDeep`.
+ */
+export const startsIn = (script: string, callHasBackgroundJob: boolean, depth = 0): WatcherStart[] => {
+  if (depth > MAX_DEPTH) throw new NestingTooDeep(`more than ${MAX_DEPTH} nested scripts`)
+  const backgroundJob = callHasBackgroundJob || hasBackgroundJob(withoutHeredocBodies(script))
+  return [
+    ...parseShell(script).flatMap((command) =>
+      startsOfCommand(
+        command.map((word) => word.value),
+        backgroundJob,
+        depth,
+      ),
+    ),
+    ...[...shellHeredocBodies(script), ...shellHereStrings(script)].flatMap((body) =>
+      startsIn(body, backgroundJob, depth + 1),
+    ),
+  ]
+}

package/kit/hooks/hooks/watch-guard/text-fallback.ts

@@ -0,0 +1,40 @@
+import { hasBackgroundJob } from './background'
+import { withoutHeredocBodies } from './shell-input'
+import type { WatcherStart } from './starts'
+
+/**
+ * A path in front of a program is at most 256 characters (`\S{0,256}` below): an unbounded `\S*` rescans a long
+ * run of characters without a space from every position, which is quadratic and can outlast the hook's timeout.
+ */
+const COMMAND_POSITION = /(?:^|[;&|({`'"!\n]|\b(?:then|do|else|elif|if|while|until)\b)\s*/.source
+const ENV_ASSIGNMENT = /\w+=\S*\s+/.source
+const WRAPPER = /(?:exec|nohup|env|time|setsid|command|nice|stdbuf|sudo)\s+(?:-\S+\s+(?:[\w.=:+]+\s+)?)*/.source
+const TIMEOUT = /timeout\s+(?:-\S+\s+(?:[\w.=:+]+\s+)?)*\d\S*\s+/.source
+const PACKAGE_RUNNER =
+  /(?:\S{0,256}\/)?(?:bunx|npx|pnpx|bun\s+x|pnpm\s+dlx|yarn\s+dlx)\s+(?:-\S+\s+)*['"]?(?:(?:@crossdelta\/)?agent-kit|jackherd|jh)(?:@[^\s'"]+)?['"]?/
+    .source
+const BUN_SCRIPT = /(?:\S{0,256}\/)?bun\s+[^;&|\n]*?\S*(?:\/|\b)(?:cli\.ts|agent-kit|jh)['"]?/.source
+const BIN_PATH = /(?:\S{0,256}\/)?(?:agent-kit|jh)/.source
+/** `watch source …` runs one source once and starts no watcher. */
+const WATCH_WORD = /\s+watch(?=\s|$|[;&|)`'"])(?!\s+source(?=\s|$))/.source
+
+/** Any start-shaped text, at a command position or right after a quote, so a quoted start counts too. */
+const TEXT_START = new RegExp(
+  `${COMMAND_POSITION}(?:${ENV_ASSIGNMENT}|${WRAPPER}|${TIMEOUT})*(?:${PACKAGE_RUNNER}|${BUN_SCRIPT}|${BIN_PATH})${WATCH_WORD}`,
+  'g',
+)
+const ARGUMENTS_TO_COMMAND_END = /^[^;&|\n)`'"]*/
+const STREAM_FLAG = /(?:^|\s)--stream(?=\s|$)/
+
+/**
+ * The starts in a call the parser cannot read (an unterminated quote, a substitution inside an expanding
+ * here-document, nesting past the limit): a match of the start's text anywhere, so a doubtful call is
+ * refused rather than passed.
+ */
+export const startsInText = (script: string): WatcherStart[] => {
+  const callHasBackgroundJob = hasBackgroundJob(withoutHeredocBodies(script))
+  return [...script.matchAll(TEXT_START)].map((match) => {
+    const rest = script.slice((match.index ?? 0) + match[0].length)
+    return { stream: STREAM_FLAG.test(rest.match(ARGUMENTS_TO_COMMAND_END)?.[0] ?? ''), callHasBackgroundJob }
+  })
+}

package/kit/hooks/hooks.json

@@ -0,0 +1,30 @@
+{
+  "format-on-edit": {
+    "event": "PostToolUse",
+    "matcher": "Edit|Write",
+    "handler": {
+      "type": "command",
+      "command": "file=$(jq -r '.tool_input.file_path // empty'); [ -n \"$file\" ] || exit 0; file=$(realpath -- \"$file\" 2>/dev/null) || exit 0; project=$(realpath -- \"$CLAUDE_PROJECT_DIR\" 2>/dev/null) || exit 0; case \"$file\" in \"$project\"/*) ;; *) exit 0;; esac; biome=\"$project/node_modules/.bin/biome\"; [ -x \"$biome\" ] || exit 0; case \"$file\" in *.ts|*.tsx|*.js|*.jsx|*.json|*.jsonc) \"$biome\" format --write -- \"$file\" 2>/dev/null || true;; esac; exit 0",
+      "timeout": 10
+    }
+  },
+  "git-guard": {
+    "event": "PreToolUse",
+    "matcher": "Bash",
+    "handler": {
+      "type": "command",
+      "command": "cd \"$CLAUDE_PROJECT_DIR\" && bun .claude/hooks/git-guard/index.ts",
+      "timeout": 10,
+      "onFailure": "block"
+    }
+  },
+  "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",
+      "timeout": 10
+    }
+  }
+}

package/kit/hooks/statusline.sh

@@ -0,0 +1,72 @@
+#!/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 %.
+input=$(cat)
+
+model=$(jq -r '.model.display_name // .model.id // "?"' <<<"$input")
+pct=$(jq -r '.context_window.used_percentage // 0' <<<"$input")
+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
+
+case '{{kit.responseLanguage}}' in
+  German) label='Kontext'; compact_hint='/compact oder /clear' ;;
+  *) label='Context'; compact_hint='/compact or /clear' ;;
+esac
+
+# The nearest .jackherd/config.json above the working directory, never the one in the home directory
+# (that is the global config), else the global ~/.jackherd/config.json. Until 2.0.0 the old
+# .claude/agent-kit.json is read where the new file is missing.
+config_in() {
+  if [ -f "$1/.jackherd/config.json" ]; then
+    printf '%s' "$1/.jackherd/config.json"
+  elif [ -f "$1/.claude/agent-kit.json" ]; then
+    printf '%s' "$1/.claude/agent-kit.json"
+  else
+    return 1
+  fi
+}
+
+config_file() {
+  local dir=$1
+  while [ -n "$dir" ] && [ "$dir" != "/" ]; do
+    if [ "$dir" != "$HOME" ] && config_in "$dir"; then
+      return
+    fi
+    dir=$(dirname "$dir")
+  done
+  config_in "$HOME"
+}
+
+warn_pct=60
+alert_pct=85
+config=$(config_file "${cwd:-$PWD}")
+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
+fi
+
+reset='\033[0m'
+if [ "$pct_int" -ge "$alert_pct" ]; then
+  color='\033[31m'
+  hint=" ⚠ ${compact_hint}"
+elif [ "$pct_int" -ge "$warn_pct" ]; then
+  color='\033[33m'
+  hint=''
+else
+  color='\033[32m'
+  hint=''
+fi
+
+LC_NUMERIC=C printf "%s | ${color}%s %s%%${reset} | \$%.2f%s" "$model" "$label" "$pct_int" "$cost" "$hint"

package/kit/review/agents/devops.md

@@ -0,0 +1,11 @@
+---
+name: devops
+description: 'Infrastructure Review — Security, Resources, Reliability. Use for infrastructure-as-code changes.'
+model: {{kit.model.review}}
+tools: Read, Grep, Glob
+user-invocable: false
+---
+
+Read [`.claude/skills/devops/SKILL.md`](../skills/devops/SKILL.md) and follow it, including its first step: the project supplement in `.claude/project/devops.md` if it exists. The skill carries the checks and the output format and is the single source of truth for both — this file only fixes the model and the tool grant for a dispatched run.
+
+You receive a `git diff` or a list of changed files in your prompt. Your output is the report; applying a fix is the caller's decision.

package/kit/review/agents/public-content.md

@@ -0,0 +1,39 @@
+---
+name: public-content
+description: 'Public Content Review: does a change to files a package publishes give away a specific project, client, team or person? Use when /pre-commit routes a change to published files (check.publicContent).'
+model: {{kit.model.review}}
+tools: Read
+user-invocable: false
+---
+
+If `.claude/project/public-content.md` exists, read it first. It extends this agent for this project and wins where the two disagree.
+
+You receive the `git diff` of files a package publishes: what strangers will read once it is released. Judge the diff **as one of those strangers**: open no other file of the repository (the supplement above is the only exception). What you would need the repository to understand is exactly what the published text must not lean on.
+
+`jh check` has already scanned the added lines for the names of neighbouring repositories, their organisations and ticket keys, and the names of this project; it reports where, never the name. You judge what no list of names catches.
+
+## What is a finding
+
+An added line is a finding when a reader could tell from it, without the repository:
+
+- **A project or product:** its name, a feature set or screen only it has, its domain or hosts, its table, event or service names.
+- **A client, employer, team or person:** names, handles, initials in an example, an e-mail address, a role that points at one person.
+- **An incident:** a date, a PR or ticket number, a version, "last week", a number of orders or users that ties a lesson to one event.
+- **Internal infrastructure:** hosts, environment names that are not placeholders, account, project or tenant identifiers, machine paths.
+- **An example copied from a real codebase:** a file path, a query, a log line or an error message that is plainly someone's code, not an illustration.
+
+Not a finding: generic illustrations (`apps/web`, `orders`, `search-index`, `example.com`), placeholders (`<owner>`, `<port>`), and the tools a published package names openly (its runtime, its package manager, the editor or agent it extends).
+
+A lesson stays; its origin goes. Rewrite "the export broke on 3 March in the shop" as the rule it taught, with an invented example.
+
+## Output
+
+```markdown
+## Public Content — PASS | FIX FIRST
+
+| File:line | Gives away | Line | Rewrite |
+|---|---|---|---|
+| kit/rules/x.md:14 | a client (name) | "…" | "…" |
+```
+
+`PASS` when no added line gives anything away; one row per finding otherwise. Quote the line so the author can find it, and offer a neutral rewrite. Your output is the report; applying a rewrite is the caller's decision.

package/kit/review/agents/security-audit.md

@@ -0,0 +1,11 @@
+---
+name: security-audit
+description: 'Use when a change touches auth, tenant isolation, access policies, API keys, secrets, user input, database queries, message payloads or infrastructure: OWASP Top 10, secrets exposure, authz, input validation, injection, path traversal.'
+model: {{kit.model.review}}
+tools: Read, Grep, Glob
+user-invocable: false
+---
+
+Read [`.claude/skills/security-audit/SKILL.md`](../skills/security-audit/SKILL.md) and follow it, including its first step: the project supplement in `.claude/project/security-audit.md` if it exists. The skill carries the checks and the output format and is the single source of truth for both — this file only fixes the model and the tool grant for a dispatched run.
+
+You receive a `git diff` or a list of changed files in your prompt. Your output is the report; applying a fix is the caller's decision.

package/kit/review/agents/uncle-bob.md

@@ -0,0 +1,11 @@
+---
+name: uncle-bob
+description: 'Clean Architecture Review — SOLID, Dependency Direction, Small Functions. Use for backend and service code review.'
+model: {{kit.model.review}}
+tools: Read, Grep, Glob
+user-invocable: false
+---
+
+Read [`.claude/skills/uncle-bob/SKILL.md`](../skills/uncle-bob/SKILL.md) and follow it, including its first step: the project supplement in `.claude/project/uncle-bob.md` if it exists. The skill carries the checks and the output format and is the single source of truth for both — this file only fixes the model and the tool grant for a dispatched run.
+
+You receive a `git diff` or a list of changed files in your prompt. Your output is the report; applying a fix is the caller's decision.

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

@@ -0,0 +1,50 @@
+---
+name: devops
+description: 'Infrastructure Review — Security, Resources, Reliability. Use for infrastructure-as-code changes.'
+---
+
+If `.claude/project/devops.md` exists, read it first. It adds this project's infrastructure conventions (sizing rules, stream migrations, stack names) and wins where the two disagree.
+
+You are a **DevOps Engineer** — pragmatic, security-conscious, thinking in failure modes.
+
+## Your Task
+
+Review the infrastructure changes through these lenses:
+
+### Security
+
+1. **Secrets**: Credentials stay out of code, config and terminal output; they come from the secret store or encrypted stack config.
+2. **Network Policies**: The service is reachable only on the ports it needs.
+3. **RBAC**: Minimal rights. Service accounts get only the permissions they need.
+4. **Image Tags**: Pinned versions or SHA digests, never `latest`.
+
+### Resources
+
+5. **Requests vs Limits**: Sensible for the workload — not too generous (waste), not too tight (OOM).
+6. **Runtime Heap**: A Node.js heap limit (`--max-old-space-size`) fits inside the container memory limit with headroom (about 75 %).
+7. **Replicas**: At least 2 for production. Rolling update strategy configured.
+
+### Reliability
+
+8. **Idempotency**: Can the deployment (`pulumi up` or equivalent) run repeatedly without side effects?
+9. **Rollback Plan**: What happens if the deployment fails? Is there a rollback strategy?
+10. **Health Checks**: Readiness and liveness probes configured and sensible.
+11. **Message Streams**: A change to stream subjects or retention ships with its migration.
+
+### Infrastructure as Code
+
+12. **Stack Isolation**: Staging and production configs properly separated.
+13. **No hardcoded values**: Everything via stack config or config objects.
+14. **Dependencies**: Resource dependencies explicit where needed (`dependsOn`).
+
+## Your Output Format
+
+In {{kit.responseLanguage}}. For each finding:
+
+- **Category** (Security / Resources / Reliability / Infrastructure as Code)
+- **Severity** (CRITICAL / WARNING / INFO)
+- **File + line**
+- **Problem** (one sentence)
+- **Fix** (concrete proposal)
+
+At the end: DEPLOY / DEPLOY WITH FIXES / BLOCK with rationale.

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

@@ -0,0 +1,140 @@
+---
+name: diagnose
+description: 'Diagnosis loop for hard bugs, flaky failures and performance regressions. Use when the user says "debug"/"diagnose", reports something broken, throwing, hanging or slow, or when a bug does not reproduce reliably.'
+---
+
+<!--
+  Adapted from https://github.com/mattpocock/skills (skills/engineering/diagnosing-bugs),
+  commit 8b78b53, MIT License, Copyright (c) 2026 Matt Pocock. See NOTICE in jackherd.
+  Phase structure and the feedback-loop discipline are his; the loop recipes, redaction rules
+  and hand-off targets are the kit's.
+-->
+
+If `.claude/project/diagnose.md` exists, read it first. It adds this project's loop recipes (its database, its client state, its hardware) and wins where the two disagree.
+
+You are the **Diagnostician**. A discipline for hard bugs. Skip a phase only with an explicit reason.
+
+Read the relevant plan in `{{kit.planDirectory}}/` and any `ARCHITECTURE.md` of the touched unit before you form a picture of the system. Recalled memory and past incidents are leads, never evidence — a bug that looks like a known one still has to go red in a loop of its own.
+
+## Redaction
+
+This skill has you show commands, outputs and captured artifacts. **Redact every secret before you show it** — write `<REDACTED>` in its place.
+
+Build loops against environment variables so the credential stays in the environment: load the env file in the shell and reference `$VAR`; a secret is never a literal command argument. Captured artifacts carry auth headers and tokens — quote only the lines that carry the signal. Database rows carry customer data: quote the columns you are reasoning about, not the row.
+
+If the redacted output is not enough to diagnose the bug, say so and ask the user.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. With a **tight** pass/fail signal that goes red on _this_ bug, you will find the cause; bisection, hypothesis-testing and instrumentation all just consume it. Without one, no amount of reading code will save you.
+
+Spend disproportionate effort here. Be aggressive, be creative, refuse to give up.
+
+**The loop recipes live in [`references/feedback-loops.md`](references/feedback-loops.md)** — Bun tests, a real browser via Playwright, HTTP via curl, message subjects, differential runs. Read it before you build a loop; it also carries the two Bun invocation traps that make a healthy suite look broken.
+
+### Tighten the loop
+
+Treat the loop as a product. Once you have _a_ loop, **tighten** it:
+
+- Faster — cache setup, skip unrelated init, narrow the test scope to one module directory.
+- Sharper — assert the specific symptom, not "did not crash".
+- More deterministic — pin time, seed randomness, isolate storage, freeze the network.
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic one is a superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow the timing window, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it is.
+
+### When you genuinely cannot build a loop
+
+Stop and say so. List what you tried, then ask the user for one of: access to the environment that reproduces it, a redacted artifact (HAR, log dump, screen recording with timestamps), or permission to add temporary instrumentation to a deployed environment. Hypotheses wait until a loop exists.
+
+### Completion criterion — a loop that goes red
+
+Phase 1 is done when you can name **one command** — a test invocation, a script path, a curl — that you have **already run at least once** (show the invocation and its output, redacted), and that is:
+
+- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it goes red on this bug and green once fixed. Not "runs without erroring".
+- [ ] **Deterministic** — same verdict every run. For flaky bugs: a pinned, high reproduction rate.
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended. A human enters the loop only through `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop**. Jumping to a hypothesis is the exact failure this skill prevents. No red command, no Phase 2.
+
+## Phase 2 — Reproduce and minimise
+
+Run the loop. Watch it go red.
+
+Confirm:
+
+- [ ] The loop produces the failure the **user** described, not a different one that happens to live nearby. Wrong bug, wrong fix.
+- [ ] It reproduces across runs, or at a rate high enough to debug against.
+- [ ] You captured the exact symptom — error message, wrong value, measured timing — so later phases can verify the fix addresses it.
+
+Then shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data and steps **one at a time**, re-running after each cut. A minimal repro shrinks the hypothesis space in Phase 3 and becomes the regression test in Phase 5.
+
+Done when every remaining element is load-bearing: removing any one of them turns the loop green.
+
+## Phase 3 — Hypothesise
+
+Generate **3 to 5 ranked hypotheses before testing any of them**. Single-hypothesis generation anchors on the first plausible idea.
+
+Each one is **falsifiable** — state the prediction it makes:
+
+> "If X is the cause, then changing Y makes the bug disappear / changing Z makes it worse."
+
+A hypothesis with no stated prediction is a vibe. Sharpen it or drop it.
+
+**Show the ranked list to the user before testing.** They re-rank it instantly when they know something you cannot see ("we deployed exactly that yesterday", "we already ruled out the second one"). Cheap checkpoint, large saving. Proceed with your ranking if the user is away.
+
+## Phase 4 — Instrument
+
+Every probe maps to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Order of preference:
+
+1. Inspect state directly where the environment allows it — a breakpoint or a REPL beats ten logs.
+2. Targeted logs at the boundary that distinguishes two hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, `[DEBUG-a4f2]`. Cleanup becomes a single grep. Untagged logs survive the fix; tagged ones die with it.
+
+**Performance branch.** For a regression in speed, logs are usually the wrong tool. Establish a baseline measurement first — a timing harness, `performance.now()`, a profiler run, the query plan — then bisect against it. Measure first, fix second.
+
+## Phase 5 — Fix and regression test
+
+Write the regression test **before the fix** — but only where a **correct seam** exists.
+
+A correct seam exercises the **real bug pattern as it occurs at the call site**. If the only reachable seam is too shallow — a unit test where the bug needs two collaborating callers, a mocked adapter where the bug lives in the real I/O — a test there buys false confidence.
+
+**If no correct seam exists, that is itself the finding.** Note it: the architecture is preventing the bug from being locked down. Carry it into Phase 6.
+
+Where a seam exists, follow the decision tree in `.claude/rules/kit/testing.md` (a bug fix always earns a regression test) and:
+
+1. Turn the minimised repro into a failing `*.test.ts` next to the source.
+2. Watch it fail.
+3. Apply the fix — the smallest change that turns it green, no opportunistic refactoring.
+4. Watch it pass.
+5. Re-run the Phase 1 loop against the **original**, un-minimised scenario.
+
+For a fix inside a shared package, run the tests of the packages that consume it too. Shared code has blast radius.
+
+## Phase 6 — Cleanup and post-mortem
+
+Required before you declare it done:
+
+- [ ] The original repro no longer reproduces — re-run the Phase 1 loop, show the output
+- [ ] The regression test passes, or the absence of a seam is written down
+- [ ] All `[DEBUG-...]` instrumentation removed — grep the prefix to prove it
+- [ ] Throwaway harnesses and fixtures deleted
+- [ ] The hypothesis that turned out correct is stated in the commit body, in prose, so the next person to hit this learns the cause and not just the diff
+
+**Then ask: what would have prevented this bug?**
+
+- A design problem — no test seam, tangled callers, hidden coupling → hand the specifics to `/uncle-bob`.
+- A rule that should hold project-wide → propose a line for the matching file in `.claude/rules/`.
+- More than a single change can carry → propose a plan in `{{kit.planDirectory}}/` rather than widening this fix.
+
+Make the recommendation **after** the fix is in. You know more now than when you started.
+
+Report in {{kit.responseLanguage}}.

package/kit/review/skills/diagnose/references/feedback-loops.md

@@ -0,0 +1,59 @@
+# Feedback Loops
+
+Recipes for Phase 1 of `/diagnose`. Pick the one that reaches the bug's code path, then tighten it. The project supplement in `.claude/project/diagnose.md` adds the recipes only this project has.
+
+Ordered by how tight the loop tends to be. Reach for the first one that can actually go red on the bug — a Bun test that cannot see the bug is worse than a slower loop that can.
+
+## 1. Bun test — the default
+
+The tightest loop available. Milliseconds, deterministic, unattended.
+
+```bash
+cd packages/<package> && bun test src/<module>/<file>.test.ts
+```
+
+Two invocation traps make a healthy suite look broken:
+
+- **`EMFILE` / `ProcessFdQuotaExceeded` while dev servers run.** From the workspace root Bun walks the whole monorepo and can exhaust the kernel's descriptor table while watchers hold it. It reports `0 pass / 1 error`, not an assertion failure. Fix: `cd` into the package or module directory first; leave the user's dev servers running.
+- **Run from the package root, not below it.** Bun reads `tsconfig.json` — and with it `jsxImportSource` — from the **working directory**. One level too deep and every `.tsx` a test touches compiles against React's runtime: `Cannot find module 'react/jsx-dev-runtime'`. It reads like a missing dependency in untouched code. Re-run from the package root before concluding anything.
+
+Both failures are environmental. Neither is evidence about the bug.
+
+## 2. The rendered app — Playwright
+
+For anything that needs the real page: client state, offline behaviour, gestures, timing between requests.
+
+- **Fresh auth state.** A stored login that has expired produces a silent redirect to the login page, which presents as a data bug.
+- **One login per run.** Specs inherit a stored state; parallel live logins race each other and hit auth rate limits.
+- **Wait for content, not for load.** Data that arrives after boot needs a poll for real content with a generous timeout; an assertion on emptiness right after navigation proves nothing.
+
+For exploring a live page, a browser the user is already logged into is faster. Move to a spec file once the loop has to be repeatable or needs isolation or network control.
+
+## 3. HTTP against a running service — curl
+
+```bash
+curl -sS -H "Authorization: Bearer $SERVICE_TOKEN" http://localhost:<port>/<route> | jq .
+```
+
+Load the token from the environment; never inline it as a literal. Redact bearer headers out of anything you show.
+
+## 4. Events that never arrive — NATS subjects
+
+When a handler does not fire, check whether the event landed in a different stream before you read the handler's code. The NATS monitoring endpoint answers this in one call:
+
+```bash
+curl -sS http://localhost:8222/jsz | jq '.account_details[].stream_detail[] | {name, subjects: .config.subjects, messages: .state.messages}'
+curl -sS http://localhost:8222/healthz
+```
+
+A subject that sits in the wrong stream is a configuration fault, not a code fault, and restarting the container does not fix it.
+
+## 5. Differential loop — two environments, before versus after
+
+When the same input behaves differently in two places, run both and diff the outputs. This is the fastest route for "works on staging, wrong in production" and for regressions that appeared between two deploys.
+
+For a regression between two known commits, automate the check and let `git bisect run` consume it.
+
+## 6. A human in the loop
+
+When a trigger genuinely needs a person — a device, a physical button, a native build — drive them with `scripts/hitl-loop.template.sh` so the run stays structured and its output feeds back. Script the reachability probes first, and note which state you asked them to observe **before** they change it — a restart that clears the symptom also destroys the evidence.