rhachet-roles-bhuild 0.1.3 → 0.4.0

package/dist/domain.roles/behaver/briefs/practices/behavior.roadmap/rule.prefer.dependency-order.md

@@ -0,0 +1,59 @@
+.rule = prefer.dependency-order
+
+.what = roadmap phases should be ordered by dependency
+
+.why = dependency order enables correct execution sequence and parallel work identification; prerequisites must be built before dependents
+
+.how = verify that phase prerequisites are listed before dependents; check for circular dependencies which are blockers
+
+.examples:
+  .positive:
+    - |
+      ## dependencies
+
+      ```
+      phase.0 (scaffolding)
+         ↓
+      phase.1 (rule briefs)
+         ↓
+      phase.2 (composite skill)
+         ↓
+      phase.3 (symlinks)
+         ↓
+      phase.4 (validation)
+      ```
+
+      ## phase.0 = scaffolding
+
+      ### dependencies
+      - none
+
+      ## phase.1 = rule briefs
+
+      ### dependencies
+      - [x] phase.0 complete (scaffolding exists)
+  .negative:
+    - |
+      ## phase.1 = validation
+
+      run validation to check everything works.
+
+      ## phase.2 = implementation
+
+      implement the features to validate.
+
+      (validation before implementation - wrong order)
+    - |
+      ## phase.1 = skill
+
+      ### dependencies
+      - phase.2 complete
+
+      ## phase.2 = tests
+
+      ### dependencies
+      - phase.1 complete
+
+      (circular dependency)
+
+.severity = BLOCKER

package/dist/domain.roles/behaver/briefs/practices/behavior.wish/rule.prefer.bounded-scope.md

@@ -0,0 +1,29 @@
+.rule = prefer.bounded-scope
+
+.what = wishes should define boundaries of what is in scope and out of scope
+
+.why = unbounded scope leads to scope creep and unclear completion criteria; explicit boundaries enable focused implementation
+
+.how = check for explicit scope boundaries or constraints; verify the wish does not imply unlimited or vague scope
+
+.examples:
+  .positive:
+    - |
+      # wish
+
+      wish = create rule briefs for behavior artifact review
+
+      ## scope
+      - in: wish, criteria, blueprint, roadmap artifacts
+      - out: code review, test review, documentation review
+  .negative:
+    - |
+      # wish
+
+      wish = review all project artifacts comprehensively
+    - |
+      # wish
+
+      wish = make everything better
+
+.severity = NITPICK

package/dist/domain.roles/behaver/briefs/practices/behavior.wish/rule.prefer.clear-desires.md

@@ -0,0 +1,31 @@
+.rule = prefer.clear-desires
+
+.what = wishes must clearly state what is desired
+
+.why = ambiguous wishes lead to misaligned implementations; clear desires enable accurate criteria, blueprints, and roadmaps
+
+.how = check for explicit "wish =" statement with concrete, actionable desires; verify desires are specific enough to derive testable criteria
+
+.examples:
+  .positive:
+    - |
+      # wish
+
+      wish = create a skill that reviews behavior artifacts against best practice rules
+
+      ## desires
+      - review wish documents for clarity and scope
+      - review criteria documents for bdd format compliance
+      - review blueprints for test coverage specification
+      - review roadmaps for dependency order
+  .negative:
+    - |
+      # wish
+
+      make the system better at reviewing things
+    - |
+      # wish
+
+      wish = improve quality
+
+.severity = BLOCKER

