@windyroad/jtbd 0.5.2 → 0.6.0

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-jtbd",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Jobs-to-be-done enforcement for Claude Code"
 }

package/agents/agent.md

@@ -1,9 +1,8 @@
 ---
 name: agent
 description: Jobs To Be Done reviewer. Use before editing any project file.
-  Reads docs/jtbd/ (or docs/JOBS_TO_BE_DONE.md) and reviews proposed changes
-  against documented jobs, persona constraints, and screen mappings. Reports alignment
-  or gaps.
+  Reads docs/jtbd/ and reviews proposed changes against documented jobs,
+  persona constraints, and screen mappings. Reports alignment or gaps.
 tools:
   - Read
   - Glob

package/hooks/jtbd-enforce-edit.sh

@@ -1,7 +1,10 @@
 #!/bin/bash
 # JTBD - PreToolUse enforcement hook
 # BLOCKS Edit/Write to project files until jtbd-lead is consulted.
-# Supports both docs/jtbd/ directory (preferred) and docs/JOBS_TO_BE_DONE.md (legacy).
+# Canonical layout is docs/jtbd/ only (ADR-008, Option 3 chosen 2026-04-20).
+# Projects still on legacy single-file docs/JOBS_TO_BE_DONE.md must run
+# /wr-jtbd:update-guide to migrate — the gate is inactive until the
+# directory layout exists.
 # Uses shared review-gate.sh for TTL, drift detection, and fail-closed.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -77,18 +80,16 @@ case "$FILE_PATH" in
     exit 0 ;;
   */docs/jtbd/*|docs/jtbd/*)
     exit 0 ;;
-  */docs/JOBS_TO_BE_DONE.md|docs/JOBS_TO_BE_DONE.md)
-    exit 0 ;;
   */docs/PRODUCT_DISCOVERY.md|docs/PRODUCT_DISCOVERY.md)
     exit 0 ;;
 esac
 
-# Determine JTBD path — prefer directory, fall back to single file
+# 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.
 JTBD_PATH=""
 if [ -d "docs/jtbd" ]; then
   JTBD_PATH="docs/jtbd"
-elif [ -f "docs/JOBS_TO_BE_DONE.md" ]; then
-  JTBD_PATH="docs/JOBS_TO_BE_DONE.md"
 fi
 
 # If no JTBD docs exist, block and direct to create skill

package/hooks/jtbd-eval.sh

@@ -1,8 +1,11 @@
 #!/bin/bash
 # JTBD - UserPromptSubmit hook
-# Detects JTBD docs in the project and injects delegation instruction.
-# Supports both docs/jtbd/ directory (preferred) and docs/JOBS_TO_BE_DONE.md (legacy).
-# If neither exists, instructs Claude to create via the update-guide skill.
+# Detects the docs/jtbd/ directory in the project and injects the
+# delegation instruction. Canonical layout is docs/jtbd/ only
+# (ADR-008, Option 3 chosen 2026-04-20). Legacy docs/JOBS_TO_BE_DONE.md
+# is NOT consulted at runtime — projects still on that layout must run
+# /wr-jtbd:update-guide to migrate. The update-guide skill is the sole
+# component permitted to read the legacy file (for one-shot migration).
 
 if [ -f "docs/jtbd/README.md" ]; then
   cat <<'HOOK_OUTPUT'
@@ -24,36 +27,14 @@ REQUIRED ACTIONS:
 SCOPE: All project files.
 Does NOT apply to: CSS, images, fonts, lockfiles, changesets, memory files,
 plan files, docs/problems/ (problem tickets), docs/BRIEFING.md,
