crewforth 3.4.0 → 3.5.0-rc.2

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/owned-blobs.tsv

@@ -1,10 +1,10 @@
-# Generated by packaging/gen-legacy-blobs.sh from the final release tags v1.0.0..v3.3.0 (below VERSION 3.4.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.3.0
+.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
@@ -30,7 +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.3.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
@@ -47,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.3.0
+.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.4.0

package/kit/settings.json

@@ -152,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
           }
         ]
       }
@@ -170,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
           }
         ]
       }
@@ -242,6 +260,41 @@
             "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": [
@@ -291,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.

package/kit/skills/brainstorm/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: brainstorm
 description: |
-  Divergent discovery BEFORE planning: turn a fuzzy ask into 2–4 scoped options + named unknowns, pick a
-  direction, hand to spec-planning. Bounded; converges to explicit choices, never guesses.
+  Use when the ask is still fuzzy and no direction is chosen yet: "not sure what we want", several ways to go,
+  or a scope to settle before any plan is written.
 ---
 
 # Brainstorm — diverge before you converge
@@ -27,6 +27,8 @@ option into tasks). If scope is already clear, skip this and go straight to [[sp
 4. **Converge — ask, don't guess.** Present the directions as **explicit numbered options** and let the user
    choose (CLAUDE.md discipline: a decision point = multiple choice, never a prose either/or). Record the
    chosen direction + the rejected ones with the one-line reason they lost.
+   How to put a question, what is worth asking and what to do when no answer comes:
+   `references/asking.md`; `/crew-interview` runs the whole round of questions as a command.
 5. **Hand off.** The chosen direction + resolved constraints flow into `spec-planning`; a lasting
    architectural choice made here is recorded with [[adr]].
 

package/kit/skills/brainstorm/references/asking.md

@@ -0,0 +1,47 @@
+# Asking the user — what is worth a question, and how to put it
+
+The discipline says to ask at every decision point with `AskUserQuestion`. This file says what a decision point
+is, and how to put one so the answer settles something.
+
+## Facts are yours, decisions are theirs
+- **Never ask for a fact the workspace, the docs or the web can answer**: the ORM, the test runner, the Node
+  version, where a file lives. Read it, then state it.
+- If the options differ only in how the code does it, and a user would see the same behaviour either way, it is
+  not their decision. Pick, and say what you picked.
+- A decision is theirs when it changes what someone sees or pays: scope, behaviour, data kept or shown, cost, risk,
+  a trade-off between two things they want.
+
+## Is it worth asking?
+A question earns its place when all three hold:
+1. **The answer changes the outcome.** If every answer leads to the same next step, do not ask.
+2. **It is about this work**, not a principle ("do you value maintainability?").
+3. **It is not asked already.** Never ask again what was answered in this session or recorded in the project.
+
+Where to look for the questions that matter: the empty state, the error state, two people at once, existing data
+when the shape changes, and the default when nobody chooses. When two things the user said pull against each
+other, quote both and ask which wins.
+
+## Putting the question
+- **One `AskUserQuestion` call, at most 4 questions, and only questions that do not depend on each other.** A
+  question whose options depend on another answer waits for the next call.
+- **Options are behaviour, not mechanics.** "A saved draft survives closing the tab" beats "use localStorage".
+- **Recommended option first**, marked as recommended, with a one-line reason. The user should be able to agree
+  in one click.
+- A concrete case beats an abstract choice: "a refund on an order shipped in two parts" is answerable;
+  "refund granularity" is not.
+
+## Confirming an inference
+When you can infer the answer, do not ask an open question: state the inference and let the user confirm it.
+The statement is the question: "Looks right" / "Off base" (and what to change). Read the answer four ways: a
+yes, a no, a correction (take the correction, not your inference), or a new constraint (add it, then re-check
+what it changes).
+
+## When the answer does not come
+- **A skipped question becomes a recorded assumption.** Write it down where the plan or brief keeps its
+  assumptions, so it can be revisited, and go on.
+- **A whole round skipped means stop asking.** Proceed on the recorded assumptions and say so.
+- **"I don't know"** means the question was framed wrong. Re-ask it from what the user would see, not from how it
+  is built.
+- **No one can answer** (`auto` mode with no person attending, `/loop`, a scheduled or headless run): do not
+  interview. Take the recommended option for each open decision, record it as an assumption, and list the
+  assumptions at the top of what you hand over.

package/kit/skills/ci-pipeline/SKILL.md

@@ -19,9 +19,19 @@ Trigger phrases: "ci", "pipeline", "github actions", "jenkins", "build pipeline"
 
 ## Principles
 - **Deterministic:** dependencies pinned, cache keyed correctly; no "it worked on my machine".
-- **Secret management:** CI secret store; NO plaintext secrets in the repo/logs (overlaps with trace scan).
+- **Actions and the token:** pin every third-party action to a full commit SHA with its version in a comment (a tag
+  moves when its owner moves it); `permissions: contents: read` at the top, raised per job only where a step writes;
+  `persist-credentials: false` on checkout unless a later step pushes; never put `${{ github.event.* }}` or a matrix
+  value inside `run:` — pass it through `env:` and quote it.
+- **Secret management:** CI secret store; NO plaintext secrets in the repo/logs (overlaps with trace scan). Log
+  masking is a filter on exact strings: an encoded, split or transformed value prints in clear, so a secret never
+  reaches a step that echoes its environment. Prefer short-lived OIDC credentials over stored keys and ephemeral
+  runners over reused ones; a cache restored into a job is input, so key it on what produced it and never on a
+  value a fork controls.
 - **PR gate:** quality gate + tests must pass; a red build is not merged.
 - **Branch protection:** direct push to main is disabled; PR + review required.
+- **An agent job in CI** (one that fixes, updates or triages with nobody watching): pinned, few tools, an isolated
+  copy, an allowlist for what comes back: **`references/agent-job.md`**.
 
 ## When a stage fails
 1. **Fetch the failing job's log first** — `gh run view --log-failed`, `glab ci trace`, `jenkins-cli console <job>`,