@windyroad/style-guide 0.4.3 → 0.4.4-preview.581

package/.claude-plugin/plugin.json

@@ -79,5 +79,5 @@
     }
   },
   "name": "wr-style-guide",
-  "version": "0.4.3"
+  "version": "0.4.4"
 }

package/README.md

@@ -45,22 +45,6 @@ This examines your existing CSS, components, and design patterns, then asks abou
 
 The `wr-style-guide:agent` reads your `docs/STYLE-GUIDE.md` and reviews proposed changes against your documented design system.
 
-## Jobs to be Done
-
-This plugin serves the [Jobs to be Done](../../docs/jtbd/) below. Per [ADR-051](../../docs/decisions/051-jtbd-anchored-readme-with-drift-advisory.proposed.md), the persona-grouped JTBD anchor is the canonical source of truth for the README's value framing.
-
-### Solo developer
-
-- **[JTBD-001 Enforce Governance Without Slowing Down](../../docs/jtbd/solo-developer/JTBD-001-enforce-governance.proposed.md)** — style-guide review fires automatically on every CSS or component edit; the project's own design system is the policy source.
-
-### Tech lead / consultant
-
-- **[JTBD-202 Run Pre-Flight Governance Checks Before Release or Handover](../../docs/jtbd/tech-lead/JTBD-202-pre-flight-governance-check.proposed.md)** — style-guide alignment is reviewable on demand before a release or client handover.
-
-### Plugin user
-
-- **[JTBD-302 Trust That the README Describes the Plugin I Just Installed](../../docs/jtbd/plugin-user/JTBD-302-trust-readme-describes-installed-behaviour.proposed.md)** — this README is anchored on current JTBD job IDs; drift between prose and shipped behaviour is detectable at retro time per ADR-051.
-
 ## Updating and Uninstalling
 
 ```bash

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,86 @@
+#!/usr/bin/env bats
+
+# Behavioural tests for ADR-009 amendment 2026-06-06: substance-aware drift +
+# atomic verdict-write — style-guide gate. Sibling-coverage to architect /
+# jtbd / voice-tone bats files of the same name.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  source "$SCRIPT_DIR/lib/review-gate.sh"
+
+  TEST_SESSION="bats-sg-substance-$$-${BATS_TEST_NUMBER}"
+  SYSTEM="style-guide"
+  TEST_DIR=$(mktemp -d -t substance-aware-drift-sg.XXXXXX)
+  POLICY_FILE="$TEST_DIR/STYLE-GUIDE.md"
+
+  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_FILE"
+  touch "$MARKER"
+  store_review_hash "$TEST_SESSION" "$SYSTEM" "$POLICY_FILE"
+}
+
+@test "style-guide substance-aware: trailing-whitespace edit does NOT re-trigger" {
+  _install_and_mark "# Style Guide
+
+Use 2-space indentation.
+"
+  printf '%s' "# Style Guide
+
+Use 2-space indentation.
+" > "$POLICY_FILE"
+
+  run check_review_gate "$TEST_SESSION" "$SYSTEM" "$POLICY_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "style-guide substance-aware: new-rule edit DOES re-trigger" {
+  _install_and_mark "# Style Guide
+
+Use 2-space indentation.
+"
+  printf '%s' "# Style Guide
+
+Use 2-space indentation.
+Always trailing-comma.
+" > "$POLICY_FILE"
+
+  run check_review_gate "$TEST_SESSION" "$SYSTEM" "$POLICY_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "style-guide atomic-write: store_review_hash lands marker + hash together" {
+  printf '%s' "# Style Guide
+
+Body.
+" > "$POLICY_FILE"
+  touch "$MARKER"
+  run store_review_hash "$TEST_SESSION" "$SYSTEM" "$POLICY_FILE"
+  [ "$status" -eq 0 ]
+  [ -f "$MARKER" ]
+  [ -f "$HASH_FILE" ]
+}
+
+@test "style-guide conservative: single-numeral change DOES re-trigger" {
+  _install_and_mark "# Style Guide
+
+Use 2-space indentation.
+"
+  printf '%s' "# Style Guide
+
+Use 4-space indentation.
+" > "$POLICY_FILE"
+
+  run check_review_gate "$TEST_SESSION" "$SYSTEM" "$POLICY_FILE"
+  [ "$status" -ne 0 ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/style-guide",
-  "version": "0.4.3",
+  "version": "0.4.4-preview.581",
   "description": "Style guide enforcement for CSS and UI components",
   "bin": {
     "windyroad-style-guide": "./bin/install.mjs"