rhachet-roles-ehmpathy 1.11.0 → 1.12.1

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,235 @@
+#!/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"
+
+  # Handle Claude Code's :* suffix matcher
+  # :* means "optionally match colon and anything after"
+  # e.g., "npm run test:*" matches "npm run test", "npm run test:", "npm run test:unit"
+
+  # First, escape regex special chars except * and :
+  local escaped_pattern
+  escaped_pattern=$(printf '%s' "$pattern" | sed 's/[.^$+?{}()[\]|\\]/\\&/g')
+
+  # Convert :* to placeholder first (to avoid * -> .* conversion interfering)
+  # Using a unique placeholder that won't appear in commands
+  escaped_pattern="${escaped_pattern//:\*/__COLON_STAR_PLACEHOLDER__}"
+
+  # Convert remaining * to .* (glob-style wildcard)
+  escaped_pattern="${escaped_pattern//\*/.*}"
+
+  # Now replace placeholder with the actual regex for :*
+  # (:.*)? matches: nothing, ":", ":foo", ":foo:bar"
+  escaped_pattern="${escaped_pattern//__COLON_STAR_PLACEHOLDER__/(:.*)?}"
+
+  # Build final regex
+  local regex="^${escaped_pattern}$"
+
+  if [[ "$cmd" =~ $regex ]]; then
+    return 0
+  fi
+  return 1
+}
+
+# Transform raw permission pattern to compact bracket notation for display
+format_pattern() {
+  local pattern="$1"
+
+  # Check if pattern ends with :*
+  if [[ "$pattern" == *":*" ]]; then
+    # Remove :* suffix and format with [p]: label (prefix match)
+    local prefix="${pattern%:*}"
+    echo "[p]: $prefix"
+  else
+    # Exact match - format with [e]: label
+    echo "[e]: $pattern"
+  fi
+}
+
+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 ""
+  echo "([e] = exact match, [p] = prefix match)"
+  echo ""
+  for pattern in "${ALLOWED_PATTERNS[@]}"; do
+    echo "  • $(format_pattern "$pattern")"
+  done
+  echo ""
+  echo "([e] = exact match, [p] = prefix match)"
+  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 ""
+  echo "([e] = exact match, [p] = prefix match)"
+  echo ""
+  for pattern in "${ALLOWED_PATTERNS[@]}"; do
+    echo "  • $(format_pattern "$pattern")"
+  done
+  echo ""
+  echo "([e] = exact match, [p] = prefix match)"
+  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/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 roles boot --repo ehmpathy --role mechanic)",
+
+      "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.11.0",
+  "version": "1.12.1",
   "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/git.worktree.test.sh

