@windyroad/jtbd 0.6.0-preview.161 → 0.7.0-preview.168

package/.claude-plugin/plugin.json

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

package/hooks/jtbd-eval.sh

@@ -1,14 +1,26 @@
 #!/bin/bash
-# JTBD - UserPromptSubmit hook
+# JTBD - UserPromptSubmit hook (P095 / ADR-038)
 # 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).
+# (ADR-008, Option 3 chosen 2026-04-20).
+#
+# Progressive disclosure (ADR-038): full MANDATORY block on first
+# prompt; terse reminder on subsequent prompts in the same session.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=lib/session-marker.sh
+source "$SCRIPT_DIR/lib/session-marker.sh"
+
+INPUT=$(cat)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo "")
 
 if [ -f "docs/jtbd/README.md" ]; then
-  cat <<'HOOK_OUTPUT'
+  if has_announced "jtbd" "$SESSION_ID"; then
+    cat <<'HOOK_OUTPUT'
+MANDATORY JTBD gate active (docs/jtbd/ present). Delegate to wr-jtbd:agent before editing project files. See turn-1 instructions for full scope and exclusions.
+HOOK_OUTPUT
+  else
+    cat <<'HOOK_OUTPUT'
 INSTRUCTION: MANDATORY JTBD CHECK. YOU MUST FOLLOW THIS.
 DETECTED: docs/jtbd/ exists in this project.
 
@@ -30,6 +42,8 @@ plan files, docs/problems/ (problem tickets), docs/BRIEFING.md,
 RISK-POLICY.md, .risk-reports/, docs/jtbd/,
 docs/PRODUCT_DISCOVERY.md, docs/VOICE-AND-TONE.md, docs/STYLE-GUIDE.md.
 HOOK_OUTPUT
+    mark_announced "jtbd" "$SESSION_ID"
+  fi
 else
   cat <<'HOOK_OUTPUT'
 NOTE: This project has no docs/jtbd/ directory. Edits to project files

package/hooks/lib/session-marker.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Shared session-announcement marker helpers (P095 / ADR-038).
+#
+# Used by UserPromptSubmit hooks to gate verbose MANDATORY instruction
+# prose behind a once-per-session check. First prompt of a session emits
+# the full block AND calls mark_announced; subsequent prompts see the
+# marker via has_announced and emit only a terse reminder.
+#
+# Why no TTL or drift check (unlike review-gate.sh): announcement is
+# bookkeeping for prose verbosity, not enforcement. PreToolUse gates
+# still block unauthorised edits regardless of announcement state; the
+# delegated agent re-reads policy when it runs. Extending the marker's
+# lifetime across policy changes mid-session is safe — the gate, not
+# the announcement, is load-bearing.
+#
+# Marker path convention: /tmp/${SYSTEM}-announced-${SESSION_ID}
+# (mirrors the /tmp/${SYSTEM}-reviewed-${SESSION_ID} convention from
+# style-guide/voice-tone/risk-scorer review-gate.sh; the -announced-
+# suffix distinguishes announcement markers from clearance markers).
+#
+# Empty SESSION_ID fallback: has_announced returns 1 (not announced,
+# full block emits) and mark_announced is a no-op (no file written).
+# This covers manual hook invocation, test harnesses, and any rare
+# case where Claude Code does not pass a session_id on stdin.
+
+# Returns 0 if the hook for SYSTEM has already announced in SESSION_ID,
+# 1 otherwise. Empty SESSION_ID => returns 1 (never announced).
+#
+# Usage: has_announced "architect" "$SESSION_ID"
+has_announced() {
+  local SYSTEM="$1"
+  local SESSION_ID="$2"
+  [ -n "$SESSION_ID" ] || return 1
+  [ -f "/tmp/${SYSTEM}-announced-${SESSION_ID}" ]
+}
+
+# Writes the announcement marker for SYSTEM in SESSION_ID. Empty
+# SESSION_ID => no-op. Safe to call more than once per session.
+#
+# Usage: mark_announced "architect" "$SESSION_ID"
+mark_announced() {
+  local SYSTEM="$1"
+  local SESSION_ID="$2"
+  [ -n "$SESSION_ID" ] || return 0
+  : > "/tmp/${SYSTEM}-announced-${SESSION_ID}"
+}

