@windyroad/jtbd 0.12.1 → 0.12.2-preview.578

package/.claude-plugin/plugin.json

@@ -90,5 +90,5 @@
     }
   },
   "name": "wr-jtbd",
-  "version": "0.12.1"
+  "version": "0.12.2"
 }

package/hooks/lib/gate-helpers.sh

@@ -13,6 +13,111 @@ _mtime() { stat -c%Y "$1" 2>/dev/null || /usr/bin/stat -f%m "$1" 2>/dev/null ||
 # Portable hash: tries md5sum, falls back to md5 -r, then shasum
 _hashcmd() { md5sum 2>/dev/null || md5 -r 2>/dev/null || shasum 2>/dev/null; }
 
+# ---------------------------------------------------------------------------
+# Substance-aware drift hash + atomic verdict-write (ADR-009 amendment
+# 2026-06-06, P353 + P303 close).
+#
+# `_substance_hash_path` normalises trivial/no-op edits BEFORE hashing so a
+# PASS marker survives whitespace / CRLF / trailing-newline edits while still
+# detecting substantive policy changes. Conservative boundary: when in doubt
+# whether an edit is trivial vs substantive, this helper treats it as
+# substantive (re-review fires). Only whitespace + line-ending + trailing-
+# newline are normalised in this iteration — single-numeral edits and
+# frontmatter-key changes are intentionally NOT normalised. See ADR-009
+# 2026-06-06 amendment for the ratified contract.
+#
+# `_atomic_mark_with_hash` writes the marker + hash file as an atomic pair
+# (mktemp + mv) so a PASS NEVER silently fails to persist (the empirically-
+# measured P353 failure mode that forced BYPASS_RISK_GATE=1 on every
+# external-comms gate clearance). Either both files land, or neither does.
+# Non-zero exit on failure so callers can emit a diagnostic.
+# ---------------------------------------------------------------------------
+
+# Substance-aware hash of a file or directory path.
+# For directories: hashes the concatenated content of all *.md files
+# (excluding README.md) in sorted order.
+# For files: hashes the file content.
+# Normalisation BEFORE hashing: CRLF → LF, strip trailing whitespace per
+# line, normalise trailing whitespace to a single \n.
+# Echoes "missing" for paths that do not exist (drop-in equivalence with the
+# pre-amendment `cat | _hashcmd | cut -d' ' -f1` site behaviour).
+# Echoes a hex sha256 of the normalised content on success.
+_substance_hash_path() {
+    local path="$1"
+    if [ -z "$path" ]; then
+        echo "missing"
+        return 0
+    fi
+    if [ -f "$path" ]; then
+        cat "$path" 2>/dev/null | _substance_normalize_then_hash
+    elif [ -d "$path" ]; then
+        find "$path" -name '*.md' -not -name 'README.md' -print0 \
+            | sort -z \
+            | xargs -0 cat 2>/dev/null \
+            | _substance_normalize_then_hash
+    else
+        echo "missing"
+    fi
+}
+
+# Internal: reads from stdin, normalises whitespace + line endings, emits a
+# hex sha256 of the normalised content. Conservative boundary documented in
+# ADR-009 2026-06-06 amendment: ambiguous edits stay substantive.
+_substance_normalize_then_hash() {
+    python3 -c "
+import sys, hashlib
+data = sys.stdin.buffer.read().decode('utf-8', errors='replace')
+# CRLF / CR -> LF
+data = data.replace('\r\n', '\n').replace('\r', '\n')
+# Strip trailing whitespace per line.
+lines = [line.rstrip() for line in data.split('\n')]
+# Re-join and normalise trailing whitespace to a single \n.
+normalised = '\n'.join(lines).rstrip() + '\n'
+print(hashlib.sha256(normalised.encode('utf-8')).hexdigest())
+" 2>/dev/null || echo "missing"
+}
+
+# Atomically write a presence marker + its paired hash file. Either both
+# files land or neither does. Returns 0 on success, 1 on failure. On failure
+# any partial state is rolled back.
+# Usage: _atomic_mark_with_hash "/tmp/architect-reviewed-${SID}" "$HASH"
+_atomic_mark_with_hash() {
+    local marker="$1"
+    local hash="$2"
+    local hash_file="${marker}.hash"
+
+    if [ -z "$marker" ]; then
+        return 1
+    fi
+
+    local htmp="${hash_file}.tmp.$$.${RANDOM:-0}"
+    local mtmp="${marker}.tmp.$$.${RANDOM:-0}"
+
+    # Write hash to tempfile.
+    if ! printf '%s\n' "$hash" > "$htmp" 2>/dev/null; then
+        rm -f "$htmp"
+        return 1
+    fi
+    # Write empty marker to tempfile.
+    if ! : > "$mtmp" 2>/dev/null; then
+        rm -f "$htmp" "$mtmp"
+        return 1
+    fi
+    # Atomic rename: hash file first.
+    if ! mv -f "$htmp" "$hash_file" 2>/dev/null; then
+        rm -f "$htmp" "$mtmp"
+        return 1
+    fi
+    # Atomic rename: marker second. If this fails, roll back the hash file
+    # so we never observe a hash-without-marker half-state.
+    if ! mv -f "$mtmp" "$marker" 2>/dev/null; then
+        rm -f "$mtmp"
+        rm -f "$hash_file"
+        return 1
+    fi
+    return 0
+}
+
 # Paths excluded from pipeline state hashing and docs-only detection.
 _doc_exclusions() {
     echo ':!docs/' ':!.risk-reports/' ':!.changeset/' ':!governance/' ':!.claude/plans/' ':!CLAUDE.md' ':!AGENTS.md' ':!PRINCIPLES.md' ':!DECISION-MANAGEMENT.md' ':!AGENTIC_RISK_REGISTER.md' ':!PROBLEM-MANAGEMENT.md'

package/hooks/lib/review-gate.sh

@@ -34,18 +34,15 @@ check_review_gate() {
     return 1
   fi
 
-  # 3. Drift detection — policy file hash must match
+  # 3. Drift detection — substance-aware policy hash must match
+  # (ADR-009 amendment 2026-06-06: trivial whitespace / line-ending /
+  # trailing-newline edits do NOT trigger drift; substantive policy
+  # changes DO. Conservative boundary — ambiguous edits stay substantive.
+  # See gate-helpers.sh::_substance_hash_path.)
   if [ -f "$HASH_FILE" ] && [ -n "$POLICY_FILE" ]; then
     local STORED_HASH=$(cat "$HASH_FILE")
-    local CURRENT_HASH=""
-    if [ -f "$POLICY_FILE" ]; then
-      CURRENT_HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
-    elif [ -d "$POLICY_FILE" ]; then
-      # Directory (e.g., docs/decisions/) — hash all .md files
-      CURRENT_HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
-    else
-      CURRENT_HASH="missing"
-    fi
+    local CURRENT_HASH
+    CURRENT_HASH=$(_substance_hash_path "$POLICY_FILE")
     if [ "$STORED_HASH" != "$CURRENT_HASH" ]; then
       rm -f "$MARKER" "$HASH_FILE"
       REVIEW_GATE_REASON="${SYSTEM} policy file changed since last review. Re-run the ${SYSTEM} agent."
@@ -59,24 +56,29 @@ check_review_gate() {
 }
 
 # Store policy file hash after a successful review.
+# Routes the marker + hash write through `_atomic_mark_with_hash` so a PASS
+# never silently fails to persist (ADR-009 amendment 2026-06-06: closes the
+# "marker doesn't land after PASS" failure mode P353 measured as ~12
+# subagent invocations + 3 BYPASS_RISK_GATE=1 uses per 3-filing session).
 # Usage: store_review_hash "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
 store_review_hash() {
   local SESSION_ID="$1"
   local SYSTEM="$2"
   local POLICY_FILE="$3"
-  local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
+  local MARKER="/tmp/${SYSTEM}-reviewed-${SESSION_ID}"
 
   if [ -n "$POLICY_FILE" ]; then
-    local HASH=""
-    if [ -f "$POLICY_FILE" ]; then
-      HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
-    elif [ -d "$POLICY_FILE" ]; then
-      HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
-    else
-      HASH="missing"
+    local HASH
+    HASH=$(_substance_hash_path "$POLICY_FILE")
+    # Atomic: marker + hash either both land or neither does.
+    if ! _atomic_mark_with_hash "$MARKER" "$HASH"; then
+      # Diagnostic on failure — surface the silent-fail mode the
+      # pre-amendment `touch + echo > .hash` pair hid.
+      echo "WARN: ${SYSTEM}-mark-reviewed atomic marker-write failed for ${MARKER}" >&2
+      return 1
     fi
-    echo "$HASH" > "$HASH_FILE"
   fi
+  return 0
 }
 
 # Emit fail-closed deny JSON for PreToolUse hooks.

package/hooks/test/substance-aware-drift.bats

@@ -0,0 +1,139 @@
+#!/usr/bin/env bats
+
+# Behavioural tests for ADR-009 amendment 2026-06-06: substance-aware drift +
+# atomic verdict-write — JTBD gate. Closes P353 (hash-marker brittleness
+# umbrella) for the review-gate.sh code path shared by JTBD / voice-tone /
+# style-guide.
+#
+# Cases ratified 2026-06-06: see substance-aware-drift.bats in the architect
+# package for the full contract. JTBD's tests cover the same four cases
+# through `check_review_gate` + `store_review_hash`.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  source "$SCRIPT_DIR/lib/review-gate.sh"
+
+  TEST_SESSION="bats-jtbd-substance-$$-${BATS_TEST_NUMBER}"
+  SYSTEM="jtbd"
+  TEST_DIR=$(mktemp -d -t substance-aware-drift-jtbd.XXXXXX)
+  mkdir -p "$TEST_DIR/docs/jtbd"
+  POLICY_DIR="$TEST_DIR/docs/jtbd"
+
+  MARKER="/tmp/${SYSTEM}-reviewed-${TEST_SESSION}"
+  HASH_FILE="${MARKER}.hash"
+  rm -f "$MARKER" "$HASH_FILE"
+}
+
+teardown() {
+  rm -f "$MARKER" "$HASH_FILE"
+  rm -rf "$TEST_DIR"
+}
+
+_install_and_mark() {
+  local body="$1"
+  printf '%s' "$body" > "$POLICY_DIR/JTBD-001.proposed.md"
+  touch "$MARKER"
+  store_review_hash "$TEST_SESSION" "$SYSTEM" "$POLICY_DIR"
+}
+
+# ---------------------------------------------------------------------------
+# Case (a) — trivial edits do NOT re-trigger
+# ---------------------------------------------------------------------------
+
+@test "jtbd substance-aware: trailing-whitespace edit does NOT re-trigger drift" {
+  _install_and_mark "# JTBD-001
+
+A job-to-be-done description.
+"
+  printf '%s' "# JTBD-001
+
+A job-to-be-done description.
+" > "$POLICY_DIR/JTBD-001.proposed.md"
+
+  run check_review_gate "$TEST_SESSION" "$SYSTEM" "$POLICY_DIR"
+  [ "$status" -eq 0 ]
+  [ -f "$MARKER" ]
+}
+
+@test "jtbd substance-aware: CRLF→LF edit does NOT re-trigger drift" {
+  _install_and_mark "# JTBD-001
+
+Body.
+"
+  printf '# JTBD-001\r\n\r\nBody.\r\n' > "$POLICY_DIR/JTBD-001.proposed.md"
+
+  run check_review_gate "$TEST_SESSION" "$SYSTEM" "$POLICY_DIR"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Case (b) — substantive edits DO re-trigger
+# ---------------------------------------------------------------------------
+
+@test "jtbd substance-aware: new-word edit DOES re-trigger drift" {
+  _install_and_mark "# JTBD-001
+
+A job-to-be-done description.
+"
+  printf '%s' "# JTBD-001
+
+A different job-to-be-done description.
+" > "$POLICY_DIR/JTBD-001.proposed.md"
+
+  run check_review_gate "$TEST_SESSION" "$SYSTEM" "$POLICY_DIR"
+  [ "$status" -ne 0 ]
+  [ ! -f "$MARKER" ]
+  [ ! -f "$HASH_FILE" ]
+}
+
+@test "jtbd substance-aware: new JTBD file DOES re-trigger drift" {
+  _install_and_mark "# JTBD-001
+
+Body.
+"
+  printf '%s' "# JTBD-002
+
+New job.
+" > "$POLICY_DIR/JTBD-002.proposed.md"
+
+  run check_review_gate "$TEST_SESSION" "$SYSTEM" "$POLICY_DIR"
+  [ "$status" -ne 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Case (c) — atomic write persists reliably
+# ---------------------------------------------------------------------------
+
+@test "jtbd atomic-write: store_review_hash lands marker + hash together" {
+  printf '%s' "# JTBD-001
+
+Body.
+" > "$POLICY_DIR/JTBD-001.proposed.md"
+  touch "$MARKER"
+  run store_review_hash "$TEST_SESSION" "$SYSTEM" "$POLICY_DIR"
+  [ "$status" -eq 0 ]
+  [ -f "$MARKER" ]
+  [ -f "$HASH_FILE" ]
+  # Stored hash matches the substance hash of the policy content.
+  local expected
+  expected=$(_substance_hash_path "$POLICY_DIR")
+  [ "$(cat "$HASH_FILE")" = "$expected" ]
+}
+
+# ---------------------------------------------------------------------------
+# Case (d) — conservative boundary holds
+# ---------------------------------------------------------------------------
+
+@test "jtbd conservative: single-numeral change DOES re-trigger drift" {
+  _install_and_mark "# JTBD-001
+
+Threshold is 5 minutes.
+"
+  printf '%s' "# JTBD-001
+
+Threshold is 6 minutes.
+" > "$POLICY_DIR/JTBD-001.proposed.md"
+
+  run check_review_gate "$TEST_SESSION" "$SYSTEM" "$POLICY_DIR"
+  [ "$status" -ne 0 ]
+}

package/package.json

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

package/skills/confirm-jobs-and-personas/SKILL.md

@@ -49,6 +49,8 @@ For each job/persona in the ordered queue, surface it as an `AskUserQuestion` (c
 
 The trailing clause exists for cross-reference value — it is optional, NOT a re-entry point for meta-leading. When the meta does not add load-bearing context for the confirm decision, omit it entirely.
 
+**Brief-before-ID discipline (P350).** The `question` and `options` text MUST inline what each referenced artefact is and what is at stake before naming it by ID. `JTBD-NNN` / `P-NNN` / `ADR-NNN` / `RFC-NNN` references are audit-trail annotations, NEVER carriers of meaning — the user reads this prompt without project filesystem access (mobile clients, accessibility tooling, notification surfaces) and cannot follow links. Acceptable: *"This job statement: developers want governance enforced automatically so they get manual-review safety without the overhead (cited by the AFK-orchestration backlog ticket)."* Unacceptable: *"This job statement: enforce governance without slowing down (cited by P256, sibling to JTBD-006)."* Trailing parenthetical IDs are permitted ONLY after a self-contained explanation, never as the explanation itself. Mirrors the canonical `/wr-architect:create-adr` Step 5 § 5a Rule 3 ("No IDs as explainers"). See also session memory `feedback_brief_before_id.md`.
+
 This is a genuine human-decision surface (the point of P288/ADR-068) — `AskUserQuestion` is correct here, not over-asking. Do not auto-confirm; do not prose-ask.
 
 ### Step 4: Apply the outcome