-RISK-POLICY.md, .risk-reports/, docs/jtbd/, docs/JOBS_TO_BE_DONE.md,
-docs/PRODUCT_DISCOVERY.md, docs/VOICE-AND-TONE.md, docs/STYLE-GUIDE.md.
-HOOK_OUTPUT
-elif [ -f "docs/JOBS_TO_BE_DONE.md" ]; then
-  cat <<'HOOK_OUTPUT'
-INSTRUCTION: MANDATORY JTBD CHECK. YOU MUST FOLLOW THIS.
-DETECTED: docs/JOBS_TO_BE_DONE.md exists in this project.
-
-This is a NON-OPTIONAL instruction. You MUST use the jtbd-lead agent
-before editing any project file. This is proactive. Do not wait for the
-user to ask.
-
-REQUIRED ACTIONS:
-1. Use the Agent tool to delegate to wr-jtbd:agent
-   (subagent_type: "wr-jtbd:agent")
-2. The jtbd-lead will review proposed changes against docs/JOBS_TO_BE_DONE.md
-   and PRODUCT_DISCOVERY.md persona definitions
-3. Do NOT write or edit project files without jtbd-lead review FIRST
-4. Do NOT skip this step even if you think you can handle it yourself
-
-SCOPE: All project files.
-Does NOT apply to: CSS, images, fonts, lockfiles, changesets, memory files,
-plan files, docs/problems/ (problem tickets), docs/BRIEFING.md,
-RISK-POLICY.md, .risk-reports/, docs/jtbd/, docs/JOBS_TO_BE_DONE.md,
+RISK-POLICY.md, .risk-reports/, docs/jtbd/,
 docs/PRODUCT_DISCOVERY.md, docs/VOICE-AND-TONE.md, docs/STYLE-GUIDE.md.
 HOOK_OUTPUT
 else
   cat <<'HOOK_OUTPUT'
-NOTE: This project has no docs/jtbd/ directory or docs/JOBS_TO_BE_DONE.md.
-Edits to project files will be blocked until a JTBD document exists.
-Run /wr-jtbd:update-guide to generate one.
+NOTE: This project has no docs/jtbd/ directory. Edits to project files
+will be blocked until a JTBD document exists. Run /wr-jtbd:update-guide
+to generate one. If the project has a legacy docs/JOBS_TO_BE_DONE.md,
+update-guide will migrate it into the directory layout (ADR-008 Option 3).
 HOOK_OUTPUT
 fi

package/hooks/jtbd-mark-reviewed.sh

@@ -1,7 +1,8 @@
 #!/bin/bash
 # JTBD - PostToolUse hook for Agent tool
 # Creates session markers when jtbd-lead has been consulted with PASS verdict.
-# Supports both docs/jtbd/ directory (preferred) and docs/JOBS_TO_BE_DONE.md (legacy).
+# Canonical layout is docs/jtbd/ only (ADR-008, Option 3 chosen 2026-04-20).
+# Legacy docs/JOBS_TO_BE_DONE.md is NOT consulted at runtime.
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/review-gate.sh"
@@ -15,11 +16,13 @@ if [ -z "$SESSION_ID" ]; then
   exit 0
 fi
 
-# Determine JTBD path — prefer directory, fall back to single file
-JTBD_PATH="docs/JOBS_TO_BE_DONE.md"
-if [ -d "docs/jtbd" ]; then
-  JTBD_PATH="docs/jtbd"
+# Canonical JTBD path — directory only (ADR-008 Option 3). If the
+# directory doesn't exist the marker is not stored; the gate will
+# surface a "run update-guide" recommendation on the next edit.
+if [ ! -d "docs/jtbd" ]; then
+  exit 0
 fi
+JTBD_PATH="docs/jtbd"
 
 case "$SUBAGENT" in
   *jtbd-lead*|*wr-jtbd*)

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

@@ -117,10 +117,16 @@ assert_path_blocked() {
   [[ "$output" != *"BLOCKED"* ]]
 }
 
