@windyroad/jtbd 0.12.5 → 0.12.6

package/.claude-plugin/plugin.json

@@ -90,5 +90,5 @@
     }
   },
   "name": "wr-jtbd",
-  "version": "0.12.5"
+  "version": "0.12.6"
 }

package/hooks/jtbd-enforce-edit.sh

@@ -9,6 +9,7 @@
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/review-gate.sh"
+source "$SCRIPT_DIR/lib/marker-only-diff.sh"
 
 # P191: resolve the project root from the session signal, not the hook's
 # runtime CWD. Claude Code may launch the hook with an actual working
@@ -40,6 +41,15 @@ except:
     print('')
 " 2>/dev/null || echo "")
 
+TOOL_NAME=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
 if [ -z "$SESSION_ID" ]; then
   review_gate_parse_error
   exit 0
@@ -120,6 +130,62 @@ case "$FILE_PATH" in
     exit 0 ;;
 esac
 
+# P301: marker-only-diff exemption for docs/decisions/*.md ADRs. The JTBD
+# gate fires on docs/decisions/ writes (not in its exclusion list), so a
+# multi-batch `/wr-architect:review-decisions` drain pays one JTBD review
+# round-trip per batch on top of the architect one — the ticket's
+# observed "Batch 8 (ADR-020): blocked on architect review (`jtbd policy
+# file changed since last review`)" symptom is precisely that. Same
+# rationale + safety-net as the architect-side exemption: oversight
+# marker writes are mechanical output of a substance-confirmed decision
+# (ADR-066 contract); the jtbd-oversight-marker-discipline.sh hook
+# continues to enforce per-ADR session evidence for `confirmed`
+# introductions.
+case "$FILE_PATH" in
+  */docs/decisions/*.md|docs/decisions/*.md)
+    case "$TOOL_NAME" in
+      Edit)
+        _OLD=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('old_string', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+        _NEW=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('new_string', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+        if [ -n "$_OLD$_NEW" ] && is_marker_only_diff "$_OLD" "$_NEW"; then
+          exit 0
+        fi
+        ;;
+      Write)
+        _NEW=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('content', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+        _OLD=""
+        if [ -f "$FILE_PATH" ]; then
+          _OLD=$(cat "$FILE_PATH" 2>/dev/null) || _OLD=""
+        fi
+        if [ -n "$_OLD$_NEW" ] && is_marker_only_diff "$_OLD" "$_NEW"; then
+          exit 0
+        fi
+        ;;
+    esac
+    ;;
+esac
+
 # Determine JTBD path — canonical directory layout only (ADR-008 Option 3).
 # Legacy docs/JOBS_TO_BE_DONE.md is NOT consulted at runtime; the gate is
 # inactive on projects that have not run /wr-jtbd:update-guide.

package/hooks/lib/marker-only-diff.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# Shared helper: detect "oversight-marker-only" frontmatter diffs.
+#
+# P301: ADR-066/068 oversight-marker writes to docs/decisions/ ADRs trip the
+# full architect+JTBD edit gate each batch of an `/wr-architect:review-decisions`
+# drain, producing 2-3 no-op-PASS review round-trips per batch. The marker
+# add/update is the mechanical output of a decision the user already
+# substance-confirmed via AskUserQuestion (ADR-066 contract); the gate has
+# nothing substantive to assess.
+#
+# This helper exposes `is_marker_only_diff OLD NEW` returning 0 when every
+# added/removed non-empty line matches one of the oversight-marker frontmatter
+# patterns:
+#
+#   human-oversight:   confirmed | unconfirmed | rejected-pending-supersede
+#   oversight-date:    <date>
+#   decision-makers:   <name|email>
+#   supersede-ticket:  <ticket>
+#
+# When the predicate fires PASS, the calling gate short-circuits to exit 0
+# without requiring a fresh architect / JTBD review marker. The
+# architect-oversight-marker-discipline.sh (and JTBD sibling) hooks remain
+# active as the safety net: a marker-only diff that introduces
+# `human-oversight: confirmed` still requires the per-ADR session evidence
+# marker (P348 / ADR-066 amendment 2026-06-02).
+#
+# Conservative boundary: any non-empty line outside the marker grammar
+# (frontmatter delimiters that shift position, status:/date: changes, body
+# edits) fails the predicate. The exemption is exact so it cannot be used
+# to slip decision-content edits past the gate.
+#
+# Fail-safe: if python3 is unavailable or the diff parse errors, the function
+# returns 1 (NOT marker-only) and the gate proceeds with its normal review
+# requirement.
+#
+# Sibling copy of packages/architect/hooks/lib/marker-only-diff.sh per the
+# existing gate-helpers.sh duplicate-shared pattern (ADR-017). Keep in sync
+# manually until a second call site justifies the cost of a sync script.
+
+is_marker_only_diff() {
+  local old="$1"
+  local new="$2"
+
+  command -v python3 >/dev/null 2>&1 || return 1
+
+  OLD_CONTENT="$old" NEW_CONTENT="$new" python3 - <<'PYEOF'
+import os, sys, re
+try:
+    import difflib
+except Exception:
+    sys.exit(1)
+
+old = os.environ.get('OLD_CONTENT', '')
+new = os.environ.get('NEW_CONTENT', '')
+
+if old == new:
+    sys.exit(0)
+
+old_lines = old.splitlines()
+new_lines = new.splitlines()
+
+marker_pat = re.compile(
+    r'^[ \t]*(human-oversight|oversight-date|decision-makers|supersede-ticket)[ \t]*:.*$'
+)
+
+def allowed(line: str) -> bool:
+    s = line.strip()
+    if s == '':
+        return True
+    if marker_pat.match(line):
+        return True
+    return False
+
+sm = difflib.SequenceMatcher(a=old_lines, b=new_lines, autojunk=False)
+for tag, i1, i2, j1, j2 in sm.get_opcodes():
+    if tag == 'equal':
+        continue
+    for line in old_lines[i1:i2]:
+        if not allowed(line):
+            sys.exit(1)
+    for line in new_lines[j1:j2]:
+        if not allowed(line):
+            sys.exit(1)
+
+sys.exit(0)
+PYEOF
+}

package/hooks/test/jtbd-marker-only-exempt.bats

@@ -0,0 +1,140 @@
+#!/usr/bin/env bats
+
+# P301: jtbd-enforce-edit.sh exempts marker-only frontmatter diffs to
+# docs/decisions/*.md ADRs from the JTBD review gate. The JTBD gate currently
+# fires on docs/decisions/ writes (decisions are not in its exclusion list);
+# the ticket's symptom "Batch 8 (ADR-020): blocked on architect review
+# (`jtbd policy file changed since last review`)" is that JTBD round-trip.
+#
+# Behavioural — exercises the full hook with constructed PreToolUse stdin
+# JSON payloads under a sandbox project dir; asserts on stdout+exit.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/jtbd-enforce-edit.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  # JTBD docs must exist for the gate to engage (otherwise it denies
+  # with "no JTBD documentation" — out of scope of this exemption test).
+  mkdir -p docs/jtbd/persona docs/decisions
+  echo "# stub job" > docs/jtbd/persona/JTBD-001-stub.proposed.md
+  echo "# stub adr" > docs/decisions/001-stub.proposed.md
+  SID="jtbd-marker-only-$$-$BATS_TEST_NUMBER"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  rm -f "/tmp/jtbd-reviewed-${SID}" "/tmp/jtbd-reviewed-${SID}.hash"
+}
+
+run_hook_json() {
+  local json_file="$1"
+  bash "$HOOK" < "$json_file"
+}
+
+# ── Marker-only ADD: should exempt ───────────────────────────────────────
+
+@test "P301: Edit adding only human-oversight + oversight-date to ADR is exempt (no JTBD marker required)" {
+  adr="$PWD/docs/decisions/100-some-adr.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 100 some adr
+EOF
+  old=$'---\nstatus: "proposed"\n---'
+  new=$'---\nstatus: "proposed"\nhuman-oversight: unconfirmed\noversight-date: 2026-06-08\n---'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "P301: Edit updating human-oversight value (unconfirmed → confirmed) on ADR is exempt" {
+  adr="$PWD/docs/decisions/101-promote.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+human-oversight: unconfirmed
+---
+
+# 101
+EOF
+  old=$'human-oversight: unconfirmed'
+  new=$'human-oversight: confirmed\noversight-date: 2026-06-08'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# ── Mixed marker + body: must NOT exempt ─────────────────────────────────
+
+@test "P301: Edit changing body content along with markers still gates" {
+  adr="$PWD/docs/decisions/110-mixed.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 110
+
+Original body.
+EOF
+  old=$'---\nstatus: "proposed"\n---\n\n# 110\n\nOriginal body.'
+  new=$'---\nstatus: "proposed"\nhuman-oversight: confirmed\noversight-date: 2026-06-08\n---\n\n# 110\n\nNew policy claim added.'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# ── Pure body change: must still gate ────────────────────────────────────
+
+@test "P301: Edit changing only body content with no marker lines still gates" {
+  adr="$PWD/docs/decisions/120-body.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 120
+
+Some text.
+EOF
+  old='Some text.'
+  new='Some text. And more.'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# ── Scope: exemption is narrow to docs/decisions/*.md ────────────────────
+
+@test "P301: marker-only diff to a NON docs/decisions/ path still gates (no path exemption)" {
+  mkdir -p "$PWD/src"
+  echo "// stub" > "$PWD/src/x.ts"
+  src="$PWD/src/x.ts"
+  old='// stub'
+  new=$'// stub\nhuman-oversight: confirmed'
+  json_file=$(mktemp)
+  jq -nc --arg p "$src" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/jtbd",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "Jobs-to-be-done enforcement for UI changes",
   "bin": {
     "windyroad-jtbd": "./bin/install.mjs"