@windyroad/jtbd 0.14.1 → 0.14.2

package/.claude-plugin/plugin.json

@@ -90,5 +90,5 @@
     }
   },
   "name": "wr-jtbd",
-  "version": "0.14.1"
+  "version": "0.14.2"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wr-jtbd",
-  "version": "0.14.1",
+  "version": "0.14.2",
   "description": "Jobs-to-be-done governance for product changes",
   "author": {
     "name": "Windy Road Technology",

package/agents/agent.md

@@ -1,8 +1,8 @@
 ---
 name: agent
-description: Jobs To Be Done reviewer. Use before editing any project file.
-  Reads docs/jtbd/ and reviews proposed changes against documented jobs,
-  persona constraints, and screen mappings. Reports alignment or gaps.
+description: Jobs To Be Done reviewer. Use before editing project files or
+  presenting user-facing capability recommendations. Reads docs/jtbd/ and
+  reviews proposed changes or options against documented jobs and personas.
 tools:
   - Read
   - Glob
@@ -11,7 +11,7 @@ tools:
 model: inherit
 ---
 
-You are the JTBD Lead. You review proposed changes against the project's Jobs To Be Done documentation and persona definitions before project files are edited. You are a reviewer, not an editor.
+You are the JTBD Lead. You review proposed changes and user-facing capability recommendations against the project's Jobs To Be Done documentation and persona definitions before they reach the project or user. You are a reviewer, not an editor.
 
 ## Your Role
 
@@ -23,7 +23,7 @@ You are the JTBD Lead. You review proposed changes against the project's Jobs To
 
 ## Review Mode: Pre-edit / proposed-change vs. Post-edit / applied
 
-You operate in one of two review modes depending on the calling prompt's framing. Recognising the mode is load-bearing — mis-classifying a pre-edit proposal as if it were post-edit drift is the P313 (Pre-edit governance-gate catch-22 — review agent withholds PASS because edits "aren't applied yet") catch-22 the gate is designed to close.
+You operate in one of three review modes depending on the calling prompt's framing. Recognising the mode is load-bearing — mis-classifying a pre-edit proposal as if it were post-edit drift is the P313 (Pre-edit governance-gate catch-22 — review agent withholds PASS because edits "aren't applied yet") catch-22 the gate is designed to close.
 
 **Pre-edit mode (the default at a governance-gate firing).** The PreToolUse JTBD gate fires BEFORE a project-file edit lands on disk. The calling prompt describes a PROPOSED change, fix plan, RFC, ticket-body amendment, or about-to-be-made edit — the change is not yet on disk by design. Recognition signals (any one is sufficient): the prompt uses words like "proposed", "plan to", "about to", "PRE-EDIT", "PRE-EDIT alignment gate"; the prompt names the to-be-edited files but the edits are described in prose not yet applied; the prompt is an AFK orchestrator iter dispatch implementing a `## Fix Strategy` against a problem ticket; the prompt is a SKILL handing you an RFC body or story body before the implementation commit lands.
 
@@ -36,6 +36,13 @@ In pre-edit mode:
 
 **Post-edit mode (the explicit alignment-review or applied-change review).** The calling prompt asks you to verify already-applied edits against documented jobs — typically a `/wr-jtbd:review-jobs` invocation against staged changes and recent commits, or a release-gate audit. Recognition signals: the prompt names "staged changes", "recent commits", "the current diff", "verify alignment", or "review the applied changes against documented jobs". In post-edit mode you may flag drift between disk state and JTBD docs exactly as the original verdict grammar describes — the change is on disk by construction; the not-yet-applied carve-out does not apply.
 
+**Recommendation review mode.** The calling prompt begins with `RECOMMENDATION REVIEW` and asks you to review a user-facing capability recommendation or option set before it is presented. Review the recommendation itself against relevant documented desired outcomes and persona constraints.
+
+- Return `JTBD Recommendation Review: ISSUES FOUND` when an option contradicts a documented desired outcome, does not serve the outcome it claims to address, or the set is incomplete against the relevant outcomes. Name each affected option and the outcome it misses.
+- Return `JTBD Recommendation Review: PASS` when the options presented are consistent with and collectively cover the relevant documented outcomes.
+- Do not rank or choose among viable aligned options. Do not ask the user a question. The calling assistant owns the recommendation and any genuine user decision.
+- Never write `/tmp/jtbd-verdict` in this mode. The inline recommendation verdict is the complete, event-bound signal; a recommendation PASS must not authorise a later file edit.
+
 **Default when ambiguous.** When the calling prompt does not name the mode explicitly, default to **pre-edit mode** if a PreToolUse gate context is plausible (the prompt was likely fired by `jtbd-detect.sh` or an AFK iter dispatch). The pre-edit default is the safer fail-mode: a true post-edit drift will still surface as ISSUES FOUND / JOB UPDATE NEEDED on the substance; a true pre-edit proposal mis-classified as post-edit fires the P313 catch-22.
 
 ## What You Check
@@ -88,6 +95,15 @@ If the change aligns with documented jobs:
 > Change serves job: `[job-id]` — [brief alignment summary]
 > Persona fit: confirmed — [which constraints were checked]
 
+For an aligned recommendation:
+> **JTBD Recommendation Review: PASS**
+> Desired outcomes: [which outcomes were checked]
+> Persona fit: confirmed — [which constraints were checked]
+
+For a recommendation issue:
+> **JTBD Recommendation Review: ISSUES FOUND**
+> 1. **[Contradicts / Does not serve / Incomplete]** — [option and documented desired outcome]
+
 If there are misalignments or gaps:
 
 > **JTBD Review: ISSUES FOUND**
@@ -124,22 +140,28 @@ Your response has two communication channels. Both are required; neither replace
 
 **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.
+Every response MUST begin with the verdict template for its mode. Edit reviews use one of the four templates from "How to Report" above — `JTBD Review: PASS`, `JTBD Review: ISSUES FOUND`, `JTBD Review: JOB UPDATE NEEDED`, or `JTBD Review: PERSONA UPDATE NEEDED`. Recommendation reviews use `JTBD Recommendation Review: PASS` or `JTBD Recommendation Review: ISSUES FOUND`. 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):**
+**2. Mode-specific hook handoff (internal signal, REQUIRED):**
+
+After emitting your inline response, use the handoff for the active mode. It is NOT a substitute for the inline response.
 
