rhachet-roles-ehmpathy 1.17.12 → 1.17.13

package/dist/domain.roles/mechanic/briefs/practices/lang.terms/rule.forbid.term-script.md

@@ -0,0 +1,81 @@
+### .rule = forbid-term-script
+
+#### .what
+the term `script` is forbidden — it is overloaded and vague
+
+#### .scope
+- code: variable names, function names, comments
+- files: filenames, directory names
+- docs: markdown, briefs, prompts
+- comms: commit messages, pr descriptions
+
+#### .why
+- `script` means too many things — it carries no precise signal
+- "all code is scripted" — the term adds no information
+- forces lazy categorization instead of domain clarity
+- hides the actual purpose and lifecycle of the code
+
+#### .enforcement
+use of `script` = **BLOCKER**
+
+#### .alternatives
+
+| 👎 vague  | 👍 precise   | .when                            |
+| -------- | ----------- | -------------------------------- |
+| `script` | `command`   | shell-invoked, adhoc usage       |
+| `script` | `procedure` | reusable sequence of steps       |
+| `script` | `operation` | domain logic with business rules |
+| `script` | `task`      | background or scheduled work     |
+| `script` | `migration` | database schema or data changes  |
+| `script` | `hook`      | lifecycle callback               |
+| `script` | `skill`     | agent-invoked capability         |
+| `script` | `init`      | setup or bootstrap logic         |
+| `script` | `transform` | data shape conversion            |
+| `script` | `handler`   | event or request responder       |
+
+#### .examples
+
+**👎 bad**
+```
+scripts/
+  deploy-script.sh
+  cleanup-script.js
+  data-script.ts
+```
+
+```ts
+// run the script to fix the data
+const runScript = () => { ... };
+```
+
+**👍 good**
+```
+commands/
+  deploy.sh
+  cleanup.command.ts
+migrations/
+  2024-01-fix-user-data.ts
+```
+
+```ts
+// run the migration to fix the data
+const runMigration = () => { ... };
+
+// invoke the command to deploy
+const invokeDeployCommand = () => { ... };
+```
+
+#### .note: filenames
+common renames:
+
+| 👎 vague           | 👍 precise             |
+| ----------------- | --------------------- |
+| `scripts/`        | `commands/` or `bin/` |
+| `run-script.sh`   | `run.command.sh`      |
+| `build-script.js` | `build.command.js`    |
+| `test-script.ts`  | `test.command.ts`     |
+| `setup-script.sh` | `init.sh`             |
+
+#### .see also
+- `rule.require.ubiqlang` — use precise domain terms
+- `rule.require.treestruct` — name structure guidance

package/dist/domain.roles/mechanic/inits/claude.hooks/pretooluse.forbid-terms.blocklist.sh