package/dist/domain.roles/behaver/inits/claude.hooks/sessionstart.boot-behavior.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = inject bound behavior context on session start
+#
+# .why  = agent starts with full awareness of current behavior
+#
+# .note = SessionStart hooks run on both session start AND compaction
+#         this means behavior context is re-injected after context
+#         is summarized, keeping the agent aligned.
+#
+# guarantee:
+#   ✔ exits 0 silently if branch not bound (unbound = normal work)
+#   ✔ exits 0 with warning if multiple bindings (don't block session)
+#   ✔ never blocks session start (exit 0 always)
+######################################################################
+
+# note: no set -e because we must exit 0 always
+set -uo pipefail
+
+# resolve script location and repo root
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../../../.." && pwd)"
+
+# ────────────────────────────────────────────────────────────────────
+# helpers
+# ────────────────────────────────────────────────────────────────────
+
+get_bound_behavior() {
+  npx tsx "$REPO_ROOT/src/domain.operations/behavior/bind/getBoundBehaviorByBranch.cli.ts" "$1" 2>/dev/null || echo '{"behaviorDir":null,"bindings":[]}'
+}
+
+get_latest_blueprint() {
+  npx tsx "$REPO_ROOT/src/domain.operations/behavior/bind/getLatestBlueprintByBehavior.cli.ts" "$1" 2>/dev/null || echo ""
+}
+
+# ────────────────────────────────────────────────────────────────────
+# main
+# ────────────────────────────────────────────────────────────────────
+
+# get current branch
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+if [[ -z "$CURRENT_BRANCH" ]]; then
+  exit 0  # not in a git repo, silently exit
+fi
+
+# check if bound
+BINDING_RESULT=$(get_bound_behavior "$CURRENT_BRANCH")
+BEHAVIOR_DIR=$(echo "$BINDING_RESULT" | jq -r '.behaviorDir // empty')
+BINDINGS_COUNT=$(echo "$BINDING_RESULT" | jq -r '.bindings | length')
+
+# if not bound, exit silently
+if [[ -z "$BEHAVIOR_DIR" || "$BEHAVIOR_DIR" == "null" ]]; then
+  # check for multiple bindings (conflict)
+  if [[ "$BINDINGS_COUNT" -gt 1 ]]; then
+    echo "⚠️  warning: branch '$CURRENT_BRANCH' has conflicting bindings:" >&2
+    echo "$BINDING_RESULT" | jq -r '.bindings[]' | while read -r binding; do
+      echo "  - $(basename "$binding")" >&2
+    done
+    echo "use 'bind.behavior.sh --del' to unbind and 'bind.behavior.sh --set' to rebind" >&2
+  fi
+  exit 0
+fi
+
+# extract behavior name from path
+BEHAVIOR_NAME=$(basename "$BEHAVIOR_DIR")
+
+# ────────────────────────────────────────────────────────────────────
+# output behavior context
+# ────────────────────────────────────────────────────────────────────
+
+echo "=================================================="
+echo "BOUND BEHAVIOR: $BEHAVIOR_NAME"
+echo "=================================================="
+echo ""
+
+# helper to output a behavior file
+output_behavior_file() {
+  local tag="$1"
+  local filepath="$2"
+  local is_required="$3"
+
+  if [[ -f "$filepath" ]]; then
+    local relpath
+    relpath=$(realpath --relative-to="$PWD" "$filepath" 2>/dev/null || echo "$filepath")
+    echo "<behavior-$tag path=\"$relpath\">"
+    cat "$filepath"
+    echo "</behavior-$tag>"
+    echo ""
+  elif [[ "$is_required" == "true" ]]; then
+    echo "⚠️  missing required file: $filepath" >&2
+  fi
+}
+
+# output wish (required)
+output_behavior_file "wish" "$BEHAVIOR_DIR/0.wish.md" "true"
+
+# output vision (optional)
+output_behavior_file "vision" "$BEHAVIOR_DIR/1.vision.md" "false"
+
+# output criteria (optional)
+output_behavior_file "criteria" "$BEHAVIOR_DIR/2.criteria.md" "false"
+
+# output latest blueprint (optional)
+LATEST_BLUEPRINT=$(get_latest_blueprint "$BEHAVIOR_DIR")
+if [[ -n "$LATEST_BLUEPRINT" && -f "$LATEST_BLUEPRINT" ]]; then
+  output_behavior_file "blueprint" "$LATEST_BLUEPRINT" "false"
+fi
+
+echo "=================================================="

package/dist/domain.roles/behaver/inits/init.claude.hooks.findsert.sh