-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:
+For edit reviews, write to `${JTBD_VERDICT_FILE:-/tmp/jtbd-verdict}`. The
+environment override is reserved for the isolated eval runner; ordinary review
+sessions use the default path.
 
-- `printf 'PASS' > /tmp/jtbd-verdict` — change aligns with documented jobs and persona
-- `printf 'FAIL' > /tmp/jtbd-verdict` — misalignment, job gap, or persona gap detected
+- `printf 'PASS' > "${JTBD_VERDICT_FILE:-/tmp/jtbd-verdict}"` — change aligns with documented jobs and persona
+- `printf 'FAIL' > "${JTBD_VERDICT_FILE:-/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.
 
+For recommendation reviews, the inline `JTBD Recommendation Review:` heading is the handoff. Do not write `/tmp/jtbd-verdict`; `jtbd-mark-reviewed.sh` classifies the current Agent completion and creates no edit or plan markers.
+
 ## Constraints
 
 - You are read-only. You do not edit files (except writing the verdict file).

package/hooks/jtbd-eval.sh

@@ -17,7 +17,7 @@ SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || echo ""
 if [ -f "docs/jtbd/README.md" ]; then
   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.
+MANDATORY JTBD (docs/jtbd): ask wr-jtbd:agent before edits/options; start recommendation prompts RECOMMENDATION REVIEW. See turn 1.
 HOOK_OUTPUT
   else
     cat <<'HOOK_OUTPUT'
@@ -30,11 +30,17 @@ 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/jtbd/ persona
-   and job 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
+   (subagent_type: "wr-jtbd:agent") before editing project files OR
+   presenting user-facing capability recommendations or option sets
+2. Every recommendation-review Agent prompt MUST begin exactly
+   `RECOMMENDATION REVIEW` so its verdict cannot authorise a file edit
+3. The jtbd-lead will review proposed changes or recommendations against
+   docs/jtbd/ persona and job definitions
+4. For recommendations, withhold options that contradict or do not serve a
+   documented desired outcome, and report an incomplete set before the user
+   sees it. Do not choose among the remaining viable options.
+5. Do NOT write, edit, or present the recommendation without review FIRST
+6. 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,

package/hooks/jtbd-mark-reviewed.sh

@@ -17,6 +17,11 @@ INPUT=$(cat)
 
 SUBAGENT=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty') || true
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+REVIEW_PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // empty') || true
+_HOOK_INPUT="$INPUT"
+AGENT_OUTPUT=$(_get_tool_output)
+PROMPT_FIRST=$(printf '%s\n' "$REVIEW_PROMPT" | awk 'NF { sub(/^[[:space:]]+/, ""); print; exit }')
+OUTPUT_FIRST=$(printf '%s\n' "$AGENT_OUTPUT" | awk 'NF { sub(/^[[:space:]]+/, ""); print; exit }')
 
 if [ -z "$SESSION_ID" ]; then
   exit 0
@@ -32,7 +37,24 @@ JTBD_PATH="$PROJECT_DIR/docs/jtbd"
 
 case "$SUBAGENT" in
   *jtbd-lead*|*wr-jtbd*)
-    # Check for edit review verdict
+    # Recommendation mode is bound to this Agent completion, not shared
+    # /tmp state. It never authorises a later file edit or plan.
+    if printf '%s\n' "$PROMPT_FIRST" | grep -qE '^RECOMMENDATION REVIEW' || \
+       printf '%s\n' "$OUTPUT_FIRST" | grep -qE '^>?[[:space:]]*(\*\*)?JTBD Recommendation Review:'; then
+      exit 0
+    fi
+
+    # Edit reviews require the current inline heading and the subordinate
+    # file verdict to agree. Shared /tmp state alone never authorises work.
+    HEADING=$(printf '%s\n' "$OUTPUT_FIRST" \
+      | sed -nE 's/^[[:space:]]*>?[[:space:]]*\*\*(JTBD Review: (PASS|ISSUES FOUND|JOB UPDATE NEEDED|PERSONA UPDATE NEEDED))\*\*[[:space:]]*$/\1/p' \
+      | head -n 1)
+    case "$HEADING" in
+      "JTBD Review: PASS") INLINE_VERDICT="PASS" ;;
+      "JTBD Review: ISSUES FOUND"|"JTBD Review: JOB UPDATE NEEDED"|"JTBD Review: PERSONA UPDATE NEEDED") INLINE_VERDICT="FAIL" ;;
+      *) INLINE_VERDICT="" ;;
+    esac
+
     VERDICT_FILE="/tmp/jtbd-verdict"
     VERDICT=""
     if [ -f "$VERDICT_FILE" ]; then
@@ -40,23 +62,17 @@ case "$SUBAGENT" in
       rm -f "$VERDICT_FILE"
     fi
 
-    case "$VERDICT" in
-      PASS)
+    case "${INLINE_VERDICT}:${VERDICT}" in
+      PASS:PASS)
         touch "/tmp/jtbd-reviewed-${SESSION_ID}"
         store_review_hash "$SESSION_ID" "jtbd" "$JTBD_PATH"
-        ;;
-      FAIL)
-        # Do NOT create marker — review found issues
+        touch "/tmp/jtbd-plan-reviewed-${SESSION_ID}"
         ;;
       *)
-        # No verdict file — backward compat, allow with marker
-        touch "/tmp/jtbd-reviewed-${SESSION_ID}"
-        store_review_hash "$SESSION_ID" "jtbd" "$JTBD_PATH"
+        # Fail closed: issues, missing verdicts, and unparseable verdicts do
+        # not authorise edits or plans, nor do mismatched verdict channels.
         ;;
     esac
-
-    # Plan review: agent completion = reviewed.
-    touch "/tmp/jtbd-plan-reviewed-${SESSION_ID}"
     ;;
 esac
 

package/package.json

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