rhachet-roles-ehmpathy 1.17.14 → 1.17.16

package/dist/domain.roles/mechanic/briefs/practices/code.prod/evolvable.procedures/rule.require.hook-wrapper-pattern.md

@@ -0,0 +1,109 @@
+### .rule = require-hook-wrapper-pattern
+
+#### .what
+wrap procedures with hooks via composition, not inline decoration
+
+#### .pattern
+```ts
+const _procedureName = (input: {...}, context: {...}) => {
+  // implementation
+};
+
+export const procedureName = withHook(_procedureName);
+```
+
+#### .why
+
+this pattern minimizes code diffs when hooks are added, changed, or removed:
+
+- **add a hook** → 1 line changes (the export line)
+- **remove a hook** → 1 line changes (the export line)
+- **change hook order** → 1 line changes (the export line)
+
+the alternative — inline wrapping at the function declaration — causes the entire function body to shift indentation, which produces noisy diffs that obscure the actual change.
+
+#### .examples
+
+##### ✅ good — wrapper pattern
+
+```ts
+/**
+ * .what = sends an invoice to the customer
+ * .why = triggers billing workflow
+ */
+const _sendInvoice = async (
+  input: { invoice: Invoice },
+  context: { log: LogMethods },
+): Promise<{ sent: boolean }> => {
+  // implementation stays clean and unindented
+  context.log.info('sending invoice', { invoiceId: input.invoice.id });
+  return { sent: true };
+};
+
+export const sendInvoice = withLogTrail(_sendInvoice);
+```
+
+##### ✅ good — multiple hooks composed
+
+```ts
+const _processPayment = async (
+  input: { payment: Payment },
+  context: { log: LogMethods },
+): Promise<{ success: boolean }> => {
+  // implementation
+};
+
+// hooks compose right-to-left: withRetry runs first, then withLogTrail
+export const processPayment = withLogTrail(
+  withRetry(_processPayment, { maxAttempts: 3 }),
+);
+```
+
+##### ⛔ bad — inline decoration
+
+```ts
+// ⛔ adding/removing the wrapper shifts the entire function body
+export const sendInvoice = withLogTrail(async (
+  input: { invoice: Invoice },
+  context: { log: LogMethods },
+): Promise<{ sent: boolean }> => {
+  // every line here will show as "changed" in the diff
+  // when the hook is added or removed
+  context.log.info('sending invoice', { invoiceId: input.invoice.id });
+  return { sent: true };
+});
+```
+
+#### .diff comparison
+
+when adding `withLogTrail` to an existing function:
+
+**wrapper pattern diff (clean):**
+```diff
+- export const sendInvoice = _sendInvoice;
++ export const sendInvoice = withLogTrail(_sendInvoice);
+```
+
+**inline pattern diff (noisy):**
+```diff
+- export const sendInvoice = async (
++ export const sendInvoice = withLogTrail(async (
+    input: { invoice: Invoice },
+    context: { log: LogMethods },
+  ): Promise<{ sent: boolean }> => {
+    context.log.info('sending invoice', { invoiceId: input.invoice.id });
+    return { sent: true };
+- };
++ });
+```
+
+the wrapper pattern produces a 1-line diff; the inline pattern touches every line of the function.
+
+#### .naming
+
+- prefix the unwrapped procedure with `_` (e.g., `_sendInvoice`)
+- export the wrapped version without prefix (e.g., `sendInvoice`)
+- this signals that `_sendInvoice` is internal and should not be imported directly
+
+#### .enforcement
+inline hook decoration = **BLOCKER**

package/dist/domain.roles/mechanic/briefs/practices/work.flow/refactor/rule.prefer.sedreplace-for-renames.md

@@ -30,20 +30,36 @@ the same rename via sedreplace = 2 tool calls (dry-run + execute) = minimal toke
 # dry-run first (default) - see what would change
 npx rhachet run --skill sedreplace --old "oldName" --new "newName"
 
-# filter to specific file types
-npx rhachet run --skill sedreplace --old "oldName" --new "newName" --glob "*.ts"
+# filter to specific file types (recursive)
+npx rhachet run --skill sedreplace --old "oldName" --new "newName" --glob "**/*.ts"
+
+# filter to files in a specific directory
+npx rhachet run --skill sedreplace --old "oldName" --new "newName" --glob "src/**/*.ts"
 
 # apply changes after review of dry-run
 npx rhachet run --skill sedreplace --old "oldName" --new "newName" --execute
 ```
 
+### glob pattern semantics
+
+the `--glob` option uses shell glob semantics:
+
+| pattern | matches |
+|---------|---------|
+| `*.ts` | `.ts` files in root directory only |
+| `**/*.ts` | all `.ts` files recursively |
+| `src/*.ts` | `.ts` files directly in `src/` |
+| `src/**/*.ts` | `.ts` files recursively in `src/` |
+| `*.{ts,tsx}` | `.ts` and `.tsx` files in root |
+| `**/*.{ts,tsx}` | all `.ts` and `.tsx` files recursively |
+
 ## .examples
 
 ### rename a function
 
 ```sh
 # rename getUserById -> findUserByUuid across all .ts files
-npx rhachet run --skill sedreplace --old "getUserById" --new "findUserByUuid" --glob "*.ts" --execute
+npx rhachet run --skill sedreplace --old "getUserById" --new "findUserByUuid" --glob "**/*.ts" --execute
 ```
 
 ### update an import path

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

@@ -81,8 +81,10 @@ if ! git rev-parse --git-dir > /dev/null 2>&1; then
 fi
 
 # get git-tracked files, optionally filtered by glob
+# note: use :(glob) magic pathspec for proper shell-like glob behavior
+# without this, git ls-files uses pathspec matching where * matches /
 if [[ -n "$GLOB_FILTER" ]]; then
-  FILES=$(git ls-files "$GLOB_FILTER")
+  FILES=$(git ls-files ":(glob)$GLOB_FILTER")
 else
   FILES=$(git ls-files)
 fi

package/package.json

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