rhachet-roles-ehmpathy 1.12.1 → 1.13.1

package/dist/logic/roles/mechanic/.briefs/style.names.treestruct.md

@@ -1,48 +0,0 @@
-.tactic = name:treestruct
-
-.what = enforce `[verb][...noun]` for mechanisms and `[...noun][state]?` for resources
-.where:
-  - `verb` = exactly one leading verb (e.g., `gen`, `set`, `get`, `map`)
-  - `...noun` = hierarchy of nouns reflecting the domain treestruct
-  - `state` = optional suffix representing state or outcome (e.g., `Updated`, `Found`, `After`, `Draft`)
-  - this tactic applies to all named functions, types, files, folders, and slugs
-
-.why:
-  - maximizes autocomplete grouping by domain or action
-  - enables tree-sorted navigation in IDEs and file explorers
-  - avoids ambiguity and naming drift across boundaries (design, dev, product)
-
-.how:
-  .rules:
-    - For **mechanisms** (functions, generators, procedures):
-      - use format: `[Verb][...NounHierarchy]`
-      - the verb must come **first**, and be **exactly one** action (e.g., `gen`, `set`, `get`, `map`, `submit`)
-      - e.g., `genStepImagineViaTemplate`, `setCustomerPhone`, `mapJobQuoteToEstimate`
-    - For **resources** (stateful data, outcomes, snapshots):
-      - use format: `[...NounHierarchy][State]?`
-      - the optional `State` suffix:
-        - is used when disambiguating multiple forms (e.g., `InvoiceDraft` vs `InvoiceFinal`)
-        - is typically a past participle or state label (e.g., `Found`, `After`, `Draft`)
-        - may be omitted if the base noun already implies a single clear meaning
-      - e.g., `contentFound`, `customer`, `invoiceDraft`
-
-  .examples:
-    .positive:
-      // mechanisms
-      - `genStepImagineViaTemplate`   // generates a StitchStepImagine from a template
-      - `setCustomerPhone`            // sets the customer's phone number
-      - `mapGitRepoToWorkspace`       // maps a Git repo into a workspace domain
-      - `getInvoiceFinalizedState`    // retrieves the final state of an invoice
-
-      // resources
-      - `contentFound`                // content retrieved from a source
-      - `customer`                    // single canonical term for a user of services
-      - `invoiceDraft`                // invoice in editable state
-      - `invoice`                     // base noun with implicit meaning
-
-    .negative:
-      - `stepImagineGenFromTemplate`  // ⛔ wrong order — verb must come first
-      - `customerSet`                 // ⛔ vague mechanism — better as `setCustomer` or `setCustomerPhone`
-      - `FoundContent`                // ⛔ reversed word order and PascalCase — should be `contentFound`
-      - `submitQuoteJob`              // ⛔ noun hierarchy flipped — should be `submitJobQuote`
-      - `update()`                    // ⛔ unscoped verb — must include noun domain (e.g., `updateInvoice`)

package/dist/logic/roles/mechanic/.briefs/style.names.ubiqlang.md

@@ -1,37 +0,0 @@
-.tactic = name:ubiqlang
-
-.what = enforce a rigorous, domain-driven naming system rooted in ubiquitous language
-.where:
-  - ubiquitous language = the shared, unambiguous vocabulary used by both domain experts and developers
-  - this tactic applies to all names: types, variables, functions, slugs, and folders
-
-.why:
-  - eliminates ambiguity and cognitive friction
-  - ensures that everyone speaks the same language — in code, UI, tests, and docs
-  - prevents synonym drift (e.g., "client" vs "customer") and overload traps (e.g., "update" meaning 3 things)
-
-.how:
-  - eliminate synonyms
-    - choose one canonical word per concept (e.g., always use `customer`, never `client`, `user`, or `account`)
-  - eliminate overloads
-    - each term must refer to one concept only (e.g., avoid using `update` for both "save data" and "fetch latest")
-  - use consistent term stacking across all code (e.g., `customerPhoneUpdate`, not `editPhoneNumber`)
-  - whenever a new term is introduced:
-    - define its interface, expected shape, and role
-    - document its meaning clearly and visibly (ideally in context or hover docs)
-    - ensure its usage is verified across type definitions, business rules, and communication flows
-
-.examples:
-  .positive:
-    - `customer` instead of `client`, `user`, or `buyer`
-    - `jobQuote` as the single term for estimates/proposals
-    - `leadCapture` as the canonical action for inbound lead collection
-    - `customerPhoneUpdate` for updating a phone number
-    - `invoiceDraft` and `invoiceFinal` for two distinct invoice states
-
-  .negative:
-    - `client`, `user`, `account`, `buyer` all referring to the same actor
-    - `editCustomerPhone`, `changePhone`, `updateNumber` used interchangeably
-    - `job` used for both a requested service and a completed one
-    - `update()` overloaded to mean save, patch, sync, or refresh
-    - `quote`, `estimate`, `proposal`, and `bid` all floating without clear hierarchy

package/dist/logic/roles/mechanic/.briefs/style.words.lowercase.md