-@test "functional: exempts docs/JOBS_TO_BE_DONE.md (backward compat)" {
+@test "functional: docs/JOBS_TO_BE_DONE.md is NOT an exempt governance artefact (ADR-008 Option 3, P019)" {
+  # Legacy single-file path is no longer a recognised governance artefact.
+  # When docs/jtbd/ exists the gate should fire against edits to the
+  # legacy file (it is not exempt). When docs/jtbd/ does not exist the
+  # gate blocks with an update-guide suggestion (covered separately).
+  mkdir -p docs/jtbd
+  echo "# Index" > docs/jtbd/README.md
   run run_hook_with_file "docs/JOBS_TO_BE_DONE.md"
   [ "$status" -eq 0 ]
-  [[ "$output" != *"BLOCKED"* ]]
+  [[ "$output" == *"BLOCKED"* ]]
 }
 
 @test "functional: blocks src/index.ts when no JTBD docs exist" {

package/hooks/test/jtbd-eval.bats

@@ -1,6 +1,8 @@
 #!/usr/bin/env bats
 
-# Tests for jtbd-eval.sh — verifies JTBD suggestion fires for any project
+# Tests for jtbd-eval.sh — verifies JTBD suggestion fires for any project.
+# Canonical layout is docs/jtbd/ only (ADR-008 Option 3 chosen 2026-04-20).
+# Legacy docs/JOBS_TO_BE_DONE.md is NOT consulted at runtime (P019).
 
 setup() {
   SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
@@ -15,14 +17,14 @@ teardown() {
   rm -rf "$TEST_DIR"
 }
 
-@test "eval: suggests update-guide when JOBS_TO_BE_DONE.md missing (no UI files)" {
+@test "eval: suggests update-guide when docs/jtbd/ missing (no UI files)" {
   # No UI files, no docs — should still suggest
   run bash "$HOOK"
   [ "$status" -eq 0 ]
   [[ "$output" == *"wr-jtbd:update-guide"* ]]
 }
 
-@test "eval: suggests update-guide when JOBS_TO_BE_DONE.md missing (with UI files)" {
+@test "eval: suggests update-guide when docs/jtbd/ missing (with UI files)" {
   mkdir -p src
   touch src/App.tsx
   run bash "$HOOK"
@@ -30,29 +32,34 @@ teardown() {
   [[ "$output" == *"wr-jtbd:update-guide"* ]]
 }
 
-@test "eval: injects enforcement instruction when JOBS_TO_BE_DONE.md exists" {
-  mkdir -p docs
-  echo "# Jobs" > docs/JOBS_TO_BE_DONE.md
+@test "eval: injects enforcement when docs/jtbd/README.md exists" {
+  mkdir -p docs/jtbd
+  echo "# Index" > docs/jtbd/README.md
   run bash "$HOOK"
   [ "$status" -eq 0 ]
   [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
 }
 
-@test "eval: injects enforcement when docs/jtbd/README.md exists" {
-  mkdir -p docs/jtbd
-  echo "# Index" > docs/jtbd/README.md
+@test "eval: does NOT consult legacy docs/JOBS_TO_BE_DONE.md (ADR-008 Option 3, P019)" {
+  # Legacy single-file layout — gate must NOT inject the enforcement
+  # instruction; instead it should suggest update-guide so the project
+  # migrates into the directory layout.
+  mkdir -p docs
+  echo "# Jobs" > docs/JOBS_TO_BE_DONE.md
   run bash "$HOOK"
   [ "$status" -eq 0 ]
-  [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
+  [[ "$output" != *"MANDATORY JTBD CHECK"* ]]
+  [[ "$output" == *"wr-jtbd:update-guide"* ]]
 }
 
-@test "eval: prefers docs/jtbd/ over docs/JOBS_TO_BE_DONE.md when both exist" {
+@test "eval: uses docs/jtbd/ when both layouts coexist (ADR-008 Option 3)" {
   mkdir -p docs/jtbd
   echo "# Index" > docs/jtbd/README.md
   echo "# Jobs" > docs/JOBS_TO_BE_DONE.md
   run bash "$HOOK"
   [ "$status" -eq 0 ]
   [[ "$output" == *"docs/jtbd"* ]]
+  [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
 }
 
 @test "eval: does not reference UI-only scoping in output" {

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

@@ -70,28 +70,24 @@ run_hook() {
   [ "$HASH_README_ONLY" = "$HASH_README_CHANGED" ]
 }
 
-# --- Path support: docs/JOBS_TO_BE_DONE.md fallback (legacy) ---
+# --- Path support: docs/jtbd/ is the sole canonical layout (ADR-008 Option 3, P019) ---
 
-@test "uses docs/JOBS_TO_BE_DONE.md when docs/jtbd does not exist" {
+@test "does NOT store a review hash when only legacy docs/JOBS_TO_BE_DONE.md exists (P019)" {
+  # Legacy single-file layout — the mark-reviewed hook must exit early
+  # without storing a hash, because the enforce hook cannot gate the
+  # project until it runs /wr-jtbd:update-guide to migrate to docs/jtbd/.
   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" ]
+  # No marker, no hash file — the gate is inactive on legacy-layout projects.
+  [ ! -f "$MARKER" ]
+  [ ! -f "$HASH_FILE" ]
 }
 
-@test "prefers docs/jtbd over docs/JOBS_TO_BE_DONE.md when both exist" {
+@test "hashes docs/jtbd/ when both layouts coexist (legacy single-file is ignored, P019)" {
   mkdir -p docs/jtbd
   echo "# job" > docs/jtbd/job.md
   echo "# legacy jobs" > docs/JOBS_TO_BE_DONE.md
@@ -99,7 +95,8 @@ run_hook() {
 
   run_hook "wr-jtbd:agent"
 
-  # The directory-derived hash must NOT equal the standalone-file hash.
+  # The directory-derived hash must NOT equal the standalone-file hash —
+  # proves the hook did not consult the legacy file.
   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) \

package/package.json

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

package/skills/update-guide/SKILL.md

@@ -50,6 +50,14 @@ Check in order of preference:
 If migrating from `docs/JOBS_TO_BE_DONE.md`, extract existing personas and jobs and
 convert them into the directory structure. Ask the user before proceeding.
 
+**Migration carve-out (ADR-008 Option 3 chosen 2026-04-20, P019)**: this skill is the
+**sole component** in the plugin suite permitted to read `docs/JOBS_TO_BE_DONE.md`.
+Every other component (eval hook, enforce hook, mark-reviewed hook, wr-jtbd:agent,
+CI validation) reads only `docs/jtbd/`. Do NOT strip this read path from this skill
+during future cleanup — it is the one-shot migration bridge for legacy projects. The
+Reassessment Criteria in ADR-008 list the sunset trigger (no legacy-layout projects
+remaining).
+
 ### 3. Draft personas
 
 For each persona (2-4), create a file at `docs/jtbd/<persona-name>/persona.md`:
@@ -155,7 +163,10 @@ Write `docs/jtbd/README.md` with tables grouping jobs by persona and status:
 
 ### 8. Handle legacy file
 
-If `docs/JOBS_TO_BE_DONE.md` exists, replace its content with a pointer:
+If `docs/JOBS_TO_BE_DONE.md` exists, after successfully migrating its content
+into the directory layout, recommend deleting it (git history is the archive,
+per ADR-008 Option 3 Consequences). If the user prefers to keep a stub for
+external links, offer to replace its content with a pointer:
 
 ```markdown
 # Jobs To Be Done
@@ -163,8 +174,15 @@ If `docs/JOBS_TO_BE_DONE.md` exists, replace its content with a pointer:
 Job definitions have been migrated to individual files in `docs/jtbd/`.
 Each persona has its own directory with a persona definition and individual
 job files. See `docs/jtbd/README.md` for the full index.
+
+This file is no longer consulted by the `@windyroad/jtbd` plugin at runtime
+(ADR-008 Option 3). It is retained only for external links.
 ```
 
+Default recommendation: delete the file once migration is confirmed. The
+repository's own `docs/JOBS_TO_BE_DONE.md` stub was deleted in the same
+commit that accepted ADR-008 Option 3 (P019).
+
 ### 9. Summary
 
 Report what was created: