rhachet-roles-ehmpathy 1.9.1 → 1.11.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/git.worktree.common.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = shared helpers for git worktree management
+#
+# .why  = centralizes path resolution and branch sanitization logic
+#         used by git.worktree.{get,set,del}.sh scripts
+#
+# .how  = source this file to get access to:
+#           - resolve_worktrees_dir: computes $REPO_WORKTREES_DIR
+#           - sanitize_branch_name: converts branch to worktree name
+#           - get_repo_name: extracts repo name from gitroot
+#
+# guarantee:
+#   - works from root repo or from within a worktree
+#   - consistent path resolution across all worktree scripts
+######################################################################
+
+# resolve the worktrees directory for this repo
+# handles both root repo and worktree contexts
+resolve_worktrees_dir() {
+  local gitroot
+  gitroot="$(git rev-parse --show-toplevel)"
+
+  local reponame
+  reponame="$(basename "$gitroot")"
+
+  # detect if we're in a worktree (path contains _worktrees)
+  if [[ "$gitroot" == *"_worktrees"* ]]; then
+    # we're in a worktree - reuse same _worktrees/$reponame dir
+    echo "${gitroot%/*}"
+  else
+    # root repo - compute sibling _worktrees dir
+    echo "$(dirname "$gitroot")/_worktrees/$reponame"
+  fi
+}
+
+# sanitize branch name for use as directory name
+# vlad/practs => vlad.practs
+sanitize_branch_name() {
+  local branch="$1"
+  echo "${branch//\//.}"
+}
+
+# get the repo name (works from root repo or worktree)
+get_repo_name() {
+  local gitroot
+  gitroot="$(git rev-parse --show-toplevel)"
+
+  # detect if we're in a worktree (path contains _worktrees)
+  if [[ "$gitroot" == *"_worktrees"* ]]; then
+    # extract repo name from _worktrees/$reponame/$worktree path
+    # gitroot = /path/to/_worktrees/$reponame/$worktree
+    local worktrees_parent="${gitroot%/*}"  # /path/to/_worktrees/$reponame
+    basename "$worktrees_parent"
+  else
+    basename "$gitroot"
+  fi
+}

package/dist/logic/roles/mechanic/.skills/git.worktree.del.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+######################################################################
+# .what = remove a git worktree
+#
+# .why  = clean up worktrees no longer needed
+#
+# .how  = removes worktree at @gitroot/../_worktrees/$reponame/$branch
+#
+# usage:
+#   git.worktree.del.sh <branch>
+#
+# guarantee:
+#   - idempotent: [DELETE] if exists, [SKIP] if not found
+#   - works from root repo or from within a worktree
+######################################################################
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# source shared helpers
+source "$SCRIPT_DIR/git.worktree.common.sh"
+
+# parse arguments
+BRANCH="${1:-}"
+
+# validate branch argument
+if [[ -z "$BRANCH" ]]; then
+  echo "error: branch name required"
+  echo "usage: git.worktree.del.sh <branch>"
+  exit 1
+fi
+
+# resolve paths
+REPO_WORKTREES_DIR="$(resolve_worktrees_dir)"
+WORKTREE_NAME="$(sanitize_branch_name "$BRANCH")"
+WORKTREE_PATH="$REPO_WORKTREES_DIR/$WORKTREE_NAME"
+
+# delete logic
+if [[ -d "$WORKTREE_PATH" ]]; then
+  # remove worktree via git
+  git worktree remove "$WORKTREE_PATH" --force 2>/dev/null || {
+    # fallback: manual removal if git worktree remove fails
+    rm -rf "$WORKTREE_PATH"
+    git worktree prune
+  }
+
+  echo "[DELETE] $WORKTREE_NAME"
+else
+  echo "[SKIP] $WORKTREE_NAME (not found)"
+fi