rhachet-roles-ehmpathy 1.9.1 → 1.11.0

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/git.worktree.test.sh

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