rhachet-roles-ehmpathy 1.10.0 → 1.12.0

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.repo.structure/bad-practices/forbid.barrel.exports.ts.md

@@ -0,0 +1,41 @@
+this is an alias to ./forbid.index.ts.md
+
+NEVER do barrel exports
+
+e.g.,
+- `src/domain.objects/index.ts`
+- `src/domain.operations/organization/index.ts`
+- `src/domain.operations/organizationAccount/index.ts`
+- `src/access/daos/index.ts`
+- `src/contract/sdks/index.ts`
+
+all are banned
+
+they're just new aliases that increase
+- codepath variants
+- cyclical import chances
+
+totally forbidden
+
+they add zero value
+
+
+---
+
+the only thing that's allowed is
+
+within an index.ts file, exporting one object
+
+e.g.,
+
+```ts
+export const daoAwsOrganization = {
+  getOne,
+  getAll,
+  set,
+  del,
+}
+```
+nice and tight export
+
+but thats it. never just an export forwarder

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/bad-practices/forbid.term=existing.md

@@ -0,0 +1,10 @@
+never use the term `existing`; its a needless gerund
+
+either
+- foundBefore
+- or
+- foundAfter
+
+or some nonGerund alternative
+
+but never `existing`

package/dist/logic/roles/mechanic/.skills/claude.hooks/check.pretooluse.permissions.sh

