@windyroad/itil 0.35.4-preview.357 → 0.35.5

package/.claude-plugin/plugin.json

@@ -484,5 +484,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.35.4"
+  "version": "0.35.5"
 }

package/hooks/itil-readme-refresh-discipline.sh

@@ -19,8 +19,12 @@
 #
 # Allow paths (exit 0 silently per ADR-045 Pattern 1):
 #   - tool_name != "Bash"               (only Bash invocations are gated)
-#   - command does not contain         `git commit` substring (non-commit
-#                                      Bash bypasses entirely)
+#   - command does not invoke           (P268: leading-executable check
+#     `git commit` as its leading-       via `lib/command-detect.sh`
+#     effective command                  — replaces prior substring match
+#                                        that misfired on grep/sed/cat
+#                                        whose arguments contained the
+#                                        literal phrase)
 #   - staged set is README-discipline-  (helper returns 0)
 #     clean
 #   - BYPASS_README_REFRESH_GATE=1 env  (helper returns 0 first)
@@ -44,10 +48,13 @@
 #   P125    — sibling staging-trap hook (same enforcement-layer shape).
 #   P141    — sibling changeset-discipline hook (same shape).
 #   P165    — this hook.
+#   P268    — leading-executable-token command-detect helper.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=lib/readme-refresh-detect.sh
 source "$SCRIPT_DIR/lib/readme-refresh-detect.sh"
+# shellcheck source=lib/command-detect.sh
+source "$SCRIPT_DIR/lib/command-detect.sh"
 
 INPUT=$(cat)
 
@@ -74,13 +81,14 @@ except:
     print('')
 " 2>/dev/null || echo "")
 
-# Only fire on `git commit` invocations. Substring match catches common
-# shapes (`git commit -m`, `git commit --amend`, leading `cd && git
-# commit`, etc.) without over-matching unrelated bash.
-case "$COMMAND" in
-  *"git commit"*) ;;
-  *) exit 0 ;;
-esac
+# Only fire on actual `git commit` invocations. Delegates to
+# `lib/command-detect.sh::command_invokes_git_commit`, which strips
+# common prefix shapes (leading whitespace, env-var assignments,
+# `cd <path> &&`) and checks whether the residual leading token pair
+# is literally `git commit`. P268: replaced the prior substring match
+# `*"git commit"*` that misfired on non-commit Bash whose argument
+# vectors merely mentioned the phrase (grep/sed/cat-heredoc/echo).
+command_invokes_git_commit "$COMMAND" || exit 0
 
 # Run detection. Helper echoes offending ticket path on stdout when
 # detected; returns 1 in that case. Returns 0 (allow) on no-trap,