@@ -1,229 +0,0 @@
-#!/usr/bin/env bash
-######################################################################
-# .what = test suite for git worktree management scripts
-#
-# .why  = verify all worktree operations work correctly
-#
-# .how  = sets up temp git repo, exercises all commands, cleans up
-#
-# usage:
-#   ./git.worktree.test.sh
-#
-# guarantee:
-#   - creates isolated temp environment
-#   - cleans up after itself
-#   - exits 0 on success, 1 on failure
-######################################################################
-
-set -uo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TEST_DIR=""
-TESTS_PASSED=0
-TESTS_FAILED=0
-
-# colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-NC='\033[0m' # No Color
-
-# test helper: assert condition
-assert() {
-  local description="$1"
-  local condition="$2"
-
-  if eval "$condition"; then
-    echo -e "  ${GREEN}✓${NC} $description"
-    ((TESTS_PASSED++))
-  else
-    echo -e "  ${RED}✗${NC} $description"
-    ((TESTS_FAILED++))
-  fi
-}
-
-# test helper: assert output contains
-assert_output_contains() {
-  local description="$1"
-  local output="$2"
-  local expected="$3"
-
-  if [[ "$output" == *"$expected"* ]]; then
-    echo -e "  ${GREEN}✓${NC} $description"
-    ((TESTS_PASSED++))
-  else
-    echo -e "  ${RED}✗${NC} $description"
-    echo "    expected: $expected"
-    echo "    got: $output"
-    ((TESTS_FAILED++))
-  fi
-}
-
-# setup: create temp git repo with remote
-setup() {
-  echo "setting up test environment..."
-
-  # create temp directory
-  TEST_DIR="$(mktemp -d)"
-
-  # create "remote" bare repo
-  mkdir -p "$TEST_DIR/remote.git"
-  git -C "$TEST_DIR/remote.git" init --bare -q
-
-  # create "local" repo
-  mkdir -p "$TEST_DIR/local"
-  git -C "$TEST_DIR/local" init -q
-  git -C "$TEST_DIR/local" config user.email "test@test.com"
-  git -C "$TEST_DIR/local" config user.name "Test"
-  git -C "$TEST_DIR/local" remote add origin "$TEST_DIR/remote.git"
-
-  # initial commit
-  echo "test" > "$TEST_DIR/local/README.md"
-  git -C "$TEST_DIR/local" add .
-  git -C "$TEST_DIR/local" commit -m "initial commit" -q
-
-  # push to remote (handle both main and master default branch names)
-  git -C "$TEST_DIR/local" push -u origin HEAD:main -q 2>/dev/null || true
-
-  echo "  test dir: $TEST_DIR"
-  echo ""
-}
-
-# teardown: clean up temp directory
-teardown() {
-  echo ""
-  echo "cleaning up..."
-
-  if [[ -n "$TEST_DIR" ]] && [[ -d "$TEST_DIR" ]]; then
-    rm -rf "$TEST_DIR"
-    echo "  removed: $TEST_DIR"
-  fi
-}
-
-# run tests
-run_tests() {
-  local worktree_sh="$SCRIPT_DIR/git.worktree.sh"
-
-  echo "=== test: dispatcher ==="
-
-  # test: dispatcher shows usage
-  local usage_output
-  usage_output=$("$worktree_sh" 2>&1 || true)
-  assert_output_contains "shows usage on no args" "$usage_output" "usage: git.worktree.sh"
-
-  echo ""
-  echo "=== test: get (empty) ==="
-
-  # test: get with no worktrees
-  local get_empty
-  get_empty=$(cd "$TEST_DIR/local" && "$worktree_sh" get)
-  assert_output_contains "shows no worktrees" "$get_empty" "(no worktrees)"
-
-  echo ""
-  echo "=== test: set (create) ==="
-
-  # test: set creates worktree
-  local set_output
-  set_output=$(cd "$TEST_DIR/local" && "$worktree_sh" set test/branch1)
-  assert_output_contains "creates worktree" "$set_output" "[CREATE]"
-  assert_output_contains "correct path" "$set_output" "_worktrees/local/test.branch1"
-  assert "worktree directory exists" "[[ -d '$TEST_DIR/_worktrees/local/test.branch1' ]]"
-
-  echo ""
-  echo "=== test: set (idempotent) ==="
-
-  # test: set is idempotent
-  local set_keep
-  set_keep=$(cd "$TEST_DIR/local" && "$worktree_sh" set test/branch1)
-  assert_output_contains "keeps existing worktree" "$set_keep" "[KEEP]"
-
-  echo ""
-  echo "=== test: get (with worktrees) ==="
-
-  # test: get lists worktrees
-  local get_list
-  get_list=$(cd "$TEST_DIR/local" && "$worktree_sh" get)
-  assert_output_contains "lists worktrees header" "$get_list" "worktrees for local:"
-  assert_output_contains "lists worktree entry" "$get_list" "test.branch1"
-
-  echo ""
-  echo "=== test: set (second worktree) ==="
-
-  # test: create second worktree
-  local set_second
-  set_second=$(cd "$TEST_DIR/local" && "$worktree_sh" set feature/auth)
-  assert_output_contains "creates second worktree" "$set_second" "[CREATE]"
-  assert "second worktree exists" "[[ -d '$TEST_DIR/_worktrees/local/feature.auth' ]]"
-
-  echo ""
-  echo "=== test: get from worktree ==="
-
-  # test: get from within worktree resolves same dir
-  local get_from_wt
-  get_from_wt=$(cd "$TEST_DIR/_worktrees/local/test.branch1" && "$worktree_sh" get)
-  assert_output_contains "lists from worktree" "$get_from_wt" "worktrees for local:"
-  assert_output_contains "sees both worktrees" "$get_from_wt" "feature.auth"
-
-  echo ""
-  echo "=== test: set from worktree ==="
-
-  # test: set from within worktree creates in same _worktrees dir
-  local set_from_wt
-  set_from_wt=$(cd "$TEST_DIR/_worktrees/local/test.branch1" && "$worktree_sh" set test/from-wt)
-  assert_output_contains "creates from worktree" "$set_from_wt" "[CREATE]"
-  assert "created in same _worktrees dir" "[[ -d '$TEST_DIR/_worktrees/local/test.from-wt' ]]"
-
-  echo ""
-  echo "=== test: del ==="
-
-  # test: del removes worktree
-  local del_output
-  del_output=$(cd "$TEST_DIR/local" && "$worktree_sh" del test/from-wt)
-  assert_output_contains "deletes worktree" "$del_output" "[DELETE]"
-  assert "worktree removed" "[[ ! -d '$TEST_DIR/_worktrees/local/test.from-wt' ]]"
-
-  echo ""
-  echo "=== test: del (skip nonexistent) ==="
-
-  # test: del skips nonexistent
-  local del_skip
-  del_skip=$(cd "$TEST_DIR/local" && "$worktree_sh" del nonexistent/branch)
-  assert_output_contains "skips nonexistent" "$del_skip" "[SKIP]"
-  assert_output_contains "shows not found" "$del_skip" "(not found)"
-
-  echo ""
-  echo "=== test: cleanup remaining ==="
-
-  # cleanup remaining test worktrees
-  cd "$TEST_DIR/local" && "$worktree_sh" del test/branch1 >/dev/null
-  cd "$TEST_DIR/local" && "$worktree_sh" del feature/auth >/dev/null
-
-  local final_get
-  final_get=$(cd "$TEST_DIR/local" && "$worktree_sh" get)
-  assert_output_contains "all cleaned up" "$final_get" "(no worktrees)"
-}
-
-# main
-main() {
-  echo "git.worktree.sh test suite"
-  echo "=========================="
-  echo ""
-
-  setup
-
-  # run tests (trap ensures cleanup on failure)
-  trap teardown EXIT
-  run_tests
-
-  echo ""
-  echo "=========================="
-  echo -e "passed: ${GREEN}$TESTS_PASSED${NC}"
-  echo -e "failed: ${RED}$TESTS_FAILED${NC}"
-
-  if [[ $TESTS_FAILED -gt 0 ]]; then
-    exit 1
-  fi
-
-  exit 0
-}
-
-main "$@"

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