@windyroad/jtbd 0.12.5 → 0.12.6-preview.654

package/.claude-plugin/plugin.json

@@ -90,5 +90,5 @@
     }
   },
   "name": "wr-jtbd",
-  "version": "0.12.5"
+  "version": "0.12.6"
 }

package/agents/agent.md

@@ -21,6 +21,23 @@ You are the JTBD Lead. You review proposed changes against the project's Jobs To
 4. Review proposed changes against every documented job and the persona
 5. Report: PASS if aligned, or list specific misalignments and gaps
 
+## 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.
+
+**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.
+
+In pre-edit mode:
+
+- If you receive a review request describing PROPOSED changes (not-yet-applied), classify alignment of the PROPOSAL itself. Not-yet-applied state of the proposed change is the EXPECTED baseline of a pre-edit gate. Do NOT treat "edits aren't applied yet" / "the residual old state is still live" / "the change isn't on disk yet" as ISSUES FOUND — that is the gate's design intent (P313 closes this catch-22).
+- The ground truth you classify against is the **proposal** as described in the calling prompt (the diff sketch, the fix-strategy prose, the file-edit plan). The disk state is the legitimate "old state" the proposal is about to replace — including any JTBD policy file the proposal itself amends. A re-review fired by a `human-oversight: <state>` marker that invalidated because the JTBD policy changed in this session MUST classify the proposal that re-amends the policy, NOT withhold PASS because the prior policy text is still live on disk.
+- PASS the review when the proposal aligns with documented jobs and the primary persona, the proposal does not introduce an undocumented user flow, and (where applicable) any cited persona/JTBD is ratified. ISSUES FOUND / JOB UPDATE NEEDED / PERSONA UPDATE NEEDED on a pre-edit review must cite a problem with the **proposal**, not with the not-yet-applied-ness of the proposal.
+- All other review machinery below (Job Alignment, Persona Fit, Screen Mapping, API / Action Alignment, Unratified Dependency) applies normally — pre-edit mode does not relax any of those substantive checks. It constrains only the verdict-grammar around the not-yet-applied baseline.
+
+**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.
+
+**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
 
 All review criteria come from the JTBD documentation. Read the docs first and apply them. Typical checks include:

package/agents/test/jtbd-pre-edit-review-mode.bats

@@ -0,0 +1,48 @@
+#!/usr/bin/env bats
+# Doc-lint guard: jtbd agent.md must carry an explicit pre-edit /
+# proposed-change review-mode carve-out so the agent classifies alignment
+# of the PROPOSAL when the calling prompt describes a not-yet-applied
+# change, instead of mis-classifying not-yet-applied state as ISSUES FOUND
+# (P313 catch-22: gate blocks edits; reviewer wants edits done first).
+#
+# tdd-review: structural-permitted (justification: P176 — agent behaviour is
+# prompt-driven with no skill-invocation harness to exercise the verdict
+# behaviourally; ADR-052 Surface 2 structural-justified case, NOT an ADR-005
+# Permitted Exception — ADR-052 narrows ADR-005 to exclude prose-doc greps).
+# When P176 lands, upgrade to a behavioural test that feeds the agent a
+# pre-edit proposal and asserts the PASS verdict.
+#
+# Cross-reference:
+#   P313 (Pre-edit governance-gate catch-22 — pass withheld pending edits)
+#   ADR-052 Surface 2 (structural-justified verdict) + P176 (harness gap)
+#   @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 carries a Review Mode section distinguishing pre-edit from post-edit (P313)" {
+  run grep -nE "^## Review Mode: Pre-edit / proposed-change vs\. Post-edit / applied" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md classifies alignment of the PROPOSAL in pre-edit mode (P313 verbatim core sentence)" {
+  run grep -nE "classify alignment of the PROPOSAL itself" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md treats not-yet-applied state as the EXPECTED baseline of a pre-edit gate (P313)" {
+  run grep -nE "EXPECTED baseline of a pre-edit gate" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md explicitly rejects 'edits aren't applied yet' as a valid ISSUES FOUND substance (P313)" {
+  run grep -nE "Do NOT treat .edits aren't applied yet" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md cites P313 as the catch-22 closure (audit-trail)" {
+  run grep -nE "P313" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}

package/hooks/jtbd-enforce-edit.sh

@@ -9,6 +9,7 @@
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/review-gate.sh"
+source "$SCRIPT_DIR/lib/marker-only-diff.sh"
 
 # P191: resolve the project root from the session signal, not the hook's
 # runtime CWD. Claude Code may launch the hook with an actual working
