crewforth 3.3.0 → 3.5.0-rc.1

package/kit/hooks/turn-check.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+# turn-check.sh — UserPromptSubmit + Stop: the files the main thread changed in a turn get the project's own fast
+# check once, before the turn ends.
+#
+# WHY. A crew agent's work is checked when it stops (agent-outcome.sh runs its card's `verify`). The main thread's
+# own edits, which the discipline allows for small changes, had nothing: the turn ended, the user read "done", and
+# a lint error waited for the next commit or the next person. This closes that gap with the command the project
+# already declared for it, and only that one.
+#
+# WHAT RUNS. The `Fast check (files):` line of ./CLAUDE.md (## Verify). `<file>` in it becomes the turn's changed files,
+# each in single quotes; a command with no `<file>` runs as written. No line, the template's placeholder, or `none`:
+# nothing runs, nothing is written, no process starts. The command is judged exactly as agent-outcome.sh judges a
+# verify command before it runs it (_am_verify_ok in guard-agent-model.sh: permission rules, the shell gate, the
+# mode); one it may not run is said to the user once per session and not run.
+#
+# WHICH FILES ARE THE TURN'S. At UserPromptSubmit a snapshot goes into the git directory (never committed): HEAD, the
+# time, and the content id of every file that was already dirty. At Stop the turn's set is
+#   * a dirty file whose content differs from the snapshot (one dirty before the turn and untouched is not the
+#     turn's, it is earlier work);
+#   * the files of commits the turn made (commit, amend, cherry-pick, revert), as `git diff <snapshot HEAD> HEAD`;
+#     an amend therefore counts only what it changed. When the turn moved HEAD any other way (pull, merge, reset,
+#     checkout, rebase), the commits are not counted at all: someone else's code is not this turn's to check.
+# Deleted files are left out. An empty set is silence.
+#
+# RED. Exit 2 with the end of the check's output, which Claude Code hands back to the model so the turn goes on to
+# fix it. Once per turn: Claude Code marks the next Stop of the same turn `stop_hook_active`, and that Stop passes.
+#
+# MODES: CREW_TURN_CHECK=off  nothing runs. CREW_TURN_CHECK_TIMEOUT  seconds the check may take (default 120, at
+# most 170, under the hook's own 180). NOT A GATE ON ITS OWN FAILURE: an error of this script is silence (exit 0);
+# the only exit 2 is a check that ran and failed.
+set -uo pipefail
+case "${CREW_TURN_CHECK:-on}" in off|OFF|0|false) exit 0 ;; esac
+trap 'exit 0' EXIT
+export LC_ALL=C
+IN=""; IFS= read -r -d '' -t "${CREW_STDIN_TIMEOUT:-2}" IN 2>/dev/null; [ "$?" -gt 128 ] && exit 0
+
+_TC_HERE="${BASH_SOURCE%/*}"; [ "$_TC_HERE" = "${BASH_SOURCE}" ] && _TC_HERE=.
+P="${CLAUDE_PROJECT_DIR:-$PWD}"; cd "$P" 2>/dev/null || exit 0
+
+# The declared command, read with the builtin `read`: a project that declared none pays no process at all.
+FC=""
+if [ -f CLAUDE.md ]; then
+  while IFS= read -r _l || [ -n "$_l" ]; do
+    case "$_l" in "Fast check (files):"*) FC="${_l#Fast check (files):}"; break ;; esac
+  done < CLAUDE.md
+fi
+FC="${FC%$'\r'}"; FC="${FC#"${FC%%[![:space:]]*}"}"; FC="${FC%"${FC##*[![:space:]]}"}"
+case "$FC" in '`'*'`') FC="${FC#\`}"; FC="${FC%\`}" ;; esac
+case "$FC" in ''|'<'*|none|None|NONE) exit 0 ;; esac
+
+_field(){  # $1 = key -> _F, the payload's string value (letters, digits, - and _ only), "" when absent
+  local r="${IN#*\"$1\"}"; _F=""
+  [ "$r" = "$IN" ] && return 0
+  r="${r#"${r%%[![:space:]:]*}"}"; r="${r#\"}"; _F="${r%%\"*}"
+  case "$_F" in *[!A-Za-z0-9_-]*) _F="" ;; esac
+}
+_field hook_event_name; EV="$_F"
+_field session_id; SID="$_F"; [ -n "$SID" ] || exit 0
+
+GD="$(git rev-parse --absolute-git-dir 2>/dev/null)" || exit 0
+SNAPD="$GD/crewforth-turn"; SNAP="$SNAPD/$SID"
+_now(){ if [ "${BASH_VERSINFO[0]}" -ge 5 ] || { [ "${BASH_VERSINFO[0]}" -eq 4 ] && [ "${BASH_VERSINFO[1]}" -ge 2 ]; }; then printf -v NOW '%(%s)T' -1; else NOW="$(date +%s)"; fi; }
+
+# Dirty paths, NUL-separated, from `status -z` (a rename's old name is dropped; a deleted file is dropped).
+_dirty(){  # -> DIRTY array
+  DIRTY=()
+  local rec st path skip=0
+  while IFS= read -r -d '' rec; do
+    if [ "$skip" = 1 ]; then skip=0; continue; fi
+    st="${rec:0:2}"; path="${rec:3}"
+    case "$st" in R*|C*) skip=1 ;; esac
+    case "$st" in *D*) continue ;; esac
+    [ -f "$path" ] && DIRTY+=("$path")
+  done < <(git -c core.fsmonitor= status --porcelain=v1 -z --untracked-files=all 2>/dev/null)
+}
+_hashes(){  # paths in "$@" -> HASH array, one content id per path (git hash-object, one process)
+  HASH=()
+  [ "$#" -gt 0 ] || return 0
+  local h
+  while IFS= read -r h; do HASH+=("$h"); done < <(printf '%s\n' "$@" | git hash-object --stdin-paths 2>/dev/null)
+}
+
+if [ "$EV" = UserPromptSubmit ]; then
+  HEAD="$(git rev-parse -q --verify HEAD 2>/dev/null)"
+  _dirty; _hashes ${DIRTY[@]+"${DIRTY[@]}"}; _now
+  mkdir -p "$SNAPD" 2>/dev/null || exit 0
+  {
+    printf 'head\t%s\ntime\t%s\n' "${HEAD:--}" "$NOW"
+    i=0; while [ "$i" -lt "${#DIRTY[@]}" ]; do printf 'f\t%s\t%s\n' "${HASH[$i]:--}" "${DIRTY[$i]}"; i=$((i+1)); done
+  } > "$SNAP.tmp" 2>/dev/null && mv -f "$SNAP.tmp" "$SNAP" 2>/dev/null
+  exit 0
+fi
+
+[ "$EV" = Stop ] || exit 0
+case "$IN" in *'"stop_hook_active":true'*|*'"stop_hook_active": true'*) exit 0 ;; esac
+[ -f "$SNAP" ] || exit 0
+
+# ---- the turn's files -----------------------------------------------------------------------------------------
+# No associative arrays: macOS ships bash 3.2. The snapshot's dirty files are one newline-framed string of
+# "<content id> <path>" lines, and a lookup is one `case`.
+SH="-"; ST=0; BEFORE=$'\n'
+while IFS=$'\t' read -r k a b; do
+  case "$k" in head) SH="$a" ;; time) ST="$a" ;; f) BEFORE="$BEFORE$a $b"$'\n' ;; esac
+done < "$SNAP"
+rm -f "$SNAP" 2>/dev/null
+case "$ST" in ''|*[!0-9]*) ST=0 ;; esac
+
+SEEN=$'\n'; FILES=()
+_add(){
+  [ -n "$1" ] && [ -f "$1" ] || return 0
+  case "$SEEN" in *$'\n'"$1"$'\n'*) return 0 ;; esac
+  SEEN="$SEEN$1"$'\n'; FILES+=("$1")
+}
+
+_dirty; _hashes ${DIRTY[@]+"${DIRTY[@]}"}
+i=0; while [ "$i" -lt "${#DIRTY[@]}" ]; do
+  p="${DIRTY[$i]}"
+  case "$BEFORE" in *$'\n'"${HASH[$i]:-x} $p"$'\n'*) ;; *) _add "$p" ;; esac
+  i=$((i+1))
+done
+
+HEAD="$(git rev-parse -q --verify HEAD 2>/dev/null)"
+if [ -n "$HEAD" ] && [ "$SH" != - ] && [ "$HEAD" != "$SH" ]; then
+  # Only a turn whose every move of HEAD was a commit of its own counts its commits.
+  OURS=1; N=0
+  while IFS=$'\t' read -r sel subj; do
+    t="${sel#*@\{}"; t="${t%\}}"; case "$t" in *[!0-9]*|'') continue ;; esac
+    [ "$t" -ge "$ST" ] || break
+    N=$((N+1))
+    case "$subj" in "commit:"*|"commit (amend):"*|"commit (initial):"*|"cherry-pick:"*|"revert:"*) ;; *) OURS=0 ;; esac
+  done < <(git log -g --date=unix --format='%gd%x09%gs' -n 50 HEAD 2>/dev/null)
+  if [ "$OURS" = 1 ] && [ "$N" -gt 0 ]; then
+    while IFS= read -r -d '' p; do _add "$p"; done < <(git -c core.fsmonitor= diff --name-only -z --no-renames --diff-filter=d --no-ext-diff "$SH" "$HEAD" -- 2>/dev/null)
+  fi
+fi
+[ "${#FILES[@]}" -gt 0 ] || exit 0
+
+# ---- the command ---------------------------------------------------------------------------------------------
+CMD="$FC"
+case "$FC" in *'<file>'*)
+  Q=""; n=0
+  for p in "${FILES[@]}"; do
+    case "$p" in *"'"*|*[\;\&\|\<\>\`\$]*|-*) continue ;; esac
+    Q="${Q:+$Q }'$p'"; n=$((n+1)); [ "$n" -ge 50 ] && break
+  done
+  [ -n "$Q" ] || exit 0
+  CMD="${FC//<file>/$Q}" ;;
+esac
+
+[ -f "$_TC_HERE/guard-agent-model.sh" ] || exit 0
+. "$_TC_HERE/guard-agent-model.sh"
+declare -F _am_verify_ok >/dev/null 2>&1 || exit 0
+_am_state
+_field permission_mode; PM="${_F:-default}"
+if ! _am_verify_ok "$CMD" "$PM"; then
+  # Said once per session: a check that never runs must not look like one that passes.
+  if mkdir -p "$SNAPD" 2>/dev/null && [ ! -e "$SNAPD/$SID.said" ] && : > "$SNAPD/$SID.said" 2>/dev/null; then
+    W="${_AMVW//\\/\\\\}"; W="${W//\"/\\\"}"
+    printf '{"systemMessage":"crew: the fast check of this turn was not run: %s. CLAUDE.md declares it under Fast check (files)."}\n' "$W"
+  fi
+  exit 0
+fi
+
+LIM="${CREW_TURN_CHECK_TIMEOUT:-120}"; case "$LIM" in ''|*[!0-9]*) LIM=120 ;; esac; [ "$LIM" -le 170 ] || LIM=170
+OUTF="$SNAPD/$SID.out"; mkdir -p "$SNAPD" 2>/dev/null || exit 0
+if command -v setsid >/dev/null 2>&1; then ( exec setsid bash -c "$CMD" ) > "$OUTF" 2>&1 </dev/null &
+else set -m; ( exec bash -c "$CMD" ) > "$OUTF" 2>&1 </dev/null & set +m; fi
+VPID=$!; W=0; RC=""
+while kill -0 "$VPID" 2>/dev/null; do
+  if [ "$W" -ge "$LIM" ]; then
+    kill -TERM -- "-$VPID" 2>/dev/null; kill -TERM "$VPID" 2>/dev/null; sleep 1
+    kill -KILL -- "-$VPID" 2>/dev/null; kill -KILL "$VPID" 2>/dev/null; RC=timeout; break
+  fi
+  sleep 1; W=$((W+1))
+done
+if [ "$RC" = timeout ]; then
+  wait "$VPID" 2>/dev/null; rm -f "$OUTF" 2>/dev/null
+  printf '{"systemMessage":"crew: the fast check of this turn did not finish in %ss and was stopped; nothing is concluded from it."}\n' "$LIM"
+  exit 0
+fi
+wait "$VPID" 2>/dev/null; RC=$?
+TAIL="$(tail -n 20 "$OUTF" 2>/dev/null | cut -c1-300)"; rm -f "$OUTF" 2>/dev/null
+[ "$RC" = 0 ] && exit 0
+{
+  printf 'The fast check this project declares failed on the files this turn changed (exit %s): %s\n' "$RC" "$CMD"
+  printf 'The end of its output:\n%s\n' "$TAIL"
+  printf 'Fix what it reports in those files, or say to the user why it stays red. This is said once per turn.\n'
+} >&2
+trap - EXIT
+exit 2

package/kit/hooks/worktree-provision.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# PreToolUse + PostToolUse on EnterWorktree — a worktree the session enters carries Crewforth with it.
+#
+# Why: `.claude/` is gitignored in a fresh install, so a worktree made with `git worktree add ../x` has none. While
+# the session that entered it lives, its hooks keep running from the main checkout. But Claude Code records the
+# session under the worktree once it enters one, and a session resumed there reads its settings from the worktree:
+# with no `.claude/settings.json` there, NO hook is registered — no commit approval, no write gate, no fill line.
+# Measured on Claude Code 2.1.309: a resumed session in such a worktree ran no project hook (0 of 1), the same
+# worktree with `.claude/` copied in ran it (1 of 1). A field session ran four and a half hours that way, printing a
+# fill it had made up. A worktree Claude Code creates under `.claude/worktrees/` is not affected (measured: the
+# resumed session there still ran the main checkout's hooks), so it is left alone.
+#
+# What it does: before the move (PreToolUse, when the call names an existing path) and after it (PostToolUse, the
+# path the tool reports), a linked worktree of THIS repository with no `.claude/settings.json` gets a copy of this
+# checkout's `.claude/`, minus what belongs to one checkout only (`worktrees/`, `state/`, the review record, the
+# gate log). If the copy cannot be made, the PreToolUse call is refused (exit 2) with the reason, and the
+# PostToolUse call tells the user and the model, since the move already happened.
+set -uo pipefail
+# ---- CREW-FAILCLOSED ---------------------------------------------------------------------------------------
+# A gate that stops on an error of its own must refuse the call, not let it through. Claude Code blocks a tool call
+# on exit 2 only; a hook that dies with 1, or runs on past the rule that broke, has allowed it. Both happened in
+# one defect (measured, bash 5): a local array declared and not set is "unbound" under `set -u`, the rule that read
+# it was abandoned in the middle, the script went on with the NEXT top-level command and left with 0, and
+# `rm .claude/hooks/pre-commit` passed. bash does one of two things with such an error, by the kind of error:
+#   * it leaves the shell with a status that is neither 0 nor 2  -> the EXIT trap below turns that into a refusal;
+#   * it abandons the top-level command it was in and continues -> the whole gate IS one top-level command,
+#     _gate_main, which only ever ends by `exit`. If it RETURNS, it was abandoned, and the line after it refuses.
+# Not covered, and said so: an error inside a command substitution (only that subshell ends), and a command
+# that is not found (status 127, the script continues inside the same command).
+# Byte-identical in every PreToolUse gate; the suite pins it. No process is started.
+_crew_stop(){  # $1 = what happened
+  declare -F gatelog >/dev/null 2>&1 && gatelog BLOCK 4.5 "the gate stopped on an error of its own"
+  echo "GUARD (§4.5): this gate stopped on an error of its own ($1) before it finished judging the call, so the call is refused." >&2
+  echo "Nothing about the call itself was found. The error is the line above these two; it is a defect in Crewforth, not in what you ran. Run the doctor (bash .claude/eval/doctor.sh, Bash tool, not PowerShell) and report it." >&2
+  exit 2
+}
+trap '_crew_rc=$?; trap - EXIT; case "$_crew_rc" in 0|2) exit "$_crew_rc" ;; esac; _crew_stop "exit status $_crew_rc"' EXIT
+# ---- /CREW-FAILCLOSED
+unq(){ local p="${1#\"}"; p="${p%\"}"; p="${p//\\\\//}"; p="${p//\\//}"; printf '%s' "$p"; }   # JSON string -> path; \ -> /
+_gate_main(){
+local IN HERE SRC READER V EV P_IN P_OUT T MINE THEIRS TOP ERR e WHY SAFE
+IFS= read -r -d '' IN || true
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SRC="$(cd "$HERE/.." && pwd)"                      # this checkout's .claude/
+READER="$SRC/eval/lib/settings-json.awk"
+[ -f "$READER" ] || exit 0                         # no reader, nothing to read the payload with: fail open
+
+V="$(printf '%s' "$IN" | awk -v op=gets -v path='hook_event_name|tool_input.path|tool_response.worktreePath' -f "$READER" - 2>/dev/null)"
+EV="${V%%$'\t'*}"; V="${V#*$'\t'}"; P_IN="${V%%$'\t'*}"; V="${V#*$'\t'}"; P_OUT="${V%%$'\t'*}"
+EV="$(unq "$EV")"
+case "$EV" in
+  PreToolUse)  T="$(unq "$P_IN")" ;;
+  PostToolUse) T="$(unq "$P_OUT")" ;;
+  *) exit 0 ;;
+esac
+[ -n "$T" ] && [ -d "$T" ] || exit 0              # no path (Claude creates one under .claude/worktrees/) or none yet
+
+# Only a linked worktree of THIS repository, asked of git rather than compared as spelled (C:/ against /c/).
+MINE="$(git -C "$SRC/.." rev-parse --git-common-dir 2>/dev/null)" || exit 0
+THEIRS="$(git -C "$T" rev-parse --git-common-dir 2>/dev/null)" || exit 0
+case "$MINE" in /*|?:*) ;; *) MINE="$SRC/../$MINE" ;; esac
+case "$THEIRS" in /*|?:*) ;; *) THEIRS="$T/$THEIRS" ;; esac
+[ "$MINE" -ef "$THEIRS" ] || exit 0
+TOP="$(git -C "$T" rev-parse --show-toplevel 2>/dev/null)" || exit 0
+[ "$TOP" -ef "$SRC/.." ] && exit 0                 # the main checkout itself
+case "$(cd "$TOP" && pwd -P)/" in "$(cd "$SRC" && pwd -P)/worktrees/"*) exit 0 ;; esac   # Claude Code's own: unaffected
+[ -f "$TOP/.claude/settings.json" ] && exit 0      # already carries it (or .claude/ is tracked)
+
+ERR=""
+mkdir -p "$TOP/.claude" 2>/dev/null || ERR="could not create $TOP/.claude"
+if [ -z "$ERR" ]; then
+  for e in "$SRC"/* "$SRC"/.[!.]*; do
+    [ -e "$e" ] || continue
+    case "${e##*/}" in worktrees|state|review-pass.json|gate-log.tsv) continue ;; esac
+    cp -R "$e" "$TOP/.claude/" 2>/dev/null || { ERR="could not copy ${e##*/}"; break; }
+  done
+fi
+[ -z "$ERR" ] && { [ -f "$TOP/.claude/settings.json" ] && [ -d "$TOP/.claude/hooks" ] || ERR="the copy has no settings.json or hooks/"; }
+[ -z "$ERR" ] && exit 0
+
+WHY="Crewforth could not put its .claude/ into the worktree $TOP ($ERR). A session resumed there would load no Crewforth hook: no commit approval, no write gate, no fill reading."
+if [ "$EV" = PreToolUse ]; then
+  echo "$WHY Fix the cause above, then enter the worktree again." >&2
+  exit 2
+fi
+SAFE="${WHY//\\/\\\\}"; SAFE="${SAFE//\"/\\\"}"
+printf '{"systemMessage":"⚠️ %s","hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"%s Tell the user, and do not resume this session in that worktree until it is fixed."}}\n' "$SAFE" "$SAFE"
+exit 0
+}
+_gate_main "$@"
+_crew_stop "a command of the gate was abandoned"

package/kit/owned-blobs.tsv

@@ -1,9 +1,10 @@
-# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.2.1 (below VERSION 3.3.0) — do not edit by hand.
+# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.4.0 (below VERSION 3.5.0) — do not edit by hand.
 # The flat files Crewforth owns: a copy whose bytes (CR aside) are one of these ids was never edited.
 # install_path	blob_sha1	first_tag	last_tag
 .claude/AGENT_TEMPLATE.md	075e2c26706c06f56af01652cd24c36918513bee	v3.0.0	v3.0.4
 .claude/AGENT_TEMPLATE.md	2c8223d811245e3627a3011bb64fb9e4b0bf3b94	v3.2.0	v3.2.1
 .claude/AGENT_TEMPLATE.md	3fdc551d221ee3665b21ef8cc3563de861a9abe6	v1.4.0	v1.6.3
+.claude/AGENT_TEMPLATE.md	59d3af63b0480696dec38136e124bd582066fb16	v3.3.0	v3.4.0
 .claude/AGENT_TEMPLATE.md	686fed306c873b45c245c77a95a8e6de6ee383d5	v1.7.0	v2.11.0
 .claude/AGENT_TEMPLATE.md	7ab19417b6ff3ac732e2c894be17ffb3ec091f7d	v3.1.0	v3.1.1
 .claude/AGENT_TEMPLATE.md	981df9ea27b6f1c5ab5cb509d40875a07603858d	v2.12.0	v2.13.0
@@ -29,6 +30,7 @@
 .claude/DISCIPLINE.md	b7e1066451a8590e0a2607ad0a6fe80b21599c53	v1.1.3	v1.1.8
 .claude/DISCIPLINE.md	b90a067ee323a08146862b889293f8feb49f8e7e	v3.1.0	v3.1.1
 .claude/DISCIPLINE.md	bf062c2b51a9cf3cc4d0caac389c148cf6fdc977	v2.12.0	v2.12.0
+.claude/DISCIPLINE.md	c04f53866b84c54aa0e60089cb54cdc7c9aa8df1	v3.3.0	v3.4.0
 .claude/DISCIPLINE.md	c693f1bd5832ce570058c6eedcacb5dff13d89e8	v1.10.0	v1.10.0
 .claude/DISCIPLINE.md	cf881a5229d85850194a98b8d0d0438a8eaaa9d6	v3.2.0	v3.2.1
 .claude/DISCIPLINE.md	d63a01a183c9a80d739c840a511d338dc2765820	v1.4.0	v1.4.4
@@ -45,4 +47,4 @@
 .claude/README.md	97d4dd1f7f1695052cc1d06cc43f5bcdc603c989	v1.0.0	v1.0.4
 .claude/README.md	a3419891cfda7385564008e4befc1007bc5364cb	v1.1.1	v1.7.0
 .claude/README.md	a3b76e0fa31267610d28b742c122a962f6db59c4	v3.0.1	v3.0.4
-.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.2.1
+.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.4.0

package/kit/settings.json

@@ -119,6 +119,17 @@
             "timeout": 600
           }
         ]
+      },
+      {
+        "matcher": "EnterWorktree",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/worktree-provision.sh",
+            "timeout": 600
+          }
+        ]
       }
     ],
     "UserPromptSubmit": [
@@ -141,6 +152,12 @@
             "shell": "bash",
             "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/route-hint.sh",
             "timeout": 60
+          },
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/turn-check.sh",
+            "timeout": 30
           }
         ]
       }
@@ -159,6 +176,18 @@
             "shell": "bash",
             "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/prompt-approval.sh",
             "timeout": 60
+          },
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/map-stale.sh",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/turn-check.sh",
+            "timeout": 180
           }
         ]
       }
@@ -220,6 +249,52 @@
             "timeout": 60
           }
         ]
+      },
+      {
+        "matcher": "EnterWorktree",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/worktree-provision.sh",
+            "timeout": 60
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/loop-guard.sh",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/map-stale.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/loop-guard.sh",
+            "timeout": 30
+          }
+        ]
       }
     ],
     "PreCompact": [
@@ -269,6 +344,17 @@
           }
         ]
       },
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "shell": "bash",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" 2>/dev/null; bash .claude/hooks/branch-fresh.sh",
+            "timeout": 30
+          }
+        ]
+      },
       {
         "matcher": "startup",
         "hooks": [

package/kit/skills/a11y/SKILL.md

@@ -8,9 +8,9 @@ description: |
 # Accessibility (a11y)
 
 <!-- routing-eval reads the next line; why it sits in the body: AGENT_TEMPLATE.md -->
-Trigger phrases: "a11y", "accessibility", "WCAG", "screen reader", "keyboard navigation", "contrast", "ARIA", "keyboard only", "with a keyboard", "keyboard focus", "without a mouse", "focus ring", "tab order", "alt text", "color blind", "colour blind", "voiceover", "talkback", "reduced motion"
+Trigger phrases: "a11y", "accessibility", "WCAG", "screen reader", "keyboard navigation", "contrast", "ARIA", "keyboard only", "with a keyboard", "keyboard focus", "without a mouse", "focus ring", "tab order", "alt text", "color blind", "colour blind", "voiceover", "talkback", "reduced motion", "target size", "focus not obscured", "focus is hidden", "WCAG 2.2"
 
-Goal: make the interface usable by **everyone**, including keyboard, screen reader, and low vision. Baseline target: **WCAG 2.1 AA**.
+Goal: make the interface usable by **everyone**, including keyboard, screen reader, and low vision. Baseline target: **WCAG 2.2 AA**.
 Stack-agnostic (web/React/RN); do a web search when needed for framework-specific APIs.
 
 ## Checklist
@@ -21,9 +21,56 @@ Stack-agnostic (web/React/RN); do a web search when needed for framework-specifi
 - [ ] **Alt text**: `alt` on meaningful images; `alt=""` on decorative images
 - [ ] **Forms**: every input has a `label`; error message programmatically linked (`aria-describedby`)
 - [ ] **ARIA**: only when needed; wrong ARIA is worse than no ARIA; role/name/state correct
-- [ ] **Motion/animation**: respect `prefers-reduced-motion`
+- [ ] **Motion/animation**: respect `prefers-reduced-motion`; anything that moves for more than 5 s can be paused (2.2.2)
 - [ ] **Language**: `<html lang>` correct (coordinate with i18n)
 
+WCAG 2.2 added these; a 2.1 checklist misses all of them:
+- [ ] **Focus not obscured** (2.4.11): a focused element is never fully hidden under a sticky header, footer or banner
+- [ ] **Dragging** (2.5.7): every drag has a single-pointer alternative (buttons, a menu)
+- [ ] **Target size** (2.5.8): pointer targets ≥ 24×24 CSS px, or spaced so a 24 px circle on each does not overlap another
+- [ ] **Redundant entry** (3.3.7): information already given in the same flow is filled in or selectable, not asked again
+- [ ] **Accessible authentication** (3.3.8): no memory or puzzle test to sign in without an alternative; paste and
+  password managers work
+
+Commonly missed, all checkable in the markup:
+- [ ] **Autocomplete** (1.3.5): personal-data inputs carry the right `autocomplete` token
+- [ ] **No paste blocking** on any input, passwords and confirmations included
+- [ ] **Submit stays enabled**: a disabled-until-valid button hides why; validate on submit and say what is wrong
+- [ ] **Zoom and reflow** (1.4.4, 1.4.10): usable at 200% text and at 320 CSS px wide; no `maximum-scale=1` or
+  `user-scalable=no` in the viewport meta
+- [ ] **Skip link** (2.4.1): the first focusable element jumps past repeated navigation to `main`
+- [ ] **No flashing** (2.3.1): nothing flashes more than three times a second
+- [ ] **Error summary**: a form that fails lists its errors in one focusable block that links to each field
+- [ ] **No positive `tabindex`**: `0` and `-1` only; order comes from the DOM
+
+**Criteria, not conventions.** A failed A or AA criterion, or a task a keyboard or screen-reader user cannot finish,
+is a finding. AAA, an ARIA Authoring Practices pattern, or a 44 px target where 24 px passes is a recommendation:
+say so, and never rank it with a finding.
+
+## Before you finish: grep for these
+| Pattern in the diff | Why it fails |
+|---|---|
+| `outline: none` / `outline: 0` with no `:focus-visible` rule | focus becomes invisible (2.4.7) |
+| `<div onClick` / `<span onClick` with no role and key handler | not reachable by keyboard (2.1.1) |
+| `tabindex="1"` or higher | breaks the reading order (2.4.3) |
+| `disabled={!isValid}` on a submit | hides why the form cannot be sent |
+| a live region rendered together with its text | many readers announce nothing: render it empty first |
+| `maximum-scale=1`, `user-scalable=no` | blocks zoom (1.4.4) |
+| `aria-hidden="true"` on an element that holds something focusable | focus lands on nothing the reader can name |
+| `<img` with no `alt` | no text alternative (1.1.1) |
+| `onDrag`/`draggable` with no button or menu path | no single-pointer alternative (2.5.7) |
+
+## Symptom → cause → fix
+| Symptom | Usual cause | Fix |
+|---|---|---|
+| Reader says "button" and nothing else | icon-only button with no name | `aria-label`, or visually hidden text |
+| Tab skips an element | a `div` handling clicks | a real `button` / `a` |
+| Focus lost after a modal closes | focus not returned | return it to the element that opened the modal |
+| An error appears and nothing is announced | message not tied to the field or a live region | `aria-describedby` on the field; a status region for the summary |
+| Layout breaks at 200% zoom | fixed heights or widths in px | let text boxes grow; `min-width: 0` on flex and grid children |
+
+Recipes for focus, forms and announcements (which channel says what, in order): `references/recipes.md`.
+
 ## How
 1. **Start with semantics** — the right element solves 80%. Use `button` instead of `role="button"`+`div`.
 2. **Navigate with the keyboard** — drop the mouse, run the whole flow with Tab/Shift-Tab/Enter/Escape; is focus visible and its order sensible.

package/kit/skills/a11y/references/recipes.md

@@ -0,0 +1,41 @@
+# Accessibility recipes: focus, forms, announcements
+
+Loaded from the `a11y` skill when a change moves focus, validates a form or tells the user something happened.
+Stack-neutral; the React Native and Flutter equivalents are named in the skill.
+
+## Focus
+- **Where focus goes after an action.** Opening a dialog: to its first meaningful control, or to the dialog itself
+  when it starts with text. Closing it: back to the control that opened it. Deleting the focused row: to the next
+  row, or the previous one when it was the last. A route change: to the new page's `h1` (`tabindex="-1"`), or to a
+  skip target, so the reader starts at the content and not at the top of the navigation.
+- **Visible focus.** Style `:focus-visible`, never remove `outline` without a replacement of at least 2 px with 3:1
+  contrast against what surrounds it. A sticky header must not cover the focused element: set `scroll-padding-top`
+  to its height.
+- **Traps.** Only a modal traps focus, and Escape always leaves it. `inert` on the background is the simplest trap
+  where it is supported.
+
+## Forms
+- Every field has a visible `label` tied by `for`/`id`; a placeholder is not a label.
+- Validate on submit (and on blur for a field the user has left), not on every keystroke.
+- On a failed submit: put a summary at the top that names how many errors there are and links to each field, move
+  focus to it, and tie each field's message to the field with `aria-describedby` and `aria-invalid="true"`.
+- Keep the submit button enabled; a disabled button cannot be focused and does not say what is missing.
+- Required fields say so in text, not only with a colour or an asterisk the reader skips.
+- Known personal data carries its `autocomplete` token (`name`, `email`, `tel`, `street-address`, `one-time-code`,
+  `current-password`, `new-password`).
+
+## Announcements: the cheapest channel that works
+Use the first rung that fits; each one further down interrupts more.
+1. **Move focus** when the user must act next (a dialog opened, an error summary).
+2. **`aria-describedby`** when the message belongs to one control (a field hint, a field error).
+3. **`role="status"`** (polite) for a result the user should hear without being interrupted: "Saved", "3 results".
+4. **`role="alert"`** (assertive) only for something that cannot wait: a session about to expire, a failed payment.
+
+Rules that make the live regions work:
+- Render the region **empty** when the page loads and change its text later. A region that arrives together with its
+  text is often not announced.
+- One polite region per page is usually enough; reuse it instead of adding one per component.
+- Do not announce what focus already says. Moving focus to an error summary and also putting it in an alert reads it
+  twice.
+- Toasts that disappear on their own need a status region and enough time to read (at least 5 s, longer for longer
+  text), or a way to bring them back.

package/kit/skills/adr/SKILL.md

@@ -34,7 +34,14 @@ every teammate's next session opening, and it travels even when the board lives
 file stays the long form; the board entry is the part that has to reach people, so it must be readable on its
 own — a title nobody can act on ("auth decided") is not a record.
 
-## Format (docs/adr/NNNN-short-title.md, ~1 page)
+## Where it goes: the project's scheme first
+Before writing, look for records that already exist: a decisions folder (`docs/adr/`, `doc/adr/`,
+`docs/decisions/`, `Documentation/Decisions/`, `architecture/decisions/`), an `.adr-dir` file (adr-tools), or files
+named like `ADR-004-…` or `0004-…`. Found: continue it, same folder, extension (.md, .rst, .adoc), numbering and
+heading style, next number. Not found: `docs/adr/NNNN-short-title.md` below. Never start a second scheme beside one
+that exists; two numbering lines make every "see ADR 12" ambiguous.
+
+## Format (fallback: docs/adr/NNNN-short-title.md, ~1 page)
 ```
 # NNNN. <Decision title>
 Status: proposed | accepted | rejected | superseded (by NNNN)
@@ -46,11 +53,15 @@ What was decided (clear, one sentence + rationale)?
 Pros / cons / accepted trade-offs.
 ## Alternatives considered
 Why were they not chosen?
+Verified against: <package>@<version> · <docs or source> · <date> — or "none" (no external fact relied on)
 ```
 
 ## Principles
 - **Invariant:** a new decision marks the old ADR as `superseded`; an ADR is **never deleted** (decision history is preserved).
 - Numbered and dated; keep it short.
+- **A number a test enforces moves with its ADR.** When a test or gate pins a figure an ADR set (a cap, a count, a
+  budget), the change that moves the figure amends that ADR in the same commit; a figure that drifts from its record
+  leaves the next reader two answers.
 
 ## Deliberately bypassing a rule is a decision too
 A gate the user knowingly overrode — a deferred DoD item, an accepted known gap, a trimmed scope — belongs here
@@ -67,7 +78,8 @@ Record it in the same file as any other decision, with the fields that make it r
 ```
 
 `revisit` is the load-bearing field. A bypass with no condition attached is permanent by default, and nobody
-chose permanence. See [[confidence-check]], which is where most bypasses surface.
+chose permanence. See [[confidence-check]], which is where most bypasses surface. A recorded bypass is the user's decision, not a
+deferral (`CLAUDE.md`, "No deferral").
 
 ## DoD
 - Decision + rationale + rejected alternatives recorded; status current.

package/kit/skills/api-design/SKILL.md

@@ -20,7 +20,8 @@ public API is a commitment; a breaking change is expensive. Stack-agnostic (REST
 - [ ] A clear **versioning** strategy (URL `/v1` or header); a breaking change means a new version
 - [ ] **Pagination/filtering/sorting** defined and consistent on large collections
 - [ ] **Backward compatibility**: adding a field is additive; removing a field or changing its meaning is breaking → version
-- [ ] **Idempotency** (for POST/payment-like cases) supported via a key when needed
+- [ ] **Idempotency** (for POST/payment-like cases) supported via a key when needed: the key, its atomic claim and
+  the answers to a replay are in **`references/idempotency.md`**
 - [ ] The contract is documented in **OpenAPI**; example request/response present (coordinate with `docs-writer`)
 
 ## How
@@ -42,6 +43,10 @@ public API is a commitment; a breaking change is expensive. Stack-agnostic (REST
 | A new optional parameter | Add a required parameter |
 | A new enum value (if the consumer is tolerant) | Change a type/meaning, change a status code |
 
+**Observable behaviour is the contract,** not only the documented fields: someone depends on the error text, the
+order of a list, the default page size and how long a call takes. Changing one of those is breaking for them; say
+it in the changelog like a field change.
+
 ## Invariant rules
 1. **A public API is a commitment** — a breaking change is not made silently; version + announcement.
 2. **Consistency > local cleverness** — a single naming/error/pagination pattern across the whole API.

package/kit/skills/api-design/references/idempotency.md

@@ -0,0 +1,39 @@
+# Idempotency keys
+
+A retried POST that charges twice, ships twice or creates two rows is the bug this prevents. The key makes a retry
+safe; the store behind it decides whether it really is.
+
+## The key
+- **From the intent, not the request.** The client sends `Idempotency-Key` (a UUID made once per user action, kept
+  across its retries), or the server derives one from what the action means (order id + operation). A key made per
+  HTTP attempt protects nothing: every retry is new.
+- **Scoped to the caller.** Store it per account or API client, so two callers cannot collide or read each other's
+  result.
+
+## Claiming it
+- **Atomically.** Insert the key under a unique constraint (or an equivalent conditional write) before the side
+  effect runs. "Look it up, then insert" leaves a window where two retries both find nothing and both charge.
+- **With a fingerprint of the payload.** Store a hash of the normalised body with the key.
+
+## Answers
+| The request | The answer |
+|---|---|
+| New key | Run it; store the outcome with the key |
+| Same key, same payload, finished | The stored response, status code included, without running it again |
+| Same key, different payload | `422` (or `409`): a client bug, never a silent replay of the first result |
+| Same key, first attempt still running | `409` with `Retry-After`, or wait briefly, or `202` with a status URL; never a second run |
+
+Three outcomes are stored: **succeeded** (replay it), **failed in a way the client can fix** (replay the 4xx), and
+**failed before or during the side effect** (5xx, timeout): release the key, or mark it retryable, so the next
+retry can run. Storing a 5xx as final turns a passing outage into a permanent failure for that action.
+
+## Retention
+Keep a key longer than the longest retry chain any client runs (its backoff schedule and the queue's redelivery
+window), and say how long in the API docs. A key dropped after one hour is useless to a client that retries for a
+day.
+
+## Review checks
+- The side effect and the key claim are in one transaction, or the key is claimed first and the effect is
+  conditional on it.
+- A downstream call (payment provider, email) gets its own idempotency key, derived from ours.
+- A test sends the same key twice in parallel and finds one effect.