@windyroad/jtbd 0.5.0 → 0.5.1-preview.103

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-jtbd",
-  "version": "0.1.0",
+  "version": "0.5.1",
   "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:

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/bin/install.mjs

@@ -37,7 +37,7 @@ utils.checkPrerequisites();
 if (flags.uninstall) {
   utils.uninstallPackage(PLUGIN);
 } else if (flags.update) {
-  utils.updatePackage(PLUGIN);
+  utils.updatePackage(PLUGIN, { scope: flags.scope });
 } else {
   utils.installPackage(PLUGIN, { deps: DEPS, scope: flags.scope });
 }

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/lib/install-utils.mjs

@@ -62,8 +62,11 @@ export function installPlugin(pluginName, { scope = "project" } = {}) {
   );
 }
 
-export function updatePlugin(pluginName) {
-  return run(`claude plugin update ${pluginName}`, pluginName);
+export function updatePlugin(pluginName, { scope = "project" } = {}) {
+  return run(
+    `claude plugin update "${pluginName}@${MARKETPLACE_NAME}" --scope ${scope}`,
+    pluginName
+  );
 }
 
 export function uninstallPlugin(pluginName) {
@@ -94,14 +97,14 @@ export function installPackage(pluginName, { deps = [], scope = "project" } = {}
 /**
  * Update a single package.
  */
-export function updatePackage(pluginName) {
+export function updatePackage(pluginName, { scope = "project" } = {}) {
   console.log(`\nUpdating @windyroad/${pluginName.replace("wr-", "")}...\n`);
 
   run(
     `claude plugin marketplace update ${MARKETPLACE_NAME}`,
     "Updating marketplace"
   );
-  updatePlugin(pluginName);
+  updatePlugin(pluginName, { scope });
 
   console.log("\nDone! Restart Claude Code to apply updates.\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/jtbd",
-  "version": "0.5.0",
+  "version": "0.5.1-preview.103",
   "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