rhachet-roles-ehmpathy 1.15.14 → 1.15.16

package/dist/domain.roles/mechanic/briefs/practices/code.prod/pitofsuccess.typedefs/rule.forbid.as-cast.md

@@ -0,0 +1,65 @@
+.tactic = types:forbid-as-cast
+
+.what = using `as X` casts is forbidden — it signals a rule.require.shapefit violation
+
+.scope:
+  - applies to all typescript code in the codebase
+  - enforced during code review and lint rules
+
+.why:
+  - `as` casts bypass typescript's type system
+  - they hide legitimate type errors that indicate design flaws
+  - they create runtime hazards when the cast is incorrect
+  - they make refactoring dangerous by silencing compiler warnings
+
+.exception:
+  - allowed only at boundaries with external org code that lacks proper typedefs
+  - must document via inline comment why this hazard is necessary
+  - must include a note about what would need to change to remove the cast
+
+.how:
+  - when tempted to use `as`, ask: "why doesn't this type fit naturally?"
+  - investigate and fix the root cause instead of casting
+  - if the source types are wrong, create proper type definitions
+  - if runtime validation is needed, use proper type guards
+  - if the compiler is wrong about a type, file a typescript issue or use a narrower cast
+
+.enforcement:
+  - `as` casts in prod code without documented exception = BLOCKER
+  - exception comments must explain:
+    - why the external code lacks proper types
+    - what the correct type should be
+    - what would need to change to remove the cast
+
+.examples:
+
+  .positive:
+    ```ts
+    // refactoring to avoid cast
+    const result = processInput(input); // types align naturally
+
+    // using type guard instead of cast
+    if (isValidResponse(response)) {
+      // response is properly narrowed here
+    }
+
+    // documented external boundary (allowed exception)
+    // NOTE: third-party-sdk lacks proper types for this response
+    // TODO: contribute types upstream or create local declaration file
+    const data = response.data as ThirdPartyResponse;
+    ```
+
+  .negative:
+    ```ts
+    // ⛔ undocumented cast
+    const user = data as User;
+
+    // ⛔ cast to silence error
+    const result = badFunction() as ExpectedType;
+
+    // ⛔ any-cast escape hatch
+    const x = (y as any) as SomeType;
+    ```
+
+.links:
+  - see also: `rule.require.shapefit`

package/dist/domain.roles/mechanic/briefs/practices/code.prod/pitofsuccess.typedefs/rule.require.shapefit.md

@@ -0,0 +1,41 @@
+.tactic = types:shapefit
+
+.what = types must be well-defined and naturally fit; mismatches signal legitimate defects to resolve
+
+.scope:
+  - applies to all type definitions, function signatures, and data transformations
+  - enforced at compile time via typescript's type system
+
+.why:
+  - types that don't fit indicate a design flaw or incomplete understanding of the domain
+  - forcing types to fit via casts hides bugs and creates runtime hazards
+  - well-shaped types enable the compiler to catch errors before runtime
+  - creates a pit-of-success where correct code is easier to write than incorrect code
+
+.how:
+  - if a type doesn't fit, investigate the root cause:
+    - is the source data incorrectly shaped?
+    - is the target type overly restrictive?
+    - is there a missing transformation step?
+  - resolve the mismatch by fixing the actual problem, not by casting
+  - use discriminated unions and type guards for legitimate polymorphism
+  - rely on typescript's inference rather than explicit annotations where possible
+
+.enforcement:
+  - type errors are blockers, not warnings to suppress
+  - `as` casts are forbidden except at documented external boundaries (see rule.forbid.as-cast)
+  - `any` types are forbidden except for truly dynamic scenarios with proper runtime validation
+
+.examples:
+
+  .positive:
+    - refactoring a function signature to accept the actual input type
+    - adding a missing property to a domain object
+    - using `satisfies` to check conformance without casting
+    - creating proper type guards for narrowing
+
+  .negative:
+    - `const x = y as SomeType` to silence compiler
+    - `// @ts-ignore` to skip type checking
+    - using `any` to bypass type constraints
+    - loosening types to accommodate bad data

