@windyroad/jtbd 0.1.2 → 0.1.3-preview.27

package/README.md

@@ -0,0 +1,62 @@
+# @windyroad/jtbd
+
+**Jobs-to-be-done enforcement for Claude Code.** Reviews UI changes against your documented user jobs, personas, and desired outcomes before they ship.
+
+Part of [Windy Road Agent Plugins](../../README.md).
+
+## What It Does
+
+An AI agent building a feature doesn't know *why* the feature exists or *who* it's for. It builds what you describe, but can't validate whether the result actually serves the user's job-to-be-done.
+
+The JTBD plugin:
+
+1. **Detects** when an edit touches user-facing UI files
+2. **Blocks** the edit until the JTBD agent has reviewed it
+3. **Reviews** changes against your `docs/JOBS_TO_BE_DONE.md` and `docs/PRODUCT_DISCOVERY.md`
+4. **Reports** alignment gaps -- features that don't map to a documented job, or that conflict with persona constraints
+
+## Install
+
+```bash
+npx @windyroad/jtbd
+```
+
+Restart Claude Code after installing.
+
+## Usage
+
+The plugin works automatically. On first use in a project without a JTBD document, it blocks edits and directs you to create one:
+
+```
+/wr-jtbd:update-guide
+```
+
+This examines your existing features and asks about your user jobs, personas, and desired outcomes to generate a `docs/JOBS_TO_BE_DONE.md`.
+
+## How It Works
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `jtbd-eval.sh` | Every prompt | Evaluates whether the task involves user-facing UI |
+| `jtbd-enforce-edit.sh` | Edit or Write | Blocks edits until the JTBD agent has reviewed |
+| `jtbd-mark-reviewed.sh` | Agent completes | Marks the review as done |
+| `jtbd-reset-marker.sh` | Session end | Cleans up review markers |
+
+## Agent
+
+The `wr-jtbd:agent` reads your `docs/JOBS_TO_BE_DONE.md` and reviews proposed UI changes against:
+
+- Documented user jobs and their success criteria
+- Persona definitions and constraints
+- Screen-to-job mappings
+
+## Updating and Uninstalling
+
+```bash
+npx @windyroad/jtbd --update
+npx @windyroad/jtbd --uninstall
+```
+
+## Licence
+
+[MIT](../../LICENSE)

package/hooks/jtbd-enforce-edit.sh

@@ -45,7 +45,7 @@ BASENAME=$(basename "$FILE_PATH")
 
 # If no JTBD doc exists, block and direct to create skill
 if [ ! -f "docs/JOBS_TO_BE_DONE.md" ]; then
-  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/JOBS_TO_BE_DONE.md does not exist. Run /wr-jtbd:create to generate a JTBD document for this project, then delegate to wr-jtbd:agent for review."
+  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/JOBS_TO_BE_DONE.md does not exist. Run /wr-jtbd:update-guide to generate a JTBD document for this project, then delegate to wr-jtbd:agent for review."
   exit 0
 fi
 

package/hooks/jtbd-eval.sh

@@ -29,7 +29,7 @@ else
     cat <<'HOOK_OUTPUT'
 NOTE: This project has UI files but no docs/JOBS_TO_BE_DONE.md.
 If the user's task involves editing UI files, the edit will be blocked
-until a JTBD document exists. Run /wr-jtbd:create to generate one.
+until a JTBD document exists. Run /wr-jtbd:update-guide to generate one.
 HOOK_OUTPUT
   fi
 fi

package/hooks/jtbd-mark-reviewed.sh

@@ -28,7 +28,7 @@ case "$SUBAGENT" in
     case "$VERDICT" in
       PASS)
         touch "/tmp/jtbd-reviewed-${SESSION_ID}"
-        store_review_hash "$SESSION_ID" "jtbd" "docs/jtbd"
+        store_review_hash "$SESSION_ID" "jtbd" "docs/JOBS_TO_BE_DONE.md"
         ;;
       FAIL)
         # Do NOT create marker — review found issues
@@ -36,7 +36,7 @@ case "$SUBAGENT" in
       *)
         # No verdict file — backward compat, allow with marker
         touch "/tmp/jtbd-reviewed-${SESSION_ID}"
-        store_review_hash "$SESSION_ID" "jtbd" "docs/jtbd"
+        store_review_hash "$SESSION_ID" "jtbd" "docs/JOBS_TO_BE_DONE.md"
         ;;
     esac
 

