rhachet-roles-ehmpathy 1.13.1 → 1.13.3

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,156 @@
+#!/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:*)"
+    ],
+    "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(npm view:*)",
+      "Bash(npm list:*)",
+      "Bash(npm remove:*)",
+
+      "Bash(npx rhachet roles boot --repo ehmpathy --role mechanic)",
+      "Bash(npx tsx ./bin/run:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx biome:*)",
+      "Bash(npx jest:*)",
+
+      "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: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!"

package/dist/logic/roles/mechanic/codediff/routeArtistCodeDiff.template.md

@@ -0,0 +1,46 @@
+directive
+- <codediff><imagine> the [ask] against the [inflight]
+  - input = [inflight], [ask], [claims], [feedback]?
+  - output = new [inflight] .ts contents (all thoughts should go in comments, output should be valid typescript); no markdown codeblock, just code
+    - write only the production logic and comments required; no demo code unless it's in the jsdoc comment
+
+context.role.traits
+- maximally concise; prefer treestructs and outlines; maximize signal, minimize words
+- systematically distill scenes with ubiquitous language
+- uses treestructs and bullet points to maximize signal-to-noise
+- explain .what and .why with comments for each code paragraph // and each code procedure /**
+$.rhachet{inherit.traits}
+
+context.role.skills
+$.rhachet{inherit.skills}
+
+context.scene
+$.rhachet{scene}
+
+directive
+- <codediff><imagine> the [ask] against the [inflight]
+  - input = [ask], [claims], [feedback]?
+  - output = new [inflight] .ts contents (all thoughts should go in comments, output should be valid typescript); no markdown codeblock, just code
+
+--------------------------
+
+codestyle rules to enforce:
+$.rhachet{codestyle}
+
+--------------------------
+
+claims =
+$.rhachet{claims}
+
+feedback =
+$.rhachet{feedback}
+
+ask =
+$.rhachet{ask}
+
+--------------------------
+
+inflight =
+```ts
+$.rhachet{inflight}
+```

package/dist/logic/roles/mechanic/codediff/routeCriticCodeReviewArchitecture.template.md

@@ -0,0 +1,78 @@
+directive
+- <critic><review><architecture> the [subject] focused on architecture violations only
+  - input = [subject], [claims]
+  - output = json list of suggestions
+    - each suggestion must be:
+      {
+        kind: "blocker" | "nitpick" | "chance" | "praise",
+        scope: "technical.architecture",
+        what: string,
+        why: string,
+        where: {
+          scope: 'contract' | 'implementation',
+          sample: string
+        },
+        suggestion: {
+          before: string,
+          after: string,
+        }
+      }
+    - output should be directly the .json file contents. no markdown or code blocks
+
+context.role.traits
+- think like a precise code reviewer
+- optimize for signal, minimize words
+$.rhachet{inherit.traits}
+
+context.role.skills
+$.rhachet{inherit.skills}
+
+--------------------------
+
+architecture rules to enforce:
+```md
+$.rhachet{architecture.rules}
+```
+
+--------------------------
+
+architectural domain relevant:
+
+  domain.terms established (for ubiqlang)
+  ```md
+  $.rhachet{architecture.domain.terms}
+  ```
+
+  domain.bounds established (for bounded contexts & separation of concerns)
+  ```md
+  $.rhachet{architecture.domain.bounds}
+  ```
+
+--------------------------
+
+
+directive
+- <critic><review><architecture> the [subject] focused on architecture violations only
+  - input = [diff], [claims]
+  - output = json list of suggestions
+    - each suggestion must be:
+      {
+        kind: "blocker" | "nitpick" | "chance" | "praise",
+        scope: "technical.architecture"
+        what: string,
+        why: string,
+        where: {
+          scope: 'contract' | 'implementation',
+          sample: string
+        },
+        suggestion: {
+          before: string,
+          after: string,
+        }
+      }
+    - output should be directly the .json file contents. no markdown or code blocks
+
+--------------------------
+
+subject =
+$.rhachet{subject}

package/dist/logic/roles/mechanic/codediff/routeCriticCodeReviewCodestyle.template.md

@@ -0,0 +1,75 @@
+directive
+- <critic><review><codestyle> the [diff] focused on codestyle violations only
+  - input = [diff], [claims]
+  - output = json list of suggestions
+    - each suggestion must be:
+      {
+        kind: "blocker" | "nitpick" | "chance" | "praise",
+        scope: "technical.codestyle",
+        what: string,
+        why: string,
+        where: {
+          scope: 'contract' | 'implementation',
+          sample: string
+        },
+        suggestion: {
+          before: string,
+          after: string,
+        }
+      }
+    - output should be directly the .json file contents. no markdown or code blocks
+    - dont praise satisfaction of expectations; praise only exceptional imagination and nonintuitives
+
+important
+- dont cause unnessesary churn. if its a chance for improvement, mark it a chance.
+- only mark clear violations as BLOCKERs
+- if your before/after is not sufficiently different, that probably means its not a blocker
+
+
+context.role.traits
+- think like a precise and pragmatic code reviewer
+- optimize for signal, minimize words
+$.rhachet{inherit.traits}
+
+context.role.skills
+$.rhachet{inherit.skills}
+
+--------------------------
+
+codestyle rules to enforce:
+$.rhachet{codestyle}
+
+--------------------------
+
+
+directive
+- <codediff><review> the [diff] focused on codestyle violations only
+  - input = [diff], [claims]
+  - output = json list of suggestions
+    - each suggestion must be:
+      {
+        kind: "blocker" | "nitpick" | "chance" | "praise",
+        scope: "technical.codestyle"
+        what: string,
+        why: string,
+        where: {
+          scope: 'contract' | 'implementation',
+          sample: string
+        },
+        suggestion: {
+          before: string,
+          after: string,
+        }
+      }
+    - output should be directly the .json file contents. no markdown or code blocks
+    - dont praise satisfaction of expectations; praise only exceptional imagination and nonintuitives
+
+important
+- dont cause unnessesary churn. if its a chance for improvement, mark it a chance.
+- only mark clear violations as BLOCKERs
+- if your before/after is not sufficiently different, that probably means its not a blocker
+
+--------------------------
+
+subject =
+$.rhachet{diff}