package/dist/domain.roles/mechanic/briefs/{criteria.practices/prefer.emojis.chill_nature.md → practices/lang.tones/rule.prefer.chill-nature-emojis.md}

@@ -20,5 +20,4 @@ e.g.,
 ⛈️ = error
 🔭 = lookup
 ✨ = success
-🌿 = output
 🌊 = outcome

package/dist/domain.roles/mechanic/inits/init.claude.permissions.jsonc

@@ -11,7 +11,9 @@
     "deny": [
       // git write operations - require explicit user request for audit trail
       "Bash(git commit:*)",
-      "Bash(git add:*)",
+      "Bash(git add .)",
+      "Bash(git add -A:*)",
+      "Bash(git add --all:*)",
       "Bash(git stash:*)",
       "Bash(git checkout:*)",
       "Bash(git branch -d:*)",
@@ -24,6 +26,10 @@
       "Bash(git reflog delete:*)",
       "Bash(git config:*)",
 
+      // git mv/rm - use mvsafe.sh and rmsafe.sh instead (repo-constrained)
+      "Bash(git mv:*)",
+      "Bash(git rm:*)",
+
       // "anywrite" commands - CRITICAL SECURITY RISK
       //
       // unlike Claude's native Edit/Write tools which are scoped to the repo,
@@ -141,10 +147,6 @@
       "Bash(mkdir:*)",
       "Bash(pwd)",
 
-      // git mv/rm are safe - constrained to repo, all changes revertable
-      "Bash(git mv:*)",
-      "Bash(git rm:*)",
-
       // git read-only - all have no write variants
       "Bash(git log:*)",
       "Bash(git status:*)",
@@ -162,6 +164,12 @@
       // cpsafe - safe file copy within git repo (source must be git-tracked)
       "Bash(.agent/repo=ehmpathy/role=mechanic/skills/.skills/claude.tools/cpsafe.sh:*)",
 
+      // mvsafe - safe file move within git repo
+      "Bash(.agent/repo=ehmpathy/role=mechanic/skills/.skills/claude.tools/mvsafe.sh:*)",
+
+      // rmsafe - safe file removal within git repo
+      "Bash(.agent/repo=ehmpathy/role=mechanic/skills/.skills/claude.tools/rmsafe.sh:*)",
+
       // npm read operations
       "Bash(npm view:*)",
       "Bash(npm list:*)",
@@ -209,6 +217,9 @@
       "Bash(RESNAP=true THOROUGH=true npm run test:integration:*)",
       "Bash(RESNAP=true THOROUGH=true npm run test:acceptance:*)",
 
+      // test list operation
+      "Bash(npx jest --listTests:*)",
+
       // fix operations
       "Bash(npm run fix:*)",
       "Bash(npm run fix:format:*)",

package/dist/domain.roles/mechanic/skills/claude.tools/mvsafe.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = safe file move within git repo
+#
+# .why  = enables file moving without:
+#         - touching files outside the repo
+#         - accidental path traversal attacks
+#
+#         this is a controlled alternative to raw mv, which is
+#         denied in permissions due to security risks.
+#
+# usage:
+#   mvsafe.sh --src "path/to/source" --dest "path/to/dest"
+#
+# guarantee:
+#   - source must be within repo
+#   - dest must be within repo
+#   - creates parent directories if needed
+#   - fail-fast on errors
+######################################################################
+set -euo pipefail
+
+# parse named arguments
+SRC=""
+DEST=""
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --src)
+      SRC="$2"
+      shift 2
+      ;;
+    --dest)
+      DEST="$2"
+      shift 2
+      ;;
+    *)
+      echo "unknown argument: $1"
+      echo "usage: mvsafe.sh --src 'source' --dest 'destination'"
+      exit 1
+      ;;
+  esac
+done
+
+# validate required args
+if [[ -z "$SRC" ]]; then
+  echo "error: --src is required"
+  exit 1
+fi
+
+if [[ -z "$DEST" ]]; then
+  echo "error: --dest is required"
+  exit 1
+fi
+
+# ensure we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "error: not in a git repository"
+  exit 1
+fi
+
+# get repo root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+# resolve absolute paths
+SRC_ABS=$(realpath -m "$SRC")
+DEST_ABS=$(realpath -m "$DEST")
+
+# validate source is within repo
+if [[ "$SRC_ABS" != "$REPO_ROOT"* ]]; then
+  echo "error: source must be within the git repository"
+  echo "  repo root: $REPO_ROOT"
+  echo "  source:    $SRC_ABS"
+  exit 1
+fi
+
+# validate dest is within repo
+if [[ "$DEST_ABS" != "$REPO_ROOT"* ]]; then
+  echo "error: destination must be within the git repository"
+  echo "  repo root: $REPO_ROOT"
+  echo "  dest:      $DEST_ABS"
+  exit 1
+fi
+
+# validate source exists
+if [[ ! -e "$SRC_ABS" ]]; then
+  echo "error: source does not exist: $SRC"
+  exit 1
+fi
+
+# create parent directories if needed
+DEST_DIR=$(dirname "$DEST_ABS")
+if [[ ! -d "$DEST_DIR" ]]; then
+  echo "creating directory: $DEST_DIR"
+  mkdir -p "$DEST_DIR"
+fi
+
+# perform the move
+mv "$SRC_ABS" "$DEST_ABS"
+
+SRC_REL="${SRC_ABS#$REPO_ROOT/}"
+DEST_REL="${DEST_ABS#$REPO_ROOT/}"
+echo "moved: $SRC_REL -> $DEST_REL"