package/hooks/lib/gate-helpers.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# Shared portable helpers for gate enforcement hooks.
+# Sourced by architect-gate.sh, risk-gate.sh, and all hook scripts.
+# Provides: _mtime, _hashcmd, _doc_exclusions, _err_trap, _get_*
+
+# ---------------------------------------------------------------------------
+# Portable utilities
+# ---------------------------------------------------------------------------
+
+# Portable mtime: tries GNU stat, falls back to macOS stat
+_mtime() { stat -c%Y "$1" 2>/dev/null || /usr/bin/stat -f%m "$1" 2>/dev/null || echo 0; }
+
+# Portable hash: tries md5sum, falls back to md5 -r, then shasum
+_hashcmd() { md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null; }
+
+# Paths excluded from pipeline state hashing and docs-only detection.
+_doc_exclusions() {
+    echo ':!docs/' ':!.risk-reports/' ':!.changeset/' ':!governance/' ':!.claude/plans/' ':!CLAUDE.md' ':!AGENTS.md' ':!PRINCIPLES.md' ':!DECISION-MANAGEMENT.md' ':!AGENTIC_RISK_REGISTER.md' ':!PROBLEM-MANAGEMENT.md'
+}
+
+# ---------------------------------------------------------------------------
+# ERR trap: outputs diagnostic JSON on hook errors (P010)
+# Usage: source gate-helpers.sh at top of hook, then call _enable_err_trap
+# ---------------------------------------------------------------------------
+
+_enable_err_trap() {
+    trap '_err_trap_handler "$BASH_SOURCE" "$LINENO" "$BASH_COMMAND"' ERR
+}
+
+_err_trap_handler() {
+    local script="$1" line="$2" cmd="$3"
+    local name
+    name=$(basename "$script" 2>/dev/null || echo "$script")
+    # Output diagnostic as systemMessage so it's visible in conversation
+    cat <<EOF
+{
+  "systemMessage": "Hook error in ${name} at line ${line}: ${cmd}"
+}
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# JSON input parsing: standardised helpers replacing inline python3
+# Each reads from _HOOK_INPUT (set by the hook before calling these)
+# ---------------------------------------------------------------------------
+
+# Store hook input for reuse by parsing helpers
+_HOOK_INPUT=""
+
+_parse_input() {
+    _HOOK_INPUT=$(cat)
+}
+
+_get_tool_name() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_session_id() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_command() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_file_path() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    ti = data.get('tool_input', {})
+    print(ti.get('file_path', ti.get('path', '')))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_subagent_type() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('subagent_type', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_user_prompt() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('user_prompt', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_tool_output() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    # PostToolUse provides tool_response (dict with content array), not tool_output
+    tr = data.get('tool_response', {})
+    if isinstance(tr, dict):
+        content = tr.get('content', [])
+        if isinstance(content, list):
+            texts = [c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text']
+            if texts:
+                print('\n'.join(texts))
+                sys.exit(0)
+    # Fallback for older/different hook formats
+    print(data.get('tool_output', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+# ---------------------------------------------------------------------------
+# Session-scoped tmp directory for risk files
+# ---------------------------------------------------------------------------
+
+# Returns the session-scoped directory for risk temp files.
+# Creates the directory if it doesn't exist.
+# Usage: DIR=$(_risk_dir "$SESSION_ID"); echo "1" > "$DIR/commit"
+_risk_dir() {
+  local sid="$1"
+  local dir="${TMPDIR:-/tmp}/claude-risk-${sid}"
+  mkdir -p "$dir"
+  echo "$dir"
+}
+
+# ---------------------------------------------------------------------------
+# Non-doc file detection for WIP gating
+# ---------------------------------------------------------------------------
+
+_is_doc_file() {
+    local file_path="$1"
+    local EXCL
+    EXCL=$(_doc_exclusions)
+    for pattern in $EXCL; do
+        local clean="${pattern#:!}"
+        case "$file_path" in
+            *"$clean"*) return 0 ;;
+        esac
+    done
+    case "$file_path" in
+        *.claude/*|*.risk-reports/*|*RISK-POLICY.md) return 0 ;;
+    esac
+    return 1
+}

package/hooks/lib/review-gate.sh

@@ -16,7 +16,7 @@ check_review_gate() {
   local POLICY_FILE="$3"   # e.g., "docs/STYLE-GUIDE.md"
   local MARKER="/tmp/${SYSTEM}-reviewed-${SESSION_ID}"
   local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
-  local TTL_SECONDS="${REVIEW_TTL:-600}"
+  local TTL_SECONDS="${REVIEW_TTL:-1800}"
 
   # 1. Marker must exist
   if [ ! -f "$MARKER" ]; then

package/hooks/test/jtbd-mark-reviewed.bats

@@ -0,0 +1,20 @@
+#!/usr/bin/env bats
+
+# Tests for JTBD mark-reviewed hook — verifies hash path matches enforce hook
+
+@test "mark-reviewed uses docs/JOBS_TO_BE_DONE.md path" {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  grep -q 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+}
+
+@test "mark-reviewed does NOT use docs/jtbd path" {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  ! grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+}
+
+@test "enforce-edit and mark-reviewed use same policy path" {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  ENFORCE_PATH=$(grep -o 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-enforce-edit.sh" | head -1)
+  MARK_PATH=$(grep -o 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-mark-reviewed.sh" | head -1)
+  [ "$ENFORCE_PATH" = "$MARK_PATH" ]
+}

package/package.json

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

package/skills/{wr:jtbd → update-guide}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wr:jtbd
+name: wr-jtbd:update-guide
 description: Create or update the project's docs/JOBS_TO_BE_DONE.md by examining existing features and asking the user about user jobs, personas, and desired outcomes.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---