@@ -40,6 +41,15 @@ except:
     print('')
 " 2>/dev/null || echo "")
 
+TOOL_NAME=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
 if [ -z "$SESSION_ID" ]; then
   review_gate_parse_error
   exit 0
@@ -120,6 +130,62 @@ case "$FILE_PATH" in
     exit 0 ;;
 esac
 
+# P301: marker-only-diff exemption for docs/decisions/*.md ADRs. The JTBD
+# gate fires on docs/decisions/ writes (not in its exclusion list), so a
+# multi-batch `/wr-architect:review-decisions` drain pays one JTBD review
+# round-trip per batch on top of the architect one — the ticket's
+# observed "Batch 8 (ADR-020): blocked on architect review (`jtbd policy
+# file changed since last review`)" symptom is precisely that. Same
+# rationale + safety-net as the architect-side exemption: oversight
+# marker writes are mechanical output of a substance-confirmed decision
+# (ADR-066 contract); the jtbd-oversight-marker-discipline.sh hook
+# continues to enforce per-ADR session evidence for `confirmed`
+# introductions.
+case "$FILE_PATH" in
+  */docs/decisions/*.md|docs/decisions/*.md)
+    case "$TOOL_NAME" in
+      Edit)
+        _OLD=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('old_string', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+        _NEW=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('new_string', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+        if [ -n "$_OLD$_NEW" ] && is_marker_only_diff "$_OLD" "$_NEW"; then
+          exit 0
+        fi
+        ;;
+      Write)
+        _NEW=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('content', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+        _OLD=""
+        if [ -f "$FILE_PATH" ]; then
+          _OLD=$(cat "$FILE_PATH" 2>/dev/null) || _OLD=""
+        fi
+        if [ -n "$_OLD$_NEW" ] && is_marker_only_diff "$_OLD" "$_NEW"; then
+          exit 0
+        fi
+        ;;
+    esac
+    ;;
+esac
+
 # Determine JTBD path — canonical directory layout only (ADR-008 Option 3).
 # Legacy docs/JOBS_TO_BE_DONE.md is NOT consulted at runtime; the gate is
 # inactive on projects that have not run /wr-jtbd:update-guide.

package/hooks/lib/marker-only-diff.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# Shared helper: detect "oversight-marker-only" frontmatter diffs.
+#
+# P301: ADR-066/068 oversight-marker writes to docs/decisions/ ADRs trip the
+# full architect+JTBD edit gate each batch of an `/wr-architect:review-decisions`
+# drain, producing 2-3 no-op-PASS review round-trips per batch. The marker
+# add/update is the mechanical output of a decision the user already
+# substance-confirmed via AskUserQuestion (ADR-066 contract); the gate has
+# nothing substantive to assess.
+#
+# This helper exposes `is_marker_only_diff OLD NEW` returning 0 when every
+# added/removed non-empty line matches one of the oversight-marker frontmatter
+# patterns:
+#
+#   human-oversight:   confirmed | unconfirmed | rejected-pending-supersede
+#   oversight-date:    <date>
+#   decision-makers:   <name|email>
+#   supersede-ticket:  <ticket>
+#
+# When the predicate fires PASS, the calling gate short-circuits to exit 0
+# without requiring a fresh architect / JTBD review marker. The
+# architect-oversight-marker-discipline.sh (and JTBD sibling) hooks remain
+# active as the safety net: a marker-only diff that introduces
+# `human-oversight: confirmed` still requires the per-ADR session evidence
+# marker (P348 / ADR-066 amendment 2026-06-02).
+#
+# Conservative boundary: any non-empty line outside the marker grammar
+# (frontmatter delimiters that shift position, status:/date: changes, body
+# edits) fails the predicate. The exemption is exact so it cannot be used
+# to slip decision-content edits past the gate.
+#
+# Fail-safe: if python3 is unavailable or the diff parse errors, the function
+# returns 1 (NOT marker-only) and the gate proceeds with its normal review
+# requirement.
+#
+# Sibling copy of packages/architect/hooks/lib/marker-only-diff.sh per the
+# existing gate-helpers.sh duplicate-shared pattern (ADR-017). Keep in sync
+# manually until a second call site justifies the cost of a sync script.
+
+is_marker_only_diff() {
+  local old="$1"
+  local new="$2"
+
+  command -v python3 >/dev/null 2>&1 || return 1
+
+  OLD_CONTENT="$old" NEW_CONTENT="$new" python3 - <<'PYEOF'
+import os, sys, re
+try:
+    import difflib
+except Exception:
+    sys.exit(1)
+
+old = os.environ.get('OLD_CONTENT', '')
+new = os.environ.get('NEW_CONTENT', '')
+
+if old == new:
+    sys.exit(0)
+
+old_lines = old.splitlines()
+new_lines = new.splitlines()
+
+marker_pat = re.compile(
+    r'^[ \t]*(human-oversight|oversight-date|decision-makers|supersede-ticket)[ \t]*:.*$'
+)
+
+def allowed(line: str) -> bool:
+    s = line.strip()
+    if s == '':
+        return True
+    if marker_pat.match(line):
+        return True
+    return False
+
+sm = difflib.SequenceMatcher(a=old_lines, b=new_lines, autojunk=False)
+for tag, i1, i2, j1, j2 in sm.get_opcodes():
+    if tag == 'equal':
+        continue
+    for line in old_lines[i1:i2]:
+        if not allowed(line):
+            sys.exit(1)
+    for line in new_lines[j1:j2]:
+        if not allowed(line):
+            sys.exit(1)
+
+sys.exit(0)
+PYEOF
+}

package/hooks/test/jtbd-marker-only-exempt.bats

@@ -0,0 +1,140 @@
+#!/usr/bin/env bats
+
+# P301: jtbd-enforce-edit.sh exempts marker-only frontmatter diffs to
+# docs/decisions/*.md ADRs from the JTBD review gate. The JTBD gate currently
+# fires on docs/decisions/ writes (decisions are not in its exclusion list);
+# the ticket's symptom "Batch 8 (ADR-020): blocked on architect review
+# (`jtbd policy file changed since last review`)" is that JTBD round-trip.
+#
+# Behavioural — exercises the full hook with constructed PreToolUse stdin
+# JSON payloads under a sandbox project dir; asserts on stdout+exit.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/jtbd-enforce-edit.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  # JTBD docs must exist for the gate to engage (otherwise it denies
+  # with "no JTBD documentation" — out of scope of this exemption test).
+  mkdir -p docs/jtbd/persona docs/decisions
+  echo "# stub job" > docs/jtbd/persona/JTBD-001-stub.proposed.md
+  echo "# stub adr" > docs/decisions/001-stub.proposed.md
+  SID="jtbd-marker-only-$$-$BATS_TEST_NUMBER"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  rm -f "/tmp/jtbd-reviewed-${SID}" "/tmp/jtbd-reviewed-${SID}.hash"
+}
+
+run_hook_json() {
+  local json_file="$1"
+  bash "$HOOK" < "$json_file"
+}
+
+# ── Marker-only ADD: should exempt ───────────────────────────────────────
+
+@test "P301: Edit adding only human-oversight + oversight-date to ADR is exempt (no JTBD marker required)" {
+  adr="$PWD/docs/decisions/100-some-adr.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 100 some adr
+EOF
+  old=$'---\nstatus: "proposed"\n---'
+  new=$'---\nstatus: "proposed"\nhuman-oversight: unconfirmed\noversight-date: 2026-06-08\n---'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "P301: Edit updating human-oversight value (unconfirmed → confirmed) on ADR is exempt" {
+  adr="$PWD/docs/decisions/101-promote.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+human-oversight: unconfirmed
+---
+
+# 101
+EOF
+  old=$'human-oversight: unconfirmed'
+  new=$'human-oversight: confirmed\noversight-date: 2026-06-08'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# ── Mixed marker + body: must NOT exempt ─────────────────────────────────
+
+@test "P301: Edit changing body content along with markers still gates" {
+  adr="$PWD/docs/decisions/110-mixed.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 110
+
+Original body.
+EOF
+  old=$'---\nstatus: "proposed"\n---\n\n# 110\n\nOriginal body.'
+  new=$'---\nstatus: "proposed"\nhuman-oversight: confirmed\noversight-date: 2026-06-08\n---\n\n# 110\n\nNew policy claim added.'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# ── Pure body change: must still gate ────────────────────────────────────
+
+@test "P301: Edit changing only body content with no marker lines still gates" {
+  adr="$PWD/docs/decisions/120-body.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 120
+
+Some text.
+EOF
+  old='Some text.'
+  new='Some text. And more.'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# ── Scope: exemption is narrow to docs/decisions/*.md ────────────────────
+
+@test "P301: marker-only diff to a NON docs/decisions/ path still gates (no path exemption)" {
+  mkdir -p "$PWD/src"
+  echo "// stub" > "$PWD/src/x.ts"
+  src="$PWD/src/x.ts"
+  old='// stub'
+  new=$'// stub\nhuman-oversight: confirmed'
+  json_file=$(mktemp)
+  jq -nc --arg p "$src" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}

package/package.json

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