@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = generic findsert utility for Claude hooks
+#
+# .why  = centralizes the "find-or-insert" logic for binding hooks
+#         to .claude/settings.local.json, avoiding duplication across
+#         individual hook initializers.
+#
+# .how  = takes hook configuration as arguments and uses jq to merge
+#         the hook into the settings file, creating structure if absent.
+#
+# usage:
+#   init.claude.hooks.findsert.sh \
+#     --hook-type SessionStart|PreToolUse \
+#     --matcher "*"|"Bash"|... \
+#     --command "command to run" \
+#     --name "hookname" \
+#     [--timeout 5] \
+#     [--position append|prepend]
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (permissions, other hooks)
+#   ✔ idempotent: no-op if hook already present (at correct position)
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+# fail loud: print what failed
+trap 'echo "❌ init.claude.hooks.findsert.sh failed at line $LINENO" >&2' ERR
+
+# Defaults
+HOOK_TYPE=""
+MATCHER=""
+HOOK_COMMAND=""
+HOOK_NAME=""
+TIMEOUT=5
+POSITION="append"
+AUTHOR="repo=bhuild/role=behaver"
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --hook-type)
+      HOOK_TYPE="$2"
+      shift 2
+      ;;
+    --matcher)
+      MATCHER="$2"
+      shift 2
+      ;;
+    --command)
+      HOOK_COMMAND="$2"
+      shift 2
+      ;;
+    --name)
+      HOOK_NAME="$2"
+      shift 2
+      ;;
+    --timeout)
+      TIMEOUT="$2"
+      shift 2
+      ;;
+    --position)
+      POSITION="$2"
+      shift 2
+      ;;
+    --author)
+      AUTHOR="$2"
+      shift 2
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required arguments
+if [[ -z "$HOOK_TYPE" || -z "$MATCHER" || -z "$HOOK_COMMAND" || -z "$HOOK_NAME" ]]; then
+  echo "Usage: $0 --hook-type TYPE --matcher MATCHER --command CMD --name NAME [--timeout SECS] [--position append|prepend] [--author AUTHOR]" >&2
+  exit 1
+fi
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+
+# 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
+
+# Build the hook configuration JSON
+HOOK_CONFIG=$(jq -n \
+  --arg hookType "$HOOK_TYPE" \
+  --arg matcher "$MATCHER" \
+  --arg command "$HOOK_COMMAND" \
+  --argjson timeout "$TIMEOUT" \
+  --arg author "$AUTHOR" \
+  '{
+    hooks: {
+      ($hookType): [
+        {
+          matcher: $matcher,
+          hooks: [
+            {
+              type: "command",
+              command: $command,
+              timeout: $timeout,
+              author: $author
+            }
+          ]
+        }
+      ]
+    }
+  }'
+)
+
+# Generate jq script based on position (append vs prepend)
+if [[ "$POSITION" == "prepend" ]]; then
+  # Prepend: ensure hook is first in the array
+  JQ_SCRIPT=$(cat <<'JQEOF'
+    def hookType: $hookType;
+    def matcher: $matcher;
+    def targetCmd: $hook.hooks[hookType][0].hooks[0].command;
+
+    # Check if hook is already first in the matcher
+    def hookIsFirst:
+      (.hooks[hookType] // [])
+      | map(select(.matcher == matcher) | .hooks // [])
+      | flatten
+      | first
+      | .command == targetCmd;
+
+    # If hook is already first, return unchanged
+    if hookIsFirst then
+      .
+    else
+      # Ensure .hooks exists
+      .hooks //= {} |
+
+      # Ensure .hooks[hookType] exists
+      .hooks[hookType] //= [] |
+
+      # Check if our matcher already exists
+      if (.hooks[hookType] | map(.matcher) | index(matcher)) then
+        # Matcher exists - remove our hook if present, then prepend it
+        .hooks[hookType] |= map(
+          if .matcher == matcher then
+            .hooks = $hook.hooks[hookType][0].hooks + (.hooks | map(select(.command != targetCmd)))
+          else
+            .
+          end
+        )
+      else
+        # Matcher does not exist, add the entire entry
+        .hooks[hookType] += $hook.hooks[hookType]
+      end
+    end
+JQEOF
+  )
+else
+  # Append: add hook to end of array (default)
+  JQ_SCRIPT=$(cat <<'JQEOF'
+    def hookType: $hookType;
+    def matcher: $matcher;
+    def targetCmd: $hook.hooks[hookType][0].hooks[0].command;
+
+    # Check if hook already exists anywhere
+    def hookExists:
+      (.hooks[hookType] // [])
+      | map(select(.matcher == matcher) | .hooks // [])
+      | flatten
+      | map(.command)
+      | any(. == targetCmd);
+
+    # If hook already exists, return unchanged
+    if hookExists then
+      .
+    else
+      # Ensure .hooks exists
+      .hooks //= {} |
+
+      # Ensure .hooks[hookType] exists
+      .hooks[hookType] //= [] |
+
+      # Check if our matcher already exists
+      if (.hooks[hookType] | map(.matcher) | index(matcher)) then
+        # Matcher exists, add our hook to its hooks array
+        .hooks[hookType] |= map(
+          if .matcher == matcher then
+            .hooks += $hook.hooks[hookType][0].hooks
+          else
+            .
+          end
+        )
+      else
+        # Matcher does not exist, add the entire entry
+        .hooks[hookType] += $hook.hooks[hookType]
+      end
+    end
+JQEOF
+  )
+fi
+
+# Run jq with the appropriate script
+jq --argjson hook "$HOOK_CONFIG" \
+   --arg hookType "$HOOK_TYPE" \
+   --arg matcher "$MATCHER" \
+   "$JQ_SCRIPT" "$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 "👌 $HOOK_NAME hook already bound"
+  exit 0
+fi
+
+# Atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔗 $HOOK_NAME hook bound successfully!"

package/dist/domain.roles/behaver/inits/init.claude.hooks.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind behaver hooks to Claude settings
+#
+# .why  = the behaver role uses a SessionStart hook to inject
+#         bound behavior context into agent sessions on start
+#         and compaction events.
+#
+# .how  = calls findsert for the boot-behavior hook
+#
+# guarantee:
+#   ✔ idempotent: safe to rerun
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+# fail loud: print what failed
+trap 'echo "❌ init.claude.hooks.sh failed at line $LINENO" >&2' ERR
+
+INITS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+FINDSERT="$INITS_DIR/init.claude.hooks.findsert.sh"
+
+# path to hook scripts (relative to this script)
+HOOKS_DIR="$INITS_DIR/claude.hooks"
+
+# SessionStart hook: boot behavior context
+# note: SessionStart hooks run on both session start AND compaction
+"$FINDSERT" \
+  --hook-type SessionStart \
+  --matcher "*" \
+  --command "$HOOKS_DIR/sessionstart.boot-behavior.sh" \
+  --name "sessionstart.boot-behavior" \
+  --timeout 10