@windyroad/jtbd 0.4.0 → 0.5.0

package/hooks/test/jtbd-enforce-scope.bats

@@ -1,7 +1,10 @@
 #!/usr/bin/env bats
 
-# Tests for jtbd-enforce-edit.sh — verifies broadened scope with exclusions
-# Mix of grep-based pattern tests and functional execution tests.
+# Tests for jtbd-enforce-edit.sh — verifies broadened scope with exclusions.
+# All tests are functional: they execute the hook with mock JSON input
+# and assert on exit status and BLOCKED output. Source-grep assertions
+# were removed (P011) — they over-specified the implementation and
+# false-positived on legitimate refactors.
 
 setup() {
   SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
@@ -16,12 +19,6 @@ teardown() {
   rm -rf "$TEST_DIR"
 }
 
-# Helper: check if a pattern is in the exclusion list by grepping the hook
-file_is_excluded() {
-  local pattern="$1"
-  grep -q "$pattern" "$HOOK"
-}
-
 # Helper: run the hook with a mock JSON input for a given file path
 run_hook_with_file() {
   local file_path="$1"
@@ -29,46 +26,75 @@ run_hook_with_file() {
   echo "$json" | bash "$HOOK"
 }
 
-# --- Pattern-based exclusion tests (grep) ---
+# Helper: assert the hook exits 0 and does NOT emit BLOCKED for the given path
+assert_path_allowed() {
+  local file_path="$1"
+  run run_hook_with_file "$file_path"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# Helper: assert the hook BLOCKS the given path
+assert_path_blocked() {
+  local file_path="$1"
+  run run_hook_with_file "$file_path"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# --- Exclusion tests (functional) ---
+
+# Claude Code passes absolute file paths in tool_input.file_path, so tests
+# use $PWD-prefixed paths to match the real shape (after the P004 root check).
 
 @test "enforce: excludes CSS files" {
-  file_is_excluded '\.css'
+  assert_path_allowed "$PWD/src/styles.css"
 }
 
 @test "enforce: excludes image files" {
-  file_is_excluded '\.png'
+  assert_path_allowed "$PWD/public/logo.png"
 }
 
 @test "enforce: excludes font files" {
-  file_is_excluded '\.woff'
+  assert_path_allowed "$PWD/public/fonts/regular.woff"
 }
 
 @test "enforce: excludes lockfiles" {
-  file_is_excluded 'package-lock.json'
+  assert_path_allowed "$PWD/package-lock.json"
 }
 
 @test "enforce: excludes changeset files" {
-  file_is_excluded '\.changeset'
+  assert_path_allowed "$PWD/.changeset/some-change.md"
 }
 
 @test "enforce: excludes memory files" {
-  file_is_excluded 'MEMORY.md'
+  assert_path_allowed "$PWD/MEMORY.md"
 }
 
 @test "enforce: excludes plan files" {
-  file_is_excluded '\.claude/plans'
+  assert_path_allowed "$PWD/.claude/plans/2026-01-01-plan.md"
 }
 
 @test "enforce: excludes risk reports" {
-  file_is_excluded '\.risk-reports'
+  assert_path_allowed "$PWD/.risk-reports/2026-01-01.md"
 }
 
 @test "enforce: excludes RISK-POLICY.md" {
-  file_is_excluded 'RISK-POLICY.md'
+  assert_path_allowed "$PWD/RISK-POLICY.md"
+}
+
+@test "enforce: does NOT exempt by UI-only extension (ADR-007/008)" {
+  # ADR-007/008 broadened scope: the hook must gate UI files like any
+  # other source file, not silently allow them.
+  assert_path_blocked "$PWD/src/Component.tsx"
+}
+
+@test "enforce: does NOT exempt .html files (ADR-007/008)" {
+  assert_path_blocked "$PWD/public/index.html"
 }
 
-@test "enforce: does NOT have UI-only case guard" {
-  ! grep -q '\*) exit 0 ;;' "$HOOK"
+@test "enforce: does NOT exempt .vue files (ADR-007/008)" {
+  assert_path_blocked "$PWD/src/App.vue"
 }
 
 # --- Functional tests (execute hook with mock JSON) ---

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

@@ -1,19 +1,163 @@
 #!/usr/bin/env bats
 
-# Tests for JTBD mark-reviewed hook — verifies hash path supports both formats
+# Tests for jtbd-mark-reviewed.sh — verifies the PostToolUse:Agent hook
+# creates session markers and stores the right policy-path hash when
+# wr-jtbd:agent (or legacy jtbd-lead) returns a PASS verdict.
+#
+# Per ADR-005 (P011): assertions are functional — execute the hook with
+# mock JSON, assert on side-effects (marker files, hash file contents).
+# Source-grep assertions for "the script mentions docs/jtbd" were
+# removed because they passed even when the surrounding code path was
+# unreachable.
 
-@test "mark-reviewed supports docs/jtbd directory path" {
+setup() {
   SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+  HOOK="$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  SESSION_ID="test-session-$$"
+  MARKER="/tmp/jtbd-reviewed-${SESSION_ID}"
+  PLAN_MARKER="/tmp/jtbd-plan-reviewed-${SESSION_ID}"
+  HASH_FILE="/tmp/jtbd-reviewed-${SESSION_ID}.hash"
+  VERDICT_FILE="/tmp/jtbd-verdict"
+  rm -f "$MARKER" "$PLAN_MARKER" "$HASH_FILE" "$VERDICT_FILE"
 }
 
-@test "mark-reviewed supports docs/JOBS_TO_BE_DONE.md fallback" {
-  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  grep -q 'docs/JOBS_TO_BE_DONE.md' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  rm -f "$MARKER" "$PLAN_MARKER" "$HASH_FILE" "$VERDICT_FILE"
 }
 
-@test "enforce-edit and mark-reviewed both support docs/jtbd" {
-  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
-  grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-enforce-edit.sh"
-  grep -q '"docs/jtbd"' "$SCRIPT_DIR/jtbd-mark-reviewed.sh"
+# Helper: pipe a PostToolUse:Agent JSON to the hook for the given subagent.
+run_hook() {
+  local subagent="$1"
+  local json="{\"tool_input\":{\"subagent_type\":\"${subagent}\"},\"session_id\":\"${SESSION_ID}\"}"
+  echo "$json" | bash "$HOOK"
+}
+
+# --- Path support: docs/jtbd directory (preferred) ---
+
+@test "uses docs/jtbd directory when present (creates marker + hash)" {
+  mkdir -p docs/jtbd/solo-developer
+  echo "# Persona" > docs/jtbd/solo-developer/persona.md
+  echo "# Index" > docs/jtbd/README.md
+  echo "PASS" > "$VERDICT_FILE"
+
+  run_hook "wr-jtbd:agent"
+
+  [ -f "$MARKER" ]
+  [ -f "$HASH_FILE" ]
+  [ "$(cat "$HASH_FILE")" != "missing" ]
+  [ -n "$(cat "$HASH_FILE")" ]
+}
+
+@test "directory hash excludes README.md (only persona/job files contribute)" {
+  mkdir -p docs/jtbd
+  echo "# Index" > docs/jtbd/README.md
+  echo "PASS" > "$VERDICT_FILE"
+  run_hook "wr-jtbd:agent"
+  HASH_README_ONLY="$(cat "$HASH_FILE")"
+
+  rm -f "$HASH_FILE" "$MARKER"
+  echo "different content" >> docs/jtbd/README.md
+  echo "PASS" > "$VERDICT_FILE"
+  run_hook "wr-jtbd:agent"
+  HASH_README_CHANGED="$(cat "$HASH_FILE")"
+
+  # Changing README.md alone must not change the hash — README is excluded.
+  [ "$HASH_README_ONLY" = "$HASH_README_CHANGED" ]
+}
+
+# --- Path support: docs/JOBS_TO_BE_DONE.md fallback (legacy) ---
+
+@test "uses docs/JOBS_TO_BE_DONE.md when docs/jtbd does not exist" {
+  mkdir -p docs
+  echo "# Jobs" > docs/JOBS_TO_BE_DONE.md
+  echo "PASS" > "$VERDICT_FILE"
+
+  run_hook "wr-jtbd:agent"
+
+  [ -f "$MARKER" ]
+  [ -f "$HASH_FILE" ]
+  [ "$(cat "$HASH_FILE")" != "missing" ]
+
+  # Hash should match the file's content hash. _hashcmd in
+  # gate-helpers.sh prefers md5sum, falls back to md5 -r, then shasum.
+  EXPECTED=$(cat docs/JOBS_TO_BE_DONE.md \
+             | (md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null) \
+             | cut -d' ' -f1)
+  [ "$(cat "$HASH_FILE")" = "$EXPECTED" ]
+}
+
+@test "prefers docs/jtbd over docs/JOBS_TO_BE_DONE.md when both exist" {
+  mkdir -p docs/jtbd
+  echo "# job" > docs/jtbd/job.md
+  echo "# legacy jobs" > docs/JOBS_TO_BE_DONE.md
+  echo "PASS" > "$VERDICT_FILE"
+
+  run_hook "wr-jtbd:agent"
+
+  # The directory-derived hash must NOT equal the standalone-file hash.
+  DIR_HASH="$(cat "$HASH_FILE")"
+  FILE_HASH=$(cat docs/JOBS_TO_BE_DONE.md \
+              | (md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null) \
+              | cut -d' ' -f1)
+  [ "$DIR_HASH" != "$FILE_HASH" ]
+}
+
+# --- Verdict handling ---
+
+@test "FAIL verdict does NOT create review marker (but plan marker still set)" {
+  mkdir -p docs/jtbd
+  echo "# job" > docs/jtbd/job.md
+  echo "FAIL" > "$VERDICT_FILE"
+
+  run_hook "wr-jtbd:agent"
+
+  [ ! -f "$MARKER" ]
+  [ -f "$PLAN_MARKER" ]
+}
+
+@test "missing verdict file allows marker (backward compat)" {
+  mkdir -p docs/jtbd
+  echo "# job" > docs/jtbd/job.md
+
+  run_hook "wr-jtbd:agent"
+
+  [ -f "$MARKER" ]
+}
+
+@test "verdict file is consumed (removed) after hook runs" {
+  mkdir -p docs/jtbd
+  echo "# job" > docs/jtbd/job.md
+  echo "PASS" > "$VERDICT_FILE"
+
+  run_hook "wr-jtbd:agent"
+
+  [ ! -f "$VERDICT_FILE" ]
+}
+
+# --- Subagent routing ---
+
+@test "ignores unrelated subagent (no marker created)" {
+  mkdir -p docs/jtbd
+  echo "# job" > docs/jtbd/job.md
+  echo "PASS" > "$VERDICT_FILE"
+
+  run_hook "wr-architect:agent"
+
+  [ ! -f "$MARKER" ]
+  [ ! -f "$PLAN_MARKER" ]
+}
+
+@test "matches legacy jtbd-lead subagent name" {
+  mkdir -p docs/jtbd
+  echo "# job" > docs/jtbd/job.md
+  echo "PASS" > "$VERDICT_FILE"
+
+  run_hook "jtbd-lead"
+
+  [ -f "$MARKER" ]
 }

package/package.json

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

package/skills/review-jobs/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: wr-jtbd:review-jobs
+description: On-demand JTBD alignment review. Checks staged changes and recent commits against documented persona jobs in docs/jtbd/. Use before a release or when adding new features.
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion, Skill
+---
+
+# JTBD Alignment Review Skill
+
+Run a Jobs To Be Done alignment review on demand — outside the pre-tool-use hook gate. Reviews staged changes and recent commits against the documented persona jobs in `docs/jtbd/`.
+
+This skill is **read-only**. It does not commit, push, or modify files.
+
+## When to use
+
+- Pre-flight before a release or client handover: confirm delivered features trace to documented persona needs
+- When adding new features: verify the feature serves a documented JTBD before building
+- After a significant capability change: check whether existing jobs are still served
+- Any time the hook gate is not convenient: planning mode, spike work, design review
+
+## Steps
+
+### 1. Parse arguments
+
+Read `$ARGUMENTS` for an explicit review scope (e.g., "review the new skill I just wrote", "check persona alignment for the release", "does this feature serve a documented job?"). If a scope is provided, use it. If empty, proceed to auto-detection.
+
+### 2. Auto-detect context
+
+Run the following to establish what needs reviewing:
+
+```bash
+# Staged changes
+git diff --cached --stat
+git diff --cached --name-only
+
+# Recent commits not yet pushed
+git log origin/$(git rev-parse --abbrev-ref HEAD)..HEAD --oneline 2>/dev/null || git log HEAD -5 --oneline
+
+# All unstaged changes
+git diff --name-only HEAD
+```
+
+Summarise:
+- Files staged or recently committed
+- Whether the changes are feature additions, behavioural changes, or purely documentary
+
+### 3. Resolve ambiguity
+
+If there are no staged changes and no recent unpushed commits, use `AskUserQuestion` to ask:
+
+> "I don't see any staged or unpushed changes. What would you like me to review?
+> (a) A specific set of files or a planned feature — please describe it
+> (b) All changes since the last tag
+> (c) Cancel"
+
+Do not ask if there is an obvious set of changed files.
+
+### 4. Construct the assessment prompt
+
+Build a self-contained prompt for the JTBD subagent that includes:
+- The list of changed/staged files
+- The git diff summary (stat output)
+- Any explicit scope from the user
+- The request: "Review these changes against the project's documented JTBD personas and jobs. Identify which jobs are served, whether any gaps exist (changes that don't trace to a documented job), and whether any jobs are unintentionally broken."
+
+### 5. Delegate to wr-jtbd:agent
+
+Invoke the JTBD subagent via the `Skill` tool:
+
+```
+subagent_type: wr-jtbd:agent
+prompt: <constructed review prompt from step 4>
+```
+
+Wait for the subagent to complete.
+
+### 6. Present results
+
+Present the full alignment report to the user. The JTBD subagent will report:
+- PASS: changes trace to documented jobs, no gaps
+- GAPS: changes that don't trace to any documented job — new JTBD entry may be needed
+- BREAKS: changes that appear to remove or degrade a documented job outcome
+- NEW JOB NEEDED: capabilities being added that serve an undocumented need
+
+If gaps or breaks are identified, use `AskUserQuestion` to ask how the user wants to proceed:
+- (a) Document the new job before continuing (recommended)
+- (b) Proceed with a documented exception
+- (c) Revise the approach to serve an existing job
+
+Do not make the decision unilaterally — per ADR-013 Rule 1, JTBD alignment decisions are the user's.
+
+$ARGUMENTS