crewforth 0.0.1 → 3.0.0-rc.2

package/kit/eval/update-guard.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# The two measured halves around an update, for /crew-update. Run from the project root.
+#
+#   update-guard.sh pre    before the update: names uncommitted changes in .claude/ and CLAUDE.md (it WARNS, it
+#                          never stops anything — whether to go ahead is the user's call, asked by /crew-update),
+#                          then records what is on disk now.
+#   update-guard.sh post   after the update: lists what the update added, changed, moved and removed, and points
+#                          at the release notes the updater extracted from the package's own CHANGELOG.
+#
+# It writes exactly one file, .claude/.state/update-snapshot, and changes nothing else. The snapshot is one
+# `cksum` over every file (one process for the lot, not one per file — that is 200 forks on Git Bash), so a
+# move is a removed path and an added path with the same checksum. The state directory and the gate log are
+# left out: they change on every run and say nothing about the update.
+set -u
+MODE="${1:-}"
+[ -d .claude ] || { echo "update-guard: no .claude/ here — run it from the project root" >&2; exit 2; }
+SNAP=".claude/.state/update-snapshot"
+
+snapshot(){ # -> "<crc> <size> <path>" per file, sorted by path
+  { find .claude -type f ! -path '.claude/.state/*' ! -name gate-log.tsv -print0 2>/dev/null
+    [ -f CLAUDE.md ] && printf 'CLAUDE.md\0'; } | xargs -0 cksum 2>/dev/null | LC_ALL=C sort -k3
+}
+
+case "$MODE" in
+  pre)
+    if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      # What git does not track, it cannot call uncommitted: a private install (the default) gitignores .claude/
+      # and CLAUDE.md, and then "clean" would be a claim nobody measured. Say which paths are outside git instead.
+      UNTR=""; for _p in .claude CLAUDE.md; do [ -e "$_p" ] && git check-ignore -q "$_p" 2>/dev/null && UNTR="$UNTR $_p"; done
+      # Crewforth's own runtime state is left out: it changes on its own, and a repo that committed it before it
+      # was ignored would otherwise warn on every update about a cache nobody edited.
+      DIRTY="$(git status --porcelain --untracked-files=all -- .claude CLAUDE.md ':(exclude).claude/.state' 2>/dev/null)"
+      if [ -n "$DIRTY" ]; then
+        echo "UNCOMMITTED: .claude/ or CLAUDE.md has changes that are not committed:"
+        printf '%s\n' "$DIRTY" | sed 's/^/    /' | head -n 20
+        [ "$(printf '%s\n' "$DIRTY" | wc -l | tr -d ' ')" -gt 20 ] && echo "    …"
+        echo "The update rewrites Crewforth's files under .claude/. Commit or stash first, or go ahead knowingly."
+      elif [ -n "$UNTR" ]; then
+        echo "NOT IN GIT:$UNTR — gitignored here, so uncommitted changes cannot be detected. The update replaces Crewforth's"
+        echo "files under .claude/ (CLAUDE.md and project skills are kept); edits made to Crewforth files there are overwritten."
+      else
+        echo "clean: no uncommitted changes in .claude/ or CLAUDE.md"
+      fi
+    else
+      echo "not a git repository: nothing to compare against — the file list after the update is the record"
+    fi
+    mkdir -p .claude/.state 2>/dev/null
+    snapshot > "$SNAP" || { echo "update-guard: could not write $SNAP" >&2; exit 1; }
+    ;;
+  post)
+    [ -f "$SNAP" ] || { echo "update-guard: no snapshot — run \`update-guard.sh pre\` before the update" >&2; exit 2; }
+    # One tagged line per path (A added · C changed · M moved · R removed), sorted, then printed as four lists.
+    OUT="$(snapshot | awk '
+      FNR==NR { p=$0; sub(/^[^ ]+ [^ ]+ /,"",p); old[p]=$1" "$2; next }
+      { p=$0; sub(/^[^ ]+ [^ ]+ /,"",p); new[p]=$1" "$2 }
+      END {
+        for (p in new) if (!(p in old)) added[p]=new[p]; else if (old[p]!=new[p]) print "C\t" p
+        for (p in old) if (!(p in new)) removed[p]=old[p]
+        # a move: gone from one path, the same bytes at another — only when those bytes are unambiguous on both
+        # sides (one removed and one added file carry them) and not empty; otherwise it stays removed + added.
+        for (r in removed) nr[removed[r]]++
+        for (a in added) na[added[a]]++
+        for (r in removed) if (nr[removed[r]]==1 && removed[r] !~ / 0$/) for (a in added) if (added[a]==removed[r] && na[added[a]]==1) { moved[r]=a; break }
+        for (r in moved) { print "M\t" r " -> " moved[r]; delete removed[r]; delete added[moved[r]] }
+        for (p in added) print "A\t" p
+        for (p in removed) print "R\t" p
+      }' "$SNAP" - | LC_ALL=C sort)"
+    for _t in "A added" "C changed" "M moved" "R removed"; do
+      _k="${_t%% *}"; _l="$(printf '%s\n' "$OUT" | sed -n "s/^$_k	//p")"
+      printf '%s (%s):\n' "${_t#* }" "$(printf '%s' "$_l" | grep -c . || true)"
+      [ -n "$_l" ] && printf '%s\n' "$_l" | sed 's/^/    /'
+    done
+    if [ -s .claude/.state/whats-new.md ]; then
+      echo "what changed: .claude/.state/whats-new.md (the release notes from the installed package's own CHANGELOG)"
+    else
+      echo "what changed: no release notes were extracted (the package carried no CHANGELOG, or nothing is newer)"
+    fi
+    ;;
+  *) echo "usage: update-guard.sh pre|post" >&2; exit 2 ;;
+esac
+exit 0

