@windyroad/jtbd 0.5.1 → 0.5.2

package/.claude-plugin/plugin.json

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

package/agents/agent.md

@@ -45,6 +45,10 @@ All review criteria come from the JTBD documentation. Read the docs first and ap
 - If the change involves API interactions, do the actions align with the job's expected flow?
 - Are new actions documented in the relevant job's action list?
 
+## Output Formatting
+
+When referencing JTBD IDs, problem IDs (P<NNN>), or ADR IDs in prose output, always include the human-readable title on first mention. Use the format `JTBD-001 (Enforce Governance Without Slowing Down)`, not bare `JTBD-001`.
+
 ## How to Report
 
 If the change aligns with documented jobs:
@@ -82,12 +86,28 @@ If the code serves a user type not described by the existing persona:
 
 These are FAIL verdicts — the JTBD documentation must be updated before the code can proceed.
 
-## Verdict
+## Output Contract (P037)
+
+Your response has two communication channels. Both are required; neither replaces the other.
+
+**1. Inline response (primary, user-facing, REQUIRED in every response):**
+
+Every response MUST begin with one of the four verdict templates from "How to Report" above — `JTBD Review: PASS`, `JTBD Review: ISSUES FOUND`, `JTBD Review: JOB UPDATE NEEDED`, or `JTBD Review: PERSONA UPDATE NEEDED`. The inline verdict is the authoritative primary channel — it is what the caller reads and acts on.
+
+- On **PASS**: include the aligned job ID, a brief alignment summary, and the persona-fit confirmation (which constraints were checked).
+- On **ISSUES FOUND / JOB UPDATE NEEDED / PERSONA UPDATE NEEDED**: include actionable remediation guidance — the specific file + line, the issue, the affected job (or "no matching job"), and the fix (what would need to change for the review to pass).
+
+You MUST NOT emit a bare verdict without body. "FAIL" alone, "ISSUES FOUND" alone, or a list of reviewed files without a verdict line are all forbidden output shapes. If there are no issues, emit PASS with alignment summary; if there are issues, emit ISSUES FOUND with at least one concrete remediation item. Every response must contain enough inline detail that the caller can act without a re-query.
+
+**2. Verdict marker file (internal signal, REQUIRED to coordinate with hooks):**
+
+After emitting your inline response, write your verdict to `/tmp/jtbd-verdict`. This file is consumed by the `jtbd-mark-reviewed.sh` PostToolUse hook to gate subsequent edits. It is NOT a substitute for the inline response:
 
-After completing your review, write your verdict to `/tmp/jtbd-verdict`:
 - `printf 'PASS' > /tmp/jtbd-verdict` — change aligns with documented jobs and persona
 - `printf 'FAIL' > /tmp/jtbd-verdict` — misalignment, job gap, or persona gap detected
 
+The inline verdict and the marker file MUST agree. If inline says PASS, the file says PASS; if inline says ISSUES FOUND / JOB UPDATE NEEDED / PERSONA UPDATE NEEDED, the file says FAIL.
+
 ## Constraints
 
 - You are read-only. You do not edit files (except writing the verdict file).

package/agents/test/jtbd-output-formatting.bats

@@ -0,0 +1,26 @@
+#!/usr/bin/env bats
+# Doc-lint guard: jtbd agent.md must include the output formatting rule
+# requiring human-readable titles alongside bare IDs (P032).
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+#
+# Cross-reference:
+#   P032 (agent output uses opaque IDs without titles)
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+
+setup() {
+  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  AGENT_FILE="${AGENT_DIR}/agent.md"
+}
+
+@test "agent.md contains output formatting section" {
+  run grep -n "## Output Formatting" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md output formatting rule requires titles with IDs (P032)" {
+  run grep -n "title" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+  run grep -n "Output Formatting" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}

package/agents/test/jtbd-verdict-contract.bats

@@ -0,0 +1,57 @@
+#!/usr/bin/env bats
+# Doc-lint guard: wr-jtbd:agent output contract — the agent MUST emit a
+# structured inline verdict in every response, regardless of the
+# /tmp/jtbd-verdict file write. Closes P037 (JTBD reviewer sometimes
+# returns a bare verdict without remediation reason).
+#
+# Structural assertion — Permitted Exception to the source-grep ban
+# (ADR-005 / P011).
+#
+# Cross-reference:
+#   P037 (JTBD reviewer bare-verdict bug)
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+
+setup() {
+  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  AGENT_FILE="${AGENT_DIR}/agent.md"
+}
+
+@test "agent.md contains inline verdict templates (How to Report section)" {
+  run grep -n "How to Report" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md declares inline output is REQUIRED in every response (P037)" {
+  # Must say inline output is required / must be emitted every time.
+  run grep -niE "(always|every|must|required).*inline|inline.*(always|every|must|required)" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md declares the primary communication channel is inline, not the file (P037)" {
+  # Must clarify the verdict file is an internal signal, not a replacement for inline output
+  run grep -niE "(primary|authoritative).*(inline|user-facing|response)|inline.*(primary|authoritative)" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md requires a specific verdict line on every response (PASS or ISSUES FOUND)" {
+  # The verdict line is explicit - bold JTBD Review: PASS / ISSUES FOUND
+  run grep -nE "JTBD Review: (PASS|ISSUES FOUND|JOB UPDATE NEEDED|PERSONA UPDATE NEEDED)" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md requires remediation guidance on every FAIL verdict (P037)" {
+  # On ISSUES FOUND the agent must include actionable guidance (what to change / what job / what fix)
+  run grep -niE "remediation|actionable|what (should|would need)|fix:|issue:" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md cross-references P037 so readers can trace the contract's origin" {
+  run grep -n "P037" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md explicitly forbids bare verdict without reason (P037)" {
+  # Directly addresses the observed bug: verdict without body
+  run grep -niE "(must not|MUST NOT|do not|DO NOT|never) (emit|return|produce) (a )?bare|without (reason|remediation|detail|actionable|explanation)" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}

package/hooks/jtbd-eval.sh

@@ -22,7 +22,10 @@ REQUIRED ACTIONS:
 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.
+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'
@@ -42,7 +45,10 @@ REQUIRED ACTIONS:
 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.
+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
 else
   cat <<'HOOK_OUTPUT'

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

@@ -0,0 +1,39 @@
+#!/usr/bin/env bats
+
+# Tests for jtbd-eval.sh (UserPromptSubmit) — verifies the injected scope
+# exclusion text lists governance docs that the PreToolUse gate already
+# exempts (P029). Without this, the LLM wastes time delegating to the
+# jtbd-lead for files the edit gate would allow anyway.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/jtbd-eval.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  mkdir -p docs/jtbd
+  echo "# Index" > docs/jtbd/README.md
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+}
+
+@test "eval: scope text mentions problem files exemption (P029)" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"docs/problems/"* ]] || [[ "$output" == *"problem tickets"* ]]
+}
+
+@test "eval: scope text mentions BRIEFING.md exemption (P029)" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BRIEFING"* ]]
+}
+
+@test "eval: scope text mentions RISK-POLICY exemption (P029)" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"RISK-POLICY"* ]]
+}

package/package.json

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

package/skills/review-jobs/SKILL.md

@@ -17,6 +17,10 @@ This skill is **read-only**. It does not commit, push, or modify files.
 - 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
 
+## Output Formatting
+
+When referencing JTBD IDs, problem IDs (P<NNN>), or ADR IDs in prose output, always include the human-readable title on first mention. Use the format `JTBD-001 (Enforce Governance Without Slowing Down)`, not bare `JTBD-001`.
+
 ## Steps
 
 ### 1. Parse arguments