@windyroad/voice-tone 0.1.2 → 0.1.3-preview.27

package/README.md

@@ -0,0 +1,63 @@
+# @windyroad/voice-tone
+
+**Voice and tone enforcement for Claude Code.** Reviews user-facing copy against your brand's voice and tone guide before it ships.
+
+Part of [Windy Road Agent Plugins](../../README.md).
+
+## What It Does
+
+When an AI agent writes user-facing text -- button labels, error messages, onboarding copy, marketing pages -- it doesn't know your brand voice. This plugin teaches it.
+
+The voice-tone plugin:
+
+1. **Detects** when an edit touches user-facing copy
+2. **Blocks** the edit until the voice-tone agent has reviewed it
+3. **Reviews** the proposed copy against your `docs/VOICE-AND-TONE.md` guide
+4. **Reports** violations with suggested fixes that match your brand's voice principles, banned patterns, and word list
+
+## Install
+
+```bash
+npx @windyroad/voice-tone
+```
+
+Restart Claude Code after installing.
+
+## Usage
+
+The plugin works automatically. On first use in a project without a voice guide, it blocks edits and directs you to create one:
+
+```
+/wr-voice-tone:update-guide
+```
+
+This examines your existing content and asks about your brand voice, target audience, and tone preferences to generate a `docs/VOICE-AND-TONE.md` tailored to your project.
+
+## How It Works
+
+| Hook | Trigger | What it does |
+|------|---------|-------------|
+| `voice-tone-eval.sh` | Every prompt | Evaluates whether the task involves user-facing copy |
+| `voice-tone-enforce-edit.sh` | Edit or Write | Blocks edits until the voice-tone agent has reviewed |
+| `voice-tone-mark-reviewed.sh` | Agent completes | Marks the review as done |
+| `voice-tone-reset-marker.sh` | Session end | Cleans up review markers |
+
+## Agent
+
+The `wr-voice-tone:agent` reads your `docs/VOICE-AND-TONE.md` and reviews proposed copy changes against:
+
+- Voice principles and personality traits
+- Tone guidance for different contexts
+- Banned words and patterns
+- Preferred terminology
+
+## Updating and Uninstalling
+
+```bash
+npx @windyroad/voice-tone --update
+npx @windyroad/voice-tone --uninstall
+```
+
+## Licence
+
+[MIT](../../LICENSE)