package/kit/eval/utilization.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# What Crewforth LOADS versus what it actually FIRES.
+#
+# Every installed skill spends its name and description in EVERY session's skill listing, forever, whether or not
+# it is ever used. doctor.sh §4a already measures the loaded half and reports it against the budget. This
+# measures the other half, because the documented remedy for an over-budget listing — setting rarely-used skills
+# to "name-only" in skillOverrides — needs a list of WHICH skills, and nothing produced one. A cold skill is not
+# automatically a bad skill (an incident runbook earns its keep by existing), so this REPORTS and never enforces.
+#
+# Usage:  bash utilization.sh [--all-projects]
+# Exit:   0 always. Measuring context cost must never fail a build.
+#
+# PRIVACY (§4.3): the current project only, unless --all-projects is asked for explicitly. What is printed is
+# skill NAMES and COUNTS — never a path, never the encoded project directory, never a prompt or a file content.
+# Nothing is written anywhere; this script only reads.
+set -uo pipefail
+
+ALL=0
+case "${1:-}" in
+  --all-projects) ALL=1 ;;
+  ""|--help|-h) [ "${1:-}" != "" ] && { sed -n '2,12p' "$0"; exit 0; } ;;
+esac
+
+# Where the skills live: an installed project, or this repo's payload when run from Crewforth's own checkout.
+SKILLS=""; OWNREPO=0
+for d in .claude/skills kit/skills; do [ -d "$d" ] && { SKILLS="$d"; break; }; done
+[ "$SKILLS" = "kit/skills" ] && OWNREPO=1
+if [ -z "$SKILLS" ]; then echo "utilization: no skills directory here (looked for .claude/skills)"; exit 0; fi
+
+TR=""
+# ---- CREW-TRANSCRIPT-DIR (kept byte-identical in context-usage.sh and session-stats.sh; smoke-test §6i3 pins it)
+# Claude Code stores a session under $HOME/.claude/projects/<cwd encoded as a directory name>. Reproducing that
+# encoding is the ONLY way a by-hand call (no hook payload on stdin) can find its own transcript.
+crew_project_dirs(){   # candidate directory names for the current cwd, best first, one per line
+  local w p
+  # Windows first. Claude Code sees the NATIVE cwd (C:\repo\app) while Git Bash's `pwd` reports /c/repo/app, so
+  # the drive letter never matched and the by-hand call could not resolve a transcript on Windows AT ALL — the
+  # same "transcript not found" was reported from that machine three separate times before the cause was found.
+  # `pwd -W` is the MSYS builtin that returns the native form; elsewhere it just fails and is discarded.
+  w="$(pwd -W 2>/dev/null || true)"
+  # The encoder folds : \ / . AND _ to '-'. The underscore is the one that hides: a project named `report_api`
+  # lands in `...-report-api`, so folding only slashes and dots misses every path containing an underscore — on
+  # every platform, not just Windows.
+  for p in "$w" "$(pwd)"; do
+    [ -n "$p" ] && printf '%s\n' "$(printf '%s' "$p" | sed 's#[:\\/._]#-#g')"
+  done
+  # Legacy shapes, kept so a directory written by an older client still resolves.
+  printf '%s\n' "$(pwd | sed 's#[/.]#-#g')" "$(pwd | sed 's#/#-#g')"
+}
+if [ -z "$TR" ]; then
+  while IFS= read -r esc; do
+    [ -n "$esc" ] || continue
+    cand="$(ls -t "$HOME/.claude/projects/$esc"/*.jsonl 2>/dev/null | head -1)"
+    [ -n "$cand" ] && { TR="$cand"; break; }
+  done <<CREWEOF
+$(crew_project_dirs)
+CREWEOF
+fi
+# ---- /CREW-TRANSCRIPT-DIR
+
+# THE TRANSCRIPTS ARE NOT ONE FILE, AND THAT IS THE WHOLE MEASUREMENT. A project directory holds
+# <session>.jsonl at the top AND a <session>/ directory per session whose subagents/ tree carries one transcript
+# per delegated agent. Measured on this machine while writing this: 14 transcripts at the top level, 306 nested.
+# A parser that reads only the top level therefore misses most of the work — and delegated agents are precisely
+# where skills fire, because that is what they are delegated with. Counting only the top level reported 2 of 40
+# skills as used; counting the tree reported 21. The difference is not a rounding error, it is the answer.
+if [ "$ALL" = 1 ]; then
+  DIRS="$HOME/.claude/projects"
+  [ -d "$DIRS" ] || { echo "utilization: NOT MEASURED — no transcripts directory"; exit 0; }
+  SCOPE="all projects"
+else
+  [ -n "$TR" ] || { echo "utilization: NOT MEASURED — no transcript found for this project."
+                    echo "  (a fresh checkout, a first session, or a project directory the encoder cannot reproduce)"
+                    echo "  NOT MEASURED is not the same as 'nothing fired'; it means nothing was read."; exit 0; }
+  DIRS="$(dirname "$TR")"
+  SCOPE="this project"
+fi
+
+# One grep over the tree, not one per skill: 40 greps × 320 files is the cost pattern Crewforth keeps removing.
+#
+# TWO SHAPES COUNT AS A FIRING, and only these two:
+#   "file_path":"…/skills/<name>/SKILL.md"   — the skill was READ (how a skill is actually consumed)
+#   "name":"Skill","input":{"skill":"<name>" — the Skill tool was invoked by name
+# THE ANCHOR IS THE POINT. Matching a bare skill name anywhere in the JSON would count Crewforth measuring itself:
+# a single `grep -rn description: skills/` tool result echoes all 40 paths on one line, and every skill would
+# report as used forever. Both patterns above require the name to sit in a position only a real invocation puts
+# it in. Lines carrying "is_error":true are dropped first — a read that failed is not a use. That drop is
+# line-level, so it catches the error record itself; correlating a failed result back to its own tool_use id
+# would need a second pass over every line, and a Read of a file that is installed rarely fails.
+HITS="$(grep -rhI --include='*.jsonl' -e '"file_path":"' -e '"name":"Skill"' "$DIRS" 2>/dev/null \
+        | grep -v '"is_error":true' \
+        | grep -ohE '/skills/[A-Za-z0-9._-]+/SKILL\.md|"name":"Skill","input":\{"skill":"[A-Za-z0-9._-]+"' 2>/dev/null \
+        | sed -e 's#^/skills/##' -e 's#/SKILL\.md$##' -e 's#.*"skill":"##' -e 's#"$##' \
+        | sort | uniq -c | sort -rn)"
+
+FIRED=0; COLD=0; COLDLIST=""; COLDBYTES=0; FIREDLIST=""
+for f in "$SKILLS"/*/SKILL.md; do
+  [ -e "$f" ] || continue
+  n="$(basename "$(dirname "$f")")"
+  c="$(printf '%s\n' "$HITS" | awk -v s="$n" '$2==s {print $1; exit}')"
+  if [ -n "$c" ]; then
+    FIRED=$((FIRED+1)); FIREDLIST="$FIREDLIST  $n($c)"
+  else
+    COLD=$((COLD+1)); COLDLIST="$COLDLIST  $n"
+    b="$(awk '/^---$/{k++; next} k==1' "$f" | awk '/^(name|description):/,0' | wc -c | tr -d ' ')"
+    COLDBYTES=$((COLDBYTES + b))
+  fi
+done
+TOTAL=$((FIRED+COLD))
+[ "$TOTAL" -gt 0 ] || { echo "utilization: NOT MEASURED — no skills installed"; exit 0; }
+
+NSESS="$(find "$DIRS" -name '*.jsonl' 2>/dev/null | wc -l | tr -d ' ')"
+echo "== skill utilization ($SCOPE, $NSESS transcript file(s)) =="
+echo "  fired : $FIRED/$TOTAL"
+echo "  cold  : $COLD/$TOTAL   (${COLDBYTES} B of always-on listing spent on skills nothing reached)"
+[ -n "$FIREDLIST" ] && { echo "  --- fired (times reached) ---"; printf '%s\n' "$FIREDLIST" | tr ' ' '\n' | grep -v '^$' | sort | paste -sd' ' - | fold -s -w 100 | sed 's/^/    /'; }
+[ -n "$COLDLIST" ]  && { echo "  --- cold ---";                  printf '%s\n' "$COLDLIST"  | tr ' ' '\n' | grep -v '^$' | sort | paste -sd' ' - | fold -s -w 100 | sed 's/^/    /'; }
+echo "  ---"
+# Crewforth's own repository is the one place where this number lies, so it says so rather than being quoted out
+# of context later. Here a SKILL.md is opened to EDIT it, and an edit is indistinguishable from an invocation at
+# the transcript level — both are a Read of the same path. In a project that USES Crewforth there is no such
+# traffic, which is the case the measurement is for.
+[ "$OWNREPO" = 1 ] && {
+  echo "  NOTE: read from Crewforth's OWN repository, where a SKILL.md is opened to be EDITED. Those edits are"
+  echo "  indistinguishable from invocations here, so 'fired' is inflated. Run this in a project that USES the"
+  echo "  Crewforth for a number that means what it says."
+  echo "  ---"; }
+echo "  A cold skill is not a bad skill — a runbook earns its place by existing. This is the evidence for the"
+echo "  skillOverrides \"name-only\" decision doctor.sh §4a asks you to make, not the decision itself."
+exit 0

package/kit/hooks/board-sync.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# SessionStart hook — put the TEAM's state into a session that would otherwise only know its own.
+#
+# The problem it closes: every teammate runs Crewforth locally, so "Ali took item #1 two hours ago" exists
+# nowhere this session can see. This hook injects the board summary at the start of every session, which is the
+# one moment the answer changes what happens next: which item to pick up, which one is blocked, which claim has
+# gone quiet.
+#
+# Deliberate scope:
+#   - Same event and channel as session-rehydrate.sh: SessionStart + hookSpecificOutput.additionalContext is the
+#     documented way to put text into the model's context.
+#   - Matched on startup|resume|clear|compact. Unlike the handover hook this DOES include `startup`: a stale
+#     handover nags, but "who holds what right now" is exactly what a fresh session is missing.
+#   - NO NETWORK IN THE FOREGROUND. The visible half reads one cache file and exits. When that cache is older
+#     than CREW_BOARD_MAX_AGE the hook starts a DETACHED refresher (fetch + heartbeat) whose result is used by the
+#     NEXT session. On an unreachable remote the session-start cost stays at zero.
+#   - Fails OPEN and SILENT: no repo, no board, no cache -> no output, exit 0. It never blocks a session.
+set -uo pipefail
+# The 2.x names of the variables a user can set still work (one helper: eval/lib/crew-env.sh).
+_crew_d="${BASH_SOURCE%/*}"; [ "$_crew_d" = "${BASH_SOURCE}" ] && _crew_d=.
+[ -f "$_crew_d/../eval/lib/crew-env.sh" ] && . "$_crew_d/../eval/lib/crew-env.sh"; unset _crew_d
+
+# Two intervals, because two very different repos run this hook. Where a board exists, 15 minutes keeps the view
+# worth acting on. Where none does — every solo project, and every install that upgraded into this feature — the
+# only thing a refresh can do is ask the remote for a ref nobody has created, so it backs off to once a day.
+# Without that split, a repo that will never have a board opened a background fetch at every session start.
+MAX_AGE="${CREW_BOARD_MAX_AGE:-900}"
+MAX_AGE_NOBOARD="${CREW_BOARD_MAX_AGE_NOBOARD:-86400}"
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SELF="$HERE/$(basename "$0")"
+
+# ---- detached half: the only place this hook is allowed to touch the network -----------------------------------
+if [ "${1:-}" = "--refresh" ]; then
+  cd "${2:-.}" 2>/dev/null || exit 0
+  bash "$HERE/board.sh" sync >/dev/null 2>&1 || exit 0
+  bash "$HERE/board.sh" beat >/dev/null 2>&1 || true
+  exit 0
+fi
+
+# ---- foreground half: one file read, then a decision -----------------------------------------------------------
+[ -n "${CREW_NO_BOARD:-}" ] && exit 0
+
+IN=""
+[ ! -t 0 ] && IN="$(cat 2>/dev/null || true)"
+ROOT="${CLAUDE_PROJECT_DIR:-}"
+[ -n "$ROOT" ] || ROOT="$(printf '%s' "$IN" | sed -n 's/.*"cwd"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)"
+[ -n "$ROOT" ] || ROOT="$PWD"
+# Windows hands this over as a native path and the stdin copy arrives JSON-encoded on top (`C:\\Repos\\app`).
+# Undo the escaping, then fold the separators; both are no-ops on POSIX.
+ROOT="${ROOT//\\\\//}"; ROOT="${ROOT//\\//}"
+
+cd "$ROOT" 2>/dev/null || exit 0
+GITDIR="$(git rev-parse --git-common-dir 2>/dev/null)" || exit 0
+[ -n "$GITDIR" ] || exit 0
+
+CACHE="$GITDIR/crew-board-cache"
+STAMP=0
+[ -f "$CACHE.at" ] && STAMP="$(tr -cd '0-9' < "$CACHE.at" 2>/dev/null)"
+[ -n "$STAMP" ] || STAMP=0
+
+# A non-empty cache means a board was found here; an absent or empty one means there is nothing to keep fresh.
+# Costs no extra process: the same test decides, below, whether there is anything to say.
+[ -s "$CACHE" ] || MAX_AGE="$MAX_AGE_NOBOARD"
+
+NOW="$(date -u +%s 2>/dev/null || echo 0)"
+if [ "$NOW" -gt 0 ] && [ "$((NOW - STAMP))" -gt "$MAX_AGE" ]; then
+  # stdin/stdout/stderr all detached: an inherited stdout keeps the hook's pipe open after it exits, and the
+  # caller then waits to EOF on a fetch that has nothing to do with it.
+  bash "$SELF" --refresh "$ROOT" </dev/null >/dev/null 2>&1 &
+fi
+
+# Never invent a board state. No cache (no board here, or every refresh so far failed) -> stay silent.
+[ -s "$CACHE" ] || exit 0
+
+# /crew-board is user-only, so the command Claude can run itself comes first (the plugin's copy names its path).
+if [ -f "$HERE/../.claude-plugin/plugin.json" ]; then _BS="bash \"$HERE/board.sh\" sync"; else _BS='bash .claude/hooks/board.sh sync'; fi
+MSG="$(cat "$CACHE")
+Board state above is a cached snapshot; $_BS (or the user can type /crew-board sync) refreshes it."
+
+# ONE PATH, no jq. The JSON is built here on every machine, so a Mac with jq and a Windows box without it emit the
+# same bytes. The escaper is jq-identical, measured on 15 inputs (quote, backslash, tab, CR, C0 controls, DEL,
+# UTF-8, leading/trailing newlines, 5000 chars): 15/15 equal to `jq -cn --arg m`. The one it replaced escaped only
+# the quote, the backslash and the newline, so a tab in an item title produced JSON the CLI cannot parse
+# (measured: jq rc=5) and the board silently vanished from the session — on exactly the no-jq machine this
+# branch existed for. The trailing newline on the printf closes the last record, so a value ending in a newline
+# keeps it. One awk, no subshell per character. A CR that ENDS a line is dropped on purpose: it is a CRLF line
+# ending, not content, and MSYS gawk already drops it on read (text mode) while BSD awk keeps it — measured on
+# Windows. Stripping it here makes every OS emit the same bytes; a CR inside a line is still escaped as \r.
+ESC="$(printf '%s\n' "$MSG" | LC_ALL=C awk 'BEGIN { ORS = ""
+    for (i = 1; i < 32; i++) ctl[i] = sprintf("%c", i)
+    nm[8] = "\\b"; nm[9] = "\\t"; nm[12] = "\\f"; nm[13] = "\\r" }
+  NR > 1 { print "\\n" }
+  { s = $0; sub(/\r$/, "", s)
+    gsub(/\\/, "\\\\", s); gsub(/"/, "\\\"", s)
+    for (i = 1; i < 32; i++) {
+      if (i == 10 || !index(s, ctl[i])) continue
+      r = (i in nm) ? nm[i] : sprintf("\\u%04x", i)
+      out = ""; while ((p = index(s, ctl[i])) > 0) { out = out substr(s, 1, p - 1) r; s = substr(s, p + 1) }
+      s = out s
+    }
+    d = sprintf("%c", 127)
+    if (index(s, d)) { out = ""; while ((p = index(s, d)) > 0) { out = out substr(s, 1, p - 1) "\\u007f"; s = substr(s, p + 1) }; s = out s }
+    print s }')"
+printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$ESC"
+exit 0