rhachet-roles-ehmpathy 1.13.6 → 1.13.8

package/dist/logic/roles/mechanic/.skills/declapract.upgrade.sh

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = initialize a .behavior directory for bhuild thoughtroute
+#
+# .why  = standardize the behavior-driven development thoughtroute
+#         by scaffolding a structured directory with:
+#           - wish definition
+#           - vision statement
+#           - acceptance criteria
+#           - research prompts
+#           - distillation prompts
+#           - blueprint prompts
+#           - roadmap prompts
+#           - execution prompts
+#           - feedback template
+#
+# .how  = creates .behavior/v${isodate}.${behaviorname}/ with
+#         all necessary scaffold files for the bhuild thoughtroute
+#
+# usage:
+#   init.bhuild.sh --name <behaviorname> [--dir <directory>]
+#
+# guarantee:
+#   - creates .behavior/ if missing
+#   - creates versioned behavior directory
+#   - findserts all thoughtroute files (creates if missing, skips if exists)
+#   - idempotent: safe to rerun
+#   - fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+# parse arguments
+BEHAVIOR_NAME=""
+TARGET_DIR="$PWD"
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --name)
+      BEHAVIOR_NAME="$2"
+      shift 2
+      ;;
+    --dir)
+      TARGET_DIR="$2"
+      shift 2
+      ;;
+    *)
+      echo "error: unknown argument '$1'"
+      echo "usage: init.bhuild.sh --name <behaviorname> [--dir <directory>]"
+      exit 1
+      ;;
+  esac
+done
+
+# validate required arguments
+if [[ -z "$BEHAVIOR_NAME" ]]; then
+  echo "error: --name is required"
+  echo "usage: init.bhuild.sh --name <behaviorname> [--dir <directory>]"
+  exit 1
+fi
+
+# generate isodate in format YYYY_MM_DD
+ISO_DATE=$(date +%Y_%m_%d)
+
+# trim trailing .behavior from TARGET_DIR if present
+TARGET_DIR="${TARGET_DIR%/.behavior}"
+TARGET_DIR="${TARGET_DIR%.behavior}"
+
+# construct behavior directory path (absolute)
+BEHAVIOR_DIR="$TARGET_DIR/.behavior/v${ISO_DATE}.${BEHAVIOR_NAME}"
+
+# compute relative path from caller's $PWD for file contents
+BEHAVIOR_DIR_REL="$(realpath --relative-to="$PWD" "$TARGET_DIR")/.behavior/v${ISO_DATE}.${BEHAVIOR_NAME}"
+# normalize: remove leading ./ if present
+BEHAVIOR_DIR_REL="${BEHAVIOR_DIR_REL#./}"
+
+# create behavior directory (idempotent)
+mkdir -p "$BEHAVIOR_DIR"
+
+# helper: findsert file (create if missing, skip if exists)
+findsert() {
+  local filepath="$1"
+  if [[ -f "$filepath" ]]; then
+    echo "   [KEEP] $(basename "$filepath")"
+    return 0
+  fi
+  cat > "$filepath"
+  echo "   [CREATE] $(basename "$filepath")"
+}
+
+# findsert 0.wish.md
+findsert "$BEHAVIOR_DIR/0.wish.md" << 'EOF'
+wish =
+
+EOF
+
+# findsert 1.vision.md
+findsert "$BEHAVIOR_DIR/1.vision.md" << 'EOF'
+
+EOF
+
+# findsert 2.criteria.md
+findsert "$BEHAVIOR_DIR/2.criteria.md" << 'EOF'
+# usecase.1 = ...
+given()
+  when()
+    then()
+      sothat()
+    then()
+    then()
+      sothat()
+  when()
+    then()
+
+given()
+  ...
+
+# usecase.2 = ...
+...
+EOF
+
+# findsert 3.1.research.domain._.v1.src
+findsert "$BEHAVIOR_DIR/3.1.research.domain._.v1.src" << EOF
+research the domain available in order to fulfill the wish declared
+in $BEHAVIOR_DIR_REL/0.wish.md
+
+specifically
+- what are the domain objects that are involved with this wish
+  - entities
+  - events
+  - literals
+- what are the domain operations
+  - getOne
+  - getAll
+  - setCreate
+  - setUpdate
+  - setDelete
+  - ...
+
+---
+
+use web search to discover and research
+- cite every claim
+- number each citation
+- clone exact quotes from each citation
+
+focus on these sdk's for reference, if provided
+-
+
+---
+
+emit into $BEHAVIOR_DIR_REL/3.1.research.domain._.v1.i1.md
+EOF
+
+# findsert 3.2.distill.domain._.v1.src
+findsert "$BEHAVIOR_DIR/3.2.distill.domain._.v1.src" << EOF
+distill the declastruct domain.objects and domain.operations that would
+- enable fulfillment of this wish $BEHAVIOR_DIR_REL/0.wish.md
+- given the research declared here $BEHAVIOR_DIR_REL/3.1.research.domain._.v1.i1.md
+
+procedure
+1. declare the usecases and envision the contract that would be used to fulfill the usecases
+2. declare the domain.objects, domain.operations, and access.daos that would fulfill this, via the declastruct pattern in this repo
+
+emit into
+- $BEHAVIOR_DIR_REL/3.2.distill.domain._.v1.i1.md
+EOF
+
+# findsert 3.3.blueprint.v1.src
+findsert "$BEHAVIOR_DIR/3.3.blueprint.v1.src" << EOF
+propose a blueprint for how we can implement the wish described
+- in $BEHAVIOR_DIR_REL/0.wish.md
+
+with the domain distillation declared
+- in $BEHAVIOR_DIR_REL/3.2.distill.domain._.v1.i1.md
+
+follow the patterns already present in this repo
+
+---
+
+reference the below for full context
+- $BEHAVIOR_DIR_REL/0.wish.md
+- $BEHAVIOR_DIR_REL/3.1.research.domain._.v1.i1.md
+- $BEHAVIOR_DIR_REL/3.2.distill.domain._.v1.i1.md
+
+
+---
+
+emit to $BEHAVIOR_DIR_REL/3.3.blueprint.v1.i1.md
+EOF
+
+# findsert 4.1.roadmap.v1.src
+findsert "$BEHAVIOR_DIR/4.1.roadmap.v1.src" << EOF
+declare a roadmap,
+
+- checklist style
+- with ordered dependencies
+- with behavioral acceptance criteria
+- with behavioral acceptance verification at each step
+
+for how to execute the blueprint specified in $BEHAVIOR_DIR_REL/3.3.blueprint.v1.i1.md
+
+---
+
+emit into $BEHAVIOR_DIR_REL/4.1.roadmap.v1.i1.md
+EOF
+
+# findsert 5.1.execution.phase0_to_phaseN.v1.src
+findsert "$BEHAVIOR_DIR/5.1.execution.phase0_to_phaseN.v1.src" << EOF
+bootup your mechanic's role via \`npx rhachet roles boot --repo ehmpathy --role mechanic\`
+
+then, execute
+- phase0 to phaseN
+of roadmap
+- $BEHAVIOR_DIR_REL/4.1.roadmap.v1.i1.md
+
+ref:
+- $BEHAVIOR_DIR_REL/3.3.blueprint.v1.i1.md
+
+---
+
+track your progress
+
+emit todos and check them off into
+- $BEHAVIOR_DIR_REL/5.1.execution.phase0_to_phaseN.v1.i1.md
+EOF
+
+# findsert .ref.[feedback].v1.[given].by_human.md
+findsert "$BEHAVIOR_DIR/.ref.[feedback].v1.[given].by_human.md" << EOF
+emit your response to the feedback into
+- $BEHAVIOR_DIR_REL/.ref.[feedback].v1.[taken].by_robot.md
+
+1. emit your response checklist
+2. exec your response plan
+3. emit your response checkoffs into the checklist
+
+---
+
+first, bootup your mechanics briefs again
+
+npx rhachet roles boot --repo ehmpathy --role mechanic
+
+---
+---
+---
+
+
+# blocker.1
+
+---
+
+# nitpick.2
+
+---
+
+# blocker.3
+EOF
+
+echo ""
+echo "behavior thoughtroute initialized!"
+echo "   $BEHAVIOR_DIR"