package/hooks/lib/gate-helpers.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+# Shared portable helpers for gate enforcement hooks.
+# Sourced by architect-gate.sh, risk-gate.sh, and all hook scripts.
+# Provides: _mtime, _hashcmd, _doc_exclusions, _err_trap, _get_*
+
+# ---------------------------------------------------------------------------
+# Portable utilities
+# ---------------------------------------------------------------------------
+
+# Portable mtime: tries GNU stat, falls back to macOS stat
+_mtime() { stat -c%Y "$1" 2>/dev/null || /usr/bin/stat -f%m "$1" 2>/dev/null || echo 0; }
+
+# 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; }
+
+# 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'
+}
+
+# ---------------------------------------------------------------------------
+# ERR trap: outputs diagnostic JSON on hook errors (P010)
+# Usage: source gate-helpers.sh at top of hook, then call _enable_err_trap
+# ---------------------------------------------------------------------------
+
+_enable_err_trap() {
+    trap '_err_trap_handler "$BASH_SOURCE" "$LINENO" "$BASH_COMMAND"' ERR
+}
+
+_err_trap_handler() {
+    local script="$1" line="$2" cmd="$3"
+    local name
+    name=$(basename "$script" 2>/dev/null || echo "$script")
+    # Output diagnostic as systemMessage so it's visible in conversation
+    cat <<EOF
+{
+  "systemMessage": "Hook error in ${name} at line ${line}: ${cmd}"
+}
+EOF
+}
+
+# ---------------------------------------------------------------------------
+# JSON input parsing: standardised helpers replacing inline python3
+# Each reads from _HOOK_INPUT (set by the hook before calling these)
+# ---------------------------------------------------------------------------
+
+# Store hook input for reuse by parsing helpers
+_HOOK_INPUT=""
+
+_parse_input() {
+    _HOOK_INPUT=$(cat)
+}
+
+_get_tool_name() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_session_id() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_command() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_file_path() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    ti = data.get('tool_input', {})
+    print(ti.get('file_path', ti.get('path', '')))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_subagent_type() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('subagent_type', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_user_prompt() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('user_prompt', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+_get_tool_output() {
+    echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    # PostToolUse provides tool_response (dict with content array), not tool_output
+    tr = data.get('tool_response', {})
+    if isinstance(tr, dict):
+        content = tr.get('content', [])
+        if isinstance(content, list):
+            texts = [c.get('text', '') for c in content if isinstance(c, dict) and c.get('type') == 'text']
+            if texts:
+                print('\n'.join(texts))
+                sys.exit(0)
+    # Fallback for older/different hook formats
+    print(data.get('tool_output', ''))
+except:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+# ---------------------------------------------------------------------------
+# Session-scoped tmp directory for risk files
+# ---------------------------------------------------------------------------
+
+# Returns the session-scoped directory for risk temp files.
+# Creates the directory if it doesn't exist.
+# Usage: DIR=$(_risk_dir "$SESSION_ID"); echo "1" > "$DIR/commit"
+_risk_dir() {
+  local sid="$1"
+  local dir="${TMPDIR:-/tmp}/claude-risk-${sid}"
+  mkdir -p "$dir"
+  echo "$dir"
+}
+
+# ---------------------------------------------------------------------------
+# Non-doc file detection for WIP gating
+# ---------------------------------------------------------------------------
+
+_is_doc_file() {
+    local file_path="$1"
+    local EXCL
+    EXCL=$(_doc_exclusions)
+    for pattern in $EXCL; do
+        local clean="${pattern#:!}"
+        case "$file_path" in
+            *"$clean"*) return 0 ;;
+        esac
+    done
+    case "$file_path" in
+        *.claude/*|*.risk-reports/*|*RISK-POLICY.md) return 0 ;;
+    esac
+    return 1
+}

package/hooks/lib/review-gate.sh

@@ -16,7 +16,7 @@ check_review_gate() {
   local POLICY_FILE="$3"   # e.g., "docs/STYLE-GUIDE.md"
   local MARKER="/tmp/${SYSTEM}-reviewed-${SESSION_ID}"
   local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
-  local TTL_SECONDS="${REVIEW_TTL:-600}"
+  local TTL_SECONDS="${REVIEW_TTL:-1800}"
 
   # 1. Marker must exist
   if [ ! -f "$MARKER" ]; then

package/hooks/test/review-gate.bats

@@ -0,0 +1,49 @@
+#!/usr/bin/env bats
+
+# Tests for review-gate.sh (shared by voice-tone, style-guide, jtbd)
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  source "$SCRIPT_DIR/lib/review-gate.sh"
+  TEST_SESSION="test-$$-$BATS_TEST_NUMBER"
+  TMPDIR_ORIG=$(mktemp -d)
+}
+
+teardown() {
+  rm -f "/tmp/voice-tone-reviewed-${TEST_SESSION}"
+  rm -f "/tmp/voice-tone-reviewed-${TEST_SESSION}.hash"
+  rm -rf "$TMPDIR_ORIG"
+}
+
+@test "gate denies when no marker exists" {
+  run check_review_gate "$TEST_SESSION" "voice-tone" "docs/VOICE-AND-TONE.md"
+  [ "$status" -ne 0 ]
+}
+
+@test "gate allows when marker exists and is fresh" {
+  touch "/tmp/voice-tone-reviewed-${TEST_SESSION}"
+  run check_review_gate "$TEST_SESSION" "voice-tone" "docs/VOICE-AND-TONE.md"
+  [ "$status" -eq 0 ]
+}
+
+@test "gate denies when marker is expired" {
+  touch "/tmp/voice-tone-reviewed-${TEST_SESSION}"
+  REVIEW_TTL=0 run check_review_gate "$TEST_SESSION" "voice-tone" "docs/VOICE-AND-TONE.md"
+  [ "$status" -ne 0 ]
+}
+
+@test "store_review_hash creates hash file" {
+  store_review_hash "$TEST_SESSION" "voice-tone" "docs/VOICE-AND-TONE.md"
+  [ -f "/tmp/voice-tone-reviewed-${TEST_SESSION}.hash" ]
+}
+
+@test "_mtime returns a number" {
+  touch "/tmp/voice-tone-reviewed-${TEST_SESSION}"
+  result=$(_mtime "/tmp/voice-tone-reviewed-${TEST_SESSION}")
+  [[ "$result" =~ ^[0-9]+$ ]]
+}
+
+@test "_hashcmd produces output" {
+  result=$(echo "test" | _hashcmd)
+  [ -n "$result" ]
+}

package/hooks/voice-tone-enforce-edit.sh

@@ -45,7 +45,7 @@ BASENAME=$(basename "$FILE_PATH")
 
 # If no policy file exists, block and direct to create skill
 if [ ! -f "docs/VOICE-AND-TONE.md" ]; then
-  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/VOICE-AND-TONE.md does not exist. Run /wr-voice-tone:create to generate a voice and tone guide for this project, then delegate to wr-voice-tone:agent for review."
+  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/VOICE-AND-TONE.md does not exist. Run /wr-voice-tone:update-guide to generate a voice and tone guide for this project, then delegate to wr-voice-tone:agent for review."
   exit 0
 fi
 

package/hooks/voice-tone-eval.sh

@@ -28,7 +28,7 @@ else
     cat <<'HOOK_OUTPUT'
 NOTE: This project has UI files but no docs/VOICE-AND-TONE.md.
 If the user's task involves editing user-facing copy, the edit will be blocked
-until a voice and tone guide exists. Run /wr-voice-tone:create to generate one.
+until a voice and tone guide exists. Run /wr-voice-tone:update-guide to generate one.
 HOOK_OUTPUT
   fi
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/voice-tone",
-  "version": "0.1.2",
+  "version": "0.1.3-preview.27",
   "description": "Voice and tone enforcement for user-facing copy",
   "bin": {
     "windyroad-voice-tone": "./bin/install.mjs"

package/skills/{wr:voice-tone → update-guide}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: wr:voice-tone
+name: wr-voice-tone:update-guide
 description: Create or update the project's docs/VOICE-AND-TONE.md by examining existing content and asking the user about brand voice, audience, and tone preferences.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 ---