@@ -0,0 +1,193 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = PreToolUse hook to encourage reuse of existing permissions
+#
+# .why  = when Claude attempts a command not covered by pre-approved
+#         permissions, this hook asks it to reconsider whether an
+#         existing permission could accomplish the same task.
+#
+#         this reduces permission prompts and encourages consistent
+#         command patterns across the project.
+#
+# .how  = reads JSON from stdin (per Claude Code docs), extracts
+#         tool_input.command, checks against allowed patterns.
+#         if no match, behavior depends on mode.
+#
+# usage:
+#   configure in .claude/settings.local.json under hooks.PreToolUse
+#
+# flags:
+#   --mode HARDNUDGE  (default) blocks on first attempt, allows on retry
+#                     tracks attempts in .claude/permissions.attempted.json
+#                     forces Claude to consciously decide to request
+#                     a new permission rather than doing so automatically
+#
+#   --mode SOFTNUDGE  outputs guidance but doesn't block (exit 0)
+#                     Claude sees the message but can proceed immediately
+#
+# guarantee:
+#   ✔ HARDNUDGE (default): blocks first attempt, allows retry
+#   ✔ SOFTNUDGE: non-blocking, feedback only
+#   ✔ fast: simple pattern matching
+#   ✔ helpful: shows available alternatives
+######################################################################
+
+set -euo pipefail
+
+# Parse flags
+MODE="HARDNUDGE"  # default
+HARDNUDGE_WINDOW_SECONDS=60  # default: 60 seconds
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --mode)
+      MODE="${2:-HARDNUDGE}"
+      shift 2
+      ;;
+    --window)
+      HARDNUDGE_WINDOW_SECONDS="${2:-60}"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+# Read JSON from stdin (Claude Code passes input via stdin, not env var)
+STDIN_INPUT=$(cat)
+
+# failfast: if no input received, something is wrong
+if [[ -z "$STDIN_INPUT" ]]; then
+  echo "ERROR: PreToolUse hook received no input via stdin" >&2
+  exit 2  # exit 2 = blocking error per Claude Code docs
+fi
+
+# Extract command from stdin JSON
+# Claude passes: {"tool_name": "Bash", "tool_input": {"command": "..."}}
+COMMAND=$(echo "$STDIN_INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+
+# Skip if not a Bash command or empty
+if [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# Find the .claude directory (search upward from current 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
+}
+
+# Find the settings file (search upward from current directory)
+find_settings_file() {
+  local claude_dir
+  claude_dir=$(find_claude_dir) || return 1
+  local settings_file="$claude_dir/settings.local.json"
+  if [[ -f "$settings_file" ]]; then
+    echo "$settings_file"
+    return 0
+  fi
+  return 1
+}
+
+SETTINGS_FILE=$(find_settings_file) || {
+  # No settings file found, allow command to proceed
+  exit 0
+}
+
+# Extract Bash permissions from settings file
+# Patterns look like: "Bash(npm run test:*)" -> extract "npm run test:*"
+mapfile -t ALLOWED_PATTERNS < <(
+  jq -r '.permissions.allow // [] | .[] | select(startswith("Bash(")) | sub("^Bash\\("; "") | sub("\\)$"; "")' "$SETTINGS_FILE" 2>/dev/null
+)
+
+# Check if command matches any allowed pattern
+match_pattern() {
+  local cmd="$1"
+  local pattern="$2"
+
+  # Convert glob * to regex .*
+  local regex="^${pattern//\*/.*}$"
+
+  if [[ "$cmd" =~ $regex ]]; then
+    return 0
+  fi
+  return 1
+}
+
+for pattern in "${ALLOWED_PATTERNS[@]}"; do
+  if match_pattern "$COMMAND" "$pattern"; then
+    exit 0  # Command matches an allowed pattern
+  fi
+done
+
+# Command not matched - handle based on mode
+
+# SOFTNUDGE mode: provide guidance but don't block (early return)
+# Output plain text - no hookSpecificOutput so normal permission flow continues
+if [[ "$MODE" == "SOFTNUDGE" ]]; then
+  echo ""
+  echo "⚠️  This command is not covered by existing pre-approved permissions."
+  echo ""
+  echo "Before requesting user approval, check if you can accomplish this task using one of these pre-approved patterns:"
+  echo ""
+  for pattern in "${ALLOWED_PATTERNS[@]}"; do
+    echo "  • $pattern"
+  done
+  echo ""
+  echo "If an existing permission pattern can solve your task, use that instead."
+  echo "If not, proceed with requesting approval."
+  echo ""
+  exit 0
+fi
+
+# HARDNUDGE mode (default): block on first attempt, allow on retry
+CLAUDE_DIR=$(find_claude_dir) || {
+  echo "ERROR: No .claude directory found. This hook requires a .claude directory." >&2
+  exit 1
+}
+ATTEMPTED_FILE="$CLAUDE_DIR/permission.nudges.local.json"
+
+# Ensure the file exists with valid JSON
+if [[ ! -f "$ATTEMPTED_FILE" ]]; then
+  echo '{}' > "$ATTEMPTED_FILE"
+fi
+
+# Check if this command was recently attempted
+now=$(date +%s)
+last_attempt=$(jq -r --arg cmd "$COMMAND" '.[$cmd] // 0' "$ATTEMPTED_FILE" 2>/dev/null || echo "0")
+elapsed=$((now - last_attempt))
+
+if [[ $elapsed -lt $HARDNUDGE_WINDOW_SECONDS ]]; then
+  # Claude already tried within the window - they've thought twice
+  # Exit silently with 0 so normal permission flow continues (user gets prompted)
+  exit 0
+fi
+
+# First attempt - record timestamp and block
+# Use a temp file for atomic update
+tmp_file=$(mktemp)
+jq --arg cmd "$COMMAND" --argjson ts "$now" '. + {($cmd): $ts}' "$ATTEMPTED_FILE" > "$tmp_file" 2>/dev/null && mv "$tmp_file" "$ATTEMPTED_FILE"
+
+# Output block message to stderr and exit 2 to deny
+{
+  echo ""
+  echo "🛑 BLOCKED: This command is not covered by existing pre-approved permissions."
+  echo ""
+  echo "Before requesting user approval, check if you can accomplish this task using one of these pre-approved patterns:"
+  echo ""
+  for pattern in "${ALLOWED_PATTERNS[@]}"; do
+    echo "  • $pattern"
+  done
+  echo ""
+  echo "If an existing permission pattern can solve your task, use that instead."
+  echo "If you've considered the alternatives and still need this specific command, retry it."
+  echo ""
+} >&2
+exit 2  # Exit 2 = block with error message

package/dist/logic/roles/mechanic/.skills/git.worktree.common.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = shared helpers for git worktree management
+#
+# .why  = centralizes path resolution and branch sanitization logic
+#         used by git.worktree.{get,set,del}.sh scripts
+#
+# .how  = source this file to get access to:
+#           - resolve_worktrees_dir: computes $REPO_WORKTREES_DIR
+#           - sanitize_branch_name: converts branch to worktree name
+#           - get_repo_name: extracts repo name from gitroot
+#
+# guarantee:
+#   - works from root repo or from within a worktree
+#   - consistent path resolution across all worktree scripts
+######################################################################
+
+# resolve the worktrees directory for this repo
+# handles both root repo and worktree contexts
+resolve_worktrees_dir() {
+  local gitroot
+  gitroot="$(git rev-parse --show-toplevel)"
+
+  local reponame
+  reponame="$(basename "$gitroot")"
+
+  # detect if we're in a worktree (path contains _worktrees)
+  if [[ "$gitroot" == *"_worktrees"* ]]; then
+    # we're in a worktree - reuse same _worktrees/$reponame dir
+    echo "${gitroot%/*}"
+  else
+    # root repo - compute sibling _worktrees dir
+    echo "$(dirname "$gitroot")/_worktrees/$reponame"
+  fi
+}
+
+# sanitize branch name for use as directory name
+# vlad/practs => vlad.practs
+sanitize_branch_name() {
+  local branch="$1"
+  echo "${branch//\//.}"
+}
+
+# get the repo name (works from root repo or worktree)
+get_repo_name() {
+  local gitroot
+  gitroot="$(git rev-parse --show-toplevel)"
+
+  # detect if we're in a worktree (path contains _worktrees)
+  if [[ "$gitroot" == *"_worktrees"* ]]; then
+    # extract repo name from _worktrees/$reponame/$worktree path
+    # gitroot = /path/to/_worktrees/$reponame/$worktree
+    local worktrees_parent="${gitroot%/*}"  # /path/to/_worktrees/$reponame
+    basename "$worktrees_parent"
+  else
+    basename "$gitroot"
+  fi
+}

package/dist/logic/roles/mechanic/.skills/git.worktree.del.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = remove a git worktree
+#
+# .why  = clean up worktrees no longer needed
+#
+# .how  = removes worktree at @gitroot/../_worktrees/$reponame/$branch
+#
+# usage:
+#   git.worktree.del.sh <branch>
+#
+# guarantee:
+#   - idempotent: [DELETE] if exists, [SKIP] if not found
+#   - works from root repo or from within a worktree
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# source shared helpers
+source "$SCRIPT_DIR/git.worktree.common.sh"
+
+# parse arguments
+BRANCH="${1:-}"
+
+# validate branch argument
+if [[ -z "$BRANCH" ]]; then
+  echo "error: branch name required"
+  echo "usage: git.worktree.del.sh <branch>"
+  exit 1
+fi
+
+# resolve paths
+REPO_WORKTREES_DIR="$(resolve_worktrees_dir)"
+WORKTREE_NAME="$(sanitize_branch_name "$BRANCH")"
+WORKTREE_PATH="$REPO_WORKTREES_DIR/$WORKTREE_NAME"
+
+# delete logic
+if [[ -d "$WORKTREE_PATH" ]]; then
+  # remove worktree via git
+  git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || {
+    # fallback: manual removal if git worktree remove fails
+    rm -rf "$WORKTREE_PATH"
+    git worktree prune
+  }
+
+  echo "[DELETE] $WORKTREE_NAME"
+else
+  echo "[SKIP] $WORKTREE_NAME (not found)"
+fi

package/dist/logic/roles/mechanic/.skills/git.worktree.get.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = list git worktrees for this repo
+#
+# .why  = discover existing worktrees managed by git.worktree.sh
+#
+# .how  = lists worktrees at @gitroot/../_worktrees/$reponame/
+#
+# usage:
+#   git.worktree.get.sh
+#
+# guarantee:
+#   - works from root repo or from within a worktree
+#   - shows "(no worktrees)" if none exist
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# source shared helpers
+source "$SCRIPT_DIR/git.worktree.common.sh"
+
+# resolve worktrees directory
+REPO_WORKTREES_DIR="$(resolve_worktrees_dir)"
+REPO_NAME="$(get_repo_name)"
+
+# check if worktrees directory exists
+if [[ ! -d "$REPO_WORKTREES_DIR" ]]; then
+  echo "(no worktrees)"
+  exit 0
+fi
+
+# list worktrees
+WORKTREES=()
+for dir in "$REPO_WORKTREES_DIR"/*/; do
+  [[ -d "$dir" ]] && WORKTREES+=("$dir")
+done
+
+# handle empty
+if [[ ${#WORKTREES[@]} -eq 0 ]]; then
+  echo "(no worktrees)"
+  exit 0
+fi
+
+# output worktree list
+echo "worktrees for $REPO_NAME:"
+for dir in "${WORKTREES[@]}"; do
+  name="$(basename "$dir")"
+  echo "  $name => $dir"
+done

package/dist/logic/roles/mechanic/.skills/git.worktree.set.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = findsert a git worktree for a branch
+#
+# .why  = enable parallel work on same repo without nested worktrees
+#         worktrees are placed outside repo so git diff stays clean
+#
+# .how  = creates worktree at @gitroot/../_worktrees/$reponame/$branch
+#
+# usage:
+#   git.worktree.set.sh <branch>            # findsert worktree
+#   git.worktree.set.sh <branch> --open     # findsert + open in codium
+#   git.worktree.set.sh <branch> --main     # create from origin/main
+#
+# guarantee:
+#   - idempotent: [KEEP] if exists, [CREATE] if not
+#   - works from root repo or from within a worktree
+#   - worktree placed outside repo (not nested)
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# source shared helpers
+source "$SCRIPT_DIR/git.worktree.common.sh"
+
+# parse arguments
+BRANCH=""
+FLAG_OPEN=false
+FLAG_MAIN=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --open)
+      FLAG_OPEN=true
+      shift
+      ;;
+    --main)
+      FLAG_MAIN=true
+      shift
+      ;;
+    -*)
+      echo "error: unknown flag '$1'"
+      echo "usage: git.worktree.set.sh <branch> [--open] [--main]"
+      exit 1
+      ;;
+    *)
+      if [[ -z "$BRANCH" ]]; then
+        BRANCH="$1"
+      else
+        echo "error: unexpected argument '$1'"
+        exit 1
+      fi
+      shift
+      ;;
+  esac
+done
+
+# validate branch argument
+if [[ -z "$BRANCH" ]]; then
+  echo "error: branch name required"
+  echo "usage: git.worktree.set.sh <branch> [--open] [--main]"
+  exit 1
+fi
+
+# resolve paths
+REPO_WORKTREES_DIR="$(resolve_worktrees_dir)"
+WORKTREE_NAME="$(sanitize_branch_name "$BRANCH")"
+WORKTREE_PATH="$REPO_WORKTREES_DIR/$WORKTREE_NAME"
+
+# ensure parent directory exists
+mkdir -p "$REPO_WORKTREES_DIR"
+
+# findsert logic
+if [[ -d "$WORKTREE_PATH" ]]; then
+  echo "[KEEP] $WORKTREE_NAME => $WORKTREE_PATH"
+else
+  # create worktree
+  if [[ "$FLAG_MAIN" == true ]]; then
+    # fetch latest main first
+    git fetch origin main 2>/dev/null || git fetch origin master 2>/dev/null || true
+
+    # create new branch from origin/main
+    git worktree add -b "$BRANCH" "$WORKTREE_PATH" origin/main 2>/dev/null || \
+      git worktree add -b "$BRANCH" "$WORKTREE_PATH" origin/master
+  else
+    # check if branch exists
+    if git show-ref --verify --quiet "refs/heads/$BRANCH" 2>/dev/null; then
+      # branch exists locally, checkout existing
+      git worktree add "$WORKTREE_PATH" "$BRANCH"
+    elif git show-ref --verify --quiet "refs/remotes/origin/$BRANCH" 2>/dev/null; then
+      # branch exists on remote, track it
+      git worktree add --track -b "$BRANCH" "$WORKTREE_PATH" "origin/$BRANCH"
+    else
+      # create new branch from current HEAD
+      git worktree add -b "$BRANCH" "$WORKTREE_PATH"
+    fi
+  fi
+
+  echo "[CREATE] $WORKTREE_NAME => $WORKTREE_PATH"
+fi
+
+# open in codium if requested
+if [[ "$FLAG_OPEN" == true ]]; then
+  echo "opening in codium..."
+  codium "$WORKTREE_PATH"
+fi

package/dist/logic/roles/mechanic/.skills/git.worktree.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = dispatcher for git worktree management
+#
+# .why  = single entry point for get|set|del subcommands
+#         enables convenient `git.worktree.sh get|set|del` interface
+#
+# .how  = routes to git.worktree.{get,set,del}.sh based on subcommand
+#
+# usage:
+#   git.worktree.sh get                     # list worktrees
+#   git.worktree.sh set <branch>            # findsert worktree
+#   git.worktree.sh set <branch> --open     # findsert + open in codium
+#   git.worktree.sh set <branch> --main     # create from origin/main
+#   git.worktree.sh del <branch>            # remove worktree
+#
+# guarantee:
+#   - dispatches to correct subcommand script
+#   - shows usage on invalid/missing subcommand
+#   - fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SUBCOMMAND="${1:-}"
+
+case "$SUBCOMMAND" in
+  get|set|del)
+    shift
+    exec "$SCRIPT_DIR/git.worktree.$SUBCOMMAND.sh" "$@"
+    ;;
+  *)
+    echo "usage: git.worktree.sh <command> [args]"
+    echo ""
+    echo "commands:"
+    echo "  get              list worktrees for this repo"
+    echo "  set <branch>     findsert worktree for branch"
+    echo "  del <branch>     remove worktree for branch"
+    echo ""
+    echo "options (for set):"
+    echo "  --open           open worktree in codium after creation"
+    echo "  --main           create branch from origin/main"
+    exit 1
+    ;;
+esac

package/dist/logic/roles/mechanic/.skills/init.claude.hooks.pretooluse.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind mechanic PreToolUse hook to Claude settings
+#
+# .why  = when Claude attempts a Bash command not covered by existing
+#         permissions, this hook provides feedback asking it to
+#         reconsider whether a pre-approved command could work instead.
+#
+#         this reduces unnecessary permission prompts and encourages
+#         consistent command patterns across the project.
+#
+# .how  = uses jq to findsert the PreToolUse hook configuration
+#         into .claude/settings.local.json
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (permissions, other hooks)
+#   ✔ idempotent: no-op if hook already present
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+SKILLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_SCRIPT="$SKILLS_DIR/claude.hooks/check.pretooluse.permissions.sh"
+
+# Verify hook script exists
+if [[ ! -f "$HOOK_SCRIPT" ]]; then
+  echo "❌ hook script not found: $HOOK_SCRIPT" >&2
+  exit 1
+fi
+
+# Define the hook configuration to findsert
+HOOK_CONFIG=$(cat <<EOF
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$HOOK_SCRIPT",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+)
+
+# Ensure .claude directory exists
+mkdir -p "$(dirname "$SETTINGS_FILE")"
+
+# Initialize settings file if it doesn't exist
+if [[ ! -f "$SETTINGS_FILE" ]]; then
+  echo "{}" > "$SETTINGS_FILE"
+fi
+
+# Findsert: merge the hook configuration if not already present
+jq --argjson hook "$HOOK_CONFIG" '
+  # Define the target command for comparison
+  def targetCmd: $hook.hooks.PreToolUse[0].hooks[0].command;
+
+  # Check if hook already exists
+  def hookExists:
+    (.hooks.PreToolUse // [])
+    | map(select(.matcher == "Bash") | .hooks // [])
+    | flatten
+    | map(.command)
+    | any(. == targetCmd);
+
+  # If hook already exists, return unchanged
+  if hookExists then
+    .
+  else
+    # Ensure .hooks exists
+    .hooks //= {} |
+
+    # Ensure .hooks.PreToolUse exists
+    .hooks.PreToolUse //= [] |
+
+    # Check if our matcher already exists
+    if (.hooks.PreToolUse | map(.matcher) | index("Bash")) then
+      # Matcher exists, add our hook to its hooks array
+      .hooks.PreToolUse |= map(
+        if .matcher == "Bash" then
+          .hooks += $hook.hooks.PreToolUse[0].hooks
+        else
+          .
+        end
+      )
+    else
+      # Matcher does not exist, add the entire entry
+      .hooks.PreToolUse += $hook.hooks.PreToolUse
+    end
+  end
+' "$SETTINGS_FILE" > "$SETTINGS_FILE.tmp"
+
+# Check if any changes were made
+if diff -q "$SETTINGS_FILE" "$SETTINGS_FILE.tmp" >/dev/null 2>&1; then
+  rm "$SETTINGS_FILE.tmp"
+  echo "👌 mechanic PreToolUse hook already bound"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# Atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔗 mechanic PreToolUse hook bound successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ Claude will now be reminded to check existing permissions before requesting new ones"

package/dist/logic/roles/mechanic/.skills/init.claude.hooks.sessionstart.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind mechanic SessionStart hook to Claude settings
+#
+# .why  = the mechanic role needs to boot on every Claude session
+#         to ensure project context and briefs are loaded.
+#
+#         this script "findserts" (find-or-insert) the SessionStart
+#         hook into .claude/settings.local.json, ensuring:
+#           • the hook is present after running this skill
+#           • no duplication if already present
+#           • idempotent: safe to rerun
+#
+# .how  = uses jq to merge the SessionStart hook configuration
+#         into the existing hooks structure, creating it if absent.
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (permissions, other hooks)
+#   ✔ idempotent: no-op if hook already present
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+
+# Define the hook configuration to findsert
+HOOK_CONFIG=$(cat <<'EOF'
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx rhachet roles boot --repo ehmpathy --role mechanic",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+)
+
+# Ensure .claude directory exists
+mkdir -p "$(dirname "$SETTINGS_FILE")"
+
+# Initialize settings file if it doesn't exist
+if [[ ! -f "$SETTINGS_FILE" ]]; then
+  echo "{}" > "$SETTINGS_FILE"
+fi
+
+# Findsert: merge the hook configuration if not already present
+# Strategy: deep merge with existing hooks, creating structure if needed
+jq --argjson hook "$HOOK_CONFIG" '
+  # Define the target command for comparison
+  def targetCmd: "npx rhachet roles boot --repo ehmpathy --role mechanic";
+
+  # Check if hook already exists
+  def hookExists:
+    (.hooks.SessionStart // [])
+    | map(select(.matcher == "*") | .hooks // [])
+    | flatten
+    | map(.command)
+    | index(targetCmd) != null;
+
+  # If hook already exists, return unchanged
+  if hookExists then
+    .
+  else
+    # Ensure .hooks exists
+    .hooks //= {} |
+
+    # Ensure .hooks.SessionStart exists
+    .hooks.SessionStart //= [] |
+
+    # Check if our matcher already exists
+    if (.hooks.SessionStart | map(.matcher) | index("*")) then
+      # Matcher exists, add our hook to its hooks array
+      .hooks.SessionStart |= map(
+        if .matcher == "*" then
+          .hooks += $hook.hooks.SessionStart[0].hooks
+        else
+          .
+        end
+      )
+    else
+      # Matcher does not exist, add the entire entry
+      .hooks.SessionStart += $hook.hooks.SessionStart
+    end
+  end
+' "$SETTINGS_FILE" > "$SETTINGS_FILE.tmp"
+
+# Check if any changes were made
+if diff -q "$SETTINGS_FILE" "$SETTINGS_FILE.tmp" >/dev/null 2>&1; then
+  rm "$SETTINGS_FILE.tmp"
+  echo "👌 mechanic SessionStart hook already bound"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# Atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔗 mechanic SessionStart hook bound successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ next time you start a Claude session, the mechanic will boot automatically"

package/dist/logic/roles/mechanic/.skills/init.claude.hooks.sh

@@ -1,113 +1,24 @@
 #!/usr/bin/env bash
 ######################################################################
-# .what = bind mechanic SessionStart hook to Claude settings
+# .what = bind all mechanic hooks to Claude settings
 #
-# .why  = the mechanic role needs to boot on every Claude session
-#         to ensure project context and briefs are loaded.
+# .why  = the mechanic role uses multiple hooks:
+#           • SessionStart: boot mechanic on every session
+#           • PreToolUse: check existing permissions before new requests
 #
-#         this script "findserts" (find-or-insert) the SessionStart
-#         hook into .claude/settings.local.json, ensuring:
-#           • the hook is present after running this skill
-#           • no duplication if already present
-#           • idempotent: safe to rerun
+#         this script dispatches to each hook initializer.
 #
-# .how  = uses jq to merge the SessionStart hook configuration
-#         into the existing hooks structure, creating it if absent.
+# .how  = runs each init.claude.hooks.*.sh script in sequence
 #
 # guarantee:
-#   ✔ creates .claude/settings.local.json if missing
-#   ✔ preserves existing settings (permissions, other hooks)
-#   ✔ idempotent: no-op if hook already present
+#   ✔ idempotent: safe to rerun
 #   ✔ fail-fast on errors
 ######################################################################
 
 set -euo pipefail
 
-PROJECT_ROOT="$PWD"
-SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+SKILLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
-# Define the hook configuration to findsert
-HOOK_CONFIG=$(cat <<'EOF'
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx rhachet roles boot --repo ehmpathy --role mechanic",
-            "timeout": 60
-          }
-        ]
-      }
-    ]
-  }
-}
-EOF
-)
-
-# Ensure .claude directory exists
-mkdir -p "$(dirname "$SETTINGS_FILE")"
-
-# Initialize settings file if it doesn't exist
-if [[ ! -f "$SETTINGS_FILE" ]]; then
-  echo "{}" > "$SETTINGS_FILE"
-fi
-
-# Findsert: merge the hook configuration if not already present
-# Strategy: deep merge with existing hooks, creating structure if needed
-jq --argjson hook "$HOOK_CONFIG" '
-  # Define the target command for comparison
-  def targetCmd: "npx rhachet roles boot --repo ehmpathy --role mechanic";
-
-  # Check if hook already exists
-  def hookExists:
-    (.hooks.SessionStart // [])
-    | map(select(.matcher == "*") | .hooks // [])
-    | flatten
-    | map(.command)
-    | index(targetCmd) != null;
-
-  # If hook already exists, return unchanged
-  if hookExists then
-    .
-  else
-    # Ensure .hooks exists
-    .hooks //= {} |
-
-    # Ensure .hooks.SessionStart exists
-    .hooks.SessionStart //= [] |
-
-    # Check if our matcher already exists
-    if (.hooks.SessionStart | map(.matcher) | index("*")) then
-      # Matcher exists, add our hook to its hooks array
-      .hooks.SessionStart |= map(
-        if .matcher == "*" then
-          .hooks += $hook.hooks.SessionStart[0].hooks
-        else
-          .
-        end
-      )
-    else
-      # Matcher does not exist, add the entire entry
-      .hooks.SessionStart += $hook.hooks.SessionStart
-    end
-  end
-' "$SETTINGS_FILE" > "$SETTINGS_FILE.tmp"
-
-# Check if any changes were made
-if diff -q "$SETTINGS_FILE" "$SETTINGS_FILE.tmp" >/dev/null 2>&1; then
-  rm "$SETTINGS_FILE.tmp"
-  echo "👌 mechanic SessionStart hook already bound"
-  echo "   $SETTINGS_FILE"
-  exit 0
-fi
-
-# Atomic replace
-mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
-
-echo "🔗 mechanic SessionStart hook bound successfully!"
-echo "   $SETTINGS_FILE"
-echo ""
-echo "✨ next time you start a Claude session, the mechanic will boot automatically"
+# Dispatch to each hook initializer
+"$SKILLS_DIR/init.claude.hooks.sessionstart.sh"
+"$SKILLS_DIR/init.claude.hooks.pretooluse.sh"

package/dist/logic/roles/mechanic/.skills/init.claude.permissions.sh

@@ -37,6 +37,7 @@ PERMISSIONS_CONFIG=$(cat <<'EOF'
       "Bash(git commit:*)"
     ],
     "ask": [
+      "Bash(bash:*)",
       "Bash(chmod:*)",
       "Bash(pnpm install:*)",
       "Bash(pnpm add:*)"
@@ -47,16 +48,40 @@ PERMISSIONS_CONFIG=$(cat <<'EOF'
       "WebFetch(domain:www.npmjs.com)",
       "WebFetch(domain:hub.docker.com)",
       "WebFetch(domain:raw.githubusercontent.com)",
-      "Bash(THOROUGH=true npm run test:*)",
-      "Bash(AWS_PROFILE=ahbode.dev npm run test:integration:*)",
-      "Bash(npm run fix:*)",
-      "Bash(AWS_PROFILE=ahbode.dev npx jest:*)",
-      "Bash(AWS_PROFILE=ahbode.dev npm run deploy:dev:*)",
-      "Bash(AWS_PROFILE=ahbode.dev STAGE=dev npm run test:acceptance:*)",
+
+      "Bash(npm run build:*)",
       "Bash(npm run start:testdb:*)",
+      "Bash(AWS_PROFILE=ahbode.dev npm run deploy:dev:*)",
+
       "Bash(cat:*)",
       "Bash(unzip:*)",
-      "Bash(npm view:*)"
+      "Bash(npm view:*)",
+      "Bash(npm list:*)",
+      "Bash(pnpm list:*)",
+
+      "Bash(npx rhachet:*)",
+
+      "Bash(npm run test:*)",
+      "Bash(npm run test:unit:*)",
+      "Bash(npm run test:integration:*)",
+      "Bash(npm run test:acceptance:*)",
+
+      "Bash(THOROUGH=true npm run test:*)",
+      "Bash(THOROUGH=true npm run test:unit:*)",
+      "Bash(THOROUGH=true npm run test:integration:*)",
+      "Bash(THOROUGH=true npm run test:acceptance:*)",
+
+      "Bash(AWS_PROFILE=ahbode.dev npm run test:integration:*)",
+      "Bash(AWS_PROFILE=ahbode.dev STAGE=dev npm run test:acceptance:*)",
+
+      "Bash(npm run fix:*)",
+      "Bash(npm run fix:format:*)",
+      "Bash(npm run fix:lint:*)",
+      "Bash(npm run fix:types:*)",
+
+      "Bash(find:*)",
+
+      "Bash(source .agent/repo=.this/skills/*)"
     ]
   }
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [
@@ -26,7 +26,7 @@
     "fix:lint": "eslint -c ./.eslintrc.js src/**/*.ts --fix",
     "build:clean": "rm dist/ -rf",
     "build:compile": "tsc -p ./tsconfig.build.json",
-    "build:complete": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --exclude='**/.behavior/**' --include='**/*.template.md' --include='**/.briefs/**/*.md' --include='**/.briefs/*.md' --include='**/.skills/**/*.sh' --include='**/.skills/*.sh' --exclude='*' src/ dist/",
+    "build:complete": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --exclude='**/.behavior/**' --exclude='**/*.test.sh' --include='**/*.template.md' --include='**/.briefs/**/*.md' --include='**/.briefs/*.md' --include='**/.skills/**/*.sh' --include='**/.skills/*.sh' --exclude='*' src/ dist/",
     "build": "npm run build:clean && npm run build:compile && npm run build:complete",
     "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
     "test:types": "tsc -p ./tsconfig.build.json --noEmit",

package/dist/logic/roles/mechanic/.skills/run.test.sh

@@ -1,251 +0,0 @@
-#!/usr/bin/env bash
-######################################################################
-# # tldr
-#
-# .what: run tests with proper setup, logs, and context preservation
-# .why:  preserve test output for review without rerun, auto-configure AWS and testdb
-# .how:  ./run.test.sh unit
-#        ./run.test.sh integration "pattern"
-#        ./run.test.sh acceptance
-#
-######################################################################
-# # full
-#
-# .what
-#
-# run tests with proper setup, logs, and context preservation
-#
-# supports unit, integration, and acceptance tests with automatic:
-# - output logs to .log/test/ for repeated review
-# - scope filter and THOROUGH mode
-# - AWS profile configuration (for repos with AWS resources)
-# - test database provision (when start:testdb is available)
-#
-#
-# .why
-#
-# tests require different setup depending on their type:
-#
-# unit tests:
-#   - isolated, no external dependencies
-#   - fast execution
-#   - use --changedSince by default for speed
-#
-# integration tests:
-#   - interact with databases and remote resources
-#   - require AWS credentials (if repo uses AWS)
-#   - require test databases (if repo uses a testdb)
-#   - test interactions between components
-#
-# acceptance tests:
-#   - end-to-end testing
-#   - require AWS credentials (if repo uses AWS)
-#   - require test database provisioning
-#   - verify complete user workflows
-#
-# all tests benefit from:
-#   - output logs via tee to .log/test/{type}/run.{timestamp}.out
-#   - preserved context for review without rerun
-#   - comparison of results across test runs
-#
-#
-# .howto.use
-#
-# ## unit tests
-#
-# run all unit tests (uses --changedSince for speed):
-#   ./run.test.sh unit
-#
-# run unit tests that match a pattern (automatically THOROUGH):
-#   ./run.test.sh unit "syncPhone"
-#   ./run.test.sh unit "relate.*Path"
-#
-# run all unit tests thoroughly (no --changedSince):
-#   THOROUGH=true ./run.test.sh unit
-#
-# behavior:
-#   - no AWS_PROFILE configuration
-#   - no test database provision
-#   - uses --changedSince by default (unless scope provided or THOROUGH=true)
-#   - logs to .log/test/unit/run.{timestamp}.out
-#
-#
-# ## integration tests
-#
-# run all integration tests:
-#   ./run.test.sh integration
-#
-# run integration tests that match a pattern:
-#   ./run.test.sh integration "database.*sync"
-#   ./run.test.sh integration "whodis"
-#
-# behavior:
-#   - sets AWS_PROFILE=$org.dev (if awsAccountId in declapract.use.yml)
-#   - runs start:testdb (if available in package.json)
-#   - uses --changedSince by default (unless scope provided or THOROUGH=true)
-#   - logs to .log/test/integration/run.{timestamp}.out
-#
-#
-# ## acceptance tests
-#
-# run all acceptance tests locally:
-#   ./run.test.sh acceptance
-#
-# run acceptance tests that match a pattern:
-#   ./run.test.sh acceptance "user.*flow"
-#
-# behavior:
-#   - sets AWS_PROFILE=$org.dev (if awsAccountId in declapract.use.yml)
-#   - runs start:testdb (if available in package.json)
-#   - uses test:acceptance:locally (local execution only for now)
-#   - logs to .log/test/acceptance/run.{timestamp}.out
-#
-#
-# ## review test output
-#
-# all test output is logged via tee to .log/test/{type}/run.{timestamp}.out
-#
-# review the latest test run:
-#   cat .log/test/unit/run.*.out | tail -n 1 | xargs cat
-#
-# compare test results across runs:
-#   ls -t .log/test/unit/
-#   diff .log/test/unit/run.2025-11-23T15-00-00Z.out \
-#        .log/test/unit/run.2025-11-23T15-10-00Z.out
-#
-# search for failures in logs:
-#   grep -r "FAIL" .log/test/unit/
-#
-#
-# .guarantee
-#
-#   ✔ configure AWS_PROFILE only if awsAccountId in declapract.use.yml
-#   ✔ provision test database only if start:testdb in package.json
-#   ✔ log output to .log/test/{type}/run.{timestamp}.out via tee
-#   ✔ preserve context for repeated review without rerun
-#   ✔ support jest pattern/scope filter
-#   ✔ automatically set THOROUGH=true when scope is provided
-#   ✔ fail-fast on test failures
-#   ✔ show relative paths for easy navigation
-######################################################################
-
-set -euo pipefail
-
-# Parse arguments
-TEST_TYPE="${1:-}"
-SCOPE="${2:-}"
-
-# Default to THOROUGH mode when scope is provided (unless explicitly set)
-if [[ -n "$SCOPE" ]] && [[ -z "${THOROUGH:-}" ]]; then
-  export THOROUGH=true
-fi
-
-# Validate test type
-if [[ -z "$TEST_TYPE" ]]; then
-  echo "✗ test type required"
-  echo ""
-  echo "usage: $0 <type> [pattern]"
-  echo ""
-  echo "types:"
-  echo "  unit         - run unit tests"
-  echo "  integration  - run integration tests"
-  echo "  acceptance   - run acceptance tests"
-  echo ""
-  echo "examples:"
-  echo "  $0 unit"
-  echo "  $0 integration 'database.*sync'"
-  echo "  THOROUGH=true $0 unit"
-  exit 1
-fi
-
-if [[ ! "$TEST_TYPE" =~ ^(unit|integration|acceptance)$ ]]; then
-  echo "✗ invalid test type: $TEST_TYPE"
-  echo "   valid types: unit, integration, acceptance"
-  exit 1
-fi
-
-PROJECT_ROOT="$PWD"
-LOG_DIR="$PROJECT_ROOT/.log/test/$TEST_TYPE"
-TIMESTAMP=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
-LOG_FILE="$LOG_DIR/run.$TIMESTAMP.out"
-
-# Ensure log directory exists
-mkdir -p "$LOG_DIR"
-
-echo "→ run $TEST_TYPE tests"
-echo "→ log to: ${LOG_FILE#$PROJECT_ROOT/}"
-echo ""
-
-# Configure AWS profile and provision test database for integration/acceptance tests
-if [[ "$TEST_TYPE" == "integration" ]] || [[ "$TEST_TYPE" == "acceptance" ]]; then
-  # Check if awsAccountId is specified in declapract.use.yml
-  if [[ -f "declapract.use.yml" ]] && grep -q "awsAccountId:" declapract.use.yml; then
-    # Extract organization from declapract.use.yml
-    ORGANIZATION=$(grep -E '^\s*organizationName:' declapract.use.yml | sed "s/.*organizationName:[[:space:]]*['\"]*//" | sed "s/['\"].*//")
-
-    if [[ -n "$ORGANIZATION" ]]; then
-      # Configure AWS profile for dev resources
-      export AWS_PROFILE="$ORGANIZATION.dev"
-      echo "→ AWS_PROFILE=$AWS_PROFILE"
-    fi
-  fi
-
-  # Start test database if available in package.json
-  if npm run | grep -q "start:testdb"; then
-    echo "→ start:testdb"
-    echo ""
-    npm run start:testdb 2>&1 | tee -a "$LOG_FILE"
-  fi
-fi
-
-# Build the test command
-case "$TEST_TYPE" in
-  unit)
-    TEST_COMMAND="npm run test:unit"
-    ;;
-  integration)
-    TEST_COMMAND="npm run test:integration"
-    ;;
-  acceptance)
-    # only support local acceptance tests for now
-    TEST_COMMAND="npm run test:acceptance:locally"
-    ;;
-esac
-
-# Add scope filter if provided
-if [[ -n "$SCOPE" ]]; then
-  echo "→ scope filter: $SCOPE"
-  echo ""
-  TEST_COMMAND="$TEST_COMMAND -- '$SCOPE'"
-else
-  echo "→ scope: all tests"
-  echo ""
-fi
-
-# Run tests with output logged via tee
-echo "> $TEST_COMMAND" | tee -a "$LOG_FILE"
-echo "" | tee -a "$LOG_FILE"
-
-# For unit tests, strip color codes from log file while preserving them in terminal output
-if [[ "$TEST_TYPE" == "unit" ]]; then
-  eval "$TEST_COMMAND" 2>&1 | tee >(sed 's/\x1B\[[0-9;]*[JKmsu]//g' >> "$LOG_FILE")
-  TEST_EXIT_CODE=${PIPESTATUS[0]}
-else
-  eval "$TEST_COMMAND" 2>&1 | tee -a "$LOG_FILE"
-  TEST_EXIT_CODE=${PIPESTATUS[0]}
-fi
-
-echo "" | tee -a "$LOG_FILE"
-
-if [[ $TEST_EXIT_CODE -eq 0 ]]; then
-  echo "✓ $TEST_TYPE tests complete!" | tee -a "$LOG_FILE"
-  echo "→ log saved: ${LOG_FILE#$PROJECT_ROOT/}"
-  exit 0
-else
-  echo "✗ $TEST_TYPE tests failed" | tee -a "$LOG_FILE"
-  echo "→ log saved: ${LOG_FILE#$PROJECT_ROOT/}"
-  echo ""
-  echo "→ review the log file for details:"
-  echo "   cat ${LOG_FILE#$PROJECT_ROOT/}"
-  exit $TEST_EXIT_CODE
-fi