rhachet-roles-ehmpathy 1.9.1 → 1.10.0

package/dist/logic/roles/coach/.briefs/claude.context-caching.md

@@ -0,0 +1,76 @@
+# 🧠 .brief: Claude Context Caching
+
+## .what
+Claude's context caching mechanism that reduces token costs by caching prompt prefixes
+
+## .how.it.works
+
+### cache key = exact prefix match
+- Claude caches content based on the **exact sequence of tokens from the start** of the conversation
+- a cache hit requires the **exact same prefix** to be present
+- cache is valid for ~5 minutes of inactivity
+
+### prefix-based matching
+```
+Turn 1: [system prompt] + [briefs: 30k tokens] → writes to cache
+Turn 2: [system prompt] + [briefs: 30k tokens] + [user msg] + [response] → cache hit ✅
+Turn 3: [system prompt] + [briefs: 30k tokens] + [history] + [new msg] → cache hit ✅
+```
+
+### when cache hits occur
+
+✅ **cache hit (free reads)** when:
+- the content appears at the **exact same position** in the context
+- everything before it is **identical** to the cached version
+- less than ~5 minutes of inactivity
+
+❌ **cache miss (full tokens charged)** when:
+- anything changed in the context **before** the cached content (even a single token)
+- the content moved to a different position in the conversation
+- more than ~5 minutes passed with no activity
+- new conversation started (different session)
+
+## .implications.for.briefs
+
+### sessionstart hooks
+when loading briefs via sessionstart hooks:
+
+1. **first boot**: full tokens cached (e.g., 30k tokens written to cache)
+2. **within same session**: cached if prefix matches (free reads)
+3. **new session**: full tokens charged again (new conversation = different prefix)
+
+### optimization strategies
+to maximize cache hits:
+
+1. **load briefs once per session** (sessionstart hook pattern)
+2. **keep them at consistent position** (ideally at the start)
+3. **avoid regenerating them** if content hasn't changed
+4. **batch related work** in same session to reuse cache
+
+## .key.insight
+
+the cache **does not move tokens around** or do LRU eviction - it's purely prefix-based matching
+
+this means:
+- you can't "refresh" cached content by using it again
+- cached content must appear in the exact same position to hit
+- any prefix changes invalidate the entire cache for that position
+
+## .cost.model
+
+### cache writes
+- **first use**: 25% of normal input token cost
+- **cache write**: happens on first occurrence of new content
+
+### cache reads
+- **cache hit**: 10% of normal input token cost
+- **cache miss**: 100% of normal input token cost (no cache benefit)
+
+### example: 30k token briefs
+- **first load**: ~7.5k tokens charged (25% write cost)
+- **subsequent hits**: ~3k tokens charged (10% read cost)
+- **cache miss**: 30k tokens charged (100% cost)
+
+## .sources
+- based on Anthropic's context caching documentation
+- observed behavior in production usage

package/dist/logic/roles/mechanic/.briefs/lessons/code.prod.typescript.types/bivariance_vs_contravariance.[lesson].md

