@windyroad/jtbd 0.5.1-preview.75 → 0.5.1-preview.81

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/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-preview.75",
+  "version": "0.5.1-preview.81",
   "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