#!/usr/bin/env bash # Kit smoke-test: structural validation (without running Claude Code). # Usage: bash .claude/eval/smoke-test.sh (from the repo root or from inside .claude/eval) set -uo pipefail HERE="$(cd "$(dirname "$0")" && pwd)" ROOT="$(cd "$HERE/.." && pwd)" # .claude/ AGENTS="$ROOT/agents"; SKILLS="$ROOT/skills"; HOOKS="$ROOT/hooks" FAIL=0; PASSN=0; SKIPN=0; SKIP_HARD=0; SKIP_LIST="" pass(){ PASSN=$((PASSN+1)); echo " ✅ $1"; } fail(){ FAIL=$((FAIL+1)); echo " ❌ $1"; } # A VERDICT WITHOUT A DENOMINATOR IS NOT A VERDICT. This suite printed one line — "SMOKE-TEST: PASSED ✅" — and # it printed the identical line whether 574 assertions ran or 293 did (CSK_SMOKE_SCOPE=install drops the rest). # Worse, seventeen places reported a test that DID NOT RUN as a green ✅, so "a tool is missing here" and "the # gate holds" were the same output. Both are now counted and named, and the reason is classified because the # classes mean different things: # tool — jq/git/curl/a jq-less PATH is unavailable. In CI that is a broken runner, not a fact of life. # fixture — the case could not build its own fixture. Same: in CI it means the fixture rotted. # scope — the case does not apply to what is being tested (an installed project has no plugin/ or start.sh). # platform — the platform genuinely cannot express the case (Git Bash keeps shebang scripts executable). # Only the first two turn CI red; the other two are honest answers everywhere. Locally nothing fails, because a # developer without jq should still get a usable run — the asymmetry IS the design, not an oversight. skip(){ # $1 = tool|fixture|scope|platform, $2 = what was not checked SKIPN=$((SKIPN+1)); SKIP_LIST="$SKIP_LIST [$1] $2" case "$1" in tool|fixture) SKIP_HARD=$((SKIP_HARD+1)) ;; esac echo " ⏭ [$1] $2 — NOT CHECKED" } # The reporter is itself a gate now, so it gets measured like one — in a subshell, so the real counters are not # disturbed. Three states: a tool-class skip must arm the CI failure, a scope-class skip must not, and neither # may be counted as a pass. Without this the asymmetry is a claim in a comment. _sk_probe(){ ( SKIPN=0; SKIP_HARD=0; PASSN=0; SKIP_LIST=""; skip "$1" probe >/dev/null; printf '%s %s %s' "$SKIPN" "$SKIP_HARD" "$PASSN" ); } [ "$(_sk_probe tool)" = "1 1 0" ] && pass "a tool-class skip is counted and arms the CI failure" || fail "skip tool did not arm the CI failure: $(_sk_probe tool)" [ "$(_sk_probe fixture)" = "1 1 0" ] && pass "a fixture-class skip arms the CI failure too" || fail "skip fixture did not arm the CI failure: $(_sk_probe fixture)" [ "$(_sk_probe scope)" = "1 0 0" ] && pass "a scope-class skip is counted but does NOT fail CI" || fail "skip scope wrongly armed the CI failure: $(_sk_probe scope)" [ "$(_sk_probe platform)" = "1 0 0" ] && pass "a platform-class skip is counted but does NOT fail CI" || fail "skip platform wrongly armed the CI failure: $(_sk_probe platform)" # Kit repo (payload) vs an INSTALLED project. Kit conventions (Trigger phrases, byte budget) are GATES on the # payload but must not fail a user's project for their OWN agents/skills — including the ones adopt imports from a # taken-over agent. In an install those become a report (note), not a failure. Kit repo has CLAUDE.md next to the # discipline; an install has DISCIPLINE.md instead. IS_KIT=0; [ -f "$ROOT/CLAUDE.md" ] && IS_KIT=1 note(){ echo " · $1"; } # informational; never counts as a failure # Scope. Declared HERE rather than beside the block it first guards, because it now gates cases that run # EARLIER than that block — see §6h. Reading an env var costs nothing; the note stays where the big skip is. UNITS=1; [ "${CSK_SMOKE_SCOPE:-full}" = install ] && UNITS=0 # Trigger-phrases requirement: a GATE in the kit repo, a note in an installed project (your skills, your call). need_trigger(){ if kit_owned "${2:-}"; then fail "$1"; else note "$1 (your own skill/agent; not gated in an install)"; fi; } # ---- the JSON oracle: a parser chosen by whether it WORKS, not whether its name resolves --------------------- # Several gates below check JSON the kit ITSELF produced. Validating generated JSON with the same hand-rolled # bash slicing that generated it proves nothing, so those gates want an independent parser — and they asked for # one by name: `command -v jq`. On Windows that question has a wrong answer waiting, and this branch already # paid for it once. Microsoft ships a `python3` on PATH by default that is a Store redirector stub: it resolves, # writes to stderr and exits 49 with empty stdout. Three tool-level guards trusted `command -v` and fell open on # every Windows machine. The rule that came out of that fix is the rule here — PROBE the tool, never ask whether # the name resolves. # # So this is a LADDER, not a name: jq first (its expressions are terser), then a real python3, then python. Each # candidate must actually parse a document before it is accepted, which is what keeps the Store stub out. When # none of them parses, JSONQ stays empty and the gates that need an oracle skip as class `tool` — which arms the # CI failure, because a runner carrying no JSON parser at all is a broken runner, not an exemption. # # Why it matters that this is a ladder and not just jq: the runner images carry jq, a real user's Git Bash # usually does not. Measured on a Windows 11 desktop with no jq — 619 assertions graded against 633 on # windows-latest. Fourteen checks differ, and only TWO of them announce themselves as skips; the rest are # `if jq` blocks with no else, so they simply do not run and nothing says so. JSONQ="" for _jc in jq python3 python; do command -v "$_jc" >/dev/null 2>&1 || continue if [ "$_jc" = jq ]; then printf '{}' | jq -e . >/dev/null 2>&1 && { JSONQ=jq; break; } else printf '{}' | "$_jc" -c 'import sys,json;json.load(sys.stdin)' >/dev/null 2>&1 && { JSONQ="$_jc"; break; } fi done unset _jc json_ok(){ # stdin parses as JSON — the `jq empty` question. rc 2 = no oracle available at all. case "$JSONQ" in jq) jq empty >/dev/null 2>&1 ;; "") return 2 ;; *) "$JSONQ" -c 'import sys,json;json.load(sys.stdin)' >/dev/null 2>&1 ;; esac } json_get(){ # $1 = dotted path. Mimics `jq -e`: prints the value as JSON, non-zero when absent, null or false. # The two branches must answer IDENTICALLY, including what they print on a miss — jq prints `null` and exits 1, # so the python branch does too. An oracle whose answer depends on which tier happened to be installed is not # an oracle; it is a second variable in the experiment, and this suite already spent a night on one of those. case "$JSONQ" in jq) jq -e ".$1" 2>/dev/null ;; "") return 2 ;; *) "$JSONQ" -c 'import sys,json d=json.load(sys.stdin) for k in sys.argv[1].split("."): d = d.get(k) if isinstance(d,dict) else None print(json.dumps(d)) sys.exit(1 if (d is None or d is False) else 0)' "$1" 2>/dev/null ;; esac } # The mode is `default` because this case tests PARSING — whether a commit message carrying a tab, an escaped # quote and a Windows path survives into the §4.4 ask — not policy. It used to say `auto`, which was incidental # until `auto` moved to the fail-closed branch and there was no "ask" left to inspect. Three sibling cases were # moved for exactly this reason when that branch changed; this one was missed because it only runs where a JSON # oracle exists, and on the machine where the change was made there is none — jq absent, python3 a Store stub. # So the case that pins the parser could not report the policy change that broke it. Same shape as the rest of # this suite's history: the check that does not run is the check that goes wrong. json_bash_payload(){ # $1 = command string -> a valid PreToolUse Bash payload carrying it VERBATIM. # The point of building it with a real serialiser is that the fixture must be valid even when the command # carries tabs, quotes and backslashes — hand-escaping it here would be testing our escaping with our escaping. case "$JSONQ" in jq) jq -nc --arg c "$1" '{tool_name:"Bash",permission_mode:"default",tool_input:{command:$c}}' ;; "") return 2 ;; *) "$JSONQ" -c 'import sys,json print(json.dumps({"tool_name":"Bash","permission_mode":"default","tool_input":{"command":sys.argv[1]}}))' "$1" ;; esac } # ---- what the gates are allowed to see, and whose fault a failure is ----------------------------------------- # Two questions the suite had been answering by DIRECTORY, which is why a real defect walked through both. # # 1) Which agent files get their own quality gated? Everything in agents/, PLUS the swap-in variants in # agents-optional/ that the installer moves INTO agents/ on a generic backend. backend-expert-generic.md is as # much a kit agent as any other, and it was reached by exactly one of nine checks because it sits one # directory over — which is how it came to ship with no auto-delegation cue, the very defect the cue check # exists to catch. NOT used by the checks that reason about the INSTALLED SET (agent count, always-on byte # budget, orphan routing): a swap-in replaces its counterpart rather than adding to it, and it is routed # under the name it takes once installed. agent_quality_files() { ls "$AGENTS"/*.md 2>/dev/null [ "$IS_KIT" = 1 ] && ls "$ROOT/agents-optional"/*.md 2>/dev/null return 0 } # 2) Is a component one the KIT shipped? .claude/kit-manifest.txt records exactly that (written by start.sh and # adopt.sh since 1.8.0). The "not gated in an install" escapes exist so a project's OWN agents and skills are # never failed by kit conventions — but with no ownership test they also excused the kit's own, and the suite # printed a green line saying so: "some agents lack a proactive cue: backend-expert-csk (your project's own # agents, not gated)". No manifest -> stay lenient; absence of evidence is not ownership. kit_owned() { # $1 = manifest entry, e.g. agents/backend-expert-csk.md or skills/a11y [ "$IS_KIT" = 1 ] && return 0 [ -n "${1:-}" ] || return 1 # no id to check -> lenient; never let "" match a blank line [ -f "$ROOT/kit-manifest.txt" ] || return 1 # no manifest -> lenient; absence of evidence is not ownership grep -qxF "$1" "$ROOT/kit-manifest.txt" } echo "== 1) Agent frontmatter & trigger ==" AC=0 for f in $(agent_quality_files); do n=$(basename "$f") case "$f" in "$AGENTS"/*) AC=$((AC+1)) ;; esac # count the installed set only; a swap-in is not an addition grep -q '^name:' "$f" || fail "$n: no name" grep -q '^tools:' "$f" || fail "$n: no tools" # `model:` is OPTIONAL and omitting it is the good default — the docs say an omitted field means `inherit`, # i.e. the model the user picked for the session. What was never checked is the VALUE, and an unrecognised # one does not error: Claude Code skips it and runs the inherited model, so a typo looks like it worked. MV="$(sed -n 's/^model:[[:space:]]*//p' "$f" | head -1 | tr -d ' \r')" if [ -n "$MV" ]; then case "$MV" in sonnet|opus|haiku|fable|inherit|claude-*) : ;; *) fail "$n: model '$MV' is not a documented value (sonnet·opus·haiku·fable·inherit·claude-*) — it will silently fall back to inherit" ;; esac fi EV="$(sed -n 's/^effort:[[:space:]]*//p' "$f" | head -1 | tr -d ' \r')" if [ -n "$EV" ]; then case "$EV" in low|medium|high|xhigh|max) : ;; *) fail "$n: effort '$EV' is not a documented level (low·medium·high·xhigh·max)" ;; esac fi grep -q 'Trigger phrases:' "$f" || need_trigger "$n: no Trigger phrases" "agents/$n" done # The mandatory audit agents must NOT be pinned to a model. Omitted means inherit, so a pin can only make the # gate that CLEARS a change run on a different tier from the agent that wrote it — and for 156 commits both of # these said `sonnet`, so an Opus session reviewed Opus-written code on Sonnet. That is backwards for the one # review the kit calls mandatory, and Claude Code's own built-in Explore states the opposite rule: inherit, # capped upward, never forced down. Buy rigour with `effort:`, which raises thinking on the user's own model. for a in security-expert-csk privacy-agent-csk; do [ -f "$AGENTS/$a.md" ] || continue if grep -qE '^model:' "$AGENTS/$a.md"; then if kit_owned "agents/$a.md"; then fail "$a pins a model — a mandatory audit must inherit the session's model, never a fixed tier" else note "$a pins a model (your install, your call — the kit ships it unpinned so the audit is never weaker than the session)"; fi else pass "$a inherits the session model (the mandatory audit is never weaker than what wrote the code)" fi done # Since 2.0 every install ships every agent, so the count no longer varies by install shape. It is still not # asserted as a fixed number: adopt.sh's `keepmine` mode legitimately leaves a kit agent out when the project # already owns that role, and a brownfield adopt is exactly the case this suite must not fail. The floor is the # core seven, which no mode may drop. for c in planner-csk security-expert-csk privacy-agent-csk test-expert-csk review-agent-csk commit-agent-csk session-manager-csk; do [ -f "$AGENTS/$c.md" ] || fail "missing core agent: $c" done [ "$AC" -ge 7 ] && pass "$AC agents found (7 core complete)" || fail "agent count below the 7 core: $AC" echo "== 2) Skill frontmatter & trigger ==" for d in "$SKILLS"/*/; do n=$(basename "$d"); f="$d/SKILL.md" [ -f "$f" ] || { fail "$n: no SKILL.md"; continue; } grep -q '^name:' "$f" || fail "$n: no name" grep -q 'Trigger phrases:' "$f" || need_trigger "$n: no Trigger phrases" "skills/$n" # Agent-Skills spec limits (agentskills.io/specification) — keep skills portable to any compliant host: # name == parent dir, name ≤ 64 chars, description ≤ 1024 chars. nm="$(awk -F':' '/^name:/{sub(/^name:[[:space:]]*/,"",$0); print; exit}' "$f" | tr -d ' \r')" [ "$nm" = "$n" ] || fail "$n: name '$nm' must equal the parent directory (spec)" [ "${#nm}" -le 64 ] || fail "$n: name is ${#nm} chars (>64 spec limit)" dl="$(awk 'BEGIN{c=0} /^---$/{c++; next} c==1 && /^description:/{p=1} c==1 && p{print}' "$f" | wc -c | tr -d ' ')" [ "${dl:-0}" -le 1024 ] || fail "$n: description ~$dl bytes (>1024 spec limit)" done pass "$(ls -d "$SKILLS"/*/ | wc -l | tr -d ' ') skills scanned (name==dir · name≤64 · description≤1024)" echo "== 3) Orphan skill reference (agent -> nonexistent skill) ==" # (a) Do the X's in "applies the \`X\` skill" in an agent body exist? for f in $(agent_quality_files); do for ref in $(grep -oE 'applies the `[a-z0-9-]+` skill' "$f" | grep -oE '`[a-z0-9-]+`' | tr -d '`'); do [ -f "$SKILLS/$ref/SKILL.md" ] || fail "$(basename $f): skill '$ref' does not exist" done done # (b) Do the backticked skill names on "Also apply: \`x\` · \`y\` ..." lines also exist? for f in $(agent_quality_files); do al="$(grep -F 'Also apply' "$f" || true)" for ref in $(printf '%s' "$al" | grep -oE '`[a-z0-9-]+`' | tr -d '`'); do [ -f "$SKILLS/$ref/SKILL.md" ] || fail "$(basename $f): 'Also apply' skill does not exist: $ref" done done pass "agent->skill references (applies + Also apply) checked" # (c) progressive disclosure: a `references/X.md` pointer in a SKILL.md body must resolve to a real file for d in "$SKILLS"/*/; do f="$d/SKILL.md"; [ -f "$f" ] || continue # A pointer may be to this skill's own references/ OR, qualified with a skill name, to another skill's — # `security-scan/references/verify.md`. Cross-skill is legitimate and the kit's single-source-of-truth rule # depends on it: the verifier contract lives in one file and code-review-csk points at it rather than keeping a # second copy to drift. The check stays strict either way — a wrong skill name or a missing file still fails. for ref in $(grep -oE '([a-z0-9-]+/)?references/[A-Za-z0-9_-]+\.md' "$f" | sort -u); do case "$ref" in */references/*.md) case "$ref" in references/*) [ -f "$d/$ref" ] || fail "$(basename "$d"): SKILL.md points to missing $ref" ;; *) [ -f "$SKILLS/$ref" ] || fail "$(basename "$d"): SKILL.md points to missing $ref (cross-skill)" ;; esac ;; esac done done pass "skill references/*.md pointers resolve" echo "== 3b) Orphan component: every skill & agent must be ROUTED (kit invariant, no idle components) ==" # Rule: nothing idle. A skill/agent that only auto-triggers on its own description is "dark" — the orchestrator is # never told to reach it. It is ROUTED when its name appears in an agent body, a command, or the discipline (the # trigger map): CLAUDE.md in the kit repo, DISCIPLINE.md in an install. A cross-link from ANOTHER skill's body does # NOT count (skills/ is not searched). In an install, a user's own un-routed skill is a note, not a failure. CMDS="$ROOT/commands" ROUTE_DOC="$ROOT/CLAUDE.md"; [ -f "$ROUTE_DOC" ] || ROUTE_DOC="$ROOT/DISCIPLINE.md" # match NAME delimited by a non-[a-z0-9-] char on both sides, so `frontend` does not match inside frontend-design. # Names always appear inside backticks / table cells / prose (never bare at line start/end), so the two delimiters # always exist — which lets us avoid the `(^|…)`/`(…|$)` line-anchor alternation that ugrep matches unreliably. routed(){ local nm="$1"; shift; grep -rqE "[^a-z0-9-]$nm[^a-z0-9-]" "$@" 2>/dev/null; } for d in "$SKILLS"/*/; do n=$(basename "$d") routed "$n" "$AGENTS" "$CMDS" "$ROUTE_DOC" && continue if kit_owned "skills/$n"; then fail "orphan skill '$n': no agent/command/discipline routes to it" else note "skill '$n' not routed by the kit discipline (your own skill? route it from ./CLAUDE.md)"; fi done # agents route from a command or the discipline (exclude the agent's own file: don't search $AGENTS) for f in "$AGENTS"/*.md; do a=$(basename "$f" .md) routed "$a" "$CMDS" "$ROUTE_DOC" && continue if kit_owned "agents/$a.md"; then fail "orphan agent '$a': no command/discipline routes to it" else note "agent '$a' not routed by the kit discipline"; fi done pass "every skill & agent is routed (no idle components)" echo "== 3b2) Capability: a skill cannot demand a tool its agent does not have ==" # A rule an agent physically cannot obey is worse than no rule: it does not fail, it degrades quietly into the # thing it forbids. `privacy-compliance` told its agent to CHECK THE OFFICIAL SOURCE rather than decide from # memory, and privacy-agent-csk shipped with Read/Grep/Glob — no WebFetch. Nothing flagged it. It surfaced in a # real regulatory audit, where the routing had to split the work by hand to get around a gap in the kit. # # So the requirement is declared in the skill (``) and checked here against every agent # that applies it. Declaration rather than guesswork: inferring "this skill probably needs the web" from prose # would be a heuristic, and a gate built on a heuristic is a gate nobody trusts when it fires. CAPFAIL="" for d in "$SKILLS"/*/; do sname="$(basename "$d")" req="$(sed -n 's/.*Requires-tool:[[:space:]]*\([A-Za-z]*\).*/\1/p' "$d/SKILL.md" 2>/dev/null | head -1)" [ -n "$req" ] || continue found=0 for af in "$AGENTS"/*.md; do [ -e "$af" ] || continue grep -qE "[^a-z0-9-]$sname([^a-z0-9-]|$)" "$af" 2>/dev/null || continue # this agent applies the skill found=1 grep -m1 '^tools:' "$af" | grep -q "$req" \ || CAPFAIL="$CAPFAIL $(basename "$af" .md)(needs $req for $sname)" done [ "$found" = 1 ] || note "skill '$sname' declares Requires-tool: $req but no agent applies it" done [ -z "$CAPFAIL" ] && pass "every skill's declared tool requirement is met by the agents that apply it" \ || fail "an agent applies a skill it cannot obey:$CAPFAIL" echo "== 3c) Backend variant parity: a --generic install must not lose routing ==" # On a non-.NET stack the installer REPLACES backend-expert-csk with agents-optional/backend-expert-generic. # Every skill routed only from the .NET variant then silently stops being reached on that stack — §3b cannot see # it, because the skill is still routed by *some* agent. The pattern skill is the one legitimate difference. if [ "$IS_KIT" = 1 ] && [ -f "$AGENTS/backend-expert-csk.md" ] && [ -f "$ROOT/agents-optional/backend-expert-generic.md" ]; then PATTERN_SKILL="devarch-module" # .NET-only by definition; the generic variant must NOT carry it MISSING="" for d in "$SKILLS"/*/; do n=$(basename "$d"); [ "$n" = "$PATTERN_SKILL" ] && continue routed "$n" "$AGENTS/backend-expert-csk.md" || continue routed "$n" "$ROOT/agents-optional/backend-expert-generic.md" || MISSING="$MISSING $n" done [ -z "$MISSING" ] && pass "the generic backend variant routes everything the .NET one does (bar $PATTERN_SKILL)" \ || fail "a --generic install loses routing to:$MISSING — add it to agents-optional/backend-expert-generic.md" routed "$PATTERN_SKILL" "$ROOT/agents-optional/backend-expert-generic.md" \ && fail "the generic backend variant references $PATTERN_SKILL — that skill is pruned on a generic install" \ || pass "the generic variant does not reference the .NET-only pattern skill" else skip scope "backend variant parity skipped (installed project — agents-optional/ is not installed)" fi echo "== 4) Stub / unfilled skill leftover ==" if grep -rlq "to be filled\|generated from source" "$SKILLS" 2>/dev/null; then fail "stub marker still present"; else pass "no stub" fi echo "== 5) Trace + secret scanner ready? ==" [ -x "$HOOKS/pre-commit" ] && pass "pre-commit hook +x" || fail "pre-commit missing/not executable" [ -f "$HOOKS/trace-blocklist.txt" ] && pass "trace-blocklist present" || fail "trace-blocklist.txt missing" [ -f "$HOOKS/secret-blocklist.txt" ] && pass "secret-blocklist present" || fail "secret-blocklist.txt missing" # secret scan (behavioral): a staged fake AWS key MUST be blocked by pre-commit (key split in source so THIS file is clean) SDIR="$(mktemp -d)" ( cd "$SDIR" && git init -q && git config user.email x@x.x && git config user.name x \ && cp "$HOOKS/pre-commit" "$HOOKS/trace-blocklist.txt" "$HOOKS/secret-blocklist.txt" . \ && printf 'aws_key = AKIA%s\n' 'IOSFODNN7EXAMPLE' > leak.txt && git add leak.txt ) >/dev/null 2>&1 if ( cd "$SDIR" && bash pre-commit ) >/dev/null 2>&1; then fail "secret scan LET a staged key through"; else pass "secret scan BLOCKED a staged AWS key"; fi rm -rf "$SDIR" echo "== 5b) Team board: is the claim a real lock, or only a convention? ==" # SCOPED, and this one is the whole cost. Measured on a Windows 11 desktop: this section alone is 682 s of # the 892 s an install-scope suite takes -- 76% of it -- and e2e runs that suite three times, so it is roughly # 34 of the 37 minutes the e2e step spends on windows-latest. What it drives is board.sh (12x) and # guard-write.sh (4x) against fixture clones; it reads no kit.conf, no manifest, no VERSION, no settings.json # and no agents/ or skills/ directory, so an installer cannot change its outcome -- it re-proves identical # bytes, which is exactly what the scope split exists to stop. Full scope still runs it, and full scope is what # the standalone CI step and every local run use. if [ "$UNITS" = 1 ]; then # BEHAVIOURAL, not structural. The board's entire value rests on one claim: two people cannot take the same # item. That claim is about what git does under a race, so asserting it any way other than by racing two real # clones would be testing the fiction rather than the gate. Every assertion below states what it proves. # # Three states per gate, deliberately: a gate tested only in the state where it should pass is indistinguishable # from a gate that always passes. if [ -x "$HOOKS/board.sh" ]; then BD="$(mktemp -d)" BOARD_OK=1 ( set -e cd "$BD" git init -q --bare origin.git for u in ali ayse; do git clone -q origin.git "$u" 2>/dev/null # A seed commit is not decoration: without it HEAD is unborn, `git rev-parse --abbrev-ref HEAD` answers # "HEAD" for every branch, and the worktree-isolation assertion below would fail for a reason that has # nothing to do with the board. ( cd "$u" && git config user.email "$u@x" && git config user.name "$u" \ && git commit -q --allow-empty -m seed ) done cp "$HOOKS/board.sh" "$HOOKS/commit-msg" "$HOOKS/trace-blocklist.txt" . ( cd ali && bash ../board.sh init >/dev/null \ && bash ../board.sh add 001 "First" >/dev/null \ && bash ../board.sh add 003 "Third" 001 >/dev/null ) ( cd ayse && bash ../board.sh sync >/dev/null ) ) >/dev/null 2>&1 || BOARD_OK=0 if [ "$BOARD_OK" = 0 ]; then fail "board fixture could not be built (init/add/sync failed)" else # 1. THE RACE. Ali claims, then Ayse claims the same item from her own clone. Exactly one must own it. ( cd "$BD/ali" && bash ../board.sh claim 001 ) >/dev/null 2>&1; A_RC=$? ( cd "$BD/ayse" && bash ../board.sh claim 001 ) >/dev/null 2>&1; B_RC=$? if [ "$A_RC" = 0 ] && [ "$B_RC" != 0 ]; then pass "claim race: first wins, second is REFUSED (rc $A_RC/$B_RC)" else fail "claim race broken: both sessions think they own #001 (rc $A_RC/$B_RC) — the lock does not hold"; fi OWNER="$(cd "$BD/ayse" && bash ../board.sh sync >/dev/null 2>&1; cd "$BD/ayse" && bash ../board.sh show 001 2>/dev/null | grep -m1 '^owner: ' | cut -d' ' -f2-)" [ "$OWNER" = "ali@x" ] && pass "the remote records exactly one owner (ali@x)" \ || fail "remote owner is '$OWNER', expected ali@x" # 2. DEPENDENCY. #003 depends on #001, which is in_progress -> claiming it must be refused... if ( cd "$BD/ayse" && bash ../board.sh claim 003 ) >/dev/null 2>&1 then fail "blocked item #003 was claimable while its dependency was unfinished" else pass "blocked item refused while its dependency is unfinished"; fi # ...and must become claimable the moment the dependency completes. A refusal that never lifts is a deadlock, # not a gate, so both directions are asserted. ( cd "$BD/ali" && bash ../board.sh done 001 "shipped" ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh sync ) >/dev/null 2>&1 if ( cd "$BD/ayse" && bash ../board.sh claim 003 ) >/dev/null 2>&1 then pass "completing the dependency UNBLOCKS the dependent item" else fail "#003 stayed blocked after #001 was completed — dependents never unblock"; fi # 3. HANDOVER IS NOT OPTIONAL. An item released with no note is the failure the board exists to prevent. if ( cd "$BD/ayse" && bash ../board.sh drop 003 ) >/dev/null 2>&1 then fail "drop accepted an EMPTY handover note" else pass "drop refuses an empty handover note"; fi # ...and a drop WITH a note must succeed, put the item back in circulation, and leave the note where the next # person will find it. Without this the refusal above would also pass if drop were simply broken — and ayse # has to end up holding nothing for the write-gate assertions below to mean anything. ( cd "$BD/ayse" && bash ../board.sh drop 003 "stopped at auth/jwt.ts:88; cookie route rejected, mobile drops them" ) >/dev/null 2>&1 HN="$(cd "$BD/ayse" && bash ../board.sh show 003 2>/dev/null | grep -c 'auth/jwt.ts:88')" OW3="$(cd "$BD/ayse" && bash ../board.sh show 003 2>/dev/null | grep -m1 '^owner: ' | cut -d' ' -f2-)" { [ "$HN" -ge 1 ] && [ "$OW3" = "-" ]; } \ && pass "drop with a note releases the item AND stores the handover for whoever picks it up" \ || fail "drop with a note did not release/record correctly (owner='$OW3' note-hits=$HN)" # Re-claimed so the commit-gate block below has an item ayse genuinely holds; the write-gate block releases # it again when it needs the opposite state. Each assertion sets up the state it claims to test. ( cd "$BD/ayse" && bash ../board.sh claim 003 ) >/dev/null 2>&1 # 4. THE COMMIT GATE, in four states. ali holds nothing now (#001 done); ayse holds #003. ( cd "$BD/ayse" && git config core.hooksPath "$BD" ) >/dev/null 2>&1 gate_says(){ printf '%s\n' "$2" > "$BD/msg"; ( cd "$BD/ayse" && bash "$BD/commit-msg" "$BD/msg" ) >/dev/null 2>&1; } gate_says x "feat: work [#003]" && pass "gate ALLOWS a commit naming an item you hold" \ || fail "gate blocked a commit for an item the committer holds" gate_says x "feat: work [#001]" && fail "gate ALLOWED a commit against an item you do not hold" \ || pass "gate BLOCKS a commit naming an item you do not hold" gate_says x "feat: unattributed" && fail "gate ALLOWED a commit naming no item at all" \ || pass "gate BLOCKS a commit naming no item" gate_says x "chore: tidy [chore]" && pass "gate ALLOWS the explicit item-less escape hatch [chore]" \ || fail "gate blocked the documented [chore] escape hatch" # 5. REGRESSION: a repo that never ran init must behave EXACTLY as before this feature existed. A gate that # switches itself on in every repo would break every solo user on upgrade. ( cd "$BD" && git init -q plain && cd plain && git config user.email p@x && git config user.name p ) >/dev/null 2>&1 printf 'feat: no board in this repo, no item id\n' > "$BD/msg" if ( cd "$BD/plain" && bash "$BD/commit-msg" "$BD/msg" ) >/dev/null 2>&1 then pass "no board in the repo -> the claim gate does not exist (no regression for solo users)" else fail "the claim gate fired in a repo with NO board — every existing project would break on upgrade"; fi # 6. The claim must not touch the user's work. Claiming mid-feature with a dirty tree is the normal case. ( cd "$BD/ali" && printf 'dirty\n' > wip.txt && git checkout -q -b feature 2>/dev/null bash ../board.sh add 004 "Fourth" >/dev/null 2>&1; bash ../board.sh claim 004 >/dev/null 2>&1 ) ST="$(cd "$BD/ali" && git status --porcelain 2>/dev/null)" BR="$(cd "$BD/ali" && git rev-parse --abbrev-ref HEAD 2>/dev/null)" if [ "$ST" = "?? wip.txt" ] && [ "$BR" = feature ]; then pass "claiming leaves the worktree and branch untouched (dirty file and branch survive)" else fail "claiming disturbed the worktree/branch (status='$ST' branch='$BR')"; fi # 5a-ii. A REFUSAL IS THE ONLY EVIDENCE THE LOCK EVER FIRED — and it used to leave none. The message went to # stderr and nowhere else, so "how often did this actually stop a collision?" could not be answered, and would # still not be answerable after a trial because the data would never have existed. An instrument cannot be # fitted after the experiment. Both refusal reasons are asserted, and that the record is on the BOARD rather # than in one clone — a count only its author can see answers nothing about a team. ( cd "$BD/ayse" && bash ../board.sh sync ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh claim 001 ) >/dev/null 2>&1 # held by ali -> refused ( cd "$BD/ali" && bash ../board.sh sync ) >/dev/null 2>&1 RLOG="$(git -C "$BD/ali" cat-file -p refs/csk/board:refusals.log 2>/dev/null)" case "$RLOG" in *"|001|held|"*) pass "a refused claim is recorded on the board, where the whole team can count it" ;; *) fail "the refusal left no trace — the lock's only evidence is unrecorded: [$RLOG]" ;; esac # 5b-ii. THE CLOCK MUST NOT RESTART. Re-claiming an item you already hold used to rewrite `since`, so an item # held all morning read as freshly started — which destroys the two things age is for: telling a teammate how # long it has been held, and letting an abandoned claim go stale. Found by reading a real session where the # timestamp jumped between two views of the same claim. S1="$(cd "$BD/ali" && bash ../board.sh show 004 2>/dev/null | grep -m1 '^since: ')" ( cd "$BD/ali" && bash ../board.sh claim 004 ) >/dev/null 2>&1 S2="$(cd "$BD/ali" && bash ../board.sh show 004 2>/dev/null | grep -m1 '^since: ')" [ -n "$S1" ] && [ "$S1" = "$S2" ] && pass "re-claiming an item you hold preserves how long you have held it" \ || fail "re-claim restarted the clock ('$S1' -> '$S2') — age and staleness both become fiction" # And the age has to be VISIBLE: "who holds it" without "for how long" is not the question a teammate asks. AGEV="$(cd "$BD/ali" && bash ../board.sh status 2>/dev/null | grep -m1 '^#004 ')" case "$AGEV" in *[0-9]m*|*[0-9]h*|*[0-9]d*) pass "status shows how long a held item has been held" ;; *) fail "status prints no claim age for a held item: $AGEV" ;; esac # 5c. CONNECTED WORK. Storing a note is not delivering it: nobody picking up #003 has a reason to go and read # #001. Claiming must hand over what the dependency actually did, at the moment the work starts. ( cd "$BD/ali" && bash ../board.sh add 010 "Downstream" 001 ) >/dev/null 2>&1 REL="$(cd "$BD/ali" && bash ../board.sh claim 010 2>&1)" case "$REL" in *"Connected work"*"#001"*) pass "claiming an item delivers its dependency's completion note unprompted" ;; *) fail "claiming #010 did not surface #001's outcome — connected work stays invisible: $REL" ;; esac # ...and the reverse direction: taking an item must name who is waiting on it, so the outcome gets written # down for them rather than only lived through by its author. ( cd "$BD/ali" && bash ../board.sh add 011 "Upstream" ) >/dev/null 2>&1 ( cd "$BD/ali" && bash ../board.sh add 012 "Waiter" 011 ) >/dev/null 2>&1 REL2="$(cd "$BD/ali" && bash ../board.sh claim 011 2>&1)" case "$REL2" in *"#012"*"waits on this one"*) pass "claiming names the items waiting on it (who your outcome affects)" ;; *) fail "claiming #011 did not name its dependent #012: $REL2" ;; esac # 5c-ii. STARTING WORK ASKS WHAT EVERYONE ELSE IS DOING. The dependency graph only knows the edges somebody # declared, and decisions were announced only at session start — so an item claimed later in the same session # could be started against a constraint the team had already settled, and against work already in flight that # nobody had linked. Both are surfaced at claim time, on an item with NO declared dependency at all. ( cd "$BD/ali" && bash ../board.sh add 020 "Unrelated" ) >/dev/null 2>&1 ( cd "$BD/ali" && bash ../board.sh claim 020 ) >/dev/null 2>&1 ( cd "$BD/ali" && bash ../board.sh note 020 "half-done, parked at lib/x.ts:12" ) >/dev/null 2>&1 ( cd "$BD/ali" && bash ../board.sh decide "Errors return problem+json" "Any endpoint returning a bare string is a bug." "-" ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh sync ) >/dev/null 2>&1 rm -f "$BD/ayse/.git/csk-board-seen" ( cd "$BD/ali" && bash ../board.sh add 021 "Also unrelated" ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh sync ) >/dev/null 2>&1 START="$( cd "$BD/ayse" && bash ../board.sh claim 021 2>&1 )" case "$START" in *"#020"*"is on this now"*) pass "starting an unrelated item still says what teammates are mid-flight on" ;; *) fail "claiming #021 said nothing about work already in flight: $START" ;; esac case "$START" in *DECISION*"problem+json"*) pass "starting work surfaces decisions you have not read yet" ;; *) fail "an unread decision did not reach the moment work started — it can only arrive too late: $START" ;; esac # Hand it back: the write-gate assertions below need this user holding nothing, and a test that leaves state # behind for the next one is how a suite starts passing for the wrong reason. ( cd "$BD/ayse" && bash ../board.sh drop 021 "released by the claim-time awareness assertions" ) >/dev/null 2>&1 # 5d. THE VIEW MUST NOT CONTRADICT ITSELF. `blocked` is stored at add time and never rewritten, so reading it # back printed items as blocked while the same view listed them as claimable. Blockedness is derived now, and # this asserts the invariant rather than the implementation: nothing listed as claimable may read as blocked. SV="$(cd "$BD/ali" && bash ../board.sh status 2>/dev/null)" CLAIMABLE="$(printf '%s' "$SV" | sed -n 's/^Claimable now: //p' | tr -d '#')" CONTRA=0 for cid in $CLAIMABLE; do [ "$cid" = none ] && continue printf '%s' "$SV" | grep -qE "^#$cid +blocked" && CONTRA=1 done [ "$CONTRA" = 0 ] && pass "the status view never marks a claimable item as blocked (state is derived, not stored)" \ || fail "status contradicts itself: an item is listed claimable AND shown blocked" # ...and it must not be stale either. Caught in a real session: the view showed an item as blocked while its # dependency had already landed, and only the claim that followed corrected it — the reader had already been # told there was nothing to pick up. "No network in the foreground" is a rule about hooks that run on every # turn, not about a view somebody asked for by name; a board that lies about who has what is worse than a slow # one. Asserted from the OTHER clone, without an explicit sync, which is exactly how the session hit it. ( cd "$BD/ali" && bash ../board.sh add 030 "Upstream" ) >/dev/null 2>&1 ( cd "$BD/ali" && bash ../board.sh add 031 "Downstream" 030 ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh sync ) >/dev/null 2>&1 # ayse takes a snapshot: #031 is blocked ( cd "$BD/ali" && bash ../board.sh claim 030 ) >/dev/null 2>&1 ( cd "$BD/ali" && bash ../board.sh done 030 "shipped" ) >/dev/null 2>&1 FRESH="$( cd "$BD/ayse" && bash ../board.sh status 2>/dev/null | grep -E '^#031 ' )" case "$FRESH" in *blocked*) fail "status served a stale view: #031 still reads blocked after its dependency completed elsewhere" ;; *) pass "status reflects what another clone just did, without an explicit sync" ;; esac # 5e. DECISIONS REACH PEOPLE. The board carried per-item memory only, so a decision that shapes the whole # project reached the person who made it and nobody else: `adr` writes to docs/adr/ and installs gitignore # docs/. Recording one has to (a) travel to another clone, (b) announce itself at the next session opening of # someone who has not read it, and (c) go quiet once they have — an alert that repeats forever is ignored, # which is the same as not sending it. ( cd "$BD/ali" && bash ../board.sh decide "Refresh tokens travel in a header" "Mobile drops cookies; every client sends X-Tenant on refresh." "001" ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh sync ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh decisions 2>/dev/null | grep -q "Refresh tokens travel in a header" ) \ && pass "a decision recorded by one teammate arrives in another's clone" \ || fail "the decision never reached the second clone — decisions stay as local as the ADRs they replace" rm -f "$BD/ayse/.git/csk-board-seen" ( cd "$BD/ayse" && bash ../board.sh cache 2>/dev/null | grep -q "recorded since you last looked" ) \ && pass "an unread decision announces itself at session start" \ || fail "an unread decision is silent at session start — it arrives after the work it should have changed" ( cd "$BD/ayse" && bash ../board.sh decisions ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh cache 2>/dev/null | grep -q "recorded since you last looked" ) \ && fail "the decision keeps announcing itself after being read — a permanent alert is an ignored one" \ || pass "once read, the decision stops being announced" # First read must not leak a shell error: the marker file does not exist yet, and an input redirect from a # missing file complains BEFORE 2>/dev/null takes effect. That error landed in a session-start hook once. rm -f "$BD/ali/.git/csk-board-seen" ERRTXT="$( cd "$BD/ali" && bash ../board.sh cache 2>&1 >/dev/null )" [ -z "$ERRTXT" ] && pass "reading the board with no seen-marker yet writes nothing to stderr" \ || fail "stderr leak on first read: $ERRTXT" # 6b. THE EARLY GATE. The claim lock settles a contested item in under a second, but it can say nothing about # someone who never claims at all — and catching that at commit time means the duplicated work already exists. # So the FIRST file edit is where it is caught. Asserted in the three states that distinguish a gate from a # blanket block: holding nothing blocks, holding something allows, and no board at all allows. WG='{"tool_name":"Edit","tool_input":{"file_path":"src/app.ts"}}' wg(){ printf '%s' "$WG" | ( cd "$1" && bash "$HOOKS/guard-write.sh" ) >/dev/null 2>&1; } # ali holds #004; ayse is put back to holding nothing, which is the state the block gate is about. ( cd "$BD/ayse" && bash ../board.sh drop 003 "released for the write-gate assertions" ) >/dev/null 2>&1 ( cd "$BD/ayse" && bash ../board.sh cache ) >/dev/null 2>&1 ( cd "$BD/ali" && bash ../board.sh cache ) >/dev/null 2>&1 wg "$BD/ayse" && fail "write gate ALLOWED a first edit while the user held no item" \ || pass "write gate BLOCKS the first edit while you hold no item" wg "$BD/ali" && pass "write gate allows edits once you hold an item" \ || fail "write gate blocked a user who does hold an item" wg "$BD/plain" && pass "no board -> the write gate does not exist either" \ || fail "the write gate fired in a repo with no board" printf '%s' "$WG" | ( cd "$BD/ayse" && CSK_NO_BOARD=1 bash "$HOOKS/guard-write.sh" ) >/dev/null 2>&1 \ && pass "CSK_NO_BOARD=1 is a working escape hatch for item-less work" \ || fail "CSK_NO_BOARD=1 did not release the write gate" # The gate it was bolted onto must still hold: a claim must never become a way to edit the gate scripts. printf '%s' '{"tool_name":"Edit","tool_input":{"file_path":".claude/hooks/guard-bash.sh"}}' \ | ( cd "$BD/ali" && bash "$HOOKS/guard-write.sh" ) >/dev/null 2>&1 \ && fail "holding a board item let the model edit a gate script" \ || pass "the gate-script block still holds for a user who holds an item" # 7. THE FALLBACK PATH. Servers reserve their own ref namespaces and may refuse anything outside # refs/heads|refs/tags. `init` probes for that and falls back to an orphan branch — but only the clone that # ran init learns the answer, so the teammate who merely clones and syncs must resolve it on their own or the # board is invisible to everyone but its author. Simulated with a pre-receive hook that denies hidden refs. FB="$(mktemp -d)" FB_OK=1 ( set -e cd "$FB" git init -q --bare origin.git printf '#!/bin/sh\nwhile read -r o n r; do case "$r" in refs/heads/*|refs/tags/*) ;; *) echo "deny updating a hidden ref" >&2; exit 1;; esac; done\nexit 0\n' > origin.git/hooks/pre-receive chmod +x origin.git/hooks/pre-receive for u in one two; do git clone -q origin.git "$u" 2>/dev/null ( cd "$u" && git config user.email "$u@x" && git config user.name "$u" \ && git commit -q --allow-empty -m seed && git push -q origin HEAD:refs/heads/main ) done cp "$HOOKS/board.sh" . ( cd one && bash ../board.sh init && bash ../board.sh add 001 "First" && bash ../board.sh claim 001 ) ) >/dev/null 2>&1 || FB_OK=0 if [ "$FB_OK" = 0 ]; then fail "board could not be created against a server that refuses custom refs" else RREF="$(cd "$FB/one" && git config --get csk.boardRef 2>/dev/null)" [ "$RREF" = "refs/heads/csk-board" ] && pass "server refuses refs/csk/* -> init falls back to the orphan branch" \ || fail "fallback did not engage (ref recorded: '$RREF')" ( cd "$FB/two" && bash ../board.sh sync ) >/dev/null 2>&1 TREF="$(cd "$FB/two" && git config --get csk.boardRef 2>/dev/null)" [ "$TREF" = "refs/heads/csk-board" ] && pass "a teammate that never ran the probe resolves the fallback ref itself" \ || fail "teammate did not find the fallback board (ref: '$TREF') — the board would be invisible to everyone but its author" if ( cd "$FB/two" && bash ../board.sh claim 001 ) >/dev/null 2>&1 then fail "the lock does not hold on the fallback ref: a claimed item was claimed again" else pass "the lock holds on the fallback ref too (second claim refused)"; fi fi rm -rf "$FB" # 7b. OPT-IN, AND REVERSIBLE. Not every project is a team project, and a team project is not a team project # every day. Two separate claims are asserted here: a repo that never created a board has no gates at all # (covered above), and a repo that HAS one can switch every gate off — including the commit gate. A switch # that silences two gates out of three is worse than no switch, because the third one then looks like a bug. SW="$(mktemp -d)" SW_OK=1 ( set -e cd "$SW" git init -q solo && cd solo && git config user.email s@x && git config user.name s cp "$HOOKS/commit-msg" "$HOOKS/board.sh" "$HOOKS/trace-blocklist.txt" .git/ git config core.hooksPath .git git commit -q --allow-empty -m seed bash "$HOOKS/board.sh" init # no remote at all: a local board, which is a legitimate solo setup bash "$HOOKS/board.sh" add 001 "Task" ) >/dev/null 2>&1 || SW_OK=0 if [ "$SW_OK" = 0 ]; then fail "board init failed in a repo with NO remote (solo, local-only board)" else pass "a repo with no remote gets a local board instead of a push failure" sw_commit(){ # -> 0 if the commit actually landed local b a; b="$(cd "$SW/solo" && git rev-list --count HEAD)" ( cd "$SW/solo" && date -u +%s%N > f.txt 2>/dev/null || date -u +%s > f.txt; git add -A; git commit -q -m "$1" ) >/dev/null 2>&1 a="$(cd "$SW/solo" && git rev-list --count HEAD)"; [ "$a" -gt "$b" ]; } sw_write(){ printf '%s' '{"tool_name":"Edit","tool_input":{"file_path":"x.ts"}}' | ( cd "$SW/solo" && bash "$HOOKS/guard-write.sh" ) >/dev/null 2>&1; } ( cd "$SW/solo" && bash "$HOOKS/board.sh" cache ) >/dev/null 2>&1 sw_commit "feat: unattributed" && fail "board ON: an unattributed commit landed" \ || pass "board ON: the gates are active (unattributed commit refused)" ( cd "$SW/solo" && bash "$HOOKS/board.sh" off ) >/dev/null 2>&1 sw_commit "feat: unattributed" && pass "/board-csk off releases the COMMIT gate" \ || fail "/board-csk off left the commit gate armed — a partial switch is a trap" sw_write && pass "/board-csk off releases the EDIT gate" || fail "/board-csk off left the edit gate armed" [ -f "$SW/solo/.git/csk-board-cache" ] && fail "/board-csk off left the session-start cache behind" \ || pass "/board-csk off leaves nothing for the session hook to announce" ( cd "$SW/solo" && bash "$HOOKS/board.sh" on ) >/dev/null 2>&1 sw_commit "feat: unattributed" && fail "/board-csk on did not re-arm the commit gate" \ || pass "/board-csk on puts every gate back" # The env switch has to reach all three too — it is the "just for this session" form of the same decision. B0="$(cd "$SW/solo" && git rev-list --count HEAD)" ( cd "$SW/solo" && date -u +%s > g.txt; git add -A; CSK_NO_BOARD=1 git commit -q -m "feat: env switch" ) >/dev/null 2>&1 [ "$(cd "$SW/solo" && git rev-list --count HEAD)" -gt "$B0" ] \ && pass "CSK_NO_BOARD=1 releases the commit gate too (session-scoped opt-out)" \ || fail "CSK_NO_BOARD=1 released the edit gate but not the commit gate" fi rm -rf "$SW" # 8. SETUP. One person runs init; everybody else must configure NOTHING. And a team whose board belongs in a # separate repository (shared across repos, or members without push rights to the code) must not have to know # that the setting is a git config key. SR="$(mktemp -d)" SR_OK=1 ( set -e cd "$SR" git init -q --bare boardonly.git git init -q app && cd app && git config user.email s@x && git config user.name s && git commit -q --allow-empty -m seed bash "$HOOKS/board.sh" init --remote ../boardonly.git bash "$HOOKS/board.sh" add 001 "Task" bash "$HOOKS/board.sh" claim 001 ) >/dev/null 2>&1 || SR_OK=0 if [ "$SR_OK" = 0 ]; then fail "init --remote could not put the board in a separate repository" else ( cd "$SR/boardonly.git" && git for-each-ref --format='%(refname)' ) 2>/dev/null | grep -q csk \ && pass "init --remote puts the board in a separate repository (no git config knowledge needed)" \ || fail "init --remote recorded the remote but the board did not land in it" ( cd "$SR/app" && git remote get-url origin ) >/dev/null 2>&1 \ && fail "init --remote hijacked origin" \ || pass "init --remote uses its own remote and leaves the code repo's remotes alone" fi rm -rf "$SR" fi rm -rf "$BD" else fail "hooks/board.sh missing or not executable" fi else note "scope=install: board race cases skipped (payload behaviour, not this install)"; fi echo "== 5e) executable bit on every shipped script ==" # A hook that loses +x does not fail loudly: Claude Code invokes it through `bash `, so it keeps working # in the installed tree while the repo carries a broken mode, and start.sh chmods on install which hides it # again. The only place it is visible is the git index — so that is where it is checked. This gate exists # because the very commit that added it dropped 755 to 644 on this file, twice in one session, with nothing # noticing: rewriting a file in place creates a NEW file, and a new file does not inherit the old one's mode. csk_exec_check(){ # $1 = human label, $2.. = paths that must be executable on disk local lbl="$1"; shift; local p bad="" for p in "$@"; do [ -e "$p" ] || continue; [ -x "$p" ] || bad="$bad $(basename "$p")"; done [ -z "$bad" ] && pass "on disk, every $lbl is executable" || fail "not executable ($lbl):$bad" } csk_exec_check "hook" "$HOOKS"/*.sh "$HOOKS/pre-commit" "$HOOKS/commit-msg" csk_exec_check "eval script" "$HERE"/*.sh # The index is the half that actually regresses, and it only exists where these files are tracked — in an # installed project .claude/ is usually gitignored, so a miss there is silence, not a failure. # ...and only where git TRACKS the bit at all. Windows filesystems carry no exec bit, so git sets # core.fileMode=false there and records 100644 for every file it has ever seen — all 19 shipped scripts at # once. An index check under that setting is not a strict check, it is a guaranteed false alarm, and it took # out the Windows job on a change that had nothing wrong with it. Where the bit is untracked the index holds # no information about it, so there is nothing to assert; the POSIX runners are where this gate has teeth. CSK_FILEMODE="$(git -C "$ROOT" config --get core.fileMode 2>/dev/null || echo true)" case "${CSK_FILEMODE:-true}" in false|0|no) note "index mode check skipped (core.fileMode=$CSK_FILEMODE — this platform does not track the bit)" ;; *) if command -v git >/dev/null 2>&1 && git -C "$ROOT" rev-parse --is-inside-work-tree >/dev/null 2>&1; then IDX="$(git -C "$ROOT" ls-files -s -- "$HOOKS" "$HERE" 2>/dev/null \ | awk '$1=="100644" && ($4 ~ /\.sh$/ || $4 ~ /\/(pre-commit|commit-msg)$/) {print $4}')" if [ -z "$(git -C "$ROOT" ls-files -- "$HOOKS" "$HERE" 2>/dev/null)" ]; then note "index mode check skipped (these files are not tracked in this layout)" elif [ -z "$IDX" ]; then pass "in the git index, every shipped script is mode 100755" else fail "tracked with mode 100644 (the +x bit was lost in a commit): $(printf '%s ' $IDX)" fi fi ;; esac echo "== 6) Context-usage threshold logic (fixture) + hook integrity ==" FX="$(mktemp)" printf '%s\n' '{"type":"assistant","isSidechain":false,"message":{"usage":{"input_tokens":1000,"cache_read_input_tokens":800000,"cache_creation_input_tokens":0}}}' > "$FX" o1="$(CONTEXT_WINDOW=1000000 bash "$HOOKS/context-usage.sh" "$FX" 2>/dev/null)" case "$o1" in *"handoff+clear"*) pass "threshold: ~80% → handoff+clear" ;; *) fail "threshold(high) not 'handoff+clear': $o1" ;; esac o2="$(CONTEXT_WINDOW=2000000 bash "$HOOKS/context-usage.sh" "$FX" 2>/dev/null)" case "$o2" in *"continue"*) pass "threshold: CONTEXT_WINDOW=2M → continue" ;; *) fail "threshold(window) not 'continue': $o2" ;; esac if bash "$HOOKS/context-usage.sh" "/no/such.jsonl" >/dev/null 2>&1; then fail "malformed transcript returned exit 0"; else pass "malformed transcript exit!=0"; fi # huge single-line paste as the LAST record: the usage record sits behind it. A line-based tail would drag the # whole blob through the scanner (timeout risk on Windows); the byte-bounded tail + guarded fallback must still # measure, and past the size cap it must FAIL OPEN rather than risk the hook timeout. BIGFX="$(mktemp)" printf '%s\n' '{"type":"assistant","isSidechain":false,"message":{"usage":{"input_tokens":1000,"cache_read_input_tokens":700000,"cache_creation_input_tokens":0}}}' > "$BIGFX" { printf '{"type":"user","isSidechain":false,"message":{"content":"'; head -c 6000000 /dev/zero | tr '\0' A; printf '"}}\n'; } >> "$BIGFX" o3="$(CONTEXT_WINDOW=1000000 bash "$HOOKS/context-usage.sh" "$BIGFX" 2>/dev/null)" case "$o3" in *"🔋 Session"*) pass "measures past a huge last-line paste (byte-bounded tail)" ;; *) fail "byte-tail did not measure past a huge paste: $o3" ;; esac if CONTEXT_WINDOW=1000000 CSK_CONTEXT_MAX_BYTES=1048576 bash "$HOOKS/context-usage.sh" "$BIGFX" >/dev/null 2>&1; then fail "oversized transcript did not fail open (emitted a line)"; else pass "oversized transcript FAILS OPEN (no timeout risk)"; fi rm -f "$BIGFX" rm -f "$FX" [ -x "$HOOKS/commit-msg" ] && pass "commit-msg hook +x" || fail "commit-msg missing/not executable" [ -x "$HOOKS/context-usage.sh" ] && pass "context-usage.sh +x" || fail "context-usage.sh missing/not executable" [ -x "$HOOKS/session-guard.sh" ] && pass "session-guard.sh +x (Stop)" || fail "session-guard.sh missing/not executable" echo "== 6b) Stop-hook gate: once per THRESHOLD · never blocks · systemMessage (not a hook error) ==" SGFX="$(mktemp)" SGPFX="smoketest-$$-${RANDOM:-0}" mkjson(){ printf '{"session_id":"%s","transcript_path":"%s","hook_event_name":"Stop","stop_hook_active":%s}' "$1" "$2" "$3"; } fill(){ printf '%s\n' "{\"type\":\"assistant\",\"isSidechain\":false,\"message\":{\"usage\":{\"input_tokens\":0,\"cache_read_input_tokens\":$1,\"cache_creation_input_tokens\":0}}}" > "$SGFX"; } sg(){ mkjson "$1" "$SGFX" "${2:-false}" | CONTEXT_WINDOW=1000000 bash "$HOOKS/session-guard.sh" 2>/dev/null; } # (1) below the threshold: completely silent fill 600000 o="$(sg "${SGPFX}-a")"; r=$? { [ "$r" = 0 ] && [ -z "$o" ]; } && pass "stop-hook: <75% is silent (exit 0)" || fail "stop-hook spoke below 75% (rc=$r out=$o)" # (2) first crossing of 75%: exit 0 + a user-facing systemMessage. exit 2 would render as "Stop hook error". fill 772000 o="$(sg "${SGPFX}-a")"; r=$? [ "$r" = 0 ] && pass "stop-hook: never blocks (exit 0)" || fail "stop-hook exit $r (must be 0 — a blocking exit shows as a hook error)" case "$o" in *'"systemMessage"'*'>75%'*) pass "stop-hook: 75% emits a user systemMessage" ;; *) fail "stop-hook did not emit the 75% systemMessage: $o" ;; esac # (3) same tier again (even at a higher fill): SILENT — no forced extra turn, no per-turn token burn fill 800000 [ -z "$(sg "${SGPFX}-a")" ] && pass "stop-hook: same tier stays SILENT on later turns" || fail "stop-hook re-fired inside tier 75" # (4) crossing 90%: escalates exactly once fill 920000 o="$(sg "${SGPFX}-a")" case "$o" in *'"systemMessage"'*CRITICAL*) pass "stop-hook: 90% escalates once (CRITICAL)" ;; *) fail "stop-hook did not escalate at 90%: $o" ;; esac fill 950000 [ -z "$(sg "${SGPFX}-a")" ] && pass "stop-hook: silent again after the 90% alert" || fail "stop-hook re-fired inside tier 90" # (5) a jump straight past 90 must stamp the lower tier too, so a post-/compact dip cannot re-fire the 75 alert fill 930000; sg "${SGPFX}-d" >/dev/null fill 760000 [ -z "$(sg "${SGPFX}-d")" ] && pass "stop-hook: dipping back under 90% does not re-fire the 75% alert" || fail "stop-hook re-fired the 75% alert after a dip" # (6) emitted payload is valid JSON carrying systemMessage # EVERY jq SELECTION BELOW IS PROBED BY RUNNING. This file tests the payload for that rule — its own # tier-B sandbox is built out of a jq that resolves and exits 49 — and broke it in ten places. Measured # with a stub jq: 51 errors instead of 21, four of them accusing shipped files of defects they do not # have, and zero skips, so nothing said a check had stopped running. if [ -n "$JSONQ" ]; then fill 800000; sg "${SGPFX}-e" | json_get systemMessage >/dev/null 2>&1 && pass "stop-hook: stdout is valid JSON with .systemMessage (oracle: $JSONQ)" || fail "stop-hook stdout is not valid systemMessage JSON" # --- the fast path ------------------------------------------------------------------------------------- # Every assertion above exercises the SLOW path, where this hook measures for itself. It now prefers the # reading context-usage.sh published at the start of the turn, because re-deriving it cost a second shell # startup and a second transcript scan at the end of EVERY turn — ~29 processes down to 14, which on a # corporate Windows machine (measured: ~290ms per process) is about four seconds a turn. A faster path that # reaches a different verdict would be worse than the cost it saves, so both halves are asserted: it must # agree with the slow path, and it must survive a cache it cannot trust. SGC="${TMPDIR:-/tmp}/csk-context.${SGPFX}-fast" fill 800000 SLOWOUT="$(sg "${SGPFX}-slow")" # no cache for this key -> measures for itself printf '80.0 800000 1000000 handoff+clear\n' > "$SGC" FASTOUT="$(sg "${SGPFX}-fast")" # same fill, published reading case "$FASTOUT" in *'"systemMessage"'*'>75%'*) pass "stop-hook fast path: a published reading produces the same 75% verdict" ;; *) fail "stop-hook fast path reached a different verdict from the measured one: $FASTOUT" ;; esac [ -n "$SLOWOUT" ] && [ -n "$FASTOUT" ] \ && pass "stop-hook: both paths speak at the same fill (the shortcut did not silence the gate)" \ || fail "one path spoke and the other did not (slow='$SLOWOUT' fast='$FASTOUT')" # A truncated or garbled cache must not be believed, and must not silence the warning either: it falls back. printf 'not-a-number junk\n' > "$SGC" case "$(sg "${SGPFX}-fast2")" in *'"systemMessage"'*) pass "stop-hook: an unreadable published reading falls back to measuring, not to silence" ;; *) fail "a corrupt cache silenced the threshold warning — fail-open became fail-quiet" ;; esac rm -f "$SGC" # And the shortcut must actually be taken: no nested shell at the end of a turn is the whole point. printf '80.0 800000 1000000 handoff+clear\n' > "${TMPDIR:-/tmp}/csk-context.${SGPFX}-cnt" mkjson "${SGPFX}-cnt" "$SGFX" false | CONTEXT_WINDOW=1000000 bash -x "$HOOKS/session-guard.sh" >/dev/null 2>"$SGFX.trace" NB="$(grep -cE '^\++ bash ' "$SGFX.trace" 2>/dev/null | tr -cd '0-9')"; NB="${NB:-0}" [ "$NB" -eq 0 ] && pass "stop-hook fast path spawns no nested shell (the cost this removes)" \ || fail "stop-hook still starts $NB nested shell(s) with a published reading available" rm -f "${TMPDIR:-/tmp}/csk-context.${SGPFX}-cnt" "$SGFX.trace" else skip tool "stop-hook JSON check skipped (no working JSON parser: jq, python3 and python all absent or non-functional)"; fi # (7) fail-open: unreadable transcript -> exit 0 and silent (never blocks on measurement failure) o="$(mkjson "${SGPFX}-f" "/no/such.jsonl" false | bash "$HOOKS/session-guard.sh" 2>/dev/null)"; r=$? { [ "$r" = 0 ] && [ -z "$o" ]; } && pass "stop-hook: measurement failure fails open (exit 0, silent)" || fail "stop-hook not fail-open (rc=$r out=$o)" # (8) loop guard: stop_hook_active -> silent no-op fill 920000 [ -z "$(sg "${SGPFX}-g" true)" ] && pass "stop-hook: stop_hook_active loop-guard is a silent no-op" || fail "stop-hook ignored stop_hook_active" # fillc: the same usage record, followed by N compaction boundaries of a given trigger. fillc(){ fill "$1"; i=0; while [ "$i" -lt "${3:-0}" ]; do printf '%s\n' "{\"type\":\"system\",\"subtype\":\"compact_boundary\",\"compactMetadata\":{\"trigger\":\"$2\",\"preTokens\":900000,\"postTokens\":9000}}" >> "$SGFX" i=$((i+1)); done; } # (9) A COMPACTION RE-ARMS THE TIERS. /compact keeps the same session_id, so without a generation key the # markers survive it: a session warned at 90% compacts, climbs all the way back, and is never warned # again — the gate goes quiet precisely on the sessions that need it twice. fillc 920000 "" 0; sg "${SGPFX}-h" >/dev/null # generation 0: warned at 90, both tiers stamped fillc 930000 manual 1 # a compaction happened -> generation 1 o="$(sg "${SGPFX}-h")" case "$o" in *CRITICAL*) pass "stop-hook: a compaction re-arms the thresholds (warns again next generation)" ;; *) fail "stop-hook stayed silent after a compaction — the gate is disarmed for the rest of the session: $o" ;; esac # (10) an AUTO compaction is announced once per generation at ANY fill: the loss already happened, and the # reading right after it is low precisely because the context was thrown away. fillc 100000 auto 1 o="$(sg "${SGPFX}-i")" case "$o" in *'"systemMessage"'*Auto-compaction*) pass "stop-hook: an auto-compaction is reported even at a low fill" ;; *) fail "stop-hook did not report an auto-compaction: $o" ;; esac [ -z "$(sg "${SGPFX}-i")" ] && pass "stop-hook: the auto-compaction notice fires once, not per turn" || fail "stop-hook repeated the auto-compaction notice" # (11) a MANUAL compaction is a deliberate act — never announced as an unchosen loss. fillc 100000 manual 1 [ -z "$(sg "${SGPFX}-j")" ] && pass "stop-hook: a manual compaction is not reported as a loss" || fail "stop-hook reported a deliberate /compact as an unchosen loss" rm -f "$SGFX"; rm -f "${TMPDIR:-/tmp}"/csk-session-guard.${SGPFX}-*.* 2>/dev/null # ---- CSK-NOJQ-PATH --------------------------------------------------------------------------------------- # ONE builder for "a PATH where the jq and python3 tiers do not deliver". It was written three times — here, # for context-usage's two fixtures, and for the guard sandbox — with three tool lists and three copies of the # same Windows caveat, and all three bailed on the same platform for the same reason. # # Tier A makes the interpreters ABSENT: a minimal PATH of symlinks to the tools the hook needs. Faithful, and # impossible on Windows, where Git-Bash copies instead of symlinking without Developer Mode. Measured on # windows-latest: six cases behind these builders never executed, and until skips were counted they were # indistinguishable from six passes. # # Tier B makes them PRESENT AND BROKEN: stubs at the front of PATH that resolve and exit non-zero. No symlink, # so it builds anywhere — and it is the shape a stock Windows install actually HAS, since Windows ships a # Microsoft Store redirector named python3 that resolves and cannot run. Choosing a tier on existence rather # than on success is the exact bug 2.6.0 fixed, so tier B tests the documented rule head-on. # # Echoes the PATH to run under (tier A: the dir alone; tier B: the dir plus the real PATH), or nothing. # CSK_NOJQ_MODE says which tier; CSK_NOJQ_WHY says why not, when nothing comes back. The caller cleans up # "${VAR%%:*}" — the sandbox directory is the first PATH element in both tiers. CSK_NOJQ_MODE=""; CSK_NOJQ_WHY="" csk_nojq_path(){ # $@ = the tools the code under test needs on PATH local d t tp probe; CSK_NOJQ_MODE=""; CSK_NOJQ_WHY="" probe="$(command -v bash 2>/dev/null || echo bash)" d="$(mktemp -d)" || { CSK_NOJQ_WHY="mktemp failed"; return 1; } for t in "$@"; do tp="$(command -v "$t" 2>/dev/null)" [ -n "$tp" ] || { CSK_NOJQ_WHY="no PATH binary for '$t'"; rm -rf "$d"; return 1; } ln -s "$tp" "$d/$t" 2>/dev/null || break done # A real symlink, and the interpreters really gone. Checked in a FRESH shell: a shell caches resolved # binaries in its hash table and consults it BEFORE PATH, so `PATH="$d" command -v jq` in THIS shell keeps # answering with the cached absolute path once anything has run jq. The code under test is a fresh process. if [ -L "$d/$1" ] \ && ! PATH="$d" "$probe" -c 'command -v jq' >/dev/null 2>&1 \ && ! PATH="$d" "$probe" -c 'command -v python3' >/dev/null 2>&1; then if PATH="$d" "$probe" -c 'printf x | grep -q x' 2>/dev/null; then CSK_NOJQ_MODE="minimal"; printf '%s' "$d"; return 0 fi CSK_NOJQ_WHY="canary failed: the minimal PATH cannot run grep"; rm -rf "$d"; return 1 fi rm -rf "$d"; d="$(mktemp -d)" || { CSK_NOJQ_WHY="mktemp failed"; return 1; } for t in jq python3 python; do printf '#!/usr/bin/env bash\nexit 49\n' > "$d/$t" 2>/dev/null || { CSK_NOJQ_WHY="cannot write the '$t' stub"; rm -rf "$d"; return 1; } chmod +x "$d/$t" 2>/dev/null || { CSK_NOJQ_WHY="cannot mark the '$t' stub executable"; rm -rf "$d"; return 1; } done # Both halves, or the tier under test is not the tier that runs: the stub must RESOLVE and must FAIL. PATH="$d:$PATH" "$probe" -c 'command -v jq' >/dev/null 2>&1 || { CSK_NOJQ_WHY="the jq stub does not resolve"; rm -rf "$d"; return 1; } PATH="$d:$PATH" "$probe" -c 'jq --version' >/dev/null 2>&1 && { CSK_NOJQ_WHY="the jq stub RUNS — it would not force the fallback"; rm -rf "$d"; return 1; } PATH="$d:$PATH" "$probe" -c 'printf x | grep -q x' 2>/dev/null || { CSK_NOJQ_WHY="canary failed: grep unusable behind the stubs"; rm -rf "$d"; return 1; } CSK_NOJQ_MODE="stubbed"; printf '%s' "$d:$PATH"; return 0 } # ---- /CSK-NOJQ-PATH -------------------------------------------------------------------------------------- echo "== 6c) no-jq fallback: sidechain-safe + full token sum ==" BASHBIN="$(command -v bash 2>/dev/null || echo bash)" # absolute -> a stripped PATH must not hide bash itself JXBIN="$(csk_nojq_path awk sed grep head tail cat ls tr)" if [ -n "$JXBIN" ]; then SX="$(mktemp)" printf '%s\n' '{"type":"assistant","isSidechain":false,"message":{"usage":{"input_tokens":20,"cache_read_input_tokens":760000,"cache_creation_input_tokens":11936}}}' > "$SX" printf '%s\n' '{"type":"assistant","isSidechain":true,"message":{"usage":{"input_tokens":5,"cache_read_input_tokens":30000,"cache_creation_input_tokens":0}}}' >> "$SX" ox="$(PATH="$JXBIN" CONTEXT_WINDOW=1000000 "$BASHBIN" "$HOOKS/context-usage.sh" --verbose "$SX" 2>/dev/null)" case "$ox" in *"771956/1000000"*handoff+clear*) pass "no-jq: skips sidechain + sums input+cache_read+cache_creation (771956)" ;; *) fail "no-jq fallback wrong (sidechain leak or undercount): $ox" ;; esac rm -f "$SX" else skip tool "no-jq fallback test skipped (no symlink / jq-less PATH buildable here)" fi rm -rf "${JXBIN%%:*}" echo "== 6d) locale: percentage keeps '.' under a comma locale ==" FXL="$(mktemp)" printf '%s\n' '{"type":"assistant","isSidechain":false,"message":{"usage":{"input_tokens":1000,"cache_read_input_tokens":800000,"cache_creation_input_tokens":0}}}' > "$FXL" ol="$(LANG=tr_TR.UTF-8 LC_NUMERIC=tr_TR.UTF-8 CONTEXT_WINDOW=1000000 bash "$HOOKS/context-usage.sh" "$FXL" 2>/dev/null | head -1)" case "$ol" in *,*) fail "locale: percentage emitted a comma under tr_TR: $ol" ;; *) pass "locale: decimal stays '.' under tr_TR ($ol)" ;; esac rm -f "$FXL" echo "== 6i) context-usage: bounded tail read + assistant anchor ==" # Two defects this locks down, both fatal on the no-jq path (stock Git Bash on Windows): # 1. The scan read the whole transcript on EVERY turn though the record it wants is the LAST match. # 4.7s on a 180MB transcript -> past the hook's timeout -> the fill line never reached the model. # 2. A returning subagent's tool_result is a MAIN-context (isSidechain:false) `type:"user"` record whose # `toolUseResult.usage` is raw, unescaped JSON. awk sees only text, so it read the SUBAGENT's tokens as the # session's: a 92.2%-full context reported 0.9%, silencing the handoff gate exactly when it mattered. # Note the window ladder itself CANNOT be tested behaviourally — a tail scan and a full scan return the same # number by construction (that is the invariant). Only the clock tells them apart, so the read bound is asserted # structurally below; the rungs are tested for the correctness they must preserve. CUD="$(mktemp -d)" A_REC='{"type":"assistant","isSidechain":false,"message":{"usage":{"input_tokens":1000,"cache_creation_input_tokens":0,"cache_read_input_tokens":800000,"output_tokens":5}}}' SIDE_REC='{"type":"assistant","isSidechain":true,"message":{"usage":{"input_tokens":5,"cache_creation_input_tokens":0,"cache_read_input_tokens":30000,"output_tokens":1}}}' POISON_REC='{"type":"user","isSidechain":false,"message":{"role":"user","content":"x"},"toolUseResult":{"usage":{"input_tokens":25,"cache_creation_input_tokens":1344,"cache_read_input_tokens":8000,"output_tokens":9}}}' noise(){ awk -v n="$1" -v l="$2" 'BEGIN{for(i=0;i/dev/null; } cu_nojq(){ PATH="$CUJX" CONTEXT_WINDOW=1000000 "$CUBASH" "$HOOKS/context-usage.sh" --verbose "$1" 2>/dev/null; } # assert the SAME expected total on both engines — they must never drift apart both(){ # $1=fixture $2=expected-total $3=label o="$(cu "$1")" case "$o" in *"$2/1000000"*) pass "jq: $3" ;; *) fail "jq: $3 — got: $o" ;; esac if [ -n "$CUJX" ]; then o="$(cu_nojq "$1")" case "$o" in *"$2/1000000"*) pass "no-jq: $3" ;; *) fail "no-jq: $3 — got: $o" ;; esac else skip tool "no-jq: $3 (skipped — no jq-less PATH buildable here)"; fi } # (1) the record sits at EOF, behind a long history: the common case { noise 500 "$SIDE_REC"; printf '%s\n' "$A_REC"; } > "$CUD/eof.jsonl" both "$CUD/eof.jsonl" 801000 "record at EOF behind 500 lines" # (2) past the first rung (200) but inside the second (2000): the ladder must widen, not give up { printf '%s\n' "$A_REC"; noise 300 "$SIDE_REC"; } > "$CUD/rung2.jsonl" both "$CUD/rung2.jsonl" 801000 "record 300 lines from EOF — ladder widens to 2000" # (3) past every rung: the whole-file fallback must still find it (a short window returns EMPTY, never stale) { printf '%s\n' "$A_REC"; noise 2500 "$SIDE_REC"; } > "$CUD/full.jsonl" both "$CUD/full.jsonl" 801000 "record 2500 lines from EOF — whole-file fallback" # (4) THE POISON: a subagent returned, so the last line is a main-context user record carrying the SUBAGENT's # usage as raw JSON. Reading it reports 0.9% for a 92%-full session. Reachable by interrupting a subagent. { printf '%s\n' "$A_REC"; printf '%s\n' "$POISON_REC"; } > "$CUD/poison.jsonl" both "$CUD/poison.jsonl" 801000 "a returning subagent's toolUseResult.usage is NOT the session's fill" # (5) a sidechain record at EOF must not be read either (the pre-existing guarantee, re-asserted at the boundary) { printf '%s\n' "$A_REC"; printf '%s\n' "$SIDE_REC"; } > "$CUD/side.jsonl" both "$CUD/side.jsonl" 801000 "a trailing sidechain record is skipped" # (6) nothing to measure -> exit non-zero, so the hook stays silent rather than inventing a number noise 50 "$SIDE_REC" > "$CUD/none.jsonl" if bash "$HOOKS/context-usage.sh" "$CUD/none.jsonl" >/dev/null 2>&1; then fail "no main-context record returned exit 0"; else pass "no main-context record -> exit!=0 (silent, never invents a fill)"; fi # (7) structural: the read must be BOUNDED. A revert to `scan "$TR"` is invisible to every test above. grep -q 'tail -n' "$HOOKS/context-usage.sh" && pass "transcript is read through a bounded 'tail -n' window" \ || fail "context-usage.sh no longer bounds its read — the whole transcript is scanned every turn" rm -rf "$CUD" "${CUJX%%:*}" echo "== 6i2) hook paths survive a WINDOWS stdin payload (JSON-escaped backslashes) ==" # The paths a hook receives on stdin are JSON values, and JSON escapes a backslash as two. So on Windows the # real path C:\Users\me\a.jsonl arrives as "C:\\Users\\me\\a.jsonl", and a sed slice hands back the doubled # form — a string that names no file on any platform. Every consumer then failed the same quiet way: # context-usage reported "transcript not found" on every turn (Windows CLI and Claude Desktop alike), # session-rehydrate rehydrated nothing, and the skill-trust security notice stopped noticing. Nothing in the # suite caught it because every fixture here writes POSIX paths, where the escaping never appears. # # These cases feed the REAL hooks a payload shaped the way Windows shapes it, with the file actually present at # the unescaped location. Passing means the path was decoded; failing means we are back to reading a literal # `\\` as part of a directory name. WPD="$(mktemp -d)"; mkdir -p "$WPD/docs" "$WPD/.claude/skills/mine" "$WPD/.claude/agents" printf '%s\n' '{"type":"assistant","isSidechain":false,"message":{"usage":{"input_tokens":1000,"cache_read_input_tokens":300000,"cache_creation_input_tokens":0}}}' > "$WPD/t.jsonl" # The encoder assumes forward separators, so normalise FIRST. On a Windows runner TMPDIR is a native path, so # `mktemp -d` already answers with backslashes — encoding that produced a mixed string that was neither the # POSIX nor the JSON shape, and all three cases below failed on windows-latest while passing everywhere else. # The fixture was wrong, not necessarily the hooks; a case that only holds on the platform it was not written # for proves nothing about the platform it was. WPD_FWD="${WPD//\\//}" # ONE encoder, used by the payload builder AND by the round-trip check below. They were separate at first and # promptly drifted: the builder emitted FOUR backslashes per separator instead of two, the checker emitted two, # so the checker passed while the payload was malformed. macOS hid it — decoding `\\\\` leaves `//`, which POSIX # collapses — and windows-latest did not, because a leading `//` there is a UNC network path. Two implementations # of the same rule is one too many. wenc(){ printf '%s' "$1" | sed 's#/#\\\\#g'; } # one separator -> the two backslashes JSON puts in the wire wjson(){ printf '{"hook_event_name":"%s","session_id":"wintest","transcript_path":"%s","cwd":"%s"}' \ "$1" "$(wenc "$WPD_FWD/t.jsonl")" "$(wenc "$WPD_FWD")"; } # Sanity: exactly the doubled form, not more. `\\\\` in the payload is the bug this fixture kept reintroducing. case "$(wjson UserPromptSubmit)" in *'\\\\'*) fail "windows fixture over-escapes (four backslashes per separator) — it decodes to // and only POSIX forgives that" ;; *'\\'*) pass "windows fixture carries JSON-escaped separators" ;; *) fail "windows fixture is not escaped — the cases below are vacuous" ;; esac # ...and it must decode back to a file that exists, or a failure below says nothing about the decoder. This # check is why the next CI failure will be readable instead of a silent ``. WDEC="$(wenc "$WPD_FWD/t.jsonl")"; WDEC="${WDEC//\\\\//}" [ -f "$WDEC" ] && pass "windows fixture decodes back to the real file" \ || fail "windows fixture does not round-trip: raw='$WPD' fwd='$WPD_FWD' decoded='$WDEC' — fix the fixture before reading the cases below" # Honest scope: of the three hooks below only context-usage was actually broken. session-rehydrate and # skill-trust already folded lone backslashes (2.0.1), and folding each half of a doubled `\\` yields `//`, # which the OS collapses — so they survived the encoded form by accident rather than by design. Their cases # here are regression guards, not bug reproductions; the discriminating case is context-usage, which did no # folding at all and therefore compared a literal `\\`-bearing string against the filesystem on every turn. o="$(wjson UserPromptSubmit | CONTEXT_WINDOW=1000000 bash "$HOOKS/context-usage.sh" 2>/dev/null)" case "$o" in *"🔋"*) pass "context-usage decodes a JSON-escaped transcript_path" ;; *) fail "context-usage could not read a Windows-shaped transcript_path (got: ${o:-}) · payload was: $(wjson UserPromptSubmit)" ;; esac # No transcript at all, delivered as a hook payload: silent AND exit 0, because a non-zero status here is an # error banner in the user's session once per turn, for a condition the discipline already handles. o="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"wintest2","transcript_path":"/no/such/x.jsonl"}' | bash "$HOOKS/context-usage.sh" 2>&1)"; rc=$? [ "$rc" = 0 ] && [ -z "$o" ] && pass "unmeasurable hook payload -> silent, exit 0 (no per-turn error banner)" \ || fail "unmeasurable hook payload should be silent+0, got rc=$rc out='$o'" # ...while a by-hand call with a bad argument still complains and exits non-zero (that is a human's mistake). if bash "$HOOKS/context-usage.sh" "/no/such/x.jsonl" >/dev/null 2>&1; then fail "by-hand bad path returned exit 0"; else pass "by-hand bad path still exits non-zero"; fi printf 'HANDOVER\n\n## Next\n- keep going\n' > "$WPD/docs/SESSION_STATE.md" o="$(wjson SessionStart | CLAUDE_PROJECT_DIR= bash "$HOOKS/session-rehydrate.sh" 2>/dev/null)" case "$o" in *SESSION_STATE*) pass "session-rehydrate decodes a JSON-escaped cwd" ;; *) fail "session-rehydrate could not resolve a Windows-shaped cwd (got: ${o:-}) · payload was: $(wjson SessionStart)" ;; esac printf 'skills/handoff\n' > "$WPD/.claude/kit-manifest.txt" printf -- '---\nname: mine\n---\nProject rules.\n' > "$WPD/.claude/skills/mine/SKILL.md" o="$(wjson SessionStart | CLAUDE_PROJECT_DIR= bash "$HOOKS/skill-trust.sh" 2>/dev/null)" case "$o" in *skills/mine*) pass "skill-trust decodes a JSON-escaped cwd (the notice still notices)" ;; *) fail "skill-trust could not resolve a Windows-shaped cwd — the gate is inert there · payload was: $(wjson SessionStart)" ;; esac rm -rf "$WPD" echo "== 6i3) transcript directory encoding (the BY-HAND call, no hook payload) ==" # With a hook payload on stdin the transcript path is handed over; called by hand there is none, so the hook has # to reproduce how Claude Code encodes a cwd into $HOME/.claude/projects/. Getting that wrong is not # cosmetic: `context-usage.sh --verbose` and `session-stats.sh` then find nothing, the 🔋 line disappears, and # the session reports "could not measure" — which is exactly what one Windows machine reported three times. # Ground truth, observed on a Windows install: a cwd of the shape `C:\Repos\team\report_api` is stored as # `C--Repos-team-report-api`, i.e. : \ / . and _ all fold to '-'. # The expression is READ OUT OF THE HOOK, never restated here. A copy in the test asserts what the test author # believed, not what ships: the hook could quietly lose the underscore again and every case below would still # pass. This is the same failure the no-jq section carried for months, so it does not get repeated. CSK_ENC_SED="$(grep -o "s#\[[^]]*\]#-#g" "$HOOKS/context-usage.sh" | head -1)" [ -n "$CSK_ENC_SED" ] && pass "the cwd encoder expression was found in context-usage.sh" \ || fail "no cwd-encoder expression in context-usage.sh (the resolver was rewritten or removed)" enc_csk(){ printf '%s' "$1" | sed "${CSK_ENC_SED:-s#x#x#}"; } [ "$(enc_csk '/Users/x/Projects/claude-starter-kit')" = '-Users-x-Projects-claude-starter-kit' ] \ && pass "encode: POSIX path" || fail "encode: POSIX path -> $(enc_csk '/Users/x/Projects/claude-starter-kit')" [ "$(enc_csk 'C:\Repos\team\report_api')" = 'C--Repos-team-report-api' ] \ && pass "encode: Windows native path (drive letter + backslashes)" \ || fail "encode: Windows native -> $(enc_csk 'C:\Repos\team\report_api')" [ "$(enc_csk '/Users/x/my_app')" = '-Users-x-my-app' ] \ && pass "encode: underscore folds to '-' (misses every such project otherwise)" \ || fail "encode: underscore NOT folded -> $(enc_csk '/Users/x/my_app')" # The encoder is written out twice, once per hook, because a shared file would have to be added to # build-plugin.sh's explicit copy list and a miss there breaks the plugin channel silently. Two copies are only # safe while they cannot drift, so that is enforced here rather than trusted. cu_blk="$(sed -n '/---- CSK-TRANSCRIPT-DIR/,/---- \/CSK-TRANSCRIPT-DIR/p' "$HOOKS/context-usage.sh")" ss_blk="$(sed -n '/---- CSK-TRANSCRIPT-DIR/,/---- \/CSK-TRANSCRIPT-DIR/p' "$HOOKS/session-stats.sh")" [ -n "$cu_blk" ] && [ "$cu_blk" = "$ss_blk" ] \ && pass "the duplicated resolver is byte-identical in both hooks" \ || fail "context-usage.sh and session-stats.sh resolvers have DRIFTED (or the markers are missing)" # Same reasoning, second pair: guard-write.sh carries a copy of guard-bash.sh's JSON parser, because the tier-3 # fallback it replaced read only `file_path` and truncated at the first escaped quote. A shared file would have # to be added to build-plugin.sh's explicit copy list and a miss there breaks the plugin channel silently. gb_blk="$(sed -n '/---- CSK-JSON-PARSE/,/---- \/CSK-JSON-PARSE/p' "$HOOKS/guard-bash.sh")" gw_blk="$(sed -n '/---- CSK-JSON-PARSE/,/---- \/CSK-JSON-PARSE/p' "$HOOKS/guard-write.sh")" [ -n "$gb_blk" ] && [ "$gb_blk" = "$gw_blk" ] \ && pass "the duplicated JSON parser is byte-identical in both guards" \ || fail "guard-bash.sh and guard-write.sh JSON parsers have DRIFTED (or the markers are missing)" # End to end: called by hand from this repo, the hook must produce a reading rather than "transcript not found". cu_hand="$(cd "$ROOT/.." && bash "$HOOKS/context-usage.sh" 2>&1)" case "$cu_hand" in *"transcript not found"*) note "by-hand reading unavailable here (no transcript for this cwd) — encoding still pinned above" ;; *%*) pass "by-hand call resolves its own transcript and reports a fill" ;; *) note "by-hand call produced no reading (out=${cu_hand:-empty})" ;; esac echo "== 6j) session-stats: evidence signals read off the transcript ==" [ -x "$HOOKS/session-stats.sh" ] && pass "session-stats.sh +x" || fail "session-stats.sh missing/not executable" SSD="$(mktemp -d)"; SSF="$SSD/t.jsonl" { # two identical real prompts -> one near-duplicate printf '%s\n' '{"type":"user","isSidechain":false,"message":{"role":"user","content":"please fix the failing migration test for orders"}}' printf '%s\n' '{"type":"assistant","isSidechain":false,"message":{"content":[{"type":"tool_use"},{"type":"tool_use"}]}}' printf '%s\n' '{"type":"assistant","isSidechain":false,"message":{"content":[{"type":"tool_use","name":"Agent"}]}}' printf '%s\n' '{"type":"user","isSidechain":false,"message":{"content":[{"type":"tool_result","is_error":true}]}}' printf '%s\n' '{"type":"user","isSidechain":false,"message":{"role":"user","content":"please fix the failing migration test for orders"}}' # a user-role record that is machinery, not a person: must count as neither prompt nor duplicate printf '%s\n' '{"type":"user","isSidechain":false,"message":{"content":"/compact"}}' printf '%s\n' '{"type":"user","isSidechain":false,"message":{"content":"/compact"}}' # an interrupt, an auto-compaction, and a subagent turn whose tools are NOT the main thread's printf '%s\n' '{"type":"user","isSidechain":false,"message":{"content":[{"type":"text","text":"[Request interrupted by user]"}]}}' printf '%s\n' '{"type":"system","subtype":"compact_boundary","compactMetadata":{"trigger":"auto","preTokens":900000,"postTokens":12000}}' printf '%s\n' '{"type":"assistant","isSidechain":true,"message":{"content":[{"type":"tool_use"},{"type":"tool_use"},{"type":"tool_use"}]}}' } > "$SSF" SS="$(bash "$HOOKS/session-stats.sh" --raw "$SSF" 2>/dev/null)" ss(){ printf '%s\n' "$SS" | sed -n "s/^$1=//p" | head -1; } [ "$(ss cycles)" = 2 ] && pass "counts real prompts only (2) — slash-command records are not prompts" || fail "cycles=$(ss cycles), expected 2 (machinery records leaked into the prompt count)" [ "$(ss tools)" = 3 ] && pass "a subagent's tool calls are not counted as the main thread's" || fail "tools=$(ss tools), expected 3 (sidechain leaked in)" # Delegation is a rule nothing enforces; counting it is the only way it becomes visible in a retro. [ "$(ss delegations)" = 1 ] && pass "delegation to a subagent is counted (1)" || fail "delegations=$(ss delegations), expected 1" [ "$(ss turns)" = 2 ] && pass "assistant turns counted excluding sidechains (2)" || fail "turns=$(ss turns), expected 2" [ "$(ss dup_extra)" = 1 ] && pass "near-duplicate prompt detected (1)" || fail "dup_extra=$(ss dup_extra), expected 1" [ "$(ss errors)" = 1 ] && pass "tool error counted (1)" || fail "errors=$(ss errors), expected 1" [ "$(ss interrupts)" = 1 ] && pass "interrupt counted from the content block (1)" || fail "interrupts=$(ss interrupts), expected 1" [ "$(ss auto_compactions)" = 1 ] && pass "auto-compaction distinguished from manual" || fail "auto_compactions=$(ss auto_compactions), expected 1" [ "$(ss pre_tokens)" = 900000 ] && pass "compaction token loss reported (900000 -> 12000)" || fail "pre_tokens=$(ss pre_tokens), expected 900000" # The phrase inside a tool INPUT (a grep for it, a script that mentions it) is not a user interrupt. Matching # raw text would score the session's own tooling as user frustration. printf '%s\n' '{"type":"assistant","isSidechain":false,"message":{"content":[{"type":"tool_use","input":{"command":"grep -c \"Request interrupted by user\" f.jsonl"}}]}}' > "$SSD/fp.jsonl" [ "$(bash "$HOOKS/session-stats.sh" --raw "$SSD/fp.jsonl" 2>/dev/null | sed -n 's/^interrupts=//p')" = 0 ] \ && pass "the interrupt phrase inside a tool input is not counted" || fail "a tool input mentioning the interrupt phrase was counted as a real interrupt" # UTF-8 must not kill the scan: BSD awk aborts on a multi-byte char inside a character class unless LC_ALL=C. printf '%s\n' '{"type":"user","isSidechain":false,"message":{"role":"user","content":"şu değişikliği gözden geçirir misin — İıĞğŞşÇçÖöÜü"}}' > "$SSD/utf8.jsonl" bash "$HOOKS/session-stats.sh" --raw "$SSD/utf8.jsonl" >/dev/null 2>&1 \ && pass "a non-ASCII transcript scans without an 'illegal byte sequence'" || fail "session-stats died on a UTF-8 transcript (LC_ALL=C missing?)" # Both consumers must actually call it, or the measurement ships and nothing reads it. for s in reflect handoff; do grep -q 'session-stats\.sh' "$SKILLS/$s/SKILL.md" && pass "$s skill runs session-stats.sh" || fail "$s skill does not run session-stats.sh (idle component)" done rm -rf "$SSD" echo "== 6e) CLAUDE.md split: sentinel · discipline/project boundary · no profile split ==" # In the kit repo ROOT is claude-starter/ (payload). In an installed project it is .claude/, which has no # CLAUDE.md but does have the already-split DISCIPLINE.md. Assert whichever is present. if [ -f "$ROOT/CLAUDE.md" ]; then grep -qE '^