@@ -0,0 +1,170 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = PreToolUse hook to forbid terms from a configurable blocklist
+#
+# .why  = certain terms are overloaded or vague and degrade precision.
+#         this hook blocks Write and Edit operations that contain
+#         blocklisted terms, via the HARDNUDGE pattern (block first,
+#         allow retry).
+#
+# .how  = reads JSON from stdin, extracts content from Write/Edit,
+#         loads terms.blocklist.jsonc, scans for matches, blocks
+#         on first attempt but allows retry within 5 minutes.
+#
+# usage:
+#   configure in .claude/settings.json under hooks.PreToolUse
+#
+# guarantee:
+#   - blocks blocklisted terms on first attempt
+#   - allows retry within 5 min window (HARDNUDGE)
+#   - shows why term is forbidden and alternatives
+######################################################################
+
+set -euo pipefail
+
+# config
+HARDNUDGE_WINDOW_SECONDS=300  # 5 minutes
+STALE_THRESHOLD_SECONDS=3600  # 1 hour
+
+# read JSON from stdin
+STDIN_INPUT=$(cat)
+
+# failfast: if no input, error
+if [[ -z "$STDIN_INPUT" ]]; then
+  echo "ERROR: PreToolUse hook received no input via stdin" >&2
+  exit 2
+fi
+
+# extract tool name
+TOOL_NAME=$(echo "$STDIN_INPUT" | jq -r '.tool_name // empty' 2>/dev/null || echo "")
+
+# skip if not Write or Edit
+if [[ "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+# extract file path
+FILE_PATH=$(echo "$STDIN_INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+
+# extract content to scan based on tool type
+if [[ "$TOOL_NAME" == "Write" ]]; then
+  CONTENT=$(echo "$STDIN_INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null || echo "")
+else
+  # Edit: only scan new_string (additions, not removals)
+  CONTENT=$(echo "$STDIN_INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null || echo "")
+fi
+
+# skip if no content
+if [[ -z "$CONTENT" ]]; then
+  exit 0
+fi
+
+# find hook directory for blocklist config
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BLOCKLIST_FILE="$HOOK_DIR/terms.blocklist.jsonc"
+
+# skip if no blocklist config
+if [[ ! -f "$BLOCKLIST_FILE" ]]; then
+  exit 0
+fi
+
+# load blocklist config (strip comments, parse JSON)
+TERMS_JSON=$(sed 's|//.*||' "$BLOCKLIST_FILE" | jq -c '.terms // []' 2>/dev/null || echo "[]")
+
+# skip if no terms
+if [[ "$TERMS_JSON" == "[]" ]]; then
+  exit 0
+fi
+
+# find .claude directory
+find_claude_dir() {
+  local dir="$PWD"
+  while [[ "$dir" != "/" ]]; do
+    if [[ -d "$dir/.claude" ]]; then
+      echo "$dir/.claude"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+CLAUDE_DIR=$(find_claude_dir) || {
+  mkdir -p "$PWD/.claude"
+  CLAUDE_DIR="$PWD/.claude"
+}
+
+NUDGE_FILE="$CLAUDE_DIR/terms.blocklist.nudges.local.json"
+
+# ensure nudge file exists
+if [[ ! -f "$NUDGE_FILE" ]]; then
+  echo '{}' > "$NUDGE_FILE"
+fi
+
+# cleanup stale entries (older than 1 hour)
+# nudge format: { hash: { time, path, terms } }
+NOW=$(date +%s)
+TMP_FILE=$(mktemp)
+jq --argjson now "$NOW" --argjson threshold "$STALE_THRESHOLD_SECONDS" \
+  'to_entries | map(select(.value.time > ($now - $threshold))) | from_entries' \
+  "$NUDGE_FILE" > "$TMP_FILE" 2>/dev/null && mv "$TMP_FILE" "$NUDGE_FILE" || rm -f "$TMP_FILE"
+
+# detect matching terms
+DETECTED_TERMS=""
+DETECTED_INFO=""
+term_count=$(echo "$TERMS_JSON" | jq 'length')
+for ((i=0; i<term_count; i++)); do
+  TERM=$(echo "$TERMS_JSON" | jq -r ".[$i].term")
+  WHY=$(echo "$TERMS_JSON" | jq -r ".[$i].why")
+  ALT=$(echo "$TERMS_JSON" | jq -r ".[$i].alt | join(\", \")")
+
+  # case-insensitive word boundary match
+  if echo "$CONTENT" | grep -iqE "\\b${TERM}\\b"; then
+    if [[ -n "$DETECTED_TERMS" ]]; then
+      DETECTED_TERMS="${DETECTED_TERMS},\"${TERM}\""
+    else
+      DETECTED_TERMS="\"${TERM}\""
+    fi
+    DETECTED_INFO="${DETECTED_INFO}  ⛔ ${TERM}\n    why: ${WHY}\n    alt: ${ALT}\n"
+  fi
+done
+
+# if no terms detected, allow
+if [[ -z "$DETECTED_TERMS" ]]; then
+  exit 0
+fi
+
+# build nudge key as hash of file_path
+NUDGE_KEY=$(echo -n "${FILE_PATH}" | sha256sum | cut -d' ' -f1)
+
+# check last attempt time (nudge format: { hash: { time, path, terms } })
+LAST_ATTEMPT=$(jq -r --arg key "$NUDGE_KEY" '.[$key].time // 0' "$NUDGE_FILE" 2>/dev/null || echo "0")
+elapsed=$((NOW - LAST_ATTEMPT))
+
+if [[ $elapsed -lt $HARDNUDGE_WINDOW_SECONDS ]]; then
+  # within retry window, allow
+  exit 0
+fi
+
+# first attempt - record and block
+TMP_FILE=$(mktemp)
+jq --arg key "$NUDGE_KEY" --argjson time "$NOW" --arg path "$FILE_PATH" --argjson terms "[${DETECTED_TERMS}]" \
+  '. + {($key): {time: $time, path: $path, terms: $terms}}' \
+  "$NUDGE_FILE" > "$TMP_FILE" 2>/dev/null && mv "$TMP_FILE" "$NUDGE_FILE" || rm -f "$TMP_FILE"
+
+# build block message
+{
+  echo ""
+  echo "🛑 BLOCKED: forbidden term(s) detected in file write"
+  echo ""
+  echo "file: $FILE_PATH"
+  echo ""
+  echo "detected terms:"
+  echo -e "$DETECTED_INFO"
+  echo "see rule.forbid.term-* briefs for rationale."
+  echo ""
+  echo "if this is intentional and absolutely unavoidable, retry the same operation."
+  echo ""
+} >&2
+
+exit 2

package/dist/domain.roles/mechanic/inits/claude.hooks/{pretooluse.forbid-gerunds.sh → pretooluse.forbid-terms.gerunds.sh}

@@ -60,7 +60,7 @@ fi
 
 # find script directory for allowlist
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-ALLOWLIST_FILE="$SCRIPT_DIR/gerunds.allowlist.jsonc"
+ALLOWLIST_FILE="$SCRIPT_DIR/terms.gerunds.allowlist.jsonc"
 
 # load allowlist (strip comments, extract all words)
 ALLOWLIST=()
@@ -123,7 +123,7 @@ CLAUDE_DIR=$(find_claude_dir) || {
   CLAUDE_DIR="$PWD/.claude"
 }
 
-NUDGE_FILE="$CLAUDE_DIR/gerund.nudges.local.json"
+NUDGE_FILE="$CLAUDE_DIR/terms.gerunds.nudges.local.json"
 
 # ensure nudge file exists
 if [[ ! -f "$NUDGE_FILE" ]]; then
@@ -131,37 +131,46 @@ if [[ ! -f "$NUDGE_FILE" ]]; then
 fi
 
 # cleanup stale entries (older than 1 hour)
+# nudge format: { hash: { time, path, terms } }
 NOW=$(date +%s)
 TMP_FILE=$(mktemp)
 jq --argjson now "$NOW" --argjson threshold "$STALE_THRESHOLD_SECONDS" \
-  'to_entries | map(select(.value > ($now - $threshold))) | from_entries' \
+  'to_entries | map(select(.value.time > ($now - $threshold))) | from_entries' \
   "$NUDGE_FILE" > "$TMP_FILE" 2>/dev/null && mv "$TMP_FILE" "$NUDGE_FILE" || rm -f "$TMP_FILE"
 
-# check each gerund against nudge file
-BLOCKED_GERUNDS=()
-for gerund in "${GERUNDS[@]}"; do
-  # build nudge key as hash of file_path + gerund
-  NUDGE_KEY=$(echo -n "${FILE_PATH}:${gerund}" | sha256sum | cut -d' ' -f1)
+# build nudge key as hash of file_path
+NUDGE_KEY=$(echo -n "${FILE_PATH}" | sha256sum | cut -d' ' -f1)
 
-  # check last attempt time
-  LAST_ATTEMPT=$(jq -r --arg key "$NUDGE_KEY" '.[$key] // 0' "$NUDGE_FILE" 2>/dev/null || echo "0")
-  ELAPSED=$((NOW - LAST_ATTEMPT))
+# check last attempt time (nudge format: { hash: { time, path, terms } })
+LAST_ATTEMPT=$(jq -r --arg key "$NUDGE_KEY" '.[$key].time // 0' "$NUDGE_FILE" 2>/dev/null || echo "0")
+ELAPSED=$((NOW - LAST_ATTEMPT))
 
-  if [[ $ELAPSED -lt $HARDNUDGE_WINDOW_SECONDS ]]; then
-    # within retry window, allow this gerund
-    continue
-  fi
+if [[ $ELAPSED -lt $HARDNUDGE_WINDOW_SECONDS ]]; then
+  # within retry window, allow
+  exit 0
+fi
 
-  # outside window, record attempt and block
-  TMP_FILE=$(mktemp)
-  jq --arg key "$NUDGE_KEY" --argjson ts "$NOW" '. + {($key): $ts}' "$NUDGE_FILE" > "$TMP_FILE" 2>/dev/null && mv "$TMP_FILE" "$NUDGE_FILE" || rm -f "$TMP_FILE"
-  BLOCKED_GERUNDS+=("$gerund")
+# outside window - all detected gerunds are blocked
+BLOCKED_GERUNDS=("${GERUNDS[@]}")
+
+# build terms array for nudge record
+TERMS_JSON="["
+first=true
+for gerund in "${BLOCKED_GERUNDS[@]}"; do
+  if [[ "$first" == "true" ]]; then
+    TERMS_JSON="${TERMS_JSON}\"${gerund}\""
+    first=false
+  else
+    TERMS_JSON="${TERMS_JSON},\"${gerund}\""
+  fi
 done
+TERMS_JSON="${TERMS_JSON}]"
 
-# if all gerunds are within retry window, allow
-if [[ ${#BLOCKED_GERUNDS[@]} -eq 0 ]]; then
-  exit 0
-fi
+# record attempt with new format: { hash: { time, path, terms } }
+TMP_FILE=$(mktemp)
+jq --arg key "$NUDGE_KEY" --argjson time "$NOW" --arg path "$FILE_PATH" --argjson terms "$TERMS_JSON" \
+  '. + {($key): {time: $time, path: $path, terms: $terms}}' \
+  "$NUDGE_FILE" > "$TMP_FILE" 2>/dev/null && mv "$TMP_FILE" "$NUDGE_FILE" || rm -f "$TMP_FILE"
 
 # build block message
 {

package/dist/domain.roles/mechanic/inits/claude.hooks/terms.blocklist.jsonc

@@ -0,0 +1,11 @@
+{
+  // forbidden terms blocklist
+  // each entry specifies a term to forbid with rationale and alternatives
+  "terms": [
+    {
+      "term": "script",
+      "why": "overloaded and vague - conflates command, procedure, operation, and mechanism",
+      "alt": ["command", "executable", "procedure", "operation", "mechanism"]
+    }
+  ]
+}

package/dist/domain.roles/mechanic/inits/init.claude.hooks.sh

@@ -7,6 +7,7 @@
 #           • SessionStart: notify Claude of allowed permissions upfront
 #           • PreToolUse: forbid stderr redirects (2>&1)
 #           • PreToolUse: forbid gerunds in file writes (HARDNUDGE)
+#           • PreToolUse: forbid blocklisted terms in file writes (HARDNUDGE)
 #           • PreToolUse: check permissions before new requests
 #
 #         this script manages hook registration via findsert utility.
@@ -85,18 +86,32 @@ run_findsert "pretooluse.forbid-stderr-redirect" \
   --timeout 5 \
   --position prepend
 
-run_findsert "pretooluse.forbid-gerunds.write" \
+run_findsert "pretooluse.forbid-terms.gerunds.write" \
   --hook-type PreToolUse \
   --matcher "Write" \
-  --command "$RHACHET_INIT claude.hooks/pretooluse.forbid-gerunds" \
-  --name "pretooluse.forbid-gerunds.write" \
+  --command "$RHACHET_INIT claude.hooks/pretooluse.forbid-terms.gerunds" \
+  --name "pretooluse.forbid-terms.gerunds.write" \
   --timeout 5
 
-run_findsert "pretooluse.forbid-gerunds.edit" \
+run_findsert "pretooluse.forbid-terms.gerunds.edit" \
   --hook-type PreToolUse \
   --matcher "Edit" \
-  --command "$RHACHET_INIT claude.hooks/pretooluse.forbid-gerunds" \
-  --name "pretooluse.forbid-gerunds.edit" \
+  --command "$RHACHET_INIT claude.hooks/pretooluse.forbid-terms.gerunds" \
+  --name "pretooluse.forbid-terms.gerunds.edit" \
+  --timeout 5
+
+run_findsert "pretooluse.forbid-terms.blocklist.write" \
+  --hook-type PreToolUse \
+  --matcher "Write" \
+  --command "$RHACHET_INIT claude.hooks/pretooluse.forbid-terms.blocklist" \
+  --name "pretooluse.forbid-terms.blocklist.write" \
+  --timeout 5
+
+run_findsert "pretooluse.forbid-terms.blocklist.edit" \
+  --hook-type PreToolUse \
+  --matcher "Edit" \
+  --command "$RHACHET_INIT claude.hooks/pretooluse.forbid-terms.blocklist" \
+  --name "pretooluse.forbid-terms.blocklist.edit" \
   --timeout 5
 
 run_findsert "pretooluse.check-permissions" \

package/dist/domain.roles/mechanic/inits/init.claude.permissions.jsonc

@@ -9,6 +9,9 @@
   "permissions": {
     // commands that should never be auto-approved
     "deny": [
+      // whatever it uses via bash is typically executable via its own name -> own permissions
+      "Bash(bash:*)",
+
       // git write operations - require explicit user request for audit trail
       "Bash(git commit:*)",
       "Bash(git add .)",
@@ -107,7 +110,6 @@
 
     // commands that require explicit user approval each time
     "ask": [
-      "Bash(bash:*)",
       "Bash(chmod:*)",
       "Bash(npm install:*)",
       "Bash(pnpm install:*)",

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.17.12",
+  "version": "1.17.13",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [
@@ -49,7 +49,7 @@
     "prepare:husky": "husky install && chmod ug+x .husky/*",
     "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
     "test:format:biome": "biome format",
-    "prepare:rhachet": "rhachet init && rhachet roles link --role mechanic && rhachet roles init --role mechanic"
+    "prepare:rhachet": "rhachet init && rhachet roles link --role mechanic && rhachet roles init --role mechanic && rhachet roles link --role behaver && rhachet roles init --role behaver"
   },
   "dependencies": {
     "@ehmpathy/as-command": "1.0.3",
@@ -89,9 +89,9 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.20.5",
-    "rhachet-roles-bhrain": "0.5.1",
-    "rhachet-roles-bhuild": "0.5.4",
+    "rhachet": "1.20.7",
+    "rhachet-roles-bhrain": "0.5.9",
+    "rhachet-roles-bhuild": "0.5.6",
     "rhachet-roles-ehmpathy": "link:.",
     "test-fns": "1.6.0",
     "tsc-alias": "1.8.10",

package/dist/domain.roles/mechanic/briefs/practices/lang.terms/rule.forbid.term-script.md.pt1.md

@@ -1,7 +0,0 @@
-never use the term `script`
-
-it's overloaded
-
-choose what exactly its purpose is
-
-- adhoc usage? => `command`

package/dist/domain.roles/mechanic/briefs/practices/lang.terms/rule.forbid.term-script.md.pt2.md

@@ -1,9 +0,0 @@
-pitch: "script" is overloaded
-
-specify what it is
-- command? = shell invoked only
-- procedure? = reusable sequence of steps
-- operation? = domain logic procedure
-- etc
-
-all is scripted. be specific with what it is