@@ -1,36 +0,0 @@
-.tactic = words:lowercase
-
-.what = enforce lowercase for all words unless capitalization is required by code or naming convention
-.where:
-  - applies to comments, docstrings, markdown, logs, and prompt copy
-  - only exceptions are code constructs (e.g., class names) and proper nouns (e.g., OpenAI)
-
-.why:
-  - keeps language neutral, minimal, and machine-aligned
-  - prevents inconsistent or performative emphasis via caps
-  - improves scanability and reduces visual noise across surfaces
-
-.how:
-  .rules:
-    - do not capitalize the first word of a sentence
-    - only use capitalization when:
-      - referencing a class, type, or constant (e.g., `StitchStepImagine`, `GitRepo`)
-      - writing a proper noun or brand (e.g., OpenAI, GitHub, AWS)
-    - never capitalize:
-      - generic nouns (`customer`, `invoice`, `step`)
-      - verbs (`set`, `get`, `submit`, `handle`)
-      - system comments or instructions, even at the beginning of a line
-
-  .examples:
-    .positive:
-      - `// returns a new invoice if customer exists`
-      - `// handled in gitrepo.init()`
-      - `// fallback if no customer was found`
-      - `// pass into StitchStepImagine to generate`
-      - `// openai prompt requires flattened string`
-    .negative:
-      - `// Returns a new invoice`       // ⛔ capitalized sentence start
-      - `// This is handled in GitRepo`  // ⛔ capitalized sentence + verb
-      - `// Submit the job for approval` // ⛔ capitalized imperative
-      - `// Customer must exist first`   // ⛔ capitalized domain noun
-      - `// GitHub Repository`           // ⛔ capitalized generic noun

package/dist/logic/roles/mechanic/.briefs/terms/badpractice/script.md

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

package/dist/logic/roles/mechanic/.briefs/terms/plan.exec_vs_apply.md

@@ -1,45 +0,0 @@
-# Execute vs Apply
-
-## ⚙️ Execute
-**Meaning:**
-To **carry out** or **perform** something, especially a plan, command, or program.
-
-**Connotation:**
-Focuses on the **act of doing** — actually running the instructions.
-
-**Examples:**
-- The computer **executes** the program.
-- She **executed** the plan perfectly.
-- The database will **execute** this SQL query.
-
-**Key idea:** "Do it."
-
----
-
-## 🖐️ Apply
-**Meaning:**
-To **put something into use** or **bring it into effect** on a target or situation.
-
-**Connotation:**
-Focuses on **using something that already exists** (a tool, rule, concept, method, etc.) to affect something else.
-
-**Examples:**
-- Please **apply** the paint evenly.
-- We can **apply** this algorithm to the data.
-- He **applied** the brakes.
-
-**Key idea:** "Use it (on something)."
-
----
-
-## 🧠 How They Differ
-
-|            | **Execute**                  | **Apply**                         |
-|------------|------------------------------|----------------------------------|
-| **Focus**  | Performing an action or plan | Using something in a situation   |
-| **Implied object** | A plan, command, task | A method, tool, concept          |
-| **Example** | Execute a script            | Apply a formula                  |
-
-**Memory trick:**
-- **Execute = do**
-- **Apply = use**

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

@@ -1,235 +0,0 @@
-#!/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/declapract.upgrade.sh

@@ -1,50 +0,0 @@
-#!/usr/bin/env bash
-######################################################################
-# .what = upgrade declapract and apply latest best practices
-#
-# .why  = declapract manages development best practices and tooling
-#         configuration across projects, ensuring consistency and
-#         enabling easy upgrades to latest standards.
-#
-#         this skill upgrades declapract packages and reapplies
-#         practices, then validates the build still passes.
-#
-# guarantee:
-#   ✔ verifies declapract.use.yml exists before proceeding
-#   ✔ upgrades to latest declapract packages
-#   ✔ applies practices twice (ensures idempotency)
-#   ✔ reinstalls dependencies after application
-#   ✔ fail-fast on any error
-######################################################################
-
-set -euo pipefail
-
-PROJECT_ROOT="$PWD"
-CONFIG_FILE="$PROJECT_ROOT/declapract.use.yml"
-
-# Verify declapract config exists
-if [[ ! -f "$CONFIG_FILE" ]]; then
-  echo "❌ no declapract.use.yml found in project root"
-  echo "   $CONFIG_FILE"
-  echo "➡️  first configure declapract for this project"
-  exit 1
-fi
-
-echo "📦 upgrading declapract packages..."
-npm install --save-dev declapract@latest declapract-typescript-ehmpathy@latest
-
-echo ""
-echo "✨ applying best practices..."
-npx declapract apply && npx declapract apply
-
-echo ""
-echo "📦 reinstalling dependencies..."
-npm install
-
-echo ""
-echo "✅ declapract upgrade complete!"
-echo ""
-echo "⚠️  next steps:"
-echo "   1. verify build passes: npm run test:types && npm run build"
-echo "   2. review changes for breaking updates"
-echo "   3. test that all still behaves as expected"

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

@@ -1,58 +0,0 @@
-#!/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

@@ -1,51 +0,0 @@
-#!/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

@@ -1,51 +0,0 @@
-#!/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