@windyroad/retrospective 0.20.3 → 0.20.4

package/.claude-plugin/plugin.json

@@ -66,5 +66,5 @@
     }
   },
   "name": "wr-retrospective",
-  "version": "0.20.3"
+  "version": "0.20.4"
 }

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/retrospective-readme-jtbd-currency.sh

@@ -81,6 +81,9 @@
 #             retro-time advisory consumption as primary).
 #   ADR-052 — behavioural-tests default (bats fixture asserts on
 #             emitted JSON, not source content).
+#   ADR-017 — shared-code sync pattern (command-detect.sh canonical at
+#             packages/shared/hooks/lib/; synced into per-package
+#             hooks/lib/ via scripts/sync-command-detect.sh).
 #   P081 — behavioural tests preferred over structural greps.
 #   P125 — sibling staging-trap helper (per-invocation no-marker).
 #   P141 — sibling changeset-discipline gate on `git commit` (same
@@ -88,9 +91,15 @@
 #   P158 — retro Step 2b wiring (backup advisory; survives this
 #             hook's primary-surface migration).
 #   P159 — this hook.
+#   P268 — shared `command_invokes_git_commit` helper landed in
+#             packages/shared/hooks/lib/command-detect.sh.
+#   P275 — sibling-hook refactor: substring-match → helper here
+#             (first cross-package consumer of the shared helper).
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 DETECTOR="$SCRIPT_DIR/../scripts/check-readme-jtbd-currency.sh"
+# shellcheck source=lib/command-detect.sh
+source "$SCRIPT_DIR/lib/command-detect.sh"
 
 INPUT=$(cat)
 
@@ -117,15 +126,10 @@ 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`, `chore: version packages` release commits routed via
-# `git commit -m 'chore: version packages'`, etc.) without
-# over-matching unrelated bash.
-case "$COMMAND" in
-  *"git commit"*) ;;
-  *) exit 0 ;;
-esac
+# Only fire on actual `git commit` invocations. P275: delegates to the
+# shared `command_invokes_git_commit` helper for leading-executable
+# semantics (was substring match prone to grep/sed/echo false positives).
+command_invokes_git_commit "$COMMAND" || exit 0
 
 # Bypass via env var — single most-common legitimate escape.
 if [ "${BYPASS_JTBD_CURRENCY:-}" = "1" ]; then

package/hooks/test/retrospective-readme-jtbd-currency.bats

@@ -261,3 +261,74 @@ EOF
   [ "$status" -eq 0 ]
   [ "${#output}" -eq 0 ]
 }
+
+# ── P275 / P268 leading-executable regression cases ─────────────────────────
+#
+# The hook must fire on ACTUAL `git commit` invocations, NOT on Bash that
+# merely MENTIONS the phrase "git commit" in argument vectors or heredoc
+# bodies. Mirrors P268 regression fixtures in command-detect.bats and
+# P272 sibling fixtures in itil-changeset-discipline.bats.
+
+@test "P275 allow: grep with literal 'git commit' pattern on drifted project does NOT deny" {
+  make_drifted_project
+  run run_bash_hook "grep -r 'git commit' ."
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P275 allow: sed pattern containing 'git commit' on drifted project does NOT deny" {
+  make_drifted_project
+  run run_bash_hook "sed -n 's/git commit/X/p' packages/stub/README.md"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P275 allow: echo with literal 'git commit' string on drifted project does NOT deny" {
+  make_drifted_project
+  run run_bash_hook "echo 'run git commit -m foo'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P275 allow: git log --grep with 'git commit' search term on drifted project does NOT deny" {
+  make_drifted_project
+  run run_bash_hook "git log --grep='git commit'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P275 allow: git commit-tree plumbing on drifted project does NOT deny (boundary)" {
+  make_drifted_project
+  run run_bash_hook "git commit-tree HEAD^{tree} -m 'msg'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [ "${#output}" -eq 0 ]
+}
+
+# ── P275 positive leading-executable cases still deny ──────────────────────
+
+@test "P275 deny: env-var-prefixed git commit on drifted project still triggers deny" {
+  make_drifted_project
+  run run_bash_hook "GIT_AUTHOR_NAME=foo git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"P159"* ]]
+}
+
+@test "P275 deny: cd-prefixed git commit on drifted project still triggers deny" {
+  make_drifted_project
+  run run_bash_hook "cd . && git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "P275 deny: leading-whitespace git commit on drifted project still triggers deny" {
+  make_drifted_project
+  run run_bash_hook "   git commit -m 'feat'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/retrospective",
-  "version": "0.20.3",
+  "version": "0.20.4",
   "description": "Session retrospectives that update briefings and create problem tickets",
   "bin": {
     "windyroad-retrospective": "./bin/install.mjs"