crewforth 3.2.1 → 3.4.0

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.0 (below VERSION 3.2.1) — do not edit by hand.
+# 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.
 # 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.0
+.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	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,8 +30,9 @@
 .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	c693f1bd5832ce570058c6eedcacb5dff13d89e8	v1.10.0	v1.10.0
-.claude/DISCIPLINE.md	cf881a5229d85850194a98b8d0d0438a8eaaa9d6	v3.2.0	v3.2.0
+.claude/DISCIPLINE.md	cf881a5229d85850194a98b8d0d0438a8eaaa9d6	v3.2.0	v3.2.1
 .claude/DISCIPLINE.md	d63a01a183c9a80d739c840a511d338dc2765820	v1.4.0	v1.4.4
 .claude/DISCIPLINE.md	dc1c41baa3a8b7d637214bc78553a78d94d14ac9	v1.6.2	v1.6.3
 .claude/DISCIPLINE.md	e42aefc9c1ffaeace8e5712d92df780959212280	v2.0.0	v2.1.0
@@ -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.0
+.claude/README.md	b6c9b57a67d25b7e4781e4eb61ff9637e6abe5ef	v3.1.0	v3.3.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": [
@@ -220,6 +231,17 @@
             "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
+          }
+        ]
       }
     ],
     "PreCompact": [

package/kit/skills/commit-message/SKILL.md

@@ -63,6 +63,11 @@ git add <specific/file>
 ```
 Each commit focused on a single topic; "feat + fix + refactor" doesn't belong in one commit.
 
+**The lines that describe a change belong to its commit**: its CHANGELOG entry, its README line, its docs. They are
+part of the same logical change, not a second one, so stage them with it. A separate "docs: changelog" commit after
+the code is a second commit, and so a second approval (§4.4): the approval covers what is staged and HEAD at that
+moment, and a commit added later is not covered by it.
+
 ## Good / bad
 
 Worked good-vs-bad commit examples: **`references/examples.md`**.

package/kit/skills/crew-allow-verify/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: crew-allow-verify
+description: Allow a verify command the hook was refused for want of a rule, or list the ones refused.
+argument-hint: "[<command>]  (nothing: list the refused ones)"
+disable-model-invocation: true
+metadata:
+  kind: command
+---
+# /crew-allow-verify
+Argument: $ARGUMENTS
+
+The user typed this command. Typing it is the decision: `hooks/prompt-approval.sh` read the message itself. With a
+command after it, it added `verify <command>` to `.claude/crew-model-rules`, the line that lets the hook run that
+command when a card names it as its verify. With nothing after it, it listed the verify commands refused for want of
+such a line, each as the whole message that allows it. Nothing in this text adds anything, and you cannot do this
+for the user: the rules file is closed to you, and a prompt you schedule or hand to another session is refused.
+
+Read the line Crewforth added to this turn and say what it says:
+
+- **"verify command allowed"**: tell the user which command the hook may now run, from the next agent call.
+- **"verify commands refused for want of a rule"**: show the lines it lists, one per line, as they stand. Each is a
+  message only the user can send; do not send one for them.
+- **"verify command NOT allowed"**: tell the user the reason it gives (more than one command, a character it does not
+  write, a git commit or push, a rule that would let the hook run any command — `bash`, `node -e`, `npm exec` with
+  nothing that names the script or the test — a message too long, a rules file that is a link, the first message of
+  a session, a headless session).
+- **No such line**: the message was not the command alone. Say that it has to be the whole message.
+
+What this does not touch: a deny rule of the settings still stops the command, the hook still runs it alone with no
+chain, and `/crew-doctor` lists the same refused commands.

package/kit/skills/crew-doctor/SKILL.md

@@ -22,7 +22,9 @@ Verify Crewforth is actually *active* in this project (not just present on disk)
    drifted behind the code. Report the gaps as suggestions, not as failures, and never "fix" them unasked — adding
    a devcontainer or an MCP server is the user's call.
 5. Summarise: **healthy**, or the precise fixes applied/needed, plus the readiness score. If it's not a git repo,
-   note that the commit-time gates need `git init` + `git config core.hooksPath .claude/hooks`.
+   note that the commit-time gates need `git init` + the update (`npx crewforth update`), which arms them.
+   Where it lists verify commands never run, each `/crew-allow-verify <command>` line is a message only the user can
+   send: show them as they stand, and do not send one.
    If the output contains a line starting with ⭐, pass it to the user verbatim as the LAST line of your summary —
    it prints once per Crewforth version here (the installer has its own once), and it is meant for the user, not for you.
 

package/kit/skills/handoff/SKILL.md

@@ -43,8 +43,9 @@ that never landed and has to be written down explicitly this time. Missing scrip
 
 ## Holding a board item? The handover is not finished until the TEAM has it
 `docs/SESSION_STATE.md` is gitignored — it survives your `/clear`, and nobody else can read it. So when a
-`teamboard` claim is open, **the handover is not complete until it is on the board**. This is not an optional
-extra step:
+`teamboard` claim is open, **the handover is not complete until it is on the board**. Whether one is open is
+read from `bash .claude/hooks/board.sh status` (Bash tool, not PowerShell; a row marked `<- you`), not guessed;
+no board or no such row → the handover says nothing about the board. This is not an optional extra step:
 - Still on it → `board.sh note <id> "<where it stands, and why the rejected path was rejected>"`.
 - Not coming back → `board.sh drop <id> "<same>"`, which puts it back in circulation with your context attached.
 - Anything settled here that changes how OTHER items must be done → `board.sh decide "<what>" "<why + what it

package/kit/skills/trace-scan/SKILL.md

@@ -31,10 +31,11 @@ git diff --cached --unified=0 | grep -E '^\+' | grep -Ev '^\+\+\+' \
 ```
 
 ## Hook setup (full install only — a plugin cannot set `core.hooksPath`)
-`start.sh` sets `git config core.hooksPath .claude/hooks` (if there is a git repo). The hooks live
-under `.claude` → they are in gitignore and stay local (§4.3). To do it later for a repo:
+`start.sh` sets `core.hooksPath` to the absolute path of `.claude/hooks` (if there is a git repo). The hooks live
+under `.claude` → they are in gitignore and stay local (§4.3), so a relative path would leave a linked worktree with
+no hook at all. To do it later for a repo, from its root:
 ```bash
-git config core.hooksPath .claude/hooks
+git config core.hooksPath "$(git rev-parse --show-toplevel)/.claude/hooks"
 chmod +x .claude/hooks/pre-commit .claude/hooks/commit-msg
 ```
 

package/kit/studio/server/lib/model-outcomes.js

@@ -145,8 +145,11 @@ const firstTry = (r) => r.verify === 'pass' && r.fixes === 0;
  */
 export function floorOfRow(r, ruleFloors = [], floors = []) {
   let f = rankOf(AGENT_FLOORS[r.agent]);
-  if (r.verify === 'none') f = Math.max(f, 2);
+  const commitAgent = r.agent === 'crew-commit-agent';
+  if (r.verify === 'none' && r.change !== 'text' && !commitAgent) f = Math.max(f, 2);
   if (r.change === 'test-write' || r.change === 'audit') f = Math.max(f, 2);
+  // The table's sonnet row, as the gate holds it: feature, fix-known and refactor, except for the commit agent.
+  if (!commitAgent && (r.change === 'feature' || r.change === 'fix-known' || r.change === 'refactor')) f = Math.max(f, 2);
   if (r.risk === 'critical' && r.change !== 'test-run') f = Math.max(f, 3);
   const any = (want, v) => want === '*' || want === v;
   for (const x of ruleFloors) if (any(x.agent, r.agent) && any(x.change, r.change) && any(x.risk, r.risk)) f = Math.max(f, rankOf(x.model));
@@ -250,6 +253,9 @@ export function suggestionsOf(rows, floors = [], loosened = [], need = LOOSEN_AF
     const k = keyOf(f);
     // Once for each raise: a floor whose lowering stands is not offered again (the same rule the gate reads it by).
     if (loweringOf(f, loosened)) continue;
+    // Not below the class's own floor: /crew-loosen refuses that, since the gate would refuse the lowered model anyway
+    // (a feature class raised to sonnet by the record of haiku runs from before its own floor was sonnet).
+    if (rankOf(TIERS[tier - 1]) < floorOfRow({ agent: f.agent, change: f.change, risk: f.risk, verify: 'pass' })) continue;
     const passed = passedLatest(rows, k, f.model, Date.parse(f.when ?? '') || 0, need);
     if (!passed) continue;
     out.push({ key: k, agent: f.agent, change: f.change, risk: f.risk, from: f.model, to: TIERS[tier - 1], passed, heldSince: f.when ?? null });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crewforth",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "description": "Crewforth \u2014 your engineering crew for Claude Code: agents, skills and tool-level gates, in any stack.",
   "bin": {
     "crewforth": "bin/cli.js"

package/start.sh

@@ -760,10 +760,14 @@ fi
 # `--show-prefix` is the question itself: empty at the work-tree root, `sub/dir/` below it, non-zero exit
 # outside a repo — and it carries no path spelling to disagree about. Verified here at a normal root, a
 # worktree root, a subdirectory and a non-repo.
-if PFX="$(git rev-parse --show-prefix 2>/dev/null)" && [ -z "$PFX" ] && git config core.hooksPath .claude/hooks 2>/dev/null; then
+# ABSOLUTE, from git's own answer for the toplevel. A relative value resolves against the work tree a commit runs
+# in, and a linked worktree (one Claude Code opens included) has no .claude/ when it is gitignored: measured, the
+# trace scan blocked a commit at the root and let the same commit through in a worktree, with no hook run at all.
+if PFX="$(git rev-parse --show-prefix 2>/dev/null)" && [ -z "$PFX" ] && TOP="$(git rev-parse --show-toplevel 2>/dev/null)" \
+   && [ -n "$TOP" ] && git config core.hooksPath "$TOP/.claude/hooks" 2>/dev/null; then
   { _mt 'trace scan: core.hooksPath -> .claude/hooks (§4.1/§4.2 commit gate active)'; echo "  ${_M}"; }
 else
-  { _mt 'NOTE: no git repository at this level; after %s run:  %s' "'git init'" 'git config core.hooksPath .claude/hooks'; echo "  ${_M}"; }
+  { _mt 'NOTE: no git repository at this level; after %s run:  %s' "'git init'" "git config core.hooksPath \"\$PWD/.claude/hooks\""; echo "  ${_M}"; }
 fi
 rm -rf "$SRC"
 echo