rhachet-roles-ehmpathy 1.13.6 → 1.13.8

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

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind forbid.stderr.redirect hook to Claude settings
+#
+# .why  = when Claude uses 2>&1, error messages are hidden and
+#         debugging becomes harder. this hook blocks such commands.
+#
+# .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
+#   ✔ prepends to hooks array (runs before other Bash hooks)
+#   ✔ 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/forbid.stderr.redirect.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: ensure hook is at the front of the hooks array
+jq --argjson hook "$HOOK_CONFIG" '
+  # Define the target command for comparison
+  def targetCmd: $hook.hooks.PreToolUse[0].hooks[0].command;
+
+  # Check if hook is already first in the Bash matcher
+  def hookIsFirst:
+    (.hooks.PreToolUse // [])
+    | map(select(.matcher == "Bash") | .hooks // [])
+    | flatten
+    | first
+    | .command == targetCmd;
+
+  # If hook is already first, return unchanged
+  if hookIsFirst 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 - remove our hook if present, then prepend it
+      .hooks.PreToolUse |= map(
+        if .matcher == "Bash" then
+          # Remove existing instance of our hook, then prepend
+          .hooks = $hook.hooks.PreToolUse[0].hooks + (.hooks | map(select(.command != targetCmd)))
+        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 "👌 forbid.stderr.redirect hook already bound"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# Atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔗 forbid.stderr.redirect hook bound successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ Claude will now be blocked from using 2>&1 in commands"

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

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind all mechanic hooks to Claude settings
+#
+# .why  = the mechanic role uses multiple hooks:
+#           • SessionStart: boot mechanic on every session
+#           • PreToolUse: check existing permissions before new requests
+#
+#         this script dispatches to each hook initializer.
+#
+# .how  = runs each init.claude.hooks.*.sh script in sequence
+#
+# guarantee:
+#   ✔ idempotent: safe to rerun
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+SKILLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Dispatch to each hook initializer
+"$SKILLS_DIR/init.claude.hooks.sessionstart.sh"
+"$SKILLS_DIR/init.claude.hooks.forbid.stderr.redirect.sh"
+"$SKILLS_DIR/init.claude.hooks.pretooluse.sh"

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

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind mechanic permissions to Claude settings
+#
+# .why  = the mechanic role needs conservative permissions to operate
+#         safely while still being productive.
+#
+#         this script manages permissions in .claude/settings.local.json:
+#           • replaces existing allows entirely (conservative)
+#           • extends denies by appending new entries (conservative)
+#           • extends asks by appending new entries (conservative)
+#           • idempotent: safe to rerun
+#
+# .how  = uses jq to merge the permissions configuration
+#         into the existing settings structure, creating it if absent.
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (hooks, other configs)
+#   ✔ replaces allow list entirely
+#   ✔ appends to deny list (no duplicates)
+#   ✔ appends to ask list (no duplicates)
+#   ✔ idempotent: safe to rerun
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+
+# define the permissions configuration to apply
+PERMISSIONS_CONFIG=$(cat <<'EOF'
+{
+  "permissions": {
+    "deny": [
+      "Bash(git commit:*)",
+      "Bash(sed:*)",
+      "Bash(tee:*)",
+      "Bash(find:*)",
+      "Bash(echo:*)",
+      "Bash(mv:*)",
+      "Bash(npx biome:*)",
+      "Bash(npx jest:*)"
+    ],
+    "ask": [
+      "Bash(bash:*)",
+      "Bash(chmod:*)",
+      "Bash(npm install:*)",
+      "Bash(pnpm install:*)",
+      "Bash(pnpm add:*)"
+    ],
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:hub.docker.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "WebFetch(domain:biomejs.dev)",
+
+      "Bash(ls:*)",
+      "Bash(tree:*)",
+      "Bash(cat:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(grep:*)",
+      "Bash(wc:*)",
+      "Bash(diff:*)",
+      "Bash(which:*)",
+      "Bash(file:*)",
+      "Bash(mkdir:*)",
+      "Bash(pwd)",
+      "Bash(bash src/logic/roles/mechanic/.skills/claude.tools/mvsafe.sh:*)",
+      "Bash(npm view:*)",
+      "Bash(npm list:*)",
+      "Bash(npm remove:*)",
+
+      "Bash(npx rhachet roles boot --repo ehmpathy --role mechanic)",
+      "Bash(npx tsx ./bin/run:*)",
+
+      "Bash(npm run build:*)",
+      "Bash(npm run build:compile)",
+      "Bash(npm run start:testdb:*)",
+
+
+      "Bash(npm run test:*)",
+      "Bash(npm run test:types:*)",
+      "Bash(npm run test:format:*)",
+      "Bash(npm run test:lint:*)",
+      "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:types:*)",
+      "Bash(THOROUGH=true npm run test:format:*)",
+      "Bash(THOROUGH=true npm run test:lint:*)",
+      "Bash(THOROUGH=true npm run test:unit:*)",
+      "Bash(THOROUGH=true npm run test:integration:*)",
+      "Bash(THOROUGH=true npm run test:acceptance:*)",
+
+      "Bash(npm run fix:*)",
+      "Bash(npm run fix:format:*)",
+      "Bash(npm run fix:lint:*)",
+
+      "Bash(gh pr checks:*)",
+      "Bash(gh pr status:*)",
+
+      "Bash(source .agent/repo=.this/skills/*)"
+    ]
+  }
+}
+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
+
+# apply permissions:
+# - replace allow entirely
+# - append to deny (unique)
+# - append to ask (unique)
+jq --argjson perms "$PERMISSIONS_CONFIG" '
+  # ensure .permissions exists
+  .permissions //= {} |
+
+  # replace allow entirely with our config
+  .permissions.allow = $perms.permissions.allow |
+
+  # append to deny (unique entries only)
+  .permissions.deny = ((.permissions.deny // []) + $perms.permissions.deny | unique) |
+
+  # append to ask (unique entries only)
+  .permissions.ask = ((.permissions.ask // []) + $perms.permissions.ask | unique)
+' "$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 permissions already configured"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔐 mechanic permissions configured successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ permissions applied:"
+echo "   • allow: replaced entirely"
+echo "   • deny: extended (no duplicates)"
+echo "   • ask: extended (no duplicates)"

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

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = initialize Claude settings for mechanic role
+#
+# .why  = mechanic needs both hooks and permissions configured to
+#         operate effectively. this script dispatches to both:
+#           • init.claude.hooks.sh - binds SessionStart hook
+#           • init.claude.permissions.sh - configures permissions
+#
+#         single entry point for full Claude configuration.
+#
+# .how  = runs both init scripts in sequence from the same directory.
+#
+# guarantee:
+#   ✔ backs up settings.local.json before changes (if exists)
+#   ✔ runs both hooks and permissions initialization
+#   ✔ fail-fast on any error
+#   ✔ idempotent: safe to rerun
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GITROOT="$(git rev-parse --show-toplevel)"
+SETTINGS_FILE="$GITROOT/.claude/settings.local.json"
+
+echo "🔧 init claude config for mechanic role..."
+echo ""
+
+# backup existing settings before changes
+if [[ -f "$SETTINGS_FILE" ]]; then
+  ISODATETIME="$(date -u +%Y-%m-%dT%H-%M-%SZ)"
+  BACKUP_FILE="$GITROOT/.claude/settings.$ISODATETIME.bak.local.json"
+  cp "$SETTINGS_FILE" "$BACKUP_FILE"
+  echo "📦 backed up settings to: ${BACKUP_FILE#$GITROOT/}"
+  echo ""
+fi
+
+# initialize hooks
+"$SCRIPT_DIR/init.claude.hooks.sh"
+echo ""
+
+# initialize permissions
+"$SCRIPT_DIR/init.claude.permissions.sh"
+echo ""
+
+echo "👌 claude config ready"

package/dist/logic/roles/mechanic/.skills/link.claude.transcripts.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = link Claude transcripts into project-local structure
+#
+# .why  = Claude stores transcripts in ~/.claude/projects/<encoded-path>
+#         which makes them hard to browse, version-control, and sync.
+#
+#         this script creates a symlink so transcripts appear under:
+#           <project>/.rhachet/claude/transcripts
+#
+#         without altering, moving, or creating files in Claude storage.
+#
+# guarantee:
+#   ✔ zero mutation to Claude's storage
+#   ✔ fail-fast if transcripts don't exist yet
+#   ✔ safe to rerun (idempotent)
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+DEST="$PROJECT_ROOT/.rhachet/claude/transcripts"
+
+# Resolve where Claude stores transcripts for this project’s cwd
+ENCODED_PATH="$(echo "$PROJECT_ROOT" | sed 's#/#-#g')"
+CLAUDE_STORAGE="$HOME/.claude/projects/$ENCODED_PATH"
+
+# Fail if Claude hasn't created the storage dir yet
+if [[ ! -d "$CLAUDE_STORAGE" ]]; then
+  echo "❌ no Claude transcripts found for this project:"
+  echo "   $CLAUDE_STORAGE"
+  echo "➡️  first run 'claude' once in this directory to create them"
+  exit 1
+fi
+
+# Ensure our local parent folder exists (not Claude’s)
+mkdir -p "$(dirname "$DEST")"
+
+# Create symlink pointing into Claude-managed storage
+ln -sfn "$CLAUDE_STORAGE" "$DEST"
+
+echo "🔗 linked:"
+echo "  $DEST → $CLAUDE_STORAGE"

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

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = run integration tests thoroughly with optional scope filter
+#
+# .why  = integration tests verify interactions between components
+#         and external systems. running them thoroughly (without
+#         --changedSince) ensures all tests pass, not just changed ones.
+#
+#         this is critical before releases, after major changes, or
+#         when verifying the entire test suite.
+#
+# usage for agents:
+#   - run all integration tests:
+#       ./test.integration.sh
+#
+#   - run tests matching a specific scope/pattern:
+#       ./test.integration.sh <pattern>
+#       example: ./test.integration.sh "user.*auth"
+#       example: ./test.integration.sh "database"
+#
+#   - the THOROUGH=true flag forces ALL tests to run, not just
+#     those changed since main branch
+#
+# guarantee:
+#   ✔ runs ALL integration tests (ignores --changedSince)
+#   ✔ supports optional jest pattern/scope filtering
+#   ✔ uses verbose output for debugging
+#   ✔ passes with no tests if scope matches nothing
+#   ✔ fail-fast on test failures
+######################################################################
+
+set -euo pipefail
+
+SCOPE="${1:-}"
+
+echo "🧪 running integration tests thoroughly..."
+echo ""
+
+if [[ -n "$SCOPE" ]]; then
+  echo "📍 scope filter: $SCOPE"
+  echo ""
+  THOROUGH=true npm run test:integration -- "$SCOPE"
+else
+  echo "📍 scope: all tests"
+  echo ""
+  THOROUGH=true npm run test:integration
+fi
+
+echo ""
+echo "✅ integration tests complete!"