package/dist/domain.roles/mechanic/skills/claude.tools/rmsafe.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = safe file removal within git repo
+#
+# .why  = enables file deletion without:
+#         - touching files outside the repo
+#         - accidental path traversal attacks
+#
+#         this is a controlled alternative to raw rm, which is
+#         denied in permissions due to security risks.
+#
+# usage:
+#   rmsafe.sh --path "path/to/file"
+#   rmsafe.sh --path "path/to/dir" --recursive
+#
+# guarantee:
+#   - path must be within repo
+#   - requires --recursive for directories
+#   - fail-fast on errors
+######################################################################
+set -euo pipefail
+
+# parse named arguments
+TARGET=""
+RECURSIVE=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --path)
+      TARGET="$2"
+      shift 2
+      ;;
+    --recursive|-r)
+      RECURSIVE=true
+      shift
+      ;;
+    *)
+      echo "unknown argument: $1"
+      echo "usage: rmsafe.sh --path 'target' [--recursive]"
+      exit 1
+      ;;
+  esac
+done
+
+# validate required args
+if [[ -z "$TARGET" ]]; then
+  echo "error: --path is required"
+  exit 1
+fi
+
+# ensure we're in a git repo
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+  echo "error: not in a git repository"
+  exit 1
+fi
+
+# get repo root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+# resolve absolute path
+TARGET_ABS=$(realpath -m "$TARGET")
+
+# validate target is within repo
+if [[ "$TARGET_ABS" != "$REPO_ROOT"* ]]; then
+  echo "error: path must be within the git repository"
+  echo "  repo root: $REPO_ROOT"
+  echo "  path:      $TARGET_ABS"
+  exit 1
+fi
+
+# prevent deleting repo root itself
+if [[ "$TARGET_ABS" == "$REPO_ROOT" ]]; then
+  echo "error: cannot delete the repository root"
+  exit 1
+fi
+
+# validate target exists
+if [[ ! -e "$TARGET_ABS" ]]; then
+  echo "error: path does not exist: $TARGET"
+  exit 1
+fi
+
+# check if directory and require --recursive
+if [[ -d "$TARGET_ABS" ]] && [[ "$RECURSIVE" != true ]]; then
+  echo "error: target is a directory, use --recursive to delete"
+  exit 1
+fi
+
+# perform the removal
+if [[ "$RECURSIVE" == true ]]; then
+  rm -rf "$TARGET_ABS"
+else
+  rm "$TARGET_ABS"
+fi
+
+TARGET_REL="${TARGET_ABS#$REPO_ROOT/}"
+echo "removed: $TARGET_REL"

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.15.14",
+  "version": "1.15.16",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [

package/dist/domain.roles/mechanic/briefs/architecture/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 noun-verb stacking that mirrors domain intent (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