package/hooks/lib/command-detect.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# P268: shared command-detection helper for PreToolUse:Bash hooks
+# that need to distinguish ACTUAL `git commit` invocations from Bash
+# commands that merely MENTION the literal phrase "git commit" in
+# argument vectors or heredoc bodies (grep patterns, sed patterns,
+# echo strings, cat heredocs, `git log --grep` queries, etc.).
+#
+# Replaces the case-statement substring match
+#
+#     case "$COMMAND" in
+#       *"git commit"*) ;;
+#       *) exit 0 ;;
+#     esac
+#
+# that 5 sibling PreToolUse:Bash hooks previously used to gate on
+# `git commit`. The substring match misfired on legitimate non-commit
+# Bash whose arguments contained the phrase (P268 ticket Description
+# — observed iter-1 retro write and orchestrator grep, ≥3 events per
+# session).
+#
+# Strategy (Fix shape B per P268 ticket):
+#   1. Strip leading whitespace from the candidate command string.
+#   2. Iteratively strip env-var-assignment prefixes (`VAR=value `,
+#      `VAR="..." `, `VAR='...' `) and a `cd <path> &&` prefix until
+#      stable (order-independent — both shapes can interleave).
+#   3. Check whether the residual leading token pair is literally
+#      `git[whitespace]commit` followed by whitespace or end-of-
+#      string. The end-of-token boundary check stops `git commit-tree`
+#      and similar `git commit-*` plumbing commands from matching.
+#
+# Scope deliberately narrow (per P268 ticket Description recommended
+# Fix shape B): handles only the prefix shapes the orchestrator and
+# capture/manage/work skills actually emit — direct `git commit`,
+# `cd && git commit`, `VAR=value git commit`. Does NOT split on
+# `&&`/`||`/`;`/`|` mid-chain — so `git add foo && git commit` reads
+# as `git add` leading and the helper returns 1 (the gate silently
+# passes). That is a documented and acceptable false-negative: a
+# stand-alone re-run of `git commit` re-triggers detection. False
+# positives — the case this fix exists to close — were causing the
+# orchestrator to need manual workaround (stage README first, then
+# run the offending non-commit command) 3+ times per session.
+#
+# Pure exit-code contract — helper never writes to stdout or stderr.
+# Callers that need to name the trigger surface in deny messages
+# should do so from their own delegated-detect helpers (e.g.
+# `lib/readme-refresh-detect.sh` echoes the offending ticket path).
+#
+# References:
+#   ADR-005  — plugin testing strategy (this helper's bats live at
+#              `packages/itil/hooks/test/command-detect.bats` per
+#              behavioural-test discipline).
+#   ADR-009  — gate marker lifecycle (helper is per-invocation, no
+#              marker state — same precedent as `lib/staging-detect.sh`,
+#              `lib/changeset-detect.sh`, `lib/readme-refresh-detect.sh`).
+#   ADR-045  — hook injection budget (silent-on-pass / silent-on-fail
+#              — pure exit-code contract).
+#   P125     — sibling staging-trap hook (candidate for follow-up
+#              refactor to use this helper).
+#   P141     — sibling changeset-discipline hook (candidate).
+#   P165     — sibling README-refresh-discipline hook (first consumer
+#              under P268).
+#   P268     — this helper's surfacing ticket.
+
+# Returns 0 if $1 is a Bash command that invokes `git commit`.
+# Returns 1 otherwise (including commands that merely mention the
+# phrase in their argument vectors or heredoc bodies, and commands
+# whose leading-effective token is some other git subcommand).
+command_invokes_git_commit() {
+  local cmd="$1"
+
+  # Strip leading whitespace (spaces, tabs, newlines).
+  if [[ "$cmd" =~ ^[[:space:]]+ ]]; then
+    cmd="${cmd#"${BASH_REMATCH[0]}"}"
+  fi
+
+  # Iteratively strip env-var-assignment prefixes and `cd <path> &&`
+  # prefixes until stable. The order is unconstrained: both shapes
+  # can appear in either sequence (`VAR=1 cd /tmp && git commit` or
+  # `cd /tmp && VAR=1 git commit`).
+  local prev=""
+  while [ "$cmd" != "$prev" ]; do
+    prev="$cmd"
+
+    # Env-var assignment with double-quoted value: VAR="..." then ws.
+    if [[ "$cmd" =~ ^[A-Za-z_][A-Za-z0-9_]*=\"[^\"]*\"[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    # Env-var assignment with single-quoted value: VAR='...' then ws.
+    if [[ "$cmd" =~ ^[A-Za-z_][A-Za-z0-9_]*=\'[^\']*\'[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    # Env-var assignment with unquoted value: VAR=word then ws.
+    # `word` here is any sequence of non-whitespace characters.
+    if [[ "$cmd" =~ ^[A-Za-z_][A-Za-z0-9_]*=[^[:space:]]*[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    # `cd <path> &&` prefix. Path token is double-quoted, single-
+    # quoted, or unquoted (in which case it cannot itself contain
+    # whitespace or `&`).
+    if [[ "$cmd" =~ ^cd[[:space:]]+\"[^\"]*\"[[:space:]]*\&\&[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    if [[ "$cmd" =~ ^cd[[:space:]]+\'[^\']*\'[[:space:]]*\&\&[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+
+    if [[ "$cmd" =~ ^cd[[:space:]]+[^[:space:]\&]+[[:space:]]*\&\&[[:space:]]+ ]]; then
+      cmd="${cmd#"${BASH_REMATCH[0]}"}"
+      continue
+    fi
+  done
+
+  # After prefix-strip, the leading two tokens must be literally
+  # `git` and `commit`, with whitespace or end-of-string after
+  # `commit` (so `git commit-tree` and similar do not match).
+  [[ "$cmd" =~ ^git[[:space:]]+commit([[:space:]]|$) ]]
+}

package/hooks/test/command-detect.bats

@@ -0,0 +1,181 @@
+#!/usr/bin/env bats
+
+# P268: lib/command-detect.sh — `command_invokes_git_commit` helper.
+#
+# Behavioural contract:
+#   `command_invokes_git_commit "$cmd"` returns 0 iff `$cmd`, when
+#   executed by bash, would actually invoke `git commit` as its
+#   leading-effective command (after stripping common prefix shapes:
+#   leading whitespace, env-var assignments, `cd <path> &&` prefix).
+#   Returns 1 for any other command, including commands whose
+#   argument vectors or heredoc bodies merely mention the literal
+#   string "git commit".
+#
+# Replaces the substring-match `case "$COMMAND" in *"git commit"*) ;;`
+# pattern that 5 sibling PreToolUse:Bash hooks previously shared. The
+# substring match misfired on `grep -n 'git commit' file.md`,
+# `cat >> file <<EOF ... git commit ... EOF`, `echo "git commit ..."`,
+# `sed -i 's/git commit/.../' file`, `git log --grep 'git commit'`,
+# and similar non-commit Bash invocations whose arguments contained
+# the literal phrase (P268 ticket Description).
+#
+# Per P081 (behavioural tests): tests assert helper return code against
+# realistic command strings — NOT grep-against-source-content.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HELPER="$SCRIPT_DIR/lib/command-detect.sh"
+  # shellcheck source=../lib/command-detect.sh
+  source "$HELPER"
+}
+
+# --- Positive cases (helper returns 0 — command IS a git commit) ---
+
+@test "positive: bare git commit -m" {
+  run command_invokes_git_commit "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: git commit --amend" {
+  run command_invokes_git_commit "git commit --amend"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: git commit with no args" {
+  run command_invokes_git_commit "git commit"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: leading whitespace before git commit" {
+  run command_invokes_git_commit "  git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: env-var prefix BYPASS_X=1 git commit" {
+  run command_invokes_git_commit "BYPASS_README_REFRESH_GATE=1 git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: multiple env-var prefixes git commit" {
+  run command_invokes_git_commit "FOO=1 BAR=baz git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: env-var with double-quoted value git commit" {
+  run command_invokes_git_commit "GIT_AUTHOR_NAME=\"Test User\" git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: env-var with single-quoted value git commit" {
+  run command_invokes_git_commit "GIT_AUTHOR_NAME='Test User' git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: cd <path> && git commit" {
+  run command_invokes_git_commit "cd /tmp && git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: cd <quoted path> && git commit" {
+  run command_invokes_git_commit "cd \"/tmp/with spaces\" && git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: env-var then cd then git commit (combined prefixes)" {
+  run command_invokes_git_commit "BYPASS=1 cd /tmp && git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: cd then env-var then git commit (reversed prefix order)" {
+  run command_invokes_git_commit "cd /tmp && BYPASS=1 git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+}
+
+@test "positive: tab-indented git commit" {
+  run command_invokes_git_commit $'\tgit commit -m feat'
+  [ "$status" -eq 0 ]
+}
+
+# --- Negative cases (helper returns 1 — command is NOT a git commit) ---
+
+@test "negative: grep with 'git commit' as pattern argument" {
+  run command_invokes_git_commit "grep -n 'git commit' file.md"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: grep -rn 'git commit' (the recurring orchestrator surface)" {
+  run command_invokes_git_commit "grep -rn 'git commit' packages/"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: cat heredoc whose body contains the phrase git commit" {
+  run command_invokes_git_commit $'cat >> docs/problems/README-history.md <<EOF\nWe added a git commit gate.\nEOF'
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: echo string containing git commit" {
+  run command_invokes_git_commit "echo 'the git commit gate fires here'"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: sed substitution mentioning git commit" {
+  run command_invokes_git_commit "sed -i 's/git commit/git push/' file.md"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: git log --grep 'git commit'" {
+  run command_invokes_git_commit "git log --grep 'git commit'"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: git status (other git subcommand)" {
+  run command_invokes_git_commit "git status"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: git push (other git subcommand)" {
+  run command_invokes_git_commit "git push origin main"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: git commit-tree (plumbing — boundary check)" {
+  run command_invokes_git_commit "git commit-tree HEAD^{tree}"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: empty command" {
+  run command_invokes_git_commit ""
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: whitespace-only command" {
+  run command_invokes_git_commit "   "
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: cat with single-quoted body containing git commit phrase" {
+  run command_invokes_git_commit "printf '%s\n' 'the git commit gate is here' > /tmp/out"
+  [ "$status" -eq 1 ]
+}
+
+@test "negative: a different command chained before git commit (e.g. git add foo && git commit) — leading is git add, helper passes" {
+  # Per Fix shape B narrow scope: helper only checks the leading-
+  # effective command after prefix-strip. Mid-chain `git commit`
+  # after a non-prefix-shape leading command (here `git add`) is a
+  # documented false negative — standalone re-commit would re-trigger
+  # detection. Acceptable per P268 ticket Description.
+  run command_invokes_git_commit "git add foo && git commit -m 'feat'"
+  [ "$status" -eq 1 ]
+}
+
+# --- Silence contract (ADR-045 Pattern 1) ---
+
+@test "helper emits zero bytes on stdout (pure exit-code contract)" {
+  run command_invokes_git_commit "git commit -m 'feat'"
+  [ "${#output}" -eq 0 ]
+}
+
+@test "helper emits zero bytes on stdout for negative case too" {
+  run command_invokes_git_commit "grep -n 'git commit' file.md"
+  [ "${#output}" -eq 0 ]
+}

package/hooks/test/itil-readme-refresh-discipline.bats

@@ -419,3 +419,110 @@ EOF
   [[ "$output" == *".claude/settings.json"* ]]
   [[ "$output" == *"P173"* ]]
 }
+
+# --- P268: substring-vs-invocation regression coverage ---
+#
+# Prior to P268, the hook used `case "$COMMAND" in *"git commit"*) ;;`
+# which fired on ANY Bash command whose text contained the literal
+# phrase "git commit" — including grep patterns, sed substitutions,
+# cat heredoc bodies, echo strings, and `git log --grep` queries.
+# Workaround was stage-README-first, observed ≥3 times per session.
+# P268 replaces that match with a leading-executable-token check via
+# `lib/command-detect.sh::command_invokes_git_commit`. The tests
+# below stage a ticket file (which would trigger deny if the gate
+# fired) and run various non-commit Bash commands whose argument
+# vectors mention `git commit`. The hook MUST pass silently.
+
+@test "P268 allow: grep with 'git commit' pattern does NOT trigger gate" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "grep -n 'git commit' file.md"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  # Silent pass per ADR-045 Pattern 1.
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P268 allow: grep -rn 'git commit' packages/ (the recurring orchestrator surface)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "grep -rn 'git commit' packages/"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P268 allow: sed -i 's/git commit/.../' substitution does NOT trigger gate" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "sed -i 's/git commit/git push/' file.md"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P268 allow: echo with 'git commit' inside string does NOT trigger gate" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "echo 'the git commit gate fires here'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P268 allow: git log --grep 'git commit' does NOT trigger gate (git log is leading)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git log --grep 'git commit'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P268 allow: cat heredoc whose body contains 'git commit' does NOT trigger gate (iter-1 retro write surface)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  # Inline-build JSON with embedded newlines via printf to mimic the
+  # Bash tool's multi-line command payload (the canonical retro-write
+  # surface that misfired in P268).
+  local payload
+  payload=$(python3 -c "import json,sys; print(json.dumps({'tool_name':'Bash','tool_input':{'command':'cat >> docs/problems/README-history.md <<EOF\nFlow note: the git commit gate fires here.\nEOF'}}))")
+  run bash -c "echo '$payload' | bash $HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P268 deny: actual git commit invocation with staged ticket still triggers gate (positive regression)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"P165"* ]]
+}
+
+@test "P268 deny: cd <path> && git commit (prefix-strip path) still triggers gate" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "cd . && git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "P268 deny: GIT_AUTHOR_NAME=Test git commit (env-prefix path) still triggers gate" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "GIT_AUTHOR_NAME=Test git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "P268 allow: git commit-tree (boundary check — commit-tree is a different plumbing command)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git commit-tree HEAD^{tree}"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.35.4-preview.357",
+  "version": "0.35.5",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"