package/hooks/test/jtbd-eval-once-per-session.bats

@@ -0,0 +1,87 @@
+#!/usr/bin/env bats
+
+# P095 / ADR-038: jtbd-eval.sh UserPromptSubmit hook must emit the full
+# MANDATORY block only on the first prompt of a session; subsequent
+# prompts emit a terse reminder.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/jtbd/hooks/jtbd-eval.sh"
+
+  WORKDIR="$(mktemp -d)"
+  mkdir -p "$WORKDIR/docs/jtbd"
+  : > "$WORKDIR/docs/jtbd/README.md"
+
+  SID="jtbd-eval-test-$$-$RANDOM"
+}
+
+teardown() {
+  rm -f "/tmp/jtbd-announced-${SID}"
+  rm -f "/tmp/jtbd-announced-${SID}-alt"
+  rm -rf "$WORKDIR"
+}
+
+run_hook() {
+  local sid="$1"
+  (cd "$WORKDIR" && echo "{\"session_id\":\"$sid\"}" | bash "$HOOK")
+}
+
+@test "jtbd-eval: first invocation emits the full MANDATORY block" {
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -gt 400 ]
+  [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
+  [[ "$output" == *"wr-jtbd:agent"* ]]
+  [[ "$output" == *"SCOPE:"* ]]
+}
+
+@test "jtbd-eval: first invocation writes the announcement marker" {
+  run run_hook "$SID"
+  [ -f "/tmp/jtbd-announced-${SID}" ]
+}
+
+@test "jtbd-eval: second invocation emits only a terse reminder" {
+  run_hook "$SID" >/dev/null
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  [ "${#output}" -lt 250 ]
+  [[ "$output" == *"jtbd"* ]] || [[ "$output" == *"JTBD"* ]]
+  [[ "$output" == *"wr-jtbd:agent"* ]]
+  [[ "$output" != *"Does NOT apply to"* ]]
+}
+
+@test "jtbd-eval: terse reminder preserves the MANDATORY signal word" {
+  run_hook "$SID" >/dev/null
+  run run_hook "$SID"
+  [[ "$output" == *"MANDATORY"* ]] || [[ "$output" == *"REQUIRED"* ]] || [[ "$output" == *"NON-OPTIONAL"* ]]
+}
+
+@test "jtbd-eval: terse reminder names the trigger artifact" {
+  run_hook "$SID" >/dev/null
+  run run_hook "$SID"
+  [[ "$output" == *"docs/jtbd"* ]]
+}
+
+@test "jtbd-eval: different session_id re-emits the full block" {
+  run_hook "$SID" >/dev/null
+  local SID2="${SID}-alt"
+  run run_hook "$SID2"
+  [ "${#output}" -gt 400 ]
+  [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
+  rm -f "/tmp/jtbd-announced-${SID2}"
+}
+
+@test "jtbd-eval: empty session_id emits the full block and writes no marker" {
+  run run_hook ""
+  [ "${#output}" -gt 400 ]
+  [[ "$output" == *"MANDATORY JTBD CHECK"* ]]
+  [ ! -f "/tmp/jtbd-announced-" ]
+}
+
+@test "jtbd-eval: absent docs/jtbd/ emits the no-docs NOTE (unchanged by this ADR)" {
+  local NO_JTBD="$(mktemp -d)"
+  run bash -c "cd '$NO_JTBD' && echo '{\"session_id\":\"$SID\"}' | bash '$HOOK'"
+  [[ "$output" == *"no docs/jtbd/ directory"* ]]
+  [[ "$output" != *"MANDATORY JTBD CHECK"* ]]
+  rm -rf "$NO_JTBD"
+}

package/package.json

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