@@ -0,0 +1,95 @@
+# method syntax for bivariance
+
+## .what
+
+typescript treats arrow function properties and method syntax differently for variance:
+
+- **arrow function syntax** = contravariant on parameters
+- **method syntax** = bivariant on parameters
+
+```ts
+// arrow function syntax (contravariant)
+interface Dao {
+  get: (input: SomeInput) => Promise<Result>;
+}
+
+// method syntax (bivariant)
+interface Dao {
+  get(input: SomeInput): Promise<Result>;
+}
+```
+
+---
+
+## .why this matters
+
+when checking if a specific type is assignable to a generic type (e.g., `Dao<Specific>` to `Dao<any>`), contravariance on function parameters can cause unexpected failures.
+
+### example: the problem
+
+```ts
+interface DeclastructDao<TResourceClass> {
+  get: {
+    // arrow syntax = contravariant
+    byPrimary?: (input: RefByPrimary<TResourceClass>) => Promise<Resource | null>;
+  };
+}
+
+// specific dao where RefByPrimary resolves to {uuid: string}
+const specificDao: DeclastructDao<typeof MyResource> = { ... };
+
+// generic dao shape where RefByPrimary<any> resolves to {}
+type GenericDao = DeclastructDao<any>;
+
+// ❌ fails: {uuid: string} is not assignable to {}
+const generic: GenericDao = specificDao;
+```
+
+the contravariant check asks: "can a function accepting `{uuid: string}` be used where a function accepting `{}` is expected?"
+
+answer: **no** — a function requiring `uuid` can't safely accept an empty object.
+
+### example: the fix
+
+```ts
+interface DeclastructDao<TResourceClass> {
+  get: {
+    // method syntax = bivariant
+    byPrimary?(input: RefByPrimary<TResourceClass>): Promise<Resource | null>;
+  };
+}
+
+// ✅ works: bivariance allows assignment in either direction
+const generic: GenericDao = specificDao;
+```
+
+---
+
+## .when to use
+
+use method syntax when:
+
+1. you need interfaces with generic type parameters to be assignable to their `<any>` variants
+2. you're defining dao/repository patterns where specific implementations must fit into generic collections
+3. the interface will be used in `Record<string, Interface<any>>` shapes
+
+---
+
+## .tradeoff
+
+bivariance is slightly less type-safe at the boundary — typescript won't catch certain mismatches. however, this is often the correct behavior for:
+
+- generic collections of typed implementations
+- plugin/provider patterns
+- dao registries
+
+the types remain fully enforced when actually calling the methods on a specific instance.
+
+---
+
+## .reference
+
+this is intentional typescript behavior. method syntax preserves the historical bivariant behavior from before `--strictFunctionTypes` was introduced, because it matches how most developers expect object subtyping to work.
+
+- [typescript handbook: type compatibility](https://www.typescriptlang.org/docs/handbook/type-compatibility.html)
+- [typescript pr: strict function types](https://github.com/microsoft/TypeScript/pull/18654)

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.errors.failfast/bad-practices/forbid.failhide.md

@@ -0,0 +1,19 @@
+failhide = any scenario where you hide real errors
+
+the most common patterns is
+
+try/catch
+
+---
+
+the only cases where a trycatch is allowed is if the catch has an allowlist of the errors it catches and CAREFULLY handles those, while throwing the rest up
+
+otherwise, its a failhide hazard, where real errors will be silently hidden, leading to defects or hours of pointless debugging
+
+never failhide
+
+always failfast
+
+---
+
+this is a mega blocker

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.errors.failfast/best-practice/prefer.HelpfulError.wrap.md

@@ -0,0 +1,54 @@
+in some cases, its useful
+
+to try/catch
+
+to make an error more observable
+
+---
+
+e.g.,
+
+```ts
+try {
+  // do something that throws
+  await doSomething({ userUuid })
+} catch (error) {
+  if (!(error instanceof Error)) throw error;
+  throw Error(`doSomething.error: ${error.message}, for userUuid=${userUuid}`, { cause });
+}
+```
+
+in these cases, its best to use HelpfulError.wrap instead
+- it automatically instantiates a HelpfulError (or more specific variant if specified) for maximum observability
+
+e.g.,
+
+```ts
+import { HelpfulError } from 'helpful-errors';
+
+await HelpfulError.wrap(
+  async () => await doSomething({ userUuid }),
+  {
+    message: 'doSomething.error',
+    metadata: {
+      userUuid,
+    }
+  }
+)()
+```
+
+or
+
+```ts
+import { UnexpectedCodePathError } from 'helpful-errors';
+
+await UnexpectedCodePathError.wrap(
+  async () => await doSomething({ userUuid }),
+  {
+    message: 'doSomething.error',
+    metadata: {
+      userUuid,
+    }
+  }
+)()
+```

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.narrative/bad-practices/forbid.else.md

@@ -0,0 +1,54 @@
+else is a code REAK
+
+its not even a smell
+
+its such a bad smell that it reaks
+
+---
+
+else's can _always_ be better rewriten as an IFFE+EarlyReturn
+
+---
+
+see the narrative flow breifs for more context on the desired goal
+
+
+-------
+
+e.g.,
+
+> no if else; only early returns; else is a code REAK
+
+● You're right - the if/else violates the flow:narrative tactic. Let me
+  refactor to use early returns only:
+
+● Update(src/domain.operations/vpcTunnel/setVpcTunnel.ts)
+  ⎿  Updated src/domain.operations/vpcTunnel/setVpcTunnel.ts with 5
+     additions and 3 removals
+       81      if (portInUse) {
+       82        const cacheFilePresent = await isFilePresent({ path:
+            cachePath });
+       83
+       84 +      // port used by unknown process; kill it to reclaim
+       85 +      if (!cacheFilePresent) {
+       86 +        killProcessOnPort({ port: input.from.port });
+       87 +      }
+       88 +
+       89        // check if existing tunnel is ours and healthy
+       90        if (cacheFilePresent) {
+       91          const cacheContent = await fs.readFile(cachePath,
+            'utf-8');
+     ...
+       100          // cleanup stale tunnel
+       101          if (isProcessAlive({ pid: cache.pid }))
+             process.kill(cache.pid, 'SIGTERM');
+       102          await fs.rm(cachePath, { force: true });
+       103 -      } else {
+       104 -        // port used by another process; kill it to reclaim
+       105 -        killProcessOnPort({ port: input.from.port });
+       103        }
+       104      }
+       105
+
+● Removed the else block - now both conditions are independent if statements
+   with no branching maze.

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.narrative/best-practice/early-returns.named-checks.[demo].md

@@ -0,0 +1,181 @@
+
+● The check now walks up the prototype chain starting from error.constructor, checking if any class in the
+  inheritance hierarchy is named 'BadRequestError'. This handles cases where a custom error class extends
+  BadRequestError (or extends something that extends it, etc.).
+
+> lets actually create a new constant called "isExtensionOfBadRequestError"
+  ⎿  Found 3 new diagnostic issues in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 4 additions and 2 removals
+        8     */
+        9    export const decideIsBadRequestError = ({ error }: { error: Error }) => {
+       10      const isInstanceOfBadRequestError = error instanceof BadRequestError;
+       11 -    const isNamedAfterBadRequestError = (() => {
+       12 -      let proto = error.constructor;
+       11 +    const isNamedAfterBadRequestError =
+       12 +      error.constructor.name === 'BadRequestError';
+       13 +    const isExtensionOfBadRequestError = (() => {
+       14 +      let proto = Object.getPrototypeOf(error.constructor);
+       15        while (proto) {
+       16          if (proto.name === 'BadRequestError') return true;
+       17          proto = Object.getPrototypeOf(proto);
+
+● Now I need to add the new constant to the return statement:
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 1 addition and 1 removal
+       18        }
+       19        return false;
+       20      })();
+       21 -    return isInstanceOfBadRequestError || isNamedAfterBadRequestError;
+       21 +    return isInstanceOfBadRequestError || isNamedAfterBadRequestError
+          +   || isExtensionOfBadRequestError;
+       22    };
+       23
+       24    /**
+
+● Done. Now decideIsBadRequestError has three separate checks:
+
+  1. isInstanceOfBadRequestError - uses instanceof check
+  2. isNamedAfterBadRequestError - checks if the error's constructor is named 'BadRequestError'
+  3. isExtensionOfBadRequestError - walks up the prototype chain to check if any parent class is named
+  'BadRequestError'
+
+> add a header comment for each constant
+  ⎿  Found 1 new diagnostic issue in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 11 additions and 1 removal
+        7     * .what = procedure for deciding whether an error is a bad request error
+        8     */
+        9    export const decideIsBadRequestError = ({ error }: { error: Error }) => {
+       10 +    // check if the error is an instance of BadRequestError
+       11      const isInstanceOfBadRequestError = error instanceof BadRequestError;
+       12 +
+       13 +    // check if the error's constructor is named 'BadRequestError'
+       14      const isNamedAfterBadRequestError =
+       15        error.constructor.name === 'BadRequestError';
+       16 +
+       17 +    // check if any parent class in the prototype chain is named 'BadRequestError'
+       18      const isExtensionOfBadRequestError = (() => {
+       19        let proto = Object.getPrototypeOf(error.constructor);
+       20        while (proto) {
+     ...
+       18        }
+       19        return false;
+       20      })();
+       21 -    return isInstanceOfBadRequestError || isNamedAfterBadRequestError ||
+          - isExtensionOfBadRequestError;
+       21 +
+       22 +    return (
+       23 +      isInstanceOfBadRequestError ||
+       24 +      isNamedAfterBadRequestError ||
+       25 +      isExtensionOfBadRequestError
+       26 +    );
+       27    };
+       28
+       29    /**
+
+● Done. Added header comments for each constant and also fixed the formatting on the return statement to
+  satisfy the eslint rule.
+
+> use early returns after each check, rather than needoing to evalaute all three
+  ⎿  Found 3 new diagnostic issues in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 8 additions and 16 removals
+        8     */
+        9    export const decideIsBadRequestError = ({ error }: { error: Error }) => {
+       10      // check if the error is an instance of BadRequestError
+       11 -    const isInstanceOfBadRequestError = error instanceof BadRequestError;
+       11 +    if (error instanceof BadRequestError) return true;
+       12
+       13      // check if the error's constructor is named 'BadRequestError'
+       14 -    const isNamedAfterBadRequestError =
+       15 -      error.constructor.name === 'BadRequestError';
+       14 +    if (error.constructor.name === 'BadRequestError') return true;
+       15
+       16      // check if any parent class in the prototype chain is named 'BadRequestError'
+       17 -    const isExtensionOfBadRequestError = (() => {
+       18 -      let proto = Object.getPrototypeOf(error.constructor);
+       19 -      while (proto) {
+       20 -        if (proto.name === 'BadRequestError') return true;
+       21 -        proto = Object.getPrototypeOf(proto);
+       22 -      }
+       23 -      return false;
+       24 -    })();
+       17 +    let proto = Object.getPrototypeOf(error.constructor);
+       18 +    while (proto) {
+       19 +      if (proto.name === 'BadRequestError') return true;
+       20 +      proto = Object.getPrototypeOf(proto);
+       21 +    }
+       22
+       23 -    return (
+       24 -      isInstanceOfBadRequestError ||
+       25 -      isNamedAfterBadRequestError ||
+       26 -      isExtensionOfBadRequestError
+       27 -    );
+       23 +    return false;
+       24    };
+       25
+       26    /**
+
+● Done. Now the function uses early returns, so it short-circuits as soon as any check passes without needing
+  to evaluate the remaining checks.
+
+> header comment on the last return, too
+  ⎿  Found 3 new diagnostic issues in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 1 addition
+       20        proto = Object.getPrototypeOf(proto);
+       21      }
+       22
+       23 +    // otherwise, not a bad request error
+       24      return false;
+       25    };
+       26
+
+● Done.
+
+> keep the names of the constants though; if (isXyz) is important for greater readability
+  ⎿  Found 3 new diagnostic issues in 1 file (ctrl+o to expand)
+
+● Update(src/logic/middlewares/badRequestErrorMiddleware.ts)
+  ⎿  Updated src/logic/middlewares/badRequestErrorMiddleware.ts with 14 additions and 7 removals
+        8     */
+        9    export const decideIsBadRequestError = ({ error }: { error: Error }) => {
+       10      // check if the error is an instance of BadRequestError
+       11 -    if (error instanceof BadRequestError) return true;
+       11 +    const isInstanceOfBadRequestError = error instanceof BadRequestError;
+       12 +    if (isInstanceOfBadRequestError) return true;
+       13
+       14      // check if the error's constructor is named 'BadRequestError'
+       15 -    if (error.constructor.name === 'BadRequestError') return true;
+       15 +    const isNamedAfterBadRequestError =
+       16 +      error.constructor.name === 'BadRequestError';
+       17 +    if (isNamedAfterBadRequestError) return true;
+       18
+       19      // check if any parent class in the prototype chain is named 'BadRequestError'
+       20 -    let proto = Object.getPrototypeOf(error.constructor);
+       21 -    while (proto) {
+       22 -      if (proto.name === 'BadRequestError') return true;
+       23 -      proto = Object.getPrototypeOf(proto);
+       24 -    }
+       20 +    const isExtensionOfBadRequestError = (() => {
+       21 +      let proto = Object.getPrototypeOf(error.constructor);
+       22 +      while (proto) {
+       23 +        if (proto.name === 'BadRequestError') return true;
+       24 +        proto = Object.getPrototypeOf(proto);
+       25 +      }
+       26 +      return false;
+       27 +    })();
+       28 +    if (isExtensionOfBadRequestError) return true;
+       29
+       30      // otherwise, not a bad request error
+       31      return false;
+
+● Done. Now each check has a named constant (isInstanceOfBadRequestError, isNamedAfterBadRequestError,
+  isExtensionOfBadRequestError) followed by an early return, giving both readability and short-circuit
+  evaluation.

package/dist/logic/roles/mechanic/.briefs/patterns/code.prod.repo.structure/bad-practices/forbid.index.ts.md

@@ -0,0 +1,3 @@
+the _only_ time an index.ts file is acceptable is if its
+1. the entrypoint of the public package, if this is a public package
+2. the entrypoint of a dao, if it is a dao

package/dist/logic/roles/mechanic/.briefs/patterns/code.test.howto/best-practice/howto.diagnose.[lesson].md

@@ -0,0 +1,14 @@
+if you have a failing test
+
+1. make the error super clear via
+   1. observable error messages
+   2. clear log trails
+
+2. when you detect which subcomponent has unexpected behavior
+   1. cover that subscomponent with tests of its own (unit, integration, etc)
+   2. if it does not have its own procedure, breakit out into its own procedure (own function + own file + own test suite)
+
+that way
+1. its easy to see exactly what is failing
+2. its easy to prove we fixed it (or verify that the behavior is / isnt expected)
+3. we can systematically track down the bug, one subcomponnent at a time

package/dist/logic/roles/mechanic/.briefs/patterns/lang.terms/best-practice/require.order.noun_adj.md

@@ -0,0 +1,39 @@
+ always use [noun][adjective] order
+
+ e.g.,
+
+ instead of
+
+ currentOwner = [adj][noun]
+
+ prefer
+
+ ownerCurrent = [noun][adj]
+
+
+---
+
+instead of
+
+
+foundUser
+
+prefer
+
+userFound
+
+----
+
+
+why?
+
+because it enables autocomplete via common prefixes
+
+e.g.,
+
+userBefore
+userAfter
+userCreated
+etc
+
+can see via autocomplete suggestions all the variants of user available in the current scope, rather than need to remember what the variants are

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"

package/dist/logic/roles/mechanic/.skills/init.claude.permissions.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = bind mechanic permissions to Claude settings
+#
+# .why  = the mechanic role needs conservative permissions to operate
+#         safely while still being productive.
+#
+#         this script manages permissions in .claude/settings.local.json:
+#           • replaces existing allows entirely (conservative)
+#           • extends denies by appending new entries (conservative)
+#           • extends asks by appending new entries (conservative)
+#           • idempotent: safe to rerun
+#
+# .how  = uses jq to merge the permissions configuration
+#         into the existing settings structure, creating it if absent.
+#
+# guarantee:
+#   ✔ creates .claude/settings.local.json if missing
+#   ✔ preserves existing settings (hooks, other configs)
+#   ✔ replaces allow list entirely
+#   ✔ appends to deny list (no duplicates)
+#   ✔ appends to ask list (no duplicates)
+#   ✔ idempotent: safe to rerun
+#   ✔ fail-fast on errors
+######################################################################
+
+set -euo pipefail
+
+PROJECT_ROOT="$PWD"
+SETTINGS_FILE="$PROJECT_ROOT/.claude/settings.local.json"
+
+# define the permissions configuration to apply
+PERMISSIONS_CONFIG=$(cat <<'EOF'
+{
+  "permissions": {
+    "deny": [
+      "Bash(git commit:*)"
+    ],
+    "ask": [
+      "Bash(chmod:*)",
+      "Bash(pnpm install:*)",
+      "Bash(pnpm add:*)"
+    ],
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:hub.docker.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(THOROUGH=true npm run test:*)",
+      "Bash(AWS_PROFILE=ahbode.dev npm run test:integration:*)",
+      "Bash(npm run fix:*)",
+      "Bash(AWS_PROFILE=ahbode.dev npx jest:*)",
+      "Bash(AWS_PROFILE=ahbode.dev npm run deploy:dev:*)",
+      "Bash(AWS_PROFILE=ahbode.dev STAGE=dev npm run test:acceptance:*)",
+      "Bash(npm run start:testdb:*)",
+      "Bash(cat:*)",
+      "Bash(unzip:*)",
+      "Bash(npm view:*)"
+    ]
+  }
+}
+EOF
+)
+
+# 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
+
+# apply permissions:
+# - replace allow entirely
+# - append to deny (unique)
+# - append to ask (unique)
+jq --argjson perms "$PERMISSIONS_CONFIG" '
+  # ensure .permissions exists
+  .permissions //= {} |
+
+  # replace allow entirely with our config
+  .permissions.allow = $perms.permissions.allow |
+
+  # append to deny (unique entries only)
+  .permissions.deny = ((.permissions.deny // []) + $perms.permissions.deny | unique) |
+
+  # append to ask (unique entries only)
+  .permissions.ask = ((.permissions.ask // []) + $perms.permissions.ask | unique)
+' "$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 "👌 mechanic permissions already configured"
+  echo "   $SETTINGS_FILE"
+  exit 0
+fi
+
+# atomic replace
+mv "$SETTINGS_FILE.tmp" "$SETTINGS_FILE"
+
+echo "🔐 mechanic permissions configured successfully!"
+echo "   $SETTINGS_FILE"
+echo ""
+echo "✨ permissions applied:"
+echo "   • allow: replaced entirely"
+echo "   • deny: extended (no duplicates)"
+echo "   • ask: extended (no duplicates)"

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

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = initialize Claude settings for mechanic role
+#
+# .why  = mechanic needs both hooks and permissions configured to
+#         operate effectively. this script dispatches to both:
+#           • init.claude.hooks.sh - binds SessionStart hook
+#           • init.claude.permissions.sh - configures permissions
+#
+#         single entry point for full Claude configuration.
+#
+# .how  = runs both init scripts in sequence from the same directory.
+#
+# guarantee:
+#   ✔ runs both hooks and permissions initialization
+#   ✔ fail-fast on any error
+#   ✔ idempotent: safe to rerun
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "🔧 init claude config for mechanic role..."
+echo ""
+
+# initialize hooks
+"$SCRIPT_DIR/init.claude.hooks.sh"
+echo ""
+
+# initialize permissions
+"$SCRIPT_DIR/init.claude.permissions.sh"
+echo ""
+
+echo "👌 claude config ready"

package/dist/logic/roles/mechanic/.skills/run.test.sh

@@ -226,8 +226,14 @@ fi
 echo "> $TEST_COMMAND" | tee -a "$LOG_FILE"
 echo "" | tee -a "$LOG_FILE"
 
-eval "$TEST_COMMAND" 2>&1 | tee -a "$LOG_FILE"
-TEST_EXIT_CODE=${PIPESTATUS[0]}
+# For unit tests, strip color codes from log file while preserving them in terminal output
+if [[ "$TEST_TYPE" == "unit" ]]; then
+  eval "$TEST_COMMAND" 2>&1 | tee >(sed 's/\x1B\[[0-9;]*[JKmsu]//g' >> "$LOG_FILE")
+  TEST_EXIT_CODE=${PIPESTATUS[0]}
+else
+  eval "$TEST_COMMAND" 2>&1 | tee -a "$LOG_FILE"
+  TEST_EXIT_CODE=${PIPESTATUS[0]}
+fi
 
 echo "" | tee -a "$LOG_FILE"
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "rhachet-roles-ehmpathy",
   "author": "ehmpathy",
   "description": "empathetic software construction roles and skills, via rhachet",
-  "version": "1.9.1",
+  "version": "1.10.0",
   "repository": "ehmpathy/rhachet-roles-ehmpathy",
   "homepage": "https://github.com/ehmpathy/rhachet-roles-ehmpathy",
   "keywords": [
@@ -26,7 +26,7 @@
     "fix:lint": "eslint -c ./.eslintrc.js src/**/*.ts --fix",
     "build:clean": "rm dist/ -rf",
     "build:compile": "tsc -p ./tsconfig.build.json",
-    "build:complete": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --include='**/*.template.md' --include='**/.briefs/**/*.md' --include='**/.briefs/*.md' --include='**/.skills/**/*.sh' --include='**/.skills/*.sh' --exclude='*' src/ dist/",
+    "build:complete": "rsync -a --prune-empty-dirs --include='*/' --exclude='**/.route/**' --exclude='**/.scratch/**' --exclude='**/.behavior/**' --include='**/*.template.md' --include='**/.briefs/**/*.md' --include='**/.briefs/*.md' --include='**/.skills/**/*.sh' --include='**/.skills/*.sh' --exclude='*' src/ dist/",
     "build": "npm run build:clean && npm run build:compile && npm run build:complete",
     "test:commits": "LAST_TAG=$(git describe --tags --abbrev=0 @^ 2> /dev/null || git rev-list --max-parents=0 HEAD) && npx commitlint --from $LAST_TAG --to HEAD --verbose",
     "test:types": "tsc -p ./tsconfig.build.json --noEmit",